@wji.ai/cli 0.8.1 → 0.8.3

package/skill/short-drama/scripts/selftest.mjs

@@ -7,7 +7,6 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { renderDashboard } from './short-drama-dashboard.mjs';
 import {
   CAMERAS, GATES, STAGES, STYLE_PRESETS, CINEMATOGRAPHY_PRESETS, cinematographyForGenre, ACTION_STYLES, ACTION_RULES, actionForGenre, IP_NAMES_RE, GRAMMARS, GRAMMAR_RULES, COMEDY_STYLES, FACESLAP, grammarsOf, grammarLines, grammarForGenre, comedyForGenre, COMPOSITION_STYLES, COMPOSITION_DEVICES, compositionOf, compositionForGenre, STORY_GENRES, STORY_RULES, storyOf, storyForGenre, FORMATS, span, runsAtLeast, formatForGenre, cinematographyOf, stopNumber,
   bindPath, claimedLines, containsName, cutStarts, dialogueSeconds, episodeSeconds,
@@ -15,12 +14,15 @@ import {
   paramsOf, parseEpRange, promptSkeleton, renderCharacter, renderOutline, renderProp, renderScene, renderScript,
   renderSegment, runGates, seedScript, seedStoryboard, seedanceAnchors, slug, timestamp, writeJsonFile,
   wanLegendLine, wanSheetLegendLine, wanShotHeader, segmentReferences, imageReferences, audioReferences, voiceSamplePrompt, voiceSampleSeconds, nonWhitespace,
-  speechDirection, cameraPhrase, lightPhrase, foregroundPhrase, focalOf, LIGHT_DIRECTIONS, identityOf, isEnglish,
+  speechDirection, cameraPhrase, lightPhrase, idlePhrase, idleSentence, IDLE_MAX_CHARS, eyelinePhrase, eyelineValid, onlyInFramePhrase, overShoulderPhrase, sidesLine, foregroundPhrase, foregroundBand, foregroundForLook, focalOf, LIGHT_DIRECTIONS, identityOf, isEnglish,
   renderGuideline, renderDialogue, scriptSelfCheck, beatOffsets, turnPoints, parseAge, talkAndAction, normalizeRegister, REGISTERS, REGISTER_ACCENT,
   cutStart, segmentCharacters, keyScenes, shotTexts, motionSentence, cameraClause, PURPOSE_KINDS, ANGLES, HEIGHTS, NO_SUBTITLES, LIPS_CLOSED,
   audioPrompt, musicOf, cueSeconds, AUDIO_MODEL, AUDIO_MAX_CHARS, AUDIO_MAX_SECONDS, scoreSheet, smpte,
   VIDEO_MODELS, VIDEO_MODES, DEFAULT_PARAMS, videoModel, videoResolutionFor, nearestResolution, segmentPlan, videoReferences,
+  formatGates, displayName, imagePrompt, imagePromptKit, foldZh, IMAGE_PROMPT_LANGS,
 } from './short-drama.mjs';
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, symlinkSync } from 'node:fs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const FIXTURE = join(here, '../examples/night-shift');
@@ -48,34 +50,35 @@ const breaks = (gateId, project, episode, needle) => {
 
 // ── dashboard ──────────────────────────────────────────────────────────────
 {
-  const outputPath = join(tmpdir(), 'wji-short-drama-dashboard-test.html');
-  const html = renderDashboard({
-    project: PROJECT,
-    episodes: { 1: E01 },
-    gateResults: runGates(makeContext(PROJECT, { 1: E01 })),
-    projectDir: FIXTURE,
-    outputPath,
-  });
+  const html = readFileSync(join(here, '../dashboard.html'), 'utf8');
   ok(html.startsWith('<!doctype html>'), 'dashboard is a standalone HTML document');
-  ok(html.includes('夜班便利店') && html.includes('人物设定'), 'dashboard renders project sections');
-  ok(html.includes('E01-01') && html.includes('制作总览'), 'dashboard renders episode storyboard');
-  ok(html.includes('图片占位'), 'dashboard keeps an image placeholder when no media is bound');
-
-  const mediaDir = mkdtempSync(join(tmpdir(), 'wji-dashboard-media-'));
-  const localImage = join(mediaDir, 'lin.jpg');
-  writeFileSync(localImage, '');
-  const withMedia = clone(PROJECT);
-  withMedia.characters[0].image.url = localImage;
-  withMedia.characters[1].video = { url: 'https://cdn.example.com/chen.mp4', type: 'video' };
-  const mediaHtml = renderDashboard({
-    project: withMedia,
-    episodes: { 1: E01 },
-    projectDir: mediaDir,
-    outputPath: join(mediaDir, 'dashboard.html'),
-  });
-  ok(mediaHtml.includes('lin.jpg') && mediaHtml.includes('<img'), 'dashboard uses a local image path');
-  ok(mediaHtml.includes('<video src="https://cdn.example.com/chen.mp4"'), 'dashboard uses a WJI video URL');
-  rmSync(mediaDir, { recursive: true, force: true });
+  ok(html.includes('project.json') && html.includes('episodes/E'), 'dashboard loads project.json and episode files');
+  ok(html.includes('/assets/check-status') && html.includes('/assets/list/'), 'dashboard resolves an asset id to its file url');
+  ok(html.includes('圖片佔位'), 'dashboard keeps an image placeholder when no media is bound');
+  ok(!html.includes('夜班便利店'), 'dashboard does not bake the fixture into the page');
+  ok(!html.includes('asset download'), 'dashboard does not download asset files');
+  ok(html.includes('data-target') && html.includes('scrollTo'), 'dashboard left nav scrolls the content column');
+  ok(html.includes('episode.scenes') && html.includes('△') && html.includes('<details class="script">'), 'dashboard folds the episode script from scenes[].flow');
+  ok(html.includes('localStorage.setItem') && html.includes('wji-short-drama-token') && html.includes('login-dialog'), 'dashboard saves the API key in localStorage');
+  ok(html.includes('https://app.wji.ai') && html.includes('InfiniteCanvas') && html.includes("app: 'Dataset'"), 'dashboard links to the WJI canvas and dataset pages');
+  ok(html.includes('id="viewer"') && html.includes('data-kind'), 'dashboard enlarges an image or video on click');
+
+  const dir = mkdtempSync(join(tmpdir(), 'sd-dash-copy-'));
+  try {
+    writeFileSync(join(dir, 'project.json'), JSON.stringify(PROJECT));
+    const engine = join(here, 'short-drama.mjs');
+    const first = spawnSync(process.execPath, [engine, 'dashboard', dir], { encoding: 'utf8' });
+    eq(first.status, 0, `dashboard copies a missing file: ${first.stderr}`);
+    ok(existsSync(join(dir, 'dashboard.html')), 'dashboard.html is copied beside project.json');
+    const stamped = join(dir, 'dashboard.html');
+    writeFileSync(stamped, 'keep');
+    const second = spawnSync(process.execPath, [engine, 'dashboard', dir], { encoding: 'utf8' });
+    eq(second.status, 0, 'dashboard leaves an existing file');
+    eq(readFileSync(stamped, 'utf8'), 'keep', 'an existing dashboard.html is not overwritten');
+    ok(second.stdout.includes('already beside project.json'), 'dashboard reports the file is already there');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
 }
 
 // ── fixture is green ────────────────────────────────────────────────────────
@@ -847,18 +850,127 @@ const breaks = (gateId, project, episode, needle) => {
   breaks('photography', PROJECT, noNote, 'light.note is required');
   const wrongDir = clone(E01); wrongDir.storyboard.segments[0].cuts[0].light.direction = 'top';
   breaks('photography', PROJECT, wrongDir, 'keyed from directly above');
-  // Foreground: named in the frame, said to be out of focus, and present on at least half the cuts.
+  // Foreground: named in the frame, said to be out of focus, and within params.foregroundLevel across the episode.
   ok(foregroundPhrase(cut).includes('out of focus'), 'the foreground phrase says it is defocused');
   eq(foregroundPhrase({ foreground: '' }), '', 'a clean frame adds nothing');
   ok(foregroundPhrase({ foreground: '\u6536\u94f6\u53f0' }, 'zh').includes('\u524d\u666f'), 'the Chinese foreground phrase says 前景');
-  const noFg = clone(E01); noFg.storyboard.segments[0].cuts.forEach((c) => { c.foreground = ''; });
-  breaks('photography', PROJECT, noFg, 'no depth');
+  const noFg = clone(E01); noFg.storyboard.segments.forEach((seg) => seg.cuts.forEach((c) => { c.foreground = ''; }));
+  // The fixture sits at `high`: no foreground at all is too few there, and fine at `low`.
+  breaks('photography', PROJECT, noFg, 'params.foregroundLevel high allows');
+  const asLevel = (level) => ({ ...PROJECT, params: { ...PROJECT.params, foregroundLevel: level } });
+  ok(!failures('photography', asLevel('low'), noFg).some((f) => f.includes('foregroundLevel')), 'low accepts an episode of clean frames');
+  breaks('photography', asLevel('low'), E01, 'params.foregroundLevel low allows');
+  breaks('photography', asLevel('medium'), E01, 'params.foregroundLevel medium allows');
+  breaks('params', asLevel('sometimes'), E01, 'params.foregroundLevel must be one of');
+  const levelFor = (params) => paramsOf({ params }).foregroundLevel;
+  eq(levelFor({}), 'medium', 'the default level is medium');
+  eq(levelFor({ composition: 'standard', cinematography: 'low-key', genre: '复仇' }), 'medium', 'a standard look stays medium');
+  eq(levelFor({ composition: 'art-first' }), 'high', '艺术优先 defaults to high');
+  eq(levelFor({ cinematography: 'sweet-romance' }), 'high', 'the 唯美 romance preset defaults to high');
+  eq(levelFor({ cinematography: 'costume-idol' }), 'high', 'the 唯美 costume preset defaults to high');
+  eq(levelFor({ genre: '唯美古风' }), 'high', 'a 唯美 genre defaults to high');
+  eq(levelFor({ genre: '美感優先' }), 'high', 'a 美感優先 genre defaults to high');
+  eq(levelFor({ composition: 'art-first', foregroundLevel: 'low' }), 'low', 'a named level beats the look');
+  eq(foregroundForLook({ cinematography: 'costume-dark' }), 'medium', 'the dark costume preset is not 唯美');
+  eq(foregroundBand('low', 40).max, 10, 'low allows a quarter of the cuts');
+  eq(foregroundBand('medium', 40).min, 10, 'medium starts at a quarter');
+  eq(foregroundBand('medium', 40).max, 20, 'medium stops at half');
+  eq(foregroundBand('high', 40).min, 20, 'high starts at half');
+  ok(foregroundBand('nope', 40) === null, 'an unknown level has no band');
+  for (const [k, pr] of Object.entries(CINEMATOGRAPHY_PRESETS)) if (pr) ok(!/foreground/i.test(pr.videoPhrase) && !/前景/.test(pr.videoPhraseZh), `${k} leaves the foreground to the level`);
   const missingFg = clone(E01); delete missingFg.storyboard.segments[0].cuts[0].foreground;
   breaks('photography', PROJECT, missingFg, 'foreground is required');
   const unsaidFg = clone(E01); unsaidFg.storyboard.segments[0].cuts[0].frame = unsaidFg.storyboard.segments[0].cuts[0].frame.replace('the dripping edge of the striped awning', 'a wall');
   breaks('photography', PROJECT, unsaidFg, 'must name the foreground');
 }
 
+{
+  // Everyone on screen is alive: a model freezes whoever the prompt gives no motion.
+  eq(idlePhrase('shifts her weight', '@image3'), '@image3 shifts her weight.', 'an idle reads as a sentence');
+  eq(idlePhrase('still', '@image3'), '@image3 holds still, only breathing and blinking.', 'still keeps the breath');
+  ok(idlePhrase('轻轻换了一下重心', '@image3', 'zh').endsWith('轻轻换了一下重心。'), 'the Chinese idle');
+  eq(idleSentence({ characters: ['A', 'B'], idle: { B: 'taps a finger' } }, (id) => id), 'B taps a finger. ', 'only the people with an idle are written');
+  const p = clone(PROJECT); p.params.references = 'sheets';
+  const only = (f) => f.filter((m) => m.startsWith('E01-02'));
+  const build = (idle) => {
+    const ep = clone(E01); const seg = ep.storyboard.segments.find((s) => s.id === 'E01-02');
+    const two = seg.cuts[2];   // C01 + C02
+    if (idle) two.idle = idle;
+    seg.prompt = promptSkeleton(p, ep, seg.id).video.prompt;
+    return { ep, seg, two };
+  };
+  const bare = build();
+  ok(only(failures('idle-motion', p, bare.ep)).some((m) => m.includes('have an idle')), 'a second visible person with no idle fails');
+  const good = build({ C02: 'shifts her weight and picks at her sleeve' });
+  eq(only(failures('idle-motion', p, good.ep)).filter((m) => !m.includes('cameraNote.hold')).length, 0, 'one idle for the second person passes');
+  ok(good.seg.prompt.includes('shifts her weight and picks at her sleeve.'), 'the skeleton writes the idle');
+  const stillOne = build({ C02: 'still' });
+  ok(stillOne.seg.prompt.includes('holds still, only breathing and blinking.'), 'still is written with the breath');
+  eq(only(failures('idle-motion', p, stillOne.ep)).filter((m) => !m.includes('cameraNote.hold')).length, 0, 'keeping still is allowed when it is the performance');
+  ok(only(failures('idle-motion', p, build({ C02: 'walks to the door' }).ep)).some((m) => m.includes('too big')), 'a change of place is not an idle');
+  ok(only(failures('idle-motion', p, build({ C02: 'says something quietly' }).ep)).some((m) => m.includes('too big')), 'a line is not an idle');
+  ok(only(failures('idle-motion', p, build({ C02: 'x'.repeat(IDLE_MAX_CHARS + 1) }).ep)).some((m) => m.includes('one small motion')), 'an idle stays small');
+  const unwritten = build({ C02: 'taps a finger' }); unwritten.seg.prompt = unwritten.seg.prompt.replace(/taps a finger\.\s*/, '');
+  ok(only(failures('idle-motion', p, unwritten.ep)).some((m) => m.includes('must carry the idle')), 'an idle left out of the prompt fails');
+  const onlyHold = build({ C02: 'taps a finger' }); onlyHold.two.cameraNote = { ...onlyHold.two.cameraNote, hold: 'only the sign flickers' };
+  ok(only(failures('idle-motion', p, onlyHold.ep)).some((m) => m.includes('drop "only"')), '"only the sign" contradicts the people moving');
+  const offScreen = build({ C03: 'taps a finger' });
+  ok(only(failures('idle-motion', p, offScreen.ep)).some((m) => m.includes('not on screen')), 'an idle for someone off screen fails');
+  eq(failures('idle-motion', PROJECT, E01).length, 0, 'keyframes mode is exempt');
+}
+
+{
+  // Two people on screen, sheets mode: who is in frame, where they look, which side they stand on.
+  eq(eyelinePhrase('screen-right down', '@image3'), '@image3 looks toward screen-right and down.', 'an eyeline has a direction and a height');
+  eq(eyelinePhrase('task', '@image3'), '@image3 keeps their eyes on what their hands are doing.', 'task keeps the eyes on the work');
+  ok(eyelinePhrase('away screen-left', '@image3').includes('looks away'), 'away says so');
+  ok(eyelinePhrase('screen-left up', '@image3', 'zh').includes('左侧上方'), 'the Chinese eyeline');
+  ok(eyelineValid('screen-left level') && eyelineValid('task') && eyelineValid('away screen-right down'), 'valid eyelines');
+  ok(!eyelineValid('at him') && !eyelineValid('screen-right sideways'), 'an eyeline without a direction is refused');
+  const p = clone(PROJECT); p.params.references = 'sheets';
+  const framed = () => {
+    const ep = clone(E01);
+    const seg = ep.storyboard.segments.find((s) => s.id === 'E01-02');   // C01 | C02 | C01+C02 | C02 | C02, C02 screen left
+    const look = { C01: 'screen-left level', C02: 'screen-right level' };
+    seg.cuts.forEach((c) => { c.eyeline = Object.fromEntries((c.characters || []).map((id) => [id, look[id]])); });
+    seg.prompt = promptSkeleton(p, ep, seg.id).video.prompt;
+    return { ep, seg };
+  };
+  const only = (f) => f.filter((m) => m.startsWith('E01-02'));
+  const { ep: okEp, seg: okSeg } = framed();
+  eq(only(failures('two-person-framing', p, okEp)).length, 0, 'the skeleton writes everything the gate asks for');
+  ok(okSeg.prompt.includes('Sides: '), 'the skeleton locks the sides');
+  ok(okSeg.prompt.includes('Only @image'), 'the skeleton opens a single with who is in frame');
+  ok(okSeg.prompt.includes('looks toward screen-left'), 'the skeleton states the eyeline');
+  const noLook = framed(); delete noLook.seg.cuts[0].eyeline;
+  ok(only(failures('two-person-framing', p, noLook.ep)).some((m) => m.includes('is required')), 'an eyeline is required');
+  const vague = framed(); vague.seg.cuts[0].eyeline = { C01: 'at him' };
+  ok(only(failures('two-person-framing', p, vague.ep)).some((m) => m.includes('not valid')), '"at him" is refused');
+  const wrong = framed(); wrong.seg.cuts[0].eyeline = { C01: 'screen-right level' };
+  ok(only(failures('two-person-framing', p, wrong.ep)).some((m) => m.includes('so looking at the other person is screen-left')), 'looking away from the other person is caught');
+  const away = framed(); away.seg.cuts[0].eyeline = { C01: 'away screen-right' }; away.seg.prompt = promptSkeleton(p, away.ep, away.seg.id).video.prompt;
+  ok(!only(failures('two-person-framing', p, away.ep)).some((m) => m.includes('so looking')), 'a deliberate look away passes');
+  const noSides = framed(); noSides.seg.prompt = noSides.seg.prompt.replace(/Sides: [^\n]*\n/, '');
+  ok(only(failures('two-person-framing', p, noSides.ep)).some((m) => m.includes('must lock the sides')), 'a prompt without the sides line fails');
+  const leaked = framed();
+  const labelOf = /(@image\d+) looks toward screen-right/.exec(leaked.seg.prompt)[1];
+  leaked.seg.prompt = leaked.seg.prompt.replace(/(Shot 1 \([^)]*\): )/, `$1Behind him stands ${labelOf}. `).replace(/(\[Shot 1\] )/, `$1Behind him stands ${labelOf}. `);
+  ok(only(failures('two-person-framing', p, leaked.ep)).some((m) => m.includes('must not describe')), 'a single that names the other person fails');
+  const ots = framed(); const twoShot = ots.seg.cuts[2];
+  twoShot.ots = 'C01'; delete twoShot.eyeline.C01;
+  ots.seg.prompt = promptSkeleton(p, ots.ep, ots.seg.id).video.prompt;
+  ok(ots.seg.prompt.includes('their face not visible'), 'the skeleton writes the over-the-shoulder');
+  ok(ots.seg.prompt.includes('lower-right foreground'), 'the near shoulder sits on its own side of the axis');
+  eq(only(failures('two-person-framing', p, ots.ep)).length, 0, 'over-the-shoulder needs no eyeline from the shoulder');
+  const badOts = framed(); badOts.seg.cuts[0].ots = 'C02';
+  ok(only(failures('two-person-framing', p, badOts.ep)).some((m) => m.includes('ots must be one of')), 'ots must be on screen with one other');
+  eq(onlyInFramePhrase('@image3', 'zh'), '画面中只有@image3。', 'the Chinese single');
+  ok(overShoulderPhrase('@image3', 'left', 'zh').includes('左下方前景'), 'the Chinese over-the-shoulder');
+  ok(sidesLine({ screenLeft: 'A', screenRight: 'B' }, (id) => id, 'zh').includes('A始终在画面左侧'), 'the Chinese sides line');
+  // Keyframes carry the blocking in their pictures: the gate stays out of the way.
+  eq(failures('two-person-framing', PROJECT, E01).length, 0, 'keyframes mode is exempt');
+}
+
 {
   // The house cinematography (params.cinematography low-key): practical sources, no flat light on a
   // person, most cuts keyed from the side or behind, shot wide open; the look rides every prompt.
@@ -1517,7 +1629,11 @@ const breaks = (gateId, project, episode, needle) => {
   const s = seedScript(PROJECT, 2);
   eq(s.targetSeconds, 60, 'seed target seconds from params');
   eq(s.beatsClaimed.join(','), 'B02', 'seed claims the episode beats');
-  eq(s.seedNote.previousCliff, PROJECT.outline.episodes[0].suspense, 'seed carries the previous cliff');
+  eq(s.seedNote.previousCliff, PROJECT.outline.episodes[0].hook, 'seed carries the previous cliff (the outline hook of the episode before)');
+  eq(s.hook, '', 'seed leaves the opening hook for the writer');
+  eq(s.cliff, PROJECT.outline.episodes[1].hook, 'seed cliff is the outline hook (the question that makes them tap next)');
+  eq(s.seedNote.suspense, PROJECT.outline.episodes[1].suspense, 'seed note carries the outline suspense');
+  ok(s.seedNote.openingHook.includes('opens the episode'), 'seed note says the hook is the opening image');
   eq(s.scenes.length, 0, 'seed leaves scenes empty');
   assert.throws(() => seedScript(PROJECT, 9), /no episode 9/, 'seed refuses unknown episode');
   const sb = seedStoryboard(PROJECT, E01);
@@ -2298,4 +2414,295 @@ const breaks = (gateId, project, episode, needle) => {
   eq(slug('E01-01 便利店 / 夜班'), 'e01-01-便利店-夜班', 'slug keeps CJK, drops separators');
 }
 
+// ── gate inventory (crew engine) ────────────────────────────────────────────
+{
+  eq(GATES.length, 69, 'gate count');
+  eq(GATES.filter((g) => !g.advisory).length, 63, 'hard gate count');
+  eq(GATES.filter((g) => g.advisory).length, 6, 'advisory gate count');
+  ok(!GATES.find((g) => g.id === 'boundary-contrast').advisory, 'boundary-contrast is hard');
+  ok(GATES.find((g) => g.id === 'boundary-contrast-episode').advisory, 'boundary-contrast-episode is advisory');
+  eq(DEFAULT_PARAMS.boundaryContrastCuts, 2, 'boundaryContrastCuts default');
+}
+
+// ── boundary-contrast (跨场边界) ─────────────────────────────────────────────
+{
+  passes('boundary-contrast', PROJECT, E01);
+  // E01-01 is scene 1, E01-02 opens scene 2: copy scene 1's last cut signature onto scene 2's first cut
+  const last = E01.storyboard.segments[0].cuts.at(-1);
+  const same = (c) => Object.assign(c, { size: last.size, angle: last.angle, characters: [...last.characters] });
+  const e = clone(E01); same(e.storyboard.segments[1].cuts[0]);
+  breaks('boundary-contrast', PROJECT, e, 'across the scene 1→2 boundary');
+  const e2 = clone(e); e2.storyboard.segments[1].cuts[0].note = 'match-cut on her hand';
+  passes('boundary-contrast', PROJECT, e2);
+  const e3 = clone(e); e3.storyboard.segments[0].cuts.at(-1).note = 'Match Cut';
+  passes('boundary-contrast', PROJECT, e3);
+  // K decides how deep the comparison reaches: a match one cut in only counts when K ≥ 2
+  const e4 = clone(E01); same(e4.storyboard.segments[1].cuts[1]);
+  breaks('boundary-contrast', PROJECT, e4, 'cut 2');
+  const p1 = clone(PROJECT); p1.params.boundaryContrastCuts = 1;
+  passes('boundary-contrast', p1, e4);
+  const p9 = clone(PROJECT); p9.params.boundaryContrastCuts = 9;   // clamps to 3
+  const e5 = clone(E01); same(e5.storyboard.segments[1].cuts[2]);
+  breaks('boundary-contrast', p9, e5, 'cut 3');
+  passes('boundary-contrast', PROJECT, e5);
+  const pBad = clone(PROJECT); pBad.params.boundaryContrastCuts = 'lots';   // falls back to 2
+  breaks('boundary-contrast', pBad, e4, 'cut 2');
+  const e6 = clone(e); e6.storyboard.segments.forEach((s) => delete s.sceneIndex);
+  passes('boundary-contrast', PROJECT, e6);
+}
+
+// ── boundary-contrast-episode (跨集边界, advisory) ───────────────────────────
+{
+  const e02 = clone(E01);
+  e02.storyboard.segments.forEach((s, i) => { s.id = `E02-${String(i + 1).padStart(2, '0')}`; });
+  const lastCut = E01.storyboard.segments.at(-1).cuts.at(-1);
+  Object.assign(e02.storyboard.segments[0].cuts[0], { size: lastCut.size, angle: lastCut.angle, characters: [...lastCut.characters] });
+  const g = GATES.find((x) => x.id === 'boundary-contrast-episode');
+  const notes = g.run(makeContext(PROJECT, { 1: E01, 2: e02 }));
+  ok(notes.length > 0 && notes.some((m) => m.includes('across episode E01→E02')), `episode boundary noted: ${notes.join(' | ')}`);
+  const results = runGates(makeContext(PROJECT, { 1: E01, 2: e02 }), { only: ['storyboard'] });
+  const r = results.find((x) => x.id === 'boundary-contrast-episode');
+  ok(r.advisory && r.failures.length === 0 && r.warnings.length > 0, 'episode boundary is a warning, never a failure');
+  e02.storyboard.segments[0].cuts[0].note = 'match-cut';
+  eq(g.run(makeContext(PROJECT, { 1: E01, 2: e02 })).length, 0, 'match-cut exempts the episode boundary');
+  eq(g.run(makeContext(PROJECT, { 1: E01 })).length, 0, 'one episode has no episode boundary');
+}
+
+// ── refOverride / faceOf (Director pins the picture references) ──────────────
+{
+  const sheets = clone(PROJECT); sheets.params.references = 'sheets';
+  const e = clone(E01);
+  const seg = e.storyboard.segments[1];   // S01 with C01 + C02 + P01
+  const derived = segmentReferences(sheets, e, seg);
+  eq(derived.filter((r) => r.kind === 'image').map((r) => r.entity).join(','), 'S01,C01,C02,P01', 'derived picture order: environment, people, props');
+  seg.refOverride = [{ entity: 'C01', asset: 'headshot', faceOf: 'C01' }, { entity: 'S01' }];
+  const refs = segmentReferences(sheets, e, seg);
+  const pics = refs.filter((r) => r.kind === 'image');
+  eq(pics.map((r) => `${r.entity}:${r.asset}:${r.label}`).join(' '), 'C01:headshot:@image1 S01:sheet:@image2', 'refOverride replaces the pictures, in its own order');
+  eq(pics[0].faceOf, 'C01', 'faceOf rides along');
+  eq(pics[1].why, 'S01:sheet', 'override defaults fill why');
+  eq(refs.filter((r) => r.kind === 'audio').length, derived.filter((r) => r.kind === 'audio').length, 'voices are still appended after an override');
+  const sk = promptSkeleton(sheets, e, 'E01-02');
+  ok(sk.video.prompt.includes('the person in @image1'), 'the speaker binds to the headshot label');
+  // A body sheet first, the headshot later: the headshot still wins the face binding
+  seg.refOverride = [{ entity: 'C01', asset: 'sheet' }, { entity: 'C01', asset: 'headshot', faceOf: 'C01' }, { entity: 'S01' }];
+  const sk2 = promptSkeleton(sheets, e, 'E01-02');
+  ok(sk2.video.prompt.includes('the person in @image2'), 'headshot / faceOf beats an earlier body sheet');
+  seg.refOverride = [];
+  eq(segmentReferences(sheets, e, seg).filter((r) => r.kind === 'image')[0].entity, 'S01', 'an empty override falls back to the derived set');
+}
+
+// ── VO lines: off-screen, no @audio, every visible mouth closed ───────────────
+{
+  const vo = (project) => {
+    const e = clone(E01);
+    e.scenes[1].flow[2].speaker = 'VO';   // beat 3, claimed by E01-02 cut 3 where C01 and C02 are on screen
+    const sk = promptSkeleton(project, e, 'E01-02');
+    const line = sk.dialogue.flat().find((l) => l.speaker === 'VO');
+    ok(line && /off-screen/.test(line.speakerRef), 'VO speaker is described as off-screen');
+    ok(sk.video.prompt.includes('off-screen'), 'the prompt says the voice is off-screen');
+    ok(sk.video.prompt.includes(`do not speak, ${LIPS_CLOSED}`), 'both visible people keep their lips closed under a VO');
+    ok(audioReferences(project, e, e.storyboard.segments[1]).every((r) => r.entity !== 'VO'), 'VO gets no voice reference');
+    eq(claimedLines(e.scenes[1], e.storyboard.segments[1].cuts).filter((l) => l.speaker === 'VO').length, 1, 'the VO line is still claimed by its cut');
+    return e;
+  };
+  const eVo = vo(PROJECT);                                             // h3 / keyframes branch
+  const sheets = clone(PROJECT); sheets.params.references = 'sheets'; vo(sheets);   // sheets branch
+  const seedance = clone(PROJECT); seedance.params.video = 'seedance'; seedance.params.references = 'sheets'; vo(seedance);
+  passes('beat-flow', PROJECT, eVo);
+  const eBad = clone(E01); eBad.scenes[1].flow[2].speaker = 'C03';
+  breaks('beat-flow', PROJECT, eBad, 'not in this scene (or VO)');
+}
+
+// ── one-episode structure ───────────────────────────────────────────────────
+{
+  const one = clone(PROJECT);
+  one.params.episodes = 1;
+  one.outline.episodes = one.outline.episodes.slice(0, 1);
+  const golden = { ...one.outline.structure[0], episodes: [1, 1] };
+  const climax = { ...one.outline.structure[2], episodes: [1, 1] };
+  one.outline.structure = [golden, climax];
+  passes('structure', one, null);
+  const p2 = clone(one); p2.outline.structure = [golden];
+  breaks('structure', p2, null, 'golden → climax');
+  const p3 = clone(one); p3.outline.structure = [{ ...golden, episodes: [1, 2] }, climax];
+  breaks('structure', p3, null, 'inside 1–1');
+  const p4 = clone(one); p4.params.episodes = 2; p4.outline.episodes = PROJECT.outline.episodes.slice(0, 2);
+  p4.outline.structure = [golden, { ...climax, episodes: [2, 2] }];
+  passes('structure', p4, null);
+  const p5 = clone(p4); p5.outline.structure = [{ ...golden, episodes: [1, 1] }, { ...climax, episodes: [1, 2] }];
+  breaks('structure', p5, null, 'expected 2');
+}
+
+// ── formatGates (what the CLI prints and what wji-backend embeds) ─────────────
+{
+  const results = runGates(makeContext(PROJECT, { 1: E01 }));
+  const rep = formatGates(results);
+  eq(Object.keys(rep).sort().join(','), 'advisory,failed,hard,lines,notes,summary,text', 'formatGates shape');
+  eq(rep.summary, '✓ 63 gate(s) passed, 6 advisory (1 note)', 'fixture summary');
+  eq(rep.failed, 0, 'nothing failed'); eq(rep.hard, 63, 'hard count'); eq(rep.advisory, 6, 'advisory count');
+  // The fixture now raises one advisory (E01-03 carries the 爽点 and is not cut as faceslap),
+  // exactly as it does in the wji-cli copy — advisory lines print, failures still must not.
+  eq(rep.lines.filter((l) => l.includes('✗')).length, 0, 'a green run prints no failed gates');
+  eq(rep.lines.length, 2, 'a green run prints only the advisory and its note');
+  ok(rep.text.endsWith(rep.summary), 'text ends with the summary');
+  const staged = formatGates(runGates(makeContext(PROJECT, {}), { stage: 'art' }), { stage: 'art' });
+  ok(staged.summary.includes('(through art)'), 'staged summary names the stage');
+  const all = formatGates(results, { all: true });
+  ok(all.lines.length >= 67 && all.lines.some((l) => l.includes('(advisory)')), '--all lists every gate');
+  ok(formatGates(runGates(makeContext(PROJECT, {})), { all: true }).lines.some((l) => l.includes('(skipped: no episode files)')), '--all shows skipped gates');
+  const bad = clone(PROJECT); bad.params.register = '';
+  const red = formatGates(runGates(makeContext(bad, { 1: E01 })));
+  ok(red.failed > 0 && red.summary.startsWith('✗') && red.text.includes('outline/params'), 'a broken register shows as a failed outline/params gate');
+}
+
+// ── names in the prompt-bound voice / delivery text; disguised characters ─────
+{
+  const p = clone(PROJECT);
+  p.characters[1].voice.emotion += '，对小夏说话时放轻';
+  breaks('voice', p, null, 'voice.emotion contains the name "小夏"');
+  const p2 = clone(PROJECT);
+  p2.characters[0].voice.sample.direction = '盯着老陈，压低声音';
+  breaks('voice', p2, null, 'voice.sample.direction contains the name "老陈"');
+  const p3 = clone(PROJECT);
+  p3.characters[0].voice.prompt += ' Speaks softly to Chen.';
+  passes('voice', p3);                                   // an English word that is no name of the cast
+  p3.characters[1].aliases.push('Uncle Chen');
+  p3.characters[0].voice.prompt += ' Warm with Uncle Chen.';
+  breaks('voice', p3, null, 'voice.prompt contains the name "Uncle Chen"');
+
+  const wan = clone(PROJECT); wan.params.video = 'wan';
+  passes('beat-flow', wan, E01);
+  const e = clone(E01);
+  e.scenes[0].flow[1].delivery = '压着嗓子，盯着林小夏';
+  breaks('beat-flow', wan, e, 'delivery names "林小夏"');
+  passes('beat-flow', PROJECT, e);                       // an English (h3) prompt never carries a Chinese delivery
+  const eEn = clone(E01);
+  eEn.scenes[0].flow[1].delivery = 'hisses it at Uncle Chen';
+  breaks('beat-flow', p3, eEn, 'delivery names "Uncle Chen"');
+
+  const d = clone(PROJECT);
+  d.characters[2].disguise = { name: '过路人', revealEpisode: 3 };
+  passes('tiers', d);
+  eq(displayName(d, 'C03', 1), '过路人', 'before the reveal the disguise name is shown');
+  eq(displayName(d, 'C03', 3), '穿雨衣的男人', 'from the reveal episode on the real name is shown');
+  eq(displayName(d, 'C03'), '穿雨衣的男人', 'without an episode the real name is shown');
+  eq(displayName(d, 'C01', 1), '林小夏', 'undisguised characters keep their name');
+  ok(forbiddenNames(d).includes('过路人'), 'a disguise name is a forbidden prompt name');
+  const script = renderScript(d, E01);
+  ok(script.includes('过路人（') && !script.includes('穿雨衣的男人（'), 'render script attributes lines to the disguise name');
+  ok(/人物：[^\n]*过路人/.test(script), 'render script lists the disguise name in the scene cast');
+  ok(renderDialogue(d, E01).includes('过路人（') && !renderDialogue(d, E01).includes('穿雨衣的男人（'), 'render dialogue uses the disguise name');
+  eq(seedScript(d, 1).seedNote.speech.C03.name, '过路人', 'seed note uses the disguise name');
+  const late = clone(E01); late.ep = 3;
+  ok(renderScript(d, late).includes('穿雨衣的男人（'), 'after the reveal the script uses the real name');
+  for (const [bad, needle] of [[{ name: '过路人', revealEpisode: 1 }, 'revealEpisode'], [{ name: '穿雨衣的男人', revealEpisode: 2 }, 'equals the real name'], [{ revealEpisode: 2 }, 'disguise.name is empty'], [{ name: '过路人', revealEpisode: 9 }, 'revealEpisode']]) {
+    const x = clone(PROJECT); x.characters[2].disguise = bad;
+    breaks('tiers', x, null, needle);
+  }
+}
+
+// ── Chinese image prompts (params.imagePromptLang = zh) ──────────────────────
+{
+  // the fixture with its image prompts written in Chinese; C02 in 繁體 to prove the folding
+  const zh = clone(PROJECT);
+  zh.params.imagePromptLang = 'zh';
+  const R = '半写实角色插画，绘画质感，笔触柔和融合并带可见的笔刷肌理，解剖结构扎实';
+  const NEG = '眼神空洞、塑料皮肤、过度磨皮、完全对称的脸、死板发型、无纹理布料、标志、品牌名、文字、水印';
+  const CH = {
+    C01: ['二十四岁左右的东亚女性，当代中国，便利店夜班店员，短发齐耳，褪色的藏青夹克，眼下微青，四分之三侧身胸像，纯色中性背景，左上方柔和方向光',
+      '单人角色设定图，一张 16:9 横版画布，纯白背景。' + R + '。左区一张正面胸像，右上三个全身像（正面、侧面、背面），右下四个细节特写；人物：二十四岁东亚女性，短发，藏青夹克。无文字、无水印。'],
+    C02: ['六十歲出頭的東亞男性，當代中國，退休保安，矮壯微駝，花白平頭，洗舊的灰色夾克，指節粗大，四分之三側身胸像，純色中性背景，左上方柔和方向光',
+      '單人角色設定圖，一張 16:9 橫版畫布，純白背景。半寫實角色插畫，繪畫質感，筆觸柔和。左區一張正面胸像，右上三個全身像，右下四個細節特寫；人物：六十歲東亞男性，花白平頭，灰夾克。無文字、無水印。'],
+    C03: ['三十多岁的东亚男性，当代中国，穿深色连帽雨衣，帽檐压低，下巴有胡茬，身形瘦高，四分之三侧身胸像，纯色中性背景，右侧硬光',
+      '单人角色设定图，一张 16:9 横版画布，纯白背景。' + R + '。左区一张正面胸像，右上三个全身像，右下四个细节特写；人物：三十多岁东亚男性，深色雨衣，瘦高。无文字、无水印。'],
+  };
+  for (const c of zh.characters) Object.assign(c.image, { prompt: CH[c.id][0], sheet: CH[c.id][1], negativePrompt: NEG });
+  const SC = {
+    S01: ['中国城市里一家小便利店的店内，空场景，没有人，从门口望向收银台，关东煮机的灯箱闪烁，绿色四格监控屏，夜晚冷白日光灯', { 凌晨冷白光: '凌晨，整片冷白日光灯，货架投下硬影', 监控回放绿: '只剩监控屏的绿光照亮收银台，其余沉在暗里' }],
+    S02: ['便利店门口的条纹雨棚下，空场景，没有人，湿漉漉的地面反光，门口的垃圾桶，雨夜', { 雨夜冷白灯: '雨夜，雨棚下一盏冷白灯，雨丝在灯下发亮' }],
+  };
+  for (const sc of zh.scenes) {
+    Object.assign(sc.image, { prompt: SC[sc.id][0], sheet: `环境设定图，一张 16:9 横版画布。${R}。主画面：${SC[sc.id][0]}；右侧与底部为锚点细节特写，所有格子是同一个空间。无文字、无水印。`, negativePrompt: '人、人物、人影、人群、手、标志、品牌名、文字、水印' });
+    for (const l of sc.lighting) l.prompt = SC[sc.id][1][l.state];
+  }
+  const pr = zh.props[0];
+  Object.assign(pr.image, { prompt: '一个旧的三点五寸监控硬盘，手持尺寸，金属外壳有划痕，贴着褪色的标签（不可辨读），纯白背景，没有人，没有手，柔和均匀的棚拍光',
+    sheet: `道具设定图，一张 16:9 横版画布，纯白背景。${R}。主画面：旧监控硬盘，手持尺寸，四分之三视角；右侧与底部为细节特写。没有人、没有手。无文字、无水印。`,
+    negativePrompt: '人、人物、手、手指、杂乱背景、标志、品牌名、文字、水印' });
+  pr.states[0].prompt = '装在半透明的防静电袋里，袋口折起';
+  pr.states[1].prompt = '接上一根灰色数据线，指示灯亮着';
+  for (const g of ['params', 'char-prompts', 'distinct', 'scene-design', 'scene-prompts', 'prop-design']) passes(g, zh);
+  ok(IMAGE_PROMPT_LANGS.includes('zh') && imagePromptKit(zh.params).zh, 'zh is an image-prompt language');
+  eq(foldZh('真人實拍參考攝影'), '真人实拍参考摄影', 'traditional folds to simplified');
+
+  const en = clone(PROJECT); en.params.imagePromptLang = 'zh';
+  breaks('char-prompts', en, null, 'image.prompt must be Chinese');
+  breaks('scene-prompts', en, null, 'must be Chinese');
+  breaks('scene-design', en, null, 'prompt must be Chinese');
+  breaks('prop-design', en, null, 'must be Chinese');
+  const fr = clone(PROJECT); fr.params.imagePromptLang = 'fr';
+  breaks('params', fr, null, 'imagePromptLang');
+
+  const x = clone(zh);
+  x.characters[0].image.prompt = x.characters[0].image.prompt.replace('东亚女性，当代中国', '女性，当代');
+  breaks('char-prompts', x, null, 'ethnicity');
+  const bright = clone(zh);
+  bright.characters[1].image.prompt = '东亚男性，退休保安，明亮清晰的元素，矮壮微驼';     // 明 / 清 / 元 alone are no era
+  breaks('char-prompts', bright, null, 'era');
+  x.characters[1].image.prompt = x.characters[1].image.prompt.replace('當代中國，', '');
+  breaks('char-prompts', x, null, 'era');
+  x.characters[2].image.sheet = x.characters[2].image.sheet.replace(R, '写实风格');
+  breaks('char-prompts', x, null, 'render phrase "半写实角色插画…"');
+  x.characters[0].image.negativePrompt += '、照片級';
+  breaks('char-prompts', x, null, 'must not ban "照片级"');
+  x.characters[0].image.sheet = x.characters[0].image.sheet.replace('16:9', '横版');
+  breaks('char-prompts', x, null, '16:9');
+  const y = clone(zh);
+  y.scenes[0].image.prompt = y.scenes[0].image.prompt.replace('空场景，没有人，', '');
+  breaks('scene-prompts', y, null, 'empty');
+  y.scenes[1].image.negativePrompt = '标志、文字、水印';
+  breaks('scene-prompts', y, null, 'ban people');
+  const z = clone(zh);
+  z.props[0].image.prompt = z.props[0].image.prompt.replace('手持尺寸，', '');
+  breaks('prop-design', z, null, 'must contain "手持尺寸"');
+  z.props[0].image.sheet = z.props[0].image.sheet.replace('纯白背景', '灰色背景');
+  breaks('prop-design', z, null, 'white background');
+  z.props[0].image.negativePrompt = '人、标志、文字';
+  breaks('prop-design', z, null, 'ban hands');
+  const d = clone(zh);
+  d.characters[2].image.prompt = d.characters[0].image.prompt;
+  breaks('distinct', d, null, 'image prompts are 100% alike');   // CJK bigrams, not English words
+
+  const head = imagePrompt(zh, 'C01', 'headshot');
+  ok(head.prompt.endsWith('正面干净人像，纯色中性背景') && head.ratio === '1:1' && head.from === null && head.lang === 'zh', 'zh headshot prompt');
+  const sheet = imagePrompt(zh, 'C01', 'sheet');
+  ok(sheet.prompt.startsWith('@image1 是必须完全一致的脸') && sheet.ratio === '16:9' && sheet.from === 'headshot' && sheet.negative === NEG, 'zh character sheet references the headshot');
+  const light = imagePrompt(zh, 'S01', 'lighting:监控回放绿');
+  ok(light.prompt.includes('只改变光线：只剩监控屏的绿光') && light.prompt.endsWith('空场景，没有任何人，电影剧照') && light.from === 'sheet', 'zh lighting variant');
+  ok(imagePrompt(zh, 'P01', 'state:接在主机上').prompt.startsWith('@image1 是要完全还原的同一件道具。接上一根灰色数据线'), 'zh prop state');
+  eq(imagePrompt(zh, 'S02').prompt, zh.scenes[1].image.sheet, 'a scene sheet is its sheet prompt');
+  ok(imagePrompt(PROJECT, 'C01', 'sheet').prompt.startsWith('@image1 is the face to match exactly'), 'en character sheet keeps the English prefix');
+  ok(imagePrompt(zh, 'C02', 'sheet').prompt.startsWith('@image1 是必須完全一致的臉——五官與髮型相同。'), '繁體 prompts get the 繁體 prefix');
+  ok(imagePrompt(zh, 'C02', 'headshot').prompt.endsWith('，正面乾淨人像，純色中性背景'), '繁體 headshot suffix');
+  ok(imagePrompt(PROJECT, 'S01', 'lighting:凌晨冷白光').prompt.endsWith('Empty scene, no people, cinematic film still'), 'en lighting variant');
+  assert.throws(() => imagePrompt(zh, 'S01', 'lighting:白天'), /no lighting state/, 'unknown lighting state refused');
+  assert.throws(() => imagePrompt(zh, 'C01', 'lighting:x'), /headshot \| sheet/, 'a character has no lighting');
+  assert.throws(() => imagePrompt(zh, 'X9'), /no character/, 'unknown id refused');
+}
+
+// ── the CLI entry point survives a symlink (realpath isMain) ──────────────────
+{
+  const dir = mkdtempSync(join(tmpdir(), 'sd-link-'));
+  try {
+    copyFileSync(join(here, 'short-drama.mjs'), join(dir, 'engine.mjs'));
+    symlinkSync(join(dir, 'engine.mjs'), join(dir, 'sd'));
+    const run = spawnSync(process.execPath, [join(dir, 'sd')], { encoding: 'utf8' });
+    eq(run.status, 0, 'symlinked engine exits 0 with usage');
+    ok(run.stdout.includes('short-drama — deterministic tooling'), 'symlinked engine prints usage (isMain resolved through realpath)');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 console.log(`✓ ${passed} assertions passed`);