@milenyumai/film-kit 2.2.1 → 2.3.0

package/README.md

@@ -55,18 +55,18 @@ After the first run, Film-Kit writes `film-kit.config.json` and uses that file a
 
 In Codex-enabled projects, all presets now include an optional `/codex-images` still phase after a successful `/generate`. It is always opt-in and never auto-starts.
 
-Storyboard-reference prompt generation is also available when you have a character reference image, storyboard reference image, and brief. It produces model-specific prompt bundles without requiring start/end frames.
+Storyboard-reference prompt generation is also available when you have a character reference image and brief. It creates one-time GPT Image 2 character sheet prompts, per-shot GPT Image 2 storyboard prompts, and model-specific video prompt bundles without requiring start/end frames. A storyboard guide image can still be supplied, but it is optional.
 
 ## Presets
 
-| Preset | Purpose | Supported video model surface | Default notes |
-|---|---|---|---|
-| `single` | Single-agent prompt runtime | `veo31`, `kling-3.0`, `seedance-2.0` | Defaults to all supported platforms |
-| `multi` | Lead-directed multi-agent shot generation | `veo31`, `kling-3.0`, `seedance-2.0` | Defaults to `maxTeammates=5`, `batchSize=4` |
-| `hybrid` | Nano Banana still generation + GPT Image 2 companion metadata + fixed Kling video runtime | fixed `kling-3.0` | No `--model` flag |
-| `hybrid-smart` | Nano Banana still generation + GPT Image 2 companion metadata + dialogue-aware Veo/Kling routing | fixed smart route | No `--model` flag |
-| `gpt-image-smart` | GPT Image 2 still generation + dialogue-aware Veo/Kling routing | fixed smart route | Defaults to `size=2048x1152`, `quality=medium`, `format=png` |
-| `studio` | Scenario-to-render pipeline with fal.ai render-stage configuration plus GPT Image 2 companion metadata | `veo31`, `kling-3.0`, `seedance-2.0` | Includes refs dir and fal model configuration |
+| Preset | Purpose | Video/model surface | Storyboard / reference support | Default notes |
+|---|---|---|---|---|
+| `single` | Single-agent prompt runtime | `veo31`, `kling-3.0`, `seedance-2.0` | Can store `storyboard-reference` config and ships the storyboard skill/workflow | Defaults to all supported platforms |
+| `multi` | Lead-directed multi-agent shot generation | `veo31`, `kling-3.0`, `seedance-2.0` | Best fit for Seedance storyboard-reference teams: character sheets, shot storyboard prompts, team-plan metadata, handoff notes | Defaults to `maxTeammates=5`, `batchSize=4` |
+| `hybrid` | Nano Banana still generation + GPT Image 2 companion metadata + fixed Kling video runtime | fixed `kling-3.0` | Ships the updated storyboard skill/workflow for prompt planning; video runtime stays Kling-focused | No `--model` flag |
+| `hybrid-smart` | Nano Banana still generation + GPT Image 2 companion metadata + dialogue-aware Veo/Kling routing | fixed smart route | Ships the updated storyboard skill/workflow and GPT Image companion metadata | No `--model` flag |
+| `gpt-image-smart` | GPT Image 2 still generation + dialogue-aware Veo/Kling routing | fixed smart route | GPT Image 2-first preset; includes the character-sheet + per-shot storyboard prompt contract | Defaults to `size=2048x1152`, `quality=medium`, `format=png` |
+| `studio` | Scenario-to-render pipeline with fal.ai render-stage configuration plus GPT Image 2 companion metadata | `veo31`, `kling-3.0`, `seedance-2.0` | Full pipeline option for Seedance storyboard-reference plus refs dir and render-stage config | Includes refs dir and fal model configuration |
 
 ## Model Support
 
@@ -81,9 +81,9 @@ Storyboard-reference prompt generation is also available when you have a charact
 - Supported in `single`, `multi`, and `studio`
 - Runtime now includes Seedance-specific prompt guidance
 - Seedance prompt behavior emphasizes:
