+
+ Web Report Designer · Demo
+
+
+
+
+
+
+
+
diff --git a/code/one-designer/apps/demo/src/main.ts b/code/one-designer/apps/demo/src/main.ts
new file mode 100644
index 00000000..b701a8af
--- /dev/null
+++ b/code/one-designer/apps/demo/src/main.ts
@@ -0,0 +1,6 @@
+import { createApp } from "vue"
+// 组件样式由库构建产出，宿主需显式引入（设计令牌由 injectThemeStyle 注入）。
+import "@report/designer-vue/style.css"
+import App from "./App.vue"
+
+createApp(App).mount("#app")
diff --git a/code/one-designer/apps/demo/vite.config.ts b/code/one-designer/apps/demo/vite.config.ts
new file mode 100644
index 00000000..5f28a97f
--- /dev/null
+++ b/code/one-designer/apps/demo/vite.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from "vite"
+import vue from "@vitejs/plugin-vue"
+
+export default defineConfig({
+ plugins: [vue()],
+ server: {
+ port: 5180,
+ host: "127.0.0.1",
+ },
+})
diff --git a/code/one-designer/n1.yaml b/code/one-designer/n1.yaml
new file mode 100644
index 00000000..e69de29b
diff --git a/code/one-designer/package.json b/code/one-designer/package.json
new file mode 100644
index 00000000..6e9ed5d7
--- /dev/null
+++ b/code/one-designer/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "report-designer-monorepo",
+ "version": "0.0.0",
+ "private": true,
+ "description": "Web Report Designer —— 面向业务系统的纯 Web、可嵌入、插件式报表设计与渲染平台",
+ "type": "module",
+ "packageManager": "pnpm@11.8.0",
+ "engines": {
+ "node": ">=20"
+ },
+ "scripts": {
+ "build": "pnpm -r --workspace-concurrency=1 --filter \"./packages/**\" run build",
+ "test": "pnpm -r --workspace-concurrency=1 --filter \"./packages/**\" run test",
+ "typecheck": "pnpm -r --workspace-concurrency=1 --filter \"./packages/**\" run typecheck",
+ "clean": "pnpm -r exec rm -rf dist .turbo node_modules/.cache"
+ },
+ "devDependencies": {
+ "typescript": "^5.7.2",
+ "tsup": "^8.3.5",
+ "vitest": "^2.1.8",
+ "@types/node": "^22.10.2"
+ }
+}
diff --git a/code/one-designer/packages/report-core/README.md b/code/one-designer/packages/report-core/README.md
new file mode 100644
index 00000000..0385a8fb
--- /dev/null
+++ b/code/one-designer/packages/report-core/README.md
@@ -0,0 +1,203 @@
+# @report/core
+
+报表文档模型、插件契约、校验、序列化与迁移。这是 Web Report Designer 的最底层包。
+
+> 对应设计文档 §4.1、§5、§6、§7、§12、§13。
+
+## 定位
+
+`@report/core` 是**纯 TypeScript** 包：无 Vue / React、无 DOM、无浏览器 API、无 UI 框架。
+因此它可以在 Browser、Node.js、Electron、Server 和 CLI 中复用（架构原则 §3.1）。
+
+Core 不依赖任何上层实现包，也不反向依赖任何具体插件。
+
+## 安装与使用
+
+```bash
+pnpm add @report/core
+```
+
+```ts
+import {
+ createDocument,
+ serialize,
+ deserialize,
+ createEditSession,
+ createCommand,
+ resolvePageSize,
+} from "@report/core"
+
+// 新建文档
+const doc = createDocument({ name: "销售单", page: { paper: "A4" } })
+
+// 解析纸张尺寸（mm）
+const size = resolvePageSize(doc.page) // { width: 210, height: 297 }
+
+// 序列化（稳定排序，便于版本控制 diff）
+const json = serialize(doc, { pretty: true })
+
+// 反序列化：parse → validate → migrate → normalize
+const result = deserialize(json)
+if (result.ok) {
+ console.log(result.document?.name)
+}
+console.log(result.diagnostics)
+```
+
+## 核心概念
+
+### 文档模型：文档 → 区域 → 元素树
+
+不把所有元素平铺在根节点上。区域（`ReportSection`）有 7 种 `kind`，V1 只实现
+`page-header` / `detail` / `page-footer`，其余保留模型扩展点。
+
+### 单位约定
+
+文档内部统一使用 **mm**；px 只用于 Designer 显示层，pt 只在 PDF 等输出边界转换（§7）。
+`paper` + `orientation` 是配置来源，由 `resolvePageSize` 在布局阶段解析为最终 width/height。
+
+### 纯数据约束
+
+`ReportDocument` 只保存可序列化的报表定义，**不保存**编辑器状态（§3.2）：
+当前选中项、缩放比例、滚动位置、辅助线、撤销栈、已加载数据和网络连接均不得进入文档。
+`serialize` 会在规范化之前先断言纯数据性，混入函数或 DOM 节点会直接抛 `TypeError`。
+
+### 诊断而非异常
+
+数据缺失、表达式错误、字体缺失、插件缺失、分页失败都通过 `Diagnostic` 表达，
+并尽量带上 `path`（JSON Pointer 风格字段路径）与 `elementId`，不中断文档读取（§13）。
+
+```ts
+import { DIAGNOSTIC_CODES, DiagnosticBag, formatDiagnostic } from "@report/core"
+
+const bag = new DiagnosticBag()
+bag.warn(DIAGNOSTIC_CODES.REF_DANGLING_DATASET, "区域引用了不存在的数据集", {
+ path: "/sections/1/datasetId",
+})
+console.log(bag.all().map(formatDiagnostic))
+```
+
+### 序列化与迁移流程（§12）
+
+```
+deserialize(json)
+ → parse 解析 JSON
+ → validate 校验结构
+ → migrate 按版本逐步迁移
+ → normalize 规范化默认值
+```
+
+- `schemaVersion` 使用单调递增整数，当前为 `CURRENT_SCHEMA_VERSION`。
+- 迁移函数**按版本逐步执行**，`planMigrations` 会强制 `to === from + 1`，禁止跨版本跳跃。
+- 序列化结果按键名稳定排序，便于 diff。
+- 版本高于当前支持时**拒绝读取**，避免降级写坏数据。
+
+新增 schema 版本时，在 `src/schema/version.ts` 的 `MIGRATIONS` 中追加一项即可。
+
+### 命令与撤销重做
+
+Designer 通过 Core 的命令接口修改文档，不直接实现报表业务规则（§4.5）。
+**撤销栈属于编辑器状态，不进入文档**（§3.2），因此 `History` 由调用方持有。
+
+```ts
+import { createCommand, createEditSession } from "@report/core"
+
+const rename = createCommand<{ name: string }>("rename", (doc, payload) => {
+ const next = JSON.parse(JSON.stringify(doc))
+ next.name = payload.name
+ return next
+})
+
+const session = createEditSession(createDocument({ name: "A" }))
+session.execute(rename, { name: "B" })
+session.undo() // 回到 "A"
+session.redo() // 回到 "B"
+
+// 事务：多次编辑合并为一步撤销
+session.transaction("批量调整", (s) => {
+ s.applyWithinTransaction(rename, { name: "C" })
+ s.applyWithinTransaction(rename, { name: "D" })
+})
+```
+
+撤销采用**快照式**而非反向命令式：文档是纯数据且体量可控，快照成本可接受，
+且天然正确处理「一个事务改了多处」的情况。`mergeKey` + `mergeWindow` 用于合并
+拖拽、连续输入这类高频操作。
+
+### 插件
+
+插件只通过契约接入，Core 不导入任何具体插件实现（§11）。
+插件缺失或版本不兼容只产生诊断，不阻止文档读取。
+
+```ts
+import { PluginRegistry } from "@report/core"
+
+const registry = new PluginRegistry()
+registry.register({
+ id: "plugin-qrcode",
+ version: "1.2.0",
+ compatibleSchemaVersion: ">=1.0.0",
+ elements: [
+ {
+ type: "qrcode",
+ createDefault: (options) => ({
+ id: options?.id ?? "el-1",
+ type: "qrcode",
+ frame: options?.frame ?? { x: 0, y: 0, width: 20, height: 20 },
+ props: { value: "https://example.com" },
+ }),
+ },
+ ],
+})
+
+// 校验文档时传入插件类型集合，避免误报未知元素类型
+const result = deserialize(json, { pluginElementTypes: registry.elementTypes() })
+```
+
+`ElementPlugin.schema` 使用 `unknown` 是有意为之：Core 不绑定任何具体校验库，
+宿主可以传 JSON Schema、Zod、Valibot 或自定义描述，由插件适配器负责具体校验。
+
+## 目录结构
+
+```
+src/
+├── model/ 报表文档模型（report / page / section / element / table / style / …）
+├── plugin/ 插件契约与注册表
+├── document/ 创建、克隆、规范化
+├── serialization/ 序列化、反序列化、迁移
+├── schema/ 版本、默认值、校验
+├── command/ 命令、事务、撤销重做
+├── diagnostics/ 统一诊断对象
+├── utils/ ID 生成、深拷贝与对象工具
+└── index.ts 公共出口
+```
+
+## 开发
+
+```bash
+pnpm build # tsup 打包（ESM + CJS + d.ts）
+pnpm test # vitest
+pnpm typecheck # tsc --noEmit
+```
+
+## 当前测试覆盖
+
+| 测试文件 | 用例数 | 覆盖内容 |
+| --- | --- | --- |
+| `document.test.ts` | 19 | 创建、规范化、克隆、元素计数 |
+| `serialization.test.ts` | 26 | 稳定序列化、往返、迁移链路、容错读取 |
+| `validation.test.ts` | 34 | 结构校验、引用完整性、样式环、插件类型 |
+| `command.test.ts` | 35 | 命令、合并、事务、撤销重做 |
+| `plugin.test.ts` | 25 | 注册、冲突、版本兼容、缺失诊断 |
+
+合计 **139** 个用例。
+
+## V1 范围内尚未实现的部分
+
+本包只覆盖设计文档 §16 的**阶段 1**（Core 和文档模型）。以下属于后续阶段：
+
+- `report-expression`：表达式解析与受限求值器（阶段 3）。
+- `report-layout`：测量、换行、分页，产出 `LayoutDocument`（阶段 2）。
+- `report-renderer`：HTML / SVG / PDF（阶段 4）。
+- `report-designer` / `report-designer-vue`：编辑器与 UI（阶段 4）。
+- 插件实现：二维码、条码、图表（阶段 5）。
diff --git a/code/one-designer/packages/report-core/package.json b/code/one-designer/packages/report-core/package.json
new file mode 100644
index 00000000..8472761d
--- /dev/null
+++ b/code/one-designer/packages/report-core/package.json
@@ -0,0 +1,29 @@
+{
+ "name": "@report/core",
+ "version": "0.1.0",
+ "description": "报表文档模型、插件契约、校验、序列化与迁移",
+ "type": "module",
+ "main": "./dist/index.cjs",
+ "module": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js",
+ "require": "./dist/index.cjs"
+ }
+ },
+ "files": ["dist"],
+ "scripts": {
+ "build": "tsup",
+ "dev": "tsup --watch",
+ "test": "vitest run",
+ "test:watch": "vitest",
+ "typecheck": "tsc --noEmit"
+ },
+ "devDependencies": {
+ "tsup": "^8.3.5",
+ "typescript": "^5.7.2",
+ "vitest": "^2.1.8"
+ }
+}
diff --git a/code/one-designer/packages/report-core/src/command/command.ts b/code/one-designer/packages/report-core/src/command/command.ts
new file mode 100644
index 00000000..e618fc07
--- /dev/null
+++ b/code/one-designer/packages/report-core/src/command/command.ts
@@ -0,0 +1,159 @@
+/**
+ * 命令模型（对应设计文档 §4.5 与 §3.2）。
+ *
+ * 设计要点：
+ * - Designer 通过 Core 的命令接口修改文档，不直接实现报表业务规则。
+ * - 撤销栈属于编辑器状态，不进文档（§3.2）。因此 History 由调用方持有，
+ * Core 只提供命令契约与执行语义。
+ *
+ * 命令采用「整体替换文档」而非原地修改，原因是文档是纯数据、体量可控，
+ * 整体替换能天然保证不可变性和撤销快照的正确性，避免细粒度 patch 漏改。
+ */
+import type { ReportDocument } from "../model/report.js"
+import type { Diagnostic } from "../model/common.js"
+import { cloneDocument } from "../document/clone.js"
+
+/** 命令执行上下文。 */
+export interface CommandContext {
+ /** 当前文档（只读，命令不得直接修改）。 */
+ readonly document: ReportDocument
+}
+
+/** 命令执行结果。 */
+export interface CommandResult {
+ /** 成功时必须返回新的文档；失败时返回 null。 */
+ document: ReportDocument | null
+ diagnostics: Diagnostic[]
+}
+
+/** 命令契约。 */
+export interface Command
+
+
+
+
diff --git a/code/one-designer/packages/report-designer-vue/src/components/ReportCanvas.vue b/code/one-designer/packages/report-designer-vue/src/components/ReportCanvas.vue
new file mode 100644
index 00000000..ed35c081
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/components/ReportCanvas.vue
@@ -0,0 +1,317 @@
+
+
+
+
+
+
+
+
+
+
diff --git a/code/one-designer/packages/report-designer-vue/src/components/ReportProperties.vue b/code/one-designer/packages/report-designer-vue/src/components/ReportProperties.vue
new file mode 100644
index 00000000..3d131ad5
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/components/ReportProperties.vue
@@ -0,0 +1,135 @@
+
+
+
+
+
+
+
diff --git a/code/one-designer/packages/report-designer-vue/src/components/ReportRuler.vue b/code/one-designer/packages/report-designer-vue/src/components/ReportRuler.vue
new file mode 100644
index 00000000..8ce10e50
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/components/ReportRuler.vue
@@ -0,0 +1,141 @@
+
+
+
+
+
+
+
diff --git a/code/one-designer/packages/report-designer-vue/src/components/ReportStatusbar.vue b/code/one-designer/packages/report-designer-vue/src/components/ReportStatusbar.vue
new file mode 100644
index 00000000..79f77502
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/components/ReportStatusbar.vue
@@ -0,0 +1,42 @@
+
+
+
+
+
+
+
diff --git a/code/one-designer/packages/report-designer-vue/src/components/ReportToolbar.vue b/code/one-designer/packages/report-designer-vue/src/components/ReportToolbar.vue
new file mode 100644
index 00000000..34669d29
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/components/ReportToolbar.vue
@@ -0,0 +1,137 @@
+
+
+
+
+
+
+
diff --git a/code/one-designer/packages/report-designer-vue/src/components/ReportToolbox.vue b/code/one-designer/packages/report-designer-vue/src/components/ReportToolbox.vue
new file mode 100644
index 00000000..7301e110
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/components/ReportToolbox.vue
@@ -0,0 +1,71 @@
+
+
+
+
+
+
+
diff --git a/code/one-designer/packages/report-designer-vue/src/index.ts b/code/one-designer/packages/report-designer-vue/src/index.ts
new file mode 100644
index 00000000..7cd21b09
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/index.ts
@@ -0,0 +1,27 @@
+/**
+ * @report/designer-vue 公共入口（对应设计文档 §4.6、§14）。
+ *
+ * 只负责 Vue 组件、面板和样式实现，不向 Core 泄漏 Vue 类型。
+ * 组件采用 Headless 思路，宿主可覆写主题（通过 CSS 变量）。
+ */
+import ReportDesigner from "./ReportDesigner.vue"
+import ReportToolbar from "./components/ReportToolbar.vue"
+import ReportToolbox from "./components/ReportToolbox.vue"
+import ReportCanvas from "./components/ReportCanvas.vue"
+import ReportRuler from "./components/ReportRuler.vue"
+import ReportProperties from "./components/ReportProperties.vue"
+import ReportStatusbar from "./components/ReportStatusbar.vue"
+
+export {
+ ReportDesigner,
+ ReportToolbar,
+ ReportToolbox,
+ ReportCanvas,
+ ReportRuler,
+ ReportProperties,
+ ReportStatusbar,
+}
+
+export { themeCss, injectThemeStyle } from "./theme.js"
+export { useEditor } from "./use-editor.js"
+export { useShortcuts } from "./use-shortcuts.js"
diff --git a/code/one-designer/packages/report-designer-vue/src/ruler.ts b/code/one-designer/packages/report-designer-vue/src/ruler.ts
new file mode 100644
index 00000000..94f90c41
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/ruler.ts
@@ -0,0 +1,88 @@
+/**
+ * 标尺刻度计算（对应设计文档 §14.7 画布规范）。
+ *
+ * 抽成纯函数的原因：步长选择、标签密度这类逻辑很容易在缩放时出边界问题，
+ * 放在组件里只能靠渲染结果间接验证，单独拿出来可以直接断言。
+ *
+ * 坐标约定：刻度位置 `px` 是**距页面原点的显示像素**，已含缩放；
+ * `mm` 是距页面原点的毫米值（即文档坐标）。
+ */
+import { mmToPx } from "@report/layout"
+
+/** 主刻度候选步长（mm）。 */
+const TICK_CANDIDATES_MM = [1, 2, 5, 10, 20, 50] as const
+
+/** 标签候选步长（mm），需比主刻度更稀疏。 */
+const LABEL_CANDIDATES_MM = [1, 2, 5, 10, 20, 50, 100] as const
+
+/** 主刻度最小视觉间距（px），低于此值刻度会糊成一片。 */
+const MIN_TICK_SPACING_PX = 8
+
+/** 标签最小视觉间距（px），低于此值数字会重叠。 */
+const MIN_LABEL_SPACING_PX = 40
+
+/** 刻度数量上限，防止自定义纸张尺寸过大时生成海量 DOM。 */
+const MAX_TICKS = 1000
+
+/** 一根刻度。 */
+export interface RulerTick {
+ /** 距页面原点的毫米值。 */
+ mm: number
+ /** 距页面原点的显示像素（已含缩放）。 */
+ px: number
+ /** 需要显示的数字标签；次刻度为 undefined。 */
+ label?: string
+}
+
+/** 从候选步长里取第一个在给定缩放下间距达标的。 */
+function firstFitting(
+ candidates: readonly number[],
+ zoom: number,
+ minSpacingPx: number,
+ atLeastMm = 0,
+): number {
+ for (const candidate of candidates) {
+ if (candidate < atLeastMm) continue
+ if (mmToPx(candidate) * zoom >= minSpacingPx) return candidate
+ }
+ return candidates[candidates.length - 1]!
+}
+
+/** 按缩放选择主刻度步长（mm）。 */
+export function chooseRulerStepMm(zoom: number): number {
+ return firstFitting(TICK_CANDIDATES_MM, zoom, MIN_TICK_SPACING_PX)
+}
+
+/**
+ * 生成标尺刻度。
+ *
+ * @param lengthMm 标尺覆盖的长度（mm），通常是纸张宽/高。
+ * @param zoom 当前缩放比例。
+ */
+export function buildRulerTicks(lengthMm: number, zoom: number): RulerTick[] {
+ if (!(lengthMm > 0) || !(zoom > 0)) return []
+
+ const stepMm = chooseRulerStepMm(zoom)
+ // 标签步长与主刻度步长都取自同一套候选值，因此 labelEvery 一定是正整数。
+ const labelStepMm = firstFitting(
+ LABEL_CANDIDATES_MM,
+ zoom,
+ MIN_LABEL_SPACING_PX,
+ stepMm,
+ )
+ const labelEvery = Math.max(1, Math.round(labelStepMm / stepMm))
+
+ const ticks: RulerTick[] = []
+ // 加 1e-9 防止 210 / 5 这类整除因浮点误差少算一根。
+ const count = Math.min(MAX_TICKS - 1, Math.floor(lengthMm / stepMm + 1e-9))
+ for (let i = 0; i <= count; i += 1) {
+ const mm = i * stepMm
+ const px = mmToPx(mm) * zoom
+ if (i % labelEvery === 0) {
+ ticks.push({ mm, px, label: String(Math.round(mm)) })
+ } else {
+ ticks.push({ mm, px })
+ }
+ }
+ return ticks
+}
diff --git a/code/one-designer/packages/report-designer-vue/src/theme.ts b/code/one-designer/packages/report-designer-vue/src/theme.ts
new file mode 100644
index 00000000..bc06c6f9
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/theme.ts
@@ -0,0 +1,68 @@
+/**
+ * 设计令牌（对应设计文档 §14.4）。
+ *
+ * 使用 CSS 自定义属性作为主题契约，提供亮色与暗色两套主题。
+ * 宿主应用可通过覆写这些变量来定制品牌色，但必须保持语义：
+ * background / canvas / foreground / muted / border / primary /
+ * destructive / selection。
+ *
+ * 颜色使用 HSL 空间（h s% l% 三元组），便于组件里用 hsl(var(--x)) 拼装。
+ */
+export const themeCss = /* css */ `
+:root {
+ --rd-background: 0 0% 100%;
+ --rd-foreground: 222 47% 11%;
+ --rd-muted: 210 40% 96%;
+ --rd-muted-foreground: 215 16% 47%;
+ --rd-border: 214 32% 91%;
+ --rd-input: 214 32% 91%;
+ --rd-primary: 221 83% 53%;
+ --rd-primary-foreground: 210 40% 98%;
+ --rd-destructive: 0 72% 51%;
+ --rd-canvas: 220 14% 96%;
+ --rd-selection: 221 83% 53%;
+ --rd-radius: 8px;
+
+ /* 纸张与墨色：属于文档表面，不随亮/暗主题切换（§14.7）。 */
+ --rd-paper: 0 0% 100%;
+ --rd-ink: 222 47% 11%;
+}
+
+.dark {
+ --rd-background: 222 47% 11%;
+ --rd-foreground: 210 40% 98%;
+ --rd-muted: 217 33% 17%;
+ --rd-muted-foreground: 215 20% 65%;
+ --rd-border: 217 33% 17%;
+ --rd-input: 217 33% 17%;
+ --rd-primary: 217 91% 60%;
+ --rd-primary-foreground: 222 47% 11%;
+ --rd-destructive: 0 63% 31%;
+ --rd-canvas: 222 47% 8%;
+ --rd-selection: 217 91% 60%;
+}
+
+.rd-designer {
+ color: hsl(var(--rd-foreground));
+ background: hsl(var(--rd-background));
+ font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI",
+ "PingFang SC", "Microsoft YaHei", sans-serif;
+ font-size: 13px;
+ line-height: 1.4;
+}
+
+.rd-designer * {
+ box-sizing: border-box;
+}
+`
+
+/** 注入主题样式到文档 head（幂等）。 */
+export function injectThemeStyle(): void {
+ if (typeof document === "undefined") return
+ const id = "rd-designer-theme"
+ if (document.getElementById(id)) return
+ const style = document.createElement("style")
+ style.id = id
+ style.textContent = themeCss
+ document.head.appendChild(style)
+}
diff --git a/code/one-designer/packages/report-designer-vue/src/use-editor.ts b/code/one-designer/packages/report-designer-vue/src/use-editor.ts
new file mode 100644
index 00000000..55c8d92e
--- /dev/null
+++ b/code/one-designer/packages/report-designer-vue/src/use-editor.ts
@@ -0,0 +1,185 @@
+/**
+ * 编辑器响应式绑定（composable）。
+ *
+ * 把 designer 包的 EditorSession（非响应式类）包装成 Vue 响应式状态，
+ * 供组件消费。文档与状态变化时触发重渲染。
+ *
+ * 这里只暴露组件真正用到的能力。designer 包里还有 pan / hoveredId 等
+ * 状态，但当前画布用滚动容器承载平移、也没有 hover 高亮，故暂不暴露，
+ * 避免出现「有 API 没人用」的死代码。
+ */
+import { reactive, readonly, computed } from "vue"
+import type { ReportDocument, ReportElement, Rect } from "@report/core"
+import type { EditorSession } from "@report/designer"
+
+/** 把 EditorSession 包装成响应式视图。 */
+export function useEditor(editor: EditorSession) {
+ // 用一个自增版本号驱动重渲染：EditorSession 内部是不可变替换，
+ // 没有 Vue 的响应式钩子，这里在每次操作后手动 bump。
+ const state = reactive({
+ version: 0,
+ document: editor.getDocument() as ReportDocument,
+ selectedIds: [] as string[],
+ zoom: editor.getState().zoom,
+ /** 是否正在拖拽（用于切换光标）。 */
+ dragging: false,
+ })
+
+ /** 同步编辑器最新状态到响应式视图。 */
+ function sync(): void {
+ state.version += 1
+ state.document = editor.getDocument()
+ state.selectedIds = editor.getSelectedIds()
+ state.zoom = editor.getState().zoom
+ state.dragging = editor.isDragging()
+ }
+
+ // -------------------------------------------------------------------------
+ // 选择
+ // -------------------------------------------------------------------------
+
+ /** 选中单个元素。 */
+ function select(id: string): void {
+ editor.select(id)
+ sync()
+ }
+
+ /** 多选。 */
+ function selectMany(ids: string[]): void {
+ editor.selectMany(ids)
+ sync()
+ }
+
+ /** 切换单个元素的选中态（Ctrl/Cmd + 点击）。 */
+ function toggleSelect(id: string): void {
+ editor.toggleSelect(id)
+ sync()
+ }
+
+ /** 清空选中。 */
+ function clearSelection(): void {
+ editor.clearSelection()
+ sync()
+ }
+
+ // -------------------------------------------------------------------------
+ // 编辑操作
+ // -------------------------------------------------------------------------
+
+ /** 移动元素（frame 为文档绝对坐标 mm）。 */
+ function move(frames: Recordmm
+
+ ") + return ( + `
` +
+ `${text}
`
+ )
+ }
+ case "rect": {
+ const css = styleToCss(node.style)
+ return ``
+ }
+ case "line": {
+ const content = node.content
+ if (content?.kind !== "line") return ""
+ const color = node.style.color ?? "#000000"
+ const thickness = toUnit(content.thickness, options)
+ const isVertical = content.direction === "vertical"
+ const lineCss =
+ isVertical
+ ? `border-left:${thickness}${unit} solid ${color}`
+ : `border-top:${thickness}${unit} solid ${color}`
+ return ``
+ }
+ case "image": {
+ const content = node.content
+ if (content?.kind !== "image") return ""
+ if (!content.src) {
+ diagnostics.push({
+ severity: "warning",
+ code: "render.image-missing",
+ message: `图片元素 "${node.id}" 缺少 src`,
+ elementId: node.id,
+ })
+ return ""
+ }
+ const fit = content.fit === "fill" ? "100% 100%" : content.fit
+ return (
+ `` +
+ `})
` +
+ `
`
+ )
+ }
+ case "table": {
+ const content = node.content
+ if (content?.kind !== "table") return ""
+ return renderHtmlTable(node, content, options)
+ }
+ default: {
+ diagnostics.push({
+ severity: "warning",
+ code: "render.unknown-node",
+ message: `不支持的节点类型 "${node.type}"，已跳过`,
+ elementId: node.id,
+ })
+ return ""
+ }
+ }
+}
+
+/** 渲染表格节点为 HTML 表格。 */
+function renderHtmlTable(
+ node: LayoutNode,
+ content: TableContent,
+ options: RenderOptions,
+): string {
+ const x = toUnit(node.frame.x, options)
+ const y = toUnit(node.frame.y, options)
+ const width = toUnit(node.frame.width, options)
+ const height = toUnit(node.frame.height, options)
+ const unit = unitSuffix(options)
+ const id = escapeAttr(node.id)
+
+ const colgroup = content.columns
+ .map((col) => `` +
+ `` +
+ `
`
+ )
+}
+
+function escapeHtml(text: string): string {
+ return text
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+}
+
+function escapeAttr(value: string): string {
+ return value
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+ .replace(/"/g, """)
+}
diff --git a/code/one-designer/packages/report-renderer/src/index.ts b/code/one-designer/packages/report-renderer/src/index.ts
new file mode 100644
index 00000000..d411cef5
--- /dev/null
+++ b/code/one-designer/packages/report-renderer/src/index.ts
@@ -0,0 +1,29 @@
+/**
+ * @report/renderer 公共入口（对应设计文档 §4.4、§3.3）。
+ *
+ * Renderer 只消费 LayoutDocument，把分页结果绘制成 HTML / SVG / PDF。
+ * 所有 Renderer 共享同一份布局结果，保证分页结构一致（§15）。
+ */
+export type {
+ RenderTarget,
+ RenderResult,
+ TextRenderResult,
+ BinaryRenderResult,
+ RenderOptions,
+ Renderer,
+} from "./types.js"
+
+// 样式与坐标共享工具
+export { styleToCss, styleToSvgTextAttrs, toUnit, unitSuffix } from "./style.js"
+
+// SVG Renderer
+export type { SvgRenderer } from "./svg.js"
+export { createSvgRenderer, renderSvg } from "./svg.js"
+
+// HTML Renderer
+export type { HtmlRenderer } from "./html.js"
+export { createHtmlRenderer, renderHtml } from "./html.js"
+
+// PDF Renderer 契约
+export type { PdfBackend, PdfRenderer } from "./pdf.js"
+export { createPdfRenderer } from "./pdf.js"
diff --git a/code/one-designer/packages/report-renderer/src/pdf.ts b/code/one-designer/packages/report-renderer/src/pdf.ts
new file mode 100644
index 00000000..577f74e6
--- /dev/null
+++ b/code/one-designer/packages/report-renderer/src/pdf.ts
@@ -0,0 +1,78 @@
+/**
+ * PDF Renderer 契约（对应设计文档 §4.4、§3.3）。
+ *
+ * PDF 的具体后端可运行在浏览器或 Node/服务端，但都遵循统一的
+ * Renderer 接口。本包只提供契约与一个"占位"实现，真实 PDF 生成
+ * 由阶段 5 结合部署环境确定后端（§16）。
+ *
+ * 设计要点：
+ * - PDF 是二进制输出，结果携带 Uint8Array。
+ * - 后端缺失或未配置时返回诊断而非抛异常（§13）。
+ */
+import type { Diagnostic } from "@report/core"
+import type { LayoutDocument } from "@report/layout"
+import type { BinaryRenderResult, RenderOptions } from "./types.js"
+
+/**
+ * PDF 后端契约。
+ *
+ * 宿主实现此接口，把 LayoutDocument 转成 PDF 字节。
+ * 典型后端：浏览器端 pdf-lib / jsPDF，Node 端 Puppeteer / pdfkit。
+ */
+export interface PdfBackend {
+ /** 后端名称，用于诊断与日志。 */
+ readonly name: string
+ /** 把布局文档渲染为 PDF 字节。 */
+ render(document: LayoutDocument, options?: RenderOptions): Uint8Array
+}
+
+/** PDF 渲染器。 */
+export interface PdfRenderer {
+ render(document: LayoutDocument, options?: RenderOptions): BinaryRenderResult
+}
+
+/** 创建 PDF 渲染器。 */
+export function createPdfRenderer(backend?: PdfBackend): PdfRenderer {
+ return {
+ render(document, options = {}) {
+ const diagnostics: Diagnostic[] = []
+ if (!backend) {
+ diagnostics.push({
+ severity: "warning",
+ code: "render.pdf-backend-missing",
+ message:
+ "未配置 PDF 后端；请注入 PdfBackend（如 pdf-lib / jsPDF / Puppeteer）。" +
+ "当前返回空字节。",
+ })
+ return {
+ target: "pdf",
+ pageCount: document.pageCount,
+ diagnostics,
+ bytes: new Uint8Array(0),
+ }
+ }
+
+ try {
+ const bytes = backend.render(document, options)
+ return {
+ target: "pdf",
+ pageCount: document.pageCount,
+ diagnostics,
+ bytes,
+ }
+ } catch (error) {
+ diagnostics.push({
+ severity: "error",
+ code: "render.pdf-backend-error",
+ message: `PDF 后端 "${backend.name}" 渲染失败：${(error as Error)?.message ?? String(error)}`,
+ })
+ return {
+ target: "pdf",
+ pageCount: document.pageCount,
+ diagnostics,
+ bytes: new Uint8Array(0),
+ }
+ }
+ },
+ }
+}
diff --git a/code/one-designer/packages/report-renderer/src/style.ts b/code/one-designer/packages/report-renderer/src/style.ts
new file mode 100644
index 00000000..164544f0
--- /dev/null
+++ b/code/one-designer/packages/report-renderer/src/style.ts
@@ -0,0 +1,61 @@
+/**
+ * 样式与坐标转换的共享工具（HTML / SVG 共用）。
+ *
+ * 布局结果内部统一使用 mm；SVG/HTML 输出按需换算为 px。
+ * 样式统一转成 CSS 声明，保证各 Renderer 视觉一致（§15）。
+ */
+import type { ResolvedStyle } from "@report/core"
+import { mmToPx } from "@report/layout"
+import type { RenderOptions } from "./types.js"
+
+/** 把 mm 值按目标单位换算为数值（SVG/HTML 里直接写数字）。 */
+export function toUnit(value: number, options: RenderOptions): number {
+ return options.unit === "px" ? mmToPx(value) : value
+}
+
+/** 单位后缀。 */
+export function unitSuffix(options: RenderOptions): string {
+ return options.unit === "px" ? "px" : "mm"
+}
+
+/**
+ * 把已解析样式转成 CSS 声明字符串。
+ *
+ * 字号在文档中是 pt，HTML/SVG 里也以 pt 表达，保证与布局测量一致。
+ * 边框只输出四边统一值；逐边覆盖的边框由 Renderer 按需处理。
+ */
+export function styleToCss(style: ResolvedStyle): string {
+ const parts: string[] = []
+ parts.push(`font-family:${style.fontFamily}`)
+ parts.push(`font-size:${style.fontSize}pt`)
+ parts.push(`font-weight:${style.fontWeight}`)
+ parts.push(`font-style:${style.fontStyle}`)
+ parts.push(`line-height:${style.lineHeight}`)
+ parts.push(`color:${style.color}`)
+ if (style.background && style.background !== "transparent") {
+ parts.push(`background:${style.background}`)
+ }
+ parts.push(`text-align:${style.align}`)
+ parts.push(`text-decoration:${style.textDecoration}`)
+ if (style.border) {
+ const width = style.border.width ?? 0.1
+ const color = style.border.color ?? "#000000"
+ const lineStyle = style.border.style ?? "solid"
+ parts.push(`border:${width}mm ${lineStyle} ${color}`)
+ }
+ return parts.join(";")
+}
+
+/** 把已解析样式转成 SVG 文本属性（fill / font-size 等）。 */
+export function styleToSvgTextAttrs(style: ResolvedStyle): Record