@faicad/faijs 0.29.5 → 0.31.1

package/dist/api/surface-face/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * api surface-face — 曲面与面构造族（S4，平台 op engines:['occt']）
+ *
+ * @platform occt — 本目录 import occt-kernel：各 op 直调 occt 原生面/曲面构造与查询
+ * 方法（`makeFaceOnSurface` / `makeNonPlanarFace` / `makeSolid` / `reverseSurfaceU` /
+ * `outerWire`，occt-wasm 原生有）。这些原生方法**不在** L1 契约 `BrepEngineApi` 里
+ * （L1 只有 `makeFace`（仅平面）与 `getSubShapes` 等子集，见 brep/engine/primitives.ts）
+ * ⇒ 全族平台 op：defineOp 声明 `engines: ['occt']`（D11）。
+ *
+ * 方案落点：docs/plans/2026-10-07-occt-wasm-op-enablement-plan.md §3.4.2。
+ * 与既有 op 的边界（§4.5 去重表）：
+ * - `makeSolid` vs `sewAndSolidify` / `compound`：前者输入是**已闭合的壳**，直接升为
+ *   实体；后两者分别走「面 → 缝合 → 固化」链 / 聚合；
+ * - `nonPlanarFace` vs L1 `makeFace`：后者只处理平面 wire，前者接受非平面 wire；
+ * - `outerWire`（取面外环）vs `offset2d`（偏置）：纯查询 vs 几何构造。
+ *
+ * 产物形态：面/实体经 `fromBrep` 收养；wire（outerWire 产物）经 `fromBrepCurve`
+ * 登记为 `kind:'curve'`（同 offset2d 口径）。
+ */
+import type { Shape } from '../../mesh/types.js';
+/**
+ * 在已有曲面上建面：以宿主面（承载曲面）为底，用曲面上的闭合 wire 圈出新面。
+ * @group 创建
+ * @inputs 2
+ * @async false
+ * @qual ok
+ * @name faceOnSurface
+ * @note 平台 op：仅 occt 引擎（原生 makeFaceOnSurface，L1 契约无对应成员）。
+ *       非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @returns Shape 新建的面。
+ * @param hostFace - 宿主面（承载曲面）。type:Shape required:true
+ * @param wire - 曲面上的闭合边界 wire。type:Shape required:true
+ * @example
+ * const f = cad.faceOnSurface(cylFace, boundaryWire)
+ */
+export declare const faceOnSurface: ((hostFace: Shape, wire: Shape) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../../define-op.js").DualOpMeta;
+};
+/**
+ * 由非平面闭合 wire 构造面（L1 `makeFace` 只处理平面 wire；本 op 补非平面缺口）。
+ * @group 创建
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name nonPlanarFace
+ * @note 平台 op：仅 occt 引擎（原生 makeNonPlanarFace）。wire 须闭合。
+ * @returns Shape 构造出的面。
+ * @param wire - 闭合边界 wire（可非平面）。type:Shape required:true
+ * @example
+ * const f = cad.nonPlanarFace(curvedBoundaryWire)
+ */
+export declare const nonPlanarFace: ((wire: Shape) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../../define-op.js").DualOpMeta;
+};
+/**
+ * 把已闭合的壳升为实体（输入是壳，不做缝合——缝合链见 `sewAndSolidify`）。
+ * @group 创建
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name makeSolid
+ * @note 平台 op：仅 occt 引擎（原生 makeSolid）。输入须为闭合 shell。
+ * @returns Shape 实体。
+ * @param shell - 已闭合的壳。type:Shape required:true
+ * @example
+ * const s = cad.makeSolid(closedShell)
+ */
+export declare const makeSolid: ((shell: Shape) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../../define-op.js").DualOpMeta;
+};
+/**
+ * 反转面的 U 参数方向（occt `Geom_Surface::UReverse` 语义）：返回新面代理，
+ * 其曲面是原曲面的 U 反转版（拓扑不变，UV 求值随之镜像）。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name reverseSurfaceU
+ * @note 平台 op：仅 occt 引擎（原生 reverseSurfaceU）。输入面。
+ * @returns Shape U 反转后的面。
+ * @param face - 输入面。type:Shape required:true
+ * @example
+ * const flipped = cad.reverseSurfaceU(f)
+ */
+export declare const reverseSurfaceU: ((face: Shape) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../../define-op.js").DualOpMeta;
+};
+/**
+ * 取面的外环（outer wire）：面上边界中最大的闭合 wire，1D 产物。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name outerWire
+ * @note 平台 op：仅 occt 引擎（原生 outerWire）。产物 kind='curve'（1D wire）。
+ * @returns Shape 面的外环（kind:'curve'）。
+ * @param face - 输入面。type:Shape required:true
+ * @example
+ * const ow = cad.outerWire(face0)
+ */
+export declare const outerWire: ((face: Shape) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/api/surface-face/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/surface-face/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAiC7C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa;;CAUxB,CAAA;AAgBF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa;;CAUxB,CAAA;AAgBF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS;;CAUpB,CAAA;AAgBF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe;;CAU1B,CAAA;AAgBF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS;;CAUpB,CAAA"}

package/dist/api/surface-face/index.js

@@ -0,0 +1,217 @@
+/**
+ * api surface-face — 曲面与面构造族（S4，平台 op engines:['occt']）
+ *
+ * @platform occt — 本目录 import occt-kernel：各 op 直调 occt 原生面/曲面构造与查询
+ * 方法（`makeFaceOnSurface` / `makeNonPlanarFace` / `makeSolid` / `reverseSurfaceU` /
+ * `outerWire`，occt-wasm 原生有）。这些原生方法**不在** L1 契约 `BrepEngineApi` 里
+ * （L1 只有 `makeFace`（仅平面）与 `getSubShapes` 等子集，见 brep/engine/primitives.ts）
+ * ⇒ 全族平台 op：defineOp 声明 `engines: ['occt']`（D11）。
+ *
+ * 方案落点：docs/plans/2026-10-07-occt-wasm-op-enablement-plan.md §3.4.2。
+ * 与既有 op 的边界（§4.5 去重表）：
+ * - `makeSolid` vs `sewAndSolidify` / `compound`：前者输入是**已闭合的壳**，直接升为
+ *   实体；后两者分别走「面 → 缝合 → 固化」链 / 聚合；
+ * - `nonPlanarFace` vs L1 `makeFace`：后者只处理平面 wire，前者接受非平面 wire；
+ * - `outerWire`（取面外环）vs `offset2d`（偏置）：纯查询 vs 几何构造。
+ *
+ * 产物形态：面/实体经 `fromBrep` 收养；wire（outerWire 产物）经 `fromBrepCurve`
+ * 登记为 `kind:'curve'`（同 offset2d 口径）。
+ */
+import { solidToShape } from '../../brep/brep-ops.js';
+import { getBrepApi } from '../../brep/handle-bridge.js';
+import { brepOf, fromBrep, fromBrepCurve } from '../../shape.js';
+import { defineOp } from '../../sdk.js';
+import { getOcctKernel } from '../../occt-kernel/occtKernel.js';
+/** 输入 Shape → 内核句柄（无 BREP 槁报错）。 */
+function handleOf(shape, op, which) {
+    const h = brepOf(shape);
+    if (!h) {
+        throw new Error(`E_${op.toUpperCase()}_NO_BREP: ${op} requires a BREP handle for ${which} (mesh-only shape has none)`);
+    }
+    return h;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// faceOnSurface — 在已有面上建面（宿主面 + 曲面上的闭合 wire）
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 makeFaceOnSurface。 */
+function faceOnSurfaceBrep(hostFace, wire) {
+    if (!hostFace || !wire) {
+        throw new Error('E_FACEONSURFACE_MISSING_ARG: faceOnSurface requires a host face and a boundary wire');
+    }
+    const fh = handleOf(hostFace, 'faceOnSurface', 'host face');
+    const wh = handleOf(wire, 'faceOnSurface', 'boundary wire');
+    const handle = getOcctKernel().makeFaceOnSurface(fh, wh);
+    return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle });
+}
+/**
+ * 在已有曲面上建面：以宿主面（承载曲面）为底，用曲面上的闭合 wire 圈出新面。
+ * @group 创建
+ * @inputs 2
+ * @async false
+ * @qual ok
+ * @name faceOnSurface
+ * @note 平台 op：仅 occt 引擎（原生 makeFaceOnSurface，L1 契约无对应成员）。
+ *       非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @returns Shape 新建的面。
+ * @param hostFace - 宿主面（承载曲面）。type:Shape required:true
+ * @param wire - 曲面上的闭合边界 wire。type:Shape required:true
+ * @example
+ * const f = cad.faceOnSurface(cylFace, boundaryWire)
+ */
+export const faceOnSurface = defineOp({
+    name: 'faceOnSurface',
+    brep(hostFace, wire) {
+        return faceOnSurfaceBrep(hostFace, wire);
+    },
+    engines: ['occt'],
+    naming: {
+        kind: 'unmodeled',
+        reason: 'face built on a host surface has no source-derived face role vocabulary',
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// nonPlanarFace — 非平面 wire → 面（L1 makeFace 只处理平面）
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 makeNonPlanarFace。 */
+function nonPlanarFaceBrep(wire) {
+    if (!wire) {
+        throw new Error('E_NONPLANARFACE_NO_WIRE: nonPlanarFace requires a boundary wire');
+    }
+    const wh = handleOf(wire, 'nonPlanarFace', 'boundary wire');
+    const handle = getOcctKernel().makeNonPlanarFace(wh);
+    return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle });
+}
+/**
+ * 由非平面闭合 wire 构造面（L1 `makeFace` 只处理平面 wire；本 op 补非平面缺口）。
+ * @group 创建
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name nonPlanarFace
+ * @note 平台 op：仅 occt 引擎（原生 makeNonPlanarFace）。wire 须闭合。
+ * @returns Shape 构造出的面。
+ * @param wire - 闭合边界 wire（可非平面）。type:Shape required:true
+ * @example
+ * const f = cad.nonPlanarFace(curvedBoundaryWire)
+ */
+export const nonPlanarFace = defineOp({
+    name: 'nonPlanarFace',
+    brep(wire) {
+        return nonPlanarFaceBrep(wire);
+    },
+    engines: ['occt'],
+    naming: {
+        kind: 'unmodeled',
+        reason: 'face from arbitrary non-planar wire has no face role vocabulary',
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// makeSolid — 闭合壳 → 实体（方案 §4.2 表列 unmodeled 例）
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 makeSolid。 */
+function makeSolidBrep(shell) {
+    if (!shell) {
+        throw new Error('E_MAKESOLID_NO_SHELL: makeSolid requires a closed shell');
+    }
+    const sh = handleOf(shell, 'makeSolid', 'closed shell');
+    const handle = getOcctKernel().makeSolid(sh);
+    return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle });
+}
+/**
+ * 把已闭合的壳升为实体（输入是壳，不做缝合——缝合链见 `sewAndSolidify`）。
+ * @group 创建
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name makeSolid
+ * @note 平台 op：仅 occt 引擎（原生 makeSolid）。输入须为闭合 shell。
+ * @returns Shape 实体。
+ * @param shell - 已闭合的壳。type:Shape required:true
+ * @example
+ * const s = cad.makeSolid(closedShell)
+ */
+export const makeSolid = defineOp({
+    name: 'makeSolid',
+    brep(shell) {
+        return makeSolidBrep(shell);
+    },
+    engines: ['occt'],
+    naming: {
+        kind: 'unmodeled',
+        reason: 'solid promoted from an arbitrary shell has no face role vocabulary',
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// reverseSurfaceU — 反转面的 U 参数方向
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 reverseSurfaceU。 */
+function reverseSurfaceUBrep(face) {
+    if (!face) {
+        throw new Error('E_REVERSESURFACEU_NO_FACE: reverseSurfaceU requires a face');
+    }
+    const fh = handleOf(face, 'reverseSurfaceU', 'face');
+    const handle = getOcctKernel().reverseSurfaceU(fh);
+    return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle });
+}
+/**
+ * 反转面的 U 参数方向（occt `Geom_Surface::UReverse` 语义）：返回新面代理，
+ * 其曲面是原曲面的 U 反转版（拓扑不变，UV 求值随之镜像）。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name reverseSurfaceU
+ * @note 平台 op：仅 occt 引擎（原生 reverseSurfaceU）。输入面。
+ * @returns Shape U 反转后的面。
+ * @param face - 输入面。type:Shape required:true
+ * @example
+ * const flipped = cad.reverseSurfaceU(f)
+ */
+export const reverseSurfaceU = defineOp({
+    name: 'reverseSurfaceU',
+    brep(face) {
+        return reverseSurfaceUBrep(face);
+    },
+    engines: ['occt'],
+    naming: {
+        kind: 'unmodeled',
+        reason: 'U-reversed face proxy keeps input topology; no new face role vocabulary',
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// outerWire — 取面外环（查询；产物 1D wire）
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 outerWire → 1D wire 经 fromBrepCurve 登记。 */
+function outerWireBrep(face) {
+    if (!face) {
+        throw new Error('E_OUTERWIRE_NO_FACE: outerWire requires a face');
+    }
+    const fh = handleOf(face, 'outerWire', 'face');
+    const handle = getOcctKernel().outerWire(fh);
+    return fromBrepCurve(solidToShape(getBrepApi(), handle), { solid: handle });
+}
+/**
+ * 取面的外环（outer wire）：面上边界中最大的闭合 wire，1D 产物。
+ * @group 查询
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name outerWire
+ * @note 平台 op：仅 occt 引擎（原生 outerWire）。产物 kind='curve'（1D wire）。
+ * @returns Shape 面的外环（kind:'curve'）。
+ * @param face - 输入面。type:Shape required:true
+ * @example
+ * const ow = cad.outerWire(face0)
+ */
+export const outerWire = defineOp({
+    name: 'outerWire',
+    brep(face) {
+        return outerWireBrep(face);
+    },
+    engines: ['occt'],
+    naming: {
+        kind: 'unmodeled',
+        reason: 'extracted sub-wire has no face role vocabulary',
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/api/surface-face/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/surface-face/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api surface-face — 曲面与面构造族（S4，平台 op engines:['occt']）\n *\n * @platform occt — 本目录 import occt-kernel：各 op 直调 occt 原生面/曲面构造与查询\n * 方法（`makeFaceOnSurface` / `makeNonPlanarFace` / `makeSolid` / `reverseSurfaceU` /\n * `outerWire`，occt-wasm 原生有）。这些原生方法**不在** L1 契约 `BrepEngineApi` 里\n * （L1 只有 `makeFace`（仅平面）与 `getSubShapes` 等子集，见 brep/engine/primitives.ts）\n * ⇒ 全族平台 op：defineOp 声明 `engines: ['occt']`（D11）。\n *\n * 方案落点：docs/plans/2026-10-07-occt-wasm-op-enablement-plan.md §3.4.2。\n * 与既有 op 的边界（§4.5 去重表）：\n * - `makeSolid` vs `sewAndSolidify` / `compound`：前者输入是**已闭合的壳**，直接升为\n *   实体；后两者分别走「面 → 缝合 → 固化」链 / 聚合；\n * - `nonPlanarFace` vs L1 `makeFace`：后者只处理平面 wire，前者接受非平面 wire；\n * - `outerWire`（取面外环）vs `offset2d`（偏置）：纯查询 vs 几何构造。\n *\n * 产物形态：面/实体经 `fromBrep` 收养；wire（outerWire 产物）经 `fromBrepCurve`\n * 登记为 `kind:'curve'`（同 offset2d 口径）。\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, fromBrep, fromBrepCurve } from '../../shape'\nimport { defineOp } from '../../sdk'\nimport type { Provenance } from '../../topology/naming/lineage'\nimport { getOcctKernel } from '../../occt-kernel/occtKernel'\n\n/** 输入 Shape → 内核句柄（无 BREP 槁报错）。 */\nfunction handleOf(shape: Shape, op: string, which: 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 for ${which} (mesh-only shape has none)`)\n  }\n  return h\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// faceOnSurface — 在已有面上建面（宿主面 + 曲面上的闭合 wire）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 makeFaceOnSurface。 */\nfunction faceOnSurfaceBrep(hostFace: Shape, wire: Shape): Shape {\n  if (!hostFace || !wire) {\n    throw new Error('E_FACEONSURFACE_MISSING_ARG: faceOnSurface requires a host face and a boundary wire')\n  }\n  const fh = handleOf(hostFace, 'faceOnSurface', 'host face')\n  const wh = handleOf(wire, 'faceOnSurface', 'boundary wire')\n  const handle = getOcctKernel().makeFaceOnSurface(fh as never, wh as never) as unknown as BrepHandle\n  return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle })\n}\n\n/**\n * 在已有曲面上建面：以宿主面（承载曲面）为底，用曲面上的闭合 wire 圈出新面。\n * @group 创建\n * @inputs 2\n * @async false\n * @qual ok\n * @name faceOnSurface\n * @note 平台 op：仅 occt 引擎（原生 makeFaceOnSurface，L1 契约无对应成员）。\n *       非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 新建的面。\n * @param hostFace - 宿主面（承载曲面）。type:Shape required:true\n * @param wire - 曲面上的闭合边界 wire。type:Shape required:true\n * @example\n * const f = cad.faceOnSurface(cylFace, boundaryWire)\n */\nexport const faceOnSurface = defineOp({\n  name: 'faceOnSurface',\n  brep(hostFace: Shape, wire: Shape) {\n    return faceOnSurfaceBrep(hostFace, wire)\n  },\n  engines: ['occt'],\n  naming: {\n    kind: 'unmodeled',\n    reason: 'face built on a host surface has no source-derived face role vocabulary',\n  } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// nonPlanarFace — 非平面 wire → 面（L1 makeFace 只处理平面）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 makeNonPlanarFace。 */\nfunction nonPlanarFaceBrep(wire: Shape): Shape {\n  if (!wire) {\n    throw new Error('E_NONPLANARFACE_NO_WIRE: nonPlanarFace requires a boundary wire')\n  }\n  const wh = handleOf(wire, 'nonPlanarFace', 'boundary wire')\n  const handle = getOcctKernel().makeNonPlanarFace(wh as never) as unknown as BrepHandle\n  return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle })\n}\n\n/**\n * 由非平面闭合 wire 构造面（L1 `makeFace` 只处理平面 wire；本 op 补非平面缺口）。\n * @group 创建\n * @inputs 1\n * @async false\n * @qual ok\n * @name nonPlanarFace\n * @note 平台 op：仅 occt 引擎（原生 makeNonPlanarFace）。wire 须闭合。\n * @returns Shape 构造出的面。\n * @param wire - 闭合边界 wire（可非平面）。type:Shape required:true\n * @example\n * const f = cad.nonPlanarFace(curvedBoundaryWire)\n */\nexport const nonPlanarFace = defineOp({\n  name: 'nonPlanarFace',\n  brep(wire: Shape) {\n    return nonPlanarFaceBrep(wire)\n  },\n  engines: ['occt'],\n  naming: {\n    kind: 'unmodeled',\n    reason: 'face from arbitrary non-planar wire has no face role vocabulary',\n  } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// makeSolid — 闭合壳 → 实体（方案 §4.2 表列 unmodeled 例）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 makeSolid。 */\nfunction makeSolidBrep(shell: Shape): Shape {\n  if (!shell) {\n    throw new Error('E_MAKESOLID_NO_SHELL: makeSolid requires a closed shell')\n  }\n  const sh = handleOf(shell, 'makeSolid', 'closed shell')\n  const handle = getOcctKernel().makeSolid(sh as never) as unknown as BrepHandle\n  return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle })\n}\n\n/**\n * 把已闭合的壳升为实体（输入是壳，不做缝合——缝合链见 `sewAndSolidify`）。\n * @group 创建\n * @inputs 1\n * @async false\n * @qual ok\n * @name makeSolid\n * @note 平台 op：仅 occt 引擎（原生 makeSolid）。输入须为闭合 shell。\n * @returns Shape 实体。\n * @param shell - 已闭合的壳。type:Shape required:true\n * @example\n * const s = cad.makeSolid(closedShell)\n */\nexport const makeSolid = defineOp({\n  name: 'makeSolid',\n  brep(shell: Shape) {\n    return makeSolidBrep(shell)\n  },\n  engines: ['occt'],\n  naming: {\n    kind: 'unmodeled',\n    reason: 'solid promoted from an arbitrary shell has no face role vocabulary',\n  } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// reverseSurfaceU — 反转面的 U 参数方向\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 reverseSurfaceU。 */\nfunction reverseSurfaceUBrep(face: Shape): Shape {\n  if (!face) {\n    throw new Error('E_REVERSESURFACEU_NO_FACE: reverseSurfaceU requires a face')\n  }\n  const fh = handleOf(face, 'reverseSurfaceU', 'face')\n  const handle = getOcctKernel().reverseSurfaceU(fh as never) as unknown as BrepHandle\n  return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle })\n}\n\n/**\n * 反转面的 U 参数方向（occt `Geom_Surface::UReverse` 语义）：返回新面代理，\n * 其曲面是原曲面的 U 反转版（拓扑不变，UV 求值随之镜像）。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name reverseSurfaceU\n * @note 平台 op：仅 occt 引擎（原生 reverseSurfaceU）。输入面。\n * @returns Shape U 反转后的面。\n * @param face - 输入面。type:Shape required:true\n * @example\n * const flipped = cad.reverseSurfaceU(f)\n */\nexport const reverseSurfaceU = defineOp({\n  name: 'reverseSurfaceU',\n  brep(face: Shape) {\n    return reverseSurfaceUBrep(face)\n  },\n  engines: ['occt'],\n  naming: {\n    kind: 'unmodeled',\n    reason: 'U-reversed face proxy keeps input topology; no new face role vocabulary',\n  } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// outerWire — 取面外环（查询；产物 1D wire）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 outerWire → 1D wire 经 fromBrepCurve 登记。 */\nfunction outerWireBrep(face: Shape): Shape {\n  if (!face) {\n    throw new Error('E_OUTERWIRE_NO_FACE: outerWire requires a face')\n  }\n  const fh = handleOf(face, 'outerWire', 'face')\n  const handle = getOcctKernel().outerWire(fh as never) as unknown as BrepHandle\n  return fromBrepCurve(solidToShape(getBrepApi(), handle), { solid: handle })\n}\n\n/**\n * 取面的外环（outer wire）：面上边界中最大的闭合 wire，1D 产物。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name outerWire\n * @note 平台 op：仅 occt 引擎（原生 outerWire）。产物 kind='curve'（1D wire）。\n * @returns Shape 面的外环（kind:'curve'）。\n * @param face - 输入面。type:Shape required:true\n * @example\n * const ow = cad.outerWire(face0)\n */\nexport const outerWire = defineOp({\n  name: 'outerWire',\n  brep(face: Shape) {\n    return outerWireBrep(face)\n  },\n  engines: ['occt'],\n  naming: {\n    kind: 'unmodeled',\n    reason: 'extracted sub-wire has no face role vocabulary',\n  } as Provenance,\n})\n"]}

package/dist/api/surface.d.ts

@@ -0,0 +1,44 @@
+/**
+ * api surface — B 样条曲面（控制点阵 → 面），平台 op engines:['occt']
+ *
+ * @platform occt — 实现走 occt-wasm 原生 `bsplineSurface`（BRepBuilderAPI 网格
+ * 控制点建面；L1 契约无对应成员）⇒ 平台 op：defineOp 声明 `engines: ['occt']`（D11）。
+ * 非 occt 引擎（brepkit）执行前报 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3
+ * 豁免不拦截。
+ *
+ * 用途：点阵（高度采样网格）→ 精确 B 样条面，是 heightmap 链路的落点。产物是
+ * **面**（非实体），沿用 api/profile.ts 的 `fromBrep(solidToShape(...), { solid })`
+ * 形态。
+ *
+ * 与既有 op 的边界：与 `cad.sweep` 的 `surface` 支撑面选项不同——那是扫掠的一个
+ * 选项，本 op 是独立的曲面构造能力。
+ */
+import type { Shape } from '../mesh/types.js';
+/** `cad.surface` 参数。 */
+export interface SurfaceOptions {
+    /** 控制点阵（`rows * cols` 个 `[x, y, z]`，按行优先展开）。 */
+    points: readonly (readonly [number, number, number])[];
+    /** 控制点行数（整数 >= 2）。 */
+    rows: number;
+    /** 控制点列数（整数 >= 2）。 */
+    cols: number;
+}
+/**
+ * 由控制点阵构造 B 样条曲面。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name surface
+ * @note 平台 op：仅 occt 引擎（原生 bsplineSurface）。非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @returns Shape 曲面（面产物，可作 thicken/sweep 的输入）。
+ * @param points - 控制点阵（`rows * cols` 个 `[x, y, z]`，按行优先展开）。type:Vec3[] required:true
+ * @param rows - 控制点行数（整数 >= 2）。type:number required:true
+ * @param cols - 控制点列数（整数 >= 2）。type:number required:true
+ * @example
+ * const s = cad.surface({ points: [[-5,-5,0],[5,-5,0],[-5,5,0],[5,5,0]], rows: 2, cols: 2 })
+ */
+export declare const surface: ((opts: SurfaceOptions) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=surface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/api/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAS1C,wBAAwB;AACxB,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAA;IACtD,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAA;CACb;AA+BD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO;;CAOlB,CAAA"}

package/dist/api/surface.js

@@ -0,0 +1,66 @@
+/**
+ * api surface — B 样条曲面（控制点阵 → 面），平台 op engines:['occt']
+ *
+ * @platform occt — 实现走 occt-wasm 原生 `bsplineSurface`（BRepBuilderAPI 网格
+ * 控制点建面；L1 契约无对应成员）⇒ 平台 op：defineOp 声明 `engines: ['occt']`（D11）。
+ * 非 occt 引擎（brepkit）执行前报 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3
+ * 豁免不拦截。
+ *
+ * 用途：点阵（高度采样网格）→ 精确 B 样条面，是 heightmap 链路的落点。产物是
+ * **面**（非实体），沿用 api/profile.ts 的 `fromBrep(solidToShape(...), { solid })`
+ * 形态。
+ *
+ * 与既有 op 的边界：与 `cad.sweep` 的 `surface` 支撑面选项不同——那是扫掠的一个
+ * 选项，本 op 是独立的曲面构造能力。
+ */
+import { solidToShape } from '../brep/brep-ops.js';
+import { getBrepApi } from '../brep/handle-bridge.js';
+import { fromBrep } from '../shape.js';
+import { defineOp } from '../sdk.js';
+import { getOcctKernel } from '../occt-kernel/occtKernel.js';
+/** BREP 路径：用 occt 原生 bsplineSurface 建面，收养句柄。 */
+function surfaceBrep(opts) {
+    const { points, rows, cols } = opts ?? {};
+    if (!Array.isArray(points) || points.length === 0) {
+        throw new Error('E_SURFACE_NO_POINTS: surface requires a non-empty control-point grid');
+    }
+    if (!Number.isInteger(rows) || !Number.isInteger(cols) || rows < 2 || cols < 2) {
+        throw new Error('E_SURFACE_BAD_SHAPE: surface.rows / surface.cols must be integers >= 2');
+    }
+    if (points.length !== rows * cols) {
+        throw new Error(`E_SURFACE_POINT_COUNT: expected rows*cols = ${rows * cols} control points, got ${points.length}`);
+    }
+    for (const p of points) {
+        if (!Array.isArray(p) || p.length !== 3 || !p.every((v) => typeof v === 'number' && Number.isFinite(v))) {
+            throw new Error('E_SURFACE_BAD_POINT: each control point must be a finite [x, y, z] triple');
+        }
+    }
+    const kernel = getBrepApi();
+    const occt = getOcctKernel();
+    const handle = occt.bsplineSurface(points.map(([x, y, z]) => ({ x, y, z })), rows, cols);
+    return fromBrep(solidToShape(kernel, handle), { solid: handle });
+}
+/**
+ * 由控制点阵构造 B 样条曲面。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name surface
+ * @note 平台 op：仅 occt 引擎（原生 bsplineSurface）。非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @returns Shape 曲面（面产物，可作 thicken/sweep 的输入）。
+ * @param points - 控制点阵（`rows * cols` 个 `[x, y, z]`，按行优先展开）。type:Vec3[] required:true
+ * @param rows - 控制点行数（整数 >= 2）。type:number required:true
+ * @param cols - 控制点列数（整数 >= 2）。type:number required:true
+ * @example
+ * const s = cad.surface({ points: [[-5,-5,0],[5,-5,0],[-5,5,0],[5,5,0]], rows: 2, cols: 2 })
+ */
+export const surface = defineOp({
+    name: 'surface',
+    brep(opts) {
+        return surfaceBrep(opts);
+    },
+    engines: ['occt'],
+    naming: { kind: 'unmodeled', reason: 'bspline-surface face vocabulary not defined' },
+});
+//# sourceMappingURL=surface.js.map

package/dist/api/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../../src/api/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAYzD,gDAAgD;AAChD,SAAS,WAAW,CAAC,IAAoB;IACvC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,IAAK,EAAqB,CAAA;IAC7D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAA;IACzF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QAC/E,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAA;IAC3F,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,GAAG,IAAI,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,+CAA+C,IAAI,GAAG,IAAI,wBAAwB,MAAM,CAAC,MAAM,EAAE,CAClG,CAAA;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACxG,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAA;QAC9F,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAChC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACxC,IAAI,EACJ,IAAI,CACoB,CAAA;IAC1B,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAU,CAAA;AAC3E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;IAC9B,IAAI,EAAE,SAAS;IACf,IAAI,CAAC,IAAoB;QACvB,OAAO,WAAW,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,6CAA6C,EAAgB;CACnG,CAAC,CAAA","sourcesContent":["/**\n * api surface — B 样条曲面（控制点阵 → 面），平台 op engines:['occt']\n *\n * @platform occt — 实现走 occt-wasm 原生 `bsplineSurface`（BRepBuilderAPI 网格\n * 控制点建面；L1 契约无对应成员）⇒ 平台 op：defineOp 声明 `engines: ['occt']`（D11）。\n * 非 occt 引擎（brepkit）执行前报 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3\n * 豁免不拦截。\n *\n * 用途：点阵（高度采样网格）→ 精确 B 样条面，是 heightmap 链路的落点。产物是\n * **面**（非实体），沿用 api/profile.ts 的 `fromBrep(solidToShape(...), { solid })`\n * 形态。\n *\n * 与既有 op 的边界：与 `cad.sweep` 的 `surface` 支撑面选项不同——那是扫掠的一个\n * 选项，本 op 是独立的曲面构造能力。\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 { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\n/** `cad.surface` 参数。 */\nexport interface SurfaceOptions {\n  /** 控制点阵（`rows * cols` 个 `[x, y, z]`，按行优先展开）。 */\n  points: readonly (readonly [number, number, number])[]\n  /** 控制点行数（整数 >= 2）。 */\n  rows: number\n  /** 控制点列数（整数 >= 2）。 */\n  cols: number\n}\n\n/** BREP 路径：用 occt 原生 bsplineSurface 建面，收养句柄。 */\nfunction surfaceBrep(opts: SurfaceOptions): Shape {\n  const { points, rows, cols } = opts ?? ({} as SurfaceOptions)\n  if (!Array.isArray(points) || points.length === 0) {\n    throw new Error('E_SURFACE_NO_POINTS: surface requires a non-empty control-point grid')\n  }\n  if (!Number.isInteger(rows) || !Number.isInteger(cols) || rows < 2 || cols < 2) {\n    throw new Error('E_SURFACE_BAD_SHAPE: surface.rows / surface.cols must be integers >= 2')\n  }\n  if (points.length !== rows * cols) {\n    throw new Error(\n      `E_SURFACE_POINT_COUNT: expected rows*cols = ${rows * cols} control points, got ${points.length}`,\n    )\n  }\n  for (const p of points) {\n    if (!Array.isArray(p) || p.length !== 3 || !p.every((v) => typeof v === 'number' && Number.isFinite(v))) {\n      throw new Error('E_SURFACE_BAD_POINT: each control point must be a finite [x, y, z] triple')\n    }\n  }\n  const kernel = getBrepApi()\n  const occt = getOcctKernel()\n  const handle = occt.bsplineSurface(\n    points.map(([x, y, z]) => ({ x, y, z })),\n    rows,\n    cols,\n  ) as unknown as BrepHandle\n  return fromBrep(solidToShape(kernel, handle), { solid: handle }) as Shape\n}\n\n/**\n * 由控制点阵构造 B 样条曲面。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name surface\n * @note 平台 op：仅 occt 引擎（原生 bsplineSurface）。非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 曲面（面产物，可作 thicken/sweep 的输入）。\n * @param points - 控制点阵（`rows * cols` 个 `[x, y, z]`，按行优先展开）。type:Vec3[] required:true\n * @param rows - 控制点行数（整数 >= 2）。type:number required:true\n * @param cols - 控制点列数（整数 >= 2）。type:number required:true\n * @example\n * const s = cad.surface({ points: [[-5,-5,0],[5,-5,0],[-5,5,0],[5,5,0]], rows: 2, cols: 2 })\n */\nexport const surface = defineOp({\n  name: 'surface',\n  brep(opts: SurfaceOptions) {\n    return surfaceBrep(opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'bspline-surface face vocabulary not defined' } as Provenance,\n})\n"]}

package/dist/api/sweep.d.ts

@@ -1,7 +1,7 @@
 /**
  * api sweep — 扫掠：截面沿脊柱路径生成扫掠体（手写平台 op，Phase 4 → G5 core 直连）
  *
- * @platform occt — 实现走 core 自有 `brep-mirror/sweepFns.ts#sweepBrep`
+ * @platform occt — 实现走 core 自有 `brep-operations/sweepFns.ts#sweepBrep`
  * （occt-wasm simplePipe / sweepPipeShell；engine-method-map 里 `sweep` 为
  * occt-only）⇒ 平台 op：defineOp 声明 `engines: ['occt']`（D11）。
  *
@@ -10,20 +10,75 @@
  * （`internal/profile-wire.ts` 的唯一步径）。脊柱容忍 face（FCStd 翻译把
  * 脊柱基对象 sketch 整圈外廓当路径）。
  *
- * core-decouple G5：vendored `sweep`（brepjs）替换为 brep-mirror 自有实现直连，
+ * core-decouple G5：旧 `sweep`（brepjs）替换为 brep-operations 自有实现直连，
  * 产物经 `fromBrep` 收养（替代 l3-bridge adoptEntity）。
  */
 import type { Shape } from '../mesh/types.js';
-/** 扫掠配置（与 vendored SweepOptions 同形；本文件自持，去 brepjs 依赖）。 */
+/** sweep 的截面朝向模式（映射 occt `SweepMode`）。 */
+export type SweepOrientation = 'fixed' | 'frenet' | 'fixedUp' | 'auxiliary';
+/** sweep 的引导线接触关系（映射 occt `SweepContact`，仅 `orientation:'auxiliary'` 有效）。 */
+export type SweepGuideContact = 'none' | 'contact' | 'contactOnBorder';
+/** sweep 沿脊柱的缩放律（映射 occt `SweepLaw`；`law ≠ 'none'` 时必须给 `lawLength`）。 */
+export type SweepLawKind = 'none' | 'linear' | 'sCurve';
+/**
+ * 扫掠配置。
+ *
+ * 两条路径（S3，方案 §3.4.3「扩 sweep」）：
+ * - **旧路径**（默认）：只给 `frenet` / `mode` / `tolerance` / `transitionMode:'right'` 时，
+ *   走 `sweepPipeShell`（`mode:'simple'` → `simplePipe`），行为与 S3 前逐字节一致；
+ * - **完整控制面**：给出下列任一 sweepFull 字段时改走 occt 原生 `sweepFull`
+ *   （occt-wasm 的 `sweepAdvanced` / `sweepOriented` 是其子集，由同一选项对象承载）。
+ */
 export interface SweepOptions {
-    /** Frenet 参考系（默认 false）。 */
+    /** Frenet 参考系（默认 false）。仅旧路径。 */
     frenet?: boolean;
-    /** 扫掠模式：'simple'（MakePipe）或 undefined（PipeShell）。 */
+    /** 扫掠模式：'simple'（MakePipe）或 undefined（PipeShell）。与 sweepFull 字段互斥。 */
     mode?: 'simple';
-    /** 过渡模式：仅支持默认 'right'（selfhost 后限制，见 sweepFns）。 */
-    transitionMode?: string;
-    /** 公差等其余 vendored 字段（保留以兼容调用方）。 */
+    /**
+     * 转角过渡模式：`'right'`（旧别名，等价于内核缺省 Transformed）或
+     * `'transformed'` / `'rightCorner'` / `'roundCorner'`（后三者走 sweepFull）。
+     */
+    transitionMode?: 'right' | 'transformed' | 'rightCorner' | 'roundCorner';
+    /** 公差等其余旧字段（保留以兼容调用方）。 */
     tolerance?: number;
+    /** 截面朝向模式（默认内核缺省 Fixed）。 */
+    orientation?: SweepOrientation;
+    /** `orientation:'fixedUp'` 的恒定 binormal 方向（默认 +Z）。 */
+    up?: [number, number, number];
+    /** `orientation:'auxiliary'` 的引导线（Shape）。 */
+    auxSpine?: Shape;
+    /** `orientation:'auxiliary'`：按弧长而非参数匹配脊柱与引导线（默认 false）。 */
+    curvilinearEquivalence?: boolean;
+    /** `orientation:'auxiliary'`：截面与引导线的关系（默认 'none'）。 */
+    guideContact?: SweepGuideContact;
+    /**
+     * 扫掠前把截面平移到与 spine 相切（`MakePipeShell::Add` 的 `WithContact`，
+     * 默认 false = 截面停在调用方放置的位置）。
+     */
+    withContact?: boolean;
+    /**
+     * 把截面旋转到与 spine 切线正交（`Add` 的 `WithCorrection`，默认 false）。
+     * 直脊柱上是空操作。
+     */
+    withCorrection?: boolean;
+    /** 支持面（含 spine 的 shape）；给出后取代 `orientation`。 */
+    support?: Shape;
+    /** 逼近面的最大阶数（缺省 = 内核缺省）。 */
+    maxDegree?: number;
+    /** 最大段数（缺省 = 内核缺省）。 */
+    maxSegments?: number;
+    /** 沿脊柱的缩放律（默认 'none'）。 */
+    law?: SweepLawKind;
+    /** law 跨越的参数长度（= 脊柱长度）；`law ≠ 'none'` 时必给。 */
+    lawLength?: number;
+    /** law 末端的截面缩放（1 = 不缩放）。 */
+    lawEndFactor?: number;
+    /** 3D 逼近公差（绝对量，缺省 = 内核缺省 1e-4）。 */
+    tol3d?: number;
+    /** 边界公差（绝对量）。 */
+    boundTol?: number;
+    /** 角度公差（弧度）。 */
+    tolAngular?: number;
 }
 /**
  * 扫掠：截面沿脊柱路径生成扫掠体。
@@ -35,10 +90,17 @@ export interface SweepOptions {
  * @note 平台 op：仅 occt 引擎（BRepOffsetAPI_MakePipeShell / MakePipe）。截面接受
  *       wire 或面（面取其外环）；脊柱必须为 wire。非 occt 引擎执行前报错；
  *       brep_mock 不拦截。`shellMode` 不暴露（元组产物跨不过单产物边界）。
+ *       S3 完整控制面（方案 §3.4.3）：给出 `orientation` / `up` / `auxSpine` /
+ *       `curvilinearEquivalence` / `guideContact` / `transitionMode`（新名）/
+ *       `withContact` / `withCorrection` / `support` / `maxDegree` / `maxSegments` /
+ *       `law` / `lawLength` / `lawEndFactor` / `tol3d` / `boundTol` / `tolAngular`
+ *       任一，即改走 occt 原生 `sweepFull`（law 驱动扫掠是 twist 类特征的正确路径）。
+ *       `sweepFull` 的 options 是 `sweepAdvanced` 的**严格超集**，且含
+ *       `sweepOriented` 的全部字段 ⇒ 三者能力并轨，脚本面只需 `sweep` 一个符号。
  * @returns Shape 扫掠体。
  * @param profile - 截面几何（wire 或面；面取其外环）。type:Shape required:true
  * @param spine - 脊柱路径（wire）。type:Shape required:true
- * @param opts - 扫掠配置（frenet / mode / tolerance 等）。type:SweepOptions required:false
+ * @param opts - 扫掠配置（旧字段 + sweepFull 完整控制面）。type:SweepOptions required:false
  * @example
  * const path = cad.wire([[0, 0, 0], [0, 0, 50]])
  * const section = cad.profile({ contours: [{ segments: [

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

@@ -1 +1 @@
-{"version":3,"file":"sweep.d.ts","sourceRoot":"","sources":["../../src/api/sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAW1C,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,qDAAqD;IACrD,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAyBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,KAAK;;CAOhB,CAAA"}
+{"version":3,"file":"sweep.d.ts","sourceRoot":"","sources":["../../src/api/sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAW1C,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAA;AAC3E,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,iBAAiB,CAAA;AACtE,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,aAAa,GAAG,aAAa,CAAA;IACxE,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAGlB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,sDAAsD;IACtD,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB,2DAA2D;IAC3D,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,sDAAsD;IACtD,YAAY,CAAC,EAAE,iBAAiB,CAAA;IAChC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,gDAAgD;IAChD,OAAO,CAAC,EAAE,KAAK,CAAA;IACf,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0BAA0B;IAC1B,GAAG,CAAC,EAAE,YAAY,CAAA;IAClB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iBAAiB;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gBAAgB;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,KAAK;;CAOhB,CAAA"}