@struq/skill 0.3.0 → 0.4.1

package/skills/struq/references/hero-scenes.md

@@ -1,107 +0,0 @@
-# Hero scenes: the WebGL layer behind the hero
-
-Every Struq marketing site carries a WebGL layer in its hero. `components/struq/HeroCanvas.tsx` owns everything that makes such a layer safe in production; a scene owns only what it draws.
-
-| HeroCanvas owns | The scene owns |
-|---|---|
-| Loading three.js in its own chunk after first paint | Its `THREE.Scene` and camera |
-| The poster (the photo, or the flat surface) and the fade-in after the first frame | Its geometry, material and uniforms |
-| The DPR cap (1.75, phones 1.5) and a 2.4 million pixel budget | Reading the palette it is given |
-| Pausing offscreen and in a hidden tab | `update(state)`: time, pointer, scroll, velocity into uniforms |
-| One composed still frame under `prefers-reduced-motion` and on phones | `resize(w, h)`, an optional multi-pass `render(renderer)`, `dispose()` |
-| The quiet zones: up to four `[data-quiet]` rects behind the copy, in device pixels | Calling `hush(v, gl_FragCoord.xy)` on its intensity |
-| The pointer's `presence`, easing in on move and out on rest | Using it as a gentle modulation only |
-| Running on `gsap.ticker`, the page's one clock | |
-| Keeping the poster when WebGL or the scene fails | |
-
-## The three shipped scenes
-
-| Scene | Looks like | Needs | Suits |
-|---|---|---|---|
-| `contours` | contour lines drifting like a slow survey map, every sixth in the accent | nothing | architecture, studios, consultancy, nature, research |
-| `ripple` | the hero photo as a liquid surface, rippling under the pointer, pushing in on scroll | `image` | hospitality, food, hotels, fashion, wellness |
-| `dots` | a field of points rolling like a swell, a hill under the pointer | nothing | mobility, logistics, technology, sport, energy |
-
-Props: `scene`, `image` (poster, and the texture for ripple), `grade` (0 to 1, how far ripple pulls the photo into the palette), `scrim` (0 to 0.6, a flat black layer for type in `text-on-photo`), `priority` (the poster is the LCP image).
-
-## The craft bar
-
-What separates a high-end ambient hero from a screensaver, and what every shipped scene does:
-
-- **Clean:** fine marks (hairlines, small dots) on a flat ground, antialiased with `fwidth`, and where marks crowd closer than the screen can draw, they fade into a mist instead of moire.
-- **Deep:** a perspective field (a horizon just above the top edge or in the upper third), marks compressing and thinning toward it, a fog toward the far side.
-- **Calm behind the copy:** `hush` holds the field under a soft ceiling behind every `data-quiet` element, so the copy reads at 4.5:1 and the field still runs on behind it.
-- **Composed:** the field is weighted to the right or the vanishing point sits on the right third; the left, where the headline sits, is the quiet side.
-- **Slow:** the ambient clock is 0.02 to 0.06 of real time. The pointer only modulates (a soft lift, a ripple) and only while it is present.
-- **Cheap:** noise runs once per field cell into a small target, never per screen pixel, where the look allows (`contours` shows the two-pass pattern).
-
-## Writing a scene (or porting the MCP background)
-
-A scene is one file in `components/struq/scenes/` that exports `createScene`:
-
-```ts
-// components/struq/scenes/<name>.ts
-import { NOISE_GLSL, QUIET_GLSL, quietUniforms, type CreateScene } from "./types";
-
-export const createScene: CreateScene = async ({ THREE, renderer, palette, image, grade, dark }) => {
-  const scene = new THREE.Scene();
-  const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
-  const quiet = quietUniforms(THREE, dark ? 0.08 : 0.12);
-  const uniforms = {
-    ...quiet.uniforms,
-    uTime: { value: 0 },
-    uRes: { value: new THREE.Vector2(1, 1) },
-    uPointer: { value: new THREE.Vector2() },
-    uScroll: { value: 0 },
-    uSurface: { value: new THREE.Color(palette.surface) },
-    uInk: { value: new THREE.Color(palette.ink) },
-    uAccent: { value: new THREE.Color(palette.accent) },
-  };
-  const material = new THREE.ShaderMaterial({
-    uniforms,
-    vertexShader: `varying vec2 vUv; void main() { vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }`,
-    fragmentShader: `
-      uniform float uTime; uniform vec2 uRes; uniform vec2 uPointer; uniform float uScroll;
-      uniform vec3 uSurface; uniform vec3 uInk; uniform vec3 uAccent;
-      varying vec2 vUv;
-      ${NOISE_GLSL}
-      ${QUIET_GLSL}
-      void main() {
-        float v = 0.0; // ... the look's intensity, from noise per cell where you can
-        v = hush(v, gl_FragCoord.xy);
-        vec3 col = mix(uSurface, uInk, v); // the three palette colours only
-        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(s) { uniforms.uTime.value = s.time; uniforms.uPointer.value.set(s.pointer.x, s.pointer.y); uniforms.uScroll.value = s.scroll; quiet.update(s); },
-    resize(w, h) { uniforms.uRes.value.set(w, h); },
-    dispose() { geometry.dispose(); material.dispose(); },
-  };
-};
-```
-
-Then register it in `HeroCanvas.tsx`:
-
-```ts
-const SCENES = {
-  contours: () => import("./scenes/contours"),
-  ripple: () => import("./scenes/ripple"),
-  dots: () => import("./scenes/dots"),
-  "<name>": () => import("./scenes/<name>"),
-};
-```
-
-**The MCP background (`struq_achtergrond`).** It returns a background family with its shader or scene description and its parameters. Port it into this contract: its shader becomes the fragment shader, its colour inputs become `uSurface`, `uInk` and `uAccent` built from `palette` (that is the recolour: the site's tokens, never the colours in the MCP sample), its animation reads `uTime`, and its pointer or scroll inputs read `uPointer` and `uScroll`. Build it even when you cannot watch it: if it fails to compile, HeroCanvas logs the error and keeps the poster, so the hero is never empty. Check the browser console when you do have a browser.
-
-## Rules that keep it fast
-
-- Colours are linear inside the shader; end every fragment shader with `#include <colorspace_fragment>` and set `texture.colorSpace = THREE.SRGBColorSpace` on photo textures, or the palette renders too dark.
-- One full-screen pass, at most five noise octaves, no loops over pixels. Points: up to about 15,000.
-- One HeroCanvas per page. A second canvas further down is a deliberate WebGL moment ([webgl-r3f.md](webgl-r3f.md)), not a reflex.
-- Never a glossy 3D blob, a purple glow or a mesh-gradient wash: the scene works in the palette's neutrals with the accent as a thread.

