@faicad/faijs 0.22.2 → 0.29.3

package/dist/api/internal/mesh-solid-op.js

@@ -0,0 +1,352 @@
+/**
+ * mesh-solid-op — 网格 op 的「三明治」共享实现（方案 2026-10-01 §3.5）
+ *
+ * 每个网格 op 的实现体都是同一个形状，本模块只把这三步抽出来，让 op 侧只剩"调哪个
+ * 内核方法"这一件事：
+ *
+ * ```
+ * MeshData ──► meshSolid 句柄（从 Shape 槽取，**不重复导入**）
+ *               │
+ *               ├─ 内核调用（fillet / chamfer / fuse / cut / intersect / …）
+ *               │
+ *               └─ meshShape(新句柄) ──► MeshData（显示 mesh 与近似拓扑**同一份**）
+ * ```
+ *
+ * 三条不可让步的口径：
+ *
+ * 1. **显示 mesh = 新实体的三角化**，不是输入的顶点数组。规则 1：拓扑 faceRuns
+ *    索引的三角形必须就是用户看到的三角形——照抄输入数组会让两者错位。
+ * 2. **新句柄必须写回**（Shape 槽 + 运行时注册表 + 近似拓扑）。不写回 = 下游 op
+ *    拿不到句柄、宿主选中不到面；不登记注册表 = 句柄无人释放。
+ * 3. **旧句柄不由本模块释放**。BREP 侧同构（`filletBrep` 也不释放输入句柄）：
+ *    句柄生命周期归链（注册表 / releasePartCaches），op 只管"取一个、交一个"。
+ *    这里"顺手 release 输入"会打断 `b = fillet(a)` 之后仍然可用的 `a`。
+ *
+ * op 拿不到 `CadRuntime` 实例，故句柄与拓扑经 **pending 通道**登记
+ * （与 `load` 的 `setPendingMeshSolid` / `setPendingMeshTopology` 同模式），
+ * 由引擎在语句执行后收编——收编时会核对存活 ctx 变量仍携带**这个**句柄，防顶替。
+ */
+import { describeMeshSolid, } from '../../brep/mesh-solid.js';
+import { fromMeshFace, fromMeshSolid, meshFaceOf, meshSolidOf } from '../../shape.js';
+import { MeshUnsupportedError, getBackends, getCurrentStmt, setPendingMeshSolid, setPendingMeshTopology, } from '../../runtime-state.js';
+import { TopoRefError, resolveTopoRef } from '../../topology/naming/index.js';
+import { OpError } from './result-unwrap.js';
+import { buildMeshEdgeResolutionContext, buildMeshFaceResolutionContext } from '../topo-resolve.js';
+import { makePlane } from '../../geometry2d/bridge/plane.js';
+/**
+ * 取当前装配的网格后端；未装配即抛（宿主装配事实，不是运行时降级点）。
+ *
+ * @param opLabel - the op name (error messages).
+ * @returns the assembled mesh backend.
+ * @throws {MeshUnsupportedError} when no mesh backend is assembled in this host.
+ */
+export function meshBackendOrThrow(opLabel) {
+    const backend = getBackends().kernel.meshSolid;
+    if (!backend) {
+        throw new MeshUnsupportedError(`E_MESH_SOLID_UNSUPPORTED: ${opLabel}'s mesh path needs an assembled mesh backend — none is ` +
+            'available in this host', getCurrentStmt());
+    }
+    return backend;
+}
+/**
+ * 取网格实体的最小执行入口（只要内核 + 后端 + 句柄）。
+ *
+ * 两个失败面必须分开说，因为它们的原因完全不同：
+ * - 输入**不是**网格实体（裸网格 / BREP 实体）→ 该 op 的 mesh 路径只懂网格实体，
+ *   如实拒绝。裸网格意味着"加载它的时候没有装配网格内核"，与"规范化失败"是两回事。
+ * - 输入是网格实体但**没有装配网格后端** → 装配事实（宿主没提供），不是运行时降级点。
+ *
+ * @param input - the op's geometry input.
+ * @param opLabel - the op name (error messages).
+ * @returns the minimal mesh-solid entry for this input.
+ * @throws {MeshUnsupportedError} when the input is not a mesh solid or no backend is assembled.
+ */
+export function meshSolidBasicEntry(input, opLabel) {
+    const backend = meshBackendOrThrow(opLabel);
+    const solid = meshSolidOf(input);
+    if (solid === undefined) {
+        throw new MeshUnsupportedError(`E_MESH_SOLID_UNSUPPORTED: ${opLabel}'s mesh path needs a mesh solid input — ` +
+            'this input is a bare mesh (it was loaded without a mesh backend, so it has no approximate topology)', getCurrentStmt());
+    }
+    return { kernel: backend.kernel, backend, solid };
+}
+/**
+ * 取网格实体的执行入口（含边解析上下文）。
+ *
+ * 两个失败面必须分开说，因为它们的原因完全不同：
+ * - 输入**不是**网格实体（裸网格 / BREP 实体）→ 该 op 的 mesh 路径只懂网格实体，
+ *   如实拒绝。裸网格意味着"加载它的时候没有装配网格内核"，与"规范化失败"是两回事。
+ * - 输入是网格实体但**没有装配网格后端** → 装配事实（宿主没提供），不是运行时降级点。
+ *
+ * @param input - the op's geometry input.
+ * @param opLabel - the op name (error messages).
+ * @returns the mesh-solid entry for this input (with the edge resolution context).
+ * @throws {MeshUnsupportedError} when the input is not a mesh solid or no backend is assembled.
+ */
+export function meshSolidEntry(input, opLabel) {
+    const basic = meshSolidBasicEntry(input, opLabel);
+    const edgeContext = buildMeshEdgeResolutionContext(basic.kernel, input);
+    if (!edgeContext) {
+        throw new MeshUnsupportedError(`E_MESH_SOLID_UNSUPPORTED: ${opLabel} could not build an edge resolution context for the mesh solid ` +
+            '(the input carries a mesh solid handle but no readable slot)', getCurrentStmt());
+    }
+    return { ...basic, edgeContext };
+}
+/**
+ * 把一组边**选择器**解析成当前网格实体的边句柄。
+ *
+ * 两种选择器，两条解析路：
+ * - **序号**（1 起，与 `sketchOnFace` 的 `face` 序号同口径）：直接取自
+ *   `getSubShapes(solid,'edge')` 的枚举序，即宿主在近似拓扑 `edges` 数组里看到的
+ *   那个下标 + 1。这是**首选**——近似拓扑没有 role 层，几何（长度 / 中点）在等长边
+ *   上无法区分，序号是唯一无歧义的指认方式。
+ * - **`EdgeTopoRef`**：纯几何匹配（length / midpoint）。解析不到或无法区分时如实
+ *   抛错，绝不静默退回"拿序号硬取"。
+ *
+ * @param entry - the mesh-solid entry (provides the live edge table).
+ * @param refs - edge selectors: 1-based ordinals or TopoRefs captured from the topology.
+ * @param opLabel - the op name (error messages).
+ * @returns the resolved edge handles, in the same order as `refs`.
+ * @throws {OpError} `E_TOPO_NOT_FOUND` when a selector cannot be resolved.
+ */
+export function resolveMeshEdges(entry, refs, opLabel) {
+    return refs.map((ref, i) => {
+        if (typeof ref === 'number')
+            return meshEdgeOrdinal(entry, ref, i, opLabel);
+        const where = `edge[${i}] of the mesh solid (length=${ref.hint.length ?? '<none>'}, ` +
+            `midpoint=${ref.hint.midpoint ? ref.hint.midpoint.join(',') : '<none>'})`;
+        let resolved;
+        try {
+            resolved = resolveTopoRef(ref, entry.edgeContext);
+        }
+        catch (cause) {
+            throw new OpError(opLabel, 'E_TOPO_NOT_FOUND', `[api/${opLabel}] ${where} could not be resolved — approximate topology has no role layer, ` +
+                `so an edge is identified by geometry alone: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        }
+        if (resolved.handle === undefined) {
+            throw new OpError(opLabel, 'E_TOPO_NOT_FOUND', `[api/${opLabel}] ${where} resolved without an edge handle`);
+        }
+        return resolved.handle;
+    });
+}
+/**
+ * 序号 → 边句柄（1 起，枚举序与近似拓扑 `edges` 数组同序）。
+ *
+ * 越界不裁剪、不取模、不"就近"——序号是调用方从拓扑读数里抄来的，抄错了就是错的，
+ * 静默换一条边会让用户拿到一个不是他要的圆角。
+ *
+ * @param entry - the mesh-solid entry (provides the live edge table).
+ * @param ordinal - the 1-based edge ordinal.
+ * @param index - the selector's position in the request (error messages).
+ * @param opLabel - the op name (error messages).
+ * @returns the live edge handle.
+ * @throws {OpError} `E_TOPO_NOT_FOUND` when the ordinal is out of range.
+ */
+function meshEdgeOrdinal(entry, ordinal, index, opLabel) {
+    const edges = entry.kernel.getSubShapes(entry.solid, 'edge');
+    if (!Number.isInteger(ordinal) || ordinal < 1 || ordinal > edges.length) {
+        throw new OpError(opLabel, 'E_TOPO_NOT_FOUND', `[api/${opLabel}] edge[${index}] ordinal ${ordinal} out of range [1, ${edges.length}] ` +
+            'on the mesh solid');
+    }
+    return edges[ordinal - 1];
+}
+/**
+ * 面选择器数组 → 面句柄数组（`shell` 的 `openFaces` 用；序号或 `FaceTopoRef` 都收）。
+ *
+ * @param kernel - the mesh backend's L1 kernel.
+ * @param on - the mesh-solid shape hosting the faces.
+ * @param selectors - 1-based face ordinals or FaceTopoRefs.
+ * @param opLabel - the op name (error messages).
+ * @returns the live face handles, in the same order as `selectors`.
+ * @throws {OpError} when a selector cannot be resolved.
+ */
+export function resolveMeshFaces(kernel, on, selectors, opLabel) {
+    return selectors.map((selector) => resolveMeshFaceHandle(kernel, on, selector, opLabel));
+}
+/**
+ * 把内核产出的**新网格实体句柄**封装成 op 产物。
+ *
+ * 一次三角化同时喂显示与拓扑（规则 1），并把句柄与近似拓扑登记到 pending 通道，
+ * 由引擎在语句执行后收编（同 `load`）。
+ *
+ * @param entry - the mesh-solid entry (backend for tessellation/topology/release).
+ * @param solid - the new mesh solid handle produced by the kernel call.
+ * @returns the product Shape carrying the new handle and its tessellation.
+ */
+export function meshSolidProduct(entry, solid) {
+    return meshSolidProductWithBackend(entry.backend, solid);
+}
+/**
+ * 同上，但直接收后端（产物输入不是网格实体时用——如 `extrude` 的输入是一张面）。
+ *
+ * @param backend - the mesh backend (tessellation / topology / release).
+ * @param solid - the new mesh solid handle produced by the kernel call.
+ * @returns the product Shape carrying the new handle and its tessellation.
+ */
+export function meshSolidProductWithBackend(backend, solid) {
+    const result = describeMeshSolid(backend, solid);
+    const part = getCurrentStmt()?.outputs[0];
+    if (part) {
+        setPendingMeshSolid(part, solid);
+        setPendingMeshTopology(part, backend.buildTopologyData(result));
+    }
+    return fromMeshSolid({ positions: result.mesh.positions, indices: result.mesh.indices }, { meshSolid: solid });
+}
+/**
+ * 阵列 / 镜像族产物：把若干**自造副本**融成一个网格零件，并把副本句柄释放掉。
+ *
+ * 释放口径与 BREP 侧完全一致（`pattern.ts` 的 `finally { for (const c of raw) kernel.release(c) }`）：
+ * - 释放的是**本次调用新建的副本**——它们是中间量，融合后无人再引用；
+ * - **不释放输入句柄**（`a` 在 `b = linearPattern(a)` 之后仍必须可用）。
+ *
+ * 副本之间通常是分离的（有间距的阵列），故 fuseAll 得到的是一体多壳的实体——与
+ * BREP 路径 fuseAll 分离副本的结局同形，不是"凑成一张皮"。
+ *
+ * 副本的**生成**也在 try 内：中途失败时已建出的副本同样会被释放（否则每个失败
+ * 调用都漏一批句柄）。
+ *
+ * @param entry - the mesh-solid entry (kernel + backend).
+ * @param opLabel - the op name (error messages).
+ * @param code - the op-level error code for kernel failures.
+ * @param makeCopies - creates the copies to fuse (called once, inside the guard).
+ * @returns the fused mesh solid as a new mesh part.
+ * @throws {OpError} with `code` when the kernel refuses a copy or the fusion.
+ */
+export function meshPatternProduct(entry, opLabel, code, makeCopies) {
+    let copies = [];
+    try {
+        copies = makeCopies();
+        if (copies.length === 0) {
+            throw new OpError(opLabel, code, `[api/${opLabel}] the kernel produced no copies`);
+        }
+        const result = entry.kernel.fuseAll(copies);
+        return meshSolidProductWithBackend(entry.backend, result);
+    }
+    catch (cause) {
+        if (cause instanceof OpError)
+            throw cause;
+        throw meshKernelFailure(opLabel, code, `${opLabel}: fusing ${copies.length} mesh copy(ies)`, cause);
+    }
+    finally {
+        for (const c of copies)
+            entry.backend.release(c);
+    }
+}
+/**
+ * 取网格链面的执行入口（`sketchOnFace` 网格分支的输入门）。
+ *
+ * 与 `meshSolidEntry` 的两个失败面同构：输入没有网格链面身份 → 如实拒绝（它可能是
+ * 网格实体、BREP 面或裸网格，三种都不是这里要的东西）；宿主没装配网格后端 → 装配事实。
+ *
+ * @param input - the op's geometry input (must be a mesh-chain face).
+ * @param opLabel - the op name (error messages).
+ * @returns the mesh-face entry for this input.
+ * @throws {MeshUnsupportedError} when the input is not a mesh-chain face or no backend is assembled.
+ */
+export function meshFaceEntry(input, opLabel) {
+    const backend = meshBackendOrThrow(opLabel);
+    const face = meshFaceOf(input);
+    if (face === undefined) {
+        throw new MeshUnsupportedError(`E_MESH_SOLID_UNSUPPORTED: ${opLabel}'s mesh path needs a mesh-chain face input — ` +
+            'this input carries no mesh-chain face handle (build one with cad.sketchOnFace on a mesh solid)', getCurrentStmt());
+    }
+    return { kernel: backend.kernel, backend, face };
+}
+/**
+ * 把网格链面上的面选择器解析成活句柄（序号直接取；`FaceTopoRef` 走纯几何解析）。
+ *
+ * 网格零件没有 role 层，故与 `resolveMeshEdges` 同纪律：解析不到或无法区分时如实抛错，
+ * 绝不静默按序号硬取一张面。**同尺寸的平行面（立方体顶面/底面）在几何上不可区分**，
+ * 这种情形会以 `E_TOPO_AMBIGUOUS` 失败——调用方应改用序号。
+ *
+ * @param kernel - the mesh backend's L1 kernel.
+ * @param on - the mesh-solid shape hosting the face.
+ * @param selector - a 1-based face ordinal or a `FaceTopoRef`.
+ * @param opLabel - the op name (error messages).
+ * @returns the live face handle.
+ * @throws {OpError} `E_MESH_SOLID_UNSUPPORTED` / `E_TOPO_NOT_FOUND` / `E_TOPO_AMBIGUOUS`.
+ */
+export function resolveMeshFaceHandle(kernel, on, selector, opLabel) {
+    const solid = meshSolidOf(on);
+    if (solid === undefined) {
+        throw new MeshUnsupportedError(`E_MESH_SOLID_UNSUPPORTED: ${opLabel}'s mesh path needs a mesh solid host — ` +
+            'this input is not a mesh solid', getCurrentStmt());
+    }
+    const faces = kernel.getSubShapes(solid, 'face');
+    if (typeof selector === 'number') {
+        if (!Number.isInteger(selector) || selector < 1 || selector > faces.length) {
+            throw new OpError(opLabel, 'E_TOPO_NOT_FOUND', `[api/${opLabel}] face ordinal ${selector} out of range [1, ${faces.length}] on the mesh solid`);
+        }
+        return faces[selector - 1];
+    }
+    const ctx = buildMeshFaceResolutionContext(kernel, on);
+    if (!ctx) {
+        throw new OpError(opLabel, 'E_TOPO_NOT_FOUND', `[api/${opLabel}] input has no mesh naming context`);
+    }
+    let resolved;
+    try {
+        resolved = resolveTopoRef(selector, ctx);
+    }
+    catch (cause) {
+        const code = cause instanceof TopoRefError && cause.code === 'E_TOPO_AMBIGUOUS' ? 'E_TOPO_AMBIGUOUS' : 'E_TOPO_NOT_FOUND';
+        throw new OpError(opLabel, code, `[api/${opLabel}] mesh face ref could not be resolved — approximate topology has no role layer, ` +
+            `so a face is identified by geometry alone (normal/center/area; use an ordinal when two faces are congruent): ` +
+            `${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+    if (resolved.handle === undefined) {
+        throw new OpError(opLabel, 'E_TOPO_NOT_FOUND', `[api/${opLabel}] mesh face ref resolved to no live handle`);
+    }
+    return resolved.handle;
+}
+/**
+ * 从一张网格链面取它的支撑平面（草图平面数据，方案 §4 Phase 3-1）。
+ *
+ * 两个数据源，各有各的理由：
+ * - **平面原点**取面的包围盒中心，不取 `surfaceCenterOfMass`：后者在 brepkit 上是
+ *   "UV 域中点求值"的近似（内核没有 per-face 质心 API），对平面求的域中点是
+ *   `getSurfaceDomain` 的中点；而平面域是 ±1e6 的**无限域**，其中点只是曲面参数原点，
+ *   可能位于面**之外**。包围盒中心是面自己的几何中心，草图从它铺出去必然落在面上。
+ * - **法向**取 UV 域中点的 `surfaceNormal`——L1 契约面上的中立方法（brepkit 侧映射
+ *   `evaluateSurfaceNormal`），不直接调内核方言的 `getAnalyticSurfaceParams`。
+ *
+ * @param kernel - the mesh backend's L1 kernel.
+ * @param face - the live face handle.
+ * @returns the face's supporting plane frame (2D origin = the face's bbox centre).
+ */
+export function meshFacePlane(kernel, face) {
+    const uv = kernel.uvBounds(face);
+    const u = (uv.uMin + uv.uMax) / 2;
+    const v = (uv.vMin + uv.vMax) / 2;
+    const n = kernel.surfaceNormal(face, u, v);
+    const bb = kernel.getBoundingBox(face);
+    return makePlane({ x: (bb.xmin + bb.xmax) / 2, y: (bb.ymin + bb.ymax) / 2, z: (bb.zmin + bb.zmax) / 2 }, { x: n.x, y: n.y, z: n.z });
+}
+/**
+ * 把内核算出的网格链面句柄封装成 op 产物。
+ *
+ * 与 `meshSolidProductWithBackend` 的区别是**不登记** `MeshSolidRegistry` 与近似拓扑：
+ * 面不是零件，没有自己的注册表条目，下游也不需要"面的近似拓扑"（它自己就是拓扑的一部分）。
+ * 显示载荷取面自身的三角化（`meshShape` 按句柄类型分发到 face 分支）。
+ *
+ * @param backend - the mesh backend (tessellation).
+ * @param face - the new face handle produced by the kernel call.
+ * @returns the product Shape carrying the face handle and its tessellation.
+ */
+export function meshFaceProduct(backend, face) {
+    const mesh = backend.kernel.meshShape(face);
+    return fromMeshFace({ positions: new Float32Array(mesh.positions), indices: new Uint32Array(mesh.indices) }, { meshFace: face });
+}
+/**
+ * 内核原生错误 → 带 op 名与输入几何的 OpError（几何失败必须带上下文，不裸抛内核串）。
+ *
+ * @param opLabel - the op name.
+ * @param code - the op-level error code.
+ * @param context - a short human description of what was being attempted.
+ * @param cause - the kernel's own error.
+ * @returns the wrapped op error.
+ */
+export function meshKernelFailure(opLabel, code, context, cause) {
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    return new OpError(opLabel, code, `[api/${opLabel}] ${context} — the mesh kernel refused: ${msg}`, { cause });
+}
+//# sourceMappingURL=mesh-solid-op.js.map

package/dist/api/internal/mesh-solid-op.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-solid-op.js","sourceRoot":"","sources":["../../../src/api/internal/mesh-solid-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,EACL,iBAAiB,GAGlB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAClF,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,YAAY,EAAE,cAAc,EAA8D,MAAM,uBAAuB,CAAA;AAChI,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,8BAA8B,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAA;AAChG,OAAO,EAAE,SAAS,EAAc,MAAM,+BAA+B,CAAA;AAwBrE;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,SAAyC,CAAA;IAC9E,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,yDAAyD;YAC7F,wBAAwB,EACxB,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAY,EAAE,OAAe;IAC/D,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAC3C,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAA2B,CAAA;IAC1D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,0CAA0C;YAC9E,qGAAqG,EACrG,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;AACnD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,OAAe;IAC1D,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IACjD,MAAM,WAAW,GAAG,8BAA8B,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IACvE,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,iEAAiE;YACrG,8DAA8D,EAC9D,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,CAAA;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAqB,EACrB,IAAuC,EACvC,OAAe;IAEf,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACzB,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,CAAC,CAAA;QAC3E,MAAM,KAAK,GACT,QAAQ,CAAC,+BAA+B,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,QAAQ,IAAI;YACvE,YAAY,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAA;QAC3E,IAAI,QAA8B,CAAA;QAClC,IAAI,CAAC;YACH,QAAQ,GAAG,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;QACnD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,OAAO,CACf,OAAO,EACP,kBAAkB,EAClB,QAAQ,OAAO,KAAK,KAAK,mEAAmE;gBAC5F,+CAA+C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACvG,EAAE,KAAK,EAAE,CACV,CAAA;QACH,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,OAAO,CACf,OAAO,EACP,kBAAkB,EAClB,QAAQ,OAAO,KAAK,KAAK,kCAAkC,CAC5D,CAAA;QACH,CAAC;QACD,OAAO,QAAQ,CAAC,MAAoB,CAAA;IACtC,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,eAAe,CACtB,KAAqB,EACrB,OAAe,EACf,KAAa,EACb,OAAe;IAEf,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC5D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACxE,MAAM,IAAI,OAAO,CACf,OAAO,EACP,kBAAkB,EAClB,QAAQ,OAAO,UAAU,KAAK,aAAa,OAAO,qBAAqB,KAAK,CAAC,MAAM,IAAI;YACvF,mBAAmB,CACpB,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,GAAG,CAAC,CAAe,CAAA;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAqB,EACrB,EAAS,EACT,SAA4C,EAC5C,OAAe;IAEf,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,qBAAqB,CAAC,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAA;AAC1F,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAoC,EAAE,KAAiB;IACtF,OAAO,2BAA2B,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;AAC1D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAyB,EAAE,KAAiB;IACtF,MAAM,MAAM,GAAoB,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACjE,MAAM,IAAI,GAAG,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACzC,IAAI,IAAI,EAAE,CAAC;QACT,mBAAmB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAChC,sBAAsB,CAAC,IAAI,EAAE,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAA;IACjE,CAAC;IACD,OAAO,aAAa,CAClB,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,EAClE,EAAE,SAAS,EAAE,KAAK,EAAE,CACrB,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAqB,EACrB,OAAe,EACf,IAAY,EACZ,UAA8B;IAE9B,IAAI,MAAM,GAAiB,EAAE,CAAA;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,UAAU,EAAE,CAAA;QACrB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,OAAO,iCAAiC,CAAC,CAAA;QACpF,CAAC;QACD,MAAM,MAAM,GAAe,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACvD,OAAO,2BAA2B,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IAC3D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,OAAO;YAAE,MAAM,KAAK,CAAA;QACzC,MAAM,iBAAiB,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,YAAY,MAAM,CAAC,MAAM,iBAAiB,EAAE,KAAK,CAAC,CAAA;IACrG,CAAC;YAAS,CAAC;QACT,KAAK,MAAM,CAAC,IAAI,MAAM;YAAE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAClD,CAAC;AACH,CAAC;AAWD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAAY,EAAE,OAAe;IACzD,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAC3C,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAA2B,CAAA;IACxD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,+CAA+C;YACnF,gGAAgG,EAChG,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAClD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAqB,EACrB,EAAS,EACT,QAA8B,EAC9B,OAAe;IAEf,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAA2B,CAAA;IACvD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,yCAAyC;YAC7E,gCAAgC,EAChC,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAChD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC3E,MAAM,IAAI,OAAO,CACf,OAAO,EACP,kBAAkB,EAClB,QAAQ,OAAO,kBAAkB,QAAQ,qBAAqB,KAAK,CAAC,MAAM,qBAAqB,CAChG,CAAA;QACH,CAAC;QACD,OAAO,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAe,CAAA;IAC1C,CAAC;IACD,MAAM,GAAG,GAAG,8BAA8B,CAAC,MAAM,EAAE,EAAY,CAAC,CAAA;IAChE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,OAAO,oCAAoC,CAAC,CAAA;IACrG,CAAC;IACD,IAAI,QAA8B,CAAA;IAClC,IAAI,CAAC;QACH,QAAQ,GAAG,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,GAAG,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,kBAAkB,CAAA;QACzH,MAAM,IAAI,OAAO,CACf,OAAO,EACP,IAAI,EACJ,QAAQ,OAAO,kFAAkF;YACjG,+GAA+G;YAC/G,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAC3D,EAAE,KAAK,EAAE,CACV,CAAA;IACH,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,OAAO,4CAA4C,CAAC,CAAA;IAC7G,CAAC;IACD,OAAO,QAAQ,CAAC,MAAoB,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqB,EAAE,IAAgB;IACnE,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAChC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACjC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACjC,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAC1C,MAAM,EAAE,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;IACtC,OAAO,SAAS,CACd,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EACtF,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAC3B,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,OAAyB,EAAE,IAAgB;IACzE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAC3C,OAAO,YAAY,CACjB,EAAE,SAAS,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EACvF,EAAE,QAAQ,EAAE,IAAI,EAAE,CACnB,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,IAAY,EACZ,OAAe,EACf,KAAc;IAEd,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAClE,OAAO,IAAI,OAAO,CAChB,OAAO,EACP,IAAI,EACJ,QAAQ,OAAO,KAAK,OAAO,+BAA+B,GAAG,EAAE,EAC/D,EAAE,KAAK,EAAE,CACV,CAAA;AACH,CAAC","sourcesContent":["/**\n * mesh-solid-op — 网格 op 的「三明治」共享实现（方案 2026-10-01 §3.5）\n *\n * 每个网格 op 的实现体都是同一个形状，本模块只把这三步抽出来，让 op 侧只剩\"调哪个\n * 内核方法\"这一件事：\n *\n * ```\n * MeshData ──► meshSolid 句柄（从 Shape 槽取，**不重复导入**）\n *               │\n *               ├─ 内核调用（fillet / chamfer / fuse / cut / intersect / …）\n *               │\n *               └─ meshShape(新句柄) ──► MeshData（显示 mesh 与近似拓扑**同一份**）\n * ```\n *\n * 三条不可让步的口径：\n *\n * 1. **显示 mesh = 新实体的三角化**，不是输入的顶点数组。规则 1：拓扑 faceRuns\n *    索引的三角形必须就是用户看到的三角形——照抄输入数组会让两者错位。\n * 2. **新句柄必须写回**（Shape 槽 + 运行时注册表 + 近似拓扑）。不写回 = 下游 op\n *    拿不到句柄、宿主选中不到面；不登记注册表 = 句柄无人释放。\n * 3. **旧句柄不由本模块释放**。BREP 侧同构（`filletBrep` 也不释放输入句柄）：\n *    句柄生命周期归链（注册表 / releasePartCaches），op 只管\"取一个、交一个\"。\n *    这里\"顺手 release 输入\"会打断 `b = fillet(a)` 之后仍然可用的 `a`。\n *\n * op 拿不到 `CadRuntime` 实例，故句柄与拓扑经 **pending 通道**登记\n * （与 `load` 的 `setPendingMeshSolid` / `setPendingMeshTopology` 同模式），\n * 由引擎在语句执行后收编——收编时会核对存活 ctx 变量仍携带**这个**句柄，防顶替。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { BrepHandle } from '../../brep/engine/types'\nimport {\n  describeMeshSolid,\n  type MeshSolidBackend,\n  type MeshSolidResult,\n} from '../../brep/mesh-solid'\nimport { fromMeshFace, fromMeshSolid, meshFaceOf, meshSolidOf } from '../../shape'\nimport {\n  MeshUnsupportedError,\n  getBackends,\n  getCurrentStmt,\n  setPendingMeshSolid,\n  setPendingMeshTopology,\n} from '../../runtime-state'\nimport { TopoRefError, resolveTopoRef, type EdgeTopoRef, type FaceTopoRef, type ResolutionContext } from '../../topology/naming'\nimport { OpError } from './result-unwrap'\nimport { buildMeshEdgeResolutionContext, buildMeshFaceResolutionContext } from '../topo-resolve'\nimport { makePlane, type Plane } from '../../geometry2d/bridge/plane'\n\n/**\n * 网格 op 的最小执行入口：内核 + 后端 + 输入句柄（**不带**解析上下文）。\n *\n * 变换 / 抽壳 / 阵列这类\"整体作用于实体\"的 op 不需要解析上下文（它们按序号或\n * 几何选面/选边，且各自的选面逻辑自带上下文构建）——对它们建一遍全边表 + 逐边\n * 几何 hint，是纯粹的浪费（大网格上是 O(边数) 次内核调用）。\n */\nexport interface MeshSolidBasic {\n  /** 网格后端的 L1 契约面（几何操作走它，op 不碰内核私有方言）。 */\n  readonly kernel: BrepEngineApi\n  /** 网格后端（三角化 / 近似拓扑 / 释放）。 */\n  readonly backend: MeshSolidBackend\n  /** 输入的网格实体句柄。 */\n  readonly solid: BrepHandle\n}\n\n/** 网格 op 的执行入口：最小入口 + 边解析上下文。 */\nexport interface MeshSolidEntry extends MeshSolidBasic {\n  /** 边解析上下文（无 role 层 → 纯几何匹配，见 `buildMeshEdgeResolutionContext`）。 */\n  readonly edgeContext: ResolutionContext\n}\n\n/**\n * 取当前装配的网格后端；未装配即抛（宿主装配事实，不是运行时降级点）。\n *\n * @param opLabel - the op name (error messages).\n * @returns the assembled mesh backend.\n * @throws {MeshUnsupportedError} when no mesh backend is assembled in this host.\n */\nexport function meshBackendOrThrow(opLabel: string): MeshSolidBackend {\n  const backend = getBackends().kernel.meshSolid as MeshSolidBackend | undefined\n  if (!backend) {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel}'s mesh path needs an assembled mesh backend — none is ` +\n      'available in this host',\n      getCurrentStmt(),\n    )\n  }\n  return backend\n}\n\n/**\n * 取网格实体的最小执行入口（只要内核 + 后端 + 句柄）。\n *\n * 两个失败面必须分开说，因为它们的原因完全不同：\n * - 输入**不是**网格实体（裸网格 / BREP 实体）→ 该 op 的 mesh 路径只懂网格实体，\n *   如实拒绝。裸网格意味着\"加载它的时候没有装配网格内核\"，与\"规范化失败\"是两回事。\n * - 输入是网格实体但**没有装配网格后端** → 装配事实（宿主没提供），不是运行时降级点。\n *\n * @param input - the op's geometry input.\n * @param opLabel - the op name (error messages).\n * @returns the minimal mesh-solid entry for this input.\n * @throws {MeshUnsupportedError} when the input is not a mesh solid or no backend is assembled.\n */\nexport function meshSolidBasicEntry(input: Shape, opLabel: string): MeshSolidBasic {\n  const backend = meshBackendOrThrow(opLabel)\n  const solid = meshSolidOf(input) as BrepHandle | undefined\n  if (solid === undefined) {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel}'s mesh path needs a mesh solid input — ` +\n      'this input is a bare mesh (it was loaded without a mesh backend, so it has no approximate topology)',\n      getCurrentStmt(),\n    )\n  }\n  return { kernel: backend.kernel, backend, solid }\n}\n\n/**\n * 取网格实体的执行入口（含边解析上下文）。\n *\n * 两个失败面必须分开说，因为它们的原因完全不同：\n * - 输入**不是**网格实体（裸网格 / BREP 实体）→ 该 op 的 mesh 路径只懂网格实体，\n *   如实拒绝。裸网格意味着\"加载它的时候没有装配网格内核\"，与\"规范化失败\"是两回事。\n * - 输入是网格实体但**没有装配网格后端** → 装配事实（宿主没提供），不是运行时降级点。\n *\n * @param input - the op's geometry input.\n * @param opLabel - the op name (error messages).\n * @returns the mesh-solid entry for this input (with the edge resolution context).\n * @throws {MeshUnsupportedError} when the input is not a mesh solid or no backend is assembled.\n */\nexport function meshSolidEntry(input: Shape, opLabel: string): MeshSolidEntry {\n  const basic = meshSolidBasicEntry(input, opLabel)\n  const edgeContext = buildMeshEdgeResolutionContext(basic.kernel, input)\n  if (!edgeContext) {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} could not build an edge resolution context for the mesh solid ` +\n      '(the input carries a mesh solid handle but no readable slot)',\n      getCurrentStmt(),\n    )\n  }\n  return { ...basic, edgeContext }\n}\n\n/**\n * 把一组边**选择器**解析成当前网格实体的边句柄。\n *\n * 两种选择器，两条解析路：\n * - **序号**（1 起，与 `sketchOnFace` 的 `face` 序号同口径）：直接取自\n *   `getSubShapes(solid,'edge')` 的枚举序，即宿主在近似拓扑 `edges` 数组里看到的\n *   那个下标 + 1。这是**首选**——近似拓扑没有 role 层，几何（长度 / 中点）在等长边\n *   上无法区分，序号是唯一无歧义的指认方式。\n * - **`EdgeTopoRef`**：纯几何匹配（length / midpoint）。解析不到或无法区分时如实\n *   抛错，绝不静默退回\"拿序号硬取\"。\n *\n * @param entry - the mesh-solid entry (provides the live edge table).\n * @param refs - edge selectors: 1-based ordinals or TopoRefs captured from the topology.\n * @param opLabel - the op name (error messages).\n * @returns the resolved edge handles, in the same order as `refs`.\n * @throws {OpError} `E_TOPO_NOT_FOUND` when a selector cannot be resolved.\n */\nexport function resolveMeshEdges(\n  entry: MeshSolidEntry,\n  refs: readonly (number | EdgeTopoRef)[],\n  opLabel: string,\n): BrepHandle[] {\n  return refs.map((ref, i) => {\n    if (typeof ref === 'number') return meshEdgeOrdinal(entry, ref, i, opLabel)\n    const where =\n      `edge[${i}] of the mesh solid (length=${ref.hint.length ?? '<none>'}, ` +\n      `midpoint=${ref.hint.midpoint ? ref.hint.midpoint.join(',') : '<none>'})`\n    let resolved: { handle?: unknown }\n    try {\n      resolved = resolveTopoRef(ref, entry.edgeContext)\n    } catch (cause) {\n      throw new OpError(\n        opLabel,\n        'E_TOPO_NOT_FOUND',\n        `[api/${opLabel}] ${where} could not be resolved — approximate topology has no role layer, ` +\n        `so an edge is identified by geometry alone: ${cause instanceof Error ? cause.message : String(cause)}`,\n        { cause },\n      )\n    }\n    if (resolved.handle === undefined) {\n      throw new OpError(\n        opLabel,\n        'E_TOPO_NOT_FOUND',\n        `[api/${opLabel}] ${where} resolved without an edge handle`,\n      )\n    }\n    return resolved.handle as BrepHandle\n  })\n}\n\n/**\n * 序号 → 边句柄（1 起，枚举序与近似拓扑 `edges` 数组同序）。\n *\n * 越界不裁剪、不取模、不\"就近\"——序号是调用方从拓扑读数里抄来的，抄错了就是错的，\n * 静默换一条边会让用户拿到一个不是他要的圆角。\n *\n * @param entry - the mesh-solid entry (provides the live edge table).\n * @param ordinal - the 1-based edge ordinal.\n * @param index - the selector's position in the request (error messages).\n * @param opLabel - the op name (error messages).\n * @returns the live edge handle.\n * @throws {OpError} `E_TOPO_NOT_FOUND` when the ordinal is out of range.\n */\nfunction meshEdgeOrdinal(\n  entry: MeshSolidEntry,\n  ordinal: number,\n  index: number,\n  opLabel: string,\n): BrepHandle {\n  const edges = entry.kernel.getSubShapes(entry.solid, 'edge')\n  if (!Number.isInteger(ordinal) || ordinal < 1 || ordinal > edges.length) {\n    throw new OpError(\n      opLabel,\n      'E_TOPO_NOT_FOUND',\n      `[api/${opLabel}] edge[${index}] ordinal ${ordinal} out of range [1, ${edges.length}] ` +\n      'on the mesh solid',\n    )\n  }\n  return edges[ordinal - 1] as BrepHandle\n}\n\n/**\n * 面选择器数组 → 面句柄数组（`shell` 的 `openFaces` 用；序号或 `FaceTopoRef` 都收）。\n *\n * @param kernel - the mesh backend's L1 kernel.\n * @param on - the mesh-solid shape hosting the faces.\n * @param selectors - 1-based face ordinals or FaceTopoRefs.\n * @param opLabel - the op name (error messages).\n * @returns the live face handles, in the same order as `selectors`.\n * @throws {OpError} when a selector cannot be resolved.\n */\nexport function resolveMeshFaces(\n  kernel: BrepEngineApi,\n  on: Shape,\n  selectors: readonly (number | FaceTopoRef)[],\n  opLabel: string,\n): BrepHandle[] {\n  return selectors.map((selector) => resolveMeshFaceHandle(kernel, on, selector, opLabel))\n}\n\n/**\n * 把内核产出的**新网格实体句柄**封装成 op 产物。\n *\n * 一次三角化同时喂显示与拓扑（规则 1），并把句柄与近似拓扑登记到 pending 通道，\n * 由引擎在语句执行后收编（同 `load`）。\n *\n * @param entry - the mesh-solid entry (backend for tessellation/topology/release).\n * @param solid - the new mesh solid handle produced by the kernel call.\n * @returns the product Shape carrying the new handle and its tessellation.\n */\nexport function meshSolidProduct(entry: { backend: MeshSolidBackend }, solid: BrepHandle): Shape {\n  return meshSolidProductWithBackend(entry.backend, solid)\n}\n\n/**\n * 同上，但直接收后端（产物输入不是网格实体时用——如 `extrude` 的输入是一张面）。\n *\n * @param backend - the mesh backend (tessellation / topology / release).\n * @param solid - the new mesh solid handle produced by the kernel call.\n * @returns the product Shape carrying the new handle and its tessellation.\n */\nexport function meshSolidProductWithBackend(backend: MeshSolidBackend, solid: BrepHandle): Shape {\n  const result: MeshSolidResult = describeMeshSolid(backend, solid)\n  const part = getCurrentStmt()?.outputs[0]\n  if (part) {\n    setPendingMeshSolid(part, solid)\n    setPendingMeshTopology(part, backend.buildTopologyData(result))\n  }\n  return fromMeshSolid(\n    { positions: result.mesh.positions, indices: result.mesh.indices },\n    { meshSolid: solid },\n  )\n}\n\n/**\n * 阵列 / 镜像族产物：把若干**自造副本**融成一个网格零件，并把副本句柄释放掉。\n *\n * 释放口径与 BREP 侧完全一致（`pattern.ts` 的 `finally { for (const c of raw) kernel.release(c) }`）：\n * - 释放的是**本次调用新建的副本**——它们是中间量，融合后无人再引用；\n * - **不释放输入句柄**（`a` 在 `b = linearPattern(a)` 之后仍必须可用）。\n *\n * 副本之间通常是分离的（有间距的阵列），故 fuseAll 得到的是一体多壳的实体——与\n * BREP 路径 fuseAll 分离副本的结局同形，不是\"凑成一张皮\"。\n *\n * 副本的**生成**也在 try 内：中途失败时已建出的副本同样会被释放（否则每个失败\n * 调用都漏一批句柄）。\n *\n * @param entry - the mesh-solid entry (kernel + backend).\n * @param opLabel - the op name (error messages).\n * @param code - the op-level error code for kernel failures.\n * @param makeCopies - creates the copies to fuse (called once, inside the guard).\n * @returns the fused mesh solid as a new mesh part.\n * @throws {OpError} with `code` when the kernel refuses a copy or the fusion.\n */\nexport function meshPatternProduct(\n  entry: MeshSolidBasic,\n  opLabel: string,\n  code: string,\n  makeCopies: () => BrepHandle[],\n): Shape {\n  let copies: BrepHandle[] = []\n  try {\n    copies = makeCopies()\n    if (copies.length === 0) {\n      throw new OpError(opLabel, code, `[api/${opLabel}] the kernel produced no copies`)\n    }\n    const result: BrepHandle = entry.kernel.fuseAll(copies)\n    return meshSolidProductWithBackend(entry.backend, result)\n  } catch (cause) {\n    if (cause instanceof OpError) throw cause\n    throw meshKernelFailure(opLabel, code, `${opLabel}: fusing ${copies.length} mesh copy(ies)`, cause)\n  } finally {\n    for (const c of copies) entry.backend.release(c)\n  }\n}\n\n/** 网格链**面**的执行入口：内核 + 后端 + 面句柄（`sketchOnFace` 的网格分支用）。 */export interface MeshFaceEntry {\n  /** 网格后端的 L1 契约面。 */\n  readonly kernel: BrepEngineApi\n  /** 网格后端（三角化 / 释放）。 */\n  readonly backend: MeshSolidBackend\n  /** 网格链面句柄。 */\n  readonly face: BrepHandle\n}\n\n/**\n * 取网格链面的执行入口（`sketchOnFace` 网格分支的输入门）。\n *\n * 与 `meshSolidEntry` 的两个失败面同构：输入没有网格链面身份 → 如实拒绝（它可能是\n * 网格实体、BREP 面或裸网格，三种都不是这里要的东西）；宿主没装配网格后端 → 装配事实。\n *\n * @param input - the op's geometry input (must be a mesh-chain face).\n * @param opLabel - the op name (error messages).\n * @returns the mesh-face entry for this input.\n * @throws {MeshUnsupportedError} when the input is not a mesh-chain face or no backend is assembled.\n */\nexport function meshFaceEntry(input: Shape, opLabel: string): MeshFaceEntry {\n  const backend = meshBackendOrThrow(opLabel)\n  const face = meshFaceOf(input) as BrepHandle | undefined\n  if (face === undefined) {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel}'s mesh path needs a mesh-chain face input — ` +\n      'this input carries no mesh-chain face handle (build one with cad.sketchOnFace on a mesh solid)',\n      getCurrentStmt(),\n    )\n  }\n  return { kernel: backend.kernel, backend, face }\n}\n\n/**\n * 把网格链面上的面选择器解析成活句柄（序号直接取；`FaceTopoRef` 走纯几何解析）。\n *\n * 网格零件没有 role 层，故与 `resolveMeshEdges` 同纪律：解析不到或无法区分时如实抛错，\n * 绝不静默按序号硬取一张面。**同尺寸的平行面（立方体顶面/底面）在几何上不可区分**，\n * 这种情形会以 `E_TOPO_AMBIGUOUS` 失败——调用方应改用序号。\n *\n * @param kernel - the mesh backend's L1 kernel.\n * @param on - the mesh-solid shape hosting the face.\n * @param selector - a 1-based face ordinal or a `FaceTopoRef`.\n * @param opLabel - the op name (error messages).\n * @returns the live face handle.\n * @throws {OpError} `E_MESH_SOLID_UNSUPPORTED` / `E_TOPO_NOT_FOUND` / `E_TOPO_AMBIGUOUS`.\n */\nexport function resolveMeshFaceHandle(\n  kernel: BrepEngineApi,\n  on: Shape,\n  selector: number | FaceTopoRef,\n  opLabel: string,\n): BrepHandle {\n  const solid = meshSolidOf(on) as BrepHandle | undefined\n  if (solid === undefined) {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel}'s mesh path needs a mesh solid host — ` +\n      'this input is not a mesh solid',\n      getCurrentStmt(),\n    )\n  }\n  const faces = kernel.getSubShapes(solid, 'face')\n  if (typeof selector === 'number') {\n    if (!Number.isInteger(selector) || selector < 1 || selector > faces.length) {\n      throw new OpError(\n        opLabel,\n        'E_TOPO_NOT_FOUND',\n        `[api/${opLabel}] face ordinal ${selector} out of range [1, ${faces.length}] on the mesh solid`,\n      )\n    }\n    return faces[selector - 1] as BrepHandle\n  }\n  const ctx = buildMeshFaceResolutionContext(kernel, on as object)\n  if (!ctx) {\n    throw new OpError(opLabel, 'E_TOPO_NOT_FOUND', `[api/${opLabel}] input has no mesh naming context`)\n  }\n  let resolved: { handle?: unknown }\n  try {\n    resolved = resolveTopoRef(selector, ctx)\n  } catch (cause) {\n    const code = cause instanceof TopoRefError && cause.code === 'E_TOPO_AMBIGUOUS' ? 'E_TOPO_AMBIGUOUS' : 'E_TOPO_NOT_FOUND'\n    throw new OpError(\n      opLabel,\n      code,\n      `[api/${opLabel}] mesh face ref could not be resolved — approximate topology has no role layer, ` +\n      `so a face is identified by geometry alone (normal/center/area; use an ordinal when two faces are congruent): ` +\n      `${cause instanceof Error ? cause.message : String(cause)}`,\n      { cause },\n    )\n  }\n  if (resolved.handle === undefined) {\n    throw new OpError(opLabel, 'E_TOPO_NOT_FOUND', `[api/${opLabel}] mesh face ref resolved to no live handle`)\n  }\n  return resolved.handle as BrepHandle\n}\n\n/**\n * 从一张网格链面取它的支撑平面（草图平面数据，方案 §4 Phase 3-1）。\n *\n * 两个数据源，各有各的理由：\n * - **平面原点**取面的包围盒中心，不取 `surfaceCenterOfMass`：后者在 brepkit 上是\n *   \"UV 域中点求值\"的近似（内核没有 per-face 质心 API），对平面求的域中点是\n *   `getSurfaceDomain` 的中点；而平面域是 ±1e6 的**无限域**，其中点只是曲面参数原点，\n *   可能位于面**之外**。包围盒中心是面自己的几何中心，草图从它铺出去必然落在面上。\n * - **法向**取 UV 域中点的 `surfaceNormal`——L1 契约面上的中立方法（brepkit 侧映射\n *   `evaluateSurfaceNormal`），不直接调内核方言的 `getAnalyticSurfaceParams`。\n *\n * @param kernel - the mesh backend's L1 kernel.\n * @param face - the live face handle.\n * @returns the face's supporting plane frame (2D origin = the face's bbox centre).\n */\nexport function meshFacePlane(kernel: BrepEngineApi, face: BrepHandle): Plane {\n  const uv = kernel.uvBounds(face)\n  const u = (uv.uMin + uv.uMax) / 2\n  const v = (uv.vMin + uv.vMax) / 2\n  const n = kernel.surfaceNormal(face, u, v)\n  const bb = kernel.getBoundingBox(face)\n  return makePlane(\n    { x: (bb.xmin + bb.xmax) / 2, y: (bb.ymin + bb.ymax) / 2, z: (bb.zmin + bb.zmax) / 2 },\n    { x: n.x, y: n.y, z: n.z },\n  )\n}\n\n/**\n * 把内核算出的网格链面句柄封装成 op 产物。\n *\n * 与 `meshSolidProductWithBackend` 的区别是**不登记** `MeshSolidRegistry` 与近似拓扑：\n * 面不是零件，没有自己的注册表条目，下游也不需要\"面的近似拓扑\"（它自己就是拓扑的一部分）。\n * 显示载荷取面自身的三角化（`meshShape` 按句柄类型分发到 face 分支）。\n *\n * @param backend - the mesh backend (tessellation).\n * @param face - the new face handle produced by the kernel call.\n * @returns the product Shape carrying the face handle and its tessellation.\n */\nexport function meshFaceProduct(backend: MeshSolidBackend, face: BrepHandle): Shape {\n  const mesh = backend.kernel.meshShape(face)\n  return fromMeshFace(\n    { positions: new Float32Array(mesh.positions), indices: new Uint32Array(mesh.indices) },\n    { meshFace: face },\n  )\n}\n\n/**\n * 内核原生错误 → 带 op 名与输入几何的 OpError（几何失败必须带上下文，不裸抛内核串）。\n *\n * @param opLabel - the op name.\n * @param code - the op-level error code.\n * @param context - a short human description of what was being attempted.\n * @param cause - the kernel's own error.\n * @returns the wrapped op error.\n */\nexport function meshKernelFailure(\n  opLabel: string,\n  code: string,\n  context: string,\n  cause: unknown,\n): OpError {\n  const msg = cause instanceof Error ? cause.message : String(cause)\n  return new OpError(\n    opLabel,\n    code,\n    `[api/${opLabel}] ${context} — the mesh kernel refused: ${msg}`,\n    { cause },\n  )\n}\n"]}

package/dist/api/internal/svg-asset-resolver.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib internal svg-asset-resolver — SVG 资产解析辅助函数
+ * api internal svg-asset-resolver — SVG 资产解析辅助函数
  *
  * 从 src/ops/svg-asset-resolver.ts 迁入（Phase 2.5 删除 src/ops/）。
  *

package/dist/api/internal/svg-asset-resolver.js

@@ -1,5 +1,5 @@
 /**
- * stdlib internal svg-asset-resolver — SVG 资产解析辅助函数
+ * api internal svg-asset-resolver — SVG 资产解析辅助函数
  *
  * 从 src/ops/svg-asset-resolver.ts 迁入（Phase 2.5 删除 src/ops/）。
  *

package/dist/api/internal/svg-asset-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"svg-asset-resolver.js","sourceRoot":"","sources":["../../../src/api/internal/svg-asset-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,kCAAkC;AAClC,SAAS,UAAU,CAAC,KAAkB;IACpC,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAA;AAC/D,CAAC;AAED,yDAAyD;AACzD,SAAS,gBAAgB,CAAC,CAAU;IAClC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,QAAQ,IAAI,CAAC,CAAA;AAClF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAY,EACZ,KAAiC;IAEjC,gCAAgC;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAA;IAEvC,yBAAyB;IACzB,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAA;QAEtB,mCAAmC;QACnC,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;YACnD,OAAO,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACjC,CAAC;QAED,+CAA+C;QAC/C,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,kDAAkD,CAAC,CAAA;IACtG,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,oDAAoD,OAAO,GAAG,EAAE,CAAC,CAAA;AACnF,CAAC","sourcesContent":["/**\n * stdlib internal svg-asset-resolver — SVG 资产解析辅助函数\n *\n * 从 src/ops/svg-asset-resolver.ts 迁入（Phase 2.5 删除 src/ops/）。\n *\n * AssetRef 类型已退役（§4.2：`cad.asset(...)` 走 CallRefIR，运行时解析为字符串）；\n * 此处保留对 `{$asset: key}` 结构（旧 IR / 宿主手写语句）的运行时兼容。\n */\n\nimport type { HostPorts } from '../../cad-runtime/ports'\n\n/** 将 ArrayBuffer 解码为 UTF-8 字符串 */\nfunction decodeUtf8(bytes: ArrayBuffer): string {\n  return new TextDecoder('utf-8').decode(new Uint8Array(bytes))\n}\n\n/** 结构判断：旧 AssetRef 形态 `{$asset: key}`（运行时兼容，不依赖已退役类型） */\nfunction isLegacyAssetRef(v: unknown): v is { $asset: string } {\n  return typeof v === 'object' && v !== null && !Array.isArray(v) && '$asset' in v\n}\n\n/**\n * 解析 args.svg 字段为 SVG 文本字符串。\n *\n * - 普通字符串：直接返回（兼容直接传入 SVG 文本）\n * - 旧 AssetRef 结构（{ $asset: key }）：按 key 解析（运行时兼容）\n *\n * @throws if the SVG key cannot be resolved.\n * @param svg - the svg argument: a plain SVG string or a legacy `{ $asset: key }` reference.\n * @param ports - the host asset ports used to resolve a legacy asset reference.\n * @returns the resolved SVG text string.\n */\nexport async function resolveSvgArg(\n  svg: unknown,\n  ports?: Pick<HostPorts, 'assets'>,\n): Promise<string> {\n  // 普通字符串：直接返回（兼容旧格式或直接传入 SVG 文本）\n  if (typeof svg === 'string') return svg\n\n  // 旧 AssetRef 结构：按 key 解析\n  if (isLegacyAssetRef(svg)) {\n    const key = svg.$asset\n\n    // 优先使用 ports.assets（headless 环境支持）\n    if (ports?.assets) {\n      const result = await ports.assets.resolveByKey(key)\n      return decodeUtf8(result.bytes)\n    }\n\n    // ports.assets is required for headless engine\n    throw new Error(`[resolveSvgArg] SVG asset \"${key}\" cannot be resolved: ports.assets not available`)\n  }\n\n  throw new Error(`[resolveSvgArg] expected string or AssetRef, got ${typeof svg}`)\n}\n"]}
+{"version":3,"file":"svg-asset-resolver.js","sourceRoot":"","sources":["../../../src/api/internal/svg-asset-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,kCAAkC;AAClC,SAAS,UAAU,CAAC,KAAkB;IACpC,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAA;AAC/D,CAAC;AAED,yDAAyD;AACzD,SAAS,gBAAgB,CAAC,CAAU;IAClC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,QAAQ,IAAI,CAAC,CAAA;AAClF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAY,EACZ,KAAiC;IAEjC,gCAAgC;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAA;IAEvC,yBAAyB;IACzB,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAA;QAEtB,mCAAmC;QACnC,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;YACnD,OAAO,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACjC,CAAC;QAED,+CAA+C;QAC/C,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,kDAAkD,CAAC,CAAA;IACtG,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,oDAAoD,OAAO,GAAG,EAAE,CAAC,CAAA;AACnF,CAAC","sourcesContent":["/**\n * api internal svg-asset-resolver — SVG 资产解析辅助函数\n *\n * 从 src/ops/svg-asset-resolver.ts 迁入（Phase 2.5 删除 src/ops/）。\n *\n * AssetRef 类型已退役（§4.2：`cad.asset(...)` 走 CallRefIR，运行时解析为字符串）；\n * 此处保留对 `{$asset: key}` 结构（旧 IR / 宿主手写语句）的运行时兼容。\n */\n\nimport type { HostPorts } from '../../cad-runtime/ports'\n\n/** 将 ArrayBuffer 解码为 UTF-8 字符串 */\nfunction decodeUtf8(bytes: ArrayBuffer): string {\n  return new TextDecoder('utf-8').decode(new Uint8Array(bytes))\n}\n\n/** 结构判断：旧 AssetRef 形态 `{$asset: key}`（运行时兼容，不依赖已退役类型） */\nfunction isLegacyAssetRef(v: unknown): v is { $asset: string } {\n  return typeof v === 'object' && v !== null && !Array.isArray(v) && '$asset' in v\n}\n\n/**\n * 解析 args.svg 字段为 SVG 文本字符串。\n *\n * - 普通字符串：直接返回（兼容直接传入 SVG 文本）\n * - 旧 AssetRef 结构（{ $asset: key }）：按 key 解析（运行时兼容）\n *\n * @throws if the SVG key cannot be resolved.\n * @param svg - the svg argument: a plain SVG string or a legacy `{ $asset: key }` reference.\n * @param ports - the host asset ports used to resolve a legacy asset reference.\n * @returns the resolved SVG text string.\n */\nexport async function resolveSvgArg(\n  svg: unknown,\n  ports?: Pick<HostPorts, 'assets'>,\n): Promise<string> {\n  // 普通字符串：直接返回（兼容旧格式或直接传入 SVG 文本）\n  if (typeof svg === 'string') return svg\n\n  // 旧 AssetRef 结构：按 key 解析\n  if (isLegacyAssetRef(svg)) {\n    const key = svg.$asset\n\n    // 优先使用 ports.assets（headless 环境支持）\n    if (ports?.assets) {\n      const result = await ports.assets.resolveByKey(key)\n      return decodeUtf8(result.bytes)\n    }\n\n    // ports.assets is required for headless engine\n    throw new Error(`[resolveSvgArg] SVG asset \"${key}\" cannot be resolved: ports.assets not available`)\n  }\n\n  throw new Error(`[resolveSvgArg] expected string or AssetRef, got ${typeof svg}`)\n}\n"]}

package/dist/api/knurl.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib knurl — 滚花库函数（mesh-only）
+ * api knurl — 滚花库函数（mesh-only）
  *
  *
  * knurl 无 BREP 实现（mesh-only）——dispatchPath 在 brep 模式下调用前抛错。

package/dist/api/knurl.js

@@ -1,5 +1,5 @@
 /**
- * stdlib knurl — 滚花库函数（mesh-only）
+ * api knurl — 滚花库函数（mesh-only）
  *
  *
  * knurl 无 BREP 实现（mesh-only）——dispatchPath 在 brep 模式下调用前抛错。
@@ -40,7 +40,7 @@ export function assertKnurlParams(params) {
 export const knurl = defineOp({
     mesh: async (input, params) => {
         if (!input)
-            throw new Error('[stdlib/knurl] no input geometry');
+            throw new Error('[api/knurl] no input geometry');
         assertKnurlParams(params);
         // 断链时刻（用户点名场景）：BREP 建模的模型最后做滚花 → BREP 输入必须先归约为
         // 合法 2-manifold 网格再进 mesh 路径（reconcileBrepInputs 对 mesh 侧输入原样透传）

package/dist/api/knurl.js.map

@@ -1 +1 @@
-{"version":3,"file":"knurl.js","sourceRoot":"","sources":["../../src/api/knurl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE/C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA+B;IAC/D,oBAAoB,CAAC,MAAM,CAAC,kBAAkB,EAAE,0BAA0B,CAAC,CAAA;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,IAAI,EAAE,KAAK,EAAE,KAAY,EAAE,MAA+B,EAAE,EAAE;QAC5D,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;QAC/D,iBAAiB,CAAC,MAAM,CAAC,CAAA;QACzB,+CAA+C;QAC/C,iEAAiE;QACjE,MAAM,CAAC,SAAS,CAAC,GAAG,mBAAmB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QAChD,OAAO,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;YAC1B,IAAI,EAAE;gBACJ,MAAM,EAAG,MAAM,CAAC,UAA+B,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;gBAC5E,MAAM,EAAG,MAAM,CAAC,UAA+B,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;aAC7D;YACD,kBAAkB,EAAG,MAAM,CAAC,kBAAyC,IAAI,GAAG;YAC5E,uBAAuB,EAAG,MAAM,CAAC,uBAA+C,IAAI,KAAK;YACzF,iBAAiB,EAAG,MAAM,CAAC,iBAAwC,IAAI,GAAG;YAC1E,WAAW,EAAG,MAAM,CAAC,WAAkC,IAAI,IAAI;YAC/D,WAAW,EAAG,MAAM,CAAC,WAAkC,IAAI,IAAI;YAC/D,gBAAgB,EAAG,MAAM,CAAC,gBAAuC,IAAI,CAAC;SACvE,CAAC,CAAA;IACJ,CAAC;IACD,SAAS,EAAE,EAAE,kBAAkB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE;IACxE,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,2CAA2C,EAAgB;CACjG,CAAC,CAAA","sourcesContent":["/**\n * stdlib knurl — 滚花库函数（mesh-only）\n *\n *\n * knurl 无 BREP 实现（mesh-only）——dispatchPath 在 brep 模式下调用前抛错。\n * part-brep-lost 事件由引擎统一发（P4，库不再 emit）。\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { reconcileBrepInputs } from './reconcile'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { assertPositiveNumber } from './assert'\n\n/**\n * Validate knurl parameters: `knurlTextureHeight` must be a positive number.\n * @param params - the raw knurl operation parameters.\n */\nexport function assertKnurlParams(params: Record<string, unknown>): void {\n  assertPositiveNumber(params.knurlTextureHeight, 'knurl.knurlTextureHeight')\n}\n\n/**\n * 施加滚花（顶点位移，非布尔）。mesh-only。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual warn\n * @name knurl\n * @note knurl 无 BREP 实现（mesh-only），本质是顶点位移（网格操作），网格参数可接受；brep 模式下调用前抛 BrepUnsupportedError。面锚定建议用几何引用。\n * @returns Shape 滚花后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param params.knurlTextureHeight - 纹路高度（mm）。type:number 默认 0.5\n * @param params.knurlScaleU - 纹路 U 向频率。type:number 默认 0.15\n * @param params.knurlScaleV - 纹路 V 向频率。type:number 默认 0.15\n * @param params.knurlInvertDisplacement - 反向位移。type:boolean 默认 false\n * @param params.knurlRefineLength - 细分长度（mm）。type:number 默认 1.0\n * @param params.knurlMappingMode - UV 映射模式。type:number 默认 5\n * @param params.faceCenter - 面锚点中心。type:[x,y,z] 默认 bboxCenter\n * @param params.faceNormal - 面法向。type:[x,y,z] 默认 [0,0,1]\n * @example\n * const p = await cad.knurl(part0, { knurlTextureHeight: 0.5, knurlScaleU: 0.15, knurlScaleV: 0.15, knurlInvertDisplacement: false, knurlRefineLength: 1.0, knurlMappingMode: 5 })\n  */\nexport const knurl = defineOp({\n  mesh: async (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[stdlib/knurl] no input geometry')\n    assertKnurlParams(params)\n    // 断链时刻（用户点名场景）：BREP 建模的模型最后做滚花 → BREP 输入必须先归约为\n    // 合法 2-manifold 网格再进 mesh 路径（reconcileBrepInputs 对 mesh 侧输入原样透传）\n    const [meshInput] = reconcileBrepInputs([input])\n    return cad.knurl(meshInput, {\n      face: {\n        center: (params.faceCenter as Vec3 | undefined) ?? cad.bboxCenter(meshInput),\n        normal: (params.faceNormal as Vec3 | undefined) ?? [0, 0, 1],\n      },\n      knurlTextureHeight: (params.knurlTextureHeight as number | undefined) ?? 0.5,\n      knurlInvertDisplacement: (params.knurlInvertDisplacement as boolean | undefined) ?? false,\n      knurlRefineLength: (params.knurlRefineLength as number | undefined) ?? 1.0,\n      knurlScaleU: (params.knurlScaleU as number | undefined) ?? 0.15,\n      knurlScaleV: (params.knurlScaleV as number | undefined) ?? 0.15,\n      knurlMappingMode: (params.knurlMappingMode as number | undefined) ?? 5,\n    })\n  },\n  paramDims: { knurlTextureHeight: 'length', knurlRefineLength: 'length' },\n  naming: { kind: 'unmodeled', reason: 'knurl is mesh-only, no BREP face identity' } as Provenance,\n})\n"]}
+{"version":3,"file":"knurl.js","sourceRoot":"","sources":["../../src/api/knurl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE/C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA+B;IAC/D,oBAAoB,CAAC,MAAM,CAAC,kBAAkB,EAAE,0BAA0B,CAAC,CAAA;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,IAAI,EAAE,KAAK,EAAE,KAAY,EAAE,MAA+B,EAAE,EAAE;QAC5D,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;QAC5D,iBAAiB,CAAC,MAAM,CAAC,CAAA;QACzB,+CAA+C;QAC/C,iEAAiE;QACjE,MAAM,CAAC,SAAS,CAAC,GAAG,mBAAmB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QAChD,OAAO,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;YAC1B,IAAI,EAAE;gBACJ,MAAM,EAAG,MAAM,CAAC,UAA+B,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;gBAC5E,MAAM,EAAG,MAAM,CAAC,UAA+B,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;aAC7D;YACD,kBAAkB,EAAG,MAAM,CAAC,kBAAyC,IAAI,GAAG;YAC5E,uBAAuB,EAAG,MAAM,CAAC,uBAA+C,IAAI,KAAK;YACzF,iBAAiB,EAAG,MAAM,CAAC,iBAAwC,IAAI,GAAG;YAC1E,WAAW,EAAG,MAAM,CAAC,WAAkC,IAAI,IAAI;YAC/D,WAAW,EAAG,MAAM,CAAC,WAAkC,IAAI,IAAI;YAC/D,gBAAgB,EAAG,MAAM,CAAC,gBAAuC,IAAI,CAAC;SACvE,CAAC,CAAA;IACJ,CAAC;IACD,SAAS,EAAE,EAAE,kBAAkB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE;IACxE,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,2CAA2C,EAAgB;CACjG,CAAC,CAAA","sourcesContent":["/**\n * api knurl — 滚花库函数（mesh-only）\n *\n *\n * knurl 无 BREP 实现（mesh-only）——dispatchPath 在 brep 模式下调用前抛错。\n * part-brep-lost 事件由引擎统一发（P4，库不再 emit）。\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { reconcileBrepInputs } from './reconcile'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { assertPositiveNumber } from './assert'\n\n/**\n * Validate knurl parameters: `knurlTextureHeight` must be a positive number.\n * @param params - the raw knurl operation parameters.\n */\nexport function assertKnurlParams(params: Record<string, unknown>): void {\n  assertPositiveNumber(params.knurlTextureHeight, 'knurl.knurlTextureHeight')\n}\n\n/**\n * 施加滚花（顶点位移，非布尔）。mesh-only。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual warn\n * @name knurl\n * @note knurl 无 BREP 实现（mesh-only），本质是顶点位移（网格操作），网格参数可接受；brep 模式下调用前抛 BrepUnsupportedError。面锚定建议用几何引用。\n * @returns Shape 滚花后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param params.knurlTextureHeight - 纹路高度（mm）。type:number 默认 0.5\n * @param params.knurlScaleU - 纹路 U 向频率。type:number 默认 0.15\n * @param params.knurlScaleV - 纹路 V 向频率。type:number 默认 0.15\n * @param params.knurlInvertDisplacement - 反向位移。type:boolean 默认 false\n * @param params.knurlRefineLength - 细分长度（mm）。type:number 默认 1.0\n * @param params.knurlMappingMode - UV 映射模式。type:number 默认 5\n * @param params.faceCenter - 面锚点中心。type:[x,y,z] 默认 bboxCenter\n * @param params.faceNormal - 面法向。type:[x,y,z] 默认 [0,0,1]\n * @example\n * const p = await cad.knurl(part0, { knurlTextureHeight: 0.5, knurlScaleU: 0.15, knurlScaleV: 0.15, knurlInvertDisplacement: false, knurlRefineLength: 1.0, knurlMappingMode: 5 })\n  */\nexport const knurl = defineOp({\n  mesh: async (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/knurl] no input geometry')\n    assertKnurlParams(params)\n    // 断链时刻（用户点名场景）：BREP 建模的模型最后做滚花 → BREP 输入必须先归约为\n    // 合法 2-manifold 网格再进 mesh 路径（reconcileBrepInputs 对 mesh 侧输入原样透传）\n    const [meshInput] = reconcileBrepInputs([input])\n    return cad.knurl(meshInput, {\n      face: {\n        center: (params.faceCenter as Vec3 | undefined) ?? cad.bboxCenter(meshInput),\n        normal: (params.faceNormal as Vec3 | undefined) ?? [0, 0, 1],\n      },\n      knurlTextureHeight: (params.knurlTextureHeight as number | undefined) ?? 0.5,\n      knurlInvertDisplacement: (params.knurlInvertDisplacement as boolean | undefined) ?? false,\n      knurlRefineLength: (params.knurlRefineLength as number | undefined) ?? 1.0,\n      knurlScaleU: (params.knurlScaleU as number | undefined) ?? 0.15,\n      knurlScaleV: (params.knurlScaleV as number | undefined) ?? 0.15,\n      knurlMappingMode: (params.knurlMappingMode as number | undefined) ?? 5,\n    })\n  },\n  paramDims: { knurlTextureHeight: 'length', knurlRefineLength: 'length' },\n  naming: { kind: 'unmodeled', reason: 'knurl is mesh-only, no BREP face identity' } as Provenance,\n})\n"]}

package/dist/api/loft.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib loft — 放样：多个截面之间蒙皮生成体（手写平台 op，Phase 4 → G5 core 直连）
+ * api loft — 放样：多个截面之间蒙皮生成体（手写平台 op，Phase 4 → G5 core 直连）
  *
  * @platform occt — 实现走 core 直连 `occt-wasm loft` / `loftWithVertices`
  * （BRepOffsetAPI_ThruSections；engine-method-map 里 `loft` 为 occt-only）⇒ 平台 op：

package/dist/api/loft.js

@@ -1,5 +1,5 @@
 /**
- * stdlib loft — 放样：多个截面之间蒙皮生成体（手写平台 op，Phase 4 → G5 core 直连）
+ * api loft — 放样：多个截面之间蒙皮生成体（手写平台 op，Phase 4 → G5 core 直连）
  *
  * @platform occt — 实现走 core 直连 `occt-wasm loft` / `loftWithVertices`
  * （BRepOffsetAPI_ThruSections；engine-method-map 里 `loft` 为 occt-only）⇒ 平台 op：

package/dist/api/loft.js.map

@@ -1 +1 @@
-{"version":3,"file":"loft.js","sourceRoot":"","sources":["../../src/api/loft.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib loft — 放样：多个截面之间蒙皮生成体（手写平台 op，Phase 4 → G5 core 直连）\n *\n * @platform occt — 实现走 core 直连 `occt-wasm loft` / `loftWithVertices`\n * （BRepOffsetAPI_ThruSections；engine-method-map 里 `loft` 为 occt-only）⇒ 平台 op：\n * defineOp 声明 `engines: ['occt']`（D11）。\n *\n * 为什么手写而不走生成投影：与 `api/sweep.ts` 同因——截面最常见来源是\n * `cad.profile(...)`（产出 **face**），内核 `loft(wires, …)` 只吃 wire ⇒\n * 需要「面 → 外环」输入适配（`internal/profile-wire.ts` 的唯一步径）。\n *\n * core-decouple G5：vendored `loft`（brepjs）替换为 occt-wasm 原生直连，\n * 产物经 `fromBrep` 收养（替代 l3-bridge adoptEntity）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep } from '../shape'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\nimport { toProfileWireView } from './internal/profile-wire'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/** 放样配置（与 vendored LoftOptions 同形；本文件自持，去 brepjs 依赖）。 */\nexport interface LoftOptions {\n  /** 直线插值（ruled）。默认 true。 */\n  ruled?: boolean\n  /** 起点（退化到点的蒙皮）。 */\n  startPoint?: readonly [number, number, number] | { x: number; y: number; z: number }\n  /** 终点（退化到点的蒙皮）。 */\n  endPoint?: readonly [number, number, number] | { x: number; y: number; z: number }\n  /** ThruSections 缝合公差。默认 1e-6。 */\n  tolerance?: number\n}\n\n/** PointInput → [x,y,z]（vendored toVec3 同口径）。 */\nfunction toVec3(p: LoftOptions['startPoint']): [number, number, number] {\n  if (Array.isArray(p) && p.length >= 3) return [p[0]!, p[1]!, p[2]!]\n  const o = p as { x: number; y: number; z: number }\n  return [o.x, o.y, o.z]\n}\n\n/** BREP 路径：按序蒙皮各截面（wire 视图 → occt-wasm 直连 → fromBrep 收养）。 */\nfunction loftBrep(sections: Shape[], opts?: LoftOptions): Shape {\n  if (!Array.isArray(sections) || sections.length === 0) {\n    throw new Error('E_LOFT_NO_SECTIONS: loft requires a non-empty array of section shapes')\n  }\n  // 每截面：wire 直用；面取外环（孔环不参与放样）。\n  const wireViews = sections.map((s) => toProfileWireView(s))\n  const { ruled = true, startPoint, endPoint } = opts ?? {}\n  const kernel = getBrepApi()\n  const k = getOcctKernel()\n  const wireHandles = wireViews.map((w) => w.wrapped as never)\n\n  try {\n    let h: unknown\n    if (startPoint !== undefined || endPoint !== undefined) {\n      const startVertex = startPoint !== undefined ? k.makeVertex(...toVec3(startPoint)) : undefined\n      const endVertex = endPoint !== undefined ? k.makeVertex(...toVec3(endPoint)) : undefined\n      try {\n        h = k.loftWithVertices(wireHandles, true, ruled, startVertex as never, endVertex as never)\n      } finally {\n        if (startVertex !== undefined) k.release(startVertex)\n        if (endVertex !== undefined) k.release(endVertex)\n      }\n    } else {\n      h = k.loft(wireHandles, true, ruled)\n    }\n    return fromBrep(solidToShape(kernel, h as BrepHandle), { solid: h as BrepHandle })\n  } catch (e) {\n    const raw = e instanceof Error ? e.message : String(e)\n    throw new Error(`E_LOFT_FAILED: loft failed: ${raw}`, { cause: e })\n  } finally {\n    // 面→外环产出的 wire 是 arena 新句柄（曲线借用不 release）\n    for (const w of wireViews) {\n      if (!w.borrowed) {\n        try { kernel.release(w.wrapped) } catch { /* 已释放 */ }\n      }\n    }\n  }\n}\n\n/**\n * 放样：按给定顺序在截面之间蒙皮生成体。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name loft\n * @note 平台 op：仅 occt 引擎（BRepOffsetAPI_ThruSections）。截面可为 wire 或面\n *       （面取其外环），至少 2 个；`startPoint` / `endPoint` 可做退化到点的蒙皮。\n *       非 occt 引擎执行前报错；brep_mock 不拦截。不做 `loftAll`（数组产物）。\n * @returns Shape 放样体。\n * @param sections - 有序截面集合（wire 或面；面取其外环）。type:Shape[] required:true\n * @param opts - 放样配置（ruled / startPoint / endPoint / tolerance）。type:LoftOptions required:false\n * @example\n * const bottom = cad.profile({ contours: [{ segments: [\n *   { kind: 'line', x1: -5, y1: -5, x2: 5, y2: -5 },\n *   { kind: 'line', x1: 5, y1: -5, x2: 5, y2: 5 },\n *   { kind: 'line', x1: 5, y1: 5, x2: -5, y2: 5 },\n *   { kind: 'line', x1: -5, y1: 5, x2: -5, y2: -5 },\n * ] }] })\n * const top = cad.translate(cad.profile({ contours: [{ segments: [\n *   { kind: 'line', x1: -3, y1: -3, x2: 3, y2: -3 },\n *   { kind: 'line', x1: 3, y1: -3, x2: 3, y2: 3 },\n *   { kind: 'line', x1: 3, y1: 3, x2: -3, y2: 3 },\n *   { kind: 'line', x1: -3, y1: 3, x2: -3, y2: -3 },\n * ] }] }), [0, 0, 20])\n * const body = await cad.loft([bottom, top])\n */\nexport const loft = defineOp({\n  name: 'loft',\n  brep(sections: Shape[], opts?: LoftOptions) {\n    return loftBrep(sections, opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'lofted-body face vocabulary not defined' } as Provenance,\n})\n"]}
+{"version":3,"file":"loft.js","sourceRoot":"","sources":["../../src/api/loft.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api loft — 放样：多个截面之间蒙皮生成体（手写平台 op，Phase 4 → G5 core 直连）\n *\n * @platform occt — 实现走 core 直连 `occt-wasm loft` / `loftWithVertices`\n * （BRepOffsetAPI_ThruSections；engine-method-map 里 `loft` 为 occt-only）⇒ 平台 op：\n * defineOp 声明 `engines: ['occt']`（D11）。\n *\n * 为什么手写而不走生成投影：与 `api/sweep.ts` 同因——截面最常见来源是\n * `cad.profile(...)`（产出 **face**），内核 `loft(wires, …)` 只吃 wire ⇒\n * 需要「面 → 外环」输入适配（`internal/profile-wire.ts` 的唯一步径）。\n *\n * core-decouple G5：vendored `loft`（brepjs）替换为 occt-wasm 原生直连，\n * 产物经 `fromBrep` 收养（替代 l3-bridge adoptEntity）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep } from '../shape'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\nimport { toProfileWireView } from './internal/profile-wire'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/** 放样配置（与 vendored LoftOptions 同形；本文件自持，去 brepjs 依赖）。 */\nexport interface LoftOptions {\n  /** 直线插值（ruled）。默认 true。 */\n  ruled?: boolean\n  /** 起点（退化到点的蒙皮）。 */\n  startPoint?: readonly [number, number, number] | { x: number; y: number; z: number }\n  /** 终点（退化到点的蒙皮）。 */\n  endPoint?: readonly [number, number, number] | { x: number; y: number; z: number }\n  /** ThruSections 缝合公差。默认 1e-6。 */\n  tolerance?: number\n}\n\n/** PointInput → [x,y,z]（vendored toVec3 同口径）。 */\nfunction toVec3(p: LoftOptions['startPoint']): [number, number, number] {\n  if (Array.isArray(p) && p.length >= 3) return [p[0]!, p[1]!, p[2]!]\n  const o = p as { x: number; y: number; z: number }\n  return [o.x, o.y, o.z]\n}\n\n/** BREP 路径：按序蒙皮各截面（wire 视图 → occt-wasm 直连 → fromBrep 收养）。 */\nfunction loftBrep(sections: Shape[], opts?: LoftOptions): Shape {\n  if (!Array.isArray(sections) || sections.length === 0) {\n    throw new Error('E_LOFT_NO_SECTIONS: loft requires a non-empty array of section shapes')\n  }\n  // 每截面：wire 直用；面取外环（孔环不参与放样）。\n  const wireViews = sections.map((s) => toProfileWireView(s))\n  const { ruled = true, startPoint, endPoint } = opts ?? {}\n  const kernel = getBrepApi()\n  const k = getOcctKernel()\n  const wireHandles = wireViews.map((w) => w.wrapped as never)\n\n  try {\n    let h: unknown\n    if (startPoint !== undefined || endPoint !== undefined) {\n      const startVertex = startPoint !== undefined ? k.makeVertex(...toVec3(startPoint)) : undefined\n      const endVertex = endPoint !== undefined ? k.makeVertex(...toVec3(endPoint)) : undefined\n      try {\n        h = k.loftWithVertices(wireHandles, true, ruled, startVertex as never, endVertex as never)\n      } finally {\n        if (startVertex !== undefined) k.release(startVertex)\n        if (endVertex !== undefined) k.release(endVertex)\n      }\n    } else {\n      h = k.loft(wireHandles, true, ruled)\n    }\n    return fromBrep(solidToShape(kernel, h as BrepHandle), { solid: h as BrepHandle })\n  } catch (e) {\n    const raw = e instanceof Error ? e.message : String(e)\n    throw new Error(`E_LOFT_FAILED: loft failed: ${raw}`, { cause: e })\n  } finally {\n    // 面→外环产出的 wire 是 arena 新句柄（曲线借用不 release）\n    for (const w of wireViews) {\n      if (!w.borrowed) {\n        try { kernel.release(w.wrapped) } catch { /* 已释放 */ }\n      }\n    }\n  }\n}\n\n/**\n * 放样：按给定顺序在截面之间蒙皮生成体。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name loft\n * @note 平台 op：仅 occt 引擎（BRepOffsetAPI_ThruSections）。截面可为 wire 或面\n *       （面取其外环），至少 2 个；`startPoint` / `endPoint` 可做退化到点的蒙皮。\n *       非 occt 引擎执行前报错；brep_mock 不拦截。不做 `loftAll`（数组产物）。\n * @returns Shape 放样体。\n * @param sections - 有序截面集合（wire 或面；面取其外环）。type:Shape[] required:true\n * @param opts - 放样配置（ruled / startPoint / endPoint / tolerance）。type:LoftOptions required:false\n * @example\n * const bottom = cad.profile({ contours: [{ segments: [\n *   { kind: 'line', x1: -5, y1: -5, x2: 5, y2: -5 },\n *   { kind: 'line', x1: 5, y1: -5, x2: 5, y2: 5 },\n *   { kind: 'line', x1: 5, y1: 5, x2: -5, y2: 5 },\n *   { kind: 'line', x1: -5, y1: 5, x2: -5, y2: -5 },\n * ] }] })\n * const top = cad.translate(cad.profile({ contours: [{ segments: [\n *   { kind: 'line', x1: -3, y1: -3, x2: 3, y2: -3 },\n *   { kind: 'line', x1: 3, y1: -3, x2: 3, y2: 3 },\n *   { kind: 'line', x1: 3, y1: 3, x2: -3, y2: 3 },\n *   { kind: 'line', x1: -3, y1: 3, x2: -3, y2: -3 },\n * ] }] }), [0, 0, 20])\n * const body = await cad.loft([bottom, top])\n */\nexport const loft = defineOp({\n  name: 'loft',\n  brep(sections: Shape[], opts?: LoftOptions) {\n    return loftBrep(sections, opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'lofted-body face vocabulary not defined' } as Provenance,\n})\n"]}

package/dist/api/measurement/index.d.ts

@@ -23,14 +23,18 @@ import type { BrepVec3 } from '../../brep/engine/types.js';
 /**
  * 测量形状的表面积（L1 getSurfaceArea，两引擎同口径）。
  *
- * @param shape - 被测量的形状（Face / Shape3D / compound）。
- * @returns 表面积（mm²）。
+ * @param shape - 被测量的形状（Face / Shape3D / compound / 网格零件）。
+ * @returns 表面积（mm²；网格零件按面片几何计）。
  */
 export declare function area(shape: Shape): Promise<number>;
 /**
  * 测量形状的边长/线长（L1 getLength，两引擎同口径）。
  *
- * @param shape - 被测量的形状（edge / wire / solid，solid 按内核口径计边）。
+ * 口径 = **shape 中所有唯一 edge 的弧长之和**：edge 取自身弧长，wire 取其边之和，
+ * face 取边界边之和，solid 取全部边之和，compound 取各子实体之和。两个 BREP 引擎
+ * 在此口径下逐位一致（2026-10-02 归一化，见 occt / brepkit 适配器的 getLength）。
+ *
+ * @param shape - 被测量的形状（edge / wire / face / solid / compound）。
  * @returns 长度（mm）。
  */
 export declare function length(shape: Shape): Promise<number>;
@@ -38,13 +42,13 @@ export declare function length(shape: Shape): Promise<number>;
  * 测量形状的体素体积（L1 getVolume，两引擎同口径）。
  *
  * @param shape - 被测量的形状（solid / compound；对 wire / face 内核按自身口径计，可能返回 0）。
- * @returns 体积（mm³）。
+ * @returns 体积（mm³；网格零件按面片几何计）。
  */
 export declare function volume(shape: Shape): Promise<number>;
 /**
  * 测量形状的质心（L1 getCenterOfMass，两引擎同口径）。
  *
- * @param shape - 被测量的形状（solid / compound / face）。
+ * @param shape - 被测量的形状（solid / compound / face / 网格零件）。
  * @returns 质心坐标（mm，BREP 中立形态 {x,y,z}）。
  */
 export declare function centerOfMass(shape: Shape): Promise<BrepVec3>;

package/dist/api/measurement/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/measurement/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAc,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAanE;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxD;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAGlE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/measurement/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAc,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AA+CnE;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxD;AAED;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAGlE"}