@kud/gh-ink 0.74.0 → 0.75.1

package/README.md

@@ -61,6 +61,31 @@ codepoints; sibling host verbs should match them rather than invent neighbours:
 | Unsubscribe / Mute / Remove reviewer | U+F478 / U+F466 / U+F468 |
 | Close PR / and delete / issue  | U+F4DC / U+F48E / U+F41D |
 
+## Inbox focus slot and tab icons
+
+`App` draws one standing row directly above the tab strip for whatever the
+reader should look at next. The fetch result carries it as
+`focus?: FocusSlot | null`: absent means the host has no focus feature and no
+row is drawn; `null` means nothing to point at and draws the dim empty line.
+It rides the fetch (and the cache beside the rows) because it goes stale the
+same way they do.
+
+| Prop / field       | What                                                                                                |
+| ------------------ | --------------------------------------------------------------------------------------------------- |
+| `focusLabel`       | What to call the row (default `focus`). Passing this or `focusEmpty` reserves the row from first paint. |
+| `focusEmpty`       | The empty sentence, drawn dim after the label when focus comes back `null`.                         |
+| `FocusSlot`        | `label`, `ref` (a ticket key, or a PR-style `#427`), `title`, `reason`, optional `marker` (the host's priority glyph), `mark`/`markColor`/`refColor` overrides, and `target: { tab, url }`. |
+| `g`                | Jumps to `focus.target`: switches to that tab and lands the cursor on that row, opening a collapsed tail it is folded into. Listed in the `?` legend only while a focus is on screen. |
+
+A row whose url matches the target draws the mark in a fixed gutter between
+the tree glyph and the marker cell; every other row holds two blanks there, so
+the mark moves nothing sideways. Without a focus the rows draw what they
+always drew.
+
+Tabs take an optional `Section.icon`, passed through to ink-ui's
+`TabItem.icon`: one glyph naming the tab beside its label, which is also what
+an inactive tab folds down to when the strip does not fit its width.
+
 ## Development
 
 ```sh

package/dist/index.d.ts

@@ -179,6 +179,101 @@ declare const SidePanel: ({ sidebar, liveLabel, width, height, focused, cursor,
     cursor?: number;
 }) => React.JSX.Element;
 
+/**
+ * The one thing the reader should look at next, in the host's words.
+ *
+ * Data, not vocabulary: `label` is the host's word for the row ("focus"), but
+ * everything else arrived over the wire — which ticket, what it says, where it
+ * lives — and goes stale the same way the rows do. That is why it rides the
+ * fetch result (and the cache beside the rows) rather than arriving as props.
+ *
+ * `undefined` (the field absent) means the host has no focus feature and draws
+ * no row at all; `null` means there is one and it currently has nothing to
+ * point at, which draws the dim empty line. The distinction matters because a
+ * host that never wired the feature must keep byte-identical output, while a
+ * host whose feature came back empty still owes the reader one line saying so.
+ */
+type FocusSlot = {
+    /** The mark in front of the row, accent by default. */
+    mark?: string;
+    /** The mark's colour. Defaults to the accent. */
+    markColor?: string;
+    /** What the row is a slot OF, in the host's words: `focus`, say. */
+    label: string;
+    /** The thing to look at: a ticket key, or a PR-style `#427`. */
+    ref: string;
+    /** The ref's colour. A `#` ref takes the accent, anything else the ticket. */
+    refColor?: string;
+    /** The row's own title, bold. Truncated to keep the line to one row. */
+    title: string;
+    /** Why this is the focus, dim, three spaces after the title. */
+    reason: string;
+    /** The host's priority glyph for the row, drawn in the default foreground. */
+    marker?: string;
+    /** Where `g` goes: the tab id and the row url. */
+    target: {
+        tab: string;
+        url: string;
+    };
+};
+declare const FOCUS_MARK = "\uDB81\uDCFE";
+declare const FOCUS_JUMP_KEY = "g";
+declare const DEFAULT_FOCUS_LABEL = "focus";
+declare const DEFAULT_FOCUS_EMPTY = "nothing to focus on";
+/**
+ * What one row draws in the focus gutter, resolved by the list. `undefined`
+ * means no focus is on screen and the row draws nothing — the branch is
+ * absent, not blank, so output without the feature is byte-identical. `null`
+ * holds two blank columns on a row the focus is not pointing at, so the one
+ * row that carries the mark does not shift its neighbours.
+ */
+type FocusGutter = {
+    mark: string;
+    color?: string;
+} | null;
+/**
+ * The gutter cell for a row url: the mark when this is the row `g` would land
+ * on, a blank holder on every other row while a focus is on screen, nothing at
+ * all without one. One function so the task rows and the PR rows cannot
+ * disagree about which row is marked.
+ */
+declare const focusCellFor: (focus: FocusSlot | null | undefined, url: string | undefined) => FocusGutter | undefined;
+/**
+ * The ref's colour, for the one decision the frame cannot show. A `#427` is a
+ * pull request and takes the accent — the same orange the PR rows number
+ * themselves in — while a ticket key takes the ticket yellow. An explicit
+ * `refColor` wins over both, for a host whose refs follow another vocabulary.
+ *
+ * Exported pure because the test frame carries no escape codes: a colour that
+ * lived only in a tint would be a colour nobody can test for.
+ */
+declare const focusRefColor: (focus: Pick<FocusSlot, "ref" | "refColor">) => string;
+/**
+ * One standing single-line row, the same height across loading / ready / empty
+ * so the tab strip below it never jumps — the same contract `StatusStripLine`
+ * keeps, and drawn in the same place, directly above the tabs.
+ *
+ * `undefined` while the first answer is out; `null` when the host answered
+ * with nothing to point at. Either prop (`label`/`empty`) reserves the row;
+ * with neither and no focus value the caller draws nothing at all.
+ */
+declare const FocusSlotLine: ({ focus, label, empty, width, jumpKey, }: {
+    /** `undefined` while the first answer is out; `null` when it came back empty. */
+    focus: FocusSlot | null | undefined;
+    /** What to call the row. The host's word; defaults to `focus`. */
+    label?: string;
+    /** The empty sentence, drawn dim after the label when focus is null. */
+    empty?: string;
+    /** Columns the row may use. */
+    width: number;
+    /**
+     * The key that jumps to the focus row, drawn as a quiet hint after the
+     * reason. Ready rows only: loading and empty have no row to jump to, so
+     * they never draw it even when it is set.
+     */
+    jumpKey?: string;
+}) => React.JSX.Element;
+
 /**
  * How this row is moving through the list right now.
  *
@@ -270,6 +365,15 @@ type PrRowProps = {
      * to the title rather than standing empty.
      */
     gutter?: boolean;
