three-slicer-viewer 0.2.5

package/types/settings.d.ts

@@ -0,0 +1,173 @@
+// three-slicer-viewer/settings — the catalog-free settings surface (three-slicer/settings re-exports it and adds the vendor catalog).
+import type { SlicerSettings, SettingKey, Point } from './settings-keys.d.ts'
+export type { SlicerSettings, SettingKey, Point }
+
+/** The config-schema default value (undefined for unknown keys) */
+export function schemaDefault(key: string): unknown
+
+/** Settings map first, schema default otherwise. Vector types are returned as-is. */
+export function settingRaw(settings: SlicerSettings | null | undefined, key: string): unknown
+
+/** Normalizes settingRaw to a scalar — [0] for vectors. */
+export function settingScalar(settings: SlicerSettings | null | undefined, key: string): unknown
+
+/**
+ * Settings map -> kernel slice params. Derived from schema keys; missing keys are filled with internal defaults.
+ * 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, opts?: { plate?: number }): Record<string, unknown>
+
+/**
+ * Clear-then-merge preset application: deletes `keys` (the catalog's own key set) from `settings`, then
+ * merges `preset`. A null preset applies nothing and returns the settings unchanged — a failed lookup must
+ * not half-clear the previous pick.
+ */
+export function applyPreset(settings: SlicerSettings | null | undefined, preset: Partial<SlicerSettings> | null | undefined, keys: readonly string[] | null | undefined): SlicerSettings
+
+/**
+ * The schema keys deriveKernelParams consumes — the distinct "From setting" column of engine/PARAMS.md,
+ * generated by the same probe that generates the table (so it cannot drift from the real mapping).
+ */
+export const kernelSettingKeys: readonly string[]
+
+/**
+ * The keys of `settings` that deriveKernelParams does NOT read — they are accepted and silently have no
+ * effect on an FFF slice. Scope is the FFF derivation only: a key listed here can still be meaningful to
+ * the SLA derivation, the viewer, or project metadata. Sorted.
+ */
+export function ignoredKernelSettings(settings: SlicerSettings | null | undefined): string[]
+
+/** Which slicing technology the settings map's printer profile declares. Defaults to FFF. */
+export function printerTechnology(settings: SlicerSettings | null | undefined): 'FFF' | 'SLA'
+
+/**
+ * Settings map -> SLA (resin) slice params for the pure-JS contour slicer + the display geometry the SL1 raster
+ * export needs. Separate from deriveKernelParams — that one feeds the WASM kernel and its key set is pinned.
+ */
+export function deriveSlaParams(settings: SlicerSettings | null | undefined): {
+  layer_height: number
+  initial_layer_height: number
+  exposure_time: number
+  initial_exposure_time: number
+  faded_layers: number
+  display_width: number
+  display_height: number
+  display_pixels_x: number
+  display_pixels_y: number
+  supports_enable: boolean
+  pad_enable: boolean
+}
+
+/**
+ * A 3mf project's raw `Metadata/project_settings.config` -> a settings map this API accepts.
+ * Upstream writes every option as a string ("0"/"1" for a bool, "0.2" for a float, one entry per extruder for a
+ * vector); each value is coerced by its config-schema type, and keys the schema does not define are dropped into
+ * `skipped` rather than carried into the map. `applied` is how many keys survived.
+ */
+export function normalizeProjectSettings(raw: Record<string, unknown> | null | undefined): {
+  settings: SlicerSettings
+  applied: number
+  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
+
+// ---- The vendor catalog: NOT in this package ---------------------------------
+// printerKeys, printersByVendor, printerTechByVendor, resinCatalog, resinSettingsFor, printerSettings,
+// printerDefaultPreset, processPresets and filamentPresets are OrcaSlicer's profile data (AGPL) and live in
+// `three-slicer/settings`. The viewer takes them through its `catalog` prop (see `Catalog` in viewer.d.ts);
+// the interface shapes below are what such a catalog's lazily loaded halves return, kept here so a host can
+// type its own.
+
+/** The schema keys the kernel's machine limits are read from — for UI that shows which ones are in play. */
+export const machineLimitKeys: string[]
+
+export interface ProcessPresetsApi {
+  /** Every key a process preset can set — clear these before applying a different one */
+  keys: string[]
+  /** Preset names compatible with a printer profile, in upstream order */
+  listFor(printerProfileName: string): string[]
+  /** The settings a preset applies, ready to merge. `null` when unknown. */
+  settingsFor(presetName: string): SlicerSettings | null
+}
+
+/** A material as a picker shows it. `type`/`vendor` are `''` when the profile chain declares neither. */
+export interface FilamentPreset { name: string, type: string, vendor: string }
+
+export interface FilamentPresetsApi {
+  /** Every key a filament preset can set — clear these before applying a different material */
+  keys: string[]
+  /** Every material in the catalog, in upstream order — for a picker shown before any printer is chosen */
+  all(): FilamentPreset[]
+  /** Materials compatible with a printer profile, in upstream order */
+  listFor(printerProfileName: string): FilamentPreset[]
+  /** The vendor's recommended materials for that printer's model — a subset of listFor */
+  recommendedFor(printerProfileName: string): FilamentPreset[]
+  /** The settings a material applies, ready to merge. `null` when unknown. */
+  settingsFor(presetName: string): SlicerSettings | null
+}

package/types/toggle.d.ts

@@ -0,0 +1,30 @@
+// three-slicer-viewer/toggle — partial evaluation of enable_if expressions. Ships unbound (no rules: nothing
+// disables); three-slicer/toggle binds upstream's toggle-rules.json and the full schema through makeToggle().
+import type { SlicerSettings } from './settings-keys.d.ts'
+
+/** Settings accessor — schema default when a value is missing, [0] for vector types. */
+export interface ToggleCfg {
+  bool(key: string): boolean
+  int(key: string): number
+  float(key: string): number
+  /** Whether the key exists in config-schema */
+  has(key: string): boolean
+}
+
+export function makeCfg(settings: SlicerSettings | null | undefined): ToggleCfg
+
+/**
+ * Evaluates a single enable_if expression. Untranslatable expressions return `null` (= fail-open, stays enabled) —
+ * make sure to treat that as distinct from `false`.
+ */
+export function evalEnableIf(expr: string, locals: Record<string, unknown>, cfg: ToggleCfg): boolean | null
+
+/** Keys that must be disabled under the current settings -> the enable_if expression that disabled them. Only rules that are unambiguously false. */
+export function disabledKeys(cfg: ToggleCfg): Record<string, string>
+
+/** Bind the evaluator to a rule set and a schema. `three-slicer/toggle` is `makeToggle(toggleRules, schema)`. */
+export function makeToggle(rules?: Record<string, { rules?: Array<{ enable_if?: string; fields?: string[] }> }>, schema?: Record<string, { default?: unknown }>): {
+  makeCfg(settings: SlicerSettings | null | undefined): ToggleCfg
+  disabledKeys(cfg: ToggleCfg): Record<string, string>
+  evalEnableIf(expr: string, locals: Record<string, unknown>, cfg: ToggleCfg): boolean | null
+}

package/types/toolpath.d.ts

@@ -0,0 +1,138 @@
+// three-slicer-viewer — kernel layers -> GPU-instanced toolpath.
+// Also published as three-slicer/viewer/toolpath, which re-exports this package.
+// Does not import three: makeToolpath takes the THREE namespace as an argument (guaranteeing a single instance).
+
+/** The 24 triangle indices of the 8-vertex diamond cross-section (from SegmentTemplate.cpp:18) */
+export const VERTEX_DATA: number[]
+
+/** Toolpath type -> color. 0=travel, 1=wall … 11=prime */
+export const TYPE_COLOR: Record<number, number[]>
+export const TYPE_LABEL: Record<number, string>
+
+/**
+ * Per-extruder colors for the Filament view. Categorical, not semantic — the toolpath stream carries a tool index and
+ * nothing about the material, and a machine may have more extruders than entries, so index it modulo its length.
+ */
+export const TOOL_COLOR: number[][]
+
+/** Blue-to-red 11-color heatmap (libvgcode ColorRange.hpp:14) */
+export const DEFAULT_RANGES_COLORS: number[][]
+
+export interface ViewTypeDef {
+  key: 'feature' | 'speed' | 'height' | 'width' | 'fan' | 'temp' | 'filament'
+  label: string
+  /** Whether values are continuous (heatmap). False means a fixed color. */
+  cont: boolean
+  unit: string
+}
+export const VIEW_TYPES: ViewTypeDef[]
+
+/** Per-vertex extra data */
+export interface SegmentMeta {
+  vType: Uint8Array
+  /** Printing extruder, decoded out of the role field's high bits. Untooled output decodes to 0, i.e. single material. */
+  vTool: Uint8Array
+  vWidth: Float32Array
+  vHeight: Float32Array
+  vLayer: Int32Array
+}
+
+export interface SegmentData {
+  position: Float32Array
+  hwa: Float32Array
+  segIndex: Uint32Array
+  nV: number
+  nSeg: number
+  layerSegPrefix: Uint32Array
+  travelPos: Float32Array
+  travelPrefix: Uint32Array
+  nTrav: number
+  layerCount: number
+  maxAbs: number
+  hasNaN: boolean
+  meta: SegmentMeta
+  /** Total extruded length per type (index = toolpath type, length 16) */
+  typeLengths: Float64Array
+  /** Null when there is not a single vertex */
+  bbox: { min: [number, number, number]; max: [number, number, number] } | null
+}
+
+/** Kernel layers[{z, paths(stride8), widths[]}] -> GPU stream. */
+export function buildSegmentData(layers: unknown[], defaultLineWidth: number): SegmentData
+
+/** Length share per type (%), descending by pct. The kernel does not expose time per role, so length is used as an approximation. */
+export function roleRatios(typeLengths: Float64Array | number[]): Array<{
+  type: number
+  label: string
+  pct: number
+  color: number[]
+}>
+
+/**
+ * speed/fan/temp are absent from the kernel toolpath and derived from settings — these are the values used for that.
+ */
+export interface ColorContext {
+  /** Print speed per toolpath type, mm/s. Falls back to the wall entry for a type not listed. */
+  speedByType?: Record<number, number>
+  firstLayerSpeed?: number
+  /** Part-cooling fan %, used for every layer at or above `closeFanLayers`. Bridges are always 100. */
+  fanNormal?: number
+  /** Layers below this index are drawn at 0% fan. */
+  closeFanLayers?: number
+  tempNormal?: number
+  tempFirst?: number
+  /** Filament colours (hex, per extruder) for the Filament view, so the preview agrees with the filament
+   *  card and the stats legend. Falls back to the categorical TOOL_COLOR palette per tool. */
+  toolColors?: string[]
+}
+
+export interface ColorResult {
+  /** Per-vertex RGBA (nV*4). The color is packed into `.r`. */
+  color: Float32Array
+  min: number
+  max: number
+  viewType: ViewTypeDef['key']
+  label: string
+  unit: string
+  /** False means fixed colors — min/max are 0 and no legend should be drawn. */
+  cont: boolean
+}
+
+export function computeColors(data: SegmentData, viewType: ViewTypeDef['key'], ctx: ColorContext): ColorResult
+
+export interface ToolpathHandle {
+  /** THREE.Mesh — typed by the THREE namespace passed in */
+  mesh: any
+  /** THREE.LineSegments (travel) */
+  travLines: any
+  setLayerRange(lo: number, hi: number): void
+  /** Backwards compatible — same as setLayerRange(0, n-1). */
+  setVisibleLayers(n: number): void
+  setTravelVisible(visible: boolean): void
+  setColors(color: Float32Array): void
+  dispose(): void
+  nSeg: number
+  layerCount: number
+}
+
+/** @param THREE - the `import * as THREE from 'three'` namespace. The consumer's instance is used as-is. */
+export function makeToolpath(THREE: any, data: SegmentData): ToolpathHandle
+
+/** [r,g,b] in 0..1 -> r<<16 | g<<8 | b, the form the shader unpacks. */
+export function packColor(rgb: number[]): number
+/** '#rrggbb' -> [r,g,b] in 0..1. Unparseable input returns mid-grey rather than NaN. */
+export function hexToRgb(hex: string): number[]
+/** Value -> colour interpolated between adjacent stops. Clamps BOTH ends; non-finite input returns stop 0. */
+export function rangeColorAt(v: number, lo: number, hi: number, palette?: number[][]): number[]
+
+/** Moves in one layer — extrusions and travels together, which is what a scrub bar walks. */
+export function layerMoveCount(data: SegmentData, layer: number): number
+/** The topmost layer in [lo, hi] that has moves, or `lo` when none does. */
+export function topMoveLayer(data: SegmentData, lo: number, hi: number): number
+/** Where the nozzle is after `at` moves into `layer`. `segCount + travCount === at`, clamped to the layer. */
+export function moveCursor(data: SegmentData, layer: number, at: number): {
+  point: [number, number, number] | null
+  segCount: number
+  travCount: number
+  onTravel: boolean
+}

package/types/viewer.d.ts

@@ -0,0 +1,256 @@
+// three-slicer/viewer
+import type * as React from 'react'
+import type { SlicerSettings } from './settings-keys.d.ts'
+import type { ProcessPresetsApi, FilamentPresetsApi } from './settings.d.ts'
+
+export interface ViewportProps {
+  /**
+   * Sparse settings map. Defaults to `{}`. Two viewer knobs ride in it beside the schema keys: `sla_antialias`
+   * (SL1 mask MSAA, 1|2|4) and `slice_workers` — how many plates an all-plates run slices at once (0/absent =
+   * Auto: half the cores on the threaded kernel, one per core on the single-threaded one; the in-app select
+   * writes it). Neither reaches a 3mf.
+   */
+  settings?: SlicerSettings
+  /** React setState shape. Defaults to a no-op. */
+  setSettings?: React.Dispatch<React.SetStateAction<SlicerSettings>>
+  /**
+   * Per-plate overrides: `{[plateIndex]: sparse map}`, merged over `settings` for that plate's slice only —
+   * a key's absence means "follow the global value" (delete the key to clear an override). Plate identity is
+   * the plate index; deleting the last plate truncates its entry. Editing one plate's override invalidates only
+   * that plate's cached result. Any key can be overridden: `printer_technology` routes that plate to the
+   * FFF or SLA slicer (an SLA plate's grid cell is sized to its resin display), and a bed override
+   * (`printable_area`/`printable_height`) resizes that plate's own grid cell. What a 3mf cannot represent —
+   * a mixed-technology or mixed-bed project — is refused at project export with a typed error
+   * (`error.code` `'UNSUPPORTED_MIXED_TECH_3MF'` / `'UNSUPPORTED_MIXED_BED_3MF'`); per-plate G-code/.sl1
+   * exports always work. Defaults to `{}`.
+   */
+  plateSettings?: Record<number, SlicerSettings>
+  /** React setState shape for {@link ViewportProps.plateSettings}. Defaults to a no-op. */
+  setPlateSettings?: React.Dispatch<React.SetStateAction<Record<number, SlicerSettings>>>
+  /**
+   * Left process-panel slot — usually `<SettingsPanel embedded/>`. Defaults to null.
+   *
+   * Pass a FUNCTION to opt into the per-plate scope toggle (shown with more than one plate): in plate scope
+   * the panel receives the selected plate's EFFECTIVE map and a setter that writes only the changed keys into
+   * {@link ViewportProps.plateSettings}; `meta.overriddenKeys`/`meta.onRevertKey` drive the override badges
+   * (`<SettingsPanel overriddenKeys={...} onRevertKey={...}/>`). In global scope the pair is simply
+   * `settings`/`setSettings`. A plain node keeps the global-only binding.
+   */
+  processPanel?: React.ReactNode
+    | ((settings: SlicerSettings, setSettings: React.Dispatch<React.SetStateAction<SlicerSettings>>,
+        meta: { scope: 'global' | 'plate', selectedPlate: number, overriddenKeys: string[],
+                onRevertKey: ((key: string) => void) | null }) => React.ReactNode)
+  /** Motion-limits editor, folded into the printer card — usually `<SettingsPanel only={{builder:'TabPrinter::build_kinematics_page'}}/>`. */
+  motionPanel?: React.ReactNode
+  /**
+   * Filament editor, folded into the filament card. Pass a function rather than a node: with more than one
+   * extruder loaded the card projects that extruder's slice of the per-extruder columns and writes the form's
+   * edits back at its index, so the panel must bind to the pair it is given.
+   */
+  filamentPanel?: React.ReactNode
+    | ((settings: SlicerSettings, setSettings: React.Dispatch<React.SetStateAction<SlicerSettings>>) => React.ReactNode)
+  /**
+   * 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>> & 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.
+   */
+  gcode?: string | null
+  /**
+   * An `.sl1` archive rendered as a raster preview — the SLA half of {@link ViewportProps.gcode}'s contract: it
+   * lands on the selected plate and the kernel is never started. Set both and the G-code wins; one plate holds
+   * one artifact.
+   *
+   * Two things it does that `gcode` does not. It writes to your `settings` — the archive's own job description,
+   * `printer_technology` included, because an .sl1 opened in an FFF session has to switch it. And it reconstructs
+   * a surface from the masks in the background, so the preview fills in a moment after the layers appear.
+   *
+   * Re-injects whenever the value's IDENTITY changes, so hold the File/buffer in state rather than building it
+   * during render — a fresh `new Uint8Array(...)` each render re-imports each render. `{name, data}` exists
+   * because the name is the import notice's subject and the filename a re-export hands back.
+   */
+  sl1?: File | Blob | ArrayBuffer | Uint8Array | { name?: string, data: ArrayBuffer | Uint8Array } | null
+  /**
+   * Content imported once on mount, through the same extension dispatch as a drop: models (STL/OBJ/3MF/AMF/PLY —
+   * a 3mf project applies its settings, plates and painting), `.sl1` raster archives, and preset files
+   * (`.json` / `.orca_printer` / `.orca_bundle` / `.orca_filament` / `.zip`). The `{name, data}` form exists
+   * because the dispatch runs on the file NAME's extension. Deliberately mount-only — recreating the array on a
+   * later render does not re-import; runtime loading is the picker, drop, or a remount.
+   */
+  files?: Array<File | { name: string, data: ArrayBuffer | Uint8Array }>
+  /**
+   * The slicing implementation — a React hook with the shape of three-slicer's `useSlicer`. This package ships
+   * none: without it the viewer runs on a no-op slicer that loads, displays and exports but never slices.
+   * Must be stable for the life of the mount (it is called as a hook).
+   */
+  slicer?: (deps: Record<string, unknown>) => SlicerHandle
+  /**
+   * The vendor preset catalog. This package ships none — nothing passed means empty pickers. `three-slicer/viewer`
+   * passes its bundled OrcaSlicer extraction; a host with its own fleet passes its own (a partial object is
+   * merged over the empty catalog).
+   */
+  catalog?: Catalog | null
+  /**
+   * A token whose identity CHANGE requests one slice of the current plate — the host's Slice button:
+   * keep a counter in state and bump it. The mount value is inert (0 and null both slice nothing), so is
+   * setting it back to `null`. Ignored while a `gcode`/`sl1` injection holds the plate or the scene is
+   * empty — the same conditions under which the built-in slice bar is not pressable. A change while a
+   * slice is running cancels it and re-slices: the last request wins.
+   */
+  sliceRequest?: number | string | object | null
+
+  /** Initial filament colours (hex), one per extruder. Defaults to the built-in T1/T2 pair. */
+  defaultExtruderColors?: string[] | null
+  /**
+   * Start with auto re-slice on. Unlike the in-app toggle's original behaviour this also performs the FIRST slice,
+   * which is what makes a panel-less embed able to slice at all.
+   */
+  defaultAutoSlice?: boolean
+  /** Every value change in one channel. See {@link ViewportEvent}. */
+  onEvent?: (event: ViewportEvent) => void
+  /** A finished slice, fired where the result is cached — switching plate tabs does not re-fire it. */
+  /** `throughput` is how fast the slice ran — see `SliceThroughput` in the engine entry. Absent on a kernel
+   *  result that carried none (a cached plate re-announced from before the field existed). */
+  onSliced?: (result: {
+    plate: number; stats: Record<string, unknown>; gcode: string
+    throughput?: { ms: number; kernelMs: number | null; layersPerSecond: number; msPerMsegment: number | null }
+  }) => void
+  /**
+   * An all-plates run as it moves: the run map on every change, `null` when none is on. `workers.pool` is how
+   * many slice at once, `workers.kernel` which kernel loaded ('mt' threads / 'st'); each plate carries its state
+   * and its own progress (0..1) and layers/second. Fired several times a second while a run is on.
+   */
+  onSliceRun?: (run: {
+    workers: { pool: number; active: number; kernel: 'mt' | 'st' | null }
+    plates: Record<number, { state: 'queued' | 'busy' | 'done' | 'failed'; progress: number; rate: number }>
+  } | null) => 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 horizontal move scrub under the canvas — how far into the top shown layer the print has got. Preview
+   *  and FFF only: a resin layer is cured in one exposure and has no intra-layer order to walk. */
+  | 'moveBar'
+  /** 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'
+  /** The resin (SLA) card. Takes the filament card's place when the printer profile declares SLA. */
+  | 'resinCard'
+
+/** Value changes reported through {@link ViewportProps.onEvent}. Not fired for the initial values. */
+export type ViewportEvent =
+  | { type: 'canvasMode'; value: 'prepare' | 'preview' }
+  | { type: 'objects'; value: Array<{ id: number; name: string; extruder: number; visible: boolean }> }
+  | { type: 'selectedPlate'; value: number }
+  | { type: 'plateCount'; value: number }
+  | { type: 'extruderColors'; value: string[] }
+  | { type: 'autoSlice'; value: boolean }
+  | { type: 'slicing'; value: boolean }
+  /** 0..1. Fires several times a second while slicing — throttle on the host side if that matters. */
+  | { type: 'progress'; value: number }
+  /**
+   * Live throughput: layers finished per second over a 250ms window, `0` between slices. An SLA slice reports it
+   * throughout. An FFF slice reports it only once the emission pass begins streaming layers — the earlier passes
+   * publish no per-layer progress, so nothing is measured there and none is invented. For the whole-slice figure
+   * use `throughput` from `onSliced`.
+   */
+  | { type: 'sliceRate'; value: number }
+  | { type: 'viewType'; value: 'feature' | 'speed' | 'height' | 'width' | 'fan' | 'temp' | 'filament' }
+  | { type: 'paintMode'; value: 'off' | 'enforcer' | 'blocker' | 'material' }
+  | { type: 'layerCount'; value: number }
+  | { type: 'layerRange'; value: { lo: number; hi: number } }
+  /** The move scrub's position within the top shown layer; `max` is that layer's move count, extrusions and
+   *  travels together. Not fired while the whole layer is shown. */
+  | { type: 'moveScrub'; value: { at: number; max: number } }
+  | { type: 'error'; value: string }
+  | { type: 'notice'; value: string }
+
+declare const Viewport: React.FC<ViewportProps>
+export default Viewport
+
+export interface SlicerHandle {
+  getWorker(): Worker | { postMessage(msg: unknown): void }
+  cancelSlice(): void
+  runSlice(merged: unknown, ctx?: unknown): Promise<unknown>
+  pendingSliceRef: { current: unknown }
+  downgradeRef: { current: boolean }
+  createPoolContext(opts: Record<string, unknown>): { cancel(): void; terminate(): void }
+  kernelKindRef: { current: 'mt' | 'st' | null }
+  progressSinkRef: { current: unknown }
+}
+export interface Catalog {
+  printerKeys: string[]
+  printerSettings(profileName: string): Record<string, unknown> | null
+  printersByVendor: Record<string, unknown>
+  printerTechByVendor: Record<string, unknown>
+  printerDefaultPreset(profileName: string): string | null
+  processPresets(): Promise<ProcessPresetsApi>
+  filamentPresets(): Promise<FilamentPresetsApi>
+  resinCatalog: unknown[]
+  resinSettingsFor(name: string): Record<string, unknown> | null
+}
+export const emptyCatalog: Catalog
+export function resolveCatalog(catalog?: Partial<Catalog> | null): Catalog
+export function useNoopSlicer(): SlicerHandle
+
+/** The slicing hook, unbound. `deps.makeWorker` must return a Worker speaking this package's slice protocol —
+ *  three-slicer/viewer supplies its WASM kernel worker and re-exports the bound hook. */
+export function useSlicer(deps: Record<string, unknown> & { makeWorker: () => Worker }): SlicerHandle