@faicad/faijs 0.22.2 → 0.29.3

package/dist/brep/mesh-solid.d.ts

@@ -0,0 +1,218 @@
+/**
+ * mesh-solid — 网格实体（mesh solid）与其网格后端端口
+ *
+ *
+ * 名词边界（方案 §3.1）：
+ * - **网格实体** = 由网格文件导入、经「规范化」得到的引擎实体。它是**近似拓扑**
+ *   的载体，不是精度链的一环；永不进 `brepChain.solidCache`。
+ * - **规范化** = `importIndexedMesh` → `weldShellsAndFaces(tol)` → `unifyFaces()`。
+ *   **顺序不可交换**：先 `unifyFaces` 会把实体做坏（体积归零），防回归用例见
+ *   `brepkit-kernel/mesh-solid-topology.test.ts`。
+ * - **网格后端** = 提供网格实体能力的引擎侧组件（本期即 brepkit 的网格用法）。
+ *   与 BREP 引擎**同名不同用**：可能同一个 wasm 实例，但走 mesh 语义路径。
+ *
+ * 本模块只依赖 L1（`engine/types`、`engine/primitives`）与拓扑构建器；后端实现
+ * 放在适配器侧（`brep/engine/adapters/brepkit`），因此本模块自身不含任何内核私有
+ * 调用——`MeshSolidKernelOps` 是内核私有原语的端口（L1 契约不含 weld/unify）。
+ */
+import type { BrepHandle, BrepMeshResult } from './engine/types.js';
+import type { BrepEngineApi } from './engine/primitives.js';
+import type { PartName } from '../identity.js';
+import type { SelectorRuntimeData } from '../topology/build-selector-runtime.js';
+/** 网格实体构建的输入网格（已按基准单位折算的坐标，与 `Shape` 同构）。 */
+export interface MeshSolidInput {
+    positions: Float32Array;
+    indices: Uint32Array;
+}
+/** 规范化选项。 */
+export interface MeshSolidNormalizeOptions {
+    /**
+     * 焊接容差（顶点/重复边缝合半径）。缺省由包围盒对角线定标
+     * （`max(1e-6, 对角线 × 1e-6)`）——**不得写死绝对值**：STL 无单位元数据，
+     * 同一文件既可能是 mm 也可能是 inch，绝对容差在两种尺度下必有一边失准。
+     */
+    weldTolerance?: number;
+    /** 三角化参数（缺省与显示 mesh 一致：0.1 / 2π/32）。 */
+    linearDeflection?: number;
+    angularDeflection?: number;
+}
+/** 规范化结果：实体句柄 + 其三角化（显示 mesh 与拓扑 mesh 的唯一真源）。 */
+export interface MeshSolidResult {
+    /** 规范化后的网格实体句柄。 */
+    readonly solid: BrepHandle;
+    /**
+     * 同一实体的三角化（含 faceGroups）。**显示 mesh 必须用这一份**——规则 1：
+     * 拓扑 faceRuns 所索引的三角形，必须就是用户看到的三角形。若显示仍用原始
+     * STL 顶点数组、拓扑用实体的重新三角化，两者三角形数/序不一致 → faceRuns 错位。
+     */
+    readonly mesh: BrepMeshResult;
+    readonly faceCount: number;
+    readonly edgeCount: number;
+    readonly vertexCount: number;
+    /** 实际使用的焊接容差（诊断/复现用）。 */
+    readonly weldTolerance: number;
+    /** `unifyFaces` 合并掉的重复面数（0 = 共面面片未被合并，顶点未焊上）。 */
+    readonly mergedFaceCount: number;
+}
+/**
+ * 网格后端的**内核私有原语**（L1 `BrepEngineApi` 不含 weld/unify）。
+ *
+ * 由适配器（拥用内核闭包的一侧）实现；句柄一律是 faijs `BrepHandle`
+ * （适配器内部负责 `asNum()` 剥离标签），本模块不感知内核方言。
+ */
+export interface MeshSolidKernelOps {
+    /** 原始三角网格 → 逐三角形面的实体（内核自带顶点焊接）。 */
+    importMesh(positions: Float32Array, indices: Uint32Array): BrepHandle;
+    /** 面列表 → 缝合后的实体（重复边缝成共享边 → 真流形）。 */
+    weld(faces: BrepHandle[], tolerance: number): BrepHandle;
+    /** 共面区域合并（**原地修改**，返回合并掉的面数）。 */
+    unify(solid: BrepHandle): number;
+}
+/**
+ * 网格后端端口：`load` 的 mesh 路径经它产出网格实体与近似拓扑。
+ *
+ * 生命周期：由宿主装配期注册进 mesh 引擎槽（`registerMeshEngine`），运行期只读。
+ */
+export interface MeshSolidBackend {
+    /** 后端 id（与 `defineOp.meshEngines` 的门禁名同源，如 `'brepkit'`）。 */
+    readonly id: string;
+    /** L1 契约面（拓扑查询 + 几何操作；brepkit 适配器已全实现）。 */
+    readonly kernel: BrepEngineApi;
+    /** 内核私有原语（weld/unify）。 */
+    readonly ops: MeshSolidKernelOps;
+    /**
+     * 规范化 + 三角化。**失败必须抛错**（带 part 名由调用方补），不静默降级。
+     * @param mesh - the source triangle mesh (base-unit coordinates).
+     * @param opts - optional weld tolerance / tessellation overrides.
+     * @returns the mesh solid with its tessellation.
+     */
+    normalize(mesh: MeshSolidInput, opts?: MeshSolidNormalizeOptions): MeshSolidResult;
+    /**
+     * 已存在的网格实体 → 结果描述（三角化 + 计数）。Phase 2 的 mesh op 用它把
+     * 「内核操作产出的新实体」包成下一份网格零件（显示 mesh 与拓扑 mesh 同源）。
+     * @param solid - an existing mesh solid handle.
+     * @param opts - optional tessellation overrides.
+     * @returns the mesh solid result carrying the shared tessellation.
+     */
+    describe(solid: BrepHandle, opts?: MeshSolidNormalizeOptions): MeshSolidResult;
+    /**
+     * 从网格实体结果构建近似拓扑数据（`SelectorRuntimeData`，可直接交 `setTopology`）。
+     * @param result - the mesh solid result (its tessellation indexes the topology).
+     * @returns the serializable selector runtime data.
+     */
+    buildTopologyData(result: MeshSolidResult): SelectorRuntimeData;
+    /** 释放网格实体句柄。 */
+    release(solid: BrepHandle): void;
+}
+/**
+ * 由包围盒对角线导出焊接容差（方案 §3.3）。
+ *
+ * 下限 1e-6 兜住退化 bbox（单点/零厚网格）；上不封顶——超大模型需要更粗的
+ * 缝合半径才缝得上（float32 坐标的相对误差随尺度线性增长）。
+ *
+ * @param kernel - the L1 kernel API (bbox query only).
+ * @param shape - the raw imported shape.
+ * @returns the weld tolerance derived from the bounding-box diagonal.
+ */
+export declare function weldToleranceFor(kernel: BrepEngineApi, shape: BrepHandle): number;
+/**
+ * 规范化：`importMesh` → `weld` → `unify`，再校验并三角化。
+ *
+ * 三条硬约束，都是 Phase 0 实测结论：
+ * 1. **顺序不可交换**——先 unify 再 weld 会得到体积归零的坏实体；
+ * 2. `unify` **原地修改**，返回值是合并面数，不是句柄；
+ * 3. 校验用 `isValid`（weld 后必须合法），不合法即抛错——开放/非流形网格必须
+ *    在导入处失败，不能静默退化成"无拓扑的裸网格"（那会让所有下游 mesh op
+ *    失去选择能力）。
+ *
+ * @param backend - the mesh backend providing ops + kernel.
+ * @param mesh - the source triangle mesh.
+ * @param opts - optional weld tolerance / tessellation overrides.
+ * @returns the normalized mesh solid, its tessellation, and element counts.
+ * @throws {Error} `E_MESH_SOLID_UNWELDABLE` when welding leaves an invalid solid.
+ */
+export declare function normalizeMeshSolid(backend: MeshSolidBackend, mesh: MeshSolidInput, opts?: MeshSolidNormalizeOptions): MeshSolidResult;
+/**
+ * 已存在的网格实体 → 结果描述（三角化 + 计数）。
+ *
+ * Phase 2 的 mesh op 产出的新实体走这里：**一次**三角化同时喂显示与拓扑，
+ * 保证 `faceRuns` 与所见三角形一一对应（规则 1）。重复调 `describe` 会得到
+ * 另一份三角化结果——同一实体在同一参数下确定性一致，但仍应复用同一份结果。
+ *
+ * @param backend - the mesh backend.
+ * @param solid - an existing mesh solid handle.
+ * @param opts - optional tessellation overrides.
+ * @returns the mesh solid result carrying the shared tessellation.
+ */
+export declare function describeMeshSolid(backend: MeshSolidBackend, solid: BrepHandle, opts?: MeshSolidNormalizeOptions): MeshSolidResult;
+/**
+ * 网格实体 → 近似拓扑数据（`SelectorRuntimeData`）。
+ *
+ * 复用 BREP 路径同源的 `buildTopologyFromMesh`（方案 §1.3 实测：产物与 BREP
+ * 路径同构——同样的 FaceRow/EdgeRow 字段、同样的 `faceStart/faceCount` 邻接）。
+ * **不引入第二套拓扑表示。**
+ *
+ * @param backend - the mesh backend (kernel + release).
+ * @param result - the normalized mesh solid result (carries the shared tessellation).
+ * @returns the serializable selector runtime data.
+ */
+export declare function buildMeshSolidTopology(backend: MeshSolidBackend, result: MeshSolidResult): SelectorRuntimeData;
+/**
+ * 网格实体句柄注册表（`PartName → BrepHandle`）。
+ *
+ * 与 `brepChain.solidCache` 的差别：本表**永不**参与 BREP 精度链判定——
+ * 它存在只表示"该 part 是网格零件，携带近似拓扑"。释放语义与 solidCache 对齐：
+ * `set` 覆盖不释放（旧句柄可能仍被旧输出 Shape 引用），`delete`/`clear` 释放。
+ */
+export declare class MeshSolidRegistry {
+    private readonly handles;
+    private backendRef;
+    /**
+     * 装配/换装网格后端（宿主装配期；运行期只读语义）。
+     * @param backend - the mesh backend, or null to detach.
+     */
+    setBackend(backend: MeshSolidBackend | null): void;
+    /**
+     * 当前网格后端（未装配则 null）。
+     * @returns the assembled mesh backend, or null.
+     */
+    get backend(): MeshSolidBackend | null;
+    /**
+     * 登记某 part 的网格实体句柄（覆盖旧值，**不释放**旧句柄——与 solidCache 同语义）。
+     * @param part - the part name.
+     * @param solid - the mesh solid handle.
+     */
+    set(part: PartName, solid: BrepHandle): void;
+    /**
+     * 读取某 part 的网格实体句柄。
+     * @param part - the part name.
+     * @returns the handle, or undefined.
+     */
+    get(part: PartName): BrepHandle | undefined;
+    /**
+     * 该 part 是否携带网格实体。
+     * @param part - the part name.
+     * @returns true when a handle is registered.
+     */
+    has(part: PartName): boolean;
+    /**
+     * 删除某 part 并释放其句柄（重放/失效路径）。
+     * @param part - the part name.
+     */
+    delete(part: PartName): void;
+    /**
+     * 按 part 名列表批量删除（重放失效用）。
+     * @param parts - the part names to delete; unknown names are ignored.
+     */
+    deleteMany(parts: Iterable<PartName>): void;
+    /** 释放全部句柄并清空（dispose）。 */
+    clear(): void;
+    /**
+     * 当前登记的全部 part 名（诊断/测试）。
+     * @returns the registered part names.
+     */
+    keys(): PartName[];
+    /** 登记数量（诊断/测试）。 */
+    get size(): number;
+}
+//# sourceMappingURL=mesh-solid.d.ts.map

package/dist/brep/mesh-solid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-solid.d.ts","sourceRoot":"","sources":["../../src/brep/mesh-solid.ts"],"names":[],"mappings":"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"}

package/dist/brep/mesh-solid.js

@@ -0,0 +1,229 @@
+/**
+ * mesh-solid — 网格实体（mesh solid）与其网格后端端口
+ *
+ *
+ * 名词边界（方案 §3.1）：
+ * - **网格实体** = 由网格文件导入、经「规范化」得到的引擎实体。它是**近似拓扑**
+ *   的载体，不是精度链的一环；永不进 `brepChain.solidCache`。
+ * - **规范化** = `importIndexedMesh` → `weldShellsAndFaces(tol)` → `unifyFaces()`。
+ *   **顺序不可交换**：先 `unifyFaces` 会把实体做坏（体积归零），防回归用例见
+ *   `brepkit-kernel/mesh-solid-topology.test.ts`。
+ * - **网格后端** = 提供网格实体能力的引擎侧组件（本期即 brepkit 的网格用法）。
+ *   与 BREP 引擎**同名不同用**：可能同一个 wasm 实例，但走 mesh 语义路径。
+ *
+ * 本模块只依赖 L1（`engine/types`、`engine/primitives`）与拓扑构建器；后端实现
+ * 放在适配器侧（`brep/engine/adapters/brepkit`），因此本模块自身不含任何内核私有
+ * 调用——`MeshSolidKernelOps` 是内核私有原语的端口（L1 契约不含 weld/unify）。
+ */
+import { buildTopologyFromMesh } from './brep-topology.js';
+// ── 规范化驱动（引擎中立，供适配器的 MeshSolidBackend 实现复用） ──
+/** 与显示 mesh 一致的默认三角化参数（`buildSolidTopologyRuntime` 同源）。 */
+const DISPLAY_LINEAR_DEFLECTION = 0.1;
+const DISPLAY_ANGULAR_DEFLECTION = (2 * Math.PI) / 32;
+/**
+ * 由包围盒对角线导出焊接容差（方案 §3.3）。
+ *
+ * 下限 1e-6 兜住退化 bbox（单点/零厚网格）；上不封顶——超大模型需要更粗的
+ * 缝合半径才缝得上（float32 坐标的相对误差随尺度线性增长）。
+ *
+ * @param kernel - the L1 kernel API (bbox query only).
+ * @param shape - the raw imported shape.
+ * @returns the weld tolerance derived from the bounding-box diagonal.
+ */
+export function weldToleranceFor(kernel, shape) {
+    const bb = kernel.getBoundingBox(shape, false);
+    const dx = bb.xmax - bb.xmin;
+    const dy = bb.ymax - bb.ymin;
+    const dz = bb.zmax - bb.zmin;
+    const diag = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    return Math.max(1e-6, diag * 1e-6);
+}
+/**
+ * 规范化：`importMesh` → `weld` → `unify`，再校验并三角化。
+ *
+ * 三条硬约束，都是 Phase 0 实测结论：
+ * 1. **顺序不可交换**——先 unify 再 weld 会得到体积归零的坏实体；
+ * 2. `unify` **原地修改**，返回值是合并面数，不是句柄；
+ * 3. 校验用 `isValid`（weld 后必须合法），不合法即抛错——开放/非流形网格必须
+ *    在导入处失败，不能静默退化成"无拓扑的裸网格"（那会让所有下游 mesh op
+ *    失去选择能力）。
+ *
+ * @param backend - the mesh backend providing ops + kernel.
+ * @param mesh - the source triangle mesh.
+ * @param opts - optional weld tolerance / tessellation overrides.
+ * @returns the normalized mesh solid, its tessellation, and element counts.
+ * @throws {Error} `E_MESH_SOLID_UNWELDABLE` when welding leaves an invalid solid.
+ */
+export function normalizeMeshSolid(backend, mesh, opts) {
+    const { kernel, ops } = backend;
+    const raw = ops.importMesh(mesh.positions, mesh.indices);
+    const tolerance = opts?.weldTolerance ?? weldToleranceFor(kernel, raw);
+    const faces = kernel.getSubShapes(raw, 'face');
+    const welded = ops.weld(faces, tolerance);
+    // 原地修改：返回值是合并掉的面数。绝不能把它当句柄。
+    const mergedFaceCount = ops.unify(welded);
+    if (!kernel.isValid(welded)) {
+        // 原始实体（逐三角形、边不共享）在 weld 前就不合法是正常的；weld 后仍不合法
+        // 说明网格本身开放/非流形/自交——这是**必须暴露的导入失败**，不是可降级状态。
+        try {
+            backend.release(raw);
+        }
+        catch { /* already released */ }
+        throw new Error(`E_MESH_SOLID_UNWELDABLE: welded mesh is still an invalid solid (tolerance=${tolerance}) — ` +
+            'the source mesh is open, non-manifold or self-intersecting');
+    }
+    // 焊接后原始逐三角形实体已无用；及时释放，避免句柄堆积（新路径不得添泄漏）。
+    try {
+        backend.release(raw);
+    }
+    catch { /* already released */ }
+    const tess = kernel.meshShape(welded, {
+        linearDeflection: opts?.linearDeflection ?? DISPLAY_LINEAR_DEFLECTION,
+        angularDeflection: opts?.angularDeflection ?? DISPLAY_ANGULAR_DEFLECTION,
+    });
+    return {
+        solid: welded,
+        mesh: tess,
+        faceCount: kernel.getSubShapes(welded, 'face').length,
+        edgeCount: kernel.getSubShapes(welded, 'edge').length,
+        vertexCount: kernel.getSubShapes(welded, 'vertex').length,
+        weldTolerance: tolerance,
+        mergedFaceCount,
+    };
+}
+/**
+ * 已存在的网格实体 → 结果描述（三角化 + 计数）。
+ *
+ * Phase 2 的 mesh op 产出的新实体走这里：**一次**三角化同时喂显示与拓扑，
+ * 保证 `faceRuns` 与所见三角形一一对应（规则 1）。重复调 `describe` 会得到
+ * 另一份三角化结果——同一实体在同一参数下确定性一致，但仍应复用同一份结果。
+ *
+ * @param backend - the mesh backend.
+ * @param solid - an existing mesh solid handle.
+ * @param opts - optional tessellation overrides.
+ * @returns the mesh solid result carrying the shared tessellation.
+ */
+export function describeMeshSolid(backend, solid, opts) {
+    const { kernel } = backend;
+    const tess = kernel.meshShape(solid, {
+        linearDeflection: opts?.linearDeflection ?? DISPLAY_LINEAR_DEFLECTION,
+        angularDeflection: opts?.angularDeflection ?? DISPLAY_ANGULAR_DEFLECTION,
+    });
+    return {
+        solid,
+        mesh: tess,
+        faceCount: kernel.getSubShapes(solid, 'face').length,
+        edgeCount: kernel.getSubShapes(solid, 'edge').length,
+        vertexCount: kernel.getSubShapes(solid, 'vertex').length,
+        weldTolerance: 0,
+        mergedFaceCount: 0,
+    };
+}
+/**
+ * 网格实体 → 近似拓扑数据（`SelectorRuntimeData`）。
+ *
+ * 复用 BREP 路径同源的 `buildTopologyFromMesh`（方案 §1.3 实测：产物与 BREP
+ * 路径同构——同样的 FaceRow/EdgeRow 字段、同样的 `faceStart/faceCount` 邻接）。
+ * **不引入第二套拓扑表示。**
+ *
+ * @param backend - the mesh backend (kernel + release).
+ * @param result - the normalized mesh solid result (carries the shared tessellation).
+ * @returns the serializable selector runtime data.
+ */
+export function buildMeshSolidTopology(backend, result) {
+    return buildTopologyFromMesh(backend.kernel, result.solid, result.mesh);
+}
+// ── 注册表（生命周期，与 brepChain.solidCache 并列且互不干扰） ──
+/**
+ * 网格实体句柄注册表（`PartName → BrepHandle`）。
+ *
+ * 与 `brepChain.solidCache` 的差别：本表**永不**参与 BREP 精度链判定——
+ * 它存在只表示"该 part 是网格零件，携带近似拓扑"。释放语义与 solidCache 对齐：
+ * `set` 覆盖不释放（旧句柄可能仍被旧输出 Shape 引用），`delete`/`clear` 释放。
+ */
+export class MeshSolidRegistry {
+    handles = new Map();
+    backendRef = null;
+    /**
+     * 装配/换装网格后端（宿主装配期；运行期只读语义）。
+     * @param backend - the mesh backend, or null to detach.
+     */
+    setBackend(backend) {
+        this.backendRef = backend;
+    }
+    /**
+     * 当前网格后端（未装配则 null）。
+     * @returns the assembled mesh backend, or null.
+     */
+    get backend() {
+        return this.backendRef;
+    }
+    /**
+     * 登记某 part 的网格实体句柄（覆盖旧值，**不释放**旧句柄——与 solidCache 同语义）。
+     * @param part - the part name.
+     * @param solid - the mesh solid handle.
+     */
+    set(part, solid) {
+        this.handles.set(part, solid);
+    }
+    /**
+     * 读取某 part 的网格实体句柄。
+     * @param part - the part name.
+     * @returns the handle, or undefined.
+     */
+    get(part) {
+        return this.handles.get(part);
+    }
+    /**
+     * 该 part 是否携带网格实体。
+     * @param part - the part name.
+     * @returns true when a handle is registered.
+     */
+    has(part) {
+        return this.handles.has(part);
+    }
+    /**
+     * 删除某 part 并释放其句柄（重放/失效路径）。
+     * @param part - the part name.
+     */
+    delete(part) {
+        const h = this.handles.get(part);
+        if (h === undefined)
+            return;
+        this.handles.delete(part);
+        try {
+            this.backendRef?.release(h);
+        }
+        catch { /* already released */ }
+    }
+    /**
+     * 按 part 名列表批量删除（重放失效用）。
+     * @param parts - the part names to delete; unknown names are ignored.
+     */
+    deleteMany(parts) {
+        for (const p of parts)
+            this.delete(p);
+    }
+    /** 释放全部句柄并清空（dispose）。 */
+    clear() {
+        for (const h of this.handles.values()) {
+            try {
+                this.backendRef?.release(h);
+            }
+            catch { /* already released */ }
+        }
+        this.handles.clear();
+    }
+    /**
+     * 当前登记的全部 part 名（诊断/测试）。
+     * @returns the registered part names.
+     */
+    keys() {
+        return [...this.handles.keys()];
+    }
+    /** 登记数量（诊断/测试）。 */
+    get size() {
+        return this.handles.size;
+    }
+}
+//# sourceMappingURL=mesh-solid.js.map

