mdv-live 0.5.5 → 0.5.9

package/src/api/marpNote/readDeck.js

@@ -0,0 +1,42 @@
+/**
+ * Resolve and read a deck file safely (path-traversal + symlink-following
+ * defenses). Returns { rawSource, stat, realPath }. Throws coded errors:
+ *   PATH_INVALID / NOT_FOUND.
+ */
+
+import * as fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import * as path from 'node:path';
+import { validatePath, validatePathReal } from '../../utils/path.js';
+import { mkError } from '../../utils/errors.js';
+
+export async function readDeckSafely(rootDir, relativePath) {
+  if (!validatePath(relativePath, rootDir)) throw mkError('PATH_INVALID');
+  const ok = await validatePathReal(relativePath, rootDir);
+  if (!ok) throw mkError('PATH_INVALID');
+
+  const fullPath = path.resolve(rootDir, relativePath);
+  let realPath;
+  try {
+    realPath = await fs.realpath(fullPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') throw mkError('NOT_FOUND');
+    throw err;
+  }
+
+  let fd;
+  try {
+    fd = await fs.open(realPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  } catch (err) {
+    if (err.code === 'ELOOP') throw mkError('PATH_INVALID', 'symlink at terminal');
+    if (err.code === 'ENOENT') throw mkError('NOT_FOUND');
+    throw err;
+  }
+  try {
+    const stat = await fd.stat();
+    const rawSource = await fd.readFile('utf-8');
+    return { rawSource, stat, realPath };
+  } finally {
+    await fd.close();
+  }
+}

package/src/api/marpNote.js

@@ -0,0 +1,40 @@
+/**
+ * /api/marp/decks/:encodedPath endpoint family — orchestration only.
+ *
+ * Routing:
+ *   GET    /api/marp/decks/:encodedPath              → handleGet
+ *   PUT    /api/marp/decks/:encodedPath/slides/:N/note  → handlePut
+ *   OPTIONS  ...                                     → CORS preflight (same-origin only)
+ */
+
+import { sendError } from '../utils/errors.js';
+import { buildAllowedHosts, checkHost, checkOrigin } from './marpNote/guards.js';
+import { makeGetHandler } from './marpNote/handleGet.js';
+import { makePutHandler } from './marpNote/handlePut.js';
+
+function makeOptionsHandler(allowedHosts) {
+  return function handleOptions(req, res) {
+    const hostErr = checkHost(req, allowedHosts);
+    if (hostErr) return sendError(res, hostErr);
+    const originErr = checkOrigin(req, allowedHosts);
+    if (originErr) return sendError(res, originErr);
+    res.setHeader('Access-Control-Allow-Methods', 'GET, PUT, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, If-Match');
+    // Note: deliberately NOT setting Allow-Private-Network; PNA is rejected.
+    return res.status(204).end();
+  };
+}
+
+export function setupMarpNoteRoutes(app, options = {}) {
+  const port = options.port || 8080;
+  const allowedHosts = buildAllowedHosts(port);
+  const rootDir = () => app.locals.rootDir;
+
+  const handleOptions = makeOptionsHandler(allowedHosts);
+  app.options('/api/marp/decks/:encodedPath/slides/:slideIndex/note', handleOptions);
+  app.options('/api/marp/decks/:encodedPath', handleOptions);
+
+  app.get('/api/marp/decks/:encodedPath', makeGetHandler({ rootDir, allowedHosts }));
+  app.put('/api/marp/decks/:encodedPath/slides/:slideIndex/note',
+    makePutHandler({ rootDir, allowedHosts }));
+}

package/src/api/pdf.js

@@ -1,25 +1,104 @@
-/**
- * PDF Export API
- * Uses marp-cli for Marp presentations
- */
-
-import { execFile } from 'child_process';
-import { promisify } from 'util';
+import { spawn } from 'child_process';
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import os from 'os';
-import { validatePath } from '../utils/path.js';
-
-const execFileAsync = promisify(execFile);
-const marpBin = path.join(
-  path.dirname(fileURLToPath(import.meta.url)),
-  '..',
-  '..',
-  'node_modules',
-  '.bin',
-  'marp'
-);
+import { createRequire } from 'module';
+import { isMarp } from '../rendering/markdown.js';
+import { validatePath, validatePathReal } from '../utils/path.js';
+import { resolvePdfOptions } from '../styles/index.js';
+
+const require = createRequire(import.meta.url);
+const highlightStylesheet = path.resolve(path.dirname(require.resolve('highlight.js')), '..', 'styles', 'atom-one-dark.css');
+const binDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'node_modules', '.bin');
+const marpBin = path.join(binDir, 'marp');
+const mdToPdfBin = path.join(binDir, 'md-to-pdf');
+const PDF_EXPORT_TIMEOUT_MS = 180000;
+
+/**
+ * Spawn a PDF tool with stdin closed.
+ *
+ * 注意: execFile は stdio オプションを受け付けない (Node 仕様)。md-to-pdf は
+ * 内部で get-stdin を呼ぶため、stdin が pipe のままだと EOF を永遠に待ち続けて
+ * ハングする。spawn で stdin を 'ignore' (= /dev/null) に明示的に縛る。
+ */
+function runPdfTool(bin, args, { cwd } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+    }, PDF_EXPORT_TIMEOUT_MS);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve({ stdout, stderr });
+      } else {
+        const err = new Error(`${path.basename(bin)} exited with code=${code} signal=${signal}`);
+        err.code = code;
+        err.signal = signal;
+        err.stdout = stdout;
+        err.stderr = stderr;
+        reject(err);
+      }
+    });
+  });
+}
+
+/**
+ * Resolve an optional user-selected file path under the server root.
+ * @param {string | undefined} relativePath - Path supplied by the web UI.
+ * @param {string} rootDir - Server root directory.
+ * @returns {Promise<string | null>} Absolute path or null.
+ */
+async function resolveOptionalUserFile(relativePath, rootDir) {
+  if (!relativePath) return null;
+  if (!await validatePathReal(relativePath, rootDir)) {
+    throw new Error(`Access denied: ${relativePath}`);
+  }
+  const fullPath = path.join(rootDir, relativePath);
+  const stat = await fs.stat(fullPath);
+  if (!stat.isFile()) {
+    throw new Error(`Not a file: ${relativePath}`);
+  }
+  return fullPath;
+}
+
+/**
+ * Export a regular markdown document with md-to-pdf.
+ * @param {string} inputPath - Source markdown file.
+ * @param {string} outputPath - Temporary output path.
+ * @param {string | null} stylesheetPath - Optional custom CSS file.
+ * @param {string | null} pdfOptionsPath - Optional PDF options JSON file.
+ * @returns {Promise<void>}
+ */
+async function exportMarkdownPdf(inputPath, outputPath, stylesheetPath, pdfOptionsPath) {
+  const pdfOptions = await resolvePdfOptions(pdfOptionsPath || undefined);
+  const args = [inputPath, '--pdf-options', JSON.stringify(pdfOptions)];
+
+  if (stylesheetPath) {
+    args.push('--stylesheet', highlightStylesheet);
+    args.push('--stylesheet', stylesheetPath);
+    args.push('--highlight-style', 'atom-one-dark');
+  }
+
+  await runPdfTool(mdToPdfBin, args, { cwd: path.dirname(inputPath) });
+
+  const generatedPdf = inputPath.replace(/\.(md|markdown)$/i, '.pdf');
+  await fs.rename(generatedPdf, outputPath);
+}
 
 /**
  * Setup PDF export routes
@@ -30,7 +109,7 @@ export function setupPdfRoutes(app) {
   const { rootDir } = app.locals;
 
   app.post('/api/pdf/export', async (req, res) => {
-    const { filePath } = req.body;
+    const { filePath, stylePath, pdfOptionsPath } = req.body;
 
     if (!filePath) {
       return res.status(400).json({ error: 'filePath is required' });
@@ -53,7 +132,17 @@ export function setupPdfRoutes(app) {
     const outputFileName = `${baseName}.pdf`;
 
     try {
-      await execFileAsync(marpBin, [fullPath, '-o', outputPath, '--html', '--allow-local-files', '--no-stdin'], { timeout: 60000 });
+      const content = await fs.readFile(fullPath, 'utf-8');
+      if (isMarp(content)) {
+        await runPdfTool(marpBin, [fullPath, '-o', outputPath, '--html', '--allow-local-files', '--no-stdin']);
+      } else {
+        const [stylesheetPath, resolvedPdfOptionsPath] = await Promise.all([
+          resolveOptionalUserFile(stylePath, rootDir),
+          resolveOptionalUserFile(pdfOptionsPath, rootDir),
+        ]);
+        await exportMarkdownPdf(fullPath, outputPath, stylesheetPath, resolvedPdfOptionsPath);
+      }
+
       res.download(outputPath, outputFileName, async (err) => {
         if (err) {
           console.error('Download error:', err);

package/src/concurrency/pathLock.js

@@ -0,0 +1,39 @@
+/**
+ * Promise-chain mutex keyed by an arbitrary string.
+ *
+ * Replaces the naive Map-based implementation in api/marpNote.js, which the
+ * concurrency audit identified as susceptible to a thundering-herd race:
+ * with two or more waiters, all of them could observe an empty map after
+ * the previous holder cleared it and then proceed in parallel.
+ *
+ * This implementation chains every new request onto the tail of the
+ * existing promise chain for the key, guaranteeing strict FIFO order.
+ */
+
+const tails = new Map(); // key → Promise (tail of the chain)
+
+export async function withLock(key, fn) {
+  const previous = tails.get(key) || Promise.resolve();
+
+  // Create the next tail BEFORE starting fn so subsequent callers chain after us.
+  let release;
+  const next = new Promise((resolve) => { release = resolve; });
+  tails.set(key, next);
+
+  try {
+    // Wait for the previous chain to settle (success OR failure).
+    await previous.catch(() => {});
+    return await fn();
+  } finally {
+    release();
+    // If we are still the tail, drop the entry so the map doesn't grow
+    // unboundedly. If a subsequent caller has already replaced us as the
+    // tail, leave their entry intact.
+    if (tails.get(key) === next) tails.delete(key);
+  }
+}
+
+/** Test helper. */
+export function _activeKeyCount() {
+  return tails.size;
+}

