@faicad/faijs 0.29.5 → 0.30.9

package/dist/api/curve-sketch/index.js

@@ -0,0 +1,487 @@
+/**
+ * api curve-sketch — 曲线与草图构造族（S4，平台 op engines:['occt']）
+ *
+ * @platform occt — 本目录 import occt-kernel：各 op 直调 occt 原生曲线构造/精修方法
+ * （`makeEdge` / `makeCircleArc` / `makeEllipseEdge` / `makeEllipseArc` /
+ * `makeTangentArc` / `approximatePoints` / `interpolatePointsWithTangents` /
+ * `curveDegreeElevate` / `curveKnotInsert` / `curveKnotRemove` / `curveIsPeriodic`，
+ * occt-wasm 原生有）。这些原生方法**不在** L1 契约 `BrepEngineApi` 里（L1 只有
+ * `makeLineEdge` / `makeArcEdge` / `interpolatePoints` 等按几何构造的子集，见
+ * brep/engine/primitives.ts）⇒ 全族平台 op：defineOp 声明 `engines: ['occt']`（D11）。
+ *
+ * 方案落点：docs/plans/2026-10-07-occt-wasm-op-enablement-plan.md §3.4.1。
+ * 与既有 op 的边界（§4.5 去重表）：`edge`（顶点对构造）≠ `makeLineEdge`（L1 点对构造，
+ * 无脚本符号）≠ `wire`（多边组装）；`approximatePoints`（逼近）与 L1 `interpolatePoints`
+ * （插值）是数学对偶的两条路径；`interpolateWithTangents` 是带端点切向的插值。
+ *
+ * 角度约定（实测钉住，见 test/api/occt-s4-curve-sketch.test.ts）：occt 原生
+ * `makeCircleArc` / `makeEllipseArc` 的起止角走 `Geom_TrimmedCurve`（**弧度**，
+ * 见 occt-wasm facade `Geom_TrimmedCurve(new Geom_Circle(circle), startAngle, endAngle)`）；
+ * 本仓契约「角度用度」（docs/api-contract.md）⇒ 脚本面收**度**、内部换算弧度。
+ *
+ * 产物形态（同 offset2d / helix）：1D 曲线经 `fromBrepCurve` 登记为 `kind:'curve'`
+ * （wire/edge 三角载荷为空，显示走 L1 `wireframe`）。
+ *
+ * `curveIsPeriodic` 返回布尔（非 Shape）⇒ 与 shape-type 族同口径：普通函数 +
+ * `assertEngineFor('curveIsPeriodic', ['occt'])`（见 api/shape-type/index.ts 头注），
+ * 覆盖率扫描器经 PLAN_C2_EXTRA 计入。
+ */
+import { solidToShape } from '../../brep/brep-ops.js';
+import { getBrepApi } from '../../brep/handle-bridge.js';
+import { brepOf, fromBrepCurve } from '../../shape.js';
+import { defineOp } from '../../sdk.js';
+import { getOcctKernel } from '../../occt-kernel/occtKernel.js';
+import { assertEngineFor } from '../internal/l3-bridge.js';
+/** 度 → 弧度（脚本面按契约收度；occt Geom_TrimmedCurve 吃弧度）。 */
+const DEG2RAD = Math.PI / 180;
+/** 1D 曲线产物登记：内核句柄 → kind:'curve' 的 faijs Shape。 */
+function adoptCurve(handle) {
+    return fromBrepCurve(solidToShape(getBrepApi(), handle), { solid: handle });
+}
+/** 元组 → {x,y,z}（同 halfSpace：occt 原生向量形参是 {x,y,z} 对象）。 */
+function toVec3(v, op, which) {
+    if (!Array.isArray(v) ||
+        v.length !== 3 ||
+        v.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+        throw new Error(`E_${op.toUpperCase()}_BAD_${which.toUpperCase()}: ${which} must be [x,y,z] finite numbers`);
+    }
+    return { x: v[0], y: v[1], z: v[2] };
+}
+/** 非零向量校验（方向/切向量）。 */
+function toNonZeroVec3(v, op, which) {
+    const out = toVec3(v, op, which);
+    if (out.x === 0 && out.y === 0 && out.z === 0) {
+        throw new Error(`E_${op.toUpperCase()}_BAD_${which.toUpperCase()}: ${which} must be a non-zero vector`);
+    }
+    return out;
+}
+/** 曲线输入 Shape → 内核句柄（无 BREP 槽报错）。 */
+function curveHandleOf(shape, op) {
+    const h = brepOf(shape);
+    if (!h) {
+        throw new Error(`E_${op.toUpperCase()}_NO_BREP: ${op} requires a BREP handle (mesh-only shape has none)`);
+    }
+    return h;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// edge — 顶点对构造边（occt 原生 makeEdge；顶点可来自 vertex Shape 或 [x,y,z]）
+// ─────────────────────────────────────────────────────────────────────────────
+/** 顶点入参：vertex Shape 或 [x,y,z] 点（内部经契约 makeVertex 物化）。 */
+function vertexHandleOf(v, op) {
+    if (Array.isArray(v)) {
+        const p = toVec3(v, op, 'vertex');
+        return getBrepApi().makeVertex(p.x, p.y, p.z);
+    }
+    return curveHandleOf(v, op);
+}
+/** BREP 路径：顶点对 → occt 原生 makeEdge。 */
+function edgeBrep(v1, v2) {
+    if (v1 === undefined || v2 === undefined) {
+        throw new Error('E_EDGE_MISSING_VERTEX: edge requires two vertices (vertex Shape or [x,y,z])');
+    }
+    const h1 = vertexHandleOf(v1, 'edge');
+    const h2 = vertexHandleOf(v2, 'edge');
+    const handle = getOcctKernel().makeEdge(h1, h2);
+    return adoptCurve(handle);
+}
+/**
+ * 两顶点构造边。顶点入参可以是 vertex Shape，也可以是 `[x,y,z]` 点
+ * （点经 L1 契约 `makeVertex` 物化成顶点再配边）。
+ * @group 创建
+ * @inputs 2
+ * @async false
+ * @qual ok
+ * @name edge
+ * @note 平台 op：仅 occt 引擎（原生 makeEdge，L1 契约只有 makeLineEdge 等按几何构造）。
+ *       非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @returns Shape 1D 直线边（kind:'curve'）。
+ * @param v1 - 第一个顶点（vertex Shape 或 [x,y,z]）。type:Shape|Vec3 required:true
+ * @param v2 - 第二个顶点（vertex Shape 或 [x,y,z]）。type:Shape|Vec3 required:true
+ * @example
+ * const e = cad.edge([0,0,0], [10,0,0])
+ */
+export const edge = defineOp({
+    name: 'edge',
+    brep(v1, v2) {
+        return edgeBrep(v1, v2);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D edge has no face role vocabulary' },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// circleArc — 圆心+法向+半径+起止角（度）构造圆弧
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 makeCircleArc（角度内部换算弧度）。 */
+function circleArcBrep(center, normal, radius, startAngleDeg, endAngleDeg) {
+    if (typeof radius !== 'number' || !(radius > 0)) {
+        throw new Error('E_CIRCLEARC_BAD_RADIUS: radius must be a positive number');
+    }
+    if (typeof startAngleDeg !== 'number' || !Number.isFinite(startAngleDeg) ||
+        typeof endAngleDeg !== 'number' || !Number.isFinite(endAngleDeg)) {
+        throw new Error('E_CIRCLEARC_BAD_ANGLE: startAngle/endAngle must be finite numbers (degrees)');
+    }
+    const c = toVec3(center, 'circleArc', 'center');
+    const n = toNonZeroVec3(normal, 'circleArc', 'normal');
+    const handle = getOcctKernel().makeCircleArc(c, n, radius, startAngleDeg * DEG2RAD, endAngleDeg * DEG2RAD);
+    return adoptCurve(handle);
+}
+/**
+ * 构造圆弧：圆心 + 法向 + 半径 + 起止角（度，绕法向右手逆时针）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name circleArc
+ * @note 平台 op：仅 occt 引擎（原生 makeCircleArc）。角度单位是**度**（内部换算弧度
+ *       传给 occt 的 Geom_TrimmedCurve）。
+ * @returns Shape 1D 圆弧（kind:'curve'）。
+ * @param center - 圆心 [x,y,z]。type:Vec3 required:true
+ * @param normal - 圆面法向 [x,y,z]（非零）。type:Vec3 required:true
+ * @param radius - 半径（mm，>0）。type:number required:true
+ * @param startAngle - 起始角（度，自法向基准 X 方向起量）。type:number required:true
+ * @param endAngle - 终止角（度）。type:number required:true
+ * @example
+ * const a = cad.circleArc([0,0,0], [0,0,1], 5, 0, 90)
+ */
+export const circleArc = defineOp({
+    name: 'circleArc',
+    paramDims: { center: 'length', normal: 'length', radius: 'length', startAngle: 'angle', endAngle: 'angle' },
+    brep(center, normal, radius, startAngleDeg, endAngleDeg) {
+        return circleArcBrep(center, normal, radius, startAngleDeg, endAngleDeg);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D arc has no face role vocabulary' },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// ellipseEdge / ellipseArc — 椭圆整边 / 椭圆弧
+// ─────────────────────────────────────────────────────────────────────────────
+/** 椭圆公共参数校验：两半径均正，且 major > minor（gp_Elips 约束）。 */
+function checkEllipseRadii(op, majorRadius, minorRadius) {
+    if (typeof majorRadius !== 'number' || !(majorRadius > 0)) {
+        throw new Error(`E_${op.toUpperCase()}_BAD_MAJOR: majorRadius must be a positive number`);
+    }
+    if (typeof minorRadius !== 'number' || !(minorRadius > 0)) {
+        throw new Error(`E_${op.toUpperCase()}_BAD_MINOR: minorRadius must be a positive number`);
+    }
+    if (minorRadius > majorRadius) {
+        throw new Error(`E_${op.toUpperCase()}_BAD_RADII: minorRadius must be <= majorRadius (gp_Elips constraint)`);
+    }
+}
+/** BREP 路径：occt 原生 makeEllipseEdge。 */
+function ellipseEdgeBrep(center, normal, majorRadius, minorRadius) {
+    checkEllipseRadii('ELLIPSEEDGE', majorRadius, minorRadius);
+    const c = toVec3(center, 'ellipseEdge', 'center');
+    const n = toNonZeroVec3(normal, 'ellipseEdge', 'normal');
+    const handle = getOcctKernel().makeEllipseEdge(c, n, majorRadius, minorRadius);
+    return adoptCurve(handle);
+}
+/**
+ * 构造整椭圆边：中心 + 法向 + 长半轴 + 短半轴。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name ellipseEdge
+ * @note 平台 op：仅 occt 引擎（原生 makeEllipseEdge）。要求 majorRadius >= minorRadius。
+ * @returns Shape 1D 椭圆边（kind:'curve'）。
+ * @param center - 椭圆中心 [x,y,z]。type:Vec3 required:true
+ * @param normal - 椭圆面法向 [x,y,z]（非零）。type:Vec3 required:true
+ * @param majorRadius - 长半轴（mm，>0）。type:number required:true
+ * @param minorRadius - 短半轴（mm，>0 且 <= 长半轴）。type:number required:true
+ * @example
+ * const e = cad.ellipseEdge([0,0,0], [0,0,1], 10, 5)
+ */
+export const ellipseEdge = defineOp({
+    name: 'ellipseEdge',
+    paramDims: { center: 'length', normal: 'length', majorRadius: 'length', minorRadius: 'length' },
+    brep(center, normal, majorRadius, minorRadius) {
+        return ellipseEdgeBrep(center, normal, majorRadius, minorRadius);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D ellipse has no face role vocabulary' },
+});
+/** BREP 路径：occt 原生 makeEllipseArc（角度内部换算弧度）。 */
+function ellipseArcBrep(center, normal, majorRadius, minorRadius, startAngleDeg, endAngleDeg) {
+    checkEllipseRadii('ELLIPSEARC', majorRadius, minorRadius);
+    if (typeof startAngleDeg !== 'number' || !Number.isFinite(startAngleDeg) ||
+        typeof endAngleDeg !== 'number' || !Number.isFinite(endAngleDeg)) {
+        throw new Error('E_ELLIPSEARC_BAD_ANGLE: startAngle/endAngle must be finite numbers (degrees)');
+    }
+    const c = toVec3(center, 'ellipseArc', 'center');
+    const n = toNonZeroVec3(normal, 'ellipseArc', 'normal');
+    const handle = getOcctKernel().makeEllipseArc(c, n, majorRadius, minorRadius, startAngleDeg * DEG2RAD, endAngleDeg * DEG2RAD);
+    return adoptCurve(handle);
+}
+/**
+ * 构造椭圆弧：中心 + 法向 + 长短半轴 + 起止角（度）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name ellipseArc
+ * @note 平台 op：仅 occt 引擎（原生 makeEllipseArc）。角度单位是**度**（内部换算弧度）。
+ * @returns Shape 1D 椭圆弧（kind:'curve'）。
+ * @param center - 椭圆中心 [x,y,z]。type:Vec3 required:true
+ * @param normal - 椭圆面法向 [x,y,z]（非零）。type:Vec3 required:true
+ * @param majorRadius - 长半轴（mm，>0）。type:number required:true
+ * @param minorRadius - 短半轴（mm，>0 且 <= 长半轴）。type:number required:true
+ * @param startAngle - 起始角（度）。type:number required:true
+ * @param endAngle - 终止角（度）。type:number required:true
+ * @example
+ * const a = cad.ellipseArc([0,0,0], [0,0,1], 10, 5, 0, 90)
+ */
+export const ellipseArc = defineOp({
+    name: 'ellipseArc',
+    paramDims: { center: 'length', normal: 'length', majorRadius: 'length', minorRadius: 'length', startAngle: 'angle', endAngle: 'angle' },
+    brep(center, normal, majorRadius, minorRadius, startAngleDeg, endAngleDeg) {
+        return ellipseArcBrep(center, normal, majorRadius, minorRadius, startAngleDeg, endAngleDeg);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D ellipse arc has no face role vocabulary' },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// tangentArc — 起点+切向+终点构造圆弧
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 makeTangentArc（GC_MakeArcOfCircle(start, tangent, end)）。 */
+function tangentArcBrep(start, tangent, end) {
+    const s = toVec3(start, 'tangentArc', 'start');
+    const t = toNonZeroVec3(tangent, 'tangentArc', 'tangent');
+    const e = toVec3(end, 'tangentArc', 'end');
+    const handle = getOcctKernel().makeTangentArc(s, t, e);
+    return adoptCurve(handle);
+}
+/**
+ * 构造圆弧：过起点、以给定切向出发、终于终点（GC_MakeArcOfCircle 语义）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name tangentArc
+ * @note 平台 op：仅 occt 引擎（原生 makeTangentArc）。切向为零向量非法。
+ * @returns Shape 1D 圆弧（kind:'curve'）。
+ * @param start - 起点 [x,y,z]。type:Vec3 required:true
+ * @param tangent - 起点切向 [x,y,z]（非零，不必单位化）。type:Vec3 required:true
+ * @param end - 终点 [x,y,z]。type:Vec3 required:true
+ * @example
+ * const a = cad.tangentArc([0,0,0], [1,0,0], [5,5,0])
+ */
+export const tangentArc = defineOp({
+    name: 'tangentArc',
+    paramDims: { start: 'length', tangent: 'length', end: 'length' },
+    brep(start, tangent, end) {
+        return tangentArcBrep(start, tangent, end);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D arc has no face role vocabulary' },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// approximatePoints — 点集逼近（与 L1 interpolatePoints 的插值成对）
+// ─────────────────────────────────────────────────────────────────────────────
+/** 点集校验（≥2 点）。 */
+function checkPoints(op, points) {
+    if (!Array.isArray(points) || points.length < 2) {
+        throw new Error(`E_${op.toUpperCase()}_BAD_POINTS: ${op} requires at least 2 points`);
+    }
+    for (const p of points)
+        toVec3(p, op, 'point');
+}
+/** BREP 路径：occt 原生 approximatePoints（逼近曲线；tolerance 缺省 = 原生 1e-3）。 */
+function approximatePointsBrep(points, tolerance) {
+    checkPoints('APPROXIMATEPOINTS', points);
+    if (tolerance !== undefined && (typeof tolerance !== 'number' || !(tolerance > 0))) {
+        throw new Error('E_APPROXIMATEPOINTS_BAD_TOLERANCE: tolerance must be a positive number');
+    }
+    const handle = (tolerance === undefined
+        ? getOcctKernel().approximatePoints(points)
+        : getOcctKernel().approximatePoints(points, tolerance));
+    return adoptCurve(handle);
+}
+/**
+ * 点集**逼近**曲线：过点但不严格插值（逼近容差内贴合，产平滑 B 样条）。
+ * 与 L1 `interpolatePoints`（严格插值）成对的数学对偶路径。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name approximatePoints
+ * @note 平台 op：仅 occt 引擎（原生 approximatePoints，tolerance 缺省 1e-3）。
+ * @returns Shape 1D 逼近曲线（kind:'curve'）。
+ * @param points - 点集 [x,y,z][]（≥2 点）。type:Vec3[] required:true
+ * @param tolerance - 逼近容差（mm，默认 1e-3）。type:number required:false
+ * @example
+ * const c = cad.approximatePoints([[0,0,0],[5,3,0],[10,0,0]])
+ */
+export const approximatePoints = defineOp({
+    name: 'approximatePoints',
+    paramDims: { points: 'length', tolerance: 'length' },
+    brep(points, tolerance) {
+        return approximatePointsBrep(points, tolerance);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D approximated curve has no face role vocabulary' },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// interpolateWithTangents — 带端点切向的插值
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 interpolatePointsWithTangents。 */
+function interpolateWithTangentsBrep(points, startTangent, endTangent) {
+    checkPoints('INTERPOLATEWITHTANGENTS', points);
+    const st = toNonZeroVec3(startTangent, 'interpolateWithTangents', 'startTangent');
+    const et = toNonZeroVec3(endTangent, 'interpolateWithTangents', 'endTangent');
+    const handle = getOcctKernel().interpolatePointsWithTangents(points, st, et);
+    return adoptCurve(handle);
+}
+/**
+ * 点集**插值**曲线，带端点切向约束（三次 B 样条，过全部点且端点切向指定）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name interpolateWithTangents
+ * @note 平台 op：仅 occt 引擎（原生 interpolatePointsWithTangents）。两端切向非零。
+ * @returns Shape 1D 插值曲线（kind:'curve'）。
+ * @param points - 点集 [x,y,z][]（≥2 点）。type:Vec3[] required:true
+ * @param startTangent - 起点切向 [x,y,z]（非零）。type:Vec3 required:true
+ * @param endTangent - 终点切向 [x,y,z]（非零）。type:Vec3 required:true
+ * @example
+ * const c = cad.interpolateWithTangents([[0,0,0],[5,3,0],[10,0,0]], [1,0,0], [1,0,0])
+ */
+export const interpolateWithTangents = defineOp({
+    name: 'interpolateWithTangents',
+    paramDims: { points: 'length', startTangent: 'length', endTangent: 'length' },
+    brep(points, startTangent, endTangent) {
+        return interpolateWithTangentsBrep(points, startTangent, endTangent);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D interpolated curve has no face role vocabulary' },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// NURBS 精修族 — curveDegreeElevate / curveKnotInsert / curveKnotRemove
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 curveDegreeElevate（NURBS 升阶）。 */
+function curveDegreeElevateBrep(curve, elevateBy) {
+    if (!Number.isInteger(elevateBy) || elevateBy <= 0) {
+        throw new Error('E_CURVEDEGREEELEVATE_BAD_STEP: elevateBy must be a positive integer');
+    }
+    const h = curveHandleOf(curve, 'curveDegreeElevate');
+    const handle = getOcctKernel().curveDegreeElevate(h, elevateBy);
+    return adoptCurve(handle);
+}
+/**
+ * NURBS 曲线升阶：把边/曲线的阶数提升 `elevateBy`（几何不变，表示空间变大）。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name curveDegreeElevate
+ * @note 平台 op：仅 occt 引擎（原生 curveDegreeElevate）。输入边/曲线。
+ * @returns Shape 升阶后的 1D 曲线（kind:'curve'）。
+ * @param curve - 输入边/曲线。type:Shape required:true
+ * @param elevateBy - 升阶量（正整数）。type:number required:true
+ * @example
+ * const up = cad.curveDegreeElevate(e, 2)
+ */
+export const curveDegreeElevate = defineOp({
+    name: 'curveDegreeElevate',
+    brep(curve, elevateBy) {
+        return curveDegreeElevateBrep(curve, elevateBy);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D refined curve has no face role vocabulary' },
+});
+/** BREP 路径：occt 原生 curveKnotInsert（插节点 times 次）。 */
+function curveKnotInsertBrep(curve, knot, times) {
+    if (typeof knot !== 'number' || !Number.isFinite(knot)) {
+        throw new Error('E_CURVEKNOTINSERT_BAD_KNOT: knot must be a finite number (curve parameter)');
+    }
+    if (!Number.isInteger(times) || times <= 0) {
+        throw new Error('E_CURVEKNOTINSERT_BAD_TIMES: times must be a positive integer');
+    }
+    const h = curveHandleOf(curve, 'curveKnotInsert');
+    const handle = getOcctKernel().curveKnotInsert(h, knot, times);
+    return adoptCurve(handle);
+}
+/**
+ * NURBS 曲线插节点：在曲线参数 `knot` 处插入节点 `times` 次（几何不变）。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name curveKnotInsert
+ * @note 平台 op：仅 occt 引擎（原生 curveKnotInsert）。knot 是曲线参数（不是长度）。
+ * @returns Shape 插节点后的 1D 曲线（kind:'curve'）。
+ * @param curve - 输入边/曲线。type:Shape required:true
+ * @param knot - 目标节点参数。type:number required:true
+ * @param times - 重复次数（正整数）。type:number required:true
+ * @example
+ * const refined = cad.curveKnotInsert(e, 0.5, 1)
+ */
+export const curveKnotInsert = defineOp({
+    name: 'curveKnotInsert',
+    brep(curve, knot, times) {
+        return curveKnotInsertBrep(curve, knot, times);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D refined curve has no face role vocabulary' },
+});
+/** BREP 路径：occt 原生 curveKnotRemove（容差内去节点）。 */
+function curveKnotRemoveBrep(curve, knot, tolerance) {
+    if (typeof knot !== 'number' || !Number.isFinite(knot)) {
+        throw new Error('E_CURVEKNOTREMOVE_BAD_KNOT: knot must be a finite number (curve parameter)');
+    }
+    if (typeof tolerance !== 'number' || !(tolerance > 0)) {
+        throw new Error('E_CURVEKNOTREMOVE_BAD_TOLERANCE: tolerance must be a positive number');
+    }
+    const h = curveHandleOf(curve, 'curveKnotRemove');
+    const handle = getOcctKernel().curveKnotRemove(h, knot, tolerance);
+    return adoptCurve(handle);
+}
+/**
+ * NURBS 曲线去节点：在容差内移除参数 `knot` 处的节点（几何漂移不超过 tolerance）。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name curveKnotRemove
+ * @note 平台 op：仅 occt 引擎（原生 curveKnotRemove）。knot 是曲线参数（不是长度）。
+ * @returns Shape 去节点后的 1D 曲线（kind:'curve'）。
+ * @param curve - 输入边/曲线。type:Shape required:true
+ * @param knot - 目标节点参数。type:number required:true
+ * @param tolerance - 允许的几何漂移（mm，>0）。type:number required:true
+ * @example
+ * const lean = cad.curveKnotRemove(e, 0.5, 1e-4)
+ */
+export const curveKnotRemove = defineOp({
+    name: 'curveKnotRemove',
+    paramDims: { tolerance: 'length' },
+    brep(curve, knot, tolerance) {
+        return curveKnotRemoveBrep(curve, knot, tolerance);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: '1D refined curve has no face role vocabulary' },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// curveIsPeriodic — 周期性查询（返回布尔 ⇒ 普通函数形态，同 shape-type 族口径）
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 曲线是否周期（L1 契约只有 `curveIsClosed`，周期性是 occt 原生独有查询）。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name curveIsPeriodic
+ * @note 平台 op：仅 occt 引擎（原生 curveIsPeriodic，L1 无对应成员）。非 occt 引擎
+ *       执行前报 E_BREP_UNSUPPORTED。
+ * @returns boolean 是否为周期曲线。
+ * @param curve - 被查询的边/曲线。type:Shape required:true
+ * @example
+ * const c = cad.circleArc([0,0,0], [0,0,1], 5, 0, 360)
+ * const periodic = cad.curveIsPeriodic(c)
+ */
+export function curveIsPeriodic(curve) {
+    assertEngineFor('curveIsPeriodic', ['occt']);
+    const h = curveHandleOf(curve, 'curveIsPeriodic');
+    const kernel = getOcctKernel();
+    return kernel.curveIsPeriodic(h);
+}
+//# sourceMappingURL=index.js.map

package/dist/api/curve-sketch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/curve-sketch/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api curve-sketch — 曲线与草图构造族（S4，平台 op engines:['occt']）\n *\n * @platform occt — 本目录 import occt-kernel：各 op 直调 occt 原生曲线构造/精修方法\n * （`makeEdge` / `makeCircleArc` / `makeEllipseEdge` / `makeEllipseArc` /\n * `makeTangentArc` / `approximatePoints` / `interpolatePointsWithTangents` /\n * `curveDegreeElevate` / `curveKnotInsert` / `curveKnotRemove` / `curveIsPeriodic`，\n * occt-wasm 原生有）。这些原生方法**不在** L1 契约 `BrepEngineApi` 里（L1 只有\n * `makeLineEdge` / `makeArcEdge` / `interpolatePoints` 等按几何构造的子集，见\n * brep/engine/primitives.ts）⇒ 全族平台 op：defineOp 声明 `engines: ['occt']`（D11）。\n *\n * 方案落点：docs/plans/2026-10-07-occt-wasm-op-enablement-plan.md §3.4.1。\n * 与既有 op 的边界（§4.5 去重表）：`edge`（顶点对构造）≠ `makeLineEdge`（L1 点对构造，\n * 无脚本符号）≠ `wire`（多边组装）；`approximatePoints`（逼近）与 L1 `interpolatePoints`\n * （插值）是数学对偶的两条路径；`interpolateWithTangents` 是带端点切向的插值。\n *\n * 角度约定（实测钉住，见 test/api/occt-s4-curve-sketch.test.ts）：occt 原生\n * `makeCircleArc` / `makeEllipseArc` 的起止角走 `Geom_TrimmedCurve`（**弧度**，\n * 见 occt-wasm facade `Geom_TrimmedCurve(new Geom_Circle(circle), startAngle, endAngle)`）；\n * 本仓契约「角度用度」（docs/api-contract.md）⇒ 脚本面收**度**、内部换算弧度。\n *\n * 产物形态（同 offset2d / helix）：1D 曲线经 `fromBrepCurve` 登记为 `kind:'curve'`\n * （wire/edge 三角载荷为空，显示走 L1 `wireframe`）。\n *\n * `curveIsPeriodic` 返回布尔（非 Shape）⇒ 与 shape-type 族同口径：普通函数 +\n * `assertEngineFor('curveIsPeriodic', ['occt'])`（见 api/shape-type/index.ts 头注），\n * 覆盖率扫描器经 PLAN_C2_EXTRA 计入。\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 { brepOf, fromBrepCurve } from '../../shape'\nimport { defineOp } from '../../sdk'\nimport type { Provenance } from '../../topology/naming/lineage'\nimport { getOcctKernel } from '../../occt-kernel/occtKernel'\nimport { assertEngineFor } from '../internal/l3-bridge'\n\ntype Vec3 = [number, number, number]\n\n/** 度 → 弧度（脚本面按契约收度；occt Geom_TrimmedCurve 吃弧度）。 */\nconst DEG2RAD = Math.PI / 180\n\n/** 1D 曲线产物登记：内核句柄 → kind:'curve' 的 faijs Shape。 */\nfunction adoptCurve(handle: BrepHandle): Shape {\n  return fromBrepCurve(solidToShape(getBrepApi(), handle), { solid: handle })\n}\n\n/** 元组 → {x,y,z}（同 halfSpace：occt 原生向量形参是 {x,y,z} 对象）。 */\nfunction toVec3(v: Vec3, op: string, which: string): { x: number; y: number; z: number } {\n  if (\n    !Array.isArray(v) ||\n    v.length !== 3 ||\n    v.some((n) => typeof n !== 'number' || !Number.isFinite(n))\n  ) {\n    throw new Error(`E_${op.toUpperCase()}_BAD_${which.toUpperCase()}: ${which} must be [x,y,z] finite numbers`)\n  }\n  return { x: v[0], y: v[1], z: v[2] }\n}\n\n/** 非零向量校验（方向/切向量）。 */\nfunction toNonZeroVec3(v: Vec3, op: string, which: string): { x: number; y: number; z: number } {\n  const out = toVec3(v, op, which)\n  if (out.x === 0 && out.y === 0 && out.z === 0) {\n    throw new Error(`E_${op.toUpperCase()}_BAD_${which.toUpperCase()}: ${which} must be a non-zero vector`)\n  }\n  return out\n}\n\n/** 曲线输入 Shape → 内核句柄（无 BREP 槽报错）。 */\nfunction curveHandleOf(shape: Shape, op: string): BrepHandle {\n  const h = brepOf(shape) as BrepHandle | undefined\n  if (!h) {\n    throw new Error(`E_${op.toUpperCase()}_NO_BREP: ${op} requires a BREP handle (mesh-only shape has none)`)\n  }\n  return h\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// edge — 顶点对构造边（occt 原生 makeEdge；顶点可来自 vertex Shape 或 [x,y,z]）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** 顶点入参：vertex Shape 或 [x,y,z] 点（内部经契约 makeVertex 物化）。 */\nfunction vertexHandleOf(v: Shape | Vec3, op: string): BrepHandle {\n  if (Array.isArray(v)) {\n    const p = toVec3(v, op, 'vertex')\n    return getBrepApi().makeVertex(p.x, p.y, p.z) as unknown as BrepHandle\n  }\n  return curveHandleOf(v, op)\n}\n\n/** BREP 路径：顶点对 → occt 原生 makeEdge。 */\nfunction edgeBrep(v1: Shape | Vec3, v2: Shape | Vec3): Shape {\n  if (v1 === undefined || v2 === undefined) {\n    throw new Error('E_EDGE_MISSING_VERTEX: edge requires two vertices (vertex Shape or [x,y,z])')\n  }\n  const h1 = vertexHandleOf(v1, 'edge')\n  const h2 = vertexHandleOf(v2, 'edge')\n  const handle = getOcctKernel().makeEdge(h1 as never, h2 as never) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * 两顶点构造边。顶点入参可以是 vertex Shape，也可以是 `[x,y,z]` 点\n * （点经 L1 契约 `makeVertex` 物化成顶点再配边）。\n * @group 创建\n * @inputs 2\n * @async false\n * @qual ok\n * @name edge\n * @note 平台 op：仅 occt 引擎（原生 makeEdge，L1 契约只有 makeLineEdge 等按几何构造）。\n *       非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 1D 直线边（kind:'curve'）。\n * @param v1 - 第一个顶点（vertex Shape 或 [x,y,z]）。type:Shape|Vec3 required:true\n * @param v2 - 第二个顶点（vertex Shape 或 [x,y,z]）。type:Shape|Vec3 required:true\n * @example\n * const e = cad.edge([0,0,0], [10,0,0])\n */\nexport const edge = defineOp({\n  name: 'edge',\n  brep(v1: Shape | Vec3, v2: Shape | Vec3) {\n    return edgeBrep(v1, v2)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D edge has no face role vocabulary' } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// circleArc — 圆心+法向+半径+起止角（度）构造圆弧\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 makeCircleArc（角度内部换算弧度）。 */\nfunction circleArcBrep(\n  center: Vec3,\n  normal: Vec3,\n  radius: number,\n  startAngleDeg: number,\n  endAngleDeg: number,\n): Shape {\n  if (typeof radius !== 'number' || !(radius > 0)) {\n    throw new Error('E_CIRCLEARC_BAD_RADIUS: radius must be a positive number')\n  }\n  if (\n    typeof startAngleDeg !== 'number' || !Number.isFinite(startAngleDeg) ||\n    typeof endAngleDeg !== 'number' || !Number.isFinite(endAngleDeg)\n  ) {\n    throw new Error('E_CIRCLEARC_BAD_ANGLE: startAngle/endAngle must be finite numbers (degrees)')\n  }\n  const c = toVec3(center, 'circleArc', 'center')\n  const n = toNonZeroVec3(normal, 'circleArc', 'normal')\n  const handle = getOcctKernel().makeCircleArc(\n    c as never, n as never, radius, startAngleDeg * DEG2RAD, endAngleDeg * DEG2RAD,\n  ) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * 构造圆弧：圆心 + 法向 + 半径 + 起止角（度，绕法向右手逆时针）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name circleArc\n * @note 平台 op：仅 occt 引擎（原生 makeCircleArc）。角度单位是**度**（内部换算弧度\n *       传给 occt 的 Geom_TrimmedCurve）。\n * @returns Shape 1D 圆弧（kind:'curve'）。\n * @param center - 圆心 [x,y,z]。type:Vec3 required:true\n * @param normal - 圆面法向 [x,y,z]（非零）。type:Vec3 required:true\n * @param radius - 半径（mm，>0）。type:number required:true\n * @param startAngle - 起始角（度，自法向基准 X 方向起量）。type:number required:true\n * @param endAngle - 终止角（度）。type:number required:true\n * @example\n * const a = cad.circleArc([0,0,0], [0,0,1], 5, 0, 90)\n */\nexport const circleArc = defineOp({\n  name: 'circleArc',\n  paramDims: { center: 'length', normal: 'length', radius: 'length', startAngle: 'angle', endAngle: 'angle' },\n  brep(center: Vec3, normal: Vec3, radius: number, startAngleDeg: number, endAngleDeg: number) {\n    return circleArcBrep(center, normal, radius, startAngleDeg, endAngleDeg)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D arc has no face role vocabulary' } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ellipseEdge / ellipseArc — 椭圆整边 / 椭圆弧\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** 椭圆公共参数校验：两半径均正，且 major > minor（gp_Elips 约束）。 */\nfunction checkEllipseRadii(op: string, majorRadius: number, minorRadius: number): void {\n  if (typeof majorRadius !== 'number' || !(majorRadius > 0)) {\n    throw new Error(`E_${op.toUpperCase()}_BAD_MAJOR: majorRadius must be a positive number`)\n  }\n  if (typeof minorRadius !== 'number' || !(minorRadius > 0)) {\n    throw new Error(`E_${op.toUpperCase()}_BAD_MINOR: minorRadius must be a positive number`)\n  }\n  if (minorRadius > majorRadius) {\n    throw new Error(`E_${op.toUpperCase()}_BAD_RADII: minorRadius must be <= majorRadius (gp_Elips constraint)`)\n  }\n}\n\n/** BREP 路径：occt 原生 makeEllipseEdge。 */\nfunction ellipseEdgeBrep(center: Vec3, normal: Vec3, majorRadius: number, minorRadius: number): Shape {\n  checkEllipseRadii('ELLIPSEEDGE', majorRadius, minorRadius)\n  const c = toVec3(center, 'ellipseEdge', 'center')\n  const n = toNonZeroVec3(normal, 'ellipseEdge', 'normal')\n  const handle = getOcctKernel().makeEllipseEdge(c as never, n as never, majorRadius, minorRadius) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * 构造整椭圆边：中心 + 法向 + 长半轴 + 短半轴。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name ellipseEdge\n * @note 平台 op：仅 occt 引擎（原生 makeEllipseEdge）。要求 majorRadius >= minorRadius。\n * @returns Shape 1D 椭圆边（kind:'curve'）。\n * @param center - 椭圆中心 [x,y,z]。type:Vec3 required:true\n * @param normal - 椭圆面法向 [x,y,z]（非零）。type:Vec3 required:true\n * @param majorRadius - 长半轴（mm，>0）。type:number required:true\n * @param minorRadius - 短半轴（mm，>0 且 <= 长半轴）。type:number required:true\n * @example\n * const e = cad.ellipseEdge([0,0,0], [0,0,1], 10, 5)\n */\nexport const ellipseEdge = defineOp({\n  name: 'ellipseEdge',\n  paramDims: { center: 'length', normal: 'length', majorRadius: 'length', minorRadius: 'length' },\n  brep(center: Vec3, normal: Vec3, majorRadius: number, minorRadius: number) {\n    return ellipseEdgeBrep(center, normal, majorRadius, minorRadius)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D ellipse has no face role vocabulary' } as Provenance,\n})\n\n/** BREP 路径：occt 原生 makeEllipseArc（角度内部换算弧度）。 */\nfunction ellipseArcBrep(\n  center: Vec3,\n  normal: Vec3,\n  majorRadius: number,\n  minorRadius: number,\n  startAngleDeg: number,\n  endAngleDeg: number,\n): Shape {\n  checkEllipseRadii('ELLIPSEARC', majorRadius, minorRadius)\n  if (\n    typeof startAngleDeg !== 'number' || !Number.isFinite(startAngleDeg) ||\n    typeof endAngleDeg !== 'number' || !Number.isFinite(endAngleDeg)\n  ) {\n    throw new Error('E_ELLIPSEARC_BAD_ANGLE: startAngle/endAngle must be finite numbers (degrees)')\n  }\n  const c = toVec3(center, 'ellipseArc', 'center')\n  const n = toNonZeroVec3(normal, 'ellipseArc', 'normal')\n  const handle = getOcctKernel().makeEllipseArc(\n    c as never, n as never, majorRadius, minorRadius, startAngleDeg * DEG2RAD, endAngleDeg * DEG2RAD,\n  ) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * 构造椭圆弧：中心 + 法向 + 长短半轴 + 起止角（度）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name ellipseArc\n * @note 平台 op：仅 occt 引擎（原生 makeEllipseArc）。角度单位是**度**（内部换算弧度）。\n * @returns Shape 1D 椭圆弧（kind:'curve'）。\n * @param center - 椭圆中心 [x,y,z]。type:Vec3 required:true\n * @param normal - 椭圆面法向 [x,y,z]（非零）。type:Vec3 required:true\n * @param majorRadius - 长半轴（mm，>0）。type:number required:true\n * @param minorRadius - 短半轴（mm，>0 且 <= 长半轴）。type:number required:true\n * @param startAngle - 起始角（度）。type:number required:true\n * @param endAngle - 终止角（度）。type:number required:true\n * @example\n * const a = cad.ellipseArc([0,0,0], [0,0,1], 10, 5, 0, 90)\n */\nexport const ellipseArc = defineOp({\n  name: 'ellipseArc',\n  paramDims: { center: 'length', normal: 'length', majorRadius: 'length', minorRadius: 'length', startAngle: 'angle', endAngle: 'angle' },\n  brep(center: Vec3, normal: Vec3, majorRadius: number, minorRadius: number, startAngleDeg: number, endAngleDeg: number) {\n    return ellipseArcBrep(center, normal, majorRadius, minorRadius, startAngleDeg, endAngleDeg)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D ellipse arc has no face role vocabulary' } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// tangentArc — 起点+切向+终点构造圆弧\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 makeTangentArc（GC_MakeArcOfCircle(start, tangent, end)）。 */\nfunction tangentArcBrep(start: Vec3, tangent: Vec3, end: Vec3): Shape {\n  const s = toVec3(start, 'tangentArc', 'start')\n  const t = toNonZeroVec3(tangent, 'tangentArc', 'tangent')\n  const e = toVec3(end, 'tangentArc', 'end')\n  const handle = getOcctKernel().makeTangentArc(s as never, t as never, e as never) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * 构造圆弧：过起点、以给定切向出发、终于终点（GC_MakeArcOfCircle 语义）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name tangentArc\n * @note 平台 op：仅 occt 引擎（原生 makeTangentArc）。切向为零向量非法。\n * @returns Shape 1D 圆弧（kind:'curve'）。\n * @param start - 起点 [x,y,z]。type:Vec3 required:true\n * @param tangent - 起点切向 [x,y,z]（非零，不必单位化）。type:Vec3 required:true\n * @param end - 终点 [x,y,z]。type:Vec3 required:true\n * @example\n * const a = cad.tangentArc([0,0,0], [1,0,0], [5,5,0])\n */\nexport const tangentArc = defineOp({\n  name: 'tangentArc',\n  paramDims: { start: 'length', tangent: 'length', end: 'length' },\n  brep(start: Vec3, tangent: Vec3, end: Vec3) {\n    return tangentArcBrep(start, tangent, end)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D arc has no face role vocabulary' } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// approximatePoints — 点集逼近（与 L1 interpolatePoints 的插值成对）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** 点集校验（≥2 点）。 */\nfunction checkPoints(op: string, points: Vec3[]): void {\n  if (!Array.isArray(points) || points.length < 2) {\n    throw new Error(`E_${op.toUpperCase()}_BAD_POINTS: ${op} requires at least 2 points`)\n  }\n  for (const p of points) toVec3(p, op, 'point')\n}\n\n/** BREP 路径：occt 原生 approximatePoints（逼近曲线；tolerance 缺省 = 原生 1e-3）。 */\nfunction approximatePointsBrep(points: Vec3[], tolerance?: number): Shape {\n  checkPoints('APPROXIMATEPOINTS', points)\n  if (tolerance !== undefined && (typeof tolerance !== 'number' || !(tolerance > 0))) {\n    throw new Error('E_APPROXIMATEPOINTS_BAD_TOLERANCE: tolerance must be a positive number')\n  }\n  const handle = (\n    tolerance === undefined\n      ? getOcctKernel().approximatePoints(points as never)\n      : getOcctKernel().approximatePoints(points as never, tolerance)\n  ) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * 点集**逼近**曲线：过点但不严格插值（逼近容差内贴合，产平滑 B 样条）。\n * 与 L1 `interpolatePoints`（严格插值）成对的数学对偶路径。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name approximatePoints\n * @note 平台 op：仅 occt 引擎（原生 approximatePoints，tolerance 缺省 1e-3）。\n * @returns Shape 1D 逼近曲线（kind:'curve'）。\n * @param points - 点集 [x,y,z][]（≥2 点）。type:Vec3[] required:true\n * @param tolerance - 逼近容差（mm，默认 1e-3）。type:number required:false\n * @example\n * const c = cad.approximatePoints([[0,0,0],[5,3,0],[10,0,0]])\n */\nexport const approximatePoints = defineOp({\n  name: 'approximatePoints',\n  paramDims: { points: 'length', tolerance: 'length' },\n  brep(points: Vec3[], tolerance?: number) {\n    return approximatePointsBrep(points, tolerance)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D approximated curve has no face role vocabulary' } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// interpolateWithTangents — 带端点切向的插值\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 interpolatePointsWithTangents。 */\nfunction interpolateWithTangentsBrep(points: Vec3[], startTangent: Vec3, endTangent: Vec3): Shape {\n  checkPoints('INTERPOLATEWITHTANGENTS', points)\n  const st = toNonZeroVec3(startTangent, 'interpolateWithTangents', 'startTangent')\n  const et = toNonZeroVec3(endTangent, 'interpolateWithTangents', 'endTangent')\n  const handle = getOcctKernel().interpolatePointsWithTangents(\n    points as never, st as never, et as never,\n  ) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * 点集**插值**曲线，带端点切向约束（三次 B 样条，过全部点且端点切向指定）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name interpolateWithTangents\n * @note 平台 op：仅 occt 引擎（原生 interpolatePointsWithTangents）。两端切向非零。\n * @returns Shape 1D 插值曲线（kind:'curve'）。\n * @param points - 点集 [x,y,z][]（≥2 点）。type:Vec3[] required:true\n * @param startTangent - 起点切向 [x,y,z]（非零）。type:Vec3 required:true\n * @param endTangent - 终点切向 [x,y,z]（非零）。type:Vec3 required:true\n * @example\n * const c = cad.interpolateWithTangents([[0,0,0],[5,3,0],[10,0,0]], [1,0,0], [1,0,0])\n */\nexport const interpolateWithTangents = defineOp({\n  name: 'interpolateWithTangents',\n  paramDims: { points: 'length', startTangent: 'length', endTangent: 'length' },\n  brep(points: Vec3[], startTangent: Vec3, endTangent: Vec3) {\n    return interpolateWithTangentsBrep(points, startTangent, endTangent)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D interpolated curve has no face role vocabulary' } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// NURBS 精修族 — curveDegreeElevate / curveKnotInsert / curveKnotRemove\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 curveDegreeElevate（NURBS 升阶）。 */\nfunction curveDegreeElevateBrep(curve: Shape, elevateBy: number): Shape {\n  if (!Number.isInteger(elevateBy) || elevateBy <= 0) {\n    throw new Error('E_CURVEDEGREEELEVATE_BAD_STEP: elevateBy must be a positive integer')\n  }\n  const h = curveHandleOf(curve, 'curveDegreeElevate')\n  const handle = getOcctKernel().curveDegreeElevate(h as never, elevateBy) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * NURBS 曲线升阶：把边/曲线的阶数提升 `elevateBy`（几何不变，表示空间变大）。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name curveDegreeElevate\n * @note 平台 op：仅 occt 引擎（原生 curveDegreeElevate）。输入边/曲线。\n * @returns Shape 升阶后的 1D 曲线（kind:'curve'）。\n * @param curve - 输入边/曲线。type:Shape required:true\n * @param elevateBy - 升阶量（正整数）。type:number required:true\n * @example\n * const up = cad.curveDegreeElevate(e, 2)\n */\nexport const curveDegreeElevate = defineOp({\n  name: 'curveDegreeElevate',\n  brep(curve: Shape, elevateBy: number) {\n    return curveDegreeElevateBrep(curve, elevateBy)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D refined curve has no face role vocabulary' } as Provenance,\n})\n\n/** BREP 路径：occt 原生 curveKnotInsert（插节点 times 次）。 */\nfunction curveKnotInsertBrep(curve: Shape, knot: number, times: number): Shape {\n  if (typeof knot !== 'number' || !Number.isFinite(knot)) {\n    throw new Error('E_CURVEKNOTINSERT_BAD_KNOT: knot must be a finite number (curve parameter)')\n  }\n  if (!Number.isInteger(times) || times <= 0) {\n    throw new Error('E_CURVEKNOTINSERT_BAD_TIMES: times must be a positive integer')\n  }\n  const h = curveHandleOf(curve, 'curveKnotInsert')\n  const handle = getOcctKernel().curveKnotInsert(h as never, knot, times) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * NURBS 曲线插节点：在曲线参数 `knot` 处插入节点 `times` 次（几何不变）。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name curveKnotInsert\n * @note 平台 op：仅 occt 引擎（原生 curveKnotInsert）。knot 是曲线参数（不是长度）。\n * @returns Shape 插节点后的 1D 曲线（kind:'curve'）。\n * @param curve - 输入边/曲线。type:Shape required:true\n * @param knot - 目标节点参数。type:number required:true\n * @param times - 重复次数（正整数）。type:number required:true\n * @example\n * const refined = cad.curveKnotInsert(e, 0.5, 1)\n */\nexport const curveKnotInsert = defineOp({\n  name: 'curveKnotInsert',\n  brep(curve: Shape, knot: number, times: number) {\n    return curveKnotInsertBrep(curve, knot, times)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D refined curve has no face role vocabulary' } as Provenance,\n})\n\n/** BREP 路径：occt 原生 curveKnotRemove（容差内去节点）。 */\nfunction curveKnotRemoveBrep(curve: Shape, knot: number, tolerance: number): Shape {\n  if (typeof knot !== 'number' || !Number.isFinite(knot)) {\n    throw new Error('E_CURVEKNOTREMOVE_BAD_KNOT: knot must be a finite number (curve parameter)')\n  }\n  if (typeof tolerance !== 'number' || !(tolerance > 0)) {\n    throw new Error('E_CURVEKNOTREMOVE_BAD_TOLERANCE: tolerance must be a positive number')\n  }\n  const h = curveHandleOf(curve, 'curveKnotRemove')\n  const handle = getOcctKernel().curveKnotRemove(h as never, knot, tolerance) as unknown as BrepHandle\n  return adoptCurve(handle)\n}\n\n/**\n * NURBS 曲线去节点：在容差内移除参数 `knot` 处的节点（几何漂移不超过 tolerance）。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name curveKnotRemove\n * @note 平台 op：仅 occt 引擎（原生 curveKnotRemove）。knot 是曲线参数（不是长度）。\n * @returns Shape 去节点后的 1D 曲线（kind:'curve'）。\n * @param curve - 输入边/曲线。type:Shape required:true\n * @param knot - 目标节点参数。type:number required:true\n * @param tolerance - 允许的几何漂移（mm，>0）。type:number required:true\n * @example\n * const lean = cad.curveKnotRemove(e, 0.5, 1e-4)\n */\nexport const curveKnotRemove = defineOp({\n  name: 'curveKnotRemove',\n  paramDims: { tolerance: 'length' },\n  brep(curve: Shape, knot: number, tolerance: number) {\n    return curveKnotRemoveBrep(curve, knot, tolerance)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: '1D refined curve has no face role vocabulary' } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// curveIsPeriodic — 周期性查询（返回布尔 ⇒ 普通函数形态，同 shape-type 族口径）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * 曲线是否周期（L1 契约只有 `curveIsClosed`，周期性是 occt 原生独有查询）。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name curveIsPeriodic\n * @note 平台 op：仅 occt 引擎（原生 curveIsPeriodic，L1 无对应成员）。非 occt 引擎\n *       执行前报 E_BREP_UNSUPPORTED。\n * @returns boolean 是否为周期曲线。\n * @param curve - 被查询的边/曲线。type:Shape required:true\n * @example\n * const c = cad.circleArc([0,0,0], [0,0,1], 5, 0, 360)\n * const periodic = cad.curveIsPeriodic(c)\n */\nexport function curveIsPeriodic(curve: Shape): boolean {\n  assertEngineFor('curveIsPeriodic', ['occt'])\n  const h = curveHandleOf(curve, 'curveIsPeriodic')\n  const kernel = getOcctKernel() as unknown as { curveIsPeriodic(h: unknown): boolean }\n  return kernel.curveIsPeriodic(h)\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"engrave.d.ts","sourceRoot":"","sources":["../../src/api/engrave.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAQ,MAAM,eAAe,CAAA;AAqBhD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASzE;AAqID;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,eAAO,MAAM,OAAO;;CA8BlB,CAAA"}
+{"version":3,"file":"engrave.d.ts","sourceRoot":"","sources":["../../src/api/engrave.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAQ,MAAM,eAAe,CAAA;AAsBhD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASzE;AAqID;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,eAAO,MAAM,OAAO;;CA8BlB,CAAA"}

package/dist/api/engrave.js

@@ -5,7 +5,8 @@
  * dispatchPath 静态判定 brep/mesh。
  * BREP 路径：textToSolid/svgToSolid + boolean（cut/fuse）。
  */
-import { cad } from '../mesh/index.js';
+// B3 correction (2026-10-06): no library-face cad aggregate — import the impl from its own module.
+import * as meshEngrave from '../mesh/engrave.js';
 import { parseSvgNaturalSize } from '../primitives/parse-svg-size.js';
 import { textToSolid } from '../brep/text/text-to-solid.js';
 import { svgToSolid } from '../brep/svg/svg-to-solid.js';
@@ -191,7 +192,7 @@ export const engrave = defineOp({
         const faceNormal = params.faceNormal ?? [0, 0, 1];
         const { naturalWidth, naturalHeight } = svgText ? parseSvgNaturalSize(svgText) : { naturalWidth: 0, naturalHeight: 0 };
         const hasText = !!params.text;
-        return cad.engrave(input, {
+        return meshEngrave.engrave(input, {
             mode: params.mode ?? 'concave',
             depth: params.depth,
             face: { center: faceCenter, normal: faceNormal },