@weasel-js/core 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -2,40 +2,40 @@ import * as React$1 from 'react';
 import React__default, { RefObject, ReactNode, Ref, MouseEvent as MouseEvent$1, MutableRefObject } from 'react';
 import { a as ViewTransform, V as View, Z as ZoomBound, b as ZoomFactor } from './view-DSQgxBJB.js';
 export { s as screenToWorld, v as viewToTransform, w as worldToScreen } from './view-DSQgxBJB.js';
-import { a as UnitValue, b as UnitSystem, U as UseMoveOptions, O as OriginProjection } from './grid-CBiLBnyc.js';
-export { I as IMPERIAL_INCHES, M as METRIC_MM, P as PIXELS, R as RECT_ORIGIN_PROJECTION, c as Unit, f as formatUnit, g as gridSnapStrategy, p as pointToGridCell, r as resolveUnit } from './grid-CBiLBnyc.js';
-import { R as RenderLayer, D as Dims, a as DeviceProfile, b as DetectedDeviceFacts, C as Condition, c as Rule, d as RuleCtx, V as VisibilityRules, e as ChromeCtx, f as ChromeId, A as Action, g as DepSchema, S as SliceDep, h as ActionsRegistry, T as Tool, i as AffordanceHit, j as Dispatcher, k as ToolDef, l as ViewportToolDef, m as AnyTool, O as OverlayPosition, n as ToolCtx, o as ToolKeybinding, H as HotkeyTrigger, L as LayerHit, p as ChromeState, q as SelectionApi, I as InsertExtras, G as GeometryProjection, r as ContentHandlerEntry, s as SvgIngestOptions, U as UseSelectionOptions, t as ActionsProp, u as Affordance, v as AffordanceRegion, w as AffordanceBinding, x as CommonAffordanceScratch, B as BooleansAdapter, E as Eligibility, y as BindingScope, z as Contribution, F as ScopedBinding } from './registry-BQL4oyTg.js';
-export { J as ALWAYS, K as ActionDeps, M as ActionDisabledReason, N as ActionEnabledResult, P as ActionEntry, Q as ActionsProvider, W as ActiveToolContextProvider, X as ActiveToolContextProviderIfRoot, Y as ActiveToolContextProviderProps, Z as ActiveToolContextValue, _ as AreaSelectDep, $ as BindingOpts, a0 as BooleanOp, a1 as BooleanOpResult, a2 as BoundGesture, a3 as BuildRuleCtxArgs, a4 as ClaimableGesture, a5 as ClipboardDep, a6 as ClipboardIngestCtx, a7 as CustomPaintContext, a8 as DepName, a9 as DepRegistry, aa as DepRegistryProvider, ab as DispatcherContext, ac as DragSample, ad as EditAnchorsDep, ae as GestureBinding, af as IDENTITY_POSE_COMPOSITION, ag as ImmediateInvoker, ah as IngestCtx, ai as IngestionDep, aj as InsertDep, ak as InvocationCtx, al as Invoker, am as LassoSelectDep, an as LayoutDep, ao as MatchResult, ap as NEVER, aq as NodeAtPointDep, ar as OngoingHandle, as as OngoingInvoker, at as OngoingOverlay, au as Point2, av as PointerContextProvider, aw as PointerContextValue, ax as PointerWorldPos, ay as PoseAdapter, az as PoseComposition, aA as ResizePolicy, aB as ResolveAllOptions, aC as ResolveOnlyResult, aD as ResolvedCandidate, aE as SelectionExtendKey, aF as SelectionMode, aG as Selector, aH as SnapDep, aI as SvgUnpacker, aJ as TextEditDep, aK as ToolModifiers, aL as ToolPresentation, aM as ToolSlot, aN as UiOngoingControl, aO as ViewApi, aP as applyBooleanOp, aQ as buildRuleCtx, aR as clipboardCopyAction, aS as clipboardCutAction, aT as composeRectPose, aU as composeWorldPose, aV as createDispatcher, aW as decomposeRectPose, aX as describeRule, aY as drawLayers, aZ as enterTextEditAction, a_ as evaluate, a$ as evaluateEnabled, b0 as rebaseLocalPose, b1 as registerContentHandler, b2 as sliceAction, b3 as specificity, b4 as translateRectPose, b5 as useAction, b6 as useActionsRegistry, b7 as useActiveToolContext, b8 as useDepRegistry, b9 as useDepSource, ba as useOptionalActiveToolContext, bb as useOptionalDepRegistry, bc as usePointerContext, bd as useSelection, be as worldPoseLookup } from './registry-BQL4oyTg.js';
+import { a as UnitValue, b as UnitSystem, U as UseMoveOptions, O as OriginProjection } from './grid-sfilv5HP.js';
+export { I as IMPERIAL_INCHES, M as METRIC_MM, P as PIXELS, R as RECT_ORIGIN_PROJECTION, c as Unit, f as formatUnit, g as gridSnapStrategy, p as pointToGridCell, r as resolveUnit } from './grid-sfilv5HP.js';
+import { R as RenderLayer, D as Dims, a as DeviceProfile, b as DetectedDeviceFacts, C as Condition, c as Rule, d as RuleCtx, V as VisibilityRules, e as ChromeCtx, f as ChromeId, A as Action, g as DepSchema, S as SliceDep, h as ActionsRegistry, T as Tool, i as AffordanceHit, j as Dispatcher, k as ToolDef, l as ViewportToolDef, m as AnyTool, O as OverlayPosition, n as ToolCtx, o as ToolKeybinding, H as HotkeyTrigger, L as LayerHit, p as ChromeState, q as SelectionApi, I as InsertExtras, G as GeometryProjection, r as ContentHandlerEntry, s as SvgIngestOptions, U as UseSelectionOptions, t as ActionsProp, u as Affordance, v as AffordanceRegion, w as AffordanceBinding, x as CommonAffordanceScratch, B as BooleansAdapter, E as Eligibility, y as BindingScope, z as Contribution, F as ScopedBinding } from './registry-CxnkXbG8.js';
+export { J as ALWAYS, K as ActionDeps, M as ActionDisabledReason, N as ActionEnabledResult, P as ActionEntry, Q as ActionsProvider, W as ActiveToolContextProvider, X as ActiveToolContextProviderIfRoot, Y as ActiveToolContextProviderProps, Z as ActiveToolContextValue, _ as AreaSelectDep, $ as BindingOpts, a0 as BooleanOp, a1 as BooleanOpResult, a2 as BoundGesture, a3 as BuildRuleCtxArgs, a4 as ClaimableGesture, a5 as ClipboardDep, a6 as ClipboardIngestCtx, a7 as CustomPaintContext, a8 as DepName, a9 as DepRegistry, aa as DepRegistryProvider, ab as DispatcherContext, ac as DragSample, ad as EditAnchorsDep, ae as GestureBinding, af as IDENTITY_POSE_COMPOSITION, ag as ImmediateInvoker, ah as IngestCtx, ai as IngestionDep, aj as InsertDep, ak as InvocationCtx, al as Invoker, am as LassoSelectDep, an as LayoutDep, ao as MatchResult, ap as NEVER, aq as NodeAtPointDep, ar as OngoingHandle, as as OngoingInvoker, at as OngoingOverlay, au as Point2, av as PointerContextProvider, aw as PointerContextValue, ax as PointerWorldPos, ay as PoseAdapter, az as PoseComposition, aA as ResizePolicy, aB as ResolveAllOptions, aC as ResolveOnlyResult, aD as ResolvedCandidate, aE as SelectionExtendKey, aF as SelectionMode, aG as Selector, aH as SnapDep, aI as SvgUnpacker, aJ as TextEditDep, aK as ToolModifiers, aL as ToolPresentation, aM as ToolSlot, aN as UiOngoingControl, aO as ViewApi, aP as applyBooleanOp, aQ as buildRuleCtx, aR as clipboardCopyAction, aS as clipboardCutAction, aT as composeRectPose, aU as composeWorldPose, aV as createDispatcher, aW as decomposeRectPose, aX as describeRule, aY as drawLayers, aZ as enterTextEditAction, a_ as evaluate, a$ as evaluateEnabled, b0 as rebaseLocalPose, b1 as registerContentHandler, b2 as sliceAction, b3 as specificity, b4 as translateRectPose, b5 as useAction, b6 as useActionsRegistry, b7 as useActiveToolContext, b8 as useDepRegistry, b9 as useDepSource, ba as useOptionalActiveToolContext, bb as useOptionalDepRegistry, bc as usePointerContext, bd as useSelection, be as worldPoseLookup } from './registry-CxnkXbG8.js';
 import { S as Stroke, F as FillStyle, a as TextureHandle, T as TilePatternSpec, b as GradientKind, G as GradStop, c as GradientFill } from './paint-types-CnLIzqq1.js';
 export { d as GradientUnits, R as Region, e as StrokeAlign, f as alignedStrokeRect } from './paint-types-CnLIzqq1.js';
-import { B as Bounds, P as PoseProjection, F as FitViewToBoundsOptions, V as ViewportDims } from './geometry-CnISZ11w.js';
-export { R as RECT_POSE_DESCRIPTOR, a as ROTATED_POSE_DESCRIPTOR, f as fitViewToBounds } from './geometry-CnISZ11w.js';
-import { N as NodeId, S as Scene, a as Node$1, b as SerializedScene, R as RectPose, U as UseSceneOptions, c as SceneRegistry, d as RegisteredOp } from './types-Kh_osAq9.js';
-export { A as AddLayerSpec, e as AddNodeSpec, C as ContainerNode, L as LayerRecord, f as LeafNode, g as SerializedNode, h as SystemLayerRecord, i as SystemLayerSpec, j as UserLayerRecord, k as asNodeId } from './types-Kh_osAq9.js';
-import { M as ModifierState, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior, L as LassoSelectBehavior, a as RotatedPose, e as RotateBehavior, S as SnapStrategy, c as ResizeAnchor, b as MoveBehavior, I as InsertBehavior } from './types-Ct4n0Z38.js';
-export { A as ActionBehavior, f as AreaSelectOverlay, g as BehaviorMoveResult, h as BehaviorResult, C as CloneBehavior, i as CloneLayer, j as ClonePose, G as GestureContext, k as GroupTransform, l as InsertMoveResult, m as InsertOverlay, n as InsertPoint, o as InsertProposed, p as LassoSelectMoveResult, q as LassoSelectOverlay, r as LassoSelectPose, s as LassoSelectProposed, t as PointSnapContext, d as PointSnapFrame, u as PointSnapResult, v as PointerState, w as ResizeMoveResult, x as ResizeOverlay, y as ResizeProposed, z as RotateMoveResult, D as RotateOverlay, E as RotateProposed } from './types-Ct4n0Z38.js';
-import { U as UseResizeOptions } from './pointSnapToGrid-Bj4r_lEQ.js';
-export { C as CORNER_ANCHORS, a as CornerAnchor, e as CornerEdge, b as CornerHandle, c as cornerPoint, d as cornerResizeHandles, h as hitCornerHandle, p as pointSnapToGrid } from './pointSnapToGrid-Bj4r_lEQ.js';
+import { B as Bounds, P as PoseProjection, F as FitViewToBoundsOptions, V as ViewportDims } from './geometry-5X6TrAkX.js';
+export { R as RECT_POSE_DESCRIPTOR, a as ROTATED_POSE_DESCRIPTOR, f as fitViewToBounds } from './geometry-5X6TrAkX.js';
+import { N as NodeId, S as Scene, a as Node$1, b as SerializedScene, R as RectPose, U as UseSceneOptions, c as SceneRegistry, d as RegisteredOp } from './types-vqxpCFVp.js';
+export { A as AddLayerSpec, e as AddNodeSpec, C as ContainerNode, L as LayerRecord, f as LeafNode, g as SerializedNode, h as SystemLayerRecord, i as SystemLayerSpec, j as UserLayerRecord, k as asNodeId } from './types-vqxpCFVp.js';
+import { M as ModifierState, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior, L as LassoSelectBehavior, a as RotatedPose, e as RotateBehavior, S as SnapStrategy, c as ResizeAnchor, b as MoveBehavior, I as InsertBehavior } from './types-ByZxoD6P.js';
+export { A as ActionBehavior, f as AreaSelectOverlay, g as BehaviorMoveResult, h as BehaviorResult, C as CloneBehavior, i as CloneLayer, j as ClonePose, G as GestureContext, k as GroupTransform, l as InsertMoveResult, m as InsertOverlay, n as InsertPoint, o as InsertProposed, p as LassoSelectMoveResult, q as LassoSelectOverlay, r as LassoSelectPose, s as LassoSelectProposed, t as PointSnapContext, d as PointSnapFrame, u as PointSnapResult, v as PointerState, w as ResizeMoveResult, x as ResizeOverlay, y as ResizeProposed, z as RotateMoveResult, D as RotateOverlay, E as RotateProposed } from './types-ByZxoD6P.js';
+import { U as UseResizeOptions } from './pointSnapToGrid-C3wowsQy.js';
+export { C as CORNER_ANCHORS, a as CornerAnchor, e as CornerEdge, b as CornerHandle, c as cornerPoint, d as cornerResizeHandles, h as hitCornerHandle, p as pointSnapToGrid } from './pointSnapToGrid-C3wowsQy.js';
 import { BodyClassification, IngestItem } from '@weasel-js/gestures';
 export { ClickSpec, DragSpec, DropSpec, GestureSpec, IngestItem, InputEvent, KeyHeldSpec, KeySpec, ModSpec, MultiTouchSpec, PasteSpec, TargetSpec, WheelSpec } from '@weasel-js/gestures';
-import { M as MoveAdapter, A as AreaSelectAdapter, R as RotateAdapter, a as LassoHitMode, b as LassoSelectAdapter, c as ResizeAdapter, d as SceneAdapter, L as LayoutStrategy, e as LayerEnumerableAdapter, I as InsertAdapter, C as ClipboardSnapshot, O as OrderedAdapter, f as LayoutSnap } from './types-Ch0Goo-j.js';
-export { g as ContainerBounds, D as DropTarget, h as LayoutChild, i as LayoutContainer, j as LayoutDragged, S as SnapTarget } from './types-Ch0Goo-j.js';
-import { D as DebugSink, a as DebugConfig, b as DebugSnapshot, c as DebugStrokes, d as DebugTheme } from './types-Dtxe7jTS.js';
-export { e as DebugFeature, f as DebugStroke, H as HandleKind, g as HitShape, R as RecordedBounds, h as RecordedHandle, i as RecordedHitbox, j as RecordedLayer, k as RecordedOrigin, l as RecordedSnap } from './types-Dtxe7jTS.js';
+import { M as MoveAdapter, A as AreaSelectAdapter, R as RotateAdapter, a as LassoHitMode, b as LassoSelectAdapter, c as ResizeAdapter, d as SceneAdapter, L as LayoutStrategy, e as LayerEnumerableAdapter, I as InsertAdapter, C as ClipboardSnapshot, O as OrderedAdapter, f as LayoutSnap } from './types-DpQ0cWYC.js';
+export { g as ContainerBounds, D as DropTarget, h as LayoutChild, i as LayoutContainer, j as LayoutDragged, S as SnapTarget } from './types-DpQ0cWYC.js';
+import { D as DebugSink, a as DebugConfig, b as DebugSnapshot, c as DebugStrokes, d as DebugTheme } from './types-BHK2dkMu.js';
+export { e as DebugFeature, f as DebugStroke, H as HandleKind, g as HitShape, R as RecordedBounds, h as RecordedHandle, i as RecordedHitbox, j as RecordedLayer, k as RecordedOrigin, l as RecordedSnap } from './types-BHK2dkMu.js';
 import { a as PolygonPath, P as Path, b as PathFillRule, R as RectPath } from './path-B6MMiodD.js';
 export { c as PATH_C, d as PATH_CMD_LENGTHS, e as PATH_L, f as PATH_M, g as PATH_Q, h as PATH_Z } from './path-B6MMiodD.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { D as DrawCommand, S as ShaderProgramHandle, P as PathDrawCommand, d as StyledRun, R as ResolvedTextStyle, e as TextStyle, f as TextVerticalAlign } from './DrawCommand-DCmiNkBj.js';
-export { g as DEFAULT_TEXT_STYLE, G as GroupDrawCommand, I as ImageDrawCommand, M as Mat3, h as ResolvedRun, a as ShaderDrawCommand, b as ShaderUniform, T as TextDrawCommand, i as fontString, j as markdownToRuns, k as resolveRuns, l as resolveTextStyle, n as runsToMarkdown, o as runsToPlainText, t as toRuns, v as verticalAlignOffset } from './DrawCommand-DCmiNkBj.js';
+import { D as DrawCommand, S as ShaderProgramHandle, P as PathDrawCommand, d as StyledRun, R as ResolvedTextStyle, e as TextStyle, f as TextVerticalAlign } from './DrawCommand-BbPrSTra.js';
+export { g as DEFAULT_TEXT_STYLE, G as GroupDrawCommand, I as ImageDrawCommand, M as Mat3, h as ResolvedRun, a as ShaderDrawCommand, b as ShaderUniform, T as TextDrawCommand, i as fontString, j as markdownToRuns, k as resolveRuns, l as resolveTextStyle, n as runsToMarkdown, o as runsToPlainText, t as toRuns, v as verticalAlignOffset } from './DrawCommand-BbPrSTra.js';
 import { Op, CreateHistoryOptions, History } from '@weasel-js/history';
 export * from '@weasel-js/history';
 export { Op } from '@weasel-js/history';
 import { Mat3 } from '@weasel-js/geom';
 import { G as Guide } from './types-D2tTKEU0.js';
-export { U as UseInsertOptions } from './options-DoOvx50U.js';
+export { U as UseInsertOptions } from './options-CbsIgQci.js';
 export { UseClipboardOpsOptions, UseClipboardOpsReturn, WEASEL_CLIPBOARD_MIME, WEASEL_CLIPBOARD_MIME_WEB, buildWeaselClipboardText, embedWeaselMetadataInSvg, extractWeaselClipboardFromSvg, parseWeaselClipboardText, sniffWeaselClipboardText, useClipboardOps } from './clipboard.js';
 export { cloneByAltDrag } from './clone.js';
-export { I as ImageMinification, v as viewToMat3 } from './viewToMat3-BvaWCN99.js';
+export { I as ImageMinification, v as viewToMat3 } from './viewToMat3-CQW_YqDw.js';
 export { FontVariant, LocalFontOutlinesResult, OutlineFontStyle, OutlineSource, OutlineStatus, OutlineVariant, canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasFont, listFontOutlines, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, subscribeGlyphReady, unregisterCanvasFont, unregisterFontOutlines } from '@weasel-js/font';
 import { CapabilityTag } from '@weasel-js/modes';
 
@@ -272,6 +272,10 @@ interface ViewportLayer<TData> extends RenderLayer<TData> {
         y: number;
     } | null;
 }
+/** Build a layer that renders other layers through a second view, inside a
+ *  sub-region of the canvas — a minimap, an inset, a magnifier. Its
+ *  `reproject` maps screen points back through the inner view so the region
+ *  can be interacted with. */
 declare function createViewportLayer<TData>(opts: CreateViewportLayerOpts<TData>): ViewportLayer<TData>;
 /**
  * @experimental
@@ -291,10 +295,15 @@ declare function viewportsAt<TData>(layers: readonly ViewportLayer<TData>[], out
     };
 } | null;
 
+/** One value for both axes, or a separate value per axis. */
 type ScalarOrXY = number | {
     x: number;
     y: number;
 };
+/** How a parallax plane tracks the camera: `pan` is the fraction of the
+ *  camera's translation it follows (1 = locked to the scene, 0 = fixed to the
+ *  screen), `zoom` the same for scale, and `anchor` the world point both are
+ *  measured from. */
 interface ParallaxOpts {
     pan: ScalarOrXY;
     zoom?: ScalarOrXY;
@@ -316,6 +325,7 @@ interface ParallaxOpts {
  */
 declare function deriveParallaxView(outer: View, opts: ParallaxOpts): View;
 
+/** Options for `createParallaxLayer`. */
 interface CreateParallaxLayerOpts<TData> extends ParallaxOpts {
     id: string;
     label: string;
@@ -364,6 +374,8 @@ interface SimulationForce<TNode extends SimulationNode = SimulationNode> {
     (alpha: number): void;
     initialize?(nodes: TNode[], random?: () => number): void;
 }
+/** Options for `useSimulation`: the nodes to move, the forces acting on them,
+ *  and the cooling schedule that decides when the simulation settles. */
 interface UseSimulationOptions<TNode extends SimulationNode> {
     /** Mutable array of nodes. Kit + forces mutate vx/vy/x/y in place. */
     nodes: TNode[];
@@ -387,6 +399,16 @@ interface UseSimulationOptions<TNode extends SimulationNode> {
     requestFrame?: (cb: (t: number) => void) => number;
     cancelFrame?: (handle: number) => void;
 }
+/**
+ * A running force simulation over a set of nodes.
+ *
+ * Each tick applies every force and then integrates velocities, scaled by
+ * `alpha` — a temperature that decays toward `alphaTarget` so the layout
+ * settles instead of jittering forever. Raise `alphaTarget` to reheat it,
+ * which is what a drag does.
+ *
+ * Nodes are mutated in place; the simulation holds the array, not a copy.
+ */
 interface Simulation<TNode extends SimulationNode> {
     readonly nodes: TNode[];
     setNodes(nodes: TNode[]): this;
@@ -414,7 +436,10 @@ interface Simulation<TNode extends SimulationNode> {
 }
 /** Default alpha decay: such that alpha drops from 1 to alphaMin (0.001) in 300 ticks. */
 declare const DEFAULT_ALPHA_DECAY: number;
+/** Alpha below which a cooling simulation is considered settled. */
 declare const DEFAULT_ALPHA_MIN = 0.001;
+/** Fraction of velocity shed each tick — friction. Higher settles sooner and
+ *  overshoots less. */
 declare const DEFAULT_VELOCITY_DECAY = 0.4;
 
 /**
@@ -555,6 +580,7 @@ interface PointerStylusState extends StylusData {
      *  glass without contact. */
     hovering: boolean;
 }
+/** Options for `usePointerStylus`. */
 interface UsePointerStylusOptions {
     /** Throttle re-renders to ≈this many state updates per second. The latest
      *  sample is always kept; intermediates are dropped. Default 60. Set to
@@ -721,12 +747,15 @@ interface ThresholdDragHandle {
 /** Begin a threshold-gated drag from a React PointerDown event; returns a handle exposing live state. */
 declare function startThresholdDrag(e: React.PointerEvent, opts: ThresholdDragOptions): ThresholdDragHandle;
 
+/** The world rect a view is not allowed to show outside of. */
 interface ClampBounds {
     x: number;
     y: number;
     width: number;
     height: number;
 }
+/** Canvas dimensions in CSS pixels — needed to know how much world a view
+ *  actually shows. */
 interface CanvasSize {
     width: number;
     height: number;
@@ -822,6 +851,7 @@ declare const ROTATION_HANDLE_BASE_PX = 24;
  * force-touch-chrome demos possible without stubbing `matchMedia`.
  */
 declare function useDeviceProfile(overrides?: Partial<DeviceProfile>): DeviceProfile;
+/** Props for `<DeviceProfileProvider>`. */
 interface DeviceProfileProviderProps {
     /** Partial override folded over detected facts. */
     value?: Partial<DeviceProfile>;
@@ -1169,6 +1199,7 @@ declare function resolveVisibility(consumer: VisibilityRules | undefined, ctx: C
  * fixture, or `<SceneCanvas>`.
  */
 
+/** The pieces of live canvas state a `ChromeCtx` is assembled from. */
 interface BuildChromeCtxArgs {
     focused: boolean;
     selection: readonly NodeId[];
@@ -1181,6 +1212,8 @@ interface BuildChromeCtxArgs {
     hover: NodeId | null;
     view: View;
 }
+/** Gather the current canvas state into the context that chrome-visibility
+ *  rules are evaluated against. Rebuilt per frame. */
 declare function buildChromeCtx(args: BuildChromeCtxArgs): ChromeCtx;
 
 /**
@@ -1198,6 +1231,7 @@ declare function buildChromeCtx(args: BuildChromeCtxArgs): ChromeCtx;
  * during paint, so the hover state is always read fresh.
  */
 
+/** Options for `useHoverTracking`. */
 interface UseHoverTrackingArgs {
     canvasRef: RefObject<HTMLCanvasElement | null>;
     /** Client → world conversion. Same shape as the dispatcher's. */
@@ -1211,6 +1245,9 @@ interface UseHoverTrackingArgs {
     } | null;
     enabled?: boolean;
 }
+/** Track which node the pointer is over. Returns a getter rather than state,
+ *  so per-frame code can read the current value without the hover re-rendering
+ *  the component on every pointer move. */
 declare function useHoverTracking(args: UseHoverTrackingArgs): () => NodeId | null;
 
 /**
@@ -1889,6 +1926,10 @@ declare function useStandardActions(opts: UseStandardActionsOptions): void;
  * widened to all op-apply methods.
  */
 
+/** Build the adapter the default actions commit through when the consumer
+ *  supplies no `applyOps` hook of its own — it applies ops straight to the
+ *  scene. Selection, path and text ops are not covered; those surfaces belong
+ *  to their own owners. */
 declare function defaultCommitAdapter<TPose>(scene: Scene<unknown, string, TPose>): {
     getNode: (id: string) => Node$1<unknown, string, TPose> | undefined;
     getNodes: () => Node$1<unknown, string, TPose>[];
@@ -1904,16 +1945,25 @@ declare function defaultCommitAdapter<TPose>(scene: Scene<unknown, string, TPose
     insertNode: (node: Node$1<unknown, string, TPose>, index?: number) => NodeId;
 };
 
+/** Options for `useResizePolicy`. Each omitted field falls back to the kit
+ *  default. */
 interface UseResizePolicyOptions<TPose> {
     constraints?: TPose extends ResizePose ? BoundsConstraint<TPose>[] : never[];
     pointSnap?: TPose extends ResizePose ? PointSnapBehavior<TPose>[] : never[];
     expandIds?: (ids: string[]) => string[];
     projection?: PoseProjection<TPose>;
 }
+/** Publish how resizing should behave — constraints, point snapping, group
+ *  expansion, pose projection — for the resize action to consult. */
 declare function useResizePolicy<TPose>(options: UseResizePolicyOptions<TPose>): void;
 
+/** Publish how a slice (knife cut) is performed, so the `slice` action can
+ *  run against the consumer's geometry. */
 declare function useSliceDep(dep: SliceDep): void;
 
+/** Options for `useGestureDispatcher`: the element to listen on, the actions
+ *  and tools in play, and the hooks that turn raw DOM events into the world
+ *  coordinates and hit targets bindings match against. */
 interface UseGestureDispatcherOptions {
     /** Ref to the canvas element. Pointer/wheel/multitouch listeners attach here. */
     canvasRef: RefObject<HTMLCanvasElement | null>;
@@ -2039,6 +2089,15 @@ interface UseGestureDispatcherOptions {
      */
     getRuleCtx?: () => RuleCtx;
 }
+/**
+ * Attach the input pipeline to a canvas: DOM pointer, wheel, keyboard and
+ * multitouch listeners in, normalized input events out, routed through the
+ * dispatcher to whichever action a binding names.
+ *
+ * Everything it needs beyond its options — the active tool, the dep registry —
+ * comes from context, so it must be mounted inside `<SceneCanvas>`'s
+ * providers.
+ */
 declare function useGestureDispatcher(opts: UseGestureDispatcherOptions): void;
 
 /**
@@ -2082,6 +2141,8 @@ declare function computeWheelAction(state: WheelState, input: WheelInput, bounds
  */
 declare function clientToCanvas(canvas: HTMLCanvasElement, clientX: number, clientY: number): [number, number];
 
+/** Records recent pointer deltas and reports the current velocity, averaged
+ *  over the last 100ms — the throw speed a momentum decay starts from. */
 declare function useVelocityTracker(): {
     record(dx: number, dy: number, t: number): void;
     getVelocity(): {
@@ -2091,12 +2152,15 @@ declare function useVelocityTracker(): {
     reset(): void;
 };
 
+/** Per-axis limits on a view's position. Any side may be left open. */
 interface PanBounds {
     minX?: number;
     maxX?: number;
     minY?: number;
     maxY?: number;
 }
+/** How a decay should run: its starting velocity, how fast it slows, and what
+ *  happens if it reaches the pan limits. */
 interface DecayLoopConfig {
     velocity: {
         vx: number;
@@ -2122,11 +2186,15 @@ interface DecayLoopConfig {
     onTick: (dx: number, dy: number) => void;
     onEnd?: () => void;
 }
+/** A rAF loop that coasts a value to a stop under friction, reporting the
+ *  per-frame delta. What turns a released pan drag into momentum scrolling. */
 declare function useDecayLoop(): {
     start: (config: DecayLoopConfig) => void;
     cancel: () => void;
 };
 
+/** Animate the view from where it is to a target view — zoom-to-fit,
+ *  zoom-to-selection, and anything else that should glide rather than jump. */
 declare function useViewTween(setView: (v: View) => void): {
     animateTo: (from: View, to: View, opts?: {
         duration?: number;
@@ -2206,6 +2274,8 @@ declare function defineTool<TScratch = void>(def: ToolDef<TScratch>): Tool<TScra
  */
 declare function defineViewportTool<TScratch = void>(def: ViewportToolDef<TScratch>): Tool<TScratch>;
 
+/** Options for `useTools`: which tools exist, which one starts active, and
+ *  which run continuously regardless of the active one. */
 interface UseToolsOptions {
     /** Initial active-slot tool id. Must exist in `registry`. */
     active: string;
@@ -2216,6 +2286,8 @@ interface UseToolsOptions {
     /** Always-on tools — listen continuously regardless of active slot. */
     ambient?: AnyTool[];
 }
+/** The tool registry's runtime surface: which tool is active, which is
+ *  temporarily held by a hotkey, and how to change either. */
 interface ToolsApi {
     /** Current active-slot tool id. */
     active: string;
@@ -2260,6 +2332,7 @@ interface ToolsApi {
  */
 declare function useTools(opts: UseToolsOptions): ToolsApi;
 
+/** Options for `useKeybindings`. */
 interface UseKeybindingsOptions {
     /** Skip all wiring. Useful for touch apps or test isolation. */
     disable?: boolean;
@@ -2278,8 +2351,12 @@ interface UseKeybindingsOptions {
      */
     isToolEligible?: (toolId: string) => boolean;
 }
+/** Wire the single-key tool-activation shortcuts (V, P, T, …) and Escape to
+ *  return to the default tool. Activation is gated on what the active mode
+ *  allows, so a key cannot reach a tool the palette greys out. */
 declare function useKeybindings(tools: ToolsApi, options?: UseKeybindingsOptions): void;
 
+/** The value types a built-in pref leaf can hold. */
 type ToolPrefKind = 'number' | 'boolean' | 'string' | 'enum' | 'color' | 'paint';
 interface ToolPrefBase<K extends string, Value> {
     kind: K;
@@ -2301,9 +2378,13 @@ interface ToolPrefBase<K extends string, Value> {
      *  `pose.x` / `pose.y`). Purely presentational. */
     pair?: string;
 }
+/** How a schema-driven UI should present a number pref. */
 type ToolPrefNumberControl = 'input' | 'slider';
+/** How a schema-driven UI should present a boolean pref. */
 type ToolPrefBooleanControl = 'checkbox' | 'switch';
+/** How a schema-driven UI should present a string pref. */
 type ToolPrefStringControl = 'input' | 'textarea';
+/** How a schema-driven UI should present an enum pref. */
 type ToolPrefEnumControl = 'select' | 'radio';
 /** Display-unit conversion for number leaves whose stored value uses a
  *  canonical unit the user shouldn't see (e.g. radians stored, degrees
@@ -2314,6 +2395,8 @@ interface ToolPrefNumberUnit {
     /** Shown after the input, e.g. `'°'`. */
     suffix?: string;
 }
+/** A numeric pref, optionally bounded and stepped, and optionally stored in a
+ *  different unit from the one shown. */
 interface ToolPrefNumber extends ToolPrefBase<'number', number> {
     min?: number;
     max?: number;
@@ -2321,12 +2404,15 @@ interface ToolPrefNumber extends ToolPrefBase<'number', number> {
     control?: ToolPrefNumberControl;
     unit?: ToolPrefNumberUnit;
 }
+/** An on/off pref. */
 interface ToolPrefBoolean extends ToolPrefBase<'boolean', boolean> {
     control?: ToolPrefBooleanControl;
 }
+/** A free-text pref. */
 interface ToolPrefString extends ToolPrefBase<'string', string> {
     control?: ToolPrefStringControl;
 }
+/** A pref with a fixed set of labeled choices. */
 interface ToolPrefEnum<T extends string = string> extends ToolPrefBase<'enum', T> {
     options: readonly {
         value: T;
@@ -2334,6 +2420,8 @@ interface ToolPrefEnum<T extends string = string> extends ToolPrefBase<'enum', T
     }[];
     control?: ToolPrefEnumControl;
 }
+/** A single color, stored as a hex string. For a value that may also be a
+ *  gradient or a pattern, use {@link ToolPrefPaint} instead. */
 interface ToolPrefColor extends ToolPrefBase<'color', string> {
     /** Value is `#rrggbb`, or `#rrggbbaa` when `alpha` is set (UIs then
      *  offer an opacity control). */
@@ -2362,6 +2450,8 @@ interface ToolPrefPaint extends ToolPrefBase<'paint', unknown> {
     /** Offer an opacity control alongside the color. */
     alpha?: boolean;
 }
+/** One built-in pref leaf. `ToolPrefLeaf` widens this to include
+ *  app-defined kinds. */
 type ToolPref = ToolPrefNumber | ToolPrefBoolean | ToolPrefString | ToolPrefEnum | ToolPrefColor | ToolPrefPaint;
 /** Built-in or app-defined leaf. */
 type ToolPrefLeaf = ToolPref | ToolPrefCustom;
@@ -2372,6 +2462,8 @@ interface ToolPrefGroup {
     children: Record<string, ToolPrefLeaf | ToolPrefGroup>;
 }
 
+/** Options for `useSelectTool`: how a point resolves to nodes, how a click
+ *  chooses among them, and the appearance of the marquee. */
 interface UseSelectToolOptions<TPose> {
     /** Return ids of all objects whose painted body covers (worldX, worldY).
      *  Order doesn't matter — the tool collapses parent/child overlap via
@@ -2465,6 +2557,8 @@ declare function useSelectTool<TNode extends {
     id: string;
 }, TPose>(adapter: SelectAdapter<TNode, TPose>, options: UseSelectToolOptions<TPose>): Tool<null>;
 
+/** Options for `useRotateTool` — mostly the placement and hit size of the
+ *  rotation handle. */
 interface UseRotateToolOptions<TNode extends {
     id: string;
 }, _TPose> {
@@ -2547,6 +2641,9 @@ interface PickTopMostHitAdapter {
      *  `getZIndex` when both are present. */
     compareZ?: (a: string, b: string) => number;
 }
+/** Reduce a set of hit ids to the single one a click should act on: drop any
+ *  id that is an ancestor of another in the set, then take the topmost of what
+ *  remains. */
 declare function pickTopMostHit(ids: readonly string[], adapter: PickTopMostHitAdapter | undefined | null): string | null;
 
 /** Hit-existing gate shared by the drag-insert tool hooks. When the consumer
@@ -2559,6 +2656,8 @@ declare function applyHitExistingGate(ctx: ToolCtx<unknown>, hitExisting: ((p: {
     y: number;
 }) => string | string[] | null) | undefined): boolean;
 
+/** Momentum settings for the hand tool: how quickly a flung view slows, when
+ *  it stops, and what happens at the pan limits. */
 interface InertiaConfig {
     friction?: number;
     minSpeed?: number;
@@ -2567,6 +2666,7 @@ interface InertiaConfig {
     /** View-coordinate limits for boundary clamping. Requires `boundary` to take effect. */
     bounds?: PanBounds;
 }
+/** Options for `useHandTool`. */
 interface UseHandToolOptions {
     inertia?: false | InertiaConfig;
     /**
@@ -2615,6 +2715,8 @@ declare function useHandTool(opts?: UseHandToolOptions): Tool<HandScratch | null
  *  factories and hit gating belong on those deps, not on the tool. */
 declare function useTextTool(): Tool<undefined>;
 
+/** Options for `usePinchZoomTool`: the zoom limits, and whether it is wired
+ *  at all. */
 interface PinchZoomToolOpts {
     min?: number;
     max?: number;
@@ -2650,6 +2752,8 @@ interface PenAnchor$1 {
      *  anchor's incoming handle is NOT mirrored from this one. */
     altBroken?: boolean;
 }
+/** One in-progress subpath of the pen tool: its anchors so far, and whether
+ *  the user has closed it. */
 interface PenSubpath {
     anchors: PenAnchor$1[];
     closed: boolean;
@@ -2686,6 +2790,8 @@ interface PenScratch {
     draggingHandleAt: number | null;
     closeHintActive: boolean;
 }
+/** Options for `usePenTool`: how a finished path becomes a pose, where it is
+ *  inserted, and when a closed subpath commits. */
 interface UsePenToolOptions<TPose> {
     /** Wrap a finished PolygonPath in the consumer's pose type. */
     wrapPath: (path: PolygonPath, opts: {
@@ -2780,6 +2886,7 @@ declare function useRectTool(): Tool<null>;
  */
 declare function useEllipseTool(): Tool<null>;
 
+/** Options for `useImageTool`. */
 interface UseImageToolOptions {
     /** Image source for inserted nodes — a URL, a `blob:` URL, or a
      *  `data:image/…;base64,…` URI. Stored verbatim on each new node's
@@ -2803,6 +2910,7 @@ interface UseImageToolOptions {
  */
 declare function useImageTool(options: UseImageToolOptions): Tool<null>;
 
+/** Options for `useEyedropperTool`. */
 interface UseEyedropperToolOptions {
     /** Called when the user picks a color. `null` means "no node was hit
      *  with a color" — currently only reachable when `colorOf` returns null
@@ -2833,6 +2941,7 @@ interface UseEyedropperToolOptions {
  */
 declare function useEyedropperTool(opts: UseEyedropperToolOptions): Tool<null>;
 
+/** An endpoint of a line, in world coordinates. */
 interface LinePoint {
     x: number;
     y: number;
@@ -2858,6 +2967,7 @@ declare function useLineTool(): Tool<null>;
  *  Consumers should import from here directly; `lassoSelect.ts`
  *  re-exports the same symbol for back-compat. */
 
+/** Options for the `lasso-select` action. */
 interface UseLassoSelectOptions {
     behaviors?: LassoSelectBehavior[];
     /** When set, overrides any behavior's `defaultTransient`. */
@@ -2873,6 +2983,8 @@ interface UseLassoSelectOptions {
     debug?: DebugSink;
 }
 
+/** Options for `useLassoTool` — the lasso-select action's options plus the
+ *  tool's own hit mode and activation key. */
 interface UseLassoToolOptions extends Pick<UseLassoSelectOptions, 'behaviors' | 'transient' | 'label' | 'onGestureStart' | 'onGestureEnd' | 'minVertexSpacing' | 'debug'> {
     /** Hit mode forwarded to the default `selectFromLasso` behavior when no
      *  explicit `behaviors` array is passed. Default 'intersect'. */
@@ -2891,10 +3003,12 @@ interface UseLassoToolOptions extends Pick<UseLassoSelectOptions, 'behaviors' |
  *  `lassoSelectAction` (see `src/interactions/actions/defaults/lassoSelect.ts`). */
 declare function useLassoTool(_adapter: LassoSelectAdapter, options?: UseLassoToolOptions): Tool<undefined>;
 
+/** A point in world coordinates. */
 interface PolygonPoint {
     x: number;
     y: number;
 }
+/** Options for `usePolygonTool`. */
 interface UsePolygonToolOptions {
     label?: string;
     /** Initial side count. Side count persists across gestures
@@ -2919,10 +3033,12 @@ declare function usePolygonTool<TNode extends {
     id: string;
 }>(options?: UsePolygonToolOptions): Tool<null>;
 
+/** A point in world coordinates. */
 interface StarPoint {
     x: number;
     y: number;
 }
+/** Options for `useStarTool`. */
 interface UseStarToolOptions {
     label?: string;
     /** Initial point count. Persists across gestures (Illustrator
@@ -3324,6 +3440,9 @@ interface HierarchicalAdapter<TNode, TPose> {
  * `viewportRegistered` is false and SceneCanvas omits `hand` from the registry.
  */
 
+/** Which viewport interactions `<SceneCanvas>` wires up — pan inertia, pinch
+ *  zoom, wheel pan, wheel and keyboard zoom. Each may be switched off with
+ *  `false` or tuned with an options object. */
 interface ViewportConfig {
     inertia?: boolean | {
         friction?: number;
@@ -3411,9 +3530,15 @@ type SelectionOverlaySlotConfig<TPose> = Omit<SelectionOverlayLayerOpts<TPose>,
 type StandardSlotConfig<TNode extends {
     id: string;
 }, TPose> = GridSlotConfig | SceneSlotConfig<TNode, TPose> | SelectionOverlaySlotConfig<TPose>;
+/** What may fill one of the canvas's named layer slots: a config the canvas
+ *  builds the layer from, a pre-built layer, or `null` to leave the slot
+ *  empty. */
 type LayerSlotValue<TNode extends {
     id: string;
 }, TPose> = StandardSlotConfig<TNode, TPose> | CustomLayerEntry | null;
+/** The canvas's render stack, as named slots. The standard slots (grid,
+ *  scene, selection overlay, cell highlight) can be configured, replaced with
+ *  a layer of your own, or switched off; further keys add custom layers. */
 type LayersMap<TNode extends {
     id: string;
 }, TPose> = {
@@ -3798,6 +3923,7 @@ interface CanvasHelpers<TPose> {
     getIsVisible(): (id: string) => boolean;
 }
 
+/** Which of a node's two per-anchor color arrays an override applies to. */
 type VertexColorChannel = 'fill' | 'stroke';
 /** Function-form override: receives the consumer-supplied base color
  *  array and the current animation timestamp (ms, from the animator's
@@ -3821,7 +3947,12 @@ declare class ColorOverrideRegistry {
     version(): number;
 }
 
+/** An easing curve: maps normalized progress `t ∈ [0, 1]` to eased progress.
+ *  Curves may leave the 0–1 range in the middle (back, elastic) but should
+ *  pass through 0 at 0 and 1 at 1. */
 type EasingFn = (t: number) => number;
+/** Blends two `T` values at eased progress `t`. Called once per frame; see
+ *  {@link InterpolatorFactory} when the blend has setup worth hoisting. */
 type Interpolate<T> = (from: T, to: T, t: number) => T;
 /** Factory interpolator: built ONCE at tween start with (from, to), the returned
  *  function is called with `t ∈ [0, 1]` each frame. Use for interpolators with
@@ -3829,12 +3960,17 @@ type Interpolate<T> = (from: T, to: T, t: number) => T;
  *  shape exactly. For cheap interpolations the per-tick `Interpolate<T>` form is
  *  fine; this is the escape hatch when setup-per-tick is wasteful. */
 type InterpolatorFactory<T> = (from: T, to: T) => (t: number) => T;
+/** A spring's physical parameters. Higher stiffness settles faster, higher
+ *  damping overshoots less, higher mass makes both sluggish. */
 interface SpringPreset {
     stiffness: number;
     damping: number;
     mass: number;
 }
+/** One of the tunings in `SPRING_PRESETS`. */
 type SpringPresetName = 'gentle' | 'wobbly' | 'stiff' | 'slow';
+/** A running animation. Cancel it, or bend its time — pausing and time-scaling
+ *  act on this animation's own virtual clock, independent of the animator's. */
 interface AnimationHandle {
     /** Monotonic id assigned by the animator. */
     id: number;
@@ -3849,6 +3985,9 @@ interface AnimationHandle {
     /** True iff this handle is currently paused. */
     isPaused(): boolean;
 }
+/** A duration-based animation from `from` to `to` over `ms`, shaped by an
+ *  easing curve. Reach for a spring instead when the motion should respond to
+ *  where the value already is rather than restart from a fixed duration. */
 interface TweenOptions<T> {
     from: T;
     to: T;
@@ -3867,6 +4006,9 @@ interface TweenOptions<T> {
     /** Any new animation passed the same cancelKey cancels the prior one in flight. */
     cancelKey?: string;
 }
+/** A spring animation: runs until the value settles on `to` rather than for a
+ *  set duration, so it absorbs an initial velocity naturally. Non-numeric `T`
+ *  needs the four vector helpers. */
 interface SpringOptions<T> {
     from: T;
     to: T;
@@ -3888,6 +4030,9 @@ interface SpringOptions<T> {
     onDone?: () => void;
     cancelKey?: string;
 }
+/** Spring and decay as one animation. With a `to`, a spring pulls toward it;
+ *  with `to: null`, the value coasts on its velocity. Either can become the
+ *  other mid-flight through the handle. */
 interface PhysicsOptions<T> {
     from: T;
     /** Target. `null` ⇒ no spring force (decay-mode). */
@@ -3908,12 +4053,16 @@ interface PhysicsOptions<T> {
     onDone?: () => void;
     cancelKey?: string;
 }
+/** An `AnimationHandle` that can also be steered while it runs — the point of
+ *  the physics primitive. */
 interface PhysicsHandle<T = unknown> extends AnimationHandle {
     /** Retarget mid-flight. `null` ⇒ switch to decay-mode (no spring force). */
     setTarget(to: T | null): void;
     /** Replace the current velocity in T-units per second. */
     setVelocity(v: T): void;
 }
+/** Momentum: coast from `from` at `velocity`, slowing by `friction` each
+ *  second until below `threshold`. What a flick-to-pan leaves behind. */
 interface DecayOptions<T> {
     from: T;
     velocity: T;
@@ -3928,6 +4077,8 @@ interface DecayOptions<T> {
     onDone?: () => void;
     cancelKey?: string;
 }
+/** Options for `useAnimator`. Everything here is an injection seam for tests;
+ *  the defaults are the real clock, rAF, and `setTimeout`. */
 interface UseAnimatorOptions {
     /** Optional clock injection for tests. Returns ms since some epoch. */
     now?: () => number;
@@ -3940,6 +4091,15 @@ interface UseAnimatorOptions {
     /** Companion to `setTimer`. Defaults to global `clearTimeout`. */
     clearTimer?: (handle: unknown) => void;
 }
+/**
+ * Owns every running animation on a canvas and drives them from one rAF loop.
+ * Beyond the primitives (`tween`, `spring`, `decay`, `physics`) it offers
+ * composition — `loop`, `stagger` — and bulk control by handle, by cancel-key,
+ * or over everything at once.
+ *
+ * An animator does not know about the scene: animations report values through
+ * `onTick` and the caller decides what to do with them.
+ */
 interface Animator {
     tween<T>(opts: TweenOptions<T>): AnimationHandle;
     spring<T>(opts: SpringOptions<T>): AnimationHandle;
@@ -4043,6 +4203,7 @@ interface Animator {
      */
     keepAlive(): () => void;
 }
+/** Options for `Animator.loop`. */
 interface LoopOptions {
     /** Maximum number of iterations. Default Infinity. */
     count?: number;
@@ -4059,15 +4220,20 @@ interface StaggerOptions {
      *  any timer or child is alive. */
     cancelKey?: string;
 }
+/** Produces one iteration of a loop. Must arrange for `next` to be called when
+ *  the animation it returns finishes, or the loop stalls after one pass. */
 type LoopFactory = (iteration: number, next: () => void) => AnimationHandle;
 /** Per-index delay schedule. Number ⇒ `index * delay` ms. Function ⇒ caller
  *  decides the absolute delay for each index (e.g. `i => i * i * 30`). */
 type StaggerDelay = number | ((index: number) => number);
+/** Produces the animation for one staggered item. */
 type StaggerFactory<TItem> = (item: TItem, index: number) => AnimationHandle;
 /** A `T` value or a function that derives one from the per-item context. Used
  *  by the fluent builder methods (`.tween`, `.springPose`) so each item can
  *  vary an option (e.g. `to: (_item, i) => (i + 1) * 10`). */
 type StaggerPerItem<T, TItem> = T | ((item: TItem, index: number) => T);
+/** Options for the stagger builder's `.tween`: a tween per item, where
+ *  `from`, `to` and `ms` may each vary by item. */
 interface StaggerTweenOptions<T, TItem> {
     from: StaggerPerItem<T, TItem>;
     to: StaggerPerItem<T, TItem>;
@@ -4077,6 +4243,8 @@ interface StaggerTweenOptions<T, TItem> {
     onTick: (value: T, item: TItem, index: number) => void;
     onDone?: (item: TItem, index: number) => void;
 }
+/** Options for the stagger builder's `.springPose`: the spring tuning, and
+ *  whether each item's settle is recorded as an undoable op. */
 interface StaggerSpringPoseOptions<TPose> {
     preset?: SpringPresetName;
     stiffness?: number;
@@ -4086,6 +4254,8 @@ interface StaggerSpringPoseOptions<TPose> {
     recordOp?: boolean;
     opLabel?: string;
 }
+/** Fluent form of `Animator.stagger`: pick what to run per item after the
+ *  items and the delay schedule are already fixed. */
 interface StaggerBuilder<TItem> {
     /** Run an arbitrary per-item factory. */
     each(factory: StaggerFactory<TItem>): AnimationHandle;
@@ -4100,6 +4270,8 @@ interface StaggerBuilder<TItem> {
         id: string;
     }, TPose>, poseFn: (item: TItem, index: number) => TPose, opts?: StaggerSpringPoseOptions<TPose>): AnimationHandle;
 }
+/** Options for `Animator.tweenLoop` — a tween's options plus how each
+ *  iteration relates to the last. */
 interface TweenLoopOptions<T> {
     from: T;
     to: T;
@@ -4133,6 +4305,10 @@ interface ReorderAdapter {
     getChildren(parentId: string | null): string[];
     setChildOrder(parentId: string | null, ids: string[]): void;
 }
+/** Everything the interaction layer can ask of a scene, as one type: the
+ *  move, resize, rotate, selection, layer and reorder contracts combined.
+ *  `<SceneCanvas>` synthesizes one of these, which is why most consumers never
+ *  touch an adapter directly. */
 type SceneCanvasAdapter<TData, TLayer extends string, TPose> = MoveAdapter<Node$1<TData, TLayer, TPose>, TPose> & ResizeAdapter<Node$1<TData, TLayer, TPose>, TPose> & RotateAdapter<Node$1<TData, TLayer, TPose>, TPose> & AreaSelectAdapter & LassoSelectAdapter & LayerEnumerableAdapter<TLayer> & ReorderAdapter & Partial<InsertAdapter<Node$1<TData, TLayer, TPose>>> & {
     getParent(id: string): string | null;
     getSelection(): string[];
@@ -4193,6 +4369,9 @@ interface SceneToAdapterOptions<TData, TLayer extends string, TPose> {
      *  primitive — containers move but their descendants don't follow. */
     cascadeContainerPose?: 'rect' | ((pose: TPose, dx: number, dy: number) => TPose);
 }
+/** Derive the adapter for a scene. Reads go straight to the scene; writes are
+ *  ops applied through its history, so anything done through the adapter is
+ *  undoable. */
 declare function sceneToAdapter<TData, TLayer extends string, TPose>(scene: Scene<TData, TLayer, TPose>, options?: SceneToAdapterOptions<TData, TLayer, TPose>): SceneCanvasAdapter<TData, TLayer, TPose>;
 /**
  * React-hook wrapper around `sceneToAdapter`. Memoizes on `scene`,
@@ -4213,11 +4392,14 @@ declare function useSceneAdapter<TData, TLayer extends string, TPose>(scene: Sce
  *  Consumers should import from here directly; `rotate.ts` re-exports the
  *  same symbols for back-compat. */
 
+/** Projects a pose to and from a rotated bounding box, so the rotate action
+ *  can work on pose shapes that carry rotation differently. */
 interface RotateGeometry<TPose> {
     getRotatedBounds(pose: TPose): RotatedPose;
     /** Write a new rotation back into the pose; bounds stay the same. */
     withRotation(pose: TPose, rotation: number): TPose;
 }
+/** Options for the `rotate` action. */
 interface UseRotateOptions<TPose> {
     /** Behaviors are typed against the pose shape; the kit ships none yet
      *  (rotation snap behaviors are deferred). For non-rect TPose, behaviors
@@ -4329,6 +4511,8 @@ interface OpenFilePickerOptions {
     /** Allow multi-select. Default false. */
     multiple?: boolean;
 }
+/** Show the browser's file picker and resolve with what the user chose —
+ *  empty when they cancel. Must be called from a user gesture. */
 declare function openFilePicker(opts?: OpenFilePickerOptions): Promise<File[]>;
 
 /**
@@ -4377,6 +4561,9 @@ interface NodeRouting {
     /** Enumerate registered kinds in registration order. */
     list(): readonly NodeRoutingEntry[];
 }
+/** Build a registry of per-node-kind routing entries, which decide how a node
+ *  kind is drawn, hit-tested and serialized. Registering a duplicate kind name
+ *  throws. */
 declare function createNodeRouting(): NodeRouting;
 
 /**
@@ -4443,6 +4630,9 @@ interface NodePaintCtx {
      *  load-status error variant). */
     resolveImage?: (node: Node$1<unknown, string, unknown>) => ImageBitmap | undefined;
 }
+/** A painter for one kind of node: which nodes it claims, and the draw
+ *  commands it emits for them. Registering one is how a consumer teaches the
+ *  default renderer to draw its own node kinds. */
 interface NodeShapeEntry<TData = unknown, TPose = unknown> {
     /** Stable identifier — used for unregistration and debugging. Pick
      *  something descriptive: `'kit:text'`, `'app:image'`, etc. */
@@ -4487,6 +4677,7 @@ interface NodeInk {
     /** Stroke width in world units. `0` for no stroke. */
     strokeWidth: number;
 }
+/** Options for `registerNodeShape`. */
 interface RegisterNodeShapeOptions {
     /** `'high'` puts the painter ahead of all normally-registered ones (so
      *  it can win over a kit built-in). `'normal'` appends at the end. */
@@ -4596,6 +4787,9 @@ type NodeFill = string | FillStyle;
  * overlay since their content already shows.
  */
 
+/** Paint one node the way the kit does by default: dispatch to the first
+ *  registered node-shape painter that matches, then draw its `data.label` on
+ *  top when it has one. Consumers replace or wrap this via `drawOne`. */
 declare function defaultDrawOne<TData, TLayer extends string, TPose>(node: Node$1<TData, TLayer, TPose>, pose: TPose, ctx?: NodePaintCtx): DrawCommand[];
 
 /** Default size in CSS pixels for selection corner-handles AND their
@@ -4625,6 +4819,9 @@ interface SceneCanvasHit {
     id: string;
     kind: string;
 }
+/** Props for `<SceneCanvas>`. Most are optional: a scene is the only thing it
+ *  truly needs, and everything else — tools, layers, selection handling,
+ *  layouts, animation — layers onto sensible defaults. */
 type SceneCanvasProps<TData, TLayer extends string, TPose> = Omit<CanvasProps<Node$1<TData, TLayer, TPose>, TPose>, 'adapter' | 'moveOptions' | 'resizeOptions' | 'rotateOptions' | 'snap' | 'pickEvery' | 'boundsOf' | 'handleHitRadius' | 'selection' | 'selectionOptions' | 'tools' | 'geometry' | 'layers' | 'onBackgroundClick' | 'getIsVisible'> & {
     /** A `Scene` (typically from `useScene`) — or a `SerializedScene`
      *  JSON object, which SceneCanvas bakes into a Scene internally on
@@ -5105,10 +5302,24 @@ type SceneCanvasProps<TData, TLayer extends string, TPose> = Omit<CanvasProps<No
     onDoubleClick?: (hit: SceneCanvasHit | null) => void;
 };
 declare function SceneCanvasInner<TData, TLayer extends string, TPose>(props: SceneCanvasProps<TData, TLayer, TPose>, ref: React__default.ForwardedRef<SceneCanvasApi>): react_jsx_runtime.JSX.Element;
+/**
+ * The canvas component: renders a `Scene` and wires the interaction stack
+ * around it.
+ *
+ * Mounting one gives you the whole default kit — an adapter synthesized from
+ * the scene, the built-in tools and actions, selection, undo, and the gesture
+ * dispatcher — with each piece replaceable through props. This is the intended
+ * entry point; the lower-level primitives it composes are not part of the
+ * public surface.
+ *
+ * Its ref exposes a `SceneCanvasApi` for the imperative operations that do not
+ * fit a prop (view control, hit queries, redraw requests).
+ */
 declare const SceneCanvas: <TData, TLayer extends string, TPose>(props: SceneCanvasProps<TData, TLayer, TPose> & {
     ref?: React__default.Ref<SceneCanvasApi>;
 }) => ReturnType<typeof SceneCanvasInner>;
 
+/** Props for `<CursorCoordsHud>`. */
 interface CursorCoordsHudProps {
     canvasRef: React.RefObject<HTMLCanvasElement | null>;
     viewRef: React.RefObject<View>;
@@ -5118,8 +5329,11 @@ interface CursorCoordsHudProps {
         right?: number;
     };
 }
+/** Debug overlay showing the pointer's client and world coordinates and the
+ *  current frame rate, pinned to the canvas's top-right corner. */
 declare function CursorCoordsHud({ canvasRef, viewRef, offset }: CursorCoordsHudProps): react_jsx_runtime.JSX.Element | null;
 
+/** Props for `<PickHud>`. */
 interface PickHudProps {
     canvasRef: React.RefObject<HTMLCanvasElement | null>;
     viewRef: React.RefObject<View>;
@@ -5135,6 +5349,8 @@ interface PickHudProps {
         right?: number;
     };
 }
+/** Debug overlay listing every node under the pointer, with the one a click
+ *  would actually select shown in bold. */
 declare function PickHud({ canvasRef, viewRef, pickEvery, pickBest, offset }: PickHudProps): react_jsx_runtime.JSX.Element | null;
 
 /**
@@ -5161,6 +5377,8 @@ interface ImageNodeData {
         opacity?: number;
     };
 }
+/** Where an image is in its load: never requested, in flight, decoded, or
+ *  failed. Renderers paint a placeholder for anything but `'ready'`. */
 type ImageStatus = 'idle' | 'loading' | 'ready' | 'error';
 /** Synchronous read. Returns the decoded bitmap when ready; otherwise returns
  *  `undefined` and lazily starts a de-duped async load for `src`. */
@@ -5256,6 +5474,9 @@ interface NodeProperties {
     /** Enumerate registered kinds in registration order. */
     list(): readonly NodePropertiesEntry[];
 }
+/** Build a registry of per-node-kind property descriptors, which schema-driven
+ *  property panels read to know what a node exposes. Registering a duplicate
+ *  kind name throws. */
 declare function createNodeProperties(): NodeProperties;
 
 /** Radians-stored / degrees-shown conversion for `pose.rotation` leaves.
@@ -5307,6 +5528,8 @@ declare const inferredNodeProperties: readonly NodePropertiesEntry[];
  * group level (see `renderSceneToCanvas`'s implementation).
  */
 type SceneViewDrawOne<TData, TLayer extends string, TPose> = (node: Node$1<TData, TLayer, TPose>, pose: TPose, view: View) => DrawCommand[];
+/** What to draw into an existing canvas: the scene, the view, and the same
+ *  painting hooks `<SceneCanvas>` takes. */
 interface RenderSceneToCanvasArgs<TData, TLayer extends string, TPose> {
     /** The DOM canvas to paint into. The helper owns its WebGL2 context: the
      *  first call on a given canvas creates a renderer and stashes it; subsequent
@@ -5379,6 +5602,7 @@ declare function buildSceneViewCommands<TData, TLayer extends string, TPose>(sce
  */
 declare function renderSceneToCanvas<TData, TLayer extends string, TPose>(args: RenderSceneToCanvasArgs<TData, TLayer, TPose>): void;
 
+/** Props for `<SceneViewCanvas>`. */
 interface SceneViewCanvasProps<TData, TLayer extends string, TPose> {
     /** Scene to render. Must be the same `Scene` instance passed to whoever
      *  is mutating it; the component subscribes to its version stream and
@@ -5423,6 +5647,9 @@ declare function SceneViewCanvasInner<TData, TLayer extends string, TPose>(props
  */
 declare const SceneViewCanvas: typeof SceneViewCanvasInner;
 
+/** Build a scene outside React. `useScene` is the usual entry point; reach for
+ *  this in tests, in headless rendering, or wherever a scene must outlive a
+ *  component. Throws if no system layers are declared. */
 declare function createScene<TData, TLayer extends string, TPose = RectPose>(options: UseSceneOptions<TData, TLayer, TPose>): Scene<TData, TLayer, TPose>;
 /** Reconstruct a Scene from a JSON snapshot produced by `scene.toJSON()`.
  *  Function fields (e.g., `clipFromPose`) are resolved by string key via the
@@ -5466,6 +5693,8 @@ type DefaultLayer = typeof DEFAULT_LAYER;
 declare function useScene<TItem extends {
     id: string;
 }>(options: UseSceneTrivialOptions<TItem>): Scene<TItem, DefaultLayer, TItem>;
+/** The full call shape: explicit layers, initial nodes, custom ops, and
+ *  history configuration. */
 declare function useScene<TData, TLayer extends string, TPose = RectPose>(options: UseSceneOptions<TData, TLayer, TPose>): Scene<TData, TLayer, TPose>;
 
 /**
@@ -5545,6 +5774,7 @@ declare function computeFitView<TData, TLayer extends string, TPose>(scene: Scen
  */
 declare function computeIndicatorCommand(mainView: View, mainViewDims: ViewportDims, style?: IndicatorStyle): PathDrawCommand;
 
+/** Props for `<MinimapCanvas>`. */
 interface MinimapCanvasProps<TData, TLayer extends string, TPose> {
     /** Same scene the main canvas is rendering. */
     scene: Scene<TData, TLayer, TPose>;
@@ -5612,6 +5842,7 @@ interface HeadlessCanvasLike {
     height: number;
     getContext(contextId: 'webgl2', options?: WebGLContextAttributes): unknown;
 }
+/** What to render, at what resolution, and with which quality settings. */
 interface RenderSceneToPixelsArgs<TData, TLayer extends string, TPose> {
     scene: Scene<TData, TLayer, TPose>;
     /** Scene-space rect to render (origin + size in scene units). Output pixel
@@ -5655,6 +5886,8 @@ interface RenderSceneToPixelsArgs<TData, TLayer extends string, TPose> {
      *  `flattenTolerance`. Explicitly passing 0.25 is always valid. */
     flattenTolerancePx?: number;
 }
+/** The result of planning a headless render: how big the output is, the view
+ *  that maps the source rect onto it, and the commands to draw. */
 interface PixelRenderPlan {
     width: number;
     height: number;
@@ -5665,6 +5898,15 @@ interface PixelRenderPlan {
  *  anisotropic `View`, and the full command list (background + view-wrapped
  *  scene). Exported for tests and for callers targeting their own renderer. */
 declare function planPixelRender<TData, TLayer extends string, TPose>(args: Omit<RenderSceneToPixelsArgs<TData, TLayer, TPose>, 'gl' | 'createCanvas' | 'flattenTolerancePx'>): PixelRenderPlan;
+/**
+ * Render part of a scene to raw pixels, with no canvas mounted and no React
+ * involved — for export, thumbnails, print, and pixel-diff tests.
+ *
+ * Output size follows from the source rect and the requested scale, so
+ * rendering the same region at a higher scale is a real resolution increase
+ * rather than an upscale: curves are re-flattened and glyphs re-rasterized for
+ * the output resolution.
+ */
 declare function renderSceneToPixels<TData, TLayer extends string, TPose>(args: RenderSceneToPixelsArgs<TData, TLayer, TPose>): RasterImage;
 
 /**
@@ -5741,22 +5983,36 @@ declare function SelectionContextProviderIfRoot({ children, }: {
  */
 declare function usePublishSelection(ids: readonly NodeId[], kinds?: readonly (string | undefined)[]): void;
 
+/** Mount a `<PointerContextProvider>` only when none is already in scope. */
 declare function PointerProviderIfRoot({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
+/** Mount an `<ActionsProvider>` only when none is already in scope, so
+ *  nesting canvases share one action registry instead of shadowing it. */
 declare function ActionsProviderIfRoot({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
+/** Mount a `<DepRegistryProvider>` only when none is already in scope, so a
+ *  consumer's dep sources are not shadowed by a nested canvas. */
 declare function DepRegistryProviderIfRoot({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
+/**
+ * Mounts every kit-wide provider at once — deps, actions, active tool,
+ * selection and pointer — each only if one is not already in scope.
+ *
+ * `<SceneCanvas>` does this for itself, so this is for the case where kit
+ * state has to be shared by things outside a canvas: a toolbar, a property
+ * panel, or two canvases that should agree on the selection.
+ */
 declare function WeaselProvider({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
+/** Options for `useCanvasFocus`. */
 interface UseCanvasFocusOptions {
     /** Initial focus state. Default `false` — handles hidden until first click. */
     initial?: boolean;
@@ -5764,6 +6020,8 @@ interface UseCanvasFocusOptions {
      *  document tab order). Set to `-1` for programmatic-only focus. */
     tabIndex?: number;
 }
+/** What `useCanvasFocus` hands back: the focus state, the props that
+ *  maintain it, and a getter for reading it from per-frame code. */
 interface CanvasFocusReturn {
     /** Live boolean — true when the element has DOM focus. Triggers re-renders
      *  when the focus state changes (set via React state). */
@@ -5783,6 +6041,8 @@ interface CanvasFocusReturn {
     /** Imperative focus / blur. Useful for tests and programmatic control. */
     setFocused: (next: boolean) => void;
 }
+/** Track DOM focus on the canvas, so chrome that should only show while the
+ *  canvas is focused can be gated on it. */
 declare function useCanvasFocus(options?: UseCanvasFocusOptions): CanvasFocusReturn;
 
 /**
@@ -5796,6 +6056,7 @@ declare function useCanvasFocus(options?: UseCanvasFocusOptions): CanvasFocusRet
  * construction time.
  */
 
+/** Options for `gateLayer`. */
 interface GateLayerOptions<TData> {
     /** The wrapped layer. Its `id`, `label`, `defaultVisible`, `alwaysOn`,
      *  `space` flow through unchanged. */
@@ -5803,6 +6064,9 @@ interface GateLayerOptions<TData> {
     /** Returns `true` to render the layer this frame, `false` to skip. */
     visible: () => boolean;
 }
+/** Wrap a render layer so it only draws while `visible()` is true. The
+ *  predicate is consulted per frame, which is how chrome follows canvas focus
+ *  without the layer knowing anything about focus. */
 declare function gateLayer<TData>(opts: GateLayerOptions<TData>): RenderLayer<TData>;
 
 /**
@@ -5928,6 +6192,8 @@ declare function annulusSemiAxes(shape: Extract<AffordanceRegion['shape'], {
     ry: number;
 };
 
+/** Options for `createCornerResizeAffordance` — the size and appearance of
+ *  the corner handles. */
 interface CornerResizeAffordanceOptions {
     /** Hit radius (screen-px) for the corner handles. Default 8. */
     handleHitRadius?: number;
@@ -5936,6 +6202,8 @@ interface CornerResizeAffordanceOptions {
     fill?: string;
     stroke?: string;
 }
+/** What a corner-resize hit hands to the resize action: which corner stays
+ *  put, what is being resized, and the world-space pivot to scale from. */
 interface CornerResizeScratch extends CommonAffordanceScratch {
     /** Resize anchor identifying the OPPOSITE corner (the one that stays
      *  fixed). Matches the kit's existing ResizeAnchor convention. */
@@ -5963,6 +6231,8 @@ interface CornerResizeScratch extends CommonAffordanceScratch {
  */
 declare function createCornerResizeAffordance(opts?: CornerResizeAffordanceOptions): Affordance;
 
+/** Options for `createRotationAffordance` — how thick the rotate band is
+ *  outside the selection, and how (or whether) it is painted. */
 interface RotationAffordanceOptions {
     /** Minimum screen-space thickness of the rotate-zone band outside the
      *  selection AABB. The outer ellipse semi-axes are clamped to
@@ -5982,6 +6252,8 @@ interface RotationAffordanceOptions {
     /** Cursor while hovering the ring. Defaults to `'grab'`. */
     cursor?: string;
 }
+/** What a rotation-handle hit hands to the rotate action: what is being
+ *  rotated, and the world-space pivot it turns around. */
 interface RotationScratch extends CommonAffordanceScratch {
     /** Id of the rotation target — single selection id, or
      *  `MULTI_RESIZE_TARGET_ID` for multi-selection. */
@@ -6036,12 +6308,16 @@ interface AnchorState {
     /** Current editable path for a node id. Non-polygon values are ignored. */
     getPose(id: string): unknown;
 }
+/** Options for the path-anchor affordances. */
 interface PathAnchorAffordanceOptions {
     /** Hit radius (screen-px) for anchor and control points. Default 8. */
     hitRadius?: number;
     /** Cursor while hovering an anchor or control. Defaults to `'pointer'`. */
     cursor?: string;
 }
+/** What an anchor hit hands to the action that follows: which path, which
+ *  anchor, and whether the grab was on the anchor itself or one of its two
+ *  control points. */
 interface AnchorScratch extends CommonAffordanceScratch {
     /** Node id of the path the anchor belongs to. */
     targetId: string;
@@ -6167,6 +6443,7 @@ interface MeasuredText {
 /** Greedy word-wrap text measurement against `maxWidth`; preserves explicit `\n` breaks. */
 declare function measureText(ctx: CanvasRenderingContext2D, text: string, maxWidth: number, style: ResolvedTextStyle): MeasuredText;
 
+/** Options for `measureTextBounds`. */
 interface MeasureTextBoundsOpts {
     /** Wrap width; words exceeding it start a new line. Default `Infinity` (no wrap). */
     maxWidth?: number;
@@ -6277,10 +6554,12 @@ declare function caretIndexAt(ctx: CanvasRenderingContext2D, x: number, y: numbe
  * closing edge from `polygon[N-1]` to `polygon[0]` is implicit. Even-odd
  * fill rule (matches `pointInPath`).
  */
+/** A 2D point or vector. */
 interface Vec2 {
     x: number;
     y: number;
 }
+/** An axis-aligned rectangle. */
 interface Rect {
     x: number;
     y: number;
@@ -6376,6 +6655,8 @@ declare function fitTextPose(ctx: CanvasRenderingContext2D, pose: TextPose, opts
  * `isMixed` check, regardless of what's being aggregated.
  */
 declare const MIXED: unique symbol;
+/** The type of {@link MIXED}. Property panels use it to say "the selection
+ *  does not agree on this value" without colliding with any real value. */
 type Mixed = typeof MIXED;
 
 /**
@@ -6701,6 +6982,8 @@ interface UseSceneTextEditReturn extends UseTextEditReturn {
      *  a caret offset via `caretIndexAt`, and starts edit on that node. */
     onDoubleClick: (e: MouseEvent$1<HTMLElement>) => void;
 }
+/** Wire double-click-to-edit text on a scene: mounts a DOM editing overlay
+ *  over the node being edited and writes the result back as an undoable op. */
 declare function useSceneTextEdit<TData extends DefaultTextData, TLayer extends string, TPose extends RectPose = RectPose>(scene: Scene<TData, TLayer, TPose>, container: HTMLElement | null, options?: UseSceneTextEditOptions<TData>): UseSceneTextEditReturn;
 
 /**
@@ -6727,6 +7010,8 @@ declare function useSceneTextEdit<TData extends DefaultTextData, TLayer extends
 
 /** The additive run flags. */
 type FlagKey = 'bold' | 'italic' | 'underline' | 'strikethrough';
+/** The result of toggling a style flag over a text range: the rewritten runs
+ *  and node style, and whether the change could be made at all. */
 interface SetFlagResult {
     runs: StyledRun[];
     style: TextStyle;
@@ -6763,6 +7048,9 @@ declare function setFlagOverRange(runs: readonly StyledRun[], style: TextStyle,
  * silently different result.
  */
 
+/** Build a draw command for a single unstyled string. Text is laid out with
+ *  the registered font's metrics, wrapped at `maxWidth` and aligned within
+ *  `height` when both are given. */
 declare function textCommand(x: number, y: number, text: string, style?: TextStyle, maxWidth?: number, height?: number, verticalAlign?: TextVerticalAlign): DrawCommand;
 
 /**
@@ -6932,6 +7220,8 @@ declare function gradientForBounds(kind: GradientKind, bounds: {
  * the renderer in one frame.
  */
 
+/** The box a `'bounds'` gradient's normalized geometry is mapped onto —
+ *  usually a node's bounds. */
 interface FillPoseBox {
     x: number;
     y: number;
@@ -7142,6 +7432,9 @@ interface MoveToIndexArgs {
 /** Op: move all `ids` to a contiguous block starting at `index` within `parentId`'s child order. */
 declare function createMoveToIndexOp(args: MoveToIndexArgs): Op;
 
+/** The geometry fields a `setPath` op replaces together — the path itself,
+ *  whether it is closed, and the parameters it was generated from. They move
+ *  as one so a parametric shape and its baked path never disagree. */
 interface SetPathFields {
     path: unknown;
     closed: boolean;
@@ -7187,6 +7480,7 @@ interface HitAdapter<TNode extends {
     getPose: (id: string) => TPose;
     getParent: (id: string) => string | null;
 }
+/** Options for `nestedHitTester`. */
 interface NestedHitOpts<TNode extends {
     id: string;
 }, TPose> {
@@ -7203,6 +7497,8 @@ interface NestedHitOpts<TNode extends {
      *  never (treat every object as hittable). */
     isGroup?: (id: string, obj: TNode | undefined) => boolean;
 }
+/** Hit-test entry points for a nested scene: one that always picks the
+ *  outermost ancestor, and one that steps deeper on alt-click. */
 interface NestedHitTester {
     /** Outermost-ancestor pick. Suitable as the chrome-level `pickEvery`: a
      *  casual click selects the whole top-level ancestor. Returns `null` on
@@ -7216,6 +7512,9 @@ interface NestedHitTester {
      *  Plug into `useSelectTool({ pickBest })`. */
     pickBest: (worldX: number, worldY: number, alt: boolean, selection: readonly string[]) => string | null;
 }
+/** Build hit-testers that respect containers: a plain click selects the
+ *  top-level ancestor, and alt-clicking descends one level at a time toward
+ *  the leaf actually under the pointer. */
 declare function nestedHitTester<TNode extends {
     id: string;
 }, TPose>(adapter: HitAdapter<TNode, TPose>, opts: NestedHitOpts<TNode, TPose>): NestedHitTester;
@@ -7332,6 +7631,9 @@ declare function boundsOfPath(path: Path): RectPath;
  * uses it to validate the array length in dev builds.
  */
 
+/** One anchor of an editable path: its on-curve point plus the two control
+ *  handles that shape the segments either side of it. Handles are in the same
+ *  space as the point, and absent when the adjoining segment is straight. */
 interface PenAnchor {
     x: number;
     y: number;
@@ -7357,6 +7659,8 @@ declare function pathToAnchors(path: PolygonPath): {
     anchors: PenAnchor[][];
     closed: boolean[];
 };
+/** How many anchors a path has. Matches the per-anchor arrays the renderer
+ *  expects for `vertexColors`. */
 declare function countPathAnchors(path: Path): number;
 
 interface Point {
@@ -7670,6 +7974,10 @@ declare function flattenQuadratic(x0: number, y0: number, x1: number, y1: number
  * front.
  */
 declare function flattenCubicWithArcLen(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, tolerance: number, out: number[], arcOut: number[]): number;
+/** Flatten a quadratic bezier into line segments within `tolerance`, appending
+ *  points to `out` and their cumulative arc lengths to `arcOut`. The arc
+ *  lengths are what lets per-anchor color and dash phase be interpolated
+ *  evenly along the curve rather than per segment. */
 declare function flattenQuadraticWithArcLen(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, tolerance: number, out: number[], arcOut: number[]): number;
 
 /**
@@ -7734,8 +8042,11 @@ declare function decomposePath(parent: Path, world: Path): Path;
  * one subpath is also returned as a single-element array — a trivial pass.
  */
 
+/** Split a path into one path per subpath, cutting at each `M`. A path with a
+ *  single subpath comes back as a one-element array. */
 declare function splitSubpaths(path: PolygonPath): PolygonPath[];
 
+/** Options for `splitByLine`. */
 interface SplitByLineOptions {
     /** Polyline flattening tolerance for the boundary-crossing gate. */
     flattenTolerance?: number;
@@ -7795,6 +8106,7 @@ declare const pathOriginProjection: OriginProjection<Path>;
  * argument.
  */
 
+/** Appearance of the pen tool's in-progress path. */
 interface PenPreviewStyle {
     anchorFill?: string;
     anchorStroke?: string;
@@ -7803,12 +8115,16 @@ interface PenPreviewStyle {
     closeHintFill?: string;
     finishedSubpathStroke?: string;
 }
+/** Options for `createPenPreviewLayer`. */
 interface CreatePenPreviewLayerOptions {
     /** The Tool returned by usePenTool. The layer reads its scratch via
      *  `tool.initScratch()` (the hook is contracted to return a stable ref). */
     penTool: Tool<PenScratch>;
     style?: PenPreviewStyle;
 }
+/** Render layer that draws the pen tool's path as it is being placed —
+ *  committed anchors, the rubber band to the cursor, and the close hint. Draws
+ *  nothing when the pen is idle. */
 declare function createPenPreviewLayer(opts: CreatePenPreviewLayerOptions): RenderLayer<unknown>;
 
 /**
@@ -7833,6 +8149,8 @@ declare function createPenPreviewLayer(opts: CreatePenPreviewLayerOptions): Rend
  * stay constant regardless of zoom.
  */
 
+/** Options for `createPathEditingOverlayLayer`. Everything is read per frame,
+ *  so the layer follows a changing edit target without being rebuilt. */
 interface CreatePathEditingOverlayLayerOptions {
     /** Returns the id of the polygon currently in anchor-edit mode, or null
      *  when no node is being edited. Read each frame so live selection /
@@ -7863,6 +8181,7 @@ interface CreatePathEditingOverlayLayerOptions {
     /** Optional styling overrides. */
     style?: PathEditingOverlayStyle;
 }
+/** Appearance of the anchor and handle markers. */
 interface PathEditingOverlayStyle {
     anchorSizePx?: number;
     handleDotRadiusPx?: number;
@@ -7882,6 +8201,9 @@ interface PathEditingOverlayStyle {
     /** Fill of the marquee rubber band. */
     marqueeFill?: string;
 }
+/** Render layer that draws the anchors and control handles of the path
+ *  currently being anchor-edited. Draws nothing when no path is being
+ *  edited. */
 declare function createPathEditingOverlayLayer(opts: CreatePathEditingOverlayLayerOptions): RenderLayer<unknown>;
 
 /** Union of N paths. Commutative. Returns an empty path if all inputs are empty. */
@@ -7945,6 +8267,7 @@ interface SharedAnchor {
     /** Spiro continuity class at this anchor. Default 'g2-smooth'. */
     spiroType?: 'corner' | 'g2-smooth' | 'g4-smooth';
 }
+/** Which curve representation an anchor set is interpreted through. */
 type CurveRepKind = 'bezierCubic' | 'bezierQuadratic' | 'nurbs' | 'spiro';
 /** A user-facing control surfaced by a representation. Rendered uniformly
  *  by the demo's panel sidebar. */
@@ -7987,14 +8310,19 @@ interface CurveRepresentation {
     discriminators(anchors: SharedAnchor[]): Discriminator[];
 }
 
+/** Cubic bezier: each segment takes two control handles. The familiar pen-tool curve, and what SVG path data stores natively. */
 declare const bezierCubic: CurveRepresentation;
 
+/** Quadratic bezier: one control point per segment. Cheaper than cubic and what TrueType glyph outlines use, at the cost of expressiveness. */
 declare const bezierQuadratic: CurveRepresentation;
 
+/** NURBS: anchors act as weighted control points the curve is pulled toward rather than passing through. Flattened to line segments when converted to a path. */
 declare const nurbs: CurveRepresentation;
 
+/** Spiro (κ-curves): curvature-continuous through each anchor, so joins stay visually smooth without hand-tuned handles. Approximated as cubics when converted to a path. */
 declare const spiro: CurveRepresentation;
 
+/** Every curve representation the kit ships, keyed by kind. */
 declare const CURVE_REPS: Readonly<Record<CurveRepKind, CurveRepresentation>>;
 
 /**
@@ -8218,6 +8546,8 @@ declare function guideSnapStrategy<TPose extends {
     x: number;
     y: number;
 }>(getGuides: () => readonly Guide[], options?: Omit<GuideSnapOptions<TPose>, 'origin'>): SnapStrategy<TPose>;
+/** As above, for a `TPose` that is not a rect: `origin` tells the strategy how
+ *  to read and write the pose's origin. */
 declare function guideSnapStrategy<TPose>(getGuides: () => readonly Guide[], options: GuideSnapOptions<TPose> & {
     origin: OriginProjection<TPose>;
 }): SnapStrategy<TPose>;
@@ -8288,6 +8618,9 @@ interface AlignBounds {
 /** Which feature of a box to test against candidates, per axis.
  *  'min' = left/top edge, 'center' = centerline, 'max' = right/bottom edge. */
 type AlignAnchor = 'min' | 'center' | 'max';
+/** The correction an alignment match asks for: the translation that lands the
+ *  dragged bounds on the matched guides, and the guides themselves so they can
+ *  be drawn. */
 interface AlignMatchResult {
     dx: number;
     dy: number;
@@ -8301,6 +8634,8 @@ interface AlignBoundsProjection<TPose> {
     boundsOf(pose: TPose): AlignBounds;
     translate(pose: TPose, dx: number, dy: number): TPose;
 }
+/** Which candidate lines to derive from a set of bounds — edges, centers, or
+ *  both, and whether the page box contributes its own. */
 interface DeriveAlignmentGuidesOptions {
     /** Include the document/page box's edges + center as candidates. */
     page?: AlignBounds;
@@ -8423,16 +8758,22 @@ declare function rotationHandle(pose: {
  *  handle's center on both axes. Mirrors `hitCornerHandle`. */
 declare function hitRotationHandle(handle: RotationHandle, px: number, py: number, radius: number): boolean;
 
+/** A point in world coordinates. */
 interface DragRectPoint {
     x: number;
     y: number;
 }
+/** The axis-aligned box between the drag's two corners, always with
+ *  non-negative extents regardless of drag direction. */
 interface DragRectBounds {
     x: number;
     y: number;
     width: number;
     height: number;
 }
+/** Live state of a rectangle drag, handed to each lifecycle callback. Either
+ *  corner can be moved mid-gesture, which is how a tool re-anchors a drag
+ *  without restarting it. */
 interface DragRectCtx<TScratch = unknown> {
     start: DragRectPoint;
     current: DragRectPoint;
@@ -8445,12 +8786,15 @@ interface DragRectCtx<TScratch = unknown> {
     /** Override the current point mid-gesture (between start and end). */
     setCurrent(p: DragRectPoint): void;
 }
+/** The context handed to `onEnd`, adding whether the final box is too small
+ *  to be meaningful. */
 interface DragRectEndCtx<TScratch = unknown> extends DragRectCtx<TScratch> {
     /** True if the end-time bounds are at or below `minBounds` on either axis.
      *  Present-tense state check — distinct from the base's retrospective
      *  `wasSubThreshold`. Computed by this wrapper, not by `useDragGesture`. */
     isSubThreshold: boolean;
 }
+/** Options for `useDragRect`. */
 interface UseDragRectOptions<TScratch = unknown> {
     minBounds?: {
         width: number;
@@ -8470,6 +8814,7 @@ interface UseDragRectOptions<TScratch = unknown> {
      *  behavior is identical to today (identity passthrough). */
     snapPoint?: (p: DragRectPoint) => DragRectPoint;
 }
+/** Drives a rectangle drag and publishes the live box for overlay drawing. */
 interface DragRectController {
     start(worldX: number, worldY: number, modifiers: ModifierState): void;
     move(worldX: number, worldY: number, modifiers: ModifierState): boolean;
@@ -8482,6 +8827,14 @@ interface DragRectController {
     } | null;
     readonly isActive: boolean;
 }
+/**
+ * The gesture "the user drew a rectangle": press, drag, release, with the
+ * resulting box reported live and at commit.
+ *
+ * It is a spatial input primitive, not an insert mechanism — what the box
+ * means is entirely up to whoever consumes it. Marquee selection, cropping and
+ * shape insertion all sit on top of the same gesture.
+ */
 declare function useDragRect<TScratch = unknown>(options?: UseDragRectOptions<TScratch>): DragRectController;
 
 /** Pointer position in both world (gesture-coord) and client (CSS-px) space. */
@@ -8504,11 +8857,15 @@ interface DragGestureCtx<TScratch = unknown> {
     /** 'pending' or 'active'. Never 'idle' inside a callback. */
     phase: 'pending' | 'active';
 }
+/** The context handed to `onEnd`, adding whether the gesture ever passed its
+ *  activation threshold. */
 interface DragGestureEndCtx<TScratch = unknown> extends DragGestureCtx<TScratch> {
     /** True if phase never reached 'active'. Wrappers without thresholdReached
      *  always see false here (their gesture activates at start()). */
     wasSubThreshold: boolean;
 }
+/** Options for `useDragGesture`: when the gesture becomes active, and what to
+ *  do at each point in its lifecycle. */
 interface UseDragGestureOptions<TScratch = unknown> {
     initScratch?: () => TScratch;
     /** Predicate consulted on each move while phase === 'pending'. Return true
@@ -8523,6 +8880,8 @@ interface UseDragGestureOptions<TScratch = unknown> {
     onGestureStart?: () => void;
     onGestureEnd?: (committed: boolean) => void;
 }
+/** Drives a drag gesture. The owner feeds it pointer positions; it decides
+ *  when the drag has really begun and calls back accordingly. */
 interface DragGestureController {
     start(point: DragGesturePoint, modifiers: ModifierState): void;
     move(point: DragGesturePoint, modifiers: ModifierState): boolean;
@@ -8531,25 +8890,41 @@ interface DragGestureController {
     readonly phase: DragGesturePhase;
     readonly isActive: boolean;
 }
+/**
+ * The base drag primitive: tracks a pointer from press to release, with an
+ * optional threshold below which the gesture stays pending and commits
+ * nothing.
+ *
+ * It is a gesture and only a gesture — it says where the pointer went, never
+ * what that should do. `useDragRect` and `useDragRadial` build on it, and
+ * actions decide what to make of the result.
+ */
 declare function useDragGesture<TScratch = unknown>(options?: UseDragGestureOptions<TScratch>): DragGestureController;
 
+/** A point in world coordinates. */
 interface DragRadialPoint {
     x: number;
     y: number;
 }
+/** A radial drag expressed as its center and the polar coordinates of the
+ *  cursor relative to it. */
 interface DragRadialState {
     center: DragRadialPoint;
     radius: number;
     rotation: number;
 }
+/** Live state of a radial drag, handed to each lifecycle callback. */
 interface DragRadialCtx<TScratch = unknown> extends DragRadialState {
     modifiers: ModifierState;
     scratch: TScratch;
 }
+/** The context handed to `onEnd`, adding whether the final radius is too
+ *  small to be meaningful. */
 interface DragRadialEndCtx<TScratch = unknown> extends DragRadialCtx<TScratch> {
     /** True at end time if the radius is at or below `minRadius`. */
     isSubThreshold: boolean;
 }
+/** Options for `useDragRadial`. */
 interface UseDragRadialOptions<TScratch = unknown> {
     minRadius?: number;
     initScratch?: () => TScratch;
@@ -8566,6 +8941,8 @@ interface UseDragRadialOptions<TScratch = unknown> {
      *  When omitted, behavior is identical to today (identity passthrough). */
     snapPoint?: (p: DragRadialPoint) => DragRadialPoint;
 }
+/** Drives a radial drag and publishes the live center/radius/rotation for
+ *  overlay drawing. */
 interface DragRadialController {
     start(worldX: number, worldY: number, modifiers: ModifierState): void;
     move(worldX: number, worldY: number, modifiers: ModifierState): boolean;
@@ -8685,6 +9062,7 @@ declare function setScratch<T>(store: ScratchStore, key: ScratchKey<T>, value: T
  *  `false` if it wasn't. */
 declare function deleteScratch<T>(store: ScratchStore, key: ScratchKey<T>): boolean;
 
+/** Options for `selectFromLasso`. */
 interface SelectFromLassoOptions {
     /** Hit mode for `hitTestLasso`. Default 'intersect'. */
     mode?: LassoHitMode;
@@ -8769,6 +9147,8 @@ interface UseDistributeReturn {
  *  remaining items are repositioned. Single batch — one undo step. */
 declare function useDistribute<TPose>(adapter: DistributeAdapter<TPose>, options?: UseDistributeOptions<TPose>): UseDistributeReturn;
 
+/** The six Boolean path operations, each acting on the current selection and
+ *  committing as one undo step. */
 interface UseBooleansReturn {
     union(): void;
     intersect(): void;
@@ -8777,13 +9157,18 @@ interface UseBooleansReturn {
     divide(): void;
     crop(): void;
 }
+/** Options for `useBooleans`. */
 interface UseBooleansOptions {
     /** No-op. Retained for source-compatibility; auto-registration is now
      *  handled by `useStandardActions` via the Pathfinder descriptors. */
     enableActions?: boolean;
 }
+/** Bind the Boolean path operations to an adapter that knows how to read the
+ *  selection, fetch world-space paths and mint result nodes. */
 declare function useBooleans(adapter: BooleansAdapter, _options?: UseBooleansOptions): UseBooleansReturn;
 
+/** Publish a Boolean-ops adapter so the built-in Pathfinder actions can run.
+ *  Silently does nothing outside a `<DepRegistryProvider>`. */
 declare function useBooleansAdapter(adapter: BooleansAdapter): void;
 
 /**
@@ -8879,39 +9264,79 @@ declare const DEFAULT_DEBUG_THEME: DebugTheme;
  */
 declare const DEFAULT_DEBUG_STROKES: DebugStrokes;
 
+/** No easing: constant rate from start to finish. */
 declare const linear: EasingFn;
+/** Accelerates from a standstill, gently. */
 declare const easeInQuad: EasingFn;
+/** Decelerates to a stop, gently. The safe default for UI motion. */
 declare const easeOutQuad: EasingFn;
+/** Accelerates then decelerates, gently. */
 declare const easeInOutQuad: EasingFn;
+/** Accelerates from a standstill, moderately. */
 declare const easeInCubic: EasingFn;
+/** Decelerates to a stop, moderately. */
 declare const easeOutCubic: EasingFn;
+/** Accelerates then decelerates, moderately. */
 declare const easeInOutCubic: EasingFn;
+/** Accelerates from a standstill, sharply. */
 declare const easeInQuart: EasingFn;
+/** Decelerates to a stop, sharply. */
 declare const easeOutQuart: EasingFn;
+/** Accelerates then decelerates, sharply. */
 declare const easeInOutQuart: EasingFn;
+/** Accelerates from a standstill, very sharply. */
 declare const easeInQuint: EasingFn;
+/** Decelerates to a stop, very sharply. */
 declare const easeOutQuint: EasingFn;
+/** Accelerates then decelerates, very sharply. */
 declare const easeInOutQuint: EasingFn;
+/** Accelerates from a standstill along a sine curve — the mildest
+ *  acceleration of the built-ins. */
 declare const easeInSine: EasingFn;
+/** Decelerates to a stop along a sine curve — the mildest
+ *  deceleration of the built-ins. */
 declare const easeOutSine: EasingFn;
+/** Accelerates then decelerates along a sine curve. */
 declare const easeInOutSine: EasingFn;
+/** Accelerates exponentially: barely moves at first, then rushes. */
 declare const easeInExpo: EasingFn;
+/** Decelerates exponentially: leaps away, then creeps in. */
 declare const easeOutExpo: EasingFn;
+/** Exponential at both ends — a very fast middle between two
+ *  near-still extremes. */
 declare const easeInOutExpo: EasingFn;
+/** Accelerates along a circular arc: slow start, abrupt arrival. */
 declare const easeInCirc: EasingFn;
+/** Decelerates along a circular arc: abrupt start, slow arrival. */
 declare const easeOutCirc: EasingFn;
+/** Circular arcs at both ends. */
 declare const easeInOutCirc: EasingFn;
+/** Pulls back past the start before moving forward. Overshoots below 0. */
 declare const easeInBack: EasingFn;
+/** Overshoots the target, then settles back onto it. Exceeds 1. */
 declare const easeOutBack: EasingFn;
+/** Overshoots at both ends. Leaves the 0–1 range on each side. */
 declare const easeInOutBack: EasingFn;
+/** Oscillates around the start with growing amplitude, then snaps away. */
 declare const easeInElastic: EasingFn;
+/** Springs past the target and wobbles into it. Exceeds 1. */
 declare const easeOutElastic: EasingFn;
+/** Wobbles at both ends. Leaves the 0–1 range on each side. */
 declare const easeInOutElastic: EasingFn;
+/** Lands on the target and bounces, in hops of decreasing height. */
 declare const easeOutBounce: EasingFn;
+/** Bounces up to the start before departing — `easeOutBounce` reversed. */
 declare const easeInBounce: EasingFn;
+/** Bounces at both ends. */
 declare const easeInOutBounce: EasingFn;
+/** Alias for `easeInQuad`, kept for call sites that predate the
+ *  named-curve library. */
 declare const easeIn: EasingFn;
+/** Alias for `easeOutQuad`, kept for call sites that predate the
+ *  named-curve library. */
 declare const easeOut: EasingFn;
+/** Alias for `easeInOutQuad`, kept for call sites that predate the
+ *  named-curve library. */
 declare const easeInOut: EasingFn;
 /** All easings in one bag — useful for demos / pickers. */
 declare const EASINGS: {
@@ -8947,11 +9372,18 @@ declare const EASINGS: {
     readonly easeOutBounce: EasingFn;
     readonly easeInOutBounce: EasingFn;
 };
+/** The name of one of the built-in easing curves. */
 type EasingName = keyof typeof EASINGS;
+/** Named spring tunings, from softest to firmest. Springs settle on a target
+ *  rather than running for a fixed duration, so these are an alternative to an
+ *  easing curve, not a modifier on one. */
 declare const SPRING_PRESETS: Record<SpringPresetName, SpringPreset>;
 
+/** Create the animator for a canvas. One rAF loop drives every animation it
+ *  owns, and everything still running is cancelled on unmount. */
 declare function useAnimator(opts?: UseAnimatorOptions): Animator;
 
+/** Options for `tweenPose`. */
 interface TweenPoseOptions<TPose> {
     id: string;
     to: TPose;
@@ -8967,6 +9399,7 @@ interface TweenPoseOptions<TPose> {
     opLabel?: string;
     onDone?: () => void;
 }
+/** Options for `springPose`. */
 interface SpringPoseOptions<TPose> {
     id: string;
     to: TPose;
@@ -8979,13 +9412,25 @@ interface SpringPoseOptions<TPose> {
     opLabel?: string;
     onDone?: () => void;
 }
+/**
+ * Animate one node's pose to `to` over `ms`, writing each frame through the
+ * adapter.
+ *
+ * Unlike the color helpers this really does move the node. Undo therefore has
+ * to be considered: by default a single transform op covering the whole
+ * animation is recorded up front, so one undo returns the node to where it
+ * started rather than replaying frames.
+ */
 declare function tweenPose<TNode extends {
     id: string;
 }, TPose>(animator: Animator, adapter: SceneAdapter<TNode, TPose>, opts: TweenPoseOptions<TPose>): AnimationHandle;
+/** `tweenPose` driven by a spring instead of a duration. Same op-recording
+ *  behavior. */
 declare function springPose<TNode extends {
     id: string;
 }, TPose>(animator: Animator, adapter: SceneAdapter<TNode, TPose>, opts: SpringPoseOptions<TPose>): AnimationHandle;
 
+/** Options for `animateOnSetPose`. */
 interface AnimateOnSetPoseOptions<TPose> {
     /** Default: 200ms tween with easeOut. */
     ms?: number;
@@ -9013,10 +9458,24 @@ interface AnimateOnSetPoseOptions<TPose> {
     /** Op label for the recorded transform op. Default: `'animate'`. */
     opLabel?: string;
 }
+/**
+ * Wrap an adapter so every `setPose` animates to the new pose instead of
+ * jumping to it. Anything that moves a node — a layout strategy, an action, a
+ * consumer's own code — is animated without knowing it, since the adapter is
+ * the single write path.
+ *
+ * Poses written from inside another animation's tick, and (optionally) poses
+ * written for a node currently under a gesture, are passed straight through:
+ * animating those would fight whatever is already driving the node.
+ */
 declare function animateOnSetPose<TNode extends {
     id: string;
 }, TPose>(adapter: SceneAdapter<TNode, TPose>, animator: Animator, opts?: AnimateOnSetPoseOptions<TPose>): SceneAdapter<TNode, TPose>;
 
+/** How nodes enter and leave. `enterFrom` derives the pose a new node starts
+ *  at, given where it belongs; `exitTo` derives the pose a departing node
+ *  animates to before it is actually removed. Omit either to leave that
+ *  transition instant. */
 interface LifecycleAnimation<TPose> {
     /** Pose to animate the new object FROM at insert. */
     enterFrom?: (final: TPose) => TPose;
@@ -9026,11 +9485,14 @@ interface LifecycleAnimation<TPose> {
     easing?: EasingFn;
     geometry?: PoseProjection<TPose>;
 }
+/** Wrap an adapter so inserts and removals animate — the scene-graph
+ *  equivalent of CSS enter/leave transitions. */
 declare function animateLifecycle<TNode extends {
     id: string;
     pose?: TPose;
 }, TPose>(adapter: SceneAdapter<TNode, TPose>, animator: Animator, opts: LifecycleAnimation<TPose>): SceneAdapter<TNode, TPose>;
 
+/** Options for the `momentum` move behavior. */
 interface MomentumOptions {
     /** Required: the per-Canvas animator that will own the decay. */
     animator: Animator;
@@ -9067,10 +9529,24 @@ interface MomentumOptions {
      */
     boundary?: 'stop' | 'continue';
 }
+/**
+ * Move behavior that keeps a dragged node coasting after the pointer is
+ * released, at the velocity it was travelling, until friction brings it below
+ * `threshold`.
+ *
+ * Plugs into the move action rather than replacing it, so the drag itself is
+ * unchanged — this only decides what happens after the release. The whole
+ * flick, coast included, records as one undoable transform.
+ */
 declare function momentum<TPose>(opts: MomentumOptions): MoveBehavior<TPose>;
 
+/** Convert an 8-bit sRGB triple to OKLab. */
 declare function srgbU8ToOklab(r: number, g: number, b: number): [number, number, number];
+/** Convert OKLab back to an 8-bit sRGB triple, clamped into gamut. */
 declare function oklabToSrgbU8(L: number, A: number, B: number): [number, number, number];
+/** Blend two 8-bit sRGB colors through OKLab. Perceptually even, and it does
+ *  not pass through the muddy midpoints an sRGB blend produces between
+ *  complementary hues. */
 declare function lerpOklab(from: readonly [number, number, number], to: readonly [number, number, number], t: number): [number, number, number];
 /** Convert OKLab (L, a, b) to OKLCh (L, C, h). h is in radians, range [-π, π]. */
 declare function oklabToOklch(L: number, A: number, B: number): [number, number, number];
@@ -9081,6 +9557,9 @@ declare function oklchToOklab(L: number, C: number, h: number): [number, number,
  *  is taken from the other endpoint (avoids hue snap-from-undefined).
  *  h inputs are in radians. */
 declare function lerpOklch(from: readonly [number, number, number], to: readonly [number, number, number], t: number): [number, number, number];
+/** Which space a color blend is computed in. `'rgb'` is cheapest; `'oklab'`
+ *  is perceptually even; `'oklch'` additionally travels around the hue wheel
+ *  rather than through it. */
 type ColorSpace = 'rgb' | 'oklab' | 'oklch';
 /** Lerp a flat RGBA color array `from` toward `to`. Inputs are 0..1
  *  floats (the renderer's color space); outputs are 0..1 floats too.
@@ -9100,6 +9579,7 @@ declare function lerpColorArray(from: readonly number[], to: readonly number[],
  * when a custom color-space or shaping is needed.
  */
 type ColorInterpolate = (from: readonly number[], to: readonly number[], t: number) => number[];
+/** Options for `tweenVertexColors`. */
 interface TweenVertexColorsOptions {
     id: string;
     channel: VertexColorChannel;
@@ -9116,7 +9596,17 @@ interface TweenVertexColorsOptions {
     interpolate?: ColorInterpolate;
     onDone?: () => void;
 }
+/**
+ * Animate one node's per-anchor colors from `from` to `to` over `ms`.
+ *
+ * The colors are published to the animator's `colorOverrides` registry rather
+ * than written into the scene, so nothing is recorded in history and the
+ * node's own data is untouched; the override is dropped when the animation
+ * finishes. Starting another color animation on the same node and channel
+ * cancels this one.
+ */
 declare function tweenVertexColors(animator: Animator, opts: TweenVertexColorsOptions): AnimationHandle;
+/** Options for `springVertexColors`. */
 interface SpringVertexColorsOptions {
     id: string;
     channel: VertexColorChannel;
@@ -9132,7 +9622,10 @@ interface SpringVertexColorsOptions {
     interpolate?: ColorInterpolate;
     onDone?: () => void;
 }
+/** `tweenVertexColors` driven by a spring instead of a duration. Same override
+ *  semantics. */
 declare function springVertexColors(animator: Animator, opts: SpringVertexColorsOptions): AnimationHandle;
+/** Options for `cycleVertexColors`. */
 interface CycleVertexColorsOptions {
     id: string;
     channel: VertexColorChannel;
@@ -9144,6 +9637,9 @@ interface CycleVertexColorsOptions {
      *  progress `t` in 0..1; returns the blended array in 0..1 floats. */
     interpolate?: ColorInterpolate;
 }
+/** Removes an installed color cycle. Unlike the other color helpers this is
+ *  not an `AnimationHandle`, because a cycle has no progress to pause or
+ *  scale — it only ends. */
 interface CycleHandle {
     cancel(): void;
 }
@@ -9158,6 +9654,9 @@ interface CycleHandle {
  *  cycleVertexColors holds an `animator.keepAlive()` entry for the
  *  lifetime of the cycle; `cancel()` releases it. */
 declare function cycleVertexColors(animator: Animator, opts: CycleVertexColorsOptions): CycleHandle;
+/** Options for `staggerVertexColors`. `origin` picks which anchor the wave
+ *  starts from and `perAnchorDelay` how far behind each successive anchor
+ *  runs. */
 interface StaggerVertexColorsOptions {
     id: string;
     channel: VertexColorChannel;
@@ -9173,6 +9672,9 @@ interface StaggerVertexColorsOptions {
     interpolate?: ColorInterpolate;
     onDone?: () => void;
 }
+/** Run the same color change across a node's anchors as a wave, each anchor
+ *  starting later than the one before it. Same override semantics as
+ *  `tweenVertexColors`. */
 declare function staggerVertexColors(animator: Animator, opts: StaggerVertexColorsOptions): AnimationHandle;
 /** Build an n-anchor rainbow RGBA array sweeping the hue wheel. The
  *  output is suitable to pass directly into `stroke.vertexColors`,
@@ -9188,8 +9690,14 @@ declare function rainbowVertexColors(n: number, opts?: {
  *  `to`-target typically needs. */
 declare function solidVertexColors(n: number, r: number, g: number, b: number, a?: number): number[];
 
+/** Snap policy that never picks a target — every drop is rejected, which is
+ *  what a free-form container wants. */
 declare function none<TPose>(): LayoutSnap<TPose>;
+/** Snap policy that always picks the target closest to the pointer, however
+ *  far away it is. */
 declare function nearest<TPose>(): LayoutSnap<TPose>;
+/** Snap policy that picks the closest target, but only within `tolerance`
+ *  world units — beyond that the drop is rejected. */
 declare function nearestWithin<TPose>(opts: {
     tolerance: number;
 }): LayoutSnap<TPose>;
@@ -9211,6 +9719,7 @@ declare function containedThenNearest<TPose>(): LayoutSnap<TPose>;
  */
 declare function cellAt<TPose>(): LayoutSnap<TPose>;
 
+/** Options for `freeform`. */
 interface FreeformOptions<TPose> {
     snap?: LayoutSnap<TPose>;
 }
@@ -9222,6 +9731,7 @@ interface FreeformOptions<TPose> {
  */
 declare function freeform<TPose>(opts?: FreeformOptions<TPose>): LayoutStrategy<TPose>;
 
+/** Options for `tileGrid`. */
 interface TileGridOptions<TPose> {
     cols: number;
     rows: number;
@@ -9241,9 +9751,14 @@ interface TileGridOptions<TPose> {
         height: number;
     }, dragged: TPose): TPose;
 }
+/** Layout strategy that arranges children into a fixed grid of cells, one
+ *  child per cell. A drag reflows the others to make room, and the container
+ *  holds at most `cols × rows` children. */
 declare function tileGrid<TPose>(opts: TileGridOptions<TPose>): LayoutStrategy<TPose>;
 
+/** Which points within a container a child can snap to. */
 type SnapPattern = 'corners' | 'edges' | 'center' | 'grid';
+/** Options for `snapPoint`. */
 interface SnapPointOptions<TPose> {
     pattern: SnapPattern;
     /** Spacing for the 'grid' pattern, in world units. Default 50. */
@@ -9252,10 +9767,14 @@ interface SnapPointOptions<TPose> {
     tolerance?: number;
     snap?: LayoutSnap<TPose>;
 }
+/** A point in world coordinates. */
 type Pt = {
     x: number;
     y: number;
 };
+/** Layout strategy that leaves children where they are but offers a fixed set
+ *  of points — corners, edge midpoints, center, or a grid — for a dragged
+ *  child to land on. */
 declare function snapPoint<TPose extends Pt>(opts: SnapPointOptions<TPose>): LayoutStrategy<TPose>;
 
 /**
@@ -9372,11 +9891,17 @@ declare function HandIcon({ className, size }: IconProps): react_jsx_runtime.JSX
  *  inside — readable, debuggable, not hidden. */
 declare function UnknownIcon({ className, size }: IconProps): react_jsx_runtime.JSX.Element;
 
+/** Icon for the union operation: two overlapping circles merged into one filled shape. */
 declare function UnionIcon(): react_jsx_runtime.JSX.Element;
+/** Icon for the intersect operation: only the overlap of two circles filled. */
 declare function IntersectIcon(): react_jsx_runtime.JSX.Element;
+/** Icon for the subtract operation: the front circle removed from the back one. */
 declare function SubtractIcon(): react_jsx_runtime.JSX.Element;
+/** Icon for the exclude operation: both circles filled except their overlap. */
 declare function ExcludeIcon(): react_jsx_runtime.JSX.Element;
+/** Icon for the divide operation: two circles split into their separate regions. */
 declare function DivideIcon(): react_jsx_runtime.JSX.Element;
+/** Icon for the crop operation: the back shape clipped to the front one. */
 declare function CropIcon(): react_jsx_runtime.JSX.Element;
 
 /** What the registry knows at dispatch time. */
@@ -9416,6 +9941,7 @@ declare function scopeBindings(entries: Iterable<Contribution>, state: Eligibili
  */
 declare function mergeContributions(...bundles: readonly Contribution[][]): Contribution[];
 
+/** Appearance of the dashed box drawn during a marquee or insert drag. */
 interface InsertOverlayStyle {
     fill?: string;
     stroke?: string;