three-slicer 0.2.2 → 0.2.3

package/engine/index.d.ts

@@ -71,12 +71,38 @@ export interface SliceStats {
   [k: string]: unknown
 }
 
+/** A condition the slice SUCCEEDED with. `'over_bed_model'`: the model itself sliced outside the printable area. */
+export type SliceWarning = 'over_bed_model' | (string & {})
+
+/** How fast the slice ran. Derived at the call site; the `stats` phase timings are untouched. */
+export interface SliceThroughput {
+  /** Wall time around the slice call, ms — includes the STL crossing the WASM boundary and the layer stream */
+  ms: number
+  /** The kernel's own phase total (`t_pass1_ms` + surface + support + emit), or `null` if it reported none.
+   *  `ms - kernelMs` is the boundary cost. */
+  kernelMs: number | null
+  /** Emitted layers per second of wall time — the figure to show a person */
+  layersPerSecond: number
+  /** Milliseconds per million path segments, or `null` when nothing was emitted. The figure to COMPARE runs with:
+   *  the kernel is not deterministic in segment count (measured 15% apart on one input), so raw milliseconds
+   *  compare two different amounts of work. */
+  msPerMsegment: number | null
+}
+
 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[]
+  /**
+   * What the slice got away with, empty when nothing. Every entry restates a `stats` flag that is easy to miss
+   * among twenty numbers — an off-bed model slices with plausible time and material and no error — so check
+   * `result.warnings.length` once instead of learning which flags exist. Absent on a failed slice (see `error`).
+   */
+  warnings?: SliceWarning[]
+  /** How fast it ran. Absent on a failed slice (see `error`). */
+  throughput?: SliceThroughput
   /** Set instead of a result when the slice failed or was cancelled (`'canceled'`) */
   error?: string
 }

package/engine/index.js

@@ -3,10 +3,25 @@
 // 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 { withSliceWarnings } from './src/warnings.js'
+import { withSliceThroughput } from './src/throughput.js'
+
 const u8 = (b) => (b instanceof Uint8Array ? b : new Uint8Array(b))
 
-// Off-main-thread worker URL for the browser: `new Worker(engineWorkerURL(), { type: 'module' })`.
+// Off-main-thread worker URL for a NO-BUNDLER browser setup (native ESM, an import map, a CDN):
+// `new Worker(engineWorkerURL(), { type: 'module' })`. Under a bundler use `createSlicerClient()`
+// (three-slicer/client), which creates the worker through the static pattern bundlers recognize.
 // The worker speaks the stage-30 streaming protocol ({type:'layer'|'done'|'error'|'progress'}).
+//
+// This expression on its OWN is what a bundler reads as a plain asset reference: through 0.2.2 it is how the
+//  client built its default worker, and Vite copied slicer.worker.js into dist verbatim — measured on a Vite 5 app
+//  importing three-slicer/client and nothing else, a 21KB copy of the untouched source, still importing
+//  `./slicer_core.js`, `./slicer_core.mt.js`, `./sla_request.js` and `./sla_core.js` in a 40KB dist that held none
+//  of them. It 404s on the worker's first message, and only after `vite build`, since dev serves the sources.
+//  What fixed it is client.js creating the worker through the static `new Worker(new URL('literal', …))` pattern
+//  bundlers treat as a worker ENTRY. Once that entry exists this reference resolves onto the same chunk and emits
+//  nothing extra (verified: dist byte-identical with the path written here inline or held in a const), so it is
+//  harmless — but it is not what makes a bundled worker work. Leave it for the no-bundler callers.
 export const engineWorkerURL = () => new URL('./src/slicer.worker.js', import.meta.url)
 
 // createSlicer(): load the WASM kernel and return a handle. Works in Node and the browser main thread.
@@ -20,7 +35,7 @@ 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() {
-  // Loaded here rather than at module scope so the 3.5MB emscripten glue is a separate chunk: a host that imports
+  // Loaded here rather than at module scope so the ~4.8MB 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()
@@ -28,14 +43,19 @@ export async function createSlicer() {
     slice(stl, params, { onProgress, onLayer } = {}) {
       const p = typeof params === 'string' ? params : JSON.stringify(params || {})
       if (onLayer) M.set_layer_sink((z, idx, gcode, paths, widths) => onLayer({ z, idx, gcode, paths, widths }))
-      try { return M.slice(u8(stl), p, onProgress || (() => {})) }
+      // `warnings` names the conditions a slice can SUCCEED with (an off-bed model above all) — see src/warnings.js.
+      // `throughput` is measured HERE rather than derived from the kernel's phase timings, because the wall time a
+      //  caller feels includes the STL crossing the WASM boundary and the layer sink running on this side.
+      const started = performance.now()
+      try { return withSliceThroughput(withSliceWarnings(M.slice(u8(stl), p, onProgress || (() => {}))), performance.now() - started) }
       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 || (() => {}))
+      const started = performance.now()
+      return withSliceThroughput(M.slice_sla(u8(stl), p, onProgress || (() => {})), performance.now() - started)
     },
     paintPrepare(stl) { M.selector_prepare(u8(stl)); return M.selector_facet_count() },
     paint(a) {

package/engine/src/client.js

@@ -13,7 +13,6 @@
 // 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'
@@ -32,7 +31,14 @@ const slaTransferables = (job) => job.objects.flatMap(object => [object, ...(obj
  * @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' })) {
+// The default is written as the full `new Worker(new URL('literal', import.meta.url), { type: 'module' })`
+//  expression rather than through engineWorkerURL(), and that is the whole reason the no-argument form works
+//  after `vite build`. Bundlers recognize this exact shape as a worker ENTRY and emit it with its own chunk
+//  graph (the st/mt kernels it dynamically imports); split across a function call, the same file matched Vite's
+//  plain-asset rule instead and was copied verbatim, still importing an unhashed `./slicer_core.js` that dist
+//  did not contain — a 404 on the first message, visible only in a production build. Same reason the viewer
+//  keeps make_worker.js out of its own bundle. Do not factor this expression out.
+export function createSlicerClient(worker = new Worker(new URL('./slicer.worker.js', import.meta.url), { 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

package/engine/src/kernel_setting_keys.js

@@ -0,0 +1,132 @@
+// AUTO-GENERATED by types/gen_kernel_params.mjs — DO NOT EDIT.
+// The schema keys deriveKernelParams consumes (the distinct "From setting" column of engine/PARAMS.md).
+export const KERNEL_SETTING_KEYS = [
+  "bottom_shell_layers",
+  "bottom_surface_filament_id",
+  "bridge_no_support",
+  "bridge_speed",
+  "brim_object_gap",
+  "brim_width",
+  "close_fan_the_first_x_layers",
+  "default_acceleration",
+  "enable_arc_fitting",
+  "enable_pressure_advance",
+  "enable_prime_tower",
+  "enable_support",
+  "fan_max_speed",
+  "filament_cost",
+  "filament_density",
+  "filament_diameter",
+  "filament_flow_ratio",
+  "filament_map",
+  "filament_retraction_length",
+  "filament_retraction_minimum_travel",
+  "filament_retraction_speed",
+  "filament_settings_id",
+  "filament_type",
+  "filament_z_hop",
+  "flush_into_infill",
+  "flush_multiplier",
+  "flush_volumes_matrix",
+  "full_fan_speed_layer",
+  "hot_plate_temp",
+  "independent_support_layer_height",
+  "infill_direction",
+  "initial_layer_line_width",
+  "initial_layer_print_height",
+  "initial_layer_speed",
+  "inner_wall_filament_id",
+  "inner_wall_line_width",
+  "internal_solid_filament_id",
+  "internal_solid_infill_line_width",
+  "ironing_flow",
+  "ironing_spacing",
+  "ironing_speed",
+  "ironing_type",
+  "layer_height",
+  "line_width",
+  "machine_end_gcode",
+  "machine_max_acceleration_e",
+  "machine_max_acceleration_retracting",
+  "machine_max_acceleration_x",
+  "machine_max_acceleration_z",
+  "machine_max_jerk_e",
+  "machine_max_jerk_x",
+  "machine_max_jerk_z",
+  "machine_max_speed_e",
+  "machine_max_speed_x",
+  "machine_max_speed_z",
+  "machine_start_gcode",
+  "max_volumetric_extrusion_rate_slope",
+  "nozzle_diameter",
+  "nozzle_temperature",
+  "outer_wall_filament_id",
+  "outer_wall_line_width",
+  "outer_wall_speed",
+  "pressure_advance",
+  "prime_tower_width",
+  "prime_volume",
+  "printable_area",
+  "printable_height",
+  "raft_contact_distance",
+  "raft_expansion",
+  "raft_layers",
+  "reduce_crossing_wall",
+  "resolution",
+  "retraction_length",
+  "retraction_minimum_travel",
+  "retraction_speed",
+  "seam_position",
+  "seam_slope_type",
+  "skirt_distance",
+  "skirt_height",
+  "skirt_loops",
+  "slow_down_layer_time",
+  "sparse_infill_density",
+  "sparse_infill_filament_id",
+  "sparse_infill_line_width",
+  "sparse_infill_pattern",
+  "spiral_mode",
+  "support_angle",
+  "support_base_pattern",
+  "support_base_pattern_spacing",
+  "support_bottom_z_distance",
+  "support_expansion",
+  "support_filament",
+  "support_interface_bottom_layers",
+  "support_interface_filament",
+  "support_interface_pattern",
+  "support_interface_spacing",
+  "support_interface_top_layers",
+  "support_line_width",
+  "support_object_first_layer_gap",
+  "support_object_xy_distance",
+  "support_on_build_plate_only",
+  "support_remove_small_overhang",
+  "support_style",
+  "support_threshold_angle",
+  "support_threshold_overlap",
+  "support_top_z_distance",
+  "support_type",
+  "top_shell_layers",
+  "top_surface_filament_id",
+  "top_surface_line_width",
+  "travel_acceleration",
+  "travel_speed",
+  "tree_support_angle_slow",
+  "tree_support_branch_angle",
+  "tree_support_branch_angle_organic",
+  "tree_support_branch_diameter",
+  "tree_support_branch_diameter_angle",
+  "tree_support_branch_diameter_organic",
+  "tree_support_branch_distance",
+  "tree_support_branch_distance_organic",
+  "tree_support_tip_diameter",
+  "tree_support_top_rate",
+  "tree_support_wall_count",
+  "wall_generator",
+  "wall_loops",
+  "wipe_tower_x",
+  "wipe_tower_y",
+  "z_hop",
+]

package/engine/src/settings.js

@@ -23,7 +23,7 @@ const KERNEL_PATTERNS = ['rectilinear', 'grid', 'triangles', 'zigzag', 'gyroid',
 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).
+// The kernel reads 159 parameters (see the reference table in engine/PARAMS.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:
@@ -340,8 +340,13 @@ export function deriveKernelParams(settings, opts) {
   // Support style: schema enum (default/grid/snug/organic/tree_slim/tree_strong/tree_hybrid)
   //  -> kernel grid|tree|tree_lite. Since stage 18 the tree/organic family maps to the real organic TreeSupport ('tree',
   //  generate_tree_support_3D -> real type5 branch toolpaths); everything else maps to grid.
+  //  support_type participates too, as upstream's UI does: a tree(auto)/tree(manual) TYPE whose style is
+  //  still 'default' is a tree request — before this, an imported Orca project saved with tree(auto) and
+  //  the default style silently sliced grid. An explicit non-tree style keeps winning over the type.
   const styleRaw = String(S('support_style') ?? 'default')
-  const support_style = /tree|organic/i.test(styleRaw) ? 'tree' : 'grid'
+  const typeRaw = String(S('support_type') ?? 'normal(auto)')
+  const support_style =
+    /tree|organic/i.test(styleRaw) || (/tree/i.test(typeRaw) && styleRaw === 'default') ? 'tree' : 'grid'
 
   // Bed: bounding box of the first rectangle in printable_area
   const pa = settingRaw(settings, 'printable_area')
@@ -698,6 +703,35 @@ export function deriveSlaParams(settings) {
   }
 }
 
+// ---- Preset application -------------------------------------------------------------------------------------
+// The clear-then-merge every preset consumer needs and each demo used to rewrite: a preset carries only the
+// keys it sets, so merging one over another leaves the previous pick's leftovers underneath (an ABS chamber
+// temperature under a PLA pick). `keys` is the catalog's own key set (filaments.keys, processApi.keys,
+// printerKeys) — cleared first, so applying a material never disturbs a process pick and vice versa.
+// A null/undefined preset (a failed settingsFor lookup) applies NOTHING — the previous pick stays whole,
+// because half-clearing on a bad name would be worse than doing nothing.
+export function applyPreset(settings, preset, keys) {
+  if (!preset) return settings ?? {}
+  const next = { ...(settings ?? {}) }
+  for (const key of keys ?? []) delete next[key]
+  return Object.assign(next, preset)
+}
+
+// ---- Ignored-key reporting ----------------------------------------------------------------------------------
+// The FFF derivation consumes a curated key set (generated by probing — types/gen_kernel_params.mjs). Every
+// other key in a settings map is accepted and silently does nothing to a slice, which is exactly how a
+// support_type request once sliced grid with no warning. This is the inspection surface for that class:
+// which of MY map's keys does deriveKernelParams actually read?
+// Scope: the FFF kernel derivation ONLY. A key ignored here can still be real elsewhere — the SLA derivation
+// (slaSettingKeys), the viewer (enable_prime_tower, printable_area), or project metadata — so treat the
+// result as "has no effect on an FFF slice", not "useless".
+import { KERNEL_SETTING_KEYS } from './kernel_setting_keys.js'
+export const kernelSettingKeys = Object.freeze([...KERNEL_SETTING_KEYS])
+const KERNEL_SETTING_KEY_SET = new Set(KERNEL_SETTING_KEYS)
+export function ignoredKernelSettings(settings) {
+  return Object.keys(settings ?? {}).filter(key => !KERNEL_SETTING_KEY_SET.has(key)).sort()
+}
+
 // ---- 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.

package/engine/src/slicer.worker.js

@@ -16,6 +16,14 @@
 //  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.
 import { assertLegacySlaFallback, parseSlaJob } from './sla_request.js'
+import { withSliceWarnings } from './warnings.js'
+import { withSliceThroughput } from './throughput.js'
+
+// The kernel parses `params` as JSON text, so the raw protocol used to require a string — while the direct handle
+//  and createSlicerClient both take an object and stringify it for you. One object, two shapes, and the difference
+//  showed up only at the boundary. The worker now accepts either; the SLA branch always did, which is what made
+//  the split arbitrary rather than principled.
+const paramsText = (params) => (typeof params === 'string' ? params : JSON.stringify(params ?? {}))
 
 let quiet = false
 const say = (level, ...args) => { if (!quiet) console[level](...args) }
@@ -140,10 +148,11 @@ self.onmessage = async (e) => {
           self.postMessage({ type: 'layer', z, idx, gcode: '', paths, widths }, transfer)
         })
         let r
+        const started = performance.now()
         try { r = Kernel.slice_sla_job(job, onProgress) }
         finally { Kernel.clear_layer_sink() }
         if (r?.error) { self.postMessage({ type: 'error', error: String(r.error) }); return }
-        self.postMessage({ type: 'done', result: r }); return
+        self.postMessage({ type: 'done', result: withSliceThroughput(r, performance.now() - started) }); return
       }
       self.postMessage({ type: 'error', code: 'SLA_UNSUPPORTED_OBJECT_AWARE',
                         error: 'Object-aware SLA slicing requires WASM kernel support' })
@@ -153,7 +162,7 @@ self.onmessage = async (e) => {
     //  the same layer-sink streaming a kernel slice uses. The pure-JS contour slicer (sla_core.js) stays as the
     //  fallback for a loaded kernel that predates the binding — it produces the same stream, minus the supports.
     if (d.cmd === 'sla') {
-      const params = typeof d.params === 'string' ? d.params : JSON.stringify(d.params ?? {})
+      const params = paramsText(d.params)
       if (!modPromise) modPromise = loadCore()
       const Kernel = await modPromise
       const onProgress = (done, total) => self.postMessage({ type: 'progress', done, total })
@@ -165,15 +174,19 @@ self.onmessage = async (e) => {
           self.postMessage({ type: 'layer', z, idx, gcode: '', paths, widths }, transfer)
         })
         let r
+        const started = performance.now()
         try { r = Kernel.slice_sla(new Uint8Array(d.stl), params, onProgress) }
         finally { Kernel.clear_layer_sink() }
         if (r && r.error) { self.postMessage({ type: 'error', error: String(r.error) }); return }
-        self.postMessage({ type: 'done', result: r })
+        self.postMessage({ type: 'done', result: withSliceThroughput(r, performance.now() - started) })
         return
       }
       const { sliceSla } = await import('./sla_core.js')
       const fallbackParams = JSON.parse(params)
       assertLegacySlaFallback(fallbackParams)
+      // The JS fallback reports no phase timings at all, so its `kernelMs` comes back null rather than 0 — the
+      //  wall time and the two rates are still the honest figures for what it did.
+      const startedFallback = performance.now()
       const r = sliceSla(new Uint8Array(d.stl), fallbackParams, {
         onProgress,
         onLayer: (L) => {
@@ -184,7 +197,7 @@ self.onmessage = async (e) => {
         },
       })
       if (r && r.error) { self.postMessage({ type: 'error', error: String(r.error) }); return }
-      self.postMessage({ type: 'done', result: r })
+      self.postMessage({ type: 'done', result: withSliceThroughput(r, performance.now() - startedFallback) })
       return
     }
     if (!modPromise) modPromise = loadCore()
@@ -302,11 +315,17 @@ self.onmessage = async (e) => {
       self.postMessage({ type: 'layer', z, idx, gcode, paths, widths }, transfer)
     })
     let r
-    try { r = Module.slice(new Uint8Array(d.stl), d.params, onProgress) }
+    // Timed around the kernel call INCLUDING the layer sink, which posts each layer to the main thread from inside
+    //  it — that transfer is part of what a streamed slice costs and leaving it out would flatter the number.
+    const started = performance.now()
+    try { r = Module.slice(new Uint8Array(d.stl), paramsText(d.params), onProgress) }
     finally { Module.clear_layer_sink() }
     if (r && r.error) { self.postMessage({ type: 'error', error: String(r.error) }); return }
     // streamed=true -> g-code/layers were already emitted as 'layer' (result holds stats only). batch/MM keep them in result.
-    self.postMessage({ type: 'done', result: r })
+    // withSliceWarnings names what the slice got away with (an off-bed model) on the result itself, and
+    //  withSliceThroughput how fast it ran — the raw protocol carries both, so createSlicerClient's callers get
+    //  them without the client having to re-derive anything.
+    self.postMessage({ type: 'done', result: withSliceThroughput(withSliceWarnings(r), performance.now() - started) })
   } catch (err) {
     // Includes the WASM abort("memory access out of bounds") — the main thread's OOM ladder decides on re-creation / economy retry.
     self.postMessage({ type: 'error', error: String((err && err.message) || err), ...(err?.code ? { code: err.code } : {}) })

package/engine/src/throughput.js

@@ -0,0 +1,53 @@
+// How fast the slice actually ran.
+//
+// The kernel already times its own phases (`t_pass1_ms`, `t_surface_ms`, `t_support_ms`, `t_emit_ms` — set
+// unconditionally in finish.cpp), but a phase breakdown is a profiling tool, not an answer to "how fast is this".
+// The wall time around the call is, and only the caller can measure it: it includes the STL crossing the WASM
+// boundary and, in the worker, the layer stream leaving it.
+//
+// `msPerMsegment` is the field to compare runs with, and it is not decoration. The kernel is not deterministic in
+// segment COUNT — the same input has been measured 15% apart between runs — so a raw millisecond figure compares
+// two different amounts of work and reads as a regression that is not there. Normalizing by the work done is what
+// makes two numbers comparable; `layersPerSecond` is the one to show a person, since layers are what a progress
+// bar counts.
+//
+// Everything here is derived. Nothing replaces or renames a `stats` field.
+
+// The two technologies time entirely different passes, and only the CONSECUTIVE ones may be summed.
+//  FFF: pass1 -> surfaces -> support -> emit (finish.cpp).
+//  SLA: contours -> sample -> tree -> raster -> emit (slice_sla.cpp). Its `t_sample_*` and `t_raster_*` keys are
+//   nested INSIDE t_sample_ms / t_raster_ms — the C++ says so at each set() — so adding them would double-count.
+//  `t_emit_ms` is the one name both use, which is exactly why the FFF list cannot be applied to an SLA result:
+//   it would find that single key, sum it alone, and report the emit pass as the whole kernel time.
+const FFF_PHASES = ['t_pass1_ms', 't_surface_ms', 't_support_ms', 't_emit_ms']
+const SLA_PHASES = ['t_contours_ms', 't_sample_ms', 't_tree_ms', 't_raster_ms', 't_emit_ms']
+
+/**
+ * @param {object} [stats] the slice result's `stats`
+ * @param {number} wallMs wall time around the slice call, ms
+ */
+export function sliceThroughput(stats, wallMs) {
+  const ms = Math.max(0, Number(wallMs) || 0)
+  const layers = Number(stats?.layers) || 0
+  // SLA counts mask segments here rather than toolpath segments, which is the same thing for this purpose: the
+  //  amount of geometry the run actually produced, so the normalized figure stays comparable within a technology.
+  const segments = Number(stats?.path_segments) || 0
+  // The kernel's own total, when it reported its phases — always smaller than `ms`, and the gap is the boundary
+  //  cost (STL upload, the layer stream, the JS sink). Worth having side by side: a slice that is slow only in
+  //  the gap is a marshalling problem, not a slicing one.
+  const phases = (stats?.sla ? SLA_PHASES : FFF_PHASES)
+    .map(key => Number(stats?.[key])).filter(Number.isFinite)
+  return {
+    ms,
+    kernelMs: phases.length ? phases.reduce((sum, value) => sum + value, 0) : null,
+    layersPerSecond: ms > 0 ? (layers * 1000) / ms : 0,
+    // Null rather than 0 when there is nothing to normalize against: 0 ms/Mseg would read as infinitely fast.
+    msPerMsegment: segments > 0 ? ms / (segments / 1e6) : null,
+  }
+}
+
+/** Attaches `throughput` to a slice result in place and returns it. */
+export function withSliceThroughput(result, wallMs) {
+  if (result && !result.error) result.throughput = sliceThroughput(result.stats, wallMs)
+  return result
+}

package/engine/src/warnings.js

@@ -0,0 +1,23 @@
+// Result-level warnings — the slices that succeed while being wrong.
+//
+// The kernel reports an off-bed model as one flag among twenty stats numbers (`over_bed_model`), which a consumer
+// only finds by already knowing it exists: a bed-centred model handed in without the plate-local subtraction slices
+// at X 234.7–265.4 on a 250mm bed with plausible time and material and no error (examples/DEMOS.md §4.5). All four
+// demos ended up writing the same `if (result.stats.over_bed_model) throw` line. Naming the whole set on the result
+// lets a host surface or log every such condition without knowing which flags the kernel happens to carry.
+//
+// Warnings are strings, and the array is always present so `result.warnings.length` needs no guard. The stats flags
+// stay exactly where they were — this is an additional view of them, not a replacement.
+
+/** @param {object} [stats] a slice result's `stats` @returns {string[]} */
+export function sliceWarnings(stats) {
+  const warnings = []
+  if (stats?.over_bed_model) warnings.push('over_bed_model')
+  return warnings
+}
+
+/** Attaches `warnings` to a slice result in place (the result is a fresh object per slice) and returns it. */
+export function withSliceWarnings(result) {
+  if (result && !result.error) result.warnings = sliceWarnings(result.stats)
+  return result
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-slicer",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Browser/WASM 3D-printing slicer reverse-engineered from OrcaSlicer: slicing engine (Arachne walls, tree/grid supports, multi-material), SLA resin slicing with PrusaSlicer's ported support/pad chain and .sl1 export, React viewer with GPU toolpath preview, and schema-driven settings UI.",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/types/settings.d.ts

@@ -19,6 +19,26 @@ export function settingScalar(settings: SlicerSettings | null | undefined, key:
  */
 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'
 

package/types/viewer.d.ts

@@ -52,6 +52,37 @@ export interface ViewportProps {
    * 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 }>
+  /**
+   * 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
   /**
@@ -62,7 +93,12 @@ export interface ViewportProps {
   /** 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. */
-  onSliced?: (result: { plate: number; stats: Record<string, unknown>; gcode: string }) => void
+  /** `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
 }
 
 /**
@@ -97,6 +133,9 @@ export type LockablePanel =
 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. */
@@ -115,10 +154,20 @@ export type ViewportEvent =
   | { 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 }
 

package/types/worker.d.ts

@@ -65,11 +65,12 @@ export type SlicerRequest =
   | { cmd: 'slaJob'; job: SlaJob }
   /**
    * Slice — and note it carries **no `cmd`**: slicing is the worker's default action, and leaving the field off
-   * is what selects it. `params` must be a JSON **string**; the worker hands it straight to the kernel, which
-   * parses JSON text. (`createSlicer().slice()` on the direct handle also accepts an object and stringifies it.)
+   * is what selects it. `params` accepts a JSON string or an object; the kernel parses JSON text, so an object is
+   * stringified for you (it was string-only through 0.2.2, which made this the one call path with a different
+   * contract from `createSlicer().slice()` and `createSlicerClient().slice()`).
    * Replies: `progress` and `layer` while it runs, then `done` — or `error`.
    */
-  | { stl: ArrayBuffer; params: string }
+  | { stl: ArrayBuffer; params: string | object }
 
 export type SlicerResponse =
   | { type: 'warm' }