create-pmos 0.30.0 → 0.30.1

package/README.md

@@ -333,6 +333,35 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.30.1
+
+**Open a markdown file in the workspace and you get the document, not its source. And scrolling
+down stays scrolled down.**
+Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **The document pane renders markdown properly.** Bold was asterisks, inline code was backticks, a
+  table was one paragraph per row with the pipes still in it, and a numbered procedure was a single
+  run-on paragraph. An indented sub-bullet was worse than unstyled — it escaped the list it belonged
+  inside and reappeared underneath it. `view` now renders headings 1–6, soft-wrapped paragraphs,
+  ordered / nested / task lists, GFM tables with per-column alignment, fenced code, blockquotes and
+  rules, plus bold, italic, inline code, strikethrough, links and images. Rubrics and skills — the
+  documents this workflow is written in — are readable in the pane for the first time.
+- **A `.md` link opens that document.** Click a link to another file in your repo and it opens as a
+  tab, resolved against the document you are reading (or the repo root for a `/planning/…` path). A
+  link to something the pane cannot open stays as plain text rather than becoming a dead link.
+- **Nothing is fetched because you opened a file.** A repo-relative image is streamed by your own
+  local workspace; a remote or `data:` image stays as its alt text and is never requested. The
+  renderer builds DOM nodes and never assigns HTML, so a `<script>` in a markdown file is characters
+  on the screen, not a script.
+- **Scrolling a document survives a repaint.** The pane rebuilt its scrolling element on every
+  redraw, so anything that changed state anywhere — including the four-second session poll, which
+  fires whenever an agent beside you is working — took a half-read document back to line 1. The
+  scroll element is now kept, per tab and per mode, the same way the edit box keeps your caret.
+  Holds for `view`, `raw` and `diff`.
+- **Not in this release, said plainly:** this is a workspace-app fix. The file-mode kit — skills,
+  scripts, state layout — is unchanged, so `--update` has nothing new to give you. Syntax
+  highlighting inside code fences, footnotes and rendered inline HTML are deliberately not included.
+
 ## What's new in 0.30.0
 
 **Your user stories are on the board, and a story can name the Jira issue, Confluence page or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "description": "Scaffold the PMOS portable kit \u2014 run the PMOS product-management workflow (initiative \u2192 lane-fit spec \u2192 contract \u2192 build \u2192 three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@ace75db
-assembled: 2026-08-04
+kernel-source: pmos@f5b480a
+assembled: 2026-08-05
 mode: vendor

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "private": true,
   "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -10,7 +10,7 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js && node state-isolation.test.js",
+    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",

package/workspace/public/pm/markdown.js

@@ -0,0 +1,420 @@
+/* pm/markdown.js — the doc pane's markdown renderer.
+ *
+ * The doc tab's `view` mode used to render through `fixture.js`'s `mdParse`, which is a
+ * TRANSCRIPTION of the design prototype's parser — four branches (`# `, `## `, `- `, paragraph) and
+ * no inline pass at all. That is exactly big enough for the prototype's four seed documents and
+ * nowhere near big enough for this repository's own artifacts: a rubric IS a GFM table, a skill IS a
+ * numbered procedure, and both reached the PM as literal source with the pipes and the asterisks
+ * still in them. See planning/explainers/workspace-doc-render-surface-explainer.md.
+ *
+ * `mdParse` is not touched — `fixture-parity.test.mjs` pins it byte-for-byte against the prototype
+ * source, and that transcription proof is the reason the design comparator can be trusted. This is a
+ * separate renderer, and `tab-doc.js` chooses it for `view`.
+ *
+ * ── THE PARITY CONTRACT ────────────────────────────────────────────────────────────────────────
+ * The fixture documents contain only `#`, `##`, `- ` and paragraphs, and `design-parity.js` diffs
+ * the app against the prototype on text nodes, computed style, geometry and pixels. So for those
+ * four constructs this renderer emits NODE-FOR-NODE what the old path emitted, including the
+ * wrapping <span> that `iv()` put around unmarked text: an inline run with no markup in it comes
+ * back as exactly one span holding the whole run. A failed marker match does NOT flush the text
+ * buffer — `planning/initiatives/*.md` is one span, not three.
+ *
+ * ── WHAT IT NEVER DOES ─────────────────────────────────────────────────────────────────────────
+ * It builds DOM NODES. No HTML string is constructed anywhere in this file and `innerHTML` is never
+ * assigned, so a `<script>` line in a document is a `<script>` on the screen, as characters, by
+ * construction rather than by remembering to escape (DOC7). And an image is fetched only when it is
+ * repo-relative, through the guarded /api/asset — a remote or `data:` source stays alt text and is
+ * never requested, which is R4: opening a document must not tell anyone it was opened.
+ */
+
+import { el } from './dom.js';
+
+/* ── styles ─────────────────────────────────────────────────────────────────────────────────────
+ * H2, P, UL and LI are the prototype's strings, verbatim, and must stay that way — they are what
+ * the parity diff measures. Everything below them is new surface, styled in the same idiom: the
+ * semantic tokens only, no raw colour anywhere. */
+const ST = {
+  h1: 'font-size:19px;font-weight:600;line-height:1.3;margin:26px 0 10px;text-wrap:balance;font-family:var(--sans)',
+  h2: 'font-size:16px;font-weight:600;line-height:1.35;margin:24px 0 8px;padding-bottom:5px;border-bottom:1px solid var(--border)',
+  h3: 'font-size:14px;font-weight:600;line-height:1.4;margin:20px 0 7px',
+  h4: 'font-size:13px;font-weight:600;line-height:1.4;margin:18px 0 6px',
+  h5: 'font-size:12.5px;font-weight:600;line-height:1.4;margin:16px 0 6px;color:var(--muted-foreground)',
+  h6: 'font-size:12px;font-weight:600;line-height:1.4;margin:16px 0 6px;color:var(--muted-foreground);text-transform:uppercase;letter-spacing:0.04em',
+  p: 'margin:0 0 12px',
+  ul: 'margin:0 0 12px;padding-left:22px',
+  ol: 'margin:0 0 12px;padding-left:24px',
+  subList: 'margin:5px 0 0;padding-left:22px',
+  li: 'margin:0 0 5px;padding-left:2px',
+  taskUl: 'margin:0 0 12px;padding-left:2px;list-style:none',
+  taskLi: 'margin:0 0 5px;display:flex;gap:8px;align-items:baseline',
+  box: 'font-family:var(--mono);font-size:12px;color:var(--muted-foreground);flex:none',
+  boxDone: 'font-family:var(--mono);font-size:12px;color:var(--success);flex:none',
+  code: 'font-family:var(--mono);font-size:0.88em;background:var(--muted);padding:1px 4px;overflow-wrap:anywhere',
+  pre: 'margin:0 0 14px;background:var(--card);border:1px solid var(--border);padding:10px 12px;overflow-x:auto',
+  preCode: 'font-family:var(--mono);font-size:12px;line-height:1.6;white-space:pre;display:block',
+  lang: 'display:block;font-family:var(--mono);font-size:10px;color:var(--muted-foreground);margin-bottom:6px;letter-spacing:0.04em',
+  quote: 'margin:0 0 14px;padding:2px 0 2px 14px;border-left:2px solid var(--border);color:var(--muted-foreground)',
+  hr: 'border:0;border-top:1px solid var(--border);margin:22px 0',
+  tableWrap: 'margin:0 0 14px;overflow-x:auto;border:1px solid var(--border)',
+  table: 'border-collapse:collapse;width:100%;font-size:12.5px',
+  th: 'font-weight:600;padding:7px 10px;border-bottom:1px solid var(--border);background:var(--card);vertical-align:top',
+  td: 'padding:7px 10px;border-bottom:1px solid var(--border);vertical-align:top',
+  a: 'color:var(--brand);text-decoration:underline;text-underline-offset:2px;overflow-wrap:anywhere',
+  img: 'max-width:100%;height:auto;display:block;margin:0 0 14px;border:1px solid var(--border)',
+  imgAlt: 'color:var(--muted-foreground)',
+};
+
+const HEAD_ST = [ST.h1, ST.h2, ST.h3, ST.h4, ST.h5, ST.h6];
+
+/* ── inline ─────────────────────────────────────────────────────────────────────────────────── */
+
+const RE = {
+  code: /^(`+)([\s\S]*?[^`])\1(?!`)/,
+  image: /^!\[([^\]]*)\]\(\s*([^)\s]*)(?:\s+"[^"]*")?\s*\)/,
+  link: /^\[([^\]]+)\]\(\s*([^)\s]*)(?:\s+"[^"]*")?\s*\)/,
+  autolink: /^<((?:https?:\/\/|mailto:)[^>\s]+)>/,
+  strongStar: /^\*\*(?=\S)([\s\S]*?\S)\*\*/,
+  strongUnder: /^__(?=\S)([\s\S]*?\S)__/,
+  emStar: /^\*(?=[^\s*])((?:[^*]|\*\*)+?)\*(?!\*)/,
+  emUnder: /^_(?=[^\s_])([^_]+?)_(?!\w)/,
+  del: /^~~(?=\S)([\s\S]*?\S)~~/,
+};
+
+const isWord = (c) => !!c && /[A-Za-z0-9]/.test(c);
+
+/**
+ * One line (or cell) of markdown → an array of DOM nodes.
+ *
+ * The scan is left-to-right and a marker that does not resolve is just a character: the plain-text
+ * buffer is flushed ONLY when a real node is emitted, which is what keeps an unmarked run a single
+ * text span (the parity contract) and what keeps `a/*.md` and `pre_run_contract` intact.
+ */
+export function inline(src, ctx = {}) {
+  const s = String(src == null ? '' : src);
+  const out = [];
+  let buf = '';
+  const flush = () => { if (buf) { out.push(el('span', null, buf)); buf = ''; } };
+  const push = (node) => { flush(); out.push(node); };
+
+  let i = 0;
+  while (i < s.length) {
+    const c = s[i];
+    // Nothing can start here — the common case, and the reason a plain paragraph stays one span.
+    if (c !== '`' && c !== '[' && c !== '!' && c !== '*' && c !== '_' && c !== '~' && c !== '<') {
+      buf += c; i++; continue;
+    }
+    const rest = s.slice(i);
+    const prev = i > 0 ? s[i - 1] : '';
+    let m;
+
+    if (c === '`' && (m = RE.code.exec(rest))) {
+      push(el('code', { style: ST.code }, m[2].replace(/^ (.*) $/, '$1')));
+      i += m[0].length; continue;
+    }
+    if (c === '!' && (m = RE.image.exec(rest))) {
+      push(mdImage(m[1], m[2], ctx));
+      i += m[0].length; continue;
+    }
+    if (c === '[' && (m = RE.link.exec(rest))) {
+      const node = mdLink(m[1], m[2], ctx);
+      if (node) { push(node); i += m[0].length; continue; }
+      // A target that cannot be opened is not offered as a link — its TEXT stays, in the buffer,
+      // so it does not fragment the run around it.
+      buf += m[1]; i += m[0].length; continue;
+    }
+    if (c === '<' && (m = RE.autolink.exec(rest))) {
+      push(mdLink(m[1], m[1], ctx) || el('span', null, m[1]));
+      i += m[0].length; continue;
+    }
+    if (c === '~' && (m = RE.del.exec(rest))) {
+      push(el('del', null, inline(m[1], ctx)));
+      i += m[0].length; continue;
+    }
+    if (c === '*' && (m = RE.strongStar.exec(rest))) {
+      push(el('strong', { style: 'font-weight:600' }, inline(m[1], ctx)));
+      i += m[0].length; continue;
+    }
+    /* `__` and `_` are word-boundary-only, deliberately. Intraword underscores are how this
+     * repository writes `pre_run_contract` and `parent_kr`, and a renderer that italicised the
+     * middle of them would be a new defect shipped with the fix for an old one. */
+    if (c === '_' && !isWord(prev) && (m = RE.strongUnder.exec(rest))) {
+      const after = s[i + m[0].length];
+      if (!isWord(after)) { push(el('strong', { style: 'font-weight:600' }, inline(m[1], ctx))); i += m[0].length; continue; }
+    }
+    if (c === '*' && !isWord(prev) && (m = RE.emStar.exec(rest))) {
+      push(el('em', null, inline(m[1], ctx)));
+      i += m[0].length; continue;
+    }
+    if (c === '_' && !isWord(prev) && (m = RE.emUnder.exec(rest))) {
+      const after = s[i + m[0].length];
+      if (!isWord(after)) { push(el('em', null, inline(m[1], ctx))); i += m[0].length; continue; }
+    }
+    buf += c; i++;                       // a marker that resolved to nothing is just a character
+  }
+  flush();
+  return out.length ? out : [el('span', null, '')];
+}
+
+/** bundle-relative (`/planning/…`, the OKF convention) or relative to the open document. */
+export function resolvePath(dir, u) {
+  const clean = String(u || '').split('#')[0].split('?')[0];
+  const stack = clean.startsWith('/') ? [] : [...(dir || [])];
+  for (const p of clean.split('/')) {
+    if (!p || p === '.') continue;
+    if (p === '..') stack.pop(); else stack.push(p);
+  }
+  return stack.join('/');
+}
+
+const REMOTE = /^(?:https?:)?\/\//i;
+const MAILTO = /^mailto:/i;
+/* Every extension `previewKind` calls a document, plus the JSONL ledgers panel 3 links to. A link
+ * to something the doc tab cannot open is not made clickable — a dead link is worse than text. */
+const OPENABLE = /\.(md|markdown|mdown|mkd|mdx|skill|txt|json|jsonl|ya?ml|toml|csv|js|mjs|cjs|ts|tsx|py|sh|css|html?)(#.*)?$/i;
+
+function mdLink(txt, url, ctx) {
+  const u = String(url || '').trim();
+  if (!u) return null;
+  if (REMOTE.test(u) || MAILTO.test(u)) {
+    return el('a', {
+      href: u, target: '_blank', rel: 'noopener noreferrer', style: ST.a,
+    }, inline(txt, ctx));
+  }
+  if (u.startsWith('#')) return null;                 // an in-page anchor has nowhere to go here
+  if (!OPENABLE.test(u)) return null;
+  const path = resolvePath(ctx.dir, u);
+  if (!path || !ctx.onDoc) return null;
+  /* Opening a document from inside a document is the one navigation affordance the retired reader
+   * column had and the doc tab never got. `href="#"` keeps it a real link for the keyboard; the
+   * click never navigates the shell. */
+  return el('a', {
+    href: '#', style: ST.a, title: path,
+    onClick: (e) => { e.preventDefault(); ctx.onDoc(path); },
+  }, inline(txt, ctx));
+}
+
+/**
+ * R4, the no-beacon invariant. A repo-relative source is streamed by the workspace's own guarded
+ * /api/asset; ANYTHING else — remote, protocol-relative, data:, any scheme — is never fetched and
+ * renders as its alt text. The classifier is `preview-kind.js`'s, the one both sides of the app
+ * already share, so "what counts as repo-relative" cannot drift; if it did not load, nothing is
+ * fetched at all.
+ */
+function mdImage(alt, src, ctx) {
+  const label = alt || 'image';
+  const PK = typeof window !== 'undefined' ? window.PreviewKind : null;
+  const repoRel = PK && typeof PK.isRepoRelativeSrc === 'function' ? PK.isRepoRelativeSrc(src) : false;
+  const path = repoRel ? resolvePath(ctx.dir, src) : '';
+  if (!path) return el('em', { style: ST.imgAlt }, label);
+  return el('img', {
+    style: ST.img, alt: label, loading: 'lazy',
+    src: '/api/asset?ws=' + encodeURIComponent(ctx.ws || '') + '&path=' + encodeURIComponent(path),
+  });
+}
+
+/* ── blocks ─────────────────────────────────────────────────────────────────────────────────── */
+
+const RE_ITEM = /^(\s*)([-*+]|\d{1,9}[.)])\s+(.*)$/;
+const RE_HR = /^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
+const RE_HEAD = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const RE_FENCE = /^\s*(`{3,}|~{3,})\s*([^\s`]*)/;
+const RE_QUOTE = /^\s{0,3}>/;
+const RE_TASK = /^\[([ xX])\]\s+(.*)$/;
+const RE_DELIM = /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/;
+
+const cells = (row) => String(row).trim().replace(/^\|/, '').replace(/\|$/, '').split(/(?<!\\)\|/)
+  .map((c) => c.trim().replace(/\\\|/g, '|'));
+
+const isTableAt = (lines, i) => lines[i].includes('|')
+  && RE_DELIM.test(lines[i + 1] || '') && (lines[i + 1] || '').includes('-');
+
+/** Frontmatter → `[{k, v}]`, exactly as the pane has always read it. */
+function frontmatter(lines) {
+  const fm = [];
+  if (lines[0] !== '---') return { fm, next: 0 };
+  let i = 1;
+  while (i < lines.length && lines[i] !== '---') {
+    const ix = lines[i].indexOf(':');
+    if (ix > 0) fm.push({ k: lines[i].slice(0, ix).trim(), v: lines[i].slice(ix + 1).trim() });
+    i++;
+  }
+  return { fm, next: i + 1 };
+}
+
+/**
+ * The document → `{ fm, title, titleText, blocks }`.
+ *
+ * `title` is the inline nodes of the FIRST `# ` line — the pane draws it as the document's heading,
+ * the way it always has. A second `# ` is a real h1 in the body rather than silently replacing the
+ * title, which is what the old parser did (last one wins, the earlier ones vanish).
+ *
+ * `ctx` carries what links and images need: `{ dir, ws, onDoc }`.
+ */
+export function mdRender(text, ctx = {}) {
+  const lines = String(text == null ? '' : text).replace(/\r\n?/g, '\n').split('\n');
+  const { fm, next } = frontmatter(lines);
+  const blocks = [];
+  let title = null, titleText = '';
+  let i = next;
+
+  while (i < lines.length) {
+    const ln = lines[i];
+    if (!ln.trim()) { i++; continue; }
+    let m;
+
+    // fenced code — verbatim, never parsed, and an unterminated fence takes the rest of the file
+    if ((m = RE_FENCE.exec(ln))) {
+      const close = new RegExp('^\\s*' + m[1][0] + '{' + m[1].length + ',}\\s*$');
+      const body = [];
+      i++;
+      while (i < lines.length && !close.test(lines[i])) body.push(lines[i++]);
+      i++;
+      blocks.push(el('pre', { style: ST.pre },
+        m[2] ? el('span', { style: ST.lang }, m[2]) : null,
+        el('code', { style: ST.preCode }, body.join('\n'))));
+      continue;
+    }
+
+    if ((m = RE_HEAD.exec(ln))) {
+      const n = m[1].length;
+      const nodes = inline(m[2], ctx);
+      if (n === 1 && title === null) { title = nodes; titleText = m[2]; }
+      else blocks.push(el('h' + n, { style: HEAD_ST[n - 1] }, nodes));
+      i++; continue;
+    }
+
+    if (RE_HR.test(ln)) { blocks.push(el('hr', { style: ST.hr })); i++; continue; }
+
+    // blockquote — its body is markdown, so it is rendered by the same pass
+    if (RE_QUOTE.test(ln)) {
+      const body = [];
+      while (i < lines.length && (RE_QUOTE.test(lines[i])
+        || (body.length && lines[i].trim() && !RE_ITEM.test(lines[i]) && !RE_HEAD.test(lines[i])))) {
+        body.push(lines[i].replace(/^\s{0,3}>\s?/, '')); i++;
+      }
+      const inner = mdRender(body.join('\n'), ctx);
+      blocks.push(el('blockquote', { style: ST.quote },
+        inner.title ? el('h3', { style: ST.h3 }, inner.title) : null, inner.blocks));
+      continue;
+    }
+
+    // GFM table: a header row followed by a delimiter row
+    if (isTableAt(lines, i)) {
+      const head = cells(ln);
+      const align = cells(lines[i + 1]).map((c) => (/^:.*:$/.test(c) ? 'center' : /:$/.test(c) ? 'right' : /^:/.test(c) ? 'left' : ''));
+      i += 2;
+      const rows = [];
+      while (i < lines.length && lines[i].includes('|') && lines[i].trim()) rows.push(cells(lines[i++]));
+      // Written for every column, not only the aligned ones: a `text-align` that is present on some
+      // cells and inherited on others is how a column silently follows its neighbour's alignment.
+      const al = (n) => ';text-align:' + (align[n] || 'left');
+      blocks.push(el('div', { style: ST.tableWrap },
+        el('table', { style: ST.table },
+          el('thead', null, el('tr', null,
+            head.map((c, n) => el('th', { style: ST.th + al(n) }, inline(c, ctx))))),
+          el('tbody', null, rows.map((r) => el('tr', null,
+            head.map((_, n) => el('td', { style: ST.td + al(n) }, inline(r[n] || '', ctx)))))))));
+      continue;
+    }
+
+    if (RE_ITEM.test(ln)) {
+      const { items, next: after } = listBlock(lines, i);
+      blocks.push(renderLists(items, 0, ctx, true).node);
+      i = after; continue;
+    }
+
+    /* paragraph — consecutive lines are ONE paragraph. The join is what makes a soft-wrapped
+     * sentence read as a sentence; the guards are what stop it swallowing the block that follows. */
+    const para = [];
+    while (i < lines.length && lines[i].trim() && !RE_ITEM.test(lines[i]) && !RE_HR.test(lines[i])
+      && !RE_QUOTE.test(lines[i]) && !RE_HEAD.test(lines[i]) && !RE_FENCE.test(lines[i])
+      && !isTableAt(lines, i)) {
+      para.push(lines[i]); i++;
+    }
+    if (para.length) blocks.push(el('p', { style: ST.p }, inline(para.join(' '), ctx)));
+    else i++;                             // nothing consumed — never spin
+  }
+
+  return { fm, title, titleText, blocks };
+}
+
+/** Collect one list block: its items, their indents, and their wrapped continuation lines. */
+function listBlock(lines, start) {
+  const items = [];
+  let i = start;
+  while (i < lines.length) {
+    const ln = lines[i];
+    const m = RE_ITEM.exec(ln);
+    if (m) {
+      items.push({ indent: m[1].replace(/\t/g, '    ').length, ordered: /\d/.test(m[2]), lines: [m[3]] });
+      i++; continue;
+    }
+    if (!ln.trim()) {
+      const nx = lines[i + 1] || '';
+      if (RE_ITEM.test(nx) || /^\s{2,}\S/.test(nx)) { i++; continue; }    // a loose list
+      break;
+    }
+    /* A fence indented under an item ENDS the list rather than being folded into the item's text.
+     * PMOS's own PRDs write a numbered step and then indent a block of output under it; joining
+     * those lines into the item would put the ``` markers on screen as characters — the exact
+     * defect this renderer exists to remove. The fence then renders as its own block, after the
+     * list: degraded placement, never degraded content. */
+    if (RE_FENCE.test(ln)) break;
+    if (items.length && /^\s+\S/.test(ln)) { items[items.length - 1].lines.push(ln.trim()); i++; continue; }
+    break;
+  }
+  return { items, next: i };
+}
+
+/** Every list at one indent level, as siblings. Returns one node when there is only one list. */
+function renderLists(items, start, ctx, top) {
+  const base = items[start].indent;
+  const nodes = [];
+  let i = start;
+  while (i < items.length && items[i].indent >= base) {
+    const r = renderList(items, i, ctx, top);
+    nodes.push(r.node);
+    if (r.next === i) break;                                             // never spin
+    i = r.next;
+  }
+  return { node: nodes.length === 1 ? nodes[0] : el('div', null, nodes), next: i };
+}
+
+/**
+ * One list. A change of marker type at the same indent — bullet ↔ number, or the first `- [ ]` —
+ * starts a sibling list, the way every markdown renderer does it. A deeper indent is nested INSIDE
+ * the item above it, which is the case the old parser got visibly wrong: an indented sub-bullet did
+ * not match `- `, fell through to the paragraph branch, and was emitted after the list it belonged
+ * inside.
+ */
+function renderList(items, start, ctx, top) {
+  const base = items[start].indent;
+  const { ordered } = items[start];
+  const task = RE_TASK.test(items[start].lines[0]);
+  const lis = [];
+  let i = start;
+  while (i < items.length && items[i].indent >= base) {
+    if (items[i].indent === base
+      && (items[i].ordered !== ordered || RE_TASK.test(items[i].lines[0]) !== task)) break;
+    if (items[i].indent > base) {
+      const sub = renderLists(items, i, ctx, false);
+      if (lis.length) lis[lis.length - 1].appendChild(sub.node);
+      else lis.push(el('li', { style: ST.li }, sub.node));
+      i = sub.next; continue;
+    }
+    const body = items[i].lines.join(' ');
+    const t = RE_TASK.exec(body);
+    if (t) {
+      lis.push(el('li', { style: ST.taskLi },
+        el('span', { style: t[1] === ' ' ? ST.box : ST.boxDone, 'aria-hidden': 'true' }, t[1] === ' ' ? '☐' : '☑'),
+        el('span', null, inline(t[2], ctx))));
+    } else {
+      lis.push(el('li', { style: ST.li }, inline(body, ctx)));
+    }
+    i++;
+  }
+  const style = task ? ST.taskUl : (ordered ? ST.ol : (top ? ST.ul : ST.subList));
+  return { node: el(ordered ? 'ol' : 'ul', { style }, lis), next: i };
+}
+
+export default mdRender;

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

@@ -22,11 +22,24 @@
  * Every keystroke is a state change, and a state change repaints the panel. A textarea rebuilt on
  * each keystroke loses the caret, so the element is created once per tab and kept; its text is
  * written back only when it actually differs from what the box already holds.
+ *
+ * ── …and why the SCROLLING ELEMENT does too ─────────────────────────────────────────────────
+ * A scroll offset is the same class of state as a caret, and it was not getting the same treatment:
+ * `view`, `raw` and `diff` each built a fresh scrolling div on every paint, so any repaint — the
+ * 4-second session poll included — took a half-read document back to the top. `scrollPane` keeps one
+ * element per tab and mode; see the block comment above it.
+ *
+ * ── What `view` renders it through ──────────────────────────────────────────────────────────
+ * `markdown.js`, not `fixture.js`'s `mdParse`. The latter is a transcription of the design
+ * prototype's four-branch stand-in (`# `/`## `/`- `/paragraph) pinned byte-for-byte by
+ * `fixture-parity.test.mjs`; it stays exactly as it is, and it is not a markdown renderer.
  */
 
 import { el, setChildren } from './dom.js';
 import { state, setState, FIXTURE } from './state.js';
 import * as FX from './fixture.js';
+import { mdRender } from './markdown.js';
+import { openDoc } from './panel-initiatives.js';
 
 /** `{{ expr }}` — one interpolated value in its own span, as the prototype's runtime emits it. */
 const iv = (v) => el('span', null, v === null || v === undefined ? '' : String(v));
