@slatesvideo/shared 0.4.1 → 0.4.3

package/dist/prompts/reference-composer.js

@@ -0,0 +1,175 @@
+// Reference composition — the prompt-as-SSOT composer.
+//
+// THE PRINCIPLE: the prompt box is the single source of truth. The app's ENTIRE
+// contribution to the model prompt is (a) translate @mentions/#tags into the
+// lightweight "image N" naming the models actually parse, and (b) name
+// token-less references (pinned images, frames, videos) by number. Nothing
+// else — no role essays, no "ignore the outfit", no injected lighting/expression
+// rules. What the user writes is what leads.
+//
+// This is the canonical implementation. It is mirrored byte-for-byte into the
+// desktop app's `slate/src/shared/promptComposition.ts` (the desktop installs
+// the published @slatesvideo/shared from npm and cannot file-import this source,
+// so the mirror carries a header pointing here). Both the agent/MCP paths and
+// the desktop generation + rail read from this one function, so the rail's badge
+// numbers and the prompt's "image N" citations can never desync.
+//
+// Naming is the ONLY identity signal. Citing both of a subject's images as the
+// SAME name ("Marcus (images 1 and 2)") tells the model they are ONE entity —
+// which is what prevents a multi-image bucket from averaging into a blended
+// face. This 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`.
+function normToken(s) {
+    return s.toLowerCase().replace(/[@#]/g, '').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
+// NOT part of the free-reference numbering — see the reference-rules note that
+// first/last-frame can't mix with free refs on models like Seedance.
+function isFreeRefImageKind(kind) {
+    return kind === 'character' || kind === 'environment' || kind === 'style' || kind === 'pinned';
+}
+/** "image 5" / "images 5 and 6" / "images 5, 6 and 7" (lowercase, for inline use). */
+function citeImages(nums) {
+    const noun = nums.length === 1 ? 'image' : 'images';
+    return `${noun} ${joinNums(nums)}`;
+}
+function joinNums(nums) {
+    if (nums.length === 1)
+        return String(nums[0]);
+    if (nums.length === 2)
+        return `${nums[0]} and ${nums[1]}`;
+    return `${nums.slice(0, -1).join(', ')} and ${nums[nums.length - 1]}`;
+}
+// Humanize an unresolved @token to plain words (preserve the legacy cleanPrompt
+// fallback: @big_red → "Big Red", @forest3 → "Forest3"). Never send a raw token.
+function humanizeToken(raw) {
+    return raw
+        .split(/[_-]/)
+        .map((w) => (w ? w.charAt(0).toUpperCase() + w.slice(1) : w))
+        .join(' ');
+}
+export function composeReferences(rawPrompt, groups, opts = {}) {
+    // ── 1. Assign global numbers by walking the list in order ──
+    let imageNum = opts.startImageNumber ?? 0;
+    let videoNum = opts.startVideoNumber ?? 0;
+    const orderedImagePaths = [];
+    const orderedVideoPaths = [];
+    const numbered = groups.map((g) => {
+        const imageNums = [];
+        const videoNums = [];
+        for (const m of g.media) {
+            if (m.mediaKind === 'video' && g.kind === 'video') {
+                videoNum += 1;
+                videoNums.push(videoNum);
+                orderedVideoPaths.push(m.path);
+            }
+            else if (m.mediaKind === 'image' && isFreeRefImageKind(g.kind)) {
+                imageNum += 1;
+                imageNums.push(imageNum);
+                orderedImagePaths.push(m.path);
+            }
+            // first-frame / last-frame media: not numbered, not in the free-ref pool.
+        }
+        return { ...g, imageNums, videoNums };
+    });
+    // ── 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
+    // 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();
+    for (const g of tokenGroups)
+        byNorm.set(normToken(g.token), g);
+    const seenFirst = new Set();
+    const matchedInPrompt = new Set();
+    // 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).
+    let body = rawPrompt.replace(/\s+(with|in)\s+the\s+style\s+of\s+([@#])([\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(/([@#])([\w-]+)/g, (_full, _sigil, tok) => {
+        const key = normToken(`${_sigil}${tok}`);
+        const g = byNorm.get(key);
+        if (!g) {
+            // Unresolved token. A #unknown vanishes; an @unknown humanizes to words.
+            return _sigil === '#' ? '' : humanizeToken(tok);
+        }
+        matchedInPrompt.add(key);
+        if (g.kind === 'style')
+            return ''; // styles never inline — trailing clause only
+        if (!seenFirst.has(key)) {
+            seenFirst.add(key);
+            return `${g.name} (${citeImages(g.imageNums)})`;
+        }
+        return g.name;
+    });
+    // Collapse the whitespace the token removals left behind.
+    body = body.replace(/[ \t]{2,}/g, ' ').replace(/\s+([,.;:!?])/g, '$1').trim();
+    // ── 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
+    // own prompt supplies the intent ("this exact frame", "the man becomes…").
+    const topKeys = [];
+    // Video sources first ("Video 1 is the motion source.").
+    for (const g of numbered) {
+        if (g.kind === 'video' && g.videoNums.length > 0) {
+            const noun = g.videoNums.length === 1 ? 'Video' : 'Videos';
+            const verb = g.videoNums.length === 1 ? 'is' : 'are';
+            topKeys.push(`${noun} ${joinNums(g.videoNums)} ${verb} the motion source.`);
+        }
+    }
+    // Pinned/base references ("Image 1 is a provided reference.").
+    for (const g of numbered) {
+        if (g.kind === 'pinned' && g.imageNums.length > 0) {
+            const noun = g.imageNums.length === 1 ? 'Image' : 'Images';
+            const tail = g.imageNums.length === 1 ? 'is a provided reference.' : 'are provided references.';
+            topKeys.push(`${noun} ${joinNums(g.imageNums)} ${tail}`);
+        }
+    }
+    // Token-less or not-in-prompt subjects/environments ("Image 1 is Marcus.").
+    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}.`);
+            }
+        }
+    }
+    // ── 4. Style trailing clause (one, at the end — style reads best last) ──
+    const styleNums = [];
+    for (const g of numbered) {
+        if (g.kind === 'style')
+            styleNums.push(...g.imageNums);
+    }
+    const styleClauses = [];
+    if (styleNums.length > 0) {
+        styleClauses.push(`Render in the visual style of ${citeImages(styleNums)}.`);
+    }
+    // ── 5. Assemble: [top key line] · [body] · [style clause], blank-line separated ──
+    const parts = [];
+    if (topKeys.length > 0)
+        parts.push(topKeys.join(' '));
+    if (body)
+        parts.push(body);
+    if (styleClauses.length > 0)
+        parts.push(styleClauses.join(' '));
+    return {
+        prompt: parts.join('\n\n'),
+        orderedImagePaths,
+        orderedVideoPaths,
+    };
+}
+//# sourceMappingURL=reference-composer.js.map

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

@@ -30,5 +30,5 @@ export declare const REFERENCE_RULES_HEADLINE = "Identity = a few flat-lit neutr
  * plans/2026-06-25-slates-prompting-system-overhaul.md). The TARGET is to
  * inject this text so it can't drift; today it's reconciled manually.
  */
-export declare const REFERENCE_RULES_TEXT = "## Reference rules (how to use reference images)\n\nIdentity = a few flat-lit neutral angles; one reference per role, labeled; 2-4 refs not 12; describe environments instead of feeding a grid.\n\n1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs.\n2. **One reference per ROLE, labeled in the prompt.** Identity / style-grade / environment. The model does not infer roles from order \u2014 name each role in the prompt text. Same-role competitors drift.\n3. **Attach both sheets \u2014 label them, don't gate them.** Attach the full-body turnaround (body/proportion/outfit) AND the close-up expression sheet (high-res facial detail: eyes, skin, teeth, bone structure). Label both as identity references and tell the model to render the SCENE's expression (default neutral). An *unlabeled* expression sheet hurts (the model copies the varied expressions \u2192 midpoint face); *labeled*, the close-ups are a fidelity win. The trend is MORE references \u2014 role-labeling is what makes many refs work.\n4. **Flat-light identity refs.** Prep identity refs with flat, even, shadowless lighting on a plain neutral background. Studio-lit / scene-lit sheets bleed their lighting into every generation (the studio-lit sheet \u2192 \"green-screen-pasted in front of mountains\" failure). Reference prep beats prompting here.\n5. **Environment: describe it, don't feed a grid.** Default to describing the location in words. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural, even ambient lighting that reads as the location's real light, not a studio setup \u2014 never a multi-panel grid fed whole.\n6. **Grids: explore, don't input.** Use grids to explore compositions cheaply, then pick a cell. Never feed a grid back in as a reference \u2014 cells share a split detail budget and generate jointly, so flaws propagate.\n7. **Reuse the same refs across all shots.** Lock a set and reuse it; swapping refs mid-sequence causes drift.\n8. **Legible in-shot text \u2192 bake it into an image start frame, never trust text-to-video.** Animate from the locked frame.\n9. **I2V / own-footage superpower.** Restyle your own clip keeping the performance; delayed-VFX on \"video one\"; marker-object insertion; video-as-ref for a series. Describe ONLY what changes.\n10. **Style transform by natural language.** Default keeps the source's art style; an optional plain-text instruction transforms it (\"anime \u2192 real person\"). No preset pickers.";
+export declare const REFERENCE_RULES_TEXT = "## Reference rules (how to use reference images)\n\nIdentity = a few flat-lit neutral angles; one reference per role, labeled; 2-4 refs not 12; describe environments instead of feeding a grid.\n\n1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs.\n2. **One reference per ROLE, labeled in the prompt.** Identity / style-grade / environment. The model does not infer roles from order \u2014 name each role in the prompt text. Same-role competitors drift.\n3. **Attach both sheets \u2014 NAME them as one entity, don't gate them.** Attach the full-body turnaround (body/proportion/outfit) AND the close-up expression sheet (high-res facial detail: eyes, skin, teeth, bone structure). NAME both inline as the same subject (\"Marcus (images 1 and 2)\") \u2014 the shared name tells the model they are ONE person, which is what stops the varied expressions from averaging the face. Do **not** inject a role essay (\"use for identity, ignore the outfit/lighting, render neutral\") \u2014 that drags the studio-lit sheet's wardrobe + lighting into the scene; the user's prompt owns wardrobe, expression, and lighting. Naming-as-one-entity IS each model's official lever (NB2 \"assign a distinct name\"; Seedance \"Reference Subject_N in Image_N\"; Kling \"reuse a fixed label verbatim\"). The trend is MORE references \u2014 addressing each by name is what makes many refs work.\n4. **Flat-light identity refs.** Prep identity refs with flat, even, shadowless lighting on a plain neutral background. Studio-lit / scene-lit sheets bleed their lighting into every generation (the studio-lit sheet \u2192 \"green-screen-pasted in front of mountains\" failure). Reference prep beats prompting here.\n5. **Environment: describe it, don't feed a grid.** Default to describing the location in words. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural, even ambient lighting that reads as the location's real light, not a studio setup \u2014 never a multi-panel grid fed whole.\n6. **Grids: explore, don't input.** Use grids to explore compositions cheaply, then pick a cell. Never feed a grid back in as a reference \u2014 cells share a split detail budget and generate jointly, so flaws propagate.\n7. **Reuse the same refs across all shots.** Lock a set and reuse it; swapping refs mid-sequence causes drift.\n8. **Legible in-shot text \u2192 bake it into an image start frame, never trust text-to-video.** Animate from the locked frame.\n9. **I2V / own-footage superpower.** Restyle your own clip keeping the performance; delayed-VFX on \"video one\"; marker-object insertion; video-as-ref for a series. Describe ONLY what changes.\n10. **Style transform by natural language.** Default keeps the source's art style; an optional plain-text instruction transforms it (\"anime \u2192 real person\"). No preset pickers.";
 //# sourceMappingURL=reference-rules.d.ts.map

package/dist/prompts/reference-rules.js

@@ -25,10 +25,10 @@ export const REFERENCE_RULES = [
         grade: 'community',
     },
     {
-        id: 'identity-label-roles',
-        title: 'Attach both sheets — label them, don\'t gate them',
-        rule: 'Attach BOTH the full-body turnaround (body/proportion/outfit) AND the close-up expression sheet (high-res facial detail). Label them as identity references and tell the model to render the SCENE\'s expression (default neutral). The label — not gating — is what stops the multiple expressions from averaging the face.',
-        why: 'An UNLABELED expression sheet hurts: the model copies its varied expressions and the face drifts to a midpoint. Labeled ("use for identity; render the scene\'s expression"), the close-ups are a fidelity win — they carry far more facial signal (eyes, skin, teeth, bone structure) than the postage-stamp faces in a full-body turnaround. The trend is MORE references (video/audio/3D into Seedance-class models); role-labeling is what makes many refs work, so lean into attaching rich refs and labeling every role.',
+        id: 'identity-name-as-one-entity',
+        title: 'Attach both sheets — NAME them as one entity, don\'t gate them',
+        rule: 'Attach BOTH the full-body turnaround (body/proportion/outfit) AND the close-up expression sheet (high-res facial detail). NAME both inline as the SAME subject ("Marcus (images 1 and 2)") — that shared name is what tells the model they are ONE person and stops the varied expressions from averaging the face. Do NOT inject a role essay ("use for identity, ignore the outfit/lighting, render neutral"): the user\'s prompt owns wardrobe, expression, and lighting.',
+        why: 'Naming both images as one entity IS each model\'s OWN official consistency lever — NB2 "assign a distinct name to each character/object"; Seedance "Reference <Subject_N> in <Image_N>"; Kling "reuse a fixed label verbatim". The old heavy role-essay was the OFF-doctrine part: telling the model to "use for identity" while injecting "ignore the outfit" dragged the studio-lit sheet\'s wardrobe + lighting into scenes that explicitly wanted otherwise (the movie-still injection failure). The close-ups still carry far more facial signal (eyes, skin, teeth, bone structure) than a turnaround\'s postage-stamp faces, so attach both — the NAME, not an instruction, is what makes many refs work. The trend is MORE references (video/audio/3D into Seedance-class models), all addressed by name.',
         grade: 'Eric-test',
     },
     {
@@ -109,7 +109,7 @@ ${REFERENCE_RULES_HEADLINE}
 
 1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs.
 2. **One reference per ROLE, labeled in the prompt.** Identity / style-grade / environment. The model does not infer roles from order — name each role in the prompt text. Same-role competitors drift.
-3. **Attach both sheets — label them, don't gate them.** Attach the full-body turnaround (body/proportion/outfit) AND the close-up expression sheet (high-res facial detail: eyes, skin, teeth, bone structure). Label both as identity references and tell the model to render the SCENE's expression (default neutral). An *unlabeled* expression sheet hurts (the model copies the varied expressions → midpoint face); *labeled*, the close-ups are a fidelity win. The trend is MORE references — role-labeling is what makes many refs work.
+3. **Attach both sheets — NAME them as one entity, don't gate them.** Attach the full-body turnaround (body/proportion/outfit) AND the close-up expression sheet (high-res facial detail: eyes, skin, teeth, bone structure). NAME both inline as the same subject ("Marcus (images 1 and 2)") — the shared name tells the model they are ONE person, which is what stops the varied expressions from averaging the face. Do **not** inject a role essay ("use for identity, ignore the outfit/lighting, render neutral") — that drags the studio-lit sheet's wardrobe + lighting into the scene; the user's prompt owns wardrobe, expression, and lighting. Naming-as-one-entity IS each model's official lever (NB2 "assign a distinct name"; Seedance "Reference Subject_N in Image_N"; Kling "reuse a fixed label verbatim"). The trend is MORE references — addressing each by name is what makes many refs work.
 4. **Flat-light identity refs.** Prep identity refs with ${IDENTITY_LIGHTING} on a plain neutral background. Studio-lit / scene-lit sheets bleed their lighting into every generation (the studio-lit sheet → "green-screen-pasted in front of mountains" failure). Reference prep beats prompting here.
 5. **Environment: describe it, don't feed a grid.** Default to describing the location in words. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with ${ENVIRONMENT_NATURAL_LIGHT} — never a multi-panel grid fed whole.
 6. **Grids: explore, don't input.** Use grids to explore compositions cheaply, then pick a cell. Never feed a grid back in as a reference — cells share a split detail budget and generate jointly, so flaws propagate.