@kenkaiiii/ggcoder 5.66.4 → 5.67.1

package/assets/motion/bin/flash-check.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// Photosensitivity screen on decoded pixels against the WCAG 2.3.1 general and red flash
+// thresholds. As in EA's open-source IRIS tool, an area's mean change only counts on frames
+// where at least a quarter of the area changes, so moving content mostly cancels out rather
+// than reading as flashing. IRIS applies this to the whole screen; here it applies to every
+// WCAG 10° field (a third of the frame each way), so a flash filling part of the frame is
+// caught too. A transition is a move of 0.1 relative luminance (or 20 red units) away from the
+// last peak or valley, as WCAG defines it; more than six in any second fails. Renders above
+// 60 fps are sampled at 60. A screen, not a certification.
+import { spawn } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { once } from "node:events";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ffmpegBinary } from "./media-binaries.mjs";
+
+/** Cells per side of the analysis grid; every aspect ratio maps onto it. */
+export const GRID = 48;
+/** Frames per analysed second; slower renders are repeated, so one second is always 60 frames. */
+export const ANALYSIS_FPS = 60;
+/** WCAG approximates the 10° field as 341×256 px of a 1024×768 screen: a third each way. */
+const FIELD = GRID / 3;
+const FIELD_CELLS = FIELD * FIELD;
+/** A field's change counts once a quarter of it changes. */
+const AREA = 0.25 * FIELD_CELLS;
+const WINDOWS_PER_SIDE = GRID - FIELD + 1;
+const WINDOWS = WINDOWS_PER_SIDE * WINDOWS_PER_SIDE;
+/** More than three flashes (six opposing transitions) within any one second fails. */
+const MAX_TRANSITIONS = 6;
+/** Transitions per field within the trailing second never exceed one per analysed frame. */
+const RING = 64;
+const CELLS = GRID * GRID;
+const FRAME_BYTES = CELLS * 3;
+const CHANNELS = {
+  // Relative luminance 0–1: a 0.1 swing, unless even the darker state is 0.8 or brighter.
+  // A cell has changed once it moves by more than encoding noise (about 1/255 linear).
+  general: { threshold: 0.1, darkLimit: 0.8, noise: 0.004 },
+  // WCAG's red measure: (R − G − B) × 320 where R / (R + G + B) ≥ 0.8, else 0.
+  red: { threshold: 20, darkLimit: Infinity, noise: 1 },
+};
+/** sRGB to linear light, applied before averaging so mixed cells keep their real brightness. */
+const LINEAR = "if(lte(val,10.31475),val/12.92,255*pow((val/255+0.055)/1.055,2.4))";
+
+function createChannel({ threshold, darkLimit, noise }) {
+  const side = GRID + 1;
+  const changed = new Float64Array(side * side);
+  const change = new Float64Array(side * side);
+  const level = new Float64Array(side * side);
+  // Per field: the accumulated counted change, its last peak and valley, and the field's
+  // mean at each, for WCAG's "darker image" rule.
+  const signal = new Float64Array(WINDOWS);
+  const peakValue = new Float64Array(WINDOWS);
+  const peakLevel = new Float64Array(WINDOWS);
+  const valleyValue = new Float64Array(WINDOWS);
+  const valleyLevel = new Float64Array(WINDOWS);
+  /** 1 after a rise, -1 after a fall, 0 before the first transition. */
+  const direction = new Int8Array(WINDOWS);
+  const ring = new Int32Array(WINDOWS * RING);
+  const head = new Int32Array(WINDOWS);
+  const tail = new Int32Array(WINDOWS);
+  const failures = [];
+  let peak = 0;
+
+  return {
+    update(frame, previous, current) {
+      // Summed-area tables, so each field's totals cost four lookups.
+      for (let y = 0; y < GRID; y++) {
+        let rowChanged = 0;
+        let rowChange = 0;
+        let rowLevel = 0;
+        for (let x = 0; x < GRID; x++) {
+          const cell = y * GRID + x;
+          const delta = current[cell] - previous[cell];
+          if (Math.abs(delta) > noise) rowChanged++;
+          rowChange += delta;
+          rowLevel += current[cell];
+          const at = (y + 1) * side + x + 1;
+          changed[at] = changed[at - side] + rowChanged;
+          change[at] = change[at - side] + rowChange;
+          level[at] = level[at - side] + rowLevel;
+        }
+      }
+      let most = 0;
+      for (let wy = 0; wy < WINDOWS_PER_SIDE; wy++) {
+        for (let wx = 0; wx < WINDOWS_PER_SIDE; wx++) {
+          const window = wy * WINDOWS_PER_SIDE + wx;
+          const a = wy * side + wx;
+          const b = a + FIELD;
+          const c = a + FIELD * side;
+          const d = c + FIELD;
+          const area = changed[d] - changed[b] - changed[c] + changed[a];
+          const step = (change[d] - change[b] - change[c] + change[a]) / FIELD_CELLS;
+          const mean = (level[d] - level[b] - level[c] + level[a]) / FIELD_CELLS;
+          if (frame === 1) {
+            peakLevel[window] = mean - step;
+            valleyLevel[window] = mean - step;
+          }
+          const value = signal[window] + (area >= AREA ? step : 0);
+          signal[window] = value;
+          let transition = false;
+          if (direction[window] >= 0) {
+            if (value > peakValue[window]) {
+              peakValue[window] = value;
+              peakLevel[window] = mean;
+            } else if (peakValue[window] - value >= threshold) {
+              transition = Math.min(mean, peakLevel[window]) < darkLimit;
+              direction[window] = -1;
+              valleyValue[window] = value;
+              valleyLevel[window] = mean;
+            }
+          }
+          if (direction[window] <= 0) {
+            if (value < valleyValue[window]) {
+              valleyValue[window] = value;
+              valleyLevel[window] = mean;
+            } else if (value - valleyValue[window] >= threshold) {
+              transition = Math.min(mean, valleyLevel[window]) < darkLimit;
+              direction[window] = 1;
+              peakValue[window] = value;
+              peakLevel[window] = mean;
+            }
+          }
+          const base = window * RING;
+          while (
+            tail[window] < head[window] &&
+            frame - ring[base + (tail[window] % RING)] >= ANALYSIS_FPS
+          )
+            tail[window]++;
+          if (transition) {
+            ring[base + (head[window] % RING)] = frame;
+            head[window]++;
+          }
+          const count = head[window] - tail[window];
+          if (count > most) most = count;
+        }
+      }
+      peak = Math.max(peak, most);
+      if (most > MAX_TRANSITIONS) {
+        const start = Math.max(0, frame + 1 - ANALYSIS_FPS) / ANALYSIS_FPS;
+        const end = (frame + 1) / ANALYSIS_FPS;
+        const last = failures.at(-1);
+        if (last && start <= last.end) last.end = end;
+        else failures.push({ start, end });
+      }
+    },
+    summary() {
+      return {
+        maxFlashesPerSecond: peak / 2,
+        failures: failures.slice(0, 20).map(({ start, end }) => ({
+          start: Math.round(start * 100) / 100,
+          end: Math.round(end * 100) / 100,
+        })),
+      };
+    },
+  };
+}
+
+/** Pure analysis over linear-light RGB frames of GRID × GRID cells (3 bytes per cell). */
+export function createFlashAnalyzer() {
+  const general = createChannel(CHANNELS.general);
+  const red = createChannel(CHANNELS.red);
+  let luminance = new Float64Array(CELLS);
+  let redness = new Float64Array(CELLS);
+  let previousLuminance = new Float64Array(CELLS);
+  let previousRedness = new Float64Array(CELLS);
+  let frames = 0;
+  return {
+    push(frame) {
+      if (!(frame instanceof Uint8Array) || frame.length !== FRAME_BYTES)
+        throw new Error(`Expected ${FRAME_BYTES}-byte analysis frames`);
+      for (let cell = 0; cell < CELLS; cell++) {
+        const r = frame[cell * 3] / 255;
+        const g = frame[cell * 3 + 1] / 255;
+        const b = frame[cell * 3 + 2] / 255;
+        luminance[cell] = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+        const total = r + g + b;
+        redness[cell] = total > 0 && r / total >= 0.8 ? Math.max(0, (r - g - b) * 320) : 0;
+      }
+      if (frames > 0) {
+        general.update(frames, previousLuminance, luminance);
+        red.update(frames, previousRedness, redness);
+      }
+      [previousLuminance, luminance] = [luminance, previousLuminance];
+      [previousRedness, redness] = [redness, previousRedness];
+      frames++;
+    },
+    result() {
+      const generalSummary = general.summary();
+      const redSummary = red.summary();
+      return {
+        ok: frames >= 2 && !generalSummary.failures.length && !redSummary.failures.length,
+        method: "rendered-pixels",
+        standard: "WCAG 2.3.1 general and red flash thresholds",
+        analysisFps: ANALYSIS_FPS,
+        frames,
+        duration: frames / ANALYSIS_FPS,
+        general: generalSummary,
+        red: redSummary,
+      };
+    },
+  };
+}
+
+/** Decode a video into linear-light analysis frames and return the flash report. */
+export async function analyzeFlashes(file, signal) {
+  const binary = await ffmpegBinary();
+  const child = spawn(
+    binary,
+    [
+      "-hide_banner",
+      "-nostdin",
+      "-loglevel",
+      "error",
+      "-xerror",
+      "-protocol_whitelist",
+      "file,pipe",
+      "-i",
+      file,
+      "-map",
+      "0:v:0",
+      "-an",
+      "-vf",
+      [
+        // Linearise before any averaging: shrinking sRGB values first darkens fine detail
+        // by up to half the flash threshold.
+        "format=gbrp",
+        `lutrgb=r='${LINEAR}':g='${LINEAR}':b='${LINEAR}'`,
+        `scale=${GRID}:${GRID}:flags=area`,
+        `fps=${ANALYSIS_FPS}`,
+        "format=rgb24",
+      ].join(","),
+      "-f",
+      "rawvideo",
+      "-pix_fmt",
+      "rgb24",
+      "pipe:1",
+    ],
+    { stdio: ["ignore", "pipe", "pipe"], windowsHide: true, signal },
+  );
+  let stderr = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (text) => {
+    if (stderr.length < 16_000) stderr += text;
+  });
+  const closed = once(child, "close");
+  closed.catch(() => {});
+  const analyzer = createFlashAnalyzer();
+  const frame = new Uint8Array(FRAME_BYTES);
+  let filled = 0;
+  for await (const chunk of child.stdout) {
+    let offset = 0;
+    while (offset < chunk.length) {
+      const take = Math.min(FRAME_BYTES - filled, chunk.length - offset);
+      frame.set(chunk.subarray(offset, offset + take), filled);
+      filled += take;
+      offset += take;
+      if (filled === FRAME_BYTES) {
+        analyzer.push(frame);
+        filled = 0;
+      }
+    }
+  }
+  const [code] = await closed;
+  if (code !== 0)
+    throw new Error(`FFmpeg could not decode the video: ${stderr.trim().slice(-2000)}`);
+  if (filled !== 0) throw new Error("Decoded video ended mid-frame; flashing is unverified");
+  const result = analyzer.result();
+  if (result.frames < 2) throw new Error("Too few decoded frames; flashing is unverified");
+  return result;
+}
+
+async function videoHash(file, signal) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(file, { signal })) hash.update(chunk);
+  return hash.digest("hex");
+}
+
+async function main() {
+  const [video, ...extra] = process.argv.slice(2);
+  if (!video || extra.length) throw new Error("usage: flash-check.mjs <rendered-video>");
+  const file = resolve(video);
+  if (!(await stat(file)).isFile()) throw new Error("Expected a local rendered video file");
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGTERM", abort);
+  process.once("SIGINT", abort);
+  const started = performance.now();
+  try {
+    const videoSha256 = await videoHash(file, controller.signal);
+    const result = await analyzeFlashes(file, controller.signal);
+    if ((await videoHash(file, controller.signal)) !== videoSha256)
+      throw new Error("Video changed during analysis; flashing is unverified");
+    process.stdout.write(
+      `${JSON.stringify({ ...result, file, videoSha256, elapsedMs: Math.round(performance.now() - started) })}\n`,
+    );
+    if (!result.ok) process.exitCode = 1;
+  } finally {
+    process.removeListener("SIGTERM", abort);
+    process.removeListener("SIGINT", abort);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    await main();
+  } catch (error) {
+    process.stderr.write(
+      `Flash verification failed: ${error instanceof Error ? error.message : "invalid input"}\n`,
+    );
+    process.exitCode = 1;
+  }
+}

