agentfootprint-lens 0.40.0 → 0.42.0

package/README.md

@@ -76,8 +76,8 @@ changes.
 
 | import | the job |
 |---|---|
-| `agentfootprint-lens/why` | Replay a recording as the agent's own milestones. `<WhyLens recording={...} />` takes the recording straight (`recordRun()`'s `{ snapshot, events, structure }`, or the `persistRecording` envelope), validates it at mount, and mounts the shipped `<Lens>` shell on the milestone axis — plus the axis helpers (`scrubAxisFor`, `stepForCommitIdx`, `stepForRuntimeStageId`) for hosts holding one cursor across views. |
-| `agentfootprint-lens/skillgraph` | Debug how a run routed through its skills. `<SkillGraphDebugger recorder={...} />` plus its headless selectors (`selectSkillRoute`, `selectSkillBeats`, `selectSkillTopology`, `selectSkillFrameContext`, `stepForRuntimeStageId`). |
+| `agentfootprint-lens/why` | Replay a recording as the agent's own milestones. `<WhyLens recording={...} />` takes the recording straight (`recordRun()`'s `{ snapshot, events, structure }`, or the `persistRecording` envelope), validates it at mount, and mounts the shipped `<Lens>` shell on the milestone axis — plus the axis helpers (`scrubAxisFor`, `stepForCommitIdx`, `stepForRuntimeStageId`, `resolveNavigation`) for hosts holding one cursor across views. |
+| `agentfootprint-lens/skillgraph` | Debug how a run routed through its skills. `<SkillGraphDebugger recorder={...} />` plus its headless selectors (`selectSkillRoute`, `selectSkillBeats`, `selectSkillTopology`, `selectSkillFrameContext`, `stepForRuntimeStageId`, `resolveNavigation`). |
 
 The axis model in three sentences: one run leaves one causal trace, and each
 lens replays one AXIS of it — the Why reading scrubs the milestones, the Flow
@@ -654,6 +654,67 @@ 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.
 
+### Pointing at a step: `navigatorRef`
+
+`step` lets you *own* the cursor. `navigatorRef` lets you *say where* — when the
+only thing you know is a stage's address. That is what a chat answer has: it can
+tell you the tool call went wrong, and now it can point at the exact step it
+means.
+
+```tsx
+import { Lens, type LensNavigator } from 'agentfootprint-lens';
+
+const nav = useRef<LensNavigator>(null);
+
+<Lens recorder={recorder} navigatorRef={nav} />
+
+// Anywhere — a chat message, a dashboard row, a deep link:
+const to = nav.current?.navigateTo('call-llm#18');
+// → { ok: true, step: 7, runtimeStageId: 'call-llm#18', match: 'exact', label: 'call-llm 1' }
+```
+
+It resolves against **the ruler you are actually scrubbing**, so the same
+address is step 7 under `granularity="step"` and step 3 under
+`granularity="group"` — and then it goes through the *same funnel* a click on
+that stop uses. Uncontrolled, the lens moves and reports. Controlled, it reports
+and your `step` lands it. Nothing new holds a position.
+
+**A miss is answered, never guessed.** Three rungs, in order:
+
+| | what happened | you get |
+|---|---|---|
+| `match: 'exact'` | a stop **is** that address | `{ ok: true, step, label }` |
+| `match: 'enclosing'` | no stop is that address, but one **contains** it (a stage inside a subflow, on a ruler that stops at whole subflows) | `{ ok: true, step, runtimeStageId }` — the stop's own address, so you always know where it went |
+| — | nothing holds it | `{ ok: false, reason, message, nearest? }` — **the cursor did not move** |
+
+`nearest` is the stop just *before* the address, handed back as data. It is an
+**offer, not a jump**: a cursor that silently lands somewhere the person did not
+ask for is worse than one that stays put. Take it when you want to — one more
+call, and it is an exact hit by construction:
+
+```tsx
+const to = nav.current?.navigateTo(stageId);
+if (to?.ok) {
+  // landed
+} else if (to?.nearest) {
+  // "That step isn't on this ruler. Go to Iteration 1 instead?"
+  onConfirm(() => nav.current?.navigateTo(to.nearest.runtimeStageId));
+} else {
+  show(to?.message); // says exactly why, in a sentence you can print
+}
+```
+
+**No component? Same answer.** The resolver is pure and ships headlessly, so a
+server-rendered link or a CLI can compute the step with nothing mounted:
+
+```ts
+import { scrubAxisFor, resolveNavigation } from 'agentfootprint-lens/core';
+
+const positions = scrubAxisFor(recorder, 'step');   // the ruler, as data
+const to = resolveNavigation(positions, 'call-llm#18');
+const href = to.ok ? `/runs/${runId}?step=${to.step}` : undefined;
+```
+
 ---
 
 ## Rendering your own detail pane
