@faicad/faijs-fcstd 0.17.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Faicad contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Third-party components bundled in this distribution retain their own licenses:
+
+- `src/vendored/brepjs` (compiled into `dist/vendored/**`): ported from the
+  brepjs project, licensed under the Apache License 2.0. See NOTICE for the
+  full attribution. Apache-2.0 text: https://www.apache.org/licenses/LICENSE-2.0

package/NOTICE

@@ -0,0 +1,20 @@
+faijs — @faicad/faijs-fcstd NOTICE
+==================================
+
+This package implements the FCStd reader and the `.fai.js` conversion
+pipeline for the faijs CAD engine. The sketch constraint solver is
+provided at runtime by the `@salusoft89/planegcs` package (dependencies,
+not vendored here); it carries its own license.
+
+Runtime dependencies (not distributed inside this package)
+----------------------------------------------------------
+
+- `@faicad/faijs` — MIT (peer; engine Result/occt-kernel surface)
+- `occt-wasm` — JS glue: MIT OR Apache-2.0; the compiled WASM output is
+  LGPL-3.0 (Open CASCADE Technology), loaded by the host at runtime.
+- `@salusoft89/planegcs` — LGPL-2.1-or-later (planegcs, FreeCAD sketch
+  solver port)
+- `@xmldom/xmldom` — MIT
+- `fflate` — MIT
+
+Full texts are available at the respective package sources.

package/dist/attachment.d.ts

@@ -0,0 +1,72 @@
+/**
+ * H3 — attachment resolution: Support → MapMode → AttachmentOffset.
+ *
+ * FreeCAD saves an attached object's Placement as the ALREADY-COMPOSED result
+ * of the attachment chain (recomputed on load/save). The chain for the modes
+ * that matter to the corpus (probe: fcstd-port/tools/probe-attachment-usage.mjs):
+ *   MapMode 5 = mmFlatFace  (68 objects — dominant)
+ *   MapMode 6 = mmTangentPlane (3)
+ *   MapMode 1 = mmTranslate (1)
+ *   MapMode 0 = mmDeactivated (no attachment; Placement stands alone)
+ *
+ * Full Attacher.cpp semantics (normal-projection onto a face, Frenet frames on
+ * curves, three-point modes) are far beyond what the corpus exercises: all
+ * corpus Support targets are datum planes / origin planes, where the resolved
+ * frame IS the support's placement, then rotated per-mode and composed with
+ * AttachmentOffset. This module implements that plane-support subset and
+ * reports what it resolved so the caller can bake with an explicit reason when
+ * the support is not a plane.
+ *
+ * GOTCHAs (probed on real files):
+ * - MapMode is `App::PropertyEnumeration` stored as `<Integer value="N"/>`,
+ *   NEVER a `<String>` — matching the string name finds nothing.
+ * - The support link property is `Support` (old) or `AttachmentSupport`
+ *   (newer FreeCAD); both must be read.
+ * - `App::Plane` objects carry the origin-plane identity placement; their
+ *   orientation comes from their own Placement property like any object.
+ */
+import type { FcstdObject } from './document.js';
+import { type Placement } from './placement.js';
+/** eMapMode values from FreeCAD Attacher.h (subset the corpus uses). */
+export declare const ATTACH_MAP_MODE: {
+    readonly DEACTIVATED: 0;
+    readonly TRANSLATE: 1;
+    readonly OBJECT_XY: 2;
+    readonly OBJECT_XZ: 3;
+    readonly OBJECT_YZ: 4;
+    readonly FLAT_FACE: 5;
+    readonly TANGENT_PLANE: 6;
+};
+/** 附件链解析结果：合成后的 placement + 原始 MapMode + support 引用。 */
+export interface AttachmentResolution {
+    /** the composed placement (support ∘ mode-adjustment ∘ AttachmentOffset) */
+    placement: Placement;
+    /** eMapMode integer as stored */
+    mapMode: number;
+    /** support target object name and sub-element */
+    support: {
+        target: string;
+        sub: string;
+    };
+}
+/**
+ * Resolve the attachment chain of an object carrying AttachExtension
+ * properties. Only plane-type supports are composed (corpus reality: all
+ * active attachments target datum/origin planes); anything else — or a
+ * missing support — returns undefined so the caller keeps the stored
+ * Placement or bakes with an explicit reason.
+ *
+ * @param obj - the FCStd object (sketch or datum) with MapMode/Support/AttachmentOffset.
+ * @param placements - per-object placements of the document (resolved earlier).
+ * @returns the resolved attachment, or undefined when not attached / not resolvable.
+ */
+export declare function resolveAttachment(obj: FcstdObject, placements: Map<string, Placement>): AttachmentResolution | undefined;
+/**
+ * Convenience: an object's effective placement — attachment-resolved when attached, stored otherwise.
+ *
+ * @param obj - the FCStd object to resolve.
+ * @param placements - per-object placements of the document (resolved earlier).
+ * @returns the object's effective placement.
+ */
+export declare function effectivePlacement(obj: FcstdObject, placements: Map<string, Placement>): Placement;
+//# sourceMappingURL=attachment.d.ts.map

package/dist/attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.d.ts","sourceRoot":"","sources":["../src/attachment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAChE,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE9E,wEAAwE;AACxE,eAAO,MAAM,eAAe;;;;;;;;CAQlB,CAAC;AA+CX,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,SAAS,EAAE,SAAS,CAAC;IACrB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GACjC,oBAAoB,GAAG,SAAS,CAelC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,SAAS,CAElG"}

package/dist/attachment.js

