@weasel-js/labkit 1.1.0 → 1.3.0-pre.0

package/README.md

@@ -59,6 +59,33 @@ import { ThemeProvider } from '@weasel-js/theme/react';
 `"light"` or `"dark"`. Only `styles.css` needs importing — the token values
 arrive through the provider.
 
+## Driving your own renderer
+
+`CanvasStack` is 2D. For three.js or raw WebGL, take rects and dirtiness from
+labkit and keep the GL yourself:
+
+```tsx
+import { toDeviceRect, useSurfaceTile, useTiledSurface } from '@weasel-js/labkit/surface';
+```
+
+A trial's `view` is opaque to labkit — it is persisted, restored on Reset and
+handed to the instrument without being read into — so a 3D lab stores an orbit
+there and gets all three. `useOrbit` is the 3D peer of `usePanZoom`.
+
+See `src/surface/AGENTS.md` for the contract and the traps.
+
+## Long-running work
+
+An instrument with work too slow for a render declares a `job`. labkit starts it,
+aborts it on unmount and on a key change, discards results from a superseded run,
+and renders progress and a cancel control into the trial chrome. Per-item failure
+is an event rather than a thrown error, so a run with two failed items is a
+partial success.
+
+```tsx
+import type { JobCapability } from '@weasel-js/labkit/job';
+```
+
 ## Development
 
 ```bash

package/dist/_dts/{DrawCommand-BkZztJsW.d.ts → DrawCommand-DBB45NfN.d.ts}

@@ -88,6 +88,8 @@ interface SerializedHistoryEntry {
     label: string;
     forwardOps: SerializedOp[];
     baseOps: SerializedOp[];
+    selectionBefore?: readonly string[];
+    selectionAfter?: readonly string[];
 }
 /** Snapshot of an entire `History` instance. Designed to live alongside the
  *  scene snapshot in IDB so a reload restores the undo / redo stacks to
@@ -119,6 +121,10 @@ interface HistoryEntry {
      *  contribute nothing. May be `undefined` for deserialized entries
      *  restored from an older snapshot that predates this field. */
     touchedIds?: ReadonlySet<string>;
+    /** Selection restored when this entry is undone. */
+    selectionBefore?: readonly string[];
+    /** Selection restored when this entry is redone. */
+    selectionAfter?: readonly string[];
 }
 /** Op-batched undo/redo controller returned by `createHistory`. */
 interface History {
@@ -170,7 +176,7 @@ interface History {
      *  Unlike `applyOps`, does NOT call `op.apply()`. Used by Journal.commit
      *  to flush a session's net forward ops to the parent as one entry without
      *  re-mutating the scene. */
-    recordEntry(ops: Op[], label: string): void;
+    recordEntry(ops: Op[], label: string, options?: RecordEntryOptions): void;
     /** Concatenated forwardOps of every undo-stack entry, in order. Snapshot
      *  of "what changes are currently applied via this history" — useful for
      *  Journal.commit to flush to a parent, and for any caller that wants to
@@ -193,6 +199,32 @@ interface History {
      *  to resume or discard before calling this. */
     resumeJournal(journal: Journal): void;
 }
+/** Options for `recordEntry`. */
+interface RecordEntryOptions {
+    /** Selection as of before the already-applied ops ran. `recordEntry` is
+     *  called after the fact, so the live selection has moved on by then and
+     *  the engine cannot sample it — a caller that wants undo to restore the
+     *  selection captures it when the batch opens and passes it here. */
+    selectionBefore?: readonly string[];
+}
+
+/**
+ * Path data model. Vector-graphics primitive used kit-wide as the canonical
+ * shape (replacing per-shape ad-hoc poses). SVG-style command stream so we
+ * cover lines, polygons, beziers, and multi-contour shapes (think the inner
+ * hole of an "O") under one type.
+ *
+ * Storage: command codes in a `Uint8Array`, parameters in a `Float32Array`.
+ * Each command consumes a fixed number of float coords from the parameter
+ * array; the parser walks both arrays in lockstep. This keeps interaction
+ * hot loops monomorphic and keeps GC pressure low under heavy edits.
+ *
+ * Two path subtypes are distinguished at the type level so common-case
+ * machinery (selection AABBs, area-select intersection, hit-testing rect
+ * silhouettes) can short-circuit on `RectPath` without paying the polygon
+ * kernel cost. Polymorphic kernels accept either via the `Path` union and
+ * dispatch on `kind`.
+ */
 
 /** Fill rule used by polygon path hit-testing and `ctx.fill()`. */
 type PathFillRule = 'nonzero' | 'evenodd';
@@ -298,6 +330,20 @@ interface NodeBase<TData, TLayer extends string, TPose> {
     pose: TPose;
     data: TData;
     parent: NodeId | null;
+    /** Nodes whose poses this node's geometry is computed from. Fixed at add
+     *  time. Absent or empty means the node's geometry is authored, which is the
+     *  normal case. */
+    dependsOn?: readonly NodeId[];
+    /** Computes this node's path from its dependencies' poses, in `dependsOn`
+     *  order. A dependency that has been removed arrives as `undefined`.
+     *  Returning `null` means "nothing to draw right now". Re-evaluated when a
+     *  dependency's world pose changes, never authored. Absolute-pose `Scene`
+     *  makes that the dependency's own pose, and an ancestor's move reaches it as
+     *  a `setPose` of its own from the container cascade.
+     *  `node` is deliberately widened: naming `TData`/`TLayer` here puts them in
+     *  a contravariant position, making `Scene` invariant in both and breaking
+     *  assignment kit-wide. The cost is that a `derivePath` casts to read `node.data`. */
+    derivePath?: (node: Node<unknown, string, TPose>, deps: readonly (TPose | undefined)[]) => Path | null;
 }
 /** A node with no children — a shape, a label, an image. */
 interface LeafNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
@@ -352,6 +398,11 @@ interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
     /** Only meaningful when `kind === 'container'`. Attach a clip-path function
      *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */
     clipFromPose?: (pose: TPose) => Path | null;
+    /** Mirrors `SceneNode.dependsOn`. */
+    dependsOn?: readonly NodeId[];
+    /** Mirrors `SceneNode.derivePath`. Taken as a live function; its registry key is
+     *  looked up from it, never passed in. */
+    derivePath?: (node: Node<unknown, string, TPose>, deps: readonly (TPose | undefined)[]) => Path | null;
 }
 /** A custom scene mutation registered with `Scene.registerOp`: how to apply
  *  it and how to undo it. The pair is what makes it participate in history. */
@@ -399,6 +450,57 @@ interface SerializedNode<TData, TLayer extends string, TPose> {
     /** Registry key for the container's clip-path factory.
      *  Containers only; omitted when the container has no clip. */
     clipFromPoseKey?: string;
+    /** Ids this node's geometry derives from. Omitted when it derives from nothing. */
+    dependsOn?: readonly string[];
+    /** Registry key for the node's `derivePath` function. Omitted when it has none. */
+    derivePathKey?: string;
+}
+/**
+ * One node's ephemeral presentation override — what a frame loop wants to say
+ * about a node without saying it about the document.
+ *
+ * Not document content: never recorded in history, never in `toJSON`, and
+ * writing one does not bump `Scene.getVersion()`. Hoist one entry per node and
+ * mutate it in place on a frame loop; `PoseOverrides.commit()` is what makes a
+ * mutation visible.
+ */
+interface PoseOverride<TPose> {
+    /** Replaces the node's document pose everywhere the render and hit-test
+     *  paths read one, including the clip a container derives from its pose.
+     *  Resolved by `effectivePose` — reading `node.pose` directly is how those
+     *  paths came to disagree about where a node is. */
+    pose?: TPose;
+    /** Multiplied into the node's painted alpha, on top of any `alphaFor`. */
+    alpha?: number;
+}
+/**
+ * The scene's ephemeral per-node overrides — see {@link PoseOverride}.
+ *
+ * The intended shape of a frame is: `set` each node once, mutate the entries
+ * in place per frame, `commit()` once. `commit` is not optional bookkeeping —
+ * the painter memo keys on pose *reference*, so a mutation without a commit
+ * paints the previous frame with no error.
+ *
+ * To promote a frame to document state (dropping a drag, baking an animation),
+ * write it once through `Scene.setPose` and `clear` the override.
+ */
+interface PoseOverrides<TPose> {
+    /** Store `entry` for `id` **by reference**; the caller keeps mutating it. */
+    set(id: NodeId, entry: PoseOverride<TPose>): void;
+    get(id: NodeId): PoseOverride<TPose> | undefined;
+    has(id: NodeId): boolean;
+    /** The overridden ids, as a snapshot array. */
+    ids(): readonly NodeId[];
+    clear(id: NodeId): void;
+    clearAll(): void;
+    /** Publish this frame's in-place mutations: invalidate the painter memo for
+     *  every overridden node, then notify subscribers. */
+    commit(): void;
+    /** Notified after every write. The canvas uses this to repaint without a
+     *  scene version bump. */
+    subscribe(fn: () => void): () => void;
+    /** Monotonic write counter. A snapshot for observers that poll. */
+    getGeneration(): number;
 }
 /**
  * The kit-owned scene tree: nodes, layers, and the undo history over both.
@@ -428,10 +530,19 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> {
      *  not a live view, and not yours to mutate. */
     renderOrderNodes(): readonly Node<TData, TLayer, TPose>[];
     add(spec: AddNodeSpec<TData, TLayer, TPose>): NodeId;
-    /** Delete `id` **and its entire subtree** — every descendant is removed in
-     *  the same operation. Recorded as one undoable step; `undo()` restores the
-     *  whole subtree (root + descendants, child order intact). */
+    /** Delete `id`, its **entire subtree**, and **everything that derives from**
+     *  any of those nodes — a node listing one of them in `dependsOn` goes too,
+     *  along with its own subtree, transitively. A dependent can live anywhere in
+     *  the tree, so this deletes nodes the caller never named and may unlink
+     *  several disjoint subtrees at once. Recorded as one undoable step; `undo()`
+     *  restores every one of them where it was, child order intact. */
     remove(id: NodeId): void;
+    /** {@link remove} over several roots at once, as a **single** undoable step.
+     *  Ids resolve against the tree as it stands at the call, so an id that
+     *  another one would cascade away is absorbed rather than removed twice —
+     *  which is what makes it safe to pass a whole selection. Throws if any id is
+     *  not in the scene; an empty list does nothing and records no step. */
+    removeMany(ids: readonly NodeId[]): void;
     update(id: NodeId, patch: {
         data: TData;
     }): void;
@@ -467,6 +578,9 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> {
     setLayerVisible(layer: TLayer, visible: boolean): void;
     setLayerLocked(layer: TLayer, locked: boolean): void;
     addLayer(spec: AddLayerSpec<TLayer>): void;
+    /** Drop a user layer and every node tagged to it, as one undoable step.
+     *  Removal cascades, so this also deletes nodes **on other layers** that
+     *  derive from a node on this one. */
     removeLayer(layer: TLayer): void;
     renameLayer(layer: TLayer, name: string): void;
     moveLayer(layer: TLayer, index: number): void;
@@ -500,6 +614,19 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> {
      *  `SceneCanvasAdapter`). Pass `this` from `sceneToAdapter` or a compatible
      *  adapter. */
     applyBatch(ops: Op[], label: string, adapter: unknown): void;
+    /** The transient set of active ids — "operate on these N as a unit".
+     *  Shared by every view over this scene unless a view supplies its own
+     *  (see `CanvasView.selection`). Not document content: it never appears
+     *  in `toJSON`. It does ride on history entries, so undo and redo put
+     *  back the selection an edit was made under; changing it is never an
+     *  undo step of its own. */
+    getSelection(): readonly NodeId[];
+    setSelection(ids: readonly NodeId[]): void;
+    /** Per-node pose / alpha overrides the render and hit-test paths read
+     *  through. Like {@link Scene.getSelection} this is not document content:
+     *  writes are never recorded, never serialized, and do not bump
+     *  {@link Scene.getVersion}. See {@link PoseOverrides}. */
+    readonly overrides: PoseOverrides<TPose>;
     undo(): boolean;
     redo(): boolean;
     canUndo(): boolean;
@@ -609,29 +736,11 @@ interface ViewportDims {
 }
 
 /**
- * 2D affine matrix utilities. Column-major 9-element Float32Array, matching
- * `WebGL2RenderingContext.uniformMatrix3fv` byte order so we can pass the
- * array directly without a transpose flag.
+ * A registered texture, named by the registry that holds it.
  *
- * Layout (column-major):
- *   [m00, m10, 0,
- *    m01, m11, 0,
- *    tx,  ty,  1]
- *
- * `apply(m, x, y)` returns `[m * (x, y, 1)] = [m00*x + m01*y + tx,
- *                                              m10*x + m11*y + ty]`.
- */
-type Mat3 = Float32Array;
-
-/**
- * registerTexture — accepts an image source, assigns an opaque id, stores in
- * a module-level registry. Actual GL upload happens lazily at draw time in
- * drawShader() via GLTextureCache.upload (which is idempotent).
- *
- * Lifecycle: textures live for the renderer's lifetime. No unregister in v1.
- *
- * Convention §9: this registry stores image data only — no per-renderer state.
- * Each WeaselRenderer's GLTextureCache does its own dedup via has(id).
+ * The handle is here rather than beside the registry because `FillStyle`'s
+ * pattern variant names it, and paint is a leaf: the registry lives in the
+ * renderer and imports this back.
  */
 interface TextureHandle {
     readonly id: string;
@@ -789,20 +898,53 @@ interface GradStop {
  * typically use a stencil mask of the stroked path against the geometry.
  */
 type StrokeAlign = 'center' | 'inner' | 'outer';
+/**
+ * The kit's built-in marker vocabulary, open on the string the way
+ * `PaintKind` is so a consumer's registered key typechecks.
+ */
+type KitMarkerKey = 'arrow' | 'arrow-open' | 'arrow-concave' | 'diamond' | 'diamond-hollow' | 'circle' | 'square' | 'bar';
+type MarkerKey = KitMarkerKey | (string & {});
+/**
+ * A marker on one end (or every interior vertex) of a stroke.
+ *
+ * `size` reuses `Stroke.width`'s unit system: a bare number scales with the
+ * resolved stroke width, `{ px }` pins screen pixels. That is SVG's
+ * `markerUnits` in the idiom this codebase already resolves at draw time.
+ * Omitted, the marker is one stroke width per unit.
+ */
+type MarkerRef = MarkerKey | {
+    key: MarkerKey;
+    size?: number | {
+        px: number;
+    };
+};
 /** Stroke style: a FillStyle plus structural line parameters. */
 interface Stroke {
     paint: FillStyle;
-    width?: number;
+    /** World units, or `{ px }` for screen pixels — resolved against the
+     *  accumulated transform scale at draw time, so it holds its on-screen
+     *  thickness as the view zooms. */
+    width?: number | {
+        px: number;
+    };
     /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */
     dash?: number[];
+    /** Marker at the first vertex of each open subpath, rotated to point back
+     *  along the line (SVG's `auto-start-reverse`, as the only behavior). */
+    markerStart?: MarkerRef;
+    /** Marker at every interior authored vertex, on the bisector of the
+     *  incoming and outgoing directions. Never insets the stroke. */
+    markerMid?: MarkerRef;
+    /** Marker at the last vertex of each open subpath. */
+    markerEnd?: MarkerRef;
     cap?: 'butt' | 'round' | 'square';
     join?: 'miter' | 'round' | 'bevel';
     /**
      * Miter join fallback threshold. When the miter length exceeds
-     * `miterLimit * width / 2`, the join falls back to a bevel. Default 10
-     * (matching Canvas2D). SVG's default is 4; consumers that want SVG
-     * fidelity should set this explicitly when constructing strokes from
-     * SVG sources where the attribute was omitted.
+     * `miterLimit * width / 2`, the join falls back to a bevel. Default 4,
+     * matching SVG — which is also what the kit's own serializer implies when
+     * it omits the attribute for an unset field. Canvas2D's 10 lets an acute
+     * corner throw a spike four times the half-width.
      */
     miterLimit?: number;
     /** Where the stroke sits relative to the geometric edge. Default `'center'`. */
@@ -837,17 +979,41 @@ interface Stroke {
     varyingWidthJoinThreshold?: number;
 }
 
+/**
+ * 2D affine matrix utilities. Column-major 9-element Float32Array, matching
+ * `WebGL2RenderingContext.uniformMatrix3fv` byte order so we can pass the
+ * array directly without a transpose flag.
+ *
+ * Layout (column-major):
+ *   [m00, m10, 0,
+ *    m01, m11, 0,
+ *    tx,  ty,  1]
+ *
+ * `apply(m, x, y)` returns `[m * (x, y, 1)] = [m00*x + m01*y + tx,
+ *                                              m10*x + m11*y + ty]`.
+ */
+type Mat3 = Float32Array;
+
 /**
  * Typography for `TextPose` and friends. Every field is optional; consumers
  * pass `{}` or override the few they care about. Defaults live in
  * `DEFAULT_TEXT_STYLE` and are applied at render/measure time, never written
  * back to the pose.
  *
- * `fill` follows the kit-wide `FillStyle` model — solid color or pattern. The
- * contenteditable edit overlay flattens non-solid fills to `'#000'` for CSS
- * since the browser can't paint with a texture handle.
+ * Paint is not typography and does not live here. A text node carries its
+ * fill and stroke in `data.fill` / `data.stroke`, the slots every other node
+ * kind uses; `resolveTextStyle` takes them as its second argument and
+ * `StyledRun.fill` / `.stroke` override them per range.
  */
 
+/**
+ * Horizontal alignment. `start` / `end` resolve against the reading direction;
+ * `left` / `right` are absolute. Same five values as CSS `text-align`, with
+ * the same split between the relative pair and the absolute pair.
+ */
+type TextAlign = 'left' | 'center' | 'right' | 'start' | 'end';
+/** Reading direction, which is what gives `start` / `end` their meaning. */
+type TextDirection = 'ltr' | 'rtl';
 /** User-facing text style. All fields optional; defaults applied at render time via `resolveTextStyle`. */
 interface TextStyle {
     /** Font size in world units. Default 16. */
@@ -858,15 +1024,15 @@ interface TextStyle {
     fontWeight?: number | string;
     /** Default `'normal'`. */
     fontStyle?: 'normal' | 'italic';
-    /** Default `'left'`. */
-    align?: 'left' | 'center' | 'right';
+    /** Default `'left'`. Pass `'start'` to align by reading order instead. */
+    align?: TextAlign;
+    /** Reading direction, resolving `align: 'start' | 'end'`. Default `'ltr'`. */
+    direction?: TextDirection;
     /** Multiplier applied to `fontSize`. Default 1.2. */
     lineHeight?: number;
-    /** Default `{ fill: 'solid', color: '#000' }`. */
-    fill?: FillStyle;
     /**
-     * Caret color used by the edit overlay. Defaults to the text color when
-     * `fill` is solid; falls back to `#000` for non-solid paints.
+     * Caret color used by the edit overlay. Defaults to the node's fill when
+     * that fill is solid; falls back to `#000` for non-solid paints.
      */
     caretColor?: string;
     /**
@@ -883,19 +1049,8 @@ interface TextStyle {
     underline?: boolean;
     /** Default `false`. */
     strikethrough?: boolean;
