three-slicer 0.1.6 → 0.2.0

package/types/settings.d.ts

@@ -1,6 +1,7 @@
 // three-slicer/settings
 import type { SlicerSettings, SettingKey, Point } from './settings-keys.d.ts'
-export type { SlicerSettings, SettingKey, Point }
+import type { PrinterEntry } from './data/printers.json.d.ts'
+export type { SlicerSettings, SettingKey, Point, PrinterEntry }
 
 /** The config-schema default value (undefined for unknown keys) */
 export function schemaDefault(key: string): unknown
@@ -18,6 +19,27 @@ export function settingScalar(settings: SlicerSettings | null | undefined, key:
  */
 export function deriveKernelParams(settings: SlicerSettings | null | undefined, opts?: { plate?: number }): Record<string, unknown>
 
+/** Which slicing technology the settings map's printer profile declares. Defaults to FFF. */
+export function printerTechnology(settings: SlicerSettings | null | undefined): 'FFF' | 'SLA'
+
+/**
+ * Settings map -> SLA (resin) slice params for the pure-JS contour slicer + the display geometry the SL1 raster
+ * export needs. Separate from deriveKernelParams — that one feeds the WASM kernel and its key set is pinned.
+ */
+export function deriveSlaParams(settings: SlicerSettings | null | undefined): {
+  layer_height: number
+  initial_layer_height: number
+  exposure_time: number
+  initial_exposure_time: number
+  faded_layers: number
+  display_width: number
+  display_height: number
+  display_pixels_x: number
+  display_pixels_y: number
+  supports_enable: boolean
+  pad_enable: boolean
+}
+
 /**
  * A 3mf project's raw `Metadata/project_settings.config` -> a settings map this API accepts.
  * Upstream writes every option as a string ("0"/"1" for a bool, "0.2" for a float, one entry per extruder for a
@@ -37,6 +59,99 @@ export function normalizeProjectSettings(raw: Record<string, unknown> | null | u
  */
 export function serializeProjectSettings(settings: SlicerSettings | null | undefined): Record<string, string | string[]>
 
+// ---- Preset files -----------------------------------------------------------
+// The `.json` OrcaSlicer's "Config files" dialog imports and its "Export preset" writes. One file, one preset,
+// one type. The value encoding is the same all-strings shape `project_settings.config` uses — same writer
+// upstream (ConfigBase::save_to_json) — so these reuse the coercion above rather than repeating it.
+
+/** Upstream's own `type` field: machine = printer, process = print settings, filament = material. */
+export type PresetType = 'machine' | 'process' | 'filament'
+
+/** The option keys that belong in a preset of this type, from upstream's `Preset::printer_options()` and friends. */
+export function presetOptionKeys(type: PresetType): string[]
+
+export interface WritePresetOptions {
+  /** Defaults to `'machine'`. */
+  type?: PresetType
+  /** Goes in the file's `name` field, and is what an importer shows. Defaults to `'Custom'`. */
+  name?: string
+  /**
+   * `true` (the default) writes every option of that type, filling unset ones from the config-schema default, so
+   * the file stands on its own. `false` writes only what the settings map holds — a diff-shaped file, readable
+   * only next to whatever it was derived from.
+   */
+  complete?: boolean
+  version?: string
+}
+
+/**
+ * A settings map -> the object a preset `.json` holds. Written **without `inherits`**: upstream saves a derived
+ * preset as the diff against its parent, which only means something beside the vendor database it came from.
+ */
+export function writePresetFile(settings: SlicerSettings | null | undefined, options?: WritePresetOptions): Record<string, unknown>
+
+/** The same, already stringified — what an export actually writes to disk. */
+export function presetFileText(settings: SlicerSettings | null | undefined, options?: WritePresetOptions): string
+
+export interface ReadPresetResult {
+  /** The parent's values with the file's own on top, since the file is the diff. */
+  settings: SlicerSettings
+  type: PresetType
+  name: string
+  /** The parent named by the file, or `null`. */
+  inherits: string | null
+  /**
+   * Set to the parent's name when it was named but could not be resolved. The file's own values are still
+   * applied — a vendor preset without its parent still carries most of itself, and the caller decides whether
+   * that is good enough. Watch for it: the Bambu X1C machine file never states its own bed, so read alone it
+   * yields a printer with no `printable_area` at all.
+   */
+  missingParent: string | null
+  applied: number
+  skipped: string[]
+}
+
+/**
+ * A parsed preset `.json` -> a settings map. Pass `resolveParent` to follow `inherits`; `printerSettings` covers
+ * the machine case for the keys this package carries.
+ */
+export function readPresetFile(raw: Record<string, unknown> | null | undefined,
+  options?: { resolveParent?: (name: string, type: PresetType) => SlicerSettings | null }): ReadPresetResult
+
+// ---- Printer profiles -------------------------------------------------------
+// printers.json is column-oriented; these hide that layout so no consumer decodes it by hand.
+
+/**
+ * Every option key a printer profile can set. Delete these from the settings map before applying a different
+ * printer — a profile only carries the keys it sets, so without the clear the previous machine's values survive.
+ */
+export const printerKeys: string[]
+
+/** Vendor -> profile name -> entry, straight from the data. For building a picker. */
+export const printersByVendor: Record<string, Record<string, PrinterEntry>>
+
+/** Vendor -> slicing technology. Absent means FFF; only the resin vendor bundles are marked. */
+export const printerTechByVendor: Record<string, 'SLA' | 'FFF'>
+
+/** The resin material catalog (SLA vendor bundles, inherits flattened). `layerHeight` is the preset's
+ *  compatibility condition reduced to a number. */
+export const resinCatalog: Array<{
+  name: string; bundle: string; type: string; vendor: string; colour: string
+  exposure_time?: number; initial_exposure_time?: number; initial_layer_height?: number; layerHeight?: number
+}>
+
+/** The settings a resin material applies (exposure family + the remembered pick). `null` when unknown. */
+export function resinSettingsFor(name: string): SlicerSettings | null
+
+/** The settings a printer profile applies, ready to merge. `null` when the name is unknown. */
+export function printerSettings(profileName: string): SlicerSettings | null
+
+/** The vendor's recommended process preset for that printer, or `''` when the profile names none. */
+export function printerDefaultPreset(profileName: string): string
+
+/** The schema keys the kernel's machine limits are read from — for UI that shows which ones are in play. */
+export const machineLimitKeys: string[]
+
 // ---- Lazily loaded presets --------------------------------------------------
 // Both facades hide the column layout of the artifact they wrap; the promise is created once and reused.
 

package/types/sla.d.ts

@@ -0,0 +1,167 @@
+import type { SlicerSettings } from './settings-keys.d.ts'
+
+export type SlaSupportStrategy = 'default' | 'branching' | 'organic'
+export type SlaCapability = 'defaultSupport' | 'branchingSupport' | 'organicSupport' | 'manualSupportPoints' | 'modifierVolumes' | 'pad' | 'correction' | 'hollowing' | 'drainHoles'
+export type SlaCapabilityStatus = 'wasm-required' | 'unsupported' | 'single-object-contours-only'
+export type SlaMatrix4 = readonly [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]
+
+export interface SlaSupportPoint {
+  readonly type: 'manual' | 'automatic' | 'island' | 'slope'
+  readonly position: readonly [number, number, number]
+  readonly radius?: number
+  readonly elevation?: number
+  readonly permanent?: boolean
+  readonly manual?: boolean
+}
+
+export interface SlaDrainHole {
+  readonly position: readonly [number, number, number]
+  readonly normal: readonly [number, number, number]
+  readonly radius: number
+  readonly height: number
+}
+
+export interface SlaModifierVolume {
+  readonly id: string
+  readonly kind: 'blocker' | 'enforcer'
+  readonly stl: ArrayBuffer | Uint8Array
+  readonly transform?: SlaMatrix4
+  readonly settings?: SlicerSettings
+}
+
+export interface SlaObjectInstance {
+  readonly id: string
+  readonly transform?: SlaMatrix4
+  readonly settings?: SlicerSettings
+}
+
+export interface SlaObject {
+  readonly id: string
+  readonly stl: ArrayBuffer | Uint8Array
+  readonly transform?: SlaMatrix4
+  readonly settings?: SlicerSettings
+  readonly instances?: readonly SlaObjectInstance[]
+  readonly supportPoints?: readonly SlaSupportPoint[]
+  readonly modifierVolumes?: readonly SlaModifierVolume[]
+  readonly drainHoles?: readonly SlaDrainHole[]
+}
+
+export interface SupportConfig {
+  readonly enabled?: boolean
+  readonly strategy?: SlaSupportStrategy
+  readonly enforcersOnly?: boolean
+  readonly headFrontDiameter?: number
+  readonly headPenetration?: number
+  readonly headWidth?: number
+  readonly pillarDiameter?: number
+  readonly smallPillarDiameterPercent?: number
+  readonly maxBridgesOnPillar?: number
+  readonly maxWeightOnModel?: number
+  readonly pillarConnectionMode?: 'zigzag' | 'cross' | 'dynamic'
+  readonly buildplateOnly?: boolean
+  readonly pillarWideningFactor?: number
+  readonly baseDiameter?: number
+  readonly baseHeight?: number
+  readonly baseSafetyDistance?: number
+  readonly criticalAngle?: number
+  readonly maxBridgeLength?: number
+  readonly maxPillarLinkDistance?: number
+  readonly objectElevation?: number
+  readonly branchingsupport_head_front_diameter?: number
+  readonly branchingsupport_head_penetration?: number
+  readonly branchingsupport_head_width?: number
+  readonly branchingsupport_pillar_diameter?: number
+  readonly branchingsupport_small_pillar_diameter_percent?: number
+  readonly branchingsupport_max_bridges_on_pillar?: number
+  readonly branchingsupport_max_weight_on_model?: number
+  readonly branchingsupport_pillar_connection_mode?: 'zigzag' | 'cross' | 'dynamic'
+  readonly branchingsupport_buildplate_only?: boolean
+  readonly branchingsupport_pillar_widening_factor?: number
+  readonly branchingsupport_base_diameter?: number
+  readonly branchingsupport_base_height?: number
+  readonly branchingsupport_base_safety_distance?: number
+  readonly branchingsupport_critical_angle?: number
+  readonly branchingsupport_max_bridge_length?: number
+  readonly branchingsupport_max_pillar_link_distance?: number
+  readonly branchingsupport_object_elevation?: number
+}
+
+export interface PadConfig {
+  readonly enabled?: boolean
+  readonly wallThickness?: number
+  readonly wallHeight?: number
+  readonly brimSize?: number
+  readonly maxMergeDistance?: number
+  readonly wallSlope?: number
+  readonly aroundObject?: boolean
+  readonly aroundObjectEverywhere?: boolean
+  readonly objectGap?: number
+  readonly objectConnectorStride?: number
+  readonly objectConnectorWidth?: number
+  readonly objectConnectorPenetration?: number
+}
+
+export interface SlaCorrectionConfig {
+  readonly relative?: readonly [number, number]
+  readonly relativeX?: number
+  readonly relativeY?: number
+  readonly relativeZ?: number
+  readonly absolute?: number
+  readonly elephantFootMinWidth?: number
+  readonly zCorrectionLayers?: number
+  readonly closingRadius?: number
+}
+
+export interface SlaDisplayConfig {
+  readonly width?: number
+  readonly height?: number
+  readonly pixelsX?: number
+  readonly pixelsY?: number
+  readonly mirrorX?: boolean
+  readonly mirrorY?: boolean
+  readonly orientation?: 'landscape' | 'portrait'
+  readonly gamma?: number
+  readonly archiveFormat?: 'SL1'
+}
+
+export interface SlaHollowingConfig {
+  readonly enabled?: boolean
+  readonly minThickness?: number
+  readonly quality?: number
+  readonly closingDistance?: number
+}
+
+export interface SlaJob {
+  readonly version?: 1
+  readonly objects: readonly SlaObject[]
+  readonly settings?: SlicerSettings
+  readonly support?: SupportConfig
+  readonly pad?: PadConfig
+  readonly correction?: SlaCorrectionConfig
+  readonly display?: SlaDisplayConfig
+  readonly hollowing?: SlaHollowingConfig
+  readonly drainHoles?: readonly unknown[]
+  readonly requiredCapabilities?: readonly SlaCapability[]
+}
+
+export interface SlaCapabilities {
+  readonly defaultSupport: SlaCapabilityStatus
+  readonly branchingSupport: SlaCapabilityStatus
+  readonly organicSupport: SlaCapabilityStatus
+  readonly manualSupportPoints: SlaCapabilityStatus
+  readonly modifierVolumes: SlaCapabilityStatus
+  readonly pad: SlaCapabilityStatus
+  readonly correction: SlaCapabilityStatus
+  readonly hollowing: SlaCapabilityStatus
+  readonly drainHoles: SlaCapabilityStatus
+  readonly jsFallback: SlaCapabilityStatus
+}
+
+export type SlaErrorCode = 'SLA_INVALID_REQUEST' | 'SLA_UNSUPPORTED_ORGANIC' | 'SLA_UNSUPPORTED_HOLLOWING' | 'SLA_FALLBACK_MULTI_OBJECT' | 'SLA_FALLBACK_SUPPORTS' | 'SLA_FALLBACK_PAD' | 'SLA_FALLBACK_OBJECT_CONTEXT'
+
+export class SlaRequestError extends Error {
+  readonly code: SlaErrorCode
+}
+
+export const SLA_JOB_VERSION: 1
+export const SLA_CAPABILITIES: SlaCapabilities

package/types/viewer.d.ts

@@ -21,8 +21,32 @@ export interface ViewportProps {
   /**
    * 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.
+   *
+   * A {@link LockablePanel} also accepts `'readonly'`: the panel is drawn but nothing inside it can be clicked,
+   * typed into or tabbed to — including any node the host passed into it. That is the shape a host wants when it
+   * presets the printer, process and filament itself and does not want the user changing them.
+   *
+   * Note what it locks: the UI path, not the value. `settings` is still the host's own prop, and other paths
+   * inside the viewer still write it — importing a 3mf project applies that project's settings either way.
    */
-  panels?: Partial<Record<ViewportPanel, boolean>>
+  panels?: Partial<Record<ViewportPanel, boolean>> & Partial<Record<LockablePanel, boolean | 'readonly'>>
+  /**
+   * Behaviour switches, following the same opt-out rule as {@link ViewportProps.panels}: everything is on unless
+   * its key is explicitly `false`. These are the things the component does *outside* its own box — take the page's
+   * keyboard, load the WASM kernel, write to the console — which a host embedding it in a larger app may already
+   * be doing itself. See {@link ViewportFeature}.
+   */
+  features?: Partial<Record<ViewportFeature, boolean>>
+  /**
+   * Intercepts every file the viewer would otherwise hand to the browser as a download — the 3mf project, the STL,
+   * and each plate's G-code. Return anything truthy to say it is handled and suppress the download; return nothing
+   * to let it proceed as well. This is the only way in: the save buttons live inside the component.
+   *
+   * ```jsx
+   * <Viewport onExport={(blob, filename) => { upload(blob, filename); return true }} />
+   * ```
+   */
+  onExport?: (file: Blob, filename: string) => boolean | void
   /**
    * 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.
@@ -41,10 +65,44 @@ export interface ViewportProps {
   onSliced?: (result: { plate: number; stats: Record<string, unknown>; gcode: string }) => void
 }
 
+/**
+ * Behaviour keys accepted by {@link ViewportProps.features}. All default to enabled.
+ *
+ * - `shortcuts` — the keyboard bindings. They are installed on `window`, so while the viewer is mounted they fire
+ *   wherever focus is (except inside inputs) and `Ctrl+C` in particular preventDefaults. Turn them off when the
+ *   host page has its own.
+ * - `warmup` — loading the WASM kernel on mount, ahead of the first slice. Off, nothing is downloaded or compiled
+ *   until something actually slices — which for a `gcode`-only viewer is never.
+ * - `drop` — drag and drop onto the canvas.
+ * - `filePicker` — the file dialog, from every button that opens it.
+ * - `contextMenu` — the right-click menu. Note that the browser's own menu stays suppressed over the canvas either
+ *   way: OrbitControls preventDefaults `contextmenu` itself.
+ * - `logs` — console diagnostics, from the component and from the slice worker.
+ */
+export type ViewportFeature = 'shortcuts' | 'warmup' | 'drop' | 'filePicker' | 'contextMenu' | 'logs'
+
+/**
+ * The panels that accept `'readonly'` as well as `true`/`false` — the right column and the cards in it. Everything
+ * else takes a boolean only: locking the gizmo rail or the plate tabs is what `features` and `panels: false` are
+ * for, and pretending otherwise would mean a `'readonly'` that silently does nothing on half the keys.
+ *
+ * `sidebar: 'readonly'` locks the whole column in one go, so the per-card keys are for mixing — a locked printer
+ * card above a live object list, say.
+ */
+export type LockablePanel =
+  | 'sidebar' | 'printerCard' | 'filamentCard' | 'objectList' | 'towerCard'
+  | 'previewControls' | 'processCard' | 'sliceBar'
+
 /** 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'
+  /** 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. */
+  | 'towerCard'
+  /** The resin (SLA) card. Takes the filament card's place when the printer profile declares SLA. */
+  | 'resinCard'
 
 /** Value changes reported through {@link ViewportProps.onEvent}. Not fired for the initial values. */
 export type ViewportEvent =

package/types/worker.d.ts

@@ -1,3 +1,98 @@
 // 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'
+import type { SlaErrorCode, SlaJob } from './sla.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[] }
+  /**
+   * 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`.
+   */
+  | { cmd: 'sla'; stl: ArrayBuffer; params: string | object }
+  /** Object-aware SLA protocol. The worker preserves the ordered objects; it never merges them for a fallback. */
+  | { 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.)
+   * 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; code?: SlaErrorCode }
+
 export {}