@bongos/core 1.17.2 → 1.17.3

package/modules/hall-ui/public/goal-inbox.js

@@ -1,6 +1,13 @@
-// goal-inbox.js — the home-page, two-sided goal-membership inbox (task 1954, ADR 0112).
+// goal-inbox.js — the Home "Needs your attention" card (task 2169), grown from
+// the two-sided goal-membership inbox (task 1954, ADR 0112).
 //
-// Surfaces the actionable slice of a builder's private-goals queue in ONE place:
+// This card is the SINGLE landing place for actionable items on Home: it owns
+// the section (id 'attention-scroll'), renders the goal-membership slice
+// itself, and hosts the idea-triage slice (#attention-ideas, rendered by
+// builders.js). New actionable item classes join as line-item slices here —
+// never as new Home cards (the anti-accretion rule).
+//
+// The goal slice surfaces a builder's private-goals queue:
 //   • "Invitations to you" — pending invites addressed to me (Accept / Decline).
 //   • "Requests to approve" — pending join-requests on goals I own or manage
 //                             (Approve / Deny).
@@ -81,32 +88,41 @@
     return `<p class="ginbox__pending card-foot">Your pending join ${noun}: ${links} — awaiting approval.</p>`;
   }
 
+  // task 2169: this render fills ONLY the goals slice (#attention-goals) — the
+  // ideas slice (#attention-ideas) belongs to builders.js's triage renderer.
+  // Card visibility + the headline count derive from BOTH via OTBAttention.
+  const MAX_GOAL_ROWS = 5;
   function render(inbox) {
+    const box = host && host.querySelector('#attention-goals');
+    if (!box) return;
     const invitations = inbox.invitations || [];
     const joinRequests = inbox.joinRequests || [];
     const myPending = inbox.myPendingRequests || [];
-    // Hide the whole card when there is nothing to see OR act on.
     if (!invitations.length && !joinRequests.length && !myPending.length) {
-      host.hidden = true;
-      host.innerHTML = '';
+      box.innerHTML = '';
+      window.OTBAttention.refresh();
       return;
     }
-    const actionable = invitations.length + joinRequests.length;
-    let html = `<h2 id="goal-inbox-h" class="scroll__h">Goal inbox${actionable ? `<span class="count-pill">${actionable}</span>` : ''}</h2>`;
-    if (actionable) {
-      html += '<p class="scroll__lede">Invitations and join-requests waiting on you.</p>';
+    // Cap the card at a handful of rows — it is a summary, not the queue.
+    let budget = MAX_GOAL_ROWS;
+    const inv = invitations.slice(0, budget); budget -= inv.length;
+    const reqs = joinRequests.slice(0, Math.max(0, budget));
+    const overflow = (invitations.length - inv.length) + (joinRequests.length - reqs.length);
+    let html = '';
+    if (inv.length) {
+      html += '<h3 class="ginbox__sec-h">Goal invitations to you</h3>';
+      html += `<ul class="ginbox">${inv.map(invitationRow).join('')}</ul>`;
     }
-    if (invitations.length) {
-      html += '<h3 class="ginbox__sec-h">Invitations to you</h3>';
-      html += `<ul class="ginbox">${invitations.map(invitationRow).join('')}</ul>`;
+    if (reqs.length) {
+      html += '<h3 class="ginbox__sec-h">Join-requests to approve</h3>';
+      html += `<ul class="ginbox">${reqs.map(requestRow).join('')}</ul>`;
     }
-    if (joinRequests.length) {
-      html += '<h3 class="ginbox__sec-h">Requests to approve</h3>';
-      html += `<ul class="ginbox">${joinRequests.map(requestRow).join('')}</ul>`;
+    if (overflow > 0) {
+      html += `<p class="ginbox__pending">…and ${overflow} more waiting — <a href="/goals">open your goals</a>.</p>`;
     }
     html += pendingLine(myPending);
-    host.innerHTML = html;
-    host.hidden = false;
+    box.innerHTML = html;
+    window.OTBAttention.refresh();
   }
 
   async function load() {
@@ -115,9 +131,11 @@
       const inbox = await getJSON(`${API}/goals/inbox`);
       render(inbox);
     } catch (err) {
-      // Signed out (401) or an older server without the route (404) → render nothing.
-      host.hidden = true;
-      host.innerHTML = '';
+      // Signed out (401) or an older server without the route (404) → render
+      // nothing in the goals slice; the ideas slice may still have content.
+      const box = host.querySelector('#attention-goals');
+      if (box) box.innerHTML = '';
+      window.OTBAttention.refresh();
       if (err.code !== 'auth-needed' && err.code !== 'not-found') {
         console.error('[hall] goal inbox load failed', err);
       }
@@ -174,18 +192,41 @@
     }
   }
 
+  // task 2169: this widget IS the "Needs your attention" card — ONE capped
+  // summary hosting every actionable item class: goal invitations +
+  // join-requests (this file) and ideas awaiting triage (builders.js renders
+  // into #attention-ideas). Future actionable item classes add a slice div
+  // here + call OTBAttention.refresh() — never a new Home card.
   function mount(hostEl) {
     host = hostEl;
-    host.hidden = true; // stays hidden until load() finds something actionable
+    host.hidden = true; // stays hidden until a slice finds something actionable
+    host.innerHTML =
+      '<h2 id="attention-h" class="scroll__h">Needs your attention<span class="count-pill" id="attention-count" hidden></span></h2>' +
+      '<div id="attention-goals"></div>' +
+      '<div id="attention-ideas"></div>';
     host.addEventListener('click', onClick);
     load();
   }
 
-  // order 24 → sits at the top of the Home main zone (just above the idea-triage
-  // inbox), since it is personal + actionable. hiddenByDefault so an empty inbox
-  // costs nothing until load() un-hides it.
+  // The card's shared visibility contract: any slice renderer calls refresh()
+  // after painting; the card shows iff any slice has actionable rows, and the
+  // headline pill is the cross-slice total.
+  window.OTBAttention = {
+    refresh() {
+      const sec = document.getElementById('attention-scroll');
+      if (!sec) return;
+      const n = sec.querySelectorAll('.ginbox__item, .triage-inbox__item').length;
+      const pending = sec.querySelector('.ginbox__pending');
+      const pill = document.getElementById('attention-count');
+      if (pill) { pill.hidden = !n; pill.textContent = String(n); }
+      sec.hidden = n === 0 && !pending;
+    },
+  };
+
+  // order 20 → the top of the Home main zone: personal + actionable beats
+  // informational. hiddenByDefault so a quiet inbox costs nothing.
   window.OTB.contributeHallWidget({
-    id: 'goal-inbox-scroll', label: 'Goal inbox', order: 24, mount,
-    labelledby: 'goal-inbox-h', view: 'home', zone: 'home-main', hiddenByDefault: true,
+    id: 'attention-scroll', label: 'Needs your attention', order: 20, mount,
+    labelledby: 'attention-h', view: 'home', zone: 'home-main', hiddenByDefault: true,
   });
 })();