package/skills/struq/references/imagery.md

@@ -1,125 +0,0 @@
-# Imagery & Art Direction: one grade, declared ratios, treated assets
-
-Imagery is now where generated builds fail hardest: the CSS can be flawless and the page still screams "AI" because the images are ungraded stock, glossy renders, or six unrelated looks. The fix is the same shape as the color system: **decide once, apply everywhere**. One grade, one ratio set, one sourcing standard.
-
-Media *behavior* (window parallax, masked reveals, aspect-ratio for CLS) lives in [depth-parallax.md](depth-parallax.md) and [scroll-reveals.md](scroll-reveals.md); this file is about what the pixels *are*.
-
----
-
-## 1. One grade per page
-
-Every image on a page passes through the **same treatment**, chosen to match the preset's temperature ([vibe-presets.md](vibe-presets.md)). Mixed grading (a warm lifestyle shot next to a cool product render next to a saturated stock photo) is the single most reliable imagery tell. It says the images were *collected*, not *directed*.
-
-Pick one:
-
-| Grade | Character | Pairs with |
-|---|---|---|
-| **Warm film** | lifted blacks, warm midtones, gentle contrast | Warm Editorial |
-| **Desaturated cool** | -20 to -40% saturation, cool shift, deep blacks | Dark Cinematic |
-| **High-contrast BW** | full monochrome, punchy | the Brutalist genre appendix only, when the brief declares the genre (color arrives only via the accent) |
-| **Soft neutral** | low contrast, airy highlights, near-monochrome palette subjects | Soft Modern (cool-leaning), Luxury Minimal (warm-leaning) |
-| **Duotone** | surface color + ink (or accent) mapped to shadows/highlights | any preset, as the *signature* look |
-
-Apply the grade in one reusable layer, not per-image in an editor:
-
-```tsx
-// The grade as a component. On a Struq build MediaFrame is this layer: add the filter to its <Image> className.
-// components/ui/GradedImage.tsx: every content image renders through this
-export function GradedImage({ src, alt, ratio = "4/3", className = "" }: {
-  src: string; alt: string; ratio?: string; className?: string;
-}) {
-  return (
-    <div className={`relative overflow-hidden ${className}`} style={{ aspectRatio: ratio }}>
-      <img src={src} alt={alt} className="h-full w-full scale-[1.18] object-cover
-                                          [filter:saturate(0.82)_contrast(1.05)]" />
-    </div>
-  );
-}
-```
-
-- The `filter` values are **per-project constants**: tune once against the preset, then never per-image. (Static CSS filters are fine; it's *scrubbed* filters that cost, see [setup.md](setup.md) §5.)
-- Duotone variant: `[filter:grayscale(1)_sepia(0.2)]` on the img. Never a tinted translucent layer over the photo: that is a tell of its own ([anti-patterns.md](anti-patterns.md) §20).
-- `scale-[1.18]` is the parallax headroom from [depth-parallax.md](depth-parallax.md) §2, so grading and panning share the same frame component.
-
-**Cheap tell:** every image at its source colors, six looks on one page. **Instead:** One `GradedImage` component; swap the page's grade by editing one filter line.
-
----
-
-## 2. The ratio set: declared like tokens
-
-Pick **2 to 3 aspect ratios per project** and use nothing else. A page whose media is 4/3, 16/9, 3/2, 1/1, and 21/9 at random reads as unplaced; the same images in a disciplined ratio set read as a system. (Explicit ratios are also the CLS guard, see [setup.md](setup.md) §6.)
-
-| Role | Default | Alternatives by genre |
-|---|---|---|
-| Standard content / work thumb | `4/3` | `3/2` editorial, `1/1` brutalist grid |
-| Full-bleed statement (1 per ~3 viewports) | `21/9` | `2/1` |
-| Portrait accent (people, product detail) | `3/4` | `4/5` |
-
-Declare them where the tokens live and reference by role, never ad-hoc:
-
-```css
-@theme {
-  --ratio-standard: 4/3;
-  --ratio-wide: 21/9;
-  --ratio-portrait: 3/4;
-}
-```
-
----
-
-## 3. Texture: grain, and when to stop
-
-One **global grain overlay** unifies mixed sources better than any filter. It puts every image (and the surfaces) on the same "stock":
-
-```tsx
-// One fixed element at the end of <body>. z-index above content, below nav (composition.md z-ladder).
-<div aria-hidden className="pointer-events-none fixed inset-0 z-40 opacity-[0.05] mix-blend-overlay"
-     style={{ backgroundImage: "url(/noise.png)", backgroundSize: "128px" }} />
-```
-
-- `noise.png`: a 128px tileable monochrome noise tile (or an inline SVG `feTurbulence` data-URI). Opacity 0.03 to 0.06: visible on a dark surface if you look, never legible as a pattern.
-- Grain suits film/cinematic/editorial registers; **skip it** for Luxury Minimal (clean air is the brand) and product-UI screenshots (they must stay crisp).
-- Budget: grain is the *only* always-on texture. Grain + vignettes + gradients + blobs = mud.
-
----
-
-## 4. Sourcing ladder: where images come from
-
-In order of preference:
-
-1. **Real assets**: the client's work, product, people, places. Always first; treatment (§1) makes even average photography cohesive.
-2. **Struq's beeldbank**: real, graded, CC0 sector packs from struq.nl, one pack per site so the grade stays single, downloaded into the project and credited. The first stop when the client has no photos, or not enough. How to pick, fetch and credit: [struq-imagery.md](struq-imagery.md).
-3. **Generated on-brief**, with any capable image model (Flux/SDXL-class local checkpoints or a hosted generator). The standard when real assets don't exist and no beeldbank pack fits. Treat each prompt as an art-direction document, not a subject description, and generate the whole set in one session with the same model and settings so it reads as one shoot. Prompt for the *page's* grade, not per-image whims:
-   - State the grade in every prompt: light temperature ("warm late-afternoon window light" / "cool overcast studio light"), palette bias matching the preset's neutrals, film character ("35mm film grain, muted colors" vs "clean digital").
-   - Keep **one lighting world** across the set. Consistent light does more for coherence than consistent subjects.
-   - Compose for the crop: prompt the ratio you'll place (§2), and leave dead space where type will sit if it's a lockup image ([composition.md](composition.md) §3).
-   - Avoid the AI-render look: no glossy 3D blobs, no purple-glow gradients, no hyperdetailed-everything. The §1 grade pass over generated output hides most remaining tells.
-4. **Treated stock**: last resort, and only *through* the grade layer. Untreated stock (beaming laptop people, handshake photos) is below the floor.
-
-**Beeldbank, stock and generated images show context, never the client's product.** The city, the canal, a rider, a room, a material: yes. A stranger's e-bike, a generated bottle or a stock ceramic presented as the product: never, because the visitor reads it as the thing they would buy. Until the real product is shot, it is type, a context image of the client's world, a declared 3D stand-in ([webgl-scenes.md](webgl-scenes.md) §4, "No model file yet"), or type.
-
-**Never:** browser-chrome screenshot mockups tilted in perspective, generic "dashboard glow" renders, or watermark-adjacent placeholder imagery. If a section has no honest image, the strongest move is **no image**: type, space, and surface carry it (same logic as the no-icon rule, [iconography.md](iconography.md) §1).
-
----
-
-## 4b. Never an empty frame
-
-A slot that will one day hold the client's own photo holds a beeldbank image today. There is no placeholder state on a Struq site: no grey box, no tonal frame with a "photo to come" caption, no placeholder component.
-
-- **Default:** `node <skill-dir>/scripts/images.mjs <pack>` fills every slot from the pack that matches the brief ([struq-imagery.md](struq-imagery.md)). It runs on every build, without asking: the images are free and CC0.
-- **struq.nl unreachable:** the same script writes graded fallback plates in the site palette (two planes of light, a horizon hairline, grain) at each slot's ratio, and `lib/struq-images.ts` points at them. They are abstract images, not boxes. Run the script again when the network is back and the photos replace them in place.
-- **The client's product, team or projects:** a beeldbank photo never stands in for those. Those sections use type, the WebGL layer or a context image of the client's world (the material, the place), and the gap is listed under Assumptions.
-- **Markup:** every image goes through `MediaFrame`, which requires an `image`, so an empty frame cannot be written by accident. `check.mjs` fails on placeholder components, "photo to come" captions and empty `aspect-` boxes.
-
----
-
-## 5. Accessibility & weight
-
-- **Content images:** real `alt` describing the subject. **Decorative/texture images** (ghost imagery, grain, backdrop media): `alt=""` or `aria-hidden`, so "image of background texture" never leaks to screen readers.
-- Ship AVIF/WebP with sensible `sizes`; a full-bleed hero stays at or under 250KB at 1920w and a content image at or under 150KB at 1440w, the budgets in [performance.md](performance.md) §1. Never 4MB.
-- Ambient/looping video obeys the motion doctrine: muted, `playsinline`, poster, paused under `prefers-reduced-motion`. It also counts as the page's one autonomous mover ([feel-layer.md](feel-layer.md) §5).
-
----
-
-**Cheap tell:** mixed-grade stock + a tilted browser-chrome screenshot + a purple-glow 3D blob, all at random ratios, alt-less.
-**Instead:** One grade constant, one grain layer, 2 to 3 declared ratios, assets real or generated on-brief, treated identically. The imagery reads as *photographed for this site*.

package/skills/struq/references/loaders.md

@@ -1,287 +0,0 @@
-# First-Load Loaders: session-gated, SSR-safe
-
-One arm of the page-flow system, the site's *arrival*. A loader is the route transition's cover phase with no swap ([route-transitions.md](route-transitions.md)): it starts closed and clears once assets are ready. Sibling: [page-entrances.md](page-entrances.md) for what the revealed page does next.
-
-**It is optional.** It is warranted on narrative/portfolio/launch sites and skipped on app/dashboard zones. Keep it short, tie it to real load progress, and play it **once per session**. Never a spinner: the overlay sits on top of finished content and reveals it.
-
----
-
-## 0. The lifecycle invariant: why flash-free loaders work
-
-A first-load loader has **two different state machines**. Never collapse them into one boolean:
-
-| State | Owner | What it may do |
-|---|---|---|
-| First paint: play or skip | synchronous script in `<head>` + CSS | Hide SSR loader markup on a revisit before the browser paints |
-| Live phase: loading → revealing → done | the mounted loader component | Keep the first-visit curtain mounted until its transform/opacity exit completes |
-
-The classic regression is using one `data-loader-seen` attribute for both jobs, then running `markLoaderSeen()` when the intro starts or when the exit starts. If CSS contains `html[data-loader-seen] [data-first-loader] { display:none }`, that write removes the live curtain immediately. The reveal timeline technically starts against `display:none`, so the user sees a flash/cut instead of a curtain.
-
-**Non-negotiable order:**
-
-1. SSR emits an already-opaque curtain. Any animated word/chars are also emitted in their hidden start state; do not wait for hydration to apply a GSAP `.from()` state.
-2. A synchronous `<head>` script stamps the skip attribute only for a session revisit or excluded app route. CSS suppresses that SSR overlay before first paint.
-3. On a genuine first visit, await real readiness plus a minimum floor, capped by a safety ceiling. The curtain remains static and opaque while waiting.
-4. Start one compositor-only exit (`transform` and/or `opacity`). Do not read layout or change overflow at release time.
-5. In the exit's `onComplete`, and only there: persist the session marker, stamp the skip attribute, release scroll, and unmount.
-
-This is why the system stays clean at both ends: the SSR gate prevents revisit flashes, while delayed persistence lets the live curtain finish.
-
----
-
-## 1. The session gate (shared by every loader)
-
-```ts
-// components/ui/loaders/useFirstVisit.ts
-const PREFIX = "loader:";
-export const LOADER_SEEN_ATTR = "data-loader-seen";
-
-// Inline this synchronously in <head>, before loader markup. It is the only code
-// allowed to activate the CSS skip gate before the first paint.
-export const PRE_PAINT_LOADER_SCRIPT = `try{if(sessionStorage.getItem('${PREFIX}intro')==='1')document.documentElement.setAttribute('${LOADER_SEEN_ATTR}','1')}catch(e){}`;
-
-export function loaderSeen(id?: string): boolean {
-  if (typeof window === "undefined" || !id) return false;
-  if (document.documentElement.hasAttribute(LOADER_SEEN_ATTR)) return true;
-  try { return sessionStorage.getItem(PREFIX + id) === "1"; } catch { return false; }
-}
-export function markLoaderSeen(id?: string): void {
-  if (typeof window === "undefined" || !id) return;
-  // CALL ONLY FROM THE CURTAIN EXIT'S onComplete.
-  document.documentElement.setAttribute(LOADER_SEEN_ATTR, "1");
-  try { sessionStorage.setItem(PREFIX + id, "1"); } catch { /* private mode → plays every time */ }
-}
-```
-
-```css
-/* SSR revisit gate. This selector is permanent suppression, not animation state. */
-html[data-loader-seen] [data-first-loader] {
-  display: none !important;
-}
-```
-
-Mount the loader in a persistent root/marketing layout, never inside a page template that remounts on every client navigation. A small same-document module guard may protect Strict Mode/HMR remounts while the first run is active; session persistence still happens only after the exit completes.
-
----
-
-## 2. Asset-aware counter (the default loader)
-
-Tie release to **real** readiness (`document.fonts.ready` + critical image decode/load) and a minimum on-screen floor, raced against a hard ceiling. The floor makes a warm-cache run legible; the ceiling means one stalled request can never pin the site.
-
-The key lifecycle, not the visual styling, is:
-
-```tsx
-"use client";
-import { useRef, useState } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-import { loaderSeen, markLoaderSeen } from "./useFirstVisit";
-
-const MIN_HOLD_MS = 1450;
-const SAFETY_CEILING_MS = 4000;
-const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
-
-function decodeCriticalHeroImage(src = "/hero-poster.webp"): Promise<void> {
-  return new Promise((resolve) => {
-    const image = new Image();
-    image.src = src;
-    image.decode().then(resolve).catch(resolve);
-  });
-}
-
-export function LoaderCounter({ id = "intro" }: { id?: string }) {
-  const root = useRef<HTMLDivElement>(null);
-  const [done, setDone] = useState(false);
-
-  useGSAP(() => {
-    if (loaderSeen(id)) { setDone(true); return; }
-    const layer = root.current;
-    if (!layer) return;
-
-    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-    let cancelled = false;
-    document.documentElement.classList.add("loader-scroll-lock");
-
-    const assetChecks = Promise.all([
-      (document as Document & { fonts?: FontFaceSet }).fonts?.ready ?? Promise.resolve(),
-      decodeCriticalHeroImage(), // resolve on decode OR error
-      wait(MIN_HOLD_MS),
-    ]);
-
-    Promise.race([assetChecks, wait(SAFETY_CEILING_MS)]).then(() => {
-      if (cancelled) return;
-      layer.dataset.loaderPhase = "revealing";
-      gsap.to(layer, {
-        yPercent: reduce ? 0 : -100,
-        autoAlpha: reduce ? 0 : 1,
-        duration: reduce ? 0.25 : 0.9,
-        ease: reduce ? "power2.out" : "power4.inOut",
-        onComplete: () => {
-          // Persist LAST. Earlier writes activate the CSS display:none gate and
-          // cut this live reveal off.
-          markLoaderSeen(id);
-          document.documentElement.classList.remove("loader-scroll-lock");
-          setDone(true);
-        },
-      });
-    });
-
-    return () => {
-      cancelled = true;
-      document.documentElement.classList.remove("loader-scroll-lock");
-    };
-  }, { scope: root });
-
-  if (done) return null;
-  return (
-    <div ref={root} data-first-loader data-loader-phase="loading"
-         className="fixed inset-0 z-[10001] bg-surface-0">
-      {/* Encode hidden start states in SSR markup/CSS. If SplitText must create
-          them after hydration, keep the whole word visibility:hidden until its
-          chars have been positioned, then reveal the wrapper. */}
-      <span className="loader-word" style={{ visibility: "hidden" }}>Brand</span>
-    </div>
-  );
-}
-```
-
-The readiness callback must only flip state/start a transform. Never run `getBoundingClientRect()`, `ScrollTrigger.refresh()`, image decoding, or synchronous asset work in the release frame.
-
-### Flash-free animated start states
-
-The curtain background itself must be present in SSR HTML. Any content that winds up (masked chars, mark, line, dot) must also start hidden before React runs:
-
-```css
-.loader-char { transform: translateY(118%); }
-.loader-dot { opacity: 0; transform: scale(0); }
-```
-
-For SplitText, SSR cannot emit the generated char wrappers. Set `visibility:hidden` on the unsplit word in JSX, create the split, position every char, then set the wrapper visible. A GSAP `.from()` without that SSR guard is too late: the browser can paint the completed word for one frame before hydration, producing the initial flash.
-
-### Scroll lock without scrollbar shift
-
-`scrollbar-gutter: stable` alone is not enough if the lock changes `<html>` to `overflow:hidden`; Chromium may collapse the gutter because the root is no longer scrollable. Keep the root scrollable and lock the body/content instead:
-
-```css
-html { scrollbar-gutter: stable; }
-html.loader-scroll-lock {
-  overflow-y: scroll;
-  touch-action: none;
-  overscroll-behavior: none;
-}
-html.loader-scroll-lock body {
-  height: 100dvh;
-  overflow: hidden;
-}
-```
-
-Apply the class while the opaque curtain is present and remove it only after the exit completes. Measure `document.documentElement.clientWidth` before/during/after the lock in browser coverage; all three values must match.
-
----
-
-## 3. Loader preset menu (pick one per project)
-
-All are SSR-safe overlays at `z-[10001]`, reveal on exit, respect reduced-motion, and use `mixBlendMode: "difference"` so the mark reads on any backdrop. Add the `loaderSeen`/`markLoaderSeen` gate (inside `useGSAP`) for any loader you want to play once per session.
-
-| Preset | Feel | Mechanic | Exit |
-|---|---|---|---|
-| **Counter** | data / precise | % count tied to real asset load | slide up `yPercent:-100` 0.9s `power4.inOut` |
-| **Mark** | minimal / brand | wordmark fades in, holds, layer fades | `opacity→0` 0.6s `power2.inOut` |
-| **Shutter** | architectural | grid of tiles holds brand, staggered grid-wipe | tiles `scaleY→0` 0.6s `power4.inOut` (the baseline curtain ease) |
-| **Odometer** | mechanical | rolling 0→100 reel | slide up 0.9s `power4.inOut` |
-| **WordCycle** | editorial | masked word reel settles on brand | slide up 0.9s `power4.inOut` |
-| **ProgressBar** | restrained | hairline fills 0→100% under a wordmark | slide up 0.8s `power4.inOut` |
-| **DrawMark** | crafted | SVG mark draws in (DrawSVG, recipe in [svg-motion.md](svg-motion.md)) + wordmark | layer fades 0.6s |
-
-> **Warning: avoid a scramble / "decode" / terminal-typewriter loader by default.** That monospaced, glitchy-text aesthetic reads as techy filler and collides with the monospace ban ([anti-patterns.md](anti-patterns.md)). Use it only when the brand is genuinely a terminal/dev product.
-
-Example of the gate wired into a preset (Shutter):
-
-```tsx
-// components/ui/loaders/LoaderShutter.tsx (abridged)
-"use client";
-import { useRef, useState } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-import { loaderSeen, markLoaderSeen } from "./useFirstVisit";
-
-export function LoaderShutter({ id, brand = "Brand", rows = 3, cols = 4 }: {
-  id?: string; brand?: string; rows?: number; cols?: number;
-}) {
-  const root = useRef<HTMLDivElement>(null);
-  const [done, setDone] = useState(false);
-
-  useGSAP(() => {
-    if (loaderSeen(id)) { setDone(true); return; } // revisit → hide before paint
-    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-    const tiles = gsap.utils.toArray<HTMLElement>(".sh-tile");
-    const tl = gsap.timeline();
-    tl.from(".sh-word", { autoAlpha: 0, y: 14, duration: reduce ? 0.2 : 0.5, ease: "power2.out" });
-    tl.to(".sh-word", { autoAlpha: 0, duration: reduce ? 0.2 : 0.4, ease: "power2.in" }, "+=" + (reduce ? 0.1 : 0.35));
-    tl.to(tiles, {
-      scaleY: 0, transformOrigin: "top", duration: reduce ? 0.3 : 0.6, ease: "power4.inOut", // curtains: quint-in-out
-      stagger: { each: reduce ? 0 : 0.04, grid: [rows, cols], from: "start" },
-      onComplete: () => {
-        markLoaderSeen(id); // persist only after the last tile has cleared
-        setDone(true);
-      },
-    }, "-=0.1");
-  }, { scope: root });
-
-  if (done) return null;
-  return (
-    <div ref={root} className="fixed inset-0 z-[10001]">
-      <div className="absolute inset-0 grid"
-           style={{ gridTemplateColumns: `repeat(${cols},1fr)`, gridTemplateRows: `repeat(${rows},1fr)` }}>
-        {Array.from({ length: rows * cols }).map((_, i) => (
-          <div key={i} className="sh-tile bg-surface-0 will-change-transform" />
-        ))}
-      </div>
-      <div className="sh-word pointer-events-none absolute inset-0 grid place-items-center font-display text-h2 text-ink"
-           style={{ mixBlendMode: "difference" }}>{brand}</div>
-    </div>
-  );
-}
-```
-
-**Why SSR-safe matters:** the overlay sits *on top of* the rendered HTML and reveals it. The page is fully in the SSR markup underneath, so there's no flash of unstyled content, no hydration mismatch, no SEO cost, and if JS fails the content is still there.
-
-Loaders mount inside `<body>`, above `children`. The root-layout wiring is in [route-transitions.md](route-transitions.md) §2.
-
----
-
-## Timing reference
-
-| Phase | Duration | Ease | Transform |
-|---|---|---|---|
-| Loader exit (slide) | 0.8-0.9s | `power4.inOut` | `yPercent 0→-100` |
-| Loader exit (fade) | 0.6s | `power2.inOut` | opacity |
-| **Reduced motion** | 0.2-0.3s | none | opacity only |
-
----
-
-## Anti-patterns (sweep before shipping)
-
-- **Spinner / loading gif** while content pops in → an asset-aware overlay that reveals finished content.
-- **Loader on every navigation** (stacked on the route wipe) → session-gate with `id`; loader is first-visit-only.
-- **FOUC / content reflowing in** as fonts/images land → SSR-safe overlay + explicit media aspect ratios; entrances double as load choreography.
-- **Completed wordmark flashes, then restarts** → its start state only exists in a hydration-time `.from()` tween; encode it in SSR CSS/inline visibility first.
-- **Curtain disappears instead of lifting** → the session `seen` attribute activated `display:none` before exit completion; persist only in `onComplete`.
-- **Page jumps horizontally at lock/unlock** → `overflow:hidden` collapsed the root scrollbar gutter; keep `<html>` at `overflow-y:scroll` and lock body/content.
-- **Warm loads blink / slow loads hang** → readiness has neither a minimum floor nor a hard safety ceiling; use both in one shared promise.
-- **Scramble/terminal-decode loader** as a default aesthetic → use a typographic preset instead (monospace ban).
-
-## When to use a loader
-
-- **Use** on narrative, portfolio, campaign, and launch sites, and only **once per session** (`id`). Keep it under ~1.5s of real work.
-- **Skip** on app/dashboard zones and utility pages. There, the route wipe alone (or even just the fast app entrance, [page-entrances.md](page-entrances.md)) is enough; a theatrical intro on a tool feels wrong.
-- Reduced motion: every preset branches to a 0.2-0.3s fade, no travel.
-
-## Regression coverage: required for loader work
-
-At minimum, automate these four checks in a real browser:
-
-1. First visit: loader is attached and visible; the persistent `seen` attribute is absent while it plays.
-2. Reveal: loader enters an explicit `revealing` phase, remains `display != none`, and its transform moves off-screen before unmount.
-3. Same-session revisit: the pre-paint attribute exists and no frame ever shows the SSR loader layer.
-4. Scroll lock: root `clientWidth` is identical before, during, and after lock; the lock class is removed when the loader finishes.
-
-Also inspect raw SSR HTML: the `<head>` pre-paint script must occur before loader markup, and animated content must carry its hidden first-paint state.