agentfootprint-lens 0.55.0 → 0.57.0

package/README.md

@@ -828,11 +828,18 @@ 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
-// lens at a time.
-<Lens recorder={recorder} granularity="step"
-      step={shared.forAxis('step').at.step} onStepChange={shared.onStepChange} />
+// 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} />
+
+// The Skill Graph on the same owner (0.57.0): it reads the address over the
+// run's commit axis, moves it from its own transport, and finds its own
+// snap stops — nothing else to hand it.
+<SkillGraphDebugger recorder={recorder} shared={shared} />
+
+// A view still on the older step + report contract is bridged into the same
+// address with `shared.onStepChange`, so a host migrates one lens at a time.
 ```
 
 The law: a tab DERIVES its step from the address (the exact stage when its

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

@@ -3,10 +3,11 @@ 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 { e as NavigationResult, C as CursorPosition, h as LensRecorder, L as LensCursor } from './lensCursor-BQyMCkdo.cjs';
+import { C as ChartGroupHighlight, H as Humanizer, b as BookmarkStore } from './tagAxis-T6KT8hQe.cjs';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
+import { L as LensCursorAt, S as SharedCursor } from './useSharedCursor-u1vyTFkj.cjs';
 
 /**
  * LensFlow — the canonical Lens chart renderer.
@@ -134,113 +135,6 @@ interface LensFlowProps {
 }
 declare const LensFlow: React__default.FC<LensFlowProps>;
 
-/**
- * useLensCursor — the ONE cursor, controlled or uncontrolled.
- *
- * `<Lens>` has always held its scrub position in local state. This hook is that
- * same state with one addition: when the host passes a value, the host owns it.
- * The standard controlled/uncontrolled pair, modelled on
- * `<TraceExplorerShell selectedRuntimeStageId / onSelectionChange>` in
- * `footprint-explainable-ui` so the family reads as one API.
- *
- * The law it exists to keep: **one cursor, never two owners.** Every mover
- * inside the lens — the step strip, the ◀ ▶ ⟳Live buttons, the arrow keys, a
- * chart node click, a "what happened" moment, a provenance jump, and the
- * auto-advance that follows a live run — goes through `moveTo`. A mover that
- * sets position without notifying would be a second cursor wearing the first
- * one's clothes.
- *
- * Omit `controlledStep` and nothing changes: the hook keeps today's internal
- * state and today's auto-advance, byte for byte.
- */
-
-/**
- * Where the cursor landed, in all three units the lens knows — handed to
- * `onStepChange` alongside the step so a host never has to reverse-engineer
- * the lens's axis.
- *
- * It is a `LensCursorReading` (`/core`) plus the one thing a MOVE REPORT needs
- * and a reading does not: `clamped`. One declaration of the reading's fields,
- * so the report and the `LensCursor` every view is handed cannot drift.
- */
-interface LensCursorAt extends LensCursorReading {
-    /**
-     * `true` when this call is Lens CORRECTING a step that is not a position on
-     * the axis it is now read against, not a move someone made. That is an
-     * out-of-range `step` you passed, one an internal jump produced, OR — when
-     * you passed no `step` at all — the lens's own remembered step after the
-     * axis shrank under it. Uncontrolled snaps are reported too, so this flag
-     * means the same thing in both modes. Store the corrected value and the two
-     * cursors agree again.
-     */
-    readonly clamped: boolean;
-}
-/** The cursor's address at one step — resolved by the caller, which owns the
- *  position list. */
-interface LensCursorPlace {
-    readonly runtimeStageId: string;
-    readonly commitIdx: number;
-    readonly label: string;
-    readonly kind?: string;
-}
-interface UseLensCursorArgs {
-    /** The host's value. `undefined` → uncontrolled (Lens owns the cursor). */
-    readonly controlledStep: number | undefined;
-    /** Fires on every cursor move, controlled or not. */
-    readonly onStepChange?: ((step: number, at: LensCursorAt) => void) | undefined;
-    /** Highest valid step (`totalSteps - 1`). */
-    readonly maxStep: number;
-    /** Resolve a step to its address. Called only when a move is reported. */
-    readonly describe: (step: number) => LensCursorPlace;
-    /**
-     * The MOVEMENT port — footprintjs 9.17's reader cursor over the Lens's own
-     * stops (`openLensCursor(positions)`). When present, every move this funnel
-     * makes is decided by the library: where a step lands, what happens at the
-     * ends of the axis, and what an out-of-range ask does. Omit it and the
-     * funnel keeps its own arithmetic, unchanged — which is what the hook's own
-     * tests drive, so the two readings can be compared.
-     *
-     * It is NOT a second cursor: the port is re-seated on the step this hook
-     * owns before every question and remembers nothing between them.
-     */
-    readonly port?: LensCursorPort | undefined;
-    /**
-     * The ACTIVE scrub axis — the same list the lens draws its ruler from.
-     *
-     * Supplied only so this hook can also hand back the `LensCursor` every view
-     * receives (`cursor` below), which needs the axis to answer an ADDRESS. It
-     * is never consulted for movement: `maxStep`, `describe` and `port` decide
-     * that, exactly as they did before 0.51.0.
-     *
-     * Omit it and `cursor` is a cursor over an EMPTY axis — `resolve` refuses
-     * `'empty-axis'`, which is the honest answer for a caller that gave none.
-     */
-    readonly positions?: readonly CursorPosition[] | undefined;
-}
-interface UseLensCursorResult {
-    /** The cursor to render. */
-    readonly step: number;
-    /** Pinned to the live edge (drives the ⟳Live affordance). */
-    readonly isLive: boolean;
-    /** The ONE way anything inside the lens moves the cursor. */
-    readonly moveTo: (n: number) => void;
-    /**
-     * The same one cursor in the shape EVERY view is handed (0.51.0): a READING
-     * (`at`), the honest address query (`resolve`) and this very `moveTo`.
-     *
-     * Added BESIDE the three fields above — nothing moved, nothing was removed.
-     * It holds no position: it is rebuilt from (`positions`, `step`) on every
-     * render, so a view cannot end up rendering a stale copy.
-     */
-    readonly cursor: LensCursor;
-}
-/**
- * Snap a host-supplied step onto the axis. Non-finite and fractional values
- * are not positions, so they clamp too — and the clamp is always reported.
- */
-declare function clampStep(n: number, maxStep: number): number;
-declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, positions, }: UseLensCursorArgs): UseLensCursorResult;
-
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.
  *
@@ -603,6 +497,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 +671,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 ToolChoiceSource as T, type UseLensNavigatorArgs as U, Lens as a, type LensDetailSlotProps as b, type LensSlots as c, type LensTheme as d, type LensView as e, LensFlow as f, type LensFlowProps as g, type LensNavigator as h, type UseToolChoiceResult as i, useToolChoice as j, useLensNavigator as u };

package/dist/{Lens-DHmINGvn.d.cts → Lens-CkZrAiF4.d.ts}

@@ -3,10 +3,11 @@ 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 { e as NavigationResult, C as CursorPosition, h as LensRecorder, L as LensCursor } from './lensCursor-BQyMCkdo.js';
+import { C as ChartGroupHighlight, H as Humanizer, b as BookmarkStore } from './tagAxis-m8H-ewcU.js';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
+import { L as LensCursorAt, S as SharedCursor } from './useSharedCursor-CR5vHgkL.js';
 
 /**
  * LensFlow — the canonical Lens chart renderer.
@@ -134,113 +135,6 @@ interface LensFlowProps {
 }
 declare const LensFlow: React__default.FC<LensFlowProps>;
 
-/**
- * useLensCursor — the ONE cursor, controlled or uncontrolled.
- *
- * `<Lens>` has always held its scrub position in local state. This hook is that
- * same state with one addition: when the host passes a value, the host owns it.
- * The standard controlled/uncontrolled pair, modelled on
- * `<TraceExplorerShell selectedRuntimeStageId / onSelectionChange>` in
- * `footprint-explainable-ui` so the family reads as one API.
- *
- * The law it exists to keep: **one cursor, never two owners.** Every mover
- * inside the lens — the step strip, the ◀ ▶ ⟳Live buttons, the arrow keys, a
- * chart node click, a "what happened" moment, a provenance jump, and the
- * auto-advance that follows a live run — goes through `moveTo`. A mover that
- * sets position without notifying would be a second cursor wearing the first
- * one's clothes.
- *
- * Omit `controlledStep` and nothing changes: the hook keeps today's internal
- * state and today's auto-advance, byte for byte.
- */
-
-/**
- * Where the cursor landed, in all three units the lens knows — handed to
- * `onStepChange` alongside the step so a host never has to reverse-engineer
- * the lens's axis.
- *
- * It is a `LensCursorReading` (`/core`) plus the one thing a MOVE REPORT needs
- * and a reading does not: `clamped`. One declaration of the reading's fields,
- * so the report and the `LensCursor` every view is handed cannot drift.
- */
-interface LensCursorAt extends LensCursorReading {
-    /**
-     * `true` when this call is Lens CORRECTING a step that is not a position on
-     * the axis it is now read against, not a move someone made. That is an
-     * out-of-range `step` you passed, one an internal jump produced, OR — when
-     * you passed no `step` at all — the lens's own remembered step after the
-     * axis shrank under it. Uncontrolled snaps are reported too, so this flag
-     * means the same thing in both modes. Store the corrected value and the two
-     * cursors agree again.
-     */
-    readonly clamped: boolean;
-}
-/** The cursor's address at one step — resolved by the caller, which owns the
- *  position list. */
-interface LensCursorPlace {
-    readonly runtimeStageId: string;
-    readonly commitIdx: number;
-    readonly label: string;
-    readonly kind?: string;
-}
-interface UseLensCursorArgs {
-    /** The host's value. `undefined` → uncontrolled (Lens owns the cursor). */
-    readonly controlledStep: number | undefined;
-    /** Fires on every cursor move, controlled or not. */
-    readonly onStepChange?: ((step: number, at: LensCursorAt) => void) | undefined;
-    /** Highest valid step (`totalSteps - 1`). */
-    readonly maxStep: number;
-    /** Resolve a step to its address. Called only when a move is reported. */
-    readonly describe: (step: number) => LensCursorPlace;
-    /**
-     * The MOVEMENT port — footprintjs 9.17's reader cursor over the Lens's own
-     * stops (`openLensCursor(positions)`). When present, every move this funnel
-     * makes is decided by the library: where a step lands, what happens at the
-     * ends of the axis, and what an out-of-range ask does. Omit it and the
-     * funnel keeps its own arithmetic, unchanged — which is what the hook's own
-     * tests drive, so the two readings can be compared.
-     *
-     * It is NOT a second cursor: the port is re-seated on the step this hook
-     * owns before every question and remembers nothing between them.
-     */
-    readonly port?: LensCursorPort | undefined;
-    /**
-     * The ACTIVE scrub axis — the same list the lens draws its ruler from.
-     *
-     * Supplied only so this hook can also hand back the `LensCursor` every view
-     * receives (`cursor` below), which needs the axis to answer an ADDRESS. It
-     * is never consulted for movement: `maxStep`, `describe` and `port` decide
-     * that, exactly as they did before 0.51.0.
-     *
-     * Omit it and `cursor` is a cursor over an EMPTY axis — `resolve` refuses
-     * `'empty-axis'`, which is the honest answer for a caller that gave none.
-     */
-    readonly positions?: readonly CursorPosition[] | undefined;
-}
-interface UseLensCursorResult {
-    /** The cursor to render. */
-    readonly step: number;
-    /** Pinned to the live edge (drives the ⟳Live affordance). */
-    readonly isLive: boolean;
-    /** The ONE way anything inside the lens moves the cursor. */
-    readonly moveTo: (n: number) => void;
-    /**
-     * The same one cursor in the shape EVERY view is handed (0.51.0): a READING
-     * (`at`), the honest address query (`resolve`) and this very `moveTo`.
-     *
-     * Added BESIDE the three fields above — nothing moved, nothing was removed.
-     * It holds no position: it is rebuilt from (`positions`, `step`) on every
-     * render, so a view cannot end up rendering a stale copy.
-     */
-    readonly cursor: LensCursor;
-}
-/**
- * Snap a host-supplied step onto the axis. Non-finite and fractional values
- * are not positions, so they clamp too — and the clamp is always reported.
- */
-declare function clampStep(n: number, maxStep: number): number;
-declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, positions, }: UseLensCursorArgs): UseLensCursorResult;
-
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.
  *
@@ -603,6 +497,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 +671,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 ToolChoiceSource as T, type UseLensNavigatorArgs as U, Lens as a, type LensDetailSlotProps as b, type LensSlots as c, type LensTheme as d, type LensView as e, LensFlow as f, type LensFlowProps as g, type LensNavigator as h, type UseToolChoiceResult as i, useToolChoice as j, useLensNavigator as u };