@struq/skill 0.0.0-stage → 0.2.1

package/skills/struq/cinematic/references/04-timeline-choreography.md

@@ -0,0 +1,264 @@
+# Timeline Choreography
+
+## Choreography is authored attention
+
+A timeline is not merely a list of property changes. It is a system for controlling attention, expectation, energy, and comprehension.
+
+At every meaningful interval answer:
+
+- What should the viewer notice first?
+- What should remain stable while that happens?
+- What anticipates the next action?
+- Where is the visual apex?
+- When is there enough stillness to read or understand?
+- What motion prepares the handoff?
+
+## The chapter phase grammar
+
+Use this grammar as a starting point:
+
+```text
+pre-roll
+→ entrance
+→ establish
+→ development
+→ transformation
+→ handoff preparation
+→ handoff
+→ resolution
+→ post-roll
+```
+
+### Pre-roll
+Prepare hidden state, load assets, place off-screen objects, or start incoming light before the viewer consciously enters.
+
+### Entrance
+Introduce the primary subject or compositional idea. Avoid introducing every layer simultaneously.
+
+### Establish
+Give the viewer a stable enough composition to understand what has arrived.
+
+### Development
+Reveal supporting copy, details, interactions, or secondary geometry.
+
+### Transformation
+Perform the chapter's principal visual idea.
+
+### Handoff preparation
+Move shared elements into positions and states that can validly begin the next chapter.
+
+### Handoff
+Transfer state ownership while preserving continuity.
+
+### Resolution
+Settle into the incoming chapter's stable composition.
+
+### Post-roll
+Park, hide, recycle, or release outgoing resources after they are no longer needed.
+
+## Normalize scroll-driven timelines
+
+A scroll-driven timeline is easier to reason about when its logical duration is `1`.
+
+```js
+const tl = gsap.timeline({ paused: true, defaults: { ease: 'none' } });
+
+tl.addLabel('chapter:enter', 0.00)
+  .addLabel('entrance:complete', 0.18)
+  .addLabel('establish:complete', 0.32)
+  .addLabel('transformation:start', 0.55)
+  .addLabel('transformation:apex', 0.76)
+  .addLabel('handoff:armed', 0.82)
+  .addLabel('handoff:occluded', 0.93)
+  .addLabel('chapter:resolved', 1.00);
+```
+
+Durations can then correspond directly to progress ranges. This does not mean every tween should use `ease: none`. The timeline is scrubbed linearly, while individual beats may still use shaped eases.
+
+## Timing hierarchy
+
+Think at four scales:
+
+### Experience rhythm
+The alternation of dense and quiet chapters across the whole route.
+
+### Chapter rhythm
+The pattern of entrance, hold, development, apex, and resolution.
+
+### Beat timing
+The relationship between camera, subject, copy, light, sound, and effects around one event.
+
+### Microtiming
+Small offsets that create causality and material feel.
+
+Example microtiming around a title reveal:
+
+```text
+0 ms    key light begins increasing
+40 ms   camera begins final 4% settle
+90 ms   first title line begins
+170 ms  second title line begins
+240 ms  camera stops
+280 ms  title reaches full contrast
+340 ms  metadata becomes interactive
+```
+
+The camera stopping before the title fully resolves can make the type feel anchored. Reversing that order can make the type feel like it is chasing the composition.
+
+## Motion relationships
+
+### Simultaneous
+Use when elements behave as one physical or conceptual unit.
+
+### Sequential
+Use when reading order or cause-and-effect matters.
+
+### Overlapping
+Use to maintain flow and avoid stop-start chapter boundaries.
+
+### Counter-motion
+Move foreground and background in opposing directions to create depth or tension.
+
+### Follow-through
+Allow secondary motion to continue after the primary action resolves.
+
+### Anticipation and release
+Pull away, compress, darken, or pause before a stronger movement.
+
+### Echo
+Repeat a motion motif at a different scale or in another medium. A camera arc can be echoed by a curved SVG line or letter stagger.
+
+## Easing by physical and emotional character
+
+Choose easing based on the intended material and beat.
+
+- `power2` or `power3`: controlled general-purpose movement.
+- `expo`: decisive arrivals and strong acceleration contrast.
+- `sine`: soft environmental drift.
+- `circ`: rounded, orbital movement.
+- custom ease: branded motion signatures and carefully controlled camera moves.
+- elastic or bounce: only when material and tone justify visible spring or impact.
+
+For scrubbed cinematic camera moves, excessively expressive easing can feel unstable because the user controls the playhead. Use ease to shape perception, but keep spatial paths readable in both directions.
+
+## Camera and target must be choreographed together
+
+Animating camera position alone often creates unwanted arcs or aim changes. Author:
+
+- camera rig position,
+- target rig position,
+- field of view,
+- roll,
+- focus distance,
+- exposure when required.
+
+A useful pattern is to animate the target slightly before the camera so attention begins shifting before the body of the move.
+
+```text
+target begins at 0.42
+camera begins at 0.46
+FOV tightens at 0.52
+focus reaches detail at 0.61
+camera settles at 0.66
+```
+
+## Holds are active design
+
+A hold does not require a completely static screen. During a hold:
+
+- major narrative transforms pause,
+- ambient motion continues,
+- pointer response may increase slightly,
+- copy becomes readable,
+- a minor detail may develop,
+- sound or shader texture may sustain tension.
+
+Avoid constant major motion. Without contrast, no beat feels important.
+
+## Staggers require direction
+
+Do not apply the same line or character stagger everywhere.
+
+Specify:
+
+- split type: lines, words, characters,
+- visual origin: top, bottom, pointer, center, path direction,
+- order: document, reverse, center-out, edges-in, random with seed,
+- temporal spacing,
+- transform axis,
+- clipping strategy,
+- re-split behavior,
+- relationship to camera and subject.
+
+Example:
+
+> Split the heading by lines. Reveal bottom-to-top through overflow masks with a 70 ms line stagger. Start the first line after the camera has completed 65% of its push-in. Let the final line finish 120 ms after the subject light settles.
+
+## Critical intervals and interaction attenuation
+
+Define a narrative criticality curve:
+
+```ts
+function criticality(progress: number): number {
+  // Example only: strongest during the pass-through.
+  return smoothRange(progress, 0.72, 0.90);
+}
+
+pointerStrength = basePointerStrength * (1 - criticality(progress) * 0.85);
+```
+
+This preserves the authored move while keeping the experience responsive elsewhere.
+
+## Scroll velocity as an effect signal
+
+Never map raw velocity directly to a strong effect.
+
+Use:
+
+1. signed input,
+2. clamp,
+3. normalize,
+4. ease or shape,
+5. smooth attack,
+6. slower decay,
+7. effect-specific maximum.
+
+```ts
+const normalized = clamp(scrollVelocity / 1800, -1, 1);
+const shaped = Math.sign(normalized) * Math.pow(Math.abs(normalized), 0.65);
+velocityTarget = shaped;
+velocityVisual = damp(velocityVisual, velocityTarget, 8, deltaTime);
+```
+
+Map velocity differently by channel. Directional smear may preserve sign; bloom intensity usually uses absolute magnitude.
+
+## Reverse-scroll choreography
+
+Scrubbing backward must be designed, not assumed.
+
+Check:
+
+- visibility states reverse cleanly,
+- paths and morphs remain valid,
+- incoming interactions disable at the right threshold,
+- scene changes are reversible or covered,
+- asset unloading does not occur too early,
+- callbacks do not create irreversible side effects,
+- labels and ownership return correctly.
+
+Avoid using timeline callbacks for state mutations that cannot be reconstructed from progress. Prefer deriving visual state from progress or using idempotent transitions.
+
+## Timeline review questions
+
+For each chapter ask:
+
+- Can I describe the chapter's main action in one sentence?
+- Is there a stable hero pose?
+- Is there a hold?
+- Is there one clear apex rather than several equal accents?
+- Does the next chapter begin preparing before this one ends?
+- Are type and camera choreographed relationally?
+- Does every motion have an owner?
+- Can the sequence reverse without a jump?
+- Does the mobile version preserve the same intention?
+- Can I tune the phase boundaries from one location?