package/assets/motion/references/motion-language.md

@@ -10,7 +10,9 @@ copy an earlier video's.
 Make a showcase piece, as if the best motion designers will judge it frame by
 frame. Ambition means deliberate craft, not length or effect count. Every
 colour, word, cut and ease needs a reason. Cut generic defaults: plain fades,
-slowly drifting gradients, text that slides up and sits there.
+slowly drifting gradients, text that slides up and sits there. Judge it as the
+kind of video it is: an explainer by how clearly it teaches, a tribute by how
+it honours its subject, a launch by how it makes people want the product.
 
 ## Plan first
 
@@ -20,58 +22,94 @@ Before writing code, decide these and record them in the `Concept` and
 - **Concept**: the idea the video demonstrates, in one sentence. Show it; don't
   just state it.
 - **Motif**: one shape or element that recurs and links every scene.
+- **Register**: the tone (calm, playful, urgent, tender, precise…) and what it
+  means for size, speed, easing and colour. Take it from the brief, the brand
+  and the viewing context.
 - **Palette**: each colour's role.
 - **Type**: each family's role.
 - **Beat**: tempo, arc and frame rate.
 
 ## Principles
 
+**Register.** Map the tone to motion before choosing anything else. Quiet,
+steady motion carries information and reading; expressive motion is saved for
+the moments that matter, because it only reads as special against calm. These
+pairings are illustrative, not presets: calm is long, soft moves and few of
+them; playful is springy overshoot, squash and stretch; luxurious is slow and
+precise with generous space; urgent is fast moves and hard cuts; tender is
+warm, slow and held; technical is precise and snapping.
+
 **Continuity.** Each scene hands something to the next: a shape, a word, a
 colour field or a camera move. Prefer match cuts and shape handoffs to
 cross-fades. The `type-as-spatial-handoff` study in [README.md](README.md) shows
 type becoming the next scene.
 
