@vanillaskyai/video 0.8.8 → 0.9.0

package/registry/items/keyFigure.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "keyFigure",
+  "type": "registry:block",
+  "title": "Key figure",
+  "description": "One supplied figure with one short label on black.",
+  "dependencies": [
+    "react"
+  ],
+  "registryDependencies": [
+    "@vanillasky/template-context",
+    "@vanillasky/theme"
+  ],
+  "files": [
+    {
+      "path": "src/visual-system/scene-templates/key-figure.tsx",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/key-figure.tsx",
+      "content": "import type {SceneTemplateProps} from './types';\nimport {editorialFont,editorialLabel,fade} from './editorial-typography';\n\n/** One supplied figure, shown directly without a count-up that invents intermediate values. */\nfunction KeyFigureScene({variables,width,height,progress,motionProgress=progress,safeZone}:SceneTemplateProps){\n const u=Math.min(width,height),side=Math.max(width*.13,safeZone.left,safeZone.right),available=width-side*2;\n const top=Math.max(height*.16,safeZone.top),bottom=height-Math.max(height*.23,safeZone.bottom),value=String(variables.value??'');\n return <div data-template=\"keyFigure\" style={{position:'absolute',inset:0,background:'#000',color:'#fff',fontFamily:editorialFont,overflow:'hidden'}}>\n  <div style={{position:'absolute',left:side,top:(top+bottom)/2,width:available,transform:'translateY(-50%)',textAlign:'center',opacity:fade((motionProgress-.03)/.22)}}>\n   <div style={{fontSize:Math.min(u*.22,available/Math.max(1,value.length*.6)),fontWeight:500,lineHeight:1.05,letterSpacing:'-.045em',fontVariantNumeric:'tabular-nums'}}>{value}</div>\n   <div style={{...editorialLabel(u),marginTop:u*.045,textWrap:'balance',overflowWrap:'anywhere'}}>{String(variables.label??'')}</div>\n  </div>\n </div>;\n}\n\nexport const KeyFigureSceneTemplate = KeyFigureScene;\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/types.ts",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/types.ts",
+      "content": "/**\n * Scene template types.\n *\n * A template is a reusable React component that defines how a scene looks.\n * It declares the variables an editor or model may provide\n * and receives universal settings as props.\n *\n * Templates are searchable by AI via description, category, jobs, register,\n * and useWhen guidance.\n * The variable schema enables any LLM to fill in template variables via JSON.\n */\n\nimport type { ResolvedTokens } from \"../theme\";\nimport type { SafeZone, TemplateStyle } from \"../template-context\";\n\n/**\n * Props passed to every scene template component.\n *\n * All animation must be driven by `progress` (0→1). No CSS animations,\n * no Framer Motion, no requestAnimationFrame. Use interpolate/spring\n * from animation-utils.ts.\n *\n * Scale factor: use `Math.min(width, height) / 1080` — normalizes to\n * the short edge so visuals are consistent across portrait and landscape.\n */\nexport interface SceneTemplateProps {\n  variables: Record<string, unknown>;\n  style: TemplateStyle;\n  /** 0→1 through the scene's duration */\n  progress: number;\n  /** Presentation clock. Active templates receive the same complete 0→1 timeline as progress. */\n  motionProgress?: number;\n  /** 0→1 beat pulse intensity */\n  beatIntensity: number;\n  /** 1080 (portrait) or 1920 (landscape) */\n  width: number;\n  /** 1920 (portrait) or 1080 (landscape) */\n  height: number;\n  /** Video-level default text effect (for templates that opt in via usesGlobalTextEffect) */\n  textArchetype?: string;\n  /** How text leaves the scene (fade / shrink / pop / blur-scale). Falls back to a sensible default per textArchetype when undefined. */\n  /** Video-level default background effect (for templates that opt in via usesGlobalBackgroundEffect) */\n  backgroundEffect?: string;\n  /** Platform-aware safe zone insets in pixels — use for text placement */\n  safeZone: SafeZone;\n  /** Scene duration in seconds — use for time-based (not progress-based) animations */\n  sceneDuration?: number;\n  /**\n   * Brand tokens already resolved from `style`. Built-in templates import\n   * resolveTokens directly; an ejected `custom_*` scene can't import anything,\n   * so without this it has no way to reach the same values and ends up\n   * hardcoding white, black and shadows — the body then looks generic next to\n   * a frame that IS using the brand.\n   */\n  tokens?: ResolvedTokens;\n  /**\n   * True when the preview player is actively advancing progress; false when paused.\n   * Templates that play HTML5 <video> elements should pause them when this is false.\n   * Undefined (export capture path) is treated as true.\n   */\n  isPlaying?: boolean;\n}\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/editorial-typography.ts",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/editorial-typography.ts",
+      "content": "/** Shared typography for quiet editorial scenes. */\nexport const editorialFont = '-apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Roboto, Arial, sans-serif';\nexport const fade = (value: number) => { const t = Math.max(0, Math.min(1, value)); return t * t * (3 - 2 * t); };\n\nexport const editorialLabel = (unit: number) => ({fontSize:unit*.042,fontWeight:400,color:'#b7b7bc',lineHeight:1.25} as const);\n"
+    }
+  ],
+  "meta": {
+    "vanillasky": {
+      "layer": "template",
+      "tier": "free",
+      "label": "Key figure",
+      "description": "One supplied figure with one short label on black.",
+      "usesGlobalTextEffect": false,
+      "usesGlobalTransition": false,
+      "usesGlobalBackgroundEffect": false,
+      "textCanvas": "tight",
+      "family": "Explainers",
+      "jobs": [
+        "proof"
+      ],
+      "register": "motion-led",
+      "useWhen": "One verified quantity or supplied target anchors the explanation. Value, unit and context must match supplied evidence.",
+      "avoidWhen": "No reliable figure is supplied or multiple values require a chart.",
+      "minDuration": 4,
+      "preferredDuration": 5,
+      "timing": {
+        "contentFields": [
+          "value",
+          "label"
+        ],
+        "contentUnit": "words",
+        "revealSeconds": 0.8,
+        "holdSeconds": 2.5,
+        "exitSeconds": 0
+      },
+      "schema": {
+        "type": "object",
+        "properties": {
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 14,
+            "format": "grounded-stat",
+            "examples": [
+              "42%"
+            ],
+            "description": "One supplied supported quantity, preserving its unit."
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 50,
+            "examples": [
+              "Illustrative example"
+            ],
+            "description": "Exactly one short label identifying the quantity and its context."
+          }
+        },
+        "required": [
+          "value",
+          "label"
+        ],
+        "additionalProperties": false,
+        "x-vanillasky": {
+          "requiresStat": true
+        }
+      }
+    }
+  }
+}

package/registry/items/mobileMessage.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "mobileMessage",
+  "type": "registry:block",
+  "title": "Reach out",
+  "description": "A frosted glass message over resolved media, without sender or timestamp.",
+  "dependencies": [
+    "react"
+  ],
+  "registryDependencies": [
+    "@vanillasky/backgrounds",
+    "@vanillasky/motion",
+    "@vanillasky/template-context",
+    "@vanillasky/theme"
+  ],
+  "files": [
+    {
+      "path": "src/visual-system/scene-templates/mobile-message.tsx",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/mobile-message.tsx",
+      "content": "import type { SceneTemplateProps } from './types';\nimport { spring } from '../motion';\n\nimport {MediaScene} from './cinema-media';\nimport {editorialFont} from './editorial-typography';\n\nconst clamp = (value: number) => Math.max(0, Math.min(1, value));\n\n/** Refines the original floating NotificationCard; the message arrives as one native alert. */\nfunction NotificationScene(props: SceneTemplateProps) {\n  const {variables,progress,motionProgress=progress,sceneDuration=6,width,height,safeZone}=props;\n  const message = String(variables.message ?? '');\n  const app = String(variables.app ?? 'Messages');\n  const unit = Math.min(width, height);\n  const cardWidth = Math.min(width * .88, unit * 1.12, width - safeZone.left - safeZone.right - unit * .06);\n  const inset = unit * .038;\n  const elapsed = clamp(motionProgress) * Math.max(2, Math.min(sceneDuration, 8));\n  const entrance = clamp((elapsed - .18) / .82);\n  const arrival = entrance >= 1 ? 1 : spring(entrance, {damping:22,stiffness:220});\n  const opacity = clamp((elapsed - .18) / .08);\n  const contentWidth = cardWidth - inset * 2;\n  const messageSize = unit * (message.length > 100 ? .038 : .043);\n  const longestWord = Math.max(1, ...message.split(/\\s+/).map(word => word.length));\n  const fittedMessageSize = Math.min(messageSize, contentWidth / (longestWord * .57));\n  const bannerTop = Math.max(safeZone.top, height * .08) + unit * .025;\n  const travel = bannerTop + unit * .65;\n  const iconSize = unit * .049;\n  return <div data-template=\"notification\" style={{position: 'absolute', inset: 0, overflow: 'hidden', background:'var(--vanillasky-template-surface, #000)', fontFamily:editorialFont}}>\n    <MediaScene {...props}/>\n    <div aria-hidden=\"true\" style={{position:\"absolute\",inset:0,background:\"rgba(0,0,0,.16)\"}}/>\n    <div data-notification-card=\"true\" style={{position: 'absolute', left: (width - cardWidth) / 2, top: bannerTop, width: cardWidth, boxSizing: 'border-box', transform: `translateY(${-(1-arrival)*travel}px) scale(${.985+arrival*.015})`, opacity, transformOrigin: '50% 0%', padding: inset, borderRadius: unit * .042, background:'rgba(245,247,250,.64)', backdropFilter:`blur(${unit*.034}px) saturate(135%)`, WebkitBackdropFilter:`blur(${unit*.034}px) saturate(135%)`, border: `${unit * .001}px solid rgba(255,255,255,.72)`, boxShadow:`0 ${unit*.018}px ${unit*.065}px rgba(0,0,0,.2), inset 0 ${unit*.001}px 0 rgba(255,255,255,.8)`, color: '#202025'}}>\n      <div data-notification-header=\"true\" style={{display: 'flex', alignItems: 'center', gap: unit * .014, marginBottom: unit * .024}}>\n        <div style={{width: iconSize, height: iconSize, borderRadius: iconSize * .25, display: 'grid', placeItems: 'center', background: 'linear-gradient(#5bd978, #25b749)', flexShrink: 0}}>\n          <svg viewBox=\"0 0 40 40\" width={iconSize * .78} height={iconSize * .78} aria-hidden=\"true\"><path d=\"M34 18c0 7-6 12-14 12-2 0-4 0-6-1l-7 3 2-7c-2-2-3-4-3-7C6 11 12 6 20 6s14 5 14 12Z\" fill=\"white\" /></svg>\n        </div>\n        <div style={{fontSize: unit * .029, fontWeight: 500, color: '#5b565f', minWidth: 0, overflowWrap: 'anywhere'}}>{app}</div>\n      </div>\n      <div style={{fontSize: fittedMessageSize, lineHeight: 1.26, letterSpacing: '-.016em', overflowWrap: 'anywhere'}}>{message}</div>\n    </div>\n  </div>;\n}\n\nexport const NotificationSceneTemplate = NotificationScene;\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/types.ts",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/types.ts",
+      "content": "/**\n * Scene template types.\n *\n * A template is a reusable React component that defines how a scene looks.\n * It declares the variables an editor or model may provide\n * and receives universal settings as props.\n *\n * Templates are searchable by AI via description, category, jobs, register,\n * and useWhen guidance.\n * The variable schema enables any LLM to fill in template variables via JSON.\n */\n\nimport type { ResolvedTokens } from \"../theme\";\nimport type { SafeZone, TemplateStyle } from \"../template-context\";\n\n/**\n * Props passed to every scene template component.\n *\n * All animation must be driven by `progress` (0→1). No CSS animations,\n * no Framer Motion, no requestAnimationFrame. Use interpolate/spring\n * from animation-utils.ts.\n *\n * Scale factor: use `Math.min(width, height) / 1080` — normalizes to\n * the short edge so visuals are consistent across portrait and landscape.\n */\nexport interface SceneTemplateProps {\n  variables: Record<string, unknown>;\n  style: TemplateStyle;\n  /** 0→1 through the scene's duration */\n  progress: number;\n  /** Presentation clock. Active templates receive the same complete 0→1 timeline as progress. */\n  motionProgress?: number;\n  /** 0→1 beat pulse intensity */\n  beatIntensity: number;\n  /** 1080 (portrait) or 1920 (landscape) */\n  width: number;\n  /** 1920 (portrait) or 1080 (landscape) */\n  height: number;\n  /** Video-level default text effect (for templates that opt in via usesGlobalTextEffect) */\n  textArchetype?: string;\n  /** How text leaves the scene (fade / shrink / pop / blur-scale). Falls back to a sensible default per textArchetype when undefined. */\n  /** Video-level default background effect (for templates that opt in via usesGlobalBackgroundEffect) */\n  backgroundEffect?: string;\n  /** Platform-aware safe zone insets in pixels — use for text placement */\n  safeZone: SafeZone;\n  /** Scene duration in seconds — use for time-based (not progress-based) animations */\n  sceneDuration?: number;\n  /**\n   * Brand tokens already resolved from `style`. Built-in templates import\n   * resolveTokens directly; an ejected `custom_*` scene can't import anything,\n   * so without this it has no way to reach the same values and ends up\n   * hardcoding white, black and shadows — the body then looks generic next to\n   * a frame that IS using the brand.\n   */\n  tokens?: ResolvedTokens;\n  /**\n   * True when the preview player is actively advancing progress; false when paused.\n   * Templates that play HTML5 <video> elements should pause them when this is false.\n   * Undefined (export capture path) is treated as true.\n   */\n  isPlaying?: boolean;\n}\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/cinema-media.tsx",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/cinema-media.tsx",
+      "content": "import type { SceneTemplateProps } from './types';\nimport { SceneBackground, getMediaBackgroundProps } from './scene-background';\n\n/** The shared SDK media plane owns playback, decode readiness, and poster handoff. */\nexport function MediaScene({variables,style,width,height,progress,sceneDuration,isPlaying}:SceneTemplateProps) {\n  return <div data-template=\"cinemaMedia\" style={{width,height,position:'relative',overflow:'hidden'}}>\n    <SceneBackground style={style} width={width} height={height} progress={progress} sceneDuration={sceneDuration} {...getMediaBackgroundProps(variables)} mediaTreatment=\"none\" backgroundEffect=\"none\" isPlaying={isPlaying}/>\n  </div>;\n}\nexport const MediaSceneTemplate = MediaScene;\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/scene-background.tsx",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/scene-background.tsx",
+      "content": "/**\n * Shared photo/video backdrop for built-in and customer-owned templates.\n * Media is host-resolved; this component never searches or generates assets.\n * The base is fixed black. Photos and videos cover it when available, and\n * optional scrims appear only once the media can paint. The cinematic built-ins\n * request no scrim; custom templates can choose a treatment and text anchor.\n * The retained internal \"gradient\" media sentinel selects the black base and\n * ignores mediaUrl. It is not a built-in authoring mode or brand-color control.\n * Video playback can be owned by the player's persistent external backdrop.\n */\n\nimport React, { useEffect, useState } from \"react\";\nimport {\n  hasSceneMedia,\n  resolveMediaType,\n  type ResolvedMediaType,\n} from \"./media-source\";\nimport type { TemplateStyle } from \"../template-context\";\nimport { BrandGradientOverlay } from \"../backgrounds\";\nimport { getBackgroundTransform } from \"../backgrounds\";\nimport { useExternalVideoBackdrop } from \"./external-video-backdrop\";\nimport { resolveMediaPosition, type MediaPosition } from \"./media-position\";\nimport { SceneVideoBackdrop } from \"./scene-video-backdrop\";\n\nexport { hasSceneMedia, resolveMediaType };\nexport { resolveMediaPosition } from \"./media-position\";\nexport { SceneVideoBackdrop } from \"./scene-video-backdrop\";\nexport type { ResolvedMediaType };\n\nexport type { MediaPosition };\nexport type MediaTreatment = \"none\" | \"subtle\" | \"cinematic\" | \"text-safe\";\n\nexport function resolveMediaTreatment(value: string): MediaTreatment {\n  return value === \"none\" || value === \"subtle\" || value === \"text-safe\" ? value : \"cinematic\";\n}\n\nexport interface MediaTreatmentLayer {\n  id: \"vignette\" | \"center-scrim\" | \"bottom-scrim\";\n  background: string;\n  style?: React.CSSProperties;\n}\n\n/**\n * Where the template puts its type. The scrim is shaped to the copy, not to\n * the frame: darkening picture the type never touches costs contrast in the\n * photo and buys no legibility. \"full\" is the conservative default for\n * templates that have not declared an anchor.\n */\nexport type MediaTextAnchor = \"center\" | \"bottom\" | \"full\";\n\n/**\n * Smoothstep-sampled alpha stops between `start`% and `end`% of the gradient\n * box, held at full strength before `start` and after `end`.\n *\n * A two-stop `rgba(0,0,0,a) → transparent` scrim ramps alpha linearly, so it\n * ends with a constant slope. Lateral inhibition in the eye amplifies that\n * slope discontinuity into a visible band — the grey bar cutting across the\n * frame that makes an overlay read as an overlay. Smoothstep flattens the\n * curve at both ends, so the scrim holds where the type sits and then leaves\n * without an edge: the same peak coverage over the copy, noticeably less of\n * the picture spent getting there.\n */\nconst SCRIM_STOP_COUNT = 7;\n\nfunction smoothstep(t: number): number {\n  return t * t * (3 - 2 * t);\n}\n\nfunction easedStops(\n  peakAlpha: number,\n  start: number,\n  end: number,\n  direction: \"fade-out\" | \"fade-in\",\n): string {\n  const alphaAt = (t: number): string => {\n    const eased = direction === \"fade-out\" ? 1 - smoothstep(t) : smoothstep(t);\n    return `rgba(0,0,0,${Number((peakAlpha * eased).toFixed(3))})`;\n  };\n  const stops: string[] = [];\n  if (start > 0) stops.push(`${alphaAt(0)} 0%`);\n  for (let i = 0; i < SCRIM_STOP_COUNT; i += 1) {\n    const t = i / (SCRIM_STOP_COUNT - 1);\n    const position = Number((start + (end - start) * t).toFixed(2));\n    stops.push(`${alphaAt(t)} ${position}%`);\n  }\n  if (end < 100) stops.push(`${alphaAt(1)} 100%`);\n  return stops.join(\", \");\n}\n\n/**\n * Export-safe contrast recipes. Overlays only: SVG capture cannot rely on CSS\n * filters, so a blur-behind-text plate is off the table.\n *\n * The scrims deliberately stop short of solving legibility on their own. A\n * uniform darkening strong enough to carry white type over a blown-out sky\n * needs roughly 0.8 alpha — at that point the photo is a texture, not a\n * picture. The cheaper half of the job belongs to the type: a per-glyph halo\n * (MEDIA_TEXT_SHADOW) buys local contrast exactly where it is needed and\n * costs the image nothing. Scrim for the plate, halo for the glyph.\n */\nexport function getMediaTreatmentLayers(\n  value: string,\n  anchor: MediaTextAnchor = \"full\",\n): MediaTreatmentLayer[] {\n  const treatment = resolveMediaTreatment(value);\n  // Nothing over the picture at all. Every other treatment exists to carry\n  // type across a photograph; where the scene has no type - a generated clip\n  // that is the whole point of the beat - even a vignette is something the\n  // viewer did not ask to look through.\n  if (treatment === \"none\") return [];\n  const vignette: MediaTreatmentLayer = {\n    id: \"vignette\",\n    background:\n      treatment === \"subtle\"\n        ? `radial-gradient(ellipse at center, ${easedStops(0.28, 45, 100, \"fade-in\")})`\n        : `radial-gradient(ellipse at center, ${easedStops(0.72, 32, 100, \"fade-in\")})`,\n  };\n  if (treatment === \"subtle\") return [vignette];\n\n  const textSafe = treatment === \"text-safe\";\n  const layers: MediaTreatmentLayer[] = [vignette];\n\n  if (anchor !== \"bottom\") {\n    layers.push({\n      id: \"center-scrim\",\n      background: textSafe\n        ? `radial-gradient(ellipse 92% 58% at 50% 50%, ${easedStops(0.46, 34, 90, \"fade-out\")})`\n        : `radial-gradient(ellipse 88% 52% at 50% 50%, ${easedStops(0.26, 30, 88, \"fade-out\")})`,\n    });\n  }\n\n  if (anchor !== \"center\") {\n    layers.push({\n      id: \"bottom-scrim\",\n      background: `linear-gradient(to top, ${easedStops(textSafe ? 0.64 : 0.5, 8, 100, \"fade-out\")})`,\n      style: { top: \"55%\" },\n    });\n  }\n\n  return layers;\n}\n\n/**\n * Whether the backdrop is actually painting, which is what decides if a scrim\n * is earned. \"pending\" is a browser-only state: static and export renders\n * never run effects and never wait on a network, so they start (and stay)\n * ready and their output is unchanged.\n */\ntype MediaPaintState = \"pending\" | \"ready\" | \"failed\";\n\nfunction initialMediaPaint(\n  wantsMedia: boolean,\n  resolved: ResolvedMediaType,\n  mediaUrl: string,\n  mediaPoster: string | undefined,\n): MediaPaintState {\n  if (typeof window === \"undefined\") return \"ready\";\n  if (!wantsMedia) return \"ready\";\n  // A poster paints the video's frame immediately, so the scene is already\n  // showing footage even though the stream is still decoding.\n  if (resolved === \"video\") return mediaPoster ? \"ready\" : \"pending\";\n  if (typeof Image === \"undefined\") return \"ready\";\n  // Preloaded or browser-cached media decodes synchronously. Reporting it\n  // ready on the first render keeps the common mid-playback case free of a\n  // black-then-photo flicker.\n  const cached = new Image();\n  cached.src = mediaUrl;\n  return cached.complete && cached.naturalWidth > 0 ? \"ready\" : \"pending\";\n}\n\nexport function getMediaBackgroundProps(variables: Record<string, unknown>) {\n  return {\n    mediaUrl: String(variables.mediaUrl || \"\"),\n    mediaType: String(variables.mediaType || \"auto\"),\n    mediaPoster: String(variables.mediaPoster || \"\"),\n    mediaPosition: String(variables.mediaPosition || \"center\"),\n    mediaTreatment: String(variables.mediaTreatment || \"cinematic\"),\n  };\n}\n\nexport interface SceneBackgroundProps {\n  style: TemplateStyle;\n  progress: number;\n  sceneDuration?: number;\n  width: number;\n  height: number;\n  mediaUrl?: string;\n  mediaType?: string;\n  /** Still image URL shown while the <video> backdrop decodes its first\n   *  frame. Without it the element renders transparent during the\n   *  decode window and the black base shows through. */\n  mediaPoster?: string;\n  /** Cover-crop focal anchor. Keeps the important edge/subject visible. */\n  mediaPosition?: string;\n  /** Overlay recipe: subtle, cinematic, or stronger text-safe contrast. */\n  mediaTreatment?: string;\n  /** Where this template's copy sits, so the scrim is shaped to the type\n   *  instead of to the frame. Defaults to \"full\" (scrim both the middle and\n   *  the lower third) for templates that have not declared an anchor. */\n  textAnchor?: MediaTextAnchor;\n  /** Background motion effect (drift / pulse / Ken Burns). Applied to the photo/video. */\n  backgroundEffect?: string;\n  /** Retained seed input for customer-owned backdrop compositions. */\n  seed?: number | string;\n  /** Pause video when preview is paused. Defaults to true (export path). */\n  isPlaying?: boolean;\n  beatIntensity?: number;\n}\n\nexport const SceneBackground: React.FC<SceneBackgroundProps> = ({\n  style,\n  progress,\n  sceneDuration,\n  width: _width, // accepted for symmetry; not currently used in render\n  height: _height,\n  mediaUrl = \"\",\n  mediaType = \"auto\",\n  mediaPoster,\n  mediaPosition = \"center\",\n  mediaTreatment = \"cinematic\",\n  textAnchor = \"full\",\n  backgroundEffect,\n  seed,\n  isPlaying = true,\n  beatIntensity = 0,\n}) => {\n  void _width;\n  void _height;\n  const resolved = resolveMediaType(mediaType, mediaUrl);\n  const wantsMedia = resolved !== \"gradient\" && !!mediaUrl;\n  const externalVideoBackdrop = useExternalVideoBackdrop();\n  const hasExternalVideoBackdrop = externalVideoBackdrop !== false && resolved === \"video\";\n  const externalVideoFailed = externalVideoBackdrop === \"fallback\" && resolved === \"video\";\n  const externalVideoReady = externalVideoBackdrop === \"ready\" && resolved === \"video\";\n\n  // Apply picture and scrim together. A loading or failed asset keeps the\n  // fixed black base instead of painting contrast treatment over empty media.\n  const [mediaPaint, setMediaPaint] = useState<MediaPaintState>(() =>\n    initialMediaPaint(wantsMedia, resolved, mediaUrl, mediaPoster),\n  );\n  useEffect(() => {\n    setMediaPaint(initialMediaPaint(wantsMedia, resolved, mediaUrl, mediaPoster));\n    // Video reports its own paint through onLoadedData / onError below.\n    if (!wantsMedia || resolved !== \"photo\") return;\n    if (typeof Image === \"undefined\") return;\n    let cancelled = false;\n    const probe = new Image();\n    probe.onload = () => {\n      if (!cancelled) setMediaPaint(\"ready\");\n    };\n    probe.onerror = () => {\n      if (!cancelled) setMediaPaint(\"failed\");\n    };\n    probe.src = mediaUrl;\n    if (probe.complete) setMediaPaint(probe.naturalWidth > 0 ? \"ready\" : \"failed\");\n    return () => {\n      cancelled = true;\n      probe.onload = null;\n      probe.onerror = null;\n    };\n  }, [mediaUrl, mediaPoster, resolved, wantsMedia]);\n\n  // The element stays mounted while pending — that is what loads it. Only a\n  // confirmed failure takes it back out.\n  const showMedia = wantsMedia && mediaPaint !== \"failed\";\n  const showTreatment = wantsMedia && mediaPaint === \"ready\";\n  const resolvedPosition = resolveMediaPosition(mediaPosition);\n  const resolvedTreatment = resolveMediaTreatment(mediaTreatment);\n  const treatmentLayers = getMediaTreatmentLayers(resolvedTreatment, textAnchor);\n\n  const gradSeed =\n    typeof seed === \"number\"\n      ? seed\n      : typeof seed === \"string\"\n        ? seed.split(\"\").reduce((acc, c) => acc + c.charCodeAt(0), 0)\n        : 0;\n\n  const bgTransform = getBackgroundTransform(\n    backgroundEffect,\n    progress,\n    beatIntensity,\n  );\n\n  return (\n    <>\n      {(!hasExternalVideoBackdrop || externalVideoFailed) && (\n        <BrandGradientOverlay\n          style={style}\n          progress={progress}\n          sceneDuration={sceneDuration}\n          seed={gradSeed}\n        />\n      )}\n\n      {showMedia && !hasExternalVideoBackdrop &&\n        (resolved === \"video\" ? (\n          <SceneVideoBackdrop\n            mediaUrl={mediaUrl}\n            mediaPoster={mediaPoster}\n            mediaPosition={mediaPosition}\n            backgroundEffect={backgroundEffect}\n            progress={progress}\n            beatIntensity={beatIntensity}\n            isPlaying={isPlaying}\n            onReady={() => setMediaPaint(\"ready\")}\n            onError={() => setMediaPaint(\"failed\")}\n          />\n        ) : (\n          <div\n            data-media-position={mediaPosition}\n            style={{\n              position: \"absolute\",\n              inset: 0,\n              transform: bgTransform.transform,\n              transformOrigin: bgTransform.transformOrigin,\n              backgroundImage: `url(${mediaUrl})`,\n              backgroundSize: \"cover\",\n              backgroundPosition: resolvedPosition,\n            }}\n          />\n        ))}\n\n      {(hasExternalVideoBackdrop ? externalVideoReady : showTreatment) && !externalVideoFailed &&\n        treatmentLayers.map((layer) => (\n          <div\n            key={layer.id}\n            data-media-treatment={resolvedTreatment}\n            data-media-overlay={layer.id}\n            style={{\n              position: \"absolute\",\n              inset: 0,\n              background: layer.background,\n              pointerEvents: \"none\",\n              ...layer.style,\n            }}\n          />\n        ))}\n    </>\n  );\n};\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/media-source.ts",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/media-source.ts",
+      "content": "/**\n * How a scene's backdrop resolves from its variables. Pure, React-free, and\n * deliberately a leaf module: the player's media preloader shares it so the\n * question \"is this scene backed by a photo, a video, or the brand gradient?\"\n * has exactly one answer in the codebase.\n */\n\nconst VIDEO_EXTENSIONS = [\".mp4\", \".webm\", \".mov\", \".m4v\", \".avi\"];\n\nfunction isVideoUrl(url: string): boolean {\n  try {\n    const pathname = new URL(url).pathname.toLowerCase();\n    return VIDEO_EXTENSIONS.some((ext) => pathname.endsWith(ext));\n  } catch {\n    const lower = url.toLowerCase();\n    return VIDEO_EXTENSIONS.some((ext) => lower.endsWith(ext));\n  }\n}\n\nexport type ResolvedMediaType = \"photo\" | \"video\" | \"gradient\";\n\n/** Apple mobile browsers share WebKit's conservative video-decoder ceiling. */\nexport function limitsConcurrentVideoDecoders(): boolean {\n  if (typeof navigator === \"undefined\") return false;\n  return /iPad|iPhone|iPod/.test(navigator.userAgent) ||\n    (navigator.platform === \"MacIntel\" && navigator.maxTouchPoints > 1);\n}\n\nexport function resolveMediaType(\n  mediaType: string,\n  mediaUrl: string,\n): ResolvedMediaType {\n  if (mediaType === \"gradient\") return \"gradient\";\n  if (mediaType === \"video\") return \"video\";\n  if (mediaType === \"photo\") return \"photo\";\n  // \"auto\" — detect from URL extension\n  return mediaUrl && isVideoUrl(mediaUrl) ? \"video\" : \"photo\";\n}\n\n/**\n * True when the scene actually renders a photo or video backdrop — i.e. a\n * mediaUrl is set and the template has not been pinned to the brand gradient.\n * Templates use it to switch their type onto the media legibility recipe.\n */\nexport function hasSceneMedia(variables: Record<string, unknown>): boolean {\n  return (\n    String(variables.mediaUrl || \"\").trim() !== \"\" &&\n    String(variables.mediaType || \"auto\") !== \"gradient\"\n  );\n}\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/editorial-typography.ts",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/editorial-typography.ts",
+      "content": "/** Shared typography for quiet editorial scenes. */\nexport const editorialFont = '-apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Roboto, Arial, sans-serif';\nexport const fade = (value: number) => { const t = Math.max(0, Math.min(1, value)); return t * t * (3 - 2 * t); };\n\nexport const editorialLabel = (unit: number) => ({fontSize:unit*.042,fontWeight:400,color:'#b7b7bc',lineHeight:1.25} as const);\n"
+    }
+  ],
+  "meta": {
+    "vanillasky": {
+      "layer": "template",
+      "tier": "free",
+      "label": "Reach out",
+      "description": "A frosted glass message over resolved media, without sender or timestamp.",
+      "usesGlobalTextEffect": false,
+      "usesGlobalTransition": false,
+      "usesGlobalBackgroundEffect": false,
+      "textCanvas": "tight",
+      "family": "Social & messaging",
+      "jobs": [
+        "setup"
+      ],
+      "register": "card-led",
+      "useWhen": "A person or organization reaches out with a short message, alert or invitation. Message must be supplied or explicitly illustrative.",
+      "avoidWhen": "The scene is a generic fact, a long exchange, or a message that would fabricate evidence.",
+      "minDuration": 4,
+      "preferredDuration": 6,
+      "timing": {
+        "contentFields": [
+          "message",
+          "app"
+        ],
+        "contentUnit": "words",
+        "revealSeconds": 1,
+        "holdSeconds": 2.2,
+        "exitSeconds": 0
+      },
+      "schema": {
+        "type": "object",
+        "properties": {
+          "mediaKeyword": {
+            "type": "string",
+            "format": "stock-media-keyword",
+            "minLength": 1,
+            "maxLength": 80,
+            "description": "2–8 word literal subject/action search intent, maximum 80 characters. Host resolves URLs.",
+            "examples": [
+              "Ocean waves breaking on a rocky shore"
+            ]
+          },
+          "mediaUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Host-only approved photo or video URL.",
+            "default": ""
+          },
+          "mediaType": {
+            "type": "string",
+            "enum": [
+              "photo",
+              "video"
+            ],
+            "default": "video",
+            "description": "Host-resolved asset kind."
+          },
+          "mediaPoster": {
+            "type": "string",
+            "format": "uri",
+            "description": "Host-only approved poster URL for video decoding.",
+            "default": ""
+          },
+          "message": {
+            "type": "string",
+            "maxLength": 120,
+            "default": "Can we talk?",
+            "description": "Exact supplied or explicitly illustrative message, preferably 6–16 words."
+          },
+          "app": {
+            "type": "string",
+            "maxLength": 24,
+            "default": "Messages",
+            "description": "Optional app label; Messages is the visual default."
+          },
+          "shotDirection": {
+            "type": "string",
+            "maxLength": 220,
+            "description": "Optional action, framing and continuity for generation. Preserve the subject; do not request rendered text."
+          },
+          "mediaSource": {
+            "type": "string",
+            "enum": [
+              "generate",
+              "stock"
+            ],
+            "description": "Generate distinctive illustrative shots; use approved stock for familiar observable subjects."
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "additionalProperties": false,
+        "x-vanillasky": {
+          "allowsStockMedia": true
+        }
+      }
+    }
+  }
+}

