@milenyumai/film-kit 2.3.3 → 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`

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;
 }
@@ -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 {};

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

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

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

@@ -0,0 +1,23 @@
+import { type ActiveModelId, type DeprecatedModelId, type ImageModelId, type KnownModelId, type RemovedModelId, type VideoModelId } from "./registry.js";
+import type { ModelAdapterKey, ModelRegistryEntry, ModelRegistryPreset, ModelRegistryReferenceMode } from "./types.js";
+export declare function getModel(id: string): ModelRegistryEntry | undefined;
+export declare function requireModel(id: string): ModelRegistryEntry;
+export declare function listModels(): ModelRegistryEntry[];
+export declare function listActiveModels(): ModelRegistryEntry[];
+export declare function listVideoModels(): ModelRegistryEntry[];
+export declare function listImageModels(): ModelRegistryEntry[];
+export declare function listModelsForPreset(preset: ModelRegistryPreset): ModelRegistryEntry[];
+export declare function listModelsForReferenceMode(referenceMode: ModelRegistryReferenceMode): ModelRegistryEntry[];
+export declare function listRunnableVideoModels(): ModelRegistryEntry[];
+export declare function listRunnableVideoModelIds(): VideoModelId[];
+export declare function listActiveVideoModelIds(): VideoModelId[];
+export declare function isKnownModelId(value: string): value is KnownModelId;
+export declare function isActiveModelId(value: string): value is ActiveModelId;
+export declare function isDeprecatedModelId(value: string): value is DeprecatedModelId;
+export declare function isRemovedModelId(value: string): value is RemovedModelId;
+export declare function isVideoModelId(value: string): value is VideoModelId;
+export declare function isImageModelId(value: string): value is ImageModelId;
+export declare function isModelSupportedByPreset(modelId: string, preset: ModelRegistryPreset): boolean;
+export declare function getModelAdapterKey(modelId: string): ModelAdapterKey;
+export declare function getReplacementModel(modelId: string): ModelRegistryEntry | undefined;
+export declare function getModelDisplayName(modelId: string): string;

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

@@ -0,0 +1,80 @@
+import { MODEL_REGISTRY } from "./registry.js";
+function entries() {
+    return Object.values(MODEL_REGISTRY);
+}
+function hasModality(model, modality) {
+    return model.modalities.includes(modality);
+}
+export function getModel(id) {
+    return MODEL_REGISTRY[id];
+}
+export function requireModel(id) {
+    const model = getModel(id);
+    if (!model) {
+        throw new Error(`Unknown model: ${id}.`);
+    }
+    return model;
+}
+export function listModels() {
+    return entries();
+}
+export function listActiveModels() {
+    return entries().filter(model => model.lifecycleStatus === "active" || model.lifecycleStatus === "experimental");
+}
+export function listVideoModels() {
+    return entries().filter(model => hasModality(model, "video"));
+}
+export function listImageModels() {
+    return entries().filter(model => hasModality(model, "image"));
+}
+export function listModelsForPreset(preset) {
+    return entries().filter(model => model.supportedPresets.includes(preset));
+}
+export function listModelsForReferenceMode(referenceMode) {
+    return entries().filter(model => model.supportedReferenceModes.includes(referenceMode));
+}
+export function listRunnableVideoModels() {
+    return listVideoModels().filter(model => model.lifecycleStatus !== "removed");
+}
+export function listRunnableVideoModelIds() {
+    return listRunnableVideoModels().map(model => model.id);
+}
+export function listActiveVideoModelIds() {
+    return listActiveModels()
+        .filter(model => hasModality(model, "video"))
+        .map(model => model.id);
+}
+export function isKnownModelId(value) {
+    return Object.prototype.hasOwnProperty.call(MODEL_REGISTRY, value);
+}
+export function isActiveModelId(value) {
+    const model = getModel(value);
+    return model?.lifecycleStatus === "active" || model?.lifecycleStatus === "experimental";
+}
+export function isDeprecatedModelId(value) {
+    return getModel(value)?.lifecycleStatus === "deprecated";
+}
+export function isRemovedModelId(value) {
+    return getModel(value)?.lifecycleStatus === "removed";
+}
+export function isVideoModelId(value) {
+    const model = getModel(value);
+    return Boolean(model && hasModality(model, "video"));
+}
+export function isImageModelId(value) {
+    const model = getModel(value);
+    return Boolean(model && hasModality(model, "image"));
+}
+export function isModelSupportedByPreset(modelId, preset) {
+    return Boolean(getModel(modelId)?.supportedPresets.includes(preset));
+}
+export function getModelAdapterKey(modelId) {
+    return requireModel(modelId).adapterKey;
+}
+export function getReplacementModel(modelId) {
+    const replacementModelId = getModel(modelId)?.replacementModelId;
+    return replacementModelId ? getModel(replacementModelId) : undefined;
+}
+export function getModelDisplayName(modelId) {
+    return requireModel(modelId).displayName;
+}

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

@@ -0,0 +1,59 @@
+export type ModelModality = "video" | "image" | "audio" | "multimodal";
+export type ModelLifecycleStatus = "active" | "experimental" | "deprecated" | "removed";
+export type ModelRegistryPreset = "single" | "multi" | "hybrid" | "hybrid-smart" | "gpt-image-smart" | "studio";
+export type ModelRegistryReferenceMode = "start-end" | "storyboard-reference" | "hybrid";
+export type ModelRegistryAspectRatio = "16:9" | "9:16" | "1:1";
+export type ModelAdapterKey = "veo31" | "seedance20" | "kling30" | "generic" | "gptImage2" | "none";
+export type PromptGrammarKey = "veo31" | "seedance20" | "kling30" | "gptImage2" | "generic";
+export type ModelProfileKey = "veo31" | "seedance20" | "kling30" | "gptImage2" | "generic";
+export type ModelRoutingRole = "primary-video" | "storyboard-video" | "image-reference" | "smart-router" | "legacy-video" | "removed";
+export interface ModelDurationRange {
+    minSeconds: number;
+    maxSeconds: number;
+}
+export interface ModelCapabilities {
+    characterReference?: boolean;
+    storyboardReference?: boolean;
+    multipleImageReferences?: boolean;
+    audioPlan?: boolean;
+    dialogue?: boolean;
+    startEndFrames?: boolean;
+    smartRouting?: boolean;
+    customStoryboardPhases?: boolean;
+    maxStoryboardPhases?: number;
+    maxReferenceImages?: number;
+    maxReferenceVideos?: number;
+    maxReferenceAudio?: number;
+    maxReferenceFiles?: number;
+}
+export interface ModelRegistryEntry {
+    id: string;
+    displayName: string;
+    provider: string;
+    modalities: readonly ModelModality[];
+    lifecycleStatus: ModelLifecycleStatus;
+    supportedPresets: readonly ModelRegistryPreset[];
+    supportedReferenceModes: readonly ModelRegistryReferenceMode[];
+    supportedAspects: readonly ModelRegistryAspectRatio[];
+    durationRange?: ModelDurationRange;
+    durationPolicy?: string;
+    adapterKey: ModelAdapterKey;
+    promptGrammarKey: PromptGrammarKey;
+    modelProfileKey: ModelProfileKey;
+    routingRole: ModelRoutingRole;
+    capabilities: ModelCapabilities;
+    deprecationMessage?: string;
+    replacementModelId?: string;
+    docsVisibility: "public" | "internal" | "hidden";
+}
+export interface ModelAllowedContext {
+    preset?: ModelRegistryPreset;
+    referenceMode?: ModelRegistryReferenceMode;
+    requiredModalities?: readonly ModelModality[];
+    allowDeprecated?: boolean;
+    usage?: string;
+}
+export interface ModelAllowedResult {
+    model: ModelRegistryEntry;
+    warnings: string[];
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+import type { ModelAllowedContext, ModelAllowedResult, ModelRegistryEntry } from "./types.js";
+export declare function validateModelAllowed(modelId: string, context?: ModelAllowedContext): ModelAllowedResult;
+export declare function assertModelAllowed(modelId: string, context?: ModelAllowedContext): ModelRegistryEntry;

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

@@ -0,0 +1,42 @@
+import { getModel, getReplacementModel, listRunnableVideoModelIds } from "./selectors.js";
+function formatModelList(models) {
+    return models.join(", ");
+}
+function hasRequiredModalities(model, required) {
+    return !required || required.every(modality => model.modalities.includes(modality));
+}
+export function validateModelAllowed(modelId, context = {}) {
+    const model = getModel(modelId);
+    const usage = context.usage ? `${context.usage} ` : "";
+    if (!model) {
+        throw new Error(`Unknown ${usage}model: ${modelId}. Supported video models: ${formatModelList(listRunnableVideoModelIds())}`);
+    }
+    if (model.lifecycleStatus === "removed") {
+        const replacement = getReplacementModel(model.id);
+        const replacementText = replacement ? ` Use ${replacement.id} instead.` : "";
+        throw new Error(`${model.deprecationMessage ?? `${model.id} has been removed.`}${replacementText}`);
+    }
+    if (!hasRequiredModalities(model, context.requiredModalities)) {
+        throw new Error(`Model ${model.id} is not valid for ${usage.trim() || "this usage"}. ` +
+            `Required modalities: ${context.requiredModalities?.join(", ") ?? "none"}.`);
+    }
+    if (context.preset && !model.supportedPresets.includes(context.preset)) {
+        throw new Error(`Model ${model.id} is not supported by preset ${context.preset}.`);
+    }
+    if (context.referenceMode && !model.supportedReferenceModes.includes(context.referenceMode)) {
+        throw new Error(`Model ${model.id} is not supported by reference mode ${context.referenceMode}.`);
+    }
+    const warnings = [];
+    if (model.lifecycleStatus === "deprecated") {
+        if (context.allowDeprecated === false) {
+            throw new Error(model.deprecationMessage ?? `Model ${model.id} is deprecated.`);
+        }
+        const replacement = getReplacementModel(model.id);
+        warnings.push(model.deprecationMessage
+            ?? `Model ${model.id} is deprecated.${replacement ? ` Use ${replacement.id} instead.` : ""}`);
+    }
+    return { model, warnings };
+}
+export function assertModelAllowed(modelId, context = {}) {
+    return validateModelAllowed(modelId, context).model;
+}

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

@@ -1,3 +1,4 @@
+import { getModelDisplayName } from "../../model-registry/index.js";
 export class BaseVideoModelPromptAdapter {
     validate(output) {
         const prompt = output.promptText;
@@ -53,9 +54,5 @@ export function formatPhaseLines(phases) {
         .join("\n");
 }
 export function getDisplayName(model) {
-    if (model === "seedance-2.0")
-        return "Seedance 2.0";
-    if (model === "kling-3.0")
-        return "Kling 3.0";
-    return "Veo 3.1";
+    return getModelDisplayName(model);
 }

package/build/lib/storyboard-reference/defaults.js

@@ -1,9 +1,10 @@
+import { listActiveVideoModelIds } from "../model-registry/index.js";
 export const STORYBOARD_REFERENCE_MODE = "storyboard-reference";
 export const DEFAULT_STORYBOARD_DURATION_SECONDS = 8;
 export const DEFAULT_STORYBOARD_ASPECT_RATIO = "16:9";
 export const DEFAULT_STORYBOARD_LANGUAGE = "NONE";
 export const DEFAULT_STORYBOARD_OUTPUT_DIR = "./outputs";
-export const DEFAULT_STORYBOARD_TARGET_MODELS = ["veo31", "seedance-2.0", "kling-3.0"];
+export const DEFAULT_STORYBOARD_TARGET_MODELS = listActiveVideoModelIds();
 export const DEFAULT_STORYBOARD_REFERENCE_RUNTIME = {
     enabled: true,
     maxStoryboardPhases: 4,

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

@@ -1,15 +1,47 @@
 import { resolveAssetRoles } from "./asset-role-resolver.js";
+import { GenericPromptAdapter } from "./adapters/generic.js";
 import { Kling30PromptAdapter } from "./adapters/kling30.js";
 import { Seedance20PromptAdapter } from "./adapters/seedance20.js";
 import { Veo31PromptAdapter } from "./adapters/veo31.js";
+import { getModelAdapterKey, requireModel } from "../model-registry/index.js";
 import { normalizeVideoPromptRequest } from "./request-normalizer.js";
 import { buildStoryboardPhaseBudget, inferContinuityMode, interpretStoryboard } from "./storyboard-interpreter.js";
 import { assertSafeStoryboardReferenceRequest, validateCharacterReferenceSheetPrompts, validateModelPromptOutput, validatePromptBundle } from "./validators.js";
 const ADAPTERS = {
     veo31: new Veo31PromptAdapter(),
-    "seedance-2.0": new Seedance20PromptAdapter(),
-    "kling-3.0": new Kling30PromptAdapter()
+    seedance20: new Seedance20PromptAdapter(),
+    kling30: new Kling30PromptAdapter()
 };
+function buildGenericCapabilities(model) {
+    const registryModel = requireModel(model);
+    const capabilities = {
+        supportsImageReference: Boolean(registryModel.capabilities.characterReference),
+        supportsMultipleImageReferences: Boolean(registryModel.capabilities.multipleImageReferences),
+        supportsStoryboardReference: Boolean(registryModel.capabilities.storyboardReference),
+        supportsAudio: Boolean(registryModel.capabilities.audioPlan),
+        supportsDialogue: Boolean(registryModel.capabilities.dialogue),
+        supportsCustomStoryboardPhases: Boolean(registryModel.capabilities.customStoryboardPhases),
+        preferredPromptShape: "natural-language"
+    };
+    if (registryModel.durationRange?.maxSeconds !== undefined) {
+        capabilities.maxDurationSeconds = registryModel.durationRange.maxSeconds;
+    }
+    if (registryModel.capabilities.maxStoryboardPhases !== undefined) {
+        capabilities.maxStoryboardPhases = registryModel.capabilities.maxStoryboardPhases;
+    }
+    return capabilities;
+}
+function resolvePromptAdapter(model) {
+    const adapterKey = getModelAdapterKey(model);
+    if (adapterKey === "generic") {
+        return new GenericPromptAdapter(model, buildGenericCapabilities(model));
+    }
+    const adapter = ADAPTERS[adapterKey];
+    if (!adapter) {
+        throw new Error(`Model ${model} does not have a storyboard-reference video adapter.`);
+    }
+    return adapter;
+}
 function getStoryboardPanelCount(request, phaseBudget) {
     return request.storyboardPanelCountHint
         ?? request.shotCountHint
@@ -320,7 +352,7 @@ function buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits
 function buildModelPrompts(request, bundleInput) {
     const modelPrompts = {};
     for (const model of request.targetModels) {
-        const adapter = ADAPTERS[model];
+        const adapter = resolvePromptAdapter(model);
         const output = adapter.buildPrompt({ ...bundleInput, request });
         const validatorQa = validateModelPromptOutput(output);
         output.qa = {

package/build/lib/storyboard-reference/request-normalizer.js

@@ -1,5 +1,5 @@
+import { validateModelAllowed } from "../model-registry/index.js";
 import { DEFAULT_STORYBOARD_ASPECT_RATIO, DEFAULT_STORYBOARD_DURATION_SECONDS, DEFAULT_STORYBOARD_LANGUAGE, DEFAULT_STORYBOARD_OUTPUT_DIR, DEFAULT_STORYBOARD_TARGET_MODELS, STORYBOARD_REFERENCE_MODE, resolveStoryboardReferenceRuntime } from "./defaults.js";
-const SUPPORTED_MODELS = ["veo31", "seedance-2.0", "kling-3.0"];
 const SUPPORTED_ASPECT_RATIOS = ["16:9", "9:16", "1:1"];
 function normalizePositiveInteger(value, fallback, fieldName) {
     const normalized = value ?? fallback;
@@ -13,9 +13,11 @@ function assertSupportedModels(models) {
         return DEFAULT_STORYBOARD_TARGET_MODELS.slice();
     }
     for (const model of models) {
-        if (!SUPPORTED_MODELS.includes(model)) {
-            throw new Error(`Unsupported target model: ${model}. Supported: ${SUPPORTED_MODELS.join(", ")}`);
-        }
+        validateModelAllowed(model, {
+            requiredModalities: ["video"],
+            referenceMode: STORYBOARD_REFERENCE_MODE,
+            usage: "storyboard target"
+        });
     }
     return Array.from(new Set(models));
 }

package/build/lib/types.d.ts

@@ -1,5 +1,6 @@
+import type { VideoModelId } from "./model-registry/index.js";
 export type SupportedPlatform = "cursor" | "claude" | "copilot" | "antigravity" | "codex";
-export type SupportedModel = "veo31" | "kling-3.0" | "seedance-2.0";
+export type SupportedModel = VideoModelId;
 export type KlingPreset = "ultra-realism" | "balanced" | "custom";
 export type FilmKitPreset = "single" | "multi" | "hybrid" | "hybrid-smart" | "gpt-image-smart" | "studio";
 export type ReferenceMode = "start-end" | "storyboard-reference" | "hybrid";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milenyumai/film-kit",
-  "version": "2.3.3",
+  "version": "2.3.4",
   "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",
@@ -36,6 +36,7 @@
     "packages/gpt-image-smart/content",
     "packages/studio/content",
     "content",
+    "MODEL_REGISTRY.md",
     "README.md",
     "LICENSE"
   ],