@wji.ai/cli 0.8.2 → 0.9.0

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

@@ -19,6 +19,7 @@
 //            [--market mainland|overseas]                            (mainland holds the supernatural to a rational explanation)
 //            [--format short|medium|movie]                            (短剧 1–3 min, 中剧 4–15 min, 电影 in ~5-minute parts — see FORMATS)
 //            [--register 台湾国语]                                      (语体 — decides how lines are written and the accent spoken)
+//            [--foreground low|medium|high]                             (how often cuts shoot past a foreground — see FOREGROUND_LEVELS)
 //            [--image-lang en|zh]                                       (language of the character / scene / prop image prompts)
 //   validate <project> [--stage outline|characters|art|script|storyboard] [--ep 1-3]
 //   checkup  <project> [--stage …] [--ep …]            every gate with ✓/✗, exit 0
@@ -199,6 +200,28 @@ export const AUDIO_MAX_REFS = 3;
  * `bed` (ambience + sfx + music) / `full` (the bed plus the lines): a Seed Audio node per segment.
  */
 export const AUDIO_TRACK_MODES = ['post', 'none', 'bed', 'full'];
+// Share of an episode's cuts that may carry a foreground. Measured per episode, not per segment, so a
+// siege can be full of them and a quiet confession can have none.
+export const FOREGROUND_LEVELS = Object.freeze({
+  low: { min: 0, max: 0.25 },
+  medium: { min: 0.25, max: 0.5 },
+  high: { min: 0.5, max: 1 },
+});
+/**
+ * The level a project gets when it does not name one: `high` for 唯美 or 美感优先 — the art-first
+ * composition, the two 唯美 cinematography presets, or a genre that says so — `medium` otherwise.
+ */
+export function foregroundForLook(params) {
+  const aesthetic = params?.composition === 'art-first'
+    || ['sweet-romance', 'costume-idol'].includes(params?.cinematography)
+    || /唯美|美感/.test(String(params?.genre || ''));
+  return aesthetic ? 'high' : 'medium';
+}
+/** The foreground cut count a level allows in an episode of `cuts` cuts. */
+export function foregroundBand(level, cuts) {
+  const band = FOREGROUND_LEVELS[level];
+  return band ? { min: Math.floor(band.min * cuts), max: Math.ceil(band.max * cuts) } : null;
+}
 /** No per-segment audio node in these modes. */
 export const NO_SEGMENT_TRACK = ['post', 'none'];
 /** What the music does at a cue point. */
@@ -413,10 +436,58 @@ export function speechDirection(character, delivery, lang = 'en') {
   return bits.join(lang === 'zh' ? '\uff0c' : ', ');
 }
 
