@slatesvideo/shared 0.6.10 → 0.7.0

package/dist/prompts/reference-composer.d.ts

@@ -196,4 +196,6 @@ export declare const KLING_EDIT_MAX_REFS = 4;
  *   trimmed first — subjects are the feature)
  */
 export declare function composeKlingEdit(rawPrompt: string, groups: ReferenceGroup[]): KlingEditComposition;
+/** No-reference paths use the same composer and preserve authored prose. */
+export declare function cleanPrompt(userPrompt: string): string;
 //# sourceMappingURL=reference-composer.d.ts.map

package/dist/prompts/reference-composer.js

@@ -19,11 +19,12 @@
 // is each model's own official consistency lever (NB2 "assign a
 // distinct name", Seedance "Reference Subject_N in Image_N", Kling "reuse a fixed
 // label verbatim"); the heavy role-essay block was the off-doctrine part.
-// Normalize a name/token for matching: drop the sigil, lowercase, strip
-// spaces/underscores/hyphens. "@big_red" / "@Big Red" / "#Big-Red" all collapse
-// to the same key. Identical to the agent-side resolver's `norm`.
+// A mention's matching key: lowercase, spaces/underscores/hyphens stripped, and
+// the SIGIL KEPT. "@big_red" / "@Big Red" / "@Big-Red" are one key, and "@red"
+// and "#red" are two: names are unique per sigil, so a subject and a look may
+// share one, and a sigil-free key bound both mentions to whichever came last.
 function normToken(s) {
-    return s.toLowerCase().replace(/[@#]/g, '').replace(/[\s_-]+/g, '');
+    return s.toLowerCase().replace(/[\s_-]+/g, '');
 }
 // Free-reference IMAGE kinds get an "image N" number. Frames are transported in
 // their own dedicated slots (start/last frame) by the per-model adapter and are
@@ -179,7 +180,7 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
     // ── 2. Inline-name token groups in the prompt body ──
     // For each character/environment group whose token appears in the prompt, the
     // FIRST occurrence becomes "Name (image N)"; later ones become just "Name".
-    // Style tokens are removed (a single trailing clause carries the style). Token
+    // Style tokens become image citations at the user's chosen binding site. Token
     // groups NOT found in the prompt fall through to a key line in step 3.
     const tokenGroups = numbered.filter((g) => g.token && (g.kind === 'character' || g.kind === 'environment' || g.kind === 'style'));
     const byNorm = new Map();
@@ -204,20 +205,7 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
         unresolvedSeen.add(key);
         unresolvedTokens.push(`${sigil}${tok}`);
     };
-    // First strip "in/with the style of #tag" phrases so the style reads as a
-    // clean trailing clause, not a dangling preposition (legacy cleanPrompt
-    // behaviour). ONLY when the tag resolves: an unresolved one leaves the whole
-    // phrase exactly as authored and falls through to the token pass below, which
-    // reports it and sends it as written.
-    let body = rawPrompt.replace(/\s+(with|in)\s+the\s+style\s+of\s+([@#])([\w-]+(?:\.[\w-]+)*)/gi, (_full, _prep, sigil, tok) => {
-        const g = byNorm.get(normToken(`${sigil}${tok}`));
-        if (g && g.kind === 'style') {
-            matchedInPrompt.add(normToken(`${sigil}${tok}`));
-            return '';
-        }
-        return _full;
-    });
-    body = body.replace(TOKEN_RE, (_full, _sigil, tok) => {
+    const body = rawPrompt.replace(TOKEN_RE, (_full, _sigil, tok) => {
         const key = normToken(`${_sigil}${tok}`);
         const g = byNorm.get(key);
         if (!g) {
@@ -227,7 +215,7 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
         }
         matchedInPrompt.add(key);
         if (g.kind === 'style')
-            return ''; // styles never inline — trailing clause only
+            return g.imageNums.length ? citeImages(g.imageNums) : g.name;
         if (!seenFirst.has(key)) {
             seenFirst.add(key);
             // 🚨 ONE BINDING SITE PER ENTITY, CARRYING EVERY MEDIUM SHE OWNS
@@ -257,8 +245,13 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
         }
         return g.name;
     });
-    // Collapse the whitespace the token removals left behind.
-    body = body.replace(/[ \t]{2,}/g, ' ').replace(/\s+([,.;:!?])/g, '$1').trim();
+    // Literal citations are authored bindings too. Do not add a competing role
+    // sentence when the user already describes what that image supplies.
+    const citedImages = new Set();
+    for (const match of body.matchAll(/\bimages?\s+(\d+(?:\s*(?:,\s*(?:(?:and|&)\s*)?|(?:and|&)\s*)\d+)*)\b/gi)) {
+        for (const n of match[1].match(/\d+/g) ?? [])
+            citedImages.add(Number(n));
+    }
     // ── 3. Build the key lines for token-less / unmatched-token groups ──
     // Video sources, pinned/base canvases, and picked subjects that have no token
     // in the prompt each get ONE short neutral key line (never an essay). The user's
@@ -314,10 +307,11 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
     for (const g of numbered) {
         if ((g.kind === 'character' || g.kind === 'environment') && g.imageNums.length > 0) {
             const tokenWasMatched = g.token && matchedInPrompt.has(normToken(g.token));
-            if (!tokenWasMatched) {
-                const noun = g.imageNums.length === 1 ? 'Image' : 'Images';
-                const verb = g.imageNums.length === 1 ? 'is' : 'are';
-                topKeys.push(`${noun} ${joinNums(g.imageNums)} ${verb} ${g.name}.`);
+            const unmentioned = g.imageNums.filter((n) => !citedImages.has(n));
+            if (!tokenWasMatched && unmentioned.length) {
+                const noun = unmentioned.length === 1 ? 'Image' : 'Images';
+                const verb = unmentioned.length === 1 ? 'is' : 'are';
+                topKeys.push(`${noun} ${joinNums(unmentioned)} ${verb} ${g.name}.`);
             }
         }
     }
@@ -419,11 +413,11 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
     // `Audio 1` sitting mid-sentence among lowercase `image 1`s; moving the
     // binding inline removed the reason for the exception along with the
     // exception.
-    // ── 4. Style trailing clause (one, at the end — style reads best last) ──
+    // ── 4. Fallback for style attachments the user has not cited ──
     const styleNums = [];
     for (const g of numbered) {
         if (g.kind === 'style')
-            styleNums.push(...g.imageNums);
+            styleNums.push(...g.imageNums.filter((n) => !citedImages.has(n)));
     }
     const styleClauses = [];
     if (styleNums.length > 0) {
@@ -475,10 +469,12 @@ export function composeVoiceCitations(rawPrompt, voices) {
         if (v?.token)
             byNorm.set(normToken(v.token), { n: i + 1, name: v.name });
     });
+    // The one mention grammar (TOKEN_RE), so `joe@sarah.com` and `@sarah.extra`
+    // stay prose. A `#` token is a look, never a voice.
     const seen = new Set();
-    const body = rawPrompt.replace(/@([\w-]+)/g, (full, tok) => {
-        const key = normToken(`@${tok}`);
-        const v = byNorm.get(key);
+    const body = rawPrompt.replace(TOKEN_RE, (full, sigil, tok) => {
+        const key = normToken(`${sigil}${tok}`);
+        const v = sigil === '@' ? byNorm.get(key) : undefined;
         if (!v)
             return full;
         if (seen.has(key))
@@ -525,7 +521,12 @@ export function composeKlingEdit(rawPrompt, groups) {
     const elements = [];
     const styleImages = [];
     const styleNums = [];
-    let body = rawPrompt;
+    // Each mention's citation, by key. The prompt is walked ONCE with the one
+    // mention grammar (TOKEN_RE), so `joe@marcus.com` and `@marcus.extra` stay
+    // prose, as they do in `composeReferences`.
+    const citations = new Map();
+    const inPrompt = new Set([...rawPrompt.matchAll(TOKEN_RE)].map((t) => normToken(`${t[1]}${t[2]}`)));
+    const keyLines = [];
     // Subjects first — they own the @ElementN numbering.
     const subjectGroups = groups.filter((g) => (g.kind === 'character' || g.kind === 'environment') && g.media.some((m) => m.mediaKind === 'image'));
     for (const g of subjectGroups) {
@@ -536,20 +537,13 @@ export function composeKlingEdit(rawPrompt, groups) {
             continue;
         const n = elements.length + 1;
         elements.push({ frontal: imgs[0], angles: imgs.slice(1, 4), name: g.name });
-        if (g.token) {
-            // Replace every @token occurrence with the element citation.
-            const escaped = g.token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            const re = new RegExp(`${escaped}\\b`, 'gi');
-            if (re.test(body)) {
-                body = body.replace(re, `@Element${n}`);
-            }
-            else {
-                body = `${body}\n@Element${n} is ${g.name}.`;
-            }
-        }
-        else {
-            body = `${body}\n@Element${n} is ${g.name}.`;
-        }
+        // Every mention of the subject becomes its element citation; a subject the
+        // prompt never names gets a key line.
+        const key = g.token ? normToken(g.token) : null;
+        if (key && inPrompt.has(key) && !citations.has(key))
+            citations.set(key, `@Element${n}`);
+        else
+            keyLines.push(`@Element${n} is ${g.name}.`);
     }
     // Style / pinned refs take the remaining slots as @ImageN.
     for (const g of groups) {
@@ -564,12 +558,15 @@ export function composeKlingEdit(rawPrompt, groups) {
             const n = styleImages.length;
             if (g.kind === 'style')
                 styleNums.push(n);
-            if (g.token) {
-                const escaped = g.token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-                body = body.replace(new RegExp(`${escaped}\\b`, 'gi'), `@Image${n}`);
-            }
+            // A group's mention cites its FIRST image.
+            const key = g.token ? normToken(g.token) : null;
+            if (key && !citations.has(key))
+                citations.set(key, `@Image${n}`);
         }
     }
+    let body = rawPrompt.replace(TOKEN_RE, (full, sigil, tok) => citations.get(normToken(`${sigil}${tok}`)) ?? full);
+    for (const line of keyLines)
+        body = `${body}\n${line}`;
     if (styleNums.length > 0) {
         const cites = styleNums.map((n) => `@Image${n}`).join(' and ');
         body = `${body}\nApply the visual style of ${cites}.`;
@@ -584,4 +581,8 @@ export function composeKlingEdit(rawPrompt, groups) {
         styleImages,
     };
 }
+/** No-reference paths use the same composer and preserve authored prose. */
+export function cleanPrompt(userPrompt) {
+    return composeReferences(userPrompt, []).prompt;
+}
 //# sourceMappingURL=reference-composer.js.map

package/dist/prompts/script-document.d.ts

@@ -0,0 +1,165 @@
+/** Script document wire contract. Spoken text has one home: the scene string. */
+export interface Block {
+    id: string;
+    kind: 'paragraph' | 'heading' | 'direction';
+    start: number;
+    end: number;
+    /** Only non-spoken blocks own text here. Paragraph text lives in Scene.script. */
+    label?: string;
+    level?: number;
+    marks: Array<{
+        start: number;
+        end: number;
+        type: 'strong' | 'em';
+    }>;
+}
+export interface Scene {
+    id: string;
+    name: string;
+    script: string;
+    blocks: Block[];
+}
+export interface Shot {
+    id: string;
+    sceneId: string;
+    range: [number, number] | null;
+    label: string;
+    prompt: string;
+    speaker: string;
+}
+export interface Document {
+    storyboardId: string;
+    recovered?: boolean;
+    version: 1;
+    revision: number;
+    title: string;
+    scenes: Scene[];
+    shots: Shot[];
+}
+export interface DocumentEdit {
+    sceneId: string;
+    at: number;
+    removed: number;
+    text: string;
+}
+export interface DocumentWrite {
+    expectedRevision: number;
+    edits: DocumentEdit[];
+    structures?: Array<{
+        sceneId: string;
+        blocks: Block[];
+    }>;
+    move?: {
+        sceneId: string;
+        blockId: string;
+        delta: -1 | 1;
+    };
+    makeShots?: Array<SectionFragment & {
+        waitingShotId?: string;
+    }>;
+    restoreRevision?: number;
+    sceneAction?: {
+        kind: 'split';
+        sceneId: string;
+        at: number;
+    } | {
+        kind: 'merge';
+        sceneId: string;
+    };
+}
+export interface SectionFragment {
+    sceneId: string;
+    start: number;
+    end: number;
+}
+export interface Section {
+    id: string;
+    storyboardId: string;
+    parentId: string | null;
+    label: string;
+    tags: string[];
+    fragments: SectionFragment[];
+    activeAlternativeId: string | null;
+    locallyChanged: boolean;
+    sourceSectionId?: string | null;
+    sourceRevisionId?: string | null;
+    alternatives: Array<{
+        id: string;
+        label: string;
+        revisionId: string;
+    }>;
+}
+/** `rename` and `archive` act on the section, or on one alternative when
+ * alternativeId is given. Archiving a section keeps its words on the page. */
+export interface SectionInput {
+    expectedRevision: number;
+    action: 'create' | 'alternative' | 'choose' | 'save' | 'reuse' | 'updateUses' | 'rename' | 'archive' | 'tags';
+    sectionId?: string;
+    alternativeId?: string;
+    parentId?: string;
+    label?: string;
+    tags?: string[];
+    fragments?: SectionFragment[];
+    target?: {
+        sceneId: string;
+        at: number;
+        expectedRevision: number;
+    };
+    uses?: Array<{
+        sectionId: string;
+        expectedRevision: number;
+    }>;
+}
+/** A proposed replacement for exact words. It moves with edits around it and
+ * applies only while those words are unchanged (`stale` says they are not).
+ * Suggesting never edits the document; accepting is one undoable write. */
+export interface ScriptSuggestion {
+    id: string;
+    storyboardId: string;
+    sceneId: string;
+    start: number;
+    end: number;
+    original: string;
+    replacement: string;
+    note: string;
+    status: 'pending' | 'accepted' | 'dismissed';
+    stale: boolean;
+    baseRevision: number;
+}
+export interface SuggestionInput {
+    expectedRevision: number;
+    action: 'create' | 'accept' | 'dismiss';
+    suggestions?: Array<{
+        sceneId: string;
+        start: number;
+        end: number;
+        original: string;
+        replacement: string;
+        note?: string;
+    }>;
+    suggestionId?: string;
+}
+export interface VariationChoice {
+    sectionId: string;
+    alternativeId: string;
+}
+/** Enumerate only on demand; even a large Cartesian set costs one row of memory. */
+export declare function variationCombinations(axes: VariationChoice[][], prefix?: VariationChoice[]): Generator<VariationChoice[]>;
+export interface VariationInput {
+    expectedRevision: number;
+    name: string;
+    choices: VariationChoice[];
+    /** When present, this sequence replaces the arrangement: omission and repetition are deliberate. */
+    arrangement?: VariationChoice[];
+    itemOverrides?: Array<{
+        from: string;
+        to: string;
+        voice: 'keep' | 'replace';
+    }>;
+    assetOverrides?: Array<{
+        from: string;
+        to: string;
+    }>;
+    idempotencyKey?: string;
+}
+//# sourceMappingURL=script-document.d.ts.map

package/dist/prompts/script-document.js

@@ -0,0 +1,11 @@
+/** Enumerate only on demand; even a large Cartesian set costs one row of memory. */
+export function* variationCombinations(axes, prefix = []) {
+    if (!axes.length) {
+        yield prefix;
+        return;
+    }
+    const [head, ...tail] = axes;
+    for (const choice of head)
+        yield* variationCombinations(tail, [...prefix, choice]);
+}
+//# sourceMappingURL=script-document.js.map

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

@@ -87,7 +87,7 @@ export interface SpeechRate {
  */
 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";
+export declare const SPEECH_RATE_MEASURED_ON = "2026-09-30";
 /**
  * 🔑 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;
@@ -102,8 +102,8 @@ export declare const SPEECH_RATE: {
         readonly segment: "speech_rate = 'performed'";
     };
     readonly conversational: {
-        readonly wpm: 159;
-        readonly n: 41;
+        readonly wpm: 153;
+        readonly n: 43;
         readonly segment: "speech_rate = 'conversational'";
     };
     readonly direct_response: {
@@ -119,7 +119,7 @@ export declare const SPEECH_RATE: {
      */
     readonly ceiling: {
         readonly wpm: 283;
-        readonly n: 65;
+        readonly n: 67;
         readonly segment: "max over every marked row";
     };
 };

package/dist/prompts/shot-grammar.js

@@ -124,7 +124,7 @@ SELECT id, speech_rate, duration_seconds, transcript
 -- 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';
+export const SPEECH_RATE_MEASURED_ON = '2026-09-30';
 /**
  * 🔑 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;
@@ -134,7 +134,7 @@ export const SPEECH_RATE_MEASURED_ON = '2026-09-04';
  */
 export const SPEECH_RATE = {
     performed: { wpm: 133, n: 4, segment: "speech_rate = 'performed'" },
-    conversational: { wpm: 159, n: 41, segment: "speech_rate = 'conversational'" },
+    conversational: { wpm: 153, n: 43, 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
@@ -142,7 +142,7 @@ export const SPEECH_RATE = {
      * 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' },
+    ceiling: { wpm: 283, n: 67, segment: 'max over every marked row' },
 };
 /**
  * The default register, and there is deliberately no picker for it.

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

@@ -122,6 +122,9 @@ export interface ShotSpec {
      *  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;
+    /** Custom bytes remain recoverable when script mode is selected. */
+    recipeMode?: 'script' | 'custom';
+    promptScriptLine?: string | null;
     model: string | null;
     /**
      * The model the PROMPT WAS AUTHORED FOR. Never auto-rewritten.
@@ -229,6 +232,16 @@ export type ScriptTextField = (typeof SCRIPT_TEXT_FIELDS)[number];
  * 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(' ')`.
+ *
+ * 🚨 A LINE IS SPEECH ONLY WHEN THE SHOT SAYS WHO SPEAKS OR HOW (2026-09-27).
+ * Since the Script page became one continuous text (2026-09-19, "cues stay
+ * words"), `line` holds whatever script text a Shot's range covers, and most
+ * of a script is action. Composing every speaker-less line as `A voice says
+ * "…"` told the video model that someone speaks the stage direction: an ad
+ * script broken into four Shots sent four of them (first-hour walk finding 15).
+ * Unlabelled text now goes in as written; a speaker (VO included) or a
+ * delivery note still makes it quoted speech. Mirrored byte-for-byte in both
+ * repos, and `check:composer-mirror` compares the two outputs.
  */
 export declare function scriptPromptBody(spec: Pick<ShotSpec, ScriptTextField>): string;
 /**

package/dist/prompts/shot-spec.js

@@ -68,6 +68,16 @@ export const SCRIPT_TEXT_FIELDS = [
  * 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(' ')`.
+ *
+ * 🚨 A LINE IS SPEECH ONLY WHEN THE SHOT SAYS WHO SPEAKS OR HOW (2026-09-27).
+ * Since the Script page became one continuous text (2026-09-19, "cues stay
+ * words"), `line` holds whatever script text a Shot's range covers, and most
+ * of a script is action. Composing every speaker-less line as `A voice says
+ * "…"` told the video model that someone speaks the stage direction: an ad
+ * script broken into four Shots sent four of them (first-hour walk finding 15).
+ * Unlabelled text now goes in as written; a speaker (VO included) or a
+ * delivery note still makes it quoted speech. Mirrored byte-for-byte in both
+ * repos, and `check:composer-mirror` compares the two outputs.
  */
 export function scriptPromptBody(spec) {
     const clean = (v) => (v ?? '').trim();
@@ -87,10 +97,16 @@ export function scriptPromptBody(spec) {
     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}"`);
+        if (!speaker && !delivery) {
+            // Script text with no one named to speak it: sent as written.
+            parts.push(line);
+        }
+        else {
+            // "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(' ');
 }
@@ -101,7 +117,7 @@ export function scriptPromptBody(spec) {
  * while the row plainly has a script in it.
  */
 export function effectivePrompt(spec) {
-    const authored = spec.prompt.trim();
+    const authored = spec.recipeMode === 'script' ? '' : spec.prompt.trim();
     return authored || scriptPromptBody(spec);
 }
 /** An empty Shot: a prompt bar nobody has touched. Every reader starts here and
@@ -247,6 +263,8 @@ export function normalizeShotSpec(raw) {
     }
     const out = {
         prompt: typeof v.prompt === 'string' ? v.prompt : '',
+        ...(v.recipeMode === 'script' || v.recipeMode === 'custom' ? { recipeMode: v.recipeMode } : {}),
+        ...(typeof v.promptScriptLine === 'string' || v.promptScriptLine === null ? { promptScriptLine: v.promptScriptLine } : {}),
         model: str(v.model),
         authoredFor: str(v.authoredFor),
         params: readParams(v.params),