package/registry/items/quote.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "quote",
+  "type": "registry:block",
+  "title": "Quote",
+  "description": "A short exact quotation with a legible attribution on black.",
+  "dependencies": [
+    "react"
+  ],
+  "registryDependencies": [
+    "@vanillasky/template-context",
+    "@vanillasky/theme"
+  ],
+  "files": [
+    {
+      "path": "src/visual-system/scene-templates/quote.tsx",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/quote.tsx",
+      "content": "import type {SceneTemplateProps} from './types';\nimport {editorialFont,fade} from './editorial-typography';\n\n/** Exact words with a readable attribution; no decorative oversized quotation mark. */\nfunction QuoteScene({variables,width,height,progress,motionProgress=progress,safeZone}:SceneTemplateProps){\n const u=Math.min(width,height),top=Math.max(height*.16,safeZone.top),bottom=height-Math.max(height*.23,safeZone.bottom);\n const side=Math.max(width*.13,safeZone.left,safeZone.right);\n return <div data-template=\"quote\" style={{position:'absolute',inset:0,background:'#000',color:'#fff',fontFamily:editorialFont,overflow:'hidden'}}>\n  <div style={{position:'absolute',left:side,top:(top+bottom)/2,width:width-side*2,transform:'translateY(-50%)',textAlign:'center',opacity:fade((motionProgress-.03)/.24)}}>\n   <div style={{fontSize:u*.067,fontWeight:500,lineHeight:1.25,letterSpacing:'-.025em',textWrap:'balance',overflowWrap:'anywhere'}}>“{String(variables.quote??'')}”</div>\n   <div style={{fontSize:u*.041,fontWeight:400,color:'#b7b7bc',lineHeight:1.3,marginTop:u*.065,textWrap:'balance',overflowWrap:'anywhere'}}>{String(variables.attribution??'')}</div>\n  </div>\n </div>;\n}\n\nexport const QuoteSceneTemplate = QuoteScene;\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/types.ts",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/types.ts",
+      "content": "/**\n * Scene template types.\n *\n * A template is a reusable React component that defines how a scene looks.\n * It declares the variables an editor or model may provide\n * and receives universal settings as props.\n *\n * Templates are searchable by AI via description, category, jobs, register,\n * and useWhen guidance.\n * The variable schema enables any LLM to fill in template variables via JSON.\n */\n\nimport type { ResolvedTokens } from \"../theme\";\nimport type { SafeZone, TemplateStyle } from \"../template-context\";\n\n/**\n * Props passed to every scene template component.\n *\n * All animation must be driven by `progress` (0→1). No CSS animations,\n * no Framer Motion, no requestAnimationFrame. Use interpolate/spring\n * from animation-utils.ts.\n *\n * Scale factor: use `Math.min(width, height) / 1080` — normalizes to\n * the short edge so visuals are consistent across portrait and landscape.\n */\nexport interface SceneTemplateProps {\n  variables: Record<string, unknown>;\n  style: TemplateStyle;\n  /** 0→1 through the scene's duration */\n  progress: number;\n  /** Presentation clock. Active templates receive the same complete 0→1 timeline as progress. */\n  motionProgress?: number;\n  /** 0→1 beat pulse intensity */\n  beatIntensity: number;\n  /** 1080 (portrait) or 1920 (landscape) */\n  width: number;\n  /** 1920 (portrait) or 1080 (landscape) */\n  height: number;\n  /** Video-level default text effect (for templates that opt in via usesGlobalTextEffect) */\n  textArchetype?: string;\n  /** How text leaves the scene (fade / shrink / pop / blur-scale). Falls back to a sensible default per textArchetype when undefined. */\n  /** Video-level default background effect (for templates that opt in via usesGlobalBackgroundEffect) */\n  backgroundEffect?: string;\n  /** Platform-aware safe zone insets in pixels — use for text placement */\n  safeZone: SafeZone;\n  /** Scene duration in seconds — use for time-based (not progress-based) animations */\n  sceneDuration?: number;\n  /**\n   * Brand tokens already resolved from `style`. Built-in templates import\n   * resolveTokens directly; an ejected `custom_*` scene can't import anything,\n   * so without this it has no way to reach the same values and ends up\n   * hardcoding white, black and shadows — the body then looks generic next to\n   * a frame that IS using the brand.\n   */\n  tokens?: ResolvedTokens;\n  /**\n   * True when the preview player is actively advancing progress; false when paused.\n   * Templates that play HTML5 <video> elements should pause them when this is false.\n   * Undefined (export capture path) is treated as true.\n   */\n  isPlaying?: boolean;\n}\n"
+    },
+    {
+      "path": "src/visual-system/scene-templates/editorial-typography.ts",
+      "type": "registry:component",
+      "target": "vanillasky/scene-templates/editorial-typography.ts",
+      "content": "/** Shared typography for quiet editorial scenes. */\nexport const editorialFont = '-apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Roboto, Arial, sans-serif';\nexport const fade = (value: number) => { const t = Math.max(0, Math.min(1, value)); return t * t * (3 - 2 * t); };\n\nexport const editorialLabel = (unit: number) => ({fontSize:unit*.042,fontWeight:400,color:'#b7b7bc',lineHeight:1.25} as const);\n"
+    }
+  ],
+  "meta": {
+    "vanillasky": {
+      "layer": "template",
+      "tier": "free",
+      "label": "Quote",
+      "description": "A short exact quotation with a legible attribution on black.",
+      "usesGlobalTextEffect": false,
+      "usesGlobalTransition": false,
+      "usesGlobalBackgroundEffect": false,
+      "textCanvas": "tight",
+      "family": "Explainers",
+      "jobs": [
+        "proof"
+      ],
+      "register": "motion-led",
+      "useWhen": "A supplied quotation deserves its own moment. Use exact source words and attribution only.",
+      "avoidWhen": "No exact quotation or reliable attribution is supplied; never invent testimony.",
+      "minDuration": 5,
+      "preferredDuration": 7,
+      "timing": {
+        "contentFields": [
+          "quote",
+          "attribution"
+        ],
+        "contentUnit": "words",
+        "revealSeconds": 1.2,
+        "holdSeconds": 3,
+        "exitSeconds": 0
+      },
+      "schema": {
+        "type": "object",
+        "properties": {
+          "quote": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 140,
+            "format": "grounded-quote",
+            "examples": [
+              "Look closely. There is always more to see."
+            ],
+            "description": "Exact supplied quotation; do not paraphrase or invent."
+          },
+          "attribution": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 60,
+            "examples": [
+              "Illustrative example"
+            ],
+            "description": "Grounded attribution belonging to these exact quoted words."
+          }
+        },
+        "required": [
+          "quote",
+          "attribution"
+        ],
+        "additionalProperties": false
+      }
+    }
+  }
+}

