@faicad/faijs 0.33.2 → 0.35.8

package/dist/api/selectors-to-refs.d.ts

@@ -0,0 +1,83 @@
+/**
+ * api selectors-to-refs — CadQuery 选择器 → TopoRef 桥（方案 2026-10-12 §3.2）
+ *
+ * 把 CadQuery 字符串选择器（`">Z"`、`"|Z"`、`"%PLANE"`、命名视图 `"top"`、
+ * 集合表达式 `"|Z and %PLANE"` …）求值成内核句柄，再经命名层（RoleTable + 血缘）
+ * 反查合成 `FaceTopoRef` / `EdgeTopoRef`，或直接投影成顶点坐标（`P3`）——让
+ * `cad.*` op 的拓扑参数能吃下字符串选择器（AI 生成 faijs 代码的目标形态），
+ * 而不破坏「选择器子系统与命名/TopoRef 系统物理隔离」的红线。
+ *
+ * 职责边界（方案 §3.2 R4）：本文件是选择器与命名系统之间**唯一的显式通道**。
+ * 句柄 → TopoRef 反查复用 `edge-ref.ts` / `face-ref.ts` 已示范的路径
+ * （`captureEdgeHint` / `captureFaceHint` / `findOriginRole` /
+ * `recoverEdgeFaceRole`），不重写命名逻辑。
+ *
+ * 错误红线（方案 §3.2 R1，与 faijs 红线一致）：选择器选中的**无名实体**
+ * （role 缺失，如 3MF 网格链）→ 抛 `TopoRefError`，不静默降级；网格零件没有
+ * role 层，选择器/命名体系只服务精度链（网格链用序号是设计定论）。
+ */
+import type { Shape } from '../mesh/types.js';
+import { type EdgeTopoRef, type FaceTopoRef } from '../topology/naming/index.js';
+import type { P3 } from './cadquery-selectors/entity.js';
+/**
+ * 把面选择器字符串解析成 `FaceTopoRef[]`（选择器 → 句柄 → TopoRef 全链）。
+ *
+ * 示例：`">Z"`（Z 极值面）、`"|Z"`（法向平行 Z 的平面面）、`"%PLANE"`、
+ * `"top"`（命名视图）、`"|Z and %PLANE"`（集合表达式）。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape；选择器服务精度链）。
+ * @param sel - CadQuery 面选择器字符串。
+ * @returns 选中面的 `FaceTopoRef[]`（保持选择器返回顺序）。
+ * @throws {TopoRefError} 无 BREP / 选中面无 role 血统（不静默降级）。
+ */
+export declare function resolveSelectorToFaceRefs(shape: Shape, sel: string): FaceTopoRef[];
+/**
+ * 把边选择器字符串解析成 `EdgeTopoRef[]`（选择器 → 句柄 → TopoRef 全链）。
+ *
+ * 示例：`"|Z"`（切线平行 Z 的边）、`">Z"`（Z 极值边）、`"%LINE"`、
+ * `"#Z"`（切线垂直 Z）。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape）。
+ * @param sel - CadQuery 边选择器字符串。
+ * @returns 选中边的 `EdgeTopoRef[]`（保持选择器返回顺序）。
+ * @throws {TopoRefError} 无 BREP / 选中边邻面不足两面或无 role 血统。
+ */
+export declare function resolveSelectorToEdgeRefs(shape: Shape, sel: string): EdgeTopoRef[];
+/**
+ * 把顶点选择器字符串解析成顶点坐标 `P3[]`。
+ *
+ * 顶点没有角色身份（命名层只给面/边命名），故直接投影成世界坐标点——
+ * 供未来需要「点」的 op（如打点/对齐）使用。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape）。
+ * @param sel - CadQuery 顶点选择器字符串（如 `">Z"`、`"(0,0,0)"`，空串 = 全部）。
+ * @returns 选中顶点的世界坐标（保持选择器返回顺序）。
+ * @throws {TopoRefError} 无 BREP（顶点选择器只服务精度链）。
+ */
+export declare function resolveSelectorToVertexPts(shape: Shape, sel: string): P3[];
+/** 边选择器参数的一个条目：选择器字符串或 `EdgeTopoRef`。 */
+export type EdgeSelectorEntry = EdgeTopoRef | string;
+/** 面选择器参数的一个条目：选择器字符串或 `FaceTopoRef`。 */
+export type FaceSelectorEntry = FaceTopoRef | string;
+/**
+ * 展开 op 的边选择器参数（顶层字符串或数组元素字符串）到 `EdgeTopoRef[]`。
+ *
+ * 形态（方案 D2-A）：`edges: "|Z"`、`edges: ["|Z"]`、`edges: ["|Z", refA]` 均可。
+ * 数组里的 `EdgeTopoRef` 原样保留；字符串逐个经桥解析（保持出现顺序）。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape）。
+ * @param edges - 边选择器参数（字符串 = 单一选择器；数组元素可为选择器字符串或 EdgeTopoRef）。
+ * @returns 展开后的 `EdgeTopoRef[]`。
+ */
+export declare function expandEdgeSelectorRefs(shape: Shape, edges: EdgeSelectorEntry[] | string): EdgeTopoRef[];
+/**
+ * 展开 op 的面选择器参数（顶层字符串或数组元素字符串）到 `FaceTopoRef[]`。
+ *
+ * 形态（方案 D2-A）：`openFaces: ">Z"`、`faces: ["|Z"]`、`faces: ["|Z", refA]` 均可。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape）。
+ * @param faces - 面选择器参数（字符串 = 单一选择器；数组元素可为选择器字符串或 FaceTopoRef）。
+ * @returns 展开后的 `FaceTopoRef[]`。
+ */
+export declare function expandFaceSelectorRefs(shape: Shape, faces: FaceSelectorEntry[] | string): FaceTopoRef[];
+//# sourceMappingURL=selectors-to-refs.d.ts.map

package/dist/api/selectors-to-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors-to-refs.d.ts","sourceRoot":"","sources":["../../src/api/selectors-to-refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAM1C,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,WAAW,EAGjB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,6BAA6B,CAAA;AAgJrD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CAalF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CAalF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,EAAE,EAAE,CAQ1E;AAID,yCAAyC;AACzC,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,MAAM,CAAA;AAEpD,yCAAyC;AACzC,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,MAAM,CAAA;AAEpD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAClC,WAAW,EAAE,CAGf;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAClC,WAAW,EAAE,CAGf"}

package/dist/api/selectors-to-refs.js

