Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

docs: write down the Surface vocabulary and its preview image

rponee42c9125e18d
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.md
index 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 Sur
determines 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
```bash
pnpm install --frozen-lockfile
@@ -150,7 +218,7 @@ The package manager owns installation, versions and integrity. Hypit loads the p
Author or Run Source imports one of its logical offers. Exact Module dependencies declared by its
Manifest 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.md
index 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.md
index 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. 安装
```bash
pnpm 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.md
index 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 |