agentfootprint-lens 0.49.0 → 0.51.0

package/README.md

@@ -940,7 +940,9 @@ not answer, since it takes an exact stop.
 ## The Served tab
 
 **At every LLM call, exactly what the model was served — provable from the log.**
-The Why Lens's right rail has a second tab, **Served**, mounted for every run.
+The Why Lens's right rail has a second tab, **Served**, mounted for every run —
+including for a host that supplies `slots.detail`, whose own pane is the tab
+beside it (0.50.0).
 Stand on an LLM turn and it shows the request that call went out with: the system
 prompt (piece by piece), the messages as sent, the tools as sent, the dials, the
 cache breakpoints — and beside every field, what the record can PROVE about it.
@@ -1108,7 +1110,8 @@ likely to rot — and the question above is answered without it.
 ## Bookmarks, and scrubbing by declared tag
 
 **The reader's marks, kept beside the recording — and the author's tags, as a
-ruler.** Since 0.48.0 the Why Lens's right rail has a third tab, **Bookmarks**,
+ruler.** Since 0.48.0 the Why Lens's right rail has a third tab, **Bookmarks**
+(a fourth when a host fills `slots.detail`),
 and the grouped ruler carries a **Tags** strip.
 
 ### Why
@@ -1222,9 +1225,17 @@ unavailable*, and nothing else changes. The peer ranges are untouched.
 
 ## 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.
