@slatesvideo/shared 0.6.3 → 0.6.4

package/dist/prompts/craft-cards.js

@@ -0,0 +1,82 @@
+// ============================================================
+// CRAFT CARDS — the POSITIVE half of "load the guide", made structural.
+//
+// THE MEASUREMENT THIS ANSWERS (2026-08-30, 48 trials at k=8, same brain, same
+// scorer). Inlining each model's NEVER-USE list into the generate ops'
+// descriptions moved `no_banned_tokens` from 0/8 to 30/32 — 94%. Over the same
+// runs, `guide_before_generate` was 13% before and 13% after: the agent still
+// did not fetch the skill. So the skill's NEGATIVE half became enforced and its
+// POSITIVE half — the named lens, the light direction, the stock, the
+// composition, the levers that make a shot GOOD rather than merely UN-BAD —
+// still only arrived if the model chose to go and get it, and it usually did
+// not.
+//
+// The lesson generalised in the CLAUDE.md rules: put the FACT where it cannot
+// be skipped, not a POINTER to the fact. A card is that fact for the positive
+// half — 250-400 words of the levers that matter for ONE model, delivered
+// where the agent is already looking.
+//
+// 🚨 WHERE IT IS DELIVERED, AND WHY THERE. On the RESULT of
+// `slates_estimate_generation_cost`, which the doctrine already tells the agent
+// to call before every generation. That placement costs ZERO prefix bytes — the
+// desktop's cached tool prefix is unchanged — and it arrives at the one moment
+// the model has just named the model it is about to use. Putting it in the
+// `model` param description instead would have grown the largest op on the
+// surface by 15 cards on every turn of every session, to be read once.
+//
+// 🚨 THE CARD IS NEVER WRITTEN HERE. It is EXTRACTED from the skill file
+// itself, between `<!-- @card:start -->` / `<!-- @card:end -->` markers — the
+// same mechanism, and the same reason, as banned-tokens.ts: a card authored
+// downstream is a second copy of the skill that drifts from it. Edit the skill;
+// the card follows on the next build.
+// ============================================================
+import { SKILLS } from '../skills/content.js';
+/**
+ * Hard ceiling per card, in characters.
+ *
+ * A card is a CARD. The largest skill is 5,736 words and loading it whole is
+ * exactly the cost this mechanism exists to avoid — if a card needs more than
+ * this, the extra belongs in the body of the skill, which is one
+ * `slates_get_prompting_guide` call away. Asserted at load, so an over-long
+ * card fails the build rather than quietly inflating every estimate result.
+ */
+export const CRAFT_CARD_CEILING = 2400;
+const CARD_FENCE_RE = /<!--\s*@card:start\s*-->([\s\S]*?)<!--\s*@card:end\s*-->/g;
+/** Author notes to whoever edits the skill next; never part of the card. */
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+function extractCard(skill, content) {
+    CARD_FENCE_RE.lastIndex = 0;
+    const parts = [];
+    let m;
+    while ((m = CARD_FENCE_RE.exec(content)) !== null) {
+        parts.push(m[1].replace(HTML_COMMENT_RE, '').trim());
+    }
+    if (parts.length === 0)
+        return null;
+    const body = parts.join('\n\n').trim();
+    if (body.length > CRAFT_CARD_CEILING) {
+        throw new Error(`[craft-cards] ${skill}.md's @card block is ${body.length} chars, over the ` +
+            `${CRAFT_CARD_CEILING} ceiling. A card rides EVERY estimate result for that model — ` +
+            `move the overflow into the body of the skill, which slates_get_prompting_guide returns whole.`);
+    }
+    return body;
+}
+/** Every card, keyed by skill name. Built once at load; integrity asserted. */
+export const CRAFT_CARDS = Object.freeze(Object.fromEntries(Object.entries(SKILLS)
+    .map(([skill, content]) => [skill, extractCard(skill, content)])
+    .filter((entry) => entry[1] !== null)));
+/** The card for a skill, or null when that skill carries none. */
+export function craftCard(skill) {
+    return CRAFT_CARDS[skill] ?? null;
+}
+/**
+ * The card as it appears in an op RESULT: the body, plus one line naming where
+ * the rest lives so the agent knows the card is a summary and not the guide.
+ */
+export function describeCraftCard(skill) {
+    const card = craftCard(skill);
+    if (!card)
+        return '';
+    return `${card}\n\nFull guide (examples, failure modes, sources): slates_get_prompting_guide("${skill}").`;
+}
+//# sourceMappingURL=craft-cards.js.map

package/dist/prompts/environment-sheet.js

@@ -25,6 +25,22 @@ export function buildEnvironmentEstablishingPrompt(userStyle) {
         `If the reference image contains people or characters, generate the location as an empty space — ignore the figures. ` +
         `No text, no labels, no captions.`);
 }
+// ⚠️ STATUS: authored doctrine that currently reaches NO model. Adjudicated
+// 2026-09-04 (dead-code sweep §5 D1). Both constants below have zero consumers
+// anywhere in the workspace, and — unlike IMAGE_PROMPT_FORMULA, which was a
+// verbatim second copy of slates-prompting-nano-banana-2.md and was deleted —
+// nothing in skills/*.md or the craft cards carries this content. So it is a
+// capability gap, not a duplicate: deleting it would lose the only copy.
+//
+// The fix is NOT to wire a TS consumer. craft-cards.ts states the rule: "THE
+// CARD IS NEVER WRITTEN HERE… a card authored downstream is a second copy of
+// the skill that drifts from it." Environment plates have no skill of their own
+// yet (there is a Characters/Environments/Styles tab in the product, and a
+// slates-character-identity skill, but no environment counterpart). Wiring this
+// in means AUTHORING that skill section — a content + token-budget decision —
+// after which these two constants should be deleted, not kept alongside it.
+//
+// Until then: EDITING THE TEXT BELOW CHANGES NOTHING THAT SHIPS.
 /** 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. ' +
     '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), ' +

package/dist/prompts/index.d.ts

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

package/dist/prompts/index.js

@@ -24,4 +24,8 @@ export * from './environment-sheet.js';
 // 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';
+// Asset captions — one rule for the op surface's compactAsset and the desktop
+// gallery. Also its own leaf subpath (`@slatesvideo/shared/asset-label`) for the
+// renderer, which cannot import the root barrel.
+export * from './asset-label.js';
 //# sourceMappingURL=index.js.map

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

@@ -49,6 +49,41 @@ export interface VideoResolutionCapability {
     default?: VideoResolution;
 }
 /** Everything a model will ACCEPT. Capability only — never a price. */
+/**
+ * What a TEXT-TO-SPEECH surface accepts. Every number here was MEASURED against
+ * the live API on 2026-09-05, not read from documentation — the vendor's docs
+ * omit the rate limit entirely and its API accepts an unknown `audioEncoding`
+ * with a 200 rather than a 400, so anything taken on trust here is a guess that
+ * bills.
+ *
+ * 🚨 `clonesPerMinute` IS A PRODUCT CONSTRAINT, NOT A TUNING KNOB. The vendor
+ * rate-limits voice cloning WORKSPACE-WIDE (every Slates user shares our one
+ * key), so it caps how many people can mint a voice in the same minute across
+ * the whole product. It is surfaced here so the seat can say so in words rather
+ * than failing opaquely.
+ */
+export interface VoiceCloneCapability {
+    /** Reference-audio duration the clone endpoint accepts, in seconds. */
+    minSeconds: number;
+    maxSeconds: number;
+    /** Ceiling on ONE reference sample, in bytes. */
+    maxBytes: number;
+    /** Container formats the clone endpoint decodes. */
+    formats: readonly string[];
+    /** Clone requests per minute, WORKSPACE-WIDE (measured: a 429 names the limit). */
+    clonesPerMinute: number;
+    /**
+     * Stored custom voices the plan allows. The seat holds the steady-state count
+     * near ZERO by deleting each voice after it renders (mint → synthesize →
+     * delete), so this is the wall that argument exists to never reach.
+     */
+    maxStoredVoices: number;
+    /** Bounds on the voice-DESIGN prompt, the path that needs no reference audio. */
+    designPromptChars: {
+        min: number;
+        max: number;
+    };
+}
 export interface ModelCapability {
     aspectRatios: AspectRatio[];
     /** Provider-keyed overrides. `fal` is the one that matters — see AGENT_ROUTE_PROVIDER. */
@@ -69,6 +104,14 @@ export interface ModelCapability {
     maxReferenceVideoSeconds?: number;
     /** Combined seconds across every reference audio clip. */
     maxReferenceAudioSeconds?: number;
+    /**
+     * Max characters in ONE synthesis request. Present ⟺ the surface is TTS.
+     * This is the number the character BILLING BUCKET is sized against, so it
+     * must never be hand-typed downstream — `slate`'s registry spreads it in.
+     */
+    maxCharacters?: number;
+    /** Reference-audio and voice-design spec. Present ⟺ the surface can clone. */
+    voiceClone?: VoiceCloneCapability;
 }
 /**
  * The provider every AGENT generation actually lands on for Kling and Veo.
@@ -86,6 +129,15 @@ export interface ModelCapability {
 export declare const AGENT_ROUTE_PROVIDER = "fal";
 export declare const MODEL_CAPABILITIES: Record<string, ModelCapability>;
 export declare function getModelCapability(model: string): ModelCapability | undefined;
+/**
+ * The voice-cloning spec for a TTS surface, or undefined for anything else.
+ *
+ * Exists so the desktop reads the reference-audio bounds, the design-prompt
+ * bounds and the clone rate limit from HERE rather than retyping them into a
+ * form control. A control whose limit disagrees with the vendor's is a limit
+ * the user first meets AFTER pressing the button.
+ */
+export declare function voiceCloneFor(model: string): VoiceCloneCapability | undefined;
 /** Aspect ratios a model accepts, honouring the provider override. */
 export declare function aspectRatiosFor(model: string, provider?: string): AspectRatio[];
 /** Video resolutions a model accepts. A FIXED model reports exactly its one value. */

package/dist/prompts/model-capabilities.js

@@ -481,11 +481,53 @@ export const MODEL_CAPABILITIES = {
     'eleven-sfx': {
         aspectRatios: [],
     },
+    // ── Text-to-speech ─────────────────────────────────────────────────────────
+    //
+    // The TTS seat. `maxCharacters` is the one number the billing bucket is sized
+    // against, and it is MEASURED: the API rejects 2,001 characters by name
+    // ("text length should not exceed 2000 characters"). Do not raise it from a
+    // docs page — raise it from a request that succeeds.
+    //
+    // ⚠️ NO `durationSeconds` HERE, and that is the shape of the surface rather
+    // than an omission: speech length falls out of the text, so this row bills on
+    // characters and has no duration dimension at all. Every derivation that
+    // switches on an audio surface must read the BILLING UNIT, never assume one.
+    'inworld-tts-2': {
+        aspectRatios: [],
+        maxCharacters: 2000,
+        voiceClone: {
+            // 5-15s of reference audio, ≤4 MB per sample — the vendor's documented
+            // spec, and a 12.6s / 555 KB sample cloned successfully against it.
+            minSeconds: 5,
+            maxSeconds: 15,
+            maxBytes: 4 * 1024 * 1024,
+            formats: ['wav', 'mp3', 'webm'],
+            // 🚨 MEASURED, and it appears in no documentation: the third clone inside
+            // one minute returned 429 "limit: 2, time window: m". This is workspace-
+            // wide, so it is shared across every Slates user.
+            clonesPerMinute: 2,
+            maxStoredVoices: 100,
+            // Measured: the design endpoint rejects a prompt outside these bounds by
+            // name ("design_prompt (Voice Description) must be between 7 and 1000").
+            designPromptChars: { min: 7, max: 1000 },
+        },
+    },
 };
 // ── Queries ──────────────────────────────────────────────────────────────────
 export function getModelCapability(model) {
     return MODEL_CAPABILITIES[model];
 }
+/**
+ * The voice-cloning spec for a TTS surface, or undefined for anything else.
+ *
+ * Exists so the desktop reads the reference-audio bounds, the design-prompt
+ * bounds and the clone rate limit from HERE rather than retyping them into a
+ * form control. A control whose limit disagrees with the vendor's is a limit
+ * the user first meets AFTER pressing the button.
+ */
+export function voiceCloneFor(model) {
+    return MODEL_CAPABILITIES[model]?.voiceClone;
+}
 /** Aspect ratios a model accepts, honouring the provider override. */
 export function aspectRatiosFor(model, provider) {
     const cap = MODEL_CAPABILITIES[model];

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

@@ -80,8 +80,4 @@ export declare const MODEL_FACTS: ModelFact[];
  */
 export declare function describeRouting(kind: ModelFact['kind'], route?: ModelFact['route']): string;
 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

@@ -300,6 +300,14 @@ export const MODEL_FACTS = [
         ...caps('eleven-sfx'),
         notes: 'ONE-SHOT SOUND EFFECT with an EXACT duration — route here for a single hit that must land on a frame (door slam, whoosh, impact, UI blip) or for a seamless loop. AUDIO-ONLY. For layered scenes with dialogue or room tone, seed-audio does it in one pass instead.',
     },
+    {
+        id: 'inworld-tts-2',
+        route: 'generate',
+        label: 'Inworld Realtime TTS-2',
+        kind: 'audio',
+        ...caps('inworld-tts-2'),
+        notes: 'THE VOICE SEAT — one named voice saying one line, billed per CHARACTER not per second. Route here when WHO is speaking matters. NOT scene audio — that is seed-audio; a single effect is eleven-sfx.',
+    },
 ];
 const FACT_BY_ID = new Map(MODEL_FACTS.map((m) => [m.id, m]));
 /**
@@ -321,8 +329,4 @@ export function describeRouting(kind, route = 'generate') {
 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/partials.generated.js

@@ -5,12 +5,13 @@
 // 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.",
+    "decision-log": "When you surface the plan, include a short **decision log** — one line per decision *you* made that the user did not specify **and that no row already records**:\n\n```\nsource phrase or declared default → what you wrote → what it resolves\n\"in a diner\"        → warm, and the light is the reason           → why the anchor was chosen, not what it is\n(no time of day)    → late afternoon, low warm key                 → default; say the word and it changes\n```\n\n🚨 **Keep it to what is NOT already data — and almost everything now IS.** A Shot holds the references and their roles, the model, every param, the shot size, the camera, the prop, the action and the spoken line, and `slates_list_shots` reads the whole board back in order with its variety counts. Narrating any of those is retelling a row the user can open. **Write the Shot, and let the log carry only the judgement no field holds** — why this world, why this light, why this register.\n\n**Hard rule: never silently add weather, props, style, or camera movement.** Four of those are now FIELDS: put the value on the Shot (`prop`, `camera`, `shotSize`, `action`) so the user can read and change it, and put the *reason* in the log only when you invented it rather than being told it. The rule has not softened — it moved from narration into data, which is stronger, because a field can be corrected and a sentence in chat cannot.\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, named inline.** A character's identity 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 better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **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 (image 1) in the cafe (image 2)`, citing them in the exact order it sends them. One canonical identity image avoids competing facial renderings; a \"Reference Image Instructions\" block drags reference 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.",
     "seedance-25-timestamps": "**2.0 does not respond to timestamps and answers only to shot numbers. 2.5 responds to\ninteger-second timestamps.** That is ByteDance's own first line under \"Differences from Seedance\n2.0\", and it is why a 30-second take is usable at all: the length is only worth buying if you can\nsay *when* things happen inside it.\n\nBoth formats are valid on 2.5, and you can mix them — `Shot N` blocks for a storyboard whose\npacing you are happy to leave to the model, timestamps when a beat has to land at a moment.\n\n**Three ways to control time, all first-party:**\n\n| Form | Write it like |\n|---|---|\n| **Interval** | `0-3 seconds… 3-7 seconds… 7-15 seconds` or `[1s-4s]… [4s-8s]… [8s-12s]` |\n| **Time point** | *\"Quick left sideways transition at the 5-second mark.\"* |\n| **Relative** | *\"After 3 seconds, everyone around him shakes their head.\"* · *\"The frame freezes for 1 second after he presses the shutter.\"* |\n\n**The rules that come with them:**\n\n- **One second is the smallest unit.** Integers only — no `2.5s`, no frames.\n- **No gaps in the timeline.** `0-3s… 5-6s…` leaves 3-5s unspecified and the model fills it however\n  it likes. Intervals must abut: `0-3s`, `3-7s`, `7-15s`.\n- **Budget the plot to the seconds.** Too little content in a range and the model improvises to\n  fill it; too much and you get extra cuts or dropped beats. This is the actual craft of a 30s take.\n- **Never time-code a high-frequency action.** *\"Shake your head three times per second\"* is\n  explicitly called out as a misuse — timestamps schedule beats, they don't choreograph frames.\n- **Transitions want both halves:** the moment AND the method — *\"At the 5-second mark, the camera\n  transitions leftward with a left wipe into a natural dissolve.\"*\n- **Timestamps work on an EDIT too**, and that is where they earn the most: they scope a change in\n  time as well as in content — *\"Change the man's action from drinking coffee to mopping the floor\n  from 4-6 seconds in Video 1, and leave the rest of the content unchanged.\"* Without a range, a\n  whole-clip instruction is applied to the whole clip.\n\nDo **not** carry this back to 2.0, and do not carry Veo's `[00:00-00:02]` bracket syntax into\neither — 2.0 ignores time entirely, and the cross-model syntax swap is its own known failure.",
     "seedance-25-timestamps-short": "Seedance 2.0 ignores timing and answers only to \"Shot 1 / Shot 2\"; 2.5 acts on whole-second timestamps, and that is what makes a 30-second take controllable rather than just long. Three forms work: intervals (\"0-3 seconds…3-7 seconds\"), a point (\"at the 5-second mark\"), or relative (\"after 3 seconds\"). Whole seconds only, no gaps between intervals, and never to choreograph fast repeated motion. They work on edits too, where a range scopes the change: \"…from 4-6 seconds…\".",
     "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.",
+    "thresholds": "<!-- GENERATED from @slatesvideo/shared — do not edit between the markers.\n     Source: CONFIRM_CREDITS, DEVIATION_FACTOR and the audio bounds in\n     packages/shared/src/operations/index.ts. Every number here is REFUSED by an\n     op when a prompt gets it wrong, which is why none of them is typed by hand\n     any more: this block replaced four claims that contradicted the code. -->\n\n**The thresholds, from the code that enforces them:**\n\n- **Confirm gate:** above **17 credits** an op returns `requires_confirm` and will not\n  proceed until you re-call with `confirm: true`. Below it, announce the cost once and go.\n- **Deviation pause:** the desktop Studio Agent stops and re-asks when projected generation spend\n  exceeds the approved plan by more than **20%**. You do not trigger this; the app does.\n- **Seed Audio duration:** **3–120 seconds.** There is no duration\n  parameter on the model — the number you pass is written into the prompt AND is what the user is\n  billed. Outside that range the op refuses rather than clamping.\n- **Sound Effects duration:** **1–22 seconds**, billed per second, never left for the\n  model to pick.\n\nNever quote a credit figure from memory: `slates_estimate_generation_cost` returns the real one.",
 };
 //# sourceMappingURL=partials.generated.js.map

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

@@ -16,7 +16,7 @@ export interface PromptingTipsEntry {
     /** Footer callout paragraphs. */
     footer?: string[];
 }
