@struq/skill 0.2.2 → 0.4.0

package/skills/struq/blocks/kit/gsap.ts

@@ -0,0 +1,21 @@
+// lib/gsap.ts (Struq recipe)
+// One registry for every GSAP plugin the site uses. Import gsap from here, never from "gsap"
+// directly, so a component rendered on its own still has its plugins registered.
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { SplitText } from "gsap/SplitText";
+import { useGSAP } from "@gsap/react";
+
+gsap.registerPlugin(ScrollTrigger, SplitText, useGSAP);
+
+// The Struq entrance: expo.out inside the reveal band.
+gsap.defaults({ ease: "expo.out", duration: 0.9 });
+
+export const EASE = {
+  enter: "expo.out",
+  exit: "power2.in",
+  swap: "power3.inOut",
+  curtain: "power4.inOut",
+} as const;
+
+export { gsap, ScrollTrigger, SplitText, useGSAP };

package/skills/struq/blocks/kit/images.ts

@@ -0,0 +1,17 @@
+// The image a block receives. In a client project the skill's images.mjs writes the list of these from a
+// beeldbank pack; the lab passes a few fixed beeldbank photos so every block is judged on real photography.
+
+export type StruqImage = {
+  src: string;
+  alt: string;
+  width: number;
+  height: number;
+  /** "16:9", "21:9", "3:2", "4:5" or "1:1" */
+  ratio: string;
+  /** What the photo shows, in more words than the alt: read it to choose the right slot. */
+  description: string;
+  /** The photo's calm side ("left", "right", "top", "bottom", "center"): where copy reads over it. */
+  negativeSpace?: string;
+  /** Set on fallback plates (SVG), which next/image must not optimise. */
+  unoptimized?: boolean;
+};

package/skills/struq/blocks/kit/photo-read.ts

@@ -0,0 +1,102 @@
+// photo-read (Struq kit)
+// Reading what a photograph holds under a box on the screen, for the blocks that choose an ink or a veil from the
+// photo itself. The whole image is drawn once to a small offscreen canvas and kept as a grid of luminances; a box is
+// then mapped onto that grid through the element's object-fit: cover and its object-position.
+//
+// Why the whole image: with a srcset, img.naturalWidth is density-corrected (a 1920w file shown at 1440 reports
+// 1440), while drawImage's source rectangle counts the file's real pixels. A sub-rectangle mapped from naturalWidth
+// therefore lands up and to the left of where it should. Drawing the whole image to fill the grid only uses the ratio
+// of naturalWidth to naturalHeight, which is right either way.
+//
+//   const ys = photoLuminances(img, frame, box);   // sorted ascending, or null when it cannot be read
+//   const median = ys && ys[Math.floor(ys.length * 0.5)];
+//
+// Returns null, so the caller keeps its safe treatment, when the photo is not loaded, comes from another origin
+// (reading it would taint the canvas) or the canvas cannot be read.
+
+export type PhotoBox = { x: number; y: number; w: number; h: number };
+
+const GRID_W = 320;
+
+const linear = (c: number) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+
+type Grid = { w: number; h: number; y: Float32Array };
+const grids = new WeakMap<HTMLImageElement, { src: string; grid: Grid | null }>();
+
+/** The photo's luminance on a small grid of the whole image, read once per source and kept. */
+function gridOf(img: HTMLImageElement): Grid | null {
+  const src = img.currentSrc || img.src;
+  const iw = img.naturalWidth;
+  const ih = img.naturalHeight;
+  if (!src || !img.complete || !iw || !ih) return null;
+  const kept = grids.get(img);
+  if (kept && kept.src === src) return kept.grid;
+  let grid: Grid | null = null;
+  try {
+    if (new URL(src, location.href).origin !== location.origin) throw new Error("other origin");
+    const w = GRID_W;
+    const h = Math.max(1, Math.round((w * ih) / iw));
+    const cv = document.createElement("canvas");
+    cv.width = w;
+    cv.height = h;
+    const ctx = cv.getContext("2d", { willReadFrequently: true });
+    if (ctx) {
+      ctx.drawImage(img, 0, 0, w, h);
+      const d = ctx.getImageData(0, 0, w, h).data;
+      const y = new Float32Array(w * h);
+      for (let k = 0; k < w * h; k += 1) {
+        y[k] = 0.2126 * linear(d[k * 4] / 255) + 0.7152 * linear(d[k * 4 + 1] / 255) + 0.0722 * linear(d[k * 4 + 2] / 255);
+      }
+      grid = { w, h, y };
+    }
+  } catch {
+    grid = null;
+  }
+  grids.set(img, { src, grid });
+  return grid;
+}
+
+/** The element's object-position as two shares (0 to 1); percentages and keywords, anything else is centred. */
+function positionOf(img: HTMLImageElement): [number, number] {
+  const parts = (getComputedStyle(img).objectPosition || "50% 50%").trim().split(/\s+/);
+  const share = (v: string | undefined) => {
+    if (!v) return 0.5;
+    if (v.endsWith("%")) {
+      const n = parseFloat(v) / 100;
+      return Number.isFinite(n) ? n : 0.5;
+    }
+    if (v === "left" || v === "top") return 0;
+    if (v === "right" || v === "bottom") return 1;
+    if (v === "center") return 0.5;
+    return 0.5;
+  };
+  return [share(parts[0]), share(parts[1] ?? parts[0])];
+}
+
+/**
+ * The luminances of the photo under `at`, sorted ascending. `frame` is the box the image is drawn into (object-fit:
+ * cover at its object-position), in the same coordinates as `at`; pass `position` to override the element's own.
+ */
+export function photoLuminances(
+  img: HTMLImageElement,
+  frame: PhotoBox,
+  at: PhotoBox,
+  position?: [number, number],
+): number[] | null {
+  if (frame.w <= 0 || frame.h <= 0 || at.w <= 0 || at.h <= 0) return null;
+  const g = gridOf(img);
+  if (!g) return null;
+  const [px, py] = position ?? positionOf(img);
+  // Frame pixels per grid cell, and where the covered image starts in the frame.
+  const c = Math.max(frame.w / g.w, frame.h / g.h);
+  const ox = frame.x + (frame.w - g.w * c) * px;
+  const oy = frame.y + (frame.h - g.h * c) * py;
+  const x0 = Math.max(0, Math.floor((at.x - ox) / c));
+  const x1 = Math.min(g.w, Math.max(x0 + 1, Math.ceil((at.x + at.w - ox) / c)));
+  const y0 = Math.max(0, Math.floor((at.y - oy) / c));
+  const y1 = Math.min(g.h, Math.max(y0 + 1, Math.ceil((at.y + at.h - oy) / c)));
+  if (x0 >= g.w || y0 >= g.h || x1 <= 0 || y1 <= 0) return null;
+  const ys: number[] = [];
+  for (let y = y0; y < y1; y += 1) for (let x = x0; x < x1; x += 1) ys.push(g.y[y * g.w + x]);
+  return ys.length ? ys.sort((a, b) => a - b) : null;
+}

package/skills/struq/blocks/kit/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/blocks/kit/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/blocks/kit/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/blocks/kit/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 };
+}