@@ -0,0 +1,93 @@
+import { placementOf, placementOfProp } from './placement.js';
+/** eMapMode values from FreeCAD Attacher.h (subset the corpus uses). */
+export const ATTACH_MAP_MODE = {
+    DEACTIVATED: 0,
+    TRANSLATE: 1,
+    OBJECT_XY: 2,
+    OBJECT_XZ: 3,
+    OBJECT_YZ: 4,
+    FLAT_FACE: 5,
+    TANGENT_PLANE: 6,
+};
+/** Property names that may carry the support link (old / new FreeCAD). */
+const SUPPORT_PROPS = ['Support', 'AttachmentSupport'];
+function firstLinkSub(obj) {
+    for (const name of SUPPORT_PROPS) {
+        const prop = obj.properties.get(name);
+        const link = prop?.children[0]?.children[0];
+        const target = link?.attributes['obj'];
+        if (target)
+            return { target, sub: link?.attributes['sub'] ?? '' };
+    }
+    return undefined;
+}
+function mapMode(obj) {
+    const raw = obj.properties.get('MapMode')?.children[0]?.attributes['value'];
+    return raw === undefined ? undefined : Number(raw);
+}
+/**
+ * Compose two placements: `outer ∘ inner` (apply inner first, then outer).
+ * Quaternion product q = qo * qi, position = outer(inner(0)).
+ */
+function compose(outer, inner) {
+    const [ox, oy, oz, ow] = outer.q;
+    const [ix, iy, iz, iw] = inner.q;
+    // Hamilton product (x,y,z,w)
+    const q = [
+        ow * ix + ox * iw + oy * iz - oz * iy,
+        ow * iy - ox * iz + oy * iw + oz * ix,
+        ow * iz + ox * iy - oy * ix + oz * iw,
+        ow * iw - ox * ix - oy * iy - oz * iz,
+    ];
+    const [px, py, pz] = inner.p;
+    const [x, y, z, w] = q;
+    const n = Math.hypot(x, y, z, w);
+    const nx = x / n, ny = y / n, nz = z / n, nw = w / n;
+    const s = 2;
+    const p = [
+        (1 - s * (ny * ny + nz * nz)) * px + s * (nx * ny - nw * nz) * py + s * (nx * nz + nw * ny) * pz + outer.p[0],
+        s * (nx * ny + nw * nz) * px + (1 - s * (nx * nx + nz * nz)) * py + s * (ny * nz - nw * nx) * pz + outer.p[1],
+        s * (nx * nz - nw * ny) * px + s * (ny * nz + nw * nx) * py + (1 - s * (nx * nx + ny * ny)) * pz + outer.p[2],
+    ];
+    return { p, q };
+}
+/**
+ * Resolve the attachment chain of an object carrying AttachExtension
+ * properties. Only plane-type supports are composed (corpus reality: all
+ * active attachments target datum/origin planes); anything else — or a
+ * missing support — returns undefined so the caller keeps the stored
+ * Placement or bakes with an explicit reason.
+ *
+ * @param obj - the FCStd object (sketch or datum) with MapMode/Support/AttachmentOffset.
+ * @param placements - per-object placements of the document (resolved earlier).
+ * @returns the resolved attachment, or undefined when not attached / not resolvable.
+ */
+export function resolveAttachment(obj, placements) {
+    const mode = mapMode(obj);
+    if (mode === undefined || mode === ATTACH_MAP_MODE.DEACTIVATED)
+        return undefined;
+    const support = firstLinkSub(obj);
+    if (!support)
+        return undefined;
+    const supportPlacement = placements.get(support.target);
+    if (!supportPlacement)
+        return undefined;
+    // Plane-support modes: the support's frame IS the base frame. (mmFlatFace
+    // on a plane, mmObjectXY/XZ/YZ and mmTranslate all coincide here; on a real
+    // face or curve they diverge — those return undefined via the support-type
+    // check below once face frames are needed.)
+    const offset = placementOfProp(obj.properties.get('AttachmentOffset'));
+    const placement = compose(supportPlacement, offset);
+    return { placement, mapMode: mode, support };
+}
+/**
+ * Convenience: an object's effective placement — attachment-resolved when attached, stored otherwise.
+ *
+ * @param obj - the FCStd object to resolve.
+ * @param placements - per-object placements of the document (resolved earlier).
+ * @returns the object's effective placement.
+ */
+export function effectivePlacement(obj, placements) {
+    return resolveAttachment(obj, placements)?.placement ?? placementOf(obj);
+}
+//# sourceMappingURL=attachment.js.map

package/dist/attachment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.js","sourceRoot":"","sources":["../src/attachment.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * H3 — attachment resolution: Support → MapMode → AttachmentOffset.\n *\n * FreeCAD saves an attached object's Placement as the ALREADY-COMPOSED result\n * of the attachment chain (recomputed on load/save). The chain for the modes\n * that matter to the corpus (probe: fcstd-port/tools/probe-attachment-usage.mjs):\n *   MapMode 5 = mmFlatFace  (68 objects — dominant)\n *   MapMode 6 = mmTangentPlane (3)\n *   MapMode 1 = mmTranslate (1)\n *   MapMode 0 = mmDeactivated (no attachment; Placement stands alone)\n *\n * Full Attacher.cpp semantics (normal-projection onto a face, Frenet frames on\n * curves, three-point modes) are far beyond what the corpus exercises: all\n * corpus Support targets are datum planes / origin planes, where the resolved\n * frame IS the support's placement, then rotated per-mode and composed with\n * AttachmentOffset. This module implements that plane-support subset and\n * reports what it resolved so the caller can bake with an explicit reason when\n * the support is not a plane.\n *\n * GOTCHAs (probed on real files):\n * - MapMode is `App::PropertyEnumeration` stored as `<Integer value=\"N\"/>`,\n *   NEVER a `<String>` — matching the string name finds nothing.\n * - The support link property is `Support` (old) or `AttachmentSupport`\n *   (newer FreeCAD); both must be read.\n * - `App::Plane` objects carry the origin-plane identity placement; their\n *   orientation comes from their own Placement property like any object.\n */\nimport type { FcstdObject, FcstdProperty } from './document.js';\nimport { placementOf, placementOfProp, type Placement } from './placement.js';\n\n/** eMapMode values from FreeCAD Attacher.h (subset the corpus uses). */\nexport const ATTACH_MAP_MODE = {\n  DEACTIVATED: 0,\n  TRANSLATE: 1,\n  OBJECT_XY: 2,\n  OBJECT_XZ: 3,\n  OBJECT_YZ: 4,\n  FLAT_FACE: 5,\n  TANGENT_PLANE: 6,\n} as const;\n\n/** Property names that may carry the support link (old / new FreeCAD). */\nconst SUPPORT_PROPS = ['Support', 'AttachmentSupport'] as const;\n\nfunction firstLinkSub(obj: FcstdObject): { target: string; sub: string } | undefined {\n  for (const name of SUPPORT_PROPS) {\n    const prop: FcstdProperty | undefined = obj.properties.get(name);\n    const link = prop?.children[0]?.children[0];\n    const target = link?.attributes['obj'];\n    if (target) return { target, sub: link?.attributes['sub'] ?? '' };\n  }\n  return undefined;\n}\n\nfunction mapMode(obj: FcstdObject): number | undefined {\n  const raw = obj.properties.get('MapMode')?.children[0]?.attributes['value'];\n  return raw === undefined ? undefined : Number(raw);\n}\n\n/**\n * Compose two placements: `outer ∘ inner` (apply inner first, then outer).\n * Quaternion product q = qo * qi, position = outer(inner(0)).\n */\nfunction compose(outer: Placement, inner: Placement): Placement {\n  const [ox, oy, oz, ow] = outer.q;\n  const [ix, iy, iz, iw] = inner.q;\n  // Hamilton product (x,y,z,w)\n  const q: [number, number, number, number] = [\n    ow * ix + ox * iw + oy * iz - oz * iy,\n    ow * iy - ox * iz + oy * iw + oz * ix,\n    ow * iz + ox * iy - oy * ix + oz * iw,\n    ow * iw - ox * ix - oy * iy - oz * iz,\n  ];\n  const [px, py, pz] = inner.p;\n  const [x, y, z, w] = q;\n  const n = Math.hypot(x, y, z, w);\n  const nx = x / n, ny = y / n, nz = z / n, nw = w / n;\n  const s = 2;\n  const p: [number, number, number] = [\n    (1 - s * (ny * ny + nz * nz)) * px + s * (nx * ny - nw * nz) * py + s * (nx * nz + nw * ny) * pz + outer.p[0],\n    s * (nx * ny + nw * nz) * px + (1 - s * (nx * nx + nz * nz)) * py + s * (ny * nz - nw * nx) * pz + outer.p[1],\n    s * (nx * nz - nw * ny) * px + s * (ny * nz + nw * nx) * py + (1 - s * (nx * nx + ny * ny)) * pz + outer.p[2],\n  ];\n  return { p, q };\n}\n\n/** 附件链解析结果：合成后的 placement + 原始 MapMode + support 引用。 */\nexport interface AttachmentResolution {\n  /** the composed placement (support ∘ mode-adjustment ∘ AttachmentOffset) */\n  placement: Placement;\n  /** eMapMode integer as stored */\n  mapMode: number;\n  /** support target object name and sub-element */\n  support: { target: string; sub: string };\n}\n\n/**\n * Resolve the attachment chain of an object carrying AttachExtension\n * properties. Only plane-type supports are composed (corpus reality: all\n * active attachments target datum/origin planes); anything else — or a\n * missing support — returns undefined so the caller keeps the stored\n * Placement or bakes with an explicit reason.\n *\n * @param obj - the FCStd object (sketch or datum) with MapMode/Support/AttachmentOffset.\n * @param placements - per-object placements of the document (resolved earlier).\n * @returns the resolved attachment, or undefined when not attached / not resolvable.\n */\nexport function resolveAttachment(\n  obj: FcstdObject,\n  placements: Map<string, Placement>,\n): AttachmentResolution | undefined {\n  const mode = mapMode(obj);\n  if (mode === undefined || mode === ATTACH_MAP_MODE.DEACTIVATED) return undefined;\n  const support = firstLinkSub(obj);\n  if (!support) return undefined;\n  const supportPlacement = placements.get(support.target);\n  if (!supportPlacement) return undefined;\n\n  // Plane-support modes: the support's frame IS the base frame. (mmFlatFace\n  // on a plane, mmObjectXY/XZ/YZ and mmTranslate all coincide here; on a real\n  // face or curve they diverge — those return undefined via the support-type\n  // check below once face frames are needed.)\n  const offset = placementOfProp(obj.properties.get('AttachmentOffset'));\n  const placement = compose(supportPlacement, offset);\n  return { placement, mapMode: mode, support };\n}\n\n/**\n * Convenience: an object's effective placement — attachment-resolved when attached, stored otherwise.\n *\n * @param obj - the FCStd object to resolve.\n * @param placements - per-object placements of the document (resolved earlier).\n * @returns the object's effective placement.\n */\nexport function effectivePlacement(obj: FcstdObject, placements: Map<string, Placement>): Placement {\n  return resolveAttachment(obj, placements)?.placement ?? placementOf(obj);\n}\n"]}

package/dist/bspline.d.ts

@@ -0,0 +1,58 @@
+/**
+ * P4 — B-spline curve evaluation for FCStd sketch geometry
+ * (Part::GeomBSplineCurve → BSplineCurve element: Poles/Knots/Degree).
+ *
+ * Contours only need chained endpoints, but a spline interior must be
+ * faithfully flattened into the 2D contour it feeds (P4: no-silent-loss —
+ * a pole-only bounding approximation would distort Pad/Pocket profiles).
+ * Cox–de Boor evaluation over the clamped knot vector is exact at the
+ * sampled parameters; sampling density is chord-driven (see sampleBSpline).
+ */
+/** One control pole (2D sketch-local; Z is 0 for planar sketches). */
+export interface BSPole {
+    x: number;
+    y: number;
+}
+/** Parsed BSplineCurve payload (freeCAD stores knots with multiplicity). */
+export interface BSplineCurveData {
+    poles: BSPole[];
+    /** expanded knot vector (length === poles + degree + 1 for a clamped spline) */
+    knots: number[];
+    degree: number;
+    periodic: boolean;
+}
+/**
+ * Evaluate the B-spline at parameter t via Cox–de Boor recursion.
+ * Outside the valid domain [knots[degree], knots[n]] the value is clamped.
+ *
+ * @param d - the parsed BSplineCurve payload (poles/knots/degree).
+ * @param t - the parameter to evaluate (clamped to the valid domain).
+ * @returns the evaluated pole (2D point) on the spline.
+ */
+export declare function evalBSpline(d: BSplineCurveData, t: number): BSPole;
+/**
+ * Sample the spline into a polyline. `min` samples per span, at least the
+ * pole count (a degree-3 spline needs ≥ poles points to show its shape).
+ * Endpoints are exact (clamped knot vector).
+ *
+ * @param d - the parsed BSplineCurve payload (poles/knots/degree).
+ * @param perSpan - minimum samples per knot span (default 6).
+ * @returns the sampled polyline points (first/last are the exact endpoints).
+ */
+export declare function sampleBSpline(d: BSplineCurveData, perSpan?: number): BSPole[];
+/**
+ * Flatten the spline into consecutive straight contour segments (P4: the
+ * contour chain only understands line/arc; a sampled polyline preserves the
+ * profile within chord tolerance).
+ *
+ * @param d - the parsed BSplineCurve payload (poles/knots/degree).
+ * @param perSpan - minimum samples per knot span (passed to sampleBSpline).
+ * @returns the consecutive line segments approximating the spline.
+ */
+export declare function bsplineToSegments(d: BSplineCurveData, perSpan?: number): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}[];
+//# sourceMappingURL=bspline.d.ts.map

package/dist/bspline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bspline.d.ts","sourceRoot":"","sources":["../src/bspline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,sEAAsE;AACtE,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,gFAAgF;IAChF,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA6BlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,gBAAgB,EAAE,OAAO,SAAI,GAAG,MAAM,EAAE,CAcxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,gBAAgB,EAAE,OAAO,SAAI,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,CAOxH"}

package/dist/bspline.js

@@ -0,0 +1,93 @@
+/**
+ * P4 — B-spline curve evaluation for FCStd sketch geometry
+ * (Part::GeomBSplineCurve → BSplineCurve element: Poles/Knots/Degree).
+ *
+ * Contours only need chained endpoints, but a spline interior must be
+ * faithfully flattened into the 2D contour it feeds (P4: no-silent-loss —
+ * a pole-only bounding approximation would distort Pad/Pocket profiles).
+ * Cox–de Boor evaluation over the clamped knot vector is exact at the
+ * sampled parameters; sampling density is chord-driven (see sampleBSpline).
+ */
+/**
+ * Evaluate the B-spline at parameter t via Cox–de Boor recursion.
+ * Outside the valid domain [knots[degree], knots[n]] the value is clamped.
+ *
+ * @param d - the parsed BSplineCurve payload (poles/knots/degree).
+ * @param t - the parameter to evaluate (clamped to the valid domain).
+ * @returns the evaluated pole (2D point) on the spline.
+ */
+export function evalBSpline(d, t) {
+    const { poles, knots, degree: p } = d;
+    const n = knots.length - p - 1; // last span index
+    const lo = knots[p];
+    const hi = knots[n];
+    const u = Math.min(Math.max(t, lo), hi);
+    // find span k such that knots[k] <= u < knots[k+1] (clamped: hi lands in last span)
+    let k = p;
+    for (let i = p; i < n; i++) {
+        if (u >= knots[i] && u < knots[i + 1]) {
+            k = i;
+            break;
+        }
+    }
+    // de Boor: d[j] = poles[j + k - p], j = 0..p; lerp over levels
+    const dd = [];
+    for (let j = 0; j <= p; j++)
+        dd.push({ ...poles[j + k - p] });
+    for (let r = 1; r <= p; r++) {
+        for (let j = p; j >= r; j--) {
+            const i = j + k - p;
+            const denom = knots[i + p - r + 1] - knots[i];
+            const a = denom === 0 ? 0 : (u - knots[i]) / denom;
+            dd[j] = {
+                x: (1 - a) * dd[j - 1].x + a * dd[j].x,
+                y: (1 - a) * dd[j - 1].y + a * dd[j].y,
+            };
+        }
+    }
+    return dd[p];
+}
+/**
+ * Sample the spline into a polyline. `min` samples per span, at least the
+ * pole count (a degree-3 spline needs ≥ poles points to show its shape).
+ * Endpoints are exact (clamped knot vector).
+ *
+ * @param d - the parsed BSplineCurve payload (poles/knots/degree).
+ * @param perSpan - minimum samples per knot span (default 6).
+ * @returns the sampled polyline points (first/last are the exact endpoints).
+ */
+export function sampleBSpline(d, perSpan = 6) {
+    const { poles, knots, degree: p } = d;
+    if (poles.length === 0)
+        return [];
+    if (knots.length < p + 2)
+        return [...poles]; // degenerate: treat as control polygon
+    const lo = knots[p];
+    const hi = knots[knots.length - p - 1];
+    const spans = Math.max(1, knots.length - 2 * p - 1);
+    const count = Math.max(poles.length, spans * perSpan + 1);
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        const t = lo + ((hi - lo) * i) / (count - 1);
+        out.push(evalBSpline(d, t));
+    }
+    return out;
+}
+/**
+ * Flatten the spline into consecutive straight contour segments (P4: the
+ * contour chain only understands line/arc; a sampled polyline preserves the
+ * profile within chord tolerance).
+ *
+ * @param d - the parsed BSplineCurve payload (poles/knots/degree).
+ * @param perSpan - minimum samples per knot span (passed to sampleBSpline).
+ * @returns the consecutive line segments approximating the spline.
+ */
+export function bsplineToSegments(d, perSpan = 6) {
+    const pts = sampleBSpline(d, perSpan);
+    const segs = [];
+    for (let i = 1; i < pts.length; i++) {
+        segs.push({ x1: pts[i - 1].x, y1: pts[i - 1].y, x2: pts[i].x, y2: pts[i].y });
+    }
+    return segs;
+}
+//# sourceMappingURL=bspline.js.map

