@helping-ai-workflow/md2doc 3.12.1 → 3.13.1

package/lib/editor/inline-md.js

@@ -47,6 +47,50 @@
     return out;
   }
 
+  // v3.13.1 T2 (F-1): text a person typed at the start of a paragraph or
+  // list-item line that a renderer would read as a block marker. Measured
+  // before this: typing `## `, `- `, `> ` or `1. ` at a paragraph start saved
+  // the line unescaped, and the next render silently turned the paragraph
+  // into a heading, list or quote.
+  //
+  // Input is escapeText() output, possibly several lines (a hard break's
+  // backslash-newline, or a lazy continuation). Each line, after up to three
+  // spaces of indent, gets the FIRST matching rule below; nothing else is
+  // touched. The list is the decision:
+  //   ATX heading      `#`..`######` then space/tab/end   -> `\#…`
+  //   bullet           `-` or `+` then space/tab/end      -> `\-…` / `\+…`
+  //   blockquote       `>` (no space needed)              -> `\>…`
+  //   ordered          1-9 digits, `.` or `)`, space/end  -> `1\.` / `1\)`
+  //   setext/rule      a run of `=` or of `-`, alone      -> `\===` / `\---`
+  //   spaced rule      3+ `-` with spaces between, alone  -> `\-- -`
+  //   table row        `|`                                -> `\|…`
+  // `*`, `_`, backtick, `~`, `<` and `[` never get here unescaped
+  // (escapeText()). A line whose first character is `\` matches nothing,
+  // which is what keeps already-escaped text byte-stable. `-5 dBm` and
+  // `1.5 V` match nothing either: the marker must be followed by a space, a
+  // tab or the end of the line. Indented code (4+ spaces) is out of scope.
+  const BLOCK_START_RULES = [
+    { re: /^#{1,6}(?=[ \t]|$)/, fix: (rest) => '\\' + rest },
+    { re: /^[-+](?=[ \t]|$)/, fix: (rest) => '\\' + rest },
+    { re: /^>/, fix: (rest) => '\\' + rest },
+    { re: /^(\d{1,9})([.)])(?=[ \t]|$)/, fix: (rest) => rest.replace(/^(\d{1,9})([.)])/, '$1\\$2') },
+    { re: /^(=+|-+)[ \t]*$/, fix: (rest) => '\\' + rest },
+    // A thematic break may have spaces between its dashes (`-- -`,
+    // `----  -`); the run rule above only sees an unbroken one.
+    { re: /^-(?:[ \t]*-){2,}[ \t]*$/, fix: (rest) => '\\' + rest },
+    { re: /^\|/, fix: (rest) => '\\' + rest },
+  ];
+  function escapeBlockStarts(md) {
+    return String(md).split('\n').map((line) => {
+      const ind = /^ {0,3}/.exec(line)[0];
+      const rest = line.slice(ind.length);
+      for (let i = 0; i < BLOCK_START_RULES.length; i++) {
+        if (BLOCK_START_RULES[i].re.test(rest)) return ind + BLOCK_START_RULES[i].fix(rest);
+      }
+      return line;
+    }).join('\n');
+  }
+
   // Real contenteditable output wraps plain runs in attribute-less <span>s
   // (Chrome/Firefox formatting artifacts). Those are transparent. A <span>
   // carrying any of these attributes is a real style/class/behavior carrier
@@ -358,5 +402,5 @@
     return serializeInline(rootEl).unsupported.length === 0;
   }
 
-  return { serializeInline, canWysiwyg, escapeText };
+  return { serializeInline, canWysiwyg, escapeText, escapeBlockStarts };
 });

package/lib/editor/list-md.js

@@ -224,7 +224,9 @@
 
       // strip leading whitespace left behind by a dropped leading element
       // (e.g. a checkbox <input>) — see header note.