@@ -812,6 +873,7 @@ graph in one call. Returns an unsubscribe. Call it once per run.
 | `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`. |
+| `navigatorRef` | `Ref<LensNavigator>?` | Move the cursor to a stage **by its `runtimeStageId`**. `ref.current.navigateTo(id)` returns `{ ok: true, step, match, label }` or `{ ok: false, reason, message, nearest? }` — a miss never moves. See [Pointing at a step](#pointing-at-a-step-navigatorref). |
 | `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

package/dist/{useCursorPositions-CF9RDUw0.d.cts → Lens-B039-UGw.d.cts}

@@ -2,9 +2,9 @@ import * as agentfootprint_observe from 'agentfootprint/observe';
 import { ToolChoiceCall, ToolChoiceSummary } from 'agentfootprint/observe';
 import * as agentfootprint from 'agentfootprint';
 import { CommentaryTemplates } from 'agentfootprint';
-import React__default from 'react';
-import { L as LensRecorder, C as CursorPosition } from './stepForRuntimeStageId-Bl6cG9wB.cjs';
-import { C as ChartGroupHighlight, H as Humanizer } from './stepForCommitIdx-feXP5i-2.cjs';
+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 { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -217,6 +217,73 @@ interface UseLensCursorResult {
 declare function clampStep(n: number, maxStep: number): number;
 declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, }: UseLensCursorArgs): UseLensCursorResult;
 
+/**
+ * useLensNavigator — move the ONE cursor to a stage by its address.
+ *
+ * `<Lens step onStepChange>` lets a host OWN the cursor. This is the other
+ * half a pointing host needs: a way to SAY WHERE, when the only thing it knows
+ * is a `runtimeStageId` — a chat answer citing the step it means, a dashboard
+ * row, a deep link.
+ *
+ * THE ONE-CURSOR LAW, kept: this adds NO state and NO second channel. It is a
+ * RESOLUTION (`resolveNavigation`, the shipped ladder) followed by the SAME
+ * `moveTo` funnel every internal mover already goes through — the step strip,
+ * the ◀ ▶ buttons, the arrow keys, a chart click, the live auto-advance. So it
+ * behaves exactly like a person clicking that stop:
+ *
+ *   - **Uncontrolled** — the cursor moves, and `onStepChange` reports it.
+ *   - **Controlled** — nothing moves on its own; `onStepChange` fires with the
+ *     step and the host's own `step` prop lands it. Two owners never fight,
+ *     because there is still only one owner.
+ *   - **Already there** — no move, no event (a non-move is not a change), and
+ *     still `{ ok: true }` with the step the cursor is standing on.
+ *
+ * HONEST MISSES: an address the axis cannot hold comes back `{ ok: false }`
+ * with the nearest-previous stop OFFERED as data, never taken. See
+ * `resolveNavigation` for the ladder.
+ *
+ * @example The handle, on the component.
+ * ```tsx
+ * const nav = useRef<LensNavigator>(null);
+ *
+ * <Lens recorder={recorder} navigatorRef={nav} />
+ *
+ * // Later — a chat answer points at its evidence:
+ * const to = nav.current?.navigateTo('llm#7');
+ * if (to?.ok) show(`Jumped to ${to.label}`);
+ * else if (to?.nearest) offer(`Not on this ruler. Go to ${to.nearest.label}?`);
+ * // Taking the offer is one more call — `nearest.runtimeStageId` is an exact
+ * // hit by construction:
+ * //   nav.current?.navigateTo(to.nearest.runtimeStageId);
+ * ```
+ */
+
+/**
+ * The imperative handle `<Lens navigatorRef>` fills in — the lens's cursor,
+ * addressable by stage.
+ */
+interface LensNavigator {
+    /**
+     * Move the ONE cursor to the stop that holds `runtimeStageId`, on whatever
+     * axis the lens is currently scrubbing (`granularity="step"` → the commit
+     * axis, `granularity="group"` → the milestone axis).
+     *
+     * Returns where it went — or, on a miss, why it did not and what was nearby.
+     * Never throws, and never moves on a miss.
+     */
+    navigateTo(runtimeStageId: string): NavigationResult;
+}
+interface UseLensNavigatorArgs {
+    /** The ACTIVE scrub axis — the same list the lens renders its ruler from. */
+    readonly positions: readonly CursorPosition[];
+    /** The one cursor funnel (`useLensCursor`'s `moveTo`). */
+    readonly moveTo: (step: number) => void;
+    /** The host's ref, filled with the handle. Omit and the hook still returns
+     *  the navigator for in-tree use. */
+    readonly navigatorRef?: Ref<LensNavigator> | undefined;
+}
+declare function useLensNavigator({ positions, moveTo, navigatorRef, }: UseLensNavigatorArgs): LensNavigator;
+
 /**
  * useToolChoice — async reader for the agentfootprint/observe
  * `toolChoiceRecorder` handle (RFC-002 block C7).
@@ -498,6 +565,33 @@ interface LensProps {
      * Memoize via `useCallback` to avoid downstream re-renders.
      */
     readonly onStepChange?: (step: number, at: LensCursorAt) => void;
+    /**
+     * Move the cursor to a STAGE, by its address — the pointing half of the
+     * cursor API. `step` / `onStepChange` let a host OWN the cursor; this lets
+     * one SAY WHERE when all it knows is a `runtimeStageId` (a chat answer
+     * citing the step it means, a dashboard row, a deep link).
+     *
+     * ```tsx
+     * const nav = useRef<LensNavigator>(null);
+     * <Lens recorder={recorder} navigatorRef={nav} />
+     *
+     * const to = nav.current?.navigateTo('llm#7');
+     * // { ok: true, step: 7, runtimeStageId: 'llm#7', match: 'exact', label: … }
+     * ```
+     *
+     * It is a RESOLUTION plus the cursor channel you already have — not a second
+     * channel. The address is resolved against the ACTIVE axis (`granularity`),
+     * then handed to the same funnel a click on that stop uses: uncontrolled,
+     * the lens moves and reports; controlled, it reports and your `step` lands
+     * it. Nothing here holds a position.
+     *
+     * An address the axis cannot hold comes back `{ ok: false, reason, message }`
+     * with the nearest earlier stop OFFERED as `nearest` — never taken. The
+     * caller decides. See `resolveNavigation` for the ladder (exact → enclosing
+     * → nearest-previous-as-an-offer), which is also exported headlessly for
+     * hosts with nothing mounted.
+     */
+    readonly navigatorRef?: React__default.Ref<LensNavigator>;
     /**
      * Optional slot overrides. Should be stable across renders (define at module
      * scope or `useMemo`). Omit and the shipped panes render unchanged.
@@ -548,48 +642,4 @@ interface LensDetailSlotProps {
 }
 declare const Lens: React__default.FC<LensProps>;
 
-/**
- * useCursorPositions — React hook exposing the slider's valid positions
- * at the current drill level, on the requested AXIS.
- *
- * Layer 2 / Tier B / Lens v0.1.
- *
- * TWO AXES, ONE CURSOR (the 0.39.0 correction):
- *
- *   `'commit'`    — one stop per executed stage, straight off the commit log.
- *                   The Flow Lens's axis (`granularity="step"`): every stage
- *                   is a stop, nothing skippable, and the ruler's count is the
- *                   commit log's count by construction.
- *   `'milestone'` — one stop per agent-meaningful moment (iteration → context
- *                   → LLM turn → route → tool call), classified by the
- *                   domain's `milestoneFor`. The Why Lens's axis
- *                   (`granularity="group"`), which `stepBands` bands by
- *                   iteration.
- *
- * The cursor type is still `runtimeStageId` either way. Only the SET of valid
- * positions differs — the same compound-time-axis rule that already scaled the
- * set by drill depth now also scales it by reading.
- *
- * Lifecycle
- * ─────────
- *   Reactive to BOTH the recorder (events advance the commit log /
- *   open new groups) and to `drillPath` changes (user drill-in /
- *   drill-out). Memoized so a stable drillPath + recorder = stable
- *   array identity.
- */
-
-/** Which projection of the run the scrub axis stops at. */
-type ScrubAxis = 'commit' | 'milestone';
-/**
- * The scrub axis for a recording, as a PURE function — the same positions the
- * mounted `<Lens>` scrubs at that granularity, computable outside React.
- *
- * This is the export a HOST holding the cursor across two granularities needs:
- * to carry a position from one axis to the other, build the target axis here
- * and resolve the commit with `stepForCommitIdx` (or an address with
- * `stepForRuntimeStageId`). Returns `[]` when the recording has no commits yet
- * (or on any read error — same posture as the hook).
- */
-declare function scrubAxisFor(recorder: LensRecorder, granularity: 'step' | 'group', drillPath?: readonly string[]): readonly CursorPosition[];
-
-export { type LensProps as L, type ScrubAxis as S, type ToolChoiceSource as T, type UseLensCursorArgs as U, Lens as a, type LensCursorAt as b, type LensDetailSlotProps as c, type LensSlots as d, type LensTheme as e, type LensView as f, type LensCursorPlace as g, LensFlow as h, type LensFlowProps as i, type UseLensCursorResult as j, type UseToolChoiceResult as k, clampStep as l, useToolChoice as m, scrubAxisFor as s, useLensCursor as u };
+export { type LensProps as L, type ToolChoiceSource as T, type UseLensCursorArgs as U, Lens as a, type LensCursorAt as b, type LensDetailSlotProps as c, type LensSlots as d, type LensTheme as e, type LensView as f, type LensCursorPlace as g, LensFlow as h, type LensFlowProps as i, type LensNavigator as j, type UseLensCursorResult as k, type UseLensNavigatorArgs as l, type UseToolChoiceResult as m, clampStep as n, useLensNavigator as o, useToolChoice as p, useLensCursor as u };

package/dist/{useCursorPositions-B1HJiarC.d.ts → Lens-ey1EgN9i.d.ts}

@@ -2,9 +2,9 @@ import * as agentfootprint_observe from 'agentfootprint/observe';
 import { ToolChoiceCall, ToolChoiceSummary } from 'agentfootprint/observe';
 import * as agentfootprint from 'agentfootprint';
 import { CommentaryTemplates } from 'agentfootprint';
-import React__default from 'react';
-import { L as LensRecorder, C as CursorPosition } from './stepForRuntimeStageId-Bl6cG9wB.js';
-import { C as ChartGroupHighlight, H as Humanizer } from './stepForCommitIdx-PnR_Kael.js';
+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 { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -217,6 +217,73 @@ interface UseLensCursorResult {
 declare function clampStep(n: number, maxStep: number): number;
 declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, }: UseLensCursorArgs): UseLensCursorResult;
 
+/**
+ * useLensNavigator — move the ONE cursor to a stage by its address.
+ *
+ * `<Lens step onStepChange>` lets a host OWN the cursor. This is the other
+ * half a pointing host needs: a way to SAY WHERE, when the only thing it knows
+ * is a `runtimeStageId` — a chat answer citing the step it means, a dashboard
+ * row, a deep link.
+ *
+ * THE ONE-CURSOR LAW, kept: this adds NO state and NO second channel. It is a
+ * RESOLUTION (`resolveNavigation`, the shipped ladder) followed by the SAME
+ * `moveTo` funnel every internal mover already goes through — the step strip,
+ * the ◀ ▶ buttons, the arrow keys, a chart click, the live auto-advance. So it
+ * behaves exactly like a person clicking that stop:
+ *
+ *   - **Uncontrolled** — the cursor moves, and `onStepChange` reports it.
+ *   - **Controlled** — nothing moves on its own; `onStepChange` fires with the
+ *     step and the host's own `step` prop lands it. Two owners never fight,
+ *     because there is still only one owner.
+ *   - **Already there** — no move, no event (a non-move is not a change), and
+ *     still `{ ok: true }` with the step the cursor is standing on.
+ *
+ * HONEST MISSES: an address the axis cannot hold comes back `{ ok: false }`
+ * with the nearest-previous stop OFFERED as data, never taken. See
+ * `resolveNavigation` for the ladder.
+ *
+ * @example The handle, on the component.
+ * ```tsx
+ * const nav = useRef<LensNavigator>(null);
+ *
+ * <Lens recorder={recorder} navigatorRef={nav} />
+ *
+ * // Later — a chat answer points at its evidence:
+ * const to = nav.current?.navigateTo('llm#7');
+ * if (to?.ok) show(`Jumped to ${to.label}`);
+ * else if (to?.nearest) offer(`Not on this ruler. Go to ${to.nearest.label}?`);
+ * // Taking the offer is one more call — `nearest.runtimeStageId` is an exact
+ * // hit by construction:
+ * //   nav.current?.navigateTo(to.nearest.runtimeStageId);
+ * ```
+ */
+
+/**
+ * The imperative handle `<Lens navigatorRef>` fills in — the lens's cursor,
+ * addressable by stage.
+ */
+interface LensNavigator {
+    /**
+     * Move the ONE cursor to the stop that holds `runtimeStageId`, on whatever
+     * axis the lens is currently scrubbing (`granularity="step"` → the commit
+     * axis, `granularity="group"` → the milestone axis).
+     *
+     * Returns where it went — or, on a miss, why it did not and what was nearby.
+     * Never throws, and never moves on a miss.
+     */
+    navigateTo(runtimeStageId: string): NavigationResult;
+}
+interface UseLensNavigatorArgs {
+    /** The ACTIVE scrub axis — the same list the lens renders its ruler from. */
+    readonly positions: readonly CursorPosition[];
+    /** The one cursor funnel (`useLensCursor`'s `moveTo`). */
+    readonly moveTo: (step: number) => void;
+    /** The host's ref, filled with the handle. Omit and the hook still returns
+     *  the navigator for in-tree use. */
+    readonly navigatorRef?: Ref<LensNavigator> | undefined;
+}
+declare function useLensNavigator({ positions, moveTo, navigatorRef, }: UseLensNavigatorArgs): LensNavigator;
+
 /**
  * useToolChoice — async reader for the agentfootprint/observe
  * `toolChoiceRecorder` handle (RFC-002 block C7).
@@ -498,6 +565,33 @@ interface LensProps {
      * Memoize via `useCallback` to avoid downstream re-renders.
      */
     readonly onStepChange?: (step: number, at: LensCursorAt) => void;
+    /**
+     * Move the cursor to a STAGE, by its address — the pointing half of the
+     * cursor API. `step` / `onStepChange` let a host OWN the cursor; this lets
+     * one SAY WHERE when all it knows is a `runtimeStageId` (a chat answer
+     * citing the step it means, a dashboard row, a deep link).
+     *
+     * ```tsx
+     * const nav = useRef<LensNavigator>(null);
+     * <Lens recorder={recorder} navigatorRef={nav} />
+     *
+     * const to = nav.current?.navigateTo('llm#7');
+     * // { ok: true, step: 7, runtimeStageId: 'llm#7', match: 'exact', label: … }
+     * ```
+     *
+     * It is a RESOLUTION plus the cursor channel you already have — not a second
+     * channel. The address is resolved against the ACTIVE axis (`granularity`),
+     * then handed to the same funnel a click on that stop uses: uncontrolled,
+     * the lens moves and reports; controlled, it reports and your `step` lands
+     * it. Nothing here holds a position.
+     *
+     * An address the axis cannot hold comes back `{ ok: false, reason, message }`
+     * with the nearest earlier stop OFFERED as `nearest` — never taken. The
+     * caller decides. See `resolveNavigation` for the ladder (exact → enclosing
+     * → nearest-previous-as-an-offer), which is also exported headlessly for
+     * hosts with nothing mounted.
+     */
+    readonly navigatorRef?: React__default.Ref<LensNavigator>;
     /**
      * Optional slot overrides. Should be stable across renders (define at module
      * scope or `useMemo`). Omit and the shipped panes render unchanged.
@@ -548,48 +642,4 @@ interface LensDetailSlotProps {
 }
 declare const Lens: React__default.FC<LensProps>;
 
-/**
- * useCursorPositions — React hook exposing the slider's valid positions
- * at the current drill level, on the requested AXIS.
- *
- * Layer 2 / Tier B / Lens v0.1.
- *
- * TWO AXES, ONE CURSOR (the 0.39.0 correction):
- *
- *   `'commit'`    — one stop per executed stage, straight off the commit log.
- *                   The Flow Lens's axis (`granularity="step"`): every stage
- *                   is a stop, nothing skippable, and the ruler's count is the
- *                   commit log's count by construction.
- *   `'milestone'` — one stop per agent-meaningful moment (iteration → context
- *                   → LLM turn → route → tool call), classified by the
- *                   domain's `milestoneFor`. The Why Lens's axis
- *                   (`granularity="group"`), which `stepBands` bands by
- *                   iteration.
- *
- * The cursor type is still `runtimeStageId` either way. Only the SET of valid
- * positions differs — the same compound-time-axis rule that already scaled the
- * set by drill depth now also scales it by reading.
- *
- * Lifecycle
- * ─────────
- *   Reactive to BOTH the recorder (events advance the commit log /
- *   open new groups) and to `drillPath` changes (user drill-in /
- *   drill-out). Memoized so a stable drillPath + recorder = stable
- *   array identity.
- */
-
-/** Which projection of the run the scrub axis stops at. */
-type ScrubAxis = 'commit' | 'milestone';
-/**
- * The scrub axis for a recording, as a PURE function — the same positions the
- * mounted `<Lens>` scrubs at that granularity, computable outside React.
- *
- * This is the export a HOST holding the cursor across two granularities needs:
- * to carry a position from one axis to the other, build the target axis here
- * and resolve the commit with `stepForCommitIdx` (or an address with
- * `stepForRuntimeStageId`). Returns `[]` when the recording has no commits yet
- * (or on any read error — same posture as the hook).
- */
-declare function scrubAxisFor(recorder: LensRecorder, granularity: 'step' | 'group', drillPath?: readonly string[]): readonly CursorPosition[];
-
-export { type LensProps as L, type ScrubAxis as S, type ToolChoiceSource as T, type UseLensCursorArgs as U, Lens as a, type LensCursorAt as b, type LensDetailSlotProps as c, type LensSlots as d, type LensTheme as e, type LensView as f, type LensCursorPlace as g, LensFlow as h, type LensFlowProps as i, type UseLensCursorResult as j, type UseToolChoiceResult as k, clampStep as l, useToolChoice as m, scrubAxisFor as s, useLensCursor as u };
+export { type LensProps as L, type ToolChoiceSource as T, type UseLensCursorArgs as U, Lens as a, type LensCursorAt as b, type LensDetailSlotProps as c, type LensSlots as d, type LensTheme as e, type LensView as f, type LensCursorPlace as g, LensFlow as h, type LensFlowProps as i, type LensNavigator as j, type UseLensCursorResult as k, type UseLensNavigatorArgs as l, type UseToolChoiceResult as m, clampStep as n, useLensNavigator as o, useToolChoice as p, useLensCursor as u };

package/dist/{chunk-S7FLEXJ3.js → chunk-F473UD5M.js}

@@ -6,14 +6,14 @@ import {
   describeReceived,
   refusalDestinationFor,
   useNarrowRow
-} from "./chunk-EBQCTQQU.js";
+} from "./chunk-FFQ5EARP.js";
 import {
   selectSkillBeatAt,
   selectSkillBeats,
   selectSkillFrameContext,
   selectSkillRoute,
   selectSkillTopology
-} from "./chunk-EYCTYBSV.js";
+} from "./chunk-VBRT372Q.js";
 
 // src/react/skillGraphFlowLayout.ts
 import dagre from "dagre";
@@ -237,6 +237,8 @@ function FrameFactsPanel({
     return /* @__PURE__ */ jsx2("div", { style: panelStyle, "data-testid": "frame-facts", children: /* @__PURE__ */ jsx2("p", { style: { margin: 0, fontSize: 12, color: T.textMuted }, children: "Nothing has been sent to the model yet at this cursor position." }) });
   }
   const hop = beat.hop;
+  const promptOnRecord = hop.systemPromptText !== void 0;
+  const reachableAsData = beat.reachable?.source === "cursor-move";
   return /* @__PURE__ */ jsxs2("div", { style: panelStyle, "data-testid": "frame-facts", children: [
     /* @__PURE__ */ jsx2(
       Header,
@@ -245,6 +247,14 @@ function FrameFactsPanel({
         subtitle: `${beat.label} \xB7 the call this stop prepared`
       }
     ),
+    hop.systemPromptText !== void 0 && /* @__PURE__ */ jsxs2(Section, { title: "system prompt, as sent", count: 1, children: [
+      /* @__PURE__ */ jsxs2("div", { style: { fontSize: 10, color: T.textMuted, marginBottom: 4 }, children: [
+        "the assembled prompt, byte-for-byte as the provider received it (the producer opted in with ",
+        /* @__PURE__ */ jsx2("code", { children: "recordSystemPrompt: true" }),
+        ")"
+      ] }),
+      /* @__PURE__ */ jsx2(Mono, { testId: "system-prompt-text", children: hop.systemPromptText })
+    ] }),
     /* @__PURE__ */ jsx2(Section, { title: "read_skill, as sent", count: hop.readSkillDescription !== void 0 ? 1 : 0, children: hop.readSkillDescription !== void 0 ? /* @__PURE__ */ jsx2(Mono, { testId: "read-skill-description", children: hop.readSkillDescription }) : /* @__PURE__ */ jsxs2(Absent, { children: [
       "This iteration's recording carries no ",
       /* @__PURE__ */ jsx2("code", { children: "read_skill" }),
@@ -321,7 +331,7 @@ function FrameFactsPanel({
         u.shape !== void 0 ? ` (${u.shape})` : ""
       ] }, i))
     ] }),
-    /* @__PURE__ */ jsxs2(
+    (!promptOnRecord || !reachableAsData) && /* @__PURE__ */ jsxs2(
       "div",
       {
         "data-testid": "frame-absence",
@@ -337,9 +347,20 @@ function FrameFactsPanel({
         },
         children: [
           /* @__PURE__ */ jsx2("strong", { style: { color: T.textSecondary }, children: "Not in this recording." }),
-          " The system prompt as one assembled string is not recorded \u2014 the injections above are the pieces it was composed from. The reachable set is not recorded as data either: it appears as prose inside ",
-          /* @__PURE__ */ jsx2("code", { children: "read_skill" }),
-          "'s description, and as a typed list only when the gate refused a pick. Neither is reconstructed here."
+          !promptOnRecord && /* @__PURE__ */ jsxs2(Fragment, { children: [
+            " ",
+            "The system prompt as one assembled string is not recorded \u2014 the injections above are the pieces it was composed from. Recording the assembled prompt is an explicit opt-in (",
+            /* @__PURE__ */ jsx2("code", { children: "recordSystemPrompt: true" }),
+            "); the default keeps it out of every recording, because it carries everything injected into it."
+          ] }),
+          !reachableAsData && /* @__PURE__ */ jsxs2(Fragment, { children: [
+            " ",
+            "The reachable set is not recorded as data in this era's recording: it appears as prose inside ",
+            /* @__PURE__ */ jsx2("code", { children: "read_skill" }),
+            "'s description, and as a typed list only when the gate refused a pick."
+          ] }),
+          " ",
+          "Nothing absent is reconstructed here."
         ]
       }
     )
@@ -647,7 +668,7 @@ function RouteDecisionCard({ beat, lens }) {
             "\u201D"
           ] })
         ] }),
-        beat.reachable !== void 0 && /* @__PURE__ */ jsx4(Evidence, { label: `reachable (${beat.reachable.source})`, children: beat.reachable.ids.join(", ") }),
+        beat.reachable !== void 0 && /* @__PURE__ */ jsx4(Evidence, { label: `reachable (${beat.reachable.source})`, children: beat.reachable.ids.length > 0 ? beat.reachable.ids.join(", ") : "none \u2014 a dead end: no skill was admissible from this cursor" }),
         beat.hop.offered !== void 0 && /* @__PURE__ */ jsx4(Evidence, { label: "menu offered", children: beat.hop.offered.join(", ") }),
         beat.hop.refusals.map((r, i) => /* @__PURE__ */ jsxs4(
           "div",
@@ -800,7 +821,10 @@ var SkillStateNode = ({ data }) => {
     {
       "data-testid": `skill-node-${d.label}`,
       "data-state": d.state,
-      title: d.jumpable ? `Jump the cursor to "${d.label}"` : `The cursor never stood in "${d.label}"`,
+      title: [
+        d.description,
+        d.jumpable ? `Jump the cursor to "${d.label}"` : `The cursor never stood in "${d.label}"`
+      ].filter((line) => line !== void 0).join("\n\n"),
       style: {
         width: 192,
         minHeight: 56,
@@ -859,6 +883,21 @@ var SkillStateNode = ({ data }) => {
             },
             children: [
               /* @__PURE__ */ jsx5("span", { children: d.stateLabel }),
+              d.isEntry && /* @__PURE__ */ jsx5(
+                "span",
+                {
+                  style: {
+                    padding: "1px 5px",
+                    borderRadius: 5,
+                    background: `${T.bgPrimary}`,
+                    border: `1px solid ${T.textMuted}`,
+                    color: T.textMuted,
+                    textTransform: "none",
+                    letterSpacing: 0
+                  },
+                  children: "entry"
+                }
+              ),
               d.pickedByModel && /* @__PURE__ */ jsx5(
                 "span",
                 {
@@ -910,11 +949,13 @@ function SkillTopologyCanvas({
         draggable: false,
         selectable: true,
         data: {
-          label: n.id,
+          label: n.label ?? n.id,
           state: n.state,
           stateLabel: lens === "product" ? STATE_STYLE[n.state].product : STATE_STYLE[n.state].developer,
           pickedByModel: n.pickedByModel,
-          jumpable: jumpable.has(n.id)
+          jumpable: jumpable.has(n.id),
+          ...n.description !== void 0 ? { description: n.description } : {},
+          isEntry: n.isEntry
         }
       };
     }),
@@ -1019,7 +1060,15 @@ function Legend({
           /* @__PURE__ */ jsx5("span", { children: "\u2014 solid: an edge the author declared" }),
           /* @__PURE__ */ jsx5("span", { children: "\u2504 dashed: a hop the run took, never declared on the record" })
         ] }),
-        topology.declaredSource !== "graph" && /* @__PURE__ */ jsx5("div", { style: { flex: "1 1 100%", color: T.warning, lineHeight: 1.35 }, children: topology.declaredSource === "recording" ? "Declared edges shown are only the ones this recording named \u2014 a recording names an edge once it fires, so the author may have drawn more." : "This recording named no declared edges; every line here is a hop that was observed." })
+        topology.declaredSource === "recording-declared" && /* @__PURE__ */ jsx5(
+          "div",
+          {
+            "data-testid": "declared-complete-note",
+            style: { flex: "1 1 100%", color: T.textMuted, lineHeight: 1.35 },
+            children: "The author's complete declared map \u2014 this recording carries it (skill.graph_declared)."
+          }
+        ),
+        !topology.declaredComplete && /* @__PURE__ */ jsx5("div", { style: { flex: "1 1 100%", color: T.warning, lineHeight: 1.35 }, children: topology.declaredSource === "recording" ? "Declared edges shown are only the ones this recording named \u2014 a recording names an edge once it fires, so the author may have drawn more." : "This recording named no declared edges; every line here is a hop that was observed." })
       ]
     }
   );
@@ -1326,4 +1375,4 @@ export {
   SKILL_GRAPH_READS,
   SkillGraphDebugger
 };
-//# sourceMappingURL=chunk-S7FLEXJ3.js.map
+//# sourceMappingURL=chunk-F473UD5M.js.map