@@ -0,0 +1,211 @@
+/**
+ * api selectors-to-refs — CadQuery 选择器 → TopoRef 桥（方案 2026-10-12 §3.2）
+ *
+ * 把 CadQuery 字符串选择器（`">Z"`、`"|Z"`、`"%PLANE"`、命名视图 `"top"`、
+ * 集合表达式 `"|Z and %PLANE"` …）求值成内核句柄，再经命名层（RoleTable + 血缘）
+ * 反查合成 `FaceTopoRef` / `EdgeTopoRef`，或直接投影成顶点坐标（`P3`）——让
+ * `cad.*` op 的拓扑参数能吃下字符串选择器（AI 生成 faijs 代码的目标形态），
+ * 而不破坏「选择器子系统与命名/TopoRef 系统物理隔离」的红线。
+ *
+ * 职责边界（方案 §3.2 R4）：本文件是选择器与命名系统之间**唯一的显式通道**。
+ * 句柄 → TopoRef 反查复用 `edge-ref.ts` / `face-ref.ts` 已示范的路径
+ * （`captureEdgeHint` / `captureFaceHint` / `findOriginRole` /
+ * `recoverEdgeFaceRole`），不重写命名逻辑。
+ *
+ * 错误红线（方案 §3.2 R1，与 faijs 红线一致）：选择器选中的**无名实体**
+ * （role 缺失，如 3MF 网格链）→ 抛 `TopoRefError`，不静默降级；网格零件没有
+ * role 层，选择器/命名体系只服务精度链（网格链用序号是设计定论）。
+ */
+import { getBrepApi } from '../brep/handle-bridge.js';
+import { brepOf, hasBrep } from '../shape.js';
+import { nameOf } from '../runtime-state.js';
+import { captureEdgeHint, captureFaceHint, findOriginRole, TopoRefError, } from '../topology/naming/index.js';
+import { buildEdgeResolutionContext, recoverEdgeFaceRole } from './topo-resolve.js';
+import { resolveStepHandles } from './cadquery-selectors/resolve.js';
+/** 桥的静态前置：shape 必须是带 BREP 的活实体（选择器服务精度链）。 */
+function requireBrep(shape, what) {
+    const kernel = getBrepApi();
+    if (!kernel) {
+        throw new TopoRefError('E_TOPO_MESH_UNSUPPORTED', 'face', `${what}: selector resolution is BREP-only (mesh path unsupported)`);
+    }
+    if (!hasBrep(shape)) {
+        throw new TopoRefError('E_TOPO_MESH_UNSUPPORTED', 'face', `${what}: input shape has no BREP solid (mesh shapes do not carry topology identity)`);
+    }
+    return kernel;
+}
+/** 取形状的 BREP solid 句柄（调用方已过 requireBrep，solid 必在）。 */
+function solidOf(shape, what) {
+    const solid = brepOf(shape);
+    if (solid === undefined) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `${what}: input has no BREP solid`);
+    }
+    return solid;
+}
+/**
+ * 面句柄 → `FaceTopoRef`：在命名现场（ctx.faces）定位 ordinal → roleTable 反查
+ * `{origin, role}`（miss 沿血缘回走恢复）→ 几何 hint。
+ *
+ * @param kernel - the active BREP engine.
+ * @param shape - the live input shape (for nameOf lineage recovery).
+ * @param ctx - the naming resolution context built from the shape.
+ * @param handle - the selected face handle.
+ * @returns the FaceTopoRef, or throws when the face has no role lineage.
+ */
+function faceHandleToRef(kernel, shape, ctx, handle) {
+    const idx = ctx.faces.findIndex((f) => f.handle !== undefined && kernel.isSame(f.handle, handle));
+    if (idx < 0) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'selector: resolved face is not in the naming context');
+    }
+    const ordinal = ctx.faces[idx].ordinal;
+    const table = ctx.roleTable;
+    if (!table) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'selector: input shape has no role table (nameless shape)');
+    }
+    const ordinalToHash = ctx.faces.map((f) => f.hash ?? 0);
+    let found = findOriginRole(table, ordinalToHash, ordinal);
+    if (!found) {
+        // 与 face-ref.ts 同构：目标 part 的 roleTable 缓存残缺但血缘可回走 → 恢复。
+        const part = nameOf(shape);
+        if (part)
+            found = recoverEdgeFaceRole(kernel, part, ordinal, ordinalToHash);
+    }
+    if (!found) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `selector: resolved face ordinal ${ordinal} has no role lineage`);
+    }
+    return { kind: 'face', origin: found.origin, role: found.role, hint: captureFaceHint(kernel, handle) };
+}
+/**
+ * 边句柄 → `EdgeTopoRef`：与 `edge-ref.ts` 同构——逐面枚举其边找邻面（不依赖
+ * 邻接表下标对齐），两邻面的 role 对合成限定符 + 几何 hint。
+ *
+ * @param kernel - the active BREP engine.
+ * @param shape - the live input shape (for nameOf lineage recovery).
+ * @param ctx - the naming resolution context built from the shape.
+ * @param handle - the selected edge handle.
+ * @returns the EdgeTopoRef, or throws when the edge lacks a two-face role pair.
+ */
+function edgeHandleToRef(kernel, shape, ctx, handle) {
+    const faceOrdinals = [];
+    for (const f of ctx.faces) {
+        if (f.handle === undefined)
+            continue;
+        if (kernel.getSubShapes(f.handle, 'edge').some((eh) => kernel.isSame(eh, handle))) {
+            faceOrdinals.push(f.ordinal);
+        }
+    }
+    if (faceOrdinals.length < 2) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', `selector: edge has ${faceOrdinals.length} adjacent face(s); an EdgeTopoRef needs a two-face pair`);
+    }
+    const table = ctx.roleTable;
+    if (!table) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', 'selector: input shape has no role table (nameless shape)');
+    }
+    const ordinalToHash = ctx.faces.map((f) => f.hash ?? 0);
+    const quals = [];
+    for (const fo of faceOrdinals.slice(0, 2)) {
+        let found = findOriginRole(table, ordinalToHash, fo);
+        if (!found) {
+            const part = nameOf(shape);
+            if (part)
+                found = recoverEdgeFaceRole(kernel, part, fo, ordinalToHash);
+        }
+        if (!found) {
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', `selector: adjacent face ordinal ${fo} has no role lineage`);
+        }
+        quals.push({ origin: found.origin, role: found.role });
+    }
+    const [qa, qb] = quals;
+    return { kind: 'edge', faces: [qa, qb], hint: captureEdgeHint(kernel, handle) };
+}
+/**
+ * 把面选择器字符串解析成 `FaceTopoRef[]`（选择器 → 句柄 → TopoRef 全链）。
+ *
+ * 示例：`">Z"`（Z 极值面）、`"|Z"`（法向平行 Z 的平面面）、`"%PLANE"`、
+ * `"top"`（命名视图）、`"|Z and %PLANE"`（集合表达式）。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape；选择器服务精度链）。
+ * @param sel - CadQuery 面选择器字符串。
+ * @returns 选中面的 `FaceTopoRef[]`（保持选择器返回顺序）。
+ * @throws {TopoRefError} 无 BREP / 选中面无 role 血统（不静默降级）。
+ */
+export function resolveSelectorToFaceRefs(shape, sel) {
+    const kernel = requireBrep(shape, 'resolveSelectorToFaceRefs');
+    const solid = solidOf(shape, 'resolveSelectorToFaceRefs');
+    const ctx = buildEdgeResolutionContext(kernel, shape);
+    if (!ctx) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'resolveSelectorToFaceRefs: input has no BREP naming context');
+    }
+    const handles = resolveStepHandles(solid, 'face', sel);
+    return handles.map((h) => faceHandleToRef(kernel, shape, ctx, h));
+}
+/**
+ * 把边选择器字符串解析成 `EdgeTopoRef[]`（选择器 → 句柄 → TopoRef 全链）。
+ *
+ * 示例：`"|Z"`（切线平行 Z 的边）、`">Z"`（Z 极值边）、`"%LINE"`、
+ * `"#Z"`（切线垂直 Z）。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape）。
+ * @param sel - CadQuery 边选择器字符串。
+ * @returns 选中边的 `EdgeTopoRef[]`（保持选择器返回顺序）。
+ * @throws {TopoRefError} 无 BREP / 选中边邻面不足两面或无 role 血统。
+ */
+export function resolveSelectorToEdgeRefs(shape, sel) {
+    const kernel = requireBrep(shape, 'resolveSelectorToEdgeRefs');
+    const solid = solidOf(shape, 'resolveSelectorToEdgeRefs');
+    const ctx = buildEdgeResolutionContext(kernel, shape);
+    if (!ctx) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', 'resolveSelectorToEdgeRefs: input has no BREP naming context');
+    }
+    const handles = resolveStepHandles(solid, 'edge', sel);
+    return handles.map((h) => edgeHandleToRef(kernel, shape, ctx, h));
+}
+/**
+ * 把顶点选择器字符串解析成顶点坐标 `P3[]`。
+ *
+ * 顶点没有角色身份（命名层只给面/边命名），故直接投影成世界坐标点——
+ * 供未来需要「点」的 op（如打点/对齐）使用。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape）。
+ * @param sel - CadQuery 顶点选择器字符串（如 `">Z"`、`"(0,0,0)"`，空串 = 全部）。
+ * @returns 选中顶点的世界坐标（保持选择器返回顺序）。
+ * @throws {TopoRefError} 无 BREP（顶点选择器只服务精度链）。
+ */
+export function resolveSelectorToVertexPts(shape, sel) {
+    const kernel = requireBrep(shape, 'resolveSelectorToVertexPts');
+    const solid = solidOf(shape, 'resolveSelectorToVertexPts');
+    const handles = resolveStepHandles(solid, 'vertex', sel);
+    return handles.map((h) => {
+        const p = kernel.vertexPosition(h);
+        return { x: p.x, y: p.y, z: p.z };
+    });
+}
+/**
+ * 展开 op 的边选择器参数（顶层字符串或数组元素字符串）到 `EdgeTopoRef[]`。
+ *
+ * 形态（方案 D2-A）：`edges: "|Z"`、`edges: ["|Z"]`、`edges: ["|Z", refA]` 均可。
+ * 数组里的 `EdgeTopoRef` 原样保留；字符串逐个经桥解析（保持出现顺序）。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape）。
+ * @param edges - 边选择器参数（字符串 = 单一选择器；数组元素可为选择器字符串或 EdgeTopoRef）。
+ * @returns 展开后的 `EdgeTopoRef[]`。
+ */
+export function expandEdgeSelectorRefs(shape, edges) {
+    if (typeof edges === 'string')
+        return resolveSelectorToEdgeRefs(shape, edges);
+    return edges.flatMap((e) => (typeof e === 'string' ? resolveSelectorToEdgeRefs(shape, e) : [e]));
+}
+/**
+ * 展开 op 的面选择器参数（顶层字符串或数组元素字符串）到 `FaceTopoRef[]`。
+ *
+ * 形态（方案 D2-A）：`openFaces: ">Z"`、`faces: ["|Z"]`、`faces: ["|Z", refA]` 均可。
+ *
+ * @param shape - 目标几何（BREP 实体所在的 Shape）。
+ * @param faces - 面选择器参数（字符串 = 单一选择器；数组元素可为选择器字符串或 FaceTopoRef）。
+ * @returns 展开后的 `FaceTopoRef[]`。
+ */
+export function expandFaceSelectorRefs(shape, faces) {
+    if (typeof faces === 'string')
+        return resolveSelectorToFaceRefs(shape, faces);
+    return faces.flatMap((f) => (typeof f === 'string' ? resolveSelectorToFaceRefs(shape, f) : [f]));
+}
+//# sourceMappingURL=selectors-to-refs.js.map

