confluence-md-sync 0.2.1 → 0.3.0

package/README.md

@@ -10,7 +10,8 @@ typed tables back, attach files — idempotently, with a **pluggable macro
 system**. ESM-only, zero-config CI.
 
 ```bash
-npm install confluence-md-sync
+npm install confluence-md-sync          # as a library
+npm install -g confluence-md-sync       # as a CLI: `confluence-md-sync …`
 ```
 
 ## Highlights
@@ -23,7 +24,13 @@ npm install confluence-md-sync
 - **Fail before write** — placeholders, files and macro markers are validated
   up front; Confluence is never touched on a broken input.
 - **Pluggable macros** — built-in `core` + `table-filter` plugins, extend
-  with your own in a few lines.
+  with your own in a few lines; unknown macros pass through unchanged.
+- **Flexible sources** — images/files accept relative paths, absolute paths
+  or `http(s)` URLs; URLs on your Confluence host are fetched with the
+  configured token.
+- **Loss-free round-trip** — export a page to Markdown and publish it back;
+  what Markdown can't express is kept verbatim, verified by canonical
+  storage comparison.
 
 ## Configuration
 
@@ -97,11 +104,23 @@ const { storage } = await publishPage({ pageId, markdownPath, dryRun: true }, cf
 
 // Inline content instead of a file
 await publishPage({ pageId, markdown: '# Generated\n\ntext' }, cfg);
+
+// Remote sources — downloaded at publish time; the filename for {{img:...}}
+// comes from the URL path. URLs on the configured Confluence host are
+// fetched with your token, so you can pull attachments from other pages.
+await publishPage({
+  pageId,
+  markdownPath,
+  images: ['https://confluence.example.com/download/attachments/999/flow.bpmn'],
+  files: ['https://files.example.com/exports/выгрузка.csv'],
+  downloadDir: 'build',   // optional; default: temp dir per run
+}, cfg);
 ```
 
 ## BPMN diagrams out of the box
 
-Pass a `.bpmn` file as an image — it is rendered to PNG at publish time
+Pass a `.bpmn` file as an image (a path or an `http(s)` URL) — it is
+rendered to PNG at publish time
 (headless Chromium via [bpmn-to-image](https://npmjs.com/package/bpmn-to-image),
 an optional peer dependency).
 
@@ -152,6 +171,59 @@ import { convertBpmnFolder } from 'confluence-md-sync';
 await convertBpmnFolder({ srcDir: 'docs/diagrams', outDir: 'build' });
 ```
 
+## Export a page back to Markdown (round-trip)
+
+Pull an existing page by ID and turn its storage format into Markdown —
+without losing markup. The conversion is **loss-free by construction**: a
+three-tier policy renders each node as clean Markdown where possible,
+macro markers where a macro round-trips, and verbatim storage (raw HTML,
+or a ` ```confluence-storage ` fence) as a fallback. Attachments and page
+links become `{{img:...}}` / `{{file:...}}` / `{{page:...}}` placeholders.
+
+```ts
+import { exportPage } from 'confluence-md-sync';
+
+const { markdownPath, images, downloaded } = await exportPage(
+  '123456789',
+  { outDir: 'exported' },   // writes exported/page.md + exported/attachments/
+  cfg,
+);
+```
+
+Round-trip means *edit the Markdown, then publish it straight back*:
+
+```ts
+await publishPage({
+  pageId: '123456789',
+  markdownPath: 'exported/page.md',
+  images: ['exported/attachments/diagram.png'],
+  // exported markup uses native attachment/link references, not URLs:
+  render: { imageStyle: 'attachment', fileStyle: 'attachment', linkify: false },
+}, cfg);
+```
+
+Verify a page survives the trip with no markup loss (writes nothing):
+
+```ts
+import { roundTripPage } from 'confluence-md-sync';
+
+const r = await roundTripPage('123456789', cfg);
+console.log(r.equal, r.stats);   // true { markers, fenced, rawHtml }
+// r.diffs lists any canonical differences when equal === false
+```
+
+Equivalence is **canonical**, not byte-for-byte: `ac:macro-id`,
+schema-version, attribute/parameter order and entity vs literal forms are
+normalised away (Confluence itself rewrites these on every save). Use
+`compareStorage(a, b)` directly to diff two storage fragments.
+
+From the CLI:
+
+```bash
+confluence-md-sync export    123456789 --out-dir exported
+confluence-md-sync roundtrip 123456789 --show-markdown   # exit 2 on loss
+```
+
 ## Read pages and tables
 
 ```ts
@@ -205,6 +277,7 @@ macros.tableExcerptInclude('name', 'Source Page');
 // Table Filter and Charts app
 macros.tableExcerpt(md, 'name', /* hide */ true);
 macros.tableFilter(md, { totalrow: ',,Sum' });
+macros.tableJoiner(includesMd, "SELECT * FROM T1 LEFT JOIN T2 ON …");  // multiline SQL ok
 ```
 
 Or write markers by hand right in Markdown:
@@ -215,6 +288,10 @@ Any **markdown**, including nested macros.
 <!-- MACRO:end:expand -->
 ```
 
+Any macro name works out of the box — one that isn't registered passes
+through to `<ac:structured-macro>` as-is (params + rich-text body). Disable
+with `registry.passthroughUnknownMacros(false)`.
+
 ### Custom macro plugin
 
 ```ts
@@ -235,11 +312,24 @@ splitting; `pageLinkValue()` builds `<ac:link><ri:page/>` parameter values.
 
 ## CLI
 
+Installed globally (`npm i -g confluence-md-sync`) the `confluence-md-sync`
+command is on your PATH; otherwise prefix the examples with `npx`. The
+instance URL and token come from the environment.
+
 ```bash
-npx confluence-md-sync publish docs/page.md --page-id 123456789 \
+export CONFLUENCE_BASE_URL='https://confluence.example.com'
+export CONFLUENCE_TOKEN='<your-PAT>'
+
+# Download a page to an exact .md path (add --no-attachments for the md only)
+confluence-md-sync export 123456789 --out ./page.md
+
+confluence-md-sync publish docs/page.md --page-id 123456789 \
   --image build/flow.png --file build/data.csv --label docs
 
-npx confluence-md-sync publish docs/page.md --space DOCS --title "Моя страница" --dry-run
+confluence-md-sync publish docs/page.md --space DOCS --title "Моя страница" --dry-run
+
+confluence-md-sync export    123456789 --out-dir exported   # page.md + attachments/
+confluence-md-sync roundtrip 123456789                      # exit 2 if markup would be lost
 ```
 
 ## CI publish plans
@@ -274,7 +364,8 @@ src/
 ├── macros/        registry, builder, plugins (core, table-filter)
 ├── attachments/   sha256 dedup, sidecar source hashes, version history
 ├── pages/         Page/Table object model, table parse & render
-├── publish/       idempotent publish pipeline, runPublish plans
+├── publish/       idempotent publish pipeline, runPublish plans, remote sources
+├── export/        storage parser, storage→Markdown, canonical compare, round-trip
 ├── wrapper.ts     confluence() facade
 ├── csv.ts         CSV helpers (subpath export ./csv)
 └── cli.ts         confluence-md-sync CLI
@@ -282,9 +373,9 @@ src/
 
 ## Roadmap
 
-Cloud API v2 backend · page-tree sync from a directory · storage→Markdown
-reverse conversion · Mermaid/PlantUML fences → images · fenced code →
-`code` macro · HTTP retry/backoff · comments API · dry-run diff preview.
+Cloud API v2 backend · page-tree sync from a directory · Mermaid/PlantUML
+fences → images · fenced code → `code` macro · HTTP retry/backoff ·
+comments API · dry-run diff preview.
 
 Issues and PRs welcome.
 

package/dist/cli.d.ts

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 /**
- * Минимальный CLI:
+ * CLI: три подкоманды.
  *
  *   confluence-md-sync publish page.md --page-id 12345 \
  *     --image build/p1.png --file data.csv --label docs --dry-run
- *
  *   confluence-md-sync publish page.md --space DOCS --title "My Page" --parent-id 777
  *
+ *   confluence-md-sync export 12345 --out-dir ./exported
+ *   confluence-md-sync roundtrip 12345           # проверка без потерь, ничего не пишет
+ *
  * Конфиг — из env: CONFLUENCE_BASE_URL, CONFLUENCE_TOKEN (или CONFLUENCE_PAT),
  * CONFLUENCE_USERNAME, CONFLUENCE_AUTH_TYPE (bearer|basic).
  */

package/dist/cli.js

@@ -1,35 +1,52 @@
 #!/usr/bin/env node
 /**
- * Минимальный CLI:
+ * CLI: три подкоманды.
  *
  *   confluence-md-sync publish page.md --page-id 12345 \
  *     --image build/p1.png --file data.csv --label docs --dry-run
- *
  *   confluence-md-sync publish page.md --space DOCS --title "My Page" --parent-id 777
  *
+ *   confluence-md-sync export 12345 --out-dir ./exported
+ *   confluence-md-sync roundtrip 12345           # проверка без потерь, ничего не пишет
+ *
  * Конфиг — из env: CONFLUENCE_BASE_URL, CONFLUENCE_TOKEN (или CONFLUENCE_PAT),
  * CONFLUENCE_USERNAME, CONFLUENCE_AUTH_TYPE (bearer|basic).
  */
 import { parseArgs } from 'node:util';
 import { loadConfigFromEnv } from './client/config.js';
 import { publishPage } from './publish/publish.js';
-const HELP = `confluence-md-sync — publish Markdown to Confluence
+import { exportPage } from './export/export-page.js';
+import { roundTripPage } from './export/roundtrip.js';
+const HELP = `confluence-md-sync — Markdown ⇄ Confluence
 
 Usage:
-  confluence-md-sync publish <markdown-file> [options]
+  confluence-md-sync publish   <markdown-file> [options]
+  confluence-md-sync export    <page-id> [--out <file> | --out-dir <dir>] [--no-attachments]
+  confluence-md-sync roundtrip <page-id> [--show-markdown]
 
-Options:
+publish options:
   --page-id <id>        Target page ID
   --space <key>         Space key (with --title, when page ID is unknown)
   --title <title>       Page title (rename, or lookup/create key with --space)
   --parent-id <id>      Parent page for page creation
-  --image <path>        Attach an image (repeatable), referenced as {{img:name.png}}
-  --file <path>         Attach a file (repeatable), referenced as {{file:name.csv}}
+  --image <src>         Attach an image (repeatable), referenced as {{img:name.png}}
+  --file <src>          Attach a file (repeatable), referenced as {{file:name.csv}}
+                        <src> is a relative/absolute path or an http(s) URL;
+                        URLs on the Confluence host are fetched with your token
   --label <name>        Ensure label on the page (repeatable)
   --message <text>      Page version comment
   --no-create           Fail instead of creating a missing page
   --dry-run             Render and validate without writing to Confluence
-  --help                Show this help
+
+export options:
+  --out <file>          Write the Markdown to exactly this path (attachments,
+                        if any, go to attachments/ next to it)
+  --out-dir <dir>       Output directory (default: ./<page-id>); writes page.md
+                        and attachments/
+  --no-attachments      Do not download referenced attachments
+
+roundtrip options:
+  --show-markdown       Print the intermediate Markdown to stdout
 
 Environment:
   CONFLUENCE_BASE_URL   e.g. https://confluence.example.com
@@ -51,33 +68,64 @@ async function main() {
             message: { type: 'string' },
             'no-create': { type: 'boolean' },
             'dry-run': { type: 'boolean' },
+            out: { type: 'string' },
+            'out-dir': { type: 'string' },
+            'no-attachments': { type: 'boolean' },
+            'show-markdown': { type: 'boolean' },
             help: { type: 'boolean' },
         },
     });
-    if (values.help || positionals.length === 0) {
+    const [command, arg] = positionals;
+    if (values.help || command === undefined) {
         console.log(HELP);
         process.exit(values.help ? 0 : 1);
     }
-    const [command, markdownPath] = positionals;
-    if (command !== 'publish' || !markdownPath) {
-        console.error(`Unknown command or missing file. See --help.`);
-        process.exit(1);
-    }
     const cfg = loadConfigFromEnv();
-    const result = await publishPage({
-        pageId: values['page-id'],
-        spaceKey: values.space,
-        title: values.title,
-        parentPageId: values['parent-id'],
-        markdownPath,
-        images: values.image ?? [],
-        files: values.file ?? [],
-        labels: values.label,
-        versionMessage: values.message,
-        createIfMissing: values['no-create'] ? false : undefined,
-        dryRun: values['dry-run'],
-    }, cfg);
-    console.log(`[cli] ${result.updated ? 'published' : 'unchanged'}: page ${result.pageId} v${result.version}`);
+    if (command === 'publish') {
+        if (!arg)
+            throw new Error('publish: markdown file is required');
+        const result = await publishPage({
+            pageId: values['page-id'],
+            spaceKey: values.space,
+            title: values.title,
+            parentPageId: values['parent-id'],
+            markdownPath: arg,
+            images: values.image ?? [],
+            files: values.file ?? [],
+            labels: values.label,
+            versionMessage: values.message,
+            createIfMissing: values['no-create'] ? false : undefined,
+            dryRun: values['dry-run'],
+        }, cfg);
+        console.log(`[cli] ${result.updated ? 'published' : 'unchanged'}: page ${result.pageId} v${result.version}`);
+        return;
+    }
+    if (command === 'export') {
+        if (!arg)
+            throw new Error('export: page id is required');
+        const result = await exportPage(arg, {
+            outFile: values.out,
+            outDir: values['out-dir'],
+            downloadAttachments: !values['no-attachments'],
+        }, cfg);
+        console.log(`[cli] exported page ${result.pageId} "${result.title}" v${result.version} → ${result.markdownPath}` +
+            ` (${result.downloaded.size} attachment(s), ${result.stats.fenced} raw storage block(s))`);
+        return;
+    }
+    if (command === 'roundtrip') {
+        if (!arg)
+            throw new Error('roundtrip: page id is required');
+        const result = await roundTripPage(arg, cfg);
+        if (values['show-markdown'])
+            console.log(result.markdown);
+        console.log(`[cli] roundtrip page ${arg} "${result.title}": ${result.equal ? 'OK — no markup loss' : 'DIFFERENCES FOUND'}` +
+            ` (markers=${result.stats.markers}, fenced=${result.stats.fenced}, rawHtml=${result.stats.rawHtml})`);
+        for (const d of result.diffs)
+            console.error(`  ${d.path}: ${d.message}`);
+        process.exit(result.equal ? 0 : 2);
+    }
+    console.error(`Unknown command '${command}'. See --help.`);
+    process.exit(1);
 }
 main().catch((err) => {
     console.error(`[cli] failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/export/canonical.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Канонизация storage-деревьев и сравнение «без потери разметки».
+ *
+ * Побайтовое равенство storage → md → storage недостижимо и не нужно:
+ * Confluence сам нормализует storage при каждом сохранении, ac:macro-id
+ * генерируется заново, markdown-it меняет форму сущностей. Критерий
+ * эквивалентности: XML-деревья равны после канонизации —
+ *  - ac:macro-id / ac:schema-version отброшены;
+ *  - сущности декодированы, пробельные последовательности схлопнуты;
+ *  - пробельные text-узлы между блочными элементами удалены;
+ *  - краевые пробелы вынесены из инлайн-форматирования
+ *    (<strong>a </strong>b ≡ <strong>a</strong> b);
+ *  - параметры макросов отсортированы по имени;
+ *  - <img src=…> ≡ <ac:image><ri:url ri:value=…/></ac:image>;
+ *  - атрибуты отсортированы по имени.
+ */
+import { type XNode } from './xhtml.js';
+/** Канонический узел: element | text (после нормализации). */
+export type CNode = {
+    kind: 'el';
+    name: string;
+    attrs: Record<string, string>;
+    children: CNode[];
+} | {
+    kind: 'text';
+    text: string;
+};
+export declare function canonicalize(nodes: XNode[]): CNode[];
+export interface StorageDiff {
+    path: string;
+    message: string;
+}
+export interface CompareResult {
+    equal: boolean;
+    diffs: StorageDiff[];
+}
+/** Сравнивает два storage-фрагмента с точностью до канонизации. */
+export declare function compareStorage(a: string, b: string, maxDiffs?: number): CompareResult;

package/dist/export/canonical.js

@@ -0,0 +1,272 @@
+/**
+ * Канонизация storage-деревьев и сравнение «без потери разметки».
+ *
+ * Побайтовое равенство storage → md → storage недостижимо и не нужно:
+ * Confluence сам нормализует storage при каждом сохранении, ac:macro-id
+ * генерируется заново, markdown-it меняет форму сущностей. Критерий
+ * эквивалентности: XML-деревья равны после канонизации —
+ *  - ac:macro-id / ac:schema-version отброшены;
+ *  - сущности декодированы, пробельные последовательности схлопнуты;
+ *  - пробельные text-узлы между блочными элементами удалены;
+ *  - краевые пробелы вынесены из инлайн-форматирования
+ *    (<strong>a </strong>b ≡ <strong>a</strong> b);
+ *  - параметры макросов отсортированы по имени;
+ *  - <img src=…> ≡ <ac:image><ri:url ri:value=…/></ac:image>;
+ *  - атрибуты отсортированы по имени.
+ */
+import { decodeEntities, parseStorage } from './xhtml.js';
+// Элементы, внутри которых пробелы значимы и не схлопываются.
+const PRESERVE_WS = new Set(['pre', 'ac:plain-text-body', 'ac:plain-text-link-body']);
+// Инлайн-форматирование: краевые пробелы выносим наружу, пустые узлы убираем.
+const INLINE_FORMATTING = new Set(['strong', 'b', 'em', 'i', 'u', 's', 'del', 'span', 'sub', 'sup']);
+// Блочные элементы: пробельный текст рядом с ними — форматирование исходника.
+const BLOCK_LEVEL = new Set([
+    'p', 'div', 'table', 'thead', 'tbody', 'tfoot', 'tr', 'td', 'th', 'colgroup', 'col',
+    'ul', 'ol', 'li', 'blockquote', 'hr', 'pre',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'ac:structured-macro', 'ac:rich-text-body', 'ac:parameter', 'ac:plain-text-body',
+    'ac:layout', 'ac:layout-section', 'ac:layout-cell', 'ac:task-list', 'ac:task',
+]);
+const DROP_ATTRS = new Set(['ac:macro-id', 'ac:schema-version']);
+function isWsOnly(s) {
+    return /^[ \t\r\n]*$/.test(s);
+}
+function collapseWs(s) {
+    return s.replace(/[ \t\r\n]+/g, ' ');
+}
+export function canonicalize(nodes) {
+    return normalizeChildren(nodes, /* preserveWs */ false, /* inlineContainer */ false);
+}
+function normalizeChildren(nodes, preserveWs, inlineContainer) {
+    // 1. Узлы → канонические (рекурсивно), комментарии отбрасываются.
+    let out = [];
+    for (const n of nodes) {
+        if (n.kind === 'comment')
+            continue;
+        if (n.kind === 'cdata') {
+            out.push({ kind: 'text', text: n.text });
+            continue;
+        }
+        if (n.kind === 'text') {
+            out.push({ kind: 'text', text: decodeEntities(n.raw) });
+            continue;
+        }
+        out.push(canonicalizeElement(n));
+    }
+    if (!preserveWs) {
+        // 2. Пробельный text-узел между блочными границами (блочный элемент
+        //    или край контейнера) — форматирование исходника, удаляем.
+        //    Между инлайн-элементами (спанами) пробел значим — остаётся.
+        out = out.filter((node, idx) => {
+            if (node.kind !== 'text' || !isWsOnly(node.text))
+                return true;
+            const prev = out[idx - 1];
+            const next = out[idx + 1];
+            const prevBoundary = prev === undefined || (prev.kind === 'el' && BLOCK_LEVEL.has(prev.name));
+            const nextBoundary = next === undefined || (next.kind === 'el' && BLOCK_LEVEL.has(next.name));
+            return !(prevBoundary && nextBoundary);
+        });
+        for (const node of out) {
+            if (node.kind === 'text')
+                node.text = collapseWs(node.text);
+        }
+        // 3. Краевые пробелы инлайн-форматирования — наружу; пустые узлы —
+        //    прочь; смежные одноимённые (без атрибутов) — в один:
+        //    <strong>a</strong><strong>b</strong> ≡ <strong>ab</strong>.
+        out = mergeAdjacentFormatting(hoistEdgeWhitespace(out));
+        // 4. Соседние text-узлы сливаем, схлопываем повторно. Края обрезаем
+        //    только в блочном контексте: краевой пробел ВНУТРИ инлайн-элемента
+        //    значим — его выносит наружу hoistEdgeWhitespace на уровне родителя.
+        out = mergeTexts(out);
+        if (inlineContainer)
+            return out;
+        if (out.length > 0) {
+            const first = out[0];
+            if (first.kind === 'text') {
+                first.text = first.text.replace(/^ +/, '');
+                if (first.text === '')
+                    out.shift();
+            }
+        }
+        if (out.length > 0) {
+            const last = out[out.length - 1];
+            if (last.kind === 'text') {
+                last.text = last.text.replace(/ +$/, '');
+                if (last.text === '')
+                    out.pop();
+            }
+        }
+    }
+    return out;
+}
+function canonicalizeElement(el) {
+    // <img src=…> и <ac:image><ri:url ri:value=…/></ac:image> — одно и то же
+    // изображение по внешнему URL; канонизируем к форме ac:image.
+    if (el.name === 'img') {
+        const attrs = {};
+        let url = '';
+        for (const [k, v] of el.attrs) {
+            const value = decodeEntities(v);
+            if (k === 'src')
+                url = value;
+            else if (k === 'alt' && value === '')
+                continue;
+            else if (k === 'alt')
+                attrs['ac:alt'] = value;
+            else
+                attrs[`ac:${k}`] = value;
+        }
+        return {
+            kind: 'el',
+            name: 'ac:image',
+            attrs,
+            children: [{ kind: 'el', name: 'ri:url', attrs: { 'ri:value': url }, children: [] }],
+        };
+    }
+    const attrs = {};
+    for (const [k, v] of el.attrs) {
+        if (DROP_ATTRS.has(k))
+            continue;
+        const value = decodeEntities(v);
+        if (el.name === 'ac:image' && k === 'ac:alt' && value === '')
+            continue;
+        attrs[k] = value;
+    }
+    const preserve = PRESERVE_WS.has(el.name);
+    let children = normalizeChildren(el.children, preserve, INLINE_FORMATTING.has(el.name));
+    // <p><ac:structured-macro/></p> ≡ <ac:structured-macro/> — обёртка
+    // блочного макроса в абзац не влияет на рендер Confluence.
+    if (el.name === 'p' && el.attrs.length === 0 && children.length === 1 &&
+        children[0].kind === 'el' && children[0].name === 'ac:structured-macro') {
+        return children[0];
+    }
+    // Параметры макроса не зависят от порядка — сортируем по ac:name.
+    if (el.name === 'ac:structured-macro') {
+        children = [...children].sort((a, b) => {
+            const an = a.kind === 'el' && a.name === 'ac:parameter' ? (a.attrs['ac:name'] ?? '') : '￿';
+            const bn = b.kind === 'el' && b.name === 'ac:parameter' ? (b.attrs['ac:name'] ?? '') : '￿';
+            return an < bn ? -1 : an > bn ? 1 : 0;
+        });
+    }
+    return { kind: 'el', name: el.name, attrs, children };
+}
+/** `<strong>a </strong>b` → `<strong>a</strong> b` (рекурсивно, для сравнения). */
+function hoistEdgeWhitespace(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        if (node.kind !== 'el' || !INLINE_FORMATTING.has(node.name)) {
+            out.push(node);
+            continue;
+        }
+        let leading = '';
+        let trailing = '';
+        const kids = node.children;
+        if (kids.length > 0 && kids[0].kind === 'text') {
+            const m = kids[0].text.match(/^ +/);
+            if (m) {
+                leading = ' ';
+                kids[0].text = kids[0].text.slice(m[0].length);
+            }
+        }
+        if (kids.length > 0) {
+            const last = kids[kids.length - 1];
+            if (last.kind === 'text') {
+                const m = last.text.match(/ +$/);
+                if (m) {
+                    trailing = ' ';
+                    last.text = last.text.slice(0, -m[0].length);
+                }
+            }
+        }
+        node.children = mergeTexts(kids.filter((k) => !(k.kind === 'text' && k.text === '')));
+        if (leading)
+            out.push({ kind: 'text', text: leading });
+        if (node.children.length > 0)
+            out.push(node);
+        if (trailing)
+            out.push({ kind: 'text', text: trailing });
+    }
+    return out;
+}
+function mergeAdjacentFormatting(nodes) {
+    const out = [];
+    for (const n of nodes) {
+        const prev = out[out.length - 1];
+        if (n.kind === 'el' && INLINE_FORMATTING.has(n.name) && Object.keys(n.attrs).length === 0 &&
+            prev !== undefined && prev.kind === 'el' && prev.name === n.name && Object.keys(prev.attrs).length === 0) {
+            prev.children = mergeTexts([...prev.children, ...n.children]);
+        }
+        else {
+            out.push(n);
+        }
+    }
+    return out;
+}
+function mergeTexts(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        const prev = out[out.length - 1];
+        if (node.kind === 'text' && prev !== undefined && prev.kind === 'text') {
+            prev.text = collapseWs(prev.text + node.text);
+        }
+        else {
+            out.push(node);
+        }
+    }
+    return out;
+}
+/** Сравнивает два storage-фрагмента с точностью до канонизации. */
+export function compareStorage(a, b, maxDiffs = 20) {
+    const ca = canonicalize(parseStorage(a));
+    const cb = canonicalize(parseStorage(b));
+    const diffs = [];
+    diffNodes(ca, cb, 'root', diffs, maxDiffs);
+    return { equal: diffs.length === 0, diffs };
+}
+function excerpt(n) {
+    if (n === undefined)
+        return '(none)';
+    if (n.kind === 'text')
+        return `text ${JSON.stringify(n.text.slice(0, 80))}`;
+    const attrs = Object.entries(n.attrs).map(([k, v]) => ` ${k}="${v.slice(0, 40)}"`).join('');
+    return `<${n.name}${attrs.slice(0, 120)}>`;
+}
+function diffNodes(a, b, path, diffs, max) {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len && diffs.length < max; i++) {
+        const na = a[i];
+        const nb = b[i];
+        const p = `${path}[${i}]`;
+        if (na === undefined || nb === undefined) {
+            diffs.push({ path: p, message: `node mismatch: ${excerpt(na)} vs ${excerpt(nb)}` });
+            continue;
+        }
+        if (na.kind !== nb.kind) {
+            diffs.push({ path: p, message: `kind mismatch: ${excerpt(na)} vs ${excerpt(nb)}` });
+            continue;
+        }
+        if (na.kind === 'text' && nb.kind === 'text') {
+            if (na.text !== nb.text) {
+                diffs.push({ path: p, message: `text differs: ${JSON.stringify(na.text.slice(0, 120))} vs ${JSON.stringify(nb.text.slice(0, 120))}` });
+            }
+            continue;
+        }
+        if (na.kind === 'el' && nb.kind === 'el') {
+            const childPath = `${p}<${na.name}>`;
+            if (na.name !== nb.name) {
+                diffs.push({ path: p, message: `element differs: <${na.name}> vs <${nb.name}>` });
+                continue;
+            }
+            const keys = new Set([...Object.keys(na.attrs), ...Object.keys(nb.attrs)]);
+            for (const k of keys) {
+                if (na.attrs[k] !== nb.attrs[k]) {
+                    diffs.push({
+                        path: childPath,
+                        message: `attr ${k}: ${JSON.stringify(na.attrs[k] ?? null)} vs ${JSON.stringify(nb.attrs[k] ?? null)}`,
+                    });
+                }
+            }
+            diffNodes(na.children, nb.children, childPath, diffs, max);
+        }
+    }
+}