package/dist/brep/mesh-solid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-solid.js","sourceRoot":"","sources":["../../src/brep/mesh-solid.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * mesh-solid — 网格实体（mesh solid）与其网格后端端口\n *\n *\n * 名词边界（方案 §3.1）：\n * - **网格实体** = 由网格文件导入、经「规范化」得到的引擎实体。它是**近似拓扑**\n *   的载体，不是精度链的一环；永不进 `brepChain.solidCache`。\n * - **规范化** = `importIndexedMesh` → `weldShellsAndFaces(tol)` → `unifyFaces()`。\n *   **顺序不可交换**：先 `unifyFaces` 会把实体做坏（体积归零），防回归用例见\n *   `brepkit-kernel/mesh-solid-topology.test.ts`。\n * - **网格后端** = 提供网格实体能力的引擎侧组件（本期即 brepkit 的网格用法）。\n *   与 BREP 引擎**同名不同用**：可能同一个 wasm 实例，但走 mesh 语义路径。\n *\n * 本模块只依赖 L1（`engine/types`、`engine/primitives`）与拓扑构建器；后端实现\n * 放在适配器侧（`brep/engine/adapters/brepkit`），因此本模块自身不含任何内核私有\n * 调用——`MeshSolidKernelOps` 是内核私有原语的端口（L1 契约不含 weld/unify）。\n */\n\nimport type { BrepHandle, BrepMeshResult } from './engine/types'\nimport type { BrepEngineApi } from './engine/primitives'\nimport type { PartName } from '../identity'\nimport type { SelectorRuntimeData } from '../topology/build-selector-runtime'\nimport { buildTopologyFromMesh } from './brep-topology'\n\n/** 网格实体构建的输入网格（已按基准单位折算的坐标，与 `Shape` 同构）。 */\nexport interface MeshSolidInput {\n  positions: Float32Array\n  indices: Uint32Array\n}\n\n/** 规范化选项。 */\nexport interface MeshSolidNormalizeOptions {\n  /**\n   * 焊接容差（顶点/重复边缝合半径）。缺省由包围盒对角线定标\n   * （`max(1e-6, 对角线 × 1e-6)`）——**不得写死绝对值**：STL 无单位元数据，\n   * 同一文件既可能是 mm 也可能是 inch，绝对容差在两种尺度下必有一边失准。\n   */\n  weldTolerance?: number\n  /** 三角化参数（缺省与显示 mesh 一致：0.1 / 2π/32）。 */\n  linearDeflection?: number\n  angularDeflection?: number\n}\n\n/** 规范化结果：实体句柄 + 其三角化（显示 mesh 与拓扑 mesh 的唯一真源）。 */\nexport interface MeshSolidResult {\n  /** 规范化后的网格实体句柄。 */\n  readonly solid: BrepHandle\n  /**\n   * 同一实体的三角化（含 faceGroups）。**显示 mesh 必须用这一份**——规则 1：\n   * 拓扑 faceRuns 所索引的三角形，必须就是用户看到的三角形。若显示仍用原始\n   * STL 顶点数组、拓扑用实体的重新三角化，两者三角形数/序不一致 → faceRuns 错位。\n   */\n  readonly mesh: BrepMeshResult\n  readonly faceCount: number\n  readonly edgeCount: number\n  readonly vertexCount: number\n  /** 实际使用的焊接容差（诊断/复现用）。 */\n  readonly weldTolerance: number\n  /** `unifyFaces` 合并掉的重复面数（0 = 共面面片未被合并，顶点未焊上）。 */\n  readonly mergedFaceCount: number\n}\n\n/**\n * 网格后端的**内核私有原语**（L1 `BrepEngineApi` 不含 weld/unify）。\n *\n * 由适配器（拥用内核闭包的一侧）实现；句柄一律是 faijs `BrepHandle`\n * （适配器内部负责 `asNum()` 剥离标签），本模块不感知内核方言。\n */\nexport interface MeshSolidKernelOps {\n  /** 原始三角网格 → 逐三角形面的实体（内核自带顶点焊接）。 */\n  importMesh(positions: Float32Array, indices: Uint32Array): BrepHandle\n  /** 面列表 → 缝合后的实体（重复边缝成共享边 → 真流形）。 */\n  weld(faces: BrepHandle[], tolerance: number): BrepHandle\n  /** 共面区域合并（**原地修改**，返回合并掉的面数）。 */\n  unify(solid: BrepHandle): number\n}\n\n/**\n * 网格后端端口：`load` 的 mesh 路径经它产出网格实体与近似拓扑。\n *\n * 生命周期：由宿主装配期注册进 mesh 引擎槽（`registerMeshEngine`），运行期只读。\n */\nexport interface MeshSolidBackend {\n  /** 后端 id（与 `defineOp.meshEngines` 的门禁名同源，如 `'brepkit'`）。 */\n  readonly id: string\n  /** L1 契约面（拓扑查询 + 几何操作；brepkit 适配器已全实现）。 */\n  readonly kernel: BrepEngineApi\n  /** 内核私有原语（weld/unify）。 */\n  readonly ops: MeshSolidKernelOps\n  /**\n   * 规范化 + 三角化。**失败必须抛错**（带 part 名由调用方补），不静默降级。\n   * @param mesh - the source triangle mesh (base-unit coordinates).\n   * @param opts - optional weld tolerance / tessellation overrides.\n   * @returns the mesh solid with its tessellation.\n   */\n  normalize(mesh: MeshSolidInput, opts?: MeshSolidNormalizeOptions): MeshSolidResult\n  /**\n   * 已存在的网格实体 → 结果描述（三角化 + 计数）。Phase 2 的 mesh op 用它把\n   * 「内核操作产出的新实体」包成下一份网格零件（显示 mesh 与拓扑 mesh 同源）。\n   * @param solid - an existing mesh solid handle.\n   * @param opts - optional tessellation overrides.\n   * @returns the mesh solid result carrying the shared tessellation.\n   */\n  describe(solid: BrepHandle, opts?: MeshSolidNormalizeOptions): MeshSolidResult\n  /**\n   * 从网格实体结果构建近似拓扑数据（`SelectorRuntimeData`，可直接交 `setTopology`）。\n   * @param result - the mesh solid result (its tessellation indexes the topology).\n   * @returns the serializable selector runtime data.\n   */\n  buildTopologyData(result: MeshSolidResult): SelectorRuntimeData\n  /** 释放网格实体句柄。 */\n  release(solid: BrepHandle): void\n}\n\n// ── 规范化驱动（引擎中立，供适配器的 MeshSolidBackend 实现复用） ──\n\n/** 与显示 mesh 一致的默认三角化参数（`buildSolidTopologyRuntime` 同源）。 */\nconst DISPLAY_LINEAR_DEFLECTION = 0.1\nconst DISPLAY_ANGULAR_DEFLECTION = (2 * Math.PI) / 32\n\n/**\n * 由包围盒对角线导出焊接容差（方案 §3.3）。\n *\n * 下限 1e-6 兜住退化 bbox（单点/零厚网格）；上不封顶——超大模型需要更粗的\n * 缝合半径才缝得上（float32 坐标的相对误差随尺度线性增长）。\n *\n * @param kernel - the L1 kernel API (bbox query only).\n * @param shape - the raw imported shape.\n * @returns the weld tolerance derived from the bounding-box diagonal.\n */\nexport function weldToleranceFor(kernel: BrepEngineApi, shape: BrepHandle): number {\n  const bb = kernel.getBoundingBox(shape, false)\n  const dx = bb.xmax - bb.xmin\n  const dy = bb.ymax - bb.ymin\n  const dz = bb.zmax - bb.zmin\n  const diag = Math.sqrt(dx * dx + dy * dy + dz * dz)\n  return Math.max(1e-6, diag * 1e-6)\n}\n\n/**\n * 规范化：`importMesh` → `weld` → `unify`，再校验并三角化。\n *\n * 三条硬约束，都是 Phase 0 实测结论：\n * 1. **顺序不可交换**——先 unify 再 weld 会得到体积归零的坏实体；\n * 2. `unify` **原地修改**，返回值是合并面数，不是句柄；\n * 3. 校验用 `isValid`（weld 后必须合法），不合法即抛错——开放/非流形网格必须\n *    在导入处失败，不能静默退化成\"无拓扑的裸网格\"（那会让所有下游 mesh op\n *    失去选择能力）。\n *\n * @param backend - the mesh backend providing ops + kernel.\n * @param mesh - the source triangle mesh.\n * @param opts - optional weld tolerance / tessellation overrides.\n * @returns the normalized mesh solid, its tessellation, and element counts.\n * @throws {Error} `E_MESH_SOLID_UNWELDABLE` when welding leaves an invalid solid.\n */\nexport function normalizeMeshSolid(\n  backend: MeshSolidBackend,\n  mesh: MeshSolidInput,\n  opts?: MeshSolidNormalizeOptions,\n): MeshSolidResult {\n  const { kernel, ops } = backend\n  const raw = ops.importMesh(mesh.positions, mesh.indices)\n  const tolerance = opts?.weldTolerance ?? weldToleranceFor(kernel, raw)\n\n  const faces = kernel.getSubShapes(raw, 'face')\n  const welded = ops.weld(faces, tolerance)\n  // 原地修改：返回值是合并掉的面数。绝不能把它当句柄。\n  const mergedFaceCount = ops.unify(welded)\n\n  if (!kernel.isValid(welded)) {\n    // 原始实体（逐三角形、边不共享）在 weld 前就不合法是正常的；weld 后仍不合法\n    // 说明网格本身开放/非流形/自交——这是**必须暴露的导入失败**，不是可降级状态。\n    try { backend.release(raw) } catch { /* already released */ }\n    throw new Error(\n      `E_MESH_SOLID_UNWELDABLE: welded mesh is still an invalid solid (tolerance=${tolerance}) — ` +\n      'the source mesh is open, non-manifold or self-intersecting',\n    )\n  }\n  // 焊接后原始逐三角形实体已无用；及时释放，避免句柄堆积（新路径不得添泄漏）。\n  try { backend.release(raw) } catch { /* already released */ }\n\n  const tess = kernel.meshShape(welded, {\n    linearDeflection: opts?.linearDeflection ?? DISPLAY_LINEAR_DEFLECTION,\n    angularDeflection: opts?.angularDeflection ?? DISPLAY_ANGULAR_DEFLECTION,\n  })\n\n  return {\n    solid: welded,\n    mesh: tess,\n    faceCount: kernel.getSubShapes(welded, 'face').length,\n    edgeCount: kernel.getSubShapes(welded, 'edge').length,\n    vertexCount: kernel.getSubShapes(welded, 'vertex').length,\n    weldTolerance: tolerance,\n    mergedFaceCount,\n  }\n}\n\n/**\n * 已存在的网格实体 → 结果描述（三角化 + 计数）。\n *\n * Phase 2 的 mesh op 产出的新实体走这里：**一次**三角化同时喂显示与拓扑，\n * 保证 `faceRuns` 与所见三角形一一对应（规则 1）。重复调 `describe` 会得到\n * 另一份三角化结果——同一实体在同一参数下确定性一致，但仍应复用同一份结果。\n *\n * @param backend - the mesh backend.\n * @param solid - an existing mesh solid handle.\n * @param opts - optional tessellation overrides.\n * @returns the mesh solid result carrying the shared tessellation.\n */\nexport function describeMeshSolid(\n  backend: MeshSolidBackend,\n  solid: BrepHandle,\n  opts?: MeshSolidNormalizeOptions,\n): MeshSolidResult {\n  const { kernel } = backend\n  const tess = kernel.meshShape(solid, {\n    linearDeflection: opts?.linearDeflection ?? DISPLAY_LINEAR_DEFLECTION,\n    angularDeflection: opts?.angularDeflection ?? DISPLAY_ANGULAR_DEFLECTION,\n  })\n  return {\n    solid,\n    mesh: tess,\n    faceCount: kernel.getSubShapes(solid, 'face').length,\n    edgeCount: kernel.getSubShapes(solid, 'edge').length,\n    vertexCount: kernel.getSubShapes(solid, 'vertex').length,\n    weldTolerance: 0,\n    mergedFaceCount: 0,\n  }\n}\n\n/**\n * 网格实体 → 近似拓扑数据（`SelectorRuntimeData`）。\n *\n * 复用 BREP 路径同源的 `buildTopologyFromMesh`（方案 §1.3 实测：产物与 BREP\n * 路径同构——同样的 FaceRow/EdgeRow 字段、同样的 `faceStart/faceCount` 邻接）。\n * **不引入第二套拓扑表示。**\n *\n * @param backend - the mesh backend (kernel + release).\n * @param result - the normalized mesh solid result (carries the shared tessellation).\n * @returns the serializable selector runtime data.\n */\nexport function buildMeshSolidTopology(\n  backend: MeshSolidBackend,\n  result: MeshSolidResult,\n): SelectorRuntimeData {\n  return buildTopologyFromMesh(backend.kernel, result.solid, result.mesh)\n}\n\n// ── 注册表（生命周期，与 brepChain.solidCache 并列且互不干扰） ──\n\n/**\n * 网格实体句柄注册表（`PartName → BrepHandle`）。\n *\n * 与 `brepChain.solidCache` 的差别：本表**永不**参与 BREP 精度链判定——\n * 它存在只表示\"该 part 是网格零件，携带近似拓扑\"。释放语义与 solidCache 对齐：\n * `set` 覆盖不释放（旧句柄可能仍被旧输出 Shape 引用），`delete`/`clear` 释放。\n */\nexport class MeshSolidRegistry {\n  private readonly handles = new Map<PartName, BrepHandle>()\n  private backendRef: MeshSolidBackend | null = null\n\n  /**\n   * 装配/换装网格后端（宿主装配期；运行期只读语义）。\n   * @param backend - the mesh backend, or null to detach.\n   */\n  setBackend(backend: MeshSolidBackend | null): void {\n    this.backendRef = backend\n  }\n\n  /**\n   * 当前网格后端（未装配则 null）。\n   * @returns the assembled mesh backend, or null.\n   */\n  get backend(): MeshSolidBackend | null {\n    return this.backendRef\n  }\n\n  /**\n   * 登记某 part 的网格实体句柄（覆盖旧值，**不释放**旧句柄——与 solidCache 同语义）。\n   * @param part - the part name.\n   * @param solid - the mesh solid handle.\n   */\n  set(part: PartName, solid: BrepHandle): void {\n    this.handles.set(part, solid)\n  }\n\n  /**\n   * 读取某 part 的网格实体句柄。\n   * @param part - the part name.\n   * @returns the handle, or undefined.\n   */\n  get(part: PartName): BrepHandle | undefined {\n    return this.handles.get(part)\n  }\n\n  /**\n   * 该 part 是否携带网格实体。\n   * @param part - the part name.\n   * @returns true when a handle is registered.\n   */\n  has(part: PartName): boolean {\n    return this.handles.has(part)\n  }\n\n  /**\n   * 删除某 part 并释放其句柄（重放/失效路径）。\n   * @param part - the part name.\n   */\n  delete(part: PartName): void {\n    const h = this.handles.get(part)\n    if (h === undefined) return\n    this.handles.delete(part)\n    try { this.backendRef?.release(h) } catch { /* already released */ }\n  }\n\n  /**\n   * 按 part 名列表批量删除（重放失效用）。\n   * @param parts - the part names to delete; unknown names are ignored.\n   */\n  deleteMany(parts: Iterable<PartName>): void {\n    for (const p of parts) this.delete(p)\n  }\n\n  /** 释放全部句柄并清空（dispose）。 */\n  clear(): void {\n    for (const h of this.handles.values()) {\n      try { this.backendRef?.release(h) } catch { /* already released */ }\n    }\n    this.handles.clear()\n  }\n\n  /**\n   * 当前登记的全部 part 名（诊断/测试）。\n   * @returns the registered part names.\n   */\n  keys(): PartName[] {\n    return [...this.handles.keys()]\n  }\n\n  /** 登记数量（诊断/测试）。 */\n  get size(): number {\n    return this.handles.size\n  }\n}\n"]}

package/dist/brep/text/fontRegistry.d.ts

@@ -13,11 +13,24 @@ import type { Font } from 'opentype.js';
  * 字体二进制加载器接口。
  *
  * 生产代码（text.ts / engrave.ts）不自己决定字体来源，
- * 而是通过 ensureDefaultFont() 使用注入的 FontLoader。
+ * 而是通过 ensureDefaultFont() / ensureFont() 使用注入的 FontLoader。
  */
 export interface FontLoader {
     /** 返回默认字体的二进制数据 */
     loadDefaultFont(): Promise<ArrayBuffer>;
+    /**
+     * 可选：按**字体族名**或**文件路径**取字体二进制。
+     *
+     * 宿主实现（Node 读磁盘/系统字体目录、浏览器按 URL 映射）决定来源；引擎核心
+     * 不碰 fs/fetch。返回 `null` 表示宿主无法解析该名字——调用方回退到默认字体
+     * （与 CadQuery/OCC `Font_FontMgr::FindFont` 找不到名字时回退默认字体的语义一致）。
+     *
+     * 未实现该方法的宿主（如浏览器）会让 `ensureFont(name)` 直接回退默认字体。
+     *
+     * @param nameOrPath - 字体族名（如 `"Arial"`）或字体文件路径
+     * @returns 字体字节，或 null（无法解析）
+     */
+    resolveFont?(nameOrPath: string): Promise<ArrayBuffer | null>;
 }
 /**
  * 设置当前环境的字体加载器。
@@ -61,6 +74,24 @@ export declare function ensureDefaultFont(): Promise<void>;
  * @returns opentype.js Font 对象，如果未加载则返回 undefined
  */
 export declare function getFont(fontFamily?: string): Font | undefined;
