three-slicer 0.1.6 → 0.2.0

package/engine/examples/sla_headless.mjs

@@ -0,0 +1,51 @@
+// three-slicer SLA (resin) headless example: slice a cube with supports + pad through the public API,
+// then show the typed capability refusal — an unsupported request errors, it never approximates.
+//   run: node packages/engine/examples/sla_headless.mjs
+import { createSlicer } from 'three-slicer'
+import { deriveSlaParams, printerTechnology } from 'three-slicer/settings'
+
+// minimal binary-STL writer for a 10mm cube. Winding matters here, unlike the FFF example: the SLA
+//  support generator reads facet normals to find downward faces, so every face is CCW seen from outside.
+function boxSTL() {
+  const vertices = [[-5,-5,0],[5,-5,0],[5,5,0],[-5,5,0],[-5,-5,10],[5,-5,10],[5,5,10],[-5,5,10]]
+  const faces = [[0,2,1],[0,3,2],[4,5,6],[4,6,7],[0,1,5],[0,5,4],[1,2,6],[1,6,5],[2,3,7],[2,7,6],[3,0,4],[3,4,7]]
+  const buf = Buffer.alloc(84 + faces.length * 50)
+  buf.writeUInt32LE(faces.length, 80)
+  faces.forEach((face, i) => {
+    let off = 84 + i * 50 + 12
+    for (const vi of face) for (const v of vertices[vi]) { buf.writeFloatLE(v, off); off += 4 }
+  })
+  return buf
+}
+const cube = boxSTL()
+
+// A sparse settings map, the same shape the UI holds. printer_technology is what routes to slice_sla.
+const settings = {
+  printer_technology: 'SLA',
+  layer_height: 0.05,
+  exposure_time: 7,
+  supports_enable: true,
+  support_object_elevation: 5,
+  pad_enable: true,
+}
+console.log(`technology: ${printerTechnology(settings)}`)
+
+const slicer = await createSlicer()
+const params = deriveSlaParams(settings)     // fills display/support/pad defaults (SL1 reference machine)
+
+// (a) SLA slice — no G-code; masks, meshes and resin stats instead.
+const r = slicer.sliceSla(cube, params)
+if (r.error) { console.error('FAIL', r.error); process.exit(1) }
+console.log(`sla   : layers=${r.stats.layers} (lift=${r.stats.lift_layers}) points=${r.stats.support_points}`
+  + ` pad_layers=${r.stats.pad_layers} resin=${r.stats.resin_ml.toFixed(2)}ml`)
+console.log(`meshes: support=${r.support_mesh.length / 9} tris, pad=${r.pad_mesh.length / 9} tris`)
+
+// (b) the capability gate: hollowing is not ported, so the request is REFUSED with a stable code —
+//     a solid slice answered to a hollow request would be a mislabeled print.
+const refused = slicer.sliceSla(cube, deriveSlaParams({ ...settings, hollowing_enable: true }))
+console.log(`gate  : ${refused.error}`)
+
+if (r.stats.support_points > 0 && r.stats.pad_layers > 0 && /^SLA_UNSUPPORTED_HOLLOWING/.test(refused.error ?? ''))
+  console.log('OK — SLA slices headlessly via the public API')
+else { console.error('FAIL'); process.exit(1) }
+slicer.dispose()

package/engine/index.d.ts

@@ -6,22 +6,94 @@ export interface SliceCallbacks {
   onProgress?: (done: number, total: number) => void
   onLayer?: (layer: SliceLayer) => void
 }
