@slatesvideo/shared 0.6.11 → 0.7.1

package/dist/prompts/prompting-tips.js

@@ -137,7 +137,7 @@ const SEEDANCE_25 = {
         [
             {
                 heading: '720p is not the cheap one here',
-                example: '30s \u00b7 720p \u00b7 Face route = 484 credits\n15s \u00b7 1080p \u00b7 Seedance 2.0 Face = 411 credits',
+                example: '30s \u00b7 720p \u00b7 Face route = 489 credits\n15s \u00b7 1080p \u00b7 Seedance 2.0 Face = 411 credits',
                 note: 'Length is what moves the price, and 2.5 doubles the length ceiling — so a 30-second 720p clip can cost more than a 15-second 1080p one, against a 1,000-credit starting balance. Explore at short LENGTH rather than low resolution: cut the seconds to 4-8 while you are finding the shot, and stay at the resolution you actually want. A 480p pass does not de-risk a 720p render — generation is stochastic, so the 720p run is a different take, not the same shot rendered better. The Generate button always shows the exact number first.',
                 critical: true,
             },
@@ -151,7 +151,7 @@ const SEEDANCE_25 = {
     ],
     footer: [
         '30 image references is a budget, not a target — 2-4 strong references still beat both extremes, one per role. ByteDance\'s own ceilings for 2.5: 1-8 subjects bound by image reference stay stable (9-12 works but needs re-rolls), 1-5 subjects bound by video or audio reference, and 5-10 seconds is the sweet spot for a reference clip. Unlike 2.0, a multi-view turnaround sheet can be a single subject reference here — past 5 subjects, go back to one view per image. The larger budget is for long multi-shot takes and for video plus audio references alongside images.',
-        'A reference VIDEO bills input seconds PLUS output seconds, and 2.5 accepts references up to 30s combined — so a 20-second reference driving a 20-second output bills 40 seconds. The Generate button shows the total.',
+        'A reference VIDEO bills input seconds PLUS output seconds, and 2.5 accepts references up to 30s combined — so a 20-second reference driving a 20-second output bills 40 seconds. On the AI-face route the reference counts as at least as long as the output: a 5-second reference on a 20-second output bills 40 seconds, not 25. The Generate button shows the total.',
         ...(SEEDANCE.footer ?? []).slice(0, 2),
         'Frames and reference images stay mutually exclusive, and on a first/last-frame generation Seedance 2.5 chooses the aspect ratio itself — the ratio control shows "Adaptive" because the start frame decides the shape.',
     ],
@@ -190,7 +190,7 @@ const SEEDANCE_25_EDIT = {
         [
             {
                 heading: 'When to use it instead of the others',
-                note: 'Length is the reason: it is the only engine that accepts a clip over 15 seconds. Inside the others\' range, choose on fidelity — Omni Flash Edit is the prompt-only fidelity winner and the cheapest seat, and Kling O3 Edit is the one that takes subject and style reference images.',
+                note: 'Length is the reason: it is the only engine that accepts a clip over 15 seconds. Inside the others\' range, choose on fidelity — Omni Flash Edit is the prompt-only fidelity winner and the cheapest option, and Kling O3 Edit is the one that takes subject and style reference images.',
             },
             {
                 heading: 'It edits the audio too',
@@ -347,7 +347,7 @@ const OMNI_FLASH = {
                 note: 'No negative-prompt field — write what to avoid as a direct instruction.',
             },
             {
-                heading: 'Know its seat',
+                heading: 'Know its role',
                 note: 'Cheap drafts, iteration volume, and audio-in-one-gen at low cost. For hero shots, Seedance 2.5 (the default) or Seedance 2.0 (4K, cheaper) still win.',
             },
         ],
@@ -398,6 +398,45 @@ const OMNI_FLASH_EDIT = {
         'Ship via segment-splice: edit only the seconds where the change happens (Trim / Split first), then splice back over the original on the timeline with the original audio underneath. Chain edits one change at a time — each edit saves as a new clip linked to its parent.',
     ],
 };
+const GPT_IMAGE_25 = {
+    label: 'GPT Image 2.5',
+    intro: [
+        'Two tiers at the same price: Flare is the faster one; Sunburst is the better-quality one, and slower. Explore on Flare, finish on Sunburst.',
+        'The photoreal front-runner for people, and the most reliable model for readable text, ordered panels and exact placement.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'Name each reference where it is used',
+                example: 'The woman from image 1 cooks on a rocky summit, lit and graded like image 2.',
+                note: PARTIALS['reference-tips-short'],
+            },
+            {
+                heading: 'Quote text that must render',
+                example: 'the word "SLATES" once in small plain letters on the left chest',
+                note: "Quoted strings render most reliably. Describe a font's feel, never its name, and keep on-image text under about 30 words.",
+            },
+            {
+                heading: 'Set the quality tier on purpose',
+                example: 'low · medium · high · xhigh · max',
+                note: 'High is the everyday tier and max costs about four times as much. Medium is cheap enough to draft on; go past high only when tiny type or a finished frame needs it.',
+            },
+        ],
+        [
+            {
+                heading: 'The look: describe what the camera sees',
+                example: 'She is close to a silhouette: her face falls into deep shadow.\nThe sky around the sun burns out to white.',
+                note: PARTIALS['cinematic-tips-short'],
+                critical: true,
+            },
+            {
+                heading: 'Describe the frame, or swap into one you own',
+                example: 'Dark hiking trousers. The only things on the rock are the stove and the pan.\nTake image 1 and change only the character to the character in image 2.',
+                note: PARTIALS['cinematic-routes-short'],
+            },
+        ],
+    ],
+};
 const NANO_BANANA = {
     label: 'Nano Banana 2',
     intro: [
@@ -414,7 +453,7 @@ const NANO_BANANA = {
             {
                 heading: 'Named lenses + apertures',
                 example: '85mm f/1.4 · 135mm f/2.8 · 50mm f/1.2 · 35mm f/2 · Panavision anamorphic · 400mm telephoto',
-                note: '135mm f/2.8 is the cheat code for skin texture and intimate compression. Anamorphic for cinematic width + horizontal flares.',
+                note: 'Describe the intended perspective, depth of field and texture alongside the lens. A model does not guarantee physical lens simulation.',
             },
             {
                 heading: 'Named film stocks (one per prompt)',
@@ -424,7 +463,7 @@ const NANO_BANANA = {
             {
                 heading: "Don't carry lens + stock into a video prompt",
                 example: '85mm f/1.4, Portra 400\n→ close-up, shallow depth of field, warm natural colors, cinematic texture',
-                note: 'Lenses, apertures, film stocks and camera bodies are an image-model lever and a video-model anti-pattern — ByteDance\'s Seedance guide never mentions f-stops, lens millimetres, fps or shutter angle. When you animate a frame you made here, translate the look into shot size, depth of field and colour tone instead of pasting the gear list across.',
+                note: PARTIALS['lens-video-split'],
             },
             {
                 heading: 'Physics-based lighting',
@@ -434,14 +473,19 @@ const NANO_BANANA = {
             {
                 heading: 'Imperfection vocabulary',
                 example: 'visible pores · peach fuzz · ISO noise · sweat beading · slight hyperpigmentation · unretouched raw photography',
-                note: 'Forces the model away from AI-clean skin. The default is too smooth — you have to ask for the imperfections that real photos have.',
+                note: 'Forces the model away from AI-clean skin. The default is too smooth — you have to ask for the imperfections that real photos have. Lead with the kind of photograph and the conditions on the skin; a bare list of flaw words reads as tokens.',
+            },
+            {
+                heading: 'The look: describe what the camera sees',
+                example: 'She is close to a silhouette: her face falls into deep shadow.\nThe sky around the sun burns out to white.',
+                note: PARTIALS['cinematic-tips-short'],
             },
         ],
         [
             {
                 heading: '❌ The anti-list — avoid these',
                 example: '8k · masterpiece · hyperrealistic · ultra-detailed · trending on ArtStation · perfect skin · flawless · airbrushed · cinematic (alone)',
-                note: 'Tag-soup phrases from the Stable-Diffusion era. Measured success ~60-70% with these vs ~95%+ with positive description. Always specify which cinema — director, lens, era, stock.',
+                note: 'Generic quality tags do not specify an observable result. Describe the medium, light, exposure and texture the brief calls for.',
                 critical: true,
             },
             {
@@ -537,7 +581,7 @@ const SEED_AUDIO = {
                 note: 'Up to 3 audio clips (max 30s each), referenced as @Audio1–@Audio3 — OR one image to score what is in frame. Never both in the same generation.',
             },
             {
-                heading: 'Know its seat',
+                heading: 'Know its role',
                 note: 'Scenes, beds, room tone and dialogue in one pass. For a single effect that has to land on a specific frame, use Sound Effects.',
             },
         ],
@@ -579,7 +623,7 @@ const ELEVEN_SFX = {
                 note: 'Higher hugs your wording with less variation between takes; lower explores. Raise it when a re-roll keeps wandering off the brief.',
             },
             {
-                heading: 'Know its seat',
+                heading: 'Know its role',
                 note: 'One precise effect on a known frame. Full rooms and layered scenes are cheaper and better in one Seed Audio pass.',
             },
         ],
@@ -589,7 +633,7 @@ const MINIMAX_H3 = {
     label: 'MiniMax H3',
     intro: [
         'MiniMax H3 generates picture and sound in one pass — 24fps, 32kHz stereo, 5-15 seconds, 11 stably-supported languages. It is the only video model in Slates where audio is AUTHORED rather than switched on: synchronised dialogue and action sounds go in the body of the prompt, ambience goes in a soundscape section, and audience-only music goes in a score section. Put a sound in the wrong section and it is dropped, doubled, or attributed to the wrong source.',
-        'Two seats that differ in LADDER and PRICE, not in what they accept. Base H3 runs 480p / 768p / 2K / 4K; H3 Max is fal\'s faster post-train and runs 480p / 768p / 1080p, dearer than base H3 at the tier they share - a deliberate speed pick, never the cheap one. BOTH read up to 9 reference images plus 3 video and 3 audio clips (12 files total, and audio never travels alone), and both animate a start frame and an end frame. 768p is the default on both because it is the tier the model natively generates; base H3\'s 2K and 4K are upscales of a 768p base. Reference images past the free allowance are billed and the allowances DIFFER: 5 free on base H3, 4 on Max.',
+        'Three models. Base H3 runs 480p / 768p / 2K / 4K; H3 Max is fal\'s faster post-train and runs 480p / 768p / 1080p, dearer than base H3 at the tier they share - a deliberate speed pick, never the cheap one; H3 Max Turbo has Max\'s ladder at half Max\'s rate and takes NO references. Base H3 and Max read up to 9 reference images plus 3 video and 3 audio clips (12 files total, and audio never travels alone); all three animate a start frame and an end frame. 768p is the default on all three because it is the tier the model natively generates; base H3\'s 2K and 4K are upscales of a 768p base, and 1080p on Max and Turbo is a refinement of it. Reference images past the free allowance are billed and the allowances DIFFER: 5 free on base H3, 4 on Max.',
     ],
     columns: [
         [
@@ -624,7 +668,7 @@ const MINIMAX_H3 = {
             {
                 heading: 'Say how much of a reference survives',
                 example: 'Give the man in image 3 the weathered leather texture of the jacket in image 4.',
-                note: 'H3 is the only seat that understands transferring a characteristic onto a DIFFERENT subject. State each reference\'s job and how much of it should carry through — kept whole, kept in part, transferred, or a loose echo.',
+                note: 'H3 is the only model that understands transferring a characteristic onto a DIFFERENT subject. State each reference\'s job and how much of it should carry through — kept whole, kept in part, transferred, or a loose echo.',
             },
             {
                 heading: 'Reference images past the fifth cost extra',
@@ -650,7 +694,7 @@ const LTX_2_5 = {
     label: 'LTX-2.5',
     intro: [
         'LTX-2.5 scores the picture on the same pass that draws it, so SOUND IS THE FIRST THING YOU WRITE, not the last. Lightricks ranks the six parts of a prompt in this order: sound, camera, character detail, shot type and scene, then scene dressing — and scene dressing is the first thing to cut when a prompt sprawls. Everything goes in ONE flowing paragraph, not a list of labelled sections.',
-        'Two seats. Base LTX-2.5 is the distilled build: 720p / 1080p / 1440p / 4K and clips from 6 to 20 seconds, and it is the cheapest native 1080p second in Slates. LTX-2.5 Pro is the full diffusion build ("Diffusion Fidelity Rendering" spends extra compute on busy frames) but reaches a SHORTER ladder — 1080p and 10 seconds maximum — while costing about a third more. Pro is for a dense final render; base is for iteration, long takes and 4K.',
+        'Two models. Base LTX-2.5 is the distilled build: 720p / 1080p / 1440p / 4K and clips from 6 to 20 seconds, and it is the cheapest native 1080p second in Slates. LTX-2.5 Pro is the full diffusion build ("Diffusion Fidelity Rendering" spends extra compute on busy frames) but reaches a SHORTER ladder — 1080p and 10 seconds maximum — while costing about a third more. Pro is for a dense final render; base is for iteration, long takes and 4K.',
     ],
     columns: [
         [
@@ -706,14 +750,14 @@ const LTX_2_5 = {
     ],
     footer: [
         'Frames, not references. LTX takes a start frame and an optional end frame (which generates a transition between the two) — it has no reference endpoint at all, so identity, style and environment reference images are not available on this model. For character consistency across separate shots, use MiniMax H3 or Kling.',
-        'Aspect ratios are 16:9 and 9:16 only, and native audio is included free at every resolution — there is no sound surcharge on either seat.',
+        'Aspect ratios are 16:9 and 9:16 only, and native audio is included free at every resolution — there is no sound surcharge on either model.',
         'In image-to-video, do not cut away from the opening frame too early: you have paid for that frame, so let it play before the first move.',
     ],
 };
 const INWORLD_TTS = {
     label: 'Inworld TTS-2',
     intro: [
-        'The voice seat: one named voice saying one line. Unlike every other surface in Slates, the prompt is not a description of what you want — it IS the words that get spoken, verbatim, and its length is what you are billed for.',
+        'The voice model: one named voice saying one line. Unlike every other surface in Slates, the prompt is not a description of what you want — it IS the words that get spoken, verbatim, and its length is what you are billed for.',
         'A voice belongs to a character, the same way a face does. Build it once from a clip or a description, then send it lines.',
     ],
     columns: [
@@ -761,7 +805,7 @@ const INWORLD_TTS = {
                 note: 'Numbers, dates and abbreviations are read literally. Write them as they should sound.',
             },
             {
-                heading: 'Know its seat',
+                heading: 'Know its role',
                 note: 'One voice, cleanly. Dialogue mixed with effects and room tone in one pass is Seed Audio; a single non-speech sound is Sound Effects.',
             },
         ],
@@ -780,6 +824,7 @@ export const PROMPTING_TIPS = {
     'ltx-2-5': LTX_2_5,
     'nano-banana': NANO_BANANA,
     'nano-banana-lite': NANO_BANANA_LITE,
+    'gpt-image-2-5': GPT_IMAGE_25,
     'seed-audio': SEED_AUDIO,
     'eleven-sfx': ELEVEN_SFX,
     'inworld-tts-2': INWORLD_TTS,

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.