@struq/skill 0.2.1 → 0.3.0

package/skills/struq/recipes/components/struq/Reveal.tsx

@@ -0,0 +1,64 @@
+"use client";
+// components/struq/Reveal.tsx (Struq recipe)
+// Staggered rise for a group of text blocks: every direct child rises 48px from a fade as the
+// group scrolls into view. Opacity AND transform, never opacity alone, expo.out, fired once.
+//
+// <Reveal className="grid gap-6">
+//   <h2 className="text-h2">...</h2>
+//   <p className="text-lead">...</p>
+// </Reveal>
+//
+// Before hydration the children are hidden only when JavaScript runs (the `js` class from the
+// layout), and a CSS failsafe shows them after 3s if hydration never comes (globals.css).
+import { useRef } from "react";
+import { gsap, useGSAP } from "@/lib/gsap";
+
+type Props = {
+  children: React.ReactNode;
+  className?: string;
+  as?: "div" | "section" | "header" | "footer" | "ul" | "ol";
+  /** Distance each child rises, in px. 24 to 80. */
+  y?: number;
+  stagger?: number;
+  delay?: number;
+  /** "scroll" waits for the viewport; "load" plays on mount (for the hero). */
+  on?: "scroll" | "load";
+};
+
+export function Reveal({ children, className = "", as = "div", y = 48, stagger = 0.08, delay = 0, on = "scroll" }: Props) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const el = ref.current;
+      if (!el) return;
+      const items = Array.from(el.children);
+      const mm = gsap.matchMedia();
+      mm.add(
+        { motion: "(prefers-reduced-motion: no-preference)", reduce: "(prefers-reduced-motion: reduce)" },
+        (ctx) => {
+          const reduce = ctx.conditions?.reduce;
+          gsap.from(items, {
+            y: reduce ? 0 : y,
+            autoAlpha: 0,
+            duration: reduce ? 0.5 : 0.9,
+            ease: "expo.out",
+            stagger,
+            delay,
+            scrollTrigger: on === "scroll" ? { trigger: el, start: "top 85%", once: true } : undefined,
+          });
+        },
+      );
+      el.dataset.ready = "1";
+      return () => mm.revert();
+    },
+    { scope: ref },
+  );
+
+  const Tag = as as "div";
+  return (
+    <Tag ref={ref} data-reveal="" className={className}>
+      {children}
+    </Tag>
+  );
+}

package/skills/struq/recipes/components/struq/SmoothScroll.tsx

@@ -0,0 +1,57 @@
+"use client";
+// components/struq/SmoothScroll.tsx (Struq recipe)
+// Lenis smooth scroll on the GSAP ticker: one requestAnimationFrame for the whole page.
+// Mount it once, in app/layout.tsx, around {children}.
+//
+// Why it is built this way:
+// - autoRaf false plus gsap.ticker: Lenis and ScrollTrigger sample scroll on the same frame,
+//   so scrubbed timelines never micro-stutter.
+// - lagSmoothing(0): GSAP never "catches up" after a long frame, which would jump scrubs.
+// - Lenis is created inside the effect, so there is no ref race that can leave the wheel dead.
+// - Reduced motion: no Lenis, native scroll. ScrollTrigger keeps working on native scroll.
+import Lenis from "lenis";
+import "lenis/dist/lenis.css";
+import { useEffect } from "react";
+import { gsap, ScrollTrigger } from "@/lib/gsap";
+
+let current: Lenis | null = null;
+
+/**
+ * The page's Lenis instance, or null under reduced motion and before mount.
+ * An overlay menu calls getLenis()?.stop() when it opens and getLenis()?.start() on EVERY close path.
+ */
+export function getLenis() {
+  return current;
+}
+
+export function SmoothScroll({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    ScrollTrigger.config({ ignoreMobileResize: true });
+    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+    // Fonts change line breaks and section heights: re-measure every trigger once they land.
+    const refresh = () => ScrollTrigger.refresh();
+    document.fonts?.ready.then(refresh);
+    const late = window.setTimeout(refresh, 600);
+
+    if (reduce) {
+      return () => window.clearTimeout(late);
+    }
+
+    const lenis = new Lenis({ lerp: 0.1, autoRaf: false, anchors: true });
+    const raf = (time: number) => lenis.raf(time * 1000); // GSAP gives seconds, Lenis wants ms
+    lenis.on("scroll", ScrollTrigger.update);
+    gsap.ticker.add(raf);
+    gsap.ticker.lagSmoothing(0);
+    current = lenis;
+
+    return () => {
+      window.clearTimeout(late);
+      gsap.ticker.remove(raf);
+      lenis.destroy();
+      current = null;
+    };
+  }, []);
+
+  return <>{children}</>;
+}

