@milenyumai/film-kit 2.3.2 → 2.3.4

package/MODEL_REGISTRY.md

@@ -0,0 +1,136 @@
+# Film-Kit Model Registry
+
+Film-Kit model metadata is centralized in `src/lib/model-registry/*`.
+
+The registry is TypeScript `as const` metadata, not dynamic JSON. It is the canonical source for model identity, lifecycle, preset compatibility, reference-mode compatibility, capabilities, routing role, prompt grammar key, model profile key, and storyboard adapter resolution.
+
+Long prompt grammar, runtime profile prose, production guidance, and generated workflow text stay in the existing template, adapter, skill, and model-profile layers.
+
+## Discovery Summary
+
+Phase 0 found model ids in four broad surfaces:
+
+- Root validation and runtime selection: `src/lib/types.ts`, `src/lib/defaults.ts`, `src/lib/configure.ts`, `src/lib/cli.ts`, and `src/lib/film-kit.ts`.
+- Storyboard-reference routing: `src/lib/storyboard-reference/defaults.ts`, `request-normalizer.ts`, `prompt-bundle-builder.ts`, and `adapters/*`.
+- Internal preset packages: `packages/*/src/lib/*`, where model ids still appear in private preset defaults, templates, and generated runtime prose.
+- Public/user-facing prose and assertions: `README.md`, `content/*`, `packages/*/content/*`, and tests.
+
+Phase 1 moved the root runtime, CLI/config validation, `generate-storyboard --models`, storyboard-reference target validation, display-name lookup, default storyboard model list, and adapter resolution onto the registry.
+
+Phase 2 intentionally does not import the root registry directly from `packages/*`: package `tsconfig.json` files use `rootDir: src`, and the internal package sources remain private preset implementations. Public usage is guarded through the root dispatcher and root CLI.
+
+Remaining hardcoded model names in templates, content, and tests are prompt grammar, generated docs, explicit examples, or compatibility assertions rather than canonical validation sources.
+
+## Files
+
+- `src/lib/model-registry/types.ts` defines registry metadata shapes.
+- `src/lib/model-registry/registry.ts` owns the canonical model entries.
+- `src/lib/model-registry/selectors.ts` exposes lookup and selector helpers.
+- `src/lib/model-registry/validation.ts` owns fail-closed model validation.
+- `src/lib/model-registry/index.ts` is the public registry API barrel.
+
+## Public API
+
+- `getModel(id)`
+- `requireModel(id)`
+- `listModels()`
+- `listActiveModels()`
+- `listVideoModels()`
+- `listImageModels()`
+- `listActiveVideoModelIds()`
+- `listRunnableVideoModels()`
+- `listRunnableVideoModelIds()`
+- `listModelsForPreset(preset)`
+- `listModelsForReferenceMode(referenceMode)`
+- `isKnownModelId(value)`
+- `isActiveModelId(value)`
+- `isDeprecatedModelId(value)`
+- `isRemovedModelId(value)`
+- `isVideoModelId(value)`
+- `isImageModelId(value)`
+- `isModelSupportedByPreset(modelId, preset)`
+- `getModelAdapterKey(modelId)`
+- `getModelDisplayName(modelId)`
+- `getReplacementModel(modelId)`
+- `assertModelAllowed(modelId, context)`
+- `validateModelAllowed(modelId, context)`
+
+## Lifecycle Rules
+
+- `active`: accepted normally.
+- `experimental`: accepted normally, but may be surfaced as internal or preview metadata.
+- `deprecated`: accepted, emits an explicit warning, and should define `replacementModelId` when possible.
+- `removed`: fail-closed. Removed models must never silently fall back.
+
+## Adapter Routing
+
+Storyboard-reference video prompt routing resolves through `adapterKey`.
+
+- `veo31` -> Veo adapter
+- `seedance20` -> Seedance 2.0 adapter
+- `kling30` -> Kling 3.0 adapter
+- `generic` -> generic adapter, allowed only when the registry entry explicitly selects it
+- `none`, `gptImage2` -> not valid for video storyboard adapter routing
+
+Unknown model strings never receive a generic fallback.
+
+## Adding A Video Model
+
+1. Add one entry in `src/lib/model-registry/registry.ts`.
+2. Choose `modalities: ["video"]`.
+3. Set `lifecycleStatus`.
+4. Set `supportedPresets`.
+5. Set `supportedReferenceModes`.
+6. Set `supportedAspects`.
+7. Add `durationRange` or `durationPolicy`.
+8. Choose an existing `adapterKey` or add a new adapter.
+9. Set `promptGrammarKey` and `modelProfileKey`.
+10. Fill `routingRole` and `capabilities`.
+11. Add registry selector/validation tests.
+12. Add storyboard adapter routing tests when the model can generate video prompts.
+13. Update docs/examples only if the model should be publicly visible.
+
+Ideal new-video-model diff:
+
+- one registry entry
+- one adapter only if no existing adapter fits
+- focused tests
+- docs update when public
+
+## Adding An Image Model
+
+1. Add one registry entry with `modalities: ["image"]`.
+2. Do not add it to video-only CLI or storyboard video target validation.
+3. Pick image-aware `supportedPresets`.
+4. Use `adapterKey: "gptImage2"` only for GPT Image 2 behavior; use `none` or a future image adapter key otherwise.
+5. Add tests proving it appears in image selectors and not in video selectors.
+
+Image models must not widen video model types or `generate-storyboard --models`.
+
+## Deprecating A Model
+
+1. Change `lifecycleStatus` to `deprecated`.
+2. Add `deprecationMessage`.
+3. Add `replacementModelId` when there is a direct replacement.
+4. Keep compatibility metadata only for paths that still work.
+5. Add tests proving validation emits a warning.
+
+Do not silently rewrite deprecated model ids unless a dedicated migration test covers that behavior.
+
+## Removing A Model
+
+1. Change `lifecycleStatus` to `removed`.
+2. Keep the id in the registry so validation can fail with a clear message.
+3. Add `deprecationMessage` and `replacementModelId` when possible.
+4. Clear runtime compatibility if the model must not be routed.
+5. Add tests proving `assertModelAllowed` fails closed.
+
+Removed models must not fall back to active models or generic adapters.
+
+## Phase Boundaries
+
+Phase 1 connects the root runtime, CLI/config validation, and storyboard-reference adapter routing to the registry.
+
+Phase 2 keeps internal preset packages private. Package source builds use `rootDir: src`, so direct imports from root `src/lib/model-registry` would break package builds or create circular product coupling. Root `configureFilmKit()` and CLI validation are the canonical guardrails for public usage. Internal package prompt/template prose can continue to contain model names as generated runtime content.
+
+Phase 3 is this maintenance documentation plus README linkage.

package/README.md

@@ -70,6 +70,8 @@ Storyboard-reference prompt generation is also available when you have a charact
 
 ## Model Support
 
+Canonical model metadata lives in `src/lib/model-registry/*`; see [MODEL_REGISTRY.md](./MODEL_REGISTRY.md) for the add/update/deprecate/remove checklist. Public model selection still happens at init time through the root package and CLI.
+
 ### `veo31`
 
 - Default single, multi, and studio model
@@ -484,6 +486,25 @@ Public root exports:
 - `FILM_KIT_CONFIG_FILE`
 - `FILM_KIT_PRESETS`
 - `LEGACY_CONFIG_FILES`
+- `getModel(id)`
+- `requireModel(id)`
+- `listModels()`
+- `listActiveModels()`
+- `listVideoModels()`
+- `listImageModels()`
+- `listModelsForPreset(preset)`
+- `listModelsForReferenceMode(referenceMode)`
+- `isKnownModelId(value)`
+- `isActiveModelId(value)`
+- `isDeprecatedModelId(value)`
+- `isRemovedModelId(value)`
+- `isVideoModelId(value)`
+- `isImageModelId(value)`
+- `isModelSupportedByPreset(modelId, preset)`
+- `getModelAdapterKey(modelId)`
+- `getReplacementModel(modelId)`
+- `assertModelAllowed(id, context)`
+- `validateModelAllowed(id, context)`
 - `FilmKitPreset`
 - `SupportedModel`
 - `SupportedPlatform`