-    /**
-     * Outline painted over the glyph fill. Omitted (the default) means no
-     * outline — there is no such thing as a default text stroke.
-     *
-     * Only glyphs on the outline tier are stroked: above
-     * `textOutlineMinScreenSize` a glyph is a real `PolygonPath`, so it gets
-     * the ordinary tessellated ribbon with real joins, caps and miters, in any
-     * paint. Below it a glyph is a sampled distance field with no geometry to
-     * stroke, and it renders unstroked rather than approximated. `width` is in
-     * world units, like every other stroke in the kit — it does not scale with
-     * `fontSize`.
-     */
-    stroke?: Stroke;
+    /** Default `false`. */
+    overline?: boolean;
 }
 
 /**
@@ -910,10 +1065,15 @@ interface TextStyle {
  * override the node-level value (`letterSpacing: 0` on a run is an override,
  * not an absence — it zeroes inherited tracking).
  *
- * `underline` / `strikethrough` are *additive*, like `bold`/`italic`: a run
- * can turn a decoration on but never off, so they resolve as
- * `run.x || style.x` and not `run.x ?? style.x`. See the header of
+ * `underline` / `strikethrough` / `overline` are *additive*, like
+ * `bold`/`italic`: a run can turn a decoration on but never off, so they
+ * resolve as `run.x || style.x` and not `run.x ?? style.x`. See the header of
  * `runs/rangeStyle.ts` for why the model collapses the tri-state.
+ *
+ * `script` is folded the same way the toggles are, into the two primitives it
+ * is a preset over: `baselineShift` and `fontScale`. Both come out as one
+ * world-unit `baselineShift` and a final `fontSize`, so layout never learns
+ * that superscripts exist — it places a run against a baseline and an offset.
  */
 
 /** A run with every style resolved against the node's text style — no
@@ -934,6 +1094,17 @@ interface ResolvedRun {
     underline: boolean;
     /** Draw a rule through this run's x-height. Additive over the node style. */
     strikethrough: boolean;