+/** The estimator's machine limits, as they were actually applied (`stats.machine_limits`). */
+export interface SliceMachineLimits {
+  max_speed_xy: number; max_speed_z: number; max_speed_e: number
+  max_accel_xy: number; max_accel_z: number; max_accel_e: number
+  jerk_xy: number; jerk_z: number; jerk_e: number
+  accel_print: number; accel_travel: number; accel_retract: number
+}
+
 export interface SliceStats {
-  layers: number; model_layers: number; raft_layers: number;
-  path_segments: number; filament_mm: number; time_estimate: number;
-  streamed?: boolean; economy?: boolean; [k: string]: unknown
+  /** Emitted layers, raft included — the length of `result.layers` */
+  layers: number
+  /** Layers belonging to the model itself */
+  model_layers: number
+  raft_layers: number
+  path_segments: number
+  /** Filament consumed, mm of input filament */
+  filament_mm: number
+  /** Wall-crossing travels — the cross-check for `reduce_crossing_wall` */
+  wall_crossings: number
+
+  /** Seconds. `0` in economy mode, which skips the estimate */
+  time_estimate: number
+  first_layer_time: number
+  time_extrude: number
+  time_travel: number
+  /** Filament total the estimator parsed back out of the G-code — compare against `filament_mm` */
+  time_filament_mm: number
+  time_moves: number
+  /** Seconds per layer index */
+  layer_times: Record<string, number>
+  /** Seconds per extrusion role, keyed by the role number (the low nibble of `paths[k+3]`) */
+  role_times: Record<string, number>
+  /** Which estimator ran: the ported GCodeProcessor, the transcription, or neither */
+  time_engine: 'full' | 'transcribed' | 'fallback' | string
+  machine_limits: SliceMachineLimits
+
+  /** True when anything printed leaves the bed — support, skirt, brim and raft included */
+  over_bed: boolean
+  /** True when the MODEL itself is off the bed, not just what was printed around it */
+  over_bed_model: boolean
+  /** How far past the bed the toolpaths reach, mm. `0` = inside */
+  over_bed_x: number; over_bed_y: number
+  /** Emitted top layer past `printable_height`, mm */
+  over_bed_z: number
+
+  /** True when G-code and layers were delivered through `onLayer` and are NOT on the result */
+  streamed: boolean
+  /** True when it finished in economy mode: no preview toolpaths and no time estimate */
+  economy: boolean
+
+  // ---- multi-material only (absent from a single-material slice) ----
+  /** Indexed by tool number; sums to `filament_mm` */
+  filament_mm_by_tool?: number[]
+  /** The prime/wipe tower's share — already counted inside the per-tool figures above */
+  filament_mm_purge?: number
+  filament_mm_purge_by_tool?: number[]
+
+  // ---- phase timings, present when the kernel was built with them ----
+  t_pass1_ms?: number; t_surface_ms?: number; t_support_ms?: number; t_emit_ms?: number
+  /** The JS boundary's share during emit */
+  t_flush_ms?: number
+
+  [k: string]: unknown
+}
+
+export interface SliceResult {
+  /** Absent when `onLayer` was set — assemble it from the callback instead */
+  gcode?: string
+  stats: SliceStats
+  /** Absent when `onLayer` was set */
+  layers?: unknown[]
+  /** Set instead of a result when the slice failed or was cancelled (`'canceled'`) */
+  error?: string
 }