package/skills/struq/cinematic/references/05-handoff-contracts.md

@@ -0,0 +1,241 @@
+# Handoff Contracts
+
+## Why handoffs determine quality
+
+Most animated sites feel like separate sections because chapter transitions are treated as decorative effects after each section has already been designed. A cinematic experience treats the boundary itself as a designed state interval.
+
+A handoff must answer:
+
+- what continues,
+- what changes,
+- what hides the change,
+- who owns each shared property,
+- when the incoming world becomes authoritative,
+- how the transition behaves in reverse.
+
+## Contract schema
+
+```ts
+export type HandoffContract = {
+  id: string;
+  fromChapter: string;
+  toChapter: string;
+  progressWindow: [number, number];
+  bridgeElements: string[];
+  outgoingState: Record<string, unknown>;
+  incomingState: Record<string, unknown>;
+  ownershipTransfer: Array<{
+    property: string;
+    outgoingOwner: string;
+    transferCue: string;
+    incomingOwner: string;
+  }>;
+  cameraContinuity: string;
+  occlusionStrategy: string;
+  lightingContinuity: string;
+  typographyContinuity: string;
+  interactionGating: string;
+  reverseBehavior: string;
+  readinessRequirements: string[];
+  completionCondition: string;
+};
+```
+
+## State equality
+
+For every shared property:
+
+```text
+outgoing final value = incoming initial value
+```
+
+This equality may exist in world space, local space, or screen space. Specify which one.
+
+Example:
+
+```text
+The ring's world position changes because it is reparented, but its screen-space center and apparent scale must remain unchanged during the transfer.
+```
+
+Reparenting may require preserving world transforms before attaching an object to a new parent.
+
+## Ownership transfer
+
+A handoff often has three ownership phases:
+
+```text
+outgoing owner
+→ shared transition owner
+→ incoming owner
+```
+
+Example:
+
+```text
+Chapter 2 controls the product placement rig until `handoff:armed`.
+The handoff timeline controls the placement rig from `handoff:armed` to `handoff:resolved`.
+Chapter 3 controls the rig after `handoff:resolved`.
+```
+
+Do not let the outgoing chapter and incoming chapter animate the same property during the overlap unless their values are explicitly blended through a transition channel.
+
+## Bridge strategies
+
+### Object bridge
+A persistent 3D object changes role while remaining visible.
+
+Use when the product or central symbol should unify the story.
+
+### Aperture or portal bridge
+A hole, screen, lens, door, or surface reveals the next state.
+
+Use when the transition should feel spatial and the incoming scene can be rendered behind or inside a mask.
+
+### Occluder bridge
+A near-camera object fills the frame and hides a swap.
+
+Use when assets or scene topology must change discontinuously.
+
+### Typography bridge
+A glyph or phrase changes scale, depth, mask, or position to become the next composition.
+
+Use when editorial direction is central.
+
+### Vector bridge
+An SVG line, path, or shape draws, bends, and morphs into an incoming visual structure.
+
+Use with DrawSVGPlugin, MorphSVGPlugin, MotionPathPlugin, masks, and clip paths.
+
+### Light bridge
+Incoming color temperature, direction, or contrast appears before incoming geometry.
+
+Use for subtle continuity and mood shifts.
+
+### Render-target bridge
+The outgoing or incoming world is rendered into a texture for portals, crossfades, displacement, feedback, or material transitions.
+
+Use when simple DOM masking cannot produce the required spatial relationship.
+
+### Motion bridge
+The direction, velocity, or rhythm of an outgoing movement continues through the incoming state.
+
+Use when no physical object persists but the kinetic logic should.
+
+## Handoff progress design
+
+A useful pattern:
+
+```text
+0.00-0.25  outgoing chapter begins preparation
+0.25-0.50  bridge becomes visually dominant
+0.50-0.75  incoming state appears under cover
+0.75-0.90  ownership transfers
+0.90-1.00  incoming state resolves and interactions enable
+```
+
+The exact proportions depend on the concept. Always reserve enough time for the viewer to understand the bridge.
+
+## Occlusion conditions
+
+Do not say only “swap when covered.” Define measurable coverage:
+
+- bridge bounding box covers at least 95% of the viewport,
+- depth buffer confirms the transition surface is nearest across the central safe area,
+- opacity or mask coverage reaches a threshold,
+- camera crosses a named portal plane,
+- shader transition progress exceeds a defined value.
+
+For responsive variants, the coverage condition may require different scale or path values.
+
+## Camera continuity patterns
+
+### Continuous path
+The same camera rig moves through the boundary.
+
+### Match-pose transfer
+The outgoing and incoming cameras have matching position, target, FOV, and framing before the scene source changes.
+
+### Virtual cut under cover
+The camera changes discontinuously while the viewport is fully occluded.
+
+### Render blend
+Two camera outputs are blended or distorted through render targets.
+
+### Subject-relative continuity
+The camera's world position changes, but its relationship to the bridge subject remains stable.
+
+## Reverse behavior
+
+Specify one of:
+
+- fully reversible scrub,
+- reversible until a commit threshold,
+- snap-backed state transition,
+- replayed inverse timeline,
+- route transition with no reverse scroll.
+
+For scroll-driven experiences, fully reversible behavior is the default expectation. Avoid destroying outgoing assets before the reverse threshold can no longer be crossed.
+
+## Complete example
+
+```md
+### Handoff: Material → Interior
+
+**Window:** global progress 0.48 to 0.58
+
+**Bridge:** circular lens opening on the product shell
+
+**Outgoing state:**
+- product placement rig at `[0.25, -0.10, 1.40]`
+- product yaw `-18deg`
+- camera shot `materialMacro`
+- environment brightness `0.35`
+- title reduced to one persistent word: “Inside”
+
+**Incoming state:**
+- tunnel root begins at the lens plane
+- camera shot begins at the exact `materialMacro` pose
+- interior light color already present at 15%
+- “Inside” is screen-space aligned with the tunnel axis
+
+**Ownership:**
+- chapter `material` owns product transforms until `handoff:armed`
+- handoff timeline owns product and camera from `handoff:armed` to `handoff:resolved`
+- chapter `interior` owns the camera target and tunnel progression after resolution
+
+**Sequence:**
+1. Reduce pointer influence from 0.06 to 0.01.
+2. Rotate the product to align the lens normal with the camera axis.
+3. Dolly forward while tightening FOV from 34 to 29.
+4. Begin rendering the tunnel behind the lens at handoff progress 0.32.
+5. Reach 96% aperture coverage at 0.68.
+6. Disable the outer shell and release the interior depth fog at 0.72.
+7. Transfer camera target ownership at 0.78.
+8. Restore pointer influence to 0.035 by 1.00.
+
+**Reverse:**
+- keep outer shell and material environment loaded until global progress exceeds 0.64
+- reverse all visibility through progress-derived values
+- restore outgoing chapter interactions below handoff progress 0.18
+
+**Completion:**
+- camera is inside the tunnel,
+- the lens edge is no longer visible,
+- interior lighting is authoritative,
+- chapter `interior` local progress is 0,
+- no transform changes at the ownership transfer frame.
+```
+
+## Handoff review checklist
+
+- Is there a bridge the viewer can understand?
+- Is the outgoing state prepared for the incoming state?
+- Are shared values equal at transfer?
+- Is the coordinate space specified?
+- Is the camera continuous or covered?
+- Is incoming content visible before outgoing content is discarded?
+- Are interactions attenuated during the critical interval?
+- Is the transition reversible?
+- Are assets retained long enough?
+- Is the mobile coverage condition valid?
+- Is the completion condition measurable?