@struq/skill 0.0.0-stage → 0.2.1

package/skills/struq/cinematic/examples/code/shared/ExperienceDirector.tsx

@@ -0,0 +1,57 @@
+import { useGSAP } from '@gsap/react';
+import { useEffect, useState, type RefObject } from 'react';
+import { buildExperienceTimeline } from './build-experience-timeline';
+import { gsap, registerGsap } from './gsap-client';
+import { experienceRegistry } from './registry';
+
+registerGsap();
+if (typeof window !== 'undefined') gsap.registerPlugin(useGSAP);
+
+const REQUIRED_TARGETS = [
+  'cameraNarrativeRig',
+  'cameraTargetNarrativeRig',
+  'camera',
+  'subjectNarrativeRig',
+  'subjectReactionRig',
+  'subjectMesh',
+  'interiorRoot',
+  'heroTitle',
+  'bridgePath',
+] as const;
+
+type ExperienceDirectorProps = {
+  scopeRef: RefObject<HTMLDivElement | null>;
+  narrativeRef: RefObject<HTMLDivElement | null>;
+  stageRef: RefObject<HTMLDivElement | null>;
+};
+
+export function ExperienceDirector({
+  scopeRef,
+  narrativeRef,
+  stageRef,
+}: ExperienceDirectorProps): null {
+  const [registryVersion, setRegistryVersion] = useState(0);
+
+  useEffect(
+    () => experienceRegistry.subscribe(() => setRegistryVersion((value) => value + 1)),
+    [],
+  );
+
+  useGSAP(() => {
+    if (!narrativeRef.current || !stageRef.current) return;
+    if (!experienceRegistry.hasAll([...REQUIRED_TARGETS])) return;
+
+    const experience = buildExperienceTimeline({
+      narrativeElement: narrativeRef.current,
+      stageElement: stageRef.current,
+    });
+
+    return experience.cleanup;
+  }, {
+    scope: scopeRef,
+    dependencies: [registryVersion],
+    revertOnUpdate: true,
+  });
+
+  return null;
+}

package/skills/struq/cinematic/examples/code/shared/ExperienceOverlay.tsx

@@ -0,0 +1,37 @@
+import { motion } from 'motion/react';
+import { useEffect, useRef, type JSX } from 'react';
+import { experienceRegistry } from './registry';
+
+export function ExperienceOverlay(): JSX.Element {
+  const title = useRef<HTMLHeadingElement>(null);
+  const path = useRef<SVGPathElement>(null);
+
+  useEffect(() => {
+    const unregister: Array<() => void> = [];
+    if (title.current) unregister.push(experienceRegistry.register('heroTitle', title.current));
+    if (path.current) unregister.push(experienceRegistry.register('bridgePath', path.current));
+    return () => unregister.forEach((dispose) => dispose());
+  }, []);
+
+  return (
+    <div className="experience-overlay">
+      <div className="experience-copy">
+        <h1 ref={title}>One world, continuously directed.</h1>
+        <p>Scroll to move through arrival, material, and interior states.</p>
+      </div>
+
+      <svg className="experience-bridge" viewBox="0 0 100 100" aria-hidden="true">
+        <path ref={path} d="M10,75 C35,15 65,15 90,75" fill="none" stroke="currentColor" />
+      </svg>
+
+      <motion.button
+        className="local-ui-button"
+        whileHover={{ scale: 1.04 }}
+        whileTap={{ scale: 0.97 }}
+        type="button"
+      >
+        Local Motion interaction
+      </motion.button>
+    </div>
+  );
+}

package/skills/struq/cinematic/examples/code/shared/ExperiencePage.tsx