@@ -558,10 +579,7 @@ These subpackages are marked `private: true` and are bundled as internal sources
 Maintainer release checklist:
 
 ```bash
-npm run typecheck
-npm test
-npm run build
-npm pack --json --dry-run
+npm run release:check
 ```
 
 Publish the single public package:
@@ -572,6 +590,12 @@ npm whoami
 npm publish --access public
 ```
 
+If the account has npm two-factor authentication enabled for publish, include the current one-time password from the authenticator app:
+
+```bash
+npm publish --access public --otp=123456
+```
+
 Optional validation before publish:
 
 ```bash

package/build/index.d.ts

@@ -1,5 +1,7 @@
 export { configureFilmKit, detectFilmKitPreset, FILM_KIT_CONFIG_FILE, FILM_KIT_PRESETS, LEGACY_CONFIG_FILES } from "./lib/film-kit.js";
 export { configureAgents } from "./lib/configure.js";
 export { buildStoryboardReferencePromptBundles, normalizeVideoPromptRequest, renderShotMarkdown, writeStoryboardReferenceOutputs } from "./lib/storyboard-reference/index.js";
+export { assertModelAllowed, getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel, validateModelAllowed } from "./lib/model-registry/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 { ActiveModelId, AudioModelId, DeprecatedModelId, ImageModelId, KnownModelId, ModelAdapterKey, ModelAllowedContext, ModelAllowedResult, ModelCapabilities, ModelLifecycleStatus, ModelModality, ModelRegistryEntry, MultimodalModelId, RemovedModelId, VideoModelId } from "./lib/model-registry/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/index.js

@@ -1,3 +1,4 @@
 export { configureFilmKit, detectFilmKitPreset, FILM_KIT_CONFIG_FILE, FILM_KIT_PRESETS, LEGACY_CONFIG_FILES } from "./lib/film-kit.js";
 export { configureAgents } from "./lib/configure.js";
 export { buildStoryboardReferencePromptBundles, normalizeVideoPromptRequest, renderShotMarkdown, writeStoryboardReferenceOutputs } from "./lib/storyboard-reference/index.js";
+export { assertModelAllowed, getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel, validateModelAllowed } from "./lib/model-registry/index.js";

package/build/lib/cli.js

@@ -2,7 +2,7 @@ import { FILM_KIT_CONFIG_FILE, FILM_KIT_PRESETS, detectFilmKitPreset, isFilmKitP
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { exists } from "./fs.js";
-const SUPPORTED_MODELS = ["veo31", "kling-3.0", "seedance-2.0"];
+import { listActiveVideoModelIds, validateModelAllowed } from "./model-registry/index.js";
 const SUPPORTED_KLING_PRESETS = ["ultra-realism", "balanced", "custom"];
 const SUPPORTED_ASPECTS = ["16:9", "9:16", "1:1"];
 const SUPPORTED_REFERENCE_MODES = ["start-end", "storyboard-reference", "hybrid"];
@@ -87,6 +87,9 @@ const PRESET_ALLOWED_FLAGS = {
     ])
 };
 const COMMON_FLAGS = new Set(["--preset", "--output-dir", "--scenario-hint", "--scenario", "--overwrite", "-f"]);
+function supportedVideoModelText() {
+    return listActiveVideoModelIds().join(", ");
+}
 function parseIntegerFlag(raw, flag) {
     const value = Number.parseInt(raw, 10);
     if (!Number.isInteger(value) || value <= 0) {
@@ -181,10 +184,10 @@ function parseKnownFlags(args) {
                 options.platforms = parsePlatforms(nextValue);
                 break;
             case "--model":
-                if (!SUPPORTED_MODELS.includes(nextValue)) {
-                    throw new Error(`Invalid --model value: ${nextValue}. Supported: ${SUPPORTED_MODELS.join(", ")}`);
-                }
-                options.model = nextValue;
+                options.model = validateModelAllowed(nextValue, {
+                    requiredModalities: ["video"],
+                    usage: "--model"
+                }).model.id;
                 break;
             case "--kling-preset":
                 if (!SUPPORTED_KLING_PRESETS.includes(nextValue)) {
@@ -293,9 +296,11 @@ function parseModels(raw) {
         throw new Error("Invalid --models value. Expected at least one supported model.");
     }
     for (const model of models) {
-        if (!SUPPORTED_MODELS.includes(model)) {
-            throw new Error(`Invalid --models value: ${model}. Supported: ${SUPPORTED_MODELS.join(", ")}`);
-        }
+        validateModelAllowed(model, {
+            requiredModalities: ["video"],
+            referenceMode: "storyboard-reference",
+            usage: "--models"
+        });
     }
     return models;
 }
@@ -414,7 +419,7 @@ async function parseGenerateStoryboardCommand(args, rootDir) {
                 break;
         }
     }
-    if (!brief) {
+    if (!brief?.trim()) {
         throw new Error("generate-storyboard requires --brief.");
     }
     if (characterRefs.length === 0) {
@@ -472,6 +477,17 @@ export async function parseCliCommand(args, rootDir = process.cwd()) {
             `You can also commit ${FILM_KIT_CONFIG_FILE} and rerun init.`);
     }
     validatePresetFlags(preset, providedFlags);
+    if (options.model) {
+        const validationContext = {
+            preset,
+            requiredModalities: ["video"],
+            usage: "--model"
+        };
+        if (options.referenceMode !== undefined) {
+            validationContext.referenceMode = options.referenceMode;
+        }
+        validateModelAllowed(options.model, validationContext);
+    }
     return {
         command: "init",
         options: {
@@ -518,7 +534,7 @@ generate-storyboard flags:
   --character-ref      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 file
-  --models             Comma-separated models: veo31,seedance-2.0,kling-3.0
+  --models             Comma-separated models: ${supportedVideoModelText()}
   --duration           Duration in seconds per generated shot
   --aspect             16:9|9:16|1:1
   --output-dir         Output root (default: ./outputs)

package/build/lib/configure.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { readdir, readFile, rm } from "node:fs/promises";
 import { exists, readJsonIfExists, writeText } from "./fs.js";
 import { resolveOptions } from "./defaults.js";
+import { getModelDisplayName as getRegistryModelDisplayName } from "./model-registry/index.js";
 import { buildProjectFiles } from "./templates.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -549,13 +550,6 @@ description: Storyboard-reference prompt structure for GPT Image 2 character she
 Do not emit main-shot \`ILK FRAME\`, \`İLK FRAME\`, \`SON FRAME\`, \`SHOTNN_START\`, \`SHOTNN_END\`, or exact first-frame reuse instructions in storyboard-reference mode.
 `;
 }
-function getModelDisplayName(model) {
-    if (model === "kling-3.0")
-        return "Kling 3.0";
-    if (model === "seedance-2.0")
-        return "Seedance 2.0";
-    return "Google Flow + Veo 3.1";
-}
 function getKlingPresetDisplay(model, klingPreset) {
     return model === "kling-3.0" ? klingPreset : "n/a (Kling-only)";
 }
@@ -622,7 +616,7 @@ export async function configureAgents(options = {}) {
         scenarioHint: resolved.scenarioHint,
         model: resolved.model,
         klingPreset: getKlingPresetDisplay(resolved.model, resolved.klingPreset),
-        modelDisplayName: getModelDisplayName(resolved.model),
+        modelDisplayName: getRegistryModelDisplayName(resolved.model),
         referenceMode: resolved.referenceMode,
         storyboardReferenceActive,
         maxStoryboardPhases: resolved.storyboardReferenceMode.maxStoryboardPhases

package/build/lib/defaults.js

@@ -1,3 +1,4 @@
+import { validateModelAllowed } from "./model-registry/index.js";
 const ALL_PLATFORMS = ["cursor", "claude", "copilot", "antigravity", "codex"];
 const DEFAULT_MODEL = "veo31";
 const DEFAULT_KLING_PRESET = "ultra-realism";
@@ -31,12 +32,21 @@ export function normalizeStoryboardReferenceConfig(input, referenceMode) {
 export function resolveOptions(input) {
     const warnings = [];
     const model = input.model ?? DEFAULT_MODEL;
+    const modelValidationContext = {
+        requiredModalities: ["video"],
+        usage: "runtime"
+    };
+    if (input.referenceMode !== undefined) {
+        modelValidationContext.referenceMode = input.referenceMode;
+    }
+    const modelValidation = validateModelAllowed(model, modelValidationContext);
     const klingPreset = input.klingPreset ?? DEFAULT_KLING_PRESET;
     const referenceMode = input.referenceMode ?? DEFAULT_REFERENCE_MODE;
     const storyboardReferenceMode = normalizeStoryboardReferenceConfig(input.storyboardReferenceMode, referenceMode);
     if (!input.model) {
         warnings.push("Model not specified. Falling back to veo31. In the next major release, --model will be required.");
     }
+    warnings.push(...modelValidation.warnings);
     if (referenceMode === "storyboard-reference" && !storyboardReferenceMode.enabled) {
         warnings.push("referenceMode is storyboard-reference, but storyboardReferenceMode.enabled is false.");
     }

package/build/lib/film-kit.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { configureAgents } from "./configure.js";
 import { resolveOptions } from "./defaults.js";
 import { exists, readJsonIfExists, writeText } from "./fs.js";
+import { validateModelAllowed } from "./model-registry/index.js";
 export const FILM_KIT_CONFIG_FILE = "film-kit.config.json";
 export const FILM_KIT_PRESETS = [
     "single",
@@ -370,6 +371,20 @@ export async function configureFilmKit(options = {}) {
     assignDefined(merged, options);
     merged.rootDir = rootDir;
     merged.preset = preset;
+    const rootValidationWarnings = [];
+    const mergedModel = readString(merged.model);
+    if (mergedModel) {
+        const validationContext = {
+            preset,
+            requiredModalities: ["video"],
+            usage: "film-kit.config.json model"
+        };
+        const mergedReferenceMode = readString(merged.referenceMode);
+        if (mergedReferenceMode !== undefined) {
+            validationContext.referenceMode = mergedReferenceMode;
+        }
+        rootValidationWarnings.push(...validateModelAllowed(mergedModel, validationContext).warnings);
+    }
     const runtime = await loadPresetRuntime(preset);
     const resolved = runtime.resolve(pickPresetOptions(preset, merged));
     if (resolved.referenceMode === undefined && merged.referenceMode !== undefined) {
@@ -382,7 +397,7 @@ export async function configureFilmKit(options = {}) {
     const result = await runtime.configure(configureOptions);
     const configPath = join(rootDir, FILM_KIT_CONFIG_FILE);
     await writeText(configPath, `${JSON.stringify(buildFilmKitConfigFile(preset, resolved), null, 2)}\n`);
-    const warnings = [...result.warnings];
+    const warnings = [...rootValidationWarnings, ...result.warnings];
     if (legacyMatch) {
         warnings.push(`Migrated legacy config '${legacyMatch.filename}' to '${FILM_KIT_CONFIG_FILE}'.`);
     }

package/build/lib/model-registry/index.d.ts

@@ -0,0 +1,4 @@
+export { MODEL_REGISTRY, type ActiveModelId, type AudioModelId, type DeprecatedModelId, type ImageModelId, type KnownModelId, type MultimodalModelId, type RemovedModelId, type VideoModelId } from "./registry.js";
+export { getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel } from "./selectors.js";
+export { assertModelAllowed, validateModelAllowed } from "./validation.js";
+export type { ModelAdapterKey, ModelAllowedContext, ModelAllowedResult, ModelCapabilities, ModelDurationRange, ModelLifecycleStatus, ModelModality, ModelProfileKey, ModelRegistryAspectRatio, ModelRegistryEntry, ModelRegistryPreset, ModelRegistryReferenceMode, ModelRoutingRole, PromptGrammarKey } from "./types.js";

package/build/lib/model-registry/index.js

@@ -0,0 +1,3 @@
+export { MODEL_REGISTRY } from "./registry.js";
+export { getModel, getModelAdapterKey, getModelDisplayName, getReplacementModel, isActiveModelId, isDeprecatedModelId, isImageModelId, isKnownModelId, isModelSupportedByPreset, isRemovedModelId, isVideoModelId, listActiveModels, listActiveVideoModelIds, listImageModels, listModels, listModelsForPreset, listModelsForReferenceMode, listRunnableVideoModelIds, listRunnableVideoModels, listVideoModels, requireModel } from "./selectors.js";
+export { assertModelAllowed, validateModelAllowed } from "./validation.js";

package/build/lib/model-registry/registry.d.ts

@@ -0,0 +1,220 @@
+import type { ModelRegistryEntry } from "./types.js";
+export declare const MODEL_REGISTRY: {
+    readonly veo31: {
+        readonly id: "veo31";
+        readonly displayName: "Google Flow + Veo 3.1";
+        readonly provider: "google";
+        readonly modalities: readonly ["video"];
+        readonly lifecycleStatus: "active";
+        readonly supportedPresets: readonly ["single", "multi", "studio"];
+        readonly supportedReferenceModes: readonly ["start-end", "storyboard-reference"];
+        readonly supportedAspects: readonly ["16:9", "9:16", "1:1"];
+        readonly durationRange: {
+            readonly minSeconds: 4;
+            readonly maxSeconds: 8;
+        };
+        readonly durationPolicy: "Default Film-Kit Veo runtime duration is 8 seconds.";
+        readonly adapterKey: "veo31";
+        readonly promptGrammarKey: "veo31";
+        readonly modelProfileKey: "veo31";
+        readonly routingRole: "primary-video";
+        readonly capabilities: {
+            readonly characterReference: true;
+            readonly storyboardReference: true;
+            readonly audioPlan: true;
+            readonly dialogue: true;
+            readonly startEndFrames: true;
+            readonly customStoryboardPhases: true;
+            readonly maxStoryboardPhases: 4;
+        };
+        readonly docsVisibility: "public";
+    };
+    readonly "seedance-2.0": {
+        readonly id: "seedance-2.0";
+        readonly displayName: "Seedance 2.0";
+        readonly provider: "bytedance";
+        readonly modalities: readonly ["video"];
+        readonly lifecycleStatus: "active";
+        readonly supportedPresets: readonly ["single", "multi", "studio"];
+        readonly supportedReferenceModes: readonly ["start-end", "storyboard-reference"];
+        readonly supportedAspects: readonly ["16:9", "9:16", "1:1"];
+        readonly durationRange: {
+            readonly minSeconds: 4;
+            readonly maxSeconds: 15;
+        };
+        readonly durationPolicy: "Seedance storyboard-reference policy uses 4-15 second shots.";
+        readonly adapterKey: "seedance20";
+        readonly promptGrammarKey: "seedance20";
+        readonly modelProfileKey: "seedance20";
+        readonly routingRole: "storyboard-video";
+        readonly capabilities: {
+            readonly characterReference: true;
+            readonly storyboardReference: true;
+            readonly multipleImageReferences: true;
+            readonly audioPlan: true;
+            readonly dialogue: true;
+            readonly customStoryboardPhases: true;
+            readonly maxStoryboardPhases: 4;
+            readonly maxReferenceImages: 9;
+            readonly maxReferenceVideos: 3;
+            readonly maxReferenceAudio: 3;
+            readonly maxReferenceFiles: 12;
+        };
+        readonly docsVisibility: "public";
+    };
+    readonly "kling-3.0": {
+        readonly id: "kling-3.0";
+        readonly displayName: "Kling 3.0";
+        readonly provider: "kuaishou";
+        readonly modalities: readonly ["video"];
+        readonly lifecycleStatus: "active";
+        readonly supportedPresets: readonly ["single", "multi", "hybrid", "hybrid-smart", "gpt-image-smart", "studio"];
+        readonly supportedReferenceModes: readonly ["start-end", "storyboard-reference", "hybrid"];
+        readonly supportedAspects: readonly ["16:9", "9:16", "1:1"];
+        readonly durationRange: {
+            readonly minSeconds: 5;
+            readonly maxSeconds: 15;
+        };
+        readonly durationPolicy: "Kling 3.0 supports Film-Kit start/end and smart-routed video generation.";
+        readonly adapterKey: "kling30";
+        readonly promptGrammarKey: "kling30";
+        readonly modelProfileKey: "kling30";
+        readonly routingRole: "primary-video";
+        readonly capabilities: {
+            readonly characterReference: true;
+            readonly storyboardReference: true;
+            readonly audioPlan: true;
+            readonly startEndFrames: true;
+            readonly customStoryboardPhases: true;
+            readonly maxStoryboardPhases: 4;
+        };
+        readonly docsVisibility: "public";
+    };
+    readonly "gpt-image-2": {
+        readonly id: "gpt-image-2";
+        readonly displayName: "GPT Image 2";
+        readonly provider: "openai";
+        readonly modalities: readonly ["image"];
+        readonly lifecycleStatus: "active";
+        readonly supportedPresets: readonly ["hybrid", "hybrid-smart", "gpt-image-smart", "studio"];
+        readonly supportedReferenceModes: readonly ["start-end", "storyboard-reference", "hybrid"];
+        readonly supportedAspects: readonly ["16:9", "9:16", "1:1"];
+        readonly durationPolicy: "Still-image model; video duration is not applicable.";
+        readonly adapterKey: "gptImage2";
+        readonly promptGrammarKey: "gptImage2";
+        readonly modelProfileKey: "gptImage2";
+        readonly routingRole: "image-reference";
+        readonly capabilities: {
+            readonly characterReference: true;
+            readonly storyboardReference: true;
+        };
+        readonly docsVisibility: "public";
+    };
+    readonly "gemini-3-pro-image-preview": {
+        readonly id: "gemini-3-pro-image-preview";
+        readonly displayName: "Gemini 3 Pro Image Preview";
+        readonly provider: "google";
+        readonly modalities: readonly ["image"];
+        readonly lifecycleStatus: "experimental";
+        readonly supportedPresets: readonly ["hybrid", "hybrid-smart"];
+        readonly supportedReferenceModes: readonly ["start-end", "storyboard-reference", "hybrid"];
+        readonly supportedAspects: readonly ["16:9", "9:16", "1:1"];
+        readonly durationPolicy: "Still-image model used by internal hybrid presets; video duration is not applicable.";
+        readonly adapterKey: "none";
+        readonly promptGrammarKey: "generic";
+        readonly modelProfileKey: "generic";
+        readonly routingRole: "image-reference";
+        readonly capabilities: {
+            readonly characterReference: true;
+            readonly storyboardReference: true;
+        };
+        readonly docsVisibility: "internal";
+    };
+    readonly "smart-dialogue-router": {
+        readonly id: "smart-dialogue-router";
+        readonly displayName: "Smart Dialogue Router";
+        readonly provider: "film-kit";
+        readonly modalities: readonly ["multimodal"];
+        readonly lifecycleStatus: "active";
+        readonly supportedPresets: readonly ["hybrid-smart", "gpt-image-smart"];
+        readonly supportedReferenceModes: readonly ["start-end", "storyboard-reference", "hybrid"];
+        readonly supportedAspects: readonly ["16:9", "9:16", "1:1"];
+        readonly durationPolicy: "Internal routing policy; routes dialogue/lip-sync to Veo and non-dialogue shots to Kling.";
+        readonly adapterKey: "none";
+        readonly promptGrammarKey: "generic";
+        readonly modelProfileKey: "generic";
+        readonly routingRole: "smart-router";
+        readonly capabilities: {
+            readonly smartRouting: true;
+            readonly audioPlan: true;
+            readonly dialogue: true;
+        };
+        readonly docsVisibility: "internal";
+    };
+    readonly veo2: {
+        readonly id: "veo2";
+        readonly displayName: "Veo 2";
+        readonly provider: "google";
+        readonly modalities: readonly ["video"];
+        readonly lifecycleStatus: "deprecated";
+        readonly supportedPresets: readonly ["single", "multi", "studio"];
+        readonly supportedReferenceModes: readonly ["start-end", "storyboard-reference"];
+        readonly supportedAspects: readonly ["16:9", "9:16", "1:1"];
+        readonly durationRange: {
+            readonly minSeconds: 4;
+            readonly maxSeconds: 8;
+        };
+        readonly durationPolicy: "Deprecated legacy video model kept only for migration warnings.";
+        readonly adapterKey: "generic";
+        readonly promptGrammarKey: "generic";
+        readonly modelProfileKey: "generic";
+        readonly routingRole: "legacy-video";
+        readonly capabilities: {
+            readonly characterReference: true;
+            readonly storyboardReference: true;
+            readonly audioPlan: true;
+            readonly dialogue: true;
+            readonly startEndFrames: true;
+            readonly customStoryboardPhases: true;
+            readonly maxStoryboardPhases: 4;
+        };
+        readonly deprecationMessage: "veo2 is deprecated. Use veo31 for current Film-Kit video generation.";
+        readonly replacementModelId: "veo31";
+        readonly docsVisibility: "hidden";
+    };
+    readonly "kling-2.0": {
+        readonly id: "kling-2.0";
+        readonly displayName: "Kling 2.0";
+        readonly provider: "kuaishou";
+        readonly modalities: readonly ["video"];
+        readonly lifecycleStatus: "removed";
+        readonly supportedPresets: readonly [];
+        readonly supportedReferenceModes: readonly [];
+        readonly supportedAspects: readonly ["16:9", "9:16", "1:1"];
+        readonly durationPolicy: "Removed legacy model. Do not route generation here.";
+        readonly adapterKey: "none";
+        readonly promptGrammarKey: "generic";
+        readonly modelProfileKey: "generic";
+        readonly routingRole: "removed";
+        readonly capabilities: {};
+        readonly deprecationMessage: "kling-2.0 has been removed from Film-Kit. Use kling-3.0 instead.";
+        readonly replacementModelId: "kling-3.0";
+        readonly docsVisibility: "hidden";
+    };
+};
+export type KnownModelId = keyof typeof MODEL_REGISTRY;
+type RegistryEntry<K extends KnownModelId = KnownModelId> = typeof MODEL_REGISTRY[K];
+type ModelIdWithLifecycle<Status extends ModelRegistryEntry["lifecycleStatus"]> = {
+    [K in KnownModelId]: RegistryEntry<K>["lifecycleStatus"] extends Status ? K : never;
+}[KnownModelId];
+type ModelIdWithModality<Modality extends ModelRegistryEntry["modalities"][number]> = {
+    [K in KnownModelId]: Modality extends RegistryEntry<K>["modalities"][number] ? K : never;
+}[KnownModelId];
+export type ActiveModelId = ModelIdWithLifecycle<"active" | "experimental">;
+export type DeprecatedModelId = ModelIdWithLifecycle<"deprecated">;
+export type RemovedModelId = ModelIdWithLifecycle<"removed">;
+export type VideoModelId = ModelIdWithModality<"video">;
+export type ImageModelId = ModelIdWithModality<"image">;
+export type AudioModelId = ModelIdWithModality<"audio">;
+export type MultimodalModelId = ModelIdWithModality<"multimodal">;
+export {};