videoclaw 3.0.0-alpha.1

package/dist/video/shot-grammar.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Camera-bible shot grammar — shot sizes, angles, movements, and the
+ * sensory-words rule, each annotated with its emotional trigger.
+ *
+ * Pure, deterministic descriptive registries. No I/O, no network. This is the
+ * cinematography "why" layer (what each choice MEANS and which words to give an
+ * AI model) that complements the quantified emitters in {@link ./cinematography}
+ * (Kelvin / key-angle / velocity). The {@link ./project-blueprint} normalizer and
+ * the {@link ./filmmaking-prompts} composer draw on these to turn a director's
+ * intent into provider-ready prompt fragments.
+ *
+ * Source: the operator-supplied camera-bible reference
+ * (references/video/camera-bible.md).
+ */
+/** Canonical shot-size ids. Order is intentional (widest → tightest, then the
+ *  relational / special framings); callers may iterate {@link SHOT_SIZE_IDS}. */
+export declare const SHOT_SIZE_IDS: readonly ["ews", "ws", "mws", "ms", "mcu", "cu", "ecu", "two-shot", "ots", "pov", "dutch", "birds-eye", "worms-eye"];
+export type ShotSizeId = (typeof SHOT_SIZE_IDS)[number];
+export interface ShotSize {
+    /** Human label, e.g. `Extreme Wide Shot`. */
+    label: string;
+    /** Short abbreviation as a director would write it, e.g. `EWS`. */
+    abbr: string;
+    /** The one-line emotional function this framing serves. */
+    emotion: string;
+    /** What the framing SAYS to the audience. */
+    says: string;
+    /** Ready-to-paste AI prompt words for this framing. */
+    promptWords: string;
+}
+/**
+ * Resolve a shot size by id, falling back to `ms` (the neutral, honest default)
+ * for unknown ids rather than throwing — mirrors {@link cinemaMode}.
+ */
+export declare function shotSize(id: string): ShotSize;
+/** Canonical camera-angle ids. */
+export declare const CAMERA_ANGLE_IDS: readonly ["low", "eye-level", "high", "overhead", "canted"];
+export type CameraAngleId = (typeof CAMERA_ANGLE_IDS)[number];
+/**
+ * Resolve a camera angle's emotional effect, falling back to `eye-level` for
+ * unknown ids.
+ */
+export declare function cameraAngle(id: string): string;
+/** Camera-bible movement ids — a DESCRIPTIVE registry (emotion + Seedance
+ *  syntax + prompt words). Intentionally separate from the typed
+ *  {@link CameraMovement} union in {@link ./cinematography}; this registry adds
+ *  crane-up / whip-pan / vertigo without touching that union's exhaustive
+ *  velocity / qualifier / prose Records. */
+export declare const MOVEMENT_GRAMMAR_IDS: readonly ["static-locked", "dolly-in", "dolly-out", "pan", "tilt-up", "tilt-down", "orbit", "tracking", "handheld", "crane-up", "whip-pan", "vertigo"];
+export type MovementGrammarId = (typeof MOVEMENT_GRAMMAR_IDS)[number];
+export interface MovementGrammar {
+    emotion: string;
+    /** Provider-friendly (Seedance) syntax token(s). */
+    seedanceSyntax: string;
+    promptWords: string;
+    /** Movements that lose all power if repeated; the composer should warn when
+     *  one appears more than once. */
+    useOnce?: boolean;
+}
+/**
+ * Resolve a movement grammar by id, falling back to `static-locked` (the most
+ * underused, most powerful move) for unknown ids.
+ */
+export declare function movementGrammar(id: string): MovementGrammar;
+/**
+ * The atmosphere/sensory signature — the camera-bible "secret weapon" rule:
+ * ALWAYS exactly five sensory words per scene (one smell, one texture, one
+ * sound, two feelings). Sensory language activates a deeper, more instinctive
+ * visual library in the model than purely visual description.
+ */
+export interface SensorySignature {
+    smell: string;
+    texture: string;
+    sound: string;
+    /** Exactly two feelings. */
+    feelings: [string, string];
+}
+/**
+ * Render a {@link SensorySignature} as the canonical five-word, slash-joined
+ * clause, e.g. `incense / worn tatami / brush on paper / restraint / waiting`.
+ * Empty fields are dropped so a partial signature still produces a clean line.
+ */
+export declare function sensoryClause(sig: SensorySignature): string;
+/**
+ * Prefix the sensory clause with an `Atmosphere:` label for inlining into a
+ * scene prompt. Returns an empty string when the signature renders empty.
+ */
+export declare function sensoryLine(sig: SensorySignature): string;
+/** The three framing intents a character blueprint declares. */
+export type FramingIntent = 'power' | 'vulnerability' | 'signature';
+export interface FramingRecommendation {
+    shotId: ShotSizeId;
+    angleId: CameraAngleId;
+    note: string;
+}
+/**
+ * Default camera-framing recommendation for a framing intent. A blueprint's
+ * per-character `cameraLanguage` strings take precedence; this is the
+ * deterministic fallback when a character declares an intent but no explicit
+ * framing.
+ */
+export declare function framingFor(intent: FramingIntent): FramingRecommendation;
+//# sourceMappingURL=shot-grammar.d.ts.map

