three-slicer-viewer 0.2.5

package/COMPONENTS.md

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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kimgh06
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# three-slicer-viewer
+
+The 3D-printing viewer without the slicer: model loading (STL/OBJ/3MF/AMF/PLY), G-code parsing, GPU toolpath
+rendering, the settings transforms, and the React `<Viewport/>` itself. **MIT licensed** — usable in closed-source
+commercial products.
+
+This is [`three-slicer`](https://www.npmjs.com/package/three-slicer) with the kernel taken out. It displays and
+exports; it does not slice. Slicing is plugged in through two props — `slicer` (a hook driving a kernel) and
+`catalog` (vendor presets) — which `three-slicer/viewer` supplies. Install `three-slicer` for that, and note that
+doing so puts your application under AGPL.
+
+## The viewer
+
+```jsx
+import Viewport from 'three-slicer-viewer'
+
+// A display-only viewer: opens models and G-code, no kernel, no presets. Pass `slicer` and `catalog` to add them.
+<Viewport settings={settings} setSettings={setSettings} gcode={gcodeText} />
+```
+
+## Slicing, if you bring a kernel
+
+```jsx
+import Viewport, { useSlicer } from 'three-slicer-viewer'
+import { makeSlicerWorker } from 'three-slicer/client'      // AGPL — the WASM kernel's worker; this is the step that changes your licence
+import { bundledCatalog } from 'three-slicer/settings'      // AGPL — OrcaSlicer's vendor presets
+
+const slicer = (deps) => useSlicer({ ...deps, makeWorker: makeSlicerWorker })   // module-level: it is a hook
+<Viewport slicer={slicer} catalog={bundledCatalog} … />
+```
+
+`useSlicer` is this package's; it only needs a worker that speaks its protocol. `three-slicer` ships one.
+
+## The settings form
+
+```jsx
+import SettingsPanel from 'three-slicer-viewer/components'
+
+// Bare: fields labelled by key, nothing disabled. Pass `schema`, `uiTree` and `toggle` for labels, tabs and
+// enable/disable rules — three-slicer/components does that with OrcaSlicer's data; a host may pass its own.
+<SettingsPanel settings={settings} setSettings={setSettings} />
+```
+
+## Rendering without React
+
+```js
+import { parseGcode } from 'three-slicer-viewer/gcode'
+import { buildSegmentData, makeToolpath, computeColors } from 'three-slicer-viewer/toolpath'
+import * as THREE from 'three'
+
+const { layers, stats } = parseGcode(gcodeText)          // any slicer's output
+const data = buildSegmentData(layers, 0.4)               // -> GPU attribute buffers
+const handle = makeToolpath(THREE, data)                 // -> { mesh, travLines, ... }
+scene.add(handle.mesh, handle.travLines)
+
+handle.setLayerRange(0, 90)                              // cut the print open
+handle.setColors(computeColors(data, 'speed', ctx).color) // recolour without a rebuild
+```
+
+- Reads G-code from OrcaSlicer, PrusaSlicer, Cura and this kernel — roles, widths, tool changes, arcs.
+- Draws one instanced call for the whole plate, with per-role, per-tool and heatmap colouring.
+- `three`, `react` and `react-dom` are **optional peers**. The main entry is the React viewer; `/toolpath` and
+  `/gcode` import neither React nor three (`makeToolpath` takes the THREE namespace as an argument), so a
+  headless consumer pulls in no renderer at all.
+
+## Licensing
+
+MIT. It depends on nothing AGPL, which a check in this repository enforces rather than documents
+(`packages/viewer/test_license_boundary.mjs`).
+
+The implementation was written from [`TOOLPATH_SPEC.md`](./TOOLPATH_SPEC.md), a functional contract, rather
+than derived from any upstream slicer. The reasoning and evidence are in
+[`../packages/PROVENANCE.md`](../packages/PROVENANCE.md); the plan it came from is
+[`../packages/RELICENSE.md`](../packages/RELICENSE.md).
+
+Published as a locked pair with `three-slicer`: both carry the same version, and `three-slicer` pins this
+package exactly, so a combination that was never built together cannot be resolved.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+`three-slicer-viewer` is licensed MIT (`LICENSE`). It contains no code from OrcaSlicer, PrusaSlicer or any other
+slicer — the provenance audit behind that statement is `../packages/PROVENANCE.md`.
+
+## Peer dependencies (not bundled or redistributed)
+
+| Package | License | Used for |
+| --- | --- | --- |
+| three | MIT | the scene, and `three/examples/jsm/libs/fflate.module.js` for zip/unzip in the 3mf and SL1 codecs |
+| react, react-dom | MIT | `<Viewport/>` and `<SettingsPanel/>`; the `/toolpath` and `/gcode` entries need neither |
+
+All three are optional peers: a consumer that only parses G-code or builds toolpath geometry installs none of them.
+
+## Data
+
+`data/config-schema-lean.json`, `data/ui-tree-keys.json` and `data/preset-keys.json` are option-key lists, types,
+defaults and layout flags extracted from OrcaSlicer's configuration — facts about an option set, carrying none of
+its authored text (labels, tooltips) and none of its vendor preset values. Those stay with `three-slicer`.

package/TOOLPATH_SPEC.md

@@ -0,0 +1,173 @@
+# Toolpath renderer — functional specification
+
+What the toolpath renderer must do, stated as a contract. Written so the four files listed in
+[../PROVENANCE.md](../PROVENANCE.md) §2 can be reimplemented **without reference to the existing code or to
+any upstream slicer** — see [../RELICENSE.md](../RELICENSE.md) for why that matters.
+
+Everything here was derived from the published types (`types/viewer-toolpath.d.ts`), the consumers, and a
+recorded run of the present implementation (`test_toolpath_contract.mjs`). No upstream source was consulted
+in writing it, and none is needed to satisfy it.
+
+## 1. The job
+
+A slice result is a list of layers. Each layer holds a flat array of straight extrusion segments in
+millimetres. The renderer turns that into something a GPU can draw as solid beads of plastic — one instanced
+draw call for the whole plate — plus the queries the UI needs about it (per-layer counts, colour ranges,
+material shares).
+
+It draws two things: **extrusions** (solid, oriented, coloured) and **travels** (thin lines, hidden by
+default).
+
+## 2. Input
+
+```js
+buildSegmentData(layers, defaultLineWidth) -> SegmentData
+```
+
+`layers[i] = { z, paths, widths }`
+
+- `paths` — a Float32Array, **stride 8**, one segment per 8 floats:
+  `[x0, y0, z0, enc, x1, y1, z1, enc]`, coordinates in mm.
+- `enc` — `role + tool * 16`. Read the role with `& 15` and the tool with `>>> 4`. **This encoding is this
+  repository's own** (the segment stream is the largest array the viewer holds, and a ninth float per vertex
+  would cost 12.5% of it for one small integer). Both endpoints of a segment carry the same `enc`.
+- `widths` — one entry per segment, in mm. A non-positive entry means "unknown": fall back to
+  `defaultLineWidth`.
+- `role 0` is a **travel** move: no plastic, drawn as a line, excluded from every extrusion count and from
+  length accounting.
+
+Roles 1–11 are: 1 wall, 2 sparse infill, 3 solid infill, 4 skirt/brim, 5 support, 6 raft, 7 gap fill,
+8 thin wall, 9 bridge, 10 ironing, 11 prime tower.
+
+Layer height is not in the input. Derive it as the gap to the previous layer's `z`, falling back to a
+sensible default for the first layer.
+
+## 3. Output — `SegmentData`
+
+Field names and types are fixed by `types/viewer-toolpath.d.ts` and by the two consumers that are **not**
+being rewritten (`core/toolpath_views.js`, `use_move_scrub.js`). Everything else is an implementation choice.
+
+| Field | Shape | Meaning |
+| --- | --- | --- |
+| `nSeg` | number | extrusion segments (travels excluded) |
+| `nTrav` | number | travel segments |
+| `nV` | number | vertices in the extrusion stream |
+| `position` | Float32Array | per-vertex geometry input |
+| `hwa` | Float32Array | per-vertex height / width / orientation |
+| `segIndex` | Uint32Array | per-vertex segment identity |
+| `layerSegPrefix` | Uint32Array, length `layerCount + 1` | non-decreasing; `[0] === 0`, `[layerCount] === nSeg` |
+| `travelPos`, `travelPrefix`, `nTrav` | — | the same, for travels |
+| `layerCount` | number | input layer count |
+| `maxAbs` | number | bounds the coordinate magnitude |
+| `hasNaN` | boolean | true if any non-finite value reached the stream |
+| `bbox` | `{min:[x,y,z], max:[x,y,z]}` or `null` | null when there is not a single vertex |
+| `typeLengths` | Float64Array(16) | total extruded length per role, mm |
+| `meta` | see below | per-vertex channels |
+
+`meta` — every array has length `nV`, and a shader reads past its attribute if any disagrees:
+
+| Channel | Type | Contents |
+| --- | --- | --- |
+| `vType` | Uint8Array | the **decoded** role (`enc & 15`), never raw `enc` |
+| `vTool` | Uint8Array | the decoded tool (`enc >>> 4`); untooled input decodes to 0 |
+| `vWidth` | Float32Array | bead width, mm, always > 0 |
+| `vHeight` | Float32Array | bead height, mm, always > 0 |
+| `vLayer` | Int32Array | layer index, `0 .. layerCount-1` |
+
+The present implementation uses two vertices per segment with `position` and `hwa` as vec4 attributes and
+`segIndex` as 2 entries per vertex. **A reimplementation may choose differently**, provided `meta`, `nV` and
+the fields above stay consistent with each other, because `computeColors` allocates `nV * 4` colours and
+`makeToolpath` consumes what `buildSegmentData` produced.
+
+Degenerate input must be survived, not crashed: no layers gives zero counts and `bbox === null`; a
+zero-length segment must not produce NaN.
+
+## 4. Geometry
+
+Each extrusion segment is drawn as a solid bead: a cross-section swept along the segment, oriented to the
+direction of travel, sized by that segment's width and height. One instanced draw call covers the plate.
+
+Requirements:
+
+- The bead is **centred on the extrusion path in z** — the toolpath's z is the nozzle position, and plastic
+  sits below it. The recorded run shows a layer at `z = 0.2` producing a bbox z of `0.1 .. 0.3` for a
+  0.2 mm layer: the bead spans half a layer height either side.
+- Orientation follows the segment direction in the XY plane.
+- Width and height come from `meta`, per vertex, so two segments in one draw call can differ.
+
+`makeToolpath(THREE, data) -> ToolpathHandle` builds the scene objects. The `THREE` namespace is **passed
+in, never imported** — that is what guarantees the consumer's own three.js instance is used, and it is why
+this module has no dependency of its own.
+
+```
+mesh              the extrusions
+travLines         the travels (THREE.LineSegments)
+setLayerRange(lo, hi)   show only layers lo..hi inclusive
+setVisibleLayers(n)     === setLayerRange(0, n - 1)
+setTravelVisible(bool)  travels start hidden
+setColors(Float32Array) swap the per-vertex colours in place, without rebuilding geometry
+dispose()               release GPU resources
+nSeg, layerCount        mirrored from the data
+```
+
+`setColors` must not rebuild the mesh: changing the view type is interactive and happens on every dropdown
+change.
+
+## 5. Colour
+
+`computeColors` (in `core/toolpath_views.js`, **not** part of the rewrite) produces a `Float32Array(nV * 4)`
+with the colour packed into the `.r` component of each vertex. The rewrite must supply the primitives it
+uses:
+
+| Export | Contract |
+| --- | --- |
+| `packColor([r,g,b])` | components 0..1 -> `r<<16 \| g<<8 \| b`; exact in float32 below 2^24, and the inverse of `hexToRgb` for any 6-digit hex |
+| `hexToRgb('#rrggbb')` | -> `[r,g,b]` in 0..1 |
+| `TYPE_COLOR` | role -> `[r,g,b]`; must cover every role in `TYPE_LABEL` |
+| `TYPE_LABEL` | role -> display name (§2's list) |
+| `TOOL_COLOR` | categorical per-extruder colours; non-empty, indexed **modulo its length** — a machine may have more extruders than entries |
+| `DEFAULT_RANGES_COLORS` | an 11-stop heatmap for continuous views |
+| `rangeColorAt(v, lo, hi, palette)` | value -> interpolated colour between adjacent stops |
+
+**`rangeColorAt` must clamp both ends.** The present implementation clamps the high end and *extrapolates*
+below the low end, returning negative components — out of gamut. It is latent today because `computeColors`
+derives `lo`/`hi` from the data, so no value is ever below `lo`; `test_toolpath_contract.mjs` records it and
+will report it as fixed once the rewrite lands.
+
+The colour values themselves are a free choice. Pick a palette that reads well; there is no external
+consumer that depends on a specific hue, only on the shape of these APIs.
+
+## 6. Queries
+
+`roleRatios(typeLengths)` — length share per role, as
+`[{ type, label, pct, color }]`, **descending by `pct`**, summing to 100, one entry per role with non-zero
+length. The kernel exposes no per-role time, so length stands in for it.
+
+The move-scrub queries, consumed by `use_move_scrub.js` and pinned by `test_move_scrub.mjs`:
+
+- `layerMoveCount(data, layer)` — moves in one layer
+- `topMoveLayer(data, lo, hi)` — the topmost visible layer in a range
+- `moveCursor(data, layer, at)` — where the nozzle is, `at` moves into `layer`, plus how much of each draw
+  list that accounts for
+
+## 7. Shaders
+
+A vertex and a fragment shader, GLSL ES 3.0, used through a raw shader material. The vertex shader expands
+each instance into the oriented bead from the per-vertex attributes; the fragment shader shades it.
+
+Constraints:
+
+- Attribute layout is the rewrite's own choice, provided the shaders and `makeToolpath` agree.
+- Per-vertex colour arrives packed in one float (see §5) and is unpacked in the shader.
+- Layer-range visibility must be a **uniform**, not a geometry rebuild — `setLayerRange` is dragged.
+
+## 8. How to know it works
+
+1. `node packages-mit/test_toolpath_contract.mjs` — the contract, plus a printed snapshot to diff against
+   the recorded run. Exact float equality is **not** expected; counts, strides, encodings, ranges and length
+   accounting are.
+2. `node packages-mit/test_move_scrub.mjs` — the scrub queries.
+3. `npm run test:viewer` — everything, including the license boundary check.
+4. **Look at it.** Build the three demos that consume this API
+   (`examples/{instant-quote,cad-embed,farm-dashboard}`) and open them. A static check cannot tell you a
+   shader is wrong; a bead facing the wrong way, z-fighting, or a black plate will only show on screen.