@knpkv/confluence-to-markdown 0.6.0 → 0.7.0

package/src/AdfPlaceholders.ts

@@ -15,16 +15,30 @@
  *      the whole paragraph is just this comment; `attrs` is base64 JSON of
  *      the node's full attrs — parameters, localId, layout — and wins over
  *      the readable key/type parts; key/type-only is the legacy form)
+ *  - `<!-- adf:paragraph marks=BASE64 --> BODY <!-- adf:/paragraph -->`
+ *      (the body paragraph regains its paragraph-level marks)
  *  - `<!-- adf:bodiedExtension … --> BODY <!-- adf:/bodiedExtension -->`
  *      (the sibling blocks between the markers become the extension's body)
+ *  - `<!-- adf:inlineCard attrs=BASE64 -->` (inline)
  *  - `<!-- adf:inlineExtension key=KEY type=TYPE attrs=BASE64 -->` (inline)
+ *  - `<!-- adf:date node=BASE64 -->` and `<!-- adf:emoji node=BASE64 -->`
+ *      (inline)
+ *  - `<!-- adf:panel type=TYPE attrs=BASE64 --> BODY <!-- adf:/panel -->`
+ *      (the sibling blocks between the markers become the panel's body)
+ *  - `<!-- adf:TYPE node=BASE64 --> BODY <!-- adf:/TYPE -->` for selected
+ *      native block nodes such as task/decision lists, expands, layouts,
+ *      cards, and tables
+ *  - `<u>TEXT</u>`, `<sub>TEXT</sub>`, `<sup>TEXT</sup>`, and exact styled
+ *      spans emitted for Confluence-only inline marks
  *  - `[@Name](confluence-mention://ACCOUNT_ID)`            (link mark with a
  *      custom scheme — the only way to round-trip mention accountIds)
+ *  - `[[toc]]`, `[[toc:min=1,max=3]]` (block-level native syntax for the
+ *      Confluence Table of Contents macro)
  *
  * @module
  */
 
-import * as Either from "effect/Either"
+import * as Option from "effect/Option"
 import * as Schema from "effect/Schema"
 
 interface AdfNode {
@@ -36,17 +50,50 @@ interface AdfNode {
 }
 
 const STATUS_RE = /<span class="adf-status"\s+data-color="([^"]+)">([^<]*)<\/span>/g
+const INLINE_NODE_RE = /<!--\s*adf:(date|emoji)(?:\s+node=([\s\S]*?))?\s*-->/g
+const INLINE_CARD_RE = /<!--\s*adf:inlineCard(?:\s+attrs=([\s\S]*?))?\s*-->/g
 const INLINE_EXTENSION_RE =
-  /<!--\s*adf:inlineExtension(?:\s+key=(\S+?))?(?:\s+type=(\S+?))?(?:\s+attrs=([A-Za-z0-9+/=]+))?\s*-->/g
-const COMBINED_INLINE_RE = new RegExp(`${STATUS_RE.source}|${INLINE_EXTENSION_RE.source}`, "g")
+  /<!--\s*adf:inlineExtension(?:\s+key=(\S+?))?(?:\s+type=(\S+?))?(?:\s+attrs=([\s\S]*?))?\s*-->/g
+const UNDERLINE_RE = /<u>([^<]*)<\/u>/g
+const SUBSCRIPT_RE = /<sub>([^<]*)<\/sub>/g
+const SUPERSCRIPT_RE = /<sup>([^<]*)<\/sup>/g
+const TEXT_COLOR_RE = /<span style="color:([^"<>]+)">([^<]*)<\/span>/g
+const BACKGROUND_COLOR_RE = /<span style="background-color:([^"<>]+)">([^<]*)<\/span>/g
+const COMBINED_INLINE_RE = new RegExp(
+  [
+    INLINE_NODE_RE.source,
+    STATUS_RE.source,
+    INLINE_CARD_RE.source,
+    INLINE_EXTENSION_RE.source,
+    UNDERLINE_RE.source,
+    SUBSCRIPT_RE.source,
+    SUPERSCRIPT_RE.source,
+    TEXT_COLOR_RE.source,
+    BACKGROUND_COLOR_RE.source
+  ].join("|"),
+  "g"
+)
 
 const BLOCK_EXTENSION_RE =
-  /^\s*<!--\s*adf:(extension|bodiedExtension)(?:\s+key=(\S+?))?(?:\s+type=(\S+?))?(?:\s+attrs=([A-Za-z0-9+/=]+))?\s*-->\s*$/
+  /^\s*<!--\s*adf:(extension|bodiedExtension)(?:\s+key=(\S+?))?(?:\s+type=(\S+?))?(?:\s+attrs=([\s\S]*?))?\s*-->\s*$/
 const BODIED_EXTENSION_END_RE = /^\s*<!--\s*adf:\/bodiedExtension\s*-->\s*$/
+const PANEL_RE = /^\s*<!--\s*adf:panel(?:\s+type=(\S+?))?(?:\s+attrs=([\s\S]*?))?\s*-->\s*$/
+const PANEL_END_RE = /^\s*<!--\s*adf:\/panel\s*-->\s*$/
+const ENCODED_BLOCK_NODE_RE =
+  /^\s*<!--\s*adf:(taskList|decisionList|expand|nestedExpand|table|layoutSection|blockCard|embedCard)(?:\s+node=([\s\S]*?))?\s*-->\s*$/
+const ENCODED_BLOCK_NODE_END_RE =
+  /^\s*<!--\s*adf:\/(taskList|decisionList|expand|nestedExpand|table|layoutSection|blockCard|embedCard)\s*-->\s*$/
+const PARAGRAPH_MARKS_RE = /^\s*<!--\s*adf:paragraph(?:\s+marks=([\s\S]*?))?\s*-->\s*$/
+const PARAGRAPH_MARKS_END_RE = /^\s*<!--\s*adf:\/paragraph\s*-->\s*$/
+const TOC_RE = /^\s*\[\[toc(?::([^\]]+))?\]\]\s*$/
+const CONFLUENCE_CORE_MACRO_TYPE = "com.atlassian.confluence.macro.core"
 
 const textNode = (text: string, marks: ReadonlyArray<AdfNode> | undefined): AdfNode =>
   marks && marks.length > 0 ? { type: "text", text, marks } : { type: "text", text }
 
+const addMark = (marks: ReadonlyArray<AdfNode> | undefined, mark: AdfNode): ReadonlyArray<AdfNode> =>
+  marks && marks.length > 0 ? [...marks, mark] : [mark]
+
 // Code-marked text is a *quotation* of placeholder syntax, not a placeholder
 // (the walker never emits placeholders with a code mark) — expanding it would
 // corrupt documentation that demonstrates the syntax.
@@ -65,16 +112,18 @@ const fromBase64 = (b64: string): string => {
 }
 
 // JSON string → free-form attrs record; rejects null/arrays/primitives.
-const AttrsBlob = Schema.parseJson(Schema.Record({ key: Schema.String, value: Schema.Unknown }))
-const decodeAttrsBlob = Schema.decodeUnknownEither(AttrsBlob)
+const AttrsBlob = Schema.Record(Schema.String, Schema.Unknown)
+const decodeAttrsBlob = Schema.decodeUnknownOption(AttrsBlob)
 
 const decodeAttrs = (b64: string | undefined): Record<string, unknown> | null => {
   if (!b64) return null
   try {
-    const decoded = decodeAttrsBlob(fromBase64(b64))
-    return Either.isRight(decoded) ? decoded.right : null
+    const raw = b64.trim()
+    const parsed = JSON.parse(raw.startsWith("{") ? raw : fromBase64(raw)) as unknown
+    const decoded = decodeAttrsBlob(parsed)
+    return Option.isSome(decoded) ? decoded.value : null
   } catch {
-    // Invalid base64 (hand-edited file?) — fall back to the readable key/type.
+    // Invalid JSON/base64 (hand-edited file?) — fall back to the readable key/type.
     return null
   }
 }
@@ -92,6 +141,43 @@ const buildExtensionAttrs = (
   return attrs
 }
 
+const buildPanelAttrs = (type: string | undefined, attrsB64: string | undefined): Record<string, unknown> => {
+  const decoded = decodeAttrs(attrsB64)
+  if (decoded) return decoded
+  return type ? { panelType: type } : {}
+}
+
+const buildInlineCardAttrs = (attrsB64: string | undefined): Record<string, unknown> => decodeAttrs(attrsB64) ?? {}
+
+const decodeMarks = (b64: string | undefined): ReadonlyArray<AdfNode> => {
+  if (!b64) return []
+  try {
+    const raw = b64.trim()
+    const parsed = JSON.parse(raw.startsWith("[") ? raw : fromBase64(raw)) as unknown
+    return Array.isArray(parsed)
+      ? parsed.filter((mark): mark is AdfNode =>
+        mark !== null && typeof mark === "object" && typeof (mark as Record<string, unknown>)["type"] === "string"
+      )
+      : []
+  } catch {
+    return []
+  }
+}
+
+const decodeNode = (b64: string | undefined): AdfNode | null => {
+  if (!b64) return null
+  try {
+    const raw = b64.trim()
+    const parsed = JSON.parse(raw.startsWith("{") ? raw : fromBase64(raw)) as unknown
+    return parsed !== null && typeof parsed === "object" &&
+        typeof (parsed as Record<string, unknown>)["type"] === "string"
+      ? parsed as AdfNode
+      : null
+  } catch {
+    return null
+  }
+}
+
 /** Split a text node into a sequence of text + status + inlineExtension nodes. */
 const expandInlineText = (
   text: string,
@@ -107,11 +193,30 @@ const expandInlineText = (
     if (match.index > lastIndex) {
       out.push(textNode(text.slice(lastIndex, match.index), marks))
     }
-    // Status capture groups: 1=color, 2=text. InlineExtension: 3=key, 4=type, 5=attrs.
+    // Capture groups follow COMBINED_INLINE_RE order.
+    // InlineNode: 1=type, 2=node. Status: 3=color, 4=text.
+    // InlineCard: 5=attrs. InlineExtension: 6=key, 7=type, 8=attrs.
+    // Underline: 9=text. Sub: 10=text. Sup: 11=text.
+    // Text color: 12=color, 13=text. Background color: 14=color, 15=text.
     if (match[1] !== undefined) {
-      out.push({ type: "status", attrs: { text: match[2] ?? "", color: match[1] } })
+      const decoded = decodeNode(match[2])
+      if (decoded && decoded.type === match[1]) out.push(decoded)
+    } else if (match[3] !== undefined) {
+      out.push({ type: "status", attrs: { text: match[4] ?? "", color: match[3] } })
+    } else if (match[5] !== undefined) {
+      out.push({ type: "inlineCard", attrs: buildInlineCardAttrs(match[5]) })
+    } else if (match[9] !== undefined) {
+      out.push(textNode(match[9], addMark(marks, { type: "underline" })))
+    } else if (match[10] !== undefined) {
+      out.push(textNode(match[10], addMark(marks, { type: "subsup", attrs: { type: "sub" } })))
+    } else if (match[11] !== undefined) {
+      out.push(textNode(match[11], addMark(marks, { type: "subsup", attrs: { type: "sup" } })))
+    } else if (match[12] !== undefined) {
+      out.push(textNode(match[13] ?? "", addMark(marks, { type: "textColor", attrs: { color: match[12] } })))
+    } else if (match[14] !== undefined) {
+      out.push(textNode(match[15] ?? "", addMark(marks, { type: "backgroundColor", attrs: { color: match[14] } })))
     } else {
-      out.push({ type: "inlineExtension", attrs: buildExtensionAttrs(match[3], match[4], match[5]) })
+      out.push({ type: "inlineExtension", attrs: buildExtensionAttrs(match[6], match[7], match[8]) })
     }
     lastIndex = match.index + match[0].length
   }
@@ -173,11 +278,96 @@ const parseBlockExtensionParagraph = (node: AdfNode): BlockExtensionMarker | nul
   }
 }
 