package/dist/video/shot-grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shot-grammar.d.ts","sourceRoot":"","sources":["../../src/video/shot-grammar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;iFACiF;AACjF,eAAO,MAAM,aAAa,sHAchB,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;CACrB;AAgGD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAE7C;AAED,kCAAkC;AAClC,eAAO,MAAM,gBAAgB,6DAA8D,CAAC;AAE5F,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAU9D;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;4CAI4C;AAC5C,eAAO,MAAM,oBAAoB,wJAavB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB;sCACkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAmED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,CAE3D;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAK3D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAGzD;AAED,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,eAAe,GAAG,WAAW,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,qBAAqB,CAsBvE"}

package/dist/video/shot-grammar.js

@@ -0,0 +1,286 @@
+/**
+ * Camera-bible shot grammar — shot sizes, angles, movements, and the
+ * sensory-words rule, each annotated with its emotional trigger.
+ *
+ * Pure, deterministic descriptive registries. No I/O, no network. This is the
+ * cinematography "why" layer (what each choice MEANS and which words to give an
+ * AI model) that complements the quantified emitters in {@link ./cinematography}
+ * (Kelvin / key-angle / velocity). The {@link ./project-blueprint} normalizer and
+ * the {@link ./filmmaking-prompts} composer draw on these to turn a director's
+ * intent into provider-ready prompt fragments.
+ *
+ * Source: the operator-supplied camera-bible reference
+ * (references/video/camera-bible.md).
+ */
+/** Canonical shot-size ids. Order is intentional (widest → tightest, then the
+ *  relational / special framings); callers may iterate {@link SHOT_SIZE_IDS}. */
+export const SHOT_SIZE_IDS = [
+    'ews',
+    'ws',
+    'mws',
+    'ms',
+    'mcu',
+    'cu',
+    'ecu',
+    'two-shot',
+    'ots',
+    'pov',
+    'dutch',
+    'birds-eye',
+    'worms-eye',
+];
+const SHOT_SIZES = {
+    ews: {
+        label: 'Extreme Wide Shot',
+        abbr: 'EWS',
+        emotion: 'isolation, scale, overwhelm, loneliness',
+        says: 'the character is tiny; the world is vast and they are small in it',
+        promptWords: 'extreme wide shot, subject tiny in vast environment, isolation, scale',
+    },
+    ws: {
+        label: 'Wide Shot',
+        abbr: 'WS',
+        emotion: 'context, arrival, journey, placement',
+        says: 'the character exists within a world larger than themselves',
+        promptWords: 'wide shot, full environment visible, character placed in world',
+    },
+    mws: {
+        label: 'Medium Wide Shot',
+        abbr: 'MWS',
+        emotion: 'action, physical storytelling, posture reads',
+        says: 'full body visible — how they carry themselves tells us who they are',
+        promptWords: 'medium wide shot, full body visible, posture and movement readable',
+    },
+    ms: {
+        label: 'Medium Shot',
+        abbr: 'MS',
+        emotion: 'conversation, relationship, neutrality',
+        says: 'normal human distance, no agenda, just listening',
+        promptWords: 'medium shot, waist up, eye level, neutral, conversational',
+    },
+    mcu: {
+        label: 'Medium Close-Up',
+        abbr: 'MCU',
+        emotion: 'emotional engagement beginning, investment',
+        says: 'we are starting to feel WITH this person, not just watch them',
+        promptWords: 'medium close-up, chest to head, emotional engagement, investment',
+    },
+    cu: {
+        label: 'Close-Up',
+        abbr: 'CU',
+        emotion: 'deep emotion, truth, vulnerability, revelation',
+        says: "this person's inner life IS the story right now",
+        promptWords: 'close-up, face fills frame, emotion is the subject, shallow depth of field',
+    },
+    ecu: {
+        label: 'Extreme Close-Up',
+        abbr: 'ECU',
+        emotion: 'obsession, dread, the world narrows to one thing',
+        says: 'this single detail IS everything; nothing else exists',
+        promptWords: 'extreme close-up, one specific element fills entire frame, world narrows',
+    },
+    'two-shot': {
+        label: 'Two-Shot',
+        abbr: '2S',
+        emotion: 'relationship, tension, contrast, dynamic between two people',
+        says: 'the space between them tells us everything',
+        promptWords: 'two-shot, both characters in frame, charged space between them',
+    },
+    ots: {
+        label: 'Over The Shoulder',
+        abbr: 'OTS',
+        emotion: 'perspective, shared view, we are in the conversation',
+        says: 'we see what this character sees; we share their position',
+        promptWords: 'over the shoulder shot, camera behind one character looking at the other',
+    },
+    pov: {
+        label: 'Point of View',
+        abbr: 'POV',
+        emotion: 'full immersion, we ARE the character, first person',
+        says: 'this is not observation — this is experience',
+        promptWords: 'point of view shot, first person perspective, we are the character',
+    },
+    dutch: {
+        label: 'Dutch Angle',
+        abbr: 'DA',
+        emotion: 'psychological unease, instability, something is wrong',
+        says: "the world is tilted; normal rules don't apply here",
+        promptWords: 'dutch angle, tilted frame 15-30 degrees, horizon line wrong, unease',
+    },
+    'birds-eye': {
+        label: "Bird's Eye / Top Down",
+        abbr: 'BA',
+        emotion: 'detachment, god view, pattern, insignificance',
+        says: 'we observe from above, removed from the character experience',
+        promptWords: "bird's eye view, camera directly overhead, top-down, subject seen as pattern",
+    },
+    'worms-eye': {
+        label: "Worm's Eye",
+        abbr: 'WE',
+        emotion: 'overwhelm, the subject is massive, we are small',
+        says: 'looking up makes the subject dominant, threatening, or heroic',
+        promptWords: "worm's eye view, camera at ground level looking up, subject towers against sky",
+    },
+};
+/**
+ * Resolve a shot size by id, falling back to `ms` (the neutral, honest default)
+ * for unknown ids rather than throwing — mirrors {@link cinemaMode}.
+ */
+export function shotSize(id) {
+    return SHOT_SIZES[id] ?? SHOT_SIZES.ms;
+}
+/** Canonical camera-angle ids. */
+export const CAMERA_ANGLE_IDS = ['low', 'eye-level', 'high', 'overhead', 'canted'];
+const CAMERA_ANGLES = {
+    low: 'subject looks powerful, heroic, threatening',
+    'eye-level': 'neutral, equal, honest, natural',
+    high: 'subject looks small, judged, vulnerable',
+    overhead: 'abstract, pattern, emotionally removed',
+    canted: 'psychological unease, instability',
+};
+/**
+ * Resolve a camera angle's emotional effect, falling back to `eye-level` for
+ * unknown ids.
+ */
+export function cameraAngle(id) {
+    return CAMERA_ANGLES[id] ?? CAMERA_ANGLES['eye-level'];
+}
+/** Camera-bible movement ids — a DESCRIPTIVE registry (emotion + Seedance
+ *  syntax + prompt words). Intentionally separate from the typed
+ *  {@link CameraMovement} union in {@link ./cinematography}; this registry adds
+ *  crane-up / whip-pan / vertigo without touching that union's exhaustive
+ *  velocity / qualifier / prose Records. */
+export const MOVEMENT_GRAMMAR_IDS = [
+    'static-locked',
+    'dolly-in',
+    'dolly-out',
+    'pan',
+    'tilt-up',
+    'tilt-down',
+    'orbit',
+    'tracking',
+    'handheld',
+    'crane-up',
+    'whip-pan',
+    'vertigo',
+];
+const MOVEMENT_GRAMMAR = {
+    'static-locked': {
+        emotion: 'authority, calm, indifference — the world accepts what is happening',
+        seedanceSyntax: 'static camera, locked off',
+        promptWords: 'static locked camera, zero movement, locked tripod, absolute stillness',
+    },
+    'dolly-in': {
+        emotion: 'tension builds, revelation approaching, we enter someone’s interior',
+        seedanceSyntax: 'slow dolly in',
+        promptWords: 'slow dolly in, camera pushes toward subject, tension building, revelation',
+    },
+    'dolly-out': {
+        emotion: 'isolation, scale revealed, character left alone, endings',
+        seedanceSyntax: 'slow dolly out',
+        promptWords: 'slow dolly out, camera retreats, subject grows smaller, isolation, release',
+    },
+    pan: {
+        emotion: 'reveal, following action, world opening in one direction',
+        seedanceSyntax: 'pan left / pan right',
+        promptWords: 'controlled pan, camera rotates horizontally, revealing space',
+    },
+    'tilt-up': {
+        emotion: 'awe, aspiration, power — the subject is greater than we realized',
+        seedanceSyntax: 'tilt up',
+        promptWords: 'slow tilt up, camera rotates upward, subject revealed bottom to top, awe',
+    },
+    'tilt-down': {
+        emotion: 'shame, defeat, weight, judgment from above',
+        seedanceSyntax: 'tilt down',
+        promptWords: 'slow tilt down, camera rotates downward, gravity, defeat, weight',
+    },
+    orbit: {
+        emotion: 'wonder, examination, god-like observation, nothing hidden',
+        seedanceSyntax: 'slow orbit left / orbit right',
+        promptWords: 'slow orbit, camera arcs around subject, wonder, examination',
+    },
+    tracking: {
+        emotion: 'journey, accompaniment, we walk with them',
+        seedanceSyntax: 'tracking shot',
+        promptWords: 'tracking shot, camera follows subject at same distance, journey, witness',
+    },
+    handheld: {
+        // CRITICAL for Seedance: keep "subtle" or the model shakes too violently.
+        emotion: 'intimacy, reality, urgency, documentary truth',
+        seedanceSyntax: 'handheld, subtle',
+        promptWords: 'subtle handheld, organic human sway, documentary feel, intimate, NOT shaky',
+    },
+    'crane-up': {
+        emotion: 'transcendence, release, story ending — we rise above and see the whole',
+        seedanceSyntax: 'slow crane up',
+        promptWords: 'slow crane up, camera rises above scene, transcendence, story releasing',
+    },
+    'whip-pan': {
+        emotion: 'surprise, energy shift, time skip, momentum',
+        seedanceSyntax: 'whip pan left / whip pan right',
+        promptWords: 'whip pan, fast horizontal snap, motion blur smear, energy shift',
+    },
+    vertigo: {
+        emotion: 'existential dread, reality shifting, something deeply wrong',
+        seedanceSyntax: 'dolly out while zooming in',
+        promptWords: 'vertigo effect, dolly out while zooming in, background warps, subject stays, dread',
+        useOnce: true,
+    },
+};
+/**
+ * Resolve a movement grammar by id, falling back to `static-locked` (the most
+ * underused, most powerful move) for unknown ids.
+ */
+export function movementGrammar(id) {
+    return MOVEMENT_GRAMMAR[id] ?? MOVEMENT_GRAMMAR['static-locked'];
+}
+/**
+ * Render a {@link SensorySignature} as the canonical five-word, slash-joined
+ * clause, e.g. `incense / worn tatami / brush on paper / restraint / waiting`.
+ * Empty fields are dropped so a partial signature still produces a clean line.
+ */
+export function sensoryClause(sig) {
+    return [sig.smell, sig.texture, sig.sound, sig.feelings?.[0], sig.feelings?.[1]]
+        .map((word) => (typeof word === 'string' ? word.trim() : ''))
+        .filter(Boolean)
+        .join(' / ');
+}
+/**
+ * Prefix the sensory clause with an `Atmosphere:` label for inlining into a
+ * scene prompt. Returns an empty string when the signature renders empty.
+ */
+export function sensoryLine(sig) {
+    const clause = sensoryClause(sig);
+    return clause ? `Atmosphere: ${clause}` : '';
+}
+/**
+ * Default camera-framing recommendation for a framing intent. A blueprint's
+ * per-character `cameraLanguage` strings take precedence; this is the
+ * deterministic fallback when a character declares an intent but no explicit
+ * framing.
+ */
+export function framingFor(intent) {
+    switch (intent) {
+        case 'power':
+            return {
+                shotId: 'mcu',
+                angleId: 'low',
+                note: 'low angle renders the subject dominant — they fill and command the frame',
+            };
+        case 'vulnerability':
+            return {
+                shotId: 'cu',
+                angleId: 'high',
+                note: 'high angle from above renders the subject small, exposed, and judged',
+            };
+        case 'signature':
+        default:
+            return {
+                shotId: 'ms',
+                angleId: 'eye-level',
+                note: 'the neutral defining frame — honest, equal, at human distance',
+            };
+    }
+}
+//# sourceMappingURL=shot-grammar.js.map

