@faicad/faijs 0.29.3 → 0.30.9

package/dist/api/engrave.js.map

@@ -1 +1 @@
-{"version":3,"file":"engrave.js","sourceRoot":"","sources":["../../src/api/engrave.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api engrave — 雕刻库函数\n *\n *\n * dispatchPath 静态判定 brep/mesh。\n * BREP 路径：textToSolid/svgToSolid + boolean（cut/fuse）。\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { AssetResolver } from '../cad-runtime/ports'\nimport { cad } from '../mesh'\nimport { parseSvgNaturalSize } from '../primitives/parse-svg-size'\nimport { textToSolid } from '../brep/text/text-to-solid'\nimport { svgToSolid } from '../brep/svg/svg-to-solid'\nimport { ensureDefaultFont } from '../brep/text/fontRegistry'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getSolidBoundingBox } from '../brep/brep-utils'\nimport { resolveSvgArg } from './internal/svg-asset-resolver'\nimport { getBackends } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, brepOf } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { assertPositiveNumber } from './assert'\n\n// ── per-op 参数自校验（Phase 2.2；api 层被直接 import 时的防御层） ──\n\n/**\n * Validate engrave parameters: at least one of `text` or `svg` must be\n * provided, and `depth` (if provided) must be a positive number.\n * @param params - the raw engrave operation parameters.\n */\nexport function assertEngraveParams(params: Record<string, unknown>): void {\n  const hasText = params.text !== undefined && params.text !== null && params.text !== ''\n  const hasSvg = params.svg !== undefined && params.svg !== null\n  if (!hasText && !hasSvg) {\n    throw new Error('[api/engrave] requires either \"text\" or \"svg\"')\n  }\n  if (params.depth !== undefined && params.depth !== null) {\n    assertPositiveNumber(params.depth, 'engrave.depth')\n  }\n}\n\n/** 世界坐标 → BREP solid 局部坐标。 */\nfunction worldToLocalPosition(\n  worldPos: Vec3,\n  partTransform: { position?: [number, number, number] } | undefined,\n): Vec3 {\n  const offset = partTransform?.position\n  if (!offset) return worldPos\n  return [\n    worldPos[0] - offset[0],\n    worldPos[1] - offset[1],\n    worldPos[2] - offset[2],\n  ]\n}\n\n/** 计算将 +Z 轴对齐到目标法向量的 3x4 仿射变换矩阵（仅旋转，无平移，Rodrigues 公式）。 */\nfunction alignZToNormal(normal: Vec3): number[] {\n  const [nx, ny, nz] = normal\n  const len = Math.sqrt(nx * nx + ny * ny + nz * nz)\n  if (len < 1e-10) {\n    return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]\n  }\n  const ux = nx / len, uy = ny / len, uz = nz / len\n\n  if (Math.abs(ux) < 1e-10 && Math.abs(uy) < 1e-10) {\n    if (uz > 0) return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]\n    return [1, 0, 0, 0, 0, -1, 0, 0, 0, 0, -1, 0]\n  }\n\n  const s = Math.sqrt(ux * ux + uy * uy)\n  const c = uz\n  const t = 1 - c\n  const ax = -uy / s, ay = ux / s\n\n  return [\n    c + ax * ax * t,  ax * ay * t,    ay * s,  0,\n    ax * ay * t,      c + ay * ay * t, -ax * s, 0,\n    -ay * s,          ax * s,          c,       0,\n  ]\n}\n\n/** 将 solid 居中到原点（基于包围盒中心，与 mesh 路径语义一致）。 */\nfunction centerSolidAtOrigin(kernel: BrepEngineApi, solid: BrepHandle): BrepHandle {\n  const bb = getSolidBoundingBox(kernel, solid)\n  const cx = (bb.min[0] + bb.max[0]) / 2\n  const cy = (bb.min[1] + bb.max[1]) / 2\n  const cz = (bb.min[2] + bb.max[2]) / 2\n  const centered = kernel.translate(solid, -cx, -cy, -cz)\n  kernel.release(solid)\n  return centered\n}\n\n/** BREP 路径：textToSolid/svgToSolid + boolean（cut/fuse）。 */\nasync function engraveBrepPath(input: Shape, params: Record<string, unknown>, svgText?: string): Promise<Shape> {\n  const kernel = getBrepApi()\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (!inputSolid) throw new Error('[api/engrave] input is not BREP')\n\n  const depth = params.depth as number\n  const mode = (params.mode as 'convex' | 'concave' | undefined) ?? 'concave'\n  const text = params.text as string | undefined\n\n  // 1. 创建装饰 solid（文字或 SVG），depth 与 mesh 路径一致\n  let decorationSolid: BrepHandle\n  if (text) {\n    await ensureDefaultFont()\n    const textSize = (params.textSize as number) ?? 10\n    decorationSolid = textToSolid(kernel, text, { fontSize: textSize, depth })\n  } else if (svgText) {\n    decorationSolid = svgToSolid(kernel, svgText, {\n      depth,\n      targetLongSide: (params.svgSize as number) ?? 20,\n    })\n  } else {\n    throw new Error('[api/engrave] neither text nor svg provided')\n  }\n\n  // 2. 居中到原点\n  decorationSolid = centerSolidAtOrigin(kernel, decorationSolid)\n\n  // 3. 旋转 +Z 对齐面法向\n  const worldFaceNormal: Vec3 = (params.faceNormal as Vec3) ?? [0, 0, 1]\n  const rotMatrix = alignZToNormal(worldFaceNormal)\n  const rotated = kernel.transform(decorationSolid, rotMatrix)\n  kernel.release(decorationSolid)\n\n  // 4. 沿法向偏移 + 平移到面中心（凸 offset=+depth/2，凹 offset=-depth/2；加 0.01 避免共面）\n  const worldFaceCenter: Vec3 = (params.faceCenter as Vec3) ?? [0, 0, 0]\n  const localFaceCenter = worldToLocalPosition(worldFaceCenter, getBackends().config.partTransform)\n  const offset = mode === 'convex' ? depth / 2 : -depth / 2\n  const epsilon = 0.01\n  const tx = localFaceCenter[0] + worldFaceNormal[0] * (offset + epsilon)\n  const ty = localFaceCenter[1] + worldFaceNormal[1] * (offset + epsilon)\n  const tz = localFaceCenter[2] + worldFaceNormal[2] * (offset + epsilon)\n  const positioned = kernel.translate(rotated, tx, ty, tz)\n  kernel.release(rotated)\n\n  // 5. 布尔运算（凸=fuse，凹=cut）\n  const isRaised = mode === 'convex'\n  let result: BrepHandle\n  if (isRaised) {\n    result = kernel.fuse(inputSolid, positioned)\n  } else {\n    result = kernel.cut(inputSolid, positioned)\n  }\n  kernel.release(positioned)\n\n  // 5b. cut 可能分裂成多个 solid（compound），用 fuseAll 合并回单一 solid\n  try {\n    const subSolids = kernel.getSubShapes(result, 'solid')\n    if (subSolids.length > 1) {\n      const fused = kernel.fuseAll(subSolids)\n      for (const s of subSolids) {\n        try { kernel.release(s) } catch { /* 已释放 */ }\n      }\n      try { kernel.release(result) } catch { /* 已释放 */ }\n      result = fused\n    }\n  } catch {\n    // getSubShapes 失败说明结果不是 compound，无需处理\n  }\n\n  return fromBrep(solidToShape(kernel, result), { solid: result })\n}\n\n/** 解析 SVG 资产引用（AssetRef → SVG 文本），两条路径共享；无 svg 返回 undefined。 */\nasync function resolveEngraveSvg(params: Record<string, unknown>): Promise<string | undefined> {\n  return params.svg !== undefined && params.svg !== null\n    ? await resolveSvgArg(params.svg, { assets: getBackends().assets as AssetResolver | undefined })\n    : undefined\n}\n\n/**\n * 在几何表面雕刻文字或 SVG（文字分支与 logo 分支都可用）。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name engrave\n * @returns Shape 雕刻后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param params.mode - 雕刻方式：concave 凹陷（减法）/ convex 凸出（加法）。type:'concave' | 'convex' 默认 'concave'\n * @param params.depth - 深度 / 凸出高度（mm）。type:number 默认 0\n * @param params.text - 文字内容（与 svg 二选一）。type:string\n * @param params.textSize - 字号（mm）。type:number 默认 10\n * @param params.svg - SVG 资产引用（与 text 二选一；经 cad.asset 解析）。type:string\n * @param params.svgSize - SVG 长边目标尺寸。type:number\n * @param params.faceCenter - 面位置（绝对坐标）。type:[x,y,z] 默认 [0,0,0]\n * @param params.faceNormal - 面法向。type:[x,y,z] 默认 [0,0,1]\n * @note 早期 logo 分支用 `svgText`（整份 XML 拷贝 + `svgSize` 文本导出丢失，往返失真）；现已改为 `svg` 资产引用，`engravingType` 冗余键已移除。faceCenter/faceNormal 目前是绝对坐标快照。\n * @example\n * const p = await cad.engrave(part0, { mode: 'concave', depth: 2, text: 'Hello', textSize: 10, faceCenter: [0, 0, 0], faceNormal: [0, 0, -1] })\n  */\nexport const engrave = defineOp({\n  mesh: async (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/engrave] no input geometry')\n    assertEngraveParams(params)\n    const svgText = await resolveEngraveSvg(params)\n    // mesh 路径\n    const faceCenter: Vec3 = (params.faceCenter as Vec3) ?? [0, 0, 0]\n    const faceNormal: Vec3 = (params.faceNormal as Vec3) ?? [0, 0, 1]\n    const { naturalWidth, naturalHeight } = svgText ? parseSvgNaturalSize(svgText) : { naturalWidth: 0, naturalHeight: 0 }\n    const hasText = !!(params.text as string | undefined)\n\n    return cad.engrave(input, {\n      mode: (params.mode as 'convex' | 'concave' | undefined) ?? 'concave',\n      depth: params.depth as number,\n      face: { center: faceCenter, normal: faceNormal },\n      text: hasText ? (params.text as string) : undefined,\n      textSize: params.textSize as number | undefined,\n      svg: svgText,\n      svgNaturalWidth: naturalWidth,\n      svgNaturalHeight: naturalHeight,\n      svgSize: params.svgSize as number | undefined,\n    })\n  },\n  brep: async (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/engrave] no input geometry')\n    assertEngraveParams(params)\n    const svgText = await resolveEngraveSvg(params)\n    return engraveBrepPath(input, params, svgText)\n  },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}
+{"version":3,"file":"engrave.js","sourceRoot":"","sources":["../../src/api/engrave.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api engrave — 雕刻库函数\n *\n *\n * dispatchPath 静态判定 brep/mesh。\n * BREP 路径：textToSolid/svgToSolid + boolean（cut/fuse）。\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { AssetResolver } from '../cad-runtime/ports'\n// B3 correction (2026-10-06): no library-face cad aggregate — import the impl from its own module.\nimport * as meshEngrave from '../mesh/engrave'\nimport { parseSvgNaturalSize } from '../primitives/parse-svg-size'\nimport { textToSolid } from '../brep/text/text-to-solid'\nimport { svgToSolid } from '../brep/svg/svg-to-solid'\nimport { ensureDefaultFont } from '../brep/text/fontRegistry'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getSolidBoundingBox } from '../brep/brep-utils'\nimport { resolveSvgArg } from './internal/svg-asset-resolver'\nimport { getBackends } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, brepOf } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { assertPositiveNumber } from './assert'\n\n// ── per-op 参数自校验（Phase 2.2；api 层被直接 import 时的防御层） ──\n\n/**\n * Validate engrave parameters: at least one of `text` or `svg` must be\n * provided, and `depth` (if provided) must be a positive number.\n * @param params - the raw engrave operation parameters.\n */\nexport function assertEngraveParams(params: Record<string, unknown>): void {\n  const hasText = params.text !== undefined && params.text !== null && params.text !== ''\n  const hasSvg = params.svg !== undefined && params.svg !== null\n  if (!hasText && !hasSvg) {\n    throw new Error('[api/engrave] requires either \"text\" or \"svg\"')\n  }\n  if (params.depth !== undefined && params.depth !== null) {\n    assertPositiveNumber(params.depth, 'engrave.depth')\n  }\n}\n\n/** 世界坐标 → BREP solid 局部坐标。 */\nfunction worldToLocalPosition(\n  worldPos: Vec3,\n  partTransform: { position?: [number, number, number] } | undefined,\n): Vec3 {\n  const offset = partTransform?.position\n  if (!offset) return worldPos\n  return [\n    worldPos[0] - offset[0],\n    worldPos[1] - offset[1],\n    worldPos[2] - offset[2],\n  ]\n}\n\n/** 计算将 +Z 轴对齐到目标法向量的 3x4 仿射变换矩阵（仅旋转，无平移，Rodrigues 公式）。 */\nfunction alignZToNormal(normal: Vec3): number[] {\n  const [nx, ny, nz] = normal\n  const len = Math.sqrt(nx * nx + ny * ny + nz * nz)\n  if (len < 1e-10) {\n    return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]\n  }\n  const ux = nx / len, uy = ny / len, uz = nz / len\n\n  if (Math.abs(ux) < 1e-10 && Math.abs(uy) < 1e-10) {\n    if (uz > 0) return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]\n    return [1, 0, 0, 0, 0, -1, 0, 0, 0, 0, -1, 0]\n  }\n\n  const s = Math.sqrt(ux * ux + uy * uy)\n  const c = uz\n  const t = 1 - c\n  const ax = -uy / s, ay = ux / s\n\n  return [\n    c + ax * ax * t,  ax * ay * t,    ay * s,  0,\n    ax * ay * t,      c + ay * ay * t, -ax * s, 0,\n    -ay * s,          ax * s,          c,       0,\n  ]\n}\n\n/** 将 solid 居中到原点（基于包围盒中心，与 mesh 路径语义一致）。 */\nfunction centerSolidAtOrigin(kernel: BrepEngineApi, solid: BrepHandle): BrepHandle {\n  const bb = getSolidBoundingBox(kernel, solid)\n  const cx = (bb.min[0] + bb.max[0]) / 2\n  const cy = (bb.min[1] + bb.max[1]) / 2\n  const cz = (bb.min[2] + bb.max[2]) / 2\n  const centered = kernel.translate(solid, -cx, -cy, -cz)\n  kernel.release(solid)\n  return centered\n}\n\n/** BREP 路径：textToSolid/svgToSolid + boolean（cut/fuse）。 */\nasync function engraveBrepPath(input: Shape, params: Record<string, unknown>, svgText?: string): Promise<Shape> {\n  const kernel = getBrepApi()\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (!inputSolid) throw new Error('[api/engrave] input is not BREP')\n\n  const depth = params.depth as number\n  const mode = (params.mode as 'convex' | 'concave' | undefined) ?? 'concave'\n  const text = params.text as string | undefined\n\n  // 1. 创建装饰 solid（文字或 SVG），depth 与 mesh 路径一致\n  let decorationSolid: BrepHandle\n  if (text) {\n    await ensureDefaultFont()\n    const textSize = (params.textSize as number) ?? 10\n    decorationSolid = textToSolid(kernel, text, { fontSize: textSize, depth })\n  } else if (svgText) {\n    decorationSolid = svgToSolid(kernel, svgText, {\n      depth,\n      targetLongSide: (params.svgSize as number) ?? 20,\n    })\n  } else {\n    throw new Error('[api/engrave] neither text nor svg provided')\n  }\n\n  // 2. 居中到原点\n  decorationSolid = centerSolidAtOrigin(kernel, decorationSolid)\n\n  // 3. 旋转 +Z 对齐面法向\n  const worldFaceNormal: Vec3 = (params.faceNormal as Vec3) ?? [0, 0, 1]\n  const rotMatrix = alignZToNormal(worldFaceNormal)\n  const rotated = kernel.transform(decorationSolid, rotMatrix)\n  kernel.release(decorationSolid)\n\n  // 4. 沿法向偏移 + 平移到面中心（凸 offset=+depth/2，凹 offset=-depth/2；加 0.01 避免共面）\n  const worldFaceCenter: Vec3 = (params.faceCenter as Vec3) ?? [0, 0, 0]\n  const localFaceCenter = worldToLocalPosition(worldFaceCenter, getBackends().config.partTransform)\n  const offset = mode === 'convex' ? depth / 2 : -depth / 2\n  const epsilon = 0.01\n  const tx = localFaceCenter[0] + worldFaceNormal[0] * (offset + epsilon)\n  const ty = localFaceCenter[1] + worldFaceNormal[1] * (offset + epsilon)\n  const tz = localFaceCenter[2] + worldFaceNormal[2] * (offset + epsilon)\n  const positioned = kernel.translate(rotated, tx, ty, tz)\n  kernel.release(rotated)\n\n  // 5. 布尔运算（凸=fuse，凹=cut）\n  const isRaised = mode === 'convex'\n  let result: BrepHandle\n  if (isRaised) {\n    result = kernel.fuse(inputSolid, positioned)\n  } else {\n    result = kernel.cut(inputSolid, positioned)\n  }\n  kernel.release(positioned)\n\n  // 5b. cut 可能分裂成多个 solid（compound），用 fuseAll 合并回单一 solid\n  try {\n    const subSolids = kernel.getSubShapes(result, 'solid')\n    if (subSolids.length > 1) {\n      const fused = kernel.fuseAll(subSolids)\n      for (const s of subSolids) {\n        try { kernel.release(s) } catch { /* 已释放 */ }\n      }\n      try { kernel.release(result) } catch { /* 已释放 */ }\n      result = fused\n    }\n  } catch {\n    // getSubShapes 失败说明结果不是 compound，无需处理\n  }\n\n  return fromBrep(solidToShape(kernel, result), { solid: result })\n}\n\n/** 解析 SVG 资产引用（AssetRef → SVG 文本），两条路径共享；无 svg 返回 undefined。 */\nasync function resolveEngraveSvg(params: Record<string, unknown>): Promise<string | undefined> {\n  return params.svg !== undefined && params.svg !== null\n    ? await resolveSvgArg(params.svg, { assets: getBackends().assets as AssetResolver | undefined })\n    : undefined\n}\n\n/**\n * 在几何表面雕刻文字或 SVG（文字分支与 logo 分支都可用）。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name engrave\n * @returns Shape 雕刻后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param params.mode - 雕刻方式：concave 凹陷（减法）/ convex 凸出（加法）。type:'concave' | 'convex' 默认 'concave'\n * @param params.depth - 深度 / 凸出高度（mm）。type:number 默认 0\n * @param params.text - 文字内容（与 svg 二选一）。type:string\n * @param params.textSize - 字号（mm）。type:number 默认 10\n * @param params.svg - SVG 资产引用（与 text 二选一；经 cad.asset 解析）。type:string\n * @param params.svgSize - SVG 长边目标尺寸。type:number\n * @param params.faceCenter - 面位置（绝对坐标）。type:[x,y,z] 默认 [0,0,0]\n * @param params.faceNormal - 面法向。type:[x,y,z] 默认 [0,0,1]\n * @note 早期 logo 分支用 `svgText`（整份 XML 拷贝 + `svgSize` 文本导出丢失，往返失真）；现已改为 `svg` 资产引用，`engravingType` 冗余键已移除。faceCenter/faceNormal 目前是绝对坐标快照。\n * @example\n * const p = await cad.engrave(part0, { mode: 'concave', depth: 2, text: 'Hello', textSize: 10, faceCenter: [0, 0, 0], faceNormal: [0, 0, -1] })\n  */\nexport const engrave = defineOp({\n  mesh: async (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/engrave] no input geometry')\n    assertEngraveParams(params)\n    const svgText = await resolveEngraveSvg(params)\n    // mesh 路径\n    const faceCenter: Vec3 = (params.faceCenter as Vec3) ?? [0, 0, 0]\n    const faceNormal: Vec3 = (params.faceNormal as Vec3) ?? [0, 0, 1]\n    const { naturalWidth, naturalHeight } = svgText ? parseSvgNaturalSize(svgText) : { naturalWidth: 0, naturalHeight: 0 }\n    const hasText = !!(params.text as string | undefined)\n\n    return meshEngrave.engrave(input, {\n      mode: (params.mode as 'convex' | 'concave' | undefined) ?? 'concave',\n      depth: params.depth as number,\n      face: { center: faceCenter, normal: faceNormal },\n      text: hasText ? (params.text as string) : undefined,\n      textSize: params.textSize as number | undefined,\n      svg: svgText,\n      svgNaturalWidth: naturalWidth,\n      svgNaturalHeight: naturalHeight,\n      svgSize: params.svgSize as number | undefined,\n    })\n  },\n  brep: async (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/engrave] no input geometry')\n    assertEngraveParams(params)\n    const svgText = await resolveEngraveSvg(params)\n    return engraveBrepPath(input, params, svgText)\n  },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}

package/dist/api/export-brep.d.ts

@@ -0,0 +1,41 @@
+/**
+ * api exportBrep — BREP 文本导出（平台：occt 专属，普通函数形态）
+ *
+ * @platform occt — 实现直调 occt 原生 `toBREP(shape)`（occt-wasm 有，L1 契约
+ * `brep/engine/primitives.ts` **只有 `fromBREP` 导入侧、没有导出成员**）。
+ *
+ * 为什么不是 `defineOp`：本 op 返回**纯文本**（非 Shape）。`defineOp` 的 brep 包装
+ * （`define-op.ts#wrapBrepOne`）把返回值一律收养为 Shape——字符串会落到
+ * `fromHandle` 并抛 `E_BAD_HANDLE: ... got string`（实测）。数据型 op 走普通函数是
+ * 本仓既有口径（先例：`api/view/view-projection.ts#projectView` 返回 SVG 字符串）。
+ *
+ * 引擎身份**不能**靠 dispatchPath 门控（普通函数不走那条路）⇒ 按
+ * `api/internal/l3-bridge.ts#assertEngineFor` 的既定做法：函数体第一行断言当前
+ * 引擎，触碰内核之前报出与 D11-4 同构的 `E_BREP_UNSUPPORTED`，不补桩、不回退。
+ * （与 dispatchPath 的差异：`assertEngineFor` **不含** D11-3 的 `brep_mock` 豁免——
+ *  mock 句柄不是 occt 句柄，放行只会拿到错形状，故这里如实拦截。）
+ *
+ * §9.5 降级路径（记录在案）：brepkit 的 wasm 面**自带 `toBREP`**
+ * （`api/surface/brepkit-wasm-surface.json` 的 `methods` 含 `toBREP`），只是尚未接进
+ * L1 契约。一旦契约新增导出成员且两侧适配器同时落地，本函数删掉 `assertEngineFor`
+ * 并改走 `getBrepApi()`，该方法即从 C2 转入 C1。
+ */
+import type { Shape } from '../mesh/types.js';
+/**
+ * 导出 BREP 文本（与 `import_brep` 成对的导出侧）。
+ * @group 导出
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name exportBrep
+ * @note 平台 op：仅 occt 引擎（原生 toBREP，L1 契约无对应导出成员）。非 occt 引擎
+ *       执行前报 E_BREP_UNSUPPORTED；brep_mock 不拦截（引擎身份判定读
+ *       `config.brepEngineId`）。返回**纯文本**，由宿主写入 `.brep` 文件；
+ *       经 `import_brep` / L1 `fromBREP` 可无损回读（精确 BREP，非 mesh 回填）。
+ * @returns string OCCT BREP 文本。
+ * @param shape - 目标几何（必须带 BREP 槽；mesh-only 输入报 E_EXPORT_BREP_NO_BREP）。type:Shape required:true
+ * @example
+ * const text = cad.exportBrep(part0)
+ */
+export declare function exportBrep(shape: Shape): string;
+//# sourceMappingURL=export-brep.d.ts.map

package/dist/api/export-brep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-brep.d.ts","sourceRoot":"","sources":["../../src/api/export-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAoB1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAE/C"}

package/dist/api/export-brep.js

@@ -0,0 +1,58 @@
+/**
+ * api exportBrep — BREP 文本导出（平台：occt 专属，普通函数形态）
+ *
+ * @platform occt — 实现直调 occt 原生 `toBREP(shape)`（occt-wasm 有，L1 契约
+ * `brep/engine/primitives.ts` **只有 `fromBREP` 导入侧、没有导出成员**）。
+ *
+ * 为什么不是 `defineOp`：本 op 返回**纯文本**（非 Shape）。`defineOp` 的 brep 包装
+ * （`define-op.ts#wrapBrepOne`）把返回值一律收养为 Shape——字符串会落到
+ * `fromHandle` 并抛 `E_BAD_HANDLE: ... got string`（实测）。数据型 op 走普通函数是
+ * 本仓既有口径（先例：`api/view/view-projection.ts#projectView` 返回 SVG 字符串）。
+ *
+ * 引擎身份**不能**靠 dispatchPath 门控（普通函数不走那条路）⇒ 按
+ * `api/internal/l3-bridge.ts#assertEngineFor` 的既定做法：函数体第一行断言当前
+ * 引擎，触碰内核之前报出与 D11-4 同构的 `E_BREP_UNSUPPORTED`，不补桩、不回退。
+ * （与 dispatchPath 的差异：`assertEngineFor` **不含** D11-3 的 `brep_mock` 豁免——
+ *  mock 句柄不是 occt 句柄，放行只会拿到错形状，故这里如实拦截。）
+ *
+ * §9.5 降级路径（记录在案）：brepkit 的 wasm 面**自带 `toBREP`**
+ * （`api/surface/brepkit-wasm-surface.json` 的 `methods` 含 `toBREP`），只是尚未接进
+ * L1 契约。一旦契约新增导出成员且两侧适配器同时落地，本函数删掉 `assertEngineFor`
+ * 并改走 `getBrepApi()`，该方法即从 C2 转入 C1。
+ */
+import { brepOf } from '../shape.js';
+import { getOcctKernel } from '../occt-kernel/occtKernel.js';
+import { assertEngineFor } from './internal/l3-bridge.js';
+/** BREP 路径：先断言引擎身份 → 借出 brep 句柄 → occt 原生 toBREP 文本。 */
+function exportBrepNative(shape) {
+    assertEngineFor('exportBrep', ['occt']);
+    const handle = brepOf(shape);
+    if (!handle) {
+        throw new Error('E_EXPORT_BREP_NO_BREP: exportBrep input has no BREP handle (mesh-only shape)');
+    }
+    const text = getOcctKernel().toBREP(handle);
+    if (typeof text !== 'string' || text.length === 0) {
+        throw new Error('E_EXPORT_BREP_EMPTY: occt toBREP produced no text');
+    }
+    return text;
+}
+/**
+ * 导出 BREP 文本（与 `import_brep` 成对的导出侧）。
+ * @group 导出
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name exportBrep
+ * @note 平台 op：仅 occt 引擎（原生 toBREP，L1 契约无对应导出成员）。非 occt 引擎
+ *       执行前报 E_BREP_UNSUPPORTED；brep_mock 不拦截（引擎身份判定读
+ *       `config.brepEngineId`）。返回**纯文本**，由宿主写入 `.brep` 文件；
+ *       经 `import_brep` / L1 `fromBREP` 可无损回读（精确 BREP，非 mesh 回填）。
+ * @returns string OCCT BREP 文本。
+ * @param shape - 目标几何（必须带 BREP 槽；mesh-only 输入报 E_EXPORT_BREP_NO_BREP）。type:Shape required:true
+ * @example
+ * const text = cad.exportBrep(part0)
+ */
+export function exportBrep(shape) {
+    return exportBrepNative(shape);
+}
+//# sourceMappingURL=export-brep.js.map

package/dist/api/export-brep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-brep.js","sourceRoot":"","sources":["../../src/api/export-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,wDAAwD;AACxD,SAAS,gBAAgB,CAAC,KAAY;IACpC,eAAe,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAA2B,CAAA;IACtD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAA;IACjG,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC,MAAM,CAAC,MAAe,CAAC,CAAA;IACpD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;IACtE,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAA;AAChC,CAAC","sourcesContent":["/**\n * api exportBrep — BREP 文本导出（平台：occt 专属，普通函数形态）\n *\n * @platform occt — 实现直调 occt 原生 `toBREP(shape)`（occt-wasm 有，L1 契约\n * `brep/engine/primitives.ts` **只有 `fromBREP` 导入侧、没有导出成员**）。\n *\n * 为什么不是 `defineOp`：本 op 返回**纯文本**（非 Shape）。`defineOp` 的 brep 包装\n * （`define-op.ts#wrapBrepOne`）把返回值一律收养为 Shape——字符串会落到\n * `fromHandle` 并抛 `E_BAD_HANDLE: ... got string`（实测）。数据型 op 走普通函数是\n * 本仓既有口径（先例：`api/view/view-projection.ts#projectView` 返回 SVG 字符串）。\n *\n * 引擎身份**不能**靠 dispatchPath 门控（普通函数不走那条路）⇒ 按\n * `api/internal/l3-bridge.ts#assertEngineFor` 的既定做法：函数体第一行断言当前\n * 引擎，触碰内核之前报出与 D11-4 同构的 `E_BREP_UNSUPPORTED`，不补桩、不回退。\n * （与 dispatchPath 的差异：`assertEngineFor` **不含** D11-3 的 `brep_mock` 豁免——\n *  mock 句柄不是 occt 句柄，放行只会拿到错形状，故这里如实拦截。）\n *\n * §9.5 降级路径（记录在案）：brepkit 的 wasm 面**自带 `toBREP`**\n * （`api/surface/brepkit-wasm-surface.json` 的 `methods` 含 `toBREP`），只是尚未接进\n * L1 契约。一旦契约新增导出成员且两侧适配器同时落地，本函数删掉 `assertEngineFor`\n * 并改走 `getBrepApi()`，该方法即从 C2 转入 C1。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { brepOf } from '../shape'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\nimport { assertEngineFor } from './internal/l3-bridge'\n\n/** BREP 路径：先断言引擎身份 → 借出 brep 句柄 → occt 原生 toBREP 文本。 */\nfunction exportBrepNative(shape: Shape): string {\n  assertEngineFor('exportBrep', ['occt'])\n  const handle = brepOf(shape) as BrepHandle | undefined\n  if (!handle) {\n    throw new Error('E_EXPORT_BREP_NO_BREP: exportBrep input has no BREP handle (mesh-only shape)')\n  }\n  const text = getOcctKernel().toBREP(handle as never)\n  if (typeof text !== 'string' || text.length === 0) {\n    throw new Error('E_EXPORT_BREP_EMPTY: occt toBREP produced no text')\n  }\n  return text\n}\n\n/**\n * 导出 BREP 文本（与 `import_brep` 成对的导出侧）。\n * @group 导出\n * @inputs 1\n * @async false\n * @qual ok\n * @name exportBrep\n * @note 平台 op：仅 occt 引擎（原生 toBREP，L1 契约无对应导出成员）。非 occt 引擎\n *       执行前报 E_BREP_UNSUPPORTED；brep_mock 不拦截（引擎身份判定读\n *       `config.brepEngineId`）。返回**纯文本**，由宿主写入 `.brep` 文件；\n *       经 `import_brep` / L1 `fromBREP` 可无损回读（精确 BREP，非 mesh 回填）。\n * @returns string OCCT BREP 文本。\n * @param shape - 目标几何（必须带 BREP 槽；mesh-only 输入报 E_EXPORT_BREP_NO_BREP）。type:Shape required:true\n * @example\n * const text = cad.exportBrep(part0)\n */\nexport function exportBrep(shape: Shape): string {\n  return exportBrepNative(shape)\n}\n"]}

package/dist/api/export-stl.d.ts

@@ -0,0 +1,50 @@
+/**
+ * api exportStl — STL 导出（中立 op：纯数据序列化，无内核调用）
+ *
+ * 中立性的判据（方案 §4.4 决策树）：实现**不触达任何引擎** —— 它只读 faijs Shape
+ * 自带的三角载荷（`positions` / `indices`），不 import `occt-kernel/*` 或
+ * `brepkit-kernel/*`。mesh 链路与 brep 链路的 Shape 都带该载荷（brep 侧由
+ * `solidToShape` 即时三角化填好），故两条链路同一份实现，无引擎分支。
+ *
+ * 为什么不是平台 op：occt-wasm 有原生 `exportStl`，但本仓的 BREP 三角化统一走
+ * L1 `meshShape`（`brep/brep-ops.ts` 的 `solidToShape`）——Shape 上的载荷就是当前
+ * 用户看到的 mesh（规则 1）。走原生 `exportStl` 会**二次三角化**，产出与显示/拓扑
+ * 不一致的第二份 mesh。这里复用现有唯一序列化器
+ * `brep/export/stl.ts#buildStlBufferFromMesh`（宿主导出链同一真值来源）。
+ *
+ * 与既有能力的分工（方案 §4.5 去重表）：`import_brep` / `import_step` 是**导入**侧；
+ * 本 op 是导出侧，与宿主 `exportModel('stl')` 同一序列化器，脚本面因此首次拿到
+ * 「导入 ↔ 导出」成对能力。
+ */
+import type { Shape } from '../mesh/types.js';
+/** `cad.exportStl` 选项。 */
+export interface ExportStlOptions {
+    /**
+     * `true` → 返回 **ASCII** STL 文本；缺省/`false` → 返回 **binary** STL 字节
+     * （`Uint8Array`，84 + 50×三角形数 字节）。
+     */
+    ascii?: boolean;
+    /** 实体名（ASCII 形态的 `solid <name>` / binary 形态的 80 字节头；缺省 'Faicad STL'）。 */
+    name?: string;
+}
+/**
+ * 导出 STL（二进制 / ASCII 双形态）。
+ * @group 导出
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name exportStl
+ * @note 中立 op：只序列化 Shape 自带的三角载荷（brep 与 mesh 链路同一份实现），
+ *       不走原生二次三角化，产物与显示 mesh 逐三角形一致。空 mesh（如
+ *       `cad.halfSpace` 产的无界体）显式报 E_EXPORT_STL_EMPTY，不返回空文件。
+ *       返回值是**纯数据**（二进制 `Uint8Array` 或 ASCII 文本），由宿主写入文件。
+ * @returns Uint8Array 二进制 STL 字节；`options.ascii === true` 时返回 ASCII 文本 string。
+ * @param shape - 目标几何（brep 或 mesh 链路的 Shape）。type:Shape required:true
+ * @param options.ascii - true = ASCII STL 文本，缺省 = 二进制。type:boolean
+ * @param options.name - 实体名（缺省 'Faicad STL'）。type:string
+ * @example
+ * const bytes = cad.exportStl(part0)
+ * const text = cad.exportStl(part0, { ascii: true, name: 'bracket' })
+ */
+export declare function exportStl(shape: Shape, options?: ExportStlOptions): Uint8Array | string;
+//# sourceMappingURL=export-stl.d.ts.map

package/dist/api/export-stl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-stl.d.ts","sourceRoot":"","sources":["../../src/api/export-stl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAG1C,0BAA0B;AAC1B,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAmED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,UAAU,GAAG,MAAM,CAOvF"}

package/dist/api/export-stl.js

@@ -0,0 +1,99 @@
+/**
+ * api exportStl — STL 导出（中立 op：纯数据序列化，无内核调用）
+ *
+ * 中立性的判据（方案 §4.4 决策树）：实现**不触达任何引擎** —— 它只读 faijs Shape
+ * 自带的三角载荷（`positions` / `indices`），不 import `occt-kernel/*` 或
+ * `brepkit-kernel/*`。mesh 链路与 brep 链路的 Shape 都带该载荷（brep 侧由
+ * `solidToShape` 即时三角化填好），故两条链路同一份实现，无引擎分支。
+ *
+ * 为什么不是平台 op：occt-wasm 有原生 `exportStl`，但本仓的 BREP 三角化统一走
+ * L1 `meshShape`（`brep/brep-ops.ts` 的 `solidToShape`）——Shape 上的载荷就是当前
+ * 用户看到的 mesh（规则 1）。走原生 `exportStl` 会**二次三角化**，产出与显示/拓扑
+ * 不一致的第二份 mesh。这里复用现有唯一序列化器
+ * `brep/export/stl.ts#buildStlBufferFromMesh`（宿主导出链同一真值来源）。
+ *
+ * 与既有能力的分工（方案 §4.5 去重表）：`import_brep` / `import_step` 是**导入**侧；
+ * 本 op 是导出侧，与宿主 `exportModel('stl')` 同一序列化器，脚本面因此首次拿到
+ * 「导入 ↔ 导出」成对能力。
+ */
+import { buildStlBufferFromMesh } from '../brep/export/stl.js';
+/** 校验输入 Shape 带可用的三角载荷。 */
+function meshOf(shape) {
+    const positions = shape?.positions;
+    const indices = shape?.indices;
+    if (!positions || !indices) {
+        throw new Error('E_EXPORT_STL_NO_MESH: exportStl requires a shape carrying mesh payload');
+    }
+    if (indices.length === 0) {
+        throw new Error('E_EXPORT_STL_EMPTY: shape has no triangles to export');
+    }
+    return { positions, indices };
+}
+/** 单位化叉积法向（退化三角形给 0 向量，与二进制形态同一规则）。 */
+function facetNormal(positions, ia, ib, ic) {
+    const ax = positions[ia * 3];
+    const ay = positions[ia * 3 + 1];
+    const az = positions[ia * 3 + 2];
+    const ux = positions[ib * 3] - ax;
+    const uy = positions[ib * 3 + 1] - ay;
+    const uz = positions[ib * 3 + 2] - az;
+    const vx = positions[ic * 3] - ax;
+    const vy = positions[ic * 3 + 1] - ay;
+    const vz = positions[ic * 3 + 2] - az;
+    let nx = uy * vz - uz * vy;
+    let ny = uz * vx - ux * vz;
+    let nz = ux * vy - uy * vx;
+    const len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    if (len > 0) {
+        nx /= len;
+        ny /= len;
+        nz /= len;
+    }
+    return [nx, ny, nz];
+}
+/** ASCII STL 文本（与二进制形态同一批三角形、同一法向规则；坐标以 mm 写出）。 */
+function asciiStl(positions, indices, name) {
+    const out = [`solid ${name}`];
+    for (let i = 0; i < indices.length; i += 3) {
+        const ia = indices[i];
+        const ib = indices[i + 1];
+        const ic = indices[i + 2];
+        const [nx, ny, nz] = facetNormal(positions, ia, ib, ic);
+        out.push(`  facet normal ${nx} ${ny} ${nz}`, '    outer loop');
+        for (const v of [ia, ib, ic]) {
+            out.push(`      vertex ${positions[v * 3]} ${positions[v * 3 + 1]} ${positions[v * 3 + 2]}`);
+        }
+        out.push('    endloop', '  endfacet');
+    }
+    out.push(`endsolid ${name}`);
+    return out.join('\n');
+}
+/**
+ * 导出 STL（二进制 / ASCII 双形态）。
+ * @group 导出
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name exportStl
+ * @note 中立 op：只序列化 Shape 自带的三角载荷（brep 与 mesh 链路同一份实现），
+ *       不走原生二次三角化，产物与显示 mesh 逐三角形一致。空 mesh（如
+ *       `cad.halfSpace` 产的无界体）显式报 E_EXPORT_STL_EMPTY，不返回空文件。
+ *       返回值是**纯数据**（二进制 `Uint8Array` 或 ASCII 文本），由宿主写入文件。
+ * @returns Uint8Array 二进制 STL 字节；`options.ascii === true` 时返回 ASCII 文本 string。
+ * @param shape - 目标几何（brep 或 mesh 链路的 Shape）。type:Shape required:true
+ * @param options.ascii - true = ASCII STL 文本，缺省 = 二进制。type:boolean
+ * @param options.name - 实体名（缺省 'Faicad STL'）。type:string
+ * @example
+ * const bytes = cad.exportStl(part0)
+ * const text = cad.exportStl(part0, { ascii: true, name: 'bracket' })
+ */
+export function exportStl(shape, options) {
+    const { positions, indices } = meshOf(shape);
+    const name = options?.name ?? 'Faicad STL';
+    // 坐标一律以 mm 写出（与宿主 exportModel('stl') 的 unit 语义一致——
+    // 单位换算在宿主侧按当前文档单位完成，本 op 不做缩放）。
+    if (options?.ascii === true)
+        return asciiStl(positions, indices, name);
+    return new Uint8Array(buildStlBufferFromMesh(positions, indices, name));
+}
+//# sourceMappingURL=export-stl.js.map

package/dist/api/export-stl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-stl.js","sourceRoot":"","sources":["../../src/api/export-stl.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api exportStl — STL 导出（中立 op：纯数据序列化，无内核调用）\n *\n * 中立性的判据（方案 §4.4 决策树）：实现**不触达任何引擎** —— 它只读 faijs Shape\n * 自带的三角载荷（`positions` / `indices`），不 import `occt-kernel/*` 或\n * `brepkit-kernel/*`。mesh 链路与 brep 链路的 Shape 都带该载荷（brep 侧由\n * `solidToShape` 即时三角化填好），故两条链路同一份实现，无引擎分支。\n *\n * 为什么不是平台 op：occt-wasm 有原生 `exportStl`，但本仓的 BREP 三角化统一走\n * L1 `meshShape`（`brep/brep-ops.ts` 的 `solidToShape`）——Shape 上的载荷就是当前\n * 用户看到的 mesh（规则 1）。走原生 `exportStl` 会**二次三角化**，产出与显示/拓扑\n * 不一致的第二份 mesh。这里复用现有唯一序列化器\n * `brep/export/stl.ts#buildStlBufferFromMesh`（宿主导出链同一真值来源）。\n *\n * 与既有能力的分工（方案 §4.5 去重表）：`import_brep` / `import_step` 是**导入**侧；\n * 本 op 是导出侧，与宿主 `exportModel('stl')` 同一序列化器，脚本面因此首次拿到\n * 「导入 ↔ 导出」成对能力。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { buildStlBufferFromMesh } from '../brep/export/stl'\n\n/** `cad.exportStl` 选项。 */\nexport interface ExportStlOptions {\n  /**\n   * `true` → 返回 **ASCII** STL 文本；缺省/`false` → 返回 **binary** STL 字节\n   * （`Uint8Array`，84 + 50×三角形数 字节）。\n   */\n  ascii?: boolean\n  /** 实体名（ASCII 形态的 `solid <name>` / binary 形态的 80 字节头；缺省 'Faicad STL'）。 */\n  name?: string\n}\n\n/** 校验输入 Shape 带可用的三角载荷。 */\nfunction meshOf(shape: Shape): { positions: Float32Array; indices: Uint32Array } {\n  const positions = shape?.positions\n  const indices = shape?.indices\n  if (!positions || !indices) {\n    throw new Error('E_EXPORT_STL_NO_MESH: exportStl requires a shape carrying mesh payload')\n  }\n  if (indices.length === 0) {\n    throw new Error('E_EXPORT_STL_EMPTY: shape has no triangles to export')\n  }\n  return { positions, indices }\n}\n\n/** 单位化叉积法向（退化三角形给 0 向量，与二进制形态同一规则）。 */\nfunction facetNormal(\n  positions: Float32Array,\n  ia: number,\n  ib: number,\n  ic: number,\n): [number, number, number] {\n  const ax = positions[ia * 3]!\n  const ay = positions[ia * 3 + 1]!\n  const az = positions[ia * 3 + 2]!\n  const ux = positions[ib * 3]! - ax\n  const uy = positions[ib * 3 + 1]! - ay\n  const uz = positions[ib * 3 + 2]! - az\n  const vx = positions[ic * 3]! - ax\n  const vy = positions[ic * 3 + 1]! - ay\n  const vz = positions[ic * 3 + 2]! - az\n  let nx = uy * vz - uz * vy\n  let ny = uz * vx - ux * vz\n  let nz = ux * vy - uy * vx\n  const len = Math.sqrt(nx * nx + ny * ny + nz * nz)\n  if (len > 0) {\n    nx /= len\n    ny /= len\n    nz /= len\n  }\n  return [nx, ny, nz]\n}\n\n/** ASCII STL 文本（与二进制形态同一批三角形、同一法向规则；坐标以 mm 写出）。 */\nfunction asciiStl(\n  positions: Float32Array,\n  indices: Uint32Array,\n  name: string,\n): string {\n  const out: string[] = [`solid ${name}`]\n  for (let i = 0; i < indices.length; i += 3) {\n    const ia = indices[i]!\n    const ib = indices[i + 1]!\n    const ic = indices[i + 2]!\n    const [nx, ny, nz] = facetNormal(positions, ia, ib, ic)\n    out.push(`  facet normal ${nx} ${ny} ${nz}`, '    outer loop')\n    for (const v of [ia, ib, ic]) {\n      out.push(\n        `      vertex ${positions[v * 3]!} ${positions[v * 3 + 1]!} ${positions[v * 3 + 2]!}`,\n      )\n    }\n    out.push('    endloop', '  endfacet')\n  }\n  out.push(`endsolid ${name}`)\n  return out.join('\\n')\n}\n\n/**\n * 导出 STL（二进制 / ASCII 双形态）。\n * @group 导出\n * @inputs 1\n * @async false\n * @qual ok\n * @name exportStl\n * @note 中立 op：只序列化 Shape 自带的三角载荷（brep 与 mesh 链路同一份实现），\n *       不走原生二次三角化，产物与显示 mesh 逐三角形一致。空 mesh（如\n *       `cad.halfSpace` 产的无界体）显式报 E_EXPORT_STL_EMPTY，不返回空文件。\n *       返回值是**纯数据**（二进制 `Uint8Array` 或 ASCII 文本），由宿主写入文件。\n * @returns Uint8Array 二进制 STL 字节；`options.ascii === true` 时返回 ASCII 文本 string。\n * @param shape - 目标几何（brep 或 mesh 链路的 Shape）。type:Shape required:true\n * @param options.ascii - true = ASCII STL 文本，缺省 = 二进制。type:boolean\n * @param options.name - 实体名（缺省 'Faicad STL'）。type:string\n * @example\n * const bytes = cad.exportStl(part0)\n * const text = cad.exportStl(part0, { ascii: true, name: 'bracket' })\n */\nexport function exportStl(shape: Shape, options?: ExportStlOptions): Uint8Array | string {\n  const { positions, indices } = meshOf(shape)\n  const name = options?.name ?? 'Faicad STL'\n  // 坐标一律以 mm 写出（与宿主 exportModel('stl') 的 unit 语义一致——\n  // 单位换算在宿主侧按当前文档单位完成，本 op 不做缩放）。\n  if (options?.ascii === true) return asciiStl(positions, indices, name)\n  return new Uint8Array(buildStlBufferFromMesh(positions, indices, name))\n}\n"]}

package/dist/api/extrude.d.ts

@@ -2,24 +2,21 @@
  * api extrude — `cad.extrude`（平台 parity op，BREP-only）
  *
  * 归属（分层红线）：`cad.extrude` 是「面 → 棱柱」的**平台** op，FCStd Pad/Pocket
- * 链路与 TS 面共用它（docs/plans/2026-09-15-fcstd-to-faijs-port-plan.md M4.6：
- * 「原 `cad.fai_extrude` 路线废弃」）。up-to（拉伸到面 / 到支持体端面）属
+ * 链路与 TS 面共用它（原 `cad.fai_extrude` 路线废弃）。up-to（拉伸到面 / 到支持体端面）属
  * CadQuery `until=` 同族语义，因此落在**本 op**；`fai_extrude`（`fai_` 前缀的
  * faijs 扩展 op，与 fai_drill / fai_split 同族）不得承载它。
  *
- * 为什么是手写 op 而不是继续用生成投影：生成投影
- * `compatOp(projectBrepOp('extrude', ['face','height'], 'A', vendoredExtrude))`
- * 有两个硬约束——
+ * 为什么是手写 op 而不是继续用生成投影：生成投影是一条 1:1 转发通道
+ * （`defineOp({ brep: __own_* })` 直连 api/brep-operations/ 的源函数），有两个硬约束——
  * ① 参数表只有位置形参；D11 归一化只在「单 plain-object 形态」下按 params 表
  *    映射（api/internal/dual-form-args.ts），`(face, { upTo })` 属位置形态 →
- *    原样喂给 vendored extrude → 报错，无法表达对象形态；
- * ② compatOp 的入参先经 `borrowDeep` 借成 brepjs 视图（api/internal/compat-op.ts），
- *    在那一层 `brepOf()` 取不到 → 依赖 faceRef / brepOf / 内核直调的 up-to 实现
- *    必然走空（同 AGENTS.md 记录的「compatOp 自动提升边界」）。
+ *    原样喂给 compat extrude → 报错，无法表达对象形态；
+ * ② 生成投影没有 faijs 侧入参解析挂点，只把实参原样转发给源函数 → 依赖 faceRef 解析 /
+ *    内核直调（extrudeUpToSolid）的 up-to 实现无法在生成投影里承载，落回本手写模块。
  * 先例：arg-spec 的 `fillet` 条目（faijs 侧由手写 dual-op 覆盖，生成模块符号为
  * 孤儿 by design）。
  *
- * 长度形态**委托给生成投影**（`projectedExtrude`）：vendored 仍是唯一拉伸引擎，
+ * 长度形态**委托给生成投影**（`projectedExtrude`）：compat 投影仍是唯一拉伸引擎，
  * 既有 `cad.extrude(face, [x,y,z])` 语义零漂移。
  */
 import type { Shape, Vec3 } from '../mesh/types.js';
@@ -54,7 +51,7 @@ export interface ExtrudeOptions {
  * 沿 normal 拉伸几何（面 → 棱柱）。
  *
  * up-to 模式（`upTo`）与长度模式（`length`）二选一；长度模式委托生成投影
- * （vendored extrude 为唯一引擎），up-to 模式走半空间组合。
+ * （brepjs extrude 为唯一引擎），up-to 模式走半空间组合。
  *
  * **网格链**（`meshEngines: ['brepkit']`，方案 2026-10-01 §4 Phase 3）：输入是
  * `cad.sketchOnFace` 在网格实体识别面上铺出的网格链面时，本 op 沿同一份方向语义

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

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

package/dist/api/extrude.js

@@ -2,24 +2,21 @@
  * api extrude — `cad.extrude`（平台 parity op，BREP-only）
  *
  * 归属（分层红线）：`cad.extrude` 是「面 → 棱柱」的**平台** op，FCStd Pad/Pocket
- * 链路与 TS 面共用它（docs/plans/2026-09-15-fcstd-to-faijs-port-plan.md M4.6：
- * 「原 `cad.fai_extrude` 路线废弃」）。up-to（拉伸到面 / 到支持体端面）属
+ * 链路与 TS 面共用它（原 `cad.fai_extrude` 路线废弃）。up-to（拉伸到面 / 到支持体端面）属
  * CadQuery `until=` 同族语义，因此落在**本 op**；`fai_extrude`（`fai_` 前缀的
  * faijs 扩展 op，与 fai_drill / fai_split 同族）不得承载它。
  *
- * 为什么是手写 op 而不是继续用生成投影：生成投影
- * `compatOp(projectBrepOp('extrude', ['face','height'], 'A', vendoredExtrude))`
- * 有两个硬约束——
+ * 为什么是手写 op 而不是继续用生成投影：生成投影是一条 1:1 转发通道
+ * （`defineOp({ brep: __own_* })` 直连 api/brep-operations/ 的源函数），有两个硬约束——
  * ① 参数表只有位置形参；D11 归一化只在「单 plain-object 形态」下按 params 表
  *    映射（api/internal/dual-form-args.ts），`(face, { upTo })` 属位置形态 →
- *    原样喂给 vendored extrude → 报错，无法表达对象形态；
- * ② compatOp 的入参先经 `borrowDeep` 借成 brepjs 视图（api/internal/compat-op.ts），
- *    在那一层 `brepOf()` 取不到 → 依赖 faceRef / brepOf / 内核直调的 up-to 实现
- *    必然走空（同 AGENTS.md 记录的「compatOp 自动提升边界」）。
+ *    原样喂给 compat extrude → 报错，无法表达对象形态；
+ * ② 生成投影没有 faijs 侧入参解析挂点，只把实参原样转发给源函数 → 依赖 faceRef 解析 /
+ *    内核直调（extrudeUpToSolid）的 up-to 实现无法在生成投影里承载，落回本手写模块。
  * 先例：arg-spec 的 `fillet` 条目（faijs 侧由手写 dual-op 覆盖，生成模块符号为
  * 孤儿 by design）。
  *
- * 长度形态**委托给生成投影**（`projectedExtrude`）：vendored 仍是唯一拉伸引擎，
+ * 长度形态**委托给生成投影**（`projectedExtrude`）：compat 投影仍是唯一拉伸引擎，
  * 既有 `cad.extrude(face, [x,y,z])` 语义零漂移。
  */
 import { extrude as projectedExtrude } from './generated/operations.js';
@@ -445,7 +442,7 @@ function extrudeMeshChain(input, params) {
  * 沿 normal 拉伸几何（面 → 棱柱）。
  *
  * up-to 模式（`upTo`）与长度模式（`length`）二选一；长度模式委托生成投影
- * （vendored extrude 为唯一引擎），up-to 模式走半空间组合。
+ * （brepjs extrude 为唯一引擎），up-to 模式走半空间组合。
  *
  * **网格链**（`meshEngines: ['brepkit']`，方案 2026-10-01 §4 Phase 3）：输入是
  * `cad.sketchOnFace` 在网格实体识别面上铺出的网格链面时，本 op 沿同一份方向语义
@@ -506,13 +503,13 @@ export const extrude = defineOp({
                 roleTable: new Map([[origin, extrudeConstructRoles(kernel, clipped, normal.toArray())]]),
             });
         }
-        // 长度形态：委托生成投影（生成投影自带借入 / Result 翻转 / 收养）
+        // 长度形态：委托生成投影（生成投影自带 Result 翻转 / adopt 收养）
         const sign = o.mode === 'backward' ? -1 : 1;
         const v = [normal.x * o.length * sign, normal.y * o.length * sign, normal.z * o.length * sign];
         let result;
-        // GOTCHA：projectedExtrude 是 occt-gated 的 compat op（vendored brepjs 借入），
+        // GOTCHA：projectedExtrude 是 occt-gated 的生成投影 op，
         // 在 brepkit 引擎下执行前即抛 E_BREP_UNSUPPORTED。brepkit 有原生 L1 extrude
-        // （face→solid），直接走 kernel.extrude——与 revolve.ts 同路径（不经过 vendored 借入）。
+        // （face→solid），直接走 kernel.extrude——与 revolve.ts 同路径（不经生成投影）。
         // occt 路径保持 projectedExtrude 不变，不回退既有几何/命名行为。
         if (getBackends().config.brepEngineId === 'brepkit') {
             const kernel = getBrepApi();