@faicad/faijs 0.33.2 → 0.35.8

package/dist/api/sketch-on-face.js

@@ -4,6 +4,7 @@ import { fromBrep, fromBrepCurve, brepOf } from '../shape.js';
 import { defineOp } from '../sdk.js';
 import { TopoRefError, resolveTopoRef } from '../topology/naming/index.js';
 import { buildEdgeResolutionContext } from './topo-resolve.js';
+import { resolveSelectorToFaceRefs } from './selectors-to-refs.js';
 import { Blueprint } from '../geometry2d/blueprint.js';
 import { CompoundBlueprint } from '../geometry2d/compound-blueprint.js';
 import { organiseBlueprints } from '../geometry2d/organise.js';
@@ -14,10 +15,11 @@ import { assertProfileParams, toContourBlueprints } from './profile.js';
 import { MeshUnsupportedError, BrepUnsupportedError, getCurrentStmt, getBackends } from '../runtime-state.js';
 import { meshBackendOrThrow, meshFacePlane, meshFaceProduct, resolveMeshFaceHandle, } from './internal/mesh-solid-op.js';
 /**
- * Resolve a face on `on` to its live BREP handle (1-based ordinal or `cad.faceRef`).
+ * Resolve a face on `on` to its live BREP handle (1-based ordinal, `cad.faceRef`,
+ * or CadQuery face selector string resolved on `on`).
  * @param kernel - the BREP engine surface.
  * @param on - the target solid shape.
- * @param selector - the face ordinal or `cad.faceRef` result.
+ * @param selector - the face ordinal, `cad.faceRef` result, or selector string.
  * @returns the live face handle.
  */
 export function resolveFaceHandle(kernel, on, selector) {
@@ -32,8 +34,26 @@ export function resolveFaceHandle(kernel, on, selector) {
         }
         return faces[selector - 1];
     }
+    if (typeof selector === 'string') {
+        // CadQuery 面选择器字符串（精度链）：在 `on` 上解析为单个宿主面。
+        const refs = resolveSelectorToFaceRefs(on, selector);
+        if (refs.length === 0) {
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `sketchOnFace: selector "${selector}" matched no face on target`);
+        }
+        if (refs.length > 1) {
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `sketchOnFace: selector "${selector}" matched ${refs.length} faces; the host face must be unique`);
+        }
+        const ctx = buildEdgeResolutionContext(kernel, on);
+        if (!ctx)
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: input has no naming context');
+        const resolved = resolveTopoRef(refs[0], ctx);
+        if (resolved.handle === undefined) {
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: selector-resolved face ref resolved to no live handle');
+        }
+        return resolved.handle;
+    }
     if (selector.kind !== 'face') {
-        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: selector must be a face ordinal or a face ref');
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: selector must be a face ordinal, a selector string, or a face ref');
     }
     const ctx = buildEdgeResolutionContext(kernel, on);
     if (!ctx)
@@ -188,6 +208,10 @@ export function buildSketchOnFaceMesh(params) {
         throw new MeshUnsupportedError(`E_MESH_SOLID_UNSUPPORTED: ${opLabel} as:'wire' has no mesh-chain representation — ` +
             'a mesh-chain wire has no identity slot; ask for the default as:\'face\' instead', getCurrentStmt());
     }
