create-pmos 0.15.0 → 0.16.0

package/workspace/public/pm/mobile.css

@@ -0,0 +1,200 @@
+/* pm/mobile.css — the ≤760px phone surface of the four-panel workspace.
+ *
+ * Built to the PM's mobile companion prototype (planning/design/four-panel/prototype-mobile.html):
+ * stack navigation rather than columns, a 52px / 1fr / 64px frame at most 430px wide, and a
+ * five-item bottom nav. Every colour here is either a token from pm/tokens.css or one of the two
+ * hard-coded bar inks the prototype uses for its chrome — the same two the desktop shell uses, so
+ * the top bar is the same ink on both surfaces.
+ *
+ * ── Why the phone frame is built out of `body` ────────────────────────────────────────────────
+ * pm/app.js appends ONE root element to <body> and gives it an inline `height:100vh` and its own
+ * three rows. The phone needs a different frame around the same element, and the one thing it must
+ * never do to get one is move anything: panel 4 holds a live xterm, and a re-parented terminal
+ * comes back with a stale grid. So <body> itself becomes the phone's grid — the static chrome in
+ * row 1 and row 3, app.js's untouched root in row 2 — and the root's own rows collapse to the one
+ * that matters. Nothing is moved, nothing is rebuilt; a media query changes which boxes are drawn.
+ *
+ * ── Why `!important` ──────────────────────────────────────────────────────────────────────────
+ * app.js writes its geometry as an inline `style` attribute, which is a deliberate part of its
+ * contract with the panel modules (the prototype's style strings are copied verbatim, so they can
+ * be diffed). An author-origin rule cannot beat an inline declaration without `!important`, and
+ * the alternative — a phone branch inside app.js's style strings — would put the breakpoint in two
+ * places at once. The overrides are confined to the media query, so the desktop cascade is exactly
+ * what it was.
+ *
+ * Sharp corners throughout: nothing here sets a border-radius.
+ */
+
+/* Above the breakpoint the phone chrome does not exist. `hidden` (set by pm/mobile.js) keeps it out
+ * of the accessibility tree as well — both, not either. */
+.mob, .mobmenu { display: none; }
+
+@media (max-width: 760px) {
+
+  /* The prototype's frame: 52px top bar, the screen, a 64px bottom nav, at most 430px wide and
+   * centred, with a hairline on each side so the phone shape is legible on a wide-ish tablet. */
+  body {
+    display: grid;
+    grid-template-rows: 52px minmax(0, 1fr) auto;
+    height: 100vh;
+    max-width: 430px;
+    margin: 0 auto;
+    overflow: hidden;
+    border-left: 1px solid var(--border);
+    border-right: 1px solid var(--border);
+  }
+
+  /* Explicit placement, never auto-placement: app.js appends its root LAST, so source order would
+   * put the screen underneath the bottom nav. */
+  .mob { display: block; grid-row: 1; min-width: 0; }
+  .mobmenu { display: block; grid-row: 3; min-width: 0; }
+
+  /* app.js's root, in row 2. Its 44px top bar and 26px status bar are the desktop's chrome and are
+   * replaced here by the phone's own — kept in the DOM (the shell suite indexes root.children) and
+   * simply not drawn, so the root is left with the single row that holds the panels. */
+  body > [data-pm-theme] {
+    grid-row: 2;
+    height: auto !important;
+    min-height: 0;
+    grid-template-rows: minmax(0, 1fr) !important;
+  }
+  body > [data-pm-theme] > *:first-child,
+  body > [data-pm-theme] > *:last-child { display: none; }
+
+  /* ONE panel at a time. `data-mpanel` carries the index pm/mobile.js derived from the reducer, and
+   * the rules below draw exactly that child of the body grid — which is the whole exclusivity
+   * guarantee, expressed as CSS rather than as something the reducer has to remember to enforce.
+   * The hidden panels keep their hosts mounted and their subtrees intact; a live terminal in panel
+   * 4 goes on running while the PM is reading the board. Each panel is restored to the `display` its
+   * own host was built with, because forcing them all to one value would relay their contents. */
+  body > [data-pm-theme] > *:nth-child(2) {
+    grid-template-columns: minmax(0, 1fr) !important;
+    min-height: 0;
+  }
+  [data-mpanel] > * { display: none !important; }
+  [data-mpanel="0"] > *:nth-child(1) { display: flex !important; }
+  [data-mpanel="1"] > *:nth-child(2) { display: block !important; }
+  [data-mpanel="2"] > *:nth-child(3) { display: flex !important; }
+  [data-mpanel="3"] > *:nth-child(4) { display: flex !important; }
+
+  /* ── the top bar ─────────────────────────────────────────────────────────────────────────── */
+
+  .mob-bar {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    height: 52px;
+    padding: 0 14px;
+    background: oklch(0.1 0.004 228.8);
+    color: oklch(0.987 0.002 197.1);
+    border-bottom: 1px solid oklch(1 0 0 / 10%);
+  }
+  /* 44px minimums on every control: the phone's targets are thumbs, not a pointer. */
+  .mob-back {
+    flex: none;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-width: 44px;
+    min-height: 44px;
+    margin-left: -6px;
+    color: oklch(0.85 0.01 214);
+    font-size: 14px;
+  }
+  .mob-brand {
+    flex: none;
+    display: grid;
+    place-items: center;
+    width: 26px;
+    height: 26px;
+    background: oklch(0.488 0.243 264.376);
+    font-size: 14px;
+    line-height: 1;
+  }
+  .mob-title {
+    flex: 1;
+    min-width: 0;
+    text-align: center;
+    font-family: var(--mono);
+    font-size: 12px;
+    color: oklch(0.85 0.01 214);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .mob-pal, .mob-theme {
+    flex: none;
+    display: grid;
+    place-items: center;
+    min-width: 44px;
+    min-height: 44px;
+    color: oklch(0.85 0.01 214);
+  }
+  .mob-pal { font-family: var(--mono); font-size: 12px; }
+  .mob-theme { font-size: 15px; }
+  .mob-back:active, .mob-pal:active, .mob-theme:active { color: oklch(0.987 0.002 197.1); }
+
+  /* ── the bottom block ────────────────────────────────────────────────────────────────────── */
+
+  .mobmenu {
+    background: oklch(0.1 0.004 228.8);
+    border-top: 1px solid oklch(1 0 0 / 10%);
+    /* viewport-fit=cover is on, so the home indicator's strip is ours to pad past. */
+    padding-bottom: env(safe-area-inset-bottom, 0px);
+  }
+
+  /* The control keys a phone keyboard does not have. Present on the terminal screen and on nothing
+   * else — the other screens have no PTY to write to, and a bar of inert keys is worse than none. */
+  .ctrlbar {
+    display: none;
+    min-width: 0;
+    gap: 5px;
+    padding: 6px 8px;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+    background: var(--muted);
+    border-bottom: 1px solid oklch(1 0 0 / 10%);
+  }
+  .mobmenu[data-view="terminal"] .ctrlbar { display: flex; }
+  .ctrlbar button {
+    flex: 1 0 auto;
+    display: grid;
+    place-items: center;
+    min-width: 44px;
+    min-height: 44px;
+    background: var(--secondary);
+    border: 1px solid var(--border);
+    color: var(--foreground);
+    font-family: var(--mono);
+    font-size: 14px;
+  }
+  .ctrlbar button:active { background: var(--accent); }
+  .ctrlbar button[aria-pressed="true"] {
+    border-color: var(--brand);
+    color: var(--brand);
+    background: var(--brand-wash);
+  }
+  .ctrlbar .lbl { font-size: 11px; letter-spacing: .04em; }
+
+  /* Five destinations, one per column, 64px tall — the prototype's bottom nav. */
+  .mobnav { display: grid; grid-template-columns: repeat(5, 1fr); min-width: 0; }
+  .mobnav-b {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 3px;
+    min-width: 0;
+    min-height: 64px;
+    padding: 0 2px;
+    color: oklch(0.6 0.02 213);
+  }
+  .mobnav-b .g { font-size: 17px; line-height: 1; }
+  .mobnav-b .l { font-size: 10px; line-height: 1; }
+  .mobnav-b[aria-current="page"] { color: oklch(0.987 0.002 197.1); }
+}
+
+/* `hidden` wins over every display above, in both directions of the breakpoint. Back is ABSENT at a
+ * destination root rather than present-and-inert: a control that looks available and does nothing is
+ * the thing this workspace refuses to ship. */
+.mob[hidden], .mobmenu[hidden], .mob-back[hidden], .mob-brand[hidden] { display: none !important; }

package/workspace/public/pm/mobile.js

@@ -0,0 +1,403 @@
+/* pm/mobile.js — the phone surface of the four-panel workspace (≤760px).
+ *
+ * Owns three things and nothing else: the top bar (back · the screen's name · the ⌘K jump palette ·
+ * theme), the five-destination bottom nav, and the terminal control-key accessory bar that writes
+ * real PTY sequences. Its markup ships in public/index.html; its styling in pm/mobile.css.
+ *
+ * ── ONE renderer, two shells ──────────────────────────────────────────────────────────────────
+ * Nothing here draws a phone-shaped copy of a panel. The four panel modules render exactly what
+ * they render on a desktop; this module decides which ONE of their hosts is drawn, and dresses the
+ * chrome around it. That is deliberate: a second implementation of a list is a second thing to keep
+ * correct, and the failure it produces — a phone showing a stale shape of the truth — is invisible
+ * from a desktop.
+ *
+ * ── The terminal must not die ────────────────────────────────────────────────────────────────
+ * Panel 4 hosts a live xterm bound to a PTY. Switching screens therefore NEVER re-parents, removes
+ * or rebuilds a host: every one of the four stays mounted in the body grid and `data-mpanel` picks
+ * which is displayed (pm/mobile.css). A terminal the PM navigated away from keeps running, keeps
+ * its scrollback, and is still there when they come back — because it never moved.
+ *
+ * ── Navigation is the reducer's, not this file's ─────────────────────────────────────────────
+ * `lib/mobile-nav.js` (window.PMOSMobileNav, loaded as a classic script from index.html) is the
+ * source of truth for the destinations, the stack, the titles and the screen→panel mapping. It is
+ * DOM-free and walked in node by test.js, which is the whole reason it lives outside this file. If
+ * it is missing, the phone surface stays down rather than half-navigating with a local copy — a
+ * duplicated reducer is exactly the drift extracting it was meant to stop.
+ *
+ * ── How depth is detected ────────────────────────────────────────────────────────────────────
+ * The panel modules do not know a phone exists; they call `setState` the way they do on a desktop.
+ * So this module watches the fields that MEAN "you went somewhere" — the selected initiative, the
+ * detail record, the active tab, the mode — and pushes the matching screen. A change this module
+ * caused itself is marked and skipped, so tapping a destination cannot be read back as the PM
+ * navigating into one.
+ */
+
+import { state, setState, writeCount, FIXTURE } from './state.js';
+
+/* ── the breakpoint ─────────────────────────────────────────────────────────────────────────── */
+
+const MQ = window.matchMedia('(max-width:760px)');
+
+/** True when the phone surface is the one that should be on screen. */
+export function isMobile() { return MQ.matches; }
+
+/* ── the reducer, and the fallbacks it does NOT get ─────────────────────────────────────────── */
+
+const NAV = window.PMOSMobileNav || null;
+if (!NAV) {
+  console.error('[pm] /lib/mobile-nav.js did not load — the phone surface is disabled. '
+    + 'index.html must load it before the module graph.');
+}
+
+/** kind → which of the four panels draws it. The reducer owns the map; this is only its fallback. */
+const PANEL = { more: 0, list: 1, detail: 2, terminal: 3, doc: 3 };
+const panelOf = (kind) =>
+  (NAV && typeof NAV.panelOf === 'function') ? NAV.panelOf(kind)
+    : (Object.prototype.hasOwnProperty.call(PANEL, kind) ? PANEL[kind] : 1);
+
+/* A destination's root list is a MODE. `more` has none: its root is the structure panel itself,
+ * which is where the repositories, the workflows, the skills, the knowledge and the connections
+ * are reached from — the phone's "more" and the desktop's panel 1 are the same surface. */
+const DEST_MODE = { board: 'product', scheduled: 'scheduled', agents: 'agent', memory: 'memory' };
+/* Two modes postdate the reducer's map (`connect` and `focus` arrived with the four-panel design).
+ * They are named here rather than added to `DEST_FOR_MODE`, because MOBNAV-P7 pins that map to the
+ * retired app.js's MODES exactly and a mode invented for a different surface would read as drift. */
+const EXTRA_DEST = { connect: 'more', focus: 'board' };
+
+const destForMode = (m) => (NAV && NAV.destForMode(m)) || EXTRA_DEST[m] || null;
+
+/* ── module state ───────────────────────────────────────────────────────────────────────────── */
+
+const $ = (id) => document.getElementById(id);
+
+const DEST_STORE_KEY = 'pmos.workspace.pm.mdest';
+
+let ctx = null;          // { bodyGrid, render } — handed over by app.js at boot
+let nav = null;          // the reducer's state
+let seen = null;         // the app-state fingerprint the last screen was derived from
+let selfDriven = false;  // the next state change is one this module caused — do not read it as navigation
+let ctrlArmed = false;   // the control bar's one-shot Ctrl
+
+/* R11 — the DESTINATION is remembered across reloads; the deeper stack deliberately is not. A
+ * pushed screen names a record that may no longer exist, and restoring it would mean drawing a
+ * screen for something PMOS has not re-read. Fixture mode reads and writes nothing, so a
+ * comparator run is deterministic. */
+function readDest() {
+  if (FIXTURE) return null;
+  try { return localStorage.getItem(DEST_STORE_KEY); } catch { return null; }
+}
+function writeDest(d) {
+  if (FIXTURE) return;
+  try { localStorage.setItem(DEST_STORE_KEY, d); } catch { /* quota / private mode */ }
+}
+
+/* ── writing to the PTY ─────────────────────────────────────────────────────────────────────── */
+
+const SEQ = { esc: '\x1b', tab: '\t', up: '\x1b[A', down: '\x1b[B', left: '\x1b[D', right: '\x1b[C' };
+
+/* Keyboard identities for the last-resort path below. xterm turns a keydown into the same bytes
+ * `SEQ` holds, so the two routes cannot disagree about what "up" means. */
+const KEYDOWN = {
+  esc: { key: 'Escape', code: 'Escape', keyCode: 27 },
+  tab: { key: 'Tab', code: 'Tab', keyCode: 9 },
+  up: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
+  down: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
+  left: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
+  right: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },
+};
+
+/** The terminal panel's own send hook, if it publishes one. */
+function termApi() {
+  const t = window.pmTerm;
+  if (t && typeof t.send === 'function') return t;
+  const mods = window.pmApp && window.pmApp.mods;
+  const tabs = mods && mods.tabs;
+  if (tabs && typeof tabs.sendInput === 'function') return { send: tabs.sendInput, focus: tabs.focusTerm };
+  return null;
+}
+
+/** The live xterm instance for the active tab, however the terminal panel publishes it. */
+function activeTerm() {
+  const id = state.active;
+  const maps = [window.pmTerms, window.pmApp && window.pmApp.terms];
+  for (const m of maps) {
+    if (!m) continue;
+    const rec = typeof m.get === 'function' ? m.get(id) : m[id];
+    const term = rec && (rec.term || rec);
+    if (term && typeof term.input === 'function') return term;
+  }
+  return null;
+}
+
+/**
+ * Send a raw sequence to the active PTY, then put focus back in the terminal so the soft keyboard
+ * stays up. Four routes, most direct first; the last one exists because panel-tabs.js may not be
+ * written yet and a control bar that silently does nothing is worse than one that is absent.
+ */
+function sendSeq(name) {
+  const data = SEQ[name];
+  if (!data) return false;
+  const api = termApi();
+  if (api) { api.send(data); if (typeof api.focus === 'function') api.focus(); return true; }
+  const term = activeTerm();
+  if (term) { term.input(data, true); if (typeof term.focus === 'function') term.focus(); return true; }
+  // Last resort: xterm's own hidden textarea. Its keydown handler produces the sequence and emits
+  // it through onData, so whatever the terminal panel wired to onData is what carries it to the PTY.
+  const ta = document.querySelector('.xterm-helper-textarea');
+  const k = KEYDOWN[name];
+  if (!ta || !k) return false;
+  ta.focus();
+  ta.dispatchEvent(new KeyboardEvent('keydown', { ...k, bubbles: true, cancelable: true }));
+  return true;
+}
+
+/** Arm/disarm the one-shot Ctrl modifier and say so on the button. */
+function setCtrlArmed(on) {
+  ctrlArmed = !!on;
+  const b = $('ctrlKey');
+  if (b) b.setAttribute('aria-pressed', String(ctrlArmed));
+  window.pmMobileCtrl = { armed: ctrlArmed, apply: applyCtrl };
+}
+
+/**
+ * The Ctrl transform, exposed so the terminal panel can apply it inside its own `onData` if it
+ * prefers. Ctrl is a ONE-SHOT: the next character becomes its control code and Ctrl disarms.
+ */
+export function applyCtrl(d) {
+  if (!ctrlArmed) return d;
+  setCtrlArmed(false);
+  if (d.length === 1) {
+    const c = d.charCodeAt(0);
+    if (c >= 97 && c <= 122) return String.fromCharCode(c - 96);   // a–z → 0x01–0x1a
+    if (c >= 65 && c <= 90) return String.fromCharCode(c - 64);    // A–Z → 0x01–0x1a
+    if (c >= 91 && c <= 95) return String.fromCharCode(c - 64);    // [ \ ] ^ _ → 0x1b–0x1f
+    if (c === 32) return '\x00';                                    // Ctrl-Space → NUL
+  }
+  return d;
+}
+
+/* Armed Ctrl, applied here as well as offered above: the soft keyboard's next printable key is
+ * intercepted in the capture phase before xterm sees it, converted, and written straight out. This
+ * is what makes Ctrl-C work on a phone whether or not the terminal panel knows this module exists. */
+function onCaptureKeyDown(e) {
+  if (!ctrlArmed || !isMobile()) return;
+  if (e.metaKey || e.ctrlKey || e.altKey) return;
+  if (typeof e.key !== 'string' || e.key.length !== 1) return;
+  const target = e.target;
+  if (!target || !target.closest || !target.closest('.xterm')) return;
+  const out = applyCtrl(e.key);
+  if (out === e.key) return;
+  e.preventDefault();
+  e.stopPropagation();
+  const api = termApi();
+  if (api) { api.send(out); return; }
+  const term = activeTerm();
+  if (term) term.input(out, true);
+}
+
+/* ── deriving the screen from the app's own state ───────────────────────────────────────────── */
+
+function fingerprint() {
+  const d = state.detail || {};
+  return {
+    mode: state.mode,
+    sel: state.sel,
+    detail: String(d.kind || '') + '|' + String(d.id || ''),
+    active: state.active,
+    /* Selecting the tab that is ALREADY active is still "show me this tab" — and on a phone the
+     * PM may be looking at the board while that tab is the active one, so the request moves the
+     * screen even though the value does not move. The counter is state.js's write log; watching
+     * the value alone is what left the terminal screen unreachable once you had navigated off it. */
+    activeAsk: writeCount('active'),
+  };
+}
+
+/** Push a screen, replacing rather than stacking when it is the same kind as the current one. */
+function go(screen) {
+  const cur = NAV.current(nav);
+  const base = (nav.stack.length && cur.kind === screen.kind) ? NAV.pop(nav) : nav;
+  nav = NAV.push(base, screen);
+}
+
+/**
+ * Read the app's state for a navigation the PM made through a panel, and push the screen it means.
+ * Exactly one transition is taken per render, most specific first: opening a session is a terminal
+ * screen even though it also changes the selection.
+ */
+function syncFromState() {
+  const cur = fingerprint();
+  if (!seen || selfDriven) { selfDriven = false; seen = cur; return; }
+
+  if (cur.active && (cur.active !== seen.active || cur.activeAsk !== seen.activeAsk)) {
+    const tab = (state.tabs || []).find((t) => t && t.id === cur.active);
+    go({ kind: (tab && tab.kind === 'doc') ? 'doc' : 'terminal', id: cur.active, title: (tab && (tab.title || tab.name)) || String(cur.active) });
+  } else if (cur.detail !== seen.detail || (cur.sel && cur.sel !== seen.sel)) {
+    const dk = (state.detail && state.detail.kind) || '';
+    if (dk && dk !== 'none') go({ kind: 'detail', dk, id: (state.detail && state.detail.id) || cur.sel });
+  } else if (cur.mode !== seen.mode) {
+    const dest = destForMode(cur.mode);
+    if (dest && DEST_MODE[dest] === cur.mode) {
+      nav = NAV.switchDest(nav, dest);
+      writeDest(nav.dest);
+    } else {
+      if (dest && dest !== nav.dest) nav = NAV.switchDest(nav, dest);
+      go({ kind: 'list', mode: cur.mode });
+    }
+  }
+  seen = cur;
+}
+
+/* ── applying it ────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Bring the chrome and the visible panel in line with the current screen. Called at the end of
+ * every shell render, and on every breakpoint change.
+ */
+export function applyMobile() {
+  const shell = $('mobShell');
+  const menu = $('mobMenu');
+  const on = isMobile() && !!NAV && !!ctx;
+
+  // R12 — above the breakpoint the chrome is `display:none` (stylesheet) AND `hidden` (here), so it
+  // is absent from the accessibility tree rather than merely invisible. Both, not either.
+  if (shell) shell.hidden = !on;
+  if (menu) menu.hidden = !on;
+  if (!on) {
+    if (ctx) ctx.bodyGrid.removeAttribute('data-mpanel');
+    if (ctrlArmed) setCtrlArmed(false);
+    return;
+  }
+
+  if (!nav) nav = NAV.init(NAV.migrateView(readDest()));
+  syncFromState();
+
+  const s = NAV.current(nav);
+
+  // The host is chosen FIRST, so a renderer that measures itself (the terminal's fit) sees the box
+  // it is actually going to occupy rather than the one it is leaving.
+  ctx.bodyGrid.dataset.mpanel = String(panelOf(s.kind));
+  if (menu) menu.dataset.view = s.kind;
+
+  const title = $('mobTitle');
+  if (title) title.textContent = NAV.titleOf(s) || '';
+
+  const deep = nav.stack.length > 0;
+  const back = $('mobBack');
+  if (back) back.hidden = !deep;          // absent at a destination root, never present-and-inert
+  const brand = $('mobBrand');
+  if (brand) brand.hidden = deep;         // the lockup yields to the back control, as the design has it
+
+  const theme = $('mobTheme');
+  if (theme) theme.textContent = state.theme === 'dark' ? '◐' : '◑';
+
+  const buttons = menu ? menu.querySelectorAll('#mobNav [data-dest]') : [];
+  for (const b of buttons) b.setAttribute('aria-current', b.dataset.dest === nav.dest ? 'page' : 'false');
+
+  if (s.kind !== 'terminal' && ctrlArmed) setCtrlArmed(false);
+}
+
+/* ── the chrome's own controls ──────────────────────────────────────────────────────────────── */
+
+/** Choose a destination: reset it to its root and put the app in the mode that root shows. */
+function setDest(dest) {
+  nav = NAV.switchDest(nav, dest);
+  writeDest(nav.dest);
+  const mode = DEST_MODE[dest];
+  selfDriven = true;
+  setState(mode ? { mode, settingsOpen: false } : { settingsOpen: false });
+}
+
+/** Back: pop exactly one screen and put the app back in the state that screen describes. */
+function goBack() {
+  nav = NAV.pop(nav);
+  const s = NAV.current(nav);
+  selfDriven = true;
+  setState(s.kind === 'list' && s.mode ? { mode: s.mode } : {});
+}
+
+/** The shell's own ⌘K target — panel 2's search input, wherever that panel decided to put it. */
+function focusSearch() {
+  const input = document.querySelector('[data-pm-search]')
+    || document.querySelector('input[placeholder="search everything…"]');
+  if (input) input.focus();
+}
+
+/**
+ * The jump palette. It is a jump control for EVERY destination, so it lives in the always-visible
+ * top bar; the control bar below scrolls, and a control that scrolls out of view at 390px is the
+ * hover-only trap in another costume. Search lives in panel 2, so the palette makes sure a list
+ * screen is the one on screen before it hands focus over.
+ */
+function openPalette() {
+  if (NAV.current(nav).kind !== 'list') go({ kind: 'list', mode: state.mode });
+  selfDriven = true;
+  setState({ col1: true }, focusSearch);
+}
+
+/** The phone's theme control drives the same state as the desktop's, so the two cannot disagree. */
+function toggleTheme() {
+  selfDriven = true;
+  setState((s) => ({ theme: s.theme === 'dark' ? 'light' : 'dark' }));
+}
+
+/* The terminal has to re-measure when the soft keyboard shows or hides and after a rotation, or
+ * xterm keeps the row count it had and the bottom of the session is clipped. The fit itself belongs
+ * to the terminal panel; this only tells it that the box changed. */
+function refit() {
+  const t = window.pmTerm;
+  if (t && typeof t.fit === 'function') { try { t.fit(); return; } catch { /* fall through */ } }
+  window.dispatchEvent(new Event('resize'));
+}
+
+/* ── mount ──────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Wire the phone chrome up, once, at boot.
+ * `context` is `{ bodyGrid, render }` — the body grid whose children are the four panel hosts, and
+ * the shell's render function, so a breakpoint change can repaint the panels the phone needs.
+ */
+export function mountMobile(context) {
+  ctx = context || null;
+  if (!ctx || !ctx.bodyGrid || !NAV) return;
+
+  for (const b of document.querySelectorAll('#ctrlBar [data-seq]')) {
+    b.addEventListener('click', () => sendSeq(b.dataset.seq));
+  }
+  const ctrl = $('ctrlKey');
+  if (ctrl) ctrl.addEventListener('click', () => setCtrlArmed(!ctrlArmed));
+  window.addEventListener('keydown', onCaptureKeyDown, true);
+
+  for (const b of document.querySelectorAll('#mobNav [data-dest]')) {
+    b.addEventListener('click', () => setDest(b.dataset.dest));
+  }
+  const back = $('mobBack');
+  if (back) back.addEventListener('click', goBack);
+  const pal = $('mobPalette');
+  if (pal) pal.addEventListener('click', openPalette);
+  const theme = $('mobTheme');
+  if (theme) theme.addEventListener('click', toggleTheme);
+
+  if (window.visualViewport) {
+    window.visualViewport.addEventListener('resize', refit);
+    window.visualViewport.addEventListener('scroll', refit);
+  }
+  window.addEventListener('orientationchange', () => setTimeout(refit, 250));
+
+  // Crossing the breakpoint (rotate a tablet, drag a window narrow) has to re-decide whether the
+  // phone shell exists at all AND repaint the panels — a shell left mounted above 760px is a second
+  // navigation system on the desktop, and panels left unpainted below it are three empty screens.
+  const onMQ = () => {
+    if (isMobile()) nav = nav || NAV.init(NAV.migrateView(readDest()));
+    if (ctx && typeof ctx.render === 'function') ctx.render();
+    else applyMobile();
+    refit();
+  };
+  if (MQ.addEventListener) MQ.addEventListener('change', onMQ);
+  else if (MQ.addListener) MQ.addListener(onMQ);
+
+  setCtrlArmed(false);
+}
+
+/* A small surface for the browser suite, mirroring window.pmApp. Read-only in spirit: everything
+ * here is either a pure function or a snapshot. */
+window.pmMobile = { isMobile, applyMobile, applyCtrl, SEQ, panelOf, nav: () => nav };