@weasel-js/labkit 1.0.2 → 1.0.3

package/dist/_dts/{DrawCommand-CitWPxMY.d.ts → DrawCommand-uKHt4Vul.d.ts}

@@ -32,10 +32,30 @@ interface Op {
     args?: unknown;
 }
 
+/** Options for `history.beginJournal()`. */
 interface BeginJournalOptions {
+    /** Label for the single parent-history entry the journal flushes on commit. */
     label: string;
+    /** Caller-supplied tag naming what this journal is scoped to — typically the
+     *  id of the node being edited. The history layer only carries it; callers
+     *  read it back off the journal to decide whether a suspended journal
+     *  matches what they are about to edit. */
     targetId?: string;
 }
+/**
+ * A scoped sub-history forked from a `History`, opened by
+ * `history.beginJournal()`. Applies, undoes and redoes against the same
+ * adapter as its parent, but keeps its entries to itself: `commit` flushes the
+ * journal's net forward ops to the parent as one entry, `cancel` rewinds them
+ * and contributes nothing. Use it when a self-contained editing session (a
+ * text edit, a modal drag) should collapse to a single step in the parent's
+ * undo stack while still offering undo *within* the session.
+ *
+ * A journal is active, suspended or closed. `commit` and `cancel` are
+ * terminal; `suspend` lets the parent be used again and can be reversed with
+ * `history.resumeJournal()`. Every mutating method throws when the journal is
+ * not active.
+ */
 interface Journal {
     readonly targetId: string | undefined;
     readonly forkedAtEntryId: number;
@@ -277,9 +297,13 @@ interface NodeBase<TData, TLayer extends string, TPose> {
     data: TData;
     parent: NodeId | 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> {
     kind: 'leaf';
 }
+/** A node with an ordered list of children. This is the real group: what
+ *  Cmd+G creates, what SVG `<g>` round-trips to. A container has its own pose,
+ *  which its children's poses are relative to, and may optionally clip them. */
 interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
     kind: 'container';
     children: NodeId[];
@@ -290,20 +314,30 @@ interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends
      *  paints descendants only where it covers. */
     clipFromPose?: (pose: TPose) => Path | null;
 }
+/** A node in the scene tree: either a leaf or a container. Re-exported
+ *  publicly as `SceneNode`, to avoid colliding with the DOM's `Node`. */
 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;
 }
+/** A layer declared when the scene was created. Fixed set, no display name —
+ *  these are the kit's own render bands, not something a user manages. */
 interface SystemLayerRecord<TLayer extends string> extends LayerRecordBase<TLayer> {
     kind: 'system';
 }
+/** A layer the user created and can rename, reorder or delete. */
 interface UserLayerRecord<TLayer extends string> extends LayerRecordBase<TLayer> {
     kind: 'user';
     name: string;
 }
+/** Per-layer metadata held by the scene: whether it is visible and locked,
+ *  and where it sits in the render stack. Distinct from a node's `layer` tag,
+ *  which merely names one of these. */
 type LayerRecord<TLayer extends string> = SystemLayerRecord<TLayer> | UserLayerRecord<TLayer>;
+/** What `Scene.add` needs to mint a node. Everything except the id is
+ *  required; the id is generated unless one is supplied. */
 interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
     kind: 'leaf' | 'container';
     layer: TLayer;
@@ -317,10 +351,13 @@ interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
      *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */
     clipFromPose?: (pose: TPose) => 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. */
 interface RegisteredOp<P> {
     apply: (payload: P) => void;
     revert: (payload: P) => void;
 }
