@litfamily/litopencode 1.0.30 → 1.0.32

package/skills/lit-typographic-motion/engine/styles.mjs

@@ -0,0 +1,221 @@
+// House styles: the data a film is built from, so two films in one style share palette, faces, type
+// scale, layout zones, motion tokens, transitions and sound. A style lives in `styles/<id>.json`; the
+// treatment names one, the validator checks it is the style the rules choose (named in the request,
+// the project's house style, or the fixed keyword pick), the stage renderer serves it to the page as
+// /lit/style.css and /lit/style.js, and the text QA judges copy against it. Layout zones are one grid
+// for every style, named per shot and mapped per format, so a story re-lays itself per format instead
+// of being cropped. The three styles with a `typePreset` mean the same on the type path.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { keywordMatches } from "./text.mjs";
+
+export const STYLE_SCHEMA = "litopencode.motion-style/v1";
+export const STYLE_IDS = Object.freeze(["swiss-signal", "tidal", "terminalcore", "paper"]);
+export const DEFAULT_STYLE = "swiss-signal";
+export const TYPE_ROLES = Object.freeze(["display", "headline", "body", "label"]);
+export const TRANSITIONS = Object.freeze(["cut", "match", "wipe", "push", "iris", "dissolve", "morph"]);
+// Copy may sit this far (a share of the frame side) outside its zone, and this far off a scale step.
+export const ZONE_TOLERANCE = 0.012;
+export const SIZE_TOLERANCE = 0.04;
+
+// [x, y, w, h] as fractions of the frame. `type` is where copy may sit; `subject` is where the drawing
+// leads (a `title` or `full` subject spans the frame as a backdrop). Every type zone lies inside the
+// central 90 % title-safe area.
+export const LAYOUTS = Object.freeze({
+  "16:9": Object.freeze({
+    title: { type: [0.08, 0.2, 0.84, 0.6], subject: [0, 0, 1, 1] },
+    split: { type: [0.08, 0.16, 0.36, 0.68], subject: [0.48, 0.08, 0.46, 0.84] },
+    "split-alt": { type: [0.56, 0.16, 0.36, 0.68], subject: [0.06, 0.08, 0.46, 0.84] },
+    stage: { type: [0.08, 0.75, 0.84, 0.18], subject: [0.06, 0.07, 0.88, 0.64] },
+    hero: { type: [0.08, 0.76, 0.84, 0.17], subject: [0.03, 0.03, 0.94, 0.94] },
+    full: { type: null, subject: [0, 0, 1, 1] }
+  }),
+  "9:16": Object.freeze({
+    title: { type: [0.09, 0.26, 0.82, 0.48], subject: [0, 0, 1, 1] },
+    split: { type: [0.09, 0.08, 0.82, 0.26], subject: [0.06, 0.36, 0.88, 0.56] },
+    "split-alt": { type: [0.09, 0.66, 0.82, 0.26], subject: [0.06, 0.06, 0.88, 0.56] },
+    stage: { type: [0.09, 0.79, 0.82, 0.13], subject: [0.06, 0.06, 0.88, 0.68] },
+    hero: { type: [0.09, 0.8, 0.82, 0.12], subject: [0.03, 0.03, 0.94, 0.94] },
+    full: { type: null, subject: [0, 0, 1, 1] }
+  })
+});
+export const LAYOUT_IDS = Object.freeze(Object.keys(LAYOUTS["16:9"]));
+const FRAME = Object.freeze({ "16:9": [1920, 1080], "9:16": [1080, 1920] });
+
+// With no name, house file or keyword, the genre picks the style where one reads better than the
+// default: an explainer on the warm, legible paper ground (stage only), a brand mood on the tidal flow.
+export const GENRE_STYLE = Object.freeze({ explainer: "paper", "brand-mood": "tidal" });
+
+// Checked in order; the first row with a whole-word hit wins. A style the request names outright wins
+// over every row. `paper` has no type-engine preset, so the type path skips its row.
+export const STYLE_PICK = Object.freeze([
+  { style: "terminalcore", korean: ["터미널", "CRT", "해커"], latin: ["terminal", "hacker", "crt"] },
+  { style: "tidal", korean: ["물결", "파도", "잔잔한", "흐름"], latin: ["gradient", "wave", "tide", "calm"] },
+  { style: "paper", korean: ["따뜻한", "밝은", "종이", "손그림", "포근한", "아기자기"], latin: ["warm", "cozy", "bright", "paper", "handmade", "hand-drawn"] }
+]);
+const NAMED = Object.freeze({
+  "swiss-signal": ["swiss-signal", "swiss signal", "스위스 시그널"],
+  tidal: ["tidal", "타이달"],
+  terminalcore: ["terminalcore", "터미널코어"],
+  paper: ["paper style", "paper look", "페이퍼 스타일", "페이퍼"]
+});
+
+export class StyleError extends Error {}
+
+const HEX = /^#[0-9a-f]{6}$/iu;
+const isText = (v) => typeof v === "string" && v.trim().length > 0;
+
+// WCAG relative luminance and contrast ratio of #rrggbb colours.
+export function relativeLuminance(hex) {
+  const channel = (i) => {
+    const c = parseInt(hex.slice(1 + 2 * i, 3 + 2 * i), 16) / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(0) + 0.7152 * channel(1) + 0.0722 * channel(2);
+}
+export function contrastRatio(a, b) {
+  const hi = Math.max(a, b), lo = Math.min(a, b);
+  return (hi + 0.05) / (lo + 0.05);
+}
+const lum = relativeLuminance;
+
+// Validate a style document; returns it or throws StyleError naming the first bad field.
+export function validateStyle(style) {
+  const fail = (field, message) => { throw new StyleError(`style ${style?.id ?? "?"}: ${field}: ${message}`); };
+  if (!style || typeof style !== "object") fail("style", "must be an object");
+  if (style.schema !== STYLE_SCHEMA) fail("schema", `must be ${STYLE_SCHEMA}`);
+  if (!STYLE_IDS.includes(style.id)) fail("id", `must be one of ${STYLE_IDS.join(", ")}`);
+  for (const k of ["name", "summary"]) if (!isText(style[k])) fail(k, "must be a non-empty string");
+  const p = style.palette ?? {};
+  for (const role of ["ground", "surface", "ink", "muted", "signal", "line"]) if (!HEX.test(p[role] ?? "")) fail(`palette.${role}`, "must be #rrggbb");
+  if (!Array.isArray(style.textRoles) || style.textRoles.some((r) => !HEX.test(p[r] ?? ""))) fail("textRoles", "every text role names a palette colour");
+  const ground = lum(p.ground);
+  if (contrastRatio(lum(p.ink), ground) < 7) fail("palette.ink", "ink on ground needs 7:1");
+  if (contrastRatio(lum(p.muted), ground) < 4.5) fail("palette.muted", "muted on ground needs 4.5:1");
+  for (const role of ["signal", "accent"]) if (p[role] && contrastRatio(lum(p[role]), ground) < 3) fail(`palette.${role}`, `${role} on ground needs 3:1 (large type)`);
+  if (!Array.isArray(style.accents) || style.accents.length < 3) fail("accents", "names at least three role accents a rich film may add");
+  style.accents.forEach((a, i) => {
+    if (!isText(a?.role)) fail(`accents[${i}].role`, "says what the colour marks");
+    if (!HEX.test(a?.color ?? "")) fail(`accents[${i}].color`, "must be #rrggbb");
+    if (contrastRatio(lum(a.color), ground) < 3) fail(`accents[${i}].color`, "an accent on ground needs 3:1 (large type)");
+  });
+  for (const role of TYPE_ROLES) if (!isText(style.faces?.[role]?.family)) fail(`faces.${role}`, "needs a family");
+  for (const format of Object.keys(FRAME)) {
+    const s = style.scale?.[format];
+    if (!s || TYPE_ROLES.some((r) => !(s[r] > 0))) fail(`scale.${format}`, "needs a size per type role");
+    if (!(s.display > s.headline && s.headline > s.body && s.body > s.label)) fail(`scale.${format}`, "steps must descend display > headline > body > label");
+  }
+  const m = style.motion ?? {};
+  for (const k of ["enter", "move", "exit"]) if (!Array.isArray(m.ease?.[k]) || m.ease[k].length !== 4) fail(`motion.ease.${k}`, "is a cubic-bezier [x1, y1, x2, y2]");
+  for (const k of ["micro", "move", "hero", "exit"]) if (!(m.dur?.[k] > 0)) fail(`motion.dur.${k}`, "seconds > 0");
+  if (!(m.dur.exit <= m.dur.hero)) fail("motion.dur.exit", "an exit is never longer than the hero move");
+  if (!Array.isArray(style.transitions) || !style.transitions.length || style.transitions.some((x) => !TRANSITIONS.includes(x))) fail("transitions", `a subset of ${TRANSITIONS.join(", ")}`);
+  if (!isText(style.score?.genre)) fail("score.genre", "names the genre a film's score takes by default");
+  if (!style.sound || !isText(style.sound.palette)) fail("sound", "needs the generated bed's palette");
+  const bedOk = (b) => isText(b?.palette) && isText(b?.key) && b?.tempo > 0;
+  if (!Array.isArray(style.beds) || style.beds.length < 2 || !style.beds.every(bedOk)) fail("beds", "lists at least two beds a film may pick, each { palette, key, tempo }");
+  const same = (a, b) => ["palette", "key", "tempo"].every((k) => String(a[k]).toLowerCase() === String(b[k]).toLowerCase());
+  if (!style.beds.some((b) => same(b, style.sound))) fail("beds", "must include the default bed (sound)");
+  if (!Array.isArray(style.bans) || style.bans.length < 3) fail("bans", "names at least three defaults this style never uses");
+  return style;
+}
+
+const cache = new Map();
+// Load a shipped style by id (validated, frozen).
+export function readStyle(id) {
+  if (!STYLE_IDS.includes(id)) throw new StyleError(`unknown style: ${id} (choose ${STYLE_IDS.join(", ")})`);
+  if (!cache.has(id)) cache.set(id, Object.freeze(validateStyle(JSON.parse(readFileSync(fileURLToPath(new URL(`../styles/${id}.json`, import.meta.url)), "utf8")))));
+  return cache.get(id);
+}
+
+// Every font family copy may use in this style (the role faces, the Hangul face, Pretendard).
+export const styleFamilies = (style) => new Set([...TYPE_ROLES.map((r) => style.faces[r].family), style.hangul?.family ?? "Pretendard", "Pretendard"]);
+// The hex colours copy may use.
+export const styleTextColors = (style) => style.textRoles.map((r) => style.palette[r].toLowerCase());
+// The beds a film in this style may pick from, the default first.
+export const styleBeds = (style) => style.beds;
+// The role accents a rich film may add to the core palette, each { role, color }.
+export const styleAccents = (style) => style.accents;
+// All palette colours of the style (what a stage treatment's palette may list); rich adds the accents.
+export const styleColors = (style, { rich = false } = {}) => [...Object.values(style.palette), ...(rich ? style.accents.map((a) => a.color) : [])].map((c) => c.toLowerCase());
+
+// Which style a film takes. A style the request names wins; then the project's house style; then the
+// keyword pick; then the genre's style; then the default. Returns { id, source, reason }.
+export function pickStyle({ request = "", copy = [], path = "stage", house = null, genre = null } = {}) {
+  const text = String(request);
+  for (const [id, names] of Object.entries(NAMED)) {
+    if (path === "type" && !readStyle(id).typePreset) continue;
+    const hit = names.find((n) => keywordMatches(text, n));
+    if (hit) return { id, source: "request", reason: `the request names the ${id} style ("${hit}")` };
+  }
+  if (house?.style && STYLE_IDS.includes(house.style) && (path !== "type" || readStyle(house.style).typePreset)) {
+    return { id: house.style, source: "house", reason: `the project's house style is ${house.style} (motion-house.json)` };
+  }
+  const haystack = [text, ...copy].join("\n");
+  for (const row of STYLE_PICK) {
+    if (path === "type" && !readStyle(row.style).typePreset) continue;
+    for (const k of [...row.korean, ...row.latin]) if (keywordMatches(haystack, k)) return { id: row.style, source: "auto", reason: `the request mentions "${k}"` };
+  }
+  const byGenre = GENRE_STYLE[genre];
+  if (byGenre && (path !== "type" || readStyle(byGenre).typePreset)) return { id: byGenre, source: "genre", reason: `no style is named and no keyword picks one, and a ${genre} film takes ${byGenre}` };
+  return { id: DEFAULT_STYLE, source: "default", reason: `no style is named and no keyword picks one, so the default ${DEFAULT_STYLE}` };
+}
+
+// A layout's zones in pixels for a format: { type: {x, y, w, h} | null, subject: {...} }.
+export function zonesPx(format) {
+  const [W, H] = FRAME[format];
+  const px = (r) => (r ? { x: Math.round(r[0] * W), y: Math.round(r[1] * H), w: Math.round(r[2] * W), h: Math.round(r[3] * H) } : null);
+  return Object.fromEntries(Object.entries(LAYOUTS[format]).map(([id, z]) => [id, { type: px(z.type), subject: px(z.subject) }]));
+}
+
+// The type step a rendered size sits on, or null when it is off the style's scale.
+export function scaleStep(style, format, sizePx) {
+  for (const role of TYPE_ROLES) {
+    const step = style.scale[format][role];
+    if (Math.abs(sizePx - step) <= step * SIZE_TOLERANCE) return role;
+  }
+  return null;
+}
+
+const familyStack = (style, role) => {
+  const hangul = style.hangul?.family ?? "Pretendard";
+  return [style.faces[role].family, hangul, "Pretendard"].filter((x, i, a) => a.indexOf(x) === i).map((x) => `"${x}"`).join(", ");
+};
+
+// /lit/style.css for one style and format: custom properties, type-role classes, colour classes.
+export function styleCss(style, format) {
+  const s = style.scale[format];
+  const vars = [
+    ...Object.entries(style.palette).map(([k, v]) => `  --lit-${k}: ${v};`),
+    ...TYPE_ROLES.map((r) => `  --lit-size-${r}: ${s[r]}px;`)
+  ];
+  const roles = TYPE_ROLES.map((r) => {
+    const f = style.faces[r];
+    return `.lit-${r} { font-family: ${familyStack(style, r)}; font-size: ${s[r]}px; font-weight: ${f.weight}; ${f.stretch ? `font-stretch: ${f.stretch}; ` : ""}line-height: ${style.leading?.[r] ?? 1.3}; letter-spacing: 0; margin: 0; }`;
+  });
+  const colours = style.textRoles.map((r) => `.lit-${r === "ground" ? "knockout" : r} { color: var(--lit-${r}); }`);
+  return [
+    `/* lit-typographic-motion style: ${style.id} (${format}) */`,
+    `:root {\n${vars.join("\n")}\n}`,
+    // Korean breaks only between eojeol, never inside a word (type-craft.md).
+    `html, body { margin: 0; overflow: hidden; background: var(--lit-ground); color: var(--lit-ink); font-family: ${familyStack(style, "body")}; word-break: keep-all; overflow-wrap: break-word; }`,
+    ...roles,
+    ...colours,
+    ".lit-zone { position: absolute; box-sizing: border-box; }",
+    ""
+  ].join("\n");
+}
+
+// /lit/style.js: window.LitStyle (tokens and pixel zones) and window.LitTimeline (the treatment's shots).
+export function styleScript(style, format, treatment) {
+  const timeline = {
+    format, fps: treatment.fps ?? 60, duration: treatment.durationSec,
+    beats: (treatment.beats ?? []).map((b, i) => ({ index: i, t0: b.t0, t1: b.t1, layout: b.layout ?? null, transition: b.transition ?? null }))
+  };
+  const data = {
+    id: style.id, name: style.name, format, palette: style.palette, textRoles: style.textRoles,
+    faces: style.faces, hangul: style.hangul ?? null, scale: style.scale[format], leading: style.leading ?? {},
+    motion: style.motion, transitions: style.transitions, ground: style.ground, zones: zonesPx(format)
+  };
+  return `window.LitStyle = Object.freeze(${JSON.stringify(data)});\nwindow.LitTimeline = Object.freeze(${JSON.stringify(timeline)});\n`;
+}

package/skills/lit-typographic-motion/engine/text.mjs

@@ -107,7 +107,7 @@ export function cpsFloor(text, kind = "line") {
   return unitCounts(text).C / limits.latinCharsPerSecond;
 }
 
-function keywordMatches(text, word) {
+export function keywordMatches(text, word) {
   if (/[a-z]/iu.test(word)) return new RegExp(`\\b${word}\\b`, "iu").test(text);
   return new RegExp(`(?:^|[^\\uAC00-\\uD7A3\\u1100-\\u11FF\\u3130-\\u318F])${word}`, "u").test(text);
 }

package/skills/lit-typographic-motion/engine/treatment.mjs

@@ -5,16 +5,26 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { readHouse } from "./house.mjs";
+import { LAYOUT_IDS, STYLE_IDS, pickStyle, readStyle, styleBeds, styleColors, styleFamilies } from "./styles.mjs";
 
 export const TREATMENT_EXIT = 16;
 export const genres = Object.freeze(["announcement", "brand-mood", "event", "explainer", "motion-graphics", "type-led", "other"]);
 export const arcStages = Object.freeze({ announcement: 5, event: 4, explainer: 4, "brand-mood": 4, "motion-graphics": 5, other: 3 });
-export const deviceKinds = Object.freeze(["illustration", "diagram", "chart", "icon", "shape", "path", "mask", "depth3d", "particles", "grid", "gradient", "photo-texture"]);
+export const deviceKinds = Object.freeze(["illustration", "diagram", "chart", "icon", "shape", "path", "mask", "depth3d", "screen", "particles", "grid", "gradient", "photo-texture"]);
 export const textureKinds = Object.freeze(["grid", "gradient", "particles", "photo-texture"]);
-export const soundModes = Object.freeze(["generated", "supplied", "authored", "none"]);
+export const soundModes = Object.freeze(["score", "generated", "supplied", "authored", "none"]);
+// The genres a rich film's score may take (engine/score.mjs); a style names its default.
+export const scoreGenres = Object.freeze(["house", "tech-house", "deep-house", "garage"]);
+// How full a film is. Rich is the default; minimal only when the request asks for calm or minimal.
+export const registers = Object.freeze(["rich", "minimal"]);
 export const soundPalettes = Object.freeze(["glass", "warm", "pulse", "air"]);
 // The product's own verified faces: the families `/lit/fonts.css` serves and the type engine draws.
 export const productFaces = Object.freeze(["Archivo", "Pretendard", "VT323", "Silkscreen", "MesloLGS NF", "Galmuri9"]);
+export const protagonistKinds = Object.freeze(["character", "object"]);
+// What a product asset is; a `screen` device needs one of the last three.
+export const assetRoles = Object.freeze(["logo", "wordmark", "icon", "photo", "screenshot", "ui", "readme-image"]);
+const screenRoles = new Set(["screenshot", "ui", "readme-image"]);
 const floorTenGenres = new Set(["announcement", "event", "explainer", "motion-graphics"]);
 
 // NFC, lowercase, then no whitespace and no punctuation.
@@ -64,6 +74,19 @@ const placeholder = /<[^<>\n]{1,80}>/u;
 const sentences = (text) => String(text).split(/(?<=[.!?。…])\s+/u).map((part) => part.trim()).filter(Boolean);
 const lengthAsked = /\d+(?:\.\d+)?\s*(?:s|sec|secs|seconds?|min|mins|minutes?|초|분)(?![a-z])/iu;
 const silenceAsked = /(?<![a-z])(?:silent|silence|no (?:sound|music|audio)|without (?:sound|music|audio)|muted?)(?![a-z])|무음|소리\s?없|음악\s?없|소리\s?빼/iu;
+const fpsAsked = /30\s?(?:fps|프레임|frames?\s+(?:a|per)\s+second)|\b30\s?p\b/iu;
+const previewAsked = /미리\s?보기|스토리보드|콘티|\bpreview\b|\bstoryboard\b/iu;
+const calmAsked = /미니멀|잔잔|차분|조용|심플|절제|고요|\bminimal(?:ist|ism)?\b|\bcalm\b|\bquiet\b|\bunderstated\b|\brestrained\b|\bsparse\b|\bserene\b/iu;
+const pathTracedAsked = /고퀄|고품질|하이엔드|시네마틱|실사|포토리얼|레이\s?트레이싱|블렌더|\b(?:high[- ]?(?:quality|end)|cinematic|photo-?real(?:istic)?|path[- ]?trac\w*|ray[- ]?trac\w*|blender|cycles)\b/iu;
+export const asksCalm = (request) => calmAsked.test(String(request ?? ""));
+export const asksPathTraced = (request) => pathTracedAsked.test(String(request ?? ""));
+export const registerOf = (t) => t?.register ?? "rich";
+export const asks30fps = (request) => fpsAsked.test(String(request ?? ""));
+export const asksPreview = (request) => previewAsked.test(String(request ?? ""));
+// A link in the request names a real product, repository or site: the film uses its real assets.
+const urlInRequest = /\bhttps?:\/\/[^\s"'<>)\]]+/giu;
+export const normUrl = (url) => String(url ?? "").trim().replace(/[.,;:!?]+$/u, "").replace(/\/+$/u, "").replace(/\.git$/u, "").toLowerCase();
+export const requestUrls = (request) => [...String(request ?? "").matchAll(urlInRequest)].map((match) => normUrl(match[0]));
 const keyPattern = /^[A-G][#b]? (?:major|minor)$/u;
 
 class Invalid extends Error {
@@ -83,7 +106,10 @@ function stringLeaves(value, at = "", out = []) {
 // The free-text leaves the copied-example rule compares.
 export function freeTextLeaves(t) {
   const leaves = [t?.idea, t?.audience, t?.channel, t?.ambition];
-  for (const beat of Array.isArray(t?.beats) ? t.beats : []) leaves.push(beat?.purpose, beat?.onScreen, beat?.motion, beat?.sound);
+  for (const beat of Array.isArray(t?.beats) ? t.beats : []) leaves.push(beat?.purpose, beat?.onScreen, beat?.motion, beat?.sound, beat?.hero);
+  for (const key of ["expect", "turn", "payoff"]) leaves.push(t?.story?.[key]);
+  leaves.push(t?.protagonist?.look);
+  for (const act of Array.isArray(t?.protagonist?.acts) ? t.protagonist.acts : []) leaves.push(act?.action);
   for (const line of Array.isArray(t?.copy?.lines) ? t.copy.lines : []) leaves.push(line);
   for (const entry of Array.isArray(t?.palette) ? t.palette : []) leaves.push(entry?.role);
   return leaves.filter((leaf) => typeof leaf === "string").map(normalize).filter(Boolean);
@@ -114,6 +140,7 @@ function checkBeats(t) {
     need(beat && typeof beat === "object", "beats", `beat ${i} must be an object`);
     for (const key of ["purpose", "onScreen", "motion", "sound"]) need(text(beat[key]), "beats", `beat ${i} needs ${key}`);
     need(Number.isFinite(beat.t0) && Number.isFinite(beat.t1), "beats", `beat ${i} needs numeric t0 and t1`);
+    if (t.path === "stage") checkShot(t, beat, i);
     need(beat.t1 - beat.t0 >= 1.2 - 1e-9, "beats", `beat ${i} lasts ${(beat.t1 - beat.t0).toFixed(2)} s; every beat is at least 1.2 s`);
     if (i > 0) {
       need(beat.t0 >= t.beats[i - 1].t0, "beats", `beat ${i} starts before beat ${i - 1}`);
@@ -126,13 +153,140 @@ function checkBeats(t) {
   need(t.beats.length >= stages, "beats", `${t.genre} needs at least ${stages} beats (its arc), found ${t.beats.length}`);
 }
 
+// A stage shot sits on the style's layout grid: where the drawing leads, where the copy may sit, the
+// one move the eye follows, and how the shot hands off to the next.
+function checkShot(t, beat, i) {
+  const style = readStyle(t.style);
+  const at = `beats[${i}]`;
+  need(LAYOUT_IDS.includes(beat.layout), "beats", `${at}.layout must be one of ${LAYOUT_IDS.join(", ")}`);
+  need(text(beat.hero) && !placeholder.test(beat.hero), "beats", `${at}.hero names the one move the eye follows in this shot`);
+  const last = i === t.beats.length - 1;
+  if (last) need(beat.transition === "end", "beats", `${at}.transition is end for the last shot`);
+  else need(style.transitions.includes(beat.transition), "beats", `${at}.transition: the ${style.id} style hands off with ${style.transitions.join(", ")}`);
+  if ("lines" in beat) {
+    const count = Array.isArray(t.copy?.lines) ? t.copy.lines.length : 0;
+    need(Array.isArray(beat.lines) && beat.lines.every((k) => Number.isInteger(k) && k >= 0 && k < count), "beats", `${at}.lines lists the indices of the copy lines this shot shows`);
+    need(!(beat.layout === "full" && beat.lines.length), "beats", `${at}: a full shot has no type zone, so it shows no copy`);
+  }
+}
+
+// Composition changes with the story: two adjacent shots never share a layout, and a film of four or
+// more shots uses at least three, so the eye is not parked on one split for the whole film.
+function checkVariety(t) {
+  for (let i = 1; i < t.beats.length; i++) {
+    need(t.beats[i].layout !== t.beats[i - 1].layout, "beats", `shots ${i} and ${i + 1} both use ${t.beats[i].layout}; adjacent shots change layout`);
+  }
+  const used = new Set(t.beats.map((beat) => beat.layout));
+  need(!(t.beats.length >= 4 && used.size < 3), "beats", `${t.beats.length} shots use only ${[...used].join(" and ")}; a film of four or more shots uses at least three layouts`);
+}
+
+// The story: what the viewer expects, the turn they do not, the shot where it lands, and the payoff.
+// A genre arc alone is an information order, not a story. Stage films only; on the type path the words are the film.
+function checkStory(t) {
+  if (t.path !== "stage") return;
+  need("story" in t, "story", "missing: { expect, turn, beat, payoff }: what the viewer expects, what happens instead, the shot where it lands, what the ending gives");
+  const story = t.story;
+  need(story && typeof story === "object" && !Array.isArray(story), "story", "story must be an object { expect, turn, beat, payoff }");
+  for (const key of ["expect", "turn", "payoff"]) {
+    need(text(story[key]), `story.${key}`, `story.${key} must be a non-empty string`);
+    need(sentences(story[key]).length <= 2, `story.${key}`, `story.${key} is at most 2 sentences`);
+  }
+  need(normalize(story.turn) !== normalize(story.expect), "story.turn", "the turn is what the viewer does not expect; it cannot equal story.expect");
+  need(Number.isInteger(story.beat) && story.beat >= 1 && story.beat < t.beats.length, "story.beat", `story.beat is the index of the shot where the turn lands: after the opening, before the end (1-${t.beats.length - 1})`);
+}
+
+// The protagonist: one drawn character or hero object that acts across the film.
+function checkProtagonist(t) {
+  if (t.path !== "stage") return;
+  need("protagonist" in t, "protagonist", "missing: { name, kind, look, acts[] }: the character or hero object that acts across the film");
+  const p = t.protagonist;
+  need(p && typeof p === "object" && !Array.isArray(p), "protagonist", "protagonist must be an object { name, kind, look, acts }");
+  need(text(p.name), "protagonist.name", "protagonist.name must name it");
+  need(protagonistKinds.includes(p.kind), "protagonist.kind", `protagonist.kind must be ${protagonistKinds.join(" or ")}`);
+  need(text(p.look), "protagonist.look", "protagonist.look says what it looks like on screen: shape, material, colour role, scale in the frame");
+  need(Array.isArray(p.acts) && p.acts.length > 0, "protagonist.acts", "list what it does, shot by shot: [{ beat, action }]");
+  const seen = new Set();
+  p.acts.forEach((act, i) => {
+    const at = `protagonist.acts[${i}]`;
+    need(Number.isInteger(act?.beat) && act.beat >= 0 && act.beat < t.beats.length, `${at}.beat`, `${at}.beat must be a beat index`);
+    need(!seen.has(act.beat), `${at}.beat`, `${at}: one act per shot`);
+    seen.add(act.beat);
+    need(text(act.action), `${at}.action`, `${at}.action says what it does in this shot, as a viewer would see it`);
+  });
+  const covered = beatSeconds(t, [...seen]);
+  need(covered >= 0.5 * t.durationSec - 1e-9, "protagonist.acts", `it acts for ${covered.toFixed(1)} s, under half the film; it carries the film, not one shot`);
+  need(seen.has(t.story.beat), "protagonist.acts", `the turn lands at shot ${t.story.beat + 1}, and the protagonist has no act there`);
+}
+
+// A named product, repository or site: its real logo, images, UI and words, never invented ones. The
+// request's link makes it required; `render.mjs assets` fetches what it can reach.
+function checkProduct(t) {
+  const urls = requestUrls(t.request);
+  if (!("product" in t)) {
+    need(urls.length === 0, "product", `missing: the request links ${urls[0]}; fetch its real assets with render.mjs assets --out <dir> --url <link> and list them`);
+    return;
+  }
+  const p = t.product;
+  need(p && typeof p === "object" && !Array.isArray(p), "product", "product must be an object { name, url, assets }");
+  need(text(p.name), "product.name", "product.name must name the product");
+  need(urls.length === 0 || urls.includes(normUrl(p.url)), "product.url", `product.url must be the link the request gives (${urls.join(", ")})`);
+  if ("unreachable" in p) {
+    need(text(p.unreachable), "product.unreachable", "say what could not be reached and why");
+    return;
+  }
+  need(Array.isArray(p.assets) && p.assets.length > 0, "product.assets", "list the real assets the film uses: [{ path, role, source, sha256 }]; when none can be reached set unreachable and ask the user");
+  p.assets.forEach((asset, i) => {
+    const at = `product.assets[${i}]`;
+    need(typeof asset?.path === "string" && asset.path.startsWith("stage/assets/") && !asset.path.split("/").includes(".."), `${at}.path`, `${at}.path must be a file under stage/assets/, relative to the output directory`);
+    need(assetRoles.includes(asset.role), `${at}.role`, `${at}.role must be one of ${assetRoles.join(", ")}`);
+    need(["fetched", "user"].includes(asset.source), `${at}.source`, `${at}.source must be fetched (by render.mjs assets) or user (supplied)`);
+    need(/^[0-9a-f]{64}$/u.test(asset.sha256 ?? ""), `${at}.sha256`, `${at}.sha256 must be the file's SHA-256`);
+  });
+  need(t.subject?.source !== "invented", "subject.source", "the product is real: the subject is the product (source user), its specifics from its own words");
+}
+
+// The register is the request's, like the format: rich unless it asks for a calm, quiet or minimal film.
+// A stage-path field; on the type path the words are the film and there is no register to choose.
+function checkRegister(t) {
+  if (t.path !== "stage") {
+    need(!("register" in t), "register", "register belongs to a stage film; the type path takes none");
+    return;
+  }
+  const register = registerOf(t);
+  need(registers.includes(register), "register", "rich (the default) or minimal");
+  const calm = asksCalm(t.request);
+  need(register !== "minimal" || calm, "register", "minimal only when the request asks for a calm, quiet or minimal film; the default is rich (references/studio.md, Register)");
+  need(register !== "rich" || !calm, "register", "the request asks for a calm or minimal film: register minimal");
+}
+
+// The 3D route: a depth3d subject is drawn with the pinned three.js on the GPU rung (references/depth.md).
+function checkDepth(t) {
+  need(!("depth" in t) || ["2d", "3d"].includes(t.depth), "depth", "depth is 2d (the default) or 3d");
+  need(!("render3d" in t) || ["three", "blender"].includes(t.render3d), "render3d", "render3d is three (the GPU rung, the default) or blender (the offline Cycles rung)");
+  if (t.path !== "stage") {
+    need(t.depth !== "3d", "depth", "3d is a stage-path route");
+    return;
+  }
+  const solid = t.visualDevices.some((device) => device.kind === "depth3d" && device.role === "subject");
+  need(!solid || t.depth === "3d", "depth", "the subject is a depth3d device: set depth to 3d, so the film takes the 3D route");
+  need(t.depth !== "3d" || solid, "depth", "3d needs the subject drawn as a depth3d device (role subject)");
+  need(!("render3d" in t) || t.depth === "3d", "depth", "render3d belongs to a depth 3d film");
+}
+
+function checkStyle(t, house) {
+  need("style" in t, "style", `missing: one of ${STYLE_IDS.join(", ")}`);
+  need(STYLE_IDS.includes(t.style), "style", `must be one of ${STYLE_IDS.join(", ")}`);
+  const pick = pickStyle({ request: t.request, copy: Array.isArray(t.copy?.lines) ? t.copy.lines : [], path: t.path, house, genre: t.genre });
+  need(t.style === pick.id, "style", `${pick.reason}; this film takes the ${pick.id} style`);
+}
+
 function beatSeconds(t, indices) {
   const covered = new Set(indices);
   return [...covered].reduce((sum, i) => sum + (t.beats[i].t1 - t.beats[i].t0), 0);
 }
 
 // Returns { ok: true } or { ok: false, field, detail }.
-export function validateTreatment(t, { examples } = {}) {
+export function validateTreatment(t, { examples, house = null } = {}) {
   try {
     need(t && typeof t === "object" && !Array.isArray(t), "treatment", "treatment.json must hold a JSON object");
     const leaf = stringLeaves(t).find(([, value]) => placeholder.test(value));
@@ -141,6 +295,7 @@ export function validateTreatment(t, { examples } = {}) {
     need(genres.includes(t.genre), "genre", `genre must be one of ${genres.join(", ")}`);
     need(["type", "stage"].includes(t.path), "path", "path must be type or stage");
     need(text(t.pathReason), "pathReason", "pathReason must say why this path fits");
+    checkStyle(t, house);
     need(text(t.idea), "idea", "idea must be one sentence");
     need(sentences(t.idea).length === 1, "idea", "idea must be exactly one sentence");
     need(!restates(t.idea, t.request), "idea", "idea restates the request; say the film's own idea");
@@ -154,18 +309,28 @@ export function validateTreatment(t, { examples } = {}) {
     need(["user", "invented"].includes(t.copy.source), "copy", "copy.source must be user or invented");
     need(Array.isArray(t.copy.lines) && t.copy.lines.length > 0 && t.copy.lines.every(text), "copy", "copy.lines must be non-empty strings");
     checkBeats(t);
+    if (t.path === "stage") checkVariety(t);
     need(t.subject && typeof t.subject === "object", "subject", "subject must be { name, source, specifics[] }");
     need(text(t.subject.name), "subject", "subject.name is required");
     need(["user", "invented"].includes(t.subject.source), "subject", "subject.source must be user or invented");
     need(Array.isArray(t.subject.specifics) && t.subject.specifics.filter(text).length >= 2, "subject", "subject.specifics needs at least 2 concrete specifics");
     if (t.subject.source === "user") need(normalize(t.request).includes(normalize(t.subject.name)), "subject", "subject.source is user, but the request does not name it; mark it invented");
+    checkRegister(t);
+    checkStory(t);
+    checkProtagonist(t);
+    checkProduct(t);
     need(Array.isArray(t.visualDevices), "visualDevices", "visualDevices must be an array");
     t.visualDevices.forEach((device, i) => {
       need(device && deviceKinds.includes(device.kind), "visualDevices", `device ${i}: kind must be one of ${deviceKinds.join(", ")}`);
       need(["subject", "support", "texture"].includes(device.role), "visualDevices", `device ${i}: role must be subject, support or texture`);
       need(!textureKinds.includes(device.kind) || device.role === "texture", "visualDevices", `device ${i}: ${device.kind} is always a texture`);
       need(Array.isArray(device.beats) && device.beats.length > 0 && device.beats.every((b) => Number.isInteger(b) && b >= 0 && b < t.beats.length), "visualDevices", `device ${i}: beats must list beat indices`);
+      if (device.kind === "screen") {
+        const real = (Array.isArray(t.product?.assets) ? t.product.assets : []).find((asset) => asset.path === device.asset);
+        need(real && screenRoles.has(real.role), "visualDevices", `device ${i}: a product screen shows the product's real screenshot, UI or README image: name one listed in product.assets; never draw an invented one`);
+      }
     });
+    checkDepth(t);
     if (t.path === "stage") {
       const subjects = t.visualDevices.filter((device) => device.role === "subject");
       need(subjects.length > 0, "visualDevices", "the stage path needs at least one role: subject device, a drawn depiction of what the film is about");
@@ -177,16 +342,32 @@ export function validateTreatment(t, { examples } = {}) {
     need(t.path !== "type" || t.copy.source === "user" || typeLedCue(t.request), "path", "the type path needs the user's own words or a type-led cue in the request");
     need(t.typePlan && typeof t.typePlan === "object", "typePlan", "typePlan must be { faces[], hierarchy, maxWordsOnScreen }");
     need(Array.isArray(t.typePlan.faces) && t.typePlan.faces.length > 0 && t.typePlan.faces.every((face) => productFaces.includes(face)), "typePlan", `typePlan.faces must come from ${productFaces.join(", ")}`);
+    if (t.path === "stage") {
+      const families = styleFamilies(readStyle(t.style));
+      const off = t.typePlan.faces.find((face) => !families.has(face));
+      need(off === undefined, "typePlan", `${off} is not a face of the ${t.style} style (${[...families].join(", ")})`);
+    }
     need(text(t.typePlan.hierarchy), "typePlan", "typePlan.hierarchy is required");
     need(Number.isInteger(t.typePlan.maxWordsOnScreen) && t.typePlan.maxWordsOnScreen >= 1, "typePlan", "typePlan.maxWordsOnScreen must be a positive integer");
-    need(Array.isArray(t.palette) && t.palette.length >= 3 && t.palette.length <= 6, "palette", "palette needs 3-6 colours");
+    need(Array.isArray(t.palette) && t.palette.length >= 3 && t.palette.length <= (t.path === "stage" && registerOf(t) === "rich" ? 14 : 6), "palette", `palette needs 3-${t.path === "stage" && registerOf(t) === "rich" ? 14 : 6} colours`);
     t.palette.forEach((entry, i) => need(entry && /^#[0-9a-f]{6}$/iu.test(entry.hex ?? "") && text(entry.role), "palette", `palette ${i} must be { hex: "#rrggbb", role }`));
+    if (t.path === "stage") {
+      const rich = registerOf(t) === "rich";
+      const allowed = new Set(styleColors(readStyle(t.style), { rich }));
+      const off = t.palette.find((entry) => !allowed.has(entry.hex.toLowerCase()));
+      need(off === undefined, "palette", `${off?.hex} is not a colour of the ${t.style} style${rich ? " or one of its role accents" : " (a minimal film keeps to the core palette)"}; the stage palette comes from the style`);
+    }
     need(t.sound && soundModes.includes(t.sound.mode), "sound", `sound.mode must be one of ${soundModes.join(", ")}`);
     need(text(t.sound.plan), "sound", "sound.plan is required");
+    need(!(t.sound.mode === "generated" && t.path === "stage" && registerOf(t) === "rich"), "sound", "a rich film scores its own music (sound.mode score); the style's preset beds are for minimal films (references/sound.md)");
+    need(!("genre" in t.sound) || scoreGenres.includes(t.sound.genre), "sound", `sound.genre must be one of ${scoreGenres.join(", ")}`);
     if (t.sound.mode === "generated") {
       need(soundPalettes.includes(t.sound.palette), "sound", `sound.palette must be one of ${soundPalettes.join(", ")}`);
       need(Number.isFinite(t.sound.tempo) && t.sound.tempo >= 60 && t.sound.tempo <= 180, "sound", "sound.tempo must be 60-180 BPM");
       need(keyPattern.test(t.sound.key ?? ""), "sound", "sound.key must look like \"D minor\" or \"F# major\"");
+      const beds = styleBeds(readStyle(t.style));
+      const same = (bed) => bed.palette === t.sound.palette && bed.key.toLowerCase() === t.sound.key.toLowerCase() && bed.tempo === t.sound.tempo;
+      need(beds.some(same), "sound", `pick one of the ${t.style} style's beds: ${beds.map((bed) => `${bed.palette} ${bed.key} ${bed.tempo} BPM`).join("; ")}`);
     }
     if (t.sound.mode === "supplied" || t.sound.mode === "authored") need(text(t.sound.file), "sound", `sound.file is required for ${t.sound.mode} sound`);
     if (t.sound.mode === "none") need(silenceAsked.test(t.request) || t.sound.mutedByDesign === true, "sound", "silence needs a user request for it, or sound.mutedByDesign for a channel that plays muted");
@@ -206,6 +387,9 @@ export function validateTreatment(t, { examples } = {}) {
     need(text(t.ambition) && sentences(t.ambition).length <= 2, "ambition", "ambition must be 1-2 sentences in craft terms");
     if (t.seed !== undefined) need(Number.isSafeInteger(t.seed), "seed", "seed must be an integer");
     if (t.fps !== undefined) need(t.fps === 60 || t.fps === 30, "fps", "fps must be 60 or 30");
+    need(t.fps !== 30 || asks30fps(t.request), "fps", "fps is 60; 30 only when the request asks for 30 fps");
+    if (t.preview !== undefined) need(typeof t.preview === "boolean", "preview", "preview must be true or false");
+    need(t.preview !== true || asksPreview(t.request), "preview", "preview is true only when the request asks for a preview or storyboard first");
     need(!copiesExample(t, examples), "copiedExample", "half or more of the free-text fields equal a shipped example; write this film's own treatment");
     return { ok: true };
   } catch (error) {
@@ -230,7 +414,7 @@ export function loadTreatment(out) {
   let parsed;
   try { parsed = JSON.parse(readFileSync(file, "utf8")); } catch (error) { throw fail("treatment", `treatment.json is not JSON (${error.message})`); }
   if (parsed?.mode === "cover") throw fail("mode", "this is a cover treatment; render it with `render.mjs cover --out <dir>` (references/cover.md)");
-  const result = validateTreatment(parsed);
+  const result = validateTreatment(parsed, { house: readHouse(out) });
   if (!result.ok) throw fail(result.field, result.detail);
   return { treatment: parsed, file };
 }

package/skills/lit-typographic-motion/engine/vendor/three/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright © 2010-2024 three.js authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.