+/**
+ * 确保某个**具名字体**可用，并返回它。
+ *
+ * 语义对齐 CadQuery 的 `font=`/`fontPath=`：
+ *
+ * - 名字已注册过（含 `loadFont(data, name)` 直接注册）⇒ 直接返回；
+ * - `fontPath`（已存在的文件路径）或字体族名 ⇒ 交给 `FontLoader.resolveFont` 解析，
+ *   解析成功后**以该名字注册**，后续同名调用命中缓存；
+ * - 宿主没有 `resolveFont`、或解析失败（名字不是本机已安装字体）⇒ **回退到默认字体**
+ *   （OCC `Font_FontMgr::FindFont` 找不到字体时同样回退默认字体，不会抛错）。
+ *
+ * `null`/`undefined`/空串等价于「不指定」⇒ 默认字体。
+ *
+ * @param nameOrPath - 字体族名、字体文件路径，或 null/undefined 表示默认字体
+ * @returns 解析到的字体（解析不到时是默认字体）
+ * @throws 没有安装 FontLoader 且默认字体也未加载时
+ */
+export declare function ensureFont(nameOrPath?: string | null): Promise<Font>;
 /**
  * 清除所有已注册的字体。
  *

package/dist/brep/text/fontRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fontRegistry.d.ts","sourceRoot":"","sources":["../../../src/brep/text/fontRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAMvC;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,mBAAmB;IACnB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACxC;AAID;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,WAAW,EACrB,UAAU,SAAY,EACtB,KAAK,UAAQ,GACZ,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAavD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,UAAU,SAAY,GAAG,IAAI,GAAG,SAAS,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAIjC"}
+{"version":3,"file":"fontRegistry.d.ts","sourceRoot":"","sources":["../../../src/brep/text/fontRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAoBvC;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,mBAAmB;IACnB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IACvC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC9D;AAID;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,WAAW,EACrB,UAAU,SAAY,EACtB,KAAK,UAAQ,GACZ,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAavD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,UAAU,SAAY,GAAG,IAAI,GAAG,SAAS,CAEhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB1E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAIjC"}

package/dist/brep/text/fontRegistry.js

@@ -8,7 +8,19 @@
  * - Node 测试：fontTestHelper.ts 通过 fs.readFileSync 加载
  * - 字体文件唯一真源：src/assets/fonts/OpenSans-Regular.ttf
  */
-import * as opentype from 'opentype.js';
+import * as opentypeModule from 'opentype.js';
+/**
+ * `opentype.js` publishes no `exports` map: it ships a UMD bundle (`main`) plus
+ * an ESM build (`module`). Node ESM resolves the UMD `main`, whose CommonJS
+ * interop exposes a namespace import as `{ default }` only — so
+ * `opentypeModule.parse` is undefined there — whereas bundlers (vite/vitest)
+ * resolve the ESM build and expose the named exports directly. Resolve once,
+ * here, so glyph parsing works in every host (CLI/tsx = Node ESM,
+ * vitest/browser = bundler).
+ */
+const opentype = typeof opentypeModule.parse === 'function'
+    ? opentypeModule
+    : opentypeModule.default;
 const FONT_REGISTER = {};
 let activeFontLoader = null;
 /**
@@ -86,6 +98,44 @@ export async function ensureDefaultFont() {
 export function getFont(fontFamily = 'default') {
     return FONT_REGISTER[fontFamily];
 }
+/**
+ * 确保某个**具名字体**可用，并返回它。
+ *
+ * 语义对齐 CadQuery 的 `font=`/`fontPath=`：
+ *
+ * - 名字已注册过（含 `loadFont(data, name)` 直接注册）⇒ 直接返回；
+ * - `fontPath`（已存在的文件路径）或字体族名 ⇒ 交给 `FontLoader.resolveFont` 解析，
+ *   解析成功后**以该名字注册**，后续同名调用命中缓存；
+ * - 宿主没有 `resolveFont`、或解析失败（名字不是本机已安装字体）⇒ **回退到默认字体**
+ *   （OCC `Font_FontMgr::FindFont` 找不到字体时同样回退默认字体，不会抛错）。
+ *
+ * `null`/`undefined`/空串等价于「不指定」⇒ 默认字体。
+ *
+ * @param nameOrPath - 字体族名、字体文件路径，或 null/undefined 表示默认字体
+ * @returns 解析到的字体（解析不到时是默认字体）
+ * @throws 没有安装 FontLoader 且默认字体也未加载时
+ */
+export async function ensureFont(nameOrPath) {
+    if (!nameOrPath) {
+        await ensureDefaultFont();
+        return getFont();
+    }
+    const already = getFont(nameOrPath);
+    if (already)
+        return already;
+    if (nameOrPath === 'default') {
+        await ensureDefaultFont();
+        return getFont();
+    }
+    const resolver = activeFontLoader?.resolveFont;
+    if (resolver) {
+        const data = await activeFontLoader.resolveFont(nameOrPath);
+        if (data)
+            return loadFont(data, nameOrPath, true);
+    }
+    await ensureDefaultFont();
+    return getFont();
+}
 /**
  * 清除所有已注册的字体。
  *