three-slicer 0.1.5 → 0.1.7

package/types/settings.d.ts

@@ -1,6 +1,7 @@
 // three-slicer/settings
 import type { SlicerSettings, SettingKey, Point } from './settings-keys.d.ts'
-export type { SlicerSettings, SettingKey, Point }
+import type { PrinterEntry } from './data/printers.json.d.ts'
+export type { SlicerSettings, SettingKey, Point, PrinterEntry }
 
 /** The config-schema default value (undefined for unknown keys) */
 export function schemaDefault(key: string): unknown
@@ -16,7 +17,7 @@ export function settingScalar(settings: SlicerSettings | null | undefined, key:
  * ponytail: 53 returned keys, so Record instead of listing each — kernel params are passed straight to slice(),
  * not an API consumers read field by field. Expand it when field access is actually needed.
  */
-export function deriveKernelParams(settings: SlicerSettings | null | undefined): Record<string, unknown>
+export function deriveKernelParams(settings: SlicerSettings | null | undefined, opts?: { plate?: number }): Record<string, unknown>
 
 /**
  * A 3mf project's raw `Metadata/project_settings.config` -> a settings map this API accepts.
@@ -30,6 +31,93 @@ export function normalizeProjectSettings(raw: Record<string, unknown> | null | u
   skipped: string[]
 }
 
+/**
+ * The inverse, for WRITING a 3mf's `Metadata/project_settings.config`: every value back to the string shape
+ * upstream serializes (a bool as "1"/"0", a point as "XxY", a points group as "X1xY1,X2xY2"), so another slicer
+ * reads what it expects. Keys the config schema does not define are dropped.
+ */
+export function serializeProjectSettings(settings: SlicerSettings | null | undefined): Record<string, string | string[]>
+
+// ---- Preset files -----------------------------------------------------------
+// The `.json` OrcaSlicer's "Config files" dialog imports and its "Export preset" writes. One file, one preset,
+// one type. The value encoding is the same all-strings shape `project_settings.config` uses — same writer
+// upstream (ConfigBase::save_to_json) — so these reuse the coercion above rather than repeating it.
+
+/** Upstream's own `type` field: machine = printer, process = print settings, filament = material. */
+export type PresetType = 'machine' | 'process' | 'filament'
+
+/** The option keys that belong in a preset of this type, from upstream's `Preset::printer_options()` and friends. */
+export function presetOptionKeys(type: PresetType): string[]
+
+export interface WritePresetOptions {
+  /** Defaults to `'machine'`. */
+  type?: PresetType
+  /** Goes in the file's `name` field, and is what an importer shows. Defaults to `'Custom'`. */
+  name?: string
+  /**
+   * `true` (the default) writes every option of that type, filling unset ones from the config-schema default, so
+   * the file stands on its own. `false` writes only what the settings map holds — a diff-shaped file, readable
+   * only next to whatever it was derived from.
+   */
+  complete?: boolean
+  version?: string
+}
+
+/**
+ * A settings map -> the object a preset `.json` holds. Written **without `inherits`**: upstream saves a derived
+ * preset as the diff against its parent, which only means something beside the vendor database it came from.
+ */
+export function writePresetFile(settings: SlicerSettings | null | undefined, options?: WritePresetOptions): Record<string, unknown>
+
+/** The same, already stringified — what an export actually writes to disk. */
+export function presetFileText(settings: SlicerSettings | null | undefined, options?: WritePresetOptions): string
+
+export interface ReadPresetResult {
+  /** The parent's values with the file's own on top, since the file is the diff. */
+  settings: SlicerSettings
+  type: PresetType
+  name: string
+  /** The parent named by the file, or `null`. */
+  inherits: string | null
+  /**
+   * Set to the parent's name when it was named but could not be resolved. The file's own values are still
+   * applied — a vendor preset without its parent still carries most of itself, and the caller decides whether
+   * that is good enough. Watch for it: the Bambu X1C machine file never states its own bed, so read alone it
+   * yields a printer with no `printable_area` at all.
+   */
+  missingParent: string | null
+  applied: number
+  skipped: string[]
+}
+
+/**
+ * A parsed preset `.json` -> a settings map. Pass `resolveParent` to follow `inherits`; `printerSettings` covers
+ * the machine case for the keys this package carries.
+ */
+export function readPresetFile(raw: Record<string, unknown> | null | undefined,
+  options?: { resolveParent?: (name: string, type: PresetType) => SlicerSettings | null }): ReadPresetResult
+
+// ---- Printer profiles -------------------------------------------------------
+// printers.json is column-oriented; these hide that layout so no consumer decodes it by hand.
+
+/**
+ * Every option key a printer profile can set. Delete these from the settings map before applying a different
+ * printer — a profile only carries the keys it sets, so without the clear the previous machine's values survive.
+ */
+export const printerKeys: string[]
+
+/** Vendor -> profile name -> entry, straight from the data. For building a picker. */
+export const printersByVendor: Record<string, Record<string, PrinterEntry>>
+
+/** The settings a printer profile applies, ready to merge. `null` when the name is unknown. */
+export function printerSettings(profileName: string): SlicerSettings | null
+
+/** The vendor's recommended process preset for that printer, or `''` when the profile names none. */
+export function printerDefaultPreset(profileName: string): string
+
+/** The schema keys the kernel's machine limits are read from — for UI that shows which ones are in play. */
+export const machineLimitKeys: string[]
+
 // ---- Lazily loaded presets --------------------------------------------------
 // Both facades hide the column layout of the artifact they wrap; the promise is created once and reused.
 

package/types/viewer.d.ts

@@ -21,8 +21,32 @@ export interface ViewportProps {
   /**
    * Per-panel visibility. Every panel is visible unless its key is explicitly `false`, so a host only opts out —
    * and a panel added in a later version does not disappear for hosts that listed the ones they wanted.
+   *
+   * A {@link LockablePanel} also accepts `'readonly'`: the panel is drawn but nothing inside it can be clicked,
+   * typed into or tabbed to — including any node the host passed into it. That is the shape a host wants when it
+   * presets the printer, process and filament itself and does not want the user changing them.
+   *
+   * Note what it locks: the UI path, not the value. `settings` is still the host's own prop, and other paths
+   * inside the viewer still write it — importing a 3mf project applies that project's settings either way.
    */
-  panels?: Partial<Record<ViewportPanel, boolean>>
+  panels?: Partial<Record<ViewportPanel, boolean>> & Partial<Record<LockablePanel, boolean | 'readonly'>>
+  /**
+   * Behaviour switches, following the same opt-out rule as {@link ViewportProps.panels}: everything is on unless
+   * its key is explicitly `false`. These are the things the component does *outside* its own box — take the page's
+   * keyboard, load the WASM kernel, write to the console — which a host embedding it in a larger app may already
+   * be doing itself. See {@link ViewportFeature}.
+   */
+  features?: Partial<Record<ViewportFeature, boolean>>
+  /**
+   * Intercepts every file the viewer would otherwise hand to the browser as a download — the 3mf project, the STL,
+   * and each plate's G-code. Return anything truthy to say it is handled and suppress the download; return nothing
+   * to let it proceed as well. This is the only way in: the save buttons live inside the component.
+   *
+   * ```jsx
+   * <Viewport onExport={(blob, filename) => { upload(blob, filename); return true }} />
+   * ```
+   */
+  onExport?: (file: Blob, filename: string) => boolean | void
   /**
    * G-code text to render instead of a slice result. Parsed into the same layer stream the kernel produces and
    * shown on the selected plate; the kernel is never started. While it is set, auto re-slice leaves that plate alone.
@@ -41,10 +65,42 @@ export interface ViewportProps {
   onSliced?: (result: { plate: number; stats: Record<string, unknown>; gcode: string }) => void
 }
 
+/**
+ * Behaviour keys accepted by {@link ViewportProps.features}. All default to enabled.
+ *
+ * - `shortcuts` — the keyboard bindings. They are installed on `window`, so while the viewer is mounted they fire
+ *   wherever focus is (except inside inputs) and `Ctrl+C` in particular preventDefaults. Turn them off when the
+ *   host page has its own.
+ * - `warmup` — loading the WASM kernel on mount, ahead of the first slice. Off, nothing is downloaded or compiled
+ *   until something actually slices — which for a `gcode`-only viewer is never.
+ * - `drop` — drag and drop onto the canvas.
+ * - `filePicker` — the file dialog, from every button that opens it.
+ * - `contextMenu` — the right-click menu. Note that the browser's own menu stays suppressed over the canvas either
+ *   way: OrbitControls preventDefaults `contextmenu` itself.
+ * - `logs` — console diagnostics, from the component and from the slice worker.
+ */
+export type ViewportFeature = 'shortcuts' | 'warmup' | 'drop' | 'filePicker' | 'contextMenu' | 'logs'
+
+/**
+ * The panels that accept `'readonly'` as well as `true`/`false` — the right column and the cards in it. Everything
+ * else takes a boolean only: locking the gizmo rail or the plate tabs is what `features` and `panels: false` are
+ * for, and pretending otherwise would mean a `'readonly'` that silently does nothing on half the keys.
+ *
+ * `sidebar: 'readonly'` locks the whole column in one go, so the per-card keys are for mixing — a locked printer
+ * card above a live object list, say.
+ */
+export type LockablePanel =
+  | 'sidebar' | 'printerCard' | 'filamentCard' | 'objectList' | 'towerCard'
+  | 'previewControls' | 'processCard' | 'sliceBar'
+
 /** Panel keys accepted by {@link ViewportProps.panels}. `sidebar: false` hides the whole right column at once. */
 export type ViewportPanel =
   | 'topBar' | 'gizmoRail' | 'objectToolbar' | 'paintPanel' | 'statsCard' | 'plateBar' | 'emptyHint' | 'status'
   | 'sidebar' | 'printerCard' | 'filamentCard' | 'objectList' | 'previewControls' | 'processCard' | 'sliceBar'
+  /** The over-the-bed warning, shown in Prepare when something leaves the printable area. */
+  | 'bedWarn'
+  /** The prime tower card. Only rendered anyway once a second filament exists. */
+  | 'towerCard'
 
 /** Value changes reported through {@link ViewportProps.onEvent}. Not fired for the initial values. */
 export type ViewportEvent =

package/types/worker.d.ts

@@ -1,3 +1,90 @@
 // three-slicer/worker — the slice worker script. Not a module you import, but the target of
 // `new Worker(new URL('three-slicer/worker', import.meta.url), { type: 'module' })`.
+//
+// The protocol below is the raw message contract. `createSlicerClient()` from `three-slicer/client` wraps it in
+// promises and is the easier way in; these types are here for hosts driving the worker directly, and because the
+// shape has traps that only a written-down contract makes visible — see the slice request and `erase`.
+import type { SliceResult } from '../engine/index.d.ts'
+
+/** Brush geometry shared by paint and erase: the hit facet, the hit point, the camera, the radius. */
+export interface BrushArgs {
+  facet: number
+  hx: number; hy: number; hz: number
+  cx: number; cy: number; cz: number
+  radius: number
+}
+
+/**
+ * Painting state, following OrcaSlicer's own `EnforcerBlockerType`: one enum serving two jobs.
+ * `1` is both the support ENFORCER and Extruder 1, `2` is both the BLOCKER and Extruder 2, `3..16` are
+ * Extruders 3 to 16. `0` (NONE) is deliberately not a value here — see the `erase` command.
+ */
+export type PaintState = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16
+
+/** Selection tools that are not the radius brush. All three take the mesh's own topology instead of a radius. */
+export type PaintTool = 'smart' | 'bucket' | 'triangle'
+
+export type SlicerRequest =
+  /** Load the kernel (and spawn the mt thread pool) ahead of the first slice. Reply: `warm`. */
+  | { cmd: 'warmup' }
+  /**
+   * Register a mesh for painting. `keepPaint` says this is the same model in a new place, so the marks carry
+   * over — the reply reports whether they actually did. Reply: `prepared`.
+   */
+  | { cmd: 'prepare'; stl: ArrayBuffer; keepPaint?: boolean }
+  /**
+   * Paint. With `state` it addresses any extruder; with `enforcer` it stays on the original boolean pair, where
+   * `false` means BLOCKER. `states` asks for those states' counts back. Reply: `painted`.
+   */
+  | (BrushArgs & { cmd: 'paint'; state?: PaintState; enforcer?: boolean; tool?: PaintTool
+                   angle?: number; cursor?: 'sphere' | 'circle'; states?: PaintState[] })
+  /**
+   * Return the brushed facets to the default extruder. Its OWN command rather than `{cmd:'paint', state:0}`:
+   * embind coerces a JS `false` to the int `0` == NONE, and the legacy blocker brush sends exactly that `false`,
+   * so admitting `0` on the state path would let a stray boolean erase silently. Reply: `painted`.
+   */
+  | (BrushArgs & { cmd: 'erase'; tool?: PaintTool; angle?: number; states?: PaintState[] })
+  /**
+   * Load painting out of a 3mf. REPLACES every mark (the kernel's deserialize resets first), so it belongs
+   * immediately after a `prepare` and nowhere else. Reply: `painted`, with `applied`.
+   */
+  | { cmd: 'importPaint'; facets: Int32Array | number[]; hex: string; states?: PaintState[] }
+  /** Every marked facet's split tree, in the CURRENT selector's numbering. Reply: `paintExport`. */
+  | { cmd: 'exportPaint' }
+  /** Wipe every state at once. Reply: `painted`, all zero. */
+  | { cmd: 'clear'; states?: PaintState[] }
+  /** The painted overlay triangles. `enf`/`blk` always; `states` adds those states. Reply: `overlay`. */
+  | { cmd: 'overlay'; states?: PaintState[] }
+  /**
+   * Slice — and note it carries **no `cmd`**: slicing is the worker's default action, and leaving the field off
+   * is what selects it. `params` must be a JSON **string**; the worker hands it straight to the kernel, which
+   * parses JSON text. (`createSlicer().slice()` on the direct handle also accepts an object and stringifies it.)
+   * Replies: `progress` and `layer` while it runs, then `done` — or `error`.
+   */
+  | { stl: ArrayBuffer; params: string }
+
+export type SlicerResponse =
+  | { type: 'warm' }
+  | { type: 'prepared'; facets: number; kept: boolean }
+  /**
+   * `enf`/`blk` are the counts for states 1 and 2 and are always present, so a listener predating the
+   * state-addressed protocol keeps working. `counts` appears only when the request named `states`.
+   */
+  | { type: 'painted'; enf: number; blk: number; counts?: Record<number, number>; applied?: number }
+  /** `supported: false` from a kernel built before the export binding existed — it does not throw. */
+  | { type: 'paintExport'; supported: boolean; facets: number[]; hex: string }
+  | { type: 'overlay'; enf: Float32Array; blk: Float32Array; overlays?: Record<number, Float32Array> }
+  /**
+   * Sent once, unprompted, by the multithreaded kernel only: the address of the support-progress counter and of
+   * the cancel flag, inside a SharedArrayBuffer. Writing 1 to the cancel flag stops a slice the worker is
+   * currently blocked inside. A single-threaded kernel has no shared buffer and never sends this.
+   */
+  | { type: 'supsab'; buf: SharedArrayBuffer; ptr: number; cancelPtr: number }
+  | { type: 'progress'; done: number; total: number }
+  /** One sliced layer, its typed arrays transferred rather than copied. */
+  | { type: 'layer'; z: number; idx: number; gcode: string; paths: Float32Array; widths: Float32Array }
+  /** `result.stats.streamed` says whether the G-code came through `layer` messages or is on the result. */
+  | { type: 'done'; result: SliceResult }
+  | { type: 'error'; error: string }
+
 export {}

package/viewer/README.md

@@ -2,23 +2,42 @@
 
 3D slicer viewer as a React component: three.js viewport (orbit/transform gizmos), model import (STL/OBJ/3MF/AMF/PLY + pluggable formats such as STEP, multi-object, drag & drop), Web Worker slicing via `three-slicer`, support and material painting, per-extruder filament presets, multi-plate, and a GPU-instanced volumetric toolpath preview ported from OrcaSlicer's libvgcode (millions of segments in a single draw path, per-feature colors, layer range slider, G-code export).
 
+![The Prepare tab — drag-and-drop viewport with the printer, filament and process cards in the right sidebar](../../slice-sidebar.png)
+
 ```bash
-npm i three-slicer/viewer react react-dom three@^0.160.0
+npm i three-slicer react react-dom three     # the three are optional peers; the viewer needs all of them
 ```
 
 ```jsx
 import { useState } from 'react'
 import Viewport from 'three-slicer/viewer'
-import 'three-slicer/viewer/styles.css'
 
 function App() {
   const [settings, setSettings] = useState({})   // OrcaSlicer schema keys; sparse — defaults fill the rest
-  return <Viewport settings={settings} setSettings={setSettings} />
+  // The container matters — see Layout below.
+  return (
+    <div style={{ position: 'relative', width: '100%', height: '100vh' }}>
+      <Viewport settings={settings} setSettings={setSettings} />
+    </div>
+  )
 }
 ```
 
+Styles are injected into the component's Shadow DOM root — nothing to import, and host CSS cannot collide.
+
+## Layout
+
+**Give it a positioned, sized container.** The shadow host is `display: contents`, so it contributes no box of its
+own, and the shell inside is `position: absolute; inset: 0`. It therefore fills the nearest *positioned* ancestor —
+`position: relative` (or absolute/fixed) with a real height. Drop it into a plain static `<div>` and it escapes to
+the initial containing block instead, which usually looks like the viewer covering the whole page.
+
+There is no width or height prop: the component always fills that container, and resizes with it.
+
 Slice parameters are derived from `settings` via `three-slicer`'s schema mapping — pair it with `three-slicer/components`' `<SettingsPanel/>` sharing the same state for a full slicer UI.
 
+A `.3mf` written by a slicer (OrcaSlicer/BambuStudio save, MakerWorld download) imports as a **project**: plate layout, project settings, and support/material painting are restored, not just the meshes. Where a facet carries both paint kinds, material paint wins and the dropped support paint is reported.
+
 Props: `settings`, `setSettings`, and three optional React-node slots rendered in the right sidebar —
 `processPanel` (the process card), `motionPanel` (folded into the printer card) and `filamentPanel`
 (folded into the filament card, next to the material picker).
@@ -58,6 +77,55 @@ Every panel can be switched off, and the values the component owns can be seeded
   second while slicing.
 - **`onSliced`** — `{plate, stats, gcode}` when a slice is cached. Switching plate tabs does not re-fire it.
 
+## Keyboard and mouse
+
+Which keys are live depends on the tab, and every one is ignored while an input has focus. Letter shortcuts match
+the **physical** key, so they keep working under a non-Latin keyboard layout — with an IME on, the Korean layout
+reports `'ㅁ'` for M, and matching on the character would silently kill every letter shortcut while leaving the
+arrows and Delete working.
+
+| Both tabs | |
+| --- | --- |
+| `Ctrl/⌘ + R` | Slice the current plate |
+| `Ctrl/⌘ + C` / `V` / `X` | Copy · paste · cut the selection |
+| `Ctrl/⌘ + K` or `Ctrl/⌘ + D` | Duplicate |
+| `Ctrl/⌘ + A` | Select all |
+| `Ctrl/⌘ + Z` | Undo — bound to the component root, so it never reaches your app's own Ctrl+Z |
+| `Ctrl/⌘ + Shift + Z` or `Ctrl/⌘ + Y` | Redo |
+
+| Prepare | |
+| --- | --- |
+| `M` or `G` · `R` · `S` | Move · rotate · scale gizmo |
+| `Arrow keys` | Nudge 10mm — `Shift` for 1mm |
+| `PageUp` / `PageDown` | Rotate ±45° |
+| `Delete` / `Backspace` | Remove the selection |
+| `Z` · `B` | Zoom to all · zoom to bed |
+| `Esc` | Cancel the current tool |
+| `?` | Shortcut help overlay |
+
+| Preview | |
+| --- | --- |
+| `↑` / `↓` | Step one layer — `Shift` for ten |
+| `L` · `T` | Single-layer view · travel moves |
+| `Z` · `B` | Zoom to all · zoom to bed |
+| `Esc` | Back to Prepare |
+
+Mouse selection follows upstream's rules: a plain click **replaces** the selection, `Ctrl/⌘ + click` adds or
+removes, a plain click on something already selected **keeps** the set (which is what makes dragging several
+objects work), `Shift + drag` is a box select, and clicking empty space clears. Alt is not a de-select, in
+upstream or here.
+
+## Undo and redo
+
+The history covers the viewport's **own** state: object transforms, additions, removals, per-object extruder and
+visibility. Fifty steps, with repeats of the same action inside half a second folded into one — so a held arrow key
+undoes as a single move rather than forty.
+
+What it deliberately does not cover, and why the boundary sits there: `settings` is **yours**, passed in as a prop,
+so nothing inside the component can put it back. Painting is outside it too (restoring a step would need a kernel
+re-`prepare` for every entry), as are the prime tower and the plate count, which write host settings. If you want
+those undoable, undo them on your side of the prop.
+
 ## Materials and painting
 
 The filament card holds **one material per extruder**: add an extruder, pick its colour, and pick its filament preset from the vendor catalog (`filamentPresets()` in `three-slicer/settings` — the shortlist is the printer model's own recommendation, the full list everything compatible). Selecting a row aims the material picker and the settings form at that extruder; the colours feed the object meshes, the prime tower and the preview's **Filament** view type, which colours every segment by the extruder that printed it.
@@ -71,6 +139,97 @@ Two limits to expect while using it:
 
 If you consume `three-slicer/viewer/toolpath` directly, note that the stride-8 role field `paths[k+3]` now carries the printing extruder alongside the role as `role + tool * 16`. Mask it — `& 15` for the role, `>>> 4` for the tool. Streams produced before this encoding are entirely below 16 and decode to their own role with tool 0, so older data still reads correctly.
 
+## Turning behaviour off
+
+`panels` controls what is drawn; `features` controls what the component *does* outside its own box. Same rule —
+opt-out only, everything on unless you say `false`, an unknown key stays on.
+
+```jsx
+<Viewport
+  gcode={text}
+  panels={{ sidebar: false, topBar: false }}
+  features={{ warmup: false, shortcuts: false, logs: false }}
+/>
+```
+
+| Key | Off means |
+| --- | --- |
+| `shortcuts` | No keyboard bindings. They are installed on `window`, so while the viewer is mounted they fire wherever focus is (inputs excepted) — and `Ctrl+C` preventDefaults, which takes a host page's own copy. Turn them off when your app has its own. |
+| `warmup` | The WASM kernel is not loaded on mount. Nothing is downloaded or compiled until something actually slices — which for a `gcode`-only viewer is never, so this is several megabytes and a thread pool you stop paying for. |
+| `drop` | No drag and drop onto the canvas. |
+| `filePicker` | The file dialog never opens, from any of the buttons that open it. |
+| `contextMenu` | No right-click menu. The browser's own menu stays suppressed over the canvas either way — OrbitControls preventDefaults `contextmenu` itself. |
+| `logs` | No console output, from the component or from the slice worker. |
+
+### Read-only panels
+
+A sidebar panel can also be shown but not editable — the shape you want when the host picks the printer, process
+and filament itself and does not want the user changing them. It is a third value on the same `panels` key:
+
+```jsx
+<Viewport
+  settings={presetSettings}
+  panels={{ printerCard: 'readonly', filamentCard: 'readonly', processCard: 'readonly' }}
+/>
+```
+
+Lockable: `sidebar`, `printerCard`, `filamentCard`, `objectList`, `towerCard`, `previewControls`, `processCard`,
+`sliceBar`. `sidebar: 'readonly'` locks the whole column at once; the per-card keys are for mixing, such as a
+locked printer card above a live object list. Every other panel takes `true`/`false` only — a `'readonly'` that
+silently did nothing on half the keys would be worse than not offering it.
+
+The panel is drawn normally and keeps showing real values; it just cannot be clicked, typed into or tabbed to, and
+that includes any node you passed into it (`motionPanel`, `filamentPanel`, `processPanel`). Implemented with the
+`inert` attribute, so it needs Chrome 102+, Safari 15.5+ or Firefox 112+.
+
+**It locks the UI path, not the value.** `settings` is still your prop, and other paths inside the viewer still
+write it — importing a 3mf project applies that project's settings whether or not the cards are locked.
+
+### Printer preset files
+
+The printer card carries **Load** and **Save**. Save writes an OrcaSlicer preset: a machine `.json` on its own, or
+an `.orca_printer` bundle when the settings map also names a process or filament preset (the cards record those as
+`printer_settings_id` / `print_settings_id` / `filament_settings_id`, so nothing extra has to be tracked). Load
+accepts the same set upstream's dialog does — `.json`, `.orca_printer`, `.orca_bundle`, `.orca_filament`, `.zip` —
+and applies every preset it finds, clearing that type's keys first.
+
+`inherits` is followed through the shipped printer catalog, so a vendor file loads with its bed intact; when the
+parent is unknown the file's own values are still applied and the notice says so. Codec details and the reason
+that matters are in the [package README](../README.md#preset-files).
+
+Load opens a file dialog, so it respects `features.filePicker`; Save goes through `onExport` like every other
+download.
+
+### Taking the saves
+
+The save buttons are inside the component, so `onExport` is the only way to send a file somewhere other than the
+browser's download folder. It sees the 3mf project, the STL and each plate's G-code. Return truthy to say you
+handled it:
+
+```jsx
+<Viewport onExport={(file, filename) => { uploadToServer(file, filename); return true }} />
+```
+
+Return nothing and the download happens as well, which is useful for logging what was saved without changing it.
+
+## What the host cannot drive
+
+The component owns its scene, and the props are the whole interface — there is no ref, no imperative handle, and no
+`models` prop. Worth knowing before you design around it:
+
+- **Models enter through the UI only** — the file dialog or drag and drop. A host cannot hand a mesh in, and cannot
+  remove or transform one. What it *can* do is watch: the `objects` event reports `{id, name, extruder, visible}`
+  for every object as the set changes.
+- **Slicing is triggered from the UI or by `defaultAutoSlice`**, which unlike the in-app toggle also performs the
+  first slice — that is what makes a panel-less embed able to slice at all. The result arrives on `onSliced`.
+- **`gcode` is one-way**: pass G-code text and it is drawn on the selected plate instead of a slice result, and
+  auto re-slice leaves that plate alone while it is set.
+- Everything else the component owns — camera, selection, plate count, paint state — is reported through `onEvent`
+  and settable only by the user.
+
+If you need programmatic control over the scene, build on the subpath exports (`three-slicer/viewer/toolpath`,
+`/loaders`, `/gcode`) and `three-slicer/client` rather than on `<Viewport/>`.
+
 ## Multithreaded slicing (automatic)
 
 The engine ships two WASM kernels: single-threaded (default) and `-pthread` multithreaded (~2× wall-clock on layer-parallel wall generation, measured 12× on the wall pass itself). The worker picks the mt kernel automatically when the page is [cross-origin isolated](https://developer.mozilla.org/en-US/docs/Web/API/Window/crossOriginIsolated) — i.e. served with: