three-slicer 0.1.6 → 0.1.7

package/types/worker.d.ts

@@ -1,3 +1,90 @@
 // three-slicer/worker — the slice worker script. Not a module you import, but the target of
 // `new Worker(new URL('three-slicer/worker', import.meta.url), { type: 'module' })`.
+//
+// The protocol below is the raw message contract. `createSlicerClient()` from `three-slicer/client` wraps it in
+// promises and is the easier way in; these types are here for hosts driving the worker directly, and because the
+// shape has traps that only a written-down contract makes visible — see the slice request and `erase`.
+import type { SliceResult } from '../engine/index.d.ts'
+
+/** Brush geometry shared by paint and erase: the hit facet, the hit point, the camera, the radius. */
+export interface BrushArgs {
+  facet: number
+  hx: number; hy: number; hz: number
+  cx: number; cy: number; cz: number
+  radius: number
+}
+
+/**
+ * Painting state, following OrcaSlicer's own `EnforcerBlockerType`: one enum serving two jobs.
+ * `1` is both the support ENFORCER and Extruder 1, `2` is both the BLOCKER and Extruder 2, `3..16` are
+ * Extruders 3 to 16. `0` (NONE) is deliberately not a value here — see the `erase` command.
+ */
+export type PaintState = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16
+
+/** Selection tools that are not the radius brush. All three take the mesh's own topology instead of a radius. */
+export type PaintTool = 'smart' | 'bucket' | 'triangle'
+
+export type SlicerRequest =
+  /** Load the kernel (and spawn the mt thread pool) ahead of the first slice. Reply: `warm`. */
+  | { cmd: 'warmup' }
+  /**
+   * Register a mesh for painting. `keepPaint` says this is the same model in a new place, so the marks carry
+   * over — the reply reports whether they actually did. Reply: `prepared`.
+   */
+  | { cmd: 'prepare'; stl: ArrayBuffer; keepPaint?: boolean }
+  /**
+   * Paint. With `state` it addresses any extruder; with `enforcer` it stays on the original boolean pair, where
+   * `false` means BLOCKER. `states` asks for those states' counts back. Reply: `painted`.
+   */
+  | (BrushArgs & { cmd: 'paint'; state?: PaintState; enforcer?: boolean; tool?: PaintTool
+                   angle?: number; cursor?: 'sphere' | 'circle'; states?: PaintState[] })
+  /**
+   * Return the brushed facets to the default extruder. Its OWN command rather than `{cmd:'paint', state:0}`:
+   * embind coerces a JS `false` to the int `0` == NONE, and the legacy blocker brush sends exactly that `false`,
+   * so admitting `0` on the state path would let a stray boolean erase silently. Reply: `painted`.
+   */
+  | (BrushArgs & { cmd: 'erase'; tool?: PaintTool; angle?: number; states?: PaintState[] })
+  /**
+   * Load painting out of a 3mf. REPLACES every mark (the kernel's deserialize resets first), so it belongs
+   * immediately after a `prepare` and nowhere else. Reply: `painted`, with `applied`.
+   */
+  | { cmd: 'importPaint'; facets: Int32Array | number[]; hex: string; states?: PaintState[] }
+  /** Every marked facet's split tree, in the CURRENT selector's numbering. Reply: `paintExport`. */
+  | { cmd: 'exportPaint' }
+  /** Wipe every state at once. Reply: `painted`, all zero. */
+  | { cmd: 'clear'; states?: PaintState[] }
+  /** The painted overlay triangles. `enf`/`blk` always; `states` adds those states. Reply: `overlay`. */
+  | { cmd: 'overlay'; states?: PaintState[] }
+  /**
+   * 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.)
+   * Replies: `progress` and `layer` while it runs, then `done` — or `error`.
+   */
+  | { stl: ArrayBuffer; params: string }
+
+export type SlicerResponse =
+  | { type: 'warm' }
+  | { 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
+   * state-addressed protocol keeps working. `counts` appears only when the request named `states`.
+   */
+  | { type: 'painted'; enf: number; blk: number; counts?: Record<number, number>; applied?: number }
+  /** `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> }
+  /**
+   * 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
+   * currently blocked inside. A single-threaded kernel has no shared buffer and never sends this.
+   */
+  | { type: 'supsab'; buf: SharedArrayBuffer; ptr: number; cancelPtr: number }
+  | { type: 'progress'; done: number; total: number }
+  /** One sliced layer, its typed arrays transferred rather than copied. */
+  | { type: 'layer'; z: number; idx: number; gcode: string; paths: Float32Array; widths: Float32Array }
+  /** `result.stats.streamed` says whether the G-code came through `layer` messages or is on the result. */
+  | { type: 'done'; result: SliceResult }
+  | { type: 'error'; error: string }
+
 export {}

package/viewer/README.md

@@ -5,7 +5,7 @@
 ![The Prepare tab — drag-and-drop viewport with the printer, filament and process cards in the right sidebar](../../slice-sidebar.png)
 
 ```bash
-npm i three-slicer     # react, react-dom and three are peer dependencies — npm installs them for you
+npm i three-slicer react react-dom three     # the three are optional peers; the viewer needs all of them
 ```
 
 ```jsx
@@ -14,12 +14,26 @@ import Viewport from 'three-slicer/viewer'
 
 function App() {
   const [settings, setSettings] = useState({})   // OrcaSlicer schema keys; sparse — defaults fill the rest
-  return <Viewport settings={settings} setSettings={setSettings} />
+  // The container matters — see Layout below.
+  return (
+    <div style={{ position: 'relative', width: '100%', height: '100vh' }}>
+      <Viewport settings={settings} setSettings={setSettings} />
+    </div>
+  )
 }
 ```
 
 Styles are injected into the component's Shadow DOM root — nothing to import, and host CSS cannot collide.
 
+## Layout
+
+**Give it a positioned, sized container.** The shadow host is `display: contents`, so it contributes no box of its
+own, and the shell inside is `position: absolute; inset: 0`. It therefore fills the nearest *positioned* ancestor —
+`position: relative` (or absolute/fixed) with a real height. Drop it into a plain static `<div>` and it escapes to
+the initial containing block instead, which usually looks like the viewer covering the whole page.
+
+There is no width or height prop: the component always fills that container, and resizes with it.
+
 Slice parameters are derived from `settings` via `three-slicer`'s schema mapping — pair it with `three-slicer/components`' `<SettingsPanel/>` sharing the same state for a full slicer UI.
 
 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.
@@ -63,6 +77,55 @@ Every panel can be switched off, and the values the component owns can be seeded
   second while slicing.
 - **`onSliced`** — `{plate, stats, gcode}` when a slice is cached. Switching plate tabs does not re-fire it.
 
+## Keyboard and mouse
+
+Which keys are live depends on the tab, and every one is ignored while an input has focus. Letter shortcuts match
+the **physical** key, so they keep working under a non-Latin keyboard layout — with an IME on, the Korean layout
+reports `'ㅁ'` for M, and matching on the character would silently kill every letter shortcut while leaving the
+arrows and Delete working.
+
+| Both tabs | |
+| --- | --- |
+| `Ctrl/⌘ + R` | Slice the current plate |
+| `Ctrl/⌘ + C` / `V` / `X` | Copy · paste · cut the selection |
+| `Ctrl/⌘ + K` or `Ctrl/⌘ + D` | Duplicate |
+| `Ctrl/⌘ + A` | Select all |
+| `Ctrl/⌘ + Z` | Undo — bound to the component root, so it never reaches your app's own Ctrl+Z |
+| `Ctrl/⌘ + Shift + Z` or `Ctrl/⌘ + Y` | Redo |
+
+| Prepare | |
+| --- | --- |
+| `M` or `G` · `R` · `S` | Move · rotate · scale gizmo |
+| `Arrow keys` | Nudge 10mm — `Shift` for 1mm |
+| `PageUp` / `PageDown` | Rotate ±45° |
+| `Delete` / `Backspace` | Remove the selection |
+| `Z` · `B` | Zoom to all · zoom to bed |
+| `Esc` | Cancel the current tool |
+| `?` | Shortcut help overlay |
+
+| Preview | |
+| --- | --- |
+| `↑` / `↓` | Step one layer — `Shift` for ten |
+| `L` · `T` | Single-layer view · travel moves |
+| `Z` · `B` | Zoom to all · zoom to bed |
+| `Esc` | Back to Prepare |
+
+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
+upstream or here.
+
+## Undo and redo
+
+The history covers the viewport's **own** state: object transforms, additions, removals, per-object extruder and
+visibility. Fifty steps, with repeats of the same action inside half a second folded into one — so a held arrow key
+undoes as a single move rather than forty.
+
+What it deliberately does not cover, and why the boundary sits there: `settings` is **yours**, passed in as a prop,
+so nothing inside the component can put it back. Painting is outside it too (restoring a step would need a kernel
+re-`prepare` for every entry), as are the prime tower and the plate count, which write host settings. If you want
+those undoable, undo them on your side of the prop.
+
 ## Materials and painting
 
 The filament card holds **one material per extruder**: add an extruder, pick its colour, and pick its filament preset from the vendor catalog (`filamentPresets()` in `three-slicer/settings` — the shortlist is the printer model's own recommendation, the full list everything compatible). Selecting a row aims the material picker and the settings form at that extruder; the colours feed the object meshes, the prime tower and the preview's **Filament** view type, which colours every segment by the extruder that printed it.
@@ -76,6 +139,97 @@ Two limits to expect while using it:
 
 If you consume `three-slicer/viewer/toolpath` directly, note that the stride-8 role field `paths[k+3]` now carries the printing extruder alongside the role as `role + tool * 16`. Mask it — `& 15` for the role, `>>> 4` for the tool. Streams produced before this encoding are entirely below 16 and decode to their own role with tool 0, so older data still reads correctly.
 
+## Turning behaviour off
+
+`panels` controls what is drawn; `features` controls what the component *does* outside its own box. Same rule —
+opt-out only, everything on unless you say `false`, an unknown key stays on.
+
+```jsx
+<Viewport
+  gcode={text}
+  panels={{ sidebar: false, topBar: false }}
+  features={{ warmup: false, shortcuts: false, logs: false }}
+/>
+```
+
+| Key | Off means |
+| --- | --- |
+| `shortcuts` | No keyboard bindings. They are installed on `window`, so while the viewer is mounted they fire wherever focus is (inputs excepted) — and `Ctrl+C` preventDefaults, which takes a host page's own copy. Turn them off when your app has its own. |
+| `warmup` | The WASM kernel is not loaded on mount. Nothing is downloaded or compiled until something actually slices — which for a `gcode`-only viewer is never, so this is several megabytes and a thread pool you stop paying for. |
+| `drop` | No drag and drop onto the canvas. |
+| `filePicker` | The file dialog never opens, from any of the buttons that open it. |
+| `contextMenu` | No right-click menu. The browser's own menu stays suppressed over the canvas either way — OrbitControls preventDefaults `contextmenu` itself. |
+| `logs` | No console output, from the component or from the slice worker. |
+
+### Read-only panels
+
+A sidebar panel can also be shown but not editable — the shape you want when the host picks the printer, process
+and filament itself and does not want the user changing them. It is a third value on the same `panels` key:
+
+```jsx
+<Viewport
+  settings={presetSettings}
+  panels={{ printerCard: 'readonly', filamentCard: 'readonly', processCard: 'readonly' }}
+/>
+```
+
+Lockable: `sidebar`, `printerCard`, `filamentCard`, `objectList`, `towerCard`, `previewControls`, `processCard`,
+`sliceBar`. `sidebar: 'readonly'` locks the whole column at once; the per-card keys are for mixing, such as a
+locked printer card above a live object list. Every other panel takes `true`/`false` only — a `'readonly'` that
+silently did nothing on half the keys would be worse than not offering it.
+
+The panel is drawn normally and keeps showing real values; it just cannot be clicked, typed into or tabbed to, and
+that includes any node you passed into it (`motionPanel`, `filamentPanel`, `processPanel`). Implemented with the
+`inert` attribute, so it needs Chrome 102+, Safari 15.5+ or Firefox 112+.
+
+**It locks the UI path, not the value.** `settings` is still your prop, and other paths inside the viewer still
+write it — importing a 3mf project applies that project's settings whether or not the cards are locked.
+
+### Printer preset files
+
+The printer card carries **Load** and **Save**. Save writes an OrcaSlicer preset: a machine `.json` on its own, or
+an `.orca_printer` bundle when the settings map also names a process or filament preset (the cards record those as
+`printer_settings_id` / `print_settings_id` / `filament_settings_id`, so nothing extra has to be tracked). Load
+accepts the same set upstream's dialog does — `.json`, `.orca_printer`, `.orca_bundle`, `.orca_filament`, `.zip` —
+and applies every preset it finds, clearing that type's keys first.
+
+`inherits` is followed through the shipped printer catalog, so a vendor file loads with its bed intact; when the
+parent is unknown the file's own values are still applied and the notice says so. Codec details and the reason
+that matters are in the [package README](../README.md#preset-files).
+
+Load opens a file dialog, so it respects `features.filePicker`; Save goes through `onExport` like every other
+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:
+
+```jsx
+<Viewport onExport={(file, filename) => { uploadToServer(file, filename); return true }} />
+```
+
+Return nothing and the download happens as well, which is useful for logging what was saved without changing it.
+
+## What the host cannot drive
+
+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`.
+- **`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`
+  and settable only by the user.
+
+If you need programmatic control over the scene, build on the subpath exports (`three-slicer/viewer/toolpath`,
+`/loaders`, `/gcode`) and `three-slicer/client` rather than on `<Viewport/>`.
+
 ## Multithreaded slicing (automatic)
 
 The engine ships two WASM kernels: single-threaded (default) and `-pthread` multithreaded (~2× wall-clock on layer-parallel wall generation, measured 12× on the wall pass itself). The worker picks the mt kernel automatically when the page is [cross-origin isolated](https://developer.mozilla.org/en-US/docs/Web/API/Window/crossOriginIsolated) — i.e. served with: