takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/motion-graphics/categories/maps/module.md

@@ -1,61 +1,61 @@
-# maps — category module
-
-Geographic motion: highlight regions, connect places, zoom to a location. **First decision: does the shot need a real basemap** (satellite/street/terrain imagery, globe, or zoom to a real address)? That picks the lane.
-
-## Plan (Director)
-
-Set `content.lane` first:
-
-- **vector** (default) — stylized region shapes, no real imagery. Native + live in HF, cheap. `asset_needs: []`.
-- **basemap** — needs real satellite/dark tiles, globe, or zoom-to-real-place. `asset_needs: [{ type: "map-bake", … }]`. **Bake the imagery in Source**: HF forbids render-time network and requires determinism, so live tiles (which re-fetch and can change per render) can't be the imagery layer — baking freezes it (and is smooth as a bonus). See Basemap lane + Determinism.
-
-`content`: `{ lane, shot: highlight|flow|choropleth|labels|flag|pin-rollout|zoom-to, regions[], points[], basemap: satellite|dark, palette, headline, overlays: [label|pin|callout-card] }`.
-
-`overlays` are independent of `shot` and work in both lanes. **`callout-card`** = a pinned card (flag chip + stat + progress bar) — this is the "documentary popup" (top #13); compose it on any zoom-to/highlight shot rather than treating it as its own shot.
-
-## Vocabulary / leans on
-
-**Vector lane** (D3 + TopoJSON — reuse the existing map family, don't duplicate):
-
-- Reuse: `us-map` (+bubble/hex/flow), `world-map`, `spain-map`.
-- **Hand-author** these (NOT in the catalog — build per the signatures below, don't expect an `add`): `geo-highlight` (N countries colored + labels + border pulse), `geo-flow` (world arcs / hub network), `flag-borders` (flag clipped to a country), `pin-rollout` (cities pulse in sequence + counter).
-- Signature: country fill-in stagger · pin drop + pulse ring · arc `stroke-dashoffset` draw-on + flyer · choropleth color reveal · **viewBox** zoom.
-
-**Basemap lane** (MapLibre, baked in Source — validated pipeline, `bake-basemap.mjs`, fully env-parametric — runs for any country, not just the prototypes):
-
-- **Bake** `bake-basemap.mjs` (puppeteer + MapLibre; env-driven: `NAME STYLE COUNTRIES CENTER ZSTART ZEND PITCH BEARING FPS DUR`): drive the camera **zoom→hold** (`easeInOutCubic`) and **`await map.once('idle')` before every frame** so each frame has complete tiles (Remotion `delayRender` technique → no tile pop). The helper resolves Chrome itself, pins deps exactly, derives the overseas-territory filter per subject, and **fails loud on idle-timeout** (suspect frames → non-zero exit). _External deps: the pinned CDN libs (maplibre/topojson/world-atlas) + the Esri/CARTO tile endpoints are third-party — re-verify availability + ToS on any version bump._ `preserveDrawingBuffer:true`, `fadeDuration:0`. The helper then **encodes the frames to an all-intra MP4 itself** (`ffmpeg -framerate FPS -i f%04d.png -c:v libx264 -g 1 -pix_fmt yuv420p`) and writes everything to **`$OUT` (default `cwd`)**, not the skill dir → `<NAME>.mp4` + `<NAME>-coords.json`.
-- **Export geo→screen** at the hold view: `map.project()` each requested country → `<NAME>-coords.json` = `{ view, countries: [{ name, color, d (SVG path), bbox, label }] }`. The camera holds static after the zoom, so these paths stay pixel-aligned. `label` is an **approximate** anchor (vertex-average of the mainland ring — for concave countries nudge per Legibility). Consume `coords.countries[i]`; the `smooth-frde2`/`smooth-flag` example dirs predate this helper and use a flat `{fr,de,…}` shape, so adapt their wiring.
-- **Builder**: `<video>` basemap on track 0 + an **SVG overlay** that, during the hold, animates country **borders (`stroke-dashoffset` draw-on)** + **fills (colour-block reveal)** + labels/pins/cards — all geo-aligned via `coords.json`. This reproduces the Hera "satellite + animated coloured borders/callouts" look.
-  - The same projected path also doubles as an SVG **`clipPath`**: clip a **flag (or any texture) into the real border** for _flag-in-borders_ — a richer fill than flat colour, over real map context (validated: France tricolor over a dark basemap, `smooth-flag`). Export the feature's screen **bbox** alongside its path so the flag stripes/texture can be sized to the country.
-- **Stretch / data gaps** (extend `bake-basemap.mjs` as needed — the eval agents did): a **globe intro** ("start from the globe") = MapLibre `projection:{type:'globe'}` for the opening phase, easing to mercator at the target (the helper defaults to mercator). **Sub-national** regions (states/provinces) aren't in world-atlas (country-only) → use a Natural Earth **admin-1** TopoJSON, or project centroids as pins (`pin-rollout`).
-
-## Build (reuse-first)
-
-Vector: `npx hyperframes add <block>` → edit regions/data/palette in place. Basemap: baked `map.mp4` as track-0 `<video>`, bind overlays to anchors.
-
-**Restraint (no cheese — this is the #1 way auto-built maps go wrong):** every animated element must serve the message — region, connector, label, pin, camera. **NO decorative ambient glows, background light blobs, floating particles, lens flares, or gratuitous bloom.** Motion = a continuous camera move (viewBox push/zoom) + purposeful, overlapping element reveals — not a light show. Palette: color must **carry meaning** — a data scale (choropleth), categorical fills that distinguish regions (political map), or 1–2 accents for the subjects (highlighted countries / route) over neutral everything-else. Don't add color as **decoration** (a country amber just for contrast, a glow for "energy"). The frame should read like a clean broadcast map, not a screensaver.
-
-**Legibility (hard rule):** offset labels from the highlighted shape and from each other; clamp to the safe area; a callout pill must not sit on another label or a border (the eval surfaced a DE/PL "Oder–Neisse" pill overlapping the POLAND label). A key element stays readable ≥~0.3s.
-
-**Attribution (hard rule):** real basemap imagery carries usage terms — bake a credit element into the composition whenever a basemap is on screen (Esri satellite → "Esri, Maxar, Earthstar Geographics"; CARTO → "© CARTO, © OpenStreetMap"). A small low-corner label (see `smooth-jp`). Non-negotiable for anything published.
-
-**Determinism (hard rules — each one bit us in the prototypes):**
-
-- Drive everything from the seek clock; **never `tl.call`** for stateful updates (counters, text) → proxy tween + `onUpdate` (tl.call freezes the timeline under HF seek).
-- SVG zoom = animate **viewBox** (don't hand-compute group transform origins).
-- Centered overlays (cards/labels using `transform: translate(-50%,…)` to center): animate **opacity only**, or wrap in an outer centered div — GSAP animating `y`/`scale` overwrites the whole transform and kills the centering.
-- Country geometry: filter to the polygon(s) **in a lon/lat box around the subject** — world-atlas bundles overseas territories that blow up the bbox (France + Guiana). Keep near islands (Corsica, Sicily), drop far ones. (`bake-basemap.mjs` anchors on the vertex-richest polygon ± `KEEPMARGIN` — no continent-specific constant.)
-- **Tile world-scale**: MapLibre's internal world width is `512·2^zoom` regardless of the raster `tileSize`. Esri/CARTO raster → `tileSize:256` (correct); a 512px / @2x / retina / vector source needs `tileSize:512` or every zoom level is off by one (this silently over-zoomed a bake once — France overflowed the frame top-to-bottom).
-- **Antimeridian**: a feature crossing ±180° (Russia, Fiji, NZ) smears under per-vertex `map.project()`. `bake-basemap.mjs` **unwraps longitudes around the camera-center ref** before projecting, which handles it; it still warns if a feature spans >180° even after unwrap.
-- **Smoothness = per-frame complete tiles + eased camera.** In the bake, `await map.once('idle')` before each screenshot (= Remotion `delayRender`) and ease the camera with `easeInOutCubic` (= interpolate+Easing). `preserveDrawingBuffer:true`, `fadeDuration:0`, large `maxTileCacheSize`.
-- **Overlay alignment**: project feature borders at a **held** camera and only animate the overlay during the hold — a moving camera + a fixed projected path drift apart.
-- **Pre-hold hidden state**: an overlay revealed _at_ the hold must be `gsap.set` to its hidden state at build time (`scaleX:0`, full `stroke-dashoffset`, `opacity:0`) — a bare `fromTo` does **not** apply its "from" until the tween starts, so the element otherwise shows at its natural (visible, mispositioned) state during the zoom-in.
-- **Why bake at all** (the real reason — not just smoothness): baking freezes the imagery into **deterministic** pixels. Live raster tiles re-fetch every render and can change, and render-time network is forbidden. MapLibre _does_ render live in HF (just janky: tiles pop, deep zooms outrun loading); exposing the engine's per-frame `onBeforeCapture` hook (it exists — `frameCapture.ts:~1250`) would make live **smooth** — but it would **not** remove the need to freeze tiles for **determinism + offline reproducibility**. So `onBeforeCapture` would replace the _smoothness_ role of baking, not the _freeze_ role.
-
-## Out of scope
-
-3D photorealistic landmarks (Cesium territory) · per-country / per-template blocks (parametrize instead) · charts (→ `charts`). (In-engine _live_ MapLibre is possible but janky today — bake instead; revisit if the engine gains a per-frame ready hook.)
-
-## Register
-
-`director.md` classifier line (the lane fork) + `catalog-map.md` `maps/geo` row (add the basemap lane). Phase pipeline untouched.
+# maps — category module
+
+Geographic motion: highlight regions, connect places, zoom to a location. **First decision: does the shot need a real basemap** (satellite/street/terrain imagery, globe, or zoom to a real address)? That picks the lane.
+
+## Plan (Director)
+
+Set `content.lane` first:
+
+- **vector** (default) — stylized region shapes, no real imagery. Native + live in HF, cheap. `asset_needs: []`.
+- **basemap** — needs real satellite/dark tiles, globe, or zoom-to-real-place. `asset_needs: [{ type: "map-bake", … }]`. **Bake the imagery in Source**: HF forbids render-time network and requires determinism, so live tiles (which re-fetch and can change per render) can't be the imagery layer — baking freezes it (and is smooth as a bonus). See Basemap lane + Determinism.
+
+`content`: `{ lane, shot: highlight|flow|choropleth|labels|flag|pin-rollout|zoom-to, regions[], points[], basemap: satellite|dark, palette, headline, overlays: [label|pin|callout-card] }`.
+
+`overlays` are independent of `shot` and work in both lanes. **`callout-card`** = a pinned card (flag chip + stat + progress bar) — this is the "documentary popup" (top #13); compose it on any zoom-to/highlight shot rather than treating it as its own shot.
+
+## Vocabulary / leans on
+
+**Vector lane** (D3 + TopoJSON — reuse the existing map family, don't duplicate):
+
+- Reuse: `us-map` (+bubble/hex/flow), `world-map`, `spain-map`.
+- **Hand-author** these (NOT in the catalog — build per the signatures below, don't expect an `add`): `geo-highlight` (N countries colored + labels + border pulse), `geo-flow` (world arcs / hub network), `flag-borders` (flag clipped to a country), `pin-rollout` (cities pulse in sequence + counter).
+- Signature: country fill-in stagger · pin drop + pulse ring · arc `stroke-dashoffset` draw-on + flyer · choropleth color reveal · **viewBox** zoom.
+
+**Basemap lane** (MapLibre, baked in Source — validated pipeline, `bake-basemap.mjs`, fully env-parametric — runs for any country, not just the prototypes):
+
+- **Bake** `bake-basemap.mjs` (puppeteer + MapLibre; env-driven: `NAME STYLE COUNTRIES CENTER ZSTART ZEND PITCH BEARING FPS DUR`): drive the camera **zoom→hold** (`easeInOutCubic`) and **`await map.once('idle')` before every frame** so each frame has complete tiles (Remotion `delayRender` technique → no tile pop). The helper resolves Chrome itself, pins deps exactly, derives the overseas-territory filter per subject, and **fails loud on idle-timeout** (suspect frames → non-zero exit). _External deps: the pinned CDN libs (maplibre/topojson/world-atlas) + the Esri/CARTO tile endpoints are third-party — re-verify availability + ToS on any version bump._ `preserveDrawingBuffer:true`, `fadeDuration:0`. The helper then **encodes the frames to an all-intra MP4 itself** (`ffmpeg -framerate FPS -i f%04d.png -c:v libx264 -g 1 -pix_fmt yuv420p`) and writes everything to **`$OUT` (default `cwd`)**, not the skill dir → `<NAME>.mp4` + `<NAME>-coords.json`.
+- **Export geo→screen** at the hold view: `map.project()` each requested country → `<NAME>-coords.json` = `{ view, countries: [{ name, color, d (SVG path), bbox, label }] }`. The camera holds static after the zoom, so these paths stay pixel-aligned. `label` is an **approximate** anchor (vertex-average of the mainland ring — for concave countries nudge per Legibility). Consume `coords.countries[i]`; the `smooth-frde2`/`smooth-flag` example dirs predate this helper and use a flat `{fr,de,…}` shape, so adapt their wiring.
+- **Builder**: `<video>` basemap on track 0 + an **SVG overlay** that, during the hold, animates country **borders (`stroke-dashoffset` draw-on)** + **fills (colour-block reveal)** + labels/pins/cards — all geo-aligned via `coords.json`. This reproduces the Hera "satellite + animated coloured borders/callouts" look.
+  - The same projected path also doubles as an SVG **`clipPath`**: clip a **flag (or any texture) into the real border** for _flag-in-borders_ — a richer fill than flat colour, over real map context (validated: France tricolor over a dark basemap, `smooth-flag`). Export the feature's screen **bbox** alongside its path so the flag stripes/texture can be sized to the country.
+- **Stretch / data gaps** (extend `bake-basemap.mjs` as needed — the eval agents did): a **globe intro** ("start from the globe") = MapLibre `projection:{type:'globe'}` for the opening phase, easing to mercator at the target (the helper defaults to mercator). **Sub-national** regions (states/provinces) aren't in world-atlas (country-only) → use a Natural Earth **admin-1** TopoJSON, or project centroids as pins (`pin-rollout`).
+
+## Build (reuse-first)
+
+Vector: `npx hyperframes add <block>` → edit regions/data/palette in place. Basemap: baked `map.mp4` as track-0 `<video>`, bind overlays to anchors.
+
+**Restraint (no cheese — this is the #1 way auto-built maps go wrong):** every animated element must serve the message — region, connector, label, pin, camera. **NO decorative ambient glows, background light blobs, floating particles, lens flares, or gratuitous bloom.** Motion = a continuous camera move (viewBox push/zoom) + purposeful, overlapping element reveals — not a light show. Palette: color must **carry meaning** — a data scale (choropleth), categorical fills that distinguish regions (political map), or 1–2 accents for the subjects (highlighted countries / route) over neutral everything-else. Don't add color as **decoration** (a country amber just for contrast, a glow for "energy"). The frame should read like a clean broadcast map, not a screensaver.
+
+**Legibility (hard rule):** offset labels from the highlighted shape and from each other; clamp to the safe area; a callout pill must not sit on another label or a border (the eval surfaced a DE/PL "Oder–Neisse" pill overlapping the POLAND label). A key element stays readable ≥~0.3s.
+
+**Attribution (hard rule):** real basemap imagery carries usage terms — bake a credit element into the composition whenever a basemap is on screen (Esri satellite → "Esri, Maxar, Earthstar Geographics"; CARTO → "© CARTO, © OpenStreetMap"). A small low-corner label (see `smooth-jp`). Non-negotiable for anything published.
+
+**Determinism (hard rules — each one bit us in the prototypes):**
+
+- Drive everything from the seek clock; **never `tl.call`** for stateful updates (counters, text) → proxy tween + `onUpdate` (tl.call freezes the timeline under HF seek).
+- SVG zoom = animate **viewBox** (don't hand-compute group transform origins).
+- Centered overlays (cards/labels using `transform: translate(-50%,…)` to center): animate **opacity only**, or wrap in an outer centered div — GSAP animating `y`/`scale` overwrites the whole transform and kills the centering.
+- Country geometry: filter to the polygon(s) **in a lon/lat box around the subject** — world-atlas bundles overseas territories that blow up the bbox (France + Guiana). Keep near islands (Corsica, Sicily), drop far ones. (`bake-basemap.mjs` anchors on the vertex-richest polygon ± `KEEPMARGIN` — no continent-specific constant.)
+- **Tile world-scale**: MapLibre's internal world width is `512·2^zoom` regardless of the raster `tileSize`. Esri/CARTO raster → `tileSize:256` (correct); a 512px / @2x / retina / vector source needs `tileSize:512` or every zoom level is off by one (this silently over-zoomed a bake once — France overflowed the frame top-to-bottom).
+- **Antimeridian**: a feature crossing ±180° (Russia, Fiji, NZ) smears under per-vertex `map.project()`. `bake-basemap.mjs` **unwraps longitudes around the camera-center ref** before projecting, which handles it; it still warns if a feature spans >180° even after unwrap.
+- **Smoothness = per-frame complete tiles + eased camera.** In the bake, `await map.once('idle')` before each screenshot (= Remotion `delayRender`) and ease the camera with `easeInOutCubic` (= interpolate+Easing). `preserveDrawingBuffer:true`, `fadeDuration:0`, large `maxTileCacheSize`.
+- **Overlay alignment**: project feature borders at a **held** camera and only animate the overlay during the hold — a moving camera + a fixed projected path drift apart.
+- **Pre-hold hidden state**: an overlay revealed _at_ the hold must be `gsap.set` to its hidden state at build time (`scaleX:0`, full `stroke-dashoffset`, `opacity:0`) — a bare `fromTo` does **not** apply its "from" until the tween starts, so the element otherwise shows at its natural (visible, mispositioned) state during the zoom-in.
+- **Why bake at all** (the real reason — not just smoothness): baking freezes the imagery into **deterministic** pixels. Live raster tiles re-fetch every render and can change, and render-time network is forbidden. MapLibre _does_ render live in HF (just janky: tiles pop, deep zooms outrun loading); exposing the engine's per-frame `onBeforeCapture` hook (it exists — `frameCapture.ts:~1250`) would make live **smooth** — but it would **not** remove the need to freeze tiles for **determinism + offline reproducibility**. So `onBeforeCapture` would replace the _smoothness_ role of baking, not the _freeze_ role.
+
+## Out of scope
+
+3D photorealistic landmarks (Cesium territory) · per-country / per-template blocks (parametrize instead) · charts (→ `charts`). (In-engine _live_ MapLibre is possible but janky today — bake instead; revisit if the engine gains a per-frame ready hook.)
+
+## Register
+
+`director.md` classifier line (the lane fork) + `catalog-map.md` `maps/geo` row (add the basemap lane). Phase pipeline untouched.

package/assets/.agent/skills/motion-graphics/categories/news/module.md

@@ -1,56 +1,56 @@
-# news — category module (search-driven)
-
-Search a real news article → animate it as an **article-highlight** — a faithful HF port of the centered-emphasis technique. Signature motion: the article text is laid out at a **readable size (NOT zoomed)**, slides + fades up, then the **keyword is highlighted in place** — a marker band grows left→right behind it. No blow-up zoom. ~5–7s.
-
-Two layouts share that one highlight core — pick by aspect + whether there's a logo / person to feature:
-
-| Layout                    | Aspect     | Use when                                                        | Has                                                                        |
-| ------------------------- | ---------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| **A · centered-emphasis** | 9:16 / 1:1 | text-only, social vertical                                      | kicker + one centered sentence + keyword highlight                         |
-| **B · full article**      | 16:9       | there's a real **outlet logo** and/or a **person** in the story | logo + date + multi-line headline highlight + dek + outlet + person cutout |
-
-## Source (Step 2)
-
-RWA / web search (or `hyperframes capture`) → a real article. The Director extracts the **keyword** (1–2 words / a number / a name — the hook) and, for Layout B, also a **brand logo**, a **date**, and a **person photo**. `asset_needs: { kind: news|web|image, query }` — request the logo (Wikimedia / simple-icons) and the person photo (Wikimedia) as separate asset queries. Run the person photo through `hyperframes remove-background <in> -o <out>.png` to get a transparent cutout.
-
-## The highlight core (shared by both layouts) — the marker-band technique
-
-The keyword highlight is a marker band grown L→R via `background-size` (NOT a `transform:scaleX` bar):
-
-```css
-.hl {
-  --hlw: 0%;
-  background-image: linear-gradient(var(--hl), var(--hl)); /* --hl: rgba(250,222,99,.6) */
-  background-repeat: no-repeat;
-  background-position: 0 72%;
-  background-size: var(--hlw) 64%;
-  box-decoration-break: clone;
-  -webkit-box-decoration-break: clone;
-}
-```
-
-`box-decoration-break:clone` makes the band **wrap across line breaks** seamlessly — a multi-word keyword spanning 2–3 lines still highlights continuously (the old `scaleX` bar could not). GSAP tweens the CSS var `--hlw` 0%→100%, **swept on AFTER the text settles — never pre-applied**. Optionally scale the duration with keyword length ~0.5–1.5s.
-
-## Layout A — centered-emphasis (9:16, text-only) — Builder
-
-1. **Lay out the key SENTENCE at a readable size — do NOT zoom.** Paper-light stage; an outlet `#kicker` (e.g. "BBC NEWS · TECHNOLOGY", brand accent) at top; the key sentence centered, serif, **~70–76px / 700 / line-height ~1.4**, `max-width ≈ 900`. The whole sentence stays legible; the keyword is emphasized _within_ it.
-2. Wrap the keyword inline: `… raised <span class="hl" id="kw">$750M</span> at …`.
-3. **Timeline** (seek-safe, paused): kicker fades+slides in → **sentence slides+fades up** (`set{autoAlpha:0,y:52}`→`to{autoAlpha:1,y:0,duration:0.8,ease:"power3.out"}`, no zoom) → **keyword highlight grows** (`--hlw 0→100%`, after the sentence settles) → gentle hold (`scale 1.012`).
-
-**Reference:** `samples/news/_ref-centered-emphasis.html` (+ `news/v2-*`).
-
-## Layout B — full article (16:9, logo + person) — Builder
-
-The editorial article-card layout (logo top-left + date + big serif headline with a multi-line keyword highlight + dek + outlet bottom-left + a background-removed **person cutout** bottom-right). 1920×1080, paper-light gradient stage, Georgia serif.
-
-1. **Logo** top-left (`#logo`, ~64px) — inline the outlet/brand SVG, `fill:currentColor`, set `color` to the mark's own hue (or near-black for a monochrome mark). **Date** below it (`#date`, ~30px, muted).
-2. **Headline** (`#headline`, Georgia **96px / 700**, `width≈1080`, `line-height 1.16`) with the keyword wrapped in `<span class="hl" id="kw">` — the highlight band sweeps across **all wrapped lines** of the phrase.
-3. **Dek** (`#dek`, Helvetica ~38px gray) under the headline; **outlet** (`#outlet`, Georgia bold ~50px) bottom-left.
-4. **Person cutout** (`#subject`, the bg-removed PNG, `height≈860`, `right:40; bottom:0`, `drop-shadow`) — **slides up from bottom-right** as the hero beat.
-5. **Timeline** (seek-safe, paused): logo `back.out` @0.15 → date @0.4 → **subject slides up** (`set{autoAlpha:0,x:90,y:60}`→`to{autoAlpha:1,x:0,y:0,duration:0.85,ease:"power3.out"}`) @0.45 → headline @0.7 → dek @1.5 → outlet @1.9 → **keyword highlight** (`--hlw 0→100%`, `duration:0.8`) @2.2. duration ~6.5s.
-
-**Reference:** `samples/news/_ref-article-layout.html` (a real article rendered with a real outlet logo + a background-removed person + a real story).
-
-## Critical
-
-Highlight is **grown in place, swept on AFTER the text — never pre-applied**. The text **stays readable — do NOT zoom the keyword to fill the frame** (team feedback 2026-06-09: zoom loses context and reads wrong; the technique never zooms — it presents the text and highlights the word). For Layout B, the person MUST be a `remove-background` cutout (no rectangular photo box). Deterministic; honor `references/builder-contract.md`.
+# news — category module (search-driven)
+
+Search a real news article → animate it as an **article-highlight** — a faithful HF port of the centered-emphasis technique. Signature motion: the article text is laid out at a **readable size (NOT zoomed)**, slides + fades up, then the **keyword is highlighted in place** — a marker band grows left→right behind it. No blow-up zoom. ~5–7s.
+
+Two layouts share that one highlight core — pick by aspect + whether there's a logo / person to feature:
+
+| Layout                    | Aspect     | Use when                                                        | Has                                                                        |
+| ------------------------- | ---------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| **A · centered-emphasis** | 9:16 / 1:1 | text-only, social vertical                                      | kicker + one centered sentence + keyword highlight                         |
+| **B · full article**      | 16:9       | there's a real **outlet logo** and/or a **person** in the story | logo + date + multi-line headline highlight + dek + outlet + person cutout |
+
+## Source (Step 2)
+
+RWA / web search (or `hyperframes capture`) → a real article. The Director extracts the **keyword** (1–2 words / a number / a name — the hook) and, for Layout B, also a **brand logo**, a **date**, and a **person photo**. `asset_needs: { kind: news|web|image, query }` — request the logo (Wikimedia / simple-icons) and the person photo (Wikimedia) as separate asset queries. Run the person photo through `hyperframes remove-background <in> -o <out>.png` to get a transparent cutout.
+
+## The highlight core (shared by both layouts) — the marker-band technique
+
+The keyword highlight is a marker band grown L→R via `background-size` (NOT a `transform:scaleX` bar):
+
+```css
+.hl {
+  --hlw: 0%;
+  background-image: linear-gradient(var(--hl), var(--hl)); /* --hl: rgba(250,222,99,.6) */
+  background-repeat: no-repeat;
+  background-position: 0 72%;
+  background-size: var(--hlw) 64%;
+  box-decoration-break: clone;
+  -webkit-box-decoration-break: clone;
+}
+```
+
+`box-decoration-break:clone` makes the band **wrap across line breaks** seamlessly — a multi-word keyword spanning 2–3 lines still highlights continuously (the old `scaleX` bar could not). GSAP tweens the CSS var `--hlw` 0%→100%, **swept on AFTER the text settles — never pre-applied**. Optionally scale the duration with keyword length ~0.5–1.5s.
+
+## Layout A — centered-emphasis (9:16, text-only) — Builder
+
+1. **Lay out the key SENTENCE at a readable size — do NOT zoom.** Paper-light stage; an outlet `#kicker` (e.g. "BBC NEWS · TECHNOLOGY", brand accent) at top; the key sentence centered, serif, **~70–76px / 700 / line-height ~1.4**, `max-width ≈ 900`. The whole sentence stays legible; the keyword is emphasized _within_ it.
+2. Wrap the keyword inline: `… raised <span class="hl" id="kw">$750M</span> at …`.
+3. **Timeline** (seek-safe, paused): kicker fades+slides in → **sentence slides+fades up** (`set{autoAlpha:0,y:52}`→`to{autoAlpha:1,y:0,duration:0.8,ease:"power3.out"}`, no zoom) → **keyword highlight grows** (`--hlw 0→100%`, after the sentence settles) → gentle hold (`scale 1.012`).
+
+**Reference:** `samples/news/_ref-centered-emphasis.html` (+ `news/v2-*`).
+
+## Layout B — full article (16:9, logo + person) — Builder
+
+The editorial article-card layout (logo top-left + date + big serif headline with a multi-line keyword highlight + dek + outlet bottom-left + a background-removed **person cutout** bottom-right). 1920×1080, paper-light gradient stage, Georgia serif.
+
+1. **Logo** top-left (`#logo`, ~64px) — inline the outlet/brand SVG, `fill:currentColor`, set `color` to the mark's own hue (or near-black for a monochrome mark). **Date** below it (`#date`, ~30px, muted).
+2. **Headline** (`#headline`, Georgia **96px / 700**, `width≈1080`, `line-height 1.16`) with the keyword wrapped in `<span class="hl" id="kw">` — the highlight band sweeps across **all wrapped lines** of the phrase.
+3. **Dek** (`#dek`, Helvetica ~38px gray) under the headline; **outlet** (`#outlet`, Georgia bold ~50px) bottom-left.
+4. **Person cutout** (`#subject`, the bg-removed PNG, `height≈860`, `right:40; bottom:0`, `drop-shadow`) — **slides up from bottom-right** as the hero beat.
+5. **Timeline** (seek-safe, paused): logo `back.out` @0.15 → date @0.4 → **subject slides up** (`set{autoAlpha:0,x:90,y:60}`→`to{autoAlpha:1,x:0,y:0,duration:0.85,ease:"power3.out"}`) @0.45 → headline @0.7 → dek @1.5 → outlet @1.9 → **keyword highlight** (`--hlw 0→100%`, `duration:0.8`) @2.2. duration ~6.5s.
+
+**Reference:** `samples/news/_ref-article-layout.html` (a real article rendered with a real outlet logo + a background-removed person + a real story).
+
+## Critical
+
+Highlight is **grown in place, swept on AFTER the text — never pre-applied**. The text **stays readable — do NOT zoom the keyword to fill the frame** (team feedback 2026-06-09: zoom loses context and reads wrong; the technique never zooms — it presents the text and highlights the word). For Layout B, the person MUST be a `remove-background` cutout (no rectangular photo box). Deterministic; honor `references/builder-contract.md`.

package/assets/.agent/skills/motion-graphics/categories/stat/module.md

@@ -1,21 +1,21 @@
-# stat — category module
-
-A single **hero number** reveal. Asset-free (the "input" is the number). ~4–6s.
-
-## Plan (Director)
-
-`content`: `{ value, prefix ($), suffix (% / x / K-M-B), label, ring: bool }`. Envelope: bold display font, restrained palette + one accent.
-
-## Vocabulary / leans on
-
-- Block: **`apple-money-count`** (finance-flavoured: $ counter + green flash + money burst + SFX) when it fits; otherwise hand-author.
-- Rules: `hyperframes-animation/rules/{counting-dynamic-scale, stat-bars-and-fills}`.
-- Primitives: `count_up` (odometer) · `scale_pop` · `ring_fill` (arc) · `label_stagger` (after value) · `hold`.
-
-## Build (reuse-first)
-
-Reuse `apple-money-count` + set target / prefix / suffix / label / palette; **or** hand-author per the proven prototype `v0-stat-motion-demo`:
-
-- **count-up is timeline-driven** — tween a proxy `{v:0}→target` with `onUpdate` writing the formatted number (seek-safe; never setInterval/wall-clock).
-- `font-variant-numeric: tabular-nums`; decelerating ease; ~1.2–1.6s then **hold** the final value.
-- ring/arc via `stroke-dashoffset`, finishing in sync with the count-up; label fades in **after** the number lands (value → meaning).
+# stat — category module
+
+A single **hero number** reveal. Asset-free (the "input" is the number). ~4–6s.
+
+## Plan (Director)
+
+`content`: `{ value, prefix ($), suffix (% / x / K-M-B), label, ring: bool }`. Envelope: bold display font, restrained palette + one accent.
+
+## Vocabulary / leans on
+
+- Block: **`apple-money-count`** (finance-flavoured: $ counter + green flash + money burst + SFX) when it fits; otherwise hand-author.
+- Rules: `hyperframes-animation/rules/{counting-dynamic-scale, stat-bars-and-fills}`.
+- Primitives: `count_up` (odometer) · `scale_pop` · `ring_fill` (arc) · `label_stagger` (after value) · `hold`.
+
+## Build (reuse-first)
+
+Reuse `apple-money-count` + set target / prefix / suffix / label / palette; **or** hand-author per the proven prototype `v0-stat-motion-demo`:
+
+- **count-up is timeline-driven** — tween a proxy `{v:0}→target` with `onUpdate` writing the formatted number (seek-safe; never setInterval/wall-clock).
+- `font-variant-numeric: tabular-nums`; decelerating ease; ~1.2–1.6s then **hold** the final value.
+- ring/arc via `stroke-dashoffset`, finishing in sync with the count-up; label fades in **after** the number lands (value → meaning).

package/assets/.agent/skills/motion-graphics/categories/tweet/module.md

@@ -1,16 +1,16 @@
-# tweet — category module (search-driven)
-
-**Search a tweet → animate the tweet card.** Grounded in a real post (RWA). ~4–8s.
-
-## Source (Step 2)
-
-RWA `search_tweets` (specific query, or a given tweet URL/id) → tweet: author, handle, avatar, text, timestamp, metrics (likes/reposts). `asset_needs`: `{ kind: tweet, query|source, treatment: none }`. Freeze the avatar + any embedded media.
-
-## Vocabulary / leans on
-
-- Block: registry **`x-post`** (animated X/Twitter post card overlay with engagement metrics) — reuse it directly.
-- Primitives: card slide/scale-in · text type-on / line reveal · avatar pop · metrics **count-up** · optional emphasis on a keyword.
-
-## Build (reuse-first)
-
-`npx hyperframes add x-post` → fill author / handle / avatar / text / metrics from the resolved tweet; animate the card in, type-on the text (or line-by-line reveal), count-up the metrics. Frozen project-local avatar/media (never a remote URL). `export: alpha-overlay` if it's meant to sit over other footage.
+# tweet — category module (search-driven)
+
+**Search a tweet → animate the tweet card.** Grounded in a real post (RWA). ~4–8s.
+
+## Source (Step 2)
+
+RWA `search_tweets` (specific query, or a given tweet URL/id) → tweet: author, handle, avatar, text, timestamp, metrics (likes/reposts). `asset_needs`: `{ kind: tweet, query|source, treatment: none }`. Freeze the avatar + any embedded media.
+
+## Vocabulary / leans on
+
+- Block: registry **`x-post`** (animated X/Twitter post card overlay with engagement metrics) — reuse it directly.
+- Primitives: card slide/scale-in · text type-on / line reveal · avatar pop · metrics **count-up** · optional emphasis on a keyword.
+
+## Build (reuse-first)
+
+`npx hyperframes add x-post` → fill author / handle / avatar / text / metrics from the resolved tweet; animate the card in, type-on the text (or line-by-line reveal), count-up the metrics. Frozen project-local avatar/media (never a remote URL). `export: alpha-overlay` if it's meant to sit over other footage.

package/assets/.agent/skills/motion-graphics/categories/webpage/module.md

@@ -1,21 +1,21 @@
-# webpage — category module (search-driven)
-
-**Animate a webpage / link** (the "website animation" use case). Search-driven: the user gives or names a URL → fetch/capture it → animate it (scroll-through, UI reveal, cursor demo, region callouts). Distinct from captioning an existing _video file_ (that's `/embedded-captions`) and from a narrated video _of_ a site (that's `/website-to-video`); here the source is a _web page_ and the output is a short, unnarrated highlight shot.
-
-## Source (Step 2)
-
-Fetch the page via `hyperframes capture` (DOM + screenshots) or a provided screenshot → frozen project-local image(s)/DOM. `asset_needs`: `{ kind: web, source: <url>, treatment: none }`.
-
-## Vocabulary / leans on
-
-- Rules: `hyperframes-animation/rules/{3d-page-scroll, demo-page-scroll-spotlight, cursor-click-ripple, coordinate-target-zoom, viewport-change}`.
-- Primitives: scroll pan · spotlight/dim · cursor move + click-ripple · zoom-to-region · callout pin + label.
-
-## Build (reuse-first)
-
-Place the captured page as the base layer; animate a **scroll-through** (translateY over the page height), **spotlight** key regions (dim + highlight), a **cursor** that moves and clicks (ripple), **zoom** to a coordinate, and **callout** pins/labels anchored to page regions. Honor `builder-contract.md`.
-
-**Two rules that match the news article-highlight (see `../news/module.md`):**
-
-- **Highlights are swept/animated ON, never pre-applied** — a spotlight box wipes in (`scaleX 0→1`), a marker sweeps a region, a callout pops _after_ the zoom lands; the page never starts pre-annotated.
-- **Anchor to REAL element positions** — `hyperframes capture` gives the page HTML/DOM, so measure the target element (`getBoundingClientRect` → stage-local) and zoom/highlight it exactly, step-by-step (the "highlight a real element" technique). Don't eyeball coords.
+# webpage — category module (search-driven)
+
+**Animate a webpage / link** (the "website animation" use case). Search-driven: the user gives or names a URL → fetch/capture it → animate it (scroll-through, UI reveal, cursor demo, region callouts). Distinct from captioning an existing _video file_ (that's `/embedded-captions`) and from a narrated video _of_ a site (that's `/website-to-video`); here the source is a _web page_ and the output is a short, unnarrated highlight shot.
+
+## Source (Step 2)
+
+Fetch the page via `hyperframes capture` (DOM + screenshots) or a provided screenshot → frozen project-local image(s)/DOM. `asset_needs`: `{ kind: web, source: <url>, treatment: none }`.
+
+## Vocabulary / leans on
+
+- Rules: `hyperframes-animation/rules/{3d-page-scroll, demo-page-scroll-spotlight, cursor-click-ripple, coordinate-target-zoom, viewport-change}`.
+- Primitives: scroll pan · spotlight/dim · cursor move + click-ripple · zoom-to-region · callout pin + label.
+
+## Build (reuse-first)
+
+Place the captured page as the base layer; animate a **scroll-through** (translateY over the page height), **spotlight** key regions (dim + highlight), a **cursor** that moves and clicks (ripple), **zoom** to a coordinate, and **callout** pins/labels anchored to page regions. Honor `builder-contract.md`.
+
+**Two rules that match the news article-highlight (see `../news/module.md`):**
+
+- **Highlights are swept/animated ON, never pre-applied** — a spotlight box wipes in (`scaleX 0→1`), a marker sweeps a region, a callout pops _after_ the zoom lands; the page never starts pre-annotated.
+- **Anchor to REAL element positions** — `hyperframes capture` gives the page HTML/DOM, so measure the target element (`getBoundingClientRect` → stage-local) and zoom/highlight it exactly, step-by-step (the "highlight a real element" technique). Don't eyeball coords.

package/assets/.agent/skills/motion-graphics/grounding/PROTOCOL.md

@@ -1,64 +1,64 @@
-# locate — find "X" in an image (no detector API assumed)
-
-The single contract every consumer (asset-fusion ring, webpage highlight, future
-explainer/recut overlays) uses:
-
-```
-locate(image, target-description) → { box: [x0,y0,x1,y1], center: [cx,cy] }   # normalized 0..1
-```
-
-## Why this exists
-
-Author models are unreliable at **regressing pixel coordinates** on a cluttered
-full image (measured: weak vision models ~16–24% center error → rings land off-target)
-but reliable at **picking a numbered strip** (~3–4% with the loop below). So:
-never eyeball coordinates; localize by discrete choice. (RSVP, ACL 2025.)
-
-## Routing — pick the cheapest path that's actually available
-
-1. **A strong detector is available** (e.g. `GEMINI_API_KEY` in env) →
-   `node grounding/locate.mjs auto <img> "<target>"` — one call, done.
-   **Never assume the key exists.** No key → path 2.
-2. **No detector (the normal case)** → YOU are the localizer; run the grid loop.
-
-## The grid loop (you read images between steps)
-
-```
-node grounding/locate.mjs overlay <img> --out /tmp/g
-  → READ /tmp/g/gv.png (vertical strips 1-9) and gh.png (horizontal 1-9);
-    decide which strip numbers the target spans (list EVERY strip it touches).
-node grounding/locate.mjs region <img> --vids 4,5 --hids 6,7 --out /tmp/g
-  → READ /tmp/g/gc.png (the region cropped + upscaled, finer 6×6 grid);
-    pick the finer strips. (Pick strips again — do NOT switch to estimating
-    coordinates; discrete choice is the whole point, at BOTH stages.)
-node grounding/locate.mjs final <img> --region <from step 2> --vids 3,4 --hids 3,4
-  → the final {box, center}.
-node grounding/locate.mjs mark <img> --box <final box> --out /tmp/g/check.png
-  → VERIFY: READ check.png. Red box ON the target → done. Off → redo
-    region/final with corrected strips (you now know which direction). Never
-    skip this step; it converts silent misses into one cheap retry.
-```
-
-## Ambiguity — resolve BEFORE localizing
-
-If the target description can match several instances ("a drum" when the scene
-has five), no geometry will save you. First make the reference unique
-("the right-most drum", "the drum on the front boat"), asking the user if
-needed — then run the loop.
-
-## Degradation path (if locate.mjs itself is unavailable)
-
-The idea is 5 lines — reproduce it with any image tool:
-draw a numbered 9×9 grid → pick the strips the target spans → crop that region
-(+pad ~0.4 strip) and upscale → draw a finer 6×6 grid → pick again → map back
-(`global = region_origin + local × region_size`) → draw the box and LOOK at it.
-
-## Notes
-
-- Geometry is frozen in `locate.mjs` (node + ffmpeg, zero npm deps — both
-  already required by hyperframes). Don't re-implement it ad hoc; the measured
-  accuracy holds for THIS implementation.
-- Consumers: `samples/asset-fusion/_ref-circle-highlight.html` takes `CFG.box`
-  directly from `final`/`auto` output.
-- Measured end-to-end (same agent, same template, only the localization step
-  differs): eyeballing 6.5% avg center error → this protocol 2.3%, no case worse.
+# locate — find "X" in an image (no detector API assumed)
+
+The single contract every consumer (asset-fusion ring, webpage highlight, future
+explainer/recut overlays) uses:
+
+```
+locate(image, target-description) → { box: [x0,y0,x1,y1], center: [cx,cy] }   # normalized 0..1
+```
+
+## Why this exists
+
+Author models are unreliable at **regressing pixel coordinates** on a cluttered
+full image (measured: weak vision models ~16–24% center error → rings land off-target)
+but reliable at **picking a numbered strip** (~3–4% with the loop below). So:
+never eyeball coordinates; localize by discrete choice. (RSVP, ACL 2025.)
+
+## Routing — pick the cheapest path that's actually available
+
+1. **A strong detector is available** (e.g. `GEMINI_API_KEY` in env) →
+   `node grounding/locate.mjs auto <img> "<target>"` — one call, done.
+   **Never assume the key exists.** No key → path 2.
+2. **No detector (the normal case)** → YOU are the localizer; run the grid loop.
+
+## The grid loop (you read images between steps)
+
+```
+node grounding/locate.mjs overlay <img> --out /tmp/g
+  → READ /tmp/g/gv.png (vertical strips 1-9) and gh.png (horizontal 1-9);
+    decide which strip numbers the target spans (list EVERY strip it touches).
+node grounding/locate.mjs region <img> --vids 4,5 --hids 6,7 --out /tmp/g
+  → READ /tmp/g/gc.png (the region cropped + upscaled, finer 6×6 grid);
+    pick the finer strips. (Pick strips again — do NOT switch to estimating
+    coordinates; discrete choice is the whole point, at BOTH stages.)
+node grounding/locate.mjs final <img> --region <from step 2> --vids 3,4 --hids 3,4
+  → the final {box, center}.
+node grounding/locate.mjs mark <img> --box <final box> --out /tmp/g/check.png
+  → VERIFY: READ check.png. Red box ON the target → done. Off → redo
+    region/final with corrected strips (you now know which direction). Never
+    skip this step; it converts silent misses into one cheap retry.
+```
+
+## Ambiguity — resolve BEFORE localizing
+
+If the target description can match several instances ("a drum" when the scene
+has five), no geometry will save you. First make the reference unique
+("the right-most drum", "the drum on the front boat"), asking the user if
+needed — then run the loop.
+
+## Degradation path (if locate.mjs itself is unavailable)
+
+The idea is 5 lines — reproduce it with any image tool:
+draw a numbered 9×9 grid → pick the strips the target spans → crop that region
+(+pad ~0.4 strip) and upscale → draw a finer 6×6 grid → pick again → map back
+(`global = region_origin + local × region_size`) → draw the box and LOOK at it.
+
+## Notes
+
+- Geometry is frozen in `locate.mjs` (node + ffmpeg, zero npm deps — both
+  already required by hyperframes). Don't re-implement it ad hoc; the measured
+  accuracy holds for THIS implementation.
+- Consumers: `samples/asset-fusion/_ref-circle-highlight.html` takes `CFG.box`
+  directly from `final`/`auto` output.
+- Measured end-to-end (same agent, same template, only the localization step
+  differs): eyeballing 6.5% avg center error → this protocol 2.3%, no case worse.