+// Two people on screen. A model puts into the shot everyone the shot names, and "looking at him" gives
+// it no direction, so sheets-mode prompts say who is in frame, which way each person looks and which
+// side each stands on (gate two-person-framing).
+export const EYELINE_DIRECTIONS = ['screen-left', 'screen-right'];
+export const EYELINE_HEIGHTS = ['level', 'up', 'down'];
+/** "screen-right down" · "away screen-left" · "task" (eyes on what the hands are doing). */
+export function parseEyeline(value) {
+  const words = String(value || '').trim().split(/\s+/).filter(Boolean);
+  if (words[0] === 'task') return { task: true };
+  const away = words[0] === 'away';
+  const [to, height = 'level'] = away ? words.slice(1) : words;
+  return { to, height, away };
+}
+export function eyelineValid(value) {
+  const e = parseEyeline(value);
+  return Boolean(e.task) || (EYELINE_DIRECTIONS.includes(e.to) && EYELINE_HEIGHTS.includes(e.height));
+}
+export function eyelinePhrase(value, who, lang = 'en') {
+  const e = parseEyeline(value);
+  const zh = lang === 'zh';
+  if (e.task) return zh ? `${who}的视线落在手上的活上。` : `${who} keeps their eyes on what their hands are doing.`;
+  const side = zh ? (e.to === 'screen-left' ? '左' : '右') : e.to;
+  if (zh) return `${who}的视线${e.away ? '移开，' : ''}朝画面${side}侧${e.height === 'up' ? '上方' : e.height === 'down' ? '下方' : '平视'}。`;
+  return `${who} ${e.away ? 'looks away toward' : 'looks toward'} ${side}${e.height === 'up' ? ' and up' : e.height === 'down' ? ' and down' : ' at eye level'}.`;
+}
+export function sidesLine(axis, whoOf, lang = 'en') {
+  const left = whoOf(axis.screenLeft), right = whoOf(axis.screenRight);
+  return lang === 'zh' ? `站位：${left}始终在画面左侧，${right}始终在画面右侧。` : `Sides: ${left} stays on screen left and ${right} on screen right in every shot.`;
+}
+export function onlyInFramePhrase(who, lang = 'en') {
+  return lang === 'zh' ? `画面中只有${who}。` : `Only ${who} in frame.`;
+}
+export function overShoulderPhrase(who, side, lang = 'en') {
+  return lang === 'zh'
+    ? `越过${who}的肩拍摄：其肩与后脑虚化在画面${side === 'left' ? '左' : '右'}下方前景，看不到其脸。`
+    : `Over-the-shoulder from behind ${who}: their shoulder and the back of their head soft in the lower-${side} foreground, their face not visible.`;
+}
+/** What a shot opens with in a two-person segment: who is in frame, then where each person looks. */
+export function shotFraming(cut, seg, whoOf, lang = 'en') {
+  if (segmentCharacters(seg).length < 2) return '';
+  const chars = cut.characters || [];
+  const parts = [];
+  if (cut.ots) parts.push(overShoulderPhrase(whoOf(cut.ots), seg.axis?.screenLeft === cut.ots ? 'left' : 'right', lang));
+  else if (chars.length === 1) parts.push(onlyInFramePhrase(whoOf(chars[0]), lang));
+  for (const id of chars) if (id !== cut.ots && cut.eyeline?.[id]) parts.push(eyelinePhrase(cut.eyeline[id], whoOf(id), lang));
+  return parts.length ? `${parts.join(' ')} ` : '';
+}
+
 /**
  * The blurred thing between the lens and the subject. Depth needs something to be shallow against,
- * so a cut names one and the prompt says it is out of focus; an empty `foreground` is a deliberate
- * clean frame and the gate limits how many of those a segment may have.
+ * so a cut that needs one names it and the prompt says it is out of focus; an empty `foreground` is a
+ * deliberate clean frame. params.foregroundLevel sets how many of each an episode has.
  */
 export function foregroundPhrase(cut, lang = 'en') {
   const fg = String(cut?.foreground || '').trim();
@@ -435,6 +506,23 @@ export function motionSentence(cut, lang = 'en') {
   return `Cue: ${t}. Action: ${a}. End: ${r}.`;
 }
 
+// Everyone on screen is alive. A model freezes whoever the prompt gives no motion, so each person other
+// than the one carrying the cut's action gets a small motion of their own (gate idle-motion).
+export const IDLE_STILL = 'still';
+// A line, a mouth that moves or a change of place is a cut's action, not an idle.
+export const IDLE_TOO_BIG = /\b(says?|speaks?|talks?|whispers?|shouts?|mouths?|chews?|walks?|crosses|leaves|enters|runs?|sits? down|stands? up)\b|[说說讲講喊嚼]|走向|离开|離開|坐下|站起/i;
+export const IDLE_MAX_CHARS = 90;
+export function idlePhrase(idle, who, lang = 'en') {
+  const text = String(idle || '').trim().replace(/[.。]+$/, '');
+  if (text === IDLE_STILL) return lang === 'zh' ? `${who}保持不动，只有呼吸与眨眼。` : `${who} holds still, only breathing and blinking.`;
+  return lang === 'zh' ? `${who}${text}。` : `${who} ${text}.`;
+}
+/** The idle motions of a cut, in on-screen order. */
+export function idleSentence(cut, whoOf, lang = 'en') {
+  const parts = (cut.characters || []).filter((id) => cut.idle?.[id]).map((id) => idlePhrase(cut.idle[id], whoOf(id), lang));
+  return parts.length ? `${parts.join(' ')} ` : '';
+}
+
 /**
  * A lock-off is written (what still moves, held), a move is written (why, when, along what, ending
  * where) — an empty camera line is read by the model as permission to drift.
@@ -614,8 +702,8 @@ export const CINEMATOGRAPHY_PRESETS = {
   'low-key': {
     label: 'low-key, practical-lit, negative space, wide open',
     framePhrase: 'low-key practical lighting',
-    videoPhrase: 'low-key cinematography lit only by practical sources in the scene, faces held in shadow and shaped by side, back and rim light with no flat fill, compositions with generous negative space and layered out-of-focus foregrounds, shallow depth of field',
-    videoPhraseZh: '低调光影，光线只来自场景内的现场光源，人物处于阴影中，以侧光、逆光、轮廓光勾勒，不打平光补光，构图留白，前景虚化增加层次，大光圈浅景深',
+    videoPhrase: 'low-key cinematography lit only by practical sources in the scene, faces held in shadow and shaped by side, back and rim light with no flat fill, compositions with generous negative space, shallow depth of field',
+    videoPhraseZh: '低调光影，光线只来自场景内的现场光源，人物处于阴影中，以侧光、逆光、轮廓光勾勒，不打平光补光，构图留白，大光圈浅景深',
     sourceHint: 'the practical in or just outside the frame that the key comes from (a lamp, a window, a screen, a sign), not a film light',
     // 包围光 / 世界光: light from the lens axis or from nowhere flattens the face and kills the shadow side.
     bannedLight: ['frontal', 'ambient'],
@@ -630,8 +718,8 @@ export const CINEMATOGRAPHY_PRESETS = {
   'sweet-romance': {
     label: 'sweet romance: soft high-key glow, backlit halo, pastel, dreamy bokeh',
     framePhrase: 'soft romantic lighting',
-    videoPhrase: 'soft romantic cinematography of a modern idol romance drama, bright airy high-key light from soft motivated sources, faces softly and flatteringly lit with a warm backlight haloing the hair, gentle low-contrast pastel grade with creamy highlights and lifted shadows, dreamy diffusion and soft halation, shot wide open with an extremely shallow depth of field, dreamy oversized creamy bokeh balls and soft out-of-focus foregrounds',
-    videoPhraseZh: '唯美浪漫偶像剧质感，明亮通透的柔光，光线来自窗光、夕阳、串灯等柔和光源，人物面部柔和明亮，暖色逆光在发丝上形成光晕，低反差粉嫩柔和色调，高光奶油般柔和，暗部通透不死黑，柔焦朦胧，全开大光圈极浅景深，梦幻的大颗奶油光斑散景与柔焦前景',
+    videoPhrase: 'soft romantic cinematography of a modern idol romance drama, bright airy high-key light from soft motivated sources, faces softly and flatteringly lit with a warm backlight haloing the hair, gentle low-contrast pastel grade with creamy highlights and lifted shadows, dreamy diffusion and soft halation, shot wide open with an extremely shallow depth of field, dreamy oversized creamy bokeh balls',
+    videoPhraseZh: '唯美浪漫偶像剧质感，明亮通透的柔光，光线来自窗光、夕阳、串灯等柔和光源，人物面部柔和明亮，暖色逆光在发丝上形成光晕，低反差粉嫩柔和色调，高光奶油般柔和，暗部通透不死黑，柔焦朦胧，全开大光圈极浅景深，梦幻的大颗奶油光斑散景',
     sourceHint: 'the soft source in or just outside the frame that the light comes from (a big window, the low sun, overcast sky, string lights, a café lamp), not a film light',
     // 底光 / 顶光: the horror and interrogation lights — they carve eye sockets and chins.
     bannedLight: ['underlight', 'top'],
@@ -685,8 +773,8 @@ export const CINEMATOGRAPHY_PRESETS = {
   'costume-dark': {
     label: 'dark historical realism: firelight and lattice windows, faces in shadow, smoke, earthy texture',
     framePhrase: 'low-key firelit period lighting',
-    videoPhrase: 'gritty low-key historical cinematography with realistic texture, lit only by candles, oil lamps, braziers, torches and daylight or moonlight through lattice windows, faces carved by side and back light and falling into deep shadow, smoke and dust hanging in shafts of light, desaturated earthy palette of ochre, umber and cold steel blue, worn fabric, weathered wood and stone, sweeping wide and extreme-wide shots with vast negative space of darkness, smoke and sky, compositions with negative space and layered out-of-focus foregrounds, shallow depth of field',
-    videoPhraseZh: '写实质感的暗黑古装影调，光线只来自蜡烛、油灯、火盆、火把，以及透过窗棂的日光或月光，人物面部被侧光与逆光雕刻，隐入浓重阴影，烟尘在光束中悬浮，低饱和的赭石、深棕与冷铁蓝色调，布料磨旧，木石斑驳，大量全景与大全景，大面积留白于黑暗、烟尘与天空之中，构图留白，前景虚化增加层次，大光圈浅景深',
+    videoPhrase: 'gritty low-key historical cinematography with realistic texture, lit only by candles, oil lamps, braziers, torches and daylight or moonlight through lattice windows, faces carved by side and back light and falling into deep shadow, smoke and dust hanging in shafts of light, desaturated earthy palette of ochre, umber and cold steel blue, worn fabric, weathered wood and stone, sweeping wide and extreme-wide shots with vast negative space of darkness, smoke and sky, compositions with negative space, shallow depth of field',
+    videoPhraseZh: '写实质感的暗黑古装影调，光线只来自蜡烛、油灯、火盆、火把，以及透过窗棂的日光或月光，人物面部被侧光与逆光雕刻，隐入浓重阴影，烟尘在光束中悬浮，低饱和的赭石、深棕与冷铁蓝色调，布料磨旧，木石斑驳，大量全景与大全景，大面积留白于黑暗、烟尘与天空之中，构图留白，大光圈浅景深',
     sourceHint: 'the period source the key comes from (a candle, an oil lamp, a brazier, a torch, daylight or moonlight through a lattice window), never an electric light',
     bannedLight: ['frontal', 'ambient'],
     bannedWhy: 'floods the face (包围光 / 世界光) — stage the person so the flame or the lattice window sits beside or behind them',
@@ -1221,6 +1309,8 @@ export function slug(name) {
 export function paramsOf(project) {
   const p = { ...DEFAULT_PARAMS, ...(project.params || {}) };
   p.thresholds = { ...DEFAULT_PARAMS.thresholds, ...(project.params?.thresholds || {}) };
+  // Named, or read from the look, so a later change of look carries the level with it.
+  if (project.params?.foregroundLevel == null) p.foregroundLevel = foregroundForLook(p);
   // The model decides how long a segment may be; an explicit param still wins, but it is then gated.
   const mode = videoModel(p);
   if (project.params?.maxSegmentSeconds == null) p.maxSegmentSeconds = mode.maxSegmentSeconds;
@@ -1619,6 +1709,7 @@ export const GATES = [
     if (!ADAPT_MODES.includes(params.adaptMode)) out.push(`params.adaptMode must be one of ${ADAPT_MODES.join(' / ')}`);
     if (!VIDEO_MODES.includes(params.video)) out.push(`params.video must be one of ${VIDEO_MODES.join(' / ')}`);
     if (!AUDIO_TRACK_MODES.includes(params.audioTrack)) out.push(`params.audioTrack must be one of ${AUDIO_TRACK_MODES.join(' / ')}`);
+    if (!FOREGROUND_LEVELS[params.foregroundLevel]) out.push(`params.foregroundLevel must be one of ${Object.keys(FOREGROUND_LEVELS).join(' / ')}`);
     if (!REGISTERS.includes(params.register)) out.push(`params.register (语体) must be one of ${REGISTERS.join(' / ')} — it decides how the lines are written and the accent the model speaks`);
     if (!REFERENCE_MODES.includes(params.references)) out.push(`params.references must be one of ${REFERENCE_MODES.join(' / ')}`);
     if (!DURATION_MODES.includes(params.videoDuration)) out.push(`params.videoDuration must be one of ${DURATION_MODES.join(' / ')}`);
@@ -3100,15 +3191,16 @@ export const GATES = [
     }
     return out;
   }),
-  gate('photography', 'storyboard', 'every cut names its lens and stop, its key-light direction, and enough foreground; the cinematography preset (named source, preferred light, wide open)', (ctx) => {
+  gate('photography', 'storyboard', 'every cut names its lens and stop, its key-light direction, and a foreground share within params.foregroundLevel; the cinematography preset (named source, preferred light, wide open)', (ctx) => {
     const { project, params } = ctx;
     const out = [];
     const kit = params.camera || DEFAULT_PARAMS.camera;
     const look = cinematographyOf(params);
-    for (const [, e] of ctx.episodes) {
+    for (const [epId, e] of ctx.episodes) {
+      let epCuts = 0, epForeground = 0;
       for (const seg of e.storyboard?.segments || []) {
         const cuts = seg.cuts || [];
-        let withForeground = 0;
+        epCuts += cuts.length;
         let withPeople = 0, shaped = 0, withBokeh = 0, wides = 0;
         cuts.forEach((c, k) => {
           const where = `${seg.id} cut ${k + 1}`;
@@ -3132,10 +3224,11 @@ export const GATES = [
           // Foreground.
           const fg = String(c.foreground || '').trim();
           if (fg) {
-            withForeground += 1;
+            epForeground += 1;
             if (frame.trim() && !frame.includes(fg)) out.push(`${where}: frame prompt must name the foreground "${fg}"`);
             if (frame.trim() && !/out of focus|foreground blur|defocus|bokeh|soft foreground/i.test(frame)) out.push(`${where}: the foreground is named but never said to be out of focus`);
           }
+          else if (c.ots) epForeground += 1;   // the near shoulder is the foreground
           if (c.foreground === undefined) out.push(`${where}: foreground is required — name what sits between the lens and the subject, or "" for a deliberately clean frame`);
           if (!look) return;
           // The cinematography preset: a named source, no banned light on a person, shot wide open.
@@ -3161,8 +3254,10 @@ export const GATES = [
         if (look && look.bokehShare && cuts.length && withBokeh < look.bokehShare * cuts.length) out.push(`${seg.id}: only ${withBokeh} of ${cuts.length} frames name their bokeh — at least ${Math.round(look.bokehShare * 100)} % must say what melts into bokeh behind or in front of the subject (params.cinematography ${params.cinematography})`);
         if (look && look.widePerSegment && cuts.length && wides < look.widePerSegment) out.push(`${seg.id}: no wide or extreme-wide cut — ${params.cinematography} needs at least ${look.widePerSegment} per segment, a 全景 / 大全景 with vast negative space`);
         if (look && withPeople && shaped < look.preferredShare * withPeople) out.push(`${seg.id}: only ${shaped} of ${withPeople} cuts with people are ${look.preferredWhat} (${look.preferredLight.join(' / ')}) — at least ${Math.round(look.preferredShare * 100)} % must (params.cinematography ${params.cinematography}); re-stage the person against the source or move the camera`);
-        // "Reasonably" means most of them: a segment of clean frames is flat.
-        if (cuts.length && withForeground * 2 < cuts.length) out.push(`${seg.id}: only ${withForeground} of ${cuts.length} cuts have a foreground element — at least half must, or the segment has no depth`);
+      }
+      const band = foregroundBand(params.foregroundLevel, epCuts);
+      if (band && (epForeground < band.min || epForeground > band.max)) {
+        out.push(`E${pad2(epId)}: ${epForeground} of ${epCuts} cuts have a foreground — params.foregroundLevel ${params.foregroundLevel} allows ${band.min}–${band.max}. Change which cuts carry one (story first), or change the level`);
       }
     }
     return out;
@@ -3553,7 +3648,7 @@ export const GATES = [
           const text = texts.get(k + 1);
           if (!text) return;   // the dialect gate reports the missing shot
           const lines = claimedLines(scene, [c]);
-          if (mode.family === 'h3' && lines.length && (c.characters || []).length >= 2 && !/does not speak|lips remain completely closed/.test(text)) out.push(`${seg.id} [Shot ${k + 1}]: two people on screen while one speaks — say the other "does not speak; ${LIPS_CLOSED}" or the lip-sync lands on the more visible face (measured 3/3 vs 2/3)`);
+          if (mode.family === 'h3' && lines.length && (c.characters || []).length >= 2 && !c.ots && !/does not speak|lips remain completely closed/.test(text)) out.push(`${seg.id} [Shot ${k + 1}]: two people on screen while one speaks — say the other "does not speak; ${LIPS_CLOSED}" or the lip-sync lands on the more visible face (measured 3/3 vs 2/3)`);
           if (sheetOf) for (const id of c.characters || []) {
             const label = sheetOf.get(id);
             if (label && !text.includes(label)) out.push(`${seg.id} shot ${k + 1}: ${characterById(project, id)?.identityEn || id} is on screen but the shot never binds ${label} — a person bound in one shot and unbound in the next becomes two people`);
@@ -3564,6 +3659,93 @@ export const GATES = [
     }
     return out;
   }),
+  gate('two-person-framing', 'storyboard', 'sheets mode, two-person segments: a single names only its person, every look has a screen direction toward the other, the sides are locked, over-the-shoulder is said', (ctx) => {
+    const { project, params } = ctx;
+    const out = [];
+    if (params.references !== 'sheets') return out;
+    const lang = videoModel(params).promptLang === 'zh' ? 'zh' : 'en';
+    for (const [, e] of ctx.episodes) {
+      for (const seg of e.storyboard?.segments || []) {
+        const people = segmentCharacters(seg);
+        if (people.length < 2) continue;
+        const cuts = seg.cuts || [];
+        const axis = isObject(seg.axis) ? seg.axis : null;
+        const labels = characterLabels(segmentReferences(project, e, seg));
+        const whoOf = (id) => labels.get(id) || identityOf(characterById(project, id));
+        const prompt = String(seg.prompt || '');
+        const texts = prompt.trim() ? shotTexts(prompt, videoModel(params).family, params.references) : new Map();
+        if (prompt.trim() && axis?.screenLeft && axis?.screenRight && !cuts.some((c) => c.axisSide === 'cross')) {
+          const line = sidesLine(axis, whoOf, lang);
+          if (!prompt.includes(line)) out.push(`${seg.id}: the prompt must lock the sides — add "${line}"`);
+        }
+        cuts.forEach((c, k) => {
+          const where = `${seg.id} cut ${k + 1}`;
+          const chars = c.characters || [];
+          const text = texts.get(k + 1);
+          if (c.ots) {
+            if (!chars.includes(c.ots) || chars.length !== 2) out.push(`${where}: ots must be one of exactly two people on screen — the one whose shoulder is near the lens`);
+            else if (text && !text.includes(overShoulderPhrase(whoOf(c.ots), axis?.screenLeft === c.ots ? 'left' : 'right', lang))) out.push(`${where}: the shot must say the over-the-shoulder — paste "${overShoulderPhrase(whoOf(c.ots), axis?.screenLeft === c.ots ? 'left' : 'right', lang)}"`);
+          } else if (chars.length === 1 && text) {
+            const phrase = onlyInFramePhrase(whoOf(chars[0]), lang);
+            if (!text.includes(phrase)) out.push(`${where}: a single must open with "${phrase}"`);
+            for (const other of people.filter((id) => id !== chars[0])) {
+              const label = labels.get(other);
+              const identity = String(characterById(project, other)?.identityEn || '').trim();
+              if ((label && new RegExp(`${label}(?!\\d)`).test(text)) || (identity && text.includes(identity))) out.push(`${where}: a single on ${chars[0]} must not describe ${other} — whoever a shot names ends up on screen`);
+            }
+          }
+          for (const id of chars) {
+            if (id === c.ots) continue;
+            const value = c.eyeline?.[id];
+            if (!value) { out.push(`${where}: eyeline.${id} is required — "screen-left|screen-right level|up|down", "away screen-left" or "task"`); continue; }
+            if (!eyelineValid(value)) { out.push(`${where}: eyeline.${id} "${value}" is not valid — "screen-left|screen-right level|up|down", "away screen-left" or "task"`); continue; }
+            const look = parseEyeline(value);
+            if (axis && !look.task && !look.away && c.axisSide !== 'cross' && (id === axis.screenLeft || id === axis.screenRight)) {
+              const toward = id === axis.screenLeft ? 'screen-right' : 'screen-left';
+              if (look.to !== toward) out.push(`${where}: ${id} stands on ${id === axis.screenLeft ? 'screen left' : 'screen right'}, so looking at the other person is ${toward}, not ${look.to} — or say "away ${look.to}"`);
+            }
+            if (text && !text.includes(eyelinePhrase(value, whoOf(id), lang))) out.push(`${where}: the shot must state the eyeline — paste "${eyelinePhrase(value, whoOf(id), lang)}"`);
+          }
+        });
+      }
+    }
+    return out;
+  }),
+  gate('idle-motion', 'storyboard', 'sheets mode: in a cut with two or more visible faces, everyone but the one carrying the action has a small motion of their own, written into the shot', (ctx) => {
+    const { project, params } = ctx;
+    const out = [];
+    if (params.references !== 'sheets') return out;
+    const lang = videoModel(params).promptLang === 'zh' ? 'zh' : 'en';
+    for (const [, e] of ctx.episodes) {
+      for (const seg of e.storyboard?.segments || []) {
+        const labels = characterLabels(segmentReferences(project, e, seg));
+        const whoOf = (id) => labels.get(id) || identityOf(characterById(project, id));
+        const prompt = String(seg.prompt || '');
+        const texts = prompt.trim() ? shotTexts(prompt, videoModel(params).family, params.references) : new Map();
+        (seg.cuts || []).forEach((c, k) => {
+          const where = `${seg.id} cut ${k + 1}`;
+          const visible = (c.characters || []).filter((id) => id !== c.ots);
+          for (const [id, idle] of Object.entries(isObject(c.idle) ? c.idle : {})) {
+            if (!(c.characters || []).includes(id)) out.push(`${where}: idle.${id} — that person is not on screen`);
+            const text = String(idle || '').trim();
+            if (text.length > IDLE_MAX_CHARS) out.push(`${where}: idle.${id} is ${text.length} chars, max ${IDLE_MAX_CHARS} — one small motion`);
+            if (IDLE_TOO_BIG.test(text)) out.push(`${where}: idle.${id} "${text}" is too big for an idle — a line, a moving mouth or a change of place is a cut's action`);
+            const phrase = idlePhrase(idle, whoOf(id), lang);
+            const shot = texts.get(k + 1);
+            if (shot && !shot.includes(phrase)) out.push(`${where}: the shot must carry the idle — paste "${phrase}"`);
+          }
+          if (visible.length < 2) return;
+          const idled = visible.filter((id) => String(c.idle?.[id] || '').trim());
+          if (idled.length < visible.length - 1) {
+            const missing = visible.filter((id) => !idled.includes(id));
+            out.push(`${where}: ${visible.length} people are visible but only ${idled.length} have an idle — give all but the one carrying the action a small motion in cut.idle (${missing.join(', ')}), or "${IDLE_STILL}" when keeping still is the performance`);
+          }
+          if (/^\s*(only|nothing but)\b|只有|只剩/i.test(String(c.cameraNote?.hold || ''))) out.push(`${where}: cameraNote.hold says only "${c.cameraNote.hold}" moves, but the people in frame move too — drop "only"`);
+        });
+      }
+    }
+    return out;
+  }),
   gate('audio-track', 'storyboard', 'Seed Audio node per segment: the derived prompt fits the model (≤ 120 s, ≤ 2048 chars, ≤ 3 voices in full mode)', (ctx) => {
     const { project, params } = ctx;
     const out = [];
@@ -3599,6 +3781,9 @@ export const GATES = [
           const action = String(c.motion?.action || '');
           if (/\b(does not|doesn't|never)\b/i.test(action) || /没有|不去|不[看说动]/.test(action)) out.push(`${where}: motion.action is phrased as what does not happen — a model cannot film an absence; write the action that happens instead (a hold, a hand that stays)`);
         });
+        const scene = (e.scenes || [])[Number(seg.sceneIndex) - 1];
+        const twoFaceLines = scene ? cuts.filter((c) => (c.characters || []).length >= 2 && !c.ots && claimedLines(scene, [c]).length).length : 0;
+        if (twoFaceLines >= 2) out.push(`${seg.id}: ${twoFaceLines} lines are played with both faces in frame — try the pattern in craft-shots.md: a two-shot once, over-the-shoulder for the exchange, a clean single for the punchline`);
         if (cuts.length >= 4 && ups >= 2 && downs === 0) out.push(`${seg.id}: every cut tightens — by mid-segment there is nowhere left to go; step back out once or hold the working size`);
       }
     }
@@ -3999,11 +4184,24 @@ function checkSpeechDirections(seg, prompt, lines, project, lang, refs = []) {
   return out;
 }
 
+/** Which image reference carries each person's face in a segment. */
+export function characterLabels(refs) {
+  const images = refs.filter((r) => r.kind === 'image');
+  const labels = new Map();
+  for (const r of images) {
+    const who = r.faceOf || (r.asset === 'sheet' || r.asset === 'headshot' ? r.entity : null);
+    if (who && !labels.has(who)) labels.set(who, r.label);
+  }
+  for (const r of images.filter((x) => x.asset === 'headshot' || x.faceOf)) labels.set(r.faceOf || r.entity, r.label);
+  return labels;
+}
+
 function shotParagraphs(prompt) {
   const map = new Map();
   const re = /\[Shot (\d+)\]\s*([\s\S]*?)(?=\n\[Shot \d+\]|\n\s*\n|$)/g;
   let m;
-  while ((m = re.exec(prompt))) map.set(Number(m[1]), m[2].trim());
+  // The soundscape line also says "at [Shot 1]": the shot's own paragraph comes first and is the one kept.
+  while ((m = re.exec(prompt))) if (!map.has(Number(m[1]))) map.set(Number(m[1]), m[2].trim());
   return map;
 }
 
@@ -4215,7 +4413,7 @@ export function seedStoryboard(project, episode) {
   });
   return {
     ...episode,
-    storyboard: { plan: segmentPlan(project, episode), seedScenes, visualPlans, segments: [] },
+    storyboard: { plan: { ...segmentPlan(project, episode), foregroundLevel: paramsOf(project).foregroundLevel }, seedScenes, visualPlans, segments: [] },
   };
 }
 
