agentfootprint-lens 0.45.0 → 0.46.0

package/README.md

@@ -808,6 +808,133 @@ const href = to.ok ? `/runs/${runId}?step=${to.step}` : undefined;
 
 ---
 
+## Time travel through one port
+
+**Nothing to do — this is how the cursor already moves.** Read it if you are
+building a second surface over the same run, or wondering why the ruler behaves
+identically in the Why Lens, the Flow Lens and your own view.
+
+### Why
+
+Every consumer of a footprintjs run was writing the same six lines: clamp at
+zero, clamp at the end, resolve an address to a stop, decide what a miss does.
+The lens had them in `<TimeTravel>`, the flow view had its own copy, and a
+dashboard had a third — and they disagreed at exactly the places nobody tests: a
+▶ at the last stop, a jump to a stage that is not on this ruler, a step stored
+from a longer run.
+
+footprintjs 9.17 owns that arithmetic now. `timeTravel(snapshot, { strategy })`
+is the **reader's cursor over a finished trace**: `first` / `last` / `prev` /
+`next` / `jumpTo`, one position, and one law — **a refused move never moves the
+cursor**, it returns the reason and the nearest stop it could name. Since
+0.46.0 the lens's movement goes through it.
+
+**Which stops exist did not change.** The lens still computes its own axis —
+milestones banded by iteration for the Why reading, one stop per executed stage
+for the Flow reading, drill-scoped either way — with the same labels, the same
+order and the same kinds. Those positions ARE the port's stops, through a
+lens-owned `TimeTravelStrategy`. The library decides *where a move lands*; the
+lens decides *what there is to land on*.
+
+**Still one cursor.** The port instance is a calculator, not a position: it is
+re-seated on the step the lens owns before every question and remembers nothing
+between them. `<Lens step onStepChange>` is unchanged, and so is everything a
+panel reads.
+
+### The port, headless
+
+```ts
+import { scrubAxisFor, openLensCursor } from 'agentfootprint-lens/core';
+
+const positions = scrubAxisFor(recorder, 'group');   // the ruler, as data
+const cursor = openLensCursor(positions);
+
+cursor.next(4).step;          // 5
+cursor.next(positions.length - 1);
+// { step: <last>, moved: false, reason: 'clamped', clamped: false }
+
+cursor.toStep(2, 9999);
+// { step: <last>, moved: true, clamped: true }   ← off the axis, said so
+
+cursor.toAddress(2, 'call-llm#18');
+// { ok: true, step: 7 }
+cursor.toAddress(2, 'never-ran#4');
+// { ok: false, reason: 'miss', nearest: <the closest stop the library
+//   could name — the same stage at another execution index if this axis
+//   holds one, otherwise the last stop whose execution index is not past
+//   the one you asked for> }
+//   the cursor is still at 2 — a miss is offered, never taken
+
+cursor.positionAt(7);
+// the LENS position: runtimeGroupId, depth, coActiveGroupIds, milestone —
+// everything the port's `Stop` has no slot for, unchanged and unflattened
+```
+
+`openLensCursor` answers **where**, never **what**: it has no `stateAt`, no
+`changedSince`, no `drill`. Those are folds over the run's commit log, and a
+fold wants the run's snapshot — which movement never reads. Want them over this
+same ruler? Build the library's cursor directly, with the lens's stops:
+
+```ts
+import { timeTravel } from 'footprintjs/trace';
+import { scrubAxisFor, lensStopsStrategy } from 'agentfootprint-lens/core';
+
+// A LIVE run. `runner.getLastSnapshot()` IS footprintjs's own snapshot, so it
+// is already a `TimeTravelSource` and the two libraries meet with no cast.
+const snapshot = runner.getLastSnapshot();
+if (snapshot) {
+  const positions = scrubAxisFor(recorder, 'group');
+  const tt = timeTravel(snapshot, { strategy: lensStopsStrategy(positions) });
+  tt.jumpTo(7);
+  tt.changedSince();       // the keys this stop's slice of the log wrote
+  tt.stateAt().state;      // state as of that stop, detached
+}
+```
+
+A **stored** recording needs one narrowing today, and the reason is honest on
+both sides: the lens types `Recording.snapshot.commitLog` as `readonly
+unknown[]` — a recording arrives as parsed JSON, and the lens will not claim
+that what came back off disk is a `CommitBundle` — while `timeTravel` takes
+`TimeTravelSource`, whose `commitLog` is `readonly CommitBundle[]`. So a
+replayed run has to say so at the seam:
+
+```ts
+import type { TimeTravelSource } from 'footprintjs/trace';
+
+const stored = recording.snapshot as unknown as TimeTravelSource;
+const tt = timeTravel(stored, { strategy: lensStopsStrategy(positions) });
+```
+
+That cast disappears — with no change here — the day footprintjs widens
+`TimeTravelSource.commitLog` to accept an unvalidated `readonly unknown[]` and
+does the per-bundle narrowing where it folds, which is the only place that can
+honestly do it. It is reported upstream as a port gap. **Movement never needs
+this**: `openLensCursor` reads the stops and no snapshot at all, which is why
+the lens's own cursor is unaffected either way.
+
+### Two axes, and drilling
+
+Rebuild the port when the positions change; its identity is that list's, which
+is already memoised per (recording, axis, drill level):
+
+```ts
+const port = useMemo(() => openLensCursor(positions), [positions]);
+```
+
+Drilling rebuilds the axis — the drilled group's own stops, which is a
+different set — so it rebuilds the port. The lens does **not** use the port's
+`drill()` for this: `drill()` opens a subflow's own commit log, and a lens drill
+level is not always a subflow (it is a group, and a subflow whose stages commit
+in their own memory scope is reconstructed from the runtime overlay). Using it
+would change which stops appear at a drill level, which is the one thing this
+change refuses to do.
+
+`snapSteps` also stays the lens's. Snaps narrow ◀ ▶ to a *subset* of the axis
+while the cursor may be parked between two of them — a question `jumpTo` does
+not answer, since it takes an exact stop.
+
+---
+
 ## Rendering your own detail pane
 
 `slots.detail` replaces the CONTENT of the shipped right column. The column