@@ -0,0 +1,52 @@
+import { useRef, type JSX } from 'react';
+import { ExperienceCanvas } from './ExperienceCanvas';
+import { ExperienceDirector } from './ExperienceDirector';
+import { ExperienceOverlay } from './ExperienceOverlay';
+import { useExperienceInput } from './useExperienceInput';
+import './styles.css';
+
+export function ExperiencePage(): JSX.Element {
+  const scopeRef = useRef<HTMLDivElement>(null);
+  const narrativeRef = useRef<HTMLDivElement>(null);
+  const stageRef = useRef<HTMLDivElement>(null);
+
+  useExperienceInput();
+
+  return (
+    <div ref={scopeRef} className="experience-root">
+      <div ref={narrativeRef} className="experience-narrative">
+        <div ref={stageRef} className="experience-stage">
+          <ExperienceCanvas />
+          <ExperienceOverlay />
+        </div>
+
+        <div className="experience-scroll-space" aria-hidden="true" />
+
+        <div className="experience-semantic-content">
+          <section aria-labelledby="arrival-heading">
+            <h2 id="arrival-heading">Arrival</h2>
+            <p>The object is introduced as one stable composition.</p>
+          </section>
+          <section aria-labelledby="material-heading">
+            <h2 id="material-heading">Material</h2>
+            <p>The same subject transforms instead of being replaced.</p>
+          </section>
+          <section aria-labelledby="interior-heading">
+            <h2 id="interior-heading">Interior</h2>
+            <p>The subject becomes the bridge into a new spatial state.</p>
+          </section>
+        </div>
+      </div>
+
+      <footer className="experience-footer">
+        Normal document flow resumes after the persistent experience.
+      </footer>
+
+      <ExperienceDirector
+        scopeRef={scopeRef}
+        narrativeRef={narrativeRef}
+        stageRef={stageRef}
+      />
+    </div>
+  );
+}

package/skills/struq/cinematic/examples/code/shared/GsapFrameLoop.tsx

@@ -0,0 +1,32 @@
+import { useThree } from '@react-three/fiber';
+import { useEffect } from 'react';
+import { gsap, registerGsap } from './gsap-client';
+
+registerGsap();
+
+/**
+ * The single clock. The canvas is mounted with frameloop="never", so R3F does
+ * not run its own requestAnimationFrame loop. This component renders one frame
+ * per gsap.ticker tick, the same ticker that advances Lenis in LenisRoot.
+ *
+ * gsap.ticker passes its time in seconds, which is what advance() expects when
+ * frameloop is "never". Verify against the installed @react-three/fiber version.
+ */
+export function GsapFrameLoop(): null {
+  const advance = useThree((state) => state.advance);
+  const clock = useThree((state) => state.clock);
+
+  useEffect(() => {
+    const tick = (time: number) => advance(time);
+
+    // Sync R3F's clock to the ticker before the first tick, or the first frame
+    // sees a delta from 0 to gsap.ticker.time and every useFrame consumer jumps.
+    clock.elapsedTime = gsap.ticker.time;
+    gsap.ticker.add(tick);
+    return () => {
+      gsap.ticker.remove(tick);
+    };
+  }, [advance, clock]);
+
+  return null;
+}

package/skills/struq/cinematic/examples/code/shared/InteriorRoot.tsx

@@ -0,0 +1,30 @@
+import { useEffect, useRef, type JSX } from 'react';
+import * as THREE from 'three';
+import { experienceRegistry } from './registry';
+import { runtime } from './runtime';
+import { useFrame } from '@react-three/fiber';
+
+export function InteriorRoot(): JSX.Element {
+  const root = useRef<THREE.Group>(null);
+
+  useEffect(() => {
+    if (!root.current) return;
+    return experienceRegistry.register('interiorRoot', root.current);
+  }, []);
+
+  useFrame(() => {
+    if (!root.current) return;
+    root.current.visible = runtime.channels.interiorReveal > 0.001;
+  });
+
+  return (
+    <group ref={root} position={[0, 0, -3]} visible={false}>
+      {Array.from({ length: 14 }, (_, index) => (
+        <mesh key={index} position={[0, 0, -index * 0.55]}>
+          <torusGeometry args={[1.5, 0.03, 8, 64]} />
+          <meshBasicMaterial transparent opacity={0.28} />
+        </mesh>
+      ))}
+    </group>
+  );
+}

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