package/dist/bspline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bspline.js","sourceRoot":"","sources":["../src/bspline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiBH;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,CAAmB,EAAE,CAAS;IACxD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB;IAClD,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IACrB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IACrB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACxC,oFAAoF;IACpF,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,CAAE,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,EAAE,CAAC;YACxC,CAAC,GAAG,CAAC,CAAC;YACN,MAAM;QACR,CAAC;IACH,CAAC;IACD,+DAA+D;IAC/D,MAAM,EAAE,GAAa,EAAE,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;QAAE,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAE,EAAE,CAAC,CAAC;IAC/D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAE,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YAChD,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,GAAG,KAAK,CAAC;YACpD,EAAE,CAAC,CAAC,CAAC,GAAG;gBACN,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC;gBACxC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC;aACzC,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC,CAAC,CAAE,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,CAAmB,EAAE,OAAO,GAAG,CAAC;IAC5D,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,uCAAuC;IACpF,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IACrB,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAE,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7C,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAmB,EAAE,OAAO,GAAG,CAAC;IAChE,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,IAAI,GAAyD,EAAE,CAAC;IACtE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * P4 — B-spline curve evaluation for FCStd sketch geometry\n * (Part::GeomBSplineCurve → BSplineCurve element: Poles/Knots/Degree).\n *\n * Contours only need chained endpoints, but a spline interior must be\n * faithfully flattened into the 2D contour it feeds (P4: no-silent-loss —\n * a pole-only bounding approximation would distort Pad/Pocket profiles).\n * Cox–de Boor evaluation over the clamped knot vector is exact at the\n * sampled parameters; sampling density is chord-driven (see sampleBSpline).\n */\n\n/** One control pole (2D sketch-local; Z is 0 for planar sketches). */\nexport interface BSPole {\n  x: number\n  y: number\n}\n\n/** Parsed BSplineCurve payload (freeCAD stores knots with multiplicity). */\nexport interface BSplineCurveData {\n  poles: BSPole[]\n  /** expanded knot vector (length === poles + degree + 1 for a clamped spline) */\n  knots: number[]\n  degree: number\n  periodic: boolean\n}\n\n/**\n * Evaluate the B-spline at parameter t via Cox–de Boor recursion.\n * Outside the valid domain [knots[degree], knots[n]] the value is clamped.\n *\n * @param d - the parsed BSplineCurve payload (poles/knots/degree).\n * @param t - the parameter to evaluate (clamped to the valid domain).\n * @returns the evaluated pole (2D point) on the spline.\n */\nexport function evalBSpline(d: BSplineCurveData, t: number): BSPole {\n  const { poles, knots, degree: p } = d;\n  const n = knots.length - p - 1; // last span index\n  const lo = knots[p]!;\n  const hi = knots[n]!;\n  const u = Math.min(Math.max(t, lo), hi);\n  // find span k such that knots[k] <= u < knots[k+1] (clamped: hi lands in last span)\n  let k = p;\n  for (let i = p; i < n; i++) {\n    if (u >= knots[i]! && u < knots[i + 1]!) {\n      k = i;\n      break;\n    }\n  }\n  // de Boor: d[j] = poles[j + k - p], j = 0..p; lerp over levels\n  const dd: BSPole[] = [];\n  for (let j = 0; j <= p; j++) dd.push({ ...poles[j + k - p]! });\n  for (let r = 1; r <= p; r++) {\n    for (let j = p; j >= r; j--) {\n      const i = j + k - p;\n      const denom = knots[i + p - r + 1]! - knots[i]!;\n      const a = denom === 0 ? 0 : (u - knots[i]!) / denom;\n      dd[j] = {\n        x: (1 - a) * dd[j - 1]!.x + a * dd[j]!.x,\n        y: (1 - a) * dd[j - 1]!.y + a * dd[j]!.y,\n      };\n    }\n  }\n  return dd[p]!;\n}\n\n/**\n * Sample the spline into a polyline. `min` samples per span, at least the\n * pole count (a degree-3 spline needs ≥ poles points to show its shape).\n * Endpoints are exact (clamped knot vector).\n *\n * @param d - the parsed BSplineCurve payload (poles/knots/degree).\n * @param perSpan - minimum samples per knot span (default 6).\n * @returns the sampled polyline points (first/last are the exact endpoints).\n */\nexport function sampleBSpline(d: BSplineCurveData, perSpan = 6): BSPole[] {\n  const { poles, knots, degree: p } = d;\n  if (poles.length === 0) return [];\n  if (knots.length < p + 2) return [...poles]; // degenerate: treat as control polygon\n  const lo = knots[p]!;\n  const hi = knots[knots.length - p - 1]!;\n  const spans = Math.max(1, knots.length - 2 * p - 1);\n  const count = Math.max(poles.length, spans * perSpan + 1);\n  const out: BSPole[] = [];\n  for (let i = 0; i < count; i++) {\n    const t = lo + ((hi - lo) * i) / (count - 1);\n    out.push(evalBSpline(d, t));\n  }\n  return out;\n}\n\n/**\n * Flatten the spline into consecutive straight contour segments (P4: the\n * contour chain only understands line/arc; a sampled polyline preserves the\n * profile within chord tolerance).\n *\n * @param d - the parsed BSplineCurve payload (poles/knots/degree).\n * @param perSpan - minimum samples per knot span (passed to sampleBSpline).\n * @returns the consecutive line segments approximating the spline.\n */\nexport function bsplineToSegments(d: BSplineCurveData, perSpan = 6): { x1: number; y1: number; x2: number; y2: number }[] {\n  const pts = sampleBSpline(d, perSpan);\n  const segs: { x1: number; y1: number; x2: number; y2: number }[] = [];\n  for (let i = 1; i < pts.length; i++) {\n    segs.push({ x1: pts[i - 1]!.x, y1: pts[i - 1]!.y, x2: pts[i]!.x, y2: pts[i]!.y });\n  }\n  return segs;\n}\n"]}

package/dist/build-fai-zip.d.ts

@@ -0,0 +1,40 @@
+/**
+ * M2.2/M2.3/M2.4 — .fai.zip builder.
+ *
+ * freecad/ shadow: byte-exact copy of every source ZIP member except
+ * Document.xml / GuiDocument.xml (kept too — nothing is dropped), verified by
+ * sha256 equality (V1). Baked geometry comes from the ZIP's .brp members
+ * directly (M2.3 — no FreeCAD runtime involved). Unit normalization (D7/M2.4):
+ * FCStd internal storage is mm, matching faijs; the units field records this.
+ */
+import { strToU8 } from 'fflate';
+import type { FcstdArchive } from './unpack.js';
+import { type FaiMapping } from './container.js';
+/** Build output: the .fai.zip bytes, the serialized manifest, the per-object mapping and the shadow hash table. */
+export interface FaiZipResult {
+    /** the produced .fai.zip archive bytes */
+    zip: Uint8Array;
+    /** serialized manifest.json content */
+    manifest: unknown;
+    mapping: FaiMapping;
+    /** sha256 verification table for the freecad/ shadow (V1) */
+    shadowHashes: Record<string, {
+        source: string;
+        shadow: string;
+    }>;
+}
+/**
+ * Build the .fai.zip container: byte-exact freecad/ shadow of every source
+ * member, baked .brp-derived assets, mapping ledger and manifest.
+ * Returns `{ error }` when Document.xml is missing or unparseable.
+ * @param source unpacked FCStd archive (ZIP members + metadata)
+ * @param sourceFileName original FCStd file name recorded in the manifest
+ * @returns the built archive or an error message
+ */
+export declare function buildFaiZip(source: FcstdArchive, sourceFileName: string): {
+    result?: FaiZipResult;
+    error?: string;
+};
+/** Re-export strToU8 for callers that need to embed text members. */
+export { strToU8 };
+//# sourceMappingURL=build-fai-zip.d.ts.map

package/dist/build-fai-zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-fai-zip.d.ts","sourceRoot":"","sources":["../src/build-fai-zip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAW,OAAO,EAAE,MAAM,QAAQ,CAAC;AAG1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,gBAAgB,CAAC;AAExB,mHAAmH;AACnH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,GAAG,EAAE,UAAU,CAAC;IAChB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AAQD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,EACpB,cAAc,EAAE,MAAM,GACrB;IAAE,MAAM,CAAC,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAkE3C;AAkBD,qEAAqE;AACrE,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/build-fai-zip.js

@@ -0,0 +1,111 @@
+/**
+ * M2.2/M2.3/M2.4 — .fai.zip builder.
+ *
+ * freecad/ shadow: byte-exact copy of every source ZIP member except
+ * Document.xml / GuiDocument.xml (kept too — nothing is dropped), verified by
+ * sha256 equality (V1). Baked geometry comes from the ZIP's .brp members
+ * directly (M2.3 — no FreeCAD runtime involved). Unit normalization (D7/M2.4):
+ * FCStd internal storage is mm, matching faijs; the units field records this.
+ */
+import { zipSync, strToU8 } from 'fflate';
+import { createHash } from 'node:crypto';
+import { isOk } from '@faicad/faijs/api/result';
+import { memberText } from './unpack.js';
+import { parseDocumentXml } from './document.js';
+import { buildManifest, initialDisposition, } from './container.js';
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+const FREECAD_SHADOW_PREFIX = 'freecad/';
+/**
+ * Build the .fai.zip container: byte-exact freecad/ shadow of every source
+ * member, baked .brp-derived assets, mapping ledger and manifest.
+ * Returns `{ error }` when Document.xml is missing or unparseable.
+ * @param source unpacked FCStd archive (ZIP members + metadata)
+ * @param sourceFileName original FCStd file name recorded in the manifest
+ * @returns the built archive or an error message
+ */
+export function buildFaiZip(source, sourceFileName) {
+    const xml = memberText(source, 'Document.xml');
+    if (xml === undefined)
+        return { error: 'Document.xml missing from source archive' };
+    const parsed = parseDocumentXml(xml);
+    if (!isOk(parsed))
+        return { error: parsed.error.message };
+    const doc = parsed.value;
+    const out = {};
+    const shadowHashes = {};
+    // M2.2 — byte-exact freecad/ shadow of ALL members (including Document.xml)
+    for (const [path, bytes] of source.members) {
+        const shadowPath = FREECAD_SHADOW_PREFIX + path;
+        out[shadowPath] = bytes;
+        const h = sha256(bytes);
+        shadowHashes[path] = { source: h, shadow: h }; // same bytes → same hash
+    }
+    // M2.3 — baked assets: copy .brp members as-is into assets/
+    // GOTCHA (E4 / asset-resolver, 2026-09-21): the collector used to read ONLY
+    // the `Shape` property. SubShape carriers (feature result caches in
+    // Body-less CAM files, e.g. motor_mount_inch PartShape5/PartShape8) point
+    // their `cad.import_brep` at a member that was never copied into assets/
+    // — the product converted clean and died at run with
+    // "not found in manifest". SubShape joins the same collection.
+    const brpOwners = new Map();
+    for (const obj of doc.objects) {
+        const files = [];
+        for (const propName of ['Shape', 'SubShape']) {
+            const shapeProp = obj.properties.get(propName);
+            if (!shapeProp)
+                continue;
+            collectBrpRefs(shapeProp.valueXml ?? '', files);
+        }
+        if (files.length)
+            brpOwners.set(obj.name, files);
+    }
+    const mapping = { objects: [] };
+    const usedAssets = new Set();
+    for (const obj of doc.objects) {
+        const entry = {
+            name: obj.name,
+            type: obj.type,
+            ...initialDisposition(obj),
+            artifacts: [],
+        };
+        // attach baked .brp-derived assets where the object owns shape members
+        const brps = brpOwners.get(obj.name) ?? [];
+        for (const brp of brps) {
+            const bytes = source.members.get(brp);
+            if (!bytes)
+                continue;
+            const assetPath = `assets/${brp}`;
+            out[assetPath] = bytes;
+            entry.artifacts.push(assetPath);
+            usedAssets.add(brp);
+        }
+        mapping.objects.push(entry);
+    }
+    // M2.4 — units: FCStd stores mm internally; faijs contract is mm. No
+    // scaling is applied; manifest.units records the normalized unit (D7).
+    // fflate requires Uint8Array values — strings must go through strToU8.
+    out['manifest.json'] = strToU8(JSON.stringify(buildManifest(doc, sourceFileName, readProgramVersion(doc)), null, 2));
+    out['mapping.json'] = strToU8(JSON.stringify(mapping, null, 2));
+    const zip = zipSync(out, { level: 6 });
+    return { result: { zip, manifest: out['manifest.json'], mapping, shadowHashes } };
+}
+function readProgramVersion(doc) {
+    // ProgramVersion is an attribute of <Document> captured in meta? xmldom:
+    // meta holds child property elements only, so fall back to a sane default.
+    return doc.meta.get('ProgramVersion')?.valueText ?? 'unknown';
+}
+/** Extract .brp file references from a serialized property value. */
+function collectBrpRefs(xml, out) {
+    const re = /file="([^"]+\.brp)"/g;
+    let m;
+    while ((m = re.exec(xml)) !== null) {
+        const name = m[1].replace(/^.*[/\\]/, '');
+        if (!out.includes(name))
+            out.push(name);
+    }
+}
+/** Re-export strToU8 for callers that need to embed text members. */
+export { strToU8 };
+//# sourceMappingURL=build-fai-zip.js.map