package/dist/api/selectors-to-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors-to-refs.js","sourceRoot":"","sources":["../../src/api/selectors-to-refs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api selectors-to-refs — CadQuery 选择器 → TopoRef 桥（方案 2026-10-12 §3.2）\n *\n * 把 CadQuery 字符串选择器（`\">Z\"`、`\"|Z\"`、`\"%PLANE\"`、命名视图 `\"top\"`、\n * 集合表达式 `\"|Z and %PLANE\"` …）求值成内核句柄，再经命名层（RoleTable + 血缘）\n * 反查合成 `FaceTopoRef` / `EdgeTopoRef`，或直接投影成顶点坐标（`P3`）——让\n * `cad.*` op 的拓扑参数能吃下字符串选择器（AI 生成 faijs 代码的目标形态），\n * 而不破坏「选择器子系统与命名/TopoRef 系统物理隔离」的红线。\n *\n * 职责边界（方案 §3.2 R4）：本文件是选择器与命名系统之间**唯一的显式通道**。\n * 句柄 → TopoRef 反查复用 `edge-ref.ts` / `face-ref.ts` 已示范的路径\n * （`captureEdgeHint` / `captureFaceHint` / `findOriginRole` /\n * `recoverEdgeFaceRole`），不重写命名逻辑。\n *\n * 错误红线（方案 §3.2 R1，与 faijs 红线一致）：选择器选中的**无名实体**\n * （role 缺失，如 3MF 网格链）→ 抛 `TopoRefError`，不静默降级；网格零件没有\n * role 层，选择器/命名体系只服务精度链（网格链用序号是设计定论）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { brepOf, hasBrep } from '../shape'\nimport { nameOf } from '../runtime-state'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { BrepHandle } from '../brep/engine/types'\nimport {\n  captureEdgeHint,\n  captureFaceHint,\n  findOriginRole,\n  TopoRefError,\n  type EdgeTopoRef,\n  type FaceTopoRef,\n  type ResolutionContext,\n  type RoleQualifier,\n} from '../topology/naming'\nimport { buildEdgeResolutionContext, recoverEdgeFaceRole } from './topo-resolve'\nimport { resolveStepHandles } from './cadquery-selectors/resolve'\nimport type { P3 } from './cadquery-selectors/entity'\n\n/** 桥的静态前置：shape 必须是带 BREP 的活实体（选择器服务精度链）。 */\nfunction requireBrep(shape: Shape, what: string): BrepEngineApi {\n  const kernel = getBrepApi()\n  if (!kernel) {\n    throw new TopoRefError(\n      'E_TOPO_MESH_UNSUPPORTED',\n      'face',\n      `${what}: selector resolution is BREP-only (mesh path unsupported)`,\n    )\n  }\n  if (!hasBrep(shape)) {\n    throw new TopoRefError(\n      'E_TOPO_MESH_UNSUPPORTED',\n      'face',\n      `${what}: input shape has no BREP solid (mesh shapes do not carry topology identity)`,\n    )\n  }\n  return kernel\n}\n\n/** 取形状的 BREP solid 句柄（调用方已过 requireBrep，solid 必在）。 */\nfunction solidOf(shape: Shape, what: string): BrepHandle {\n  const solid = brepOf(shape) as BrepHandle | undefined\n  if (solid === undefined) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `${what}: input has no BREP solid`)\n  }\n  return solid\n}\n\n/**\n * 面句柄 → `FaceTopoRef`：在命名现场（ctx.faces）定位 ordinal → roleTable 反查\n * `{origin, role}`（miss 沿血缘回走恢复）→ 几何 hint。\n *\n * @param kernel - the active BREP engine.\n * @param shape - the live input shape (for nameOf lineage recovery).\n * @param ctx - the naming resolution context built from the shape.\n * @param handle - the selected face handle.\n * @returns the FaceTopoRef, or throws when the face has no role lineage.\n */\nfunction faceHandleToRef(\n  kernel: BrepEngineApi,\n  shape: Shape,\n  ctx: ResolutionContext,\n  handle: BrepHandle,\n): FaceTopoRef {\n  const idx = ctx.faces.findIndex(\n    (f) => f.handle !== undefined && kernel.isSame(f.handle, handle),\n  )\n  if (idx < 0) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'face',\n      'selector: resolved face is not in the naming context',\n    )\n  }\n  const ordinal = ctx.faces[idx].ordinal\n  const table = ctx.roleTable\n  if (!table) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'face',\n      'selector: input shape has no role table (nameless shape)',\n    )\n  }\n  const ordinalToHash = ctx.faces.map((f) => f.hash ?? 0)\n  let found = findOriginRole(table, ordinalToHash, ordinal)\n  if (!found) {\n    // 与 face-ref.ts 同构：目标 part 的 roleTable 缓存残缺但血缘可回走 → 恢复。\n    const part = nameOf(shape as object)\n    if (part) found = recoverEdgeFaceRole(kernel, part, ordinal, ordinalToHash)\n  }\n  if (!found) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'face',\n      `selector: resolved face ordinal ${ordinal} has no role lineage`,\n    )\n  }\n  return { kind: 'face', origin: found.origin, role: found.role, hint: captureFaceHint(kernel, handle) }\n}\n\n/**\n * 边句柄 → `EdgeTopoRef`：与 `edge-ref.ts` 同构——逐面枚举其边找邻面（不依赖\n * 邻接表下标对齐），两邻面的 role 对合成限定符 + 几何 hint。\n *\n * @param kernel - the active BREP engine.\n * @param shape - the live input shape (for nameOf lineage recovery).\n * @param ctx - the naming resolution context built from the shape.\n * @param handle - the selected edge handle.\n * @returns the EdgeTopoRef, or throws when the edge lacks a two-face role pair.\n */\nfunction edgeHandleToRef(\n  kernel: BrepEngineApi,\n  shape: Shape,\n  ctx: ResolutionContext,\n  handle: BrepHandle,\n): EdgeTopoRef {\n  const faceOrdinals: number[] = []\n  for (const f of ctx.faces) {\n    if (f.handle === undefined) continue\n    if (kernel.getSubShapes(f.handle, 'edge').some((eh) => kernel.isSame(eh, handle))) {\n      faceOrdinals.push(f.ordinal)\n    }\n  }\n  if (faceOrdinals.length < 2) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `selector: edge has ${faceOrdinals.length} adjacent face(s); an EdgeTopoRef needs a two-face pair`,\n    )\n  }\n\n  const table = ctx.roleTable\n  if (!table) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      'selector: input shape has no role table (nameless shape)',\n    )\n  }\n  const ordinalToHash = ctx.faces.map((f) => f.hash ?? 0)\n  const quals: RoleQualifier[] = []\n  for (const fo of faceOrdinals.slice(0, 2)) {\n    let found = findOriginRole(table, ordinalToHash, fo)\n    if (!found) {\n      const part = nameOf(shape as object)\n      if (part) found = recoverEdgeFaceRole(kernel, part, fo, ordinalToHash)\n    }\n    if (!found) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'edge',\n        `selector: adjacent face ordinal ${fo} has no role lineage`,\n      )\n    }\n    quals.push({ origin: found.origin, role: found.role })\n  }\n\n  const [qa, qb] = quals as [RoleQualifier, RoleQualifier]\n  return { kind: 'edge', faces: [qa, qb], hint: captureEdgeHint(kernel, handle) }\n}\n\n/**\n * 把面选择器字符串解析成 `FaceTopoRef[]`（选择器 → 句柄 → TopoRef 全链）。\n *\n * 示例：`\">Z\"`（Z 极值面）、`\"|Z\"`（法向平行 Z 的平面面）、`\"%PLANE\"`、\n * `\"top\"`（命名视图）、`\"|Z and %PLANE\"`（集合表达式）。\n *\n * @param shape - 目标几何（BREP 实体所在的 Shape；选择器服务精度链）。\n * @param sel - CadQuery 面选择器字符串。\n * @returns 选中面的 `FaceTopoRef[]`（保持选择器返回顺序）。\n * @throws {TopoRefError} 无 BREP / 选中面无 role 血统（不静默降级）。\n */\nexport function resolveSelectorToFaceRefs(shape: Shape, sel: string): FaceTopoRef[] {\n  const kernel = requireBrep(shape, 'resolveSelectorToFaceRefs')\n  const solid = solidOf(shape, 'resolveSelectorToFaceRefs')\n  const ctx = buildEdgeResolutionContext(kernel, shape as object)\n  if (!ctx) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'face',\n      'resolveSelectorToFaceRefs: input has no BREP naming context',\n    )\n  }\n  const handles = resolveStepHandles(solid, 'face', sel)\n  return handles.map((h) => faceHandleToRef(kernel, shape, ctx, h))\n}\n\n/**\n * 把边选择器字符串解析成 `EdgeTopoRef[]`（选择器 → 句柄 → TopoRef 全链）。\n *\n * 示例：`\"|Z\"`（切线平行 Z 的边）、`\">Z\"`（Z 极值边）、`\"%LINE\"`、\n * `\"#Z\"`（切线垂直 Z）。\n *\n * @param shape - 目标几何（BREP 实体所在的 Shape）。\n * @param sel - CadQuery 边选择器字符串。\n * @returns 选中边的 `EdgeTopoRef[]`（保持选择器返回顺序）。\n * @throws {TopoRefError} 无 BREP / 选中边邻面不足两面或无 role 血统。\n */\nexport function resolveSelectorToEdgeRefs(shape: Shape, sel: string): EdgeTopoRef[] {\n  const kernel = requireBrep(shape, 'resolveSelectorToEdgeRefs')\n  const solid = solidOf(shape, 'resolveSelectorToEdgeRefs')\n  const ctx = buildEdgeResolutionContext(kernel, shape as object)\n  if (!ctx) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      'resolveSelectorToEdgeRefs: input has no BREP naming context',\n    )\n  }\n  const handles = resolveStepHandles(solid, 'edge', sel)\n  return handles.map((h) => edgeHandleToRef(kernel, shape, ctx, h))\n}\n\n/**\n * 把顶点选择器字符串解析成顶点坐标 `P3[]`。\n *\n * 顶点没有角色身份（命名层只给面/边命名），故直接投影成世界坐标点——\n * 供未来需要「点」的 op（如打点/对齐）使用。\n *\n * @param shape - 目标几何（BREP 实体所在的 Shape）。\n * @param sel - CadQuery 顶点选择器字符串（如 `\">Z\"`、`\"(0,0,0)\"`，空串 = 全部）。\n * @returns 选中顶点的世界坐标（保持选择器返回顺序）。\n * @throws {TopoRefError} 无 BREP（顶点选择器只服务精度链）。\n */\nexport function resolveSelectorToVertexPts(shape: Shape, sel: string): P3[] {\n  const kernel = requireBrep(shape, 'resolveSelectorToVertexPts')\n  const solid = solidOf(shape, 'resolveSelectorToVertexPts')\n  const handles = resolveStepHandles(solid, 'vertex', sel)\n  return handles.map((h) => {\n    const p = kernel.vertexPosition(h)\n    return { x: p.x, y: p.y, z: p.z }\n  })\n}\n\n// ── op 参数输入归一（string 顶层或数组元素 → refs 展开）──────────────────\n\n/** 边选择器参数的一个条目：选择器字符串或 `EdgeTopoRef`。 */\nexport type EdgeSelectorEntry = EdgeTopoRef | string\n\n/** 面选择器参数的一个条目：选择器字符串或 `FaceTopoRef`。 */\nexport type FaceSelectorEntry = FaceTopoRef | string\n\n/**\n * 展开 op 的边选择器参数（顶层字符串或数组元素字符串）到 `EdgeTopoRef[]`。\n *\n * 形态（方案 D2-A）：`edges: \"|Z\"`、`edges: [\"|Z\"]`、`edges: [\"|Z\", refA]` 均可。\n * 数组里的 `EdgeTopoRef` 原样保留；字符串逐个经桥解析（保持出现顺序）。\n *\n * @param shape - 目标几何（BREP 实体所在的 Shape）。\n * @param edges - 边选择器参数（字符串 = 单一选择器；数组元素可为选择器字符串或 EdgeTopoRef）。\n * @returns 展开后的 `EdgeTopoRef[]`。\n */\nexport function expandEdgeSelectorRefs(\n  shape: Shape,\n  edges: EdgeSelectorEntry[] | string,\n): EdgeTopoRef[] {\n  if (typeof edges === 'string') return resolveSelectorToEdgeRefs(shape, edges)\n  return edges.flatMap((e) => (typeof e === 'string' ? resolveSelectorToEdgeRefs(shape, e) : [e]))\n}\n\n/**\n * 展开 op 的面选择器参数（顶层字符串或数组元素字符串）到 `FaceTopoRef[]`。\n *\n * 形态（方案 D2-A）：`openFaces: \">Z\"`、`faces: [\"|Z\"]`、`faces: [\"|Z\", refA]` 均可。\n *\n * @param shape - 目标几何（BREP 实体所在的 Shape）。\n * @param faces - 面选择器参数（字符串 = 单一选择器；数组元素可为选择器字符串或 FaceTopoRef）。\n * @returns 展开后的 `FaceTopoRef[]`。\n */\nexport function expandFaceSelectorRefs(\n  shape: Shape,\n  faces: FaceSelectorEntry[] | string,\n): FaceTopoRef[] {\n  if (typeof faces === 'string') return resolveSelectorToFaceRefs(shape, faces)\n  return faces.flatMap((f) => (typeof f === 'string' ? resolveSelectorToFaceRefs(shape, f) : [f]))\n}\n"]}

package/dist/api/shell.d.ts

@@ -16,12 +16,15 @@
  */
 import type { Shape } from '../mesh/types.js';
 import type { FaceTopoRef } from '../topology/naming/index.js';
-/** 抽壳时移除的面选择器：精度链用 `FaceTopoRef`；网格链也可用 1 起序号。 */
-export type ShellFaceSelector = number | FaceTopoRef;
+/**
+ * 抽壳时移除的面选择器：精度链用 `FaceTopoRef`（UI 拾取产物）或 CadQuery 面选择器
+ * 字符串（AI 生成，如 `">Z"` / `"|Z"` / `"%PLANE"`）；网格链也可用 1 起序号。
+ */
+export type ShellFaceSelector = number | FaceTopoRef | string;
 /** `cad.shell` 参数。 */
 export interface ShellParams {
-    /** 抽壳时移除的面（FaceTopoRef[]，`cad.faceRef` 产物；空数组 = 全封闭薄壁）。 */
-    openFaces: ShellFaceSelector[];
+    /** 抽壳时移除的面：面选择器字符串（`">Z"` 等）、或 FaceTopoRef/序号/选择器字符串数组（空数组 = 全封闭薄壁）。 */
+    openFaces: ShellFaceSelector[] | string;
     /** 壁厚（mm，>0，向内偏置）。 */
     thickness: number;
     /** 容差（mm，可选；默认走内核约定值）。 */
@@ -35,15 +38,21 @@ export interface ShellParams {
  * @qual ok
  * @name shell
  * @note 中立 op：L1 shell 两引擎同实现。`openFaces` 为空数组时生成全封闭薄壁。
- *       精度链按 role 线路选面（`cad.faceRef`）；网格链按序号或几何选面——网格零件
- *       没有 role 层，序号是唯一无歧义的指认方式。
+ *       精度链按 role 线路选面（TopoRef 字面量或 CadQuery 面选择器字符串）；
+ *       **禁止 `cad.faceRef` 序号**——序号跨内核不可移植。网格链没有 role 层，
+ *       序号是唯一无歧义的指认方式（仅当前内核快照），选择器字符串只服务精度链。
  * @returns Shape 抽壳后的薄壁体。
  * @param input - 目标几何。type:Shape required:true
- * @param params.openFaces - 要移除的面（FaceTopoRef[]，cad.faceRef 产物；网格链可用 1 起序号）。type:FaceTopoRef[] required:true
+ * @param params.openFaces - 要移除的面：面选择器字符串（如 ">Z"，AI 生成）或 FaceTopoRef[]（UI 拾取产物字面量；禁止 cad.faceRef 序号；网格链可用 1 起序号）。type:ShellFaceSelector[]|string required:true
  * @param params.thickness - 壁厚（mm，>0）。type:number required:true
  * @param params.tolerance - 容差（mm）。type:number required:false
  * @example
- * const sh = await cad.shell(part0, { openFaces: [cad.faceRef(part0, 1)], thickness: 2 })
+ * // openFaces 取 UI 拾取产物的 FaceTopoRef 字面量（origin/role 由命名层分配，不手写）；
+ * // ❌ 不要用 cad.faceRef 序号——跨内核不可移植
+ * const sh = await cad.shell(part0, { openFaces: pickedFaces, thickness: 2 })
+ * // AI 生成可写 CadQuery 面选择器字符串（"|Z" 法向平行 Z 的面、"top" 命名视图）
+ * const sh2 = await cad.shell(part0, { openFaces: "|Z", thickness: 2 })
+ * // 网格链（3MF mesh-solid）：无 role 层，序号是唯一无歧义指认（仅当前内核快照）
  * const sm = await cad.shell(meshPart, { openFaces: [4], thickness: 2 })
  */
 export declare const shell: ((input: Shape, params: ShellParams) => Promise<Shape>) & {

package/dist/api/shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/api/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAQ1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAMrD,kDAAkD;AAClD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,WAAW,CAAA;AAEpD,sBAAsB;AACtB,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,SAAS,EAAE,iBAAiB,EAAE,CAAA;IAC9B,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAqFD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK;;CAWhB,CAAA"}
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/api/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAQ1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAOrD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;AAE7D,sBAAsB;AACtB,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,SAAS,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAA;IACvC,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAqHD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,KAAK;;CAWhB,CAAA"}

package/dist/api/shell.js

@@ -23,16 +23,43 @@ import { hasNativeHistory } from '../brep/engine/native-history.js';
 import { resolveTopoRef, TopoRefError } from '../topology/naming/index.js';
 import { buildEdgeResolutionContext } from './topo-resolve.js';
 import { meshKernelFailure, meshSolidBasicEntry, meshSolidProduct, resolveMeshFaces } from './internal/mesh-solid-op.js';
+import { resolveSelectorToFaceRefs } from './selectors-to-refs.js';
 /** 参数共校验（两条路径共用；`openFaces` 为空数组合法 = 全封闭薄壁）。 */
 function assertShellParams(params) {
     const { openFaces, thickness } = params ?? {};
-    if (!Array.isArray(openFaces)) {
-        throw new Error('E_SHELL_BAD_OPEN_FACES: shell.openFaces must be an array of FaceTopoRef or ordinals');
+    const openFacesOk = typeof openFaces === 'string' ||
+        (Array.isArray(openFaces) &&
+            openFaces.every((s) => typeof s === 'string' ||
+                typeof s === 'number' ||
+                (!!s && typeof s === 'object' && s.kind === 'face')));
+    if (!openFacesOk) {
+        throw new Error('E_SHELL_BAD_OPEN_FACES: shell.openFaces must be a face selector string, or an array of FaceTopoRef / ordinal / selector string');
     }
     if (typeof thickness !== 'number' || !Number.isFinite(thickness) || thickness <= 0) {
         throw new Error('E_SHELL_BAD_THICKNESS: shell.thickness must be a positive number');
     }
 }
+/**
+ * 展开 `openFaces` 到 `FaceTopoRef` 列表（BREP 路径）：选择器字符串 → 桥解析；
+ * `FaceTopoRef` 原样保留；**序号在精度链抛错**（BREP 面身份是 `(origin, role)`，
+ * 序号只是本次枚举序，见 shellBrep 原注释）。
+ */
+function expandShellFaceRefs(input, openFaces) {
+    if (typeof openFaces === 'string')
+        return resolveSelectorToFaceRefs(input, openFaces);
+    return openFaces.flatMap((sel) => {
+        if (typeof sel === 'string')
+            return resolveSelectorToFaceRefs(input, sel);
+        if (typeof sel === 'number') {
+            throw new Error('E_SHELL_BAD_OPEN_FACES: an ordinal face selector is only available on the mesh chain — ' +
+                'a precision-chain face is identified by its role line (cad.faceRef) or a selector string');
+        }
+        if (!sel || sel.kind !== 'face') {
+            throw new Error('E_SHELL_BAD_OPEN_FACES: every openFaces entry must be a FaceTopoRef (cad.faceRef) or a selector string');
+        }
+        return [sel];
+    });
+}
 /** BREP 路径：解析面引用 → L1 shell → 收养。 */
 function shellBrep(input, params) {
     const { openFaces, thickness, tolerance } = params;
@@ -44,15 +71,7 @@ function shellBrep(input, params) {
     const ctx = buildEdgeResolutionContext(kernel, input);
     if (!ctx)
         throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'shell: input has no BREP naming context');
-    const faceHandles = openFaces.map((ref) => {
-        // 精度链不开序号口子：BREP 的面身份是 `(origin, role)`，序号只是本次枚举序。
-        if (typeof ref === 'number') {
-            throw new Error('E_SHELL_BAD_OPEN_FACES: an ordinal face selector is only available on the mesh chain — ' +
-                'a precision-chain face is identified by its role line (cad.faceRef)');
-        }
-        if (!ref || ref.kind !== 'face') {
-            throw new Error('E_SHELL_BAD_OPEN_FACES: every openFaces entry must be a FaceTopoRef (cad.faceRef)');
-        }
+    const faceHandles = expandShellFaceRefs(input, openFaces).map((ref) => {
         const r = resolveTopoRef(ref, ctx);
         if (r.handle === undefined) {
             throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `shell: face resolved without handle (${ref.origin}/${ref.role})`);
@@ -86,6 +105,11 @@ function shellMeshSolid(input, params) {
     const { openFaces, thickness, tolerance } = params;
     assertShellParams(params);
     const entry = meshSolidBasicEntry(input, 'shell');
+    // 选择器字符串只服务精度链：网格零件没有 role 层，选择器命中无名实体转
+    // TopoRef 必然失败（方案 R1），显式抛错而非静默降级；网格链用 1 起序号。
+    if (typeof openFaces === 'string' || openFaces.some((s) => typeof s === 'string')) {
+        throw new TopoRefError('E_TOPO_MESH_UNSUPPORTED', 'face', 'shell: selector strings are precision-chain only — mesh solids have no role layer (use 1-based face ordinals)');
+    }
     const faceHandles = resolveMeshFaces(entry.kernel, input, openFaces, 'shell');
     let result;
     try {
@@ -104,15 +128,21 @@ function shellMeshSolid(input, params) {
  * @qual ok
  * @name shell
  * @note 中立 op：L1 shell 两引擎同实现。`openFaces` 为空数组时生成全封闭薄壁。
- *       精度链按 role 线路选面（`cad.faceRef`）；网格链按序号或几何选面——网格零件
- *       没有 role 层，序号是唯一无歧义的指认方式。
+ *       精度链按 role 线路选面（TopoRef 字面量或 CadQuery 面选择器字符串）；
+ *       **禁止 `cad.faceRef` 序号**——序号跨内核不可移植。网格链没有 role 层，
+ *       序号是唯一无歧义的指认方式（仅当前内核快照），选择器字符串只服务精度链。
  * @returns Shape 抽壳后的薄壁体。
  * @param input - 目标几何。type:Shape required:true
- * @param params.openFaces - 要移除的面（FaceTopoRef[]，cad.faceRef 产物；网格链可用 1 起序号）。type:FaceTopoRef[] required:true
+ * @param params.openFaces - 要移除的面：面选择器字符串（如 ">Z"，AI 生成）或 FaceTopoRef[]（UI 拾取产物字面量；禁止 cad.faceRef 序号；网格链可用 1 起序号）。type:ShellFaceSelector[]|string required:true
  * @param params.thickness - 壁厚（mm，>0）。type:number required:true
  * @param params.tolerance - 容差（mm）。type:number required:false
  * @example
- * const sh = await cad.shell(part0, { openFaces: [cad.faceRef(part0, 1)], thickness: 2 })
+ * // openFaces 取 UI 拾取产物的 FaceTopoRef 字面量（origin/role 由命名层分配，不手写）；
+ * // ❌ 不要用 cad.faceRef 序号——跨内核不可移植
+ * const sh = await cad.shell(part0, { openFaces: pickedFaces, thickness: 2 })
+ * // AI 生成可写 CadQuery 面选择器字符串（"|Z" 法向平行 Z 的面、"top" 命名视图）
+ * const sh2 = await cad.shell(part0, { openFaces: "|Z", thickness: 2 })
+ * // 网格链（3MF mesh-solid）：无 role 层，序号是唯一无歧义指认（仅当前内核快照）
  * const sm = await cad.shell(meshPart, { openFaces: [4], thickness: 2 })
  */
 export const shell = defineOp({

package/dist/api/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/api/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEhE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAerH,gDAAgD;AAChD,SAAS,iBAAiB,CAAC,MAAmB;IAC5C,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,IAAK,EAAkB,CAAA;IAC9D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,qFAAqF,CAAC,CAAA;IACxG,CAAC;IACD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAA;IACrF,CAAC;AACH,CAAC;AAED,qCAAqC;AACrC,SAAS,SAAS,CAAC,KAAY,EAAE,MAAmB;IAClD,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IAClD,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAA2B,CAAA;IACrD,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;IAEpF,MAAM,GAAG,GAAG,0BAA0B,CAAC,MAAM,EAAE,KAAe,CAAC,CAAA;IAC/D,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,yCAAyC,CAAC,CAAA;IACvG,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACxC,mDAAmD;QACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,yFAAyF;gBACzF,qEAAqE,CACtE,CAAA;QACH,CAAC;QACD,IAAI,CAAC,GAAG,IAAK,GAA0B,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CAAC,mFAAmF,CAAC,CAAA;QACtG,CAAC;QACD,MAAM,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QAClC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,wCAAwC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,CAAA;QACvH,CAAC;QACD,OAAO,CAAC,CAAC,MAAoB,CAAA;IAC/B,CAAC,CAAC,CAAA;IAEF,iCAAiC;IACjC,gDAAgD;IAChD,kDAAkD;IAClD,uBAAuB;IACvB,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,sBAAsB,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,CAAA;QAC1F,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC,CAAA;IACtG,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,CAAA;IAC7E,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AAClE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,cAAc,CAAC,KAAY,EAAE,MAAmB;IACvD,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IAClD,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IACjD,MAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;IAE7E,IAAI,MAAkB,CAAA;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,CAAA;IACrF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,iBAAiB,CACrB,OAAO,EACP,gBAAgB,EAChB,mBAAmB,SAAS,cAAc,WAAW,CAAC,MAAM,UAAU,EACtE,KAAK,CACN,CAAA;IACH,CAAC;IACD,OAAO,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,WAAW,EAAE,CAAC,SAAS,CAAC;IACxB,IAAI,CAAC,KAAY,EAAE,MAAmB;QACpC,OAAO,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACtC,CAAC;IACD,IAAI,CAAC,KAAY,EAAE,MAAmB;QACpC,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACjC,CAAC;IACD,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,EAAgB;IAE1E,SAAS,EAAE,EAAE;CACd,CAAC,CAAA","sourcesContent":["/**\n * api shell — 抽壳：按面移除生成等厚薄壁（手写中立 op，Phase 5）\n *\n * 中立 op：L1 `shell(solid, facesToRemove, thickness, tolerance)` 在 occt 与\n * brepkit 两侧均有真实现（engine-method-map 实测 `dialect`）⇒ 走 `getBrepApi()`\n * （D12），不声明 engines（中立 op：实现只经 L1 契约面）。相对现状是\n * 覆盖面扩大——旧版是 occt 平台 op（arg-spec `engines:['occt']`，skip）。\n *\n * 选面口径（设计原则 4）：`openFaces: FaceTopoRef[]`（`cad.faceRef` 产物），\n * 与 `fillet` 的 `EdgeTopoRef[]` / `extrude` 的 `upTo` 同族；不复刻旧\n * `Face[]` 句柄入参。解析在 op 内一处完成（`buildEdgeResolutionContext` 现场枚举\n * + `resolveTopoRef`）。\n *\n * 网格链（方案 2026-10-01 §4 Phase 4 / B3 批）：`mesh:` 实现走网格后端，面按\n * **序号或 FaceTopoRef** 解析（近似拓扑没有 role 层），产物是新的网格零件。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { shellWithHashEvolution } from '../brep/face-evolution'\nimport { brepOf, fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport { hasNativeHistory } from '../brep/engine/native-history'\nimport type { FaceTopoRef } from '../topology/naming'\nimport { resolveTopoRef, TopoRefError } from '../topology/naming'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { buildEdgeResolutionContext } from './topo-resolve'\nimport { meshKernelFailure, meshSolidBasicEntry, meshSolidProduct, resolveMeshFaces } from './internal/mesh-solid-op'\n\n/** 抽壳时移除的面选择器：精度链用 `FaceTopoRef`；网格链也可用 1 起序号。 */\nexport type ShellFaceSelector = number | FaceTopoRef\n\n/** `cad.shell` 参数。 */\nexport interface ShellParams {\n  /** 抽壳时移除的面（FaceTopoRef[]，`cad.faceRef` 产物；空数组 = 全封闭薄壁）。 */\n  openFaces: ShellFaceSelector[]\n  /** 壁厚（mm，>0，向内偏置）。 */\n  thickness: number\n  /** 容差（mm，可选；默认走内核约定值）。 */\n  tolerance?: number\n}\n\n/** 参数共校验（两条路径共用；`openFaces` 为空数组合法 = 全封闭薄壁）。 */\nfunction assertShellParams(params: ShellParams): void {\n  const { openFaces, thickness } = params ?? ({} as ShellParams)\n  if (!Array.isArray(openFaces)) {\n    throw new Error('E_SHELL_BAD_OPEN_FACES: shell.openFaces must be an array of FaceTopoRef or ordinals')\n  }\n  if (typeof thickness !== 'number' || !Number.isFinite(thickness) || thickness <= 0) {\n    throw new Error('E_SHELL_BAD_THICKNESS: shell.thickness must be a positive number')\n  }\n}\n\n/** BREP 路径：解析面引用 → L1 shell → 收养。 */\nfunction shellBrep(input: Shape, params: ShellParams): Shape {\n  const { openFaces, thickness, tolerance } = params\n  assertShellParams(params)\n  const kernel = getBrepApi()\n  const solid = brepOf(input) as BrepHandle | undefined\n  if (solid === undefined) throw new Error('E_SHELL_NO_BREP: shell input is not BREP')\n\n  const ctx = buildEdgeResolutionContext(kernel, input as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'shell: input has no BREP naming context')\n  const faceHandles = openFaces.map((ref) => {\n    // 精度链不开序号口子：BREP 的面身份是 `(origin, role)`，序号只是本次枚举序。\n    if (typeof ref === 'number') {\n      throw new Error(\n        'E_SHELL_BAD_OPEN_FACES: an ordinal face selector is only available on the mesh chain — ' +\n        'a precision-chain face is identified by its role line (cad.faceRef)',\n      )\n    }\n    if (!ref || (ref as { kind?: unknown }).kind !== 'face') {\n      throw new Error('E_SHELL_BAD_OPEN_FACES: every openFaces entry must be a FaceTopoRef (cad.faceRef)')\n    }\n    const r = resolveTopoRef(ref, ctx)\n    if (r.handle === undefined) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `shell: face resolved without handle (${ref.origin}/${ref.role})`)\n    }\n    return r.handle as BrepHandle\n  })\n\n  // C5 实现面接入（静态双轨，无运行时 try-catch）：\n  // - occt 原生有 `shellWithHistory` → 走权威面演化（血缘更准）；\n  // - brepkit 没有 → 显式回退裸 L1 `shell`（**不报错**），不伪造面演化\n  //   （抽壳是毁面重造，恒等映射不真实）。\n  if (hasNativeHistory('shellWithHistory')) {\n    const r = shellWithHashEvolution(kernel, solid, faceHandles, thickness, tolerance ?? 1e-6)\n    return fromBrep(solidToShape(kernel, r.result), { solid: r.result, faceEvolution: r.faceEvolution })\n  }\n  const result = kernel.shell(solid, faceHandles, thickness, tolerance ?? 1e-6)\n  return fromBrep(solidToShape(kernel, result), { solid: result })\n}\n\n/**\n * 网格实体路径：按序号或几何选出要开口的面，交网格后端抽壳。\n *\n * 与 BREP 路径同一条 L1 契约面（`shell(solid, faces, thickness, tolerance)`），\n * 差别只在选面方式：近似拓扑没有 role 层，面靠**序号**（拓扑 `faces` 数组下标 + 1）\n * 或 `FaceTopoRef` 的几何匹配（法向/中心/面积）指认。产物是新网格零件，\n * 近似拓扑由 `meshSolidProduct` 重建。\n *\n * @param input - the mesh-solid input.\n * @param params - the shell parameters.\n * @returns the shelled mesh solid as a new mesh part.\n */\nfunction shellMeshSolid(input: Shape, params: ShellParams): Shape {\n  const { openFaces, thickness, tolerance } = params\n  assertShellParams(params)\n  const entry = meshSolidBasicEntry(input, 'shell')\n  const faceHandles = resolveMeshFaces(entry.kernel, input, openFaces, 'shell')\n\n  let result: BrepHandle\n  try {\n    result = entry.kernel.shell(entry.solid, faceHandles, thickness, tolerance ?? 1e-6)\n  } catch (cause) {\n    throw meshKernelFailure(\n      'shell',\n      'E_SHELL_FAILED',\n      `shell(thickness=${thickness}) removing ${faceHandles.length} face(s)`,\n      cause,\n    )\n  }\n  return meshSolidProduct(entry, result)\n}\n\n/**\n * 抽壳：移除指定面并把余下面偏置成等厚薄壁。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name shell\n * @note 中立 op：L1 shell 两引擎同实现。`openFaces` 为空数组时生成全封闭薄壁。\n *       精度链按 role 线路选面（`cad.faceRef`）；网格链按序号或几何选面——网格零件\n *       没有 role 层，序号是唯一无歧义的指认方式。\n * @returns Shape 抽壳后的薄壁体。\n * @param input - 目标几何。type:Shape required:true\n * @param params.openFaces - 要移除的面（FaceTopoRef[]，cad.faceRef 产物；网格链可用 1 起序号）。type:FaceTopoRef[] required:true\n * @param params.thickness - 壁厚（mm，>0）。type:number required:true\n * @param params.tolerance - 容差（mm）。type:number required:false\n * @example\n * const sh = await cad.shell(part0, { openFaces: [cad.faceRef(part0, 1)], thickness: 2 })\n * const sm = await cad.shell(meshPart, { openFaces: [4], thickness: 2 })\n */\nexport const shell = defineOp({\n  meshEngines: ['brepkit'],\n  mesh(input: Shape, params: ShellParams) {\n    return shellMeshSolid(input, params)\n  },\n  brep(input: Shape, params: ShellParams) {\n    return shellBrep(input, params)\n  },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n\n  paramDims: {},\n})\n"]}
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/api/shell.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api shell — 抽壳：按面移除生成等厚薄壁（手写中立 op，Phase 5）\n *\n * 中立 op：L1 `shell(solid, facesToRemove, thickness, tolerance)` 在 occt 与\n * brepkit 两侧均有真实现（engine-method-map 实测 `dialect`）⇒ 走 `getBrepApi()`\n * （D12），不声明 engines（中立 op：实现只经 L1 契约面）。相对现状是\n * 覆盖面扩大——旧版是 occt 平台 op（arg-spec `engines:['occt']`，skip）。\n *\n * 选面口径（设计原则 4）：`openFaces: FaceTopoRef[]`（`cad.faceRef` 产物），\n * 与 `fillet` 的 `EdgeTopoRef[]` / `extrude` 的 `upTo` 同族；不复刻旧\n * `Face[]` 句柄入参。解析在 op 内一处完成（`buildEdgeResolutionContext` 现场枚举\n * + `resolveTopoRef`）。\n *\n * 网格链（方案 2026-10-01 §4 Phase 4 / B3 批）：`mesh:` 实现走网格后端，面按\n * **序号或 FaceTopoRef** 解析（近似拓扑没有 role 层），产物是新的网格零件。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { shellWithHashEvolution } from '../brep/face-evolution'\nimport { brepOf, fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport { hasNativeHistory } from '../brep/engine/native-history'\nimport type { FaceTopoRef } from '../topology/naming'\nimport { resolveTopoRef, TopoRefError } from '../topology/naming'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { buildEdgeResolutionContext } from './topo-resolve'\nimport { meshKernelFailure, meshSolidBasicEntry, meshSolidProduct, resolveMeshFaces } from './internal/mesh-solid-op'\nimport { resolveSelectorToFaceRefs } from './selectors-to-refs'\n\n/**\n * 抽壳时移除的面选择器：精度链用 `FaceTopoRef`（UI 拾取产物）或 CadQuery 面选择器\n * 字符串（AI 生成，如 `\">Z\"` / `\"|Z\"` / `\"%PLANE\"`）；网格链也可用 1 起序号。\n */\nexport type ShellFaceSelector = number | FaceTopoRef | string\n\n/** `cad.shell` 参数。 */\nexport interface ShellParams {\n  /** 抽壳时移除的面：面选择器字符串（`\">Z\"` 等）、或 FaceTopoRef/序号/选择器字符串数组（空数组 = 全封闭薄壁）。 */\n  openFaces: ShellFaceSelector[] | string\n  /** 壁厚（mm，>0，向内偏置）。 */\n  thickness: number\n  /** 容差（mm，可选；默认走内核约定值）。 */\n  tolerance?: number\n}\n\n/** 参数共校验（两条路径共用；`openFaces` 为空数组合法 = 全封闭薄壁）。 */\nfunction assertShellParams(params: ShellParams): void {\n  const { openFaces, thickness } = params ?? ({} as ShellParams)\n  const openFacesOk =\n    typeof openFaces === 'string' ||\n    (Array.isArray(openFaces) &&\n      openFaces.every(\n        (s) =>\n          typeof s === 'string' ||\n          typeof s === 'number' ||\n          (!!s && typeof s === 'object' && (s as { kind?: unknown }).kind === 'face'),\n      ))\n  if (!openFacesOk) {\n    throw new Error(\n      'E_SHELL_BAD_OPEN_FACES: shell.openFaces must be a face selector string, or an array of FaceTopoRef / ordinal / selector string',\n    )\n  }\n  if (typeof thickness !== 'number' || !Number.isFinite(thickness) || thickness <= 0) {\n    throw new Error('E_SHELL_BAD_THICKNESS: shell.thickness must be a positive number')\n  }\n}\n\n/**\n * 展开 `openFaces` 到 `FaceTopoRef` 列表（BREP 路径）：选择器字符串 → 桥解析；\n * `FaceTopoRef` 原样保留；**序号在精度链抛错**（BREP 面身份是 `(origin, role)`，\n * 序号只是本次枚举序，见 shellBrep 原注释）。\n */\nfunction expandShellFaceRefs(input: Shape, openFaces: ShellFaceSelector[] | string): FaceTopoRef[] {\n  if (typeof openFaces === 'string') return resolveSelectorToFaceRefs(input, openFaces)\n  return openFaces.flatMap((sel) => {\n    if (typeof sel === 'string') return resolveSelectorToFaceRefs(input, sel)\n    if (typeof sel === 'number') {\n      throw new Error(\n        'E_SHELL_BAD_OPEN_FACES: an ordinal face selector is only available on the mesh chain — ' +\n          'a precision-chain face is identified by its role line (cad.faceRef) or a selector string',\n      )\n    }\n    if (!sel || (sel as { kind?: unknown }).kind !== 'face') {\n      throw new Error('E_SHELL_BAD_OPEN_FACES: every openFaces entry must be a FaceTopoRef (cad.faceRef) or a selector string')\n    }\n    return [sel]\n  })\n}\n\n/** BREP 路径：解析面引用 → L1 shell → 收养。 */\nfunction shellBrep(input: Shape, params: ShellParams): Shape {\n  const { openFaces, thickness, tolerance } = params\n  assertShellParams(params)\n  const kernel = getBrepApi()\n  const solid = brepOf(input) as BrepHandle | undefined\n  if (solid === undefined) throw new Error('E_SHELL_NO_BREP: shell input is not BREP')\n\n  const ctx = buildEdgeResolutionContext(kernel, input as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'shell: input has no BREP naming context')\n  const faceHandles = expandShellFaceRefs(input, openFaces).map((ref) => {\n    const r = resolveTopoRef(ref, ctx)\n    if (r.handle === undefined) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `shell: face resolved without handle (${ref.origin}/${ref.role})`)\n    }\n    return r.handle as BrepHandle\n  })\n\n  // C5 实现面接入（静态双轨，无运行时 try-catch）：\n  // - occt 原生有 `shellWithHistory` → 走权威面演化（血缘更准）；\n  // - brepkit 没有 → 显式回退裸 L1 `shell`（**不报错**），不伪造面演化\n  //   （抽壳是毁面重造，恒等映射不真实）。\n  if (hasNativeHistory('shellWithHistory')) {\n    const r = shellWithHashEvolution(kernel, solid, faceHandles, thickness, tolerance ?? 1e-6)\n    return fromBrep(solidToShape(kernel, r.result), { solid: r.result, faceEvolution: r.faceEvolution })\n  }\n  const result = kernel.shell(solid, faceHandles, thickness, tolerance ?? 1e-6)\n  return fromBrep(solidToShape(kernel, result), { solid: result })\n}\n\n/**\n * 网格实体路径：按序号或几何选出要开口的面，交网格后端抽壳。\n *\n * 与 BREP 路径同一条 L1 契约面（`shell(solid, faces, thickness, tolerance)`），\n * 差别只在选面方式：近似拓扑没有 role 层，面靠**序号**（拓扑 `faces` 数组下标 + 1）\n * 或 `FaceTopoRef` 的几何匹配（法向/中心/面积）指认。产物是新网格零件，\n * 近似拓扑由 `meshSolidProduct` 重建。\n *\n * @param input - the mesh-solid input.\n * @param params - the shell parameters.\n * @returns the shelled mesh solid as a new mesh part.\n */\nfunction shellMeshSolid(input: Shape, params: ShellParams): Shape {\n  const { openFaces, thickness, tolerance } = params\n  assertShellParams(params)\n  const entry = meshSolidBasicEntry(input, 'shell')\n  // 选择器字符串只服务精度链：网格零件没有 role 层，选择器命中无名实体转\n  // TopoRef 必然失败（方案 R1），显式抛错而非静默降级；网格链用 1 起序号。\n  if (typeof openFaces === 'string' || openFaces.some((s) => typeof s === 'string')) {\n    throw new TopoRefError(\n      'E_TOPO_MESH_UNSUPPORTED',\n      'face',\n      'shell: selector strings are precision-chain only — mesh solids have no role layer (use 1-based face ordinals)',\n    )\n  }\n  const faceHandles = resolveMeshFaces(entry.kernel, input, openFaces as (number | FaceTopoRef)[], 'shell')\n\n  let result: BrepHandle\n  try {\n    result = entry.kernel.shell(entry.solid, faceHandles, thickness, tolerance ?? 1e-6)\n  } catch (cause) {\n    throw meshKernelFailure(\n      'shell',\n      'E_SHELL_FAILED',\n      `shell(thickness=${thickness}) removing ${faceHandles.length} face(s)`,\n      cause,\n    )\n  }\n  return meshSolidProduct(entry, result)\n}\n\n/**\n * 抽壳：移除指定面并把余下面偏置成等厚薄壁。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name shell\n * @note 中立 op：L1 shell 两引擎同实现。`openFaces` 为空数组时生成全封闭薄壁。\n *       精度链按 role 线路选面（TopoRef 字面量或 CadQuery 面选择器字符串）；\n *       **禁止 `cad.faceRef` 序号**——序号跨内核不可移植。网格链没有 role 层，\n *       序号是唯一无歧义的指认方式（仅当前内核快照），选择器字符串只服务精度链。\n * @returns Shape 抽壳后的薄壁体。\n * @param input - 目标几何。type:Shape required:true\n * @param params.openFaces - 要移除的面：面选择器字符串（如 \">Z\"，AI 生成）或 FaceTopoRef[]（UI 拾取产物字面量；禁止 cad.faceRef 序号；网格链可用 1 起序号）。type:ShellFaceSelector[]|string required:true\n * @param params.thickness - 壁厚（mm，>0）。type:number required:true\n * @param params.tolerance - 容差（mm）。type:number required:false\n * @example\n * // openFaces 取 UI 拾取产物的 FaceTopoRef 字面量（origin/role 由命名层分配，不手写）；\n * // ❌ 不要用 cad.faceRef 序号——跨内核不可移植\n * const sh = await cad.shell(part0, { openFaces: pickedFaces, thickness: 2 })\n * // AI 生成可写 CadQuery 面选择器字符串（\"|Z\" 法向平行 Z 的面、\"top\" 命名视图）\n * const sh2 = await cad.shell(part0, { openFaces: \"|Z\", thickness: 2 })\n * // 网格链（3MF mesh-solid）：无 role 层，序号是唯一无歧义指认（仅当前内核快照）\n * const sm = await cad.shell(meshPart, { openFaces: [4], thickness: 2 })\n */\nexport const shell = defineOp({\n  meshEngines: ['brepkit'],\n  mesh(input: Shape, params: ShellParams) {\n    return shellMeshSolid(input, params)\n  },\n  brep(input: Shape, params: ShellParams) {\n    return shellBrep(input, params)\n  },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n\n  paramDims: {},\n})\n"]}

package/dist/api/sketch-on-face.d.ts

@@ -36,15 +36,17 @@ import type { BrepHandle } from '../brep/engine/types.js';
 import { type FaceTopoRef } from '../topology/naming/index.js';
 import { type FaceScaleMode } from '../geometry2d/bridge/on-surface.js';
 import { type ProfileLoop } from './profile.js';
-/** A face selector on a target solid: a 1-based ordinal (FreeCAD `FaceN`) or a `cad.faceRef` result. */
-export type FaceSelector = number | FaceTopoRef;
+/** A face selector on a target solid: a 1-based ordinal (FreeCAD `FaceN`, mesh chain /
+ * current kernel snapshot only), a `cad.faceRef` result, or a CadQuery face selector
+ * string (e.g. `">Z"` — precision chain, resolved on `on`). */
+export type FaceSelector = number | FaceTopoRef | string;
 /** Contour loops + the target face for `cad.sketchOnFace`. */
 export interface SketchOnFaceParams {
     /** Ordered 2D closed contours (same shape as `cad.profile` / `cad.sketchOnPlane`). */
     contours: ProfileLoop[];
     /** The target solid on which the host face lives. */
     on: Shape;
-    /** The host face: a 1-based face ordinal, or a `cad.faceRef(on, n)` result. */
+    /** The host face: a FaceTopoRef (UI-picked literal), a CadQuery face selector string (e.g. ">Z", resolved on `on`), or a 1-based face ordinal (mesh chain / current kernel snapshot only). */
     face: FaceSelector;
     /** How 2D coords map onto the face UV space: `'original'` (identity) | `'bounds'`/`'native'` (affine-fit). */
     scaleMode?: FaceScaleMode;
@@ -52,10 +54,11 @@ export interface SketchOnFaceParams {
     as?: 'face' | 'wire';
 }
 /**
- * Resolve a face on `on` to its live BREP handle (1-based ordinal or `cad.faceRef`).
+ * Resolve a face on `on` to its live BREP handle (1-based ordinal, `cad.faceRef`,
+ * or CadQuery face selector string resolved on `on`).
  * @param kernel - the BREP engine surface.
  * @param on - the target solid shape.
- * @param selector - the face ordinal or `cad.faceRef` result.
+ * @param selector - the face ordinal, `cad.faceRef` result, or selector string.
  * @returns the live face handle.
  */
 export declare function resolveFaceHandle(kernel: BrepEngineApi, on: Shape, selector: FaceSelector): BrepHandle;
@@ -120,9 +123,12 @@ export declare function buildSketchOnFaceMesh(params: SketchOnFaceParams): Shape
  * @returns Shape on the target face (face, or a wire curve when `as:'wire'`).
  * @param params.contours - ordered 2D closed contours (same shape as `cad.profile`).type:any[] required:true
  * @param params.on - the target solid on which the face lives.type:Shape required:true
- * @param params.face - the host face: a 1-based ordinal or a `cad.faceRef(on, n)` result.type:any required:true
+ * @param params.face - the host face: FaceTopoRef（UI 拾取产物字面量）| 面选择器字符串（如 ">Z"，在 on 上解析，多面命中抛错）| 1 起序号（仅网格链/当前内核快照，禁止用于生成脚本）。type:any required:true
  * @param params.scaleMode - UV mapping: 'original' (identity) | 'bounds'/'native' (affine-fit; OCCT planar only).type:string required:false
  * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false
+ * @example
+ * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }
+ * const face = cad.sketchOnFace({ contours: [loop], on: cad.box(20, 20, 10), face: '>Z' })
  */
 export declare const sketchOnFace: ((params: Record<string, unknown>) => Promise<Shape>) & {
     __faijs__dualOp?: import("../define-op.js").DualOpMeta;

package/dist/api/sketch-on-face.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sketch-on-face.d.ts","sourceRoot":"","sources":["../../src/api/sketch-on-face.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAMtD,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAKnF,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAGxF,OAAO,EAA4C,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAStF,wGAAwG;AACxG,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,CAAA;AAE/C,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,qDAAqD;IACrD,EAAE,EAAE,KAAK,CAAA;IACT,+EAA+E;IAC/E,IAAI,EAAE,YAAY,CAAA;IAClB,8GAA8G;IAC9G,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB,gHAAgH;IAChH,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,GAAG,UAAU,CA0BtG;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAKpG;AA6BD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,GAAG,KAAK,CA+C9F;AAoCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,KAAK,CAgDvE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY;;CAavB,CAAA"}
+{"version":3,"file":"sketch-on-face.d.ts","sourceRoot":"","sources":["../../src/api/sketch-on-face.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAMtD,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAMnF,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAGxF,OAAO,EAA4C,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAStF;;+DAE+D;AAC/D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;AAExD,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,qDAAqD;IACrD,EAAE,EAAE,KAAK,CAAA;IACT,8LAA8L;IAC9L,IAAI,EAAE,YAAY,CAAA;IAClB,8GAA8G;IAC9G,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB,gHAAgH;IAChH,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,GAAG,UAAU,CA+CtG;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAKpG;AA6BD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,GAAG,KAAK,CA+C9F;AAoCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,KAAK,CAwDvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY;;CAavB,CAAA"}