@struq/skill 0.0.0-stage → 0.2.1

package/skills/struq/cinematic/references/08-gsap-plugin-patterns.md

@@ -0,0 +1,218 @@
+# GSAP Plugin Patterns
+
+This reference assigns each plugin a clear role inside a cinematic experience. Use plugins because they solve a transition or direction problem, not because they are available.
+
+## ScrollTrigger
+
+Use for:
+
+- chapter progress mapping,
+- persistent-stage pin ranges,
+- activation and deactivation,
+- velocity and direction signals,
+- scroll labels and debug markers,
+- optional snapping.
+
+Direction questions:
+
+- What is the scroll-distance budget?
+- Is the stage pinned once or per chapter?
+- What happens before and after the range?
+- Is the timeline fully scrubbed or partly state-based?
+- What must happen in reverse?
+- When are measurements refreshed?
+
+Avoid creating one trigger for every small element when a chapter timeline can coordinate them.
+
+## SplitText
+
+Use for:
+
+- line, word, and character choreography,
+- masked editorial reveals,
+- directional reading order,
+- typographic bridges,
+- reflow-aware text sequences.
+
+Direction schema:
+
+```text
+split unit: lines
+mask: overflow hidden per line
+origin: bottom
+order: document order
+stagger: 70 ms
+relationship: begins when camera move reaches 65%
+resolve: final line settles 120 ms after key light
+responsive: mobile splits by words, not lines
+```
+
+Keep accessible original text available and revert split markup during cleanup.
+
+## DrawSVGPlugin
+
+Use for:
+
+- technical drawing reveals,
+- paths that guide the camera or eye,
+- diagrams and annotations,
+- vector bridge elements,
+- line accents tied to chapter beats.
+
+Direction schema:
+
+```text
+path role: bridge from product outline to tunnel axis
+start: 0% drawn
+entrance: draw 0 to 58% during establish
+hold: preserve 58% while copy is readable
+handoff: complete draw and move highlight along the final 42%
+reverse: exact scrub reversal
+```
+
+Prepare paths carefully. Multi-segment paths may need to be separated for predictable drawing.
+
+## MorphSVGPlugin
+
+Use for:
+
+- icon-to-object transitions,
+- typography-to-symbol bridges,
+- mask deformation,
+- portal shape transitions,
+- vector states that preserve conceptual identity.
+
+Direction questions:
+
+- Are source and target paths semantically related?
+- Should the form rotate, scale, or move during the morph?
+- Which contour point should visually remain anchored?
+- Is the morph a primary beat or a transition cover?
+- Does the shape remain valid on mobile?
+
+Prepare source and target paths to reduce unexpected point correspondence. Break complex forms into multiple paths when needed.
+
+## MotionPathPlugin
+
+Use for:
+
+- camera or object travel along authored curves,
+- particles following a visual axis,
+- interface elements attached to a path,
+- spatial carry through a transition.
+
+Separate path progress from auto-rotation when direction must be art-directed. A camera path should also define target behavior and FOV.
+
+## Flip
+
+Use for:
+
+- moving an element between DOM layouts while preserving visual continuity,
+- grid-to-detail transitions,
+- navigation and overlay expansion,
+- shared-element route transitions.
+
+A FLIP transition is a state-layout bridge. It does not replace the chapter state model. Define which wrapper GSAP owns and keep Motion layout animation off that same layer.
+
+## Observer
+
+Use for:
+
+- wheel or touch gestures that advance discrete chapters,
+- controlled full-screen state experiences,
+- drag and swipe intent,
+- gesture locking,
+- pausing native scroll during an immersive mode (stop Lenis with `lenis.stop()` and resume it on exit).
+
+Define thresholds, cooldowns, reversibility, focus behavior, keyboard alternatives, and escape conditions. Do not trap the user without an accessible navigation path.
+
+## ScrollToPlugin
+
+Use for:
+
+- explicit chapter navigation,
+- restoring a progress location,
+- menu links into an immersive sequence,
+- guided demos.
+
+With Lenis active, `lenis.scrollTo()` is the one authoritative scroll command path. Do not tween the root scroller with ScrollToPlugin at the same time, or two scroll animations will fight. Use ScrollToPlugin only for non-root scroll containers.
+
+## CustomEase
+
+Use for:
+
+- branded camera acceleration,
+- a repeated product motion signature,
+- transition covers requiring exact velocity shape,
+- matching motion to sound or film reference.
+
+Document the intended feel and reuse the same named ease across related beats. Avoid a different custom ease for every tween.
+
+## CustomWiggle and CustomBounce
+
+Use sparingly for:
+
+- physically justified impacts,
+- tactile UI accents,
+- elastic materials,
+- stylized object responses.
+
+They are rarely appropriate for the main camera.
+
+## Draggable and InertiaPlugin
+
+Use for:
+
+- object exploration,
+- carousels with physical response,
+- 3D model rotation proxies,
+- timeline scrubbing controls,
+- spatial interfaces.
+
+Define boundaries, snapping, inertia, handoff to scroll, and what happens when the narrative timeline becomes active.
+
+## TextPlugin
+
+Use for controlled text replacement, counters, or terminal-like effects. Do not use typewriter behavior as a default “tech” aesthetic without narrative justification.
+
+## Physics and procedural plugins
+
+Physics-based plugins can create useful particles and impacts, but WebGL particle systems may be more appropriate for large quantities. Choose based on visual role and performance.
+
+## Plugin registration pattern
+
+Register only in the browser for frameworks that render on the server.
+
+```ts
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+import { SplitText } from 'gsap/SplitText';
+import { DrawSVGPlugin } from 'gsap/DrawSVGPlugin';
+import { MorphSVGPlugin } from 'gsap/MorphSVGPlugin';
+import { MotionPathPlugin } from 'gsap/MotionPathPlugin';
+
+if (typeof window !== 'undefined') {
+  gsap.registerPlugin(
+    ScrollTrigger,
+    SplitText,
+    DrawSVGPlugin,
+    MorphSVGPlugin,
+    MotionPathPlugin,
+  );
+}
+```
+
+Verify import paths and bundler behavior against the installed GSAP version and official documentation.
+
+## Plugin review rule
+
+For every plugin in the project, document:
+
+- the experience problem it solves,
+- its authoritative properties,
+- its lifecycle and cleanup,
+- responsive behavior,
+- reverse behavior,
+- fallback when disabled.
+
+If a plugin cannot be tied to a clear responsibility, remove it from the central experience architecture.

package/skills/struq/cinematic/references/09-tuning-harness.md

@@ -0,0 +1,202 @@
+# Tuning Harness
+
+## Manual tweaking is part of direction
+
+Three.js composition requires visual judgment. The goal is not to eliminate manual tweaking; it is to make it fast, controlled, reversible, and understandable.
+
+A tuning harness should let you answer:
+
+- Where am I in the experience?
+- Which chapter and phase are active?
+- Which system owns the property I am inspecting?
+- What are the current camera and target values?
+- Can I isolate this chapter and handoff?
+- Can I compare two settings without rebuilding?
+- Can I capture the current composition as direction data?
+
+## Minimum controls
+
+### Narrative controls
+
+- global progress slider,
+- active chapter selector,
+- local chapter progress slider,
+- play and pause,
+- forward and reverse,
+- playback speed,
+- jump to semantic label,
+- isolate handoff,
+- lock scroll while scrubbing.
+
+### Camera controls
+
+- camera world position,
+- camera narrative-rig position,
+- target world position,
+- FOV,
+- roll,
+- near and far planes,
+- focus distance,
+- aperture,
+- exposure,
+- capture current values as a named shot.
+
+### Subject controls
+
+- placement position,
+- rotation,
+- scale,
+- anchor visualization,
+- bounding box,
+- material and shader channels,
+- capture current values as a key pose.
+
+### Input controls
+
+- pointer visualization,
+- current pointer influence,
+- scroll velocity and normalized velocity,
+- direction,
+- interaction envelope,
+- force reduced motion,
+- emulate touch input.
+
+### Rendering controls
+
+- FPS and frame duration,
+- draw calls,
+- triangles,
+- textures,
+- render targets,
+- DPR,
+- shadow toggle,
+- post-processing toggle by pass,
+- particle-density tier,
+- wireframe and normals,
+- scene-group visibility.
+
+## Direction register
+
+Maintain a central register:
+
+```ts
+export const direction = {
+  chapters: {
+    reveal: {
+      scrollVh: 3.2,
+      phases: {
+        entrance: [0.00, 0.18],
+        establish: [0.18, 0.36],
+        development: [0.36, 0.68],
+        transformation: [0.68, 0.84],
+        handoff: [0.84, 1.00],
+      },
+      pointerStrength: 0.045,
+      velocityStrength: 0.12,
+    },
+  },
+  effects: {
+    bloom: { base: 0.15, apex: 0.55 },
+    grain: { strength: 0.08 },
+    distortion: { maxVelocity: 0.22 },
+  },
+};
+```
+
+Use named values and units. Avoid ambiguous values such as `speed: 2` without defining what the number means.
+
+## Preset capture
+
+A capture action should output valid direction data:
+
+```json
+{
+  "name": "productMacroDesktop",
+  "camera": {
+    "position": [0.12, 0.36, 2.18],
+    "target": [0.04, 0.18, 0.00],
+    "fov": 29,
+    "roll": -0.012
+  },
+  "subject": {
+    "position": [0.28, -0.14, 0.24],
+    "rotation": [0.06, -0.31, 0.02],
+    "scale": 1.18
+  }
+}
+```
+
+The agent can then compare, name, and integrate the preset into `shots.ts`.
+
+## Debug overlays
+
+Useful overlays include:
+
+- viewport center and thirds,
+- typography safe areas,
+- camera target and forward axis,
+- model anchors,
+- portal plane,
+- clipping and mask bounds,
+- chapter and handoff range markers,
+- active ownership labels,
+- current cue names.
+
+## Slow-motion review
+
+Review time-driven intros and discrete transitions at `0.25x` and `0.5x` speed. Scrub scroll-driven timelines slowly. Look for:
+
+- property jumps,
+- target drift,
+- hidden geometry appearing too early,
+- opacity changes covering architectural mistakes,
+- type and camera landing at the same instant without hierarchy,
+- insufficient occlusion,
+- interaction influence during critical moves,
+- abrupt effect thresholds.
+
+## Tuning order
+
+Tune in this order:
+
+1. state continuity,
+2. camera and subject composition,
+3. chapter phase boundaries,
+4. handoff coverage and ownership,
+5. hierarchy of beats,
+6. typography timing,
+7. interaction envelopes,
+8. lighting and material response,
+9. post-processing,
+10. microtiming and accents.
+
+Do not tune bloom, grain, and distortion before the camera path and state continuity are correct.
+
+## Review recordings
+
+Capture repeatable recordings at:
+
+- slow deliberate scroll,
+- normal trackpad scroll,
+- fast scroll and direction reversal,
+- touch scroll,
+- mobile portrait,
+- mobile landscape when supported,
+- reduced motion,
+- low-performance tier,
+- route enter and leave,
+- browser resize during the experience.
+
+Compare the same chapter across revisions. A screen recording is useful evidence for agent audits when the code alone does not reveal perceptual timing.
+
+## Acceptance thresholds
+
+Define project-specific thresholds such as:
+
+- no visible jump larger than one device pixel at ownership transfer,
+- no frame longer than 50 ms during a normal chapter transition on the target device,
+- stable 60 FPS on the primary desktop class or a documented lower target,
+- mobile camera keeps the principal subject inside the safe area at all key poses,
+- text remains readable for a minimum scroll interval,
+- reduced-motion mode contains no large forced parallax or rapid camera pass-through,
+- all triggers and ticker callbacks are removed after route leave.

package/skills/struq/cinematic/references/10-quality-systems.md

@@ -0,0 +1,206 @@
+# Responsive, Performance, and Accessibility Systems
+
+## Responsive choreography
+
+Responsive work is not a scale transform applied to desktop direction. It is a reinterpretation of the same narrative intent under different spatial and input constraints.
+
+Define viewport classes such as:
+
+```ts
+type ViewportClass =
+  | 'desktop-wide'
+  | 'desktop'
+  | 'tablet'
+  | 'mobile-portrait'
+  | 'mobile-landscape';
+```
+
+For each class define:
+
+- shot presets,
+- subject scale and anchors,
+- typography composition,
+- scroll-distance budgets,
+- interaction strengths,
+- transition coverage values,
+- particle and effect tier,
+- copy density,
+- controls and navigation behavior.
+
+## Mobile direction changes
+
+Common intentional changes include:
+
+- reduce camera lateral travel,
+- favor target movement over large camera orbit,
+- shorten or simplify portal passes,
+- move copy into a stable safe region,
+- use word-based rather than line-based splitting,
+- reduce pointer-dependent behavior,
+- replace hover interactions with tap or scroll responses,
+- reduce transparent particles and depth-of-field,
+- increase handoff occluder scale to guarantee coverage,
+- allocate more scroll distance for dense reading.
+
+## Reduced-motion choreography
+
+Reduced motion should preserve story and hierarchy while reducing:
+
+- long spatial travel,
+- rapid acceleration,
+- large parallax,
+- camera roll,
+- depth tunneling,
+- repeated oscillation,
+- velocity-linked distortion,
+- disorienting zoom changes.
+
+Possible substitutions:
+
+- dissolve within the same composition rather than fly through space,
+- cut between matched key poses under a short cover,
+- reveal type by opacity and contrast instead of large masked translation,
+- use limited scale changes,
+- disable pointer parallax and camera shake,
+- preserve bridge objects but reduce movement distance.
+
+Reduced motion is still directed. Do not simply disable all animation and leave broken visibility states.
+
+## Semantic content and accessibility
+
+The experience must preserve:
+
+- meaningful document order,
+- readable text outside the canvas,
+- keyboard access,
+- focus visibility,
+- accessible controls,
+- route announcements where needed,
+- alternatives for gesture-only interactions,
+- sufficient contrast,
+- non-blocking scroll escape,
+- meaningful fallback when WebGL is unavailable.
+
+Canvas visuals should not be the only source of essential information.
+
+## Input accessibility
+
+If wheel or touch gestures advance discrete chapters, also provide:
+
+- keyboard navigation,
+- visible progress or navigation,
+- a way to escape or return,
+- sensible browser-history behavior,
+- focus management,
+- reduced-motion behavior,
+- no accidental trapping inside nested scrollers.
+
+## Performance tiers
+
+Example:
+
+```ts
+type PerformanceTier = 'high' | 'balanced' | 'safe';
+```
+
+### High
+
+- full post-processing,
+- higher DPR cap,
+- dense particles,
+- dynamic shadows,
+- higher texture or geometry detail.
+
+### Balanced
+
+- selected post effects,
+- moderate DPR,
+- reduced particles,
+- limited shadows,
+- optimized texture sizes.
+
+### Safe
+
+- minimal post-processing,
+- low DPR cap,
+- simplified materials,
+- static or baked lighting,
+- reduced geometry and particles,
+- simpler transitions preserving the bridge concept.
+
+Do not rely on a single device heuristic. Allow manual override and respond to observed performance when appropriate.
+
+## Frame-budget thinking
+
+At 60 Hz the total frame duration is about 16.7 ms. This includes JavaScript, style, layout, paint, and GPU rendering. Treat long main-thread tasks, shader cost, overdraw, and asset decoding as part of one budget.
+
+Profile:
+
+- CPU frame time,
+- GPU frame time when available,
+- JS allocations,
+- layout and style recalculation,
+- texture memory,
+- draw calls,
+- triangles,
+- transparent overdraw,
+- shader complexity,
+- render-target count and resolution.
+
+## Asset strategy
+
+Define asset readiness by chapter:
+
+```text
+critical for first paint
+critical for intro
+required before chapter 2 handoff
+prefetch during chapter 1 hold
+optional enhancement for high tier
+```
+
+Preload the next chapter's bridge assets before the handoff. Do not load every high-resolution asset before showing anything unless the concept requires a fully controlled opening.
+
+## Common performance failures
+
+- full-resolution render targets for several effects,
+- high DPR on dense mobile screens,
+- unbounded transparent particles,
+- shadows on many dynamic lights,
+- rebuilding geometry or materials during render,
+- React state updates every frame,
+- layout reads and writes interleaved in pointer handlers,
+- multiple independent RAF loops doing redundant work (including R3F's default loop running next to the Lenis ticker, which should be a single `gsap.ticker` clock),
+- oversized textures,
+- mounting the incoming scene during the critical frame,
+- excessive blur filters on large DOM layers,
+- SplitText or ScrollTrigger refresh loops during resize.
+
+## Quality validation matrix
+
+Test combinations, not isolated features:
+
+| Dimension | Cases |
+|---|---|
+| Input | mouse, trackpad, touch, keyboard |
+| Motion | normal, reduced motion |
+| Performance | high, balanced, safe |
+| Viewport | wide desktop, laptop, tablet, mobile portrait |
+| Scroll | slow, fast, reverse, jump via navigation |
+| Lifecycle | first load, route enter, route leave, back navigation |
+| Assets | warm cache, cold cache, delayed model, delayed font |
+| Visibility | foreground tab, background and resume |
+
+## Graceful failure
+
+Define behavior for:
+
+- WebGL unavailable,
+- model fails to load,
+- shader compilation fails,
+- reduced-data preference,
+- autoplay audio unavailable,
+- low-memory device,
+- missing optional plugin effect.
+
+The fallback should preserve content and visual hierarchy, not display an empty stage.