-  - multimodal role assignment such as `@image1`, `@video1`, `@audio1`
-  - first-frame anchoring like `Use @image1 as the first frame of the scene.`
-  - continuous-shot wording such as `No scene cuts throughout, one continuous shot.`
+  - multimodal role assignment such as `@Image1` / `@image1`, `@video1`, `@audio1`
+  - first-frame anchoring like `Use @Image1 as the first frame of the scene.`
+  - continuous-shot wording such as `No scene cuts throughout, one continuous shot.` only for uninterrupted camera moves
   - explicit extension syntax such as `Extend @video1 by 5s`
   - separation of identity reference vs camera reference vs action reference
 
@@ -122,12 +122,34 @@ When the active model is not Kling, generated runtime files intentionally render
 
 ## Storyboard Reference Mode
 
-Use this mode when the source material is a character reference image plus a storyboard image rather than explicit start/end frames.
+Use this mode when the source material is a character reference image plus a brief rather than explicit start/end frames. Film-Kit first prepares character-sheet prompts, then per-shot storyboard prompts. Optional storyboard images can be supplied as loose composition/timing guides.
+
+Initialize a Seedance storyboard-reference runtime:
+
+```bash
+npx @milenyumai/film-kit init \
+  --preset multi \
+  --model seedance-2.0 \
+  --reference-mode storyboard-reference \
+  --max-storyboard-phases 4
+```
+
+For a GPT Image 2-first workflow, initialize the smart image preset with the same reference mode:
+
+```bash
+npx @milenyumai/film-kit init \
+  --preset gpt-image-smart \
+  --reference-mode storyboard-reference \
+  --gpt-image-size 2048x1152 \
+  --gpt-image-quality medium \
+  --gpt-image-format png
+```
+
+Generate prompt bundle files directly:
 
 ```bash
 npx @milenyumai/film-kit generate-storyboard \
   --character-ref ./refs/character.png \
-  --storyboard-ref ./refs/storyboard.png \
   --brief ./scenario.md \
   --models veo31,seedance-2.0,kling-3.0 \
   --duration 8 \
@@ -135,20 +157,49 @@ npx @milenyumai/film-kit generate-storyboard \
   --output-dir ./outputs
 ```
 
+Add an external storyboard guide only when you already have one:
+
+```bash
+npx @milenyumai/film-kit generate-storyboard \
+  --character-ref ./refs/character.png \
+  --storyboard-ref ./refs/storyboard-guide.png \
+  --brief ./scenario.md \
+  --models seedance-2.0 \
+  --duration 8
+```
+
 Outputs:
 
 - `outputs/storyboard-reference-plan.json`
+- `outputs/reference-prep/CHARACTER-SHEET-*.md`
+- `outputs/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md`
 - `outputs/prompt-bundles/SHOTNN.bundle.json`
 - `outputs/shots/SHOTNN.md`
 - `outputs/reports/STORYBOARD-REFERENCE-QA.md`
 
 Rules:
 
