@struq/skill 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +133 -2
  3. package/bin/struq.mjs +132 -0
  4. package/package.json +41 -4
  5. package/skills/struq/SKILL.md +237 -0
  6. package/skills/struq/cinematic/README.md +409 -0
  7. package/skills/struq/cinematic/checklists/01-preproduction.md +15 -0
  8. package/skills/struq/cinematic/checklists/02-implementation.md +17 -0
  9. package/skills/struq/cinematic/checklists/03-polish.md +17 -0
  10. package/skills/struq/cinematic/examples/code/nextjs/README.md +13 -0
  11. package/skills/struq/cinematic/examples/code/nextjs/app/cinematic-experience.tsx +13 -0
  12. package/skills/struq/cinematic/examples/code/nextjs/app/components/LenisRoot.tsx +42 -0
  13. package/skills/struq/cinematic/examples/code/nextjs/app/page.tsx +6 -0
  14. package/skills/struq/cinematic/examples/code/shared/CameraRig.tsx +65 -0
  15. package/skills/struq/cinematic/examples/code/shared/ExperienceCanvas.tsx +20 -0
  16. package/skills/struq/cinematic/examples/code/shared/ExperienceDirector.tsx +57 -0
  17. package/skills/struq/cinematic/examples/code/shared/ExperienceOverlay.tsx +37 -0
  18. package/skills/struq/cinematic/examples/code/shared/ExperiencePage.tsx +52 -0
  19. package/skills/struq/cinematic/examples/code/shared/GsapFrameLoop.tsx +32 -0
  20. package/skills/struq/cinematic/examples/code/shared/InteriorRoot.tsx +30 -0
  21. package/skills/struq/cinematic/examples/code/shared/README.md +20 -0
  22. package/skills/struq/cinematic/examples/code/shared/SubjectRig.tsx +58 -0
  23. package/skills/struq/cinematic/examples/code/shared/build-experience-timeline.ts +237 -0
  24. package/skills/struq/cinematic/examples/code/shared/direction.ts +52 -0
  25. package/skills/struq/cinematic/examples/code/shared/gsap-client.ts +32 -0
  26. package/skills/struq/cinematic/examples/code/shared/math.ts +12 -0
  27. package/skills/struq/cinematic/examples/code/shared/registry.ts +58 -0
  28. package/skills/struq/cinematic/examples/code/shared/runtime.ts +52 -0
  29. package/skills/struq/cinematic/examples/code/shared/styles.css +127 -0
  30. package/skills/struq/cinematic/examples/code/shared/useExperienceInput.ts +42 -0
  31. package/skills/struq/cinematic/examples/code/vite/README.md +14 -0
  32. package/skills/struq/cinematic/examples/code/vite/src/App.tsx +11 -0
  33. package/skills/struq/cinematic/examples/code/vite/src/LenisRoot.tsx +37 -0
  34. package/skills/struq/cinematic/examples/code/vite/src/main.tsx +9 -0
  35. package/skills/struq/cinematic/examples/concise/01-chapter-spec-example.md +42 -0
  36. package/skills/struq/cinematic/examples/concise/02-handoff-example.md +25 -0
  37. package/skills/struq/cinematic/examples/concise/03-audit-finding-example.md +13 -0
  38. package/skills/struq/cinematic/examples/verbose/01-full-experience-direction.md +687 -0
  39. package/skills/struq/cinematic/examples/verbose/02-full-audit-example.md +362 -0
  40. package/skills/struq/cinematic/references/01-core-mental-model.md +221 -0
  41. package/skills/struq/cinematic/references/02-vocabulary.md +384 -0
  42. package/skills/struq/cinematic/references/03-experience-architecture.md +302 -0
  43. package/skills/struq/cinematic/references/04-timeline-choreography.md +264 -0
  44. package/skills/struq/cinematic/references/05-handoff-contracts.md +241 -0
  45. package/skills/struq/cinematic/references/06-three-rig-architecture.md +286 -0
  46. package/skills/struq/cinematic/references/07-stack-integration.md +228 -0
  47. package/skills/struq/cinematic/references/08-gsap-plugin-patterns.md +218 -0
  48. package/skills/struq/cinematic/references/09-tuning-harness.md +202 -0
  49. package/skills/struq/cinematic/references/10-quality-systems.md +206 -0
  50. package/skills/struq/cinematic/references/11-agent-workflows.md +246 -0
  51. package/skills/struq/cinematic/references/12-audit-rubric.md +176 -0
  52. package/skills/struq/cinematic/references/13-official-docs.md +53 -0
  53. package/skills/struq/cinematic/templates/01-experience-brief.md +105 -0
  54. package/skills/struq/cinematic/templates/02-experience-contract.md +80 -0
  55. package/skills/struq/cinematic/templates/03-chapter-spec.md +103 -0
  56. package/skills/struq/cinematic/templates/04-handoff-contract.md +102 -0
  57. package/skills/struq/cinematic/templates/05-ownership-matrix.md +29 -0
  58. package/skills/struq/cinematic/templates/06-shot-presets.md +59 -0
  59. package/skills/struq/cinematic/templates/07-implementation-slice.md +66 -0
  60. package/skills/struq/cinematic/templates/08-tuning-register.md +36 -0
  61. package/skills/struq/cinematic/templates/09-acceptance-tests.md +57 -0
  62. package/skills/struq/references/anti-patterns.md +265 -0
  63. package/skills/struq/references/baseline-prompt.md +118 -0
  64. package/skills/struq/references/brand.md +143 -0
  65. package/skills/struq/references/brief-router.md +219 -0
  66. package/skills/struq/references/composition.md +191 -0
  67. package/skills/struq/references/depth-parallax.md +235 -0
  68. package/skills/struq/references/direction.md +188 -0
  69. package/skills/struq/references/feel-layer.md +107 -0
  70. package/skills/struq/references/gsap-api.md +293 -0
  71. package/skills/struq/references/iconography.md +255 -0
  72. package/skills/struq/references/imagery.md +144 -0
  73. package/skills/struq/references/loaders.md +287 -0
  74. package/skills/struq/references/micro-interactions.md +270 -0
  75. package/skills/struq/references/mobile-composition.md +70 -0
  76. package/skills/struq/references/nav-header.md +296 -0
  77. package/skills/struq/references/page-architecture.md +134 -0
  78. package/skills/struq/references/page-entrances.md +198 -0
  79. package/skills/struq/references/performance.md +235 -0
  80. package/skills/struq/references/pinning-scrub.md +341 -0
  81. package/skills/struq/references/pitfalls.md +290 -0
  82. package/skills/struq/references/route-transitions.md +281 -0
  83. package/skills/struq/references/scaling.md +151 -0
  84. package/skills/struq/references/scroll-reveals.md +280 -0
  85. package/skills/struq/references/seo.md +219 -0
  86. package/skills/struq/references/setup.md +397 -0
  87. package/skills/struq/references/showcase.md +87 -0
  88. package/skills/struq/references/stack-targets.md +78 -0
  89. package/skills/struq/references/struq-imagery.md +107 -0
  90. package/skills/struq/references/svg-motion.md +390 -0
  91. package/skills/struq/references/transitions.md +160 -0
  92. package/skills/struq/references/triage.md +71 -0
  93. package/skills/struq/references/typography.md +720 -0
  94. package/skills/struq/references/vibe-presets.md +287 -0
  95. package/skills/struq/references/webgl-r3f.md +274 -0
  96. package/skills/struq/references/webgl-scenes.md +593 -0
@@ -0,0 +1,687 @@
1
+ # Full Experience Direction Example: Aether One
2
+
3
+ This example demonstrates the expected level of direction for a fictional premium spatial-audio product. It is not intended as a visual style to copy. Its purpose is to show how a brief becomes chapters, states, camera shots, timelines, handoffs, responsive variants, and acceptance criteria.
4
+
5
+ ## 1. Brief summary
6
+
7
+ **Product:** Aether One, a sculptural spatial-audio object with an outer ring, suspended acoustic core, and internal waveguide.
8
+
9
+ **Objective:** Make the visitor understand that the product does not merely play sound; it shapes a room as a responsive acoustic field.
10
+
11
+ **Required messages:**
12
+
13
+ 1. Aether One is a physical object with a distinctive silhouette.
14
+ 2. Its material construction creates controlled acoustic behavior.
15
+ 3. Its internal waveguide shapes spatial sound.
16
+ 4. It adapts to the room and listener.
17
+ 5. The user can explore details and proceed to a product page or purchase flow.
18
+
19
+ **Available assets:** optimized GLB with named nodes, room environment map, four SVG diagrams, editorial typeface, short ambient audio loop, product renders, and a lightweight noise shader.
20
+
21
+ **Target:** modern desktop and mobile devices, with a balanced performance tier as the default.
22
+
23
+ ## 2. Experience thesis
24
+
25
+ The viewer approaches Aether One as a silent sculptural object, gradually discovers that its physical layers form an acoustic instrument, passes through its central aperture into the waveguide, and emerges into a room transformed by a responsive sound field. The outer ring remains the principal bridge across the experience, changing from silhouette to mechanism to portal to field boundary. The emotional progression is restraint → curiosity → mechanical clarity → spatial immersion → calm resolution.
26
+
27
+ ## 3. Experience contract
28
+
29
+ ### Persistent-stage strategy
30
+
31
+ A single viewport-locked stage persists from the opening through the room resolution. The Three.js canvas, camera hierarchy, lighting root, product root, grain, cursor, and progress indicator remain mounted. Semantic DOM chapters provide content and scroll ranges. The visible world evolves without resetting the camera or canvas at chapter boundaries.
32
+
33
+ ### Chapter map
34
+
35
+ | ID | Name | Purpose | Main transformation | Scroll budget | Bridge |
36
+ |---|---|---|---|---:|---|
37
+ | `arrival` | Silent Object | Establish silhouette and premium material presence. | Darkness becomes a controlled hero composition. | 2.2 vh | Outer ring silhouette |
38
+ | `material` | Built to Shape | Reveal shell, suspension, and acoustic layers. | Complete object separates into functional layers. | 3.4 vh | Outer ring aligns to camera |
39
+ | `interior` | Inside the Wave | Explain the internal waveguide spatially. | Camera passes through ring into a luminous acoustic tunnel. | 4.0 vh | Traveling wave ribbon |
40
+ | `field` | The Room Responds | Show the product shaping a room-scale field. | Tunnel wave expands into a room and listener field. | 3.8 vh | Wave ribbon becomes room contour |
41
+ | `resolve` | A Quiet Centre | Return control and present product action. | Field contracts around the complete product in a calm final pose. | 2.3 vh | Ring becomes CTA focus |
42
+
43
+ `vh` here means viewport-height units of scroll distance, not literal CSS units inside the timeline.
44
+
45
+ ### Motion language
46
+
47
+ **Camera:** controlled dolly and truck movement with small target leads; no perpetual orbit. Stable hero poses and one major pass-through form the spatial punctuation.
48
+
49
+ **Product:** weighty, precise, mechanically plausible. Layer separation uses restrained overshoot only on suspended internal parts.
50
+
51
+ **Typography:** large editorial lines appear through directional masks, then reduce into small technical labels. Type follows the same visual axes as product geometry.
52
+
53
+ **SVG:** thin technical lines initially describe physical construction, then become the traveling wave ribbon and finally the room-field contour.
54
+
55
+ **Ambient:** subtle material shimmer, low-amplitude particle drift, minute light motion, and slow wave shader movement continue when scrolling stops.
56
+
57
+ **Transition language:** object bridge, camera pass-through, vector morph, light continuity, and screen-space matching. No full-screen fade between narrative chapters.
58
+
59
+ ### Input ownership
60
+
61
+ | Input | Responsibility | Strength | Gating |
62
+ |---|---|---:|---|
63
+ | Scroll | Primary narrative progress | 1.0 | Always, except intro and route leave locks |
64
+ | Time | Ambient wave, material shimmer, room particles | Low | Continuous |
65
+ | Pointer | Micro camera target shift and product reaction | 0.02-0.055 | Reduced during pass-through and final CTA focus |
66
+ | Scroll velocity | Brief wave stretch and slight chromatic displacement | Max 0.18 | Disabled in reduced motion; attenuated during reading holds |
67
+ | Hover | Local technical labels and CTA feedback | Local | Only inside chapter interaction envelopes |
68
+ | Click/tap | Detail state, sound toggle, CTA route transition | Discrete | Disabled during critical handoffs |
69
+ | Keyboard | Chapter links, details, CTA, sound control | Equivalent | Always available |
70
+
71
+ ### Prohibited patterns
72
+
73
+ - No chapter begins from a blank or default camera pose.
74
+ - No repeated title fade-up from `y: 50` as the default reveal.
75
+ - No equal-strength pointer parallax throughout.
76
+ - No separate full-screen background color swap without a light or geometry bridge.
77
+ - No direct camera mutation from pointer code.
78
+ - No model layer unmount during a reversible transition.
79
+ - No desktop-only pass-through copied unchanged to mobile.
80
+
81
+ ## 4. State model
82
+
83
+ ```ts
84
+ type AetherExperienceState = {
85
+ route: 'home' | 'product';
86
+ routePhase: 'idle' | 'entering' | 'active' | 'leaving';
87
+ activeChapter:
88
+ | 'arrival'
89
+ | 'material'
90
+ | 'interior'
91
+ | 'field'
92
+ | 'resolve';
93
+ globalProgress: number;
94
+ chapterProgress: number;
95
+ handoffId: string | null;
96
+ handoffProgress: number;
97
+ elapsedTime: number;
98
+ deltaTime: number;
99
+ scrollVelocity: number;
100
+ scrollDirection: -1 | 0 | 1;
101
+ pointer: {
102
+ x: number;
103
+ y: number;
104
+ speed: number;
105
+ };
106
+ interactionMode: 'narrative' | 'explore' | 'detail' | 'route-transition';
107
+ viewport: 'desktop-wide' | 'desktop' | 'tablet' | 'mobile';
108
+ motionPreference: 'full' | 'reduced';
109
+ performanceTier: 'high' | 'balanced' | 'safe';
110
+ assets: {
111
+ productReady: boolean;
112
+ interiorReady: boolean;
113
+ roomReady: boolean;
114
+ fontsReady: boolean;
115
+ };
116
+ };
117
+ ```
118
+
119
+ ## 5. Property ownership matrix
120
+
121
+ | Target/property | Narrative owner | Reactive channel | Ambient channel | Discrete owner |
122
+ |---|---|---|---|---|
123
+ | camera placement | route timeline only during route transitions | none | none | route transition |
124
+ | camera narrative position | active chapter or handoff timeline | none | none | none |
125
+ | camera reaction rotation | none | pointer damping | tiny breathing target offset | disabled during critical handoff |
126
+ | camera shake | none | velocity accent | low noise | disabled in reduced motion |
127
+ | camera target narrative | chapter or handoff timeline | none | none | route transition under cover |
128
+ | product placement | chapter or handoff timeline | none | none | detail state when chapter allows |
129
+ | product reaction | none | pointer yaw/pitch | suspended-core idle | detail state attenuates |
130
+ | product layer separation | material chapter | none | small follow-through | handoff owns ring after cue |
131
+ | wave shader narrative progress | interior/field timelines | velocity additive channel | time phase | none |
132
+ | title wrapper transform | GSAP chapter timeline | none | none | route transition cover may own outer wrapper |
133
+ | title inner hover | none | Motion local interaction | none | none |
134
+ | SVG bridge path | handoff timeline | none | dash shimmer | none |
135
+ | bloom strength | chapter/effect channel | velocity additive | base level | route cover may override |
136
+ | grain | none | none | global ambient | none |
137
+
138
+ ## 6. Scene and rig hierarchy
139
+
140
+ ```text
141
+ ExperienceScene
142
+ ├── WorldRoot
143
+ │ ├── ProductWorldAnchor
144
+ │ │ └── ProductPlacementRig
145
+ │ │ └── ProductTransitionRig
146
+ │ │ └── ProductReactionRig
147
+ │ │ └── ProductIdleRig
148
+ │ │ └── ProductModel
149
+ │ │ ├── shell
150
+ │ │ ├── outerRing
151
+ │ │ ├── suspendedCore
152
+ │ │ ├── waveguide
153
+ │ │ └── named anchors
154
+ │ ├── InteriorRoot
155
+ │ │ ├── Tunnel
156
+ │ │ └── WaveRibbon
157
+ │ ├── RoomRoot
158
+ │ │ ├── RoomGeometry
159
+ │ │ ├── FieldContours
160
+ │ │ └── ListenerAnchor
161
+ │ └── AtmosphereRoot
162
+ │ ├── Particles
163
+ │ └── VolumetricAccents
164
+ ├── CameraPlacementRig
165
+ │ └── CameraNarrativeRig
166
+ │ └── CameraReactionRig
167
+ │ └── CameraShakeRig
168
+ │ └── PerspectiveCamera
169
+ ├── CameraTargetNarrativeRig
170
+ │ └── CameraTargetReactionRig
171
+ │ └── CameraTargetAnchor
172
+ ├── LightingRoot
173
+ │ ├── NarrativeLightingRig
174
+ │ ├── EnvironmentLightingRig
175
+ │ └── ReactiveAccentRig
176
+ └── Effects
177
+ ├── Bloom
178
+ ├── DepthOfField
179
+ ├── VelocityDisplacement
180
+ ├── ColorGrade
181
+ └── Grain
182
+ ```
183
+
184
+ ## 7. Shot presets
185
+
186
+ Values are starting points for tuning, not assumed final composition.
187
+
188
+ ### `arrivalSilhouette`
189
+
190
+ ```ts
191
+ {
192
+ camera: {
193
+ position: [0.00, 0.15, 6.20],
194
+ target: [0.00, 0.05, 0.00],
195
+ fov: 31,
196
+ roll: 0
197
+ },
198
+ subject: {
199
+ position: [0.40, -0.20, 0.00],
200
+ rotation: [0.02, -0.42, 0.00],
201
+ scale: 1.00
202
+ },
203
+ exposure: 0.72,
204
+ composition: 'Product sits right of centre; left side reserved for title. Ring silhouette is readable but inner construction remains dark.'
205
+ }
206
+ ```
207
+
208
+ ### `arrivalHero`
209
+
210
+ ```ts
211
+ {
212
+ camera: {
213
+ position: [0.10, 0.22, 4.90],
214
+ target: [0.14, 0.06, 0.00],
215
+ fov: 34,
216
+ roll: -0.008
217
+ },
218
+ subject: {
219
+ position: [0.34, -0.16, 0.00],
220
+ rotation: [0.03, -0.30, 0.01],
221
+ scale: 1.04
222
+ },
223
+ exposure: 1.00,
224
+ composition: 'Clear premium three-quarter hero; title still occupies left safe area.'
225
+ }
226
+ ```
227
+
228
+ ### `materialExploded`
229
+
230
+ ```ts
231
+ {
232
+ camera: {
233
+ position: [-0.52, 0.34, 4.15],
234
+ target: [0.12, 0.02, 0.00],
235
+ fov: 36,
236
+ roll: 0.006
237
+ },
238
+ subject: {
239
+ position: [0.18, -0.08, 0.00],
240
+ rotation: [0.02, -0.08, 0.00],
241
+ scale: 0.96
242
+ },
243
+ exposure: 1.08,
244
+ composition: 'Layer depth is readable; technical labels occupy right and lower-left safe regions.'
245
+ }
246
+ ```
247
+
248
+ ### `ringMacro`
249
+
250
+ ```ts
251
+ {
252
+ camera: {
253
+ position: [0.05, 0.08, 2.15],
254
+ target: [0.02, 0.02, 0.00],
255
+ fov: 29,
256
+ roll: 0
257
+ },
258
+ subject: {
259
+ position: [0.00, 0.00, 0.00],
260
+ rotation: [0.00, 0.00, 0.00],
261
+ scale: 1.18
262
+ },
263
+ exposure: 0.92,
264
+ composition: 'Ring aperture dominates the central safe area and supports full occlusion on continued dolly.'
265
+ }
266
+ ```
267
+
268
+ ### `interiorTravel`
269
+
270
+ ```ts
271
+ {
272
+ camera: {
273
+ position: [0.00, 0.00, 0.80],
274
+ target: [0.00, 0.00, -3.00],
275
+ fov: 47,
276
+ roll: -0.015
277
+ },
278
+ exposure: 0.82,
279
+ composition: 'Wave ribbon enters lower-left and leads to central vanishing point.'
280
+ }
281
+ ```
282
+
283
+ ### `roomEstablish`
284
+
285
+ ```ts
286
+ {
287
+ camera: {
288
+ position: [-3.20, 1.45, 5.80],
289
+ target: [0.20, 0.70, 0.00],
290
+ fov: 42,
291
+ roll: 0
292
+ },
293
+ exposure: 1.05,
294
+ composition: 'Room context is clear; product remains visible as the source of the field.'
295
+ }
296
+ ```
297
+
298
+ ### `finalResolve`
299
+
300
+ ```ts
301
+ {
302
+ camera: {
303
+ position: [0.00, 0.30, 5.20],
304
+ target: [0.00, 0.10, 0.00],
305
+ fov: 33,
306
+ roll: 0
307
+ },
308
+ subject: {
309
+ position: [0.00, -0.12, 0.00],
310
+ rotation: [0.02, 0.00, 0.00],
311
+ scale: 1.03
312
+ },
313
+ exposure: 0.96,
314
+ composition: 'Calm centered product; CTA sits below the ring without competing with the silhouette.'
315
+ }
316
+ ```
317
+
318
+ ## 8. Master timeline hierarchy
319
+
320
+ ```text
321
+ route:home
322
+ ├── preload
323
+ ├── intro
324
+ │ ├── darkness hold
325
+ │ ├── ring edge-light
326
+ │ ├── title entrance
327
+ │ └── scroll release
328
+ ├── narrative master
329
+ │ ├── chapter:arrival
330
+ │ ├── handoff:arrival-material
331
+ │ ├── chapter:material
332
+ │ ├── handoff:material-interior
333
+ │ ├── chapter:interior
334
+ │ ├── handoff:interior-field
335
+ │ ├── chapter:field
336
+ │ ├── handoff:field-resolve
337
+ │ └── chapter:resolve
338
+ ├── details
339
+ │ ├── material-detail-open
340
+ │ └── material-detail-close
341
+ └── route leave
342
+ ```
343
+
344
+ ## 9. Chapter specifications
345
+
346
+ ### Chapter `arrival`: Silent Object
347
+
348
+ **Narrative purpose:** establish restraint, silhouette, and premium material presence before explaining functionality.
349
+
350
+ **Incoming state:** black stage; product loaded in `arrivalSilhouette`; ring edge light at 8%; no scroll control until intro release.
351
+
352
+ **Outgoing state:** product in `arrivalHero`; outer ring edge is the brightest stable contour; the title has reduced to a small chapter marker; material chapter lighting is already present at 12%.
353
+
354
+ | Progress | Phase | Choreography |
355
+ |---:|---|---|
356
+ | 0.00-0.10 | pre-roll | Maintain near-darkness. Ambient material shimmer continues at very low amplitude. Scroll indicator becomes visible. |
357
+ | 0.10-0.28 | entrance | Dolly from `arrivalSilhouette` toward `arrivalHero`. Increase rim light from 0.08 to 0.62. Reveal title line 1 after camera has moved 35%. |
358
+ | 0.28-0.42 | establish | Camera movement decelerates. Reveal line 2 and product descriptor. Product rotation changes only 4 degrees to keep silhouette stable. |
359
+ | 0.42-0.64 | development | Increase fill light to reveal inner core. Pointer target influence fades from 0.00 to 0.035. Small SVG arc draws around 38% of ring circumference. |
360
+ | 0.64-0.78 | hold | Major motion stops. Copy is readable. Ambient wave faintly moves inside the product. |
361
+ | 0.78-0.90 | transformation | Title masks close toward the ring axis. Camera target shifts 6% right; product rotates toward a more analytical angle. |
362
+ | 0.90-1.00 | handoff prep | Material key light begins. SVG arc extends into the technical diagram axis. Outer ring remains the visual constant. |
363
+
364
+ **Cues:**
365
+
366
+ - `chapter:enter` 0.00
367
+ - `ring:readable` 0.18
368
+ - `title:primary` 0.28
369
+ - `product:hero` 0.42
370
+ - `copy:available` 0.52
371
+ - `handoff:armed` 0.82
372
+ - `chapter:resolved` 1.00
373
+
374
+ **Critical interval:** 0.78 to 1.00. Reduce pointer camera influence by 55% so the analytical framing lands reliably.
375
+
376
+ ### Handoff `arrival-material`
377
+
378
+ **Bridge:** SVG arc plus outer ring contour.
379
+
380
+ **Method:** screen-space line continuation and light bridge.
381
+
382
+ **Sequence:** The title exits along the same left-to-right axis as the SVG arc. The arc completes the ring contour, then extends into three technical callout lines. Material lighting begins before the product separates. The camera does not cut; it trucks left and slightly upward into `materialExploded`.
383
+
384
+ **Ownership:** `arrival` owns product placement until `handoff:armed`; handoff owns camera, product placement, SVG arc, and lighting until the material hero pose; `material` then owns layer separation.
385
+
386
+ **Completion:** callout lines are stable, the camera is in the material establishing shot, and the complete product remains assembled at material local progress `0`.
387
+
388
+ ### Chapter `material`: Built to Shape
389
+
390
+ **Narrative purpose:** convert sculptural mystery into mechanical clarity.
391
+
392
+ **Incoming state:** complete product in analytical three-quarter view; technical lines available; material lighting active.
393
+
394
+ **Outgoing state:** outer ring aligned to camera and centered; shell and core receded; title reduced to the single word “Inside”; interior scene rendered behind the aperture.
395
+
396
+ | Progress | Phase | Choreography |
397
+ |---:|---|---|
398
+ | 0.00-0.12 | establish | Hold complete object. Draw final 12% of technical lines. Reveal material label. |
399
+ | 0.12-0.36 | separation | Separate shell, ring, suspension, and core along authored local axes with 60 ms overlap. Truck camera slightly to preserve readable depth. |
400
+ | 0.36-0.58 | development | Reveal one feature statement per layer. Labels enter from their anchor direction rather than a common vertical fade. Pointer provides limited depth response. |
401
+ | 0.58-0.70 | hold | Major transforms pause. Let the suspended core continue a small follow-through and settle. |
402
+ | 0.70-0.82 | transformation | Non-ring layers rotate edge-on and recede. Ring moves toward screen centre. Copy collapses to “Inside.” |
403
+ | 0.82-1.00 | handoff | Align ring normal to camera, tighten FOV, and begin interior render behind the aperture. |
404
+
405
+ **Layer timing:** shell begins first, suspension follows 0.05 progress later, core follows 0.10 later. The ring initially remains stable to preserve orientation.
406
+
407
+ **Interaction envelope:** 0.32 to 0.70. Hovering labels may increase the associated layer scale by at most 2.5% through a child reaction rig. Disable label interaction after 0.70.
408
+
409
+ ### Handoff `material-interior`
410
+
411
+ **Bridge:** outer ring aperture.
412
+
413
+ **Progress window:** global 0.40 to 0.49.
414
+
415
+ **Outgoing final state:** ring screen center `[0.50, 0.50]`; apparent outer diameter `1.16 × viewport short edge`; yaw within 0.5 degrees of camera normal; camera shot `ringMacro`.
416
+
417
+ **Incoming initial state:** tunnel entrance plane aligned with the ring aperture; camera position and target match the outgoing pose; interior light at 15%; wave ribbon visible at 8% opacity.
418
+
419
+ **Choreography:**
420
+
421
+ 1. At handoff 0.00, pointer camera influence becomes `0.008`.
422
+ 2. At 0.12, begin dolly and reduce FOV from 34 to 29.
423
+ 3. At 0.24, activate render-target interior behind the aperture.
424
+ 4. At 0.45, move the word “Inside” to the tunnel vanishing axis and reduce it to a thin outline.
425
+ 5. At 0.68, ring coverage exceeds 95% of the central safe area.
426
+ 6. At 0.72, hide outgoing shell and core under full cover.
427
+ 7. At 0.76, transfer camera target ownership to the tunnel target rig.
428
+ 8. At 0.82, morph the SVG ring outline into the wave ribbon origin.
429
+ 9. At 1.00, pointer strength resolves to `0.022`; interior chapter local progress is 0.
430
+
431
+ **Reverse:** outgoing product layers stay mounted until global progress exceeds 0.55. Visibility and render blend derive from progress. No one-time callbacks destroy state.
432
+
433
+ ### Chapter `interior`: Inside the Wave
434
+
435
+ **Narrative purpose:** let the viewer experience the waveguide as a spatial system rather than a diagram.
436
+
437
+ **Incoming state:** camera just inside tunnel; wave ribbon begins at aperture; low light and central vanishing point.
438
+
439
+ **Outgoing state:** ribbon expands beyond tunnel geometry; the camera reaches the tunnel exit; room color temperature is already visible beyond.
440
+
441
+ | Progress | Phase | Choreography |
442
+ |---:|---|---|
443
+ | 0.00-0.14 | entrance | Move slowly into tunnel; reveal wave ribbon from 0 to 32% with DrawSVG-like spatial equivalent. |
444
+ | 0.14-0.38 | development | Ribbon alternates between compression and expansion zones. Small copy labels attach to stable tunnel anchors. |
445
+ | 0.38-0.54 | hold | Camera travel slows by 65%. Viewer can read the waveguide explanation. Ambient wave continues. |
446
+ | 0.54-0.74 | transformation | Wave ribbon amplitude increases and tunnel ribs react sequentially. Velocity effect is clamped to preserve legibility. |
447
+ | 0.74-0.88 | apex | Camera accelerates moderately; FOV widens from 44 to 49; incoming room light blooms beyond the tunnel exit. |
448
+ | 0.88-1.00 | handoff prep | Ribbon leaves tunnel constraints and becomes a broad contour. Camera target moves to the listener anchor in the room. |
449
+
450
+ **Camera path:** cubic path with three authored points. Target path is separate and leads by 4 to 7% of chapter progress.
451
+
452
+ **Roll:** maximum `-0.018` radians and resolves to zero before room reveal.
453
+
454
+ **Critical interval:** 0.72 to 0.94. Disable pointer camera rotation and use pointer only for low-amplitude ribbon displacement.
455
+
456
+ ### Handoff `interior-field`
457
+
458
+ **Bridge:** wave ribbon.
459
+
460
+ **Method:** spatial carry plus vector-role transformation.
461
+
462
+ The tunnel exit becomes a room window under bright cover. The ribbon continues in the same screen-space direction, expands laterally, and becomes the first room-field contour. The room is visible before the tunnel ribs dissolve. The camera target shifts to the listener anchor while the camera completes its forward motion and then cranes upward into `roomEstablish`.
463
+
464
+ **Completion:** room geometry is authoritative, tunnel ribs are fully hidden, ribbon contour belongs to the room field system, camera roll is zero, and field chapter local progress is 0.
465
+
466
+ ### Chapter `field`: The Room Responds
467
+
468
+ **Narrative purpose:** demonstrate adaptive room-scale behavior while maintaining the product as the field source.
469
+
470
+ **Incoming state:** room establishing shot; product visible at left-midground; first field contour crosses the listener anchor.
471
+
472
+ **Outgoing state:** contours converge toward product and listener; room geometry reduces; product returns toward centered final presentation.
473
+
474
+ | Progress | Phase | Choreography |
475
+ |---:|---|---|
476
+ | 0.00-0.18 | establish | Crane into room shot. Keep first contour stable long enough to establish scale. |
477
+ | 0.18-0.42 | development | Emit three contour families from the product. Each responds to room surfaces and listener position. Reveal concise statements at stable screen regions. |
478
+ | 0.42-0.62 | interaction hold | Allow pointer to move the listener anchor within a constrained zone. Field contours respond; camera remains largely stable. |
479
+ | 0.62-0.78 | transformation | Return listener anchor to authored position. Room surfaces dim and contour lines intensify. |
480
+ | 0.78-0.90 | handoff prep | Contours contract toward the product ring. Camera begins moving toward `finalResolve`. |
481
+ | 0.90-1.00 | handoff | Room becomes a dark field; the final contour aligns with the product ring and morphs into its edge light. |
482
+
483
+ **Interaction envelope:** pointer controls listener anchor only from 0.42 to 0.62. On touch, a short drag interaction is available within the same range with a visible “move the listening point” instruction. Keyboard controls move the point in four directions.
484
+
485
+ ### Handoff `field-resolve`
486
+
487
+ **Bridge:** field contour becomes ring edge light.
488
+
489
+ **Method:** vector morph, spatial contraction, and camera match.
490
+
491
+ The final room contour contracts toward the product and becomes circular. MorphSVG controls the DOM/SVG overlay while the WebGL contour follows a matched proxy progress. At 72% coverage, room surfaces are fully dark. The product has already returned to complete form under the field lines. Camera reaches the final centered shot as the contour aligns to the ring.
492
+
493
+ **Reverse:** room remains mounted and dark until progress is below 0.18. Contours expand from the ring without a pop.
494
+
495
+ ### Chapter `resolve`: A Quiet Centre
496
+
497
+ **Narrative purpose:** release intensity, restore agency, and present the final action.
498
+
499
+ **Incoming state:** complete product centered; ring edge light linked to final contour; dark calm environment.
500
+
501
+ **Outgoing state:** CTA route transition state or stable idle.
502
+
503
+ | Progress | Phase | Choreography |
504
+ |---:|---|---|
505
+ | 0.00-0.18 | resolution | Camera settles the final 3% after field contraction. Ambient sound and particles reduce. |
506
+ | 0.18-0.38 | copy entrance | Reveal final statement by two lines with restrained masks. No large translation. |
507
+ | 0.38-0.58 | CTA entrance | CTA and product details become interactive. Ring responds subtly to pointer proximity. |
508
+ | 0.58-1.00 | stable explore | Preserve a calm final state. Scroll can continue into semantic footer content without changing the product pose. |
509
+
510
+ **CTA transition:** clicking “Explore Aether One” expands the ring edge into a route cover, freezes narrative input, prefetches the destination, and transfers to the product route under full cover.
511
+
512
+ ## 10. Semantic cue map
513
+
514
+ | Cue | Meaning | Responding systems |
515
+ |---|---|---|
516
+ | `intro:ring-edge` | First visible product contour | rim light, title pre-roll, ambient sound |
517
+ | `arrival:hero` | Product is fully legible | camera, copy, pointer envelope |
518
+ | `material:separate` | Mechanical explanation begins | layer rigs, labels, SVG callouts |
519
+ | `material:hold` | Reading state | camera hold, label interaction |
520
+ | `portal:armed` | Ring is prepared as aperture | interaction gate, interior preload, camera target |
521
+ | `portal:covered` | Outgoing swap is safe | scene visibility, environment ownership |
522
+ | `interior:apex` | Maximum spatial intensity | wave amplitude, FOV, velocity effect |
523
+ | `room:available` | Listener interaction can begin | pointer/drag/keyboard controls |
524
+ | `field:contract` | Resolution begins | contours, room lighting, camera move |
525
+ | `resolve:interactive` | CTA and details enabled | Motion UI, focus, route prefetch |
526
+
527
+ ## 11. Responsive direction
528
+
529
+ ### Desktop wide
530
+
531
+ Use full lateral composition, stronger room depth, and technical labels distributed around the product. Cap pointer camera yaw at `0.055` outside critical intervals.
532
+
533
+ ### Laptop and tablet
534
+
535
+ Reduce camera truck distances by 20 to 30%. Keep labels closer to their anchors. Reduce tunnel FOV apex by 3 degrees. Use fewer room contour families.
536
+
537
+ ### Mobile portrait
538
+
539
+ - Product remains near center rather than right-aligned in `arrival`.
540
+ - Title occupies top and lower regions rather than a single left column.
541
+ - Material layers separate vertically and slightly in depth instead of broadly horizontally.
542
+ - Ring portal scale increases by 18% and camera lateral offsets are removed.
543
+ - Interior travel is shorter and roll is disabled.
544
+ - Room chapter uses a simplified abstract field rather than full room geometry on safe tier.
545
+ - Listener interaction uses a visible drag area and can be skipped.
546
+ - Final CTA remains in normal DOM flow below the stage if viewport height is limited.
547
+
548
+ ### Reduced motion
549
+
550
+ - Replace the fast portal dolly with a matched ring scale and short masked dissolve.
551
+ - Disable camera roll, velocity displacement, camera shake, and large parallax.
552
+ - Use three key camera poses with shorter interpolation.
553
+ - Preserve the ring, wave, and contour bridge concepts.
554
+ - Keep ambient motion low and optional.
555
+ - Type reveals through opacity and small clipping changes rather than large travel.
556
+
557
+ ## 12. Performance tiers
558
+
559
+ ### High
560
+
561
+ Full room geometry, depth of field, higher contour count, dynamic rim shadows, DPR cap 2.
562
+
563
+ ### Balanced
564
+
565
+ Reduced room detail, selective bloom and color grade, moderate particles, DPR cap 1.5.
566
+
567
+ ### Safe
568
+
569
+ Simplified room planes, no depth of field, low contour count, baked lighting, DPR cap 1.15, portal transition uses a mask without dual full-resolution render targets.
570
+
571
+ ## 13. Implementation plan
572
+
573
+ ### Slice 1: Foundation and arrival
574
+
575
+ - persistent DOM stage and semantic scroll regions,
576
+ - Lenis and ScrollTrigger integration,
577
+ - experience runtime and target registry,
578
+ - camera and product rigs,
579
+ - `arrival` timeline,
580
+ - shot capture controls,
581
+ - responsive `arrival` shots.
582
+
583
+ ### Slice 2: Material and first handoff
584
+
585
+ - model layer registry and anchors,
586
+ - technical SVG overlay,
587
+ - material chapter timeline,
588
+ - label interaction envelope,
589
+ - `arrival-material` handoff,
590
+ - reverse validation.
591
+
592
+ ### Slice 3: Portal proof
593
+
594
+ - ring alignment,
595
+ - interior render strategy,
596
+ - cover measurement,
597
+ - camera target transfer,
598
+ - `material-interior` handoff,
599
+ - mobile and safe-tier alternative.
600
+
601
+ This is the architectural proof. Do not build the full tunnel before the portal is reliable.
602
+
603
+ ### Slice 4: Interior and field
604
+
605
+ - tunnel and wave systems,
606
+ - camera and target paths,
607
+ - velocity channels,
608
+ - room preloading,
609
+ - interior-field handoff,
610
+ - listener interaction.
611
+
612
+ ### Slice 5: Resolution and routes
613
+
614
+ - field contraction,
615
+ - final product pose,
616
+ - CTA presence,
617
+ - route cover and cleanup,
618
+ - footer flow.
619
+
620
+ ### Slice 6: Quality pass
621
+
622
+ - reduced motion,
623
+ - performance tiers,
624
+ - accessibility and keyboard flow,
625
+ - responsive choreography,
626
+ - recordings and rubric audit,
627
+ - final microtiming and sound synchronization.
628
+
629
+ ## 14. Tuning register
630
+
631
+ Priority values:
632
+
633
+ ```ts
634
+ export const aetherDirection = {
635
+ arrival: {
636
+ scrollVh: 2.2,
637
+ titleStart: 0.18,
638
+ heroSettle: 0.42,
639
+ holdStart: 0.64,
640
+ handoffStart: 0.82,
641
+ pointerMax: 0.035,
642
+ },
643
+ material: {
644
+ scrollVh: 3.4,
645
+ separationStart: 0.12,
646
+ separationEnd: 0.36,
647
+ labelHoldEnd: 0.70,
648
+ ringAlignStart: 0.78,
649
+ layerDepth: 0.72,
650
+ },
651
+ portal: {
652
+ pointerMin: 0.008,
653
+ interiorVisible: 0.24,
654
+ safeCoverage: 0.68,
655
+ sceneTransfer: 0.72,
656
+ targetTransfer: 0.76,
657
+ },
658
+ interior: {
659
+ scrollVh: 4.0,
660
+ holdStart: 0.38,
661
+ holdEnd: 0.54,
662
+ apexStart: 0.74,
663
+ fovApex: 49,
664
+ },
665
+ field: {
666
+ scrollVh: 3.8,
667
+ interactionStart: 0.42,
668
+ interactionEnd: 0.62,
669
+ contractionStart: 0.78,
670
+ },
671
+ };
672
+ ```
673
+
674
+ ## 15. Acceptance criteria
675
+
676
+ The experience passes when:
677
+
678
+ 1. The outer ring remains a recognizable continuity device across all five chapters.
679
+ 2. Every chapter has a stable, readable key pose.
680
+ 3. The portal handoff exposes no invalid frame on desktop, mobile, or reverse scrub.
681
+ 4. Pointer movement cannot alter the final narrative rig values.
682
+ 5. The product and camera land on the same poses after slow, fast, and reversed scroll.
683
+ 6. Copy remains readable during documented holds.
684
+ 7. Mobile uses separately authored shots and portal coverage.
685
+ 8. Reduced motion preserves all required content and transition logic without large tunnel travel.
686
+ 9. Balanced tier sustains the documented target frame behavior on representative devices.
687
+ 10. Route leave removes all triggers, ticker callbacks, listeners, and route-specific GPU resources.