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
docs: rewrite quickstart and develop guides, split site themes
rpone92a6c2af89aa
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex a8ff2fc2..e32e54ce 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -1,27 +1,5 @@import { defineConfig } from "vitepress";-const noctisBordo = {- name: "narratage-noctis-bordo",- type: "dark" as const,- colors: {- "editor.background": "#322A2D",- "editor.foreground": "#CBBEC2",- },- settings: [- { settings: { background: "#322A2D", foreground: "#CBBEC2" } },- { scope: ["comment", "punctuation.definition.comment"], settings: { foreground: "#715B63" } },- { scope: ["string", "string.quoted", "punctuation.definition.string"], settings: { foreground: "#49E9A6" } },- { scope: ["keyword", "storage", "storage.type", "storage.modifier"], settings: { foreground: "#E66533" } },- { scope: ["entity.name.tag", "punctuation.definition.tag", "meta.tag punctuation"], settings: { foreground: "#E66533" } },- { scope: ["entity.other.attribute-name", "support.type.property-name", "variable.other.property"], settings: { foreground: "#D5971A" } },- { scope: ["constant", "constant.numeric", "constant.language", "constant.character"], settings: { foreground: "#E4B781" } },- { scope: ["entity.name.function", "support.function", "meta.function-call"], settings: { foreground: "#49D6E9" } },- { scope: ["entity.name.type", "entity.name.class", "support.class", "support.type"], settings: { foreground: "#7060EB" } },- { scope: ["variable", "identifier"], settings: { foreground: "#CBBEC2" } },- { scope: ["invalid", "invalid.illegal"], settings: { foreground: "#FFB3CD" } },- ],-};-const sharedTheme = {siteTitle: "NARRATAGE",socialLinks: [{ icon: "github" as const, link: "https://github.com/cashdiffusion/svml" }],@@ -32,7 +10,7 @@ const enTheme = {...sharedTheme,nav: [{ text: "Quickstart", link: "/quickstart" },- { text: "Develop", link: "/guide/components" },+ { text: "Develop", link: "/guide/develop" },],sidebar: {"/quickstart": [@@ -42,8 +20,14 @@ const enTheme = {{text: "Develop",items: [- { text: "Components", link: "/guide/components" },- { text: "Runtime & Providers", link: "/guide/runtime" },+ { text: "Overview", link: "/guide/develop" },+ { text: "Package Architecture", link: "/guide/packages" },+ { text: "Adding an Author Package", link: "/guide/author-packages" },+ { text: "Adding a Provider", link: "/guide/providers" },+ { text: "Runtime Profile", link: "/guide/runtime-profile" },+ { text: "Local Services", link: "/guide/services" },+ { text: "Testing", link: "/guide/testing" },+ { text: "Conventions", link: "/guide/conventions" },],},],@@ -56,7 +40,7 @@ const zhTheme = {...sharedTheme,nav: [{ text: "快速开始", link: "/zh/quickstart" },- { text: "开发指南", link: "/zh/guide/components" },+ { text: "开发指南", link: "/zh/guide/develop" },],sidebar: {"/zh/quickstart": [@@ -66,8 +50,14 @@ const zhTheme = {{text: "开发指南",items: [- { text: "创建组件", link: "/zh/guide/components" },- { text: "运行时与 Provider", link: "/zh/guide/runtime" },+ { text: "概览", link: "/zh/guide/develop" },+ { text: "包架构", link: "/zh/guide/packages" },+ { text: "添加 Author 包", link: "/zh/guide/author-packages" },+ { text: "添加 Provider", link: "/zh/guide/providers" },+ { text: "Runtime Profile", link: "/zh/guide/runtime-profile" },+ { text: "本地服务", link: "/zh/guide/services" },+ { text: "测试", link: "/zh/guide/testing" },+ { text: "代码规范", link: "/zh/guide/conventions" },],},],@@ -81,12 +71,16 @@ export default defineConfig({lang: "en-US",title: "Narratage",description: "Write the story. Compile the video.",- appearance: false,+ appearance: true,cleanUrls: true,+ // Contributor-facing indexes of repository files, not site pages: they link to+ // ../spec, ../packages, ../services and ../examples, which resolve when browsing+ // the repository but have no route on the published site.+ srcExclude: ["README.md", "implementation-status.md"],markdown: {theme: {- light: noctisBordo,- dark: noctisBordo,+ light: "github-light",+ dark: "github-dark",},languageAlias: {svml: "xml",@@ -100,7 +94,7 @@ export default defineConfig({["script",{},- `(function(){var p=location.pathname,b="/docs/",k="narratage-locale",h="narratage-hero-intro-seen",l;try{if(sessionStorage.getItem(h)==="1")document.documentElement.classList.add("hero-intro-seen");l=localStorage.getItem(k)}catch(e){}if(!l)l=(navigator.language||"").toLowerCase().indexOf("zh")===0?"zh":"en";if(p===b&&l==="zh")location.replace(b+"zh/"+location.search+location.hash)})()`,+ `(function(){var p=location.pathname,b="/docs/",k="narratage-locale",h="narratage-hero-intro-seen",l;try{if(sessionStorage.getItem(h)==="1")document.documentElement.classList.add("hero-intro-seen");l=localStorage.getItem(k)}catch(e){}if(!l)l=(navigator.language||"").toLowerCase().indexOf("zh")===0?"zh":"en";if(p===b||p===b+"zh/"||p===b.slice(0,-1)||p===b+"zh")document.documentElement.classList.add("home-page");if(p===b&&l==="zh")location.replace(b+"zh/"+location.search+location.hash)})()`,],["link", { rel: "preconnect", href: "https://fonts.googleapis.com" }],["link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "" }],diff --git a/docs/.vitepress/theme/HomeThemeScope.ts b/docs/.vitepress/theme/HomeThemeScope.tsnew file mode 100644index 00000000..8804f85f--- /dev/null+++ b/docs/.vitepress/theme/HomeThemeScope.ts@@ -0,0 +1,19 @@+import { watchEffect, type Ref } from "vue";++const HOME_CLASS = "home-page";++/**+ * The home page keeps the branded always-dark design; documentation pages use the+ * stock VitePress theme with the light/dark toggle. All branded styling is scoped to+ * `html.home-page`, so the flag has to live on the document element — `html` and `body`+ * backgrounds sit outside the theme's `.Layout` root and cannot be scoped from inside it.+ *+ * The matching inline script in `config.ts` sets the same class before first paint;+ * this keeps it in sync across client-side navigation.+ */+export function useHomeThemeScope(isHome: Ref<boolean>): void {+ if (typeof document === "undefined") return;+ watchEffect(() => {+ document.documentElement.classList.toggle(HOME_CLASS, isHome.value);+ });+}diff --git a/docs/.vitepress/theme/Layout.vue b/docs/.vitepress/theme/Layout.vuenew file mode 100644index 00000000..afed1c27--- /dev/null+++ b/docs/.vitepress/theme/Layout.vue@@ -0,0 +1,22 @@+<script setup lang="ts">+import DefaultTheme from "vitepress/theme";+import { useData } from "vitepress";+import { computed } from "vue";+import HeroStatement from "./components/HeroStatement.vue";+import LocalePreference from "./components/LocalePreference.vue";+import { useHomeThemeScope } from "./HomeThemeScope";++const DefaultLayout = DefaultTheme.Layout;++const { frontmatter } = useData();+const isHome = computed(() => frontmatter.value.layout === "home");++useHomeThemeScope(isHome);+</script>++<template>+ <DefaultLayout>+ <template #layout-top><LocalePreference /></template>+ <template #home-hero-info><HeroStatement /></template>+ </DefaultLayout>+</template>diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.tsindex f61013a1..245f1347 100644--- a/docs/.vitepress/theme/index.ts+++ b/docs/.vitepress/theme/index.ts@@ -1,18 +1,12 @@import DefaultTheme from "vitepress/theme";import type { Theme } from "vitepress";-import { h } from "vue";-import HeroStatement from "./components/HeroStatement.vue";-import LocalePreference from "./components/LocalePreference.vue";+import Layout from "./Layout.vue";import SvmlDemoCarousel from "./components/SvmlDemoCarousel.vue";import "./style.css";export default {extends: DefaultTheme,- Layout: () =>- h(DefaultTheme.Layout, null, {- "layout-top": () => h(LocalePreference),- "home-hero-info": () => h(HeroStatement),- }),+ Layout,enhanceApp({ app }) {app.component("SvmlDemoCarousel", SvmlDemoCarousel);},diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.cssindex 1c88f8a6..c47f1b3a 100644--- a/docs/.vitepress/theme/style.css+++ b/docs/.vitepress/theme/style.css@@ -1,5 +1,12 @@-:root,-.dark {+/*+ * Home page keeps the branded, always-dark editorial design and has no appearance+ * toggle. Documentation pages use the stock VitePress theme with light/dark support.+ *+ * Everything branded is scoped to `html.home-page`, set before first paint by the inline+ * script in config.ts and kept in sync across navigation by theme/Layout.vue.+ */++html.home-page {--paper: #2C2126;--paper-light: #3D2A33;--paper-deep: #3D2A33;@@ -42,26 +49,33 @@--vp-code-copy-code-hover-border-color: #49D6E9;--vp-code-copy-code-hover-bg: #272022;--vp-code-copy-code-active-text: #49E9A6;+ background: var(--paper);}-html { background: var(--paper); }.hero-statement-viewport-zh.is-locale-hidden { height: 0 !important; margin-top: 0; visibility: hidden; opacity: 0 !important; transform: none !important; pointer-events: none; }-body {++html.home-page body {background: var(--paper);color: var(--ink);font-optical-sizing: auto;letter-spacing: 0;}-* { scrollbar-width: auto; scrollbar-color: #EB609155 transparent; }-*::-webkit-scrollbar { width: 12px; height: 12px; }-*::-webkit-scrollbar-track { border-radius: 0; background: transparent; }-*::-webkit-scrollbar-thumb { border: 0; border-radius: 0; background: #EB609155; }-*::-webkit-scrollbar-thumb:hover { background: #EB609177; }++/* The home page is dark by design and offers no light mode. */+html.home-page .VPNavBarAppearance,+html.home-page .VPNavScreenAppearance { display: none !important; }++html.home-page * { scrollbar-width: auto; scrollbar-color: #EB609155 transparent; }+html.home-page *::-webkit-scrollbar { width: 12px; height: 12px; }+html.home-page *::-webkit-scrollbar-track { border-radius: 0; background: transparent; }+html.home-page *::-webkit-scrollbar-thumb { border: 0; border-radius: 0; background: #EB609155; }+html.home-page *::-webkit-scrollbar-thumb:hover { background: #EB609177; }+.VPHome { margin-bottom: 0 !important; overflow-x: clip; }-.VPNav { border-bottom: 0; background: #272022; }-.VPNavBar { border-bottom: 0 !important; }-.VPNavBarTitle { display: flex; align-items: center; height: 64px; }-.VPNavBarTitle .title {+html.home-page .VPNav { border-bottom: 0; background: #272022; }+html.home-page .VPNavBar { border-bottom: 0 !important; }+html.home-page .VPNavBarTitle { display: flex; align-items: center; height: 64px; }+html.home-page .VPNavBarTitle .title {display: inline-flex;align-items: center;gap: 8px;@@ -78,7 +92,7 @@ body {-webkit-text-stroke: .2px currentColor;paint-order: stroke fill;}-.VPNavBarTitle .title::before {+html.home-page .VPNavBarTitle .title::before {content: "cinematic_blur";display: block;flex: 0 0 30px;@@ -94,33 +108,33 @@ body {text-align: center;-webkit-text-stroke: 0;}-.VPNavBarMenuLink,-.VPNavBarMenuGroup .text,-.VPNavScreenMenuLink,-.VPNavScreenMenuGroup .button {+html.home-page .VPNavBarMenuLink,+html.home-page .VPNavBarMenuGroup .text,+html.home-page .VPNavScreenMenuLink,+html.home-page .VPNavScreenMenuGroup .button {color: var(--ink-muted) !important;font-family: var(--font-ui);font-size: 13px;font-weight: 600;}-.VPNavBarMenuLink:hover,-.VPNavBarMenuLink.active,-.VPNavScreenMenuLink:hover { color: var(--accent) !important; }-.VPNavBarSocialLinks .VPSocialLink,-.VPNavBarHamburger .container { color: var(--ink) !important; }-.VPNavScreen { background: #272022 !important; }-.VPNav .DocSearch-Button,-.VPNav .VPNavBarSearchButton {+html.home-page .VPNavBarMenuLink:hover,+html.home-page .VPNavBarMenuLink.active,+html.home-page .VPNavScreenMenuLink:hover { color: var(--accent) !important; }+html.home-page .VPNavBarSocialLinks .VPSocialLink,+html.home-page .VPNavBarHamburger .container { color: var(--ink) !important; }+html.home-page .VPNavScreen { background: #272022 !important; }+html.home-page .VPNav .DocSearch-Button,+html.home-page .VPNav .VPNavBarSearchButton {border-color: var(--rule) !important;background: rgba(233,178,166,.06) !important;color: var(--ink) !important;font-family: var(--font-ui);}-.VPNav .DocSearch-Button-Placeholder,-.VPNav .DocSearch-Button-Key {+html.home-page .VPNav .DocSearch-Button-Placeholder,+html.home-page .VPNav .DocSearch-Button-Key {color: var(--ink-muted) !important;}-.VPButton {+html.home-page .VPButton {min-height: 42px !important;border-radius: 2px !important;padding-inline: 22px !important;@@ -129,12 +143,15 @@ body {font-weight: 700 !important;letter-spacing: .02em;}-.VPButton.brand { border-color: var(--button-gold) !important; background: var(--button-gold) !important; color: #FAF7F5 !important; }-.VPButton.brand:hover { border-color: var(--button-gold-hover) !important; background: var(--button-gold-hover) !important; }-.VPButton.brand:active { border-color: var(--button-gold-pressed) !important; background: var(--button-gold-pressed) !important; }-.VPButton.alt { border-color: var(--button-gold) !important; background: transparent !important; color: var(--ink) !important; }-.VPButton.alt:hover { border-color: var(--button-gold-hover) !important; color: var(--ink) !important; }-.VPButton.alt:active { border-color: var(--button-gold-pressed) !important; }+html.home-page .VPButton.brand { border-color: var(--button-gold) !important; background: var(--button-gold) !important; color: #FAF7F5 !important; }+html.home-page .VPButton.brand:hover { border-color: var(--button-gold-hover) !important; background: var(--button-gold-hover) !important; }+html.home-page .VPButton.brand:active { border-color: var(--button-gold-pressed) !important; background: var(--button-gold-pressed) !important; }+html.home-page .VPButton.alt { border-color: var(--button-gold) !important; background: transparent !important; color: var(--ink) !important; }+html.home-page .VPButton.alt:hover { border-color: var(--button-gold-hover) !important; color: var(--ink) !important; }+html.home-page .VPButton.alt:active { border-color: var(--button-gold-pressed) !important; }++html.home-page .VPContent,+html.home-page .VPPage { background: var(--paper); }.VPHero { padding-top: 112px !important; padding-bottom: 0 !important; }.VPHero .name,@@ -352,107 +369,6 @@ body {.ranking-track .segment:nth-child(1) { background: var(--demo-segment-cyan); }.ranking-track .segment:nth-child(2) { background: var(--demo-segment-green); }.ranking-track .segment:nth-child(3) { background: var(--demo-segment-gold); }.ranking-track .segment:nth-child(4) { background: var(--demo-segment-pink); }.ranking-track .segment:nth-child(5) { background: var(--demo-segment-violet); }.demo-provenance { margin: 12px 4px 0 !important; color: var(--ink-muted); font-size: 11px; text-align: right; }.demo-provenance code { color: var(--accent); background: transparent; }-/* Editorial documentation surfaces. */-.VPDoc,-.VPContent,-.VPPage { background: var(--paper); }-.VPSidebar {- border-right: 1px solid var(--rule);- background: var(--paper-light) !important;-}-.VPSidebarItem .text,-.VPDocAsideOutline .outline-title,-.VPDocAsideOutline .outline-link,-.pager-link .title,-.pager-link .desc {- font-family: var(--font-ui);-}-.VPSidebarItem.level-0 > .item > .text {- color: var(--ink);- font-size: 11px;- font-weight: 700;- letter-spacing: .12em;- text-transform: uppercase;-}-.VPSidebarItem .link:hover .text,-.VPSidebarItem.is-active > .item .link > .text,-.VPDocAsideOutline .outline-link.active { color: var(--accent) !important; }-.VPDocAsideOutline .content { border-left-color: var(--rule) !important; }-.vp-doc { color: var(--ink); font-size: 18px; line-height: 1.7; }-.vp-doc h1,-.vp-doc h2,-.vp-doc h3,-.vp-doc h4 {- color: var(--ink);- font-family: var(--font-ui);- font-weight: 600;- letter-spacing: -.035em;-}-.vp-doc h1 { font-size: clamp(42px, 6vw, 64px); font-weight: 700; line-height: 1; }-.vp-doc h2 { margin-top: 54px; padding-top: 18px; border-top-color: var(--rule); font-size: 34px; line-height: 1.08; }-.vp-doc h3 { font-size: 25px; }-.vp-doc p,-.vp-doc li { color: var(--ink-muted); }-.vp-doc strong { color: var(--ink); }-.vp-doc a { color: var(--accent); text-decoration-color: rgba(238,123,98,.42); text-underline-offset: .18em; }-.vp-doc a:hover { color: var(--accent); }-.vp-doc :not(pre) > code {- border: 0;- border-radius: 1px;- background: #322A2D;- color: #E4B781;- font-family: var(--font-code);- font-size: .94em;- letter-spacing: normal;-}-.vp-doc div[class*="language-"] {- border: 0;- border-radius: 2px;- background: #322A2D !important;- box-shadow: none;-}-.vp-doc div[class*="language-"] pre {- padding-block: 18px;- background: transparent !important;-}-.vp-doc div[class*="language-"] code,-.vp-doc pre code {- color: #CBBEC2;- font-family: var(--font-code);- font-size: 14.5px;- letter-spacing: normal;- line-height: 26px;-}-.vp-doc div[class*="language-"] span[style*="--shiki-light"] {- color: var(--shiki-dark) !important;-}-.vp-doc div[class*="language-"] > span.lang {- color: #715B63;- font-family: var(--font-ui);-}-.vp-doc .line-numbers-wrapper { color: #715B63; }-.vp-doc div[class*="language-"] > button.copy { border-radius: 1px; }-.vp-doc blockquote {- border-left: 2px solid var(--accent);- background: rgba(233,178,166,.06);- color: var(--ink-muted);- font-style: normal;-}-.vp-doc table { border-top: 1px solid var(--rule); border-bottom: 1px solid var(--rule); }-.vp-doc th { background: rgba(233,178,166,.06); color: var(--ink); font-family: var(--font-ui); font-size: 12px; letter-spacing: .06em; text-transform: uppercase; }-.vp-doc tr { border-top-color: var(--rule); }-.vp-doc th,-.vp-doc td { border-color: var(--rule); }-.pager-link {- border-color: var(--rule) !important;- border-radius: 2px !important;- background: transparent !important;-}-.pager-link:hover { border-color: var(--accent) !important; }-.VPLocalSearchBox .shell { border-color: var(--rule) !important; border-radius: 2px !important; background: var(--paper-light) !important; }-.VPLocalSearchBox .search-input { color: var(--ink) !important; font-family: var(--font-ui); }-.VPLocalSearchBox .result { border-radius: 2px !important; }-@media (max-width: 900px) {.VPHero { padding-top: 96px !important; }.demo-shell { grid-template-columns: 1fr; }diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.mdnew file mode 100644index 00000000..778a0555--- /dev/null+++ b/docs/guide/author-packages.md@@ -0,0 +1,163 @@+---+title: Adding an Author Package+description: Step-by-step guide for adding a new author-level component.+---++# Adding an Author Package++An author package extends the video vocabulary with a new component. Authors use it through+`<import>` and XML elements in their `.svml` source. No change to Core, the CLI or any aggregate+package is needed.++## 1. Create the package++```bash+mkdir -p packages/my-component/src packages/my-component/test+```++## 2. Write package.json++```json+{+ "name": "@svml/my-component",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "svml": {+ "activation": "./src/activation.ts"+ },+ "dependencies": {+ "@svml/protocol": "workspace:*",+ "@svml/elaborator": "workspace:*",+ "@svml/text": "workspace:*"+ }+}+```++Add only the dependencies your package actually imports. See+[Package architecture](./packages.md) for layer rules.++## 3. Define the Module Manifest++In `src/index.ts`, declare your Module's identity, Types and Producers:++```typescript+import type { ModuleManifest, ModuleRef } from "@svml/protocol";++export const myComponentModuleRef: ModuleRef = {+ name: "@svml/my-component",+ version: 1,+};++export const myComponentManifest: ModuleManifest = {+ module: myComponentModuleRef,+ types: [ /* your nominal Types */ ],+ producers: [ /* your deterministic Producers */ ],+};+```++Types are nominally owned by Modules. Core does not maintain a central union of every domain+type — installing a new package can add a new Type without a Core release.++## 4. Implement the Surface handler++The Surface handler decodes the Text Frontend's XML elements into typed author declarations.++```typescript+// src/surface.ts+import type { TextSurfaceDecoder } from "@svml/text";++export const decodeMyComponentSurface: TextSurfaceDecoder = (element, context) => {+ // Read attributes and children from the XML element+ // Validate inputs+ // Emit typed Records and Operations into context+ // Return authored graph declarations+};+```++Look at existing Surface implementations for reference:+- `packages/seedance/src/surface.ts` — Prompt, Speech and Video Surfaces+- `packages/caption/src/surface.ts` — Style, Program and Track Surfaces+- `packages/broll/src/surface.ts` — Track and Item Surfaces++## 5. Write the activation descriptor++```typescript+// src/activation.ts+import { createTextSurfaceHostFacet } from "@svml/text";+import {+ myComponentManifest,+ myComponentModuleRef,+ decodeMyComponentSurface,+} from "./index.js";++export const svmlPackage = {+ format: "svml.node-package@1" as const,+ name: "@svml/my-component",+ modules: [{+ manifest: myComponentManifest,+ specifiers: ["@svml/my-component", "@svml/my-component@1"],+ }],+ hostFacets: [+ createTextSurfaceHostFacet({+ module: myComponentModuleRef,+ surface: "my-widget",+ mode: "structured",+ implementationDigest: "sha256:...",+ handler: decodeMyComponentSurface,+ }),+ ],+};++export default svmlPackage;+```++The `specifiers` array lists the strings that an `<import from="..."/>` will match against. The+`surface` string determines the XML element prefix (`<mine:my-widget>` when imported as `mine`).++## 6. Register in tsconfig.v2.json++Add the path mapping so TypeScript resolves `@svml/my-component` to source:++```json+"@svml/my-component": ["packages/my-component/src/index.ts"]+```++## 7. Install and lock++```bash+pnpm install++pnpm svml:v2 lock-packages <lock-file> \+ --package @svml/my-component \+ [--package @svml/other-dep ...] \+ --root .+```++## 8. Use in Author Source++```xml+<?svml using="@svml/text@1"?>+<svml>+ <import as="mine" from="@svml/my-component@1"/>++ <mine:Widget id="demo" during={story.selection.example}/>+</svml>+```++The `<import>` activates only author vocabulary. It never grants network, filesystem or credential+authority.++## Existing examples to study++| Package | What it demonstrates |+|---|---|+| `packages/seedance/` | Model family with multiple Surfaces (Prompt, Speech, Video) |+| `packages/seedance-speaker/` | Higher-level binding that composes Script, Prompt Kit and Seedance |+| `packages/caption/` | Style, Program and Track Surfaces with typed field declarations |+| `packages/broll/` | Track with Item/transition behavior |+| `packages/text-track/` | Simple text overlay Track |+| `packages/film/` | Composition target that consumes peer Tracks |diff --git a/docs/guide/components.md b/docs/guide/components.mddeleted file mode 100644index 602fa29b..00000000--- a/docs/guide/components.md+++ /dev/null@@ -1,53 +0,0 @@-----title: Create SVK Components-description: Package recurring video treatments as reusable components.------# Create SVK Components--SVK is the reusable component format for SVML. Authors describe what they want; the component decides how to produce it.--## A minimal component--Suppose we want to package a ranking card. The author only needs to write:--```xml-<script>- <segment id="ranking">- <HOST>Here is @winner our number one pick @/winner.- </segment>-</script>--<ranking-card- title="Top 5 tools"- during={script.selection.winner}-/>-```--The component owns its typography, layout, entrance behavior, and output Track. Video authors do not need to rebuild the node graph or tune a dozen parameters every time.--## What a component should hide--- Repeated internal wiring and defaults-- Visual styling, animation, and media placement-- The concrete HyperFrames output implementation--## What a component should not hide--- Choices that materially change the author's intent-- Whether a transition is a hard cut, fade, or push-- Which part of the spoken script the card should bind to--Good components expose a small set of clear choices:--```xml-<ranking-card- during={script.selection.winner}- enter="fade 200ms"- exit="push-left 300ms"-/>-```--## Next--Components that call video-generation APIs also ship with a Runtime implementation. Authors declare the content; the Runtime handles requests, queues, and downloads. See [Runtime & Providers](/guide/runtime).diff --git a/docs/guide/conventions.md b/docs/guide/conventions.mdnew file mode 100644index 00000000..2a397baf--- /dev/null+++ b/docs/guide/conventions.md@@ -0,0 +1,57 @@+---+title: Conventions+description: Naming, module boundaries, TypeScript configuration and wire data.+---++# Conventions++## Naming++| Thing | Convention | Example |+|---|---|---|+| Package directory | kebab-case | `packages/speech-align/` |+| Package name | `@svml/` scope | `@svml/speech-align` |+| Provider package | `provider-` prefix | `@svml/provider-kie` |+| TypeScript file | kebab-case | `speech-align.ts` |+| Exported type | PascalCase | `SpeechAlignment` |+| Exported function | camelCase | `createSpeechAlignment` |++## Module boundaries++- Each package has exactly one public entry point: `src/index.ts`.+- Internal modules use explicit `.js` extensions (NodeNext resolution).+- Cross-package imports use `@svml/*`, never relative paths across package boundaries.+- Circular dependencies are forbidden (enforced by `tools/package-boundaries.test.mjs`).++## TypeScript configuration++`tsconfig.v2.json` extends `tsconfig.json` and adds `paths` mappings for all `@svml/*` packages.++| Setting | Value |+|---|---|+| Target | ES2023 |+| Module | NodeNext |+| Module resolution | NodeNext |+| `strict` | `true` |+| `noUncheckedIndexedAccess` | `true` — indexed access returns `T \| undefined` |+| `exactOptionalPropertyTypes` | `true` — `undefined` must be explicit |++When adding a new package, add its path mapping to `tsconfig.v2.json`:++```json+"@svml/my-package": ["packages/my-package/src/index.ts"]+```++## Wire data++- All persisted data uses the `@2` wire format version.+- Wire types are defined in `@svml/protocol` and are immutable.+- Nominal Types are owned by Modules, not registered in a central union.+- Type schemas use JSON-compatible structures, not TypeScript interfaces.++## Error handling++- Compilation failures throw with descriptive messages including source location.+- Runtime failures are recorded as Operation failures in the Build state machine.+- Recoverable failures trigger retry according to the Scheduler's lane policy.+- Fatal failures transition the Build to a terminal state.diff --git a/docs/guide/develop.md b/docs/guide/develop.mdnew file mode 100644index 00000000..6699fc74--- /dev/null+++ b/docs/guide/develop.md@@ -0,0 +1,70 @@+---+title: Development Guide+description: Getting started with Narratage development.+---++# Development Guide++## Prerequisites++| Tool | Version | Required for |+|---|---|---|+| Node.js | 22+ | everything |+| pnpm | 9+ | workspace management |+| Python | 3.10–3.13 | WhisperX and OpenCV [sidecar services](./services.md) |+| uv | latest | Python environment management |+| ffmpeg / ffprobe | recent stable | media processing |+| Chrome / Chromium | recent stable | HyperFrames rendering |++Node.js and pnpm are the only hard requirements. The rest are needed only for live Builds.++## Daily workflow++```bash+pnpm install # after pulling or changing dependencies+pnpm check # TypeScript type-check: v1 + v2+pnpm test # full test suite: v1 + v2+```++| Command | What it runs |+|---|---|+| `pnpm check:v1` | `tsc -p tsconfig.json --noEmit` — retained v1 research oracle |+| `pnpm check:v2` | `tsc -p tsconfig.v2.json --noEmit` — all v2 workspace packages |+| `pnpm test:v1` | `node --import tsx --test 'test/**/*.test.ts'` |+| `pnpm test:v2` | `node --import tsx --test 'packages/*/test/**/*.test.ts' 'tools/*.test.mjs'` |++See [Testing](./testing.md) for environment-gated tests and test patterns.++## Repository layout++```text+svml/+├── packages/ 64 v2 workspace packages (the active system)+├── spec/ 7 normative specification documents+├── docs/ VitePress documentation site+├── examples/ v2 examples and v1 regression fixtures+├── services/ Python sidecar services (whisperx, image-opencv)+├── src/ v1 legacy source (regression evidence only)+├── stdlib/ v1 kernel definitions and runtime+├── test/ v1 test suite+├── tools/ boundary tests and build scripts+├── package.json root workspace manifest+├── pnpm-workspace.yaml workspace: [packages/*]+├── tsconfig.json v1 TypeScript config+└── tsconfig.v2.json v2 TypeScript config+```++`src/`, `stdlib/` and `test/` are the v1 research oracle, retained as regression evidence. They+are not the v2 API.++## Guide contents++| Guide | Topic |+|---|---|+| [Package architecture](./packages.md) | The four layers, dependency rules, package anatomy, facets |+| [Adding an author package](./author-packages.md) | Step-by-step: new component, Surface, activation |+| [Adding a Provider](./providers.md) | Step-by-step: new Endpoint adapter |+| [Runtime Profile](./runtime-profile.md) | JSON and TypeScript configuration, diagnostics, Build archive |+| [Local services](./services.md) | WhisperX and OpenCV sidecar setup |+| [Testing](./testing.md) | Test runner, patterns, examples, boundary tests |+| [Conventions](./conventions.md) | Naming, module boundaries, wire data, TypeScript config |diff --git a/docs/guide/packages.md b/docs/guide/packages.mdnew file mode 100644index 00000000..c0d61bf4--- /dev/null+++ b/docs/guide/packages.md@@ -0,0 +1,218 @@+---+title: Package Architecture+description: The four layers, dependency boundaries, package anatomy and facets.+---++# Package Architecture++The 64+ workspace packages under `packages/` are organized into four architectural layers. Each+layer has strict dependency rules enforced by tests on every commit.++## The four layers++### Layer 1: Domain-neutral foundation++These packages implement the graph language, Build state machine, compiler infrastructure and+Runtime ports. They are reusable by any domain — not just video — and have no dependency on Text,+Script, Seedance, Film or any video concept.++```text+@svml/protocol immutable wire contracts+@svml/artifact domain-neutral content-addressed byte type+@svml/core Demand compiler and Build state machine+@svml/source mandatory Source Header+@svml/elaborator author declarations and Fragment expansion+@svml/realization typed realization overlays+@svml/run syntax-neutral Run Graph+@svml/validation semantic admission+@svml/host Host-facing interfaces+@svml/compiler-node reference Node compiler Host+@svml/workspace-fs-node workspace filesystem abstraction+@svml/component-kit Producer/validator registration+@svml/runtime Scheduler and Store ports+@svml/runtime-adapter deployment-adapter ABI+@svml/runtime-adapter-node project-root resolution+@svml/endpoint-kit Endpoint registration+@svml/driver-node trusted Node command executor+@svml/package-loader-node byte-locked package loading+@svml/store-sqlite SQLite Build/Operation stores+@svml/artifact-store-fs filesystem Artifact store+@svml/artifact-store-s3 S3 Artifact store+@svml/credential-store-env environment credentials+@svml/transport invocation seams+@svml/transport-process local process transport+@svml/transport-aws-lambda Lambda transport+@svml/local SQLite/filesystem developer assembly+```++### Layer 2: Author language++Author-facing vocabulary: the text Frontend, Script Surface, SVS Recipes, Run text Frontend and+reusable compilation libraries.++```text+@svml/text official .svml markup Frontend+@svml/script Script Surface+@svml/svs SVS Recipe Frontend+@svml/run-text official .svrun Frontend+@svml/prompt-kit declarative prompt compilation+@svml/compiler-text-node Text Frontend + Surface Host assembly+```++### Layer 3: Video domain++Video-specific types, generation model families, speech/caption/track contracts and composition.+Depends on Layer 1 and 2 but not on any Provider.++```text+@svml/contracts Narrative, Track, Composition contracts+@svml/media media types+@svml/generation image/video product contracts+@svml/model-kit model family abstractions+@svml/seedance Seedance model family + author Surface+@svml/seedance-speaker Seedance Speaker binding+@svml/minimax-h3 MiniMax H3 model family+@svml/gemini-omni Gemini Omni model family+@svml/grok-imagine Grok Imagine model family+@svml/gpt-image GPT Image model family+@svml/nano-banana Nano Banana model family+@svml/seedream Seedream model family+@svml/estimate duration estimation+@svml/speech-program speech program compilation+@svml/speech-take atomic speech take+@svml/speech-align speech alignment+@svml/whisperx WhisperX component+@svml/caption caption planning and Track+@svml/caption-gemini Gemini caption planner+@svml/broll B-roll Track+@svml/text-track text overlay Track+@svml/film Film composition+@svml/hyperframes HyperFrames Visual IR+@svml/hyperframes-render HyperFrames rendering component+@svml/image-transform image processing component+@svml/media-pipeline media inspection/normalization+```++### Layer 4: Provider (Endpoint) packages++Privileged external capabilities. Depend on Runtime ports and the model families they serve, never+on the CLI.++```text+@svml/provider-kie KIE generation (16 model capabilities)+@svml/provider-media-local local ffprobe/ffmpeg+@svml/provider-whisperx-local local WhisperX sidecar+@svml/provider-google-vertex Vertex Gemini caption planning+@svml/provider-hyperframes-local local Chrome rendering+@svml/provider-image-opencv-local local OpenCV image transforms+```++### Application layer++```text+@svml/cli generic command engine (requires explicit Distribution)+@svml/video-cli video command application (selects Text compiler, no built-in author packages)+```++## Dependency rules++`tools/package-boundaries.test.mjs` enforces three invariants on every commit:++1. **Acyclic production graph.** No dependency cycle among any `@svml/*` packages.++2. **Domain-neutral closure.** Every Layer 1 package's transitive closure contains only Layer 1+ packages. `@svml/core` depends only on `@svml/protocol`.++3. **CLI independence.** Neither `@svml/cli` nor `@svml/video-cli` transitively depends on any+ Provider package. The video CLI also does not depend on any author-level video package+ (`@svml/script`, `@svml/seedance-speaker`, `@svml/broll`, `@svml/text-track`, `@svml/film`).+ Author packages are activated through the explicit package lock, not compile-time CLI+ dependencies.++## Package anatomy++Every package lives under `packages/<name>/` with this structure:++```text+packages/example/+├── package.json+├── src/+│ ├── index.ts public API entry point+│ └── activation.ts package contribution descriptor (if installable)+└── test/+ └── example.test.ts+```++### package.json++```json+{+ "name": "@svml/example",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "svml": {+ "activation": "./src/activation.ts"+ },+ "dependencies": {+ "@svml/protocol": "workspace:*"+ }+}+```++- `"exports"` points to TypeScript source directly. The workspace `tsconfig.v2.json` maps+ `@svml/*` imports to source entry points via `paths`.+- `"svml.activation"` is the entry point that the Package Loader reads when this package is+ byte-locked. It must default-export a `NodePackageContribution`.++### activation.ts++Every installable package exports a passive contribution descriptor — an inventory of what it+offers, not an authority grant. See [Adding an author package](./author-packages.md) and+[Adding a Provider](./providers.md) for concrete examples.++## Five package facets++A physical package may expose independently activated facets:++| Facet | ABI | Authority | Selected by |+|---|---|---|---|+| `static` | Manifest and identity | none | always available after loading |+| `author` | Frontend, Surface, Graph Fragment | author vocabulary only | source `<import>` through the compiler Host |+| `compute` | deterministic Producer, Type Validator | pure computation | compiler Host |+| `endpoint` | privileged external capability | network, filesystem, process, credentials | Runtime Profile |+| `runtime` | Scheduler, Store implementation | persistence, scheduling | Runtime Profile |++A source `<import>` activates only author facets. It never grants network, filesystem, process,+credential or queue authority.++## Package locking++SVML uses byte-locked trusted code execution. The loader records each package's name, version and+SHA-256 digest:++```json+{+ "format": "svml.node-package-lock@1",+ "artifacts": [+ {+ "name": "@svml/seedance",+ "version": "0.0.0-dev",+ "digest": "sha256:abc123..."+ }+ ]+}+```++Two independent lock closures serve different authority scopes:++| Lock file | Contains | Identity scope |+|---|---|---|+| `svml.packages.lock` | Frontends, Surfaces, Producers, Validators | Author Graph + Run Graph + execution Program Closure |+| `svml.runtime-packages.lock` | Providers, Stores, transports | Runtime Closure |++Changing a package requires regenerating the lock. The Build state machine verifies every digest+before issuing a Command.diff --git a/docs/guide/providers.md b/docs/guide/providers.mdnew file mode 100644index 00000000..10450a96--- /dev/null+++ b/docs/guide/providers.md@@ -0,0 +1,174 @@+---+title: Adding a Provider+description: Step-by-step guide for adding a new Endpoint adapter.+---++# Adding a Provider++A Provider package implements a privileged external capability — video generation, media+processing, alignment, caption planning, rendering. It is activated through the Runtime Profile,+never through `<import>` in Author Source.++No change to Core, the CLI or any author package is required.++## 1. Create the package++```bash+mkdir -p packages/provider-my-service/src packages/provider-my-service/test+```++## 2. Write package.json++Provider packages depend on Runtime ports and the model families they serve, never on the CLI:++```json+{+ "name": "@svml/provider-my-service",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "svml": { "activation": "./src/activation.ts" },+ "dependencies": {+ "@svml/endpoint-kit": "workspace:*",+ "@svml/protocol": "workspace:*",+ "@svml/runtime": "workspace:*",+ "@svml/runtime-adapter": "workspace:*",+ "@svml/runtime-adapter-node": "workspace:*",+ "@svml/seedance": "workspace:*"+ }+}+```++## 3. Implement the Provider++The Provider handles Commands from the Scheduler: request submission, polling, download and+ArtifactStore persistence.++```typescript+// src/provider.ts+import type { EndpointManifest } from "@svml/endpoint-kit";++export function createMyServiceProvider(options: {+ instance: string;+ lane?: string;+ apiKey?: { env: string };+ defaultConcurrency?: number;+}) {+ // Return an object with:+ // - manifest: declares Capabilities this Endpoint implements+ // - handle: processes Commands from the Scheduler+ // - close: cleanup+}+```++Look at existing Providers for reference:+- `packages/provider-kie/src/provider.ts` — remote generation with upload, polling and download+- `packages/provider-media-local/` — local process execution (ffprobe/ffmpeg)+- `packages/provider-whisperx-local/` — local sidecar HTTP service+- `packages/provider-hyperframes-local/` — local Chrome rendering++## 4. Write the activation descriptor++```typescript+// src/activation.ts+import {+ createRuntimeEndpointAdapterFacet,+ runtimeConfigObject,+ runtimeConfigString,+ runtimeConfigPositiveInteger,+} from "@svml/runtime-adapter";+import { diagnoseRuntimeEnvironmentCredential } from "@svml/runtime-adapter-node";+import { createMyServiceProvider } from "./provider.js";++const adapter = createRuntimeEndpointAdapterFacet({+ use: "@svml/provider-my-service",++ create(context) {+ const config = runtimeConfigObject(context.config, "MyService");+ const apiKeyEnv = runtimeConfigString(config.apiKeyEnv, "MyService apiKeyEnv");+ return createMyServiceProvider({+ instance: context.instance,+ lane: context.lane,+ ...(apiKeyEnv === undefined ? {} : { apiKey: { env: apiKeyEnv } }),+ ...(runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency") === undefined+ ? {} : { defaultConcurrency: config.defaultConcurrency as number }),+ });+ },++ doctor(context) {+ const config = runtimeConfigObject(context.config, "MyService");+ const apiKeyEnv = runtimeConfigString(config.apiKeyEnv, "MyService apiKeyEnv")+ ?? "MY_SERVICE_API_KEY";+ return diagnoseRuntimeEnvironmentCredential(apiKeyEnv, "MyService");+ },+});++export const svmlPackage = {+ format: "svml.node-package@1" as const,+ name: "@svml/provider-my-service",+ hostFacets: [adapter],+};++export default svmlPackage;+```++The `create` function constructs the Endpoint from Runtime config. The `doctor` function returns+diagnostics (credential presence, executable availability) without constructing or calling+anything.++## 5. Register and lock++Add the path mapping to `tsconfig.v2.json`:++```json+"@svml/provider-my-service": ["packages/provider-my-service/src/index.ts"]+```++Lock into a Runtime package lock:++```bash+pnpm svml:v2 lock-packages <runtime-lock> \+ --package @svml/provider-my-service \+ --root .+```++## 6. Reference from svml.runtime.json++```json+{+ "endpoints": [+ {+ "use": "@svml/provider-my-service",+ "instance": "my-service.project",+ "lane": "generation",+ "config": {+ "apiKeyEnv": "MY_SERVICE_API_KEY",+ "defaultConcurrency": 2+ }+ }+ ],+ "permissions": [+ "network:api.my-service.com"+ ]+}+```++Verify the configuration:++```bash+pnpm svml:v2 doctor svml.runtime.json+```++## Existing Providers to study++| Package | Pattern |+|---|---|+| `provider-kie` | Remote API: upload, paid submission, checkpointed polling, bounded download, immediate ArtifactStore persistence |+| `provider-media-local` | Local process: shell-free ffprobe/ffmpeg with bounded execution |+| `provider-whisperx-local` | Local sidecar: HTTP service with warm model, single-admit concurrency |+| `provider-google-vertex` | Cloud API: Vertex AI with project/credentials configuration |+| `provider-hyperframes-local` | Local process: Chrome rendering with worker parallelism and output probe validation |+| `provider-image-opencv-local` | Local Python: bounded OpenCV/NumPy with locked Python environment |diff --git a/docs/guide/runtime-profile.md b/docs/guide/runtime-profile.mdnew file mode 100644index 00000000..e2d88857--- /dev/null+++ b/docs/guide/runtime-profile.md@@ -0,0 +1,222 @@+---+title: Runtime Profile+description: Configuring where Builds execute, diagnostics and Build archive.+---++# Runtime Profile++The Runtime Profile declares *where* a frozen Build executes: Endpoints, credentials, concurrency,+permissions. It is deployment configuration, not creative content — it never enters Author or Run+graph identity.++Two forms are supported:++| Form | File | Use case |+|---|---|---|+| Declarative JSON | `svml.runtime.json` | Standard path |+| Executable TypeScript | `svml.runtime.ts` | Advanced embedding API |++## Declarative JSON++```json+{+ "format": "svml.runtime-config@1",+ "packageLock": "./svml.packages.lock",+ "runtimePackageLock": "./svml.runtime-packages.lock",+ "services": [],+ "endpoints": [+ {+ "use": "@svml/provider-kie",+ "instance": "kie.production",+ "lane": "generation",+ "config": {+ "apiKeyEnv": "KIE_API_KEY",+ "defaultConcurrency": 2+ }+ },+ {+ "use": "@svml/provider-media-local",+ "instance": "media.local",+ "lane": "media",+ "config": { "defaultConcurrency": 2 }+ },+ {+ "use": "@svml/provider-whisperx-local",+ "instance": "whisperx.local",+ "lane": "alignment",+ "config": { "defaultConcurrency": 1 }+ },+ {+ "use": "@svml/provider-google-vertex",+ "instance": "vertex.local",+ "lane": "planning",+ "config": {+ "projectEnv": "GOOGLE_CLOUD_PROJECT",+ "credentialsEnv": "GOOGLE_APPLICATION_CREDENTIALS_JSON",+ "defaultConcurrency": 1+ }+ },+ {+ "use": "@svml/provider-hyperframes-local",+ "instance": "hyperframes.local",+ "lane": "render",+ "config": { "workers": 2, "quality": "standard", "defaultConcurrency": 1 }+ }+ ],+ "permissions": [+ "filesystem:whisperx-staging",+ "network:aiplatform.googleapis.com",+ "network:api.kie.ai",+ "network:whisperx-loopback",+ "process:hyperframes",+ "process:media"+ ],+ "scheduling": {+ "maxConcurrency": 4,+ "lanes": {+ "generation": 2,+ "media": 2,+ "alignment": 1,+ "planning": 1,+ "render": 1+ }+ }+}+```++### Endpoint fields++| Field | Meaning |+|---|---|+| `use` | Adapter name, resolved from `runtimePackageLock` |+| `instance` | Unique identifier for this Endpoint instance |+| `lane` | Scheduling lane governing concurrency |+| `config` | Adapter-specific configuration (credential env vars, concurrency, timeouts) |++Credentials are referenced by environment variable name, never stored in the Profile.++### Scheduling++`maxConcurrency` caps total concurrent Operations across all lanes. Each named `lane` has its own+sub-cap. Lanes are declared by the Endpoint and enforced by the Scheduler.++### Permissions++Each permission string grants one specific authority to the locked Endpoints:++- `network:<host>` — outbound HTTP to that host+- `filesystem:<scope>` — file access within a named scope+- `process:<name>` — local process execution++## Executable TypeScript++For advanced embedding, construct the Runtime programmatically:++```typescript+import { createProjectLocalRuntime } from "@svml/local";+import { createKieProvider } from "@svml/provider-kie";+import { createLocalMediaProvider } from "@svml/provider-media-local";++export default async function createRuntime() {+ const endpoints = [+ createKieProvider({+ instance: "kie.prod",+ lane: "generation",+ defaultConcurrency: 2,+ }),+ createLocalMediaProvider({+ instance: "media.prod",+ lane: "media",+ defaultConcurrency: 2,+ }),+ ];++ return await createProjectLocalRuntime({+ root: import.meta.dirname,+ packageLock: "./svml.packages.lock",+ endpoints,+ allowedPermissions: endpoints.flatMap(e =>+ e.manifest.facets.flatMap(f => f.permissions)),+ scheduling: {+ maxConcurrency: 4,+ lanes: { generation: 2, media: 2 },+ },+ });+}+```++Pass either form to `--runtime`:++```bash+pnpm svml:v2 build build.svrun --runtime ./svml.runtime.json+pnpm svml:v2 build build.svrun --runtime ./svml.runtime.ts+```++## Diagnostics++### doctor++Checks the Runtime Profile without running a Build or making paid requests:++```bash+pnpm svml:v2 doctor svml.runtime.json+```++Validates:+- Package locks exist and are readable+- Adapter byte digests match+- Configuration keys are valid for each adapter+- Referenced credentials exist in the environment+- Required executables (ffmpeg, ffprobe, chrome) are found++### gc (garbage collection)++```bash+pnpm svml:v2 gc svml.runtime.json # dry-run+pnpm svml:v2 gc svml.runtime.json --apply # delete unreachable Artifacts+```++Walks every retained BuildState and Operation, computes reachable Artifact digests, and reports+(or deletes) unreachable orphans.++## Build archive and inspection++Every Build archives all accepted Records and referenced Artifacts durably, independent of any+`--to` destination path.++### List Builds++```bash+pnpm svml:v2 builds --runtime svml.runtime.json+```++### Inspect++```bash+pnpm svml:v2 inspect <build-id> --runtime svml.runtime.json+```++Shows target bindings, demanded Logical Outputs, every accepted Record and Operation status.++### Retrieve Records++```bash+# By source output name+pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+ --name final.video --to output.mp4++# By Record id+pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+ --record <record-id> --to output.json++# By Logical Output id+pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+ --output <output-id>++# By Artifact digest+pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+ --artifact <sha256:...> --to file.bin+```++`--name` uses the source output alias from the Host-only Build Catalog. The Catalog is a+presentation convenience; it does not enter Core Build identity.diff --git a/docs/guide/runtime.md b/docs/guide/runtime.mddeleted file mode 100644index 124cfe7e..00000000--- a/docs/guide/runtime.md+++ /dev/null@@ -1,46 +0,0 @@-----title: Runtime & Providers-description: How components connect to external generation services such as Seedance.------# Runtime & Providers--Ordinary video authors should not need to initialize a Runtime or put API keys in project files.--## Author workflow--Sign in to a Provider once:--```bash-svml provider login seedance-```--Then import and use its component in a video:--```xml-<svml>- <import as="seedance" from="@svml/seedance@1"/>-- <seedance:speaker- script={story.segment.opening}- character="./host.png"- direction="Speak naturally to camera"- />-</svml>-```--Build normally:--```bash-svml build main.svml-```--## Who calls the API--The `@svml/seedance` package carries its own Runtime implementation for queueing, requesting, polling, and downloading. The official CLI loads it automatically when it encounters the component. Keys remain in the system keychain or the user's global SVML configuration; they never enter `.svml` files, lockfiles, or Git.--::: info Not implemented yet-This is the planned author workflow, not a command set already provided by the current repository. The existing implementation accepts prepared local media and capability artifacts only.-:::--Only developers embedding SVML inside another product need to work directly with APIs such as `createRuntime()`.diff --git a/docs/guide/services.md b/docs/guide/services.mdnew file mode 100644index 00000000..6b58357c--- /dev/null+++ b/docs/guide/services.md@@ -0,0 +1,89 @@+---+title: Local Services+description: Setting up the WhisperX and OpenCV sidecar services.+---++# Local Services++Two Python sidecar services support local Builds. They are Runtime deployment packages, not part+of Core or the author language.++## WhisperX++Provides ASR and language-specific alignment for speech timing measurement.++### Install++WhisperX 3.8.6 supports Python 3.10–3.13. The checked-in lock selects 3.13:++```bash+uv python install 3.13+uv sync --project services/whisperx --frozen+uv run --project services/whisperx --frozen svml-whisperx-prepare+uv run --project services/whisperx --frozen svml-whisperx-check+```++`svml-whisperx-prepare` installs NLTK's `punkt_tab` sentence data from a pinned archive after+SHA-256 verification. This is required by WhisperX alignment and is never downloaded during+inference.++The first model start may download ASR and alignment weights. Production should put the Hugging+Face cache on persistent storage.++### Run++```bash+uv run --project services/whisperx --frozen svml-whisperx-service+curl http://127.0.0.1:8765/health+```++### Configuration++| Variable | Default | Meaning |+|---|---|---|+| `SVML_WHISPERX_PORT` | `8765` | loopback port |+| `SVML_WHISPERX_MODEL` | `small` | faster-whisper model |+| `SVML_WHISPERX_DEVICE` | `cpu` | `cpu` or deployed accelerator |+| `SVML_WHISPERX_COMPUTE` | `int8` on CPU | CTranslate2 compute type |+| `SVML_WHISPERX_BATCH_SIZE` | `8` | bounded ASR batch size |+| `SVML_WHISPERX_INPUT_ROOTS` | OS temp dir | path-separated roots the service may read |+| `SVML_WHISPERX_NLTK_DATA` | user SVML cache | prepared NLTK data root |+| `SVML_WHISPERX_MAX_REQUEST_BYTES` | `65536` | HTTP JSON bound |+| `SVML_WHISPERX_MAX_AUDIO_BYTES` | `536870912` | staged canonical WAV bound |++### Concurrency++The service admits exactly one inference at a time. A second request receives `503 BUSY`.+Concurrency is governed by the SVML Runtime Scheduler's lane configuration, not the service+itself.++The Node Provider (`@svml/provider-whisperx-local`) must be configured with matching model,+device, compute and batch size. A mismatch fails before results are accepted.++### Tests++```bash+pnpm test:whisperx-service+```++## OpenCV image service++Provides bounded image transforms (e.g. the GPT Image YCrCb denoise preset) through+`@svml/provider-image-opencv-local`.++### Install++```bash+uv python install 3.13+uv sync --project services/image-opencv --frozen+```++### Tests++Tests are gated behind environment variables:++```bash+SVML_OPENCV_TESTS=1 \+SVML_OPENCV_PYTHON=services/image-opencv/.venv/bin/python \+pnpm test:image-opencv+```diff --git a/docs/guide/testing.md b/docs/guide/testing.mdnew file mode 100644index 00000000..5d9f22ea--- /dev/null+++ b/docs/guide/testing.md@@ -0,0 +1,95 @@+---+title: Testing+description: Test runner, patterns and environment-gated tests.+---++# Testing++## Test runner++SVML uses the Node.js built-in test runner (`node:test`), not Jest, Vitest or Mocha.++```bash+pnpm test # everything: v1 + v2+pnpm test:v1 # v1 regression tests+pnpm test:v2 # v2 package tests + boundary tests+```++Test files live in `packages/<name>/test/` with the `.test.ts` extension. They are discovered by+the glob `packages/*/test/**/*.test.ts`.++## Writing a test++```typescript+import assert from "node:assert/strict";+import { describe, test } from "node:test";++import { someFunction } from "@svml/example";++describe("someFunction", () => {+ test("returns the expected result", () => {+ const result = someFunction(input);+ assert.deepStrictEqual(result, expected);+ });+});+```++## Test patterns++### Pure compilation tests++The most common pattern. Compile an Author or Run Source and assert on the resulting graph,+exports, Records or plan steps. Never calls an external service.++```typescript+test("compiles the expected exports", async () => {+ const compiler = createCompiler({ root, packageContributions });+ const workspace = await compiler.openFile("fixture.svml");+ const result = await compiler.compileSource(workspace.entry, workspace);+ assert.equal(result.exports.length, 3);+});+```++### Provider tests++Test Endpoint implementations with real or simulated external services. Environment-gated: check+for required credentials or executables and skip when absent.++```typescript+test("generates a video", async (t) => {+ if (!process.env.KIE_API_KEY) {+ t.skip("KIE_API_KEY not set");+ return;+ }+ // ... real API call+});+```++### Boundary tests++`tools/package-boundaries.test.mjs` and `tools/graph-first-value-boundary.test.mjs` verify+structural invariants across the entire workspace:++- Acyclic dependency graph+- Domain-neutral closure contains only domain-neutral packages+- CLI has no Provider or author-package dependency++These run as part of `pnpm test:v2` on every commit.++## Environment-gated tests++| Command | What it tests | Prerequisites |+|---|---|---|+| `pnpm test:whisperx-service` | Python WhisperX service | Python 3.13, uv, frozen sync |+| `pnpm test:image-opencv` | OpenCV image transforms | `SVML_OPENCV_TESTS=1`, `SVML_OPENCV_PYTHON` |+| `pnpm smoke:kie` | Live paid KIE generation | `KIE_API_KEY` |++## Test fixtures++Test fixtures go in `packages/<name>/test/fixtures/` or `test/fixtures/` (v1). They are+ordinary `.svml`, `.svs` and `.svrun` files that exercise specific compilation paths.++The `examples/` directory also serves as integration-level fixtures:+- `examples/v2-bootstrap/` — smallest source closure check+- `examples/talking-film-graph-check/` — complete graph compilation without Providers+- `examples/echo-pro-aroll/` — live acceptance with explicit historical-Candidate reusediff --git a/docs/index.md b/docs/index.mdindex cefca32f..b2dfee51 100644--- a/docs/index.md+++ b/docs/index.md@@ -9,7 +9,7 @@ hero:link: /quickstart- theme: alttext: Develop- link: /guide/components+ link: /guide/develop---<ClientOnly>diff --git a/docs/quickstart.md b/docs/quickstart.mdindex 26089282..c8925c91 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -1,70 +1,140 @@---title: Quickstart-description: Check and compile your first SVML video in minutes.+description: Set up Narratage and compile your first video graph.---# Quickstart-Start with a spoken script and compile it into a video page ready for HyperFrames to render.+The name **Narratage** comes from a 1933 *New York Times* review of the film *The Power and the+Glory*. The critic coined the word to describe a then-new cinematic technique:+**Narration + Montage** — a narrator's voice carries the story forward while the screen assembles+a montage of scenes to match.++That is exactly what this system does. The author writes a narrated Script with semantic anchors,+and the compiler assembles generated video, captions, B-roll, text and audio into a finished film.+The internal package scope is `@svml` (Semantic Video Markup Language).## Install-SVML currently requires Node.js 22 and pnpm.+Requires Node.js 22+ and pnpm.```bashpnpm install-pnpm build+pnpm check+pnpm test```-## Start with a real example+## Three inputs-The Ranking example in this repository uses `@name … @/name` to declare semantic ranges in the spoken script, then lets components consume those ranges. Here is the core excerpt:+Every Build takes three separate inputs:-```xml-<svml version="1">- <import from="../../stdlib/ranking-column.svk"/>-- <script>- <segment id="ranking">- <NARRATOR> @photoshop Photoshop.- <SPEAKER> Powerful, but only if you know how to use it.- Otherwise it becomes a three-hour project @/photoshop.- </segment>- </script>-- <ranking-column id="ranking" z="42">- <item- id="photoshop"- rank="5"- image={ranking-icon-5}- during={script.selection.photoshop}- />- </ranking-column>-</svml>+| Input | What it owns | Typical file |+|---|---|---|+| **Author Source** | script, model choices, track composition, output graph | `.svml` |+| **Run Source** | which outputs to target, alternate candidates, satisfaction edges | `.svrun` |+| **Runtime Profile** | endpoints, credentials, concurrency, permissions | `svml.runtime.json` |++Author Source says *what*. Run Source says *which*. Runtime Profile says *where*.++## Check a video graph (free)++The `talking-film-graph-check` example compiles a complete video graph — Script, Seedance, Speech,+WhisperX, Gemini Caption, B-roll, Text, Film, HyperFrames — without calling any external service.++```bash+# Compile the Author Source.+pnpm svml:v2 check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .++# Compile the Run Source and inspect the frozen plan.+pnpm svml:v2 plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .```-There is no hand-written “second 3 to second 7.” The locator resolves the `photoshop` Selection against the spoken script and media into the real time range for this build.+`check` produces the typed Author Graph. `plan` binds the Author and Run graphs, resolves Targets+and outputs the frozen BuildPlan — every Operation and Needs the Scheduler would issue. Inspect it+before spending money.++## Run a real Build (paid)-## Check and compile+The `echo-pro-aroll` example is a four-take Seedance Mini talking-head film.++Prerequisites:++- `KIE_API_KEY`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS_JSON` in env+- `ffmpeg`, `ffprobe`, Chrome+- Local WhisperX service running (see `services/whisperx/README.md`)+- Local assets in `examples/echo-pro-aroll/assets/` (not committed)```bash-pnpm svml check examples/regen-ranking/regen-ranking.svml-pnpm svml lock examples/regen-ranking/regen-ranking.svml --out svml.lock-pnpm svml compile examples/regen-ranking/regen-ranking.svml \- --lock svml.lock \- --out build/index.html+# Diagnose the Runtime environment.+pnpm svml:v2 doctor examples/echo-pro-aroll/svml.runtime.json++# Submit the Build.+pnpm svml:v2 build examples/echo-pro-aroll/build.svrun \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --package-lock examples/echo-pro-aroll/svml.packages.lock \+ --root . \+ --build-id echo-pro-film-001 \+ --follow++# Retrieve the final video.+pnpm svml:v2 get echo-pro-film-001 \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --name final.video \+ --to examples/echo-pro-aroll/output/final.mp4```-`check` verifies that the declarations are complete; `lock` freezes the inputs actually used by this build; `compile` produces deterministic HyperFrames HTML.+Every accepted intermediate Record and Artifact is archived before the Build completes. `get`+makes an optional copy of an already durable Record.++## Reuse previous results-## Render+SVML has no implicit cache. Reusing a result is explicit Run Graph authoring — declare zero-input+Candidates backed by historical Records and connect them through Satisfaction edges:++```xml+<?svml using="@svml/run-text@1"?>+<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="substitute"/>+ </target-set>++ <build-record id="hook-video"+ build="echo-pro-film-001" output="hook-take.video"/>+ <satisfy output="hook-take.video"+ candidate="hook-video" fidelity="substitute"/>+</svrun>+```++The compiled plan prunes all upstream Operations that the substitute Candidates replace. This is a+new Build, not a continuation.```bash-pnpm svml render build/index.html --out build/video.mp4+pnpm svml:v2 build examples/echo-pro-aroll/reuse-generated.svrun \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --package-lock examples/echo-pro-aroll/svml.packages.lock \+ --root . --build-id echo-pro-film-reuse-001 --follow+```++## CLI reference++```text+svml-v2 lock-packages <lock> --package name [--package name ...] [--root dir]+svml-v2 doctor <runtime.json>+svml-v2 gc <runtime.json> [--apply]+svml-v2 check <source> [--package-lock file] [--root dir]+svml-v2 plan <run-source> [--package-lock file] [--root dir]+svml-v2 build <run-source> --runtime profile [--build-id id] [--follow]+svml-v2 status <build-id> --runtime profile+svml-v2 builds --runtime profile+svml-v2 inspect <build-id> --runtime profile+svml-v2 get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]+svml-v2 cancel <build-id> --runtime profile```-::: warning Current status-The executable example requires its local media and alignment evidence. Automatic loading from online Providers is not implemented yet.-:::+## Next-Continue to [Components](/guide/components) to learn how recurring visual treatments can be packaged as SVK components.+- [Development guide](./guide/develop.md) — repository layout, package architecture, extension+ patterns.diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.mdnew file mode 100644index 00000000..7ffd0284--- /dev/null+++ b/docs/zh/guide/author-packages.md@@ -0,0 +1,157 @@+---+title: 添加 Author 包+description: 添加新的作者层组件的分步指南。+---++# 添加 Author 包++作者包用一个新组件扩展视频词汇。作者在自己的 `.svml` 源码里通过 `<import>` 和 XML 元素来使用它。无需改动 Core、CLI 或任何聚合包。++## 1. 创建包++```bash+mkdir -p packages/my-component/src packages/my-component/test+```++## 2. 编写 package.json++```json+{+ "name": "@svml/my-component",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "svml": {+ "activation": "./src/activation.ts"+ },+ "dependencies": {+ "@svml/protocol": "workspace:*",+ "@svml/elaborator": "workspace:*",+ "@svml/text": "workspace:*"+ }+}+```++只添加你的包实际导入的依赖。分层规则参见[包架构](./packages.md)。++## 3. 定义 Module Manifest++在 `src/index.ts` 中声明你的 Module 的身份、Type 和 Producer:++```typescript+import type { ModuleManifest, ModuleRef } from "@svml/protocol";++export const myComponentModuleRef: ModuleRef = {+ name: "@svml/my-component",+ version: 1,+};++export const myComponentManifest: ModuleManifest = {+ module: myComponentModuleRef,+ types: [ /* your nominal Types */ ],+ producers: [ /* your deterministic Producers */ ],+};+```++Type 在名义上归属于 Module。Core 并不维护一个包含所有领域类型的中央联合类型 —— 安装一个新包就能添加新的 Type,无需发布新的 Core 版本。++## 4. 实现 Surface handler++Surface handler 把 Text Frontend 的 XML 元素解码成带类型的作者声明。++```typescript+// src/surface.ts+import type { TextSurfaceDecoder } from "@svml/text";++export const decodeMyComponentSurface: TextSurfaceDecoder = (element, context) => {+ // Read attributes and children from the XML element+ // Validate inputs+ // Emit typed Records and Operations into context+ // Return authored graph declarations+};+```++可以参考已有的 Surface 实现:+- `packages/seedance/src/surface.ts` —— Prompt、Speech 和 Video Surface+- `packages/caption/src/surface.ts` —— Style、Program 和 Track Surface+- `packages/broll/src/surface.ts` —— Track 和 Item Surface++## 5. 编写 activation 描述符++```typescript+// src/activation.ts+import { createTextSurfaceHostFacet } from "@svml/text";+import {+ myComponentManifest,+ myComponentModuleRef,+ decodeMyComponentSurface,+} from "./index.js";++export const svmlPackage = {+ format: "svml.node-package@1" as const,+ name: "@svml/my-component",+ modules: [{+ manifest: myComponentManifest,+ specifiers: ["@svml/my-component", "@svml/my-component@1"],+ }],+ hostFacets: [+ createTextSurfaceHostFacet({+ module: myComponentModuleRef,+ surface: "my-widget",+ mode: "structured",+ implementationDigest: "sha256:...",+ handler: decodeMyComponentSurface,+ }),+ ],+};++export default svmlPackage;+```++`specifiers` 数组列出了 `<import from="..."/>` 会去匹配的字符串。`surface` 字符串决定 XML 元素前缀(以 `mine` 导入时即为 `<mine:my-widget>`)。++## 6. 在 tsconfig.v2.json 中注册++添加路径映射,让 TypeScript 把 `@svml/my-component` 解析到源码:++```json+"@svml/my-component": ["packages/my-component/src/index.ts"]+```++## 7. 安装并锁定++```bash+pnpm install++pnpm svml:v2 lock-packages <lock-file> \+ --package @svml/my-component \+ [--package @svml/other-dep ...] \+ --root .+```++## 8. 在 Author Source 中使用++```xml+<?svml using="@svml/text@1"?>+<svml>+ <import as="mine" from="@svml/my-component@1"/>++ <mine:Widget id="demo" during={story.selection.example}/>+</svml>+```++`<import>` 只会 activate 作者词汇。它绝不授予网络、文件系统或凭据权限。++## 可供研究的现有示例++| 包 | 它展示了什么 |+|---|---|+| `packages/seedance/` | 带多个 Surface(Prompt、Speech、Video)的模型族 |+| `packages/seedance-speaker/` | 组合 Script、Prompt Kit 和 Seedance 的更高层绑定 |+| `packages/caption/` | 带类型化字段声明的 Style、Program 和 Track Surface |+| `packages/broll/` | 带 Item/转场行为的 Track |+| `packages/text-track/` | 简单的文字叠加 Track |+| `packages/film/` | 消费同级 Track 的合成 target |diff --git a/docs/zh/guide/components.md b/docs/zh/guide/components.mddeleted file mode 100644index 2433e1df..00000000--- a/docs/zh/guide/components.md+++ /dev/null@@ -1,53 +0,0 @@-----title: 创建 SVK 组件-description: 把重复的视频表现封装成可复用组件。------# 创建 SVK 组件--SVK 是 SVML 的可复用组件。作者写“我要什么”,组件决定“具体怎样做”。--## 一个最小组件--假设我们想封装一个排名卡片。作者只需要写:--```xml-<script>- <segment id="ranking">- <HOST>Here is @winner our number one pick @/winner.- </segment>-</script>--<ranking-card- title="Top 5 tools"- during={script.selection.winner}-/>-```--组件内部负责字体、布局、入场方式和输出的 Track。换句话说,视频作者不需要每次重新搭节点或手调十几个参数。--## 组件应该隐藏什么--- 重复的内部接线和默认值-- 视觉样式、动画和媒体摆放-- 对 HyperFrames 输出的具体实现--## 组件不应该隐藏什么--- 会明显改变作者意图的选择-- 例如硬切、淡入淡出或推拉转场-- 例如这个卡片应该绑定哪一段口播稿--好的组件会提供简单但清楚的选择:--```xml-<ranking-card- during={script.selection.winner}- enter="fade 200ms"- exit="push-left 300ms"-/>-```--## 下一步--需要调用视频生成 API 的组件,还会带一个 Runtime 实现。作者侧只声明内容,Runtime 侧负责请求、排队和下载。参见[运行时与 Provider](/zh/guide/runtime)。diff --git a/docs/zh/guide/conventions.md b/docs/zh/guide/conventions.mdnew file mode 100644index 00000000..b36c881e--- /dev/null+++ b/docs/zh/guide/conventions.md@@ -0,0 +1,57 @@+---+title: 代码规范+description: 命名、模块边界、TypeScript 配置与 wire 数据。+---++# 代码规范++## 命名++| 项目 | 约定 | 示例 |+|---|---|---|+| 包目录 | kebab-case | `packages/speech-align/` |+| 包名 | `@svml/` scope | `@svml/speech-align` |+| Provider 包 | `provider-` 前缀 | `@svml/provider-kie` |+| TypeScript 文件 | kebab-case | `speech-align.ts` |+| 导出类型 | PascalCase | `SpeechAlignment` |+| 导出函数 | camelCase | `createSpeechAlignment` |++## 模块边界++- 每个包有且只有一个公开入口点:`src/index.ts`。+- 内部模块使用显式的 `.js` 扩展名(NodeNext 解析)。+- 跨包导入使用 `@svml/*`,绝不跨包边界使用相对路径。+- 禁止循环依赖(由 `tools/package-boundaries.test.mjs` 强制执行)。++## TypeScript 配置++`tsconfig.v2.json` 继承 `tsconfig.json`,并为所有 `@svml/*` 包添加 `paths` 映射。++| 配置项 | 值 |+|---|---|+| Target | ES2023 |+| Module | NodeNext |+| Module resolution | NodeNext |+| `strict` | `true` |+| `noUncheckedIndexedAccess` | `true` — 索引访问返回 `T \| undefined` |+| `exactOptionalPropertyTypes` | `true` — `undefined` 必须显式写出 |++新增一个包时,要把它的路径映射加入 `tsconfig.v2.json`:++```json+"@svml/my-package": ["packages/my-package/src/index.ts"]+```++## wire 数据++- 所有持久化数据使用 `@2` wire 格式版本。+- wire 类型定义在 `@svml/protocol` 中,且不可变。+- Nominal Type 由 Module 拥有,不在中心化的联合类型中注册。+- 类型 schema 使用与 JSON 兼容的结构,而不是 TypeScript 接口。++## 错误处理++- 编译失败时抛出带有描述性信息的错误,其中包含源码位置。+- 运行时失败在 Build 状态机中记录为 Operation 失败。+- 可恢复的失败会按照 Scheduler 的 lane 策略触发重试。+- 致命失败会让 Build 转入终止状态。diff --git a/docs/zh/guide/develop.md b/docs/zh/guide/develop.mdnew file mode 100644index 00000000..32065eea--- /dev/null+++ b/docs/zh/guide/develop.md@@ -0,0 +1,69 @@+---+title: 开发指南+description: 开始 Narratage 开发工作。+---++# 开发指南++## 前置条件++| 工具 | 版本 | 用于 |+|---|---|---|+| Node.js | 22+ | 所有工作 |+| pnpm | 9+ | workspace 管理 |+| Python | 3.10–3.13 | WhisperX 与 OpenCV [sidecar 服务](./services.md) |+| uv | latest | Python 环境管理 |+| ffmpeg / ffprobe | 较新的稳定版 | 媒体处理 |+| Chrome / Chromium | 较新的稳定版 | HyperFrames 渲染 |++只有 Node.js 与 pnpm 是硬性要求。其余都只在跑真实 Builds 时才需要。++## 日常工作流++```bash+pnpm install # 拉取代码或改动依赖之后+pnpm check # TypeScript 类型检查:v1 + v2+pnpm test # 完整测试套件:v1 + v2+```++| 命令 | 实际执行什么 |+|---|---|+| `pnpm check:v1` | `tsc -p tsconfig.json --noEmit` —— 保留下来的 v1 research oracle |+| `pnpm check:v2` | `tsc -p tsconfig.v2.json --noEmit` —— 全部 v2 workspace 包 |+| `pnpm test:v1` | `node --import tsx --test 'test/**/*.test.ts'` |+| `pnpm test:v2` | `node --import tsx --test 'packages/*/test/**/*.test.ts' 'tools/*.test.mjs'` |++关于受环境开关控制的测试与测试写法,参见 [Testing](./testing.md)。++## 仓库结构++```text+svml/+├── packages/ 64 v2 workspace packages (the active system)+├── spec/ 7 normative specification documents+├── docs/ VitePress documentation site+├── examples/ v2 examples and v1 regression fixtures+├── services/ Python sidecar services (whisperx, image-opencv)+├── src/ v1 legacy source (regression evidence only)+├── stdlib/ v1 kernel definitions and runtime+├── test/ v1 test suite+├── tools/ boundary tests and build scripts+├── package.json root workspace manifest+├── pnpm-workspace.yaml workspace: [packages/*]+├── tsconfig.json v1 TypeScript config+└── tsconfig.v2.json v2 TypeScript config+```++`src/`、`stdlib/` 与 `test/` 是 v1 research oracle,作为回归证据保留下来。它们不是 v2 API。++## 指南目录++| 指南 | 主题 |+|---|---|+| [包架构](./packages.md) | 四个层次、依赖规则、包的构成、facets |+| [添加 Author 包](./author-packages.md) | 分步说明:新增组件、Surface、activation |+| [添加 Provider](./providers.md) | 分步说明:新增 Endpoint 适配器 |+| [Runtime Profile](./runtime-profile.md) | JSON 与 TypeScript 配置、诊断、Build 归档 |+| [本地服务](./services.md) | WhisperX 与 OpenCV sidecar 的搭建 |+| [测试](./testing.md) | 测试运行器、写法、示例、boundary tests |+| [代码规范](./conventions.md) | 命名、模块边界、wire 数据、TypeScript 配置 |diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.mdnew file mode 100644index 00000000..da0f64bf--- /dev/null+++ b/docs/zh/guide/packages.md@@ -0,0 +1,200 @@+---+title: 包架构+description: 四个分层、依赖边界、包的结构与 facet。+---++# 包架构++`packages/` 下的 64 个以上工作区包被组织成四个架构分层。每一层都有严格的依赖规则,并由测试在每次提交时强制执行。++## 四个分层++### Layer 1:领域无关的基础层++这些包实现图语言、Build 状态机、编译器基础设施和 Runtime 端口。它们可以被任意领域复用 —— 不只是视频 —— 并且不依赖 Text、Script、Seedance、Film 或任何视频概念。++```text+@svml/protocol immutable wire contracts+@svml/artifact domain-neutral content-addressed byte type+@svml/core Demand compiler and Build state machine+@svml/source mandatory Source Header+@svml/elaborator author declarations and Fragment expansion+@svml/realization typed realization overlays+@svml/run syntax-neutral Run Graph+@svml/validation semantic admission+@svml/host Host-facing interfaces+@svml/compiler-node reference Node compiler Host+@svml/workspace-fs-node workspace filesystem abstraction+@svml/component-kit Producer/validator registration+@svml/runtime Scheduler and Store ports+@svml/runtime-adapter deployment-adapter ABI+@svml/runtime-adapter-node project-root resolution+@svml/endpoint-kit Endpoint registration+@svml/driver-node trusted Node command executor+@svml/package-loader-node byte-locked package loading+@svml/store-sqlite SQLite Build/Operation stores+@svml/artifact-store-fs filesystem Artifact store+@svml/artifact-store-s3 S3 Artifact store+@svml/credential-store-env environment credentials+@svml/transport invocation seams+@svml/transport-process local process transport+@svml/transport-aws-lambda Lambda transport+@svml/local SQLite/filesystem developer assembly+```++### Layer 2:作者语言层++面向作者的词汇:文本 Frontend、Script Surface、SVS Recipe、Run 文本 Frontend 以及可复用的编译库。++```text+@svml/text official .svml markup Frontend+@svml/script Script Surface+@svml/svs SVS Recipe Frontend+@svml/run-text official .svrun Frontend+@svml/prompt-kit declarative prompt compilation+@svml/compiler-text-node Text Frontend + Surface Host assembly+```++### Layer 3:视频领域层++视频专属类型、生成模型族、语音/字幕/轨道契约以及合成。依赖 Layer 1 和 Layer 2,但不依赖任何 Provider。++```text+@svml/contracts Narrative, Track, Composition contracts+@svml/media media types+@svml/generation image/video product contracts+@svml/model-kit model family abstractions+@svml/seedance Seedance model family + author Surface+@svml/seedance-speaker Seedance Speaker binding+@svml/minimax-h3 MiniMax H3 model family+@svml/gemini-omni Gemini Omni model family+@svml/grok-imagine Grok Imagine model family+@svml/gpt-image GPT Image model family+@svml/nano-banana Nano Banana model family+@svml/seedream Seedream model family+@svml/estimate duration estimation+@svml/speech-program speech program compilation+@svml/speech-take atomic speech take+@svml/speech-align speech alignment+@svml/whisperx WhisperX component+@svml/caption caption planning and Track+@svml/caption-gemini Gemini caption planner+@svml/broll B-roll Track+@svml/text-track text overlay Track+@svml/film Film composition+@svml/hyperframes HyperFrames Visual IR+@svml/hyperframes-render HyperFrames rendering component+@svml/image-transform image processing component+@svml/media-pipeline media inspection/normalization+```++### Layer 4:Provider(Endpoint)包++具备特权的外部能力。依赖 Runtime 端口和它们所服务的模型族,绝不依赖 CLI。++```text+@svml/provider-kie KIE generation (16 model capabilities)+@svml/provider-media-local local ffprobe/ffmpeg+@svml/provider-whisperx-local local WhisperX sidecar+@svml/provider-google-vertex Vertex Gemini caption planning+@svml/provider-hyperframes-local local Chrome rendering+@svml/provider-image-opencv-local local OpenCV image transforms+```++### 应用层++```text+@svml/cli generic command engine (requires explicit Distribution)+@svml/video-cli video command application (selects Text compiler, no built-in author packages)+```++## 依赖规则++`tools/package-boundaries.test.mjs` 在每次提交时强制执行三条不变式:++1. **无环的生产依赖图。** 任何 `@svml/*` 包之间都不存在依赖环。++2. **领域无关闭包。** 每个 Layer 1 包的传递闭包只包含 Layer 1 的包。`@svml/core` 只依赖 `@svml/protocol`。++3. **CLI 独立性。** `@svml/cli` 和 `@svml/video-cli` 都不会传递依赖任何 Provider 包。video CLI 同样不依赖任何作者层的视频包(`@svml/script`、`@svml/seedance-speaker`、`@svml/broll`、`@svml/text-track`、`@svml/film`)。作者包通过显式的 package lock 被 activate,而不是通过编译期的 CLI 依赖。++## 包的结构++每个包都位于 `packages/<name>/` 下,结构如下:++```text+packages/example/+├── package.json+├── src/+│ ├── index.ts public API entry point+│ └── activation.ts package contribution descriptor (if installable)+└── test/+ └── example.test.ts+```++### package.json++```json+{+ "name": "@svml/example",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "svml": {+ "activation": "./src/activation.ts"+ },+ "dependencies": {+ "@svml/protocol": "workspace:*"+ }+}+```++- `"exports"` 直接指向 TypeScript 源码。工作区的 `tsconfig.v2.json` 通过 `paths` 把 `@svml/*` 导入映射到源码入口。+- `"svml.activation"` 是该包被 byte-locked 时 Package Loader 会读取的入口。它必须默认导出一个 `NodePackageContribution`。++### activation.ts++每个可安装的包都会导出一个被动的 contribution 描述符 —— 它是对自身所提供内容的清单,而不是一份权限授予。具体示例参见[添加作者包](./author-packages.md)和[添加 Provider](./providers.md)。++## 五种包 facet++一个物理包可以暴露多个可独立 activate 的 facet:++| Facet | ABI | 权限 | 由谁选择 |+|---|---|---|---|+| `static` | Manifest 与身份 | 无 | 加载后始终可用 |+| `author` | Frontend、Surface、Graph Fragment | 仅作者词汇 | 源码中的 `<import>`,经由编译器 Host |+| `compute` | 确定性 Producer、Type Validator | 纯计算 | 编译器 Host |+| `endpoint` | 具备特权的外部能力 | 网络、文件系统、进程、凭据 | Runtime Profile |+| `runtime` | Scheduler、Store 实现 | 持久化、调度 | Runtime Profile |++源码中的 `<import>` 只会 activate author facet。它绝不授予网络、文件系统、进程、凭据或队列权限。++## 包锁定++SVML 使用按字节锁定的受信任代码执行。加载器会记录每个包的名称、版本和 SHA-256 摘要:++```json+{+ "format": "svml.node-package-lock@1",+ "artifacts": [+ {+ "name": "@svml/seedance",+ "version": "0.0.0-dev",+ "digest": "sha256:abc123..."+ }+ ]+}+```++两个相互独立的 lock 闭包服务于不同的权限范围:++| Lock 文件 | 包含内容 | 身份范围 |+|---|---|---|+| `svml.packages.lock` | Frontend、Surface、Producer、Validator | Author Graph + Run Graph + 执行 Program Closure |+| `svml.runtime-packages.lock` | Provider、Store、transport | Runtime Closure |++修改一个包就需要重新生成 lock。Build 状态机在下发 Command 之前会校验每一个摘要。diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.mdnew file mode 100644index 00000000..51a68e65--- /dev/null+++ b/docs/zh/guide/providers.md@@ -0,0 +1,169 @@+---+title: 添加 Provider+description: 添加新 Endpoint 适配器的分步指南。+---++# 添加 Provider++一个 Provider 包实现一项受控的外部能力——视频生成、媒体处理、对齐、字幕规划、渲染。它通过 Runtime Profile 激活,而不是通过 Author Source 里的 `<import>`。++不需要改动 Core、CLI 或任何作者包。++## 1. 创建包++```bash+mkdir -p packages/provider-my-service/src packages/provider-my-service/test+```++## 2. 编写 package.json++Provider 包依赖 Runtime 端口以及它所服务的模型族,绝不依赖 CLI:++```json+{+ "name": "@svml/provider-my-service",+ "version": "0.0.0-dev",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "svml": { "activation": "./src/activation.ts" },+ "dependencies": {+ "@svml/endpoint-kit": "workspace:*",+ "@svml/protocol": "workspace:*",+ "@svml/runtime": "workspace:*",+ "@svml/runtime-adapter": "workspace:*",+ "@svml/runtime-adapter-node": "workspace:*",+ "@svml/seedance": "workspace:*"+ }+}+```++## 3. 实现 Provider++Provider 处理来自 Scheduler 的 Command:提交请求、轮询、下载以及 ArtifactStore 持久化。++```typescript+// src/provider.ts+import type { EndpointManifest } from "@svml/endpoint-kit";++export function createMyServiceProvider(options: {+ instance: string;+ lane?: string;+ apiKey?: { env: string };+ defaultConcurrency?: number;+}) {+ // 返回一个包含以下内容的对象:+ // - manifest:声明该 Endpoint 实现的 Capability+ // - handle:处理来自 Scheduler 的 Command+ // - close:清理+}+```++可以参考现有的 Provider:+- `packages/provider-kie/src/provider.ts` — 带上传、轮询和下载的远程生成+- `packages/provider-media-local/` — 本地进程执行(ffprobe/ffmpeg)+- `packages/provider-whisperx-local/` — 本地 sidecar HTTP 服务+- `packages/provider-hyperframes-local/` — 本地 Chrome 渲染++## 4. 编写 activation 描述符++```typescript+// src/activation.ts+import {+ createRuntimeEndpointAdapterFacet,+ runtimeConfigObject,+ runtimeConfigString,+ runtimeConfigPositiveInteger,+} from "@svml/runtime-adapter";+import { diagnoseRuntimeEnvironmentCredential } from "@svml/runtime-adapter-node";+import { createMyServiceProvider } from "./provider.js";++const adapter = createRuntimeEndpointAdapterFacet({+ use: "@svml/provider-my-service",++ create(context) {+ const config = runtimeConfigObject(context.config, "MyService");+ const apiKeyEnv = runtimeConfigString(config.apiKeyEnv, "MyService apiKeyEnv");+ return createMyServiceProvider({+ instance: context.instance,+ lane: context.lane,+ ...(apiKeyEnv === undefined ? {} : { apiKey: { env: apiKeyEnv } }),+ ...(runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency") === undefined+ ? {} : { defaultConcurrency: config.defaultConcurrency as number }),+ });+ },++ doctor(context) {+ const config = runtimeConfigObject(context.config, "MyService");+ const apiKeyEnv = runtimeConfigString(config.apiKeyEnv, "MyService apiKeyEnv")+ ?? "MY_SERVICE_API_KEY";+ return diagnoseRuntimeEnvironmentCredential(apiKeyEnv, "MyService");+ },+});++export const svmlPackage = {+ format: "svml.node-package@1" as const,+ name: "@svml/provider-my-service",+ hostFacets: [adapter],+};++export default svmlPackage;+```++`create` 函数根据 Runtime 配置构造 Endpoint。`doctor` 函数返回诊断信息(凭据是否存在、可执行文件是否可用),不构造也不调用任何东西。++## 5. 注册并锁定++在 `tsconfig.v2.json` 中添加路径映射:++```json+"@svml/provider-my-service": ["packages/provider-my-service/src/index.ts"]+```++锁定进 Runtime 包锁文件:++```bash+pnpm svml:v2 lock-packages <runtime-lock> \+ --package @svml/provider-my-service \+ --root .+```++## 6. 在 svml.runtime.json 中引用++```json+{+ "endpoints": [+ {+ "use": "@svml/provider-my-service",+ "instance": "my-service.project",+ "lane": "generation",+ "config": {+ "apiKeyEnv": "MY_SERVICE_API_KEY",+ "defaultConcurrency": 2+ }+ }+ ],+ "permissions": [+ "network:api.my-service.com"+ ]+}+```++验证配置:++```bash+pnpm svml:v2 doctor svml.runtime.json+```++## 可供研究的现有 Provider++| 包 | 模式 |+|---|---|+| `provider-kie` | 远程 API:上传、付费提交、带检查点的轮询、有界下载、即时 ArtifactStore 持久化 |+| `provider-media-local` | 本地进程:不经 shell 的 ffprobe/ffmpeg,执行有界 |+| `provider-whisperx-local` | 本地 sidecar:带热模型的 HTTP 服务,单次准入并发 |+| `provider-google-vertex` | 云 API:带 project/credentials 配置的 Vertex AI |+| `provider-hyperframes-local` | 本地进程:Chrome 渲染,带 worker 并行与输出探测校验 |+| `provider-image-opencv-local` | 本地 Python:有界的 OpenCV/NumPy,配合锁定的 Python 环境 |diff --git a/docs/zh/guide/runtime-profile.md b/docs/zh/guide/runtime-profile.mdnew file mode 100644index 00000000..eedcd944--- /dev/null+++ b/docs/zh/guide/runtime-profile.md@@ -0,0 +1,216 @@+---+title: Runtime Profile+description: 配置 Build 在哪里执行、诊断与 Build 归档。+---++# Runtime Profile++Runtime Profile 声明冻结后的 Build *在哪里*执行:Endpoint、凭据、并发、权限。它属于部署配置,而不是创作内容——它绝不进入 Author Graph 或 Run Graph 的身份。++支持两种形式:++| 形式 | 文件 | 适用场景 |+|---|---|---|+| 声明式 JSON | `svml.runtime.json` | 标准路径 |+| 可执行 TypeScript | `svml.runtime.ts` | 高级嵌入 API |++## 声明式 JSON++```json+{+ "format": "svml.runtime-config@1",+ "packageLock": "./svml.packages.lock",+ "runtimePackageLock": "./svml.runtime-packages.lock",+ "services": [],+ "endpoints": [+ {+ "use": "@svml/provider-kie",+ "instance": "kie.production",+ "lane": "generation",+ "config": {+ "apiKeyEnv": "KIE_API_KEY",+ "defaultConcurrency": 2+ }+ },+ {+ "use": "@svml/provider-media-local",+ "instance": "media.local",+ "lane": "media",+ "config": { "defaultConcurrency": 2 }+ },+ {+ "use": "@svml/provider-whisperx-local",+ "instance": "whisperx.local",+ "lane": "alignment",+ "config": { "defaultConcurrency": 1 }+ },+ {+ "use": "@svml/provider-google-vertex",+ "instance": "vertex.local",+ "lane": "planning",+ "config": {+ "projectEnv": "GOOGLE_CLOUD_PROJECT",+ "credentialsEnv": "GOOGLE_APPLICATION_CREDENTIALS_JSON",+ "defaultConcurrency": 1+ }+ },+ {+ "use": "@svml/provider-hyperframes-local",+ "instance": "hyperframes.local",+ "lane": "render",+ "config": { "workers": 2, "quality": "standard", "defaultConcurrency": 1 }+ }+ ],+ "permissions": [+ "filesystem:whisperx-staging",+ "network:aiplatform.googleapis.com",+ "network:api.kie.ai",+ "network:whisperx-loopback",+ "process:hyperframes",+ "process:media"+ ],+ "scheduling": {+ "maxConcurrency": 4,+ "lanes": {+ "generation": 2,+ "media": 2,+ "alignment": 1,+ "planning": 1,+ "render": 1+ }+ }+}+```++### Endpoint 字段++| 字段 | 含义 |+|---|---|+| `use` | 适配器名称,从 `runtimePackageLock` 解析 |+| `instance` | 该 Endpoint 实例的唯一标识 |+| `lane` | 管辖并发的调度 lane |+| `config` | 适配器专属配置(凭据环境变量、并发、超时) |++凭据通过环境变量名引用,绝不存放在 Profile 里。++### 调度++`maxConcurrency` 限制所有 lane 上并发 Operation 的总量。每个具名 lane 还有自己的子上限。lane 由 Endpoint 声明,并由 Scheduler 强制执行。++### 权限++每个权限字符串向已锁定的 Endpoint 授予一项具体权能:++- `network:<host>` — 到该主机的出站 HTTP+- `filesystem:<scope>` — 在具名作用域内的文件访问+- `process:<name>` — 本地进程执行++## 可执行 TypeScript++用于高级嵌入场景,以编程方式构造 Runtime:++```typescript+import { createProjectLocalRuntime } from "@svml/local";+import { createKieProvider } from "@svml/provider-kie";+import { createLocalMediaProvider } from "@svml/provider-media-local";++export default async function createRuntime() {+ const endpoints = [+ createKieProvider({+ instance: "kie.prod",+ lane: "generation",+ defaultConcurrency: 2,+ }),+ createLocalMediaProvider({+ instance: "media.prod",+ lane: "media",+ defaultConcurrency: 2,+ }),+ ];++ return await createProjectLocalRuntime({+ root: import.meta.dirname,+ packageLock: "./svml.packages.lock",+ endpoints,+ allowedPermissions: endpoints.flatMap(e =>+ e.manifest.facets.flatMap(f => f.permissions)),+ scheduling: {+ maxConcurrency: 4,+ lanes: { generation: 2, media: 2 },+ },+ });+}+```++两种形式都可以传给 `--runtime`:++```bash+pnpm svml:v2 build build.svrun --runtime ./svml.runtime.json+pnpm svml:v2 build build.svrun --runtime ./svml.runtime.ts+```++## 诊断++### doctor++在不运行 Build、不发出付费请求的前提下检查 Runtime Profile:++```bash+pnpm svml:v2 doctor svml.runtime.json+```++校验内容:+- 包锁文件存在且可读+- 适配器字节摘要匹配+- 配置键对各适配器有效+- 引用的凭据在环境中存在+- 找得到所需的可执行文件(ffmpeg、ffprobe、chrome)++### gc(垃圾回收)++```bash+pnpm svml:v2 gc svml.runtime.json # dry-run+pnpm svml:v2 gc svml.runtime.json --apply # delete unreachable Artifacts+```++遍历每个保留的 BuildState 与 Operation,计算可达的 Artifact 摘要,并报告(或删除)不可达的孤儿对象。++## Build 归档与检视++每次 Build 都会持久归档全部已接受的 Record 与被引用的 Artifact,与任何 `--to` 目标路径无关。++### 列出 Build++```bash+pnpm svml:v2 builds --runtime svml.runtime.json+```++### 检视++```bash+pnpm svml:v2 inspect <build-id> --runtime svml.runtime.json+```++显示 target 绑定、被请求的 Logical Output、每个已接受的 Record 以及 Operation 状态。++### 取回 Record++```bash+# By source output name+pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+ --name final.video --to output.mp4++# By Record id+pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+ --record <record-id> --to output.json++# By Logical Output id+pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+ --output <output-id>++# By Artifact digest+pnpm svml:v2 get <build-id> --runtime svml.runtime.json \+ --artifact <sha256:...> --to file.bin+```++`--name` 使用 Host-only Build Catalog 中的来源输出别名。Catalog 只是展示层的便利设施,不进入 Core 的 Build 身份。diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.mddeleted file mode 100644index cd4ba710..00000000--- a/docs/zh/guide/runtime.md+++ /dev/null@@ -1,46 +0,0 @@-----title: 运行时与 Provider-description: 组件怎样连接 Seedance 等外部生成服务。------# 运行时与 Provider--普通视频作者不需要初始化 Runtime,也不需要在项目文件里写 API Key。--## 作者怎么用--登录一次 Provider:--```bash-svml provider login seedance-```--然后在视频里导入和使用组件:--```xml-<svml>- <import as="seedance" from="@svml/seedance@1"/>-- <seedance:speaker- script={story.segment.opening}- character="./host.png"- direction="正对镜头自然说话"- />-</svml>-```--最后正常构建:--```bash-svml build main.svml-```--## 谁负责请求 API--`@svml/seedance` 包自己携带 Runtime 实现,负责排队、请求、轮询和下载。官方 CLI 在看到这个组件后自动加载它。Key 保存在系统钥匙串或用户的全局 SVML 配置里,不进入 `.svml`、锁文件或 Git。--::: info 尚未实现-这是计划中的普通用户体验,不是当前仓库已经提供的命令。现有实现只接受已经准备好的本地媒体与能力产物。-:::--只有把 SVML 嵌入自己产品的开发者,才需要接触 `createRuntime()` 之类的开发接口。diff --git a/docs/zh/guide/services.md b/docs/zh/guide/services.mdnew file mode 100644index 00000000..09d7906c--- /dev/null+++ b/docs/zh/guide/services.md@@ -0,0 +1,81 @@+---+title: 本地服务+description: 配置 WhisperX 与 OpenCV 边车服务。+---++# 本地服务++两个 Python 边车服务为本地 Build 提供支持。它们属于 Runtime 部署包,不属于 Core,也不属于作者语言。++## WhisperX++提供 ASR 以及针对特定语言的对齐能力,用于测量语音时序。++### 安装++WhisperX 3.8.6 支持 Python 3.10–3.13。仓库中已签入的锁文件选定 3.13:++```bash+uv python install 3.13+uv sync --project services/whisperx --frozen+uv run --project services/whisperx --frozen svml-whisperx-prepare+uv run --project services/whisperx --frozen svml-whisperx-check+```++`svml-whisperx-prepare` 会在完成 SHA-256 校验后,从固定版本的归档中安装 NLTK 的 `punkt_tab` 句子数据。WhisperX 的对齐流程需要这份数据,并且它绝不会在推理过程中下载。++首次启动模型时可能会下载 ASR 与对齐权重。生产环境应将 Hugging Face 缓存放在持久化存储上。++### 运行++```bash+uv run --project services/whisperx --frozen svml-whisperx-service+curl http://127.0.0.1:8765/health+```++### 配置++| 变量 | 默认值 | 含义 |+|---|---|---|+| `SVML_WHISPERX_PORT` | `8765` | 回环端口 |+| `SVML_WHISPERX_MODEL` | `small` | faster-whisper 模型 |+| `SVML_WHISPERX_DEVICE` | `cpu` | `cpu` 或已部署的加速器 |+| `SVML_WHISPERX_COMPUTE` | CPU 上为 `int8` | CTranslate2 计算类型 |+| `SVML_WHISPERX_BATCH_SIZE` | `8` | 有上界的 ASR 批大小 |+| `SVML_WHISPERX_INPUT_ROOTS` | 操作系统临时目录 | 以路径分隔符分隔的根目录,服务可读取其中内容 |+| `SVML_WHISPERX_NLTK_DATA` | 用户 SVML 缓存 | 已准备好的 NLTK 数据根目录 |+| `SVML_WHISPERX_MAX_REQUEST_BYTES` | `65536` | HTTP JSON 上限 |+| `SVML_WHISPERX_MAX_AUDIO_BYTES` | `536870912` | 暂存的规范 WAV 上限 |++### 并发++该服务同一时刻只接纳一次推理。第二个请求会收到 `503 BUSY`。并发由 SVML Runtime Scheduler 的 lane 配置管控,而不是由服务自身管控。++Node Provider(`@svml/provider-whisperx-local`)必须配置与之匹配的模型、设备、计算类型和批大小。一旦不匹配,会在结果被接受之前失败。++### 测试++```bash+pnpm test:whisperx-service+```++## OpenCV 图像服务++通过 `@svml/provider-image-opencv-local` 提供有上界的图像变换(例如 GPT Image 的 YCrCb 降噪预设)。++### 安装++```bash+uv python install 3.13+uv sync --project services/image-opencv --frozen+```++### 测试++测试由环境变量门控:++```bash+SVML_OPENCV_TESTS=1 \+SVML_OPENCV_PYTHON=services/image-opencv/.venv/bin/python \+pnpm test:image-opencv+```diff --git a/docs/zh/guide/testing.md b/docs/zh/guide/testing.mdnew file mode 100644index 00000000..473e8e55--- /dev/null+++ b/docs/zh/guide/testing.md@@ -0,0 +1,90 @@+---+title: 测试+description: 测试运行器、测试模式与环境门控的测试。+---++# 测试++## 测试运行器++SVML 使用 Node.js 内置的测试运行器(`node:test`),而不是 Jest、Vitest 或 Mocha。++```bash+pnpm test # everything: v1 + v2+pnpm test:v1 # v1 regression tests+pnpm test:v2 # v2 package tests + boundary tests+```++测试文件位于 `packages/<name>/test/`,扩展名为 `.test.ts`。它们通过 glob `packages/*/test/**/*.test.ts` 被发现。++## 编写测试++```typescript+import assert from "node:assert/strict";+import { describe, test } from "node:test";++import { someFunction } from "@svml/example";++describe("someFunction", () => {+ test("returns the expected result", () => {+ const result = someFunction(input);+ assert.deepStrictEqual(result, expected);+ });+});+```++## 测试模式++### 纯编译测试++最常见的模式。编译一份 Author Source 或 Run Source,然后对生成的图、导出、Record 或计划步骤做断言。绝不调用外部服务。++```typescript+test("compiles the expected exports", async () => {+ const compiler = createCompiler({ root, packageContributions });+ const workspace = await compiler.openFile("fixture.svml");+ const result = await compiler.compileSource(workspace.entry, workspace);+ assert.equal(result.exports.length, 3);+});+```++### Provider 测试++用真实或模拟的外部服务测试 Endpoint 实现。这类测试由环境门控:检查所需的凭据或可执行文件,缺失时跳过。++```typescript+test("generates a video", async (t) => {+ if (!process.env.KIE_API_KEY) {+ t.skip("KIE_API_KEY not set");+ return;+ }+ // ... real API call+});+```++### Boundary 测试++`tools/package-boundaries.test.mjs` 和 `tools/graph-first-value-boundary.test.mjs` 会在整个 workspace 范围内校验结构性不变量:++- 依赖图无环+- 领域中立闭包中只包含领域中立的包+- CLI 不依赖任何 Provider 或作者包++它们作为 `pnpm test:v2` 的一部分,在每次提交时运行。++## 受环境开关控制的测试++| 命令 | 测试内容 | 前置条件 |+|---|---|---|+| `pnpm test:whisperx-service` | Python WhisperX 服务 | Python 3.13、uv、frozen sync |+| `pnpm test:image-opencv` | OpenCV 图像变换 | `SVML_OPENCV_TESTS=1`、`SVML_OPENCV_PYTHON` |+| `pnpm smoke:kie` | 实时付费的 KIE 生成 | `KIE_API_KEY` |++## 测试 fixtures++测试夹具放在 `packages/<name>/test/fixtures/` 或 `test/fixtures/`(v1)。它们是普通的 `.svml`、`.svs` 和 `.svrun` 文件,用于覆盖特定的编译路径。++`examples/` 目录同时充当集成级别的夹具:+- `examples/v2-bootstrap/` — 最小源闭包检查+- `examples/talking-film-graph-check/` — 不含 Provider 的完整图编译+- `examples/echo-pro-aroll/` — 显式复用历史 Candidate 的实时验收diff --git a/docs/zh/index.md b/docs/zh/index.mdindex cc2920e5..658b8ab1 100644--- a/docs/zh/index.md+++ b/docs/zh/index.md@@ -9,7 +9,7 @@ hero:link: /zh/quickstart- theme: alttext: 开发指南- link: /zh/guide/components+ link: /zh/guide/develop---<ClientOnly>diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex 1287cd9e..0b946d4c 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -1,70 +1,136 @@---title: Quickstart-description: 在几分钟内检查并编译第一支 SVML 视频。+description: 搭建 Narratage 并编译你的第一张视频图。---# Quickstart-从一份口播稿开始,编译出可交给 HyperFrames 渲染的视频页面。+**Narratage** 这个名字来自 1933 年《*New York Times*》对电影《*The Power and the+Glory*》的一篇影评。那位影评人造出这个词,用来描述当时的一种新兴电影手法:+**Narration + Montage** —— 旁白的声音推动故事前进,同时画面组接出与之呼应的蒙太奇。++这套系统做的正是这件事。作者写下带有语义锚点的口播 Script,编译器则把生成的视频、字幕、B-roll、+文字与音频组装成一部完成的影片。内部的包作用域是 `@svml`(Semantic Video Markup Language)。## 安装-SVML 目前需要 Node.js 22 和 pnpm。+需要 Node.js 22+ 与 pnpm。```bashpnpm install-pnpm build+pnpm check+pnpm test```-## 先看一个真实例子+## 三份输入-仓库里的 Ranking 示例用 `@name … @/name` 在口播稿中声明语义范围,再让组件消费这个范围。下面是核心节选:+每一次 Build 都接受三份彼此独立的输入:-```xml-<svml version="1">- <import from="../../stdlib/ranking-column.svk"/>-- <script>- <segment id="ranking">- <NARRATOR> @photoshop Photoshop.- <SPEAKER> Powerful, but only if you know how to use it.- Otherwise it becomes a three-hour project @/photoshop.- </segment>- </script>-- <ranking-column id="ranking" z="42">- <item- id="photoshop"- rank="5"- image={ranking-icon-5}- during={script.selection.photoshop}- />- </ranking-column>-</svml>+| 输入 | 各自负责什么 | 典型文件 |+|---|---|---|+| **Author Source** | 口播稿、模型选择、轨道构成、输出图 | `.svml` |+| **Run Source** | 要产出哪些输出、备选 candidates、satisfaction edges | `.svrun` |+| **Runtime Profile** | endpoints、凭据、并发、权限 | `svml.runtime.json` |++Author Source 说明*做什么*。Run Source 说明*要哪些*。Runtime Profile 说明*在哪里做*。++## 检查一张视频图(免费)++`talking-film-graph-check` 示例会编译一张完整的视频图 —— Script、Seedance、Speech、+WhisperX、Gemini Caption、B-roll、Text、Film、HyperFrames —— 全程不调用任何外部服务。++```bash+# 编译 Author Source。+pnpm svml:v2 check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .++# 编译 Run Source 并查看冻结后的 plan。+pnpm svml:v2 plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .```-这里没有手写“第 3 秒到第 7 秒”。定位器会根据口播与媒体,把 `photoshop` Selection 解析成这次构建的真实时间。+`check` 产出带类型的 Author Graph。`plan` 绑定 Author Graph 与 Run Graph,解析 Targets,+并输出冻结的 BuildPlan —— 其中包含 Scheduler 将会发出的每一个 Operation 与 Needs。花钱之前先检查它。++## 跑一次真实的 Build(付费)-## 检查与编译+`echo-pro-aroll` 示例是一部由四条 take 构成的 Seedance Mini 口播人像影片。++前置条件:++- 环境变量中配置 `KIE_API_KEY`、`GOOGLE_CLOUD_PROJECT`、`GOOGLE_APPLICATION_CREDENTIALS_JSON`+- `ffmpeg`、`ffprobe`、Chrome+- 本地 WhisperX 服务正在运行(参见 `services/whisperx/README.md`)+- `examples/echo-pro-aroll/assets/` 下的本地素材(未纳入版本库)```bash-pnpm svml check examples/regen-ranking/regen-ranking.svml-pnpm svml lock examples/regen-ranking/regen-ranking.svml --out svml.lock-pnpm svml compile examples/regen-ranking/regen-ranking.svml \- --lock svml.lock \- --out build/index.html+# 诊断 Runtime 环境。+pnpm svml:v2 doctor examples/echo-pro-aroll/svml.runtime.json++# 提交 Build。+pnpm svml:v2 build examples/echo-pro-aroll/build.svrun \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --package-lock examples/echo-pro-aroll/svml.packages.lock \+ --root . \+ --build-id echo-pro-film-001 \+ --follow++# 取回最终视频。+pnpm svml:v2 get echo-pro-film-001 \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --name final.video \+ --to examples/echo-pro-aroll/output/final.mp4```-`check` 检查声明是否完整;`lock` 固定本次构建实际使用的输入;`compile` 生成确定的 HyperFrames HTML。+每一个被接受的中间 Record 与 Artifact 都会在 Build 完成之前归档。`get` 只是对一个已经持久化的+Record 做一次可选的复制。++## 复用既有结果-## 渲染+SVML 没有隐式缓存。复用结果是显式的 Run Graph 编写工作 —— 声明由历史 Records 支撑的零输入+Candidates,再用 Satisfaction edges 把它们接起来:++```xml+<?svml using="@svml/run-text@1"?>+<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="substitute"/>+ </target-set>++ <build-record id="hook-video"+ build="echo-pro-film-001" output="hook-take.video"/>+ <satisfy output="hook-take.video"+ candidate="hook-video" fidelity="substitute"/>+</svrun>+```++编译出的 plan 会剪掉所有被 substitute Candidates 取代的上游 Operations。这是一次新的 Build,+而不是对上一次的续跑。```bash-pnpm svml render build/index.html --out build/video.mp4+pnpm svml:v2 build examples/echo-pro-aroll/reuse-generated.svrun \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --package-lock examples/echo-pro-aroll/svml.packages.lock \+ --root . --build-id echo-pro-film-reuse-001 --follow+```++## CLI 参考++```text+svml-v2 lock-packages <lock> --package name [--package name ...] [--root dir]+svml-v2 doctor <runtime.json>+svml-v2 gc <runtime.json> [--apply]+svml-v2 check <source> [--package-lock file] [--root dir]+svml-v2 plan <run-source> [--package-lock file] [--root dir]+svml-v2 build <run-source> --runtime profile [--build-id id] [--follow]+svml-v2 status <build-id> --runtime profile+svml-v2 builds --runtime profile+svml-v2 inspect <build-id> --runtime profile+svml-v2 get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]+svml-v2 cancel <build-id> --runtime profile```-::: warning 当前状态-可执行示例需要其本地媒体和对齐证据。在线 Provider 自动加载尚未实现。-:::+## 下一步-接下来可以去[开发指南](/zh/guide/components),了解怎样把常用视觉封装成 SVK 组件。+- [开发指南](./guide/develop.md) —— 仓库结构、包架构、扩展模式。