@faicad/faijs 0.13.0

package/dist/api/extrude.d.ts

@@ -0,0 +1,81 @@
+/**
+ * stdlib extrude — `cad.extrude`（平台 parity op，BREP-only）
+ *
+ * 归属（分层红线）：`cad.extrude` 是「面 → 棱柱」的**平台** op，FCStd Pad/Pocket
+ * 链路与 TS 面共用它（docs/plans/2026-09-15-fcstd-to-faijs-port-plan.md M4.6：
+ * 「原 `cad.fai_extrude` 路线废弃」）。up-to（拉伸到面 / 到支持体端面）属
+ * CadQuery `until=` 同族语义，因此落在**本 op**；`fai_extrude`（`fai_` 前缀的
+ * faijs 扩展 op，与 fai_drill / fai_split 同族）不得承载它。
+ *
+ * 为什么是手写 op 而不是继续用生成投影：生成投影
+ * `compatOp(projectBrepOp('extrude', ['face','height'], 'A', vendoredExtrude))`
+ * 有两个硬约束——
+ * ① 参数表只有位置形参；D11 归一化只在「单 plain-object 形态」下按 params 表
+ *    映射（api/internal/dual-form-args.ts），`(face, { upTo })` 属位置形态 →
+ *    原样喂给 vendored extrude → 报错，无法表达对象形态；
+ * ② compatOp 的入参先经 `borrowDeep` 借成 brepjs 视图（api/internal/compat-op.ts），
+ *    在那一层 `brepOf()` 取不到 → 依赖 faceRef / brepOf / 内核直调的 up-to 实现
+ *    必然走空（同 AGENTS.md 记录的「compatOp 自动提升边界」）。
+ * 先例：arg-spec 的 `fillet` 条目（faijs 侧由手写 dual-op 覆盖，生成模块符号为
+ * 孤儿 by design）。
+ *
+ * 长度形态**委托给生成投影**（`projectedExtrude`）：vendored 仍是唯一拉伸引擎，
+ * 既有 `cad.extrude(face, [x,y,z])` 语义零漂移。
+ */
+import type { Shape, Vec3 } from '../mesh/types.js';
+import type { FaceTopoRef } from '../topology/naming/index.js';
+/** 显式平面目标（up-to 截断面）：点 + 法向（点在平面上即可，无需共面于面边界）。 */
+export interface UpToPlaneSpec {
+    /** 平面上一点（世界坐标）。type:[x,y,z] */
+    point: Vec3;
+    /** 平面法向（世界坐标，方向仅定半空间语义，截断取两侧之一）。type:[x,y,z] */
+    normal: Vec3;
+}
+/** up-to 目标：显式面引用 / 显式平面 / 支持体沿拉伸方向的远端（last）/近端（first）端面。 */
+export type ExtrudeUpTo = FaceTopoRef | 'last' | 'first' | {
+    plane: UpToPlaneSpec;
+};
+/** `cad.extrude` 的对象形态参数（位置形态由 {@link normalizeExtrudeOptions} 归一到这里）。 */
+export interface ExtrudeOptions {
+    /** 拉伸量（mm，>0）。up-to 模式下无需给。 */
+    length?: number;
+    /** 拉伸方向（世界坐标）；缺省 [0,0,1]。 */
+    normal?: Vec3;
+    /** 沿 normal 的前进方向；缺省 'forward'（'backward' 等价于方向取反）。 */
+    mode?: 'forward' | 'backward';
+    /** 拉伸到面 / 到支持体端面；提供时忽略 length。 */
+    upTo?: ExtrudeUpTo;
+    /** upTo 'last'/'first' 的支持体（累积支持体，由转换器显式传入）。 */
+    baseFeature?: Shape;
+    /** 截断面沿其法向的偏移（mm）；缺省 0。 */
+    offset?: number;
+}
+/**
+ * 沿 normal 拉伸几何（面 → 棱柱）。
+ *
+ * up-to 模式（`upTo`）与长度模式（`length`）二选一；长度模式委托生成投影
+ * （vendored extrude 为唯一引擎），up-to 模式走半空间组合。
+ *
+ * @group 特征
+ * @inputs 1
+ * @async true
+ * @qual ok
+ * @name extrude
+ * @returns Shape 拉伸后的几何。
+ * @param input - 目标几何（平面面）。type:Shape required:true
+ * @param params.length - 总拉伸量（mm，>0）。up-to 模式下无需给。type:number
+ * @param params.normal - 拉伸方向（世界坐标）。type:[x,y,z] 默认 [0,0,1]
+ * @param params.mode - 沿 normal 的前进方向：forward 正向 / backward 反向。type:'forward' | 'backward' 默认 'forward'
+ * @param params.upTo - 拉伸到面：FaceTopoRef 指定面 / 'last' 支持体远端面 / 'first' 近端面（需 baseFeature）。提供时忽略 length。type:'last' | 'first' | FaceTopoRef
+ * @param params.baseFeature - upTo 'last'/'first' 的支持体几何（累积支持体）。type:Shape
+ * @param params.offset - 截断面沿其法向的偏移（mm）。type:number 默认 0
+ * @example
+ * const p = await cad.extrude(part0, [0, 0, 10])
+ * const p = await cad.extrude(part0, { length: 10 })
+ * const p = await cad.extrude(sk, { upTo: cad.faceRef(part0, 3) })
+ * const p = await cad.extrude(sk, { upTo: 'last', baseFeature: part0 })
+ */
+export declare const extrude: ((input: Shape, params: unknown) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=extrude.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extrude.d.ts","sourceRoot":"","sources":["../../src/api/extrude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAGhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAGrD,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,KAAK,EAAE,IAAI,CAAA;IACX,gDAAgD;IAChD,MAAM,EAAE,IAAI,CAAA;CACb;AAED,6DAA6D;AAC7D,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG;IAAE,KAAK,EAAE,aAAa,CAAA;CAAE,CAAA;AAEnF,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6BAA6B;IAC7B,MAAM,CAAC,EAAE,IAAI,CAAA;IACb,uDAAuD;IACvD,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,CAAA;IAC7B,kCAAkC;IAClC,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,gDAAgD;IAChD,WAAW,CAAC,EAAE,KAAK,CAAA;IACnB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AA2OD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,OAAO;;CAsBlB,CAAA"}

package/dist/api/extrude.js

@@ -0,0 +1,299 @@
+/**
+ * stdlib extrude — `cad.extrude`（平台 parity op，BREP-only）
+ *
+ * 归属（分层红线）：`cad.extrude` 是「面 → 棱柱」的**平台** op，FCStd Pad/Pocket
+ * 链路与 TS 面共用它（docs/plans/2026-09-15-fcstd-to-faijs-port-plan.md M4.6：
+ * 「原 `cad.fai_extrude` 路线废弃」）。up-to（拉伸到面 / 到支持体端面）属
+ * CadQuery `until=` 同族语义，因此落在**本 op**；`fai_extrude`（`fai_` 前缀的
+ * faijs 扩展 op，与 fai_drill / fai_split 同族）不得承载它。
+ *
+ * 为什么是手写 op 而不是继续用生成投影：生成投影
+ * `compatOp(projectBrepOp('extrude', ['face','height'], 'A', vendoredExtrude))`
+ * 有两个硬约束——
+ * ① 参数表只有位置形参；D11 归一化只在「单 plain-object 形态」下按 params 表
+ *    映射（api/internal/dual-form-args.ts），`(face, { upTo })` 属位置形态 →
+ *    原样喂给 vendored extrude → 报错，无法表达对象形态；
+ * ② compatOp 的入参先经 `borrowDeep` 借成 brepjs 视图（api/internal/compat-op.ts），
+ *    在那一层 `brepOf()` 取不到 → 依赖 faceRef / brepOf / 内核直调的 up-to 实现
+ *    必然走空（同 AGENTS.md 记录的「compatOp 自动提升边界」）。
+ * 先例：arg-spec 的 `fillet` 条目（faijs 侧由手写 dual-op 覆盖，生成模块符号为
+ * 孤儿 by design）。
+ *
+ * 长度形态**委托给生成投影**（`projectedExtrude`）：vendored 仍是唯一拉伸引擎，
+ * 既有 `cad.extrude(face, [x,y,z])` 语义零漂移。
+ */
+import { extrude as projectedExtrude } from './generated/operations.js';
+import * as THREE from 'three';
+import { solidToShape, matrixToArray } from '../brep/brep-ops.js';
+import { getSolidBoundingBox } from '../brep/brep-utils.js';
+import { getBackends } from '../runtime-state.js';
+import { fromBrep, brepOf } from '../shape.js';
+import { defineOp } from '../sdk.js';
+import { assertPositiveNumber } from './assert.js';
+import { TopoRefError } from '../topology/naming/index.js';
+/** 判定是否为朴素对象（对象形态判别器，避免误吞 Shape / 数组）。 */
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+}
+/**
+ * 归一化 `cad.extrude` 的两种调用形态。
+ *
+ * - 位置形态（与生成投影同款，历史产物在用）：`cad.extrude(face, 10)` /
+ *   `cad.extrude(face, [x,y,z])`——向量即「方向 × 长度」，恒为沿该方向前进。
+ * - 对象形态（faijs 面）：`cad.extrude(face, { length, normal, mode, upTo, ... })`。
+ *
+ * @param params - 调用点第二实参（数字 / 向量 / 对象）。
+ * @returns 归一化后的对象形态参数。
+ * @throws Error 参数既非数字 / 向量 / 朴素对象时（不猜）。
+ */
+function normalizeExtrudeOptions(params) {
+    if (isPlainObject(params))
+        return params;
+    if (Array.isArray(params)) {
+        const v = params;
+        const len = Math.hypot(v[0] ?? 0, v[1] ?? 0, v[2] ?? 0);
+        if (!Number.isFinite(len) || len < 1e-12) {
+            throw new Error('E_EXTRUDE_ZERO_VECTOR: extrude direction vector has zero length');
+        }
+        return { length: len, normal: [v[0] / len, v[1] / len, v[2] / len], mode: 'forward' };
+    }
+    if (typeof params === 'number')
+        return { length: params, normal: [0, 0, 1], mode: 'forward' };
+    throw new Error('E_EXTRUDE_BAD_PARAMS: extrude expects (face, number | [x,y,z] | { length | upTo, ... })');
+}
+/**
+ * 参数自校验：up-to 模式下无需 length；否则 length 必须为正数。
+ *
+ * @param o - 归一化后的参数。
+ */
+function assertExtrudeOptions(o) {
+    if (o.upTo !== undefined)
+        return; // up-to 模式：长度由目标面决定
+    assertPositiveNumber(o.length, 'extrude.length');
+}
+/** bbox 对角线长度（长试探的余量基数）。 */
+function bboxDiag(bbox) {
+    return Math.hypot(bbox.max[0] - bbox.min[0], bbox.max[1] - bbox.min[1], bbox.max[2] - bbox.min[2]);
+}
+/**
+ * 目标面法向负侧的半空间覆盖盒（截断长拉伸用）——定向版。
+ *
+ * GOTCHA（PadTest Pad001 斜置基准面实测）：轴对齐盒的边界不是斜面本身，
+ * 截断呈台阶而非精确斜平面（体积 7076 vs 真值 4860）。正确做法：在局部基
+ * (u, v, n) 里构造盒（深度沿 −n 伸出 R、横向 ±R），再用 kernel.transform
+ * 旋到世界系——盒的 n=R 端面就是精确的目标平面。
+ *
+ * @param kernel - BREP 内核。
+ * @param faceCenter - 目标面中心（世界坐标，盒的 n=0 端面过此点）。
+ * @param faceNormal - 目标面法向（半空间保留 −n 侧…即盒占据 −n 侧深度）。
+ * @param reach - 覆盖半径 R。
+ * @returns 定向半空间盒的 brep 句柄。
+ */
+function farSideBox(kernel, faceCenter, faceNormal, reach) {
+    const unit = new THREE.Vector3(...faceNormal).normalize();
+    const center = new THREE.Vector3(...faceCenter);
+    // 与 n 正交的正交基 u,v
+    const aux = Math.abs(unit.y) < 0.9 ? new THREE.Vector3(0, 1, 0) : new THREE.Vector3(1, 0, 0);
+    const u = new THREE.Vector3().crossVectors(unit, aux).normalize();
+    const v = new THREE.Vector3().crossVectors(unit, u).normalize();
+    const R = reach;
+    // 局部系盒：x∈[−R,R] (u), y∈[−R,R] (v), z∈[−R,0] (n 深度侧)
+    const box = kernel.makeBoxFromCorners({ x: -R, y: -R, z: -R }, { x: R, y: R, z: 0 });
+    // 旋转矩阵：列 = u, v, n；平移 = center（局部 z=0 端面落到过 center 的目标平面）
+    const m = new THREE.Matrix4().makeBasis(u, v, unit).setPosition(center);
+    return kernel.transform(box, matrixToArray(m));
+}
+/**
+ * up-to 拉伸：occt-wasm 未暴露 `BRepFeat_MakePrism`，用「长拉伸 → 与目标面侧
+ * 半空间盒求交」等价组合；长试探上限只作布尔构造辅助，不进入结果几何。
+ *
+ * @param kernel - BREP 内核。
+ * @param inputSolid - 轮廓实体句柄。
+ * @param o - 归一化参数（需带 upTo）。
+ * @returns 截断后的实体句柄。
+ * @throws Error E_UP_TO_* 系列：缺支持体 / 方向与目标面平行 / 不相交（禁静默）。
+ */
+function extrudeUpToSolid(kernel, inputSolid, o) {
+    const normal = new THREE.Vector3(...(o.normal ?? [0, 0, 1])).normalize();
+    const offset = o.offset ?? 0;
+    const upTo = o.upTo;
+    // 1) 方向目标：FaceTopoRef → 现场面几何；'last'/'first' → baseFeature 支持体
+    //    沿拉伸方向的端面（远端 last / 近端 first）。
+    let targetCenter;
+    let targetNormal;
+    if (typeof upTo === 'string') {
+        const base = o.baseFeature;
+        const baseSolid = base ? brepOf(base) : undefined;
+        if (!baseSolid) {
+            throw new Error('E_UP_TO_NO_BASE: upTo "last"/"first" requires a baseFeature shape');
+        }
+        // 支持体 bbox 沿拉伸方向的远端/近端平面（R-C：baseFeature 显式传参）
+        const bbox = getSolidBoundingBox(kernel, baseSolid);
+        const pick = (which) => {
+            const c = [
+                (bbox.min[0] + bbox.max[0]) / 2,
+                (bbox.min[1] + bbox.max[1]) / 2,
+                (bbox.min[2] + bbox.max[2]) / 2,
+            ];
+            const extent = which === 'max' ? 1 : -1;
+            const proj = (bbox.max[0] - bbox.min[0]) * Math.abs(normal.x) +
+                (bbox.max[1] - bbox.min[1]) * Math.abs(normal.y) +
+                (bbox.max[2] - bbox.min[2]) * Math.abs(normal.z);
+            return [
+                c[0] + ((normal.x * proj) / 2) * extent,
+                c[1] + ((normal.y * proj) / 2) * extent,
+                c[2] + ((normal.z * proj) / 2) * extent,
+            ];
+        };
+        targetCenter = pick(upTo === 'last' ? 'max' : 'min');
+        targetNormal = [normal.x, normal.y, normal.z];
+    }
+    else if (upTo && typeof upTo === 'object' && 'plane' in upTo) {
+        // 显式平面目标（datum plane 等无限平面：截断面由平面方程决定，不受
+        // 目标面边界限制——斜置基准面时顶面是斜的，定长路径语义错误）。
+        targetCenter = [...upTo.plane.point];
+        targetNormal = [...upTo.plane.normal];
+    }
+    else {
+        // GOTCHA（探针实测）：FaceTopoRef 携带的 hint 是 faceRef 现场捕获的
+        // center/normal 快照，直接使用；不要对拉伸轮廓（sketch 面）做二次
+        // resolveFaceGeometry——引用的面在目标体上、不在轮廓上，会 E_TOPO_NOT_FOUND。
+        if (upTo.hint.center && upTo.hint.normal) {
+            targetCenter = [...upTo.hint.center];
+            targetNormal = [...upTo.hint.normal];
+        }
+        else {
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'extrude upTo: face ref hint has no center/normal snapshot');
+        }
+    }
+    // 2) 长试探长度：GOTCHA（探针实测）——不能按轮廓自身 bbox 对角线算（小轮廓够不到
+    //    远处目标面）；必须取「截断平面沿拉伸方向的投影距离」加余量，保证长拉伸至
+    //    少穿过目标面。
+    const bbox = getSolidBoundingBox(kernel, inputSolid);
+    const shiftedCenter0 = [
+        targetCenter[0] + targetNormal[0] * offset,
+        targetCenter[1] + targetNormal[1] * offset,
+        targetCenter[2] + targetNormal[2] * offset,
+    ];
+    // 自动定向（仅 { plane } 目标）：FreeCAD UpToFace 朝目标面所在方向拉伸。
+    // GOTCHA（PadTest Pad001 实测，probe 探针）：斜置基准面在草图局部坐标里
+    // 位于轮廓的反方向（圆心处平面交点 t=−26 而非 +26），固定沿 +Z 拉截不到
+    // 平面（体积 597 ≠ 真值 4860）。轮廓 bbox 中心到截断平面的有向投影与
+    // 拉伸方向异号 → 翻转拉伸方向（就地翻转 Vector3，后续 tMax/keepSide 自洽）。
+    if (upTo && typeof upTo === 'object' && 'plane' in upTo) {
+        const c0 = [
+            (bbox.min[0] + bbox.max[0]) / 2,
+            (bbox.min[1] + bbox.max[1]) / 2,
+            (bbox.min[2] + bbox.max[2]) / 2,
+        ];
+        const tnAuto = new THREE.Vector3(...targetNormal).normalize();
+        const dAuto = (c0[0] - shiftedCenter0[0]) * tnAuto.x +
+            (c0[1] - shiftedCenter0[1]) * tnAuto.y +
+            (c0[2] - shiftedCenter0[2]) * tnAuto.z;
+        // 沿拉伸方向到平面的有向交点参数：t = −((c0−plane)·n) / (dir·n)。
+        // t<0 → 平面在行进反方向 → 翻转（FreeCAD UpToFace 朝平面拉伸）。
+        const tAuto = -dAuto / normal.dot(tnAuto);
+        if (tAuto < 0) {
+            normal.multiplyScalar(-1);
+        }
+    }
+    const cornerProjections = [
+        [bbox.min[0], bbox.min[1], bbox.min[2]],
+        [bbox.max[0], bbox.min[1], bbox.min[2]],
+        [bbox.min[0], bbox.max[1], bbox.min[2]],
+        [bbox.min[0], bbox.min[1], bbox.max[2]],
+        [bbox.max[0], bbox.max[1], bbox.min[2]],
+        [bbox.max[0], bbox.min[1], bbox.max[2]],
+        [bbox.min[0], bbox.max[1], bbox.max[2]],
+        [bbox.max[0], bbox.max[1], bbox.max[2]],
+    ];
+    const planePoint0 = new THREE.Vector3(...shiftedCenter0);
+    const tn0 = new THREE.Vector3(...targetNormal).normalize();
+    const planeD = planePoint0.dot(tn0);
+    const dirD = normal.dot(tn0);
+    if (Math.abs(dirD) < 1e-9) {
+        throw new Error('E_UP_TO_PARALLEL: extrude direction is parallel to the target face plane');
+    }
+    const tMax = cornerProjections
+        .map((p) => (planeD - new THREE.Vector3(...p).dot(tn0)) / dirD)
+        .reduce((a, b) => Math.max(a, b), 0);
+    const L = tMax + Math.abs(offset) + bboxDiag(bbox) * 0.1 + 1;
+    const longSolid = kernel.extrude(inputSolid, normal.x * L, normal.y * L, normal.z * L);
+    // 3) 截断平面 = 目标面 + offset（沿面法向）。GOTCHA（探针实测）：半空间侧不能固定
+    //    取「法向负侧」——目标面法向朝向与拉伸方向无必然关系。正确语义：保留「包含
+    //    拉伸起点」的那一侧。farSideBox 覆盖「传入法向的反侧」，因此传 -keepSide。
+    const tn = tn0;
+    const startCenter = new THREE.Vector3((bbox.min[0] + bbox.max[0]) / 2, (bbox.min[1] + bbox.max[1]) / 2, (bbox.min[2] + bbox.max[2]) / 2);
+    const planePoint = new THREE.Vector3(...shiftedCenter0);
+    const d = startCenter.sub(planePoint).dot(tn);
+    // 保留侧法向：起点所在侧（d 与 tn 同号 → 正侧；异号 → 负侧）；d≈0 时退化为
+    // 拉伸方向（起点在面上时按拉伸方向截）
+    const keepSide = Math.abs(d) < 1e-9 ? normal.clone() : tn.clone().multiplyScalar(Math.sign(d));
+    // GOTCHA（PadTest Pad001 斜置基准面实测）：targetCenter 可以是平面上离轮廓
+    // 很远的任意一点（基准面 point 在草图局部坐标里横向偏 ~100），reach 若只取
+    // L（按轮廓到截断面的投影距离）则半空间盒横向盖不住长拉伸体 → common 为空。
+    // reach 必须 ≥ 平面点到拉伸体的距离 + 体对角线（全方向覆盖）。
+    const reach = new THREE.Vector3(...shiftedCenter0).distanceTo(new THREE.Vector3((bbox.min[0] + bbox.max[0]) / 2, (bbox.min[1] + bbox.max[1]) / 2, (bbox.min[2] + bbox.max[2]) / 2)) + bboxDiag(bbox) + Math.abs(offset) + 1;
+    const halfspace = farSideBox(kernel, shiftedCenter0, [-keepSide.x, -keepSide.y, -keepSide.z], reach);
+    // 4) 求交：长拉伸 ∩ 半空间盒
+    const clipped = kernel.common(longSolid, halfspace);
+    kernel.release(longSolid);
+    kernel.release(halfspace);
+    // 预检：方向上不相交 → 显式报错（禁静默）
+    const clippedBBox = getSolidBoundingBox(kernel, clipped);
+    if (!Number.isFinite(bboxDiag(clippedBBox)) || bboxDiag(clippedBBox) < 1e-9) {
+        kernel.release(clipped);
+        throw new Error('E_UP_TO_NO_INTERSECTION: extrude direction does not reach the target face');
+    }
+    return clipped;
+}
+/**
+ * 沿 normal 拉伸几何（面 → 棱柱）。
+ *
+ * up-to 模式（`upTo`）与长度模式（`length`）二选一；长度模式委托生成投影
+ * （vendored extrude 为唯一引擎），up-to 模式走半空间组合。
+ *
+ * @group 特征
+ * @inputs 1
+ * @async true
+ * @qual ok
+ * @name extrude
+ * @returns Shape 拉伸后的几何。
+ * @param input - 目标几何（平面面）。type:Shape required:true
+ * @param params.length - 总拉伸量（mm，>0）。up-to 模式下无需给。type:number
+ * @param params.normal - 拉伸方向（世界坐标）。type:[x,y,z] 默认 [0,0,1]
+ * @param params.mode - 沿 normal 的前进方向：forward 正向 / backward 反向。type:'forward' | 'backward' 默认 'forward'
+ * @param params.upTo - 拉伸到面：FaceTopoRef 指定面 / 'last' 支持体远端面 / 'first' 近端面（需 baseFeature）。提供时忽略 length。type:'last' | 'first' | FaceTopoRef
+ * @param params.baseFeature - upTo 'last'/'first' 的支持体几何（累积支持体）。type:Shape
+ * @param params.offset - 截断面沿其法向的偏移（mm）。type:number 默认 0
+ * @example
+ * const p = await cad.extrude(part0, [0, 0, 10])
+ * const p = await cad.extrude(part0, { length: 10 })
+ * const p = await cad.extrude(sk, { upTo: cad.faceRef(part0, 3) })
+ * const p = await cad.extrude(sk, { upTo: 'last', baseFeature: part0 })
+ */
+export const extrude = defineOp({
+    name: 'extrude',
+    brep: async (input, params) => {
+        if (!input)
+            throw new Error('[stdlib/extrude] no input geometry');
+        const o = normalizeExtrudeOptions(params);
+        assertExtrudeOptions(o);
+        if (o.upTo !== undefined) {
+            const kernel = getBackends().kernel.brep;
+            if (!kernel)
+                throw new Error('[stdlib/extrude] no OCCT kernel');
+            const inputSolid = brepOf(input);
+            if (!inputSolid)
+                throw new Error('[stdlib/extrude] input is not BREP');
+            const clipped = extrudeUpToSolid(kernel, inputSolid, o);
+            return fromBrep(solidToShape(kernel, clipped), { solid: clipped });
+        }
+        // 长度形态：委托生成投影（生成投影自带借入 / Result 翻转 / 收养）
+        const normal = new THREE.Vector3(...(o.normal ?? [0, 0, 1])).normalize();
+        const sign = o.mode === 'backward' ? -1 : 1;
+        const v = [normal.x * o.length * sign, normal.y * o.length * sign, normal.z * o.length * sign];
+        return (await projectedExtrude(input, v));
+    },
+});
+//# sourceMappingURL=extrude.js.map

