@chestnutlabs/gcode-preview-element 0.18.0 → 0.20.0

package/README.md

@@ -43,29 +43,89 @@ Scalar options are **attributes** (also settable as properties); rich options ar
 | Attribute | Property | Type | Default |
 |---|---|---|---|
 | `quality` | `quality` | `'auto' \| 'lines' \| 'tubes'` | `'auto'` |
+| `renderer` | `renderer` | `'3d' \| '2d'` — **construction-time** | `'3d'` |
+| `adjacent-layers` | `adjacentLayers` | integer (2D ghost layers) — **construction-time** | — |
 | `camera-mode` | `cameraMode` | `'perspective' \| 'orthographic'` | `'perspective'` |
 | `show-travel` | `showTravel` | `"true" \| "false"` | `true` |
 | `show-retractions` | `showRetractions` | `"true" \| "false"` | `false` |
 | `scrub` | `scrub` | integer | — (all) |
 | `layer-range` | `layerRange` | `"start,end"` / `[number, number]` | — (all) |
+| `hidden-feature-roles` | `hiddenFeatureRoles` | `"6,7"` / `number[]` — hide roles (Skirt, Brim…) | — |
 | — | `source` | `Uint8Array \| ArrayBuffer \| File` | `null` |
 | — | `colorMode` | `ColorMode` | — |
 | — | `theme` | `Theme` | — |
+| — | `tube` | `TubeOptions` — **construction-time** | — |
 | — | `buildVolume` | `BuildVolumeDef \| MachineGeometry` | — |
 | — | `progress` | `ProgressObservation \| null` | `null` |
 | — | `createWorker` | `() => WorkerLike` | batteries default |
 
 > `source` is a **property only** (never a URL attribute) — the element does not fetch.
+> `colorMode`, `theme`, `tube`, and `buildVolume` are **property-only** because objects can't be HTML
+> attributes — set them as JS properties. `hidden-feature-roles` gates on `capabilities.featureRoles`
+> (declarative form of `controls.setFeatureRoleVisible`). This is a ~24-option surface; the rest of
+> the declarative props (`qualityMode`, `view`, `cameraState`, `frameContent`, `scrubTime`,
+> `showWipe`, `showVolumeCage`, `interactionQuality`, `parseOptions`, `rendererOptions`, `layerRange`)
+> are set the same way.
 
 ### DOM events (`CustomEvent`, kebab-case `detail`)
 
-`ready` · `parse-error` · `parse-cancelled` · `parse-progress` · `build-complete` · `disclosure` ·
-`quality-fallback` · `progress-presentation-changed` · `machine-geometry-discovered` ·
-`machine-geometry-mismatch` · `error`.
+`ready` · `camerachange` · `parse-error` · `parse-cancelled` · `parse-progress` · `stage` ·
+`build-complete` · `disclosure` · `quality-fallback` · `progress-presentation-changed` ·
+`machine-geometry-discovered` · `machine-geometry-mismatch` · `error`.
+
+A few event `detail`s are DOM-wrapped, an accepted custom-element idiom: `disclosure` detail is
+`{ text }`, `machine-geometry-discovered` is `{ machine }`, and `machine-geometry-mismatch` is
+`{ message }`.
 
 The underlying handle is also exposed as instance members (`state`, `controls`, `raw`, `onEvent`,
-`parse`, `observeProgress`, `tickProgress`, `clearProgress`) for advanced use — the same neutral
-controller surface the other adapters expose.
+`parse`, `observeProgress`, `tickProgress`, `clearProgress`, `capture`) for advanced use — the same
+neutral controller surface the other adapters expose. `controls` reaches the imperative extras —
+`getRenderStats()` (render diagnostics), `pickSegment(ndcX, ndcY, threshold?)` (source-mapping /
+picking), and `isColorModeAvailable(mode)`; `capture(opts?)` (image `Blob`) is both a top-level
+method and `controls.capture`. The handle `state` carries capability-aware UI data
+(`availableColorModes`, `hasRetractions`, `hasColorChanges`).
+
+## Model viewing (Prepare side)
+
+The `/model/define` entry registers `<gcode-model-viewer>` — the **Prepare**-side counterpart to
+`<gcode-preview>` (the tag deliberately avoids the reserved `<model-viewer>`). Where `<gcode-preview>`
+draws the toolpath (how a print runs), `<gcode-model-viewer>` draws the **source model** (an `.stl` /
+`.3mf` mesh) — the object before slicing.
+
+```html
+<script type="module">
+  import '@chestnutlabs/gcode-preview-element/model/define'; // registers <gcode-model-viewer>
+
+  const el = document.querySelector('gcode-model-viewer');
+  el.addEventListener('ready', (e) => console.log(e.detail.objectCount, e.detail.materials));
+  el.source = { kind: '3mf', bytes }; // rich options are properties; primitives are attributes
+</script>
+
+<gcode-model-viewer background="transparent" style="width: 100%; height: 70vh"></gcode-model-viewer>
+```
+
+The `ready` event carries the honest material-colour tier: `e.detail.materials` is `'known'` /
+`'approximated'` when the file declared colours the render used, and `'unavailable'` when it declared
+none (a neutral default, never faked). The same attribute/property split as `<gcode-preview>` applies —
+rich options (`.source`, `.cameraState`, `.renderScope`, …) are properties; primitives (`view`,
+`background`, `camera-mode`) are attributes. See
+[`docs/manual/adapters.md`](../../docs/manual/adapters.md) "Two viewers: Preview and Prepare" for the
+cross-adapter tour, and `tools/example-webcomponent/model.html` for a runnable minimal page.
+
+## Examples
+
+`tools/example-webcomponent` in the repository is a framework-free Vite app with two tiers, both
+driving this published element (no raw renderer or parser imports):
+
+- **`minimal.html`** — the smallest real integration: import `/define` to register `<gcode-preview>`,
+  set the `source` property, listen for `ready`; the layer slider drives the `layer-range` attribute.
+  Shows the attribute/property split in ~40 lines.
+- **`showcase.html`** — the full surface in vanilla JS: objects (`source`, `colorMode`,
+  `hiddenFeatureRoles`) set as properties, primitives (`layer-range`, `view`) as attributes;
+  capability-gated color modes; `getRenderStats()`/`pickSegment()` diagnostics via `element.controls`.
+
+Run it with `npm install --prefix tools/example-webcomponent && npm run dev --prefix
+tools/example-webcomponent` (port 5204).
 
 ## Workers
 

package/dist/gcode-preview-element.d.ts

