feat: add Typst-based Doc generation example

CONTEXT.md

@@ -35,3 +35,43 @@ _Avoid_: screenshot, inspection result
 **Review URL**:
 A Server-scoped URL for viewing a trunk or Worktree Slide deck while the example's Web Server is running.
 _Avoid_: public URL, permanent share link
+
+**Typst Source Bundle**:
+The author-owned manifest, ordered Typst page sources, optional prelude, and local assets used to create one Univer Doc.
+_Avoid_: generated program, output directory
+
+**Materialized Doc**:
+A Univer Doc created by executing the Facade program compiled from a Typst Source Bundle.
+_Avoid_: Typst document, preview
+
+**Local Doc Library**:
+A local collection of Generated Artifacts whose Materialized Docs can be discovered for human review.
+_Avoid_: Workspace, document database
+
+**Local Doc Viewer**:
+A read-only browser surface for choosing and viewing Materialized Docs from a Local Doc Library.
+_Avoid_: editor, Review URL, screenshot viewer
+
+**Local Doc Identity**:
+The `targetUnitId` shared by a Typst Source Bundle and its Materialized Doc inside one example build; it is not an external Workspace identity.
+_Avoid_: Workspace ID, remote Unit ID
+
+**Generated Artifact**:
+A replaceable output derived from a Typst Source Bundle, such as a Facade program, diagnostics, Doc UnitData, or PNG.
+_Avoid_: source, authored document
+
+**Typst Preview**:
+A PNG rendered directly from a Typst Source Bundle as evidence of the source-side layout.
+_Avoid_: Univer Screenshot, final preview
+
+**Univer Screenshot**:
+A PNG rendered from a Materialized Doc as evidence of the resulting Univer layout.
+_Avoid_: Typst Preview, source preview
+
+**Machine Result**:
+The single JSON document written to stdout when an example command succeeds in `--json` mode.
+_Avoid_: JSON log, success message
+
+**Machine Failure**:
+The single JSON document written to stderr when an example command fails in `--json` mode.
+_Avoid_: stdout error, human-readable stack trace

README.md