@@ -1112,6 +1239,12 @@ so instead of drawing an empty graph.
 / CLI view on the same primitives — see `ChangeNotifier`'s JSDoc for adapter
 snippets.
 
+The cursor is headless too: `scrubAxisFor` builds the ruler, `openLensCursor`
+moves along it through footprintjs's `timeTravel()` port, `resolveNavigation`
+turns an address into a step with every rung named, and `stepForCommitIdx`
+carries a position between the two axes. See
+[Time travel through one port](#time-travel-through-one-port).
+
 ---
 
 ## Why this design

package/dist/{Lens-B039-UGw.d.cts → Lens-6elRg27j.d.cts}

@@ -4,7 +4,7 @@ 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-o4E4cM_1.cjs';
-import { C as ChartGroupHighlight, H as Humanizer } from './scrubAxisFor-CNceBlz-.cjs';
+import { C as ChartGroupHighlight, a as LensCursorPort, H as Humanizer } from './lensStops-hQ10t3Lt.cjs';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -153,6 +153,7 @@ declare const LensFlow: React__default.FC<LensFlowProps>;
  * 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
@@ -178,9 +179,13 @@ interface LensCursorAt {
     /** What kind of stop this is. Absent when the axis is empty. */
     readonly kind?: string;
     /**
-     * `true` when this call is Lens CORRECTING an out-of-range `step` you
-     * passed (or one an internal jump produced), not a move someone made.
-     * Store the corrected value and the two cursors agree again.
+     * `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;
 }
@@ -201,6 +206,18 @@ interface UseLensCursorArgs {
     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;
 }
 interface UseLensCursorResult {
     /** The cursor to render. */
@@ -215,7 +232,7 @@ interface UseLensCursorResult {
  * 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, }: UseLensCursorArgs): UseLensCursorResult;
+declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, }: UseLensCursorArgs): UseLensCursorResult;
 
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.

package/dist/{Lens-ey1EgN9i.d.ts → Lens-Bdz-JzVm.d.ts}

@@ -4,7 +4,7 @@ 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-o4E4cM_1.js';
-import { C as ChartGroupHighlight, H as Humanizer } from './scrubAxisFor-Cz214OHj.js';
+import { C as ChartGroupHighlight, a as LensCursorPort, H as Humanizer } from './lensStops-DAc3GB8G.js';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -153,6 +153,7 @@ declare const LensFlow: React__default.FC<LensFlowProps>;
  * 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
@@ -178,9 +179,13 @@ interface LensCursorAt {
     /** What kind of stop this is. Absent when the axis is empty. */
     readonly kind?: string;
     /**
-     * `true` when this call is Lens CORRECTING an out-of-range `step` you
-     * passed (or one an internal jump produced), not a move someone made.
-     * Store the corrected value and the two cursors agree again.
+     * `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;
 }
@@ -201,6 +206,18 @@ interface UseLensCursorArgs {
     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;
 }
 interface UseLensCursorResult {
     /** The cursor to render. */
@@ -215,7 +232,7 @@ interface UseLensCursorResult {
  * 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, }: UseLensCursorArgs): UseLensCursorResult;
+declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, }: UseLensCursorArgs): UseLensCursorResult;
 
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.

package/dist/{chunk-YEJJOPOZ.js → chunk-2UOQEE4U.js}

@@ -6,7 +6,7 @@ import {
   describeReceived,
   refusalDestinationFor,
   useNarrowRow
-} from "./chunk-QNMA25X5.js";
+} from "./chunk-AUGRQKRL.js";
 import {
   selectSkillBeatAt,
   selectSkillBeats,
@@ -1492,4 +1492,4 @@ export {
   SKILL_GRAPH_READS,
   SkillGraphDebugger
 };
-//# sourceMappingURL=chunk-YEJJOPOZ.js.map
+//# sourceMappingURL=chunk-2UOQEE4U.js.map

package/dist/{chunk-LRGT7UQL.js → chunk-A4EIPCLY.js}

@@ -6,16 +6,17 @@ import {
   cursorProvenance,
   isFrameworkChartNode,
   makeTeachingHumanizer,
+  openLensCursor,
   selectHops,
   selectToolChoiceCall,
   structureGraphFromRunner
-} from "./chunk-CGR5VFJU.js";
+} from "./chunk-SJEKKUTI.js";
 import {
   MODE_PALETTES,
   T,
   TimeTravel,
   useNarrowRow
-} from "./chunk-QNMA25X5.js";
+} from "./chunk-AUGRQKRL.js";
 import {
   bandChartGroup,
   bandIndexOf,
@@ -914,14 +915,15 @@ function useLensCursor({
   controlledStep,
   onStepChange,
   maxStep,
-  describe
+  describe,
+  port
 }) {
   const isControlled = controlledStep !== void 0;
   const [internalStep, setInternalStep] = useState(0);
   const [autoAdvance, setAutoAdvance] = useState(
     () => controlledStep === void 0 || clampStep(controlledStep, maxStep) >= maxStep
   );
-  const step = isControlled ? clampStep(controlledStep, maxStep) : internalStep;
+  const step = clampStep(isControlled ? controlledStep : internalStep, maxStep);
   const isLive = autoAdvance && step >= maxStep;
   const describeRef = useRef(describe);
   describeRef.current = describe;
@@ -931,6 +933,8 @@ function useLensCursor({
   maxRef.current = maxStep;
   const stepRef = useRef(step);
   stepRef.current = step;
+  const portRef = useRef(port);
+  portRef.current = port;
   const notify = useCallback2((n, clamped) => {
     const cb = onChangeRef.current;
     if (!cb) return;
@@ -946,10 +950,12 @@ function useLensCursor({
     });
   }, []);
   const moveTo = useCallback2((n) => {
-    if (controlledStep === void 0) setInternalStep(n);
-    setAutoAdvance(n >= maxRef.current);
-    if (n === stepRef.current) return;
-    notify(n, false);
+    const from = stepRef.current;
+    const to = portRef.current !== void 0 ? portRef.current.toStep(from, n) : { step: n, moved: n !== from, clamped: false };
+    if (controlledStep === void 0) setInternalStep(to.step);
+    setAutoAdvance(to.step >= maxRef.current);
+    if (to.step === from && !to.clamped) return;
+    notify(to.step, to.clamped);
   }, [controlledStep, notify]);
   useEffect(() => {
     if (controlledStep === void 0) return;
@@ -963,18 +969,20 @@ function useLensCursor({
   }, [maxStep, autoAdvance, controlledStep, notify]);
   const warnedRef = useRef(void 0);
   useEffect(() => {
-    if (controlledStep === void 0) return;
-    const snapped = clampStep(controlledStep, maxStep);
-    if (snapped === controlledStep) return;
-    const key = `${controlledStep}/${maxStep}`;
-    if (warnedRef.current !== key) {
-      warnedRef.current = key;
-      console.warn(
-        `[agentfootprint-lens] <Lens step={${controlledStep}}> is not a position in this run: the cursor axis holds ${maxStep + 1} step${maxStep === 0 ? "" : "s"} (0\u2026${maxStep}). Lens moved to step ${snapped} and called onStepChange(${snapped}, { clamped: true }) so your state can follow. The axis GROWS as the run does, so store the value the callback hands you rather than a remembered number.`
-      );
+    const owned = controlledStep !== void 0 ? controlledStep : internalStep;
+    const snapped = clampStep(owned, maxStep);
+    if (snapped === owned) return;
+    if (controlledStep !== void 0) {
+      const key = `${controlledStep}/${maxStep}`;
+      if (warnedRef.current !== key) {
+        warnedRef.current = key;
+        console.warn(
+          `[agentfootprint-lens] <Lens step={${controlledStep}}> is not a position in this run: the cursor axis holds ${maxStep + 1} step${maxStep === 0 ? "" : "s"} (0\u2026${maxStep}). Lens moved to step ${snapped} and called onStepChange(${snapped}, { clamped: true }) so your state can follow. The axis GROWS as the run does, so store the value the callback hands you rather than a remembered number.`
+        );
+      }
     }
     notify(snapped, true);
-  }, [controlledStep, maxStep, notify]);
+  }, [controlledStep, internalStep, maxStep, notify]);
   return { step, isLive, moveTo };
 }
 
@@ -2631,6 +2639,16 @@ var Lens = ({
   );
   const stepCount = Math.max(1, cursorPositions.length);
   const maxStep = Math.max(0, stepCount - 1);
+  const cursorPort = useMemo7(() => openLensCursor(cursorPositions), [cursorPositions]);
+  const stepper = useMemo7(
+    () => ({
+      back: (from) => cursorPort.prev(from).step,
+      forward: (from) => cursorPort.next(from).step,
+      toFirst: (from) => cursorPort.first(from).step,
+      toLast: (from) => cursorPort.last(from).step
+    }),
+    [cursorPort]
+  );
   const describeStep = useCallback5(
     (n) => {
       const p = cursorPositions[n];
@@ -2651,7 +2669,8 @@ var Lens = ({
     controlledStep,
     onStepChange,
     maxStep,
-    describe: describeStep
+    describe: describeStep,
+    port: cursorPort
   });
   useLensNavigator({
     positions: cursorPositions,
@@ -2701,6 +2720,7 @@ var Lens = ({
           focusSeq: focusStep,
           onFocusChange: handleFocusChange,
           isLive,
+          stepper,
           liveStreamLine
         }
       )
@@ -2722,6 +2742,8 @@ var Lens = ({
         focusStep,
         onFocusChange: handleFocusChange,
         isLive,
+        stepper,
+        cursorPort,
         stepStrip,
         showSummary,
         liveStreamLine,
@@ -2809,6 +2831,8 @@ var EngineerView = ({
   cursorRuntimeStageId,
   toolChoice,
   granularity,
+  stepper,
+  cursorPort,
   slots
 }) => {
   const bands = useMemo7(
@@ -3048,16 +3072,10 @@ var EngineerView = ({
   const DetailSlot = slots?.detail;
   const jumpToRuntimeStageId = useCallback5(
     (runtimeStageId) => {
-      const exact = cursorPositions.findIndex((p) => p.runtimeStageId === runtimeStageId);
-      if (exact >= 0) {
-        onFocusChange(exact);
-        return;
-      }
-      const stagePart = runtimeStageId.split("#")[0];
-      const byStage = cursorPositions.findIndex((p) => p.runtimeStageId.split("#")[0] === stagePart);
-      if (byStage >= 0) onFocusChange(byStage);
+      const to = cursorPort.toAddress(focusStep, runtimeStageId);
+      if (to.ok && to.step !== void 0) onFocusChange(to.step);
     },
-    [cursorPositions, onFocusChange]
+    [cursorPort, focusStep, onFocusChange]
   );
   return /* @__PURE__ */ jsxs8(
     "div",
@@ -3109,7 +3127,8 @@ var EngineerView = ({
             total,
             focusSeq: focusStep,
             onFocusChange,
-            isLive
+            isLive,
+            stepper
           }
         ),
         granularity === "group" && frameworkHiddenCount > 0 && /* @__PURE__ */ jsxs8(
@@ -3899,6 +3918,7 @@ var AnalystView = ({
   focusSeq,
   onFocusChange,
   isLive,
+  stepper,
   liveStreamLine
 }) => {
   return /* @__PURE__ */ jsxs8("div", { style: { display: "grid", gap: 16 }, children: [
@@ -3909,7 +3929,8 @@ var AnalystView = ({
         total,
         focusSeq,
         onFocusChange,
-        isLive
+        isLive,
+        stepper
       }
     ),
     /* @__PURE__ */ jsx9(Card, { title: "Commentary", children: /* @__PURE__ */ jsxs8("div", { style: { fontSize: 13, lineHeight: 1.6, fontFamily: T.fontSans }, children: [
@@ -4172,4 +4193,4 @@ export {
   WhereFrom,
   Lens
 };
-//# sourceMappingURL=chunk-LRGT7UQL.js.map
+//# sourceMappingURL=chunk-A4EIPCLY.js.map