three-slicer 0.1.6 → 0.1.7

package/engine/src/preset_file.js

@@ -0,0 +1,99 @@
+// OrcaSlicer preset files — the `.json` its "Config files (*.json;…)" import accepts, and that its
+// "Export preset" writes. One file holds one preset of one type: machine, process or filament.
+//
+// The value encoding is the same one `project_settings.config` uses, and for the same reason: upstream writes
+// every option through ConfigBase::save_to_json, which serializes each one to a string (a bool is "1"/"0", a point
+// is "XxY", a vector becomes an array of strings). So normalize/serializeProjectSettings are reused verbatim
+// rather than reimplemented — a second copy of that coercion table is exactly how the two would drift.
+//
+// Zero dependencies, so this lives in the engine and works headless. The zip bundle formats (.orca_printer) need
+// a deflate and therefore live in the viewer, which already has one.
+import { schema, presetKeys } from './data.js'
+import { normalizeProjectSettings, serializeProjectSettings } from './settings.js'
+
+/** `machine` for printers, `process` for print settings, `filament` for materials — upstream's own `type` field. */
+const KEY_LIST = { machine: 'printer', process: 'process', filament: 'filament' }
+
+// Preset bookkeeping, not settings. Upstream writes six of these; `inherits` is read (it names the parent) and the
+// rest are carried only so a round trip does not lose them.
+const ENVELOPE = new Set(['type', 'name', 'from', 'version', 'setting_id', 'instantiation', 'inherits',
+  'filament_id', 'is_custom_defined', 'filament_settings_id', 'print_settings_id', 'printer_settings_id'])
+
+/** Every option key that belongs in a preset of this type. */
+export function presetOptionKeys(type) {
+  const list = presetKeys[KEY_LIST[type]]
+  if (!list) throw new Error(`unknown preset type '${type}' (expected machine, process or filament)`)
+  return list
+}
+
+/**
+ * A settings map -> the object an OrcaSlicer preset `.json` holds.
+ *
+ * Written **flattened**: no `inherits`, every key present. That is the whole difference between a file another
+ * program can read on its own and one that only means something next to the vendor database it was derived from —
+ * upstream's own exports are diffs against a parent (`Preset::save`: "only save difference if it has parent"),
+ * which is fine for OrcaSlicer reading its own files back and useless for anyone else.
+ *
+ * `complete: false` writes only the keys the settings map actually holds, for a diff-shaped file.
+ */
+export function writePresetFile(settings, { type = 'machine', name = 'Custom', complete = true, version = '1.0.0.0' } = {}) {
+  const keys = presetOptionKeys(type)
+  const picked = {}
+  for (const key of keys) {
+    // `inherits` is in upstream's printer_options list — it is an option to OrcaSlicer's config machinery, but it
+    //  is bookkeeping here, and writing it would put an empty parent name in a file meant to stand alone. The same
+    //  ENVELOPE set the reader strips is what the writer refuses to emit, so the two cannot disagree about it.
+    if (ENVELOPE.has(key)) continue
+    if (settings && key in settings && settings[key] != null) picked[key] = settings[key]
+    // A key with no schema default cannot be filled — there is nothing to fill it with. `complete` means "every
+    //  option that HAS a value", not "every option name", and inventing one would be worse than leaving it out.
+    else if (complete && schema[key]?.default !== undefined) picked[key] = schema[key].default
+  }
+  return {
+    type, name, from: 'User', version, instantiation: 'true',
+    ...serializeProjectSettings(picked),
+  }
+}
+
+/**
+ * The inverse: a parsed preset `.json` -> a settings map this package accepts.
+ *
+ * `inherits` is the trap. Upstream stores a derived preset as the DIFF against its parent, so a vendor file on its
+ * own carries a fraction of the preset — the Bambu X1C machine json inherits `fdm_bbl_3dp_001_common` and lists
+ * about twenty keys. Resolution therefore needs a parent lookup, and this package has no full preset database:
+ * `resolveParent(name)` is the hook, and `printerSettings` covers the machine case for the keys the kernel reads.
+ *
+ * When the parent cannot be resolved the file's own values are still applied and `missingParent` names it —
+ * dropping a whole file because one name is unknown loses more than it protects, and the caller can decide.
+ */
+export function readPresetFile(raw, { resolveParent } = {}) {
+  if (!raw || typeof raw !== 'object') throw new Error('not a preset object')
+  const type = raw.type
+  if (!KEY_LIST[type]) throw new Error(`not an OrcaSlicer preset: type is ${JSON.stringify(type)}`)
+
+  const own = {}
+  for (const [key, value] of Object.entries(raw)) if (!ENVELOPE.has(key)) own[key] = value
+  const { settings, applied, skipped } = normalizeProjectSettings(own)
+
+  // The parent goes UNDER the file's own values — the file is the diff, so it wins.
+  let missingParent = null
+  let merged = settings
+  if (raw.inherits) {
+    const parent = resolveParent?.(raw.inherits, type) ?? null
+    if (parent) merged = { ...parent, ...settings }
+    else missingParent = raw.inherits
+  }
+
+  return {
+    settings: merged,
+    type,
+    name: typeof raw.name === 'string' ? raw.name : '',
+    inherits: raw.inherits ?? null,
+    missingParent,
+    applied,
+    skipped,
+  }
+}
+
+/** Convenience: the JSON text an export writes. */
+export const presetFileText = (settings, options) => JSON.stringify(writePresetFile(settings, options), null, 1)