-export interface SliceResult { gcode?: string; stats: SliceStats; layers?: unknown[]; error?: string }
 export interface PaintArgs {
   facet: number; hx: number; hy: number; hz: number;
   cx: number; cy: number; cz: number; radius: number; enforcer: boolean
 }
 export interface Slicer {
   slice(stl: ArrayBuffer | Uint8Array, params: object | string, cb?: SliceCallbacks): SliceResult
+  /** SLA (resin) slice — no G-code: mask segment streams per layer, support/pad meshes, resin stats.
+   *  Params from deriveSlaParams(); a refused capability (e.g. hollowing) sets `error` to its typed code. */
+  sliceSla(stl: ArrayBuffer | Uint8Array, params: object | string, onProgress?: (done: number, total: number) => void): SliceResult
   paintPrepare(stl: ArrayBuffer | Uint8Array): number
   paint(args: PaintArgs): { enf: number; blk: number }
   paintClear(): void
-  overlay(enforcer: boolean): number[]
+  /** The painted overlay triangles for one state, as the kernel's own detached copy. */
+  overlay(enforcer: boolean): Float32Array
   heapSize(): number
   module: unknown
   dispose(): void

package/engine/index.js

@@ -1,8 +1,7 @@
 // three-slicer — browser/WASM 3D-slicing SDK (reverse-engineered from OrcaSlicer).
-// Public API. Node-safe (imports only the pure-JS WASM factory; no JSON so it loads in plain Node ESM).
+// Public API. Node-safe (loads only the pure-JS WASM factory; no JSON so it loads in plain Node ESM).
 // Schema-driven helpers (deriveKernelParams etc.) live in the "three-slicer/settings" subpath because
 // they import JSON — use them in a bundler (vite) or with Node JSON import attributes.
-import createModule from './src/slicer_core.js'
 
 const u8 = (b) => (b instanceof Uint8Array ? b : new Uint8Array(b))
 
@@ -21,7 +20,10 @@ export const engineWorkerURL = () => new URL('./src/slicer.worker.js', import.me
 //  paintPrepare/paint/paintClear/overlay: manual support enforcer/blocker painting (TriangleSelector).
 //  heapSize(): current WASM heap bytes (peak, monotonic). module: escape hatch. dispose(): drop the module.
 export async function createSlicer() {
-  const M = await createModule()
+  // Loaded here rather than at module scope so the 3.5MB emscripten glue is a separate chunk: a host that imports
+  //  this module only for engineWorkerURL() — the recommended browser path, where the kernel runs in the worker —
+  //  used to pull the whole thing into its bundle for a function that returns a URL.
+  const M = await (await import('./src/slicer_core.js')).default()
   return {
     slice(stl, params, { onProgress, onLayer } = {}) {
       const p = typeof params === 'string' ? params : JSON.stringify(params || {})
@@ -29,13 +31,22 @@ export async function createSlicer() {
       try { return M.slice(u8(stl), p, onProgress || (() => {})) }
       finally { if (onLayer) M.clear_layer_sink() }
     },
+    // SLA (resin) slice: no G-code — layers carry the mask segment stream, support_mesh/pad_mesh the preview
+    //  soups, stats the resin figures and lift_layers. Same params-object-or-string contract as slice().
+    sliceSla(stl, params, onProgress) {
+      const p = typeof params === 'string' ? params : JSON.stringify(params || {})
+      return M.slice_sla(u8(stl), p, onProgress || (() => {}))
+    },
     paintPrepare(stl) { M.selector_prepare(u8(stl)); return M.selector_facet_count() },
     paint(a) {
       M.selector_paint(a.facet, a.hx, a.hy, a.hz, a.cx, a.cy, a.cz, a.radius, a.enforcer)
       return { enf: M.selector_painted_count(true), blk: M.selector_painted_count(false) }
     },
     paintClear() { M.selector_clear() },
-    overlay(enforcer) { return Array.from(M.selector_overlay(!!enforcer)) },
+    // Returned as the kernel's own Float32Array. It is already a detached copy (bindings.cpp to_f32 slices the
+    //  memory view), and the Array.from() this used to do cost 1.1ms of a measured 3.6ms stroke on a 40k-triangle
+    //  mesh — the same conversion the worker dropped for the same reason (slicer.worker.js, 'overlay').
+    overlay(enforcer) { return M.selector_overlay(!!enforcer) },
     heapSize() { return M.heap_size() },
     module: M,
     dispose() { /* emscripten module is GC'd when dropped; no explicit teardown required */ },

package/engine/src/client.js

@@ -0,0 +1,165 @@
+// three-slicer/client — a promise wrapper over the slice worker's message protocol.
+//
+// Why it exists: the worker is the recommended way to slice in a browser (the kernel blocks its thread for
+// seconds), but driving it meant hand-writing a `cmd` string protocol, assembling the streamed layers, knowing
+// that a slice request is the one message with NO cmd and that its params must already be a JSON string, and
+// reaching into a SharedArrayBuffer at an offset the worker posts once to cancel anything. All of that lived in
+// the viewer and was not published.
+//
+// What it deliberately does NOT do: the viewer's progress weighting (its 15/5/40/40 phase budget is measured
+// against ITS models) and its out-of-memory retry ladder (re-slicing simplified, then in economy mode). Those are
+// UI policy — a host wanting them should own them, and lifting them here would make this a copy of the viewer.
+//
+// Requests are answered in order. The worker's onmessage handler processes one message at a time and each command
+// replies exactly once, so a FIFO of pending requests is enough to match a reply to its caller — the protocol
+// carries no request ids and does not need them.
+import { engineWorkerURL } from '../index.js'
+import { parseSlaJob, SlaRequestError } from './sla_request.js'
+
+export { SLA_CAPABILITIES, SLA_JOB_VERSION, SlaRequestError } from './sla_request.js'
+
+// Which reply type ends which command. A slice has no cmd (that is what selects slicing) and ends on 'done'.
+const REPLY_OF = {
+  warmup: 'warm', prepare: 'prepared', paint: 'painted', erase: 'painted', clear: 'painted',
+  importPaint: 'painted', exportPaint: 'paintExport', overlay: 'overlay', slice: 'done', sla: 'done',
+}
+
+const asBuffer = (data) => (data instanceof ArrayBuffer ? data : data?.buffer ?? data)
+const slaTransferables = (job) => job.objects.flatMap(object => [object, ...(object.modifierVolumes ?? [])])
+  .map(record => asBuffer(record.stl)).filter(buffer => buffer instanceof ArrayBuffer)
+
+/**
+ * @param {Worker} [worker] an existing worker to drive. Omit to create one — which only works in a browser,
+ *   since Node has no global Worker; a Node caller should use createSlicer() from the root entry instead.
+ */
+export function createSlicerClient(worker = new Worker(engineWorkerURL(), { type: 'module' })) {
+  const pending = []          // FIFO of {expect, resolve, reject, onProgress, onLayer, chunks, layers}
+  let cancelFlag = null       // Uint32Array over the worker's SharedArrayBuffer — mt kernel only
+  let closed = false
+
+  worker.addEventListener('message', ({ data }) => {
+    // Unprompted and not a reply to anything: the addresses of the progress counter and the cancel flag.
+    if (data.type === 'supsab') {
+      try { if (data.cancelPtr) cancelFlag = new Uint32Array(data.buf, data.cancelPtr, 1) } catch { /* not shared */ }
+      return
+    }
+    const head = pending[0]
+    if (!head) return
+    if (data.type === 'progress') { head.onProgress?.(data.done, data.total); return }
+    if (data.type === 'layer') {
+      head.onLayer?.({ z: data.z, idx: data.idx, gcode: data.gcode, paths: data.paths, widths: data.widths })
+      // Accumulated only when the caller did not take the layers itself — otherwise a streamed slice would hold
+      //  the whole model in memory here, which is the one thing streaming exists to avoid.
+      if (!head.onLayer) { if (data.gcode) head.chunks.push(data.gcode); head.layers.push(data) }
+      return
+    }
+    pending.shift()
+    if (data.type === 'error') {
+      head.reject(data.code ? new SlaRequestError(data.code, data.error) : new Error(data.error)); return
+    }
+    if (data.type !== head.expect) { head.reject(new Error(`expected '${head.expect}', got '${data.type}'`)); return }
+    // What the layer messages accumulated, if this caller did not take them itself.
+    if (data.type === 'done' && head.layers.length) data.assembled = { gcode: head.chunks.join(''), layers: head.layers }
+    head.resolve(data)
+  })
+  worker.addEventListener('error', (event) => {
+    const head = pending.shift()
+    head?.reject(new Error(event.message || 'worker failed'))
+  })
+
+  const send = (message, { transfer = [], onProgress, onLayer } = {}) => new Promise((resolve, reject) => {
+    if (closed) { reject(new Error('slicer client terminated')); return }
+    pending.push({ expect: REPLY_OF[message.cmd ?? 'slice'], resolve, reject, onProgress, onLayer, chunks: [], layers: [] })
+    worker.postMessage(message, transfer)
+  })
+
+  const brush = (cmd, args) => send({ ...args, cmd }).then(reply => ({
+    enforcer: reply.enf, blocker: reply.blk, counts: reply.counts, applied: reply.applied,
+  }))
+
+  return {
+    worker,
+
+    /** Load the kernel ahead of the first slice, so the first one is not also a 4MB download. */
+    warmup: () => send({ cmd: 'warmup' }).then(() => undefined),
+
+    /**
+     * Slice. `params` may be an object — it is stringified here, which the raw protocol does not do for you.
+     * With `onLayer` the layers are yours and the result carries stats only; without it they are assembled and
+     * the result looks like the direct handle's.
+     */
+    async slice(stl, params, { onProgress, onLayer } = {}) {
+      const buffer = asBuffer(stl)
+      const entry = { stl: buffer, params: typeof params === 'string' ? params : JSON.stringify(params ?? {}) }
+      const reply = await send(entry, { transfer: [buffer], onProgress, onLayer })
+      const result = reply.result ?? {}
+      // A streamed slice returns stats only, with the content delivered as `layer` messages. Unless the caller
+      //  took those itself, hand back the same shape a batch slice produces.
+      if (!reply.assembled) return result
+      return { ...result, gcode: reply.assembled.gcode, layers: reply.assembled.layers }
+    },
+
+    /**
+     * Legacy single-object SLA slice: per-layer closed contours instead of toolpaths. It uses WASM when available;
+     * its contour-only JS fallback rejects requested supports and pads. Same streaming shape as slice(): `onLayer` hands you the layers and the result
+     * carries stats only; without it they are assembled onto the result.
+     */
+    async sliceSla(stl, params, { onProgress, onLayer } = {}) {
+      const buffer = asBuffer(stl)
+      const entry = { cmd: 'sla', stl: buffer, params: typeof params === 'string' ? params : JSON.stringify(params ?? {}) }
+      const reply = await send(entry, { transfer: [buffer], onProgress, onLayer })
+      const result = reply.result ?? {}
+      if (!reply.assembled) return result
+      return { ...result, layers: reply.assembled.layers }
+    },
+
+    async sliceSlaJob(job, { onProgress, onLayer } = {}) {
+      const parsed = parseSlaJob(job)
+      const reply = await send({ cmd: 'slaJob', job: parsed }, { transfer: slaTransferables(parsed), onProgress, onLayer })
+      const result = reply.result ?? {}
+      if (!reply.assembled) return result
+      return { ...result, layers: reply.assembled.layers }
+    },
+
+    /** Register a mesh for painting. `keepPaint` carries existing marks across a move. */
+    prepare: (stl, { keepPaint = false } = {}) => {
+      const buffer = asBuffer(stl)
+      return send({ cmd: 'prepare', stl: buffer, keepPaint }, { transfer: [buffer] })
+        .then(reply => ({ facets: reply.facets, kept: reply.kept }))
+    },
+
+    /** Paint. `{state: 1..16}` addresses any extruder; `{enforcer: false}` is the legacy blocker brush. */
+    paint: (args) => brush('paint', args),
+    /** Return the brushed facets to the default extruder. Not `paint` with state 0 — see types/worker.d.ts. */
+    erase: (args) => brush('erase', args),
+    clear: (states) => brush('clear', states ? { states } : {}),
+
+    overlay: (states) => send({ cmd: 'overlay', ...(states ? { states } : {}) })
+      .then(reply => ({ enforcer: reply.enf, blocker: reply.blk, overlays: reply.overlays })),
+
+    /** Load a 3mf's painting. Replaces every mark, so run it directly after `prepare`. */
+    importPaint: (facets, hex, states) => brush('importPaint', { facets, hex, ...(states ? { states } : {}) }),
+    exportPaint: () => send({ cmd: 'exportPaint' })
+      .then(reply => ({ supported: reply.supported, facets: reply.facets, hex: reply.hex })),
+
+    /**
+     * Stop the running slice. The kernel polls this flag from inside its C++ loop, so it works while the worker
+     * is blocked in WASM — but the flag lives in a SharedArrayBuffer, so it exists only on the multithreaded
+     * kernel, i.e. on a cross-origin-isolated page. Returns false when there is nothing to write to; terminate
+     * the worker instead.
+     */
+    cancel() {
+      if (!cancelFlag) return false
+      try { Atomics.store(cancelFlag, 0, 1) } catch { cancelFlag[0] = 1 }
+      return true
+    },
+
+    terminate() {
+      closed = true
+      while (pending.length) pending.shift().reject(new Error('slicer client terminated'))
+      worker.terminate()
+    },
+  }
+}
+
+export default createSlicerClient

package/engine/src/data.js

@@ -11,6 +11,9 @@ export { default as uiTree } from 'three-slicer/data/ui-tree.json' with { type:
 export { default as toggleRules } from 'three-slicer/data/toggle-rules.json' with { type: 'json' }
 export { default as invalidationMap } from 'three-slicer/data/invalidation-map.json' with { type: 'json' }
 export { default as printers } from 'three-slicer/data/printers.json' with { type: 'json' }
+// Which option keys belong to which preset type, straight from upstream's Preset.cpp. Small (17KB) and needed by
+// anything that writes or reads a preset FILE, so it is static rather than lazy like the two big catalogs.
+export { default as presetKeys } from 'three-slicer/data/preset-keys.json' with { type: 'json' }
 // processes is the largest artifact (~800 KB) and is only needed once a printer is picked, so it stays a dynamic
 // import. It is generated as a JS module rather than JSON precisely because of the attribute problem above, in its
 // other direction: a dynamic JSON import needs the attribute in Node, and that same attribute makes browsers

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)