@slatesvideo/shared 0.6.2 → 0.6.4

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

@@ -0,0 +1,154 @@
+/**
+ * SHOT GRAMMAR — the buckets that COUNT framing, and the measured speech rate.
+ *
+ * 🚨 KEEP THIS A DEPENDENCY-FREE LEAF, exported from its own subpath
+ * (`@slatesvideo/shared/shot-grammar`). The desktop imports it from
+ * `slate/src/shared/` for the variety counter and the fit check, and the same
+ * two reasons that made `model-capabilities.ts` a leaf apply verbatim: the root
+ * barrel re-exports `auth.js` → `node:fs` (breaks renderer bundling) and
+ * `/prompts` drags the 5,000-word tips corpus in with no `require` condition.
+ *
+ * 🚨 BUCKETS EXIST TO COUNT, NEVER TO CONSTRAIN. `rules/ads/cinematic-storyboard.md`
+ * §4e, reconciled against ByteDance's own ModelArk docs: *"Camera vocabulary is
+ * open standard language and includes shot size (close-up / medium / wide) —
+ * not a closed list of eight moves."* Authoring `shotSize` and `camera` is FREE
+ * TEXT. A value matching no bucket counts as `other` and is never rejected,
+ * rewritten, or warned about. This module is the ONE home for these names —
+ * a second bucket list anywhere downstream is the drift `MODEL_CAPABILITIES`
+ * was created to end.
+ */
+export declare const SHOT_SIZE_BUCKETS: readonly ["wide", "medium", "close", "extreme-close", "other"];
+export type ShotSizeBucket = (typeof SHOT_SIZE_BUCKETS)[number];
+export declare const CAMERA_MOVE_BUCKETS: readonly ["static", "push", "pull", "handheld", "orbit", "crane", "other"];
+export type CameraMoveBucket = (typeof CAMERA_MOVE_BUCKETS)[number];
+/** Which shot-size bucket a free-text value counts in. Never rejects. */
+export declare function bucketShotSize(raw: string | null | undefined): ShotSizeBucket;
+/** Which camera-move bucket a free-text value counts in. Never rejects. */
+export declare function bucketCameraMove(raw: string | null | undefined): CameraMoveBucket;
+/** Human label for a bucket, for a header strip or an op result. Derived from
+ *  the bucket name so a seventh bucket cannot ship without a label. */
+export declare function bucketLabel(bucket: ShotSizeBucket | CameraMoveBucket): string;
+/**
+ * 🚨 MEASURED, NOT CITED — and the corpus is ours.
+ *
+ * An earlier draft of the plan that introduced this said no source existed and
+ * deferred the fit check. That was a claim about the world made without looking:
+ * `second-brain/business/projects/slates/content-strategy/examples/ad-research.db`
+ * carries `transcript` and `duration_seconds` on every row and always did.
+ *
+ * ⚠️ IT IS A CORPUS STATISTIC, SO IT DECAYS AND MUST STAY RE-DERIVABLE.
+ * `SPEECH_RATE_QUERY` below is the exact derivation; a constant whose query no
+ * longer reproduces it is STALE, not wrong — update the number and the `n`
+ * together. Same discipline as the pSEO `verifiedOn` dates. What it must never
+ * become is a hand-typed figure nobody can reproduce.
+ *
+ * 🚨 THE SAMPLE IS OPT-IN, AND THAT IS THE WHOLE POINT (2026-09-04, Eric).
+ * A row counts ONLY if its `speech_rate` column names a register. The query
+ * used to take every row carrying a transcript, which coupled two things that
+ * have no business touching: **researching a new ad turned a Slates RELEASE
+ * BUILD red.** `predist` → `check:all` → `check:shot-list` re-derives from the
+ * vault, so two ads landing in the corpus blocked `npm run dist` on work that
+ * had nothing to do with the desktop app. Opt-in decouples them — new research
+ * changes nothing until it is marked, so a red check is a deliberate act again
+ * rather than noise, and blocking on it is finally correct.
+ *
+ * Three things the old unfiltered query got wrong, all fixed by the mark:
+ * 1. **wpm is words ÷ TOTAL RUNTIME, not speaking time**, so a silence-heavy or
+ *    music-only ad reads as a slow talker. The corpus really held a 179s row at
+ *    55 wpm and a 16s row at 26 wpm. Nobody speaks at 26 wpm.
+ * 2. **`has_voiceover` was SELECTed and never filtered on** — 9 of the 74 rows
+ *    had no voiceover at all. (One row's value is the free text
+ *    `'yes (scripted dialogue/interviews)'`, so a naive boolean filter would
+ *    have dropped a real read as well.)
+ * 3. **The register was a creator-name regex on free text.** `%AI Video
+ *    Bootcamp%` happened to catch three different spellings of one person, and
+ *    `conversational` was the median over EVERYTHING — the other two registers
+ *    included. Each ad now names its own register and belongs to exactly one.
+ *
+ * Honest about the size of it: the medians barely moved (156 → 159) and the
+ * CEILING — the only number that ever flags a line — is 283 under every
+ * definition tried, because the fastest read was always a genuine voiceover
+ * row. The accuracy was never really the problem. The coupling was.
+ */
+export interface SpeechRate {
+    /** Words per minute. */
+    readonly wpm: number;
+    /** How many ads in the corpus this segment covers. */
+    readonly n: number;
+    /** Which rows `SPEECH_RATE_QUERY` was segmented to. */
+    readonly segment: string;
+}
+/**
+ * The derivation, verbatim, so gate 13a can re-run it.
+ *
+ * Word count is a WHITESPACE SPLIT of the trimmed transcript (`/\s+/`), not a
+ * space count — transcripts carry newlines, and counting only ' ' undercounts
+ * every multi-line row and drags the median down about ten wpm.
+ */
+export declare const SPEECH_RATE_QUERY: string;
+/** When the numbers below were last derived from the query above. */
+export declare const SPEECH_RATE_MEASURED_ON = "2026-09-04";
+/**
+ * 🔑 THE REGISTER SPLIT IS REAL AND MEASURED, which is why there is no single
+ * number. the performed, genre-acted reads run a median of 133 wpm;
+ * the hard-sell direct response runs 169 — thirty-six words a
+ * minute apart on the same runtime. A single point value would have been worse
+ * than none.
+ */
+export declare const SPEECH_RATE: {
+    readonly performed: {
+        readonly wpm: 133;
+        readonly n: 4;
+        readonly segment: "speech_rate = 'performed'";
+    };
+    readonly conversational: {
+        readonly wpm: 159;
+        readonly n: 41;
+        readonly segment: "speech_rate = 'conversational'";
+    };
+    readonly direct_response: {
+        readonly wpm: 169;
+        readonly n: 20;
+        readonly segment: "speech_rate = 'direct_response'";
+    };
+    /**
+     * The fastest read in the whole corpus. **The fit check flags only ABOVE
+     * this** — that is what "cannot fit at any plausible delivery" means. Not
+     * 250, not p90: those are rates real ads actually hit, and flagging an
+     * achievable read is exactly how a check gets ignored.
+     */
+    readonly ceiling: {
+        readonly wpm: 283;
+        readonly n: 65;
+        readonly segment: "max over every marked row";
+    };
+};
+export type SpeechRegister = Exclude<keyof typeof SPEECH_RATE, 'ceiling'>;
+/**
+ * The default register, and there is deliberately no picker for it.
+ *
+ * It is the corpus median and the safest of the three. A control would be a
+ * preference widget in a feature whose whole argument is that fewer required
+ * choices is better. If a project's own measured rate ever justifies one, that
+ * is a later change with its own evidence.
+ */
+export declare const DEFAULT_SPEECH_REGISTER: SpeechRegister;
+/** How many words fit in `seconds` at a register's pace. `null` when there is
+ *  no duration — a cut with no model has none, and inventing one would lie. */
+export declare function wordsForDuration(seconds: number | null | undefined, register?: SpeechRegister): number | null;
+/** Words in a spoken line. One definition, shared by the header and the flag. */
+export declare function countWords(line: string | null | undefined): number;
+/**
+ * Does this line fit this cut? `false` ONLY when it cannot fit at ANY plausible
+ * delivery — above the fastest read in every ad marked for the sample.
+ *
+ * 🚨 THE CLAIM IS DELIBERATELY WEAK SO THE CITATION CAN BE WEAK. Never flag "a
+ * bit long"; a check that nags gets ignored, and then it is worse than absent.
+ * Returns `null` when it cannot be decided (no line, or no duration).
+ */
+export declare function lineFitsCut(line: string | null | undefined, seconds: number | null | undefined): {
+    fits: boolean;
+    words: number;
+    requiredWpm: number;
+} | null;
+//# sourceMappingURL=shot-grammar.d.ts.map