package/modules/hall-ui/public/goals-page.js

@@ -280,6 +280,7 @@
           <span class="goal-card__title">${escapeHtml(g.title || 'Untitled goal')}</span>
         </div>
         <div class="goal-card__meta">
+          <span class="goal-card__id" title="Goal id — use this to reference the goal (e.g. 'goal ${escapeHtml(String(g.id))}'). Distinct from the priority position on the left.">#${escapeHtml(String(g.id))}</span>
           <span>${escapeHtml(g.version_id || '')}</span>
           ${statusBadge(g.status)}
           ${blockedPill}
@@ -857,7 +858,9 @@
     const iAmLead = members.some((m) => sameId(m.builder_id, selfId()) && m.role === 'lead');
 
     const h = $('#goal-detail-h');
-    if (h) h.textContent = g.title || 'Untitled goal';
+    // task 2163 — surface the numeric goal id alongside the title (escaped title,
+    // so switching from textContent to innerHTML stays injection-safe).
+    if (h) h.innerHTML = `<span class="goal-detail__id" title="Goal id">#${escapeHtml(String(g.id))}</span> ${escapeHtml(g.title || 'Untitled goal')}`;
     const desc = $('#goal-detail-desc');
     if (desc) desc.textContent = g.description || '';
     const meta = $('#goal-detail-meta');

