@knpkv/confluence-to-markdown 0.6.0 → 0.7.0

package/test/MarkdownConverter.test.ts

@@ -75,7 +75,7 @@ describe("MarkdownConverter", () => {
         expect(md).toContain("const x = 1")
       }).pipe(Effect.provide(TestLayer)))
 
-    it.effect("converts a panel to a GitHub admonition", () =>
+    it.effect("converts a panel to a Confluence-preserving placeholder", () =>
       Effect.gen(function*() {
         const converter = yield* MarkdownConverter
         const md = yield* converter.adfToMarkdown(
@@ -85,18 +85,19 @@ describe("MarkdownConverter", () => {
             content: [{ type: "paragraph", content: [{ type: "text", text: "heads up" }] }]
           }])
         )
-        expect(md).toContain("[!NOTE]")
+        expect(md).toContain("<!-- adf:panel type=info attrs=")
         expect(md).toContain("heads up")
+        expect(md).toContain("<!-- adf:/panel -->")
       }).pipe(Effect.provide(TestLayer)))
 
     it.effect("fails with ConversionError on invalid JSON", () =>
       Effect.gen(function*() {
         const converter = yield* MarkdownConverter
-        const result = yield* Effect.either(converter.adfToMarkdown("not json"))
-        expect(result._tag).toBe("Left")
-        if (result._tag === "Left") {
-          expect(result.left._tag).toBe("ConversionError")
-          expect(result.left.direction).toBe("adfToMarkdown")
+        const result = yield* Effect.result(converter.adfToMarkdown("not json"))
+        expect(result._tag).toBe("Failure")
+        if (result._tag === "Failure") {
+          expect(result.failure._tag).toBe("ConversionError")
+          expect(result.failure.direction).toBe("adfToMarkdown")
         }
       }).pipe(Effect.provide(TestLayer)))
 
@@ -124,10 +125,10 @@ describe("MarkdownConverter", () => {
         // page that could overwrite a real local file.
         const converter = yield* MarkdownConverter
         for (const bad of ["null", "{}", "[1,2]", `{"type":"doc","content":"not an array"}`]) {
-          const result = yield* Effect.either(converter.adfToMarkdown(bad))
-          expect(result._tag).toBe("Left")
-          if (result._tag === "Left") {
-            expect(result.left._tag).toBe("ConversionError")
+          const result = yield* Effect.result(converter.adfToMarkdown(bad))
+          expect(result._tag).toBe("Failure")
+          if (result._tag === "Failure") {
+            expect(result.failure._tag).toBe("ConversionError")
           }
         }
       }).pipe(Effect.provide(TestLayer)))

package/test/RoundTrip.test.ts

@@ -131,12 +131,20 @@ describe("MarkdownConverter round-trip", () => {
       expect(md).toContain(`<span class="adf-status" data-color="blue">TESTING</span>`)
     }).pipe(Effect.provide(TestLayer)))
 
-  it.effect("upgrades a legacy block extension placeholder to the attrs form, then stays fixed", () =>
+  it.effect("upgrades a legacy generic block extension placeholder to the attrs form, then stays fixed", () =>
     Effect.gen(function*() {
       const md = yield* roundTrip(
-        `<!-- adf:extension key=toc type=com.atlassian.confluence.macro.core -->\n`
+        `<!-- adf:extension key=anchor type=com.atlassian.confluence.macro.core -->\n`
       )
-      expect(md).toContain("<!-- adf:extension key=toc type=com.atlassian.confluence.macro.core attrs=")
+      expect(md).toContain("<!-- adf:extension key=anchor type=com.atlassian.confluence.macro.core attrs=")
+      const again = yield* roundTrip(md)
+      expect(again).toBe(md)
+    }).pipe(Effect.provide(TestLayer)))
+
+  it.effect("round-trips native TOC syntax as a fixed point", () =>
+    Effect.gen(function*() {
+      const md = yield* roundTrip("[[toc:min=2,max=4]]\n")
+      expect(md).toContain("[[toc:min=2,max=4]]")
       const again = yield* roundTrip(md)
       expect(again).toBe(md)
     }).pipe(Effect.provide(TestLayer)))
@@ -162,6 +170,34 @@ describe("MarkdownConverter round-trip", () => {
       expect(adfOut.content[0]).toEqual({ type: "extension", attrs })
     }).pipe(Effect.provide(TestLayer)))
 
+  it.effect("round-trips Confluence TOC macroMetadata through the placeholder attrs blob", () =>
+    Effect.gen(function*() {
+      const converter = yield* MarkdownConverter
+      const attrs = {
+        extensionKey: "toc",
+        extensionType: "com.atlassian.confluence.macro.core",
+        layout: "default",
+        parameters: {
+          macroMetadata: {
+            schemaVersion: { value: "1" },
+            title: "Table of Contents"
+          },
+          macroParams: {}
+        }
+      }
+      const md = yield* converter.adfToMarkdown(JSON.stringify({
+        version: 1,
+        type: "doc",
+        content: [{ type: "extension", attrs }]
+      }))
+      expect(md).toContain("<!-- adf:extension key=toc type=com.atlassian.confluence.macro.core attrs=")
+      expect(md).not.toContain("[[toc")
+      const adfOut = JSON.parse(yield* converter.markdownToAdf(md)) as {
+        content: Array<{ type: string; attrs: Record<string, unknown> }>
+      }
+      expect(adfOut.content[0]).toEqual({ type: "extension", attrs })
+    }).pipe(Effect.provide(TestLayer)))
+
   it.effect("round-trips a bodiedExtension with its body re-attached", () =>
     Effect.gen(function*() {
       const converter = yield* MarkdownConverter
@@ -189,6 +225,225 @@ describe("MarkdownConverter round-trip", () => {
       ])
     }).pipe(Effect.provide(TestLayer)))
 
+  it.effect("round-trips a Confluence panel as a panel node", () =>
+    Effect.gen(function*() {
+      const converter = yield* MarkdownConverter
+      const attrs = { panelType: "warning" }
+      const md = yield* converter.adfToMarkdown(JSON.stringify({
+        version: 1,
+        type: "doc",
+        content: [{
+          type: "panel",
+          attrs,
+          content: [{ type: "paragraph", content: [{ type: "text", text: "watch this" }] }]
+        }]
+      }))
+      const adfOut = JSON.parse(yield* converter.markdownToAdf(md)) as {
+        content: Array<{ type: string; attrs: Record<string, unknown>; content: Array<unknown> }>
+      }
+      expect(adfOut.content[0]).toEqual({
+        type: "panel",
+        attrs,
+        content: [{ type: "paragraph", content: [{ type: "text", text: "watch this" }] }]
+      })
+    }).pipe(Effect.provide(TestLayer)))
+
+  it.effect("round-trips Confluence-only inline marks as native marks", () =>
+    Effect.gen(function*() {
+      const converter = yield* MarkdownConverter
+      const source = {
+        version: 1,
+        type: "doc",
+        content: [{
+          type: "paragraph",
+          content: [
+            { type: "text", text: "underline", marks: [{ type: "underline" }] },
+            { type: "text", text: "2", marks: [{ type: "subsup", attrs: { type: "sub" } }] },
+            { type: "text", text: "2", marks: [{ type: "subsup", attrs: { type: "sup" } }] },
+            { type: "text", text: "Colored", marks: [{ type: "textColor", attrs: { color: "#ff5630" } }] },
+            { type: "text", text: "highlighted", marks: [{ type: "backgroundColor", attrs: { color: "#f8e6a0" } }] }
+          ]
+        }]
+      }
+      const md = yield* converter.adfToMarkdown(JSON.stringify(source))
+      const adfOut = JSON.parse(yield* converter.markdownToAdf(md)) as typeof source
+      expect(adfOut.content[0]).toEqual(source.content[0])
+    }).pipe(Effect.provide(TestLayer)))
+
+  it.effect("round-trips paragraph alignment and indentation marks", () =>
+    Effect.gen(function*() {
+      const converter = yield* MarkdownConverter
+      const source = {
+        version: 1,
+        type: "doc",
+        content: [
+          {
+            type: "paragraph",
+            marks: [{ type: "alignment", attrs: { align: "center" } }],
+            content: [{ type: "text", text: "centered" }]
+          },
+          {
+            type: "paragraph",
+            marks: [{ type: "alignment", attrs: { align: "end" } }],
+            content: [{ type: "text", text: "right" }]
+          },
+          {
+            type: "paragraph",
+            marks: [{ type: "indentation", attrs: { level: 2 } }],
+            content: [{ type: "text", text: "indented" }]
+          }
+        ]
+      }
+      const md = yield* converter.adfToMarkdown(JSON.stringify(source))
+      const adfOut = JSON.parse(yield* converter.markdownToAdf(md)) as typeof source
+      expect(adfOut.content).toEqual(source.content)
+    }).pipe(Effect.provide(TestLayer)))
+
+  it.effect("round-trips inline smart links as native inlineCard nodes", () =>
+    Effect.gen(function*() {
+      const converter = yield* MarkdownConverter
+      const source = {
+        version: 1,
+        type: "doc",
+        content: [{
+          type: "paragraph",
+          content: [
+            { type: "text", text: "Inline smart link: " },
+            { type: "inlineCard", attrs: { url: "https://www.atlassian.com" } },
+            { type: "text", text: "." }
+          ]
+        }]
+      }
+      const md = yield* converter.adfToMarkdown(JSON.stringify(source))
+      const adfOut = JSON.parse(yield* converter.markdownToAdf(md)) as typeof source
+      expect(adfOut.content[0]).toEqual(source.content[0])
+    }).pipe(Effect.provide(TestLayer)))
+
+  it.effect("round-trips task lists as native task nodes", () =>
+    Effect.gen(function*() {
+      const converter = yield* MarkdownConverter
+      const source = {
+        version: 1,
+        type: "doc",
+        content: [{
+          type: "taskList",
+          attrs: { localId: "tasks-1" },
+          content: [
+            {
+              type: "taskItem",
+              attrs: { localId: "task-1", state: "DONE" },
+              content: [{ type: "text", text: "Existing primitive coverage reviewed" }]
+            },
+            {
+              type: "taskItem",
+              attrs: { localId: "task-2", state: "TODO" },
+              content: [{ type: "text", text: "Insert real @mention in editor" }]
+            }
+          ]
+        }]
+      }
+      const md = yield* converter.adfToMarkdown(JSON.stringify(source))
+      const adfOut = JSON.parse(yield* converter.markdownToAdf(md)) as typeof source
+      expect(adfOut.content[0]).toEqual(source.content[0])
+    }).pipe(Effect.provide(TestLayer)))
+
+  it.effect("round-trips decision lists as native decision nodes", () =>
+    Effect.gen(function*() {
+      const converter = yield* MarkdownConverter
+      const source = {
+        version: 1,
+        type: "doc",
+        content: [{
+          type: "decisionList",
+          attrs: { localId: "decisions-1" },
+          content: [{
+            type: "decisionItem",
+            attrs: { localId: "decision-1", state: "DECIDED" },
+            content: [{ type: "text", text: "Decide whether to maintain a separate asset for advanced macros." }]
+          }]
+        }]
+      }
+      const md = yield* converter.adfToMarkdown(JSON.stringify(source))
+      const adfOut = JSON.parse(yield* converter.markdownToAdf(md)) as typeof source
+      expect(adfOut.content[0]).toEqual(source.content[0])
+    }).pipe(Effect.provide(TestLayer)))
+
+  it.effect("round-trips expand, table, layout, cards, date, and emoji as native nodes", () =>
+    Effect.gen(function*() {
+      const converter = yield* MarkdownConverter
+      const source = {
+        version: 1,
+        type: "doc",
+        content: [
+          {
+            type: "expand",
+            attrs: { title: "Expandable supplementary content" },
+            content: [{ type: "paragraph", content: [{ type: "text", text: "This section can be expanded." }] }]
+          },
+          {
+            type: "table",
+            content: [{
+              type: "tableRow",
+              content: [
+                {
+                  type: "tableHeader",
+                  content: [{ type: "paragraph", content: [{ type: "text", text: "Primitive" }] }]
+                },
+                {
+                  type: "tableHeader",
+                  content: [{ type: "paragraph", content: [{ type: "text", text: "Example" }] }]
+                }
+              ]
+            }, {
+              type: "tableRow",
+              content: [
+                { type: "tableCell", content: [{ type: "paragraph", content: [{ type: "text", text: "Date" }] }] },
+                {
+                  type: "tableCell",
+                  content: [{
+                    type: "paragraph",
+                    content: [{ type: "date", attrs: { timestamp: "1782259200000" } }]
+                  }]
+                }
+              ]
+            }, {
+              type: "tableRow",
+              content: [
+                { type: "tableCell", content: [{ type: "paragraph", content: [{ type: "text", text: "Emoji" }] }] },
+                {
+                  type: "tableCell",
+                  content: [{
+                    type: "paragraph",
+                    content: [{ type: "emoji", attrs: { shortName: ":white_check_mark:", text: "✅" } }]
+                  }]
+                }
+              ]
+            }]
+          },
+          {
+            type: "layoutSection",
+            content: [
+              {
+                type: "layoutColumn",
+                attrs: { width: 50 },
+                content: [{ type: "paragraph", content: [{ type: "text", text: "Left column" }] }]
+              },
+              {
+                type: "layoutColumn",
+                attrs: { width: 50 },
+                content: [{ type: "paragraph", content: [{ type: "text", text: "Right column" }] }]
+              }
+            ]
+          },
+          { type: "blockCard", attrs: { url: "https://www.atlassian.com/software/confluence" } },
+          { type: "embedCard", attrs: { url: "https://www.atlassian.com/software/confluence", layout: "center" } }
+        ]
+      }
+      const md = yield* converter.adfToMarkdown(JSON.stringify(source))
+      const adfOut = JSON.parse(yield* converter.markdownToAdf(md)) as typeof source
+      expect(adfOut.content).toEqual(source.content)
+    }).pipe(Effect.provide(TestLayer)))
+
   // Regression: `|` in a cell was escaped twice (escapeText + the table-cell
   // pass), emitting `\\|` — GFM reads that as literal backslash + bare pipe,
   // which opens a phantom column and breaks the row.

