@faicad/faijs 0.29.3 → 0.29.5

package/dist/api/appearance.d.ts

@@ -0,0 +1,138 @@
+/**
+ * api/appearance — faijs PBR 外观规格（颜色/材质/透明度）权威类型与 Shape 方法
+ *
+ * 设计文档：docs/plans/2026-10-05-faijs-pbr-appearance-api-design.md（v2）
+ *
+ * 定位：
+ * - 外观设置**不是 op**（不进 defineOp/api-namespace/args-schema），是 Shape
+ *   实例方法（`box1.setColor(...)`，复用 `asm1.solve()` 的成员调用语句形态）。
+ * - `PbrAppearance` 引擎无关、JSON 可序列化，随 Shape 走 mesh/brep 双链路
+ *   （`Shape.appearance`），编辑器/查看器只读字段，不依赖方法。
+ * - 本文件零依赖（不 import THREE / occt / store）；唯一 import 是 mesh/types
+ *   的 `Shape` 类型（type-only），mesh/types 亦只 type-import 本文件的类型，
+ *   两者为类型环、无运行时环（值依赖单向：shape.ts → api/appearance.ts）。
+ *
+ * 颜色约定：
+ * - 内部归一形态：`color: [r, g, b]`（sRGB，0–1）；`opacity` 是透明度的唯一
+ *   权威字段（0–1）。
+ * - 输入接受 hex（#rgb / #rrggbb / #rrggbbaa）与数组（[r,g,b] / [r,g,b,a]）；
+ *   `#rrggbbaa` / 数组第 4 分量的 alpha 等价于 `opacity`（显式 setOpacity 后
+ *   写入的 opacity 优先于后续无 alpha 的 setColor 推导，见 setColor 注释）。
+ * - CSS 颜色名：P1 不支持（抛错），由宿主或后续版本扩展。
+ */
+import type { Shape } from '../mesh/types.js';
+/** 颜色输入：hex（#rgb/#rrggbb/#rrggbbaa）或 sRGB 0–1 数组（[r,g,b] / [r,g,b,a]）。 */
+export type PbrColor = string | [number, number, number] | [number, number, number, number];
+/** glTF 透明度约定（与 3d_editor MaterialAppearance.alphaMode 对齐）。 */
+export type PbrAlphaMode = 'OPAQUE' | 'MASK' | 'BLEND';
+/**
+ * faijs PBR 外观规格 —— 引擎无关、JSON 可序列化、随 Shape 走双链路。
+ *
+ * 全字段可选：未设置字段 = 继承上游 / 宿主默认，不隐式清零。
+ * 归一形态约定：`color` 为 [r,g,b]（sRGB 0–1）数组；`opacity`（0–1）为
+ * 透明度唯一权威字段（color 的 aa 分量在 set 时归一为 opacity）。
+ */
+export interface PbrAppearance {
+    /** 基色（sRGB 0–1）。 */
+    color?: [number, number, number];
+    /** 透明度 0–1。 */
+    opacity?: number;
+    /** 金属度 0–1；粗糙度 0–1。 */
+    metalness?: number;
+    roughness?: number;
+    /** 自发光：颜色 + 强度（>0 时启用，默认 1）。 */
+    emissive?: [number, number, number];
+    emissiveIntensity?: number;
+    /** 透射/玻璃。 */
+    transmission?: number;
+    thickness?: number;
+    ior?: number;
+    attenuationColor?: [number, number, number];
+    attenuationDistance?: number;
+    /** 清漆。 */
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+    /** 织物/丝绒。 */
+    sheen?: number;
+    sheenColor?: [number, number, number];
+    sheenRoughness?: number;
+    /** 拉丝金属。 */
+    anisotropy?: number;
+    anisotropyRotation?: number;
+    /** 高光工作流（替代 metalness 工作流）。 */
+    specularIntensity?: number;
+    specularColor?: [number, number, number];
+    /** 环境光强度（IBL 贡献）。 */
+    envMapIntensity?: number;
+    /** 透明度模式：默认 OPAQUE；opacity<1 未显式指定时宿主按 BLEND 处理。 */
+    alphaMode?: PbrAlphaMode;
+    alphaCutoff?: number;
+    /** 双面渲染。 */
+    doubleSided?: boolean;
+    /** 无光照。 */
+    unlit?: boolean;
+}
+/** 材质参数（不含颜色/透明度，`cad` 便捷方法 setMaterial 的入参）。 */
+export type MaterialSpec = Omit<PbrAppearance, 'color' | 'opacity'>;
+/** Shape 外观方法签名（运行时由 attachAppearanceMethods 挂载；纯数据判定不受影响）。 */
+export interface ShapeAppearanceMethods {
+    /** 合并外观：`{...cur, ...spec}`，spec 中 undefined 字段保留旧值。 */
+    setAppearance(spec: PbrAppearance): this;
+    /** 便捷：等价 setAppearance({ color })；#rrggbbaa / [r,g,b,a] 的 alpha 归一为 opacity。 */
+    setColor(color: PbrColor): this;
+    /** 便捷：等价 setAppearance(spec)。 */
+    setMaterial(spec: MaterialSpec): this;
+    /** 便捷：透明度权威字段（0–1）。 */
+    setOpacity(opacity: number): this;
+    /** 读取当前外观（可能 undefined）。 */
+    getAppearance(): Readonly<PbrAppearance> | undefined;
+    /**
+     * 面级设色：把 faceIds 指定的面（面序号契约见 `Shape.faceRanges`，参数化
+     * primitives 才有）写入 `materialGroups`。无面结构（布尔/组合/导入产物）抛
+     * `E_FACE_UNAVAILABLE`；面序号越界抛 `E_FACE_INDEX`。
+     */
+    setFaceColor(faces: number[], color: PbrColor): this;
+    /** 面级材质：等价 setFaceColor 的 material 版本。 */
+    setFaceMaterial(faces: number[], spec: MaterialSpec): this;
+}
+/**
+ * 归一颜色输入 → { rgb, alpha? }。
+ * hex 与 [r,g,b] / [r,g,b,a]（sRGB 0–1）；CSS 颜色名 P1 不支持。
+ * @param color 颜色输入：`#rgb` / `#rrggbb` / `#rrggbbaa`，或 `[r,g,b]` / `[r,g,b,a]`（sRGB 0–1）
+ * @returns 归一后的 sRGB 颜色（0–1）与可选 alpha；带 alpha 的输入在 alpha 通道返回
+ */
+export declare function normalizeColor(color: PbrColor): {
+    rgb: [number, number, number];
+    alpha?: number;
+};
+/**
+ * 合并外观：spec 中 undefined 字段不覆盖旧值。
+ * @param cur 当前外观（可为 undefined）
+ * @param spec 待合并字段（undefined 字段被跳过）
+ * @returns 合并后的外观（新对象；cur 为 undefined 时仅含 spec 非空字段）
+ */
+export declare function mergeAppearance(cur: PbrAppearance | undefined, spec: PbrAppearance): PbrAppearance;
+/**
+ * 把 faceIds 指定的面（面序号 → `Shape.faceRanges` 三角形区间）合并进
+ * `shape.materialGroups`。多次设置同一面 → 外观合并（spec 未设置字段保留旧值）；
+ * 不同面同外观 → 相邻区间合并为一个分组。输出按三角形起始排序。
+ *
+ * 无面结构（`faceRanges` 缺失——布尔/组合/导入产物）抛 `E_FACE_UNAVAILABLE`；
+ * 面序号越界/非整数抛 `E_FACE_INDEX`。
+ * @param shape 目标 Shape（必须携带 faceRanges）
+ * @param faceIds 面序号列表（PbrAppearance 面序契约见 mesh/primitives.ts 各构造点注释）
+ * @param spec 待合并到目标面的外观字段
+ */
+export declare function mergeFaceAppearance(shape: Shape, faceIds: number[], spec: PbrAppearance): void;
+/**
+ * 给 Shape 实例挂载外观方法（幂等：已有 setAppearance 则跳过）。
+ *
+ * 所有产物构造点（solid/curve → fromBrep/fromMeshSolid/fromBrepCurve）统一
+ * 调用本函数，保证 mesh/brep 双链路产物都可用 `box1.setColor(...)`。
+ * 方法**不序列化**（JSON 丢弃函数）；`appearance` 字段随产物跨 worker 传递，
+ * 编辑器/查看器只读字段即可，不依赖方法。
+ * @param shape 产物 Shape 实例（solid/curve 产物）
+ * @returns 挂载后的 shape（类型提升为 `Shape & ShapeAppearanceMethods`；同一实例原地挂载）
+ */
+export declare function attachAppearanceMethods(shape: Shape): Shape & ShapeAppearanceMethods;
+//# sourceMappingURL=appearance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../../src/api/appearance.ts"],"names":[],"mappings":"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"}