package/engine/src/settings.js

@@ -22,6 +22,43 @@ const KERNEL_PATTERNS = ['rectilinear', 'grid', 'triangles', 'zigzag', 'gyroid',
   'honeycomb', '3dhoneycomb', 'crosshatch', 'concentric']
 const KERNEL_SEAMS = ['nearest', 'aligned', 'back', 'random']
 
+// ---- Pass-through kernel parameters -----------------------------------------------------------------------
+// The kernel reads 159 parameters (see the reference table in engine/README.md, generated from its own reader).
+//  These are the ones whose schema key carries the SAME name, so the mapping is the identity and the only real
+//  decision is WHEN to send them. They are sent only when the settings map actually holds the key — never filled
+//  in from the schema default — because the two defaults disagree for several of them:
+//  independent_support_layer_height is true in the schema and false in the kernel, printable_height is 100 there
+//  and 250 here. Filling one in would silently reslice every existing caller's model. This is the same omission
+//  rule the per-feature widths, the support tools and the prime tower keys already follow, and it is what keeps
+//  deriveKernelParams({}) producing exactly the parameter set it produced before these keys were mapped.
+const PASSTHROUGH_NUM = [
+  // Real (organic) tree support shape. Upstream keeps an _organic spelling and a suffix-less one for most of
+  //  these, and the kernel accepts both — preferring _organic — so both are passed as written rather than
+  //  reconciled here. Before this, none of the organic tree support could be tuned from a settings map at all.
+  'tree_support_branch_angle', 'tree_support_branch_angle_organic',
+  'tree_support_branch_diameter', 'tree_support_branch_diameter_organic',
+  'tree_support_branch_distance', 'tree_support_branch_distance_organic',
+  'tree_support_branch_diameter_angle', 'tree_support_angle_slow', 'tree_support_tip_diameter',
+  'tree_support_top_rate', 'tree_support_wall_count',
+  'support_object_first_layer_gap',
+  // The tree support's build-volume ceiling. Distinct from bed_height above — that one is the kernel's own
+  //  off-the-bed check — but both come from this single schema key, because upstream has one option for both jobs.
+  'printable_height',
+  // Upstream's *_filament_id family: a 1-based filament index per feature, 0 meaning "whatever tool the region
+  //  already prints with". slice_mm.cpp honours the wall and sparse-infill ids and reports the rest in the G-code
+  //  rather than silently dropping them.
+  'outer_wall_filament_id', 'inner_wall_filament_id', 'sparse_infill_filament_id',
+  'top_surface_filament_id', 'bottom_surface_filament_id', 'internal_solid_filament_id',
+]
+const PASSTHROUGH_BOOL = ['independent_support_layer_height']
+// Per-filament vectors, one entry per filament, passed positionally like every other per-extruder array.
+//  filament_map is which physical extruder each filament sits in; density and cost turn extruded millimetres into
+//  the grams and currency the G-code footer reports.
+const PASSTHROUGH_NUM_VECTOR = ['filament_map', 'filament_density', 'filament_cost']
+// Material identity. The kernel needs the type for the two decisions upstream makes by material name (PETG's
+//  extra unretract, TPU on the first layer) and the settings id for the footer.
+const PASSTHROUGH_STR_VECTOR = ['filament_type', 'filament_settings_id']
+
 // Machine limits (the "Motion ability" printer page) -> kernel time-estimate parameters.
 //  Declarative on purpose: the kernel collapses X/Y into one axis, so the mapping cannot be a plain pass-through,
 //  but adding a limit stays a data row instead of code. The fallback is the kernel's own default, so an unedited
@@ -353,6 +390,38 @@ export function deriveKernelParams(settings, opts) {
     if (prime > 0) towerSettings.prime_volume = prime
   }
 
+  // Pass-through parameters (see PASSTHROUGH_* above). `present` reads the settings MAP, not settingRaw, because
+  //  settingRaw's schema fallback is exactly what must not happen here — an unedited key has to stay absent.
+  const passthrough = {}
+  {
+    const present = (key) => settings != null && key in settings && settings[key] != null && settings[key] !== ''
+    for (const key of PASSTHROUGH_NUM) {
+      if (!present(key)) continue
+      const value = Number(S(key))
+      if (Number.isFinite(value)) passthrough[key] = value
+    }
+    for (const key of PASSTHROUGH_BOOL) if (present(key)) passthrough[key] = bool(key, false)
+    for (const key of PASSTHROUGH_NUM_VECTOR) {
+      if (!present(key)) continue
+      const raw = settings[key]
+      passthrough[key] = (Array.isArray(raw) ? raw : [raw]).map(entry => { const n = Number(entry); return Number.isFinite(n) ? n : 0 })
+    }
+    for (const key of PASSTHROUGH_STR_VECTOR) {
+      if (!present(key)) continue
+      const raw = settings[key]
+      passthrough[key] = (Array.isArray(raw) ? raw : [raw]).map(entry => String(entry ?? ''))
+    }
+    // support_line_width is coFloatOrPercent, but the kernel reads it with the plain number reader rather than the
+    //  percent-aware jwidth_raw the per-feature widths get. A "120%" would reach strtod as a quoted string and
+    //  parse to 0 == auto — the setting silently ignored. Resolved here against the nozzle, which is the same
+    //  thing jwidth_raw does for the widths that do get the percent-aware reader.
+    if (present('support_line_width')) {
+      const text = String(settingScalar(settings, 'support_line_width')).trim()
+      const width = text.endsWith('%') ? (parseFloat(text) / 100) * num('nozzle_diameter', 0.4) : Number(text)
+      if (Number.isFinite(width) && width > 0) passthrough.support_line_width = width
+    }
+  }
+
   const perExtruder = {}
   for (const [param, key, scalar] of [
     ['extruder_nozzle_temp', 'nozzle_temperature', num('nozzle_temperature', 200)],
@@ -374,6 +443,7 @@ export function deriveKernelParams(settings, opts) {
   return {
     ...widths,
     ...machine,
+    ...passthrough,     // present only for keys the settings map actually holds (see PASSTHROUGH_* above)
     layer_height: num('layer_height', 0.2),
     first_layer_height: num('initial_layer_print_height', 0.2),
     line_width,
@@ -463,3 +533,8 @@ export function deriveKernelParams(settings, opts) {
     // support_density has no matching schema key, so the kernel default (0.15) is used; scarf_length likewise uses the kernel default (10mm)
   }
 }
+
+// ---- Preset files (the .json OrcaSlicer imports/exports) ----------------------------------------------------
+// Re-exported here rather than given their own subpath: they are settings-map transforms like the 3mf project
+//  codecs above, and a consumer that has one hand on `settings` should not need a second import path for them.
+export { writePresetFile, readPresetFile, presetFileText, presetOptionKeys } from './preset_file.js'

package/engine/src/slicer.worker.js

@@ -11,17 +11,24 @@
 // Automatic multithreaded kernel selection: with crossOriginIsolated (sites serving COOP/COEP) it uses mt (-pthread, PASS1
 //  layers in parallel — measured 2.2x), otherwise st (zero-config). The dynamic import makes bundlers emit both as chunks,
 //  but only one is loaded at runtime. On mt init failure (SAB blocked, …) it falls back to st.
+// Which kernel loaded is worth saying once — mt vs st is a 2x difference and the fallback is silent otherwise.
+//  A host embedding the viewer in its own product can switch it off (`<Viewport features={{ logs: false }} />`,
+//  which sets `quiet` on the messages it sends): this is a separate module instance from the viewer's log.js and
+//  cannot read a flag set over there.
+let quiet = false
+const say = (level, ...args) => { if (!quiet) console[level](...args) }
+
 const loadCore = async () => {
   const isolated = typeof crossOriginIsolated !== 'undefined' && crossOriginIsolated
   if (isolated) {
     try {
       const M = await (await import('./slicer_core.mt.js')).default()
-      console.info('[slicer.worker] core: mt (threads)')
+      say('info', '[slicer.worker] core: mt (threads)')
       return M
-    } catch (e) { console.warn('[slicer.worker] mt load failed — falling back to st:', e) }
+    } catch (e) { say('warn', '[slicer.worker] mt load failed — falling back to st:', e) }
   }
   const M = await (await import('./slicer_core.js')).default()
-  console.info('[slicer.worker] core: st')
+  say('info', '[slicer.worker] core: st')
   return M
 }
 
@@ -108,6 +115,9 @@ const paintedReply = (Module, message, paintedState) => {
 
 self.onmessage = async (e) => {
   const d = e.data
+  // Read before the kernel loads: loadCore() below is what prints, so a `quiet` arriving with the first message
+  //  (the warmup) has to take effect before that call, not after it.
+  if (d.quiet !== undefined) quiet = !!d.quiet
   try {
     // Asking for the painting must not be what LOADS the kernel. Every other command needs it, but if this worker
     //  has never loaded it then selector_prepare has never run either, so there is no painting to report — and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-slicer",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Browser/WASM 3D-printing slicer reverse-engineered from OrcaSlicer: slicing engine (Arachne walls, tree/grid supports, multi-material), React viewer with GPU toolpath preview, and schema-driven settings UI.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -21,6 +21,10 @@
       "types": "./types/worker.d.ts",
       "default": "./engine/src/slicer.worker.js"
     },
+    "./client": {
+      "types": "./types/client.d.ts",
+      "default": "./engine/src/client.js"
+    },
     "./wasm": {
       "types": "./types/wasm.d.ts",
       "default": "./engine/src/slicer_core.js"
@@ -56,10 +60,12 @@
     "./data/*": {
       "types": "./types/data/*.d.ts",
       "default": "./data/*"
-    }
+    },
+    "./package.json": "./package.json"
   },
+  "sideEffects": false,
   "scripts": {
-    "build": "node types/gen_settings_types.mjs && vite build --config components/vite.config.js && vite build --config viewer/vite.config.js && cp viewer/src/make_worker.js viewer/dist/make_worker.js",
+    "build": "node types/gen_settings_types.mjs && node types/gen_kernel_params.mjs && vite build --config components/vite.config.js && vite build --config viewer/vite.config.js && cp viewer/src/make_worker.js viewer/dist/make_worker.js",
     "check": "bash pack_check.sh"
   },
   "peerDependencies": {
@@ -67,6 +73,11 @@
     "react-dom": ">=18",
     "three": "^0.160.0"
   },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-dom": { "optional": true },
+    "three": { "optional": true }
+  },
   "devDependencies": {
     "typescript": "^5.6.0",
     "vite": "^5.4.11"
@@ -75,17 +86,16 @@
     "engine",
     "!engine/**/.omc",
     "types",
+    "!**/test_*.mjs",
+    "!types/gen_*.mjs",
     "components/dist",
     "viewer/dist",
     "viewer/styles.css",
     "components/styles.css",
-    "data/config-schema.json",
-    "data/ui-tree.json",
-    "data/toggle-rules.json",
-    "data/invalidation-map.json",
-    "data/printers.json",
-    "data/processes.js",
-    "data/filaments.js",
+    "data",
+    "!data/config-schema-builddump.json",
+    "!data/**/.omc",
+    "!data/printers/**",
     "README.md",
     "LICENSE.txt"
   ],

package/types/client.d.ts

@@ -0,0 +1,74 @@
+// three-slicer/client — promise wrapper over the worker protocol in three-slicer/worker.
+import type { SliceLayer, SliceResult } from '../engine/index.d.ts'
+import type { BrushArgs, PaintState, PaintTool } from './worker.d.ts'
+
+export type { BrushArgs, PaintState, PaintTool }
+
+export interface ClientSliceCallbacks {
+  onProgress?: (done: number, total: number) => void
+  /** Takes the layers yourself. With it set, the result carries stats only and nothing is buffered here. */
+  onLayer?: (layer: SliceLayer) => void
+}
+
+/** Painted facet counts. `counts` is present only when the call named states. */
+export interface PaintCounts {
+  /** State 1 — the support enforcer, and Extruder 1 */
+  enforcer: number
+  /** State 2 — the support blocker, and Extruder 2 */
+  blocker: number
+  counts?: Record<number, number>
+  /** Facets an importPaint actually applied */
+  applied?: number
+}
+
+export interface PaintOverlays {
+  enforcer: Float32Array
+  blocker: Float32Array
+  overlays?: Record<number, Float32Array>
+}
+
+export interface SlicerClient {
+  /** The worker being driven — for a host that also wants to listen in. */
+  worker: Worker
+
+  /** Load the kernel ahead of the first slice. */
+  warmup(): Promise<void>
+
+  /** `params` may be an object; it is stringified for you, which the raw protocol does not do. */
+  slice(stl: ArrayBuffer | Uint8Array, params: object | string, cb?: ClientSliceCallbacks): Promise<SliceResult>
+
+  /** Register a mesh for painting. `keepPaint` carries existing marks across a move; `kept` says whether they survived. */
+  prepare(stl: ArrayBuffer | Uint8Array, opts?: { keepPaint?: boolean }): Promise<{ facets: number; kept: boolean }>
+
+  paint(args: BrushArgs & {
+    state?: PaintState; enforcer?: boolean; tool?: PaintTool
+    angle?: number; cursor?: 'sphere' | 'circle'; states?: PaintState[]
+  }): Promise<PaintCounts>
+
+  /** Back to the default extruder. A separate call, not `paint` with state 0 — see three-slicer/worker. */
+  erase(args: BrushArgs & { tool?: PaintTool; angle?: number; states?: PaintState[] }): Promise<PaintCounts>
+
+  clear(states?: PaintState[]): Promise<PaintCounts>
+  overlay(states?: PaintState[]): Promise<PaintOverlays>
+
+  /** Load a 3mf's painting. Replaces every mark, so run it directly after `prepare`. */
+  importPaint(facets: Int32Array | number[], hex: string, states?: PaintState[]): Promise<PaintCounts>
+  exportPaint(): Promise<{ supported: boolean; facets: number[]; hex: string }>
+
+  /**
+   * Stop the running slice. Works while the worker is blocked in WASM, but the flag lives in a SharedArrayBuffer,
+   * so it exists only on the multithreaded kernel — a cross-origin-isolated page. Returns false when there is no
+   * flag to write; terminate the worker instead.
+   */
+  cancel(): boolean
+
+  /** Kill the worker and reject everything still in flight. */
+  terminate(): void
+}
+
+/**
+ * @param worker an existing worker to drive. Omitted, one is created — browser only, since Node has no global
+ *   `Worker`; in Node use `createSlicer()` from the root entry instead.
+ */
+export function createSlicerClient(worker?: Worker): SlicerClient
+export default createSlicerClient

package/types/components.d.ts

@@ -13,6 +13,16 @@ export interface SettingsPanelProps {
   embedded?: boolean
   /** Replace schema-driven widgets per key (e.g. `{ printable_area: MyBedEditor }`) */
   customWidgets?: Record<string, React.ComponentType<any>>
+  /**
+   * Pins the panel to one builder (optionally one page) and drops the search/group/page/mode chrome, so the form
+   * can be folded into another card. This is how `<Viewport/>`'s `motionPanel` slot is meant to be filled:
+   *
+   * ```jsx
+   * <SettingsPanel settings={settings} setSettings={setSettings} embedded
+   *                only={{ builder: 'TabPrinter::build_kinematics_page' }} />
+   * ```
+   */
+  only?: { builder: string; page?: string }
 }
 
 declare const SettingsPanel: React.FC<SettingsPanelProps>

package/types/data/preset-keys.json.d.ts

@@ -0,0 +1,20 @@
+// preset-keys.json — which option keys belong to which preset type, extracted from upstream's Preset.cpp
+// (`s_Preset_print_options`, `s_Preset_filament_options`, and printer_options() = printer + machine limits +
+// the per-extruder keys from PrintConfig.cpp).
+//
+// Distinct from printers.json's `keys`, which is the 21 columns the kernel reads: that is what a picker needs,
+// this is what writing a preset FILE another slicer will accept needs. Keys the config schema does not define are
+// dropped at extraction — every consumer coerces by schema type, so an untyped key could not be handled anyway.
+// Read it through `presetOptionKeys()` in three-slicer/settings rather than indexing this by hand.
+
+export interface PresetKeyLists {
+  /** Machine preset options — upstream's `Preset::printer_options()` */
+  printer: string[]
+  /** Print (process) preset options */
+  process: string[]
+  /** Filament preset options */
+  filament: string[]
+}
+
+declare const presetKeys: PresetKeyLists
+export default presetKeys

package/types/data/printers.json.d.ts

@@ -7,8 +7,8 @@
 /** A positional row aligned to `keys`; `null` where the profile chain never set that option. */
 export type PrinterRow = (unknown | null)[]
 
-/** `[nozzle diameter, index into sets, model name without the nozzle suffix]` */
-export type PrinterEntry = [string, number, string]
+/** `[nozzle diameter, index into sets, model name without the nozzle suffix, default process preset]` */
+export type PrinterEntry = [string, number, string, string]
 
 export interface PrinterData {
   /** Option keys, in column order — the same keys the settings panel edits */

package/types/data.d.ts

@@ -5,10 +5,12 @@ import type { UIPage } from './data/ui-tree.json.d.ts'
 import type { ToggleGroup } from './data/toggle-rules.json.d.ts'
 import type { InvalidationRule } from './data/invalidation-map.json.d.ts'
 import type { PrinterData, PrinterRow, PrinterEntry } from './data/printers.json.d.ts'
+import type { PresetKeyLists } from './data/preset-keys.json.d.ts'
 import type { ProcessData } from './data/processes.js.d.ts'
 import type { FilamentData, FilamentRow, FilamentEntry } from './data/filaments.js.d.ts'
 
 export type { ConfigOption, UIPage, ToggleGroup, InvalidationRule, PrinterData, PrinterRow, PrinterEntry }
+export type { PresetKeyLists }
 export type { ProcessData, FilamentData, FilamentRow, FilamentEntry }
 
 /** The 907 option definitions */
@@ -21,6 +23,8 @@ export const toggleRules: Record<string, ToggleGroup>
 export const invalidationMap: Record<string, InvalidationRule[]>
 /** Machine limits per printer, from the upstream vendor profiles */
 export const printers: PrinterData
+/** Which option keys belong to which preset type — read it through `presetOptionKeys()` */
+export const presetKeys: PresetKeyLists
 // The two large artifacts load on demand — read them through processPresets()/filamentPresets()
 // in three-slicer/settings rather than decoding the column layout here.
 export function loadProcesses(): Promise<ProcessData>

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
@@ -37,6 +38,86 @@ export function normalizeProjectSettings(raw: Record<string, unknown> | null | u
  */
 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 =