package/test/Schemas.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "@effect/vitest"
-import * as Either from "effect/Either"
+import * as Result from "effect/Result"
 import * as Schema from "effect/Schema"
 import type { ContentHash, PageId } from "../src/Brand.js"
 import {
@@ -17,11 +17,11 @@ describe("Schemas", () => {
         rootPageId: "123456",
         baseUrl: "https://mysite.atlassian.net"
       }
-      const result = Schema.decodeUnknownEither(ConfluenceConfigFileSchema)(config)
-      expect(Either.isRight(result)).toBe(true)
-      if (Either.isRight(result)) {
-        expect(result.right.docsPath).toBe(".confluence/docs")
-        expect(result.right.excludePatterns).toEqual([])
+      const result = Schema.decodeUnknownResult(ConfluenceConfigFileSchema)(config)
+      expect(Result.isSuccess(result)).toBe(true)
+      if (Result.isSuccess(result)) {
+        expect(result.success.docsPath).toBe(".confluence/docs")
+        expect(result.success.excludePatterns).toEqual([])
       }
     })
 
@@ -33,11 +33,11 @@ describe("Schemas", () => {
         docsPath: "docs",
         excludePatterns: ["*.tmp"]
       }
-      const result = Schema.decodeUnknownEither(ConfluenceConfigFileSchema)(config)
-      expect(Either.isRight(result)).toBe(true)
-      if (Either.isRight(result)) {
-        expect(result.right.spaceKey).toBe("DEV")
-        expect(result.right.docsPath).toBe("docs")
+      const result = Schema.decodeUnknownResult(ConfluenceConfigFileSchema)(config)
+      expect(Result.isSuccess(result)).toBe(true)
+      if (Result.isSuccess(result)) {
+        expect(result.success.spaceKey).toBe("DEV")
+        expect(result.success.docsPath).toBe("docs")
       }
     })
 
@@ -46,14 +46,14 @@ describe("Schemas", () => {
         rootPageId: "123456",
         baseUrl: "http://invalid.com"
       }
-      const result = Schema.decodeUnknownEither(ConfluenceConfigFileSchema)(config)
-      expect(Either.isLeft(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(ConfluenceConfigFileSchema)(config)
+      expect(Result.isFailure(result)).toBe(true)
     })
 
     it("rejects missing required fields", () => {
       const config = { baseUrl: "https://mysite.atlassian.net" }
-      const result = Schema.decodeUnknownEither(ConfluenceConfigFileSchema)(config)
-      expect(Either.isLeft(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(ConfluenceConfigFileSchema)(config)
+      expect(Result.isFailure(result)).toBe(true)
     })
   })
 
@@ -68,8 +68,8 @@ describe("Schemas", () => {
         updated: new Date().toISOString(),
         contentHash: validHash
       }
-      const result = Schema.decodeUnknownEither(PageFrontMatterSchema)(fm)
-      expect(Either.isRight(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(PageFrontMatterSchema)(fm)
+      expect(Result.isSuccess(result)).toBe(true)
     })
 
     it("decodes front matter with optional fields", () => {
@@ -82,11 +82,11 @@ describe("Schemas", () => {
         position: 0,
         contentHash: validHash
       }
-      const result = Schema.decodeUnknownEither(PageFrontMatterSchema)(fm)
-      expect(Either.isRight(result)).toBe(true)
-      if (Either.isRight(result)) {
-        expect(result.right.parentId).toBe("456")
-        expect(result.right.position).toBe(0)
+      const result = Schema.decodeUnknownResult(PageFrontMatterSchema)(fm)
+      expect(Result.isSuccess(result)).toBe(true)
+      if (Result.isSuccess(result)) {
+        expect(result.success.parentId).toBe("456")
+        expect(result.success.position).toBe(0)
       }
     })
 
@@ -98,8 +98,8 @@ describe("Schemas", () => {
         updated: new Date().toISOString(),
         contentHash: validHash
       }
-      const result = Schema.decodeUnknownEither(PageFrontMatterSchema)(fm)
-      expect(Either.isLeft(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(PageFrontMatterSchema)(fm)
+      expect(Result.isFailure(result)).toBe(true)
     })
   })
 
@@ -113,8 +113,8 @@ describe("Schemas", () => {
         cloud_id: "abc123",
         site_url: "https://mysite.atlassian.net"
       }
-      const result = Schema.decodeUnknownEither(OAuthTokenSchema)(token)
-      expect(Either.isRight(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(OAuthTokenSchema)(token)
+      expect(Result.isSuccess(result)).toBe(true)
     })
 
     it("decodes token with user info", () => {
@@ -131,10 +131,10 @@ describe("Schemas", () => {
           email: "test@example.com"
         }
       }
-      const result = Schema.decodeUnknownEither(OAuthTokenSchema)(token)
-      expect(Either.isRight(result)).toBe(true)
-      if (Either.isRight(result)) {
-        expect(result.right.user?.name).toBe("Test User")
+      const result = Schema.decodeUnknownResult(OAuthTokenSchema)(token)
+      expect(Result.isSuccess(result)).toBe(true)
+      if (Result.isSuccess(result)) {
+        expect(result.success.user?.name).toBe("Test User")
       }
     })
 
@@ -147,8 +147,8 @@ describe("Schemas", () => {
         cloud_id: "abc123",
         site_url: "https://mysite.atlassian.net"
       }
-      const result = Schema.decodeUnknownEither(OAuthTokenSchema)(token)
-      expect(Either.isLeft(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(OAuthTokenSchema)(token)
+      expect(Result.isFailure(result)).toBe(true)
     })
   })
 
@@ -158,16 +158,16 @@ describe("Schemas", () => {
         clientId: "client_id_value",
         clientSecret: "client_secret_value"
       }
-      const result = Schema.decodeUnknownEither(OAuthConfigSchema)(config)
-      expect(Either.isRight(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(OAuthConfigSchema)(config)
+      expect(Result.isSuccess(result)).toBe(true)
     })
 
     it("rejects missing clientSecret", () => {
       const config = {
         clientId: "client_id_value"
       }
-      const result = Schema.decodeUnknownEither(OAuthConfigSchema)(config)
-      expect(Either.isLeft(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(OAuthConfigSchema)(config)
+      expect(Result.isFailure(result)).toBe(true)
     })
   })
 
@@ -178,8 +178,8 @@ describe("Schemas", () => {
         name: "Test User",
         email: "test@example.com"
       }
-      const result = Schema.decodeUnknownEither(OAuthUserSchema)(user)
-      expect(Either.isRight(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(OAuthUserSchema)(user)
+      expect(Result.isSuccess(result)).toBe(true)
     })
 
     it("rejects missing email", () => {
@@ -187,8 +187,8 @@ describe("Schemas", () => {
         account_id: "user123",
         name: "Test User"
       }
-      const result = Schema.decodeUnknownEither(OAuthUserSchema)(user)
-      expect(Either.isLeft(result)).toBe(true)
+      const result = Schema.decodeUnknownResult(OAuthUserSchema)(user)
+      expect(Result.isFailure(result)).toBe(true)
     })
   })
 })

package/test/adfMetadata.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "@effect/vitest"
+import { collectAdfMetadataHrefs, externalizeAdfMetadata, hydrateAdfMetadata } from "../src/internal/adfMetadata.js"
+
+const toBase64 = (text: string): string => {
+  const bytes = new TextEncoder().encode(text)
+  return btoa(String.fromCharCode(...bytes))
+}
+
+describe("ADF metadata sidecars", () => {
+  it("moves decoded placeholder metadata into a linked sidecar", () => {
+    const markdown = [
+      `<!-- adf:panel type=info attrs={"panelType":"info"} -->`,
+      "",
+      "Body",
+      "",
+      "<!-- adf:/panel -->",
+      "",
+      `Regular link: <!-- adf:inlineCard attrs={"url":"https://www.atlassian.com"} -->.`
+    ].join("\n")
+
+    const prepared = externalizeAdfMetadata(markdown, "./123.adf.json")
+
+    expect(prepared.markdown).toContain("<!-- adf:panel type=info ref=./123.adf.json#panel-1 -->")
+    expect(prepared.markdown).toContain("<!-- adf:inlineCard ref=./123.adf.json#inlineCard-2 -->")
+    expect(prepared.markdown).not.toContain("attrs={")
+    expect(prepared.sidecar).toEqual({
+      version: 1,
+      entries: {
+        "panel-1": {
+          kind: "attrs",
+          value: { panelType: "info" }
+        },
+        "inlineCard-2": {
+          kind: "attrs",
+          value: { url: "https://www.atlassian.com" }
+        }
+      }
+    })
+  })
+
+  it("moves base64 placeholder metadata into a linked sidecar", () => {
+    const attrs = {
+      extensionKey: "toc",
+      extensionType: "com.atlassian.confluence.macro.core",
+      parameters: {
+        macroMetadata: {
+          title: "Table of Contents"
+        }
+      }
+    }
+    const encodedAttrs = toBase64(JSON.stringify(attrs))
+    const markdown =
+      `| **On this page** | <!-- adf:extension key=toc type=com.atlassian.confluence.macro.core attrs=${encodedAttrs} --> |`
+
+    const prepared = externalizeAdfMetadata(markdown, "./2731114497.adf.json")
+
+    expect(prepared.markdown).toBe(
+      "| **On this page** | <!-- adf:extension key=toc type=com.atlassian.confluence.macro.core ref=./2731114497.adf.json#extension-1 --> |"
+    )
+    expect(prepared.markdown).not.toContain(encodedAttrs)
+    expect(prepared.sidecar).toEqual({
+      version: 1,
+      entries: {
+        "extension-1": {
+          kind: "attrs",
+          value: attrs
+        }
+      }
+    })
+  })
+
+  it("hydrates linked sidecar metadata back into placeholders for push", () => {
+    const markdown = `<!-- adf:taskList ref=./123.adf.json#taskList-1 -->`
+    const hydrated = hydrateAdfMetadata(
+      markdown,
+      new Map([
+        [
+          "./123.adf.json",
+          {
+            version: 1,
+            entries: {
+              "taskList-1": {
+                kind: "node",
+                value: {
+                  type: "taskList",
+                  attrs: { localId: "task-list" },
+                  content: [{ type: "taskItem", attrs: { state: "DONE" } }]
+                }
+              }
+            }
+          }
+        ]
+      ])
+    )
+
+    expect(hydrated).toBe(
+      `<!-- adf:taskList node={"attrs":{"localId":"task-list"},"content":[{"attrs":{"state":"DONE"},"type":"taskItem"}],"type":"taskList"} -->`
+    )
+  })
+
+  it("collects each referenced sidecar href once", () => {
+    const hrefs = collectAdfMetadataHrefs([
+      "<!-- adf:panel ref=./123.adf.json#panel-1 -->",
+      "<!-- adf:taskList ref=./123.adf.json#taskList-2 -->",
+      "<!-- adf:panel ref=./456.adf.json#panel-1 -->"
+    ].join("\n"))
+
+    expect([...hrefs].sort()).toEqual(["./123.adf.json", "./456.adf.json"])
+  })
+})

package/test/cleanMarkdown.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "@effect/vitest"
+import { cleanMarkdown } from "../src/internal/cleanMarkdown.js"
+
+describe("cleanMarkdown", () => {
+  it("removes full-line ADF metadata comments", () => {
+    const markdown = [
+      "# Title",
+      "",
+      "<!-- adf:panel type=info attrs={} -->",
+      "",
+      "Body",
+      "",
+      "<!-- adf:/panel -->"
+    ].join("\n")
+
+    expect(cleanMarkdown(markdown)).toBe("# Title\n\nBody\n")
+  })
+
+  it("removes inline ADF metadata comments", () => {
+    expect(cleanMarkdown("Card <!-- adf:inlineCard attrs={} --> text")).toBe("Card  text\n")
+  })
+
+  it("keeps regular markdown, native macros, status spans, and non-ADF comments", () => {
+    const markdown = [
+      "[[toc]]",
+      "",
+      "<span data-adf-status=\"todo\" data-adf-color=\"blue\">TODO</span>",
+      "",
+      "<!-- keep this comment -->",
+      "",
+      "- item"
+    ].join("\n")
+
+    expect(cleanMarkdown(markdown)).toBe(`${markdown}\n`)
+  })
+})