@litfamily/lithermes 1.0.28 → 1.0.30

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/styles.mjs

@@ -0,0 +1,240 @@
+// House styles as data: palette, faces, type scale, layout zones, motion tokens, transitions
+// and sound for one look, so every film in a style shares them. A style lives in
+// `styles/<id>.json`; the treatment names one, the validator checks it against the rules
+// (named in the request, the project's house style, or the fixed keyword auto-pick), the
+// renderer serves it to the stage page as /lit/style.css and /lit/style.js, and the text QA
+// judges copy against it. Zones are one grid per layout, named per shot and mapped per
+// format, so a story re-lays itself per format instead of cropping. Four styles ship;
+// `paper` is stage-only (the type engine has no preset for it, so the type path skips it).
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { contrastRatio, relativeLuminance } from './util.mjs';
+
+export const STYLE_SCHEMA = 'litfamily.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 frame fractions. `type` bounds where copy may sit; `subject` bounds where the
+// drawing leads (a `title` or `full` subject fills the frame as backdrop). Every type zone sits
+// 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 chooses the style that reads best: 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. `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 = (value) => typeof value === 'string' && value.trim().length > 0;
+const escape = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+
+export const matchesKeyword = (text, keyword, korean) => {
+  const pattern = korean
+    ? new RegExp(`(?<![\\p{L}\\p{N}])${escape(keyword)}`, 'u')
+    : new RegExp(`(?<![\\p{L}\\p{N}])${escape(keyword)}(?![\\p{L}\\p{N}])`, 'iu');
+  return pattern.test(String(text ?? ''));
+};
+
+/** 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 key of ['name', 'summary']) if (!isText(style[key])) fail(key, 'must be a non-empty string');
+  const palette = style.palette ?? {};
+  for (const role of ['ground', 'surface', 'ink', 'muted', 'signal', 'line']) {
+    if (!HEX.test(palette[role] ?? '')) fail(`palette.${role}`, 'must be #rrggbb');
+  }
+  if (!Array.isArray(style.textRoles) || style.textRoles.some((role) => !HEX.test(palette[role] ?? ''))) {
+    fail('textRoles', 'every text role names a palette colour');
+  }
+  const ground = relativeLuminance(palette.ground);
+  if (contrastRatio(relativeLuminance(palette.ink), ground) < 7) fail('palette.ink', 'ink on ground needs 7:1');
+  if (contrastRatio(relativeLuminance(palette.muted), ground) < 4.5) fail('palette.muted', 'muted on ground needs 4.5:1');
+  for (const role of ['signal', 'accent']) {
+    if (palette[role] && contrastRatio(relativeLuminance(palette[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((accent, index) => {
+    if (!isText(accent?.role)) fail(`accents[${index}].role`, 'says what the colour marks');
+    if (!HEX.test(accent?.color ?? '')) fail(`accents[${index}].color`, 'must be #rrggbb');
+    if (contrastRatio(relativeLuminance(accent.color), ground) < 3) fail(`accents[${index}].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 steps = style.scale?.[format];
+    if (!steps || TYPE_ROLES.some((role) => !(steps[role] > 0))) fail(`scale.${format}`, 'needs a size per type role');
+    if (!(steps.display > steps.headline && steps.headline > steps.body && steps.body > steps.label)) {
+      fail(`scale.${format}`, 'steps must descend display > headline > body > label');
+    }
+  }
+  const motion = style.motion ?? {};
+  for (const key of ['enter', 'move', 'exit']) {
+    if (!Array.isArray(motion.ease?.[key]) || motion.ease[key].length !== 4) fail(`motion.ease.${key}`, 'is a cubic-bezier [x1, y1, x2, y2]');
+  }
+  for (const key of ['micro', 'move', 'hero', 'exit']) if (!(motion.dur?.[key] > 0)) fail(`motion.dur.${key}`, 'seconds > 0');
+  if (!(motion.dur.exit <= motion.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((name) => !TRANSITIONS.includes(name))) {
+    fail('transitions', `a subset of ${TRANSITIONS.join(', ')}`);
+  }
+  if (!isText(style.score?.genre)) fail('score.genre', 'names the genre a film\u2019s score takes by default');
+  if (!style.sound || !isText(style.sound.timbre)) fail('sound', 'needs the generated bed\u2019s palette');
+  if (!Array.isArray(style.beds) || style.beds.length < 2 || style.beds.some((bed) => !isText(bed?.timbre) || !isText(bed?.key) || !(bed?.tempo > 0))) {
+    fail('beds', 'lists at least two beds a film may pick, each { timbre, key, mode, tempo }');
+  }
+  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)) {
+    const file = fileURLToPath(new URL(`../styles/${id}.json`, import.meta.url));
+    cache.set(id, Object.freeze(validateStyle(JSON.parse(readFileSync(file, '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((role) => style.faces[role].family), style.hangul?.family ?? 'Pretendard', 'Pretendard']);
+/** The hex colours copy may use. */
+export const styleTextColors = (style) => style.textRoles.map((role) => style.palette[role].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((accent) => accent.color) : [])].map((color) => color.toLowerCase());
+
+/**
+ * Which style a film takes. A style named in the request wins; then the project's house style;
+ * then the keyword auto-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((name) => matchesKeyword(text, name, /[가-힣]/u.test(name)));
+    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 keyword of row.korean) if (matchesKeyword(haystack, keyword, true)) return { id: row.style, source: 'auto', reason: `the request mentions "${keyword}"` };
+    for (const keyword of row.latin) if (matchesKeyword(haystack, keyword, false)) return { id: row.style, source: 'auto', reason: `the request mentions "${keyword}"` };
+  }
+  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 [frameWidth, frameHeight] = FRAME[format];
+  const px = (rect) => (rect ? { x: Math.round(rect[0] * frameWidth), y: Math.round(rect[1] * frameHeight), w: Math.round(rect[2] * frameWidth), h: Math.round(rect[3] * frameHeight) } : null);
+  return Object.fromEntries(Object.entries(LAYOUTS[format]).map(([id, zones]) => [id, { type: px(zones.type), subject: px(zones.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;
+}
+
+/** /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((beat, index) => ({ index, t0: beat.t0, t1: beat.t1, layout: beat.layout ?? null, transition: beat.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`;
+}
+
+const familyStack = (style, role) => {
+  const face = style.faces[role];
+  const hangul = style.hangul?.family ?? 'Pretendard';
+  return [face.family, hangul, 'Pretendard'].filter((family, index, all) => all.indexOf(family) === index).map((family) => `"${family}"`).join(', ');
+};
+
+/** /lit/style.css for one style and format: custom properties, type-role classes, colour classes. */
+export function styleCss(style, format) {
+  const steps = style.scale[format];
+  const vars = [
+    ...Object.entries(style.palette).map(([key, value]) => `  --lit-${key}: ${value};`),
+    ...TYPE_ROLES.map((role) => `  --lit-size-${role}: ${steps[role]}px;`),
+  ];
+  const roles = TYPE_ROLES.map((role) => {
+    const face = style.faces[role];
+    return `.lit-${role} { font-family: ${familyStack(style, role)}; font-size: ${steps[role]}px; font-weight: ${face.weight}; line-height: ${style.leading?.[role] ?? 1.3}; letter-spacing: 0; margin: 0; }`;
+  });
+  const colours = style.textRoles.map((role) => `.lit-${role === 'ground' ? 'knockout' : role} { color: var(--lit-${role}); }`);
+  return [
+    `/* lit-typographic-motion style: ${style.id} (${format}) */`,
+    `:root {\n${vars.join('\n')}\n}`,
+    // Korean breaks 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');
+}

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/treatment.mjs

@@ -5,19 +5,36 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { LAYOUT_IDS, pickStyle, readStyle, styleColors, styleFamilies } from './styles.mjs';
+import { readHouse } from './house.mjs';
+import { EVENT_SOUNDS } from './sound.mjs';
+import { SCORE_GENRES } from './score.mjs';
 
 export const GENRES = Object.freeze(['announcement', 'brand-mood', 'event', 'explainer', 'motion-graphics', 'type-led', 'other']);
 export const ARC_STAGES = Object.freeze({ announcement: 5, 'brand-mood': 4, event: 4, explainer: 4, 'motion-graphics': 5, other: 3 });
 export const DEVICE_KINDS = Object.freeze(['illustration', 'diagram', 'chart', 'icon', 'shape', 'path', 'mask', 'depth3d', 'particles', 'grid', 'gradient', 'photo-texture']);
 export const TEXTURE_KINDS = Object.freeze(['grid', 'gradient', 'particles', 'photo-texture']);
 export const FORMATS = Object.freeze({ '16:9': [1920, 1080], '9:16': [1080, 1920] });
-export const SOUND_MODES = Object.freeze(['generated', 'supplied', 'authored', 'none']);
+export const SOUND_MODES = Object.freeze(['score', 'generated', 'supplied', 'authored', 'none']);
+export const EVENT_OFF_CUT_SEC = 0.1;
 // The families fonts.css serves; the type engine draws from the same set.
 export const FACES = Object.freeze(['Pretendard', 'Archivo', 'Galmuri9', 'VT323', 'Silkscreen', 'MesloLGS NF']);
 export const SOUND_PALETTES = Object.freeze(['soft-mallet', 'warm-keys', 'glass-pulse', 'low-strings']);
+export const PROTAGONIST_KINDS = Object.freeze(['character', 'object']);
+// A rich stage film plans its density before any page exists: the depth layers
+// of its world, the labelled parts the viewer reads and the camera moves.
+export const RICH_WORLD = Object.freeze({ layers: 3, labels: 6, labelWords: 4, cameraShare: 0.5 });
+const LOCKED_CAMERA = /^\s*(?:none|locked|static|still|hold|fixed|no move)\s*\.?\s*$/iu;
+// A bare deferred-work marker with no value: the global placeholder sweep only
+// sees <angle> markers, so story, protagonist and world fields check this too.
+const BARE_PLACEHOLDER = /^\s*(?:todo|tbd|tk|xxx|\.\.\.|…)\s*$/iu;
 const FLOOR_GENRES = new Set(['announcement', 'event', 'explainer', 'motion-graphics']);
 const MIN_BEAT_SEC = 1.2;
 const MAX_GAP_SEC = 0.25;
+const REGISTERS = Object.freeze(['rich', 'minimal']);
+// The request asks for a calm, quiet or minimal film: the one case the minimal register is for.
+const MINIMAL_ASKED = /미니멀|잔잔|차분|조용|심플|절제|단순하게|고요|\bminimal(?:ist|ism)?\b|\bcalm\b|\bquiet\b|\bsimple\b|\bunderstated\b|\brestrained\b|\bsparse\b|\bserene\b/iu;
+const PREVIEW_ASKED = /미리\s?보기|스토리보드|콘티|\bpreview\b|\bstoryboard\b/iu;
 
 const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -57,7 +74,10 @@ export function sharesSubstring(text, request, limit = restatementLimit(request)
 // Free-text leaves the copiedExample 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((v) => typeof v === 'string').map(normalizeText).filter(Boolean);
@@ -104,7 +124,7 @@ const need = (cond, field, message) => { if (!cond) throw new Invalid(field, mes
 function check(t, { outDir, examples }) {
   need(t && typeof t === 'object' && !Array.isArray(t), 'treatment', 'treatment.json must be a JSON object');
   need(t.mode !== 'cover', 'mode', 'this is a cover treatment; render it with `cover --out DIR` (references/cover.md)');
-  for (const field of ['request', 'genre', 'path', 'pathReason', 'idea', 'audience', 'channel', 'format', 'durationSec', 'beats', 'subject', 'visualDevices', 'typePlan', 'palette', 'sound', 'copy', 'ambition']) {
+  for (const field of ['request', 'genre', 'path', 'pathReason', 'style', 'idea', 'audience', 'channel', 'format', 'durationSec', 'beats', 'subject', 'visualDevices', 'typePlan', 'palette', 'sound', 'copy', 'ambition']) {
     need(t[field] !== undefined && t[field] !== null && t[field] !== '', field, `${field} is required`);
   }
   const mine = freeTextLeaves(t);
@@ -120,6 +140,17 @@ function check(t, { outDir, 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');
+  const house = outDir ? readHouse(outDir) : null;
+  const pick = pickStyle({ request: t.request, copy: Array.isArray(t.copy?.lines) ? t.copy.lines : [], path: t.path, house, genre: t.genre });
+  need('style' in t, 'style', 'missing: one of swiss-signal, tidal, terminalcore, paper (references/studio.md)');
+  need(['swiss-signal', 'tidal', 'terminalcore', 'paper'].includes(t.style), 'style', 'must be one of swiss-signal, tidal, terminalcore, paper');
+  if (t.path === 'type' && t.style === 'paper') need(false, 'style', 'paper is stage-only; the type path takes swiss-signal, tidal or terminalcore');
+  need(t.style === pick.id, 'style', `${pick.reason}; this film takes the ${pick.id} style`);
+  const register = t.register ?? 'rich';
+  need(REGISTERS.includes(register), 'register', 'rich (the default) or minimal');
+  need(!(register === 'minimal' && !MINIMAL_ASKED.test(t.request)), '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' && MINIMAL_ASKED.test(t.request)), 'register', 'the request asks for a calm or minimal film: register minimal');
+  if (t.preview === true) need(PREVIEW_ASKED.test(t.request), 'preview', 'true only when the request asks for a preview or storyboard first');
   need(Object.hasOwn(FORMATS, t.format), 'format', 'format must be 16:9 or 9:16');
   need(text(t.formatReason), 'formatReason', 'formatReason must tie the format to the channel');
   need(text(t.audience), 'audience', 'audience must say who watches');
@@ -157,11 +188,58 @@ function check(t, { outDir, examples }) {
     const at = `beats[${i}]`;
     need(beat && typeof beat.t0 === 'number' && typeof beat.t1 === 'number', at, `${at} needs numeric t0 and t1`);
     for (const key of ['purpose', 'onScreen', 'motion', 'sound']) need(text(beat[key]), `${at}.${key}`, `${at}.${key} is required`);
+    if (t.path === 'stage') {
+      const style = readStyle(t.style);
+      need(LAYOUT_IDS.includes(beat.layout), `${at}.layout`, `${at}.layout must be one of ${LAYOUT_IDS.join(', ')}`);
+      need(text(beat.hero) && !PLACEHOLDER.test(String(beat.hero)), `${at}.hero`, `${at}.hero names the one move the eye follows in this shot`);
+      if (i === beats.length - 1) need(beat.transition === 'end', `${at}.transition`, `${at}.transition: the last shot's transition is end`);
+      else need(style.transitions.includes(beat.transition), `${at}.transition`, `${at}.transition: the ${t.style} 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((key) => Number.isInteger(key) && key >= 0 && key < count), `${at}.lines`, `${at}.lines lists the indices of the copy lines this shot shows`);
+        need(!(beat.layout === 'full' && beat.lines.length), `${at}.lines`, `${at}.lines: a full shot has no type zone, so it shows no copy`);
+      }
+    }
     need(beat.t1 - beat.t0 >= MIN_BEAT_SEC - 1e-9, at, `${at} lasts ${(beat.t1 - beat.t0).toFixed(2)} s; every beat is at least ${MIN_BEAT_SEC} s`);
     need(beat.t0 - cursor <= MAX_GAP_SEC + 1e-9, at, `${at} leaves a ${(beat.t0 - cursor).toFixed(2)} s gap; beats cover the film with no gap over ${MAX_GAP_SEC} s`);
     cursor = Math.max(cursor, beat.t1);
   });
   need(d - cursor <= MAX_GAP_SEC + 1e-9 && cursor <= d + MAX_GAP_SEC, 'beats', `beats end at ${cursor} s but the film runs ${d} s`);
+  if (t.path === 'stage') {
+    for (let i = 1; i < beats.length; i++) {
+      need(beats[i].layout !== beats[i - 1].layout, `beats[${i}].layout`, `shots ${i} and ${i + 1} both use ${beats[i].layout}; adjacent shots change layout (references/studio.md)`);
+    }
+    const used = new Set(beats.map((beat) => beat.layout));
+    need(beats.length < 4 || used.size >= 3, 'beats', `${beats.length} shots use only ${[...used].join(' and ')}; a film of four or more shots uses at least three layouts`);
+  }
+
+  const story = t.story;
+  need(story && typeof story === 'object', 'story', 'story is required: { expect, turn, beat, payoff }: what the viewer expects, what happens instead, the shot where it lands, what the ending gives');
+  for (const key of ['expect', 'turn', 'payoff']) {
+    need(text(story[key]) && !BARE_PLACEHOLDER.test(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(normalizeText(story.turn) !== normalizeText(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 < beats.length, 'story.beat', `story.beat is the index of the shot where the turn lands: after the opening, before the end (1-${beats.length - 1})`);
+
+  if (t.path === 'stage') {
+    const protagonist = t.protagonist;
+    need(protagonist && typeof protagonist === 'object', 'protagonist', 'protagonist is required: { name, kind, look, acts[] }: the character or hero object that acts across the film');
+    need(text(protagonist.name) && !BARE_PLACEHOLDER.test(protagonist.name), 'protagonist.name', 'protagonist.name must name it');
+    need(PROTAGONIST_KINDS.includes(protagonist.kind), 'protagonist.kind', `protagonist.kind must be ${PROTAGONIST_KINDS.join(' or ')}`);
+    need(text(protagonist.look) && !BARE_PLACEHOLDER.test(protagonist.look), 'protagonist.look', 'protagonist.look says what it looks like on screen: shape, material, colour role, scale in the frame');
+    need(Array.isArray(protagonist.acts) && protagonist.acts.length > 0, 'protagonist.acts', 'protagonist.acts lists what it does, shot by shot: [{ beat, action }]');
+    const seen = new Set();
+    protagonist.acts.forEach((act, i) => {
+      need(Number.isInteger(act?.beat) && act.beat >= 0 && act.beat < beats.length, `protagonist.acts[${i}].beat`, 'protagonist.acts[].beat must be a beat index');
+      need(!seen.has(act.beat), `protagonist.acts[${i}].beat`, 'one act per shot');
+      seen.add(act.beat);
+      need(text(act.action) && !BARE_PLACEHOLDER.test(act.action), `protagonist.acts[${i}].action`, 'say what it does in this shot, as a viewer would see it');
+    });
+    const covered = [...seen].reduce((sum, b) => sum + (beats[b].t1 - beats[b].t0), 0);
+    need(covered >= 0.5 * d - 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(story.beat), 'protagonist.acts', `the turn lands at shot ${story.beat + 1}, and the protagonist has no act there`);
+  }
 
   const subject = t.subject;
   need(subject && text(subject.name), 'subject.name', 'subject.name is required');
@@ -188,31 +266,95 @@ function check(t, { outDir, examples }) {
     need(kinds.size >= 2, 'visualDevices', `the stage path needs at least 2 distinct non-texture device kinds; this has ${kinds.size}`);
   }
 
+  if ('depth' in t) need(['2d', '3d'].includes(t.depth), 'depth', 'depth is 2d (the default) or 3d');
+  const solid = Array.isArray(devices) && devices.some((device) => device?.kind === 'depth3d' && device?.role === 'subject');
+  if (t.path === 'stage') {
+    need(!(solid && t.depth !== '3d'), 'depth', 'the subject is a depth3d device: set depth to 3d, so the film takes the 3D route (references/depth.md)');
+    need(!(t.depth === '3d' && !solid), 'depth', 'depth 3d needs the subject drawn as a depth3d device (role subject)');
+    if ('render3d' in t) need(['three', 'blender'].includes(t.render3d), 'render3d', 'render3d is three (the GPU rung, the default) or blender (the offline Cycles rung)');
+    need(t.render3d !== 'blender' || t.depth === '3d', 'render3d', 'the Blender rung renders a 3D world: set depth to 3d with a depth3d subject');
+  } else {
+    need(t.depth !== '3d', 'depth', 'depth 3d is a stage-path route');
+  }
+
+  if (t.path === 'stage' && register === 'rich') {
+    const world = t.world;
+    need(world && typeof world === 'object', 'world', 'world is required: { layers, labels, camera }: the layered world, its labelled parts and its camera moves');
+    need(Array.isArray(world.layers) && world.layers.filter(text).length >= RICH_WORLD.layers, 'world.layers', `world.layers needs at least ${RICH_WORLD.layers} depth layers, back to front, each saying what lives there`);
+    need(Array.isArray(world.labels) && world.labels.length >= RICH_WORLD.labels, 'world.labels', `world.labels needs at least ${RICH_WORLD.labels} labelled parts the viewer reads on screen`);
+    world.labels.forEach((label, i) => {
+      need(text(label) && !BARE_PLACEHOLDER.test(label), `world.labels[${i}]`, 'the label as it appears on screen');
+      need(String(label).trim().split(/\s+/u).length <= RICH_WORLD.labelWords, `world.labels[${i}]`, `a label is at most ${RICH_WORLD.labelWords} words; longer text is copy`);
+    });
+    need(Array.isArray(world.camera), 'world.camera', 'world.camera lists the camera moves: [{ beat, move }]');
+    const moving = new Set();
+    world.camera.forEach((entry, i) => {
+      need(Number.isInteger(entry?.beat) && entry.beat >= 0 && entry.beat < beats.length, `world.camera[${i}].beat`, 'world.camera[].beat must be a beat index');
+      need(text(entry.move) && !BARE_PLACEHOLDER.test(entry.move) && !LOCKED_CAMERA.test(entry.move), `world.camera[${i}].move`, 'name the move (push-in, truck, crane, orbit, rack focus); a locked shot is not listed');
+      moving.add(entry.beat);
+    });
+    need(moving.size >= RICH_WORLD.cameraShare * beats.length - 1e-9, 'world.camera', `the camera moves in ${moving.size} of ${beats.length} shots; a rich film moves it in at least half`);
+  }
+
   const plan = t.typePlan;
   need(plan && Array.isArray(plan.faces) && plan.faces.length > 0, 'typePlan.faces', 'typePlan.faces must list faces');
   plan.faces.forEach((face, i) => need(FACES.some((f) => f.toLowerCase() === String(face).toLowerCase()), `typePlan.faces[${i}]`, `${face} is not a verified face; use ${FACES.join(', ')}`));
+  if (t.path === 'stage') {
+    const families = styleFamilies(readStyle(t.style));
+    const off = plan.faces.find((face) => ![...families].some((family) => family.toLowerCase() === String(face).toLowerCase()));
+    need(!off, 'typePlan.faces', `${off} is not a face of the ${t.style} style (${[...families].join(', ')})`);
+  }
   need(text(plan.hierarchy), 'typePlan.hierarchy', 'typePlan.hierarchy is required');
   need(Number.isInteger(plan.maxWordsOnScreen) && plan.maxWordsOnScreen > 0, 'typePlan.maxWordsOnScreen', 'typePlan.maxWordsOnScreen must be a positive integer');
 
-  need(Array.isArray(t.palette) && t.palette.length >= 3 && t.palette.length <= 6, 'palette', 'palette must hold 3 to 6 colours');
-  t.palette.forEach((entry, i) => {
-    need(/^#[0-9a-f]{6}$/iu.test(entry?.color || ''), `palette[${i}].color`, `palette[${i}].color must be #rrggbb`);
-    need(text(entry.role), `palette[${i}].role`, `palette[${i}].role is required`);
-  });
+  if (t.path === 'stage') {
+    const rich = register === 'rich';
+    const allowed = new Set(styleColors(readStyle(t.style), { rich }));
+    need(Array.isArray(t.palette) && t.palette.length <= (rich ? 14 : 9), 'palette', 'palette lists the style\u2019s colours with their roles');
+    t.palette.forEach((entry, i) => {
+      need(allowed.has(String(entry?.color ?? '').toLowerCase()), `palette[${i}].color`, `${entry?.color} 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(text(entry.role), `palette[${i}].role`, `palette[${i}].role is required`);
+    });
+  } else {
+    need(Array.isArray(t.palette) && t.palette.length >= 3 && t.palette.length <= 6, 'palette', 'palette must hold 3 to 6 colours');
+    t.palette.forEach((entry, i) => {
+      need(/^#[0-9a-f]{6}$/iu.test(entry?.color || ''), `palette[${i}].color`, `palette[${i}].color must be #rrggbb`);
+      need(text(entry.role), `palette[${i}].role`, `palette[${i}].role is required`);
+    });
+  }
 
   const sound = t.sound;
   need(sound && SOUND_MODES.includes(sound.mode), 'sound.mode', `sound.mode must be one of ${SOUND_MODES.join(', ')}`);
   if (sound.mode === 'none') {
     need(SILENT_REQUEST.test(t.request) || /무음|소리\s*없이|(?<![A-Za-z])muted?(?![A-Za-z])/iu.test(t.channel), 'sound.mode',
-      'sound none is allowed only when the user asked for silence or the channel plays muted by design');
+      'sound none is allowed only when the user asked for silence or the channel plays muted by design; the default is a score');
   } else {
     need(text(sound.plan), 'sound.plan', 'sound.plan is required');
+    if (sound.mode === 'score' && register === 'minimal') need(false, 'sound.mode', 'a minimal film keeps the generated bed; the score is for rich films');
+    if (sound.mode === 'generated' && register === 'rich') need(false, 'sound.mode', 'a rich film scores its own music (mode score); the generated bed is for minimal films');
+    if ('genre' in sound) need(SCORE_GENRES.includes(sound.genre), 'sound.genre', `sound.genre must be one of ${SCORE_GENRES.join(', ')}`);
     if (sound.mode === 'generated') need(SOUND_PALETTES.includes(sound.palette), 'sound.palette', `sound.palette must be one of ${SOUND_PALETTES.join(', ')}`);
-    else {
+    else if (sound.mode !== 'score') {
       need(text(sound.file), 'sound.file', `a ${sound.mode} track names its WAV in sound.file`);
       if (sound.mode === 'authored') need(/^stage\//u.test(sound.file), 'sound.file', 'an authored track lives in the stage dir (stage/*.wav)');
       if (outDir) need(existsSync(resolve(outDir, sound.file)), 'sound.file', `${sound.file} does not exist in the output dir`);
     }
+    if ((sound.mode === 'generated' || sound.mode === 'score') && t.path === 'stage') {
+      need('events' in sound, 'sound.events', 'list the on-screen events that make a sound: [{ t, on, kind }], at least 2, half of them away from the cuts');
+    }
+    if ('events' in sound) {
+      const events = sound.events;
+      need(Array.isArray(events) && events.length >= 2, 'sound.events', 'at least 2 on-screen events that make a sound: [{ t, on, kind }]');
+      const cuts = beats.slice(1).map((beat) => beat.t0);
+      let offCut = 0;
+      events.forEach((entry, i) => {
+        need(typeof entry?.t === 'number' && entry.t > 0 && entry.t < d, `sound.events[${i}].t`, `the second the event happens on screen, inside the film (0-${d})`);
+        need(text(entry.on), `sound.events[${i}].on`, 'what happens on screen at that moment, as a viewer would see it');
+        need(EVENT_SOUNDS.includes(entry.kind), `sound.events[${i}].kind`, `must be one of ${EVENT_SOUNDS.join(', ')}`);
+        if (cuts.every((cut) => Math.abs(cut - entry.t) >= EVENT_OFF_CUT_SEC - 1e-9)) offCut += 1;
+      });
+      need(offCut * 2 >= events.length, 'sound.events', `${events.length - offCut} of ${events.length} events sit on a cut; at least half sync to something moving inside a shot`);
+    }
   }
 
   const inventedSubject = subject.source === 'invented';

package/assets/lithermes-plugin/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.

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/vendor/three/addons/environments/RoomEnvironment.js

@@ -0,0 +1,144 @@
+/**
+ * https://github.com/google/model-viewer/blob/master/packages/model-viewer/src/three-components/EnvironmentScene.ts
+ */
+
+import {
+ 	BackSide,
+ 	BoxGeometry,
+ 	Mesh,
+	MeshBasicMaterial,
+ 	MeshStandardMaterial,
+ 	PointLight,
+ 	Scene,
+} from 'three';
+
+class RoomEnvironment extends Scene {
+
+	constructor() {
+
+		super();
+
+		const geometry = new BoxGeometry();
+		geometry.deleteAttribute( 'uv' );
+
+		const roomMaterial = new MeshStandardMaterial( { side: BackSide } );
+		const boxMaterial = new MeshStandardMaterial();
+
+		const mainLight = new PointLight( 0xffffff, 900, 28, 2 );
+		mainLight.position.set( 0.418, 16.199, 0.300 );
+		this.add( mainLight );
+
+		const room = new Mesh( geometry, roomMaterial );
+		room.position.set( - 0.757, 13.219, 0.717 );
+		room.scale.set( 31.713, 28.305, 28.591 );
+		this.add( room );
+
+		const box1 = new Mesh( geometry, boxMaterial );
+		box1.position.set( - 10.906, 2.009, 1.846 );
+		box1.rotation.set( 0, - 0.195, 0 );
+		box1.scale.set( 2.328, 7.905, 4.651 );
+		this.add( box1 );
+
+		const box2 = new Mesh( geometry, boxMaterial );
+		box2.position.set( - 5.607, - 0.754, - 0.758 );
+		box2.rotation.set( 0, 0.994, 0 );
+		box2.scale.set( 1.970, 1.534, 3.955 );
+		this.add( box2 );
+
+		const box3 = new Mesh( geometry, boxMaterial );
+		box3.position.set( 6.167, 0.857, 7.803 );
+		box3.rotation.set( 0, 0.561, 0 );
+		box3.scale.set( 3.927, 6.285, 3.687 );
+		this.add( box3 );
+
+		const box4 = new Mesh( geometry, boxMaterial );
+		box4.position.set( - 2.017, 0.018, 6.124 );
+		box4.rotation.set( 0, 0.333, 0 );
+		box4.scale.set( 2.002, 4.566, 2.064 );
+		this.add( box4 );
+
+		const box5 = new Mesh( geometry, boxMaterial );
+		box5.position.set( 2.291, - 0.756, - 2.621 );
+		box5.rotation.set( 0, - 0.286, 0 );
+		box5.scale.set( 1.546, 1.552, 1.496 );
+		this.add( box5 );
+
+		const box6 = new Mesh( geometry, boxMaterial );
+		box6.position.set( - 2.193, - 0.369, - 5.547 );
+		box6.rotation.set( 0, 0.516, 0 );
+		box6.scale.set( 3.875, 3.487, 2.986 );
+		this.add( box6 );
+
+
+		// -x right
+		const light1 = new Mesh( geometry, createAreaLightMaterial( 50 ) );
+		light1.position.set( - 16.116, 14.37, 8.208 );
+		light1.scale.set( 0.1, 2.428, 2.739 );
+		this.add( light1 );
+
+		// -x left
+		const light2 = new Mesh( geometry, createAreaLightMaterial( 50 ) );
+		light2.position.set( - 16.109, 18.021, - 8.207 );
+		light2.scale.set( 0.1, 2.425, 2.751 );
+		this.add( light2 );
+
+		// +x
+		const light3 = new Mesh( geometry, createAreaLightMaterial( 17 ) );
+		light3.position.set( 14.904, 12.198, - 1.832 );
+		light3.scale.set( 0.15, 4.265, 6.331 );
+		this.add( light3 );
+
+		// +z
+		const light4 = new Mesh( geometry, createAreaLightMaterial( 43 ) );
+		light4.position.set( - 0.462, 8.89, 14.520 );
+		light4.scale.set( 4.38, 5.441, 0.088 );
+		this.add( light4 );
+
+		// -z
+		const light5 = new Mesh( geometry, createAreaLightMaterial( 20 ) );
+		light5.position.set( 3.235, 11.486, - 12.541 );
+		light5.scale.set( 2.5, 2.0, 0.1 );
+		this.add( light5 );
+
+		// +y
+		const light6 = new Mesh( geometry, createAreaLightMaterial( 100 ) );
+		light6.position.set( 0.0, 20.0, 0.0 );
+		light6.scale.set( 1.0, 0.1, 1.0 );
+		this.add( light6 );
+
+	}
+
+	dispose() {
+
+		const resources = new Set();
+
+		this.traverse( ( object ) => {
+
+			if ( object.isMesh ) {
+
+				resources.add( object.geometry );
+				resources.add( object.material );
+
+			}
+
+		} );
+
+		for ( const resource of resources ) {
+
+			resource.dispose();
+
+		}
+
+	}
+
+}
+
+function createAreaLightMaterial( intensity ) {
+
+	const material = new MeshBasicMaterial();
+	material.color.setScalar( intensity );
+	return material;
+
+}
+
+export { RoomEnvironment };