@sonordev/site-kit 7.0.1 → 7.1.0

package/src/motion/README.md

@@ -0,0 +1,372 @@
+# Motion — `@sonordev/site-kit/motion`
+
+The Upforge motion standard: **highly interactive, lean, and designed from
+day one for SEO/AEO.** Three tiers, three subpaths, so a site only installs
+and ships what it imports.
+
+| Tier | Import | Cost (gzipped) | When |
+|------|--------|----------------|------|
+| 0 | `@sonordev/site-kit/motion` | ~2KB, zero deps | Every site |
+| 1 | `@sonordev/site-kit/motion/gsap` | +46KB (gsap + ScrollTrigger), at idle | Sequenced timelines, SplitText, Flip |
+| 2 | `@sonordev/site-kit/motion/three` | +180KB (three), on approach | Flagship builds with a WebGL scene |
+
+The reference build is [upforgelabs.com](https://upforgelabs.com): a full
+three.js flythrough that scores 95 on mobile Lighthouse. Every primitive
+here sits on the same scroll engine that site runs.
+
+## The guarantees
+
+These hold for every primitive in tier 0, and are asserted by
+`motion.test.tsx`:
+
+1. **The server HTML is fully visible.** No opacity, transform, or
+   visibility in the markup. Crawlers, no-JS visitors, and the LCP
+   measurement all read the finished page.
+2. **Above-the-fold content is never animated in.** `<Reveal>` checks on
+   mount whether its element is already on screen and, if so, does nothing.
+   An `opacity: 0` hero cannot be the LCP element; Chrome records LCP at the
+   end of the entrance tween, or never.
+3. **A headless renderer gets the content back.** Google's Web Rendering
+   Service executes JavaScript but never scrolls. If nothing scrolls within
+   2.5s of a reveal arming, the content is restored, so the indexed snapshot
+   is never transparent.
+4. **Native scroll only.** The wheel is never hijacked and the body is never
+   transformed. The liquid feel comes from each scene lerping toward the real
+   scroll position.
+5. **`prefers-reduced-motion` turns it all off.** Reveals and parallax stay
+   static; pinned scenes hold one representative frame.
+6. **Nothing is mounted by `SiteKitLayout`.** Motion is opt-in per element,
+   never a wrapper around the page.
+
+## Tier 0
+
+### `<Reveal>`
+
+Scroll-entrance reveal on a CSS transition. Replaces the per-site
+`Reveal` / `ScrollReveal` / `RevealOnScroll` components.
+
+```tsx
+import { Reveal } from '@sonordev/site-kit/motion'
+
+<Reveal>
+  <h2>Server-rendered, visible in the HTML, revealed as it scrolls in.</h2>
+</Reveal>
+
+<Reveal as="ul" stagger from="left" distance={32}>
+  <li>…</li><li>…</li><li>…</li>
+</Reveal>
+```
+
+| Prop | Default | Meaning |
+|------|---------|---------|
+| `as` | `"div"` | Element to render |
+| `from` | `"up"` | `"up" \| "down" \| "left" \| "right" \| "none"` — where it travels in from |
+| `distance` | `24` | Travel in px |
+| `delay` | `0` | Seconds before the transition starts |
+| `duration` | `0.7` | Seconds |
+| `stagger` | `false` | `true` (0.08s) or seconds between direct children |
+| `once` | `true` | `false` re-hides when it scrolls back out |
+| `threshold` | `0.15` | Reveal when the top crosses this far up from the bottom edge (0.15 = 85% down the screen) |
+| `scale` | off | Starting scale, e.g. `0.96` |
+| `opacity` | `0` | Starting opacity |
+| `easing` | ease-out quint | Any CSS easing |
+
+The element carries `data-sk-reveal` so you can style or debug it.
+
+### `<Parallax>` / `useParallax(ref, options)`
+
+Scroll-linked transform and opacity, compositor-only, driven by the
+element's progress through the viewport (0 as its top enters at the bottom,
+1 as its bottom leaves at the top). Replaces `ParallaxImage` / `ParallaxY`.
+
+```tsx
+import { Parallax } from '@sonordev/site-kit/motion'
+
+// A parallax photo: the frame clips, the scale hides the travel.
+<div className="overflow-hidden rounded-2xl">
+  <Parallax y={[-40, 40]} scale={[1.15, 1.15]}>
+    <Image src={photo} alt="…" fill sizes="…" />
+  </Parallax>
+</div>
+```
+
+Options: `y` (default `[40, -40]`), `x`, `scale`, `opacity`, `rotate` — each
+a `[at p=0, at p=1]` pair — `ease(p)` to remap progress, and `anchor`.
+
+**Above the fold, use `anchor="load"`.** Progress runs over the element's
+whole trip through the viewport, and a hero layer is already partway along
+that trip when the page loads (p ≈ 0.5), so an unanchored layer jumps to
+that frame on hydration. A hero photo is usually the LCP element, so it
+must not move. Anchored, progress counts from where the page was when the
+layer armed: the first frame renders each range's first value, and from
+there it moves at the usual rate (one range per full trip). Give it ranges
+that start at rest:
+
+```tsx
+// Server component: the photo layer behind the hero copy.
+<section className="relative overflow-hidden">
+  <Parallax anchor="load" y={[0, 120]} className="absolute inset-0 -bottom-16">
+    <img src="/hero.avif" alt="…" fetchPriority="high" className="h-full w-full object-cover" />
+  </Parallax>
+  <h1 className="relative">…</h1>
+</section>
+```
+
+A layer that arms below the fold anchors at 0, so `anchor` changes nothing
+for it.
+
+### `<ScrollScene>` / `useScrollScene(ref, onProgress?, options)`
+
+A pinned scene: a tall wrapper with a sticky, viewport-sized stage inside
+it. As the visitor scrolls the wrapper's height the stage stays put and
+progress runs 0→1. Progress is written to `--sk-p` on the wrapper every
+frame, so choreography can be pure CSS.
+
+```tsx
+import { ScrollScene } from '@sonordev/site-kit/motion'
+
+<ScrollScene length="300vh" className="scene">
+  <h2 className="scene-title">This copy is in the server HTML.</h2>
+  <img className="scene-art" src="…" alt="" />
+</ScrollScene>
+```
+
+```css
+.scene-title { opacity: calc(1 - var(--sk-p) * 2); }
+.scene-art   { transform: translateX(calc(var(--sk-p) * -40vw)) scale(calc(1 + var(--sk-p) * 0.4)); }
+```
+
+`onProgress(p, { target, visible })` runs the same frame for canvas
+frame-scrub, three.js, or anything measured. `continuous` keeps rendering
+while visible (shader time), `reducedP` sets the frame held under reduced
+motion (default 0.55), `lerp` tunes the smoothing (default 0.16, 1 = locked
+to the scrollbar).
+
+The children are server-rendered. A `"use client"` component still renders
+children that arrive as props on the server, so the copy inside a scene is
+in the HTML. What you must **not** do is load a component containing a
+scene through `dynamic(…, { ssr: false })`: that de-opts the whole subtree
+to client rendering and the copy disappears from the HTML.
+
+### The engine
+
+```ts
+import { registerScene, refreshScenes, prefersReducedMotion, sceneProgress, onNoScroll } from '@sonordev/site-kit/motion'
+
+const stop = registerScene(pinElement, (p, { target, visible }) => draw(p), { mode: 'pin' })
+```
+
+One shared `requestAnimationFrame` drives every registered scene and sleeps
+when everything has settled; scenes beyond a 35% viewport margin are not
+rendered. Call `refreshScenes()` after a layout change the engine cannot see
+(an accordion opening above a scene). `sceneProgress` is the pure progress
+math, exported for tests and reuse.
+
+`anchor: 'load'` works here too, for a custom scene above the fold: the
+callback's first `p` is 0 and it moves one unit per full trip from there
+(negative if the page scrolls back above where it armed). One scene can
+drive many layers at their own rates:
+
+```ts
+registerScene(
+  collage,
+  (p) => tiles.forEach((t) => (t.style.transform = `translate3d(0, ${p * Number(t.dataset.depth)}px, 0)`)),
+  { mode: 'view', lerp: 1, anchor: 'load' },
+)
+```
+
+## Tier 1 — GSAP
+
+```bash
+npm i gsap
+```
+
+```tsx
+import { useGsap } from '@sonordev/site-kit/motion/gsap'
+
+const ref = useRef<HTMLDivElement>(null)
+useGsap(ref, ({ gsap, el }) => {
+  gsap.from(el.querySelectorAll('[data-line]'), {
+    yPercent: 100, opacity: 0, stagger: 0.06, duration: 0.8, ease: 'power3.out',
+    scrollTrigger: { trigger: el, start: 'top 80%' },
+  })
+})
+```
+
+`useGsap` loads gsap + ScrollTrigger once per page at idle (`whenIdle`: after
+the `load` event, when the main thread goes quiet), so it's off the LCP path
+and out of hydration's way but already in hand when a visitor scrolls to the
+section. It runs the setup when the element comes within 200px of the
+viewport (`near`), inside `gsap.context(el)` so selectors are scoped and
+everything is reverted on unmount, and skips under reduced motion
+(`reducedMotion: 'run'` to opt out). A reduced-motion visitor never downloads
+gsap at all.
+
+**Plugins beyond ScrollTrigger go in `options.plugins`**, never an
+`import()` inside setup:
+
+```tsx
+useGsap(
+  ref,
+  ({ gsap, el, plugins: { SplitText } }) => {
+    SplitText.create(el, {
+      type: 'lines',
+      mask: 'lines',
+      autoSplit: true,
+      onSplit: (self) =>
+        gsap.from(self.lines, { yPercent: 115, stagger: 0.09, scrollTrigger: { trigger: el, once: true } }),
+    })
+  },
+  [],
+  { plugins: { SplitText: () => import('gsap/SplitText') } },
+)
+```
+
+They load with gsap (once per page, however many components ask), get
+registered, and reach setup by name, so setup stays synchronous. That's the
+point: gsap.context only records what runs synchronously inside it, so a
+plugin imported from within setup did its work after the context closed.
+Its tweens and splits were unscoped and never reverted on unmount.
+
+Anything setup still has to start later (after an await, in a timer) goes
+through the context it's handed: `context.add(() => gsap.to(...))`.
+
+Rules: below the fold only; hide things inside the setup with `gsap.set`,
+never with a stylesheet; no ScrollSmoother (it transforms the page body,
+fights native scroll, and costs INP).
+
+### `scrollIn(gsap, el, build, { start })`
+
+A below-the-fold entrance with the rules every kit reveal keeps, for use
+inside a `useGsap` setup:
+
+```tsx
+useGsap(ref, ({ gsap, el }) =>
+  scrollIn(gsap, el, (tl) => tl.from(el.querySelectorAll('li'), { y: 24, opacity: 0, stagger: 0.06 })),
+)
+```
+
+- An element already on screen when setup runs is left as the server
+  rendered it, and `build` never runs.
+- Otherwise `build` fills a paused timeline. Its from-states apply at once,
+  while the element is still offscreen, and it plays when the element's top
+  crosses `start` (default `"top 90%"`).
+- A visitor who never scrolls gets the finished state after 2.5s, callbacks
+  included, through the same failsafe `<Reveal>` uses.
+
+It returns the failsafe's cancel; return it from setup as the cleanup.
+
+### `<CountUp>`
+
+A stat that rolls up to its value as it scrolls into view. Pass the
+formatted value as its text; it rolls the first number and keeps everything
+around it (currency, `%`, units, decimals, thousands separators only if the
+text had them):
+
+```tsx
+import { CountUp } from '@sonordev/site-kit/motion/gsap'
+
+<CountUp as="p" className="stat">$412,500</CountUp>
+<CountUp>{`${ownerPct}%`}</CountUp>
+```
+
+The server HTML is the real text. A stat already on screen keeps its
+number, the real text comes back at the end of the roll and from the
+no-scroll failsafe, and reduced motion never touches it. Props: `as`
+(default `"span"`), `className`, `id`, `duration` (1.3), `ease`
+(`"power2.out"`), `start` (`"top 90%"`). `parseCountUp(text)` is the
+formatting split, exported for tests.
+
+Also exported: `loadGsap()` (the shared loader, immediate), `whenIdle()`
+(the idle gate useGsap loads behind), and
+`useExpandCollapse(isOpen)` (height/opacity expand without unmounting, so
+the content stays indexable).
+
+## Tier 2 — three.js
+
+```bash
+npm i three && npm i -D @types/three
+```
+
+The scene component is loaded lazily and mounted as a **childless sibling**
+of the server-rendered stage, never wrapping it. Copy lives in the DOM,
+never in the canvas.
+
+```tsx
+// page.tsx (server component)
+import dynamic from 'next/dynamic'
+import { ScrollScene } from '@sonordev/site-kit/motion'
+const Scene = dynamic(() => import('./Scene'), { ssr: false })
+
+<ScrollScene id="hero-scene" length="400vh">
+  <div className="relative z-10">
+    <h1>Real copy, in the HTML, above the canvas.</h1>
+  </div>
+</ScrollScene>
+<Scene pinId="hero-scene" />
+```
+
+```tsx
+// Scene.tsx
+'use client'
+import { useRef, useEffect } from 'react'
+import { useThreeStage } from '@sonordev/site-kit/motion/three'
+import { Mesh, BoxGeometry, MeshStandardMaterial, DirectionalLight } from 'three'
+
+export default function Scene({ pinId }: { pinId: string }) {
+  const pin = useRef<HTMLElement | null>(null)
+  useEffect(() => { pin.current = document.getElementById(pinId) }, [pinId])
+  useThreeStage(pin, {
+    onReady: ({ scene, camera }) => {
+      camera.position.z = 5
+      scene.add(new Mesh(new BoxGeometry(), new MeshStandardMaterial()), new DirectionalLight())
+    },
+    render: (p, { renderer, scene, camera }) => {
+      camera.position.z = 5 - p * 4
+      renderer.render(scene, camera)
+    },
+  })
+  return null
+}
+```
+
+`useThreeStage` creates the canvas behind the stage's content, sizes it with
+a `ResizeObserver`, caps DPR at 1.75 (`maxDpr`), pauses on context loss, and
+disposes everything on unmount. `canRunWebGL()` is false under reduced
+motion, Save-Data, or without WebGL, in which case nothing mounts and the
+visitor keeps the server-rendered still. `loadTexture(url)` resolves `null`
+instead of throwing, so one bad asset can't take a scene down.
+`disposeObject(root)` frees a subtree.
+
+Budgets: three itself is ~180KB gzipped, so this tier is for flagship builds;
+keep models and textures to ≤5MB per scene and fetch them on approach.
+
+## Migrating a site's own Reveal
+
+Per-site components map onto `<Reveal>` almost one to one:
+
+| Site prop | `<Reveal>` |
+|-----------|-----------|
+| `from="up"`, `direction="up"` | `from="up"` |
+| `y={30}` (upforge.io) | `distance={30}` |
+| `stagger` (boolean) | `stagger` |
+| `delay`, `duration` | same, in seconds |
+| `threshold`, `rootMargin` | `threshold` |
+| `once` | `once` |
+
+Remove `@gsap/react` and any `useGSAP` at module scope while you're there:
+that pattern puts gsap in the initial bundle of every page.
+
+A site's own count-up becomes `<CountUp>` with the formatted value as its
+text (`<CountUp value={n} prefix="$" />` → `<CountUp>{usd(n)}</CountUp>`).
+A hero or above-the-fold parallax that captured its first progress by hand
+to stop the hydration jump becomes `<Parallax anchor="load">`, or
+`registerScene(..., { anchor: 'load' })` for a custom scene.
+
+## Before you ship
+
+- `curl` the built page and confirm the copy inside every scene and reveal
+  is in the raw HTML.
+- Mobile Lighthouse ≥ 90: `npx lighthouse <url> --form-factor=mobile --only-categories=performance`.
+- Toggle reduced motion and confirm the page reads as a plain column.
+- Disable JavaScript and confirm nothing is hidden.

