egregore-artifacts 0.9.8 → 0.9.9

package/lib/markdown.js

@@ -1,11 +1,53 @@
 // Lightweight markdown → React elements converter
 // Handles: **bold**, *italic*, `code`, ### headings, [links](url), tables, lists
 import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import crypto from 'node:crypto';
 import { colors, fonts } from './tokens.js';
 import { artifactIdFromPath } from './artifact-id.js';
 
 const h = React.createElement;
 
+// ---------------------------------------------------------------------------
+// Source-map helpers (Contract §4)
+// ---------------------------------------------------------------------------
+
+// sha256 hex of `text`, truncated to first 16 chars, prefixed `sha256:`.
+// Used as the paragraphId (per Contract §2.3 and §4.2).
+function paragraphIdOf(text) {
+  const hex = crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+  return `sha256:${hex.slice(0, 16)}`;
+}
+
+// kebab-case the heading text and truncate to 40 chars (Contract §4.3 / §2.3).
+// Strips non-alphanumerics (collapsing to single hyphens) and trims hyphens.
+function slugify(headingText) {
+  const sliced = (headingText || '').slice(0, 40);
+  return sliced
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Compute char offsets for the start of every line. Index `i` is the offset
+// of `lines[i]` in the original source (accounting for newline separators).
+function buildLineOffsets(lines) {
+  const offsets = new Array(lines.length);
+  let off = 0;
+  for (let i = 0; i < lines.length; i++) {
+    offsets[i] = off;
+    off += lines[i].length + 1; // +1 for the '\n' that join uses
+  }
+  return offsets;
+}
+
+// Strip block-level markdown sigils from a line so anchor text (used for
+// per-`<li>` paragraphIds and paragraphIndex.text) is what the user actually
+// reads, not the raw source. Used only for hashing/text fields, not rendering.
+function stripListSigils(line) {
+  return line.replace(/^[-*]\s+/, '').replace(/^\d+\.\s+/, '');
+}
+
 // Module-level link context. Set by generateArtifact() before rendering, read
 // by inlineMarkdown() when deciding whether to rewrite `memory/…` code spans
 // and bare egregore.xyz URLs into <a> tags. Renders are synchronous so this
@@ -30,15 +72,33 @@ function memoryPathHref(memoryPath) {
   return `${linkContext.viewBase}/${linkContext.orgSlug}/${id}`;
 }
 
-export function renderMarkdown(text) {
+/**
+ * Render markdown to React elements with optional source-map data attributes.
+ * @param {string} text — raw markdown source
+ * @param {object} [opts]
+ * @param {boolean} [opts.sourceMap=false] — when true, emit data-* attributes
+ * @returns {React.Element} root <div> of rendered content
+ */
+export function renderMarkdown(text, opts = {}) {
   if (!text) return null;
 
+  const sourceMap = opts.sourceMap === true; // default false — /edit passes true
   const lines = text.split('\n');
+  const lineOffsets = sourceMap ? buildLineOffsets(lines) : null;
+
+  // Section counters per Contract §4.3. Top-level (`## `) increments N and
+  // resets M; sub-section (`### `) increments M. Deeper headings emit
+  // normally without `data-section` (Q1 v0.1 decision).
+  let sectionCounter = 0;
+  let subSectionCounter = 0;
+
   const elements = [];
   let i = 0;
 
   while (i < lines.length) {
     const line = lines[i];
+    const lineStart = i;
+    const charOffset = sourceMap ? lineOffsets[lineStart] : 0;
 
     // Table detection — starts with |
     if (line.trim().startsWith('|') && line.includes('|', 1)) {
@@ -47,13 +107,18 @@ export function renderMarkdown(text) {
         tableLines.push(lines[i]);
         i++;
       }
-      elements.push(renderTable(tableLines, elements.length));
+      const tableProps = sourceMap
+        ? { sourceOffset: charOffset, sourceLine: lineStart + 1 }
+        : null;
+      elements.push(renderTable(tableLines, elements.length, tableProps));
       continue;
     }
 
-    // H1 heading (rare inside a document body; render as section-sized)
+    // H1 heading — treated as document title; does NOT participate in section
+    // numbering (per Q1 v0.1 decision: §N starts at the first `## `).
     if (line.startsWith('# ')) {
-      elements.push(h('h2', {
+      const headingText = line.slice(2);
+      const props = {
         key: elements.length,
         style: {
           fontFamily: fonts.serif,
@@ -63,14 +128,20 @@ export function renderMarkdown(text) {
           margin: '1.75rem 0 0.75rem',
           color: 'var(--black)',
         },
-      }, inlineMarkdown(line.slice(2))));
+      };
+      // No data-section attribute — H1 is unnumbered.
+      elements.push(h('h2', props, inlineMarkdown(headingText)));
       i++;
       continue;
     }
 
     // H2 heading
     if (line.startsWith('## ')) {
-      elements.push(h('h3', {
+      const headingText = line.slice(3);
+      sectionCounter += 1;
+      subSectionCounter = 0;
+      const sectionLabel = `§${sectionCounter}. ${slugify(headingText)}`;
+      const props = {
         key: elements.length,
         style: {
           fontFamily: fonts.serif,
@@ -80,14 +151,19 @@ export function renderMarkdown(text) {
           margin: '1.5rem 0 0.5rem',
           color: 'var(--black)',
         },
-      }, inlineMarkdown(line.slice(3))));
+      };
+      if (sourceMap) props['data-section'] = sectionLabel;
+      elements.push(h('h3', props, inlineMarkdown(headingText)));
       i++;
       continue;
     }
 
     // H3 heading
     if (line.startsWith('### ')) {
-      elements.push(h('h3', {
+      const headingText = line.slice(4);
+      subSectionCounter += 1;
+      const sectionLabel = `§${sectionCounter}.${subSectionCounter}. ${slugify(headingText)}`;
+      const props = {
         key: elements.length,
         style: {
           fontFamily: fonts.serif,
@@ -97,12 +173,14 @@ export function renderMarkdown(text) {
           margin: '1.5rem 0 0.5rem',
           color: 'var(--black)',
         },
-      }, inlineMarkdown(line.slice(4))));
+      };
+      if (sourceMap) props['data-section'] = sectionLabel;
+      elements.push(h('h3', props, inlineMarkdown(headingText)));
       i++;
       continue;
     }
 
-    // H4 heading
+    // H4 heading — no data-section (per Q1 v0.1 decision: emit normally)
     if (line.startsWith('#### ')) {
       elements.push(h('h4', {
         key: elements.length,
@@ -121,16 +199,23 @@ export function renderMarkdown(text) {
     // Unordered list item
     if (line.match(/^[-*] /)) {
       const listItems = [];
+      const itemLineStarts = [];
       while (i < lines.length && lines[i].match(/^[-*] /)) {
+        itemLineStarts.push(i);
         listItems.push(lines[i].replace(/^[-*] /, ''));
         i++;
       }
-      elements.push(h('ul', {
+      const ulProps = {
         key: elements.length,
         style: { listStyle: 'none', padding: 0, margin: '0.5rem 0' },
-      },
-        ...listItems.map((item, j) =>
-          h('li', {
+      };
+      if (sourceMap) {
+        ulProps['data-source-offset'] = String(charOffset);
+        ulProps['data-source-line'] = String(lineStart + 1);
+      }
+      elements.push(h('ul', ulProps,
+        ...listItems.map((item, j) => {
+          const liProps = {
             key: j,
             style: {
               position: 'relative',
@@ -140,7 +225,14 @@ export function renderMarkdown(text) {
               lineHeight: 1.55,
               color: 'var(--dark)',
             },
-          },
+          };
+          if (sourceMap) {
+            const liLineIdx = itemLineStarts[j];
+            liProps['data-para-id'] = paragraphIdOf(item);
+            liProps['data-source-offset'] = String(lineOffsets[liLineIdx]);
+            liProps['data-source-line'] = String(liLineIdx + 1);
+          }
+          return h('li', liProps,
             h('span', {
               style: {
                 position: 'absolute',
@@ -153,8 +245,8 @@ export function renderMarkdown(text) {
               },
             }),
             inlineMarkdown(item),
-          )
-        ),
+          );
+        }),
       ));
       continue;
     }
@@ -162,16 +254,23 @@ export function renderMarkdown(text) {
     // Ordered list item
     if (line.match(/^\d+\.\s/)) {
       const listItems = [];
+      const itemLineStarts = [];
       while (i < lines.length && lines[i].match(/^\d+\.\s/)) {
+        itemLineStarts.push(i);
         listItems.push(lines[i].replace(/^\d+\.\s*/, ''));
         i++;
       }
-      elements.push(h('ol', {
+      const olProps = {
         key: elements.length,
         style: { listStyle: 'none', padding: 0, margin: '0.5rem 0', counterReset: 'step' },
-      },
-        ...listItems.map((item, j) =>
-          h('li', {
+      };
+      if (sourceMap) {
+        olProps['data-source-offset'] = String(charOffset);
+        olProps['data-source-line'] = String(lineStart + 1);
+      }
+      elements.push(h('ol', olProps,
+        ...listItems.map((item, j) => {
+          const liProps = {
             key: j,
             style: {
               display: 'flex',
@@ -180,7 +279,14 @@ export function renderMarkdown(text) {
               fontSize: '15px',
               lineHeight: 1.55,
             },
-          },
+          };
+          if (sourceMap) {
+            const liLineIdx = itemLineStarts[j];
+            liProps['data-para-id'] = paragraphIdOf(item);
+            liProps['data-source-offset'] = String(lineOffsets[liLineIdx]);
+            liProps['data-source-line'] = String(liLineIdx + 1);
+          }
+          return h('li', liProps,
             h('span', {
               style: {
                 flexShrink: 0,
@@ -199,8 +305,8 @@ export function renderMarkdown(text) {
               },
             }, String(j + 1)),
             h('span', null, inlineMarkdown(item)),
-          )
-        ),
+          );
+        }),
       ));
       continue;
     }
@@ -214,7 +320,7 @@ export function renderMarkdown(text) {
         i++;
       }
       i++; // skip closing ```
-      elements.push(h('pre', {
+      const preProps = {
         key: elements.length,
         style: {
           background: 'var(--terminal-bg)',
@@ -227,7 +333,12 @@ export function renderMarkdown(text) {
           overflowX: 'auto',
           margin: '0.75rem 0',
         },
-      }, h('code', null, codeLines.join('\n'))));
+      };
+      if (sourceMap) {
+        preProps['data-source-offset'] = String(charOffset);
+        preProps['data-source-line'] = String(lineStart + 1);
+      }
+      elements.push(h('pre', preProps, h('code', null, codeLines.join('\n'))));
       continue;
     }
 
@@ -247,10 +358,16 @@ export function renderMarkdown(text) {
       i++;
     }
     if (paraLines.length > 0) {
-      elements.push(h('p', {
+      const pProps = {
         key: elements.length,
         style: { margin: '0.5rem 0', fontSize: '15px', lineHeight: 1.6, color: 'var(--dark)' },
-      }, inlineMarkdown(paraLines.join(' '))));
+      };
+      if (sourceMap) {
+        pProps['data-para-id'] = paragraphIdOf(paraLines.join('\n'));
+        pProps['data-source-offset'] = String(charOffset);
+        pProps['data-source-line'] = String(lineStart + 1);
+      }
+      elements.push(h('p', pProps, inlineMarkdown(paraLines.join(' '))));
     } else {
       // Safety: nothing consumed this line. Skip it to avoid an infinite loop.
       i++;
@@ -260,6 +377,167 @@ export function renderMarkdown(text) {
   return h('div', { style: { color: 'var(--dark)' } }, ...elements);
 }
 
+/**
+ * Render markdown to a static HTML string (source-mapped by default).
+ *
+ * Wraps `renderMarkdown` + `renderToStaticMarkup` so consumers outside the
+ * artifacts package don't need to resolve `react-dom/server` themselves —
+ * the import lives here and resolves from the package's local node_modules.
+ *
+ * Used by `/api/edit/render` (bin/lib/edit-loopback.mjs) to ship source-mapped
+ * HTML to the browser annotation surface. This is "source render" — the body
+ * markup only, NOT the full /view document shell.
+ *
+ * @param {string} text — raw markdown source
+ * @param {object} opts — same options as renderMarkdown
+ * @returns {string} static HTML string (body only, no shell)
+ */
+export function renderMarkdownToHtml(text, opts = {}) {
+  const tree = renderMarkdown(text, opts);
+  if (!tree) return '';
+  return renderToStaticMarkup(tree);
+}
+
+/**
+ * Build a paragraph index for a markdown source. Same line walker as
+ * renderMarkdown, but emits a structured array instead of React elements.
+ * Used by /api/edit/render to ship paragraphIndex alongside HTML so the
+ * browser can resolve DOM selection to anchors without reparsing.
+ *
+ * Returns one entry per anchorable block: paragraphs and per-`<li>` items
+ * (per Contract §4.2 / Q2 v0.1 decision). Headings, tables, and code fences
+ * are NOT in the index — they're container-only anchors.
+ *
+ * @param {string} text — raw markdown source
+ * @returns {Array<{paragraphId: string, section: string, charOffset: number, lineNumber: number, text: string}>}
+ */
+export function buildParagraphIndex(text) {
+  if (!text) return [];
+
+  const lines = text.split('\n');
+  const lineOffsets = buildLineOffsets(lines);
+  const index = [];
+
+  let sectionCounter = 0;
+  let subSectionCounter = 0;
+  let currentSection = '§0. unsectioned';
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const lineStart = i;
+    const charOffset = lineOffsets[lineStart];
+
+    // Table — skip; not an anchorable paragraph.
+    if (line.trim().startsWith('|') && line.includes('|', 1)) {
+      while (i < lines.length && lines[i].trim().startsWith('|')) i++;
+      continue;
+    }
+
+    // H1 — document title; does NOT participate in section numbering
+    // (matches renderMarkdown behavior). Skip without changing currentSection.
+    if (line.startsWith('# ')) {
+      i++;
+      continue;
+    }
+
+    // H2 — top-level section.
+    if (line.startsWith('## ')) {
+      const headingText = line.slice(3);
+      sectionCounter += 1;
+      subSectionCounter = 0;
+      currentSection = `§${sectionCounter}. ${slugify(headingText)}`;
+      i++;
+      continue;
+    }
+
+    // H3 — sub-section.
+    if (line.startsWith('### ')) {
+      const headingText = line.slice(4);
+      subSectionCounter += 1;
+      currentSection = `§${sectionCounter}.${subSectionCounter}. ${slugify(headingText)}`;
+      i++;
+      continue;
+    }
+
+    // H4+ — emit normally; section unchanged.
+    if (line.startsWith('#### ') || line.startsWith('##### ') || line.startsWith('###### ')) {
+      i++;
+      continue;
+    }
+
+    // Unordered list — each <li> is an anchor.
+    if (line.match(/^[-*] /)) {
+      while (i < lines.length && lines[i].match(/^[-*] /)) {
+        const itemText = lines[i].replace(/^[-*] /, '');
+        index.push({
+          paragraphId: paragraphIdOf(itemText),
+          section: currentSection,
+          charOffset: lineOffsets[i],
+          lineNumber: i + 1,
+          text: itemText,
+        });
+        i++;
+      }
+      continue;
+    }
+
+    // Ordered list — each <li> is an anchor.
+    if (line.match(/^\d+\.\s/)) {
+      while (i < lines.length && lines[i].match(/^\d+\.\s/)) {
+        const itemText = lines[i].replace(/^\d+\.\s*/, '');
+        index.push({
+          paragraphId: paragraphIdOf(itemText),
+          section: currentSection,
+          charOffset: lineOffsets[i],
+          lineNumber: i + 1,
+          text: itemText,
+        });
+        i++;
+      }
+      continue;
+    }
+
+    // Code fence — skip; container-only anchor.
+    if (line.startsWith('```')) {
+      i++;
+      while (i < lines.length && !lines[i].startsWith('```')) i++;
+      if (i < lines.length) i++; // skip closing ```
+      continue;
+    }
+
+    // Empty line.
+    if (line.trim() === '') {
+      i++;
+      continue;
+    }
+
+    // Paragraph.
+    const paraLines = [];
+    while (i < lines.length && lines[i].trim() !== '' &&
+           !lines[i].startsWith('#') && !lines[i].startsWith('|') &&
+           !lines[i].startsWith('```') && !lines[i].match(/^[-*] /) &&
+           !lines[i].match(/^\d+\.\s/)) {
+      paraLines.push(lines[i]);
+      i++;
+    }
+    if (paraLines.length > 0) {
+      const joined = paraLines.join('\n');
+      index.push({
+        paragraphId: paragraphIdOf(joined),
+        section: currentSection,
+        charOffset,
+        lineNumber: lineStart + 1,
+        text: paraLines.join(' '),
+      });
+    } else {
+      i++;
+    }
+  }
+
+  return index;
+}
+
 // Inline markdown: **bold**, *italic*, `code`, [link](url)
 // Finds whichever pattern appears earliest in the string
 export function inlineMarkdown(text) {
@@ -340,18 +618,26 @@ function inlineMarkdownSimple(text, key) {
   return h(React.Fragment, { key }, text);
 }
 
-// Render markdown table
-function renderTable(lines, key) {
+// Render markdown table.
+// `sourceMapProps` is { sourceOffset, sourceLine } when the caller wants
+// `data-source-offset` / `data-source-line` on the outer wrapper (Contract §4.2).
+function renderTable(lines, key, sourceMapProps) {
   // Parse header
   const headerCells = parseTableRow(lines[0]);
   // Skip separator row (|---|---|)
   const startRow = lines[1]?.match(/^\|[\s-:|]+\|$/) ? 2 : 1;
   const bodyRows = lines.slice(startRow).map(parseTableRow);
 
-  return h('div', {
+  const wrapperProps = {
     key,
     style: { overflowX: 'auto', margin: '0.75rem 0' },
-  },
+  };
+  if (sourceMapProps) {
+    wrapperProps['data-source-offset'] = String(sourceMapProps.sourceOffset);
+    wrapperProps['data-source-line'] = String(sourceMapProps.sourceLine);
+  }
+
+  return h('div', wrapperProps,
     h('table', {
       style: {
         width: '100%',