package/skills/struq/recipes/components/struq/SplitHeadline.tsx

@@ -0,0 +1,68 @@
+"use client";
+// components/struq/SplitHeadline.tsx (Struq recipe)
+// The hero headline: SplitText cuts it into lines, each line rises out of its own mask.
+// autoSplit re-cuts it when the width or the webfont changes, so mobile line breaks stay right.
+//
+// <SplitHeadline as="h1" className="font-display text-display max-w-[14ch]">
+//   Vis en groente, van het seizoen.
+// </SplitHeadline>
+//
+// Pass plain text (or text with <em>): SplitText needs text nodes, not components.
+import { useRef } from "react";
+import { gsap, SplitText, useGSAP } from "@/lib/gsap";
+
+type Props = {
+  children: React.ReactNode;
+  as?: "h1" | "h2" | "h3" | "p";
+  className?: string;
+  /** "load" for the hero, "scroll" for a statement further down. */
+  on?: "load" | "scroll";
+  delay?: number;
+  /** Mark it as copy the hero canvas hushes behind. On by default for the h1. */
+  quiet?: boolean;
+};
+
+export function SplitHeadline({ children, as = "h1", className = "", on = "load", delay = 0.15, quiet = as === "h1" }: Props) {
+  const ref = useRef<HTMLHeadingElement>(null);
+
+  useGSAP(
+    () => {
+      const el = ref.current;
+      if (!el) return;
+      const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+      if (reduce) {
+        el.dataset.ready = "1";
+        gsap.from(el, { autoAlpha: 0, duration: 0.6 });
+        return;
+      }
+
+      const split = SplitText.create(el, {
+        type: "lines",
+        mask: "lines",
+        linesClass: "struq-line",
+        autoSplit: true,
+        onSplit(self) {
+          return gsap.from(self.lines, {
+            yPercent: 115,
+            duration: 1.25,
+            ease: "expo.out",
+            stagger: 0.09,
+            delay,
+            scrollTrigger: on === "scroll" ? { trigger: el, start: "top 80%", once: true } : undefined,
+          });
+        },
+      });
+      el.dataset.ready = "1";
+      return () => split.revert();
+    },
+    { scope: ref },
+  );
+
+  const Tag = as as "h1";
+  return (
+    <Tag ref={ref} data-split="" data-quiet={quiet ? "" : undefined} className={className}>
+      {children}
+    </Tag>
+  );
+}

package/skills/struq/recipes/components/struq/scenes/contours.ts

