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
refactor: stop the playground reading stylesheets, and knowing Film
rpone351b8ad63f1b
diff --git a/docs/guide/playground.md b/docs/guide/playground.mdindex 1321ae04..6d0fe19c 100644--- a/docs/guide/playground.md+++ b/docs/guide/playground.md@@ -21,78 +21,39 @@ no credentials, no local services.| Control | What it does ||---|---|| Component list | Every module that can put pixels on a frame |-| W / H / fps / sec | The canvas and the frame domain |-| Appearance from a stylesheet | Adopt a `.svs` Film Recipe's background |+| W / H / fps / sec / bg | The canvas, the frame domain and the clear colour || Input forms | One per input the component takes || Scrubber | Frame-exact; the counter shows `frame / last` |-The preview uses the installed modules' real Producer handlers. For example,-Fine Caption, Media Track, Screen Overlay, Speech Basis and Typography Track-all lower to `VisualTrack`, then `compileHyperframesDocument` produces the same-document a Build would render.+The preview runs the installed modules' real Producer handlers and compiles the+same document a Build would render.-## It lists nothing+The list and the forms are read from the manifests, so a module that declares a+Producer emitting a `VisualTrack` appears on its own.-The playground has no list of components. It reads the manifests and offers-every module that declares a Producer whose output type is `VisualTrack`. Add a-module that emits one and it appears; stop emitting one and it disappears.+## Controls-Everything else is read the same way:--| Question | Answered by |-|---|---|-| What a component needs | that Producer's `inputs` |-| What shape each input has | the declaring module's `TypeDeclaration.schema` |-| What to start from | that type's `TypeDeclaration.default` |-| What a control looks like | `ValueSchema.format` |--So a caption's `mode` is a dropdown because its schema declares an `enum`, and-its `display` is a text area because the field is `format: "multiline"`. Neither-is configured here.--## Formats--`format` is how a module says what a value means when its type alone is-ambiguous — a colour and a font family are both strings.+A module annotates a field with `format` to say what the value means:| Format | Control ||---|---|-| `color` | Swatch beside a text box. The text is authoritative, because `#RRGGBBAA` carries alpha a swatch cannot. |+| `color` | Swatch beside a text box. Type the value to set alpha: `#RRGGBBAA`. || `unit-fraction` | Slider plus a number box || `multiline` | Text area || `digest` | File picker || `duration` | Number box, in seconds |-`color` and `digest` have an exact shape, so `validateStoredValue` enforces-them. The others describe without narrowing.-## Media-A `format: "digest"` field takes a file. The playground hashes it with SHA-256-and registers a real content-addressed identity, because a compiled document-cross-checks every Artifact reference and would reject a stub.--Modules that draw supplied footage — B-roll, speaker footage — therefore have no-default: a module has no bytes to point at, so it says nothing rather than-inventing a digest. Until you choose a file those components draw nothing, which-is a state to pass through and not an error.--## Stylesheets--Choosing a `.svs` file reads **only its Film Recipe**, and only for Film-appearance. Point it at `examples/talking-film-golden/studio.svs` and the-preview adopts that Recipe's background. Canvas dimensions and time remain-explicit preview-environment controls.--Nothing else in the sheet is read. What a component looks like comes from the-module that owns it, not from a stylesheet the playground happened to open.+A `format: "digest"` field takes a file, hashed as you pick it. Components that+draw supplied footage — B-roll, speaker footage — draw nothing until you choose+one.## When something is wrong-Nothing in the playground validates. The modules' own `seal` and `assert`-functions are the judge, because they are what a real Build runs. A rejected-value shows the compiler's own message under the canvas and leaves the last good-frame on screen, so you can read the error and the picture together.+A rejected value shows the compiler's own message under the canvas and leaves+the last good frame on screen, so you can read the error and the picture+together.## Known divergences from a real render@@ -100,7 +61,7 @@ frame on screen, so you can read the error and the picture together.`FontArtifactRef` path with hashed `@font-face` families is not exercised.- Audio tracks are not played.- A `ProgramSpace` input is filled from the canvas controls rather than offered- in a form, so there is only one place to change the frame domain.+ in a form.See [`tools/playground/README.md`](https://github.com/cashdiffusion/svml/blob/main/tools/playground/README.md)for how the timeline shim works and what a module must declare to bediff --git a/docs/zh/guide/playground.md b/docs/zh/guide/playground.mdindex bf6beafa..fc23a883 100644--- a/docs/zh/guide/playground.md+++ b/docs/zh/guide/playground.md@@ -19,73 +19,41 @@ pnpm playground| 控件 | 作用 ||---|---|| 组件下拉 | 所有能在画面上产生像素的模块 |-| W / H / fps / sec | 画布与帧域 |-| Appearance from a stylesheet | 采用某个 `.svs` Film Recipe 的背景 |+| W / H / fps / sec / bg | 画布、帧域与清除颜色 || 输入表单 | 组件每个输入各一份 || 刻度条 | 帧精确,计数显示为 `当前帧 / 末帧` |-预览运行的是已安装模块真正的 Producer handler。例如 Fine Caption、Media Track、-Screen Overlay、Speech Basis 和 Typography Track 都会降低为 `VisualTrack`,再由-`compileHyperframesDocument` 产出与 Build 相同的文档。+预览运行的是已安装模块真正的 Producer handler,编译出的文档与 Build 渲染的是同一份。-## 它不维护任何清单+下拉与表单都读自各个 manifest,所以只要模块声明了「输出 `VisualTrack` 的 Producer」,它自己就会出现。-Playground 里没有组件列表。它读取各 manifest,把所有声明了「输出 `VisualTrack` 的 Producer」的模块-列出来。新增这样的模块,它自己会出现;不再输出,它自己会消失。+## 控件-其余信息同样是读出来的:--| 问题 | 来源 |-|---|---|-| 组件需要什么 | 该 Producer 的 `inputs` |-| 每个输入什么形状 | 声明方的 `TypeDeclaration.schema` |-| 从什么值开始 | 该类型的 `TypeDeclaration.default` |-| 控件长什么样 | `ValueSchema.format` |--所以字幕的 `mode` 是下拉框,因为它的 schema 声明了 `enum`;`display` 是多行文本框,因为该字段是-`format: "multiline"`。这两者都不在 Playground 里配置。--## format--当类型本身不足以表达含义时,模块用 `format` 说明——颜色和字体名同样都是字符串。+模块用 `format` 标注一个字段,说明它的值是什么:| format | 控件 ||---|---|-| `color` | 色板配文本框。以文本框为准,因为 `#RRGGBBAA` 带的 alpha 色板表达不了 |+| `color` | 色板配文本框。要带 alpha 就在文本框里写 `#RRGGBBAA` || `unit-fraction` | 滑块加数字框 || `multiline` | 多行文本框 || `digest` | 文件选择 || `duration` | 数字框,单位秒 |-`color` 和 `digest` 有确切形状,由 `validateStoredValue` 校验。其余只描述,不收窄。-## 媒体-`format: "digest"` 的字段接受一个文件。Playground 用 SHA-256 计算并注册真实的内容寻址标识——-编译产出的文档会交叉校验每一个 Artifact 引用,占位值会被拒绝。--因此绘制外部素材的模块(B-roll、说话人画面)**没有默认值**:模块手里没有那些字节,与其编造一个-digest,不如什么都不说。在你选择文件之前这些组件不画任何东西,这是一个可以经过的状态,不是错误。--## 样式表--选择 `.svs` 文件**只读其中的 Film Recipe**,且只用于 Film 外观。指向-`examples/talking-film-golden/studio.svs`,预览会采用该 Recipe 的背景色;画布尺寸与时间仍由-预览环境的显式控件决定。--表里其余内容一概不读。组件长什么样由拥有它的模块决定,而不是由 Playground 恰好打开的某张样式表决定。+`format: "digest"` 的字段接受一个文件,选中即计算哈希。绘制外部素材的组件(B-roll、说话人画面)+在你选择文件之前不画任何东西。## 出错时-Playground 自身不做任何校验。裁判是各模块自己的 `seal` 与 `assert` 函数——它们正是真实 Build 会跑的-东西。被拒绝的值会把编译器原本的报错显示在画布下方,并保留上一帧正确画面,让你能同时看到错误和图像。+被拒绝的值会把编译器原本的报错显示在画布下方,并保留上一帧正确画面,让你能同时看到错误和图像。## 与真实渲染的已知偏差- 字体降级为普通 CSS `font-family` 字符串,不会走生产环境中带哈希 `@font-face` 的`FontArtifactRef` 路径。- 不播放音频轨。-- `ProgramSpace` 输入由画布控件填充而非出现在表单里,使帧域只有一处可改。+- `ProgramSpace` 输入由画布控件填充,不出现在表单里。时间线 shim 的原理、以及一个模块需要声明什么才能被预览,见[`tools/playground/README.md`](https://github.com/cashdiffusion/svml/blob/main/tools/playground/README.md)。diff --git a/tools/playground/README.md b/tools/playground/README.mdindex d692d577..60105962 100644--- a/tools/playground/README.md+++ b/tools/playground/README.md@@ -6,17 +6,16 @@ Look at a visual component without running a Build.pnpm playground```-Pick a producer, fill in its inputs, and it renders on a canvas of the size you-choose. Choose a `.svs` stylesheet and its Film Recipe fills in Film appearance;-canvas size and time stay explicit preview-environment controls.+Pick a producer, fill in its inputs, and it renders on a canvas whose size,+frame rate, duration and background you choose.[The guide page](../../docs/guide/playground.md) covers using it. This filecovers how it works.-## It lists nothing+## Where everything comes from-There is no registry here, and no per-component code. Everything comes from-what the compiler already declares about itself:+There is no registry here and no per-component code. Each answer is read at run+time:| Question | Answered by ||---|---|@@ -27,13 +26,13 @@ what the compiler already declares about itself:| What to start from | `TypeDeclaration.default`, given by the module that owns the type || How to run it | the module's `component.producers[].handler` |-A module that gains a visual Producer appears here on its own. One that loses-it disappears. Neither requires editing anything in this directory.+A module that gains a visual Producer appears here on its own; one that loses it+disappears. Neither requires editing anything in this directory.-Nothing here validates, either: `validateStoredValue` and the modules' own-`seal*` and `assert*` functions are the judge, because they are what a real-Build runs. A rejected value shows the compiler's own message beside the form-and leaves the last good frame up.+Nothing here validates. `validateStoredValue` and the modules' own `seal*` and+`assert*` functions are the judge, since they are what a real Build runs. A+rejected value shows the compiler's own message beside the form and leaves the+last good frame up.## Two things a Build supplies that the document does not@@ -53,17 +52,16 @@ self-sufficient — a real render supplies a producer for the rest. The shim inNothing to add here. In the module: declare a Producer that outputs a`VisualTrack`, give each input type a `schema`, and give it a `default` where-you honestly can. A type carrying content-addressed media has no default — say-nothing rather than inventing a digest, and the playground will ask the operator-for a file instead.+one exists. A type carrying content-addressed media has none, and the playground+asks the operator for a file instead.-Annotate a field with `format` where its type alone is ambiguous: a colour and-a font family are both strings, and only the module knows which is which.+Annotate a field with `format` where its type alone is ambiguous — a colour and+a font family are both strings.## Known divergences from a real render- Fonts lower to a plain CSS `font-family` string. The production`FontArtifactRef` path with hashed `@font-face` families is not exercised.- Audio tracks are not played.-- The frame domain is the shell's, not the form's: a `ProgramSpace` input is- filled from the canvas controls, so there is only one place to change it.+- A `ProgramSpace` input is filled from the canvas controls rather than offered+ in a form.diff --git a/tools/playground/src/svml.ts b/tools/playground/src/svml.tsindex 5cf80839..a05d9a46 100644--- a/tools/playground/src/svml.ts+++ b/tools/playground/src/svml.ts@@ -41,10 +41,3 @@ export type {} from "@narratage/protocol";export type { MediaArtifactRef } from "@narratage/media";--// Stylesheets are read to fill a form, never to decide what a component is.-export { parseSvs } from "@narratage/svs";-export type { SvsRecipe } from "@narratage/svs";-export { maskSourceHeader, parseSourceHeader } from "@narratage/source";--export { defaultFilmProgram, filmAppearanceFromRecipe, filmRecipeKeys } from "@narratage/film";diff --git a/tools/playground/src/ui/shell.ts b/tools/playground/src/ui/shell.tsindex b3dd26da..b0f9cc2c 100644--- a/tools/playground/src/ui/shell.ts+++ b/tools/playground/src/ui/shell.ts@@ -3,13 +3,7 @@ import { workspacePreviewProducers } from "../discovery/workspace.js";import { renderPreview } from "../preview/render.js";import {defaultCanvasSpace,- defaultFilmProgram,defaultProgramSpace,- filmAppearanceFromRecipe,- filmRecipeKeys,- maskSourceHeader,- parseSourceHeader,- parseSvs,sealProgramSpace,} from "../svml.js";import type { CanonicalValue, ProgramSpace, Track } from "../svml.js";@@ -33,14 +27,11 @@ const CSS = `.section { color: var(--accent); font-size: 11px; margin: 15px 0 4px; }.section:first-child { margin-top: 0; }.module { color: var(--muted); font-size: 11px; font-family: ui-monospace, monospace; margin-top: 4px; }-.sheet-note { color: var(--muted); font-size: 12px; margin-top: 7px; }-.sheet-note b { color: var(--accent); font-weight: 500; }-.sheet-file { font-size: 11px; color: var(--muted); max-width: 100%; }-.sheet-file::file-selector-button {- border: 1px solid var(--line); border-radius: 5px; background: #1c1c21;- color: var(--text); font: inherit; font-size: 11px; padding: 3px 9px; margin-right: 7px; cursor: pointer;+.hint { color: var(--muted); font-size: 12px; margin-top: 7px; }+.rail-canvas input[type=color] {+ width: 100%; height: 24px; padding: 0; border: 1px solid var(--line);+ background: none; border-radius: 5px;}-.sheet-file::file-selector-button:hover { border-color: #3a3a42; }${FORM_CSS}`;@@ -61,6 +52,7 @@ export async function mountShell(root: HTMLElement): Promise<void> {<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" />+ <span>bg</span><input type="color" data-background /></div></div><div class="rail-body"></div>@@ -73,6 +65,7 @@ export async function mountShell(root: HTMLElement): Promise<void> {const heightInput = rail.querySelector<HTMLInputElement>("[data-height]")!;const fpsInput = rail.querySelector<HTMLInputElement>("[data-fps]")!;const durationInput = rail.querySelector<HTMLInputElement>("[data-duration]")!;+ const backgroundInput = rail.querySelector<HTMLInputElement>("[data-background]")!;const stage = createStage();root.append(rail, stage.element);@@ -89,16 +82,16 @@ export async function mountShell(root: HTMLElement): Promise<void> {picker.append(option);}- // Spatial owns geometry, Film owns appearance and ProgramSpace owns time.- // The preview starts from those three package-owned values instead of a- // second playground-specific model of a frame.+ // Spatial owns geometry and ProgramSpace owns time, so the preview starts+ // from those package-owned values rather than a second playground model of a+ // frame. The clear colour belongs to a Composition, and a preview assembles+ // none, so it is a stage control the operator sets like the others.const canvasSpace = defaultCanvasSpace();- const film = defaultFilmProgram();const defaultSpace = defaultProgramSpace();const canvas = {width: canvasSpace.widthPx,height: canvasSpace.heightPx,- clearColor: film.clearColor,+ clearColor: "#09090b",};const space = {fps: defaultSpace.frameRate.numerator / defaultSpace.frameRate.denominator,@@ -175,51 +168,6 @@ export async function mountShell(root: HTMLElement): Promise<void> {}}- const note = document.createElement("div");- note.className = "sheet-note";-- /**- * Reads a chosen stylesheet for Film appearance.- *- * Geometry and time are graph inputs, not style. A Film Recipe may therefore- * change only the Composition background; component Recipes remain owned by- * their own modules.- */- function loadSheet(file: File): void {- void file.text().then((source) => {- const header = parseSourceHeader(file.name, source);- if (!header.using.startsWith("@narratage/svs@")) {- throw new Error(`${file.name} is a ${header.using} source, not a stylesheet.`);- }- const sheet = parseSvs(file.name, maskSourceHeader(source, header));- const filmShape = [...filmRecipeKeys].sort().join(" ");- const found = sheet.recipes.find((recipe) =>- Object.keys(recipe.value.properties).sort().join(" ") === filmShape);- if (found === undefined) {- note.textContent = `${file.name} declares no Film Recipe, so the background is unchanged.`;- return;- }- const read = filmAppearanceFromRecipe(found.value.properties);- canvas.clearColor = read.clearColor;- note.replaceChildren(document.createTextNode("Background from "));- const which = document.createElement("b");- which.textContent = found.value.path;- note.append(which);- render();- }).catch((error: unknown) => {- note.textContent = error instanceof Error ? error.message : String(error);- });- }-- const sheetPicker = document.createElement("input");- sheetPicker.type = "file";- sheetPicker.accept = ".svs";- sheetPicker.className = "sheet-file";- sheetPicker.addEventListener("change", () => {- const file = sheetPicker.files?.[0];- if (file !== undefined) loadSheet(file);- });-function section(title: string): HTMLElement {const element = document.createElement("div");element.className = "section";@@ -230,7 +178,7 @@ export async function mountShell(root: HTMLElement): Promise<void> {function renderRail(): void {const values = draft(active);moduleLine.textContent = active.moduleName;- body.replaceChildren(section("Appearance from a stylesheet"), sheetPicker, note);+ body.replaceChildren();for (const input of active.inputs) {// The shell owns the frame domain; offering it again would be a second@@ -239,14 +187,14 @@ export async function mountShell(root: HTMLElement): Promise<void> {body.append(section(input.name));if (input.schema === undefined) {const missing = document.createElement("div");- missing.className = "sheet-note";+ missing.className = "hint";missing.textContent = `${input.type.module.name} declares no schema for ${input.type.name}.`;body.append(missing);continue;}if (values[input.name] === null || values[input.name] === undefined) {const empty = document.createElement("div");- empty.className = "sheet-note";+ empty.className = "hint";empty.textContent = `${input.type.module.name} offers no default for ${input.type.name}.`;body.append(empty);}@@ -264,6 +212,11 @@ export async function mountShell(root: HTMLElement): Promise<void> {heightInput.value = String(canvas.height);fpsInput.value = String(space.fps);durationInput.value = String(space.durationSec);+ backgroundInput.value = canvas.clearColor;+ backgroundInput.addEventListener("input", () => {+ canvas.clearColor = backgroundInput.value;+ schedule();+ });for (const [input, apply] of [[widthInput, (n: number) => { canvas.width = n; }],[heightInput, (n: number) => { canvas.height = n; }],