+    /**
+     * The focus gutter, resolved by the list — see `focusCellFor`. `undefined`
+     * draws nothing at all (no focus feature, byte-identical to before); `null`
+     * holds two blank columns so the marked row does not shift its neighbours;
+     * a mark draws the focus glyph there in its colour. A fixed cell either way,
+     * for the same reason the cursor gutter is one: a mark that moved the title
+     * of exactly the row being watched would defeat its own purpose.
+     */
+    focusCell?: FocusGutter;
 };
 /**
  * The trailing block, in reading order: whose, how contested, how big, how
@@ -313,7 +417,9 @@ declare const trailingColumnsOf: (items: readonly GHItem[]) => TrailingColumns;
  * three, and a six-digit number would have run straight into its title.
  */
 declare const numberColumnsOf: (items: readonly GHItem[]) => number;
-type LayoutInput = Pick<PrRowProps, "item" | "login" | "cols" | "prefix" | "uniformLabels" | "announcements" | "columns" | "shed" | "numberCols" | "gutter">;
+type LayoutInput = Pick<PrRowProps, "item" | "login" | "cols" | "prefix" | "uniformLabels" | "announcements" | "columns" | "shed" | "numberCols" | "gutter"> & {
+    focusGutter?: boolean;
+};
 /**
  * Which trailing columns the section has to give up, so that every row gives up
  * the same ones. Each row is laid out alone and the drops are unioned: if any
@@ -339,7 +445,7 @@ declare const sectionShedOf: (rows: readonly Pick<LayoutInput, "item" | "prefix"
  * arrival, merge and departure belongs to whoever owns the list, and reaches
  * the row as `icon`, `motion` and `announcements` after the decisions are made.
  */
-declare const PrRow: ({ item, active, login, cols, selectionBg, icon: iconOverride, prefix, uniformLabels, motion, announcements, columns, shed, numberCols, gutter, }: PrRowProps) => React.JSX.Element;
+declare const PrRow: ({ item, active, login, cols, selectionBg, icon: iconOverride, prefix, uniformLabels, motion, announcements, columns, shed, numberCols, gutter, focusCell, }: PrRowProps) => React.JSX.Element;
 
 /**
  * One state per thing, from a closed set the strip knows how to draw. The host
@@ -517,6 +623,16 @@ type CachedCockpit = {
      * refresh — `i` did nothing and the footer did not even offer it.
      */
     sidebar?: Rails;