+const parseTocParagraph = (node: AdfNode): AdfNode | null => {
+  const child = soleTextChild(node)
+  if (!child || !child.text) return null
+  const match = TOC_RE.exec(child.text)
+  if (!match) return null
+
+  let minLevel: string | undefined
+  let maxLevel: string | undefined
+  const params = match[1]?.trim()
+
+  if (params && params.length > 0) {
+    const seen = new Set<string>()
+    for (const part of params.split(",")) {
+      const [rawKey, rawValue, ...rest] = part.split("=")
+      if (rest.length > 0) return null
+      const key = rawKey?.trim()
+      const value = rawValue?.trim()
+      if ((key !== "min" && key !== "max") || !value || !/^[1-6]$/.test(value) || seen.has(key)) return null
+      seen.add(key)
+      if (key === "min") minLevel = value
+      else maxLevel = value
+    }
+  } else if (params !== undefined) {
+    return null
+  }
+
+  const macroParams: Record<string, { readonly value: string }> = {}
+  if (minLevel) macroParams.minLevel = { value: minLevel }
+  if (maxLevel) macroParams.maxLevel = { value: maxLevel }
+
+  const attrs: Record<string, unknown> = {
+    extensionKey: "toc",
+    extensionType: CONFLUENCE_CORE_MACRO_TYPE
+  }
+  if (Object.keys(macroParams).length > 0) {
+    attrs.parameters = { macroParams }
+  }
+
+  return { type: "extension", attrs }
+}
+
 const isBodiedExtensionEnd = (node: AdfNode): boolean => {
   const child = soleTextChild(node)
   return child !== null && typeof child.text === "string" && BODIED_EXTENSION_END_RE.test(child.text)
 }
 
+const parsePanelParagraph = (node: AdfNode): Record<string, unknown> | null => {
+  const child = soleTextChild(node)
+  if (!child || !child.text) return null
+  const match = PANEL_RE.exec(child.text)
+  if (!match) return null
+  const [, type, attrsB64] = match
+  return buildPanelAttrs(type, attrsB64)
+}
+
+const isPanelEnd = (node: AdfNode): boolean => {
+  const child = soleTextChild(node)
+  return child !== null && typeof child.text === "string" && PANEL_END_RE.test(child.text)
+}
+
+const parseEncodedBlockNodeParagraph = (node: AdfNode): { readonly type: string; readonly node: AdfNode } | null => {
+  const child = soleTextChild(node)
+  if (!child || !child.text) return null
+  const match = ENCODED_BLOCK_NODE_RE.exec(child.text)
+  if (!match) return null
+  const decoded = decodeNode(match[2])
+  if (!decoded || decoded.type !== match[1]) return null
+  return { type: match[1]!, node: decoded }
+}
+
+const isEncodedBlockNodeEnd = (node: AdfNode, type: string): boolean => {
+  const child = soleTextChild(node)
+  if (child === null || typeof child.text !== "string") return false
+  const match = ENCODED_BLOCK_NODE_END_RE.exec(child.text)
+  return match?.[1] === type
+}
+
+const parseParagraphMarksParagraph = (node: AdfNode): ReadonlyArray<AdfNode> | null => {
+  const child = soleTextChild(node)
+  if (!child || !child.text) return null
+  const match = PARAGRAPH_MARKS_RE.exec(child.text)
+  if (!match) return null
+  return decodeMarks(match[1])
+}
+
+const isParagraphMarksEnd = (node: AdfNode): boolean => {
+  const child = soleTextChild(node)
+  return child !== null && typeof child.text === "string" && PARAGRAPH_MARKS_END_RE.test(child.text)
+}
+
 /**
  * Replace block-extension marker paragraphs among `children`. A bare
  * `extension` marker becomes an extension node; a `bodiedExtension` marker
@@ -237,6 +427,110 @@ const groupBlockExtensions = (children: ReadonlyArray<AdfNode>, parentType: stri
   return out
 }
 
+const groupPanels = (children: ReadonlyArray<AdfNode>): ReadonlyArray<AdfNode> => {
+  const out: Array<AdfNode> = []
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    if (!child) continue
+    const attrs = parsePanelParagraph(child)
+    if (!attrs) {
+      if (!isPanelEnd(child)) out.push(child)
+      continue
+    }
+
+    let end = -1
+    for (let j = i + 1; j < children.length; j++) {
+      if (isPanelEnd(children[j]!)) {
+        end = j
+        break
+      }
+      if (parsePanelParagraph(children[j]!)) break
+    }
+
+    if (end === -1) {
+      out.push({ type: "panel", attrs, content: [{ type: "paragraph", content: [] }] })
+      continue
+    }
+
+    const body = groupPanels(children.slice(i + 1, end))
+    out.push({
+      type: "panel",
+      attrs,
+      content: body.length > 0 ? body : [{ type: "paragraph", content: [] }]
+    })
+    i = end
+  }
+  return out
+}
+
+const groupEncodedBlockNodes = (children: ReadonlyArray<AdfNode>): ReadonlyArray<AdfNode> => {
+  const out: Array<AdfNode> = []
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    if (!child) continue
+    const marker = parseEncodedBlockNodeParagraph(child)
+    if (!marker) {
+      out.push(child)
+      continue
+    }
+
+    let end = -1
+    for (let j = i + 1; j < children.length; j++) {
+      if (isEncodedBlockNodeEnd(children[j]!, marker.type)) {
+        end = j
+        break
+      }
+      if (parseEncodedBlockNodeParagraph(children[j]!) !== null) break
+    }
+
+    out.push(marker.node)
+    if (end !== -1) i = end
+  }
+  return out
+}
+
+const groupMarkedParagraphs = (children: ReadonlyArray<AdfNode>): ReadonlyArray<AdfNode> => {
+  const out: Array<AdfNode> = []
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    if (!child) continue
+    const marks = parseParagraphMarksParagraph(child)
+    if (!marks) {
+      if (!isParagraphMarksEnd(child)) out.push(child)
+      continue
+    }
+
+    let end = -1
+    for (let j = i + 1; j < children.length; j++) {
+      if (isParagraphMarksEnd(children[j]!)) {
+        end = j
+        break
+      }
+      if (parseParagraphMarksParagraph(children[j]!) !== null) break
+    }
+
+    if (end === -1) {
+      out.push({ type: "paragraph", marks, content: [] })
+      continue
+    }
+
+    const body = children.slice(i + 1, end)
+    const first = body[0]
+    if (first?.type === "paragraph") {
+      out.push(marks.length > 0 ? { ...first, marks } : first)
+      for (const rest of body.slice(1)) out.push(rest)
+    } else {
+      out.push({ type: "paragraph", marks, content: [] })
+      for (const rest of body) out.push(rest)
+    }
+    i = end
+  }
+  return out
+}
+
+const groupNativeMacros = (children: ReadonlyArray<AdfNode>): ReadonlyArray<AdfNode> =>
+  children.map((child) => parseTocParagraph(child) ?? child)
+
 const transform = (node: AdfNode): AdfNode => {
   // ADF codeBlock permits only plain text children — expanding placeholder-
   // looking text inside one would inject schema-invalid nodes and corrupt
@@ -259,7 +553,10 @@ const transform = (node: AdfNode): AdfNode => {
       newContent.push(transform(child))
     }
   }
-  return { ...node, content: groupBlockExtensions(newContent, node.type) }
+  const nativeMacrosRestored = groupNativeMacros(newContent)
+  const paragraphsRestored = groupMarkedParagraphs(nativeMacrosRestored)
+  const encodedBlocksRestored = groupEncodedBlockNodes(paragraphsRestored)
+  return { ...node, content: groupPanels(groupBlockExtensions(encodedBlocksRestored, node.type)) }
 }
 
 /** Walk the document tree and rewrite placeholder text into proper ADF nodes. */

