@chestnutlabs/gcode-renderer-2d 0.3.0

package/README.md

@@ -0,0 +1,46 @@
+# @chestnutlabs/gcode-renderer-2d
+
+Low-resource **Canvas 2D layer renderer** for the [Chestnut Labs G-code Preview](https://github.com/ChestnutLabs/gcode-preview) toolpath stack (DD-014 / Epic E8).
+
+An **opt-in** current/adjacent-layer 2D view over the existing `ToolpathIR`, for contexts where the
+default Three.js renderer is a poor fit: old / low-end mobile, embedded printer touchscreens
+(Fluidd/Mainsail-class UIs), and locked-down or WebGL-blocked browsers. One parse, one IR, a second
+lightweight view — **no second parser path, no `three`, no framework**. Per-segment color is
+single-sourced with the 3D renderer via `@chestnutlabs/gcode-colors`, so the two never disagree.
+
+The memory ceiling is the point: drawing is bounded to the active (± adjacent, later phases) layer,
+never the whole model.
+
+> **Status:** E8 phases 1–3 done. Phase 1 (#212): the Canvas 2D core — draw one layer from the IR,
+> honest color, fit-to-canvas. Phase 2 (#213): current-layer **+ adjacent "ghost" layers** (dimmed
+> preceding layers, `adjacentLayers` default 1 / floor 0) over one stable model frame. Phase 3 (#214):
+> selectable from the viewer via **`<GcodePreview renderer="2d" />`** (the 3D renderer is loaded on
+> demand, so a 2D-only bundle never ships Three.js), plus a **live-progress "completed cut"**
+> (`setProgress`). Still ahead: the low-resource benchmark + capability-honesty UX (#215).
+
+## Usage
+
+```ts
+import { LayerView2D } from '@chestnutlabs/gcode-renderer-2d';
+
+const view = new LayerView2D(canvas, { colorMode: { mode: 'feature', palette, fallback: [0.7, 0.7, 0.7] } });
+view.setToolpath(ir); // a ToolpathIR from the worker parser
+view.setLayer(12);
+view.render(); // clears + redraws the active layer
+```
+
+The drawing core is also exposed as pure functions — `drawLayer(ctx, ir, opts)`, `computeLayerFit`,
+`layerBounds2D`, `rgbToCss` — which take a minimal Canvas-2D-context interface and are fully
+testable in Node with a recording mock.
+
+## Honesty
+
+A flat per-layer 2D view cannot represent non-XY/CNC toolpaths or 3D-only options. A missing or
+out-of-range layer draws nothing and reports `drawn: false` rather than fabricating geometry.
+Color modes that read an optional IR channel (`feature`, `object`, `feedrate`) must be
+capability-gated by the caller. The full capability-honesty UX for non-XY / `layers: unavailable`
+inputs arrives with the phase-4 work (#215).
+
+## License
+
+MIT © Chestnut Labs. See the [repository](https://github.com/ChestnutLabs/gcode-preview) for provenance and the full support policy.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @chestnutlabs/gcode-renderer-2d — low-resource Canvas 2D layer renderer (DD-014 / E8).
+ *
+ * An opt-in current/adjacent-layer 2D view over the existing `ToolpathIR`, for low-GPU,
+ * low-memory, or WebGL-blocked devices (old mobile, embedded printer UIs, locked-down browsers).
+ * One parse, one IR, a second lightweight view — no second parser path, no `three`, no framework.
+ * Per-segment color is single-sourced with the 3D renderer via `@chestnutlabs/gcode-colors`.
+ *
+ * Re-exports the color model so 2D consumers get `ColorMode`/`RGB` from one import.
+ */
+export { LayerView2D, drawLayer, drawLayers, computeLayerFit, layerBounds2D, modelBounds2D, describe2DDisclosures, rgbToCss } from './layer-view.js';
+export type { LayerView2DOptions, DrawLayerOptions, DrawLayerResult, DrawLayersOptions, DrawLayersResult, LayerProgress, LayerFit, LayerBounds2D, TravelStyle, CanvasContext2DLike } from './layer-view.js';
+export type { ColorMode, RGB } from '@chestnutlabs/gcode-colors';
+//# 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;;;;;;;;;GASG;AACH,OAAO,EACL,WAAW,EACX,SAAS,EACT,UAAU,EACV,eAAe,EACf,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,QAAQ,EACT,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,aAAa,EACb,WAAW,EACX,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @chestnutlabs/gcode-renderer-2d — low-resource Canvas 2D layer renderer (DD-014 / E8).
+ *
+ * An opt-in current/adjacent-layer 2D view over the existing `ToolpathIR`, for low-GPU,
+ * low-memory, or WebGL-blocked devices (old mobile, embedded printer UIs, locked-down browsers).
+ * One parse, one IR, a second lightweight view — no second parser path, no `three`, no framework.
+ * Per-segment color is single-sourced with the 3D renderer via `@chestnutlabs/gcode-colors`.
+ *
+ * Re-exports the color model so 2D consumers get `ColorMode`/`RGB` from one import.
+ */
+export { LayerView2D, drawLayer, drawLayers, computeLayerFit, layerBounds2D, modelBounds2D, describe2DDisclosures, rgbToCss } from './layer-view.js';

package/dist/layer-view.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Low-resource Canvas 2D layer view (DD-014 / E8, phase 1, #212).
+ *
+ * Draws a single layer of a `ToolpathIR` as flat, top-down polylines to a Canvas 2D
+ * surface — the memory ceiling is one layer's segments, not the whole model (DD-014 §6/§7).
+ * Geometry is read straight from the SoA in the IR's origin-relative frame; per-segment
+ * color comes from the shared, renderer-agnostic `@chestnutlabs/gcode-colors` so 2D and 3D
+ * never disagree. No `three`, no WebGL.
+ *
+ * The drawing core ({@link drawLayer}, {@link computeLayerFit}) is pure and takes a minimal
+ * {@link CanvasContext2DLike}, so it is fully testable in Node with a recording mock; the
+ * {@link LayerView2D} class is a thin lifecycle wrapper over a real `<canvas>`.
+ */
+import { type ToolpathIR } from '@chestnutlabs/toolpath-core';
+import { type ColorMode, type RGB } from '@chestnutlabs/gcode-colors';
+/** The subset of `CanvasRenderingContext2D` the layer view uses (a real context satisfies it). */
+export type CanvasContext2DLike = Pick<CanvasRenderingContext2D, 'strokeStyle' | 'lineWidth' | 'lineCap' | 'lineJoin' | 'globalAlpha' | 'beginPath' | 'moveTo' | 'lineTo' | 'stroke' | 'clearRect'>;
+/** XY extent of a set of segments, in the IR's origin-relative frame. */
+export interface LayerBounds2D {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+    /** False when the layer has no segments (nothing to fit / draw). */
+    hasContent: boolean;
+}
+/** Maps printer XY (origin-relative) to canvas pixels, with Y flipped (printer up → canvas down). */
+export interface LayerFit {
+    /** World-units-to-pixels scale. */
+    scale: number;
+    /** Project a printer XY point to device pixels `[px, py]`. */
+    project(x: number, y: number): [number, number];
+}
+export interface DrawLayerOptions {
+    /** Index into `ir.layers`. Out-of-range or absent → nothing drawn (honest no-op). */
+    layer: number;
+    /** Per-segment color mode (shared with the 3D renderer). Applied to extrusion moves. */
+    colorMode: ColorMode;
+    /** World→pixel mapping. Usually from {@link computeLayerFit} for the same layer. */
+    fit: LayerFit;
+    /** Extrusion stroke width in device px (default 1). */
+    lineWidth?: number;
+    /** Draw travel moves too, in this style. Omitted/false → extrusion only (the default). */
+    travel?: TravelStyle | false;
+    /** Layer opacity in [0,1] via `globalAlpha` (default 1). Used to dim adjacent "ghost" layers. */
+    opacity?: number;
+    /**
+     * Live-progress "completed cut" (DD-006): the last printed segment index in THIS layer. Extrusion
+     * segments at or before it draw at full opacity; those after it draw at {@link upcomingOpacity}
+     * (not yet printed). Omit for no progress split. Honest — nothing is hidden, only dimmed.
+     */
+    progressCutSeg?: number;
+    /** Opacity of not-yet-printed extrusion when {@link progressCutSeg} is set (default 0.15). */
+    upcomingOpacity?: number;
+}
+export interface TravelStyle {
+    /** CSS color for travel moves (e.g. a muted gray). */
+    color: string;
+    /** Travel stroke width in device px (default 0.5). */
+    lineWidth?: number;
+}
+export interface DrawLayerResult {
+    layer: number;
+    layerCount: number;
+    extrudeDrawn: number;
+    travelDrawn: number;
+    /** False when the layer index is out of range or the IR has no layer table. */
+    drawn: boolean;
+}
+/** Convert a float {@link RGB} triple to a CSS `rgb(...)` string for `strokeStyle`. */
+export declare function rgbToCss(rgb: RGB): string;
+/** XY bounds of one layer's segments (both endpoints), in the origin-relative frame. */
+export declare function layerBounds2D(ir: ToolpathIR, layer: number): LayerBounds2D;
+/**
+ * Fit `bounds` into a `width`×`height` canvas with uniform scale, centered, `padding` px inset,
+ * and the Y axis flipped so higher printer-Y draws higher on screen. Degenerate (zero-span or
+ * empty) bounds fall back to scale 1 centered at the canvas middle.
+ */
+export declare function computeLayerFit(bounds: LayerBounds2D, width: number, height: number, padding?: number): LayerFit;
+/**
+ * Draw one layer of `ir` to `ctx`. Extrusion moves are colored via {@link DrawLayerOptions.colorMode}
+ * (single-sourced with the 3D renderer); travel moves are drawn only when `travel` is given. The
+ * caller is responsible for clearing the canvas and for capability-gating the color mode. Returns an
+ * honest count; a missing/out-of-range layer draws nothing and reports `drawn: false`.
+ */
+export declare function drawLayer(ctx: CanvasContext2DLike, ir: ToolpathIR, opts: DrawLayerOptions): DrawLayerResult;
+/** XY bounds over ALL of the IR's segments — a stable frame for the layer view (not per-layer). */
+export declare function modelBounds2D(ir: ToolpathIR): LayerBounds2D;
+/**
+ * Honest capability disclosures for rendering `ir` as a flat 2D layer view (DD-014 §6/§11). Returns
+ * human-readable notes a consumer UI can show; empty when the IR is faithfully representable (planar
+ * FDM). It never suppresses geometry — it explains what the flat top-down projection cannot convey.
+ *
+ * - `layers: 'unavailable'` (non-planar / CNC / unindexed): the parser put every move on layer 0, so
+ *   the 2D view shows them all in one flat frame — Z variation and non-XY (e.g. `G18`/`G19`) motion
+ *   are not represented.
+ * - `layers: 'inferred'`: layer boundaries are approximate.
+ */
+export declare function describe2DDisclosures(ir: ToolpathIR): string[];
+export interface DrawLayersOptions {
+    /** Active (fully-drawn) layer index. */
+    layer: number;
+    /** Number of preceding layers drawn beneath the active one as dimmed "ghosts" (default 1, floor 0). */
+    adjacentLayers?: number;
+    /** Per-segment color mode for all drawn layers (shared with the 3D renderer). */
+    colorMode: ColorMode;
+    /** Shared world→pixel mapping — the SAME fit for every layer so they overlay in printer XY. */
+    fit: LayerFit;
+    /** Extrusion stroke width in device px (default 1). */
+    lineWidth?: number;
+    /** Draw travel moves too (default hidden). Applied to the active layer only. */
+    travel?: TravelStyle | false;
+    /** Opacity of each ghost layer in [0,1] (default 0.25). The active layer is always fully opaque. */
+    ghostOpacity?: number;
+    /** Live-progress cut (DD-006). Applied only when its `layerIndex` is the active layer. */
+    progress?: LayerProgress | null;
+}
+/** The minimal live-progress shape the 2D view needs (a projection of DD-006's `MappedProgress`). */
+export interface LayerProgress {
+    /** Last printed segment index (global IR index); null when unknown. */
+    segIndex: number | null;
+    /** Layer currently printing; null when unknown. */
+    layerIndex: number | null;
+}
+export interface DrawLayersResult {
+    layer: number;
+    layerCount: number;
+    /** Ghost layer indices actually drawn (oldest→newest, beneath the active layer). */
+    ghostLayers: number[];
+    /** Extrusion segments drawn across the active layer + ghosts. */
+    extrudeDrawn: number;
+    travelDrawn: number;
+    drawn: boolean;
+}
+/**
+ * Draw the active layer over its preceding "ghost" layers (DD-014 D2, #213). Ghosts are the
+ * `adjacentLayers` layers immediately below the active one, drawn first (underneath) and dimmed to
+ * `ghostOpacity`; the active layer is drawn last at full opacity. All layers share ONE `fit`, so
+ * they overlay correctly in printer XY. `adjacentLayers: 0` draws the active layer only (the floor).
+ */
+export declare function drawLayers(ctx: CanvasContext2DLike, ir: ToolpathIR, opts: DrawLayersOptions): DrawLayersResult;
+export interface LayerView2DOptions {
+    /** Initial layer index (default 0). */
+    layer?: number;
+    /** Initial color mode (default single mid-gray). */
+    colorMode?: ColorMode;
+    /** Extrusion stroke width in device px (default 1). */
+    lineWidth?: number;
+    /** Travel style, or false to hide travel (default: hidden). */
+    travel?: TravelStyle | false;
+    /** Padding inset in device px (default 8). */
+    padding?: number;
+    /** Preceding "ghost" layers drawn beneath the active one (default 1, floor 0). */
+    adjacentLayers?: number;
+    /** Ghost-layer opacity in [0,1] (default 0.25). */
+    ghostOpacity?: number;
+}
+/**
+ * A thin lifecycle wrapper binding a `ToolpathIR` to a `<canvas>`: pick a layer, pick a color
+ * mode, `render()`. It owns no WebGL context and holds no per-layer geometry — each `render()`
+ * clears and redraws the active layer (plus its dimmed "ghost" layers), so peak memory stays near
+ * one layer (DD-014 §6). The view frame is the whole-model XY bounds (cached on `setToolpath`), so
+ * scrubbing layers doesn't jump or rescale and ghosts overlay the active layer exactly. Adapter
+ * wiring (the `renderer: '2d' | '3d'` prop) arrives in a later E8 phase.
+ */
+export declare class LayerView2D {
+    private readonly canvas;
+    private ir;
+    private bounds;
+    private layer;
+    private colorMode;
+    private lineWidth;
+    private travel;
+    private padding;
+    private adjacentLayers;
+    private ghostOpacity;
+    private progress;
+    constructor(canvas: HTMLCanvasElement, opts?: LayerView2DOptions);
+    setToolpath(ir: ToolpathIR | null): void;
+    setLayer(layer: number): void;
+    setColorMode(colorMode: ColorMode): void;
+    /** Number of preceding ghost layers drawn beneath the active one (clamped to ≥ 0). */
+    setAdjacentLayers(n: number): void;
+    /** Live-progress cut (DD-006); null clears it. Applied only when on the active layer. */
+    setProgress(progress: LayerProgress | null): void;
+    /** Show/hide travel moves on the active layer (`false` hides). */
+    setTravel(travel: TravelStyle | false): void;
+    /**
+     * Honest capability notes for the current IR (DD-014 §6/§11) — e.g. a non-planar/CNC toolpath the
+     * flat 2D view cannot fully represent. Empty for faithfully-representable (planar) input.
+     */
+    getDisclosures(): string[];
+    /** Number of layers in the current IR (0 when none / no layer table). */
+    get layerCount(): number;
+    /** Clear and redraw the active layer + ghosts. Returns the draw result (drawn:false when empty). */
+    render(): DrawLayersResult;
+}
+//# sourceMappingURL=layer-view.d.ts.map

package/dist/layer-view.d.ts.map

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

package/dist/layer-view.js

@@ -0,0 +1,354 @@
+/**
+ * Low-resource Canvas 2D layer view (DD-014 / E8, phase 1, #212).
+ *
+ * Draws a single layer of a `ToolpathIR` as flat, top-down polylines to a Canvas 2D
+ * surface — the memory ceiling is one layer's segments, not the whole model (DD-014 §6/§7).
+ * Geometry is read straight from the SoA in the IR's origin-relative frame; per-segment
+ * color comes from the shared, renderer-agnostic `@chestnutlabs/gcode-colors` so 2D and 3D
+ * never disagree. No `three`, no WebGL.
+ *
+ * The drawing core ({@link drawLayer}, {@link computeLayerFit}) is pure and takes a minimal
+ * {@link CanvasContext2DLike}, so it is fully testable in Node with a recording mock; the
+ * {@link LayerView2D} class is a thin lifecycle wrapper over a real `<canvas>`.
+ */
+import { MoveKind } from '@chestnutlabs/toolpath-core';
+import { createSegmentColorer } from '@chestnutlabs/gcode-colors';
+/** Clamp a 0..1 float channel and scale to an 8-bit int. */
+function chan(v) {
+    const c = v < 0 ? 0 : v > 1 ? 1 : v;
+    return Math.round(c * 255);
+}
+/** Convert a float {@link RGB} triple to a CSS `rgb(...)` string for `strokeStyle`. */
+export function rgbToCss(rgb) {
+    return `rgb(${chan(rgb[0])}, ${chan(rgb[1])}, ${chan(rgb[2])})`;
+}
+/** XY bounds of one layer's segments (both endpoints), in the origin-relative frame. */
+export function layerBounds2D(ir, layer) {
+    const empty = { minX: 0, minY: 0, maxX: 0, maxY: 0, hasContent: false };
+    const l = ir.layers[layer];
+    if (!l)
+        return empty;
+    const seg = ir.segments;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (let i = l.segStart; i <= l.segEnd && i < seg.count; i++) {
+        const xs = [seg.x0[i], seg.x1[i]];
+        const ys = [seg.y0[i], seg.y1[i]];
+        for (const x of xs) {
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+        }
+        for (const y of ys) {
+            if (y < minY)
+                minY = y;
+            if (y > maxY)
+                maxY = y;
+        }
+    }
+    if (minX > maxX)
+        return empty;
+    return { minX, minY, maxX, maxY, hasContent: true };
+}
+/**
+ * Fit `bounds` into a `width`×`height` canvas with uniform scale, centered, `padding` px inset,
+ * and the Y axis flipped so higher printer-Y draws higher on screen. Degenerate (zero-span or
+ * empty) bounds fall back to scale 1 centered at the canvas middle.
+ */
+export function computeLayerFit(bounds, width, height, padding = 8) {
+    const availW = Math.max(1, width - 2 * padding);
+    const availH = Math.max(1, height - 2 * padding);
+    const spanX = bounds.maxX - bounds.minX;
+    const spanY = bounds.maxY - bounds.minY;
+    const scale = !bounds.hasContent || (spanX <= 0 && spanY <= 0)
+        ? 1
+        : Math.min(spanX > 0 ? availW / spanX : Infinity, spanY > 0 ? availH / spanY : Infinity);
+    const drawnW = spanX * scale;
+    const drawnH = spanY * scale;
+    const offsetX = padding + (availW - drawnW) / 2;
+    const offsetYTop = padding + (availH - drawnH) / 2;
+    const { minX, minY } = bounds;
+    return {
+        scale,
+        project(x, y) {
+            const px = offsetX + (x - minX) * scale;
+            // Flip Y: the top of the drawn box is offsetYTop; printer-Y grows upward.
+            const py = offsetYTop + (drawnH - (y - minY) * scale);
+            return [px, py];
+        }
+    };
+}
+/**
+ * Draw one layer of `ir` to `ctx`. Extrusion moves are colored via {@link DrawLayerOptions.colorMode}
+ * (single-sourced with the 3D renderer); travel moves are drawn only when `travel` is given. The
+ * caller is responsible for clearing the canvas and for capability-gating the color mode. Returns an
+ * honest count; a missing/out-of-range layer draws nothing and reports `drawn: false`.
+ */
+export function drawLayer(ctx, ir, opts) {
+    const layerCount = ir.layers.length;
+    const l = ir.layers[opts.layer];
+    const base = {
+        layer: opts.layer,
+        layerCount,
+        extrudeDrawn: 0,
+        travelDrawn: 0,
+        drawn: false
+    };
+    if (!l)
+        return base;
+    const seg = ir.segments;
+    const colorOf = createSegmentColorer(ir, opts.colorMode);
+    const extrudeWidth = opts.lineWidth ?? 1;
+    const showTravel = opts.travel ? opts.travel : null;
+    ctx.lineCap = 'round';
+    ctx.lineJoin = 'round';
+    const prevAlpha = ctx.globalAlpha;
+    ctx.globalAlpha = opts.opacity ?? 1;
+    // Travel first (underneath), if requested.
+    let travelDrawn = 0;
+    if (showTravel) {
+        ctx.strokeStyle = showTravel.color;
+        ctx.lineWidth = showTravel.lineWidth ?? 0.5;
+        for (let i = l.segStart; i <= l.segEnd && i < seg.count; i++) {
+            if ((seg.kind[i] & MoveKind.Travel) === 0)
+                continue;
+            const [ax, ay] = opts.fit.project(seg.x0[i], seg.y0[i]);
+            const [bx, by] = opts.fit.project(seg.x1[i], seg.y1[i]);
+            ctx.beginPath();
+            ctx.moveTo(ax, ay);
+            ctx.lineTo(bx, by);
+            ctx.stroke();
+            travelDrawn++;
+        }
+    }
+    // Extrusion, colored per-segment. With a progress cut, segments after `progressCutSeg` in this
+    // layer are the not-yet-printed part — drawn dimmed (never hidden), the 2D "completed cut" (DD-006).
+    ctx.lineWidth = extrudeWidth;
+    const baseOpacity = opts.opacity ?? 1;
+    const upcomingOpacity = baseOpacity * (opts.upcomingOpacity ?? 0.15);
+    const cut = opts.progressCutSeg;
+    let extrudeDrawn = 0;
+    for (let i = l.segStart; i <= l.segEnd && i < seg.count; i++) {
+        if ((seg.kind[i] & MoveKind.Extrude) === 0)
+            continue;
+        ctx.globalAlpha = cut !== undefined && i > cut ? upcomingOpacity : baseOpacity;
+        ctx.strokeStyle = rgbToCss(colorOf(i));
+        const [ax, ay] = opts.fit.project(seg.x0[i], seg.y0[i]);
+        const [bx, by] = opts.fit.project(seg.x1[i], seg.y1[i]);
+        ctx.beginPath();
+        ctx.moveTo(ax, ay);
+        ctx.lineTo(bx, by);
+        ctx.stroke();
+        extrudeDrawn++;
+    }
+    ctx.globalAlpha = prevAlpha;
+    return { layer: opts.layer, layerCount, extrudeDrawn, travelDrawn, drawn: true };
+}
+/** XY bounds over ALL of the IR's segments — a stable frame for the layer view (not per-layer). */
+export function modelBounds2D(ir) {
+    const seg = ir.segments;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (let i = 0; i < seg.count; i++) {
+        const x0 = seg.x0[i];
+        const x1 = seg.x1[i];
+        const y0 = seg.y0[i];
+        const y1 = seg.y1[i];
+        if (x0 < minX)
+            minX = x0;
+        if (x1 < minX)
+            minX = x1;
+        if (x0 > maxX)
+            maxX = x0;
+        if (x1 > maxX)
+            maxX = x1;
+        if (y0 < minY)
+            minY = y0;
+        if (y1 < minY)
+            minY = y1;
+        if (y0 > maxY)
+            maxY = y0;
+        if (y1 > maxY)
+            maxY = y1;
+    }
+    if (minX > maxX)
+        return { minX: 0, minY: 0, maxX: 0, maxY: 0, hasContent: false };
+    return { minX, minY, maxX, maxY, hasContent: true };
+}
+/**
+ * Honest capability disclosures for rendering `ir` as a flat 2D layer view (DD-014 §6/§11). Returns
+ * human-readable notes a consumer UI can show; empty when the IR is faithfully representable (planar
+ * FDM). It never suppresses geometry — it explains what the flat top-down projection cannot convey.
+ *
+ * - `layers: 'unavailable'` (non-planar / CNC / unindexed): the parser put every move on layer 0, so
+ *   the 2D view shows them all in one flat frame — Z variation and non-XY (e.g. `G18`/`G19`) motion
+ *   are not represented.
+ * - `layers: 'inferred'`: layer boundaries are approximate.
+ */
+export function describe2DDisclosures(ir) {
+    const notes = [];
+    const layers = ir.header.capabilities['layers'];
+    if (layers === 'unavailable') {
+        notes.push('No planar layer index (non-planar or CNC toolpath): showing all moves in one flat top-down ' +
+            'view. Z variation and non-XY (e.g. G18/G19 plane) motion are not represented in 2D.');
+    }
+    else if (layers === 'inferred') {
+        notes.push('Layer index is inferred; layer boundaries may be approximate.');
+    }
+    return notes;
+}
+/**
+ * Draw the active layer over its preceding "ghost" layers (DD-014 D2, #213). Ghosts are the
+ * `adjacentLayers` layers immediately below the active one, drawn first (underneath) and dimmed to
+ * `ghostOpacity`; the active layer is drawn last at full opacity. All layers share ONE `fit`, so
+ * they overlay correctly in printer XY. `adjacentLayers: 0` draws the active layer only (the floor).
+ */
+export function drawLayers(ctx, ir, opts) {
+    const layerCount = ir.layers.length;
+    const base = {
+        layer: opts.layer,
+        layerCount,
+        ghostLayers: [],
+        extrudeDrawn: 0,
+        travelDrawn: 0,
+        drawn: false
+    };
+    if (!ir.layers[opts.layer])
+        return base;
+    const adjacent = Math.max(0, Math.floor(opts.adjacentLayers ?? 1));
+    const ghostOpacity = opts.ghostOpacity ?? 0.25;
+    const firstGhost = Math.max(0, opts.layer - adjacent);
+    const ghostLayers = [];
+    let extrudeDrawn = 0;
+    let travelDrawn = 0;
+    // Ghosts first (oldest→newest), dimmed, extrusion only — a depth cue, not the focus.
+    for (let li = firstGhost; li < opts.layer; li++) {
+        const r = drawLayer(ctx, ir, {
+            layer: li,
+            colorMode: opts.colorMode,
+            fit: opts.fit,
+            lineWidth: opts.lineWidth,
+            opacity: ghostOpacity
+        });
+        if (r.drawn) {
+            ghostLayers.push(li);
+            extrudeDrawn += r.extrudeDrawn;
+        }
+    }
+    // Active layer last, full opacity, with travel if requested. Apply the progress cut only when the
+    // live-progress layer IS the active layer — otherwise the marker would be misplaced (honest).
+    const p = opts.progress;
+    const progressCutSeg = p != null && p.segIndex != null && p.layerIndex === opts.layer ? p.segIndex : undefined;
+    const active = drawLayer(ctx, ir, {
+        layer: opts.layer,
+        colorMode: opts.colorMode,
+        fit: opts.fit,
+        lineWidth: opts.lineWidth,
+        travel: opts.travel,
+        progressCutSeg
+    });
+    extrudeDrawn += active.extrudeDrawn;
+    travelDrawn += active.travelDrawn;
+    return { layer: opts.layer, layerCount, ghostLayers, extrudeDrawn, travelDrawn, drawn: true };
+}
+const DEFAULT_COLOR_MODE = { mode: 'single', color: [0.55, 0.72, 0.55] };
+/**
+ * A thin lifecycle wrapper binding a `ToolpathIR` to a `<canvas>`: pick a layer, pick a color
+ * mode, `render()`. It owns no WebGL context and holds no per-layer geometry — each `render()`
+ * clears and redraws the active layer (plus its dimmed "ghost" layers), so peak memory stays near
+ * one layer (DD-014 §6). The view frame is the whole-model XY bounds (cached on `setToolpath`), so
+ * scrubbing layers doesn't jump or rescale and ghosts overlay the active layer exactly. Adapter
+ * wiring (the `renderer: '2d' | '3d'` prop) arrives in a later E8 phase.
+ */
+export class LayerView2D {
+    canvas;
+    ir = null;
+    bounds = { minX: 0, minY: 0, maxX: 0, maxY: 0, hasContent: false };
+    layer;
+    colorMode;
+    lineWidth;
+    travel;
+    padding;
+    adjacentLayers;
+    ghostOpacity;
+    progress = null;
+    constructor(canvas, opts = {}) {
+        this.canvas = canvas;
+        this.layer = opts.layer ?? 0;
+        this.colorMode = opts.colorMode ?? DEFAULT_COLOR_MODE;
+        this.lineWidth = opts.lineWidth ?? 1;
+        this.travel = opts.travel ?? false;
+        this.padding = opts.padding ?? 8;
+        this.adjacentLayers = Math.max(0, Math.floor(opts.adjacentLayers ?? 1));
+        this.ghostOpacity = opts.ghostOpacity ?? 0.25;
+    }
+    setToolpath(ir) {
+        this.ir = ir;
+        // Cache the stable whole-model frame once (a scan is O(segments); render() stays layer-bounded).
+        this.bounds = ir ? modelBounds2D(ir) : { minX: 0, minY: 0, maxX: 0, maxY: 0, hasContent: false };
+        if (ir && this.layer > ir.layers.length - 1)
+            this.layer = Math.max(0, ir.layers.length - 1);
+    }
+    setLayer(layer) {
+        this.layer = layer < 0 ? 0 : layer;
+    }
+    setColorMode(colorMode) {
+        this.colorMode = colorMode;
+    }
+    /** Number of preceding ghost layers drawn beneath the active one (clamped to ≥ 0). */
+    setAdjacentLayers(n) {
+        this.adjacentLayers = Math.max(0, Math.floor(n));
+    }
+    /** Live-progress cut (DD-006); null clears it. Applied only when on the active layer. */
+    setProgress(progress) {
+        this.progress = progress;
+    }
+    /** Show/hide travel moves on the active layer (`false` hides). */
+    setTravel(travel) {
+        this.travel = travel;
+    }
+    /**
+     * Honest capability notes for the current IR (DD-014 §6/§11) — e.g. a non-planar/CNC toolpath the
+     * flat 2D view cannot fully represent. Empty for faithfully-representable (planar) input.
+     */
+    getDisclosures() {
+        return this.ir ? describe2DDisclosures(this.ir) : [];
+    }
+    /** Number of layers in the current IR (0 when none / no layer table). */
+    get layerCount() {
+        return this.ir?.layers.length ?? 0;
+    }
+    /** Clear and redraw the active layer + ghosts. Returns the draw result (drawn:false when empty). */
+    render() {
+        const ctx = this.canvas.getContext('2d');
+        const empty = {
+            layer: this.layer,
+            layerCount: this.layerCount,
+            ghostLayers: [],
+            extrudeDrawn: 0,
+            travelDrawn: 0,
+            drawn: false
+        };
+        if (!ctx)
+            return empty;
+        ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+        if (!this.ir)
+            return empty;
+        const fit = computeLayerFit(this.bounds, this.canvas.width, this.canvas.height, this.padding);
+        return drawLayers(ctx, this.ir, {
+            layer: this.layer,
+            adjacentLayers: this.adjacentLayers,
+            colorMode: this.colorMode,
+            fit,
+            lineWidth: this.lineWidth,
+            travel: this.travel,
+            ghostOpacity: this.ghostOpacity,
+            progress: this.progress
+        });
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@chestnutlabs/gcode-renderer-2d",
+  "version": "0.3.0",
+  "description": "Low-resource Canvas 2D layer renderer for the Chestnut Labs G-code viewer (DD-014 / E8): an opt-in current/adjacent-layer 2D view over the existing ToolpathIR for low-GPU/low-memory/WebGL-blocked devices. No three, no framework.",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "canvas",
+    "canvas2d",
+    "low-resource",
+    "layer-view",
+    "renderer"
+  ],
+  "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/gcode-renderer-2d"
+  },
+  "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": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@chestnutlabs/gcode-colors": "0.3.0",
+    "@chestnutlabs/toolpath-core": "0.3.0"
+  }
+}