@weasel-js/core 1.0.1 → 1.0.3

package/dist/renderer.d.ts

@@ -1,9 +1,9 @@
-import { I as ImageMinification, G as GLImageCache } from './viewToMat3-BvaWCN99.js';
-export { V as ViewLike, v as viewToMat3 } from './viewToMat3-BvaWCN99.js';
+import { I as ImageMinification, G as GLImageCache } from './viewToMat3-CQW_YqDw.js';
+export { V as ViewLike, v as viewToMat3 } from './viewToMat3-CQW_YqDw.js';
 import { G as GradStop, S as Stroke } from './paint-types-CnLIzqq1.js';
 export { a as TextureHandle, r as registerTexture } from './paint-types-CnLIzqq1.js';
-import { M as Mat3, S as ShaderProgramHandle, D as DrawCommand } from './DrawCommand-DCmiNkBj.js';
-export { G as GroupDrawCommand, I as ImageDrawCommand, P as PathDrawCommand, a as ShaderDrawCommand, b as ShaderUniform, c as SolidPaint, T as TextDrawCommand, m as mat3, r as registerProgram } from './DrawCommand-DCmiNkBj.js';
+import { M as Mat3, S as ShaderProgramHandle, D as DrawCommand } from './DrawCommand-BbPrSTra.js';
+export { G as GroupDrawCommand, I as ImageDrawCommand, P as PathDrawCommand, a as ShaderDrawCommand, b as ShaderUniform, c as SolidPaint, T as TextDrawCommand, m as mat3, r as registerProgram } from './DrawCommand-BbPrSTra.js';
 import { P as Path } from './path-B6MMiodD.js';
 export { canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasFont, listFontOutlines, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, subscribeGlyphReady, unregisterCanvasFont, unregisterFontOutlines } from '@weasel-js/font';
 
