@neosh/api 0.3.0 → 0.4.1

package/src/ui.ts

@@ -513,7 +513,11 @@ export async function picker<T>(
   items: PickerItem<T>[],
   opts: PickerOptions<T> = {},
 ): Promise<T | null> {
-  const height = Math.max(1, opts.height ?? 12);
+  // What the list would like. What it *gets* is settled by `measure` below, once the frontend has
+  // said how much of the screen there was — a picker asking for twelve rows on a sixteen-row
+  // terminal is not a twelve-row picker, and every number this widget computes from `rows` was
+  // wrong by the difference until it asked.
+  let rows = Math.max(1, opts.height ?? 12);
   const width = Math.max(20, opts.width ?? 64);
   const filtering = opts.filter !== false;
 
@@ -530,13 +534,13 @@ export async function picker<T>(
     anchor: opts.anchor ?? { kind: "screen" },
     offset: opts.offset,
     width: { kind: "fixed", n: width },
-    // Exactly the rows that get drawn: the list, plus a filter line when there is one, a title
-    // when there is one, and the key strip unless it was waived.
-    height: {
-      kind: "fixed",
-      n: height + (filtering ? 1 : 0) + (opts.title ? 1 : 0) + (hints === "" ? 0 : 1),
-    },
+    // Exactly the rows that get drawn: the list, plus a filter line when there is one and a title
+    // when there is one. The key strip is not among them any more — it is on the bottom border,
+    // where it costs no row and cannot be the row that does not fit. It was a row, and on a
+    // sixteen-row terminal it was reliably the one clipped: the strip that says how to get out.
+    height: { kind: "fixed", n: rows + (filtering ? 1 : 0) + (opts.title ? 1 : 0) },
     border: "rounded",
+    footer: hints === "" ? undefined : ` ${hints} `,
     focusable: true,
     closeOnBlur: true,
     // Modal: nothing global resolves while this is up. Shadowing the keys a widget wants — which
@@ -625,7 +629,7 @@ export async function picker<T>(
     if (closed) return;
     // Keep the cursor on screen without recentring on every keystroke.
     if (cursor < top) top = cursor;
-    if (cursor >= top + height) top = cursor - height + 1;
+    if (cursor >= top + rows) top = cursor - rows + 1;
 
     const lines: string[] = [];
     if (opts.title) lines.push(opts.title);
@@ -636,7 +640,7 @@ export async function picker<T>(
     // dock. Measuring against anything else puts the last visible character on both lines — the
     // continuation says `/ finds` under a row that already ended in `/`.
     const inner = Math.max(8, width);
-    let window = visible.slice(top, top + height);
+    let window = visible.slice(top, top + rows);
     // One gutter for the whole list, or none at all. Giving it only to the rows that asked for an
     // icon would step every other label one column left, which reads as a list that cannot decide
     // where its left margin is.
@@ -672,7 +676,7 @@ export async function picker<T>(
     // float's height: the window was sized for `height` lines and growing past it would push the
     // key strip off the bottom, which is the row that says how to get out.
     if (rest.length > 0) {
-      const room = Math.max(1, height - rest.length);
+      const room = Math.max(1, rows - rest.length);
       if (cursor < top) top = cursor;
       if (cursor >= top + room) top = cursor - room + 1;
       window = visible.slice(top, top + room);
@@ -691,23 +695,6 @@ export async function picker<T>(
       if (!isCursor) continue;
       for (const line of rest) lines.push(`    ${line}`);
     }
-    // Pushed onto the last row rather than floated: the float is sized for it, and a strip that
-    // moved up as the list shortened would be a strip you have to look for.
-    //
-    // The placeholder takes a row of the list's own space, so an empty list has used one of the
-    // `height` rows and not none. Counting it as none put the strip one row past the bottom of a
-    // float sized for exactly `height`, where it was silently clipped — leaving the empty state,
-    // the one state where you most want to be told what the keys do, as the only one with no keys
-    // on it.
-    // Lines, not rows: the row under the cursor is more than one of them when it has unfolded, and
-    // counting rows here would leave the strip that many lines low — off the bottom of a float
-    // sized for exactly `height`.
-    const listRows = Math.max(1, lines.length - firstListLine);
-    const hintLine = hints === "" ? -1 : lines.length + Math.max(0, height - listRows);
-    if (hintLine >= 0) {
-      while (lines.length < hintLine) lines.push("");
-      lines.push(` ${hints}`);
-    }
     // Marks are collected against their row and handed over with the text, in one call. Set one at
     // a time they were a sequence the frontend could draw the middle of: the moment the clear had
     // landed and the marks had not, every row drew unmarked — in `Normal`, which is near-white.
@@ -716,9 +703,6 @@ export async function picker<T>(
       drawn[line]?.marks!.push({ col, opts: o });
     };
 
-    if (hintLine >= 0) {
-      mark(hintLine, 0, { hlGroup: "Sidebar.Dim", endCol: byteLength(lines[hintLine] ?? "") });
-    }
     const listTop = (opts.title ? 1 : 0) + (filtering ? 1 : 0);
     for (let i = 0; i < window.length; i++) {
       const row = window[i]!;
@@ -869,10 +853,10 @@ export async function picker<T>(
           cursor = Math.max(0, cursor - 1);
           break;
         case "page_down":
-          cursor = Math.min(last(), cursor + height);
+          cursor = Math.min(last(), cursor + rows);
           break;
         case "page_up":
-          cursor = Math.max(0, cursor - height);
+          cursor = Math.max(0, cursor - rows);
           break;
         case "first":
           cursor = 0;
@@ -923,6 +907,33 @@ export async function picker<T>(
     }, { desc: "picker key" }),
   );
 
+  /**
+   * How many list rows there turned out to be room for.
+   *
+   * A float is *asked* for a height and given whatever the screen has, so `opts.height` is a wish
+   * and this is the answer. Everything above counts in `rows` — where the window starts, what a
+   * page step is, how far the cursor may go before the list scrolls — and while that number was the
+   * wish, a picker on a short terminal scrolled to keep the cursor on a row that was not drawn.
+   *
+   * Read once when the panel opens and again whenever the frontend says this window changed size,
+   * rather than on every keystroke: a round trip per character typed is latency on the one path in
+   * this widget that has to feel immediate.
+   */
+  async function measure(): Promise<void> {
+    if (closed) return;
+    const v = await neosh.win.viewport(win).catch(() => null);
+    if (!v) return;
+    const next = Math.max(1, v.height - (filtering ? 1 : 0) - (opts.title ? 1 : 0));
+    if (next === rows) return;
+    rows = next;
+    await render();
+  }
+  disposers.push(
+    neosh.event.on("neosh.viewport", (e) => {
+      if ((e as { win?: WindowId }).win === win) void measure();
+    }),
+  );
+
   await neosh.focus.push(win);
   disposers.push(await neosh.keymap.capture(win, command));
   // `<C-c>` is bound globally to `interrupt`, which would arm "press again to quit" while a picker
@@ -935,6 +946,7 @@ export async function picker<T>(
   if (typeof opts.query === "function") query = opts.query();
   await refetch();
   await render();
+  await measure();
   if (opts.onHighlight) {
     const row = visible[cursor];
     if (row) opts.onHighlight(row.item, row.index);
@@ -957,6 +969,145 @@ function dropSegment(text: string): string {
   return at < 0 ? "" : trimmed.slice(0, at + 1);
 }
 
+// ---------------------------------------------------------------------------
+// Reading something too long for the screen
+// ---------------------------------------------------------------------------
+
+export interface PagerOptions {
+  /** On the top border. */
+  title?: string;
+  /**
+   * On the bottom border, replacing the default legend.
+   *
+   * The default already names the scroll keys and the way out, read out of nothing — they are fixed
+   * defaults on `neosh.scroll` and `^Z` is where a rebinding shows up. Pass your own only to add a
+   * verb of your own to it.
+   */
+  footer?: string;
+  /** Columns of content. The border is drawn outside it. */
+  width?: number;
+  /**
+   * The most rows of content to ask for. Fewer if the content is shorter, fewer still if the screen
+   * is — which is the case this whole widget is about, and is why it is a ceiling and not a size.
+   */
+  height?: number;
+  /**
+   * The buffer kind, so a third party can bind keys in *this* panel and find it with `win.ofKind`.
+   *
+   * Defaults to {@link KIND_PAGER}, which every pager in the workspace shares. Pass your own when
+   * the panel is a thing in its own right — a diff, a status — and somebody might reasonably want
+   * keys on that and not on every pager there is.
+   */
+  kind?: string;
+  /** Marks to lay over the rows, in the same shape {@link Neosh.buf.render} takes. */
+  marks?: DrawnRow["marks"][];
+  z?: number;
+  /**
+   * Handed this panel's own close, as soon as it is on screen.
+   *
+   * For the caller that has to be able to put it away itself — a key that toggles, a panel that
+   * closes when the thing it is about goes. Without it the only way out is a key, and a `^Z` that
+   * opens a sheet and then opens a second one behind it is the bug this exists to prevent.
+   */
+  onOpen?: (close: () => Promise<void>) => void;
+}
+
+/** The kind a pager's buffer gets when the caller does not name one. */
+export const KIND_PAGER = "neosh.pager";
+
+/**
+ * Show rows you can read but not edit, in a float that scrolls when it does not fit.
+ *
+ * The shape almost every read-only panel in the workspace turned out to want, and the thing each of
+ * them was missing: a float is given whatever height the screen has, so a status of sixty changed
+ * files or a diff of four hundred lines was thirty rows on screen and the rest drawn nowhere, with
+ * no key pointed at it and nothing to say it was there. Every one of them had independently written
+ * "open a float, put lines in it" and independently stopped before the part where the terminal is
+ * short.
+ *
+ * What you get: the reader's motions (`j`/`k`, `^D`/`^U`, `^F`/`^B`, `gg`/`G`, arrows, paging keys)
+ * and the wheel, because the float sets `scroll` and those are ordinary bindings on
+ * `neosh.scroll` — so `^Z` lists them and `init.ts` moves them. A bar down the right border while
+ * anything is hidden. A legend on the bottom border, which cannot scroll away and is not the first
+ * row clipped. `<Esc>`, `q`, `<CR>` and `^C` close it.
+ *
+ * Resolves when it closes.
+ */
+export async function pager(
+  neosh: Neosh,
+  lines: string[],
+  opts: PagerOptions = {},
+): Promise<void> {
+  const buf = await neosh.buf.create({
+    name: `[${opts.title?.trim() || "pager"}]`,
+    scratch: true,
+    kind: opts.kind ?? KIND_PAGER,
+  });
+  const ns = await neosh.ns.create("neosh.ui.pager");
+  await neosh.buf.render(
+    buf,
+    ns,
+    0,
+    -1,
+    lines.map((text, i) => ({ text, marks: opts.marks?.[i] ?? [] })),
+  );
+
+  const win = await neosh.float.open(buf, {
+    anchor: { kind: "screen" },
+    width: opts.width === undefined ? { kind: "auto" } : { kind: "fixed", n: opts.width },
+    // A ceiling, never a size. `fixed` here would ask for rows the screen does not have and get
+    // clipped to them anyway — the difference being that `max` also shrinks to fit content that is
+    // shorter, so a two-line status is a two-line panel rather than a mostly empty box.
+    height: { kind: "max", n: opts.height ?? 30 },
+    border: "rounded",
+    title: opts.title,
+    footer: opts.footer ?? " j k move   ^D ^U half   gg G ends   esc close ",
+    focusable: true,
+    closeOnBlur: true,
+    scroll: true,
+    z: opts.z ?? 200,
+  });
+  await neosh.focus.push(win);
+
+  let settle: () => void = () => {};
+  const done = new Promise<void>((resolve) => {
+    settle = resolve;
+  });
+
+  const command = `neosh.ui.pager.key.${++pickerSeq}`;
+  const disposers: Disposable[] = [];
+  let closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    for (const d of disposers) d.dispose();
+    await neosh.focus.pop().catch(() => {});
+    await neosh.win.close(win).catch(() => {});
+    settle();
+  };
+
+  disposers.push(
+    await neosh.cmd.register(command, (_args, key) => {
+      // Only what nothing else claimed reaches here, and the scroll keys are claimed — they resolve
+      // at `neosh.scroll`, which is nearer than this capture is late. So what is left is dismissal.
+      // Which is *named*: a panel you scroll is a panel you spend time in, and "any key closes it"
+      // turns a mistyped letter into losing your place.
+      if (!key || closesPager(key)) void close();
+    }, { desc: "close this panel" }),
+  );
+  disposers.push(await neosh.keymap.capture(win, command));
+  opts.onOpen?.(close);
+  return done;
+}
+
+/** `<Esc>`, `q`, `<CR>` and `^C` — the four keys every panel in this workspace closes on. */
+function closesPager(key: KeyContext): boolean {
+  const { code, mods } = key.key;
+  if (code.kind === "esc" || code.kind === "enter") return true;
+  if (code.kind !== "char") return false;
+  return mods.ctrl ? code.c.toLowerCase() === "c" : code.c.toLowerCase() === "q";
+}
+
 // ---------------------------------------------------------------------------
 // Derived widgets
 // ---------------------------------------------------------------------------
@@ -1013,6 +1164,18 @@ export async function confirm(
     `y ${yes.toLowerCase()}   n ${no.toLowerCase()}   ↵ choose   esc cancel`,
     width - 2,
   );
+  /**
+   * How many of the detail lines there is room for.
+   *
+   * Settled once the frontend has said how tall this dialog turned out to be — a dialog is asked
+   * for a height and given what the screen has, and the rows it loses are the ones at the bottom.
+   * Which for a question with the answers under the detail meant the answers, so a long `detail` on
+   * a short terminal was a dialog you could not see either option in.
+   *
+   * The detail is what gives way, because the detail is the part you can do without: the question
+   * and the two answers are the dialog. What went is said rather than silently dropped.
+   */
+  let room = detail.length;
 
   // On the answer that changes nothing, when the other one cannot be taken back.
   let cursor = opts.dangerous ? 1 : 0;
@@ -1025,14 +1188,17 @@ export async function confirm(
 
   /** Where each part of the dialog starts, so the marks do not have to count rows twice. */
   const detailAt = asked.length + 1;
-  const answersAt = detailAt + (detail.length === 0 ? 0 : detail.length + 1);
-  const stripAt = answersAt + answers.length + 1;
+  /** Every row but the detail: the question, the blanks around it, and the two answers. */
+  const fixedRows = asked.length + 1 + answers.length;
 
   const win = await neosh.float.open(buf, {
     anchor: { kind: "screen" },
     width: { kind: "fixed", n: width },
-    height: { kind: "fixed", n: stripAt + 1 },
+    height: { kind: "fixed", n: fixedRows + (detail.length === 0 ? 0 : detail.length + 1) },
     border: "rounded",
+    // The key strip, on the edge. It was the last row of the buffer, which made it both the row a
+    // long `detail` pushed off the bottom and a row of height every dialog had to pay for.
+    footer: ` ${strip} `,
     focusable: true,
     closeOnBlur: true,
     // Modal: nothing global resolves while this is up. Shadowing the keys a widget wants — which
@@ -1048,15 +1214,20 @@ export async function confirm(
   });
 
   const render = async () => {
+    const shownDetail = room >= detail.length
+      ? detail
+      : // One row of the budget goes to saying what is not being shown, so a dialog that has had to
+        // cut something never looks like a dialog that had nothing more to say.
+        [...detail.slice(0, Math.max(0, room - 1)), `… and ${detail.length - Math.max(0, room - 1)} more lines`];
+    const detailRows = shownDetail.length;
+    const answersAt = detailAt + (detailRows === 0 ? 0 : detailRows + 1);
     const lines: string[] = asked.map((l) => ` ${l}`);
     lines.push("");
-    if (detail.length > 0) {
-      lines.push(...detail.map((l) => ` ${l}`));
+    if (detailRows > 0) {
+      lines.push(...shownDetail.map((l) => ` ${l}`));
       lines.push("");
     }
     answers.forEach((a, i) => lines.push(`${i === cursor ? `${CURSOR_MARKER}` : BLANK_MARKER}${a}`));
-    lines.push("");
-    lines.push(` ${strip}`);
     // Text and marks together, in one call: this is redrawn on every keystroke, and a repaint the
     // frontend can draw the middle of is one that flashes — unmarked rows draw in `Normal`. It also
     // takes care of the older half of the same bug, that a mark whose line was replaced under it
@@ -1069,7 +1240,7 @@ export async function confirm(
     for (let i = 0; i < asked.length; i++) {
       mark(i, 0, { hlGroup: "Title", endCol: byteLength(lines[i] ?? "") });
     }
-    for (let i = 0; i < detail.length; i++) {
+    for (let i = 0; i < detailRows; i++) {
       mark(detailAt + i, 0, {
         hlGroup: "Comment",
         endCol: byteLength(lines[detailAt + i] ?? ""),
@@ -1090,7 +1261,6 @@ export async function confirm(
         });
       }
     }
-    mark(stripAt, 0, { hlGroup: "Sidebar.Dim", endCol: byteLength(lines[stripAt] ?? "") });
     await neosh.buf.render(buf, ns, 0, -1, drawn);
     // The caret marks the answer, since there is nothing here to type into.
     await neosh.win.setCursor(win, answersAt + cursor, 0);
@@ -1161,6 +1331,23 @@ export async function confirm(
   disposers.push(await neosh.keymap.capture(win, command));
   await bindWidgetKeys(neosh, win, command, keys);
   await render();
+  // And then how much of it there was room for. Asked after the first draw, because a window the
+  // frontend has never laid out has no answer to give.
+  const measure = async () => {
+    if (closed) return;
+    const v = await neosh.win.viewport(win).catch(() => null);
+    if (!v) return;
+    const next = Math.max(0, v.height - fixedRows - 1);
+    if (next === room) return;
+    room = next;
+    await render();
+  };
+  disposers.push(
+    neosh.event.on("neosh.viewport", (e) => {
+      if ((e as { win?: WindowId }).win === win) void measure();
+    }),
+  );
+  await measure();
   return done;
 }
 
@@ -1352,6 +1539,10 @@ export async function pathPicker(
   title: string,
   opts: { initial?: string; width?: number; height?: number } = {},
 ): Promise<string | null> {
+  // The last refusal said out loud, so a folder the OS is hiding is reported once rather than on
+  // every keystroke into it. `source` runs per character typed, and a notice per character is the
+  // same message forty times for one cause.
+  let saidDenied: string | null = null;
   return picker<string>(neosh, [], {
     title,
     width: Math.max(40, opts.width ?? 72),
@@ -1359,8 +1550,19 @@ export async function pathPicker(
     query: opts.initial ?? "",
     placeholder: "no directory matches — <CR> takes what you typed",
     source: async (query) => {
-      const paths = await neosh.path.complete(query).catch(() => []);
-      return paths.map((path) => ({ label: path, value: path }));
+      const answer = await neosh.path
+        .complete(query)
+        .catch(() => ({ paths: [] as string[], denied: undefined }));
+      // An empty list because nobody was allowed to look is not an empty directory, and the
+      // placeholder under this field can only say the second one. Said the way the remote branch
+      // of the same question says it — a notice, because it is feedback for a key you pressed.
+      if (answer.denied && answer.denied !== saidDenied) {
+        saidDenied = answer.denied;
+        neosh.notify(answer.denied, "warn");
+      } else if (!answer.denied) {
+        saidDenied = null;
+      }
+      return answer.paths.map((path) => ({ label: path, value: path }));
     },
     // What you typed, when it is not one of the offered rows. A completion list that refuses a path
     // it did not think of is a list that gets in the way.
@@ -1386,6 +1588,9 @@ export async function prompt(
     width: { kind: "fixed", n: width },
     height: { kind: "fixed", n: 2 },
     border: "rounded",
+    // A field with no legend on it is a field you guess at. On the border, so it costs neither of
+    // the two rows this has.
+    footer: " ↵ accept   ^W a word   ^U all   esc cancel ",
     focusable: true,
     closeOnBlur: true,
     // Modal: nothing global resolves while this is up. Shadowing the keys a widget wants — which
@@ -2209,9 +2414,11 @@ export async function railPicker<G, T>(
   const win = await neosh.float.open(buf, {
     anchor: { kind: "screen" },
     width: { kind: "fixed", n: total },
-    // title, filter, rule, body, rule, hints
-    height: { kind: "fixed", n: height + 5 },
+    // title, filter, rule, body, rule. The key strip is not among them: it is on the bottom border,
+    // where it costs no row of body and cannot be the row a short terminal clips.
+    height: { kind: "fixed", n: height + 4 },
     border: "rounded",
+    footer: ` ${opts.hints ?? "↵ use   ⇥ panes   ^N/^P move   esc close"} `,
     focusable: true,
     closeOnBlur: true,
     // Modal: nothing global resolves while this is up. Shadowing the keys a widget wants — which
@@ -2321,8 +2528,21 @@ export async function railPicker<G, T>(
     all = got;
     rebuild();
     cursor = Math.max(0, Math.min(opts.itemAt?.(all) ?? 0, Math.max(0, rows.length - 1)));
-    // Land on something selectable rather than on a section header.
-    if (rows[cursor]?.kind !== "item") cursor = rows.findIndex((r) => r.kind === "item");
+    // Land on something you can actually press `↵` on: not a section header, and not a row the
+    // caller disabled. `movePane` has always stepped over disabled rows, so the only way to be
+    // standing on one was to open here — and the first row of a list is where a picker opens by
+    // default. A pane whose top row is "this needs a newer CLI" then greeted every `↵` with
+    // nothing happening, which reads as the picker being broken rather than the row being refused.
+    const landable = (at: number) => {
+      const row = rows[at];
+      return row?.kind === "item" && !row.item.disabled;
+    };
+    if (!landable(cursor)) {
+      const next = rows.findIndex((_, at) => landable(at));
+      // Every row refused is still a list worth opening — you came to read why. Falling back to
+      // the first item rather than to nothing keeps the detail line of *something* on screen.
+      cursor = next >= 0 ? next : rows.findIndex((r) => r.kind === "item");
+    }
     if (cursor < 0) cursor = 0;
     paneTop = 0;
   };
@@ -2400,7 +2620,11 @@ export async function railPicker<G, T>(
       ? takeWords(detail, Math.max(0, room))
       : [clipToWidth(detail, Math.max(0, room)), ""];
     const label = padToWidth(labelHead, labelWidth);
-    const badgeCell = badgeWidth === 0 ? "" : padToWidth(clipToWidth(badge, badgeWidth), badgeWidth);
+    // One column narrower than the cell it sits in, so there is always a space before the detail.
+    // Clipped to the full width, a badge that happens to fill it runs straight into the sentence
+    // after it and the two read as one word.
+    const badgeCell =
+      badgeWidth === 0 ? "" : padToWidth(clipToWidth(badge, badgeWidth - 1), badgeWidth);
     const text = `${head}${label}${badgeCell}${detailHead}`;
 
     const labelAt = byteLength(head);
@@ -2528,12 +2752,6 @@ export async function railPicker<G, T>(
       line: lines.length - 1,
       mark: { from: 0, to: byteLength(lines[lines.length - 1]!), hl: "Separator" },
     });
-    const hints = opts.hints ?? "↵ use   ⇥ panes   ^N/^P move   esc close";
-    lines.push(` ${hints}`);
-    marks.push({
-      line: lines.length - 1,
-      mark: { from: 0, to: byteLength(lines[lines.length - 1]!), hl: "Sidebar.Dim" },
-    });
 
     // The marks were already collected against their rows; they now travel with them. One call
     // rather than one per mark, so there is no frame in which the text has arrived and the colour
@@ -2751,16 +2969,47 @@ export interface ActionItem {
   /** For the hint strip and `^Z`. */
   label: string;
   command: string;
-  /** Which rows it applies to — a row kind the panel names, `custom` for contributed rows, or `any`. */
+  /**
+   * Which rows it applies to — a row kind the panel names, `custom` for contributed rows, or `any`.
+   *
+   * `custom:<section id>` narrows it to the rows of **one** section: `custom:git` is a verb about
+   * the git block and nothing else. Bare `custom` means every contributed row in the panel, which
+   * is right for a verb about contributions in general and wrong for the usual case — two plugins
+   * each with a block in the column and each wanting `<Tab>` on their own rows were, without this,
+   * one key that one of them won and the other silently lost. A panel binds the key once and sends
+   * it to whichever action matches the row the cursor is actually on.
+   */
   on?: string;
 }
 
+/** One coloured run of a badge. A part with no `hl` is the panel's own colour — a separator. */
+export interface BadgePart {
+  text: string;
+  hl?: string;
+}
+
+/**
+ * A mark after a row's name: one coloured run, or several.
+ *
+ * Several, because a badge is often several facts rather than one — `↓2` is not the same news as
+ * `~7`, and a strip of git stats drawn in one colour is a string you have to read rather than a
+ * row you can glance at. The single form stays because most badges *are* one fact.
+ *
+ * `short` is the same badge with less in it, for a row too narrow to carry all of it — the fewest
+ * parts still worth drawing, not a truncation. A panel is what knows how many columns there are;
+ * which fact to give up is the badge's to say, exactly as it is for a status segment. Absent means
+ * there is no shorter true version, and the full badge stands.
+ */
+export type BadgeSpec =
+  | { text: string; hl?: string }
+  | { parts: BadgePart[]; short?: BadgePart[] };
+
 /** A mark on a row a panel already draws, keyed by what the row is about. */
 export interface DecorationItem {
   /** The row it is about, in the panel's own terms: `{ project: cwd }`, `{ task: id }`. */
   target: Record<string, string>;
-  /** A short mark after the name, in `hl`. The name is clipped to make room. */
-  badge?: { text: string; hl?: string };
+  /** A short mark after the name. The name is clipped to make room. */
+  badge?: BadgeSpec;
   /** The row's highlight, when the panel has no opinion of its own. */
   hl?: string;
   /** The right-hand column, on a row that is not busy. */
@@ -2769,11 +3018,43 @@ export interface DecorationItem {
 
 /** Every decoration on one target, merged. */
 export interface Decoration {
-  badge?: { text: string; hl?: string };
+  /** `text` is every part run together — what a caller measuring the badge reads. */
+  badge?: { text: string; hl?: string; parts: BadgePart[]; short: BadgePart[] };
   hl?: string;
   right?: { text: string; hl?: string };
 }
 
+/** A badge in either form, as the run of parts the rest of this file works in. */
+function badgeParts(badge: BadgeSpec | undefined): BadgePart[] {
+  if (!badge || typeof badge !== "object") return [];
+  const many = (badge as { parts?: unknown }).parts;
+  if (Array.isArray(many)) {
+    return many.filter((p): p is BadgePart =>
+      Boolean(p) && typeof p === "object" && typeof (p as BadgePart).text === "string" &&
+      (p as BadgePart).text !== ""
+    );
+  }
+  const one = badge as { text?: unknown; hl?: unknown };
+  if (typeof one.text !== "string" || one.text === "") return [];
+  return [{ text: one.text, hl: typeof one.hl === "string" ? one.hl : undefined }];
+}
+
+/**
+ * A badge's short form, falling back to the whole of it.
+ *
+ * The fallback is what lets several decorations merge without anybody declaring one: a plugin with
+ * nothing to give up keeps all of its parts in both forms, and {@link fitBadge} notices that the
+ * two are the same width and leaves the badge alone.
+ */
+function badgeShort(badge: BadgeSpec | undefined): BadgePart[] {
+  const declared = (badge as { short?: unknown } | undefined)?.short;
+  if (!Array.isArray(declared)) return badgeParts(badge);
+  return declared.filter((p): p is BadgePart =>
+    Boolean(p) && typeof p === "object" && typeof (p as BadgePart).text === "string" &&
+    (p as BadgePart).text !== ""
+  );
+}
+
 /** The key a decoration's `target` files under: `project:/w/x`, `task:17`. */
 export function decorationKey(target: unknown): string | null {
   if (!target || typeof target !== "object") return null;
@@ -2797,11 +3078,16 @@ export function mergeDecorations(
     const key = decorationKey(c.item?.target);
     if (key === null) continue;
     const d = out.get(key) ?? {};
-    const badge = c.item.badge;
-    if (typeof badge?.text === "string" && badge.text !== "") {
-      d.badge = d.badge
-        ? { text: `${d.badge.text} ${badge.text}`, hl: d.badge.hl }
-        : { text: badge.text, hl: badge.hl };
+    const parts = badgeParts(c.item.badge);
+    if (parts.length > 0) {
+      const short = badgeShort(c.item.badge);
+      const merged = d.badge ? [...d.badge.parts, { text: " " }, ...parts] : parts;
+      d.badge = {
+        text: merged.map((p) => p.text).join(""),
+        hl: d.badge?.hl ?? parts[0]?.hl,
+        parts: merged,
+        short: d.badge ? [...d.badge.short, { text: " " }, ...short] : short,
+      };
     }
     if (d.hl === undefined && typeof c.item.hl === "string") d.hl = c.item.hl;
     if (d.right === undefined && typeof c.item.right?.text === "string") {
@@ -2812,9 +3098,41 @@ export function mergeDecorations(
   return out;
 }
 
-/** How many columns a decoration's badge will take, for a row builder to leave free. */
+/**
+ * How many columns a decoration's badge will take, for a row builder to leave free.
+ *
+ * Columns rather than bytes, which is what a row builder is subtracting this from: `●3` is four
+ * bytes and two columns, and a strip of arrows is three bytes each — measured in bytes, a badge
+ * that says `↓2 ↑5 ~7` takes eleven columns off a name to occupy nine.
+ */
 export function badgeWidth(d: Decoration | undefined): number {
-  return d?.badge ? byteLength(` ${d.badge.text}`) : 0;
+  return d?.badge ? width(` ${d.badge.text}`) : 0;
+}
+
+/**
+ * The badge as this row can actually afford it: the whole of it, or its short form.
+ *
+ * **The badge yields before the name does.** A row's name is what the row *is* — a project you
+ * cannot read the name of is not a row you can use — and a badge is news about it. So the full
+ * strip is drawn whenever the name fits beside it, and a name that would be clipped by the badge
+ * gets the short form instead. Only if it still does not fit is the name clipped, which is the
+ * panel's own business and unchanged.
+ *
+ * `room` is every column the name and the badge have between them, `name` the columns the name
+ * wants. A badge whose short form saves nothing is left alone, which is what makes the fallback in
+ * {@link badgeShort} safe: a plugin that declared no short form never has one chosen for it.
+ */
+export function fitBadge(
+  d: Decoration | undefined,
+  room: number,
+  name: number,
+): Decoration | undefined {
+  if (!d?.badge) return d;
+  const full = badgeWidth(d);
+  if (name + full <= room) return d;
+  const short = { ...d.badge, text: d.badge.short.map((p) => p.text).join("") };
+  if (width(` ${short.text}`) >= full) return d;
+  return { ...d, badge: { ...short, parts: d.badge.short } };
 }
 
 /**
@@ -2833,12 +3151,18 @@ export function decorateRow<T>(
   if (!d) return row;
   if (d.badge) {
     const mark = ` ${d.badge.text}`;
-    const from = byteLength(row.text);
+    // Past the space this puts between the name and the badge: it is the panel's colour, not the
+    // badge's, and a span over it would be one colour claiming a column it does not fill.
+    let at = byteLength(row.text) + 1;
     row.text = `${row.text}${mark}`;
     if (row.full !== undefined) row.full = `${row.full}${mark}`;
-    if (d.badge.hl) {
-      row.spans = [...(row.spans ?? []), { from, to: from + byteLength(mark), hl: d.badge.hl }];
+    const spans = [...(row.spans ?? [])];
+    for (const part of d.badge.parts) {
+      const to = at + byteLength(part.text);
+      if (part.hl) spans.push({ from: at, to, hl: part.hl });
+      at = to;
     }
+    if (spans.length > 0) row.spans = spans;
   }
   if (d.hl && row.hl === undefined) row.hl = d.hl;
   if (d.right && !busy) row.right = { text: `${d.right.text} `, hl: d.right.hl };
@@ -2900,7 +3224,16 @@ export function placeSections<S extends string>(
  */
 export function sectionRows<T>(
   c: Contribution & { item: SectionItem },
-  opts: { width: number; custom: (command: string, args: string[]) => T },
+  opts: {
+    width: number;
+    /**
+     * What a landable contributed row *is*, in the panel's own vocabulary.
+     *
+     * The section's id comes third so a panel can tell one contributor's rows from another's —
+     * which is what {@link ActionItem.on}'s `custom:<id>` form is matched against.
+     */
+    custom: (command: string, args: string[], section: string) => T;
+  },
 ): ListRow<T>[] {
   const rows: ListRow<T>[] = [];
   const contributed = Array.isArray(c.item?.rows) ? c.item.rows : [];
@@ -2940,7 +3273,7 @@ export function sectionRows<T>(
       spans: spans.length > 0 ? spans : undefined,
       right: typeof r.right?.text === "string" ? { text: `${r.right.text} `, hl: r.right.hl } : undefined,
       inert: typeof r.command !== "string",
-      value: typeof r.command === "string" ? opts.custom(r.command, args) : undefined,
+      value: typeof r.command === "string" ? opts.custom(r.command, args, c.id) : undefined,
     });
   }
   return rows;