@plaintake/scenario 1.9.0 → 1.10.0

package/dist/index.js

@@ -543,6 +543,7 @@ var SpeechSchema = z5.object({
   message: "engine must be recorded whenever any clip was synthesised",
   path: ["engine"]
 });
+var ThemeSchema = z5.object({ accentColor: HEX_COLOUR });
 var RENDER_PLAN_SCHEMA = "agent-demo.render/v1";
 var RenderPlanSchema = z5.object({
   schema: z5.literal(RENDER_PLAN_SCHEMA),
@@ -730,6 +731,31 @@ var RenderPlanSchema = z5.object({
   camera: CameraSchema.optional(),
   highlight: HighlightSchema.optional(),
   speech: SpeechSchema.optional(),
+  /**
+   * The branding decision, resolved once from the licence and configuration at run time
+   * and frozen whole — the accent the cursor's fill, its click-ripple ring and the
+   * highlight label's text all draw. See `ThemeSchema`.
+   *
+   * Optional and **never defaulted**. The plan's own JSON is a weaker claim than the
+   * render — the schema doc above records how a Zod `.default()` materialises on parse,
+   * so `stableStringify` writes the field into `render/render-plan.json` and diverges the
+   * committed golden plan, which is what `style`'s defaults already did once. A default
+   * here would do it again on every parse; absent means off, and the object appears only
+   * when a theme was actually resolved.
+   *
+   * Top-level — a sibling of `intro`/`outro`/`cursor`/`highlight`, not a key inside one
+   * of them — so `recutPlan`'s `{...plan}` spread carries it through `--aspect` re-cuts
+   * unchanged; a nested key would need explicit handling there.
+   *
+   * The plan is not `.strict()`, so an older binary strips a `theme` it has never heard
+   * of — but a plain re-render is unaffected by that: `renderBundle` executes the frozen
+   * themed `cursor.ass`/`highlight.ass` verbatim and never regenerates them, exactly as
+   * an older build ignoring `speech` still muxes the frozen WAV. The hardcoded colours
+   * return only where derived files are *redrawn* — a fresh freeze, or a `render
+   * --aspect` re-cut, whose `writeCaptions(recut)` regenerates the tracks from a plan the
+   * older binary's own re-parse has stripped `theme` out of.
+   */
+  theme: ThemeSchema.optional(),
   /**
    * The capture timeline cut into windows — of a genuine multi-actor cast, of an implicit
    * single actor pausing for explain cut-aways, or both at once. `segments` is the one

package/dist/schema/render-plan.d.ts

@@ -296,9 +296,11 @@ export declare const TRANSITION_CARD_DEFAULT_MS = 3000;
  * to be a pure function of the plan, so the rect a step measured has to survive plan freeze
  * as a rect, not merely as a decision to draw one.
  *
- * `startMs`/`endMs` bound the whole step, not a retimed lead/rest/glide the way a cursor
- * point is — a spotlight has no motion to choreograph, so unlike `CursorPointSchema` there is
- * nothing here to pull earlier or hold open.
+ * `startMs`/`endMs` carry a window the derivation already retimed, the way a cursor point's
+ * do: a click's brackets the press — opening when the pointer parks and closing as the click
+ * ripple ends — while a continuous action's spans its whole step. The times are frozen as
+ * computed, so unlike `CursorPointSchema` (whose `rippleMs` the emitter re-derives fades
+ * around) there is no further choreography left for the render to do.
  *
  * `label` is the optional callout text a scenario may attach (`highlight: { label: '...' }`).
  * Absent means the spotlight alone, exactly what `highlight: true` (no object) asks for.
@@ -457,6 +459,54 @@ export type IntroInput = Omit<Intro, 'assPath'>;
  * position in the array against the schema's own `captions/turn-[0-9]+\.ass` family.
  */
 export type TransitionCardInput = Omit<TransitionCard, 'assPath'>;
+/**
+ * The brand accent: one colour shared by the cursor's fill, its click-ripple ring and the
+ * highlight label's text. One field rather than one per consumer, because the cursor and
+ * the highlight should never disagree about the brand — the same "one block, one decision"
+ * shape as every other optional capability on the plan.
+ *
+ * Present only when a theme actually resolved — Pro tier, branding enabled, at least one
+ * colour named. Absent means every hardcoded colour the emitters already draw, so
+ * an unbranded run's `cursor.ass`/`highlight.ass` are exactly what they always were.
+ * Caption colours deliberately do not live here: `RenderPlanSchema.style` already carries
+ * `textColor`/`outlineColor`/`boxColor` as the single source of `captions/captions.ass`,
+ * and theming captions is a change to what gets frozen into those, not a second place a
+ * colour can hide.
+ *
+ * `accentColor` is `HEX_COLOUR` for the reason every plan colour is: the value reaches
+ * `assColour` and from there an ASS override tag, and `#RRGGBB` admits no ASS
+ * metacharacter. It is stored in the form the author wrote and converted to `&HAABBGGRR`
+ * only at emission, so the bundle shows the colour, not its encoding.
+ *
+ * Like the inputs above, this is the decision as the application layer supplies it — but
+ * it is the narrow end of a wider input: `buildRenderPlan` takes the four-field
+ * `ThemeInput` below and freezes only the accent here, because the caption colours have
+ * somewhere else to go.
+ */
+export declare const ThemeSchema: z.ZodObject<{
+    accentColor: z.ZodString;
+}, z.core.$strip>;
+export type Theme = z.infer<typeof ThemeSchema>;
+/**
+ * The theme decision as the application layer supplies it — all four colours a licence can
+ * resolve, in the same shape `@plaintake/license`'s `resolveTheme` returns, exactly as
+ * `OutroInput`/`IntroInput` are the shapes its other resolvers return. Only the fields the
+ * user actually configured appear; each absent field keeps the hardcoded default at the
+ * freeze, so recolouring `accentColor` alone is a complete theme.
+ *
+ * Wider than `ThemeSchema` on purpose. The plan-level block carries only `accentColor`
+ * because the three caption colours freeze into `RenderPlanSchema.style` — the single
+ * source `captions.ass` already reads — while the accent has no style field to freeze
+ * into and needs the plan key. A theme with no accent therefore freezes no `theme` key at
+ * all: the schema requires one, and defaulting it would recolour cursor surfaces the
+ * author never asked about.
+ */
+export type ThemeInput = {
+    accentColor?: string | undefined;
+    captionTextColor?: string | undefined;
+    captionOutlineColor?: string | undefined;
+    captionBoxColor?: string | undefined;
+};
 /**
  * The one value a plan's `schema` field ever holds.
  *
@@ -663,6 +713,9 @@ export declare const RenderPlanSchema: z.ZodObject<{
             voice: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    theme: z.ZodOptional<z.ZodObject<{
+        accentColor: z.ZodString;
+    }, z.core.$strip>>;
     actors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaintake/scenario",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Authoring SDK for PlainTake demo scenarios: defineDemo and the scenario DSL types. Install for editor autocomplete; the PlainTake binary ships a runtime fallback.",
   "license": "MIT",
   "type": "module",