agentfootprint-lens 0.49.0 → 0.50.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,6 +1256,23 @@ 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>`.
 
@@ -1377,7 +1406,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-_IjGLEGt.d.cts → Lens-DJJsMfud.d.cts}

@@ -634,16 +634,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

package/dist/{Lens-_hExvOXu.d.ts → Lens-okdu_w0H.d.ts}

@@ -634,16 +634,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

package/dist/{chunk-KS4AIWQJ.js → chunk-TBYKXQSA.js}

@@ -191,7 +191,7 @@ function withGroupEmphasisAll(nodeTypes, stageNode) {
 
 // src/react/lensStyles.ts
 var STYLE_MARKER = "data-lens-styles";
-var STYLE_VERSION = "v5";
+var STYLE_VERSION = "v6";
 var LENS_STYLESHEET = `
 /* The streaming caret's blink, and the in-flight edge's dash march. */
 @keyframes lens-blink { 50% { opacity: 0; } }
@@ -773,6 +773,16 @@ var LENS_STYLESHEET = `
   font-weight: 600;
   line-height: 1.5;
 }
+/* \u2500\u2500 The right rail's tab strip \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   The tabs are keyboard-reachable buttons, and this is the ring that says so.
+   A tab strip whose focus is invisible is a strip only a mouse can use, and
+   since 0.50.0 a host's own pane is one of these tabs \u2014 so the reader who
+   tabs to it must see where they are. */
+.lens-rail-tab:focus-visible {
+  outline: 2px solid ${T.primary};
+  outline-offset: -2px;
+}
+
 @media (prefers-reduced-motion: reduce) {
   .lens-group-boundary,
   .lens-group-node--member::after,
@@ -4809,7 +4819,11 @@ var EngineerView = ({
   const rowRef = useRef6(null);
   const stacked = useNarrowRow(rowRef);
   const DetailSlot = slots?.detail;
-  const [railTab, setRailTab] = useState8("happened");
+  const detailLabel = slots?.detailLabel ?? "Details";
+  const detailOnly = DetailSlot !== void 0 && slots?.detailOnly === true;
+  const [railTabChoice, setRailTabChoice] = useState8(void 0);
+  const defaultRailTab = DetailSlot !== void 0 ? "detail" : "happened";
+  const railTab = railTabChoice !== void 0 && (railTabChoice !== "detail" || DetailSlot !== void 0) && (railTabChoice !== "bookmarks" || bookmarks !== void 0) ? railTabChoice : defaultRailTab;
   const servedRunner = runner ?? recorder.observedRunner();
   const jumpToRuntimeStageId = useCallback6(
     (runtimeStageId) => {
@@ -4818,6 +4832,21 @@ var EngineerView = ({
     },
     [cursorPort, focusStep, onFocusChange]
   );
+  const detailPane = DetailSlot !== void 0 ? /* @__PURE__ */ jsx14(
+    DetailSlot,
+    {
+      step: focusStep,
+      totalSteps: total,
+      cursorRuntimeStageId,
+      commitIdx: cursorPositions[focusStep]?.commitIdx ?? -1,
+      label: cursorPositions[focusStep]?.label ?? "",
+      ...cursorPositions[focusStep]?.kind ? { kind: cursorPositions[focusStep].kind } : {},
+      ...cursorFocusedNode ? { node: cursorFocusedNode } : {},
+      relatedNodes: cursorRelatedNodes,
+      recorder,
+      onNavigate: onFocusChange
+    }
+  ) : null;
   return /* @__PURE__ */ jsxs13(
     "div",
     {
@@ -5109,22 +5138,21 @@ var EngineerView = ({
                       borderTop: `1px solid ${T.border}`
                     } : {}
                   },
-                  children: DetailSlot ? /* @__PURE__ */ jsx14(
-                    DetailSlot,
-                    {
-                      step: focusStep,
-                      totalSteps: total,
-                      cursorRuntimeStageId,
-                      commitIdx: cursorPositions[focusStep]?.commitIdx ?? -1,
-                      label: cursorPositions[focusStep]?.label ?? "",
-                      ...cursorPositions[focusStep]?.kind ? { kind: cursorPositions[focusStep].kind } : {},
-                      ...cursorFocusedNode ? { node: cursorFocusedNode } : {},
-                      relatedNodes: cursorRelatedNodes,
-                      recorder,
-                      onNavigate: onFocusChange
-                    }
-                  ) : /* @__PURE__ */ jsxs13(Fragment6, { children: [
+                  children: detailOnly ? detailPane : /* @__PURE__ */ jsxs13(Fragment6, { children: [
                     /* @__PURE__ */ jsxs13("div", { role: "tablist", "aria-label": "Right rail", style: railTabsStyle, children: [
+                      DetailSlot !== void 0 && /* @__PURE__ */ jsx14(
+                        "button",
+                        {
+                          type: "button",
+                          role: "tab",
+                          "aria-selected": railTab === "detail",
+                          "data-testid": "rail-tab-detail",
+                          className: "lens-rail-tab",
+                          style: railTabStyle(railTab === "detail"),
+                          onClick: () => setRailTabChoice("detail"),
+                          children: detailLabel
+                        }
+                      ),
                       /* @__PURE__ */ jsx14(
                         "button",
                         {
@@ -5132,8 +5160,9 @@ var EngineerView = ({
                           role: "tab",
                           "aria-selected": railTab === "happened",
                           "data-testid": "rail-tab-happened",
+                          className: "lens-rail-tab",
                           style: railTabStyle(railTab === "happened"),
-                          onClick: () => setRailTab("happened"),
+                          onClick: () => setRailTabChoice("happened"),
                           children: "What happened"
                         }
                       ),
@@ -5144,8 +5173,9 @@ var EngineerView = ({
                           role: "tab",
                           "aria-selected": railTab === "served",
                           "data-testid": "rail-tab-served",
+                          className: "lens-rail-tab",
                           style: railTabStyle(railTab === "served"),
-                          onClick: () => setRailTab("served"),
+                          onClick: () => setRailTabChoice("served"),
                           children: "Served"
                         }
                       ),
@@ -5156,13 +5186,28 @@ var EngineerView = ({
                           role: "tab",
                           "aria-selected": railTab === "bookmarks",
                           "data-testid": "rail-tab-bookmarks",
+                          className: "lens-rail-tab",
                           style: railTabStyle(railTab === "bookmarks"),
-                          onClick: () => setRailTab("bookmarks"),
+                          onClick: () => setRailTabChoice("bookmarks"),
                           children: "Bookmarks"
                         }
                       )
                     ] }),
-                    railTab === "bookmarks" && bookmarks !== void 0 ? /* @__PURE__ */ jsx14(
+                    DetailSlot !== void 0 && /* @__PURE__ */ jsx14(
+                      "div",
+                      {
+                        "data-testid": "rail-pane-detail",
+                        style: {
+                          display: railTab === "detail" ? "flex" : "none",
+                          flexDirection: "column",
+                          flex: "1 1 auto",
+                          minHeight: 0,
+                          overflow: "hidden"
+                        },
+                        children: detailPane
+                      }
+                    ),
+                    railTab === "detail" ? null : railTab === "bookmarks" && bookmarks !== void 0 ? /* @__PURE__ */ jsx14(
                       BookmarksTab,
                       {
                         bookmarks: bookmarks.bookmarks,
@@ -6042,4 +6087,4 @@ export {
   useBookmarkSidecar,
   Lens
 };
-//# sourceMappingURL=chunk-KS4AIWQJ.js.map
+//# sourceMappingURL=chunk-TBYKXQSA.js.map