agentfootprint-lens 0.72.1 → 0.73.0

package/README.md

@@ -30,6 +30,11 @@ agentfootprint = **2 primitives (LLM, Agent) + 3 compositions (Sequence, Paralle
 npm install agentfootprint agentfootprint-lens
 ```
 
+Lens requires `footprint-explainable-ui >=0.34.0 <1.0.0`. Earlier versions
+lack renderer APIs used by Lens even if an older peer range accepted them.
+The minimum and current tested renderer versions are checked with packed
+installs on both React 18 and React 19; an import failure fails the check.
+
 ```tsx
 import { useMemo } from 'react';
 import { Agent } from 'agentfootprint';
@@ -174,6 +179,26 @@ One mental model. The runner does the work; Lens watches.
 
 ---
 
+## Trust boundaries and source prefixes
+
+`TrustBoundaryView` reads the optional version-1 `TrustBoundaries` recorder bundle. It shows observed permission, policy, middleware, and credential facts with retained/dropped counts. It does not infer missing decisions from a finished execution tree or certify security or regulatory compliance.
+
+Share the same cursor with execution replay to inspect a fact's actual source location:
+
+```tsx
+const shared = useSharedCursor(recorder, recording.snapshot);
+return <>
+  <TrustBoundaryView snapshot={recording.snapshot} shared={shared} />
+  <Lens recorder={recorder} shared={shared} />
+</>;
+```
+
+Import these components and the hook from `agentfootprint-lens`. A fact's `sourcePosition` identifies its exact log, complete runtime subflow path, and inclusive committed prefix (`-1` means the base before any commit). Source navigation does not substitute an enclosing stage or the final state. Missing positions remain **Unplaced**; absent, incompatible, or damaged logs remain unavailable.
+
+Metadata-only exporters should mark their snapshot or selected child context with `stateValuesWithheld: true`. Lens then distinguishes a known source location from unavailable state values. For full-content snapshots, prefix folding requires the recorded base and intact prefix; a missing base never falls back to `globalContext`. **Show final execution step** explicitly leaves source-prefix mode. Older recorder bundles and manually supplied legacy cursors remain readable without source navigation.
+
+Headless consumers can import `readTrustBoundaries`, `readSourcePosition`, and `resolveSourcePrefix` from `agentfootprint-lens/core`. See [the reader contract](src/core/trustBoundaries/README.md) and [cursor ownership](src/core/cursor/README.md) for limits and failure codes.
+
 ## Watching a run that already finished
 
 A recording is a run you kept. It is exactly THREE things — miss one and one
@@ -852,6 +877,15 @@ its own last stop; a new recorder drops the held address. Headless pieces on
 `/core`: `stepForAddress`, `cursorForAddress`, `addressOf`. Design and the
 facts the fixtures taught: docs/design/2026-09-shared-cursor.md.
 
+If the held address has no position on a child or filtered axis, Lens says so
+instead of displaying that axis's first stage. It does not fold stage state or
+render a final answer for that missing position. Return to the parent view to
+recover the same address, or explicitly choose a recorded stop to move it.
+With a shared cursor, **Latest** is a jump to the current last stop, not a
+subscription to future stops. Before any explicit selection, the shared cursor
+continues to derive the growing end. The older numeric `step` contract keeps
+its existing clamp and live-follow behavior.
+
 ## Time travel through one port
 
 **Nothing to do — this is how the cursor already moves.** Read it if you are
@@ -1512,14 +1546,9 @@ legend.source;                                  // 'structure' | 'log'
 legend.entries.map((e) => [e.label, e.hits]);   // [['Iteration', 2], ['LLM turn', 2], ['audit', 0], …]
 
 const axis = tagAxisPositions(snapshot, ['milestone:llm-turn'], scrubAxisFor(recorder, 'group'));
-axis?.map((p) => p.label);                      // ['Run · start', 'LLM turn 1', 'LLM turn 2', 'Run · end']
+axis.map((p) => p.label);                       // ['Run · start', 'LLM turn 1', 'LLM turn 2', 'Run · end']
 ```
 
-**Older peers.** `tagStops` (footprintjs 9.21) and `milestoneFromTags`
-(agentfootprint 9.90) are read off their module namespaces at call time: on a
-peer without them the legend prints raw names, the strip says *tag axis
-unavailable*, and nothing else changes. The peer ranges are untouched.
-
 ---
 
 ## Rendering your own detail pane
@@ -1895,12 +1924,14 @@ store's availability is a label. Headless: `bookmarkKey` · `toSidecar` ·
 
 ### `<TagPicker>` — the declared-tag legend and picker
 
-`<TagPicker legend picked onPick available>`. The engineer view mounts it above
+`<TagPicker legend picked onPick available?>`. The engineer view mounts it above
 the chart on `granularity="group"` at the root level; `legend` is
 `tagLegend(structure, snapshot)` (`source: 'structure' | 'log'`), a pick is a
 list of tag names the lens hands to `tagAxisPositions(snapshot, picked, base)`
 (footprintjs 9.21's `tagStops`). Picking never moves the cursor; it changes the
-list the one cursor is a step into.
+list the one cursor is a step into. `available` defaults to `true`; `false` holds
+the strip read-only — the legend still shows, every chip is disabled, and the
+strip says so (`TAG_PICKER_LABELS.tagAxisUnavailable`).
 
 ### `<BugReportButton>` — report a bug with the run attached, consent first
 

package/dist/{Lens-DaElQv4z.d.cts → Lens-dAaGjB6z.d.ts}

@@ -3,11 +3,11 @@ import { ToolChoiceCall, ToolChoiceSummary, AnswerAccount, AnswerAccountShownLea
 import * as agentfootprint from 'agentfootprint';
 import { CommentaryTemplates } from 'agentfootprint';
 import React__default, { Ref } from 'react';
-import { h as NavigationResult, C as CursorPosition, m as LensRecorder, a as LensCursor } from './lensCursorPort-Djm3W7K1.cjs';
-import { C as ChartGroupHighlight, H as Humanizer, b as BookmarkStore } from './tagAxis-CijjA_6P.cjs';
+import { h as NavigationResult, C as CursorPosition, n as LensRecorder, a as LensCursor } from './lensCursorPort-nD3C6iQs.js';
+import { C as ChartGroupHighlight, H as Humanizer, b as BookmarkStore } from './tagAxis-Cgk6vlcY.js';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
-import { L as LensCursorAt, S as SharedCursor } from './useSharedCursor-lgpWw94t.cjs';
+import { L as LensCursorAt, S as SharedCursor } from './useSharedCursor-BdzFNO_C.js';
 
 /**
  * LensFlow — the canonical Lens chart renderer.
@@ -504,9 +504,10 @@ interface LensProps {
      * 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.
+     * still fires for explicit moves. An address this axis cannot hold shows
+     * no position; it is never corrected to a neighbouring stop. Axis changes
+     * and drills preserve the address. The transport's Latest button jumps to
+     * the current end; that held address stays fixed if the recording grows.
      *
      * ```tsx
      * const shared = useSharedCursor(recorder);
@@ -680,6 +681,12 @@ interface LensDetailSlotProps {
      */
     readonly cursor?: LensCursor;
 }
+/**
+ * Source prefixes are not stage stops. Keep them outside the legacy stage
+ * shell so its clamp, final-answer slots and state folds cannot show a future
+ * state while an exact source prefix (including -1) is held by the host.
+ * Entering this mode resets local visual drill state, not the shared target.
+ */
 declare const Lens: React__default.FC<LensProps>;
 
 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-lTf_UA0N.d.ts → Lens-v6JPZWcg.d.cts}