+    // 选择器字符串只服务精度链（网格零件无 role 层）；网格链用 1 起序号。
+    if (typeof params.face === 'string') {
+        throw new TopoRefError('E_TOPO_MESH_UNSUPPORTED', 'face', `sketchOnFace: selector strings are precision-chain only — mesh solids have no role layer (use 1-based face ordinals)`);
+    }
     const host = resolveMeshFaceHandle(kernel, params.on, params.face, opLabel);
     const surface = kernel.surfaceType(host);
     if (surface !== 'plane') {
@@ -227,9 +251,12 @@ export function buildSketchOnFaceMesh(params) {
  * @returns Shape on the target face (face, or a wire curve when `as:'wire'`).
  * @param params.contours - ordered 2D closed contours (same shape as `cad.profile`).type:any[] required:true
  * @param params.on - the target solid on which the face lives.type:Shape required:true
- * @param params.face - the host face: a 1-based ordinal or a `cad.faceRef(on, n)` result.type:any required:true
+ * @param params.face - the host face: FaceTopoRef（UI 拾取产物字面量）| 面选择器字符串（如 ">Z"，在 on 上解析，多面命中抛错）| 1 起序号（仅网格链/当前内核快照，禁止用于生成脚本）。type:any required:true
  * @param params.scaleMode - UV mapping: 'original' (identity) | 'bounds'/'native' (affine-fit; OCCT planar only).type:string required:false
  * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false
+ * @example
+ * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }
+ * const face = cad.sketchOnFace({ contours: [loop], on: cad.box(20, 20, 10), face: '>Z' })
  */
 export const sketchOnFace = defineOp({
     meshEngines: ['brepkit'],

package/dist/api/sketch-on-face.js.map

@@ -1 +1 @@
-{"version":3,"file":"sketch-on-face.js","sourceRoot":"","sources":["../../src/api/sketch-on-face.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `cad.sketchOnFace`: place 2D contours onto a **planar** face of an existing\n * solid (E3 placement), engine-neutral.\n *\n * 2026-10-09 split: `sketchOnFace` now owns the *planar* case only and carries\n * **no `engines` declaration** — it is a common op, available on the OCCT BREP\n * engine, the brepkit BREP engine, and the brepkit mesh backend. The\n * curved / UV-conform capability (map into the face's `(u,v)` domain + snap to\n * the surface via `fixWireOnFace`, which needs OCCT) moved to\n * `cad.sketchOnSurface` (`engines: ['occt']`).\n *\n * For a planar face the contour is laid on the face's own plane frame via\n * `assembleWireOnFace` (identity `original` scale mode, or `bounds`/`native`\n * where the engine exposes a finite UV domain) and wrapped as a face with\n * `makeFace` — exact, no surface snapping needed. Non-planar faces are refused\n * up front with a pointer to `cad.sketchOnSurface`.\n *\n * **Two chains, two mechanisms** (plan 2026-10-01 §4 Phase 3). The BREP branch\n * above maps the contour onto the host face's plane. The **mesh branch**\n * (`buildSketchOnFaceMesh`, `meshEngines: ['brepkit']`) works on a mesh solid's\n * approximate topology and deliberately does NOT use a UV domain: a brepkit\n * plane's domain is ±1e6 (an infinite domain), so \"place the sketch in the face's\n * UV range\" is meaningless there. It places the contour in the face's own plane\n * frame instead (origin = face bbox centre, normal = `surfaceNormal`), which\n * matches `cad.sketchOnPlane`'s semantics. The result is a **mesh-chain face**\n * (`ShapeSlot.meshFace`), ready for the mesh branch of `cad.extrude`.\n *\n * For both chains a planar face is required; curved faces are rejected by the\n * BREP branch (→ `cad.sketchOnSurface`) and by the mesh branch (→\n * `E_MESH_SOLID_UNSUPPORTED`).\n * @module\n */\nimport type { Shape } from '../mesh/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { solidToShape } from '../brep/brep-ops'\nimport { fromBrep, fromBrepCurve, brepOf } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { TopoRefError, resolveTopoRef, type FaceTopoRef } from '../topology/naming'\nimport { buildEdgeResolutionContext } from './topo-resolve'\nimport { Blueprint } from '../geometry2d/blueprint'\nimport { CompoundBlueprint } from '../geometry2d/compound-blueprint'\nimport { organiseBlueprints } from '../geometry2d/organise'\nimport { assembleWireOnFace, type FaceScaleMode } from '../geometry2d/bridge/on-surface'\nimport { assembleWire, type Plane, type Vec3 } from '../geometry2d/bridge/lift-on-plane'\nimport { profileSegToCurve, type ProfileSegLike } from '../geometry2d/adapt'\nimport { assertProfileParams, toContourBlueprints, type ProfileLoop } from './profile'\nimport { MeshUnsupportedError, BrepUnsupportedError, getCurrentStmt, getBackends } from '../runtime-state'\nimport {\n  meshBackendOrThrow,\n  meshFacePlane,\n  meshFaceProduct,\n  resolveMeshFaceHandle,\n} from './internal/mesh-solid-op'\n\n/** A face selector on a target solid: a 1-based ordinal (FreeCAD `FaceN`) or a `cad.faceRef` result. */\nexport type FaceSelector = number | FaceTopoRef\n\n/** Contour loops + the target face for `cad.sketchOnFace`. */\nexport interface SketchOnFaceParams {\n  /** Ordered 2D closed contours (same shape as `cad.profile` / `cad.sketchOnPlane`). */\n  contours: ProfileLoop[]\n  /** The target solid on which the host face lives. */\n  on: Shape\n  /** The host face: a 1-based face ordinal, or a `cad.faceRef(on, n)` result. */\n  face: FaceSelector\n  /** How 2D coords map onto the face UV space: `'original'` (identity) | `'bounds'`/`'native'` (affine-fit). */\n  scaleMode?: FaceScaleMode\n  /** Result shape: `'face'` (default) builds a face on the contour; `'wire'` returns the outer-loop wire only. */\n  as?: 'face' | 'wire'\n}\n\n/**\n * Resolve a face on `on` to its live BREP handle (1-based ordinal or `cad.faceRef`).\n * @param kernel - the BREP engine surface.\n * @param on - the target solid shape.\n * @param selector - the face ordinal or `cad.faceRef` result.\n * @returns the live face handle.\n */\nexport function resolveFaceHandle(kernel: BrepEngineApi, on: Shape, selector: FaceSelector): BrepHandle {\n  const solid = brepOf(on) as BrepHandle | undefined\n  if (solid === undefined) {\n    throw new TopoRefError('E_TOPO_MESH_UNSUPPORTED', 'face', 'sketchOnFace: target `on` has no BREP solid')\n  }\n  if (typeof selector === 'number') {\n    const faces = kernel.getSubShapes(solid, 'face')\n    if (!Number.isInteger(selector) || selector < 1 || selector > faces.length) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `sketchOnFace: face ordinal ${selector} out of range [1, ${faces.length}]`,\n      )\n    }\n    return faces[selector - 1] as BrepHandle\n  }\n  if (selector.kind !== 'face') {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: selector must be a face ordinal or a face ref')\n  }\n  const ctx = buildEdgeResolutionContext(kernel, on as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: input has no naming context')\n  const resolved = resolveTopoRef(selector, ctx)\n  if (resolved.handle === undefined) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: face ref resolved to no live handle')\n  }\n  return resolved.handle as BrepHandle\n}\n\n/**\n * Make the placed face inherit the host face's outward orientation: surface\n * normals must point the same way, otherwise the resulting face — and any prism\n * extruded from it — carries a reversed shell whose OCCT volume collapses to ~0.\n * @param kernel - the BREP engine surface.\n * @param host - the host face handle (its normal is the reference).\n * @param face - the face built on the host surface.\n * @returns a handle to the (possibly re-oriented) face.\n */\nexport function orientLikeHost(kernel: BrepEngineApi, host: BrepHandle, face: BrepHandle): BrepHandle {\n  const a = kernel.surfaceNormal(host, 0, 0)\n  const b = kernel.surfaceNormal(face, 0, 0)\n  const dot = a.x * b.x + a.y * b.y + a.z * b.z\n  return dot < 0 ? kernel.reverseShape(face) : face\n}\n\n/**\n * Build one planar face (outer + optional holes) on the host **planar** face for\n * an organised contour entry. No surface snapping (`fixWireOnFace`) is needed:\n * the wire from `assembleWireOnFace` already lies in the face's plane, so\n * `makeFace` is exact.\n * @param kernel - the BREP engine surface.\n * @param host - the resolved live host face handle.\n * @param mode - the face-scale mode (`original` everywhere; `bounds`/`native` only where the engine exposes a finite UV domain).\n * @param entry - the organised contour entry (outer + optional holes).\n * @returns the built face handle.\n */\nfunction buildPlanarFaceOnHost(\n  kernel: BrepEngineApi,\n  host: BrepHandle,\n  mode: FaceScaleMode,\n  entry: Blueprint | CompoundBlueprint,\n): BrepHandle {\n  const outerBp = entry instanceof CompoundBlueprint ? entry.blueprints[0]! : entry\n  const outerWire = assembleWireOnFace(kernel, host, mode, outerBp).wire\n  let face = orientLikeHost(kernel, host, kernel.makeFace(outerWire))\n  if (entry instanceof CompoundBlueprint) {\n    const holes = entry.blueprints.slice(1).map((h) => assembleWireOnFace(kernel, host, mode, h).wire as never)\n    if (holes.length > 0) face = kernel.addHolesInFace(face, holes)\n  }\n  return face\n}\n\n/**\n * Build a 3D Shape from closed contours placed on the host **planar** face.\n * @param kernel - the BREP engine surface.\n * @param params - contour loops + target solid + face + scale mode.\n * @returns Shape on the target face (face, or the outer wire when `as:'wire'`).\n * @throws {BrepUnsupportedError} when the host face is not planar (use `cad.sketchOnSurface`).\n */\nexport function buildSketchOnFaceWith(kernel: BrepEngineApi, params: SketchOnFaceParams): Shape {\n  const host = resolveFaceHandle(kernel, params.on, params.face)\n  const mode = params.scaleMode ?? 'original'\n\n  // Planar-only gate: the curved / UV-conform capability moved to `cad.sketchOnSurface`.\n  const surface = kernel.surfaceType(host)\n  if (surface !== 'plane') {\n    throw new BrepUnsupportedError(\n      `E_BREP_UNSUPPORTED: cad.sketchOnFace only supports planar faces (got surfaceType '${surface}'). ` +\n      'Use cad.sketchOnSurface for curved/UV-conform placement.',\n      getCurrentStmt(),\n    )\n  }\n  // brepkit planar faces expose an infinite (±1e6) UV domain, so only the\n  // identity 'original' scale mode is meaningful there (mirrors the mesh branch\n  // restriction); OCCT planar faces keep full scaleMode support.\n  const engineId = getBackends().config.brepEngineId\n  if (engineId === 'brepkit' && mode !== 'original') {\n    throw new BrepUnsupportedError(\n      `E_BREP_UNSUPPORTED: cad.sketchOnFace on a brepkit planar face only supports scaleMode 'original' ` +\n      \"(brepkit planar faces have no finite UV domain) — use the default 'original'.\",\n      getCurrentStmt(),\n    )\n  }\n\n  const blueprints = params.contours.map(\n    (loop) => new Blueprint(loop.segments.map((s) => profileSegToCurve(s as ProfileSegLike))),\n  )\n  const organised = organiseBlueprints(blueprints)\n\n  if (params.as === 'wire') {\n    const outer =\n      organised.blueprints[0] instanceof CompoundBlueprint\n        ? organised.blueprints[0].blueprints[0]!\n        : (organised.blueprints[0] as Blueprint)\n    const { wire } = assembleWireOnFace(kernel, host, mode, outer)\n    return fromBrepCurve(solidToShape(kernel, wire), { solid: wire })\n  }\n\n  const faces = organised.blueprints.map((entry) => buildPlanarFaceOnHost(kernel, host, mode, entry))\n  if (faces.length === 0) throw new Error('sketchOnFace: no contours to place')\n  if (faces.length === 1) {\n    const f = faces[0]!\n    return fromBrep(solidToShape(kernel, f), { solid: f })\n  }\n  const compound = kernel.makeCompound(faces)\n  return fromBrep(solidToShape(kernel, compound), { solid: compound })\n}\n\n/**\n * 把一张平面的法向对齐到参考方向（外部朝向）。网格链上的复制版：BREP 侧的\n * `orientLikeHost` 存在的原因是\"面朝向反了 → 由它拉出的棱柱壳反向 → 体积归零\"，\n * 这里同一个道理，只是参考法向来自**平面本身**（`meshFacePlane` 的法向就是从宿主面\n * 的 `surfaceNormal` 取的），不必再回读宿主句柄。\n *\n * @param kernel - the mesh backend's L1 kernel.\n * @param reference - the outward normal the placed face must agree with.\n * @param face - the face built on the plane.\n * @returns a handle to the (possibly re-oriented) face.\n */\nfunction orientFaceTo(kernel: BrepEngineApi, reference: Vec3, face: BrepHandle): BrepHandle {\n  const uv = kernel.uvBounds(face)\n  const n = kernel.surfaceNormal(face, (uv.uMin + uv.uMax) / 2, (uv.vMin + uv.vMax) / 2)\n  const dot = reference.x * n.x + reference.y * n.y + reference.z * n.z\n  return dot < 0 ? kernel.reverseShape(face) : face\n}\n\n/** 一个已归类的轮廓条目（外环 + 可选孔）在平面坐标系里造一张面。 */\nfunction buildFaceOnPlane(\n  kernel: BrepEngineApi,\n  plane: Plane,\n  outward: Vec3,\n  entry: Blueprint | CompoundBlueprint,\n): BrepHandle {\n  const outerBp = entry instanceof CompoundBlueprint ? entry.blueprints[0]! : entry\n  let face = orientFaceTo(kernel, outward, kernel.makeFace(assembleWire(kernel, plane, outerBp)))\n  if (entry instanceof CompoundBlueprint) {\n    const holes = entry.blueprints.slice(1).map((h) => assembleWire(kernel, plane, h) as never)\n    if (holes.length > 0) face = kernel.addHolesInFace(face, holes)\n  }\n  return face\n}\n\n/**\n * 网格链上的 `cad.sketchOnFace`：在**识别出的平面网格面**上铺 2D 轮廓，产出网格链面\n * （方案 2026-10-01 §4 Phase 3-2），可交给 `cad.extrude` 的网格路径拉伸出新实体。\n *\n * 与 BREP 侧的三点差别，每一点都是\"近似拓扑没有 UV 语义\"的直接后果：\n *\n * 1. **不走 UV 域**。BREP 侧 `assembleWireOnFace` 把 2D 采样点映射进面的 `(u,v)` 域；\n *    而平面在 brepkit 上的域是 ±1e6 的**无限域**（方案 §4 Phase 3-1 实测），拿它当\n *    草图范围毫无意义。这里改用面自己的平面框（原点 = 面包围盒中心、法向 = 面法向），\n *    2D 坐标直接落在平面坐标系里——与 `cad.sketchOnPlane` 的语义一致。\n * 2. **`scaleMode` 只接受 `'original'`**。`'bounds'` / `'native'` 的定义是\"拟合到面的\n *    UV 域\"，而那个域在这里要么是无限域、要么不存在。静默按 `'original'` 处理会造成\n *    \"同一次调用在两条链上得到不同尺寸\"的隐性分歧，所以如实拒绝。\n * 3. **`as:'wire'` 不支持**。网格链上的一根 wire 没有身份槽（面才有），而 sketch 的\n *    下游用途（拉伸）要的正是面。需要 wire 的场景请走 BREP 链。\n *\n * 另外只支持**平面面**：曲面面（STL 圆柱的侧面片）上铺草图需要曲面嵌入，属未开的能力。\n *\n * @param params - contour loops + target mesh solid + face selector + scale mode.\n * @returns the mesh-chain face Shape on the target face.\n * @throws {MeshUnsupportedError} when the target is not a mesh solid, the face is not planar,\n *   the scale mode is not `'original'`, `as:'wire'` was requested, or the sketch is multi-island.\n */\nexport function buildSketchOnFaceMesh(params: SketchOnFaceParams): Shape {\n  const opLabel = 'sketchOnFace'\n  const backend = meshBackendOrThrow(opLabel)\n  const kernel = backend.kernel\n\n  const mode = params.scaleMode ?? 'original'\n  if (mode !== 'original') {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} scaleMode '${mode}' is defined against the face's UV domain, ` +\n      'which a mesh-chain face does not have — use the default \\'original\\' (2D coords live in the face plane)',\n      getCurrentStmt(),\n    )\n  }\n  if (params.as === 'wire') {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} as:'wire' has no mesh-chain representation — ` +\n      'a mesh-chain wire has no identity slot; ask for the default as:\\'face\\' instead',\n      getCurrentStmt(),\n    )\n  }\n\n  const host = resolveMeshFaceHandle(kernel, params.on, params.face, opLabel)\n  const surface = kernel.surfaceType(host)\n  if (surface !== 'plane') {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} needs a planar mesh face to sketch on — this face reports ` +\n      `surfaceType '${surface}'. Sketches on curved approximate faces are not implemented ` +\n      '(an STL cylinder is 32 planar strips, each of which IS usable)',\n      getCurrentStmt(),\n    )\n  }\n\n  const plane = meshFacePlane(kernel, host)\n  const outward: Vec3 = { x: plane.zDir.x, y: plane.zDir.y, z: plane.zDir.z }\n\n  const organised = organiseBlueprints(toContourBlueprints(params.contours))\n  if (organised.blueprints.length === 0) throw new Error('sketchOnFace: no contours to place')\n  if (organised.blueprints.length > 1) {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} produced ${organised.blueprints.length} disjoint islands — ` +\n      'the mesh backend can only extrude a single face (brepkit extrude takes one face, not a compound). ' +\n      'Sketch and extrude each island separately, then unite them with a boolean',\n      getCurrentStmt(),\n    )\n  }\n\n  const face = buildFaceOnPlane(kernel, plane, outward, organised.blueprints[0]!)\n  return meshFaceProduct(backend, face)\n}\n\n/**\n * `cad.sketchOnFace`: place 2D contours on a **planar** face of a solid and\n * construct a Shape. Engine-neutral (no `engines` declaration): works on the\n * OCCT BREP engine, the brepkit BREP engine, and the brepkit mesh backend.\n *\n * **网格链**（`meshEngines: ['brepkit']`，方案 2026-10-01 §4 Phase 3）：`on` 是网格实体\n * 时，轮廓按面自己的**平面框**铺放（原点 = 面包围盒中心、法向 = 面法向），产物是一张\n * 网格链面，可直接交给 `cad.extrude` 拉伸。该分支只接受平面面、只接受默认\n * `scaleMode`（`'bounds'`/`'native'` 相对 UV 域定义，网格链上没有 UV 域）、只接受\n * `as:'face'`、且只接受单个轮廓岛——每一条越界都以 `E_MESH_SOLID_UNSUPPORTED` 说明原因。\n *\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sketchOnFace\n * @returns Shape on the target face (face, or a wire curve when `as:'wire'`).\n * @param params.contours - ordered 2D closed contours (same shape as `cad.profile`).type:any[] required:true\n * @param params.on - the target solid on which the face lives.type:Shape required:true\n * @param params.face - the host face: a 1-based ordinal or a `cad.faceRef(on, n)` result.type:any required:true\n * @param params.scaleMode - UV mapping: 'original' (identity) | 'bounds'/'native' (affine-fit; OCCT planar only).type:string required:false\n * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false\n */\nexport const sketchOnFace = defineOp({\n  meshEngines: ['brepkit'],\n  mesh(params: Record<string, unknown>) {\n    assertProfileParams(params)\n    return buildSketchOnFaceMesh(params as unknown as SketchOnFaceParams)\n  },\n  brep(params: Record<string, unknown>) {\n    assertProfileParams(params)\n    return buildSketchOnFaceWith(getBrepApi(), params as unknown as SketchOnFaceParams)\n  },\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [] } } as Provenance,\n\n  paramDims: {},\n})\n"]}
+{"version":3,"file":"sketch-on-face.js","sourceRoot":"","sources":["../../src/api/sketch-on-face.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAoB,MAAM,oBAAoB,CAAA;AACnF,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAsB,MAAM,iCAAiC,CAAA;AACxF,OAAO,EAAE,YAAY,EAAyB,MAAM,oCAAoC,CAAA;AACxF,OAAO,EAAE,iBAAiB,EAAuB,MAAM,qBAAqB,CAAA;AAC5E,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAoB,MAAM,WAAW,CAAA;AACtF,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC1G,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,qBAAqB,GACtB,MAAM,0BAA0B,CAAA;AAqBjC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAqB,EAAE,EAAS,EAAE,QAAsB;IACxF,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAA2B,CAAA;IAClD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,YAAY,CAAC,yBAAyB,EAAE,MAAM,EAAE,6CAA6C,CAAC,CAAA;IAC1G,CAAC;IACD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC3E,MAAM,IAAI,YAAY,CACpB,kBAAkB,EAClB,MAAM,EACN,8BAA8B,QAAQ,qBAAqB,KAAK,CAAC,MAAM,GAAG,CAC3E,CAAA;QACH,CAAC;QACD,OAAO,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAe,CAAA;IAC1C,CAAC;IACD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,0CAA0C;QAC1C,MAAM,IAAI,GAAG,yBAAyB,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;QACpD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,2BAA2B,QAAQ,6BAA6B,CAAC,CAAA;QACtH,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,YAAY,CACpB,kBAAkB,EAClB,MAAM,EACN,2BAA2B,QAAQ,aAAa,IAAI,CAAC,MAAM,sCAAsC,CAClG,CAAA;QACH,CAAC;QACD,MAAM,GAAG,GAAG,0BAA0B,CAAC,MAAM,EAAE,EAAY,CAAC,CAAA;QAC5D,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,2CAA2C,CAAC,CAAA;QACzG,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAE,EAAE,GAAG,CAAC,CAAA;QAC9C,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,qEAAqE,CAAC,CAAA;QAC3H,CAAC;QACD,OAAO,QAAQ,CAAC,MAAoB,CAAA;IACtC,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,iFAAiF,CAAC,CAAA;IACvI,CAAC;IACD,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;IACzG,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;IAC9C,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,mDAAmD,CAAC,CAAA;IACzG,CAAC;IACD,OAAO,QAAQ,CAAC,MAAoB,CAAA;AACtC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB,EAAE,IAAgB,EAAE,IAAgB;IACtF,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAC1C,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IAC7C,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACnD,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,qBAAqB,CAC5B,MAAqB,EACrB,IAAgB,EAChB,IAAmB,EACnB,KAAoC;IAEpC,MAAM,OAAO,GAAG,KAAK,YAAY,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,KAAK,CAAA;IACjF,MAAM,SAAS,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,CAAA;IACtE,IAAI,IAAI,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAA;IACnE,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAa,CAAC,CAAA;QAC3G,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,IAAI,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACjE,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAqB,EAAE,MAA0B;IACrF,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,IAAI,UAAU,CAAA;IAE3C,uFAAuF;IACvF,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;IACxC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAC5B,qFAAqF,OAAO,MAAM;YAClG,0DAA0D,EAC1D,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IACD,wEAAwE;IACxE,8EAA8E;IAC9E,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,YAAY,CAAA;IAClD,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QAClD,MAAM,IAAI,oBAAoB,CAC5B,mGAAmG;YACnG,+EAA+E,EAC/E,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CACpC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,CAAmB,CAAC,CAAC,CAAC,CAC1F,CAAA;IACD,MAAM,SAAS,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAA;IAEhD,IAAI,MAAM,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;QACzB,MAAM,KAAK,GACT,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,iBAAiB;YAClD,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAE;YACxC,CAAC,CAAE,SAAS,CAAC,UAAU,CAAC,CAAC,CAAe,CAAA;QAC5C,MAAM,EAAE,IAAI,EAAE,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;QAC9D,OAAO,aAAa,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,qBAAqB,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;IACnG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IAC7E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAA;QACnB,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA;IACxD,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;IAC3C,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;AACtE,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,YAAY,CAAC,MAAqB,EAAE,SAAe,EAAE,IAAgB;IAC5E,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAChC,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;IACtF,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACrE,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACnD,CAAC;AAED,uCAAuC;AACvC,SAAS,gBAAgB,CACvB,MAAqB,EACrB,KAAY,EACZ,OAAa,EACb,KAAoC;IAEpC,MAAM,OAAO,GAAG,KAAK,YAAY,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,KAAK,CAAA;IACjF,IAAI,IAAI,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IAC/F,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAU,CAAC,CAAA;QAC3F,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,IAAI,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACjE,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA0B;IAC9D,MAAM,OAAO,GAAG,cAAc,CAAA;IAC9B,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IAE7B,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,IAAI,UAAU,CAAA;IAC3C,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,eAAe,IAAI,6CAA6C;YACpG,yGAAyG,EACzG,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IACD,IAAI,MAAM,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,gDAAgD;YACpF,iFAAiF,EACjF,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IACD,yCAAyC;IACzC,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,YAAY,CACpB,yBAAyB,EACzB,MAAM,EACN,sHAAsH,CACvH,CAAA;IACH,CAAC;IAED,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAC3E,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;IACxC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,6DAA6D;YACjG,gBAAgB,OAAO,8DAA8D;YACrF,gEAAgE,EAChE,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IAED,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACzC,MAAM,OAAO,GAAS,EAAE,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAA;IAE3E,MAAM,SAAS,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC1E,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IAC5F,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,oBAAoB,CAC5B,6BAA6B,OAAO,aAAa,SAAS,CAAC,UAAU,CAAC,MAAM,sBAAsB;YAClG,oGAAoG;YACpG,2EAA2E,EAC3E,cAAc,EAAE,CACjB,CAAA;IACH,CAAC;IAED,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,CAAE,CAAC,CAAA;IAC/E,OAAO,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC;IACnC,WAAW,EAAE,CAAC,SAAS,CAAC;IACxB,IAAI,CAAC,MAA+B;QAClC,mBAAmB,CAAC,MAAM,CAAC,CAAA;QAC3B,OAAO,qBAAqB,CAAC,MAAuC,CAAC,CAAA;IACvE,CAAC;IACD,IAAI,CAAC,MAA+B;QAClC,mBAAmB,CAAC,MAAM,CAAC,CAAA;QAC3B,OAAO,qBAAqB,CAAC,UAAU,EAAE,EAAE,MAAuC,CAAC,CAAA;IACrF,CAAC;IACD,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE,EAAgB;IAErF,SAAS,EAAE,EAAE;CACd,CAAC,CAAA","sourcesContent":["/**\n * `cad.sketchOnFace`: place 2D contours onto a **planar** face of an existing\n * solid (E3 placement), engine-neutral.\n *\n * 2026-10-09 split: `sketchOnFace` now owns the *planar* case only and carries\n * **no `engines` declaration** — it is a common op, available on the OCCT BREP\n * engine, the brepkit BREP engine, and the brepkit mesh backend. The\n * curved / UV-conform capability (map into the face's `(u,v)` domain + snap to\n * the surface via `fixWireOnFace`, which needs OCCT) moved to\n * `cad.sketchOnSurface` (`engines: ['occt']`).\n *\n * For a planar face the contour is laid on the face's own plane frame via\n * `assembleWireOnFace` (identity `original` scale mode, or `bounds`/`native`\n * where the engine exposes a finite UV domain) and wrapped as a face with\n * `makeFace` — exact, no surface snapping needed. Non-planar faces are refused\n * up front with a pointer to `cad.sketchOnSurface`.\n *\n * **Two chains, two mechanisms** (plan 2026-10-01 §4 Phase 3). The BREP branch\n * above maps the contour onto the host face's plane. The **mesh branch**\n * (`buildSketchOnFaceMesh`, `meshEngines: ['brepkit']`) works on a mesh solid's\n * approximate topology and deliberately does NOT use a UV domain: a brepkit\n * plane's domain is ±1e6 (an infinite domain), so \"place the sketch in the face's\n * UV range\" is meaningless there. It places the contour in the face's own plane\n * frame instead (origin = face bbox centre, normal = `surfaceNormal`), which\n * matches `cad.sketchOnPlane`'s semantics. The result is a **mesh-chain face**\n * (`ShapeSlot.meshFace`), ready for the mesh branch of `cad.extrude`.\n *\n * For both chains a planar face is required; curved faces are rejected by the\n * BREP branch (→ `cad.sketchOnSurface`) and by the mesh branch (→\n * `E_MESH_SOLID_UNSUPPORTED`).\n * @module\n */\nimport type { Shape } from '../mesh/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { solidToShape } from '../brep/brep-ops'\nimport { fromBrep, fromBrepCurve, brepOf } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { TopoRefError, resolveTopoRef, type FaceTopoRef } from '../topology/naming'\nimport { buildEdgeResolutionContext } from './topo-resolve'\nimport { resolveSelectorToFaceRefs } from './selectors-to-refs'\nimport { Blueprint } from '../geometry2d/blueprint'\nimport { CompoundBlueprint } from '../geometry2d/compound-blueprint'\nimport { organiseBlueprints } from '../geometry2d/organise'\nimport { assembleWireOnFace, type FaceScaleMode } from '../geometry2d/bridge/on-surface'\nimport { assembleWire, type Plane, type Vec3 } from '../geometry2d/bridge/lift-on-plane'\nimport { profileSegToCurve, type ProfileSegLike } from '../geometry2d/adapt'\nimport { assertProfileParams, toContourBlueprints, type ProfileLoop } from './profile'\nimport { MeshUnsupportedError, BrepUnsupportedError, getCurrentStmt, getBackends } from '../runtime-state'\nimport {\n  meshBackendOrThrow,\n  meshFacePlane,\n  meshFaceProduct,\n  resolveMeshFaceHandle,\n} from './internal/mesh-solid-op'\n\n/** A face selector on a target solid: a 1-based ordinal (FreeCAD `FaceN`, mesh chain /\n * current kernel snapshot only), a `cad.faceRef` result, or a CadQuery face selector\n * string (e.g. `\">Z\"` — precision chain, resolved on `on`). */\nexport type FaceSelector = number | FaceTopoRef | string\n\n/** Contour loops + the target face for `cad.sketchOnFace`. */\nexport interface SketchOnFaceParams {\n  /** Ordered 2D closed contours (same shape as `cad.profile` / `cad.sketchOnPlane`). */\n  contours: ProfileLoop[]\n  /** The target solid on which the host face lives. */\n  on: Shape\n  /** The host face: a FaceTopoRef (UI-picked literal), a CadQuery face selector string (e.g. \">Z\", resolved on `on`), or a 1-based face ordinal (mesh chain / current kernel snapshot only). */\n  face: FaceSelector\n  /** How 2D coords map onto the face UV space: `'original'` (identity) | `'bounds'`/`'native'` (affine-fit). */\n  scaleMode?: FaceScaleMode\n  /** Result shape: `'face'` (default) builds a face on the contour; `'wire'` returns the outer-loop wire only. */\n  as?: 'face' | 'wire'\n}\n\n/**\n * Resolve a face on `on` to its live BREP handle (1-based ordinal, `cad.faceRef`,\n * or CadQuery face selector string resolved on `on`).\n * @param kernel - the BREP engine surface.\n * @param on - the target solid shape.\n * @param selector - the face ordinal, `cad.faceRef` result, or selector string.\n * @returns the live face handle.\n */\nexport function resolveFaceHandle(kernel: BrepEngineApi, on: Shape, selector: FaceSelector): BrepHandle {\n  const solid = brepOf(on) as BrepHandle | undefined\n  if (solid === undefined) {\n    throw new TopoRefError('E_TOPO_MESH_UNSUPPORTED', 'face', 'sketchOnFace: target `on` has no BREP solid')\n  }\n  if (typeof selector === 'number') {\n    const faces = kernel.getSubShapes(solid, 'face')\n    if (!Number.isInteger(selector) || selector < 1 || selector > faces.length) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `sketchOnFace: face ordinal ${selector} out of range [1, ${faces.length}]`,\n      )\n    }\n    return faces[selector - 1] as BrepHandle\n  }\n  if (typeof selector === 'string') {\n    // CadQuery 面选择器字符串（精度链）：在 `on` 上解析为单个宿主面。\n    const refs = resolveSelectorToFaceRefs(on, selector)\n    if (refs.length === 0) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `sketchOnFace: selector \"${selector}\" matched no face on target`)\n    }\n    if (refs.length > 1) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `sketchOnFace: selector \"${selector}\" matched ${refs.length} faces; the host face must be unique`,\n      )\n    }\n    const ctx = buildEdgeResolutionContext(kernel, on as object)\n    if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: input has no naming context')\n    const resolved = resolveTopoRef(refs[0]!, ctx)\n    if (resolved.handle === undefined) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: selector-resolved face ref resolved to no live handle')\n    }\n    return resolved.handle as BrepHandle\n  }\n  if (selector.kind !== 'face') {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: selector must be a face ordinal, a selector string, or a face ref')\n  }\n  const ctx = buildEdgeResolutionContext(kernel, on as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: input has no naming context')\n  const resolved = resolveTopoRef(selector, ctx)\n  if (resolved.handle === undefined) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'sketchOnFace: face ref resolved to no live handle')\n  }\n  return resolved.handle as BrepHandle\n}\n\n/**\n * Make the placed face inherit the host face's outward orientation: surface\n * normals must point the same way, otherwise the resulting face — and any prism\n * extruded from it — carries a reversed shell whose OCCT volume collapses to ~0.\n * @param kernel - the BREP engine surface.\n * @param host - the host face handle (its normal is the reference).\n * @param face - the face built on the host surface.\n * @returns a handle to the (possibly re-oriented) face.\n */\nexport function orientLikeHost(kernel: BrepEngineApi, host: BrepHandle, face: BrepHandle): BrepHandle {\n  const a = kernel.surfaceNormal(host, 0, 0)\n  const b = kernel.surfaceNormal(face, 0, 0)\n  const dot = a.x * b.x + a.y * b.y + a.z * b.z\n  return dot < 0 ? kernel.reverseShape(face) : face\n}\n\n/**\n * Build one planar face (outer + optional holes) on the host **planar** face for\n * an organised contour entry. No surface snapping (`fixWireOnFace`) is needed:\n * the wire from `assembleWireOnFace` already lies in the face's plane, so\n * `makeFace` is exact.\n * @param kernel - the BREP engine surface.\n * @param host - the resolved live host face handle.\n * @param mode - the face-scale mode (`original` everywhere; `bounds`/`native` only where the engine exposes a finite UV domain).\n * @param entry - the organised contour entry (outer + optional holes).\n * @returns the built face handle.\n */\nfunction buildPlanarFaceOnHost(\n  kernel: BrepEngineApi,\n  host: BrepHandle,\n  mode: FaceScaleMode,\n  entry: Blueprint | CompoundBlueprint,\n): BrepHandle {\n  const outerBp = entry instanceof CompoundBlueprint ? entry.blueprints[0]! : entry\n  const outerWire = assembleWireOnFace(kernel, host, mode, outerBp).wire\n  let face = orientLikeHost(kernel, host, kernel.makeFace(outerWire))\n  if (entry instanceof CompoundBlueprint) {\n    const holes = entry.blueprints.slice(1).map((h) => assembleWireOnFace(kernel, host, mode, h).wire as never)\n    if (holes.length > 0) face = kernel.addHolesInFace(face, holes)\n  }\n  return face\n}\n\n/**\n * Build a 3D Shape from closed contours placed on the host **planar** face.\n * @param kernel - the BREP engine surface.\n * @param params - contour loops + target solid + face + scale mode.\n * @returns Shape on the target face (face, or the outer wire when `as:'wire'`).\n * @throws {BrepUnsupportedError} when the host face is not planar (use `cad.sketchOnSurface`).\n */\nexport function buildSketchOnFaceWith(kernel: BrepEngineApi, params: SketchOnFaceParams): Shape {\n  const host = resolveFaceHandle(kernel, params.on, params.face)\n  const mode = params.scaleMode ?? 'original'\n\n  // Planar-only gate: the curved / UV-conform capability moved to `cad.sketchOnSurface`.\n  const surface = kernel.surfaceType(host)\n  if (surface !== 'plane') {\n    throw new BrepUnsupportedError(\n      `E_BREP_UNSUPPORTED: cad.sketchOnFace only supports planar faces (got surfaceType '${surface}'). ` +\n      'Use cad.sketchOnSurface for curved/UV-conform placement.',\n      getCurrentStmt(),\n    )\n  }\n  // brepkit planar faces expose an infinite (±1e6) UV domain, so only the\n  // identity 'original' scale mode is meaningful there (mirrors the mesh branch\n  // restriction); OCCT planar faces keep full scaleMode support.\n  const engineId = getBackends().config.brepEngineId\n  if (engineId === 'brepkit' && mode !== 'original') {\n    throw new BrepUnsupportedError(\n      `E_BREP_UNSUPPORTED: cad.sketchOnFace on a brepkit planar face only supports scaleMode 'original' ` +\n      \"(brepkit planar faces have no finite UV domain) — use the default 'original'.\",\n      getCurrentStmt(),\n    )\n  }\n\n  const blueprints = params.contours.map(\n    (loop) => new Blueprint(loop.segments.map((s) => profileSegToCurve(s as ProfileSegLike))),\n  )\n  const organised = organiseBlueprints(blueprints)\n\n  if (params.as === 'wire') {\n    const outer =\n      organised.blueprints[0] instanceof CompoundBlueprint\n        ? organised.blueprints[0].blueprints[0]!\n        : (organised.blueprints[0] as Blueprint)\n    const { wire } = assembleWireOnFace(kernel, host, mode, outer)\n    return fromBrepCurve(solidToShape(kernel, wire), { solid: wire })\n  }\n\n  const faces = organised.blueprints.map((entry) => buildPlanarFaceOnHost(kernel, host, mode, entry))\n  if (faces.length === 0) throw new Error('sketchOnFace: no contours to place')\n  if (faces.length === 1) {\n    const f = faces[0]!\n    return fromBrep(solidToShape(kernel, f), { solid: f })\n  }\n  const compound = kernel.makeCompound(faces)\n  return fromBrep(solidToShape(kernel, compound), { solid: compound })\n}\n\n/**\n * 把一张平面的法向对齐到参考方向（外部朝向）。网格链上的复制版：BREP 侧的\n * `orientLikeHost` 存在的原因是\"面朝向反了 → 由它拉出的棱柱壳反向 → 体积归零\"，\n * 这里同一个道理，只是参考法向来自**平面本身**（`meshFacePlane` 的法向就是从宿主面\n * 的 `surfaceNormal` 取的），不必再回读宿主句柄。\n *\n * @param kernel - the mesh backend's L1 kernel.\n * @param reference - the outward normal the placed face must agree with.\n * @param face - the face built on the plane.\n * @returns a handle to the (possibly re-oriented) face.\n */\nfunction orientFaceTo(kernel: BrepEngineApi, reference: Vec3, face: BrepHandle): BrepHandle {\n  const uv = kernel.uvBounds(face)\n  const n = kernel.surfaceNormal(face, (uv.uMin + uv.uMax) / 2, (uv.vMin + uv.vMax) / 2)\n  const dot = reference.x * n.x + reference.y * n.y + reference.z * n.z\n  return dot < 0 ? kernel.reverseShape(face) : face\n}\n\n/** 一个已归类的轮廓条目（外环 + 可选孔）在平面坐标系里造一张面。 */\nfunction buildFaceOnPlane(\n  kernel: BrepEngineApi,\n  plane: Plane,\n  outward: Vec3,\n  entry: Blueprint | CompoundBlueprint,\n): BrepHandle {\n  const outerBp = entry instanceof CompoundBlueprint ? entry.blueprints[0]! : entry\n  let face = orientFaceTo(kernel, outward, kernel.makeFace(assembleWire(kernel, plane, outerBp)))\n  if (entry instanceof CompoundBlueprint) {\n    const holes = entry.blueprints.slice(1).map((h) => assembleWire(kernel, plane, h) as never)\n    if (holes.length > 0) face = kernel.addHolesInFace(face, holes)\n  }\n  return face\n}\n\n/**\n * 网格链上的 `cad.sketchOnFace`：在**识别出的平面网格面**上铺 2D 轮廓，产出网格链面\n * （方案 2026-10-01 §4 Phase 3-2），可交给 `cad.extrude` 的网格路径拉伸出新实体。\n *\n * 与 BREP 侧的三点差别，每一点都是\"近似拓扑没有 UV 语义\"的直接后果：\n *\n * 1. **不走 UV 域**。BREP 侧 `assembleWireOnFace` 把 2D 采样点映射进面的 `(u,v)` 域；\n *    而平面在 brepkit 上的域是 ±1e6 的**无限域**（方案 §4 Phase 3-1 实测），拿它当\n *    草图范围毫无意义。这里改用面自己的平面框（原点 = 面包围盒中心、法向 = 面法向），\n *    2D 坐标直接落在平面坐标系里——与 `cad.sketchOnPlane` 的语义一致。\n * 2. **`scaleMode` 只接受 `'original'`**。`'bounds'` / `'native'` 的定义是\"拟合到面的\n *    UV 域\"，而那个域在这里要么是无限域、要么不存在。静默按 `'original'` 处理会造成\n *    \"同一次调用在两条链上得到不同尺寸\"的隐性分歧，所以如实拒绝。\n * 3. **`as:'wire'` 不支持**。网格链上的一根 wire 没有身份槽（面才有），而 sketch 的\n *    下游用途（拉伸）要的正是面。需要 wire 的场景请走 BREP 链。\n *\n * 另外只支持**平面面**：曲面面（STL 圆柱的侧面片）上铺草图需要曲面嵌入，属未开的能力。\n *\n * @param params - contour loops + target mesh solid + face selector + scale mode.\n * @returns the mesh-chain face Shape on the target face.\n * @throws {MeshUnsupportedError} when the target is not a mesh solid, the face is not planar,\n *   the scale mode is not `'original'`, `as:'wire'` was requested, or the sketch is multi-island.\n */\nexport function buildSketchOnFaceMesh(params: SketchOnFaceParams): Shape {\n  const opLabel = 'sketchOnFace'\n  const backend = meshBackendOrThrow(opLabel)\n  const kernel = backend.kernel\n\n  const mode = params.scaleMode ?? 'original'\n  if (mode !== 'original') {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} scaleMode '${mode}' is defined against the face's UV domain, ` +\n      'which a mesh-chain face does not have — use the default \\'original\\' (2D coords live in the face plane)',\n      getCurrentStmt(),\n    )\n  }\n  if (params.as === 'wire') {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} as:'wire' has no mesh-chain representation — ` +\n      'a mesh-chain wire has no identity slot; ask for the default as:\\'face\\' instead',\n      getCurrentStmt(),\n    )\n  }\n  // 选择器字符串只服务精度链（网格零件无 role 层）；网格链用 1 起序号。\n  if (typeof params.face === 'string') {\n    throw new TopoRefError(\n      'E_TOPO_MESH_UNSUPPORTED',\n      'face',\n      `sketchOnFace: selector strings are precision-chain only — mesh solids have no role layer (use 1-based face ordinals)`,\n    )\n  }\n\n  const host = resolveMeshFaceHandle(kernel, params.on, params.face, opLabel)\n  const surface = kernel.surfaceType(host)\n  if (surface !== 'plane') {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} needs a planar mesh face to sketch on — this face reports ` +\n      `surfaceType '${surface}'. Sketches on curved approximate faces are not implemented ` +\n      '(an STL cylinder is 32 planar strips, each of which IS usable)',\n      getCurrentStmt(),\n    )\n  }\n\n  const plane = meshFacePlane(kernel, host)\n  const outward: Vec3 = { x: plane.zDir.x, y: plane.zDir.y, z: plane.zDir.z }\n\n  const organised = organiseBlueprints(toContourBlueprints(params.contours))\n  if (organised.blueprints.length === 0) throw new Error('sketchOnFace: no contours to place')\n  if (organised.blueprints.length > 1) {\n    throw new MeshUnsupportedError(\n      `E_MESH_SOLID_UNSUPPORTED: ${opLabel} produced ${organised.blueprints.length} disjoint islands — ` +\n      'the mesh backend can only extrude a single face (brepkit extrude takes one face, not a compound). ' +\n      'Sketch and extrude each island separately, then unite them with a boolean',\n      getCurrentStmt(),\n    )\n  }\n\n  const face = buildFaceOnPlane(kernel, plane, outward, organised.blueprints[0]!)\n  return meshFaceProduct(backend, face)\n}\n\n/**\n * `cad.sketchOnFace`: place 2D contours on a **planar** face of a solid and\n * construct a Shape. Engine-neutral (no `engines` declaration): works on the\n * OCCT BREP engine, the brepkit BREP engine, and the brepkit mesh backend.\n *\n * **网格链**（`meshEngines: ['brepkit']`，方案 2026-10-01 §4 Phase 3）：`on` 是网格实体\n * 时，轮廓按面自己的**平面框**铺放（原点 = 面包围盒中心、法向 = 面法向），产物是一张\n * 网格链面，可直接交给 `cad.extrude` 拉伸。该分支只接受平面面、只接受默认\n * `scaleMode`（`'bounds'`/`'native'` 相对 UV 域定义，网格链上没有 UV 域）、只接受\n * `as:'face'`、且只接受单个轮廓岛——每一条越界都以 `E_MESH_SOLID_UNSUPPORTED` 说明原因。\n *\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sketchOnFace\n * @returns Shape on the target face (face, or a wire curve when `as:'wire'`).\n * @param params.contours - ordered 2D closed contours (same shape as `cad.profile`).type:any[] required:true\n * @param params.on - the target solid on which the face lives.type:Shape required:true\n * @param params.face - the host face: FaceTopoRef（UI 拾取产物字面量）| 面选择器字符串（如 \">Z\"，在 on 上解析，多面命中抛错）| 1 起序号（仅网格链/当前内核快照，禁止用于生成脚本）。type:any required:true\n * @param params.scaleMode - UV mapping: 'original' (identity) | 'bounds'/'native' (affine-fit; OCCT planar only).type:string required:false\n * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false\n * @example\n * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }\n * const face = cad.sketchOnFace({ contours: [loop], on: cad.box(20, 20, 10), face: '>Z' })\n */\nexport const sketchOnFace = defineOp({\n  meshEngines: ['brepkit'],\n  mesh(params: Record<string, unknown>) {\n    assertProfileParams(params)\n    return buildSketchOnFaceMesh(params as unknown as SketchOnFaceParams)\n  },\n  brep(params: Record<string, unknown>) {\n    assertProfileParams(params)\n    return buildSketchOnFaceWith(getBrepApi(), params as unknown as SketchOnFaceParams)\n  },\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [] } } as Provenance,\n\n  paramDims: {},\n})\n"]}

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

@@ -82,6 +82,9 @@ export declare function buildSketchOnPlaneWith(kernel: BrepEngineApi, params: Sk
  * @param params.contours - ordered 2D contours (same shape as `cad.profile`: segment loops, or a drawn `Blueprint`).type:any required:true
  * @param params.plane - named plane (`'XY'` / `'XZ'`…) or `{ origin, normal, xAxis }`.type:any required:true
  * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false
+ * @example
+ * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }
+ * const face = cad.sketchOnPlane({ contours: [loop], plane: 'XY' })
  */
 export declare const sketchOnPlane: ((params: Record<string, unknown>) => Promise<Shape>) & {
     __faijs__dualOp?: import("../define-op.js").DualOpMeta;

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

@@ -1 +1 @@
-{"version":3,"file":"sketch-on-plane.d.ts","sourceRoot":"","sources":["../../src/api/sketch-on-plane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAM9D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGnD,OAAO,EAAiC,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAEtG,OAAO,EAA4C,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAE1G,wGAAwG;AACxG,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,EAAE,WAAW,EAAE,GAAG,aAAa,CAAA;IACvC,iEAAiE;IACjE,KAAK,EAAE,SAAS,CAAA;IAChB,oGAAoG;IACpG,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,GAAE,SAAqB,GAAG,KAAK,CAK/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,SAAS,EAAE,EACvB,EAAE,GAAE,MAAM,GAAG,MAAe,GAC3B,KAAK,CAgCP;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,GAAG,KAAK,CAQhG;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa;;CASxB,CAAA"}
+{"version":3,"file":"sketch-on-plane.d.ts","sourceRoot":"","sources":["../../src/api/sketch-on-plane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAM9D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGnD,OAAO,EAAiC,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAEtG,OAAO,EAA4C,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAE1G,wGAAwG;AACxG,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,EAAE,WAAW,EAAE,GAAG,aAAa,CAAA;IACvC,iEAAiE;IACjE,KAAK,EAAE,SAAS,CAAA;IAChB,oGAAoG;IACpG,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,GAAE,SAAqB,GAAG,KAAK,CAK/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,SAAS,EAAE,EACvB,EAAE,GAAE,MAAM,GAAG,MAAe,GAC3B,KAAK,CAgCP;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,GAAG,KAAK,CAQhG;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa;;CASxB,CAAA"}

package/dist/api/sketch-on-plane.js

@@ -93,6 +93,9 @@ export function buildSketchOnPlaneWith(kernel, params) {
  * @param params.contours - ordered 2D contours (same shape as `cad.profile`: segment loops, or a drawn `Blueprint`).type:any required:true
  * @param params.plane - named plane (`'XY'` / `'XZ'`…) or `{ origin, normal, xAxis }`.type:any required:true
  * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false
+ * @example
+ * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }
+ * const face = cad.sketchOnPlane({ contours: [loop], plane: 'XY' })
  */
 export const sketchOnPlane = defineOp({
     brep(params) {

package/dist/api/sketch-on-plane.js.map

@@ -1 +1 @@
-{"version":3,"file":"sketch-on-plane.js","sourceRoot":"","sources":["../../src/api/sketch-on-plane.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `cad.sketchOnPlane`: lift 2D contours onto an arbitrary plane (E2 placement).\n *\n * This is the shared \"placement\" step of the plan's unified 3D pipeline: any 2D\n * profile source (profile / draw / sketch) that describes contours as\n * `ProfileLoop`s can be placed here, then extruded along the plane normal. The\n * plane is a named plane (`'XY'` / `'XZ'` / `'top'` …) or an explicit frame\n * `{ origin, normal, xAxis }`. The plane lift runs on the geometry2d bridge,\n * which builds exact analytic edges on BOTH engines: full circles via\n * `makeCircleEdge`, arcs via `makeArcEdge` (brepkit's circumcircle defect fixed\n * 2026-09-30). The op therefore carries no engine gate.\n * @module\n */\nimport type { Shape } from '../mesh/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { solidToShape } from '../brep/brep-ops'\nimport { fromBrep, fromBrepCurve } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { Blueprint } from '../geometry2d/blueprint'\nimport { CompoundBlueprint } from '../geometry2d/compound-blueprint'\nimport { organiseBlueprints } from '../geometry2d/organise'\nimport { namedPlane, makePlane, toVec3, type Plane, type Vec3Input } from '../geometry2d/bridge/plane'\nimport { assembleWire } from '../geometry2d/bridge/lift-on-plane'\nimport { assertProfileParams, toContourBlueprints, type DrawnContours, type ProfileLoop } from './profile'\n\n/** A plane given by a named plane and/or an explicit frame (coords accept both array and `{x,y,z}`). */\nexport interface PlaneSpec {\n  /** Named plane (`'XY'` / `'XZ'` / `'YZ'` / `'front'` / `'back'` / `'left'` / …). */\n  name?: string\n  /** The plane origin (default [0,0,0]; array `[x,y,z]` or `{x,y,z}`). */\n  origin?: Vec3Input\n  /** Explicit normal (used with an explicit frame; array or `{x,y,z}`). */\n  normal?: Vec3Input\n  /** Explicit in-plane X axis (auto-derived when omitted; array or `{x,y,z}`). */\n  xAxis?: Vec3Input\n}\n\n/** Contour loops + a target plane (+ the result mode) for `cad.sketchOnPlane`. */\nexport interface SketchOnPlaneParams {\n  /**\n   * Contour source: segment loops (`{segments: […]}`) or already-drawn contours\n   * (a `Blueprint`, or an array of them). The drawn form is what makes the\n   * \"draw → place → extrude\" pipeline real — see {@link DrawnContours}.\n   */\n  contours: ProfileLoop[] | DrawnContours\n  /** Named plane or explicit `{ origin, normal, xAxis }` frame. */\n  plane: PlaneSpec\n  /** Result shape: 'face' (default) builds a planar face; 'wire' returns the outer-loop wire only. */\n  as?: 'face' | 'wire'\n}\n\n/**\n * Resolve a `PlaneSpec` to a plane frame. A named plane wins over an explicit\n * frame; with neither, the XY plane is used.\n * @param planeSpec - the user-facing plane spec (named plane and/or explicit frame).\n * @param fallbackOrigin - the origin used when `planeSpec.origin` is absent (default [0,0,0]).\n * @returns the resolved plane frame.\n */\nexport function resolvePlane(planeSpec: PlaneSpec, fallbackOrigin: Vec3Input = [0, 0, 0]): Plane {\n  const o = planeSpec.origin ?? toVec3(fallbackOrigin)\n  if (planeSpec.name) return namedPlane(planeSpec.name, o)\n  if (planeSpec.normal) return makePlane(o, planeSpec.normal, planeSpec.xAxis)\n  return namedPlane('XY', o)\n}\n\n/**\n * Build a 3D Shape (planar face, or outer-loop wire when `as:'wire'`) from a set\n * of classified `Blueprint` contours on a plane. This is the shared placement\n * core for every 2D profile source (`cad.profile` / a drawn contour / sketch): it\n * organises the closed contours (holes vs islands), assembles edge wires on the\n * plane via the geometry2d bridge, and wraps them as a BREP face — ready to be\n * extruded along the plane normal.\n * @param kernel - the BREP engine surface.\n * @param plane - the resolved target plane frame.\n * @param blueprints - ordered closed contours as `Blueprint`s (draw output).\n * @param as - `'face'` (default) or `'wire'` (outer loop only).\n * @returns Shape on the target plane (face, or a wire curve when `as:'wire'`).\n */\nexport function buildShapeFromBlueprints(\n  kernel: BrepEngineApi,\n  plane: Plane,\n  blueprints: Blueprint[],\n  as: 'face' | 'wire' = 'face',\n): Shape {\n  const organised = organiseBlueprints(blueprints)\n\n  if (as === 'wire') {\n    const outerBp =\n      organised.blueprints[0] instanceof CompoundBlueprint\n        ? organised.blueprints[0].blueprints[0]!\n        : (organised.blueprints[0] as Blueprint)\n    const wire = assembleWire(kernel, plane, outerBp)\n    return fromBrepCurve(solidToShape(kernel, wire), { solid: wire })\n  }\n\n  const faces: ReturnType<BrepEngineApi['makeFace']>[] = []\n  for (const entry of organised.blueprints) {\n    if (entry instanceof CompoundBlueprint) {\n      let face = kernel.makeFace(assembleWire(kernel, plane, entry.blueprints[0]!))\n      const holes = entry.blueprints.slice(1).map((h) => assembleWire(kernel, plane, h) as never)\n      if (holes.length > 0) {\n        face = kernel.addHolesInFace(face, holes)\n      }\n      faces.push(face)\n    } else {\n      faces.push(kernel.makeFace(assembleWire(kernel, plane, entry)))\n    }\n  }\n\n  if (faces.length === 1) {\n    const f = faces[0]!\n    return fromBrep(solidToShape(kernel, f), { solid: f })\n  }\n  const compound = kernel.makeCompound(faces)\n  return fromBrep(solidToShape(kernel, compound), { solid: compound })\n}\n\n/**\n * Build the 2D→3D placement: normalize the contour source (segment loops or a\n * drawn contour) to a classified Blueprint set, assemble a wire on the plane,\n * then wrap as a face (or the outer wire).\n * @param kernel - the BREP engine surface.\n * @param params - contour source + plane + mode.\n * @returns Shape on the target plane (face, or a wire curve when `as:'wire'`).\n */\nexport function buildSketchOnPlaneWith(kernel: BrepEngineApi, params: SketchOnPlaneParams): Shape {\n  const plane = resolvePlane(params.plane)\n  // 2026-09-28：段环数据与「已绘制轮廓」（`Blueprint`）在此归一。少了这一步，\n  // 「draw → sketchOnPlane → extrude」就断了 —— 已绘制轮廓没有 OCCT 句柄，\n  // 实测喂 `cad.extrude` 报 `argument carries no BREP handle`、喂 `cad.sweep`\n  // 报 `INVALID_SHAPE_ID`，全仓没有第二个能把它变成 Shape 的通道。\n  const blueprints = toContourBlueprints(params.contours)\n  return buildShapeFromBlueprints(kernel, plane, blueprints, params.as ?? 'face')\n}\n\n/**\n * `cad.sketchOnPlane`: place 2D contours on a plane and construct a Shape.\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sketchOnPlane\n * @returns Shape on the target plane (face, or a wire curve when `as:'wire'`).\n * @param params.contours - ordered 2D contours (same shape as `cad.profile`: segment loops, or a drawn `Blueprint`).type:any required:true\n * @param params.plane - named plane (`'XY'` / `'XZ'`…) or `{ origin, normal, xAxis }`.type:any required:true\n * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false\n */\nexport const sketchOnPlane = defineOp({\n\n  brep(params: Record<string, unknown>) {\n    assertProfileParams(params)\n    return buildSketchOnPlaneWith(getBrepApi(), params as unknown as SketchOnPlaneParams)\n  },\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [] } } as Provenance,\n\n  paramDims: {},\n})"]}
+{"version":3,"file":"sketch-on-plane.js","sourceRoot":"","sources":["../../src/api/sketch-on-plane.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `cad.sketchOnPlane`: lift 2D contours onto an arbitrary plane (E2 placement).\n *\n * This is the shared \"placement\" step of the plan's unified 3D pipeline: any 2D\n * profile source (profile / draw / sketch) that describes contours as\n * `ProfileLoop`s can be placed here, then extruded along the plane normal. The\n * plane is a named plane (`'XY'` / `'XZ'` / `'top'` …) or an explicit frame\n * `{ origin, normal, xAxis }`. The plane lift runs on the geometry2d bridge,\n * which builds exact analytic edges on BOTH engines: full circles via\n * `makeCircleEdge`, arcs via `makeArcEdge` (brepkit's circumcircle defect fixed\n * 2026-09-30). The op therefore carries no engine gate.\n * @module\n */\nimport type { Shape } from '../mesh/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { solidToShape } from '../brep/brep-ops'\nimport { fromBrep, fromBrepCurve } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { Blueprint } from '../geometry2d/blueprint'\nimport { CompoundBlueprint } from '../geometry2d/compound-blueprint'\nimport { organiseBlueprints } from '../geometry2d/organise'\nimport { namedPlane, makePlane, toVec3, type Plane, type Vec3Input } from '../geometry2d/bridge/plane'\nimport { assembleWire } from '../geometry2d/bridge/lift-on-plane'\nimport { assertProfileParams, toContourBlueprints, type DrawnContours, type ProfileLoop } from './profile'\n\n/** A plane given by a named plane and/or an explicit frame (coords accept both array and `{x,y,z}`). */\nexport interface PlaneSpec {\n  /** Named plane (`'XY'` / `'XZ'` / `'YZ'` / `'front'` / `'back'` / `'left'` / …). */\n  name?: string\n  /** The plane origin (default [0,0,0]; array `[x,y,z]` or `{x,y,z}`). */\n  origin?: Vec3Input\n  /** Explicit normal (used with an explicit frame; array or `{x,y,z}`). */\n  normal?: Vec3Input\n  /** Explicit in-plane X axis (auto-derived when omitted; array or `{x,y,z}`). */\n  xAxis?: Vec3Input\n}\n\n/** Contour loops + a target plane (+ the result mode) for `cad.sketchOnPlane`. */\nexport interface SketchOnPlaneParams {\n  /**\n   * Contour source: segment loops (`{segments: […]}`) or already-drawn contours\n   * (a `Blueprint`, or an array of them). The drawn form is what makes the\n   * \"draw → place → extrude\" pipeline real — see {@link DrawnContours}.\n   */\n  contours: ProfileLoop[] | DrawnContours\n  /** Named plane or explicit `{ origin, normal, xAxis }` frame. */\n  plane: PlaneSpec\n  /** Result shape: 'face' (default) builds a planar face; 'wire' returns the outer-loop wire only. */\n  as?: 'face' | 'wire'\n}\n\n/**\n * Resolve a `PlaneSpec` to a plane frame. A named plane wins over an explicit\n * frame; with neither, the XY plane is used.\n * @param planeSpec - the user-facing plane spec (named plane and/or explicit frame).\n * @param fallbackOrigin - the origin used when `planeSpec.origin` is absent (default [0,0,0]).\n * @returns the resolved plane frame.\n */\nexport function resolvePlane(planeSpec: PlaneSpec, fallbackOrigin: Vec3Input = [0, 0, 0]): Plane {\n  const o = planeSpec.origin ?? toVec3(fallbackOrigin)\n  if (planeSpec.name) return namedPlane(planeSpec.name, o)\n  if (planeSpec.normal) return makePlane(o, planeSpec.normal, planeSpec.xAxis)\n  return namedPlane('XY', o)\n}\n\n/**\n * Build a 3D Shape (planar face, or outer-loop wire when `as:'wire'`) from a set\n * of classified `Blueprint` contours on a plane. This is the shared placement\n * core for every 2D profile source (`cad.profile` / a drawn contour / sketch): it\n * organises the closed contours (holes vs islands), assembles edge wires on the\n * plane via the geometry2d bridge, and wraps them as a BREP face — ready to be\n * extruded along the plane normal.\n * @param kernel - the BREP engine surface.\n * @param plane - the resolved target plane frame.\n * @param blueprints - ordered closed contours as `Blueprint`s (draw output).\n * @param as - `'face'` (default) or `'wire'` (outer loop only).\n * @returns Shape on the target plane (face, or a wire curve when `as:'wire'`).\n */\nexport function buildShapeFromBlueprints(\n  kernel: BrepEngineApi,\n  plane: Plane,\n  blueprints: Blueprint[],\n  as: 'face' | 'wire' = 'face',\n): Shape {\n  const organised = organiseBlueprints(blueprints)\n\n  if (as === 'wire') {\n    const outerBp =\n      organised.blueprints[0] instanceof CompoundBlueprint\n        ? organised.blueprints[0].blueprints[0]!\n        : (organised.blueprints[0] as Blueprint)\n    const wire = assembleWire(kernel, plane, outerBp)\n    return fromBrepCurve(solidToShape(kernel, wire), { solid: wire })\n  }\n\n  const faces: ReturnType<BrepEngineApi['makeFace']>[] = []\n  for (const entry of organised.blueprints) {\n    if (entry instanceof CompoundBlueprint) {\n      let face = kernel.makeFace(assembleWire(kernel, plane, entry.blueprints[0]!))\n      const holes = entry.blueprints.slice(1).map((h) => assembleWire(kernel, plane, h) as never)\n      if (holes.length > 0) {\n        face = kernel.addHolesInFace(face, holes)\n      }\n      faces.push(face)\n    } else {\n      faces.push(kernel.makeFace(assembleWire(kernel, plane, entry)))\n    }\n  }\n\n  if (faces.length === 1) {\n    const f = faces[0]!\n    return fromBrep(solidToShape(kernel, f), { solid: f })\n  }\n  const compound = kernel.makeCompound(faces)\n  return fromBrep(solidToShape(kernel, compound), { solid: compound })\n}\n\n/**\n * Build the 2D→3D placement: normalize the contour source (segment loops or a\n * drawn contour) to a classified Blueprint set, assemble a wire on the plane,\n * then wrap as a face (or the outer wire).\n * @param kernel - the BREP engine surface.\n * @param params - contour source + plane + mode.\n * @returns Shape on the target plane (face, or a wire curve when `as:'wire'`).\n */\nexport function buildSketchOnPlaneWith(kernel: BrepEngineApi, params: SketchOnPlaneParams): Shape {\n  const plane = resolvePlane(params.plane)\n  // 2026-09-28：段环数据与「已绘制轮廓」（`Blueprint`）在此归一。少了这一步，\n  // 「draw → sketchOnPlane → extrude」就断了 —— 已绘制轮廓没有 OCCT 句柄，\n  // 实测喂 `cad.extrude` 报 `argument carries no BREP handle`、喂 `cad.sweep`\n  // 报 `INVALID_SHAPE_ID`，全仓没有第二个能把它变成 Shape 的通道。\n  const blueprints = toContourBlueprints(params.contours)\n  return buildShapeFromBlueprints(kernel, plane, blueprints, params.as ?? 'face')\n}\n\n/**\n * `cad.sketchOnPlane`: place 2D contours on a plane and construct a Shape.\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sketchOnPlane\n * @returns Shape on the target plane (face, or a wire curve when `as:'wire'`).\n * @param params.contours - ordered 2D contours (same shape as `cad.profile`: segment loops, or a drawn `Blueprint`).type:any required:true\n * @param params.plane - named plane (`'XY'` / `'XZ'`…) or `{ origin, normal, xAxis }`.type:any required:true\n * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false\n * @example\n * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }\n * const face = cad.sketchOnPlane({ contours: [loop], plane: 'XY' })\n */\nexport const sketchOnPlane = defineOp({\n\n  brep(params: Record<string, unknown>) {\n    assertProfileParams(params)\n    return buildSketchOnPlaneWith(getBrepApi(), params as unknown as SketchOnPlaneParams)\n  },\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [] } } as Provenance,\n\n  paramDims: {},\n})"]}

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

@@ -66,9 +66,12 @@ export declare function buildSketchOnSurfaceWith(kernel: BrepEngineApi, params:
  * @returns Shape on the target face (face, or a wire curve when `as:'wire'`).
  * @param params.contours - ordered 2D closed contours (same shape as `cad.profile`).type:any[] required:true
  * @param params.on - the target solid on which the face lives.type:Shape required:true
- * @param params.face - the host face: a 1-based ordinal or a `cad.faceRef(on, n)` result.type:any required:true
+ * @param params.face - the host face: FaceTopoRef（UI 拾取产物字面量）| 面选择器字符串（如 ">Z"，在 on 上解析，多面命中抛错）| 1 起序号（仅网格链/当前内核快照，禁止用于生成脚本）。type:any required:true
  * @param params.scaleMode - UV mapping: 'original' (identity) | 'bounds'/'native' (affine-fit).type:string required:false
  * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false
+ * @example
+ * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }
+ * const sk = cad.sketchOnSurface({ contours: [loop], on: cad.cylinder(20, 30), face: '>Z', scaleMode: 'original' })
  */
 export declare const sketchOnSurface: ((params: Record<string, unknown>) => Promise<Shape>) & {
     __faijs__dualOp?: import("../define-op.js").DualOpMeta;

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

@@ -1 +1 @@
-{"version":3,"file":"sketch-on-surface.d.ts","sourceRoot":"","sources":["../../src/api/sketch-on-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAStD,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAExF,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAEjE,OAAO,EAAqC,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAe7F;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,WAAW,EAAE,GACtB,UAAU,EAAE,CAMd;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,GAAG,KAAK,CAyBjG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe;;CAS1B,CAAA"}
+{"version":3,"file":"sketch-on-surface.d.ts","sourceRoot":"","sources":["../../src/api/sketch-on-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAStD,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAExF,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAEjE,OAAO,EAAqC,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAe7F;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,WAAW,EAAE,GACtB,UAAU,EAAE,CAMd;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,GAAG,KAAK,CAyBjG;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe;;CAS1B,CAAA"}

package/dist/api/sketch-on-surface.js

@@ -83,9 +83,12 @@ export function buildSketchOnSurfaceWith(kernel, params) {
  * @returns Shape on the target face (face, or a wire curve when `as:'wire'`).
  * @param params.contours - ordered 2D closed contours (same shape as `cad.profile`).type:any[] required:true
  * @param params.on - the target solid on which the face lives.type:Shape required:true
- * @param params.face - the host face: a 1-based ordinal or a `cad.faceRef(on, n)` result.type:any required:true
+ * @param params.face - the host face: FaceTopoRef（UI 拾取产物字面量）| 面选择器字符串（如 ">Z"，在 on 上解析，多面命中抛错）| 1 起序号（仅网格链/当前内核快照，禁止用于生成脚本）。type:any required:true
  * @param params.scaleMode - UV mapping: 'original' (identity) | 'bounds'/'native' (affine-fit).type:string required:false
  * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false
+ * @example
+ * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }
+ * const sk = cad.sketchOnSurface({ contours: [loop], on: cad.cylinder(20, 30), face: '>Z', scaleMode: 'original' })
  */
 export const sketchOnSurface = defineOp({
     engines: ['occt'],

package/dist/api/sketch-on-surface.js.map

@@ -1 +1 @@
-{"version":3,"file":"sketch-on-surface.js","sourceRoot":"","sources":["../../src/api/sketch-on-surface.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `cad.sketchOnSurface`: place 2D contours onto the UV parameter space of an\n * existing face (E3 placement) — the **curved / UV-conform** sketch op.\n *\n * This is the renamed successor of the old curved-capable `cad.sketchOnFace`\n * (2026-10-09 split). `cad.sketchOnFace` now owns the *planar* face case\n * (engine-neutral, works on OCCT and brepkit BREP as well as mesh solids); this\n * op owns the *surface* case: it maps the contour into the host face's `(u,v)`\n * domain and snaps the resulting wire to the surface via `fixWireOnFace` (occt\n * only), so it is declared `engines: ['occt']`.\n *\n * Unlike `sketchOnPlane` (which lifts a contour onto a whole plane *frame*),\n * `sketchOnSurface` lays the contour on the surface of a specific face of a\n * target solid. Every 2D curve is sampled, the samples mapped into the face's\n * `(u,v)` domain under a scale mode (`original` / `bounds` / `native`), the\n * surface evaluated at those UVs, and a curve edge interpolated through the\n * resulting 3D points (see `geometry2d/bridge/on-surface.ts`). The placed wire\n * then becomes a face (`as:'face'`) ready to be extruded along the face normal,\n * or is returned raw (`as:'wire'`).\n *\n * It is surface-type-independent (plane / cylinder / cone / sphere): for planar\n * host faces `makeFace` is exact, for curved ones the wire is snapped to the\n * surface via `fixWireOnFace` (occt-wasm 5.6) before `makeFace`. The op\n * declares `engines: ['occt']` because that snapping step needs the BREP\n * platform.\n * @module\n */\nimport type { Shape } from '../mesh/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, fromBrepCurve } from '../shape'\nimport { solidToShape } from '../brep/brep-ops'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { Blueprint } from '../geometry2d/blueprint'\nimport { CompoundBlueprint } from '../geometry2d/compound-blueprint'\nimport { organiseBlueprints } from '../geometry2d/organise'\nimport { assembleWireOnFace, type FaceScaleMode } from '../geometry2d/bridge/on-surface'\nimport { profileSegToCurve, type ProfileSegLike } from '../geometry2d/adapt'\nimport { assertProfileParams, type ProfileLoop } from './profile'\nimport { fixWireOnFaceBrep } from './brep-operations/healingFns'\nimport { resolveFaceHandle, orientLikeHost, type SketchOnFaceParams } from './sketch-on-face'\n\n/** Build one face (outer + optional holes) on the host face for an organised contour entry (UV-conform). */\nfunction buildOnFace(kernel: BrepEngineApi, host: BrepHandle, mode: FaceScaleMode, entry: Blueprint | CompoundBlueprint): BrepHandle {\n  if (entry instanceof CompoundBlueprint) {\n    const outerWire = fixWireOnFaceBrep(assembleWireOnFace(kernel, host, mode, entry.blueprints[0]!).wire, host)\n    let face = orientLikeHost(kernel, host, kernel.makeFace(outerWire))\n    const holes = entry.blueprints.slice(1).map((h) => fixWireOnFaceBrep(assembleWireOnFace(kernel, host, mode, h).wire, host) as never)\n    if (holes.length > 0) face = kernel.addHolesInFace(face, holes)\n    return face\n  }\n  const wire = fixWireOnFaceBrep(assembleWireOnFace(kernel, host, mode, entry).wire, host)\n  return orientLikeHost(kernel, host, kernel.makeFace(wire))\n}\n\n/**\n * Place `contours` onto the UV space of the host face and return one BREP face\n * per classified contour (each outer + holes folded into a single face). Shared\n * by `cad.sketchOnSurface` (wrap as a Shape) and `cad.punchHole` (extrude → cut).\n * @param kernel - the BREP engine surface.\n * @param host - the resolved live host face handle.\n * @param mode - the face-scale (UV mapping) mode.\n * @param contours - ordered 2D closed contour loops to place.\n * @returns the BREP faces built on the host face (one per organised entry).\n */\nexport function placeContoursOnFace(\n  kernel: BrepEngineApi,\n  host: BrepHandle,\n  mode: FaceScaleMode,\n  contours: ProfileLoop[],\n): BrepHandle[] {\n  const blueprints = contours.map(\n    (loop) => new Blueprint(loop.segments.map((s) => profileSegToCurve(s as ProfileSegLike))),\n  )\n  const organised = organiseBlueprints(blueprints)\n  return organised.blueprints.map((entry) => buildOnFace(kernel, host, mode, entry))\n}\n\n/**\n * Build a 3D Shape from closed contours placed on the host face (UV-conform).\n * @param kernel - the BREP engine surface.\n * @param params - contour loops + target solid + face + scale mode.\n * @returns Shape on the target face (face, or the outer wire when `as:'wire'`).\n */\nexport function buildSketchOnSurfaceWith(kernel: BrepEngineApi, params: SketchOnFaceParams): Shape {\n  const host = resolveFaceHandle(kernel, params.on, params.face)\n  const mode = params.scaleMode ?? 'original'\n  const blueprints = params.contours.map(\n    (loop) => new Blueprint(loop.segments.map((s) => profileSegToCurve(s as ProfileSegLike))),\n  )\n  const organised = organiseBlueprints(blueprints)\n\n  if (params.as === 'wire') {\n    const outer =\n      organised.blueprints[0] instanceof CompoundBlueprint\n        ? organised.blueprints[0].blueprints[0]!\n        : (organised.blueprints[0] as Blueprint)\n    const { wire } = assembleWireOnFace(kernel, host, mode, outer)\n    return fromBrepCurve(solidToShape(kernel, wire), { solid: wire })\n  }\n\n  const faces = placeContoursOnFace(kernel, host, mode, params.contours)\n  if (faces.length === 0) throw new Error('sketchOnSurface: no contours to place')\n  if (faces.length === 1) {\n    const f = faces[0]!\n    return fromBrep(solidToShape(kernel, f), { solid: f })\n  }\n  const compound = kernel.makeCompound(faces)\n  return fromBrep(solidToShape(kernel, compound), { solid: compound })\n}\n\n/**\n * `cad.sketchOnSurface`: place 2D contours on a face of a solid via UV-conform\n * placement and construct a Shape.\n *\n * Curved/UV-conform variant of `cad.sketchOnFace` (which is now planar-only and\n * engine-neutral). This op maps the contour into the face's `(u,v)` domain and\n * snaps it to the surface, a step that needs the OCCT BREP platform, hence\n * `engines: ['occt']`.\n *\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sketchOnSurface\n * @returns Shape on the target face (face, or a wire curve when `as:'wire'`).\n * @param params.contours - ordered 2D closed contours (same shape as `cad.profile`).type:any[] required:true\n * @param params.on - the target solid on which the face lives.type:Shape required:true\n * @param params.face - the host face: a 1-based ordinal or a `cad.faceRef(on, n)` result.type:any required:true\n * @param params.scaleMode - UV mapping: 'original' (identity) | 'bounds'/'native' (affine-fit).type:string required:false\n * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false\n */\nexport const sketchOnSurface = defineOp({\n  engines: ['occt'],\n  brep(params: Record<string, unknown>) {\n    assertProfileParams(params)\n    return buildSketchOnSurfaceWith(getBrepApi(), params as unknown as SketchOnFaceParams)\n  },\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [] } } as Provenance,\n\n  paramDims: {},\n})\n"]}
+{"version":3,"file":"sketch-on-surface.js","sourceRoot":"","sources":["../../src/api/sketch-on-surface.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `cad.sketchOnSurface`: place 2D contours onto the UV parameter space of an\n * existing face (E3 placement) — the **curved / UV-conform** sketch op.\n *\n * This is the renamed successor of the old curved-capable `cad.sketchOnFace`\n * (2026-10-09 split). `cad.sketchOnFace` now owns the *planar* face case\n * (engine-neutral, works on OCCT and brepkit BREP as well as mesh solids); this\n * op owns the *surface* case: it maps the contour into the host face's `(u,v)`\n * domain and snaps the resulting wire to the surface via `fixWireOnFace` (occt\n * only), so it is declared `engines: ['occt']`.\n *\n * Unlike `sketchOnPlane` (which lifts a contour onto a whole plane *frame*),\n * `sketchOnSurface` lays the contour on the surface of a specific face of a\n * target solid. Every 2D curve is sampled, the samples mapped into the face's\n * `(u,v)` domain under a scale mode (`original` / `bounds` / `native`), the\n * surface evaluated at those UVs, and a curve edge interpolated through the\n * resulting 3D points (see `geometry2d/bridge/on-surface.ts`). The placed wire\n * then becomes a face (`as:'face'`) ready to be extruded along the face normal,\n * or is returned raw (`as:'wire'`).\n *\n * It is surface-type-independent (plane / cylinder / cone / sphere): for planar\n * host faces `makeFace` is exact, for curved ones the wire is snapped to the\n * surface via `fixWireOnFace` (occt-wasm 5.6) before `makeFace`. The op\n * declares `engines: ['occt']` because that snapping step needs the BREP\n * platform.\n * @module\n */\nimport type { Shape } from '../mesh/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, fromBrepCurve } from '../shape'\nimport { solidToShape } from '../brep/brep-ops'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { Blueprint } from '../geometry2d/blueprint'\nimport { CompoundBlueprint } from '../geometry2d/compound-blueprint'\nimport { organiseBlueprints } from '../geometry2d/organise'\nimport { assembleWireOnFace, type FaceScaleMode } from '../geometry2d/bridge/on-surface'\nimport { profileSegToCurve, type ProfileSegLike } from '../geometry2d/adapt'\nimport { assertProfileParams, type ProfileLoop } from './profile'\nimport { fixWireOnFaceBrep } from './brep-operations/healingFns'\nimport { resolveFaceHandle, orientLikeHost, type SketchOnFaceParams } from './sketch-on-face'\n\n/** Build one face (outer + optional holes) on the host face for an organised contour entry (UV-conform). */\nfunction buildOnFace(kernel: BrepEngineApi, host: BrepHandle, mode: FaceScaleMode, entry: Blueprint | CompoundBlueprint): BrepHandle {\n  if (entry instanceof CompoundBlueprint) {\n    const outerWire = fixWireOnFaceBrep(assembleWireOnFace(kernel, host, mode, entry.blueprints[0]!).wire, host)\n    let face = orientLikeHost(kernel, host, kernel.makeFace(outerWire))\n    const holes = entry.blueprints.slice(1).map((h) => fixWireOnFaceBrep(assembleWireOnFace(kernel, host, mode, h).wire, host) as never)\n    if (holes.length > 0) face = kernel.addHolesInFace(face, holes)\n    return face\n  }\n  const wire = fixWireOnFaceBrep(assembleWireOnFace(kernel, host, mode, entry).wire, host)\n  return orientLikeHost(kernel, host, kernel.makeFace(wire))\n}\n\n/**\n * Place `contours` onto the UV space of the host face and return one BREP face\n * per classified contour (each outer + holes folded into a single face). Shared\n * by `cad.sketchOnSurface` (wrap as a Shape) and `cad.punchHole` (extrude → cut).\n * @param kernel - the BREP engine surface.\n * @param host - the resolved live host face handle.\n * @param mode - the face-scale (UV mapping) mode.\n * @param contours - ordered 2D closed contour loops to place.\n * @returns the BREP faces built on the host face (one per organised entry).\n */\nexport function placeContoursOnFace(\n  kernel: BrepEngineApi,\n  host: BrepHandle,\n  mode: FaceScaleMode,\n  contours: ProfileLoop[],\n): BrepHandle[] {\n  const blueprints = contours.map(\n    (loop) => new Blueprint(loop.segments.map((s) => profileSegToCurve(s as ProfileSegLike))),\n  )\n  const organised = organiseBlueprints(blueprints)\n  return organised.blueprints.map((entry) => buildOnFace(kernel, host, mode, entry))\n}\n\n/**\n * Build a 3D Shape from closed contours placed on the host face (UV-conform).\n * @param kernel - the BREP engine surface.\n * @param params - contour loops + target solid + face + scale mode.\n * @returns Shape on the target face (face, or the outer wire when `as:'wire'`).\n */\nexport function buildSketchOnSurfaceWith(kernel: BrepEngineApi, params: SketchOnFaceParams): Shape {\n  const host = resolveFaceHandle(kernel, params.on, params.face)\n  const mode = params.scaleMode ?? 'original'\n  const blueprints = params.contours.map(\n    (loop) => new Blueprint(loop.segments.map((s) => profileSegToCurve(s as ProfileSegLike))),\n  )\n  const organised = organiseBlueprints(blueprints)\n\n  if (params.as === 'wire') {\n    const outer =\n      organised.blueprints[0] instanceof CompoundBlueprint\n        ? organised.blueprints[0].blueprints[0]!\n        : (organised.blueprints[0] as Blueprint)\n    const { wire } = assembleWireOnFace(kernel, host, mode, outer)\n    return fromBrepCurve(solidToShape(kernel, wire), { solid: wire })\n  }\n\n  const faces = placeContoursOnFace(kernel, host, mode, params.contours)\n  if (faces.length === 0) throw new Error('sketchOnSurface: no contours to place')\n  if (faces.length === 1) {\n    const f = faces[0]!\n    return fromBrep(solidToShape(kernel, f), { solid: f })\n  }\n  const compound = kernel.makeCompound(faces)\n  return fromBrep(solidToShape(kernel, compound), { solid: compound })\n}\n\n/**\n * `cad.sketchOnSurface`: place 2D contours on a face of a solid via UV-conform\n * placement and construct a Shape.\n *\n * Curved/UV-conform variant of `cad.sketchOnFace` (which is now planar-only and\n * engine-neutral). This op maps the contour into the face's `(u,v)` domain and\n * snaps it to the surface, a step that needs the OCCT BREP platform, hence\n * `engines: ['occt']`.\n *\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sketchOnSurface\n * @returns Shape on the target face (face, or a wire curve when `as:'wire'`).\n * @param params.contours - ordered 2D closed contours (same shape as `cad.profile`).type:any[] required:true\n * @param params.on - the target solid on which the face lives.type:Shape required:true\n * @param params.face - the host face: FaceTopoRef（UI 拾取产物字面量）| 面选择器字符串（如 \">Z\"，在 on 上解析，多面命中抛错）| 1 起序号（仅网格链/当前内核快照，禁止用于生成脚本）。type:any required:true\n * @param params.scaleMode - UV mapping: 'original' (identity) | 'bounds'/'native' (affine-fit).type:string required:false\n * @param params.as - `'face'` (default) or `'wire'` (outer loop only).type:string required:false\n * @example\n * // loop = 一个闭合 2D 轮廓：{ segments: [{ kind: 'line', x1, y1, x2, y2 }, ...] }\n * const sk = cad.sketchOnSurface({ contours: [loop], on: cad.cylinder(20, 30), face: '>Z', scaleMode: 'original' })\n */\nexport const sketchOnSurface = defineOp({\n  engines: ['occt'],\n  brep(params: Record<string, unknown>) {\n    assertProfileParams(params)\n    return buildSketchOnSurfaceWith(getBrepApi(), params as unknown as SketchOnFaceParams)\n  },\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [] } } as Provenance,\n\n  paramDims: {},\n})\n"]}

package/dist/api/surface/arg-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arg-spec.d.ts","sourceRoot":"","sources":["../../../src/api/surface/arg-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,kBAAkB;AAClB,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAErF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D,YAAY,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAE/D,uDAAuD;AAEvD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,cAAc,CAAA;IACpB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;OAEG;IACH,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAA;IACjC,8GAA8G;IAC9G,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,yFAAyF;IACzF,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAC1B,8NAA8N;IAC9N,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IACjC,iDAAiD;IACjD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IAEnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,mCAAmC,EAAE,OAAO,CAAA;IAC7D;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,aAAa,EAAE,OAAO,CAAC,CAAA;IACzD,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,aAAa,EAAE,OAAO,CAAA;IACtC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,YAAY,EAqzHlC,CAAA"}
+{"version":3,"file":"arg-spec.d.ts","sourceRoot":"","sources":["../../../src/api/surface/arg-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,kBAAkB;AAClB,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAErF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D,YAAY,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAE/D,uDAAuD;AAEvD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,cAAc,CAAA;IACpB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;OAEG;IACH,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAA;IACjC,8GAA8G;IAC9G,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,yFAAyF;IACzF,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAC1B,8NAA8N;IAC9N,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IACjC,iDAAiD;IACjD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IAEnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,mCAAmC,EAAE,OAAO,CAAA;IAC7D;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,aAAa,EAAE,OAAO,CAAC,CAAA;IACzD,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,aAAa,EAAE,OAAO,CAAA;IACtC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,YAAY,EAozHlC,CAAA"}

package/dist/api/surface/arg-spec.js

@@ -55,9 +55,11 @@ export const ARG_SPEC = [
         name: 'fuse',
         source: 'brep-operations/booleanFns.ts#fuseBrep',
         kind: 'brep-op',
-        // Phase 5 补漏（§1.5 推论 1 / D11）：来源实现 fuse 默认 trackEvolution 路径依赖
-        // kernel.isNull / kernel.dispose（occt 平台面）→ 平台 op，声明 engines: ['occt']
-        // 在 brepkit 下执行前报错（D11-4）。
+        // 来源实现 fuseBrep 仅经 getBrepApi().fuse（L1 裸方法，引擎无关）：brepkit 内核
+        // L1 有 fuse（brepkitKernel.ts）。曾以"依赖 kernel.isNull / kernel.dispose（occt
+        // 平台面）"为由声明 engines:['occt']（Phase 5 补漏），2026-10-17 实证当前
+        // fuseBrep 无此依赖 → 移除门禁。两引擎下均无面演化（裸 fuse；naming 仅作溯源
+        // 标注，同 intersect 的"几何正确、无面演化"处理）。
         args: '(a: Shape3D, b: Shape3D, options?: BooleanOptions) -> Result<Shape3D>',
         // 两个输入都是 faijs Shape → 原样直传给来源实现（引擎不改写入参）；第三参 options 透传。
         geometryArgs: [0, 1],
@@ -65,9 +67,6 @@ export const ARG_SPEC = [
         params: ['a', 'b', 'options'],
         formClass: 'A',
         scriptFace: true,
-        // 依赖声明（诚实原则）：来源实现 fuse 依赖 kernel.isNull / kernel.dispose（occt
-        // 平台面）→ 平台 op，声明 engines: ['occt']，在 brepkit / 其它引擎下执行前报错（D11-4）。
-        engines: ['occt'],
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {