create-pmos 0.55.5 → 0.57.0

package/workspace/public/pm/dest-docs.js

@@ -0,0 +1,405 @@
+/* pm/dest-docs.js — the Docs destination: is each document the same as its Google Docs and Confluence copy, and use
+ * one version over the other on the PM's press (initiative docs-three-way-sync, PRD R-D1 to R-D6 and R-F1 to R-F4).
+ *
+ * A DESTINATION MODULE (registry.js): mountDestination(host, ctx) on every render with the same host, disposeDestination(host).
+ * It keeps ONE persistent root per host; the header (title and search) is built once, so typing never loses focus, and
+ * only the body is rebuilt when its own data changed.
+ *
+ * What it shows, for the repository the tab names (or the open one):
+ *   - Docs, a search box, Needs you · All, and when the copies were last compared, with a control that compares again;
+ *   - the copies grouped by initiative, ONE line per copy: a status dot, the title, a link that opens the copy, one
+ *     sentence (which side is newer, and who edited it last) and at most one button (Use PMOS version, Use Confluence
+ *     version, or Choose… when both changed);
+ *   - a click on a line: both sides with where they live and their last edit, a Use … version button for each, the first
+ *     difference the check saw, Compare again and Stop tracking this copy;
+ *   - search: every markdown file that matches; a file without a copy offers Add copy, in place.
+ * The signal is decided on the server (lib/doc-sync.js) from what a check session read. Nothing here reads or writes
+ * Google Docs or Confluence. Use … version waits five seconds behind Undo, then asks the server to start ONE doc-sync
+ * session for that copy, which writes one side with the PM's own connectors (the PM's ruling, amended 2026-10-06).
+ * In fixture mode it reads nothing.
+ */
+
+import { el } from './dom.js';
+import { button, row, field, toast, empty, tabs, ensureComponentsCss } from './primitives.js';
+import { ensureSprite } from './icons.js';
+import { pmGet, pmPost } from './http.js';
+import { wsOf } from './data.js';
+import { registerCommand, openDestination } from './registry.js';
+
+const LABEL = { google: 'Google Docs', confluence: 'Confluence' };
+const UNDO_MS = 5000;
+
+export const COPY = Object.freeze({
+  title: 'Docs',
+  fixture: 'Docs shows linked documents in a real session.',
+  noRepo: 'Open a repository to see its documents.',
+  loading: 'Reading…',
+  readError: 'The documents could not be read.',
+  find: 'Find a document',
+  needs: 'Needs you',
+  all: 'All',
+  compared: (iso) => 'Compared ' + ago(iso),
+  never: 'Not compared yet',
+  comparing: 'Comparing…',
+  compareAll: 'Compare every copy again',
+  none: 'No document has a copy yet. Find a document above and press Add copy.',
+  nothingNeeds: 'Nothing needs you. Every copy matches PMOS.',
+  noMatch: (q) => `No document matches “${q}”.`,
+  other: 'Other',
+  usePmos: 'Use PMOS version',
+  useCopy: (label) => `Use ${label} version`,
+  choose: 'Choose…',
+  noCopy: 'No copy',
+  addCopy: 'Add copy',
+  add: 'Add',
+  cancel: 'Cancel',
+  paste: 'Paste a Google Docs or Confluence link',
+  badPaste: 'Paste the address of a Google Doc or a Confluence page.',
+  added: 'Copy added. Compare to see which side is newer.',
+  compareAgain: 'Compare again',
+  stop: 'Stop tracking this copy',
+  stopped: (label) => `Stopped tracking the ${label} copy. Nothing was deleted.`,
+  undo: 'Undo',
+  pushing: (label) => `Updating ${label} with the PMOS version.`,
+  pulling: (label) => `Updating PMOS with the ${label} version.`,
+  cancelled: 'Nothing was changed.',
+  started: 'Compare started. It reads every copy and changes nothing.',
+});
+
+// Docs is not in the top bar (the bar holds at most 7 controls); ⌘K and `g d` open it.
+registerCommand({ id: 'docs-open', label: 'Docs', hint: 'Is each document the same as its Google Docs and Confluence copy', cli: 'pmos docs list', run: () => openDestination('docs') });
+
+/* ── words ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function ago(iso) {
+  if (!iso) return 'never';
+  const m = Math.round((Date.now() - Date.parse(iso)) / 60000);
+  if (m < 1) return 'just now';
+  if (m < 60) return `${m} min ago`;
+  if (m < 48 * 60) return `${Math.round(m / 60)} h ago`;
+  return `${Math.round(m / 1440)} days ago`;
+}
+/** "today 09:12", "yesterday 17:55", "Mon 14:05", "Sep 30". */
+function when(iso) {
+  const t = new Date(iso);
+  if (Number.isNaN(t.getTime())) return '';
+  const hm = t.toTimeString().slice(0, 5);
+  const day = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+  const days = Math.round((day(new Date()) - day(t)) / 86400000);
+  if (days === 0) return 'today ' + hm;
+  if (days === 1) return 'yesterday ' + hm;
+  if (days > 1 && days < 7) return t.toLocaleDateString('en-US', { weekday: 'short' }) + ' ' + hm;
+  return t.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+}
+const edit = (by, at) => [by, at ? when(at) : null].filter(Boolean).join(', ');
+const keyOf = (doc, link) => `${doc.path}|${link.kind}`;
+/** Which kind a pasted address names. The server checks it again; this only picks the kind. */
+function kindOf(target) {
+  const t = String(target || '');
+  if (/atlassian|confluence|\/wiki\/|pageId=/i.test(t)) return 'confluence';
+  if (/google|docs\.|drive\./i.test(t)) return 'google';
+  return null;
+}
+
+/** One dot, one sentence and at most one button per copy. The newer side's last edit is the only detail on the line. */
+function stateOf(inst, doc, link) {
+  const L = link.label || LABEL[link.kind];
+  const pend = inst.pending.get(keyOf(doc, link));
+  const syncing = link.syncing || (pend ? { use: pend.use } : null);
+  if (syncing) return { dot: 'none', strong: syncing.use === 'pmos' ? `Updating ${L}…` : `Updating PMOS from ${L}…` };
+  const by = (s) => (link.basis === 'date' ? s + ' · by date' : s);
+  let st;
+  switch (link.signal) {
+    case 'same': st = { dot: 'ok', rest: 'Same' }; break;
+    case 'ahead': st = { dot: 'warn', strong: 'PMOS is newer', rest: by(edit(doc.repo && doc.repo.modified_by, doc.repo && doc.repo.modified_at)), btn: 'pmos' }; break;
+    case 'behind': st = { dot: 'warn', strong: `${L} is newer`, rest: by(edit(link.remote_modified_by, link.remote_modified_at)), btn: 'copy' }; break;
+    case 'diverged': st = { dot: 'bad', strong: 'Edited on both sides', btn: 'choose' }; break;
+    case 'unchecked': st = { dot: 'none', rest: COPY.never }; break;
+    case 'unreadable': st = { dot: 'bad', strong: `Can't open in ${L}`, rest: String(link.words || '').replace(/^Could not check — /, '') }; break;
+    case 'missing-remote': st = { dot: 'bad', strong: `Not found in ${L}` }; break;
+    case 'missing-repo': st = { dot: 'bad', strong: 'Not in PMOS any more' }; break;
+    default: st = { dot: 'none', rest: link.words || '' };
+  }
+  if (link.sync_failed) return { ...st, dot: 'bad', strong: 'Sync failed', rest: link.sync_failed.reason };
+  return st;
+}
+
+/* ── mount ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+const insts = new WeakMap();
+const REREAD_MS = 5000;
+
+export function mountDestination(host, ctx) {
+  let inst = insts.get(host);
+  if (!inst) {
+    inst = { host, root: el('div', { class: 'rp-page rp-docs', 'data-docs': '' }), head: null, body: el('div', { class: 'rp-docs-body' }),
+      ws: null, loaded: false, error: null, view: null, filter: 'needs', q: '', files: [], open: null, adding: null,
+      pending: new Map(), busy: false, seq: 0, fseq: 0, last: '', timer: null, ftimer: null };
+    insts.set(host, inst);
+  }
+  ensureComponentsCss();
+  if (!inst.root.isConnected || inst.root.parentNode !== host) host.replaceChildren(inst.root);
+  if (ctx && ctx.FIXTURE) { inst.root.replaceChildren(empty({ text: COPY.fixture })); return; }
+  const repo = (ctx && ctx.tab && ctx.tab.repo) || (ctx && ctx.state && ctx.state.product) || null;
+  const ws = repo ? wsOf(repo) : null;
+  if (ws !== inst.ws) {
+    stopPoll(inst);
+    Object.assign(inst, { ws, loaded: false, error: null, view: null, last: '', open: null, adding: null, files: [] });
+    if (ws) { ensureSprite(); refresh(inst); }
+    draw(inst);
+    return;
+  }
+  // Coming back to Docs reads again (at most every few seconds): a file edited since shows its new signal.
+  if (Date.now() - (inst.readAt || 0) > REREAD_MS) refresh(inst);
+  if (!inst.last) draw(inst);
+}
+
+export function disposeDestination(host) {
+  const inst = insts.get(host);
+  if (!inst) return;
+  stopPoll(inst);
+  inst.seq++;
+  inst.root.remove();
+  insts.delete(host);
+}
+
+function stopPoll(inst) { if (inst.timer) { clearInterval(inst.timer); inst.timer = null; } }
+/** While a compare or a sync runs, read again every few seconds so its result lands without a reload; stop when it ends. */
+function pollWhileRunning(inst) {
+  const v = inst.view;
+  const running = v && (v.open || v.session || v.docs.some((d) => d.links.some((l) => l.syncing)));
+  if (running && !inst.timer) inst.timer = setInterval(() => refresh(inst), 4000);
+  if (!running) stopPoll(inst);
+}
+
+async function refresh(inst) {
+  const ws = inst.ws;
+  if (!ws) return;
+  const seq = ++inst.seq;
+  inst.readAt = Date.now();
+  const v = await pmGet('/api/docs?ws=' + encodeURIComponent(ws));
+  if (seq !== inst.seq || ws !== inst.ws) return;
+  inst.loaded = true;
+  if (!v || v.ok === false) { inst.error = (v && v.error) || COPY.readError; inst.view = null; }
+  else { inst.error = null; inst.view = v; }
+  pollWhileRunning(inst);
+  draw(inst);
+}
+
+/** The repository's files that match the search and have no copy yet: what Add copy is offered on. */
+function searchFiles(inst) {
+  if (inst.ftimer) clearTimeout(inst.ftimer);
+  const q = inst.q.trim();
+  if (!q) { inst.files = []; return; }
+  inst.ftimer = setTimeout(async () => {
+    const seq = ++inst.fseq;
+    const r = await pmGet('/api/docs/files?ws=' + encodeURIComponent(inst.ws) + '&q=' + encodeURIComponent(q));
+    if (seq !== inst.fseq || q !== inst.q.trim()) return;
+    inst.files = (r && r.ok && r.files) || [];
+    draw(inst);
+  }, 200);
+}
+
+/* ── actions ─────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+async function compareAll(inst) {
+  inst.busy = true; draw(inst);
+  const r = await pmPost('/api/docs/check', { ws: inst.ws });
+  inst.busy = false;
+  if (r && r.ok) toast({ text: COPY.started, timeout: 4000 });
+  else toast({ text: (r && r.error) || 'The compare could not start.', tone: 'error' });
+  await refresh(inst);
+}
+
+/** Use one version over the other. Held for five seconds behind Undo; only then is the session asked for. */
+function useVersion(inst, doc, link, use) {
+  const key = keyOf(doc, link);
+  if (inst.pending.has(key)) return;
+  const L = link.label || LABEL[link.kind];
+  const p = { use, timer: null, toast: null };
+  p.timer = setTimeout(async () => {
+    inst.pending.delete(key);
+    const r = await pmPost('/api/docs/sync', { ws: inst.ws, path: doc.path, kind: link.kind, use });
+    if (!r || !r.ok) toast({ text: (r && r.error) || 'The sync could not start.', tone: 'error' });
+    await refresh(inst);
+  }, UNDO_MS);
+  p.toast = toast({ text: use === 'pmos' ? COPY.pushing(L) : COPY.pulling(L), actionLabel: COPY.undo, timeout: UNDO_MS,
+    onAction: () => { clearTimeout(p.timer); inst.pending.delete(key); draw(inst); toast({ text: COPY.cancelled, timeout: 3000 }); } });
+  inst.pending.set(key, p);
+  inst.open = null;
+  draw(inst);
+}
+
+async function stopTracking(inst, doc, link) {
+  const r = await pmPost('/api/docs/unlink', { ws: inst.ws, path: doc.path, kind: link.kind });
+  if (!r || !r.ok) { toast({ text: (r && r.error) || 'The copy is still tracked.', tone: 'error' }); return; }
+  inst.open = null;
+  toast({ text: COPY.stopped(link.label || LABEL[link.kind]), actionLabel: COPY.undo, timeout: 6000,
+    onAction: async () => { await pmPost('/api/docs/link', { ws: inst.ws, path: doc.path, kind: link.kind, target: link.target }); refresh(inst); } });
+  refresh(inst);
+}
+
+async function addCopy(inst, path, target, err) {
+  const kind = kindOf(target);
+  if (!kind) { err.textContent = COPY.badPaste; return; }
+  const r = await pmPost('/api/docs/link', { ws: inst.ws, path, kind, target });
+  if (!r || !r.ok) { err.textContent = (r && r.error) || 'The copy was not added.'; return; }
+  inst.adding = null;
+  inst.files = inst.files.filter((f) => f.path !== path);
+  toast({ text: COPY.added, timeout: 4000 });
+  refresh(inst);
+}
+
+/* ── lines ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function copyLine(inst, doc, link) {
+  const key = keyOf(doc, link);
+  const L = link.label || LABEL[link.kind];
+  const st = stateOf(inst, doc, link);
+  const open = inst.open === key;
+  const toggle = () => { inst.open = open ? null : key; draw(inst); };
+  let act = null;
+  if (st.btn === 'pmos' || st.btn === 'copy') {
+    act = button({ label: st.btn === 'pmos' ? COPY.usePmos : COPY.useCopy(L), variant: 'primary', size: 'sm',
+      attrs: { 'data-docs-act': 'use-' + st.btn, 'data-docs-key': key }, onClick: () => useVersion(inst, doc, link, st.btn) });
+  } else if (st.btn === 'choose') {
+    act = button({ label: COPY.choose, variant: 'outline', size: 'sm', attrs: { 'data-docs-act': 'choose', 'data-docs-key': key, 'aria-expanded': open ? 'true' : 'false' },
+      onClick: toggle });
+  }
+  const opener = link.url
+    ? el('a', { class: 'rp-docs-open', href: link.url, target: '_blank', rel: 'noopener noreferrer', 'data-docs-open': link.kind }, L + ' ↗')
+    : el('span', { class: 'rp-docs-open' }, L);
+  const line = row({
+    title: doc.title,
+    meta: [st.strong, st.rest].filter(Boolean),
+    lead: [el('span', { class: 'rp-docs-dot rp-docs-dot--' + st.dot, 'aria-hidden': 'true' })],
+    trail: [opener, act].filter(Boolean),
+    onOpen: toggle,
+    openLabel: `${doc.title}, ${L}: ${[st.strong, st.rest].filter(Boolean).join(', ')}`,
+    openAttrs: { 'aria-expanded': open ? 'true' : 'false', title: doc.path, 'data-docs-toggle': key },
+    attrs: { 'data-docs-line': key, 'data-docs-signal': link.signal, 'data-docs-kind': link.kind, 'data-docs-title': doc.title,
+      'data-docs-state': [st.strong, st.rest].filter(Boolean).join(' · ') },
+  });
+  const wrap = el('div', { class: 'rp-docs-row', role: 'listitem', 'data-docs-doc': doc.path }, line);
+  if (open) wrap.appendChild(details(inst, doc, link, st));
+  return wrap;
+}
+
+/** The details, on a click: where each side lives, its last edit, both choices, and the first difference the check saw. */
+function details(inst, doc, link, st) {
+  const L = link.label || LABEL[link.kind];
+  const can = !st.strong || !/^Updating/.test(st.strong);
+  const offer = can && ['ahead', 'behind', 'diverged'].includes(link.signal);
+  const pNew = link.signal === 'ahead';
+  const cNew = link.signal === 'behind';
+  const side = (name, where, last, isNew, use) => el('div', { class: 'rp-docs-side' + (isNew ? ' rp-docs-side--new' : ''), 'data-docs-side': use },
+    el('span', { class: 'rp-docs-side__label' }, name + (isNew ? ' · newer' : '')),
+    el('span', { class: 'rp-docs-side__where' }, where),
+    el('span', { class: 'rp-docs-side__edit' }, last ? 'Last edit: ' + last : 'Last edit: read at the next compare'),
+    offer ? button({ label: use === 'pmos' ? COPY.usePmos : COPY.useCopy(L), variant: isNew ? 'primary' : 'outline', size: 'sm',
+      attrs: { 'data-docs-act': 'use-' + use, 'data-docs-key': keyOf(doc, link) }, onClick: () => useVersion(inst, doc, link, use) }) : null);
+  const diff = link.note && link.signal !== 'same' && link.signal !== 'unchecked'
+    ? el('p', { class: 'rp-docs-diff', 'data-docs-diff': '' }, 'First difference: ' + link.note) : null;
+  return el('div', { class: 'rp-docs-detail', 'data-docs-detail': keyOf(doc, link) },
+    side('PMOS', doc.path, edit(doc.repo && doc.repo.modified_by, doc.repo && doc.repo.modified_at), pNew, 'pmos'),
+    side(L, link.target, edit(link.remote_modified_by, link.remote_modified_at), cNew, 'copy'),
+    diff,
+    el('div', { class: 'rp-docs-more' },
+      button({ label: COPY.compareAgain, variant: 'ghost', size: 'sm', disabled: !!(inst.view && (inst.view.open || inst.view.session)) || inst.busy,
+        attrs: { 'data-docs-act': 'compare-one' }, onClick: () => compareAll(inst) }),
+      button({ label: COPY.stop, variant: 'ghost', size: 'sm', attrs: { 'data-docs-act': 'stop', 'data-docs-key': keyOf(doc, link) },
+        onClick: () => stopTracking(inst, doc, link) })));
+}
+
+/** A file with no copy: "No copy" and Add copy, which opens a paste field in place. */
+function fileLine(inst, f) {
+  const start = () => { inst.adding = f.path; draw(inst); };
+  const adding = inst.adding === f.path;
+  const line = row({
+    title: f.title,
+    meta: [COPY.noCopy],
+    lead: [el('span', { class: 'rp-docs-dot rp-docs-dot--none', 'aria-hidden': 'true' })],
+    trail: adding ? [] : [button({ label: COPY.addCopy, variant: 'outline', size: 'sm', attrs: { 'data-docs-act': 'add-copy', 'data-docs-key': f.path }, onClick: start })],
+    attrs: { 'data-docs-file-line': f.path, title: f.path },
+  });
+  const wrap = el('div', { class: 'rp-docs-row', role: 'listitem', 'data-docs-file': f.path }, line);
+  if (!adding) return wrap;
+  const err = el('span', { class: 'rp-docs-add__err', role: 'alert' });
+  const inp = field({ label: `Copy of ${f.title}`, hideLabel: true, placeholder: COPY.paste, attrs: { 'data-docs-field': 'target' } });
+  inp.control.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter') addCopy(inst, f.path, inp.control.value.trim(), err);
+    if (e.key === 'Escape') { inst.adding = null; draw(inst); }
+  });
+  setTimeout(() => inp.control.focus(), 0);
+  wrap.appendChild(el('div', { class: 'rp-docs-add' }, el('div', { class: 'rp-docs-add__input' }, inp),
+    button({ label: COPY.add, variant: 'primary', size: 'sm', attrs: { 'data-docs-act': 'add-save' }, onClick: () => addCopy(inst, f.path, inp.control.value.trim(), err) }),
+    button({ label: COPY.cancel, variant: 'ghost', size: 'sm', onClick: () => { inst.adding = null; draw(inst); } }),
+    err));
+  return wrap;
+}
+
+/* ── the page ────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function header(inst) {
+  if (inst.head) return inst.head;
+  const find = field({ label: COPY.find, hideLabel: true, placeholder: COPY.find, attrs: { 'data-docs-find': '' } });
+  const q = find.control;
+  q.addEventListener('input', () => { inst.q = q.value; inst.open = null; inst.adding = null; searchFiles(inst); draw(inst); });
+  // The field restores its last committed text on Escape; here Escape clears the search instead.
+  q.addEventListener('keydown', (e) => { if (e.key === 'Escape') { q.resetCommitted(''); inst.q = ''; searchFiles(inst); draw(inst); } });
+  inst.head = el('div', { class: 'rp-docs-top' }, el('h2', { class: 'rp-head__title' }, COPY.title), el('div', { class: 'rp-docs-find' }, find));
+  return inst.head;
+}
+
+function grouped(inst, docs) {
+  const by = new Map();
+  for (const d of docs) {
+    const k = d.initiative ? d.initiative.id : '';
+    if (!by.has(k)) by.set(k, { title: d.initiative ? d.initiative.title : COPY.other, docs: [] });
+    by.get(k).docs.push(d);
+  }
+  return [...by.entries()].sort((a, b) => (a[0] === '') - (b[0] === '')).map(([k, g]) =>
+    el('section', { class: 'rp-docs-group', 'data-docs-group': k || 'other' },
+      el('h3', { class: 'rp-docs-group__title' }, g.title),
+      el('div', { role: 'list' }, g.docs.flatMap((d) => d.links.map((l) => copyLine(inst, d, l))))));
+}
+
+function body(inst) {
+  const v = inst.view;
+  const q = inst.q.trim().toLowerCase();
+  if (q) {
+    const hits = v.docs.filter((d) => [d.title, d.path, d.initiative ? d.initiative.title : ''].join(' ').toLowerCase().includes(q));
+    const rows = [...hits.flatMap((d) => d.links.map((l) => copyLine(inst, d, l))), ...inst.files.map((f) => fileLine(inst, f))];
+    return rows.length ? [el('div', { role: 'list', class: 'rp-docs-group', 'data-docs-results': '' }, rows)] : [el('p', { class: 'rp-section__empty' }, COPY.noMatch(inst.q.trim()))];
+  }
+  const all = v.docs.reduce((n, d) => n + d.links.length, 0);
+  const needs = v.docs.reduce((n, d) => n + d.links.filter((l) => l.signal !== 'same' || l.syncing).length, 0);
+  const running = !!(v.open || v.session) || inst.busy;
+  const out = [el('div', { class: 'rp-docs-views' },
+    tabs({ variant: 'line', items: [{ id: 'needs', label: COPY.needs, count: needs }, { id: 'all', label: COPY.all, count: all }],
+      value: inst.filter, ariaLabel: 'Filter', attrs: { 'data-docs-filter': '' }, onChange: (val) => { inst.filter = val; draw(inst); } }),
+    el('span', { class: 'rp-docs-when', 'data-docs-summary': '' },
+      running ? COPY.comparing : (v.last ? COPY.compared(v.last.finished_at) : COPY.never),
+      button({ label: '↻', variant: 'ghost', size: 'sm', disabled: running || !all,
+        attrs: { 'data-docs-act': 'check', 'aria-label': COPY.compareAll, title: COPY.compareAll }, onClick: () => compareAll(inst) })))];
+  if (!v.docs.length) { out.push(el('p', { class: 'rp-section__empty' }, COPY.none)); return out; }
+  const shown = inst.filter === 'needs'
+    ? v.docs.map((d) => ({ ...d, links: d.links.filter((l) => l.signal !== 'same' || l.syncing || inst.pending.has(keyOf(d, l))) })).filter((d) => d.links.length)
+    : v.docs;
+  if (!shown.length) { out.push(el('p', { class: 'rp-section__empty' }, COPY.nothingNeeds)); return out; }
+  out.push(...grouped(inst, shown));
+  return out;
+}
+
+function draw(inst) {
+  const root = inst.root;
+  if (!inst.ws) { root.replaceChildren(empty({ text: COPY.noRepo })); inst.last = 'none'; return; }
+  const fp = JSON.stringify([inst.loaded, inst.error, inst.view, inst.filter, inst.busy, inst.q, inst.files, inst.open, inst.adding, [...inst.pending.keys()]]);
+  if (fp === inst.last && root.childNodes.length && root.contains(inst.body)) return;
+  inst.last = fp;
+  const head = header(inst);
+  if (head.parentNode !== root || inst.body.parentNode !== root) root.replaceChildren(head, inst.body);
+  if (!inst.loaded) { inst.body.replaceChildren(el('p', { class: 'rp-section__empty' }, COPY.loading)); return; }
+  if (inst.error) { inst.body.replaceChildren(el('p', { class: 'rp-section__empty rp-section__empty--bad', role: 'alert' }, inst.error)); return; }
+  inst.body.replaceChildren(...body(inst));
+}

package/workspace/public/pm/dest-settings.js

@@ -1,11 +1,12 @@
 /* pm/dest-settings.js — the Settings destination, the frame's ⚙ (pm-os-absorb Run 3, slice 3A; PRD R9).
  *
- * Settings holds settings only, in five sections and in this order:
+ * Settings holds settings only, in six sections and in this order:
  *   Repositories       every registered repository as a row (open it to make it current; ⋯ for more), and Add repository,
  *                      which draws the existing add-repository flow (view-addrepo.js) in place
  *   Profiles           one row that opens the Claude profiles in the detail
  *   New sessions       the default CLI and the default model the dock's ＋ Session applies (dock.js)
  *   Validate consent   the current repository's consent switch (GET and POST /api/validate/repo)
+ *   Online             the Online switch and its five settings (GET and POST /api/online; workspace-online-mode, D89)
  *   Theme              Dark or Light
  * The work itself (what needs you, initiatives, items, reports) is never here.
  *
@@ -26,6 +27,7 @@ import { COPY } from './frame-copy.js';
 const P = COPY.page;
 const roots = new WeakMap();      // host -> { root, sig }
 const consentByWs = new Map();    // ws -> { on: boolean | null, error, at, pending }
+const online = { data: null, error: null, note: null, at: 0, pending: false };   // GET /api/online, and the last refusal
 let addOpen = false;
 let addMod = null;
 
@@ -52,11 +54,29 @@ async function setConsent(ws, on) {
   setState({});
 }
 
+function readOnline(force) {
+  if (FIXTURE || online.pending) return;
+  if (!force && Date.now() - online.at < 10000) return;
+  online.pending = true;
+  pmGet('/api/online').then((j) => {
+    online.pending = false; online.at = Date.now();
+    if (j && j.ok !== false) { online.data = j; online.error = null; } else online.error = P.onlineUnread;
+    setState({});
+  });
+}
+
+async function setOnline(patch) {
+  const j = await pmPost('/api/online', patch);
+  if (j && j.ok !== false) { online.data = j; online.note = null; } else online.note = (j && j.error) || P.onlineUnread;
+  online.at = Date.now();
+  setState({});
+}
+
 const section = (id, title, kids, action) => el('section', { class: 'fr-set__section', 'data-fr-section': id },
   el('div', { class: 'fr-set__head' }, el('h2', { class: 'fr-set__title' }, title), action || null),
   kids);
 
-/* ── the five sections ──────────────────────────────────────────────────────────────────────────────────────────── */
+/* ── the six sections ───────────────────────────────────────────────────────────────────────────────────────────── */
 
 function reposSection(scope) {
   const tuples = repoTuples();
@@ -166,6 +186,38 @@ function validateSection(scope) {
     el('span', { 'data-fr': 'consent-state', 'data-on': known ? String(c.on) : 'unread' }, line), toggle, open)]);
 }
 
