three-slicer 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 0.2.3 — 2026-08-29
+
+A developer-experience release: everything here comes from a log of what integrating the package actually
+cost while building the four `examples/` demos and the live landing embed (`packages/FRICTION.md`). The
+theme is the one failure mode they shared — wrong input returning something plausible instead of an error.
+
+### Added
+
+- `sliceRequest` on `<Viewport/>`: a token whose identity change requests one slice. The component's
+  contract stays props-only, but a host that hides the built-in chrome no longer has to remount the whole
+  viewer to start a slice (which blanked the scene and re-parsed the model — measured as a visible
+  double-flip on the landing embed).
+- `result.warnings`, a `string[]` naming what a **successful** slice got away with. Today's one entry is
+  `'over_bed_model'`: a bed-centred model sliced outside the printable area with plausible time and
+  material and no error. Present on the direct handle, through `createSlicerClient()`, and on the raw
+  worker's `done` reply. The `stats` flags are unchanged.
+- `result.throughput` — how fast the slice ran: `ms` (wall time around the call), `kernelMs` (the kernel's own
+  phase total, so `ms - kernelMs` is the WASM boundary cost), `layersPerSecond`, and `msPerMsegment`. The last
+  one is the field to compare runs with: the kernel is not deterministic in segment count, so raw milliseconds
+  compare two different amounts of work. Same three paths as `warnings`, and on the SLA routes as well —
+  `kernelMs` there sums the resin passes (contours, sample, tree, raster, emit), since the two technologies
+  share only the name `t_emit_ms`.
+- Throughput in the viewer, in three places: the slice bar shows layers/second **while** a slice runs, the stats
+  card shows the finished figure ("Sliced in 4.0s · 166 layers/s", with the kernel share and ms/Msegment on the
+  tooltip), and hosts receive both — `sliceRate` on `onEvent` and `throughput` beside `stats` on `onSliced`.
+  An SLA slice reports the live figure throughout; an FFF slice reports it once the emission pass starts
+  streaming layers, since its earlier passes publish no per-layer progress and none is invented. It therefore
+  reads higher than the whole-slice average, which counts the passes that emit nothing (measured on a 38MB
+  model: 306–707 layers/s live, 166 over the whole 4.0s slice).
+- `applyPreset(settings, preset, keys)` in `three-slicer/settings` — clear-then-merge, so a preset switch
+  cannot leave the previous material's keys underneath. All four demos had written this by hand.
+- `kernelSettingKeys` and `ignoredKernelSettings(settings)`: the 128 schema keys the FFF derivation reads,
+  and which of yours it does not. A key it does not read is accepted and does nothing.
+- The raw worker's slice request accepts an object `params`, not only a JSON string — the direct handle
+  and the client already did, and the worker's own SLA branch always had.
+
+### Fixed
+
+- The prime tower stand-in is drawn only when the plate actually changes tools — objects on more than one
+  extruder, or material paint reaching extruder 2 or higher — instead of whenever a second filament happened to
+  be loaded. With everything on T1 the slice emits no tool change and generates no tower, so the box promised
+  one that would not be printed.
+- The viewer no longer shows a slice result that the current settings would not produce. A change to `settings`
+  drops the cached results and returns to Prepare, instead of leaving a preview, a print estimate and an enabled
+  G-code export describing the settings the slice ran with. An injected (`gcode` / `sl1`) plate and an opened
+  `.sl1` archive are left alone — neither claims to be a slice of these settings.
+- **`createSlicerClient()` with no argument now works after `vite build`.** Its default worker is written
+  as the literal `new Worker(new URL(…), { type: 'module' })` that bundlers recognize as a worker entry;
+  routed through `engineWorkerURL()` it matched Vite's plain-asset rule instead and was copied verbatim,
+  still importing an unhashed `./slicer_core.js` that the build never emitted — a 404 on the first message,
+  invisible until a production build. Measured on a Vite 5 consumer: a 21KB copy in a 40KB dist with no
+  kernel at all, versus a 12KB worker chunk importing the emitted kernels. `pack_check.sh` now fails when
+  a worker chunk imports a file the build did not produce.
+- `support_type: 'tree(auto)'` selects tree supports. Tree vs grid was routed from `support_style` alone,
+  so an imported OrcaSlicer project asking for tree supports sliced grid, silently.
+- A `files` prop changed after mount warns once instead of being ignored in silence.
+
+### Changed
+
+- `engineWorkerURL()` is documented as the **no-bundler** path (native ESM, an import map, a CDN). Under
+  Vite or webpack use `createSlicerClient()` or `three-slicer/worker?worker`. The function is unchanged.
+- Since tree vs grid now reads `support_type`, a settings map carrying `support_type: 'tree(auto)'` with
+  `support_style: 'default'` produces different G-code than it did in 0.2.2 — tree, as upstream does.
+
+## 0.2.2 — 2026-08-22
+
+### Added
+
+- SL1 import in the viewer: an `.sl1` archive opens through the file picker, drag & drop, or the new `files`
+  prop — rendered as a raster preview, with the model shape reconstructed from the masks in the background
+  (two passes: a coarse mesh in under a second, then full resolution). This viewer's own exports carry scene
+  and role sidecars, so reopening one shows the exported surface itself, in the sliced preview's colours, and
+  re-exports byte-identical. Opening an `.sl1` applies the archive's job description to the settings
+  (`printer_technology` first), so a fresh FFF session switches to the SLA route.
+- SL1 export: role/scene sidecar members, off-thread mask encoding, and a save window.
+- Move scrub in Preview: a horizontal slider that walks the top layer move by move with a screen-fixed nozzle
+  marker — upstream's sequential view. Position changes reach the host as the `moveScrub` event.
+- `files` and `sl1` Viewport props: models, `.3mf` projects, `.sl1` archives and preset files handed in once
+  at mount.
+
+### Fixed
+
+- The SLA print area is the resin display size, not `printable_area`.
+
+## 0.2.1 — 2026-08-21
+
+### Added
+
+- `pad_around_object` (embed) is now supported in the SLA path — the `SLA_PAD_AROUND_OBJECT_UNSUPPORTED`
+  capability gate is gone. It forces zero elevation (upstream `is_zero_elevation`), and an empty embed pad is
+  legal: the ring survives only where supports stand.
+
+### Performance
+
+- SLA slicing: the raster fallback was rewritten, and slicing/prepare run layer-parallel on the multithreaded
+  kernel — byte-identical output, with progress bands matched to measured time.
+
 ## 0.2.0 — 2026-08-19
 
 SLA (resin) printing lands as a second technology in the same kernel, routed by `printer_technology`.