-- `@character1` is the identity lock.
-- `@storyboard1` controls composition, blocking, camera, timing, and editorial phase order only.
-- 5+ storyboard phases are split into multiple `SHOTNN.md` files.
+- `@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.
+- 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.
+- Multi-phase storyboards use planned phase transitions instead of forcing `No scene cuts throughout, one continuous shot.`
 - Existing start/end workflows stay unchanged and remain the default.
 
+CLI flags for direct storyboard bundle generation:
+
+| Flag | Description |
+|---|---|
+| `--character-ref` | Required character identity reference image path or URL. Repeatable or comma-separated |
+| `--storyboard-ref` | Optional storyboard guide image path or URL. Repeatable or comma-separated |
+| `--brief` | Inline brief text or a path to a brief/scenario file |
+| `--models` | Comma-separated target models: `veo31`, `seedance-2.0`, `kling-3.0` |
+| `--duration` | Duration in seconds per generated shot. Seedance provider range is 4-15 seconds |
+| `--aspect` | `16:9`, `9:16`, or `1:1` |
+| `--storyboard-panel-count-hint` | Optional total panel/phase hint. 5+ phases are split when overload splitting is enabled |
+| `--max-storyboard-phases` | Upper bound per shot. Default: `4` |
+
 ## CLI
 
 Base command:

package/build/index.d.ts

@@ -2,4 +2,4 @@ export { configureFilmKit, detectFilmKitPreset, FILM_KIT_CONFIG_FILE, FILM_KIT_P
 export { configureAgents } from "./lib/configure.js";
 export { buildStoryboardReferencePromptBundles, normalizeVideoPromptRequest, renderShotMarkdown, writeStoryboardReferenceOutputs } from "./lib/storyboard-reference/index.js";
 export type { AgentConfigOptions, ConfigureFilmKitResult, ConfigureResult, FilmKitConfigFile, FilmKitConfigOptions, FilmKitPreset, GptImageFormat, GptImageQuality, GptImageSize, HybridAspectRatio, KlingPreset, NanoBananaImageSize, ReferenceMode, StoryboardReferenceConfig, SupportedModel, SupportedPlatform } from "./lib/types.js";
-export type { ModelPromptOutput, PromptBundle, ReferenceAsset, StoryboardReferenceBuildResult, StoryboardReferenceWriteResult, VideoPromptRequest } from "./lib/storyboard-reference/index.js";
+export type { CharacterReferenceSheetPrompt, ModelPromptOutput, ModelRouteMetadata, PromptBundle, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, SeedanceContinuityMode, ShotHandoffNote, StoryboardImagePrompt, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoPromptRequest } from "./lib/storyboard-reference/index.js";

package/build/lib/cli.js

@@ -492,7 +492,7 @@ Usage:
   npx @milenyumai/film-kit init --preset hybrid-smart --kling-preset balanced --gpt-image-size 2048x1152
   npx @milenyumai/film-kit init --preset gpt-image-smart --gpt-image-size 2048x1152 --gpt-image-quality medium
   npx @milenyumai/film-kit init --preset studio --refs-dir ./refs --fal-video-model fal-ai/kling-video/v3/pro/image-to-video
-  npx @milenyumai/film-kit generate-storyboard --character-ref ./refs/character.png --storyboard-ref ./refs/storyboard.png --brief ./scenario.md --models veo31,seedance-2.0,kling-3.0 --duration 8 --aspect 16:9
+  npx @milenyumai/film-kit generate-storyboard --character-ref ./refs/character.png --brief ./scenario.md --models veo31,seedance-2.0,kling-3.0 --duration 8 --aspect 16:9
   npx @milenyumai/film-kit init --overwrite
 
 Common flags:
@@ -513,7 +513,7 @@ Preset-specific flags:
 
 generate-storyboard flags:
   --character-ref      Character identity reference image path or URL (repeatable or comma-separated)
-  --storyboard-ref     Storyboard planning reference image path or URL (repeatable or comma-separated)
+  --storyboard-ref     Optional storyboard guide image path or URL (repeatable or comma-separated)
   --brief              Inline brief text or a path to a brief file
   --models             Comma-separated models: veo31,seedance-2.0,kling-3.0
   --duration           Duration in seconds per generated shot

package/build/lib/film-kit.js

@@ -372,10 +372,12 @@ export async function configureFilmKit(options = {}) {
     merged.preset = preset;
     const runtime = await loadPresetRuntime(preset);
     const resolved = runtime.resolve(pickPresetOptions(preset, merged));
-    assignDefined(resolved, {
-        referenceMode: merged.referenceMode,
-        storyboardReferenceMode: merged.storyboardReferenceMode
-    });
+    if (resolved.referenceMode === undefined && merged.referenceMode !== undefined) {
+        resolved.referenceMode = merged.referenceMode;
+    }
+    if (resolved.storyboardReferenceMode === undefined && merged.storyboardReferenceMode !== undefined) {
+        resolved.storyboardReferenceMode = merged.storyboardReferenceMode;
+    }
     const configureOptions = pickPresetOptions(preset, resolved);
     const result = await runtime.configure(configureOptions);
     const configPath = join(rootDir, FILM_KIT_CONFIG_FILE);

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

@@ -22,7 +22,7 @@ export class Kling30PromptAdapter extends BaseVideoModelPromptAdapter {
         const visualWorld = input.visualWorld;
         const route = routeForPhaseCount(input.interpretation.phases.length);
         const promptText = `[CHARACTER / SUBJECT CONSISTENCY]
