@weasel-js/labkit 0.1.0

package/dist/_dts/fitViewToBounds-rWrBI4a6.d.ts

@@ -0,0 +1,870 @@
+/**
+ * An invertible mutation. Applied via an adapter; produces an inverse op
+ * that, when applied to the same adapter, undoes the original.
+ *
+ * Adapters are intentionally typed loosely here so different op types can
+ * require different adapter capabilities. Each op is responsible for
+ * narrowing the adapter via the methods it calls.
+ *
+ * Lives here rather than in `@weasel-js/core` because an invertible,
+ * replayable mutation is a history concept: this package is what pushes ops
+ * onto a stack, inverts them, coalesces them, and rebuilds them from a
+ * serialized snapshot. Nothing about the shape is core-specific — it names no
+ * scene, node, or pose type. Core re-exports it from `core/ops/types` so its
+ * own call sites read unchanged.
+ */
+interface Op {
+    /** Apply the mutation. Return `false` (or `'noop'`) to signal that
+     *  nothing changed — the history layer then skips pushing an undo
+     *  entry for the batch when *every* op reports no-op. Returning
+     *  `undefined`/`void` means "mutated" (the common case; existing ops
+     *  don't need to change). */
+    apply(adapter: unknown): void | boolean | 'noop';
+    invert(): Op;
+    label?: string;
+    coalesceKey?: string;
+    /** Stable factory name for op-registry lookup. Kit-emitted ops always
+     *  set this; consumer ops without a name can't round-trip through
+     *  `History.serialize()` and are dropped from persisted snapshots. */
+    name?: string;
+    /** Serializable args (JSON / structured-clone-safe) that, paired with
+     *  `name`, reconstruct the op via the registry's `rebuildOp`. */
+    args?: unknown;
+}
+
+interface Journal {
+    readonly targetId: string | undefined;
+    readonly forkedAtEntryId: number;
+    applyBatch(ops: Op[], label: string): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    entries(): {
+        undo: HistoryEntry[];
+        redo: HistoryEntry[];
+    };
+    commit(label: string): void;
+    cancel(): void;
+    suspend(): void;
+    isActive(): boolean;
+}
+
+/** Wire form of a single op inside a serialized history. The pair
+ *  `(name, args)` reconstructs a live `Op` via the op-factory registry. */
+interface SerializedOp {
+    name: string;
+    args: unknown;
+}
+/** Wire form of one history entry. `forwardOps` / `baseOps` mirror the
+ *  in-memory entry's fields (see `Entry` above) but only carry the
+ *  serializable `(name, args)` projection of each op. */
+interface SerializedHistoryEntry {
+    id: number;
+    label: string;
+    forwardOps: SerializedOp[];
+    baseOps: SerializedOp[];
+}
+/** Snapshot of an entire `History` instance. Designed to live alongside the
+ *  scene snapshot in IDB so a reload restores the undo / redo stacks to
+ *  exactly where they were. */
+interface SerializedHistory {
+    version: 1;
+    undoStack: SerializedHistoryEntry[];
+    /** Stored newest-first, mirroring the in-memory stack so a deserialized
+     *  history matches the original's `entries().redo` ordering. */
+    redoStack: SerializedHistoryEntry[];
+    nextEntryId: number;
+    /** Entries dropped because at least one of their ops lacked a `name`
+     *  and therefore couldn't round-trip through the op-factory registry.
+     *  Always present (zero when nothing was dropped) so callers can detect
+     *  loss without parsing the debug log. */
+    droppedEntries: number;
+}
+/** Read-only view of a history entry exposed via `History.entries()`. */
+interface HistoryEntry {
+    /** Stable monotonic id (preserved across coalesce merges). */
+    id: number;
+    /** Human-readable label (the `label` arg passed to `applyOps`). */
+    label: string;
+    /** Push/last-coalesce timestamp (ms). */
+    timestamp: number;
+    /** Set of node ids touched by any op in this entry. Populated from ops
+     *  whose `args` carry an `id` field (transform, setPath, reparent) or a
+     *  `node.id` field (insert, delete). Ops without a recognisable id field
+     *  contribute nothing. May be `undefined` for deserialized entries
+     *  restored from an older snapshot that predates this field. */
+    touchedIds?: ReadonlySet<string>;
+}
+
+/**
+ * Pose composition for hierarchical scene graphs.
+ *
+ * As of the nesting change, `getPose(id)` on adapters returns the
+ * **local** pose — relative to the object's direct parent. Anything in the
+ * kit that needs to draw, hit-test, snap, or otherwise reason about world
+ * coordinates routes through `composeWorldPose`, which walks the parent
+ * chain and folds local poses together via a consumer-supplied `compose`.
+ *
+ * Pose shape is generic, so the compose strategy is too. For the common
+ * `{x, y, width, height}` axis-aligned rect, use `composeRectPose` —
+ * translation only, child dimensions preserved. Custom pose shapes (paths,
+ * matrix transforms) supply their own.
+ *
+ * The inverse — `rebaseLocalPose` — converts a world-space pose into a
+ * local pose under a target parent. Used when reparenting so the visual
+ * world position of a child is preserved across the parent change.
+ */
+/**
+ * Axis-aligned rectangle pose with optional rotation. The canonical pose
+ * shape used by `composeRectPose` and the `unionBounds` helper. Rotation is
+ * in radians, pivoted on the unrotated AABB center; absent === 0. Kit-side
+ * code that consumes rotation already reads `pose.rotation ?? 0`
+ * (`SceneCanvas.defaultDrawOne`, `rotate/handle.ts`, `pathInWorld.ts`), so
+ * the slot exists on every default scene whether or not the consumer
+ * populates it. Defined here in core/transforms so the compose helpers
+ * don't depend on features.
+ */
+interface RectPose {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Rotation in radians around the unrotated AABB center. Absent === 0. */
+    rotation?: number;
+}
+
+/** Fill rule used by polygon path hit-testing and `ctx.fill()`. */
+type PathFillRule = 'nonzero' | 'evenodd';
+/**
+ * Polygon path with arbitrary contours and optional bezier segments.
+ * Multi-contour: each `M` opens a new subpath; `Z` closes the current one.
+ * Open subpaths (no `Z`) render as polylines and don't contribute to fills.
+ */
+interface PolygonPath {
+    kind: 'polygon';
+    commands: Uint8Array;
+    coords: Float32Array;
+    fillRule: PathFillRule;
+}
+/**
+ * Axis-aligned rectangle. Fast path for the (very common) case where the
+ * shape is just a rect — preserves O(1) bounds and hit-test, avoids the
+ * polygon kernel entirely. Promote to `PolygonPath` only when the shape
+ * grows beyond what a rect can express.
+ */
+interface RectPath {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Canonical path shape — either an axis-aligned rect (fast path) or a polygon command stream. */
+type Path = PolygonPath | RectPath;
+
+/**
+ * # SceneNode — the thing in the scene
+ *
+ * A `SceneNode` is the single canonical unit of a weasel scene. Everything
+ * the user sees on the canvas — a shape, a group, an annotation, a tile —
+ * is one of these. Containers and leaves are both nodes; the kit has no
+ * other concept of "scene element."
+ *
+ * ## Three orthogonal slots
+ *
+ * Every node carries three independent slots, plus its tree position:
+ *
+ *   - **`data: TData`** — app-defined payload. The kit never inspects it.
+ *     Color, label, kind, glyph, sample-rate, whatever the app's domain
+ *     calls for. Mutated via `Scene.update(id, { data })`.
+ *
+ *   - **`pose: TPose`** — local transform, relative to the node's direct
+ *     parent (or world, for root nodes). Default `RectPose` is
+ *     `{ x, y, width, height }`, but `TPose` is fully generic so apps can
+ *     use rotated rects, paths, ellipses, etc. The kit composes world
+ *     poses via `composeWorldPose` when rendering / hit-testing / snapping.
+ *
+ *   - **`layer: TLayer`** — a string tag associating the node with a
+ *     visual `RenderLayer` at draw time. Separate from `LayerRecord` (the
+ *     per-layer visible/locked metadata held by the `Scene`).
+ *
+ * Tree position lives on the node itself: every node has a `parent` (or
+ * `null` for roots), and `ContainerNode` adds an ordered `children: NodeId[]`.
+ *
+ * ## Identity is by `NodeId`, not by reference
+ *
+ * Nodes are addressed by `NodeId` everywhere outside the scene tree:
+ * selection is `NodeId[]`, ops reference `NodeId`s, adapter methods accept
+ * `string` ids and look up the node on demand. The `Node` object itself is
+ * a snapshot of current state — don't hold references to it across scene
+ * updates; look up by id when you need the latest.
+ *
+ * Picking helpers (`pickBest`, `pickEvery`) likewise return ids, not nodes —
+ * they're hit-testing primitives that stay ignorant of node payload shape.
+ *
+ * ## Vocabulary
+ *
+ * The kit-internal name is `Node`; the public re-export is `SceneNode`
+ * (avoids collision with DOM `Node` at call sites). Adapter methods speak
+ * the same vocabulary: `getNode`, `getNodes`, `insertNode`, `removeNode`,
+ * `cloneNode`, `addNode`. Older code, demos, and comments may still say
+ * "object" or "item" — those are historical aliases for the same concept.
+ */
+/** Opaque branded id. Treat as opaque outside the kit. */
+type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
+interface NodeBase<TData, TLayer extends string, TPose> {
+    id: NodeId;
+    layer: TLayer;
+    pose: TPose;
+    data: TData;
+    parent: NodeId | null;
+}
+interface LeafNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
+    kind: 'leaf';
+}
+interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
+    kind: 'container';
+    children: NodeId[];
+    /** Optional clip-path source. Re-evaluated each render. Returning `null`
+     *  means "no clip for this container right now"; an empty / zero-area path
+     *  means "clip everything out" (children render nowhere). When set, the
+     *  renderer rasterizes the returned path into the stencil buffer and
+     *  paints descendants only where it covers. */
+    clipFromPose?: (pose: TPose) => Path | null;
+}
+type Node<TData, TLayer extends string, TPose = RectPose> = LeafNode<TData, TLayer, TPose> | ContainerNode<TData, TLayer, TPose>;
+interface LayerRecordBase<TLayer extends string> {
+    id: TLayer;
+    visible: boolean;
+    locked: boolean;
+}
+interface SystemLayerRecord<TLayer extends string> extends LayerRecordBase<TLayer> {
+    kind: 'system';
+}
+interface UserLayerRecord<TLayer extends string> extends LayerRecordBase<TLayer> {
+    kind: 'user';
+    name: string;
+}
+type LayerRecord<TLayer extends string> = SystemLayerRecord<TLayer> | UserLayerRecord<TLayer>;
+interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
+    kind: 'leaf' | 'container';
+    layer: TLayer;
+    pose: TPose;
+    data: TData;
+    parent?: NodeId | null;
+    index?: number;
+    /** Explicit id wins over the Scene's `generateId` and the kit default. */
+    id?: NodeId;
+    /** Only meaningful when `kind === 'container'`. Attach a clip-path function
+     *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */
+    clipFromPose?: (pose: TPose) => Path | null;
+}
+interface RegisteredOp<P> {
+    apply: (payload: P) => void;
+    revert: (payload: P) => void;
+}
+interface SystemLayerSpec<TLayer extends string> {
+    id: TLayer;
+    visible?: boolean;
+    locked?: boolean;
+}
+/** Argument to `Scene.addLayer`. Always produces a `UserLayerRecord`
+ *  (`kind: 'user'`). */
+interface AddLayerSpec<TLayer extends string> {
+    id: TLayer;
+    name: string;
+    /** Default `true`. */
+    visible?: boolean;
+    /** Default `false`. */
+    locked?: boolean;
+    /** Render-stack position. Default: top of stack (highest render index). */
+    index?: number;
+}
+/** JSON-serializable shape of a Scene's current state. Produced by
+ *  `scene.toJSON()`; consumed by `sceneFromJSON()`. Function fields
+ *  (e.g., `clipFromPose`) appear as string keys (`clipFromPoseKey`) and
+ *  are resolved through `SceneRegistry` at load time. */
+interface SerializedScene<TData, TLayer extends string, TPose> {
+    version: 1;
+    systemLayers: readonly SystemLayerSpec<TLayer>[];
+    nodes: readonly SerializedNode<TData, TLayer, TPose>[];
+}
+/** JSON-serializable shape of a single node. Mirrors `AddNodeSpec` but
+ *  with function fields replaced by registry keys. */
+interface SerializedNode<TData, TLayer extends string, TPose> {
+    id: string;
+    kind: 'leaf' | 'container';
+    layer: TLayer;
+    pose: TPose;
+    data: TData;
+    /** Parent id; omitted for roots. */
+    parent?: string;
+    /** Registry key for the container's clip-path factory.
+     *  Containers only; omitted when the container has no clip. */
+    clipFromPoseKey?: string;
+}
+interface Scene<TData, TLayer extends string, TPose = RectPose> {
+    readonly nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>;
+    readonly roots: readonly NodeId[];
+    readonly layers: readonly LayerRecord<TLayer>[];
+    get(id: NodeId): Node<TData, TLayer, TPose> | undefined;
+    childrenOf(id: NodeId): readonly NodeId[];
+    ancestorsOf(id: NodeId): readonly NodeId[];
+    renderOrder(): Iterable<NodeId>;
+    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). */
+    remove(id: NodeId): void;
+    update(id: NodeId, patch: {
+        data: TData;
+    }): void;
+    setPose(id: NodeId, pose: TPose): void;
+    /** Retag `id` to `layer`. On a **container this cascades**: every descendant
+     *  is moved to the same layer, recorded as a **single** undo step.
+     *
+     *  Invariants:
+     *  - **Layer floor** — a child may not render below its parent, so retagging
+     *    to a layer *below* the node's parent throws. Retagging to the parent's
+     *    layer or any higher one is allowed; a node with no parent is
+     *    unconstrained.
+     *  - **No-op elision** — setting the layer a node already has does nothing
+     *    and pushes **no** history entry. */
+    setLayer(id: NodeId, layer: TLayer): void;
+    /** Reparent `id` under `parent` (or to a root when `parent` is `null`) at
+     *  `index` within the new sibling list, appending when `index` is omitted.
+     *  Siblings are reindexed. Recorded as one undoable step.
+     *
+     *  Rejected (throws) when:
+     *  - `parent` exists but is a **leaf**, not a container;
+     *  - the move would form a **cycle** — `parent` is `id` itself or one of
+     *    `id`'s own descendants;
+     *  - it would drop `id` **below its new parent's layer** (child may not
+     *    render below its parent).
+     *
+     *  `move(id, null)` — detaching to a root — is always allowed regardless of
+     *  layer, since a root has no parent to render beneath. */
+    move(id: NodeId, parent: NodeId | null, index?: number): void;
+    /** Shift `id` to `index` within its **current** parent's child list. Unlike
+     *  {@link move}, the parent never changes — only sibling order. */
+    reorder(id: NodeId, index: number): void;
+    setLayerVisible(layer: TLayer, visible: boolean): void;
+    setLayerLocked(layer: TLayer, locked: boolean): void;
+    addLayer(spec: AddLayerSpec<TLayer>): void;
+    removeLayer(layer: TLayer): void;
+    renameLayer(layer: TLayer, name: string): void;
+    moveLayer(layer: TLayer, index: number): void;
+    registerOp<P>(kind: string, handler: RegisteredOp<P>): void;
+    recordOp<P>(op: {
+        kind: string;
+        payload: P;
+    }): void;
+    /** Install (or clear) the active-journal accessor after scene construction.
+     *  Useful when the journal source (typically a mode machine) is built
+     *  with `scene.history` as a dependency — a chicken-and-egg situation
+     *  where the accessor can't be passed in via `UseSceneOptions`.
+     *
+     *  Pass `null` to detach. Overrides any `getActiveJournal` set in
+     *  `UseSceneOptions`. */
+    setActiveJournalAccessor(fn: (() => Journal | null) | null): void;
+    /** Apply a batch of ops with journal-aware routing.
+     *
+     *  - **Without active journal** (or no `getActiveJournal` in options):
+     *    the ops themselves are recorded as one undo entry on the scene's own
+     *    history, rebound to `adapter` — undo replays each op's `invert()`
+     *    against that same adapter. Consecutive `applyBatch` entries can
+     *    coalesce via matching op `coalesceKey`s when the scene opts into
+     *    `coalesceWindowMs`.
+     *  - **With active journal**: routes ops to `journal.applyBatch(ops, label)`.
+     *    The scene's history recording is suppressed for the duration so the
+     *    journal's inner history — not the scene's undo stack — tracks the batch.
+     *    Mutations still happen on `adapter` / scene state.
+     *
+     *  `adapter` must be the same adapter the ops expect (typically a
+     *  `SceneCanvasAdapter`). Pass `this` from `sceneToAdapter` or a compatible
+     *  adapter. */
+    applyBatch(ops: Op[], label: string, adapter: unknown): void;
+    undo(): boolean;
+    redo(): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    batch<T>(label: string, fn: () => T): T;
+    /** Read-only snapshot of every history entry currently reachable from
+     *  the present state. Oldest applied first, then redoable entries in
+     *  the order they'd be re-applied. Each entry id is stable. */
+    historyEntries(): readonly {
+        id: string;
+        label: string;
+    }[];
+    /** Index of the "current state". Equals the count of applied entries;
+     *  `0` means "nothing applied" (initial). */
+    historyIndex(): number;
+    /** Jump to the given history index by calling undo/redo repeatedly.
+     *  Clamps to [0, total]. Returns true if any movement occurred. */
+    jumpToHistoryIndex(index: number): boolean;
+    /** Snapshot the undo/redo history in a JSON-serializable form (the
+     *  engine's `SerializedHistory`). Entries containing any nameless op are
+     *  dropped (hand-rolled anonymous ops passed to `applyBatch`); kit and
+     *  consumer-registered ops always carry names. Payload JSON-safety
+     *  (e.g. typed arrays inside poses) is the caller's concern. Do not call
+     *  mid-`batch` — the open batch's ops are not yet recorded. */
+    serializeHistory(): SerializedHistory;
+    /** Replace the undo/redo history from a `serializeHistory()` snapshot.
+     *  Call on a scene whose node/layer state already matches the snapshot's
+     *  head state (i.e. right after `loadState` from the paired scene
+     *  snapshot); node state is NOT mutated. Ops re-registered via
+     *  `registerOp` before this call round-trip; unknown kinds become no-op
+     *  placeholders; external ops rebuild via the global op-factory registry
+     *  and replay against the `setHistoryAdapter` accessor. Restored entries
+     *  never coalesce with new ones. Notifies once. Do not call mid-`batch`:
+     *  the stacks are replaced underneath the open batch, whose eventual
+     *  flush would graft onto (and evict against) the restored stacks. */
+    restoreHistory(snapshot: SerializedHistory): void;
+    /** Install (or clear with `null`) the accessor for the adapter that
+     *  RESTORED external ops (recorded via `applyBatch`, rebuilt from a
+     *  `restoreHistory` snapshot) apply against on undo/redo. Resolved lazily
+     *  at each apply, so wiring order relative to `restoreHistory` doesn't
+     *  matter. Live `applyBatch` entries are unaffected (they bind their
+     *  call-site adapter). If unset when a restored op applies, the op is a
+     *  debug-warned no-op. */
+    setHistoryAdapter(fn: (() => unknown) | null): void;
+    /** Snapshot the current scene state to a JSON-serializable shape.
+     *  History (undo/redo stacks) is NOT captured. Function fields like
+     *  `ContainerNode.clipFromPose` are translated to string keys via the
+     *  scene's registry; throws if any function field has no matching key. */
+    toJSON(): SerializedScene<TData, TLayer, TPose>;
+    /** Replace this scene's entire node + layer state in place from a snapshot
+     *  produced by `toJSON()`. Unlike `sceneFromJSON`, the existing Scene
+     *  instance is preserved — holders such as `<SceneCanvas>` keep their
+     *  reference. History (undo/redo) is cleared, matching `sceneFromJSON`.
+     *  Bumps `getVersion()` and notifies subscribers exactly once.
+     *
+     *  Throws on an unsupported version or unknown registry/layer ids; on a
+     *  malformed snapshot the scene is left empty or partially populated (callers should treat a
+     *  `loadState` throw as fatal and reload). Snapshots from `toJSON()` are
+     *  always well-formed. */
+    loadState(json: SerializedScene<TData, TLayer, TPose>): void;
+    subscribe(listener: () => void): () => void;
+    /** Monotonically increasing version. Snapshot for `useSyncExternalStore`. */
+    getVersion(): number;
+}
+
+/**
+ * Viewport state. `(view.x, view.y)` is the **world point currently
+ * rendered at the canvas top-left**; `view.scale.x` / `view.scale.y` is
+ * pixels per world unit on each axis (default `{ x: 1, y: 1 }`). So:
+ *
+ *   screenX = (worldX - view.x) * view.scale.x
+ *   screenY = (worldY - view.y) * view.scale.y
+ *   worldX  = screenX / view.scale.x + view.x
+ *   worldY  = screenY / view.scale.y + view.y
+ *
+ * `scale` is always a 2-vector. Input convenience types
+ * {@link ZoomFactor} and {@link ZoomBound} let callers pass a scalar
+ * when they want both axes treated the same.
+ */
+interface View {
+    x: number;
+    y: number;
+    scale: {
+        x: number;
+        y: 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;
+
+/**
+ * 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).
+ */
+interface TextureHandle {
+    readonly id: string;
+}
+
+/**
+ * FillStyle and Stroke types — the unified shape for "what color or texture
+ * paints these pixels," modeled on SVG's paint-server concept.
+ *
+ * - `FillStyle` is a tagged union: solid color, pattern, or gradient. Used
+ *   wherever a kit option previously took `fillStyle: string`.
+ * - `Stroke` pairs a `FillStyle` with structural stroke parameters (width, dash,
+ *   line cap/join, alignment).
+ * - These types are consumed by the GL renderer's DrawCommand path fills
+ *   and strokes.
+ *
+ * The 2D `applyPaint` / `applyStroke` / `renderFilledRegion` helpers that
+ * formerly lived alongside these types were deleted with the 2D backend in
+ * Step 10. `alignedStrokeRect` survives as a pure geometry helper used by
+ * path tessellation and the selection overlay.
+ */
+
+/**
+ * Color/texture strategy for fills (and, via `Stroke.paint`, strokes).
+ *
+ * `fill` is optional and defaults to `'solid'` — `{ color: '#abc' }` is
+ * equivalent to `{ fill: 'solid', color: '#abc' }`. Pattern paints must set
+ * `fill: 'pattern'` explicitly.
+ *
+ * The `'pattern'` variant's payload is a `TextureHandle` (registered via
+ * `registerTexture()`). The kit-level factory `createTilePattern` (and the
+ * `patterns-builtin` catalog: `hatch`, `crosshatch`, `dots`, `chunks`)
+ * produces these handles by rendering a tile to an `OffscreenCanvas` and
+ * registering the resulting `ImageBitmap` as a GL texture.
+ */
+type FillStyle = {
+    fill?: 'solid';
+    color: string;
+    opacity?: number;
+} | {
+    fill: 'pattern';
+    pattern: TextureHandle;
+    opacity?: number;
+} | {
+    fill: 'linear-gradient';
+    from: {
+        x: number;
+        y: number;
+    };
+    to: {
+        x: number;
+        y: number;
+    };
+    stops: GradStop[];
+    opacity?: number;
+} | {
+    fill: 'radial-gradient';
+    center: {
+        x: number;
+        y: number;
+    };
+    radius: number;
+    stops: GradStop[];
+    opacity?: number;
+} | {
+    fill: 'conic-gradient';
+    center: {
+        x: number;
+        y: number;
+    };
+    angle: number;
+    stops: GradStop[];
+    opacity?: number;
+};
+/** A single color stop within a gradient. `offset` is in 0..1. */
+interface GradStop {
+    offset: number;
+    color: string;
+}
+/**
+ * Where a stroke sits relative to the geometric edge it strokes.
+ *
+ * - `'center'` (default): canvas-native — half the stroke width sits inside
+ *   the geometry, half outside.
+ * - `'inner'`: the entire stroke lies inside the geometry. The outer edge of
+ *   the stroke coincides with the geometric edge.
+ * - `'outer'`: the entire stroke lies outside the geometry. The inner edge
+ *   of the stroke coincides with the geometric edge.
+ *
+ * Mirrors the (proposed) SVG `stroke-alignment` property. Honoring `inner`
+ * or `outer` is the renderer's responsibility — for axis-aligned rects, the
+ * kit shifts coordinates by `width / 2`. For arbitrary paths, renderers
+ * typically use a stencil mask of the stroked path against the geometry.
+ */
+type StrokeAlign = 'center' | 'inner' | 'outer';
+/** Stroke style: a FillStyle plus structural line parameters. */
+interface Stroke {
+    paint: FillStyle;
+    width?: number;
+    /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */
+    dash?: number[];
+    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?: number;
+    /** Where the stroke sits relative to the geometric edge. Default `'center'`. */
+    align?: StrokeAlign;
+    /**
+     * Per-anchor RGBA, flat (length = 4 × countPathAnchors(path)). Each
+     * value in 0..1. Arc-length interpolated across the tessellated ribbon
+     * between consecutive anchors. When set, `paint` is still required —
+     * its `opacity` (and color, as a placeholder) flow through the shader.
+     */
+    vertexColors?: number[];
+    /**
+     * Per-anchor stroke width (length = `countPathAnchors(path)`). When set,
+     * the tessellator interpolates half-widths along each segment to produce
+     * a tapered ribbon. `width` is used as the fallback for any anchor whose
+     * entry is missing or non-finite. Pressure-driven pencil strokes use
+     * this; pair with `pressureToWidth` to derive widths from stylus input.
+     *
+     * Joins between adjacent segments whose widths differ by more than
+     * `varyingWidthJoinThreshold` (default 1.5×) are forced to bevel
+     * regardless of the `join` setting — miter math is unstable when widths
+     * vary across the corner; smooth round joins with mismatched widths
+     * are a future enhancement.
+     */
+    vertexWidths?: number[];
+    /**
+     * Max width ratio (greater / lesser) at which a non-bevel join is
+     * preserved when `vertexWidths` causes adjacent segments to differ.
+     * Beyond this ratio the join falls back to bevel. Default 1.5. Ignored
+     * when `vertexWidths` is absent.
+     */
+    varyingWidthJoinThreshold?: number;
+}
+
+/**
+ * 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.
+ */
+
+/** User-facing text style. All fields optional; defaults applied at render time via `resolveTextStyle`. */
+interface TextStyle {
+    /** Font size in world units. Default 16. */
+    fontSize?: number;
+    /** Default `'sans-serif'`. */
+    fontFamily?: string;
+    /** Default 400. */
+    fontWeight?: number | string;
+    /** Default `'normal'`. */
+    fontStyle?: 'normal' | 'italic';
+    /** Default `'left'`. */
+    align?: 'left' | 'center' | 'right';
+    /** 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.
+     */
+    caretColor?: string;
+    /**
+     * Selection background color used by the edit overlay's `::selection`
+     * pseudo-element. Defaults to a 25%-opacity tint of `caretColor` via CSS
+     * `color-mix`. Pass `'none'` to fall back to the browser-native highlight.
+     */
+    selectionBackground?: string;
+    /** Selection text color paired with `selectionBackground`. Default: inherits text color. */
+    selectionColor?: string;
+}
+
+/**
+ * Apply node-level `ResolvedTextStyle` defaults to each `StyledRun`,
+ * producing a fully-resolved run with every styling field set. Downstream
+ * layout and draw never re-resolve defaults — `ResolvedRun` is the
+ * canonical shape the renderer consumes.
+ *
+ * `bold`/`italic` toggles on a run are folded into `fontWeight`/`fontStyle`:
+ * `bold: true` → fontWeight 700, `italic: true` → fontStyle 'italic'.
+ * Explicit `fontFamily` / `fontSize` / `fill` on the run override the
+ * node-level value.
+ */
+
+interface ResolvedRun {
+    text: string;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: number;
+    fontStyle: 'normal' | 'italic';
+    fill: FillStyle;
+}
+
+/**
+ * Box vertical alignment for text draw commands. Given the command's box
+ * `height` and the laid-out text block's height, returns the Y offset to
+ * apply to every quad. `'top'` (or an undefined `align`, or a missing box
+ * `height`) is the legacy behavior: offset 0.
+ */
+type TextVerticalAlign = 'top' | 'center' | 'bottom';
+
+/**
+ * registerProgram — public API for registering custom shader programs.
+ *
+ * Stores raw GLSL source strings in a module-level registry. GL compilation
+ * happens on each WeaselRenderer via WeaselRenderer.registerProgram(), which
+ * 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
+ * programs live on each renderer's programRegistry (Map<id, ShaderProgram>).
+ *
+ * Lifecycle: program sources live for the module lifetime. No unregister in v1.
+ */
+
+/** Opaque handle to a compiled custom shader program. */
+interface ShaderProgramHandle {
+    readonly id: string;
+}
+/**
+ * Scalar and vector uniform types accepted by the custom shader uniform binder.
+ *
+ * | TS type                 | GL call                              |
+ * |-------------------------|--------------------------------------|
+ * | number                  | uniform1f                            |
+ * | [n, n]                  | uniform2fv                           |
+ * | [n, n, n]               | uniform3fv                           |
+ * | [n, n, n, n]            | uniform4fv                           |
+ * | Float32Array length 9   | uniformMatrix3fv (column-major)      |
+ * | Float32Array length 16  | uniformMatrix4fv (column-major)      |
+ * | TextureHandle           | bind to next tex unit + uniform1i    |
+ */
+type ShaderUniform = number | [number, number] | [number, number, number] | [number, number, number, number] | Float32Array | TextureHandle;
+
+/** DrawCommand variants implemented through step 6. */
+type DrawCommand = PathDrawCommand | GroupDrawCommand | TextDrawCommand | ImageDrawCommand | ShaderDrawCommand;
+interface PathDrawCommand {
+    kind: 'path';
+    path: Path;
+    /** Any `FillStyle` variant: solid, pattern, or gradient (linear/radial/conic). */
+    fill?: FillStyle;
+    /** Stroke spec. Only solid `paint` supported through step 4. */
+    stroke?: Stroke;
+    /**
+     * Optional flat RGBA-per-path-anchor color array (length =
+     * `4 × countPathAnchors(path)`, floats in 0..1). The renderer
+     * arc-length-interpolates these per-anchor colors across the
+     * flattened/triangulated mesh between consecutive anchors using the
+     * mesh's `anchorA` / `anchorB` / `anchorT` parameterization.
+     *
+     * **`fill` must also be set when using `vertexColors`.** The renderer
+     * only enters the per-vertex shader path when the command has a fill
+     * (the fill provides the opacity uniform; the vertex colors override
+     * the fill's color). Pass any solid `fill` (e.g. `{ color: '#fff' }`)
+     * as the placeholder; the per-vertex colors win in the shader.
+     */
+    vertexColors?: number[];
+}
+interface GroupDrawCommand {
+    kind: 'group';
+    transform?: Mat3;
+    alpha?: number;
+    /**
+     * Optional 4×5 color matrix (row-major, 20 numbers) — `out = M₄ₓ₄ * in + bias`.
+     * Accumulated multiplicatively down the group stack. Defaults to identity.
+     */
+    colorMatrix?: number[];
+    /** Optional clip path. When set, the renderer rasterizes this path into
+     *  the stencil buffer before drawing `children`; the children paint only
+     *  where the clip covers. Nested groups with clips intersect — a child
+     *  cannot escape an ancestor's clip. Max 7 nesting levels; the renderer
+     *  throws if exceeded. */
+    clip?: Path;
+    children: DrawCommand[];
+}
+/**
+ * Text draw command. Renders one or more runs at (`x`, `y`) in screen
+ * space, optionally word-wrapping at `maxWidth`. The renderer resolves
+ * each run's `(fontFamily, fontWeight, fontStyle)` to an MSDF atlas via
+ * `resolveFontVariant` and bucket-draws by atlas + color group.
+ *
+ * `style` carries node-level defaults (`lineHeight`, anti-alias width)
+ * that don't belong on individual runs.
+ */
+interface TextDrawCommand {
+    kind: 'text';
+    x: number;
+    y: number;
+    runs: ResolvedRun[];
+    maxWidth?: number;
+    align?: 'left' | 'center' | 'right';
+    style: TextStyle;
+    /** Box height for vertical alignment. When set with `verticalAlign`,
+     *  the laid-out block shifts within `[y, y+height]`. */
+    height?: number;
+    /** Default 'top' — the legacy top-anchored behavior. */
+    verticalAlign?: TextVerticalAlign;
+}
+/**
+ * Image draw command — renders `image` at screen-space rect (x, y, w, h).
+ * The image is stretched to fit; no tiling. Use a pattern FillStyle on a path
+ * for tiling.
+ */
+interface ImageDrawCommand {
+    kind: 'image';
+    image: ImageBitmap;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    opacity?: number;
+}
+/**
+ * Custom shader draw command. The renderer generates a quad over `bounds`
+ * and dispatches the consumer's fragment shader with the kit's vertex prelude.
+ *
+ * `uniforms` keys must match names declared in the consumer's fragment shader.
+ * The kit automatically sets `u_bounds`, `u_view`, and `u_proj` — do not
+ * declare those in `uniforms`.
+ *
+ * @experimental API may change before v2.
+ */
+interface ShaderDrawCommand {
+    kind: 'shader';
+    program: ShaderProgramHandle;
+    uniforms: Record<string, ShaderUniform>;
+    /** Screen-space bounding rect in CSS pixels. */
+    bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+
+/**
+ * Axis-aligned rectangle in world space. Kit-wide `Bounds` shape used by
+ * selection, group, and viewport helpers. The optional `rotation` field
+ * (radians, around the AABB center) lets selection chrome attach a rotated
+ * orientation to an otherwise axis-aligned rect without needing a parallel
+ * type.
+ */
+interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+}
+/** Pixel dimensions of the canvas viewport. */
+interface ViewportDims {
+    width: number;
+    height: number;
+}
+
+export type { Bounds as B, DrawCommand as D, Node as N, Op as O, PathDrawCommand as P, Scene as S, View as V, ViewportDims as a, NodeId as b };