package/README.md

@@ -12,6 +12,20 @@ The package is published as a single npm package, `three-slicer`, with subpath e
 - Source: [kimgh06/Web_Three_Slicer](https://github.com/kimgh06/Web_Three_Slicer)
 - Demo: [slicer.kimgh06.com](https://slicer.kimgh06.com/)
 
+## Start Here
+
+Three ways in — pick the row that is your case. Each path is a working code block plus the one doc worth
+reading whole; everything else is lookup.
+
+| Your case | Path | Copy this | Then read |
+| --- | --- | --- | --- |
+| "Just the numbers" — quotes, farms, automation. No UI, no React | **Headless** | [Quick Start: Headless Slicing](#quick-start-headless-slicing) | [engine/README](engine/README.md) (134 lines), params via [PARAMS.md](engine/PARAMS.md) as lookup |
+| A slicer inside your existing page | **Embed** | [Quick Start: React Viewer](#quick-start-react-viewer) | [viewer/README](viewer/README.md) (330 lines — the props contracts live there) |
+| The full slicer UI — viewport + settings panel | **Full UI** | [Full React Example](#full-react-example) | viewer/README + [components/README](components/README.md) |
+
+Whichever path: read [Before You Ship](#before-you-ship) before deploying — those traps return plausible
+results instead of errors, and the first two never show up in `npm run dev`.
+
 ## Features
 
 - WASM slicing engine with Arachne walls, infill patterns, supports, raft/brim/skirt, ironing, arc fitting, multi-material paths, and layer streaming.
@@ -23,7 +37,9 @@ The package is published as a single npm package, `three-slicer`, with subpath e
 - Support painting and material painting, plus per-tool filament and purge statistics.
 - 3MF **project** import in the viewer: a slicer-written `.3mf` (OrcaSlicer/BambuStudio save, MakerWorld download) restores its plate layout, project settings, and painted facets — not just the meshes.
 - Extracted data files for custom UIs: config schema, UI tree, toggle rules, invalidation map, and the printer/process/filament catalogs.
-- SLA (resin) slicing: PrusaSlicer 2.9.6's ported support-point generator, support tree and pad, a resin material catalog, and `.sl1` mask export — routed by `printer_technology`, with typed capability errors for what the port does not cover.
+- SLA (resin) slicing: PrusaSlicer 2.9.6's ported support-point generator, support tree and pad, a resin material catalog, and `.sl1` mask export *and import* — routed by `printer_technology`, with typed capability errors for what the port does not cover.
+- Preview move scrub: a position slider with a nozzle marker that walks the toolpath inside a layer (upstream's sequential view).
+- Host injection props on the viewer: `files` hands models, `.3mf` projects, `.sl1` archives and preset files in at mount; `gcode` injects a sliced result for preview-only use.
 - Automatic multithreaded WASM selection on cross-origin-isolated browser pages.
 
 ## Installation
@@ -42,8 +58,8 @@ npm i three-slicer react react-dom three
 
 | Import path | Needs react/three |
 | --- | --- |
-| `three-slicer`, `/settings`, `/toggle`, `/client`, `/worker`, `/wasm`, `/data` | no |
-| `three-slicer/viewer`, `/viewer/toolpath`, `/viewer/loaders`, `/viewer/gcode` | yes |
+| `three-slicer`, `/settings`, `/toggle`, `/client`, `/worker`, `/wasm`, `/data`, `/viewer/gcode`, `/viewer/toolpath` | no — `makeToolpath(THREE, data)` takes `three` as an argument |
+| `three-slicer/viewer`, `/viewer/loaders` | yes |
 | `three-slicer/components` | react only |
 
 ## Quick Start: Headless Slicing
@@ -71,12 +87,37 @@ console.log(result.gcode)
 slicer.dispose()
 ```
 
-`slice()` accepts a binary STL as an `ArrayBuffer` or `Uint8Array`. Parameters can be either a kernel params object or a JSON string — every accepted parameter is listed in the [kernel parameter reference](engine/README.md#kernel-parameter-reference), which is generated from the kernel's own reader.
+`slice()` accepts a binary STL as an `ArrayBuffer` or `Uint8Array`. Parameters can be either a kernel params object or a JSON string — every accepted parameter is listed in the [kernel parameter reference](engine/PARAMS.md), which is generated from the kernel's own reader.
 
 A runnable version of the above ships with the package: `node node_modules/three-slicer/engine/examples/headless.mjs` writes a cube, slices it batch and streamed, and prints the stats.
 
 `result.error` is set instead of a result when a slice fails or is cancelled — check it before reading `gcode`.
 
+`result.warnings` is the other half of that: a `string[]`, empty when nothing, naming what a **successful** slice
+got away with. Today the one entry is `'over_bed_model'` — the model sliced outside the printable area, which
+otherwise reports plausible time and material and no error (see [Before You Ship](#before-you-ship)). Every path
+carries it: the direct handle, `createSlicerClient()`, and the raw worker's `done` reply.
+
+`result.throughput` says how fast it ran, measured around the call on the same three paths:
+
+```js
+result.throughput.ms               // wall time, incl. the STL crossing into WASM and the layer stream out
+result.throughput.kernelMs         // the kernel's own phase total; ms − kernelMs is the boundary cost
+result.throughput.layersPerSecond  // the figure to show a person
+result.throughput.msPerMsegment    // the figure to COMPARE runs with
+```
+
+Compare runs on `msPerMsegment`, not on `ms`. The kernel is not deterministic in segment count — the same input
+has been measured 15% apart between runs — so two raw millisecond figures describe two different amounts of work,
+and the difference reads as a regression that is not there. In the viewer the same throughput is live: the slice
+bar shows layers/second while slicing, and the host receives it as the `sliceRate` event.
+
+SLA slices carry it too (`sliceSla`, the object-aware job, and the JS contour fallback). `kernelMs` sums that
+technology's own passes — contours, sample, tree, raster, emit — because the two share only the name `t_emit_ms`,
+and reading an SLA result through the FFF phase list would report its emit pass as the entire kernel time
+(measured on a 10mm cube: 2.99ms summed correctly, 1.42ms if mis-read). Compare SLA runs against SLA runs: its
+`path_segments` counts mask segments, not toolpath segments.
+
 ## Streaming Layers
 
 For large models, pass callbacks to receive each sliced layer as it is produced. This avoids keeping the full G-code and layer payload in memory at once.
@@ -209,9 +250,36 @@ Available subpaths:
 | `three-slicer/data` | Named exports for extracted metadata |
 | `three-slicer/data/*.json` | Extracted OrcaSlicer metadata |
 
+## Architecture: How the Pieces Connect
+
+One npm package, five modules. The dependency direction is one-way: `wasm-core` →(build)→ `engine`
+←(data)← `data`, with `components` and `viewer` consuming different surfaces of the engine, `types`
+generating and gating the contract from the side — and the glue at the top is always a single sparse
+settings map held by the host app.
+
+| Module | Role | Published as | Depends on | Consumed by |
+| --- | --- | --- | --- | --- |
+| `wasm-core` | C++ kernel sources + vendored third_party | not published | (ported upstream sources) | `engine` — as build output only |
+| `engine` | kernel SDK: direct handle, worker, client, settings derivation | `three-slicer` root + `/settings` `/toggle` `/client` `/worker` `/wasm(-mt)` `/data` | committed wasm-core output, `data`, the generated `kernel_setting_keys.js` | `components`, `viewer`, every consumer |
+| `data` | extracted schema + catalogs (config-schema, printers, processes, filaments…) | `/data` | `extract_all.py` ← upstream | `engine`'s settings, `components`, `viewer` |
+| `types` | every `.d.ts` + two generators | attached per subpath via the exports map's `types` fields | runs `engine` at generation time (probing), reads `data`'s schema | consumers' IDE/TS — no runtime dependency |
+| `components` | `<SettingsPanel/>` (Shadow DOM) | `/components` | `data` (schema + UI tree), `engine`'s `/toggle` | host apps |
+| `viewer` | `<Viewport/>` (three.js, Shadow DOM) | `/viewer` + `/viewer/toolpath` `/loaders` `/gcode` | `engine`'s `/settings`, the worker, `/data`; `three` (peer) | host apps |
+
+Some of the connections are not imports, and knowing which is which explains most of the layout:
+
+| Connection | Mechanism | Notes |
+| --- | --- | --- |
+| `wasm-core` → `engine` | `build.sh` (emscripten) commits its output into `engine/src/` | not an import — the golden byte-identical gate and the invariant suite verify kernel changes against the engine's output |
+| `data` → `engine`/`components`/`viewer` | `/data` subpath imports | the source of truth is `extract_all.py` over the upstream checkout |
+| `types` → `engine` | the generator **executes** `deriveKernelParams` (probing) and writes `engine/PARAMS.md` + `engine/src/kernel_setting_keys.js` back into the engine | `test_kernel_params.mjs` is the staleness gate |
+| `types` → `data` | `gen_settings_types.mjs` generates `settings-keys.d.ts` (976 keys) from the schema | run automatically by the build |
+| `viewer` ↔ `components` | **no direct link** | the host shares one settings map with both as props, and mounts `<SettingsPanel embedded/>` into the viewer's panel slots |
+| inside `viewer` | `core` (pure, node-runnable) ← `scene` (three/DOM) ← `actions` ← `ui` | `test_layers.mjs` enforces the boundary |
+
 ## TypeScript
 
-Type declarations ship with the package — no `@types/*` needed. All 923 setting keys are typed from the config schema, enum values included:
+Type declarations ship with the package — no `@types/*` needed. All 976 setting keys are typed from the config schema, enum values included:
 
 ```ts
 import { createSlicer, type SlicerSettings } from 'three-slicer'
@@ -252,7 +320,7 @@ const params = deriveKernelParams(settings)
 const result = slicer.slice(stlArrayBuffer, params)
 ```
 
-`deriveKernelParams()` maps the curated set of schema keys currently supported by the kernel (92 today). Other schema keys can still be displayed by the UI, but they may not affect slicing output yet. Vector options are simplified to their first element, except the filament options described below, which keep every extruder's entry.
+`deriveKernelParams()` maps the curated set of schema keys currently supported by the kernel — 131 of its 159 parameters are reachable from 128 schema keys today; the [generated reference](engine/PARAMS.md) is the authoritative list. Other schema keys can still be displayed by the UI, but they may not affect slicing output yet — `ignoredKernelSettings(settings)` names the keys of your map in that category, so a "why did this setting do nothing" question has a one-call answer. Vector options are simplified to their first element, except the filament options described below, which keep every extruder's entry.
 
 ## 3MF Projects
 
@@ -358,13 +426,10 @@ pick's leftovers behind — an ABS material followed by a PLA one keeps ABS's ch
 exposes the exact key set to remove first:
 
 ```js
-function applyPreset(settings, preset, keys) {
-  const next = { ...settings }
-  for (const key of keys) delete next[key]
-  return Object.assign(next, preset)
-}
+import { applyPreset } from 'three-slicer/settings'
 
 setSettings(s => applyPreset(s, filaments.settingsFor(name), filaments.keys))
+// clears filaments.keys first, then merges; a null preset (failed lookup) applies nothing
 ```
 
 The same applies to `processPresets().keys` and `printerKeys`. The filament key set is disjoint from the process key
@@ -386,6 +451,8 @@ The kernel reloads the loaded-filament settings at every tool change and reports
 
 A single-material slice sends none of these keys and produces exactly the G-code it produced before multi-material existed.
 
+Besides per-extruder arrays and painting, a per-feature filament assignment is the third way a slice becomes multi-tool: `outer_wall_filament_id`, `inner_wall_filament_id`, `sparse_infill_filament_id`, `top_surface_filament_id`, `bottom_surface_filament_id` and `internal_solid_filament_id` are 1-based filament indices ("print the outer wall with filament 2"). Values of 0 (default) and 1 (the default extruder) add no second tool, so existing single-material slices are unaffected.
+
 ### Painting a region onto another extruder
 
 Painting is the only way a single object can print in two materials. Painting states follow OrcaSlicer's own enum, in which state `1` is both the support enforcer and Extruder 1, state `2` is both the support blocker and Extruder 2, and `3..16` are Extruders 3 to 16. The state-addressed protocol is on the worker; `slicer.paint()` on the direct handle is the original enforcer/blocker boolean pair.
@@ -398,12 +465,12 @@ worker.postMessage({ cmd: 'erase', facet, hx, hy, hz, cx, cy, cz, radius })
 
 `erase` is a separate command rather than `state: 0`, because a JS `false` coerces to `0` at the WASM boundary and the legacy blocker brush sends exactly that — so the state path refuses `0` outright.
 
-Because a single enum serves both jobs, a support blocker paint and an Extruder 2 paint are the same mark on a facet, and painted materials only take effect with support turned off (the painted multi-material path emits no support). Support painting is unaffected: a support-enabled slice stays on the single-material path.
+Painting and support now coexist: the painted multi-material path runs the same support pass the single-material path does, so enabling support no longer costs the material paint (or the other way round). What remains is the ambiguity a single enum creates — a support **blocker** paint and an Extruder 2 paint are the same mark on a facet, so on a model that uses both brushes the blocker reads as "print with T1".
 
 ## SLA (Resin) Slicing
 
 SLA is a second printer technology, not an FFF mode. `printer_technology` in the settings map routes it —
-apply an SLA machine profile from the catalog (`printersByVendor` marks the technology) or set the key
+apply an SLA machine profile from the catalog (`printerTechByVendor` marks the technology) or set the key
 yourself, then derive SLA params and call the SLA entry:
 
 ```js
@@ -481,7 +548,11 @@ and its out-of-memory retry ladder, both of which are UI policy rather than prot
 ### Driving the worker directly
 
 `createSlicerClient` is a thin wrapper; the protocol underneath is a plain message contract, fully typed in
-`three-slicer/worker`.
+`three-slicer/worker`. A slice request is the message with **no `cmd`**, and its `params` takes an object or a
+JSON string (object accepted since 0.2.3 — the kernel parses JSON text, so it is stringified for you).
+
+The worker below is created with `engineWorkerURL()`, which suits a no-bundler page; under Vite or webpack
+create it the way [Bundler Notes](#bundler-notes) describes and drive that instance instead.
 
 ```js
 import { engineWorkerURL } from 'three-slicer'
@@ -546,6 +617,19 @@ progress cannot be interrupted — terminate the worker instead.
 
 ## Bundler Notes
 
+**Creating the slice worker.** `createSlicerClient()` with no argument is the supported path under Vite and
+webpack: the default is written as the literal `new Worker(new URL('./slicer.worker.js', import.meta.url),
+{ type: 'module' })` that both bundlers recognize as a worker entry, so the worker reaches `dist` together
+with the kernel chunks it dynamically imports. Verified in `pack_check.sh`, which builds a Vite consumer and
+asserts every relative import the emitted worker chunk makes names a file the build actually produced.
+
+Through 0.2.2 that default went through `engineWorkerURL()`, and a function call does not match the pattern —
+Vite fell back to its plain-asset rule and copied the worker source in verbatim, still importing an unhashed
+`./slicer_core.js`. Measured on a Vite 5 app importing `three-slicer/client` and nothing else: a 21KB copy in
+a 40KB `dist` — no kernel emitted at all, a 404 on the worker's first message, and only after `vite build`,
+since the dev server serves the sources. `engineWorkerURL()` remains for no-bundler setups (native ESM, an
+import map, a CDN); under a bundler use the no-argument client or `three-slicer/worker?worker`.
+
 Vite consumers should enable ES module workers and an ES2022 build target:
 
 ```js
@@ -596,11 +680,12 @@ The package includes extracted OrcaSlicer metadata for custom interfaces:
 
 | File | Use |
 | --- | --- |
-| `three-slicer/data/config-schema.json` | Setting definitions, defaults, labels, units, and option metadata (923 options) |
+| `three-slicer/data/config-schema.json` | Setting definitions, defaults, labels, units, and option metadata (976 options) |
 | `three-slicer/data/ui-tree.json` | Tab, page, group, and option layout |
 | `three-slicer/data/toggle-rules.json` | Original enable/disable rule metadata |
 | `three-slicer/data/invalidation-map.json` | Setting invalidation/dependency metadata |
-| `three-slicer/data/printers.json` | 1,035 vendor machine profiles across 64 vendors: motion limits, bed, nozzle |
+| `three-slicer/data/preset-keys.json` | The option keys belonging to each preset type — what `presetOptionKeys(type)` reads |
+| `three-slicer/data/printers.json` | 1,041 vendor machine profiles across 66 vendors: motion limits, bed, nozzle — plus the resin catalog and each vendor's printer technology |
 | `three-slicer/data/processes.js` | 2,243 print presets (speeds, accelerations) |
 | `three-slicer/data/filaments.js` | 5,999 material presets over 81 filament types, plus each printer model's recommended list |
 
@@ -623,13 +708,16 @@ the layout by hand.
 | `slicer.overlay(enforcer)` | The painted overlay triangles for one state, as a `Float32Array` |
 | `slicer.heapSize()` | Current WASM heap size, bytes (peak, monotonic) |
 | `slicer.dispose()` | Releases the slicer handle for garbage collection |
-| `engineWorkerURL()` | Returns a browser worker URL |
+| `engineWorkerURL()` | Worker URL for a **no-bundler** browser setup. Under Vite/webpack use `createSlicerClient()` or `three-slicer/worker?worker` — see [Bundler Notes](#bundler-notes) |
 
 ### `three-slicer/settings`
 
 | API | Description |
 | --- | --- |
 | `deriveKernelParams(settings, opts?)` | Converts sparse OrcaSlicer settings to kernel params. `opts.plate` picks a plate's entry from per-plate options |
+| `applyPreset(settings, preset, keys)` | Clear-then-merge: deletes the catalog's `keys`, merges the preset; a null preset applies nothing |
+| `kernelSettingKeys` | The schema keys `deriveKernelParams` consumes — generated with the [reference table](engine/PARAMS.md) |
+| `ignoredKernelSettings(settings)` | The map's keys the FFF derivation does **not** read — accepted but without slicing effect |
 | `schemaDefault(key)` | The config-schema default for a key |
 | `settingRaw(settings, key)` | The map's value, or the schema default |
 | `settingScalar(settings, key)` | The same, reduced to a scalar — the first set entry of a per-extruder column |
@@ -640,6 +728,7 @@ the layout by hand.
 | `readPresetFile(raw, opts)` | A preset `.json` → a settings map; follows `inherits` via `resolveParent` |
 | `presetOptionKeys(type)` | The option keys belonging to `machine` / `process` / `filament` |
 | `printersByVendor` | Vendor → profile name → entry, for building a picker |
+| `printerTechByVendor` | Vendor → printer technology (`'FFF'` / `'SLA'`) |
 | `printerSettings(name)` | Settings a vendor machine profile applies |
 | `printerKeys` | Every key a printer profile can set — clear these before applying another |
 | `printerDefaultPreset(name)` | The vendor's recommended process preset for that printer |
@@ -678,7 +767,7 @@ the layout by hand.
 
 | API | Description |
 | --- | --- |
-| `schema`, `uiTree`, `toggleRules`, `invalidationMap`, `printers` | The extracted metadata, import attributes already applied |
+| `schema`, `uiTree`, `toggleRules`, `invalidationMap`, `printers`, `presetKeys` | The extracted metadata, import attributes already applied |
 | `loadProcesses()` / `loadFilaments()` | The two large catalogs, on demand — prefer the `settings` facades |
 
 ## Runtime Support
@@ -691,6 +780,41 @@ the layout by hand.
 | React | Viewer and settings panel |
 | three.js | Required by `three-slicer/viewer` |
 
+## Before You Ship
+
+The traps below were all hit while building the [integration demos](https://github.com/kimgh06/Web_Three_Slicer/tree/main/examples)
+and the live landing embed — each one returns something plausible instead of an error, which is why they
+are listed **in the order they bite**, not by topic. The later a trap fires, the more it costs — and none of
+them fails a build or throws, so nothing surfaces them for you.
+
+1. **Your first real model: hand it over origin-centered, not bed-centered.** The kernel takes plate-local
+   coordinates and seats the model on the bed itself; pre-centering on the bed adds the offset twice and the
+   part slices *off the bed* — with plausible time and material and no error. Since 0.2.3 the result says so:
+   `result.warnings` carries `'over_bed_model'` (the `stats.over_bed_model` flag is still there too). Check
+   `result.warnings.length` after every slice; it is the channel every future condition of this kind uses.
+2. **Reading the results: `filament_mm` is a length, and the time depends on the kernel.** Grams are your
+   conversion (`filament_mm × π × (diameter/2)² × density / 1000`, from the filament preset's
+   `filament_diameter`/`filament_density`). `time_estimate` differs ~25% between the single- and
+   multi-threaded kernels on identical geometry, so your COOP/COEP headers change the number — pin one as
+   the reference if you price on it.
+3. **Drawing toolpaths: the role field is encoded, and G-code round-trips lose roles.** `paths[k+3]` holds
+   `role + tool*16` — mask with `& 15` / `>>> 4`. `SegmentData.position` is stride 4 (x, y, z, w). The
+   kernel's G-code carries no `;TYPE:` comments, so `parseGcode` collapses roles into wall — draw
+   `result.layers` directly when the slicing side is yours.
+4. **Settings: presets are sparse, and unread keys are silent.** Apply presets with
+   [`applyPreset`](#materials-and-multi-material) (clear-then-merge — a plain merge keeps the previous
+   material's leftovers). A key the FFF derivation does not read is accepted and does nothing:
+   `ignoredKernelSettings(settings)` names them.
+5. **Cancel is conditional.** `client.cancel()` works only on a cross-origin-isolated page (the mt kernel);
+   otherwise it returns `false` — terminate and recreate the client instead.
+   Details: [Cancelling a slice](#cancelling-a-slice).
+
+Gone as of 0.2.3, and listed here only because it bit every consumer before then: `createSlicerClient()` with
+no argument used to build a worker Vite copied as a plain asset, which 404'd on its own kernel import in
+production while `npm run dev` passed. The no-argument form now emits a real worker chunk — see
+[Bundler Notes](#bundler-notes). On 0.2.2 or earlier, pass the worker in yourself
+(`import SlicerWorker from 'three-slicer/worker?worker'`).
+
 ## Known Limits
 
 - `slice()` currently takes binary STL input at the engine API boundary.
@@ -698,7 +822,7 @@ the layout by hand.
 - `registerLoader(exts, fn)` from `three-slicer/viewer/loaders` adds any other format. Formats needing a heavy dependency are kept out of the package so it stays runtime-dependency-free — see `web/viewer/src/step_loader.js` for a STEP loader built on `occt-import-js` (OCCT WASM).
 - Not every OrcaSlicer schema key is wired into the WASM kernel yet.
 - Some vector settings are simplified to their first element.
-- Material painting and support cannot currently produce two materials on the same slice: the painted multi-material path emits no support, and one triangle selector serves both brushes.
+- One triangle selector serves both the support brush and the material brush (upstream's shared enum), so a support **blocker** paint and an Extruder 2 paint are the same mark — the two brushes cannot mark the same model independently.
 - The multi-material prime tower is a real ported wipe tower, but the fallback square ring used when it fails is not.
 - SLA hollowing and drain-hole geometry are refused with `SLA_UNSUPPORTED_HOLLOWING` (the OpenVDB chain is not ported); the records still round-trip through `.3mf`.
 - The `.sl1` export lives in the viewer (its masks need a canvas); there is no headless `.sl1` writer export yet.

package/components/README.md

@@ -4,12 +4,12 @@ Reusable React components for the browser slicer. Props-driven — no global sta
 
 ## `<SettingsPanel/>`
 
-An OrcaSlicer-style settings form generated from `three-slicer/data` (schema + UI tree + toggle rules): tab/page/group navigation, mode filter (simple/advanced/expert), search across 923 options, dirty markers with per-option reset, and enable/disable rules evaluation.
+An OrcaSlicer-style settings form generated from `three-slicer/data` (schema + UI tree + toggle rules): tab/page/group navigation, mode filter (all/simple/advanced/expert/develop), search across 976 options, dirty markers with per-option reset, and enable/disable rules evaluation.
 
 The tab set follows the printer profile's technology: a settings map whose `printer_technology` says SLA swaps the FFF tabs for the SLA ones (print/material/printer builders carry the technology in their upstream builder name, which is what the filter reads). No prop needed — change the profile in the shared settings map and the panel follows.
 
 ```bash
-npm i three-slicer     # react is a peer dependency — npm installs it for you
+npm i three-slicer react react-dom     # react is an OPTIONAL peer — npm does not install it for you
 ```
 
 ```jsx
@@ -29,10 +29,13 @@ Props:
 | `settings` | `{ [schemaKey]: value }` | Sparse settings map — the consumer's state is the single source of truth |
 | `setSettings` | `(updater) => void` | React setState-style updater; the only way state leaves the component |
 | `onOptionOpen` | `(key) => void` (optional) | Label click hook for deep links/detail views. Omit → plain labels |
+| `embedded` | `boolean` (optional) | Compact layout for embedding inside another panel |
+| `customWidgets` | `{ [schemaKey]: Component }` (optional) | Replace schema-driven widgets per key (e.g. `{ printable_area: MyBedEditor }`) |
+| `only` | `{ builder, page? }` (optional) | Pins the panel to one builder/page and drops the search/page/mode chrome — how `<Viewport/>`'s `motionPanel` slot is meant to be filled |
 
 The same `settings` object feeds `deriveKernelParams()` in `three-slicer` and the `<Viewport/>` in `three-slicer/viewer` — one state connects all three.
 
-Ships transpiled ESM (`dist/`); react is a peer dependency. Styling is class-based and unstyled by default (bring your own CSS, or reuse the demo's).
+Ships transpiled ESM (`dist/`); react is an optional peer dependency. The panel arrives fully styled: its stylesheet is inlined into the bundle and injected into a Shadow DOM root, so host CSS neither styles it nor collides with it.
 
 The 3D viewport lives in its own package: `three-slicer/viewer`.
 

package/data/README.md

@@ -4,12 +4,13 @@ OrcaSlicer configuration metadata extracted from the original C++ sources, shipp
 
 | File | Contents |
 |---|---|
-| `config-schema.json` | 923 print options: type, label, category, tooltip, min/max, mode, enum values/labels, defaults, source line numbers |
-| `config-schema-builddump.json` | Build-verified cross-check: the real `print_config_def` (817 options) dumped from a WASM compile of the original `PrintConfig.cpp` |
-| `ui-tree.json` | Tab → page → group → option tree from `Tab.cpp` (20 pages, 542 option references) |
+| `config-schema.json` | 976 print options: type, label, category, tooltip, min/max, mode, enum values/labels, defaults, source line numbers |
+| `config-schema-builddump.json` | Build-verified cross-check: the real `print_config_def` (817 options) dumped from a WASM compile of the original `PrintConfig.cpp` — repo-only, excluded from the npm tarball |
+| `ui-tree.json` | Tab → page → group → option tree from `Tab.cpp` (34 pages, 618 option references — the SLA tabs included) |
 | `toggle-rules.json` | 231 enable/disable rules with original C++ `enable_if` condition source |
 | `invalidation-map.json` | Option-change → re-slice step mapping (Print/PrintObject invalidation branches) |
-| `printers.json` | 1,035 vendor machine profiles across 64 vendors: motion limits, bed and nozzle |
+| `preset-keys.json` | The option keys belonging to each preset type (`machine`/`process`/`filament`) — what `presetOptionKeys(type)` reads |
+| `printers.json` | 1,041 vendor machine profiles across 66 vendors: motion limits, bed and nozzle — plus the resin catalog and each vendor's printer technology |
 | `processes.js` | 2,243 print presets (speeds, accelerations), joined to printers by `compatible_printers` |
 | `filaments.js` | 5,999 material presets over 81 filament types, plus each printer model's recommended list |
 
@@ -18,10 +19,10 @@ The last two are column-oriented and deduplicated, and load on demand. Read them
 
 ## Material presets
 
-`filaments.js` carries only the keys the kernel actually reads (14 today: temperatures, flow, diameter, cooling,
-and the retraction/z-hop overrides a material is allowed to apply on top of the machine's). That column set is
-disjoint from `processes.js`' 59, which is what lets a material pick and a process pick be applied independently —
-neither clears the other's values.
+`filaments.js` carries only the keys the kernel actually reads (18 today: temperatures, flow, diameter, cooling,
+pressure advance, cost/density, and the retraction/z-hop overrides a material is allowed to apply on top of the
+machine's). That column set is disjoint from `processes.js`' 85, which is what lets a material pick and a process
+pick be applied independently — neither clears the other's values.
 
 `filamentPresets()` is the facade:
 
@@ -37,7 +38,7 @@ filaments.keys                                        // clear these before appl
 
 `recommendedFor()` intersects with the compatible list rather than returning the raw recommendation, and the
 filtering is not cosmetic: the recommendation is declared on the machine **model** and so is nozzle-agnostic,
-while its entries name nozzle-specific presets. Across all 1,035 printer profiles, 1,749 of 4,259 raw
+while its entries name nozzle-specific presets. Across all 1,041 printer profiles, 1,749 of 4,259 raw
 recommendation entries (41%) name a material whose own compatible list excludes that profile.
 
 `type` and `vendor` are empty strings when the profile chain declares neither — 265 of the 5,999 presets. That is