agentfootprint-lens 0.50.0 → 0.51.0

package/README.md

@@ -1278,6 +1278,108 @@ Keep the slots object stable across renders (module scope or `useMemo`), same as
 
 ---
 
+## One address, one cursor — for every view
+
+> **A stage id is an ADDRESS, not a POSITION.** It says WHICH stage, never WHERE
+> on an axis. Only an axis can answer that, and it may honestly answer *"not
+> here"*.
+
+Until 0.51.0 the same one cursor reached three views in three vocabularies, and
+every new view invented a fourth:
+
+| view | handed | reads |
+|---|---|---|
+| skill graph | `cursorRuntimeStageId` + `onJumpTo` | the EVENT record |
+| a consumer's data graph | `{ step, total, stepOf(id), onStep }` | the COMMIT record |
+| Served tab / graph | `cursorRuntimeStageId` + `commitIdx` | the COMMIT record |
+
+`LensCursor` is their superset, and every view now gets exactly it. It is three
+things and deliberately nothing more:
+
+```ts
+interface LensCursor {
+  readonly at: LensCursorReading;              // step · totalSteps · runtimeStageId · commitIdx · label · kind
+  readonly total: number;
+  resolve(runtimeStageId: string): NavigationResult;   // an ADDRESS, answered honestly
+  moveTo(step: number): void;                          // the ONE funnel
+}
+```
+
+**It holds no position of its own**, and no view may gain one: `at` is derived
+from the axis and the step on every render, `resolve` is a pure query, and
+`moveTo` is the same funnel the step strip, the ◀ ▶ buttons and the live
+auto-advance go through. Read it; never store it.
+
+### Adopting it — one line
+
+```tsx
+<Lens
+  recorder={recorder}
+  slots={{ detail: (p) => <SkillGraphDebugger recorder={p.recorder} cursor={p.cursor} /> }}
+/>
+```
+
+`cursor` arrives on `LensDetailSlotProps` beside every prop that was already
+there, and `<SkillGraphDebugger cursor>` / `<ServedTab cursor>` are the narrow
+form of the props they already took. Nothing was removed; an explicit prop still
+wins wherever both are passed.
+
+### Placing an element by address
+
+This is the behaviour the packet generalises. A real consumer's data-graph view
+took `stepOf(id)` and drew an element `unplaced` when the answer came back below
+zero — a number every view had to invent a meaning for. Written against
+`resolve`, the meaning *and the words* come from the library:
+
+```tsx
+function Element({ cursor, runtimeStageId, name }) {
+  const to = cursor.resolve(runtimeStageId);
+  if (!to.ok) {
+    // Drawn, never hidden — omit never deny — and the sentence is the library's.
+    return <li data-unplaced title={to.message}>{name}</li>;
+  }
+  return (
+    <li data-enclosing={to.match === 'enclosing'} onClick={() => cursor.moveTo(to.step)}>
+      {to.label}
+    </li>
+  );
+}
+```
+
+### The three cases the contract names
+
+Each is a real run, and each has a test measured on a frozen fixture:
+
+1. **The axis does not stop there.** A filtered or tag axis over an untagged
+   stage. `resolve` refuses `'not-on-axis'`, carries a printable `message`, and
+   OFFERS the nearest earlier stop in `nearest` — an offer, never a move.
+2. **The id belongs to an inner log.** A subflow's stages commit into their own
+   isolated log, so the axis holds the MOUNT rather than the stage. The ladder's
+   `'enclosing'` rung answers `{ ok: true, match: 'enclosing' }` whose
+   `runtimeStageId` is the mount's — a true landing at the granularity this axis
+   has. Branch on `match` when you must tell "on it" from "inside it", and offer
+   a drill to go deeper.
+3. **The event has no stage at all.** Run start, run end. There is no id;
+   `resolve('')` refuses `'no-id'` and your view says so rather than inventing
+   an address.
+
+### Headless
+
+```ts
+import { scrubAxisFor, lensCursorFrom } from 'agentfootprint-lens/core';
+
+const positions = scrubAxisFor(recorder, 'step');
+const cursor = lensCursorFrom(positions, 0, (step) => setStep(step));
+const to = cursor.resolve('llm#7');
+const href = to.ok ? `/run/${runId}?step=${to.step}` : undefined;
+```
+
+`stepForRuntimeStageId` still ships and still behaves byte for byte; it is
+**deprecated** in favour of `resolveNavigation` / `cursor.resolve`, the same
+ladder with its rungs named instead of flattened to `-1`.
+
+---
+
 ## Theming
 
 **Lens inherits theme tokens from your app via CSS variables.** Set `--fp-*`