@@ -3,11 +3,11 @@ import { ToolChoiceCall, ToolChoiceSummary, AnswerAccount, AnswerAccountShownLea
 import * as agentfootprint from 'agentfootprint';
 import { CommentaryTemplates } from 'agentfootprint';
 import React__default, { Ref } from 'react';
-import { h as NavigationResult, C as CursorPosition, m as LensRecorder, a as LensCursor } from './lensCursorPort-Djm3W7K1.js';
-import { C as ChartGroupHighlight, H as Humanizer, b as BookmarkStore } from './tagAxis-ClhV50a2.js';
+import { h as NavigationResult, C as CursorPosition, n as LensRecorder, a as LensCursor } from './lensCursorPort-nD3C6iQs.cjs';
+import { C as ChartGroupHighlight, H as Humanizer, b as BookmarkStore } from './tagAxis-COX6o7DJ.cjs';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
-import { L as LensCursorAt, S as SharedCursor } from './useSharedCursor-CdXdsXvD.js';
+import { L as LensCursorAt, S as SharedCursor } from './useSharedCursor-DJTQSH0y.cjs';
 
 /**
  * LensFlow — the canonical Lens chart renderer.
@@ -504,9 +504,10 @@ interface LensProps {
      * 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.
+     * still fires for explicit moves. An address this axis cannot hold shows
+     * no position; it is never corrected to a neighbouring stop. Axis changes
+     * and drills preserve the address. The transport's Latest button jumps to
+     * the current end; that held address stays fixed if the recording grows.
      *
      * ```tsx
      * const shared = useSharedCursor(recorder);
@@ -680,6 +681,12 @@ interface LensDetailSlotProps {
      */
     readonly cursor?: LensCursor;
 }
+/**
+ * Source prefixes are not stage stops. Keep them outside the legacy stage
+ * shell so its clamp, final-answer slots and state folds cannot show a future
+ * state while an exact source prefix (including -1) is held by the host.
+ * Entering this mode resets local visual drill state, not the shared target.
+ */
 declare const Lens: React__default.FC<LensProps>;
 
 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/{chunk-WIQVUP5C.js → chunk-4XZHSL5T.js}

@@ -1,3 +1,130 @@
+// src/core/group/resolveNavigation.ts
+function execIndex(runtimeStageId) {
+  const hash = runtimeStageId.lastIndexOf("#");
+  if (hash < 0) return void 0;
+  const n = Number(runtimeStageId.slice(hash + 1));
+  return Number.isInteger(n) && n >= 0 ? n : void 0;
+}
+function resolveNavigation(positions, runtimeStageId) {
+  if (typeof runtimeStageId !== "string" || runtimeStageId === "") {
+    return {
+      ok: false,
+      reason: "no-id",
+      message: `No address was given. navigateTo needs a runtimeStageId \u2014 footprintjs's own address for a stage, like "llm#3" or "sf-tools/search#7".`
+    };
+  }
+  if (positions.length === 0) {
+    return {
+      ok: false,
+      reason: "empty-axis",
+      message: "This ruler has no stops yet, so there is nowhere to move. A run that has not committed a stage has no positions to scrub."
+    };
+  }
+  const exact = positions.findIndex((p) => p.runtimeStageId === runtimeStageId);
+  if (exact >= 0) {
+    return {
+      ok: true,
+      step: exact,
+      runtimeStageId,
+      match: "exact",
+      label: positions[exact]?.label ?? ""
+    };
+  }
+  const target = execIndex(runtimeStageId);
+  if (target === void 0) {
+    return {
+      ok: false,
+      reason: "not-on-axis",
+      message: `"${runtimeStageId}" is not a stop on this ruler, and it carries no #executionIndex, so no nearby stop can be worked out from it either. A runtimeStageId looks like "llm#3".`
+    };
+  }
+  const scopes = [];
+  const base = runtimeStageId.split("#")[0] ?? "";
+  for (let cut = base.lastIndexOf("/"); cut > 0; cut = base.lastIndexOf("/", cut - 1)) {
+    scopes.push(base.slice(0, cut));
+  }
+  for (const scope of scopes) {
+    let best = -1;
+    let bestIdx = -1;
+    for (let i = 0; i < positions.length; i += 1) {
+      const id = positions[i]?.runtimeStageId ?? "";
+      if ((id.split("#")[0] ?? "") !== scope) continue;
+      const idx = execIndex(id);
+      if (idx === void 0 || idx > target || idx <= bestIdx) continue;
+      best = i;
+      bestIdx = idx;
+    }
+    if (best >= 0) {
+      return {
+        ok: true,
+        step: best,
+        runtimeStageId: positions[best]?.runtimeStageId ?? "",
+        match: "enclosing",
+        label: positions[best]?.label ?? ""
+      };
+    }
+  }
+  let prev = -1;
+  let prevIdx = -1;
+  for (let i = 0; i < positions.length; i += 1) {
+    const idx = execIndex(positions[i]?.runtimeStageId ?? "");
+    if (idx === void 0 || idx > target || idx <= prevIdx) continue;
+    prev = i;
+    prevIdx = idx;
+  }
+  if (prev >= 0) {
+    const at = positions[prev];
+    return {
+      ok: false,
+      reason: "not-on-axis",
+      message: `"${runtimeStageId}" is not a stop on this ruler. The nearest stop before it is "${at.runtimeStageId}" (step ${prev}${at.label ? `, ${at.label}` : ""}) \u2014 offered, not taken: moving there is your call.`,
+      nearest: { runtimeStageId: at.runtimeStageId, step: prev, label: at.label }
+    };
+  }
+  return {
+    ok: false,
+    reason: "before-first-stop",
+    message: `"${runtimeStageId}" comes before this ruler's first stop, so there is nothing at or before it to stand on. The cursor did not move.`
+  };
+}
+
+// src/core/cursor/foldAt.ts
+function foldCommitIdxOf(position) {
+  const opening = position.kind === "group-start" || position.kind === "user-in";
+  return opening && position.depth === 0 ? -1 : position.commitIdx;
+}
+function foldCursorOf(at) {
+  return { runtimeStageId: at.runtimeStageId, commitIdx: at.foldCommitIdx ?? at.commitIdx };
+}
+
+// src/core/cursor/lensCursor.ts
+var EMPTY_READING = Object.freeze({
+  step: 0,
+  totalSteps: 0,
+  runtimeStageId: "",
+  commitIdx: -1,
+  foldCommitIdx: -1,
+  label: ""
+});
+function lensCursorFrom(positions, step, moveTo) {
+  const here = positions[step];
+  const at = here === void 0 ? Object.freeze({ ...EMPTY_READING, step, totalSteps: positions.length }) : Object.freeze({
+    step,
+    totalSteps: positions.length,
+    runtimeStageId: here.runtimeStageId,
+    commitIdx: here.commitIdx,
+    foldCommitIdx: foldCommitIdxOf(here),
+    label: here.label,
+    ...here.kind !== void 0 ? { kind: here.kind } : {}
+  });
+  return Object.freeze({
+    at,
+    total: positions.length,
+    resolve: (runtimeStageId) => resolveNavigation(positions, runtimeStageId),
+    moveTo
+  });
+}
+
 // src/core/group/groupDisplayName.ts
 function groupDisplayName(label) {
   const named = label.subflowName ?? label.compositionName ?? label.primitiveKind;
@@ -222,133 +349,6 @@ function buildGroups(boundaryIndex) {
   return result;
 }
 
-// src/core/group/resolveNavigation.ts
-function execIndex(runtimeStageId) {
-  const hash = runtimeStageId.lastIndexOf("#");
-  if (hash < 0) return void 0;
-  const n = Number(runtimeStageId.slice(hash + 1));
-  return Number.isInteger(n) && n >= 0 ? n : void 0;
-}
-function resolveNavigation(positions, runtimeStageId) {
-  if (typeof runtimeStageId !== "string" || runtimeStageId === "") {
-    return {
-      ok: false,
-      reason: "no-id",
-      message: `No address was given. navigateTo needs a runtimeStageId \u2014 footprintjs's own address for a stage, like "llm#3" or "sf-tools/search#7".`
-    };
-  }
-  if (positions.length === 0) {
-    return {
-      ok: false,
-      reason: "empty-axis",
-      message: "This ruler has no stops yet, so there is nowhere to move. A run that has not committed a stage has no positions to scrub."
-    };
-  }
-  const exact = positions.findIndex((p) => p.runtimeStageId === runtimeStageId);
-  if (exact >= 0) {
-    return {
-      ok: true,
-      step: exact,
-      runtimeStageId,
-      match: "exact",
-      label: positions[exact]?.label ?? ""
-    };
-  }
-  const target = execIndex(runtimeStageId);
-  if (target === void 0) {
-    return {
-      ok: false,
-      reason: "not-on-axis",
-      message: `"${runtimeStageId}" is not a stop on this ruler, and it carries no #executionIndex, so no nearby stop can be worked out from it either. A runtimeStageId looks like "llm#3".`
-    };
-  }
-  const scopes = [];
-  const base = runtimeStageId.split("#")[0] ?? "";
-  for (let cut = base.lastIndexOf("/"); cut > 0; cut = base.lastIndexOf("/", cut - 1)) {
-    scopes.push(base.slice(0, cut));
-  }
-  for (const scope of scopes) {
-    let best = -1;
-    let bestIdx = -1;
-    for (let i = 0; i < positions.length; i += 1) {
-      const id = positions[i]?.runtimeStageId ?? "";
-      if ((id.split("#")[0] ?? "") !== scope) continue;
-      const idx = execIndex(id);
-      if (idx === void 0 || idx > target || idx <= bestIdx) continue;
-      best = i;
-      bestIdx = idx;
-    }
-    if (best >= 0) {
-      return {
-        ok: true,
-        step: best,
-        runtimeStageId: positions[best]?.runtimeStageId ?? "",
-        match: "enclosing",
-        label: positions[best]?.label ?? ""
-      };
-    }
-  }
-  let prev = -1;
-  let prevIdx = -1;
-  for (let i = 0; i < positions.length; i += 1) {
-    const idx = execIndex(positions[i]?.runtimeStageId ?? "");
-    if (idx === void 0 || idx > target || idx <= prevIdx) continue;
-    prev = i;
-    prevIdx = idx;
-  }
-  if (prev >= 0) {
-    const at = positions[prev];
-    return {
-      ok: false,
-      reason: "not-on-axis",
-      message: `"${runtimeStageId}" is not a stop on this ruler. The nearest stop before it is "${at.runtimeStageId}" (step ${prev}${at.label ? `, ${at.label}` : ""}) \u2014 offered, not taken: moving there is your call.`,
-      nearest: { runtimeStageId: at.runtimeStageId, step: prev, label: at.label }
-    };
-  }
-  return {
-    ok: false,
-    reason: "before-first-stop",
-    message: `"${runtimeStageId}" comes before this ruler's first stop, so there is nothing at or before it to stand on. The cursor did not move.`
-  };
-}
-
-// src/core/cursor/foldAt.ts
-function foldCommitIdxOf(position) {
-  const opening = position.kind === "group-start" || position.kind === "user-in";
-  return opening && position.depth === 0 ? -1 : position.commitIdx;
-}
-function foldCursorOf(at) {
-  return { runtimeStageId: at.runtimeStageId, commitIdx: at.foldCommitIdx ?? at.commitIdx };
-}
-
-// src/core/cursor/lensCursor.ts
-var EMPTY_READING = Object.freeze({
-  step: 0,
-  totalSteps: 0,
-  runtimeStageId: "",
-  commitIdx: -1,
-  foldCommitIdx: -1,
-  label: ""
-});
-function lensCursorFrom(positions, step, moveTo) {
-  const here = positions[step];
-  const at = here === void 0 ? Object.freeze({ ...EMPTY_READING, step, totalSteps: positions.length }) : Object.freeze({
-    step,
-    totalSteps: positions.length,
-    runtimeStageId: here.runtimeStageId,
-    commitIdx: here.commitIdx,
-    foldCommitIdx: foldCommitIdxOf(here),
-    label: here.label,
-    ...here.kind !== void 0 ? { kind: here.kind } : {}
-  });
-  return Object.freeze({
-    at,
-    total: positions.length,
-    resolve: (runtimeStageId) => resolveNavigation(positions, runtimeStageId),
-    moveTo
-  });
-}
-
 // src/core/group/groupForRuntimeStageId.ts
 function pathOf(rid) {
   if (rid.length === 0) return [];
@@ -763,6 +763,10 @@ function scrubAxisFor(recorder, granularity, drillPath = []) {
 }
 
 export {
+  resolveNavigation,
+  foldCommitIdxOf,
+  foldCursorOf,
+  lensCursorFrom,
   groupDisplayName,
   groupDisplayNameForLabel,
   groupContainsCommit,
@@ -775,14 +779,10 @@ export {
   nextSnapStep,
   prevSnapStep,
   buildGroups,
-  resolveNavigation,
-  foldCommitIdxOf,
-  foldCursorOf,
-  lensCursorFrom,
   groupForRuntimeStageId,
   buildCommitSyncMap,
   commitAxisPositions,
   cursorPositionsAtDrill,
   scrubAxisFor
 };
-//# sourceMappingURL=chunk-WIQVUP5C.js.map
+//# sourceMappingURL=chunk-4XZHSL5T.js.map