@struq/skill 0.0.0-stage → 0.2.2

package/skills/struq/cinematic/templates/03-chapter-spec.md

@@ -0,0 +1,103 @@
+# Chapter Specification
+
+## Identity
+
+**Chapter ID:**
+
+**Name:**
+
+**Narrative purpose:**
+
+**Local progress source:**
+
+**Scroll-distance budget:**
+
+## State transformation
+
+**Incoming state:**
+
+**Hero state:**
+
+**Outgoing state:**
+
+**Primary subject:**
+
+**Bridge to next:**
+
+## Phase windows
+
+| Phase | Start | End | Viewer sees | Camera | Subject | DOM/SVG | Light/effects |
+|---|---:|---:|---|---|---|---|---|
+| Pre-roll | | | | | | | |
+| Entrance | | | | | | | |
+| Establish | | | | | | | |
+| Development | | | | | | | |
+| Transformation | | | | | | | |
+| Handoff prep | | | | | | | |
+| Handoff | | | | | | | |
+| Resolution | | | | | | | |
+
+## Semantic cues
+
+| Label | Progress | Meaning | Systems responding |
+|---|---:|---|---|
+| `chapter:enter` | | | |
+| `subject:established` | | | |
+| `copy:available` | | | |
+| `transformation:apex` | | | |
+| `handoff:armed` | | | |
+| `chapter:resolved` | | | |
+
+## Shot sequence
+
+| Shot | Progress range | Camera move | Target behavior | FOV/focus | Composition purpose |
+|---|---|---|---|---|---|
+
+## Property ownership
+
+| Property | Authoritative owner | Additive channel | Active range |
+|---|---|---|---|
+
+## Interaction envelope
+
+**Available interactions:**
+
+**Enable range:**
+
+**Critical interval:**
+
+**Attenuation rule:**
+
+**Touch behavior:**
+
+**Keyboard behavior:**
+
+## Reverse behavior
+
+[Describe what reverses, what remains loaded, which state thresholds change, and how interactions return.]
+
+## Responsive variants
+
+### Desktop
+
+### Tablet
+
+### Mobile
+
+### Reduced motion
+
+## Tuning values
+
+- 
+- 
+- 
+
+## Validation
+
+- [ ] Forward scrub is continuous.
+- [ ] Reverse scrub is continuous.
+- [ ] Key poses preserve composition.
+- [ ] Copy has sufficient reading time.
+- [ ] Interaction does not fight critical camera motion.
+- [ ] Handoff starts from the documented outgoing state.
+- [ ] Mobile composition is separately authored.

package/skills/struq/cinematic/templates/04-handoff-contract.md

@@ -0,0 +1,102 @@
+# Handoff Contract
+
+## Identity
+
+**ID:**
+
+**From:**
+
+**To:**
+
+**Global or local progress window:**
+
+## Bridge
+
+**Bridge element(s):**
+
+**Continuity type:** object / screen-space / world-space / typography / vector / light / texture / motion
+
+**Why the viewer understands the bridge:**
+
+## Outgoing state
+
+| Property | Value | Coordinate space | Owner |
+|---|---|---|---|
+
+## Incoming state
+
+| Property | Value | Coordinate space | Owner |
+|---|---|---|---|
+
+## State equality requirements
+
+| Shared property | Outgoing final | Incoming initial | Tolerance |
+|---|---|---|---|
+
+## Ownership transfer
+
+| Property | Outgoing owner | Transfer cue | Transition owner | Incoming cue | Incoming owner |
+|---|---|---|---|---|---|
+
+## Choreography
+
+| Handoff progress | Action | Visual purpose | Owner |
+|---:|---|---|---|
+| 0.00 | | | |
+| 0.25 | | | |
+| 0.50 | | | |
+| 0.75 | | | |
+| 1.00 | | | |
+
+## Camera continuity
+
+**Method:** continuous path / match pose / cut under cover / render blend / subject-relative
+
+**Position and target behavior:**
+
+**FOV and focus behavior:**
+
+## Cover or compositing
+
+**Occlusion strategy:**
+
+**Coverage condition:**
+
+**Scene or asset swap condition:**
+
+## Lighting and typography
+
+**Lighting continuity:**
+
+**Typography continuity:**
+
+## Interaction gating
+
+**Pointer:**
+
+**Scroll velocity effects:**
+
+**Click or hover:**
+
+## Readiness
+
+- Required assets:
+- Prefetch cue:
+- Fallback if unavailable:
+
+## Reverse behavior
+
+[Describe exact reverse thresholds, retained assets, and owner restoration.]
+
+## Completion condition
+
+[Measurable state proving that the incoming chapter is authoritative.]
+
+## Validation
+
+- [ ] Shared values match.
+- [ ] Cover condition works on all viewport classes.
+- [ ] No frame exposes an invalid mixed state.
+- [ ] Reverse behavior reconstructs the outgoing chapter.
+- [ ] Interaction ownership transfers cleanly.
+- [ ] Assets remain alive for reversal.

