@weasel-js/labkit 0.1.0 → 0.7.1

package/dist/_dts/{fitViewToBounds-rWrBI4a6.d.ts → DrawCommand-CEvS5AdV.d.ts}

@@ -32,6 +32,10 @@ interface Op {
     args?: unknown;
 }
 
+interface BeginJournalOptions {
+    label: string;
+    targetId?: string;
+}
 interface Journal {
     readonly targetId: string | undefined;
     readonly forkedAtEntryId: number;
@@ -96,6 +100,77 @@ interface HistoryEntry {
      *  restored from an older snapshot that predates this field. */
     touchedIds?: ReadonlySet<string>;
 }
+/** Op-batched undo/redo controller returned by `createHistory`. */
+interface History {
+    apply(op: Op, label?: string): void;
+    applyOps(ops: Op[], label: string): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Number of entries on the undo stack (O(1); `entries().undo.length`
+     *  without materializing the views). */
+    undoDepth(): number;
+    /** Number of entries on the redo stack (O(1)). */
+    redoDepth(): number;
+    clear(): void;
+    /** Snapshot of the current undo + redo stacks. `undo` is oldest→newest
+     *  (i.e. the last element is what `undo()` would pop next); `redo` is
+     *  also oldest→newest from the user's perspective (i.e. the *first*
+     *  element is what `redo()` would pop next — see implementation note).
+     *  Callers should treat the arrays as immutable. */
+    entries(): {
+        undo: HistoryEntry[];
+        redo: HistoryEntry[];
+    };
+    /** Walk the history forward/back until exactly `n` entries are on the
+     *  undo stack (0 ≤ n ≤ entries().undo.length + entries().redo.length).
+     *  Equivalent to repeated `undo()`/`redo()` calls but doesn't bother
+     *  rebuilding entry snapshots between steps. No-op if already at `n`. */
+    goto(n: number): void;
+    /** Monotonic counter bumped on every push/undo/redo/clear/coalesce.
+     *  Cheap to read; callers use it as a React dep to detect changes. */
+    getVersion(): number;
+    /** Subscribe to history changes. Fires after every push/undo/redo/
+     *  clear/coalesce. Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Snapshot the undo + redo stacks in a structured-clone-safe form.
+     *  Entries whose ops aren't all kit-registered (i.e. any op missing a
+     *  `name`) are dropped from the snapshot with a debug-level log — they
+     *  can't round-trip, so we omit them rather than emit a half-restorable
+     *  entry. The in-memory stacks aren't modified. */
+    serialize(): SerializedHistory;
+    /** Replace the current undo + redo stacks with the deserialized contents
+     *  of `snapshot`. Ops are rebuilt via the `rebuildOp` option when
+     *  provided, then the global registry; unknown names become no-op
+     *  placeholders so stack ordering survives across kit-version skew.
+     *  Bumps `version` and notifies subscribers exactly once. */
+    restore(snapshot: SerializedHistory): void;
+    /** Push an entry whose ops have already been applied to the adapter.
+     *  Unlike `applyOps`, does NOT call `op.apply()`. Used by Journal.commit
+     *  to flush a session's net forward ops to the parent as one entry without
+     *  re-mutating the scene. */
+    recordEntry(ops: Op[], label: string): void;
+    /** Concatenated forwardOps of every undo-stack entry, in order. Snapshot
+     *  of "what changes are currently applied via this history" — useful for
+     *  Journal.commit to flush to a parent, and for any caller that wants to
+     *  diff against a baseline. */
+    allForwardOps(): Op[];
+    /** The id that will be assigned to the *next* pushed entry. Stable
+     *  monotonic counter; callers use it to tag a fork point (see Journal). */
+    currentEntryId(): number;
+    /** Open a scoped sub-history. All apply/undo/redo on the returned Journal
+     *  affect the same adapter; on commit, the Journal's net forward ops are
+     *  flushed to this History as one entry. See spec docs/superpowers/specs/
+     *  2026-05-24-modality-design.md for the full lifecycle. */
+    beginJournal(opts: BeginJournalOptions): Journal;
+    /** Re-activate a suspended journal. Throws if the journal was committed or
+     *  cancelled (those are terminal). Staleness checking is the caller's
+     *  responsibility — consult `journal.forkedAtEntryId` against
+     *  `currentEntryId()` and your own op-semantic rules to decide whether
+     *  to resume or discard before calling this. */
+    resumeJournal(journal: Journal): void;
+}
 
 /**
  * Pose composition for hierarchical scene graphs.
@@ -133,6 +208,14 @@ interface RectPose {
     /** Rotation in radians around the unrotated AABB center. Absent === 0. */
     rotation?: number;
 }
+/** Consumer's pose-composition strategy for hierarchical scenes. `compose`
+ *  folds a child's pose (in parent's frame) up to the next frame; `decompose`
+ *  is its inverse. Default is IDENTITY — an absolute-pose scene where every
+ *  node already stores world coords (parent is grouping-only, no transform). */
+interface PoseComposition<TPose> {
+    compose: (parent: TPose, child: TPose) => TPose;
+    decompose: (parent: TPose, world: TPose) => TPose;
+}
 
 /** Fill rule used by polygon path hit-testing and `ctx.fill()`. */
 type PathFillRule = 'nonzero' | 'evenodd';
@@ -475,6 +558,26 @@ interface View {
     };
 }
 
+/**
+ * Axis-aligned rectangle in world space. Kit-wide `Bounds` shape used by
+ * selection, group, and viewport helpers. The optional `rotation` field
+ * (radians, around the AABB center) lets selection chrome attach a rotated
+ * orientation to an otherwise axis-aligned rect without needing a parallel
+ * type.
+ */
+interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+}
+/** Pixel dimensions of the canvas viewport. */
+interface ViewportDims {
+    width: number;
+    height: number;
+}
+
 /**
  * 2D affine matrix utilities. Column-major 9-element Float32Array, matching
  * `WebGL2RenderingContext.uniformMatrix3fv` byte order so we can pass the
@@ -682,6 +785,12 @@ interface TextStyle {
     selectionBackground?: string;
     /** Selection text color paired with `selectionBackground`. Default: inherits text color. */
     selectionColor?: string;
+    /** Extra advance added after each glyph, in world units. Default 0. */
+    letterSpacing?: number;
+    /** Default `false`. */
+    underline?: boolean;
+    /** Default `false`. */
+    strikethrough?: boolean;
 }
 
 /**
@@ -692,8 +801,14 @@ interface TextStyle {
  *
  * `bold`/`italic` toggles on a run are folded into `fontWeight`/`fontStyle`:
  * `bold: true` → fontWeight 700, `italic: true` → fontStyle 'italic'.
- * Explicit `fontFamily` / `fontSize` / `fill` on the run override the
- * node-level value.
+ * Explicit `fontFamily` / `fontSize` / `fill` / `letterSpacing` on the run
+ * override the node-level value (`letterSpacing: 0` on a run is an override,
+ * not an absence — it zeroes inherited tracking).
+ *
+ * `underline` / `strikethrough` are *additive*, like `bold`/`italic`: a run
+ * can turn a decoration on but never off, so they resolve as
+ * `run.x || style.x` and not `run.x ?? style.x`. See the header of
+ * `runs/rangeStyle.ts` for why the model collapses the tri-state.
  */
 
 interface ResolvedRun {
@@ -703,6 +818,12 @@ interface ResolvedRun {
     fontWeight: number;
     fontStyle: 'normal' | 'italic';
     fill: FillStyle;
+    /** Extra advance added after each glyph of this run, in world units. */
+    letterSpacing: number;
+    /** Draw a rule below this run's baseline. Additive over the node style. */
+    underline: boolean;
+    /** Draw a rule through this run's x-height. Additive over the node style. */
+    strikethrough: boolean;
 }
 
 /**
@@ -847,24 +968,4 @@ interface ShaderDrawCommand {
     };
 }
 
-/**
- * Axis-aligned rectangle in world space. Kit-wide `Bounds` shape used by
- * selection, group, and viewport helpers. The optional `rotation` field
- * (radians, around the AABB center) lets selection chrome attach a rotated
- * orientation to an otherwise axis-aligned rect without needing a parallel
- * type.
- */
-interface Bounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    rotation?: number;
-}
-/** Pixel dimensions of the canvas viewport. */
-interface ViewportDims {
-    width: number;
-    height: number;
-}
-
-export type { Bounds as B, DrawCommand as D, Node as N, Op as O, PathDrawCommand as P, Scene as S, View as V, ViewportDims as a, NodeId as b };
+export type { Bounds as B, DrawCommand as D, History as H, Node as N, Op as O, PathDrawCommand as P, Scene as S, View as V, ViewportDims as a, NodeId as b, Path as c, PoseComposition as d };