@slatesvideo/shared 0.4.2 → 0.4.4

package/dist/operations/index.d.ts

@@ -93,6 +93,19 @@ export declare const createEnvironment: Operation<{
     description?: string;
     style?: string;
 }>;
+export declare const generateCharacterSheets: Operation<{
+    characterId: string;
+    projectId: string;
+    baseAssetId: string;
+    sheetTypes?: ('turnaround' | 'expression')[];
+    userNotes?: string;
+}>;
+export declare const generateEnvironmentPlate: Operation<{
+    environmentId: string;
+    projectId: string;
+    baseAssetId?: string;
+    userNotes?: string;
+}>;
 export declare const listStoryboards: Operation<{
     projectId: string;
 }>;
@@ -153,9 +166,14 @@ export declare const generateVideo: Operation<{
     firstFrameAssetId?: string;
     lastFrameAssetId?: string;
     ingredientAssetIds?: string[];
+    characterAssetIds?: string[];
+    environmentAssetIds?: string[];
+    styleAssetIds?: string[];
+    videoReferenceAssetId?: string;
     sound?: boolean;
     audioLanguage?: 'EN' | 'ZH' | 'JA' | 'KO' | 'ES';
     generateMusic?: boolean;
+    seedanceFace?: boolean;
     negativePrompt?: string;
     background?: boolean;
     confirm?: boolean;
@@ -171,6 +189,7 @@ export declare const generateLipSync: Operation<{
     ttsSpeed?: number;
     audioFilePath?: string;
     avatarModel?: 'avatar-standard' | 'avatar-pro';
+    klingProvider?: 'fal' | 'kling';
     background?: boolean;
     confirm?: boolean;
 }>;
@@ -181,6 +200,7 @@ export declare const generateMotionTransfer: Operation<{
     motionModel?: 'kling-mc-std' | 'kling-mc-pro';
     characterOrientation?: 'video' | 'image';
     prompt?: string;
+    klingProvider?: 'fal' | 'kling';
     background?: boolean;
     confirm?: boolean;
 }>;

package/dist/operations/index.js

@@ -372,6 +372,51 @@ export const createEnvironment = {
         return ok(await ctx.desktop().post('/agent/environments', input));
     },
 };
+export const generateCharacterSheets = {
+    id: 'slates_generate_character_sheets',
+    description: "Generate a character's turnaround sheet (4 neutral full-body angles — identity: body, proportions, outfit) AND expression sheet (close-up facial detail) from a base portrait asset, on Nano Banana 2 at 2K, and bind both to the character. THE real character-building workflow — call right after slates_create_character. baseAssetId is the source portrait (a project asset). Both sheets generate by default. Afterward, carry the character into a scene by passing its turnaround + expression asset ids as characterAssetIds to slates_generate_video (or referenceAssetIds to slates_generate_image) so identity stays consistent across shots. Cost ~$0.36 for both sheets.",
+    input: z.object({
+        characterId: z.string().uuid(),
+        projectId: z.string().uuid(),
+        baseAssetId: z.string().uuid().describe('The base portrait asset the sheets are generated from.'),
+        sheetTypes: z
+            .array(z.enum(['turnaround', 'expression']))
+            .optional()
+            .describe('Which sheets to generate. Default both.'),
+        userNotes: z.string().optional().describe('Extra instruction, e.g. "use the woman on the left".'),
+    }),
+    async run(input, ctx) {
+        return ok(await ctx.desktop().post('/agent/characters/generate-sheets', {
+            characterId: input.characterId,
+            projectId: input.projectId,
+            baseAssetIds: [input.baseAssetId],
+            sheetTypes: input.sheetTypes,
+            userNotes: input.userNotes,
+        }));
+    },
+};
+export const generateEnvironmentPlate = {
+    id: 'slates_generate_environment_plate',
+    description: "Generate an environment's single clean establishing plate (Nano Banana 2, 2K) from an optional base image, and bind it as the environment's reference. THE real environment-building workflow — call right after slates_create_environment. Afterward, pass the plate asset id as environmentAssetIds to slates_generate_video (or referenceAssetIds to slates_generate_image) so the location stays consistent across shots. Cost ~$0.18.",
+    input: z.object({
+        environmentId: z.string().uuid(),
+        projectId: z.string().uuid(),
+        baseAssetId: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Optional base image to establish from (e.g. a rough location shot).'),
+        userNotes: z.string().optional(),
+    }),
+    async run(input, ctx) {
+        return ok(await ctx.desktop().post('/agent/environments/generate-plate', {
+            environmentId: input.environmentId,
+            projectId: input.projectId,
+            baseAssetIds: input.baseAssetId ? [input.baseAssetId] : [],
+            userNotes: input.userNotes,
+        }));
+    },
+};
 // ── Storyboards ─────────────────────────────────────────────────
 export const listStoryboards = {
     id: 'slates_list_storyboards',
@@ -932,9 +977,12 @@ const KLING_TIER_MAP = {
 };
 function videoCostKey(input) {
     if (input.model.startsWith('seedance')) {
-        // Mirrors seedanceCreditKey() in slate/src/shared/pricing.ts (res × duration).
+        // Mirrors seedanceCreditKey() in slate/src/shared/pricing.ts (face × res × duration).
+        // Face route (AI-character face ref) bills the EvoLink relaxed rate (+10%) via
+        // the `-face-` key; faceless uses the cheaper BytePlus key.
         const res = input.videoResolution ?? '1080p';
-        return `${input.model}-${res}-${input.duration}s`;
+        const face = input.seedanceFace ? '-face' : '';
+        return `${input.model}${face}-${res}-${input.duration}s`;
     }
     if (input.model.startsWith('veo')) {
         const is4k = input.videoResolution === '4k';
@@ -979,9 +1027,14 @@ export const generateVideo = {
         firstFrameAssetId: z.string().uuid().optional().describe('Asset id from the project — used as the starting frame for image-to-video. Must already exist in the project.'),
         lastFrameAssetId: z.string().uuid().optional().describe('Asset id from the project — used as the ending frame. Veo and Seedance only. Pairs with firstFrameAssetId for guided transitions.'),
         ingredientAssetIds: z.array(z.string().uuid()).max(9).optional().describe('Asset ids used as visual reference / ingredients for Kling Omni or Seedance. Up to 9 (Seedance) or 4 (Kling).'),
+        characterAssetIds: z.array(z.string().uuid()).optional().describe('Asset ids of character sheets — keeps a character consistent across the shot. From a Slates project.'),
+        environmentAssetIds: z.array(z.string().uuid()).optional().describe('Asset ids of environment grids — keeps a location/setting consistent across the shot. From a Slates project.'),
+        styleAssetIds: z.array(z.string().uuid()).optional().describe('Asset ids of style references — locks the visual style of the shot. From a Slates project.'),
+        videoReferenceAssetId: z.string().uuid().optional().describe('Seedance ONLY: an existing VIDEO asset to use as a reference (edit / relocate an existing clip — Seedance ref-to-video). 2-15s. If the clip contains a human/AI character, pair with seedanceFace=true so it routes to the face-capable provider (the default Seedance route blocks people). Ignored by Kling/Veo.'),
         sound: z.boolean().optional().describe('Kling Omni / Veo / Seedance: enable audio generation. Default true.'),
         audioLanguage: z.enum(['EN', 'ZH', 'JA', 'KO', 'ES']).optional().describe('Kling Omni only — language for dialogue.'),
         generateMusic: z.boolean().optional().describe('Kling Omni only — auto-generate background music.'),
+        seedanceFace: z.boolean().optional().describe('Seedance ONLY: set true when a reference/ingredient shows an AI-character\'s FACE. Faces are blocked on the default (cheaper) Seedance route, so this reroutes the gen to a face-capable provider and costs ~10% more (the cost key becomes seedance-2-face-*). Leave false/unset for faceless or object-only references. No effect on Kling/Veo. Real-person faces are not supported on any route.'),
         negativePrompt: z.string().optional(),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true after explicit user OK to bypass the >$0.50 cost confirm gate (which fires for almost every video gen since they\'re expensive).'),
@@ -1039,6 +1092,7 @@ export const generateVideo = {
             duration: input.duration,
             videoResolution: input.videoResolution,
             sound: input.sound,
+            seedanceFace: input.seedanceFace,
         });
         const entry = registry.models.find((m) => m.model === costKey);
         if (!entry) {
@@ -1064,6 +1118,15 @@ export const generateVideo = {
         for (const id of input.ingredientAssetIds ?? []) {
             referenceRefs.push({ id, type: 'image', role: 'ingredient' });
         }
+        for (const id of input.characterAssetIds ?? []) {
+            referenceRefs.push({ id, type: 'image', role: 'character' });
+        }
+        for (const id of input.environmentAssetIds ?? []) {
+            referenceRefs.push({ id, type: 'image', role: 'environment' });
+        }
+        for (const id of input.styleAssetIds ?? []) {
+            referenceRefs.push({ id, type: 'image', role: 'style' });
+        }
         const hasReferences = referenceRefs.length > 0;
         if ((totalCents > 50 || hasReferences) && !input.confirm) {
             const previews = hasReferences ? await previewAssets(ctx, referenceRefs) : [];
@@ -1111,9 +1174,14 @@ export const generateVideo = {
             firstFrameAssetId: input.firstFrameAssetId,
             lastFrameAssetId: input.lastFrameAssetId,
             ingredientAssetIds: input.ingredientAssetIds ?? [],
+            characterAssetIds: input.characterAssetIds ?? [],
+            environmentAssetIds: input.environmentAssetIds ?? [],
+            styleAssetIds: input.styleAssetIds ?? [],
+            videoReferenceAssetId: input.videoReferenceAssetId,
             sound: input.sound,
             audioLanguage: input.audioLanguage,
             generateMusic: input.generateMusic,
+            seedanceFace: input.seedanceFace,
             negativePrompt: input.negativePrompt,
             background: input.background,
         });
@@ -1163,6 +1231,7 @@ export const generateLipSync = {
         ttsSpeed: z.number().min(0.5).max(2).optional().describe('TTS speech rate. Default 1.0. Range 0.5-2.0.'),
         audioFilePath: z.string().optional().describe('Required when audioMethod=upload. Absolute path to the audio file on the user\'s machine (mp3, wav, m4a).'),
         avatarModel: z.enum(['avatar-standard', 'avatar-pro']).optional().describe('Image-source only. avatar-standard ($0.42/5s) for general use. avatar-pro ($0.86/5s) for sharper face fidelity. Ignored when sourceType=video.'),
+        klingProvider: z.enum(['fal', 'kling']).optional().describe('Provider routing for the Kling call. "fal" (default) uses Slates credits. "kling" uses the user\'s own BYOK Kling key if configured — omit unless the user explicitly wants BYOK.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the >$0.50 cost confirm gate. Required for avatar-pro.'),
     }),
@@ -1231,6 +1300,7 @@ export const generateLipSync = {
             ttsSpeed: input.ttsSpeed,
             audioFilePath: input.audioFilePath,
             avatarModel: input.avatarModel,
+            klingProvider: input.klingProvider,
             estimatedCost: totalCents,
             background: input.background,
         });
@@ -1276,6 +1346,7 @@ export const generateMotionTransfer = {
         motionModel: z.enum(['kling-mc-std', 'kling-mc-pro']).optional().describe('std ($0.95) for general motion. pro ($1.26) for cleaner anatomy + identity preservation. Default pro — pick std deliberately for cost savings.'),
         characterOrientation: z.enum(['video', 'image']).optional().describe('"video" = use the source video\'s framing. "image" = use the target image\'s framing. Default video.'),
         prompt: z.string().optional().describe('Optional refinement prompt. Read slates-prompting-motion-transfer for guidance.'),
+        klingProvider: z.enum(['fal', 'kling']).optional().describe('Provider routing for the Kling call. "fal" (default) uses Slates credits. "kling" uses the user\'s own BYOK Kling key if configured — omit unless the user explicitly wants BYOK.'),
         background: z.boolean().optional().describe(BACKGROUND_DESCRIBE),
         confirm: z.boolean().optional().describe('Set true to bypass the >$0.50 confirm gate. Required — both tiers exceed.'),
     }),
@@ -1322,6 +1393,7 @@ export const generateMotionTransfer = {
             motionModel,
             characterOrientation: input.characterOrientation ?? 'video',
             prompt: input.prompt,
+            klingProvider: input.klingProvider,
             estimatedCost: totalCents,
             background: input.background,
         });
@@ -1874,6 +1946,8 @@ export const ALL_OPERATIONS = [
     setCharacterExpression,
     listEnvironments,
     createEnvironment,
+    generateCharacterSheets,
+    generateEnvironmentPlate,
     listStoryboards,
     createStoryboard,
     getStoryboardWithFrames,

package/dist/prompts/index.d.ts

@@ -1,4 +1,5 @@
 export * from './reference-rules.js';
+export * from './reference-composer.js';
 export * from './content-policy.js';
 export * from './style-library.js';
 export * from './model-facts.js';

package/dist/prompts/index.js

@@ -10,6 +10,7 @@
 // plan). So a change here must be applied to those copies in the same pass for
 // now. SSOT map: second-brain business/projects/slates/product/prompting-ssot.md
 export * from './reference-rules.js';
+export * from './reference-composer.js';
 export * from './content-policy.js';
 export * from './style-library.js';
 export * from './model-facts.js';

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

@@ -0,0 +1,46 @@
+export type ReferenceKind = 'character' | 'environment' | 'style' | 'pinned' | 'first-frame' | 'last-frame' | 'video';
+export interface ReferenceMedia {
+    path: string;
+    mediaKind: 'image' | 'video';
+}
+/**
+ * A named bucket of reference media that can be @mentioned. The whole definition
+ * of a reference. It does NOT mandate a structure — one photo or eight angles,
+ * the composer treats them all as "this is one named thing".
+ */
+export interface ReferenceGroup {
+    /** '@Marcus' | '@Cafe' | '#noir' | null (pinned / frames / picked video) */
+    token: string | null;
+    /** Display + citation name: 'Marcus' | 'the cafe' | 'noir'. Used verbatim. */
+    name: string;
+    kind: ReferenceKind;
+    /** A group can carry several images (e.g. turnaround + expression). */
+    media: ReferenceMedia[];
+}
+export interface ComposedReferences {
+    /** The composed prompt: user's words lead, references cited inline as "image N". */
+    prompt: string;
+    /** Free-reference image paths in cited order — flatten yields "image 1..N". */
+    orderedImagePaths: string[];
+    /** Video reference paths in cited order — "video 1..M". */
+    orderedVideoPaths: string[];
+}
+/**
+ * Compose the raw prompt (mentions intact) + an ORDERED list of reference groups
+ * into the named prompt text + ordered media the API receives. The group order
+ * IS the send order — image numbers are assigned by walking the list, so the
+ * caller controls numbering by ordering the list (default: pinned/base first,
+ * then @mentions in first-appearance order, then #style last).
+ *
+ * @param rawPrompt  the user's prompt with @mentions / #tags still in it
+ * @param groups     the single ordered ReferenceGroup[] (rail + prompt read this)
+ * @param opts.startImageNumber  images already attached AHEAD of these groups
+ *   (e.g. a grid-cell base that is "image 1" before the free-refs). Free-ref
+ *   numbering and orderedImagePaths begin after it. Default 0.
+ */
+export interface ComposeOptions {
+    startImageNumber?: number;
+    startVideoNumber?: number;
+}
+export declare function composeReferences(rawPrompt: string, groups: ReferenceGroup[], opts?: ComposeOptions): ComposedReferences;
+//# sourceMappingURL=reference-composer.d.ts.map

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.