@weasel-js/core 1.0.2 → 1.0.4

package/dist/{registry-BQL4oyTg.d.ts → registry-QRg8KiNM.d.ts}

@@ -1,18 +1,18 @@
-import { N as NodeId, R as RectPose, S as Scene } from './types-Kh_osAq9.js';
-import { M as ModifierState, A as ActionBehavior, c as ResizeAnchor, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior } from './types-Ct4n0Z38.js';
+import { N as NodeId, R as RectPose, S as Scene } from './types-vqxpCFVp.js';
+import { M as ModifierState, A as ActionBehavior, c as ResizeAnchor, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior } from './types-ByZxoD6P.js';
 import { V as View } from './view-DSQgxBJB.js';
 import { CapabilityTag } from '@weasel-js/modes';
 import * as React from 'react';
 import { MutableRefObject, ReactNode, ReactElement } from 'react';
 import { GestureSpec, IngestItem, InputEvent } from '@weasel-js/gestures';
-import { B as Bounds, P as PoseProjection } from './geometry-CnISZ11w.js';
+import { B as Bounds, P as PoseProjection } from './geometry-5X6TrAkX.js';
 import { F as FillStyle, S as Stroke } from './paint-types-CnLIzqq1.js';
-import { D as DrawCommand } from './DrawCommand-DCmiNkBj.js';
+import { D as DrawCommand } from './DrawCommand-BbPrSTra.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { P as Path } from './path-B6MMiodD.js';
 import { Op, History } from '@weasel-js/history';
-import { L as LayoutStrategy, I as InsertAdapter } from './types-Ch0Goo-j.js';
-import { D as DebugSink } from './types-Dtxe7jTS.js';
+import { L as LayoutStrategy, I as InsertAdapter } from './types-DpQ0cWYC.js';
+import { D as DebugSink } from './types-BHK2dkMu.js';
 import { Mat3 } from '@weasel-js/geom';
 
 /**
@@ -455,6 +455,8 @@ interface RuleCtx {
      *  an absent profile is behavior-preserving by construction. */
     readonly device?: DeviceProfile;
 }