+/** One of the layers a scene is created with. */
 interface SystemLayerSpec<TLayer extends string> {
     id: TLayer;
     visible?: boolean;
@@ -361,6 +398,18 @@ interface SerializedNode<TData, TLayer extends string, TPose> {
      *  Containers only; omitted when the container has no clip. */
     clipFromPoseKey?: string;
 }
+/**
+ * The kit-owned scene tree: nodes, layers, and the undo history over both.
+ *
+ * A scene is logical, not visual — it says what exists and where, and nothing
+ * about how it is painted. Every mutating method is undoable, and reads are
+ * snapshots rather than live views. Nodes are addressed by `NodeId`; hold ids
+ * across mutations, not node objects.
+ *
+ * Three type parameters keep it domain-agnostic: `TData` is the app's payload,
+ * which the kit never inspects; `TPose` is the transform shape, `RectPose` by
+ * default; `TLayer` is the union of layer names.
+ */
 interface Scene<TData, TLayer extends string, TPose = RectPose> {
     readonly nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>;
     readonly roots: readonly NodeId[];
@@ -865,6 +914,8 @@ interface TextStyle {
  * `runs/rangeStyle.ts` for why the model collapses the tri-state.
  */
 
+/** A run with every style resolved against the node's text style — no
+ *  optional inheritance left. This is what layout and painting consume. */
 interface ResolvedRun {
     text: string;
     fontFamily: string;
@@ -926,6 +977,8 @@ type ShaderUniform = number | [number, number] | [number, number, number] | [num
 
 /** DrawCommand variants implemented through step 6. */
 type DrawCommand = PathDrawCommand | GroupDrawCommand | TextDrawCommand | ImageDrawCommand | ShaderDrawCommand;
+/** Draw a path, filled and/or stroked. The workhorse command: every shape the
+ *  kit draws that is not text, an image, or a custom shader is one of these. */
 interface PathDrawCommand {
     kind: 'path';
     path: Path;
@@ -948,6 +1001,9 @@ interface PathDrawCommand {
      */
     vertexColors?: number[];
 }
+/** Draw a list of commands under a shared transform, opacity, color matrix
+ *  and clip. Groups nest, and their effects accumulate down the stack — this
+ *  is how a container node's transform reaches its descendants. */
 interface GroupDrawCommand {
     kind: 'group';
     transform?: Mat3;

package/dist/_dts/{index-C6Yze7sQ.d.ts → index-CFlDPeZh.d.ts}

@@ -1,6 +1,8 @@
 import { ReactNode } from 'react';
-import { C as ConfigField } from './types-Si4Fw-1F.js';
+import { C as ConfigField } from './types-x92Kfeme.js';
 
+/** What an instrument's `render` is handed: its state and config, the setters
+ *  for both, the workspace it is mounted in, and a way to emit named events. */
 interface RenderContext<TS = unknown, TC = unknown> {
     state: TS;
     config: TC;
@@ -13,6 +15,7 @@ interface RenderContext<TS = unknown, TC = unknown> {
     };
     emit: (event: string) => void;
 }
+/** One 2D canvas layer of an instrument, drawn in declaration order. */
 interface CanvasLayer<TS = unknown, TC = unknown> {
     id: string;
     draw: (ctx: CanvasRenderingContext2D, args: {
@@ -21,6 +24,8 @@ interface CanvasLayer<TS = unknown, TC = unknown> {
         zoom: number;
     }) => void;
 }
+/** Declares that an instrument draws to a canvas: its layers, and where the
+ *  view starts. */
 interface CanvasCapability<TS = unknown, TC = unknown> {
     layers: CanvasLayer<TS, TC>[];
     initialView?: {
@@ -31,9 +36,14 @@ interface CanvasCapability<TS = unknown, TC = unknown> {
         };
     };
 }
+/** Declares which of an instrument's layers the workspace should offer
+ *  show/hide controls for. */
 interface LayerCapability {
     ids: string[];
 }
+/** Declares that an instrument accepts items dragged from a palette: what the
+ *  palette offers, what a drop does to the state, and — optionally — live
+ *  feedback during the drag and the ability to drag existing items back out. */
 interface DragDropCapability<TS = unknown, TC = unknown> {
     palette: PaletteItem[] | ((state: TS, config: TC) => PaletteItem[]);
     onDrop: (worldPos: Point, item: PaletteItem, state: TS, config: TC) => TS;
@@ -43,38 +53,57 @@ interface DragDropCapability<TS = unknown, TC = unknown> {
         state: TS;
     } | null;
 }
+/** Declares that an instrument's state is undoable: which emitted events
+ *  snapshot it, and how many snapshots to keep. */
 interface UndoCapability {
     snapshotOn?: string[];
     maxDepth?: number;
 }
+/** The name of an event an instrument emits through `RenderContext.emit`. */
 type SystemEvent = string;
+/** A point in world coordinates. */
 type Point = {
     x: number;
     y: number;
 };
+/** What a hit-test found, and where. */
 type HitResult = {
     hit: boolean;
     layerId?: string;
     pointId?: string;
 };
+/** A workspace's camera. */
 type ViewTransform = {
     zoom: number;
     pan: Point;
 };
+/** A layer as the layer list shows it. `alwaysOn` layers cannot be hidden. */
 type LayerDescriptor = {
     id: string;
     label: string;
     alwaysOn?: boolean;
 };
+/** One draggable entry in an instrument's palette. */
 type PaletteItem = {
     id: string;
     label: string;
     data?: unknown;
 };
+/** Whether a drop would be accepted at the current position, and why not if
+ *  it would not. */
 type DragFeedback = {
     ok: boolean;
     reason?: string;
 };
+/**
+ * An instrument: one self-contained interactive experiment a lab can host.
+ *
+ * It owns two pieces of data — `config`, the settings the control panel edits,
+ * and `state`, what the experiment is currently doing — and renders from both.
+ * The optional capability fields declare what else it wants from the runtime:
+ * a canvas, a layer list, palette drag-and-drop, undo. Declaring a capability
+ * is what makes the workspace provide the corresponding chrome.
+ */
 interface Instrument<TS = unknown, TC = unknown> {
     name: string;
     defaultConfig: () => TC;

package/dist/_dts/{types-Si4Fw-1F.d.ts → types-x92Kfeme.d.ts}

@@ -1,9 +1,13 @@
+/** Which control a config field is edited with. */
 type ConfigFieldType = 'slider' | 'checkbox' | 'select' | 'number' | 'text' | 'color';
+/** What every config field carries: the config key it writes, the label shown
+ *  beside it, and which control renders it. */
 interface ConfigFieldBase {
     key: string;
     label: string;
     type: ConfigFieldType;
 }
+/** A bounded number edited by dragging. */
 interface SliderField extends ConfigFieldBase {
     type: 'slider';
     default: number;
@@ -11,19 +15,24 @@ interface SliderField extends ConfigFieldBase {
     max: number;
     step?: number;
 }
+/** A boolean. */
 interface CheckboxField extends ConfigFieldBase {
     type: 'checkbox';
     default: boolean;
 }
+/** One choice in a select field. */
 interface SelectOption {
     value: string;
     label: string;
 }
+/** A fixed set of labeled choices. */
 interface SelectField extends ConfigFieldBase {
     type: 'select';
     default: string;
     options: SelectOption[];
 }
+/** A number typed directly, optionally bounded. Use a slider field instead
+ *  when the range matters more than the exact value. */
 interface NumberField extends ConfigFieldBase {
     type: 'number';
     default: number;
@@ -31,6 +40,8 @@ interface NumberField extends ConfigFieldBase {
     max?: number;
     step?: number;
 }
+/** A free-text string. Writes are debounced so typing does not re-run the
+ *  instrument on every keystroke. */
 interface TextField extends ConfigFieldBase {
     type: 'text';
     default: string;
@@ -39,10 +50,13 @@ interface TextField extends ConfigFieldBase {
     /** Milliseconds to debounce live setConfig calls. Default 150 ms. Set to 0 to disable. */
     debounceMs?: number;
 }
+/** A color, as a CSS color string. */
 interface ColorField extends ConfigFieldBase {
     type: 'color';
     default: string;
 }
+/** One field of an instrument's config schema. The schema is what the control
+ *  panel renders, and what `validateConfigSchema` checks. */
 type ConfigField = SliderField | CheckboxField | SelectField | NumberField | TextField | ColorField;
 
 export type { ConfigField as C, NumberField as N, SelectField as S, TextField as T, CheckboxField as a, ColorField as b, ConfigFieldBase as c, ConfigFieldType as d, SelectOption as e, SliderField as f };

package/dist/_dts/{useExperimentState-CJn2hHzd.d.ts → useExperimentState-vrttakTt.d.ts}

@@ -2,10 +2,14 @@ import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { StoreApi } from 'zustand/vanilla';
 
+/** A workspace's undo history, as snapshots of its state either side of the
+ *  present. */
 interface UndoStack {
     past: unknown[];
     future: unknown[];
 }
+/** One workspace as the store holds it: which instrument it runs, that
+ *  instrument's config and state, the camera, and the undo history. */
 interface WorkspaceRecord<TS = unknown, TC = unknown> {
     id: string;
     instrumentName: string;
@@ -20,6 +24,8 @@ interface WorkspaceRecord<TS = unknown, TC = unknown> {
     };
     undoStack: UndoStack;
 }
+/** A named, saved copy of a workspace's config and state, restorable into any
+ *  workspace running the same instrument. */
 interface SavedSnapshot {
     id: string;
     name: string;
@@ -31,38 +37,59 @@ interface SavedSnapshot {
 }
 /** `auto` follows the OS; the other two are an explicit choice. */
 type LabMode = 'auto' | 'light' | 'dark';
+/** Everything a lab persists: its workspaces, its saved snapshots, and the
+ *  chosen color mode. */
 interface LabStoreState {
     workspaces: WorkspaceRecord[];
     savedSnapshots: SavedSnapshot[];
     mode: LabMode;
 }
+/** Where a lab persists itself. Implementations are keyed string storage and
+ *  nothing more, so the same store works against localStorage, the URL hash,
+ *  or memory. */
 interface StorageAdapter {
     read(key: string): string | null;
     write(key: string, value: string): void;
     delete?(key: string): void;
 }
+/** What `useExperimentState` hands an instrument: its state and config, with
+ *  a setter for each. */
 interface ExperimentStateHandle<TS, TC> {
     state: TS;
     setState: (next: TS | ((prev: TS) => TS)) => void;
     config: TC;
     setConfig: (key: keyof TC, value: TC[keyof TC]) => void;
 }
+/** Options for `createLabStore`. `storageKey` namespaces the keys written, so
+ *  two labs on one origin do not collide. */
 interface CreateLabStoreOptions {
     storageKey: string;
     storage: StorageAdapter;
     initialMode?: LabMode;
 }
+/** Per-instrument serialize/deserialize hooks, keyed by instrument name. An
+ *  instrument whose state is already JSON-safe needs no entry. */
 type InstrumentSerializers = Record<string, {
     serialize?: (state: unknown) => unknown;
     deserialize?: (data: unknown) => unknown;
 } | undefined>;
 
+/** Persist to `localStorage` — state survives a reload and a new tab. Falls
+ *  back to no-ops when storage is unavailable. */
 declare const localStorageAdapter: StorageAdapter;
+/** Persist to `sessionStorage` — state survives a reload but not a new tab. */
 declare const sessionStorageAdapter: StorageAdapter;
+/** Persist into the URL fragment, so the page's link carries its state and
+ *  can be shared or bookmarked. */
 declare const urlHashAdapter: StorageAdapter;
+/** An in-memory store, discarded on reload. For tests, and for labs that
+ *  should start fresh every time. */
 declare function createMemoryAdapter(): StorageAdapter;
+/** Persists nothing and reads back nothing. */
 declare const noneAdapter: StorageAdapter;
 
+/** Every mutation a lab store supports: managing workspaces, saving and
+ *  restoring snapshots, and setting the color mode. */
 interface LabStoreActions {
     addWorkspace: (record: Omit<WorkspaceRecord, 'undoStack'>) => void;
     removeWorkspace: (id: string) => void;
@@ -77,27 +104,43 @@ interface LabStoreActions {
     listSnapshots: (workspaceId?: string) => SavedSnapshot[];
     setMode: (mode: LabMode) => void;
 }
+/** A lab's store: its state and actions, plus the hook instruments use to
+ *  register how their state is serialized. */
 type LabStore = StoreApi<LabStoreState & LabStoreActions> & {
     registerSerializers: (s: InstrumentSerializers) => void;
 };
+/** Build a lab store, hydrating from storage if anything was saved under the
+ *  same key. Writes back are debounced. */
 declare function createLabStore(options: CreateLabStoreOptions): LabStore;
 
 type LabStoreCtx = {
     store: LabStore;
 } | null;
+/** Context carrying the lab store. Prefer `useLabStore`; this is exported for
+ *  code that needs to read the context without subscribing. */
 declare const LabStoreContext: react.Context<LabStoreCtx>;
+/** Provides a lab store to its subtree. */
 declare function LabStoreProvider({ store, children, }: {
     store: LabStore;
     children: ReactNode;
 }): ReactElement;
+/** Subscribe to the whole lab store. Throws outside a `<LabStoreProvider>`. */
 declare function useLabStore(): LabStoreState & ReturnType<LabStore['getState']>;
+/** Context carrying which workspace the subtree belongs to. */
 declare const WorkspaceIdContext: react.Context<string | null>;
+/** Names the workspace its subtree belongs to, so an instrument's hooks can
+ *  find their own record in the store without being passed an id. */
 declare function WorkspaceIdProvider({ workspaceId, children, }: {
     workspaceId: string;
     children: ReactNode;
 }): ReactElement;
+/** The id of the workspace this component is inside. Throws outside a
+ *  `<WorkspaceIdProvider>`. */
 declare function useWorkspaceId(): string;
 
+/** An instrument's own state and config, plus setters. Reads the surrounding
+ *  workspace id, so an instrument never has to know which workspace it is
+ *  running in. Throws outside a lab store and workspace. */
 declare function useExperimentState<TS = unknown, TC = unknown>(): ExperimentStateHandle<TS, TC>;
 
 export { LabStoreContext as b, LabStoreProvider as c, WorkspaceIdContext as f, WorkspaceIdProvider as g, createLabStore as h, createMemoryAdapter as i, useExperimentState as j, useLabStore as k, localStorageAdapter as l, useWorkspaceId as m, noneAdapter as n, sessionStorageAdapter as s, urlHashAdapter as u };

package/dist/canvas/index.d.ts

@@ -1,15 +1,18 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { V as ViewTransform, d as Point } from '../_dts/index-C6Yze7sQ.js';
-import '../_dts/types-Si4Fw-1F.js';
+import { V as ViewTransform, d as Point } from '../_dts/index-CFlDPeZh.js';
+import '../_dts/types-x92Kfeme.js';
 
+/** One layer of a canvas stack: its id, whether it is currently shown, and how
+ *  it paints itself. */
 interface CanvasLayerDescriptor {
     id: string;
     visible: boolean;
     render: (ctx: CanvasRenderingContext2D, view: ViewTransform) => void;
 }
 
+/** Props for `<CanvasStack>`. */
 interface CanvasStackProps {
     layers: CanvasLayerDescriptor[];
     view: ViewTransform;
@@ -20,14 +23,22 @@ interface CanvasStackProps {
     onHitTest?: (worldPos: Point) => void;
     children?: ReactNode;
 }
+/** Stacks one `<canvas>` per layer and drives them from a shared view, so a
+ *  layer that changes rarely is not redrawn with one that changes every frame.
+ *  Handles sizing, device pixel ratio, and pan/zoom. */
 declare function CanvasStack({ layers, view, onViewChange, width, height, className, onHitTest, children, }: CanvasStackProps): react_jsx_runtime.JSX.Element;
 
+/** What a canvas stack publishes to its children — currently the view, so
+ *  DOM overlays can position themselves in the same coordinates. */
 interface CanvasStackContextValue {
     view: ViewTransform;
 }
+/** Context carrying the surrounding canvas stack's view. */
 declare const CanvasStackContext: react.Context<CanvasStackContextValue | null>;
 
+/** Project a world point into screen coordinates under a view. */
 declare function worldToScreen(world: Point, view: ViewTransform): Point;
+/** Unproject a screen point back to world coordinates under a view. */
 declare function screenToWorld(screen: Point, view: ViewTransform): Point;
 
 export { CanvasStack, CanvasStackContext, screenToWorld, worldToScreen };

package/dist/canvas/index.js

@@ -1,4 +1,4 @@
-export { CanvasStack, screenToWorld, worldToScreen } from '../chunk-54IQ2DX7.js';
-export { CanvasStackContext } from '../chunk-PWC7AQZM.js';
+export { CanvasStack, screenToWorld, worldToScreen } from '../chunk-574LJAV4.js';
+export { CanvasStackContext } from '../chunk-CPUJ3QXL.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map