@univer-cli/doc-typst-facade 1.0.0-beta.2

package/README.md

@@ -0,0 +1,63 @@
+# @univer-cli/doc-typst-facade
+
+English | [简体中文](./README.zh-CN.md)
+
+Compile a constrained Typst source bundle into a plain JavaScript Facade program that creates a complete Univer Doc.
+
+The compilation result also includes structured diagnostics. When the layout needs manual review, the package can generate Typst PNG previews from the same source.
+
+## Installation
+
+```bash
+pnpm add @univer-cli/doc-typst-facade
+```
+
+Requires Node.js 22.12 or higher and uses the platform native binding supported by the package.
+
+## Bundle structure
+
+Bundle root contains `typst.json`, page source and local assets:
+
+```text
+paper/
+├── typst.json
+├── prelude.typ
+├── pages/
+│   ├── 01.typ
+│   └── 02.typ
+└── assets/
+    └── logo.png
+```
+
+The manifest declares `targetUnitId` and an ordered `pages` list. It may also declare `title`, `prelude`, and explicit page IDs. Every path must stay within the bundle root; absolute paths, URLs, parent traversal, and symlinks that escape the root are rejected.
+
+## Quick Start
+
+```ts
+import { compileDocTypstBundle } from "@univer-cli/doc-typst-facade";
+
+const result = await compileDocTypstBundle("./paper", {
+  previewDir: "./review/typst",
+});
+
+console.log(result.javascript);
+console.log(result.diagnostics);
+console.log(result.previews);
+```
+
+`javascript` assumes that `univerAPI` is available in the execution environment. Running it creates the complete Doc identified by `targetUnitId` in the manifest. This ID is internal to the generated program, not the real content identity assigned by Workspace.
+
+No PNG is generated when `previewDir` is omitted. When provided, the same official native binding renders the previews, and each result records its page ID, source path, and output path.
+
+## Diagnostics and failures
+
+Diagnostics have `info`, `warning`, or `error` severity:
+
+- A warning means the result is available but has fidelity limitations or needs manual review.
+- An error means the caller should not apply the generated program to a persistent target.
+- If the program cannot be generated, the package throws `DocTypstFacadeError` or `DaCTypstTranslationError` with diagnostics.
+
+An adapter can identify capability errors with `isDocTypstFacadeError()` and present each issue by source path/span.
+
+For the preset command, see
+[`@univer-cli/doc-typst-facade-command`](../doc-typst-facade-command/README.md).

package/README.zh-CN.md

