agentfootprint-lens 0.55.0 → 0.56.0

package/README.md

@@ -828,11 +828,15 @@ 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 older step + report contract, bridged into the same address — so a
-// `<Lens>` or a Skill Graph transport keeps working while you migrate one
+// 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.
-<Lens recorder={recorder} granularity="step"
-      step={shared.forAxis('step').at.step} onStepChange={shared.onStepChange} />
+<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

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