create-pmos 0.14.0 → 0.16.0

package/workspace/public/pm/tab-term.js

@@ -0,0 +1,560 @@
+/* pm/tab-term.js — the body of a `term` tab. ONE component, TWO modes.
+ *
+ * ── fixture mode (`?fixture=proto`) ──────────────────────────────────────────────────────────
+ * The prototype's faux terminal, ported line for line from template lines 928–939 and derivation
+ * lines 1981–2006: the five attach lines, the transcript in `termHist[tab.id]`, the working prompt
+ * with the blinking `pmblink` caret, and the fake shell's command table (which lives in
+ * fixture.js — `termBaseLines` / `fauxShellReply` / `termEcho` — so there is exactly one copy of
+ * it). Every inline style below is the prototype's string, character for character, and each
+ * interpolated value sits in its own `<span>` because that is what the prototype's runtime emits
+ * (`<span class="sc-interp">…</span>`) and the comparator reads text nodes, not properties.
+ * Fixture mode opens no socket and touches no PTY: it is the offline demo path and the only render
+ * the comparator ever sees.
+ *
+ * ── real mode (everything else) ─────────────────────────────────────────────────────────────
+ * A LIVE xterm.js terminal on the existing WebSocket/node-pty path — the same protocol the retired
+ * public/app.js spoke, preserved frame for frame:
+ *
+ *   out: attach{id} · input{id,data} · resize{id,cols,rows} · detach{id} · new{name,agent,ws}
+ *   in : hello{sessions} · sessions{sessions} · attached{id,buf,…} · data{id,data} · created{id}
+ *
+ * Three properties of that path are load-bearing and are the reason this file is written the way
+ * it is:
+ *
+ *   1. A SESSION SURVIVES DETACH AND RELOAD. The PTY lives in the server; the browser holds a view
+ *      of it. Closing a tab sends `detach`, never `kill`. Reconnecting re-`attach`es and the
+ *      server replays its ring buffer, so scrollback comes back with the page.
+ *   2. A TERMINAL IS NEVER REBUILT BY NAVIGATION. One xterm per tab id, kept for the tab's whole
+ *      life. panel-tabs.js caches the pane host for the same reason; `mountTerm` is therefore
+ *      idempotent — called on every render, it builds once and re-fits thereafter.
+ *   3. IT MUST BE RE-FITTED. A terminal that attaches and is never re-fitted keeps a stale grid:
+ *      output wraps at the wrong column and a full-screen TUI paints into a box that is not there.
+ *      It is invisible in a screenshot of an empty terminal, which is why the PRD names it "the
+ *      quiet PTY regression". Refit is explicit here — ONE exported `refitVisible()` — and it is
+ *      driven from every event that can change a terminal's box: a render (tab shown, split
+ *      toggled, a panel collapsed), a ResizeObserver on the pane, window resize, tab visibility,
+ *      and `document.fonts.ready` (xterm measures its cell from the face resolved at construction,
+ *      so the first real metrics arrive after the woff2 lands).
+ *
+ * The xterm palette is the DESIGN's: `--term-bg` for the background — dark in both themes, D41 —
+ * and IBM Plex Mono at the design's 12.5px / 1.65. xterm's colour parser does not understand
+ * `oklch()`, so the token is resolved to a concrete sRGB value at runtime (canvas round-trip, with
+ * the pre-computed hex as the fallback) rather than handed to xterm as written.
+ */
+
+import { el, setChildren } from './dom.js';
+import { state, setState, subscribe, FIXTURE } from './state.js';
+import * as FX from './fixture.js';
+
+/* ── the design's terminal colours ───────────────────────────────────────────────────────────
+ * `--term-bg` is oklch(0.148 0.004 228.8) in BOTH themes. Resolved through a canvas at runtime so
+ * the value xterm gets is whatever the stylesheet actually says; TERM_BG_FALLBACK is that same
+ * oklch converted offline, for a browser that will not do the conversion for us. The ANSI ramp is
+ * the workspace's own, unchanged — it is the palette agent CLIs have been rendering against.
+ */
+const TERM_BG_FALLBACK = '#090b0c';
+const ANSI = {
+  foreground: '#c4ccce', cursor: '#47cf79', cursorAccent: '#090b0c',
+  selectionBackground: 'rgba(43,127,255,.3)',
+  black: '#090b0c', red: '#ff6467', green: '#47cf79', yellow: '#f4b93c',
+  blue: '#2b7fff', magenta: '#b48df4', cyan: '#53d1d0', white: '#d2d9db',
+  brightBlack: '#6f7d81', brightRed: '#ff6467', brightGreen: '#81e8a0', brightYellow: '#f4b93c',
+  brightBlue: '#2b7fff', brightMagenta: '#b48df4', brightCyan: '#53d1d0', brightWhite: '#f9fbfb',
+};
+
+/** Resolve a CSS colour value (possibly `oklch(…)`, possibly a `var()`) to something xterm parses. */
+function resolveColor(value, fallback) {
+  let spec = value;
+  try {
+    const probe = document.createElement('span');
+    probe.style.cssText = 'position:absolute;left:-9999px;top:-9999px;visibility:hidden';
+    probe.style.color = value;
+    document.body.appendChild(probe);
+    spec = getComputedStyle(probe).color || value;
+    probe.remove();
+  } catch { /* keep the literal */ }
+  if (/^rgba?\(/.test(spec) || /^#/.test(spec)) return spec;
+  try {
+    const c = document.createElement('canvas');
+    c.width = c.height = 1;
+    const ctx = c.getContext('2d');
+    ctx.fillStyle = '#000000';
+    ctx.fillStyle = spec;                      // an unparsable value leaves the previous one
+    ctx.fillRect(0, 0, 1, 1);
+    const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+    const hex = '#' + [r, g, b].map((n) => n.toString(16).padStart(2, '0')).join('');
+    if (hex !== '#000000') return hex;
+  } catch { /* fall through */ }
+  return fallback;
+}
+
+/** The xterm theme, read off the live token layer (app.js:165–179 in the retired client). */
+function xtheme() {
+  let bg = TERM_BG_FALLBACK;
+  try {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue('--term-bg').trim();
+    if (raw) bg = resolveColor(raw, TERM_BG_FALLBACK);
+  } catch { /* the fallback IS the design's value */ }
+  return { ...ANSI, background: bg, cursorAccent: bg };
+}
+
+/* ── module state ──────────────────────────────────────────────────────────────────────────── */
+
+/** tab id → the mounted pane. Fixture panes and real panes are both keyed here. */
+const panes = new Map();
+
+const XTERM = () => (typeof window !== 'undefined' ? window.Terminal : null);
+const FIT = () => (typeof window !== 'undefined' && window.FitAddon ? window.FitAddon.FitAddon : null);
+const LINKS = () => (typeof window !== 'undefined' && window.WebLinksAddon ? window.WebLinksAddon.WebLinksAddon : null);
+
+/* ── the socket ────────────────────────────────────────────────────────────────────────────────
+ * Opened LAZILY, and never in fixture mode: the fixture render must make no network call at all,
+ * which is what lets the comparator and no-network.test.js trust a fixture run. One socket for the
+ * page, shared by every terminal, reconnecting on a fixed 1.2s delay with the attach set cleared —
+ * so every visible terminal re-attaches and replays its ring buffer, exactly as before.
+ */
+const SOCK = {
+  ws: null, open: false, tries: 0,
+  sessions: [],                 // the server's session list, module-local on purpose (see below)
+  attached: new Set(),          // session ids this connection has attached
+  spawning: new Map(),          // tab id → true, while a `new` is in flight
+  spawnQueue: [],               // the SAME requests, in order — `created` carries no correlation id
+  timer: null,
+};
+
+/* The session heartbeat arrives about every 2s. It is deliberately NOT pushed through setState:
+ * a state change repaints all four panels, and repainting the window twice a second to redraw
+ * nothing would destroy text selection, scroll position and any in-flight edit. Nothing in this
+ * pane is rendered from the session list — it only decides which PTY a terminal is bound to — so
+ * the list stays here and the panels keep their own reads. */
+
+function connect() {
+  if (FIXTURE || SOCK.ws) return;
+  let ws;
+  try {
+    const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+    ws = new WebSocket(`${proto}://${location.host}`);
+  } catch { return; }
+  SOCK.ws = ws;
+  ws.onopen = () => {
+    SOCK.open = true; SOCK.tries = 0;
+    for (const rec of panes.values()) if (rec.kind === 'real') bind(rec);
+  };
+  ws.onclose = () => {
+    SOCK.open = false; SOCK.ws = null; SOCK.attached.clear();
+    /* An in-flight `new` is abandoned rather than retried: the server may well have started the
+     * session before the socket dropped, and the reconnect's `hello` will find it by name. Retrying
+     * blind is how a PM ends up with two shells and one tab. */
+    SOCK.spawning.clear(); SOCK.spawnQueue = [];
+    for (const rec of panes.values()) {
+      if (rec.kind !== 'real') continue;
+      rec.attachedId = null;
+      note(rec, 'pmos: connection to the workspace server lost — retrying');
+    }
+    clearTimeout(SOCK.timer);
+    SOCK.timer = setTimeout(connect, 1200);
+  };
+  ws.onerror = () => { /* onclose does the retrying */ };
+  ws.onmessage = (ev) => {
+    let m; try { m = JSON.parse(ev.data); } catch { return; }
+    handle(m);
+  };
+}
+
+function send(obj) {
+  if (SOCK.ws && SOCK.ws.readyState === 1) { SOCK.ws.send(JSON.stringify(obj)); return true; }
+  return false;
+}
+
+function handle(m) {
+  if (m.t === 'hello' || m.t === 'sessions') {
+    SOCK.sessions = Array.isArray(m.sessions) ? m.sessions : [];
+    if (m.t === 'hello' && Array.isArray(m.workspaces)) SOCK.workspaces = m.workspaces;
+    if (m.t === 'hello' && m.home) SOCK.home = m.home;
+    for (const rec of panes.values()) if (rec.kind === 'real') bind(rec);
+    return;
+  }
+  if (m.t === 'attached') {
+    const rec = recFor(m.id);
+    if (!rec) return;
+    rec.attachedId = m.id;
+    rec.noted = null;
+    try { rec.term.reset(); } catch { /* a disposed terminal */ }
+    if (m.buf) { try { rec.term.write(m.buf); } catch { /* ignore */ } }
+    refitVisible();
+    return;
+  }
+  if (m.t === 'data') {
+    const rec = recFor(m.id);
+    if (rec) { try { rec.term.write(m.data); } catch { /* ignore */ } }
+    return;
+  }
+  if (m.t === 'created') {
+    // `created` carries no correlation id, so the OLDEST outstanding request takes it. The server
+    // answers `new` in the order it received them, which makes the queue the correlation — matching
+    // by iteration order over the pane map would hand two simultaneous starts each other's shell.
+    const id = SOCK.spawnQueue.shift();
+    if (!id) return;
+    SOCK.spawning.delete(id);
+    const rec = panes.get(id);
+    if (!rec) { send({ t: 'detach', id: m.id }); return; }   // the tab closed while we waited
+    rec.sessionId = m.id;
+    attach(rec);
+    return;
+  }
+  if (m.t === 'error' || m.t === 'notice') {
+    const line = m.error ? 'pmos: ' + m.error : 'pmos: ' + m.notice;
+    const id = m.error ? SOCK.spawnQueue.shift() : SOCK.spawnQueue[0];
+    if (m.error && id) SOCK.spawning.delete(id);
+    const rec = id ? panes.get(id) : null;
+    if (rec) note(rec, line, true);
+    return;
+  }
+}
+
+const recFor = (sessionId) => {
+  for (const rec of panes.values()) if (rec.kind === 'real' && rec.sessionId === sessionId) return rec;
+  return null;
+};
+
+/* ── binding a tab to a real session ───────────────────────────────────────────────────────────
+ * The tab knows the initiative slug and the session NAME (`term:<slug>:<name>` is its id); the
+ * server knows session ids. The join is by name within the tab's workspace, which is the same join
+ * the sidebar has always made — a session's name is what the PM sees and what they named it.
+ * `sessionId` set on the tab by the data layer wins, when there is one.
+ */
+function resolveSessionId(tab) {
+  if (tab.sessionId) return tab.sessionId;
+  const pool = SOCK.sessions.length ? SOCK.sessions
+    : (Array.isArray(state.sessions) ? state.sessions : []);
+  const name = tab.sess;
+  if (!name) return null;
+  const byId = pool.find((s) => s && s.id === name);
+  if (byId) return byId.id;
+  const ws = workspaceId();
+  const inWs = pool.find((s) => s && s.name === name && (!ws || s.ws === ws));
+  if (inWs) return inWs.id;
+  const anywhere = pool.find((s) => s && s.name === name);
+  return anywhere ? anywhere.id : null;
+}
+
+/** The workspace a new session should start in: the selected repository when the server knows it. */
+function workspaceId() {
+  const known = Array.isArray(SOCK.workspaces) ? SOCK.workspaces.map((w) => w.id) : [];
+  // `state.wsId` FIRST — it is the workspace id the data layer published for the selected
+  // repository. `state.product` is the repository's NAME, and reading a name as an id was only ever
+  // harmless because it fails over to SOCK.home, which is right when exactly one repo is
+  // registered. With two, a terminal would be spawned in the home tree while the PM was looking at
+  // the other repository's board — a PTY in the wrong working tree, reported as if it were in the
+  // right one. Kept as a fallback so a fixture render with no data layer still resolves.
+  if (state.wsId && (!known.length || known.includes(state.wsId))) return state.wsId;
+  if (state.product && known.includes(state.product)) return state.product;
+  if (SOCK.home) return SOCK.home;
+  return known.length ? known[0] : null;
+}
+
+/**
+ * Was this session started in THIS window (the `＋ session` path)? Only then may a terminal spawn a
+ * PTY on its own: a tab opened against a session the board listed must attach to that session or
+ * say it is gone — silently starting a second shell with the same name would be a lie about what
+ * the PM is looking at.
+ */
+function startedHere(tab) {
+  const list = (state.extraSess || {})[tab.slug];
+  return Array.isArray(list) && list.some((s) => s && s.name === tab.sess);
+}
+
+function bind(rec) {
+  if (rec.kind !== 'real' || !rec.term) return;
+  const id = resolveSessionId(rec.tab);
+  if (id) {
+    if (rec.sessionId !== id) { rec.sessionId = id; rec.attachedId = null; }
+    attach(rec);
+    return;
+  }
+  if (!SOCK.open) { note(rec, 'pmos: connecting to the workspace server…'); return; }
+  if (SOCK.spawning.get(rec.tab.id)) return;
+  if (startedHere(rec.tab)) {
+    // agent 'shell' deliberately: PMOS cannot know which agent CLI the PM meant from a tab alone,
+    // and falling back from an agent to a shell after the fact would be the dishonest version.
+    SOCK.spawning.set(rec.tab.id, true);
+    SOCK.spawnQueue.push(rec.tab.id);
+    note(rec, 'pmos: starting a session…', true);
+    const ok = send({ t: 'new', name: rec.tab.sess, agent: 'shell', ws: workspaceId() });
+    if (!ok) {
+      SOCK.spawning.delete(rec.tab.id);
+      SOCK.spawnQueue = SOCK.spawnQueue.filter((x) => x !== rec.tab.id);
+    }
+    return;
+  }
+  note(rec, 'pmos: no live session named "' + rec.tab.sess + '" — nothing was attached');
+}
+
+function attach(rec) {
+  if (!rec.sessionId || !SOCK.open) return;
+  if (rec.attachedId === rec.sessionId && SOCK.attached.has(rec.sessionId)) return;
+  if (send({ t: 'attach', id: rec.sessionId })) SOCK.attached.add(rec.sessionId);
+}
+
+/** Write a status line into the terminal itself — once per distinct message, dimmed. */
+function note(rec, line, force) {
+  if (!rec.term) return;
+  if (!force && rec.noted === line) return;
+  rec.noted = line;
+  try { rec.term.write('\x1b[2m' + line + '\x1b[0m\r\n'); } catch { /* disposed */ }
+}
+
+/* ── refit ─────────────────────────────────────────────────────────────────────────────────────
+ * The single entry point. Coalesced into one animation frame so the six triggers below cost one
+ * measure per frame rather than six. A pane that is not in the document, or has no box yet, is
+ * skipped — fitting a zero-sized element is how a terminal ends up 1×1 and stays there.
+ */
+let refitQueued = false;
+
+export function refitVisible() {
+  if (refitQueued) return;
+  refitQueued = true;
+  const run = () => {
+    refitQueued = false;
+    for (const rec of panes.values()) {
+      if (rec.kind !== 'real' || !rec.fit || !rec.host) continue;
+      if (!rec.host.isConnected) continue;
+      if (!rec.host.offsetWidth || !rec.host.offsetHeight) continue;
+      try { rec.fit.fit(); } catch { /* a terminal mid-teardown */ }
+    }
+  };
+  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(run);
+  else setTimeout(run, 16);
+}
+
+/* Every event that can change a terminal's box. `subscribe` covers the three the PRD names —
+ * a tab being shown, the split toggling, a panel collapsing — because each of them is a state
+ * change, and the shell's render has already run by the time this subscriber does. */
+if (typeof window !== 'undefined') {
+  subscribe(() => refitVisible());
+  window.addEventListener('resize', () => refitVisible());
+  document.addEventListener('visibilitychange', () => { if (!document.hidden) refitVisible(); });
+  if (document.fonts && document.fonts.ready) document.fonts.ready.then(() => refitVisible()).catch(() => {});
+}
+
+/* ── fixture pane ──────────────────────────────────────────────────────────────────────────── */
+
+const SCROLL_STYLE = 'flex:1;overflow-y:auto;padding:14px 16px;font-family:var(--mono);font-size:12.5px;line-height:1.65;color:#c4ccce';
+const LINE_STYLE = (c) => 'color:' + c + ';white-space:pre-wrap;overflow-wrap:anywhere';
+const PROMPT_ROW_STYLE = 'display:flex;gap:8px;align-items:baseline';
+const PROMPT_STYLE = 'color:#47cf79;flex:none';
+const INPUT_STYLE = 'flex:1;min-width:0;font-family:var(--mono);font-size:12.5px;color:#f9fbfb;caret-color:#47cf79';
+const CARET_STYLE = 'width:8px;height:15px;background:#47cf79;animation:pmblink 1.1s step-end infinite;flex:none;align-self:center';
+
+/** The fake shell (lines 1993–2006). The command table itself lives in fixture.js. */
+function fauxKey(tab, e) {
+  if (e.key !== 'Enter') return;
+  const v = e.target.value.trim();
+  if (!v) return;
+  e.target.value = '';
+  const reply = FX.fauxShellReply(v, tab);
+  setState((s) => ({
+    termHist: {
+      ...s.termHist,
+      [tab.id]: v === 'clear' ? [] : [
+        ...(s.termHist[tab.id] || []),
+        FX.termEcho(v),
+        ...(reply ? [{ t: reply, c: FX.TERM_COLORS.text }] : []),
+      ],
+    },
+  }));
+}
+
+function buildFixture(tab) {
+  const input = el('input', { style: INPUT_STYLE, onKeyDown: (e) => fauxKey(rec.tab, e) });
+  const promptRow = el('div', { style: PROMPT_ROW_STYLE },
+    el('span', { style: PROMPT_STYLE }, 'root@vm:~/pmos$'),
+    input,
+    el('span', { style: CARET_STYLE }),
+  );
+  const scroll = el('div', { style: SCROLL_STYLE });
+  const rec = { kind: 'fixture', tab, scroll, promptRow, input, lines: [] };
+  return rec;
+}
+
+/**
+ * Paint the transcript: the five attach lines, then whatever the session has said since. Line
+ * nodes are REUSED rather than rebuilt — the prompt input sits in the same subtree and a rebuilt
+ * ancestor is a lost caret.
+ */
+function paintFixture(rec) {
+  const tab = rec.tab;
+  const lines = [...FX.termBaseLines(tab), ...((state.termHist || {})[tab.id] || [])];
+  while (rec.lines.length > lines.length) rec.lines.pop();
+  lines.forEach((ln, i) => {
+    let node = rec.lines[i];
+    if (!node) {
+      const value = el('span', null, ln.t);
+      node = el('div', { style: LINE_STYLE(ln.c) }, value);
+      node._value = value;
+      rec.lines[i] = node;
+      return;
+    }
+    const want = LINE_STYLE(ln.c);
+    if (node.getAttribute('style') !== want) node.setAttribute('style', want);
+    if (node._value.textContent !== ln.t) node._value.textContent = ln.t;
+  });
+  setChildren(rec.scroll, [...rec.lines, rec.promptRow]);
+}
+
+/* ── real pane ─────────────────────────────────────────────────────────────────────────────── */
+
+/* The CSS contract a live terminal needs, and the reason for each half of it:
+ *   WRAP  — `flex:1;min-height:0;position:relative;overflow:hidden`. It is the box the fit addon
+ *           measures, and it must be sized by the PANEL, never by the terminal inside it.
+ *   INNER — `position:absolute;inset:0`. Taking the terminal OUT OF FLOW is what breaks the loop:
+ *           in flow, the xterm's rendered height feeds the pane's automatic min-height, which
+ *           feeds the next fit, which adds rows — a terminal that grows a few thousand rows tall
+ *           on its own. Measured, not theorised: without `inset:0` this pane fit to 209 rows in a
+ *           900px window.
+ */
+const WRAP_STYLE = 'flex:1;min-height:0;position:relative;overflow:hidden;background:var(--term-bg)';
+const INNER_STYLE = 'position:absolute;inset:0;padding:14px 16px';
+const DEAD_STYLE = SCROLL_STYLE;
+
+/** The honest pane for a real-mode browser with no xterm on the page. */
+function buildDead(tab) {
+  const scroll = el('div', { style: DEAD_STYLE },
+    el('div', { style: LINE_STYLE(FX.TERM_COLORS.dim) },
+      el('span', null, 'pmos: the terminal engine did not load — /vendor/xterm.js was not served, '
+        + 'so nothing was attached. Run `npm install` in workspace/ and reload.')),
+  );
+  return { kind: 'dead', tab, scroll };
+}
+
+function buildReal(tab) {
+  const Terminal = XTERM();
+  if (!Terminal) return buildDead(tab);
+  const inner = el('div', { style: INNER_STYLE });
+  const host = el('div', { style: WRAP_STYLE }, inner);
+  const term = new Terminal({
+    fontFamily: '"IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+    fontSize: 12.5,
+    lineHeight: 1.65,
+    theme: xtheme(),
+    cursorBlink: true,
+    scrollback: 5000,
+    allowProposedApi: true,
+  });
+  const Fit = FIT();
+  let fit = null;
+  if (Fit) { fit = new Fit(); term.loadAddon(fit); }
+  const Links = LINKS();
+  if (Links) { try { term.loadAddon(new Links()); } catch { /* optional */ } }
+  term.open(inner);
+  // xterm sizes itself to its container only if the element it created fills it.
+  const xel = inner.querySelector('.xterm');
+  if (xel) { xel.style.height = '100%'; xel.style.width = '100%'; }
+
+  // ⌘K belongs to the shell's search, not to the PTY. Returning false stops xterm consuming the
+  // key; the event still bubbles to app.js's window listener, which is where the palette lives.
+  term.attachCustomKeyEventHandler((e) => !((e.metaKey || e.ctrlKey) && (e.key === 'k' || e.key === 'K')));
+
+  const rec = {
+    kind: 'real', tab, host, term, fit, sessionId: null, attachedId: null, noted: null, ro: null,
+  };
+  term.onData((d) => { if (rec.sessionId) send({ t: 'input', id: rec.sessionId, data: d }); });
+  term.onResize(({ cols, rows }) => {
+    if (rec.sessionId) send({ t: 'resize', id: rec.sessionId, cols, rows });
+  });
+  if (typeof ResizeObserver === 'function') {
+    rec.ro = new ResizeObserver(() => refitVisible());
+    try { rec.ro.observe(host); } catch { /* ignore */ }
+  }
+  return rec;
+}
+
+/* ── the exported surface ──────────────────────────────────────────────────────────────────── */
+
+/**
+ * Mount (or re-show) the terminal body of `tab` inside `host` — the pane element panel-tabs.js
+ * keeps for this tab's whole life. Idempotent: the first call builds, every later call re-paints
+ * the fixture transcript or re-fits the live terminal. It never rebuilds an xterm.
+ */
+export function mountTerm(host, tab) {
+  if (!host || !tab) return;
+  let rec = panes.get(tab.id);
+  if (!rec) {
+    rec = FIXTURE ? buildFixture(tab) : buildReal(tab);
+    panes.set(tab.id, rec);
+    if (rec.kind === 'real') connect();
+  }
+  rec.tab = tab;                       // the record is re-derived every render; the pane is not
+
+  if (rec.kind === 'fixture') {
+    paintFixture(rec);
+    setChildren(host, [rec.scroll]);
+    return;
+  }
+  if (rec.kind === 'dead') { setChildren(host, [rec.scroll]); return; }
+
+  setChildren(host, [rec.host]);
+  bind(rec);
+  refitVisible();                      // the tab was just shown — this is the fit that must happen
+}
+
+/**
+ * Release the terminal of a tab that has been CLOSED. The PTY is not killed: it is detached, so
+ * the session keeps running on the server and re-opening the tab (or reloading the page) picks it
+ * back up with its scrollback. Killing a session is the sidebar's explicit action, never a
+ * side effect of closing a view of it.
+ */
+export function disposeTerm(tab) {
+  const id = tab && (tab.id || tab);
+  const rec = panes.get(id);
+  if (!rec) return;
+  panes.delete(id);
+  SOCK.spawning.delete(id);
+  /* The queue entry STAYS: the server is still going to answer that `new`, and dropping the slot
+   * would let the next tab's `created` be handed the session this one asked for. `created` finds no
+   * pane for the id and detaches from the orphan instead. */
+  if (rec.kind !== 'real') return;
+  if (rec.ro) { try { rec.ro.disconnect(); } catch { /* ignore */ } }
+  if (rec.sessionId) {
+    send({ t: 'detach', id: rec.sessionId });
+    SOCK.attached.delete(rec.sessionId);
+  }
+  try { rec.term.dispose(); } catch { /* already gone */ }
+  if (rec.host && rec.host.parentNode) rec.host.parentNode.removeChild(rec.host);
+}
+
+/**
+ * Write text to a terminal as if it had been typed — the scratchpad's `⇥ send to terminal`.
+ * In fixture mode the transcript is panel-tabs.js's to append (it already did); here there is a
+ * PTY, and text that only appeared in a transcript would be text the shell never received.
+ */
+export function sendToTerm(tab, data) {
+  const rec = panes.get(tab && (tab.id || tab));
+  if (!rec || rec.kind !== 'real' || !rec.sessionId) return false;
+  return send({ t: 'input', id: rec.sessionId, data });
+}
+
+/** Focus the terminal of a tab, if it is live. */
+export function focusTerm(tab) {
+  const rec = panes.get(tab && (tab.id || tab));
+  if (rec && rec.kind === 'real') { try { rec.term.focus(); } catch { /* ignore */ } }
+}
+
+/* A read-only window into this module for the browser suite: cell geometry after a tab switch and
+ * a split is the assertion that guards the quiet PTY regression, and it cannot be read from the
+ * DOM alone. */
+export function termProbe() {
+  const out = {};
+  for (const [id, rec] of panes) {
+    out[id] = rec.kind === 'real'
+      ? { kind: 'real', cols: rec.term.cols, rows: rec.term.rows, sessionId: rec.sessionId,
+          attached: rec.attachedId === rec.sessionId && !!rec.sessionId,
+          width: rec.host.offsetWidth, height: rec.host.offsetHeight }
+      : { kind: rec.kind, lines: rec.lines ? rec.lines.length : 0 };
+  }
+  return out;
+}
+
+if (typeof window !== 'undefined') window.pmTerm = { refitVisible, termProbe, panes };
+
+export default mountTerm;

package/workspace/public/pm/tokens.css

@@ -0,0 +1,73 @@
+/* pm/tokens.css — the four-panel workspace token layer.
+ *
+ * The :root / [data-pm-theme="light"] blocks, the resets and the pmblink keyframe are copied
+ * VERBATIM from the design prototype. Do not "improve" a value here: the acceptance bar for this
+ * surface is a mechanical diff against that prototype, so an edit to a token is a defect.
+ *
+ * The faces are VENDORED (D62: the workspace is a local companion app that must render correctly
+ * with no network at all). The prototype linked Google Fonts; a CDN font is network egress and is
+ * forbidden here, so the same three IBM Plex Mono weights and the Space Grotesk variable face are
+ * declared against /vendor/. font-display:block matches the prototype's swap-free measurement —
+ * xterm measures its cell from whatever face is resolved at construction, and a swap mid-load
+ * leaves a terminal with a stale grid.
+ */
+
+@font-face {
+  font-family: "Space Grotesk";
+  src: url("/vendor/space-grotesk-var.woff2") format("woff2-variations");
+  font-weight: 300 700;
+  font-style: normal;
+  font-display: block;
+}
+@font-face {
+  font-family: "IBM Plex Mono";
+  src: url("/vendor/ibm-plex-mono-400.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: block;
+}
+@font-face {
+  font-family: "IBM Plex Mono";
+  src: url("/vendor/ibm-plex-mono-500.woff2") format("woff2");
+  font-weight: 500;
+  font-style: normal;
+  font-display: block;
+}
+@font-face {
+  font-family: "IBM Plex Mono";
+  src: url("/vendor/ibm-plex-mono-700.woff2") format("woff2");
+  font-weight: 700;
+  font-style: normal;
+  font-display: block;
+}
+
+:root{
+  --background:oklch(0.148 0.004 228.8);--foreground:oklch(0.987 0.002 197.1);
+  --card:oklch(0.218 0.008 223.9);--secondary:oklch(0.274 0.006 286.033);
+  --muted:oklch(0.275 0.011 216.9);--muted-foreground:oklch(0.723 0.014 214.4);
+  --accent:oklch(0.275 0.011 216.9);--border:oklch(1 0 0 / 10%);--input:oklch(1 0 0 / 15%);
+  --ring:oklch(0.56 0.021 213.5);--sidebar:oklch(0.218 0.008 223.9);
+  --brand:oklch(0.623 0.214 259.815);--brand-wash:color-mix(in oklab, oklch(0.623 0.214 259.815) 12%, transparent);
+  --success:oklch(0.76 0.17 152);--warning:oklch(0.82 0.15 82);--info:oklch(0.79 0.11 195);
+  --purple:oklch(0.72 0.15 300);--destructive:oklch(0.704 0.191 22.216);
+  --term-bg:oklch(0.148 0.004 228.8);
+  --mono:"IBM Plex Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+  --sans:"Space Grotesk",ui-sans-serif,system-ui,sans-serif;
+}
+[data-pm-theme="light"]{
+  --background:oklch(1 0 0);--foreground:oklch(0.148 0.004 228.8);
+  --card:oklch(1 0 0);--secondary:oklch(0.967 0.001 286.375);
+  --muted:oklch(0.963 0.002 197.1);--muted-foreground:oklch(0.56 0.021 213.5);
+  --accent:oklch(0.963 0.002 197.1);--border:oklch(0.925 0.005 214.3);--input:oklch(0.925 0.005 214.3);
+  --ring:oklch(0.723 0.014 214.4);--sidebar:oklch(0.987 0.002 197.1);
+  --brand:oklch(0.488 0.243 264.376);--brand-wash:color-mix(in oklab, oklch(0.488 0.243 264.376) 7%, transparent);
+  --success:oklch(0.52 0.14 152);--warning:oklch(0.55 0.12 72);--info:oklch(0.52 0.09 195);
+  --purple:oklch(0.5 0.2 300);--destructive:oklch(0.577 0.245 27.325);
+  --term-bg:oklch(0.148 0.004 228.8);
+}
+@keyframes pmblink{0%,49%{opacity:1}50%,100%{opacity:0}}
+*{box-sizing:border-box}
+body{margin:0;background:oklch(0.148 0.004 228.8);-webkit-font-smoothing:antialiased}
+a{color:oklch(0.623 0.214 259.815)}a:hover{color:oklch(0.72 0.19 259.8)}
+button{font:inherit;color:inherit;background:none;border:0;cursor:pointer;text-align:left;padding:0}
+input,textarea{font:inherit;color:inherit;background:none;border:0;outline:none;padding:0;resize:none}