agentfootprint-lens 0.44.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-OQRL3II6.js → chunk-2UOQEE4U.js}

@@ -6,7 +6,7 @@ import {
   describeReceived,
   refusalDestinationFor,
   useNarrowRow
-} from "./chunk-QNMA25X5.js";
+} from "./chunk-AUGRQKRL.js";
 import {
   selectSkillBeatAt,
   selectSkillBeats,
@@ -608,7 +608,7 @@ var CAUSE_LABEL = {
   stay: "nothing moved it",
   none: "no skill was in play"
 };
-function RouteDecisionCard({ beat, lens }) {
+function RouteDecisionCard({ beat, turnStart, lens }) {
   return /* @__PURE__ */ jsx4(
     "aside",
     {
@@ -736,6 +736,7 @@ function RouteDecisionCard({ beat, lens }) {
             children: beat.notes.map((n, i) => /* @__PURE__ */ jsx4("li", { children: n }, i))
           }
         ),
+        turnStart !== void 0 && (turnStart.by === "intent" || turnStart.by === "continuity") && /* @__PURE__ */ jsx4(ScoreTable, { start: turnStart }),
         lens === "developer" && beat.runtimeStageId !== void 0 && /* @__PURE__ */ jsx4("div", { style: { marginTop: 8, fontFamily: T.fontMono, fontSize: 10, color: T.textMuted }, children: beat.runtimeStageId })
       ] })
     }
@@ -761,6 +762,104 @@ function Evidence({
     children
   ] });
 }
+function ScoreTable({ start }) {
+  if (start.scores.length === 0) return null;
+  const floor = start.policy?.floor;
+  const margin = start.policy?.nearTieMargin;
+  return /* @__PURE__ */ jsxs4("div", { style: { marginTop: 8 }, children: [
+    /* @__PURE__ */ jsxs4(
+      "div",
+      {
+        style: {
+          fontSize: 10,
+          letterSpacing: "0.08em",
+          textTransform: "uppercase",
+          color: T.textMuted,
+          marginBottom: 4
+        },
+        children: [
+          "Scored",
+          start.scorer ? ` by ${start.scorer}` : "",
+          floor !== void 0 ? ` \xB7 floor ${floor}` : "",
+          start.runnerUp !== void 0 && margin !== void 0 ? ` \xB7 gap ${fmt(start.runnerUp.gap)} of ${margin} needed` : ""
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsxs4(
+      "table",
+      {
+        style: { borderCollapse: "collapse", width: "100%", fontSize: 12 },
+        children: [
+          /* @__PURE__ */ jsx4(
+            "caption",
+            {
+              style: {
+                captionSide: "top",
+                textAlign: "left",
+                fontSize: 11,
+                color: T.textMuted,
+                paddingBottom: 3
+              },
+              children: "Every candidate this turn was scored against, best first."
+            }
+          ),
+          /* @__PURE__ */ jsx4("tbody", { children: start.scores.map((row) => {
+            const belowFloor = floor !== void 0 && row.score <= floor;
+            const won = row.id === start.to;
+            return /* @__PURE__ */ jsxs4("tr", { children: [
+              /* @__PURE__ */ jsxs4(
+                "td",
+                {
+                  style: {
+                    padding: "2px 6px 2px 0",
+                    color: belowFloor ? T.textMuted : T.textPrimary,
+                    fontWeight: won ? 700 : 400,
+                    fontFamily: T.fontMono
+                  },
+                  children: [
+                    won ? "\u2192 " : "   ",
+                    row.id
+                  ]
+                }
+              ),
+              /* @__PURE__ */ jsx4(
+                "td",
+                {
+                  style: {
+                    padding: "2px 6px",
+                    textAlign: "right",
+                    fontFamily: T.fontMono,
+                    color: belowFloor ? T.textMuted : T.textPrimary
+                  },
+                  children: fmt(row.score)
+                }
+              ),
+              /* @__PURE__ */ jsxs4(
+                "td",
+                {
+                  style: {
+                    padding: "2px 6px",
+                    textAlign: "right",
+                    fontFamily: T.fontMono,
+                    color: T.textMuted
+                  },
+                  children: [
+                    Math.round(row.relevance * 100),
+                    "%"
+                  ]
+                }
+              ),
+              /* @__PURE__ */ jsx4("td", { style: { padding: "2px 0 2px 6px", color: T.textMuted, fontSize: 11 }, children: belowFloor ? "below floor" : won ? "" : "beaten" })
+            ] }, row.id);
+          }) })
+        ]
+      }
+    )
+  ] });
+}
+function fmt(n) {
+  return String(Math.round(n * 1e3) / 1e3);
+}
 
 // src/react/skillgraph/skillTopologyPositions.ts
 function skillTopologyPositions(nodeIds, edges) {
@@ -1123,6 +1222,10 @@ function SkillGraphDebugger({
     [beats, cursorRuntimeStageId, cursorKind]
   );
   const activeIndex = activeBeat?.index;
+  const activeTurnStart = useMemo2(
+    () => activeBeat === void 0 || route === void 0 ? void 0 : route.turns.find((t) => t.turnIndex === activeBeat.turnIndex),
+    [route, activeBeat]
+  );
   const topology = useMemo2(
     () => route !== void 0 ? selectSkillTopology({
       route,
@@ -1264,7 +1367,14 @@ function SkillGraphDebugger({
                     onPickSkill: jumpToSkill
                   }
                 ) }),
-                /* @__PURE__ */ jsx6(RouteDecisionCard, { ...activeBeat !== void 0 ? { beat: activeBeat } : {}, lens })
+                /* @__PURE__ */ jsx6(
+                  RouteDecisionCard,
+                  {
+                    ...activeBeat !== void 0 ? { beat: activeBeat } : {},
+                    ...activeTurnStart !== void 0 ? { turnStart: activeTurnStart } : {},
+                    lens
+                  }
+                )
               ]
             }
           ),
@@ -1382,4 +1492,4 @@ export {
   SKILL_GRAPH_READS,
   SkillGraphDebugger
 };
-//# sourceMappingURL=chunk-OQRL3II6.js.map
+//# sourceMappingURL=chunk-2UOQEE4U.js.map