-      const itemMd = rawItemMd.replace(/^[ \t]+/, '');
+      // v3.13.1 T2 (F-1): text that begins with a block marker is escaped,
+      // or the item's own text would re-lex as a nested heading/list/quote.
+      const itemMd = inlineMd.escapeBlockStarts(rawItemMd.replace(/^[ \t]+/, ''));
 
       // Two-part marker: bullet (ordered ordinal or plain '- ') and an
       // optional checkbox prefix. The two parts are independent so that
@@ -617,6 +619,11 @@
         // zero-width character it never asked for, and the item would stop
         // reading as empty to every `itemMd === ''` test in this function.
         if (SETEXT_ESCAPE_RE.test(itemMd)) itemMd = '';
+        // v3.13.1 T2 (F-1): an item whose text begins with `## `, `- `, `> `,
+        // `1. ` (…) is written escaped, or the next render reads it as a
+        // nested block. Only re-serialized items get here; a bystander
+        // replayed from its source lines never does.
+        itemMd = inlineMd.escapeBlockStarts(itemMd);
       }
 
       // Anything in the block that is neither chrome nor the text surface is

package/lib/editor/server.js

@@ -88,8 +88,11 @@ const PASTE_MD_SRC = fs.readFileSync(path.join(__dirname, 'paste-md.js'), 'utf8'
 //
 // wave-ui.js is UMD like its neighbours and needs no shim; in the page it
 // defines `window.md2docWaveUi` and takes the other five as parameters.
+const WAVE_OVERFLOW_SRC = fs.readFileSync(path.join(__dirname, '..', 'wave-overflow.js'), 'utf8');
 const WAVE_CODEC_SRC = fs.readFileSync(path.join(__dirname, 'wave-codec.js'), 'utf8');
 const WAVE_GEOMETRY_SRC = fs.readFileSync(path.join(__dirname, 'wave-geometry.js'), 'utf8');
+// wave-redesign P1 Task 4: the engine-drawn canvas (createCanvas), same shim.
+const WAVE_CANVAS_SRC = fs.readFileSync(path.join(__dirname, 'wave-canvas.js'), 'utf8');
 const WAVE_STORE_SRC = fs.readFileSync(path.join(__dirname, 'wave-store.js'), 'utf8');
 const WAVE_DRAW_SRC = fs.readFileSync(path.join(__dirname, 'wave-draw.js'), 'utf8');
 const WAVE_PANELS_SRC = fs.readFileSync(path.join(__dirname, 'wave-panels.js'), 'utf8');
@@ -742,7 +745,9 @@ async function createEditorServer({
           `<script>${TURNDOWN_SRC}</script>\n` +
           `<script>${PASTE_MD_SRC}</script>\n` +
           waveModuleTag('wave-codec.js', WAVE_CODEC_SRC) +
+          waveModuleTag('wave-overflow.js', WAVE_OVERFLOW_SRC) +
           waveModuleTag('wave-geometry.js', WAVE_GEOMETRY_SRC) +
+          waveModuleTag('wave-canvas.js', WAVE_CANVAS_SRC) +
           waveModuleTag('wave-store.js', WAVE_STORE_SRC) +
           waveModuleTag('wave-draw.js', WAVE_DRAW_SRC) +
           waveModuleTag('wave-panels.js', WAVE_PANELS_SRC) +

package/lib/editor/wave-canvas.js

@@ -0,0 +1,301 @@
+'use strict';
+
+/**
+ * The wave editor's canvas, drawn by the WaveDrom engine itself
+ * (wave-redesign spec §3).
+ *
+ * The editor used to paint its own picture of the waveform, and four of the
+ * seven defects in spec §5 were that picture disagreeing with the reader's.
+ * Here the engine draws the canvas — the same call the old preview panel
+ * made — so what the editor shows IS the output. This module owns that call
+ * and the coordinate bridge on top of it; the interaction layer (selection,
+ * cursor, dots, handles) is drawn by the layers above, in client coordinates
+ * this hands out.
+ *
+ * Coordinates, three spaces:
+ *   - engine units: the svg's viewBox (a cycle is 40, a lane 30). `layout`
+ *     and `measured` speak these.
+ *   - the svg is enlarged by `scale` (width/height multiplied, viewBox kept),
+ *     so one engine unit is `scale` CSS px.
+ *   - client: what pointer events carry. Converted by subtracting the svg's
+ *     client rect and dividing by `scale`.
+ *
+ * UMD: in the edit page lib/editor/server.js wraps this as the
+ * `window.__md2docWave['wave-canvas.js']` module; every dependency (the
+ * document, the engine, the theme API, geometry, codec) is handed in.
+ */
+
+/** How long a label can be beyond its segment: lib/wave-overflow.js `PAD`. */
+const LABEL_PAD = 6;
+/** The engine's cycle width in its own units (2 bricks of `lane.xs` 20). */
+const CYCLE_UNITS = 40;
+
+/**
+ * A plain, unfrozen copy of a document: the store's documents are frozen and
+ * the engine writes into the source it is given. Same bound as wave-panels.js
+ * `plainCopy`, which this mirrors.
+ */
+function plainCopy(value, depth) {
+  if (depth > 64 || value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) {
+    const out = [];
+    for (let i = 0; i < value.length; i++) out.push(plainCopy(value[i], depth + 1));
+    return out;
+  }
+  const out = {};
+  for (const key of Object.keys(value)) out[key] = plainCopy(value[key], depth + 1);
+  return out;
+}
+
+function createCanvas(opts) {
+  const d = opts.d;
+  const engine = opts.engine;
+  const theme = opts.theme || null;
+  const geometry = opts.geometry;
+  const codec = opts.codec;
+  const host = opts.host;
+  // Not 0: the document's own diagrams render at 0, and the ids the engine
+  // derives from the index would collide (wave-ui.js PREVIEW_INDEX explains
+  // the measurement). The prefix avoids `WaveDrom_Display_`, which the
+  // reader's own scripts (lightbox, recolour observer) treat as theirs.
+  const index = opts.index === undefined ? 9000 : opts.index;
+  const prefix = opts.prefix === undefined ? 'md2doc-wave-preview-' : opts.prefix;
+  const scale = opts.scale === undefined ? 1.5 : opts.scale;
+
+  const target = d.createElement('div');
+  target.id = prefix + index;
+  host.appendChild(target);
+
+  let svg = null;
+  let layout = null;
+  let measured = null;
+  let lastDoc = null;
+  let destroyed = false;
+
+  /**
+   * The canvas background the label backings take in dark (spec §5-5): the
+   * first ancestor of the host, the host included, whose computed background
+   * is not transparent.
+   */
+  function backing() {
+    for (let el = host; el && el.nodeType === 1; el = el.parentElement) {
+      const bg = getComputedStyle(el).backgroundColor;
+      if (bg && bg !== 'transparent' && !/^rgba\(.*,\s*0\)$/.test(bg)) return bg;
+    }
+    return undefined;
+  }
+
+  function recolour(dark) {
+    if (theme === null || svg === null) return;
+    theme.recolourSvg(svg, dark, { backing: backing() });
+  }
+
+  /**
+   * Whether a WaveDrom skin is on the page OUTSIDE this canvas. The engine
+   * empties the target before drawing, so a skin this canvas carried itself
+   * would be gone by the time the new svg looked for it. `socket` is asked
+   * for inside a WaveDrom svg's defs, not anywhere: a document's inline HTML
+   * may carry its own `id="socket"` (the same test the WaveDrom preview
+   * panel the redesign retired used to make).
+   */
+  function skinElsewhere() {
+    const found = d.querySelectorAll('svg.WaveDrom defs #socket');
+    for (let i = 0; i < found.length; i++) if (!target.contains(found[i])) return true;
+    return false;
+  }
+
+  function render(doc) {
+    if (engine === null || engine === undefined || typeof engine.RenderWaveForm !== 'function') {
+      return { ok: false, error: '這一頁沒有載入 WaveDrom' };
+    }
+    if (!target.isConnected) return { ok: false, error: '畫布還沒放進頁面' };
+    try {
+      engine.RenderWaveForm(index, plainCopy(doc, 0), prefix, skinElsewhere());
+    } catch (e) {
+      svg = null; layout = null; measured = null;
+      return { ok: false, error: 'WaveDrom 畫不出這份文件：' + String(e && e.message) };
+    }
+    svg = target.querySelector('svg');
+    if (svg === null) {
+      layout = null; measured = null;
+      return { ok: false, error: 'WaveDrom 沒有畫出圖' };
+    }
+    const w = Number(svg.getAttribute('width'));
+    const h = Number(svg.getAttribute('height'));
+    svg.setAttribute('width', String(w * scale));
+    svg.setAttribute('height', String(h * scale));
+    if (theme !== null && theme.isDark()) recolour(true);
+    lastDoc = doc;
+    measured = geometry.measureEngineSvg(svg, doc);
+    layout = geometry.layoutOf(doc, {
+      laneHeight: measured.laneHeight,
+      cycleWidth: CYCLE_UNITS,
+      nameColWidth: measured.xg + 0.5,
+      originY: measured.laneTops.length > 0 ? measured.laneTops[0] : measured.originY,
+    });
+    return { ok: true };
+  }
+
+  function origin() {
+    const r = svg.getBoundingClientRect();
+    return { left: r.left, top: r.top };
+  }
+
+  function toEngine(clientX, clientY) {
+    const o = origin();
+    return { x: (clientX - o.left) / scale, y: (clientY - o.top) / scale };
+  }
+
+  function cellAt(clientX, clientY) {
+    if (layout === null) return null;
+    const p = toEngine(clientX, clientY);
+    return geometry.cellAt(layout, p.x, p.y);
+  }
+
+  function boundaryAt(clientX, clientY) {
+    if (layout === null) return null;
+    const p = toEngine(clientX, clientY);
+    return geometry.boundaryAt(layout, p.x, p.y);
+  }
+
+  function cellRectClient(laneIndex, cycle) {
+    if (layout === null) return null;
+    const r = geometry.cellRect(layout, laneIndex, cycle);
+    if (r === null) return null;
+    const o = origin();
+    return { left: o.left + r.x * scale, top: o.top + r.y * scale,
+      width: r.width * scale, height: r.height * scale };
+  }
+
+  function anchorClient(laneIndex, cell) {
+    if (layout === null) return null;
+    const a = geometry.anchorOfCell(layout, laneIndex, cell);
+    if (a === null) return null;
+    const o = origin();
+    return { x: o.left + a.x * scale, y: o.top + a.y * scale };
+  }
+
+  function labelBoxes() {
+    if (measured === null) return [];
+    const o = origin();
+    return measured.labels.map(function (l) {
+      return {
+        laneIndex: l.laneIndex, slot: l.slot, text: l.text,
+        left: o.left + (l.x - l.width / 2) * scale, top: o.top + l.y * scale,
+        width: l.width * scale, height: l.height * scale,
+      };
+    });
+  }
+
+  /**
+   * Labels wider than their segment, by the width the engine really drew —
+   * the same rule as lib/wave-overflow.js `overflowOf` (label + LABEL_PAD
+   * against the segment's `cells * 40 * period`, times hscale), which can
+   * only estimate the width.
+   */
+  function overflow() {
+    if (measured === null || layout === null) return [];
+    const out = [];
+    for (const l of measured.labels) {
+      if (l.slot === null || l.cells === null) continue;
+      const row = layout.lanes[l.laneIndex];
+      const lane = row && row.lane && typeof row.lane === 'object' ? row.lane : {};
+      const p = Number(lane.period);
+      const unit = l.cells * CYCLE_UNITS * (p > 0 ? p : 1);
+      const need = l.width + LABEL_PAD;
+      if (need <= unit * layout.hscale) continue;
+      out.push({ laneIndex: l.laneIndex, slot: l.slot, label: l.text, needScale: Math.ceil(need / unit) });
+    }
+    return out;
+  }
+
+  /**
+   * The engine's own drawing of every `edge` entry it drew (Task 9): `[{index,
+   * path, label}]`, `index` the entry's position in `doc.edge`, `path` the
+   * engine's `gmark_<from>_<to>` path, `label` the `g` holding its label box
+   * or null. The engine writes them into `wavearcs_<index>` in entry order,
+   * each path followed by its label when the entry has one, and skips an
+   * entry when either letter names no anchor (render-arcs.js `archer`), so
+   * the walk below repeats exactly that test: the same split of the entry
+   * (`trim().split(/\s+/)`, the label taken from the UNtrimmed string) and
+   * the same anchor set (every non-`.` character of every lane's `node`).
+   * The lowercase letter labels the engine adds after the last edge are
+   * never reached. If a drawn element is not the one expected (an id that
+   * does not name the entry's letters), the walk stops there rather than
+   * pair an entry with another entry's drawing.
+   */
+  function arcs() {
+    if (svg === null || lastDoc === null || !Array.isArray(lastDoc.edge)) return [];
+    const group = svg.querySelector('g[id^="wavearcs_"]');
+    if (group === null) return [];
+    const events = new Set();
+    for (const p of codec.lanePaths(lastDoc)) {
+      const lane = geometry.valueAt(lastDoc, p);
+      const node = lane !== null && typeof lane === 'object' && typeof lane.node === 'string' ? lane.node : '';
+      for (const ch of node) if (ch !== '.') events.add(ch);
+    }
+    const kids = [];
+    for (let n = group.firstChild; n !== null; n = n.nextSibling) if (n.nodeType === 1) kids.push(n);
+    const out = [];
+    let k = 0;
+    for (let i = 0; i < lastDoc.edge.length; i++) {
+      const entry = lastDoc.edge[i];
+      if (typeof entry !== 'string') return out;
+      const head = entry.trim().split(/\s+/)[0];
+      const from = head.substr(0, 1);
+      const to = head.substr(-1, 1);
+      if (!events.has(from) || !events.has(to)) continue;
+      const path = kids[k];
+      if (path === undefined || path.tagName.toLowerCase() !== 'path' ||
+          path.getAttribute('id') !== 'gmark_' + from + '_' + to) return out;
+      k++;
+      let label = null;
+      if (entry.substring(head.length).substring(1) !== '') {
+        label = kids[k];
+        if (label === undefined || label.tagName.toLowerCase() !== 'g') return out;
+        k++;
+      }
+      out.push({ index: i, path: path, label: label });
+    }
+    return out;
+  }
+
+  // `onTheme` returns the unsubscribe (lib/theme/runtime.js); `destroy()`
+  // calls it, so a closed canvas is not kept alive by the theme's listener
+  // list — that listener reaches the host, and through it the whole editor
+  // overlay and its store, for the life of the page (final review M3).
+  let unsubscribe = null;
+  if (theme !== null && typeof theme.onTheme === 'function') {
+    const off = theme.onTheme(function (dark) { if (!destroyed) recolour(dark); });
+    if (typeof off === 'function') unsubscribe = off;
+  }
+
+  /** Stops following the theme and takes the canvas out of the host. */
+  function destroy() {
+    destroyed = true;
+    if (unsubscribe !== null) { unsubscribe(); unsubscribe = null; }
+    if (target.parentNode) target.parentNode.removeChild(target);
+    svg = null; layout = null; measured = null; lastDoc = null;
+  }
+
+  return {
+    render: render,
+    get svg() { return svg; },
+    get layout() { return layout; },
+    get measured() { return measured; },
+    get doc() { return lastDoc; },
+    scale: scale,
+    cellAt: cellAt,
+    boundaryAt: boundaryAt,
+    cellRectClient: cellRectClient,
+    anchorClient: anchorClient,
+    labelBoxes: labelBoxes,
+    overflow: overflow,
+    arcs: arcs,
+    destroy: destroy,
+  };
+}
+
+const api = { createCanvas: createCanvas, plainCopy: plainCopy };
+if (typeof module === 'object' && module.exports) module.exports = api;
+else if (typeof window !== 'undefined') window.md2docWaveCanvas = api;