@struq/skill 0.0.0-stage → 0.2.2

package/skills/struq/cinematic/examples/code/shared/runtime.ts

@@ -0,0 +1,52 @@
+export type ViewportClass = 'desktop' | 'tablet' | 'mobile';
+export type PerformanceTier = 'high' | 'balanced' | 'safe';
+
+export type ExperienceRuntime = {
+  globalProgress: number;
+  activeChapter: 'arrival' | 'material' | 'interior';
+  chapterProgress: number;
+  activeHandoff: string | null;
+  elapsedTime: number;
+  deltaTime: number;
+  scrollVelocity: number;
+  scrollDirection: -1 | 0 | 1;
+  pointer: {
+    x: number;
+    y: number;
+    speed: number;
+  };
+  channels: {
+    pointerCameraStrength: number;
+    narrativeDistortion: number;
+    velocityDistortion: number;
+    interiorReveal: number;
+  };
+  viewport: ViewportClass;
+  reducedMotion: boolean;
+  performanceTier: PerformanceTier;
+};
+
+export const runtime: ExperienceRuntime = {
+  globalProgress: 0,
+  activeChapter: 'arrival',
+  chapterProgress: 0,
+  activeHandoff: null,
+  elapsedTime: 0,
+  deltaTime: 0,
+  scrollVelocity: 0,
+  scrollDirection: 0,
+  pointer: { x: 0, y: 0, speed: 0 },
+  channels: {
+    pointerCameraStrength: 0.035,
+    narrativeDistortion: 0,
+    velocityDistortion: 0,
+    interiorReveal: 0,
+  },
+  viewport: 'desktop',
+  reducedMotion: false,
+  performanceTier: 'balanced',
+};
+
+export function updateViewportClass(width: number): void {
+  runtime.viewport = width < 768 ? 'mobile' : width < 1100 ? 'tablet' : 'desktop';
+}

package/skills/struq/cinematic/examples/code/shared/styles.css

@@ -0,0 +1,127 @@
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  background: #080808;
+  color: #f5f2ea;
+  font-family: system-ui, sans-serif;
+}
+
+button,
+a {
+  font: inherit;
+}
+
+.experience-root {
+  min-height: 100%;
+  background: #080808;
+}
+
+.experience-narrative {
+  position: relative;
+  min-height: 1000vh;
+}
+
+.experience-stage {
+  position: relative;
+  width: 100%;
+  height: 100svh;
+  overflow: hidden;
+}
+
+.experience-stage canvas {
+  position: absolute;
+  inset: 0;
+}
+
+.experience-scroll-space {
+  height: 900vh;
+}
+
+.experience-overlay {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  display: grid;
+  align-items: center;
+  padding: clamp(1rem, 0.5rem + 3.5vw, 4rem);
+}
+
+.experience-copy {
+  width: min(34rem, 80vw);
+}
+
+/* Demo values. In a Struq build the h1 takes `font-display text-display` and the
+   pairing's tracking from typography.md §3.1; the clamp keeps a rem term for zoom. */
+.experience-copy h1 {
+  margin: 0;
+  font-size: clamp(2.875rem, 1.2rem + 6.86vw, 8rem);
+  font-weight: 300;
+  line-height: 0.96;
+  letter-spacing: -0.03em;
+}
+
+.experience-bridge {
+  position: absolute;
+  inset: auto 5vw 8vh auto;
+  width: min(32rem, 45vw);
+  overflow: visible;
+}
+
+.local-ui-button {
+  position: absolute;
+  left: clamp(1rem, 0.5rem + 3.5vw, 4rem);
+  bottom: 4vh;
+  pointer-events: auto;
+}
+
+.experience-semantic-content {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.experience-semantic-content section {
+  min-height: 300vh;
+  padding: 2rem;
+}
+
+.experience-semantic-content h2,
+.experience-semantic-content p {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
+
+.experience-footer {
+  min-height: 70vh;
+  display: grid;
+  place-items: center;
+  padding: 2rem;
+  background: #ece9e0;
+  color: #111;
+}
+
+@media (max-width: 767px) {
+  .experience-copy {
+    align-self: start;
+    margin-top: 12vh;
+  }
+
+  .experience-bridge {
+    width: 70vw;
+    right: 15vw;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .local-ui-button {
+    transition: none;
+  }
+}

package/skills/struq/cinematic/examples/code/shared/useExperienceInput.ts

@@ -0,0 +1,42 @@
+import { useEffect } from 'react';
+import { runtime, updateViewportClass } from './runtime';
+
+export function useExperienceInput(): void {
+  useEffect(() => {
+    let previousX = window.innerWidth / 2;
+    let previousY = window.innerHeight / 2;
+
+    const onPointerMove = (event: PointerEvent) => {
+      const x = (event.clientX / window.innerWidth) * 2 - 1;
+      const y = (event.clientY / window.innerHeight) * 2 - 1;
+      const dx = event.clientX - previousX;
+      const dy = event.clientY - previousY;
+
+      runtime.pointer.x = x;
+      runtime.pointer.y = y;
+      runtime.pointer.speed = Math.min(1, Math.hypot(dx, dy) / 80);
+
+      previousX = event.clientX;
+      previousY = event.clientY;
+    };
+
+    const onResize = () => updateViewportClass(window.innerWidth);
+    const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const onMotionChange = () => {
+      runtime.reducedMotion = reducedMotion.matches;
+    };
+
+    onResize();
+    onMotionChange();
+
+    window.addEventListener('pointermove', onPointerMove, { passive: true });
+    window.addEventListener('resize', onResize);
+    reducedMotion.addEventListener('change', onMotionChange);
+
+    return () => {
+      window.removeEventListener('pointermove', onPointerMove);
+      window.removeEventListener('resize', onResize);
+      reducedMotion.removeEventListener('change', onMotionChange);
+    };
+  }, []);
+}

package/skills/struq/cinematic/examples/code/vite/README.md

@@ -0,0 +1,14 @@
+# Vite Adapter
+
+## Create and install
+
+```bash
+npm create vite@latest cinematic-experience -- --template react-ts
+cd cinematic-experience
+npm install
+npm install gsap @gsap/react lenis three @react-three/fiber @react-three/drei motion
+```
+
+Copy `cinematic/examples/code/shared` to `src/experience`, then use the adapter files in this folder.
+
+Vite does not require a Next.js client boundary, but the same cleanup, target readiness, ownership, and responsive rules apply.

package/skills/struq/cinematic/examples/code/vite/src/App.tsx

@@ -0,0 +1,11 @@
+import type { JSX } from 'react';
+import { ExperiencePage } from './experience/ExperiencePage';
+import { LenisRoot } from './LenisRoot';
+
+export default function App(): JSX.Element {
+  return (
+    <LenisRoot>
+      <ExperiencePage />
+    </LenisRoot>
+  );
+}

package/skills/struq/cinematic/examples/code/vite/src/LenisRoot.tsx

@@ -0,0 +1,37 @@
+import { ReactLenis, useLenis, type LenisRef } from 'lenis/react';
+import 'lenis/dist/lenis.css';
+import { useEffect, useRef, type JSX, type ReactNode } from 'react';
+import { gsap, ScrollTrigger, registerGsap } from './experience/gsap-client';
+
+registerGsap();
+
+type LenisRootProps = {
+  children: ReactNode;
+};
+
+export function LenisRoot({ children }: LenisRootProps): JSX.Element {
+  const lenisRef = useRef<LenisRef>(null);
+
+  // ScrollTrigger sync without capturing the instance once.
+  useLenis(() => ScrollTrigger.update());
+
+  useEffect(() => {
+    // Registered unconditionally, instance resolved per frame (references/setup.md §2).
+    const update = (time: number) => {
+      lenisRef.current?.lenis?.raf(time * 1000);
+    };
+
+    gsap.ticker.add(update);
+    gsap.ticker.lagSmoothing(0);
+
+    return () => {
+      gsap.ticker.remove(update);
+    };
+  }, []);
+
+  return (
+    <ReactLenis root ref={lenisRef} options={{ lerp: 0.1, anchors: true, autoRaf: false }}>
+      {children}
+    </ReactLenis>
+  );
+}

package/skills/struq/cinematic/examples/code/vite/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/skills/struq/cinematic/examples/concise/01-chapter-spec-example.md

@@ -0,0 +1,42 @@
+# Concise Chapter Example: Product Disassembly
+
+## Purpose
+
+Reveal three functional systems by spatially separating one hero object while preserving it as a single readable composition.
+
+## State
+
+**Incoming:** complete object in shot `heroThreeQuarter`; title visible; pointer yaw strength `0.045`.
+
+**Outgoing:** three layers separated along the camera's depth axis; outer ring centered and facing camera as the bridge into the next chapter.
+
+## Progress
+
+| Range | Action |
+|---|---|
+| 0.00-0.12 | Hold hero pose; lower ambient noise and prepare rim light. |
+| 0.12-0.30 | Dolly 8% closer; SplitText title exits by lines toward the left vanishing point. |
+| 0.30-0.62 | Separate the three product layers with 60 ms overlap; reveal one feature label per layer. |
+| 0.62-0.78 | Hold separation; allow restrained pointer depth response. |
+| 0.78-0.90 | Rotate outer ring toward camera and move other layers behind it. |
+| 0.90-1.00 | Reduce pointer influence; ring reaches viewport center and becomes the transition aperture. |
+
+## Cues
+
+- `chapter:enter` at 0.00
+- `camera:commit` at 0.12
+- `layers:readable` at 0.62
+- `handoff:armed` at 0.78
+- `aperture:aligned` at 0.94
+- `chapter:resolved` at 1.00
+
+## Ownership
+
+- GSAP chapter timeline owns narrative camera and layer placement rigs.
+- R3F `useFrame` owns layer idle float and pointer reaction rigs.
+- SplitText timeline owns the title mask wrappers.
+- Handoff timeline takes the outer-ring placement rig at `handoff:armed`.
+
+## Mobile
+
+Use a shallower layer separation and move labels below the subject. Replace lateral camera truck with a target shift. Increase ring scale by 18% to guarantee transition coverage.

package/skills/struq/cinematic/examples/concise/02-handoff-example.md

@@ -0,0 +1,25 @@
+# Concise Handoff Example: Ring to Portal
+
+**From:** `disassembly`
+
+**To:** `interior`
+
+**Window:** global progress `0.51 to 0.60`
+
+**Bridge:** the product's outer ring.
+
+**Continuity:** screen-space center, apparent scale, ring rotation, and camera target must match at transfer.
+
+**Sequence:**
+
+1. At handoff progress `0.00`, disable ring hover and reduce pointer camera yaw from `0.045` to `0.008`.
+2. From `0.00 to 0.42`, align the ring normal to the camera and dolly toward it.
+3. At `0.28`, start rendering the interior scene behind the ring mask.
+4. At `0.68`, the ring covers at least `95%` of the central viewport safe area.
+5. At `0.72`, disable outgoing layers and change environment ownership under full cover.
+6. At `0.78`, transfer camera target ownership to the interior tunnel anchor.
+7. From `0.78 to 1.00`, restore pointer influence to the interior value `0.025` and reveal depth fog.
+
+**Reverse:** retain outgoing product layers until global progress exceeds `0.66`; all visibility is derived from progress, not one-time callbacks.
+
+**Completion:** camera is inside the tunnel, no ring edge is visible, interior lighting is authoritative, and incoming chapter local progress equals `0`.

package/skills/struq/cinematic/examples/concise/03-audit-finding-example.md

@@ -0,0 +1,13 @@
+# Concise Audit Finding Example
+
+## Finding: Camera drift during chapter transitions
+
+**Symptom:** The camera never lands on the same composition twice. Fast scroll produces a different final framing than slow scroll.
+
+**Cause:** The ScrollTrigger timeline writes directly to `camera.position`, while `useFrame` lerps the same position toward a pointer-based target. A route transition also animates the camera directly.
+
+**Perceptual consequence:** Key poses feel soft and unintentional. Handoffs expose small jumps because the outgoing final pose is unstable.
+
+**Correction:** Introduce `cameraNarrativeRig`, `cameraReactionRig`, and `cameraRouteRig`. Assign the chapter timeline to the narrative rig, pointer damping to the reaction rig, and route transitions to a temporary parent route rig. The physical camera only resolves look-at and projection.
+
+**Validation:** Scrub the chapter forward and backward ten times with pointer at different positions. The narrative rig must end at identical values, and the final subject screen position must remain within one pixel before reactive modulation is applied.