@@ -152,36 +165,68 @@ function revert(tab) {
 const FM_K = 'font-size:10.5px;color:var(--muted-foreground);padding-top:2px;font-family:var(--mono)';
 const FM_V = 'overflow-wrap:anywhere;font-family:var(--mono);font-size:11.5px';
 
-function viewBody(text) {
-  const doc = FX.mdParse(text);
-  const fm = [];
-  doc.fm.forEach((fp) => { fm.push(el('span', { style: FM_K }, iv(fp.k)), el('span', { style: FM_V }, iv(fp.v))); });
-  return el('div', {
-    style: 'flex:1;min-height:0;overflow-y:auto;background:var(--background);color:var(--foreground);padding:20px 24px 60px;font-size:14px;line-height:1.65',
-  },
-    el('div', { style: 'max-width:72ch' },
+const VIEW_ST = 'flex:1;min-height:0;overflow-y:auto;background:var(--background);color:var(--foreground);padding:20px 24px 60px;font-size:14px;line-height:1.65';
+const RAW_ST = 'flex:1;min-height:0;overflow-y:auto;background:var(--background);padding:14px 16px;font-family:var(--mono);font-size:12px;line-height:1.7';
+const DIFF_ST = 'flex:1;min-height:0;overflow-y:auto;background:var(--background);padding:14px 0;font-family:var(--mono);font-size:12px;line-height:1.7';
+
+/* ── THE SCROLL POSITION IS STATE, AND IT LIVES ON A NODE ──────────────────────────────────────
+ *
+ * Every `setState` anywhere in the app repaints all four panels, and panel 4 calls `mountDoc` on
+ * every paint. Each body used to be built from scratch, and `setChildren` reconciles by node
+ * IDENTITY — so the div `scrollTop` lives on was removed and a fresh one inserted, and a half-read
+ * document went back to line 1. With a live agent session beside it that fires on the session poll,
+ * at four-second intervals the PM neither caused nor can predict.
+ *
+ * This is the same problem the edit textarea has, and it gets the same answer: the element is
+ * created once per tab and per mode and KEPT. A repaint whose text has not changed hands back the
+ * identical node, which is what `setChildren` needs in order to leave it alone; when the text really
+ * does change the children are rebuilt INSIDE that element and the offset is restored, because the
+ * document being read is still the document being read.
+ *
+ * Keyed on the rendered text, not on the tab alone — that is what makes "changed nothing" decidable
+ * without diffing DOM.
+ */
+const scrollers = new Map();      // tab id -> { view|raw|diff: { key, node } }
+
+function scrollPane(tab, mode, key, style, build) {
+  let per = scrollers.get(tab.id);
+  if (!per) { per = {}; scrollers.set(tab.id, per); }
+  const cur = per[mode];
+  if (cur && cur.key === key) return cur.node;          // nothing changed — the very same element
+  const node = (cur && cur.node) || el('div', { style });
+  const top = node.scrollTop;
+  setChildren(node, build());
+  if (top) node.scrollTop = top;
+  per[mode] = { key, node };
+  return node;
+}
+
+/** What links and images in this document resolve against. `onDoc` opens a .md link as a doc tab. */
+const linkCtx = (tab) => ({
+  dir: String(tab.path || '').split('/').slice(0, -1),
+  ws: wsId(),
+  onDoc: (p) => openDoc(tab.slug, p, 'FILE'),
+});
+
+function viewBody(tab, text) {
+  return scrollPane(tab, 'view', text, VIEW_ST, () => {
+    const doc = mdRender(text, linkCtx(tab));
+    const fm = [];
+    doc.fm.forEach((fp) => { fm.push(el('span', { style: FM_K }, iv(fp.k)), el('span', { style: FM_V }, iv(fp.v))); });
+    return [el('div', { style: 'max-width:72ch' },
       el('div', {
         style: 'border:1px solid var(--border);background:var(--card);padding:10px 12px;margin-bottom:18px;display:grid;grid-template-columns:auto 1fr;gap:4px 14px;font-size:12.5px',
       }, fm),
       el('h1', {
         style: 'font-size:21px;font-weight:600;line-height:1.3;margin:4px 0 12px;text-wrap:balance;font-family:var(--sans)',
-      }, iv(doc.title)),
-      doc.blocks.map((bk) => el('div', null,
-        bk.isH ? el('h2', {
-          style: 'font-size:16px;font-weight:600;line-height:1.35;margin:24px 0 8px;padding-bottom:5px;border-bottom:1px solid var(--border)',
-        }, iv(bk.h)) : null,
-        bk.isP ? el('p', { style: 'margin:0 0 12px' }, iv(bk.p)) : null,
-        bk.isList ? el('ul', { style: 'margin:0 0 12px;padding-left:22px' },
-          bk.items.map((li) => el('li', { style: 'margin:0 0 5px;padding-left:2px' }, iv(li)))) : null,
-      )),
-    ),
-  );
+      }, doc.title || iv('')),
+      doc.blocks.map((bk) => el('div', null, bk)),
+    )];
+  });
 }
 
