@helping-ai-workflow/md2doc 2.10.0 → 2.11.0

package/lib/editor/convert-md.js

@@ -0,0 +1,200 @@
+'use strict';
+/* UMD, same shape as lineops.js / indent-clamp.js: `require`-able in node for
+   the unit tests, and injected into the editor page as `window.md2docConvertMd`
+   (lib/editor/server.js). client.js is inlined into the page as a plain
+   <script>, not bundled, so a bare require('./convert-md.js') there would be
+   an undefined identifier in the browser. */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.md2docConvertMd = factory();
+})(typeof self !== 'undefined' ? self : this, function () {
+
+// Pure marker arithmetic for the S2 "轉換成" submenu (spec 3.2, 4.3).
+//
+// Why this module reads LINES and not the DOM: `serializeBlocks` reports any
+// non-`li` block inside a span as unsupported (list-md.js:462-463), which is
+// exactly the shape a conversion produces. Routing a conversion through the
+// run re-serializer would make every li->heading refuse itself. Reading the
+// source lines also means inline content is never re-escaped, so a `~5px` in
+// the converted block survives as `~5px`.
+//
+// This module knows nothing about indent arithmetic. The caller owns the
+// marker-width stack (spec 3.4) and passes the finished `indentPrefix` in.
+
+const CONVERT_TARGETS = [
+  { id: 'text', label: '文字' },
+  { id: 'h1', label: '標題 1' },
+  { id: 'h2', label: '標題 2' },
+  { id: 'h3', label: '標題 3' },
+  { id: 'h4', label: '標題 4' },
+  { id: 'h5', label: '標題 5' },
+  { id: 'h6', label: '標題 6' },
+  { id: 'ul', label: '項目符號列表' },
+  { id: 'ol', label: '編號列表' },
+  { id: 'task', label: '待辦清單' },
+  { id: 'code', label: '程式碼' },
+  { id: 'quote', label: '引用' },
+];
+
+// A bullet is -, * or +; an ordinal is digits followed by . or ). The GFM task
+// checkbox is parsed out of the CONTENT, not the marker (spec 3.4 errata), so
+// it is stripped as a second, separate step.
+const LI_MARKER = /^(\s*)(?:[-*+]|\d{1,9}[.)])(\s+)/;
+const TASK_BOX = /^\[([ xX])\]\s+/;
+// An ATX heading may carry NO content at all: measured against marked 14.1.4,
+// '#', '##', '###', '## ##' and '#### #' all lex as a heading whose text is
+// ''. Requiring `\s+` plus content refused them, and the user saw
+// 此區塊的格式無法轉換 on an empty heading. The optional closing sequence is
+// stripped separately, because '## ##' has one with no content in front of it.
+const ATX = /^(#{1,6})(?:[ \t]+(.*?))?[ \t]*$/;
+// A closing sequence is a run of # at end of line, preceded by whitespace or
+// by nothing at all. Measured: '## alpha#' keeps the '#' (no space in front)
+// and '## alpha #x' keeps the whole tail (not a pure run).
+const ATX_CLOSE = /(?:^|[ \t]+)#+$/;
+const QUOTE = /^>\s?/;
+// The OPENING fence: <=3 columns of indent, then a run of >=3 backticks or
+// tildes, then an optional info string.
+const FENCE_OPEN = /^( {0,3})(`{3,}|~{3,})(.*)$/;
+
+// Does `line` close a fence opened with `openRun`? Measured against marked
+// 14.1.4, all four conditions are load-bearing:
+//   '````\na\n```'   -> the '```' survives as CONTENT (too short)
+//   '```\na\n~~~'    -> the '~~~' survives as CONTENT (wrong character)
+//   '```\na\n```js'  -> the '```js' survives as CONTENT (info string)
+//   '```\na\n    ```'-> the '    ```' survives as CONTENT (4 columns)
+// while '```\na\n   ```' and '```js\na\n````' both DO close. Matching
+// "looks like a fence" ate a line of the user's code in the first four cases.
+function isClosingFence(line, openRun) {
+  const m = String(line).match(/^( {0,3})(`{3,}|~{3,})[ \t]*$/);
+  if (!m) return false;
+  return m[2][0] === openRun[0] && m[2].length >= openRun.length;
+}
+
+// The longest fence-shaped run of `ch` in `body` -- i.e. the longest run that
+// would CLOSE a fence made of `ch`. Measured: an inline run ('a ``` b') and a
+// run indented 4+ columns never close, so neither inflates the fence; a run
+// indented 0-3 columns does.
+function longestClosingRun(body, ch) {
+  const re = ch === '`' ? /^ {0,3}(`{3,})[ \t]*$/ : /^ {0,3}(~{3,})[ \t]*$/;
+  let longest = 0;
+  for (const line of body) {
+    const m = String(line).match(re);
+    if (m && m[1].length > longest) longest = m[1].length;
+  }
+  return longest;
+}
+
+function stripMarker(sourceLines, blockKind) {
+  const src = Array.isArray(sourceLines) ? sourceLines : [];
+  if (src.length === 0) return { content: [], ok: false };
+
+  if (blockKind === 'li') {
+    const m = src[0].match(LI_MARKER);
+    if (!m) return { content: [], ok: false };
+    // A MULTI-LINE li refuses. The previous code flattened continuations with
+    // replace(/^\s+/, ''), which is exactly the guess the code branch below
+    // refuses to make for an indented code block -- and it silently destroys
+    // whatever structure the continuation carried (a nested fence, an indented
+    // sub-block). Today the \u00a74.1 gate refuses a multi-line li as an operation
+    // target before this is ever reached, so this is defence in depth; dead
+    // code in this repo has a history of later gaining a caller, and it must
+    // not be a mine when it does.
+    if (src.length > 1) return { content: [], ok: false };
+    let first = src[0].slice(m[0].length);
+    const box = first.match(TASK_BOX);
+    if (box) first = first.slice(box[0].length);
+    return { content: [first], ok: true };
+  }
+
+  if (blockKind === 'heading') {
+    const m = src[0].match(ATX);
+    // A setext heading (underlined with === or ---) is two lines and has no
+    // marker to strip from line 1; treat it as content plus a discarded rule.
+    if (!m) {
+      if (src.length >= 2 && /^\s*(=+|-+)\s*$/.test(src[1])) {
+        return { content: [src[0].trim()], ok: true };
+      }
+      return { content: [], ok: false };
+    }
+    const raw = m[2] === undefined ? '' : m[2];
+    return { content: [raw.replace(ATX_CLOSE, '')], ok: true };
+  }
+
+  if (blockKind === 'blockquote') {
+    return { content: src.map((l) => l.replace(QUOTE, '')), ok: true };
+  }
+
+  if (blockKind === 'code') {
+    const open = src[0].match(FENCE_OPEN);
+    // An INDENTED code block has no fence. Stripping four spaces would be a
+    // guess, and a wrong one whenever the body is itself indented, so refuse.
+    if (!open) return { content: [], ok: false };
+    let end = src.length;
+    if (end > 1 && isClosingFence(src[end - 1], open[2])) end -= 1;
+    return { content: src.slice(1, end), ok: true };
+  }
+
+  // paragraph, html, anything else that owns its lines verbatim
+  return { content: src.slice(), ok: true };
+}
+
+function targetIsList(target) {
+  return target === 'ul' || target === 'ol' || target === 'task';
+}
+
+function listAttrsFor(target) {
+  if (target === 'ul') return { listType: 'ul', task: false };
+  if (target === 'ol') return { listType: 'ol', task: false };
+  if (target === 'task') return { listType: 'ul', task: true };
+  return null;
+}
+
+function emitAs(content, target, opts) {
+  const o = opts || {};
+  const prefix = o.indentPrefix || '';
+  const body = Array.isArray(content) ? content : [];
+
+  if (target === 'text') return body.slice();
+
+  if (/^h[1-6]$/.test(target)) {
+    // A heading is one line by definition. Joining is the only lossless move
+    // available; splitting would make one gesture produce two blocks.
+    const hashes = '#'.repeat(Number(target.slice(1)));
+    const text = body.join(' ');
+    // An EMPTY heading emits no trailing space, or converting '##' to a
+    // heading of the same level would rewrite the line to '## '.
+    return [text === '' ? prefix + hashes : prefix + hashes + ' ' + text];
+  }
+
+  if (target === 'quote') return body.map((l) => prefix + '> ' + l);
+
+  if (target === 'code') {
+    // Negotiate the fence length. A body that itself contains a fence line
+    // closed the block early: emitting ['```','before','```','after','```']
+    // lexes as code,paragraph -- 'after' escapes into the document, and the
+    // trailing fence opens an unterminated block. The opening run must be
+    // strictly longer than any run in the body that could close it. Measured:
+    // a TILDE run cannot close a backtick fence, so it does not count here,
+    // despite what the fix request assumed.
+    const fence = '`'.repeat(Math.max(3, longestClosingRun(body, '`') + 1));
+    return [prefix + fence, ...body.map((l) => prefix + l), prefix + fence];
+  }
+
+  if (targetIsList(target)) {
+    const marker = target === 'ol' ? String(o.ordinal || 1) + '. ' : '- ';
+    const box = target === 'task' ? (o.checked ? '[x] ' : '[ ] ') : '';
+    const head = prefix + marker + box + (body[0] !== undefined ? body[0] : '');
+    // Continuations sit under the marker so they stay inside the item. The
+    // checkbox is deliberately NOT counted: spec 3.4's errata measured
+    // `- [ ] ` as contributing 2 columns, not 6, because GFM parses the box
+    // out of the item's CONTENT rather than out of the CommonMark marker.
+    const contIndent = ' '.repeat(marker.length);
+    const rest = body.slice(1).map((l) => prefix + contIndent + l);
+    return [head, ...rest];
+  }
+
+  return body.slice();
+}
+
+return { CONVERT_TARGETS, stripMarker, emitAs, targetIsList, listAttrsFor };
+});

package/lib/editor/indent-clamp.js

@@ -0,0 +1,152 @@
+'use strict';
+/* Spec §3.4 — 縮排合法性：位移後再夾取.
+   UMD, same shape as lineops.js: `require`-able in node for the unit tests,
+   and injected into the editor page as `window.md2docIndentClamp`. */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.md2docIndentClamp = factory();
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  // Markdown indent is only ever RELATIVE: an item's depth exists solely
+  // because some shallower item stands above it. So every structural
+  // operation can leave blocks it never touched with an indent that no longer
+  // has an anchor — and an unanchored indent is not a display glitch, it is a
+  // different document. Four columns of dangling indent after a paragraph
+  // lexes as an INDENTED CODE BLOCK; one column too many under a task marker
+  // makes marked swallow the sublist as literal text. The editor re-renders
+  // from the file after every commit, so "looks right on screen, cannot be
+  // saved" survives exactly one round trip.
+  //
+  //   clampIndents(blocks, opIndex, opOldIndent, opts)
+  //
+  //   blocks       — the commit span, in document order, as plain objects:
+  //                  `{ id, type, indent }`. `type` is the block type string
+  //                  ('li' or anything else); `indent` is the POST-mutation
+  //                  value the caller has already written for whatever it
+  //                  moved. Nothing here reads the DOM.
+  //   opIndex      — index into `blocks` of the operated block, or an ARRAY of
+  //                  indices for a multi-block operation (spec §3.4 rule 3).
+  //   opOldIndent  — the operated block's indent BEFORE the operation (spec
+  //                  §3.4's global convention). For a multi-block operation
+  //                  this is the SMALLEST old indent in the set — anchoring on
+  //                  the first member instead drives later members negative on
+  //                  a delete and no-ops an entire batch Tab.
+  //   opts.removed          — the operated block(s) no longer exist.
+  //   opts.operatedBecomes  — the operated block is still there but is no
+  //                           longer a list item (§3.3 conversion); the value
+  //                           is its new `{ type }`.
+  //
+  // Returns `[{ blockId, indent }]` — one entry per block that is STILL a list
+  // item, in document order. A removed or converted block has no indent to
+  // report and is absent; every other block is present, including ones ahead
+  // of the operation, which never move.
+  function clampIndents(blocks, opIndex, opOldIndent, opts) {
+    const options = opts || {};
+    const src = (blocks || []).map((b) => ({
+      id: b.id,
+      type: b.type,
+      indent: typeof b.indent === 'number' ? b.indent : 0,
+    }));
+    const opIdxs = (Array.isArray(opIndex) ? opIndex.slice() : [opIndex])
+      .filter((i) => i >= 0 && i < src.length)
+      .sort((a, b) => a - b);
+    if (!opIdxs.length) return liEntries(src, () => true);
+
+    const removed = {};
+    if (options.removed) opIdxs.forEach((i) => { removed[i] = true; });
+    if (options.operatedBecomes) {
+      opIdxs.forEach((i) => { src[i].type = options.operatedBecomes.type || 'paragraph'; });
+    }
+
+    // A block that is gone, or is no longer a list item, cannot anchor
+    // anything. `null` means "the next block down may sit at indent 0 and no
+    // deeper" — the same answer as having no previous block at all.
+    function anchorBefore(idx) {
+      for (let k = idx - 1; k >= 0; k--) {
+        if (removed[k]) continue;
+        if (src[k].type !== 'li') return null;
+        return src[k].indent;
+      }
+      return null;
+    }
+    const boundAt = (idx) => {
+      const a = anchorBefore(idx);
+      return a === null ? 0 : a + 1;
+    };
+
+    // ── Rule 1: the operated block itself ────────────────────────────────
+    // Its own upper bound is the ordinary one, so a caller that optimistically
+    // wrote `indent + 1` for a Tab gets it taken back when nothing above can
+    // parent it. Clamped in document order so a multi-block set anchors on
+    // members the loop has already settled.
+    opIdxs.forEach((i) => {
+      if (removed[i] || src[i].type !== 'li') return;
+      src[i].indent = Math.max(0, Math.min(src[i].indent, boundAt(i)));
+    });
+
+    // ── Rule 2: the scope ────────────────────────────────────────────────
+    // From the block after the LAST operated one, up to (not including) the
+    // first block that is not a list item or whose indent is SMALLER than the
+    // operated block's OLD indent. "Smaller", never "smaller or equal": the
+    // following same-level siblings lost the same anchor the children did, and
+    // leaving them out is what makes the model and the bytes drift apart.
+    const scopeStart = opIdxs[opIdxs.length - 1] + 1;
+    let scopeEnd = scopeStart; // exclusive
+    while (scopeEnd < src.length) {
+      const b = src[scopeEnd];
+      if (b.type !== 'li') break;
+      if (b.indent < opOldIndent) break;
+      scopeEnd++;
+    }
+
+    // ── Rule 3: segments ─────────────────────────────────────────────────
+    // The first segment is the operated block's whole subtree (everything
+    // deeper than its old indent); each later segment is one same-level
+    // sibling plus ITS whole subtree. One delta per segment, never per item:
+    // clamping items independently lets the first child settle at 0 and the
+    // second stay at 1, i.e. sibling #2 gets ADOPTED by sibling #1 — a
+    // restructure of content the user never touched.
+    const segments = [];
+    let at = scopeStart;
+    if (at < scopeEnd && src[at].indent > opOldIndent) {
+      let end = at;
+      while (end < scopeEnd && src[end].indent > opOldIndent) end++;
+      segments.push([at, end]);
+      at = end;
+    }
+    while (at < scopeEnd) {
+      let end = at + 1;
+      while (end < scopeEnd && src[end].indent > src[at].indent) end++;
+      segments.push([at, end]);
+      at = end;
+    }
+
+    segments.forEach(([from, to]) => {
+      const delta = Math.max(0, src[from].indent - boundAt(from));
+      if (delta === 0) return;
+      for (let k = from; k < to; k++) src[k].indent = Math.max(0, src[k].indent - delta);
+    });
+
+    // ── Rule 4: per-item clamp, both bounds ──────────────────────────────
+    // Runs over the scope in document order so each block is measured against
+    // the already-settled block above it. The segment deltas above preserve
+    // relative depth; this only ever pulls in an item that is still deeper
+    // than its own parent allows.
+    for (let k = scopeStart; k < scopeEnd; k++) {
+      src[k].indent = Math.max(0, Math.min(src[k].indent, boundAt(k)));
+    }
+
+    return liEntries(src, (i) => !removed[i]);
+  }
+
+  function liEntries(src, keep) {
+    const out = [];
+    src.forEach((b, i) => {
+      if (!keep(i) || b.type !== 'li') return;
+      out.push({ blockId: b.id, indent: b.indent });
+    });
+    return out;
+  }
+
+  return { clampIndents };
+});

package/lib/editor/inline-md.js

@@ -196,7 +196,31 @@
         continue;
       }
       if (name === 'BR') {
-        out += '<br>';
+        // Spec §3.12. Two different things arrive here as the same element:
+        //   * a <br> the EDIT-MODE renderer marked (lib/md2doc.js's
+        //     renderer.br) as having come from a markdown HARD BREAK — it must
+        //     go back out as a hard break, or the block loses a source line;
+        //   * every other <br> — one Shift+Enter inserted, one the source
+        //     spelled out literally, or the placeholder Chromium leaves behind
+        //     when the last character of a surface is deleted — which keeps
+        //     emitting the literal '<br>' it always did. That is a round-trip
+        //     contract with tests pinning it and it does not move.
+        //
+        // BACKSLASH, not two trailing spaces, and the choice is forced rather
+        // than stylistic: markdown's other hard-break spelling is two trailing
+        // spaces, and this module's own output is checked by
+        // assertNoTrailingWhitespace() (gate-compat.test.js's fossilized
+        // paperwork-gate contract), while list-md.js additionally trims every
+        // emitted line unconditionally. The backslash form clears both and
+        // re-lexes to the same `br` token (verified: marked.lexer('- a\\\n  b')
+        // gives the item a `br`). The cost, stated in §3.12: a user who wrote
+        // two trailing spaces gets a backslash back — on a block they were
+        // editing, with the same meaning and the same line count. Untouched
+        // blocks are replayed byte-for-byte by §3.4's bystander rule and never
+        // reach this code.
+        const hardBreak = typeof node.getAttribute === 'function' &&
+          node.getAttribute('data-hard-break') === '1';
+        out += hardBreak ? '\\\n' : '<br>';
         firstSegment = false;
         continue;
       }