+function onlineSection() {
+  readOnline(false);
+  const d = online.data;
+  if (!d) return section('online', P.online, [el('p', { class: 'fr-set__note' }, online.error || '')]);
+  if (d.envHost) return section('online', P.online, [el('p', { class: 'fr-set__note', 'data-fr': 'online-state', 'data-on': 'env' }, P.onlineEnv(d.envHost))]);
+  const lines = [el('p', { class: 'fr-set__note', 'data-fr': 'online-state', 'data-on': String(!!d.on) }, d.on ? P.onlineOn(d.host) : P.onlineOff)];
+  if (d.on) {
+    const r = d.running || {};
+    lines.push(el('p', { class: 'fr-set__note', 'data-fr': 'online-tunnel' },
+      r.running ? P.onlineRunning : r.lastExit ? P.onlineExited(r.lastExit.code) : P.onlineStarting));
+    if (d.keys && !d.keys.keys) lines.push(el('p', { class: 'fr-set__note', 'data-fr': 'online-keys' }, d.keys.lastError ? P.onlineKeysError(d.keys.lastError) : P.onlineKeysWait));
+  }
+  if (!d.canChange) return section('online', P.online, [...lines, el('p', { class: 'fr-set__note' }, P.onlineRemote)]);
+  const f = (key, label, placeholder) => field({
+    label, value: d[key] || '', placeholder,
+    onCommit: (v) => setOnline({ [key]: v }),
+    attrs: { 'data-fr': 'online-' + key, disabled: d.on ? true : undefined },
+  });
+  const fields = el('div', { class: 'fr-set__fields' },
+    f('host', P.onlineHost, 'pmos.example.com'), f('tunnel', P.onlineTunnel, 'pmos'), f('team', P.onlineTeam, 'myteam.cloudflareaccess.com'),
+    f('audience', P.onlineAudience, ''), f('email', P.onlineEmail, 'you@example.com'));
+  const blocked = !d.on && (!d.complete ? P.onlineNeedFields : !d.cloudflared ? P.onlineNoCloudflared : null);
+  const toggle = button({
+    label: d.on ? P.turnOff : P.turnOn, variant: 'outline', size: 'sm', disabled: !!blocked,
+    attrs: { 'data-fr': 'online-toggle' }, onClick: () => setOnline({ on: !d.on }),
+  });
+  const kids = [el('p', { class: 'fr-set__note' }, P.onlineIntro), fields, el('div', { class: 'fr-set__line' }, ...lines, toggle)];
+  if (blocked) kids.push(el('p', { class: 'fr-set__note', 'data-fr': 'online-blocked' }, blocked));
+  if (online.note) kids.push(el('p', { class: 'fr-set__note', 'data-fr': 'online-error', role: 'alert' }, online.note));
+  return section('online', P.online, kids);
+}
+
 function themeSection() {
   return section('theme', P.theme, [tabs({
     variant: 'segmented', role: 'radiogroup', ariaLabel: P.theme, value: state.theme,
@@ -182,7 +234,7 @@ function signature(scope) {
   const addKeys = addOpen ? Object.keys(state).filter((k) => /^add[A-Z]/.test(k)).sort().map((k) => [k, state[k]]) : null;
   let add = '';
   try { add = JSON.stringify(addKeys); } catch { add = String(Date.now()); }
-  return JSON.stringify([repoTuples(), activeProduct(), scope, state.theme, sessionDefaults(), ws, consentByWs.get(ws) || null, addOpen, !!addMod]) + add;
+  return JSON.stringify([repoTuples(), activeProduct(), scope, state.theme, sessionDefaults(), ws, consentByWs.get(ws) || null, addOpen, !!addMod, online.data, online.error, online.note]) + add;
 }
 
 /** True while the PM is typing in the page or a menu of it is open: a rebuild then would take the focus away. */
@@ -208,6 +260,7 @@ export function mountDestination(host, ctx) {
     profilesSection(),
     sessionsSection(),
     validateSection(scope),
+    onlineSection(),
     themeSection(),
   ]);
 }

package/workspace/public/pm/frame-copy.js

@@ -150,6 +150,25 @@ export const COPY = {
     theme: 'Theme',
     dark: 'Dark',
     light: 'Light',
+    online: 'Online',
+    onlineIntro: 'Reach this workspace from your phone at your own address. The workspace runs the Cloudflare tunnel, and you sign in with Cloudflare Access (Google or an email code). Only this computer can change it.',
+    onlineHost: 'Public address',
+    onlineTunnel: 'Tunnel name',
+    onlineTeam: 'Cloudflare team domain',
+    onlineAudience: 'Access audience (AUD) tag',
+    onlineEmail: 'Email allowed in',
+    onlineOn: (host) => `Online at https://${host}/`,
+    onlineOff: 'Offline. Only this computer can reach the workspace.',
+    onlineRunning: 'The tunnel is running.',
+    onlineStarting: 'The tunnel is starting.',
+    onlineExited: (code) => `The tunnel stopped${code == null ? '' : ` (exit code ${code})`}. It starts again in a few seconds. Its log is online-tunnel.log in the workspace state folder.`,
+    onlineKeysWait: 'Cloudflare\'s sign-in keys are not loaded yet. Sign-ins are refused until they are.',
+    onlineKeysError: (e) => `Cloudflare\'s sign-in keys did not load (${e}). Check the team domain. Sign-ins are refused until they load.`,
+    onlineNeedFields: 'Fill in all five fields to turn Online on.',
+    onlineNoCloudflared: 'cloudflared is not installed. Install it (brew install cloudflared), then turn Online on.',
+    onlineEnv: (host) => `Online at https://${host}/, set by PMOS_PUBLIC_HOST when the workspace started. It signs in with the token. Restart the workspace without PMOS_PUBLIC_HOST to use this switch.`,
+    onlineRemote: 'Only the computer that runs the workspace can change this.',
+    onlineUnread: 'The Online settings did not load.',
   },
 };
 

package/workspace/public/pm/registry.js

@@ -48,6 +48,8 @@ export const DESTINATIONS = Object.freeze([
   Object.freeze({ id: 'initiatives', label: 'Initiatives', key: 'g i', module: 'dest-initiatives.js', run: 2 }),
   Object.freeze({ id: 'board', label: 'Board', key: 'g b', module: 'dest-board.js', run: 4 }),
   Object.freeze({ id: 'reports', label: 'Reports', key: 'g r', module: 'dest-reports.js', run: 5 }),
+  // Not a pm-os-absorb run (run: null): docs-three-way-sync added it — is each linked document the same as its copies.
+  Object.freeze({ id: 'docs', label: 'Docs', key: 'g d', module: 'dest-docs.js', run: null }),
   Object.freeze({ id: 'settings', label: 'Settings', key: null, module: 'dest-settings.js', run: 3 }),
 ]);
 export const EXTENSIONS = Object.freeze([

package/workspace/replaced-tests.json

@@ -69,6 +69,17 @@
       "names": [
         "(a) calibration: the audit on specimen A gives exactly Today 17, Initiatives 24, Board 33, Reports 14 outside the dock"
       ]
+    },
+    {
+      "id": "SOM-D89",
+      "file": "workspace/no-network.test.js",
+      "run": "workspace-online-mode",
+      "ref": "D89 (ratified by PM wawan on a decision card, 2026-10-06) and planning/prd/workspace-online-mode-prd.md O5",
+      "reason": "D89 adds a second named HTTP client, lib/access-keys.js (a GET of the PM's Cloudflare Access team's public key set while Online is on). The two assertions that named lib/typesafe.js as the only client now name both sanctioned modules; three new assertions pin the new module to cloudflareaccess.com, GET only, and its two requirers. The D79 assertions are unchanged.",
+      "names": [
+        "no-network: the server process opens no HTTP client outside the one TypeSafe module (D79)",
+        "no-network: lib/typesafe.js is the ONLY file that opens an HTTP client"
+      ]
     }
   ],
   "entries": [
@@ -2904,6 +2915,20 @@
       "names": [
         "E3b: an outcome check recorded ONLY in planning/runs/ disposes its initiative"
       ]
+    },
+    {
+      "id": "E72",
+      "group": "E",
+      "file": "workspace/d86-seams.test.js",
+      "section": "assertion 7: the registry's destination modules",
+      "change": "replaced",
+      "slice": "docs-three-way-sync",
+      "reason": "docs-three-way-sync adds a sixth destination, Docs (dest-docs.js), opened from ⌘K and g d. The assertion counted exactly five destination modules, so its name and count change.",
+      "replacement": "The same assertion 7 under a new name counts six destination modules; the three extensions and provider-cards.js first are unchanged.",
+      "pm_approval": null,
+      "names": [
+        "7 registry.js lists the five destination modules and the three extensions (provider-cards.js first)"
+      ]
     }
   ]
 }