@helping-ai-workflow/md2doc 2.8.0 → 2.10.0

package/README.md

@@ -127,6 +127,232 @@ the PDF output.
 | `md2html foo.md --open` | `md2doc foo.md` (open is default) |
 | `md2html *.md` (output next to source) | `md2doc *.md --out ./build/` (or accept temp output) |
 
+## Editing (`--edit`)
+
+```bash
+md2doc --edit foo.md              # serve foo.md in the browser editor, open a tab
+md2doc --edit foo.md bar.md       # one tab per file
+md2doc --edit foo.md --port 4000  # pin the server to a specific port
+md2doc --edit foo.md --no-open    # start the server without launching a browser tab
+```
+
+`--edit` starts a local (`127.0.0.1`-only) server and opens the rendered document in
+your browser. Click anywhere inside a paragraph, heading, list item, or table cell
+to place your cursor and start typing directly — no separate "select then edit" step.
+The block is live-marked as edited; focus leaving the block commits your changes
+automatically. Press `Ctrl+S` to save to disk explicitly.
+
+### Direct editing: click to type
+
+Every paragraph, heading, list, and table cell is editable by clicking inside it.
+The rendered formatting (bold, italic, code, links) displays as you type; no
+Markdown syntax characters are shown. This applies to any block that doesn't
+contain unsupported content (see "Degraded blocks" below).
+
+| Block type | Interaction |
+|---|---|
+| Paragraph | Click to place caret, type; Enter commits, Esc reverts |
+| Heading | Click to place caret, type; Enter commits, Esc reverts |
+| List | Click to place caret, type; list-specific keys below |
+| Table | Click any cell to edit; Tab/Shift+Tab navigate between cells |
+
+### ⠿ Block menu
+
+Every block has a ⠿ button on its left edge. Click it to open a menu with block-level
+operations:
+
+| Item | Applies to | Action |
+|---|---|---|
+| **−** (minus) | Heading only | Decrease heading level (# → ... → #####) |
+| **+** (plus) | Heading only | Increase heading level |
+| **MD 原始碼** | All blocks | Discard in-progress edits, switch to raw Markdown source editing |
+| **刪除** | All blocks | Delete the block entirely (absorbs one adjacent blank line; one Ctrl+Z restores it exactly) |
+| **✕** | All blocks | Close the menu |
+
+The **MD 原始碼** button is the escape hatch: it reverts any unsaved typing in the
+current block and opens the raw Markdown editor instead, letting you make changes
+WYSIWYG cannot express.
+
+### ＋ Insert menu
+
+Every block also has a ＋ button, stacked just above the ⠿ handle in the same left
+gutter. Click it to open a menu for inserting a new block directly below:
+
+| Item | Inserts |
+|---|---|
+| **段落** | An empty paragraph |
+| **標題** | An empty `##` heading |
+| **清單** | An empty single-item list |
+| **表格** | A minimal 2×2 table skeleton |
+| **程式碼** | An empty fenced code block |
+
+The new block is inserted below the block whose ＋ you clicked, and the cursor lands
+directly in it — the first (body) cell for a table, the raw source editor for a code
+block, and the always-on WYSIWYG surface (pre-selected, so your first keystroke
+replaces the placeholder) for everything else. The whole insert is a single Ctrl+Z
+step — one undo removes the block entirely.
+
+### Paragraph and heading editing
+
+Click inside a paragraph or heading to place your cursor. Type and format text
+normally; the rendered marks (bold, italic, code, links) show as you type.
+
+**Selection toolbar**: when you select text inside a paragraph or heading, a
+floating toolbar appears with formatting buttons:
+
+| Button | Action |
+|---|---|
+| **B** | Toggle bold (`**text**`) |
+| **I** | Toggle italic (`*text*`) |
+| **`<>`** | Wrap selection in backticks (`` `code` ``) |
+| **🔗** | Wrap selection as a link; click to edit the URL |
+
+**Key shortcuts**:
+
+| Key | Action |
+|---|---|
+| Enter | Commit and close the editor |
+| Shift + Enter | Insert a line break within the paragraph |
+| Esc | Revert all edits and close the editor |
+| Ctrl + Z | Step backward through the paragraph's local edit history, then cascade to document-level undos once exhausted |
+| Ctrl + Y (or Ctrl + Shift + Z) | Step forward through the paragraph's local edit history, then cascade to document-level redos once exhausted |
+
+### List editing
+
+Click inside a list item to place your cursor and type. Lists support structural editing:
+
+| Key | Action |
+|---|---|
+| Enter | Split the current item into two siblings at the caret; empty item + Enter removes it and ends the burst |
+| Shift + Enter | Insert a line break (`<br>`) within the item (does not split) |
+| Tab | Indent the current item (becomes a child of the previous sibling; no-op if no previous sibling) |
+| Shift + Tab | Outdent the current item (moves after its parent; no-op at top level) |
+| Esc | Revert all edits and close the list |
+| Ctrl + Z / Ctrl + Y | Step through the list's local edit history, then cascade to document-level history |
+
+An empty list (all items removed) is cleaned up automatically — the block is deleted
+entirely and the document structure stays consistent.
+
+### Table editing
+
+Click any table cell to edit it. The table is treated as a single editing unit —
+focus remains inside the table until you press Esc, click outside, or navigate away.
+
+**Cell navigation**:
+
+| Key / Action | Effect |
+|---|---|
+| Click a cell | Move to that cell and edit |
+| Tab | Move to the next cell (left-to-right, row by row; no-op — stays put — on the last cell) |
+| Shift + Tab | Move to the previous cell |
+| Enter | Insert a line break (`<br>`) within the cell (does NOT commit the table) |
+| Esc | Revert the entire table session (all cells) and discard all changes |
+| Ctrl + Z / Ctrl + Y | Step through the table's local edit history, then cascade to document-level history |
+
+**Column grip**: hover any cell in a column — a small horizontal 6-dot grip handle
+appears just above it (Notion-style affordance, replacing the old edge-hover-only
+target). Click the grip to open the column menu:
+
+| Option | Action |
+|---|---|
+| **刪除欄** | Delete the column (last column protected) |
+| **對齊** | Cycle alignment: left → center → right → left (no unset state; use Ctrl+Z to revert a cycle) |
+
+A **＋** insert bubble separately appears when you hover the top boundary between
+two columns — click it to insert an empty column there.
+
+**Row grip**: hover any cell in a body row — a small vertical 6-dot grip handle
+appears just left of it (the header row never gets one; it isn't deletable or
+draggable). Click the grip to open the row menu:
+
+| Option | Action |
+|---|---|
+| **刪除列** | Delete the row (header row and last body row protected) |
+| *Drag* | Press and hold the row grip and drag up/down; drop to reorder (body rows only; header fixed) |
+
+A **＋** insert bubble separately appears when you hover the left boundary between
+two rows — click it to insert an empty row there.
+
+**Edited tables emit minimal form**: tables that you edit are saved with single-space
+padding and minimal separators (`|---|`) to keep the Markdown readable and
+version-control-friendly.
+
+### Degraded blocks: code, diagrams, images, math
+
+Blocks containing content WYSIWYG cannot represent (code fences, Mermaid/Graphviz/
+WaveDrom diagrams, images, LaTeX math, or unstyled HTML) automatically degrade to
+raw-edit mode: click the block to open the raw Markdown source in a textarea, make
+your changes, then press `Ctrl+Enter` to commit or `Esc` to cancel.
+
+If a WYSIWYG session encounters unsupported content mid-edit (e.g., via a rich
+paste), it automatically falls back to raw-edit with the block's untouched
+on-disk source, preserving your unsaved work context.
+
+### Burst undo: local history + cascade
+
+Ctrl+Z / Ctrl+Y step through a block's local edit history first (the changes you
+made in the current editing session). Once that history is exhausted, the next
+Ctrl+Z cascades out to the document-level undo stack, covering all committed edits.
+This lets you undo/redo recent changes within a block without affecting work in
+other blocks.
+
+### Whole-document controls
+
+| Key / control | Action |
+|---|---|
+| `Ctrl`/`⌘` + `S` | Save the document to disk (explicit; changes commit locally when focus leaves) |
+| `Ctrl`/`⌘` + `Z` | Undo: first steps through the focused block's local history, then cascades to document level |
+| `Ctrl`/`⌘` + `Y` (or `Ctrl`/`⌘` + `Shift` + `Z`) | Redo: mirrors undo's cascade behavior |
+| Click outside any block | Commit any open block if changed, dismiss the ⠿/＋ menu |
+| `Esc` (at document level, not in an open block) | Close the ⠿/＋ menu |
+
+### Auto-commit on focus change
+
+When focus leaves a block:
+- If the block is **unchanged**, it closes silently.
+- If the block is **changed**, it commits automatically to the undo stack (but not to disk — you must press Ctrl+S for that).
+
+This means switching between blocks flows naturally — you never get stuck waiting to
+confirm or cancel.
+
+### Save and conflict handling
+
+**Save is explicit, not autosave**. Your changes are committed to the undo stack
+immediately when you press Enter or focus leaves a block, but they're not written
+to disk until you press `Ctrl+S`.
+
+**Conflict detection**: each save carries the file's last-known modification time.
+If the file on disk has changed since the page loaded (edited elsewhere, or saved
+from another tab), the save is rejected with a conflict banner instead of silently
+overwriting — reload the page to pick up the newer content, then re-apply your edit.
+
+### Fidelity guarantee
+
+Only the lines inside the block(s) you actually commit are rewritten. Every other
+line — including whitespace-sensitive formatting like padded table columns, trailing
+spaces, and the file's original EOF-newline state — is left byte-for-byte untouched,
+whether you save with zero edits or after several. This applies both to unchanged
+blocks and to blocks you open and then revert.
+
+### Known Phase-3 limitations
+
+**First diagram/math type requires reload**: if a committed edit introduces the
+*first* occurrence of a diagram type (Mermaid or WaveDrom) that the document didn't
+already contain when the page was loaded, that diagram library was never embedded
+into the page, so the new block renders as raw source until you reload the browser
+tab (no need to restart `md2doc --edit`). The same applies to math: if a committed
+edit introduces the document's *first* `math` fence or `$…$`/`$$…$$` expression,
+the KaTeX stylesheet was never injected, so the equation renders unstyled until you
+reload the tab.
+
+**Alignment cycle has no unset state**: the **對齊** button cycles through left,
+center, and right alignment. To revert an unwanted alignment, use Ctrl+Z.
+
+---
+
+`--edit` does not support directory inputs yet (planned for a later phase) and
+cannot be combined with `--html` / `--pdf` / `--out` / `--bake-svg`.
+
 ## Supported diagram types
 
 Embedded in fenced code blocks inside your Markdown:

package/bin/md2doc.js

@@ -33,6 +33,8 @@ function printHelp() {
         '  --no-open           Skip the viewer launch.',
         '  --quiet             Suppress per-file progress messages.',
         '  --bake-svg          Pre-render mermaid/wavedrom to inert SVG (HTML output only; needs Chromium).',
+        '  --edit              Serve listed .md files in the browser editor (localhost).',
+        '  --port <n>          Pin the editor server port (only with --edit).',
         '  --version, -v       Print version.',
         '  --help, -h          Print this help.',
         ''
@@ -47,6 +49,8 @@ function parseArgs(argv) {
     let openExplicit = null; // null = unset; true/false = user-specified
     let quiet = false;
     let bakeSvg = false;
+    let edit = false;
+    let port = null;
 
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -64,6 +68,21 @@ function parseArgs(argv) {
         if (a === '--no-open') { openExplicit = false; continue; }
         if (a === '--quiet') { quiet = true; continue; }
         if (a === '--bake-svg') { bakeSvg = true; continue; }
+        if (a === '--edit') { edit = true; continue; }
+        if (a === '--port') {
+            i++;
+            if (i >= argv.length) {
+                process.stderr.write('error: --port requires a value\n');
+                process.exit(2);
+            }
+            const n = Number(argv[i]);
+            if (!Number.isInteger(n) || n < 0) {
+                process.stderr.write('error: --port must be a non-negative integer\n');
+                process.exit(2);
+            }
+            port = n;
+            continue;
+        }
         if (a === '--out') {
             if (out !== null) {
                 process.stderr.write('error: --out specified more than once\n');
@@ -105,7 +124,7 @@ function parseArgs(argv) {
         open = (out === null);
     }
 
-    return { inputs, formats, formatsExplicit, out, open, quiet, bakeSvg };
+    return { inputs, formats, formatsExplicit, out, open, quiet, bakeSvg, edit, port };
 }
 
 function shortHash(absPath) {
@@ -200,38 +219,7 @@ function resolveOutputs(args) {
     return pairs;
 }
 
-function isWSL() {
-    if (process.platform !== 'linux') return false;
-    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
-    try {
-        return fs.existsSync('/proc/sys/fs/binfmt_misc/WSLInterop');
-    } catch (_) {
-        return false;
-    }
-}
-
-function openViewer(filePath) {
-    const platform = process.platform;
-    let cmd, args;
-    if (platform === 'darwin') {
-        cmd = 'open'; args = [filePath];
-    } else if (platform === 'win32') {
-        cmd = 'cmd'; args = ['/c', 'start', '""', filePath];
-    } else if (isWSL()) {
-        const r = spawnSync('wslpath', ['-w', filePath], { encoding: 'utf8' });
-        if (r.status === 0 && r.stdout) {
-            cmd = 'explorer.exe'; args = [r.stdout.trim()];
-        } else {
-            cmd = 'xdg-open'; args = [filePath];
-        }
-    } else {
-        cmd = 'xdg-open'; args = [filePath];
-    }
-    const r = spawnSync(cmd, args, { stdio: 'ignore' });
-    if (r.error) {
-        process.stderr.write('warning: could not launch viewer for ' + filePath + ': ' + r.error.message + '\n');
-    }
-}
+const { openViewer } = require('../lib/editor/open.js');
 
 function main() {
     const args = parseArgs(process.argv.slice(2));
@@ -243,6 +231,31 @@ function main() {
         }
     }
 
+    if (args.edit) {
+        if (args.formatsExplicit || args.out !== null || args.bakeSvg) {
+            process.stderr.write('error: --edit cannot be combined with --html/--pdf/--out/--bake-svg\n');
+            process.exit(2);
+        }
+        for (const input of args.inputs) {
+            if (!fs.existsSync(input)) {
+                process.stderr.write('error: input not found: ' + input + '\n');
+                process.exit(1);
+            }
+            if (fs.statSync(input).isDirectory()) {
+                process.stderr.write('error: --edit directory mode is not implemented yet (Phase 3)\n');
+                process.exit(2);
+            }
+        }
+        const { startEditSession } = require('../lib/editor/cli.js');
+        startEditSession({ files: args.inputs, port: args.port, open: args.open, quiet: args.quiet })
+            .catch((e) => { process.stderr.write('error: ' + e.message + '\n'); process.exit(1); });
+        return; // do not fall through to render pipeline
+    }
+    if (args.port !== null) {
+        process.stderr.write('error: --port is only valid with --edit\n');
+        process.exit(2);
+    }
+
     const pairs = resolveOutputs(args);
     const outputs = [];
     for (const { input, output } of pairs) {

package/lib/editor/blockmap.js

@@ -0,0 +1,75 @@
+'use strict';
+const { marked } = require('marked');
+
+// Top-level marked tokens → 1-indexed inclusive line ranges.
+// `space` tokens (blank-line runs) advance the cursor but are not blocks.
+// A token's `raw` may include trailing newlines (blank lines marked folded
+// in); the block's endLine excludes those so ranges never claim blank lines
+// that separate blocks.
+
+function trimmedLineCount(raw) {
+  const content = raw.replace(/\n+$/, '');
+  return content === '' ? 1 : content.split('\n').length;
+}
+
+// Recursively emit one `li` block per list item at every depth.
+// Recursion order (mirrored by Task 4's render walk):
+//   1. Push the item's own block.
+//   2. Recurse into that item's nested child lists, left-to-right.
+//   3. Move on to the next sibling item.
+// `nextId` is a shared box { v: <int> } so ids stay 0..n-1 in document order.
+function pushListItemBlocks(listToken, cursor, indent, blocks, nextId) {
+  for (const item of listToken.items) {
+    const childListTokens = item.tokens.filter((t) => t.type === 'list');
+    const totalSpan = trimmedLineCount(item.raw);
+    const childSpan = childListTokens.reduce((s, t) => s + trimmedLineCount(t.raw), 0);
+    const ownSpan = totalSpan - childSpan;
+    const block = {
+      id: nextId.v++,
+      type: 'li',
+      startLine: cursor,
+      endLine: cursor + ownSpan - 1,
+      listType: item.task ? 'task' : (listToken.ordered ? 'ol' : 'ul'),
+      indent,
+    };
+    if (item.task) block.checked = !!item.checked;
+    blocks.push(block);
+    let childCursor = cursor + ownSpan;
+    for (const ct of childListTokens) {
+      pushListItemBlocks(ct, childCursor, indent + 1, blocks, nextId);
+      childCursor += (ct.raw.match(/\n/g) || []).length;
+    }
+    // advance cursor by full item raw newlines; fall back to totalSpan if raw
+    // has no trailing newline (EOF item).
+    cursor += (item.raw.match(/\n/g) || []).length || totalSpan;
+  }
+}
+
+function buildBlockMap(mdText) {
+  const tokens = marked.lexer(mdText);
+  const blocks = [];
+  let cursor = 1; // current line number of the token's first character
+  const nextId = { v: 0 };
+  for (const t of tokens) {
+    const rawNewlines = (t.raw.match(/\n/g) || []).length;
+    if (t.type === 'list') {
+      pushListItemBlocks(t, cursor, 0, blocks, nextId);
+    } else if (t.type !== 'space') {
+      const content = t.raw.replace(/\n+$/, '');
+      const span = content === '' ? 1 : content.split('\n').length;
+      blocks.push({
+        id: nextId.v++,
+        type: t.type,
+        startLine: cursor,
+        endLine: cursor + span - 1,
+      });
+    }
+    // advance by full raw (including folded trailing blank lines).
+    // If raw has no trailing newline (EOF), the next token doesn't exist,
+    // so the off-by-one is unobservable.
+    cursor += rawNewlines;
+  }
+  return { blocks, lineCount: mdText.split('\n').length };
+}
+
+module.exports = { buildBlockMap };

package/lib/editor/cli.js

@@ -0,0 +1,23 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { createEditorServer } = require('./server.js');
+
+const CLIENT_SRC = fs.readFileSync(path.join(__dirname, 'client.js'), 'utf8');
+
+async function startEditSession({ files, port = null, open = true, quiet = false }) {
+  const srv = await createEditorServer({
+    files,
+    clientJs: CLIENT_SRC,
+    listenPort: port === null ? 0 : port,
+  });
+  const urls = files.map((f) => srv.urlFor(f));
+  for (const u of urls) process.stdout.write(u + '\n');
+  if (open) {
+    const { openViewer } = require('./open.js');
+    for (const u of urls) openViewer(u);
+  }
+  srv.server.on('close', () => process.exit(0));
+  return srv;
+}
+module.exports = { startEditSession };