-**Palette.** At most four flat colours: a dark neutral, a light neutral, one
-saturated hero colour and one bright accent used sparingly. Derive them from
-the brand or subject. Full-frame colour blocks that change on most cuts carry
-energy; gradients and glows are seasoning, not the base. Keep text readable.
-
-**Type.** One heavy display family, set huge: hero words around 250–360 px at
-1080p, one to three words per shot. Keep any explanatory line short. Animate
-weight and width axes as motion, not only position and opacity. Add at most one
-contrasting voice, such as an italic serif, plus small uppercase tracked mono
-for labels and UI. Bundled axes (see `fonts.mjs list` and its specimen): weight
-and width in Mona Sans, Hubot Sans, Anybody, Archivo, Bricolage Grotesque and
-Martian Mono; italics in Fraunces and Newsreader. Brand fonts win.
-
-**Motion.** Entrances `expo.out`; exits `power3.in`; moves `expo.inOut` or
-`power3.inOut`; pops `back.out`; settles `elastic.out`, sparingly. Most
-durations 0.12–0.7 s; staggers 0.012–0.06 s. Use real animation principles
-where they help: anticipation before big moves, squash and stretch on impact,
-arcs instead of straight paths, overlapping action, follow-through and smears on
-fast moves. Every move starts, travels and lands on purpose; nothing drifts. For
-calm or luxury subjects, lengthen durations and soften eases, and stay just as
-deliberate.
-
-**Pace.** Cut on a beat grid even without music: 0.5 s at 120 BPM by default,
-or the track's beats (`hf beats`) when there is music. For a short promo: a slow
-opening, a fast-cut middle, one showpiece moment, a climax such as a
-convergence or particle burst, then an end card held about 2 s. Declare that
-hold in the hold plan before checking.
-
-**3D, when the subject earns it.** One hero object with a physical material
-(clearcoat or iridescent) and environment lighting; a few supporting elements
-such as orbiting rings, trails or sparse debris; a soft coloured glow; a
-cinematic camera move such as an orbit or dolly zoom. Resolve 3D back to flat 2D
-to hand off to the next scene. Use the bundled Three.js (`three.mjs`); no 3D by
+**Palette.** A few colours, each with a role, derived from the brand, subject or
+references. How many, how saturated and how often the frame changes colour
+follow the register: full-frame colour blocks that change on most cuts suit a
+loud, kinetic piece; a calm, tender or documentary piece holds a steadier field
+and lets one accent carry attention. Gradients and glows are seasoning, not the
+base. Keep text readable.
+
+**No harmful flashing.** Anything flashing over more than about 3% of the frame
+counts. Keep light/dark swaps, and swaps to and from saturated red, to at most
+six in any one second (three flashes): faster flashing can trigger seizures,
+and `motion_check` fails it. A swap on every beat at 120 BPM is fine; a white
+flash frame on every half-beat is not.
+
+**Type.** Choose faces for the register and the reading job. Size follows the
+viewing context and how much there is to read: a kinetic poster can set one to
+three huge words per shot; an explainer, documentary or lyric video sets whole
+lines at a comfortable reading size. Size type against the frame's shorter side
+(in vertical video, the width inside the safe margins) and check that the
+longest word fits. Animate weight and width axes as motion, not only position
+and opacity. Use one display family, at most one contrasting voice, such as an
+italic serif, and small uppercase tracked mono for labels and UI where the
+subject calls for it. Bundled axes (see `fonts.mjs list` and its specimen):
+weight and width in Mona Sans, Hubot Sans, Anybody, Archivo, Bricolage
+Grotesque and Martian Mono; italics in Fraunces and Newsreader. Brand fonts win.
+
+**Motion.** Smooth by default, bounce by choice. Entrances settle on the
+critically damped spring or `power3.out` / `expo.out`; exits `power3.in`; moves
+`power3.inOut` or `expo.inOut`. Overshoot (`back.out`, `elastic.out` or an
+underdamped spring) is a register chosen for playful or physical work, never
+the default; see [easing](runtime/gsap-easing-and-stagger.md). Durations follow
+the register: roughly 0.15–0.5 s for snappy, energetic or technical motion, and
+0.6–1.5 s or longer for calm, luxurious or tender work. Staggers run 0.012–0.06 s
+for type and longer for larger elements. Use real animation principles where
+they help: anticipation before big moves, squash and stretch on impact, arcs
+instead of straight paths, overlapping action, follow-through and smears on fast
+moves. Lead with one movement at a time, with smaller overlapping motion under
+it. Every move starts, travels and lands on purpose; nothing drifts without a
+reason.
+
+**Pace.** Keep time on a grid: the track's beats (`hf beats`) when there is
+music, otherwise a tempo chosen for the register. Cut by how much there is to
+take in, not by the grid alone: a simple image can last one beat; a line to
+read or an idea to grasp holds for several. Meaningful text stays still and
+readable for at least the longer of 0.8 s and one second per 15 characters,
+longer for the key line; repeated or decorative words can go faster. Vary the
+density (build, release, rest) so the video is neither always fast nor always
+slow. Shape the whole to its form, with a beginning, development, peak and
+resolution even in five seconds. Illustratively: a launch builds to its
+product, an explainer steps through its idea, a lyric video follows the song's
+sections, a tribute lets each moment breathe. End on a composed frame held long
+enough to read, and declare that hold in the hold plan before checking.
+
+**3D, when the subject earns it.** One hero object whose material, light and
+camera come from the concept and register, not a stock tech look; add
+supporting elements only when they mean something. Resolve 3D back to flat 2D to
+hand off to the next scene. Use the bundled Three.js (`three.mjs`); no 3D by
 default.
 
 **Chrome, when it suits.** A small persistent mono layer (labels, timecode,
 chapter name, a progress bar with markers) makes a tech subject feel like a pro
 tool. Leave it out elsewhere.
 