package/src/rendering/index.js

@@ -7,6 +7,8 @@ import path from 'path';
 import { getFileType } from '../utils/fileTypes.js';
 import { renderMarkdown, isMarp } from './markdown.js';
 import { renderMarp } from './marp.js';
+import { analyseSource } from '../utils/lineMath.js';
+import { makeEtag } from '../utils/etag.js';
 
 /**
  * Escape HTML entities
@@ -99,10 +101,16 @@ export async function renderFile(filePath, relativeDir) {
  */
 function renderMarkdownFile(content, relativeDir) {
   if (isMarp(content)) {
-    const { html, css } = renderMarp(content);
+    const { html, css, notes, notesMultiplicity } = renderMarp(content);
+    const lineInfo = analyseSource(content);
     return {
       content: rewriteMediaPaths(html, relativeDir),
       css,
+      notes,
+      notesMultiplicity,
+      etag: makeEtag(content),
+      lineEnding: lineInfo.lineEnding,
+      hasBom: lineInfo.hasBom,
       raw: content,
       fileType: 'markdown',
       isMarp: true

package/src/rendering/markdown.js

@@ -90,23 +90,16 @@ md.enable('strikethrough');
 // Enable task lists (checkboxes)
 md.use(taskLists);
 
-// Pattern to detect Marp frontmatter (must be at very start of file, not using 'm' flag)
-const MARP_PATTERN = /^---\s*\n[\s\S]*?marp:\s*true[\s\S]*?\n---/;
-
 // Pattern to detect YAML frontmatter at start of file
 const FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*(\n|$)/;
 
 // Pattern for Mermaid code blocks
 const MERMAID_PATTERN = /```mermaid\s*\n([\s\S]*?)\n```/g;
 
-/**
- * Check if content is a Marp presentation
- * @param {string} content - Markdown content
- * @returns {boolean}
- */
-export function isMarp(content) {
-  return MARP_PATTERN.test(content);
-}
+// Re-export the SSOT version of isMarp so callers don't import a separate
+// (and previously slightly different) regex from this module.
+import { isMarp } from './marpitAdapter.js';
+export { isMarp };
 
 /**
  * Convert YAML frontmatter to code block for display

package/src/rendering/marp.js

@@ -1,49 +1,28 @@
 /**
- * Marp rendering using @marp-team/marp-core
+ * Marp rendering — thin compat layer over `marpitAdapter.renderDeck`.
+ *
+ * Historically this file owned its own Marp instance. The audit flagged
+ * that as a SOLID/DRY violation: the adapter already owns the canonical
+ * instance, and having two of them risked subtle directive-state drift
+ * between code paths. We now delegate to the adapter.
  *
  * IMPORTANT: Do not modify Marp's HTML output structure.
  * The CSS depends on the exact structure: div.marpit > svg > foreignObject > section
  */
 
-import { Marp } from '@marp-team/marp-core';
-
-// Initialize Marp with full HTML support
-const marp = new Marp({
-  html: true,
-  math: true,
-  markdown: {
-    html: true,
-    breaks: false,
-    linkify: true,
-  }
-});
-
-// Disable indented code blocks (4-space indent → code)
-// This allows HTML with indentation to render properly
-marp.markdown.disable('code');
+import { renderDeck } from './marpitAdapter.js';
 
 /**
- * Render Marp presentation to HTML
+ * Render Marp presentation to HTML.
  * @param {string} content - Markdown content with Marp frontmatter
- * @returns {{ html: string, css: string, slideCount: number }}
+ * @returns {{ html: string, css: string, slideCount: number, notes: string[], notesMultiplicity: number[] }}
  */
 export function renderMarp(content) {
-  const { html, css } = marp.render(content);
-
-  // Count slides by counting <section> tags
-  const slideCount = (html.match(/<section[^>]*>/g) || []).length;
-
-  // Return Marp's HTML output AS-IS to preserve CSS selector compatibility
-  return {
-    html,
-    css,
-    slideCount
-  };
+  return renderDeck(content);
 }
 
 /**
- * Get available Marp themes
- * @returns {string[]} Theme names
+ * Get available Marp themes.
  */
 export function getThemes() {
   return ['default', 'gaia', 'uncover'];

package/src/rendering/marpNoteWriter.js

@@ -0,0 +1,156 @@
+/**
+ * Speaker-note rewriter — pure function operating on a parsed deck.
+ *
+ * Strategy:
+ *   - At most ONE speaker note per slide is supported by auto-save (see
+ *     Multi-note Guard below). The Plan caps editing to single-note slides
+ *     so that the join-of-comments string round-trips losslessly.
+ *   - Rewriting replaces or removes the existing single note token's line
+ *     range, or appends a new comment if the slide has no note.
+ *   - Marp directives are left untouched (they are not in `classifiedNotes`,
+ *     so `pickNoteComments` filters them out).
+ */
+
+import { pickNoteComments } from './marpitAdapter.js';
+import { lineRangeToOffsets } from '../utils/lineMath.js';
+import { mkError } from '../utils/errors.js';
+
+/** Speaker notes are stored as HTML comments. Reject text that would close
+ *  or invalidate the comment on the markdown side. */
+export function validateNoteText(text) {
+  if (typeof text !== 'string') return 'note must be a string';
+  if (text.length > 64 * 1024) return 'note exceeds 64 KiB';
+  if (/\u0000/.test(text)) return 'note contains NUL';
+  if (text.includes('-->')) return 'note cannot contain "-->"';
+  if (text.includes('--!>')) return 'note cannot contain "--!>"';
+  if (/--\s*$/.test(text)) return 'note cannot end with "--"';
+  return null;
+}
+
+export function formatNoteComment(text, lineEnding) {
+  const trimmed = text.trim();
+  if (trimmed.includes('\n') || trimmed.includes('\r')) {
+    // Normalise embedded newlines to the file's line ending.
+    const normalised = trimmed.replace(/\r\n|\r|\n/g, lineEnding);
+    return '<!--' + lineEnding + normalised + lineEnding + '-->';
+  }
+  return '<!-- ' + trimmed + ' -->';
+}
+
+/**
+ * Find the line index where a new note comment should be inserted into a
+ * slide that has no existing note. Walks backwards from `endLine - 1` and
+ * returns the line *after* the last non-blank line.
+ */
+function findInsertionLine(rawSource, lineStarts, totalLines, range) {
+  let line = Math.min(range.endLine, totalLines) - 1;
+  while (line > range.startLine) {
+    const start = lineStarts[line];
+    const end = line + 1 < lineStarts.length ? lineStarts[line + 1] : rawSource.length;
+    const text = rawSource.slice(start, end);
+    if (text.replace(/\r?\n$/, '').trim().length > 0) {
+      return line + 1; // insert immediately after this content line
+    }
+    line--;
+  }
+  return range.startLine + 1; // default: just after the slide's first line
+}
+
+/**
+ * @param {string} rawSource
+ * @param {number} slideIndex
+ * @param {string} newNote  empty string == remove
+ * @param {ReturnType<import('./marpitAdapter.js').parseDeck>} parsed
+ * @param {ReturnType<import('../utils/lineMath.js').analyseSource>} lineInfo
+ * @returns {{ source: string, changed: boolean }}
+ */
+export function rewriteSlideNote(rawSource, slideIndex, newNote, parsed, lineInfo) {
+  if (slideIndex < 0 || slideIndex >= parsed.slideCount) {
+    throw mkError('OUT_OF_RANGE', `slideIndex ${slideIndex} out of range`);
+  }
+  const reason = validateNoteText(newNote);
+  if (reason) throw mkError('INVALID_NOTE', reason);
+
+  const noteStrings = parsed.classifiedNotes[slideIndex] || [];
+  const candidates = parsed.commentsBySlide[slideIndex] || [];
+  const noteComments = pickNoteComments(candidates, noteStrings);
+
+  // Multi-note Guard (defense-in-depth): even if the client misbehaves and
+  // POSTs against a slide that has multiple speaker notes, refuse — joining
+  // them into a single string is lossy round-trip.
+  if (noteComments.length > 1) {
+    throw mkError(
+      'MULTI_NOTE_READONLY',
+      'slide has multiple speaker notes; auto-save disabled'
+    );
+  }
+
+  const totalLines = parsed.slideRanges[parsed.slideCount - 1].endLine;
+  const { lineStarts } = lineInfo;
+  const lineEnding = lineInfo.lineEnding;
+  const trimmedNew = newNote.trim();
+
+  if (trimmedNew === '' && noteComments.length === 0) {
+    return { source: rawSource, changed: false };
+  }
+
+  if (trimmedNew === '') {
+    // Remove the single existing note token, including the line break that
+    // delimits it. Does NOT touch surrounding code blocks.
+    const c = noteComments[0];
+    const { startOffset, endOffset } = lineRangeToOffsets(
+      lineStarts, totalLines, rawSource.length, c.startLine, c.endLine
+    );
+    return {
+      source: rawSource.slice(0, startOffset) + rawSource.slice(endOffset),
+      changed: true
+    };
+  }
+
+  const formatted = formatNoteComment(trimmedNew, lineEnding);
+
+  if (noteComments.length === 1) {
+    // Replace the single existing comment's line range.
+    const c = noteComments[0];
+    const { startOffset, endOffset } = lineRangeToOffsets(
+      lineStarts, totalLines, rawSource.length, c.startLine, c.endLine
+    );
+    // Preserve the trailing newline of the line we replace, if any.
+    const preserveTrailingNewline = endOffset < rawSource.length
+      || /(?:\r\n|\r|\n)$/.test(rawSource.slice(startOffset, endOffset));
+    return {
+      source:
+        rawSource.slice(0, startOffset) +
+        formatted +
+        (preserveTrailingNewline ? lineEnding : '') +
+        rawSource.slice(endOffset),
+      changed: true
+    };
+  }
+
+  // Insert a new comment at the slide's last non-blank line + 1.
+  const range = parsed.slideRanges[slideIndex];
+  const insertLine = findInsertionLine(rawSource, lineStarts, totalLines, range);
+  const insertOffset = insertLine < lineStarts.length
+    ? lineStarts[insertLine]
+    : rawSource.length;
+
+  const inserted = formatted + lineEnding + lineEnding;
+  // If the slide had no trailing blank line, we need to introduce a blank
+  // line between content and our comment.
+  const needsLeadingBlank = (() => {
+    if (insertOffset === 0) return false;
+    const before = rawSource.slice(0, insertOffset);
+    return !/(?:\r\n\r\n|\n\n|\r\r)$/.test(before);
+  })();
+  const prefix = needsLeadingBlank ? lineEnding : '';
+
+  return {
+    source:
+      rawSource.slice(0, insertOffset) +
+      prefix +
+      inserted +
+      rawSource.slice(insertOffset),
+    changed: true
+  };
+}

package/src/rendering/marpitAdapter.js

@@ -0,0 +1,139 @@
+/**
+ * MarpitTokenAdapter — Marp/Marpit のパーサ出力を正規化する 1 箇所のラッパ。
+ *
+ * Slide 範囲・speaker note 位置の特定はすべてこのモジュール経由で行う。
+ * 直接 marp.markdown.parse() / marp.render() を別の場所から呼ばない。
+ *
+ * 契約 (tests/test-marpit-adapter.js で snapshot 凍結):
+ *  - marpit_slide_open.map === [startLine, endLine]
+ *  - marpit_comment.content は両側 trim 済み
+ *  - marpit_comment.map === [startLine, endLineExclusive]
+ *  - marpit_slide_close.map は null になり得る
+ *  - BOM 付き入力で slide_open.map[0] === 0
+ *  - render(rawSource).comments は 2D 配列で directive を除外済み
+ */
+
+import { Marp } from '@marp-team/marp-core';
+import { mkError } from '../utils/errors.js';
+
+const marp = new Marp({
+  html: true,
+  math: true,
+  markdown: { html: true, breaks: false, linkify: true }
+});
+marp.markdown.disable('code');
+
+/**
+ * Marp deck を解析し、slide 範囲・classified notes・comment 位置を返す。
+ *
+ * @param {string} rawSource
+ * @returns {{
+ *   slideCount: number,
+ *   slideRanges: Array<{startLine: number, endLine: number}>,
+ *   classifiedNotes: string[][],
+ *   commentsBySlide: Array<Array<{content: string, startLine: number, endLine: number}>>,
+ *   notesMultiplicity: number[]
+ * }}
+ * @throws {Error} code='NOT_PARSEABLE' if Marpit returns malformed tokens.
+ */
+export function parseDeck(rawSource) {
+  const env = {};
+  const tokens = marp.markdown.parse(rawSource, env);
+  const { comments: classifiedNotes } = marp.render(rawSource);
+
+  const slideOpens = tokens.filter((t) => t.type === 'marpit_slide_open');
+  for (const t of slideOpens) {
+    if (!t.map) throw mkError('NOT_PARSEABLE', 'slide_open without source map');
+  }
+  const slideStartLines = slideOpens.map((t) => t.map[0]);
+  const totalLines = countLines(rawSource);
+
+  const slideRanges = slideStartLines.map((start, i) => ({
+    startLine: start,
+    endLine: i + 1 < slideStartLines.length ? slideStartLines[i + 1] : totalLines
+  }));
+
+  const commentsBySlide = slideRanges.map(() => []);
+  let cursor = -1;
+  for (const t of tokens) {
+    if (t.type === 'marpit_slide_open') {
+      cursor = slideStartLines.indexOf(t.map[0]);
+      continue;
+    }
+    if (t.type === 'marpit_comment' && cursor >= 0) {
+      if (!t.map) throw mkError('NOT_PARSEABLE', 'marpit_comment without source map');
+      commentsBySlide[cursor].push({
+        content: t.content,
+        startLine: t.map[0],
+        endLine: t.map[1]
+      });
+    }
+  }
+
+  const notesMultiplicity = classifiedNotes.map((arr) => (arr || []).length);
+
+  return {
+    slideCount: slideRanges.length,
+    slideRanges,
+    classifiedNotes,
+    commentsBySlide,
+    notesMultiplicity
+  };
+}
+
+/**
+ * commentsBySlide[i] のうち、classifiedNotes[i] と順序 zip でマッチしたもの
+ * だけを speaker note として返す。directive コメントは classifiedNotes には
+ * 出ないので、自然に除外される。
+ *
+ * @param {Array<{content: string, startLine: number, endLine: number}>} commentsInSlide
+ * @param {string[]} noteStrings
+ * @returns {Array<{content: string, startLine: number, endLine: number}>}
+ * @throws {Error} code='NOT_PARSEABLE' if zip ends with mismatched count.
+ */
+export function pickNoteComments(commentsInSlide, noteStrings) {
+  const notes = [];
+  let cursor = 0;
+  for (const c of commentsInSlide) {
+    if (cursor < noteStrings.length && c.content === noteStrings[cursor]) {
+      notes.push(c);
+      cursor++;
+    }
+  }
+  if (cursor !== noteStrings.length) {
+    throw mkError('NOT_PARSEABLE', 'comment tokens do not match classifiedNotes');
+  }
+  return notes;
+}
+
+/**
+ * markdown-it / marpit の行カウント慣例に整合する line 数を返す。
+ * `t.map` の `endLine` と整合させるため、末尾改行ありなら改行数、なしなら +1。
+ */
+export function countLines(source) {
+  if (source.length === 0) return 0;
+  const newlines = (source.match(/\r\n|\r|\n/g) || []).length;
+  const endsWithNewline = /(?:\r\n|\r|\n)$/.test(source);
+  return endsWithNewline ? newlines : newlines + 1;
+}
+
+/**
+ * Marp 互換 marker (`marp: true` を frontmatter に含むか)。
+ */
+export function isMarp(content) {
+  return /^---\s*\n[\s\S]*?marp:\s*true[\s\S]*?\n---/.test(content);
+}
+
+/**
+ * Render の薄いラッパ（既存呼び出し元との互換用）。
+ */
+export function renderDeck(rawSource) {
+  const { html, css, comments } = marp.render(rawSource);
+  const slideCount = (html.match(/<section[^>]*>/g) || []).length;
+  const notes = (comments || []).map((arr) =>
+    Array.isArray(arr) ? arr.join('\n\n').trim() : ''
+  );
+  while (notes.length < slideCount) notes.push('');
+  const notesMultiplicity = (comments || []).map((arr) => (arr || []).length);
+  return { html, css, slideCount, notes, notesMultiplicity };
+}