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: write down the Surface vocabulary and its preview image
rponee42c9125e18d
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.mdindex f64b1159..2b700dd9 100644--- a/docs/guide/author-packages.md+++ b/docs/guide/author-packages.md@@ -67,6 +67,7 @@ export const myComponentMarkupSurfaces = [{tag: "Widget",mode: "structured",outputs: [ /* Types this syntax may author */ ],+ vocabulary: { /* what this element is, and what it looks like — see step 5 */ },implementation: { digest: "sha256:..." },}] as const;```@@ -95,7 +96,74 @@ Look at existing Surface implementations for reference:- `packages/caption/src/surface.ts` — the common Program Surface; concrete Style/Track Surfaces live in Style-family packages- `packages/media-track/src/surface.ts` — Track, Item and Sequence Surfaces-## 5. Write the activation descriptor+## 5. Declare the Surface vocabulary and its preview++`vocabulary` is how the element explains itself. Authors read it, and so does every tool that+inspects installed packages instead of reading source. A Surface without it is legal and invisible:+whoever meets your element next has only the tag name to go on.++```typescript+// src/manifest.ts+import { readFile } from "node:fs/promises";++const previewImage = (file: string) => ({+ mediaType: "image/png",+ path: `preview/${file}`,+ open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),+});++vocabulary: {+ summary: "One sentence naming what this element produces and what it is placed on.",+ appearance: "What a viewer actually sees, including how it enters, holds and leaves.",+ preview: previewImage("Widget.png"),+ attributes: [+ { name: "id", kind: "identifier", required: true, summary: "Names this Widget." },+ ],+ children: [ /* accepted child elements */ ],+ ports: [ /* declared edges */ ],+ example: "<mine:Widget id=\"first\" space={speech.space}/>",+ notes: [ /* rules a reader would otherwise have to discover by failing */ ],+}+```++Declare a `preview` for every Surface whose result a reader needs to see to understand it. That is+not only Surfaces producing a `VisualTrack`: `@hypit/speech-spine` declares one for a Spine because+its shape is easier to see than to describe. Skip it for a Surface with nothing to show, such as one+that only assembles a request.++`appearance` and `preview` answer different questions and neither replaces the other. `appearance`+says what the element draws in every case; the preview shows one honest instance of it.++Study `packages/media-track/src/manifest.ts` for a complete vocabulary, and+`packages/typography-track/`, `packages/caption-fine/`, `packages/deck-track/`,+`packages/comment-sticker/`, `packages/screen-overlay/`, `packages/ranking/` and+`packages/speech-spine/` for their `preview/` directories.++### Producing the preview image++The preview is a real frame of your own component, rendered locally. Nothing generates it for you,+and a mock-up drawn by hand is worse than no preview at all, because it claims to be output.++Render one the way the repository's own visual tests do —+`packages/hyperframes/test/browser-visual.test.ts` is the working example, and the sequence is:++1. build the Track value with your package's own render function, over a sealed ProgramSpace;+2. `sealComposition({ id, canvas, tracks })`, then `compileHyperframesDocument(composition, space)`+ from `@hypit/hyperframes`;+3. `materializeHyperframesHtml(document, resolve)` into a temporary directory, where `resolve` maps+ each declared Artifact — fonts, images — to a local file;+4. run the pinned HyperFrames CLI's `render` on that directory with a PNG-sequence output, resolved+ through `@hypit/provider-hyperframes-local`;+5. keep one frame that shows the component in a representative state, and commit it under+ `preview/`.++The alternative is a narrow `.svrun` Target rendered by the local HyperFrames Provider, then one+frame taken with `ffmpeg`. That is a Build; it needs a Runtime Profile, and it is the heavier route.++Choose a frame mid-behaviour rather than at rest. A preview of an element that has not entered yet,+or has already settled into a static end state, shows the least useful thing about it.++## 6. Write the activation descriptor```typescript// src/activation.ts@@ -130,7 +198,7 @@ when the package intentionally owns a genuinely different logical alias. The Surdetermines the accepted tag (`<mine:Widget>` when imported as `mine`). It is a Markup Host facet,not part of the semantic Module Manifest or Core.-## 6. Declare package dependencies+## 7. Declare package dependencies```json"dependencies": {@@ -140,7 +208,7 @@ not part of the semantic Module Manifest or Core.pnpm workspace links resolve the package. No root path registry is involved.-## 7. Install+## 8. Install```bashpnpm install --frozen-lockfile@@ -150,7 +218,7 @@ The package manager owns installation, versions and integrity. Hypit loads the pAuthor or Run Source imports one of its logical offers. Exact Module dependencies declared by itsManifest are loaded from its installed dependencies.-## 8. Use in Author Source+## 9. Use in Author Source```xml<?svml using="@hypit/markup@1"?>diff --git a/docs/guide/develop.md b/docs/guide/develop.mdindex f55c2c2c..130ea9e4 100644--- a/docs/guide/develop.md+++ b/docs/guide/develop.md@@ -53,7 +53,7 @@ hypit/| Guide | Topic ||---|---|| [Package architecture](./packages.md) | The five layers, dependency rules, package anatomy, facets |-| [Adding an author package](./author-packages.md) | Step-by-step: new component, Surface, activation |+| [Adding an author package](./author-packages.md) | Step-by-step: new component, Surface, vocabulary and preview, activation || [Adding a Provider](./providers.md) | Step-by-step: new Endpoint adapter || [Runtime](./runtime.md) | Profile, Workspace, execution and lifecycle boundaries || [Testing](./testing.md) | Test runner, patterns, examples, boundary tests |diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.mdindex 812c49b6..4a900aed 100644--- a/docs/zh/guide/author-packages.md+++ b/docs/zh/guide/author-packages.md@@ -64,6 +64,7 @@ export const myComponentMarkupSurfaces = [{tag: "Widget",mode: "structured",outputs: [ /* 这段语法可以创作的 Type */ ],+ vocabulary: { /* 这个元素是什么、长什么样 —— 见第 5 步 */ },implementation: { digest: "sha256:..." },}] as const;```@@ -91,7 +92,57 @@ export const decodeMyComponentSurface: StructuredSurfaceHandler = ({ element })- `packages/caption/src/surface.ts` —— 公共 Program Surface;具体 Style/Track Surface 属于各样式族包- `packages/media-track/src/surface.ts` —— Track、Item 和 Sequence Surface-## 5. 编写 activation 描述符+## 5. 声明 Surface 词表与预览图++`vocabulary` 是这个元素自我说明的地方。创作者要读它,任何不去翻源码、只检视已安装包的工具也要读它。一个没有词表的 Surface 是合法的,同时也是不可见的:下一个碰到你这个元素的人,手上只有一个标签名。++```typescript+// src/manifest.ts+import { readFile } from "node:fs/promises";++const previewImage = (file: string) => ({+ mediaType: "image/png",+ path: `preview/${file}`,+ open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),+});++vocabulary: {+ summary: "一句话说明这个元素产出什么、被放在什么之上。",+ appearance: "观众实际看到的东西,包括它如何进入、如何保持、如何离开。",+ preview: previewImage("Widget.png"),+ attributes: [+ { name: "id", kind: "identifier", required: true, summary: "为这个 Widget 命名。" },+ ],+ children: [ /* 接受的子元素 */ ],+ ports: [ /* 声明的边 */ ],+ example: "<mine:Widget id=\"first\" space={speech.space}/>",+ notes: [ /* 读者不看就只能靠报错发现的规则 */ ],+}+```++凡是读者必须看一眼产出才能理解的 Surface,都要声明 `preview`。这不限于产出 `VisualTrack` 的 Surface:`@hypit/speech-spine` 也为 Spine 声明了预览图,因为它的形态看一眼比读一段描述更快。没有可展示产出的 Surface 可以不声明,例如只负责装配请求的那种。++`appearance` 和 `preview` 回答的是两个不同的问题,谁都替代不了谁:`appearance` 说的是这个元素在所有情况下都会画出什么,预览图给出的是其中一个诚实的实例。++完整词表可研究 `packages/media-track/src/manifest.ts`;`preview/` 目录可参考 `packages/typography-track/`、`packages/caption-fine/`、`packages/deck-track/`、`packages/comment-sticker/`、`packages/screen-overlay/`、`packages/ranking/` 和 `packages/speech-spine/`。++### 预览图怎么产出++预览图是你自己这个组件在本地渲染出来的真实一帧。没有任何工具会替你生成它,而手工画的示意图比没有预览图更糟,因为它冒充了真实产出。++按仓库自身视觉测试的做法渲染即可 —— `packages/hyperframes/test/browser-visual.test.ts` 就是可运行的示例,步骤是:++1. 用你自己包的 render 函数,在一个封好的 ProgramSpace 上构造出 Track 值;+2. `sealComposition({ id, canvas, tracks })`,再用 `@hypit/hyperframes` 的 `compileHyperframesDocument(composition, space)`;+3. `materializeHyperframesHtml(document, resolve)` 写进一个临时目录,其中 `resolve` 把声明的每个 Artifact(字体、图片)映射到本地文件;+4. 用经由 `@hypit/provider-hyperframes-local` 解析出的、版本被钉住的 HyperFrames CLI 对该目录执行 `render`,输出 PNG 序列;+5. 留下能代表该组件状态的一帧,提交到 `preview/` 下。++另一条路是写一个窄的 `.svrun` Target,交给本地 HyperFrames Provider 渲染,再用 `ffmpeg` 取一帧。那是一次 Build,需要 Runtime Profile,也更重。++选帧要选行为进行中的那一刻,而不是静止的时刻。一个还没入场、或者已经落定成静态终态的预览图,展示的恰好是这个元素最没用的一面。++## 6. 编写 activation 描述符```typescript// src/activation.ts@@ -120,12 +171,9 @@ export const hypitPackage = {export default hypitPackage;```-Module 会自动提供精确的 `[email protected]`,所以作者直接导入-`@hypit/my-component@1`,无需再声明一份重复别名。只有包确实拥有另一个逻辑名称时-才使用可选的 `specifiers`。Surface declaration 决定可接受的标签(以 `mine` 导入时即为-`<mine:Widget>`)。它属于 Markup Host facet,不属于语义 Module Manifest,更不属于 Core。+Module 会自动提供精确的 `[email protected]`,所以作者直接导入 `@hypit/my-component@1`,无需再声明一份重复别名。只有包确实拥有另一个逻辑名称时才使用可选的 `specifiers`。Surface declaration 决定可接受的标签(以 `mine` 导入时即为 `<mine:Widget>`)。它属于 Markup Host facet,不属于语义 Module Manifest,更不属于 Core。-## 6. 声明包依赖+## 7. 声明包依赖```json"dependencies": {@@ -135,16 +183,15 @@ Module 会自动提供精确的 `[email protected]`,所以作者pnpm 工作区链接负责解析包,不需要根路径注册表。-## 7. 安装+## 8. 安装```bashpnpm install --frozen-lockfile```-包管理器负责安装、版本与完整性。Author 或 Run Source 导入逻辑能力时,Hypit 才会加载-对应包;Manifest 声明的精确 Module 依赖从该包的已安装依赖中加载。+包管理器负责安装、版本与完整性。Author 或 Run Source 导入逻辑能力时,Hypit 才会加载对应包;Manifest 声明的精确 Module 依赖从该包的已安装依赖中加载。-## 8. 在 Author Source 中使用+## 9. 在 Author Source 中使用```xml<?svml using="@hypit/markup@1"?>diff --git a/docs/zh/guide/develop.md b/docs/zh/guide/develop.mdindex 9eed9ff0..b6a3a25e 100644--- a/docs/zh/guide/develop.md+++ b/docs/zh/guide/develop.md@@ -53,7 +53,7 @@ hypit/| 指南 | 主题 ||---|---|| [包架构](./packages.md) | 五个层次、依赖规则、包的构成、facets |-| [添加 Author 包](./author-packages.md) | 分步说明:新增组件、Surface、activation |+| [添加 Author 包](./author-packages.md) | 分步说明:新增组件、Surface、词表与预览图、activation || [添加 Provider](./providers.md) | 分步说明:新增 Endpoint 适配器 || [Runtime](./runtime.md) | Profile、Workspace、执行与生命周期边界 || [测试](./testing.md) | 测试运行器、写法、示例、boundary tests |