-Use the character reference as the exact identity and wardrobe anchor. Same face, hair, skin texture, body proportions, wardrobe, accessories, and visible props. The storyboard reference controls staging, camera rhythm, and phase order only. Do not inherit alternate character design from the storyboard.
+Use the generated character sheet reference as the exact identity and wardrobe anchor. Same face, hair, skin texture, body proportions, wardrobe, accessories, and visible props. The generated shot storyboard reference (${input.storyboardImagePrompt.outputPath}) controls staging, camera rhythm, and phase order only. Do not inherit alternate character design from the storyboard.
 
 [CORE INTENT]
 ${input.request.brief}
@@ -60,6 +60,8 @@ identity drift, face drift, outfit drift, storyboard text, panel borders, waterm
             displayName: getDisplayName(this.model),
             routeMetadata: {
                 route,
+                providerAssetMapping: input.providerAssetMapping,
+                phaseBudget: input.phaseBudget,
                 phaseCount: input.interpretation.phases.length,
                 maxCustomStoryboardPhases: this.maxStoryboardPhases
             },

package/build/lib/storyboard-reference/adapters/seedance20.d.ts

@@ -6,6 +6,10 @@ export declare class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter
     readonly supportsCharacterReference = true;
     readonly supportsAudioPlan = true;
     readonly maxStoryboardPhases = 4;
+    private buildProviderWarnings;
+    private getMappingEntries;
+    private formatCharacterRoleLine;
+    private formatStoryboardRoleLine;
     buildPrompt(input: AdapterInput): ModelPromptOutput;
     validate(output: ModelPromptOutput): ModelPromptQa;
 }

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

@@ -5,12 +5,56 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
     supportsCharacterReference = true;
     supportsAudioPlan = true;
     maxStoryboardPhases = 4;
