@struq/skill 0.3.0 → 0.4.0

package/skills/struq/references/scroll-reveals.md

@@ -1,279 +0,0 @@
-# Scroll-Driven Reveals
-
-The single highest-payoff motion category. Three techniques, in ascending order of drama: staggered group reveals, masked reveals, and split-text line reveals. All assume the providers from [setup.md](setup.md). Shipping values (durations, eases, staggers) justified in [feel-layer.md](feel-layer.md).
-
-**A reveal misbehaving?** Content stuck invisible, an offset that vanished, clipped descenders: [pitfalls.md](pitfalls.md) first, symptom by symptom.
-
----
-
-## 1. Staggered group reveal
-
-**Term:** Orchestrated entrance / stagger choreography.
-**Mechanic:** Sibling elements enter with a shared transform + opacity, offset in time by 0.06 to 0.1s each, triggered when the group scrolls into view. The offsets create a reading order. The eye is led, not flooded.
-
-**When:** Default for any group: nav items, card rows, list items, footer columns. Basically never overkill; this is the floor, not the ceiling.
-**Cost:** Negligible (transform/opacity only).
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-export function FeatureRow({ children }: { children: React.ReactNode }) {
-  const container = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      const mm = gsap.matchMedia();
-      // Reduced motion: nothing registers, the server markup is already the final state.
-      mm.add("(prefers-reduced-motion: no-preference)", () => {
-        gsap.from("[data-reveal]", {
-          y: 48,
-          autoAlpha: 0,
-          duration: 0.9,
-          ease: "expo.out",
-          stagger: { each: 0.08, from: "start" }, // try "center" or "edges" for non-linear rows
-          scrollTrigger: {
-            trigger: container.current,
-            start: "top 78%",   // fire while approaching, not at the edge; feels anticipatory
-            once: true,          // entrances happen once; re-triggering reads as a glitch
-          },
-        });
-      });
-    },
-    { scope: container }
-  );
-
-  return (
-    <div ref={container} className="grid grid-cols-12 gap-6">
-      {children /* each child carries data-reveal */}
-    </div>
-  );
-}
-```
-
-**Hard rule: one owner per property per element.** A `[data-reveal]` element never carries a CSS `transition-*` on a property this tween writes (`transition-opacity`, `transition-transform`, `transition-all`), and never a Tailwind `translate-*`, `scale-*` or `rotate-*` utility. The transition fights the inline values GSAP writes and can leave the element at `opacity: 0; visibility: hidden` with the tween at progress 1; GSAP sets the individual `translate`, `scale` and `rotate` properties to `none`, which erases the utility. Reveal the wrapper, put hover transitions and offsets on a child. Symptoms and checks: [pitfalls.md](pitfalls.md) §3.
-
-Notes that separate this from the reflex version:
-- `start: "top 78%"`: content is already moving as it enters the eye line. `"top bottom"` fires too early (animates off-screen), `"top top"` too late.
-- `once: true` for entrances. Scrub-tied effects may repeat; entrances may not.
-- Vary the stagger origin: a centered logo wall feels better with `from: "center"`.
-- Motion swap: for a one-off, `<motion.div initial={{ opacity: 0, y: 48 }} whileInView={{ opacity: 1, y: 0 }} viewport={{ once: true, margin: "-22%" }} transition={{ duration: 0.9, ease: [0.16, 1, 0.3, 1] }}>` is fine. Use GSAP once multiple groups need coordination.
-
-**Cheap tell:** every element fades in with `opacity: 0 → 1`, no transform, all at once, `duration-300 ease-in-out` (the "AOS fade" look). **Instead:** Transform + stagger + expo-out, triggered at 78%.
-
----
-
-## 2. Masked / clip-path reveal
-
-**Term:** Mask reveal (wipe).
-**Mechanic:** The element doesn't fade *into* view. It's *uncovered*, as if sliding out from behind an invisible edge. Two implementations: **overflow mask** (parent `overflow-hidden`, child translates up from 110%) and **clip-path wipe** (`inset()` animates open). The motion has a surface to interact with, which is what reads as physical.
-
-**When:** Images, hero media, big standalone statements. The signature "agency" reveal.
-**Overkill when:** applied to every paragraph. Masks are for moments; body content uses technique 1.
-**Cost:** `clip-path` and transforms are paint/composite-only. Cheap.
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-// A) Overflow mask: image slides up from behind its own bottom edge,
-//    while scaling down from 1.25 → 1 ("settle") for a parallax-like richness.
-export function MaskedImage({ src, alt }: { src: string; alt: string }) {
-  const container = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      const tl = gsap.timeline({
-        scrollTrigger: { trigger: container.current, start: "top 75%", once: true },
-        defaults: { duration: 1.2, ease: "expo.out" },
-      });
-      tl.from(container.current, { yPercent: 18, autoAlpha: 0 }, 0)
-        .from("img", { yPercent: 24, scale: 1.25 }, 0); // counter-move: frame up, image down
-    },
-    { scope: container }
-  );
-
-  return (
-    <div ref={container} className="overflow-hidden rounded-sm">
-      <img src={src} alt={alt} className="block h-full w-full object-cover" />
-    </div>
-  );
-}
-
-// B) Clip-path wipe, for blocks where overflow-hidden would clip siblings.
-export function WipeReveal({ children }: { children: React.ReactNode }) {
-  const el = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      gsap.fromTo(
-        el.current,
-        { clipPath: "inset(100% 0% 0% 0%)" },                  // covered from top
-        {
-          clipPath: "inset(0% 0% 0% 0%)",
-          duration: 1.1,
-          ease: "power4.inOut",                                 // wipes read best with in-out
-          scrollTrigger: { trigger: el.current, start: "top 80%", once: true },
-        }
-      );
-    },
-    { scope: el }
-  );
-
-  return <div ref={el}>{children}</div>;
-}
-```
-
-The **counter-move** in (A) is the load-bearing detail: container and image translate in opposite directions, so the image appears to be revealed *through* a window rather than sliding as a sticker. Same trick powers parallax-in-mask ([depth-parallax.md](depth-parallax.md)).
-
-**Cheap tell:** image scales from 0.8 with a fade ("zoom-in card"), or slides as one rigid block. **Instead:** Frame and content counter-translate inside an overflow mask.
-
----
-
-## 2C. Curtain section reveal (named preset)
-
-**Term:** Curtain section reveal (a.k.a. "the curtain reveal").
-**Mechanic:** The clip-path wipe (2B) *paired with a counter-scale on the inner image*, fired per media frame as a row/section enters view. The frame is **uncovered bottom-up** (`inset(100% 0 0 0)` → `inset(0)`) while the image behind **settles back from a slight zoom** (`scale 1.2 → 1`), both from the same trigger. The picture is drawn up like a rising curtain while the image "breathes" into place behind it. The two tweens are the whole effect: clip alone is flat; clip + counter-scale is what reads as premium and physical.
-
-**When:** Editorial media rows, alternating image/text sections, case-study frames, discipline mosaics. The default "professional section entrance" for imagery on a narrative page. Ready-made named showpiece recipes built on presets like this one are catalogued in [showcase.md](showcase.md).
-**Overkill when:** tiny thumbnails, logo walls, or anything below ~240px tall. The wipe needs vertical distance to read.
-**Cost:** `clip-path` + `transform` only (paint/composite). Cheap. Composes cleanly with a parallax `yPercent` drift on the *same* inner element (translate + scale coexist).
-
-```tsx
-// Clip on the OUTER frame, counter-scale on the INNER image, one timeline, once per frame.
-gsap.utils.toArray<HTMLElement>("[data-curtain]").forEach((frame) => {
-  const inner = frame.querySelector("[data-curtain-inner]");
-  const tl = gsap.timeline({
-    scrollTrigger: { trigger: frame, start: "top 88%", once: true },
-    defaults: { ease: "power4.out" },
-  });
-  tl.fromTo(
-    frame,
-    { clipPath: "inset(100% 0% 0% 0%)" },       // covered from the bottom up
-    { clipPath: "inset(0% 0% 0% 0%)", duration: 1.1 },
-  );
-  if (inner) tl.fromTo(inner, { scale: 1.2 }, { scale: 1, duration: 1.4 }, "<"); // settle, same start
-});
-```
-
-Details that matter:
-- **Clip on the frame, scale on the inner child**: never both on one node, or the scale visibly drags the clip edge. Structure: `<div data-curtain><div data-curtain-inner><img/></div></div>`.
-- `"<"` starts the scale at the **same instant** as the clip; the slightly longer scale duration (1.4 vs 1.1) means the image keeps easing after the curtain is fully open. That trailing settle is the premium tell.
-- `start: "top 88%"` fires just before the frame is comfortably in view; `once: true` (entrances never re-fire).
-- **Do not also wrap the frame in a fade-in** (e.g. a `FadeIn`/`whileInView` opacity). The curtain *is* the entrance; a fade on top muddies it. Give the media its curtain and nothing else.
-- **Reduced-motion:** register the tween only under `(prefers-reduced-motion: no-preference)` and set no initial clip in CSS, so motion-off renders the image fully visible with zero JS. No FOUC.
-- Pairs with: a parallax drift on `[data-curtain-inner]` ([depth-parallax.md](depth-parallax.md)) and an entrance-drawn connector line between frames (DrawSVG, recipes in [svg-motion.md](svg-motion.md); API surface in [gsap-api.md](gsap-api.md)).
-
-**Cheap tell:** the frame just fades/zooms in as one block, or the clip runs with no scale. **Instead:** Bottom-up clip on the frame + counter-scale settle on the image, same trigger, image easing a beat longer.
-
----
-
-## 3. Line-by-line text split (SplitText)
-
-**Term:** Masked line reveal / line stagger.
-**Mechanic:** SplitText slices a heading into line elements, each wrapped in an `overflow: clip` mask; lines translate up from 110% below their own mask, staggered. The text appears to rise out of the page in slats, the canonical award-site headline entrance.
-
-**When:** Hero h1, section headlines, pull quotes. 3 to 6 uses per page.
-**Overkill when:** body paragraphs (use a plain fade-up), or per-**char** splits on long text (chars are for short display words only; char-staggering a sentence looks like a typewriter toy).
-**Cost:** Splitting mutates DOM and measures layout. Fine for headlines, do not split hundreds of nodes. `aria` handling is automatic (SplitText sets `aria-label` on the parent).
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP, SplitText } from "@/lib/gsap";
-
-export function SplitHeadline({
-  children,
-  as: Tag = "h2",
-  className = "",
-}: {
-  children: string;
-  as?: "h1" | "h2" | "h3" | "p";
-  className?: string;
-}) {
-  const container = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      const mm = gsap.matchMedia();
-      mm.add("(prefers-reduced-motion: no-preference)", () => {
-        SplitText.create(container.current!.querySelector("[data-split]"), {
-          type: "lines",
-          mask: "lines",        // wraps each line in an overflow-clipped .split-line-mask
-          autoSplit: true,      // re-splits on font load / resize; animation must live in onSplit
-          linesClass: "split-line",
-          onSplit: (self) =>
-            gsap.from(self.lines, {
-              yPercent: 110,
-              duration: 1.1,
-              ease: "expo.out",
-              stagger: 0.09,
-              scrollTrigger: { trigger: container.current, start: "top 80%", once: true },
-            }),
-        });
-      });
-    },
-    { scope: container }
-  );
-
-  return (
-    <div ref={container}>
-      <Tag data-split className={className}>
-        {children}
-      </Tag>
-    </div>
-  );
-}
-
-// Usage:
-// <SplitHeadline className="font-display text-h2 max-w-[20ch]">
-//   Design that survives contact with reality
-// </SplitHeadline>
-```
-
-```css
-/* globals.css: descender room inside each line mask (class = linesClass + "-mask"), no layout jump */
-.split-line-mask { padding-block: 0.1em; margin-block: -0.1em; }
-```
-
-Details that matter:
-- `mask: "lines"` + `yPercent: 110` is the whole effect. Without the mask it's just a stagger fade; with it, each line is born at its own baseline.
-- `autoSplit: true` + returning the tween from `onSplit` makes the split responsive and font-safe: GSAP reverts and re-runs on reflow. This API needs GSAP 3.13 or later; do not use the old `new SplitText()` + manual resize listeners.
-- Set the headline with its role token (`text-display`, `text-h2`) *before* splitting: the token carries the pairing's tight leading, and masks clip to line boxes, so loose leading shows gaps.
-- Descenders: the `.split-line-mask` rule above pads each mask and pulls the margin back, so g/y/p are never clipped and the layout does not move. It is not the only place a descender dies: parent overflow, reveal wrappers sized to the line height, clip-path insets and italic overhang all clip too. The full list and the 10-second "Gyp, jq." test: [pitfalls.md](pitfalls.md) §1.
-- Section headlines use this scroll version; the hero has its own load-time variant (`line-rise-hero`, [typography.md](typography.md) §5), and the masked rise is one technique among the presets' named entrances. It is a tell only as the hero's sole gesture, with no signature move and no preset entrance behind it.
-- Reduced motion: the split and the tween exist only in the `no-preference` branch, so the server markup stays the final state.
-- Scrub variant for manifesto paragraphs: split into `words`, set initial `opacity: 0.15`, and `gsap.to(words, { opacity: 1, stagger: 0.05, scrollTrigger: { scrub: true, start: "top 70%", end: "top 20%" } })`, the "reading highlights itself" effect.
-- Motion swap: only if you refuse GSAP. Manually wrap lines and animate `y` with `whileInView`. SplitText's measurement/re-split handling is why GSAP wins here.
-- SplitText typography choreography in depth: [typography.md](typography.md).
-
-**Cheap tell:** whole headline fades in as one block; or chars typewriter in one-by-one with uniform linear timing. **Instead:** Lines rise from individual masks, 0.09s apart, expo-out.
-
----
-
-## Orchestrating a full section
-
-Reveals compose into one timeline per section so the elements *relate* (label → headline → body → media), instead of each element wearing its own trigger:
-
-```tsx
-useGSAP(
-  () => {
-    const tl = gsap.timeline({
-      scrollTrigger: { trigger: container.current, start: "top 70%", once: true },
-      defaults: { ease: "expo.out", duration: 1 },
-    });
-
-    tl.add(splitHeadlineIn())
-      .from("[data-body]", { y: 32, autoAlpha: 0 }, "-=0.6")
-      .from("[data-media]", { yPercent: 12, autoAlpha: 0, duration: 1.2 }, "-=0.8");
-  },
-  { scope: container }
-);
-```
-
-The `-=0.x` overlaps are the craft: sequential-but-overlapping reads as one composed gesture; strictly sequential reads as a PowerPoint build.

package/skills/struq/references/sections.md

@@ -1,141 +0,0 @@
-# Sections: patterns for the arc
-
-Copy a pattern, then make it the brief's own: the copy, the photos, the proportions. Each one uses the recipes (`components/struq/`) and the role tokens, never a raw size, never a label above a heading. Vary them: two neighbours never share a layout.
-
-Imports for every pattern on this page:
-
-```tsx
-import { HorizontalGallery } from "@/components/struq/HorizontalGallery";
-import { MagneticButton } from "@/components/struq/MagneticButton";
-import { MediaFrame } from "@/components/struq/MediaFrame";
-import { PinnedZoom } from "@/components/struq/PinnedZoom";
-import { Reveal } from "@/components/struq/Reveal";
-import { SplitHeadline } from "@/components/struq/SplitHeadline";
-import { imageCredit, images } from "@/lib/struq-images";
-```
-
-## Header
-
-Every page has one. It sits over the hero, not a bar: the name in the display face as the wordmark (marked `data-wordmark`, which `check.mjs` looks for), two or three links, the CTA. No pill, no blur. Internal links use `next/link` (the lint rule fails a plain `<a>` to a page).
-
-```tsx
-import Link from "next/link";
-
-<header className="absolute inset-x-0 top-0 z-20 flex items-center justify-between px-6 py-6 md:px-[8vw]">
-  <Link href="/" data-wordmark="" className="font-display text-h3">Zout</Link>
-  <nav className="flex items-center gap-8 text-small">
-    <a href="#kaart" className="hidden md:inline">Kaart</a>
-    <a href="#zaal" className="hidden md:inline">De zaal</a>
-    <MagneticButton href="#reserveren" variant="line">Reserveer</MagneticButton>
-  </nav>
-</header>
-```
-
-On a ripple hero, give the header `text-on-photo`. A multi-page site with a menu: [nav-header.md](nav-header.md).
-
-## Orient: a statement beside an image that bleeds off the edge (grid break)
-
-```tsx
-<section className="grid gap-12 px-6 py-32 md:grid-cols-12 md:gap-8 md:px-[8vw] md:py-48">
-  <Reveal className="flex flex-col gap-6 md:col-span-5 md:pt-[14vh]">
-    <h2 className="font-display text-h2">Eén kaart, die meebeweegt met de markt.</h2>
-    <p className="max-w-[44ch] text-body text-ink-muted">Wat de vissers en telers die week brengen, staat zaterdag op tafel. De kaart is kort, en elke week een beetje anders.</p>
-  </Reveal>
-  <MediaFrame image={images.column[0]} ratio="4/5" sizes="(min-width: 768px) 50vw, 100vw" className="md:col-span-6 md:col-start-7 md:-mr-[8vw]" />
-</section>
-```
-
-## Prove: hairline rows instead of cards
-
-For a menu, services, a process, projects. Title left, text offset right, the figure (a price, a year) in tabular figures at the end. Only facts the brief gave: no invented prices.
-
-```tsx
-<section className="px-6 py-28 md:px-[8vw] md:py-40">
-  <SplitHeadline as="h2" on="scroll" className="font-display text-h2 max-w-[16ch]">Deze week op de kaart</SplitHeadline>
-  <Reveal as="ul" className="mt-16 divide-y divide-line border-y border-line">
-    {rows.map((row) => (
-      <li key={row.title} className="grid gap-3 py-8 md:grid-cols-12 md:gap-8">
-        <span className="font-display text-h3 md:col-span-5">{row.title}</span>
-        <span className="max-w-[48ch] text-body text-ink-muted md:col-span-5 md:col-start-7">{row.text}</span>
-      </li>
-    ))}
-  </Reveal>
-</section>
-```
-
-## Band: a full-bleed photo with one line overlapping its edge
-
-```tsx
-<section className="relative">
-  <MediaFrame image={images.band[0]} ratio="21/9" sizes="100vw" className="w-full" />
-  <Reveal className="relative z-10 -mt-[10vh] px-6 md:px-[8vw]">
-    <p className="font-display text-h2 max-w-[18ch] bg-surface-0 pt-8 pr-10 md:max-w-[22ch]">Brood uit de eigen oven, elke ochtend vroeg.</p>
-  </Reveal>
-</section>
-```
-
-## Deepen: a tall photo and two details, offset
-
-```tsx
-<section className="grid gap-8 px-6 py-32 md:grid-cols-12 md:px-[8vw] md:py-48">
-  <MediaFrame image={images.column[1]} ratio="4/5" sizes="(min-width: 768px) 40vw, 100vw" className="md:col-span-5" />
-  <div className="flex flex-col gap-8 md:col-span-6 md:col-start-7 md:pt-[20vh]">
-    <Reveal className="flex flex-col gap-5">
-      <h2 className="font-display text-h2">Van de oven naar tafel.</h2>
-      <p className="max-w-[44ch] text-body text-ink-muted">Wat er uit het vuur komt, gaat direct de zaal in.</p>
-    </Reveal>
-    <div className="grid grid-cols-2 gap-6">
-      <MediaFrame image={images.detail[0]} ratio="1/1" sizes="25vw" />
-      <MediaFrame image={images.detail[1]} ratio="1/1" sizes="25vw" className="mt-[12vh]" />
-    </div>
-  </div>
-</section>
-```
-
-## Invite: the too-empty section
-
-One line, one button, a lot of air. This is the section that should feel empty by SaaS standards.
-
-```tsx
-<section id="reserveren" className="flex flex-col items-start gap-12 px-6 py-[24vh] md:px-[8vw]">
-  <SplitHeadline as="h2" on="scroll" className="font-display text-display max-w-[12ch]">Een tafel voor vanavond?</SplitHeadline>
-  <MagneticButton href="mailto:...">Reserveer een tafel</MagneticButton>
-</section>
-```
-
-Use only the contact route the brief gave. No booking system named in the brief: a mail link or "bel ons", never a fake form that sends nothing.
-
-## Footer: designed as hard as the hero
-
-```tsx
-<footer className="overflow-hidden bg-surface-1 px-6 pt-24 pb-10 md:px-[8vw]">
-  <div className="grid gap-10 md:grid-cols-12">
-    <p className="text-lead md:col-span-5">Veertig plekken in Amsterdam-Noord.</p>
-    <nav className="flex flex-col gap-2 text-small md:col-span-3 md:col-start-8">
-      <a href="#kaart">Kaart</a>
-      <a href="#reserveren">Reserveren</a>
-    </nav>
-  </div>
-  <p aria-hidden className="font-display mt-24 text-[22vw] leading-[0.8] tracking-[-0.04em]">Zout</p>
-  <div className="mt-10 flex flex-wrap justify-between gap-4 border-t border-line pt-6 text-small text-ink-muted">
-    <span>Zout, Amsterdam-Noord</span>
-    <a href={imageCredit.href}>{imageCredit.label}</a>
-  </div>
-</footer>
-```
-
-The giant wordmark is the one place a vw size is right: it is a shape, not a reading size.
-
-## Showpieces
-
-```tsx
-<HorizontalGallery
-  title="Uit de keuken"
-  intro="Wat de oven en de markt deze week brengen."
-  items={images.card.slice(0, 6).map((image) => ({ image, title: image.alt }))}
-/>
-
-<PinnedZoom image={images.band[1]} statement="Eén zaal, veertig plekken." closing="Reserveer voor vanavond." />
-```
-
-Write `title` and `text` from the brief; the pack alt is a description of the photo, fine as a caption only when it says nothing false about the client.

package/skills/struq/references/seo.md

@@ -1,219 +0,0 @@
-# SEO, social images and site structure
-
-A cinematic site that nobody finds, or that shows a blank grey card when it is shared, has failed at the first impression. These are the basics every Struq build ships, wired the Next.js App Router way (Vite notes at the end). They are cheap, and most of them have to be decided in the plan, not patched after launch.
-
-## 1. Site structure (decided in the PLAN phase)
-
-- **Flat and named.** Every page is at most two levels deep: `/work`, `/work/<slug>`, `/studio`, `/contact`. Slugs are lowercase words in the site's language, never ids.
-- **One page, one job, one h1.** By default the hero display line **is** the h1: write it so it says what the page is about in words someone would search. Only when the display line is deliberately not descriptive (a poetic claim, a single word) does the h1 become a smaller line above it, with the display line as a `p` in display styling.
-- **Headings in order.** h1, then h2 per section, h3 inside. A caption or meta line is a `p`, not a heading. Visual size and heading level are separate decisions.
-- **Every important page linked from the nav or the footer** with a real `<a href>` (the `TransitionLink` from [route-transitions.md](route-transitions.md) renders one). A route reachable only through a JavaScript click handler does not exist to a crawler.
-- **A real 404** (`app/not-found.tsx`) designed as hard as the hero, with a way back.
-
-Record the page list and slugs under PLAN in STRUQ.md ([direction.md](direction.md)).
-
-## 2. Metadata
-
-Set the base once in the root layout, then per page:
-
-```tsx
-// app/layout.tsx
-import type { Metadata } from "next";
-
-export const metadata: Metadata = {
-  metadataBase: new URL("https://example.com"),
-  title: { default: "Name: what it is in five words", template: "%s | Name" },
-  description: "One or two plain sentences, 140 to 160 characters, written for a person, not a keyword list.",
-  // No alternates.canonical here: metadata merges down, so a root canonical of "/"
-  // would mark every page as a duplicate of the home page. Set it per page.
-  openGraph: { type: "website", siteName: "Name", locale: "en_US" },
-  twitter: { card: "summary_large_image" },
-};
-```
-
-```tsx
-// app/page.tsx: the home page sets its own canonical too
-import type { Metadata } from "next";
-
-export const metadata: Metadata = {
-  alternates: { canonical: "/" },
-};
-```
-
-```tsx
-// app/work/[slug]/page.tsx
-import type { Metadata } from "next";
-
-export async function generateMetadata(
-  { params }: { params: Promise<{ slug: string }> }
-): Promise<Metadata> {
-  const { slug } = await params;
-  const project = await getProject(slug);
-  return {
-    title: project.title,
-    description: project.summary,
-    alternates: { canonical: `/work/${slug}` },
-  };
-}
-```
-
-- `metadataBase` makes every relative OG and canonical URL absolute. Without it, shared links break.
-- Titles: the page's own name first, the brand after (`%s | Name`). Under about 60 characters.
-- One canonical per page, set in that page's own `metadata` or `generateMetadata`, never in the root layout. Multi-language sites add `alternates.languages`.
-- Add the theme color to `viewport` so mobile browser chrome matches the surface: `export const viewport = { themeColor: "#0A0A0B" }`.
-
-## 3. Open Graph images: one per route, designed as posters
-
-The OG image is the site's first impression in every chat app and social feed. Design it like a poster from the same system as the site: the surface color, the display face at a light weight, the wordmark, one line, generous margins. Never a screenshot of the hero, never a default grey card.
-
-Every route that gets shared gets its own image via the file convention: an `opengraph-image.tsx` next to the route's `page.tsx`.
-
-```tsx
-// app/opengraph-image.tsx (and app/work/[slug]/opengraph-image.tsx for per-project cards)
-import { ImageResponse } from "next/og";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-
-export const alt = "Name: what it is";
-export const size = { width: 1200, height: 630 };
-export const contentType = "image/png";
-
-export default async function Image() {
-  // next/og needs the font as data: a TTF, OTF or WOFF of the display face in the repo (Fontsource WOFF works, brand.md §3).
-  const display = await readFile(join(process.cwd(), "assets/fonts/Display-Light.ttf"));
-
-  return new ImageResponse(
-    (
-      <div
-        style={{
-          width: "100%",
-          height: "100%",
-          display: "flex",
-          flexDirection: "column",
-          justifyContent: "space-between",
-          padding: 72,
-          background: "#0A0A0B",
-          color: "#EDEAE4",
-          fontFamily: "Display",
-        }}
-      >
-        <div style={{ fontSize: 28, letterSpacing: "0.12em", textTransform: "uppercase", opacity: 0.6 }}>
-          Name
-        </div>
-        <div style={{ fontSize: 96, lineHeight: 1, letterSpacing: "-0.03em", fontWeight: 300, maxWidth: 900 }}>
-          The one line the page is about.
-        </div>
-      </div>
-    ),
-    { ...size, fonts: [{ name: "Display", data: display, weight: 300, style: "normal" }] }
-  );
-}
-```
-
-- `ImageResponse` renders a flexbox subset of CSS: every element with more than one child needs `display: "flex"`. No grid, no `clamp()`.
-- It needs TTF, OTF or WOFF font data, not WOFF2. Keep a TTF of the display face in the repo for this.
-- Per-project images pull the project's title and, if it reads at card size, its cover image as an `<img>` with an absolute URL. In a dynamic segment the image receives the params as a promise, like the page does:
-
-```tsx
-// app/work/[slug]/opengraph-image.tsx
-export default async function Image({ params }: { params: Promise<{ slug: string }> }) {
-  const { slug } = await params;
-  const project = await getProject(slug);
-  // ...same ImageResponse as above, with project.title as the line
-}
-```
-- Twitter and X use the same image when `twitter.card` is `summary_large_image`; add `twitter-image.tsx` only when it should differ.
-- Check every card at real size before shipping: text over 60 characters wraps badly at 96px.
-
-## 4. Sitemap and robots
-
-```ts
-// app/sitemap.ts
-import type { MetadataRoute } from "next";
-
-export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
-  const base = "https://example.com";
-  // A constant, not new Date(): with cacheComponents on, a request-time date breaks the prerender
-  // (setup.md §0, Known API shifts). Bump it when the content changes.
-  const LAST_UPDATED = "2026-01-15";
-  const projects = await getProjects();
-  return [
-    { url: base, lastModified: LAST_UPDATED, changeFrequency: "monthly", priority: 1 },
-    { url: `${base}/work`, lastModified: LAST_UPDATED, changeFrequency: "weekly", priority: 0.8 },
-    ...projects.map((p) => ({
-      url: `${base}/work/${p.slug}`,
-      lastModified: p.updatedAt,
-      changeFrequency: "yearly" as const,
-      priority: 0.6,
-    })),
-    { url: `${base}/contact`, lastModified: LAST_UPDATED, changeFrequency: "yearly", priority: 0.5 },
-  ];
-}
-```
-
-```ts
-// app/robots.ts
-import type { MetadataRoute } from "next";
-
-export default function robots(): MetadataRoute.Robots {
-  return {
-    rules: { userAgent: "*", allow: "/" },
-    sitemap: "https://example.com/sitemap.xml",
-  };
-}
-```
-
-Every page in the PLAN's page list appears in the sitemap; nothing that 404s does. A staging deploy must disallow everything (`disallow: "/"`) so it never gets indexed.
-
-## 5. Structured data
-
-One JSON-LD block per page type, server-rendered:
-
-```tsx
-// in a server component
-const jsonLd = {
-  "@context": "https://schema.org",
-  "@type": "Organization", // LocalBusiness for a place, Person for a portfolio, Product for a product page
-  name: "Name",
-  url: "https://example.com",
-  logo: "https://example.com/brand/mark.png",
-  sameAs: ["https://www.instagram.com/name"],
-};
-
-<script
-  type="application/ld+json"
-  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, "\\u003c") }}
-/>
-```
-
-Add `BreadcrumbList` on nested pages and `FAQPage` only when the page really has a visible FAQ. Never mark up content that is not on the page.
-
-## 6. Where cinematic sites lose SEO, and the fix
-
-| Risk | Fix |
-|---|---|
-| A loader that covers the page delays the Largest Contentful Paint | The hero renders and paints underneath; the loader is an overlay, session-gated, and never blocks HTML ([loaders.md](loaders.md)). Never render the hero only after the loader finishes. |
-| SplitText turns the h1 into dozens of spans for screen readers | Use SplitText's `aria` option (the default `"auto"` keeps an accessible label on the parent); never split before fonts are ready ([typography.md](typography.md)) |
-| Content that only exists after a scroll animation, or starts at `opacity: 0` in server HTML with no fallback | Animate `from` so final state is the default; content stays readable with JavaScript off and under reduced motion ([setup.md](setup.md) §4) |
-| Text inside a WebGL canvas | Real copy lives in the DOM; 3D text is decoration with the same words in the DOM next to it ([webgl-scenes.md](webgl-scenes.md)) |
-| Heavy 3D or video on first load | Lazy islands with posters ([webgl-r3f.md](webgl-r3f.md)); the poster image is the LCP candidate, sized and preloaded |
-| Route transitions built on client-only navigation | `TransitionLink` keeps a real `href`; every route is server-rendered and works on direct load |
-| Images without dimensions | `next/image` with width and height or `fill` in a sized frame; descriptive `alt` for content images, empty `alt` for decoration |
-| Fonts swapping and shifting the layout | `next/font` with `adjustFontFallback` ([typography.md](typography.md)) |
-
-**Performance floor to check in verify:** LCP under 2.5s, CLS under 0.1, INP under 200ms on a mid-range phone profile. Run Lighthouse or PageSpeed once on the production build for LCP and CLS; lab Lighthouse reports TBT, not INP, so INP comes from field data or a manual interaction trace ([performance.md](performance.md) §8). Record the numbers under VERIFY in STRUQ.md.
-
-## 7. Vite
-
-No metadata API: set title, description, canonical and OG tags per route in the HTML or with a head manager, ship static OG PNGs per shared page, and generate `sitemap.xml` at build time (a small script over the route list, or a sitemap plugin). A client-only SPA is weak for SEO; if search matters, prerender the routes or use Next.js.
-
-## Checklist
-
-- [ ] `metadataBase`, title template and description in the root layout; a canonical on every page (home included), none in the layout
-- [ ] An `opengraph-image` per shared route, designed from the system, checked at real size
-- [ ] `sitemap.ts` covers every page; `robots.ts` points at it; staging disallows all
-- [ ] One h1 per page (the hero display line, unless it is not descriptive), headings in order, captions are not headings
-- [ ] JSON-LD for the page type
-- [ ] Every route reachable by a real link and server-rendered on direct load
-- [ ] Loader and animations never hide content from the server HTML
-- [ ] LCP, CLS and INP recorded under VERIFY