-**Frame rate.** 60 fps for fast, dense motion, where smears and quick cuts read
-cleaner; 30 fps for calmer pieces. 60 fps doubles render time.
+**Frame rate.** 30 fps suits most work. Use 60 fps when fast, dense motion or
+scrolling UI must read smoothly; it doubles render time. Renders carry no
+motion blur, so fast moves stutter at 24 fps: keep 24 fps for slow, filmic or
+handmade work.
 
 **Truth.** Show only real product UI, numbers and claims from the user's
 sources.
@@ -79,7 +117,7 @@ sources.
 ## Building blocks
 
 Library looks (`library.mjs list looks`) are complete palette, type and rhythm
-systems; when one fits the concept, it replaces the palette and type defaults
+systems; when one fits the concept, it replaces the palette and type choices
 above. Library pieces are optional building blocks.
 
 ## Check against the plan

package/assets/motion/references/runtime/gsap-easing-and-stagger.md

@@ -6,19 +6,19 @@ Built-in eases: `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`
 
 Each has `.in`, `.out`, `.inOut` variants.
 
-| Ease                                       | Use for                                                                                         |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default. |
-| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                            |
-| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                             |
-| `back.out(1.7)`                            | Overshoot then settle. RARE — explicitly-playful register only, never a default.                |
-| `elastic.out(1, 0.3)`                      | Springy bounce. Same playful-only rule; prefer a baked spring (see Spring Eases below).         |
-| `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                        |
-| `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                        |
+| Ease                                       | Use for                                                                                                 |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default.         |
+| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                                    |
+| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                                     |
+| `back.out(1.7)`                            | Overshoot then settle. A chosen register (playful, physical), never a default.                          |
+| `elastic.out(1, 0.3)`                      | Springy bounce. Same register rule; prefer a baked spring (see Spring Eases below).                     |
+| `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                                |
+| `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                                |
 
 Pick `.out` for entrances, `.in` for exits, `.inOut` for symmetric moves and continuous motion.
 
