@faicad/faijs 0.13.0

package/dist/api/compat/index.js

@@ -0,0 +1,222 @@
+/**
+ * BREP-TS compatibility surface (P21).
+ *
+ * Projects the vendored BREP TS tree onto four stable groups so library authors
+ * can write `import { box, fuse, Sketcher, ok } from this module` and call it
+ * upstream-style:
+ *
+ *   ① op        — solid primitives + boolean / evolution operations
+ *   ② topology  — sub-shape queries + measurements (plus the Bounds3D type)
+ *   ③ sketching — stateful Sketcher / FaceSketcher DSL + drawing factories
+ *   ④ combinators / types — result, vector, plane, errors, constants, types
+ *
+ * Every symbol is a projection (re-export or a thin dual-form wrapper) from the
+ * ported tree: no reimplementation. The `.js` specifiers are the repo
+ * convention (TypeScript maps `.js` → `.ts`).
+ *
+ * Semantic wraps (P23: both live in `api/internal/compat-projection.ts` so the
+ * generated face and this hand-curated face share one mechanism):
+ * - single-kernel assert: every modeling op asserts a bound BREP kernel first
+ *   (see `assertKernelBound`); `getBackends()` may throw before configuration,
+ *   so it is guarded and falls back to the occt-kernel binding flag.
+ * - dual argument forms: object form normalizes to positional form via the
+ *   shared `resolveArgs` discriminant; object keys outside the declared
+ *   parameter table throw the shared `E_ARGS_FORM` token.
+ * - `box` is the hand-written dual-form sample: positional
+ *   `box(width, depth, height)` and `box({ size })` / `box({ width, depth,
+ *   height })` both forward to the vendored primitive in its native dimension
+ *   order (width = X, depth = Y, height = Z — confirm against
+ *   `primitiveFns#box`), so every accepted form yields identical geometry.
+ */
+import { assertKernelBound, projectBrepOp } from '../internal/compat-projection.js';
+import { isObjectForm } from '../internal/dual-form-args.js';
+/**
+ * Dual-form op wrapper (A-class): asserts the kernel, normalizes object form to
+ * positional form via `resolveArgs`, then delegates to the vendored
+ * implementation.
+ *
+ * P23: delegates to the shared {@link projectBrepOp} so the hand-curated face
+ * and the generated face share one projection mechanism (§4.3.2).
+ */
+function wrapDual(name, params, impl) {
+    return projectBrepOp(name, params, 'A', impl);
+}
+/**
+ * Guard-only wrapper: forwards the arguments unchanged after the kernel assert.
+ * Used for positional-first ops (booleans, evolutions) whose first argument is
+ * a shape, so the object-form discriminant never applies. The exact function
+ * type `F` (including its parameter and Result types) is preserved.
+ */
+function wrapGuarded(name, impl) {
+    const fn = (...args) => {
+        assertKernelBound(name);
+        return impl(...args);
+    };
+    return fn;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// ① primitives + booleans + evolutions
+// ─────────────────────────────────────────────────────────────────────────────
+import { box as primitiveBox, sphere as primitiveSphere, cylinder as primitiveCylinder, cone as primitiveCone, torus as primitiveTorus, ellipsoid as primitiveEllipsoid, } from '../../vendored/brepjs/topology/primitiveFns.js';
+export function box(...args) {
+    assertKernelBound('box');
+    if (isObjectForm(args)) {
+        const obj = args[0];
+        const keys = Object.keys(obj);
+        const unknownKeys = keys.filter((k) => !['size', 'width', 'depth', 'height'].includes(k));
+        if (unknownKeys.length > 0)
+            throw boxArgError(args);
+        const size = obj.size;
+        if (size !== undefined) {
+            if (typeof size === 'number')
+                return primitiveBox(size, size, size);
+            if (Array.isArray(size) && size.length === 3) {
+                const [w, d, h] = size;
+                return primitiveBox(w, d, h);
+            }
+            throw boxArgError(args);
+        }
+        const width = obj.width;
+        const depth = obj.depth;
+        const height = obj.height;
+        if (typeof width === 'number' && typeof depth === 'number' && typeof height === 'number') {
+            return primitiveBox(width, depth, height);
+        }
+        throw boxArgError(args);
+    }
+    if (args.length === 3 && args.every((a) => typeof a === 'number')) {
+        const [w, d, h] = args;
+        return primitiveBox(w, d, h);
+    }
+    throw boxArgError(args);
+}
+/** Shared E_ARGS_FORM error for {@link box} argument mismatches. */
+function boxArgError(args) {
+    return new Error('[compat:box] E_ARGS_FORM: expected box(width, depth, height), ' +
+        "box({ size: number | [w, d, h] }) or box({ width, depth, height }); got " +
+        args.map((a) => safeJson(a)).join(', '));
+}
+/** JSON stringification that never throws on cyclic or exotic values. */
+function safeJson(v) {
+    try {
+        return JSON.stringify(v) ?? String(v);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * Project the vendored `sphere(radius, options?)` verbatim (P25: the raw
+ * morph form is what portable libraries call — upstream brepjs signatures,
+ * no op projection).
+ */
+export { primitiveSphere as sphere };
+/** Project the vendored `cylinder(radius, height, options?)` verbatim. */
+export { primitiveCylinder as cylinder };
+/** Project the vendored `cone(bottomRadius, topRadius, height, options?)`. */
+export const cone = wrapDual('cone', ['bottomRadius', 'topRadius', 'height'], primitiveCone);
+/** Project the vendored `torus(majorRadius, minorRadius, options?)`. */
+export const torus = wrapDual('torus', ['majorRadius', 'minorRadius'], primitiveTorus);
+/** Project the vendored `ellipsoid(rx, ry, rz, options?)`. */
+export const ellipsoid = wrapDual('ellipsoid', ['rx', 'ry', 'rz'], primitiveEllipsoid);
+import { fuse as vendoredFuse, cut as vendoredCut, intersect as vendoredIntersect, } from '../../vendored/brepjs/topology/api.js';
+import { extrude as vendoredExtrude, revolve as vendoredRevolve, loft as vendoredLoft, } from '../../vendored/brepjs/operations/api.js';
+/** Fuse two shapeables into one 3D result. */
+export const fuse = wrapGuarded('fuse', vendoredFuse);
+/** Cut the second shapeable out of the first. */
+export const cut = wrapGuarded('cut', vendoredCut);
+/** Extrude a planar profile along a height or direction vector. */
+export const extrude = wrapGuarded('extrude', vendoredExtrude);
+/** Revolve a planar profile around an axis with optional angle. */
+export const revolve = wrapGuarded('revolve', vendoredRevolve);
+/** Loft through a set of wire profiles. */
+export const loft = wrapGuarded('loft', vendoredLoft);
+/** Intersect two shapeables (common 3D volume). */
+export const intersect = wrapGuarded('intersect', vendoredIntersect);
+// ─────────────────────────────────────────────────────────────────────────────
+// ①b library-building factories (P24, §8.1): spur gears, planetary trains, threads.
+// Both morphs of these factories are brep-only builders gated by the single-kernel
+// assert (wrapGuarded); the kernel is bound at the host boundary (D10).
+// ─────────────────────────────────────────────────────────────────────────────
+import { makeExternalGear as vendoredMakeExternalGear, makeInternalGear as vendoredMakeInternalGear, makePlanetaryGear as vendoredMakePlanetaryGear, } from '../../vendored/brepjs/gear/gearFns.js';
+import { thread as vendoredThread } from '../../vendored/brepjs/operations/threadFns.js';
+/**
+ * Build an external spur gear.
+ * @param params - the external-gear parameters (`teeth`, `moduleSize`, `thickness`, …).
+ * @returns `Ok` with the gear solid + geometry, or `Err` for invalid parameters.
+ */
+export const makeExternalGear = wrapGuarded('makeExternalGear', vendoredMakeExternalGear);
+/**
+ * Build an internal (ring) spur gear.
+ * @param params - the internal-gear parameters, including the optional ring wall thickness.
+ * @returns `Ok` with the gear solid + geometry, or `Err` for invalid parameters.
+ */
+export const makeInternalGear = wrapGuarded('makeInternalGear', vendoredMakeInternalGear);
+/**
+ * Build a planetary gear train (sun + planets + ring).
+ * @param params - the planetary-gear parameters.
+ * @returns `Ok` with the sun/planet/ring solids and mesh diagnostics, or `Err`.
+ */
+export const makePlanetaryGear = wrapGuarded('makePlanetaryGear', vendoredMakePlanetaryGear);
+/**
+ * Build a helical screw-thread ridge.
+ * @param options - the thread profile (`radius`, `pitch`, `height`, …).
+ * @returns `Ok` with the thread-ridge solid, or `Err` for invalid parameters.
+ */
+export const thread = wrapGuarded('thread', vendoredThread);
+// ─────────────────────────────────────────────────────────────────────────────
+// ② sub-shape queries + measurements
+// ─────────────────────────────────────────────────────────────────────────────
+export { getEdges, getFaces, getWires, getVertices, getShells, getSolids, getCompSolids, getBounds, vertexPosition, } from '../../vendored/brepjs/topology/topologyQueryFns.js';
+export { measureVolume, measureArea, measureLength, } from '../../vendored/brepjs/measurement/measureFns.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// ③ sketching DSL + drawing factories
+// ─────────────────────────────────────────────────────────────────────────────
+export { default as Sketcher } from '../../vendored/brepjs/sketching/sketcher.js';
+export { default as FaceSketcher } from '../../vendored/brepjs/sketching/faceSketcher.js';
+export { drawCircle, drawEllipse, drawRoundedRectangle, drawRectangle, drawSingleCircle, drawSingleEllipse, drawPolysides, drawText, } from '../../vendored/brepjs/sketching/drawingFactories.js';
+export { draw } from '../../vendored/brepjs/sketching/drawingPen.js';
+export { makeBaseBox } from '../../vendored/brepjs/sketching/shortcuts.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// ④ combinators / pure helpers / types
+// ─────────────────────────────────────────────────────────────────────────────
+export { ok, err, isOk, isErr, unwrap, unwrapOr, map, andThen, } from '../../vendored/brepjs/core/result.js';
+export { vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize, } from '../../vendored/brepjs/core/vecOps.js';
+export { createPlane, createNamedPlane, resolvePlane, } from '../../vendored/brepjs/core/planeOps.js';
+export { kernelError, validationError } from '../../vendored/brepjs/core/errors.js';
+export { DEG2RAD, RAD2DEG } from '../../vendored/brepjs/core/constants.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// ⑤ raw 2D-morph + transform + face ports (P25: sheetmetal 单一说明符面)
+//
+// The sheetmetal authoring path consumes the vendored morph semantics exactly
+// (handles in, handles out, `Result` only where the vendored chain returns
+// one). These are projected verbatim from the ported tree — same names, same
+// signatures as upstream brepjs — so portable library sources only change the
+// import specifier line (§8.2).
+// ─────────────────────────────────────────────────────────────────────────────
+import { line as rawLine, wire as rawWire, wireLoop as rawWireLoop, face as rawFace, polygon as rawPolygon, } from '../../vendored/brepjs/topology/primitiveFns.js';
+import { outerWire as rawOuterWire, getSurfaceType as rawSurfaceType, pointOnSurface as rawPointOnSurface, normalAt as rawNormalAt, faceCenter as rawFaceCenter, } from '../../vendored/brepjs/topology/faceFns.js';
+import { sharedEdges as rawSharedEdges } from '../../vendored/brepjs/topology/adjacencyFns.js';
+import { curveStartPoint as rawCurveStartPoint, curveEndPoint as rawCurveEndPoint, } from '../../vendored/brepjs/topology/curveFns.js';
+import { translate as rawTranslate } from '../../vendored/brepjs/topology/transformFns.js';
+import { rotate as rawRotate } from '../../vendored/brepjs/topology/transformFns.js';
+import { isSolid as rawIsSolid } from '../../vendored/brepjs/core/shapeTypes.js';
+import { isPlanarWire as rawIsPlanarWire } from '../../vendored/brepjs/core/validityTypes.js';
+import { isValid as rawIsValid } from '../../vendored/brepjs/topology/healingFns.js';
+export { rawLine as line, rawWire as wire, rawWireLoop as wireLoop, rawFace as face, rawPolygon as polygon, rawOuterWire as outerWire, rawSurfaceType as getSurfaceType, rawPointOnSurface as pointOnSurface, rawNormalAt as normalAt, rawFaceCenter as faceCenter, rawSharedEdges as sharedEdges, rawCurveStartPoint as curveStartPoint, rawCurveEndPoint as curveEndPoint, rawTranslate as translate, rawIsSolid as isSolid, rawIsPlanarWire as isPlanarWire, rawIsValid as isValid, };
+// Upstream brepjs 18's `rotate` takes an axis through an `{ at, axis }` options
+// object; the vendored tree (P5-locked commit) is the four-argument positional
+// form. Export the upstream-aligned wrap so library code written for brepjs
+// rotates with `rotate(shape, angle, { at?, axis? })`.
+/**
+ * Rotate a shape by an angle in degrees around an axis.
+ * @param shape - The shape to rotate.
+ * @param angle - Rotation angle in degrees.
+ * @param options - Axis and pivot (`at`) for the rotation; defaults to the Z
+ * axis through the origin, matching upstream brepjs.
+ * @returns A new rotated shape.
+ */
+export function rotate(shape, angle, options = {}) {
+    return rawRotate(shape, angle, options.at ?? [0, 0, 0], options.axis ?? [0, 0, 1]);
+}
+//# sourceMappingURL=index.js.map

package/dist/api/compat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/compat/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * BREP-TS compatibility surface (P21).\n *\n * Projects the vendored BREP TS tree onto four stable groups so library authors\n * can write `import { box, fuse, Sketcher, ok } from this module` and call it\n * upstream-style:\n *\n *   ① op        — solid primitives + boolean / evolution operations\n *   ② topology  — sub-shape queries + measurements (plus the Bounds3D type)\n *   ③ sketching — stateful Sketcher / FaceSketcher DSL + drawing factories\n *   ④ combinators / types — result, vector, plane, errors, constants, types\n *\n * Every symbol is a projection (re-export or a thin dual-form wrapper) from the\n * ported tree: no reimplementation. The `.js` specifiers are the repo\n * convention (TypeScript maps `.js` → `.ts`).\n *\n * Semantic wraps (P23: both live in `api/internal/compat-projection.ts` so the\n * generated face and this hand-curated face share one mechanism):\n * - single-kernel assert: every modeling op asserts a bound BREP kernel first\n *   (see `assertKernelBound`); `getBackends()` may throw before configuration,\n *   so it is guarded and falls back to the occt-kernel binding flag.\n * - dual argument forms: object form normalizes to positional form via the\n *   shared `resolveArgs` discriminant; object keys outside the declared\n *   parameter table throw the shared `E_ARGS_FORM` token.\n * - `box` is the hand-written dual-form sample: positional\n *   `box(width, depth, height)` and `box({ size })` / `box({ width, depth,\n *   height })` both forward to the vendored primitive in its native dimension\n *   order (width = X, depth = Y, height = Z — confirm against\n *   `primitiveFns#box`), so every accepted form yields identical geometry.\n */\n\nimport { assertKernelBound, projectBrepOp } from '../internal/compat-projection'\nimport { isObjectForm } from '../internal/dual-form-args'\n\nimport type { ValidSolid } from '../../vendored/brepjs/core/shapeTypes.js'\n\n/** Signature of a compat op projection (inputs normalized before the call). */\ntype CompatOp = (...args: unknown[]) => unknown\n\n/**\n * Dual-form op wrapper (A-class): asserts the kernel, normalizes object form to\n * positional form via `resolveArgs`, then delegates to the vendored\n * implementation.\n *\n * P23: delegates to the shared {@link projectBrepOp} so the hand-curated face\n * and the generated face share one projection mechanism (§4.3.2).\n */\nfunction wrapDual<R>(\n  name: string,\n  params: string[],\n  impl: (...args: unknown[]) => R\n): CompatOp {\n  return projectBrepOp(name, params, 'A', impl as (...args: never[]) => unknown)\n}\n\n/**\n * Guard-only wrapper: forwards the arguments unchanged after the kernel assert.\n * Used for positional-first ops (booleans, evolutions) whose first argument is\n * a shape, so the object-form discriminant never applies. The exact function\n * type `F` (including its parameter and Result types) is preserved.\n */\nfunction wrapGuarded<F>(name: string, impl: F): F {\n  const fn: (...args: unknown[]) => unknown = (...args: unknown[]) => {\n    assertKernelBound(name)\n    return (impl as (...args: unknown[]) => unknown)(...args)\n  }\n  return fn as unknown as F\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ① primitives + booleans + evolutions\n// ─────────────────────────────────────────────────────────────────────────────\n\nimport {\n  box as primitiveBox,\n  sphere as primitiveSphere,\n  cylinder as primitiveCylinder,\n  cone as primitiveCone,\n  torus as primitiveTorus,\n  ellipsoid as primitiveEllipsoid,\n} from '../../vendored/brepjs/topology/primitiveFns.js'\n\n/**\n * Create a solid box.\n *\n * Positional form `box(width, depth, height)` uses the vendor's native\n * dimension order — X = width, Y = depth,\n * Z = height (the vendored `primitiveFns#box` dimension order; width/height are\n * NOT swapped). See the overload below for the object form.\n *\n * @param width - side length along X.\n * @param depth - side length along Y.\n * @param height - side length along Z.\n * @returns a new valid solid box.\n */\nexport function box(width: number, depth: number, height: number): ValidSolid\n/**\n * Create a solid box from an object form.\n *\n * Accepts `box({ size })` where `size` is a number (cube) or a\n * `[width, depth, height]` triple, or `box({ width, depth, height })`. Every\n * accepted form forwards to `primitiveBox(width, depth, height)`, so equal\n * dimension values always produce identical geometry.\n *\n * @param options - the dimension set: `size` (a cube edge or a triple) or\n * `width`/`depth`/`height` sides.\n * @returns a new valid solid box.\n * @throws An `Error` whose message contains the shared `E_ARGS_FORM` token when\n * no form matches (e.g. `box('x')`, `box()`, or unknown object keys).\n */\nexport function box(options: BoxDimensions): ValidSolid\nexport function box(...args: unknown[]): ValidSolid {\n  assertKernelBound('box')\n  if (isObjectForm(args)) {\n    const obj = args[0] as Record<string, unknown>\n    const keys = Object.keys(obj)\n    const unknownKeys = keys.filter((k) => !['size', 'width', 'depth', 'height'].includes(k))\n    if (unknownKeys.length > 0) throw boxArgError(args)\n    const size = obj.size\n    if (size !== undefined) {\n      if (typeof size === 'number') return primitiveBox(size, size, size)\n      if (Array.isArray(size) && size.length === 3) {\n        const [w, d, h] = size as [number, number, number]\n        return primitiveBox(w, d, h)\n      }\n      throw boxArgError(args)\n    }\n    const width = obj.width\n    const depth = obj.depth\n    const height = obj.height\n    if (typeof width === 'number' && typeof depth === 'number' && typeof height === 'number') {\n      return primitiveBox(width, depth, height)\n    }\n    throw boxArgError(args)\n  }\n  if (args.length === 3 && args.every((a) => typeof a === 'number')) {\n    const [w, d, h] = args as [number, number, number]\n    return primitiveBox(w, d, h)\n  }\n  throw boxArgError(args)\n}\n\n/** Object-form input accepted by {@link box}. */\nexport interface BoxDimensions {\n  /** All three sides as one number (cube) or a `[width, depth, height]` triple. */\n  size?: number | [number, number, number]\n  /** Side length along X. */\n  width?: number\n  /** Side length along Y. */\n  depth?: number\n  /** Side length along Z. */\n  height?: number\n}\n\n/** Shared E_ARGS_FORM error for {@link box} argument mismatches. */\nfunction boxArgError(args: unknown[]): Error {\n  return new Error(\n    '[compat:box] E_ARGS_FORM: expected box(width, depth, height), ' +\n      \"box({ size: number | [w, d, h] }) or box({ width, depth, height }); got \" +\n      args.map((a) => safeJson(a)).join(', ')\n  )\n}\n\n/** JSON stringification that never throws on cyclic or exotic values. */\nfunction safeJson(v: unknown): string {\n  try {\n    return JSON.stringify(v) ?? String(v)\n  } catch {\n    return '[unserializable]'\n  }\n}\n\n/**\n * Project the vendored `sphere(radius, options?)` verbatim (P25: the raw\n * morph form is what portable libraries call — upstream brepjs signatures,\n * no op projection).\n */\nexport { primitiveSphere as sphere }\n/** Project the vendored `cylinder(radius, height, options?)` verbatim. */\nexport { primitiveCylinder as cylinder }\n/** Project the vendored `cone(bottomRadius, topRadius, height, options?)`. */\nexport const cone = wrapDual(\n  'cone',\n  ['bottomRadius', 'topRadius', 'height'],\n  primitiveCone as CompatOp\n)\n/** Project the vendored `torus(majorRadius, minorRadius, options?)`. */\nexport const torus = wrapDual('torus', ['majorRadius', 'minorRadius'], primitiveTorus as CompatOp)\n/** Project the vendored `ellipsoid(rx, ry, rz, options?)`. */\nexport const ellipsoid = wrapDual('ellipsoid', ['rx', 'ry', 'rz'], primitiveEllipsoid as CompatOp)\n\nimport {\n  fuse as vendoredFuse,\n  cut as vendoredCut,\n  intersect as vendoredIntersect,\n} from '../../vendored/brepjs/topology/api.js'\nimport {\n  extrude as vendoredExtrude,\n  revolve as vendoredRevolve,\n  loft as vendoredLoft,\n} from '../../vendored/brepjs/operations/api.js'\n\n/** Fuse two shapeables into one 3D result. */\nexport const fuse = wrapGuarded('fuse', vendoredFuse)\n/** Cut the second shapeable out of the first. */\nexport const cut = wrapGuarded('cut', vendoredCut)\n/** Extrude a planar profile along a height or direction vector. */\nexport const extrude = wrapGuarded('extrude', vendoredExtrude)\n/** Revolve a planar profile around an axis with optional angle. */\nexport const revolve = wrapGuarded('revolve', vendoredRevolve)\n/** Loft through a set of wire profiles. */\nexport const loft = wrapGuarded('loft', vendoredLoft)\n\n/** Intersect two shapeables (common 3D volume). */\nexport const intersect = wrapGuarded('intersect', vendoredIntersect)\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ①b library-building factories (P24, §8.1): spur gears, planetary trains, threads.\n// Both morphs of these factories are brep-only builders gated by the single-kernel\n// assert (wrapGuarded); the kernel is bound at the host boundary (D10).\n// ─────────────────────────────────────────────────────────────────────────────\n\nimport {\n  makeExternalGear as vendoredMakeExternalGear,\n  makeInternalGear as vendoredMakeInternalGear,\n  makePlanetaryGear as vendoredMakePlanetaryGear,\n} from '../../vendored/brepjs/gear/gearFns.js'\nimport { thread as vendoredThread } from '../../vendored/brepjs/operations/threadFns.js'\n\n/**\n * Build an external spur gear.\n * @param params - the external-gear parameters (`teeth`, `moduleSize`, `thickness`, …).\n * @returns `Ok` with the gear solid + geometry, or `Err` for invalid parameters.\n */\nexport const makeExternalGear = wrapGuarded('makeExternalGear', vendoredMakeExternalGear)\n/**\n * Build an internal (ring) spur gear.\n * @param params - the internal-gear parameters, including the optional ring wall thickness.\n * @returns `Ok` with the gear solid + geometry, or `Err` for invalid parameters.\n */\nexport const makeInternalGear = wrapGuarded('makeInternalGear', vendoredMakeInternalGear)\n/**\n * Build a planetary gear train (sun + planets + ring).\n * @param params - the planetary-gear parameters.\n * @returns `Ok` with the sun/planet/ring solids and mesh diagnostics, or `Err`.\n */\nexport const makePlanetaryGear = wrapGuarded('makePlanetaryGear', vendoredMakePlanetaryGear)\n/**\n * Build a helical screw-thread ridge.\n * @param options - the thread profile (`radius`, `pitch`, `height`, …).\n * @returns `Ok` with the thread-ridge solid, or `Err` for invalid parameters.\n */\nexport const thread = wrapGuarded('thread', vendoredThread)\n\nexport type {\n  ExternalGearParams,\n  InternalGearParams,\n  PlanetaryGearParams,\n  GearResult,\n  PlanetaryGearAssembly,\n} from '../../vendored/brepjs/gear/gearFns.js'\nexport type { ThreadOptions } from '../../vendored/brepjs/operations/threadFns.js'\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ② sub-shape queries + measurements\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport {\n  getEdges,\n  getFaces,\n  getWires,\n  getVertices,\n  getShells,\n  getSolids,\n  getCompSolids,\n  getBounds,\n  vertexPosition,\n} from '../../vendored/brepjs/topology/topologyQueryFns.js'\n\nexport type { Bounds3D } from '../../vendored/brepjs/topology/topologyQueryFns.js'\n\nexport {\n  measureVolume,\n  measureArea,\n  measureLength,\n} from '../../vendored/brepjs/measurement/measureFns.js'\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ③ sketching DSL + drawing factories\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport { default as Sketcher } from '../../vendored/brepjs/sketching/sketcher.js'\nexport { default as FaceSketcher } from '../../vendored/brepjs/sketching/faceSketcher.js'\n\nexport {\n  drawCircle,\n  drawEllipse,\n  drawRoundedRectangle,\n  drawRectangle,\n  drawSingleCircle,\n  drawSingleEllipse,\n  drawPolysides,\n  drawText,\n} from '../../vendored/brepjs/sketching/drawingFactories.js'\n\nexport { draw } from '../../vendored/brepjs/sketching/drawingPen.js'\nexport { makeBaseBox } from '../../vendored/brepjs/sketching/shortcuts.js'\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ④ combinators / pure helpers / types\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport {\n  ok,\n  err,\n  isOk,\n  isErr,\n  unwrap,\n  unwrapOr,\n  map,\n  andThen,\n} from '../../vendored/brepjs/core/result.js'\nexport type { Result, Ok, Err } from '../../vendored/brepjs/core/result.js'\n\nexport {\n  vecAdd,\n  vecSub,\n  vecScale,\n  vecDot,\n  vecCross,\n  vecLength,\n  vecNormalize,\n} from '../../vendored/brepjs/core/vecOps.js'\n\nexport {\n  createPlane,\n  createNamedPlane,\n  resolvePlane,\n} from '../../vendored/brepjs/core/planeOps.js'\n\nexport { kernelError, validationError } from '../../vendored/brepjs/core/errors.js'\nexport type { BrepError } from '../../vendored/brepjs/core/errors.js'\n\nexport { DEG2RAD, RAD2DEG } from '../../vendored/brepjs/core/constants.js'\n\nexport type {\n  Vertex,\n  Edge,\n  Wire,\n  Face,\n  Shell,\n  Solid,\n  CompSolid,\n  Shape3D,\n  ValidSolid,\n  ClosedWire,\n  AnyShape,\n} from '../../vendored/brepjs/core/shapeTypes.js'\n\nexport type { GearGeometry } from '../../vendored/brepjs/gear/gearMath.js'\n\nexport type { Plane, PlaneName, PlaneInput } from '../../vendored/brepjs/core/planeTypes.js'\n\nexport type { Vec3, PointInput } from '../../vendored/brepjs/core/types.js'\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ⑤ raw 2D-morph + transform + face ports (P25: sheetmetal 单一说明符面)\n//\n// The sheetmetal authoring path consumes the vendored morph semantics exactly\n// (handles in, handles out, `Result` only where the vendored chain returns\n// one). These are projected verbatim from the ported tree — same names, same\n// signatures as upstream brepjs — so portable library sources only change the\n// import specifier line (§8.2).\n// ─────────────────────────────────────────────────────────────────────────────\n\nimport {\n  line as rawLine,\n  wire as rawWire,\n  wireLoop as rawWireLoop,\n  face as rawFace,\n  polygon as rawPolygon,\n} from '../../vendored/brepjs/topology/primitiveFns.js'\nimport {\n  outerWire as rawOuterWire,\n  getSurfaceType as rawSurfaceType,\n  pointOnSurface as rawPointOnSurface,\n  normalAt as rawNormalAt,\n  faceCenter as rawFaceCenter,\n} from '../../vendored/brepjs/topology/faceFns.js'\nimport { sharedEdges as rawSharedEdges } from '../../vendored/brepjs/topology/adjacencyFns.js'\nimport {\n  curveStartPoint as rawCurveStartPoint,\n  curveEndPoint as rawCurveEndPoint,\n} from '../../vendored/brepjs/topology/curveFns.js'\nimport { translate as rawTranslate } from '../../vendored/brepjs/topology/transformFns.js'\nimport { rotate as rawRotate } from '../../vendored/brepjs/topology/transformFns.js'\nimport { isSolid as rawIsSolid } from '../../vendored/brepjs/core/shapeTypes.js'\nimport { isPlanarWire as rawIsPlanarWire } from '../../vendored/brepjs/core/validityTypes.js'\nimport { isValid as rawIsValid } from '../../vendored/brepjs/topology/healingFns.js'\nimport type { AnyShape } from '../../vendored/brepjs/core/shapeTypes.js'\nimport type { Vec3 } from '../../vendored/brepjs/core/types.js'\n\nexport {\n  rawLine as line,\n  rawWire as wire,\n  rawWireLoop as wireLoop,\n  rawFace as face,\n  rawPolygon as polygon,\n  rawOuterWire as outerWire,\n  rawSurfaceType as getSurfaceType,\n  rawPointOnSurface as pointOnSurface,\n  rawNormalAt as normalAt,\n  rawFaceCenter as faceCenter,\n  rawSharedEdges as sharedEdges,\n  rawCurveStartPoint as curveStartPoint,\n  rawCurveEndPoint as curveEndPoint,\n  rawTranslate as translate,\n  rawIsSolid as isSolid,\n  rawIsPlanarWire as isPlanarWire,\n  rawIsValid as isValid,\n}\n\n// Upstream brepjs 18's `rotate` takes an axis through an `{ at, axis }` options\n// object; the vendored tree (P5-locked commit) is the four-argument positional\n// form. Export the upstream-aligned wrap so library code written for brepjs\n// rotates with `rotate(shape, angle, { at?, axis? })`.\n/**\n * Rotate a shape by an angle in degrees around an axis.\n * @param shape - The shape to rotate.\n * @param angle - Rotation angle in degrees.\n * @param options - Axis and pivot (`at`) for the rotation; defaults to the Z\n * axis through the origin, matching upstream brepjs.\n * @returns A new rotated shape.\n */\nexport function rotate<T extends AnyShape>(\n  shape: T,\n  angle: number,\n  options: { at?: Vec3; axis?: Vec3 } = {}\n): T {\n  return rawRotate(shape, angle, options.at ?? [0, 0, 0], options.axis ?? [0, 0, 1]);\n}"]}

package/dist/api/compound.d.ts

@@ -0,0 +1,108 @@
+/**
+ * stdlib compound — group/assembly 库函数（compound Shape + AssemblyBehavior）
+ *
+ *
+ * 从 src/ops/assemble.ts 迁出并改写为 stdlib 形态：
+ * - `group(params)` → compound Shape（kind='compound'，children 为成员 Shape 引用）
+ * - `assembly(params)` → compound Shape + AssemblyBehavior（约束列表 + solve 方法）
+ * - 装配求解（P1 起）委派 api/assembly/（brepjs solverAdapter 内核）：
+ *   do_assemble/solve 触发求解 → 引擎应用
+ *   （mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。
+ *   P2-f5：旧装配算法与自有四元数实现已删除，求解全链路走 api/assembly。
+ *
+ * compound 自身无独立 mesh——几何由 children 承载，意义是结构（层级）。
+ * do_assemble 编译为 `await ctx.<asm>.do_assemble()`：调用 compound 的求解方法，
+ * 对约束定位的成员施加装配变换（mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。
+ */
+import type { Shape } from '../mesh/types.js';
+import { type CompoundShape } from '../shape.js';
+import { type AssemblyTransform } from '../runtime-state.js';
+import { type AssemblySolveResult } from './assembly/solve.js';
+import { type JointSpec } from './assembly/joints.js';
+import type { AssemblyConstraint } from './assembly/types.js';
+import type { SolverStyle } from './assembly/solvers/types.js';
+/** Parameters for the `group` stdlib function: an optional name and ordered members. */
+export interface GroupParams {
+    name?: string;
+    /** Compound members: read-only references, never mutated by group/assembly. */
+    members?: Shape[];
+    memberNames?: string[];
+}
+/** Parameters for the `assembly` stdlib function: group params plus assembly constraints. */
+export interface AssemblyParams extends GroupParams {
+    constraints?: AssemblyConstraint[];
+    /** P3：运动副声明（可选；parent/child 必须是 members 里的名字）。 */
+    joints?: JointSpec[];
+    /** P3：驱动值覆盖（键 = child 成员名；值 = 主 DOF 数值或多 DOF 数组）。 */
+    drive?: Record<string, number | number[]>;
+    /** cq-compat：成员颜色（sRGB 0..1），导出 STEP 时写入 XCAF。 */
+    memberColors?: Record<string, [number, number, number]>;
+    /** P1：求解风格。'chain'（默认，vendored brepjs 解析链式）| 'global'（CadQuery 兼容全局最小二乘）。 */
+    solver?: SolverStyle;
+}
+export type { AssemblyConstraint, FaceMateConstraint, FaceMateFace, EntityRef, FaceRef, EdgeRef, MateConstraint, AlignConstraint, CoincidentConstraint, ConcentricConstraint, DistanceConstraint, AngleConstraint, ParallelConstraint, PerpendicularConstraint, FixedConstraint, StructuralConstraint, AssemblyVec3, } from './assembly/types.js';
+export type { AssemblySolveResult } from './assembly/solve.js';
+export { applyTransform } from '../mesh/rigid-transform.js';
+/** Behavior attached to an assembly compound: its members, constraints, and solver. */
+export interface AssemblyBehavior {
+    name?: string;
+    memberNames: string[];
+    constraints: AssemblyConstraint[];
+    /** P3：运动副声明（无 joints 时为空数组）。 */
+    joints?: JointSpec[];
+    /** P3：驱动值覆盖（键 = child 成员名；缺省 undefined = 用 joint 存储值）。 */
+    drive?: Record<string, number | number[]>;
+    /** cq-compat：成员颜色（sRGB 0..1）。 */
+    memberColors?: Record<string, [number, number, number]>;
+    /** P1：求解风格。 */
+    solver?: SolverStyle;
+    /** 只求解（P6）：返回"成员下标 → 变换"列表。不改写入参、不传播；可重复调用（幂等）。 */
+    solve(): AssemblyTransform[];
+    /** 只求解并带诊断量（P1）：transforms + dof/converged/unsupported（方案 P1⑤）；P3 增 kinematics/warnings。 */
+    solveDetailed(): AssemblySolveResult;
+}
+/**
+ * `cad.group({ name, members })` → compound Shape。
+ * members 是成员 Shape（编译产物 ctx.<var> 引用），成员名经 keep() 反查。
+ *
+ * 函数体 keep 声明（keep-syntax 设计 §2.5）：group 保留其成员且可见（R6）。
+ */
+/**
+ * 分组：零约束，保持当前布局。结构语句，无几何输出，成员用变量名引用。
+ * @group 结构
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name group
+ * @returns CompoundShape 复合几何（kind='compound'，children 为成员 Shape 引用）。
+ * @param params.name - 组名。type:string
+ * @param params.members - 成员（编译产物 ctx.<var> 引用；结构语句里是裸变量引用，非字符串数组）。type:Shape[]
+ * @note members 在 .fai.js 里是裸变量引用（编译为 ctx.<var>），字符串数组形态的成员名经 keep() 反查兼容历史 IR。
+ * @example
+ * const part0 = cad.box(30, 20, 10, { centered: true })
+ * cad.group({ name: '底板组', members: [part0] })
+  */
+export declare function group(params: GroupParams): CompoundShape;
+/**
+ * 装配：成员 + 约束。结构语句，无几何输出，成员用变量名引用、实体用 EntityRef / 拓扑引用。
+ * 求解内核复用 vendored brepjs solverAdapter.solveConstraints（链式拓扑调度 / DOF / converged /
+ * unsupported 诊断）；输出为 per-member 终态变换（每成员一条，恒等位姿不输出）。
+ * @group 结构
+ * @inputs 1
+ * @async false
+ * @qual warn
+ * @name assembly
+ * @returns CompoundShape + AssemblyBehavior（含 do_assemble / solve 方法）。
+ * @note 约束类型（a=参考、b=从动，移动 b 去贴合 a）：`mate` 面对面贴合（法向反向+面中心重合，遗留 face_mate 的新名，求解降级为 concentric + 轴编码）；`align` 同向对齐（法向同向+面中心重合）；`coincident` 共面/共点/共线（保留面内 2 个平移 DOF）；`concentric` 轴重合（孔轴配合，圆柱/圆锥面需 hint.axis，直边/圆边需 EdgeHint.axis）；`distance` 定距（mm，带 value）；`angle` 夹角（deg，带 value）；`parallel`/`perpendicular` 平行/垂直（angle 0°/90° 语法糖）；`fixed` 锚定部件（地基）；`face_mate` 为遗留别名（规范化为 mate，新代码不再使用）。
+ * @note EntityRef 四种形态：`{ part, face: { topoRef } | { surfaceType?, center, normal } }`、`{ part, edge: { topoRef } | { axis: { origin, direction } } }`、`{ part, point: [x,y,z] }`、`{ part, faceIndex }`（1 起，仅调试简写）。
+ * @note 不收敛（实体类型不匹配/环/参考不可达）→ 抛错并带 unsupported 明细；成员名为空串 → 求解前抛错；mesh 快照缺 axis 的圆柱/圆锥面作轴实体 → E_TOPO_NOT_FOUND（绝不静默降级）。`mate`（中心重合）与 `coincident`（只共面）是两种不同语义，不互相映射。
+ * @note 早期文档/示例曾用 `fixedPartId`/`movingPartId`/`faceRowIndex`/`faceId`/`invalid`——这些键在代码中不存在。真实契约是 `fixedPartName`/`movingPartName` + `fixedFace`/`movingFace`（遗留 face_mate）。`faceId` 字段随 §6.2 移除，不再写入。
+ * @param params.name - 装配名。type:string
+ * @param params.members - 成员（裸变量引用）。type:Shape[]
+ * @param params.constraints - 约束数组（遗留 face_mate 形态或上述新形态 { type, a, b }）。type:AssemblyConstraint[]
+ * @example
+ * let asm1 = cad.assembly({ name: '主轴组件', members: [part0, part1, part2], constraints: [ { type: 'fixed', part: 'part0' }, { type: 'mate', a: { part: 'part0', face: { topoRef: { kind: 'face', origin: 'part0', role: 'box:top', hint: { kind: 'face', surfaceType: 'plane' } } } }, b: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: 'box:bottom', hint: { kind: 'face', surfaceType: 'plane' } } } } }, { type: 'concentric', a: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: '', hint: { kind: 'face', surfaceType: 'cylinder' } } } }, b: { part: 'part2', face: { topoRef: { kind: 'face', origin: 'part2', role: 'cylinder:lateral', hint: { kind: 'face', surfaceType: 'cylinder' } } } } } ] })
+ * asm1.solve()
+  */
+export declare function assembly(params: AssemblyParams): CompoundShape;
+//# sourceMappingURL=compound.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compound.d.ts","sourceRoot":"","sources":["../../src/api/compound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAwC,KAAK,aAAa,EAAE,MAAM,UAAU,CAAA;AACnF,OAAO,EAA4E,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACnI,OAAO,EAA8B,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAEvF,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAI3D,wFAAwF;AACxF,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+EAA+E;IAC/E,OAAO,CAAC,EAAE,KAAK,EAAE,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAClC,kDAAkD;IAClD,MAAM,CAAC,EAAE,SAAS,EAAE,CAAA;IACpB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;IACzC,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACvD,6EAA6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAID,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,YAAY,GACb,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAQ3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAIxD,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,WAAW,EAAE,kBAAkB,EAAE,CAAA;IACjC,gCAAgC;IAChC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAA;IACpB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;IACzC,iCAAiC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACvD,eAAe;IACf,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,mDAAmD;IACnD,KAAK,IAAI,iBAAiB,EAAE,CAAA;IAC5B,4FAA4F;IAC5F,aAAa,IAAI,mBAAmB,CAAA;CACrC;AAyCD;;;;;GAKG;AACH;;;;;;;;;;;;;;IAcI;AACJ,wBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAcxD;AAED;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAqD9D"}

package/dist/api/compound.js

@@ -0,0 +1,162 @@
+/**
+ * stdlib compound — group/assembly 库函数（compound Shape + AssemblyBehavior）
+ *
+ *
+ * 从 src/ops/assemble.ts 迁出并改写为 stdlib 形态：
+ * - `group(params)` → compound Shape（kind='compound'，children 为成员 Shape 引用）
+ * - `assembly(params)` → compound Shape + AssemblyBehavior（约束列表 + solve 方法）
+ * - 装配求解（P1 起）委派 api/assembly/（brepjs solverAdapter 内核）：
+ *   do_assemble/solve 触发求解 → 引擎应用
+ *   （mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。
+ *   P2-f5：旧装配算法与自有四元数实现已删除，求解全链路走 api/assembly。
+ *
+ * compound 自身无独立 mesh——几何由 children 承载，意义是结构（层级）。
+ * do_assemble 编译为 `await ctx.<asm>.do_assemble()`：调用 compound 的求解方法，
+ * 对约束定位的成员施加装配变换（mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。
+ */
+import { compound as makeCompound, ensureSlot } from '../shape.js';
+import { keep, nameOf, setPendingAssemblyTransforms, setPendingAssemblyKinematics } from '../runtime-state.js';
+import { solveAssemblyAndKinematics } from './assembly/solve.js';
+import { validateConstraints } from './assembly/validate.js';
+import { buildKinematicTree } from './assembly/joints.js';
+// ── 求解器 ──
+// P2-f5：旧装配算法与自有四元数实现已整体删除——旋转计算一律走
+// brepjs utils/quaternion.ts，输出经 api/assembly/pose.ts fromBrepjsQuat 重排。
+// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：
+// 引擎不得 import stdlib/compound；公共 API 经本 re-export 保持）。
+export { applyTransform } from '../mesh/rigid-transform.js';
+/**
+ * 纯求解（P6：求解 ≠ 传播）：委派 api/assembly/solveAssembly（P1 起）。
+ * 不修改任何输入、不触碰引擎状态——引擎负责应用变换并让下游失效重算（F2）。
+ *
+ * 约束形态（方案 §5）：
+ * - 遗留 face_mate：规范化为 mate 后降级为 brepjs concentric + 轴编码求解（§3.7.2）；
+ * - 新形态 mate/align/coincident/concentric/distance/angle/parallel/perpendicular/fixed；
+ * - 面参数 `{ topoRef }` 执行期解析（BREP 现场/mesh 行快照），旧 `{ center, normal }`
+ *   快照直接使用（兼容已持久化的历史脚本）；
+ * - 输出为 per-member 终态（L6 修复），锚定成员不输出变换。
+ */
+function solveTransforms(members, behavior) {
+    return solveAssemblyAndKinematics(members, behavior.memberNames, behavior.constraints, behavior.joints ?? [], behavior.drive, { solver: behavior.solver, name: behavior.name }).transforms;
+}
+// ── group / assembly 库函数 ──
+/**
+ * 成员名推导：显式 memberNames 兼容旧手工构造 IR；否则经 keep() 反查
+ * （P3 起经 keep()/nameOfShapes 反查成员名——库不再访问执行上下文，F1）。
+ */
+function memberNamesOf(params, members) {
+    if (Array.isArray(params.memberNames) && params.memberNames.length > 0) {
+        return params.memberNames;
+    }
+    return members.map((m) => {
+        // 兼容字符串形态的 members（历史 IR 直传 partName）：字符串本身就是名字
+        if (typeof m === 'string')
+            return m;
+        return String(nameOf(m) ?? '');
+    });
+}
+/**
+ * `cad.group({ name, members })` → compound Shape。
+ * members 是成员 Shape（编译产物 ctx.<var> 引用），成员名经 keep() 反查。
+ *
+ * 函数体 keep 声明（keep-syntax 设计 §2.5）：group 保留其成员且可见（R6）。
+ */
+/**
+ * 分组：零约束，保持当前布局。结构语句，无几何输出，成员用变量名引用。
+ * @group 结构
+ * @inputs 1
+ * @async false
+ * @qual ok
+ * @name group
+ * @returns CompoundShape 复合几何（kind='compound'，children 为成员 Shape 引用）。
+ * @param params.name - 组名。type:string
+ * @param params.members - 成员（编译产物 ctx.<var> 引用；结构语句里是裸变量引用，非字符串数组）。type:Shape[]
+ * @note members 在 .fai.js 里是裸变量引用（编译为 ctx.<var>），字符串数组形态的成员名经 keep() 反查兼容历史 IR。
+ * @example
+ * const part0 = cad.box(30, 20, 10, { centered: true })
+ * cad.group({ name: '底板组', members: [part0] })
+  */
+export function group(params) {
+    const members = params.members ?? [];
+    if (members.length > 0)
+        keep(...members);
+    const memberNames = memberNamesOf(params, members);
+    const c = makeCompound(members);
+    // 挂最小 behavior（memberNames 供 ExecutionResult.compounds 结构输出；group 无约束）
+    ensureSlot(c).behavior = {
+        memberNames,
+        constraints: [],
+        joints: [],
+        solve: () => [],
+        solveDetailed: () => ({ transforms: [], dof: 0, converged: true, unsupported: [] }),
+    };
+    return c;
+}
+/**
+ * 装配：成员 + 约束。结构语句，无几何输出，成员用变量名引用、实体用 EntityRef / 拓扑引用。
+ * 求解内核复用 vendored brepjs solverAdapter.solveConstraints（链式拓扑调度 / DOF / converged /
+ * unsupported 诊断）；输出为 per-member 终态变换（每成员一条，恒等位姿不输出）。
+ * @group 结构
+ * @inputs 1
+ * @async false
+ * @qual warn
+ * @name assembly
+ * @returns CompoundShape + AssemblyBehavior（含 do_assemble / solve 方法）。
+ * @note 约束类型（a=参考、b=从动，移动 b 去贴合 a）：`mate` 面对面贴合（法向反向+面中心重合，遗留 face_mate 的新名，求解降级为 concentric + 轴编码）；`align` 同向对齐（法向同向+面中心重合）；`coincident` 共面/共点/共线（保留面内 2 个平移 DOF）；`concentric` 轴重合（孔轴配合，圆柱/圆锥面需 hint.axis，直边/圆边需 EdgeHint.axis）；`distance` 定距（mm，带 value）；`angle` 夹角（deg，带 value）；`parallel`/`perpendicular` 平行/垂直（angle 0°/90° 语法糖）；`fixed` 锚定部件（地基）；`face_mate` 为遗留别名（规范化为 mate，新代码不再使用）。
+ * @note EntityRef 四种形态：`{ part, face: { topoRef } | { surfaceType?, center, normal } }`、`{ part, edge: { topoRef } | { axis: { origin, direction } } }`、`{ part, point: [x,y,z] }`、`{ part, faceIndex }`（1 起，仅调试简写）。
+ * @note 不收敛（实体类型不匹配/环/参考不可达）→ 抛错并带 unsupported 明细；成员名为空串 → 求解前抛错；mesh 快照缺 axis 的圆柱/圆锥面作轴实体 → E_TOPO_NOT_FOUND（绝不静默降级）。`mate`（中心重合）与 `coincident`（只共面）是两种不同语义，不互相映射。
+ * @note 早期文档/示例曾用 `fixedPartId`/`movingPartId`/`faceRowIndex`/`faceId`/`invalid`——这些键在代码中不存在。真实契约是 `fixedPartName`/`movingPartName` + `fixedFace`/`movingFace`（遗留 face_mate）。`faceId` 字段随 §6.2 移除，不再写入。
+ * @param params.name - 装配名。type:string
+ * @param params.members - 成员（裸变量引用）。type:Shape[]
+ * @param params.constraints - 约束数组（遗留 face_mate 形态或上述新形态 { type, a, b }）。type:AssemblyConstraint[]
+ * @example
+ * let asm1 = cad.assembly({ name: '主轴组件', members: [part0, part1, part2], constraints: [ { type: 'fixed', part: 'part0' }, { type: 'mate', a: { part: 'part0', face: { topoRef: { kind: 'face', origin: 'part0', role: 'box:top', hint: { kind: 'face', surfaceType: 'plane' } } } }, b: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: 'box:bottom', hint: { kind: 'face', surfaceType: 'plane' } } } } }, { type: 'concentric', a: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: '', hint: { kind: 'face', surfaceType: 'cylinder' } } } }, b: { part: 'part2', face: { topoRef: { kind: 'face', origin: 'part2', role: 'cylinder:lateral', hint: { kind: 'face', surfaceType: 'cylinder' } } } } } ] })
+ * asm1.solve()
+  */
+export function assembly(params) {
+    const members = params.members ?? [];
+    const constraints = params.constraints ?? [];
+    const joints = params.joints ?? [];
+    const drive = params.drive;
+    // P2-f1：约束参数运行期校验（keep() 之前，fail-fast；规则见 api/assembly/validate.ts V1–V6）
+    const memberNames = memberNamesOf(params, members);
+    validateConstraints(constraints, memberNames);
+    // P3：运动副构造期 fail-fast——parent/child ∈ members、child 唯一驱动、多 DOF 类型
+    // 在 assembly() 构造时暴露（buildJoint/buildKinematicTree 复用同一份校验实现）
+    if (joints.length > 0)
+        buildKinematicTree(memberNames, joints);
+    if (members.length > 0)
+        keep(...members);
+    const c = makeCompound(members);
+    const behavior = {
+        name: params.name,
+        memberNames,
+        constraints,
+        joints,
+        drive,
+        memberColors: params.memberColors,
+        solver: params.solver,
+        solve: () => solveTransforms(members, behavior),
+        solveDetailed: () => solveAssemblyAndKinematics(members, behavior.memberNames, behavior.constraints, behavior.joints ?? [], behavior.drive, { solver: behavior.solver, name: behavior.name }),
+    };
+    ensureSlot(c).behavior = behavior;
+    // solve / do_assemble 完全同义（方案 §5.5 D2：solve 为新名，do_assemble 保留为别名）
+    const solveAndRegister = () => {
+        // P6：只求解并登记待应用变换；应用与下游失效由引擎做（F2：库不查询/修改 DAG）
+        // P3：约束 + 运动副在库侧一次合并（solveAssemblyAndKinematics），transforms 与
+        // kinematics 一起登记（禁止引擎侧两次求解/两次登记）
+        const result = behavior.solveDetailed();
+        if (result.transforms.length > 0)
+            setPendingAssemblyTransforms(c, result.transforms);
+        if (result.kinematics)
+            setPendingAssemblyKinematics(c, result.kinematics);
+    };
+    c.do_assemble = solveAndRegister;
+    c.solve = solveAndRegister;
+    c.add_constraint = () => {
+        // Phase 1 semantics: constraints are read from the assembly statement's args.constraints;
+        // add_constraint is intentionally a no-op (kept for ABI uniformity).
+    };
+    return c;
+}
+//# sourceMappingURL=compound.js.map

package/dist/api/compound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compound.js","sourceRoot":"","sources":["../../src/api/compound.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib compound — group/assembly 库函数（compound Shape + AssemblyBehavior）\n *\n *\n * 从 src/ops/assemble.ts 迁出并改写为 stdlib 形态：\n * - `group(params)` → compound Shape（kind='compound'，children 为成员 Shape 引用）\n * - `assembly(params)` → compound Shape + AssemblyBehavior（约束列表 + solve 方法）\n * - 装配求解（P1 起）委派 api/assembly/（brepjs solverAdapter 内核）：\n *   do_assemble/solve 触发求解 → 引擎应用\n *   （mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。\n *   P2-f5：旧装配算法与自有四元数实现已删除，求解全链路走 api/assembly。\n *\n * compound 自身无独立 mesh——几何由 children 承载，意义是结构（层级）。\n * do_assemble 编译为 `await ctx.<asm>.do_assemble()`：调用 compound 的求解方法，\n * 对约束定位的成员施加装配变换（mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { compound as makeCompound, ensureSlot, type CompoundShape } from '../shape'\nimport { keep, nameOf, setPendingAssemblyTransforms, setPendingAssemblyKinematics, type AssemblyTransform } from '../runtime-state'\nimport { solveAssemblyAndKinematics, type AssemblySolveResult } from './assembly/solve'\nimport { validateConstraints } from './assembly/validate'\nimport { buildKinematicTree, type JointSpec } from './assembly/joints'\nimport type { AssemblyConstraint } from './assembly/types'\nimport type { SolverStyle } from './assembly/solvers/types'\n\n// ── 参数类型（keep-syntax 设计 §2.5：成员保留由函数体 keep() 显式声明，不再靠类型标注） ──\n\n/** Parameters for the `group` stdlib function: an optional name and ordered members. */\nexport interface GroupParams {\n  name?: string\n  /** Compound members: read-only references, never mutated by group/assembly. */\n  members?: Shape[]\n  memberNames?: string[]\n}\n\n/** Parameters for the `assembly` stdlib function: group params plus assembly constraints. */\nexport interface AssemblyParams extends GroupParams {\n  constraints?: AssemblyConstraint[]\n  /** P3：运动副声明（可选；parent/child 必须是 members 里的名字）。 */\n  joints?: JointSpec[]\n  /** P3：驱动值覆盖（键 = child 成员名；值 = 主 DOF 数值或多 DOF 数组）。 */\n  drive?: Record<string, number | number[]>\n  /** cq-compat：成员颜色（sRGB 0..1），导出 STEP 时写入 XCAF。 */\n  memberColors?: Record<string, [number, number, number]>\n  /** P1：求解风格。'chain'（默认，vendored brepjs 解析链式）| 'global'（CadQuery 兼容全局最小二乘）。 */\n  solver?: SolverStyle\n}\n\n// ── 约束类型（P1 起定义收口在 api/assembly/types，此处 re-export 保持既有导出面） ──\n\nexport type {\n  AssemblyConstraint,\n  FaceMateConstraint,\n  FaceMateFace,\n  EntityRef,\n  FaceRef,\n  EdgeRef,\n  MateConstraint,\n  AlignConstraint,\n  CoincidentConstraint,\n  ConcentricConstraint,\n  DistanceConstraint,\n  AngleConstraint,\n  ParallelConstraint,\n  PerpendicularConstraint,\n  FixedConstraint,\n  StructuralConstraint,\n  AssemblyVec3,\n} from './assembly/types'\nexport type { AssemblySolveResult } from './assembly/solve'\n\n// ── 求解器 ──\n// P2-f5：旧装配算法与自有四元数实现已整体删除——旋转计算一律走\n// brepjs utils/quaternion.ts，输出经 api/assembly/pose.ts fromBrepjsQuat 重排。\n\n// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：\n// 引擎不得 import stdlib/compound；公共 API 经本 re-export 保持）。\nexport { applyTransform } from '../mesh/rigid-transform'\n\n// ── AssemblyBehavior ──\n\n/** Behavior attached to an assembly compound: its members, constraints, and solver. */\nexport interface AssemblyBehavior {\n  name?: string\n  memberNames: string[]\n  constraints: AssemblyConstraint[]\n  /** P3：运动副声明（无 joints 时为空数组）。 */\n  joints?: JointSpec[]\n  /** P3：驱动值覆盖（键 = child 成员名；缺省 undefined = 用 joint 存储值）。 */\n  drive?: Record<string, number | number[]>\n  /** cq-compat：成员颜色（sRGB 0..1）。 */\n  memberColors?: Record<string, [number, number, number]>\n  /** P1：求解风格。 */\n  solver?: SolverStyle\n  /** 只求解（P6）：返回\"成员下标 → 变换\"列表。不改写入参、不传播；可重复调用（幂等）。 */\n  solve(): AssemblyTransform[]\n  /** 只求解并带诊断量（P1）：transforms + dof/converged/unsupported（方案 P1⑤）；P3 增 kinematics/warnings。 */\n  solveDetailed(): AssemblySolveResult\n}\n\n/**\n * 纯求解（P6：求解 ≠ 传播）：委派 api/assembly/solveAssembly（P1 起）。\n * 不修改任何输入、不触碰引擎状态——引擎负责应用变换并让下游失效重算（F2）。\n *\n * 约束形态（方案 §5）：\n * - 遗留 face_mate：规范化为 mate 后降级为 brepjs concentric + 轴编码求解（§3.7.2）；\n * - 新形态 mate/align/coincident/concentric/distance/angle/parallel/perpendicular/fixed；\n * - 面参数 `{ topoRef }` 执行期解析（BREP 现场/mesh 行快照），旧 `{ center, normal }`\n *   快照直接使用（兼容已持久化的历史脚本）；\n * - 输出为 per-member 终态（L6 修复），锚定成员不输出变换。\n */\nfunction solveTransforms(members: Shape[], behavior: AssemblyBehavior): AssemblyTransform[] {\n  return solveAssemblyAndKinematics(\n    members,\n    behavior.memberNames,\n    behavior.constraints,\n    behavior.joints ?? [],\n    behavior.drive,\n    { solver: behavior.solver, name: behavior.name },\n  ).transforms\n}\n\n// ── group / assembly 库函数 ──\n\n/**\n * 成员名推导：显式 memberNames 兼容旧手工构造 IR；否则经 keep() 反查\n * （P3 起经 keep()/nameOfShapes 反查成员名——库不再访问执行上下文，F1）。\n */\nfunction memberNamesOf(params: { memberNames?: unknown }, members: Shape[]): string[] {\n  if (Array.isArray(params.memberNames) && params.memberNames.length > 0) {\n    return params.memberNames as string[]\n  }\n  return members.map((m) => {\n    // 兼容字符串形态的 members（历史 IR 直传 partName）：字符串本身就是名字\n    if (typeof m === 'string') return m\n    return String(nameOf(m) ?? '')\n  })\n}\n\n/**\n * `cad.group({ name, members })` → compound Shape。\n * members 是成员 Shape（编译产物 ctx.<var> 引用），成员名经 keep() 反查。\n *\n * 函数体 keep 声明（keep-syntax 设计 §2.5）：group 保留其成员且可见（R6）。\n */\n/**\n * 分组：零约束，保持当前布局。结构语句，无几何输出，成员用变量名引用。\n * @group 结构\n * @inputs 1\n * @async false\n * @qual ok\n * @name group\n * @returns CompoundShape 复合几何（kind='compound'，children 为成员 Shape 引用）。\n * @param params.name - 组名。type:string\n * @param params.members - 成员（编译产物 ctx.<var> 引用；结构语句里是裸变量引用，非字符串数组）。type:Shape[]\n * @note members 在 .fai.js 里是裸变量引用（编译为 ctx.<var>），字符串数组形态的成员名经 keep() 反查兼容历史 IR。\n * @example\n * const part0 = cad.box(30, 20, 10, { centered: true })\n * cad.group({ name: '底板组', members: [part0] })\n  */\nexport function group(params: GroupParams): CompoundShape {\n  const members = (params.members as Shape[] | undefined) ?? []\n  if (members.length > 0) keep(...members)\n  const memberNames = memberNamesOf(params, members)\n  const c = makeCompound(members)\n  // 挂最小 behavior（memberNames 供 ExecutionResult.compounds 结构输出；group 无约束）\n  ensureSlot(c).behavior = {\n    memberNames,\n    constraints: [],\n    joints: [],\n    solve: () => [],\n    solveDetailed: () => ({ transforms: [], dof: 0, converged: true, unsupported: [] }),\n  }\n  return c\n}\n\n/**\n * 装配：成员 + 约束。结构语句，无几何输出，成员用变量名引用、实体用 EntityRef / 拓扑引用。\n * 求解内核复用 vendored brepjs solverAdapter.solveConstraints（链式拓扑调度 / DOF / converged /\n * unsupported 诊断）；输出为 per-member 终态变换（每成员一条，恒等位姿不输出）。\n * @group 结构\n * @inputs 1\n * @async false\n * @qual warn\n * @name assembly\n * @returns CompoundShape + AssemblyBehavior（含 do_assemble / solve 方法）。\n * @note 约束类型（a=参考、b=从动，移动 b 去贴合 a）：`mate` 面对面贴合（法向反向+面中心重合，遗留 face_mate 的新名，求解降级为 concentric + 轴编码）；`align` 同向对齐（法向同向+面中心重合）；`coincident` 共面/共点/共线（保留面内 2 个平移 DOF）；`concentric` 轴重合（孔轴配合，圆柱/圆锥面需 hint.axis，直边/圆边需 EdgeHint.axis）；`distance` 定距（mm，带 value）；`angle` 夹角（deg，带 value）；`parallel`/`perpendicular` 平行/垂直（angle 0°/90° 语法糖）；`fixed` 锚定部件（地基）；`face_mate` 为遗留别名（规范化为 mate，新代码不再使用）。\n * @note EntityRef 四种形态：`{ part, face: { topoRef } | { surfaceType?, center, normal } }`、`{ part, edge: { topoRef } | { axis: { origin, direction } } }`、`{ part, point: [x,y,z] }`、`{ part, faceIndex }`（1 起，仅调试简写）。\n * @note 不收敛（实体类型不匹配/环/参考不可达）→ 抛错并带 unsupported 明细；成员名为空串 → 求解前抛错；mesh 快照缺 axis 的圆柱/圆锥面作轴实体 → E_TOPO_NOT_FOUND（绝不静默降级）。`mate`（中心重合）与 `coincident`（只共面）是两种不同语义，不互相映射。\n * @note 早期文档/示例曾用 `fixedPartId`/`movingPartId`/`faceRowIndex`/`faceId`/`invalid`——这些键在代码中不存在。真实契约是 `fixedPartName`/`movingPartName` + `fixedFace`/`movingFace`（遗留 face_mate）。`faceId` 字段随 §6.2 移除，不再写入。\n * @param params.name - 装配名。type:string\n * @param params.members - 成员（裸变量引用）。type:Shape[]\n * @param params.constraints - 约束数组（遗留 face_mate 形态或上述新形态 { type, a, b }）。type:AssemblyConstraint[]\n * @example\n * let asm1 = cad.assembly({ name: '主轴组件', members: [part0, part1, part2], constraints: [ { type: 'fixed', part: 'part0' }, { type: 'mate', a: { part: 'part0', face: { topoRef: { kind: 'face', origin: 'part0', role: 'box:top', hint: { kind: 'face', surfaceType: 'plane' } } } }, b: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: 'box:bottom', hint: { kind: 'face', surfaceType: 'plane' } } } } }, { type: 'concentric', a: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: '', hint: { kind: 'face', surfaceType: 'cylinder' } } } }, b: { part: 'part2', face: { topoRef: { kind: 'face', origin: 'part2', role: 'cylinder:lateral', hint: { kind: 'face', surfaceType: 'cylinder' } } } } } ] })\n * asm1.solve()\n  */\nexport function assembly(params: AssemblyParams): CompoundShape {\n  const members = (params.members as Shape[] | undefined) ?? []\n  const constraints = (params.constraints as AssemblyConstraint[] | undefined) ?? []\n  const joints = (params.joints as JointSpec[] | undefined) ?? []\n  const drive = params.drive as Record<string, number | number[]> | undefined\n\n  // P2-f1：约束参数运行期校验（keep() 之前，fail-fast；规则见 api/assembly/validate.ts V1–V6）\n  const memberNames = memberNamesOf(params, members)\n  validateConstraints(constraints, memberNames)\n  // P3：运动副构造期 fail-fast——parent/child ∈ members、child 唯一驱动、多 DOF 类型\n  // 在 assembly() 构造时暴露（buildJoint/buildKinematicTree 复用同一份校验实现）\n  if (joints.length > 0) buildKinematicTree(memberNames, joints)\n\n  if (members.length > 0) keep(...members)\n  const c = makeCompound(members)\n  const behavior: AssemblyBehavior = {\n    name: params.name as string | undefined,\n    memberNames,\n    constraints,\n    joints,\n    drive,\n    memberColors: params.memberColors,\n    solver: params.solver,\n    solve: () => solveTransforms(members, behavior),\n    solveDetailed: () =>\n      solveAssemblyAndKinematics(\n        members,\n        behavior.memberNames,\n        behavior.constraints,\n        behavior.joints ?? [],\n        behavior.drive,\n        { solver: behavior.solver, name: behavior.name },\n      ),\n  }\n  ensureSlot(c).behavior = behavior\n  // solve / do_assemble 完全同义（方案 §5.5 D2：solve 为新名，do_assemble 保留为别名）\n  const solveAndRegister = (): void => {\n    // P6：只求解并登记待应用变换；应用与下游失效由引擎做（F2：库不查询/修改 DAG）\n    // P3：约束 + 运动副在库侧一次合并（solveAssemblyAndKinematics），transforms 与\n    // kinematics 一起登记（禁止引擎侧两次求解/两次登记）\n    const result = behavior.solveDetailed()\n    if (result.transforms.length > 0) setPendingAssemblyTransforms(c, result.transforms)\n    if (result.kinematics) setPendingAssemblyKinematics(c, result.kinematics)\n  }\n  ;(c as CompoundShape & { do_assemble?: () => void }).do_assemble = solveAndRegister\n  ;(c as CompoundShape & { solve?: () => void }).solve = solveAndRegister\n  // 统一成员调用 ABI：add_constraint 是 no-op（现状语义：约束由 assembly 语句 args.constraints 读取，\n  // 编译产物机械发射 `ctx.<asm>.add_constraint({...})`，调用此方法不崩）\n  ;(c as CompoundShape & { add_constraint?: () => void }).add_constraint = () => {\n    // Phase 1 semantics: constraints are read from the assembly statement's args.constraints;\n    // add_constraint is intentionally a no-op (kept for ABI uniformity).\n  }\n  return c\n}\n"]}