package/dist/api/appearance.js

@@ -0,0 +1,230 @@
+/**
+ * api/appearance — faijs PBR 外观规格（颜色/材质/透明度）权威类型与 Shape 方法
+ *
+ * 设计文档：docs/plans/2026-10-05-faijs-pbr-appearance-api-design.md（v2）
+ *
+ * 定位：
+ * - 外观设置**不是 op**（不进 defineOp/api-namespace/args-schema），是 Shape
+ *   实例方法（`box1.setColor(...)`，复用 `asm1.solve()` 的成员调用语句形态）。
+ * - `PbrAppearance` 引擎无关、JSON 可序列化，随 Shape 走 mesh/brep 双链路
+ *   （`Shape.appearance`），编辑器/查看器只读字段，不依赖方法。
+ * - 本文件零依赖（不 import THREE / occt / store）；唯一 import 是 mesh/types
+ *   的 `Shape` 类型（type-only），mesh/types 亦只 type-import 本文件的类型，
+ *   两者为类型环、无运行时环（值依赖单向：shape.ts → api/appearance.ts）。
+ *
+ * 颜色约定：
+ * - 内部归一形态：`color: [r, g, b]`（sRGB，0–1）；`opacity` 是透明度的唯一
+ *   权威字段（0–1）。
+ * - 输入接受 hex（#rgb / #rrggbb / #rrggbbaa）与数组（[r,g,b] / [r,g,b,a]）；
+ *   `#rrggbbaa` / 数组第 4 分量的 alpha 等价于 `opacity`（显式 setOpacity 后
+ *   写入的 opacity 优先于后续无 alpha 的 setColor 推导，见 setColor 注释）。
+ * - CSS 颜色名：P1 不支持（抛错），由宿主或后续版本扩展。
+ */
+// ── 归一化 ──
+/** hex #rgb/#rrggbb/#rrggbbaa → sRGB 0–1（+可选 alpha）。 */
+function parseHexColor(hex) {
+    let h = hex.startsWith('#') ? hex.slice(1) : hex;
+    if (h.length === 3) {
+        h = h.split('').map((c) => c + c).join('');
+    }
+    if (h.length !== 6 && h.length !== 8) {
+        throw new Error(`[faijs/appearance] invalid hex color "${hex}" (expected #rgb/#rrggbb/#rrggbbaa)`);
+    }
+    if (!/^[0-9a-fA-F]+$/.test(h)) {
+        throw new Error(`[faijs/appearance] invalid hex color "${hex}" (non-hex digit)`);
+    }
+    const r = parseInt(h.slice(0, 2), 16) / 255;
+    const g = parseInt(h.slice(2, 4), 16) / 255;
+    const b = parseInt(h.slice(4, 6), 16) / 255;
+    const rgb = [r, g, b];
+    if (h.length === 8)
+        return { rgb, alpha: parseInt(h.slice(6, 8), 16) / 255 };
+    return { rgb };
+}
+function assertComponent01(v, label) {
+    if (v < 0 || v > 1 || !Number.isFinite(v)) {
+        throw new Error(`[faijs/appearance] ${label} must be in 0..1, got ${v}`);
+    }
+}
+/**
+ * 归一颜色输入 → { rgb, alpha? }。
+ * hex 与 [r,g,b] / [r,g,b,a]（sRGB 0–1）；CSS 颜色名 P1 不支持。
+ * @param color 颜色输入：`#rgb` / `#rrggbb` / `#rrggbbaa`，或 `[r,g,b]` / `[r,g,b,a]`（sRGB 0–1）
+ * @returns 归一后的 sRGB 颜色（0–1）与可选 alpha；带 alpha 的输入在 alpha 通道返回
+ */
+export function normalizeColor(color) {
+    if (typeof color === 'string') {
+        if (color.startsWith('#'))
+            return parseHexColor(color);
+        throw new Error(`[faijs/appearance] unsupported color "${color}" (P1: hex #rgb/#rrggbb/#rrggbbaa or [r,g,b] expected; CSS names not supported)`);
+    }
+    const [r, g, b, a] = color;
+    assertComponent01(r, 'color.r');
+    assertComponent01(g, 'color.g');
+    assertComponent01(b, 'color.b');
+    if (a !== undefined) {
+        assertComponent01(a, 'color.a');
+        return { rgb: [r, g, b], alpha: a };
+    }
+    return { rgb: [r, g, b] };
+}
+/**
+ * 合并外观：spec 中 undefined 字段不覆盖旧值。
+ * @param cur 当前外观（可为 undefined）
+ * @param spec 待合并字段（undefined 字段被跳过）
+ * @returns 合并后的外观（新对象；cur 为 undefined 时仅含 spec 非空字段）
+ */
+export function mergeAppearance(cur, spec) {
+    const clean = {};
+    for (const [k, v] of Object.entries(spec)) {
+        if (v !== undefined)
+            clean[k] = v;
+    }
+    return { ...(cur ?? {}), ...clean };
+}
+/** 两外观等价判定（字段级深比较；undefined 视同空对象）。 */
+function sameAppearance(a, b) {
+    const ka = Object.keys(a ?? {}).filter((k) => a[k] !== undefined).sort();
+    const kb = Object.keys(b ?? {}).filter((k) => b[k] !== undefined).sort();
+    if (ka.length !== kb.length)
+        return false;
+    for (const k of ka) {
+        const va = a[k];
+        const vb = b[k];
+        if (Array.isArray(va) || Array.isArray(vb)) {
+            if (!Array.isArray(va) || !Array.isArray(vb) || va.length !== vb.length)
+                return false;
+            for (let i = 0; i < va.length; i++)
+                if (va[i] !== vb[i])
+                    return false;
+        }
+        else if (va !== vb) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 把 faceIds 指定的面（面序号 → `Shape.faceRanges` 三角形区间）合并进
+ * `shape.materialGroups`。多次设置同一面 → 外观合并（spec 未设置字段保留旧值）；
+ * 不同面同外观 → 相邻区间合并为一个分组。输出按三角形起始排序。
+ *
+ * 无面结构（`faceRanges` 缺失——布尔/组合/导入产物）抛 `E_FACE_UNAVAILABLE`；
+ * 面序号越界/非整数抛 `E_FACE_INDEX`。
+ * @param shape 目标 Shape（必须携带 faceRanges）
+ * @param faceIds 面序号列表（PbrAppearance 面序契约见 mesh/primitives.ts 各构造点注释）
+ * @param spec 待合并到目标面的外观字段
+ */
+export function mergeFaceAppearance(shape, faceIds, spec) {
+    const ranges = shape.faceRanges;
+    if (!ranges || ranges.length === 0) {
+        throw new Error('[faijs/appearance] E_FACE_UNAVAILABLE: shape has no face structure — ' +
+            'face-level methods only apply to parameterized primitives (box/cylinder/cone); ' +
+            'boolean/combined/imported shapes have no CAD faces');
+    }
+    const targets = [];
+    for (const id of faceIds) {
+        if (!Number.isInteger(id) || id < 0 || id >= ranges.length) {
+            throw new Error(`[faijs/appearance] E_FACE_INDEX: face index ${id} out of range 0..${ranges.length - 1}`);
+        }
+        targets.push(ranges[id]);
+    }
+    const spans = [];
+    for (const g of shape.materialGroups ?? []) {
+        spans.push({ start: g.start, end: g.start + g.count, appearance: g.appearance });
+    }
+    // 每个目标区间与现有 spans 求并：重叠部分 mergeAppearance，保留两侧未覆盖段。
+    for (const t of targets) {
+        const ts = t.start;
+        const te = t.start + t.count;
+        let applied = false;
+        for (const h of spans) {
+            const is = Math.max(ts, h.start);
+            const ie = Math.min(te, h.end);
+            if (is >= ie)
+                continue;
+            applied = true;
+            const left = h.start < is ? { start: h.start, end: is, appearance: h.appearance } : null;
+            const right = ie < h.end ? { start: ie, end: h.end, appearance: h.appearance } : null;
+            const merged = { start: is, end: ie, appearance: mergeAppearance(h.appearance, spec) };
+            const idx = spans.indexOf(h);
+            spans.splice(idx, 1, ...(left ? [left] : []), merged, ...(right ? [right] : []));
+        }
+        if (!applied)
+            spans.push({ start: ts, end: te, appearance: spec });
+    }
+    // 归一化：按 start 排序 + 相邻同外观合并。
+    spans.sort((a, b) => a.start - b.start);
+    const out = [];
+    for (const s of spans) {
+        const last = out[out.length - 1];
+        if (last && last.end === s.start && sameAppearance(last.appearance, s.appearance)) {
+            last.end = s.end;
+        }
+        else {
+            out.push({ ...s });
+        }
+    }
+    shape.materialGroups = out.map((s) => ({
+        start: s.start,
+        count: s.end - s.start,
+        appearance: s.appearance ?? {},
+    }));
+}
+// ── Shape 方法挂载 ──
+/**
+ * 给 Shape 实例挂载外观方法（幂等：已有 setAppearance 则跳过）。
+ *
+ * 所有产物构造点（solid/curve → fromBrep/fromMeshSolid/fromBrepCurve）统一
+ * 调用本函数，保证 mesh/brep 双链路产物都可用 `box1.setColor(...)`。
+ * 方法**不序列化**（JSON 丢弃函数）；`appearance` 字段随产物跨 worker 传递，
+ * 编辑器/查看器只读字段即可，不依赖方法。
+ * @param shape 产物 Shape 实例（solid/curve 产物）
+ * @returns 挂载后的 shape（类型提升为 `Shape & ShapeAppearanceMethods`；同一实例原地挂载）
+ */
+export function attachAppearanceMethods(shape) {
+    const s = shape;
+    if (typeof s.setAppearance === 'function')
+        return s;
+    s.setAppearance = function setAppearance(spec) {
+        this.appearance = mergeAppearance(this.appearance, spec);
+        return this;
+    };
+    s.setColor = function setColor(color) {
+        const { rgb, alpha } = normalizeColor(color);
+        const spec = { color: rgb };
+        // #rrggbbaa / [r,g,b,a] 的 alpha 归一为 opacity（权威字段）。已显式
+        // setOpacity 的旧值：仅当本次 color 自带 alpha 时覆盖；无 alpha 的
+        // setColor 不动 opacity。
+        if (alpha !== undefined)
+            spec.opacity = alpha;
+        this.appearance = mergeAppearance(this.appearance, spec);
+        return this;
+    };
+    s.setMaterial = function setMaterial(spec) {
+        this.appearance = mergeAppearance(this.appearance, spec);
+        return this;
+    };
+    s.setOpacity = function setOpacity(opacity) {
+        assertComponent01(opacity, 'opacity');
+        this.appearance = mergeAppearance(this.appearance, { opacity });
+        return this;
+    };
+    s.getAppearance = function getAppearance() {
+        return this.appearance;
+    };
+    s.setFaceColor = function setFaceColor(faces, color) {
+        const { rgb, alpha } = normalizeColor(color);
+        const spec = { color: rgb };
+        if (alpha !== undefined)
+            spec.opacity = alpha;
+        mergeFaceAppearance(this, faces, spec);
+        return this;
+    };
+    s.setFaceMaterial = function setFaceMaterial(faces, spec) {
+        mergeFaceAppearance(this, faces, spec);
+        return this;
+    };
+    return s;
+}
+//# sourceMappingURL=appearance.js.map

package/dist/api/appearance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.js","sourceRoot":"","sources":["../../src/api/appearance.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/appearance — faijs PBR 外观规格（颜色/材质/透明度）权威类型与 Shape 方法\n *\n * 设计文档：docs/plans/2026-10-05-faijs-pbr-appearance-api-design.md（v2）\n *\n * 定位：\n * - 外观设置**不是 op**（不进 defineOp/api-namespace/args-schema），是 Shape\n *   实例方法（`box1.setColor(...)`，复用 `asm1.solve()` 的成员调用语句形态）。\n * - `PbrAppearance` 引擎无关、JSON 可序列化，随 Shape 走 mesh/brep 双链路\n *   （`Shape.appearance`），编辑器/查看器只读字段，不依赖方法。\n * - 本文件零依赖（不 import THREE / occt / store）；唯一 import 是 mesh/types\n *   的 `Shape` 类型（type-only），mesh/types 亦只 type-import 本文件的类型，\n *   两者为类型环、无运行时环（值依赖单向：shape.ts → api/appearance.ts）。\n *\n * 颜色约定：\n * - 内部归一形态：`color: [r, g, b]`（sRGB，0–1）；`opacity` 是透明度的唯一\n *   权威字段（0–1）。\n * - 输入接受 hex（#rgb / #rrggbb / #rrggbbaa）与数组（[r,g,b] / [r,g,b,a]）；\n *   `#rrggbbaa` / 数组第 4 分量的 alpha 等价于 `opacity`（显式 setOpacity 后\n *   写入的 opacity 优先于后续无 alpha 的 setColor 推导，见 setColor 注释）。\n * - CSS 颜色名：P1 不支持（抛错），由宿主或后续版本扩展。\n */\n\nimport type { Shape } from '../mesh/types'\n\n// ── 类型 ──\n\n/** 颜色输入：hex（#rgb/#rrggbb/#rrggbbaa）或 sRGB 0–1 数组（[r,g,b] / [r,g,b,a]）。 */\nexport type PbrColor = string | [number, number, number] | [number, number, number, number]\n\n/** glTF 透明度约定（与 3d_editor MaterialAppearance.alphaMode 对齐）。 */\nexport type PbrAlphaMode = 'OPAQUE' | 'MASK' | 'BLEND'\n\n/**\n * faijs PBR 外观规格 —— 引擎无关、JSON 可序列化、随 Shape 走双链路。\n *\n * 全字段可选：未设置字段 = 继承上游 / 宿主默认，不隐式清零。\n * 归一形态约定：`color` 为 [r,g,b]（sRGB 0–1）数组；`opacity`（0–1）为\n * 透明度唯一权威字段（color 的 aa 分量在 set 时归一为 opacity）。\n */\nexport interface PbrAppearance {\n  /** 基色（sRGB 0–1）。 */\n  color?: [number, number, number]\n  /** 透明度 0–1。 */\n  opacity?: number\n  /** 金属度 0–1；粗糙度 0–1。 */\n  metalness?: number\n  roughness?: number\n\n  /** 自发光：颜色 + 强度（>0 时启用，默认 1）。 */\n  emissive?: [number, number, number]\n  emissiveIntensity?: number\n\n  /** 透射/玻璃。 */\n  transmission?: number\n  thickness?: number\n  ior?: number\n  attenuationColor?: [number, number, number]\n  attenuationDistance?: number\n\n  /** 清漆。 */\n  clearcoat?: number\n  clearcoatRoughness?: number\n\n  /** 织物/丝绒。 */\n  sheen?: number\n  sheenColor?: [number, number, number]\n  sheenRoughness?: number\n\n  /** 拉丝金属。 */\n  anisotropy?: number\n  anisotropyRotation?: number\n\n  /** 高光工作流（替代 metalness 工作流）。 */\n  specularIntensity?: number\n  specularColor?: [number, number, number]\n\n  /** 环境光强度（IBL 贡献）。 */\n  envMapIntensity?: number\n\n  /** 透明度模式：默认 OPAQUE；opacity<1 未显式指定时宿主按 BLEND 处理。 */\n  alphaMode?: PbrAlphaMode\n  alphaCutoff?: number\n  /** 双面渲染。 */\n  doubleSided?: boolean\n  /** 无光照。 */\n  unlit?: boolean\n}\n\n/** 材质参数（不含颜色/透明度，`cad` 便捷方法 setMaterial 的入参）。 */\nexport type MaterialSpec = Omit<PbrAppearance, 'color' | 'opacity'>\n\n/** Shape 外观方法签名（运行时由 attachAppearanceMethods 挂载；纯数据判定不受影响）。 */\nexport interface ShapeAppearanceMethods {\n  /** 合并外观：`{...cur, ...spec}`，spec 中 undefined 字段保留旧值。 */\n  setAppearance(spec: PbrAppearance): this\n  /** 便捷：等价 setAppearance({ color })；#rrggbbaa / [r,g,b,a] 的 alpha 归一为 opacity。 */\n  setColor(color: PbrColor): this\n  /** 便捷：等价 setAppearance(spec)。 */\n  setMaterial(spec: MaterialSpec): this\n  /** 便捷：透明度权威字段（0–1）。 */\n  setOpacity(opacity: number): this\n  /** 读取当前外观（可能 undefined）。 */\n  getAppearance(): Readonly<PbrAppearance> | undefined\n  /**\n   * 面级设色：把 faceIds 指定的面（面序号契约见 `Shape.faceRanges`，参数化\n   * primitives 才有）写入 `materialGroups`。无面结构（布尔/组合/导入产物）抛\n   * `E_FACE_UNAVAILABLE`；面序号越界抛 `E_FACE_INDEX`。\n   */\n  setFaceColor(faces: number[], color: PbrColor): this\n  /** 面级材质：等价 setFaceColor 的 material 版本。 */\n  setFaceMaterial(faces: number[], spec: MaterialSpec): this\n}\n\n// ── 归一化 ──\n\n/** hex #rgb/#rrggbb/#rrggbbaa → sRGB 0–1（+可选 alpha）。 */\nfunction parseHexColor(hex: string): { rgb: [number, number, number]; alpha?: number } {\n  let h = hex.startsWith('#') ? hex.slice(1) : hex\n  if (h.length === 3) {\n    h = h.split('').map((c) => c + c).join('')\n  }\n  if (h.length !== 6 && h.length !== 8) {\n    throw new Error(`[faijs/appearance] invalid hex color \"${hex}\" (expected #rgb/#rrggbb/#rrggbbaa)`)\n  }\n  if (!/^[0-9a-fA-F]+$/.test(h)) {\n    throw new Error(`[faijs/appearance] invalid hex color \"${hex}\" (non-hex digit)`)\n  }\n  const r = parseInt(h.slice(0, 2), 16) / 255\n  const g = parseInt(h.slice(2, 4), 16) / 255\n  const b = parseInt(h.slice(4, 6), 16) / 255\n  const rgb: [number, number, number] = [r, g, b]\n  if (h.length === 8) return { rgb, alpha: parseInt(h.slice(6, 8), 16) / 255 }\n  return { rgb }\n}\n\nfunction assertComponent01(v: number, label: string): void {\n  if (v < 0 || v > 1 || !Number.isFinite(v)) {\n    throw new Error(`[faijs/appearance] ${label} must be in 0..1, got ${v}`)\n  }\n}\n\n/**\n * 归一颜色输入 → { rgb, alpha? }。\n * hex 与 [r,g,b] / [r,g,b,a]（sRGB 0–1）；CSS 颜色名 P1 不支持。\n * @param color 颜色输入：`#rgb` / `#rrggbb` / `#rrggbbaa`，或 `[r,g,b]` / `[r,g,b,a]`（sRGB 0–1）\n * @returns 归一后的 sRGB 颜色（0–1）与可选 alpha；带 alpha 的输入在 alpha 通道返回\n */\nexport function normalizeColor(color: PbrColor): { rgb: [number, number, number]; alpha?: number } {\n  if (typeof color === 'string') {\n    if (color.startsWith('#')) return parseHexColor(color)\n    throw new Error(\n      `[faijs/appearance] unsupported color \"${color}\" (P1: hex #rgb/#rrggbb/#rrggbbaa or [r,g,b] expected; CSS names not supported)`,\n    )\n  }\n  const [r, g, b, a] = color\n  assertComponent01(r, 'color.r')\n  assertComponent01(g, 'color.g')\n  assertComponent01(b, 'color.b')\n  if (a !== undefined) {\n    assertComponent01(a, 'color.a')\n    return { rgb: [r, g, b], alpha: a }\n  }\n  return { rgb: [r, g, b] }\n}\n\n/**\n * 合并外观：spec 中 undefined 字段不覆盖旧值。\n * @param cur 当前外观（可为 undefined）\n * @param spec 待合并字段（undefined 字段被跳过）\n * @returns 合并后的外观（新对象；cur 为 undefined 时仅含 spec 非空字段）\n */\nexport function mergeAppearance(cur: PbrAppearance | undefined, spec: PbrAppearance): PbrAppearance {\n  const clean: Record<string, unknown> = {}\n  for (const [k, v] of Object.entries(spec)) {\n    if (v !== undefined) clean[k] = v\n  }\n  return { ...(cur ?? {}), ...clean } as PbrAppearance\n}\n\n/** 两外观等价判定（字段级深比较；undefined 视同空对象）。 */\nfunction sameAppearance(a: PbrAppearance | undefined, b: PbrAppearance | undefined): boolean {\n  const ka = Object.keys(a ?? {}).filter((k) => (a as Record<string, unknown>)[k] !== undefined).sort()\n  const kb = Object.keys(b ?? {}).filter((k) => (b as Record<string, unknown>)[k] !== undefined).sort()\n  if (ka.length !== kb.length) return false\n  for (const k of ka) {\n    const va = (a as Record<string, unknown>)[k]\n    const vb = (b as Record<string, unknown>)[k]\n    if (Array.isArray(va) || Array.isArray(vb)) {\n      if (!Array.isArray(va) || !Array.isArray(vb) || va.length !== vb.length) return false\n      for (let i = 0; i < va.length; i++) if (va[i] !== vb[i]) return false\n    } else if (va !== vb) {\n      return false\n    }\n  }\n  return true\n}\n\n// ── 面级外观 ──\n\n/** 面区间跨度（内部表示，end 为开区间上界）。 */\ninterface FaceSpan {\n  start: number\n  end: number\n  appearance: PbrAppearance | undefined\n}\n\n/**\n * 把 faceIds 指定的面（面序号 → `Shape.faceRanges` 三角形区间）合并进\n * `shape.materialGroups`。多次设置同一面 → 外观合并（spec 未设置字段保留旧值）；\n * 不同面同外观 → 相邻区间合并为一个分组。输出按三角形起始排序。\n *\n * 无面结构（`faceRanges` 缺失——布尔/组合/导入产物）抛 `E_FACE_UNAVAILABLE`；\n * 面序号越界/非整数抛 `E_FACE_INDEX`。\n * @param shape 目标 Shape（必须携带 faceRanges）\n * @param faceIds 面序号列表（PbrAppearance 面序契约见 mesh/primitives.ts 各构造点注释）\n * @param spec 待合并到目标面的外观字段\n */\nexport function mergeFaceAppearance(shape: Shape, faceIds: number[], spec: PbrAppearance): void {\n  const ranges = shape.faceRanges\n  if (!ranges || ranges.length === 0) {\n    throw new Error(\n      '[faijs/appearance] E_FACE_UNAVAILABLE: shape has no face structure — ' +\n      'face-level methods only apply to parameterized primitives (box/cylinder/cone); ' +\n      'boolean/combined/imported shapes have no CAD faces',\n    )\n  }\n  const targets: Array<{ start: number; count: number }> = []\n  for (const id of faceIds) {\n    if (!Number.isInteger(id) || id < 0 || id >= ranges.length) {\n      throw new Error(\n        `[faijs/appearance] E_FACE_INDEX: face index ${id} out of range 0..${ranges.length - 1}`,\n      )\n    }\n    targets.push(ranges[id])\n  }\n\n  const spans: FaceSpan[] = []\n  for (const g of shape.materialGroups ?? []) {\n    spans.push({ start: g.start, end: g.start + g.count, appearance: g.appearance })\n  }\n  // 每个目标区间与现有 spans 求并：重叠部分 mergeAppearance，保留两侧未覆盖段。\n  for (const t of targets) {\n    const ts = t.start\n    const te = t.start + t.count\n    let applied = false\n    for (const h of spans) {\n      const is = Math.max(ts, h.start)\n      const ie = Math.min(te, h.end)\n      if (is >= ie) continue\n      applied = true\n      const left = h.start < is ? { start: h.start, end: is, appearance: h.appearance } : null\n      const right = ie < h.end ? { start: ie, end: h.end, appearance: h.appearance } : null\n      const merged: FaceSpan = { start: is, end: ie, appearance: mergeAppearance(h.appearance, spec) }\n      const idx = spans.indexOf(h)\n      spans.splice(idx, 1, ...(left ? [left] : []), merged, ...(right ? [right] : []))\n    }\n    if (!applied) spans.push({ start: ts, end: te, appearance: spec })\n  }\n  // 归一化：按 start 排序 + 相邻同外观合并。\n  spans.sort((a, b) => a.start - b.start)\n  const out: FaceSpan[] = []\n  for (const s of spans) {\n    const last = out[out.length - 1]\n    if (last && last.end === s.start && sameAppearance(last.appearance, s.appearance)) {\n      last.end = s.end\n    } else {\n      out.push({ ...s })\n    }\n  }\n  shape.materialGroups = out.map((s) => ({\n    start: s.start,\n    count: s.end - s.start,\n    appearance: s.appearance ?? {},\n  }))\n}\n\n// ── Shape 方法挂载 ──\n\n/**\n * 给 Shape 实例挂载外观方法（幂等：已有 setAppearance 则跳过）。\n *\n * 所有产物构造点（solid/curve → fromBrep/fromMeshSolid/fromBrepCurve）统一\n * 调用本函数，保证 mesh/brep 双链路产物都可用 `box1.setColor(...)`。\n * 方法**不序列化**（JSON 丢弃函数）；`appearance` 字段随产物跨 worker 传递，\n * 编辑器/查看器只读字段即可，不依赖方法。\n * @param shape 产物 Shape 实例（solid/curve 产物）\n * @returns 挂载后的 shape（类型提升为 `Shape & ShapeAppearanceMethods`；同一实例原地挂载）\n */\nexport function attachAppearanceMethods(shape: Shape): Shape & ShapeAppearanceMethods {\n  const s = shape as Shape & ShapeAppearanceMethods\n  if (typeof s.setAppearance === 'function') return s\n  s.setAppearance = function setAppearance(this: Shape & ShapeAppearanceMethods, spec: PbrAppearance) {\n    this.appearance = mergeAppearance(this.appearance, spec)\n    return this\n  }\n  s.setColor = function setColor(this: Shape & ShapeAppearanceMethods, color: PbrColor) {\n    const { rgb, alpha } = normalizeColor(color)\n    const spec: PbrAppearance = { color: rgb }\n    // #rrggbbaa / [r,g,b,a] 的 alpha 归一为 opacity（权威字段）。已显式\n    // setOpacity 的旧值：仅当本次 color 自带 alpha 时覆盖；无 alpha 的\n    // setColor 不动 opacity。\n    if (alpha !== undefined) spec.opacity = alpha\n    this.appearance = mergeAppearance(this.appearance, spec)\n    return this\n  }\n  s.setMaterial = function setMaterial(this: Shape & ShapeAppearanceMethods, spec: MaterialSpec) {\n    this.appearance = mergeAppearance(this.appearance, spec as PbrAppearance)\n    return this\n  }\n  s.setOpacity = function setOpacity(this: Shape & ShapeAppearanceMethods, opacity: number) {\n    assertComponent01(opacity, 'opacity')\n    this.appearance = mergeAppearance(this.appearance, { opacity })\n    return this\n  }\n  s.getAppearance = function getAppearance(this: Shape) {\n    return this.appearance\n  }\n  s.setFaceColor = function setFaceColor(this: Shape & ShapeAppearanceMethods, faces: number[], color: PbrColor) {\n    const { rgb, alpha } = normalizeColor(color)\n    const spec: PbrAppearance = { color: rgb }\n    if (alpha !== undefined) spec.opacity = alpha\n    mergeFaceAppearance(this, faces, spec)\n    return this\n  }\n  s.setFaceMaterial = function setFaceMaterial(this: Shape & ShapeAppearanceMethods, faces: number[], spec: MaterialSpec) {\n    mergeFaceAppearance(this, faces, spec as PbrAppearance)\n    return this\n  }\n  return s\n}\n"]}

package/dist/api/import-step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-step.d.ts","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAU1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAuCpF;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;CAMtB,CAAA"}
+{"version":3,"file":"import-step.d.ts","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAwB1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAkDpF;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;CAMtB,CAAA"}

package/dist/api/import-step.js

@@ -4,6 +4,20 @@ import { OpError } from './internal/result-unwrap.js';
 import { loadBrep } from '../brep/brep-ops.js';
 import { fromBrep } from '../shape.js';
 import { defineOp } from '../sdk.js';
+import { parseStepPartMeta } from '../step/stepMetaParser.js';
+/** 尽力把 ArrayBuffer 当 UTF-8 文本解出；非文本（如 .brp 二进制）返回 undefined。 */
+function decodeStepText(buffer) {
+    if (!(buffer?.byteLength))
+        return undefined;
+    try {
+        const s = new TextDecoder('utf-8', { fatal: false }).decode(buffer);
+        // STEP 是纯文本 ISO-10303-21；首段要出现 `ISO-10303-21;` 才算。
+        return s.includes('ISO-10303-21') ? s : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * api import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）
  *
@@ -55,6 +69,20 @@ export async function importStepImpl(params) {
     // C6：非实体一等公民（对齐 import_brep）。loadBrep 自适应：CASCADE Topology
     // 文本走 kernel.fromBREP，其余（STEP/STP）走 kernel.importStep。
     const { solid: solidHandle, shape } = loadBrep(kernel, buffer, undefined, undefined, { allowNonSolid: true });
+    // P2（设计文档 2026-10-05-meta §5.2 读）：从 STEP (P21) 文本捞伙伴级描述/属性
+    // 挂 `shape.meta`（name 已由 OCCT label 提供，description/UDA 由纯文本补充）。
+    // 非文本/非 STEP 内容跳过，绝不抛。
+    const stepText = decodeStepText(buffer);
+    if (stepText && shape.meta == null) {
+        const partMeta = parseStepPartMeta(stepText);
+        const shapeMeta = { ...(shape.meta ?? {}) };
+        if (partMeta.description)
+            shapeMeta.description = partMeta.description;
+        if (partMeta.metadata && Object.keys(partMeta.metadata).length > 0)
+            shapeMeta.metadata = partMeta.metadata;
+        if (Object.keys(shapeMeta).length > 0)
+            shape.meta = shapeMeta;
+    }
     // E3（H12）：链根建 roleTable——导入文件的面没有语义名，按枚举序命名
     // imported:<i>（同一文件重复导入，枚举序稳定，role 名跨次导入保持一致）。
     const stmtId = String(getCurrentStmt()?.id ?? '');

package/dist/api/import-step.js.map

@@ -1 +1 @@
-{"version":3,"file":"import-step.js","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACpF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAIjC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAA+B;IAClE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAA;IACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,6CAA6C,CAAC,CAAA;IAC3F,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAEhB,CAAA;IACb,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,IAAI,OAAO,CACf,aAAa,EACb,aAAa,EACb,4DAA4D,CAC7D,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;IAE7C,IAAI,MAAqB,CAAA;IACzB,IAAI,CAAC;QAAC,MAAM,GAAG,UAAU,EAAE,CAAA;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,oBAAoB,CAChE,mFAAmF,CACpF,CAAA;IACH,CAAC;IAED,2DAA2D;IAC3D,uDAAuD;IACvD,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,QAAQ,CAC5C,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAC9D,CAAA;IACD,4CAA4C;IAC5C,+CAA+C;IAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,CAAA;IACrE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAA;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAA;IAC1C,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AACvF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;IAClC,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,iEAAiE;IACjE,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,EAAgB;CACpH,CAAC,CAAA","sourcesContent":["import type { Shape } from '../mesh/types'\nimport { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { OpError } from './internal/result-unwrap'\nimport { loadBrep } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/**\n * api import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）\n *\n * 与 `import_brep`（容器资产）和 `cad.load`（编辑器 FileRef）的职责切分：\n * - `cad.import_step` 是 faijs **平台**几何 op：单一本地路径（宿主 `resolveFile`），\n *   OCCT STEPControl_Reader 读入，返回持 OCCT 句柄 + roleTable 的 Shape。\n * - `import_brep` 读的是容器 `assets/` 里的冻结 BREP 资产（key，去扩展名）；\n *   `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流、\n *   画布语句位置语义），平台侧不要复用它（C7）。\n *\n * 非实体（wire/face/shell）一等公民（C6，对齐 import_brep）：始终 allowNonSolid。\n * STEP 是 BREP 专属格式：mesh / 无内核模式抛 E_BREP_UNSUPPORTED。\n *\n * @group 创建\n * @inputs 0\n * @async true\n * @qual ok\n * @name import_step\n * @param params.path - 本地绝对路径（宿主 resolveFile 解析）。type:string required:true\n * @note 平台 STEP 导入 op。读文件经宿主资产解析器（`assets.resolveFile`），与 `cad.load` 同一通道；语义为「任意路径 STEP → OCCT 读入的 Shape」。\n * @note 非实体一等（C6）：wire/face/shell 一律可导入。需要实体的 op（布尔、up-to 目标面）在**使用点**报错。\n * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。\n * @example\n * const a = await cad.import_step({ path: 'D:/models/box.step' })\n */\n\n/**\n * 裸实现：契约层测试直调（不经 defineOp 的 dispatch 拦截）。\n *\n * @param params - op 参数对象；`path` 为 STEP 文件路径。\n * @returns 持 OCCT 句柄的几何（非实体亦可）。\n */\nexport async function importStepImpl(params: Record<string, unknown>): Promise<Shape> {\n  const path = params.path\n  if (typeof path !== 'string' || path.length === 0) {\n    throw new OpError('import_step', 'E_ARGS', '[api/import_step] path (string) is required')\n  }\n\n  const assets = getBackends().assets as {\n    resolveFile?(path: string): Promise<ArrayBuffer>\n  } | undefined\n  if (!assets || !assets.resolveFile) {\n    throw new OpError(\n      'import_step',\n      'E_OP_FAILED',\n      '[api/import_step] assets backend (resolveFile) is required',\n    )\n  }\n\n  const buffer = await assets.resolveFile(path)\n\n  let kernel: BrepEngineApi\n  try { kernel = getBrepApi() } catch { throw new BrepUnsupportedError(\n      'E_BREP_UNSUPPORTED: import_step requires an OCCT kernel (STEP has no mesh parser)',\n    )\n  }\n\n  // C6：非实体一等公民（对齐 import_brep）。loadBrep 自适应：CASCADE Topology\n  // 文本走 kernel.fromBREP，其余（STEP/STP）走 kernel.importStep。\n  const { solid: solidHandle, shape } = loadBrep(\n    kernel, buffer, undefined, undefined, { allowNonSolid: true },\n  )\n  // E3（H12）：链根建 roleTable——导入文件的面没有语义名，按枚举序命名\n  // imported:<i>（同一文件重复导入，枚举序稳定，role 名跨次导入保持一致）。\n  const stmtId = String(getCurrentStmt()?.id ?? '')\n  const hashes = kernel.subShapeHashes(solidHandle, 'face', 2147483647)\n  const roles = new Map<string, number[]>()\n  for (let i = 0; i < hashes.length; i++) {\n    roles.set(`imported:${i}`, [hashes[i]!])\n  }\n  return fromBrep(shape, { solid: solidHandle, roleTable: new Map([[stmtId, roles]]) })\n}\n\n/**\n * GOTCHA（2026-09-30）：与 import_brep 同——必须经 defineOp 包装进入 cad 命名空间，\n * 不能是裸 async 函数。part 键 roleTable（outputTablesByPart）只在 define-op.ts\n * 包装层的 brep 分支登记；裸 async 函数产物没有 part 键表，下游 place/edgeRef\n * 报 \"input shape has no role table (nameless shape)\"。\n */\nexport const import_step = defineOp({\n  name: 'import_step',\n  brep: importStepImpl,\n  engines: ['occt'],\n  // `imported:0` 是 <i> 采样值（同 extrude 的 `wall:0`），与 import-brep 同构。\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [{ kind: 'imported', index: 0 }] } } as Provenance,\n})\n"]}
+{"version":3,"file":"import-step.js","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Shape } from '../mesh/types'\nimport { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { OpError } from './internal/result-unwrap'\nimport { loadBrep } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport { parseStepPartMeta } from '../step/stepMetaParser'\nimport type { ShapeMeta } from './meta'\n\n/** 尽力把 ArrayBuffer 当 UTF-8 文本解出；非文本（如 .brp 二进制）返回 undefined。 */\nfunction decodeStepText(buffer: ArrayBuffer): string | undefined {\n  if (!(buffer?.byteLength)) return undefined\n  try {\n    const s = new TextDecoder('utf-8', { fatal: false }).decode(buffer)\n    // STEP 是纯文本 ISO-10303-21；首段要出现 `ISO-10303-21;` 才算。\n    return s.includes('ISO-10303-21') ? s : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * api import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）\n *\n * 与 `import_brep`（容器资产）和 `cad.load`（编辑器 FileRef）的职责切分：\n * - `cad.import_step` 是 faijs **平台**几何 op：单一本地路径（宿主 `resolveFile`），\n *   OCCT STEPControl_Reader 读入，返回持 OCCT 句柄 + roleTable 的 Shape。\n * - `import_brep` 读的是容器 `assets/` 里的冻结 BREP 资产（key，去扩展名）；\n *   `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流、\n *   画布语句位置语义），平台侧不要复用它（C7）。\n *\n * 非实体（wire/face/shell）一等公民（C6，对齐 import_brep）：始终 allowNonSolid。\n * STEP 是 BREP 专属格式：mesh / 无内核模式抛 E_BREP_UNSUPPORTED。\n *\n * @group 创建\n * @inputs 0\n * @async true\n * @qual ok\n * @name import_step\n * @param params.path - 本地绝对路径（宿主 resolveFile 解析）。type:string required:true\n * @note 平台 STEP 导入 op。读文件经宿主资产解析器（`assets.resolveFile`），与 `cad.load` 同一通道；语义为「任意路径 STEP → OCCT 读入的 Shape」。\n * @note 非实体一等（C6）：wire/face/shell 一律可导入。需要实体的 op（布尔、up-to 目标面）在**使用点**报错。\n * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。\n * @example\n * const a = await cad.import_step({ path: 'D:/models/box.step' })\n */\n\n/**\n * 裸实现：契约层测试直调（不经 defineOp 的 dispatch 拦截）。\n *\n * @param params - op 参数对象；`path` 为 STEP 文件路径。\n * @returns 持 OCCT 句柄的几何（非实体亦可）。\n */\nexport async function importStepImpl(params: Record<string, unknown>): Promise<Shape> {\n  const path = params.path\n  if (typeof path !== 'string' || path.length === 0) {\n    throw new OpError('import_step', 'E_ARGS', '[api/import_step] path (string) is required')\n  }\n\n  const assets = getBackends().assets as {\n    resolveFile?(path: string): Promise<ArrayBuffer>\n  } | undefined\n  if (!assets || !assets.resolveFile) {\n    throw new OpError(\n      'import_step',\n      'E_OP_FAILED',\n      '[api/import_step] assets backend (resolveFile) is required',\n    )\n  }\n\n  const buffer = await assets.resolveFile(path)\n\n  let kernel: BrepEngineApi\n  try { kernel = getBrepApi() } catch { throw new BrepUnsupportedError(\n      'E_BREP_UNSUPPORTED: import_step requires an OCCT kernel (STEP has no mesh parser)',\n    )\n  }\n\n  // C6：非实体一等公民（对齐 import_brep）。loadBrep 自适应：CASCADE Topology\n  // 文本走 kernel.fromBREP，其余（STEP/STP）走 kernel.importStep。\n  const { solid: solidHandle, shape } = loadBrep(\n    kernel, buffer, undefined, undefined, { allowNonSolid: true },\n  )\n  // P2（设计文档 2026-10-05-meta §5.2 读）：从 STEP (P21) 文本捞伙伴级描述/属性\n  // 挂 `shape.meta`（name 已由 OCCT label 提供，description/UDA 由纯文本补充）。\n  // 非文本/非 STEP 内容跳过，绝不抛。\n  const stepText = decodeStepText(buffer)\n  if (stepText && shape.meta == null) {\n    const partMeta = parseStepPartMeta(stepText)\n    const shapeMeta: ShapeMeta = { ...(shape.meta ?? {}) }\n    if (partMeta.description) shapeMeta.description = partMeta.description\n    if (partMeta.metadata && Object.keys(partMeta.metadata).length > 0) shapeMeta.metadata = partMeta.metadata\n    if (Object.keys(shapeMeta).length > 0) shape.meta = shapeMeta\n  }\n  // E3（H12）：链根建 roleTable——导入文件的面没有语义名，按枚举序命名\n  // imported:<i>（同一文件重复导入，枚举序稳定，role 名跨次导入保持一致）。\n  const stmtId = String(getCurrentStmt()?.id ?? '')\n  const hashes = kernel.subShapeHashes(solidHandle, 'face', 2147483647)\n  const roles = new Map<string, number[]>()\n  for (let i = 0; i < hashes.length; i++) {\n    roles.set(`imported:${i}`, [hashes[i]!])\n  }\n  return fromBrep(shape, { solid: solidHandle, roleTable: new Map([[stmtId, roles]]) })\n}\n\n/**\n * GOTCHA（2026-09-30）：与 import_brep 同——必须经 defineOp 包装进入 cad 命名空间，\n * 不能是裸 async 函数。part 键 roleTable（outputTablesByPart）只在 define-op.ts\n * 包装层的 brep 分支登记；裸 async 函数产物没有 part 键表，下游 place/edgeRef\n * 报 \"input shape has no role table (nameless shape)\"。\n */\nexport const import_step = defineOp({\n  name: 'import_step',\n  brep: importStepImpl,\n  engines: ['occt'],\n  // `imported:0` 是 <i> 采样值（同 extrude 的 `wall:0`），与 import-brep 同构。\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [{ kind: 'imported', index: 0 }] } } as Provenance,\n})\n"]}

package/dist/api/index.d.ts

@@ -50,6 +50,10 @@ export { solid, isShape, isCompound } from '../shape.js';
 export { compound as structCompound } from '../shape.js';
 export type { ShapeSlot, SolidShape, CompoundShape, CurveShape, StdShape, ShapeKind } from '../shape.js';
 export type { Shape } from '../mesh/types.js';
+export type { PbrAppearance, PbrColor, PbrAlphaMode, MaterialSpec, ShapeAppearanceMethods } from './appearance.js';
+export { mergeAppearance, normalizeColor } from './appearance.js';
+export type { ShapeMeta, FileMeta, ShapeMetaMethods } from './meta.js';
+export { mergeMeta } from './meta.js';
 export * from './generated/script-face.js';
 export { extrude } from './extrude.js';
 export { revolve } from './generated/operations.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}

package/dist/api/index.js

@@ -60,6 +60,8 @@ export { faceRef } from './face-ref.js';
 export { asset } from './asset.js';
 export { solid, isShape, isCompound } from '../shape.js';
 export { compound as structCompound } from '../shape.js';
+export { mergeAppearance, normalizeColor } from './appearance.js';
+export { mergeMeta } from './meta.js';
 // ── P23：brepjs 兼容面接线（§4.2 / B1 三源一致）──
 //
 // ① 生成脚本面 op（与 api-namespace 的 cad 面同源：api/generated/script-face.ts）。

package/dist/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * L3 API 面（api/）— faijs 库函数命名空间\n *\n * 设计文档：docs/plans/2026-09-01-layered-api-architecture.md §D1/D2（P6 迁入 core）\n *\n * 导出全部官方库函数、Shape 构造器与 schema 表。\n * 库函数签名 = .fai.js 源码里的调用形态（无隐式参数）；\n * 后端资源经 getBackends() 获取，保留声明经 keep() 表达。\n * 实现来源按 D11：mesh 侧复用 mesh/ 层，brep 侧复用既有 brep/ 层；\n * 缺失 brep 能力时经 D10 桥接调移植树 L2（见各 op 实现）。\n */\n\nexport { box, sphere, cylinder, cone, wedge } from './primitives'\n// `../3d_editor` 消费面（**不是废弃项**，措辞于 2026-09-22 校正）：transform 家族\n// （translate/rotate_euler/scale/scale3d）为编辑器应用提供（拖拽 / 时间线语句），\n// 不属 faijs 平台面，但服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**；\n// 各 op 的 JSDoc 已带校正后的 @deprecated。\n//\n// D1（2026-09-23 扩展库拆分，选项 C）：四个 transform op **全部留 core**——\n// `translate` 是通用几何变换且是小程序端唯一在用的 transform op，同族不拆散。\nexport { translate, rotate_euler, scale, scale3d } from './transform'\nexport { union, subtract, intersect, cut } from './boolean'\nexport { engrave } from './engrave'\nexport { chamfer } from './chamfer'\nexport { fillet } from './fillet'\nexport { shell, type ShellParams } from './shell'\nexport { draft, type DraftParams } from './draft'\nexport { thicken } from './thicken'\nexport { defeature, reverseShape, unifySameDomain, sew, sewAndSolidify, removeHolesFromFace, type SewParams } from './feature-repair'\nexport { filletVariable } from './fillet-variable'\nexport { splitByPlane, type SplitByPlaneParams } from './split-by-plane'\nexport { sectionByPlane, type SectionByPlaneParams } from './section-by-plane'\nexport { screw } from './screw'\nexport { profile, buildProfileShape, assertProfileParams } from './profile'\nexport type { ProfileLineSeg, ProfileArcSeg, ProfileSeg, ProfileLoop, ProfileParams } from './profile'\nexport { sketchOnPlane, buildSketchOnPlaneWith } from './sketch-on-plane'\nexport { sketchOnFace, buildSketchOnFaceWith } from './sketch-on-face'\nexport { punchHole, buildPunchHole, punchSolidOf } from './punch-hole'\nexport type { SketchOnPlaneParams, PlaneSpec } from './sketch-on-plane'\nexport { wire } from './wire'\nexport { helix } from './helix'\nexport { split } from './split'\nexport { sweep } from './sweep'\nexport { loft } from './loft'\nexport { knurl } from './knurl'\nexport { sdf } from './sdf'\n// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：\n// 引擎不得 import api/compound；公共 API 经本 re-export 保持）。\nexport { applyTransform } from '../mesh/rigid-transform'\n// P2-f3：装配子层全量导出（solvePreview/entityFromGeometry 等经此到门面）。\n// A/B 组 op（fai_* / group / assembly / copy / load / text / svgExtrude）已迁出\n// core，见 @faicad/faijs-extra；装配**求解器**（solve/validate/joints/solvers）\n// 仍是平台能力，留在此处。\nexport * from './assembly'\n// ── H11：平台几何 op（方案 §4，替代 FCStd 迁移对编辑器 op 的借用）──\nexport { import_brep } from './import-brep'\nexport { import_step } from './import-step'\nexport { compound } from './compound-geom'\nexport { place } from './place'\nexport { faceNormal, bboxCenter, bboxMin, bboxMax } from './geom'\nexport { edgeRef } from './edge-ref'\nexport { faceRef } from './face-ref'\nexport { asset } from './asset'\nexport { solid, isShape, isCompound } from '../shape'\nexport { compound as structCompound } from '../shape'\nexport type { ShapeSlot, SolidShape, CompoundShape, CurveShape, StdShape, ShapeKind } from '../shape'\nexport type { Shape } from '../mesh/types'\n\n// ── P23：brepjs 兼容面接线（§4.2 / B1 三源一致）──\n//\n// ① 生成脚本面 op（与 api-namespace 的 cad 面同源：api/generated/script-face.ts）。\n//    这批 op 经 `compatOp(projectBrepOp(…))` 包装，faijs 形态（Shape 进 / Shape 出、\n//    布尔双形态、brep-only），TS 侧与 `.fai.js` 侧同语义。\nexport * from './generated/script-face'\n// P25: compat extrude/revolve (brep-only, face→prism / face→lathe) share one\n// definition between the TS surface and the cad scripting surface. The fcstd\n// codegen wires Pad/Pocket/Extrusion/Revolution through these (sketch face →\n// cad.extrude / cad.revolve).\n// extrude 是平台手写 op（承载 upTo；长度形态委托生成投影）——见 api/extrude.ts；\n// revolve 仍直接取生成投影。\nexport { extrude } from './extrude'\nexport { revolve } from './generated/operations'\n//\n// ② 2026-09-25 core-decouple：brepjsCompat 命名空间与全部 op 投影随 vendored\n//    树删除（§5.5 第 3 条，裁决 9）。此处只平铺**无 op 语义**的组合器与纯工具\n//    （Result / 向量 / 平面 / 错误 / 常量），它们为 core 内联实现（§5.2），\n//    在两个面之间语义一致且无同名冲突。\nexport {\n  ok, err, isOk, isErr, unwrap, unwrapOr,\n  vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize,\n  createPlane, createNamedPlane, resolvePlane,\n  kernelError, validationError,\n  DEG2RAD, RAD2DEG,\n} from './brepjs-compat'\nexport type {\n  Result, Ok, Err,\n  BrepError,\n  Plane, PlaneName, PlaneInput,\n  Vec3, PointInput,\n} from './brepjs-compat'\n// ── 2026-09-25 core-decouple：vendored 库建造工厂（makeExternalGear /\n//    makeInternalGear / makePlanetaryGear / thread）与其句柄类型\n//    （Vertex/Edge/…/Shape3D/ValidSolid/Bounds3D/Gear*）随裁决 9 删除；\n//    Result 组合器 map/andThen 为 core 内联（§5.2），保留平铺；\n//    brepjsCompat 命名空间整体删除（§5.5 第 3 条）。\nexport { map, andThen } from './brepjs-compat'\n// ── 2026-09-25 core-decouple wrapup §2.2：sheetmetal 拓扑查询 / 构造 / 测量\n//    出口（faijs 风格，裁决 3 补进公开导出）。isValid 不在此面——cad 脚本面\n//    已有同语义出口（见 brep-topology.ts 头部注释）。同步测量（measureVolume\n//    / measureArea / measureLength）为 api/generated/measurement.ts 第一方\n//    同步版，一并平铺（cad 面的 volume/area/length 为 async 脚本面重命名）。\nexport * from './brep-topology'\n// CadQuery 拓扑选择器子系统（独立物理边界，与 topo-resolve 隔离）：\n// 等价搬运自 cq-compat，子路径直达 @faicad/faijs/api/cadquery-selectors。\nexport * from './cadquery-selectors'\nexport { measureVolume, measureArea, measureLength } from './generated/measurement'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * L3 API 面（api/）— faijs 库函数命名空间\n *\n * 设计文档：docs/plans/2026-09-01-layered-api-architecture.md §D1/D2（P6 迁入 core）\n *\n * 导出全部官方库函数、Shape 构造器与 schema 表。\n * 库函数签名 = .fai.js 源码里的调用形态（无隐式参数）；\n * 后端资源经 getBackends() 获取，保留声明经 keep() 表达。\n * 实现来源按 D11：mesh 侧复用 mesh/ 层，brep 侧复用既有 brep/ 层；\n * 缺失 brep 能力时经 D10 桥接调移植树 L2（见各 op 实现）。\n */\n\nexport { box, sphere, cylinder, cone, wedge } from './primitives'\n// `../3d_editor` 消费面（**不是废弃项**，措辞于 2026-09-22 校正）：transform 家族\n// （translate/rotate_euler/scale/scale3d）为编辑器应用提供（拖拽 / 时间线语句），\n// 不属 faijs 平台面，但服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**；\n// 各 op 的 JSDoc 已带校正后的 @deprecated。\n//\n// D1（2026-09-23 扩展库拆分，选项 C）：四个 transform op **全部留 core**——\n// `translate` 是通用几何变换且是小程序端唯一在用的 transform op，同族不拆散。\nexport { translate, rotate_euler, scale, scale3d } from './transform'\nexport { union, subtract, intersect, cut } from './boolean'\nexport { engrave } from './engrave'\nexport { chamfer } from './chamfer'\nexport { fillet } from './fillet'\nexport { shell, type ShellParams } from './shell'\nexport { draft, type DraftParams } from './draft'\nexport { thicken } from './thicken'\nexport { defeature, reverseShape, unifySameDomain, sew, sewAndSolidify, removeHolesFromFace, type SewParams } from './feature-repair'\nexport { filletVariable } from './fillet-variable'\nexport { splitByPlane, type SplitByPlaneParams } from './split-by-plane'\nexport { sectionByPlane, type SectionByPlaneParams } from './section-by-plane'\nexport { screw } from './screw'\nexport { profile, buildProfileShape, assertProfileParams } from './profile'\nexport type { ProfileLineSeg, ProfileArcSeg, ProfileSeg, ProfileLoop, ProfileParams } from './profile'\nexport { sketchOnPlane, buildSketchOnPlaneWith } from './sketch-on-plane'\nexport { sketchOnFace, buildSketchOnFaceWith } from './sketch-on-face'\nexport { punchHole, buildPunchHole, punchSolidOf } from './punch-hole'\nexport type { SketchOnPlaneParams, PlaneSpec } from './sketch-on-plane'\nexport { wire } from './wire'\nexport { helix } from './helix'\nexport { split } from './split'\nexport { sweep } from './sweep'\nexport { loft } from './loft'\nexport { knurl } from './knurl'\nexport { sdf } from './sdf'\n// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：\n// 引擎不得 import api/compound；公共 API 经本 re-export 保持）。\nexport { applyTransform } from '../mesh/rigid-transform'\n// P2-f3：装配子层全量导出（solvePreview/entityFromGeometry 等经此到门面）。\n// A/B 组 op（fai_* / group / assembly / copy / load / text / svgExtrude）已迁出\n// core，见 @faicad/faijs-extra；装配**求解器**（solve/validate/joints/solvers）\n// 仍是平台能力，留在此处。\nexport * from './assembly'\n// ── H11：平台几何 op（方案 §4，替代 FCStd 迁移对编辑器 op 的借用）──\nexport { import_brep } from './import-brep'\nexport { import_step } from './import-step'\nexport { compound } from './compound-geom'\nexport { place } from './place'\nexport { faceNormal, bboxCenter, bboxMin, bboxMax } from './geom'\nexport { edgeRef } from './edge-ref'\nexport { faceRef } from './face-ref'\nexport { asset } from './asset'\nexport { solid, isShape, isCompound } from '../shape'\nexport { compound as structCompound } from '../shape'\nexport type { ShapeSlot, SolidShape, CompoundShape, CurveShape, StdShape, ShapeKind } from '../shape'\nexport type { Shape } from '../mesh/types'\n// PBR 外观规格（设计文档 2026-10-05 v2 §4.1）：类型供宿主/第三方消费；\n// 归一化/合并纯函数供编辑器映射（faijsAppearanceToHost）与导出复用。\nexport type { PbrAppearance, PbrColor, PbrAlphaMode, MaterialSpec, ShapeAppearanceMethods } from './appearance'\nexport { mergeAppearance, normalizeColor } from './appearance'\n// 零件/文件级说明性元数据（设计文档 2026-10-05-meta）：类型供宿主/第三方消费；\n// 合并纯函数供编辑器映射与导出复用。\nexport type { ShapeMeta, FileMeta, ShapeMetaMethods } from './meta'\nexport { mergeMeta } from './meta'\n\n// ── P23：brepjs 兼容面接线（§4.2 / B1 三源一致）──\n//\n// ① 生成脚本面 op（与 api-namespace 的 cad 面同源：api/generated/script-face.ts）。\n//    这批 op 经 `compatOp(projectBrepOp(…))` 包装，faijs 形态（Shape 进 / Shape 出、\n//    布尔双形态、brep-only），TS 侧与 `.fai.js` 侧同语义。\nexport * from './generated/script-face'\n// P25: compat extrude/revolve (brep-only, face→prism / face→lathe) share one\n// definition between the TS surface and the cad scripting surface. The fcstd\n// codegen wires Pad/Pocket/Extrusion/Revolution through these (sketch face →\n// cad.extrude / cad.revolve).\n// extrude 是平台手写 op（承载 upTo；长度形态委托生成投影）——见 api/extrude.ts；\n// revolve 仍直接取生成投影。\nexport { extrude } from './extrude'\nexport { revolve } from './generated/operations'\n//\n// ② 2026-09-25 core-decouple：brepjsCompat 命名空间与全部 op 投影随 vendored\n//    树删除（§5.5 第 3 条，裁决 9）。此处只平铺**无 op 语义**的组合器与纯工具\n//    （Result / 向量 / 平面 / 错误 / 常量），它们为 core 内联实现（§5.2），\n//    在两个面之间语义一致且无同名冲突。\nexport {\n  ok, err, isOk, isErr, unwrap, unwrapOr,\n  vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize,\n  createPlane, createNamedPlane, resolvePlane,\n  kernelError, validationError,\n  DEG2RAD, RAD2DEG,\n} from './brepjs-compat'\nexport type {\n  Result, Ok, Err,\n  BrepError,\n  Plane, PlaneName, PlaneInput,\n  Vec3, PointInput,\n} from './brepjs-compat'\n// ── 2026-09-25 core-decouple：vendored 库建造工厂（makeExternalGear /\n//    makeInternalGear / makePlanetaryGear / thread）与其句柄类型\n//    （Vertex/Edge/…/Shape3D/ValidSolid/Bounds3D/Gear*）随裁决 9 删除；\n//    Result 组合器 map/andThen 为 core 内联（§5.2），保留平铺；\n//    brepjsCompat 命名空间整体删除（§5.5 第 3 条）。\nexport { map, andThen } from './brepjs-compat'\n// ── 2026-09-25 core-decouple wrapup §2.2：sheetmetal 拓扑查询 / 构造 / 测量\n//    出口（faijs 风格，裁决 3 补进公开导出）。isValid 不在此面——cad 脚本面\n//    已有同语义出口（见 brep-topology.ts 头部注释）。同步测量（measureVolume\n//    / measureArea / measureLength）为 api/generated/measurement.ts 第一方\n//    同步版，一并平铺（cad 面的 volume/area/length 为 async 脚本面重命名）。\nexport * from './brep-topology'\n// CadQuery 拓扑选择器子系统（独立物理边界，与 topo-resolve 隔离）：\n// 等价搬运自 cq-compat，子路径直达 @faicad/faijs/api/cadquery-selectors。\nexport * from './cadquery-selectors'\nexport { measureVolume, measureArea, measureLength } from './generated/measurement'\n"]}