@slatesvideo/shared 0.3.0 → 0.4.1

package/dist/operations/index.d.ts

@@ -74,7 +74,7 @@ export declare const createCharacter: Operation<{
     projectId: string;
     name: string;
     description?: string;
-    style?: 'realistic' | 'anime' | 'pixar' | 'comic-book';
+    style?: string;
 }>;
 export declare const setCharacterTurnaround: Operation<{
     characterId: string;
@@ -91,7 +91,7 @@ export declare const createEnvironment: Operation<{
     projectId: string;
     name: string;
     description?: string;
-    style?: 'realistic' | 'anime' | 'pixar' | 'comic-book';
+    style?: string;
 }>;
 export declare const listStoryboards: Operation<{
     projectId: string;
@@ -256,7 +256,7 @@ export declare const updateCharacter: Operation<{
     characterId: string;
     name?: string;
     description?: string;
-    style?: 'realistic' | 'anime' | 'pixar' | 'comic-book';
+    style?: string;
 }>;
 export declare const deleteCharacter: Operation<{
     characterId: string;
@@ -265,7 +265,7 @@ export declare const updateEnvironment: Operation<{
     environmentId: string;
     name?: string;
     description?: string;
-    style?: 'realistic' | 'anime' | 'pixar' | 'comic-book';
+    style?: string;
     gridAssetId?: string | null;
 }>;
 export declare const deleteEnvironment: Operation<{

package/dist/operations/index.js

@@ -316,7 +316,7 @@ export const createCharacter = {
         projectId: z.string().uuid(),
         name: z.string().min(1).max(120),
         description: z.string().optional(),
-        style: z.enum(['realistic', 'anime', 'pixar', 'comic-book']).optional(),
+        style: z.string().max(200).optional().describe("Art style. Omit to inherit the reference's style (the default). Canonical styles: photoreal, anime, painterly, 3d-render, comic. Or pass any free-text instruction, e.g. 'turn this into a real person'."),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/characters', input));
@@ -366,7 +366,7 @@ export const createEnvironment = {
         projectId: z.string().uuid(),
         name: z.string().min(1).max(120),
         description: z.string().optional(),
-        style: z.enum(['realistic', 'anime', 'pixar', 'comic-book']).optional(),
+        style: z.string().max(200).optional().describe("Art style. Omit to inherit the reference's style (the default). Canonical styles: photoreal, anime, painterly, 3d-render, comic. Or pass any free-text instruction, e.g. 'turn this into a real person'."),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/environments', input));
@@ -1627,7 +1627,7 @@ export const updateCharacter = {
         characterId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
         description: z.string().optional(),
-        style: z.enum(['realistic', 'anime', 'pixar', 'comic-book']).optional(),
+        style: z.string().max(200).optional().describe("Art style. Omit to inherit the reference's style (the default). Canonical styles: photoreal, anime, painterly, 3d-render, comic. Or pass any free-text instruction, e.g. 'turn this into a real person'."),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/characters/update', {
@@ -1651,7 +1651,7 @@ export const updateEnvironment = {
         environmentId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
         description: z.string().optional(),
-        style: z.enum(['realistic', 'anime', 'pixar', 'comic-book']).optional(),
+        style: z.string().max(200).optional().describe("Art style. Omit to inherit the reference's style (the default). Canonical styles: photoreal, anime, painterly, 3d-render, comic. Or pass any free-text instruction, e.g. 'turn this into a real person'."),
         gridAssetId: z.string().uuid().nullable().optional(),
     }),
     async run(input, ctx) {

package/dist/prompts/character-sheet.d.ts

@@ -0,0 +1,24 @@
+/** Turnaround = the IDENTITY reference. 4 neutral full-body angles. */
+export declare const CHARACTER_ANGLES_DESC = "front view, back view, left side profile, right side profile";
+/**
+ * Expression-sheet close-ups = the FACE identity reference (high-res
+ * eyes/skin/teeth/bone). Attached alongside the turnaround; the scene-time
+ * reference label drives the rendered expression.
+ */
+export declare const CHARACTER_EXPRESSIONS_DESC = "neutral expression on left, genuine smile showing teeth in center, serious frown on right";
+export declare const BODY_POSE_LABELS: readonly ["front", "back", "profile-left", "profile-right"];
+export declare const EXPRESSION_LABELS: readonly ["neutral", "smile", "serious"];
+/**
+ * Body turnaround sheet — the identity reference.
+ * @param userStyle optional natural-language style transform (e.g. "make her a real person")
+ */
+export declare function buildCharacterTurnaroundPrompt(userStyle?: string | null): string;
+/**
+ * Expression sheet — the close-up face reference. Its three portraits carry
+ * high-res facial detail (eyes, skin, teeth, bone structure) plus the
+ * character's expression range. Attached ALONGSIDE the turnaround; the
+ * reference label drives identity-use + scene-driven expression so the multiple
+ * expressions don't average the generated face.
+ */
+export declare function buildExpressionSheetPrompt(userStyle?: string | null): string;
+//# sourceMappingURL=character-sheet.d.ts.map

package/dist/prompts/character-sheet.js

@@ -0,0 +1,53 @@
+// Canonical character-sheet prompt content. ONE mode: inherit the source's
+// medium, render on a flat-lit plain background, optional natural-language
+// style transform. (Replaces the old photorealistic / match-reference fork
+// that baked studio lighting or a scene's lighting into the identity ref.)
+//
+// This is the SOURCE OF TRUTH that the desktop templates, the MCP skill
+// markdown, and the lead-magnet are RECONCILED against. They do NOT import it
+// yet (the skill-embed + desktop-import wiring is future work per
+// plans/2026-06-25-slates-prompting-system-overhaul.md), so when you change a
+// rule here, update those copies in the same pass until the wiring ships.
+import { IDENTITY_LIGHTING_CLAUSE, INHERIT_SOURCE_STYLE, } from './reference-rules.js';
+import { renderStyleInstruction } from './style-library.js';
+/** Turnaround = the IDENTITY reference. 4 neutral full-body angles. */
+export const CHARACTER_ANGLES_DESC = 'front view, back view, left side profile, right side profile';
+/**
+ * Expression-sheet close-ups = the FACE identity reference (high-res
+ * eyes/skin/teeth/bone). Attached alongside the turnaround; the scene-time
+ * reference label drives the rendered expression.
+ */
+export const CHARACTER_EXPRESSIONS_DESC = 'neutral expression on left, genuine smile showing teeth in center, serious frown on right';
+export const BODY_POSE_LABELS = ['front', 'back', 'profile-left', 'profile-right'];
+export const EXPRESSION_LABELS = ['neutral', 'smile', 'serious'];
+// The sheet's style directive: a user transform REPLACES the inherit-source
+// instruction (so the model isn't told to both preserve the medium AND change
+// it); otherwise inherit the source medium.
+function styleDirective(userStyle) {
+    return renderStyleInstruction(userStyle).trim() || INHERIT_SOURCE_STYLE;
+}
+/**
+ * Body turnaround sheet — the identity reference.
+ * @param userStyle optional natural-language style transform (e.g. "make her a real person")
+ */
+export function buildCharacterTurnaroundPrompt(userStyle) {
+    return (`Character model reference sheet with 4 full body views of the same character: ${CHARACTER_ANGLES_DESC}. ` +
+        `Neutral pose, neutral expression, consistent character appearance across all views. ` +
+        `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} ` +
+        `For upright/bipedal characters arrange side-by-side; for quadruped/animal characters use a 2x2 grid. ` +
+        `No text, no labels, no captions.`);
+}
+/**
+ * Expression sheet — the close-up face reference. Its three portraits carry
+ * high-res facial detail (eyes, skin, teeth, bone structure) plus the
+ * character's expression range. Attached ALONGSIDE the turnaround; the
+ * reference label drives identity-use + scene-driven expression so the multiple
+ * expressions don't average the generated face.
+ */
+export function buildExpressionSheetPrompt(userStyle) {
+    return (`Character expression reference sheet with 3 head and shoulder portraits arranged side by side horizontally: ${CHARACTER_EXPRESSIONS_DESC}. ` +
+        `Consistent character appearance across all three. ` +
+        `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} Same framing for each. ` +
+        `No text, no labels, no captions.`);
+}
+//# sourceMappingURL=character-sheet.js.map

package/dist/prompts/environment-sheet.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Single establishing image of an empty location — the optional
+ * exact-match environment reference. One frame, naturally lit.
+ * @param userStyle optional natural-language style transform
+ */
+export declare function buildEnvironmentEstablishingPrompt(userStyle?: string | null): string;
+/** Guidance shown to users/agents: prefer describing the environment in text. */
+export declare const ENVIRONMENT_DESCRIBE_FIRST = "Default to describing the environment in words and let the model build it to fit the shot. Generate an establishing plate only when a location must be locked exactly across shots.";
+//# sourceMappingURL=environment-sheet.d.ts.map

package/dist/prompts/environment-sheet.js

@@ -0,0 +1,27 @@
+// Canonical environment-plate prompt content. ONE clean establishing image —
+// NOT a 3x3 grid fed whole (that was Eric's "green-screen pasted in front of
+// mountains" failure: a bordered collage used as a reference). Default
+// workflow is to DESCRIBE the location in words; this plate is the optional
+// exact-match lock, and when used it is a single naturally-lit frame.
+import { ENVIRONMENT_NATURAL_LIGHT, INHERIT_SOURCE_STYLE, } from './reference-rules.js';
+import { renderStyleInstruction } from './style-library.js';
+// A user transform REPLACES the inherit-source instruction (no "preserve the
+// medium AND change it" contradiction); otherwise inherit the source medium.
+function styleDirective(userStyle) {
+    return renderStyleInstruction(userStyle).trim() || INHERIT_SOURCE_STYLE;
+}
+/**
+ * Single establishing image of an empty location — the optional
+ * exact-match environment reference. One frame, naturally lit.
+ * @param userStyle optional natural-language style transform
+ */
+export function buildEnvironmentEstablishingPrompt(userStyle) {
+    return (`A single clean establishing shot of this empty location: a wide, eye-level view that captures the space — its architecture or geography, materials, and depth. ` +
+        `The location is empty and unpopulated, ready for scene staging. ` +
+        `${styleDirective(userStyle)} Use ${ENVIRONMENT_NATURAL_LIGHT}. ` +
+        `If the reference image contains people or characters, generate the location as an empty space — ignore the figures. ` +
+        `No text, no labels, no captions.`);
+}
+/** Guidance shown to users/agents: prefer describing the environment in text. */
+export const ENVIRONMENT_DESCRIBE_FIRST = 'Default to describing the environment in words and let the model build it to fit the shot. Generate an establishing plate only when a location must be locked exactly across shots.';
+//# sourceMappingURL=environment-sheet.js.map

package/dist/prompts/index.d.ts

@@ -0,0 +1,6 @@
+export * from './reference-rules.js';
+export * from './style-library.js';
+export * from './model-facts.js';
+export * from './character-sheet.js';
+export * from './environment-sheet.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.js

@@ -0,0 +1,17 @@
+// @slatesvideo/shared/prompts — the canonical "WHAT" layer for Slates model
+// prompting: reference best-practices, the style library, per-model facts, and
+// the character/environment prompt builders. The desktop app, the MCP
+// prompting skills, and the lead-magnet .skill all DERIVE from here.
+//
+// Propagation rule (the TARGET): research → second-brain; encode once → here;
+// everything else derives. Reality today: nothing imports this module yet — the
+// desktop templates and MCP skill markdown are RECONCILED against it by hand
+// until the desktop-import + skill-embed wiring ships (see the SSOT map +
+// 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 './style-library.js';
+export * from './model-facts.js';
+export * from './character-sheet.js';
+export * from './environment-sheet.js';
+//# sourceMappingURL=index.js.map

package/dist/prompts/model-facts.d.ts

@@ -0,0 +1,17 @@
+export interface ModelFact {
+    id: string;
+    label: string;
+    kind: 'image' | 'video';
+    /** Max reference images (image models) — null if not applicable. */
+    maxRefImages: number | null;
+    /** Max ingredient images (video models) — null if not applicable. */
+    maxIngredients: number | null;
+    notes: string;
+}
+export declare const MODEL_FACTS: ModelFact[];
+export declare function getModelFact(id: string): ModelFact | undefined;
+/** The official NB2 / general image prompt formula (subject-first). */
+export declare const IMAGE_PROMPT_FORMULA = "[Subject] + [Action] + [Location/context] + [Composition] + [Style]";
+/** The expanded cinematic/photoreal formula for NB2 start frames. */
+export declare const CINEMATIC_IMAGE_FORMULA = "Film still from [DIRECTOR] [GENRE]. Shot on [CAMERA] with [LENS]. [SUBJECT and action]. [3-5 specific visual details]. [LIGHTING \u2014 direction + quality]. [COLOR PALETTE]. [FILM STOCK or sensor language]. [1-2 word emotional tone].";
+//# sourceMappingURL=model-facts.d.ts.map

package/dist/prompts/model-facts.js

@@ -0,0 +1,64 @@
+// Per-model prompting facts — reference/ingredient limits and the prompt
+// formula, as KNOWLEDGE (for skills + lead-magnet + desktop tooltips). The
+// RUNTIME source of truth for limits is slate/src/shared/pricing.ts
+// (MODEL_REGISTRY.maxRefImages / maxIngredientImages); these mirror it for
+// documentation. Code-verified 2026-06-25.
+export const MODEL_FACTS = [
+    {
+        id: 'nano-banana-2',
+        label: 'Nano Banana 2 (Gemini 3 Image)',
+        kind: 'image',
+        maxRefImages: 14, // 10 object-fidelity + 4 character-consistency; categories don't trade.
+        maxIngredients: null,
+        notes: 'Default image model. 14 refs hard cap (10 object + 4 character). Brief it like a creative director, not tag soup. No negativePrompt field — use positive reframing. Best image start-frame for legible text. Knowledge cutoff Jan 2025.',
+    },
+    {
+        id: 'flux-2-max',
+        label: 'FLUX.2 Max',
+        kind: 'image',
+        maxRefImages: 4,
+        maxIngredients: null,
+        notes: 'Photoreal, less censored, up to ~4MP. Auto-routes to its edit endpoint when references are present. Lower ref cap than NB2.',
+    },
+    {
+        id: 'seedream-5-lite',
+        label: 'Seedream 5 Lite',
+        kind: 'image',
+        maxRefImages: 10,
+        maxIngredients: null,
+        notes: 'Cheapest image model (~flat price). Less censored. Routes to its edit endpoint with references.',
+    },
+    {
+        id: 'seedance-2',
+        label: 'Seedance 2.0',
+        kind: 'video',
+        maxRefImages: null,
+        maxIngredients: 9, // ingredient images per video gen
+        notes: 'Hero video model — physics, effects, scale. Up to 9 ingredient images. Strong I2V / own-footage restyle.',
+    },
+    {
+        id: 'kling-v3',
+        label: 'Kling 3.0',
+        kind: 'video',
+        maxRefImages: null,
+        maxIngredients: 4,
+        notes: 'Budget-cinematic video — acting, dialogue, lip-sync. Strong start-frame adherence.',
+    },
+    {
+        id: 'veo-3.1',
+        label: 'Veo 3.1',
+        kind: 'video',
+        maxRefImages: null,
+        maxIngredients: 3,
+        notes: 'Native audio. Default audio-on. Strong prompt adherence; treats the prompt as scene direction.',
+    },
+];
+const FACT_BY_ID = new Map(MODEL_FACTS.map((m) => [m.id, m]));
+export function getModelFact(id) {
+    return FACT_BY_ID.get(id);
+}
+/** The official NB2 / general image prompt formula (subject-first). */
+export const IMAGE_PROMPT_FORMULA = '[Subject] + [Action] + [Location/context] + [Composition] + [Style]';
+/** The expanded cinematic/photoreal formula for NB2 start frames. */
+export const CINEMATIC_IMAGE_FORMULA = 'Film still from [DIRECTOR] [GENRE]. Shot on [CAMERA] with [LENS]. [SUBJECT and action]. [3-5 specific visual details]. [LIGHTING — direction + quality]. [COLOR PALETTE]. [FILM STOCK or sensor language]. [1-2 word emotional tone].';
+//# sourceMappingURL=model-facts.js.map

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

@@ -0,0 +1,34 @@
+export type SourceGrade = 'Eric-test' | 'community' | 'code-verified' | 'creator-demo';
+export interface ReferenceRule {
+    id: string;
+    title: string;
+    rule: string;
+    why: string;
+    grade: SourceGrade;
+}
+/**
+ * The 10 verified reference rules. These are the WHY; the fragments below
+ * are the reusable text the templates compose.
+ */
+export declare const REFERENCE_RULES: ReferenceRule[];
+/** Flat, even, shadowless identity lighting on a plain neutral background. */
+export declare const IDENTITY_LIGHTING = "flat, even, shadowless lighting";
+export declare const IDENTITY_BACKGROUND = "a plain neutral-grey background";
+export declare const IDENTITY_LIGHTING_CLAUSE = "Render on a plain neutral-grey background with flat, even, shadowless lighting so the sheet captures the character's identity, not scene lighting.";
+/** Inherit the source's artistic medium unless told otherwise. */
+export declare const INHERIT_SOURCE_STYLE = "Preserve the artistic medium and visual style of the reference image (photograph, anime, illustration, 3D render, painterly, etc.).";
+/** Environment plate guidance: one clean, naturally-lit establishing image. */
+export declare const ENVIRONMENT_NATURAL_LIGHT = "natural, even ambient lighting that reads as the location's real light, not a studio setup";
+/** One-line summary used as a header in skills + the lead magnet. */
+export declare const REFERENCE_RULES_HEADLINE = "Identity = a few flat-lit neutral angles; one reference per role, labeled; 2-4 refs not 12; describe environments instead of feeding a grid.";
+/**
+ * Canonical markdown block — the SOURCE OF TRUTH the skill markdown and the
+ * lead-magnet are reconciled AGAINST. NOTE: nothing imports this yet — the
+ * skills hand-author their own reference-rule prose and embed-skills.mjs ships
+ * the raw .md as-is, so a change here must be propagated to the per-model skill
+ * blocks + lead-magnet by hand until the skill-embed wiring lands (see
+ * 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.";
+//# sourceMappingURL=reference-rules.d.ts.map

package/dist/prompts/reference-rules.js

@@ -0,0 +1,120 @@
+// Reference best-practices — the canonical "how to use reference images"
+// knowledge for every Slates surface (desktop templates, MCP skills, the
+// lead-magnet .skill). Authored ONCE here; consumers derive from it.
+//
+// Source grades: [Eric-test] = Eric's own hands-on result (doctrine-grade);
+// [community] = multi-guide consensus; [code-verified] = verified against
+// the slate codebase; [creator-demo] = single creator demonstration.
+/**
+ * The 10 verified reference rules. These are the WHY; the fragments below
+ * are the reusable text the templates compose.
+ */
+export const REFERENCE_RULES = [
+    {
+        id: 'two-to-four-refs',
+        title: '2-4 strong references beat both extremes',
+        rule: 'Use 2-4 strong, focused references — not 1 (warps), not 12 (averages worse). Start with 2-3.',
+        why: 'One reference warps toward itself; a dozen averages everyone into mush. One tester cut drift ~60% going 6→2.',
+        grade: 'community',
+    },
+    {
+        id: 'one-ref-per-role',
+        title: 'One reference per ROLE, labeled in the prompt',
+        rule: 'Use one reference per role — identity, style-grade, environment — and label each role explicitly in the prompt text. The model does not infer roles from order.',
+        why: 'Same-role competitors drift; two "identity" refs of different people blend into a third face.',
+        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.',
+        grade: 'Eric-test',
+    },
+    {
+        id: 'flat-light-identity',
+        title: 'Flat-light identity refs',
+        rule: 'Prep identity refs with flat, even, shadowless lighting on a plain neutral background. Studio-lit or scene-lit sheets bleed their lighting into every generation.',
+        why: "Eric's Norse-woman test: a studio-lit sheet produced a subject that looked green-screen-pasted in front of mountains. Reference prep beats prompting here.",
+        grade: 'Eric-test',
+    },
+    {
+        id: 'describe-environment',
+        title: 'Environment: describe it, don\'t feed a grid',
+        rule: 'Default to describing the environment in words. Reserve an environment reference for a mandatory exact-match location, and when you do, use ONE clean establishing image — never a multi-panel grid fed whole.',
+        why: "Eric's test: character sheet + 3x3 mountain grid → pasted-in mess; the same character + a described background → believable scene with natural lighting the model invented to fit.",
+        grade: 'Eric-test',
+    },
+    {
+        id: 'grids-explore-not-input',
+        title: 'Grids: generation/exploration = fine; INPUT reference = bad',
+        rule: 'Use grids to EXPLORE compositions (cheap multi-angle generation), then pick a cell. Do NOT feed a grid back in as a reference image — cells share a split detail budget and generate jointly, so flaws propagate.',
+        why: 'A picked cell re-generated with a "preserve the exact composition" prompt keeps its flaws faithfully (that is the budget path, kept on purpose). A loose prompt can fix anatomy but drifts off the picked composition.',
+        grade: 'code-verified',
+    },
+    {
+        id: 'reuse-refs',
+        title: 'Reuse the same refs across all shots',
+        rule: 'Lock a reference set and reuse it across every shot in a sequence. Swapping refs mid-sequence causes drift.',
+        why: 'The model adapts environment refs to each prompt rather than copying them, so swapping compounds inconsistency shot to shot.',
+        grade: 'community',
+    },
+    {
+        id: 'text-as-start-frame',
+        title: 'Legible in-shot text → image start-frame, never trust text-to-video',
+        rule: 'When a shot needs legible on-screen text, bake it into a still start frame (NB2) and animate from that. Do not expect a text-to-video model to render clean text.',
+        why: 'Video models smear text; an image model holds it, and the video inherits the locked frame.',
+        grade: 'community',
+    },
+    {
+        id: 'i2v-own-footage',
+        title: 'I2V / own-footage superpower — describe only what changes',
+        rule: 'Restyle your own clip while keeping the performance; "video one" delayed-VFX; marker-object insertion; video-as-ref for a series. In all cases describe ONLY what changes, not the whole scene.',
+        why: 'The source clip already carries motion, timing, and performance; re-describing them fights the model. Narrate the delta.',
+        grade: 'creator-demo',
+    },
+    {
+        id: 'style-transform-nl',
+        title: 'Style transform by natural language',
+        rule: 'Default: keep the source\'s artistic medium/style. To change it, add a plain-text instruction ("anime → real person") — no preset pickers.',
+        why: 'Paste/natural-language over preset menus is the product philosophy; the medium is inherited unless the user explicitly asks to transform it.',
+        grade: 'Eric-test',
+    },
+];
+// ── Reusable text fragments (the template-assembly building blocks) ──
+// These are the exact strings the desktop prompt templates, MCP skills,
+// and lead-magnet compose. Change a rule HERE and every consumer follows.
+/** Flat, even, shadowless identity lighting on a plain neutral background. */
+export const IDENTITY_LIGHTING = 'flat, even, shadowless lighting';
+export const IDENTITY_BACKGROUND = 'a plain neutral-grey background';
+export const IDENTITY_LIGHTING_CLAUSE = `Render on ${IDENTITY_BACKGROUND} with ${IDENTITY_LIGHTING} so the sheet captures the character's identity, not scene lighting.`;
+/** Inherit the source's artistic medium unless told otherwise. */
+export const INHERIT_SOURCE_STYLE = 'Preserve the artistic medium and visual style of the reference image (photograph, anime, illustration, 3D render, painterly, etc.).';
+/** Environment plate guidance: one clean, naturally-lit establishing image. */
+export const ENVIRONMENT_NATURAL_LIGHT = 'natural, even ambient lighting that reads as the location\'s real light, not a studio setup';
+/** One-line summary used as a header in skills + the lead magnet. */
+export const REFERENCE_RULES_HEADLINE = 'Identity = a few flat-lit neutral angles; one reference per role, labeled; 2-4 refs not 12; describe environments instead of feeding a grid.';
+/**
+ * Canonical markdown block — the SOURCE OF TRUTH the skill markdown and the
+ * lead-magnet are reconciled AGAINST. NOTE: nothing imports this yet — the
+ * skills hand-author their own reference-rule prose and embed-skills.mjs ships
+ * the raw .md as-is, so a change here must be propagated to the per-model skill
+ * blocks + lead-magnet by hand until the skill-embed wiring lands (see
+ * 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 const REFERENCE_RULES_TEXT = `## Reference rules (how to use reference images)
+
+${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.
+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.
+7. **Reuse the same refs across all shots.** Lock a set and reuse it; swapping refs mid-sequence causes drift.
+8. **Legible in-shot text → bake it into an image start frame, never trust text-to-video.** Animate from the locked frame.
+9. **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.
+10. **Style transform by natural language.** Default keeps the source's art style; an optional plain-text instruction transforms it ("anime → real person"). No preset pickers.`;
+//# sourceMappingURL=reference-rules.js.map

package/dist/prompts/style-library.d.ts

@@ -0,0 +1,31 @@
+export interface StyleEntry {
+    id: string;
+    label: string;
+    /** What the model should produce when this style is requested. */
+    description: string;
+    /** The artistic medium this style implies. */
+    medium: string;
+}
+/**
+ * Optional named styles for when a user DOES want to name one. The default is
+ * always `inherit` — keep the reference's own medium. These are descriptions,
+ * not preset buttons; they exist so an agent can translate a user's plain
+ * request ("make it anime") into a clean instruction.
+ */
+export declare const STYLE_LIBRARY: StyleEntry[];
+export declare const DEFAULT_STYLE_ID = "inherit";
+export declare function getStyle(id: string | null | undefined): StyleEntry;
+/**
+ * Render the optional style instruction that templates append verbatim.
+ * - No user style → empty string (inherit the source medium, the default).
+ * - A free-text instruction ("make her a real person") → appended as a clean
+ *   transform clause.
+ * - A known style id → the library description.
+ *
+ * Tolerant of the legacy desktop values ('photorealistic' / 'match-reference'):
+ * 'match-reference' coalesces to inherit (empty); 'photorealistic' maps to the
+ * photoreal description. So old character/environment rows stay valid with no
+ * data migration.
+ */
+export declare function renderStyleInstruction(userStyle?: string | null): string;
+//# sourceMappingURL=style-library.d.ts.map

package/dist/prompts/style-library.js

@@ -0,0 +1,84 @@
+// Style library — the canonical "style name → description / medium" map and
+// the single rule that governs how Slates handles style: inherit the source's
+// artistic medium by default, transform only on an explicit natural-language
+// instruction. No preset pickers (PRODUCT_PHILOSOPHY: paste/NL over menus).
+import { INHERIT_SOURCE_STYLE } from './reference-rules.js';
+/**
+ * Optional named styles for when a user DOES want to name one. The default is
+ * always `inherit` — keep the reference's own medium. These are descriptions,
+ * not preset buttons; they exist so an agent can translate a user's plain
+ * request ("make it anime") into a clean instruction.
+ */
+export const STYLE_LIBRARY = [
+    {
+        id: 'inherit',
+        label: 'Match Source',
+        description: INHERIT_SOURCE_STYLE,
+        medium: 'whatever the reference already is',
+    },
+    {
+        id: 'photoreal',
+        label: 'Photoreal',
+        description: 'A real photograph of a real person/place. Natural skin texture and imperfection, motivated lighting, lens and film-stock language — never the word "photorealistic" as a token.',
+        medium: 'live-action photography',
+    },
+    {
+        id: 'anime',
+        label: 'Anime',
+        description: 'Hand-drawn 2D anime/cel style: clean line art, flat-shaded color, expressive eyes.',
+        medium: '2D animation',
+    },
+    {
+        id: 'painterly',
+        label: 'Painterly',
+        description: 'Visible brushwork, painted edges, concept-art rendering rather than photographic capture.',
+        medium: 'digital/traditional painting',
+    },
+    {
+        id: '3d-render',
+        label: '3D Render',
+        description: 'Stylized 3D CGI render: sculpted forms, subsurface materials, soft GI lighting (Pixar/Unreal lineage).',
+        medium: '3D render',
+    },
+    {
+        id: 'comic',
+        label: 'Comic',
+        description: 'Inked comic-book style: bold outlines, halftone or flat color, graphic shadows.',
+        medium: 'comic illustration',
+    },
+];
+export const DEFAULT_STYLE_ID = 'inherit';
+const STYLE_BY_ID = new Map(STYLE_LIBRARY.map((s) => [s.id, s]));
+export function getStyle(id) {
+    return (id && STYLE_BY_ID.get(id)) || STYLE_BY_ID.get(DEFAULT_STYLE_ID);
+}
+/**
+ * Render the optional style instruction that templates append verbatim.
+ * - No user style → empty string (inherit the source medium, the default).
+ * - A free-text instruction ("make her a real person") → appended as a clean
+ *   transform clause.
+ * - A known style id → the library description.
+ *
+ * Tolerant of the legacy desktop values ('photorealistic' / 'match-reference'):
+ * 'match-reference' coalesces to inherit (empty); 'photorealistic' maps to the
+ * photoreal description. So old character/environment rows stay valid with no
+ * data migration.
+ */
+export function renderStyleInstruction(userStyle) {
+    const raw = (userStyle ?? '').trim();
+    if (!raw)
+        return '';
+    const lower = raw.toLowerCase();
+    // Legacy / default values are no-ops — keep the source medium.
+    if (lower === 'match-reference' || lower === 'inherit' || lower === 'match source')
+        return '';
+    if (lower === 'photorealistic' || lower === 'photoreal') {
+        return ` Style: ${getStyle('photoreal').description}`;
+    }
+    const known = STYLE_BY_ID.get(lower);
+    if (known)
+        return ` Style: ${known.description}`;
+    // Free-text natural-language transform — append verbatim.
+    return ` Style change: ${raw}.`;
+}
+//# sourceMappingURL=style-library.js.map