package/dist/video/shot-grammar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shot-grammar.js","sourceRoot":"","sources":["../../src/video/shot-grammar.ts"],"names":[],"mappings":"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"}

package/dist/video/show-bible.d.ts

@@ -0,0 +1,113 @@
+export interface ShowCastMember {
+    name: string;
+    /** Visual descriptor (from the character profile). */
+    description?: string;
+    /** Character-sheet reference (image path / Asset URI), when known. */
+    sheetRef?: string;
+    /** Bound voice clone name, when the character has one. */
+    voice?: string;
+}
+export interface ShowLocation {
+    name: string;
+    description?: string;
+    /** Key-visual / plate reference, when known. */
+    plateRef?: string;
+    /**
+     * Multi-angle view labels for this location. Author-supplied via `--from-json`
+     * sources — the auto-derive path reads single-view environment plates
+     * (`environment-assets.json`), which carry no view labels, so deriving leaves
+     * this empty.
+     */
+    views?: string[];
+}
+export interface ShowVoice {
+    name: string;
+    /** Character this voice belongs to, when bound. */
+    character?: string;
+    /** The blank-video-with-audio clip path. */
+    clipPath?: string;
+    description?: string;
+}
+export interface ShowEpisode {
+    /** Stable episode id, e.g. "ep01". */
+    id: string;
+    title: string;
+    logline?: string;
+    /** Optional scene briefs for the episode. */
+    scenes?: string[];
+}
+export interface ShowBibleArtifact {
+    schemaVersion: 1;
+    projectSlug: string;
+    generatedAt: string;
+    showTitle: string;
+    premise?: string;
+    /** The locked art style of the world (one line). */
+    style?: string;
+    cast: ShowCastMember[];
+    locations: ShowLocation[];
+    voices: ShowVoice[];
+    episodes: ShowEpisode[];
+}
+export declare function showBiblePathFor(root: string, slug: string): string;
+export declare function writeShowBible(root: string, slug: string, artifact: ShowBibleArtifact): Promise<void>;
+/** Read `artifacts/show-bible.json` (null when absent). */
+export declare function readShowBible(root: string, slug: string): Promise<ShowBibleArtifact | null>;
+/** The already-loaded project artifacts the assembler derives the bible from. */
+export interface ShowBibleSources {
+    characters?: Array<{
+        name: string;
+        description?: string;
+        referenceAssets?: string[];
+    }>;
+    environments?: Array<{
+        name: string;
+        description?: string;
+        plateRef?: string;
+        plateUrl?: string;
+        views?: Array<{
+            view: string;
+        }>;
+    }>;
+    voices?: Array<{
+        name: string;
+        character?: string;
+        clipPath?: string;
+        description?: string;
+    }>;
+    /** A pre-existing bible to merge episodes/overrides onto (e.g. the persisted one). */
+    existing?: ShowBibleArtifact | null;
+}
+export interface BuildShowBibleInput {
+    projectSlug: string;
+    generatedAt: string;
+    showTitle?: string;
+    premise?: string;
+    style?: string;
+    sources: ShowBibleSources;
+    /** Episodes to append/replace (matched by id). */
+    episodes?: ShowEpisode[];
+}
+/**
+ * Assemble the show bible deterministically. Cast is derived from character
+ * profiles; voices are matched onto cast by their `character` binding (so a cast
+ * member surfaces its bound voice). Locations come from environment assets.
+ * Episodes merge by id (new replaces old). All overrides (title/premise/style) fall
+ * back to the existing bible, then to sensible defaults. PURE.
+ */
+export declare function buildShowBible(input: BuildShowBibleInput): ShowBibleArtifact;
+/**
+ * Parse an `--add-episode "id|title|logline"` spec into a ShowEpisode. The id and
+ * title are required; logline is optional. Throws on a malformed spec (code 1).
+ */
+export declare function parseEpisodeSpec(spec: string): ShowEpisode;
+/**
+ * Validate + normalize an operator-authored show bible (from --from-json). Strict on
+ * the required envelope; coerces arrays to empty when missing. Throws (code 1) on a
+ * structurally invalid bible.
+ */
+export declare function validateShowBible(raw: unknown, ctx: {
+    projectSlug: string;
+    generatedAt: string;
+}): ShowBibleArtifact;
+//# sourceMappingURL=show-bible.d.ts.map