-export type PromptingTipsKey = 'seedance' | 'seedance-2-5' | 'seedance-2-5-edit' | 'kling' | 'kling-edit' | 'veo' | 'omni-flash' | 'omni-flash-edit' | 'minimax-h3' | 'ltx-2-5' | 'nano-banana' | 'nano-banana-lite' | 'seed-audio' | 'eleven-sfx';
+export type PromptingTipsKey = 'seedance' | 'seedance-2-5' | 'seedance-2-5-edit' | 'kling' | 'kling-edit' | 'veo' | 'omni-flash' | 'omni-flash-edit' | 'minimax-h3' | 'ltx-2-5' | 'nano-banana' | 'nano-banana-lite' | 'seed-audio' | 'eleven-sfx' | 'inworld-tts-2';
 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;

package/dist/prompts/prompting-tips.js

@@ -704,6 +704,63 @@ const LTX_2_5 = {
         'In image-to-video, do not cut away from the opening frame too early: you have paid for that frame, so let it play before the first move.',
     ],
 };
+const INWORLD_TTS = {
+    label: 'Inworld TTS-2',
+    intro: [
+        'The voice seat: one named voice saying one line. Unlike every other surface in Slates, the prompt is not a description of what you want — it IS the words that get spoken, verbatim, and its length is what you are billed for.',
+        'A voice belongs to a character, the same way a face does. Build it once from a clip or a description, then send it lines.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'Direction goes in SQUARE BRACKETS',
+                example: '\u2717 (quietly) I hope nobody notices\n\u2713 [whispering] I hope nobody notices',
+                note: 'Brackets are read as direction and never spoken. PARENTHESES ARE SPOKEN ALOUD \u2014 a parenthetical stage direction comes back with the narrator saying the word "quietly". This is the single easiest way to ruin a take.',
+                critical: true,
+            },
+            {
+                heading: 'Plain English inside the brackets',
+                example: '[very quiet] \u00b7 [very slow] \u00b7 [say excitedly] \u00b7 [whisper in a hushed style]',
+                note: 'It is natural-language steering across emotion, volume, pitch, speed, articulation and vocal style \u2014 not a fixed vocabulary. Write the direction the way you would say it to an actor.',
+            },
+            {
+                heading: 'Non-verbals are their own tags',
+                example: '[laugh] \u00b7 [sigh] \u00b7 [breathe] \u00b7 [cough] \u00b7 [yawn] \u00b7 [clear throat]',
+                note: 'They land inline, where they occur in the line.',
+            },
+            {
+                heading: 'A mistyped tag fails silently',
+                note: 'An instruction it does not recognise is still swallowed and still changes the delivery \u2014 it is never spoken and never errors. So a typo produces a strange read with no warning. If a take sounds off, suspect the tag before the voice.',
+                critical: true,
+            },
+        ],
+        [
+            {
+                heading: 'Tags persist until changed',
+                example: '[very slow] First line. Second line is still slow. [reset] Third is normal.',
+                note: 'A direction governs everything after it, across sentences. Use [reset] to return to a normal read rather than assuming the next sentence starts clean.',
+            },
+            {
+                heading: 'Punctuation is the timing',
+                example: 'Wait. Stop.  \u2260  Wait, stop.',
+                note: 'Full stops buy a beat; commas do not. Write the line the way it is said.',
+            },
+            {
+                heading: 'One line, one take',
+                note: 'Split a paragraph into separate generations so a bad clause costs one re-roll instead of the whole speech. Max 2,000 characters per take.',
+            },
+            {
+                heading: 'Spell out anything ambiguous',
+                example: 'twenty twenty-six \u00b7 Doctor Reyes',
+                note: 'Numbers, dates and abbreviations are read literally. Write them as they should sound.',
+            },
+            {
+                heading: 'Know its seat',
+                note: 'One voice, cleanly. Dialogue mixed with effects and room tone in one pass is Seed Audio; a single non-speech sound is Sound Effects.',
+            },
+        ],
+    ],
+};
 export const PROMPTING_TIPS = {
     seedance: SEEDANCE,
     'seedance-2-5': SEEDANCE_25,
@@ -719,6 +776,7 @@ export const PROMPTING_TIPS = {
     'nano-banana-lite': NANO_BANANA_LITE,
     'seed-audio': SEED_AUDIO,
     'eleven-sfx': ELEVEN_SFX,
+    'inworld-tts-2': INWORLD_TTS,
 };
 /** Null when no tips exist for the key — callers render an honest fallback. */
 export function getPromptingTips(key) {

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

@@ -50,16 +50,45 @@ export interface ComposedReferences {
      * Tokens written in the prompt that matched NO reference group, as authored
      * (`'#noir'`, `'@bob'`), first-appearance order, deduped case-insensitively.
      *
-     * 🚨 THIS FIELD EXISTS BECAUSE THE ALTERNATIVE IS A SILENT EDIT. A `#tag` with
-     * no matching style is DELETED from the text — a raw tag confuses every model,
-     * so removing it is right, but removing it without saying so changes what the
-     * user asked for behind their back. Prompt-transparency doctrine (slate
-     * `CLAUDE.md`) requires the surface to be able to say "this went nowhere", and
-     * this is the only record that the token was ever there. Callers that render a
-     * composed-prompt preview MUST surface it.
+     * 🚨 IT IS A REPORT, NOT A RECEIPT FOR A DELETION. These tokens are left in
+     * `prompt` EXACTLY as the user typed them (see step 2) — nothing is removed
+     * and nothing is humanised. What the field says is narrower and more useful:
+     * "no reference is attached for this word", which is the difference between a
+     * mistyped mention and a `@handle` you meant to typeset. Callers that render a
+     * composed-prompt preview SHOULD surface it — as a note, never as an error,
+     * because nothing has gone wrong.
      */
     unresolvedTokens: string[];
 }
+/**
+ * 🚨 A HEX COLOUR IS NOT A TAG. `#000000` is to `#` what `eric@gmail.com` is to
+ * `@`: an everyday literal that happens to open with our sigil, written by
+ * someone who was not reaching for our feature at all.
+ *
+ * The TEXT was already safe — an unresolved token is returned byte-identical
+ * (see TOKEN_RE) — so what this guards is the REPORT. The `@` half of that
+ * grammar gets its everyday literal excluded for free, because an email's `@`
+ * sits after a word character and the boundary lookbehind kills it. A hex
+ * colour gets no such help: `#` at a word boundary is exactly how a real tag is
+ * written too, so `#000000` reaches `noteUnresolved` and a palette prompt
+ * ("pure black #000000 with #c8ff00 accents") comes back with every colour
+ * listed as *matching nothing saved* — an accusation about words that were
+ * never mentions. That is the asymmetry this closes, and it is the same
+ * complaint, in the same place, as `#3a3a3c` being eaten for months.
+ *
+ * 🚨 IT GATES THE REPORT, NOT THE GRAMMAR, and that is the whole design.
+ * `fade`, `cafe`, `dead`, `beef`, `decade` and `facade` are all valid hex
+ * digits AND plausible style names, so excluding hex shapes from TOKEN_RE would
+ * quietly stop `#fade` from attaching a style called "Fade" — trading a noisy
+ * note for a silent drop, which is the worse half of the trade every time.
+ * Resolution is checked first and always wins; only a token that binds to
+ * nothing ever reaches here.
+ *
+ * Lengths are CSS's: 3 (`#fff`), 4 (`#fff8`), 6 (`#c8ff00`), 8 (`#c8ff00ff`).
+ * `#1` and `#2026` are deliberately NOT covered — an ordinal is not a colour,
+ * and widening this to "anything numeric" would start swallowing tags.
+ */
+export declare function isHexColorToken(sigil: string, token: string): boolean;
 /**
  * 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

package/dist/prompts/reference-composer.js

@@ -44,13 +44,66 @@ function joinNums(nums) {
         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(' ');
+/**
+ * 🚨 A SIGIL IS A MENTION ONLY IF IT RESOLVES. Everything else is prose, and
+ * prose is not ours to edit.
+ *
+ * This grammar used to be `/([@#])([\w-]+)/g` with "unresolved" as a rewrite
+ * branch: an unknown `@word` was humanised (`@woodland.candle` → "Woodland" +
+ * ".candle") and an unknown `#word` was deleted outright. Both assumed anyone
+ * typing a sigil was reaching for OUR feature, so the app quietly rewrote the
+ * one thing the composer exists to protect — and it failed precisely where the
+ * literal characters matter most: a poster's `@handle`, an email address, a hex
+ * colour. That last one is not hypothetical: `#3a3a3c` was eaten out of every
+ * identity-sheet prompt for months (`reference-rules.ts`, 2026-07-30), which is
+ * the same bug wearing a different sigil.
+ *
+ * Two changes make the sigil safe to type:
+ *
+ * 1. THE GRAMMAR IS NARROW. A sigil only opens a token at a boundary, so
+ *    `eric@gmail.com` is never even a candidate, and a token may carry interior
+ *    dots, so `@woodland.candle` is ONE token rather than a mention with debris
+ *    stuck to it. Interior only — a trailing `.` stays with the sentence.
+ * 2. AN UNRESOLVED TOKEN IS RETURNED UNTOUCHED. A mention is a BINDING; when it
+ *    binds to nothing there is nothing to translate, so there is nothing to
+ *    rewrite. It is reported through `unresolvedTokens` and sent as written.
+ *
+ * There is deliberately NO escape syntax (`\@`, quoting). Making someone learn
+ * our grammar to opt OUT of a feature they never invoked is the shoehorn this
+ * change exists to remove — the sandbox rule from the root `CLAUDE.md`: a
+ * capability attaches to the primitive, it does not stand in the way of it.
+ */
+const TOKEN_RE = /(?<![\w.@#])([@#])([\w-]+(?:\.[\w-]+)*)/g;
+/**
+ * 🚨 A HEX COLOUR IS NOT A TAG. `#000000` is to `#` what `eric@gmail.com` is to
+ * `@`: an everyday literal that happens to open with our sigil, written by
+ * someone who was not reaching for our feature at all.
+ *
+ * The TEXT was already safe — an unresolved token is returned byte-identical
+ * (see TOKEN_RE) — so what this guards is the REPORT. The `@` half of that
+ * grammar gets its everyday literal excluded for free, because an email's `@`
+ * sits after a word character and the boundary lookbehind kills it. A hex
+ * colour gets no such help: `#` at a word boundary is exactly how a real tag is
+ * written too, so `#000000` reaches `noteUnresolved` and a palette prompt
+ * ("pure black #000000 with #c8ff00 accents") comes back with every colour
+ * listed as *matching nothing saved* — an accusation about words that were
+ * never mentions. That is the asymmetry this closes, and it is the same
+ * complaint, in the same place, as `#3a3a3c` being eaten for months.
+ *
+ * 🚨 IT GATES THE REPORT, NOT THE GRAMMAR, and that is the whole design.
+ * `fade`, `cafe`, `dead`, `beef`, `decade` and `facade` are all valid hex
+ * digits AND plausible style names, so excluding hex shapes from TOKEN_RE would
+ * quietly stop `#fade` from attaching a style called "Fade" — trading a noisy
+ * note for a silent drop, which is the worse half of the trade every time.
+ * Resolution is checked first and always wins; only a token that binds to
+ * nothing ever reaches here.
+ *
+ * Lengths are CSS's: 3 (`#fff`), 4 (`#fff8`), 6 (`#c8ff00`), 8 (`#c8ff00ff`).
+ * `#1` and `#2026` are deliberately NOT covered — an ordinal is not a colour,
+ * and widening this to "anything numeric" would start swallowing tags.
+ */
+export function isHexColorToken(sigil, token) {
+    return sigil === '#' && /^(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(token);
 }
 export function composeReferences(rawPrompt, groups, opts = {}) {
     // ── 1. Assign global numbers by walking the list in order ──
@@ -99,11 +152,16 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
     const seenFirst = new Set();
     const matchedInPrompt = new Set();
     // Every token that named nothing, recorded as authored and deduped by the
-    // same normalisation used for matching. This is what makes the deletion
-    // below reportable instead of silent — see ComposedReferences.unresolvedTokens.
+    // same normalisation used for matching. Nothing is removed on its account —
+    // it is the "no reference is attached for this word" report. See
+    // ComposedReferences.unresolvedTokens.
     const unresolvedTokens = [];
     const unresolvedSeen = new Set();
     const noteUnresolved = (sigil, tok) => {
+        // A hex colour that binds to no style is a colour, not a mistyped tag.
+        // See isHexColorToken — the text is unchanged either way; this is the note.
+        if (isHexColorToken(sigil, tok))
+            return;
         const key = normToken(`${sigil}${tok}`);
         if (unresolvedSeen.has(key))
             return;
@@ -112,27 +170,24 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
     };
     // 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). An UNRESOLVED token in that phrase is stripped too: leaving the
-    // preposition behind ("…a portrait in the style of") was the worse half of the
-    // silent edit — the tag vanished a step later anyway and the sentence was left
-    // broken. Stripped or not, the token is reported.
-    let body = rawPrompt.replace(/\s+(with|in)\s+the\s+style\s+of\s+([@#])([\w-]+)/gi, (_full, _prep, sigil, tok) => {
+    // behaviour). ONLY when the tag resolves: an unresolved one leaves the whole
+    // phrase exactly as authored and falls through to the token pass below, which
+    // reports it and sends it as written.
+    let body = rawPrompt.replace(/\s+(with|in)\s+the\s+style\s+of\s+([@#])([\w-]+(?:\.[\w-]+)*)/gi, (_full, _prep, sigil, tok) => {
         const g = byNorm.get(normToken(`${sigil}${tok}`));
         if (g && g.kind === 'style') {
             matchedInPrompt.add(normToken(`${sigil}${tok}`));
             return '';
         }
-        noteUnresolved(sigil, tok);
-        return '';
+        return _full;
     });
-    body = body.replace(/([@#])([\w-]+)/g, (_full, _sigil, tok) => {
+    body = body.replace(TOKEN_RE, (_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.
-            // Both are edits the user never asked for, so both are reported.
+            // Not a mention — see TOKEN_RE. Reported, returned byte-identical.
             noteUnresolved(_sigil, tok);
-            return _sigil === '#' ? '' : humanizeToken(tok);
+            return _full;
         }
         matchedInPrompt.add(key);
         if (g.kind === 'style')