create-pmos 0.31.0 → 0.31.1

package/payload/scripts/md-normalize.js

@@ -0,0 +1,223 @@
+/* md-normalize — a newline in a PMOS document means what it says.
+ *
+ * ONE implementation, used on three sides, in the idiom `preview-kind.js` established for exactly
+ * this reason:
+ *   - scripts/md-newlines.js requires it (the check, the --fix, the CI ratchet)
+ *   - workspace/server.js requires it (the doc tab's `normalize` action)
+ *   - the browser loads it as /lib/md-normalize.js (window.MdNormalize)
+ * so the command, the gate and the button can never disagree about what a normalized file is.
+ *
+ * ── WHAT IT IS FOR ─────────────────────────────────────────────────────────────────────────────
+ * PMOS hard-wraps prose at ~100 columns: 30,345 continuation lines across 1,013 of 1,022 tracked
+ * files. A single newline inside a paragraph is NOT a line break in markdown — CommonMark joins the
+ * lines, GitHub joins them, the workspace's own renderer joins them — so this looks right everywhere
+ * inside PMOS. It stops looking right the moment a file is published: Jira wiki markup treats a
+ * newline as a line break, a Google Doc keeps every newline, and several markdown→ADF converters
+ * emit a hard break per `\n`. The paragraph arrives as a stack of ragged short lines, and no
+ * converter can undo it, because an accidental wrap and a deliberate break are THE SAME BYTE in the
+ * source. The only place the distinction still exists is the file.
+ *
+ * ── WHAT IT REFUSES TO TOUCH ───────────────────────────────────────────────────────────────────
+ * Frontmatter, fenced code (including unterminated), indented code, table rows, headings, rules,
+ * link-reference definitions, HTML blocks, a line ending in two spaces or a backslash (a DELIBERATE
+ * hard break — an author's intent, not a wrap), and a line followed by a setext underline. Joining
+ * inside any of those changes what the document MEANS rather than how it wraps, and a repair tool
+ * that damages a file is worse than the defect it repairs.
+ *
+ * ── THE CORRECTNESS PROPERTY ───────────────────────────────────────────────────────────────────
+ * Idempotence: normalize(normalize(x)) === normalize(x), asserted over all 1,022 tracked files
+ * rather than over fixtures. The ratchet, the button and an adopter's repair run are all
+ * untrustworthy without it.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.MdNormalize = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+  const FENCE = /^(\s*)(`{3,}|~{3,})/;
+  const HEADING = /^\s{0,3}#{1,6}(\s|$)/;
+  const RULE = /^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
+  const ITEM = /^(\s*)([-*+]|\d{1,9}[.)])(\s+)(\S.*)$/;
+  const QUOTE = /^(\s{0,3}>\s?)(.*)$/;
+  const TABLE_DELIM = /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/;
+  const SETEXT = /^\s{0,3}(=+|-+)\s*$/;
+  const REF_DEF = /^\s{0,3}\[[^\]]+\]:\s/;
+  const HTML_BLOCK = /^\s{0,3}<[a-zA-Z!/?]/;
+  const INDENTED_CODE = /^(?: {4,}|\t)\S/;
+  /* A break the AUTHOR asked for. Markdown spells it two trailing spaces or a trailing backslash,
+   * and it is the one newline in a paragraph that is not an accident — eating it would be removing
+   * intent, which is the failure this tool exists to avoid, not to commit. */
+  const HARD_BREAK = /(?: {2,}|\\)$/;
+
+  const isBlank = (l) => !l.trim();
+
+  /** A table's header row: this line has a pipe and the NEXT line is the delimiter. */
+  const isTableHeader = (lines, i) =>
+    lines[i].includes('|') && TABLE_DELIM.test(lines[i + 1] || '') && (lines[i + 1] || '').includes('-');
+
+  /** A row inside a table body — a pipe line in a run that began with a header. */
+  function tableRunEnd(lines, i) {
+    let j = i + 2;
+    while (j < lines.length && lines[j].includes('|') && lines[j].trim()) j++;
+    return j;
+  }
+
+  /**
+   * A line that can never be joined ONTO the previous one — it opens a block of its own. This is
+   * the list the blank-line rule is derived from too, so "what needs a blank line above it" and
+   * "what stops a paragraph" cannot drift apart.
+   */
+  function opensBlock(lines, i) {
+    const l = lines[i];
+    return HEADING.test(l) || RULE.test(l) || FENCE.test(l) || ITEM.test(l) || QUOTE.test(l)
+      || REF_DEF.test(l) || HTML_BLOCK.test(l) || INDENTED_CODE.test(l) || isTableHeader(lines, i)
+      || SETEXT.test(l);
+  }
+
+  /**
+   * Normalize `src`.
+   *
+   * Returns `{ text, changed, joins, blanks }` — the bytes, whether anything moved, how many lines
+   * were joined into a paragraph or an item, and how many blank lines were inserted above a block.
+   * The counts are what the CLI reports per file: a tool that says "changed" without saying what it
+   * changed is asking to be trusted rather than read.
+   */
+  function normalize(src) {
+    const input = String(src == null ? '' : src);
+    const nl = input.indexOf('\r\n') >= 0 ? '\r\n' : '\n';
+    const lines = input.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let joins = 0;
+    let blanks = 0;
+    let i = 0;
+
+    // ── frontmatter: copied through, never parsed and never joined ──────────────────────────────
+    if (lines[0] === '---') {
+      let j = 1;
+      while (j < lines.length && lines[j] !== '---') j++;
+      if (j < lines.length) { for (let k = 0; k <= j; k++) out.push(lines[k]); i = j + 1; }
+    }
+
+    /* A continuation line, left-trimmed. Trailing whitespace is dropped ONLY when it is not a hard
+     * break: `.trim()` would eat the author's two trailing spaces mid-paragraph, which is the one
+     * newline in a paragraph that was asked for. */
+    const piece = (l) => {
+      const s2 = l.replace(/^\s+/, '');
+      return HARD_BREAK.test(s2) ? s2 : s2.replace(/\s+$/, '');
+    };
+
+    /** The blank line a block construct needs above it, when prose is what sits there. */
+    const blankAbove = () => {
+      const prev = out.length ? out[out.length - 1] : '';
+      if (!out.length || isBlank(prev)) return;
+      // Only prose gets a blank inserted after it. Two adjacent list items, a table row under its
+      // header, a fence closing — none of those want one, and inserting it would restructure the
+      // document rather than repair its wrapping.
+      if (ITEM.test(prev) || QUOTE.test(prev) || prev.includes('|') || HEADING.test(prev)) return;
+      out.push('');
+      blanks++;
+    };
+
+    while (i < lines.length) {
+      const line = lines[i];
+
+      if (isBlank(line)) { out.push(line); i++; continue; }
+
+      // fenced code — verbatim, to the closing fence or to EOF
+      const fence = FENCE.exec(line);
+      if (fence) {
+        blankAbove();
+        const close = new RegExp('^\\s*' + fence[2][0] + '{' + fence[2].length + ',}\\s*$');
+        out.push(line); i++;
+        while (i < lines.length && !close.test(lines[i])) { out.push(lines[i]); i++; }
+        if (i < lines.length) { out.push(lines[i]); i++; }
+        continue;
+      }
+
+      // indented code, headings, rules, reference definitions, HTML — one line, untouched
+      if (INDENTED_CODE.test(line) || HEADING.test(line) || RULE.test(line) || REF_DEF.test(line)
+        || HTML_BLOCK.test(line) || SETEXT.test(line)) {
+        /* A blank is NEVER inserted above a `---`/`===` line. Directly under prose that is a SETEXT
+         * HEADING, not a rule, and separating it would turn one heading into a paragraph and a
+         * horizontal rule — the untouchable rule wins over the blank-line rule wherever they meet. */
+        if (HEADING.test(line)) blankAbove();
+        out.push(line); i++;
+        continue;
+      }
+
+      // a table: its header, its delimiter and its rows are records — never joined, never reflowed
+      if (isTableHeader(lines, i)) {
+        blankAbove();
+        const end = tableRunEnd(lines, i);
+        for (let k = i; k < end; k++) out.push(lines[k]);
+        i = end;
+        continue;
+      }
+
+      // a list item, plus the continuation lines that belong to it
+      const item = ITEM.exec(line);
+      if (item) {
+        blankAbove();
+        /* INSIDE a list item, four spaces is not code — it is the item's own text column. The
+         * generic `opensBlock` test calls an indented continuation an indented code block and stops,
+         * which left every nested item's wrapped line un-joined. Code inside an item starts four
+         * columns further in than the item's CONTENT does, so that is the line this measures. */
+        const contentCol = item[1].length + item[2].length + item[3].length;
+        const isItemCode = (l) => (l.match(/^[ \t]*/)[0].replace(/\t/g, '    ').length) >= contentCol + 4;
+        let body = line;
+        i++;
+        while (i < lines.length && !isBlank(lines[i]) && !HARD_BREAK.test(body)
+          && /^\s+\S/.test(lines[i]) && !isItemCode(lines[i])
+          && !(HEADING.test(lines[i]) || RULE.test(lines[i]) || FENCE.test(lines[i])
+            || ITEM.test(lines[i]) || QUOTE.test(lines[i]) || isTableHeader(lines, i))) {
+          body += ' ' + piece(lines[i]);
+          joins++; i++;
+        }
+        out.push(body);
+        continue;
+      }
+
+      // a blockquote line, plus its lazy continuations
+      const quote = QUOTE.exec(line);
+      if (quote) {
+        /* A `>` with nothing after it is the blank line INSIDE a quote — it is what separates two
+         * quoted paragraphs. Joining the next paragraph onto it deletes the separator, silently
+         * turns two paragraphs into one, and (because the result then joins again on the next run)
+         * is how this tool would fail its own idempotence property. Found by running the proof over
+         * the real corpus rather than over fixtures: 50 files did exactly this. */
+        if (!quote[2].trim()) { out.push(line); i++; continue; }
+        let body = line;
+        i++;
+        while (i < lines.length && !isBlank(lines[i]) && !HARD_BREAK.test(body)) {
+          const q = QUOTE.exec(lines[i]);
+          const inner = q ? q[2] : lines[i];
+          if (!inner.trim()) break;                                     // a blank quote line ends it
+          if (q && (HEADING.test(inner) || ITEM.test(inner) || RULE.test(inner) || FENCE.test(inner))) break;
+          if (!q && opensBlock(lines, i)) break;                        // lazy continuation, but not a new block
+          body += ' ' + piece(inner);
+          joins++; i++;
+        }
+        out.push(body);
+        continue;
+      }
+
+      // prose — the case the whole tool is about
+      let para = line;
+      i++;
+      while (i < lines.length && !isBlank(lines[i]) && !opensBlock(lines, i) && !HARD_BREAK.test(para)) {
+        para += ' ' + piece(lines[i]);
+        joins++; i++;
+      }
+      out.push(para);
+    }
+
+    const text = out.join(nl);
+    return { text, changed: text !== input, joins, blanks };
+  }
+
+  /** True when the file is already normalized — the check half, with no allocation of a new string. */
+  const isNormalized = (src) => !normalize(src).changed;
+
+  return { normalize, isNormalized };
+});

