@chestnutlabs/toolpath-core 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @chestnutlabs/toolpath-core
+
+Neutral **`ToolpathIR`** and **capability model** for the Chestnut Labs G-code Preview toolpath stack.
+This is the replacement seam for the whole stack: the parser **writes** it, renderers and analyzers **read**
+it. See [`docs/design/DD-001`](../../docs/design/DD-001-toolpath-ir-and-capability-model.md).
+
+**Design rules**
+
+- The canonical IR is plain, **transferable** data — a small header plus **structure-of-arrays typed
+  buffers** (not object graphs). Positions are `Float32` deltas relative to a `Float64` `originOffset`
+  (floating origin, DD-001 §4.6).
+- **Unknown is a valid state.** Optional/derived data carries a `Confidence`
+  (`known | inferred | approximated | unavailable`); missing values are sentinels (`NaN`, `0`), never
+  fabricated data.
+- This package depends on **nothing** — no `three`, DOM, Vue, or AnyBridge (DD-002 boundary).
+
+**Contents (scaffold)**
+
+- `ir.ts` — `ToolpathIR`, header, segments (SoA), layers/tools/objects, capabilities, `MoveKind`,
+  `FeatureRole`, `IR_SCHEMA_VERSION`.
+- `builder.ts` — `ToolpathIRBuilder` (accumulate segments → canonical typed-array IR).
+- `source-index.ts` — `buildSourceIndex` / `segmentAtByte` (byte offset → segment; live-progress input).
+- `bounds.ts` — extrude-only and travel-inclusive bounds.
+
+```bash
+npm run build      -w @chestnutlabs/toolpath-core   # tsc -> dist
+npm run typecheck  -w @chestnutlabs/toolpath-core
+npm test           -w @chestnutlabs/toolpath-core
+```
+
+> Status: **scaffold** (E1, issue #32). The builder accumulates into number arrays and converts to typed
+> arrays in `finalize()`; E2's worker parser will write directly into growable typed buffers. Package
+> extraction/publish is gated by DD-002 §7 and the release DD (E7/DD-008).

package/dist/bounds.d.ts

@@ -0,0 +1,11 @@
+import { type ToolpathBounds, type ToolpathSegments, type Vec3 } from './ir.js';
+export declare function emptyBounds(): ToolpathBounds;
+/**
+ * Compute bounds over segment endpoints, converting Float32 deltas back to absolute
+ * coordinates via `origin`. Returns extrude-only bounds and travel-inclusive bounds.
+ */
+export declare function computeSegmentBounds(seg: ToolpathSegments, origin: Vec3): {
+    bounds: ToolpathBounds;
+    boundsWithTravel: ToolpathBounds;
+};
+//# sourceMappingURL=bounds.d.ts.map

package/dist/bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounds.d.ts","sourceRoot":"","sources":["../src/bounds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAE1F,wBAAgB,WAAW,IAAI,cAAc,CAK5C;AAWD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,IAAI,GACX;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,gBAAgB,EAAE,cAAc,CAAA;CAAE,CAkB9D"}

package/dist/bounds.js

@@ -0,0 +1,44 @@
+import { MoveKind } from './ir.js';
+export function emptyBounds() {
+    return {
+        min: { x: Infinity, y: Infinity, z: Infinity },
+        max: { x: -Infinity, y: -Infinity, z: -Infinity }
+    };
+}
+function expand(b, x, y, z) {
+    if (x < b.min.x)
+        b.min.x = x;
+    if (y < b.min.y)
+        b.min.y = y;
+    if (z < b.min.z)
+        b.min.z = z;
+    if (x > b.max.x)
+        b.max.x = x;
+    if (y > b.max.y)
+        b.max.y = y;
+    if (z > b.max.z)
+        b.max.z = z;
+}
+/**
+ * Compute bounds over segment endpoints, converting Float32 deltas back to absolute
+ * coordinates via `origin`. Returns extrude-only bounds and travel-inclusive bounds.
+ */
+export function computeSegmentBounds(seg, origin) {
+    const bounds = emptyBounds();
+    const boundsWithTravel = emptyBounds();
+    for (let i = 0; i < seg.count; i++) {
+        const sx = origin.x + seg.x0[i];
+        const sy = origin.y + seg.y0[i];
+        const sz = origin.z + seg.z0[i];
+        const ex = origin.x + seg.x1[i];
+        const ey = origin.y + seg.y1[i];
+        const ez = origin.z + seg.z1[i];
+        expand(boundsWithTravel, sx, sy, sz);
+        expand(boundsWithTravel, ex, ey, ez);
+        if ((seg.kind[i] & MoveKind.Extrude) !== 0) {
+            expand(bounds, sx, sy, sz);
+            expand(bounds, ex, ey, ez);
+        }
+    }
+    return { bounds, boundsWithTravel };
+}

package/dist/builder.d.ts

@@ -0,0 +1,73 @@
+import { type Confidence, type ObjectInfo, type ToolInfo, type ToolpathIR, type Units, type Vec3, type Warning } from './ir.js';
+/** One motion segment in absolute model coordinates. The builder stores it as a delta from the origin. */
+export interface SegmentInput {
+    x0: number;
+    y0: number;
+    z0: number;
+    x1: number;
+    y1: number;
+    z1: number;
+    /** Extrusion delta; omit or 0 for travel. */
+    e?: number;
+    /** mm/min; omit when unknown (stored as NaN). */
+    feedrate?: number;
+    /** MoveKind bitflags. */
+    kind: number;
+    tool?: number;
+    layer: number;
+    feature?: number;
+    /** Object index + 1; 0/omitted = none. */
+    object?: number;
+    srcByte: number;
+}
+export interface BuilderOptions {
+    parserVersion?: string;
+    units?: Units;
+    unitsSource?: Confidence;
+    source?: {
+        id?: string;
+        byteLength?: number;
+        sha256?: string;
+    };
+    /** Fixed floating-origin reference; defaults to the first segment's start point. */
+    originOffset?: Vec3;
+}
+/**
+ * Accumulates segments and produces a canonical {@link ToolpathIR}.
+ *
+ * The builder accumulates into plain number arrays and converts to typed arrays in
+ * {@link ToolpathIRBuilder.finalize}. The *canonical* IR it returns is already the compact,
+ * transferable typed-array contract from DD-001; E2 (the worker parser) will additionally
+ * write directly into growable typed buffers to avoid the intermediate arrays.
+ */
+export declare class ToolpathIRBuilder {
+    private readonly opts;
+    private originOffset;
+    private readonly x0;
+    private readonly y0;
+    private readonly z0;
+    private readonly x1;
+    private readonly y1;
+    private readonly z1;
+    private readonly e;
+    private readonly feedrate;
+    private readonly kind;
+    private readonly tool;
+    private readonly layer;
+    private readonly feature;
+    private readonly object;
+    private readonly srcByte;
+    private readonly toolsMap;
+    private readonly objectsList;
+    private readonly warnings;
+    private readonly capabilities;
+    constructor(opts?: BuilderOptions);
+    addSegment(s: SegmentInput): void;
+    addWarning(w: Warning): void;
+    setCapability(name: string, confidence: Confidence): void;
+    setTool(info: ToolInfo): void;
+    /** Register an object; returns its 1-based index for use in `SegmentInput.object`. */
+    addObject(info: ObjectInfo): number;
+    finalize(): ToolpathIR;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,UAAU,EAIf,KAAK,KAAK,EACV,KAAK,IAAI,EACT,KAAK,OAAO,EACb,MAAM,SAAS,CAAC;AAIjB,0GAA0G;AAC1G,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,MAAM,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,oFAAoF;IACpF,YAAY,CAAC,EAAE,IAAI,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,YAAY,CAAc;IAElC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAgB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;gBAEnD,IAAI,GAAE,cAAmB;IAKrC,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI;IAwBjC,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI;IAI5B,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAIzD,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAI7B,sFAAsF;IACtF,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IAKnC,QAAQ,IAAI,UAAU;CA4CvB"}

package/dist/builder.js

@@ -0,0 +1,131 @@
+import { IR_SCHEMA_VERSION } from './ir.js';
+import { computeSegmentBounds } from './bounds.js';
+import { buildSourceIndex } from './source-index.js';
+/**
+ * Accumulates segments and produces a canonical {@link ToolpathIR}.
+ *
+ * The builder accumulates into plain number arrays and converts to typed arrays in
+ * {@link ToolpathIRBuilder.finalize}. The *canonical* IR it returns is already the compact,
+ * transferable typed-array contract from DD-001; E2 (the worker parser) will additionally
+ * write directly into growable typed buffers to avoid the intermediate arrays.
+ */
+export class ToolpathIRBuilder {
+    opts;
+    originOffset;
+    x0 = [];
+    y0 = [];
+    z0 = [];
+    x1 = [];
+    y1 = [];
+    z1 = [];
+    e = [];
+    feedrate = [];
+    kind = [];
+    tool = [];
+    layer = [];
+    feature = [];
+    object = [];
+    srcByte = [];
+    toolsMap = new Map();
+    objectsList = [];
+    warnings = [];
+    capabilities = {};
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.originOffset = opts.originOffset ?? null;
+    }
+    addSegment(s) {
+        if (this.originOffset === null) {
+            this.originOffset = { x: s.x0, y: s.y0, z: s.z0 };
+        }
+        const o = this.originOffset;
+        this.x0.push(s.x0 - o.x);
+        this.y0.push(s.y0 - o.y);
+        this.z0.push(s.z0 - o.z);
+        this.x1.push(s.x1 - o.x);
+        this.y1.push(s.y1 - o.y);
+        this.z1.push(s.z1 - o.z);
+        this.e.push(s.e ?? 0);
+        this.feedrate.push(s.feedrate ?? NaN);
+        this.kind.push(s.kind);
+        this.tool.push(s.tool ?? 0);
+        this.layer.push(s.layer);
+        this.feature.push(s.feature ?? 0);
+        this.object.push(s.object ?? 0);
+        this.srcByte.push(s.srcByte);
+        if (s.tool !== undefined && !this.toolsMap.has(s.tool)) {
+            this.toolsMap.set(s.tool, { id: s.tool });
+        }
+    }
+    addWarning(w) {
+        this.warnings.push(w);
+    }
+    setCapability(name, confidence) {
+        this.capabilities[name] = confidence;
+    }
+    setTool(info) {
+        this.toolsMap.set(info.id, info);
+    }
+    /** Register an object; returns its 1-based index for use in `SegmentInput.object`. */
+    addObject(info) {
+        this.objectsList.push(info);
+        return this.objectsList.length;
+    }
+    finalize() {
+        const count = this.x0.length;
+        const segments = {
+            count,
+            x0: Float32Array.from(this.x0),
+            y0: Float32Array.from(this.y0),
+            z0: Float32Array.from(this.z0),
+            x1: Float32Array.from(this.x1),
+            y1: Float32Array.from(this.y1),
+            z1: Float32Array.from(this.z1),
+            e: Float32Array.from(this.e),
+            feedrate: Float32Array.from(this.feedrate),
+            kind: Uint8Array.from(this.kind),
+            tool: Uint16Array.from(this.tool),
+            layer: Uint32Array.from(this.layer),
+            feature: Uint8Array.from(this.feature),
+            object: Uint32Array.from(this.object),
+            srcByte: Uint32Array.from(this.srcByte)
+        };
+        const origin = this.originOffset ?? { x: 0, y: 0, z: 0 };
+        const layers = deriveLayers(segments, origin.z);
+        const { bounds, boundsWithTravel } = computeSegmentBounds(segments, origin);
+        const sourceIndex = buildSourceIndex(segments.srcByte, count);
+        const header = {
+            irSchemaVersion: IR_SCHEMA_VERSION,
+            parserVersion: this.opts.parserVersion ?? 'unknown',
+            source: {
+                id: this.opts.source?.id,
+                byteLength: this.opts.source?.byteLength ?? 0,
+                sha256: this.opts.source?.sha256
+            },
+            units: this.opts.units ?? 'mm',
+            unitsSource: this.opts.unitsSource ?? 'unavailable',
+            originOffset: origin,
+            complete: true,
+            dialects: [],
+            warnings: this.warnings,
+            capabilities: this.capabilities
+        };
+        const tools = [...this.toolsMap.values()].sort((a, b) => a.id - b.id);
+        return { header, segments, layers, tools, objects: this.objectsList, bounds, boundsWithTravel, sourceIndex };
+    }
+}
+/** Group segments into layers by their `layer` index; layer Z is absolute. Assumes dense layer indices. */
+function deriveLayers(seg, originZ) {
+    const byIndex = new Map();
+    for (let i = 0; i < seg.count; i++) {
+        const li = seg.layer[i];
+        const existing = byIndex.get(li);
+        if (existing === undefined) {
+            byIndex.set(li, { z: originZ + seg.z1[i], segStart: i, segEnd: i });
+        }
+        else {
+            existing.segEnd = i;
+        }
+    }
+    return [...byIndex.keys()].sort((a, b) => a - b).map((k) => byIndex.get(k));
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @chestnutlabs/toolpath-core — neutral ToolpathIR and capability model (DD-001).
+ *
+ * Public entry point. This package depends on nothing (no `three`, DOM, Vue, or AnyBridge)
+ * and is the replacement seam for the whole toolpath stack: the parser writes it, renderers
+ * and analyzers read it.
+ */
+export * from './ir.js';
+export * from './builder.js';
+export * from './bounds.js';
+export * from './source-index.js';
+export * from './metadata.js';
+export * from './progress.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @chestnutlabs/toolpath-core — neutral ToolpathIR and capability model (DD-001).
+ *
+ * Public entry point. This package depends on nothing (no `three`, DOM, Vue, or AnyBridge)
+ * and is the replacement seam for the whole toolpath stack: the parser writes it, renderers
+ * and analyzers read it.
+ */
+export * from './ir.js';
+export * from './builder.js';
+export * from './bounds.js';
+export * from './source-index.js';
+export * from './metadata.js';
+export * from './progress.js';

package/dist/ir.d.ts

@@ -0,0 +1,150 @@
+/**
+ * ToolpathIR — the neutral, versioned intermediate representation (DD-001).
+ *
+ * The canonical IR is plain, transferable data: a small metadata header plus
+ * structure-of-arrays (SoA) typed buffers. No class instances, DOM, `three`,
+ * Vue, or consumer (AnyBridge) types appear here. Positions are `Float32`
+ * deltas relative to a `Float64` `originOffset` (floating origin, DD-001 §4.6).
+ */
+/** Bump on any breaking layout/semantic change. Separate from the package version. */
+export declare const IR_SCHEMA_VERSION = 1;
+/** Confidence of an optional/derived datum. `unavailable` is a valid state — never a fabricated 0. */
+export type Confidence = 'known' | 'inferred' | 'approximated' | 'unavailable';
+export type Units = 'mm' | 'in';
+export type Severity = 'info' | 'warn' | 'error';
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Bitflags stored in `ToolpathSegments.kind`. */
+export declare const MoveKind: {
+    readonly None: 0;
+    readonly Extrude: number;
+    readonly Travel: number;
+    readonly Retract: number;
+    readonly Unretract: number;
+    readonly Wipe: number;
+    readonly ArcSegment: number;
+    readonly Seam: number;
+};
+export type MoveKindName = keyof typeof MoveKind;
+/** Feature-role indices stored in `ToolpathSegments.feature` (0 = unknown). */
+export declare const FeatureRole: {
+    readonly Unknown: 0;
+    readonly Perimeter: 1;
+    readonly ExternalPerimeter: 2;
+    readonly Infill: 3;
+    readonly SolidInfill: 4;
+    readonly Support: 5;
+    readonly Skirt: 6;
+    readonly Brim: 7;
+    readonly Bridge: 8;
+    readonly Travel: 9;
+    readonly Custom: 10;
+};
+export type FeatureRoleName = keyof typeof FeatureRole;
+export interface Warning {
+    code: string;
+    message: string;
+    severity: Severity;
+    srcByte?: number;
+    count?: number;
+}
+export interface DialectDecision {
+    id: string;
+    version?: string;
+    confidence: Confidence;
+}
+export interface ToolpathIRHeader {
+    irSchemaVersion: number;
+    parserVersion: string;
+    source: {
+        id?: string;
+        byteLength: number;
+        sha256?: string;
+    };
+    units: Units;
+    unitsSource: Confidence;
+    /** Float64 reference point; segment positions are Float32 deltas from this (DD-001 §4.6). */
+    originOffset: Vec3;
+    complete: boolean;
+    truncatedAtByte?: number;
+    dialects: DialectDecision[];
+    warnings: Warning[];
+    /** Per-field confidence summary, e.g. { featureRoles: 'unavailable', units: 'known' }. */
+    capabilities: Record<string, Confidence>;
+}
+/**
+ * Ordered motion segments as parallel typed arrays of length `count`.
+ * Positions are Float32 deltas relative to `ToolpathIRHeader.originOffset`.
+ * Optional channels use sentinels: `feedrate` NaN = unknown; `feature`/`object` 0 = unknown/none.
+ */
+export interface ToolpathSegments {
+    count: number;
+    x0: Float32Array;
+    y0: Float32Array;
+    z0: Float32Array;
+    x1: Float32Array;
+    y1: Float32Array;
+    z1: Float32Array;
+    /** Extrusion delta for the segment (0 for travel). */
+    e: Float32Array;
+    /** mm/min; NaN when unknown. */
+    feedrate: Float32Array;
+    /** MoveKind bitflags. */
+    kind: Uint8Array;
+    /** Index into `tools`. */
+    tool: Uint16Array;
+    /** Index into `layers`. */
+    layer: Uint32Array;
+    /** FeatureRole index; 0 = unknown. */
+    feature: Uint8Array;
+    /** Index into `objects` + 1; 0 = none/unknown. */
+    object: Uint32Array;
+    /** Byte offset in the source of the command that produced this segment. */
+    srcByte: Uint32Array;
+}
+export interface ToolpathLayer {
+    /** Absolute Z of the layer. */
+    z: number;
+    segStart: number;
+    segEnd: number;
+}
+export interface ToolInfo {
+    id: number;
+    color?: RGBA;
+    material?: string;
+}
+export interface ObjectInfo {
+    id: string;
+    name?: string;
+}
+export interface ToolpathBounds {
+    min: Vec3;
+    max: Vec3;
+}
+/** Sorted parallel arrays enabling `byteOffset -> segmentIndex` via binary search (E5/DD-006 input). */
+export interface SourceIndex {
+    byteOffsets: Uint32Array;
+    segmentIndices: Uint32Array;
+}
+export interface ToolpathIR {
+    header: ToolpathIRHeader;
+    segments: ToolpathSegments;
+    layers: ToolpathLayer[];
+    tools: ToolInfo[];
+    objects: ObjectInfo[];
+    /** Bounds over extruding moves only. */
+    bounds: ToolpathBounds;
+    /** Bounds including travel moves. */
+    boundsWithTravel: ToolpathBounds;
+    sourceIndex: SourceIndex;
+}
+//# sourceMappingURL=ir.d.ts.map

package/dist/ir.d.ts.map

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

package/dist/ir.js

@@ -0,0 +1,35 @@
+/**
+ * ToolpathIR — the neutral, versioned intermediate representation (DD-001).
+ *
+ * The canonical IR is plain, transferable data: a small metadata header plus
+ * structure-of-arrays (SoA) typed buffers. No class instances, DOM, `three`,
+ * Vue, or consumer (AnyBridge) types appear here. Positions are `Float32`
+ * deltas relative to a `Float64` `originOffset` (floating origin, DD-001 §4.6).
+ */
+/** Bump on any breaking layout/semantic change. Separate from the package version. */
+export const IR_SCHEMA_VERSION = 1;
+/** Bitflags stored in `ToolpathSegments.kind`. */
+export const MoveKind = {
+    None: 0,
+    Extrude: 1 << 0,
+    Travel: 1 << 1,
+    Retract: 1 << 2,
+    Unretract: 1 << 3,
+    Wipe: 1 << 4,
+    ArcSegment: 1 << 5,
+    Seam: 1 << 6
+};
+/** Feature-role indices stored in `ToolpathSegments.feature` (0 = unknown). */
+export const FeatureRole = {
+    Unknown: 0,
+    Perimeter: 1,
+    ExternalPerimeter: 2,
+    Infill: 3,
+    SolidInfill: 4,
+    Support: 5,
+    Skirt: 6,
+    Brim: 7,
+    Bridge: 8,
+    Travel: 9,
+    Custom: 10
+};

package/dist/metadata.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Dialect/machine metadata data contracts (DD-005 §4.2, as amended).
+ *
+ * Pure data types — no behavior. They live in toolpath-core (not
+ * @chestnutlabs/gcode-dialects) because every layer consumes them as values:
+ * the parser carries them beside the IR in ParseResult/protocol messages and
+ * the renderer applies MachineGeometry as a build volume — neither may depend
+ * on the dialects package (DD-002 §5 boundaries). The behavioral contracts
+ * (DialectAdapter, AnnotationSink, registry) live in gcode-dialects.
+ */
+import type { Confidence } from './ir.js';
+export interface Point2 {
+    x: number;
+    y: number;
+}
+/** A 2D region in printer coordinates (excluded areas etc.). */
+export interface Region2 {
+    kind: 'rect' | 'polygon';
+    points: Point2[];
+}
+/**
+ * Machine/bed geometry discovered from a file (DD-005 §4.2, amendment 2).
+ * Never fabricated: absent means unknown, and consumers must not invent one.
+ */
+export interface MachineGeometry {
+    bed: {
+        kind: 'rect';
+        min: Point2;
+        max: Point2;
+    } | {
+        kind: 'circular';
+        center: Point2;
+        diameter: number;
+    } | {
+        kind: 'polygon';
+        points: Point2[];
+    };
+    /** Printer-coordinate origin location — explicit, not a convention flag. */
+    origin: Point2;
+    /** Regions the toolhead must avoid (Klipper excludes, Bambu excluded areas). */
+    excludedRegions?: Region2[];
+    heightMm?: number;
+    printerName?: string;
+    /** 'known' from container/config data; 'inferred' from slicer comments. */
+    confidence: Confidence;
+    /** Provenance: which adapter concluded this, from what evidence. */
+    source: {
+        adapterId: string;
+        evidence: string;
+        srcByte?: number;
+    };
+}
+/** A dialect detection decision with its evidence (DD-005 §4.1). */
+export interface DialectDetection {
+    dialectId: string;
+    /** 'slicer' and 'firmware' adapters compose (amendment 1). */
+    kind: 'slicer' | 'firmware' | 'generic';
+    confidence: Confidence;
+    evidence: string;
+}
+export interface FilamentInfo {
+    slot: number;
+    type?: string;
+    color?: string;
+    name?: string;
+}
+export interface ThumbnailData {
+    width: number;
+    height: number;
+    mime: string;
+    bytes: Uint8Array;
+}
+/**
+ * Optional result metadata riding beside the IR (DD-005 §4.2) — no IR schema
+ * bump; structured-cloneable across the worker boundary (thumbnail bytes
+ * transferable).
+ */
+export interface DialectMetadata {
+    /** Every applied adapter (composition, amendment 1). */
+    dialects?: DialectDetection[];
+    machine?: MachineGeometry;
+    filaments?: FilamentInfo[];
+    thumbnails?: ThumbnailData[];
+    /** Whitelisted key/value settings only — bounded, never local paths. */
+    raw?: Record<string, string>;
+}
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,gEAAgE;AAChE,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EACC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAC1C;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GACtD;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC1C,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,eAAe,CAAC,EAAE,OAAO,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,UAAU,EAAE,UAAU,CAAC;IACvB,oEAAoE;IACpE,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IACxC,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B"}

package/dist/metadata.js

@@ -0,0 +1 @@
+export {};

package/dist/progress.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Normalized live progress: observation contract + source-position mapper (DD-006).
+ *
+ * A host (e.g. AnyBridge) pushes `ProgressObservation`s built from its own telemetry;
+ * `createProgressMapper` turns each into a `MappedProgress` over an existing `ToolpathIR`
+ * using the fallback hierarchy of DD-006 §4.3: byte > line (reserved) > layer > percent.
+ * Everything here is plain serializable data and pure IR math — no telemetry transport,
+ * no worker round-trip, O(log n) per observation.
+ *
+ * Honesty rules are the point: confidence reuses the DD-001 vocabulary, approximate tiers
+ * carry an uncertainty band instead of pretending to be a point, and unusable observations
+ * degrade to `unavailable` — never a fabricated position.
+ */
+import { type Confidence, type ToolpathIR } from './ir.js';
+/** Contract version of `ProgressObservation`. Bump only on breaking shape changes. */
+export declare const PROGRESS_OBSERVATION_VERSION = 1;
+/** Default staleness threshold (DD-006 §4.4.3). */
+export declare const DEFAULT_STALE_AFTER_MS = 10000;
+/** What a percent observation measures — decides how it maps (DD-006 D4). */
+export type ProgressPercentBasis = 'bytes' | 'job' | 'unknown';
+export type ProgressJobState = 'printing' | 'paused' | 'complete' | 'cancelled' | 'unknown';
+/** Identity evidence for the file the printer is executing (mismatch detection, DD-006 §4.4.1). */
+export interface ProgressFileIdentity {
+    name?: string;
+    sizeBytes?: number;
+    sha256?: string;
+}
+export interface ProgressPosition {
+    /** Exact byte offset into the byte stream the parser consumed (DD-006 §4.4.1 byte domain). */
+    byte?: number;
+    /** 0-based source line. Reserved (D3): carried and serialized, not mapped in v1. */
+    line?: number;
+    /** Current layer as reported by the printer/host (numbering caveats, DD-006 §4.3). */
+    layer?: number;
+    totalLayers?: number;
+    /** Fraction 0..1. */
+    percent?: number;
+    percentBasis?: ProgressPercentBasis;
+}
+/** One consumer-supplied snapshot of where the printer is. All position facts optional. */
+export interface ProgressObservation {
+    v: 1;
+    /** Consumer clock (ms) — drives staleness via `tick()`. */
+    timestampMs: number;
+    file?: ProgressFileIdentity;
+    position?: ProgressPosition;
+    state?: ProgressJobState;
+}
+/** Which observation fact won the fallback hierarchy. */
+export type ProgressBasis = 'byte' | 'line' | 'layer' | 'percent' | 'none';
+export interface ProgressNote {
+    code: string;
+    message?: string;
+}
+export interface MappedProgress {
+    /** Last segment at-or-before the observed position; null when unavailable (or before the first segment). */
+    segIndex: number | null;
+    basis: ProgressBasis;
+    /** DD-001 vocabulary (D2): byte→known, line/layer→inferred, percent→approximated, none→unavailable. */
+    confidence: Confidence;
+    /** Inclusive uncertainty band [loSeg, hiSeg]; a point (lo === hi) for the byte tier. */
+    band: [number, number] | null;
+    layerIndex: number | null;
+    /** True once `tick(now)` observes `now - timestampMs > staleAfterMs`. */
+    stale: boolean;
+    /** Structured degradation reasons (capped at {@link MAX_PROGRESS_NOTES}). */
+    notes: ProgressNote[];
+}
+export interface ProgressMapperOptions {
+    /** Staleness threshold in ms (default {@link DEFAULT_STALE_AFTER_MS}). */
+    staleAfterMs?: number;
+    /** Byte length of the parsed source; enables percent(bytes) promotion to the byte tier (D4). */
+    fileSizeBytes?: number;
+}
+export interface ProgressMapper {
+    /** Map one observation. Never throws on observation content (DD-006 §6). */
+    observe(obs: ProgressObservation): MappedProgress;
+    /** Recompute staleness against `nowMs` without a new observation. */
+    tick(nowMs: number): MappedProgress;
+    reset(): void;
+}
+/** Notes are bounded so a hostile/buggy host cannot grow memory (DD-006 §7). */
+export declare const MAX_PROGRESS_NOTES = 8;
+/**
+ * Build a `ProgressMapper` over a parsed IR. The mapper keeps only the last observation's
+ * timestamp/result (for `tick`); it never mutates the IR.
+ */
+export declare function createProgressMapper(ir: ToolpathIR, opts?: ProgressMapperOptions): ProgressMapper;
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAG3D,sFAAsF;AACtF,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C,mDAAmD;AACnD,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,6EAA6E;AAC7E,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;AAE/D,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5F,mGAAmG;AACnG,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACrC;AAED,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC,CAAC,EAAE,CAAC,CAAC;IACL,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,4GAA4G;IAC5G,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,aAAa,CAAC;IACrB,uGAAuG;IACvG,UAAU,EAAE,UAAU,CAAC;IACvB,wFAAwF;IACxF,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;IACf,6EAA6E;IAC7E,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,cAAc,CAAC;IAClD,qEAAqE;IACrE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;IACpC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AA0EpC;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,cAAc,CAmQjG"}

package/dist/progress.js

@@ -0,0 +1,316 @@
+import { segmentAtByte } from './source-index.js';
+/** Contract version of `ProgressObservation`. Bump only on breaking shape changes. */
+export const PROGRESS_OBSERVATION_VERSION = 1;
+/** Default staleness threshold (DD-006 §4.4.3). */
+export const DEFAULT_STALE_AFTER_MS = 10_000;
+/** Notes are bounded so a hostile/buggy host cannot grow memory (DD-006 §7). */
+export const MAX_PROGRESS_NOTES = 8;
+/** Widening factor for percent(bytes) promotion: the source is still a fraction (§4.3 tier 4). */
+const PERCENT_BYTES_BAND_FRACTION = 0.005;
+/** Minimum half-width for ordinal percent interpolation (§4.3 tier 5). */
+const PERCENT_ORDINAL_BAND_FRACTION = 0.02;
+/** Relative file-size disagreement that demotes the byte domain (§4.4.1). */
+const FILE_SIZE_MISMATCH_TOLERANCE = 0.001;
+/** Reported-vs-IR layer-count disagreement beyond which the reported layer is a fraction (§4.3). */
+const LAYER_COUNT_MISMATCH_TOLERANCE = 2;
+/** Backward layer movement at or below this re-syncs silently (§4.4.2). */
+const REGRESSION_LAYER_TOLERANCE = 2;
+const UNAVAILABLE = Object.freeze({
+    segIndex: null,
+    basis: 'none',
+    confidence: 'unavailable',
+    band: null,
+    layerIndex: null,
+    stale: false,
+    notes: []
+});
+function finiteNonNegative(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** Extract the usable numeric facts, noting (not throwing on) malformed ones (DD-006 §6). */
+function sanitizePosition(position, notes) {
+    const out = { percentBasis: 'unknown' };
+    if (position === undefined || position === null || typeof position !== 'object')
+        return out;
+    for (const field of ['byte', 'line', 'layer', 'totalLayers', 'percent']) {
+        const raw = position[field];
+        if (raw === undefined || raw === null)
+            continue;
+        const value = finiteNonNegative(raw);
+        if (value === undefined) {
+            pushNote(notes, { code: 'invalid-field', message: `position.${field} ignored` });
+        }
+        else {
+            out[field] = value;
+        }
+    }
+    if (out.percent !== undefined && out.percent > 1) {
+        pushNote(notes, { code: 'invalid-field', message: 'position.percent > 1 ignored' });
+        out.percent = undefined;
+    }
+    if (position.percentBasis === 'bytes' || position.percentBasis === 'job') {
+        out.percentBasis = position.percentBasis;
+    }
+    return out;
+}
+function pushNote(notes, note) {
+    if (notes.length < MAX_PROGRESS_NOTES)
+        notes.push(note);
+}
+function clampSeg(ir, seg) {
+    return Math.max(0, Math.min(ir.segments.count - 1, seg));
+}
+function layerOfSegment(ir, segIndex) {
+    if (segIndex === null || ir.segments.count === 0)
+        return null;
+    return ir.segments.layer[segIndex];
+}
+/**
+ * Build a `ProgressMapper` over a parsed IR. The mapper keeps only the last observation's
+ * timestamp/result (for `tick`); it never mutates the IR.
+ */
+export function createProgressMapper(ir, opts) {
+    const staleAfterMs = opts?.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    const fileSizeBytes = finiteNonNegative(opts?.fileSizeBytes);
+    let lastTimestampMs = null;
+    let lastResult = UNAVAILABLE;
+    function mapByte(byte, confidence, bandHalfWidth, notes) {
+        const seg = segmentAtByte(ir.sourceIndex, byte);
+        if (seg === -1) {
+            // Position precedes the first segment: nothing completed yet — honest empty, not seg 0.
+            pushNote(notes, { code: 'before-first-segment' });
+            return { segIndex: null, basis: 'byte', confidence, band: null, layerIndex: null, stale: false, notes };
+        }
+        const lo = clampSeg(ir, seg - bandHalfWidth);
+        const hi = clampSeg(ir, seg + bandHalfWidth);
+        return {
+            segIndex: seg,
+            basis: 'byte',
+            confidence,
+            band: [lo, hi],
+            layerIndex: layerOfSegment(ir, seg),
+            stale: false,
+            notes
+        };
+    }
+    function mapLayer(reported, notes) {
+        const layerCount = ir.layers.length;
+        let layer = Math.floor(reported);
+        if (layer >= layerCount) {
+            pushNote(notes, { code: 'layer-out-of-range', message: `reported ${layer}, IR has ${layerCount}` });
+            layer = layerCount - 1;
+        }
+        const entry = ir.layers[layer];
+        // segEnd is inclusive; "somewhere in layer L" maps to its last segment with a whole-layer band.
+        return {
+            segIndex: entry.segEnd,
+            basis: 'layer',
+            confidence: 'inferred',
+            band: [entry.segStart, entry.segEnd],
+            layerIndex: layer,
+            stale: false,
+            notes
+        };
+    }
+    function mapPercentOrdinal(percent, notes) {
+        const count = ir.segments.count;
+        const seg = clampSeg(ir, Math.round(percent * (count - 1)));
+        const halfWidth = Math.ceil(count * PERCENT_ORDINAL_BAND_FRACTION);
+        const layer = ir.segments.layer[seg];
+        const entry = ir.layers[layer];
+        // Band: at least ±2% of segments, widened to cover the whole containing layer (§4.3 tier 5).
+        const lo = Math.min(clampSeg(ir, seg - halfWidth), entry?.segStart ?? seg);
+        const hi = Math.max(clampSeg(ir, seg + halfWidth), entry?.segEnd ?? seg);
+        return {
+            segIndex: seg,
+            basis: 'percent',
+            confidence: 'approximated',
+            band: [lo, hi],
+            layerIndex: layer,
+            stale: false,
+            notes
+        };
+    }
+    /**
+     * File-identity check (§4.4.1). A hash disagreement kills the mapping outright; a size
+     * disagreement demotes the byte domain (byte + percent-bytes promotion) to fraction mapping.
+     */
+    function checkIdentity(file, notes) {
+        if (file === undefined || file === null || typeof file !== 'object')
+            return 'ok';
+        const expectedSha = ir.header.source.sha256;
+        if (typeof file.sha256 === 'string' && expectedSha !== undefined && file.sha256 !== expectedSha) {
+            pushNote(notes, { code: 'file-mismatch', message: 'sha256 disagrees with the parsed source' });
+            return 'unavailable';
+        }
+        const obsSize = finiteNonNegative(file.sizeBytes);
+        const expectedSize = fileSizeBytes ?? finiteNonNegative(ir.header.source.byteLength);
+        if (obsSize !== undefined && expectedSize !== undefined && expectedSize > 0) {
+            if (Math.abs(obsSize - expectedSize) / expectedSize > FILE_SIZE_MISMATCH_TOLERANCE) {
+                pushNote(notes, {
+                    code: 'file-mismatch',
+                    message: `sizeBytes ${obsSize} vs parsed ${expectedSize}`
+                });
+                return 'demote';
+            }
+        }
+        return 'ok';
+    }
+    /**
+     * Cross-check the winning tier against a reported layer (§4.3): disagreement beyond one layer
+     * widens the band to cover both — precision claims stay evidence-backed, tiers never switch silently.
+     */
+    function applyLayerCrossCheck(result, reportedLayerRaw) {
+        if (result.layerIndex === null || result.band === null || ir.layers.length === 0)
+            return result;
+        const reported = Math.min(Math.max(Math.floor(reportedLayerRaw), 0), ir.layers.length - 1);
+        if (Math.abs(result.layerIndex - reported) <= 1)
+            return result;
+        const entry = ir.layers[reported];
+        const notes = [...result.notes];
+        pushNote(notes, {
+            code: 'cross-check-disagrees',
+            message: `mapped layer ${result.layerIndex}, reported ${reported}`
+        });
+        return {
+            ...result,
+            band: [Math.min(result.band[0], entry.segStart), Math.max(result.band[1], entry.segEnd)],
+            notes
+        };
+    }
+    function map(obs) {
+        if (ir.segments.count === 0)
+            return { ...UNAVAILABLE, notes: [{ code: 'empty-ir' }] };
+        if (obs.v !== PROGRESS_OBSERVATION_VERSION) {
+            return { ...UNAVAILABLE, notes: [{ code: 'version-unsupported' }] };
+        }
+        const notes = [];
+        const p = sanitizePosition(obs.position, notes);
+        const identity = checkIdentity(obs.file, notes);
+        if (identity === 'unavailable') {
+            // A marker on the wrong file is worse than no marker (§4.4.1).
+            return { ...UNAVAILABLE, notes };
+        }
+        // `complete` maps to the final segment regardless of position facts (§4.4.3).
+        if (obs.state === 'complete') {
+            const last = ir.segments.count - 1;
+            return {
+                segIndex: last,
+                basis: p.byte !== undefined ? 'byte' : 'none',
+                confidence: 'known',
+                band: [last, last],
+                layerIndex: layerOfSegment(ir, last),
+                stale: false,
+                notes
+            };
+        }
+        // Fallback hierarchy (§4.3): highest-precision usable fact wins.
+        if (p.byte !== undefined) {
+            if (identity === 'demote') {
+                // The printer's byte domain is not our parsed stream: map its byte as a fraction of
+                // ITS file (tier 5), keeping the basis honest about which fact was used.
+                const theirSize = finiteNonNegative(obs.file?.sizeBytes);
+                if (theirSize !== undefined && theirSize > 0) {
+                    const demoted = mapPercentOrdinal(Math.min(1, p.byte / theirSize), notes);
+                    const withBasis = { ...demoted, basis: 'byte' };
+                    return p.layer !== undefined ? applyLayerCrossCheck(withBasis, p.layer) : withBasis;
+                }
+                return { ...UNAVAILABLE, notes };
+            }
+            const mapped = mapByte(p.byte, 'known', 0, notes);
+            return p.layer !== undefined ? applyLayerCrossCheck(mapped, p.layer) : mapped;
+        }
+        if (p.line !== undefined) {
+            // Reserved tier (D3): carried but unmapped in v1 — fall through, visibly.
+            pushNote(notes, { code: 'line-unmapped', message: 'no line index in v1; falling through' });
+        }
+        // Size usable for percent(bytes) promotion — untrusted after an identity demotion.
+        const promoSize = identity === 'demote'
+            ? undefined // their fraction is of a different byte stream — no promotion
+            : (fileSizeBytes ?? finiteNonNegative(obs.file?.sizeBytes) ?? finiteNonNegative(ir.header.source.byteLength));
+        /** Segment the percent fact points at on its own (for cross-checking a winning layer tier). */
+        function percentImpliedSegment(percent) {
+            if (p.percentBasis === 'bytes' && promoSize !== undefined && promoSize > 0) {
+                const seg = segmentAtByte(ir.sourceIndex, Math.round(percent * promoSize));
+                return seg === -1 ? 0 : seg;
+            }
+            return clampSeg(ir, Math.round(percent * (ir.segments.count - 1)));
+        }
+        if (p.layer !== undefined && ir.layers.length > 0) {
+            if (p.totalLayers !== undefined &&
+                p.totalLayers > 0 &&
+                Math.abs(p.totalLayers - ir.layers.length) > LAYER_COUNT_MISMATCH_TOLERANCE) {
+                // The reporter counts layers differently than the IR: its index is untrustworthy as an
+                // index, but still meaningful as a fraction (§4.3 layer caveats).
+                pushNote(notes, {
+                    code: 'layer-count-mismatch',
+                    message: `reported total ${p.totalLayers}, IR has ${ir.layers.length}`
+                });
+                const fraction = Math.min(1, p.layer / p.totalLayers);
+                return { ...mapPercentOrdinal(fraction, notes), basis: 'layer' };
+            }
+            const mapped = mapLayer(p.layer, notes);
+            // Winning layer tier is validated against the percent fact when both are present (§4.3).
+            return p.percent !== undefined
+                ? applyLayerCrossCheck(mapped, ir.segments.layer[percentImpliedSegment(p.percent)])
+                : mapped;
+        }
+        if (p.percent !== undefined) {
+            if (p.percentBasis === 'bytes' && promoSize !== undefined && promoSize > 0) {
+                // Promotion (D4): arithmetic is exact, the source is still a fraction → approximated + band.
+                const halfWidth = Math.ceil(ir.segments.count * PERCENT_BYTES_BAND_FRACTION);
+                const mapped = {
+                    ...mapByte(Math.round(p.percent * promoSize), 'approximated', halfWidth, notes),
+                    basis: 'percent'
+                };
+                return p.layer !== undefined ? applyLayerCrossCheck(mapped, p.layer) : mapped;
+            }
+            return mapPercentOrdinal(p.percent, notes);
+        }
+        if (notes.length === 0)
+            pushNote(notes, { code: 'no-position-facts' });
+        return { ...UNAVAILABLE, notes };
+    }
+    /** Append a note to a finished result (copy-on-write; respects the cap). */
+    function withNote(result, code, message) {
+        const notes = [...result.notes];
+        pushNote(notes, message === undefined ? { code } : { code, message });
+        return { ...result, notes };
+    }
+    return {
+        observe(obs) {
+            const prev = lastResult;
+            let result = map(obs);
+            // `cancelled`/`unknown` with no usable facts keep the last mapped position, flagged (§4.4.3).
+            const state = obs?.state;
+            if ((state === 'cancelled' || state === 'unknown') && result.basis === 'none' && prev.segIndex !== null) {
+                result = withNote({ ...prev, stale: false }, state === 'cancelled' ? 'job-cancelled' : 'state-unknown');
+            }
+            else if (state === 'cancelled') {
+                result = withNote(result, 'job-cancelled');
+            }
+            // Regression (§4.4.2): re-sync always; a jump back beyond tolerance is visible, not dropped.
+            if (prev.layerIndex !== null &&
+                result.layerIndex !== null &&
+                prev.layerIndex - result.layerIndex > REGRESSION_LAYER_TOLERANCE) {
+                result = withNote(result, 'position-regressed', `layer ${prev.layerIndex} -> ${result.layerIndex}`);
+            }
+            lastTimestampMs =
+                typeof obs?.timestampMs === 'number' && Number.isFinite(obs.timestampMs) ? obs.timestampMs : null;
+            lastResult = result;
+            return result;
+        },
+        tick(nowMs) {
+            if (lastTimestampMs === null)
+                return lastResult;
+            const stale = nowMs - lastTimestampMs > staleAfterMs;
+            if (stale !== lastResult.stale)
+                lastResult = { ...lastResult, stale };
+            return lastResult;
+        },
+        reset() {
+            lastTimestampMs = null;
+            lastResult = UNAVAILABLE;
+        }
+    };
+}

package/dist/source-index.d.ts

@@ -0,0 +1,13 @@
+import { type SourceIndex } from './ir.js';
+/**
+ * Build the source-position index: sort segments by their source byte offset so a
+ * consumer (live progress, E5/DD-006) can map `byteOffset -> segmentIndex`.
+ */
+export declare function buildSourceIndex(srcByte: Uint32Array, count: number): SourceIndex;
+/**
+ * Return the segment index for the largest indexed byte offset `<= byteOffset`,
+ * or `-1` if `byteOffset` precedes the first segment. Exact where an offset matches;
+ * otherwise resolves to the segment in progress at that offset.
+ */
+export declare function segmentAtByte(index: SourceIndex, byteOffset: number): number;
+//# sourceMappingURL=source-index.d.ts.map

package/dist/source-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-index.d.ts","sourceRoot":"","sources":["../src/source-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAUjF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAe5E"}

package/dist/source-index.js

@@ -0,0 +1,37 @@
+/**
+ * Build the source-position index: sort segments by their source byte offset so a
+ * consumer (live progress, E5/DD-006) can map `byteOffset -> segmentIndex`.
+ */
+export function buildSourceIndex(srcByte, count) {
+    const order = Array.from({ length: count }, (_, i) => i);
+    order.sort((a, b) => srcByte[a] - srcByte[b]);
+    const byteOffsets = new Uint32Array(count);
+    const segmentIndices = new Uint32Array(count);
+    for (let k = 0; k < count; k++) {
+        byteOffsets[k] = srcByte[order[k]];
+        segmentIndices[k] = order[k];
+    }
+    return { byteOffsets, segmentIndices };
+}
+/**
+ * Return the segment index for the largest indexed byte offset `<= byteOffset`,
+ * or `-1` if `byteOffset` precedes the first segment. Exact where an offset matches;
+ * otherwise resolves to the segment in progress at that offset.
+ */
+export function segmentAtByte(index, byteOffset) {
+    const offsets = index.byteOffsets;
+    let lo = 0;
+    let hi = offsets.length - 1;
+    let ans = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (offsets[mid] <= byteOffset) {
+            ans = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return ans === -1 ? -1 : index.segmentIndices[ans];
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@chestnutlabs/toolpath-core",
+  "version": "0.1.0",
+  "description": "Neutral ToolpathIR and capability model for the Chestnut Labs G-code Preview toolpath stack.",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "toolpath-ir",
+    "intermediate-representation",
+    "capability-model",
+    "progress"
+  ],
+  "author": "Chestnut Labs",
+  "homepage": "https://github.com/ChestnutLabs/gcode-preview#readme",
+  "bugs": "https://github.com/ChestnutLabs/gcode-preview/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChestnutLabs/gcode-preview.git",
+    "directory": "packages/toolpath-core"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}