agentfootprint-lens 0.54.0 → 0.56.0

package/README.md

@@ -812,6 +812,41 @@ const href = to.ok ? `/runs/${runId}?step=${to.step}` : undefined;
 
 ---
 
+### One cursor across several lenses: `useSharedCursor`
+
+A debug tool that mounts Why, Flow, Context and the Skill Graph over one
+recording keeps ONE cursor. The lenses draw different axes — Flow every
+commit, Why and Context the agent's milestones — so what the host holds must
+be an ADDRESS on the record, not a step on an axis. `useSharedCursor` holds
+that address and hands each lens a `LensCursor` for the axis it draws:
+
+```tsx
+import { useSharedCursor, Lens, ContextView } from 'agentfootprint-lens';
+
+const shared = useSharedCursor(recorder);
+
+// Reads the address on the milestone axis; a click here moves the address.
+<ContextView runner={recording} cursor={shared.forAxis('group')} />
+
+// The Lens on the same owner (0.56.0): it derives its own step over
+// whatever axis it draws — pick tags, drill, change granularity — and every
+// mover in it moves the shared address.
+<Lens recorder={recorder} granularity="step" shared={shared} />
+
+// A view still on the older step + report contract, bridged into the same
+// address — so a Skill Graph transport keeps working while you migrate one
+// lens at a time.
+<SkillGraphDebugger step={shared.forAxis('step').at.step} onStepChange={shared.onStepChange} … />
+```
+
+The law: a tab DERIVES its step from the address (the exact stage when its
+axis has it, else the stop that contains the commit); only a MOVER changes
+the address; a visit to a coarser axis and back lands on the same commit.
+With no move yet the address is the run's end, from which each axis derives
+its own last stop; a new recorder drops the held address. Headless pieces on
+`/core`: `stepForAddress`, `cursorForAddress`, `addressOf`. Design and the
+facts the fixtures taught: docs/design/2026-09-shared-cursor.md.
+
 ## Time travel through one port
 
 **Nothing to do — this is how the cursor already moves.** Read it if you are

package/dist/{Lens-DHmINGvn.d.cts → Lens-Bt2Rh-aq.d.cts}

@@ -3,8 +3,8 @@ import { ToolChoiceCall, ToolChoiceSummary } from 'agentfootprint/observe';
 import * as agentfootprint from 'agentfootprint';
 import { CommentaryTemplates } from 'agentfootprint';
 import React__default, { Ref } from 'react';
-import { a as LensCursorReading, C as CursorPosition, L as LensCursor, e as NavigationResult, h as LensRecorder } from './lensCursor-BQyMCkdo.cjs';
-import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-Dh-lINvw.cjs';
+import { a as LensCursorReading, C as CursorPosition, L as LensCursor, h as LensRecorder, e as NavigationResult } from './lensCursor-BQyMCkdo.cjs';
+import { C as ChartGroupHighlight, c as LensCursorPort, z as CursorAddress, H as Humanizer, b as BookmarkStore } from './tagAxis-4LDsCmxZ.cjs';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -241,6 +241,26 @@ interface UseLensCursorResult {
 declare function clampStep(n: number, maxStep: number): number;
 declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, positions, }: UseLensCursorArgs): UseLensCursorResult;
 
+type SharedAxis = 'step' | 'group';
+interface SharedCursor {
+    /** The held address — `undefined` until a move, when the default (the run's end) applies. */
+    readonly address: CursorAddress | undefined;
+    /** The `LensCursor` a lens drawing this axis reads; its `moveTo` moves the shared address. */
+    forAxis(granularity: SharedAxis, drillPath?: readonly string[]): LensCursor;
+    /**
+     * The general form (0.56.0): the `LensCursor` over ANY positions a view
+     * draws — a tag-filtered axis, a drilled one — read under `drillPath`.
+     * `forAxis` is this over the library's own two axes. Same positions, same
+     * address → the same object, so a memo keyed on it holds.
+     */
+    over(positions: readonly CursorPosition[], drillPath?: readonly string[]): LensCursor;
+    /** Move the ONE cursor to an address — what every mover ends in. */
+    moveTo(address: CursorAddress): void;
+    /** The older contract, bridged: a `<Lens onStepChange>` or a transport reporting a step lands here. */
+    onStepChange(step: number, at: LensCursorAt): void;
+}
+declare function useSharedCursor(recorder: LensRecorder | undefined): SharedCursor;
+
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.
  *
