agentfootprint-lens 0.35.0 → 0.37.0

package/README.md

@@ -503,6 +503,163 @@ pane.
 
 ---
 
+## Scrubbing by group — the active group is a named place
+
+One causal trace, replayed at two zoom levels. On the **per-step** ruler each
+commit is a stop; on the **grouped** ruler each boundary is a stop, and ◀ ▶ moves
+a whole group at a time.
+
+The chart used to paint both the same way, and that was wrong for the second one.
+A stage's styling is by TYPE — the LLM call carries a hero emphasis (accent
+border, tint, glow) and the cursor's one node pulses — so landing on a group of
+six nodes pulled the eye to the LLM box. The group, the thing the ruler had
+actually moved by, never read as the position at all.
+
+Pass `granularity="group"` and it does:
+
+- **one accent for every member.** An LLM call, a tool and a context pill light
+  identically — same tint, same intensity. What a node IS stays legible in its
+  icon and its shape; how loud it is no longer depends on its type.
+- **everything else recedes uniformly** — one dim, not a second ranking.
+- **a boundary is drawn around the members**, from their real measured positions,
+  with the group's **name** on its top edge. Scrubbing group to group animates it
+  (and doesn't, under `prefers-reduced-motion: reduce`).
+
+The name is `groupDisplayName` — the same spelling the WHAT HAPPENED boundary
+list uses. One place, one name.
+
+```tsx
+<Lens recorder={recorder} runner={runner} granularity="group" />
+```
+
+Or, in a shell that owns its own canvas and its own cursor:
+
+```tsx
+import { LensFlow, useChartGroup } from 'agentfootprint-lens';
+
+function WhyLensChart({ recorder, chart, cursorCommitIdx }) {
+  // The group the cursor stands in, as chart node ids. Derived from the
+  // boundary ranges the grouped ruler already computes its stops from —
+  // no extra fetch, no second cursor.
+  const group = useChartGroup(recorder, cursorCommitIdx);
+  return <LensFlow chart={chart} granularity="group" activeGroup={group} />;
+}
+```
+
+`granularity` defaults to `'step'`, and on that path nothing changes: no classes,
+no boundary, the same chart the Flow Lens has always drawn. `'group'` at a commit
+no boundary encloses also renders as `'step'` — a mode with nothing to draw draws
+nothing, rather than boxing the whole chart.
+
+Restyle it with one variable (`--lens-group-accent`, falling back to
+`--fp-group-accent`), or target the classes directly: `.lens-group-node--member`,
+`.lens-group-node--outsider`, `.lens-group-boundary`, `.lens-group-boundary-name`.
+
+Headless: `activeChartGroup({ groups, commits, commitIdx })` on
+`agentfootprint-lens/core` is the pure function behind the hook — same answer for
+a Vue or CLI shell.
+
+---
+
+## Driving the cursor from your app
+
+**Omitting these props keeps the lens self-driving.** It holds the position
+itself, follows the live run, and needs nothing from you — that is the default
+and it has not changed.
+
+Pass `step` and you own the cursor. That is the difference between a lens that
+happens to be on your page and a lens that is part of your app: two tabs can
+show the same moment, a "jump to the failure" button in your own UI can move it,
+and switching tabs no longer loses the position.
+
+```tsx
+function Debugger({ recorder, runner }) {
+  // ONE cursor, held by you. Both lenses show the same moment.
+  const [step, setStep] = useState(0);
+
+  return (
+    <>
+      <Lens recorder={recorder} runner={runner} step={step} onStepChange={setStep} />
+      <Lens recorder={recorder} runner={runner} step={step} onStepChange={setStep} view="analyst" />
+      <button onClick={() => setStep(0)}>Back to the start</button>
+    </>
+  );
+}
+```
+
+Just want to *watch* the cursor? Pass `onStepChange` alone. The lens keeps
+owning the state and calls you on every move — the same contract
+`<TraceExplorerShell onSelectionChange>` has in `footprint-explainable-ui`.
+
+### The unit is a step, and the callback carries the rest
+
+A **step** is one stop on the lens's scrub axis — the same number the transport
+counts ("3 / 12"), the same one the WHAT HAPPENED rail dots. Valid values are
+`0 … totalSteps - 1`, and `totalSteps` **grows** while a run is live.
+
+Every call hands you the other two units of the same position, so you never
+invert the mapping yourself:
+
+```ts
+onStepChange(step, at)
+// at = { step, totalSteps, runtimeStageId, commitIdx, label, kind?, clamped }
+```
+
+- `at.runtimeStageId` — footprintjs's address, the string
+  `<TraceExplorerShell selectedRuntimeStageId>` and `<RunSlider cursorRuntimeStageId>` take.
+- `at.commitIdx` — the commit-log index the position anchors to.
+
+Why the step is the controlled unit and not one of those: it is the only one
+that is **one-to-one** with a position the lens can show. A group's start and
+its end are the same group, so "Run · start" and "Run · end" are both
+`__root__#0`; a parallel fork's branches open at the same commit. Address the
+cursor by either and the second of every such pair becomes unreachable — half
+the positions silently unselectable, which is the exact failure this prop
+exists to prevent.
+
+Move it out of range and the lens **clamps and says so**: it renders the nearest
+real position, calls `onStepChange(clamped, { clamped: true })`, and warns once
+on the console. It clamps rather than refuses because the axis grows under you —
+a step you stored from a finished run is a perfectly good value that the same
+run, earlier, does not have yet. Store what the callback hands back and the two
+cursors agree again.
+
+Every mover reports: the step strip, ◀ ▶ ⟳Live, the arrow keys, a chart node
+click, a WHAT HAPPENED moment, a provenance jump, and the auto-advance that
+follows a live run. One cursor, one funnel — a mover that moved without telling
+you would be a second cursor wearing the first one's clothes.
+
+---
+
+## Rendering your own detail pane
+
+`slots.detail` replaces the CONTENT of the shipped right column. The column
+itself — its width, its border, its collapse pill, its cursor — is unchanged.
+Omit `slots` and the built-in timeline renders exactly as before.
+
+```tsx
+const Detail: React.FC<LensDetailSlotProps> = ({ step, cursorRuntimeStageId, node, onNavigate }) => (
+  <div>
+    <h3>{node?.label ?? 'nothing focused'}</h3>
+    <code>{cursorRuntimeStageId}</code>
+    <button onClick={() => onNavigate(0)}>rewind</button>
+  </div>
+);
+
+<Lens recorder={recorder} runner={runner} slots={{ detail: Detail }} />
+```
+
+The slot receives the cursor in every unit (`step`, `totalSteps`,
+`cursorRuntimeStageId`, `commitIdx`, `label`, `kind`), the `StepNode` it sits on
+and the ones that ran inside its scope (`node`, `relatedNodes`), the `recorder`
+for anything else, and `onNavigate` — the same funnel every built-in mover uses,
+so your pane moves the ONE cursor rather than starting a second one.
+
+Keep the slots object stable across renders (module scope or `useMemo`), same as
+`<TraceExplorerShell slots>`.
+
+---
+
 ## Theming
 
 **Lens inherits theme tokens from your app via CSS variables.** Set `--fp-*`
@@ -579,9 +736,22 @@ if a strict CSP blocks the automatic injection.
 
 ## Responsive
 
-Lens resizes to whatever space you give it. Below ~640px wide it stacks panels
-vertically (like `<ExplainableShell>` does). Drop it in a splitter, a drawer, or
-a full-screen tab — no config needed.
+Lens resizes to whatever space you give it. The engineer view is a chart column
+beside an inspector with a 300px minimum, and below **`LENS_NARROW_BREAKPOINT`
+(690px of available row width)** that pair stops fitting — so the columns
+**stack** instead of clipping. Nothing is hidden and nothing is cut off; the
+same panes are read top to bottom instead of left to right. A split panel
+dragged down to 392px gets a readable lens, not a sliver of one.
+
+The threshold is exported, so a shell that lays out around Lens can use the same
+number rather than guessing it:
+
+```ts
+import { LENS_NARROW_BREAKPOINT, isNarrowRow } from 'agentfootprint-lens';
+```
+
+Drop it in a splitter, a drawer, or a full-screen tab — no config needed, both
+themes.
 
 ---
 
@@ -614,6 +784,28 @@ graph in one call. Returns an unsubscribe. Call it once per run.
 | `chart` | `LensFlowProps['chart']?` | Render YOUR graph instead of the derived one. |
 | `stepGraph` | `StepGraph?` | Bring your own step graph; by default Lens uses the recorder's. |
 | `toolChoice` | `ToolChoiceSource?` | Mount the per-iteration tool-choice panel. |
+| `granularity` | `'step' \| 'group'?` | Which ruler is scrubbing the chart. `'group'` paints the cursor's group as a named place. Default `'step'`. See [Scrubbing by group](#scrubbing-by-group--the-active-group-is-a-named-place). |
+| `step` | `number?` | Controlled cursor. **Omit it and the lens is self-driving, exactly as before.** Pass it and you own the position; out-of-range values are clamped and reported. See [Driving the cursor](#driving-the-cursor-from-your-app). |
+| `onStepChange` | `(step, at) => void?` | Fires on every cursor move — required for movement in controlled mode, an observation hook otherwise. `at` carries `runtimeStageId`, `commitIdx`, `label`, `kind` and `clamped`. |
+| `slots` | `LensSlots?` | Slot overrides. `slots.detail` renders your content in the shipped right column. Omit for the built-in timeline. See [Rendering your own detail pane](#rendering-your-own-detail-pane). |
+
+### `<LensFlow>` — the chart canvas on its own
+
+The chart without the shell, for consumers who own their layout and their
+cursor. Takes `chart`, the runtime overlay, the cursor, and — for the grouped
+ruler — `granularity="group"` plus `activeGroup` (from `useChartGroup`). Every
+other prop is unchanged by group mode.
+
+### `useChartGroup(recorder, commitIdx, options?)` / `activeChartGroup(...)`
+
+The group the cursor stands in, resolved to CHART NODE IDS: the boundary's
+commit range read off the recording, each commit's `runtimeStageId` stripped of
+its `#executionIndex` (the id rule every chart-click and co-active highlight in
+the ecosystem already uses), plus the group's own mount. Returns `undefined`
+when no boundary encloses the cursor. `options.includeRoot` opts into the
+synthetic Run root, which is off by default because a box around the whole chart
+states nothing. `activeChartGroup` is the pure, React-free twin on
+`agentfootprint-lens/core`.
 
 ### `observeRecording(recording, options?)`
 

package/dist/{chunk-PBRAJNVI.js → chunk-EGU4GZVH.js}

@@ -2296,6 +2296,126 @@ function selectToolChoiceCall(calls, cursorRuntimeStageId, cursorKind) {
   return within ?? prev;
 }
 
+// src/core/group/groupDisplayName.ts
+function groupDisplayName(label) {
+  const named = label.subflowName ?? label.compositionName ?? label.primitiveKind;
+  if (named !== void 0 && named !== "") return named;
+  if (label.type === "run.entry") return "Run";
+  return label.runtimeStageId;
+}
+function groupDisplayNameForLabel(label) {
+  return groupDisplayName(label);
+}
+
+// src/core/group/Group.ts
+function groupContainsCommit(group, commitIdx) {
+  if (commitIdx < group.opensAtCommitIdx) return false;
+  if (group.closesAtCommitIdx === void 0) return true;
+  return commitIdx <= group.closesAtCommitIdx;
+}
+
+// src/core/group/activeChartGroup.ts
+function chartNodeIdOf(runtimeStageId) {
+  const hash = runtimeStageId.lastIndexOf("#");
+  return hash < 0 ? runtimeStageId : runtimeStageId.slice(0, hash);
+}
+function activeChartGroup(args) {
+  const { groups, commits, commitIdx, includeRoot = false } = args;
+  if (!Number.isFinite(commitIdx) || commitIdx < 0) return void 0;
+  let best;
+  for (const group of groups) {
+    if (group.isRoot && !includeRoot) continue;
+    if (!groupContainsCommit(group, commitIdx)) continue;
+    if (best === void 0) {
+      best = group;
+      continue;
+    }
+    if (group.depth > best.depth) best = group;
+    else if (group.depth === best.depth && group.opensAtCommitIdx >= best.opensAtCommitIdx) best = group;
+  }
+  if (best === void 0) return void 0;
+  const memberNodeIds = /* @__PURE__ */ new Set();
+  memberNodeIds.add(chartNodeIdOf(best.runtimeGroupId));
+  const from = Math.max(0, best.opensAtCommitIdx);
+  const to = Math.min(commits.length - 1, best.closesAtCommitIdx ?? commits.length - 1);
+  for (let i = from; i <= to; i++) {
+    const rid = commits[i]?.runtimeStageId;
+    if (rid === void 0 || rid === "") continue;
+    memberNodeIds.add(chartNodeIdOf(rid));
+  }
+  return {
+    runtimeGroupId: best.runtimeGroupId,
+    name: best.name,
+    memberNodeIds,
+    opensAtCommitIdx: best.opensAtCommitIdx,
+    closesAtCommitIdx: best.closesAtCommitIdx,
+    depth: best.depth
+  };
+}
+
+// src/core/group/buildGroups.ts
+function samePath(a, b) {
+  return a.length === b.length && a.every((s, i) => s === b[i]);
+}
+function buildGroups(boundaryIndex) {
+  const all = boundaryIndex.overlapping(0, Number.MAX_SAFE_INTEGER);
+  if (all.length === 0) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (let i = 0; i < all.length; i++) {
+    const entry = all[i];
+    const label = entry.label;
+    if (seen.has(label.runtimeStageId)) continue;
+    seen.add(label.runtimeStageId);
+    let parentGroupId;
+    if (label.type === "subflow.entry") {
+      const enclosing = boundaryIndex.enclosing(entry.startIdx);
+      const parentPath = label.subflowPath.slice(0, -1);
+      for (let j = enclosing.length - 1; j >= 0; j--) {
+        const cand = enclosing[j].label;
+        if (cand.runtimeStageId === label.runtimeStageId) continue;
+        if (samePath(cand.subflowPath, parentPath)) {
+          parentGroupId = cand.runtimeStageId;
+          break;
+        }
+      }
+      if (parentGroupId === void 0) {
+        for (let j = enclosing.length - 1; j >= 0; j--) {
+          const cand = enclosing[j].label;
+          if (cand.runtimeStageId === label.runtimeStageId) continue;
+          parentGroupId = cand.runtimeStageId;
+          break;
+        }
+      }
+    } else if (label.type === "composition.start") {
+      const enclosing = boundaryIndex.enclosing(entry.startIdx);
+      for (let j = enclosing.length - 1; j >= 0; j--) {
+        const cand = enclosing[j].label;
+        if (cand.runtimeStageId === label.runtimeStageId) continue;
+        parentGroupId = cand.runtimeStageId;
+        break;
+      }
+    }
+    const isRoot = label.type === "run.entry";
+    const name = groupDisplayNameForLabel(label);
+    const compositionKind = label.type === "composition.start" ? label.compositionKind : void 0;
+    result.push({
+      runtimeGroupId: label.runtimeStageId,
+      name,
+      parentGroupId,
+      subflowPath: label.subflowPath,
+      depth: label.depth,
+      opensAtCommitIdx: entry.startIdx,
+      closesAtCommitIdx: entry.endIdx,
+      isRoot,
+      ...compositionKind !== void 0 ? { compositionKind } : {},
+      ...label.slotKind !== void 0 ? { slotKind: label.slotKind } : {},
+      ...label.primitiveKind !== void 0 ? { primitiveKind: label.primitiveKind } : {}
+    });
+  }
+  return result;
+}
+
 // src/core/translate/helpers/makeNodeId.ts
 function makeRootNodeId(kind, id) {
   return `${kind.toLowerCase()}:${id}`;
@@ -3486,6 +3606,12 @@ export {
   selectCommentaryAt,
   selectCommentaryRanges,
   selectToolChoiceCall,
+  groupDisplayName,
+  groupDisplayNameForLabel,
+  groupContainsCommit,
+  chartNodeIdOf,
+  activeChartGroup,
+  buildGroups,
   makeRootNodeId,
   makeChildNodeId,
   translateAgent,
@@ -3525,4 +3651,4 @@ export {
   decisionSentence,
   isConsentDecision
 };
-//# sourceMappingURL=chunk-PBRAJNVI.js.map
+//# sourceMappingURL=chunk-EGU4GZVH.js.map