package/dist/prompts/shot-grammar.js

@@ -0,0 +1,184 @@
+/**
+ * SHOT GRAMMAR — the buckets that COUNT framing, and the measured speech rate.
+ *
+ * 🚨 KEEP THIS A DEPENDENCY-FREE LEAF, exported from its own subpath
+ * (`@slatesvideo/shared/shot-grammar`). The desktop imports it from
+ * `slate/src/shared/` for the variety counter and the fit check, and the same
+ * two reasons that made `model-capabilities.ts` a leaf apply verbatim: the root
+ * barrel re-exports `auth.js` → `node:fs` (breaks renderer bundling) and
+ * `/prompts` drags the 5,000-word tips corpus in with no `require` condition.
+ *
+ * 🚨 BUCKETS EXIST TO COUNT, NEVER TO CONSTRAIN. `rules/ads/cinematic-storyboard.md`
+ * §4e, reconciled against ByteDance's own ModelArk docs: *"Camera vocabulary is
+ * open standard language and includes shot size (close-up / medium / wide) —
+ * not a closed list of eight moves."* Authoring `shotSize` and `camera` is FREE
+ * TEXT. A value matching no bucket counts as `other` and is never rejected,
+ * rewritten, or warned about. This module is the ONE home for these names —
+ * a second bucket list anywhere downstream is the drift `MODEL_CAPABILITIES`
+ * was created to end.
+ */
+// ── Shot size ──────────────────────────────────────────────────────
+export const SHOT_SIZE_BUCKETS = [
+    'wide',
+    'medium',
+    'close',
+    'extreme-close',
+    'other',
+];
+// ── Camera move ────────────────────────────────────────────────────
+export const CAMERA_MOVE_BUCKETS = [
+    'static',
+    'push',
+    'pull',
+    'handheld',
+    'orbit',
+    'crane',
+    'other',
+];
+/**
+ * The vocabulary each bucket answers to, as whole-word patterns.
+ *
+ * 🚨 NO TWO-LETTER ABBREVIATIONS — no `CU`, `ECU`, `MS`, `WS`, `LS`. They
+ * collide with ordinary words, they collide with EACH OTHER across shooting
+ * conventions (`MS` is a medium shot to one crew and a master to another), and
+ * a value bucketed WRONG is worse than one bucketed `other`: the whole claim of
+ * the variety check is that it is arithmetic anyone can verify by eye. `other`
+ * says "I did not recognise this"; a wrong bucket says something false.
+ * `cinematic-storyboard.md` §1's own example — `long-lens CU, other head
+ * blurred` — is deliberately `other`, and that is the correct answer.
+ *
+ * `satisfies Record<Exclude<Bucket, 'other'>, string[]>` on both records is
+ * what makes a SEVENTH bucket a compile error here rather than a name nothing
+ * ever matches. `other` is excluded because it is the fallback, by definition
+ * the bucket with no vocabulary.
+ */
+const SHOT_SIZE_VOCABULARY = {
+    // Longest/most specific first — `extreme close` must win over `close`.
+    'extreme-close': ['extreme close', 'extreme-close', 'macro', 'insert'],
+    close: ['close up', 'close-up', 'closeup', 'close on', 'close', 'tight'],
+    medium: ['medium', 'mid shot', 'mid-shot', 'waist', 'cowboy', 'two shot', 'two-shot'],
+    wide: ['wide', 'establishing', 'long shot', 'long-shot', 'full shot', 'full-shot', 'master'],
+};
+const CAMERA_MOVE_VOCABULARY = {
+    // `pull` before `push` so "dolly out" is never eaten by a looser "dolly".
+    // The bare bucket name is in every list: `push` alone matched while `pull`
+    // alone did not, which is the kind of asymmetry nobody notices until a count
+    // is quietly wrong.
+    pull: ['pull back', 'pull-back', 'pull out', 'pull away', 'dolly out', 'track out', 'zoom out', 'pull'],
+    push: ['push in', 'push-in', 'push', 'dolly in', 'track in', 'punch in', 'creep in', 'zoom in'],
+    // No trailing space on `arc` — matching is word-boundary based, so a space in
+    // the needle is both redundant and a trap for the next editor.
+    orbit: ['orbit', 'arc', 'circle', 'revolve', 'around the'],
+    crane: ['crane', 'jib', 'boom', 'drone', 'aerial', 'overhead descend'],
+    handheld: ['handheld', 'hand-held', 'shaky', 'shoulder', 'verite', 'vérité'],
+    static: ['static', 'locked off', 'locked-off', 'lock off', 'tripod', 'still', 'no movement'],
+};
+/** Case- and punctuation-insensitive containment, on word boundaries so
+ *  `wide` does not match `widescreen` and `close` does not match `closer`. */
+function matches(haystack, needle) {
+    const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, 'i').test(haystack);
+}
+function bucketBy(raw, vocabulary, fallback) {
+    if (!raw || !raw.trim())
+        return fallback;
+    const text = ` ${raw.toLowerCase().trim()} `;
+    for (const [bucket, words] of Object.entries(vocabulary)) {
+        for (const word of words)
+            if (matches(text, word))
+                return bucket;
+    }
+    return fallback;
+}
+/** Which shot-size bucket a free-text value counts in. Never rejects. */
+export function bucketShotSize(raw) {
+    return bucketBy(raw, SHOT_SIZE_VOCABULARY, 'other');
+}
+/** Which camera-move bucket a free-text value counts in. Never rejects. */
+export function bucketCameraMove(raw) {
+    return bucketBy(raw, CAMERA_MOVE_VOCABULARY, 'other');
+}
+/** Human label for a bucket, for a header strip or an op result. Derived from
+ *  the bucket name so a seventh bucket cannot ship without a label. */
+export function bucketLabel(bucket) {
+    return bucket.replace(/-/g, ' ');
+}
+/**
+ * The derivation, verbatim, so gate 13a can re-run it.
+ *
+ * Word count is a WHITESPACE SPLIT of the trimmed transcript (`/\s+/`), not a
+ * space count — transcripts carry newlines, and counting only ' ' undercounts
+ * every multi-line row and drags the median down about ten wpm.
+ */
+export const SPEECH_RATE_QUERY = `
+-- words-per-minute per ad, from second-brain/business/projects/slates/
+--   content-strategy/examples/ad-research.db
+-- words = transcript.trim().split(/\s+/).length   (applied to each row)
+-- wpm   = words / (duration_seconds / 60)
+SELECT id, speech_rate, duration_seconds, transcript
+  FROM ads
+ WHERE speech_rate IS NOT NULL
+   AND transcript IS NOT NULL AND TRIM(transcript) <> ''
+   AND duration_seconds IS NOT NULL AND duration_seconds > 0;
+-- segments: speech_rate, which is one register per ad and never overlaps
+-- statistic: median per register; ceiling = max over every marked row
+`.trim();
+/** When the numbers below were last derived from the query above. */
+export const SPEECH_RATE_MEASURED_ON = '2026-09-04';
+/**
+ * 🔑 THE REGISTER SPLIT IS REAL AND MEASURED, which is why there is no single
+ * number. the performed, genre-acted reads run a median of 133 wpm;
+ * the hard-sell direct response runs 169 — thirty-six words a
+ * minute apart on the same runtime. A single point value would have been worse
+ * than none.
+ */
+export const SPEECH_RATE = {
+    performed: { wpm: 133, n: 4, segment: "speech_rate = 'performed'" },
+    conversational: { wpm: 159, n: 41, segment: "speech_rate = 'conversational'" },
+    direct_response: { wpm: 169, n: 20, segment: "speech_rate = 'direct_response'" },
+    /**
+     * The fastest read in the whole corpus. **The fit check flags only ABOVE
+     * this** — that is what "cannot fit at any plausible delivery" means. Not
+     * 250, not p90: those are rates real ads actually hit, and flagging an
+     * achievable read is exactly how a check gets ignored.
+     */
+    ceiling: { wpm: 283, n: 65, segment: 'max over every marked row' },
+};
+/**
+ * The default register, and there is deliberately no picker for it.
+ *
+ * It is the corpus median and the safest of the three. A control would be a
+ * preference widget in a feature whose whole argument is that fewer required
+ * choices is better. If a project's own measured rate ever justifies one, that
+ * is a later change with its own evidence.
+ */
+export const DEFAULT_SPEECH_REGISTER = 'conversational';
+/** How many words fit in `seconds` at a register's pace. `null` when there is
+ *  no duration — a cut with no model has none, and inventing one would lie. */
+export function wordsForDuration(seconds, register = DEFAULT_SPEECH_REGISTER) {
+    if (seconds == null || !(seconds > 0))
+        return null;
+    return Math.round((SPEECH_RATE[register].wpm * seconds) / 60);
+}
+/** Words in a spoken line. One definition, shared by the header and the flag. */
+export function countWords(line) {
+    if (!line)
+        return 0;
+    return line.trim().split(/\s+/).filter(Boolean).length;
+}
+/**
+ * Does this line fit this cut? `false` ONLY when it cannot fit at ANY plausible
+ * delivery — above the fastest read in every ad marked for the sample.
+ *
+ * 🚨 THE CLAIM IS DELIBERATELY WEAK SO THE CITATION CAN BE WEAK. Never flag "a
+ * bit long"; a check that nags gets ignored, and then it is worse than absent.
+ * Returns `null` when it cannot be decided (no line, or no duration).
+ */
+export function lineFitsCut(line, seconds) {
+    const words = countWords(line);
+    if (words === 0 || seconds == null || !(seconds > 0))
+        return null;
+    const requiredWpm = Math.round(words / (seconds / 60));
+    return { fits: requiredWpm <= SPEECH_RATE.ceiling.wpm, words, requiredWpm };
+}
+//# sourceMappingURL=shot-grammar.js.map

package/dist/prompts/shot-spec.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Role an attachment carries in the composer tray. User-set, never inferred.
+ *
+ * 🚨 THIS UNION IS THE ONE ROLE LIST. The desktop's
+ * `slate/src/shared/attachmentRoles.ts` derives every map from it with
+ * `satisfies Record<AttachmentRole, …>`, so adding a role here is a COMPILE
+ * ERROR in the store buckets, the group kinds, the group names, the storage
+ * writer and the ops — never a silent gap. It used to be defined in the
+ * desktop renderer; it moved here when `ShotSpec` needed to be keyed by it in
+ * both repos.
+ *
+ * `video-reference` / `audio-reference` are REFERENCE roles, not modes:
+ * attaching a clip as a reference leaves the create surface alone, while "Edit
+ * with AI" is the separate, deliberate choice that swaps the surface.
+ */
+export type AttachmentRole = 'reference' | 'first-frame' | 'last-frame' | 'subject' | 'style' | 'video-reference' | 'audio-reference';
+/**
+ * The roles that hold an ORDERED, multi-occupancy list.
+ *
+ * Derived from the union by subtraction, never retyped: the two frame slots are
+ * scalars (single-occupancy, no order to change and no index to address), and a
+ * hand-written second union would be the exact hand-typed re-derivation this
+ * module exists to prevent.
+ */
+export type OrderedAttachmentRole = Exclude<AttachmentRole, 'first-frame' | 'last-frame'>;
+/**
+ * Emission ORDER of the ordered roles — the order `buildReferenceGroups` pushes
+ * them in, which is the order the composer numbers them in, which is the order
+ * the rail badges them in. Changing a number here changes what the model is
+ * told, so treat it exactly like the composer's own ordering.
+ *
+ * `satisfies Record<OrderedAttachmentRole, number>` is what makes a new role a
+ * compile error here rather than a missing bucket at runtime.
+ */
+export declare const ORDERED_ROLE_EMISSION: {
+    readonly reference: 0;
+    readonly subject: 1;
+    readonly style: 2;
+    readonly 'video-reference': 3;
+    readonly 'audio-reference': 4;
+};
+/** The ordered roles, in emission order. Sorted from the map above so the two
+ *  cannot disagree — never a second hand-written array. */
+export declare const ORDERED_ATTACHMENT_ROLES: readonly OrderedAttachmentRole[];
+/**
+ * Everything on the prompt bar that is NOT the prompt, the model or an
+ * attachment. Every field is optional and every field is a value the composer
+ * already persists into `settings_json` today — this is a rename, not a new
+ * vocabulary.
+ *
+ * 🚨 NO INDEX SIGNATURE, DELIBERATELY. An open record would let a param be
+ * written that nothing downstream restores, which is the shape of the live
+ * reuse bug this whole plan starts from: persisted, never read, invisible.
+ * Adding a param to the prompt bar means adding it HERE and to the desktop's
+ * `applyShotParams`, in the same pass.
+ */
+export interface ShotParams {
+    aspectRatio?: string;
+    /** Image models (Nano Banana 2 &co) — `1k` / `2k` / `4k`. */
+    imageResolution?: string;
+    videoResolution?: string;
+    quality?: string;
+    /** gpt-image-2's tier. Always sent explicitly: fal's own default is `high`. */
+    gptQuality?: 'medium' | 'high';
+    duration?: number;
+    imageQuantity?: number;
+    gridMode?: 'off' | '2x2' | '3x3';
+    negativePrompt?: string;
+    sound?: boolean;
+    audioLanguage?: string;
+    audioAccent?: string;
+    generateMusic?: boolean;
+    seedanceFace?: boolean;
+    multiShot?: boolean;
+    multiShotSegments?: Array<{
+        prompt: string;
+        duration: number;
+        camera: string;
+        shotSize: string;
+    }> | null;
+    cameraControls?: {
+        horizontal: number;
+        vertical: number;
+        pan: number;
+        tilt: number;
+        roll: number;
+        zoom: number;
+    };
+    /** Audio lane. On seed-audio the requested duration IS the bill. */
+    audioDurationSeconds?: number;
+    audioLoop?: boolean;
+    audioPromptInfluence?: number;
+    audioMultilingual?: boolean;
+}
+/** Prompt-owned identity — the entities the prompt text NAMES. */
+export interface ShotMentions {
+    characterIds: string[];
+    environmentIds: string[];
+    styleIds: string[];
+}
+export interface ShotSpec {
+    /** RAW prompt, `@mentions` intact. Never a composed one: the composer is the
+     *  only thing that may number anything, and a stored "image 3" would be a
+     *  lie the moment a reference is added, removed or reordered. */
+    prompt: string;
+    model: string | null;
+    /**
+     * The model the PROMPT WAS AUTHORED FOR. Never auto-rewritten.
+     *
+     * MiniMax H3 takes tagged `<Subject N>` references, `(S1)` speaker labels and
+     * `<d>[lang]…</d>` dialogue; Seedance does not. A prompt authored for one and
+     * replayed on another is not merely suboptimal — it can carry literal syntax
+     * the new model reads as text. Rewriting it would be prompt enhancement, the
+     * thing this codebase deleted on 2026-08-01. Record it, show it when it
+     * diverges from `model`, and leave the user's words alone.
+     */
+    authoredFor: string | null;
+    params: ShotParams;
+    /** ENTITY ids, never flattened paths — update the character and every Shot
+     *  that mentions it updates with it. */
+    mentions: ShotMentions;
+    /** Attachment-owned refs as ASSET IDS, ordered within each role. Keyed by
+     *  `OrderedAttachmentRole` so `ORDERED_ROLE_EMISSION` stays the ONE role
+     *  list; a sixth role is a compile error here too. */
+    refs: Record<OrderedAttachmentRole, string[]>;
+    firstFrameAssetId: string | null;
+    lastFrameAssetId: string | null;
+    /**
+     * What is SAID in each reference-audio clip, keyed by its ASSET ID.
+     *
+     * 🚨 KEYED, NOT INDEX-ALIGNED. A parallel array desyncs on a single drag and
+     * then tells the model one clip's words over another clip — silently. Its
+     * worst failure keyed is a stale entry, which composes as nothing.
+     */
+    audioRefSpokenText: Record<string, string>;
+    /** Who speaks: an entity id, a bare name, the literal `VO`, or null. A name
+     *  matching no character is a working state, not an error — it renders as
+     *  plain text and offers "make this a character". */
+    speaker: string | null;
+    /** What is said, verbatim. No camera, no scene, no prompt bloat — this is
+     *  the half a person reads aloud. */
+    line: string | null;
+    /** The parenthetical: how it is said. `(flat, exhausted)` */
+    delivery: string | null;
+    /** What happens in the shot, screenplay-style. ONE field: an action line
+     *  already describes everyone in frame, and splitting out the non-speakers
+     *  invents a distinction writers do not make. */
+    action: string | null;
+    /** The one readable object carrying the beat. */
+    prop: string | null;
+    /** Framing, FREE TEXT. Bucketed for counting by
+     *  `@slatesvideo/shared/shot-grammar`; never constrained by it. */
+    shotSize: string | null;
+    /** Camera move, FREE TEXT. Same rule as `shotSize`. */
+    camera: string | null;
+    /**
+     * This row's line runs on from the previous row's — one sentence, two cuts.
+     *
+     * ONE FLAG, NO OFFSETS. It says "these two rows are one sentence" without
+     * either row pointing into the other's text. Set by a mid-sentence split,
+     * editable by hand, and cleared on both sides when a move breaks the run.
+     * `heinrich-ad-prompting.md` §0a is built on exactly this move, so script →
+     * cut is many-to-many and must stay that way.
+     */
+    continues: boolean;
+}
+/**
+ * What each script field MEANS, in one sentence — the prose the op surface
+ * shows an agent for that parameter.
+ *
+ * It lives beside the fields because `satisfies Record<ScriptField, string>` is
+ * what makes a new field a compile error in the DESCRIPTIONS too. An op that
+ * hand-typed these would ship a ninth field with no explanation, which is the
+ * same failure as a column nothing renders.
+ */
+export declare const SCRIPT_FIELD_DESCRIPTION: {
+    readonly speaker: "Who says the line — a character id, a bare name (a character that does not exist yet is fine), or \"VO\". Null for a shot with no words.";
+    readonly line: "What is SAID, verbatim. Never camera, scene or prompt language — this is the half a person reads aloud.";
+    readonly delivery: "The parenthetical: how it is said. \"(flat, exhausted)\"";
+    readonly action: "What happens in the shot, screenplay-style. One line covering everyone in frame.";
+    readonly prop: "The one readable object carrying the beat.";
+    readonly shotSize: "Framing, in your own words — \"wide\", \"long-lens CU, other head blurred\". FREE TEXT: it is bucketed for the variety count and never rejected or rewritten.";
+    readonly camera: "Camera move, in your own words — \"slow push in\", \"through the rearview, eyes only\". FREE TEXT, same rule as shotSize.";
+    readonly continues: "True when this row's line runs on from the previous row's — one sentence split across two cuts. The signature VO move; set it deliberately.";
+};
+/** The script fields, as a list. Sorted from the description map so the two
+ *  cannot disagree — never a second hand-written array. */
+export type ScriptField = 'speaker' | 'line' | 'delivery' | 'action' | 'prop' | 'shotSize' | 'camera' | 'continues';
+/** The seven free-text script fields (everything but the `continues` flag) —
+ *  the set an op accepts as `string | null` and a layer renders as text. */
+export declare const SCRIPT_TEXT_FIELDS: readonly ["speaker", "line", "delivery", "action", "prop", "shotSize", "camera"];
+export type ScriptTextField = (typeof SCRIPT_TEXT_FIELDS)[number];
+/**
+ * The script, composed into prompt prose. **The one derivation, mirrored in
+ * both repos**, so the desktop, `slates_get_shot` and the generation handler
+ * cannot disagree about what a scripted Shot sends.
+ *
+ * 🚨 IT IS A TEMPLATE, NOT A WRITER. Deterministic, inspectable, no model. It
+ * orders the fields the way a shot is actually described — what the camera is
+ * doing, what happens, then who says what — and does nothing else. It never
+ * invents adjectives, never "enhances", and never reorders a sentence the user
+ * wrote. That is the prompt-transparency invariant: Slates may compose, and
+ * every composed character has to be visible in the composer before Generate.
+ *
+ * 🚨 AND IT ONLY FIRES WHEN `prompt` IS EMPTY. A Shot that carries an authored
+ * prompt keeps it byte-for-byte — which is what makes this safe to ship to live
+ * users with no migration. `prompt` wins because it is the more specific
+ * statement of intent; the script still counts, still fits, still reads.
+ *
+ * Dialogue is quoted so a model receives it as speech rather than as
+ * description — the one piece of grammar this adds, and the reason it is not
+ * just `join(' ')`.
+ */
+export declare function scriptPromptBody(spec: Pick<ShotSpec, ScriptTextField>): string;
+/**
+ * What this Shot actually sends: the authored prompt, or the script composed
+ * into one. Every consumer calls THIS, never `spec.prompt` directly — a reader
+ * that reached past it would be the surface that still says "No prompt yet"
+ * while the row plainly has a script in it.
+ */
+export declare function effectivePrompt(spec: ShotSpec): string;
+/** An empty Shot: a prompt bar nobody has touched. Every reader starts here and
+ *  overlays what it actually found, so a missing field is never `undefined`
+ *  leaking into a request. */
+export declare function emptyShotSpec(): ShotSpec;
+/**
+ * Read a `ShotSpec` out of whatever is on disk — a row written by an older
+ * build, a partial object from an op, `null`.
+ *
+ * TOLERANT ON PURPOSE (invariant 7: a Shot that cannot currently fire still
+ * loads). A missing role, an unknown key, a string where an array belongs —
+ * none of them may throw, because the one thing worse than a degraded Shot is a
+ * Shots list that will not open.
+ */
+export declare function normalizeShotSpec(raw: unknown): ShotSpec;
+/** Every asset id a Shot references, deduped, in emission order then frames.
+ *
+ *  🚨 THIS IS THE INPUT TO THE FK MIRROR. `refs_json` is a JSON blob and is
+ *  therefore INVISIBLE to the desktop's runtime FK classifier
+ *  (`storage/assetReferences.ts` walks `PRAGMA foreign_key_list`), so a Shot's
+ *  references would not block a cross-project move and the asset's file would
+ *  be relocated out from under it. `shot_assets` is the visible mirror, and
+ *  this function is the ONE place its row set is derived. */
+export declare function shotAssetIds(spec: ShotSpec): string[];
+/** Total attachment count — what a list row shows without composing anything. */
+export declare function shotRefCount(spec: ShotSpec): number;
+/**
+ * What each role MEANS, in one sentence — the prose the op surface shows an
+ * agent for that parameter.
+ *
+ * It lives here, beside the union, because `satisfies Record<AttachmentRole,
+ * string>` is what makes a new role a compile error in the DESCRIPTIONS too. An
+ * op that hand-typed these would silently ship a seventh role with no
+ * explanation, which is the same failure as a bucket nobody wired up.
+ */
+export declare const ATTACHMENT_ROLE_DESCRIPTION: {
+    readonly reference: "Plain reference images, in send order — cited in the prompt as \"image 1\", \"image 2\"…";
+    readonly subject: "Reference images that ARE the subject — composed as \"Image N is the subject\", so the model knows who the shot is about.";
+    readonly style: "Reference images the look is taken from — composed as one trailing \"Render in the visual style of image N\" clause.";
+    readonly 'video-reference': "Reference CLIPS read alongside the images — cited as \"video 1\", \"video 2\"…";
+    readonly 'audio-reference': "Reference AUDIO clips — cited as \"audio 1\", \"audio 2\"…. Pair each with audioRefSpokenText when it contains speech.";
+    readonly 'first-frame': "The starting frame for image-to-video.";
+    readonly 'last-frame': "The ending frame for image-to-video.";
+};
+//# sourceMappingURL=shot-spec.d.ts.map