three-slicer 0.2.2 → 0.2.4

package/types/viewer.d.ts

@@ -52,6 +52,37 @@ export interface ViewportProps {
    * shown on the selected plate; the kernel is never started. While it is set, auto re-slice leaves that plate alone.
    */
   gcode?: string | null
+  /**
+   * An `.sl1` archive rendered as a raster preview — the SLA half of {@link ViewportProps.gcode}'s contract: it
+   * lands on the selected plate and the kernel is never started. Set both and the G-code wins; one plate holds
+   * one artifact.
+   *
+   * Two things it does that `gcode` does not. It writes to your `settings` — the archive's own job description,
+   * `printer_technology` included, because an .sl1 opened in an FFF session has to switch it. And it reconstructs
+   * a surface from the masks in the background, so the preview fills in a moment after the layers appear.
+   *
+   * Re-injects whenever the value's IDENTITY changes, so hold the File/buffer in state rather than building it
+   * during render — a fresh `new Uint8Array(...)` each render re-imports each render. `{name, data}` exists
+   * because the name is the import notice's subject and the filename a re-export hands back.
+   */
+  sl1?: File | Blob | ArrayBuffer | Uint8Array | { name?: string, data: ArrayBuffer | Uint8Array } | null
+  /**
+   * Content imported once on mount, through the same extension dispatch as a drop: models (STL/OBJ/3MF/AMF/PLY —
+   * a 3mf project applies its settings, plates and painting), `.sl1` raster archives, and preset files
+   * (`.json` / `.orca_printer` / `.orca_bundle` / `.orca_filament` / `.zip`). The `{name, data}` form exists
+   * because the dispatch runs on the file NAME's extension. Deliberately mount-only — recreating the array on a
+   * later render does not re-import; runtime loading is the picker, drop, or a remount.
+   */
+  files?: Array<File | { name: string, data: ArrayBuffer | Uint8Array }>
+  /**
+   * A token whose identity CHANGE requests one slice of the current plate — the host's Slice button:
+   * keep a counter in state and bump it. The mount value is inert (0 and null both slice nothing), so is
+   * setting it back to `null`. Ignored while a `gcode`/`sl1` injection holds the plate or the scene is
+   * empty — the same conditions under which the built-in slice bar is not pressable. A change while a
+   * slice is running cancels it and re-slices: the last request wins.
+   */
+  sliceRequest?: number | string | object | null
+
   /** Initial filament colours (hex), one per extruder. Defaults to the built-in T1/T2 pair. */
   defaultExtruderColors?: string[] | null
   /**
@@ -62,7 +93,12 @@ export interface ViewportProps {
   /** Every value change in one channel. See {@link ViewportEvent}. */
   onEvent?: (event: ViewportEvent) => void
   /** A finished slice, fired where the result is cached — switching plate tabs does not re-fire it. */
-  onSliced?: (result: { plate: number; stats: Record<string, unknown>; gcode: string }) => void
+  /** `throughput` is how fast the slice ran — see `SliceThroughput` in the engine entry. Absent on a kernel
+   *  result that carried none (a cached plate re-announced from before the field existed). */
+  onSliced?: (result: {
+    plate: number; stats: Record<string, unknown>; gcode: string
+    throughput?: { ms: number; kernelMs: number | null; layersPerSecond: number; msPerMsegment: number | null }
+  }) => void
 }
 
 /**
@@ -97,6 +133,9 @@ export type LockablePanel =
 export type ViewportPanel =
   | 'topBar' | 'gizmoRail' | 'objectToolbar' | 'paintPanel' | 'statsCard' | 'plateBar' | 'emptyHint' | 'status'
   | 'sidebar' | 'printerCard' | 'filamentCard' | 'objectList' | 'previewControls' | 'processCard' | 'sliceBar'
+  /** The horizontal move scrub under the canvas — how far into the top shown layer the print has got. Preview
+   *  and FFF only: a resin layer is cured in one exposure and has no intra-layer order to walk. */
+  | 'moveBar'
   /** The over-the-bed warning, shown in Prepare when something leaves the printable area. */
   | 'bedWarn'
   /** The prime tower card. Only rendered anyway once a second filament exists. */
@@ -115,10 +154,20 @@ export type ViewportEvent =
   | { type: 'slicing'; value: boolean }
   /** 0..1. Fires several times a second while slicing — throttle on the host side if that matters. */
   | { type: 'progress'; value: number }
+  /**
+   * Live throughput: layers finished per second over a 250ms window, `0` between slices. An SLA slice reports it
+   * throughout. An FFF slice reports it only once the emission pass begins streaming layers — the earlier passes
+   * publish no per-layer progress, so nothing is measured there and none is invented. For the whole-slice figure
+   * use `throughput` from `onSliced`.
+   */
+  | { type: 'sliceRate'; value: number }
   | { type: 'viewType'; value: 'feature' | 'speed' | 'height' | 'width' | 'fan' | 'temp' | 'filament' }
   | { type: 'paintMode'; value: 'off' | 'enforcer' | 'blocker' | 'material' }
   | { type: 'layerCount'; value: number }
   | { type: 'layerRange'; value: { lo: number; hi: number } }
+  /** The move scrub's position within the top shown layer; `max` is that layer's move count, extrusions and
+   *  travels together. Not fired while the whole layer is shown. */
+  | { type: 'moveScrub'; value: { at: number; max: number } }
   | { type: 'error'; value: string }
   | { type: 'notice'; value: string }
 

package/types/worker.d.ts

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

@@ -38,9 +38,10 @@ Slice parameters are derived from `settings` via `three-slicer`'s schema mapping
 
 A `.3mf` written by a slicer (OrcaSlicer/BambuStudio save, MakerWorld download) imports as a **project**: plate layout, project settings, and support/material painting are restored, not just the meshes. Where a facet carries both paint kinds, material paint wins and the dropped support paint is reported.
 
-Props: `settings`, `setSettings`, and three optional React-node slots rendered in the right sidebar —
-`processPanel` (the process card), `motionPanel` (folded into the printer card) and `filamentPanel`
-(folded into the filament card, next to the material picker).
+Props: `settings`, `setSettings`, and three optional sidebar slots — `processPanel` (the process card) and
+`motionPanel` (folded into the printer card) take a React node; `filamentPanel` (folded into the filament card,
+next to the material picker) takes a **function** `(settings, setSettings) => ReactNode`, because the filament
+card binds each extruder's per-extruder values.
 
 Subpath exports for custom UIs (framework-free, no React):
 - `three-slicer/viewer/toolpath` — GPU toolpath renderer (`buildSegmentData`, `makeToolpath`, view-type colorers)
@@ -63,25 +64,88 @@ Every panel can be switched off, and the values the component owns can be seeded
 - **`panels`** — `{name: false}` hides one. Everything is visible by default, so a host only ever opts out and a
   panel added in a later version does not vanish for hosts that listed the ones they wanted. `sidebar: false` drops
   the whole right column; the rest are `topBar`, `gizmoRail`, `objectToolbar`, `paintPanel`, `statsCard`, `plateBar`,
-  `emptyHint`, `status`, `printerCard`, `filamentCard`, `resinCard`, `objectList`, `previewControls`, `processCard`,
-  `sliceBar`. Which of `filamentCard`/`resinCard` renders follows the printer profile's technology: a profile whose
+  `emptyHint`, `status`, `printerCard`, `filamentCard`, `resinCard`, `towerCard`, `objectList`, `previewControls`,
+  `processCard`, `sliceBar`, `moveBar`, `bedWarn` (the off-bed warning strip). Which of `filamentCard`/`resinCard` renders follows the printer profile's technology: a profile whose
   `printer_technology` says SLA swaps the filament card (and the prime tower, and the painting brushes) for the
   resin card, and slicing routes to the kernel's `slice_sla` — PrusaSlicer's ported support/pad chain — with an
   `.sl1` export instead of G-code (portrait masks, like every SL1-family machine). The preview lifts the model by
   `stats.lift_layers` (pad + elevation), and a request the port does not cover (hollowing, organic trees)
   surfaces as a typed error instead of a wrong print.