@@ -0,0 +1,20 @@
+# Shared Architecture Example
+
+Copy this folder to `src/experience` inside either the Next.js or Vite example.
+
+This code demonstrates:
+
+- one persistent stage,
+- one mutable runtime for high-frequency signals,
+- a named target registry,
+- camera and subject rig separation,
+- GSAP chapter and handoff timelines,
+- ScrollTrigger mapping,
+- Lenis integration in the framework adapters,
+- the single clock: Lenis (`autoRaf: false`) and the R3F canvas (`frameloop="never"`, advanced by `GsapFrameLoop`) both run from `gsap.ticker`,
+- Motion used only for local interface behavior,
+- centralized direction values.
+
+It is intentionally visually plain. The point is to prove orchestration and ownership before adding production assets, shaders, post-processing, or detailed styling.
+
+Verify plugin imports against the GSAP version installed in the project. The examples use the modern `motion/react` import path documented by Motion for React.

package/skills/struq/cinematic/examples/code/shared/SubjectRig.tsx

@@ -0,0 +1,58 @@
+import { useFrame } from '@react-three/fiber';
+import { useEffect, useRef, type JSX } from 'react';
+import * as THREE from 'three';
+import { experienceRegistry } from './registry';
+import { runtime } from './runtime';
+import { damp } from './math';
+
+export function SubjectRig(): JSX.Element {
+  const narrativeRig = useRef<THREE.Group>(null);
+  const reactionRig = useRef<THREE.Group>(null);
+  const mesh = useRef<THREE.Mesh>(null);
+
+  useEffect(() => {
+    if (!narrativeRig.current || !reactionRig.current || !mesh.current) return;
+
+    const unregister = [
+      experienceRegistry.register('subjectNarrativeRig', narrativeRig.current),
+      experienceRegistry.register('subjectReactionRig', reactionRig.current),
+      experienceRegistry.register('subjectMesh', mesh.current),
+    ];
+
+    return () => unregister.forEach((dispose) => dispose());
+  }, []);
+
+  useFrame((state, delta) => {
+    if (!reactionRig.current) return;
+
+    const interactionAllowed = runtime.activeHandoff === null;
+    const targetYaw = interactionAllowed ? runtime.pointer.x * 0.06 : 0;
+    const targetPitch = interactionAllowed ? -runtime.pointer.y * 0.03 : 0;
+
+    reactionRig.current.rotation.y = damp(
+      reactionRig.current.rotation.y,
+      targetYaw,
+      7,
+      delta,
+    );
+    reactionRig.current.rotation.x = damp(
+      reactionRig.current.rotation.x,
+      targetPitch,
+      7,
+      delta,
+    );
+
+    reactionRig.current.position.y = Math.sin(state.clock.elapsedTime * 0.7) * 0.015;
+  });
+
+  return (
+    <group ref={narrativeRig} position={[0.55, -0.1, 0]} rotation={[0.08, -0.55, 0]}>
+      <group ref={reactionRig}>
+        <mesh ref={mesh}>
+          <torusKnotGeometry args={[0.8, 0.24, 160, 24]} />
+          <meshStandardMaterial metalness={0.8} roughness={0.2} />
+        </mesh>
+      </group>
+    </group>
+  );
+}

package/skills/struq/cinematic/examples/code/shared/build-experience-timeline.ts