package/workspace/lib/md-normalize.js

@@ -0,0 +1,223 @@
+/* md-normalize — a newline in a PMOS document means what it says.
+ *
+ * ONE implementation, used on three sides, in the idiom `preview-kind.js` established for exactly
+ * this reason:
+ *   - scripts/md-newlines.js requires it (the check, the --fix, the CI ratchet)
+ *   - workspace/server.js requires it (the doc tab's `normalize` action)
+ *   - the browser loads it as /lib/md-normalize.js (window.MdNormalize)
+ * so the command, the gate and the button can never disagree about what a normalized file is.
+ *
+ * ── WHAT IT IS FOR ─────────────────────────────────────────────────────────────────────────────
+ * PMOS hard-wraps prose at ~100 columns: 30,345 continuation lines across 1,013 of 1,022 tracked
+ * files. A single newline inside a paragraph is NOT a line break in markdown — CommonMark joins the
+ * lines, GitHub joins them, the workspace's own renderer joins them — so this looks right everywhere
+ * inside PMOS. It stops looking right the moment a file is published: Jira wiki markup treats a
+ * newline as a line break, a Google Doc keeps every newline, and several markdown→ADF converters
+ * emit a hard break per `\n`. The paragraph arrives as a stack of ragged short lines, and no
+ * converter can undo it, because an accidental wrap and a deliberate break are THE SAME BYTE in the
+ * source. The only place the distinction still exists is the file.
+ *
+ * ── WHAT IT REFUSES TO TOUCH ───────────────────────────────────────────────────────────────────
+ * Frontmatter, fenced code (including unterminated), indented code, table rows, headings, rules,
+ * link-reference definitions, HTML blocks, a line ending in two spaces or a backslash (a DELIBERATE
+ * hard break — an author's intent, not a wrap), and a line followed by a setext underline. Joining
+ * inside any of those changes what the document MEANS rather than how it wraps, and a repair tool
+ * that damages a file is worse than the defect it repairs.
+ *
+ * ── THE CORRECTNESS PROPERTY ───────────────────────────────────────────────────────────────────
+ * Idempotence: normalize(normalize(x)) === normalize(x), asserted over all 1,022 tracked files
+ * rather than over fixtures. The ratchet, the button and an adopter's repair run are all
+ * untrustworthy without it.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.MdNormalize = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+  const FENCE = /^(\s*)(`{3,}|~{3,})/;
+  const HEADING = /^\s{0,3}#{1,6}(\s|$)/;
+  const RULE = /^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
+  const ITEM = /^(\s*)([-*+]|\d{1,9}[.)])(\s+)(\S.*)$/;
+  const QUOTE = /^(\s{0,3}>\s?)(.*)$/;
+  const TABLE_DELIM = /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/;
+  const SETEXT = /^\s{0,3}(=+|-+)\s*$/;
+  const REF_DEF = /^\s{0,3}\[[^\]]+\]:\s/;
+  const HTML_BLOCK = /^\s{0,3}<[a-zA-Z!/?]/;
+  const INDENTED_CODE = /^(?: {4,}|\t)\S/;
+  /* A break the AUTHOR asked for. Markdown spells it two trailing spaces or a trailing backslash,
+   * and it is the one newline in a paragraph that is not an accident — eating it would be removing
+   * intent, which is the failure this tool exists to avoid, not to commit. */
+  const HARD_BREAK = /(?: {2,}|\\)$/;
+
+  const isBlank = (l) => !l.trim();
+
+  /** A table's header row: this line has a pipe and the NEXT line is the delimiter. */
+  const isTableHeader = (lines, i) =>
+    lines[i].includes('|') && TABLE_DELIM.test(lines[i + 1] || '') && (lines[i + 1] || '').includes('-');
+
+  /** A row inside a table body — a pipe line in a run that began with a header. */
+  function tableRunEnd(lines, i) {
+    let j = i + 2;
+    while (j < lines.length && lines[j].includes('|') && lines[j].trim()) j++;
+    return j;
+  }
+
+  /**
+   * A line that can never be joined ONTO the previous one — it opens a block of its own. This is
+   * the list the blank-line rule is derived from too, so "what needs a blank line above it" and
+   * "what stops a paragraph" cannot drift apart.
+   */
+  function opensBlock(lines, i) {
+    const l = lines[i];
+    return HEADING.test(l) || RULE.test(l) || FENCE.test(l) || ITEM.test(l) || QUOTE.test(l)
+      || REF_DEF.test(l) || HTML_BLOCK.test(l) || INDENTED_CODE.test(l) || isTableHeader(lines, i)
+      || SETEXT.test(l);
+  }
+
+  /**
+   * Normalize `src`.
+   *
+   * Returns `{ text, changed, joins, blanks }` — the bytes, whether anything moved, how many lines
+   * were joined into a paragraph or an item, and how many blank lines were inserted above a block.
+   * The counts are what the CLI reports per file: a tool that says "changed" without saying what it
+   * changed is asking to be trusted rather than read.
+   */
+  function normalize(src) {
+    const input = String(src == null ? '' : src);
+    const nl = input.indexOf('\r\n') >= 0 ? '\r\n' : '\n';
+    const lines = input.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let joins = 0;
+    let blanks = 0;
+    let i = 0;
+
+    // ── frontmatter: copied through, never parsed and never joined ──────────────────────────────
+    if (lines[0] === '---') {
+      let j = 1;
+      while (j < lines.length && lines[j] !== '---') j++;
+      if (j < lines.length) { for (let k = 0; k <= j; k++) out.push(lines[k]); i = j + 1; }
+    }
+
+    /* A continuation line, left-trimmed. Trailing whitespace is dropped ONLY when it is not a hard
+     * break: `.trim()` would eat the author's two trailing spaces mid-paragraph, which is the one
+     * newline in a paragraph that was asked for. */
+    const piece = (l) => {
+      const s2 = l.replace(/^\s+/, '');
+      return HARD_BREAK.test(s2) ? s2 : s2.replace(/\s+$/, '');
+    };
+
+    /** The blank line a block construct needs above it, when prose is what sits there. */
+    const blankAbove = () => {
+      const prev = out.length ? out[out.length - 1] : '';
+      if (!out.length || isBlank(prev)) return;
+      // Only prose gets a blank inserted after it. Two adjacent list items, a table row under its
+      // header, a fence closing — none of those want one, and inserting it would restructure the
+      // document rather than repair its wrapping.
+      if (ITEM.test(prev) || QUOTE.test(prev) || prev.includes('|') || HEADING.test(prev)) return;
+      out.push('');
+      blanks++;
+    };
+
+    while (i < lines.length) {
+      const line = lines[i];
+
+      if (isBlank(line)) { out.push(line); i++; continue; }
+
+      // fenced code — verbatim, to the closing fence or to EOF
+      const fence = FENCE.exec(line);
+      if (fence) {
+        blankAbove();
+        const close = new RegExp('^\\s*' + fence[2][0] + '{' + fence[2].length + ',}\\s*$');
+        out.push(line); i++;
+        while (i < lines.length && !close.test(lines[i])) { out.push(lines[i]); i++; }
+        if (i < lines.length) { out.push(lines[i]); i++; }
+        continue;
+      }
+
+      // indented code, headings, rules, reference definitions, HTML — one line, untouched
+      if (INDENTED_CODE.test(line) || HEADING.test(line) || RULE.test(line) || REF_DEF.test(line)
+        || HTML_BLOCK.test(line) || SETEXT.test(line)) {
+        /* A blank is NEVER inserted above a `---`/`===` line. Directly under prose that is a SETEXT
+         * HEADING, not a rule, and separating it would turn one heading into a paragraph and a
+         * horizontal rule — the untouchable rule wins over the blank-line rule wherever they meet. */
+        if (HEADING.test(line)) blankAbove();
+        out.push(line); i++;
+        continue;
+      }
+
+      // a table: its header, its delimiter and its rows are records — never joined, never reflowed
+      if (isTableHeader(lines, i)) {
+        blankAbove();
+        const end = tableRunEnd(lines, i);
+        for (let k = i; k < end; k++) out.push(lines[k]);
+        i = end;
+        continue;
+      }
+
+      // a list item, plus the continuation lines that belong to it
+      const item = ITEM.exec(line);
+      if (item) {
+        blankAbove();
+        /* INSIDE a list item, four spaces is not code — it is the item's own text column. The
+         * generic `opensBlock` test calls an indented continuation an indented code block and stops,
+         * which left every nested item's wrapped line un-joined. Code inside an item starts four
+         * columns further in than the item's CONTENT does, so that is the line this measures. */
+        const contentCol = item[1].length + item[2].length + item[3].length;
+        const isItemCode = (l) => (l.match(/^[ \t]*/)[0].replace(/\t/g, '    ').length) >= contentCol + 4;
+        let body = line;
+        i++;
+        while (i < lines.length && !isBlank(lines[i]) && !HARD_BREAK.test(body)
+          && /^\s+\S/.test(lines[i]) && !isItemCode(lines[i])
+          && !(HEADING.test(lines[i]) || RULE.test(lines[i]) || FENCE.test(lines[i])
+            || ITEM.test(lines[i]) || QUOTE.test(lines[i]) || isTableHeader(lines, i))) {
+          body += ' ' + piece(lines[i]);
+          joins++; i++;
+        }
+        out.push(body);
+        continue;
+      }
+
+      // a blockquote line, plus its lazy continuations
+      const quote = QUOTE.exec(line);
+      if (quote) {
+        /* A `>` with nothing after it is the blank line INSIDE a quote — it is what separates two
+         * quoted paragraphs. Joining the next paragraph onto it deletes the separator, silently
+         * turns two paragraphs into one, and (because the result then joins again on the next run)
+         * is how this tool would fail its own idempotence property. Found by running the proof over
+         * the real corpus rather than over fixtures: 50 files did exactly this. */
+        if (!quote[2].trim()) { out.push(line); i++; continue; }
+        let body = line;
+        i++;
+        while (i < lines.length && !isBlank(lines[i]) && !HARD_BREAK.test(body)) {
+          const q = QUOTE.exec(lines[i]);
+          const inner = q ? q[2] : lines[i];
+          if (!inner.trim()) break;                                     // a blank quote line ends it
+          if (q && (HEADING.test(inner) || ITEM.test(inner) || RULE.test(inner) || FENCE.test(inner))) break;
+          if (!q && opensBlock(lines, i)) break;                        // lazy continuation, but not a new block
+          body += ' ' + piece(inner);
+          joins++; i++;
+        }
+        out.push(body);
+        continue;
+      }
+
+      // prose — the case the whole tool is about
+      let para = line;
+      i++;
+      while (i < lines.length && !isBlank(lines[i]) && !opensBlock(lines, i) && !HARD_BREAK.test(para)) {
+        para += ' ' + piece(lines[i]);
+        joins++; i++;
+      }
+      out.push(para);
+    }
+
+    const text = out.join(nl);
+    return { text, changed: text !== input, joins, blanks };
+  }
+
+  /** True when the file is already normalized — the check half, with no allocation of a new string. */
+  const isNormalized = (src) => !normalize(src).changed;
+
+  return { normalize, isNormalized };
+});

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "private": true,
   "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/index.html