+**A slot fills a PANE, never the CHROME around it.** The right rail's tab strip,
+the one cursor and the collapse pill belong to the library, because chrome is how
+the library adds capability over time — a consumer that fills a slot must still
+receive every reading the rail gains later. That is why `slots.detail` is ONE TAB
+and not a takeover, and why `detailOnly` is an opt-out rather than the default.
+
+`slots.detail` renders the right column's FIRST tab. The column itself — its
+width, its border, its collapse pill, its cursor — is unchanged, and so is the
+strip: your pane is selected by default, with *What happened*, *Served* and
+*Bookmarks* one click away beside it. Omit `slots` and the built-in timeline
+renders exactly as before.
 
 ```tsx
 const Detail: React.FC<LensDetailSlotProps> = ({ step, cursorRuntimeStageId, node, onNavigate }) => (
@@ -1235,7 +1246,8 @@ const Detail: React.FC<LensDetailSlotProps> = ({ step, cursorRuntimeStageId, nod
   </div>
 );
 
-<Lens recorder={recorder} runner={runner} slots={{ detail: Detail }} />
+<Lens recorder={recorder} runner={runner} slots={{ detail: Detail, detailLabel: 'My bands' }} />
+// rail: [ My bands* | What happened | Served | Bookmarks ]
 ```
 
 The slot receives the cursor in every unit (`step`, `totalSteps`,
@@ -1244,11 +1256,130 @@ 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.
 
+| key | what it does |
+|---|---|
+| `detail` | your pane, as the rail's first tab, selected by default |
+| `detailLabel` | what that tab is CALLED. Default `"Details"` — the library's generic word for someone else's pane. Name it and the strip reads in your reader's words. |
+| `detailOnly` | opt OUT of the strip: your pane takes the whole rail, as it did before 0.50.0. For a full-height custom layout that would read as a second chrome under the library's strip. The cost: nothing the rail gains later can reach you. |
+
+**Switching tabs moves nothing and remounts nothing.** The cursor stays where it
+was, and your pane is hidden rather than unmounted — a reader who glances at
+*Served* and comes back finds their bands open and their scroll where they left
+it.
+
+**The worked example (0.50.0).** An app supplies `detail` + `detailLabel` and
+changes nothing else: it sees its own pane first and selected, exactly as before,
+and it GAINS Served, the Served graph and Bookmarks on the version bump. Before
+0.50.0 that same app lost the entire rail — the tab strip included — and could
+not reach any of them.
+
 Keep the slots object stable across renders (module scope or `useMemo`), same as
 `<TraceExplorerShell slots>`.
 
 ---
 
+## One address, one cursor — for every view
+
+> **A stage id is an ADDRESS, not a POSITION.** It says WHICH stage, never WHERE
+> on an axis. Only an axis can answer that, and it may honestly answer *"not
+> here"*.
+
+Until 0.51.0 the same one cursor reached three views in three vocabularies, and
+every new view invented a fourth:
+
+| view | handed | reads |
+|---|---|---|
+| skill graph | `cursorRuntimeStageId` + `onJumpTo` | the EVENT record |
+| a consumer's data graph | `{ step, total, stepOf(id), onStep }` | the COMMIT record |
+| Served tab / graph | `cursorRuntimeStageId` + `commitIdx` | the COMMIT record |
+
+`LensCursor` is their superset, and every view now gets exactly it. It is three
+things and deliberately nothing more:
+
+```ts
+interface LensCursor {
+  readonly at: LensCursorReading;              // step · totalSteps · runtimeStageId · commitIdx · label · kind
+  readonly total: number;
+  resolve(runtimeStageId: string): NavigationResult;   // an ADDRESS, answered honestly
+  moveTo(step: number): void;                          // the ONE funnel
+}
+```
+
+**It holds no position of its own**, and no view may gain one: `at` is derived
+from the axis and the step on every render, `resolve` is a pure query, and
+`moveTo` is the same funnel the step strip, the ◀ ▶ buttons and the live
+auto-advance go through. Read it; never store it.
+
+### Adopting it — one line
+
+```tsx
+<Lens
+  recorder={recorder}
+  slots={{ detail: (p) => <SkillGraphDebugger recorder={p.recorder} cursor={p.cursor} /> }}
+/>
+```
+
+`cursor` arrives on `LensDetailSlotProps` beside every prop that was already
+there, and `<SkillGraphDebugger cursor>` / `<ServedTab cursor>` are the narrow
+form of the props they already took. Nothing was removed; an explicit prop still
+wins wherever both are passed.
+
+### Placing an element by address
+
+This is the behaviour the packet generalises. A real consumer's data-graph view
+took `stepOf(id)` and drew an element `unplaced` when the answer came back below
+zero — a number every view had to invent a meaning for. Written against
+`resolve`, the meaning *and the words* come from the library:
+
+```tsx
+function Element({ cursor, runtimeStageId, name }) {
+  const to = cursor.resolve(runtimeStageId);
+  if (!to.ok) {
+    // Drawn, never hidden — omit never deny — and the sentence is the library's.
+    return <li data-unplaced title={to.message}>{name}</li>;
+  }
+  return (
+    <li data-enclosing={to.match === 'enclosing'} onClick={() => cursor.moveTo(to.step)}>
+      {to.label}
+    </li>
+  );
+}
+```
+
+### The three cases the contract names
+
+Each is a real run, and each has a test measured on a frozen fixture:
+
+1. **The axis does not stop there.** A filtered or tag axis over an untagged
+   stage. `resolve` refuses `'not-on-axis'`, carries a printable `message`, and
+   OFFERS the nearest earlier stop in `nearest` — an offer, never a move.
+2. **The id belongs to an inner log.** A subflow's stages commit into their own
+   isolated log, so the axis holds the MOUNT rather than the stage. The ladder's
+   `'enclosing'` rung answers `{ ok: true, match: 'enclosing' }` whose
+   `runtimeStageId` is the mount's — a true landing at the granularity this axis
+   has. Branch on `match` when you must tell "on it" from "inside it", and offer
+   a drill to go deeper.
+3. **The event has no stage at all.** Run start, run end. There is no id;
+   `resolve('')` refuses `'no-id'` and your view says so rather than inventing
+   an address.
+
+### Headless
+
+```ts
+import { scrubAxisFor, lensCursorFrom } from 'agentfootprint-lens/core';
+
+const positions = scrubAxisFor(recorder, 'step');
+const cursor = lensCursorFrom(positions, 0, (step) => setStep(step));
+const to = cursor.resolve('llm#7');
+const href = to.ok ? `/run/${runId}?step=${to.step}` : undefined;
+```
+
+`stepForRuntimeStageId` still ships and still behaves byte for byte; it is
+**deprecated** in favour of `resolveNavigation` / `cursor.resolve`, the same
+ladder with its rungs named instead of flattened to `-1`.
+
+---
+
 ## Theming
 
 **Lens inherits theme tokens from your app via CSS variables.** Set `--fp-*`
@@ -1377,7 +1508,7 @@ graph in one call. Returns an unsubscribe. Call it once per run.
 | `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). |
+| `slots` | `LensSlots?` | Slot overrides. `slots.detail` renders your content as the right rail's FIRST TAB (`slots.detailLabel` names it; `slots.detailOnly` takes the whole rail instead). The strip stays the library's. 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/{Lens-_hExvOXu.d.ts → Lens-Bw1em67x.d.cts}

@@ -3,8 +3,8 @@ import { ToolChoiceCall, ToolChoiceSummary } from 'agentfootprint/observe';
 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-Ckr2nXHY.js';
-import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-C__DMHiD.js';
+import { a as LensCursorReading, C as CursorPosition, L as LensCursor, e as NavigationResult, h as LensRecorder } from './lensCursor-B8HFFZgR.cjs';
+import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-BUrsQ1fX.cjs';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -158,26 +158,12 @@ declare const LensFlow: React__default.FC<LensFlowProps>;
  * 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
  * the lens's axis.
+ *
+ * It is a `LensCursorReading` (`/core`) plus the one thing a MOVE REPORT needs
+ * and a reading does not: `clamped`. One declaration of the reading's fields,
+ * so the report and the `LensCursor` every view is handed cannot drift.
  */
-interface LensCursorAt {
-    /** The new cursor position, on the lens's step axis. Same number the
-     *  `step` prop takes. */
-    readonly step: number;
-    /** How many positions the axis has right now. Valid steps are
-     *  `0 … totalSteps - 1`. GROWS during a live run. */
-    readonly totalSteps: number;
-    /** The cursor's address in footprintjs's address space
-     *  (`[subflowPath/]stageId#executionIndex`) — the same string
-     *  `<TraceExplorerShell>` and `<RunSlider>` call `selectedRuntimeStageId` /
-     *  `cursorRuntimeStageId`. `''` when the axis is empty. */
-    readonly runtimeStageId: string;
-    /** The commit-log index this position anchors to. `-1` when unknown. */
-    readonly commitIdx: number;
-    /** The position's human label, as the step strip and the timeline spell it
-     *  ("Iteration 2", "Context 3", "Run · start"). */
-    readonly label: string;
-    /** What kind of stop this is. Absent when the axis is empty. */
-    readonly kind?: string;
+interface LensCursorAt extends LensCursorReading {
     /**
      * `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
@@ -218,6 +204,18 @@ interface UseLensCursorArgs {
      * owns before every question and remembers nothing between them.
      */
     readonly port?: LensCursorPort | undefined;
+    /**
+     * The ACTIVE scrub axis — the same list the lens draws its ruler from.
+     *
+     * Supplied only so this hook can also hand back the `LensCursor` every view
+     * receives (`cursor` below), which needs the axis to answer an ADDRESS. It
+     * is never consulted for movement: `maxStep`, `describe` and `port` decide
+     * that, exactly as they did before 0.51.0.
+     *
+     * Omit it and `cursor` is a cursor over an EMPTY axis — `resolve` refuses
+     * `'empty-axis'`, which is the honest answer for a caller that gave none.
+     */
+    readonly positions?: readonly CursorPosition[] | undefined;
 }
 interface UseLensCursorResult {
     /** The cursor to render. */
@@ -226,13 +224,22 @@ interface UseLensCursorResult {
     readonly isLive: boolean;
     /** The ONE way anything inside the lens moves the cursor. */
     readonly moveTo: (n: number) => void;
+    /**
+     * The same one cursor in the shape EVERY view is handed (0.51.0): a READING
+     * (`at`), the honest address query (`resolve`) and this very `moveTo`.
+     *
+     * Added BESIDE the three fields above — nothing moved, nothing was removed.
+     * It holds no position: it is rebuilt from (`positions`, `step`) on every
+     * render, so a view cannot end up rendering a stale copy.
+     */
+    readonly cursor: LensCursor;
 }
 /**
  * Snap a host-supplied step onto the axis. Non-finite and fractional values
  * 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, port, }: UseLensCursorArgs): UseLensCursorResult;
+declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, positions, }: UseLensCursorArgs): UseLensCursorResult;
 
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.
@@ -634,16 +641,67 @@ interface LensProps {
  *
  * Same idea as `<TraceExplorerShell slots>`: keep the shipped layout and the
  * shipped cursor, replace what one pane renders.
+ *
+ * THE LAW: **a slot fills a PANE, never the CHROME around it.** The rail's tab
+ * strip, the one cursor and the collapse pill belong to the library, because
+ * chrome is how the library adds capability over time — a consumer that fills a
+ * slot must still receive every capability the rail gains later. That is why
+ * `detail` is ONE TAB and not a takeover, and why `detailOnly` is an opt-out
+ * rather than the default.
  */
 interface LensSlots {
     /**
-     * Override the RIGHT column — the "what happened" timeline. Your component
-     * renders inside the shipped column (its width, borders, collapse pill and
-     * scroll behaviour are unchanged); only the content is yours.
+     * Render the right column's FIRST TAB — your own pane, beside the library's.
+     *
+     * Your component renders inside the shipped column (its width, borders,
+     * collapse pill and scroll behaviour are unchanged) and inside the shipped
+     * rail: the tab strip stays, your pane becomes the first tab and is selected
+     * by default, and "What happened", "Served" and "Bookmarks" stay reachable
+     * beside it. Switching tabs never moves the cursor and never unmounts your
+     * pane — it keeps its own state.
+     *
+     * Before 0.50.0 a supplied slot replaced the whole rail, tab strip included,
+     * so a slot consumer could not reach anything the rail gained afterwards.
+     * That was the defect this shape fixes; `detailOnly` is the way back.
      *
      * Omit it and the built-in timeline renders exactly as before.
+     *
+     * ```tsx
+     * <Lens recorder={recorder} slots={{ detail: MyBands, detailLabel: 'Bands' }} />
+     * // rail: [ Bands* | What happened | Served | Bookmarks ]
+     * ```
      */
     readonly detail?: React__default.ComponentType<LensDetailSlotProps>;
+    /**
+     * What the `detail` tab is CALLED. Default: `"Details"`.
+     *
+     * WHY it exists: the tab strip names each reading in the reader's own words,
+     * and "Details" is the library's generic word for someone else's pane. An app
+     * whose pane is a stack of SEO bands should say so — the strip is read left to
+     * right and an unnamed tab makes the app's own reading the anonymous one.
+     *
+     * A plain string, rendered as the tab's text; it is the accessible name too.
+     * Ignored when no `detail` slot is supplied.
+     *
+     * ```tsx
+     * slots={{ detail: MyBands, detailLabel: 'SEO bands' }}
+     * ```
+     */
+    readonly detailLabel?: string;
+    /**
+     * OPT OUT of the tab strip: the `detail` slot takes the whole rail, as it did
+     * before 0.50.0. Default `false`.
+     *
+     * For the app with a full-height custom layout of its own — a pane that owns
+     * its scroll and its header and would read as a second chrome under the
+     * library's strip. The cost is stated plainly: nothing the rail gains later
+     * (Served, Bookmarks, whatever follows) can reach that consumer, and neither
+     * can the library's own timeline. Prefer the tabs; take this only when the
+     * layout genuinely demands it.
+     *
+     * Ignored when no `detail` slot is supplied.
+     */
+    readonly detailOnly?: boolean;
 }
 /**
  * What the `detail` slot receives — the cursor, in the units a detail pane
@@ -670,6 +728,26 @@ interface LensDetailSlotProps {
     readonly recorder: LensRecorder;
     /** Move the ONE cursor — same funnel every built-in mover uses. */
     readonly onNavigate: (step: number) => void;
+    /**
+     * THE CURSOR, in the one vocabulary every view now shares (0.51.0) — the
+     * reading above (`cursor.at`), the axis's honest answer to an ADDRESS
+     * (`cursor.resolve(id)`), and the same funnel as `onNavigate`
+     * (`cursor.moveTo`).
+     *
+     * Everything else on this interface stays exactly as it was; this is the
+     * shape to reach for when your pane places elements BY ADDRESS, because the
+     * axis may honestly not stop where an address points:
+     *
+     * ```tsx
+     * const to = p.cursor.resolve(node.runtimeStageId);
+     * if (!to.ok) return <li data-unplaced title={to.message}>{node.name}</li>;
+     * return <li onClick={() => p.cursor.moveTo(to.step)}>{to.label}</li>;
+     * ```
+     *
+     * It holds no position of its own — it is rebuilt every render. Read it;
+     * never store it.
+     */
+    readonly cursor: LensCursor;
 }
 declare const Lens: React__default.FC<LensProps>;
 

package/dist/{Lens-_IjGLEGt.d.cts → Lens-CDsSUiHJ.d.ts}

@@ -3,8 +3,8 @@ import { ToolChoiceCall, ToolChoiceSummary } from 'agentfootprint/observe';
 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-Ckr2nXHY.cjs';
-import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-B598GxMJ.cjs';
+import { a as LensCursorReading, C as CursorPosition, L as LensCursor, e as NavigationResult, h as LensRecorder } from './lensCursor-B8HFFZgR.js';
+import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-Cqom3DPf.js';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -158,26 +158,12 @@ declare const LensFlow: React__default.FC<LensFlowProps>;
  * 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
  * the lens's axis.
+ *
+ * It is a `LensCursorReading` (`/core`) plus the one thing a MOVE REPORT needs
+ * and a reading does not: `clamped`. One declaration of the reading's fields,
+ * so the report and the `LensCursor` every view is handed cannot drift.
  */
-interface LensCursorAt {
-    /** The new cursor position, on the lens's step axis. Same number the
-     *  `step` prop takes. */
-    readonly step: number;
-    /** How many positions the axis has right now. Valid steps are
-     *  `0 … totalSteps - 1`. GROWS during a live run. */
-    readonly totalSteps: number;
-    /** The cursor's address in footprintjs's address space
-     *  (`[subflowPath/]stageId#executionIndex`) — the same string
-     *  `<TraceExplorerShell>` and `<RunSlider>` call `selectedRuntimeStageId` /
-     *  `cursorRuntimeStageId`. `''` when the axis is empty. */
-    readonly runtimeStageId: string;
-    /** The commit-log index this position anchors to. `-1` when unknown. */
-    readonly commitIdx: number;
-    /** The position's human label, as the step strip and the timeline spell it
-     *  ("Iteration 2", "Context 3", "Run · start"). */
-    readonly label: string;
-    /** What kind of stop this is. Absent when the axis is empty. */
-    readonly kind?: string;
+interface LensCursorAt extends LensCursorReading {
     /**
      * `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
@@ -218,6 +204,18 @@ interface UseLensCursorArgs {
      * owns before every question and remembers nothing between them.
      */
     readonly port?: LensCursorPort | undefined;
+    /**
+     * The ACTIVE scrub axis — the same list the lens draws its ruler from.
+     *
+     * Supplied only so this hook can also hand back the `LensCursor` every view
+     * receives (`cursor` below), which needs the axis to answer an ADDRESS. It
+     * is never consulted for movement: `maxStep`, `describe` and `port` decide
+     * that, exactly as they did before 0.51.0.
+     *
+     * Omit it and `cursor` is a cursor over an EMPTY axis — `resolve` refuses
+     * `'empty-axis'`, which is the honest answer for a caller that gave none.
+     */
+    readonly positions?: readonly CursorPosition[] | undefined;
 }
 interface UseLensCursorResult {
     /** The cursor to render. */
@@ -226,13 +224,22 @@ interface UseLensCursorResult {
     readonly isLive: boolean;
     /** The ONE way anything inside the lens moves the cursor. */
     readonly moveTo: (n: number) => void;
+    /**
+     * The same one cursor in the shape EVERY view is handed (0.51.0): a READING
+     * (`at`), the honest address query (`resolve`) and this very `moveTo`.
+     *
+     * Added BESIDE the three fields above — nothing moved, nothing was removed.
+     * It holds no position: it is rebuilt from (`positions`, `step`) on every
+     * render, so a view cannot end up rendering a stale copy.
+     */
+    readonly cursor: LensCursor;
 }
 /**
  * Snap a host-supplied step onto the axis. Non-finite and fractional values
  * 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, port, }: UseLensCursorArgs): UseLensCursorResult;
+declare function useLensCursor({ controlledStep, onStepChange, maxStep, describe, port, positions, }: UseLensCursorArgs): UseLensCursorResult;
 
 /**
  * useLensNavigator — move the ONE cursor to a stage by its address.
@@ -634,16 +641,67 @@ interface LensProps {
  *
  * Same idea as `<TraceExplorerShell slots>`: keep the shipped layout and the
  * shipped cursor, replace what one pane renders.
+ *
+ * THE LAW: **a slot fills a PANE, never the CHROME around it.** The rail's tab
+ * strip, the one cursor and the collapse pill belong to the library, because
+ * chrome is how the library adds capability over time — a consumer that fills a
+ * slot must still receive every capability the rail gains later. That is why
+ * `detail` is ONE TAB and not a takeover, and why `detailOnly` is an opt-out
+ * rather than the default.
  */
 interface LensSlots {
     /**
-     * Override the RIGHT column — the "what happened" timeline. Your component
-     * renders inside the shipped column (its width, borders, collapse pill and
-     * scroll behaviour are unchanged); only the content is yours.
+     * Render the right column's FIRST TAB — your own pane, beside the library's.
+     *
+     * Your component renders inside the shipped column (its width, borders,
+     * collapse pill and scroll behaviour are unchanged) and inside the shipped
+     * rail: the tab strip stays, your pane becomes the first tab and is selected
+     * by default, and "What happened", "Served" and "Bookmarks" stay reachable
+     * beside it. Switching tabs never moves the cursor and never unmounts your
+     * pane — it keeps its own state.
+     *
+     * Before 0.50.0 a supplied slot replaced the whole rail, tab strip included,
+     * so a slot consumer could not reach anything the rail gained afterwards.
+     * That was the defect this shape fixes; `detailOnly` is the way back.
      *
      * Omit it and the built-in timeline renders exactly as before.
+     *
+     * ```tsx
+     * <Lens recorder={recorder} slots={{ detail: MyBands, detailLabel: 'Bands' }} />
+     * // rail: [ Bands* | What happened | Served | Bookmarks ]
+     * ```
      */
     readonly detail?: React__default.ComponentType<LensDetailSlotProps>;
+    /**
+     * What the `detail` tab is CALLED. Default: `"Details"`.
+     *
+     * WHY it exists: the tab strip names each reading in the reader's own words,
+     * and "Details" is the library's generic word for someone else's pane. An app
+     * whose pane is a stack of SEO bands should say so — the strip is read left to
+     * right and an unnamed tab makes the app's own reading the anonymous one.
+     *
+     * A plain string, rendered as the tab's text; it is the accessible name too.
+     * Ignored when no `detail` slot is supplied.
+     *
+     * ```tsx
+     * slots={{ detail: MyBands, detailLabel: 'SEO bands' }}
+     * ```
+     */
+    readonly detailLabel?: string;
+    /**
+     * OPT OUT of the tab strip: the `detail` slot takes the whole rail, as it did
+     * before 0.50.0. Default `false`.
+     *
+     * For the app with a full-height custom layout of its own — a pane that owns
+     * its scroll and its header and would read as a second chrome under the
+     * library's strip. The cost is stated plainly: nothing the rail gains later
+     * (Served, Bookmarks, whatever follows) can reach that consumer, and neither
+     * can the library's own timeline. Prefer the tabs; take this only when the
+     * layout genuinely demands it.
+     *
+     * Ignored when no `detail` slot is supplied.
+     */
+    readonly detailOnly?: boolean;
 }
 /**
  * What the `detail` slot receives — the cursor, in the units a detail pane
@@ -670,6 +728,26 @@ interface LensDetailSlotProps {
     readonly recorder: LensRecorder;
     /** Move the ONE cursor — same funnel every built-in mover uses. */
     readonly onNavigate: (step: number) => void;
+    /**
+     * THE CURSOR, in the one vocabulary every view now shares (0.51.0) — the
+     * reading above (`cursor.at`), the axis's honest answer to an ADDRESS
+     * (`cursor.resolve(id)`), and the same funnel as `onNavigate`
+     * (`cursor.moveTo`).
+     *
+     * Everything else on this interface stays exactly as it was; this is the
+     * shape to reach for when your pane places elements BY ADDRESS, because the
+     * axis may honestly not stop where an address points:
+     *
+     * ```tsx
+     * const to = p.cursor.resolve(node.runtimeStageId);
+     * if (!to.ok) return <li data-unplaced title={to.message}>{node.name}</li>;
+     * return <li onClick={() => p.cursor.moveTo(to.step)}>{to.label}</li>;
+     * ```
+     *
+     * It holds no position of its own — it is rebuilt every render. Read it;
+     * never store it.
+     */
+    readonly cursor: LensCursor;
 }
 declare const Lens: React__default.FC<LensProps>;