@slatesvideo/shared 0.6.2 → 0.6.4

package/dist/prompts/shot-spec.js

@@ -0,0 +1,303 @@
+// The Shot — the prompt bar, serialized.
+//
+// THE PRINCIPLE: a generation's full recipe already exists (the desktop writes
+// `referenceGroups` into every `settings_json`), but only as a byproduct of
+// spending money on it. This module gives that structure a NAME, so it can be
+// listed, forked, agent-authored and restored without loss — before anything
+// has been generated.
+//
+// This is the canonical implementation. It is mirrored byte-for-byte into the
+// desktop app's `slate/src/shared/shotSpec.ts` (the desktop installs the
+// published @slatesvideo/shared from npm and cannot file-import this source, so
+// the mirror carries a header pointing here — the same rule
+// `reference-composer.ts` follows). `slate/scripts/composer-mirror-check.mjs`
+// asserts the two agree; do not invent a second sync mechanism.
+//
+// 🚨 KEEP THIS A DEPENDENCY-FREE LEAF. It imports nothing, in either repo. The
+// desktop's renderer bundles its mirror, the desktop's MAIN process reads it,
+// and the op surface here builds Zod schemas from it — a single `node:` import
+// would break the first of those.
+/**
+ * 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 const ORDERED_ROLE_EMISSION = {
+    reference: 0,
+    subject: 1,
+    style: 2,
+    'video-reference': 3,
+    '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 const ORDERED_ATTACHMENT_ROLES = Object.keys(ORDERED_ROLE_EMISSION).sort((a, b) => ORDERED_ROLE_EMISSION[a] - ORDERED_ROLE_EMISSION[b]);
+/**
+ * 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 const SCRIPT_FIELD_DESCRIPTION = {
+    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.',
+    line: 'What is SAID, verbatim. Never camera, scene or prompt language — this is the half a person reads aloud.',
+    delivery: 'The parenthetical: how it is said. "(flat, exhausted)"',
+    action: 'What happens in the shot, screenplay-style. One line covering everyone in frame.',
+    prop: 'The one readable object carrying the beat.',
+    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.',
+    camera: 'Camera move, in your own words — "slow push in", "through the rearview, eyes only". FREE TEXT, same rule as shotSize.',
+    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 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 const SCRIPT_TEXT_FIELDS = [
+    'speaker',
+    'line',
+    'delivery',
+    'action',
+    'prop',
+    'shotSize',
+    'camera',
+];
+/**
+ * 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 function scriptPromptBody(spec) {
+    const clean = (v) => (v ?? '').trim();
+    const parts = [];
+    // Framing first: it is the camera instruction, and every model's own docs
+    // put shot size and movement at the head of the prompt.
+    const framing = [clean(spec.shotSize), clean(spec.camera)].filter(Boolean).join(', ');
+    if (framing)
+        parts.push(`${framing}.`);
+    const action = clean(spec.action);
+    if (action)
+        parts.push(/[.!?]$/.test(action) ? action : `${action}.`);
+    const prop = clean(spec.prop);
+    if (prop)
+        parts.push(`${prop} is visible in frame.`);
+    const line = clean(spec.line);
+    if (line) {
+        const speaker = clean(spec.speaker);
+        const delivery = clean(spec.delivery).replace(/^\(|\)$/g, '').trim();
+        // "VO" is a screenplay abbreviation, not something to send to a model.
+        const who = !speaker || speaker.toUpperCase() === 'VO' ? 'A voice' : speaker;
+        const how = delivery ? `, ${delivery},` : '';
+        parts.push(`${who} says${how} "${line}"`);
+    }
+    return parts.join(' ');
+}
+/**
+ * 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 function effectivePrompt(spec) {
+    const authored = spec.prompt.trim();
+    return authored || scriptPromptBody(spec);
+}
+/** 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 function emptyShotSpec() {
+    const refs = {};
+    for (const role of ORDERED_ATTACHMENT_ROLES)
+        refs[role] = [];
+    return {
+        prompt: '',
+        model: null,
+        authoredFor: null,
+        params: {},
+        mentions: { characterIds: [], environmentIds: [], styleIds: [] },
+        refs,
+        firstFrameAssetId: null,
+        lastFrameAssetId: null,
+        audioRefSpokenText: {},
+        speaker: null,
+        line: null,
+        delivery: null,
+        action: null,
+        prop: null,
+        shotSize: null,
+        camera: null,
+        continues: false,
+    };
+}
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+const strArray = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x.length > 0) : [];
+function readParams(v) {
+    if (!v || typeof v !== 'object')
+        return {};
+    const raw = v;
+    const out = {};
+    const s = (k) => {
+        if (typeof raw[k] === 'string')
+            out[k] = raw[k];
+    };
+    const n = (k) => {
+        if (typeof raw[k] === 'number' && Number.isFinite(raw[k]))
+            out[k] = raw[k];
+    };
+    const b = (k) => {
+        if (typeof raw[k] === 'boolean')
+            out[k] = raw[k];
+    };
+    s('aspectRatio');
+    s('imageResolution');
+    s('videoResolution');
+    s('quality');
+    s('audioLanguage');
+    s('audioAccent');
+    s('negativePrompt');
+    n('duration');
+    n('imageQuantity');
+    n('audioDurationSeconds');
+    n('audioPromptInfluence');
+    b('sound');
+    b('generateMusic');
+    b('seedanceFace');
+    b('multiShot');
+    b('audioLoop');
+    b('audioMultilingual');
+    if (raw.gptQuality === 'medium' || raw.gptQuality === 'high')
+        out.gptQuality = raw.gptQuality;
+    if (raw.gridMode === 'off' || raw.gridMode === '2x2' || raw.gridMode === '3x3')
+        out.gridMode = raw.gridMode;
+    if (Array.isArray(raw.multiShotSegments)) {
+        out.multiShotSegments = raw.multiShotSegments;
+    }
+    const cc = raw.cameraControls;
+    if (cc && typeof cc === 'object') {
+        const keys = ['horizontal', 'vertical', 'pan', 'tilt', 'roll', 'zoom'];
+        if (keys.every((k) => typeof cc[k] === 'number')) {
+            out.cameraControls = {
+                horizontal: cc.horizontal, vertical: cc.vertical,
+                pan: cc.pan, tilt: cc.tilt,
+                roll: cc.roll, zoom: cc.zoom,
+            };
+        }
+    }
+    return out;
+}
+/**
+ * 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 function normalizeShotSpec(raw) {
+    const base = emptyShotSpec();
+    if (!raw || typeof raw !== 'object')
+        return base;
+    const v = raw;
+    const mentions = (v.mentions ?? {});
+    const refs = (v.refs ?? {});
+    const spoken = {};
+    if (v.audioRefSpokenText && typeof v.audioRefSpokenText === 'object') {
+        for (const [k, text] of Object.entries(v.audioRefSpokenText)) {
+            // Trimmed on the way in, exactly as the composer trims it on the way out,
+            // so a value that round-trips through a save cannot come back different.
+            if (typeof text === 'string' && text.trim())
+                spoken[k] = text.trim();
+        }
+    }
+    const out = {
+        prompt: typeof v.prompt === 'string' ? v.prompt : '',
+        model: str(v.model),
+        authoredFor: str(v.authoredFor),
+        params: readParams(v.params),
+        mentions: {
+            characterIds: strArray(mentions.characterIds),
+            environmentIds: strArray(mentions.environmentIds),
+            styleIds: strArray(mentions.styleIds),
+        },
+        refs: base.refs,
+        firstFrameAssetId: str(v.firstFrameAssetId),
+        lastFrameAssetId: str(v.lastFrameAssetId),
+        audioRefSpokenText: spoken,
+        // The script layer reads through the same tolerant `str()` as everything
+        // else: a row written before these existed comes back with nulls, which is
+        // exactly right — it had no line and never claimed one.
+        speaker: str(v.speaker),
+        line: str(v.line),
+        delivery: str(v.delivery),
+        action: str(v.action),
+        prop: str(v.prop),
+        shotSize: str(v.shotSize),
+        camera: str(v.camera),
+        continues: v.continues === true,
+    };
+    for (const role of ORDERED_ATTACHMENT_ROLES)
+        out.refs[role] = strArray(refs[role]);
+    return out;
+}
+/** 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 function shotAssetIds(spec) {
+    const ids = [];
+    for (const role of ORDERED_ATTACHMENT_ROLES)
+        ids.push(...spec.refs[role]);
+    if (spec.firstFrameAssetId)
+        ids.push(spec.firstFrameAssetId);
+    if (spec.lastFrameAssetId)
+        ids.push(spec.lastFrameAssetId);
+    return [...new Set(ids.filter(Boolean))];
+}
+/** Total attachment count — what a list row shows without composing anything. */
+export function shotRefCount(spec) {
+    return shotAssetIds(spec).length;
+}
+/**
+ * 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 const ATTACHMENT_ROLE_DESCRIPTION = {
+    reference: 'Plain reference images, in send order — cited in the prompt as "image 1", "image 2"…',
+    subject: 'Reference images that ARE the subject — composed as "Image N is the subject", so the model knows who the shot is about.',
+    style: 'Reference images the look is taken from — composed as one trailing "Render in the visual style of image N" clause.',
+    'video-reference': 'Reference CLIPS read alongside the images — cited as "video 1", "video 2"…',
+    'audio-reference': 'Reference AUDIO clips — cited as "audio 1", "audio 2"…. Pair each with audioRefSpokenText when it contains speech.',
+    'first-frame': 'The starting frame for image-to-video.',
+    'last-frame': 'The ending frame for image-to-video.',
+};
+//# sourceMappingURL=shot-spec.js.map