package/src/og/README.md

@@ -0,0 +1,304 @@
+# OG cards — `@sonordev/site-kit/og`
+
+Social cards, rendered at build time by headless Chrome. Real CSS, real
+webfonts, no Satori subset, nothing at runtime.
+
+```bash
+npx sonor-setup og
+```
+
+That renders the site card to `public/og.png` **and one card per route**.
+
+## The one rule that will bite you
+
+**Config metadata beats the file convention.** A route whose `generateMetadata`
+returns `openGraph.images` overrides its own `opengraph-image` file.
+
+So a site using per-page cards must declare **no images anywhere**:
+
+```ts
+// ✅ root layout — no images array
+openGraph: { type: 'website', locale: 'en_US', siteName: 'Acme' },
+twitter:   { card: 'summary_large_image' },
+```
+
+```ts
+// ❌ this silently disables EVERY per-page card
+openGraph: { images: ['/og.png'] },
+```
+
+That includes **`seo_pages.managed_og_image`** in Sonor. site-kit serves it into
+`openGraph.images` for every managed page, so setting it suppresses that page's
+card from the dashboard, with nothing in the repo to explain why. `sonor-setup
+og` reads it for every route while it titles the cards and names the pages that
+set one; `sonor-setup doctor --online` does the same. Offline, the doctor says
+nothing about it (it used to warn on every per-page site, set or not).
+
+The one image a page may declare is its own **per-URL card** or a **code card on
+a `trailingSlash` site** (both below). Those replace the route's card on purpose.
+
+This was verified against real builds, both ways: with images declared, all 32
+routes on a real site served the same card and every generated page card was
+inert; removing the declaration made each route serve its own.
+
+A second surprise from the same investigation: **file metadata does not cascade
+to child segments.** A card at `services/` is not inherited by
+`services/[city]`. Dynamic segments get their own card (one file covers every
+param), which the generator does automatically.
+
+`sonor-setup og` and `sonor-setup doctor` both check this through one shared
+rule (`og/wiring.ts`). Do not re-implement it — there were two copies once and
+both told sites to do the wrong thing. The rule reads the site's code through
+`shared/source-graph.ts`, which follows imports into `lib/` helpers and monorepo
+workspace packages, so `twitter.card` set in a metadata helper counts. It used
+to read the root layout alone.
+
+## Writing the card
+
+`og.config.ts` at the site root owns the theme. Sonor's brand data is only a
+zero-config seed for sites that have no config yet.
+
+```ts
+import { defineOgCard } from '@sonordev/site-kit/og'
+
+export default defineOgCard({
+  theme: { bg: '#0A0A0A', text: '#f5f5f7', accent: '#C41E3A', surface: '#141418' },
+  fonts: [{ family: 'Playfair Display', weights: [800] }],
+  logo: '/logo-white.svg',
+  layout: 'split',
+  photo: { src: '/team.jpg' },
+  content: {
+    kicker: 'Custom Closets · Cincinnati',
+    title: 'Built by\nbrothers',
+    subtitle: 'Designed, built, and installed by the same two people.',
+    bar: ['Free design', 'example.com'],
+  },
+})
+```
+
+Layouts: `plate-left` (logo plate + copy), `centered`, `banner` (copy only),
+`split` (copy left, photo right). In `split` a configured `logo` renders as a
+small mark above the kicker.
+
+### Copy is fitted, not guessed
+
+The title opens at 104px and the renderer steps it down until it fits **both**
+axes, stopping at a 56px legibility floor — below that a headline stops reading
+at the ~300px thumbnail width platforms actually show.
+
+If copy still does not fit at the floor, the command **fails** and names the
+element and the overflow in pixels. That is deliberate: the failure it exists to
+catch was a card that shipped with the kicker off-canvas and the subtitle buried
+under the bottom bar, while the CLI printed a tick.
+
+Rules of thumb: about 10 uppercase characters per title line, and about 29 for
+the kicker. `\n` in a title is a hard break, so choose the wrap yourself rather
+than leaving it to the box.
+
+## Per-page cards
+
+Every static route gets a card, plus one per dynamic segment. Copy comes from
+Sonor's managed title and description when `SONOR_API_KEY` is set, so a card and
+its search result say the same thing; otherwise the route path is titled.
+Everything else is inherited from the site card, so the set reads as one family.
+
+Hand-write the few that deserve it:
+
+```ts
+cards: {
+  '/free-3d-design': {
+    content: { kicker: 'Free 3D design', title: 'See it\nfirst' },
+    photo: { src: '/lp/hero.jpg' },
+  },
+},
+```
+
+Keyed by route path or slug (`services-garage`), layered over the derived card,
+so an entry only states what differs.
+
+Managed titles carry the brand for the SERP (`About Us | Acme`); the card drops
+it. It also drops the two broken suffixes managed titles turn up with: a dangling
+separator with no brand after it (`About Us |`) and a domain after a comma
+(`Privacy Policy, abbeyglenapts.com`). A hyphen inside a word is never a
+separator (`Walk-In Closets` stays whole).
+
+### Dynamic routes are keyed by pattern, one `*` per level
+
+A dynamic segment has no single URL, so its card is keyed by the route pattern:
+`services/[slug]` is `/services/*`, and `services/[slug]/[metro]` is
+`/services/*/*`. Slug form is `services-any` and `services-any-any`.
+
+Depth matters because a card file lives beside each `page.tsx`, so those two
+directories are two different cards. They are also the one place the generator
+runs out of facts: neither pattern has managed metadata of its own, so **both
+derive their copy from the nearest static ancestor** (`/services`) and come out
+identical. If the deeper route deserves its own words, write them:
+
+```ts
+cards: {
+  '/services/*':   { content: { title: 'What we do' } },
+  '/services/*/*': { content: { kicker: 'Service areas', title: 'Near you' } },
+},
+```
+
+This was a real bug: both directories keyed to `/services/*`, so 120
+service-by-metro pages shipped the service pages' card and the `/services/*/*`
+override matched nothing — silently. A `cards` key that matches no rendered
+route is now reported by `sonor-setup og` (`og.cards`, a warning).
+
+> **Writing a nested pattern in a comment.** `/services/*/*` contains `*/`,
+> which **closes a `/* */` block comment early**. In TypeScript put it in a
+> string, a `//` line comment, or spell the depth out in prose — this bit the
+> fix for the bug above, inside the comment explaining the bug.
+
+### Static routes under a dynamic segment get a card too
+
+`properties/[slug]/about` is a static route under a dynamic one. It gets its
+own card, keyed `/properties/*/about` and titled from its own name ("About",
+kicker "properties"). The generator used to stop at the first dynamic segment,
+so these pages shipped with no og:image at all, 30 of them on two
+property sites.
+
+### Per-URL cards: one per floor plan, one per community
+
+A static file in a dynamic segment covers every param, so `/floor-plans/*` is
+one card for every plan. When each page deserves its own, key `cards` by the
+URL itself. `sonor-setup og` loads og.config.ts with plain Node, so it can
+import the site's data only through a relative path with the `.ts` extension
+and no `@/` aliases; a short list inline is often simpler:
+
+```ts
+// og.config.ts
+import { defineOgCard } from '@sonordev/site-kit/og'
+
+const floorPlans = [
+  { slug: '1-bedroom', name: '1 Bedroom', image: '/living-room.webp' },
+  { slug: '2-bedroom', name: '2 Bedroom', image: '/kitchen.webp' },
+]
+
+export default defineOgCard({
+  // ...theme, content
+  cards: {
+    '/floor-plans/*': { content: { title: 'Floor\nplans' } }, // the fallback
+    ...Object.fromEntries(
+      floorPlans.map(plan => [
+        `/floor-plans/${plan.slug}`,
+        { content: { kicker: 'Floor plan', title: plan.name }, photo: { src: plan.image } },
+      ]),
+    ),
+  },
+})
+```
+
+`sonor-setup og` renders each to `public/_og/<url>.jpg` (the kit owns that
+directory and clears it every run), and the page declares its own:
+
+```ts
+// app/floor-plans/[slug]/page.tsx
+import { paramCardImage } from '@sonordev/site-kit/og'
+import ogConfig from '../../../og.config'
+
+export async function generateMetadata({ params }) {
+  const { slug } = await params
+  const card = paramCardImage(`/floor-plans/${slug}`, { config: ogConfig })
+  return {
+    openGraph: { ...(card && { images: [card] }) },
+    twitter: { card: 'summary_large_image', ...(card && { images: [card.url] }) },
+  }
+}
+```
+
+With `config`, a page with no entry gets undefined and keeps the segment card.
+The URL ends in `.jpg`, so a `trailingSlash: true` site never redirects it.
+Per-URL cards need `sharp` (they have to be `.jpg`); without it the command
+fails those cards and says so. Their copy comes from Sonor's managed title for
+that URL, like any route card. A per-URL key matches a pattern one segment per
+`*`, so `/properties/tall-pines/about` falls under `/properties/*/about`.
+
+Cards are re-encoded to JPEG when `sharp` resolves — on a real 18-card site that
+was 5.6 MB → 1.4 MB. Without sharp they stay PNG, which is correct, just heavier.
+
+`--no-pages` renders only the site card.
+
+## When cards go stale
+
+Cards are build-time artifacts of the copy at generation time. If managed titles
+change in Sonor, re-run `sonor-setup og` — nothing re-renders them automatically.
+Worth adding to the same routine as a content pass.
+
+## Per-entity cards (tier 2)
+
+For cards that must vary per *record* and can't wait for a rebuild — one per
+article published from Sonor, per event — `@sonordev/site-kit/og/route`
+renders on demand with next/og. Use the metadata file convention:
+
+```tsx
+// app/article/[slug]/opengraph-image.tsx
+import { createOgImage } from '@sonordev/site-kit/og/route'
+import { getArticle } from '@sonordev/site-kit/articles/server'
+import ogConfig from '../../../og.config'
+
+export { size, contentType } from '@sonordev/site-kit/og/route'
+export const alt = 'From the Acme article'
+
+export default createOgImage<{ slug: string }>(async ({ slug }) => {
+  const post = await getArticle(slug)
+  if (!post) return null // 404
+  return {
+    theme: ogConfig.theme,
+    kicker: 'From the publication',
+    title: post.title,
+    photoUrl: post.featured_image, // must be absolute
+    bar: 'acme.com',
+  }
+})
+```
+
+Next calls it with `{ params }` and wires og:image for the post by itself, and
+`sonor-setup og` sees the file and leaves the folder alone. The post page passes
+`images: false` to `generateArticleMetadata`, or the featured image beats the
+card (the doctor flags a page that doesn't).
+
+`createOgImageRoute` is the same card as a route handler, `GET(req, { params })`,
+for a card at a URL of your own. Next doesn't wire a route handler into
+metadata. It used to be the only shape, so sites wrote an adapter to use it
+from `opengraph-image.tsx`; delete those for `createOgImage`.
+
+The runtime card fits its title the way the build-time card does, from an
+estimate since Satori can't measure: 104px down to the 56px floor. When the
+title can't fit beside the photo even at the floor, the photo goes and the
+title gets the full width. No more hand-picked "drop the photo past 40
+characters". The bottom bar's text defaults to whichever of `surface`, `bg` and
+`text` reads on the accent (WCAG 3:1 for large text), in that order; set
+`theme.barText` to choose. It used to be `text`, which put navy on crimson. The
+build-time card uses the same rule, and keeps `surface` wherever it already
+read.
+
+Satori's constraints still apply: a flexbox-only CSS subset, no external
+stylesheets, images as absolute URLs or data URIs (a relative `photoUrl` is
+dropped), and fonts supplied as ArrayBuffers. Reach for it only when the cards
+can't be rendered at build time; per-URL cards in `og.config.ts` cover
+everything `generateStaticParams` can list.
+
+### Code cards on a `trailingSlash: true` site
+
+Next serves a code card at `<page>/opengraph-image`, with no extension, and
+`trailingSlash: true` 308-redirects that URL, so every share preview starts
+with a redirect. Declare the slashed URL from the page instead:
+
+```ts
+import { codeCardImage } from '@sonordev/site-kit/og'
+
+openGraph: { images: [codeCardImage(`/article/${slug}`)] }, // /article/x/opengraph-image/
+```
+
+`trailingSlash` defaults to the site's next.config. `sonor-setup og` and the
+doctor flag a code card on a `trailingSlash` site whose page doesn't. A code card
+at `opengraph-image/route.tsx` (a route handler folder) is recognised too, so
+the generator no longer writes an `opengraph-image.jpg` beside it, which Next
+refused to build.
+
+## Reminder
+
+Facebook caches aggressively. After deploying a new card, re-scrape at
+<https://developers.facebook.com/tools/debug/>.