+/** The live state a `RuleCtx` is assembled from — the chrome context plus
+ *  what the active mode allows. */
 interface BuildRuleCtxArgs {
     focused: boolean;
     selection: readonly NodeId[];
@@ -475,6 +477,8 @@ interface BuildRuleCtxArgs {
     /** Optional — omitted means {@link DEFAULT_DEVICE_PROFILE}. */
     device?: DeviceProfile;
 }
+/** Gather the current canvas and mode state into the context that action
+ *  eligibility and chrome-visibility rules are evaluated against. */
 declare function buildRuleCtx(args: BuildRuleCtxArgs): RuleCtx;
 
 /**
@@ -535,6 +539,7 @@ type Rule = Selector | {
 };
 /** Constant rules. Kept here so they have a single source. */
 declare const ALWAYS: Rule;
+/** A rule that never passes. `any` of nothing is false. */
 declare const NEVER: Rule;
 /**
  * Render a {@link Rule} as a short human-readable string, for inspectors and
@@ -551,6 +556,8 @@ declare const NEVER: Rule;
  * on a cyclic value and renders the `when` arm as a useless `{}`.
  */
 declare function describeRule(rule: Rule): string;
+/** Evaluate a rule against a context. Pure, and cheap enough to run per
+ *  frame for every piece of chrome. */
 declare function evaluate(rule: Rule, ctx: RuleCtx): boolean;
 
 /**
@@ -1008,6 +1015,9 @@ type Invoker = ImmediateInvoker | OngoingInvoker;
  * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`.
  */
 
+/** An interaction: a gesture spec composed with the id of the action it
+ *  invokes. Tools declare arrays of these; the dispatcher matches an incoming
+ *  input event against them and runs the winner's action. */
 interface GestureBinding {
     spec: GestureSpec;
     actionId: string;
@@ -1169,6 +1179,15 @@ type BooleanOpResult = {
     kind: 'noop';
     reason: 'no-paths' | 'too-few-for-subtract' | 'empty-result';
 };
+/**
+ * Run one Boolean operation over the selected paths and commit the result as a
+ * single undoable batch.
+ *
+ * Operands are ordered back-to-front, which is what makes `subtract` mean
+ * "everything in front removed from the backmost shape". Returns without
+ * mutating anything when the selection holds no paths, or too few for the
+ * requested operation.
+ */
 declare function applyBooleanOp(adapter: BooleansAdapter, op: BooleanOp): BooleanOpResult;
 
 /**
@@ -1291,6 +1310,9 @@ interface IngestCtx {
     /** Full action-deps bag, for consumer handlers that need more. */
     deps: ActionDeps;
 }
+/** A handler for content arriving by paste, drop or file picker. Handlers are
+ *  matched by MIME glob or predicate and run highest-priority first; the kit's
+ *  own register at a low priority so a consumer's handler wins by default. */
 interface ContentHandlerEntry {
     /** Stable identifier — used for unregistration and debugging
      *  (`'kit:image'`, `'app:csv'`). */
@@ -1357,6 +1379,9 @@ declare function PointerContextProvider({ children }: {
  *  no provider is in scope. */
 declare function usePointerContext(): PointerContextValue | null;
 
+/** Which tool is active, plus the stack of tools temporarily held active by a
+ *  hotkey (space-for-hand and the like). The dispatcher reads this to decide
+ *  whose bindings are in scope. */
 interface ActiveToolContextValue {
     active: string;
     hotkeyStack: string[];
@@ -1364,11 +1389,15 @@ interface ActiveToolContextValue {
     pushHotkey(id: string): void;
     popHotkey(): void;
 }
+/** Props for `<ActiveToolContextProvider>`. */
 interface ActiveToolContextProviderProps {
     children: ReactNode;
     initialActive?: string;
 }
+/** Provides active-tool state for a canvas. `<SceneCanvas>` mounts one. */
 declare function ActiveToolContextProvider({ children, initialActive, }: ActiveToolContextProviderProps): react_jsx_runtime.JSX.Element;
+/** The active-tool state in scope. Throws outside a provider; use
+ *  `useActiveToolContextOptional` where one is not guaranteed. */
 declare function useActiveToolContext(): ActiveToolContextValue;
 /**
  * Like `useActiveToolContext`, but returns `null` when no
@@ -1600,6 +1629,8 @@ type NodeAtPointDep = (point: {
     x: number;
     y: number;
 }, exclude?: Iterable<NodeId>) => NodeId | null;
+/** What an area-selecting action needs: a way to ask what a region covers,
+ *  and a way to read and replace the selection. */
 interface AreaSelectDep {
     /** Return ids of all scene nodes whose AABB overlaps `bounds`. */
     hitTestArea(bounds: {
@@ -1938,6 +1969,14 @@ interface ResizePolicy<TPose> {
 interface LayoutDep {
     getLayout(containerId: string): LayoutStrategy<unknown> | null;
 }
+/**
+ * The names an action may declare in `requires`, and what each resolves to.
+ *
+ * This is the whole vocabulary of things an action can reach — selection,
+ * scene, view, history, and the rest. Consumers add their own entries by
+ * augmenting the interface (`declare module '@weasel-js/core'`), which is what
+ * makes a custom dep name type-check in `requires` and in the deps bag.
+ */
 interface DepSchema {
     /** Kit selection state — ids of currently selected nodes. */
     selection: SelectionApi;
@@ -2124,13 +2163,19 @@ interface DepSchema {
  */
 type DepName = keyof DepSchema;
 
+/** Holds the live sources an action's declared dependencies resolve to.
+ *  Sources are thunks, read at invocation time, so an action never captures
+ *  stale state. */
 interface DepRegistry {
     register<K extends DepName>(name: K, source: () => DepSchema[K]): () => void;
     get<K extends DepName>(name: K): DepSchema[K] | undefined;
 }
+/** Provides the dep registry for a canvas. `<SceneCanvas>` mounts one; a
+ *  consumer registering its own dep sources must be inside it. */
 declare function DepRegistryProvider({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
+/** The dep registry in scope. Throws outside a `<DepRegistryProvider>`. */
 declare function useDepRegistry(): DepRegistry;
 /**
  * Like `useDepRegistry`, but returns `null` when no `<DepRegistryProvider>` is
@@ -2207,6 +2252,15 @@ interface ToolKeybinding {
      */
     shift?: boolean | 'optional';
 }
+/**
+ * What a tool declares.
+ *
+ * A tool is a declarative shell, not an event handler: it names the gestures
+ * it responds to and, for each, the action to invoke. The dispatcher owns the
+ * gesture, and the action owns the preview and the commit — so a tool
+ * definition is mostly `bindings`, plus presentation and any actions the tool
+ * itself introduces.
+ */
 interface ToolDef<TScratch = void> {
     id: string;
     /** Capability tags for modality eligibility. Forwarded onto `Tool.capabilities`. */
@@ -2411,7 +2465,11 @@ type AnyTool = Tool<any>;
  * binding-scope / matchBest logic on top.
  */
 
+/** Where a binding came from, which is also its priority: a held hotkey beats
+ *  the active tool, which beats bindings that are always in scope. */
 type BindingScope = 'ambient' | 'active' | 'hotkey';
+/** A binding paired with where it came from, ready to be matched against an
+ *  event. */
 interface ScopedBinding {
     binding: GestureBinding;
     scope: BindingScope;
@@ -2420,6 +2478,7 @@ interface ScopedBinding {
      *  Action with no owning tool. */
     ownerToolId: string | null;
 }
+/** The binding that won a match. */
 interface MatchResult {
     binding: GestureBinding;
     scope: BindingScope;
@@ -2479,6 +2538,11 @@ declare function specificity(spec: GestureSpec): readonly [number, number, numbe
  * the misconfiguration at dev time.
  */
 
+/** Everything the dispatcher must consult to route one input event: the
+ *  registered actions and their deps, which tool is active, which hotkeys are
+ *  held, and — optionally — the chrome state that action eligibility rules are
+ *  evaluated against. Rebuilt per event rather than held, so the dispatcher
+ *  itself stays stateless apart from in-flight gestures. */
 interface DispatcherContext {
     /** All registered actions; the dispatcher walks `.defaultBinding` for ambient bindings. */
     actions: ActionsRegistry;
@@ -2584,6 +2648,15 @@ interface ResolveAllOptions {
      */
     evaluateShadowed?: boolean;
 }
+/**
+ * Routes input events to actions.
+ *
+ * For each event it assembles the bindings in scope (hotkey, then active tool,
+ * then ambient), matches them in specificity order, filters by eligibility and
+ * each action's `enabled` gate, and invokes the first survivor. Ongoing
+ * actions — anything that runs across a drag — are kept in flight here and
+ * pumped with subsequent moves until the gesture ends.
+ */
 interface Dispatcher {
     /**
      * Route an input event through the binding pipeline. Returns `'handled'`
@@ -2720,6 +2793,8 @@ interface Dispatcher {
      */
     beginUiOngoing(actionId: string, deps: ActionDeps, params?: Record<string, unknown>): UiOngoingControl | null;
 }
+/** Build a dispatcher. `getAction` overrides how action ids are resolved;
+ *  by default the `DispatcherContext`'s registry is used. */
 declare function createDispatcher(opts?: {
     getAction?: (id: string) => Action | undefined;
 }): Dispatcher;
@@ -2873,6 +2948,7 @@ declare const ActionDisabledReason: {
     /** Sentinel: the predicate threw. Surfaced by `evaluateEnabled`'s catch. */
     readonly PredicateThrew: "predicate-threw";
 };
+/** Why an action is unavailable right now. */
 type ActionDisabledReason = (typeof ActionDisabledReason)[keyof typeof ActionDisabledReason];
 /**
  * @experimental
@@ -2882,6 +2958,14 @@ interface ActionEnabledResult {
     enabled: boolean;
     reason?: ActionDisabledReason;
 }
+/**
+ * @experimental
+ * Safely evaluate an action's `enabled` predicate. Returns `{enabled: true}`
+ * when no predicate is supplied. Catches throws and treats them as disabled
+ * with reason `'(predicate threw)'`. In dev mode, warns once per action id
+ * when a single call exceeds 4ms (single frame at 240fps — generous; real
+ * predicates should be sub-millisecond).
+ */
 declare function evaluateEnabled(action: Action, deps?: ActionDeps): ActionEnabledResult;
 /**
  * @experimental
@@ -2959,4 +3043,4 @@ declare function useActionsRegistry(): ActionsRegistry | null;
  */
 declare function useAction(action: Action): void;
 
-export { type BindingOpts as $, type Action as A, type BooleansAdapter as B, type Condition as C, type Dims as D, type Eligibility as E, type ScopedBinding as F, type GeometryProjection as G, type HotkeyTrigger as H, type InsertExtras as I, ALWAYS as J, type ActionDeps as K, type LayerHit as L, ActionDisabledReason as M, type ActionEnabledResult as N, type OverlayPosition as O, type ActionEntry as P, ActionsProvider as Q, type RenderLayer as R, type SliceDep as S, type Tool as T, type UseSelectionOptions as U, type VisibilityRules as V, ActiveToolContextProvider as W, ActiveToolContextProviderIfRoot as X, type ActiveToolContextProviderProps as Y, type ActiveToolContextValue as Z, type AreaSelectDep as _, type DeviceProfile as a, evaluateEnabled as a$, type BooleanOp as a0, type BooleanOpResult as a1, type BoundGesture as a2, type BuildRuleCtxArgs as a3, type ClaimableGesture as a4, type ClipboardDep as a5, type ClipboardIngestCtx as a6, type CustomPaintContext as a7, type DepName as a8, type DepRegistry as a9, type ResizePolicy as aA, type ResolveAllOptions as aB, type ResolveOnlyResult as aC, type ResolvedCandidate as aD, type SelectionExtendKey as aE, type SelectionMode as aF, type Selector as aG, type SnapDep as aH, type SvgUnpacker as aI, type TextEditDep as aJ, type ToolModifiers as aK, type ToolPresentation as aL, type ToolSlot as aM, type UiOngoingControl as aN, type ViewApi as aO, applyBooleanOp as aP, buildRuleCtx as aQ, clipboardCopyAction as aR, clipboardCutAction as aS, composeRectPose as aT, composeWorldPose as aU, createDispatcher as aV, decomposeRectPose as aW, describeRule as aX, drawLayers as aY, enterTextEditAction as aZ, evaluate as a_, DepRegistryProvider as aa, type DispatcherContext as ab, type DragSample as ac, type EditAnchorsDep as ad, type GestureBinding as ae, IDENTITY_POSE_COMPOSITION as af, type ImmediateInvoker as ag, type IngestCtx as ah, type IngestionDep as ai, type InsertDep as aj, type InvocationCtx as ak, type Invoker as al, type LassoSelectDep as am, type LayoutDep as an, type MatchResult as ao, NEVER as ap, type NodeAtPointDep as aq, type OngoingHandle as ar, type OngoingInvoker as as, type OngoingOverlay as at, type Point2 as au, PointerContextProvider as av, type PointerContextValue as aw, type PointerWorldPos as ax, type PoseAdapter as ay, type PoseComposition as az, type DetectedDeviceFacts as b, rebaseLocalPose as b0, registerContentHandler as b1, sliceAction as b2, specificity as b3, translateRectPose as b4, useAction as b5, useActionsRegistry as b6, useActiveToolContext as b7, useDepRegistry as b8, useDepSource as b9, useOptionalActiveToolContext as ba, useOptionalDepRegistry as bb, usePointerContext as bc, useSelection as bd, worldPoseLookup as be, type Rule as c, type RuleCtx as d, type ChromeCtx as e, type ChromeId as f, type DepSchema as g, type ActionsRegistry as h, type AffordanceHit as i, type Dispatcher as j, type ToolDef as k, type ViewportToolDef as l, type AnyTool as m, type ToolCtx as n, type ToolKeybinding as o, type ChromeState as p, type SelectionApi as q, type ContentHandlerEntry as r, type SvgIngestOptions as s, type ActionsProp as t, type Affordance as u, type AffordanceRegion as v, type AffordanceBinding as w, type CommonAffordanceScratch as x, type BindingScope as y, type Contribution as z };
+export { type BooleanOp as $, type Action as A, type BooleansAdapter as B, type Condition as C, type Dims as D, type Eligibility as E, ALWAYS as F, type GeometryProjection as G, type HotkeyTrigger as H, type InsertExtras as I, type ActionDeps as J, ActionDisabledReason as K, type LayerHit as L, type ActionEnabledResult as M, type ActionEntry as N, type OverlayPosition as O, ActionsProvider as P, ActiveToolContextProvider as Q, type RenderLayer as R, type SliceDep as S, type Tool as T, type UseSelectionOptions as U, type VisibilityRules as V, ActiveToolContextProviderIfRoot as W, type ActiveToolContextProviderProps as X, type ActiveToolContextValue as Y, type AreaSelectDep as Z, type BindingOpts as _, type DeviceProfile as a, evaluateEnabled as a$, type BooleanOpResult as a0, type BoundGesture as a1, type BuildRuleCtxArgs as a2, type ClaimableGesture as a3, type ClipboardDep as a4, type ClipboardIngestCtx as a5, type CustomPaintContext as a6, type DepName as a7, type DepRegistry as a8, DepRegistryProvider as a9, type ResolveAllOptions as aA, type ResolveOnlyResult as aB, type ResolvedCandidate as aC, type SelectionExtendKey as aD, type SelectionMode as aE, type Selector as aF, type SnapDep as aG, type SvgUnpacker as aH, type TextEditDep as aI, type ToolCtx as aJ, type ToolModifiers as aK, type ToolPresentation as aL, type ToolSlot as aM, type UiOngoingControl as aN, type ViewApi as aO, applyBooleanOp as aP, buildRuleCtx as aQ, clipboardCopyAction as aR, clipboardCutAction as aS, composeRectPose as aT, composeWorldPose as aU, createDispatcher as aV, decomposeRectPose as aW, describeRule as aX, drawLayers as aY, enterTextEditAction as aZ, evaluate as a_, type DispatcherContext as aa, type DragSample as ab, type EditAnchorsDep as ac, type GestureBinding as ad, IDENTITY_POSE_COMPOSITION as ae, type ImmediateInvoker as af, type IngestCtx as ag, type IngestionDep as ah, type InsertDep as ai, type InvocationCtx as aj, type Invoker as ak, type LassoSelectDep as al, type LayoutDep as am, type MatchResult as an, NEVER as ao, type NodeAtPointDep as ap, type OngoingHandle as aq, type OngoingInvoker as ar, type OngoingOverlay as as, type Point2 as at, PointerContextProvider as au, type PointerContextValue as av, type PointerWorldPos as aw, type PoseAdapter as ax, type PoseComposition as ay, type ResizePolicy as az, type DetectedDeviceFacts as b, rebaseLocalPose as b0, registerContentHandler as b1, sliceAction as b2, specificity as b3, translateRectPose as b4, useAction as b5, useActionsRegistry as b6, useActiveToolContext as b7, useDepRegistry as b8, useDepSource as b9, useOptionalActiveToolContext as ba, useOptionalDepRegistry as bb, usePointerContext as bc, useSelection as bd, worldPoseLookup as be, type Rule as c, type RuleCtx as d, type ChromeCtx as e, type ChromeId as f, type DepSchema as g, type ActionsRegistry as h, type AffordanceHit as i, type Dispatcher as j, type ToolDef as k, type ViewportToolDef as l, type AnyTool as m, type ToolKeybinding as n, type ChromeState as o, type SelectionApi as p, type ContentHandlerEntry as q, type SvgIngestOptions as r, type ActionsProp as s, type Affordance as t, type AffordanceRegion as u, type AffordanceBinding as v, type CommonAffordanceScratch as w, type BindingScope as x, type Contribution as y, type ScopedBinding as z };

package/dist/renderer.d.ts

@@ -1,9 +1,9 @@
-import { I as ImageMinification, G as GLImageCache } from './viewToMat3-BvaWCN99.js';
-export { V as ViewLike, v as viewToMat3 } from './viewToMat3-BvaWCN99.js';
+import { I as ImageMinification, G as GLImageCache } from './viewToMat3-CQW_YqDw.js';
+export { V as ViewLike, v as viewToMat3 } from './viewToMat3-CQW_YqDw.js';
 import { G as GradStop, S as Stroke } from './paint-types-CnLIzqq1.js';
 export { a as TextureHandle, r as registerTexture } from './paint-types-CnLIzqq1.js';
-import { M as Mat3, S as ShaderProgramHandle, D as DrawCommand } from './DrawCommand-DCmiNkBj.js';
-export { G as GroupDrawCommand, I as ImageDrawCommand, P as PathDrawCommand, a as ShaderDrawCommand, b as ShaderUniform, c as SolidPaint, T as TextDrawCommand, m as mat3, r as registerProgram } from './DrawCommand-DCmiNkBj.js';
+import { M as Mat3, S as ShaderProgramHandle, D as DrawCommand } from './DrawCommand-BbPrSTra.js';
+export { G as GroupDrawCommand, I as ImageDrawCommand, P as PathDrawCommand, a as ShaderDrawCommand, b as ShaderUniform, c as SolidPaint, T as TextDrawCommand, m as mat3, r as registerProgram } from './DrawCommand-BbPrSTra.js';
 import { P as Path } from './path-B6MMiodD.js';
 export { canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasFont, listFontOutlines, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, subscribeGlyphReady, unregisterCanvasFont, unregisterFontOutlines } from '@weasel-js/font';
 
@@ -16,6 +16,8 @@ export { canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasF
  * via the recorder Proxy without further special-casing.
  */
 type Stage = 'vertex' | 'fragment' | 'link';
+/** Thrown when a shader fails to compile or link, carrying which stage failed
+ *  and the driver's log. */
 declare class ShaderCompileError extends Error {
     readonly stage: Stage;
     readonly log: string;
@@ -157,7 +159,8 @@ declare class GLMeshCache {
  * GL texture upload + cache for MSDF font atlases (and future images).
  *
  * Textures are keyed by a string id (the font family name or image id).
- * Upload happens once; subsequent uploads for the same id are no-ops.
+ * Pixels are uploaded once per id; a later upload of the same id reuses the
+ * texture and only re-applies its wrap mode when that changed.
  * The cache is GL-context-bound; discard and create a new one on context loss.
  *
  * Atlas format: RGBA UNSIGNED_BYTE, linear filtering, no mipmaps.
@@ -172,11 +175,15 @@ type TextureWrap = 'clamp' | 'repeat';
 declare class GLTextureCache {
     private readonly gl;
     private readonly map;
+    private readonly wraps;
     constructor(gl: WebGL2RenderingContext);
     has(id: string): boolean;
-    /** Uploads once per id; `wrap` therefore applies on first upload only.
-     *  An id is either a pattern tile or a shader texture, never both. */
+    /** Uploads the pixels once per id. `wrap` is re-applied whenever it differs
+     *  from what the id was last uploaded under: the same registered image can
+     *  be a clamped shader texture in one draw and a repeating pattern tile in
+     *  the next, and first-upload-wins gave the second one the first one's mode. */
     upload(id: string, source: TexSource, wrap?: TextureWrap): string;
+    private applyWrap;
     /** Create a single-channel R8 texture from raw bytes (full upload).
      *  No-op if `id` already exists. Same LINEAR/CLAMP params as `upload`;
      *  UNPACK_ALIGNMENT dropped to 1 for non-4-aligned row widths. */
@@ -203,6 +210,8 @@ declare class GLTextureCache {
  * shader applies premultiplication before writing outColor.
  */
 
+/** Bake gradient stops into a 256-entry RGBA lookup strip, which the shader
+ *  samples instead of evaluating stops per fragment. */
 declare function buildGradientRamp(stops: GradStop[]): Uint8ClampedArray;
 declare class GradientRampCache {
     private readonly gl;
@@ -241,6 +250,9 @@ declare class GroupState {
     get alpha(): number;
     get colorMatrix(): Float32Array;
     push(frame: GroupFrame): void;
+    /** Drop every pushed frame, leaving the root. A frame that throws part-way
+     *  down the tree never pops, and the next frame would draw under leftovers. */
+    reset(): void;
     pop(): void;
 }
 
@@ -257,16 +269,22 @@ declare class GroupState {
 
 declare class SolidBatch {
     private readonly gl;
-    private readonly vao;
-    private readonly vbo;
-    private readonly ibo;
+    private readonly aPos;
+    private readonly aColor;
+    /** Cycled per flush, and created on first use so a renderer that flushes
+     *  rarely allocates as few slots as it flushes. */
+    private readonly ring;
+    private next;
+    /** The same, for flushes past a slot's capacity; these sets grow to fit. */
+    private readonly largeRing;
+    private nextLarge;
     private verts;
     private idx;
     private nVerts;
     private nIdx;
-    /** What the GPU buffers are currently sized for. */
-    private vboVerts;
-    private iboIdx;
+    /** Whether the staged run is rects alone, so its indices are the canonical
+     *  quad pattern and a slot already holding that pattern needs no upload. */
+    private pureRects;
     constructor(gl: WebGL2RenderingContext, prog: ShaderProgram);
     get length(): number;
     /** Whether staging `vertices` more would put the run past the per-flush cap. */
@@ -283,17 +301,22 @@ declare class SolidBatch {
      * index buffer is uploaded per flush rather than written once.
      */
     pushMesh(mesh: Mesh, m: Mat3, r: number, g: number, b: number, a: number): void;
-    /** Upload the staged geometry and bind the batch VAO. Returns the index
-     *  count for the caller's `drawElements`. */
+    /** Upload the staged geometry into the next set of buffers and bind its VAO.
+     *  Returns the index count for the caller's `drawElements`. */
     uploadAndBind(): number;
     reset(): void;
     dispose(): void;
     /** Grow the CPU arrays so `vertices` / `indices` more fit. */
     private reserve;
-    /** Size both GPU buffers for at least what is staged, doubling to amortize. */
-    private growGpu;
+    private nextRingSlot;
+    private nextLargeSlot;
+    private createSet;
+    private deleteSet;
 }
 
+/** How to construct a `WeaselRenderer`: the GL context or canvas to draw
+ *  into, the output size, and the quality knobs that separate screen
+ *  rendering from print. */
 interface WeaselRendererOptions {
     gl?: WebGL2RenderingContext;
     canvas?: HTMLCanvasElement;
@@ -326,6 +349,14 @@ interface WeaselRendererOptions {
      *  print has no reason to sample a field it could evaluate exactly). */
     textOutlineMinScreenSize?: number;
 }
+/**
+ * The WebGL2 renderer: takes a list of draw commands and paints them.
+ *
+ * It knows nothing about the scene — commands are the whole interface, which
+ * is what lets layers, HUD widgets and overlays all draw through the same
+ * pipeline. GPU resources (meshes, textures, gradient ramps) are cached across
+ * frames and keyed by identity, so re-issuing the same command is cheap.
+ */
 declare class WeaselRenderer {
     private readonly gl;
     private pathFill;
@@ -433,12 +464,18 @@ declare class WeaselRenderer {
     /** @internal */ _dpr(): number;
 }
 
+/** Options for `tessellate`. A smaller tolerance means more triangles and
+ *  smoother curves; it is in path-local units, so callers rendering at a
+ *  larger scale should tighten it. */
 interface TessellateOptions {
     /** Flatness tolerance for bezier subdivision in path-local units. */
     flattenTolerance?: number;
 }
+/** Turn a path into a triangle mesh the renderer can draw: curves flattened to
+ *  line segments, then the resulting polygon triangulated. */
 declare function tessellate(path: Path, opts?: TessellateOptions): Mesh;
 
+/** Options for stroke tessellation. */
 interface StrokeOptions {
     flattenTolerance?: number;
 }

package/dist/renderer.js

@@ -1,12 +1,12 @@
-export { IDENTITY_COLOR_MATRIX, OUTLINE_MIN_SCREEN_PX, ShaderCompileError, WeaselRenderer, buildGradientRamp, canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasFont, listFontOutlines, mat3, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, registerProgram, subscribeGlyphReady, tessellate, tessellateStroke, unregisterCanvasFont, unregisterFontOutlines, viewToMat3 } from './chunk-PI56ORHE.js';
-import './chunk-W2WB4352.js';
-import './chunk-UB6A6L77.js';
-import './chunk-Z3KNFTTS.js';
-import './chunk-6SHZHXXR.js';
-import './chunk-775XXAHR.js';
+export { IDENTITY_COLOR_MATRIX, OUTLINE_MIN_SCREEN_PX, ShaderCompileError, WeaselRenderer, buildGradientRamp, canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasFont, listFontOutlines, mat3, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, registerProgram, subscribeGlyphReady, tessellate, tessellateStroke, unregisterCanvasFont, unregisterFontOutlines, viewToMat3 } from './chunk-AYGSXNY3.js';
+import './chunk-J3YC3GVF.js';
+import './chunk-CSMF654J.js';
+import './chunk-J7LUY47N.js';
+import './chunk-4Z6J4IVH.js';
+import './chunk-JOSUVS6C.js';
 import './chunk-UGFFCMQP.js';
 import './chunk-BHVYVFGV.js';
 import './chunk-GVCNT7UH.js';
-export { registerTexture } from './chunk-IO5Z75X4.js';
+export { registerTexture } from './chunk-HGF5X6MZ.js';
 //# sourceMappingURL=renderer.js.map
 //# sourceMappingURL=renderer.js.map

package/dist/resize.d.ts

@@ -1,12 +1,15 @@
-export { C as CORNER_ANCHORS, a as CornerAnchor, b as CornerHandle, U as UseResizeOptions, c as cornerPoint, d as cornerResizeHandles, f as fixedCornerOf, h as hitCornerHandle, p as pointSnapToGrid } from './pointSnapToGrid-Bj4r_lEQ.js';
-export { P as PoseProjection, R as RECT_POSE_DESCRIPTOR, a as ROTATED_POSE_DESCRIPTOR } from './geometry-CnISZ11w.js';
-import { R as ResizePose, B as BoundsConstraint, M as ModifierState } from './types-Ct4n0Z38.js';
+export { C as CORNER_ANCHORS, a as CornerAnchor, b as CornerHandle, U as UseResizeOptions, c as cornerPoint, d as cornerResizeHandles, f as fixedCornerOf, h as hitCornerHandle, p as pointSnapToGrid } from './pointSnapToGrid-C3wowsQy.js';
+export { P as PoseProjection, R as RECT_POSE_DESCRIPTOR, a as ROTATED_POSE_DESCRIPTOR } from './geometry-5X6TrAkX.js';
+import { R as ResizePose, B as BoundsConstraint, M as ModifierState } from './types-ByZxoD6P.js';
 import { G as Guide } from './types-D2tTKEU0.js';
 import { V as View } from './view-DSQgxBJB.js';
-import './types-Dtxe7jTS.js';
+import './types-BHK2dkMu.js';
 import '@weasel-js/history';
-import './types-Ch0Goo-j.js';
+import './types-DpQ0cWYC.js';
 
+/** Resize constraint that stops a node shrinking past a minimum. The anchored
+ *  edge stays put, so clamping pushes the dragged edge back rather than moving
+ *  the node. */
 declare function clampMinSize<TPose extends ResizePose>(args: {
     minWidth: number;
     minHeight: number;
@@ -39,6 +42,10 @@ declare function lockAspectWithModifier<TPose extends ResizePose>(opts?: {
 }): BoundsConstraint<TPose>;
 
 type ModKey$1 = keyof ModifierState;
+/** Resize constraint that snaps the moving edges to a grid, leaving the
+ *  anchored ones where they are. By default a node already smaller than one
+ *  grid cell on an axis is left unsnapped on that axis, so it stays resizable
+ *  at sub-grid sizes. */
 declare function snapToGrid<TPose extends ResizePose>(args: {
     spacing: number;
     bypassKey?: ModKey$1;

package/dist/resize.js

@@ -1,4 +1,4 @@
-export { CORNER_ANCHORS, DEFAULT_RESIZE_BEHAVIORS, clampMinSize, cornerPoint, cornerResizeHandles, fixedCornerOf, hitCornerHandle, lockAspectWithModifier, pointSnapToGrid, snapToGrid, snapToGuides } from './chunk-Z3KNFTTS.js';
-export { RECT_POSE_DESCRIPTOR, ROTATED_POSE_DESCRIPTOR } from './chunk-6SHZHXXR.js';
+export { CORNER_ANCHORS, DEFAULT_RESIZE_BEHAVIORS, clampMinSize, cornerPoint, cornerResizeHandles, fixedCornerOf, hitCornerHandle, lockAspectWithModifier, pointSnapToGrid, snapToGrid, snapToGuides } from './chunk-J7LUY47N.js';
+export { RECT_POSE_DESCRIPTOR, ROTATED_POSE_DESCRIPTOR } from './chunk-4Z6J4IVH.js';
 //# sourceMappingURL=resize.js.map
 //# sourceMappingURL=resize.js.map

package/dist/routing.d.ts

@@ -1,19 +1,19 @@
 import { ParsedModifiers, GestureName, GestureSpec } from '@weasel-js/gestures';
 export { ChannelRef, DescribeRouteOptions, GESTURE_DESCRIPTORS, GestureArgSpec, GestureDescriptor, GestureName, ModRequirement, ModifierKey, ParsedModifiers, ParsedRoute, PhaseAtom, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, RouteDescriptionPart, RouteFieldName, RouteTermLabel, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute } from '@weasel-js/gestures';
-import { T as Tool } from './registry-BQL4oyTg.js';
-import './types-Kh_osAq9.js';
+import { T as Tool } from './registry-QRg8KiNM.js';
+import './types-vqxpCFVp.js';
 import '@weasel-js/history';
 import './path-B6MMiodD.js';
-import './types-Ct4n0Z38.js';
-import './types-Ch0Goo-j.js';
+import './types-ByZxoD6P.js';
+import './types-DpQ0cWYC.js';
 import './view-DSQgxBJB.js';
 import '@weasel-js/modes';
 import 'react';
-import './geometry-CnISZ11w.js';
+import './geometry-5X6TrAkX.js';
 import './paint-types-CnLIzqq1.js';
-import './DrawCommand-DCmiNkBj.js';
+import './DrawCommand-BbPrSTra.js';
 import 'react/jsx-runtime';
-import './types-Dtxe7jTS.js';
+import './types-BHK2dkMu.js';
 import '@weasel-js/geom';
 
 /**

package/dist/routing.js

@@ -1,3 +1,3 @@
-export { GESTURE_DESCRIPTORS, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, buildRouteRegistry, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, findConflicts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute } from './chunk-W2WB4352.js';
+export { GESTURE_DESCRIPTORS, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, buildRouteRegistry, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, findConflicts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute } from './chunk-J3YC3GVF.js';
 //# sourceMappingURL=routing.js.map
 //# sourceMappingURL=routing.js.map

package/dist/{types-Dtxe7jTS.d.ts → types-BHK2dkMu.d.ts}

@@ -20,7 +20,10 @@ interface DebugConfig {
      *  {@link DEFAULT_DEBUG_STROKES}. */
     strokes?: Partial<DebugStrokes>;
 }
+/** The name of one debug-overlay feature — the keys of {@link DebugConfig}
+ *  that toggle a visualization. */
 type DebugFeature = 'hitboxes' | 'handles' | 'bounds' | 'origins' | 'snap' | 'layers' | 'ids' | 'fps';
+/** Colors the debug overlay draws with, one entry per feature. */
 interface DebugTheme {
     hitboxFill: string;
     hitboxStroke: string;
@@ -52,7 +55,10 @@ interface DebugStrokes {
     /** Rejected snap candidates only; accepted ones paint as a filled dot. */
     snap: DebugStroke;
 }
+/** Which kind of handle a recorded handle marker represents. */
 type HandleKind = 'corner' | 'rotation' | 'anchor';
+/** The geometry a hit region actually tests against, as reported to the debug
+ *  sink so the overlay can draw the real shape rather than its bounding box. */
 type HitShape = {
     kind: 'rect';
     x: number;
@@ -69,11 +75,13 @@ type HitShape = {
     kind: 'path';
     d: Path2D;
 };
+/** A hit region tested during the current frame. */
 interface RecordedHitbox {
     id: string;
     kind: 'body' | 'handle' | 'rotation' | 'anchor';
     shape: HitShape;
 }
+/** A handle drawn during the current frame, and where. */
 interface RecordedHandle {
     id: string;
     position: {
@@ -82,6 +90,7 @@ interface RecordedHandle {
     };
     kind: HandleKind;
 }
+/** A node's bounds as computed during the current frame. */
 interface RecordedBounds {
     id: string;
     bounds: {
@@ -91,6 +100,7 @@ interface RecordedBounds {
         height: number;
     };
 }
+/** A node's transform origin as used during the current frame. */
 interface RecordedOrigin {
     id: string;
     point: {
@@ -98,6 +108,9 @@ interface RecordedOrigin {
         y: number;
     };
 }
+/** A snap candidate considered during the current gesture, and whether it
+ *  won. Unlike the other records these survive across frames, until the
+ *  gesture ends. */
 interface RecordedSnap {
     point: {
         x: number;
@@ -105,12 +118,14 @@ interface RecordedSnap {
     };
     accepted: boolean;
 }
+/** A render layer that drew during the current frame. */
 interface RecordedLayer {
     id: string;
     label: string;
     space: 'world' | 'screen';
     index: number;
 }
+/** Everything the sink collected, ready for the overlay to draw. */
 interface DebugSnapshot {
     hitboxes: RecordedHitbox[];
     handles: RecordedHandle[];
@@ -119,6 +134,14 @@ interface DebugSnapshot {
     snap: RecordedSnap[];
     layers: RecordedLayer[];
 }
+/**
+ * Where the kit reports what it is doing so the debug overlay can draw it.
+ *
+ * Recording is push-based and cheap: hit-testers, handle painters and snap
+ * strategies call these as they run, whether or not any overlay is watching.
+ * Nothing here affects behavior — a sink that discards everything is a valid
+ * sink.
+ */
 interface DebugSink {
     recordHitbox(id: string, kind: 'body' | 'handle' | 'rotation' | 'anchor', shape: HitShape): void;
     recordHandle(id: string, position: {

package/dist/{types-Ct4n0Z38.d.ts → types-ByZxoD6P.d.ts}

@@ -1,5 +1,5 @@
 import { Op } from '@weasel-js/history';
-import { S as SnapTarget, M as MoveAdapter, I as InsertAdapter } from './types-Ch0Goo-j.js';
+import { S as SnapTarget, M as MoveAdapter, I as InsertAdapter } from './types-DpQ0cWYC.js';
 
 /**
  * Snapshot of modifier-key state at gesture dispatch.