@struq/skill 0.0.0-stage → 0.2.1

package/skills/struq/cinematic/references/06-three-rig-architecture.md

@@ -0,0 +1,286 @@
+# Three.js and React Three Fiber Rig Architecture
+
+## Why rigs matter
+
+Rigs turn transform conflicts into explicit composition. A rig is simply a parent `Object3D` or `Group` created to own one category of motion.
+
+Without rigs:
+
+```text
+GSAP writes camera.position
+pointer handler writes camera.position
+noise loop writes camera.position
+route transition writes camera.position
+```
+
+With rigs:
+
+```text
+cameraPlacementRig          ← route or viewport placement
+└── cameraNarrativeRig      ← chapter and handoff timelines
+    └── cameraReactionRig   ← pointer and velocity modulation
+        └── cameraShakeRig  ← procedural noise
+            └── camera
+```
+
+The final transform is composed by the scene graph.
+
+## Suggested camera hierarchy
+
+```tsx
+<group ref={placementRig}>
+  <group ref={narrativeRig}>
+    <group ref={reactionRig}>
+      <group ref={shakeRig}>
+        <PerspectiveCamera ref={camera} makeDefault />
+      </group>
+    </group>
+  </group>
+  <object3D ref={targetRig} />
+</group>
+```
+
+The target may have its own narrative and reactive hierarchy if needed.
+
+```text
+targetNarrativeRig
+└── targetReactionRig
+    └── targetAnchor
+```
+
+During each frame, orient the physical camera toward the resolved target anchor. If roll is used, apply it after look-at orientation through a roll rig or quaternion composition.
+
+## Suggested subject hierarchy
+
+```text
+subjectWorldAnchor
+└── subjectPlacementRig      ← chapter composition
+    └── subjectTransitionRig ← handoff ownership
+        └── subjectReactionRig
+            └── subjectIdleRig
+                └── modelRoot
+```
+
+Not every project needs every rig. Add a rig only when a distinct system must own a transform channel.
+
+## Named anchors
+
+Create anchors inside or around the model:
+
+```text
+productRoot
+├── anchor:center
+├── anchor:lens
+├── anchor:logo
+├── anchor:detailA
+├── anchor:portalPlane
+└── anchor:cameraTarget
+```
+
+Anchors support:
+
+- shot targeting,
+- DOM labels aligned to 3D,
+- transition portals,
+- particle emitters,
+- lighting attachment,
+- screen-space measurements,
+- authored motion paths.
+
+Prefer anchors exported from the 3D file or created in a model setup module instead of repeated magic coordinates.
+
+## Camera shot application
+
+A shot contains target values. Apply it to narrative rigs, not reactive rigs.
+
+```ts
+function addShotTween(
+  tl: gsap.core.Timeline,
+  rig: THREE.Group,
+  target: THREE.Object3D,
+  camera: THREE.PerspectiveCamera,
+  shot: ShotPreset,
+  position: gsap.Position,
+  duration: number,
+) {
+  tl.to(rig.position, {
+    x: shot.camera.position[0],
+    y: shot.camera.position[1],
+    z: shot.camera.position[2],
+    duration,
+    ease: shot.ease ?? 'power2.inOut',
+  }, position);
+
+  tl.to(target.position, {
+    x: shot.camera.target[0],
+    y: shot.camera.target[1],
+    z: shot.camera.target[2],
+    duration,
+    ease: shot.targetEase ?? shot.ease ?? 'power2.inOut',
+  }, position);
+
+  tl.to(camera, {
+    fov: shot.camera.fov,
+    duration,
+    ease: shot.fovEase ?? 'power1.inOut',
+    onUpdate: () => camera.updateProjectionMatrix(),
+  }, position);
+}
+```
+
+For performance, avoid creating new vectors every frame. Reuse temporary objects.
+
+## Frame composition
+
+`useFrame` is suitable for high-frequency visual composition inside the Canvas.
+
+```tsx
+useFrame((state, delta) => {
+  const runtime = runtimeRef.current;
+
+  reactionRig.current.rotation.y = damp(
+    reactionRig.current.rotation.y,
+    runtime.pointer.x * direction.pointerYaw,
+    direction.pointerDamping,
+    delta,
+  );
+
+  shakeRig.current.position.y =
+    Math.sin(state.clock.elapsedTime * 0.7) * direction.idleFloat;
+
+  camera.current.lookAt(targetAnchor.current.getWorldPosition(tempTarget));
+});
+```
+
+GSAP owns narrative rig values. `useFrame` owns reaction, ambient motion, and final camera look-at resolution.
+
+`useFrame` runs on the single clock: the canvas is mounted with `frameloop="never"` and advanced from `gsap.ticker` (see [`07-stack-integration.md`](07-stack-integration.md) and [`../examples/code/shared/GsapFrameLoop.tsx`](../examples/code/shared/GsapFrameLoop.tsx)). Because scroll, timelines and rendering share one ticker, there is no separate render loop that can drift out of step with the narrative values `useFrame` reads.
+
+## Animating Three.js with GSAP
+
+GSAP can tween numeric object properties directly:
+
+```js
+gsap.to(group.rotation, { y: Math.PI * 0.75, duration: 1 });
+gsap.to(material, { opacity: 0.2, duration: 0.4 });
+gsap.to(uniforms.uProgress, { value: 1, duration: 1 });
+```
+
+Use proxy objects when:
+
+- several final values must be composed,
+- a uniform requires clamping or transformation,
+- a timeline should remain decoupled from a material instance,
+- responsive variants share the same logical channel.
+
+```ts
+const channels = {
+  narrativeDistortion: 0,
+  velocityDistortion: 0,
+};
+
+gsap.to(channels, { narrativeDistortion: 0.7 });
+
+useFrame(() => {
+  material.uniforms.uDistortion.value = Math.min(
+    1,
+    channels.narrativeDistortion + Math.abs(channels.velocityDistortion),
+  );
+});
+```
+
+## Reparenting and continuity
+
+When a bridge object must move between rigs, preserve world transform.
+
+Three.js `Object3D.attach()` can reparent while preserving world transform when the hierarchy has compatible scale assumptions. Test carefully when non-uniform scale exists.
+
+Alternative:
+
+1. read world position, quaternion, and scale,
+2. reparent,
+3. convert world transform into the new parent's local space,
+4. apply values,
+5. continue the timeline from that local state.
+
+Document the coordinate-space requirement in the handoff contract.
+
+## DOM-to-WebGL alignment
+
+For labels, masks, or shared transitions, convert world positions to normalized device coordinates and then screen pixels.
+
+```ts
+worldPosition.project(camera);
+const x = (worldPosition.x * 0.5 + 0.5) * viewportWidth;
+const y = (-worldPosition.y * 0.5 + 0.5) * viewportHeight;
+```
+
+Consider:
+
+- device pixel ratio,
+- DOM scroll transforms,
+- canvas bounds,
+- perspective scale,
+- visibility behind the camera,
+- occlusion,
+- responsive safe areas.
+
+Do not update React state every frame solely to position a DOM label. Write to a CSS transform through a ref or use an established HTML-in-3D helper when appropriate.
+
+## Scene strategy
+
+### One persistent scene
+Best for a unified product or world with continuous lighting and camera behavior.
+
+### Multiple scene roots in one scene
+Toggle or blend environment groups while sharing a camera and effects pipeline.
+
+### Multiple scenes with render targets
+Best for portals, compositing, cross-scene displacement, or radically different render settings.
+
+### Route-specific canvases
+Best when routes are independently immersive and route transition continuity can be handled outside the canvas or through snapshots.
+
+Choose the least complex strategy that supports the handoff language.
+
+## Lighting rigs
+
+Separate lighting responsibilities:
+
+```text
+lightingRoot
+├── narrativeLightingRig
+│   ├── key
+│   ├── fill
+│   └── rim
+├── environmentLightingRig
+└── reactiveAccentLights
+```
+
+Animate intensity, color, position, and environment contribution through named lighting states. Avoid changing every light independently without a state plan.
+
+## Effects ownership
+
+Post-processing should support narrative state:
+
+- bloom increases at a reveal apex,
+- depth of field shifts during rack focus,
+- chromatic displacement responds briefly to velocity,
+- vignette increases before a portal pass,
+- grain remains ambient and stable,
+- color grading transitions between chapter moods.
+
+Create effect channels rather than allowing each chapter to instantiate its own independent composer.
+
+## Performance rules
+
+- Reuse geometries and materials where possible.
+- Avoid mounting and unmounting large model trees during a visible handoff.
+- Preload assets needed by the next transition.
+- Limit transparent particle overdraw.
+- Use instancing for repeated geometry.
+- Avoid React state updates in `useFrame`.
+- Reuse vectors, matrices, and quaternions.
+- Scale DPR and post-processing by performance tier.
+- Dispose custom resources on unmount.
+- Profile actual target devices.

package/skills/struq/cinematic/references/07-stack-integration.md

@@ -0,0 +1,228 @@
+# Stack Integration
+
+## Responsibility map
+
+The stack is strongest when each tool has a clear job.
+
+| Tool | Primary responsibility | Avoid |
+|---|---|---|
+| Next.js / Vite | application shell, bundling, routing, asset delivery | embedding choreography logic in route files |
+| React | lifecycle, composition, semantic state | high-frequency visual state updates every frame |
+| React Three Fiber | Three.js scene graph and frame composition | forcing all scene changes through React re-renders |
+| GSAP | authored sequences and property interpolation | becoming an unstructured global mutation layer |
+| ScrollTrigger | mapping scroll ranges to timeline progress | treating each section as an isolated animation by default |
+| Lenis | smoothing and normalizing physical scroll | controlling narrative state independently of ScrollTrigger |
+| Motion for React | local presence, layout, gestures, UI state | controlling the same transform as GSAP |
+| SVG GSAP plugins | vector drawing, morphing, path movement | using incompatible paths without shape preparation |
+
+## Next.js guidance
+
+Place browser-dependent experience systems behind a client boundary.
+
+```tsx
+'use client';
+```
+
+Register GSAP plugins in a client-side module. Build timelines after refs and WebGL targets are ready. Route transitions must account for App Router mounting behavior and must kill route-specific timelines and ScrollTriggers.
+
+For a large canvas, consider dynamically loading the experience component with server-side rendering disabled when that improves reliability. Preserve semantic content and fallback output outside the canvas.
+
+Do not put mutable Three.js objects into server components or serialize them through props.
+
+## Vite guidance
+
+Vite has fewer server/client boundaries. Keep the same lifecycle discipline:
+
+- register plugins once,
+- create timelines inside scoped hooks,
+- remove ticker callbacks,
+- kill ScrollTriggers,
+- dispose route-specific scene resources,
+- refresh measurements after fonts and assets are ready.
+
+## GSAP in React
+
+Use the official React integration or scoped GSAP context so animation and ScrollTrigger instances revert on cleanup.
+
+Conceptual pattern:
+
+```tsx
+const root = useRef<HTMLDivElement>(null);
+
+useGSAP(() => {
+  const tl = gsap.timeline();
+  // Build scoped timelines and ScrollTriggers.
+
+  return () => {
+    // Additional cleanup not handled by context.
+  };
+}, { scope: root, dependencies: [isReady] });
+```
+
+Do not rebuild expensive timelines on every React render. Keep direction objects stable and recreate only when relevant responsive or asset-readiness conditions change.
+
+## Lenis and ScrollTrigger
+
+Use one Lenis instance for the root scroll unless the design intentionally uses a custom scroll container.
+
+Key integration responsibilities:
+
+- Lenis emits scroll updates to ScrollTrigger.
+- Lenis is advanced from a controlled animation ticker.
+- ScrollTrigger refreshes after layout-affecting assets are ready.
+- Lenis is stopped during states that require scroll lock.
+- native nested scrolling is handled deliberately.
+
+Lenis must be created with `autoRaf: false`. If it keeps its own animation loop it becomes a second clock next to `gsap.ticker`, and scroll, ScrollTrigger and the canvas drift apart by a frame. The canonical setup lives in [`../../references/setup.md`](../../references/setup.md); this is the conceptual shape.
+
+Conceptual setup:
+
+```tsx
+// ScrollTrigger sync: useLenis subscribes once the root instance exists.
+// Never capture lenisRef.current?.lenis once in an effect; on first mount it
+// is often still undefined, and the listener is silently never bound.
+useLenis(() => ScrollTrigger.update());
+
+useEffect(() => {
+  // Registered unconditionally, instance resolved per frame.
+  const update = (time: number) => {
+    lenisRef.current?.lenis?.raf(time * 1000);
+  };
+
+  gsap.ticker.add(update);
+  gsap.ticker.lagSmoothing(0);
+
+  return () => {
+    gsap.ticker.remove(update);
+  };
+}, []);
+```
+
+Do not add CSS `scroll-behavior: smooth` on top of Lenis.
+
+## R3F frame-loop options
+
+The single-clock rule applies: the canvas is rendered from `gsap.ticker`, the same callback chain that advances Lenis. The exact bridge is documented in [`../../references/webgl-r3f.md`](../../references/webgl-r3f.md) and shown in [`../examples/code/shared/GsapFrameLoop.tsx`](../examples/code/shared/GsapFrameLoop.tsx).
+
+### Ticker-driven loop (default)
+
+Mount the canvas with `frameloop="never"` and call `advance()` from a `gsap.ticker` callback. `useFrame` still runs, once per ticker tick, so ambient and reactive layers keep working, and GSAP tweens of Three.js objects land in the frame they were written.
+
+Use when ambient animation is always active, which is the normal case for a directed experience.
+
+Advantages:
+
+- one clock for scroll, timelines and rendering,
+- no drift between ScrollTrigger measurements and the rendered frame,
+- `useFrame` reads narrative values from the same tick that produced them, with no separate render loop to run ahead or behind.
+
+### Demand loop with invalidation
+
+Use only when the scene changes solely with scroll or pointer and has no ambient animation, so it can sit idle (power efficiency matters).
+
+Mount the canvas with `frameloop="demand"` and call `invalidate()` from the things that change it (a ScrollTrigger `onUpdate`, a pointer handler, a uniform setter). R3F then renders on demand without a continuous loop of its own. A directed experience with ambient shaders, particles or model idles is not this case, so use the ticker-driven loop instead.
+
+### Fully coordinated manual loop
+
+Use only when exact render ordering or multi-scene compositing requires it. This is more complex and should be justified by the transition design. It still advances from the one ticker.
+
+Do not leave the canvas on R3F's default `frameloop="always"` next to a Lenis ticker. R3F then runs its own `requestAnimationFrame` loop, which is a second clock.
+
+## Motion for React boundaries
+
+Use Motion for:
+
+- menus,
+- route-level interface shells,
+- local hover and press states,
+- layout transitions,
+- presence and exit behavior,
+- interface controls,
+- non-central content transitions.
+
+Use GSAP for:
+
+- the central chapter sequence,
+- camera and WebGL choreography,
+- multi-element timeline relationships,
+- scroll-scrubbed sequences,
+- SVG path drawing and morphing,
+- branded typography direction.
+
+The split that keeps the two libraries from colliding: GSAP owns scroll-linked and chapter-timeline motion, Motion owns React-lifecycle motion (mount, unmount, presence, layout, UI state). Motion never reads scroll progress for the central narrative.
+
+If a Motion component must participate in a GSAP sequence, let GSAP own a wrapper and Motion own an inner element or vice versa. Never animate the same CSS transform layer from both systems.
+
+## SplitText lifecycle
+
+Typography layout can change after fonts load or the viewport changes. The text system must account for re-splitting.
+
+Define:
+
+- split mode,
+- overflow masks,
+- accessibility output,
+- font-readiness condition,
+- resize behavior,
+- timeline rebuild or rebind behavior,
+- cleanup and revert.
+
+Do not cache line elements across a re-split without updating the timeline targets.
+
+## ScrollTrigger architecture
+
+Use ScrollTrigger to define input ranges, not the full conceptual architecture.
+
+Preferred patterns:
+
+### One long persistent-stage trigger
+
+A master timeline maps the complete scroll narrative.
+
+Best when the route is a highly integrated continuous experience.
+
+### Chapter triggers within one persistent stage
+
+Each chapter has a trigger and local timeline while the visual stage remains fixed.
+
+Best when chapters need separate activation and easier tuning.
+
+### Mixed pinned and flowing content
+
+Some chapters control the persistent stage while semantic content can flow normally between immersive sequences.
+
+Best when readability and editorial depth matter.
+
+Avoid nested pinning unless it is carefully tested. Pin spacing and measurement changes can easily create fragile layouts.
+
+## Refresh and resize sequence
+
+After a meaningful responsive or asset change:
+
+1. update viewport classification,
+2. apply responsive direction data,
+3. update camera projection and renderer size,
+4. re-split typography if required,
+5. rebuild affected timelines,
+6. refresh ScrollTrigger measurements,
+7. restore or remap progress,
+8. validate the active state.
+
+Debounce expensive rebuilds, but do not leave stale measurements.
+
+## Route transitions
+
+A professional route transition defines:
+
+- click intent,
+- interaction lock,
+- leave timeline,
+- destination asset prefetch,
+- scroll state handling,
+- history behavior,
+- transition cover,
+- destination ready condition,
+- enter timeline,
+- cleanup and unlock.
+
+Do not begin navigation before the transition system has captured or covered the current visual state if continuity depends on it.