agentfootprint-lens 0.35.0 → 0.36.0

package/README.md

@@ -503,6 +503,64 @@ 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.
+
+---
+
 ## Theming
 
 **Lens inherits theme tokens from your app via CSS variables.** Set `--fp-*`
@@ -614,6 +672,25 @@ 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). |
+
+### `<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