@@ -12,9 +12,11 @@ architecture live on the [Univer Office documentation site](https://office.unive
 | [`03-visual-inspection`](./examples/03-visual-inspection/README.md)   | Visually inspect all three Unit types                   | Render Page, Screenshot, Layout Lint       |
 | [`04-worktree`](./examples/04-worktree/README.md)                     | Edit in a draft and hand it to a human for review       | Worktree, Ready, Merge, Reopen, Discard    |
 | [`slide-gen-cli`](./examples/slide-gen-cli/README.md)                 | Generate, review, export, and view Slides with an Agent | SVG Compile, Resource Library, Agent Skill |
+| [`doc-gen`](./examples/doc-gen/README.md)                             | Author and visually verify a Doc with Typst             | Typst Compile, Doc Materialization         |
 
-Read them in numbered order. Each directory has its own `package.json`, lockfile, and dependencies,
-so it can be copied and run independently.
+Read examples `01` through `04` in numbered order. Unnumbered examples are self-contained. Each
+directory has its own `package.json`, lockfile, and dependencies, so it can be copied and run
+independently.
 
 ## 01 Content Operations
 

README.zh-CN.md

@@ -12,8 +12,10 @@
 | [`03-visual-inspection`](./examples/03-visual-inspection/README.zh-CN.md)   | 视觉检查前三种 Unit                     | Render Page、Screenshot、Layout Lint       |
 | [`04-worktree`](./examples/04-worktree/README.zh-CN.md)                     | 在 draft 编辑并交给人审阅               | Worktree、Ready、Merge、Reopen、Discard    |
 | [`slide-gen-cli`](./examples/slide-gen-cli/README.zh-CN.md)                 | 借助 Agent 生成、审阅、导出和查看 Slide | SVG Compile、Resource Library、Agent Skill |
+| [`doc-gen`](./examples/doc-gen/README.zh-CN.md)                             | 使用 Typst 创作并视觉检查 Doc            | Typst Compile、Doc Materialization         |
 
-请按编号阅读。每个目录都有自己的 `package.json`、lockfile 和依赖，可以独立复制和运行。
+请按编号阅读 `01` 至 `04`；无编号 example 各自独立。每个目录都有自己的 `package.json`、lockfile
+和依赖，可以独立复制和运行。
 
 ## 01 Content Operations
 

examples/doc-gen/.gitignore

@@ -0,0 +1 @@
+/output/

examples/doc-gen/README.md

@@ -0,0 +1,172 @@
+# Doc Gen
+
+English | [简体中文](./README.zh-CN.md)
+
+This agent-oriented example creates editable local Univer Docs from Typst. For each request, the
+agent creates or revises a task-specific Typst Source Bundle, compiles it, materializes the generated
+Facade program in headless Univer, saves Doc UnitData, and reviews source-side and Univer-side PNGs.
+
+## Set up the example
+
+Requires Node.js 22.12 or later and pnpm 10.32.1.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+pnpm link-cli
+pnpm skill:install
+```
+
+Open this directory with an Agent and ask it to use `doc-gen`, for example:
+
+```text
+Use doc-gen to create a two-page customer research brief. Keep the source under
+authoring/customer-research and generated artifacts under output/customer-research.
+```
+
+The Agent creates the source instead of editing a bundled document. If you already have a bundle,
+give its directory or `typst.json` path in the request.
+
+## Typst Source Bundle
+
+The path is caller-selected. A typical bundle looks like:
+
+```text
+authoring/customer-research/
+├── typst.json
+├── prelude.typ
+├── pages/
+│   ├── 01.typ
+│   └── 02.typ
+└── assets/
+    └── diagram.svg
+```
+
+`typst.json` declares the Local Doc Identity and ordered page sources:
+
+```json
+{
+  "schemaVersion": 1,
+  "targetUnitId": "customer-research",
+  "title": "Customer research brief",
+  "prelude": ["prelude.typ"],
+  "pages": [
+    { "id": "page-01", "source": "pages/01.typ" },
+    { "id": "page-02", "source": "pages/02.typ" }
+  ]
+}
+```
+
+`schemaVersion`, `targetUnitId`, and `pages` are required. `title`, `prelude`, explicit page IDs,
+and local `assets/` are optional. All referenced paths must stay inside the bundle. The authored
+bundle remains source; generated JavaScript, JSON, and PNG files do not.
+
+`targetUnitId` connects this bundle to its Materialized Doc inside the local build. It is not a Workspace identity or remote Unit ID.
+
+Build any bundle directory or manifest path with a separate output directory:
+
+```bash
+doc-gen compile-typst <bundle-or-manifest> --out <output-directory> --json
+```
+
+## Generated Artifacts
+
+The required `--out` directory receives:
+
+| Path               | Meaning                                          |
+| ------------------ | ------------------------------------------------ |
+| `document.js`      | Facade program generated from the current bundle |
+| `diagnostics.json` | Structured compiler diagnostics                  |
+| `document.json`    | Saved Materialized Doc UnitData                  |
+| `typst/*.png`      | Typst Previews for source-side layout review     |
+| `univer/*.png`     | Univer Screenshots for the converted Doc         |
+
+The command replaces only these known artifacts. Other files in the output directory remain untouched, and the example ignores `/output/` in Git.
+
+In `--json` mode, success writes one Machine Result to stdout. Failure writes one Machine Failure to stderr. Error diagnostics stop before materialization; warnings allow success and remain in the result for review.
+
+## View generated Docs
+
+Use `output/<slug>` when you want a generated Doc to appear in the repository-local Local Doc
+Library:
+
+```bash
+doc-gen compile-typst authoring/customer-research \
+  --out output/customer-research --json
+pnpm viewer
+```
+
+The loopback-only page opens in your browser and lists every matching
+`output/<slug>/document.json`. Select an entry in the sidebar to switch Docs. Add or remove a Doc
+while the page is running and use the automatic development update or **Refresh** to update the
+list without restarting Vite.
+
+The Viewer loads a disabled in-memory copy and hides Univer's editing ribbon and floating formatting UI. Typing, pasting,
+deleting, formatting, saving, and file write-back are unavailable; scrolling, zooming, text
+selection, and copying remain available. An
+explicit `--out` path outside `output/<slug>` still works with every CLI command but does not appear
+in the Viewer.
+
+`pnpm build` records the Local Doc Library visible at build time in `dist/viewer`; rebuild to include
+later changes. That directory is a local snapshot, not a published or continuously updated service.
+The Viewer supports human inspection only and does not replace Agent review of Typst Previews and
+the latest Univer Screenshots.
+
+## Visual review
+
+Read both PNG groups after every successful build:
+
+1. Check Typst Previews for requested text, hierarchy, margins, wrapping, and table geometry.
+2. Check Univer Screenshots for the same content, clipping, missing blocks, and conversion differences.
+3. Report remaining warnings. Visual verification stays pending if either image group cannot be read by an image-capable model.
+
+The bundled `doc-gen` skill encodes bundle creation, compilation, and review. Install or remove its
+local symlink with:
+
+```bash
+pnpm skill:install
+pnpm skill:uninstall
+```
+
+## Refine the Materialized Doc
+
+Fix content and layout in the Typst Source Bundle whenever possible, then rebuild. For a native Doc
+capability or a final precise adjustment, query the installed offline Facade reference:
+
+```bash
+doc-gen api find paragraph --unit doc
+doc-gen api show FDocumentParagraph.setText
+```
+
+Write the adjustment as a task-local script. `execute` supplies `univerAPI`, `api`, and `doc`; the
+script must not redeclare them. Read the script before running it, check mutation return values, and
+return JSON-compatible readback explicitly:
+
+```js
+const paragraph = doc.getParagraphs()[0];
+if (!paragraph) throw new Error("paragraph missing");
+const changed = paragraph.setText(`${paragraph.getText()} [reviewed]`);
+if (!changed) throw new Error("paragraph update failed");
+return { text: paragraph.getText() };
+```
+
+Apply it to the current Materialized Doc, refresh its screenshots, and read every new PNG:
+
+```bash
+doc-gen execute <output-directory>/document.json --file <task-script.js> --json
+doc-gen screenshot <output-directory>/document.json \
+  --out <output-directory>/univer --json
+```
+
+`execute` changes the Generated Artifact, not the Typst Source Bundle. A later `compile-typst`
+rebuild replaces those changes; reapply any still-needed final adjustment afterward. There is no
+automatic replay.
+
+## Runtime boundaries
+
+- Typst compilation supports the native binding targets published for macOS x64/arm64, Linux glibc x64/arm64, and Windows x64. Linux musl and Windows arm64 are outside this example's supported matrix.
+- Univer Screenshots require Chrome, Chromium, or Edge. Set `UNIVER_RENDER_BROWSER` when automatic discovery cannot find the executable.
+- The example includes its application-owned 90-day development license for headless execution and screenshots. Replace it on the stated rotation schedule in `src/shared/license.ts`.
+- `compile-typst` uses only the package's native Typst binding and executes only the program returned by its current compile. It does not use a system Typst executable.
+- `execute` runs trusted local JavaScript supplied with `--file`; it is not sandboxed. Do not run downloaded, unknown, or previously generated `document.js` files.
+- `screenshot` reads `document.json` directly through the Render Runtime and does not create a headless Univer, Server, or Worktree.