three-slicer 0.2.2 → 0.2.4

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'
@@ -22,6 +21,7 @@ export { SLA_CAPABILITIES, SLA_JOB_VERSION, SlaRequestError } from './sla_reques
 const REPLY_OF = {
   warmup: 'warm', prepare: 'prepared', paint: 'painted', erase: 'painted', clear: 'painted',
   importPaint: 'painted', exportPaint: 'paintExport', overlay: 'overlay', slice: 'done', sla: 'done',
+  fillPreview: 'fillPreview', paintMode: 'paintMode',
 }
 
 const asBuffer = (data) => (data instanceof ArrayBuffer ? data : data?.buffer ?? data)
@@ -32,7 +32,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
@@ -137,6 +144,14 @@ export function createSlicerClient(worker = new Worker(engineWorkerURL(), { type
     overlay: (states) => send({ cmd: 'overlay', ...(states ? { states } : {}) })
       .then(reply => ({ enforcer: reply.enf, blocker: reply.blk, overlays: reply.overlays })),
 
+    /** What a fill would select under `{tool, facet, hx, hy, hz, angle}`, without applying it. `{clear:true}`
+     *  drops the standing selection. `supported` is false on a kernel built before the preview existed. */
+    fillPreview: (args) => send({ cmd: 'fillPreview', ...args })
+      .then(reply => ({ supported: reply.supported, triangles: reply.tris })),
+    /** Brush-wide options: `{overhangDeg}` restricts every stroke to overhangs (0 = off), `{clipPlane:[nx,ny,nz,d]}`
+     *  sets the section plane every cursor clips against (null turns it off). */
+    paintMode: (args) => send({ cmd: 'paintMode', ...args }).then(() => undefined),
+
     /** 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' })

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) }
@@ -87,6 +95,16 @@ const cursorShapeOf = (message) => (message.cursor === 'circle' ? 1 : 0)
 //  a radius or a camera: what they select comes from the mesh's own topology, which is why they are a branch rather
 //  than more optional fields on the brush call. `state === null` means erase (the entry points with no state
 //  argument), matching how the brush splits paint from erase.
+// The previous sample of the current stroke, when the message carries one. Upstream paints the CAPSULE between two
+//  consecutive mouse positions (DoublePointCursor, GLGizmoPainterBase.cpp:878) — a pointer stream is sampled, not
+//  continuous, so a ball per sample leaves a fast drag as a row of blobs with gaps between them. Optional on the
+//  wire and feature-detected on the kernel, so a caller or a build without it keeps painting single points.
+const strokeFrom = (message) =>
+  Number.isFinite(message.px) && Number.isFinite(message.py) && Number.isFinite(message.pz)
+
+// The fill modes the kernel's fill_preview takes (selector_bridge.h FILL_*), by the tool name the protocol uses.
+const FILL_PREVIEW_MODE = { smart: 0, bucket: 1, triangle: 2 }
+
 const FILL_TOOLS = new Set(['smart', 'bucket', 'triangle'])
 const applyFill = (Module, message, state) => {
   const angle = Number.isFinite(message.angle) ? message.angle : 30
@@ -140,10 +158,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 +172,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 +184,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 +207,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()
@@ -211,6 +234,8 @@ self.onmessage = async (e) => {
         applyFill(Module, d, paintedState)
       }
       else if (paintedState === null) Module.selector_paint(d.facet, d.hx, d.hy, d.hz, d.cx, d.cy, d.cz, d.radius, d.enforcer)
+      else if (strokeFrom(d) && Module.selector_paint_stroke)
+        Module.selector_paint_stroke(d.facet, d.px, d.py, d.pz, d.hx, d.hy, d.hz, d.cx, d.cy, d.cz, d.radius, paintedState, cursorShapeOf(d))
       else Module.selector_paint_shape(d.facet, d.hx, d.hy, d.hz, d.cx, d.cy, d.cz, d.radius, paintedState, cursorShapeOf(d))
       self.postMessage(paintedReply(Module, d, paintedState)); return
     }
@@ -223,6 +248,11 @@ self.onmessage = async (e) => {
     //  change to the same counts, and the viewer's listeners must not need to know which brush produced it.
     if (d.cmd === 'erase')   {
       if (FILL_TOOLS.has(d.tool)) applyFill(Module, d, null)
+      else if (strokeFrom(d) && Module.selector_erase_stroke)
+        Module.selector_erase_stroke(d.facet, d.px, d.py, d.pz, d.hx, d.hy, d.hz, d.cx, d.cy, d.cz, d.radius, cursorShapeOf(d))
+      // The eraser gets the cursor shape too, or a shift+drag with the circle brush rubs out the far side of a wall
+      //  the paint brush never touched. `selector_erase` (no shape) stays the fallback for an older kernel.
+      else if (Module.selector_erase_shape) Module.selector_erase_shape(d.facet, d.hx, d.hy, d.hz, d.cx, d.cy, d.cz, d.radius, cursorShapeOf(d))
       else Module.selector_erase(d.facet, d.hx, d.hy, d.hz, d.cx, d.cy, d.cz, d.radius)
       self.postMessage(paintedReply(Module, d, null)); return
     }
@@ -279,6 +309,34 @@ self.onmessage = async (e) => {
       self.postMessage(reply, transfer); return
     }
 
+    // fillPreview: what a fill WOULD select, without applying it. Upstream runs this on every mouse move while a
+    //  fill tool is active and draws the result in a lighter shade (GLGizmoPainterBase.cpp:929) — a preview marks
+    //  nothing, so it needs no state at all and there is no NONE for a stray boolean to become. `{clear:true}`
+    //  drops the standing selection, which is what leaving the model under the pointer means.
+    if (d.cmd === 'fillPreview') {
+      if (!Module.selector_fill_preview) { self.postMessage({ type: 'fillPreview', supported: false, tris: EMPTY_OVERLAY }); return }
+      if (d.clear) { Module.selector_fill_preview_clear(); self.postMessage({ type: 'fillPreview', supported: true, tris: EMPTY_OVERLAY }); return }
+      const angle = Number.isFinite(d.angle) ? d.angle : 30
+      const mode = FILL_PREVIEW_MODE[d.tool] ?? FILL_PREVIEW_MODE.smart
+      // Upstream's -1 for the non-propagating case, the same value applyFill sends: one facet has no neighbour to
+      //  measure an angle against.
+      const tris = Module.selector_fill_preview(d.facet, d.hx, d.hy, d.hz, mode === FILL_PREVIEW_MODE.triangle ? -1 : angle, mode)
+      self.postMessage({ type: 'fillPreview', supported: true, tris },
+                       tris?.buffer && tris.byteLength > 0 ? [tris.buffer] : [])
+      return
+    }
+    // paintMode: the brush-wide options upstream keeps on the gizmo — the overhang restriction and the section
+    //  plane. Both are set once and read by every stroke, so they are their own command rather than fields on one.
+    if (d.cmd === 'paintMode') {
+      if (Number.isFinite(d.overhangDeg) && Module.selector_set_overhang_limit) Module.selector_set_overhang_limit(d.overhangDeg)
+      if (Module.selector_set_clip_plane) {
+        const plane = d.clipPlane
+        if (plane) Module.selector_set_clip_plane(plane[0], plane[1], plane[2], plane[3], true)
+        else if (d.clipPlane === null) Module.selector_set_clip_plane(0, 0, 1, 0, false)
+      }
+      self.postMessage({ type: 'paintMode', ok: true }); return
+    }
+
     if (d.stall) return   // stage-30 test hook: simulate a hang -> verifies the main-thread watchdog fires (not set in production)
     // mt (SAB): share the address of the real support progress counter (u32) with main once — even while the kernel is
     //  blocked inside C++, the UI thread polls the SAB directly to show support progress. st (non-shared buffer) is unsupported -> not sent.
@@ -302,11 +360,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.4",
   "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/.omc/state/sessions/02e5ddf5-4378-46e1-8fca-e90412c30804/pre-tool-advisory-throttle.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "entries": {
+    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
+      "last_emitted_at_ms": 1788437194779,
+      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
+    }
+  },
+  "updated_at": "2026-09-03T12:06:34.779Z"
+}

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'