+  An `.sl1` can also be OPENED (file picker or drag & drop). This viewer's own exports carry a SCENE sidecar
+  (`Metadata/threeslicer_scene.bin`: the model STL plus the support and pad meshes the preview was showing, ~3%
+  of the archive), so reopening one shows the exported surface ITSELF — no reconstruction, nothing approximated,
+  and the whole import lands in ~0.3s. A foreign SL1 has no such record, and there its SHAPE is reconstructed
+  from the masks —
+  every layer streamed through surface nets in workers (six producers turning masks into occupancy slices, one
+  sequential consumer sweeping them). It runs in TWO passes: a quarter-resolution one lands a real shaded mesh
+  in well under a second, then the full one replaces it (measured 0.7s and 4.2s on a 1095-layer archive), at the archive's own layer height in z and ~0.12mm
+  in xy, with the anti-aliased mask grays interpolated for sub-voxel edges and both the surface and its normals
+  relaxed (the layer ripple a mask grid leaves behind is largely a shading artefact) — and shown as a solid mesh on the
+  selected plate, with the layer slider section-cutting it like any sliced result. While the reconstruction
+  runs a translucent stack of sampled masks stands in, until the coarse pass replaces it.
+  Colours: a mask records what cures, not which pixels were model, support or pad — so this viewer's own
+  exports carry a role sidecar (`Metadata/threeslicer_roles.bin`, the support/pad segments per layer; every
+  other consumer ignores the unknown member) and reconstruct in the sliced preview's three colours. A foreign
+  SL1 has no such record and reconstructs in one colour. Opening one applies what the archive states —
+  `printer_technology` first of all, then the exposure family, the layer height and the pixel grid read off a
+  mask header — so a file opened in a fresh FFF session switches the whole route to SLA instead of stranding
+  resin masks on a filament bed. The one number it cannot supply is the display's PHYSICAL size: millimetres
+  appear nowhere in an SL1, so the preview is scaled by the printer set in the viewer and the import notice says
+  so. Export hands an imported archive back byte-identical rather than re-rasterizing empty geometry.
 - **`gcode`** — G-code text drawn on the selected plate instead of a slice result. `parseGcode` recovers roles from
   `;TYPE:` (OrcaSlicer/PrusaSlicer/Cura), from `;_EXTRUSION_ROLE:` tags and from this kernel's own feature comments;
   bead width comes from `;WIDTH:` or, absent that, from E. What the file never states cannot be recovered: an
   unmarked run reads as wall, and there is no print-time estimate (that needs the machine's acceleration limits).
+- **`sl1`** — the SLA half of that contract: an `.sl1` archive (`File`, raw bytes, or `{name, data}`) rendered as a
+  raster preview on the selected plate, again without starting the kernel. It routes into the same import the
+  picker and a drop use, so it behaves identically — including the two things `gcode` does not do: it writes the
+  archive's own job description into your `settings` (`printer_technology` among them, per the paragraph above),
+  and it reconstructs a surface from the masks in the background. Set both and the G-code wins; one plate holds one
+  artifact. It re-injects on the value's IDENTITY, so hold the File in state rather than rebuilding it each render.
+- **The move scrub** (`panels.moveBar`) — the horizontal counterpart of the layer slider, under the canvas in
+  Preview: the vertical one picks WHICH layers are shown, this one walks inside the top one. It is upstream's
+  sequential view (`GCodeViewer`'s `update_sequential_view_current`) in this viewer's terms. On an FFF result it
+  cuts that layer at a move — extrusions and travels together, in the order the printer performs them, which the
+  two draw lists do not store and `moveCursor` recovers — and marks where the nozzle is: a solid cone at the
+  current position and a translucent one where the layer ends. Both are fixed SCREEN size and drawn over
+  everything, because a marker that scales with the scene is a speck zoomed out and a marker that respects depth
+  is buried in the bead it is pointing at. Position changes reach the host as the `moveScrub` event.
+  FFF only, and deliberately: mSLA cures a whole layer in one exposure, so a resin layer has no intra-layer
+  order to walk — the same conclusion upstream reaches, PrusaSlicer's SLA preview having a layer slider and no
+  horizontal one.
+- **`files`** — content imported once on mount, through the same extension dispatch as a drop: models and 3mf
+  projects, `.sl1` archives, and preset files. Mount-only on purpose — a host that rebuilds the array each render
+  must not re-import its models; runtime loading stays with the picker and drop.
+- **`sliceRequest`** — the host's Slice button: a token whose identity change requests one slice of the current
+  plate. The mount value is inert, so hold a counter in state and bump it. Ignored under the same conditions
+  the built-in slice bar is not pressable (empty scene, an injected `gcode`/`sl1` plate); a change during a
+  running slice cancels and re-slices, so the last request wins.
 - **`defaultExtruderColors`**, **`defaultAutoSlice`** — initial values for state the component owns. Unlike the
   in-app toggle, `defaultAutoSlice` also performs the *first* slice, which is what makes a panel-less embed able to
   slice at all.
 - **`onEvent`** — one channel for every change: `canvasMode`, `objects`, `selectedPlate`, `plateCount`,
-  `extruderColors`, `autoSlice`, `slicing`, `progress`, `viewType`, `paintMode`, `layerCount`, `layerRange`,
-  `error`, `notice`. Initial values are not announced — the host passed them. `progress` fires several times a
-  second while slicing.
-- **`onSliced`** — `{plate, stats, gcode}` when a slice is cached. Switching plate tabs does not re-fire it.
+  `extruderColors`, `autoSlice`, `slicing`, `progress`, `sliceRate`, `viewType`, `paintMode`, `layerCount`,
+  `layerRange`, `moveScrub`, `error`, `notice`. Initial values are not announced — the host passed them.
+  `progress` and `sliceRate` fire several times a second while slicing.
+- **`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.
+
+`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
+opposite ends of the run:
+
+- **SLA** reports it throughout: its progress counter is linear in layers. (Its layer *stream* is not usable for
+  this — `slice_sla` builds the whole scene and then drains the sink, measured as 1095 layer messages inside a
+  22ms burst at the end of a 2.8s run, which would time the drain rather than the slicing.)
+- **FFF** reports it once the emission pass starts streaming layers. PASS1 publishes per-mille of itself rather
+  than a layer count (the total only arrives when it ends), and surfaces and support publish nothing per layer,
+  so there is nothing to measure before that and nothing is invented. Measured on a 38MB model: a 4.0s slice,
+  2.8s of it PASS1, the rate shown for the final 0.6s. On a support-heavy model emission is a much larger share.
+
+The whole-slice figure is `throughput` on `onSliced`, and it is present on both technologies — wall milliseconds,
+the kernel's own share, layers/second, and ms per million segments. It reads lower than the live figure whenever
+the live one covers only part of the run.
 
 ## Keyboard and mouse
 
@@ -116,6 +180,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
@@ -209,8 +293,8 @@ download.
 ### Taking the saves
 
 The save buttons are inside the component, so `onExport` is the only way to send a file somewhere other than the
-browser's download folder. It sees the 3mf project, the STL and each plate's G-code. Return truthy to say you
-handled it:
+browser's download folder. It sees every save: the 3mf project, the STL, each plate's G-code, an SLA plate's
+`.sl1` archive, and preset files. Return truthy to say you handled it:
 
 ```jsx
 <Viewport onExport={(file, filename) => { uploadToServer(file, filename); return true }} />
@@ -223,11 +307,23 @@ Return nothing and the download happens as well, which is useful for logging wha
 The component owns its scene, and the props are the whole interface — there is no ref, no imperative handle, and no
 `models` prop. Worth knowing before you design around it:
 
-- **Models enter through the UI only** — the file dialog or drag and drop. A host cannot hand a mesh in, and cannot
-  remove or transform one. What it *can* do is watch: the `objects` event reports `{id, name, extruder, visible}`
-  for every object as the set changes.
-- **Slicing is triggered from the UI or by `defaultAutoSlice`**, which unlike the in-app toggle also performs the
-  first slice — that is what makes a panel-less embed able to slice at all. The result arrives on `onSliced`.
+- **Models enter through the UI, or once at mount through `files`** — after mount, runtime loading stays with the
+  file dialog and drag and drop. A host cannot remove or transform an object, or hand a mesh in mid-session. What
+  it *can* do is watch: the `objects` event reports `{id, name, extruder, visible}` for every object as the set
+  changes.
+- **Slicing is triggered from the UI, by `defaultAutoSlice`, or by bumping `sliceRequest`** — a token prop whose
+  identity change requests one slice of the current plate (the mount value is inert), which is what a host with
+  the built-in chrome hidden wires its own Slice button to. The result arrives on `onSliced`.
+- **The prime tower stand-in appears only when the plate actually changes tools** — objects assigned to more
+  than one extruder, or material paint reaching extruder 2 or higher. Loading a second filament is not enough:
+  with everything on T1 the slice emits no tool change and builds no tower, so drawing the box would promise one.
+- **A settings change discards every slice result.** Everything a slice puts on screen — the toolpaths, the stats
+  card, the layer slider, the G-code export — describes the settings it ran with, and none of it says so. So when
+  a value in `settings` changes, the results are dropped and the viewer returns to Prepare; with `autoSlice` on
+  the re-slice then fills the empty preview. Two exceptions, neither of which claims to be a slice of these
+  settings: a plate injected through `gcode` / `sl1`, and an opened `.sl1` archive (that import applies the
+  archive's own settings, so invalidating on it would erase what the file was opened to show). Comparison is by
+  value, so a host that rebuilds its settings object every render does not lose its preview to it.
 - **`gcode` is one-way**: pass G-code text and it is drawn on the selected plate instead of a slice result, and
   auto re-slice leaves that plate alone while it is set.
 - Everything else the component owns — camera, selection, plate count, paint state — is reported through `onEvent`