@slatesvideo/shared 0.5.2 → 0.5.4

package/README.md

@@ -3,3 +3,21 @@
 Internal shared layer for the [Slates](https://slates.video) MCP server and CLI: the auth/connection-file reader, the cloud and desktop HTTP clients, and the single operations array both surfaces register. You almost certainly want [@slatesvideo/mcp-server](https://www.npmjs.com/package/@slatesvideo/mcp-server) (MCP clients like Claude Desktop and Cursor) or [@slatesvideo/cli](https://www.npmjs.com/package/@slatesvideo/cli) (the `slates` command) instead — this package is published only as their dependency.
 
 Source: [github.com/EricDisero/slates-mcp](https://github.com/EricDisero/slates-mcp)
+
+## Prompt partials — how shared prompting prose stays de-forked
+
+Prompting doctrine that applies to more than one model lives **once**, in `skills/_partials/<name>.md`. Every surface that needs it derives:
+
+- **Skill markdown** (`skills/*.md`) carries a marker pair; `scripts/sync-partials.mjs` writes the resolved text between them and commits it, so each de-fork is visible in review and `install-skills` can keep writing the files verbatim to disk.
+
+  ```markdown
+  <!-- @inject:reference-rules-core -->
+  …generated; do not edit between the markers…
+  <!-- @end:reference-rules-core -->
+  ```
+
+- **TypeScript** reads the same text from the generated `PARTIALS` record (`src/prompts/partials.generated.ts`) — that is how `REFERENCE_RULES_TEXT` and the doctrine-bearing cards in `prompting-tips.ts` are built.
+
+`npm run build` runs `sync-partials.mjs --check`, which fails with a diff if anything inside a marker block was hand-edited, if a skill references a partial that doesn't exist, if markers are unbalanced, or if a partial is referenced by nothing. Run `npm run sync-partials` to apply changes after editing a partial.
+
+**To change shared prompting doctrine: edit the partial.** Never edit between markers, never edit `partials.generated.ts`, and never hand-copy a shared rule into a new skill — a copy is a fork with a delay fuse. Per-model levers (a vendor's own official consistency mechanism, its caps and transport quirks) stay hand-authored, below the injected block, under a `### For <model> specifically` heading.

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export { SKILLS } from './skills/content.js';
 export * as operations from './operations/index.js';
 export { ALL_OPERATIONS, VIDEO_MODELS, defaultContext, type Operation, type OperationContext, type OperationResult } from './operations/index.js';
 export { MODEL_FACTS, getModelFact, type ModelFact } from './prompts/model-facts.js';
+export { PROMPTING_TIPS, getPromptingTips, type PromptingTipsEntry, type PromptingTipCard, type PromptingTipsKey } from './prompts/prompting-tips.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,4 +8,7 @@ export { ALL_OPERATIONS, VIDEO_MODELS, defaultContext } from './operations/index
 // prompt derives its MODEL ROUTING doctrine from (kind: image vs video,
 // default/premium/niche notes). Edit model-facts.ts, never prose copies.
 export { MODEL_FACTS, getModelFact } from './prompts/model-facts.js';
+// Per-model prompting tips — the SSOT for the desktop "See prompting tips"
+// modals. The desktop renders these; it never hand-writes tips content.
+export { PROMPTING_TIPS, getPromptingTips } from './prompts/prompting-tips.js';
 //# sourceMappingURL=index.js.map

package/dist/operations/index.d.ts

@@ -112,6 +112,7 @@ export declare const generateCharacterSheets: Operation<{
     baseAssetId: string;
     sheetTypes?: ('turnaround' | 'expression')[];
     userNotes?: string;
+    model?: 'nano-banana-2' | 'nano-banana-2-lite' | 'nano-banana-pro' | 'gpt-image-2';
 }>;
 export declare const generateEnvironmentPlate: Operation<{
     environmentId: string;
@@ -297,6 +298,30 @@ export declare const reorderClips: Operation<{
 export declare const removeClip: Operation<{
     clipId: string;
 }>;
+export declare const addTimelineTrack: Operation<{
+    projectId: string;
+    type?: 'video' | 'audio';
+    name?: string;
+}>;
+export declare const updateTimelineTrack: Operation<{
+    projectId: string;
+    trackId: string;
+    name?: string;
+    muted?: boolean;
+    locked?: boolean;
+    volume?: number;
+}>;
+export declare const removeTimelineTrack: Operation<{
+    projectId: string;
+    trackId: string;
+}>;
+export declare const updateTimelineSettings: Operation<{
+    projectId: string;
+    width?: number;
+    height?: number;
+    frameRate?: 24 | 30 | 60;
+    masterVolume?: number;
+}>;
 export declare const exportVideo: Operation<{
     projectId?: string;
     timelineId?: string;

package/dist/operations/index.js

@@ -580,7 +580,7 @@ export const createEnvironment = {
 };
 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.",
+    description: "Generate a character's identity reference sheet from a base portrait asset and bind it to the character. THE real character-building workflow — call right after slates_create_character. ONE sheet per character by default: a dominant three-quarter chest-up portrait (the sole face authority) plus full-body front and back panels on a deep neutral-grey plate — it binds to the turnaround slot and the expression slot stays null. That is deliberate: every bound sheet costs a reference slot on EVERY downstream shot, so one sheet per character doubles the cast you can stage against real caps (Kling 3.0 takes 4 ingredients, NB2 4 character slots, Seedance 9). Pass sheetTypes:['expression'] only when a character genuinely needs a separate expression range. baseAssetId is the source portrait (a project asset). Afterward, carry the character into a scene by passing its bound sheet asset id as characterAssetIds to slates_generate_video (or referenceAssetIds to slates_generate_image). Read slates-character-turnaround before calling. Default nano-banana-2 @ 2K — quote the price from slates_estimate_generation_cost, never from memory.",
     input: z.object({
         characterId: z.string().uuid(),
         projectId: z.string().uuid(),
@@ -588,8 +588,12 @@ export const generateCharacterSheets = {
         sheetTypes: z
             .array(z.enum(['turnaround', 'expression']))
             .optional()
-            .describe('Which sheets to generate. Default both.'),
+            .describe("Which sheets to generate. Default ['turnaround'] — the single identity sheet. Add 'expression' only when the character needs a dedicated expression range; it costs a second reference slot on every downstream generation."),
         userNotes: z.string().optional().describe('Extra instruction, e.g. "use the woman on the left".'),
+        model: z
+            .enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2'])
+            .optional()
+            .describe('Image model for the sheet. Omit for the default (nano-banana-2). Exists so the layout-vs-face tradeoff can be tested with comparison gens — do not switch without a receipt.'),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/characters/generate-sheets', {
@@ -598,6 +602,7 @@ export const generateCharacterSheets = {
             baseAssetIds: [input.baseAssetId],
             sheetTypes: input.sheetTypes,
             userNotes: input.userNotes,
+            model: input.model,
         }));
     },
 };
@@ -2260,11 +2265,11 @@ export const getTimeline = {
 };
 export const addClipToTimeline = {
     id: 'slates_add_clip_to_timeline',
-    description: "Append a video asset from the project to the project's timeline (or place it at an explicit startFrame). Defaults match the desktop UI: clip goes to the end of the first video track, full source duration, and an empty timeline auto-adopts the clip's resolution and frame rate. Optionally trim with sourceInFrame/sourceOutFrame (frames at the SOURCE fps). Use slates_get_timeline first to see current clips and pick positions. Only video assets are accepted.",
+    description: "Append a video or audio asset from the project to the project's timeline (or place it at an explicit startFrame). Defaults match the desktop UI: video clips go to the end of the first video track; audio clips (music, voiceover, AI audio) go after the last clip on the first AUDIO track and are mixed under the video on export. An empty timeline auto-adopts the first video clip's resolution and frame rate; later higher-resolution clips raise the canvas. Overlapping video clips resolve top-track-wins. Optionally trim with sourceInFrame/sourceOutFrame (frames at the SOURCE fps). Use slates_get_timeline first to see current clips and pick positions.",
     input: z.object({
         projectId: z.string().uuid(),
-        assetId: z.string().uuid().describe('Video asset already in the project.'),
-        trackId: z.string().uuid().optional().describe('Target track. Default: the first video track.'),
+        assetId: z.string().uuid().describe('Video or audio asset already in the project.'),
+        trackId: z.string().uuid().optional().describe('Target track (type must match the asset: video asset → video track, audio asset → audio track). Default: the first track of the matching type.'),
         startFrame: z.number().int().min(0).optional().describe('Timeline frame to place the clip at. Default: append after the last clip.'),
         sourceInFrame: z.number().int().min(0).optional(),
         sourceOutFrame: z.number().int().min(1).optional(),
@@ -2315,6 +2320,66 @@ export const removeClip = {
         return ok(await desktop.post('/agent/timeline/remove-clip', input));
     },
 };
+export const addTimelineTrack = {
+    id: 'slates_add_timeline_track',
+    description: "Add a track to the project's timeline (default: an audio track, for layering voiceover + music + AI audio). The new track is appended below existing tracks. Returns the new track and the full timeline.",
+    input: z.object({
+        projectId: z.string().uuid(),
+        type: z.enum(['video', 'audio']).optional().describe('Default: audio.'),
+        name: z.string().optional().describe("Default: 'Audio N' / 'Video N'."),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('timeline-tracks', 'timeline tracks + audio mixing');
+        return ok(await desktop.post('/agent/timeline/add-track', input));
+    },
+};
+export const updateTimelineTrack = {
+    id: 'slates_update_timeline_track',
+    description: 'Update a timeline track: rename, mute/unmute, lock/unlock, or set its volume fader (linear gain, -∞ to +12 dB). Track volume applies to both preview and MP4 export — audio-track clips are mixed at this gain; a muted video track still shows video but its embedded audio is silenced.',
+    input: z.object({
+        projectId: z.string().uuid(),
+        trackId: z.string().uuid(),
+        name: z.string().optional(),
+        muted: z.boolean().optional(),
+        locked: z.boolean().optional(),
+        volume: z.number().min(0).max(4).optional().describe('Track fader as LINEAR gain: 0 = -∞ (silent), 1 = 0 dB (unity), ~3.98 = +12 dB (max boost).'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('timeline-tracks', 'timeline tracks + audio mixing');
+        return ok(await desktop.post('/agent/timeline/update-track', input));
+    },
+};
+export const removeTimelineTrack = {
+    id: 'slates_remove_timeline_track',
+    description: 'Remove an EMPTY timeline track (fails if it still has clips, or if it is the last track of its type).',
+    input: z.object({
+        projectId: z.string().uuid(),
+        trackId: z.string().uuid(),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('timeline-tracks', 'timeline tracks + audio mixing');
+        return ok(await desktop.post('/agent/timeline/remove-track', input));
+    },
+};
+export const updateTimelineSettings = {
+    id: 'slates_update_timeline_settings',
+    description: "Update the project timeline's output settings: resolution, frame rate (24/30/60 — all clips are conformed to it on export), and masterVolume, the output fader (linear gain, -∞ to +12 dB) applied to the final mix in both preview and MP4 export (use it to prevent clipping when stacking loud tracks). Note these are normally auto-managed: the first video clip sets fps + resolution, and higher-res clips raise the canvas. Changing frameRate after clips are placed retimes them — avoid unless the timeline is empty.",
+    input: z.object({
+        projectId: z.string().uuid(),
+        width: z.number().int().min(16).optional(),
+        height: z.number().int().min(16).optional(),
+        frameRate: z.union([z.literal(24), z.literal(30), z.literal(60)]).optional(),
+        masterVolume: z.number().min(0).max(4).optional().describe('Output fader as LINEAR gain: 0 = -∞ (silent), 1 = 0 dB (unity), ~3.98 = +12 dB (max boost).'),
+    }),
+    async run(input, ctx) {
+        const desktop = ctx.desktop();
+        await desktop.requireCapability('timeline-tracks', 'timeline tracks + audio mixing');
+        return ok(await desktop.post('/agent/timeline/update-settings', input));
+    },
+};
 // ── Export ──────────────────────────────────────────────────────
 const ABSOLUTE_PATH_RE = /^([A-Za-z]:[\\/]|\/)/;
 export const exportVideo = {
@@ -2773,6 +2838,10 @@ export const ALL_OPERATIONS = [
     addClipToTimeline,
     reorderClips,
     removeClip,
+    addTimelineTrack,
+    updateTimelineTrack,
+    removeTimelineTrack,
+    updateTimelineSettings,
     exportVideo,
     exportTimelineXml,
     revealFile,

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

@@ -1,24 +1,36 @@
-/** 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.
+ * The identity sheet's panels. The portrait is FIRST and DOMINANT — every
+ * detail the downstream model will ever know about the face comes from those
+ * pixels, so it gets the resolution. The body panels exist for build,
+ * proportion, wardrobe and hair, not for the face.
+ *
+ * The back panel KEEPS its head on purpose: it has no face to compete with the
+ * portrait, and it is the only panel where hair fall reads.
+ */
+export declare const CHARACTER_SHEET_PANELS_DESC: string;
+/** Panel identifiers, in sheet order. */
+export declare const BODY_POSE_LABELS: readonly ["portrait", "front", "back"];
+/**
+ * Expression-sheet close-ups — LEGACY. Kept so characters built before the
+ * 2026-07-21 single-sheet architecture keep regenerating correctly, and so the
+ * expression slot remains usable for a character that genuinely needs a
+ * dedicated expression range.
  */
 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.
+ * The character identity sheet — one asset, three panels, bound to the
+ * turnaround slot. Named `buildCharacterTurnaroundPrompt` for continuity with
+ * every existing caller and with the slot it binds to.
+ *
  * @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.
+ * Expression sheet — LEGACY close-up face reference. Since 2026-07-21 the
+ * identity sheet above is the default and this slot is normally left null.
+ * Generate one only when a character needs an explicit expression range;
+ * attaching it costs a second reference slot on every generation.
  */
 export declare function buildExpressionSheetPrompt(userStyle?: string | null): string;
 //# sourceMappingURL=character-sheet.d.ts.map

package/dist/prompts/character-sheet.js

@@ -1,24 +1,70 @@
-// 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.)
+// Canonical character-sheet prompt content.
 //
-// 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';
+// ARCHITECTURE (locked by Eric 2026-07-21): ONE identity sheet per character.
+// A dominant off-frontal chest-up portrait carries the face; two full-body
+// panels (front + back) carry build, wardrobe and hair. The sheet binds to the
+// character's TURNAROUND slot and the expression slot is left null.
+//
+// Why one sheet and not two — three arguments, none of which depend on a
+// comparison generation:
+//   1. Reference-cap economics. Every `@character` mention pushes BOTH bound
+//      sheets into one reference group, so a two-sheet character costs TWO
+//      reference slots on every generation. Against real caps that is brutal:
+//      Kling 3.0 takes 4 ingredients (2 characters, zero room for an
+//      environment), NB2 has 4 character slots, Seedance 9. One sheet each
+//      DOUBLES the cast you can stage on every model we route to.
+//   2. Competing face renderings drop 6 → 2. The old pair sent three large
+//      portraits plus three postage-stamp faces (turnaround front + both
+//      profiles). The model cannot tell which rendering is authoritative and
+//      averages them; ByteDance documents the same root cause for its
+//      duplicate-character failure (ModelArk :1959) and prescribes fewer
+//      competing views. Both profile panels disappear with the shape change.
+//   3. One generation instead of two per character — half the sheet spend, one
+//      asset to inspect and bind.
+//
+// KNOWN COST, accepted for v1: a neutral chest-up portrait carries no dental
+// information, so a character who smiles in a shot gets invented teeth. The
+// 2026-06-26 doctrine already holds that the user's prompt owns expression.
+// Revisit only if a receipt shows invented teeth.
+//
+// DEFERRED, not rejected: cropping the face off the front body panel (the
+// "ghost mannequin" treatment). Adopting this layout takes competing faces
+// 6 → 2 for free; the crop buys only 2 → 1, and it is contradicted by the only
+// visible output in the source corpus. Flipping it later is a one-line change
+// here — no migration, no data touched.
+//
+// BACK-COMPAT IS MANDATORY: ~20 live users have characters bound to BOTH
+// slots. `buildExpressionSheetPrompt` stays exported and the expression slot
+// stays readable; `mentions.ts` only pushes non-null paths, so old two-sheet
+// characters and new one-sheet characters both work unchanged.
+//
+// SOURCE OF TRUTH. The desktop imports these builders through
+// `slate/src/shared/prompts/character-sheet.ts` (a thin re-export since 1.2.1)
+// — there is no desktop prompt mirror to update. Map:
+// second-brain business/projects/slates/product/prompting-ssot.md
+import { IDENTITY_CRAFT_CLAUSE, 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.
+ * The identity sheet's panels. The portrait is FIRST and DOMINANT — every
+ * detail the downstream model will ever know about the face comes from those
+ * pixels, so it gets the resolution. The body panels exist for build,
+ * proportion, wardrobe and hair, not for the face.
+ *
+ * The back panel KEEPS its head on purpose: it has no face to compete with the
+ * portrait, and it is the only panel where hair fall reads.
+ */
+export const CHARACTER_SHEET_PANELS_DESC = 'a large chest-up portrait on the left at a three-quarter angle (never dead-on), ' +
+    'a full-body front view in a relaxed A-pose in the centre, ' +
+    'and a full-body back view on the right';
+/** Panel identifiers, in sheet order. */
+export const BODY_POSE_LABELS = ['portrait', 'front', 'back'];
+/**
+ * Expression-sheet close-ups — LEGACY. Kept so characters built before the
+ * 2026-07-21 single-sheet architecture keep regenerating correctly, and so the
+ * expression slot remains usable for a character that genuinely needs a
+ * dedicated expression range.
  */
 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
@@ -27,27 +73,31 @@ function styleDirective(userStyle) {
     return renderStyleInstruction(userStyle).trim() || INHERIT_SOURCE_STYLE;
 }
 /**
- * Body turnaround sheet — the identity reference.
+ * The character identity sheet — one asset, three panels, bound to the
+ * turnaround slot. Named `buildCharacterTurnaroundPrompt` for continuity with
+ * every existing caller and with the slot it binds to.
+ *
  * @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.`);
+    return (`A single character identity reference sheet of one character, three panels side by side on one plate: ` +
+        `${CHARACTER_SHEET_PANELS_DESC}. ` +
+        `The portrait is the largest panel and occupies roughly a quarter to a third of the sheet — it is the sole authority for the face, so render it at maximum facial detail. ` +
+        `Neutral expression and identical appearance, wardrobe and hair across all three panels. ` +
+        `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} ${IDENTITY_CRAFT_CLAUSE} ` +
+        `For quadruped or non-bipedal characters, replace the A-pose with a natural standing stance and keep the same three-panel layout. ` +
+        `No text, no labels, no captions, no panel borders.`);
 }
 /**
- * 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.
+ * Expression sheet — LEGACY close-up face reference. Since 2026-07-21 the
+ * identity sheet above is the default and this slot is normally left null.
+ * Generate one only when a character needs an explicit expression range;
+ * attaching it costs a second reference slot on every generation.
  */
 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. ` +
+        `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} ${IDENTITY_CRAFT_CLAUSE} Same framing for each. ` +
         `No text, no labels, no captions.`);
 }
 //# sourceMappingURL=character-sheet.js.map

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

@@ -5,5 +5,13 @@
  */
 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.";
+export declare const ENVIRONMENT_DESCRIBE_FIRST: string;
+/**
+ * The continuity test for a location that must hold across shots: generate a
+ * SECOND frame from the reverse angle and approve the plate only if the anchor
+ * object, the openings, the light side, the materials and the palette all still
+ * match. A plate that fails this will drift the moment the camera turns — and a
+ * broken plate gives every later character failure a second plausible cause.
+ */
+export declare const ENVIRONMENT_REVERSE_ANGLE_TEST = "Reverse-angle check: generate one frame from the opposite side of the space and confirm the anchor object, openings, light direction, materials and colour palette all still match. If they do not, the plate is not locked \u2014 fix the plate before staging anything in it.";
 //# sourceMappingURL=environment-sheet.d.ts.map

package/dist/prompts/environment-sheet.js

@@ -16,12 +16,26 @@ function styleDirective(userStyle) {
  * @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. ` +
+    return (`A single clean establishing shot of this empty location, framed at a three-quarter angle — never a dead-on frontal view — so two walls or planes are visible and the floor reads as usable staging space. ` +
+        `Capture the space: its architecture or geography, materials, and depth. ` +
+        `Include a clearly readable ANCHOR OBJECT with a definite position in the room — a sofa, a doorway, a counter, a signpost — so later shots can be blocked against it. ` +
         `The location is empty and unpopulated, ready for scene staging. ` +
-        `${styleDirective(userStyle)} Use ${ENVIRONMENT_NATURAL_LIGHT}. ` +
+        `${styleDirective(userStyle)} Use ${ENVIRONMENT_NATURAL_LIGHT}, motivated by ONE dominant source with shadows falling consistently away from it — soft and diffused for interiors, no hard visible light rays. ` +
+        `Add gentle atmospheric haze with distance so near and far planes separate in depth rather than reading at the same sharpness. ` +
         `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.';
+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. ' +
+    'When you do: frame it three-quarter, never dead-on (a frontal facade turns the location into a backdrop characters stand in FRONT of; a three-quarter exposes side geometry and usable floor), ' +
+    'name an anchor object so blocking can be stated as "between the sofa\'s hall-side arm and the window" instead of "on the left" — one is testable after a camera turn, the other drifts, ' +
+    'give it one motivated light source with shadows falling away from it, and ask for atmospheric haze so depth separates.';
+/**
+ * The continuity test for a location that must hold across shots: generate a
+ * SECOND frame from the reverse angle and approve the plate only if the anchor
+ * object, the openings, the light side, the materials and the palette all still
+ * match. A plate that fails this will drift the moment the camera turns — and a
+ * broken plate gives every later character failure a second plausible cause.
+ */
+export const ENVIRONMENT_REVERSE_ANGLE_TEST = 'Reverse-angle check: generate one frame from the opposite side of the space and confirm the anchor object, openings, light direction, materials and colour palette all still match. If they do not, the plate is not locked — fix the plate before staging anything in it.';
 //# sourceMappingURL=environment-sheet.js.map

package/dist/prompts/index.d.ts

@@ -5,4 +5,5 @@ export * from './style-library.js';
 export * from './model-facts.js';
 export * from './character-sheet.js';
 export * from './environment-sheet.js';
+export * from './prompting-tips.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.js

@@ -16,4 +16,8 @@ export * from './style-library.js';
 export * from './model-facts.js';
 export * from './character-sheet.js';
 export * from './environment-sheet.js';
+// Exported from the `./prompts` subpath (not just the root barrel) because the
+// desktop RENDERER imports the tips — the root barrel re-exports auth.js
+// (node:fs/os/path), which breaks browser bundling. `./prompts` stays Node-free.
+export * from './prompting-tips.js';
 //# sourceMappingURL=index.js.map

package/dist/prompts/model-facts.js

@@ -6,7 +6,10 @@
 export const MODEL_FACTS = [
     {
         id: 'nano-banana-2',
-        label: 'Nano Banana 2 (Gemini 3 Image)',
+        // Gemini 3.1 FLASH Image — verified against the runtime slug map in
+        // slate/src/main/api/google.ts. Nano Banana PRO is a different model
+        // (gemini-3-pro-image-preview); do not conflate them.
+        label: 'Nano Banana 2 (Gemini 3.1 Flash Image)',
         kind: 'image',
         maxRefImages: 14, // 10 object-fidelity + 4 character-consistency; categories don't trade.
         maxIngredients: null,

package/dist/prompts/partials.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const PARTIALS: Record<string, string>;
+//# sourceMappingURL=partials.generated.d.ts.map

package/dist/prompts/partials.generated.js

@@ -0,0 +1,14 @@
+// GENERATED — do not edit. Source: packages/shared/skills/_partials/*.md
+// Regenerated by scripts/sync-partials.mjs on every build.
+//
+// This is the SAME text injected between the @inject markers in the
+// per-model skills, so the TS consumers and the markdown consumers can
+// no longer disagree. Edit the partial, not this file, not the skills.
+export const PARTIALS = {
+    "decision-log": "When you surface the plan, include a short **decision log** — one line per decision *you* made that the user did not specify:\n\n```\nsource phrase or declared default → what you wrote → what it resolves\n\"in a diner\"        → chrome-and-vinyl booth, 3/4 on the counter   → fixes the anchor so blocking is repeatable\n(no time of day)    → late afternoon, low warm key                 → default; say the word and it changes\n(no camera)         → slow push-in, single move                    → one move per shot; stacking increases instability\n```\n\n**Hard rule: never silently add weather, props, style, or camera movement.** If it wasn't in the brief and you added it, it goes in the log. This is the \"why did you add that?\" affordance — for an agent that writes prompts on the user's behalf and spends their credits, it is what keeps the model in assembly and the user in the director's chair.\n\n> ❌ **Do NOT turn this into a question gate.** Clarifying questions before optimizing directly fight the locked fast-path rule: *if intent is clear, generate immediately with sane defaults, don't ask questions; only ask for production intent, and batch every question into one message.* Log the decisions, then go. The log is an **output**, not an interrogation — surfaced alongside the plan, never as a separate ceremony, and never as a reason to wait.",
+    "reference-rules-core": "Identity = a few flat-lit neutral angles; one reference per role, named inline; 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 — each one adds context AND another variable to balance.\n2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two \"identity\" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.\n3. **One identity sheet per character — and whatever you do attach for a subject, NAME it as one entity.** A character's identity sheet is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is always better, because the model cannot tell which one is authoritative and averages them.** Where a character carries a second bound sheet — an explicit expression range, or a legacy turnaround+expression pair — cite BOTH under the SAME name, `Marcus (images 1 and 2)`. That shared name, not a role essay, is what tells the model they are ONE person and stops the varied expressions from averaging the face. **Do NOT hand-write a \"Reference Image Instructions\" block or role essays** (\"use for identity, ignore the outfit, render a neutral expression\") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.\n4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.\n5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — 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 — the cells share a split detail budget and were generated jointly, so their flaws propagate.\n7. **Reuse the same refs across every shot** in a sequence. Lock a set and keep it; swapping references mid-sequence causes drift, because the model adapts each reference to the current prompt rather than copying it.\n8. **Legible in-shot text → bake it into a still start frame, never trust text-to-video.** Have an image model render the text, then animate from that locked frame. Video models smear type.\n9. **Working from existing media — describe ONLY what changes.** The source already carries its composition, motion, timing, and performance; re-describing them fights the model. Narrate the delta. (Video lane: restyle your own clip while keeping the performance; delayed-VFX on \"video one\"; marker-object insertion; video-as-reference for a series.)\n10. **Style transforms happen in natural language.** By default the source's artistic medium and visual style are inherited. To change it, add a plain-text instruction (\"anime → real person\"). There are no preset pickers, and there is no style slider.",
+    "reference-tips-short": "Name each reference inline; never write role essays. Slates does this for you: `@mention` a subject or environment and it composes `Marcus (images 1 and 2) in the cafe (image 3)`, citing them in the exact order it sends them. Citing both of a character's sheets under the SAME name is what tells the model they are one person — a \"Reference Image Instructions\" block does the opposite and drags the sheet's studio lighting into your scene. Start with 2-3 focused refs.",
+    "references-read-literally": "> **The general law: the model reads a reference literally.**\n> A reference image is not a suggestion. Whatever is baked into it — lighting, medium, texture, symmetry, competing identities — is read as a **property of the subject** and reproduced downstream. A baked rim light tints every shot made from that sheet. A sheet that looks like a 3D game render gets animated like game footage. Two competing renderings of one face get averaged into a third face.\n\nEvery reference rule below is a corollary of that one sentence, which is why \"prep the reference\" beats \"prompt around the reference\" every time:\n\n- **Flat, plain identity refs** — because scene lighting in the sheet becomes scene lighting in the output (Slates' own receipt: a studio-lit sheet produced a subject that looked green-screen-pasted in front of mountains).\n- **One authoritative rendering per subject** — because the model cannot tell which panel is the real one. ByteDance documents this failure directly: multi-view character assets \"confuse the model's character recognition, causing it to generate duplicate characters of the same appearance.\"\n- **No 3D-game-render look in a reference** — the model recognizes the render mood and inherits its motion character, so the *animation* comes out looking like game footage. This is not a taste rule; it is the same literal-reading mechanism applied to the temporal layer.\n- **Break perfect symmetry** — mirrored faces and dead-square framing read as synthetic, and the model preserves that reading rather than correcting it.\n\n**What this means in practice:** when output is wrong in a way that tracks the *subject* rather than the *scene* — the lighting is wrong the same way in every shot, the face drifts, the material looks synthetic everywhere — fix the reference, not the prompt. Prompting around a baked-in property is the expensive way to lose.",
+    "still-gate": "**A visible defect in the still is already a STOP.** Do not animate it. Fix the frame first, then move to motion — and go to motion only when the crop passes the still scan and you genuinely need movement to confirm an uncertain edge, reflection, or object.\n\nThis is a **cost** rule as much as a craft rule: a 1080p/10s premium video generation costs many multiples of an image re-roll, and video is where a defect stops being fixable. Anything wrong in the still gets worse in motion — soft geometry mushes, broken-but-plausible objects fall apart, oily textures start crawling. **Animating a known-bad frame is the single most expensive mistake in the pipeline.** Re-rolling the image is the cheap move; re-rolling the video is not.",
+};
+//# sourceMappingURL=partials.generated.js.map

package/dist/prompts/prompting-tips.d.ts

@@ -0,0 +1,23 @@
+export interface PromptingTipCard {
+    heading: string;
+    /** Monospace example line(s). \n renders as a line break. */
+    example?: string;
+    note: string;
+    /** Render highlighted as a critical/mandatory card. */
+    critical?: boolean;
+}
+export interface PromptingTipsEntry {
+    /** Family label for the modal title ("Prompting Tips — {label}"). */
+    label: string;
+    /** Intro paragraphs above the cards. */
+    intro: string[];
+    /** Two columns of tip cards. */
+    columns: [PromptingTipCard[], PromptingTipCard[]];
+    /** Footer callout paragraphs. */
+    footer?: string[];
+}
+export type PromptingTipsKey = 'seedance' | 'kling' | 'kling-edit' | 'veo' | 'omni-flash' | 'omni-flash-edit' | 'nano-banana' | 'nano-banana-lite';
+export declare const PROMPTING_TIPS: Record<PromptingTipsKey, PromptingTipsEntry>;
+/** Null when no tips exist for the key — callers render an honest fallback. */
+export declare function getPromptingTips(key: string): PromptingTipsEntry | null;
+//# sourceMappingURL=prompting-tips.d.ts.map