@@ -0,0 +1,67 @@
+# @univer-cli/doc-typst-facade
+
+[English](./README.md) | 简体中文
+
+把一个受约束的 Typst source bundle 编译为 plain JavaScript Facade program，用于创建完整的 Univer Doc。
+
+编译结果同时包含结构化 diagnostics；需要人工复核版式时，还可以生成与同一 source 对应的 Typst PNG preview。
+
+## 安装
+
+```bash
+pnpm add @univer-cli/doc-typst-facade
+```
+
+要求 Node.js 22.12 或更高版本，并使用 package 支持的平台 native binding。
+
+## Bundle 结构
+
+Bundle root 包含 `typst.json`、页面 source 和本地 asset：
+
+```text
+paper/
+├── typst.json
+├── prelude.typ
+├── pages/
+│   ├── 01.typ
+│   └── 02.typ
+└── assets/
+    └── logo.png
+```
+
+Manifest 声明 `targetUnitId` 和有序 `pages`，也可以声明 `title`、`prelude` 与显式 page ID。所有路径必须
+留在 bundle root 内；绝对路径、URL、parent traversal 和逃逸 root 的 symlink 会被拒绝。
+
+## 快速开始
+
+```ts
+import { compileDocTypstBundle } from "@univer-cli/doc-typst-facade";
+
+const result = await compileDocTypstBundle("./paper", {
+  previewDir: "./review/typst",
+});
+
+console.log(result.javascript);
+console.log(result.diagnostics);
+console.log(result.previews);
+```
+
+`javascript` 假定执行环境已注入 `univerAPI`。执行后会创建 manifest 中 `targetUnitId` 指定的完整 Doc；
+这个 ID 是生成 program 内部的 identity，不是 Workspace 分配的真实 content identity。
+
+省略 `previewDir` 时不生成 PNG。提供后，preview 由同一官方 native binding 渲染，并记录 page ID、source
+path 和输出 path。
+
+## Diagnostics 与失败
+
+Diagnostic 包含 `info`、`warning` 或 `error`：
+
+- warning 表示结果可用，但存在 fidelity 限制或需要人工复核；
+- error 表示调用方不应把生成 program 应用于持久化 target；
+- 无法产生 program 时抛出 `DocTypstFacadeError` 或带 diagnostics 的
+  `DaCTypstTranslationError`。
+
+Adapter 可用 `isDocTypstFacadeError()` 识别 capability error，并按 source path/span 呈现问题。
+
+预设 command 见
+[`@univer-cli/doc-typst-facade-command`](../doc-typst-facade-command/README.zh-CN.md)。

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';module['exports']=require('./index.mjs');

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+//#region src/doc-typst-pages.d.ts
+type DaCTypstMappingGrade = "native editable" | "approximate editable" | "preserved metadata" | "diagnostic";
+interface DaCTypstPreviewArtifactMetadata {
+  readonly pageId: string;
+  readonly path: string;
+  readonly sourcePath: string;
+}
+interface DaCTypstTranslationDiagnostic {
+  readonly fidelityLimit?: string;
+  readonly feature?: string;
+  readonly mappingGrade?: DaCTypstMappingGrade;
+  readonly pageId?: string;
+  readonly recommendedNextAction?: string;
+  readonly reason: string;
+  readonly severity?: "info" | "warning" | "error";
+  readonly sourceNodeId?: string;
+  readonly sourcePath: string;
+  readonly span?: DaCTypstSourceSpan;
+  readonly suggestedRewrite?: string;
+}
+interface DaCTypstSourceSpan {
+  readonly column?: number;
+  readonly endColumn?: number;
+  readonly endLine?: number;
+  readonly line?: number;
+  readonly offset?: number;
+}
+declare function createDaCTranslationDiagnostic(diagnostic: DaCTypstTranslationDiagnostic): DaCTypstTranslationDiagnostic;
+//#endregion
+//#region src/compiler.d.ts
+interface DocTypstBundleManifest {
+  readonly schemaVersion: 1;
+  readonly targetUnitId: string;
+  readonly title?: string;
+  readonly pages: readonly (string | {
+    readonly id?: string;
+    readonly source: string;
+  })[];
+  readonly prelude?: readonly string[];
+}
+type DocTypstDiagnostic = DaCTypstTranslationDiagnostic;
+type DocTypstPreview = DaCTypstPreviewArtifactMetadata;
+interface CompileDocTypstBundleOptions {
+  readonly previewDir?: string;
+}
+interface CompileDocTypstBundleResult {
+  readonly diagnostics: readonly DocTypstDiagnostic[];
+  readonly javascript: string;
+  readonly targetUnitId: string;
+  readonly title: string;
+  readonly previews: readonly DocTypstPreview[];
+}
+/** Parse and compile the lifecycle-neutral paper/typst.json bundle exactly once. */
+declare function compileDocTypstBundle(bundleOrManifestPath: string, options?: CompileDocTypstBundleOptions): Promise<CompileDocTypstBundleResult>;
+//#endregion
+//#region src/error.d.ts
+declare class DocTypstFacadeError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+declare function isDocTypstFacadeError(error: unknown): error is DocTypstFacadeError;
+//#endregion
+//#region src/doc-typst-pages-translator.d.ts
+declare class DaCTypstTranslationError extends DocTypstFacadeError {
+  readonly diagnostics: readonly ReturnType<typeof createDaCTranslationDiagnostic>[];
+  readonly previews: readonly DaCTypstPreviewArtifactMetadata[];
+  constructor(message: string, diagnostics: readonly ReturnType<typeof createDaCTranslationDiagnostic>[], previews?: readonly DaCTypstPreviewArtifactMetadata[]);
+}
+//#endregion
+export { type CompileDocTypstBundleOptions, type CompileDocTypstBundleResult, DaCTypstTranslationError, type DocTypstBundleManifest, type DocTypstDiagnostic, DocTypstFacadeError, type DocTypstPreview, compileDocTypstBundle, isDocTypstFacadeError };