@@ -53,6 +53,10 @@
      opinion about what an .html file is would mean the endpoint and the pane disagreeing about the
      same document. Classic script (a UMD), like the three above. -->
 <script src="/lib/preview-kind.js"></script>
+<!-- The newline normalizer behind the doc tab's `normalize` action (markdown-newlines). The same
+     file scripts/md-newlines.js requires, loaded here as window.MdNormalize, so the one-click
+     repair and the CI ratchet can never disagree about what a normalized document is. -->
+<script src="/lib/md-normalize.js"></script>
 <link rel="preload" href="/vendor/ibm-plex-mono-500.woff2" as="font" type="font/woff2" crossorigin />
 </head>
 <body>

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

@@ -316,6 +316,7 @@ function diffBody(tab, raw, text, dirty) {
 /* ── per-tab state that is DOM, not data ───────────────────────────────────────────────────── */
 
 const boxes = new Map();      // tab id -> the persistent textarea for that tab
+const normNote = new Map();   // tab id -> what the last `normalize` click did, in words
 
 function editBox(tab) {
   let ta = boxes.get(tab.id);
@@ -336,6 +337,7 @@ function editBox(tab) {
 /** Release what a closed doc tab held. Called by panel-tabs.js when the tab goes away. */
 export function disposeDoc(id) {
   boxes.delete(id);
+  normNote.delete(id);
   frames.delete(id);
   scrollers.delete(id);
 }
@@ -373,15 +375,44 @@ export function mountDoc(host, tab) {
     hover: 'border-color:var(--ring)',
   }, 'revert') : null;
 
+  /* ── normalize ────────────────────────────────────────────────────────────────────────────────
+   * The one-click half of markdown-newlines. It writes the normalized text into the BUFFER, never
+   * to disk: the pane goes dirty, `diff` shows exactly which lines were joined, and `save` is the
+   * existing write path with its existing refusal on a changed base. So a repair the PM did not
+   * want is one `revert` away, and no new way to write a file was added to get it.
+   *
+   * A document that is already normalized reports that and leaves the buffer alone — marking a
+   * clean file dirty for nothing is how a tool teaches you to ignore its dirty flag. */
+  const norm = typeof window !== 'undefined' ? window.MdNormalize : null;
+  const canNormalize = !!(norm && typeof norm.normalize === 'function')
+    && !isHtmlDoc(tab.path) && !isReference(tab.path) && !unread.has(tab.path);
+  const normBtn = canNormalize ? el('button', {
+    onClick: () => {
+      const r = norm.normalize(text);
+      normNote.set(tab.id, r.changed
+        ? r.joins + ' line(s) joined' + (r.blanks ? ', ' + r.blanks + ' blank inserted' : '')
+        : 'already normalized — every paragraph is one line');
+      if (!r.changed) { setState({}); return; }
+      setState((s) => ({ docEdits: { ...s.docEdits, [tab.path]: r.text } }));
+    },
+    style: 'margin-left:8px;font-family:var(--mono);font-size:10.5px;padding:4px 10px;min-height:26px;background:var(--secondary);border:1px solid var(--border);color:var(--muted-foreground)',
+    hover: 'border-color:var(--ring)',
+    title: 'Join hard-wrapped paragraphs into one line each — what a Jira issue, a Google Doc or any'
+      + ' plain-text destination needs. Writes the buffer, not the file: read it in diff, then save.',
+  }, 'normalize') : null;
+
   // The one place a real-mode refusal is reported: the same line that carries the dirty flag, so
-  // a save that did not happen cannot read as one that did.
-  const dirtyLabel = err ? 'not saved — ' + err : (dirty ? '● modified — unsaved' : 'saved on disk');
+  // a save that did not happen cannot read as one that did. The normalize note shares the line for
+  // the same reason — a repair that changed nothing must say so where the PM is already looking.
+  const note = normNote.get(tab.id);
+  const dirtyLabel = err ? 'not saved — ' + err
+    : (dirty ? '● modified — unsaved' : (note || 'saved on disk'));
   const dirtyColor = err ? 'var(--destructive)' : (dirty ? 'var(--warning)' : 'var(--muted-foreground)');
 
   const modeBar = el('div', {
     style: 'flex:none;display:flex;gap:2px;align-items:center;padding:6px 10px;border-bottom:1px solid var(--border);background:var(--background)',
   },
-    modeBtns, saveBtn, revertBtn,
+    modeBtns, normBtn, saveBtn, revertBtn,
     el('span', { style: 'margin-left:auto;font-family:var(--mono);font-size:10px;color:' + dirtyColor }, iv(dirtyLabel)),
   );
 

package/workspace/server.js

@@ -3760,6 +3760,10 @@ async function handleRequest(req, res) {
   // /pm/ module graph below, and one front end is the point. A stray <script src="/app.js"> now
   // 404s loudly rather than silently resurrecting a second, diverging surface.
   if (p === '/lib/preview-kind.js') return serveFile(res, path.join(__dirname, 'lib', 'preview-kind.js'));
+  // The newline normalizer the doc tab's `normalize` action runs, and the same file
+  // scripts/md-newlines.js requires — one implementation, so the button and the gate can never
+  // disagree about what a normalized document is (markdown-newlines).
+  if (p === '/lib/md-normalize.js') return serveFile(res, path.join(__dirname, 'lib', 'md-normalize.js'));
   if (p === '/lib/layout.js') return serveFile(res, path.join(__dirname, 'lib', 'layout.js'));
   if (p === '/lib/mobile-nav.js') return serveFile(res, path.join(__dirname, 'lib', 'mobile-nav.js'));
   if (p === '/lib/session-state.js') return serveFile(res, path.join(__dirname, 'lib', 'session-state.js'));