@@ -0,0 +1,237 @@
+import type * as THREE from 'three';
+import { experienceDirection, shots, type Shot } from './direction';
+import {
+  DrawSVGPlugin,
+  ScrollTrigger,
+  SplitText,
+  gsap,
+  registerGsap,
+} from './gsap-client';
+import { experienceRegistry } from './registry';
+import { runtime } from './runtime';
+
+export type BuildExperienceTimelineArgs = {
+  narrativeElement: HTMLElement;
+  stageElement: HTMLElement;
+};
+
+function addShot(
+  timeline: gsap.core.Timeline,
+  shot: Shot,
+  position: gsap.Position,
+  duration: number,
+): void {
+  const cameraRig = experienceRegistry.require('cameraNarrativeRig');
+  const targetRig = experienceRegistry.require('cameraTargetNarrativeRig');
+  const camera = experienceRegistry.require('camera');
+  const subjectRig = experienceRegistry.require('subjectNarrativeRig');
+
+  timeline.to(cameraRig.position, {
+    x: shot.camera.position[0],
+    y: shot.camera.position[1],
+    z: shot.camera.position[2],
+    duration,
+    ease: 'power2.inOut',
+  }, position);
+
+  timeline.to(targetRig.position, {
+    x: shot.camera.target[0],
+    y: shot.camera.target[1],
+    z: shot.camera.target[2],
+    duration,
+    ease: 'power2.inOut',
+  }, position);
+
+  timeline.to(camera, {
+    fov: shot.camera.fov,
+    duration,
+    ease: 'power1.inOut',
+    onUpdate: () => camera.updateProjectionMatrix(),
+  }, position);
+
+  timeline.to(subjectRig.position, {
+    x: shot.subject.position[0],
+    y: shot.subject.position[1],
+    z: shot.subject.position[2],
+    duration,
+    ease: 'power2.inOut',
+  }, position);
+
+  timeline.to(subjectRig.rotation, {
+    x: shot.subject.rotation[0],
+    y: shot.subject.rotation[1],
+    z: shot.subject.rotation[2],
+    duration,
+    ease: 'power2.inOut',
+  }, position);
+
+  timeline.to(subjectRig.scale, {
+    x: shot.subject.scale,
+    y: shot.subject.scale,
+    z: shot.subject.scale,
+    duration,
+    ease: 'power2.inOut',
+  }, position);
+}
+
+function buildArrival(): { timeline: gsap.core.Timeline; cleanup: () => void } {
+  const title = experienceRegistry.require('heroTitle');
+  const path = experienceRegistry.require('bridgePath');
+  const split = SplitText.create(title, { type: 'lines', mask: 'lines' });
+
+  const timeline = gsap.timeline({ defaults: { ease: 'none' } });
+  timeline.addLabel('arrival:enter', 0)
+    .from(split.lines, {
+      yPercent: 110,
+      autoAlpha: 0,
+      duration: 0.28,
+      stagger: 0.04,
+      ease: 'power3.out',
+    }, 0.08)
+    .fromTo(path, { drawSVG: '0%' }, {
+      drawSVG: '65%',
+      duration: 0.48,
+      ease: 'power2.inOut',
+    }, 0.22)
+    .addLabel('arrival:hero', 0.48)
+    .addLabel('arrival:handoff-armed', 0.82);
+
+  addShot(timeline, shots.material, 0.54, 0.46);
+
+  return { timeline, cleanup: () => split.revert() };
+}
+
+function buildMaterial(): gsap.core.Timeline {
+  const subject = experienceRegistry.require('subjectNarrativeRig');
+  const timeline = gsap.timeline({ defaults: { ease: 'none' } });
+
+  timeline.addLabel('material:enter', 0)
+    .to(subject.rotation, {
+      y: 0,
+      duration: 0.45,
+      ease: 'power2.inOut',
+    }, 0.10)
+    .to(subject.scale, {
+      x: 1.18,
+      y: 1.18,
+      z: 1.18,
+      duration: 0.34,
+      ease: 'power2.in',
+    }, 0.60)
+    .addLabel('portal:armed', 0.74);
+
+  addShot(timeline, shots.portal, 0.56, 0.44);
+
+  return timeline;
+}
+
+function buildPortalHandoff(): gsap.core.Timeline {
+  const interior = experienceRegistry.require('interiorRoot');
+  const subject = experienceRegistry.require('subjectNarrativeRig');
+  const timeline = gsap.timeline({ defaults: { ease: 'none' } });
+
+  timeline.addLabel('handoff:enter', 0)
+    .to(runtime.channels, {
+      pointerCameraStrength: experienceDirection.pointerStrength.critical,
+      duration: 0.18,
+      ease: 'power2.out',
+    }, 0)
+    .set(interior, { visible: true }, 0.22)
+    .to(runtime.channels, {
+      interiorReveal: 1,
+      duration: 0.58,
+      ease: 'power1.inOut',
+    }, 0.22)
+    .to(subject.scale, {
+      x: runtime.viewport === 'mobile'
+        ? experienceDirection.mobile.portalScale
+        : 2.1,
+      y: runtime.viewport === 'mobile'
+        ? experienceDirection.mobile.portalScale
+        : 2.1,
+      z: runtime.viewport === 'mobile'
+        ? experienceDirection.mobile.portalScale
+        : 2.1,
+      duration: 0.72,
+      ease: 'power2.in',
+    }, 0)
+    .addLabel('cover:safe', 0.68)
+    .set(subject, { visible: false }, 0.72)
+    .to(runtime.channels, {
+      pointerCameraStrength: experienceDirection.pointerStrength.interior,
+      duration: 0.22,
+      ease: 'power2.out',
+    }, 0.76)
+    .addLabel('handoff:resolved', 1);
+
+  addShot(timeline, shots.interior, 0.54, 0.46);
+
+  return timeline;
+}
+
+export function buildExperienceTimeline({
+  narrativeElement,
+  stageElement,
+}: BuildExperienceTimelineArgs): {
+  timeline: gsap.core.Timeline;
+  trigger: ScrollTrigger;
+  cleanup: () => void;
+} {
+  registerGsap();
+
+  const master = gsap.timeline({ paused: true });
+  const arrival = buildArrival();
+  const material = buildMaterial();
+  const portal = buildPortalHandoff();
+
+  master
+    .addLabel('chapter:arrival', 0)
+    .add(arrival.timeline, 'chapter:arrival')
+    .addLabel('chapter:material', 1)
+    .add(material, 'chapter:material')
+    .addLabel('handoff:portal', 2)
+    .add(portal, 'handoff:portal')
+    .addLabel('chapter:interior', 3);
+
+  const trigger = ScrollTrigger.create({
+    trigger: narrativeElement,
+    start: 'top top',
+    end: 'bottom bottom',
+    pin: stageElement,
+    pinSpacing: false,
+    // Lenis smooths the scroll input and a numeric scrub smooths the output on
+    // top. Keep the two paired (lower Lenis lerp, lower scrub number).
+    scrub: 0.65,
+    animation: master,
+    invalidateOnRefresh: true,
+    onUpdate(self) {
+      runtime.globalProgress = self.progress;
+      runtime.scrollVelocity = self.getVelocity();
+      runtime.scrollDirection = self.direction as -1 | 1;
+
+      if (self.progress < 1 / 3) {
+        runtime.activeChapter = 'arrival';
+        runtime.activeHandoff = null;
+        runtime.chapterProgress = self.progress * 3;
+      } else if (self.progress < 2 / 3) {
+        runtime.activeChapter = 'material';
+        runtime.activeHandoff = null;
+        runtime.chapterProgress = (self.progress - 1 / 3) * 3;
+      } else {
+        runtime.activeChapter = 'interior';
+        runtime.activeHandoff = 'material-interior';
+        runtime.chapterProgress = (self.progress - 2 / 3) * 3;
+      }
+    },
+  });
+
+  return {
+    timeline: master,
+    trigger,
+    cleanup: () => {
+      trigger.kill();
+      master.kill();
+      arrival.cleanup();
+    },
+  };
+}

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