package/modules/hall-ui/public/goals.html

@@ -38,6 +38,14 @@
     .goal-deps--blocked { color: var(--warn); font-weight: 600; }
     .goal-card__title { font-weight: 650; font-size: 14px; flex: 1; min-width: 0; }
     .goal-card__meta { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; font-size: 12px; color: var(--ink-faint); }
+    /* task 2163 — the real goal id, shown as a monospace #NNN token so it reads as
+       an identifier and never gets confused with the priority ordinal on the left. */
+    .goal-card__id, .goal-detail__id {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-variant-numeric: tabular-nums; font-weight: 600; color: var(--ink-faint);
+    }
+    .goal-card__id { padding: 0 5px; border: 1px solid var(--rule-soft); border-radius: 5px; }
+    .goal-detail__id { font-size: 0.72em; vertical-align: 0.12em; margin-right: 4px; }
     .goal-card__foot { display: flex; gap: 14px; font-size: 12.5px; color: var(--ink-soft); }
     .goal-card__foot strong { font-variant-numeric: tabular-nums; }
 

package/modules/hall-ui/public/hall-kit.js

@@ -0,0 +1,474 @@
+// modules/hall-ui/public/hall-kit.js — the hall's shared UI component kit
+// (task 2166, the hall UX-coherence program's foundation).
+//
+// One dependency-free IIFE exposing `window.OTBKit`: the SIX primitives every
+// page redesign (tasks 2169–2176) adopts instead of re-implementing — pager,
+// ledger, filter bar, tabs, section rail, empty/skeleton/collapsible. Before
+// this file, the ledger+pager block existed in ~10 drifted copies across
+// work.js / goals-page.js / builders.js; the section rail existed twice with
+// different mechanics (Standing scrollspy vs Settings panel-switch).
+//
+// Contract:
+// - Dependency-free like shell.js (own esc(), no window.OTB use) so load order
+//   only needs "before the page script". Node-require-safe: no eval-time DOM.
+// - String-template + innerHTML factories returning { el, render(data) } — the
+//   exact idiom the pages already use. No state manager, no render loop.
+// - Pager markup/ids and localStorage keys are caller-supplied so existing
+//   per-page prefs (otb.work.*PerPage, …) survive migration verbatim.
+// - Tabs/rails toggle [hidden] — the window stays the hall's ONLY scroller.
+// - The kit NEVER touches location hashes in the deep-link namespace ("#/…"
+//   — task/idea/blocker overlays, goal sub-routes). Guarded in makeTabs.
+// - CSS lives in style.css §"hall-kit components" (same task); the kit reuses
+//   .ledger/.pager/.filters/.setup__tab/.rail-link classes that already exist.
+(() => {
+  'use strict';
+
+  // HTML-escape for text interpolated into innerHTML.
+  function esc(s) {
+    return String(s ?? '').replace(/[&<>"']/g, (c) => ({
+      '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    }[c]));
+  }
+  const $id = (id) => document.getElementById(id);
+
+  // ---- pager ----------------------------------------------------------------
+  // Canonized from work.js (task 1931/1955): page + per-page persisted per list,
+  // clamping against shrunken lists, poll-safe page retention, bar hidden when
+  // the list fits one minimum page.
+
+  const PAGER_DEFAULTS = { perPageOptions: [10, 25, 50, 100], defaultPerPage: 25 };
+
+  function loadPerPage(key, options, fallback) {
+    try {
+      const v = Number(window.localStorage.getItem(key));
+      return options.includes(v) ? v : fallback;
+    } catch (_) { return fallback; }
+  }
+
+  // makePager(prefix, storageKey, opts?) → pager state. `prefix` names the DOM
+  // ids the bar paints (#<prefix>-{pager,range,page,prev,next,per-page});
+  // `storageKey` is the caller's localStorage key (kept stable across
+  // migrations so builders' per-page prefs survive).
+  function makePager(prefix, storageKey, opts = {}) {
+    const perPageOptions = opts.perPageOptions || PAGER_DEFAULTS.perPageOptions;
+    const defaultPerPage = opts.defaultPerPage || PAGER_DEFAULTS.defaultPerPage;
+    return {
+      prefix,
+      key: storageKey,
+      page: 1,
+      perPage: loadPerPage(storageKey, perPageOptions, defaultPerPage),
+      perPageOptions,
+      // ≤ this fits one page — hide the bar entirely.
+      minPerPage: opts.minPerPage ?? perPageOptions[0],
+    };
+  }
+
+  // The standard pager-bar markup. Pages stop hand-copying this block; the ids
+  // match what renderPagerBar/wirePager address.
+  function pagerBarHtml(prefix, { label = 'items' } = {}) {
+    const p = esc(prefix);
+    const l = esc(label);
+    return `
+      <div class="pager pager--paged" id="${p}-pager" hidden>
+        <span class="pager__range" id="${p}-range"></span>
+        <div class="pager__nav">
+          <label class="pager__perpage">
+            <span>Per page</span>
+            <select id="${p}-per-page" aria-label="${l} per page"></select>
+          </label>
+          <button class="btn-ghost pager__btn" type="button" id="${p}-prev" aria-label="Previous page">‹ Prev</button>
+          <span class="pager__page" id="${p}-page" aria-live="polite"></span>
+          <button class="btn-ghost pager__btn" type="button" id="${p}-next" aria-label="Next page">Next ›</button>
+        </div>
+      </div>`;
+  }
+
+  // Slice `list` to the pager's current page (clamped — a filtered list may
+  // have shrunk under a background poll), paint the bar, return the slice.
+  function paginate(list, p) {
+    const total = list.length;
+    const totalPages = Math.max(1, Math.ceil(total / p.perPage));
+    if (p.page > totalPages) p.page = totalPages;
+    if (p.page < 1) p.page = 1;
+    const start = (p.page - 1) * p.perPage;
+    const slice = list.slice(start, start + p.perPage);
+    renderPagerBar(p, total, totalPages, start, slice.length);
+    return slice;
+  }
+
+  function renderPagerBar(p, total, totalPages, start, shownCount) {
+    const pager = $id(`${p.prefix}-pager`);
+    if (!pager) return;
+    if (total <= p.minPerPage) { pager.hidden = true; return; }
+    pager.hidden = false;
+    const range = $id(`${p.prefix}-range`);
+    if (range) range.textContent = total
+      ? `Showing ${start + 1}–${start + shownCount} of ${total}`
+      : 'Showing 0 of 0';
+    const ind = $id(`${p.prefix}-page`);
+    if (ind) ind.textContent = `Page ${p.page} of ${totalPages}`;
+    const prev = $id(`${p.prefix}-prev`);
+    if (prev) prev.disabled = p.page <= 1;
+    const next = $id(`${p.prefix}-next`);
+    if (next) next.disabled = p.page >= totalPages;
+    const sel = $id(`${p.prefix}-per-page`);
+    if (sel && sel.value !== String(p.perPage)) sel.value = String(p.perPage);
+  }
+
+  // Wire a pager's controls once. `rerender` re-renders that list; a per-page
+  // change resets to page 1 and persists. Fills the per-page <select> from the
+  // pager's own options so pagerBarHtml stays option-agnostic.
+  function wirePager(p, rerender) {
+    const sel = $id(`${p.prefix}-per-page`);
+    if (sel && !sel.options.length) {
+      sel.innerHTML = p.perPageOptions.map((v) => `<option value="${v}">${v}</option>`).join('');
+      sel.value = String(p.perPage);
+    }
+    sel?.addEventListener('change', (e) => {
+      const v = Number(e.target.value);
+      if (!p.perPageOptions.includes(v)) return;
+      p.perPage = v; p.page = 1;
+      try { window.localStorage.setItem(p.key, String(v)); } catch (_) { /* private mode */ }
+      rerender();
+    });
+    $id(`${p.prefix}-prev`)?.addEventListener('click', () => { if (p.page > 1) { p.page -= 1; rerender(); } });
+    $id(`${p.prefix}-next`)?.addEventListener('click', () => { p.page += 1; rerender(); });
+  }
+
+  // ---- ledger ----------------------------------------------------------------
+  // makeLedger({ mount, columns, rowHtml, emptyMsg, emptyAction?, pager? })
+  // Stamps the standard table.ledger (+ pager bar when a pager is given) into
+  // `mount` and returns { el, tbody, render(rows) }. `columns` entries are
+  // strings or { label, class }. `rowHtml(row, i)` returns a <tr> string —
+  // callers keep full control of cells (and must esc() their own data).
+  function makeLedger({ mount, columns = [], rowHtml, emptyMsg = 'Nothing here yet.', emptyAction = null, pager = null }) {
+    if (!mount || typeof rowHtml !== 'function') {
+      throw new Error('makeLedger({ mount, columns, rowHtml, … }) requires mount + rowHtml()');
+    }
+    const head = columns.map((c) => {
+      const col = typeof c === 'string' ? { label: c } : c;
+      return `<th${col.class ? ` class="${esc(col.class)}"` : ''}>${esc(col.label)}</th>`;
+    }).join('');
+    mount.innerHTML = `
+      <table class="ledger">
+        <thead><tr>${head}</tr></thead>
+        <tbody></tbody>
+      </table>
+      ${pager ? pagerBarHtml(pager.prefix, { label: 'rows' }) : ''}`;
+    const tbody = mount.querySelector('tbody');
+    let last = [];
+    function render(rows) {
+      if (Array.isArray(rows)) last = rows;
+      const slice = pager ? paginate(last, pager) : last;
+      tbody.innerHTML = slice.length
+        ? slice.map((r, i) => rowHtml(r, i)).join('')
+        : `<tr><td class="ledger__empty" colspan="${columns.length || 1}">${emptyStateHtml(emptyMsg, emptyAction)}</td></tr>`;
+    }
+    if (pager) wirePager(pager, () => render());
+    return { el: mount, tbody, render };
+  }
+
+  // ---- filter bar ------------------------------------------------------------
+  // makeFilterBar({ mount, search?, primary?, overflow?, url?, onChange })
+  // Primary controls render inline; `overflow` controls sit behind a
+  // "More filters" disclosure with an active-count badge, plus removable chips
+  // when the overflow row is closed. Control spec:
+  //   { id, label, type?: 'select'|'search', options?: [{value,label}|string],
+  //     value?, default? }   (default falls back to the first option / '')
+  // `url: true` round-trips non-default values through the query string
+  // (history.replaceState — shareable filtered views, hash untouched).
+  function makeFilterBar({ mount, search = null, primary = [], overflow = [], url = false, onChange = null }) {
+    if (!mount) throw new Error('makeFilterBar requires mount');
+    const controls = [...(search ? [{ type: 'search', ...search }] : []), ...primary, ...overflow]
+      .map((c) => ({ type: 'select', ...c, default: c.default ?? (c.type === 'search' || !c.options?.length ? '' : optVal(c.options[0])) }));
+    const byId = new Map(controls.map((c) => [c.id, c]));
+    const overflowIds = new Set(overflow.map((c) => c.id));
+
+    function optVal(o) { return typeof o === 'string' ? o : o.value; }
+    function optLabel(o) { return typeof o === 'string' ? o : o.label; }
+
+    if (url) {
+      const q = new URLSearchParams(window.location.search);
+      controls.forEach((c) => { if (q.has(c.id)) c.value = q.get(c.id); });
+    }
+
+    function controlHtml(c) {
+      const cur = c.value ?? c.default;
+      if (c.type === 'search') {
+        return `<label class="filter">${esc(c.label || 'Search')}
+          <input type="search" id="${esc(c.id)}" placeholder="${esc(c.placeholder || '')}" value="${esc(cur)}"></label>`;
+      }
+      const opts = (c.options || []).map((o) =>
+        `<option value="${esc(optVal(o))}"${String(optVal(o)) === String(cur) ? ' selected' : ''}>${esc(optLabel(o))}</option>`).join('');
+      return `<label class="filter">${esc(c.label)}<select id="${esc(c.id)}">${opts}</select></label>`;
+    }
+
+    const activeOverflow = () => overflow.filter((c) => String(get(c.id)) !== String(byId.get(c.id).default));
+
+    mount.innerHTML = `
+      <div class="filters">
+        ${(search ? [controls[0]] : []).map(controlHtml).join('')}
+        ${primary.map((c) => controlHtml(byId.get(c.id))).join('')}
+        ${overflow.length ? `<button type="button" class="btn-ghost filters__more" aria-expanded="false">Filters<span class="count-pill filters__more-count" hidden></span></button>` : ''}
+      </div>
+      ${overflow.length ? `<div class="filters filters--overflow" hidden>
+        ${overflow.map((c) => controlHtml(byId.get(c.id))).join('')}
+        <button type="button" class="btn-ghost filters__clear">Clear all</button>
+      </div>
+      <div class="filter-chips" hidden></div>` : ''}`;
+
+    const moreBtn = mount.querySelector('.filters__more');
+    const overflowRow = mount.querySelector('.filters--overflow');
+    const chipsRow = mount.querySelector('.filter-chips');
+
+    function get(id) {
+      const el = mount.querySelector(`#${CSS.escape(id)}`);
+      return el ? el.value : (byId.get(id)?.value ?? byId.get(id)?.default);
+    }
+    function set(id, value, { fire = true } = {}) {
+      const el = mount.querySelector(`#${CSS.escape(id)}`);
+      if (el) el.value = value;
+      if (fire) changed();
+    }
+    function values() {
+      const out = {};
+      controls.forEach((c) => { out[c.id] = get(c.id); });
+      return out;
+    }
+
+    function paintBadges() {
+      const active = activeOverflow();
+      const count = mount.querySelector('.filters__more-count');
+      if (count) { count.hidden = !active.length; count.textContent = String(active.length); }
+      if (chipsRow) {
+        const open = overflowRow && !overflowRow.hidden;
+        chipsRow.hidden = open || !active.length;
+        chipsRow.innerHTML = active.map((c) => {
+          const cur = get(c.id);
+          const lbl = (c.options || []).find((o) => String(optVal(o)) === String(cur));
+          return `<button type="button" class="chip" data-chip="${esc(c.id)}" title="Remove filter">
+            ${esc(c.label)}: ${esc(lbl ? optLabel(lbl) : cur)} <span aria-hidden="true">×</span></button>`;
+        }).join('');
+      }
+    }
+
+    function syncUrl() {
+      if (!url) return;
+      const q = new URLSearchParams(window.location.search);
+      controls.forEach((c) => {
+        const v = get(c.id);
+        if (String(v) === String(c.default) || v === '') q.delete(c.id); else q.set(c.id, v);
+      });
+      const qs = q.toString();
+      history.replaceState(null, '', window.location.pathname + (qs ? `?${qs}` : '') + window.location.hash);
+    }
+
+    function changed() {
+      paintBadges();
+      syncUrl();
+      if (onChange) onChange(values());
+    }
+
+    mount.addEventListener('change', (e) => { if (e.target.matches('select, input[type="search"]')) changed(); });
+    mount.addEventListener('input', (e) => { if (e.target.matches('input[type="search"]')) changed(); });
+    moreBtn?.addEventListener('click', () => {
+      const open = overflowRow.hidden;
+      overflowRow.hidden = !open;
+      moreBtn.setAttribute('aria-expanded', String(open));
+      paintBadges();
+    });
+    mount.querySelector('.filters__clear')?.addEventListener('click', () => {
+      overflow.forEach((c) => set(c.id, byId.get(c.id).default, { fire: false }));
+      changed();
+    });
+    chipsRow?.addEventListener('click', (e) => {
+      const chip = e.target.closest('[data-chip]');
+      if (chip) set(chip.dataset.chip, byId.get(chip.dataset.chip).default);
+    });
+
+    paintBadges();
+    return { el: mount, values, get, set };
+  }
+
+  // ---- tabs ------------------------------------------------------------------
+  // makeTabs({ mount, tabs: [{ id, label, panel }], initial?, hash?, onChange })
+  // The promoted .setup__tab idiom: a tablist whose buttons toggle [hidden] on
+  // their panel elements — exactly like the index hash views, so the window
+  // stays the only scroller. `hash: true` syncs "#<id>" for deep links and
+  // back/forward, but NEVER claims the "#/…" deep-link namespace (task/idea/
+  // blocker overlays, goal sub-routes) — those hashes pass through untouched.
+  function makeTabs({ mount, tabs = [], initial = null, hash = false, onChange = null }) {
+    if (!mount || !tabs.length) throw new Error('makeTabs requires mount + tabs');
+    const ids = new Set(tabs.map((t) => t.id));
+    mount.innerHTML = `<div class="kit-tabs" role="tablist">${tabs.map((t) => `
+      <button class="setup__tab" type="button" role="tab" id="tab-${esc(t.id)}" aria-selected="false"
+        data-tab="${esc(t.id)}">${esc(t.label)}<span class="count-pill" data-tab-count="${esc(t.id)}" hidden></span></button>`).join('')}
+    </div>`;
+
+    let current = null;
+    function activate(id, { push = true } = {}) {
+      if (!ids.has(id) || id === current) return;
+      current = id;
+      tabs.forEach((t) => {
+        mount.querySelector(`[data-tab="${CSS.escape(t.id)}"]`)?.setAttribute('aria-selected', String(t.id === id));
+        const panel = $id(t.panel);
+        if (panel) panel.hidden = t.id !== id;
+      });
+      if (hash && push && window.location.hash !== `#${id}`) {
+        history.replaceState(null, '', window.location.pathname + window.location.search + `#${id}`);
+      }
+      if (onChange) onChange(id);
+    }
+
+    mount.addEventListener('click', (e) => {
+      const btn = e.target.closest('[data-tab]');
+      if (btn) activate(btn.dataset.tab);
+    });
+
+    function fromHash() {
+      const h = window.location.hash.slice(1);
+      // "#/…" is the overlay/sub-route namespace — never ours.
+      if (!h || h.startsWith('/')) return false;
+      if (ids.has(h)) { activate(h, { push: false }); return true; }
+      return false;
+    }
+    if (hash) window.addEventListener('hashchange', fromHash);
+
+    if (!(hash && fromHash())) activate(initial || tabs[0].id, { push: false });
+
+    return {
+      el: mount,
+      activate,
+      active: () => current,
+      setCount(id, n) {
+        const pill = mount.querySelector(`[data-tab-count="${CSS.escape(id)}"]`);
+        if (pill) { pill.hidden = n == null; pill.textContent = n == null ? '' : String(n); }
+      },
+    };
+  }
+
+  // ---- section rail ------------------------------------------------------------
+  // makeSectionRail({ mount, items: [{ id, label }], mode, onSwitch })
+  // ONE rail, two modes — replaces the two divergent implementations:
+  //  - 'scrollspy' (the Standing idiom): links are #anchors; an
+  //    IntersectionObserver flips --active as section headlines cross a band a
+  //    third of the way down the viewport; window scrolling only.
+  //  - 'switch' (the Settings idiom): links carry data-key; clicking activates
+  //    a key and hands it to onSwitch(key) — the caller toggles its panels.
+  function makeSectionRail({ mount, items = [], mode = 'scrollspy', onSwitch = null }) {
+    if (!mount) throw new Error('makeSectionRail requires mount');
+    let observer = null;
+    let current = null;
+
+    function renderLinks(list) {
+      mount.classList.add('section-rail');
+      mount.innerHTML = list.map((s) => mode === 'switch'
+        ? `<a class="rail-link" href="#${esc(s.id)}" data-key="${esc(s.id)}">${esc(s.label)}</a>`
+        : `<a class="rail-link" href="#${esc(s.id)}" data-section="${esc(s.id)}">${esc(s.label)}</a>`).join('');
+      mount.hidden = list.length < 2;
+    }
+
+    function markActive(id) {
+      current = id;
+      mount.querySelectorAll('.rail-link').forEach((a) => {
+        a.classList.toggle('rail-link--active', (a.dataset.key || a.dataset.section) === id);
+      });
+      const active = mount.querySelector('.rail-link--active');
+      if (active && window.matchMedia('(max-width: 640px)').matches) {
+        active.scrollIntoView({ behavior: 'smooth', inline: 'center', block: 'nearest' });
+      }
+    }
+
+    function observe(list) {
+      observer?.disconnect();
+      if (mode !== 'scrollspy') return;
+      // The active flip happens when a section crosses a ~5% horizontal band
+      // about a third of the way down the viewport (the Standing tuning).
+      observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) { markActive(entry.target.id); break; }
+        }
+      }, { rootMargin: '-40% 0px -55% 0px', threshold: 0 });
+      list.forEach((s) => { const el = $id(s.id); if (el) observer.observe(el); });
+    }
+
+    function refresh(list) {
+      renderLinks(list);
+      observe(list);
+    }
+    refresh(items);
+
+    if (mode === 'switch') {
+      mount.addEventListener('click', (e) => {
+        const a = e.target.closest('.rail-link');
+        if (!a || !a.dataset.key) return;
+        e.preventDefault();
+        markActive(a.dataset.key);
+        if (onSwitch) onSwitch(a.dataset.key);
+      });
+    }
+
+    return {
+      el: mount,
+      refresh,
+      activate: markActive,
+      active: () => current,
+      dispose: () => observer?.disconnect(),
+    };
+  }
+
+  // ---- empty state / skeleton / collapsible ------------------------------------
+
+  // One standard empty pattern: a short line + at most one action link. An
+  // empty card should earn its height or hide — this is the "earn" form.
+  function emptyStateHtml(msg, action = null) {
+    return `<div class="empty-state"><p>${esc(msg)}</p>${action
+      ? `<a class="empty-state__action" href="${esc(action.href)}">${esc(action.label)}</a>` : ''}</div>`;
+  }
+
+  // CSS-only shimmer placeholder rows (style.css §hall-kit), standard heights
+  // so cards don't jump when data lands. For use inside a <tbody>.
+  function skeletonRows(n = 3, cols = 1) {
+    const cells = Array.from({ length: cols }, () => '<td><span class="kit-skel"></span></td>').join('');
+    return Array.from({ length: n }, () => `<tr class="kit-skel-row" aria-hidden="true">${cells}</tr>`).join('');
+  }
+
+  // collapsibleCard({ mount, title, open? }) — the Work-backlog <details> idiom,
+  // generalized: a card section whose body collapses behind its heading.
+  // Returns { el, body, setCount(n) }. Secondary content should default closed.
+  function collapsibleCard({ mount, title, open = false }) {
+    if (!mount) throw new Error('collapsibleCard requires mount');
+    mount.innerHTML = `
+      <details class="kit-collapse"${open ? ' open' : ''}>
+        <summary class="kit-collapse__summary">
+          <span class="scroll__h">${esc(title)}</span>
+          <span class="count-pill" hidden></span>
+        </summary>
+        <div class="kit-collapse__body"></div>
+      </details>`;
+    const details = mount.querySelector('details');
+    const pill = mount.querySelector('.count-pill');
+    return {
+      el: details,
+      body: mount.querySelector('.kit-collapse__body'),
+      setCount(n) {
+        if (pill) { pill.hidden = n == null; pill.textContent = n == null ? '' : String(n); }
+      },
+    };
+  }
+
+  const api = {
+    esc,
+    // pager (low-level exports so pages can adopt incrementally)
+    makePager, pagerBarHtml, paginate, renderPagerBar, wirePager,
+    // composed primitives
+    makeLedger, makeFilterBar, makeTabs, makeSectionRail,
+    // states
+    emptyStateHtml, skeletonRows, collapsibleCard,
+  };
+
+  // Node-require-safe (the dom-utils.js pattern): assignment is the only
+  // eval-time side effect, and only when a window exists.
+  if (typeof window !== 'undefined') window.OTBKit = api;
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+})();