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: isolate the official SVML playground
kashorin22cf845aa6e4
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.mdindex d1aee06e..1eb3538a 100644--- a/.agents/skills/narratage/SKILL.md+++ b/.agents/skills/narratage/SKILL.md@@ -20,49 +20,10 @@ Source, and the declarative `svml.runtime.json` Runtime Profile separate.`references/playbooks/craft/visual-continuity.md`, then the relevant craft/format file.- Reference-video reconstruction → read `references/reference-vlm.md`; emit `main.svml`, optional`studio.svs`, and `build.svrun` directly.-- Showing an author what they have so far → start the SVML Playground and send them the link.- See "Show the work" below.- Execution, Runtime control, Build inspection, or output retrieval → read`references/runtime.md`; diagnose and start the durable Runtime, `check` Author Source, `plan`before paid work, then submit, inspect, and retrieve the Build.-## Show the work--After each step that changes a Source — a Script edit, a Frame moved, a B-roll-placed, a Recipe adjusted — start the Playground and give the author the link.-Reading a diff is not the same as seeing where a cutaway lands.--```bash-pkill -f svml-playground || true # never leave the old one holding the port-pnpm svml:playground -- --source path/to/main.svml \- --run path/to/build.svrun \- --runtime path/to/svml.runtime.json &-# then send the author: http://localhost:5179/-```--Kill the previous server first. A second one silently picks another port, and the-author ends up looking at a stale preview while you describe a new one.--Both extra arguments are optional and each answers one question. `--run` says-which material and which timings to read the Source with. `--runtime` says where-material earlier Builds produced is kept, and is needed only by a Source that-reuses an accepted shot through `<build-record>`; without it that one shot is-refused by name and everything else still draws.--The preview compiles the Source with the real compiler and runs the same-Producers a build runs, so a Source that will not build does not preview. It-needs no build of its own: a directory holding `main.svml` and its `.svs` is-enough.--What it cannot know, it stands in for and says so. Words are placed at an-ordinary delivery pace, except where the Source declares a length — a take that-says it is eight seconds long gets eight seconds of words. A shot nobody has-made shows the picture it names, or a black frame if it names none. Captions-nobody has phrased are cut every few words. Each Track says which of these it is-showing, so say that rather than implying a preview is a render.--Read `docs/guide/svml-playground.md` before explaining what an author is seeing.-## Ordinary loop```bashdiff --git a/.agents/skills/narratage/references/playbooks/craft/b-roll.md b/.agents/skills/narratage/references/playbooks/craft/b-roll.mdindex d0631844..d2c5d9f0 100644--- a/.agents/skills/narratage/references/playbooks/craft/b-roll.md+++ b/.agents/skills/narratage/references/playbooks/craft/b-roll.md@@ -1,24 +1,4 @@--## See it before you generate it--Where a cutaway lands, how long it holds, and whether its Frame sits in the right-part of the picture are all decided by the Source, not by the footage. The SVML-Playground answers all three without a generation:--```bash-pkill -f svml-playground || true-pnpm svml:playground -- --source path/to/main.svml --run path/to/build.svrun &-# send the author http://localhost:5179/-```--Each Item shows real frames when its source already exists and already lives in-the program's frame rate, and a painted box when it does not, so an unresolved-B-roll is still placed and still scrubbable. Timings are estimated until a build-or a Run Source supplies measured ones — the badges say which, and an estimated-cut point will move once WhisperX has heard the audio.--Do this after placing a Selection and before paying for a generation.# B-roll craftB-roll is authored visual evidence, context, or emotional progression outside the primary speakingdiff --git a/docs/guide/svml-playground.md b/docs/guide/svml-playground.mdindex b347771c..65bd0e90 100644--- a/docs/guide/svml-playground.md+++ b/docs/guide/svml-playground.md@@ -142,6 +142,12 @@ the compiled Source for its exports and builds the ones typed `VisualTrack` or`AudioTrack` — so a package that grows a new kind of Track appears here withoutthe Playground being taught about it.+The application explicitly bundles Narratage's official video packages. That+list belongs only to the Playground: installing or removing this application+changes nothing about compilation or the Runtime. Adding another official+package requires a Playground release; adding another Track to a package it+already bundles does not require a special preview branch.+Each Track is built on its own. A Track waiting on a Provider this machine hasno key for costs only itself; the rest of the programme still plays, and theTrack says what it was waiting for rather than disappearing.diff --git a/docs/zh/guide/svml-playground.md b/docs/zh/guide/svml-playground.mdindex 84472bbe..10a9853b 100644--- a/docs/zh/guide/svml-playground.md+++ b/docs/zh/guide/svml-playground.md@@ -120,6 +120,10 @@ Playground 按以下顺序优先采用真实来源:把类型是 `VisualTrack` 或 `AudioTrack` 的那些建出来 —— 所以某个包新长出一种 Track,不需要教 Playground 就会出现在这里。+这个应用显式携带 Narratage 的官方视频包清单。清单只属于 Playground:安装或卸载它,+都不会改变编译与 Runtime。新增一个官方包时需要同步发布 Playground;已携带的包新增+Track 时,不需要再为预览写一条特殊分支。+每条 Track 各自构建。某条轨道在等一个这台机器没有密钥的 Provider,代价只有它自己:其余部分照常播放,而那条轨道会说明它在等什么,而不是凭空消失。diff --git a/packages/video-domain/package.json b/packages/video-domain/package.jsondeleted file mode 100644index ab01d7a0..00000000--- a/packages/video-domain/package.json+++ /dev/null@@ -1,33 +0,0 @@-{- "name": "@narratage/video-domain",- "version": "0.0.0-dev",- "license": "SEE LICENSE IN LICENSE",- "private": true,- "type": "module",- "exports": {- ".": "./src/index.ts"- },- "dependencies": {- "@narratage/artifact": "workspace:*",- "@narratage/component-kit": "workspace:*",- "@narratage/composition": "workspace:*",- "@narratage/core": "workspace:*",- "@narratage/driver-node": "workspace:*",- "@narratage/elaborator": "workspace:*",- "@narratage/generation": "workspace:*",- "@narratage/markup": "workspace:*",- "@narratage/media": "workspace:*",- "@narratage/narrative": "workspace:*",- "@narratage/program-space": "workspace:*",- "@narratage/protocol": "workspace:*",- "@narratage/semantic-map": "workspace:*",- "@narratage/spatial": "workspace:*",- "@narratage/speech": "workspace:*",- "@narratage/speech-alignment": "workspace:*",- "@narratage/speech-basis": "workspace:*",- "@narratage/speech-evidence": "workspace:*",- "@narratage/temporal": "workspace:*",- "@narratage/validation": "workspace:*",- "@narratage/visual-ir": "workspace:*"- }-}diff --git a/packages/video-domain/src/index.ts b/packages/video-domain/src/index.tsdeleted file mode 100644index a86b928b..00000000--- a/packages/video-domain/src/index.ts+++ /dev/null@@ -1,214 +0,0 @@-/**- * Every package a video Source may name, assembled into the registries a- * compiler needs.- *- * Nothing here is new behaviour. Each package already declares its own Types,- * Surfaces, Producers and Validators in its activation; this module only- * collects them so a caller that is not the CLI - a test, or a preview - can- * compile and execute a Source without a package lock, a filesystem scan or a- * Provider.- */--import { artifactManifest } from "@narratage/artifact";-import { compositionManifest } from "@narratage/composition";-import { mediaManifest } from "@narratage/media";-import { narrativeManifest } from "@narratage/narrative";-import { programSpaceManifest } from "@narratage/program-space";-import { semanticMapManifest } from "@narratage/semantic-map";-import { spatialManifest } from "@narratage/spatial";-import { speechManifest } from "@narratage/speech";-import { speechEvidenceManifest } from "@narratage/speech-evidence";-import { temporalManifest } from "@narratage/temporal";-import { generationManifest } from "@narratage/generation";-import { speechBasisManifest } from "@narratage/speech-basis";-import { speechAlignmentManifest } from "@narratage/speech-alignment";-import { visualIrManifest } from "@narratage/visual-ir";--import { existsSync, readdirSync, readFileSync } from "node:fs";-import { join, resolve } from "node:path";-import { pathToFileURL } from "node:url";--import { registerProducerFacets, registerTypeValidatorFacets } from "@narratage/component-kit";-import type { ComponentPackage } from "@narratage/component-kit";-import { createResolvedClosure } from "@narratage/core";-import { ProducerRegistry } from "@narratage/driver-node";-import {- AuthorFrontendRegistry, installAuthorFrontendHostFacets,-} from "@narratage/elaborator";-import { createMarkupAuthorFrontend, installMarkupSurfaceHostFacets, MarkupSurfaceRegistry } from "@narratage/markup";-import type { MarkupSurfaceRegistryLike } from "@narratage/markup";-import type { ModuleManifest, ModuleRef, ResolvedModuleClosure } from "@narratage/protocol";-import { TypeValidatorRegistry } from "@narratage/validation";--/**- * Types with no Surface of their own. A Source never writes these tags, but- * every Type a Surface produces has to resolve against something.- */-export const videoContractManifests = [- artifactManifest,- narrativeManifest,- mediaManifest,- programSpaceManifest,- speechManifest,- speechEvidenceManifest,- semanticMapManifest,- spatialManifest,- temporalManifest,- generationManifest,- speechBasisManifest,- speechAlignmentManifest,- visualIrManifest,- compositionManifest,-] as const;--/** The shape every package's `activation.ts` default-exports. */-export type VideoDomainPackage = {- readonly name: string;- readonly modules?: readonly {- readonly manifest: ModuleManifest;- /** Absent on packages a Source reaches through another module rather than by name. */- readonly specifiers?: readonly string[];- }[];- readonly components?: readonly ComponentPackage[];- readonly hostFacets?: readonly unknown[];- /** The directory it was discovered in; an activation does not name itself. */- readonly from?: string;- /** Sources that are not markup, such as a Style Sheet. */-};--/**- * Discover every installed package, the way the package loader does: each one- * declares where its activation lives in its own `package.json`, so this list- * is the workspace rather than a copy of it that can fall behind.- */-async function discover(): Promise<readonly VideoDomainPackage[]> {- if (discovered !== undefined) return discovered;- const root = resolve(import.meta.dirname, "../..");- const found: VideoDomainPackage[] = [];- for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {- if (!entry.isDirectory()) continue;- const manifestPath = join(root, entry.name, "package.json");- if (!existsSync(manifestPath)) continue;- const declared = JSON.parse(readFileSync(manifestPath, "utf8")) as {- readonly svml?: { readonly activation?: string };- };- if (declared.svml?.activation === undefined) continue;- const loaded = await import(pathToFileURL(join(root, entry.name, declared.svml.activation)).href) as- { readonly default?: VideoDomainPackage };- if (loaded.default !== undefined) found.push({ ...loaded.default, from: entry.name });- }- discovered = found;- return found;-}--let discovered: readonly VideoDomainPackage[] | undefined;--/** Every package a Source may `<import from="...">`. */-export async function videoDomainPackages(): Promise<readonly VideoDomainPackage[]> {- return await discover();-}--let cachedManifests: readonly ModuleManifest[] | undefined;--async function manifests(): Promise<readonly ModuleManifest[]> {- const seen = new Map<string, ModuleManifest>();- for (const manifest of videoContractManifests) seen.set(manifest.name, manifest);- for (const item of await discover()) {- for (const declared of item.modules ?? []) seen.set(declared.manifest.name, declared.manifest);- }- cachedManifests = [...seen.values()];- return cachedManifests;-}--async function components(): Promise<readonly ComponentPackage[]> {- // Every package that carries a Validator activates itself, so the discovery- // scan is the whole list; keyed by where it was found, because two packages- // may each contribute a Component at the same index.- const seen = new Map<string, ComponentPackage>();- for (const item of await discover()) {- for (const [index, component] of (item.components ?? []).entries()) {- seen.set(`${item.from}:${index}`, component);- }- }- return [...seen.values()];-}--/** The Types every Source in this domain may name. */-export async function videoDomainClosure(): Promise<ResolvedModuleClosure> {- return createResolvedClosure(await manifests());-}--/** The Surfaces that decode authored markup, keyed as the frontend looks them up. */-export async function videoDomainSurfaces(): Promise<MarkupSurfaceRegistry> {- const registry = new MarkupSurfaceRegistry();- for (const item of await discover()) {- installMarkupSurfaceHostFacets((item.hostFacets ?? []) as never, registry);- }- return registry;-}--/**- * Every Author Frontend a Source closure can reach: the markup frontend built- * over the Surfaces above, plus the packages that read a Source of their own- * rather than markup.- */-export async function videoDomainFrontends(- resolveModule: (request: { readonly from: string }) => ModuleRef,- /**- * The Surfaces the markup Frontend decodes with. A caller that wants to watch- * a decode passes its own registry over the discovered one; the Frontend is- * built the same way either way.- */- surfaces?: MarkupSurfaceRegistryLike,-): Promise<AuthorFrontendRegistry> {- const registry = new AuthorFrontendRegistry();- registry.register(createMarkupAuthorFrontend({- registry: surfaces ?? await videoDomainSurfaces(), resolveModule,- }) as never);- // A Frontend travels as a Host Facet, the same way a Surface does, so a- // package that publishes one is never asked to name it twice.- for (const item of await discover()) {- installAuthorFrontendHostFacets((item.hostFacets ?? []) as never, registry as never);- }- return registry;-}--/** The implementations behind every Producer a fragment can name. */-export async function videoDomainProducers(): Promise<ProducerRegistry> {- const registry = new ProducerRegistry();- for (const component of await components()) registerProducerFacets(registry, component.producers ?? []);- return registry;-}--/** The checks a Record must pass before it is admitted. */-export async function videoDomainValidators(): Promise<TypeValidatorRegistry> {- const registry = new TypeValidatorRegistry();- for (const component of await components()) registerTypeValidatorFacets(registry, component.validators ?? []);- return registry;-}--/**- * Resolve an `<import from="...">` specifier to the module that declares it.- * The specifiers are the ones each package publishes, so a Source that names a- * module this domain does not carry fails by name rather than silently.- */-export function videoDomainModule(specifier: string): ModuleRef | undefined {- if (discovered === undefined) {- throw new Error("videoDomainModule needs the domain discovered first; await videoDomainClosure().");- }- for (const item of discovered) {- for (const declared of item.modules ?? []) {- if ((declared.specifiers ?? []).includes(specifier)) {- return { name: declared.manifest.name, version: declared.manifest.version };- }- }- }- // A Source may also name a contract module directly, to write a Type it holds- // rather than a tag it declares.- for (const manifest of cachedManifests ?? []) {- if (specifier === manifest.name || specifier === `${manifest.name}@${manifest.version}`) {- return { name: manifest.name, version: manifest.version };- }- }- return undefined;-}diff --git a/packages/video-domain/test/compile.test.ts b/packages/video-domain/test/compile.test.tsdeleted file mode 100644index 77e270f3..00000000--- a/packages/video-domain/test/compile.test.ts+++ /dev/null@@ -1,82 +0,0 @@-import assert from "node:assert/strict";-import { createHash } from "node:crypto";-import { existsSync, readdirSync, readFileSync } from "node:fs";-import { dirname, join, resolve } from "node:path";-import test from "node:test";--import { compileSourceClosure } from "@narratage/elaborator";-import { createRecordAdmitter } from "@narratage/validation";--import {- videoDomainClosure, videoDomainFrontends, videoDomainModule, videoDomainValidators,-} from "../src/index.js";--const examples = resolve(import.meta.dirname, "../../../examples");--async function compile(entryPath: string): Promise<unknown> {- // Discovery has to run before a module can be resolved by name.- const closure = await videoDomainClosure();- return await compileSourceClosure({- entry: { id: entryPath, name: "main.svml", text: readFileSync(entryPath, "utf8") },- closure,- frontends: await videoDomainFrontends((request) => {- const found = videoDomainModule(request.from);- if (found === undefined) throw new Error(`no module for ${request.from}`);- return found;- }),- admitRecord: createRecordAdmitter(await videoDomainValidators()),- resolveSource(importer: { id: string }, request: { from: string }) {- const path = resolve(dirname(importer.id), request.from);- return { id: path, name: request.from, text: readFileSync(path, "utf8") };- },- resolveAsset(importer: { id: string }, request: { from: string; mediaType: string; bytes?: Uint8Array }) {- // A package Surface hands its own bytes over; an authored asset is a path- // beside the Source.- const bytes = request.bytes ?? readFileSync(resolve(dirname(importer.id), request.from));- return {- artifact: {- kind: "blob" as const,- digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,- size: bytes.byteLength,- mediaType: request.mediaType,- },- };- },- } as never);-}--/**- * Compile every committed example the way a build does.- *- * A Surface may only emit Types its manifest declares, and the frontend is the- * only thing that checks. Two packages shipped Surfaces that emitted more than- * they admitted, and nothing noticed because no Source here wrote those tags.- * `all-components-preview` writes every kind of Track for exactly that reason.- *- * A Surface is only exercised when a real Source names it, so a package can- * declare a tag whose Types or graph do not agree with what its handler emits- * and nothing notices. This is the test that notices: it needs no Provider, no- * lock and no filesystem beyond the example itself.- */-for (const name of readdirSync(examples, { withFileTypes: true })- .filter((entry) => entry.isDirectory())- .map((entry) => entry.name)- .sort()) {- const entryPath = join(examples, name, "main.svml");- if (!existsSync(entryPath)) continue;- test(`the ${name} example compiles`, async (context) => {- // Generated stills are deliberately not committed; the example READMEs say- // to supply them. Absent material is not a compiler failure.- const assets = join(examples, name, "assets");- if (existsSync(join(examples, name, "README.md"))- && readFileSync(entryPath, "utf8").includes("./assets/")- && !existsSync(assets)) {- context.skip(`${name} needs assets that are not committed`);- return;- }- const compiled = await compile(entryPath) as {- graph: { outputs: readonly unknown[] };- };- assert.ok(compiled.graph.outputs.length >= 0);- });-}diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex f371acbd..46a16c99 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -2708,72 +2708,6 @@ importers:specifier: workspace:*version: link:../workspace-fs-node- packages/video-domain:- dependencies:- '@narratage/artifact':- specifier: workspace:*- version: link:../artifact- '@narratage/component-kit':- specifier: workspace:*- version: link:../component-kit- '@narratage/composition':- specifier: workspace:*- version: link:../composition- '@narratage/core':- specifier: workspace:*- version: link:../core- '@narratage/driver-node':- specifier: workspace:*- version: link:../driver-node- '@narratage/elaborator':- specifier: workspace:*- version: link:../elaborator- '@narratage/generation':- specifier: workspace:*- version: link:../generation- '@narratage/markup':- specifier: workspace:*- version: link:../markup- '@narratage/media':- specifier: workspace:*- version: link:../media- '@narratage/narrative':- specifier: workspace:*- version: link:../narrative- '@narratage/program-space':- specifier: workspace:*- version: link:../program-space- '@narratage/protocol':- specifier: workspace:*- version: link:../protocol- '@narratage/semantic-map':- specifier: workspace:*- version: link:../semantic-map- '@narratage/spatial':- specifier: workspace:*- version: link:../spatial- '@narratage/speech':- specifier: workspace:*- version: link:../speech- '@narratage/speech-alignment':- specifier: workspace:*- version: link:../speech-alignment- '@narratage/speech-basis':- specifier: workspace:*- version: link:../speech-basis- '@narratage/speech-evidence':- specifier: workspace:*- version: link:../speech-evidence- '@narratage/temporal':- specifier: workspace:*- version: link:../temporal- '@narratage/validation':- specifier: workspace:*- version: link:../validation- '@narratage/visual-ir':- specifier: workspace:*- version: link:../visual-ir-packages/visual-ir:dependencies:'@narratage/protocol':@@ -2913,12 +2847,24 @@ importers:tools/svml-playground:dependencies:+ '@narratage/audio-track':+ specifier: workspace:*+ version: link:../../packages/audio-track+ '@narratage/background-removal':+ specifier: workspace:*+ version: link:../../packages/background-removal'@narratage/caption':specifier: workspace:*version: link:../../packages/caption'@narratage/caption-fine':specifier: workspace:*version: link:../../packages/caption-fine+ '@narratage/caption-gemini':+ specifier: workspace:*+ version: link:../../packages/caption-gemini+ '@narratage/comment-sticker':+ specifier: workspace:*+ version: link:../../packages/comment-sticker'@narratage/compiler-node':specifier: workspace:*version: link:../../packages/compiler-node@@ -2931,6 +2877,9 @@ importers:'@narratage/core':specifier: workspace:*version: link:../../packages/core+ '@narratage/deck-track':+ specifier: workspace:*+ version: link:../../packages/deck-track'@narratage/driver-node':specifier: workspace:*version: link:../../packages/driver-node@@ -2949,21 +2898,51 @@ importers:'@narratage/fonts-open':specifier: workspace:*version: link:../../packages/fonts-open+ '@narratage/gemini-omni':+ specifier: workspace:*+ version: link:../../packages/gemini-omni+ '@narratage/gpt-image':+ specifier: workspace:*+ version: link:../../packages/gpt-image+ '@narratage/grok-imagine':+ specifier: workspace:*+ version: link:../../packages/grok-imagine'@narratage/hyperframes':specifier: workspace:*version: link:../../packages/hyperframes+ '@narratage/image-compose':+ specifier: workspace:*+ version: link:../../packages/image-compose+ '@narratage/image-transform':+ specifier: workspace:*+ version: link:../../packages/image-transform'@narratage/markup':specifier: workspace:*version: link:../../packages/markup'@narratage/media':specifier: workspace:*version: link:../../packages/media+ '@narratage/media-pipeline':+ specifier: workspace:*+ version: link:../../packages/media-pipeline'@narratage/media-track':specifier: workspace:*version: link:../../packages/media-track+ '@narratage/mimo-tts':+ specifier: workspace:*+ version: link:../../packages/mimo-tts+ '@narratage/minimax-h3':+ specifier: workspace:*+ version: link:../../packages/minimax-h3+ '@narratage/nano-banana':+ specifier: workspace:*+ version: link:../../packages/nano-banana'@narratage/narrative':specifier: workspace:*version: link:../../packages/narrative+ '@narratage/package-loader-node':+ specifier: workspace:*+ version: link:../../packages/package-loader-node'@narratage/program-space':specifier: workspace:*version: link:../../packages/program-space@@ -2982,6 +2961,9 @@ importers:'@narratage/ranking':specifier: workspace:*version: link:../../packages/ranking+ '@narratage/render-hyperframes':+ specifier: workspace:*+ version: link:../../packages/render-hyperframes'@narratage/run':specifier: workspace:*version: link:../../packages/run@@ -2991,27 +2973,45 @@ importers:'@narratage/runtime':specifier: workspace:*version: link:../../packages/runtime+ '@narratage/screen-overlay':+ specifier: workspace:*+ version: link:../../packages/screen-overlay'@narratage/script':specifier: workspace:*version: link:../../packages/script+ '@narratage/seedance':+ specifier: workspace:*+ version: link:../../packages/seedance+ '@narratage/seedream':+ specifier: workspace:*+ version: link:../../packages/seedream'@narratage/semantic-map':specifier: workspace:*version: link:../../packages/semantic-map'@narratage/spatial':specifier: workspace:*version: link:../../packages/spatial+ '@narratage/speech-spine':+ specifier: workspace:*+ version: link:../../packages/speech-spine'@narratage/svs':specifier: workspace:*version: link:../../packages/svs'@narratage/temporal':specifier: workspace:*version: link:../../packages/temporal+ '@narratage/text':+ specifier: workspace:*+ version: link:../../packages/text+ '@narratage/typography-track':+ specifier: workspace:*+ version: link:../../packages/typography-track'@narratage/validation':specifier: workspace:*version: link:../../packages/validation- '@narratage/video-domain':+ '@narratage/whisperx':specifier: workspace:*- version: link:../../packages/video-domain+ version: link:../../packages/whisperxvite:specifier: 5.4.21version: 5.4.21(@types/[email protected])diff --git a/tools/svml-playground/README.md b/tools/svml-playground/README.mdindex f53ac2e3..20cd1b1e 100644--- a/tools/svml-playground/README.md+++ b/tools/svml-playground/README.md@@ -1,90 +1,35 @@# SVML Playground-A read-only preview of one `.svml` Source: the code on the right, the picture-top-left, and a timeline bottom-left rendered from the Source itself.+A read-only official preview application for one `.svml` Author Source.```bashpnpm svml:playground -- --source examples/talking-film-broll-preview/main.svml# ➜ http://localhost:5179/```-Optional: `--run <build.svrun>` to read material a Run Source already names, and-`--port <number>`.+Optional arguments:-Selecting works from any of the three panes and selects in all of them: click a-timeline clip, marked text in the source, or the picture itself. Lines that bind-a clip carry a coloured bar in the gutter.+- `--run <build.svrun>` reads material and timings explicitly selected by a Run Source.+- `--runtime <svml.runtime.json>` opens earlier Build records and Artifacts read-only.+- `--port <number>` changes the listening port from `5179`.-A Segment encloses a Selection, which can enclose another. Each level has its-own colour, and an enclosing range stays outlined while an inner one is — the-nesting is what the markers are for. Everything the playhead is inside is-outlined as it passes, and clicking marked prose lands inside the marker you-clicked rather than at the start of whatever encloses it.+The Playground never writes a Source, Recipe, Build or Artifact and never calls+a paid Provider. Missing generation results are shown as declared stand-ins;+missing speech timings are visibly estimated.-`Space` plays and pauses, `←` and `→` step a frame with `Shift` ten, `Home` and-`End` jump to the ends, `Esc` clears. The Speech Spine's material sounds during-playback; the speaker button turns it off.+## Package boundary-## What it is for+The Playground is an application, not a registry required by Narratage. It+explicitly depends on the official video packages it can preview and loads the+same activation, Frontends, Surfaces, Producers and Validators that a normal+Host loads. No compiler, Runtime or video package imports the Playground, and+normal production works identically when it is not installed.-Reading a Source as a timeline **before** anything has been generated. It answers-"where does this B-roll land, how long is it, and is the card in the right part-of the frame" without a Seedance generation, a WhisperX alignment, an FFmpeg-render or a headless browser.+The compiled Source remains the authority. The application asks it for every+`VisualTrack` and `AudioTrack`, builds each independently, and renders the+result with HyperFrames. A new Track from an already bundled package therefore+needs no Playground-specific implementation. A newly published official video+package is added to this application's dependency list in its next release.-It never writes. There is no route that can change what an author wrote, and no-form that edits a Recipe — that is the Caption Playground's job, not this one.--## What is real and what is estimated--Everything structural is real. Placement Frames, padding, stacking order, motion-and the Track layout are computed by the same functions the build calls, from the-Source and its style sheet.--**Timings prefer real things,** in this order, and the header badges say which-you are looking at:--1. A completed build in `.svml/state.sqlite` — its `timing.map` and- `speech.space` replace the estimate outright, and its `final.video` becomes- the picture.-2. A Run Source — `<file>` bound by `<satisfy>` is material you already have, so- it can be the picture with no build at all.-3. The Script text — token windows from `@narratage/estimate`, the same- delivery-density model the pipeline uses before generation.--Real cut points move once WhisperX has aligned real audio, so treat an estimated-timeline as a proportion, not a prediction. If a store is from a newer schema, or-its build never completed, the Playground falls back to estimates rather than-showing a measured timeline it cannot vouch for.--**Material degrades one element at a time.** A Take or an Item shows real frames-when its source already exists and already lives in the program's frame domain,-and a painted rectangle when it does not. Reading a file's frame rate needs-`ffprobe` on the path; without it every Item keeps its placeholder and says so. Normalizing footage of another frame-rate is the media pipeline's job and takes a real transcode, so the preview-refuses and says which file and why rather than quietly resampling.--## How it reads a Source--A shallow interpreter, not the compiler. It walks the authored markup with-`@narratage/markup`'s own parser and calls each package's own pure projection-functions — `frameFromEdges`, `appendSelectionMediaItem`, `finalizeMediaTrack`,-`projectMediaVisualTrack`. It never elaborates the graph, never resolves a-package lock, and never constructs a Host, so it runs on a directory containing-nothing but `main.svml` and `studio.svs`.--Interpreted: `<script>`, the Spatial Frames, `<speech:Spine>` and its Takes,-`<media-track:Track>` and its Items, `<fonts:Stack>`, `<caption-fine:Style>` and-`<caption-fine:Track>`, `<film:Film>` (for the clear colour), and `.svs` source-imports.--Everything else — every generation Surface, `<whisperx:Alignment>`, the-Typography Tracks, `<render:Video>` — is read, listed under "not projected",-and skipped. A Source is worth previewing even when most of-it is produced by Providers.--## A note on `<space:Frame>`--`right` and `bottom` are **absolute edge positions**, not insets. A Frame-spanning the middle 80% of its parent is `left="8%" right="92%"`, not-`left="8%" right="8%"` — the latter resolves to zero width and is rejected.+See [the complete guide](../../docs/guide/svml-playground.md) for selection,+timeline, stand-in and measured-timing behavior.diff --git a/tools/svml-playground/package.json b/tools/svml-playground/package.jsonindex 8a1f01c8..f859d820 100644--- a/tools/svml-playground/package.json+++ b/tools/svml-playground/package.json@@ -4,39 +4,61 @@"private": true,"type": "module","dependencies": {+ "@narratage/audio-track": "workspace:*",+ "@narratage/background-removal": "workspace:*","@narratage/caption": "workspace:*","@narratage/caption-fine": "workspace:*",+ "@narratage/caption-gemini": "workspace:*",+ "@narratage/comment-sticker": "workspace:*","@narratage/compiler-node": "workspace:*","@narratage/component-kit": "workspace:*","@narratage/composition": "workspace:*","@narratage/core": "workspace:*",+ "@narratage/deck-track": "workspace:*","@narratage/driver-node": "workspace:*","@narratage/elaborator": "workspace:*","@narratage/endpoint-kit": "workspace:*","@narratage/estimate": "workspace:*","@narratage/film": "workspace:*","@narratage/fonts-open": "workspace:*",+ "@narratage/gemini-omni": "workspace:*",+ "@narratage/gpt-image": "workspace:*",+ "@narratage/grok-imagine": "workspace:*","@narratage/hyperframes": "workspace:*",+ "@narratage/image-compose": "workspace:*",+ "@narratage/image-transform": "workspace:*","@narratage/markup": "workspace:*","@narratage/media": "workspace:*",+ "@narratage/media-pipeline": "workspace:*","@narratage/media-track": "workspace:*",+ "@narratage/mimo-tts": "workspace:*",+ "@narratage/minimax-h3": "workspace:*",+ "@narratage/nano-banana": "workspace:*","@narratage/narrative": "workspace:*",+ "@narratage/package-loader-node": "workspace:*","@narratage/program-space": "workspace:*","@narratage/protocol": "workspace:*","@narratage/provider-hyperframes-local": "workspace:*","@narratage/provider-media-local": "workspace:*","@narratage/provider-whisperx-local": "workspace:*","@narratage/ranking": "workspace:*",+ "@narratage/render-hyperframes": "workspace:*","@narratage/run": "workspace:*","@narratage/run-markup": "workspace:*","@narratage/runtime": "workspace:*",+ "@narratage/screen-overlay": "workspace:*","@narratage/script": "workspace:*",+ "@narratage/seedance": "workspace:*",+ "@narratage/seedream": "workspace:*","@narratage/semantic-map": "workspace:*","@narratage/spatial": "workspace:*",+ "@narratage/speech-spine": "workspace:*","@narratage/svs": "workspace:*","@narratage/temporal": "workspace:*",+ "@narratage/text": "workspace:*",+ "@narratage/typography-track": "workspace:*","@narratage/validation": "workspace:*",- "@narratage/video-domain": "workspace:*",+ "@narratage/whisperx": "workspace:*","vite": "5.4.21"}}diff --git a/tools/svml-playground/src/official-video.ts b/tools/svml-playground/src/official-video.tsnew file mode 100644index 00000000..34f0216b--- /dev/null+++ b/tools/svml-playground/src/official-video.ts@@ -0,0 +1,131 @@+/**+ * The official video packages understood by this preview application.+ *+ * This is deliberately application-local composition. Narratage packages do+ * not register themselves with a central video catalogue and do not know that+ * the Playground exists. The Playground chooses the packages it previews,+ * then reads the activation each package already publishes for normal Hosts.+ */+import { registerProducerFacets, registerTypeValidatorFacets } from "@narratage/component-kit";+import { createResolvedClosure } from "@narratage/core";+import { ProducerRegistry } from "@narratage/driver-node";+import {+ AuthorFrontendRegistry,+ installAuthorFrontendHostFacets,+} from "@narratage/elaborator";+import {+ createMarkupAuthorFrontend,+ installMarkupSurfaceHostFacets,+ MarkupSurfaceRegistry,+} from "@narratage/markup";+import type { MarkupSurfaceRegistryLike } from "@narratage/markup";+import { createNodePackageInventory } from "@narratage/package-loader-node";+import type { ModuleRef, ResolvedModuleClosure } from "@narratage/protocol";+import { TypeValidatorRegistry } from "@narratage/validation";++const OFFICIAL_VIDEO_PACKAGES = [+ "@narratage/audio-track",+ "@narratage/background-removal",+ "@narratage/caption",+ "@narratage/caption-fine",+ "@narratage/caption-gemini",+ "@narratage/comment-sticker",+ "@narratage/deck-track",+ "@narratage/estimate",+ "@narratage/film",+ "@narratage/fonts-open",+ "@narratage/gemini-omni",+ "@narratage/gpt-image",+ "@narratage/grok-imagine",+ "@narratage/image-compose",+ "@narratage/image-transform",+ "@narratage/media",+ "@narratage/media-pipeline",+ "@narratage/media-track",+ "@narratage/mimo-tts",+ "@narratage/minimax-h3",+ "@narratage/nano-banana",+ "@narratage/ranking",+ "@narratage/render-hyperframes",+ "@narratage/screen-overlay",+ "@narratage/script",+ "@narratage/seedance",+ "@narratage/seedream",+ "@narratage/spatial",+ "@narratage/speech-spine",+ "@narratage/svs",+ "@narratage/text",+ "@narratage/typography-track",+ "@narratage/whisperx",+] as const;++type OfficialVideoDomain = {+ readonly closure: ResolvedModuleClosure;+ readonly surfaces: MarkupSurfaceRegistry;+ readonly producers: ProducerRegistry;+ readonly validators: TypeValidatorRegistry;+ readonly resolveModule: (specifier: string) => ModuleRef | undefined;+ readonly frontends: (surfaces?: MarkupSurfaceRegistryLike) => AuthorFrontendRegistry;+};++let loading: Promise<OfficialVideoDomain> | undefined;++async function loadOfficialVideoDomain(): Promise<OfficialVideoDomain> {+ const loaded = await createNodePackageInventory(OFFICIAL_VIDEO_PACKAGES, import.meta.dirname);+ const contributions = loaded.packages.map((item) => item.contribution);+ const manifests = contributions.flatMap((item) =>+ (item.modules ?? []).map((module) => module.manifest));+ const closure = createResolvedClosure(manifests);++ const modules = new Map<string, ModuleRef>();+ for (const contribution of contributions) {+ for (const module of contribution.modules ?? []) {+ const ref = { name: module.manifest.name, version: module.manifest.version };+ for (const specifier of [+ module.manifest.name,+ `${module.manifest.name}@${module.manifest.version}`,+ ...(module.specifiers ?? []),+ ]) modules.set(specifier, ref);+ }+ }+ const resolveModule = (specifier: string): ModuleRef | undefined => modules.get(specifier);++ const facets = contributions.flatMap((item) => item.hostFacets ?? []);+ const surfaces = new MarkupSurfaceRegistry();+ installMarkupSurfaceHostFacets(facets, surfaces);++ const components = contributions.flatMap((item) => item.components ?? []);+ const producers = new ProducerRegistry();+ const validators = new TypeValidatorRegistry();+ for (const component of components) {+ registerProducerFacets(producers, component.producers ?? []);+ registerTypeValidatorFacets(validators, component.validators ?? []);+ }++ return {+ closure,+ surfaces,+ producers,+ validators,+ resolveModule,+ frontends(registry = surfaces) {+ const frontends = new AuthorFrontendRegistry();+ frontends.register(createMarkupAuthorFrontend({+ registry,+ resolveModule(request) {+ const found = resolveModule(request.from);+ if (found === undefined) throw new Error(`No official preview package declares ${request.from}.`);+ return found;+ },+ }));+ installAuthorFrontendHostFacets(facets, frontends);+ return frontends;+ },+ };+}++/** Load the preview application's package composition once per process. */+export async function officialVideoDomain(): Promise<OfficialVideoDomain> {+ loading ??= loadOfficialVideoDomain();+ return await loading;+}diff --git a/tools/svml-playground/src/pipeline/compile.ts b/tools/svml-playground/src/pipeline/compile.tsindex 5c25546b..fce9ddae 100644--- a/tools/svml-playground/src/pipeline/compile.ts+++ b/tools/svml-playground/src/pipeline/compile.ts@@ -12,11 +12,8 @@ import { dirname, isAbsolute, relative, resolve } from "node:path";import { compileSourceClosure, resolveCompiledSourceExport } from "@narratage/elaborator";import type { Digest } from "@narratage/protocol";import { createRecordAdmitter } from "@narratage/validation";-import {- videoDomainClosure, videoDomainFrontends, videoDomainModule, videoDomainSurfaces,- videoDomainValidators,-} from "@narratage/video-domain";+import { officialVideoDomain } from "../official-video.js";import { createObserver } from "./observe.js";import type { Observations } from "./observe.js";@@ -66,27 +63,26 @@ function digestOfBytes(bytes: Uint8Array): Digest {}export async function compileSource(entryPath: string): Promise<CompiledSource> {+ const domain = await officialVideoDomain();const served = new Map<string, ServedFile>();// Everything a Source reads has to sit beside it, as it must in a build.const root = dirname(entryPath);const resolveModule = (request: { readonly from: string }) => {- const found = videoDomainModule(request.from);+ const found = domain.resolveModule(request.from);if (found === undefined) {throw new CompileFailure(`No package in this preview declares ${request.from}.`);}return found;};- // Discovery has to run before a module can be resolved by name.- const closure = await videoDomainClosure();- const observer = createObserver(await videoDomainSurfaces(), resolveModule);+ const observer = createObserver(domain.surfaces, resolveModule);let compiled: CompiledClosure;try {compiled = await compileSourceClosure({entry: { id: entryPath, name: "main.svml", text: readFileSync(entryPath, "utf8") },- closure,- frontends: await videoDomainFrontends(resolveModule, observer.surfaces),- admitRecord: createRecordAdmitter(await videoDomainValidators()),+ closure: domain.closure,+ frontends: domain.frontends(observer.surfaces),+ admitRecord: createRecordAdmitter(domain.validators),resolveSource(importer: { readonly id: string }, request: { readonly from: string }) {const path = resolve(dirname(importer.id), request.from);return { id: path, name: request.from, text: readFileSync(path, "utf8") };diff --git a/tools/svml-playground/src/pipeline/execute.ts b/tools/svml-playground/src/pipeline/execute.tsindex f0097936..263e4005 100644--- a/tools/svml-playground/src/pipeline/execute.ts+++ b/tools/svml-playground/src/pipeline/execute.ts@@ -13,7 +13,8 @@ import type { BuildState } from "@narratage/protocol";import { createLocalHyperframesProvider } from "@narratage/provider-hyperframes-local";import { createLocalMediaProvider } from "@narratage/provider-media-local";import { createLocalWhisperXProvider } from "@narratage/provider-whisperx-local";-import { videoDomainProducers, videoDomainValidators } from "@narratage/video-domain";++import { officialVideoDomain } from "../official-video.js";/** A Capability no Provider on this machine could answer. */export type Unserved = { readonly capability: string; readonly count: number };@@ -56,9 +57,10 @@ async function endpoints(): Promise<EndpointRegistry> {}export async function execute(planned: BuildState, artifacts: ArtifactStore): Promise<Executed> {+ const domain = await officialVideoDomain();const result = await new NodeDriver({- producers: await videoDomainProducers(),- validators: await videoDomainValidators(),+ producers: domain.producers,+ validators: domain.validators,endpoints: await endpoints(),artifacts,}).run(planned);diff --git a/tools/svml-playground/src/pipeline/preview.ts b/tools/svml-playground/src/pipeline/preview.tsindex 1131715a..7e49d990 100644--- a/tools/svml-playground/src/pipeline/preview.ts+++ b/tools/svml-playground/src/pipeline/preview.ts@@ -10,9 +10,9 @@import { createHash } from "node:crypto";import { createProvidedCandidate } from "@narratage/run";-import { videoDomainClosure, videoDomainValidators } from "@narratage/video-domain";import { validateValue } from "@narratage/validation";+import { officialVideoDomain } from "../official-video.js";import { compileSource } from "./compile.js";import type { CompiledSource, ServedFile } from "./compile.js";import type { Placement } from "./observe.js";@@ -125,6 +125,7 @@ export async function preview(runPath?: string,archive?: Archive,): Promise<Preview> {+ const domain = await officialVideoDomain();const source = await compileSource(entryPath);let base: RunPlan;@@ -186,15 +187,13 @@ export async function preview();anchors = new Map((estimated.map as { anchors: readonly { identity: string; frame: number }[] }).anchors.map((anchor) => [anchor.identity, anchor.frame]));- const closure = await videoDomainClosure();- const validators = await videoDomainValidators();const added: unknown[] = [];const satisfactions = [...base.run.graph.satisfactions];for (const output of unsaid) {const supplied = output.type === TIMING ? estimated.map : estimated.space;const type = outputType(source, output.ref);const stored = { kind: "inline" as const, value: supplied as never };- const validation = await validateValue(closure, type as never, stored, validators);+ const validation = await validateValue(domain.closure, type as never, stored, domain.validators);const candidate = createProvidedCandidate({type: type as never,value: stored,@@ -332,8 +331,6 @@ export async function preview(? undefined: inlineRecord(source.compiled, programExport.ref) as { runs?: readonly never[] } | undefined;if (hasAtoms(sequence) && Array.isArray(program?.runs) && program.runs.length > 0) {- const closure = await videoDomainClosure();- const validators = await videoDomainValidators();const added = new Map<string, unknown>(run.graph.candidates.map((item) => [(item as { id: string }).id, item]));const satisfactions = [...run.graph.satisfactions];@@ -341,7 +338,7 @@ export async function preview(const plan = evenCaptionPlan(sequence, program as never);const type = outputType(source, output.ref);const stored = { kind: "inline" as const, value: plan as never };- const validation = await validateValue(closure, type as never, stored, validators);+ const validation = await validateValue(domain.closure, type as never, stored, domain.validators);const candidate = createProvidedCandidate({type: type as never, value: stored,...(validation === undefined ? {} : { validation }),diff --git a/tools/svml-playground/src/pipeline/run-source.ts b/tools/svml-playground/src/pipeline/run-source.tsindex 8bbc0eae..e00d2b92 100644--- a/tools/svml-playground/src/pipeline/run-source.ts+++ b/tools/svml-playground/src/pipeline/run-source.ts@@ -18,8 +18,8 @@ import {compileRunSource, RunFragmentRegistry, RunFrontendRegistry, resolveRunDocument,} from "@narratage/run";import { runMarkupFrontend } from "@narratage/run-markup";-import { videoDomainClosure, videoDomainValidators } from "@narratage/video-domain";+import { officialVideoDomain } from "../official-video.js";import type { Archive } from "./archive.js";import type { ServedFile } from "./compile.js";@@ -55,10 +55,11 @@ async function planner(source: string,authorSource: string,): Promise<RunPlan["plan"]> {+ const domain = await officialVideoDomain();const frontends = new RunFrontendRegistry();frontends.register(runMarkupFrontend);const compiler = new NodeRunCompiler({- frontends, closure: await videoDomainClosure(), validators: await videoDomainValidators(),+ frontends, closure: domain.closure, validators: domain.validators,} as never);return (run, targets) => compiler.planCompilation({source,diff --git a/tools/svml-playground/start.ts b/tools/svml-playground/start.tsindex 2a535642..22d75f6e 100644--- a/tools/svml-playground/start.ts+++ b/tools/svml-playground/start.ts@@ -48,7 +48,9 @@ const run = runArgument === undefined ? undefined : resolve(invokedFrom, runArgu// Source that reuses an accepted take needs one.const runtimeArgument = values.get("runtime");const runtime = runtimeArgument === undefined ? undefined : resolve(invokedFrom, runtimeArgument);-const packageRoot = resolve(repoRoot, "packages/video-cli/src");+// Runtime packages belong to the project that selected them. Pointing into the+// Narratage monorepo would make the preview work here and fail once installed.+const packageRoot = invokedFrom;const port = Number(values.get("port") ?? "5179");if (!Number.isSafeInteger(port) || port <= 0) usage("--port must be a positive integer");