@@ -0,0 +1,52 @@
+export type Shot = {
+  camera: {
+    position: [number, number, number];
+    target: [number, number, number];
+    fov: number;
+  };
+  subject: {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: number;
+  };
+};
+
+export const shots: Record<'arrival' | 'material' | 'portal' | 'interior', Shot> = {
+  arrival: {
+    camera: { position: [0, 0.25, 5.8], target: [0, 0, 0], fov: 34 },
+    subject: { position: [0.55, -0.1, 0], rotation: [0.08, -0.55, 0], scale: 1 },
+  },
+  material: {
+    camera: { position: [-0.4, 0.35, 4.4], target: [0.1, 0, 0], fov: 36 },
+    subject: { position: [0.15, -0.05, 0], rotation: [0.05, -0.2, 0], scale: 0.95 },
+  },
+  portal: {
+    camera: { position: [0, 0.05, 2.25], target: [0, 0, 0], fov: 29 },
+    subject: { position: [0, 0, 0], rotation: [0, 0, 0], scale: 1.3 },
+  },
+  interior: {
+    camera: { position: [0, 0, 0.55], target: [0, 0, -3], fov: 46 },
+    subject: { position: [0, 0, -2], rotation: [0, 0, 0], scale: 1 },
+  },
+};
+
+export const experienceDirection = {
+  scrollVh: 10,
+  labels: {
+    arrivalStart: 0,
+    materialStart: 1,
+    portalStart: 2,
+    interiorStart: 3,
+    end: 4,
+  },
+  pointerStrength: {
+    arrival: 0.035,
+    material: 0.05,
+    critical: 0.008,
+    interior: 0.02,
+  },
+  mobile: {
+    portalScale: 1.55,
+    pointerMultiplier: 0,
+  },
+};

package/skills/struq/cinematic/examples/code/shared/gsap-client.ts

@@ -0,0 +1,32 @@
+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';
+
+let registered = false;
+
+export function registerGsap(): typeof gsap {
+  if (typeof window !== 'undefined' && !registered) {
+    gsap.registerPlugin(
+      ScrollTrigger,
+      SplitText,
+      DrawSVGPlugin,
+      MorphSVGPlugin,
+      MotionPathPlugin,
+    );
+    registered = true;
+  }
+
+  return gsap;
+}
+
+export {
+  gsap,
+  ScrollTrigger,
+  SplitText,
+  DrawSVGPlugin,
+  MorphSVGPlugin,
+  MotionPathPlugin,
+};

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

@@ -0,0 +1,12 @@
+export function damp(
+  current: number,
+  target: number,
+  lambda: number,
+  deltaTime: number,
+): number {
+  return target + (current - target) * Math.exp(-lambda * deltaTime);
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}

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

@@ -0,0 +1,58 @@
+import type * as THREE from 'three';
+
+export type ExperienceTargetMap = {
+  cameraNarrativeRig: THREE.Group;
+  cameraTargetNarrativeRig: THREE.Group;
+  camera: THREE.PerspectiveCamera;
+  subjectNarrativeRig: THREE.Group;
+  subjectReactionRig: THREE.Group;
+  subjectMesh: THREE.Mesh;
+  interiorRoot: THREE.Group;
+  heroTitle: HTMLElement;
+  bridgePath: SVGPathElement;
+};
+
+type Key = keyof ExperienceTargetMap;
+type Listener = () => void;
+
+class ExperienceRegistry {
+  private targets = new Map<Key, ExperienceTargetMap[Key]>();
+  private listeners = new Set<Listener>();
+
+  register<K extends Key>(key: K, value: ExperienceTargetMap[K]): () => void {
+    this.targets.set(key, value);
+    this.emit();
+
+    return () => {
+      if (this.targets.get(key) === value) {
+        this.targets.delete(key);
+        this.emit();
+      }
+    };
+  }
+
+  get<K extends Key>(key: K): ExperienceTargetMap[K] | undefined {
+    return this.targets.get(key) as ExperienceTargetMap[K] | undefined;
+  }
+
+  require<K extends Key>(key: K): ExperienceTargetMap[K] {
+    const value = this.get(key);
+    if (!value) throw new Error(`Missing experience target: ${key}`);
+    return value;
+  }
+
+  hasAll(keys: Key[]): boolean {
+    return keys.every((key) => this.targets.has(key));
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) listener();
+  }
+}
+
+export const experienceRegistry = new ExperienceRegistry();