@@ -603,6 +623,24 @@ interface LensProps {
      * Memoize via `useCallback` to avoid downstream re-renders.
      */
     readonly onStepChange?: (step: number, at: LensCursorAt) => void;
+    /**
+     * The HOST's one cursor across every lens it mounts (0.56.0) — the owner
+     * `useSharedCursor(recorder)` hands back. Pass it and this lens derives its
+     * own step over whatever axis it is drawing (the commit axis, the milestone
+     * axis, a tag-filtered one, a drilled one) from the shared ADDRESS, and
+     * every mover here — the strip, ◀ ▶, a chart click, `navigatorRef` — moves
+     * that address. `step` is ignored while `shared` is given; `onStepChange`
+     * still fires as an observation hook. A correction the lens makes on its
+     * own (`at.clamped`, an address this axis cannot hold) never rewrites the
+     * address: a tab derives a step, only a mover changes the address.
+     *
+     * ```tsx
+     * const shared = useSharedCursor(recorder);
+     * <Lens recorder={recorder} shared={shared} granularity="group" />
+     * <ContextView runner={runner} cursor={shared.forAxis('group')} />
+     * ```
+     */
+    readonly shared?: SharedCursor;
     /**
      * Move the cursor to a STAGE, by its address — the pointing half of the
      * cursor API. `step` / `onStepChange` let a host OWN the cursor; this lets
@@ -759,4 +797,4 @@ interface LensDetailSlotProps {
 }
 declare const Lens: React__default.FC<LensProps>;
 
-export { type LensProps as L, type ToolChoiceSource as T, type UseLensCursorArgs as U, Lens as a, type LensCursorAt as b, type LensDetailSlotProps as c, type LensSlots as d, type LensTheme as e, type LensView as f, type LensCursorPlace as g, LensFlow as h, type LensFlowProps as i, type LensNavigator as j, type UseLensCursorResult as k, type UseLensNavigatorArgs as l, type UseToolChoiceResult as m, clampStep as n, useLensNavigator as o, useToolChoice as p, useLensCursor as u };
+export { type LensProps as L, type SharedAxis as S, type ToolChoiceSource as T, type UseLensCursorArgs as U, Lens as a, type LensCursorAt as b, type LensDetailSlotProps as c, type LensSlots as d, type LensTheme as e, type LensView as f, type LensCursorPlace as g, LensFlow as h, type LensFlowProps as i, type LensNavigator as j, type SharedCursor as k, type UseLensCursorResult as l, type UseLensNavigatorArgs as m, type UseToolChoiceResult as n, clampStep as o, useLensNavigator as p, useSharedCursor as q, useToolChoice as r, useLensCursor as u };

package/dist/{Lens-DKbZBkI8.d.ts → Lens-FeyxIX4N.d.ts}

@@ -3,8 +3,8 @@ import { ToolChoiceCall, ToolChoiceSummary } from 'agentfootprint/observe';
 import * as agentfootprint from 'agentfootprint';
 import { CommentaryTemplates } from 'agentfootprint';
 import React__default, { Ref } from 'react';
-import { a as LensCursorReading, C as CursorPosition, L as LensCursor, e as NavigationResult, h as LensRecorder } from './lensCursor-BQyMCkdo.js';
-import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-DuOMNXvq.js';
+import { a as LensCursorReading, C as CursorPosition, L as LensCursor, h as LensRecorder, e as NavigationResult } from './lensCursor-BQyMCkdo.js';
+import { C as ChartGroupHighlight, c as LensCursorPort, z as CursorAddress, H as Humanizer, b as BookmarkStore } from './tagAxis-DyLdm6ah.js';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -241,6 +241,26 @@ interface UseLensCursorResult {
 declare function clampStep(n: number, maxStep: number): number;
 declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, positions, }: UseLensCursorArgs): UseLensCursorResult;
 
+type SharedAxis = 'step' | 'group';
+interface SharedCursor {
+    /** The held address — `undefined` until a move, when the default (the run's end) applies. */
+    readonly address: CursorAddress | undefined;
+    /** The `LensCursor` a lens drawing this axis reads; its `moveTo` moves the shared address. */
+    forAxis(granularity: SharedAxis, drillPath?: readonly string[]): LensCursor;
+    /**
+     * The general form (0.56.0): the `LensCursor` over ANY positions a view
+     * draws — a tag-filtered axis, a drilled one — read under `drillPath`.
+     * `forAxis` is this over the library's own two axes. Same positions, same
+     * address → the same object, so a memo keyed on it holds.
+     */
+    over(positions: readonly CursorPosition[], drillPath?: readonly string[]): LensCursor;
+    /** Move the ONE cursor to an address — what every mover ends in. */
+    moveTo(address: CursorAddress): void;
+    /** The older contract, bridged: a `<Lens onStepChange>` or a transport reporting a step lands here. */
+    onStepChange(step: number, at: LensCursorAt): void;
+}
+declare function useSharedCursor(recorder: LensRecorder | undefined): SharedCursor;
+
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.
  *
