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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat: preview captions and text overlays from a generated form
rponef7c16897bf49
diff --git a/test/playground-preview.test.ts b/test/playground-preview.test.tsnew file mode 100644index 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.mjsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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-spaexport 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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();+}