three-slicer 0.1.3 → 0.1.4

package/types/settings-keys.d.ts

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by types/gen_settings_types.mjs — DO NOT EDIT.
-// Source: data/config-schema.json (906 keys)
+// Source: data/config-schema.json (923 keys)
 
  /** [x, y] — coPoint family */
 export type Point = [number, number]
@@ -391,6 +391,8 @@ export interface SlicerSettings {
   filament_cost?: number[] | number
   /** Density — (g/cm³) — Filament density, for statistical purposes only. */
   filament_density?: number[] | number
+  /** Deretraction speed — (mm/s) — Speed for reloading filament into the nozzle. Zero means same speed of retraction. */
+  filament_deretraction_speed?: number[] | number
   filament_dev_ams_drying_ams_limitations?: string[] | string
   filament_dev_ams_drying_heat_distortion_temperature?: number[] | number
   filament_dev_ams_drying_temperature?: number[] | number
@@ -433,6 +435,8 @@ export interface SlicerSettings {
   filament_loading_speed?: number[] | number
   /** Loading speed at the start — (mm/s) — Speed used at the very beginning of loading phase. */
   filament_loading_speed_start?: number[] | number
+  /** Long retraction when cut (beta) — Experimental feature: Retracting and cutting off the filament at a longer distance during changes to minimize purge. While this reduces flush significantly, it may also raise the risk of nozzle clogs or other printing problems. */
+  filament_long_retractions_when_cut?: boolean[] | boolean
   /** Filament map to extruder — Filament map to extruder. */
   filament_map?: number[] | number
   /** Filament map plus for multi nozzle — Filament map to the index identified by extruder and nozzle_volume_type */
@@ -478,8 +482,30 @@ export interface SlicerSettings {
   filament_ramming_volumetric_speed?: number[] | number
   /** Hotend change — (mm³/s) — The maximum volumetric speed for ramming before a hotend change, where -1 means using the maximum volumetric speed. */
   filament_ramming_volumetric_speed_nc?: number[] | number
+  /** Retract amount after wipe — (%) — The length of fast retraction after wipe, relative to retraction length. The value will be clamped by 100% minus the retract amount before the wipe value. */
+  filament_retract_after_wipe?: number[] | number
+  /** Retract amount before wipe — (%) — This is the length of fast retraction before a wipe, relative to retraction length. */
+  filament_retract_before_wipe?: number[] | number
   /** length when change hotend — (mm) — When this retraction value is modified, it will be used as the amount of filament retracted inside the hotend before changing hotends. */
   filament_retract_length_nc?: number[] | number
+  /** Only lift Z above — (mm) — If you set this to a positive value, Z lift will only take place above the specified absolute Z. */
+  filament_retract_lift_above?: number[] | number
+  /** Only lift Z below — (mm) — If you set this to a positive value, Z lift will only take place below the specified absolute Z. */
+  filament_retract_lift_below?: number[] | number
+  /** On surfaces — Enforce Z-Hop behavior. This setting is impacted by the above settings (Only lift Z above/below). */
+  filament_retract_lift_enforce?: ('All Surfaces' | 'Top Only' | 'Bottom Only' | 'Top and Bottom')[] | ('All Surfaces' | 'Top Only' | 'Bottom Only' | 'Top and Bottom')
+  /** Extra length on restart — (mm) — When the retraction is compensated after the travel move, the extruder will push this additional amount of filament. This setting is rarely needed. */
+  filament_retract_restart_extra?: number[] | number
+  /** Retract on layer change — This forces a retraction on layer changes. */
+  filament_retract_when_changing_layer?: boolean[] | boolean
+  /** Retraction distance when cut — Experimental feature: Retraction length before cutting off during filament change. */
+  filament_retraction_distances_when_cut?: number[] | number
+  /** Length — (mm) — Some amount of material in extruder is pulled back to avoid ooze during long travel. Set zero to disable retraction. */
+  filament_retraction_length?: number[] | number
+  /** Travel distance threshold — (mm) — Only trigger retraction when the travel distance is longer than this threshold. */
+  filament_retraction_minimum_travel?: number[] | number
+  /** Retraction speed — (mm/s) — Speed for retracting filament from the nozzle. */
+  filament_retraction_speed?: number[] | number
   /** Filament self index — Filament self index. */
   filament_self_index?: number[] | number
   filament_settings_id?: string[] | string
@@ -516,6 +542,14 @@ export interface SlicerSettings {
   /** Vendor — Vendor of filament. For show only. */
   filament_vendor?: string[] | string
   filament_volume_map?: number[] | number
+  /** Wipe while retracting — This moves the nozzle along the last extrusion path when retracting to clean any leaked material on the nozzle. This can minimize blobs when printing a new part after traveling. */
+  filament_wipe?: boolean[] | boolean
+  /** Wipe distance — (mm) — Describe how long the nozzle will move along the last path when retracting. Depending on how long the wipe operation lasts, how fast and long the extruder/filament retraction settings are, a retraction move may be needed to retract the remaining filament. Setting a value in the retract amount before wipe setting below will perform any excess retraction before the wipe, else it will be performed after. */
+  filament_wipe_distance?: number[] | number
+  /** Z-hop height — (mm) — Whenever there is a retraction, the nozzle is lifted a little to create clearance between the nozzle and the print. This prevents the nozzle from hitting the print when traveling more. Using spiral lines to lift z can prevent stringing. */
+  filament_z_hop?: number[] | number
+  /** Z-hop type — Type of Z-hop. */
+  filament_z_hop_types?: ('Auto Lift' | 'Normal Lift' | 'Slope Lift' | 'Spiral Lift')[] | ('Auto Lift' | 'Normal Lift' | 'Slope Lift' | 'Spiral Lift')
   /** File header G-code — G-code written at the very top of the output file, before any other content. Useful for adding metadata that printer firmware reads from the first lines of the file (e.g. estimated print time, filament usage). Supports placeholders like {print_time_sec} and {used_filament_length}. */
   file_start_gcode?: string
   /** Filename format — Users can decide project file names when exporting. */

package/types/settings.d.ts

@@ -17,3 +17,33 @@ export function settingScalar(settings: SlicerSettings | null | undefined, key:
  * not an API consumers read field by field. Expand it when field access is actually needed.
  */
 export function deriveKernelParams(settings: SlicerSettings | null | undefined): Record<string, unknown>
+
+// ---- Lazily loaded presets --------------------------------------------------
+// Both facades hide the column layout of the artifact they wrap; the promise is created once and reused.
+
+export interface ProcessPresetsApi {
+  /** Every key a process preset can set — clear these before applying a different one */
+  keys: string[]
+  /** Preset names compatible with a printer profile, in upstream order */
+  listFor(printerProfileName: string): string[]
+  /** The settings a preset applies, ready to merge. `null` when unknown. */
+  settingsFor(presetName: string): SlicerSettings | null
+}
+export function processPresets(): Promise<ProcessPresetsApi>
+
+/** A material as a picker shows it. `type`/`vendor` are `''` when the profile chain declares neither. */
+export interface FilamentPreset { name: string, type: string, vendor: string }
+
+export interface FilamentPresetsApi {
+  /** Every key a filament preset can set — clear these before applying a different material */
+  keys: string[]
+  /** Every material in the catalog, in upstream order — for a picker shown before any printer is chosen */
+  all(): FilamentPreset[]
+  /** Materials compatible with a printer profile, in upstream order */
+  listFor(printerProfileName: string): FilamentPreset[]
+  /** The vendor's recommended materials for that printer's model — a subset of listFor */
+  recommendedFor(printerProfileName: string): FilamentPreset[]
+  /** The settings a material applies, ready to merge. `null` when unknown. */
+  settingsFor(presetName: string): SlicerSettings | null
+}
+export function filamentPresets(): Promise<FilamentPresetsApi>

package/types/viewer-gcode.d.ts

@@ -0,0 +1,29 @@
+// three-slicer/viewer/gcode — G-code text -> kernel-shaped layer stream (renderable without slicing).
+// Feed the returned layers straight into buildSegmentData (three-slicer/viewer/toolpath).
+
+export interface GcodeLayer {
+  z: number
+  /** Stride 8: [x0,y0,z0,enc, x1,y1,z1,enc] per segment, enc = role + tool*16 (role 0 = travel). */
+  paths: Float32Array
+  /** One entry per segment; 0 means "use the default line width". */
+  widths: Float32Array
+}
+
+export interface ParseGcodeResult {
+  layers: GcodeLayer[]
+  stats: { layers: number; path_segments: number; travel_segments: number; tools: number[] }
+}
+
+export interface ParseGcodeOptions {
+  /** Used to derive bead width from E when the file has no ;WIDTH: comments. Default 1.75. */
+  filamentDiameter?: number
+  /** Bead-height fallback when a layer's height cannot be inferred from z steps. Default 0.2. */
+  defaultLayerHeight?: number
+}
+
+/**
+ * Parses G0/G1/G2/G3 (I/J arcs), G90/G91, M82/M83, G92, T<n>, and the layer/role comment conventions of
+ * OrcaSlicer/PrusaSlicer (;TYPE: ;WIDTH: ;LAYER_CHANGE ;Z:), Cura (;TYPE: ;LAYER:) and this kernel's own output.
+ * Recovery is lossy where G-code carries no data: unknown roles become wall(1), widths are derived from E.
+ */
+export function parseGcode(text: string, opts?: ParseGcodeOptions): ParseGcodeResult

package/types/viewer-toolpath.d.ts

@@ -8,11 +8,17 @@ export const VERTEX_DATA: number[]
 export const TYPE_COLOR: Record<number, number[]>
 export const TYPE_LABEL: Record<number, string>
 
+/**
+ * Per-extruder colors for the Filament view. Categorical, not semantic — the toolpath stream carries a tool index and
+ * nothing about the material, and a machine may have more extruders than entries, so index it modulo its length.
+ */
+export const TOOL_COLOR: number[][]
+
 /** Blue-to-red 11-color heatmap (libvgcode ColorRange.hpp:14) */
 export const DEFAULT_RANGES_COLORS: number[][]
 
 export interface ViewTypeDef {
-  key: 'feature' | 'speed' | 'height' | 'width' | 'fan' | 'temp'
+  key: 'feature' | 'speed' | 'height' | 'width' | 'fan' | 'temp' | 'filament'
   label: string
   /** Whether values are continuous (heatmap). False means a fixed color. */
   cont: boolean
@@ -23,6 +29,8 @@ export const VIEW_TYPES: ViewTypeDef[]
 /** Per-vertex extra data */
 export interface SegmentMeta {
   vType: Uint8Array
+  /** Printing extruder, decoded out of the role field's high bits. Untooled output decodes to 0, i.e. single material. */
+  vTool: Uint8Array
   vWidth: Float32Array
   vHeight: Float32Array
   vLayer: Int32Array

package/types/viewer.d.ts

@@ -9,7 +9,60 @@ export interface ViewportProps {
   setSettings?: React.Dispatch<React.SetStateAction<SlicerSettings>>
   /** Left process-panel slot — usually `<SettingsPanel embedded/>`. Defaults to null. */
   processPanel?: React.ReactNode
+  /** Motion-limits editor, folded into the printer card — usually `<SettingsPanel only={{builder:'TabPrinter::build_kinematics_page'}}/>`. */
+  motionPanel?: React.ReactNode
+  /**
+   * Filament editor, folded into the filament card. Pass a function rather than a node: with more than one
+   * extruder loaded the card projects that extruder's slice of the per-extruder columns and writes the form's
+   * edits back at its index, so the panel must bind to the pair it is given.
+   */
+  filamentPanel?: React.ReactNode
+    | ((settings: SlicerSettings, setSettings: React.Dispatch<React.SetStateAction<SlicerSettings>>) => React.ReactNode)
+  /**
+   * Per-panel visibility. Every panel is visible unless its key is explicitly `false`, so a host only opts out —
+   * and a panel added in a later version does not disappear for hosts that listed the ones they wanted.
+   */
+  panels?: Partial<Record<ViewportPanel, boolean>>
+  /**
+   * G-code text to render instead of a slice result. Parsed into the same layer stream the kernel produces and
+   * shown on the selected plate; the kernel is never started. While it is set, auto re-slice leaves that plate alone.
+   */
+  gcode?: string | null
+  /** Initial filament colours (hex), one per extruder. Defaults to the built-in T1/T2 pair. */
+  defaultExtruderColors?: string[] | null
+  /**
+   * Start with auto re-slice on. Unlike the in-app toggle's original behaviour this also performs the FIRST slice,
+   * which is what makes a panel-less embed able to slice at all.
+   */
+  defaultAutoSlice?: boolean
+  /** 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
 }
 
+/** Panel keys accepted by {@link ViewportProps.panels}. `sidebar: false` hides the whole right column at once. */
+export type ViewportPanel =
+  | 'topBar' | 'gizmoRail' | 'objectToolbar' | 'paintPanel' | 'statsCard' | 'plateBar' | 'emptyHint' | 'status'
+  | 'sidebar' | 'printerCard' | 'filamentCard' | 'objectList' | 'previewControls' | 'processCard' | 'sliceBar'
+
+/** Value changes reported through {@link ViewportProps.onEvent}. Not fired for the initial values. */
+export type ViewportEvent =
+  | { type: 'canvasMode'; value: 'prepare' | 'preview' }
+  | { type: 'objects'; value: Array<{ id: number; name: string; extruder: number; visible: boolean }> }
+  | { type: 'selectedPlate'; value: number }
+  | { type: 'plateCount'; value: number }
+  | { type: 'extruderColors'; value: string[] }
+  | { type: 'autoSlice'; value: boolean }
+  | { 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 }
+  | { 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 } }
+  | { type: 'error'; value: string }
+  | { type: 'notice'; value: string }
+
 declare const Viewport: React.FC<ViewportProps>
 export default Viewport

package/viewer/README.md

@@ -1,6 +1,6 @@
 # three-slicer/viewer
 
-3D slicer viewer as a React component: three.js viewport (orbit/transform gizmos), model import (STL/OBJ/3MF/AMF/PLY + pluggable formats such as STEP, multi-object, drag & drop), Web Worker slicing via `three-slicer`, support painting, multi-plate, and a GPU-instanced volumetric toolpath preview ported from OrcaSlicer's libvgcode (millions of segments in a single draw path, per-feature colors, layer range slider, G-code export).
+3D slicer viewer as a React component: three.js viewport (orbit/transform gizmos), model import (STL/OBJ/3MF/AMF/PLY + pluggable formats such as STEP, multi-object, drag & drop), Web Worker slicing via `three-slicer`, support and material painting, per-extruder filament presets, multi-plate, and a GPU-instanced volumetric toolpath preview ported from OrcaSlicer's libvgcode (millions of segments in a single draw path, per-feature colors, layer range slider, G-code export).
 
 ```bash
 npm i three-slicer/viewer react react-dom three@^0.160.0
@@ -19,11 +19,57 @@ function App() {
 
 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.
 
-Props: `settings`, `setSettings`, `processPanel` (optional React node rendered in the right sidebar).
+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).
 
 Subpath exports for custom UIs (framework-free, no React):
 - `three-slicer/viewer/toolpath` — GPU toolpath renderer (`buildSegmentData`, `makeToolpath`, view-type colorers)
 - `three-slicer/viewer/loaders` — model loaders returning unified triangle soup
+- `three-slicer/viewer/gcode` — `parseGcode(text)`, G-code back into the layer stream the renderer consumes
+
+## Embedding it without the panels
+
+Every panel can be switched off, and the values the component owns can be seeded and watched, so the same
+`<Viewport/>` also works as a bare G-code viewer or as a headless slicer inside another app's UI.
+
+```jsx
+// A G-code viewer: no kernel run, no panels.
+<Viewport gcode={text} panels={{ sidebar: false, topBar: false, gizmoRail: false, plateBar: false }} />
+
+// A headless slicer: the host drives it and takes the result.
+<Viewport panels={{ sidebar: false }} defaultAutoSlice onSliced={({ stats, gcode }) => save(gcode)} />
+```
+
+- **`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`, `objectList`, `previewControls`, `processCard`, `sliceBar`.
+- **`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).
+- **`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.
+
+## 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.
+
+The brush has two targets sharing one shell: **support painting** (enforcer / blocker) and **material painting** (one chip per extruder, plus an eraser that returns facets to the default extruder). They are mutually exclusive, and that is a data constraint rather than a UI choice — upstream's `EnforcerBlockerType` is a single enum in which ENFORCER *is* Extruder1 and BLOCKER *is* Extruder2, so one integer per facet means a support mark and a material mark cannot coexist there.
+
+Two limits to expect while using it:
+
+- Painting a region onto a second extruder only takes effect with **support turned off**. The painted multi-material path emits no support, so a support-enabled slice deliberately stays on the single-material path (where painted support keeps working as before).
+- On a machine with two or more extruders, a support *blocker* paint and an *Extruder 2* paint are the same mark and cannot be told apart.
+
+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.
 
 ## Multithreaded slicing (automatic)