three-slicer 0.2.3 → 0.2.5

package/types/viewer.d.ts

@@ -3,12 +3,42 @@ import type * as React from 'react'
 import type { SlicerSettings } from './settings-keys.d.ts'
 
 export interface ViewportProps {
-  /** Sparse settings map. Defaults to `{}`. */
+  /**
+   * Sparse settings map. Defaults to `{}`. Two viewer knobs ride in it beside the schema keys: `sla_antialias`
+   * (SL1 mask MSAA, 1|2|4) and `slice_workers` — how many plates an all-plates run slices at once (0/absent =
+   * Auto: half the cores on the threaded kernel, one per core on the single-threaded one; the in-app select
+   * writes it). Neither reaches a 3mf.
+   */
   settings?: SlicerSettings
   /** React setState shape. Defaults to a no-op. */
   setSettings?: React.Dispatch<React.SetStateAction<SlicerSettings>>
-  /** Left process-panel slot — usually `<SettingsPanel embedded/>`. Defaults to null. */
+  /**
+   * Per-plate overrides: `{[plateIndex]: sparse map}`, merged over `settings` for that plate's slice only —
+   * a key's absence means "follow the global value" (delete the key to clear an override). Plate identity is
+   * the plate index; deleting the last plate truncates its entry. Editing one plate's override invalidates only
+   * that plate's cached result. Any key can be overridden: `printer_technology` routes that plate to the
+   * FFF or SLA slicer (an SLA plate's grid cell is sized to its resin display), and a bed override
+   * (`printable_area`/`printable_height`) resizes that plate's own grid cell. What a 3mf cannot represent —
+   * a mixed-technology or mixed-bed project — is refused at project export with a typed error
+   * (`error.code` `'UNSUPPORTED_MIXED_TECH_3MF'` / `'UNSUPPORTED_MIXED_BED_3MF'`); per-plate G-code/.sl1
+   * exports always work. Defaults to `{}`.
+   */
+  plateSettings?: Record<number, SlicerSettings>
+  /** React setState shape for {@link ViewportProps.plateSettings}. Defaults to a no-op. */
+  setPlateSettings?: React.Dispatch<React.SetStateAction<Record<number, SlicerSettings>>>
+  /**
+   * Left process-panel slot — usually `<SettingsPanel embedded/>`. Defaults to null.
+   *
+   * Pass a FUNCTION to opt into the per-plate scope toggle (shown with more than one plate): in plate scope
+   * the panel receives the selected plate's EFFECTIVE map and a setter that writes only the changed keys into
+   * {@link ViewportProps.plateSettings}; `meta.overriddenKeys`/`meta.onRevertKey` drive the override badges
+   * (`<SettingsPanel overriddenKeys={...} onRevertKey={...}/>`). In global scope the pair is simply
+   * `settings`/`setSettings`. A plain node keeps the global-only binding.
+   */
   processPanel?: React.ReactNode
+    | ((settings: SlicerSettings, setSettings: React.Dispatch<React.SetStateAction<SlicerSettings>>,
+        meta: { scope: 'global' | 'plate', selectedPlate: number, overriddenKeys: string[],
+                onRevertKey: ((key: string) => void) | null }) => React.ReactNode)
   /** Motion-limits editor, folded into the printer card — usually `<SettingsPanel only={{builder:'TabPrinter::build_kinematics_page'}}/>`. */
   motionPanel?: React.ReactNode
   /**
@@ -99,6 +129,15 @@ export interface ViewportProps {
     plate: number; stats: Record<string, unknown>; gcode: string
     throughput?: { ms: number; kernelMs: number | null; layersPerSecond: number; msPerMsegment: number | null }
   }) => void
+  /**
+   * An all-plates run as it moves: the run map on every change, `null` when none is on. `workers.pool` is how
+   * many slice at once, `workers.kernel` which kernel loaded ('mt' threads / 'st'); each plate carries its state
+   * and its own progress (0..1) and layers/second. Fired several times a second while a run is on.
+   */
+  onSliceRun?: (run: {
+    workers: { pool: number; active: number; kernel: 'mt' | 'st' | null }
+    plates: Record<number, { state: 'queued' | 'busy' | 'done' | 'failed'; progress: number; rate: number }>
+  } | null) => void
 }
 
 /**

package/types/worker.d.ts

@@ -13,6 +13,14 @@ export interface BrushArgs {
   hx: number; hy: number; hz: number
   cx: number; cy: number; cz: number
   radius: number
+  /**
+   * The PREVIOUS sample of this stroke. Present, the kernel paints the capsule swept from there to `(hx,hy,hz)`
+   * instead of a ball at the hit — which is what upstream does between two consecutive mouse positions
+   * (`DoublePointCursor`, GLGizmoPainterBase.cpp:878). A pointer stream is sampled, not continuous, so without it
+   * a fast drag lands as a row of separate blobs. Omit on the first sample of a stroke; a kernel built before the
+   * capsule existed ignores it and paints the ball, so it is safe to always send.
+   */
+  px?: number; py?: number; pz?: number
 }
 
 /**
@@ -56,6 +64,23 @@ export type SlicerRequest =
   | { cmd: 'clear'; states?: PaintState[] }
   /** The painted overlay triangles. `enf`/`blk` always; `states` adds those states. Reply: `overlay`. */
   | { cmd: 'overlay'; states?: PaintState[] }
+
+  /**
+   * What a fill tool WOULD select under the cursor, without marking anything — upstream draws this on every mouse
+   * move while a fill is active (GLGizmoPainterBase.cpp:929) so a click is aimed rather than tried. No state
+   * argument at all: a preview marks nothing, so there is no NONE for a stray boolean to become.
+   * `{clear:true}` drops the standing selection. Reply: `fillPreview`.
+   */
+  | { cmd: 'fillPreview'; facet?: number; hx?: number; hy?: number; hz?: number
+      tool?: PaintTool; angle?: number; clear?: boolean }
+
+  /**
+   * Brush-wide options, set once and read by every stroke and fill — upstream keeps both on the gizmo.
+   * `overhangDeg` restricts painting to facets overhanging by more than that angle (`0` = off, the default);
+   * `clipPlane` is the section plane `[nx, ny, nz, offset]` in KERNEL coords that every cursor clips against
+   * (`null` turns it off), which is the only way a brush reaches an interior surface. Reply: `paintMode`.
+   */
+  | { cmd: 'paintMode'; overhangDeg?: number; clipPlane?: [number, number, number, number] | null }
   /**
    * Legacy single-object SLA (resin) slice. `params` accepts a JSON string or an object (this path parses either). Same reply stream as
    * a slice: `progress` and `layer` while it runs, then `done` (stats only; layers arrived as `layer`) — or `error`.
@@ -73,7 +98,8 @@ export type SlicerRequest =
   | { stl: ArrayBuffer; params: string | object }
 
 export type SlicerResponse =
-  | { type: 'warm' }
+  /** `kernel` says which variant loaded: 'mt' under crossOriginIsolated, 'st' otherwise (or after an mt load failure). */
+  | { type: 'warm'; kernel: 'mt' | 'st' | null }
   | { type: 'prepared'; facets: number; kept: boolean }
   /**
    * `enf`/`blk` are the counts for states 1 and 2 and are always present, so a listener predating the
@@ -83,6 +109,9 @@ export type SlicerResponse =
   /** `supported: false` from a kernel built before the export binding existed — it does not throw. */
   | { type: 'paintExport'; supported: boolean; facets: number[]; hex: string }
   | { type: 'overlay'; enf: Float32Array; blk: Float32Array; overlays?: Record<number, Float32Array> }