@@ -4503,7 +4701,17 @@ export function promptSkeleton(project, episode, segmentId) {
   const clipMusic = params.audioTrack === 'post' ? '' : musicOf(sound).intent;
   // Who else is on screen while `speaker` has a line: the H3 idiom keeps the lip-sync off them.
   // In keyframes mode the @imageN labels are frames, so a person is named by identity instead.
-  const othersOnScreen = (c, speaker) => (c.characters || []).filter((id) => id !== speaker).map((id) => (params.references === 'sheets' && sheetLabels.get(id) ? `the person in ${sheetLabels.get(id)}` : identityOf(characterById(project, id))));
+  const framingLabels = characterLabels(allRefs);
+  const whoOf = (id) => framingLabels.get(id) || identityOf(characterById(project, id));
+  const framingLang = videoModel(params).promptLang === 'zh' ? 'zh' : 'en';
+  const idleOf = (c) => (params.references === 'sheets' ? idleSentence(c, whoOf, framingLang) : '');
+  const framingOf = (c) => (params.references === 'sheets' ? shotFraming(c, seg, whoOf, framingLang) : '');
+  const sidesOf = () => {
+    const axis = isObject(seg.axis) ? seg.axis : null;
+    if (params.references !== 'sheets' || !axis?.screenLeft || !axis?.screenRight || cuts.some((c) => c.axisSide === 'cross')) return [];
+    return [sidesLine(axis, whoOf, framingLang)];
+  };
+  const othersOnScreen = (c, speaker) => (c.characters || []).filter((id) => id !== speaker && id !== c.ots).map((id) => (params.references === 'sheets' && sheetLabels.get(id) ? `the person in ${sheetLabels.get(id)}` : identityOf(characterById(project, id))));
   let video;
   if (mode.family === 'h3') {
     const sheets = params.references === 'sheets';
@@ -4519,14 +4727,14 @@ export function promptSkeleton(project, episode, segmentId) {
       // In sheets mode the cut's own `frame` goes into the prompt and already carries the lens, the
       // light and the foreground (gated there), so only the shot size and camera move are added.
       const body = sheets
-        ? `${c.frame || '…'} ${SIZES[c.size] || c.size}, ${c.camera}.`
+        ? `${framingOf(c)}${c.frame || '…'} ${SIZES[c.size] || c.size}, ${c.camera}.`
         : `… anchor on @image${k + 1} · ${SIZES[c.size] || c.size}, ${c.camera}, ${cameraPhrase(c, params)}. ${lightPhrase(c)}.${foregroundPhrase(c)}`;
-      return `${head}${body} ${motionSentence(c)} ${cameraClause(c)} ${d}${lips}`.replace(/\s+/g, ' ').trim();
+      return `${head}${body} ${motionSentence(c)} ${idleOf(c)}${cameraClause(c)} ${d}${lips}`.replace(/\s+/g, ' ').trim();
     });
     // Keyframes are aligned by the alignment line; the voices are named either way.
     const voiceLegend = allRefs.filter((r) => r.kind !== 'image').map((r) => `${r.label} is ${r.use}.`);
     const lead = sheets
-      ? allRefs.map((r) => `${r.label} is ${r.use}.`)
+      ? [...allRefs.map((r) => `${r.label} is ${r.use}.`), ...sidesOf()]
       : [h3AlignmentLine(cuts), ...voiceLegend];
     const look = sheets ? [`Look: ${lookOf()}.`, ''] : [];
     const soundscape = [sound.ambience || '…', ...cuts.map((c, k) => (sfxOf(k) ? `at [Shot ${k + 1}] ${sfxOf(k)}` : '')).filter(Boolean)].join('; ');
@@ -4537,18 +4745,18 @@ export function promptSkeleton(project, episode, segmentId) {
       // Wan's prompt is Chinese: the lens and the light direction translate, the note and the
       // foreground are the author's English prose, so they are left as blanks to write in Chinese.
       const shot = `${cameraPhrase(c, params, 'zh')}。${LIGHT_DIRECTIONS_ZH[c.light?.direction] || '…'}，…。前景：${c.foreground ? '…（虚化）' : '无'}。`;
-      return [`${wanShotHeader(cuts, k)}…${shot}${motionSentence(c, 'zh')}${cameraClause(c, 'zh')}`, ...talk].join('\n');
+      return [`${wanShotHeader(cuts, k)}${framingOf(c)}…${shot}${motionSentence(c, 'zh')}${idleOf(c)}${cameraClause(c, 'zh')}`, ...talk].join('\n');
     });
     const sfxAll = cuts.map((c, k) => (sfxOf(k) ? `镜头${k + 1}：${sfxOf(k)}` : '')).filter(Boolean).join('；');
     video = [
-      params.references === 'sheets' ? wanSheetLegendLine(allRefs) : wanLegendLine(cuts, allRefs), '',
+      params.references === 'sheets' ? wanSheetLegendLine(allRefs) : wanLegendLine(cuts, allRefs), ...sidesOf(), '',
       ...blocks.flatMap((b) => [b, '']),
       ...(cine && params.references === 'sheets' ? [`画面：${cine.videoPhraseZh}${params.lookPhraseZh ? `，${params.lookPhraseZh}` : ''}。`, ''] : []),
       ...(grammarLines(seg, params, 'zh').length ? [...grammarLines(seg, params, 'zh'), ''] : []),
       `音频：对白为${accent || '…'}，环境音${sound.ambience || '…'}${sfxAll ? `；${sfxAll}` : ''}${clipMusic ? `；配乐：${clipMusic}` : params.audioTrack === 'post' ? '；无配乐' : ''}。${params.subtitles ? '' : `${NO_SUBTITLES.zh}。`}`,
     ].join('\n');
   } else if (params.references === 'sheets') {
-    const legend = allRefs.map((r) => `${r.label} is ${r.use}.`);
+    const legend = [...allRefs.map((r) => `${r.label} is ${r.use}.`), ...sidesOf()];
     const shots = cuts.map((c, k) => {
       const talk = dialogue[k].map((l) => {
         const base = `${l.speakerRef}${l.direction ? `, ${l.direction},` : ''} says: ${l.line}`;
@@ -4559,7 +4767,7 @@ export function promptSkeleton(project, episode, segmentId) {
         return `${base} while ${others.join(' and ')} ${others.length > 1 ? 'do' : 'does'} not speak, ${LIPS_CLOSED}`;
       }).join(' ');
       // The frame already carries the lens, the light and the foreground — do not repeat them.
-      return `Shot ${k + 1} (${starts[k].toFixed(1)}–${(starts[k] + Number(c.seconds)).toFixed(1)} s, ${SIZES[c.size] || c.size}, ${c.camera}): ${c.frame || '…'} ${motionSentence(c)} ${cameraClause(c)} ${talk}`.replace(/\s+/g, ' ').trim();
+      return `Shot ${k + 1} (${starts[k].toFixed(1)}–${(starts[k] + Number(c.seconds)).toFixed(1)} s, ${SIZES[c.size] || c.size}, ${c.camera}): ${framingOf(c)}${c.frame || '…'} ${motionSentence(c)} ${idleOf(c)}${cameraClause(c)} ${talk}`.replace(/\s+/g, ' ').trim();
     });
     const sfxAll = cuts.map((c, k) => (sfxOf(k) ? `shot ${k + 1}: ${sfxOf(k)}` : '')).filter(Boolean).join('; ');
     video = [...legend, '', ...shots, '', ...actionLine, `Look: ${lookOf()}. Maintain continuity in character identities, clothing, prop ownership, scene layout and the camera axis across every shot.`, `Sound: ${sound.ambience || '…'}${sfxAll ? `; ${sfxAll}` : ''}.${accent && dialogue.flat().length ? ` All dialogue in ${accent}.` : ''}${clipMusic ? ` Music: ${clipMusic}.` : ' No music.'}${params.subtitles ? '' : ` ${NO_SUBTITLES.en[0].toUpperCase()}${NO_SUBTITLES.en.slice(1)}.`}`].join('\n');
@@ -5098,6 +5306,7 @@ export function initProject(opts) {
       lookPhrase: opts.look || DEFAULT_PARAMS.lookPhrase,
       style: opts.style || DEFAULT_PARAMS.style,
       imagePromptLang: opts.imageLang || DEFAULT_PARAMS.imagePromptLang,
+      ...(opts.foreground ? { foregroundLevel: opts.foreground } : {}),
       // Picked from the genre unless named; `--cinematography none` opts out.
       cinematography: cine,
       // Named, or read from the genre only when it names an action style outright.
@@ -5253,7 +5462,7 @@ function main(argv) {
       adapt: flag(rest, '--adapt'), ratio: flag(rest, '--ratio'), video: flag(rest, '--video'), style: flag(rest, '--style'), lang: flag(rest, '--lang'),
       resolution: flag(rest, '--resolution'), accent: flag(rest, '--accent'),
       references: flag(rest, '--references'), duration: flag(rest, '--duration'), look: flag(rest, '--look'),
-      register: flag(rest, '--register'), imageLang: flag(rest, '--image-lang'),
+      register: flag(rest, '--register'), imageLang: flag(rest, '--image-lang'), foreground: flag(rest, '--foreground'),
       cinematography: flag(rest, '--cinematography'), action: flag(rest, '--action'), violence: flag(rest, '--violence'), grammar: flag(rest, '--grammar'), comedy: flag(rest, '--comedy'), composition: flag(rest, '--composition'), story: flag(rest, '--story'), market: flag(rest, '--market'), format: flag(rest, '--format'),
       source: flag(rest, '--source'), sourcePath: flag(rest, '--source-path'),
     });

package/skill/wji/SKILL.md

@@ -487,11 +487,15 @@ wji npc doc apply @mika @mika.md --dry-run     # see the diff, then without --dr
 - `npc create` needs NPC City spawn permission on the account (a 403 says so);
   only an admin can grant it. Admin actions — spawn permission, featured / hero
   slider, moderation — are not in `wji`.
+- Handles are 2–32 of a-z 0-9 . _ -; NPC City reserves system and brand names (admin, official,
+  npccity, wji, backreel, …) anywhere in the handle — `wji npc handle <h>` says why one is refused.
+  An NPC created without `--image` has no avatar (NPC City shows its initials).
 - `npc transfer send <npc> --to <email>` offers the NPC to someone; they
   `npc transfer accept <id>` within 7 days. You lose it on acceptance.
 
 **Backreel posts** are your film / project pages. `create` always makes a
-draft; publishing needs a cover, media or an episode.
+draft; publishing needs a cover, media or an episode. Jobs, bids and contracts
+(`wji br job …`, `wji br contract …`) are covered by the `backreel` skill.
 
 ```bash
 wji backreel list                              # yours, drafts included; --all for published posts