create-pmos 0.51.0 → 0.53.0

package/workspace/public/pm/panel-breakdown.js

@@ -0,0 +1,702 @@
+/* pm/panel-breakdown.js — the Breakdown: an initiative's items, inside today's initiative detail (pm-os-absorb Run 1).
+ *
+ * Two entry points, and no side effect at import:
+ *   breakdownEntry(slug, rec, repo)  one row in the initiative detail — "Breakdown · 7 of 12 ›" — that opens the tab.
+ *                                    Exactly one control. Null in fixture mode, so the pinned screens do not change.
+ *   mountBreakdown(host, tab)        the tab body: the Tree or the Board, the item sheet, Undo, Hand to agent.
+ *
+ * Where the data comes from. GET /api/plan-items returns the initiative's Layout: the items folded from
+ * planning/runs/plan-items.jsonl, the stages of its profile and lane, the owed step per stage from the workflow ladder,
+ * the Board columns and the agent batches. The pane keeps the last Layout it read and draws from it; it stores nothing
+ * else (D33). Writes are optimistic: the change is drawn at once on a copy, POSTed, and the Layout is read again. A
+ * failed write shows the server's own words and reads again, so the screen never keeps a change that was not saved.
+ *
+ * When it reads again. data.js polls /api/sessions every 4 seconds and, while a Breakdown is open, asks for the
+ * plan-items signature of its workspace. A changed `items` signature (an agent's `pmos item`, another window) reads the
+ * Layout without the ladder, which is fast; a changed `evidence` signature (a commit, a run) reads it with the ladder, so
+ * the owed rows follow the workflow.
+ */
+
+import { el, setChildren } from './dom.js';
+import { state, setState, FIXTURE, LEGACY_LAYOUT_FLAG, subscribe } from './state.js';
+import { isMobile } from './mobile.js';
+import { wsOf, watchLedgers } from './data.js';
+import { currentProduct } from './board-read.js';
+import { openTab } from './panel-initiatives.js';
+import { getLayout, postEvents } from './breakdown-api.js';
+import { COPY } from './breakdown-copy.js';
+import { ensureComponentsCss, layer, meter, tabs, menu, toast, button, SEL } from './primitives.js';
+import { ensureSprite } from './icons.js';
+import { hold, cancel, isHeld, flush, overlay, anyHeld } from './undo-hold.js';
+import { loadSortable, baseOptions, dragSet } from './bd-drag.js';
+import { renderTree, bindTreeDrag } from './bd-tree.js';
+import { renderBoard, bindBoardDrag, WIDE_BOARD } from './bd-board.js';
+import { openItemSheet } from './item-sheet.js';
+import { breakdownViews } from './registry.js';
+import {
+  recount, moveLocal, setLocal, flagLocal, removeLocal, keepLocal, planLocal, orderBetween, endOrder, treeOrder,
+} from './bd-model.js';
+
+const COLLAPSE_KEY = 'pm.breakdown.collapsed.v1';
+const STATE_LABEL = (s) => COPY.states[s] || s;
+
+/* ── the entry row in the initiative detail ───────────────────────────────────────────────────────────────────────── */
+
+const entries = new Map();   // `${ws}|${slug}` -> { state: 'idle'|'loading'|'ok'|'error', label, error }
+let entryHooked = false;
+
+function loadEntry(ws, slug, e) {
+  e.state = 'loading'; e.again = false;
+  getLayout(ws, slug, { ladder: false }).then((out) => {
+    if (out && out.ok !== false && out.progress) { e.state = 'ok'; e.label = out.progress.label; }
+    else { e.state = 'error'; e.error = (out && out.error) || 'could not read'; }
+    // The ledger changed while this read was in flight, so the read may not hold the change: read once more.
+    if (e.again) { if (slug === state.sel) { loadEntry(ws, slug, e); return; } e.state = 'idle'; }
+    setState((s) => ({ bdTick: (s.bdTick || 0) + 1 }));
+  });
+}
+
+function hookEntries() {
+  if (entryHooked || typeof window === 'undefined') return;
+  entryHooked = true;
+  window.addEventListener('pmos:ledgers', (ev) => {
+    const changed = (ev && ev.detail && ev.detail.changed) || [];
+    for (const [key, e] of entries) {
+      const [ws, slug] = [key.slice(0, key.indexOf('|')), key.slice(key.indexOf('|') + 1)];
+      if (!changed.includes(ws)) continue;
+      // Not dropped while a read is in flight: that read may have started before the change (loadEntry reads again).
+      if (e.state === 'loading') { e.again = true; continue; }
+      if (slug === state.sel) loadEntry(ws, slug, e); else e.state = 'idle';
+    }
+  });
+}
+
+/** Open the Breakdown tab of one initiative. The title is the one word; the tab's sub-line already names the slug. */
+export function openBreakdown(ws, slug) {
+  openTab({ id: `breakdown:${ws}:${slug}`, kind: 'breakdown', ws, slug, title: COPY.breakdown, role: 'breakdown' });
+}
+
+/**
+ * The detail's entry: one button, "Breakdown" with "7 of 12" or "no breakdown", that opens the tab. `repo` is the
+ * repository panel-detail resolved for the slug; the workspace is read from it with wsOf, as the detail reads it.
+ */
+export function breakdownEntry(slug, rec, repo) {
+  if (FIXTURE || !slug || !rec) return null;
+  const ws = wsOf(repo || currentProduct());
+  if (!ws) return null;
+  ensureComponentsCss();
+  hookEntries();
+  const key = ws + '|' + slug;
+  let e = entries.get(key);
+  if (!e) { e = { state: 'idle' }; entries.set(key, e); }
+  if (e.state === 'idle') loadEntry(ws, slug, e);
+  const meta = e.state === 'ok' ? e.label : e.state === 'error' ? e.error : '';
+  const btn = button({
+    variant: 'outline', block: true, iconEnd: 'chevron-right', onClick: () => openBreakdown(ws, slug),
+    label: [el('span', { class: 'bd-entry__title' }, COPY.breakdown), el('span', { class: 'bd-entry__meta', 'data-bd-entry-meta': '' }, meta)],
+    attrs: { class: 'bd-entry', 'data-bd-entry': '', 'data-ws': ws, 'data-slug': slug, 'aria-label': COPY.breakdown + (meta ? ', ' + meta : '') },
+  });
+  ensureSprite();
+  return LEGACY_LAYOUT_FLAG || isMobile() ? el('div', { class: 'bd-entry-wrap--legacy' }, btn) : btn;
+}
+
+/* ── the pane ─────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+const panes = new WeakMap();   // host -> pane
+const live = new Set();
+let swept = false;
+
+function readCollapsed(P) {
+  try { const all = JSON.parse(localStorage.getItem(COLLAPSE_KEY) || '{}'); const v = all[P.ws + '|' + P.slug]; return Array.isArray(v) ? new Set(v) : null; }
+  catch { return null; }
+}
+function writeCollapsed(P) {
+  try {
+    const all = JSON.parse(localStorage.getItem(COLLAPSE_KEY) || '{}');
+    all[P.ws + '|' + P.slug] = [...P.collapsed];
+    localStorage.setItem(COLLAPSE_KEY, JSON.stringify(all));
+  } catch { /* storage unavailable: the choice lasts for this page only */ }
+}
+
+/**
+ * The layout the pane draws: the last one read, with every held change applied. The server's counts, columns and stage
+ * lists are drawn as they came; only a held change (or an optimistic write, in write()) is re-counted here, and the next
+ * read replaces it.
+ */
+function view(P) {
+  if (!P.raw) return null;
+  const L = typeof structuredClone === 'function' ? structuredClone(P.raw) : JSON.parse(JSON.stringify(P.raw));
+  return anyHeld() ? recount(overlay(L)) : L;
+}
+
+function defaultOpen(L, s) {
+  return !!s.current || !!s.owed || s.proposed > 0 || (s.items || []).some((id) => L.items[id] && L.items[id].state !== 'done');
+}
+
+async function load(P, { ladder }) {
+  const seq = ++P.seq;
+  const out = await getLayout(P.ws, P.slug, { ladder });
+  if (P.disposed) return;
+  if (out && out.ok !== false && out.ladderIncluded) {
+    P.owed = {};
+    for (const s of out.stages || []) P.owed[s.id] = { owed: s.owed || null, current: !!s.current, state: s.state || null };
+    // The owed rows are this read's, so the evidence signature that decides when to read them again is this read's too.
+    P.owedEvidence = out.sig ? out.sig.evidence : null;
+    // A derivation that failed gives no owed rows. The Tree then says so, instead of showing stages that owe nothing.
+    P.owedError = out.ladder && out.ladder.ok === false ? String(out.ladder.error || 'no reason was given') : null;
+  }
+  if (seq !== P.seq) return;
+  if (!out || out.ok === false) { P.error = (out && out.error) || 'could not read'; P.loaded = true; bump(P); return; }
+  if (!out.ladderIncluded) {
+    // the fast read leaves out what the workflow derives: keep it from the last full read
+    for (const s of out.stages || []) {
+      const k = (P.owed && P.owed[s.id]) || { owed: null, current: false, state: null };
+      s.owed = k.owed; s.current = k.current; s.state = k.state;
+      s.visible = s.visible || !!s.owed;
+    }
+  }
+  /* The signature the pane keeps decides when it reads again, so it may name only what this pane has read. `items` is
+   * this read's: the server takes it BEFORE it reads the ledger (lib/plan-items.js readLayout). `evidence` is the one
+   * the owed rows on screen were derived under: a fast read derives none, and taking its evidence signature would mark
+   * owed rows current that were never read again. */
+  P.raw = out; P.error = null; P.loaded = true;
+  P.sig = out.sig ? { ...out.sig, evidence: P.owedEvidence === undefined ? null : P.owedEvidence } : null;
+  bump(P);
+}
+
+function bump(P) {
+  P.ver++;
+  if (P.dragging) return;
+  render(P);
+}
+
+/** The context the Tree, the Board and the sheet draw with. */
+function ctxOf(P, L) {
+  return { P, L, A: P.actions, wide: P.wide, cardMenus: P.cardMenus };
+}
+
+function focusKeyIn(P) {
+  const a = document.activeElement;
+  if (!a || !P.root.contains(a)) return null;
+  const k = a.closest('[data-fk]');
+  return k ? k.getAttribute('data-fk') : null;
+}
+
+function render(P) {
+  P.rendering = true;
+  try {
+    const fk = focusKeyIn(P);
+    const addFocused = P.addEl && document.activeElement === P.addEl.input;
+    const addSel = addFocused ? [P.addEl.input.selectionStart, P.addEl.input.selectionEnd] : null;
+    P.drags.destroy();
+    const L = view(P);
+    P.wide = (P.root.getBoundingClientRect().width || P.lastWidth || 0) >= WIDE_BOARD;
+    /* A wide Board with a fine pointer draws cards without the ⋯ button, as specimen A does (D1: the Board's 33-control
+     * budget; a ⋯ on every card is 50). Its cards keep the same menu, Hand to agent included, on a right-click and on
+     * Shift+F10 or the ContextMenu key (bd-board.js). A touch screen always gets the ⋯ button. */
+    P.cardMenus = !P.wide || P.coarse;
+    /* head: Tree | Board, then each registered view (registry.js, Runs 2 to 5: Timeline is Run 4's), then the meter */
+    const extra = breakdownViews();
+    P.viewsKey = viewsKey(extra);
+    if (P.view !== 'tree' && P.view !== 'board' && !extra.some((v) => v.id === P.view)) P.view = 'tree';
+    const switcher = tabs({
+      variant: 'segmented', ariaLabel: COPY.views, value: P.view,
+      items: [{ id: 'tree', label: COPY.tree }, { id: 'board', label: COPY.board }, ...extra.map((v) => ({ id: v.id, label: v.label || v.id }))],
+      onChange: (v) => P.actions.setView(v), attrs: { 'data-bd-view': P.view },
+    });
+    for (const b of switcher.querySelectorAll('[data-tab]')) b.setAttribute('data-fk', 'view:' + b.getAttribute('data-tab'));
+    const prog = L ? L.progress : null;
+    setChildren(P.headEl, [switcher, prog ? meter({ done: prog.done, total: prog.total, label: prog.label }) : null]);
+    /* body */
+    let kids;
+    if (!P.loaded) kids = [el('div', { class: 'bd-note' }, COPY.reading)];
+    else if (!L) kids = [el('div', { class: 'bd-note bd-note--error', role: 'alert' }, COPY.readFailed(P.error || ''))];
+    else {
+      if (!P.roveId || !L.items[P.roveId]) P.roveId = firstRow(P, L);
+      const ext = extra.find((v) => v.id === P.view);
+      kids = ext ? [extHost(P, ext, L)] : P.view === 'board' ? renderBoard(ctxOf(P, L)) : renderTree(ctxOf(P, L));
+      kids.unshift(...notesOf(P, L));
+      if (P.error) kids.unshift(el('div', { class: 'bd-note bd-note--error', role: 'alert' }, COPY.readFailed(P.error)));
+    }
+    setChildren(P.bodyEl, kids);
+    P.root.setAttribute('data-bd-view', P.view);
+    P.root.setAttribute('data-bd-progress', prog ? prog.label : '');
+    if (fk) {
+      const t = P.root.querySelector('[data-fk="' + (window.CSS && CSS.escape ? CSS.escape(fk) : fk) + '"]');
+      if (t && document.activeElement !== t) t.focus({ preventScroll: true });
+    }
+    if (addFocused && P.addEl && P.addEl.input.isConnected) {
+      P.addEl.input.focus({ preventScroll: true });
+      try { P.addEl.input.setSelectionRange(addSel[0], addSel[1]); } catch { /* not a text input */ }
+    }
+    P.renderedVer = P.ver;
+    if (P.sheet && P.sheet.open) P.sheet.refresh();
+    bindDrag(P);
+  } finally { P.rendering = false; }
+}
+
+/* What the rows cannot say, in words above them. Static text: neither note adds a control.
+ *   - Owed steps that could not be derived. The Tree then draws none, and without this note a failure read as a stage
+ *     that owes nothing. The engine's own word for the derivation is kept off the screen (glossary.test.js).
+ *   - The ledger's own flags: a torn or schema-invalid line, an item planned twice, one event with two contents, a Keep
+ *     with no effect, a predecessor loop. The fold skips those lines, so no row shows them. An unknown stage is left
+ *     out: its item already shows under Other. */
+const FLAGS_SHOWN = 3;
+function notesOf(P, L) {
+  const out = [];
+  if (P.view === 'tree' && P.owedError) {
+    const why = P.owedError.replace(/^the ladder could not be derived:\s*/i, '').replace(/\bladders?\b/gi, 'workflow');
+    out.push(el('div', { class: 'bd-note bd-note--error', role: 'status', 'data-bd-owed-error': '' }, COPY.owedFailed(why)));
+  }
+  const flags = (L.flags || []).filter((f) => f && f.message && f.kind !== 'unknown-stage');
+  if (flags.length) {
+    const shown = flags.slice(0, FLAGS_SHOWN);
+    out.push(el('div', { class: 'bd-note bd-note--flags', 'data-bd-flags': String(flags.length) },
+      el('div', null, COPY.flagsHead(flags.length)),
+      el('ul', { class: 'bd-flags' }, shown.map((f) => el('li', { 'data-flag': f.kind }, f.message))),
+      flags.length > shown.length ? el('div', null, COPY.flagsMore(flags.length - shown.length)) : null));
+  }
+  return out;
+}
+
+/* ── a registered view (registry.js registerBreakdownView): its own host, mounted on every render ───────────────────── */
+
+const viewsKey = (list) => list.map((v) => v.id).join(',');
+
+/**
+ * The host a registered view draws into: one element per view id, kept while that view is shown. `mount(host, ctx)` is
+ * called on every render of the pane with the Layout of that render; the view rebuilds only what changed. ctx:
+ *   ws, slug, layout   the workspace, the initiative and the Layout the pane draws (held changes applied)
+ *   coarse             a coarse pointer
+ *   setFields(id, f)   one `set` event through the pane's own write (optimistic, POST /api/plan-items, read again)
+ *   openItem(id)       the item sheet
+ *   hold(on)           true while a gesture is live: the pane does not draw again until hold(false)
+ */
+function extHost(P, view, L) {
+  let host = P.extHosts.get(view.id);
+  if (!host) { host = el('div', { class: 'bd-view', 'data-bd-ext': view.id }); P.extHosts.set(view.id, host); }
+  const ctx = {
+    ws: P.ws, slug: P.slug, layout: L, coarse: P.coarse,
+    setFields: (id, fields) => P.actions.setFields(id, fields),
+    openItem: (id) => P.actions.openSheet(id),
+    hold: (on) => { P.dragging = !!on; if (!on && !P.disposed && P.renderedVer !== P.ver) render(P); },
+  };
+  try { view.mount(host, ctx); } catch (e) { console.error('[pm] Breakdown view ' + view.id + ' failed:', e); }
+  return host;
+}
+
+function disposeExt(P, id) {
+  const host = P.extHosts.get(id);
+  if (!host) return;
+  P.extHosts.delete(id);
+  P.dragging = false;
+  const view = breakdownViews().find((v) => v.id === id);
+  if (view && typeof view.dispose === 'function') { try { view.dispose(host); } catch (e) { console.error('[pm] Breakdown view ' + id + ' dispose failed:', e); } }
+}
+
+function bindDrag(P) {
+  if (!P.raw || P.disposed) return;
+  const ver = P.ver;
+  loadSortable().then((Sortable) => {
+    if (!Sortable || P.disposed || P.ver !== ver || P.drags.size) return;
+    const L = view(P);
+    if (!L) return;
+    const ctx = ctxOf(P, L);
+    if (P.view === 'board') bindBoardDrag(ctx, Sortable, P.drags, baseOptions);
+    else if (P.view === 'tree') bindTreeDrag(ctx, Sortable, P.drags, baseOptions);
+  });
+}
+
+function firstRow(P, L) {
+  for (const s of L.stages || []) {
+    if (!s.visible || !isExpanded(P, L, s)) continue;
+    const id = (s.items || []).find((x) => P.foldOpen.has(s.id) || L.items[x].state !== 'done');
+    if (id) return id;
+  }
+  return null;
+}
+
+function isExpanded(P, L, s) {
+  if (P.adding && P.adding.stage === s.id) return true;
+  if (P.collapsed) return !P.collapsed.has(s.id);
+  return defaultOpen(L, s);
+}
+
+/* ── writes ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+async function write(P, events, apply) {
+  if (apply && P.raw) { apply(P.raw); recount(P.raw); bump(P); }
+  const out = await postEvents(P.ws, events);
+  if (!out || out.ok === false) {
+    toast({ text: (out && out.error) || 'nothing was saved', tone: 'error' });
+    await load(P, { ladder: true });
+    return out;
+  }
+  /* The POST's own signature is not kept: it names the ledger after this write AND after any line another writer
+   * appended first, which this pane has not read. The read below brings the items and their signature together. A
+   * poll that lands before it reads once more, which is harmless. */
+  await load(P, { ladder: false });
+  return out;
+}
+
+/** After an Undo: draw again, and give the row back its focus (the toast's button that had it is gone). */
+function undone(P, id) {
+  bump(P);
+  const t = P.root.querySelector('[data-fk="open:' + id + '"], [data-fk="card:' + id + '"]');
+  if (t && t.isConnected && !(P.sheet && P.sheet.open)) t.focus({ preventScroll: true });
+}
+
+function makeActions(P) {
+  const L = () => view(P);
+  const A = {
+    isExpanded: (s) => isExpanded(P, L(), s),
+    refresh: () => load(P, { ladder: false }),
+    rerender: () => bump(P),
+    setView(v) { if (P.view === v) return; disposeExt(P, P.view); P.view = v; P.roveId = null; bump(P); },
+    setBoardCol(c) { if (P.boardCol === c) return; P.boardCol = c; bump(P); },
+    toggleStage(id) {
+      const lay = L();
+      if (!P.collapsed) P.collapsed = new Set((lay.stages || []).filter((s) => !defaultOpen(lay, s)).map((s) => s.id));
+      if (P.collapsed.has(id)) P.collapsed.delete(id); else P.collapsed.add(id);
+      writeCollapsed(P);
+      bump(P);
+    },
+    toggleFold(id) { if (P.foldOpen.has(id)) P.foldOpen.delete(id); else P.foldOpen.add(id); bump(P); },
+    startAdd(stage, afterId) {
+      P.adding = { stage, afterId: afterId || null };
+      if (P.collapsed && P.collapsed.has(stage)) { P.collapsed.delete(stage); writeCollapsed(P); }
+      bump(P);
+      if (P.addEl) P.addEl.input.focus();
+    },
+    closeAdd(refocus) {
+      const was = P.adding;
+      P.adding = null; P.addEl = null;
+      bump(P);
+      if (refocus && was) {
+        const t = P.root.querySelector(was.afterId ? '[data-fk="open:' + was.afterId + '"]' : '[data-fk="add:' + was.stage + '"]');
+        if (t) t.focus();
+      }
+    },
+    async addTitles(stage, titles, afterId) {
+      const lay = L();
+      if (!lay) return;
+      const list = (lay.stages.find((s) => s.id === stage) || { items: [] }).items || [];
+      let prev = null; let next = null;
+      if (afterId && lay.items[afterId]) {
+        prev = lay.items[afterId].order;
+        const i = list.indexOf(afterId);
+        const n = list.slice(i + 1).find((x) => lay.items[x]);
+        next = n ? lay.items[n].order : null;
+      }
+      const events = []; const tmp = [];
+      titles.forEach((title, k) => {
+        let order;
+        if (afterId) {
+          const step = next === null ? 1024 : (next - prev) / (titles.length + 1);
+          order = next === null ? prev + 1024 * (k + 1) : prev + step * (k + 1);
+          if (!(Math.abs(step) >= 1e-6)) order = undefined;
+        }
+        const ev = { ev: 'planned', initiative: P.slug, title, stage };
+        if (Number.isFinite(order)) ev.order = order;
+        events.push(ev);
+        tmp.push({ tmpId: P.slug + '.tmp' + (++P.tmpN), title, stage, order });
+      });
+      if (P.adding) P.adding.afterId = afterId ? tmp[tmp.length - 1].tmpId : null;
+      if (afterId) P.roveId = tmp[tmp.length - 1].tmpId;
+      const out = await write(P, events, (raw) => { for (const t of tmp) planLocal(raw, t); });
+      if (out && out.ok !== false && Array.isArray(out.written)) {
+        const ids = out.written.map((w) => w.item).filter(Boolean);
+        const k = tmp.findIndex((t) => t.tmpId === P.roveId);
+        if (k >= 0 && ids[k]) P.roveId = ids[k];
+      }
+      if (out && out.ok !== false && Array.isArray(out.written) && P.adding) {
+        const ids = out.written.map((w) => w.item).filter(Boolean);
+        if (P.adding.afterId && P.adding.afterId.includes('.tmp')) P.adding.afterId = ids[ids.length - 1] || null;
+        bump(P);
+      }
+    },
+    tick(id) {
+      const it = L() && L().items[id];
+      if (!it) return;
+      if (it.state !== 'done') { A.moveTo(id, 'done'); return; }
+      if (cancel('done:' + id)) { bump(P); return; }
+      write(P, [{ ev: 'moved', item: id, to: 'todo' }], (raw) => moveLocal(raw, id, 'todo'));
+    },
+    moveTo(id, to) {
+      const it = L() && L().items[id];
+      if (!it) { bump(P); return; }
+      if (it.state === to) { bump(P); return; }
+      if (to === 'done') {
+        hold({
+          key: 'done:' + id, ws: P.ws, text: COPY.markedDone,
+          events: [{ ev: 'moved', item: id, to: 'done' }],
+          apply: (lay) => moveLocal(lay, id, 'done'),
+          onDone: () => load(P, { ladder: false }), onUndo: () => undone(P, id),
+        });
+        bump(P);
+        return;
+      }
+      if (isHeld('done:' + id)) cancel('done:' + id);
+      write(P, [{ ev: 'moved', item: id, to }], (raw) => moveLocal(raw, id, to));
+    },
+    withdraw(id) {
+      const it = L() && L().items[id];
+      if (!it) return;
+      // A held Done is written first, so an Undo of the withdraw returns the item as Done, not as it was before the Done.
+      flush('done:' + id);
+      hold({
+        key: 'withdraw:' + id, ws: P.ws, text: COPY.withdrawn,
+        events: [{ ev: 'withdrawn', item: id }],
+        apply: (lay) => removeLocal(lay, id),
+        onDone: () => load(P, { ladder: false }), onUndo: () => undone(P, id),
+      });
+      bump(P);
+    },
+    setFields(id, fields) { return write(P, [{ ev: 'set', item: id, fields }], (raw) => setLocal(raw, id, fields)); },
+    flag(id, blocked, reason) {
+      return write(P, [blocked ? { ev: 'flagged', item: id, blocked: true, reason } : { ev: 'flagged', item: id, blocked: false }],
+        (raw) => flagLocal(raw, id, blocked, reason));
+    },
+    keepApplied(b) { if (P.raw) { keepLocal(P.raw, b.by, b.items); bump(P); } },
+    /** Keep all from the item sheet: the same `kept` line the Keep card writes, and only the page writes it. */
+    async keepBatch(b) {
+      const n = (b.items || []).length;
+      const out = await write(P, [{ ev: 'kept', initiative: P.slug, batch: b.by, items: b.items }], (raw) => keepLocal(raw, b.by, b.items));
+      if (out && out.ok !== false) toast({ text: COPY.kept(n) });
+    },
+    reorder(id, dir) {
+      const lay = L();
+      const it = lay && lay.items[id];
+      if (!it) return;
+      const stages = (lay.stages || []).filter((s) => s.visible);
+      const si = stages.findIndex((s) => s.id === it.stage);
+      const list = si >= 0 ? stages[si].items : [];
+      const i = list.indexOf(id);
+      if (dir < 0 && i > 0) {
+        const before = list[i - 1]; const beforeBefore = i > 1 ? list[i - 2] : null;
+        placeAt(P, id, it.stage, beforeBefore ? lay.items[beforeBefore].order : null, lay.items[before].order, list.filter((x) => x !== id), i - 1);
+      } else if (dir > 0 && i >= 0 && i < list.length - 1) {
+        const after = list[i + 1]; const afterAfter = i < list.length - 2 ? list[i + 2] : null;
+        placeAt(P, id, it.stage, lay.items[after].order, afterAfter ? lay.items[afterAfter].order : null, list.filter((x) => x !== id), i + 1);
+      } else if (dir < 0 && si > 0) {
+        const to = stages[si - 1];
+        write(P, [{ ev: 'set', item: id, fields: { stage: to.id, order: endOrder(lay, to.id) } }], (raw) => setLocal(raw, id, { stage: to.id, order: endOrder(raw, to.id) }));
+      } else if (dir > 0 && si >= 0 && si < stages.length - 1) {
+        const to = stages[si + 1];
+        const first = (to.items || [])[0];
+        const order = first ? lay.items[first].order - 1024 : 1024;
+        if (P.collapsed && P.collapsed.has(to.id)) { P.collapsed.delete(to.id); writeCollapsed(P); }
+        write(P, [{ ev: 'set', item: id, fields: { stage: to.id, order } }], (raw) => setLocal(raw, id, { stage: to.id, order }));
+      }
+    },
+    dropTree(evt) {
+      const id = evt.item && evt.item.getAttribute('data-item');
+      const toList = evt.to;
+      const stage = toList ? toList.getAttribute('data-stage-list') : null;
+      const lay = L();
+      if (!id || !lay || !lay.items[id] || !stage || (evt.from === evt.to && evt.oldIndex === evt.newIndex)) { bump(P); return; }
+      const rows = [...toList.querySelectorAll(':scope > .bd-trow')].map((r) => r.getAttribute('data-item'));
+      const k = rows.indexOf(id);
+      const prev = k > 0 ? lay.items[rows[k - 1]] : null;
+      const next = k < rows.length - 1 ? lay.items[rows[k + 1]] : null;
+      placeAt(P, id, stage, prev ? prev.order : null, next ? next.order : null, rows.filter((x) => x !== id), k);
+    },
+    dropHeader(id, stage) {
+      const lay = L();
+      if (!id || !lay || !lay.items[id]) { bump(P); return; }
+      if (lay.items[id].stage === stage) { bump(P); return; }
+      const order = endOrder(lay, stage);
+      write(P, [{ ev: 'set', item: id, fields: { stage, order } }], (raw) => setLocal(raw, id, { stage, order }));
+    },
+    openSheet(id, opts) {
+      if (P.sheet && P.sheet.open) P.sheet.close();
+      const ctx = {
+        ws: P.ws, slug: P.slug, view: () => view(P),
+        move: (i, to) => A.moveTo(i, to), setFields: (i, f) => A.setFields(i, f), flag: (i, b, r) => A.flag(i, b, r),
+        withdraw: (i) => A.withdraw(i), sessions: () => state.sessions || [],
+        attachEvidence: (i, evidence) => write(P, [{ ev: 'moved', item: i, to: 'done', evidence }], (raw) => {
+          const x = raw.items[i]; const k = String(evidence).indexOf(':');
+          if (x && k > 0) { x.evidence = { kind: String(evidence).slice(0, k), ref: String(evidence).slice(k + 1) }; x.noEvidence = false; }
+        }),
+        keep: (b) => A.keepBatch(b),
+        onClose: (i) => {
+          P.sheet = null;
+          const t = P.root.querySelector('[data-fk="open:' + i + '"], [data-fk="card:' + i + '"]');
+          if (t && t.isConnected) t.focus({ preventScroll: true });
+        },
+      };
+      P.sheet = openItemSheet(ctx, id, opts);
+    },
+    menu(anchor, id, place) {
+      const lay = L();
+      const it = lay && lay.items[id];
+      if (!it) return;
+      const items = [];
+      if (place === 'tree') items.push({ label: COPY.menu.open, onSelect: () => A.openSheet(id) });
+      for (const s of ['todo', 'doing', 'review', 'done']) if (s !== it.state) items.push({ label: COPY.menu.moveTo(STATE_LABEL(s)), onSelect: () => A.moveTo(id, s) });
+      if (place === 'tree') {
+        items.push({ sep: true });
+        items.push({ label: COPY.menu.moveUp, icon: 'arrow-up', onSelect: () => A.reorder(id, -1) });
+        items.push({ label: COPY.menu.moveDown, icon: 'arrow-down', onSelect: () => A.reorder(id, 1) });
+      }
+      items.push({ sep: true });
+      items.push({ label: COPY.handToAgent, icon: 'bot', onSelect: () => A.openSheet(id, { handoff: true }) });
+      items.push({ label: COPY.labels.withdraw, danger: true, onSelect: () => A.withdraw(id) });
+      menu({ anchor, items, ariaLabel: COPY.aria.more(it.title) });
+    },
+  };
+  return A;
+}
+
+/** Put `id` between two orders in `stage`. When the gap is too small, renumber the whole stage in one request. */
+function placeAt(P, id, stage, prevOrder, nextOrder, others, index) {
+  const lay = view(P);
+  const it = lay.items[id];
+  const stageChange = it.stage !== stage;
+  const order = orderBetween(prevOrder, nextOrder);
+  if (order !== null) {
+    const fields = stageChange ? { stage, order } : { order };
+    write(P, [{ ev: 'set', item: id, fields }], (raw) => setLocal(raw, id, fields));
+    return;
+  }
+  const ids = (lay.stages.find((s) => s.id === stage) || { items: [] }).items.filter((x) => x !== id);
+  const full = [...(others || ids)];
+  full.splice(Math.max(0, Math.min(index, full.length)), 0, id);
+  const events = full.map((x, i) => ({ ev: 'set', item: x, fields: x === id && stageChange ? { stage, order: (i + 1) * 1024 } : { order: (i + 1) * 1024 } }));
+  write(P, events, (raw) => { full.forEach((x, i) => setLocal(raw, x, x === id && stageChange ? { stage, order: (i + 1) * 1024 } : { order: (i + 1) * 1024 })); });
+}
+
+/* ── keyboard on the pane body ────────────────────────────────────────────────────────────────────────────────────── */
+
+function onKey(P, e) {
+  const t = e.target;
+  if (!t || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName)) return;
+  if (P.view !== 'tree') return;
+  const fk = (t.closest('[data-fk]') || t).getAttribute('data-fk') || '';
+  const rowId = fk.startsWith('open:') ? fk.slice(5) : null;
+  const headId = fk.startsWith('stage:') ? fk.slice(6) : null;
+  if (!rowId && !headId) return;
+  const A = P.actions;
+  const handled = () => { e.preventDefault(); e.stopPropagation(); };
+  const roves = [...P.bodyEl.querySelectorAll('[data-rove]')];
+  const i = roves.indexOf(t);
+  if (e.altKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
+    if (rowId) { handled(); P.roveId = rowId; A.reorder(rowId, e.key === 'ArrowUp' ? -1 : 1); }
+    return;
+  }
+  if (e.metaKey || e.ctrlKey || e.altKey) return;
+  if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'j' || e.key === 'k') {
+    handled();
+    const j = i + (e.key === 'ArrowUp' || e.key === 'k' ? -1 : 1);
+    const n = roves[Math.max(0, Math.min(roves.length - 1, j))];
+    if (n) {
+      for (const r of roves) if (r.getAttribute('data-rove') === 'row') r.setAttribute('tabindex', '-1');
+      if (n.getAttribute('data-rove') === 'row') { n.setAttribute('tabindex', '0'); P.roveId = (n.getAttribute('data-fk') || '').slice(5); }
+      n.focus();
+    }
+    return;
+  }
+  if (e.key === ' ' && rowId) { handled(); A.tick(rowId); return; }
+  if (e.key === 'n' || e.key === 'N') {
+    handled();
+    if (rowId) { const lay = view(P); A.startAdd(lay.items[rowId].stage, rowId); } else A.startAdd(headId, null);
+  }
+}
+
+/* ── mount ────────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function dispose(P) {
+  P.disposed = true;
+  for (const id of [...P.extHosts.keys()]) disposeExt(P, id);
+  P.drags.destroy();
+  if (P.unwatch) P.unwatch();
+  if (P.onLedgers) window.removeEventListener('pmos:ledgers', P.onLedgers);
+  if (P.resize) P.resize.disconnect();
+  if (P.sheet && P.sheet.open) P.sheet.close();
+  live.delete(P);
+}
+
+function sweep() {
+  const open = new Set((state.tabs || []).map((t) => t && t.id));
+  // an embedded pane (the initiative sheet's Breakdown tab, Run 2) is not a panel-4 tab: its owner calls unmountBreakdown
+  for (const P of [...live]) if (!P.embedded && !open.has(P.tab.id)) dispose(P);
+}
+
+function createPane(host, tab) {
+  const ws = tab.ws; const slug = tab.slug;
+  const headEl = el('div', { class: 'bd-head' });
+  const bodyEl = el('div', { class: 'bd-body', 'data-bd-body': '' });
+  const root = el('div', { class: 'bd-pane', 'data-bd-pane': '', 'data-ws': ws || '', 'data-slug': slug || '' }, headEl, bodyEl);
+  const P = {
+    host, tab, ws, slug, root, headEl, bodyEl, raw: null, sig: null, owed: null, error: null, loaded: false,
+    view: 'tree', boardCol: 'todo', foldOpen: new Set(), adding: null, addEl: null, roveId: null, tmpN: 0,
+    ver: 0, renderedVer: -1, seq: 0, drags: dragSet(), dragging: false, rendering: false, disposed: false, sheet: null,
+    wide: false, cardMenus: true, lastWidth: 0, extHosts: new Map(), viewsKey: '',
+    coarse: typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches,
+  };
+  P.collapsed = readCollapsed(P);
+  P.actions = makeActions(P);
+  bodyEl.addEventListener('keydown', (e) => onKey(P, e));
+  P.unwatch = watchLedgers(ws);
+  P.onLedgers = (e) => {
+    const d = e && e.detail;
+    if (!d || !(d.changed || []).includes(ws)) return;
+    const sig = d.ledgers && d.ledgers[ws];
+    if (!sig) return;
+    const evidenceMoved = sig.evidence && P.sig && sig.evidence !== P.sig.evidence;
+    const itemsMoved = !P.sig || sig.items !== P.sig.items;
+    if (evidenceMoved) load(P, { ladder: true });
+    else if (itemsMoved) load(P, { ladder: false });
+  };
+  window.addEventListener('pmos:ledgers', P.onLedgers);
+  if (typeof ResizeObserver === 'function') {
+    P.resize = new ResizeObserver((entries) => {
+      const w = entries[0] && entries[0].contentRect.width;
+      if (!w) return;
+      P.lastWidth = w;
+      if ((w >= WIDE_BOARD) !== P.wide && P.view === 'board') bump(P);
+    });
+    P.resize.observe(root);
+  }
+  return P;
+}
+
+/**
+ * The Breakdown tab's body. Called on every app render; it rebuilds only when the data or the view changed. The pane's
+ * state lives here, not in state.js.
+ *
+ * `embedded: true` (pm-os-absorb Runs 2 to 5) mounts the same pane inside another surface, such as the initiative sheet.
+ * `tab` is then `{ id, ws, slug }` with an id that is no panel-4 tab; closing tabs does not dispose the pane, and the
+ * owner calls unmountBreakdown(host) when it lets go of the host.
+ */
+export function mountBreakdown(host, tab, { embedded = false } = {}) {
+  if (FIXTURE) { if (!host.firstChild) host.appendChild(el('div', null, COPY.breakdown)); return; }
+  if (!swept) { swept = true; subscribe(sweep); }
+  let P = panes.get(host);
+  if (P && (P.disposed || P.tab.id !== tab.id)) { dispose(P); P = null; }
+  if (!P) {
+    ensureComponentsCss(); layer(); ensureSprite();
+    P = createPane(host, tab);
+    P.embedded = !!embedded;
+    panes.set(host, P); live.add(P);
+    if (host.firstChild !== P.root || host.childNodes.length !== 1) setChildren(host, [P.root]);
+    render(P);
+    load(P, { ladder: true });
+    return;
+  }
+  if (host.firstChild !== P.root || host.childNodes.length !== 1) setChildren(host, [P.root]);
+  // a view registered after the pane was drawn (the registry loads after boot) joins the switch on the next app render
+  if ((P.renderedVer !== P.ver || P.viewsKey !== viewsKey(breakdownViews())) && !P.dragging) render(P);
+}
+
+/** Release the pane mounted in `host` (its ledger watch, its listeners, an open sheet). For an embedded pane. */
+export function unmountBreakdown(host) {
+  const P = panes.get(host);
+  if (!P) return;
+  panes.delete(host);
+  if (!P.disposed) dispose(P);
+}
+
+/* for the browser suites: the pane of a tab id, read-only */
+export function _paneOf(tabId) { for (const P of live) if (P.tab.id === tabId) return P; return null; }
+export { SEL };