Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat: preview captions and text overlays from a generated form

rponef7c16897bf49
diff --git a/test/playground-preview.test.ts b/test/playground-preview.test.ts
new file mode 100644
index 00000000..85803702
--- /dev/null
+++ b/test/playground-preview.test.ts
@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { assertHyperframesDocument, compileHyperframesDocument } from "@narratage/hyperframes";
+import { sealComposition } from "@narratage/composition";
+import { sealProgramSpace } from "@narratage/program-space";
+
+import { REGISTRY, matchRecipe } from "../tools/playground/src/registry/index.js";
+
+/**
+ * Every adapter, through the whole compiler path it will run in the browser.
+ *
+ * The playground has no schema validator by design — the packages' own seal and
+ * assert functions are the judge. That makes this the test that matters: if an
+ * adapter's defaults cannot reach a legal HyperFrames document here, the
+ * playground cannot show it there.
+ */
+
+const programSpace = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 4,
+ frameRate: { numerator: 30, denominator: 1 },
+});
+const canvas = { width: 1080, height: 1920, clearColor: "#09090b" };
+
+for (const component of REGISTRY) {
+ test(`${component.id} compiles its defaults into a legal document`, () => {
+ const { parameters, content } = component.defaults();
+ const tracks = component.build({ parameters, content, programSpace, canvas });
+ assert.ok(tracks.length > 0, "an adapter must contribute at least one Track");
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id: component.id,
+ canvas,
+ tracks,
+ }), programSpace);
+ assert.doesNotThrow(() => assertHyperframesDocument(document));
+ assert.match(document.html, /class="clip svml-visual-present"/u);
+ });
+
+ test(`${component.id} survives a duration shorter than its content`, () => {
+ // Dragging the duration down must clamp spans, not throw: the Presents an
+ // adapter derives from seconds would otherwise fall outside the program.
+ const short = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 0.5,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+ const { parameters, content } = component.defaults();
+ assert.doesNotThrow(() => {
+ compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id: component.id,
+ canvas,
+ tracks: component.build({ parameters, content, programSpace: short, canvas }),
+ }), short);
+ });
+ });
+}
+
+test("a Recipe is matched by its exact property key set, not its path prefix", () => {
+ const caption = REGISTRY.find((component) => component.id === "caption")!;
+ const properties = Object.fromEntries((caption.recipeKeys ?? []).map((key) => [key, "0"]));
+ assert.equal(matchRecipe(properties)?.id, "caption");
+
+ // caption.short-cues shares the prefix and is a different shape entirely.
+ assert.equal(matchRecipe({ model: "x", "max-words": 6, "max-lines": 2 }), undefined);
+ // A near miss is a miss: one extra key means a different contract.
+ assert.equal(matchRecipe({ ...properties, extra: 1 }), undefined);
+});
+
+test("filling from a Recipe leaves no parameter unset", () => {
+ // The bug this catches is a Recipe key that gains a mapping in the schema but
+ // not in fromRecipe, which would silently hand the form an undefined field.
+ for (const component of REGISTRY) {
+ if (component.recipeKeys === undefined) continue;
+ assert.equal(typeof component.fromRecipe, "function",
+ `${component.id} declares recipeKeys so it must accept a Recipe`);
+ const properties = Object.fromEntries(component.recipeKeys.map((key) => [key, "0"]));
+ const filled = component.fromRecipe!(properties) as Record<string, unknown>;
+ const declared = component.parameters.kind === "object"
+ ? Object.keys(component.parameters.fields)
+ : [];
+ for (const name of declared) {
+ assert.notEqual(filled[name], undefined,
+ `${component.id}.fromRecipe left ${name} unset`);
+ }
+ }
+});
+
+/** Verbatim from examples/talking-film-golden/studio.svs. */
+const GOLDEN: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+ caption: {
+ "stack-order": "70", x: "0.08", y: "0.76", width: "0.84",
+ font: "inter-semibold", weight: "600", size: "58", "line-height": "0.96",
+ align: "center", fill: "#FFFFFF", background: "#09090BCC",
+ padding: "16 24", radius: "18",
+ },
+ "text-track": {
+ "stack-order": "90", x: "0.08", y: "0.12", width: "0.84", height: "0.2",
+ font: "inter-black", weight: "800", size: "96", tracking: "-2",
+ align: "left", fill: "#FFFFFF",
+ },
+};
+
+test("a real Recipe renders through the component it describes", () => {
+ for (const [id, properties] of Object.entries(GOLDEN)) {
+ const component = REGISTRY.find((entry) => entry.id === id)!;
+ assert.deepEqual(
+ Object.keys(properties).sort(),
+ [...(component.recipeKeys ?? [])].sort(),
+ `the ${id} fixture must carry exactly the Recipe's keys`,
+ );
+ assert.equal(matchRecipe(properties)?.id, id);
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id,
+ canvas,
+ tracks: component.build({
+ parameters: component.fromRecipe!(properties),
+ content: component.defaults().content,
+ programSpace,
+ canvas,
+ }),
+ }), programSpace);
+ assert.doesNotThrow(() => assertHyperframesDocument(document));
+ }
+});
+
+test("padding carries y first, and one value covers both axes", () => {
+ const caption = REGISTRY.find((entry) => entry.id === "caption")!;
+ const of = (padding: string) => caption.fromRecipe!({
+ ...GOLDEN["caption"]!, padding,
+ }) as Record<string, unknown>;
+ assert.deepEqual([of("16 24")["paddingY"], of("16 24")["paddingX"]], [16, 24]);
+ assert.deepEqual([of("12")["paddingY"], of("12")["paddingX"]], [12, 12]);
+});
diff --git a/tools/playground-registry.test.mjs b/tools/playground-registry.test.mjs
new file mode 100644
index 00000000..516e0fac
--- /dev/null
+++ b/tools/playground-registry.test.mjs
@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { REGISTRY } from "./playground/src/registry/index.ts";
+
+/**
+ * The playground copies each component's SVS Recipe key set, because the
+ * compiler states it only as a literal inside its Surface handler and there is
+ * no shared declaration to import yet.
+ *
+ * A copy that can drift silently is worse than no copy: the playground would
+ * quietly stop matching a Recipe it still claims to preview. This reads the
+ * literal back out of the Surface source and pins the two together, so adding a
+ * property to a Recipe breaks the build until the playground follows.
+ *
+ * Delete this once the key sets move into the packages' manifests and the
+ * playground can import them.
+ */
+
+const SURFACES = {
+ caption: "../packages/caption/src/surface.ts",
+ "text-track": "../packages/text-track/src/surface.ts",
+};
+
+/** Pulls the `expected` array literal a Surface compares Recipe keys against. */
+function declaredKeys(source) {
+ const found = /const expected = \[([^\]]*)\]/u.exec(source);
+ assert.notEqual(found, null, "the Surface must declare an expected Recipe key list");
+ return [...found[1].matchAll(/"([^"]+)"/gu)].map((match) => match[1]).sort();
+}
+
+for (const [id, relative] of Object.entries(SURFACES)) {
+ test(`the ${id} Recipe key set matches its Surface`, () => {
+ const source = readFileSync(fileURLToPath(new URL(relative, import.meta.url)), "utf8");
+ const component = REGISTRY.find((entry) => entry.id === id);
+ assert.notEqual(component, undefined, `the registry must carry ${id}`);
+ assert.deepEqual(
+ [...component.recipeKeys].sort(),
+ declaredKeys(source),
+ `${id} drifted from ${relative}; update tools/playground/src/registry/${id}.ts`,
+ );
+ });
+}
+
+test("no two components claim the same Recipe shape", () => {
+ const seen = new Map();
+ for (const component of REGISTRY) {
+ if (component.recipeKeys === undefined) continue;
+ const key = [...component.recipeKeys].sort().join(" ");
+ assert.equal(seen.get(key), undefined,
+ `${component.id} and ${seen.get(key)} match the same Recipe, so discovery would be arbitrary`);
+ seen.set(key, component.id);
+ }
+});
diff --git a/tools/playground/src/main.ts b/tools/playground/src/main.ts
index 38f3216e..03f7c865 100644
--- a/tools/playground/src/main.ts
+++ b/tools/playground/src/main.ts
@@ -1,114 +1,3 @@
-import { renderPreview } from "./preview/render.js";
-import { sealProgramSpace, sealVisualTrack } from "./svml.js";
-import type { ProgramSpace, Track, VisualElement } from "./svml.js";
-import { createStage } from "./ui/stage.js";
+import { mountShell } from "./ui/shell.js";
-/**
- * Slice 0 fixture.
- *
- * Two Presents that do not overlap, each with an animated child. The compiled
- * document gates neither — it marks every clip visible and starts every
- * animation at load — so this composition renders as one muddle without the
- * runtime shim and as a clean two-shot sequence with it. That difference is the
- * whole point of the fixture: it is what proves the shim before anything is
- * built on top of it.
- */
-
-const programSpace: ProgramSpace = sealProgramSpace({
- contract: "svml.program-space@1",
- durationSec: 4,
- frameRate: { numerator: 30, denominator: 1 },
-});
-
-const CANVAS = { width: 1080, height: 1920, clearColor: "#09090b" };
-
-function shot(
- id: string,
- startFrame: number,
- endFrameExclusive: number,
- order: number,
- fill: string,
- label: string,
-): Track {
- const duration = endFrameExclusive - startFrame;
- const elements: VisualElement[] = [
- {
- id: "root",
- order: 0,
- kind: "box",
- style: [
- { name: "position", value: "absolute" },
- { name: "inset", value: 0 },
- { name: "display", value: "flex" },
- { name: "align-items", value: "center" },
- { name: "justify-content", value: "center" },
- ],
- },
- {
- id: "card",
- parent: "root",
- order: 1,
- kind: "box",
- style: [
- { name: "width", value: "760px" },
- { name: "height", value: "420px" },
- { name: "background", value: fill },
- { name: "border-radius", value: "36px" },
- { name: "display", value: "flex" },
- { name: "align-items", value: "center" },
- { name: "justify-content", value: "center" },
- ],
- // Fades up and settles. Seeking must land mid-fade, not at the end.
- animation: {
- keyframes: [
- { atFrame: 0, easing: "ease-out", style: [{ name: "opacity", value: 0 }, { name: "transform", value: "translateY(60px)" }] },
- { atFrame: Math.round(duration / 2), style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0px)" }] },
- { atFrame: duration, style: [{ name: "opacity", value: 1 }, { name: "transform", value: "translateY(0px)" }] },
- ],
- },
- },
- {
- id: "label",
- parent: "card",
- order: 2,
- kind: "text",
- text: label,
- style: [
- { name: "color", value: "#09090b" },
- { name: "font-family", value: "ui-sans-serif, sans-serif" },
- { name: "font-size", value: "64px" },
- { name: "font-weight", value: 700 },
- { name: "text-align", value: "center" },
- ],
- },
- ];
- return sealVisualTrack({
- contract: "svml.visual-track@1",
- visualIr: "svml.visual-ir@1",
- id,
- presents: [{
- id: `${id}-present`,
- span: { startFrame, endFrameExclusive },
- stacking: { order, tieBreak: id },
- elements,
- }],
- });
-}
-
-const app = document.querySelector<HTMLElement>("#app")!;
-const stage = createStage();
-app.append(stage.element);
-
-try {
- stage.show(renderPreview({
- id: "slice-0",
- canvas: CANVAS,
- programSpace,
- tracks: [
- shot("shot-a", 0, 60, 10, "#73fbd3", "frames 0–59"),
- shot("shot-b", 60, 120, 20, "#ffd166", "frames 60–119"),
- ],
- }));
-} catch (error) {
- stage.showError(error instanceof Error ? error.message : String(error));
-}
+mountShell(document.querySelector<HTMLElement>("#app")!);
diff --git a/tools/playground/src/registry/caption.ts b/tools/playground/src/registry/caption.ts
new file mode 100644
index 00000000..cf6188b0
--- /dev/null
+++ b/tools/playground/src/registry/caption.ts
@@ -0,0 +1,198 @@
+import {
+ renderCaptionTrack,
+ sealCaptionTrackProgram,
+} from "../svml.js";
+import type {
+ CanonicalValue,
+ CaptionPresentationMode,
+ TimedCaptionProjection,
+ TimedCaptionRegion,
+} from "../svml.js";
+import { fields, list, number, text } from "./types.js";
+import type { PreviewComponent } from "./types.js";
+
+/**
+ * The Caption Recipe key set, copied from packages/caption/src/surface.ts.
+ * tools/playground-registry.test.mjs fails if the two ever diverge.
+ */
+const RECIPE_KEYS = [
+ "align", "background", "fill", "font", "line-height", "padding",
+ "radius", "size", "stack-order", "weight", "width", "x", "y",
+] as const;
+
+const MODES: readonly CaptionPresentationMode[] = ["whole", "proportional-word", "character-flow"];
+
+/** SVS writes padding as "y" or "y x" — the y value comes first. */
+function padding(value: CanonicalValue): { y: number; x: number } {
+ const parts = String(value).trim().split(/\s+/u).map(Number);
+ const y = parts[0];
+ if (y === undefined || !Number.isFinite(y)) return { y: 0, x: 0 };
+ const x = parts[1];
+ return { y, x: x !== undefined && Number.isFinite(x) ? x : y };
+}
+
+function numeric(properties: Readonly<Record<string, CanonicalValue>>, key: string): number {
+ const value = Number(properties[key]);
+ return Number.isFinite(value) ? value : 0;
+}
+
+export const captionComponent: PreviewComponent = {
+ id: "caption",
+ label: "Caption",
+ recipeKeys: RECIPE_KEYS,
+
+ parameters: {
+ kind: "object",
+ fields: {
+ mode: { schema: { kind: "string", enum: [...MODES] } },
+ stackOrder: { schema: { kind: "number", integer: true, minimum: 0 } },
+ font: { schema: { kind: "string" } },
+ size: { schema: { kind: "number", minimum: 1 } },
+ weight: { schema: { kind: "number", integer: true, minimum: 100, maximum: 900 } },
+ lineHeight: { schema: { kind: "number", minimum: 0 } },
+ fill: { schema: { kind: "string" } },
+ background: { schema: { kind: "string" } },
+ paddingY: { schema: { kind: "number", minimum: 0 } },
+ paddingX: { schema: { kind: "number", minimum: 0 } },
+ radius: { schema: { kind: "number", minimum: 0 } },
+ align: { schema: { kind: "string", enum: ["left", "center", "right"] } },
+ x: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ y: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ width: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ },
+ },
+
+ content: {
+ kind: "object",
+ fields: {
+ cues: {
+ schema: {
+ kind: "array",
+ minItems: 1,
+ items: {
+ kind: "object",
+ fields: {
+ text: { schema: { kind: "string" } },
+ startSec: { schema: { kind: "number", minimum: 0 } },
+ endSec: { schema: { kind: "number", minimum: 0 } },
+ },
+ },
+ },
+ },
+ },
+ },
+
+ hints: {
+ fill: "color",
+ background: "color",
+ x: "unit-fraction",
+ y: "unit-fraction",
+ width: "unit-fraction",
+ "cues[].text": "multiline",
+ },
+
+ defaults: () => ({
+ parameters: {
+ mode: "whole",
+ stackOrder: 70,
+ font: "Inter, system-ui, sans-serif",
+ size: 58,
+ weight: 600,
+ lineHeight: 1.25,
+ fill: "#ffffff",
+ background: "#000000cc",
+ paddingY: 14,
+ paddingX: 26,
+ radius: 18,
+ align: "center",
+ x: 0.08,
+ y: 0.76,
+ width: 0.84,
+ },
+ content: {
+ cues: [
+ { text: "This is the first caption cue.", startSec: 0, endSec: 1.8 },
+ { text: "And this one follows it.", startSec: 1.8, endSec: 4 },
+ ],
+ },
+ }),
+
+ fromRecipe: (properties) => {
+ const pad = padding(properties["padding"] ?? "0");
+ return {
+ mode: "whole",
+ stackOrder: numeric(properties, "stack-order"),
+ font: String(properties["font"] ?? ""),
+ size: numeric(properties, "size"),
+ weight: numeric(properties, "weight"),
+ lineHeight: numeric(properties, "line-height"),
+ fill: String(properties["fill"] ?? "#ffffff"),
+ background: String(properties["background"] ?? "#00000000"),
+ paddingY: pad.y,
+ paddingX: pad.x,
+ radius: numeric(properties, "radius"),
+ align: String(properties["align"] ?? "center"),
+ x: numeric(properties, "x"),
+ y: numeric(properties, "y"),
+ width: numeric(properties, "width"),
+ };
+ },
+
+ build: ({ parameters, content, programSpace }) => {
+ const p = fields(parameters);
+ const mode = text(p["mode"], "mode") as CaptionPresentationMode;
+
+ // The compiler's own conversion, from packages/caption/src/surface.ts:
+ // SVS geometry is a 0–1 fraction and the style carries percentages.
+ const program = sealCaptionTrackProgram({
+ contract: "svml.caption-track-program@1",
+ id: "caption",
+ mode,
+ stacking: { order: number(p["stackOrder"], "stackOrder"), tieBreak: "caption" },
+ style: {
+ fontFamily: text(p["font"], "font"),
+ fontSizePx: number(p["size"], "size"),
+ fontWeight: number(p["weight"], "weight"),
+ color: text(p["fill"], "fill"),
+ backgroundColor: text(p["background"], "background"),
+ paddingXPx: number(p["paddingX"], "paddingX"),
+ paddingYPx: number(p["paddingY"], "paddingY"),
+ borderRadiusPx: number(p["radius"], "radius"),
+ bottomPercent: 0,
+ maxWidthPercent: number(p["width"], "width") * 100,
+ leftPercent: number(p["x"], "x") * 100,
+ topPercent: number(p["y"], "y") * 100,
+ widthPercent: number(p["width"], "width") * 100,
+ lineHeight: number(p["lineHeight"], "lineHeight"),
+ textAlign: text(p["align"], "align") as "left" | "center" | "right",
+ },
+ });
+
+ // A projection the playground synthesises. planCaptionPresentation reads
+ // only display text and timing, so an empty token list and no refinements
+ // are honest here rather than a stub: every mode, including
+ // proportional-word, distributes time the same way it does without
+ // alignment refinements in a real Build.
+ const cues = list(fields(content)["cues"], "cues");
+ const regions: TimedCaptionRegion[] = cues.map((cue, index) => {
+ const item = fields(cue);
+ return {
+ id: `cue-${index + 1}`,
+ display: text(item["text"], "cue text"),
+ segmentId: "playground",
+ kind: "identity",
+ sourceTokenIds: [],
+ startSec: number(item["startSec"], "startSec"),
+ endSec: number(item["endSec"], "endSec"),
+ refinements: [],
+ };
+ });
+ const projection: TimedCaptionProjection = {
+ contract: "svml.timed-caption-projection@1",
+ text: regions.map((region) => region.display).join(" "),
+ regions,
+ };
+
+ return [renderCaptionTrack(projection, program, programSpace)];
+ },
+};
diff --git a/tools/playground/src/registry/index.ts b/tools/playground/src/registry/index.ts
new file mode 100644
index 00000000..ef72c12d
--- /dev/null
+++ b/tools/playground/src/registry/index.ts
@@ -0,0 +1,35 @@
+import type { CanonicalValue } from "../svml.js";
+import { captionComponent } from "./caption.js";
+import { textTrackComponent } from "./text-track.js";
+import type { PreviewComponent } from "./types.js";
+
+export type { BuildInput, FieldHint, PreviewComponent } from "./types.js";
+
+export const REGISTRY: readonly PreviewComponent[] = [
+ captionComponent,
+ textTrackComponent,
+];
+
+export function componentById(id: string): PreviewComponent | undefined {
+ return REGISTRY.find((component) => component.id === id);
+}
+
+/** Joined on a separator no CSS-like property name can contain. */
+function keySet(names: readonly string[]): string {
+ return [...names].sort().join("\u0000");
+}
+
+/**
+ * Finds the component a Recipe describes.
+ *
+ * By exact property key set, which is what every Surface handler in the
+ * compiler matches on. A Recipe's dotted path is a label: `caption.dialogue`
+ * and `caption.short-cues` share a prefix and describe unrelated things.
+ */
+export function matchRecipe(
+ properties: Readonly<Record<string, CanonicalValue>>,
+): PreviewComponent | undefined {
+ const wanted = keySet(Object.keys(properties));
+ return REGISTRY.find((component) =>
+ component.recipeKeys !== undefined && keySet(component.recipeKeys) === wanted);
+}
diff --git a/tools/playground/src/registry/text-track.ts b/tools/playground/src/registry/text-track.ts
new file mode 100644
index 00000000..133f6959
--- /dev/null
+++ b/tools/playground/src/registry/text-track.ts
@@ -0,0 +1,147 @@
+import { programSpaceFrameCount, renderTextTrack, sealTextTrackProgram } from "../svml.js";
+import type { CanonicalValue, TextItem } from "../svml.js";
+import { fields, list, number, text } from "./types.js";
+import type { PreviewComponent } from "./types.js";
+
+/**
+ * The Text Recipe key set, copied from packages/text-track/src/surface.ts.
+ * tools/playground-registry.test.mjs fails if the two ever diverge.
+ */
+const RECIPE_KEYS = [
+ "align", "fill", "font", "height", "size",
+ "stack-order", "tracking", "weight", "width", "x", "y",
+] as const;
+
+function numeric(properties: Readonly<Record<string, CanonicalValue>>, key: string): number {
+ const value = Number(properties[key]);
+ return Number.isFinite(value) ? value : 0;
+}
+
+export const textTrackComponent: PreviewComponent = {
+ id: "text-track",
+ label: "Text overlay",
+ recipeKeys: RECIPE_KEYS,
+
+ parameters: {
+ kind: "object",
+ fields: {
+ stackOrder: { schema: { kind: "number", integer: true, minimum: 0 } },
+ font: { schema: { kind: "string" } },
+ size: { schema: { kind: "number", minimum: 1 } },
+ weight: { schema: { kind: "number", integer: true, minimum: 100, maximum: 900 } },
+ tracking: { schema: { kind: "number" } },
+ fill: { schema: { kind: "string" } },
+ align: { schema: { kind: "string", enum: ["left", "center", "right"] } },
+ x: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ y: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ width: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ height: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ },
+ },
+
+ content: {
+ kind: "object",
+ fields: {
+ items: {
+ schema: {
+ kind: "array",
+ minItems: 1,
+ items: {
+ kind: "object",
+ fields: {
+ text: { schema: { kind: "string" } },
+ startSec: { schema: { kind: "number", minimum: 0 } },
+ endSec: { schema: { kind: "number", minimum: 0 } },
+ },
+ },
+ },
+ },
+ },
+ },
+
+ hints: {
+ fill: "color",
+ x: "unit-fraction",
+ y: "unit-fraction",
+ width: "unit-fraction",
+ height: "unit-fraction",
+ "items[].text": "multiline",
+ },
+
+ defaults: () => ({
+ parameters: {
+ stackOrder: 90,
+ font: "Inter, system-ui, sans-serif",
+ size: 96,
+ weight: 800,
+ tracking: -2,
+ fill: "#ffffff",
+ align: "left",
+ x: 0.08,
+ y: 0.12,
+ width: 0.84,
+ height: 0.2,
+ },
+ content: {
+ items: [{ text: "A title card", startSec: 0, endSec: 4 }],
+ },
+ }),
+
+ fromRecipe: (properties) => ({
+ stackOrder: numeric(properties, "stack-order"),
+ font: String(properties["font"] ?? ""),
+ size: numeric(properties, "size"),
+ weight: numeric(properties, "weight"),
+ tracking: numeric(properties, "tracking"),
+ fill: String(properties["fill"] ?? "#ffffff"),
+ align: String(properties["align"] ?? "left"),
+ x: numeric(properties, "x"),
+ y: numeric(properties, "y"),
+ width: numeric(properties, "width"),
+ height: numeric(properties, "height"),
+ }),
+
+ build: ({ parameters, content, programSpace }) => {
+ const p = fields(parameters);
+ const totalFrames = programSpaceFrameCount(programSpace);
+ const fps = programSpace.frameRate.numerator / programSpace.frameRate.denominator;
+
+ const items: TextItem[] = list(fields(content)["items"], "items").map((entry, index) => {
+ const item = fields(entry);
+ const startFrame = Math.max(0, Math.min(totalFrames - 1, Math.round(number(item["startSec"], "startSec") * fps)));
+ // assertTextTrackProgramIdentity requires every span inside the program
+ // space, so shortening the duration must clamp rather than throw.
+ const endFrameExclusive = Math.max(
+ startFrame + 1,
+ Math.min(totalFrames, Math.round(number(item["endSec"], "endSec") * fps)),
+ );
+ return {
+ id: `item-${index + 1}`,
+ text: text(item["text"], "item text"),
+ span: { startFrame, endFrameExclusive },
+ z: number(p["stackOrder"], "stackOrder"),
+ tieBreak: `text:${index + 1}`,
+ box: {
+ xPercent: number(p["x"], "x") * 100,
+ yPercent: number(p["y"], "y") * 100,
+ widthPercent: number(p["width"], "width") * 100,
+ heightPercent: number(p["height"], "height") * 100,
+ },
+ appearance: {
+ color: text(p["fill"], "fill"),
+ fontSizePx: number(p["size"], "size"),
+ fontFamily: text(p["font"], "font"),
+ fontWeight: number(p["weight"], "weight"),
+ letterSpacingPx: number(p["tracking"], "tracking"),
+ align: text(p["align"], "align") as "left" | "center" | "right",
+ },
+ };
+ });
+
+ return [renderTextTrack(programSpace, sealTextTrackProgram({
+ contract: "svml.text-track-program@1",
+ id: "text",
+ items,
+ }))];
+ },
+};
diff --git a/tools/playground/src/registry/types.ts b/tools/playground/src/registry/types.ts
new file mode 100644
index 00000000..d61c4b1f
--- /dev/null
+++ b/tools/playground/src/registry/types.ts
@@ -0,0 +1,71 @@
+import type { CanonicalValue, ProgramSpace, Track, ValueSchema } from "../svml.js";
+
+/**
+ * What a control needs to know that `ValueSchema` cannot say.
+ *
+ * `ValueSchema` describes what a value *is*, not how it should be typed in. SVS
+ * geometry is normalized 0–1, which a slider edits far better than a number box,
+ * and colours may carry alpha, which `<input type=color>` cannot express.
+ */
+export type FieldHint = "color" | "multiline" | "unit-fraction";
+
+export type BuildInput = {
+ readonly parameters: CanonicalValue;
+ readonly content: CanonicalValue;
+ readonly programSpace: ProgramSpace;
+ readonly canvas: { readonly width: number; readonly height: number };
+};
+
+/**
+ * One previewable component.
+ *
+ * `build` returns Tracks rather than a Composition: the shell owns the canvas,
+ * the ProgramSpace and the seal, so adding a component is one file and one entry
+ * in the registry array. Everything a component states about itself — its
+ * parameters, its sample content, how a Recipe fills it in — lives here, and the
+ * form is generated from it rather than written per component.
+ */
+export type PreviewComponent = {
+ readonly id: string;
+ readonly label: string;
+ /**
+ * The exact SVS property key set this component's Recipe carries. Absent means
+ * the component is not discoverable from a stylesheet. Matching is by key set
+ * because that is what the compiler itself matches on — a Recipe's dotted path
+ * is a label, and `caption.dialogue` and `caption.short-cues` are different
+ * shapes under one prefix.
+ */
+ readonly recipeKeys?: readonly string[];
+ readonly parameters: ValueSchema;
+ readonly content: ValueSchema;
+ readonly hints?: Readonly<Record<string, FieldHint>>;
+ readonly defaults: () => { parameters: CanonicalValue; content: CanonicalValue };
+ /** Fills the parameter form from a Recipe. The form stays the source of truth. */
+ readonly fromRecipe?: (properties: Readonly<Record<string, CanonicalValue>>) => CanonicalValue;
+ readonly build: (input: BuildInput) => readonly Track[];
+};
+
+/** Narrows a form value to the object every component's parameters and content are. */
+export function fields(value: CanonicalValue): Readonly<Record<string, CanonicalValue>> {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) {
+ throw new Error("Expected an object of fields.");
+ }
+ return value as Readonly<Record<string, CanonicalValue>>;
+}
+
+export function text(value: CanonicalValue | undefined, name: string): string {
+ if (typeof value !== "string") throw new Error(`${name} must be a string.`);
+ return value;
+}
+
+export function number(value: CanonicalValue | undefined, name: string): number {
+ if (typeof value !== "number" || !Number.isFinite(value)) {
+ throw new Error(`${name} must be a number.`);
+ }
+ return value;
+}
+
+export function list(value: CanonicalValue | undefined, name: string): readonly CanonicalValue[] {
+ if (!Array.isArray(value)) throw new Error(`${name} must be a list.`);
+ return value;
+}
diff --git a/tools/playground/src/svml.ts b/tools/playground/src/svml.ts
index c4fa5af2..bbf1b3db 100644
--- a/tools/playground/src/svml.ts
+++ b/tools/playground/src/svml.ts
@@ -37,3 +37,19 @@ export { programSpaceFrameCount, sealProgramSpace } from "@narratage/program-spa
export type { ProgramSpace } from "@narratage/program-space";
export type { CanonicalValue, ValueSchema } from "@narratage/protocol";
+
+// Component lowering. These are the real renderers the compiler runs, so what
+// the playground shows is the production visual result and not a lookalike.
+export {
+ renderCaptionTrack,
+ sealCaptionTrackProgram,
+} from "@narratage/caption";
+export type {
+ CaptionPresentationMode,
+ CaptionTrackProgram,
+ TimedCaptionProjection,
+ TimedCaptionRegion,
+} from "@narratage/caption";
+
+export { renderTextTrack, sealTextTrackProgram } from "@narratage/text-track";
+export type { TextItem, TextTrackProgram } from "@narratage/text-track";
diff --git a/tools/playground/src/ui/form.ts b/tools/playground/src/ui/form.ts
new file mode 100644
index 00000000..1201fdb5
--- /dev/null
+++ b/tools/playground/src/ui/form.ts
@@ -0,0 +1,278 @@
+import type { CanonicalValue, ValueSchema } from "../svml.js";
+import type { FieldHint } from "../registry/index.js";
+
+export const FORM_CSS = `
+.form { display: flex; flex-direction: column; gap: 2px; }
+.form-row { display: grid; grid-template-columns: 96px 1fr; gap: 8px; align-items: center; padding: 3px 0; }
+.form-row > label { color: var(--muted); font-size: 12px; overflow: hidden; text-overflow: ellipsis; }
+.form-control { display: flex; gap: 6px; align-items: center; min-width: 0; }
+.form-control input[type=text], .form-control input[type=number], .form-control select, .form-control textarea {
+ flex: 1; min-width: 0; background: #1c1c21; color: var(--text);
+ border: 1px solid var(--line); border-radius: 5px; padding: 4px 7px; font: inherit; font-size: 12px;
+}
+.form-control textarea { resize: vertical; min-height: 46px; font-family: inherit; }
+.form-control input[type=range] { flex: 1; min-width: 0; accent-color: var(--accent); }
+.form-control input[type=color] { width: 28px; height: 24px; padding: 0; border: 1px solid var(--line); background: none; border-radius: 4px; }
+.form-control .narrow { flex: 0 0 68px; }
+.form-group { border: 1px solid var(--line); border-radius: 6px; padding: 8px 10px; margin: 5px 0; }
+.form-group > legend { color: var(--accent); font-size: 11px; letter-spacing: .04em; text-transform: uppercase; padding: 0 5px; }
+.form-item { border-top: 1px dashed var(--line); padding-top: 7px; margin-top: 7px; }
+.form-item:first-of-type { border-top: 0; padding-top: 0; margin-top: 0; }
+.form-actions { display: flex; gap: 6px; margin-top: 7px; }
+.form-actions button {
+ border: 1px solid var(--line); border-radius: 5px; background: #1c1c21;
+ color: var(--text); cursor: pointer; padding: 3px 9px; font-size: 12px;
+}
+.form-actions button:hover:not(:disabled) { border-color: #3a3a42; }
+.form-actions button:disabled { opacity: .4; cursor: default; }
+`;
+
+type Emit = () => void;
+
+function row(label: string, control: HTMLElement): HTMLElement {
+ const element = document.createElement("div");
+ element.className = "form-row";
+ const caption = document.createElement("label");
+ caption.textContent = label;
+ caption.title = label;
+ const holder = document.createElement("div");
+ holder.className = "form-control";
+ holder.append(control);
+ element.append(caption, holder);
+ return element;
+}
+
+/** `#RRGGBB` or `#RRGGBBAA`; `<input type=color>` can only carry the first six. */
+function colorControl(value: string, onChange: (next: string) => void): HTMLElement {
+ const holder = document.createElement("div");
+ holder.className = "form-control";
+ const swatch = document.createElement("input");
+ swatch.type = "color";
+ swatch.value = /^#[0-9a-f]{6}/iu.test(value) ? value.slice(0, 7) : "#000000";
+ const exact = document.createElement("input");
+ exact.type = "text";
+ exact.value = value;
+ // The text box is the source of truth: alpha survives only there.
+ swatch.addEventListener("input", () => {
+ const alpha = exact.value.length === 9 ? exact.value.slice(7) : "";
+ exact.value = swatch.value + alpha;
+ onChange(exact.value);
+ });
+ exact.addEventListener("input", () => {
+ if (/^#[0-9a-f]{6}/iu.test(exact.value)) swatch.value = exact.value.slice(0, 7);
+ onChange(exact.value);
+ });
+ holder.append(swatch, exact);
+ return holder;
+}
+
+function fractionControl(
+ value: number,
+ schema: { minimum?: number; maximum?: number },
+ onChange: (next: number) => void,
+): HTMLElement {
+ const holder = document.createElement("div");
+ holder.className = "form-control";
+ const slider = document.createElement("input");
+ slider.type = "range";
+ slider.min = String(schema.minimum ?? 0);
+ slider.max = String(schema.maximum ?? 1);
+ slider.step = "0.001";
+ slider.value = String(value);
+ const exact = document.createElement("input");
+ exact.type = "number";
+ exact.className = "narrow";
+ exact.step = "0.001";
+ exact.value = String(value);
+ slider.addEventListener("input", () => { exact.value = slider.value; onChange(Number(slider.value)); });
+ exact.addEventListener("input", () => { slider.value = exact.value; onChange(Number(exact.value)); });
+ holder.append(slider, exact);
+ return holder;
+}
+
+/**
+ * Builds controls from a ValueSchema.
+ *
+ * Nothing here validates. The schema shapes and coerces the input; the packages'
+ * own seal and assert functions decide whether a value is legal, because they
+ * are what a real Build would run and their messages are already good. A form
+ * that pre-judged would only disagree with them.
+ */
+export function buildForm(
+ schema: ValueSchema,
+ value: CanonicalValue,
+ hints: Readonly<Record<string, FieldHint>>,
+ emit: Emit,
+ path = "",
+): HTMLElement {
+ const container = document.createElement("div");
+ container.className = "form";
+
+ if (schema.kind !== "object") {
+ container.textContent = "Unsupported top-level schema.";
+ return container;
+ }
+
+ const bag = value as Record<string, CanonicalValue>;
+
+ for (const [name, field] of Object.entries(schema.fields)) {
+ const here = path ? `${path}.${name}` : name;
+ const hint = hints[here] ?? hints[name];
+ const current = bag[name];
+
+ if (field.schema.kind === "array") {
+ container.append(arrayGroup(name, here, field.schema, bag, hints, emit));
+ continue;
+ }
+ if (field.schema.kind === "object") {
+ const group = document.createElement("fieldset");
+ group.className = "form-group";
+ const legend = document.createElement("legend");
+ legend.textContent = name;
+ group.append(legend, buildForm(field.schema, current ?? {}, hints, emit, here));
+ container.append(group);
+ continue;
+ }
+ container.append(row(name, scalarControl(field.schema, current, hint, (next) => {
+ bag[name] = next;
+ emit();
+ })));
+ }
+ return container;
+}
+
+function scalarControl(
+ schema: ValueSchema,
+ current: CanonicalValue | undefined,
+ hint: FieldHint | undefined,
+ onChange: (next: CanonicalValue) => void,
+): HTMLElement {
+ if (schema.kind === "boolean") {
+ const box = document.createElement("input");
+ box.type = "checkbox";
+ box.checked = current === true;
+ box.addEventListener("input", () => onChange(box.checked));
+ return box;
+ }
+
+ if (schema.kind === "number") {
+ if (hint === "unit-fraction") {
+ return fractionControl(typeof current === "number" ? current : 0, schema, onChange);
+ }
+ const input = document.createElement("input");
+ input.type = "number";
+ if (schema.minimum !== undefined) input.min = String(schema.minimum);
+ if (schema.maximum !== undefined) input.max = String(schema.maximum);
+ input.step = schema.integer === true ? "1" : "any";
+ input.value = String(typeof current === "number" ? current : 0);
+ input.addEventListener("input", () => {
+ if (input.value !== "") onChange(Number(input.value));
+ });
+ return input;
+ }
+
+ if (schema.kind === "string") {
+ if (schema.enum !== undefined) {
+ const select = document.createElement("select");
+ for (const option of schema.enum) {
+ const item = document.createElement("option");
+ item.value = option;
+ item.textContent = option;
+ select.append(item);
+ }
+ select.value = typeof current === "string" ? current : (schema.enum[0] ?? "");
+ select.addEventListener("input", () => onChange(select.value));
+ return select;
+ }
+ if (hint === "color") {
+ return colorControl(typeof current === "string" ? current : "#ffffff", onChange);
+ }
+ if (hint === "multiline") {
+ const area = document.createElement("textarea");
+ area.value = typeof current === "string" ? current : "";
+ area.addEventListener("input", () => onChange(area.value));
+ return area;
+ }
+ const input = document.createElement("input");
+ input.type = "text";
+ input.value = typeof current === "string" ? current : "";
+ input.addEventListener("input", () => onChange(input.value));
+ return input;
+ }
+
+ const unsupported = document.createElement("span");
+ unsupported.textContent = `(${schema.kind})`;
+ return unsupported;
+}
+
+function blank(schema: ValueSchema): CanonicalValue {
+ if (schema.kind === "object") {
+ return Object.fromEntries(Object.entries(schema.fields)
+ .filter(([, field]) => field.optional !== true)
+ .map(([name, field]) => [name, blank(field.schema)]));
+ }
+ if (schema.kind === "array") return [];
+ if (schema.kind === "number") return schema.minimum ?? 0;
+ if (schema.kind === "string") return schema.enum?.[0] ?? "";
+ if (schema.kind === "boolean") return false;
+ return null;
+}
+
+function arrayGroup(
+ name: string,
+ path: string,
+ schema: ValueSchema & { kind: "array" },
+ bag: Record<string, CanonicalValue>,
+ hints: Readonly<Record<string, FieldHint>>,
+ emit: Emit,
+): HTMLElement {
+ const group = document.createElement("fieldset");
+ group.className = "form-group";
+ const legend = document.createElement("legend");
+ legend.textContent = name;
+ group.append(legend);
+
+ const entries = Array.isArray(bag[name]) ? [...(bag[name] as CanonicalValue[])] : [];
+ bag[name] = entries;
+ const minItems = schema.minItems ?? 0;
+
+ const rebuild = (): void => {
+ // Adding or removing an entry changes the control tree, so this subtree is
+ // rebuilt rather than patched. Scalar edits never come through here.
+ const replacement = arrayGroup(name, path, schema, bag, hints, emit);
+ group.replaceWith(replacement);
+ emit();
+ };
+
+ entries.forEach((entry, index) => {
+ const item = document.createElement("div");
+ item.className = "form-item";
+ item.append(buildForm(
+ schema.items,
+ entry,
+ hints,
+ emit,
+ `${path}[]`,
+ ));
+ const actions = document.createElement("div");
+ actions.className = "form-actions";
+ const remove = document.createElement("button");
+ remove.type = "button";
+ remove.textContent = "Remove";
+ remove.disabled = entries.length <= minItems;
+ remove.addEventListener("click", () => { entries.splice(index, 1); rebuild(); });
+ actions.append(remove);
+ item.append(actions);
+ group.append(item);
+ });
+
+ const actions = document.createElement("div");
+ actions.className = "form-actions";
+ const add = document.createElement("button");
+ add.type = "button";
+ add.textContent = "Add";
+ add.addEventListener("click", () => { entries.push(blank(schema.items)); rebuild(); });
+ actions.append(add);
+ group.append(actions);
+ return group;
+}
diff --git a/tools/playground/src/ui/shell.ts b/tools/playground/src/ui/shell.ts
new file mode 100644
index 00000000..7e110016
--- /dev/null
+++ b/tools/playground/src/ui/shell.ts
@@ -0,0 +1,152 @@
+import { REGISTRY, componentById } from "../registry/index.js";
+import type { PreviewComponent } from "../registry/index.js";
+import { renderPreview } from "../preview/render.js";
+import { sealProgramSpace } from "../svml.js";
+import type { CanonicalValue } from "../svml.js";
+import { FORM_CSS, buildForm } from "./form.js";
+import { createStage } from "./stage.js";
+
+const CSS = `
+.rail {
+ width: 340px; flex: 0 0 340px; border-right: 1px solid var(--line);
+ background: var(--panel); display: flex; flex-direction: column; min-height: 0;
+}
+.rail-head { padding: 12px 14px; border-bottom: 1px solid var(--line); }
+.rail-head h1 { margin: 0 0 10px; font-size: 13px; font-weight: 600; letter-spacing: .02em; }
+.rail-body { flex: 1; min-height: 0; overflow-y: auto; padding: 10px 14px 24px; }
+.rail select, .rail input[type=number] {
+ background: #1c1c21; color: var(--text); border: 1px solid var(--line);
+ border-radius: 5px; padding: 4px 7px; font: inherit; font-size: 12px; min-width: 0;
+}
+.rail-canvas { display: grid; grid-template-columns: auto 1fr auto 1fr; gap: 6px; align-items: center; margin-top: 9px; }
+.rail-canvas span { color: var(--muted); font-size: 11px; }
+.section { color: var(--accent); font-size: 11px; letter-spacing: .05em;
+ text-transform: uppercase; margin: 14px 0 4px; }
+.section:first-child { margin-top: 0; }
+${FORM_CSS}
+`;
+
+type Draft = { parameters: CanonicalValue; content: CanonicalValue };
+
+export function mountShell(root: HTMLElement): void {
+ const style = document.createElement("style");
+ style.textContent = CSS;
+ document.head.append(style);
+
+ const rail = document.createElement("div");
+ rail.className = "rail";
+ rail.innerHTML = `
+ <div class="rail-head">
+ <h1>Component playground</h1>
+ <select data-component></select>
+ <div class="rail-canvas">
+ <span>W</span><input type="number" data-width min="16" step="2" />
+ <span>H</span><input type="number" data-height min="16" step="2" />
+ <span>fps</span><input type="number" data-fps min="1" step="1" />
+ <span>sec</span><input type="number" data-duration min="0.1" step="0.1" />
+ </div>
+ </div>
+ <div class="rail-body"></div>
+ `;
+
+ const picker = rail.querySelector<HTMLSelectElement>("[data-component]")!;
+ const body = rail.querySelector<HTMLElement>(".rail-body")!;
+ const widthInput = rail.querySelector<HTMLInputElement>("[data-width]")!;
+ const heightInput = rail.querySelector<HTMLInputElement>("[data-height]")!;
+ const fpsInput = rail.querySelector<HTMLInputElement>("[data-fps]")!;
+ const durationInput = rail.querySelector<HTMLInputElement>("[data-duration]")!;
+
+ for (const component of REGISTRY) {
+ const option = document.createElement("option");
+ option.value = component.id;
+ option.textContent = component.label;
+ picker.append(option);
+ }
+
+ const stage = createStage();
+ root.append(rail, stage.element);
+
+ const canvas = { width: 1080, height: 1920, clearColor: "#09090b" };
+ const space = { fps: 30, durationSec: 4 };
+ widthInput.value = String(canvas.width);
+ heightInput.value = String(canvas.height);
+ fpsInput.value = String(space.fps);
+ durationInput.value = String(space.durationSec);
+
+ // One draft per component, so switching away and back keeps your edits.
+ const drafts = new Map<string, Draft>();
+ let active: PreviewComponent = REGISTRY[0]!;
+
+ function draft(component: PreviewComponent): Draft {
+ const existing = drafts.get(component.id);
+ if (existing !== undefined) return existing;
+ const created = component.defaults();
+ drafts.set(component.id, created);
+ return created;
+ }
+
+ let queued = 0;
+ function schedule(): void {
+ if (queued !== 0) clearTimeout(queued);
+ queued = window.setTimeout(render, 120);
+ }
+
+ function render(): void {
+ const current = draft(active);
+ try {
+ const programSpace = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: space.durationSec,
+ frameRate: { numerator: space.fps, denominator: 1 },
+ });
+ const tracks = active.build({
+ parameters: current.parameters,
+ content: current.content,
+ programSpace,
+ canvas,
+ });
+ stage.show(renderPreview({ id: active.id, canvas, programSpace, tracks }));
+ } catch (error) {
+ // The compiler's own message, verbatim. The last good frame stays up.
+ stage.showError(error instanceof Error ? error.message : String(error));
+ }
+ }
+
+ function renderForm(): void {
+ const current = draft(active);
+ body.replaceChildren();
+ const parameters = document.createElement("div");
+ parameters.className = "section";
+ parameters.textContent = "Parameters";
+ const content = document.createElement("div");
+ content.className = "section";
+ content.textContent = "Content";
+ body.append(
+ parameters,
+ buildForm(active.parameters, current.parameters, active.hints ?? {}, schedule),
+ content,
+ buildForm(active.content, current.content, active.hints ?? {}, schedule),
+ );
+ }
+
+ picker.addEventListener("input", () => {
+ active = componentById(picker.value) ?? active;
+ renderForm();
+ render();
+ });
+
+ for (const [input, apply] of [
+ [widthInput, (n: number) => { canvas.width = n; }],
+ [heightInput, (n: number) => { canvas.height = n; }],
+ [fpsInput, (n: number) => { space.fps = n; }],
+ [durationInput, (n: number) => { space.durationSec = n; }],
+ ] as const) {
+ input.addEventListener("input", () => {
+ const value = Number(input.value);
+ if (Number.isFinite(value) && value > 0) { apply(value); schedule(); }
+ });
+ }
+
+ renderForm();
+ render();
+}