package/src/AdfSchemaValidator.ts

@@ -27,9 +27,7 @@ const validate = ajv.compile(adfJsonSchema as object)
  *
  * @category Service
  */
-export class AdfSchemaValidator extends Context.Tag(
-  "@knpkv/confluence-to-markdown/AdfSchemaValidator"
-)<
+export class AdfSchemaValidator extends Context.Service<
   AdfSchemaValidator,
   {
     readonly check: (
@@ -37,7 +35,7 @@ export class AdfSchemaValidator extends Context.Tag(
       direction: "incoming" | "outgoing"
     ) => Effect.Effect<DocNode, AdfSchemaError>
   }
->() {}
+>()("@knpkv/confluence-to-markdown/AdfSchemaValidator") {}
 
 /**
  * Live Layer for `AdfSchemaValidator`. The Ajv validator is compiled once at

package/src/AdfWalker.ts

@@ -93,31 +93,17 @@ const attrNum = (n: AdfNode, key: string): number | undefined => {
   const v = n.attrs?.[key]
   return typeof v === "number" ? v : undefined
 }
+const attrRecord = (n: AdfNode, key: string): Record<string, unknown> | undefined => {
+  const v = n.attrs?.[key]
+  return v !== null && typeof v === "object" && !Array.isArray(v) ? v as Record<string, unknown> : undefined
+}
 
-// Color-matched to GitHub's admonition palette: info/blue→NOTE, note/purple→
-// IMPORTANT, success/green→TIP, warning/yellow→WARNING, error/red→CAUTION.
-const PANEL_MAP: Record<string, string> = {
-  info: "NOTE",
-  note: "IMPORTANT",
-  warning: "WARNING",
-  success: "TIP",
-  error: "CAUTION"
-}
-
-// btoa operates on byte strings; route through TextEncoder so non-ASCII attrs
-// survive. Web APIs only — this module is a standalone subpath export and
-// must not assume Node (same reasoning as internal/hashUtils' Web Crypto).
-const toBase64 = (s: string): string => {
-  const bytes = new TextEncoder().encode(s)
-  let bin = ""
-  for (const b of bytes) bin += String.fromCharCode(b)
-  return btoa(bin)
-}
-
-// Deterministic JSON for the placeholder attrs blob: object keys are sorted
-// recursively so the same attrs always produce the same base64, no matter
-// what order Confluence happens to serialize them in. Keeps pull → push →
-// pull a byte-level fixed point (and contentHash stable).
+const CONFLUENCE_CORE_MACRO_TYPE = "com.atlassian.confluence.macro.core"
+
+// Deterministic JSON for placeholder metadata: object keys are sorted
+// recursively so the same attrs always produce the same marker/sidecar data,
+// no matter what order Confluence happens to serialize them in. Keeps pull →
+// push → pull a byte-level fixed point (and contentHash stable).
 const stableStringify = (v: unknown): string => {
   if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`
   if (v !== null && typeof v === "object") {
@@ -163,24 +149,21 @@ const inlineNode = (n: AdfNode, ctx: Ctx): string => {
       return id ? `[${display}](confluence-mention://${encodeURIComponent(id)})` : display
     }
     case "emoji": {
-      const short = attrStr(n, "shortName")
-      return short ? `:${short}:` : (attrStr(n, "text") ?? "")
+      return `<!-- adf:${n.type} node=${stableStringify(n)} -->`
     }
     case "inlineCard": {
-      const url = attrStr(n, "url")
+      const url = cardUrl(n)
       if (!url) {
         // data-payload smart links have no URL to render — losing one must
         // at least be visible in the logs.
         ctx.warnings.push({ _tag: "UnsupportedNode", nodeType: "inlineCard" })
         return ""
       }
-      return `<${url}>`
+      const attrs = n.attrs ?? { url }
+      return `<!-- adf:inlineCard attrs=${stableStringify(attrs)} -->`
     }
     case "date": {
-      const ts = attrStr(n, "timestamp")
-      if (!ts) return ""
-      const d = new Date(Number(ts))
-      return Number.isNaN(d.getTime()) ? ts : d.toISOString().slice(0, 10)
+      return `<!-- adf:${n.type} node=${stableStringify(n)} -->`
     }
     case "status": {
       const text = attrStr(n, "text") ?? ""
@@ -215,11 +198,55 @@ const extensionPlaceholder = (
   // so macros survive a pull → push round-trip with their configuration.
   const attrs = n.attrs ?? {}
   const attrsPart = Object.keys(attrs).length > 0
-    ? ` attrs=${toBase64(stableStringify(attrs))}`
+    ? ` attrs=${stableStringify(attrs)}`
     : ""
   return `<!-- adf:${nodeType}${keyPart}${typePart}${attrsPart} -->`
 }
 
+const objectKeys = (v: Record<string, unknown> | undefined): ReadonlyArray<string> => Object.keys(v ?? {})
+const isOnlyKeys = (v: Record<string, unknown> | undefined, keys: ReadonlyArray<string>): boolean => {
+  const allowed = new Set(keys)
+  return objectKeys(v).every((key) => allowed.has(key))
+}
+
+const tocLevel = (macroParams: Record<string, unknown> | undefined, key: "minLevel" | "maxLevel"): string | null => {
+  const param = macroParams?.[key]
+  if (param === undefined) return null
+  if (param === null || typeof param !== "object" || Array.isArray(param)) return null
+  const record = param as Record<string, unknown>
+  if (!isOnlyKeys(record, ["value"])) return null
+  const value = record["value"]
+  return typeof value === "string" && /^[1-6]$/.test(value) ? value : null
+}
+
+const tocMarkdown = (n: AdfNode): string | null => {
+  const attrs = n.attrs
+  if (!attrs) return null
+  if (attrStr(n, "extensionKey") !== "toc" || attrStr(n, "extensionType") !== CONFLUENCE_CORE_MACRO_TYPE) return null
+  if (!isOnlyKeys(attrs, ["extensionKey", "extensionType", "parameters"])) return null
+
+  const parameters = attrRecord(n, "parameters")
+  if (!parameters) return "[[toc]]"
+  if (!isOnlyKeys(parameters, ["macroParams"])) return null
+
+  const macroParams = parameters["macroParams"]
+  if (macroParams === null || typeof macroParams !== "object" || Array.isArray(macroParams)) return null
+  const macroParamRecord = macroParams as Record<string, unknown>
+  if (!isOnlyKeys(macroParamRecord, ["minLevel", "maxLevel"])) return null
+
+  const minLevel = tocLevel(macroParamRecord, "minLevel")
+  const maxLevel = tocLevel(macroParamRecord, "maxLevel")
+  if (macroParamRecord["minLevel"] !== undefined && minLevel === null) return null
+  if (macroParamRecord["maxLevel"] !== undefined && maxLevel === null) return null
+
+  const parts = [
+    minLevel ? `min=${minLevel}` : "",
+    maxLevel ? `max=${maxLevel}` : ""
+  ].filter((part) => part.length > 0)
+
+  return parts.length > 0 ? `[[toc:${parts.join(",")}]]` : "[[toc]]"
+}
+
 const bodiedExtension = (n: AdfNode, ctx: Ctx): string => {
   const open = extensionPlaceholder(n, "bodiedExtension", ctx)
   // Table cells flatten newlines to <br>, which would weld the markers and
@@ -299,7 +326,7 @@ const indentLines = (s: string, indent: string): string =>
 const block = (n: AdfNode, ctx: Ctx): string => {
   switch (n.type) {
     case "paragraph":
-      return escapeLineStarts(inline(n.content, ctx))
+      return paragraph(n, ctx)
     case "heading": {
       const level = Math.min(6, Math.max(1, attrNum(n, "level") ?? 1))
       return "#".repeat(level) + " " + inline(n.content, ctx)
@@ -325,12 +352,19 @@ const block = (n: AdfNode, ctx: Ctx): string => {
       return taskList(n, ctx)
     case "decisionList":
       return decisionList(n, ctx)
+    case "layoutSection":
+      return layoutSection(n, ctx)
+    case "layoutColumn":
+      return layoutColumn(n, ctx)
     case "mediaSingle":
       return mediaSingle(n, ctx)
     case "mediaGroup":
       return mediaGroup(n, ctx)
+    case "blockCard":
+    case "embedCard":
+      return blockCard(n, ctx)
     case "extension":
-      return extensionPlaceholder(n, "extension", ctx)
+      return tocMarkdown(n) ?? extensionPlaceholder(n, "extension", ctx)
     case "bodiedExtension":
       return bodiedExtension(n, ctx)
     default:
@@ -339,6 +373,14 @@ const block = (n: AdfNode, ctx: Ctx): string => {
   }
 }
 
+const paragraph = (n: AdfNode, ctx: Ctx): string => {
+  const body = escapeLineStarts(inline(n.content, ctx))
+  const marks = n.marks ?? []
+  if (marks.length === 0 || ctx.inTable) return body
+  const marksPart = ` marks=${stableStringify(marks)}`
+  return `<!-- adf:paragraph${marksPart} -->\n\n${body}\n\n<!-- adf:/paragraph -->`
+}
+
 const blockquote = (content: ReadonlyArray<AdfNode> | undefined, ctx: Ctx): string => {
   const inner = (content ?? []).map((c) => block(c, ctx)).join("\n\n")
   return inner.split("\n").map((l) => (l.length === 0 ? ">" : `> ${l}`)).join("\n")
@@ -423,15 +465,25 @@ const table = (n: AdfNode, ctx: Ctx): string => {
   const separator = Array<string>(colCount).fill("---")
   const bodyRows = (firstIsHeader ? allRows.slice(1) : allRows).map(pad)
   const fmt = (cells: Array<string>): string => `| ${cells.join(" | ")} |`
-  return [fmt(header), fmt(separator), ...bodyRows.map(fmt)].join("\n")
+  return encodedBlockNode(n, [fmt(header), fmt(separator), ...bodyRows.map(fmt)].join("\n"), ctx)
 }
 
 const panel = (n: AdfNode, ctx: Ctx): string => {
   const panelType = attrStr(n, "panelType") ?? "info"
-  const tag = PANEL_MAP[panelType] ?? "NOTE"
+  const attrs = n.attrs ?? { panelType }
+  const attrsPart = Object.keys(attrs).length > 0 ? ` attrs=${stableStringify(attrs)}` : ""
+  const open = `<!-- adf:panel type=${panelType}${attrsPart} -->`
+  if (ctx.inTable) return open
   const inner = (n.content ?? []).map((c) => block(c, ctx)).join("\n\n")
-  const lines = [`[!${tag}]`, ...inner.split("\n")]
-  return lines.map((l) => (l.length === 0 ? ">" : `> ${l}`)).join("\n")
+  const parts = inner.length > 0 ? [open, inner] : [open]
+  return [...parts, "<!-- adf:/panel -->"].join("\n\n")
+}
+
+const encodedBlockNode = (n: AdfNode, body: string, ctx: Ctx): string => {
+  if (ctx.inTable) return body
+  const open = `<!-- adf:${n.type} node=${stableStringify(n)} -->`
+  const parts = body.length > 0 ? [open, body] : [open]
+  return [...parts, `<!-- adf:/${n.type} -->`].join("\n\n")
 }
 
 const expand = (n: AdfNode, ctx: Ctx): string => {
@@ -442,7 +494,8 @@ const expand = (n: AdfNode, ctx: Ctx): string => {
   // backslash escapes are the correct (and only working) form.
   const safeTitle = ctx.inTable ? escapeText(title) : escapeHtml(title)
   const inner = (n.content ?? []).map((c) => block(c, ctx)).join("\n\n")
-  return `<details><summary>${safeTitle}</summary>\n\n${inner}\n\n</details>`
+  if (ctx.inTable) return `<details><summary>${safeTitle}</summary>\n\n${inner}\n\n</details>`
+  return encodedBlockNode(n, `${title}\n\n${inner}`, ctx)
 }
 
 const taskList = (n: AdfNode, ctx: Ctx): string => {
@@ -457,7 +510,7 @@ const taskList = (n: AdfNode, ctx: Ctx): string => {
     const text = inline(item.content, ctx)
     lines.push(`- [${checked}] ${text}`)
   }
-  return lines.join("\n")
+  return encodedBlockNode(n, lines.join("\n"), ctx)
 }
 
 const decisionList = (n: AdfNode, ctx: Ctx): string => {
@@ -470,7 +523,34 @@ const decisionList = (n: AdfNode, ctx: Ctx): string => {
     }
     lines.push(`- 🔘 ${inline(item.content, ctx)}`)
   }
-  return lines.join("\n")
+  return encodedBlockNode(n, lines.join("\n"), ctx)
+}
+
+const layoutSection = (n: AdfNode, ctx: Ctx): string => {
+  const body = (n.content ?? [])
+    .map((column) => block(column, ctx))
+    .filter((part) => part.trim().length > 0)
+    .join("\n\n")
+  return encodedBlockNode(n, body, ctx)
+}
+
+const layoutColumn = (n: AdfNode, ctx: Ctx): string => (n.content ?? []).map((child) => block(child, ctx)).join("\n\n")
+
+const cardUrl = (n: AdfNode): string | undefined => {
+  const url = attrStr(n, "url")
+  if (url) return url
+  const data = attrRecord(n, "data")
+  const dataUrl = data?.["url"]
+  return typeof dataUrl === "string" ? dataUrl : undefined
+}
+
+const blockCard = (n: AdfNode, ctx: Ctx): string => {
+  const url = cardUrl(n)
+  if (!url) {
+    ctx.warnings.push({ _tag: "UnsupportedNode", nodeType: n.type })
+    return `<!-- unsupported ADF node: ${n.type} -->`
+  }
+  return encodedBlockNode(n, `<${url}>`, ctx)
 }
 
 const renderMedia = (media: AdfNode | undefined, ctx: Ctx): string => {