three-slicer 0.1.6 → 0.1.7

package/engine/README.md

@@ -37,7 +37,7 @@ Off-main-thread (browser): `new Worker(engineWorkerURL(), { type: 'module' })`
 
 Two levels — use whichever fits:
 
-1. **Kernel params (this package's native contract)** — a flat JSON object of ~90 keys (`layer_height`, `wall_loops`, `infill_density` 0–1, `sparse_infill_pattern`, `enable_support`, `wall_generator: 'classic' | 'arachne'`, …). See `src/settings.js` for the full shape.
+1. **Kernel params (this package's native contract)** — a flat JSON object (`layer_height`, `wall_loops`, `infill_density` 0–1, `sparse_infill_pattern`, `enable_support`, `wall_generator: 'classic' | 'arachne'`, …). Every accepted key is listed under [Kernel parameter reference](#kernel-parameter-reference) below.
 2. **OrcaSlicer settings map** — a sparse `{schemaKey: value}` map using original OrcaSlicer option keys (923 defined in `three-slicer/data`); unset keys fall back to schema defaults:
 
 ```js
@@ -45,7 +45,253 @@ import { deriveKernelParams } from 'three-slicer/settings'
 slicer.slice(stl, deriveKernelParams({ layer_height: 0.25, sparse_infill_density: 15 }))
 ```
 
-**Known limit:** `deriveKernelParams` maps a curated whitelist of 92 schema keys to kernel params. Editing other schema keys has no slicing effect (they exist for UI/metadata). Scalar options use their first element only; the filament options listed under *Materials* below are the exception — those keep every extruder's entry.
+**Known limit:** `deriveKernelParams` maps a curated subset of schema keys to kernel params. Editing other schema keys has no slicing effect (they exist for UI/metadata). Scalar options use their first element only; the filament options listed under *Materials* below are the exception — those keep every extruder's entry. Kernel parameters with no schema key behind them are reachable only by writing the params object yourself — the reference table marks which those are.
+
+## Kernel parameter reference
+
+Generated from the kernel's own reader (`params.cpp`) — it is the definition of the accepted key set, so this table
+cannot drift from what `slice()` actually honours. Regenerate with `node types/gen_kernel_params.mjs`.
+
+<!-- KERNEL-PARAMS:BEGIN — generated by types/gen_kernel_params.mjs, do not edit by hand -->
+
+The kernel accepts **159 parameters**. `deriveKernelParams()` produces 131 of them from the
+OrcaSlicer settings map; the remaining 28 have no schema key behind them and can only be set by writing
+the params object directly — those rows show `—` in the *From setting* column.
+
+A parameter left out of the object keeps the default listed here, so sending a partial object is normal and is
+what `deriveKernelParams()` itself does.
+
+*From setting* names the schema key the value is read from, which is often **not** the same name and not the
+same unit — `first_layer_height` comes from `initial_layer_print_height`, and `infill_density` is
+`sparse_infill_density` divided by 100 (a settings map holding `20` produces `0.2` here).
+
+### Geometry and walls
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `auto_center` | `boolean` | `false` | — | stage 28: true = realign the combined bbox to the origin (stage-3 legacy). false (default) = trust the viewer coordinates (no realignment, only Z seating) -> the toolpath overlaps the on-screen model exactly. Upstream = only the plate origin offset (GCode.cpp:932). |
+| `first_layer_height` | `number` | `0.2` | `initial_layer_print_height` |  |
+| `gcode_resolution` | `number` | `0.01` | `resolution` | resolution (mm): path simplification tolerance. Upstream PrintConfig default 0.01 |
+| `initial_layer_line_width` | `number` | `0` | `initial_layer_line_width` |  |
+| `inner_wall_line_width` | `number` | `0` | `inner_wall_line_width` |  |
+| `internal_solid_infill_line_width` | `number` | `0` | `internal_solid_infill_line_width` |  |
+| `layer_height` | `number` | `0.2` | `layer_height` |  |
+| `line_width` | `number` | `0.42` | `line_width` |  |
+| `outer_wall_line_width` | `number` | `0` | `outer_wall_line_width` |  |
+| `sparse_infill_line_width` | `number` | `0` | `sparse_infill_line_width` |  |
+| `spiral_mode` | `boolean` | `false` | `spiral_mode` | spiral_mode (vase) |
+| `support_line_width` | `number` | `0.0` | `support_line_width` | support_line_width (0=auto; the real tree support extrusion width) |
+| `top_surface_line_width` | `number` | `0` | `top_surface_line_width` |  |
+| `wall_generator` | `string` | `'classic'` | `wall_generator` | classic\|arachne (arachne = the real ported WallToolPaths) |
+| `wall_loops` | `number` | `2` | `wall_loops` |  |
+
+### Infill
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `bottom_shell_layers` | `number` | `3` | `bottom_shell_layers` | top_shell_layers/bottom_shell_layers |
+| `infill_angle` | `number` | `45.0` | `infill_direction` | infill_direction |
+| `infill_density` | `number` | `0.15` | `sparse_infill_density` |  |
+| `ironing_flow` | `number` | `10.0` | `ironing_flow` | ironing flow (%) |
+| `ironing_spacing` | `number` | `0.1` | `ironing_spacing` | ironing line spacing (mm) |
+| `ironing_speed` | `number` | `30.0` | `ironing_speed` | ironing speed (mm/s) |
+| `ironing_type` | `string` | `'none'` | `ironing_type` | none\|top\|topmost\|solid (the top family = on) |
+| `sparse_infill_filament_id` | `number` | `0` | `sparse_infill_filament_id` |  |
+| `sparse_infill_pattern` | `string` | `'rectilinear'` | `sparse_infill_pattern` | rectilinear\|grid\|triangles\|zigzag\|gyroid |
+| `top_shell_layers` | `number` | `4` | `top_shell_layers` | top_shell_layers/bottom_shell_layers |
+
+### Speeds, flow and temperature
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `bed_temp` | `number` | `60` | `hot_plate_temp` |  |
+| `bridge_speed` | `number` | `25.0` | `bridge_speed` | bridge_speed[0] (slowdown for unsupported bottoms) |
+| `close_fan_the_first_x_layers` | `number` | `1` | `close_fan_the_first_x_layers` | close_fan_the_first_x_layers |
+| `enable_pressure_advance` | `boolean` | `false` | `enable_pressure_advance` | enable_pressure_advance[0] |
+| `fan_speed` | `number` | `100.0` | `fan_max_speed` | fan_speed (%) |
+| `filament_diameter` | `number` | `1.75` | `filament_diameter` |  |
+| `first_layer_speed` | `number` | `20` | `initial_layer_speed` |  |
+| `flow_ratio` | `number` | `1.0` | `filament_flow_ratio` |  |
+| `full_fan_speed_layer` | `number` | `3` | `full_fan_speed_layer` | full_fan_speed_layer |
+| `machine_accel_print` | `number` | `5000` | `default_acceleration` | mm/s² |
+| `machine_accel_retract` | `number` | `5000` | `machine_max_acceleration_retracting` | mm/s² |
+| `machine_accel_travel` | `number` | `5000` | `travel_acceleration` | mm/s² |
+| `machine_jerk_e` | `number` | `2.5` | `machine_max_jerk_e` | mm/s |
+| `machine_jerk_xy` | `number` | `9.0` | `machine_max_jerk_x` | mm/s |
+| `machine_jerk_z` | `number` | `0.4` | `machine_max_jerk_z` | mm/s |
+| `machine_max_accel_e` | `number` | `5000` | `machine_max_acceleration_e` | mm/s² (machine_max_acceleration_*) — per-axis ceiling, distinct from the accel_* feedrates above |
+| `machine_max_accel_xy` | `number` | `5000` | `machine_max_acceleration_x` | mm/s² (machine_max_acceleration_*) — per-axis ceiling, distinct from the accel_* feedrates above |
+| `machine_max_accel_z` | `number` | `500` | `machine_max_acceleration_z` | mm/s² (machine_max_acceleration_*) — per-axis ceiling, distinct from the accel_* feedrates above |
+| `machine_max_speed_e` | `number` | `30` | `machine_max_speed_e` | mm/s |
+| `machine_max_speed_xy` | `number` | `500` | `machine_max_speed_x` | mm/s |
+| `machine_max_speed_z` | `number` | `12` | `machine_max_speed_z` | mm/s |
+| `max_volumetric_extrusion_rate_slope` | `number` | `0.0` | `max_volumetric_extrusion_rate_slope` | PE-lite flow change rate limit (mm³/s², 0=off) |
+| `nozzle_diameter` | `number` | `0.4` | `nozzle_diameter` |  |
+| `nozzle_temp` | `number` | `210` | `nozzle_temperature` |  |
+| `pressure_advance` | `number` | `0.02` | `pressure_advance` | pressure_advance[0] |
+| `print_speed` | `number` | `60` | `outer_wall_speed` |  |
+| `slow_down_layer_time` | `number` | `8.0` | `slow_down_layer_time` | slow_down_layer_time (s) |
+| `travel_speed` | `number` | `150` | `travel_speed` |  |
+
+### Retraction and seams
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `retract_length` | `number` | `0.8` | `filament_retraction_length`, `retraction_length` | retraction_length/speed[0], z_hop[0] |
+| `retract_speed` | `number` | `30.0` | `filament_retraction_speed`, `retraction_speed` | retraction_length/speed[0], z_hop[0] |
+| `retraction_minimum_travel` | `number` | `2.0` | `filament_retraction_minimum_travel`, `retraction_minimum_travel` | retraction_minimum_travel (mm): minimum travel that triggers a retraction |
+| `scarf_length` | `number` | `10.0` | — | length of the scarf z/flow ramp (mm) |
+| `seam_position` | `string` | `'back'` | `seam_position` | nearest\|aligned\|back\|random |
+| `seam_slope_type` | `string` | `'none'` | `seam_slope_type` | none\|external\|all -> scarf seam (external/all = on) |
+| `z_hop` | `number` | `0.4` | `filament_z_hop`, `z_hop` | retraction_length/speed[0], z_hop[0] |
+
+### Adhesion (skirt, brim, raft)
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `brim_object_gap` | `number` | `0.0` | `brim_object_gap` | brim_object_gap (mm): gap between brim and object |
+| `brim_width` | `number` | `0.0` | `brim_width` | skirt_distance / brim_width |
+| `raft_contact_distance` | `number` | `0.1` | `raft_contact_distance` | raft_contact_distance (mm) |
+| `raft_expansion` | `number` | `1.5` | `raft_expansion` | raft_expansion (mm). Upstream default 1.5 (previously hardcoded to 3.0) |
+| `raft_first_layer_height` | `number` | `0.30` | — | raft first layer height (mm) |
+| `raft_layers` | `number` | `0` | `raft_layers` | raft_layers |
+| `skirt_distance` | `number` | `2.0` | `skirt_distance` | skirt_distance / brim_width |
+| `skirt_height` | `number` | `1` | `skirt_height` | skirt_height: how many layers the skirt is drawn on |
+| `skirt_loops` | `number` | `1` | `skirt_loops` | skirt_loops |
+
+### Support
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `bridge_no_support` | `boolean` | `false` | `bridge_no_support` | bridge_no_support: no support under bridge regions |
+| `enable_support` | `boolean` | `false` | `enable_support` | enable_support |
+| `support_angle` | `number` | `0.0` | `support_angle` | support_angle: base angle of the support body (°). Upstream SupportParameters::base_angle |
+| `support_auto` | `boolean` | `true` | — | stage 20: true = automatic overhang detection, false = manual (painted enforcers only) |
+| `support_base_pattern` | `string` | `'default'` | `support_base_pattern` | support_base_pattern: default\|rectilinear\|rectilinear-grid\|honeycomb\|... |
+| `support_base_pattern_spacing` | `number` | `2.5` | `support_base_pattern_spacing` | support_base_pattern_spacing (mm). Determines spacing together with density |
+| `support_bottom_z_distance` | `number` | `0.2` | `support_bottom_z_distance` | stage 32: z gap under support resting on a model top surface (default 0.2 = equivalent to today's 1 layer -> default behavior and golden unchanged) |
+| `support_density` | `number` | `0.15` | — | density of the support body |
+| `support_expansion` | `number` | `0.0` | `support_expansion` | support_expansion (mm): expands the overhang region |
+| `support_filament` | `number` | `0` | `support_filament` | filament for the support base (and, upstream, the raft) |
+| `support_grid_snap` | `boolean` | `true` | — | equivalent of the upstream SupportGridPattern (default behavior of the grid style) |
+| `support_interface_bottom_layers` | `number` | `0` | `support_interface_bottom_layers` | support_interface_bottom_layers (0 = none) |
+| `support_interface_filament` | `number` | `0` | `support_interface_filament` | filament for the support interface |
+| `support_interface_pattern` | `string` | `'auto'` | `support_interface_pattern` | support_interface_pattern: auto\|rectilinear\|concentric\|rectilinear_interlaced\|grid |
+| `support_interface_spacing` | `number` | `0.5` | `support_interface_spacing` | support_interface_spacing (mm, 0=solid). Upstream default 0.5 |
+| `support_interface_top_layers` | `number` | `2` | `support_interface_top_layers` | support_interface_top_layers |
+| `support_object_first_layer_gap` | `number` | `0.2` | `support_object_first_layer_gap` | support_object_first_layer_gap (mm) |
+| `support_on_build_plate_only` | `boolean` | `false` | `support_on_build_plate_only` | support_on_build_plate_only: only support reaching the bed |
+| `support_overhang_min_area` | `number` | `0.0` | — | minimum overhang area (mm², 0 = auto w²). Replaces the morphological opening filter |
+| `support_remove_small_overhang` | `boolean` | `true` | `support_remove_small_overhang` | support_remove_small_overhang (upstream default true) |
+| `support_style` | `string` | `'grid'` | `support_style` | grid\|tree_lite |
+| `support_threshold_angle` | `number` | `30.0` | `support_threshold_angle` | support_threshold_angle |
+| `support_threshold_overlap` | `number` | `0.5` | `support_threshold_overlap` | support_threshold_overlap: the overlap criterion when θ=0 (as a fraction of extrusion width) |
+| `support_top_z_distance` | `number` | `0.2` | `support_top_z_distance` | support_top_z_distance |
+| `support_xy_distance` | `number` | `0.35` | `support_object_xy_distance` | support_object_xy_distance |
+| `tree_lite_min_radius` | `number` | `1.5` | — | tree_lite taper constants (our own approximation — no matching upstream key) |
+| `tree_lite_shrink` | `number` | `0.5` | — | tree_lite taper constants (our own approximation — no matching upstream key) |
+| `tree_style` | `string` | `'organic'` | — | organic\|slim\|strong\|hybrid (upstream support_style smsTree*) |
+| `tree_support_angle_slow` | `number` | `25.0` | `tree_support_angle_slow` | tree_support_angle_slow (deg) |
+| `tree_support_branch_angle` | `number` | `40.0` | `tree_support_branch_angle` | fallback spelling — `tree_support_branch_angle_organic` wins when both are sent |
+| `tree_support_branch_angle_organic` | `number` | `40.0` | `tree_support_branch_angle_organic` | tree_support_branch_angle_organic (deg) |
+| `tree_support_branch_diameter` | `number` | `2.0` | `tree_support_branch_diameter` | fallback spelling — `tree_support_branch_diameter_organic` wins when both are sent |
+| `tree_support_branch_diameter_angle` | `number` | `5.0` | `tree_support_branch_diameter_angle` | tree_support_branch_diameter_angle (deg) |
+| `tree_support_branch_diameter_organic` | `number` | `2.0` | `tree_support_branch_diameter_organic` | tree_support_branch_diameter_organic (mm) |
+| `tree_support_branch_distance` | `number` | `1.0` | `tree_support_branch_distance` | fallback spelling — `tree_support_branch_distance_organic` wins when both are sent |
+| `tree_support_branch_distance_organic` | `number` | `1.0` | `tree_support_branch_distance_organic` | tree_support_branch_distance_organic (mm) |
+| `tree_support_tip_diameter` | `number` | `0.8` | `tree_support_tip_diameter` | tree_support_tip_diameter (mm) |
+| `tree_support_top_rate` | `number` | `30.0` | `tree_support_top_rate` | tree_support_top_rate (%) |
+| `tree_support_wall_count` | `number` | `0` | `tree_support_wall_count` | tree_support_wall_count (organic applies max(1,·) internally) |
+
+### Multi-material and prime tower
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `bottom_surface_filament_id` | `number` | `0` | `bottom_surface_filament_id` |  |
+| `enable_prime_tower` | `boolean` | `true` | `enable_prime_tower` |  |
+| `filament_cost` | `number[]` | `[]` | `filament_cost` | currency per kg, per filament |
+| `filament_density` | `number[]` | `[]` | `filament_density` | g/cm3, per filament |
+| `filament_map` | `number[]` | `[]` | `filament_map` |  |
+| `filament_settings_id` | `vector<std::string>` | `[]` | `filament_settings_id` |  |
+| `filament_type` | `vector<std::string>` | `[]` | `filament_type` |  |
+| `inner_wall_filament_id` | `number` | `0` | `inner_wall_filament_id` |  |
+| `internal_solid_filament_id` | `number` | `0` | `internal_solid_filament_id` |  |
+| `outer_wall_filament_id` | `number` | `0` | `outer_wall_filament_id` |  |
+| `top_surface_filament_id` | `number` | `0` | `top_surface_filament_id` |  |
+| `wipe_tower_real` | `boolean` | `false` | — | stage 12: use the real WipeTower.generate() on MM changes instead of the stage-6 square ring |
+
+### Bed and machine G-code
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `bed_depth` | `number` | `256.0` | `printable_area` | bed size (offset = bed/2) |
+| `bed_height` | `number` | `0.0` | `printable_height` | printable_height (mm). 0 = no ceiling (backwards compatible) |
+| `bed_width` | `number` | `256.0` | `printable_area` | bed size (offset = bed/2) |
+| `enable_arc_fitting` | `boolean` | `false` | `enable_arc_fitting` | enable_arc_fitting |
+| `machine_end_gcode` | `string` | — | `machine_end_gcode` | printer profile custom G-code. Empty = the mini-kernel's own preamble/footer only |
+| `machine_start_gcode` | `string` | — | `machine_start_gcode` | printer profile custom G-code. Empty = the mini-kernel's own preamble/footer only |
+| `printable_height` | `number` | `250.0` | `printable_height` | printable_height (mm) — the tree BuildVolume height |
+
+### Engine, streaming and diagnostics
+
+| Kernel param | Type | Default | From setting | Notes |
+| --- | --- | --- | --- | --- |
+| `arachne_dump` | `boolean` | `false` | — | temporary diagnostic: dump the PASS1 arachne input polygons to stderr |
+| `economy` | `boolean` | `false` | — |  |
+| `emit_pe_tags` | `boolean` | `false` | — | emit PE tags on extrusion runs (enabled automatically when the real PE is used). Default false (backwards compatible) |
+| `extruder_count` | `number` | `1` | — | multi-material: how many extruders are used (1\|2) |
+| `extruder_filament_diameter` | `number[]` | `[]` | `filament_diameter` |  |
+| `extruder_flow_ratio` | `number[]` | `[]` | `filament_flow_ratio` |  |
+| `extruder_nozzle_temp` | `number[]` | `[]` | `nozzle_temperature` |  |
+| `extruder_retract_length` | `?` | `[]` | `filament_retraction_length` | undefined |
+| `extruder_retract_speed` | `?` | `[]` | `filament_retraction_speed` | undefined |
+| `extruder_z_hop` | `?` | `[]` | `filament_z_hop` | undefined |
+| `extrusion_rate_slope_segment_length` | `number` | `1.0` | — | segment split length for the real PE (mm) |
+| `flush_into_infill` | `boolean` | `false` | `flush_into_infill` |  |
+| `flush_multiplier` | `number` | `1.0` | `flush_multiplier` | upstream scales the whole table by this |
+| `flush_volumes_matrix` | `number[]` | `[]` | `flush_volumes_matrix` |  |
+| `gcode_config_block` | `boolean` | `false` | — | ; CONFIG_BLOCK_START … the parameters this slice ran with … END |
+| `gcode_stats_block` | `boolean` | `false` | — | ; filament used [mm]/[cm3]/[g], cost, total filament change |
+| `independent_support_layer_height` | `boolean` | `false` | `independent_support_layer_height` | false by default because of the kernel z grid constraint (gap quantized to layers) |
+| `keep_stages` | `boolean` | `false` | — | keep the stages cached after slicing (skips the early release — a memory trade-off) |
+| `mm_group_split` | `number` | `0` | — | triangle group boundary index ([0,split)=T0, [split,N)=T1) |
+| `mm_group_splits` | `number[]` | `[]` | — |  |
+| `mm_group_tools` | `number[]` | `[]` | — |  |
+| `pe_external_perimeter_only` | `boolean` | `false` | — | real PE: smooth outer walls only |
+| `pe_lite` | `boolean` | `true` | — | true = the effective PE-lite (default), false = the ported real PE (tagged g-code) |
+| `pe_strip_tags` | `boolean` | `true` | — | strip the tags from the final output after real PE post-processing |
+| `prime_tower_ring_size` | `number` | `15.0` | — | side length of the fallback square ring (mm) |
+| `prime_tower_width` | `number` | `30.0` | `prime_tower_width` | width of the real WipeTower (mm). Separate from the square ring width (15). |
+| `prime_tower_x` | `number` | `10.0` | `wipe_tower_x` |  |
+| `prime_tower_y` | `number` | `10.0` | `wipe_tower_y` |  |
+| `prime_volume` | `number` | `0.0` | `prime_volume` | extra volume primed on every change, on top of the pair's |
+| `reduce_crossing_wall` | `boolean` | `false` | `reduce_crossing_wall` | wall-avoiding travel |
+| `reuse_stages` | `number` | `0` | — |  |
+| `time_engine` | `string` | `'full'` | — |  |
+
+<!-- KERNEL-PARAMS:END -->
+
+### The parameters no setting reaches
+
+A `—` in *From setting* means there is no OrcaSlicer option behind that parameter, so it exists only if you put it
+in the params object yourself. They are not one kind of thing, and the difference matters before you reach for one:
+
+- **Host runtime flags** — `economy`, `keep_stages`, `reuse_stages`, `time_engine`, `wipe_tower_real`,
+  `gcode_stats_block`, `gcode_config_block`. Decisions the *caller* makes about a particular run, not properties of
+  the print. `economy` is the last rung of an out-of-memory retry: it streams G-code and skips the preview
+  toolpaths and the time estimate, so a model that cannot finish any other way still finishes.
+- **Values the viewer computes** — `extruder_count`, `mm_group_split`, `mm_group_splits`, `mm_group_tools`,
+  `auto_center`. These come from the scene (how many extruders are loaded, which triangle ranges belong to which
+  tool), so there is nothing for a settings map to hold. `<Viewport/>` fills them in at slice time.
+- **Kernel-only tuning** — `support_density`, `support_auto`, `support_grid_snap`, `support_overhang_min_area`,
+  `tree_style`, `tree_lite_shrink`, `tree_lite_min_radius`, `scarf_length`, `prime_tower_ring_size`,
+  `raft_first_layer_height`, `extrusion_rate_slope_segment_length`. Real knobs with no upstream option of the same
+  name — some are this kernel's own approximations (the `tree_lite_*` taper), others are upstream behaviour that
+  upstream never exposed as a setting.
+- **Diagnostics** — `arachne_dump`, `pe_lite`, `pe_strip_tags`, `pe_external_perimeter_only`, `emit_pe_tags`. Left
+  at their defaults unless you are working on the kernel itself. `pe_lite` in particular defaults to `true` because
+  the real pressure equalizer only acts on G-code carrying OrcaSlicer's `;_EXTRUDE_SET_SPEED` tags, which this
+  kernel emits only when asked.
 
 ## Materials and multi-material
 
@@ -57,7 +303,17 @@ import { filamentPresets, deriveKernelParams } from 'three-slicer/settings'
 const filaments = await filamentPresets()               // lazy — the artifact loads on first call
 filaments.listFor('Bambu Lab X1 Carbon 0.4 nozzle')     // [{name, type, vendor}, …]
 filaments.recommendedFor('Bambu Lab X1 Carbon 0.4 nozzle')  // the vendor's shortlist, filtered to the compatible set
-Object.assign(settings, filaments.settingsFor('Bambu PLA Basic @BBL X1C'))
+
+// Applying one: CLEAR the preset's key set first. A preset carries only the keys it sets, so a plain merge leaves
+//  behind whatever the previous material set and this one does not — a PLA pick after an ABS pick keeps ABS's
+//  chamber temperature. `keys` is the exact set to clear, and the filament and process key sets are disjoint, so
+//  clearing one never disturbs the other.
+function applyPreset(settings, preset, keys) {
+  const next = { ...settings }
+  for (const key of keys) delete next[key]
+  return Object.assign(next, preset)
+}
+settings = applyPreset(settings, filaments.settingsFor('Bambu PLA Basic @BBL X1C'), filaments.keys)
 ```
 
 **One material per extruder.** Upstream stores every filament option as one entry per extruder, so a multi-material settings map writes each extruder's material at its own index:

package/engine/index.d.ts

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

package/engine/index.js

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

package/engine/src/client.js

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

package/engine/src/data.js

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