package/dist/video/show-bible.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"show-bible.d.ts","sourceRoot":"","sources":["../../src/video/show-bible.ts"],"names":[],"mappings":"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"}

package/dist/video/show-bible.js

@@ -0,0 +1,140 @@
+/**
+ * Show bible — the cartoon-SHOW asset library index.
+ *
+ * Source of truth: the Jack-Vs-AI "cartoon show" workflow (the whole video). Its
+ * thesis is a REPEATABLE production system: a single reusable world of characters +
+ * locations + voices that you recombine across MANY episodes, all consistent. The
+ * existing per-project artifacts (characters.json, environment-assets.json,
+ * voice-clones.json, brand-definition) each cover one asset kind; nothing ties them
+ * into a SHOW that spans episodes. This module is that index.
+ *
+ * It is distinct from:
+ *   - story-bible (per-project narrative continuity: cast/settings/props/timeline of
+ *     ONE production), and
+ *   - director-blueprint (visual direction: color/lighting/forbidden moves).
+ * The show bible is the multi-episode ASSET LIBRARY: which cast, which locations,
+ * which voices, which style, and the EPISODE list of the world.
+ *
+ * Deterministic/pure: `buildShowBible()` assembles the bible from the project's
+ * existing artifacts (passed in by the handler, which does the I/O) plus optional
+ * operator overrides. `validateShowBible()` normalizes an operator-authored bible.
+ * No provider calls.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { resolveProjectWorkspace } from './workspace.js';
+import { writeTextFileAtomic } from './atomic-write.js';
+export function showBiblePathFor(root, slug) {
+    return join(resolveProjectWorkspace(slug, root).artifactsDir, 'show-bible.json');
+}
+export async function writeShowBible(root, slug, artifact) {
+    const path = showBiblePathFor(root, slug);
+    await mkdir(dirname(path), { recursive: true });
+    await writeTextFileAtomic(path, `${JSON.stringify(artifact, null, 2)}\n`);
+}
+/** Read `artifacts/show-bible.json` (null when absent). */
+export async function readShowBible(root, slug) {
+    const path = showBiblePathFor(root, slug);
+    if (!existsSync(path))
+        return null;
+    return JSON.parse(await readFile(path, 'utf-8'));
+}
+/**
+ * Assemble the show bible deterministically. Cast is derived from character
+ * profiles; voices are matched onto cast by their `character` binding (so a cast
+ * member surfaces its bound voice). Locations come from environment assets.
+ * Episodes merge by id (new replaces old). All overrides (title/premise/style) fall
+ * back to the existing bible, then to sensible defaults. PURE.
+ */
+export function buildShowBible(input) {
+    const existing = input.sources.existing ?? null;
+    const voiceByCharacter = new Map();
+    const voices = (input.sources.voices ?? []).map((v) => {
+        const voice = {
+            name: v.name,
+            ...(v.character ? { character: v.character } : {}),
+            ...(v.clipPath ? { clipPath: v.clipPath } : {}),
+            ...(v.description ? { description: v.description } : {}),
+        };
+        if (v.character)
+            voiceByCharacter.set(v.character.toLowerCase(), voice);
+        return voice;
+    });
+    const cast = (input.sources.characters ?? []).map((c) => {
+        const boundVoice = voiceByCharacter.get(c.name.toLowerCase());
+        return {
+            name: c.name,
+            ...(c.description ? { description: c.description } : {}),
+            ...(c.referenceAssets?.[0] ? { sheetRef: c.referenceAssets[0] } : {}),
+            ...(boundVoice ? { voice: boundVoice.name } : {}),
+        };
+    });
+    const locations = (input.sources.environments ?? []).map((e) => ({
+        name: e.name,
+        ...(e.description ? { description: e.description } : {}),
+        ...(e.plateUrl || e.plateRef ? { plateRef: e.plateUrl || e.plateRef } : {}),
+        ...(Array.isArray(e.views) && e.views.length > 0
+            ? { views: e.views.map((v) => v.view) }
+            : {}),
+    }));
+    // Merge episodes: start from existing, replace/append by id.
+    const episodeById = new Map();
+    for (const ep of existing?.episodes ?? [])
+        episodeById.set(ep.id, ep);
+    for (const ep of input.episodes ?? [])
+        episodeById.set(ep.id, ep);
+    const episodes = [...episodeById.values()];
+    return {
+        schemaVersion: 1,
+        projectSlug: input.projectSlug,
+        generatedAt: input.generatedAt,
+        showTitle: input.showTitle ?? existing?.showTitle ?? input.projectSlug,
+        ...(input.premise ?? existing?.premise ? { premise: input.premise ?? existing?.premise } : {}),
+        ...(input.style ?? existing?.style ? { style: input.style ?? existing?.style } : {}),
+        cast,
+        locations,
+        voices,
+        episodes,
+    };
+}
+/**
+ * Parse an `--add-episode "id|title|logline"` spec into a ShowEpisode. The id and
+ * title are required; logline is optional. Throws on a malformed spec (code 1).
+ */
+export function parseEpisodeSpec(spec) {
+    const parts = spec.split('|').map((p) => p.trim());
+    const [id, title, logline] = parts;
+    if (!id || !title) {
+        throw new Error(`--add-episode expects "id|title[|logline]"; got ${JSON.stringify(spec)}.`);
+    }
+    return { id, title, ...(logline ? { logline } : {}) };
+}
+/**
+ * Validate + normalize an operator-authored show bible (from --from-json). Strict on
+ * the required envelope; coerces arrays to empty when missing. Throws (code 1) on a
+ * structurally invalid bible.
+ */
+export function validateShowBible(raw, ctx) {
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('show-bible --from-json must be a JSON object.');
+    }
+    const obj = raw;
+    if (!obj.showTitle || typeof obj.showTitle !== 'string') {
+        throw new Error('show-bible requires a string "showTitle".');
+    }
+    const asArray = (v) => (Array.isArray(v) ? v : []);
+    return {
+        schemaVersion: 1,
+        projectSlug: ctx.projectSlug,
+        generatedAt: ctx.generatedAt,
+        showTitle: obj.showTitle,
+        ...(obj.premise ? { premise: obj.premise } : {}),
+        ...(obj.style ? { style: obj.style } : {}),
+        cast: asArray(obj.cast),
+        locations: asArray(obj.locations),
+        voices: asArray(obj.voices),
+        episodes: asArray(obj.episodes),
+    };
+}
+//# sourceMappingURL=show-bible.js.map