package/dist/api/extrude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extrude.js","sourceRoot":"","sources":["../../src/api/extrude.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib extrude — `cad.extrude`（平台 parity op，BREP-only）\n *\n * 归属（分层红线）：`cad.extrude` 是「面 → 棱柱」的**平台** op，FCStd Pad/Pocket\n * 链路与 TS 面共用它（docs/plans/2026-09-15-fcstd-to-faijs-port-plan.md M4.6：\n * 「原 `cad.fai_extrude` 路线废弃」）。up-to（拉伸到面 / 到支持体端面）属\n * CadQuery `until=` 同族语义，因此落在**本 op**；`fai_extrude`（`fai_` 前缀的\n * faijs 扩展 op，与 fai_drill / fai_split 同族）不得承载它。\n *\n * 为什么是手写 op 而不是继续用生成投影：生成投影\n * `compatOp(projectBrepOp('extrude', ['face','height'], 'A', vendoredExtrude))`\n * 有两个硬约束——\n * ① 参数表只有位置形参；D11 归一化只在「单 plain-object 形态」下按 params 表\n *    映射（api/internal/dual-form-args.ts），`(face, { upTo })` 属位置形态 →\n *    原样喂给 vendored extrude → 报错，无法表达对象形态；\n * ② compatOp 的入参先经 `borrowDeep` 借成 brepjs 视图（api/internal/compat-op.ts），\n *    在那一层 `brepOf()` 取不到 → 依赖 faceRef / brepOf / 内核直调的 up-to 实现\n *    必然走空（同 AGENTS.md 记录的「compatOp 自动提升边界」）。\n * 先例：arg-spec 的 `fillet` 条目（faijs 侧由手写 dual-op 覆盖，生成模块符号为\n * 孤儿 by design）。\n *\n * 长度形态**委托给生成投影**（`projectedExtrude`）：vendored 仍是唯一拉伸引擎，\n * 既有 `cad.extrude(face, [x,y,z])` 语义零漂移。\n */\n\nimport { extrude as projectedExtrude } from './generated/operations'\nimport * as THREE from 'three'\nimport { solidToShape, matrixToArray } from '../brep/brep-ops'\nimport { getSolidBoundingBox } from '../brep/brep-utils'\nimport { getBackends } from '../runtime-state'\nimport { fromBrep, brepOf } from '../shape'\nimport { defineOp } from '../sdk'\nimport { assertPositiveNumber } from './assert'\nimport type { Shape, Vec3 } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { FaceTopoRef } from '../topology/naming'\nimport { TopoRefError } from '../topology/naming'\n\n/** 显式平面目标（up-to 截断面）：点 + 法向（点在平面上即可，无需共面于面边界）。 */\nexport interface UpToPlaneSpec {\n  /** 平面上一点（世界坐标）。type:[x,y,z] */\n  point: Vec3\n  /** 平面法向（世界坐标，方向仅定半空间语义，截断取两侧之一）。type:[x,y,z] */\n  normal: Vec3\n}\n\n/** up-to 目标：显式面引用 / 显式平面 / 支持体沿拉伸方向的远端（last）/近端（first）端面。 */\nexport type ExtrudeUpTo = FaceTopoRef | 'last' | 'first' | { plane: UpToPlaneSpec }\n\n/** `cad.extrude` 的对象形态参数（位置形态由 {@link normalizeExtrudeOptions} 归一到这里）。 */\nexport interface ExtrudeOptions {\n  /** 拉伸量（mm，>0）。up-to 模式下无需给。 */\n  length?: number\n  /** 拉伸方向（世界坐标）；缺省 [0,0,1]。 */\n  normal?: Vec3\n  /** 沿 normal 的前进方向；缺省 'forward'（'backward' 等价于方向取反）。 */\n  mode?: 'forward' | 'backward'\n  /** 拉伸到面 / 到支持体端面；提供时忽略 length。 */\n  upTo?: ExtrudeUpTo\n  /** upTo 'last'/'first' 的支持体（累积支持体，由转换器显式传入）。 */\n  baseFeature?: Shape\n  /** 截断面沿其法向的偏移（mm）；缺省 0。 */\n  offset?: number\n}\n\n/** 判定是否为朴素对象（对象形态判别器，避免误吞 Shape / 数组）。 */\nfunction isPlainObject(v: unknown): v is Record<string, unknown> {\n  return v !== null && typeof v === 'object' && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype\n}\n\n/**\n * 归一化 `cad.extrude` 的两种调用形态。\n *\n * - 位置形态（与生成投影同款，历史产物在用）：`cad.extrude(face, 10)` /\n *   `cad.extrude(face, [x,y,z])`——向量即「方向 × 长度」，恒为沿该方向前进。\n * - 对象形态（faijs 面）：`cad.extrude(face, { length, normal, mode, upTo, ... })`。\n *\n * @param params - 调用点第二实参（数字 / 向量 / 对象）。\n * @returns 归一化后的对象形态参数。\n * @throws Error 参数既非数字 / 向量 / 朴素对象时（不猜）。\n */\nfunction normalizeExtrudeOptions(params: unknown): ExtrudeOptions {\n  if (isPlainObject(params)) return params as ExtrudeOptions\n  if (Array.isArray(params)) {\n    const v = params as Vec3\n    const len = Math.hypot(v[0] ?? 0, v[1] ?? 0, v[2] ?? 0)\n    if (!Number.isFinite(len) || len < 1e-12) {\n      throw new Error('E_EXTRUDE_ZERO_VECTOR: extrude direction vector has zero length')\n    }\n    return { length: len, normal: [v[0] / len, v[1] / len, v[2] / len], mode: 'forward' }\n  }\n  if (typeof params === 'number') return { length: params, normal: [0, 0, 1], mode: 'forward' }\n  throw new Error('E_EXTRUDE_BAD_PARAMS: extrude expects (face, number | [x,y,z] | { length | upTo, ... })')\n}\n\n/**\n * 参数自校验：up-to 模式下无需 length；否则 length 必须为正数。\n *\n * @param o - 归一化后的参数。\n */\nfunction assertExtrudeOptions(o: ExtrudeOptions): void {\n  if (o.upTo !== undefined) return // up-to 模式：长度由目标面决定\n  assertPositiveNumber(o.length, 'extrude.length')\n}\n\n/** bbox 对角线长度（长试探的余量基数）。 */\nfunction bboxDiag(bbox: { min: Vec3; max: Vec3 }): number {\n  return Math.hypot(bbox.max[0] - bbox.min[0], bbox.max[1] - bbox.min[1], bbox.max[2] - bbox.min[2])\n}\n\n/**\n * 目标面法向负侧的半空间覆盖盒（截断长拉伸用）——定向版。\n *\n * GOTCHA（PadTest Pad001 斜置基准面实测）：轴对齐盒的边界不是斜面本身，\n * 截断呈台阶而非精确斜平面（体积 7076 vs 真值 4860）。正确做法：在局部基\n * (u, v, n) 里构造盒（深度沿 −n 伸出 R、横向 ±R），再用 kernel.transform\n * 旋到世界系——盒的 n=R 端面就是精确的目标平面。\n *\n * @param kernel - BREP 内核。\n * @param faceCenter - 目标面中心（世界坐标，盒的 n=0 端面过此点）。\n * @param faceNormal - 目标面法向（半空间保留 −n 侧…即盒占据 −n 侧深度）。\n * @param reach - 覆盖半径 R。\n * @returns 定向半空间盒的 brep 句柄。\n */\nfunction farSideBox(kernel: BrepEngineApi, faceCenter: Vec3, faceNormal: Vec3, reach: number): BrepHandle {\n  const unit = new THREE.Vector3(...faceNormal).normalize()\n  const center = new THREE.Vector3(...faceCenter)\n  // 与 n 正交的正交基 u,v\n  const aux = Math.abs(unit.y) < 0.9 ? new THREE.Vector3(0, 1, 0) : new THREE.Vector3(1, 0, 0)\n  const u = new THREE.Vector3().crossVectors(unit, aux).normalize()\n  const v = new THREE.Vector3().crossVectors(unit, u).normalize()\n  const R = reach\n  // 局部系盒：x∈[−R,R] (u), y∈[−R,R] (v), z∈[−R,0] (n 深度侧)\n  const box = kernel.makeBoxFromCorners(\n    { x: -R, y: -R, z: -R },\n    { x: R, y: R, z: 0 },\n  )\n  // 旋转矩阵：列 = u, v, n；平移 = center（局部 z=0 端面落到过 center 的目标平面）\n  const m = new THREE.Matrix4().makeBasis(u, v, unit).setPosition(center)\n  return kernel.transform(box, matrixToArray(m))\n}\n\n/**\n * up-to 拉伸：occt-wasm 未暴露 `BRepFeat_MakePrism`，用「长拉伸 → 与目标面侧\n * 半空间盒求交」等价组合；长试探上限只作布尔构造辅助，不进入结果几何。\n *\n * @param kernel - BREP 内核。\n * @param inputSolid - 轮廓实体句柄。\n * @param o - 归一化参数（需带 upTo）。\n * @returns 截断后的实体句柄。\n * @throws Error E_UP_TO_* 系列：缺支持体 / 方向与目标面平行 / 不相交（禁静默）。\n */\nfunction extrudeUpToSolid(kernel: BrepEngineApi, inputSolid: BrepHandle, o: ExtrudeOptions): BrepHandle {\n  const normal = new THREE.Vector3(...(o.normal ?? [0, 0, 1])).normalize()\n  const offset = o.offset ?? 0\n  const upTo = o.upTo as ExtrudeUpTo\n\n  // 1) 方向目标：FaceTopoRef → 现场面几何；'last'/'first' → baseFeature 支持体\n  //    沿拉伸方向的端面（远端 last / 近端 first）。\n  let targetCenter: Vec3\n  let targetNormal: Vec3\n  if (typeof upTo === 'string') {\n    const base = o.baseFeature\n    const baseSolid = base ? (brepOf(base) as BrepHandle | undefined) : undefined\n    if (!baseSolid) {\n      throw new Error('E_UP_TO_NO_BASE: upTo \"last\"/\"first\" requires a baseFeature shape')\n    }\n    // 支持体 bbox 沿拉伸方向的远端/近端平面（R-C：baseFeature 显式传参）\n    const bbox = getSolidBoundingBox(kernel, baseSolid)\n    const pick = (which: 'max' | 'min'): Vec3 => {\n      const c: Vec3 = [\n        (bbox.min[0] + bbox.max[0]) / 2,\n        (bbox.min[1] + bbox.max[1]) / 2,\n        (bbox.min[2] + bbox.max[2]) / 2,\n      ]\n      const extent = which === 'max' ? 1 : -1\n      const proj =\n        (bbox.max[0] - bbox.min[0]) * Math.abs(normal.x) +\n        (bbox.max[1] - bbox.min[1]) * Math.abs(normal.y) +\n        (bbox.max[2] - bbox.min[2]) * Math.abs(normal.z)\n      return [\n        c[0] + ((normal.x * proj) / 2) * extent,\n        c[1] + ((normal.y * proj) / 2) * extent,\n        c[2] + ((normal.z * proj) / 2) * extent,\n      ]\n    }\n    targetCenter = pick(upTo === 'last' ? 'max' : 'min')\n    targetNormal = [normal.x, normal.y, normal.z]\n  } else if (upTo && typeof upTo === 'object' && 'plane' in upTo) {\n    // 显式平面目标（datum plane 等无限平面：截断面由平面方程决定，不受\n    // 目标面边界限制——斜置基准面时顶面是斜的，定长路径语义错误）。\n    targetCenter = [...upTo.plane.point] as Vec3\n    targetNormal = [...upTo.plane.normal] as Vec3\n  } else {\n    // GOTCHA（探针实测）：FaceTopoRef 携带的 hint 是 faceRef 现场捕获的\n    // center/normal 快照，直接使用；不要对拉伸轮廓（sketch 面）做二次\n    // resolveFaceGeometry——引用的面在目标体上、不在轮廓上，会 E_TOPO_NOT_FOUND。\n    if (upTo.hint.center && upTo.hint.normal) {\n      targetCenter = [...upTo.hint.center] as Vec3\n      targetNormal = [...upTo.hint.normal] as Vec3\n    } else {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'extrude upTo: face ref hint has no center/normal snapshot')\n    }\n  }\n\n  // 2) 长试探长度：GOTCHA（探针实测）——不能按轮廓自身 bbox 对角线算（小轮廓够不到\n  //    远处目标面）；必须取「截断平面沿拉伸方向的投影距离」加余量，保证长拉伸至\n  //    少穿过目标面。\n  const bbox = getSolidBoundingBox(kernel, inputSolid)\n  const shiftedCenter0: Vec3 = [\n    targetCenter[0] + targetNormal[0] * offset,\n    targetCenter[1] + targetNormal[1] * offset,\n    targetCenter[2] + targetNormal[2] * offset,\n  ]\n  // 自动定向（仅 { plane } 目标）：FreeCAD UpToFace 朝目标面所在方向拉伸。\n  // GOTCHA（PadTest Pad001 实测，probe 探针）：斜置基准面在草图局部坐标里\n  // 位于轮廓的反方向（圆心处平面交点 t=−26 而非 +26），固定沿 +Z 拉截不到\n  // 平面（体积 597 ≠ 真值 4860）。轮廓 bbox 中心到截断平面的有向投影与\n  // 拉伸方向异号 → 翻转拉伸方向（就地翻转 Vector3，后续 tMax/keepSide 自洽）。\n  if (upTo && typeof upTo === 'object' && 'plane' in upTo) {\n    const c0: Vec3 = [\n      (bbox.min[0] + bbox.max[0]) / 2,\n      (bbox.min[1] + bbox.max[1]) / 2,\n      (bbox.min[2] + bbox.max[2]) / 2,\n    ]\n    const tnAuto = new THREE.Vector3(...targetNormal).normalize()\n    const dAuto =\n      (c0[0] - shiftedCenter0[0]) * tnAuto.x +\n      (c0[1] - shiftedCenter0[1]) * tnAuto.y +\n      (c0[2] - shiftedCenter0[2]) * tnAuto.z\n    // 沿拉伸方向到平面的有向交点参数：t = −((c0−plane)·n) / (dir·n)。\n    // t<0 → 平面在行进反方向 → 翻转（FreeCAD UpToFace 朝平面拉伸）。\n    const tAuto = -dAuto / normal.dot(tnAuto)\n    if (tAuto < 0) {\n      normal.multiplyScalar(-1)\n    }\n  }\n  const cornerProjections = [\n    [bbox.min[0], bbox.min[1], bbox.min[2]],\n    [bbox.max[0], bbox.min[1], bbox.min[2]],\n    [bbox.min[0], bbox.max[1], bbox.min[2]],\n    [bbox.min[0], bbox.min[1], bbox.max[2]],\n    [bbox.max[0], bbox.max[1], bbox.min[2]],\n    [bbox.max[0], bbox.min[1], bbox.max[2]],\n    [bbox.min[0], bbox.max[1], bbox.max[2]],\n    [bbox.max[0], bbox.max[1], bbox.max[2]],\n  ] as Vec3[]\n  const planePoint0 = new THREE.Vector3(...shiftedCenter0)\n  const tn0 = new THREE.Vector3(...targetNormal).normalize()\n  const planeD = planePoint0.dot(tn0)\n  const dirD = normal.dot(tn0)\n  if (Math.abs(dirD) < 1e-9) {\n    throw new Error('E_UP_TO_PARALLEL: extrude direction is parallel to the target face plane')\n  }\n  const tMax = cornerProjections\n    .map((p) => (planeD - new THREE.Vector3(...p).dot(tn0)) / dirD)\n    .reduce((a, b) => Math.max(a, b), 0)\n  const L = tMax + Math.abs(offset) + bboxDiag(bbox) * 0.1 + 1\n  const longSolid = kernel.extrude(inputSolid, normal.x * L, normal.y * L, normal.z * L)\n\n  // 3) 截断平面 = 目标面 + offset（沿面法向）。GOTCHA（探针实测）：半空间侧不能固定\n  //    取「法向负侧」——目标面法向朝向与拉伸方向无必然关系。正确语义：保留「包含\n  //    拉伸起点」的那一侧。farSideBox 覆盖「传入法向的反侧」，因此传 -keepSide。\n  const tn = tn0\n  const startCenter = new THREE.Vector3(\n    (bbox.min[0] + bbox.max[0]) / 2,\n    (bbox.min[1] + bbox.max[1]) / 2,\n    (bbox.min[2] + bbox.max[2]) / 2,\n  )\n  const planePoint = new THREE.Vector3(...shiftedCenter0)\n  const d = startCenter.sub(planePoint).dot(tn)\n  // 保留侧法向：起点所在侧（d 与 tn 同号 → 正侧；异号 → 负侧）；d≈0 时退化为\n  // 拉伸方向（起点在面上时按拉伸方向截）\n  const keepSide = Math.abs(d) < 1e-9 ? normal.clone() : tn.clone().multiplyScalar(Math.sign(d))\n  // GOTCHA（PadTest Pad001 斜置基准面实测）：targetCenter 可以是平面上离轮廓\n  // 很远的任意一点（基准面 point 在草图局部坐标里横向偏 ~100），reach 若只取\n  // L（按轮廓到截断面的投影距离）则半空间盒横向盖不住长拉伸体 → common 为空。\n  // reach 必须 ≥ 平面点到拉伸体的距离 + 体对角线（全方向覆盖）。\n  const reach =\n    new THREE.Vector3(...shiftedCenter0).distanceTo(\n      new THREE.Vector3((bbox.min[0] + bbox.max[0]) / 2, (bbox.min[1] + bbox.max[1]) / 2, (bbox.min[2] + bbox.max[2]) / 2),\n    ) + bboxDiag(bbox) + Math.abs(offset) + 1\n  const halfspace = farSideBox(kernel, shiftedCenter0, [-keepSide.x, -keepSide.y, -keepSide.z], reach)\n\n  // 4) 求交：长拉伸 ∩ 半空间盒\n  const clipped = kernel.common(longSolid, halfspace)\n  kernel.release(longSolid)\n  kernel.release(halfspace)\n\n  // 预检：方向上不相交 → 显式报错（禁静默）\n  const clippedBBox = getSolidBoundingBox(kernel, clipped)\n  if (!Number.isFinite(bboxDiag(clippedBBox)) || bboxDiag(clippedBBox) < 1e-9) {\n    kernel.release(clipped)\n    throw new Error('E_UP_TO_NO_INTERSECTION: extrude direction does not reach the target face')\n  }\n  return clipped\n}\n\n/**\n * 沿 normal 拉伸几何（面 → 棱柱）。\n *\n * up-to 模式（`upTo`）与长度模式（`length`）二选一；长度模式委托生成投影\n * （vendored extrude 为唯一引擎），up-to 模式走半空间组合。\n *\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name extrude\n * @returns Shape 拉伸后的几何。\n * @param input - 目标几何（平面面）。type:Shape required:true\n * @param params.length - 总拉伸量（mm，>0）。up-to 模式下无需给。type:number\n * @param params.normal - 拉伸方向（世界坐标）。type:[x,y,z] 默认 [0,0,1]\n * @param params.mode - 沿 normal 的前进方向：forward 正向 / backward 反向。type:'forward' | 'backward' 默认 'forward'\n * @param params.upTo - 拉伸到面：FaceTopoRef 指定面 / 'last' 支持体远端面 / 'first' 近端面（需 baseFeature）。提供时忽略 length。type:'last' | 'first' | FaceTopoRef\n * @param params.baseFeature - upTo 'last'/'first' 的支持体几何（累积支持体）。type:Shape\n * @param params.offset - 截断面沿其法向的偏移（mm）。type:number 默认 0\n * @example\n * const p = await cad.extrude(part0, [0, 0, 10])\n * const p = await cad.extrude(part0, { length: 10 })\n * const p = await cad.extrude(sk, { upTo: cad.faceRef(part0, 3) })\n * const p = await cad.extrude(sk, { upTo: 'last', baseFeature: part0 })\n */\nexport const extrude = defineOp({\n  name: 'extrude',\n  brep: async (input: Shape, params: unknown): Promise<Shape> => {\n    if (!input) throw new Error('[stdlib/extrude] no input geometry')\n    const o = normalizeExtrudeOptions(params)\n    assertExtrudeOptions(o)\n\n    if (o.upTo !== undefined) {\n      const kernel = getBackends().kernel.brep as BrepEngineApi | null\n      if (!kernel) throw new Error('[stdlib/extrude] no OCCT kernel')\n      const inputSolid = brepOf(input) as BrepHandle | undefined\n      if (!inputSolid) throw new Error('[stdlib/extrude] input is not BREP')\n      const clipped = extrudeUpToSolid(kernel, inputSolid, o)\n      return fromBrep(solidToShape(kernel, clipped), { solid: clipped })\n    }\n\n    // 长度形态：委托生成投影（生成投影自带借入 / Result 翻转 / 收养）\n    const normal = new THREE.Vector3(...(o.normal ?? [0, 0, 1])).normalize()\n    const sign = o.mode === 'backward' ? -1 : 1\n    const v: Vec3 = [normal.x * o.length! * sign, normal.y * o.length! * sign, normal.z * o.length! * sign]\n    return (await projectedExtrude(input, v)) as Shape\n  },\n})\n"]}

package/dist/api/face-ref.d.ts

@@ -0,0 +1,37 @@
+/**
+ * stdlib face-ref — 面引用查询：把「面序号」解析成 `FaceTopoRef`（1 起）
+ *
+ * extrude 的 `upTo` 参数（拉伸到面，PadTest UpToFace 链路）需要指向
+ * 「某个实体上第 N 张面」的引用。外部格式（FCStd 的 `UpToFace` LinkSub 等）
+ * 只给序号，本模块与 `edge-ref.ts` 同构：在内核现场枚举里取第 N 张面，
+ * 经输入 Shape 的命名槽（RoleTable + subShapeHashes）反查它的
+ * `{origin, role}` 血统，合成 `FaceTopoRef`。
+ *
+ * 序号语义（GOTCHA）：与 `edgeRef` 一致，1 起 == FreeCAD 的 `FaceN`
+ * （`getSubShapes(solid,'face')` 用 TopExp::MapShapes + IndexedMap 枚举，
+ * 与 `edge-ref.ts` 头注同源已记档）。
+ *
+ * 纯查询：同步、无副作用、不改 Shape；定不了案一律抛 `TopoRefError`，
+ * 绝不静默拿序号硬取。
+ */
+import type { Shape } from '../mesh/types.js';
+import type { FaceTopoRef } from '../topology/naming/index.js';
+/**
+ * 查询几何体第 N 张面的 `FaceTopoRef`，供 `cad.extrude` 的 `upTo` 等参数使用：
+ * `cad.extrude(part0, { upTo: cad.faceRef(part0, 3) })`。
+ *
+ * 定不了案（无 BREP / 序号越界 / 面无 role 血统）抛 `TopoRefError`。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name faceRef
+ * @returns FaceTopoRef 该面的拓扑引用（origin/role 血统 + 几何 hint）。
+ * @param of - 目标几何（BREP 实体所在的 Shape）。type:Shape required:true
+ * @param faceOrdinal - 面序号（1 起；等于 FreeCAD 的 `FaceN`）。type:number required:true
+ * @note 序号 1 起，与命名层 `TopoRef.ordinal` 及 FreeCAD `FaceN` 同序（`getSubShapes(solid,'face')` 用 TopExp::MapShapes + IndexedMap 枚举）。
+ * @example
+ * const part1 = cad.extrude(sk, { upTo: cad.faceRef(part0, 3) })
+ */
+export declare function faceRef(of: Shape, faceOrdinal: number): FaceTopoRef;
+//# sourceMappingURL=face-ref.d.ts.map

package/dist/api/face-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-ref.d.ts","sourceRoot":"","sources":["../../src/api/face-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAK1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAGrD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,CA8BnE"}

package/dist/api/face-ref.js

@@ -0,0 +1,64 @@
+/**
+ * stdlib face-ref — 面引用查询：把「面序号」解析成 `FaceTopoRef`（1 起）
+ *
+ * extrude 的 `upTo` 参数（拉伸到面，PadTest UpToFace 链路）需要指向
+ * 「某个实体上第 N 张面」的引用。外部格式（FCStd 的 `UpToFace` LinkSub 等）
+ * 只给序号，本模块与 `edge-ref.ts` 同构：在内核现场枚举里取第 N 张面，
+ * 经输入 Shape 的命名槽（RoleTable + subShapeHashes）反查它的
+ * `{origin, role}` 血统，合成 `FaceTopoRef`。
+ *
+ * 序号语义（GOTCHA）：与 `edgeRef` 一致，1 起 == FreeCAD 的 `FaceN`
+ * （`getSubShapes(solid,'face')` 用 TopExp::MapShapes + IndexedMap 枚举，
+ * 与 `edge-ref.ts` 头注同源已记档）。
+ *
+ * 纯查询：同步、无副作用、不改 Shape；定不了案一律抛 `TopoRefError`，
+ * 绝不静默拿序号硬取。
+ */
+import { getBackends } from '../runtime-state.js';
+import { brepOf } from '../shape.js';
+import { captureFaceHint, findOriginRole, TopoRefError } from '../topology/naming/index.js';
+import { buildEdgeResolutionContext } from './topo-resolve.js';
+/**
+ * 查询几何体第 N 张面的 `FaceTopoRef`，供 `cad.extrude` 的 `upTo` 等参数使用：
+ * `cad.extrude(part0, { upTo: cad.faceRef(part0, 3) })`。
+ *
+ * 定不了案（无 BREP / 序号越界 / 面无 role 血统）抛 `TopoRefError`。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name faceRef
+ * @returns FaceTopoRef 该面的拓扑引用（origin/role 血统 + 几何 hint）。
+ * @param of - 目标几何（BREP 实体所在的 Shape）。type:Shape required:true
+ * @param faceOrdinal - 面序号（1 起；等于 FreeCAD 的 `FaceN`）。type:number required:true
+ * @note 序号 1 起，与命名层 `TopoRef.ordinal` 及 FreeCAD `FaceN` 同序（`getSubShapes(solid,'face')` 用 TopExp::MapShapes + IndexedMap 枚举）。
+ * @example
+ * const part1 = cad.extrude(sk, { upTo: cad.faceRef(part0, 3) })
+ */
+export function faceRef(of, faceOrdinal) {
+    if (!Number.isInteger(faceOrdinal) || faceOrdinal < 1) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceRef: faceOrdinal must be an integer >= 1 (got ${faceOrdinal})`);
+    }
+    const kernel = getBackends().kernel.brep;
+    if (!kernel)
+        throw new Error('[faceRef] no BREP kernel (face references are BREP-only)');
+    if (!brepOf(of))
+        throw new Error('[faceRef] E_FACE_REF_NO_BREP: input shape has no BREP solid');
+    const ctx = buildEdgeResolutionContext(kernel, of);
+    if (!ctx)
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'faceRef: input has no BREP naming context');
+    const face = ctx.faces.find((f) => f.ordinal === faceOrdinal);
+    if (!face || face.handle === undefined) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceRef: face ordinal ${faceOrdinal} out of range [1, ${ctx.faces.length}]`);
+    }
+    const table = ctx.roleTable;
+    if (!table) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'faceRef: input shape has no role table (nameless shape)');
+    }
+    const found = findOriginRole(table, ctx.faces.map((f) => f.hash ?? 0), faceOrdinal);
+    if (!found) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceRef: face ordinal ${faceOrdinal} has no role lineage`);
+    }
+    return { kind: 'face', origin: found.origin, role: found.role, hint: captureFaceHint(kernel, face.handle) };
+}
+//# sourceMappingURL=face-ref.js.map

package/dist/api/face-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-ref.js","sourceRoot":"","sources":["../../src/api/face-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEjC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAElF,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,OAAO,CAAC,EAAS,EAAE,WAAmB;IACpD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,qDAAqD,WAAW,GAAG,CAAC,CAAA;IACzH,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAA4B,CAAA;IAChE,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAA;IACxF,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAA;IAE/F,MAAM,GAAG,GAAG,0BAA0B,CAAC,MAAM,EAAE,EAAY,CAAC,CAAA;IAC5D,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,2CAA2C,CAAC,CAAA;IAEzG,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,WAAW,CAAC,CAAA;IAC7D,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,IAAI,YAAY,CACpB,kBAAkB,EAClB,MAAM,EACN,yBAAyB,WAAW,qBAAqB,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAC7E,CAAA;IACH,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAA;IAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,yDAAyD,CAAC,CAAA;IAC/G,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,WAAW,CAAC,CAAA;IACnF,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,yBAAyB,WAAW,sBAAsB,CAAC,CAAA;IAChH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAA;AAC7G,CAAC","sourcesContent":["/**\n * stdlib face-ref — 面引用查询：把「面序号」解析成 `FaceTopoRef`（1 起）\n *\n * extrude 的 `upTo` 参数（拉伸到面，PadTest UpToFace 链路）需要指向\n * 「某个实体上第 N 张面」的引用。外部格式（FCStd 的 `UpToFace` LinkSub 等）\n * 只给序号，本模块与 `edge-ref.ts` 同构：在内核现场枚举里取第 N 张面，\n * 经输入 Shape 的命名槽（RoleTable + subShapeHashes）反查它的\n * `{origin, role}` 血统，合成 `FaceTopoRef`。\n *\n * 序号语义（GOTCHA）：与 `edgeRef` 一致，1 起 == FreeCAD 的 `FaceN`\n * （`getSubShapes(solid,'face')` 用 TopExp::MapShapes + IndexedMap 枚举，\n * 与 `edge-ref.ts` 头注同源已记档）。\n *\n * 纯查询：同步、无副作用、不改 Shape；定不了案一律抛 `TopoRefError`，\n * 绝不静默拿序号硬取。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBackends } from '../runtime-state'\nimport { brepOf } from '../shape'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport { captureFaceHint, findOriginRole, TopoRefError } from '../topology/naming'\nimport type { FaceTopoRef } from '../topology/naming'\nimport { buildEdgeResolutionContext } from './topo-resolve'\n\n/**\n * 查询几何体第 N 张面的 `FaceTopoRef`，供 `cad.extrude` 的 `upTo` 等参数使用：\n * `cad.extrude(part0, { upTo: cad.faceRef(part0, 3) })`。\n *\n * 定不了案（无 BREP / 序号越界 / 面无 role 血统）抛 `TopoRefError`。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name faceRef\n * @returns FaceTopoRef 该面的拓扑引用（origin/role 血统 + 几何 hint）。\n * @param of - 目标几何（BREP 实体所在的 Shape）。type:Shape required:true\n * @param faceOrdinal - 面序号（1 起；等于 FreeCAD 的 `FaceN`）。type:number required:true\n * @note 序号 1 起，与命名层 `TopoRef.ordinal` 及 FreeCAD `FaceN` 同序（`getSubShapes(solid,'face')` 用 TopExp::MapShapes + IndexedMap 枚举）。\n * @example\n * const part1 = cad.extrude(sk, { upTo: cad.faceRef(part0, 3) })\n */\nexport function faceRef(of: Shape, faceOrdinal: number): FaceTopoRef {\n  if (!Number.isInteger(faceOrdinal) || faceOrdinal < 1) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceRef: faceOrdinal must be an integer >= 1 (got ${faceOrdinal})`)\n  }\n  const kernel = getBackends().kernel.brep as BrepEngineApi | null\n  if (!kernel) throw new Error('[faceRef] no BREP kernel (face references are BREP-only)')\n  if (!brepOf(of)) throw new Error('[faceRef] E_FACE_REF_NO_BREP: input shape has no BREP solid')\n\n  const ctx = buildEdgeResolutionContext(kernel, of as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'faceRef: input has no BREP naming context')\n\n  const face = ctx.faces.find((f) => f.ordinal === faceOrdinal)\n  if (!face || face.handle === undefined) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'face',\n      `faceRef: face ordinal ${faceOrdinal} out of range [1, ${ctx.faces.length}]`,\n    )\n  }\n\n  const table = ctx.roleTable\n  if (!table) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'faceRef: input shape has no role table (nameless shape)')\n  }\n  const found = findOriginRole(table, ctx.faces.map((f) => f.hash ?? 0), faceOrdinal)\n  if (!found) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceRef: face ordinal ${faceOrdinal} has no role lineage`)\n  }\n\n  return { kind: 'face', origin: found.origin, role: found.role, hint: captureFaceHint(kernel, face.handle) }\n}\n"]}

package/dist/api/fai_drill.d.ts

@@ -0,0 +1,46 @@
+/**
+ * stdlib drill — 钻孔库函数
+ *
+ *
+ * dispatchPath 静态判定 brep/mesh。
+ * BREP 路径：OCCT cut（简单孔）或 threadBrep + cut（螺丝孔）。
+ */
+import type { Shape } from '../mesh/types.js';
+/**
+ * Validate drill parameters: `diameter` must be a positive number, `position`
+ * (if provided) a vec3, and `depth` (if provided) a number (<= 0 means a through hole).
+ * @param params - the raw drill operation parameters.
+ */
+export declare function assertDrillParams(params: Record<string, unknown>): void;
+/**
+ * 在几何体上钻孔（CSG 减除）。depth=0 为通孔，>0 为盲孔。
+ * @group 特征
+ * @inputs 1
+ * @async true
+ * @qual ok
+ * @name fai_drill
+ * @deprecated `fai_` 前缀 op 是 ../3d_editor 项目特有的操作，不属于 faijs 平台面；将来会迁往该项目并从 faijs 删除。新代码请勿使用。
+ * @note 键名以本表为准：`type: 'through'|'blind'` 与 `direction` 为向量的旧素材是无效写法——孔型由 `depth`（0=通孔）推导，`direction` 是 'normal'|'x'|'y'|'z' 枚举。
+ * @returns Shape 钻孔后的几何。
+ * @param input - 目标几何。type:Shape required:true
+ * @param params.diameter - 孔径（mm）。type:number required:true
+ * @param params.depth - 孔深（mm）；0 = 通孔，> 0 = 盲孔。type:number 默认 0
+ * @param params.holeType - 孔类型：simple 简单孔 / screw 螺丝孔。type:'simple' | 'screw' 默认 'simple'
+ * @param params.direction - 钻孔轴向（normal 表示沿面法向）。type:'normal' | 'x' | 'y' | 'z' 默认 'normal'
+ * @param params.position - 孔心位置。type:[x,y,z] 默认 原点
+ * @param params.face - 面引用（§6.2 新形态：`FaceTopoRef`，执行期按输入 Shape 解析派生法向；优先于 `faceNormal`）。type:FaceTopoRef
+ * @param params.faceNormal - 面法向（决定朝向；历史兜底，§6.2 起宿主不再写，改由 `face` 解析）。type:[x,y,z] 默认 [0,0,1]
+ * @param params.tolerance - 公差（mm）。type:number 默认 0.3
+ * @param params.screwSystem - 螺丝孔制式（holeType='screw' 时用）。type:'metric' | 'imperial' 默认 'metric'
+ * @param params.screwSpecIdx - 螺丝规格索引（holeType='screw' 时用；4 → M5）。type:number 默认 4
+ * @param params.screwThread - 螺丝螺纹类型。type:'coarse' | 'fine' | 'custom' 默认 'coarse'
+ * @param params.screwHead - 螺丝头型。type:'hex' | 'chc' | 'none' 默认 'none'
+ * @example
+ * const p = await cad.fai_drill(part0, { diameter: 5 })
+ * const p = await cad.fai_drill(part0, { diameter: 5, depth: 3 })
+ * const p = await cad.fai_drill(part0, { diameter: 5.2, depth: 8, holeType: 'screw', screwSystem: 'metric', screwSpecIdx: 4, screwThread: 'coarse', screwHead: 'none' })
+  */
+export declare const fai_drill: ((input: Shape, params: Record<string, unknown>) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=fai_drill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fai_drill.d.ts","sourceRoot":"","sources":["../../src/api/fai_drill.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAQ,MAAM,eAAe,CAAA;AAqBhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQvE;AAgLD;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2BI;AACJ,eAAO,MAAM,SAAS;;CAWpB,CAAA"}