printbench 0.8.6 → 0.8.7

package/README.md

@@ -101,7 +101,7 @@ function onExported(payload: PrintBenchExportedPayload) {
 | `gridSizeMm`      | `{ x, y, z }`                                         | —         | 宿主默认固定网格尺寸（mm，边长取床面两轴 max，20 格）。挂载时写入一次；若未同时传 `gridAutoFit`，会自动设为固定尺寸（`gridAutoFit: false`） |
 | `diagnosisZIndex` | `number`                                              | `100`     | 诊断浮层 `z-index`。也可在外层设 CSS 变量 `--printbench-diagnosis-z`                                         |
 | `annotations`     | `Annotation[]` \| `AnnotationDocument` \| `string`     | —         | 模型批注（世界坐标 mm）。需同时打开 `features.annotations` 才能编辑；详见下方「批注」           |
-| `features`        | `{ numeric?, primitives?, split?, autoSplit?, drafts?, extras?, restore?, layout?, importUnit?, hideEmpty?, hideTour?, hideStatusBar?, hidePanelModeToggle?, hidePreviewLighting?, annotations?, … }` | 能力项默认 `false` | 进阶能力。缺省精简：左栏仅导入 / 零件 / 导出 / 快照。未开 `drafts` 时不读不写自动草稿。导入单位优先用文件声明，否则按包围盒尺寸推测 mm/cm/m 再换算到内部毫米；开 `importUnit` 时可再确认。`split` 为切面拆件；`autoSplit` 为「自动拆件」按钮（默认隐藏，需显式打开）。`restore` 为「复原到导入状态」按钮（默认隐藏，宿主需显式打开；完整工作台预设已开启）。`layout` 打开贴地 / 镜像 / 目标尺寸缩放 / 选面朝下与打印床体积。`annotations` 打开模型批注（默认关闭，`PRINTBENCH_FULL_FEATURES` 也不含该项）。`hideEmpty` / `hideTour` / `hideStatusBar` / `hidePanelModeToggle` / `hidePreviewLighting` 为 `true` 时分别隐藏空画布提示、首次引导 Tour（可与 `extras` 同开）、底栏状态条、零件栏悬浮/通栏切换按钮、预览模式左上角灯光模式控件（默认显示）。 |
+| `features`        | `{ numeric?, primitives?, split?, autoSplit?, drafts?, extras?, restore?, layout?, importUnit?, hideEmpty?, hideTour?, hideStatusBar?, hidePanelModeToggle?, hidePreviewLighting?, annotations?, annotationPanel?, … }` | 能力项默认 `false` | 进阶能力。缺省精简：左栏仅导入 / 零件 / 导出 / 快照。未开 `drafts` 时不读不写自动草稿。导入单位优先用文件声明，否则按包围盒尺寸推测 mm/cm/m 再换算到内部毫米；开 `importUnit` 时可再确认。`split` 为切面拆件；`autoSplit` 为「自动拆件」按钮（默认隐藏，需显式打开）。`restore` 为「复原到导入状态」按钮（默认隐藏，宿主需显式打开；完整工作台预设已开启）。`layout` 打开贴地 / 镜像 / 目标尺寸缩放 / 选面朝下与打印床体积。`annotations` 打开批注能力（画布标记、放置、prop/事件与 ref API；默认关闭，`PRINTBENCH_FULL_FEATURES` 也不含）。`annotationPanel` 控制右栏自带批注 Tab（依赖 `annotations`；省略时随 `annotations` 开启，设 `false` 可自建宿主 UI）。`hideEmpty` / `hideTour` / `hideStatusBar` / `hidePanelModeToggle` / `hidePreviewLighting` 为 `true` 时分别隐藏空画布提示、首次引导 Tour（可与 `extras` 同开）、底栏状态条、零件栏悬浮/通栏切换按钮、预览模式左上角灯光模式控件（默认显示）。 |
 
 
 嵌入预览示例（宿主列表 + 色板 + 自定义导出 + 按轴/最长边缩放）：
@@ -198,6 +198,10 @@ async function upload() {
 | `select-part`        | `{ id, index, additive }`                         | 画布或零件树点选                                           |
 | `part-colors-change` | `Record<string, string>`                          | 工作台内改色时抛出（嵌入预览以 `partColors` 为准）                   |
 | `annotations-change` | `{ schema, version, unit, coordinateSpace, fileName?, generatedAt, annotations, reason }` | 批注新增 / 修改 / 删除时抛出（`reason`: `add` \| `update` \| `remove`）。仅在 `features.annotations` 开启时触发 |
+| `annotation-select`  | `string \| null`                                      | 当前选中批注变化（列表、画布标记或 ref API）；关闭批注能力时不触发 |
+| `annotation-mode-change` | `'off' \| 'place'`                                 | 放置模式进出（含 Esc 取消与放置成功）；仅在 `features.annotations` 开启时触发 |
+| `annotation-click`   | `string`                                              | 点击画布标注点（随后仍会选中并飞到锚点） |
+| `annotation-hover`   | `string \| null`                                      | 鼠标经过画布标注点；离开全部标记时为 `null` |
 
 
 `exported` 的 `format` 为 `'stl' | '3mf' | 'glb'`；多零件 STL 时 `fileName` 为 zip，`blob` 为打包后的文件。GLB 为单文件，零件色写入材质。
@@ -218,24 +222,170 @@ async function upload() {
 | `exportAnnotations()` | 上面文档的格式化 JSON 字符串。 |
 | `setAnnotations(input)` | 用数组 / 文档 / JSON 字符串替换批注列表。 |
 | `addAnnotation(input)` | 以编程方式添加一条批注，返回新 `Annotation`；功能未开启时返回 `null`。 |
+| `setAnnotationMode(mode)` | `'off'` \| `'place'`：进入 / 退出画布放置模式（下一次点模型表面会钉一条批注）。 |
+| `getAnnotationMode()` | 当前放置模式。 |
+| `selectAnnotation(id)` | 选中批注，或传 `null` 清空；不飞相机。 |
+| `getSelectedAnnotationId()` | 当前选中批注 id。 |
+| `updateAnnotation(id, patch)` | 更新标题 / 说明 / 级别 / 状态等；未开启或找不到时返回 `null`。 |
+| `removeAnnotation(id)` | 删除批注。 |
+| `flyToAnnotation(id)` | 选中并飞到该批注锚点。 |
 
 ### 批注（默认关闭）
 
-批注是**独立旁路数据**：只做锚点渲染与 JSON 序列化，不进入网格、不进入 STL / 3MF / GLB 导出，也不影响诊断结果。默认隐藏，需显式开启：
+批注是**独立旁路数据**：只做锚点渲染与 JSON 序列化，不进入网格、不进入 STL / 3MF / GLB 导出，也不影响诊断结果。默认隐藏，需显式开启。
+
+能力与自带 UI 分开配置：
+
+| 开关 | 作用 |
+| ---- | ---- |
+| `features.annotations` | 画布标记、放置模式、`annotations` prop / 事件、ref API |
+| `features.annotationPanel` | 右栏「检查」里的自带批注 Tab（依赖上一行）。**省略时随 `annotations` 开启**；设 `false` 可只用宿主自定义 UI |
+
+#### 示例 1：自带面板（默认行为）
+
+开启批注能力后，右栏出现「检查」页签（诊断 / 批注）。省略 `annotationPanel` 时默认同开。
 
 ```vue
-<PrintBench
-  :features="{ annotations: true }"
-  :annotations="notes"
-  @annotations-change="notes = $event"
-/>
+<script setup lang="ts">
+import { ref } from 'vue'
+import { PrintBench } from 'printbench'
+import type { PrintBenchAnnotationsPayload } from 'printbench'
+
+/** 受控回写：原样赋回不会回环 */
+const notes = ref<PrintBenchAnnotationsPayload | undefined>()
+</script>
+
+<template>
+  <PrintBench
+    :features="{ annotations: true }"
+    :annotations="notes"
+    @annotations-change="notes = $event"
+  />
+</template>
 ```
 
-开启后右栏出现「检查」页签（诊断 / 批注），可点「放置批注」后在模型表面点上标注，支持级别、标题、说明与已解决标记。
+用户可在面板内点「放置批注」→ 点模型表面标注；支持级别、标题、说明与已解决标记。也可随时用 `ref` 读写：
 
-锚点使用**内部毫米世界坐标**（与当前 `upAxis` 一致，默认 Z 轴向上）加 `partId`、命中面法线；零件被移动 / 旋转 / 镜像后仍可按 `partId` 重新挂接，`partId` 消失（拆件 / 布尔 / 合并）时标记为 `orphaned` 并保留原位置显示。
+```ts
+import type { PrintBenchExpose } from 'printbench'
+
+const bench = ref<PrintBenchExpose | null>(null) // 绑到 <PrintBench ref="bench" />
+
+bench.value?.exportAnnotations() // JSON 字符串
+bench.value?.setAnnotations(savedDoc) // 整表替换（数组 / 文档 / JSON 字符串均可）
+bench.value?.addAnnotation({
+  position: [12.5, 8, -3.25],
+  normal: [0, 0, 1],
+  partId: 'mesh_xxx',
+  title: '壁厚不足',
+  body: '建议加厚至 1.2mm',
+  severity: 'yellow',
+})
+```
 
-JSON 结构：
+#### 示例 2：自定义宿主 UI
+
+关掉自带 Tab，保留画布标记与 API，由宿主渲染列表 / 编辑器。
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { PrintBench } from 'printbench'
+import type {
+  PrintBenchAnnotationMode,
+  PrintBenchAnnotationsPayload,
+  PrintBenchExpose,
+} from 'printbench'
+
+const bench = ref<PrintBenchExpose | null>(null)
+const notes = ref<PrintBenchAnnotationsPayload | undefined>()
+const selectedId = ref<string | null>(null)
+const hoveredId = ref<string | null>(null)
+const mode = ref<PrintBenchAnnotationMode>('off')
+
+const list = computed(() => notes.value?.annotations ?? [])
+const selected = computed(() => list.value.find((a) => a.id === selectedId.value) ?? null)
+const placing = computed(() => mode.value === 'place')
+
+function togglePlace() {
+  bench.value?.setAnnotationMode(placing.value ? 'off' : 'place')
+}
+
+function openNote(id: string) {
+  bench.value?.flyToAnnotation(id) // 选中并飞到锚点
+}
+
+function saveTitle(title: string) {
+  if (!selectedId.value) return
+  bench.value?.updateAnnotation(selectedId.value, { title })
+}
+
+function markResolved() {
+  if (!selectedId.value || !selected.value) return
+  const next = selected.value.status === 'resolved' ? 'open' : 'resolved'
+  bench.value?.updateAnnotation(selectedId.value, { status: next })
+}
+
+function removeSelected() {
+  if (!selectedId.value) return
+  bench.value?.removeAnnotation(selectedId.value)
+}
+</script>
+
+<template>
+  <div class="host-review">
+    <PrintBench
+      ref="bench"
+      :features="{ annotations: true, annotationPanel: false }"
+      :annotations="notes"
+      @annotations-change="notes = $event"
+      @annotation-select="selectedId = $event"
+      @annotation-mode-change="mode = $event"
+      @annotation-click="openNote"
+      @annotation-hover="hoveredId = $event"
+    />
+
+    <aside>
+      <button type="button" @click="togglePlace">
+        {{ placing ? '点击模型放置…（Esc 取消）' : '放置批注' }}
+      </button>
+      <p v-if="hoveredId">悬停：{{ hoveredId }}</p>
+
+      <button
+        v-for="a in list"
+        :key="a.id"
+        type="button"
+        :class="{ active: a.id === selectedId }"
+        @click="openNote(a.id)"
+      >
+        {{ a.title }}
+        <span v-if="a.status === 'resolved'">已解决</span>
+        <span v-if="a.orphaned">零件已失效</span>
+      </button>
+
+      <div v-if="selected">
+        <input
+          :value="selected.title"
+          @change="saveTitle(($event.target as HTMLInputElement).value)"
+        />
+        <button type="button" @click="markResolved">
+          {{ selected.status === 'resolved' ? '重新打开' : '标记已解决' }}
+        </button>
+        <button type="button" @click="removeSelected">删除</button>
+      </div>
+    </aside>
+  </div>
+</template>
+```
+
+要点：
+- `@annotation-mode-change` 同步放置态（含 Esc 取消、放置成功后回到 `off`）
+- `@annotation-click` / `@annotation-hover` 响应画布标记手势；`@annotation-select` 覆盖列表与 API 选中
+- `annotationPanel: false` 时放置成功**不会**弹出右栏诊断浮层
+
+#### 数据格式
+
+锚点使用**内部毫米世界坐标**（与当前 `upAxis` 一致，默认 Z 轴向上）加 `partId`、命中面法线；零件被移动 / 旋转 / 镜像后仍可按 `partId` 重新挂接，`partId` 消失（拆件 / 布尔 / 合并）时标记为 `orphaned` 并保留原位置显示。
 
 ```json
 {
@@ -290,7 +440,7 @@ JSON 结构：
 | --- | ------------------------------------------------------ |
 | 左栏  | 导入、导出、快照、零件树、上色、移动/旋转/缩放；`features` 打开后才有数值变换、布局（贴地/镜像/缩放/选面朝下）、基本体、拆件、草稿与观察工具 |
 | 画布  | 轨道旋转缩放；双击或 **F** 自适应；**复位视角** 回默认相机；开启 `layout` 后可在布局区/设置中显示打印床线框（默认隐藏） |
-| 右栏  | 诊断与测量浮层（右上，默认 `z-index: 100`），默认收起；开启 `features.annotations` 后标题变为「检查」，多出「批注」页签 |
+| 右栏  | 诊断与测量浮层（右上，默认 `z-index: 100`），默认收起；开启 `features.annotationPanel`（默认随 `annotations`）后标题变为「检查」，多出「批注」页签 |
 | 底栏  | 包围盒、内部单位 mm、体积、文件名；超床时提示超出轴                                     |
 
 

package/dist/chunks/{3mf-BrPsk9Z0.js → 3mf-CH9wGJ51.js}

@@ -1,5 +1,5 @@
 import j from "jszip";
-import { h as w, r as R } from "./index-DV7N04zK.js";
+import { h as w, r as R } from "./index-BHL8_oaU.js";
 function p(s, l) {
   return s.match(new RegExp(`\\b${l}\\s*=\\s*"([^"]*)"`, "i"))?.[1];
 }

package/dist/chunks/{glb-BUUnX9vf.js → glb-XZ3fyf6P.js}

@@ -1,6 +1,6 @@
 import { Group as w, Mesh as l, MeshStandardMaterial as u, DoubleSide as h, Color as c } from "three";
 import { GLTFExporter as p } from "three/examples/jsm/exporters/GLTFExporter.js";
-import { b as d } from "./index-DV7N04zK.js";
+import { b as d } from "./index-BHL8_oaU.js";
 async function G(r, e, n) {
   const t = new w();
   t.name = "PrintBench", r.forEach((f, o) => {