+    buildProviderWarnings(fileLimits) {
+        const warnings = [];
+        if (fileLimits.observedImages > fileLimits.maxImages) {
+            warnings.push(`Seedance provider image reference limit exceeded: ${fileLimits.observedImages}/${fileLimits.maxImages}.`);
+        }
+        if (fileLimits.observedVideos > fileLimits.maxVideos) {
+            warnings.push(`Seedance provider video reference limit exceeded: ${fileLimits.observedVideos}/${fileLimits.maxVideos}.`);
+        }
+        if (fileLimits.observedAudio > fileLimits.maxAudio) {
+            warnings.push(`Seedance provider audio reference limit exceeded: ${fileLimits.observedAudio}/${fileLimits.maxAudio}.`);
+        }
+        if (fileLimits.observedTotalFiles > fileLimits.maxTotalFiles) {
+            warnings.push(`Seedance provider total reference file limit exceeded: ${fileLimits.observedTotalFiles}/${fileLimits.maxTotalFiles}.`);
+        }
+        return warnings;
+    }
+    getMappingEntries(input, role) {
+        return Object.values(input.providerAssetMapping).filter(entry => entry.role === role);
+    }
+    formatCharacterRoleLine(input) {
+        const characterEntries = this.getMappingEntries(input, "character_identity");
+        const tokens = characterEntries.map(entry => entry.token);
+        const tokenText = tokens.length === 1 ? tokens[0] : tokens.join(", ");
+        const aliasText = characterEntries
+            .map(entry => entry.legacyAlias)
+            .filter((alias) => Boolean(alias))
+            .join(", ");
+        return tokens.length === 1
+            ? `Use ${tokenText} as the exact character identity reference. Preserve the same face, hair, body proportions, wardrobe, accessories, and visible props throughout.${aliasText ? ` Legacy alias: ${aliasText}.` : ""}`
+            : `Use ${tokenText} as exact character identity references. Preserve each matching face, hair, body proportion, wardrobe, accessory, and visible prop throughout; never merge or swap identities.${aliasText ? ` Legacy aliases: ${aliasText}.` : ""}`;
+    }
+    formatStoryboardRoleLine(input) {
+        const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
+        const token = storyboardEntry?.token ?? "@Image2";
+        const alias = storyboardEntry?.legacyAlias;
+        return `Use ${token} as the shot storyboard reference for composition, blocking, camera direction, timing, action rhythm, and phase order only. Do not copy storyboard text, labels, panel borders, watermarks, logos, or alternate character design from ${token}.${alias ? ` Legacy alias: ${alias}.` : ""}`;
+    }
     buildPrompt(input) {
         const audioPlan = buildAudioPlan(input);
-        const promptText = `Use @image1 as the exact character identity reference. Preserve the same face, hair, body proportions, wardrobe, accessories, and visible props throughout.
-Use @image2 as the storyboard reference for composition, blocking, camera direction, and action progression only. Do not copy storyboard text, labels, panel borders, watermarks, logos, or alternate character design from @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.";
+        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)}
 
-No scene cuts throughout, one continuous shot unless the storyboard phases below explicitly define internal editorial stages.
+${continuityInstruction}
 
 [CORE INTENT]
 ${input.request.brief}
@@ -18,6 +62,9 @@ ${input.request.brief}
 [STORYBOARD PHASES]
 ${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.
+
 [CAMERA]
 ${input.interpretation.cameraPlan.framing}, ${input.interpretation.cameraPlan.movement}, ${input.interpretation.cameraPlan.lens}, ${input.interpretation.cameraPlan.stabilization}. Preserve ${input.interpretation.cameraPlan.screenDirection}.
 
@@ -31,23 +78,22 @@ Ambience: ${audioPlan.ambience.join(", ")}.
 Music: NONE.
 
 [CONTINUITY]
-Identity reference stays locked to @image1. Storyboard @image2 controls staging and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard.
+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.
 
 Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps.`;
         const output = {
             model: this.model,
             displayName: getDisplayName(this.model),
             routeMetadata: {
-                assetMapping: {
-                    "@image1": "character identity reference",
-                    "@image2": "storyboard/composition/timing reference"
-                },
-                continuousShot: true,
+                continuityMode: input.continuityMode,
+                providerAssetMapping: input.providerAssetMapping,
+                phaseBudget: input.phaseBudget,
+                providerFileLimits: input.providerFileLimits,
                 phaseCount: input.interpretation.phases.length
             },
             promptText,
             audioPlan,
-            warnings: [],
+            warnings: this.buildProviderWarnings(input.providerFileLimits),
             qa: { verdict: "pass", checks: {}, issues: [] }
         };
         output.qa = this.validate(output);
@@ -55,11 +101,24 @@ Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders,
     }
     validate(output) {
         const base = super.validate(output);
+        const continuityMode = output.routeMetadata.continuityMode;
+        const mapping = output.routeMetadata.providerAssetMapping ?? {};
+        const mappingEntries = Object.values(mapping);
+        const characterTokens = mappingEntries
+            .filter(entry => entry.role === "character_identity")
+            .map(entry => entry.token);
+        const storyboardToken = mappingEntries.find(entry => entry.role === "storyboard_plan")?.token ?? "@Image2";
+        const hasNoCutsRule = /No scene cuts throughout, one continuous shot/i.test(output.promptText);
         const checks = {
             ...base.checks,
-            usesImage1Identity: /@image1 as the exact character identity reference/i.test(output.promptText),
-            usesImage2Storyboard: /@image2 as the storyboard reference/i.test(output.promptText),
-            continuousShot: /No scene cuts throughout, one continuous shot/i.test(output.promptText),
+            usesCharacterIdentityTokens: characterTokens.length > 0
+                && 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),
+            continuityMode: continuityMode === "continuous-shot"
+                ? hasNoCutsRule
+                : !hasNoCutsRule && /planned storyboard phase transitions/i.test(output.promptText),
             musicNone: /Music: NONE/i.test(output.promptText)
         };
         const issues = [

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

@@ -17,7 +17,7 @@ export class Veo31PromptAdapter extends BaseVideoModelPromptAdapter {
         const audioPlan = buildAudioPlan(input);
         const camera = input.interpretation.cameraPlan;
         const visualWorld = input.visualWorld;
-        const promptText = `Use the uploaded character reference as the exact identity anchor throughout the shot. Preserve the same face, hair, body proportions, wardrobe, accessories, and visible props. Use the uploaded storyboard image as a visual planning reference for composition, blocking, camera angle, pacing, and intended action progression only. Do not copy storyboard text, labels, panel borders, watermarks, logos, or any alternate character design from the storyboard.
+        const promptText = `Use the generated character sheet reference as the exact identity anchor throughout the shot. Preserve the same face, hair, body proportions, wardrobe, accessories, and visible props. Use the generated shot storyboard image from ${input.storyboardImagePrompt.outputPath} as a visual planning reference for composition, blocking, camera angle, pacing, and intended action progression only. Do not copy storyboard text, labels, panel borders, watermarks, logos, or any alternate character design from the storyboard.
 
 Cinematic ${camera.shotType} of the referenced character in ${visualWorld.environment}. ${input.request.brief} The scene follows the storyboard's ${input.interpretation.phases.length} visual beats: ${summarizeBeats(input)}. Performance remains grounded in visible micro-behavior, with controlled eye-line changes, breath, posture, and hand tension. The character reference always wins over the storyboard if identity, wardrobe, proportions, accessories, or prop design conflict.
 
@@ -39,6 +39,8 @@ Avoid: identity drift, face drift, outfit drift, storyboard panel borders, on-sc
             displayName: getDisplayName(this.model),
             routeMetadata: {
                 storyboardRole: "visual planning reference",
+                providerAssetMapping: input.providerAssetMapping,
+                phaseBudget: input.phaseBudget,
                 phaseCount: input.interpretation.phases.length,
                 minWordTarget: 120
             },

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

@@ -4,4 +4,4 @@ export { resolveAssetRoles } from "./asset-role-resolver.js";
 export { interpretStoryboard } from "./storyboard-interpreter.js";
 export { renderShotMarkdown, writeStoryboardReferenceOutputs } from "./output-writer.js";
 export { assertSafeStoryboardReferenceRequest, validateModelPromptOutput, validatePromptBundle, validateResolvedAssetRoles } from "./validators.js";
-export type { AdapterInput, AudioPlan, CameraPlan, ContinuityAnchors, DialogueLine, ModelPromptOutput, ModelPromptQa, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ReferenceAsset, ReferenceAssetRole, ReferenceLockStrength, ResolvedAssetRoles, StoryboardInterpretation, StoryboardPhase, StoryboardReferenceBuildResult, StoryboardReferencePlan, StoryboardReferenceWriteResult, VideoModelPromptAdapter, VideoPromptRequest, VisualWorld, VoiceCastEntry } from "./types.js";
+export type { AdapterInput, AudioPlan, CameraPlan, CharacterReferenceSheetPrompt, ContinuityAnchors, DialogueLine, ModelPromptOutput, ModelPromptQa, ModelRouteMetadata, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, ReferenceAssetRole, ReferenceLockStrength, ResolvedAssetRoles, SeedanceContinuityMode, ShotHandoffNote, StoryboardImagePrompt, StoryboardInterpretation, StoryboardPhase, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePlan, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoModelPromptAdapter, VideoPromptRequest, VisualWorld, VoiceCastEntry } from "./types.js";

package/build/lib/storyboard-reference/output-writer.js

@@ -23,6 +23,23 @@ function formatQa(bundle) {
     }
     return lines.join("\n");
 }
+function formatReferenceRequirements(bundle) {
+    return bundle.referenceAssetRequirements
+        .map(requirement => {
+        const alias = requirement.legacyAlias ? ` / ${requirement.legacyAlias}` : "";
+        const path = requirement.generatedPromptPath ? ` Prompt: ${requirement.generatedPromptPath}.` : "";
+        return `- ${requirement.token}${alias}: ${requirement.source}, ${requirement.role}, ${requirement.required ? "required" : "optional"}. ${requirement.notes}${path}`;
+    })
+        .join("\n");
+}
+function formatProviderTokens(bundle) {
+    return Object.values(bundle.providerAssetMapping)
+        .map(entry => {
+        const alias = entry.legacyAlias ? ` / ${entry.legacyAlias}` : "";
+        return `- ${entry.token}${alias}: ${entry.description}`;
+    })
+        .join("\n");
+}
 export function renderShotMarkdown(bundle) {
     const interpretation = bundle.storyboardInterpretation;
     const audioPlan = getAudioPlan(bundle);
@@ -33,24 +50,44 @@ export function renderShotMarkdown(bundle) {
     return `# ${bundle.shotId} | ${bundle.durationSeconds}s | Mode: storyboard-reference
 
 ## Türkçe Özet
-Storyboard referansı kompozisyon, bloklama, kamera ve zamanlama planı olarak kullanılır; karakter referansı kimlik, kıyafet, oran, aksesuar ve görünür prop kilidi olarak korunur.
+Önce tek seferlik karakter sheet referansları üretilir. Bu shot için ayrıca GPT Image 2 ile profesyonel storyboard görsel promptu üretilir; Seedance tarafında karakter sheet tokenları kimliği, shot storyboard tokenı ise kompozisyon, bloklama, kamera ve zamanlamayı yönetir.
 
 ## Model Control
 - Reference Mode: storyboard-reference
 - Target Models: ${Object.keys(bundle.modelPrompts).join(", ")}
 - Aspect Ratio: ${bundle.aspectRatio}
 - Duration: ${bundle.durationSeconds}s
+- Continuity Mode: ${bundle.continuityMode}
+- Phase Budget: ${bundle.phaseBudget.policy}; effective max ${bundle.phaseBudget.effectiveMaxStoryboardPhases}
 - Safety Mode: fail-closed
 
 ## Input Asset Roles
 ${Object.values(bundle.assetRoles).map(role => `- ${role.token}: ${role.role}, ${role.lockStrength} lock`).join("\n")}
 
+## Reference Asset Requirements
+${formatReferenceRequirements(bundle)}
+
+## Provider Reference Tokens
+${formatProviderTokens(bundle)}
+
+## GPT Image 2 Storyboard Prompt
+- Output: ${bundle.storyboardImagePrompt.outputPath}
+- Panel count: ${bundle.storyboardImagePrompt.panelCount}
+- Previous handoff: ${bundle.storyboardImagePrompt.previousShotHandoff}
+- Next handoff: ${bundle.storyboardImagePrompt.nextShotHandoff}
+
+\`\`\`text
+${bundle.storyboardImagePrompt.promptText}
+\`\`\`
+
 ## Storyboard Interpretation
 - Editorial function: ${interpretation.editorialFunction}
 - Panel/phase count: ${interpretation.panelCount}
 - Camera plan: ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}
 - Screen direction: ${interpretation.cameraPlan.screenDirection}
 - Light source: ${interpretation.visualWorld.lighting}
+- Entry handoff: ${bundle.handoffNote.entryHandoff}
+- Exit handoff: ${bundle.handoffNote.exitHandoff}
 - Continuity anchors: ${[
         ...interpretation.continuityAnchors.identity,
         ...interpretation.continuityAnchors.wardrobe,
@@ -70,6 +107,34 @@ ${modelPrompts}
 ${formatQa(bundle)}
 `;
 }
+function renderCharacterSheetPrompt(prompt) {
+    return `# ${prompt.id}
+
+- Provider: ${prompt.provider}
+- Aspect Ratio: ${prompt.aspectRatio}
+- Source: ${prompt.sourceToken}
+- Generated Once: ${prompt.generatedOnce ? "YES" : "NO"}
+- Cell Count: ${prompt.cellCount}
+
+\`\`\`text
+${prompt.promptText}
+\`\`\`
+`;
+}
+function renderStoryboardPromptFile(bundle) {
+    return `# ${bundle.shotId} GPT Image 2 Storyboard Prompt
+
+- Provider: ${bundle.storyboardImagePrompt.provider}
+- Aspect Ratio: ${bundle.storyboardImagePrompt.aspectRatio}
+- Panel Count: ${bundle.storyboardImagePrompt.panelCount}
+- Character Sheets: ${bundle.storyboardImagePrompt.characterSheetIds.join(", ")}
+- External Storyboard Guides: ${bundle.storyboardImagePrompt.externalStoryboardGuideIds.join(", ") || "none"}
+
+\`\`\`text
+${bundle.storyboardImagePrompt.promptText}
+\`\`\`
+`;
+}
 function renderQaReport(result) {
     const models = result.request.targetModels.join(", ");
     const rows = result.bundles
@@ -82,7 +147,7 @@ function renderQaReport(result) {
         .map(row => `| ${row.shotId} | ${row.model} | ${row.verdict.toUpperCase()} | ${row.notes} |`)
         .join("\n");
     const assetRows = result.bundles
-        .map(bundle => `| ${bundle.shotId} | ${result.assets.characters.length} | ${result.assets.storyboards.length} | ${bundle.qa.verdict.toUpperCase()} |`)
+        .map(bundle => `| ${bundle.shotId} | ${result.characterReferenceSheetPrompts.length} | ${result.assets.storyboards.length} | ${bundle.storyboardImagePrompt ? "YES" : "NO"} | ${bundle.qa.verdict.toUpperCase()} |`)
         .join("\n");
     const issues = result.bundles.flatMap(bundle => bundle.qa.issues);
     return `# Storyboard Reference QA Report
@@ -90,12 +155,16 @@ function renderQaReport(result) {
 ## Summary
 - Verdict: ${issues.length === 0 ? "PASS" : "FAIL"}
 - Shots checked: ${result.bundles.length}
+- Character sheet prompts: ${result.characterReferenceSheetPrompts.length}
+- Shot storyboard prompts: ${result.bundles.length}
 - Models checked: ${models}
 - Split required: ${result.plan.splitRequired ? "YES" : "NO"}
+- Phase budget: ${result.plan.policy.storyboard_reference.recommended_phase_budget.policy}
+- Provider files within limits: ${result.plan.policy.storyboard_reference.provider_file_limits.withinLimits ? "YES" : "NO"}
 
 ## Asset Role Checks
-| Shot | Character Ref | Storyboard Ref | Verdict |
-|---|---:|---:|---|
+| Shot | Character Sheets | External Storyboard Guides | Generated Storyboard | Verdict |
+|---|---:|---:|---:|---|
 ${assetRows}
 
 ## Model Grammar Checks
@@ -122,17 +191,26 @@ export async function writeStoryboardReferenceOutputs(result, rootDir = process.
 
 - Mode: storyboard-reference
 - Character references: ${result.assets.characters.length}
-- Storyboard references: ${result.assets.storyboards.length}
+- Character sheet prompts: ${result.characterReferenceSheetPrompts.length}
+- External storyboard guides: ${result.assets.storyboards.length}
+- Generated shot storyboard prompts: ${result.bundles.length}
 - Target models: ${result.request.targetModels.join(", ")}
 - Safety context: ${result.request.safetyContext}
 `);
     written.push(projectInfoPath);
+    for (const prompt of result.characterReferenceSheetPrompts) {
+        const promptPath = resolve(rootDir, prompt.outputPath);
+        await writeText(promptPath, renderCharacterSheetPrompt(prompt));
+        written.push(promptPath);
+    }
     for (const bundle of result.bundles) {
         const shotPath = join(outputRoot, "shots", `${bundle.shotId}.md`);
         const bundlePath = join(outputRoot, "prompt-bundles", `${bundle.shotId}.bundle.json`);
+        const storyboardPromptPath = resolve(rootDir, bundle.storyboardImagePrompt.outputPath);
+        await writeText(storyboardPromptPath, renderStoryboardPromptFile(bundle));
         await writeText(shotPath, renderShotMarkdown(bundle));
         await writeText(bundlePath, `${JSON.stringify(bundle, null, 2)}\n`);
-        written.push(shotPath, bundlePath);
+        written.push(storyboardPromptPath, shotPath, bundlePath);
     }
     await writeText(qaPath, renderQaReport(result));
     written.push(qaPath);