package/dist/{Lens-okdu_w0H.d.ts → Lens-Bw1em67x.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 { d as NavigationResult, C as CursorPosition, L as LensRecorder } from './resolveNavigation-Ckr2nXHY.js';
-import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-C__DMHiD.js';
+import { a as LensCursorReading, C as CursorPosition, L as LensCursor, e as NavigationResult, h as LensRecorder } from './lensCursor-B8HFFZgR.cjs';
+import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-BUrsQ1fX.cjs';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -158,26 +158,12 @@ declare const LensFlow: React__default.FC<LensFlowProps>;
  * 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 {
-    /** The new cursor position, on the lens's step axis. Same number the
-     *  `step` prop takes. */
-    readonly step: number;
-    /** How many positions the axis has right now. Valid steps are
-     *  `0 … totalSteps - 1`. GROWS during a live run. */
-    readonly totalSteps: number;
-    /** The cursor's address in footprintjs's address space
-     *  (`[subflowPath/]stageId#executionIndex`) — the same string
-     *  `<TraceExplorerShell>` and `<RunSlider>` call `selectedRuntimeStageId` /
-     *  `cursorRuntimeStageId`. `''` when the axis is empty. */
-    readonly runtimeStageId: string;
-    /** The commit-log index this position anchors to. `-1` when unknown. */
-    readonly commitIdx: number;
-    /** The position's human label, as the step strip and the timeline spell it
-     *  ("Iteration 2", "Context 3", "Run · start"). */
-    readonly label: string;
-    /** What kind of stop this is. Absent when the axis is empty. */
-    readonly kind?: string;
+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
@@ -218,6 +204,18 @@ interface UseLensCursorArgs {
      * 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. */
@@ -226,13 +224,22 @@ interface UseLensCursorResult {
     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, }: UseLensCursorArgs): UseLensCursorResult;
+declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, positions, }: UseLensCursorArgs): UseLensCursorResult;
 
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.
@@ -721,6 +728,26 @@ interface LensDetailSlotProps {
     readonly recorder: LensRecorder;
     /** Move the ONE cursor — same funnel every built-in mover uses. */
     readonly onNavigate: (step: number) => void;
+    /**
+     * THE CURSOR, in the one vocabulary every view now shares (0.51.0) — the
+     * reading above (`cursor.at`), the axis's honest answer to an ADDRESS
+     * (`cursor.resolve(id)`), and the same funnel as `onNavigate`
+     * (`cursor.moveTo`).
+     *
+     * Everything else on this interface stays exactly as it was; this is the
+     * shape to reach for when your pane places elements BY ADDRESS, because the
+     * axis may honestly not stop where an address points:
+     *
+     * ```tsx
+     * const to = p.cursor.resolve(node.runtimeStageId);
+     * if (!to.ok) return <li data-unplaced title={to.message}>{node.name}</li>;
+     * return <li onClick={() => p.cursor.moveTo(to.step)}>{to.label}</li>;
+     * ```
+     *
+     * It holds no position of its own — it is rebuilt every render. Read it;
+     * never store it.
+     */
+    readonly cursor: LensCursor;
 }
 declare const Lens: React__default.FC<LensProps>;
 

package/dist/{Lens-DJJsMfud.d.cts → Lens-CDsSUiHJ.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 { d as NavigationResult, C as CursorPosition, L as LensRecorder } from './resolveNavigation-Ckr2nXHY.cjs';
-import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-B598GxMJ.cjs';
+import { a as LensCursorReading, C as CursorPosition, L as LensCursor, e as NavigationResult, h as LensRecorder } from './lensCursor-B8HFFZgR.js';
+import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-Cqom3DPf.js';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -158,26 +158,12 @@ declare const LensFlow: React__default.FC<LensFlowProps>;
  * 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 {
-    /** The new cursor position, on the lens's step axis. Same number the
-     *  `step` prop takes. */
-    readonly step: number;
-    /** How many positions the axis has right now. Valid steps are
-     *  `0 … totalSteps - 1`. GROWS during a live run. */
-    readonly totalSteps: number;
-    /** The cursor's address in footprintjs's address space
-     *  (`[subflowPath/]stageId#executionIndex`) — the same string
-     *  `<TraceExplorerShell>` and `<RunSlider>` call `selectedRuntimeStageId` /
-     *  `cursorRuntimeStageId`. `''` when the axis is empty. */
-    readonly runtimeStageId: string;
-    /** The commit-log index this position anchors to. `-1` when unknown. */
-    readonly commitIdx: number;
-    /** The position's human label, as the step strip and the timeline spell it
-     *  ("Iteration 2", "Context 3", "Run · start"). */
-    readonly label: string;
-    /** What kind of stop this is. Absent when the axis is empty. */
-    readonly kind?: string;
+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
@@ -218,6 +204,18 @@ interface UseLensCursorArgs {
      * 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. */
@@ -226,13 +224,22 @@ interface UseLensCursorResult {
     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, }: UseLensCursorArgs): UseLensCursorResult;
+declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, positions, }: UseLensCursorArgs): UseLensCursorResult;
 
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.
@@ -721,6 +728,26 @@ interface LensDetailSlotProps {
     readonly recorder: LensRecorder;
     /** Move the ONE cursor — same funnel every built-in mover uses. */
     readonly onNavigate: (step: number) => void;
+    /**
+     * THE CURSOR, in the one vocabulary every view now shares (0.51.0) — the
+     * reading above (`cursor.at`), the axis's honest answer to an ADDRESS
+     * (`cursor.resolve(id)`), and the same funnel as `onNavigate`
+     * (`cursor.moveTo`).
+     *
+     * Everything else on this interface stays exactly as it was; this is the
+     * shape to reach for when your pane places elements BY ADDRESS, because the
+     * axis may honestly not stop where an address points:
+     *
+     * ```tsx
+     * const to = p.cursor.resolve(node.runtimeStageId);
+     * if (!to.ok) return <li data-unplaced title={to.message}>{node.name}</li>;
+     * return <li onClick={() => p.cursor.moveTo(to.step)}>{to.label}</li>;
+     * ```
+     *
+     * It holds no position of its own — it is rebuilt every render. Read it;
+     * never store it.
+     */
+    readonly cursor: LensCursor;
 }
 declare const Lens: React__default.FC<LensProps>;