@@ -0,0 +1,161 @@
+// components/struq/scenes/contours.ts (Struq recipe)
+// A survey terrain seen at a low angle: fine contour lines in the ink, every fifth line catching the
+// accent on the right of the frame, compressing toward a horizon above the top edge. The field drifts
+// toward the viewer on a slow clock, the pointer lifts it a little, and it hushes behind the copy.
+// Composition: the vanishing point sits on the right third and the lines fade out to the left, so a
+// headline on the left sits in calm space. Needs no photo.
+// Suits: architecture, studios, consultancy, research, nature, anything calm and precise.
+//
+// Two passes, so noise never runs per screen pixel: a field pass writes the terrain height into a
+// small target (one texel per 4 CSS pixels, packed to 16 bits), and the draw pass turns the
+// upsampled height into antialiased lines with cheap per-pixel arithmetic.
+import { NOISE_GLSL, QUIET_GLSL, quietUniforms, type CreateScene } from "./types";
+
+const CELL = 4; // CSS pixels per field texel
+
+export const createScene: CreateScene = async ({ THREE, renderer, palette, dark }) => {
+  const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+  const quad = new THREE.PlaneGeometry(2, 2);
+  const vertexShader = /* glsl */ `void main() { gl_Position = vec4(position.xy, 0.0, 1.0); }`;
+
+  const field = new THREE.WebGLRenderTarget(2, 2, {
+    minFilter: THREE.NearestFilter,
+    magFilter: THREE.NearestFilter,
+    depthBuffer: false,
+    generateMipmaps: false,
+  });
+
+  const fieldUniforms = {
+    uFieldRes: { value: new THREE.Vector2(2, 2) },
+    uAspect: { value: 1 },
+    uTime: { value: 0 },
+    uPointer: { value: new THREE.Vector2() },
+    uPresence: { value: 0 },
+    uScroll: { value: 0 },
+  };
+  const fieldMaterial = new THREE.ShaderMaterial({
+    uniforms: fieldUniforms,
+    vertexShader,
+    fragmentShader: /* glsl */ `
+      uniform vec2 uFieldRes; uniform float uAspect; uniform float uTime;
+      uniform vec2 uPointer; uniform float uPresence; uniform float uScroll;
+      ${NOISE_GLSL}
+      void main() {
+        vec2 uv = gl_FragCoord.xy / uFieldRes;
+        float t = uTime * 0.022; // the ambient clock: a slow drift, Vapor pace
+        // Perspective: the horizon sits just above the top edge, the vanishing point on the right third.
+        float below = 1.18 - uv.y;
+        float Z = 0.8 / below;
+        float X = (uv.x - 0.66) * uAspect * Z;
+        vec2 p = vec2(X, Z - t * 1.1 + uScroll * 1.2) * 0.62;
+        vec2 warp = vec2(fbm(p + vec2(0.0, t)), fbm(p + vec2(4.1, -t)));
+        float h = fbm(p * 0.9 + 1.25 * warp);
+        // The pointer: a soft rise where it rests, eased by presence. A modulation, never a spotlight.
+        vec2 d = (uv - (uPointer * 0.5 + 0.5)) * vec2(uAspect, 1.0);
+        h += exp(-dot(d, d) / 0.035) * 0.05 * uPresence;
+        h = clamp(h, 0.0, 0.999);
+        gl_FragColor = vec4(floor(h * 255.0) / 255.0, fract(h * 255.0), 0.0, 1.0);
+      }
+    `,
+  });
+  const fieldScene = new THREE.Scene();
+  fieldScene.add(new THREE.Mesh(quad, fieldMaterial));
+
+  const quietSet = quietUniforms(THREE, dark ? 0.08 : 0.12);
+  const drawUniforms = {
+    ...quietSet.uniforms,
+    uField: { value: field.texture },
+    uFieldRes: { value: new THREE.Vector2(2, 2) },
+    uCell: { value: CELL },
+    uResPx: { value: new THREE.Vector2(1, 1) },
+    uTime: { value: 0 },
+    uSurface: { value: new THREE.Color(palette.surface) },
+    uInk: { value: new THREE.Color(palette.ink) },
+    uAccent: { value: new THREE.Color(palette.accent) },
+    uInkWeight: { value: dark ? 0.85 : 0.56 },
+    // On a dark ground the lines need more weight and must not vanish on the copy side.
+    uLeftFloor: { value: dark ? 0.45 : 0.2 },
+  };
+  const drawMaterial = new THREE.ShaderMaterial({
+    uniforms: drawUniforms,
+    vertexShader,
+    fragmentShader: /* glsl */ `
+      uniform sampler2D uField; uniform vec2 uFieldRes; uniform float uCell; uniform vec2 uResPx;
+      uniform float uTime; uniform vec3 uSurface; uniform vec3 uInk; uniform vec3 uAccent; uniform float uInkWeight; uniform float uLeftFloor;
+      ${QUIET_GLSL}
+      float grain(vec2 p) { p = fract(p * vec2(443.897, 441.423)); p += dot(p, p.yx + 19.19); return fract((p.x + p.y) * p.x); }
+      float at(ivec2 i) {
+        ivec2 m = ivec2(uFieldRes) - 1;
+        vec4 v = texelFetch(uField, clamp(i, ivec2(0), m), 0);
+        return v.r + v.g / 255.0;
+      }
+      float height(vec2 fc) {
+        vec2 g = fc / uCell - 0.5;
+        ivec2 i = ivec2(floor(g));
+        vec2 f = fract(g);
+        return mix(mix(at(i), at(i + ivec2(1, 0)), f.x), mix(at(i + ivec2(0, 1)), at(i + ivec2(1, 1)), f.x), f.y);
+      }
+      void main() {
+        vec2 fc = gl_FragCoord.xy;
+        vec2 uv = fc / uResPx;
+        float f = height(fc) * 54.0;
+        float w = fwidth(f);
+        float dist = min(fract(f), 1.0 - fract(f));
+        float line = 1.0 - smoothstep(0.0, w * 1.3, dist);
+        // Where lines crowd closer than the screen can draw, they fade into a mist instead of moire.
+        float dense = smoothstep(0.22, 0.55, w);
+        float mist = dense * 0.05;
+        line *= 1.0 - dense;
+        float major = 1.0 - step(0.5, mod(floor(f + 0.5), 5.0));
+        // Composition and depth: weighted to the right, fading toward the far horizon.
+        float right = uLeftFloor + (1.0 - uLeftFloor) * smoothstep(0.05, 0.8, uv.x);
+        float near = 1.0 - 0.6 * smoothstep(0.3, 1.0, uv.y);
+        float inkV = hush((line * (0.55 + 0.45 * major) + mist) * uInkWeight * right * near, fc);
+        float accentV = hush(line * major * smoothstep(0.5, 0.95, uv.x) * near * 0.75, fc);
+        vec3 col = mix(uSurface, uInk, inkV);
+        col = mix(col, uAccent, accentV);
+        col += (grain(fc + fract(uTime) * 61.0) - 0.5) * 0.018;
+        gl_FragColor = vec4(col, 1.0);
+        #include <colorspace_fragment>
+      }
+    `,
+  });
+  const scene = new THREE.Scene();
+  scene.add(new THREE.Mesh(quad, drawMaterial));
+
+  return {
+    scene,
+    camera,
+    update(state) {
+      fieldUniforms.uTime.value = state.time;
+      fieldUniforms.uPointer.value.set(state.pointer.x, state.pointer.y);
+      fieldUniforms.uPresence.value = state.presence;
+      fieldUniforms.uScroll.value = state.scroll;
+      drawUniforms.uTime.value = state.time;
+      quietSet.update(state);
+    },
+    resize(width, height) {
+      const pr = renderer.getPixelRatio();
+      const fw = Math.max(2, Math.ceil(width / CELL));
+      const fh = Math.max(2, Math.ceil(height / CELL));
+      field.setSize(fw, fh);
+      fieldUniforms.uFieldRes.value.set(fw, fh);
+      fieldUniforms.uAspect.value = width / Math.max(1, height);
+      drawUniforms.uFieldRes.value.set(fw, fh);
+      drawUniforms.uCell.value = CELL * pr;
+      drawUniforms.uResPx.value.set(width * pr, height * pr);
+    },
+    render(r) {
+      r.setRenderTarget(field);
+      r.render(fieldScene, camera);
+      r.setRenderTarget(null);
+      r.render(scene, camera);
+    },
+    dispose() {
+      quad.dispose();
+      field.dispose();
+      fieldMaterial.dispose();
+      drawMaterial.dispose();
+    },
+  };
+};

package/skills/struq/recipes/components/struq/scenes/dots.ts

@@ -0,0 +1,110 @@
+// components/struq/scenes/dots.ts (Struq recipe)
+// A fine field of points seen at a low angle, rolling like a slow swell toward a horizon in the upper
+// third. The swell rises toward the right of the frame, its crests catch the accent, the far rows thin
+// out into the ground colour, and the field hushes behind the copy. The pointer lifts a soft hill only
+// while it is there. Scrolling lowers the field away.
+// Suits: mobility, logistics, technology, sport, energy, data: anything about movement or scale.
+import { NOISE_GLSL, QUIET_GLSL, quietUniforms, type CreateScene } from "./types";
+
+export const createScene: CreateScene = async ({ THREE, renderer, palette, dark }) => {
+  const scene = new THREE.Scene();
+  const camera = new THREE.PerspectiveCamera(38, 1, 0.1, 100);
+  camera.position.set(-1.5, 4.2, 13);
+  camera.lookAt(1.5, 0.4, -6);
+  renderer.setClearColor(new THREE.Color(palette.surface), 1);
+
+  const cols = 260;
+  const rows = 120;
+  const positions = new Float32Array(cols * rows * 3);
+  let i = 0;
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      positions[i++] = (c / (cols - 1) - 0.5) * 48;
+      positions[i++] = 0;
+      positions[i++] = (r / (rows - 1)) * -40 + 10;
+    }
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+
+  const quietSet = quietUniforms(THREE, dark ? 0.1 : 0.16);
+  const uniforms = {
+    ...quietSet.uniforms,
+    uTime: { value: 0 },
+    uPointer: { value: new THREE.Vector2(0, 0) },
+    uPresence: { value: 0 },
+    uScroll: { value: 0 },
+    uDpr: { value: renderer.getPixelRatio() },
+    uInk: { value: new THREE.Color(palette.ink) },
+    uAccent: { value: new THREE.Color(palette.accent) },
+    uInkWeight: { value: dark ? 1.0 : 0.8 },
+    // On a dark ground light points read smaller and fainter: bigger points and a visibility floor,
+    // so a photo-less opener on the inverse ground still carries the screen.
+    uSize: { value: dark ? 62 : 44 },
+    uFloor: { value: dark ? 0.38 : 0 },
+  };
+
+  const material = new THREE.ShaderMaterial({
+    uniforms,
+    transparent: true,
+    depthWrite: false,
+    vertexShader: /* glsl */ `
+      uniform float uTime; uniform vec2 uPointer; uniform float uPresence; uniform float uScroll; uniform float uDpr; uniform float uSize;
+      varying float vH; varying float vFade;
+      ${NOISE_GLSL}
+      void main() {
+        vec3 p = position;
+        float t = uTime * 0.04;
+        // Long swells rolling toward the viewer, broken by slow noise; taller toward the right.
+        float rise = smoothstep(-20.0, 18.0, p.x);
+        float h = 0.8 * sin(p.z * 0.3 + p.x * 0.05 + t * 3.0) + 1.4 * (fbm(p.xz * 0.07 + vec2(t, t * 0.6)) - 0.5);
+        h = h * (0.35 + 0.85 * rise);
+        vec2 hill = p.xz - vec2(uPointer.x * 16.0 + 2.0, -uPointer.y * 10.0 - 4.0);
+        h += exp(-dot(hill, hill) * 0.03) * 0.7 * uPresence;
+        p.y += h - uScroll * 2.2;
+        vH = clamp(h * 0.6 + 0.5, 0.0, 1.0);
+        vec4 mv = modelViewMatrix * vec4(p, 1.0);
+        vFade = smoothstep(46.0, 14.0, -mv.z) * smoothstep(0.5, 4.0, -mv.z);
+        gl_Position = projectionMatrix * mv;
+        gl_PointSize = max(1.5 * uDpr, uDpr * uSize / -mv.z);
+      }
+    `,
+    fragmentShader: /* glsl */ `
+      uniform vec3 uInk; uniform vec3 uAccent; uniform float uInkWeight; uniform float uFloor;
+      varying float vH; varying float vFade;
+      ${QUIET_GLSL}
+      void main() {
+        float d = length(gl_PointCoord - 0.5);
+        float disc = smoothstep(0.5, 0.3, d);
+        float crest = smoothstep(0.68, 0.95, vH);
+        float v = hush(max((0.3 + 0.7 * vH) * uInkWeight, uFloor) * vFade, gl_FragCoord.xy);
+        vec3 col = mix(uInk, uAccent, crest * 0.85);
+        gl_FragColor = vec4(col, disc * v);
+        #include <colorspace_fragment>
+      }
+    `,
+  });
+
+  scene.add(new THREE.Points(geometry, material));
+
+  return {
+    scene,
+    camera,
+    update(state) {
+      uniforms.uTime.value = state.time;
+      uniforms.uPointer.value.set(state.pointer.x, state.pointer.y);
+      uniforms.uPresence.value = state.presence;
+      uniforms.uScroll.value = state.scroll;
+      quietSet.update(state);
+    },
+    resize(width, height) {
+      camera.aspect = width / Math.max(1, height);
+      camera.updateProjectionMatrix();
+      uniforms.uDpr.value = renderer.getPixelRatio();
+    },
+    dispose() {
+      geometry.dispose();
+      material.dispose();
+    },
+  };
+};

