@milenyumai/film-kit 2.3.0 → 2.3.1

package/README.md

@@ -180,7 +180,8 @@ Outputs:
 Rules:
 
 - `@character1` is used once to create a 16:9 character sheet prompt with front, back, side, three-quarter, and face close-up views.
-- Each `SHOTNN.md` includes a `GPT IMAGE 2 STORYBOARD PROMPT`; the generated shot storyboard controls composition, blocking, camera, timing, and editorial phase order only.
+- Each `SHOTNN.md` includes a professional `GPT IMAGE 2 STORYBOARD PROMPT`; the generated shot storyboard controls composition, blocking, camera, timing, and editorial phase order only.
+- Storyboard prompts use production-board grammar: rough black-and-white pencil panels, strong silhouettes, visible body/camera momentum, and optional color-coded planning annotations. Seedance is instructed to follow the panel order while ignoring arrows, notes, labels, and timestamps in the rendered video.
 - Seedance provider-facing tokens map generated character sheets first (`@Image1`, `@Image2`, ...) and the generated shot storyboard next. Legacy lowercase aliases remain documented in runtime text.
 - Phase budget: 4-6s uses 1-2 phases, 7-10s uses 2-3 phases, and 11-15s uses 3-4 phases.
 - 5+ storyboard phases are split into multiple `SHOTNN.md` files by default.

package/build/lib/storyboard-reference/adapters/seedance20.js

