From 586fa1df0857879ab7a5cf7e1a0eaf0a349a1685 Mon Sep 17 00:00:00 2001
From: FedG-code <federico.giovannini28@gmail.com>
Date: Wed, 1 Apr 2026 17:28:23 +0100
Subject: [PATCH 1/3] quick claude code reference docs

---
 CLAUDE.md     |  50 ++------
 css/CLAUDE.md | 129 +++++++++++++++++++
 js/CLAUDE.md  | 350 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 493 insertions(+), 36 deletions(-)
 create mode 100644 css/CLAUDE.md
 create mode 100644 js/CLAUDE.md
diff --git a/CLAUDE.md b/CLAUDE.md
index 96a3e3f..55f6c0d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,15 +11,18 @@ lost-satellite.html     - Lost Satellite Studios breakdown (1 project + screensh
 css/
   shared.css            - All shared styles (variables, nav, layout, components)
   project.css           - Project page-specific styles (hero, sections, gallery)
+  cards.css             - Card and hand container styles (base card 220x320, theme overrides)
 js/
   shared.js             - Scroll reveal + theme switcher with localStorage persistence
   destruction.js        - Text destruction system (plane mode shatter + sequential reform)
   card-hand.js          - Card hand system (fan layout, drag, proximity detection, play zone)
   page-transition.js    - Card play animation + SPA page transitions (fly clones, page fade-in)
-css/
-  cards.css             - Card and hand container styles (base card 220×320, theme overrides)
 ```
 
+## Detailed Documentation
+- **CSS** (themes, line ranges, selectors): See [css/CLAUDE.md](css/CLAUDE.md)
+- **JS** (functions, constants, APIs): See [js/CLAUDE.md](js/CLAUDE.md)
+
 ## Key Details
 - **Fonts**: Google Fonts `<link>` tags in every page's `<head>` load all theme fonts:
   - Bold: Archivo Black, Archivo, IBM Plex Mono
@@ -28,48 +31,23 @@ css/
   - Retro: Shrikhand, Bitter, IBM Plex Mono
   - Neon: Sora, Space Mono
   - Font CSS variables (`--font-serif`, `--font-body`, `--font-mono`) are redefined per theme in `shared.css`
-- **Theme system**: Five themes cycle via button: `bold → cinematic → brutalist → retro → neon → bold`
+- **Theme system**: Five themes cycle via button: `bold -> cinematic -> brutalist -> retro -> neon -> bold`
   - `data-theme` attribute on `<html>` controls the active theme (`bold` default)
   - Each theme defines its own CSS variable block in `shared.css` (`:root` for bold, `[data-theme="cinematic"]`, etc.)
   - Theme-specific overrides (hardcoded colours, border-radius, font weights, etc.) go in `[data-theme="<name>"]` selector blocks after the variable blocks
   - `js/shared.js` has `const themes = ['bold', 'cinematic', 'brutalist', 'retro', 'neon']` — the switcher button cycles through and persists to `localStorage`
   - **Persistence**: inline `<script>` in `<head>` of every page reads `localStorage.getItem('portfolio-theme')` and sets `data-theme` before CSS loads (prevents flash). Also migrates stored `coral`/`slate` values to `bold`.
-- **Theme design notes**:
-  - **bold** (default): Warm light theme. Archivo Black headings, Archivo body, IBM Plex Mono labels. Orange accent (#FF6123). Sharp corners (0px radius). Dark about section, orange contact section. Hero accent circle.
-  - **cinematic**: Dark tech-noir theme. Syne headings, system body, Commit Mono labels. Red accent (#D6001C). Scanline overlay in hero, red glow, film grain on body. Sharp corners.
-  - **brutalist**: Typographic grid theme. Space Mono headings, Literata body. Electric blue accent (#0038FF). Status bar below nav. 2-column hero grid, data-row about section. Heavy black borders (2px). Uses alternate HTML layouts (.hero-brutalist, .about-brutalist).
-  - **retro**: 1970s warm theme. Shrikhand headings, Bitter body, IBM Plex Mono labels. Red accent (#D94230) + mustard secondary (#E8A825). Split hero with teal panel. Deep teal about section. Rounded corners (10px). Uses .hero-panel HTML element.
-  - **neon**: Dark techy theme. Sora headings/body, Space Mono labels. Lime-green accent (`#c9f059`). Sharp corners (6-12px radius). Grain overlay on `body::before`. Grid pattern in hero `::before`. Doodles hidden.
+  - See [css/CLAUDE.md](css/CLAUDE.md) for per-theme design notes and line ranges.
 - **Nav**: Removed from all pages. Navigation is handled by the card-hand system only. Nav CSS is archived in `backup/nav-styles.css`.
 - **Alternate HTML layouts**:
-  - `.hero-default` / `.hero-brutalist` — dual-layout hero (brutalist has alternate grid)
-  - `.about-default` / `.about-brutalist` — dual-layout about (brutalist has data rows)
-  - `.hero-panel` — retro teal panel (right side of split hero)
+  - `.hero-default` / `.hero-brutalist` — dual-layout hero
+  - `.about-default` / `.about-brutalist` — dual-layout about
+  - `.hero-panel` — retro teal panel
   - `.status-bar` — brutalist status bar (hidden by default)
 - **Work cards**: `<a>` links in `index.html` that navigate to individual project pages; hover highlight effect (accent border + lift + shadow)
 - **JS features**: Scroll reveal (IntersectionObserver), theme switcher with localStorage
-- **Text Destruction** (`js/destruction.js`): "Plane mode" feature — a paper airplane projectile shatters text on collision, then characters reform.
-  - **Dependencies**: GSAP core, SplitText plugin, Physics2DPlugin (all loaded externally, no npm)
-  - **How it works**: `TextDestruction.init()` splits all destructible text elements (headings, paragraphs, labels, etc.) into word and char `<span>`s via `SplitText` (classes `destruct-word` and `destruct-char`). Word spans are `inline-block; white-space: nowrap` to prevent mid-word breaks. When plane mode is active, `onProjectileAt(x, y)` finds chars within `BLAST_RADIUS` and shatters them.
-  - **Scatter phase**: Chars fly away from impact using `physics2D` (velocity, angle, gravity) with a brief accent-colour flash, fading to `opacity: 0` over `SCATTER_DURATION` (1.2s).
-  - **Reform phase** (sequential typing drop-in): After a `REFORM_PAUSE` (1.0s), chars re-enter left-to-right in DOM reading order. Each char is pre-positioned 16px above its slot (`DROP_DISTANCE`), then drops into place with `power2.out` (no bounce) over `CHAR_LAND_DURATION` (0.12s). Consecutive chars are staggered by `CHAR_STAGGER` (0.055s) with an extra `WORD_EXTRA_STAGGER` (0.05s) pause at word boundaries (detected by `parentElement` change).
-  - **Lifecycle**: `TextDestruction.onThemeChange()` destroys and re-inits on theme switch. Resize is debounced to re-split text. A `charRectCache` (invalidated on scroll/resize) accelerates hit detection.
-  - **Selector list** (`DESTRUCTIBLE_SELECTOR`): targets headings, hero text, work cards, about section, chips, contact, project pages, footer, brutalist layout elements, retro panel elements — excludes theme switcher, buttons.
-  - **Mobile-gated constants**: `_isMob` (viewport ≤768 OR touch+coarse) gates performance-sensitive values. Desktop is completely unchanged. Mobile overrides: `MAX_SHATTERED` 100 (vs 300), `REFORM_PAUSE` 1.0s (vs 0.8s), `CHAR_STAGGER` 0.035s (vs 0.055s), `WORD_EXTRA_STAGGER` 0.03s (vs 0.05s), `MAX_VELOCITY` 350 (vs 500), `MAX_ROTATION` 360° (vs 720°). Color flash tween is skipped on mobile. Impact coalescing on mobile batches same-frame `onProjectileAt()` calls via RAF.
-  - **Impact throttle**: `IMPACT_THROTTLE` in `plane.js` is 80ms on mobile, 0ms on desktop. The scroll speed gate (`SCROLL_SPEED_THRESHOLD`) was removed — it unnecessarily limited desktop destruction.
-  - **Design fallback**: If optimisation doesn't resolve plane mode scroll+fire lag, the fallback is to **disable page scrolling while plane mode is active** (e.g. CSS `overflow: hidden` on `<html>` when `.plane-active`). This eliminates scroll-triggered cache invalidation and the compound scroll+destruction cost entirely.
-- **Card-hand system** (`js/card-hand.js`, `js/page-transition.js`, `css/cards.css`): Cards are held in a fan layout at the bottom of the viewport. Dragging a card into the play zone triggers a page transition.
-  - **Card constants**: `CARD_W` = 220, `CARD_H` = 320, `HAND_W` = 700, `PLAY_ZONE_HALF_W` = 385, `PLAY_ZONE_HALF_H` = 289
-  - **Play animation phases**: center (0.5s) → wriggle (1.0s, increasing amplitude) → expand to fill viewport (0.5s) → decompose card elements → fly title/art clones to target page positions → page fade-in → rebuild hand
-  - **Expand scaling**: Uses `Math.min(vw / CARD_W, vh / CARD_H)` ("contain" behavior) so the card never exceeds viewport bounds. No `devicePixelRatio` multiplication needed — `window.innerWidth`/`innerHeight` return CSS pixels, which is what GSAP operates in.
-  - **Proximity effects**: As a dragged card approaches the viewport center, a blur overlay and card glow intensify. Calculated via distance from card center to viewport center.
-  - **SPA navigation**: `page-transition.js` fetches project pages via `fetch()`, caches them, and injects content into `#pageContainer` without full page reload. Title and art elements fly from the expanded card position to their target positions on the new page.
-  - **Title matching convention**: Card titles (in `card-hand.js` CARDS array) must match the project page `<h1 class="project-hero-title">` text exactly. Descriptive subtitles (e.g. "Casino Games", "Eve of Destruction") go in `.project-hero-badge`. Project title font styling (italic, weight, line-height) matches card title styling so the flying clone transition is seamless.
-  - **`.reveal` vs card handoff**: Any element that a fly clone hands off to must have `.reveal` removed from itself **and all `.reveal` ancestors** before the wrapper fades in. Otherwise the clone disappears but the real element is still `opacity: 0` (waiting for IntersectionObserver → `.visible`), causing a visible gap. This is done in `transitionToProject()` after measuring targets — currently handled for `.project-hero-title` and the first `.work-image`'s parent. **When adding new fly targets** (e.g. a second image, a badge, etc.), find the target element, call `el.closest('.reveal')`, and remove the class before the fly timeline starts.
-  - **Known issue — clone fly alignment**: The card title is `text-align: center` but the project page title is left-aligned. During the fly animation, the clone inherits center alignment from the card. For shorter titles (e.g. "Coffin-Likker"), the text visibly snaps from center to left when the clone is swapped for the real title. Longer titles (e.g. "Lost Satellite Studios") mask this. Fix options: left-align the clone and offset its start position, center the page title, or left-align the card title.
-  - **Char-fly landing bugs (resolved)**: Two issues caused the flying chars to land at the wrong position:
-    1. **Home page: `.measuring` removed too early** — `transitionToHome()` removed `.measuring` from `#page-home` before calling `fly()`. Without `.measuring`, the page reverted to `.spa-page { display:none }`, so all `getBoundingClientRect()` calls in `measureDirect()` returned zeros. Fix: remove `.measuring` after `fly()`, matching `transitionToProject()`.
-    2. **All pages: inline vs inline-block glyph offset + line-height mismatch** — `measureDirect()` measures inline `<span>` chars whose `getBoundingClientRect()` returns glyph bounds (ascenders extend above the line box). Flying chars are `display:inline-block` where the box top IS the positioned coordinate. Additionally, flying chars had hardcoded `line-height:1` but project titles use `line-height:1.2`. Fix in `text-rearrange.js`: (a) y-correction shifts target positions by `elRect.top - minCharY` so inline-block boxes align with the element box, (b) line-height is captured per-char and interpolated from source to target during the animation.
+- **Text Destruction**: See [js/CLAUDE.md](js/CLAUDE.md) for detailed destruction.js documentation (mechanics, constants, mobile-gated values, impact throttle, design fallback).
+- **Card-hand system**: See [js/CLAUDE.md](js/CLAUDE.md) for card-hand.js and page-transition.js documentation (play animation phases, SPA navigation, title matching, .reveal vs card handoff, known issues).
 - **Project pages**: Shared template - theme switcher, back link, project hero, repeatable sub-project sections, footer
 
 ## Serving Locally
@@ -130,7 +108,7 @@ Seven scenarios:
 - **scatter_spike**: Single impact on dense text (#about). Isolates the 1.2s physics2D scatter window. Thresholds: maxFrameMs > 40, p95 > 30, avg > 22.
 - **cache_rebuild**: Forces `cacheStale = true` then impacts to trigger `rebuildCharCache()`. Measures the `getBoundingClientRect()` loop cost. Threshold: maxFrameMs > 50.
 - **dense_burst**: 6 rapid-fire impacts at 100ms intervals across #about. Measures overlapping physics2D tweens. Thresholds: p95 > 35, droppedFrames > 30%, ScriptDurationMs > 800.
-- **overlap_scatter_reform**: 3 staggered impacts on hero (h1 → hero-desc → tidbits) creating triple wave overlap (scatter + reform simultaneously). Thresholds: maxFrameMs > 50, p95 > 35.
+- **overlap_scatter_reform**: 3 staggered impacts on hero (h1 -> hero-desc -> tidbits) creating triple wave overlap (scatter + reform simultaneously). Thresholds: maxFrameMs > 50, p95 > 35.
 - **high_count_reform**: 8-10 impacts to shatter near MAX_SHATTERED chars, then measures the reform animation window. Thresholds: maxFrameMs > 60, p95 > 30.
 - **figure8_scroll_fire**: Simultaneous scrolling + destruction across the full page height (figure-8 Lissajous pattern). Tests scroll-triggered cache invalidation, overlapping scatter+reform across viewport changes, and compound scroll+destruction cost. Thresholds: maxFrameMs > 60, p95 > 35, avg > 25, droppedFrames > 40%.
 - **sustained_annihilation**: Destroys all text in #about every 0.3s for 6 cycles using a 60px impact grid. Measures overlapping scatter+reform waves at extreme frequency. Thresholds: overlap maxFrameMs > 70, p95 > 40, avg > 25, droppedFrames > 40%.
@@ -145,7 +123,7 @@ Verify that the expanded card stays within the viewport at multiple sizes. These
 3. Wait for the expand phase (~2s into the animation timeline)
 4. Check `document.documentElement.scrollWidth <= window.innerWidth` and `document.documentElement.scrollHeight <= window.innerHeight` — if either is false, the card overflows
 5. Take a screenshot at the expanded state for visual verification
-6. Repeat at different viewport sizes: 1920×1080 (desktop), 1024×768 (tablet), 375×812 (mobile portrait), 812×375 (mobile landscape)
+6. Repeat at different viewport sizes: 1920x1080 (desktop), 1024x768 (tablet), 375x812 (mobile portrait), 812x375 (mobile landscape)
 
 **Test script pattern** (to be implemented in `tests/card-bounds-test.js`):
 ```js
diff --git a/css/CLAUDE.md b/css/CLAUDE.md
new file mode 100644
index 0000000..a7a2443
--- /dev/null
+++ b/css/CLAUDE.md
@@ -0,0 +1,129 @@
+# CSS Reference Map
+
+Brief overview: 3 CSS files totaling ~3,900 lines. Five themes (bold, cinematic, brutalist, retro, neon). Pattern: base component styles followed by theme override blocks.
+
+## shared.css (2607 lines)
+
+### Section Map
+
+| Section | Lines | Key Details |
+|---------|-------|-------------|
+| Universal reset + :root variables | 1-26 | --bg, --bg-warm, --bg-card, --border, --border-hover, --text-primary, --text-secondary, --text-muted, --accent, --accent-soft, --accent-mid, --pop, --pop-soft, --cream, --accent-glow, --font-serif, --font-body, --font-mono, --ease-out, --ease-spring, --radius, --radius-sm |
+| [data-theme="neon"] variables | 28-47 | Dark grays, lime accent (#c9f059), blue pop (#59b8f0), Sora/Space Mono fonts |
+| Global transitions | 49-51 | body, .work-card, .approach-card transitions |
+| .theme-switcher | 53-74 | Fixed positioning, sizing, hover states |
+| PLANE ACTIVE | 76-81 | html.plane-active styles (user-select: none) |
+| PLANE TOGGLE | 83-127 | .plane-toggle button, attractor state, bounce animation |
+| Global html/body/links | 128-148 | Base typography, .container max-width 1140px |
+| HERO | 150-257 | .hero min-height 100vh, .hero-badge fadeUp, .hero h1 clamp(3rem-6.5rem), .hero-body grid, .hero-tidbits |
+| SECTIONS | 258-279 | section padding 7rem, .section-label, .section-heading |
+| WORK CARDS | 280-491 | .work-grid, .work-card, .work-card-header, .work-icon, .work-expand, .work-image-placeholder (warm/cool/fresh), .work-details, .work-stats |
+| ABOUT | 493-562 | .about-content grid (1.2fr 1fr), .about-prose, .about-box, .chip-grid |
+| APPROACH | 564-608 | .approach-cards grid, .approach-card |
+| CONTACT | 609-677 | .contact, .btn primary/secondary |
+| FOOTER | 678-689 | footer styles |
+| DOODLE DECORATION | 690-723 | .doodle positioning and animation |
+| ANIMATIONS | 724-748 | @keyframes: fadeUp, pulse, nudgeBounce |
+| 3D PLANE OVERLAY | 749-756 | #plane-canvas fixed overlay |
+| THEME LAYOUT TOGGLES | 757-765 | .status-bar, .hero-brutalist, .about-brutalist, .hero-panel display toggles |
+| NEON THEME OVERRIDES | 766-860 | Font weights 600-700, sharp corners, grain overlay, doodle hidden |
+| RESPONSIVE (general) | 861-895 | @media 900px, 768px, 600px breakpoints |
+| Destruction system | 873-881 | .destruct-char, .destruct-word rules |
+| BOLD THEME OVERRIDES | 897-1195 | Hero circle ::after, uppercase h1, work/approach/contact overrides |
+| CINEMATIC THEME OVERRIDES | 1197-1520 | Dark red accent #D6001C, Syne/Segoe UI/Commit Mono, uppercase h1 |
+| BRUTALIST THEME OVERRIDES | 1521-2205 | Blue accent #0038FF, Space Mono/Literata, single-screen flex, .hero-brutalist grid, .status-bar |
+| RETRO THEME OVERRIDES | 2207-2607 | Cream bg, red #D94230, teal #1A5C52, Shrikhand/Bitter, hero split grid, .hero-panel |
+
+### Custom Properties (defined in :root)
+
+All variables defined in lines 3-26:
+
+- `--bg`, `--bg-warm`, `--bg-card` -- background colors
+- `--border`, `--border-hover` -- border colors
+- `--text-primary`, `--text-secondary`, `--text-muted` -- text colors
+- `--accent`, `--accent-soft`, `--accent-mid`, `--accent-glow` -- accent color + opacity variants
+- `--pop`, `--pop-soft` -- pop color (same as accent in bold theme)
+- `--cream` -- cream background
+- `--font-serif`, `--font-body`, `--font-mono` -- font stacks
+- `--ease-out`, `--ease-spring` -- easing functions
+- `--radius`, `--radius-sm` -- border-radius values
+
+### Alternate Layout Selectors
+
+- `.hero-default` (display: block) / `.hero-brutalist` (display: none by default, shown in brutalist)
+- `.about-default` / `.about-brutalist` (same pattern)
+- `.hero-panel` (display: none, shown in retro)
+- `.status-bar` (display: none, shown in brutalist)
+
+### Responsive Breakpoints
+
+- max-width: 900px -- hero-body 1fr, about-content 1fr
+- max-width: 768px -- plane-toggle adjustments
+- max-width: 600px -- overflow-x: hidden
+
+## cards.css (864 lines)
+
+### Section Map
+
+| Section | Lines | Key Details |
+|---------|-------|-------------|
+| SPA PAGE SYSTEM | 1-18 | .spa-page display states (active, measuring, transitioning), z-index 200 |
+| PAGE CONTAINER | 20-28 | .page-container absolute, inset 0, z-index 5, overflow-y auto, padding-bottom 220px |
+| DRAG BLUR OVERLAY | 30-40 | .drag-blur-overlay fixed, backdrop-filter blur(0px), will-change |
+| HAND CONTAINER | 42-59 | .hand-container bottom 0, translateX(-50%), height 400px (768px+: 260px), max-width 700px |
+| PERSPECTIVE + FLY | 61-74 | .perspective-container, .fly-overlay fixed, z-index 60/500 |
+| CARD BASE | 76-105 | .card 220x320px (768px+: 132x192), cursor grab, transition 0.55s cubic-bezier |
+| CARD INNER | 107-246 | .card-inner radius 14px, .card-title h3, .card-art height 155px, .card-art-icon, .card-inner--home, .type-bar, .card-textbox, .accent-strip |
+| MOBILE CARD SCALING | 248-261 | @media 768px: radius 9px, font-sizes reduced |
+| NEON OVERRIDES | 263-342 | Dark card bg #131318, lime accent glow |
+| TOUCH SUPPORT | 344-356 | html.card-dragging overflow hidden |
+| BOLD OVERRIDES | 358-475 | White/opaque, uppercase, orange accent, no accent-strip |
+| CINEMATIC OVERRIDES | 476-594 | Dark #161616, red accent, 800 weight |
+| BRUTALIST OVERRIDES | 596-713 | White/monospace, blue accent, 2px borders, hand positioning overrides |
+| RETRO OVERRIDES | 714-864 | Rounded 10px, red top line, Shrikhand, decorative elements, hardcoded hex palette |
+
+### Card Dimensions
+
+- Desktop: 220px x 320px
+- Mobile (<=768px): 132px x 192px
+
+## project.css (412 lines)
+
+### Section Map
+
+| Section | Lines | Key Details |
+|---------|-------|-------------|
+| PROJECT NAV | 1-19 | .project-nav flex, .project-nav-link font-mono 0.75rem |
+| PROJECT HERO | 21-62 | .project-hero padding 2rem 0 4rem, .project-hero-badge, .project-hero-title clamp(2.5rem-4.5rem), .project-meta |
+| PROJECT SECTIONS | 64-96 | .project-section, .project-content grid (1.2fr 1fr), --reversed variant |
+| IMAGES | 98-122 | .work-image-placeholder aspect-ratio 16/10 (warm/cool/fresh), .work-image |
+| STATS | 124-152 | .work-stats flex, .work-stat-num font-mono accent |
+| SCREENSHOT GALLERY | 154-169 | .screenshot-gallery flex, .screenshot-thumb 120px |
+| VIDEO EMBED | 170-190 | .video-embed-wrapper aspect-ratio 16/9 |
+| WIP BADGE | 191-205 | .wip-badge yellow/orange #FFC107 |
+| PROJECT LINK | 207-211 | .project-link accent color |
+| PORTRAIT DUO | 213-225 | .project-images-duo flex |
+| NEON OVERRIDES | 227-235 | 600 weight, 6-8px radius, dark radial-gradient placeholders |
+| RESPONSIVE | 237-250 | @media 900px (1fr grid), 480px (image sizing) |
+| BOLD OVERRIDES | 251-291 | Uppercase, 0 radius, linear-gradient placeholders |
+| CINEMATIC OVERRIDES | 292-330 | 700 weight uppercase, dark radial-gradient placeholders |
+| BRUTALIST OVERRIDES | 331-369 | Monospace, 2px border badge, solid color placeholders |
+| RETRO OVERRIDES | 370-412 | Shrikhand, 2px border badge, cream/teal/olive gradients |
+
+### Responsive Breakpoints
+
+- 900px -- grid to 1fr
+- 480px -- mobile image sizing
+
+## Cross-File Notes
+
+- All files use the same CSS custom property names from :root
+- Theme override pattern: `[data-theme="X"]` blocks redefine variables AND add theme-specific component styles
+- Brutalist is the most complex theme (~685 lines in shared.css) due to alternate hero/about HTML layouts
+- Image placeholder gradients vary by theme (linear, radial, or solid)
+- Card dimensions defined in both cards.css (CSS) and card-hand.js (JS constants CARD_W/CARD_H) -- keep in sync
+
+## Uncertainties
+
+- Lines 442-444 in shared.css have `[data-theme="slate"]` rules -- appears unused/legacy (slate was renamed to bold)
+- NEON section boundaries (lines 849-860) have image/icon tweaks that could be grouped with responsive or with neon overrides -- boundary is ambiguous
diff --git a/js/CLAUDE.md b/js/CLAUDE.md
new file mode 100644
index 0000000..faf5b95
--- /dev/null
+++ b/js/CLAUDE.md
@@ -0,0 +1,350 @@
+# JS Reference Map
+
+Overview: 6 JS files (~3,100 lines). No build step, no modules — all globals. GSAP + Three.js loaded from CDN. Files communicate via `window.*` hooks.
+
+## Dependency Graph
+
+```
+shared.js (theme switcher)
+  ├─ fires → TextDestruction.onThemeChange()
+  ├─ fires → window._planeOnThemeChange()
+  └─ fires → window._cardHandOnThemeChange()
+
+plane.js (3D canvas + projectiles)
+  └─ calls → TextDestruction.onProjectileAt()
+
+card-hand.js ←→ page-transition.js (shared state: CARDS, cardOrder, activePageCardId, dragState, animState)
+  └─ page-transition.js uses → TextRearrange.fly()
+
+External: GSAP core, SplitText, Physics2DPlugin, Three.js r128, GLTFLoader
+```
+
+---
+
+## shared.js (37 lines)
+
+### Complete Reference
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Scroll reveal (IntersectionObserver) | 1-11 | threshold 0.1, rootMargin '0px 0px -40px 0px', staggered 60ms delay, unobserves after visible |
+| Theme switcher setup | 14-17 | themes = ['bold','cinematic','brutalist','retro','neon'], reads data-theme attr |
+| updateLabel() | 21-25 | Shows NEXT theme name on button |
+| Click handler | 27-35 | Cycles index, sets data-theme, persists to localStorage('portfolio-theme'), fires 3 callbacks |
+
+### Global Exports
+- `window.revealObserver` (line 10) — IntersectionObserver instance
+
+### Theme Change Hooks Fired (in order)
+1. `window.TextDestruction.onThemeChange()` (line 32)
+2. `window._planeOnThemeChange()` (line 33)
+3. `window._cardHandOnThemeChange()` (line 34)
+
+These are called without null checks — would throw if undefined and script loads before the others.
+
+---
+
+## destruction.js (545 lines)
+
+### Section Map
+| Section | Lines | Notes |
+|---------|-------|-------|
+| GSAP registration | 1-7 | Registers SplitText + Physics2DPlugin |
+| Mobile detection | 9-11 | `_isMob`: viewport ≤768px OR coarse pointer |
+| Constants (mobile-gated) | 13-26 | 14 constants with mobile overrides |
+| DESTRUCTIBLE_SELECTOR | 28-48 | 28 CSS selectors targeting destructible text |
+| splitAllText() | 56-81 | SplitText.create() per element, caches parent color |
+| revertAllText() | 83-89 | Clears splits/char arrays |
+| revertElement() | 91-104 | Single element revert |
+| preloadSplit() | 106-110 | Desktop-only pre-split on fonts ready |
+| CharRect cache + rebuild | 112-217 | Async chunking on mobile, eager warm-up, scroll/viewport checks |
+| getCharsInBlastRadius() | 219-250 | Distance-based hit detection using cache |
+| Impact coalescing (mobile) | 255-265 | Batches same-frame hits via RAF |
+| shatterChars() | 276-358 | Physics2D scatter (desktop) or eased motion (mobile), color flash desktop-only |
+| scheduleTypingReform() | 360-454 | Staggered reform with word-boundary pauses, chunked cleanup on mobile |
+| Resize debounce | 456-467 | 300ms debounce, re-splits + stale cache |
+| Public API (window.TextDestruction) | 469-538 | init(), destroy(), onProjectileAt(), onThemeChange(), revertElement() |
+| Auto-run preload | 540-545 | Delays until fonts ready or 100ms |
+
+### Constants Table
+| Name | Desktop | Mobile | Description |
+|------|---------|--------|-------------|
+| BLAST_RADIUS | 40 | 40 | Impact radius (px) |
+| MAX_SHATTERED | 300 | 100 | Max concurrent shattered chars |
+| SCATTER_DURATION | 1.2 | 1.2 | Scatter time (s) |
+| REFORM_PAUSE | 0.8 | 1.0 | Pause before reform (s) |
+| CHAR_LAND_DURATION | 0.12 | 0.12 | Drop-in time per char (s) |
+| CHAR_STAGGER | 0.055 | 0.035 | Delay between char reforms (s) |
+| WORD_EXTRA_STAGGER | 0.05 | 0.03 | Extra pause at word boundary (s) |
+| DROP_DISTANCE | 16 | 16 | Pre-position offset above slot (px) |
+| GRAVITY | 600 | 600 | Physics gravity (desktop only) |
+| MIN_VELOCITY | 150 | 150 | Scatter velocity floor (px/s) |
+| MAX_VELOCITY | 500 | 350 | Scatter velocity ceiling (px/s) |
+| ANGLE_SPREAD | 60 | 60 | Scatter angle variance (deg) |
+| MAX_ROTATION | 720 | 360 | Max rotation scatter (deg) |
+| CACHE_CHUNK_SIZE | 200 | 200 | Chars per RAF frame during async rebuild |
+
+### Global API
+```
+window.TextDestruction = {
+  init()                    // Arm + split all text
+  destroy()                 // Disarm + kill tweens (does NOT revert split)
+  onProjectileAt(sx, sy)    // Hit detection entry (coalesced on mobile)
+  onThemeChange()           // Kill tweens, revert/re-split, re-read accent
+  revertElement(el)         // Revert single element split
+}
+```
+
+### Key Mechanisms
+- **CharRect cache** (L112-217): Stores {el, cx, cy} per visible char. Rebuilt sync (desktop) or async-chunked (mobile). Scroll delta adjustment in getCharsInBlastRadius().
+- **Impact coalescing** (L255-265, mobile only): pendingHits[] batched per RAF frame.
+- **Shatter**: Desktop uses physics2D (gravity+rotation); mobile uses pre-computed eased motion.
+- **Reform**: Left-to-right DOM order, staggered CHAR_STAGGER with WORD_EXTRA_STAGGER at word boundaries. Cleanup chunked on mobile (40 chars/RAF).
+
+### Dependencies
+GSAP core, SplitText plugin, Physics2DPlugin (all CDN, no npm)
+
+---
+
+## plane.js (812 lines)
+
+### Section Map
+| Section | Lines | Notes |
+|---------|-------|-------|
+| IIFE & constants | 1-68 | 28 tuneables, mobile gating (MIN_VIEWPORT 768px) |
+| Mobile detection | 29-35 | isMobile() with _isMobileCached |
+| State variables | 37-80 | enabled, scene/camera/renderer, plane model, mouse/touch, projectiles[], fire interval |
+| Iframe avoidance | 82-125 | getAvoidanceTarget() keeps plane outside iframe buffered regions |
+| Toggle button UI | 127-214 | createToggleButton(), updateButtonLabel(), attractor bounce |
+| Toggle handler | 216-247 | SessionStorage persist, syncs TextDestruction.init/destroy, plane-active class |
+| start() / stop() | 249-271 | Control animation loop + canvas visibility |
+| Dynamic script loading | 273-298 | CDN Three.js r128 + GLTFLoader |
+| Coordinate conversion | 300-312 | screenToWorld(), worldToScreen() |
+| Mouse events (desktop) | 314-388 | onMouseMove/Leave/Enter, snapMouseIfTrappedInIframe() |
+| Touch events (mobile) | 390-437 | onTouchStart/Move/End with touch hit radius |
+| Mobile mouse fallback | 439-471 | DevTools emulation support |
+| Projectile system | 473-532 | Pool of 20 THREE.Line objects, fire from wing tips |
+| Animation loop | 534-669 | animate(): propeller spin, position lerp, scroll-on-drag, roll, projectile update, destruction trigger |
+| Resize handler | 671-682 | Camera frustum + renderer size update |
+| init() (Three.js) | 684-799 | Scene/camera/renderer, lighting, GLB load, event listeners |
+| Bootstrap | 801-812 | Disables on page reload, creates button, inits if enabled |
+
+### Key Constants
+| Name | Value | Mobile? | Description |
+|------|-------|---------|-------------|
+| MODEL_SCALE | 0.1 | x1.3 mobile | Plane GLB scale |
+| FRUSTUM_SIZE | 10 | no | Orthographic camera height |
+| PROJECTILE_SPEED | 8.0 | no | World units/s |
+| FIRE_INTERVAL | 0.12 | no | Rapid-fire delay (s) |
+| POOL_SIZE | 20 | no | Projectile pool |
+| IMPACT_THROTTLE | 0ms desktop / 120ms mobile | yes | Text destruction hit throttle |
+| TOUCH_HIT_RADIUS | 60 | no | Mobile touch target (px) |
+| LS_KEY | 'portfolio-plane' | — | SessionStorage key |
+| IFRAME_BUFFER | 50 | no | Avoidance margin (px) |
+
+### Global Exports
+- `window._planeOnThemeChange` (L723): Updates cachedAccentColor
+- `window._planeWorldToScreen` (L656): worldToScreen() alias
+
+### Three.js Setup
+- Orthographic camera, frustum height 10, looking down Y axis
+- WebGL renderer, antialias disabled on mobile, pixel ratio capped at 2.0
+- GLB from `assets/plane.glb`, finds FrontPropeller/TopPropeller children
+- Ambient light 0.8 + directional light 0.6
+
+### Projectile System
+- Pool of 20 pre-allocated THREE.Line objects (BufferGeometry, 6 floats each)
+- Fires 2 per trigger (left + right wing)
+- Progress 0-1, head travels at PROJECTILE_SPEED, tail at 70% (TAIL_SPEED_RATIO)
+- At head=1.0: triggers TextDestruction.onProjectileAt() (throttled on mobile)
+
+### Toggle Persistence
+- SessionStorage key 'portfolio-plane', cleared on page reload (L804-808)
+- Adds/removes `plane-active` class on documentElement
+
+---
+
+## text-rearrange.js (268 lines)
+
+### Section Map
+| Section | Lines | Notes |
+|---------|-------|-------|
+| IIFE wrapper | 14, 266-268 | `var TextRearrange = (function() { ... })()` |
+| quadBezier() | 23-29 | Quadratic bezier interpolation -> {x, y} |
+| measureDirect() | 37-80 | SplitText on element, extracts char rects + computed styles |
+| fly() | 94-263 | Main entry: measures source/target, builds bezier arc timeline |
+
+### Constants
+| Name | Value | Description |
+|------|-------|-------------|
+| CHAR_STAGGER | 0.05s | Delay between char launches |
+| CHAR_DURATION | 0.20s | Per-char fly time |
+| ARC_HEIGHT | 150px | Bezier arc offset |
+| DISCRETE_SWAP | 0.30 | Progress point for font-family/style/transform swap |
+
+### Functions
+| Function | Lines | Params | Returns | Description |
+|----------|-------|--------|---------|-------------|
+| quadBezier | 23-29 | t, p0x/y, p1x/y, p2x/y | {x,y} | Bezier point interpolation |
+| measureDirect | 37-80 | el, keepSplit | {positions[], sourceChars[], split, elRect, lineHeight} | Measures char positions + computed styles via SplitText |
+| fly | 94-263 | {sourceEl, targetEl, overlay, onStart?} | {timeline, lastLaunchTime, destroy(), charEls[]} or null | Builds GSAP timeline: chars fly along bezier arcs from source to target |
+
+### Y-Correction Logic (L121-138)
+**Problem**: SplitText on inline elements captures glyph bounds (ascenders extend above element box). Flying chars are inline-block where the box top IS the positioned coordinate.
+**Solution**: Shift all target Y positions by `elementTop - minCharY` to align inline-block boxes with glyph visual positions.
+
+### Line-Height Interpolation (L204-205, L230)
+Source and target line-heights extracted per-char, linearly interpolated during animation. Prevents vertical spacing jumps between card and page typography.
+
+### fly() Animation Flow
+1. **Validate** (L94-119): Check fonts loaded, measure source (keepSplit), measure target, validate char count (+/-2 tolerance)
+2. **Y-correct** (L121-138): Compute element-vs-glyph offset
+3. **Prepare chars** (L140-164): Reparent source chars to overlay as fixed-position elements, copy 9 computed style properties
+4. **Build timeline** (L166-250): Per-char bezier arc (alternating perpendicular offset), interpolate font-size/weight/letter-spacing/line-height linearly, swap font-family/style/text-transform at DISCRETE_SWAP, GSAP native color interpolation
+5. **Return** (L252-262): timeline, lastLaunchTime, destroy(), charEls[]
+
+### Dependencies
+GSAP core (timeline, to, set), SplitText (measureDirect)
+
+---
+
+## card-hand.js (546 lines)
+
+### Section Map
+| Section | Lines | Notes |
+|---------|-------|-------|
+| CARDS array | 0-40 | 4 card objects with id, accent, title, pageUrl, artImage, etc. |
+| Constants | 42-61 | Responsive dimensions (mobile vs desktop) |
+| State variables | 63-84 | dragState, animState, cardOrder, activePageCardId, etc. |
+| createCardHTML() + freezeGif() + buildCards() | 86-150 | DOM construction, GIF->PNG freeze |
+| Fan geometry | 152-175 | fanX(), fanAngle(), fanArcY(), getRestPosition() |
+| layoutCards() | 177-197 | Applies transforms to card elements |
+| Slot detection + proximity | 199-239 | getSlotForX(), getCardCenter(), calcProximity(), isInPlayZone() |
+| Proximity feedback | 242-280 | applyProximityFeedback(), resetProximityFeedback(), hexToRGB() |
+| Touch helpers | 282-319 | isPlaneActive(), findNearestCardInRange(), liftCard(), dismissLift() |
+| Drag handlers | 321-467 | onPointerDown(), onPointerMove(), onPointerUp() |
+| Hover handlers | 469-494 | pointerover/pointerout |
+| Event listeners | 496-528 | Pointer events, dragstart, scroll, theme callback |
+| Theme change callback | 530-540 | window._cardHandOnThemeChange |
+| Init | 542-546 | buildCards() + layoutCards() |
+
+### CARDS Array Structure (each object)
+```
+{ id, accent, title, typeLeft, typeRight, icon, text, pageUrl, artImage }
+```
+- id 0-2: project cards (have pageUrl + artImage)
+- id 3: Home card (pageUrl: null, artImage: null)
+
+### Key Constants
+| Name | Desktop | Mobile (<=768) | Description |
+|------|---------|----------------|-------------|
+| CARD_W | 220 | 132 | Card width (px) |
+| CARD_H | 320 | 192 | Card height (px) |
+| HAND_W | 700 | min(innerWidth, 400) | Hand container width |
+| HAND_H | 400 | 260 | Hand container height |
+| HOLD_RADIUS | 1400 | 900 | Fan arc radius |
+| FAN_SPREAD | 20 deg | 14 deg | Angular spread |
+| OVERLAP_SPACING | 155 | 90 | Horizontal card spacing |
+| SINK_BELOW | 190 | 130 | Vertical offset down |
+| HOVER_LIFT | 50 | 35 | Hover lift (px) |
+| PLAY_ZONE_HALF_W | ~385 | — | Play zone half-width |
+| PLAY_ZONE_HALF_H | ~289 | — | Play zone half-height |
+| MAX_BLUR | 8 | — | Max proximity blur (px) |
+| MAX_OVERLAY_OPACITY | 0.3 | — | Max overlay darkness |
+| MAX_GLOW_SIZE | 30 | — | Max card glow (px) |
+| PROXIMITY_DEAD_ZONE | 0.35 | — | Dead zone (35% distance) |
+
+### Fan Geometry
+- X: `(slot - (total-1)/2) * OVERLAP_SPACING`
+- Angle: `-FAN_SPREAD/2 + (FAN_SPREAD/(total-1)) * slot`
+- Y: `HOLD_RADIUS - HOLD_RADIUS * cos(angle_radians)`
+
+### DOM Structure Created
+```
+#handContainer (preserve-3d)
+  .card[data-card-id]
+    .card-inner[data-accent]
+      .card-title > h3
+      .card-art > .card-art-inner > (img.card-art-img OR .card-art-icon)
+      .type-bar
+      .card-textbox
+      .accent-strip
+```
+
+### Global Exports
+- `window._cardHandOnThemeChange` (L533-540): Clears inline proximity feedback styles
+- Shared variables (used by page-transition.js): CARDS, cardOrder, activePageCardId, dragState, animState, buildCards, getRestPosition, calcProximity, MAX_BLUR, MAX_OVERLAY_OPACITY, MAX_GLOW_SIZE, handContainer, dragBlurOverlay, perspectiveContainer, flyOverlay
+
+### Cross-File Dependencies
+- Calls `window.prefetchPage()` (from page-transition.js) on pointer down
+- Checks `isPlaneActive()` — reads `plane-active` CSS class (set by plane.js)
+
+---
+
+## page-transition.js (890 lines)
+
+### Section Map
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Timing constants | 0-6 | DECOMPOSE_DURATION=0.1s, FLY_DURATION=0.5s |
+| Fetch + cache | 8-31 | pageCache = {url: Promise<html>}, prefetchPage(), extractPageContent() |
+| SPA bootstrap | 50-136 | bootstrapFromProjectPage(): handles direct project page loads |
+| playCard() | 138-258 | 6-phase animation: center -> wriggle -> expand -> decompose -> pause -> transition |
+| beginPageTransition() | 260-356 | Measures title/art, reparents to flyOverlay, routes to home/project |
+| transitionToHome() | 358-501 | Flies elements to home hero, fades in home page |
+| transitionToProject() | 503-694 | Flies elements to project page, fades in wrapper |
+| Helpers | 696-722 | getTargetTypography(), applyArtCloneStyles() |
+| rebuildHand() | 725-765 | Rebuilds card hand after transition |
+| History + navigation | 767-889 | navigateToPage(), popstate handler, back/forward |
+
+### Timing Constants
+| Name | Value | Lines | Description |
+|------|-------|-------|-------------|
+| DECOMPOSE_DURATION | 0.1s | 5 | Decorative element fade-out |
+| FLY_DURATION | 0.5s | 6 | Title/art fly animation |
+| WRIGGLE_DURATION | 1.0s | 202 | Wriggle phase |
+| Page fade | 0.3-0.4s | various | Opacity transitions |
+
+### playCard() Animation Phases
+1. **Center** (0-500ms, L195-199): Card slides to viewport center, power3.out
+2. **Wriggle** (500-1500ms, L201-225): +/-8 deg rotation, +/-2.5px jitter, blur->16px, overlay->0.55, glow->70px
+3. **Expand** (1500-2000ms, L227-235): Scale to fill viewport `min(vw/CARD_W, vh/CARD_H)`, glow+blur->0
+4. **Decompose** (2000-2150ms, L237-249): Fade .type-bar, .card-textbox, .accent-strip, border
+5. **Pause** (2150-2350ms, L252): Empty delay
+6. **Transition** (2350ms+, L255-257): Calls beginPageTransition()
+
+### transitionToHome vs transitionToProject
+| Aspect | toHome (L358-501) | toProject (L503-694) |
+|--------|-------------------|----------------------|
+| Target | `#page-home` (hidden) | New `<div class="spa-page measuring">` |
+| Title target | `.hero h1` (theme-aware) | `.project-hero-title` |
+| Image target | None (art fades out) | First `.work-image` |
+| .reveal handling | Strips from title | Strips from title + image ancestor |
+| History | pushState -> index.html | pushState -> cardData.pageUrl |
+
+### Fly Clone System
+1. Measures card title/art at current scale (beginPageTransition L285-296)
+2. Reparents real elements to #flyOverlay with fixed positioning (L298-342)
+3. Uses TextRearrange.fly() for char-by-char animation (or fallback tween)
+4. After animation: destroy() clears overlay
+
+### .reveal Class Handling
+Elements with `.reveal` start at opacity:0 + translateY(24px). Must be stripped from fly targets before measuring, otherwise getBoundingClientRect returns wrong values. Re-observed after transition for elements without `.visible`.
+
+### pageCache Structure
+```
+{ [url: string]: Promise<string> }
+```
+Promises resolve to extracted HTML (nav/footer/canvas stripped by extractPageContent).
+
+### Global Exports
+- `window.prefetchPage(url)` (L31): Starts async fetch+cache
+
+### Cross-File Dependencies
+- Imports from card-hand.js: CARDS, calcProximity, MAX_BLUR, MAX_OVERLAY_OPACITY, MAX_GLOW_SIZE, cardOrder, activePageCardId, buildCards, getRestPosition, handContainer, dragBlurOverlay, perspectiveContainer, flyOverlay
+- Uses optional: window.TextDestruction, window.TextRearrange, window.revealObserver
+- Modifies: activePageCardId, cardOrder, dragState, animState
+
+### Uncertainties
+- extractPageContent() (L33-48) uses hardcoded selector list for removal — if page structure changes, content may be incorrectly stripped
+- TextRearrange.fly() failure is silently caught (L416-420)
+- popstate handler (L877-889) clears GSAP timeline on every navigation — may interrupt unrelated animations

From a428d6e9c2072deb03a1c8d85064e8e351d1872d Mon Sep 17 00:00:00 2001
From: FedG-code <federico.giovannini28@gmail.com>
Date: Wed, 1 Apr 2026 18:32:16 +0100
Subject: [PATCH 2/3] tests summarised

---
 CLAUDE.md       |   1 +
 tests/CLAUDE.md | 268 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 269 insertions(+)
 create mode 100644 tests/CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 55f6c0d..c307770 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,6 +22,7 @@ js/
 ## Detailed Documentation
 - **CSS** (themes, line ranges, selectors): See [css/CLAUDE.md](css/CLAUDE.md)
 - **JS** (functions, constants, APIs): See [js/CLAUDE.md](js/CLAUDE.md)
+- **Tests** (scenarios, thresholds, setup): See [tests/CLAUDE.md](tests/CLAUDE.md)
 
 ## Key Details
 - **Fonts**: Google Fonts `<link>` tags in every page's `<head>` load all theme fonts:
diff --git a/tests/CLAUDE.md b/tests/CLAUDE.md
new file mode 100644
index 0000000..5dd5d4f
--- /dev/null
+++ b/tests/CLAUDE.md
@@ -0,0 +1,268 @@
+# Tests Reference Map
+
+Overview: 10 Playwright test files (~4,000 lines). Two categories: performance benchmarks (2 files) and visual/interaction regression tests (8 files). All require `npx http-server -p 8080 -c-1` running locally. All use Chromium.
+
+## Running Tests
+
+All tests: `node tests/<filename>.js`
+Prerequisite: local server on port 8080.
+
+## Performance Tests
+
+### perf-test.js (412 lines)
+
+**Purpose**: Mobile frame timing under 4x CPU throttle across scroll + plane scenarios.
+
+**Setup**: Chromium headless, iPhone 14 (390x844, 3x DPR), 4x CPU throttle, dropped-frame threshold 20ms.
+
+#### Section Map
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Imports & constants | 0-35 | Viewport 390x844, 3x DPR, 4x CPU throttle, 20ms drop threshold |
+| Frame timing helpers | 39-82 | injectFrameCollector(), collectFrames(), computeFrameStats() -- RAF-based |
+| CDP metrics helpers | 84-109 | getCdpMetrics(), diffMetrics() -- LayoutCount, RecalcStyleCount, ScriptDuration |
+| programmaticScroll() | 113-137 | Ease-in-out scroll over 5000ms |
+| Reveal override | 141-148 | Forces .reveal opacity:1 |
+| waitForPageReady() | 152-169 | Navigates, waits for GSAP/TextDestruction/button |
+| activatePlaneMode() | 173-188 | Clicks toggle, waits for plane-active + canvas + GLB |
+| runScenario() | 192-207 | Wraps scenario with metric capture |
+| Scenario functions | 211-256 | 4 scenarios |
+| buildAnalysis() | 260-313 | Compares baseline vs plane overhead, identifies bottleneck |
+| main() | 317-412 | Browser launch, 2 phases (baseline then plane), JSON output |
+
+#### Scenarios
+| Scenario | Lines | Measures |
+|----------|-------|----------|
+| baseline_scroll | 211-216 | Scroll without plane -- frame baseline |
+| plane_idle_scroll | 218-223 | Scroll with plane active but not firing |
+| plane_firing_scroll | 225-248 | Sine-wave mouse + scroll -- triggers firing & auto-scroll |
+| post_scroll_reform | 250-256 | Mouse release + 3000ms idle for reform animations |
+
+**Output**: JSON to stdout with scenarios + analysis (baselineOk, planeOverheadMs, firingOverheadMs, worstOffender, likelyBottleneck).
+
+**Key thresholds** (in buildAnalysis): avgFrameMs > 25 = bad baseline.
+
+---
+
+### perf-test-destruction.js (1021 lines)
+
+**Purpose**: Isolates destruction.js frame spikes via direct `TextDestruction.onProjectileAt()` calls. Windowed measurement prevents broad averaging from hiding spikes.
+
+**Setup**: Same as perf-test.js (Chromium headless, iPhone 14, 4x CPU throttle).
+
+#### Section Map
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Imports & constants | 0-36 | Same viewport/throttle as perf-test.js |
+| Thresholds | 38-77 | Per-scenario metric limits |
+| Frame/CDP helpers | 82-124 | computeFrameStats() with droppedFramePct, getCdpMetrics(), diffMetrics() |
+| Reveal override + page ready | 126-158 | Reused from perf-test.js |
+| Marker-aware frame collector | 162-211 | injectMarkerFrameCollector(), stopFrameCollector(), sliceFramesByMarkers() |
+| Direct impact helper | 213-220 | directImpact(page, x, y) -- calls onProjectileAt directly |
+| Destruction stats helpers | 222-281 | getElementCenter(), getDestructionStats(), scrollToElement(), ensureDestructionArmed(), resetDestructionState() |
+| Scenario: scatter_spike | 283-334 | Single impact on #about |
+| Scenario: cache_rebuild | 336-383 | Stale cache via resize + impact |
+| Scenario: dense_burst | 385-480 | 6 impacts at 100ms intervals |
+| Scenario: overlap_scatter_reform | 482-551 | 3 staggered impacts on hero |
+| Scenario: high_count_reform | 553-620 | 8-10 impacts, reform observation |
+| Scenario: figure8_scroll_fire | 622-688 | Lissajous pattern + scroll |
+| Scenario: sustained_annihilation | 690-797 | 60+ grid points x 6 cycles |
+| buildAnalysis() | 799-936 | Checks all 7 vs thresholds |
+| main() | 938-1021 | 7 phases, JSON output |
+
+#### Scenarios & Thresholds
+| Scenario | Lines | Measures | Key Thresholds |
+|----------|-------|----------|----------------|
+| scatter_spike | 283-334 | Single impact scatter window | maxFrame <=40ms, p95 <=30ms, avg <=22ms |
+| cache_rebuild | 336-383 | rebuildCharCache() cost after resize | maxFrame <=50ms |
+| dense_burst | 385-480 | 6 rapid impacts, burst vs scatter phases | p95 <=35ms, dropped <=30%, Script <=800ms |
+| overlap_scatter_reform | 482-551 | Triple wave overlap (scatter+reform) | maxFrame <=50ms, p95 <=35ms |
+| high_count_reform | 553-620 | Reform at near MAX_SHATTERED chars | maxFrame <=60ms, p95 <=30ms |
+| figure8_scroll_fire | 622-688 | Scroll + destruction simultaneously | maxFrame <=60ms, p95 <=35ms, avg <=25ms, dropped <=40% |
+| sustained_annihilation | 690-797 | All text destroyed repeatedly | overlap: maxFrame <=70ms, p95 <=40ms, avg <=25ms, dropped <=40% |
+
+**Output**: JSON to stdout with scenarios (each with sub-windows) + analysis (flags array, flagCount, worstScenario).
+
+**Key technique**: Marker-based windowed measurement -- `window.__perfMark(name)` inserts named markers into RAF frame array, then `sliceFramesByMarkers()` extracts stats for specific time windows.
+
+---
+
+## Transition & Animation Tests
+
+### title-jump-diagnostic.js (257 lines)
+
+**Purpose**: Detects vertical position jumps in `.project-hero-title` after card-to-page fly-in.
+
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Constants | 0-15 | JUMP_THRESHOLD=2px, default card id=1 |
+| measureAllHeroElements() | 16-74 | BBox on clone + title/badge/desc/meta |
+| Browser setup | 76-91 | Headless:false, 1280x800 |
+| Instrumentation | 92-117 | MutationObserver on flyOverlay |
+| Card trigger | 119-127 | playCard(el, CARD_ID) |
+| Polling loop | 128-149 | 8s, 200ms intervals, 6 screenshots |
+| Summary + detection | 150-233 | Flags jumps >2px |
+| Result | 235-257 | PASS if jumpCount==0 |
+
+**Config**: Headless:false, 1280x800, single card (default id=1, configurable via argv).
+**Pass/fail**: No title jumps >2px. Screenshots to `tests/diag-ck-*.png`.
+
+---
+
+### home-title-jump-diagnostic.js (680 lines)
+
+**Purpose**: Extended title jump diagnostics for home card transitions. Tests char-based fly animation (TextRearrange), plus project transitions as prerequisite.
+
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Constants & config | 0-76 | JUMP_THRESHOLD=2px, 5 themes x 2 cards x 7 viewports |
+| Viewport matrix | 55-72 | 7 viewports: 375x812 to 2560x1440 |
+| parseFlags() | 79-101 | CLI: --theme, --card, --viewport |
+| measureHeroElements() | 109-175 | Measures char spans from TextRearrange + h1/badge/heroBody |
+| checkLandingAccuracy() | 182-234 | Polls chars vs title at 50ms intervals |
+| runDiagnostic() | 238-581 | Per-combo: load, set theme, instrument, play, poll, report |
+| Main loop | 583-675 | Matrix of theme x card x viewport combos |
+
+**Config**: Headless:false, 7 viewports, 5 themes. For home card: plays card 0 first (5s), then card 3 (8s).
+**Pass/fail**: No jumps >2px, landing miss <=2px, reflow miss <=2px.
+
+---
+
+### fly-clone-alignment-test.js (459 lines)
+
+**Purpose**: Verifies flying title clone lands aligned on real target across all theme/card/viewport combos.
+
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Constants & config | 0-76 | POSITION_TOLERANCE=5px, SIZE_TOLERANCE=10px, 7 viewports |
+| CLI parsing | 77-100 | --theme, --card, --all-cards, --viewport, --width/--height |
+| testFlyAlignment() | 114-361 | Core: load, set theme, inject probe, play card, measure clone vs target |
+| MutationObserver probe | 154-272 | Same-frame paired BBox measurement of clone + target |
+| Alignment checks | 318-341 | Position <=5px, size <=10px, text <=5px |
+| Main loop | 363-454 | Matrix: themes x cards x viewports |
+
+**Config**: Headless:true, 7 viewports, 5 themes, cards 0+3 default.
+**Measurement**: MutationObserver + rAF loop measuring clone and target getBoundingClientRect on same frame. Also measures first text node via Range.
+**Pass/fail**: Position delta <=5px, size delta <=10px, text delta <=5px.
+
+---
+
+### transition-refresh-test.js (285 lines)
+
+**Purpose**: Detects invisible "flash" or slow fade-in of `.work-image` after flying clone removal.
+
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Constants | 0-31 | TIME_SETTLE=5000ms, OBSERVATION_WINDOW=2000ms, card 1 |
+| run() setup | 32-40 | Headless:true, 1280x800 |
+| Perf + Mutation observers | 41-135 | PerformanceObserver for CLS, rAF probe for effective opacity |
+| Card trigger | 141-156 | playCard on card 1 |
+| Gap/fade analysis | 158-225 | Counts frames where clone gone + image invisible |
+| Result | 230-279 | 4 checks: CLS <=0.05, no DOM bursts, no gap, <=5 fade-in frames |
+
+**Config**: Headless:true, 1280x800, card 1 only.
+**Key technique**: Effective opacity = product of all ancestor opacities (traverses chain).
+**Pass/fail**: CLS <=0.05, no image gap frames, <=5 fade-in frames.
+
+---
+
+### blur-overlay-cleanup-test.js (266 lines)
+
+**Purpose**: Verifies #dragBlurOverlay is fully cleared after card play. Catches WebKit bug where webkitBackdropFilter persists.
+
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Constants | 0-21 | MOBILE 390x844, DESKTOP 1280x800, SETTLE 6000ms |
+| triggerCardPlayAndWait() | 31-49 | Plays card 1, waits 6s |
+| getOverlayState() | 52-68 | Reads inline + computed styles |
+| isBlurCleared() / isBgCleared() | 70-76 | Checks for 'none', 'blur(0px)', transparent, etc. |
+| Test: mobile-webkit | 80-118 | Inline webkitBackdropFilter cleared |
+| Test: desktop-webkit | 120-152 | Same on desktop |
+| Test: mobile-computed | 154-186 | Computed blur value < 0.5px |
+| Test: overlay-non-blocking | 188-234 | No residual blur/bg in computed styles |
+| Runner | 236-266 | 4 tests, exit 0/1 |
+
+**Config**: Mobile (390x844) + Desktop (1280x800).
+**Pass/fail**: All blur/bg values cleared after 6s settle.
+
+---
+
+## Mobile Tests
+
+### mobile-touch-test.js (360 lines)
+
+**Purpose**: Verifies card hand touch interactions: tap-to-lift, unlift, drag, scroll-lock, plane blocking, outside dismissal, play zone scaling, hover suppression.
+
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Setup | 0-32 | iPhone 14 (390x844, 2x, hasTouch) |
+| CDP touch helpers | 34-97 | touchTap() (50ms hold), touchDrag() (interpolated steps, 16ms each) |
+| Test: tap-to-lift | 101-118 | Verify hover-active class |
+| Test: tap-to-unlift | 120-141 | Second tap removes class |
+| Test: drag-without-lift | 143-166 | No DRAGGING state after drag |
+| Test: scroll-lock | 168-210 | card-dragging class during drag |
+| Test: plane-mode-block | 212-235 | plane-active blocks tap |
+| Test: outside-dismiss | 237-269 | Tap away clears lifted state |
+| Test: play-zone-scaling | 271-293 | Zone caps at 385/289 |
+| Test: hover-suppressed | 295-325 | Touch pointerover doesn't trigger hover |
+| Runner | 329-360 | 8 tests |
+
+**Config**: iPhone 14 (390x844, 2x scale, isMobile, hasTouch).
+**Touch simulation**: CDP Input.dispatchTouchEvent (not Playwright gestures).
+
+---
+
+### mobile-hand-test.js (112 lines)
+
+**Purpose**: Verifies all cards visible and fit within viewport across 4 sizes.
+
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Setup | 0-16 | 4 viewports |
+| VIEWPORTS | 18-23 | iPhone SE 375x667, iPhone 14 390x844, Pro Max 430x932, QHD 2560x1440 |
+| Viewport loop | 30-94 | Per-viewport: count cards, check hFits + visibleAboveFold |
+| Output | 96-106 | JSON results |
+
+**Pass/fail**: >=3 cards, each within +/-5px horizontal bounds and >=30px visible above fold.
+
+---
+
+## Layout Tests
+
+### hero-layout-test.js (179 lines)
+
+**Purpose**: Checks bold theme hero layout (tidbits below desc, content flush-left, no circle overlap).
+
+| Section | Lines | Notes |
+|---------|-------|-------|
+| Setup | 0-21 | 5 resolutions |
+| RESOLUTIONS | 23-29 | 2560x1440, 1920x1080, 1440x900, 1024x768, 375x812 |
+| Resolution loop | 42-163 | Set bold theme, measure hero elements, 4 layout checks |
+| Screenshot | 118-123 | tests/screenshots/hero-bold-{w}x{h}.png |
+
+**Layout checks** (bold theme):
+1. `tidbits_below_desc`: tidbits top >= desc bottom - 2px
+2. `content_flush_left`: body left <= 80px
+3. `content_left_aligned`: body right <= vw x ratio (0.6 desktop, 0.75 tablet, 1.0 mobile)
+4. `tidbits_no_circle_overlap`: tidbits right <= vw x 0.56 (only checked at vw > 1200)
+
+---
+
+## Cross-File Patterns
+
+| Pattern | Files |
+|---------|-------|
+| iPhone 14 emulation (390x844) | perf-test, perf-test-destruction, mobile-touch-test, blur-overlay-cleanup |
+| CDP touch events | mobile-touch-test |
+| playCard() trigger | title-jump, home-title-jump, fly-clone, transition-refresh, blur-overlay |
+| RAF-based frame collection | perf-test, perf-test-destruction |
+| MutationObserver on flyOverlay | title-jump, home-title-jump, fly-clone |
+| Reveal override CSS | perf-test, perf-test-destruction, hero-layout |
+| Multi-theme matrix | fly-clone, home-title-jump |
+| Multi-viewport matrix | fly-clone, home-title-jump, mobile-hand |
+
+## Common Uncertainties
+- Several tests call `window.playCard()` without defining it -- it is expected to exist on the page (from page-transition.js)
+- Headless:false tests (title-jump, home-title-jump) require a display
+- Home card tests require playing a project card first to get the home card into the hand -- complex setup with 5s+ waits
+- Touch simulation uses CDP directly rather than Playwright's built-in touch API

From 7d89be0a39f1b185b93b0bd9ade3238055d851d2 Mon Sep 17 00:00:00 2001
From: FedG-code <federico.giovannini28@gmail.com>
Date: Thu, 2 Apr 2026 00:42:59 +0100
Subject: [PATCH 3/3] fixed, title now finally lands cleanly, only phone plane
 mode left

---
 CLAUDE.md                    |   1 +
 js/CLAUDE.md                 |  19 +-
 js/page-transition.js        |  13 +-
 js/text-rearrange.js         |  24 +-
 tests/fly-swap-diagnostic.js | 670 +++++++++++++++++++++++++++++++++++
 tests/fullstop-shift-test.js | 328 +++++++++++++++++
 6 files changed, 1023 insertions(+), 32 deletions(-)
 create mode 100644 tests/fly-swap-diagnostic.js
 create mode 100644 tests/fullstop-shift-test.js

diff --git a/CLAUDE.md b/CLAUDE.md
index c307770..6a7d8df 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -49,6 +49,7 @@ js/
 - **JS features**: Scroll reveal (IntersectionObserver), theme switcher with localStorage
 - **Text Destruction**: See [js/CLAUDE.md](js/CLAUDE.md) for detailed destruction.js documentation (mechanics, constants, mobile-gated values, impact throttle, design fallback).
 - **Card-hand system**: See [js/CLAUDE.md](js/CLAUDE.md) for card-hand.js and page-transition.js documentation (play animation phases, SPA navigation, title matching, .reveal vs card handoff, known issues).
+- **Fly-swap alignment pitfall**: Character positions differ between inline text and `display: inline-block` spans (`.destruct-char`). Any code that measures character positions for the fly animation (`measureDirect` in text-rearrange.js) must use `charsClass: 'destruct-char'` so measurements match the final split state. Similarly, `onThemeChange()` must run before the target title is revealed during cleanup — see [js/CLAUDE.md](js/CLAUDE.md) "transitionToHome Cleanup Ordering" and "Measurement Invariant" sections.
 - **Project pages**: Shared template - theme switcher, back link, project hero, repeatable sub-project sections, footer
 
 ## Serving Locally
diff --git a/js/CLAUDE.md b/js/CLAUDE.md
index faf5b95..69c7347 100644
--- a/js/CLAUDE.md
+++ b/js/CLAUDE.md
@@ -188,19 +188,21 @@ GSAP core, SplitText plugin, Physics2DPlugin (all CDN, no npm)
 | measureDirect | 37-80 | el, keepSplit | {positions[], sourceChars[], split, elRect, lineHeight} | Measures char positions + computed styles via SplitText |
 | fly | 94-263 | {sourceEl, targetEl, overlay, onStart?} | {timeline, lastLaunchTime, destroy(), charEls[]} or null | Builds GSAP timeline: chars fly along bezier arcs from source to target |
 
-### Y-Correction Logic (L121-138)
-**Problem**: SplitText on inline elements captures glyph bounds (ascenders extend above element box). Flying chars are inline-block where the box top IS the positioned coordinate.
-**Solution**: Shift all target Y positions by `elementTop - minCharY` to align inline-block boxes with glyph visual positions.
+### Measurement Invariant: destruct-char Consistency
+`measureDirect()` uses `charsClass: 'destruct-char'` so that SplitText creates inline-block spans matching the final state after `TextDestruction.onThemeChange()` re-splits. This is critical — without it, positions measured as inline text differ from positions rendered as inline-block spans, causing visible character shifts (especially on punctuation like "." which shifts ~15px).
+
+The old Y-correction block (previously L121-138) was removed because it compensated for inline-vs-inline-block glyph offset, which no longer exists when both source and target are measured as inline-block.
+
+**If you touch measureDirect or splitAllText**: both MUST use `charsClass: 'destruct-char'` with matching SplitText options, or fly-swap positions will diverge.
 
 ### Line-Height Interpolation (L204-205, L230)
 Source and target line-heights extracted per-char, linearly interpolated during animation. Prevents vertical spacing jumps between card and page typography.
 
 ### fly() Animation Flow
 1. **Validate** (L94-119): Check fonts loaded, measure source (keepSplit), measure target, validate char count (+/-2 tolerance)
-2. **Y-correct** (L121-138): Compute element-vs-glyph offset
-3. **Prepare chars** (L140-164): Reparent source chars to overlay as fixed-position elements, copy 9 computed style properties
-4. **Build timeline** (L166-250): Per-char bezier arc (alternating perpendicular offset), interpolate font-size/weight/letter-spacing/line-height linearly, swap font-family/style/text-transform at DISCRETE_SWAP, GSAP native color interpolation
-5. **Return** (L252-262): timeline, lastLaunchTime, destroy(), charEls[]
+2. **Prepare chars** (L126-150): Reparent source chars to overlay as fixed-position elements, copy 9 computed style properties
+3. **Build timeline** (L152-236): Per-char bezier arc (alternating perpendicular offset), interpolate font-size/weight/letter-spacing/line-height linearly, swap font-family/style/text-transform at DISCRETE_SWAP, GSAP native color interpolation
+4. **Return** (L238-248): timeline, lastLaunchTime, destroy(), charEls[]
 
 ### Dependencies
 GSAP core (timeline, to, set), SplitText (measureDirect)
@@ -327,6 +329,9 @@ GSAP core (timeline, to, set), SplitText (measureDirect)
 3. Uses TextRearrange.fly() for char-by-char animation (or fallback tween)
 4. After animation: destroy() clears overlay
 
+### transitionToHome Cleanup Ordering
+In the cleanup callback (~L477), `TextDestruction.onThemeChange()` MUST run BEFORE `targetTitle.style.opacity = '1'` and `rearrangeResult.destroy()`. This ensures the h1 is already split into `destruct-char` spans (inline-block) when it becomes visible. If onThemeChange runs after the title is revealed, the h1 briefly appears in its unsplit (inline) state, then jumps when re-split — punctuation like "." shifts ~15px.
+
 ### .reveal Class Handling
 Elements with `.reveal` start at opacity:0 + translateY(24px). Must be stripped from fly targets before measuring, otherwise getBoundingClientRect returns wrong values. Re-observed after transition for elements without `.visible`.
 
diff --git a/js/page-transition.js b/js/page-transition.js
index eddc6bc..9d6646e 100644
--- a/js/page-transition.js
+++ b/js/page-transition.js
@@ -475,6 +475,13 @@ function transitionToHome(cardEl, cardId, cardData, titleEl, artEl, titleRect, a
 
   // Cleanup + rebuild hand
   flyTl.call(function() {
+    // Re-init text destruction BEFORE revealing the title — splits the
+    // target h1 into destruct-char spans so positions match the fly targets.
+    // Moving this after opacity='1' caused a visible 15px jump on the fullstop.
+    if (window.TextDestruction) {
+      TextDestruction.onThemeChange();
+    }
+
     if (targetTitle) targetTitle.style.opacity = '1';
     if (rearrangeResult) rearrangeResult.destroy();
     flyOverlay.innerHTML = '';
@@ -489,12 +496,6 @@ function transitionToHome(cardEl, cardId, cardData, titleEl, artEl, titleRect, a
       }
     });
 
-    // Re-init text destruction for home page content (split was lost when
-    // onThemeChange ran while home was display:none during project view)
-    if (window.TextDestruction) {
-      TextDestruction.onThemeChange();
-    }
-
     rebuildHand(cardId);
     history.pushState({ cardId: cardId }, '', 'index.html');
   });
diff --git a/js/text-rearrange.js b/js/text-rearrange.js
index 65a4b7a..bbc3b19 100644
--- a/js/text-rearrange.js
+++ b/js/text-rearrange.js
@@ -37,7 +37,7 @@ var TextRearrange = (function () {
   function measureDirect(el, keepSplit) {
     var split = null;
     try {
-      split = SplitText.create(el, { type: 'words, chars', tag: 'span', wordsClass: 'destruct-word' });
+      split = SplitText.create(el, { type: 'words, chars', tag: 'span', charsClass: 'destruct-char', wordsClass: 'destruct-word' });
 
       var elRect = el.getBoundingClientRect();
       if (elRect.width === 0 && elRect.height === 0) {
@@ -118,24 +118,10 @@ var TextRearrange = (function () {
       }
     }
 
-    // ── Correct target positions for inline vs inline-block glyph offset ──
-    // measureDirect returns inline span glyph bounds (ascenders/italic overhangs
-    // extend beyond the element box). Flying chars are display:inline-block, where
-    // the box edges ARE the positioned coordinates. Shift target positions so the
-    // inline-block boxes align with the element box, keeping glyphs at the correct
-    // visual position when the real element appears.
-    if (tgtData.elRect && tgtData.positions.length > 0) {
-      var minCharY = tgtData.positions[0].y;
-      for (var j = 1; j < tgtData.positions.length; j++) {
-        if (tgtData.positions[j].y < minCharY) minCharY = tgtData.positions[j].y;
-      }
-      var yCorrection = tgtData.elRect.top - minCharY;
-      if (yCorrection !== 0) {
-        for (var j = 0; j < tgtData.positions.length; j++) {
-          tgtData.positions[j].y += yCorrection;
-        }
-      }
-    }
+    // Y-correction removed: measureDirect now uses charsClass:'destruct-char'
+    // (inline-block), so getBoundingClientRect already returns box positions that
+    // match the final split state. The old correction shifted targets to elRect.top
+    // which was BELOW the actual inline-block char tops, causing a 16px vertical gap.
 
     // ── Pull source chars out of sourceEl into overlay directly ──
     var charEls = [];
diff --git a/tests/fly-swap-diagnostic.js b/tests/fly-swap-diagnostic.js
new file mode 100644
index 0000000..f240f4d
--- /dev/null
+++ b/tests/fly-swap-diagnostic.js
@@ -0,0 +1,670 @@
+/**
+ * Fly-Swap Diagnostic
+ *
+ * Measures the exact position delta between the flying chars (in #flyOverlay)
+ * and the real hero h1 characters at the moment the swap happens — when
+ * destroy() is about to remove the flying chars and the real title appears.
+ *
+ * This catches the "fullstop and t shift" bug that element-level bbox tests miss.
+ *
+ * Prerequisites:
+ *   - Local server running on port 8081: npx http-server -p 8081 -c-1
+ *   - Playwright installed: npm install playwright
+ *
+ * Usage:
+ *   node tests/fly-swap-diagnostic.js
+ *   node tests/fly-swap-diagnostic.js --viewport=mobile
+ *   node tests/fly-swap-diagnostic.js --viewport=1920x1080
+ */
+
+const { chromium } = require('playwright');
+
+var BASE_URL = 'http://localhost:8081';
+var SHIFT_THRESHOLD = 2; // px — matches the jump threshold used in other tests
+
+var VIEWPORT_SHORTCUTS = {
+  mobile:  { width: 375,  height: 812,  label: '375x812'  },
+  tablet:  { width: 768,  height: 1024, label: '768x1024' },
+  desktop: { width: 1920, height: 1080, label: '1920x1080' },
+};
+
+var DEFAULT_VIEWPORTS = [
+  { width: 1280, height: 800,  label: '1280x800'  },
+  { width: 1920, height: 1080, label: '1920x1080' },
+  { width: 375,  height: 812,  label: '375x812'   },
+];
+
+function parseFlags() {
+  var flags = {};
+  process.argv.slice(2).forEach(function(arg) {
+    var m = arg.match(/^--([\w-]+)=(.+)$/);
+    if (m) { flags[m[1]] = m[2]; return; }
+    var b = arg.match(/^--([\w-]+)$/);
+    if (b) { flags[b[1]] = true; return; }
+  });
+  return flags;
+}
+
+function resolveViewport(token) {
+  var lower = token.toLowerCase();
+  if (VIEWPORT_SHORTCUTS[lower]) return VIEWPORT_SHORTCUTS[lower];
+  var m = token.match(/^(\d+)[xX×](\d+)$/);
+  if (m) {
+    var w = parseInt(m[1], 10);
+    var h = parseInt(m[2], 10);
+    return { width: w, height: h, label: w + 'x' + h };
+  }
+  return null;
+}
+
+async function runTest(browser, viewport) {
+  var label = 'bold ' + viewport.label;
+  console.log('\n--- [' + label + '] ---');
+
+  var context = await browser.newContext({
+    viewport: { width: viewport.width, height: viewport.height },
+  });
+  var page = await context.newPage();
+  var result = { name: label, passed: false, detail: null };
+
+  try {
+    // Step 1: Load page
+    console.log('  Loading index page...');
+    await page.goto(BASE_URL, { waitUntil: 'networkidle' });
+    await page.waitForFunction(function() {
+      return typeof gsap !== 'undefined' &&
+             typeof playCard === 'function' &&
+             window.TextDestruction &&
+             window.TextRearrange;
+    }, { timeout: 15000 });
+    await page.waitForTimeout(1500);
+
+    // Step 2: Set bold theme
+    await page.evaluate(function() {
+      document.documentElement.setAttribute('data-theme', 'bold');
+      localStorage.setItem('portfolio-theme', 'bold');
+    });
+    await page.waitForTimeout(300);
+
+    // Step 3: Install the swap-point hook
+    // This monkey-patches rearrangeResult.destroy to capture measurements
+    // right before the flying chars are removed.
+    await page.evaluate(function() {
+      window.__swapDiag = { captured: false, data: null, flyCount: 0 };
+
+      // Measure chars in flyOverlay using getBoundingClientRect on each span
+      function measureFlyingChars() {
+        var flyOv = document.getElementById('flyOverlay');
+        if (!flyOv) return [];
+        var spans = flyOv.querySelectorAll('span[style*="position"]');
+        var chars = [];
+        for (var i = 0; i < spans.length; i++) {
+          var span = spans[i];
+          var text = span.textContent.trim();
+          if (!text || /^\s+$/.test(text)) continue;
+          var rect = span.getBoundingClientRect();
+          if (rect.width === 0 && rect.height === 0) continue;
+          chars.push({
+            char: text,
+            left: Math.round(rect.left * 100) / 100,
+            top: Math.round(rect.top * 100) / 100,
+            width: Math.round(rect.width * 100) / 100,
+            height: Math.round(rect.height * 100) / 100,
+          });
+        }
+        return chars;
+      }
+
+      // Measure chars in the real h1 using getBoundingClientRect on .destruct-char spans
+      // (matches how flying chars are measured — both use box bounds, not glyph bounds).
+      // Falls back to Range API if h1 isn't split yet.
+      function measureRealTitle(selector) {
+        var h1 = document.querySelector(selector);
+        if (!h1) return [];
+        // Force the h1 visible temporarily so we get real rects
+        var prevOpacity = h1.style.opacity;
+        h1.style.opacity = '1';
+        // Force layout
+        h1.offsetHeight;
+
+        var charSpans = h1.querySelectorAll('.destruct-char');
+        var chars = [];
+        if (charSpans.length > 0) {
+          // Measure via destruct-char span getBoundingClientRect (same as fly chars)
+          for (var i = 0; i < charSpans.length; i++) {
+            var text = charSpans[i].textContent.trim();
+            if (!text || /^\s+$/.test(text)) continue;
+            var rect = charSpans[i].getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0) continue;
+            chars.push({
+              char: text,
+              left: Math.round(rect.left * 100) / 100,
+              top: Math.round(rect.top * 100) / 100,
+              width: Math.round(rect.width * 100) / 100,
+              height: Math.round(rect.height * 100) / 100,
+            });
+          }
+        } else {
+          // Fallback: Range API for unsplit h1
+          var walker = document.createTreeWalker(h1, NodeFilter.SHOW_TEXT);
+          var node;
+          while ((node = walker.nextNode())) {
+            for (var i = 0; i < node.length; i++) {
+              var ch = node.textContent[i];
+              if (/^\s$/.test(ch)) continue;
+              var range = document.createRange();
+              range.setStart(node, i);
+              range.setEnd(node, i + 1);
+              var rect = range.getBoundingClientRect();
+              chars.push({
+                char: ch,
+                left: Math.round(rect.left * 100) / 100,
+                top: Math.round(rect.top * 100) / 100,
+                width: Math.round(rect.width * 100) / 100,
+                height: Math.round(rect.height * 100) / 100,
+              });
+              range.detach();
+            }
+          }
+        }
+        // Restore original opacity
+        h1.style.opacity = prevOpacity;
+        return chars;
+      }
+
+      // Hook: patch TextRearrange.fly to wrap the returned destroy fn.
+      // Only capture on the SECOND fly call (card 3 -> home), skip the first (card 0 -> project).
+      var origFly = TextRearrange.fly;
+      TextRearrange.fly = function(opts) {
+        var result = origFly.call(this, opts);
+        if (!result) return result;
+
+        window.__swapDiag.flyCount++;
+        var flyNum = window.__swapDiag.flyCount;
+
+        // Only hook the second fly (home card transition)
+        if (flyNum < 2) return result;
+
+        var origDestroy = result.destroy;
+        result.destroy = function() {
+          // === THIS IS THE SWAP POINT ===
+          // Flying chars are still in the DOM. Real h1 is about to get opacity:1.
+          // Measure both right now, in the same frame.
+          if (!window.__swapDiag.captured) {
+            var flyChars = measureFlyingChars();
+            var realChars = measureRealTitle('#page-home .hero h1');
+
+            // Also capture DOM state of the h1
+            var h1 = document.querySelector('#page-home .hero h1');
+            var h1Html = h1 ? h1.innerHTML : 'NOT FOUND';
+            var h1Opacity = h1 ? h1.style.opacity : 'N/A';
+            var pageOpacity = '';
+            var homePage = document.getElementById('page-home');
+            if (homePage) pageOpacity = getComputedStyle(homePage).opacity;
+
+            window.__swapDiag.captured = true;
+            window.__swapDiag.data = {
+              flyChars: flyChars,
+              realChars: realChars,
+              h1Html: h1Html,
+              h1Opacity: h1Opacity,
+              pageOpacity: pageOpacity,
+              timestamp: performance.now(),
+            };
+          }
+
+          // Run the real destroy
+          return origDestroy.apply(this, arguments);
+        };
+
+        return result;
+      };
+    });
+
+    // Step 4: Play card 0 to get Home card in hand
+    console.log('  Playing card 0 to reach a project page...');
+    await page.evaluate(function() {
+      var el = document.querySelector('[data-card-id="0"]');
+      if (!el) throw new Error('Card 0 not found');
+      playCard(el, 0);
+    });
+    await page.waitForTimeout(7000);
+
+    // Verify Home card is in hand
+    var hasHome = await page.evaluate(function() {
+      return !!document.querySelector('[data-card-id="3"]');
+    });
+    if (!hasHome) {
+      console.log('  ERROR: Home card not found in hand after project transition');
+      result.detail = 'Home card not in hand';
+      return result;
+    }
+    console.log('  Home card confirmed in hand.');
+
+    // Step 5: Play card 3 (Home)
+    console.log('  Playing card 3 (Home)...');
+    await page.evaluate(function() {
+      var el = document.querySelector('[data-card-id="3"]');
+      if (!el) throw new Error('Card 3 not found');
+      playCard(el, 3);
+    });
+
+    // Wait for the full animation + cleanup
+    await page.waitForTimeout(10000);
+
+    // Step 6: Retrieve swap-point data
+    var diag = await page.evaluate(function() {
+      return window.__swapDiag;
+    });
+
+    if (!diag.captured || !diag.data) {
+      console.log('  WARNING: Swap point was never reached — animation may have failed');
+      result.detail = 'Swap hook not triggered';
+      return result;
+    }
+
+    var flyChars = diag.data.flyChars;
+    var realChars = diag.data.realChars;
+
+    console.log('  Flying chars captured: ' + flyChars.length);
+    console.log('  Real h1 chars captured: ' + realChars.length);
+    console.log('  h1 opacity at swap: ' + diag.data.h1Opacity);
+    console.log('  #page-home opacity at swap: ' + diag.data.pageOpacity);
+    console.log('  h1 DOM at swap (first 200): ' + diag.data.h1Html.substring(0, 200));
+
+    if (flyChars.length === 0) {
+      console.log('  WARNING: No flying chars found at swap point');
+      result.detail = 'No flying chars at swap';
+      return result;
+    }
+    if (realChars.length === 0) {
+      console.log('  WARNING: No real h1 chars found at swap point');
+      result.detail = 'No real h1 chars at swap';
+      return result;
+    }
+
+    // Step 7: Compare positions
+    console.log('\n  === Character Comparison at Swap Point ===');
+    console.log('  ' + 'idx'.padStart(4) + '  char  ' +
+      'fly.left'.padStart(9) + '  ' + 'fly.top'.padStart(9) + '  ' +
+      'real.left'.padStart(9) + '  ' + 'real.top'.padStart(9) + '  ' +
+      'dx'.padStart(8) + '  ' + 'dy'.padStart(8) + '  ' +
+      'dw'.padStart(8) + '  ' + 'dh'.padStart(8));
+    console.log('  ' + '-'.repeat(100));
+
+    var len = Math.min(flyChars.length, realChars.length);
+    var shiftCount = 0;
+    var maxDx = 0;
+    var maxDy = 0;
+    var watchedShifts = [];
+
+    for (var i = 0; i < len; i++) {
+      var f = flyChars[i];
+      var r = realChars[i];
+      var dx = f.left - r.left;
+      var dy = f.top - r.top;
+      var dw = f.width - r.width;
+      var dh = f.height - r.height;
+      var hasShift = Math.abs(dx) > SHIFT_THRESHOLD || Math.abs(dy) > SHIFT_THRESHOLD;
+      var isWatched = ['.', 't'].indexOf(f.char) !== -1;
+
+      var marker = '';
+      if (hasShift) {
+        shiftCount++;
+        marker = ' ***';
+        if (Math.abs(dx) > Math.abs(maxDx)) maxDx = dx;
+        if (Math.abs(dy) > Math.abs(maxDy)) maxDy = dy;
+      }
+      if (isWatched) marker += ' <--';
+      if (isWatched && hasShift) {
+        watchedShifts.push({ char: f.char, index: i, dx: dx, dy: dy, dw: dw, dh: dh });
+      }
+
+      console.log('  ' +
+        String(i).padStart(4) + '  ' +
+        ('"' + f.char + '"').padEnd(6) + '' +
+        f.left.toFixed(1).padStart(9) + '  ' +
+        f.top.toFixed(1).padStart(9) + '  ' +
+        r.left.toFixed(1).padStart(9) + '  ' +
+        r.top.toFixed(1).padStart(9) + '  ' +
+        dx.toFixed(2).padStart(8) + '  ' +
+        dy.toFixed(2).padStart(8) + '  ' +
+        dw.toFixed(2).padStart(8) + '  ' +
+        dh.toFixed(2).padStart(8) +
+        marker
+      );
+    }
+
+    if (flyChars.length !== realChars.length) {
+      console.log('\n  WARNING: Char count mismatch — fly=' + flyChars.length + ' real=' + realChars.length);
+    }
+
+    // Step 8: Also measure the real title AFTER onThemeChange runs
+    // (it runs during cleanup, after destroy)
+    console.log('\n  === Post-cleanup Measurement ===');
+    var postChars = await page.evaluate(function() {
+      var h1 = document.querySelector('#page-home .hero h1');
+      if (!h1) return [];
+      var charSpans = h1.querySelectorAll('.destruct-char');
+      var chars = [];
+      if (charSpans.length > 0) {
+        for (var i = 0; i < charSpans.length; i++) {
+          var text = charSpans[i].textContent.trim();
+          if (!text || /^\s+$/.test(text)) continue;
+          var rect = charSpans[i].getBoundingClientRect();
+          if (rect.width === 0 && rect.height === 0) continue;
+          chars.push({
+            char: text,
+            left: Math.round(rect.left * 100) / 100,
+            top: Math.round(rect.top * 100) / 100,
+            width: Math.round(rect.width * 100) / 100,
+            height: Math.round(rect.height * 100) / 100,
+          });
+        }
+      } else {
+        var walker = document.createTreeWalker(h1, NodeFilter.SHOW_TEXT);
+        var node;
+        while ((node = walker.nextNode())) {
+          for (var i = 0; i < node.length; i++) {
+            var ch = node.textContent[i];
+            if (/^\s$/.test(ch)) continue;
+            var range = document.createRange();
+            range.setStart(node, i);
+            range.setEnd(node, i + 1);
+            var rect = range.getBoundingClientRect();
+            chars.push({
+              char: ch,
+              left: Math.round(rect.left * 100) / 100,
+              top: Math.round(rect.top * 100) / 100,
+              width: Math.round(rect.width * 100) / 100,
+              height: Math.round(rect.height * 100) / 100,
+            });
+            range.detach();
+          }
+        }
+      }
+      return chars;
+    });
+
+    var postState = await page.evaluate(function() {
+      var h1 = document.querySelector('#page-home .hero h1');
+      if (!h1) return { html: 'NOT FOUND' };
+      return {
+        html: h1.innerHTML.substring(0, 300),
+        inlineStyle: h1.getAttribute('style') || 'none',
+        className: h1.className,
+        parentStyle: h1.parentElement ? (h1.parentElement.getAttribute('style') || 'none') : 'N/A',
+        parentClass: h1.parentElement ? h1.parentElement.className : 'N/A',
+        computedWidth: getComputedStyle(h1).width,
+        computedDisplay: getComputedStyle(h1).display,
+        computedPosition: getComputedStyle(h1).position,
+        // Check if .reveal or .visible is on hero ancestors
+        heroClass: document.querySelector('#page-home .hero') ? document.querySelector('#page-home .hero').className : 'N/A',
+      };
+    });
+    console.log('  h1 DOM after cleanup (first 300): ' + postState.html);
+    console.log('  h1 inline style: ' + postState.inlineStyle);
+    console.log('  h1 class: "' + postState.className + '"');
+    console.log('  h1 parent style: ' + postState.parentStyle);
+    console.log('  h1 parent class: "' + postState.parentClass + '"');
+    console.log('  h1 computed width: ' + postState.computedWidth);
+    console.log('  h1 computed display: ' + postState.computedDisplay);
+    console.log('  .hero class: "' + postState.heroClass + '"');
+
+    // Compare real-at-swap vs real-after-cleanup (catches onThemeChange drift)
+    var postLen = Math.min(realChars.length, postChars.length);
+    var postShiftCount = 0;
+    for (var j = 0; j < postLen; j++) {
+      var rr = realChars[j];
+      var pp = postChars[j];
+      var pdx = pp.left - rr.left;
+      var pdy = pp.top - rr.top;
+      if (Math.abs(pdx) > SHIFT_THRESHOLD || Math.abs(pdy) > SHIFT_THRESHOLD) {
+        postShiftCount++;
+        console.log('  Post-cleanup shift: [' + j + '] "' + rr.char + '" dx=' + pdx.toFixed(2) + ' dy=' + pdy.toFixed(2));
+      }
+    }
+    if (postShiftCount === 0) {
+      console.log('  No post-cleanup shifts (onThemeChange did not cause drift)');
+    }
+
+    // Step 9: Reproduce the measuring state on a fresh page load
+    // Load a fresh page and check if .measuring class causes different layout
+    console.log('\n  === Diagnostic: .measuring class effect ===');
+    var measuringTest = await page.evaluate(function() {
+      var h1 = document.querySelector('#page-home .hero h1');
+      if (!h1) return null;
+
+      // First revert SplitText so we have clean DOM
+      if (window.TextDestruction) {
+        TextDestruction.onThemeChange(); // revert + re-split
+      }
+
+      // Measure in current (normal) state — should be "correct" positions
+      function measureLast5() {
+        var walker = document.createTreeWalker(h1, NodeFilter.SHOW_TEXT);
+        var all = [];
+        var n;
+        while ((n = walker.nextNode())) {
+          for (var i = 0; i < n.length; i++) {
+            if (/^\s$/.test(n.textContent[i])) continue;
+            var r = document.createRange();
+            r.setStart(n, i); r.setEnd(n, i + 1);
+            var rect = r.getBoundingClientRect();
+            all.push({ char: n.textContent[i], left: Math.round(rect.left * 100) / 100 });
+            r.detach();
+          }
+        }
+        return all.slice(-5);
+      }
+
+      var normal = measureLast5();
+
+      // Now simulate the measuring state: revert split, then check
+      // Actually, let's test the effect of having display:none → display:block
+      // by toggling the page class
+      var page = document.getElementById('page-home');
+      var origClasses = page.className;
+
+      // Remove active, add measuring
+      page.classList.remove('active');
+      page.classList.add('measuring');
+      page.offsetHeight; // force reflow
+
+      // Revert SplitText split to match the swap-point state
+      if (window.TextDestruction) {
+        // We can't easily just revert without re-splitting, but let's try
+        // calling onThemeChange which does revert+split
+        TextDestruction.onThemeChange();
+      }
+
+      var measuring = measureLast5();
+
+      // Restore
+      page.classList.remove('measuring');
+      page.classList.add('active');
+      page.offsetHeight;
+
+      // Re-split
+      if (window.TextDestruction) {
+        TextDestruction.onThemeChange();
+      }
+
+      var restored = measureLast5();
+
+      return { normal: normal, measuring: measuring, restored: restored };
+    });
+
+    if (measuringTest) {
+      console.log('  Last 5 chars — normal vs .measuring vs restored:');
+      for (var mi = 0; mi < measuringTest.normal.length; mi++) {
+        var mn = measuringTest.normal[mi];
+        var mm = measuringTest.measuring[mi];
+        var mr = measuringTest.restored[mi];
+        console.log('    "' + mn.char + '" normal=' + mn.left + '  measuring=' + (mm ? mm.left : 'N/A') + '  restored=' + (mr ? mr.left : 'N/A') +
+          (mm && Math.abs(mm.left - mn.left) > 0.5 ? '  *** DIFF ***' : ''));
+      }
+    }
+
+    // Step 10: Check inline style effect
+    console.log('\n  === Diagnostic: Revert split and remeasure ===');
+    var revertedChars = await page.evaluate(function() {
+      // Revert the SplitText split
+      if (window.TextDestruction) {
+        // Access the internal revertAllText via onThemeChange - but that re-splits.
+        // Instead, call destroy which just disarms, then manually check.
+      }
+      // Actually, let's check the "t" and "." positions with and without the inline style
+      var h1 = document.querySelector('#page-home .hero h1');
+      var results = {};
+
+      // Current state (after onThemeChange with inline styles)
+      results.withInline = {};
+      var walker1 = document.createTreeWalker(h1, NodeFilter.SHOW_TEXT);
+      var allChars1 = [];
+      var n1;
+      while ((n1 = walker1.nextNode())) {
+        for (var i = 0; i < n1.length; i++) {
+          if (/^\s$/.test(n1.textContent[i])) continue;
+          var r = document.createRange();
+          r.setStart(n1, i); r.setEnd(n1, i + 1);
+          var rect = r.getBoundingClientRect();
+          allChars1.push({ char: n1.textContent[i], left: rect.left, top: rect.top });
+          r.detach();
+        }
+      }
+      results.withInline.chars = allChars1;
+      results.withInline.style = h1.getAttribute('style');
+
+      // Remove inline styles, re-measure
+      h1.removeAttribute('style');
+      h1.offsetHeight; // force reflow
+
+      // Also need to re-add .reveal.visible or the h1 might be invisible
+      // Actually let's just check if removing inline style changes positions
+      var walker2 = document.createTreeWalker(h1, NodeFilter.SHOW_TEXT);
+      var allChars2 = [];
+      var n2;
+      while ((n2 = walker2.nextNode())) {
+        for (var i = 0; i < n2.length; i++) {
+          if (/^\s$/.test(n2.textContent[i])) continue;
+          var r = document.createRange();
+          r.setStart(n2, i); r.setEnd(n2, i + 1);
+          var rect = r.getBoundingClientRect();
+          allChars2.push({ char: n2.textContent[i], left: rect.left, top: rect.top });
+          r.detach();
+        }
+      }
+      results.withoutInline = {};
+      results.withoutInline.chars = allChars2;
+      results.withoutInline.display = getComputedStyle(h1).display;
+      results.withoutInline.opacity = getComputedStyle(h1).opacity;
+      results.withoutInline.h1Class = h1.className;
+      results.withoutInline.hasReveal = h1.classList.contains('reveal');
+      results.withoutInline.hasVisible = h1.classList.contains('visible');
+
+      // Restore inline style for consistency
+      h1.style.opacity = '1';
+      h1.style.transform = 'translateY(0px)';
+
+      return results;
+    });
+
+    // Compare the "." position with vs without inline styles
+    var withChars = revertedChars.withInline.chars;
+    var withoutChars = revertedChars.withoutInline.chars;
+    var len2 = Math.min(withChars.length, withoutChars.length);
+    console.log('  h1 class: "' + revertedChars.withoutInline.h1Class + '"  .reveal=' + revertedChars.withoutInline.hasReveal + '  .visible=' + revertedChars.withoutInline.hasVisible);
+    console.log('  Without inline style: display=' + revertedChars.withoutInline.display + ' opacity=' + revertedChars.withoutInline.opacity);
+    for (var k = len2 - 5; k < len2; k++) {
+      if (k < 0) continue;
+      var wc = withChars[k];
+      var woc = withoutChars[k];
+      var ddx = woc.left - wc.left;
+      console.log('    [' + k + '] "' + wc.char + '" with=' + wc.left.toFixed(1) + ' without=' + woc.left.toFixed(1) + ' delta=' + ddx.toFixed(2));
+    }
+
+    // Summary
+    console.log('\n  === Result ===');
+    var passed = shiftCount === 0 && watchedShifts.length === 0 && postShiftCount === 0;
+    if (passed) {
+      console.log('  PASS: Flying chars aligned with real title (threshold: ' + SHIFT_THRESHOLD + 'px)');
+    } else {
+      if (shiftCount > 0) {
+        console.log('  FAIL: ' + shiftCount + ' char(s) misaligned at swap. Max dx=' + maxDx.toFixed(2) + 'px, dy=' + maxDy.toFixed(2) + 'px');
+      }
+      if (watchedShifts.length > 0) {
+        console.log('  FAIL: Watched chars shifted:');
+        watchedShifts.forEach(function(ws) {
+          console.log('    "' + ws.char + '" [' + ws.index + '] dx=' + ws.dx.toFixed(2) + ' dy=' + ws.dy.toFixed(2));
+        });
+      }
+      if (postShiftCount > 0) {
+        console.log('  FAIL: ' + postShiftCount + ' char(s) shifted after onThemeChange cleanup');
+      }
+    }
+
+    result.passed = passed;
+
+  } catch (err) {
+    console.log('  ERROR: ' + err.message);
+    result.detail = err.message;
+  } finally {
+    await context.close();
+  }
+
+  return result;
+}
+
+async function main() {
+  var flags = parseFlags();
+
+  var viewports;
+  if (flags.viewport) {
+    viewports = flags.viewport.split(',').map(function(token) {
+      var vp = resolveViewport(token.trim());
+      if (!vp) {
+        console.error('Unknown viewport: "' + token.trim() + '"');
+        process.exit(1);
+      }
+      return vp;
+    });
+  } else {
+    viewports = DEFAULT_VIEWPORTS;
+  }
+
+  console.log('=== Fly-Swap Diagnostic ===');
+  console.log('Theme: bold');
+  console.log('Viewports: ' + viewports.map(function(v) { return v.label; }).join(', '));
+  console.log('Shift threshold: ' + SHIFT_THRESHOLD + 'px');
+
+  var browser = await chromium.launch({ headless: false });
+  var results = [];
+
+  for (var i = 0; i < viewports.length; i++) {
+    var r = await runTest(browser, viewports[i]);
+    results.push(r);
+  }
+
+  await browser.close();
+
+  // Summary
+  console.log('\n════════════════════════════════');
+  var passed = results.filter(function(r) { return r.passed; }).length;
+  var failed = results.filter(function(r) { return !r.passed; }).length;
+  console.log('Passed: ' + passed + '  Failed: ' + failed + '  Total: ' + results.length);
+
+  if (failed > 0) {
+    console.log('\nFailed:');
+    results.forEach(function(r) {
+      if (!r.passed) console.log('  [FAIL] ' + r.name + (r.detail ? ' — ' + r.detail : ''));
+    });
+  }
+
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+main().catch(function(err) {
+  console.error('Error:', err);
+  process.exit(1);
+});
diff --git a/tests/fullstop-shift-test.js b/tests/fullstop-shift-test.js
new file mode 100644
index 0000000..38e7f96
--- /dev/null
+++ b/tests/fullstop-shift-test.js
@@ -0,0 +1,328 @@
+/**
+ * Fullstop & "t" Shift Diagnostic
+ *
+ * Tests whether TextDestruction.onThemeChange() causes individual characters
+ * in the home page hero h1 ("Never shipped a boring product.") to shift
+ * position — specifically the "t" and "." at the end of the second line.
+ *
+ * This test does NOT run the fly animation. It isolates the SplitText
+ * revert/re-split cycle to confirm whether that alone causes the shift.
+ *
+ * Prerequisites:
+ *   - Local server running on port 8080: npx http-server -p 8080 -c-1
+ *   - Playwright installed: npm install playwright
+ *
+ * Usage:
+ *   node tests/fullstop-shift-test.js
+ */
+
+const { chromium } = require('playwright');
+
+var BASE_URL = 'http://localhost:8081';
+var SHIFT_THRESHOLD = 0.5; // px — anything above this is a detectable shift
+
+// Characters of interest (will flag shifts on these specifically)
+var WATCH_CHARS = ['.', 't'];
+
+/**
+ * Measures individual character positions in an element using the Range API.
+ * This avoids introducing any DOM changes (unlike SplitText).
+ * Returns array of { char, left, top, width, height } for each character.
+ */
+function getMeasureCharsFn() {
+  return function measureCharPositions(selector) {
+    var el = document.querySelector(selector);
+    if (!el) return null;
+
+    // Collect all characters from text nodes via TreeWalker
+    var walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    var positions = [];
+    var node;
+    while ((node = walker.nextNode())) {
+      for (var i = 0; i < node.length; i++) {
+        var ch = node.textContent[i];
+        // Skip whitespace-only characters (spaces, newlines)
+        if (/^\s$/.test(ch)) continue;
+
+        var range = document.createRange();
+        range.setStart(node, i);
+        range.setEnd(node, i + 1);
+        var rect = range.getBoundingClientRect();
+        positions.push({
+          char: ch,
+          left: Math.round(rect.left * 100) / 100,
+          top: Math.round(rect.top * 100) / 100,
+          width: Math.round(rect.width * 100) / 100,
+          height: Math.round(rect.height * 100) / 100,
+        });
+        range.detach();
+      }
+    }
+    return positions;
+  };
+}
+
+function comparePositions(before, after, label) {
+  var passed = true;
+  var shifts = [];
+
+  // Match by index — both arrays should have same char sequence
+  var len = Math.min(before.length, after.length);
+  if (before.length !== after.length) {
+    console.log('  WARNING: Character count changed (' + before.length + ' -> ' + after.length + ')');
+  }
+
+  for (var i = 0; i < len; i++) {
+    var b = before[i];
+    var a = after[i];
+    if (b.char !== a.char) {
+      console.log('  WARNING: Character mismatch at index ' + i + ': "' + b.char + '" vs "' + a.char + '"');
+      continue;
+    }
+
+    var dx = a.left - b.left;
+    var dy = a.top - b.top;
+    var dw = a.width - b.width;
+    var dh = a.height - b.height;
+
+    var isWatched = WATCH_CHARS.indexOf(b.char) !== -1;
+    var hasShift = Math.abs(dx) > SHIFT_THRESHOLD || Math.abs(dy) > SHIFT_THRESHOLD ||
+                   Math.abs(dw) > SHIFT_THRESHOLD || Math.abs(dh) > SHIFT_THRESHOLD;
+
+    if (hasShift) {
+      var entry = {
+        index: i,
+        char: b.char,
+        dx: dx,
+        dy: dy,
+        dw: dw,
+        dh: dh,
+        watched: isWatched,
+      };
+      shifts.push(entry);
+      if (isWatched) passed = false;
+    }
+  }
+
+  console.log('\n  === ' + label + ' ===');
+  if (shifts.length === 0) {
+    console.log('  No character shifts detected (threshold: ' + SHIFT_THRESHOLD + 'px)');
+  } else {
+    console.log('  ' + shifts.length + ' character(s) shifted:');
+    shifts.forEach(function(s) {
+      var marker = s.watched ? ' *** WATCHED ***' : '';
+      console.log(
+        '    [' + s.index + '] "' + s.char + '"' +
+        '  dx=' + s.dx.toFixed(2) + 'px' +
+        '  dy=' + s.dy.toFixed(2) + 'px' +
+        '  dw=' + s.dw.toFixed(2) + 'px' +
+        '  dh=' + s.dh.toFixed(2) + 'px' +
+        marker
+      );
+    });
+  }
+
+  return { passed: passed, shifts: shifts };
+}
+
+async function run() {
+  console.log('=== Fullstop & "t" Shift Diagnostic ===');
+  console.log('Threshold: ' + SHIFT_THRESHOLD + 'px');
+  console.log('Watched chars: ' + WATCH_CHARS.join(', '));
+
+  var browser = await chromium.launch({ headless: false });
+  var context = await browser.newContext({
+    viewport: { width: 1280, height: 800 },
+  });
+  var page = await context.newPage();
+  var allPassed = true;
+
+  try {
+    // Load page
+    console.log('\nLoading index page...');
+    await page.goto(BASE_URL, { waitUntil: 'networkidle' });
+
+    // Wait for GSAP + SplitText + TextDestruction
+    await page.waitForFunction(function() {
+      return typeof gsap !== 'undefined' &&
+             typeof SplitText !== 'undefined' &&
+             window.TextDestruction;
+    }, { timeout: 15000 });
+
+    // Set bold theme
+    await page.evaluate(function() {
+      document.documentElement.setAttribute('data-theme', 'bold');
+      localStorage.setItem('portfolio-theme', 'bold');
+    });
+
+    // Wait for fonts to load
+    await page.waitForFunction(function() {
+      return document.fonts.status === 'loaded';
+    }, { timeout: 10000 });
+    await page.waitForTimeout(500);
+
+    // Make sure .reveal elements are visible
+    await page.evaluate(function() {
+      document.querySelectorAll('.reveal').forEach(function(el) {
+        el.classList.add('visible');
+      });
+    });
+    await page.waitForTimeout(300);
+
+    var selector = '.hero h1';
+
+    // ─── Test 1: Fresh page → onThemeChange() ───────────────
+    console.log('\n--- Test 1: Fresh page -> onThemeChange() ---');
+
+    // Check if text is already split from page load
+    var alreadySplit = await page.evaluate(function() {
+      var h1 = document.querySelector('.hero h1');
+      return h1 ? h1.querySelector('.destruct-char') !== null : false;
+    });
+    console.log('  Text already split on load: ' + alreadySplit);
+
+    if (alreadySplit) {
+      // Revert first to get clean baseline
+      console.log('  Reverting existing split for clean baseline...');
+      await page.evaluate(function() {
+        TextDestruction.onThemeChange(); // revert + re-split
+      });
+      await page.waitForTimeout(200);
+      // Now revert again to get truly clean state
+      // We need to access the internal revert — call onThemeChange which does revert+split,
+      // but we want just reverted. Instead, destroy + revert approach:
+      await page.evaluate(function() {
+        // onThemeChange does revertAll then splitAll, so calling destroy
+        // leaves the text in split state. Let's just measure in whatever state it is.
+      });
+    }
+
+    // Measure baseline (whatever state the page is in after load)
+    console.log('  Measuring baseline character positions...');
+    var baseline1 = await page.evaluate(getMeasureCharsFn(), selector);
+    if (!baseline1) {
+      console.log('  ERROR: Could not find ' + selector);
+      allPassed = false;
+    } else {
+      console.log('  Found ' + baseline1.length + ' characters');
+
+      // Print all char positions for debugging
+      console.log('  Characters:');
+      baseline1.forEach(function(c, i) {
+        var marker = WATCH_CHARS.indexOf(c.char) !== -1 ? ' <--' : '';
+        console.log('    [' + i + '] "' + c.char + '"  left=' + c.left + '  top=' + c.top + '  w=' + c.width + '  h=' + c.height + marker);
+      });
+
+      // Call onThemeChange (revert + re-split)
+      console.log('\n  Calling TextDestruction.onThemeChange()...');
+      await page.evaluate(function() {
+        TextDestruction.onThemeChange();
+      });
+      await page.waitForTimeout(300);
+
+      // Measure after
+      var after1 = await page.evaluate(getMeasureCharsFn(), selector);
+      if (!after1) {
+        console.log('  ERROR: Could not measure after onThemeChange');
+        allPassed = false;
+      } else {
+        console.log('  Found ' + after1.length + ' characters after onThemeChange');
+
+        // Print post positions
+        console.log('  Characters after:');
+        after1.forEach(function(c, i) {
+          var marker = WATCH_CHARS.indexOf(c.char) !== -1 ? ' <--' : '';
+          console.log('    [' + i + '] "' + c.char + '"  left=' + c.left + '  top=' + c.top + '  w=' + c.width + '  h=' + c.height + marker);
+        });
+
+        var result1 = comparePositions(baseline1, after1, 'Test 1: Fresh -> onThemeChange');
+        if (!result1.passed) allPassed = false;
+      }
+    }
+
+    // ─── Test 2: Repeated onThemeChange() cycles ─────────────
+    console.log('\n--- Test 2: Repeated onThemeChange() cycles (drift check) ---');
+
+    // Measure current state
+    var baseline2 = await page.evaluate(getMeasureCharsFn(), selector);
+
+    // Run 3 more cycles
+    for (var cycle = 0; cycle < 3; cycle++) {
+      await page.evaluate(function() {
+        TextDestruction.onThemeChange();
+      });
+      await page.waitForTimeout(200);
+    }
+
+    var after2 = await page.evaluate(getMeasureCharsFn(), selector);
+    if (baseline2 && after2) {
+      var result2 = comparePositions(baseline2, after2, 'Test 2: 3x onThemeChange cycles');
+      if (!result2.passed) allPassed = false;
+    }
+
+    // ─── Test 3: Revert only (no re-split) ───────────────────
+    console.log('\n--- Test 3: Measure split vs reverted (no re-split) ---');
+
+    // Current state is split. Measure it.
+    var baseline3 = await page.evaluate(getMeasureCharsFn(), selector);
+
+    // Revert without re-splitting by calling the internal function
+    // We can access it via a trick: call onThemeChange but intercept
+    // Actually, let's just use the public API differently:
+    // destroy() kills tweens but doesn't revert. We need to trigger revert.
+    // The cleanest way: evaluate the revert directly
+    await page.evaluate(function() {
+      // onThemeChange does: revertAll -> splitAll
+      // We want just revertAll. But it's not exposed.
+      // Workaround: call onThemeChange, then immediately check if we can
+      // access the reverted state. Actually onThemeChange is synchronous,
+      // so by the time it returns, text is already re-split.
+      // Alternative: just compare split state before and after full revert+split
+      // which is what Test 1 already does.
+      // For this test, let's measure the h1 innerHTML to see DOM structure changes.
+    });
+
+    // Instead, let's check the DOM structure difference
+    var domBefore = await page.evaluate(function() {
+      var h1 = document.querySelector('.hero h1');
+      return h1 ? h1.innerHTML : null;
+    });
+    console.log('  DOM structure (split): ' + (domBefore ? domBefore.substring(0, 120) + '...' : 'null'));
+
+    // Check if kern-ri span survives the split
+    var kernRiSurvived = await page.evaluate(function() {
+      var h1 = document.querySelector('.hero h1');
+      if (!h1) return { exists: false };
+      var kernSpan = h1.querySelector('.kern-ri');
+      if (!kernSpan) return { exists: false, innerHTML: h1.innerHTML };
+      return {
+        exists: true,
+        text: kernSpan.textContent,
+        parentTag: kernSpan.parentElement ? kernSpan.parentElement.className : 'none',
+      };
+    });
+    console.log('  .kern-ri span after split: ' + JSON.stringify(kernRiSurvived));
+
+    if (!kernRiSurvived.exists) {
+      console.log('  WARNING: .kern-ri span was destroyed by SplitText — this may cause the "t"/"." shift!');
+    }
+
+    // ─── Summary ─────────────────────────────────────────────
+    console.log('\n════════════════════════════════');
+    console.log(allPassed ? 'RESULT: PASS — no watched character shifts detected' : 'RESULT: FAIL — watched characters shifted');
+
+  } catch (err) {
+    console.log('ERROR: ' + err.message);
+    allPassed = false;
+  } finally {
+    await context.close();
+    await browser.close();
+  }
+
+  process.exit(allPassed ? 0 : 1);
+}
+
+run().catch(function(err) {
+  console.error('Error:', err);
+  process.exit(1);
+});