+    /**
+     * The focus slot, when the host supplied one. Cached beside the rows because
+     * it is painted beside them: a launch that trusts the cache never refetches,
+     * so a focus left out of the file is a slot that stays on `loading…` until
+     * the next refresh — or never fills in at all.
+     *
+     * Absent reads as `undefined`: no focus feature, no row. `null` is a real
+     * answer ("nothing to focus on") and round-trips as one.
+     */
+    focus?: FocusSlot | null;
 };
 declare const readCache: (key: string) => CachedCockpit | null;
 declare const writeCache: (key: string, data: {
@@ -524,6 +640,7 @@ declare const writeCache: (key: string, data: {
     login: string;
     budget?: InboxBudget;
     sidebar?: Rails;
+    focus?: FocusSlot | null;
 }) => void;
 
 /**
@@ -880,7 +997,7 @@ declare const ActionMenu: ({ item, actions, cursor, cols, }: {
     cols?: number;
 }) => React.JSX.Element;
 declare const signatureOf: (sections: Section[]) => string;
-declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jiraKeyRe, jiraSetupHint, jiraTransitions, jiraTransitionsFor, tabForStatus, hasCiStatus, ciJob, ciFetcher, ciPollMs, stripFetcher, stripLabel, stripPollMs, watchPath, watchDebounceMs, watchJitterMs, extensions, tabHelp, emptyHint, liveLabel, onSettled, }: {
+declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jiraKeyRe, jiraSetupHint, jiraTransitions, jiraTransitionsFor, tabForStatus, hasCiStatus, ciJob, ciFetcher, ciPollMs, stripFetcher, stripLabel, stripPollMs, focusLabel, focusEmpty, watchPath, watchDebounceMs, watchJitterMs, extensions, tabHelp, emptyHint, liveLabel, onSettled, }: {
     fetcher: () => Promise<{
         sections: Section[];
         login: string;
@@ -901,6 +1018,15 @@ declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jir
          * data that goes stale the same way the rows do.
          */
         sidebar?: Rails;
+        /**
+         * What the reader should look at next, in the host's words — see
+         * `FocusSlot`. Part of the fetch result for the same reason the rail is:
+         * it goes stale with the rows, and the cache paints it beside them.
+         *
+         * Absent means the host has no focus feature and no row is drawn; `null`
+         * means nothing to point at and draws the dim empty line.
+         */
+        focus?: FocusSlot | null;
     }>;
     cacheKey?: string;
     /**
@@ -943,6 +1069,16 @@ declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jir
     /** What to call the row before its first answer arrives with a title. */
     stripLabel?: string;
     stripPollMs?: number;
+    /**
+     * What to call the focus row. Passing this (or `focusEmpty`) reserves the
+     * row from the first paint — `loading…` until the fetch lands — while a
+     * host that never wires the feature passes neither and draws nothing.
+     * Vocabulary, not data: it never goes stale, so it is a prop rather than
+     * part of the fetch result.
+     */
+    focusLabel?: string;
+    /** The empty sentence, drawn dim after the label when focus comes back null. */
+    focusEmpty?: string;
     /**
      * A file something else touches when it has changed GitHub on your behalf —
      * a Claude session closing an issue, a script merging a PR. Touching it makes
@@ -995,4 +1131,4 @@ declare const matchesFilter: (repo: string, filter: RepoFilter) => boolean;
  */
 declare const parsePatterns: (value: string) => string[];
 
-export { type Action, type ActionGroup, ActionMenu, App, COLS, type ChromeHints, type ChromeSpec, type ChromeState, CiStatusLine, type CiStatusState, type Command, CommentsPanel, type CommentsPanelProps, type DetailContext, type ExplainSection, type ExtensionTarget, HealthPanel, type HealthPanelProps, type InboxBudget, type InboxExtension, type JiraAvailableTransition, type JiraTransition, type JiraTransitionsFor, type LiveLabel, LookupMiss, MIN_SIDEBAR_COLS, type MenuGap, type MenuRow, PrRow, type PrRowProps, type Rails, type RepoFilter, type RowAnnouncement, type RowMotion, SIDEBAR_COLS, type SettledResult, SidePanel, type Sidebar, type SidebarRow, type StatusStrip, StatusStripLine, type StripItem, type StripState, type StripStatusState, type TabForStatus, type TrailingColumns, type TrailingShed, ageLabel, budgetNotice, buildActions, buildCheckoutCmd, clipboard, counts, drillCmd, explainGhAction, explainItem, fitCount, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, isMenuGap, itermRun, jumpToRepo, jumpToRepoPane, matchesFilter, maxViewStart, menuRowsOf, menuTone, moveCursor, numberColumnsOf, openInTab, parsePatterns, railCapacity, railHeights, railRowsOf, railWidth, railsOf, readCache, renderMarkdown, reposInSections, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, sectionShedOf, signatureOf, stripGlyph, stripLayout, stripSignature, toCiStatusState, trailingColumnsOf, truncate, useActionMenu, useChrome, windowCount, withHeaders, withoutItem, workCount, writeCache };
+export { type Action, type ActionGroup, ActionMenu, App, COLS, type ChromeHints, type ChromeSpec, type ChromeState, CiStatusLine, type CiStatusState, type Command, CommentsPanel, type CommentsPanelProps, DEFAULT_FOCUS_EMPTY, DEFAULT_FOCUS_LABEL, type DetailContext, type ExplainSection, type ExtensionTarget, FOCUS_JUMP_KEY, FOCUS_MARK, type FocusGutter, type FocusSlot, FocusSlotLine, HealthPanel, type HealthPanelProps, type InboxBudget, type InboxExtension, type JiraAvailableTransition, type JiraTransition, type JiraTransitionsFor, type LiveLabel, LookupMiss, MIN_SIDEBAR_COLS, type MenuGap, type MenuRow, PrRow, type PrRowProps, type Rails, type RepoFilter, type RowAnnouncement, type RowMotion, SIDEBAR_COLS, type SettledResult, SidePanel, type Sidebar, type SidebarRow, type StatusStrip, StatusStripLine, type StripItem, type StripState, type StripStatusState, type TabForStatus, type TrailingColumns, type TrailingShed, ageLabel, budgetNotice, buildActions, buildCheckoutCmd, clipboard, counts, drillCmd, explainGhAction, explainItem, fitCount, focusCellFor, focusRefColor, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, isMenuGap, itermRun, jumpToRepo, jumpToRepoPane, matchesFilter, maxViewStart, menuRowsOf, menuTone, moveCursor, numberColumnsOf, openInTab, parsePatterns, railCapacity, railHeights, railRowsOf, railWidth, railsOf, readCache, renderMarkdown, reposInSections, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, sectionShedOf, signatureOf, stripGlyph, stripLayout, stripSignature, toCiStatusState, trailingColumnsOf, truncate, useActionMenu, useChrome, windowCount, withHeaders, withoutItem, workCount, writeCache };

package/dist/index.js

@@ -876,7 +876,8 @@ var layoutOf = ({
   columns,
   shed = {},
   numberCols,
-  gutter = true
+  gutter = true,
+  focusGutter = false
 }) => {
   const numCols = numberCols ?? numberColumnsOf([item]);
   const numStr = `#${item.number}`.padEnd(numCols);
@@ -923,7 +924,7 @@ var layoutOf = ({
     );
     const pills = announcements.reduce((w, a) => w + 2 + a.label.length, 0);
     const cell = labelCell();
-    return (gutter ? 2 : 0) + prefix.length + 2 + 2 + numCols + (cell ? 2 + cell.length + 1 : 0) + (givingUp.repo ? 0 : repoLabel.length) + block + pills + pillCaps + 4;
+    return (gutter ? 2 : 0) + prefix.length + (focusGutter ? 2 : 0) + 2 + 2 + numCols + (cell ? 2 + cell.length + 1 : 0) + (givingUp.repo ? 0 : repoLabel.length) + block + pills + pillCaps + 4;
   };
   const MIN_TITLE = 24;
   for (const give of [
@@ -969,7 +970,8 @@ var PrRow = ({
   columns,
   shed,
   numberCols,
-  gutter = true
+  gutter = true,
+  focusCell
 }) => {
   const backdropped = useBackdropped();
   const { glyph: healthIcon, color: healthColor2 } = displayFor(item.health);
@@ -1002,7 +1004,8 @@ var PrRow = ({
     columns,
     shed,
     numberCols,
-    gutter
+    gutter,
+    focusGutter: focusCell !== void 0
   });
   return (
     // The wash paints every cell of the fixed-width row — an Ink Box's
@@ -1010,6 +1013,7 @@ var PrRow = ({
     /* @__PURE__ */ jsxs(Box, { width: cols, backgroundColor: selectionBg, children: [
       gutter ? /* @__PURE__ */ jsx(Text3, { color: colors.info, children: active ? "\u276F " : "  " }) : null,
       /* @__PURE__ */ jsx(Text3, { dimColor: true, children: prefix }),
+      focusCell !== void 0 ? focusCell ? /* @__PURE__ */ jsx(Text3, { color: focusCell.color, bold: true, children: `${focusCell.mark} ` }) : /* @__PURE__ */ jsx(Text3, { children: "  " }) : null,
       /* @__PURE__ */ jsx(Text3, { color, bold: true, children: icon + " " }),
       /* @__PURE__ */ jsx(Text3, { color: turnColor, bold: turnIcon === "\u2190", children: turnIcon + " " }),
       /* @__PURE__ */ jsx(Text3, { color: colors.accent, children: numStr }),
@@ -1372,7 +1376,7 @@ var lookupRows = (claim, lookup, query, start, openUrl) => {
 
 // src/inbox/cache.ts
 var cacheTtlMs = () => inboxConfig().cacheTtlMs;
-var CACHE_VERSION = 5;
+var CACHE_VERSION = 6;
 var cacheDir = () => join(
   process.env.XDG_CACHE_HOME || join(homedir(), ".cache"),
   inboxConfig().cacheNamespace
@@ -1383,11 +1387,14 @@ var readCache = (key) => {
     const raw = JSON.parse(readFileSync(cacheFile(key), "utf8"));
     if (raw?.version !== CACHE_VERSION) return null;
     if (!Array.isArray(raw?.sections)) return null;
+    const focusOk = raw.focus === void 0 || raw.focus === null || typeof raw.focus?.target?.tab === "string" && typeof raw.focus?.target?.url === "string";
+    if (!focusOk) return null;
     return {
       sections: raw.sections,
       login: raw.login ?? "",
       at: raw.at ?? 0,
       budget: raw.budget,
+      ...raw.focus !== void 0 ? { focus: raw.focus } : {},
       ...railsOf(raw.sidebar).every((s) => Array.isArray(s?.rows)) && raw.sidebar !== void 0 ? { sidebar: raw.sidebar } : {}
     };
   } catch {
@@ -1686,6 +1693,73 @@ var failureNotice = (failed) => {
   const more = failed.length > 1 ? `  +${failed.length - 1} more` : "";
   return `\u2717 Couldn't ${newest.action} ${newest.label}: ${newest.failure?.reason ?? "no reason reported"}${more}  w restore`;
 };
+var FOCUS_MARK = "\u{F04FE}";
+var FOCUS_JUMP_KEY = "g";
+var DEFAULT_FOCUS_LABEL = "focus";
+var DEFAULT_FOCUS_EMPTY = "nothing to focus on";
+var focusCellFor = (focus, url) => {
+  if (focus === void 0) return void 0;
+  if (!focus || url !== focus.target.url) return null;
+  return { mark: focus.mark ?? FOCUS_MARK, color: focus.markColor ?? colors.accent };
+};
+var focusRefColor = (focus) => focus.refColor ?? (focus.ref.startsWith("#") ? colors.accent : colors.ticket);
+var cells = (s) => [...s].length;
+var titleBudgetOf = (focus, label, width, jumpKey) => {
+  const hint = jumpKey ? jumpKey : void 0;
+  const mark = focus.mark ?? FOCUS_MARK;
+  const head = 2 + cells(mark) + 1 + cells(label) + 2 + (focus.marker ? cells(focus.marker) + 1 : 0) + cells(focus.ref) + 2;
+  const hintCells = hint ? 3 + cells(hint) + 5 : 0;
+  const tail = 3 + cells(focus.reason);
+  const titleMax = width - head - tail - hintCells;
+  if (titleMax >= 1)
+    return { title: truncate(focus.title, titleMax), reason: focus.reason, hint };
+  const reasonMax = width - head - 3 - 1 - hintCells;
+  if (hint === void 0 || reasonMax >= 1)
+    return {
+      title: "",
+      reason: truncate(focus.reason, Math.max(0, width - head - 3 - 1 - hintCells)),
+      hint
+    };
+  return {
+    title: "",
+    reason: truncate(focus.reason, Math.max(0, width - head - 3 - 1)),
+    hint: void 0
+  };
+};
+var FocusSlotLine = ({
+  focus,
+  label = DEFAULT_FOCUS_LABEL,
+  empty = DEFAULT_FOCUS_EMPTY,
+  width,
+  jumpKey
+}) => {
+  if (focus === void 0)
+    return /* @__PURE__ */ jsxs(Box, { marginBottom: 1, children: [
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: "  \xB7 " }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: `${label}  loading\u2026` })
+    ] });
+  if (focus === null)
+    return /* @__PURE__ */ jsxs(Box, { marginBottom: 1, children: [
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: `  ${FOCUS_MARK} ` }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: `${label}  ${empty}` })
+    ] });
+  const mark = focus.mark ?? FOCUS_MARK;
+  const { title, reason, hint } = titleBudgetOf(focus, label, width, jumpKey);
+  return /* @__PURE__ */ jsxs(Box, { marginBottom: 1, children: [
+    /* @__PURE__ */ jsx(Text, { children: "  " }),
+    /* @__PURE__ */ jsx(Text, { color: focus.markColor ?? colors.accent, bold: true, children: `${mark} ` }),
+    /* @__PURE__ */ jsx(Text, { dimColor: true, children: `${label}  ` }),
+    focus.marker ? /* @__PURE__ */ jsx(Text, { children: `${focus.marker} ` }) : null,
+    /* @__PURE__ */ jsx(Text, { color: focusRefColor(focus), bold: true, children: `${focus.ref}  ` }),
+    /* @__PURE__ */ jsx(Text, { bold: true, children: title }),
+    /* @__PURE__ */ jsx(Text, { dimColor: true, children: `   ${reason}` }),
+    hint ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: "   " }),
+      /* @__PURE__ */ jsx(Text, { color: colors.accent, bold: true, children: hint }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: " jump" })
+    ] }) : null
+  ] });
+};
 var quietly = $({ quiet: true });
 var isMenuGap = (row) => "gap" in row;
 var rowLabelOf = (item) => item.kind === "task" ? item.ticket ?? item.key : item.kind === "pr" || item.kind === "issue" ? `#${item.number}` : "";
@@ -2911,7 +2985,8 @@ var ItemRow = ({
   uniformLabels = [],
   columns,
   shed,
-  numberCols
+  numberCols,
+  focus
 }) => {
   const backdropped = useBackdropped();
   const selBg = selectionBackground(active, backdropped);
@@ -2955,12 +3030,16 @@ var ItemRow = ({
     const transitIcon = pending ? PENDING_GLYPH : !transient ? " " : isDeparture(transient) ? TRANSIT_OUT_FRAMES[rampAt(TRANSIT_OUT_FRAMES.length)] : isArrival(transient) ? TRANSIT_IN_FRAMES[rampAt(TRANSIT_IN_FRAMES.length)] : "\u25C9";
     const titleMax = Math.max(
       1,
-      cols - item.key.length - note.length - (item.pill ? pillWidth(item.pill) + 1 : 0) - (farewellLabel ? pillWidth(farewellLabel) + 2 : 0) - prefix.length - (markerCols > 0 ? markerCols + 1 : 0) - 12
+      cols - item.key.length - note.length - (item.pill ? pillWidth(item.pill) + 1 : 0) - (farewellLabel ? pillWidth(farewellLabel) + 2 : 0) - prefix.length - (markerCols > 0 ? markerCols + 1 : 0) - // The focus gutter, priced only when it is drawn: two columns on every
+      // url-bearing row while a focus is on screen, none at all without one.
+      (focus !== void 0 ? 2 : 0) - 12
     );
+    const focusCell = focusCellFor(focus, item.url);
     return /* @__PURE__ */ jsxs(Box, { marginTop: gap ? 1 : 0, width: cols, backgroundColor: selBg, children: [
       /* @__PURE__ */ jsx(Text3, { color: colors.info, children: active ? "\u276F " : "  " }),
       /* @__PURE__ */ jsx(Text3, { dimColor: true, children: prefix }),
       /* @__PURE__ */ jsx(Text3, { dimColor: true, children: parent ? "\u252C " : "  " }),
+      focusCell !== void 0 ? focusCell ? /* @__PURE__ */ jsx(Text3, { color: focusCell.color, bold: true, children: `${focusCell.mark} ` }) : /* @__PURE__ */ jsx(Text3, { children: "  " }) : null,
       pending ? /* @__PURE__ */ jsx(Text3, { dimColor: true, children: transitIcon + " " }) : /* @__PURE__ */ jsx(Text3, { bold: true, color: transient ? TRANSIT_COLOUR[transient] : void 0, children: transitIcon + " " }),
       markerCols > 0 ? /* @__PURE__ */ jsx(Text3, { color: item.markerColor, children: (item.marker ?? "").padEnd(markerCols) + " " }) : null,
       /* @__PURE__ */ jsx(Text3, { ...taskKeyStyle(), children: item.key + "  " }),
@@ -3019,7 +3098,11 @@ var ItemRow = ({
       numberCols,
       icon,
       motion,
-      announcements
+      announcements,
+      focusCell: focusCellFor(
+        focus,
+        "url" in item ? item.url : void 0
+      )
     }
   );
 };
@@ -3223,6 +3306,7 @@ var LEGEND_FOOTNOTE = "Each item lands in the FIRST tab that claims it, so count
 var HelpModal = ({
   extensions,
   hasJira,
+  hasFocus,
   tabHelp,
   maxRows,
   scroll = 0,
@@ -3257,6 +3341,7 @@ var HelpModal = ({
     ["f", "filter by repo"],
     ["r", "refresh"],
     ["w", "restore a change that failed"],
+    ...hasFocus ? [[FOCUS_JUMP_KEY, "jump to focus"]] : [],
     ...extensionLegend(extensions),
     ["?", "this help"],
     ["q", "quit"]
@@ -3452,6 +3537,9 @@ var BrowseScreen = ({
   ciJob,
   stripState,
   stripLabel,
+  focus,
+  focusLabel,
+  focusEmpty,
   tabHelp,
   origin,
   budget,
@@ -3503,12 +3591,13 @@ var BrowseScreen = ({
   const filterActive = search != null || repoFilter.size > 0;
   const reserveCiRow = ciStatusState != null;
   const reserveStripRow = stripState != null;
+  const reserveFocusRow = focusLabel !== void 0 || focusEmpty !== void 0 || focus !== void 0;
   const ciStatus = ciStatusState?.kind === "ready" ? ciStatusState.status : null;
   const listHeight = Math.max(
     5,
     // -10 rather than -8: the extra 2 are the frame's top and bottom border
     // rows, so the tree never grows taller than the terminal inside the frame.
-    rows - 10 - (filterActive ? 2 : 0) - (reserveCiRow ? 2 : 0) - (reserveStripRow ? 2 : 0)
+    rows - 10 - (filterActive ? 2 : 0) - (reserveCiRow ? 2 : 0) - (reserveStripRow ? 2 : 0) - (reserveFocusRow ? 2 : 0)
   );
   useEffect(() => {
     setLocalSections(applyWork(sections));
@@ -3654,7 +3743,10 @@ var BrowseScreen = ({
       cols: rowCols,
       uniformLabels,
       columns: trailingColumns,
-      numberCols
+      numberCols,
+      // Presence only: every row holds the same two gutter columns while a
+      // focus is on screen, so the shed ladder prices the cost once for all.
+      focusGutter: focus !== void 0
     }
   );
   const [sparkFrame, setSparkFrame] = useState(0);
@@ -3894,6 +3986,56 @@ var BrowseScreen = ({
       onRefresh?.();
       return;
     }
+    if (input === FOCUS_JUMP_KEY && focus) {
+      const tabId = focus.target.tab;
+      const at = localSections.findIndex((s) => s.id === tabId);
+      if (at === -1) return;
+      const drawn = (s) => {
+        const one = search != null ? filterBySearch([s], search, login) : [s];
+        const two = repoFilter.size > 0 ? filterByRepos(one, repoFilter, login) : one;
+        return filterActive ? two[0]?.items ?? [] : s.items;
+      };
+      const urlOf = (i) => "url" in i ? i.url : void 0;
+      let items = localSections[at].items;
+      if (!items.some((i) => urlOf(i) === focus.target.url)) {
+        const tail = items.find(
+          (i) => i.kind === "show-more" && i.hidden.some((h) => h.url === focus.target.url)
+        );
+        if (!tail) {
+          setTabIdx(at);
+          return;
+        }
+        items = [
+          ...items.slice(0, items.indexOf(tail)),
+          ...tail.hidden,
+          {
+            kind: "show-less",
+            toHide: tail.hidden,
+            // The depth of the row it replaces, never a constant — a collapsed
+            // row under a story sits deeper than 1, and pinning it breaks the
+            // `treeUrls` walk exactly as the comment there warns.
+            depth: depthOf(tail)
+          },
+          ...items.slice(items.indexOf(tail) + 1)
+        ];
+        const expanded = items;
+        setLocalSections(
+          (prev) => prev.map((s) => s.id === tabId ? { ...s, items: expanded } : s)
+        );
+        prevItems.current = { ...prevItems.current, [tabId]: expanded };
+      }
+      setTabIdx(at);
+      const shown = drawn({ ...localSections[at], items });
+      const dit = shown.findIndex((i) => urlOf(i) === focus.target.url);
+      if (dit === -1) return;
+      setCursors((p) => ({ ...p, [tabId]: dit }));
+      setViewStarts((p) => {
+        let vs = Math.min(p[tabId] ?? 0, withHeaders(shown, dit));
+        while (dit >= vs + windowCount(shown, vs, listHeight)) vs++;
+        return { ...p, [tabId]: vs };
+      });
+      return;
+    }
     const ext = extensionFor(input, extensions);
     if (ext) {
       onOpenExt?.(ext.id, extensionTargetFor(activeItem));
@@ -4309,6 +4451,7 @@ var BrowseScreen = ({
     {
       extensions,
       hasJira: !!jiraBase,
+      hasFocus: focus != null,
       tabHelp,
       maxRows: listHeight,
       scroll: helpScroll,
@@ -4365,6 +4508,16 @@ var BrowseScreen = ({
             width: COLS
           }
         ) : null,
+        reserveFocusRow ? /* @__PURE__ */ jsx(
+          FocusSlotLine,
+          {
+            focus,
+            label: focusLabel,
+            empty: focusEmpty,
+            width: COLS,
+            jumpKey: FOCUS_JUMP_KEY
+          }
+        ) : null,
         skippedForBudget ? /* @__PURE__ */ jsxs(Box, { marginBottom: 1, children: [
           /* @__PURE__ */ jsx(Text3, { bold: true, color: colors.accent, children: "  \u26A1 auto-refresh paused to save API budget" }),
           /* @__PURE__ */ jsx(Text3, { dimColor: true, children: "   r refreshes anyway" })
@@ -4373,9 +4526,11 @@ var BrowseScreen = ({
           Tabs,
           {
             active: section.id,
+            width: COLS,
             items: localSections.map((s) => ({
               value: s.id,
               label: s.label,
+              icon: s.icon,
               count: countOf(s.id),
               /*
                * The denominator, and only where it can still be true.
@@ -4461,6 +4616,7 @@ var BrowseScreen = ({
                           columns: trailingColumns,
                           shed: trailingShed,
                           numberCols,
+                          focus,
                           gap: i > 0 && gapsAbove(section.items, viewStart + i)
                         },
                         `${viewStart + i}:${rowKey(item)}`
@@ -4556,6 +4712,8 @@ var App = ({
   stripFetcher,
   stripLabel,
   stripPollMs = 3e5,
+  focusLabel,
+  focusEmpty,
   watchPath,
   watchDebounceMs = 400,
   // Zero by default, deliberately. A package that adds randomness to its own
@@ -4610,6 +4768,7 @@ var App = ({
     return sameCiStatusState(prev, next) ? prev : next;
   });
   const hasStrip = !!stripFetcher;
+  const hasFocusSlot = focusLabel !== void 0 || focusEmpty !== void 0;
   const [stripState, setStripState] = useState({
     kind: "loading"
   });
@@ -4738,6 +4897,7 @@ var App = ({
         )
       };
       if (fresh.budget) setBudget(fresh.budget);
+      if (fresh.focus !== void 0) setFocus(fresh.focus);
       if (fresh.sidebar !== void 0) setSidebar(fresh.sidebar);
       if (cacheKey) writeCache(cacheKey, fresh);
       setRefreshing(false);
@@ -4890,6 +5050,7 @@ var App = ({
       displayedSections.current = cached.sections;
       setFetchedAt(cached.at);
       if (cached.sidebar) setSidebar(cached.sidebar);
+      if (cached.focus !== void 0) setFocus(cached.focus);
       setState({
         phase: "browse",
         sections: cached.sections,
@@ -4952,6 +5113,7 @@ var App = ({
           if (shared && shared.at > firedAt) {
             receive({ sections: shared.sections, login: shared.login });
             if (shared.sidebar) setSidebar(shared.sidebar);
+            if (shared.focus !== void 0) setFocus(shared.focus);
             setFetchedAt(shared.at);
             return;
           }
@@ -4972,6 +5134,7 @@ var App = ({
   );
   const [appliedSummary, setAppliedSummary] = useState("");
   const [sidebar, setSidebar] = useState(void 0);
+  const [focus, setFocus] = useState(void 0);
   const [skippedForBudget, setSkippedForBudget] = useState(false);
   const [mergedUrls, setMergedUrls] = useState([]);
   const [leavingUrls, setLeavingUrls] = useState([]);
@@ -5024,11 +5187,23 @@ var App = ({
               width: COLS
             }
           ) : null,
+          hasFocusSlot ? /* @__PURE__ */ jsx(
+            FocusSlotLine,
+            {
+              focus: void 0,
+              label: focusLabel,
+              empty: focusEmpty,
+              width: COLS
+            }
+          ) : null,
           /* @__PURE__ */ jsx(
             Box,
             {
               flexDirection: "column",
-              minHeight: Math.max(5, rows - 6 - (hasCiStatus ? 2 : 0)),
+              minHeight: Math.max(
+                5,
+                rows - 6 - (hasCiStatus ? 2 : 0) - (hasStrip ? 2 : 0) - (hasFocusSlot ? 2 : 0)
+              ),
               children: state.phase === "loading" ? /* @__PURE__ */ jsx(LoadingScreen, { label: `Fetching ${title}\u2026` }) : /* @__PURE__ */ jsx(
                 NoRowsScreen,
                 {
@@ -5136,6 +5311,9 @@ var App = ({
       ciJob,
       stripState: hasStrip ? stripState : void 0,
       stripLabel,
+      focus,
+      focusLabel,
+      focusEmpty,
       tabHelp,
       onOpenPr: (item) => {
         setChromeSpec({});
@@ -5184,4 +5362,4 @@ var matchesFilter = (repo, filter) => {
 };
 var parsePatterns = (value) => value.split(",").map((p) => p.trim()).filter(Boolean);
 
-export { ActionMenu, App, COLS, CiStatusLine, CommentsPanel, HealthPanel, LookupMiss, MIN_SIDEBAR_COLS, PrRow, SIDEBAR_COLS, SidePanel, StatusStripLine, ageLabel, budgetNotice, buildActions, buildCheckoutCmd, clipboard, counts, drillCmd, explainGhAction, explainItem, fitCount, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, isMenuGap, itermRun, jumpToRepo, jumpToRepoPane, matchesFilter, maxViewStart, menuRowsOf, menuTone, moveCursor, numberColumnsOf, openInTab, parsePatterns, railCapacity, railHeights, railRowsOf, railWidth, railsOf, readCache, renderMarkdown, reposInSections, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, sectionShedOf, signatureOf, stripGlyph, stripLayout, stripSignature, toCiStatusState, trailingColumnsOf, truncate, useActionMenu, useChrome, windowCount, withHeaders, withoutItem, workCount, writeCache };
+export { ActionMenu, App, COLS, CiStatusLine, CommentsPanel, DEFAULT_FOCUS_EMPTY, DEFAULT_FOCUS_LABEL, FOCUS_JUMP_KEY, FOCUS_MARK, FocusSlotLine, HealthPanel, LookupMiss, MIN_SIDEBAR_COLS, PrRow, SIDEBAR_COLS, SidePanel, StatusStripLine, ageLabel, budgetNotice, buildActions, buildCheckoutCmd, clipboard, counts, drillCmd, explainGhAction, explainItem, fitCount, focusCellFor, focusRefColor, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, isMenuGap, itermRun, jumpToRepo, jumpToRepoPane, matchesFilter, maxViewStart, menuRowsOf, menuTone, moveCursor, numberColumnsOf, openInTab, parsePatterns, railCapacity, railHeights, railRowsOf, railWidth, railsOf, readCache, renderMarkdown, reposInSections, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, sectionShedOf, signatureOf, stripGlyph, stripLayout, stripSignature, toCiStatusState, trailingColumnsOf, truncate, useActionMenu, useChrome, windowCount, withHeaders, withoutItem, workCount, writeCache };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kud/gh-ink",
-  "version": "0.74.0",
+  "version": "0.75.1",
   "description": "Ink components for rendering GitHub PR review comments and health — controlled, presentation-only, built on @kud/ink-ui and fed by @kud/gh.",
   "type": "module",
   "main": "dist/index.js",
@@ -44,17 +44,17 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@kud/ink-ui": ">=0.38.0 <1",
+    "@kud/ink-ui": ">=0.39.0 <1",
     "ink": ">=7",
     "react": ">=19"
   },
   "dependencies": {
     "@kud/gh": "0.21.0",
-    "@kud/gh-workflow": "0.16.0",
+    "@kud/gh-workflow": "0.17.0",
     "zx": "8.8.5"
   },
   "devDependencies": {
-    "@kud/ink-ui": "0.38.0",
+    "@kud/ink-ui": "0.39.0",
     "@types/node": "22.20.1",
     "@types/react": "19.2.17",
     "ink": "7.1.0",