+    /** Draw a rule above this run's ascent. Additive over the node style. */
+    overline: boolean;
+    /**
+     * How far this run sits off the line's shared baseline, in world units;
+     * positive raises. 0 for ordinary text.
+     *
+     * Already multiplied out against the inherited font size, and already
+     * carrying whatever `script` asked for — layout adds it to a baseline and
+     * asks nothing about where it came from.
+     */
+    baselineShift: number;
 }
 
 /**
@@ -952,7 +1123,7 @@ type TextVerticalAlign = 'top' | 'center' | 'bottom';
  * calls getProgramSource() and compiles the result. This keeps registerProgram
  * GL-context-agnostic — identical pattern to registerFont storing ImageBitmap.
  *
- * Convention §9: module-level state = source strings only; compiled GL
+ * Module-level state = source strings only; compiled GL
  * programs live on each renderer's programRegistry (Map<id, ShaderProgram>).
  *
  * Lifecycle: program sources live for the module lifetime. No unregister in v1.
@@ -1063,6 +1234,21 @@ interface ImageDrawCommand {
      *  device pixels as hard squares — required by anything magnifying a
      *  framebuffer readback, where blur destroys the point of the readback. */
     sampling?: 'linear' | 'nearest';
+    /** Sub-rectangle of `image` to draw, in bitmap pixels from the top-left.
+     *  Omitted draws the whole bitmap. Not range-checked: a rect past the edge
+     *  samples outside [0..1], which CLAMP_TO_EDGE smears. With
+     *  `sampling: 'linear'` the filter reaches half a texel beyond `source`, so
+     *  atlas frames need a gutter (see `SpriteSheet.spacing`) or `'nearest'`. */
+    source?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Mirror the sampled region within the destination rect. The quad does not
+     *  move — a flipped draw covers exactly the pixels an unflipped one does. */
+    flipX?: boolean;
+    flipY?: boolean;
 }
 /**
  * Custom shader draw command. The renderer generates a quad over `bounds`
@@ -1087,4 +1273,4 @@ interface ShaderDrawCommand {
     };
 }
 
-export type { Bounds as B, DrawCommand as D, History as H, Node as N, Op as O, PathDrawCommand as P, Scene as S, View as V, ViewportDims as a, NodeId as b, Path as c };
+export type { Bounds as B, DrawCommand as D, History as H, Node as N, Op as O, Path as P, Scene as S, View as V, ViewportDims as a, PathDrawCommand as b, NodeId as c };