package/skills/struq/recipes/components/struq/scenes/ripple.ts

@@ -0,0 +1,99 @@
+// components/struq/scenes/ripple.ts (Struq recipe)
+// The hero photo as a living surface: a slow liquid drift, a ripple that follows the pointer
+// and grows with its speed, a hint of chromatic split in the ripple, and a slow push-in as the
+// hero scrolls away. The photo is pulled toward the palette (ink in the shadows, surface in the
+// highlights) by `grade`, so any pack photo sits in the site's colours. The ripple only lives while
+// the pointer is there (presence), and it stills behind the copy marked data-quiet.
+// Suits: hospitality, food, hotels, fashion, wellness, any brief with one strong hero photo.
+import { NOISE_GLSL, QUIET_GLSL, quietUniforms, type CreateScene } from "./types";
+
+export const createScene: CreateScene = async ({ THREE, renderer, palette, image, grade }) => {
+  if (!image) throw new Error("The ripple scene needs an image: <HeroCanvas scene=\"ripple\" image={images.hero[0]} />");
+  const scene = new THREE.Scene();
+  const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+  const texture = await new THREE.TextureLoader().loadAsync(image.src);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.minFilter = THREE.LinearFilter;
+  texture.generateMipmaps = false;
+
+  const quietSet = quietUniforms(THREE, 0.1);
+  const uniforms = {
+    ...quietSet.uniforms,
+    uMap: { value: texture },
+    uPresence: { value: 0 },
+    uPr: { value: renderer.getPixelRatio() },
+    uTime: { value: 0 },
+    uRes: { value: new THREE.Vector2(1, 1) },
+    uImg: { value: new THREE.Vector2(image.width, image.height) },
+    uPointer: { value: new THREE.Vector2(0, 0) },
+    uStrength: { value: 0 },
+    uScroll: { value: 0 },
+    uGrade: { value: grade },
+    uInk: { value: new THREE.Color(palette.ink) },
+    uSurface: { value: new THREE.Color(palette.surface) },
+  };
+
+  const material = new THREE.ShaderMaterial({
+    uniforms,
+    vertexShader: /* glsl */ `
+      varying vec2 vUv;
+      void main() { vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }
+    `,
+    fragmentShader: /* glsl */ `
+      uniform sampler2D uMap; uniform float uTime; uniform vec2 uRes; uniform vec2 uImg;
+      uniform vec2 uPointer; uniform float uStrength; uniform float uScroll; uniform float uGrade;
+      uniform vec3 uInk; uniform vec3 uSurface; uniform float uPresence; uniform float uPr;
+      varying vec2 vUv;
+      ${NOISE_GLSL}
+      ${QUIET_GLSL}
+      vec2 cover(vec2 uv) {
+        float rs = uRes.x / uRes.y; float ri = uImg.x / uImg.y;
+        vec2 s = rs > ri ? vec2(1.0, ri / rs) : vec2(rs / ri, 1.0);
+        return (uv - 0.5) * s + 0.5;
+      }
+      void main() {
+        vec2 uv = (vUv - 0.5) / (1.04 + uScroll * 0.12) + 0.5;
+        float calm = 1.0 - 0.8 * quiet(gl_FragCoord.xy);
+        float t = uTime * 0.05;
+        vec2 d = (vec2(noise(uv * 2.4 + t), noise(uv * 2.4 - t * 0.8)) - 0.5) * 0.008 * calm;
+        vec2 aspect = vec2(uRes.x / uRes.y, 1.0);
+        vec2 diff = (vUv - (uPointer * 0.5 + 0.5)) * aspect;
+        float dist = length(diff);
+        float wave = sin(dist * 30.0 - uTime * 2.0) * exp(-dist * 6.0) * (0.003 + uStrength * 0.012) * uPresence * calm;
+        d += normalize(diff + 1e-5) * wave;
+        vec2 c = cover(uv + d);
+        float split = abs(wave) * 0.6;
+        vec3 col = vec3(texture2D(uMap, c + vec2(split, 0.0)).r, texture2D(uMap, c).g, texture2D(uMap, c - vec2(split, 0.0)).b);
+        float l = dot(col, vec3(0.2126, 0.7152, 0.0722));
+        col = mix(col, mix(uInk, uSurface, smoothstep(0.02, 0.9, l)), uGrade);
+        col += (hash(vUv * uRes + fract(uTime * 7.0)) - 0.5) * 0.025;
+        gl_FragColor = vec4(col, 1.0);
+        #include <colorspace_fragment>
+      }
+    `,
+  });
+
+  const geometry = new THREE.PlaneGeometry(2, 2);
+  scene.add(new THREE.Mesh(geometry, material));
+
+  return {
+    scene,
+    camera,
+    update(state) {
+      uniforms.uTime.value = state.time;
+      uniforms.uPointer.value.set(state.pointer.x, state.pointer.y);
+      uniforms.uStrength.value = state.velocity;
+      uniforms.uPresence.value = state.presence;
+      quietSet.update(state);
+      uniforms.uScroll.value = state.scroll;
+    },
+    resize(width, height) {
+      uniforms.uRes.value.set(width, height);
+    },
+    dispose() {
+      geometry.dispose();
+      material.dispose();
+      texture.dispose();
+    },
+  };
+};

package/skills/struq/recipes/components/struq/scenes/types.ts

@@ -0,0 +1,114 @@
+// components/struq/scenes/types.ts (Struq recipe)
+// The contract every hero scene follows. HeroCanvas owns the renderer, the clock, the pointer,
+// the pause, the poster and the quiet zones; a scene owns only what it draws.
+import type * as THREE_NS from "three";
+
+export type Palette = {
+  /** CSS colour strings, already resolved to rgb() from the :root tokens. */
+  surface: string;
+  surface2: string;
+  ink: string;
+  accent: string;
+};
+
+export type SceneState = {
+  /** Seconds on gsap.ticker. Scenes scale it down: an ambient field moves at 0.02 to 0.06 of it. */
+  time: number;
+  /** Smoothed pointer, -1 to 1 on both axes, y up. A gentle modulation only, never the subject. */
+  pointer: { x: number; y: number };
+  /** 0 to 1: how far the pointer is engaged; eases in on move and out when it rests or leaves. */
+  presence: number;
+  /** 0 to 1: how far the hero has scrolled out of view. */
+  scroll: number;
+  /** 0 to 1: recent pointer speed, decays on its own. */
+  velocity: number;
+  /**
+   * Up to four rects behind the copy (elements marked data-quiet in the hero), in device pixels with
+   * a bottom-left origin like gl_FragCoord: [left, bottom, right, top] per rect, zeros when unused.
+   */
+  quiet: Float32Array;
+  /** The soft edge around each quiet rect, in device pixels. */
+  feather: number;
+};
+
+export type SceneInput = {
+  THREE: typeof THREE_NS;
+  renderer: THREE_NS.WebGLRenderer;
+  palette: Palette;
+  image?: { src: string; width: number; height: number };
+  grade: number;
+  /** True on a dark palette: the quiet level and the line weights differ per ground. */
+  dark: boolean;
+};
+
+export type HeroScene = {
+  scene: THREE_NS.Scene;
+  camera: THREE_NS.Camera;
+  update(state: SceneState): void;
+  /** Width and height in CSS pixels; read renderer.getPixelRatio() for device pixels. */
+  resize(width: number, height: number): void;
+  /** A multi-pass scene renders itself; otherwise HeroCanvas renders scene with camera. */
+  render?(renderer: THREE_NS.WebGLRenderer): void;
+  dispose(): void;
+};
+
+export type CreateScene = (input: SceneInput) => Promise<HeroScene>;
+
+/** Shared GLSL: hash, value noise and fbm. Run noise per field cell, never per screen pixel, where you can. */
+export const NOISE_GLSL = /* glsl */ `
+  float hash(vec2 p) { p = fract(p * vec2(123.34, 456.21)); p += dot(p, p + 45.32); return fract(p.x * p.y); }
+  float noise(vec2 p) {
+    vec2 i = floor(p); vec2 f = fract(p);
+    vec2 u = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);
+    return mix(mix(hash(i), hash(i + vec2(1.0, 0.0)), u.x), mix(hash(i + vec2(0.0, 1.0)), hash(i + vec2(1.0, 1.0)), u.x), u.y);
+  }
+  float fbm(vec2 p) {
+    float v = 0.0; float a = 0.5;
+    for (int i = 0; i < 4; i++) { v += a * noise(p); p = p * 2.03 + vec2(1.7, 9.2); a *= 0.5; }
+    return v;
+  }
+`;
+
+/**
+ * The hush behind the copy. Inside a quiet rect the field does not scale down to a dark box: it meets
+ * a soft ceiling (uQuietLevel), so faint light passes as it is and only the bright parts are held
+ * down. The feather lies outside each rect, so the copy itself sits at full quiet.
+ */
+export const QUIET_GLSL = /* glsl */ `
+  uniform vec4 uQuiet[4];
+  uniform float uFeather;
+  uniform float uQuietLevel;
+  float quietBox(vec2 p, vec4 r, float f) {
+    vec2 a = smoothstep(r.xy - f, r.xy, p);
+    vec2 b = 1.0 - smoothstep(r.zw, r.zw + f, p);
+    return a.x * a.y * b.x * b.y;
+  }
+  float quiet(vec2 p) {
+    float m = 0.0;
+    for (int i = 0; i < 4; i++) {
+      vec4 r = uQuiet[i];
+      if (r.z > r.x) m = max(m, quietBox(p, r, uFeather));
+    }
+    return m;
+  }
+  float hush(float v, vec2 p) {
+    float q = quiet(p);
+    return mix(v, uQuietLevel * (1.0 - exp(-v / uQuietLevel)), q);
+  }
+`;
+
+/** The uniforms QUIET_GLSL reads, and the update that copies HeroCanvas's rects into them. */
+export function quietUniforms(THREE: typeof THREE_NS, level: number) {
+  const uniforms = {
+    uQuiet: { value: [0, 1, 2, 3].map(() => new THREE.Vector4()) },
+    uFeather: { value: 48 },
+    uQuietLevel: { value: level },
+  };
+  const update = (state: SceneState) => {
+    for (let i = 0; i < 4; i++) {
+      uniforms.uQuiet.value[i].set(state.quiet[i * 4], state.quiet[i * 4 + 1], state.quiet[i * 4 + 2], state.quiet[i * 4 + 3]);
+    }
+    uniforms.uFeather.value = state.feather;
+  };
+  return { uniforms, update };
+}