@@ -603,6 +623,24 @@ interface LensProps {
      * Memoize via `useCallback` to avoid downstream re-renders.
      */
     readonly onStepChange?: (step: number, at: LensCursorAt) => void;
+    /**
+     * The HOST's one cursor across every lens it mounts (0.56.0) — the owner
+     * `useSharedCursor(recorder)` hands back. Pass it and this lens derives its
+     * own step over whatever axis it is drawing (the commit axis, the milestone
+     * axis, a tag-filtered one, a drilled one) from the shared ADDRESS, and
+     * every mover here — the strip, ◀ ▶, a chart click, `navigatorRef` — moves
+     * that address. `step` is ignored while `shared` is given; `onStepChange`
+     * still fires as an observation hook. A correction the lens makes on its
+     * own (`at.clamped`, an address this axis cannot hold) never rewrites the
+     * address: a tab derives a step, only a mover changes the address.
+     *
+     * ```tsx
+     * const shared = useSharedCursor(recorder);
+     * <Lens recorder={recorder} shared={shared} granularity="group" />
+     * <ContextView runner={runner} cursor={shared.forAxis('group')} />
+     * ```
+     */
+    readonly shared?: SharedCursor;
     /**
      * Move the cursor to a STAGE, by its address — the pointing half of the
      * cursor API. `step` / `onStepChange` let a host OWN the cursor; this lets
@@ -759,4 +797,4 @@ interface LensDetailSlotProps {
 }
 declare const Lens: React__default.FC<LensProps>;
 
-export { type LensProps as L, type ToolChoiceSource as T, type UseLensCursorArgs as U, Lens as a, type LensCursorAt as b, type LensDetailSlotProps as c, type LensSlots as d, type LensTheme as e, type LensView as f, type LensCursorPlace as g, LensFlow as h, type LensFlowProps as i, type LensNavigator as j, type UseLensCursorResult as k, type UseLensNavigatorArgs as l, type UseToolChoiceResult as m, clampStep as n, useLensNavigator as o, useToolChoice as p, useLensCursor as u };
+export { type LensProps as L, type SharedAxis as S, type ToolChoiceSource as T, type UseLensCursorArgs as U, Lens as a, type LensCursorAt as b, type LensDetailSlotProps as c, type LensSlots as d, type LensTheme as e, type LensView as f, type LensCursorPlace as g, LensFlow as h, type LensFlowProps as i, type LensNavigator as j, type SharedCursor as k, type UseLensCursorResult as l, type UseLensNavigatorArgs as m, type UseToolChoiceResult as n, clampStep as o, useLensNavigator as p, useSharedCursor as q, useToolChoice as r, useLensCursor as u };

package/dist/{chunk-UYL7DUOI.js → chunk-7LOCALIV.js}

@@ -2965,8 +2965,9 @@ var Lens = ({
   commentaryTemplates,
   toolChoice,
   granularity = "step",
-  step: controlledStep,
-  onStepChange,
+  step: controlledStepProp,
+  onStepChange: onStepChangeProp,
+  shared,
   navigatorRef,
   slots,
   bookmarkStore
@@ -3079,6 +3080,15 @@ var Lens = ({
     },
     [cursorPositions]
   );
+  const sharedOver = shared !== void 0 ? shared.over(cursorPositions, drillPath) : void 0;
+  const controlledStep = sharedOver !== void 0 ? sharedOver.at.step : controlledStepProp;
+  const onStepChange = useCallback6(
+    (n, at) => {
+      if (sharedOver !== void 0 && !at.clamped) sharedOver.moveTo(n);
+      onStepChangeProp?.(n, at);
+    },
+    [sharedOver, onStepChangeProp]
+  );
   const {
     step: focusStep,
     isLive,
@@ -3102,6 +3112,7 @@ var Lens = ({
     const prev = seatRef.current;
     seatRef.current = { positions: cursorPositions, step: focusStep, tagAxis };
     if (prev.tagAxis === tagAxis) return;
+    if (shared !== void 0) return;
     const commit = prev.positions[prev.step]?.commitIdx;
     if (commit === void 0 || commit < 0) return;
     const target = stepForCommitIdx(cursorPositions, commit);
@@ -4775,4 +4786,4 @@ export {
   useBookmarkSidecar,
   Lens
 };
-//# sourceMappingURL=chunk-UYL7DUOI.js.map
+//# sourceMappingURL=chunk-7LOCALIV.js.map