package/registry/items/template-context.json

@@ -9,7 +9,7 @@
       "path": "src/visual-system/template-context.ts",
       "type": "registry:lib",
       "target": "vanillasky/template-context.ts",
-      "content": "/** Shared render context for built-in and project-owned scene templates. */\nexport interface TemplateStyle {\n  brand: {\n    name?: string;\n    logoUrl?: string;\n    font: string;\n    scriptFont: string;\n    background:\n      | { type: \"solid\"; color: string }\n      | { type: \"gradient\"; colors: [string, string] };\n    colors: {\n      primary: string;\n      secondary: string;\n      foreground: string;\n      surface: string;\n      surfaceElevated: string;\n      muted: string;\n    };\n  };\n  preset?: string;\n  density?: string;\n  motion?: string;\n  defaultTextArchetype?: string;\n  defaultTransition?: string;\n  defaultBackgroundEffect?: string;\n}\n\nexport interface SafeZone {\n  top: number;\n  bottom: number;\n  left: number;\n  right: number;\n}\n"
+      "content": "/** Shared render context for built-in and project-owned scene templates. */\nexport interface TemplateStyle {\n  preset?: string;\n  density?: string;\n  motion?: string;\n  defaultTextArchetype?: string;\n  defaultTransition?: string;\n  defaultBackgroundEffect?: string;\n}\n\nexport interface SafeZone {\n  top: number;\n  bottom: number;\n  left: number;\n  right: number;\n}\n"
     }
   ],
   "meta": {

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": "/**\n * Template-token adapter for an already-resolved semantic video brand.\n *\n * Before this module the default brand was defined in 19+ places with three\n * different answers (17 templates hardcoded \"#00e5a0\", milestone used\n * \"#3b82f6\", tweet hashes the author name), the font-stack idiom was\n * copy-pasted in 22 files, and shiftHue(accent, 50) was re-derived in 14.\n * Every fallback now lives here, exactly once.\n *\n * `deriveBrandContext` (src/visual-system/primitives/brand-context.ts) delegates to\n * this resolver, so templates and primitives can never drift.\n *\n * Documented divergences that stay OUTSIDE the canonical fallbacks:\n *  - social-tweet derives a per-author hue when no brand accent is set —\n *    an intentional feature, routed through `accentFallback`.\n *  - Platform-look templates (incoming-call, social-conversation,\n *    social-notification, brand-message) keep their OS/system font stacks;\n *    they imitate iOS/WhatsApp/X chrome, not the brand.\n */\n\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: TemplateStyle[\"brand\"][\"background\"];\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  const brand = style.brand;\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: brand.colors.primary,\n    secondary: brand.colors.secondary,\n    background: brand.background,\n    surface: brand.colors.surface,\n    surfaceElevated: brand.colors.surfaceElevated,\n    foreground: brand.colors.foreground,\n    muted: brand.colors.muted,\n    font: fontStack(brand.font),\n    scriptFont: brand.scriptFont,\n    logoUrl: brand.logoUrl,\n    name: brand.name,\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 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"
     }
   ],
   "meta": {

package/starters/video-chat/README.md

@@ -43,32 +43,30 @@ Restart the development server after changing keys. Open
 
 ## How a response is made
 
-1. The planner streams one 6-9 word spoken hook, then continues into the scenes
-   without starting a second model call.
-2. A clicked welcome card starts its prewritten hook and loaded footage
-   immediately; a typed prompt resolves the streamed keyword through the
-   optional stock provider.
-3. The SDK speaks that hook while the same model continues planning the visual
-   response. In full AI mode, the first streamed object also reserves the exact
-   first generated shot so it can render while scenes two through five arrive.
-4. The opening footage loops or holds until the first planned scene and its
-   voice are ready, then the response timeline takes over without a blank gap.
-5. The SDK holds every planned scene for its measured or estimated speech time
-   and loads possible next prompts independently after the response completes.
-
-The text model is the only required provider. Generated speech, transcription,
-stock media, and generated video are independent upgrades and never prevent a
-template response from completing.
-
-## Visual modes
-
-The templates mode is always available. Full AI video appears only when a
-video provider is configured.
-
-| Mode | Generated scenes | Cost profile |
-| --- | ---: | --- |
-| Templates only | 0 | Rendered locally |
-| Full AI video | 5 | Every beat generated |
+The planner streams a short spoken hook, then complete narrated scenes. When a
+generated provider is configured, an early shot can start generating while the
+rest of the story is planned. The director chooses footage or one of eight
+editorial templates for each beat; there is one cinematic mode.
+
+Playback starts after a contiguous preparation cushion, or after a shorter
+complete response is ready. Media is decoded before use. At a late video cut,
+the player holds its clock and narration until a usable frame appears, with a
+bounded error path. The first hook can play during preparation.
+
+`mediaSource: "generate"` requests a distinctive illustrative shot;
+`mediaSource: "stock"` requests approved footage. Generation attempts, including
+failures, share the host's `maxGeneratedVideos` ceiling. A stock miss never
+broadens the subject automatically. A failed full-bleed scene uses its grounded
+`fallbackText` as a chapter card.
+
+## Reviewed stock
+
+The starter's `approvedStock` index in `stock.ts` is deliberately empty. Add an
+asset only after inspecting its content, poster and allowed orientations. List
+literal matching queries and a reviewed description. Add those available
+queries to your host instructions so the planner can choose them when relevant.
+An unreviewed query returns `null` without a network search or unrelated result.
+The host owns licensing, storage, clip rendition and retention.
 
 The provider names its own model. Override the tested defaults with
 `ANTHROPIC_PLANNER_MODEL`, `ANTHROPIC_NARRATION_MODEL`, or `FAL_VIDEO_MODEL`

package/starters/video-chat/package.json

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

package/starters/video-chat/providers/video.ts

@@ -8,16 +8,17 @@ async function filmScene(
   generatedLook: string | undefined,
   orientation: "portrait" | "landscape",
   signal: AbortSignal,
+  shotDirection?: string,
 ) {
   fal.config({ credentials: process.env.FAL_KEY });
   const started = Date.now();
-  console.log(`[video-chat] filming: ${subject.slice(0, 70)}`);
   try {
     const result = await fal.subscribe(VIDEO_MODEL, {
       input: {
         prompt: [
-          `Locked-off shot, ${orientation === "portrait" ? "9:16 vertical" : "16:9"}. ${subject}.`,
-          "One slow continuous camera move. Physically plausible motion.",
+          `Cinematic shot, ${orientation === "portrait" ? "9:16 vertical" : "16:9"}. ${subject}.`,
+          "Use a steady composition or one restrained camera move. Physically plausible motion.",
+          shotDirection,
           "No on-screen text, captions, subtitles, watermarks or logos.",
           "Diegetic sound only. No music, no voiceover.",
           generatedLook,
@@ -44,8 +45,8 @@ async function filmScene(
 /** Optional generated video and transcription; credentials remain server-only. */
 export const videoProvider: Pick<VideoChatHandlerOptions, "generateVideo" | "transcribe"> = {
   generateVideo: process.env.FAL_KEY
-    ? async (query, { generatedLook, orientation, signal }) => ({
-        url: await filmScene(query, generatedLook, orientation, signal),
+    ? async (query, { generatedLook, orientation, signal, scene }) => ({
+        url: await filmScene(query, generatedLook, orientation, signal, typeof scene?.variables.shotDirection === "string" ? scene.variables.shotDirection : undefined),
         type: "video" as const,
       })
     : undefined,