-function rawBody(text) {
-  return el('div', {
-    style: 'flex:1;min-height:0;overflow-y:auto;background:var(--background);padding:14px 16px;font-family:var(--mono);font-size:12px;line-height:1.7',
-  }, text.split('\n').map((l) => {
+function rawBody(tab, text) {
+  return scrollPane(tab, 'raw', text, RAW_ST, () => text.split('\n').map((l) => {
     const ln = FX.rawLine(l);
     return el('div', {
       style: 'color:' + ln.c + ';font-weight:' + ln.w + ';white-space:pre-wrap;overflow-wrap:anywhere;min-height:1.2em',
@@ -254,13 +299,18 @@ function htmlFrame(tab, text) {
   return node;
 }
 
-function diffBody(raw, text, dirty) {
-  const rows = dirty ? FX.diffLines(raw, text) : [FX.NO_DIFF_ROW];
-  return el('div', {
-    style: 'flex:1;min-height:0;overflow-y:auto;background:var(--background);padding:14px 0;font-family:var(--mono);font-size:12px;line-height:1.7',
-  }, rows.map((dr) => el('div', {
-    style: 'color:' + dr.c + ';background:' + dr.bg + ';padding:0 16px;white-space:pre-wrap;overflow-wrap:anywhere;min-height:1.2em',
-  }, iv(dr.t))));
+/* Two texts joined into one key. The separator is a character no document can contain — the same
+ * reasoning `sessionProjection` uses in data.js — so a change that only moves the boundary between
+ * them cannot fold into an identical key and suppress a rebuild that was real. */
+const SEP = '\u0000';
+
+function diffBody(tab, raw, text, dirty) {
+  return scrollPane(tab, 'diff', dirty ? raw + SEP + text : '', DIFF_ST, () => {
+    const rows = dirty ? FX.diffLines(raw, text) : [FX.NO_DIFF_ROW];
+    return rows.map((dr) => el('div', {
+      style: 'color:' + dr.c + ';background:' + dr.bg + ';padding:0 16px;white-space:pre-wrap;overflow-wrap:anywhere;min-height:1.2em',
+    }, iv(dr.t)));
+  });
 }
 
 /* ── per-tab state that is DOM, not data ───────────────────────────────────────────────────── */
@@ -287,6 +337,7 @@ function editBox(tab) {
 export function disposeDoc(id) {
   boxes.delete(id);
   frames.delete(id);
+  scrollers.delete(id);
 }
 
 /* ── mount ─────────────────────────────────────────────────────────────────────────────────── */
@@ -335,8 +386,8 @@ export function mountDoc(host, tab) {
   );
 
   let body;
-  if (dm === 'raw') body = rawBody(text);
-  else if (dm === 'diff') body = diffBody(raw, text, dirty);
+  if (dm === 'raw') body = rawBody(tab, text);
+  else if (dm === 'diff') body = diffBody(tab, raw, text, dirty);
   else if (dm === 'edit') {
     body = editBox(tab);
     /* `defaultValue` IS the textarea's child text node, and the prototype's runtime keeps it in
@@ -345,7 +396,7 @@ export function mountDoc(host, tab) {
      * genuinely differs, which is what keeps the caret still mid-sentence. */
     if (body.defaultValue !== text) body.defaultValue = text;
     if (body.value !== text) body.value = text;
-  } else body = rendersAsPage(tab) ? htmlFrame(tab, text) : viewBody(text);
+  } else body = rendersAsPage(tab) ? htmlFrame(tab, text) : viewBody(tab, text);
 
   setChildren(host, [modeBar, body]);
   return host;