@@ -16,6 +16,8 @@ export { canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasF
  * via the recorder Proxy without further special-casing.
  */
 type Stage = 'vertex' | 'fragment' | 'link';
+/** Thrown when a shader fails to compile or link, carrying which stage failed
+ *  and the driver's log. */
 declare class ShaderCompileError extends Error {
     readonly stage: Stage;
     readonly log: string;
@@ -109,6 +111,8 @@ declare class GLMeshCache {
     private readonly gl;
     private readonly aPositionLoc;
     private readonly map;
+    /** Meshes this context has drawn at least once; see `uploadRecurring`. */
+    private readonly seen;
     private readonly finalizer;
     private readonly pendingDeletes;
     /** Transient resources allocated this frame; freed at end of render(). */
@@ -123,6 +127,15 @@ declare class GLMeshCache {
      * and the FinalizationRegistry, so transient meshes never wait on GC.
      */
     uploadTransient(mesh: Mesh): GLMeshHandle;
+    /**
+     * Upload a Mesh that may or may not recur across frames. Its first sight in
+     * *this* context takes `uploadTransient`; every later one takes the
+     * persistent handle. One transient upload to find out is cheaper than
+     * stranding a persistent VAO on a mesh that never returns, whose release
+     * would wait on GC. The transient upload does not populate the persistent
+     * map, so steady-state reuse begins on the third frame.
+     */
+    uploadRecurring(mesh: Mesh): GLMeshHandle;
     /**
      * Free all transient resources allocated since the last call. Called by
      * the renderer at the end of each `render()`. Safe under context loss.
@@ -192,6 +205,8 @@ declare class GLTextureCache {
  * shader applies premultiplication before writing outColor.
  */
 
+/** Bake gradient stops into a 256-entry RGBA lookup strip, which the shader
+ *  samples instead of evaluating stops per fragment. */
 declare function buildGradientRamp(stops: GradStop[]): Uint8ClampedArray;
 declare class GradientRampCache {
     private readonly gl;
@@ -283,6 +298,9 @@ declare class SolidBatch {
     private growGpu;
 }
 
+/** How to construct a `WeaselRenderer`: the GL context or canvas to draw
+ *  into, the output size, and the quality knobs that separate screen
+ *  rendering from print. */
 interface WeaselRendererOptions {
     gl?: WebGL2RenderingContext;
     canvas?: HTMLCanvasElement;
@@ -315,6 +333,14 @@ interface WeaselRendererOptions {
      *  print has no reason to sample a field it could evaluate exactly). */
     textOutlineMinScreenSize?: number;
 }
+/**
+ * The WebGL2 renderer: takes a list of draw commands and paints them.
+ *
+ * It knows nothing about the scene — commands are the whole interface, which
+ * is what lets layers, HUD widgets and overlays all draw through the same
+ * pipeline. GPU resources (meshes, textures, gradient ramps) are cached across
+ * frames and keyed by identity, so re-issuing the same command is cheap.
+ */
 declare class WeaselRenderer {
     private readonly gl;
     private pathFill;
@@ -422,12 +448,18 @@ declare class WeaselRenderer {
     /** @internal */ _dpr(): number;
 }
 
+/** Options for `tessellate`. A smaller tolerance means more triangles and
+ *  smoother curves; it is in path-local units, so callers rendering at a
+ *  larger scale should tighten it. */
 interface TessellateOptions {
     /** Flatness tolerance for bezier subdivision in path-local units. */
     flattenTolerance?: number;
 }
+/** Turn a path into a triangle mesh the renderer can draw: curves flattened to
+ *  line segments, then the resulting polygon triangulated. */
 declare function tessellate(path: Path, opts?: TessellateOptions): Mesh;
 
+/** Options for stroke tessellation. */
 interface StrokeOptions {
     flattenTolerance?: number;
 }

package/dist/renderer.js

@@ -1,13 +1,12 @@
-export { IDENTITY_COLOR_MATRIX, OUTLINE_MIN_SCREEN_PX, ShaderCompileError, WeaselRenderer, buildGradientRamp, canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasFont, listFontOutlines, mat3, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, registerProgram, subscribeGlyphReady, tessellate, tessellateStroke, unregisterCanvasFont, unregisterFontOutlines, viewToMat3 } from './chunk-FVNWK7U3.js';
-import './chunk-DCIU3SRK.js';
-import './chunk-UB6A6L77.js';
-import './chunk-Z3KNFTTS.js';
-import './chunk-6SHZHXXR.js';
-import './chunk-775XXAHR.js';
+export { IDENTITY_COLOR_MATRIX, OUTLINE_MIN_SCREEN_PX, ShaderCompileError, WeaselRenderer, buildGradientRamp, canQueryLocalFonts, enableLocalFontOutlines, hasFontOutlines, isCanvasFont, listFontOutlines, mat3, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, registerProgram, subscribeGlyphReady, tessellate, tessellateStroke, unregisterCanvasFont, unregisterFontOutlines, viewToMat3 } from './chunk-SMCZRSYB.js';
+import './chunk-TR3HZN34.js';
+import './chunk-3KGMJMOS.js';
+import './chunk-3JYFAQIB.js';
+import './chunk-U45SODC2.js';
+import './chunk-JOSUVS6C.js';
 import './chunk-UGFFCMQP.js';
 import './chunk-BHVYVFGV.js';
 import './chunk-GVCNT7UH.js';
-export { registerTexture } from './chunk-IO5Z75X4.js';
-import './chunk-PZ5AY32C.js';
+export { registerTexture } from './chunk-HGF5X6MZ.js';
 //# sourceMappingURL=renderer.js.map
 //# sourceMappingURL=renderer.js.map

package/dist/resize.d.ts

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

package/dist/resize.js

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

package/dist/routing.d.ts

@@ -1,16 +1,115 @@
-export { bd as Conflict, be as PREDICATE_TARGET, bf as RegistryEntry, bg as ToolDef, m as ToolKeybinding, bh as ToolScopes, bi as ViewportToolDef, bj as buildRouteRegistry, bk as defineTool, bl as defineViewportTool, bm as findConflicts, bn as findScopedConflicts, bo as formatConflict, bp as reportRouteConflicts } from './index-DPI8DV0A.js';
+import { ParsedModifiers, GestureName, GestureSpec } from '@weasel-js/gestures';
 export { ChannelRef, DescribeRouteOptions, GESTURE_DESCRIPTORS, GestureArgSpec, GestureDescriptor, GestureName, ModRequirement, ModifierKey, ParsedModifiers, ParsedRoute, PhaseAtom, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, RouteDescriptionPart, RouteFieldName, RouteTermLabel, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute } from '@weasel-js/gestures';
-import './types-Kh_osAq9.js';
+import { T as Tool } from './registry-CxnkXbG8.js';
+import './types-vqxpCFVp.js';
 import '@weasel-js/history';
 import './path-B6MMiodD.js';
-import './types-BhJJ2OCM.js';
-import './types-B_-khFM0.js';
+import './types-ByZxoD6P.js';
+import './types-DpQ0cWYC.js';
 import './view-DSQgxBJB.js';
 import '@weasel-js/modes';
 import 'react';
-import './geometry-DVeZ2i-c.js';
+import './geometry-5X6TrAkX.js';
 import './paint-types-CnLIzqq1.js';
-import './DrawCommand-DCmiNkBj.js';
+import './DrawCommand-BbPrSTra.js';
 import 'react/jsx-runtime';
+import './types-BHK2dkMu.js';
 import '@weasel-js/geom';
-import './types-BJ8_cyT7.js';
+
+/**
+ * One row in the route registry — a single `GestureBinding` on one tool,
+ * flattened into the route grammar's vocabulary so the inspector, the
+ * conflict checker, and `describeRoute` can all read the same shape.
+ *
+ * Multiple rows can share (gesture, arg, target, modifiers) if different tools
+ * declare them; consumers walk the list and group client-side.
+ */
+interface RegistryEntry {
+    toolId: string;
+    /** Which phase the binding's `phase` spec restricts it to. `'any'` when it
+     *  declares none, declares `'*'`, or declares an atom list whose atoms
+     *  don't agree on one phase — such a binding fires in either phase, and
+     *  reporting it as `'initial'` made it collide with genuinely-initial
+     *  bindings in `findConflicts`' bucket key. */
+    phase: 'initial' | 'engaged' | 'any';
+    /** Structured v3 modifier requirements. Empty object = "no modifiers
+     *  held" (the strict default). */
+    modifiers: ParsedModifiers;
+    gesture: GestureName;
+    /** Resolved arg value for arg-bearing gestures (wheel direction,
+     *  key name, multiTouchTap fingers). Undefined for gestures whose
+     *  descriptor has no `arg`. */
+    arg: string | undefined;
+    /** Target class for hit-testing gestures. `undefined` when the descriptor
+     *  has `hasTarget: false` or the spec declares no target;
+     *  {@link PREDICATE_TARGET} when the spec uses a `kindOf` predicate, which
+     *  the route grammar has no notation for. */
+    target: string | undefined;
+    /** The action this binding fires. */
+    actionId: string;
+    /** The `GestureSpec` this row was flattened from, by reference. Reflection
+     *  consumers that need something the grammar doesn't capture — the
+     *  specificity tuple, a `kindOf` predicate identity — read it here rather
+     *  than re-walking `Tool.bindings`. */
+    spec: GestureSpec;
+}
+/**
+ * Flatten every tool's `bindings` into route-registry rows.
+ *
+ * This was `buildActionRegistry`, and it walked `ToolDef.initial` /
+ * `.engaged` phase tables — the grammar that no longer exists. It was also
+ * blind to `Tool.bindings` the entire time the two lived side by side, which
+ * is why the inspector under-reported select by more than half. The rename
+ * fixes a second thing: it never had anything to do with the Actions
+ * Registry, and reading `buildActionRegistry` next to `ActionsRegistry`
+ * suggested otherwise.
+ */
+declare function buildRouteRegistry(tools: readonly Tool<unknown>[]): RegistryEntry[];
+
+/** Two or more tools declare the same exact (phase, gesture, arg, target,
+ *  modifiers) tuple — the dispatcher's slot precedence picks one
+ *  arbitrarily (well, deterministically by slot order, but the author
+ *  probably didn't intend the duplication). */
+interface Conflict {
+    phase: 'initial' | 'engaged' | 'any';
+    gesture: GestureName;
+    arg: string | undefined;
+    target: string | undefined;
+    modifiers: ParsedModifiers;
+    /** All tool ids that registered the same tuple. At least 2 by
+     *  construction. Order matches the input tools[] order. */
+    toolIds: string[];
+}
+/** Detect exact-tuple overlaps across a tool registration set.
+ *
+ *  Intentionally NOT flagged:
+ *  - Broad vs. narrow targets (e.g. an untargeted `click` alongside
+ *    `click` on `empty`) — the dispatcher's specificity ordering resolves
+ *    those cleanly, and the broad one is usually the intended fallback.
+ *  - Different modifier requirements on the same target — they fire on
+ *    different inputs.
+ *  - A binding whose action declines via `enabled()` so a lower-priority
+ *    one can take the gesture. Detecting that intent would mean evaluating
+ *    the action; consumers can suppress known-intentional compositions in
+ *    their UI layer.
+ *
+ *  - Two `{ kindOf }` predicate targets. The route grammar renders every
+ *    predicate as the single token {@link PREDICATE_TARGET}, so bucketing on
+ *    the rendered target alone reported select's `resize` / `rotate` / `move`
+ *    drags — three genuinely different predicates — as a three-way conflict.
+ *    Predicate entries bucket by function identity instead, which means two
+ *    *separately written but equivalent* predicates go unflagged. That's the
+ *    right way to be wrong here: this check has to be silent when nothing is
+ *    wrong or nobody will keep it on.
+ *
+ *  Note that two bindings sharing a tuple on the SAME tool are now possible
+ *  (bindings are an array, where phase tables were objects with unique
+ *  keys) — so a conflict may name one tool twice.
+ *
+ *  This is the raw same-tuple detector. Feeding it a whole tool *registry*
+ *  over-reports, because registry tools take turns in the active slot and
+ *  can't collide with each other — see {@link findScopedConflicts}.
+ */
+declare function findConflicts(tools: readonly Tool<unknown>[]): Conflict[];
+
+export { type Conflict, type RegistryEntry, buildRouteRegistry, findConflicts };

package/dist/routing.js

@@ -1,4 +1,3 @@
-export { GESTURE_DESCRIPTORS, PREDICATE_TARGET, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, buildRouteRegistry, canonicalModifiers, collapseShiftPairs, defineTool, defineViewportTool, describeRoute, describeRouteParts, findConflicts, findScopedConflicts, formatConflict, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute, reportRouteConflicts } from './chunk-DCIU3SRK.js';
-import './chunk-PZ5AY32C.js';
+export { GESTURE_DESCRIPTORS, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, buildRouteRegistry, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, findConflicts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute } from './chunk-TR3HZN34.js';
 //# sourceMappingURL=routing.js.map
 //# sourceMappingURL=routing.js.map

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

@@ -16,8 +16,14 @@ interface DebugConfig {
     fps?: boolean;
     /** Optional per-feature color overrides; falls back to the default theme. */
     theme?: Partial<DebugTheme>;
+    /** Optional per-feature line-width / dash overrides; falls back to
+     *  {@link DEFAULT_DEBUG_STROKES}. */
+    strokes?: Partial<DebugStrokes>;
 }
+/** The name of one debug-overlay feature — the keys of {@link DebugConfig}
+ *  that toggle a visualization. */
 type DebugFeature = 'hitboxes' | 'handles' | 'bounds' | 'origins' | 'snap' | 'layers' | 'ids' | 'fps';
+/** Colors the debug overlay draws with, one entry per feature. */
 interface DebugTheme {
     hitboxFill: string;
     hitboxStroke: string;
@@ -33,7 +39,26 @@ interface DebugTheme {
     fpsText: string;
     fpsTextBg: string;
 }
+/** Line width and dash pattern for one stroked debug feature. An empty (or
+ *  omitted) `dash` is a solid line. */
+interface DebugStroke {
+    width: number;
+    dash?: readonly number[];
+}
+/** The stroked half of the debug overlay's appearance, split from
+ *  {@link DebugTheme} because only some features draw a line at all — text
+ *  panels and filled origin dots take color and nothing else. */
+interface DebugStrokes {
+    hitbox: DebugStroke;
+    bounds: DebugStroke;
+    handle: DebugStroke;
+    /** Rejected snap candidates only; accepted ones paint as a filled dot. */
+    snap: DebugStroke;
+}
+/** Which kind of handle a recorded handle marker represents. */
 type HandleKind = 'corner' | 'rotation' | 'anchor';
+/** The geometry a hit region actually tests against, as reported to the debug
+ *  sink so the overlay can draw the real shape rather than its bounding box. */
 type HitShape = {
     kind: 'rect';
     x: number;
@@ -50,11 +75,13 @@ type HitShape = {
     kind: 'path';
     d: Path2D;
 };
+/** A hit region tested during the current frame. */
 interface RecordedHitbox {
     id: string;
     kind: 'body' | 'handle' | 'rotation' | 'anchor';
     shape: HitShape;
 }
+/** A handle drawn during the current frame, and where. */
 interface RecordedHandle {
     id: string;
     position: {
@@ -63,6 +90,7 @@ interface RecordedHandle {
     };
     kind: HandleKind;
 }
+/** A node's bounds as computed during the current frame. */
 interface RecordedBounds {
     id: string;
     bounds: {
@@ -72,6 +100,7 @@ interface RecordedBounds {
         height: number;
     };
 }
+/** A node's transform origin as used during the current frame. */
 interface RecordedOrigin {
     id: string;
     point: {
@@ -79,6 +108,9 @@ interface RecordedOrigin {
         y: number;
     };
 }
+/** A snap candidate considered during the current gesture, and whether it
+ *  won. Unlike the other records these survive across frames, until the
+ *  gesture ends. */
 interface RecordedSnap {
     point: {
         x: number;
@@ -86,12 +118,14 @@ interface RecordedSnap {
     };
     accepted: boolean;
 }
+/** A render layer that drew during the current frame. */
 interface RecordedLayer {
     id: string;
     label: string;
     space: 'world' | 'screen';
     index: number;
 }
+/** Everything the sink collected, ready for the overlay to draw. */
 interface DebugSnapshot {
     hitboxes: RecordedHitbox[];
     handles: RecordedHandle[];
@@ -100,6 +134,14 @@ interface DebugSnapshot {
     snap: RecordedSnap[];
     layers: RecordedLayer[];
 }
+/**
+ * Where the kit reports what it is doing so the debug overlay can draw it.
+ *
+ * Recording is push-based and cheap: hit-testers, handle painters and snap
+ * strategies call these as they run, whether or not any overlay is watching.
+ * Nothing here affects behavior — a sink that discards everything is a valid
+ * sink.
+ */
 interface DebugSink {
     recordHitbox(id: string, kind: 'body' | 'handle' | 'rotation' | 'anchor', shape: HitShape): void;
     recordHandle(id: string, position: {
@@ -127,4 +169,4 @@ interface DebugSink {
     clearSnap(): void;
 }
 
-export type { DebugSink as D, HandleKind as H, RecordedBounds as R, DebugConfig as a, DebugSnapshot as b, DebugTheme as c, DebugFeature as d, HitShape as e, RecordedHandle as f, RecordedHitbox as g, RecordedLayer as h, RecordedOrigin as i, RecordedSnap as j };
+export type { DebugSink as D, HandleKind as H, RecordedBounds as R, DebugConfig as a, DebugSnapshot as b, DebugStrokes as c, DebugTheme as d, DebugFeature as e, DebugStroke as f, HitShape as g, RecordedHandle as h, RecordedHitbox as i, RecordedLayer as j, RecordedOrigin as k, RecordedSnap as l };

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

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

package/dist/{types-B_-khFM0.d.ts → types-DpQ0cWYC.d.ts}

@@ -1,15 +1,20 @@
 import { Op } from '@weasel-js/history';
 
+/** A layout container's extent in world units. */
 type ContainerBounds = {
     x: number;
     y: number;
     width: number;
     height: number;
 };
+/** A child a layout strategy is arranging. */
 interface LayoutChild<TPose> {
     id: string;
     pose: TPose;
 }
+/** One place a dragged child could land. A strategy offers these as the drag
+ *  moves, a `LayoutSnap` picks between them, and the chosen one decides both
+ *  the preview and the committed poses. */
 interface DropTarget<TPose> {
     /** Where the dragged child lands if this target is picked. */
     pose: TPose;
@@ -33,16 +38,22 @@ interface DropTarget<TPose> {
     /** Strategy-private metadata (e.g. cell coords for tile-grid). */
     meta?: unknown;
 }
+/** Chooses which of a strategy's drop targets the pointer means, or `null`
+ *  to reject the drop. Separate from the strategy so the same arrangement can
+ *  be paired with different snapping rules. */
 interface LayoutSnap<TPose> {
     pickTarget(targets: DropTarget<TPose>[], pointer: {
         x: number;
         y: number;
     }): DropTarget<TPose> | null;
 }
+/** The container a layout strategy is arranging children within. */
 interface LayoutContainer {
     id: string;
     bounds: ContainerBounds;
 }
+/** The child currently being dragged: where it started, where the pointer
+ *  currently proposes it goes, and which container it came from. */
 interface LayoutDragged<TPose> {
     id: string;
     /** The pose the dragged child currently has (pre-drop). */
@@ -51,6 +62,15 @@ interface LayoutDragged<TPose> {
     pose: TPose;
     sourceContainerId: string | null;
 }
+/**
+ * How a container arranges its children, and what happens when one is dragged
+ * into or around it.
+ *
+ * The four required methods cover the whole cycle: `childPoses` is the resting
+ * arrangement, `getDropTargets` enumerates where a drag could land,
+ * `reflowPoses` is the live preview once a target is picked, and `commitDrop`
+ * turns the result into ops so the drop is undoable.
+ */
 interface LayoutStrategy<TPose> {
     childPoses(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>): Map<string, TPose>;
     getDropTargets(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>): DropTarget<TPose>[];
@@ -66,6 +86,12 @@ interface LayoutStrategy<TPose> {
         x: number;
         y: number;
     }): boolean;
+    /** Optional: reject a drag before any drop-target work happens. A type-aware
+     *  container (a palette that only takes swatches, say) returns `false` and
+     *  the drag falls through to whatever container is under it next. When
+     *  absent, every drag is considered — rejection is still possible later, by
+     *  `snap.pickTarget` returning null. */
+    acceptsDrop?(container: LayoutContainer, dragged: LayoutDragged<TPose>): boolean;
 }
 
 /**
@@ -134,6 +160,12 @@ interface MoveAdapter<TNode extends {
      *  targeting (`getLayout` present), nested-hit collapse
      *  (`pickTopMostHit`), and group-pose composition. Flat scenes may omit. */
     getParent?(id: string): string | null;
+    /** Optional paint depth, read by `pickTopMostHit` to resolve two *siblings*
+     *  whose bodies both cover the pointer. Without it the hit list's own order
+     *  decides, which is right for a back-to-front walk and wrong for anything
+     *  else. See `PickTopMostHitAdapter` for the `compareZ` alternative. */
+    getZIndex?(id: string): number | null | undefined;
+    compareZ?(a: string, b: string): number;
     setPose(id: string, pose: TPose): void;
     /** Optional. Used only by reparent ops (e.g. drag-into-container drops via
      *  layout strategies). Flat scenes that never reparent may omit. */

package/dist/{types-Kh_osAq9.d.ts → types-vqxpCFVp.d.ts}

@@ -80,9 +80,13 @@ interface NodeBase<TData, TLayer extends string, TPose> {
     data: TData;
     parent: NodeId | null;
 }
+/** A node with no children — a shape, a label, an image. */
 interface LeafNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
     kind: 'leaf';
 }
+/** A node with an ordered list of children. This is the real group: what
+ *  Cmd+G creates, what SVG `<g>` round-trips to. A container has its own pose,
+ *  which its children's poses are relative to, and may optionally clip them. */
 interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
     kind: 'container';
     children: NodeId[];
@@ -93,20 +97,30 @@ interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends
      *  paints descendants only where it covers. */
     clipFromPose?: (pose: TPose) => Path | null;
 }
+/** A node in the scene tree: either a leaf or a container. Re-exported
+ *  publicly as `SceneNode`, to avoid colliding with the DOM's `Node`. */
 type Node<TData, TLayer extends string, TPose = RectPose> = LeafNode<TData, TLayer, TPose> | ContainerNode<TData, TLayer, TPose>;
 interface LayerRecordBase<TLayer extends string> {
     id: TLayer;
     visible: boolean;
     locked: boolean;
 }
+/** A layer declared when the scene was created. Fixed set, no display name —
+ *  these are the kit's own render bands, not something a user manages. */
 interface SystemLayerRecord<TLayer extends string> extends LayerRecordBase<TLayer> {
     kind: 'system';
 }
+/** A layer the user created and can rename, reorder or delete. */
 interface UserLayerRecord<TLayer extends string> extends LayerRecordBase<TLayer> {
     kind: 'user';
     name: string;
 }
+/** Per-layer metadata held by the scene: whether it is visible and locked,
+ *  and where it sits in the render stack. Distinct from a node's `layer` tag,
+ *  which merely names one of these. */
 type LayerRecord<TLayer extends string> = SystemLayerRecord<TLayer> | UserLayerRecord<TLayer>;
+/** What `Scene.add` needs to mint a node. Everything except the id is
+ *  required; the id is generated unless one is supplied. */
 interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
     kind: 'leaf' | 'container';
     layer: TLayer;
@@ -120,10 +134,13 @@ interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
      *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */
     clipFromPose?: (pose: TPose) => Path | null;
 }
+/** A custom scene mutation registered with `Scene.registerOp`: how to apply
+ *  it and how to undo it. The pair is what makes it participate in history. */
 interface RegisteredOp<P> {
     apply: (payload: P) => void;
     revert: (payload: P) => void;
 }
+/** One of the layers a scene is created with. */
 interface SystemLayerSpec<TLayer extends string> {
     id: TLayer;
     visible?: boolean;
@@ -171,6 +188,8 @@ interface SceneRegistry<TPose> {
     /** Maps registry keys to `clipFromPose` factory functions for container nodes. */
     clipFromPose?: Readonly<Record<string, (pose: TPose) => Path | null>>;
 }
+/** Options for `useScene` — the layers the scene has, what it starts out
+ *  holding, and how its history behaves. */
 interface UseSceneOptions<TData, TLayer extends string, TPose = RectPose> {
     systemLayers: readonly SystemLayerSpec<TLayer>[];
     initial?: readonly AddNodeSpec<TData, TLayer, TPose>[];
@@ -204,6 +223,18 @@ interface UseSceneOptions<TData, TLayer extends string, TPose = RectPose> {
      *  wire it after construction via `scene.setActiveJournalAccessor(fn)`. */
     getActiveJournal?: () => _weasel_js_history.Journal | null;
 }
+/**
+ * The kit-owned scene tree: nodes, layers, and the undo history over both.
+ *
+ * A scene is logical, not visual — it says what exists and where, and nothing
+ * about how it is painted. Every mutating method is undoable, and reads are
+ * snapshots rather than live views. Nodes are addressed by `NodeId`; hold ids
+ * across mutations, not node objects.
+ *
+ * Three type parameters keep it domain-agnostic: `TData` is the app's payload,
+ * which the kit never inspects; `TPose` is the transform shape, `RectPose` by
+ * default; `TLayer` is the union of layer names.
+ */
 interface Scene<TData, TLayer extends string, TPose = RectPose> {
     readonly nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>;
     readonly roots: readonly NodeId[];

package/dist/{viewToMat3-BvaWCN99.d.ts → viewToMat3-CQW_YqDw.d.ts}

@@ -1,4 +1,4 @@
-import { M as Mat3 } from './DrawCommand-DCmiNkBj.js';
+import { M as Mat3 } from './DrawCommand-BbPrSTra.js';
 
 /**
  * GL texture upload cache for ImageBitmap objects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/core",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Domain-agnostic 2D scene graph primitives for React: viewport math, drag/resize/insert/clone interactions, layered canvas rendering.",
   "license": "MIT",
   "author": "orochi235",
@@ -74,11 +74,11 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@weasel-js/font": "1.0.1",
-    "@weasel-js/geom": "1.0.1",
-    "@weasel-js/gestures": "1.0.1",
-    "@weasel-js/history": "1.0.1",
-    "@weasel-js/modes": "1.0.1",
+    "@weasel-js/font": "1.0.3",
+    "@weasel-js/geom": "1.0.3",
+    "@weasel-js/gestures": "1.0.3",
+    "@weasel-js/history": "1.0.3",
+    "@weasel-js/modes": "1.0.3",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7"
   },