+  /** `supported` false on a kernel built before the preview existed; `tris` is flat x,y,z, 3 vertices per triangle. */
+  | { type: 'fillPreview'; supported: boolean; tris: Float32Array }
+  | { type: 'paintMode'; ok: boolean }
   /**
    * Sent once, unprompted, by the multithreaded kernel only: the address of the support-progress counter and of
    * the cancel flag, inside a SharedArrayBuffer. Writing 1 to the cancel flag stops a slice the worker is

package/viewer/README.md

@@ -130,6 +130,8 @@ Every panel can be switched off, and the values the component owns can be seeded
 - **`onSliced`** — `{plate, stats, gcode, throughput}` when a slice is cached. Switching plate tabs does not
   re-fire it. `throughput` sits beside `stats` rather than inside it, because that is where the engine puts it:
   it is measured around the call, not reported by the kernel.
+- **`onSliceRun`** — an all-plates run as it moves: `{workers: {pool, active, kernel}, plates: {[i]: {state,
+  progress, rate}}}` on every change, `null` between runs. For a host drawing its own per-plate progress.
 
 `sliceRate` is live throughput — layers finished per second over a 250ms window, `0` between slices, and shown in
 the slice bar as well. When it appears depends on the technology, because the two publish per-layer news at
@@ -180,6 +182,26 @@ arrows and Delete working.
 | `Z` · `B` | Zoom to all · zoom to bed |
 | `Esc` | Back to Prepare |
 
+While a brush is open these take over the same letters — the object shortcuts come back the moment it closes.
+
+| Painting | |
+| --- | --- |
+| `C` · `S` | Brush shape: circle (the visible surface) · sphere (reaches through a thin wall) |
+| `F` · `B` · `T` | Smart fill · bucket fill · single triangle |
+| `V` · `H` | Lock the stroke to a vertical · horizontal line — press again to release |
+| `1`…`9` | Paint with that filament (material brush only) |
+| `Shift + drag` | Erase instead of paint |
+| Drag off the model | Rotate the camera — a press that misses the model is not the brush's, so orbiting never means closing it |
+| `Ctrl/⌘ + wheel` | Brush radius, or the fill angle for a fill tool — the bare wheel stays the camera zoom |
+| `Alt + wheel` | Scrub the section plane, which is what lets a brush reach a surface inside the model |
+| `Esc` | Close the brush, and put back whatever the section plane cut away |
+
+The brush draws itself while it is open — a ring for the circle cursor, a translucent ball for the sphere — and a
+fill tool shades what a click would flood before you click it. A drag paints the **capsule** swept between samples
+rather than one ball per sample, so a fast stroke is continuous instead of a row of blobs. A press that misses the
+model falls through to the camera, so the view can be turned mid-paint without closing the brush. The support brush also
+offers *on overhangs only*, which restricts every stroke to facets steeper than the support threshold.
+
 Mouse selection follows upstream's rules: a plain click **replaces** the selection, `Ctrl/⌘ + click` adds or
 removes, a plain click on something already selected **keeps** the set (which is what makes dragging several
 objects work), `Shift + drag` is a box select, and clicking empty space clears. Alt is not a de-select, in
@@ -321,7 +343,53 @@ Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-No headers → falls back to the single-threaded kernel. Nothing else to change.
+No headers → falls back to the single-threaded kernel. Nothing else to change. Which one loaded is shown as a
+badge (`mt`/`st`) beside the Workers select in the slice menu, and the `warmup()` client call resolves with it —
+the two are a measured 9.8x apart on a 3M-facet model, which is too much to leave to the console.
+
+### Slicing several plates at once
+
+**All plates** in the slice menu drains the plates through a pool of workers instead of one after another. The
+**Workers** select beside it sets the pool: *Auto* is half the cores on the threaded kernel and one per core on the
+single-threaded one, capped at the plate count and by model size (below); the select offers every value up to
+that memory cap and nothing past it, because past it the tab itself dies (measured: five workers on a 143MB
+model), which nothing in the page can catch. The plate tabs show each plate's state (queued, slicing with its own percentage, done, failed)
+independently of which one is selected, and the slice bar lists them on one row. Cancel stops every worker. A worker that dies mid-run (memory, most
+often) is dropped and its plate is re-run alone once the others finish, so a count that was too high for the
+model costs time rather than results; the notice says which plates that happened to.
+
+The numbers behind Auto (node harness, 3M-facet model, 15 cores, 30 plates, wall time against one worker):
+
+| kernel | preset | 3 workers | 5 | 10 | 15 |
+|---|---|---|---|---|---|
+| mt | classic walls, no support | 1.10x | 1.15x | 1.15x | 1.14x |
+| mt | arachne + tree support | 2.08x | 2.60x | 3.16x | 3.31x |
+| st | classic walls, no support | — | — | — | 7.2x (14 workers) |
+
+The gain is the kernel's serial share: with classic walls one worker already keeps ~77% of the cores busy, with
+arachne (whose emission pass runs serial) and tree support far less, and the extra workers fill that. More workers
+than cores gained nothing (17 = 15), and no count ever made a run slower — what a worker costs is memory: each
+holds its own copy of the model and its own wasm heap, measured 2.5GB for one, 8.8GB for five and 11.6GB for
+fifteen on that model. That is why Auto stops at half the cores and why the select goes higher only by hand.
+Three things were measured NOT to matter and are deliberately absent: giving each worker a thread budget, slicing
+the largest plate first, and whether the count divides the plate count. The value is `slice_workers` in the
+settings map (0 = Auto), a viewer knob like `sla_antialias`, and it does not reach a 3mf.
+
+The browser is tighter than that harness, because every worker's wasm heap lives in the one renderer process that
+already holds each plate's STL buffer and three.js geometry. Measured in Chromium on the same 143MB-STL model
+over nine plates (classic preset, 15 cores):
+
+| workers | wall | Chromium RSS peak |
+|---|---|---|
+| 1 | 17.8s | 10.4GB |
+| 2 | 15.7s (1.13x) | 13.7GB |
+| 3 | crashed the tab once; 18.7s once | 10.2GB |
+| 8 (Auto by cores) | crashed the tab | 11.6GB |
+
+So Auto is also capped by model size — a worker's heap is taken as 12x the STL it slices (node measured ~1.7GB
+for 143MB) against a 4GB pool budget, which gives 2 for that model and does not bind below ~40MB per plate. A
+manual count is capped the same way. What the browser has NOT measured yet is
+the arachne + tree-support preset, where the harness gains were largest.
 
 ## Bundler notes