@@ -44,13 +44,13 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
     }
     buildPrompt(input) {
         const audioPlan = buildAudioPlan(input);
+        const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
+        const storyboardToken = storyboardEntry?.token ?? "@Image2";
         const continuityInstruction = input.continuityMode === "continuous-shot"
             ? "No scene cuts throughout, one continuous shot."
-            : "Use only the planned storyboard phase transitions below; do not add unplanned cuts, extra scene jumps, or new locations.";
+            : `Follow the generated storyboard panels in ${storyboardToken} left-to-right, top-to-bottom as the exact visual beat order. Do not reinterpret actions, poses, camera angles, emotional progression, frame variety, or the final pose. Compress the planned sequence into the full duration as concise motion snapshots; use only storyboard-motivated cuts, match cuts, whip transitions, or camera moves, and do not add unplanned cuts, extra scene jumps, or new locations.`;
         const characterEntries = this.getMappingEntries(input, "character_identity");
-        const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
         const characterTokenText = characterEntries.map(entry => entry.token).join(", ") || "@Image1";
-        const storyboardToken = storyboardEntry?.token ?? "@Image2";
         const promptText = `${this.formatCharacterRoleLine(input)}
 ${this.formatStoryboardRoleLine(input)}
 
@@ -63,7 +63,7 @@ ${input.request.brief}
 ${formatPhaseLines(input.interpretation.phases)}
 
 [GPT IMAGE 2 STORYBOARD SOURCE]
-Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source.
+Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source. Treat colored arrows, panel labels, and lens notes as planning annotations only; never render arrows, notes, labels, timestamps, or storyboard text into the video.
 
 [CAMERA]
 ${input.interpretation.cameraPlan.framing}, ${input.interpretation.cameraPlan.movement}, ${input.interpretation.cameraPlan.lens}, ${input.interpretation.cameraPlan.stabilization}. Preserve ${input.interpretation.cameraPlan.screenDirection}.
@@ -78,9 +78,9 @@ Ambience: ${audioPlan.ambience.join(", ")}.
 Music: NONE.
 
 [CONTINUITY]
-Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard. Storyboard text, panel borders, watermark, logo, and alternate character design are never identity sources.
+Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging, shot order, pose logic, camera variety, emotional progression, and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard. Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources and must not appear in the rendered video.
 
-Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps.`;
+Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders, colored arrows, annotation marks, lens notes, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps.`;
         const output = {
             model: this.model,
             displayName: getDisplayName(this.model),
@@ -115,7 +115,11 @@ Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders,
                 && characterTokens.every(token => output.promptText.includes(token))
                 && /exact character identity reference/i.test(output.promptText),
             usesStoryboardToken: output.promptText.includes(storyboardToken) && /shot storyboard reference/i.test(output.promptText),
-            blocksStoryboardIdentitySources: /Storyboard text, panel borders, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
+            followsStoryboardOrder: continuityMode === "continuous-shot"
+                ? hasNoCutsRule
+                : /left-to-right, top-to-bottom/i.test(output.promptText)
+                    && /Do not reinterpret actions, poses, camera angles, emotional progression/i.test(output.promptText),
+            blocksStoryboardIdentitySources: /Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
             continuityMode: continuityMode === "continuous-shot"
                 ? hasNoCutsRule
                 : !hasNoCutsRule && /planned storyboard phase transitions/i.test(output.promptText),

package/build/lib/storyboard-reference/prompt-bundle-builder.js

@@ -117,18 +117,34 @@ function buildStoryboardImagePrompt(input) {
     const externalGuideText = assets.storyboards.length > 0
         ? `Use external storyboard guide tokens ${assets.storyboards.map(storyboard => storyboard.token).join(", ")} only for composition, blocking, camera direction, timing, and action rhythm.`
         : "No external storyboard guide is required; infer the board from the screenplay brief, continuity notes, and visual world.";
+    const phaseDirection = interpretation.phases
+        .map(phase => `Panel ${phase.index}: ${phase.job}; ${phase.subjectAction}; camera behavior: ${phase.cameraBehavior}; background behavior: ${phase.backgroundBehavior}.`)
+        .join(" ");
+    const continuityStyle = interpretation.phases.length <= 1
+        ? "Because this is a single uninterrupted beat, show one decisive action moment with a clear entry pose, motion direction, and final body intention inside the same panel."
+        : "Read panels left-to-right, top-to-bottom as a planned visual beat sequence. Each panel must show a distinct body pose, camera size/angle, movement logic, and emotional escalation, not decorative micro-poses.";
     return {
         shotId,
         outputPath: `${request.outputDir}/storyboard-prompts/${shotId}-GPT-IMAGE-2-STORYBOARD.md`,
         provider: "gpt-image-2",
         aspectRatio: "16:9",
         panelCount: interpretation.panelCount,
-        style: "realistic-production-storyboard",
+        style: "professional-production-storyboard",
         characterSheetIds,
         externalStoryboardGuideIds,
         previousShotHandoff: input.previousShotHandoff,
         nextShotHandoff: input.nextShotHandoff,
-        promptText: `Create a professional 16:9 realistic production storyboard image for ${shotId} with exactly ${interpretation.panelCount} readable panel${interpretation.panelCount === 1 ? "" : "s"}. Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, body proportions, wardrobe, accessories, and visible props. ${externalGuideText} The scene brief is: ${request.brief}. Continue from the previous handoff: ${input.previousShotHandoff}. End on the next handoff: ${input.nextShotHandoff}. Show the camera plan clearly: ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}, preserving ${interpretation.cameraPlan.screenDirection}. Maintain the same environment, lighting, atmosphere, color grade, foreground, midground, and background continuity: ${interpretation.visualWorld.environment}; ${interpretation.visualWorld.lighting}; ${interpretation.visualWorld.atmosphere}. Each panel must show only the phase action needed for the shot, with clean blocking, motivated eyelines, stable scale, readable silhouettes, and practical production-board detail. Do not create final render polish, alternate character designs, text, captions, labels, panel numbers, watermarks, logos, decorative borders, extra scene cuts, or new locations.`
+        promptText: `Create a professional 16:9 production storyboard page for ${shotId} with exactly ${interpretation.panelCount} cinematic panel${interpretation.panelCount === 1 ? "" : "s"}. Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, body proportions, wardrobe, accessories, and visible props. ${externalGuideText}
+
+Storyboard drawing style: raw contemporary film storyboard, black-and-white rough pencil linework for the artwork only, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished choreography-previsualization feel, not polished concept art or final render.
+
+Panel direction: ${continuityStyle} The scene brief is: ${request.brief} Previous handoff: ${input.previousShotHandoff}. Next handoff: ${input.nextShotHandoff}. Planned panel actions: ${phaseDirection}
+
+Camera and staging: show ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}; preserve ${interpretation.cameraPlan.screenDirection}. Use cinematic camera variety only when motivated by the beat: handheld energy, push-in, orbit, overhead, low angle, side silhouette, insert, aggressive close-up, long-lens compression, or extreme negative space. Maintain the same environment, lighting, atmosphere, foreground, midground, and background continuity: ${interpretation.visualWorld.environment}; ${interpretation.visualWorld.lighting}; ${interpretation.visualWorld.foreground}; ${interpretation.visualWorld.midground}; ${interpretation.visualWorld.background}; ${interpretation.visualWorld.atmosphere}.
+
+Annotation color system: red arrows for body movement, blue arrows for camera movement, green marks for framing/composition, orange marks for lighting direction, purple marks for vocal or emotional emphasis when relevant, black text only for very short lens notes and panel labels. No timestamps.
+
+Every panel must contain visible momentum or clear behavioral change: gaze shift, breath, weight transfer, contact with ground/prop, fabric motion, hand tension, or a readable pose transition. Avoid static standing poses unless the brief requires a deliberately held beat. Keep the location minimal and readable; do not add new characters, new locations, alternate wardrobe, alternate identity, logos, watermarks, decorative borders, final-render polish, or photorealistic video frames.`
     };
 }
 function isImageReference(asset) {

package/build/lib/storyboard-reference/types.d.ts

@@ -128,7 +128,7 @@ export interface StoryboardImagePrompt {
     provider: "gpt-image-2";
     aspectRatio: "16:9";
     panelCount: number;
-    style: "realistic-production-storyboard";
+    style: "professional-production-storyboard";
     characterSheetIds: string[];
     externalStoryboardGuideIds: string[];
     previousShotHandoff: string;

package/content/skills/storyboard-reference/SKILL.md

@@ -39,7 +39,9 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
 - hard cap: max 4 panels/phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
-- target detail: 160-240 words, concrete blocking and camera language, no decorative prose
+- target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
+- storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
 - continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
 
 The shot storyboard prompt must use the character sheet reference as the only identity source. Optional external storyboard guide images may inform composition and timing only.
@@ -74,6 +76,8 @@ Seedance 2.0:
 - Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
 - Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
 - The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
+- Follow generated storyboard panels left-to-right, top-to-bottom. Do not reinterpret the action, pose logic, camera angle, emotional progression, frame variety, or final pose.
+- Treat storyboard arrows, labels, lens notes, and colored marks as planning annotations only; never render them into the video.
 - Use explicit timeline phases when the storyboard has multiple beats.
 - Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
 - For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milenyumai/film-kit",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Single-package Film-Kit distribution with preset-driven cinematic runtime setup for OpenAI Codex App, Claude Code, Cursor, Copilot, and Antigravity.",
   "type": "module",
   "main": "./build/index.js",

package/packages/gpt-image-smart/content/skills/storyboard-reference/SKILL.md

@@ -39,7 +39,9 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
 - hard cap: max 4 panels/phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
-- target detail: 160-240 words, concrete blocking and camera language, no decorative prose
+- target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
+- storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
 - continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
 
 The shot storyboard prompt must use the character sheet reference as the only identity source. Optional external storyboard guide images may inform composition and timing only.
@@ -74,6 +76,8 @@ Seedance 2.0:
 - Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
 - Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
 - The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
+- Follow generated storyboard panels left-to-right, top-to-bottom. Do not reinterpret the action, pose logic, camera angle, emotional progression, frame variety, or final pose.
+- Treat storyboard arrows, labels, lens notes, and colored marks as planning annotations only; never render them into the video.
 - Use explicit timeline phases when the storyboard has multiple beats.
 - Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
 - For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.

package/packages/hybrid/content/skills/storyboard-reference/SKILL.md

@@ -39,7 +39,9 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
 - hard cap: max 4 panels/phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
-- target detail: 160-240 words, concrete blocking and camera language, no decorative prose
+- target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
+- storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
 - continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
 
 The shot storyboard prompt must use the character sheet reference as the only identity source. Optional external storyboard guide images may inform composition and timing only.
@@ -74,6 +76,8 @@ Seedance 2.0:
 - Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
 - Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
 - The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
+- Follow generated storyboard panels left-to-right, top-to-bottom. Do not reinterpret the action, pose logic, camera angle, emotional progression, frame variety, or final pose.
+- Treat storyboard arrows, labels, lens notes, and colored marks as planning annotations only; never render them into the video.
 - Use explicit timeline phases when the storyboard has multiple beats.
 - Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
 - For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.

package/packages/hybrid-smart/content/skills/storyboard-reference/SKILL.md

@@ -39,7 +39,9 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
 - hard cap: max 4 panels/phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
-- target detail: 160-240 words, concrete blocking and camera language, no decorative prose
+- target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
+- storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
 - continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
 
 The shot storyboard prompt must use the character sheet reference as the only identity source. Optional external storyboard guide images may inform composition and timing only.
@@ -74,6 +76,8 @@ Seedance 2.0:
 - Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
 - Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
 - The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
+- Follow generated storyboard panels left-to-right, top-to-bottom. Do not reinterpret the action, pose logic, camera angle, emotional progression, frame variety, or final pose.
+- Treat storyboard arrows, labels, lens notes, and colored marks as planning annotations only; never render them into the video.
 - Use explicit timeline phases when the storyboard has multiple beats.
 - Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
 - For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.

package/packages/multi/content/skills/storyboard-reference/SKILL.md

@@ -39,7 +39,9 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
 - hard cap: max 4 panels/phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
-- target detail: 160-240 words, concrete blocking and camera language, no decorative prose
+- target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
+- storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
 - continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
 
 The shot storyboard prompt must use the character sheet reference as the only identity source. Optional external storyboard guide images may inform composition and timing only.
@@ -74,6 +76,8 @@ Seedance 2.0:
 - Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
 - Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
 - The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
+- Follow generated storyboard panels left-to-right, top-to-bottom. Do not reinterpret the action, pose logic, camera angle, emotional progression, frame variety, or final pose.
+- Treat storyboard arrows, labels, lens notes, and colored marks as planning annotations only; never render them into the video.
 - Use explicit timeline phases when the storyboard has multiple beats.
 - Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
 - For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.

package/packages/studio/content/skills/storyboard-reference/SKILL.md

@@ -39,7 +39,9 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 - panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
 - hard cap: max 4 panels/phases per shot unless the configured project cap is lower
 - split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
-- target detail: 160-240 words, concrete blocking and camera language, no decorative prose
+- target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
+- storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
+- annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
 - continuity: include previous shot handoff, next shot handoff, shared `visual_world`, screen direction, lighting, and action rhythm
 
 The shot storyboard prompt must use the character sheet reference as the only identity source. Optional external storyboard guide images may inform composition and timing only.
@@ -74,6 +76,8 @@ Seedance 2.0:
 - Map the generated shot storyboard to the next image token, for example one character means `@Image2`, two characters means `@Image3`.
 - Character image tokens control identity, face, body proportions, wardrobe, accessories, and visible props.
 - The storyboard token controls composition, blocking, camera direction, timing, action rhythm, and phase order only.
+- Follow generated storyboard panels left-to-right, top-to-bottom. Do not reinterpret the action, pose logic, camera angle, emotional progression, frame variety, or final pose.
+- Treat storyboard arrows, labels, lens notes, and colored marks as planning annotations only; never render them into the video.
 - Use explicit timeline phases when the storyboard has multiple beats.
 - Use `No scene cuts throughout, one continuous shot` only for a true single uninterrupted camera move.
 - For multi-phase storyboard prompts, use only the planned phase transitions and do not add unplanned cuts.