@@ -34,6 +34,8 @@ export declare class GcodePreviewElement extends HTMLElement {
     private _createWorker;
     private _rendererOptions;
     private _cameraState;
+    /** Which roles the `hidden-feature-roles` attribute last hid, for prev→next diffing (DD-031 G3). */
+    private prevHiddenRoles;
     get source(): GcodePreviewSource;
     set source(v: GcodePreviewSource);
     get parseOptions(): WireParseOptions | undefined;
@@ -52,6 +54,17 @@ export declare class GcodePreviewElement extends HTMLElement {
     set createWorker(v: (() => WorkerLike) | undefined);
     get rendererOptions(): ElementRendererOptions | undefined;
     set rendererOptions(v: ElementRendererOptions | undefined);
+    /**
+     * DD-014 D5 renderer selection (DD-031 E1): reflected property accessor over the `renderer`
+     * attribute. Construction-time like every adapter — read once at connect; changing it after the
+     * element is connected has no effect (mode switching post-mount is out of scope), it just keeps the
+     * attribute and property in sync so the value is readable/consistent.
+     */
+    get renderer(): string | null;
+    set renderer(v: string | null);
+    /** 2D only: preceding "ghost" layers (DD-031 E1). Construction-time; reflected accessor over the attribute. */
+    get adjacentLayers(): number | null;
+    set adjacentLayers(v: number | null);
     get quality(): string | null;
     set quality(v: string | null);
     get qualityMode(): string | null;
@@ -92,6 +105,13 @@ export declare class GcodePreviewElement extends HTMLElement {
     set scrubTime(v: number | null);
     get layerRange(): [number, number] | null;
     set layerRange(v: [number, number] | null);
+    /**
+     * DD-031 G3: feature roles to hide, as a comma-separated numeric list (`hidden-feature-roles="6,7"`
+     * for Skirt+Brim). Declarative form of `controls.setFeatureRoleVisible`; gate on
+     * `capabilities.featureRoles`. Import `FeatureRole` from `@chestnutlabs/toolpath-core` for the values.
+     */
+    get hiddenFeatureRoles(): number[];
+    set hiddenFeatureRoles(v: number[] | null);
     get state(): GcodePreviewState;
     get controls(): GcodePreviewControls;
     get raw(): PreviewController['raw'];
@@ -107,6 +127,8 @@ export declare class GcodePreviewElement extends HTMLElement {
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
     /** Apply the runtime-only controls (the construction options were set at controller creation). */
     private applyRuntimeState;
+    /** Feature-role visibility (DD-031 G3): diff prev→next so we only toggle roles this attribute owns. */
+    private applyHiddenRoles;
     private applyProgress;
     private reflect;
     private requireController;

package/dist/gcode-preview-element.d.ts.map

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

package/dist/gcode-preview-element.js

@@ -26,7 +26,8 @@ const OBSERVED = [
     'show-volume-cage',
     'scrub',
     'scrub-time',
-    'layer-range'
+    'layer-range',
+    'hidden-feature-roles'
 ];
 /** The default tag name (DD-009 §4.5). */
 export const DEFAULT_TAG = 'gcode-preview';
@@ -47,6 +48,8 @@ export class GcodePreviewElement extends HTMLElement {
     _createWorker;
     _rendererOptions;
     _cameraState = null;
+    /** Which roles the `hidden-feature-roles` attribute last hid, for prev→next diffing (DD-031 G3). */
+    prevHiddenRoles = [];
     // ---- rich-option property accessors ----
     get source() {
         return this._source;
@@ -111,6 +114,26 @@ export class GcodePreviewElement extends HTMLElement {
     set rendererOptions(v) {
         this._rendererOptions = v; // construction-only injectables
     }
+    /**
+     * DD-014 D5 renderer selection (DD-031 E1): reflected property accessor over the `renderer`
+     * attribute. Construction-time like every adapter — read once at connect; changing it after the
+     * element is connected has no effect (mode switching post-mount is out of scope), it just keeps the
+     * attribute and property in sync so the value is readable/consistent.
+     */
+    get renderer() {
+        return this.getAttribute('renderer');
+    }
+    set renderer(v) {
+        this.reflect('renderer', v);
+    }
+    /** 2D only: preceding "ghost" layers (DD-031 E1). Construction-time; reflected accessor over the attribute. */
+    get adjacentLayers() {
+        const a = this.getAttribute('adjacent-layers');
+        return a === null ? null : Number(a);
+    }
+    set adjacentLayers(v) {
+        this.reflect('adjacent-layers', v);
+    }
     // ---- scalar-option accessors (reflect to attributes: one source of truth) ----
     get quality() {
         return this.getAttribute('quality');
@@ -216,6 +239,17 @@ export class GcodePreviewElement extends HTMLElement {
     set layerRange(v) {
         this.reflect('layer-range', v === null ? null : `${v[0]},${v[1]}`);
     }
+    /**
+     * DD-031 G3: feature roles to hide, as a comma-separated numeric list (`hidden-feature-roles="6,7"`
+     * for Skirt+Brim). Declarative form of `controls.setFeatureRoleVisible`; gate on
+     * `capabilities.featureRoles`. Import `FeatureRole` from `@chestnutlabs/toolpath-core` for the values.
+     */
+    get hiddenFeatureRoles() {
+        return parseRoleList(this.getAttribute('hidden-feature-roles'));
+    }
+    set hiddenFeatureRoles(v) {
+        this.reflect('hidden-feature-roles', v === null || v.length === 0 ? null : v.join(','));
+    }
     // ---- handle-parity passthrough (advanced/parity surface; DOM events are the ergonomic one) ----
     get state() {
         return this.requireController().getState();
@@ -351,6 +385,9 @@ export class GcodePreviewElement extends HTMLElement {
                     c.setLayerRange(r[0], r[1]);
                 break;
             }
+            case 'hidden-feature-roles':
+                this.applyHiddenRoles(parseRoleList(value));
+                break;
             default:
                 break;
         }
@@ -370,8 +407,24 @@ export class GcodePreviewElement extends HTMLElement {
             c.setLayerRange(r[0], r[1]);
         c.setScrubPosition(this.scrub);
         c.setScrubTime(this.scrubTime);
+        this.applyHiddenRoles(this.hiddenFeatureRoles);
         this.applyProgress();
     }
+    /** Feature-role visibility (DD-031 G3): diff prev→next so we only toggle roles this attribute owns. */
+    applyHiddenRoles(next) {
+        if (this.controller === null)
+            return;
+        const c = this.controller.controls;
+        for (const role of this.prevHiddenRoles) {
+            if (!next.includes(role))
+                c.setFeatureRoleVisible(role, true);
+        }
+        for (const role of next) {
+            if (!this.prevHiddenRoles.includes(role))
+                c.setFeatureRoleVisible(role, false);
+        }
+        this.prevHiddenRoles = [...next];
+    }
     applyProgress() {
         if (this.controller === null)
             return;
@@ -455,6 +508,15 @@ function parseLayerRange(value) {
         return null;
     return [parts[0], parts[1]];
 }
+/** Parse `hidden-feature-roles="6,7"` into a numeric role list; ignores blanks/NaN (DD-031 G3). */
+function parseRoleList(value) {
+    if (value === null || value.trim() === '')
+        return [];
+    return value
+        .split(',')
+        .map((s) => Number(s.trim()))
+        .filter((n) => Number.isFinite(n));
+}
 /**
  * Register `<gcode-preview>` (idempotent — safe to call repeatedly and from multiple
  * bundles). Kept as a function (not a module side effect) so the package stays

package/dist/index.d.ts

@@ -5,5 +5,5 @@
  * `@chestnutlabs/gcode-preview-element/define` to auto-register.
  */
 export { GcodePreviewElement, defineGcodePreview, DEFAULT_TAG, type GcodePreviewSource, type ElementRendererOptions } from './gcode-preview-element.js';
-export type { GcodePreviewControls, GcodePreviewState, ParseOutcome, PreviewEvent } from '@chestnutlabs/gcode-preview-core';
+export type { GcodePreviewControls, GcodePreviewState, ParseOutcome, PreviewEvent, PreviewRenderer, RendererMode } from '@chestnutlabs/gcode-preview-core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AAGpC,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACb,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AAIpC,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACb,MAAM,kCAAkC,CAAC"}

package/dist/model/define.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/model/define.d.ts.map

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

package/dist/model/define.js

@@ -0,0 +1,7 @@
+/**
+ * Side-effectful registration entry: `import '@chestnutlabs/gcode-preview-element/model/define'`
+ * auto-registers `<gcode-model-viewer>`. Kept as a separate subpath so `.../model` stays
+ * side-effect-free.
+ */
+import { defineGcodeModelViewer } from './index.js';
+defineGcodeModelViewer();

package/dist/model/gcode-model-viewer-element.d.ts

@@ -0,0 +1,68 @@
+/**
+ * <gcode-model-viewer> — the framework-free Web Component for interactive source-model viewing
+ * (STL / 3MF), the Prepare-side counterpart to <gcode-preview> (DD-031). A SHELL over
+ * `createModelPreviewController`, exactly like the Vue/React/Svelte model adapters: attributes and
+ * properties map to controller options / `controls.*` calls, and controller events are re-emitted as
+ * DOM `CustomEvent`s. The handle is also exposed as instance members (`state`/`controls`/`raw`/`onEvent`/
+ * `setSource`/`capture`) so the shared model behavioral suite runs against it identically.
+ *
+ * The tag is `gcode-model-viewer` (not the reserved `model-viewer`). No framework peer dependency.
+ */
+import { type ModelBackground, type ModelLimits, type ModelLoader, type ModelPreviewControls, type ModelPreviewState, type ModelSourceInput, type ModelViewer, type ModelViewerEvent, type RenderScope } from '@chestnutlabs/gcode-model-renderer';
+import type { CameraState, CaptureOptions, GLRendererLike, InteractiveStageOptions, RenderTargetCanvas } from '@chestnutlabs/gcode-renderer-three';
+/** The default tag name for the model viewer. */
+export declare const DEFAULT_MODEL_TAG = "gcode-model-viewer";
+export declare class GcodeModelViewerElement extends HTMLElement {
+    static get observedAttributes(): string[];
+    private controller;
+    private canvasEl;
+    private _source;
+    private _cameraState;
+    private _background;
+    private _renderScope;
+    private _limits;
+    private _filamentPalette;
+    private _loaders;
+    private _createRenderer;
+    private _createControls;
+    get source(): ModelSourceInput | null;
+    set source(v: ModelSourceInput | null);
+    get cameraState(): CameraState | null;
+    set cameraState(v: CameraState | null);
+    get background(): ModelBackground | undefined;
+    set background(v: ModelBackground | undefined);
+    get renderScope(): RenderScope | null;
+    set renderScope(v: RenderScope | null);
+    get limits(): ModelLimits | undefined;
+    set limits(v: ModelLimits | undefined);
+    get filamentPalette(): readonly (string | undefined)[] | undefined;
+    set filamentPalette(v: readonly (string | undefined)[] | undefined);
+    get loaders(): readonly ModelLoader[] | undefined;
+    set loaders(v: readonly ModelLoader[] | undefined);
+    get createRenderer(): ((canvas: RenderTargetCanvas) => GLRendererLike) | undefined;
+    set createRenderer(v: ((canvas: RenderTargetCanvas) => GLRendererLike) | undefined);
+    get createControls(): NonNullable<InteractiveStageOptions['createControls']> | undefined;
+    set createControls(v: NonNullable<InteractiveStageOptions['createControls']> | undefined);
+    get view(): string | null;
+    set view(v: string | null);
+    get interactionQuality(): string | null;
+    set interactionQuality(v: string | null);
+    get cameraMode(): string | null;
+    set cameraMode(v: string | null);
+    get state(): ModelPreviewState;
+    get controls(): ModelPreviewControls;
+    get raw(): {
+        viewer: () => ModelViewer | null;
+    };
+    setSource(input: ModelSourceInput): Promise<import('@chestnutlabs/gcode-model-renderer').ModelReadyInfo>;
+    capture(opts?: CaptureOptions): Promise<Blob>;
+    onEvent(cb: (e: ModelViewerEvent) => void): () => void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    private reemit;
+    private requireController;
+}
+/** Register the element (idempotent). Import `.../model/define` for auto-registration. */
+export declare function defineGcodeModelViewer(tag?: string): void;
+//# sourceMappingURL=gcode-model-viewer-element.d.ts.map

package/dist/model/gcode-model-viewer-element.d.ts.map

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

package/dist/model/gcode-model-viewer-element.js

@@ -0,0 +1,249 @@
+/**
+ * <gcode-model-viewer> — the framework-free Web Component for interactive source-model viewing
+ * (STL / 3MF), the Prepare-side counterpart to <gcode-preview> (DD-031). A SHELL over
+ * `createModelPreviewController`, exactly like the Vue/React/Svelte model adapters: attributes and
+ * properties map to controller options / `controls.*` calls, and controller events are re-emitted as
+ * DOM `CustomEvent`s. The handle is also exposed as instance members (`state`/`controls`/`raw`/`onEvent`/
+ * `setSource`/`capture`) so the shared model behavioral suite runs against it identically.
+ *
+ * The tag is `gcode-model-viewer` (not the reserved `model-viewer`). No framework peer dependency.
+ */
+import { createModelPreviewController } from '@chestnutlabs/gcode-model-renderer';
+/** Observed scalar attributes; rich options (source, cameraState, palettes, loaders, injectables) are property-only. */
+const OBSERVED = ['view', 'background', 'interaction-quality', 'camera-mode'];
+/** The default tag name for the model viewer. */
+export const DEFAULT_MODEL_TAG = 'gcode-model-viewer';
+export class GcodeModelViewerElement extends HTMLElement {
+    static get observedAttributes() {
+        return [...OBSERVED];
+    }
+    controller = null;
+    canvasEl = null;
+    // Rich options — objects/functions can't be attributes, so they are property-only.
+    _source = null;
+    _cameraState = null;
+    _background;
+    _renderScope = null;
+    _limits;
+    _filamentPalette;
+    _loaders;
+    _createRenderer;
+    _createControls;
+    // ---- rich-option property accessors ----
+    get source() {
+        return this._source;
+    }
+    set source(v) {
+        this._source = v;
+        if (v !== null && this.controller !== null)
+            void this.controller.controls.setSource(v);
+    }
+    get cameraState() {
+        return this._cameraState;
+    }
+    set cameraState(v) {
+        this._cameraState = v;
+        if (v !== null)
+            this.controller?.controls.setCameraState(v);
+    }
+    get background() {
+        return this._background;
+    }
+    set background(v) {
+        this._background = v;
+        if (v !== undefined)
+            this.controller?.controls.setBackground(v);
+    }
+    get renderScope() {
+        return this._renderScope;
+    }
+    set renderScope(v) {
+        this._renderScope = v;
+        this.controller?.controls.setRenderScope(v);
+    }
+    get limits() {
+        return this._limits;
+    }
+    set limits(v) {
+        this._limits = v; // construction-time only
+    }
+    get filamentPalette() {
+        return this._filamentPalette;
+    }
+    set filamentPalette(v) {
+        this._filamentPalette = v; // construction-time only
+    }
+    get loaders() {
+        return this._loaders;
+    }
+    set loaders(v) {
+        this._loaders = v; // construction-time only
+    }
+    get createRenderer() {
+        return this._createRenderer;
+    }
+    set createRenderer(v) {
+        this._createRenderer = v; // construction-time only
+    }
+    get createControls() {
+        return this._createControls;
+    }
+    set createControls(v) {
+        this._createControls = v; // construction-time only
+    }
+    // ---- scalar attribute accessors ----
+    get view() {
+        return this.getAttribute('view');
+    }
+    set view(v) {
+        if (v === null)
+            this.removeAttribute('view');
+        else
+            this.setAttribute('view', v);
+    }
+    get interactionQuality() {
+        return this.getAttribute('interaction-quality');
+    }
+    set interactionQuality(v) {
+        if (v === null)
+            this.removeAttribute('interaction-quality');
+        else
+            this.setAttribute('interaction-quality', v);
+    }
+    get cameraMode() {
+        return this.getAttribute('camera-mode');
+    }
+    set cameraMode(v) {
+        if (v === null)
+            this.removeAttribute('camera-mode');
+        else
+            this.setAttribute('camera-mode', v);
+    }
+    // ---- handle passthrough (parity with the other adapters) ----
+    get state() {
+        return this.requireController().getState();
+    }
+    get controls() {
+        return this.requireController().controls;
+    }
+    get raw() {
+        return this.requireController().raw;
+    }
+    setSource(input) {
+        return this.requireController().controls.setSource(input);
+    }
+    capture(opts) {
+        return this.requireController().controls.capture(opts);
+    }
+    onEvent(cb) {
+        return this.requireController().onEvent(cb);
+    }
+    // ---- lifecycle ----
+    connectedCallback() {
+        if (this.controller !== null)
+            return;
+        const root = this.shadowRoot ?? this.attachShadow({ mode: 'open' });
+        root.replaceChildren();
+        const style = document.createElement('style');
+        style.textContent = ':host{display:block;width:100%;height:100%}canvas{display:block;width:100%;height:100%}';
+        const canvas = document.createElement('canvas');
+        canvas.setAttribute('aria-label', '3D source-model preview');
+        canvas.setAttribute('tabindex', '0');
+        root.append(style, canvas);
+        this.canvasEl = canvas;
+        const bg = this._background ?? this.getAttribute('background') ?? undefined;
+        this.controller = createModelPreviewController({
+            ...(this._loaders ? { loaders: this._loaders } : {}),
+            ...(bg !== undefined ? { background: bg } : {}),
+            ...(this.getAttribute('interaction-quality')
+                ? { interactionQuality: this.getAttribute('interaction-quality') }
+                : {}),
+            ...(this.getAttribute('camera-mode') ? { cameraMode: this.getAttribute('camera-mode') } : {}),
+            ...(this._limits ? { limits: this._limits } : {}),
+            ...(this._filamentPalette ? { filamentPalette: this._filamentPalette } : {}),
+            ...(this._renderScope ? { renderScope: this._renderScope } : {}),
+            ...(this._createRenderer ? { createRenderer: this._createRenderer } : {}),
+            ...(this._createControls ? { createControls: this._createControls } : {}),
+            onProgress: (p) => this.dispatchEvent(new CustomEvent('progress', { detail: p }))
+        });
+        this.controller.onEvent((e) => this.reemit(e));
+        this.controller.bindCanvas(canvas);
+        // Apply runtime-only state that isn't a construction option.
+        const view = this.getAttribute('view');
+        if (view !== null)
+            this.controller.controls.setView(view);
+        if (this._cameraState !== null)
+            this.controller.controls.setCameraState(this._cameraState);
+        if (this._source !== null)
+            void this.controller.controls.setSource(this._source);
+    }
+    disconnectedCallback() {
+        this.controller?.dispose();
+        this.controller = null;
+        this.canvasEl = null;
+        this.shadowRoot?.replaceChildren();
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (this.controller === null)
+            return;
+        const c = this.controller.controls;
+        switch (name) {
+            case 'view':
+                if (value !== null)
+                    c.setView(value);
+                break;
+            case 'background':
+                if (value !== null)
+                    c.setBackground(value);
+                break;
+            case 'interaction-quality':
+                if (value !== null)
+                    c.setInteractionQuality(value);
+                break;
+            case 'camera-mode':
+                // Construction-time only (projection switching post-mount is out of scope); no-op at runtime.
+                break;
+            default:
+                break;
+        }
+    }
+    reemit(e) {
+        const emit = (type, detail) => {
+            this.dispatchEvent(new CustomEvent(type, { detail }));
+        };
+        switch (e.type) {
+            case 'ready':
+                emit('ready', e.info);
+                break;
+            case 'camera-changed':
+                emit('camerachange', e.state);
+                break;
+            case 'error':
+                emit('error', { code: e.code, message: e.message });
+                break;
+            case 'renderer-unsupported':
+                emit('renderer-unsupported', { feature: e.feature, message: e.message });
+                break;
+            case 'context-lost':
+                emit('context-lost');
+                break;
+            case 'context-restored':
+                emit('context-restored');
+                break;
+            default:
+                break;
+        }
+    }
+    requireController() {
+        if (this.controller === null) {
+            throw new Error('gcode-model-viewer: not connected to the DOM yet (no controller)');
+        }
+        return this.controller;
+    }
+}
+/** Register the element (idempotent). Import `.../model/define` for auto-registration. */
+export function defineGcodeModelViewer(tag = DEFAULT_MODEL_TAG) {
+    if (customElements.get(tag) === undefined) {
+        customElements.define(tag, GcodeModelViewerElement);
+    }
+}

package/dist/model/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @chestnutlabs/gcode-preview-element/model — the framework-free `<gcode-model-viewer>` Web Component
+ * for interactive source-model viewing (STL / 3MF), the Prepare-side counterpart to `<gcode-preview>`
+ * (DD-031). Registration is a function (`defineGcodeModelViewer`) so this entry stays side-effect-free;
+ * import `.../model/define` to auto-register. A thin shell over `createModelPreviewController`.
+ */
+export { GcodeModelViewerElement, defineGcodeModelViewer, DEFAULT_MODEL_TAG } from './gcode-model-viewer-element.js';
+export type { ModelPreviewControls, ModelPreviewState, ModelViewer, ModelViewerEvent, ModelReadyInfo, ModelSourceInput } from '@chestnutlabs/gcode-model-renderer';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/model/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGrH,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EACjB,MAAM,oCAAoC,CAAC"}

package/dist/model/index.js

@@ -0,0 +1,7 @@
+/**
+ * @chestnutlabs/gcode-preview-element/model — the framework-free `<gcode-model-viewer>` Web Component
+ * for interactive source-model viewing (STL / 3MF), the Prepare-side counterpart to `<gcode-preview>`
+ * (DD-031). Registration is a function (`defineGcodeModelViewer`) so this entry stays side-effect-free;
+ * import `.../model/define` to auto-register. A thin shell over `createModelPreviewController`.
+ */
+export { GcodeModelViewerElement, defineGcodeModelViewer, DEFAULT_MODEL_TAG } from './gcode-model-viewer-element.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chestnutlabs/gcode-preview-element",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Framework-free <gcode-preview> Web Component for the Chestnut Labs G-code viewer (DD-007 D1 / DD-009 D5): a custom element bridging @chestnutlabs/gcode-preview-core, no framework peer dependency.",
   "keywords": [
     "gcode",
@@ -38,6 +38,14 @@
     "./define": {
       "types": "./dist/define.d.ts",
       "import": "./dist/define.js"
+    },
+    "./model": {
+      "types": "./dist/model/index.d.ts",
+      "import": "./dist/model/index.js"
+    },
+    "./model/define": {
+      "types": "./dist/model/define.d.ts",
+      "import": "./dist/model/define.js"
     }
   },
   "files": [
@@ -52,9 +60,10 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@chestnutlabs/gcode-parser": "0.18.0",
-    "@chestnutlabs/gcode-preview-core": "0.18.0",
-    "@chestnutlabs/gcode-renderer-three": "0.18.0",
-    "@chestnutlabs/toolpath-core": "0.18.0"
+    "@chestnutlabs/gcode-model-renderer": "0.20.0",
+    "@chestnutlabs/gcode-parser": "0.20.0",
+    "@chestnutlabs/gcode-preview-core": "0.20.0",
+    "@chestnutlabs/gcode-renderer-three": "0.20.0",
+    "@chestnutlabs/toolpath-core": "0.20.0"
   }
 }