@vanillaskyai/video 0.10.22 → 0.10.23

package/CHANGELOG.md

@@ -4,6 +4,18 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.23
+
+- Stop shipping the maintainer-only cinematic migration note in the published
+  package. The changelog now links it on GitHub.
+- Remove the unreferenced text-rendering and emoji modules from the source tree.
+  The bundle is unchanged; this code was already excluded from it.
+- Correct the repository map in the architecture guide, and drop the stale
+  comments that described a text component the templates no longer use. Those
+  comments also shipped inside the installable `theme` registry item.
+- Remove the CLI redirect for template command names that were renamed before
+  the package had users. Use `vanillasky templates <command>`.
+
 ## 0.10.22
 
 - Offer eight diverse homepage prompts with curated footage, a balanced fresh-page shuffle, and stable ordering when returning Home.
@@ -175,7 +187,7 @@ Before:
 
 ### Adoption
 
-Remove brand options and regenerate source-owned templates from the new catalog. Re-author or regenerate saved videos from retained source material; do not rename old IDs or change their version field blindly. See [cinematic migration](docs/maintainers/cinematic-migration.md).
+Remove brand options and regenerate source-owned templates from the new catalog. Re-author or regenerate saved videos from retained source material; do not rename old IDs or change their version field blindly. See [cinematic migration](https://github.com/VanillaSkyAi/video/blob/main/docs/maintainers/cinematic-migration.md).
 
 ```tsx
 <VideoChat options={{ endpoint: "/api/video-chat" }} />

package/README.md

@@ -1,5 +1,10 @@
 # Give your AI a voice and a face
 
+[![CI](https://github.com/VanillaSkyAi/video/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/VanillaSkyAi/video/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@vanillaskyai/video.svg)](https://www.npmjs.com/package/@vanillaskyai/video)
+[![runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](package.json)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
 **VanillaSky is the open-source voice-and-video chat layer.** Add a polished,
 general-purpose AI conversation that speaks and starts playing visual answers
 while they are still being composed.

package/dist/cli.js

@@ -1994,11 +1994,6 @@ function runVanillaSkyCli(argv, environment = {}) {
     return result.ok ? 0 : 1;
   }
   if (rootCommand !== "templates") {
-    const removed = /* @__PURE__ */ new Set(["list", "describe", "add", "sync", "check", "create"]);
-    if (rootCommand && removed.has(rootCommand)) {
-      write(`Template commands moved. Use: vanillasky templates ${argv.join(" ")}`);
-      return 1;
-    }
     write(help());
     return rootCommand == null || rootCommand === "help" || rootCommand === "--help" || rootCommand === "-h" ? 0 : 1;
   }

package/docs/architecture.md

@@ -19,6 +19,26 @@ own your product policy. It supplies the complete default chat, video-planning
 prompts, trusted visual vocabulary, conversation and narration lifecycle,
 validation, streaming, and player.
 
+## Start here
+
+Six files, in this order, are enough to hold the whole system in your head.
+About 2,600 lines total, and two of them are most of it.
+
+1. `src/protocol/types.ts` — the `Video` shape. Everything else exists to
+   produce, validate, transport, or play this one object.
+2. `src/server/prompts/system-prompt.ts` — what the model is actually asked
+   for. The product's behavior is mostly here, not in the code around it.
+3. `src/server/create-video-chat-handler.ts` — the one endpoint. Where an
+   application's providers and policy attach.
+4. `src/protocol/events.ts` — the wire contract between server and browser.
+5. `src/video-chat/use-video-chat.ts` — the client lifecycle, as a reducer.
+   Read `reducer` first and the hook second.
+6. `src/visual-system/scene-templates/quote.tsx` — one complete scene, small
+   enough to read in a sitting. Every other template has this shape.
+
+To watch it run instead, `npm run dev:chat` renders the real `VideoChat` from
+source against fixtures, with no provider credentials and no spend.
+
 ## Repository map
 
 | Location | Purpose |
@@ -32,19 +52,20 @@ validation, streaming, and player.
 | `src/video-chat/` | Default `VideoChat` interface and headless conversation/session engine |
 | `src/visual-system/catalog/` | Template metadata, schemas, loading, and planner catalog |
 | `src/visual-system/scene-templates/` | Complete scenes the model may select |
-| `src/visual-system/primitives/` | Reusable visual components used inside scenes |
 | `src/visual-system/backgrounds/` | Standalone background renderers |
 | `src/visual-system/motion/` | Animation functions and timing behavior |
 | `src/visual-system/theme/` | Color and design tokens |
+| `src/visual-system/typography/` | Text fitting, formatting, and kinetic type lifecycles |
 | `src/cli/` | `vanillasky init`, `doctor`, and `providers add`, plus `vanillasky templates create`, `add`, `sync`, `check`, `list`, and `describe` |
 | `registry/items/` | Generated distributable copies installed into customer projects |
 | `src/index.ts`, `src/server.ts`, `src/react.ts`, `src/templates.ts`, `src/template-catalog.ts`, `src/test.ts`, `styles/video-chat.css` | The six small code entry points and one scoped stylesheet |
 
 The source of truth for built-in visuals is `src/visual-system`. The JSON files
 in `registry/items` are distribution artifacts, kept flat so the CLI can address
-every installable item by a stable name. Their `meta.vanillasky.layer` and
-`category` fields distinguish full templates, primitives, effects, and shared
-support code. Run `npm run registry:sync` after changing canonical visual source.
+every installable item by a stable name. Their `meta.vanillasky.layer` field is
+`template` for a complete scene the model may select, or `lib` for shared
+support code a template imports. Run `npm run registry:sync` after changing
+canonical visual source.
 
 Customer applications do not edit those internal locations. Their source of
 truth is one file per visual under `vanillasky/templates/`; `vanillasky templates sync`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.22",
+  "version": "0.10.23",
   "description": "Open-source voice-and-video chat SDK for AI applications.",
   "keywords": [
     "video-chat",
@@ -56,8 +56,7 @@
     "docs/reference/protocol.md",
     "CHANGELOG.md",
     "docs/*.md",
-    "docs/reference",
-    "docs/maintainers/cinematic-migration.md"
+    "docs/reference"
   ],
   "bin": {
     "vanillasky": "bin/vanillasky.js"

package/registry/items/theme.json

@@ -24,7 +24,7 @@
       "path": "src/visual-system/scene-templates/tokens.ts",
       "type": "registry:lib",
       "target": "vanillasky/scene-templates/tokens.ts",
-      "content": "/** Internal monochrome render tokens for cinematic scenes and shared primitives. */\nimport type { TemplateStyle } from \"../template-context\";\n\n// ─── Canonical defaults (the only place these values are defined) ──\n\nexport const TOKEN_DEFAULTS = {\n  /** Primary brand colour — CTA, highlights. */\n  primary: \"#00E5A0\",\n  /** Deepest background surface. */\n  surface: \"#0A0A14\",\n  /** Elevated card / panel surface. */\n  surfaceElevated: \"#14152A\",\n  /** Primary text color. */\n  foreground: \"#FFFFFF\",\n  /** Muted text — labels, footers, supporting copy. */\n  muted: \"#A7A6B0\",\n  /** Primary sans font family (first name of the stack). */\n  font: \"Inter\",\n  /** Script accent font family for handwritten callouts. */\n  scriptFont: \"Caveat\",\n} as const;\n\n/**\n * The canonical template font stack: first family of the resolved brand font, backed by\n * OS-native sans fallbacks that render identically in preview and the\n * SVG-as-image export path.\n */\nexport function fontStack(styleFont: string | undefined): string {\n  return `${(styleFont || \"\").split(\",\")[0].trim() || TOKEN_DEFAULTS.font}, -apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Helvetica, Arial, sans-serif`;\n}\n\n// ─── Resolved tokens ───────────────────────────────────────────────\n\n// ─── Style presets ─────────────────────────────────────────────────\n\n/**\n * Background families a preset can pick. Each resolves to a pure CSS\n * background string in `gradientBackground` — no CSS `filter`, which the\n * SVG export path cannot rasterize.\n */\nexport type BackgroundFamily = \"mesh\" | \"wash\" | \"spotlight\";\n\n/** Title placement a preset defaults to (SceneFrameVariant, minus no-title). */\nexport type PresetTitlePlacement = \"title-top\" | \"title-center\";\n\nexport interface TypeTreatment {\n  /** Added to the computed fontWeight (clamped 100–900). */\n  weightDelta: number;\n  /** Added to the size role's letterSpacing, in em. */\n  trackingDeltaEm: number;\n  /** Multiplies the computed fontSize. */\n  sizeScale: number;\n  /** Applied as CSS text-transform when set. */\n  transform?: \"uppercase\";\n  /**\n   * Multiplies every text-archetype entrance/exit phase duration. Set by\n   * `resolveTokens` from `style.motion`; absent on the raw preset literals,\n   * where it reads as 1.\n   *\n   * It rides on the type treatment because that object is the one channel\n   * that already flows from `style` into every `<TemplateText>` — 17 call\n   * sites pass `resolveTokens(style).preset.type` and nothing else\n   * style-derived. Pacing of typographic motion is part of how the type is\n   * treated, so this isn't a smuggled payload.\n   */\n  phaseScale?: number;\n}\n\nexport interface StylePreset {\n  id: string;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  background: BackgroundFamily;\n  titlePlacement: PresetTitlePlacement;\n  type: TypeTreatment;\n}\n\n/**\n * The named looks. `bold` is the default and is a deliberate no-op: a config\n * with no `preset` resolves to it and renders byte-identically to the\n * pre-preset output, so adding presets can't restyle anyone's existing video.\n *\n * Deliberately small. Every preset multiplies the QA surface by every\n * template at both orientations — grow this only when a brief can't be\n * expressed by the ones here.\n */\nexport const STYLE_PRESETS: Record<string, StylePreset> = {\n  bold: {\n    id: \"bold\",\n    useWhen:\n      \"The default. Drifting two-color brand mesh, heavy tight headlines at the top. Launches, hype, product moments — the loudest of the three.\",\n    background: \"mesh\",\n    titlePlacement: \"title-top\",\n    type: { weightDelta: 0, trackingDeltaEm: 0, sizeScale: 1 },\n  },\n  editorial: {\n    id: \"editorial\",\n    useWhen:\n      \"Calm vertical wash, lighter and wider-tracked headlines, centered. Reviews, thoughtful updates, premium or B2B brands — when the copy should feel considered rather than shouted.\",\n    background: \"wash\",\n    titlePlacement: \"title-center\",\n    type: { weightDelta: -200, trackingDeltaEm: 0.01, sizeScale: 1.08 },\n  },\n  stark: {\n    id: \"stark\",\n    useWhen:\n      \"Single hard spotlight on near-black, uppercase and tightly tracked. Dev tools, technical claims, high-contrast statements — maximum weight on very few words.\",\n    background: \"spotlight\",\n    titlePlacement: \"title-top\",\n    type: { weightDelta: 100, trackingDeltaEm: -0.01, sizeScale: 1, transform: \"uppercase\" },\n  },\n};\n\nexport const DEFAULT_PRESET_ID = \"bold\";\nexport const PRESET_IDS = Object.keys(STYLE_PRESETS);\n\n/** Unknown/unset ids fall back to the default rather than throwing — a bad\n *  preset should never be the reason a render fails. */\nexport function resolvePreset(id: string | undefined): StylePreset {\n  return (id && STYLE_PRESETS[id]) || STYLE_PRESETS[DEFAULT_PRESET_ID];\n}\n\n// ─── Density & motion ──────────────────────────────────────────────\n//\n// Two dimensions orthogonal to the named preset. `preset` answers \"which\n// look\"; these answer \"how loud\". Splitting them is what lets \"make the\n// whole video more understated\" be one instruction instead of hand-tuning\n// every scene: they resolve into multipliers on levers that already reach\n// all 28 templates, so no template file knows they exist.\n//\n// Both default to `normal`, whose multipliers are all 1 — a config that sets\n// neither renders byte-identically to the pre-density output. Same invariant\n// the presets hold.\n\nexport type StyleDensity = \"airy\" | \"normal\" | \"packed\";\nexport type StyleMotion = \"calm\" | \"normal\" | \"punchy\";\n\nexport interface DensityScale {\n  id: StyleDensity;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  /** Multiplies the headline font size (via the preset's `type.sizeScale`). */\n  typeScale: number;\n  /** Multiplies the frame's safe-zone insets — bigger insets, more air. */\n  safeZoneScale: number;\n}\n\nexport interface MotionScale {\n  id: StyleMotion;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  /** Multiplies every text-archetype entrance/exit phase duration. */\n  phaseScale: number;\n}\n\nexport const DENSITY_SCALES: Record<StyleDensity, DensityScale> = {\n  airy: {\n    id: \"airy\",\n    useWhen:\n      \"Smaller headlines held further off the frame edges. Premium, considered, editorial — when the copy should have room to breathe.\",\n    typeScale: 0.92,\n    safeZoneScale: 1.3,\n  },\n  normal: {\n    id: \"normal\",\n    useWhen: \"The default. No change to type size or frame padding.\",\n    typeScale: 1,\n    safeZoneScale: 1,\n  },\n  packed: {\n    id: \"packed\",\n    useWhen:\n      \"Bigger headlines pushed closer to the edges. Dense, urgent, information-heavy — when the frame should feel full.\",\n    typeScale: 1.08,\n    safeZoneScale: 0.8,\n  },\n};\n\nexport const MOTION_SCALES: Record<StyleMotion, MotionScale> = {\n  calm: {\n    id: \"calm\",\n    useWhen:\n      \"Slower entrances and exits — text eases in rather than arriving. Founder stories, sober data, anything reflective.\",\n    phaseScale: 1.4,\n  },\n  normal: {\n    id: \"normal\",\n    useWhen: \"The default. Archetype timings as authored.\",\n    phaseScale: 1,\n  },\n  punchy: {\n    id: \"punchy\",\n    useWhen:\n      \"Snappier entrances and exits — text lands fast and clears fast. Hype, launches, hot takes.\",\n    phaseScale: 0.7,\n  },\n};\n\nexport const DEFAULT_DENSITY_ID: StyleDensity = \"normal\";\nexport const DEFAULT_MOTION_ID: StyleMotion = \"normal\";\nexport const DENSITY_IDS = Object.keys(DENSITY_SCALES) as StyleDensity[];\nexport const MOTION_IDS = Object.keys(MOTION_SCALES) as StyleMotion[];\n\n/** Unknown/unset ids fall back to `normal`, same as `resolvePreset`. */\nexport function resolveDensity(id: string | undefined): DensityScale {\n  return (id && DENSITY_SCALES[id as StyleDensity]) || DENSITY_SCALES[DEFAULT_DENSITY_ID];\n}\n\n/** Unknown/unset ids fall back to `normal`, same as `resolvePreset`. */\nexport function resolveMotion(id: string | undefined): MotionScale {\n  return (id && MOTION_SCALES[id as StyleMotion]) || MOTION_SCALES[DEFAULT_MOTION_ID];\n}\n\nexport interface ResolvedTokens {\n  /** Primary brand colour. */\n  primary: string;\n  /** Secondary brand colour. */\n  secondary: string;\n  /** Visual background, deliberately separate from semantic foreground colours. */\n  background: { type: \"solid\"; color: string } | { type: \"gradient\"; colors: [string, string] };\n  /** Deepest background surface. */\n  surface: string;\n  /** Elevated card / panel surface. */\n  surfaceElevated: string;\n  /** Primary foreground colour. */\n  foreground: string;\n  /** Muted text color. */\n  muted: string;\n  /** Full font fallback stack (see fontStack). */\n  font: string;\n  /** Script accent font family. */\n  scriptFont: string;\n  logoUrl?: string;\n  name?: string;\n  /**\n   * Resolved style preset — frame-level look. Always set.\n   *\n   * `preset.type` is the composed treatment, not the raw preset literal:\n   * `sizeScale` already carries the density multiplier and `phaseScale`\n   * carries the motion one. Templates pass this straight to `<TemplateText>`,\n   * which is how both dials reach every template without a template edit.\n   */\n  preset: StylePreset;\n  /** Resolved density dial. Always set; `normal` when unset. */\n  density: DensityScale;\n  /** Resolved motion dial. Always set; `normal` when unset. */\n  motion: MotionScale;\n}\n\nexport function resolveTokens(\n  style: TemplateStyle,\n): ResolvedTokens {\n\n  // Compose the two dials into the preset's type treatment here, once. Every\n  // template already passes `preset.type` to <TemplateText>, so folding them\n  // in at the resolver is what makes them bite everywhere with no template\n  // edits. At `normal`/`normal` both multipliers are 1 and the object is\n  // value-identical to the preset literal.\n  const preset = resolvePreset(style.preset);\n  const density = resolveDensity(style.density);\n  const motion = resolveMotion(style.motion);\n  const composedPreset: StylePreset = {\n    ...preset,\n    type: {\n      ...preset.type,\n      sizeScale: preset.type.sizeScale * density.typeScale,\n      phaseScale: motion.phaseScale,\n    },\n  };\n\n  return {\n    primary: \"#FFFFFF\",\n    secondary: \"#FFFFFF\",\n    background: { type: \"solid\", color: \"#000000\" },\n    surface: \"#000000\",\n    surfaceElevated: \"#171717\",\n    foreground: \"#FFFFFF\",\n    muted: \"#B7B7BC\",\n    font: '-apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Roboto, Arial, sans-serif',\n    scriptFont: \"Georgia\",\n    preset: composedPreset,\n    density,\n    motion,\n  };\n}\n\n// ─── Color math the resolver depends on ────────────────────────────\n// (Lives beside the resolver because theme owns both token resolution and\n// color derivation.)\n\n/**\n * Shift a hex color's hue by a number of degrees.\n * Used by internal template treatments that need a related hue.\n */\nexport function shiftHue(hex: string, degrees: number): string {\n  const r = parseInt(hex.slice(1, 3), 16) / 255;\n  const g = parseInt(hex.slice(3, 5), 16) / 255;\n  const b = parseInt(hex.slice(5, 7), 16) / 255;\n\n  const max = Math.max(r, g, b);\n  const min = Math.min(r, g, b);\n  const d = max - min;\n  const l = (max + min) / 2;\n  let h = 0;\n  let s = 0;\n\n  if (d > 0) {\n    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);\n    if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;\n    else if (max === g) h = ((b - r) / d + 2) / 6;\n    else h = ((r - g) / d + 4) / 6;\n  }\n\n  h = (h + degrees / 360 + 1) % 1;\n\n  const hue2rgb = (p: number, q: number, t: number) => {\n    if (t < 0) t += 1;\n    if (t > 1) t -= 1;\n    if (t < 1 / 6) return p + (q - p) * 6 * t;\n    if (t < 1 / 2) return q;\n    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;\n    return p;\n  };\n\n  let r2: number, g2: number, b2: number;\n  if (s === 0) {\n    r2 = g2 = b2 = l;\n  } else {\n    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;\n    const p = 2 * l - q;\n    r2 = hue2rgb(p, q, h + 1 / 3);\n    g2 = hue2rgb(p, q, h);\n    b2 = hue2rgb(p, q, h - 1 / 3);\n  }\n\n  const toHex = (v: number) =>\n    Math.round(v * 255)\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${toHex(r2)}${toHex(g2)}${toHex(b2)}`;\n}\n\n/** Lighten a hex color by a 0-1 factor. */\n/** Scale a hex color toward black by `factor` (0 = unchanged, 1 = black). */\nexport function darken(hex: string, factor: number): string {\n  if (!hex.startsWith(\"#\") || (hex.length !== 4 && hex.length !== 7)) {\n    return hex;\n  }\n  const full = hex.length === 4\n    ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`\n    : hex;\n  const ch = (i: number) =>\n    Math.max(0, Math.round(parseInt(full.slice(i, i + 2), 16) * (1 - factor)))\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${ch(1)}${ch(3)}${ch(5)}`;\n}\n\nexport function lighten(hex: string, factor: number): string {\n  if (!hex.startsWith(\"#\") || (hex.length !== 4 && hex.length !== 7)) {\n    return hex;\n  }\n  const full = hex.length === 4\n    ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`\n    : hex;\n  const r = parseInt(full.slice(1, 3), 16);\n  const g = parseInt(full.slice(3, 5), 16);\n  const b = parseInt(full.slice(5, 7), 16);\n  const lr = Math.min(255, Math.round(r + (255 - r) * factor));\n  const lg = Math.min(255, Math.round(g + (255 - g) * factor));\n  const lb = Math.min(255, Math.round(b + (255 - b) * factor));\n  return `#${lr.toString(16).padStart(2, \"0\")}${lg.toString(16).padStart(2, \"0\")}${lb.toString(16).padStart(2, \"0\")}`;\n}\n\n/**\n * Per-glyph halo for type sitting directly on photo or video.\n *\n * A frame-wide scrim can only trade picture for contrast, and it loses that\n * trade against blown-out highlights: holding white type at 4.5:1 over a\n * near-white region needs ~0.8 alpha of black across the whole plate. A\n * two-layer shadow buys the same local separation for free — a tight 8px pass\n * for edge definition against fine texture, a wide 16px pass for the soft\n * falloff that separates the word from whatever sits behind it. Export-safe:\n * `text-shadow` survives SVG capture, `filter`/`backdrop-filter` do not.\n */\nexport const MEDIA_TEXT_SHADOW =\n  \"0 2px 8px rgba(0,0,0,0.55), 0 6px 16px rgba(0,0,0,0.35)\";\n"
+      "content": "/** Internal monochrome render tokens for cinematic scenes and shared primitives. */\nimport type { TemplateStyle } from \"../template-context\";\n\n// ─── Canonical defaults (the only place these values are defined) ──\n\nexport const TOKEN_DEFAULTS = {\n  /** Primary brand colour — CTA, highlights. */\n  primary: \"#00E5A0\",\n  /** Deepest background surface. */\n  surface: \"#0A0A14\",\n  /** Elevated card / panel surface. */\n  surfaceElevated: \"#14152A\",\n  /** Primary text color. */\n  foreground: \"#FFFFFF\",\n  /** Muted text — labels, footers, supporting copy. */\n  muted: \"#A7A6B0\",\n  /** Primary sans font family (first name of the stack). */\n  font: \"Inter\",\n  /** Script accent font family for handwritten callouts. */\n  scriptFont: \"Caveat\",\n} as const;\n\n/**\n * The canonical template font stack: first family of the resolved brand font, backed by\n * OS-native sans fallbacks that render identically in preview and the\n * SVG-as-image export path.\n */\nexport function fontStack(styleFont: string | undefined): string {\n  return `${(styleFont || \"\").split(\",\")[0].trim() || TOKEN_DEFAULTS.font}, -apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Helvetica, Arial, sans-serif`;\n}\n\n// ─── Resolved tokens ───────────────────────────────────────────────\n\n// ─── Style presets ─────────────────────────────────────────────────\n\n/**\n * Background families a preset can pick. Each resolves to a pure CSS\n * background string in `gradientBackground` — no CSS `filter`, which the\n * SVG export path cannot rasterize.\n */\nexport type BackgroundFamily = \"mesh\" | \"wash\" | \"spotlight\";\n\n/** Title placement a preset defaults to (SceneFrameVariant, minus no-title). */\nexport type PresetTitlePlacement = \"title-top\" | \"title-center\";\n\nexport interface TypeTreatment {\n  /** Added to the computed fontWeight (clamped 100–900). */\n  weightDelta: number;\n  /** Added to the size role's letterSpacing, in em. */\n  trackingDeltaEm: number;\n  /** Multiplies the computed fontSize. */\n  sizeScale: number;\n  /** Applied as CSS text-transform when set. */\n  transform?: \"uppercase\";\n  /**\n   * Multiplies every text-archetype entrance/exit phase duration. Set by\n   * `resolveTokens` from `style.motion`; absent on the raw preset literals,\n   * where it reads as 1.\n   *\n   * It rides on the type treatment because that object is the one channel\n   * that already flows from `style` into text rendering. Pacing of\n   * typographic motion is part of how the type is treated, so this isn't a\n   * smuggled payload.\n   */\n  phaseScale?: number;\n}\n\nexport interface StylePreset {\n  id: string;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  background: BackgroundFamily;\n  titlePlacement: PresetTitlePlacement;\n  type: TypeTreatment;\n}\n\n/**\n * The named looks. `bold` is the default and is a deliberate no-op: a config\n * with no `preset` resolves to it and renders byte-identically to the\n * pre-preset output, so adding presets can't restyle anyone's existing video.\n *\n * Deliberately small. Every preset multiplies the QA surface by every\n * template at both orientations — grow this only when a brief can't be\n * expressed by the ones here.\n */\nexport const STYLE_PRESETS: Record<string, StylePreset> = {\n  bold: {\n    id: \"bold\",\n    useWhen:\n      \"The default. Drifting two-color brand mesh, heavy tight headlines at the top. Launches, hype, product moments — the loudest of the three.\",\n    background: \"mesh\",\n    titlePlacement: \"title-top\",\n    type: { weightDelta: 0, trackingDeltaEm: 0, sizeScale: 1 },\n  },\n  editorial: {\n    id: \"editorial\",\n    useWhen:\n      \"Calm vertical wash, lighter and wider-tracked headlines, centered. Reviews, thoughtful updates, premium or B2B brands — when the copy should feel considered rather than shouted.\",\n    background: \"wash\",\n    titlePlacement: \"title-center\",\n    type: { weightDelta: -200, trackingDeltaEm: 0.01, sizeScale: 1.08 },\n  },\n  stark: {\n    id: \"stark\",\n    useWhen:\n      \"Single hard spotlight on near-black, uppercase and tightly tracked. Dev tools, technical claims, high-contrast statements — maximum weight on very few words.\",\n    background: \"spotlight\",\n    titlePlacement: \"title-top\",\n    type: { weightDelta: 100, trackingDeltaEm: -0.01, sizeScale: 1, transform: \"uppercase\" },\n  },\n};\n\nexport const DEFAULT_PRESET_ID = \"bold\";\nexport const PRESET_IDS = Object.keys(STYLE_PRESETS);\n\n/** Unknown/unset ids fall back to the default rather than throwing — a bad\n *  preset should never be the reason a render fails. */\nexport function resolvePreset(id: string | undefined): StylePreset {\n  return (id && STYLE_PRESETS[id]) || STYLE_PRESETS[DEFAULT_PRESET_ID];\n}\n\n// ─── Density & motion ──────────────────────────────────────────────\n//\n// Two dimensions orthogonal to the named preset. `preset` answers \"which\n// look\"; these answer \"how loud\". Splitting them is what lets \"make the\n// whole video more understated\" be one instruction instead of hand-tuning\n// every scene: they resolve into multipliers on levers that already reach\n// all 28 templates, so no template file knows they exist.\n//\n// Both default to `normal`, whose multipliers are all 1 — a config that sets\n// neither renders byte-identically to the pre-density output. Same invariant\n// the presets hold.\n\nexport type StyleDensity = \"airy\" | \"normal\" | \"packed\";\nexport type StyleMotion = \"calm\" | \"normal\" | \"punchy\";\n\nexport interface DensityScale {\n  id: StyleDensity;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  /** Multiplies the headline font size (via the preset's `type.sizeScale`). */\n  typeScale: number;\n  /** Multiplies the frame's safe-zone insets — bigger insets, more air. */\n  safeZoneScale: number;\n}\n\nexport interface MotionScale {\n  id: StyleMotion;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  /** Multiplies every text-archetype entrance/exit phase duration. */\n  phaseScale: number;\n}\n\nexport const DENSITY_SCALES: Record<StyleDensity, DensityScale> = {\n  airy: {\n    id: \"airy\",\n    useWhen:\n      \"Smaller headlines held further off the frame edges. Premium, considered, editorial — when the copy should have room to breathe.\",\n    typeScale: 0.92,\n    safeZoneScale: 1.3,\n  },\n  normal: {\n    id: \"normal\",\n    useWhen: \"The default. No change to type size or frame padding.\",\n    typeScale: 1,\n    safeZoneScale: 1,\n  },\n  packed: {\n    id: \"packed\",\n    useWhen:\n      \"Bigger headlines pushed closer to the edges. Dense, urgent, information-heavy — when the frame should feel full.\",\n    typeScale: 1.08,\n    safeZoneScale: 0.8,\n  },\n};\n\nexport const MOTION_SCALES: Record<StyleMotion, MotionScale> = {\n  calm: {\n    id: \"calm\",\n    useWhen:\n      \"Slower entrances and exits — text eases in rather than arriving. Founder stories, sober data, anything reflective.\",\n    phaseScale: 1.4,\n  },\n  normal: {\n    id: \"normal\",\n    useWhen: \"The default. Archetype timings as authored.\",\n    phaseScale: 1,\n  },\n  punchy: {\n    id: \"punchy\",\n    useWhen:\n      \"Snappier entrances and exits — text lands fast and clears fast. Hype, launches, hot takes.\",\n    phaseScale: 0.7,\n  },\n};\n\nexport const DEFAULT_DENSITY_ID: StyleDensity = \"normal\";\nexport const DEFAULT_MOTION_ID: StyleMotion = \"normal\";\nexport const DENSITY_IDS = Object.keys(DENSITY_SCALES) as StyleDensity[];\nexport const MOTION_IDS = Object.keys(MOTION_SCALES) as StyleMotion[];\n\n/** Unknown/unset ids fall back to `normal`, same as `resolvePreset`. */\nexport function resolveDensity(id: string | undefined): DensityScale {\n  return (id && DENSITY_SCALES[id as StyleDensity]) || DENSITY_SCALES[DEFAULT_DENSITY_ID];\n}\n\n/** Unknown/unset ids fall back to `normal`, same as `resolvePreset`. */\nexport function resolveMotion(id: string | undefined): MotionScale {\n  return (id && MOTION_SCALES[id as StyleMotion]) || MOTION_SCALES[DEFAULT_MOTION_ID];\n}\n\nexport interface ResolvedTokens {\n  /** Primary brand colour. */\n  primary: string;\n  /** Secondary brand colour. */\n  secondary: string;\n  /** Visual background, deliberately separate from semantic foreground colours. */\n  background: { type: \"solid\"; color: string } | { type: \"gradient\"; colors: [string, string] };\n  /** Deepest background surface. */\n  surface: string;\n  /** Elevated card / panel surface. */\n  surfaceElevated: string;\n  /** Primary foreground colour. */\n  foreground: string;\n  /** Muted text color. */\n  muted: string;\n  /** Full font fallback stack (see fontStack). */\n  font: string;\n  /** Script accent font family. */\n  scriptFont: string;\n  logoUrl?: string;\n  name?: string;\n  /**\n   * Resolved style preset — frame-level look. Always set.\n   *\n   * `preset.type` is the composed treatment, not the raw preset literal:\n   * `sizeScale` already carries the density multiplier and `phaseScale`\n   * carries the motion one, which is how both dials reach text rendering\n   * without a template edit.\n   */\n  preset: StylePreset;\n  /** Resolved density dial. Always set; `normal` when unset. */\n  density: DensityScale;\n  /** Resolved motion dial. Always set; `normal` when unset. */\n  motion: MotionScale;\n}\n\nexport function resolveTokens(\n  style: TemplateStyle,\n): ResolvedTokens {\n\n  // Compose the two dials into the preset's type treatment here, once, so\n  // folding them in at the resolver is what makes them bite everywhere with\n  // no template edits. At `normal`/`normal` both multipliers are 1 and the\n  // object is value-identical to the preset literal.\n  const preset = resolvePreset(style.preset);\n  const density = resolveDensity(style.density);\n  const motion = resolveMotion(style.motion);\n  const composedPreset: StylePreset = {\n    ...preset,\n    type: {\n      ...preset.type,\n      sizeScale: preset.type.sizeScale * density.typeScale,\n      phaseScale: motion.phaseScale,\n    },\n  };\n\n  return {\n    primary: \"#FFFFFF\",\n    secondary: \"#FFFFFF\",\n    background: { type: \"solid\", color: \"#000000\" },\n    surface: \"#000000\",\n    surfaceElevated: \"#171717\",\n    foreground: \"#FFFFFF\",\n    muted: \"#B7B7BC\",\n    font: '-apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Roboto, Arial, sans-serif',\n    scriptFont: \"Georgia\",\n    preset: composedPreset,\n    density,\n    motion,\n  };\n}\n\n// ─── Color math the resolver depends on ────────────────────────────\n// (Lives beside the resolver because theme owns both token resolution and\n// color derivation.)\n\n/**\n * Shift a hex color's hue by a number of degrees.\n * Used by internal template treatments that need a related hue.\n */\nexport function shiftHue(hex: string, degrees: number): string {\n  const r = parseInt(hex.slice(1, 3), 16) / 255;\n  const g = parseInt(hex.slice(3, 5), 16) / 255;\n  const b = parseInt(hex.slice(5, 7), 16) / 255;\n\n  const max = Math.max(r, g, b);\n  const min = Math.min(r, g, b);\n  const d = max - min;\n  const l = (max + min) / 2;\n  let h = 0;\n  let s = 0;\n\n  if (d > 0) {\n    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);\n    if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;\n    else if (max === g) h = ((b - r) / d + 2) / 6;\n    else h = ((r - g) / d + 4) / 6;\n  }\n\n  h = (h + degrees / 360 + 1) % 1;\n\n  const hue2rgb = (p: number, q: number, t: number) => {\n    if (t < 0) t += 1;\n    if (t > 1) t -= 1;\n    if (t < 1 / 6) return p + (q - p) * 6 * t;\n    if (t < 1 / 2) return q;\n    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;\n    return p;\n  };\n\n  let r2: number, g2: number, b2: number;\n  if (s === 0) {\n    r2 = g2 = b2 = l;\n  } else {\n    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;\n    const p = 2 * l - q;\n    r2 = hue2rgb(p, q, h + 1 / 3);\n    g2 = hue2rgb(p, q, h);\n    b2 = hue2rgb(p, q, h - 1 / 3);\n  }\n\n  const toHex = (v: number) =>\n    Math.round(v * 255)\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${toHex(r2)}${toHex(g2)}${toHex(b2)}`;\n}\n\n/** Lighten a hex color by a 0-1 factor. */\n/** Scale a hex color toward black by `factor` (0 = unchanged, 1 = black). */\nexport function darken(hex: string, factor: number): string {\n  if (!hex.startsWith(\"#\") || (hex.length !== 4 && hex.length !== 7)) {\n    return hex;\n  }\n  const full = hex.length === 4\n    ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`\n    : hex;\n  const ch = (i: number) =>\n    Math.max(0, Math.round(parseInt(full.slice(i, i + 2), 16) * (1 - factor)))\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${ch(1)}${ch(3)}${ch(5)}`;\n}\n\nexport function lighten(hex: string, factor: number): string {\n  if (!hex.startsWith(\"#\") || (hex.length !== 4 && hex.length !== 7)) {\n    return hex;\n  }\n  const full = hex.length === 4\n    ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`\n    : hex;\n  const r = parseInt(full.slice(1, 3), 16);\n  const g = parseInt(full.slice(3, 5), 16);\n  const b = parseInt(full.slice(5, 7), 16);\n  const lr = Math.min(255, Math.round(r + (255 - r) * factor));\n  const lg = Math.min(255, Math.round(g + (255 - g) * factor));\n  const lb = Math.min(255, Math.round(b + (255 - b) * factor));\n  return `#${lr.toString(16).padStart(2, \"0\")}${lg.toString(16).padStart(2, \"0\")}${lb.toString(16).padStart(2, \"0\")}`;\n}\n\n/**\n * Per-glyph halo for type sitting directly on photo or video.\n *\n * A frame-wide scrim can only trade picture for contrast, and it loses that\n * trade against blown-out highlights: holding white type at 4.5:1 over a\n * near-white region needs ~0.8 alpha of black across the whole plate. A\n * two-layer shadow buys the same local separation for free — a tight 8px pass\n * for edge definition against fine texture, a wide 16px pass for the soft\n * falloff that separates the word from whatever sits behind it. Export-safe:\n * `text-shadow` survives SVG capture, `filter`/`backdrop-filter` do not.\n */\nexport const MEDIA_TEXT_SHADOW =\n  \"0 2px 8px rgba(0,0,0,0.55), 0 6px 16px rgba(0,0,0,0.35)\";\n"
     }
   ],
   "meta": {

package/starters/video-chat/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@vanillaskyai/video": "0.10.22",
+    "@vanillaskyai/video": "0.10.23",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "@ai-sdk/anthropic": "^3.0.0",

package/docs/maintainers/cinematic-migration.md

@@ -1,38 +0,0 @@
-# Cinematic contract migration
-
-The eight-template replacement is an approved breaking pre-1.0 change. Persisted Video schema is now `0.2`; event protocol is `0.6`.
-
-## Breaking changes
-
-- Removed `VideoInput.brand`, `VideoStyle.brand`, `VideoBrand`, `VideoBrandInput`, `VideoBackground`, and `resolveVideoBrand`. Graphics use black, white/neutral text and system typography. Naturally colored media is unaffected.
-- Removed all 28 old built-in IDs. Eight new IDs describe different schemas: `cinemaMedia`, `chapterTitle`, `focusCards`, `editorialTimeline`, `mobileMessage`, `comparison`, `quote`, `keyFigure`.
-- `parseVideo` rejects the old persisted `0.1` fixture with `unsupported_video_version`. The parser also rejects `style.brand` if a caller merely stamps the new version onto an old object.
-- Scene source intent uses `mediaKeyword` (up to 80 characters) and optional `mediaSource`. The host owns `mediaUrl`, `mediaPoster` and resolved `mediaType`. No gradient fallback mode. Full-bleed requires a resolvable intent or asset; Reach out can remain on black when media is unavailable.
-
-## Adoption
-
-Regenerate videos from the retained source and narration using the new catalog. Do not automatically relabel old IDs: before/after emojis, count-ups and factual quote/stat schemas have different meanings. Retain an older published SDK in a separate legacy playback boundary if historical exports must continue to render; do not pass those payloads into the new parser.
-
-Before (old persisted format):
-
-```json
-{"schemaVersion":"0.1","scenes":[{"id":"one","templateId":"media","variables":{"texts":"A new perspective","mediaType":"gradient"},"timing":{"fixedDuration":4}}],"style":{"brand":{"font":"Inter"}}}
-```
-
-After re-authoring that title as a chapter:
-
-```json
-{"schemaVersion":"0.2","scenes":[{"id":"one","templateId":"chapterTitle","variables":{"title":"A new perspective"},"timing":{"fixedDuration":4}}],"style":{}}
-```
-
-Evidence: persistence tests preserve the untouched old release fixture and assert rejection, accept current-style round trips, reject hidden/non-JSON input as before, and pin new checksums. Template tests cover both orientations, deterministic seeking, exact evidence text and single-decoder backdrop ownership. Final packed consumer and mobile playback checks remain release gates.
-
-## Render fonts
-
-The cinematic templates use `-apple-system, BlinkMacSystemFont, "Helvetica Neue", Roboto, Arial, sans-serif` at regular and medium weights. Apple devices keep native system typography. The existing `@vanillaskyai/video/video-chat.css` entry registers packaged Roboto v51 WOFF2 subsets as the fallback for environments without those fonts. Standalone player and source-owned template integrations should also import that stylesheet. No font is fetched from Google at runtime; browsers fetch local packaged subsets only when Roboto is selected for the rendered glyphs. The font assets include the SIL Open Font License and a source/hash manifest.
-
-Live native fonts and a Linux renderer’s Roboto have slightly different metrics. For repeatable exports, keep the browser, installed fonts, viewport and package version fixed, and await `document.fonts.ready` after mounting the final scene before capturing frames. This is a host export responsibility; the SDK does not add a separate export API or force downloaded fonts onto Apple devices.
-
-## Media-led follow-up
-
-The owner requested removing `focusCards`. Regenerate persisted videos using that ID; migrate parallel explanations to narration over footage rather than another bullet layout. The remaining seven templates retain their IDs. Comparison, quote, key figure and timeline accept optional standard media variables and remain readable on black when assets are absent. No provider callback signatures or host limits change.