@stravica-ai/digital-operator-pa 0.1.39 → 0.1.41

package/dist/engineering-pa-core-extensions-atlassian/src/confluence/storage.mjs

@@ -0,0 +1,880 @@
+// storage.mjs - Confluence XHTML storage format ↔ markdown conversion.
+//
+// Confluence stores page content in XHTML "storage format" with proprietary
+// macros using ac: and ri: namespaces. This module converts between that
+// format and markdown, enabling markdown-first workflows.
+//
+// Zero external dependencies - internals use a hand-rolled recursive-descent
+// XHTML parser that produces a small DOM-like tree, then walks the tree to
+// render. This replaces an older regex-based approach that misfired on
+// nested macros (e.g. an info macro containing a code block: the outer
+// `</ac:structured-macro>` close would be greedy-matched against the inner
+// macro's close, dropping content).
+//
+// Public API (unchanged):
+//   markdownToStorage(md)       - markdown → Confluence storage XHTML
+//   storageToMarkdown(xhtml)    - storage XHTML → markdown
+//   storageToText(xhtml)        - storage XHTML → plain text
+//   textToStorage(text)         - plain text → storage XHTML
+
+// ── Markdown → Storage Format ────────────────────────────────────────
+
+/**
+ * Convert markdown to Confluence XHTML storage format.
+ *
+ * @param {string} md  Markdown input
+ * @returns {string}   XHTML storage format
+ */
+export function markdownToStorage(md) {
+  if (!md || typeof md !== 'string') return '';
+
+  const lines = md.split('\n');
+  const output = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Fenced code block
+    const codeMatch = line.match(/^```(\w*)$/);
+    if (codeMatch) {
+      const lang = codeMatch[1] || '';
+      const codeLines = [];
+      i++;
+      while (i < lines.length && !lines[i].match(/^```$/)) {
+        codeLines.push(lines[i]);
+        i++;
+      }
+      i++; // skip closing ```
+      const codeContent = codeLines.join('\n');
+      if (lang) {
+        output.push(
+          `<ac:structured-macro ac:name="code"><ac:parameter ac:name="language">${escapeXml(lang)}</ac:parameter><ac:plain-text-body><![CDATA[${codeContent}]]></ac:plain-text-body></ac:structured-macro>`
+        );
+      } else {
+        output.push(
+          `<ac:structured-macro ac:name="code"><ac:plain-text-body><![CDATA[${codeContent}]]></ac:plain-text-body></ac:structured-macro>`
+        );
+      }
+      continue;
+    }
+
+    // Horizontal rule
+    if (line.match(/^---+$/)) {
+      output.push('<hr />');
+      i++;
+      continue;
+    }
+
+    // Headings
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const text = convertInlineMarkdown(headingMatch[2]);
+      output.push(`<h${level}>${text}</h${level}>`);
+      i++;
+      continue;
+    }
+
+    // Table - detect pipe-delimited rows
+    if (line.match(/^\|.+\|$/)) {
+      const tableLines = [];
+      while (i < lines.length && lines[i].match(/^\|.+\|$/)) {
+        tableLines.push(lines[i]);
+        i++;
+      }
+      output.push(convertTable(tableLines));
+      continue;
+    }
+
+    // Blockquote
+    if (line.match(/^>\s/)) {
+      const quoteLines = [];
+      while (i < lines.length && lines[i].match(/^>\s?/)) {
+        quoteLines.push(lines[i].replace(/^>\s?/, ''));
+        i++;
+      }
+      const quoteContent = quoteLines.map((l) => `<p>${convertInlineMarkdown(l)}</p>`).join('');
+      output.push(`<blockquote>${quoteContent}</blockquote>`);
+      continue;
+    }
+
+    // Unordered list
+    if (line.match(/^[-*]\s/)) {
+      const listItems = [];
+      while (i < lines.length && lines[i].match(/^[-*]\s/)) {
+        listItems.push(lines[i].replace(/^[-*]\s/, ''));
+        i++;
+      }
+      const items = listItems.map((item) => `<li>${convertInlineMarkdown(item)}</li>`).join('');
+      output.push(`<ul>${items}</ul>`);
+      continue;
+    }
+
+    // Ordered list
+    if (line.match(/^\d+\.\s/)) {
+      const listItems = [];
+      while (i < lines.length && lines[i].match(/^\d+\.\s/)) {
+        listItems.push(lines[i].replace(/^\d+\.\s/, ''));
+        i++;
+      }
+      const items = listItems.map((item) => `<li>${convertInlineMarkdown(item)}</li>`).join('');
+      output.push(`<ol>${items}</ol>`);
+      continue;
+    }
+
+    // Empty line - skip (paragraph separation)
+    if (line.trim() === '') {
+      i++;
+      continue;
+    }
+
+    // Regular paragraph
+    output.push(`<p>${convertInlineMarkdown(line)}</p>`);
+    i++;
+  }
+
+  return output.join('');
+}
+
+/**
+ * Convert inline markdown elements to XHTML.
+ * Handles: bold, italic, code, links, images.
+ *
+ * @param {string} text  Inline markdown text
+ * @returns {string}     XHTML text
+ */
+function convertInlineMarkdown(text) {
+  if (!text) return '';
+
+  let result = escapeXml(text);
+
+  // Images: ![alt](url) → <ac:image><ri:url ri:value="url" /></ac:image>
+  // Process before links to avoid conflict
+  result = result.replace(
+    /!\[([^\]]*)\]\(([^)]+)\)/g,
+    '<ac:image><ri:url ri:value="$2" /></ac:image>'
+  );
+
+  // Links: [text](url) → <a href="url">text</a>
+  result = result.replace(
+    /\[([^\]]+)\]\(([^)]+)\)/g,
+    '<a href="$2">$1</a>'
+  );
+
+  // Bold: **text** → <strong>text</strong>
+  result = result.replace(
+    /\*\*([^*]+)\*\*/g,
+    '<strong>$1</strong>'
+  );
+
+  // Italic: *text* → <em>text</em>
+  result = result.replace(
+    /\*([^*]+)\*/g,
+    '<em>$1</em>'
+  );
+
+  // Inline code: `text` → <code>text</code>
+  result = result.replace(
+    /`([^`]+)`/g,
+    '<code>$1</code>'
+  );
+
+  return result;
+}
+
+/**
+ * Convert markdown pipe table to XHTML table.
+ *
+ * @param {string[]} lines  Table lines including header, separator, and body rows
+ * @returns {string}        XHTML table
+ */
+function convertTable(lines) {
+  if (lines.length < 2) return '';
+
+  const parseRow = (line) =>
+    line.split('|').slice(1, -1).map((cell) => cell.trim());
+
+  const headerCells = parseRow(lines[0]);
+
+  // Skip separator row (line[1] with dashes)
+  const bodyStart = lines[1].match(/^[\s|:-]+$/) ? 2 : 1;
+  const bodyRows = lines.slice(bodyStart).map(parseRow);
+
+  const thead = `<thead><tr>${headerCells.map((c) => `<th>${convertInlineMarkdown(c)}</th>`).join('')}</tr></thead>`;
+
+  let tbody = '';
+  if (bodyRows.length > 0) {
+    const rows = bodyRows.map((cells) =>
+      `<tr>${cells.map((c) => `<td>${convertInlineMarkdown(c)}</td>`).join('')}</tr>`
+    ).join('');
+    tbody = `<tbody>${rows}</tbody>`;
+  }
+
+  return `<table>${thead}${tbody}</table>`;
+}
+
+// ── XHTML Parser (DOM-style tree) ────────────────────────────────────
+//
+// Produces a small tree of nodes:
+//   { type: 'element', name, attrs: { k: v }, children: [...] }
+//   { type: 'text', value }
+//   { type: 'cdata', value }        - preserves CDATA body verbatim
+//   { type: 'comment', value }      - discarded by renderers
+//
+// HTML void elements close themselves (<br>, <hr>, <img>, <meta>, ...).
+// Self-closing syntax (`<x />`) is honoured for any tag.
+// Tag names are case-preserved as written (Confluence uses lower-case + ac:/ri:).
+// Unclosed tags auto-close at end of input - this is a forgiving parser,
+// not a validating one.
+
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+/**
+ * Parse Confluence XHTML / HTML-ish input into a tree of nodes.
+ *
+ * @param {string} input
+ * @returns {Array} children of an implicit root
+ */
+function parseXhtml(input) {
+  const root = { type: 'element', name: '#root', attrs: {}, children: [] };
+  const stack = [root];
+  let i = 0;
+  const n = input.length;
+
+  const top = () => stack[stack.length - 1];
+  const appendText = (s) => {
+    if (!s) return;
+    const parent = top();
+    const last = parent.children[parent.children.length - 1];
+    if (last && last.type === 'text') {
+      last.value += s;
+    } else {
+      parent.children.push({ type: 'text', value: s });
+    }
+  };
+
+  while (i < n) {
+    const ch = input[i];
+
+    if (ch !== '<') {
+      // Text run - accumulate until next '<'
+      const end = input.indexOf('<', i);
+      const chunk = end === -1 ? input.slice(i) : input.slice(i, end);
+      appendText(decodeEntities(chunk));
+      if (end === -1) break;
+      i = end;
+      continue;
+    }
+
+    // CDATA: <![CDATA[ ... ]]>
+    if (input.startsWith('<![CDATA[', i)) {
+      const end = input.indexOf(']]>', i + 9);
+      if (end === -1) {
+        // Unterminated - treat rest as CDATA verbatim
+        top().children.push({ type: 'cdata', value: input.slice(i + 9) });
+        i = n;
+        break;
+      }
+      top().children.push({ type: 'cdata', value: input.slice(i + 9, end) });
+      i = end + 3;
+      continue;
+    }
+
+    // Comment: <!-- ... -->
+    if (input.startsWith('<!--', i)) {
+      const end = input.indexOf('-->', i + 4);
+      if (end === -1) { i = n; break; }
+      top().children.push({ type: 'comment', value: input.slice(i + 4, end) });
+      i = end + 3;
+      continue;
+    }
+
+    // Doctype or other <! declaration - skip to next '>'
+    if (input[i + 1] === '!') {
+      const end = input.indexOf('>', i);
+      if (end === -1) { i = n; break; }
+      i = end + 1;
+      continue;
+    }
+
+    // Processing instruction: <? ... ?>
+    if (input[i + 1] === '?') {
+      const end = input.indexOf('?>', i);
+      if (end === -1) { i = n; break; }
+      i = end + 2;
+      continue;
+    }
+
+    // Closing tag: </name>
+    if (input[i + 1] === '/') {
+      const end = input.indexOf('>', i);
+      if (end === -1) {
+        // Unterminated - treat as text
+        appendText(input.slice(i));
+        i = n;
+        break;
+      }
+      const closeName = input.slice(i + 2, end).trim();
+      // Pop until we close a matching open tag; if no match, drop silently
+      let popIdx = -1;
+      for (let j = stack.length - 1; j >= 1; j--) {
+        if (stack[j].name === closeName) { popIdx = j; break; }
+      }
+      if (popIdx >= 1) {
+        stack.length = popIdx;
+      }
+      i = end + 1;
+      continue;
+    }
+
+    // Open or self-closing tag
+    const tagEnd = findTagEnd(input, i);
+    if (tagEnd === -1) {
+      // Unterminated - treat as text
+      appendText(input.slice(i));
+      i = n;
+      break;
+    }
+    const raw = input.slice(i + 1, tagEnd);
+    i = tagEnd + 1;
+
+    const selfClosing = raw.endsWith('/');
+    const body = selfClosing ? raw.slice(0, -1).trim() : raw.trim();
+    if (!body) continue; // <> or </> garbage - skip
+
+    const { name, attrs } = parseTag(body);
+    if (!name) continue;
+
+    const node = { type: 'element', name, attrs, children: [] };
+    top().children.push(node);
+
+    const isVoid = VOID_ELEMENTS.has(name.toLowerCase());
+    if (!selfClosing && !isVoid) {
+      stack.push(node);
+    }
+  }
+
+  return root.children;
+}
+
+/**
+ * Find the position of the '>' that closes a tag started at `start`.
+ * Handles attribute values containing '>' inside quotes.
+ *
+ * @param {string} input
+ * @param {number} start  Index of the '<'
+ * @returns {number}      Index of the matching '>', or -1
+ */
+function findTagEnd(input, start) {
+  const n = input.length;
+  let i = start + 1;
+  let quote = null;
+  while (i < n) {
+    const ch = input[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+    } else {
+      if (ch === '"' || ch === "'") quote = ch;
+      else if (ch === '>') return i;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * Parse "name attr1="v" attr2='v' attr3=v attr4" into { name, attrs }.
+ *
+ * @param {string} body  Tag body without `<`, `>`, or trailing `/`
+ * @returns {{ name: string, attrs: Record<string, string> }}
+ */
+function parseTag(body) {
+  // First token is the tag name
+  let i = 0;
+  const n = body.length;
+  while (i < n && /\s/.test(body[i])) i++;
+  const nameStart = i;
+  while (i < n && !/[\s/>]/.test(body[i])) i++;
+  const name = body.slice(nameStart, i);
+  const attrs = {};
+  if (!name) return { name: '', attrs };
+
+  while (i < n) {
+    while (i < n && /\s/.test(body[i])) i++;
+    if (i >= n) break;
+
+    // Attribute name
+    const aStart = i;
+    while (i < n && !/[\s=/>]/.test(body[i])) i++;
+    const aName = body.slice(aStart, i);
+    if (!aName) { i++; continue; }
+
+    while (i < n && /\s/.test(body[i])) i++;
+
+    if (body[i] === '=') {
+      i++;
+      while (i < n && /\s/.test(body[i])) i++;
+      const q = body[i];
+      let value = '';
+      if (q === '"' || q === "'") {
+        i++;
+        const vStart = i;
+        while (i < n && body[i] !== q) i++;
+        value = body.slice(vStart, i);
+        if (i < n) i++; // closing quote
+      } else {
+        // Unquoted value: read until whitespace
+        const vStart = i;
+        while (i < n && !/\s/.test(body[i])) i++;
+        value = body.slice(vStart, i);
+      }
+      attrs[aName] = decodeEntities(value);
+    } else {
+      // Boolean attribute
+      attrs[aName] = '';
+    }
+  }
+
+  return { name, attrs };
+}
+
+/**
+ * Decode the common XHTML named entities and numeric references.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function decodeEntities(s) {
+  if (!s || s.indexOf('&') === -1) return s;
+  return s.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z]+);/g, (m, ent) => {
+    if (ent[0] === '#') {
+      const cp = ent[1] === 'x' || ent[1] === 'X'
+        ? parseInt(ent.slice(2), 16)
+        : parseInt(ent.slice(1), 10);
+      if (Number.isFinite(cp) && cp >= 0 && cp <= 0x10FFFF) {
+        try { return String.fromCodePoint(cp); } catch { return m; }
+      }
+      return m;
+    }
+    switch (ent) {
+      case 'amp': return '&';
+      case 'lt': return '<';
+      case 'gt': return '>';
+      case 'quot': return '"';
+      case 'apos': return "'";
+      case 'nbsp': return ' ';
+      default: return m;
+    }
+  });
+}
+
+// ── Tree helpers ─────────────────────────────────────────────────────
+
+/** @returns {boolean} */
+function isElement(node, name) {
+  return node && node.type === 'element' && (!name || node.name === name);
+}
+
+/** Find first child element matching `name`. */
+function findChild(node, name) {
+  if (!node || !node.children) return null;
+  for (const c of node.children) {
+    if (isElement(c, name)) return c;
+  }
+  return null;
+}
+
+/** Find all descendant elements matching `name` (depth-first). */
+function findAll(node, name, out = []) {
+  if (!node || !node.children) return out;
+  for (const c of node.children) {
+    if (isElement(c, name)) out.push(c);
+    if (c.type === 'element') findAll(c, name, out);
+  }
+  return out;
+}
+
+/**
+ * Find a macro parameter by name. Confluence storage:
+ *   <ac:parameter ac:name="title">...</ac:parameter>
+ *
+ * @returns {string|null} parameter text content, or null
+ */
+function findMacroParam(macroNode, paramName) {
+  if (!macroNode || !macroNode.children) return null;
+  for (const c of macroNode.children) {
+    if (isElement(c, 'ac:parameter') && c.attrs['ac:name'] === paramName) {
+      return innerText(c);
+    }
+  }
+  return null;
+}
+
+/**
+ * Get the inner text of a node - concatenate all descendant text + CDATA,
+ * decode entities, ignore elements/comments.
+ */
+function innerText(node) {
+  if (!node) return '';
+  if (node.type === 'text') return node.value;
+  if (node.type === 'cdata') return node.value;
+  if (node.type === 'comment') return '';
+  let out = '';
+  for (const c of node.children || []) out += innerText(c);
+  return out;
+}
+
+// ── Storage Format → Markdown ────────────────────────────────────────
+
+/**
+ * Convert Confluence XHTML storage format to markdown.
+ *
+ * @param {string} xhtml  XHTML storage format input
+ * @returns {string}      Markdown output
+ */
+export function storageToMarkdown(xhtml) {
+  if (!xhtml || typeof xhtml !== 'string') return '';
+  const tree = parseXhtml(xhtml);
+  let out = renderNodesToMarkdown(tree);
+  out = out.replace(/\n{3,}/g, '\n\n');
+  return out.trim();
+}
+
+function renderNodesToMarkdown(nodes) {
+  let out = '';
+  for (const node of nodes) out += renderNodeToMarkdown(node);
+  return out;
+}
+
+function renderNodeToMarkdown(node) {
+  if (!node) return '';
+  if (node.type === 'text') return node.value; // already decoded by the parser
+  if (node.type === 'cdata') return node.value;
+  if (node.type === 'comment') return '';
+  if (node.type !== 'element') return '';
+
+  const name = node.name;
+
+  // Macros
+  if (name === 'ac:structured-macro') return renderMacroToMarkdown(node);
+  if (name === 'ac:link') return renderAcLinkToMarkdown(node);
+  if (name === 'ac:image') return renderAcImageToMarkdown(node);
+  if (name === 'ac:emoticon') {
+    // Best-effort: emit the emoji shortname if present
+    const shortname = node.attrs['ac:emoji-shortname'] || node.attrs['ac:name'] || '';
+    return shortname ? `:${shortname.replace(/^:|:$/g, '')}:` : '';
+  }
+  // Ignore ri:* directly - they are consumed by their parents (link/image)
+  if (name.startsWith('ri:')) return '';
+  // Parameters inside macros - consumed by the macro renderer
+  if (name === 'ac:parameter' || name === 'ac:rich-text-body' || name === 'ac:plain-text-body' || name === 'ac:plain-text-link-body') {
+    return renderNodesToMarkdown(node.children);
+  }
+  // Drop any other unknown ac:* wrapper but keep contents
+  if (name.startsWith('ac:')) return renderNodesToMarkdown(node.children);
+
+  // HTML elements
+  switch (name.toLowerCase()) {
+    case 'h1': case 'h2': case 'h3': case 'h4': case 'h5': case 'h6': {
+      const level = parseInt(name.slice(1), 10);
+      return `\n${'#'.repeat(level)} ${plainInline(node).trim()}\n`;
+    }
+    case 'strong': case 'b':
+      return `**${renderNodesToMarkdown(node.children)}**`;
+    case 'em': case 'i':
+      return `*${renderNodesToMarkdown(node.children)}*`;
+    case 'code':
+      return `\`${renderNodesToMarkdown(node.children)}\``;
+    case 'a': {
+      const href = node.attrs.href || '';
+      return `[${renderNodesToMarkdown(node.children)}](${href})`;
+    }
+    case 'p':
+      return `${renderNodesToMarkdown(node.children)}\n\n`;
+    case 'br':
+      return '\n';
+    case 'hr':
+      return '\n---\n';
+    case 'blockquote': {
+      const inner = plainInline(node).trim();
+      if (!inner) return '';
+      return inner.split('\n').map((l) => `> ${l}`).join('\n') + '\n';
+    }
+    case 'ul': {
+      const items = [];
+      for (const c of node.children) {
+        if (isElement(c, 'li')) items.push(`- ${plainInline(c).trim()}`);
+      }
+      return '\n' + items.join('\n') + '\n';
+    }
+    case 'ol': {
+      const items = [];
+      let idx = 1;
+      for (const c of node.children) {
+        if (isElement(c, 'li')) items.push(`${idx++}. ${plainInline(c).trim()}`);
+      }
+      return '\n' + items.join('\n') + '\n';
+    }
+    case 'table':
+      return renderTableToMarkdown(node);
+    case 'img': {
+      const src = node.attrs.src || '';
+      const alt = node.attrs.alt || '';
+      return `![${alt}](${src})`;
+    }
+    case 'span': case 'div': case 'section': case 'article': case 'header': case 'footer': case 'main': case 'nav':
+      return renderNodesToMarkdown(node.children);
+    default:
+      // Unknown tag - drop, keep contents
+      return renderNodesToMarkdown(node.children);
+  }
+}
+
+/**
+ * Plain inline rendering - collapses block-ish output (for use in headings,
+ * list items, blockquotes where block separation isn't wanted).
+ */
+function plainInline(node) {
+  return renderNodesToMarkdown(node.children)
+    .replace(/\n+/g, ' ')
+    .replace(/\s{2,}/g, ' ');
+}
+
+function renderMacroToMarkdown(node) {
+  const macroName = node.attrs['ac:name'];
+
+  switch (macroName) {
+    case 'code': {
+      const lang = findMacroParam(node, 'language') || '';
+      const bodyNode = findChild(node, 'ac:plain-text-body');
+      const code = bodyNode ? innerText(bodyNode) : '';
+      return `\n\`\`\`${lang}\n${code}\n\`\`\`\n`;
+    }
+    case 'info':
+    case 'warning':
+    case 'note':
+    case 'tip': {
+      const label = macroName.charAt(0).toUpperCase() + macroName.slice(1);
+      const body = findChild(node, 'ac:rich-text-body');
+      const content = body ? renderNodesToMarkdown(body.children).trim() : '';
+      return `\n> **${label}:** ${content}\n`;
+    }
+    case 'panel': {
+      const title = findMacroParam(node, 'title') || 'Panel';
+      const body = findChild(node, 'ac:rich-text-body');
+      const content = body ? renderNodesToMarkdown(body.children).trim() : '';
+      return `\n> **${title}:** ${content}\n`;
+    }
+    case 'status': {
+      const title = findMacroParam(node, 'title') || '';
+      return `[${title}]`;
+    }
+    case 'expand': {
+      const body = findChild(node, 'ac:rich-text-body');
+      return body ? renderNodesToMarkdown(body.children) : '';
+    }
+    default: {
+      // Unknown macro - surface rich-text body or plain-text body if present
+      const rich = findChild(node, 'ac:rich-text-body');
+      if (rich) return renderNodesToMarkdown(rich.children);
+      const plain = findChild(node, 'ac:plain-text-body');
+      if (plain) return innerText(plain);
+      return '';
+    }
+  }
+}
+
+function renderAcLinkToMarkdown(node) {
+  // Confluence page link
+  const page = findChild(node, 'ri:page');
+  if (page) {
+    const title = page.attrs['ri:content-title'] || '';
+    return `[${title}]`;
+  }
+  // User mention
+  const user = findChild(node, 'ri:user');
+  if (user) {
+    const account = user.attrs['ri:account-id'] || user.attrs['ri:userkey'] || 'user';
+    return `[@${account}]`;
+  }
+  // Attachment
+  const att = findChild(node, 'ri:attachment');
+  if (att) {
+    const filename = att.attrs['ri:filename'] || 'attachment';
+    return `[${filename}]`;
+  }
+  // External URL link with plain-text body
+  const url = findChild(node, 'ri:url');
+  if (url) {
+    const value = url.attrs['ri:value'] || '';
+    const linkBody = findChild(node, 'ac:plain-text-link-body') || findChild(node, 'ac:link-body');
+    const text = linkBody ? innerText(linkBody).trim() : value;
+    return `[${text}](${value})`;
+  }
+  // Fallback - emit inner text
+  return innerText(node);
+}
+
+function renderAcImageToMarkdown(node) {
+  const url = findChild(node, 'ri:url');
+  if (url) return `![](${url.attrs['ri:value'] || ''})`;
+  const att = findChild(node, 'ri:attachment');
+  if (att) return `![](${att.attrs['ri:filename'] || ''})`;
+  return '';
+}
+
+function renderTableToMarkdown(node) {
+  const rows = [];
+  let hasHeader = false;
+
+  // Collect header rows from <thead>; if missing, first <tr> becomes header
+  const thead = findChild(node, 'thead');
+  const tbody = findChild(node, 'tbody');
+
+  const renderCell = (cell) => plainInline(cell).trim();
+
+  const collectRows = (container) => {
+    if (!container) return [];
+    const trs = [];
+    for (const c of container.children) {
+      if (isElement(c, 'tr')) trs.push(c);
+    }
+    return trs;
+  };
+
+  if (thead) {
+    const trs = collectRows(thead);
+    if (trs.length > 0) {
+      const cells = [];
+      for (const c of trs[0].children) {
+        if (isElement(c, 'th') || isElement(c, 'td')) cells.push(renderCell(c));
+      }
+      rows.push(`| ${cells.join(' | ')} |`);
+      rows.push(`| ${cells.map(() => '---').join(' | ')} |`);
+      hasHeader = true;
+    }
+  }
+
+  const bodyTrs = tbody
+    ? collectRows(tbody)
+    : collectRows(node).filter((tr) => !thead || !thead.children.includes(tr));
+
+  for (let r = 0; r < bodyTrs.length; r++) {
+    const tr = bodyTrs[r];
+    const cells = [];
+    for (const c of tr.children) {
+      if (isElement(c, 'th') || isElement(c, 'td')) cells.push(renderCell(c));
+    }
+    if (cells.length === 0) continue;
+    if (!hasHeader && r === 0) {
+      rows.push(`| ${cells.join(' | ')} |`);
+      rows.push(`| ${cells.map(() => '---').join(' | ')} |`);
+      hasHeader = true;
+      continue;
+    }
+    rows.push(`| ${cells.join(' | ')} |`);
+  }
+
+  return rows.length > 0 ? '\n' + rows.join('\n') + '\n' : '';
+}
+
+// ── Storage Format → Plain Text ──────────────────────────────────────
+
+/**
+ * Convert Confluence XHTML storage format to plain text.
+ * Strips all tags and macro structures, but preserves CDATA bodies
+ * (code-macro contents) and inserts newlines for block elements.
+ *
+ * @param {string} xhtml  XHTML storage format
+ * @returns {string}      Plain text
+ */
+export function storageToText(xhtml) {
+  if (!xhtml || typeof xhtml !== 'string') return '';
+  const tree = parseXhtml(xhtml);
+  let out = renderNodesToText(tree);
+  out = out.replace(/\n{3,}/g, '\n\n');
+  return out.trim();
+}
+
+const TEXT_BLOCK_ELEMENTS = new Set([
+  'p', 'div', 'blockquote', 'li', 'tr',
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+]);
+
+function renderNodesToText(nodes) {
+  let out = '';
+  for (const node of nodes) out += renderNodeToText(node);
+  return out;
+}
+
+function renderNodeToText(node) {
+  if (!node) return '';
+  if (node.type === 'text') return node.value;
+  if (node.type === 'cdata') return node.value;
+  if (node.type === 'comment') return '';
+  if (node.type !== 'element') return '';
+
+  const name = node.name;
+  const lowerName = name.toLowerCase();
+
+  // Macros - recurse into their bodies (rich-text or plain-text); skip parameters.
+  if (name === 'ac:structured-macro') {
+    const rich = findChild(node, 'ac:rich-text-body');
+    if (rich) return renderNodesToText(rich.children) + '\n';
+    const plain = findChild(node, 'ac:plain-text-body');
+    if (plain) return innerText(plain);
+    return '';
+  }
+  if (name === 'ac:parameter') return ''; // metadata - drop
+  if (name.startsWith('ri:')) return '';
+  if (name === 'ac:image') return '';
+  if (name === 'ac:emoticon') return '';
+  if (name.startsWith('ac:')) return renderNodesToText(node.children);
+
+  if (lowerName === 'br') return '\n';
+  if (lowerName === 'hr') return '\n---\n';
+
+  const inner = renderNodesToText(node.children);
+  if (TEXT_BLOCK_ELEMENTS.has(lowerName)) return inner + '\n';
+  return inner;
+}
+
+// ── Plain Text → Storage Format ──────────────────────────────────────
+
+/**
+ * Convert plain text to basic XHTML storage format.
+ * Wraps text in paragraphs, splitting on double newlines.
+ *
+ * @param {string} text  Plain text input
+ * @returns {string}     XHTML storage format
+ */
+export function textToStorage(text) {
+  if (!text || typeof text !== 'string') return '';
+
+  const paragraphs = text.split(/\n{2,}/);
+  return paragraphs
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0)
+    .map((p) => `<p>${escapeXml(p).replace(/\n/g, '<br />')}</p>`)
+    .join('');
+}
+
+// ── Utilities ────────────────────────────────────────────────────────
+
+/**
+ * Escape special XML characters for emission.
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeXml(text) {
+  if (!text) return '';
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}