-**Smooth beats bouncy** — the motion doctrine (`rules/spring-pop-entrance.md`, the workflows' `motion-language.md`): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`) are a rare, explicitly-playful register, never the house style.
+**Smooth by default, bounce by choice** — the same rule as the Motion section of [`motion-language.md`](../motion-language.md): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`, or an underdamped spring) are a register the brief chooses for playful or physical work, never the house style.
 
 ## Easing Vocabulary (character & mood)
 
@@ -29,15 +29,15 @@ The full palette by character (each family has `.in`, `.out`, `.inOut` variants)
 | Family               | Character                                                                    | Typical use                                                                                                                                  |
 | -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                            |
-| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | RARE — explicitly-playful register only, never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
-| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | RARE — same playful-only rule; the baked spring (below) is the physical version                                                              |
-| `bounce`             | Ball-drop bouncing                                                           | RARE — physical-comedy register only (something literally dropping)                                                                          |
+| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Chosen register only (playful, physical), never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
+| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Same register rule; the baked spring (below) is the physical version                                                                         |
+| `bounce`             | Ball-drop bouncing                                                           | Physical-comedy register only (something literally dropping)                                                                                 |
 | `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                                                                   |
 | `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                                                           |
 | `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                                                              |
 | `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                                                                        |
 
-**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only on explicitly-playful beats. The storyboard's mood description should guide which character fits — not a formula.
+**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only when the brief's register is playful or physical. The register recorded in `frame.md` should guide which character fits — not a formula.
 
 ## Defaults
 
@@ -58,7 +58,7 @@ Setting defaults at timeline scope is preferred — it documents the motion lang
 
 ## Spring Eases (baked physics, seek-safe)
 
-The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for the rare playful register — bake the spring's closed-form solution into a function ease.
+The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for a playful register — bake the spring's closed-form solution into a function ease.
 
 Why not a real-time spring library: an interactive spring is a stateful integrator (velocity accumulates frame to frame), which cannot be seeked deterministically — you'd have to simulate frames 0…N−1 to render frame N. The closed form below is a **pure function of progress** — no state, nothing to desync, seek-safe by construction. This is also why interaction-lib spring solvers are banned in compositions.
 
@@ -67,7 +67,7 @@ Why not a real-time spring library: an interactive spring is a stateful integrat
 // response         ≈ seconds one oscillation would take (0.3–0.6 for entrances)
 // dampingFraction  1.0       = critically damped — smooth settle, NO overshoot (house default)
 //                  0.80–0.85 ≈ the iOS system register — ~1–1.5% overshoot, felt not seen
-//                  0.60–0.70 = explicitly playful — ~5–10% overshoot (rare; replaces back.out)
+//                  0.60–0.70 = playful register — ~5–10% overshoot (by choice; replaces back.out)
 function springEase({ response = 0.5, dampingFraction = 1 } = {}) {
   const w = (2 * Math.PI) / response; // undamped natural frequency
   const z = dampingFraction;
@@ -120,20 +120,20 @@ tl.fromTo(
 | ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                 |
 | 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                            |
-| 0.60–0.70         | ~5–10%          | Explicitly-playful ONLY (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
+| 0.60–0.70         | ~5–10%          | Playful register, by choice (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
 | < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                   |
 
 | response  | duration (ζ=1) | feel                                                         |
 | --------- | -------------- | ------------------------------------------------------------ |
 | 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                 |
 | 0.35–0.50 | 0.51–0.74s     | standard entrance                                            |
-| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — check the `t ≤ 0.5s` visibility rule |
+| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — when the shot opens on it, start it early so the subject is seen within about half a second |
 
 Craft notes:
 
 - **ζ=1 vs `power3.out`**: the true spring front-loads harder (~67% vs ~58% travelled at quarter-time) and settles on a longer asymptotic tail; max shape difference ~11%. That long tail is the "premium" read — use it when the settle IS the shot (a wordmark landing, a final lockup).
 - **At ζ<1, overshooting curves go on transforms only** — never on `opacity` (it would push past 1) or color. Split opacity onto its own `power2.out` tween at the same timeline position.
-- **Doctrine unchanged**: ζ below ~0.8 is still the rare, explicitly-playful exception (`rules/spring-pop-entrance.md`). The default of this section is ζ=1 — real spring physics is not a license for bounce.
+- **Default unchanged**: ζ below ~0.8 is a register the brief chooses, never a default. The default of this section is ζ=1 — real spring physics is not a license for bounce.
 
 ## Stagger
 

package/assets/motion/references/runtime/minimal-composition.md

@@ -67,3 +67,9 @@ What the runtime actually requires:
 Everything else in the skeleton is ordinary HTML and CSS: the `#root` box, `.clip` positioning, and fonts are yours to choose.
 
 This pattern is **standalone** (top-level `index.html`) — no `<template>` wrapper around the root. For sub-compositions (files loaded by `data-composition-src`), see `sub-compositions.md`.
+
+## Vertical (9:16)
+
+For phone-first video, set the viewport meta to `width=1080, height=1920`, give the root `data-width="1080"` and `data-height="1920"`, and render with the matching size (`--resolution portrait`). Everything else stays the same.
+
+Size type against the frame's width, not its height: a 96 px headline that suits a 1920 px-wide frame takes over half the width of a 1080 px one, so check that the longest word fits. When the video will play in a feed (Reels, TikTok, Shorts), keep text, logos and key subjects out of the areas the app covers. Meta asks for the top 14%, the bottom 35% and 6% on each side to stay clear (about 270 px, 670 px and 65 px at 1080×1920); TikTok covers a similar band at the bottom and a column of buttons on the right.

package/assets/motion/skills/brand-kit/SKILL.md

@@ -19,9 +19,10 @@ Do not overwrite a reusable kit while editing a video.
 3. Record the selected kit and bindings in the video's `frame.md`.
 
 The kit's colours, fonts and motion personality feed the plan: they replace
-the motion-language defaults. Required identity outranks taste; if it conflicts
-with a requested treatment, resolve that actual choice with the user instead of
-silently changing the font, logo or colours.
+the motion-language defaults and set its palette, type and register. Required
+identity outranks taste; if it conflicts with a requested treatment, resolve
+that actual choice with the user instead of silently changing the font, logo or
+colours.
 
 If the source was already captured and the kit approved, reuse it. Do not
 repeat a brand interview, capture, audit or approval for a new headline.