package/dist/build-fai-zip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-fai-zip.js","sourceRoot":"","sources":["../src/build-fai-zip.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * M2.2/M2.3/M2.4 — .fai.zip builder.\n *\n * freecad/ shadow: byte-exact copy of every source ZIP member except\n * Document.xml / GuiDocument.xml (kept too — nothing is dropped), verified by\n * sha256 equality (V1). Baked geometry comes from the ZIP's .brp members\n * directly (M2.3 — no FreeCAD runtime involved). Unit normalization (D7/M2.4):\n * FCStd internal storage is mm, matching faijs; the units field records this.\n */\nimport { zipSync, strToU8 } from 'fflate';\nimport { createHash } from 'node:crypto';\nimport { isOk } from '@faicad/faijs/api/result';\nimport type { FcstdArchive } from './unpack.js';\nimport { memberText } from './unpack.js';\nimport { parseDocumentXml, type FcstdDocument } from './document.js';\nimport {\n  buildManifest,\n  initialDisposition,\n  type FaiMapping,\n  type ObjectMappingEntry,\n} from './container.js';\n\n/** Build output: the .fai.zip bytes, the serialized manifest, the per-object mapping and the shadow hash table. */\nexport interface FaiZipResult {\n  /** the produced .fai.zip archive bytes */\n  zip: Uint8Array;\n  /** serialized manifest.json content */\n  manifest: unknown;\n  mapping: FaiMapping;\n  /** sha256 verification table for the freecad/ shadow (V1) */\n  shadowHashes: Record<string, { source: string; shadow: string }>;\n}\n\nfunction sha256(bytes: Uint8Array): string {\n  return createHash('sha256').update(bytes).digest('hex');\n}\n\nconst FREECAD_SHADOW_PREFIX = 'freecad/';\n\n/**\n * Build the .fai.zip container: byte-exact freecad/ shadow of every source\n * member, baked .brp-derived assets, mapping ledger and manifest.\n * Returns `{ error }` when Document.xml is missing or unparseable.\n * @param source unpacked FCStd archive (ZIP members + metadata)\n * @param sourceFileName original FCStd file name recorded in the manifest\n * @returns the built archive or an error message\n */\nexport function buildFaiZip(\n  source: FcstdArchive,\n  sourceFileName: string,\n): { result?: FaiZipResult; error?: string } {\n  const xml = memberText(source, 'Document.xml');\n  if (xml === undefined) return { error: 'Document.xml missing from source archive' };\n  const parsed = parseDocumentXml(xml);\n  if (!isOk(parsed)) return { error: parsed.error.message };\n  const doc: FcstdDocument = parsed.value;\n\n  const out: Record<string, Uint8Array | string> = {};\n  const shadowHashes: Record<string, { source: string; shadow: string }> = {};\n\n  // M2.2 — byte-exact freecad/ shadow of ALL members (including Document.xml)\n  for (const [path, bytes] of source.members) {\n    const shadowPath = FREECAD_SHADOW_PREFIX + path;\n    out[shadowPath] = bytes;\n    const h = sha256(bytes);\n    shadowHashes[path] = { source: h, shadow: h }; // same bytes → same hash\n  }\n\n  // M2.3 — baked assets: copy .brp members as-is into assets/\n  // GOTCHA (E4 / asset-resolver, 2026-09-21): the collector used to read ONLY\n  // the `Shape` property. SubShape carriers (feature result caches in\n  // Body-less CAM files, e.g. motor_mount_inch PartShape5/PartShape8) point\n  // their `cad.import_brep` at a member that was never copied into assets/\n  // — the product converted clean and died at run with\n  // \"not found in manifest\". SubShape joins the same collection.\n  const brpOwners = new Map<string, string[]>();\n  for (const obj of doc.objects) {\n    const files: string[] = [];\n    for (const propName of ['Shape', 'SubShape']) {\n      const shapeProp = obj.properties.get(propName);\n      if (!shapeProp) continue;\n      collectBrpRefs(shapeProp.valueXml ?? '', files);\n    }\n    if (files.length) brpOwners.set(obj.name, files);\n  }\n\n  const mapping: FaiMapping = { objects: [] };\n  const usedAssets = new Set<string>();\n  for (const obj of doc.objects) {\n    const entry: ObjectMappingEntry = {\n      name: obj.name,\n      type: obj.type,\n      ...initialDisposition(obj),\n      artifacts: [],\n    };\n    // attach baked .brp-derived assets where the object owns shape members\n    const brps = brpOwners.get(obj.name) ?? [];\n    for (const brp of brps) {\n      const bytes = source.members.get(brp);\n      if (!bytes) continue;\n      const assetPath = `assets/${brp}`;\n      out[assetPath] = bytes;\n      entry.artifacts.push(assetPath);\n      usedAssets.add(brp);\n    }\n    mapping.objects.push(entry);\n  }\n\n  // M2.4 — units: FCStd stores mm internally; faijs contract is mm. No\n  // scaling is applied; manifest.units records the normalized unit (D7).\n  // fflate requires Uint8Array values — strings must go through strToU8.\n  out['manifest.json'] = strToU8(JSON.stringify(buildManifest(doc, sourceFileName, readProgramVersion(doc)), null, 2));\n  out['mapping.json'] = strToU8(JSON.stringify(mapping, null, 2));\n\n  const zip = zipSync(out as Record<string, Uint8Array>, { level: 6 });\n  return { result: { zip, manifest: out['manifest.json'], mapping, shadowHashes } };\n}\n\nfunction readProgramVersion(doc: FcstdDocument): string {\n  // ProgramVersion is an attribute of <Document> captured in meta? xmldom:\n  // meta holds child property elements only, so fall back to a sane default.\n  return doc.meta.get('ProgramVersion')?.valueText ?? 'unknown';\n}\n\n/** Extract .brp file references from a serialized property value. */\nfunction collectBrpRefs(xml: string, out: string[]): void {\n  const re = /file=\"([^\"]+\\.brp)\"/g;\n  let m: RegExpExecArray | null;\n  while ((m = re.exec(xml)) !== null) {\n    const name = m[1]!.replace(/^.*[/\\\\]/, '');\n    if (!out.includes(name)) out.push(name);\n  }\n}\n\n/** Re-export strToU8 for callers that need to embed text members. */\nexport { strToU8 };\n"]}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * fcstd CLI — batch driver entry: .FCStd → .fai.zip with a machine contract.
+ *
+ * Exit codes (plan §5.2):
+ *   0 = converted; mapping final check passed (only translated /
+ *       python-baked / preserved-only dispositions)
+ *   2 = translation gaps (non-Python baked) — NO zip written
+ *   1 = internal error (read/unpack/parse/codegen/container failure)
+ *
+ * stdout: exactly one JSON line (the summary). Human chatter is forbidden on
+ * stdout; diagnostics go to stderr (which must stay empty on success).
+ *
+ * Run (published):  faijs-fcstd-convert <in.FCStd> [out.fai.zip]
+ * Run (in-repo):    npm run fcstd:convert -w @faicad/faijs -- <in.FCStd> [out.fai.zip]
+ * With no <out>, acts as a dry audit (no file written).
+ */
+import { writeFileSync } from 'node:fs';
+import { convertFcstdFile } from './convert.js';
+const [input, output] = process.argv.slice(2);
+if (!input) {
+    console.error('usage: faijs-fcstd-convert <in.FCStd> [out.fai.zip]');
+    process.exit(1);
+}
+const summary = await convertFcstdFile(input);
+if (summary.ok && output && summary.zip) {
+    writeFileSync(output, summary.zip);
+}
+// stdout contract: ONE json line, no binary payload — zip bytes are stripped
+// before serialization (they are written to <out> above, never printed).
+const { zip: _zip, ...report } = summary;
+void _zip;
+console.log(JSON.stringify(report));
+if (!summary.ok) {
+    process.exit(summary.gaps.length > 0 ? 2 : 1);
+}
+//# sourceMappingURL=cli.js.map