package/skills/struq/cinematic/templates/05-ownership-matrix.md

@@ -0,0 +1,29 @@
+# Property Ownership Matrix
+
+## Rules
+
+- Every mutable visual property has one authoritative writer at a time.
+- Additive behavior uses separate rigs or named channels.
+- Ownership changes occur only at semantic cues.
+- Route-level transitions can temporarily take ownership only through a documented handoff.
+
+## Matrix
+
+| Target | Property | Narrative owner | Reactive channel | Ambient channel | Discrete owner | Transfer cue | Final resolution |
+|---|---|---|---|---|---|---|---|
+| Camera | position | | | | | | |
+| Camera | target | | | | | | |
+| Camera | FOV | | | | | | |
+| Subject | position | | | | | | |
+| Subject | rotation | | | | | | |
+| Subject | scale | | | | | | |
+| Material | transition progress | | | | | | |
+| Shader | distortion | | | | | | |
+| DOM title wrapper | transform | | | | | | |
+| SVG bridge | path/morph | | | | | | |
+| Post FX | bloom | | | | | | |
+
+## Conflict findings
+
+| Property | Current writers | Symptom | Correction |
+|---|---|---|---|

package/skills/struq/cinematic/templates/06-shot-presets.md

@@ -0,0 +1,59 @@
+# Camera and Composition Shot Presets
+
+## Shot schema
+
+```ts
+type ShotPreset = {
+  id: string;
+  camera: {
+    position: [number, number, number];
+    target: [number, number, number];
+    fov: number;
+    roll: number;
+  };
+  focus?: {
+    distance: number;
+    aperture: number;
+  };
+  subject?: {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: number | [number, number, number];
+  };
+  exposure?: number;
+  composition: string;
+  safeArea: string;
+};
+```
+
+## Presets
+
+### `shot-name`
+
+**Purpose:**
+
+**Camera position:** `[x, y, z]`
+
+**Target:** `[x, y, z]`
+
+**FOV:**
+
+**Roll:**
+
+**Focus distance:**
+
+**Aperture:**
+
+**Subject transform:**
+
+**Exposure:**
+
+**Composition:**
+
+**Typography safe area:**
+
+**Desktop notes:**
+
+**Mobile variant:**
+
+**Transition compatibility:**

package/skills/struq/cinematic/templates/07-implementation-slice.md

@@ -0,0 +1,66 @@
+# Implementation Vertical Slice
+
+## Target behavior
+
+**Chapter:**
+
+**Handoff:**
+
+**Starting state:**
+
+**Ending state:**
+
+**Acceptance behavior:**
+
+## Files and responsibilities
+
+| File | Responsibility | Change |
+|---|---|---|
+
+## Required targets
+
+| Registry key | Component owner | Readiness condition |
+|---|---|---|
+
+## Timeline plan
+
+| Label | Progress/time | Action |
+|---|---:|---|
+
+## State and ownership changes
+
+| Property | Before | During | After |
+|---|---|---|---|
+
+## Responsive behavior
+
+**Desktop:**
+
+**Mobile:**
+
+**Reduced motion:**
+
+## Cleanup
+
+- timelines:
+- ScrollTriggers:
+- ticker callbacks:
+- listeners:
+- WebGL resources:
+- document styles/classes:
+
+## Tuning values exposed
+
+- 
+- 
+
+## Validation
+
+- [ ] forward
+- [ ] reverse
+- [ ] fast scroll
+- [ ] resize
+- [ ] route leave
+- [ ] touch
+- [ ] reduced motion
+- [ ] low-performance tier

package/skills/struq/cinematic/templates/08-tuning-register.md

@@ -0,0 +1,36 @@
+# Tuning Register
+
+## Current build
+
+**Commit or version:**
+
+**Viewport:**
+
+**Device:**
+
+**Performance tier:**
+
+## Values
+
+| ID | System | Value | Unit/range | Purpose | Last change | Evidence |
+|---|---|---:|---|---|---|---|
+
+## Shot captures
+
+| Shot | Camera | Target | FOV | Subject | Notes |
+|---|---|---:|---:|---|---|
+
+## Timing decisions
+
+| Chapter | Cue or phase | Previous | New | Reason | Recording/reference |
+|---|---|---:|---:|---|---|
+
+## Open visual questions
+
+- 
+- 
+
+## Rejected values
+
+| Value | Rejected because | Replacement |
+|---|---|---|

package/skills/struq/cinematic/templates/09-acceptance-tests.md

@@ -0,0 +1,57 @@
+# Experience Acceptance Tests
+
+## Narrative and continuity
+
+- [ ] The experience can be described as one coherent transformation.
+- [ ] Every chapter performs a distinct narrative action.
+- [ ] Every boundary has a visible or conceptual bridge.
+- [ ] Shared end and start states match.
+- [ ] No transition relies solely on hiding a jump with opacity.
+
+## Timeline and ownership
+
+- [ ] Every important property has one authoritative writer.
+- [ ] Chapter and handoff timelines are separated.
+- [ ] Semantic labels coordinate DOM and WebGL.
+- [ ] Reverse scrub reconstructs valid states.
+- [ ] Critical intervals attenuate reactive effects.
+
+## Camera and composition
+
+- [ ] Every chapter has named key shots.
+- [ ] Camera position and target are authored together.
+- [ ] Holds provide comprehension and reading time.
+- [ ] Mobile shots preserve the intended focal hierarchy.
+- [ ] FOV and focus changes are deliberate.
+
+## Interaction
+
+- [ ] Scroll owns macro progression.
+- [ ] Pointer and hover remain additive.
+- [ ] Touch has equivalent behavior.
+- [ ] Keyboard navigation is available where required.
+- [ ] Gesture modes provide a clear exit.
+
+## Responsive and reduced motion
+
+- [ ] Desktop, tablet, and mobile choreography are tested.
+- [ ] Reduced motion preserves story and visibility.
+- [ ] Transition covers work at all aspect ratios.
+- [ ] Typography re-splits or rebuilds safely.
+
+## Performance
+
+- [ ] Target frame-rate behavior is documented.
+- [ ] DPR and effects scale by tier.
+- [ ] Next-chapter assets are ready before the handoff.
+- [ ] No recurring allocations or React state updates occur in the frame loop.
+- [ ] Transparent overdraw and render targets are controlled.
+
+## Lifecycle
+
+- [ ] ScrollTriggers are killed on unmount.
+- [ ] GSAP ticker callbacks are removed.
+- [ ] Lenis state is restored.
+- [ ] Event listeners are removed.
+- [ ] custom WebGL resources are disposed.
+- [ ] route back/forward behavior is valid.