From da706cd13a29a97c8551166153add5244f39fb39 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Thu, 26 Feb 2026 18:12:12 +0100
Subject: [PATCH 01/38] Initial work on extended asciidoc

This commit adds CLI flags and propagation of XAD options.
---
 .../Sources/AsciiDocCore/XADOptions.swift     |  23 ++
 Sources/AsciiDocCore/ISM.swift                |   5 +-
 Sources/AsciiDocCore/Parser.swift             |   5 +-
 Sources/AsciiDocCore/XADOptions.swift         |  23 ++
 Sources/AsciiDocRender/DocumentRender.swift   |  13 +-
 Sources/AsciiDocRender/FootnoteResolver.swift |   3 +-
 Sources/asciidoc-swift/Commands.swift         | 206 +++++++++++++++++-
 .../asciidoc-swift.docc/asciidoc-swift.md     |  61 ++++++
 8 files changed, 326 insertions(+), 13 deletions(-)
 create mode 100644 .swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADOptions.swift
 create mode 100644 Sources/AsciiDocCore/XADOptions.swift

diff --git a/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADOptions.swift b/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADOptions.swift
new file mode 100644
index 0000000..9343084
--- /dev/null
+++ b/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADOptions.swift
@@ -0,0 +1,23 @@
+//
+// Copyright (c) 2026 Mattias Holm
+// SPDX-License-Identifier: Apache-2.0
+//
+
+public struct XADOptions: Sendable, Equatable {
+    public var enabled: Bool
+    public var strict: Bool
+    public var pagedJS: Bool
+    public var templatePath: String?
+
+    public init(
+        enabled: Bool = false,
+        strict: Bool = false,
+        pagedJS: Bool = false,
+        templatePath: String? = nil
+    ) {
+        self.enabled = enabled
+        self.strict = strict
+        self.pagedJS = pagedJS
+        self.templatePath = templatePath
+    }
+}
diff --git a/Sources/AsciiDocCore/ISM.swift b/Sources/AsciiDocCore/ISM.swift
index 616fbd9..fe7ec25 100644
--- a/Sources/AsciiDocCore/ISM.swift
+++ b/Sources/AsciiDocCore/ISM.swift
@@ -402,17 +402,20 @@ public struct AdocDocument: Sendable, Equatable {
     public var header: AdocHeader? = nil
     public var blocks: [AdocBlock] = []
     public var span: AdocRange?
+    public var xadOptions: XADOptions = .init()
 
     public init(
         attributes: [String: String?] = [:],
         header: AdocHeader? = nil,
         blocks: [AdocBlock] = [],
-        span: AdocRange? = nil
+        span: AdocRange? = nil,
+        xadOptions: XADOptions = .init()
     ) {
         self.attributes = attributes
         self.header = header
         self.blocks = blocks
         self.span = span
+        self.xadOptions = xadOptions
     }
 }
 
diff --git a/Sources/AsciiDocCore/Parser.swift b/Sources/AsciiDocCore/Parser.swift
index b06409a..e965fc7 100644
--- a/Sources/AsciiDocCore/Parser.swift
+++ b/Sources/AsciiDocCore/Parser.swift
@@ -232,7 +232,8 @@ public struct AdocParser: Sendable {
         attributes initialAttributes: [String: String?] = [:],
         lockedAttributeNames: Set<String> = [],
         includeHeaderDerivedAttributes: Bool = true,
-        preprocessorOptions: Preprocessor.Options = .init()
+        preprocessorOptions: Preprocessor.Options = .init(),
+        xadOptions: XADOptions = .init()
     ) -> AdocDocument {
         let preprocessor = Preprocessor(options: preprocessorOptions)
         let preprocessed = preprocessor.process(
@@ -266,7 +267,7 @@ public struct AdocParser: Sendable {
             return AdocRange(start: first.range.start, end: last.range.end)
         }()
 
-        return AdocDocument(attributes: docAttrs, header: header, blocks: bodyBlocks, span: docSpan)
+        return AdocDocument(attributes: docAttrs, header: header, blocks: bodyBlocks, span: docSpan, xadOptions: xadOptions)
     }
 
 
diff --git a/Sources/AsciiDocCore/XADOptions.swift b/Sources/AsciiDocCore/XADOptions.swift
new file mode 100644
index 0000000..9343084
--- /dev/null
+++ b/Sources/AsciiDocCore/XADOptions.swift
@@ -0,0 +1,23 @@
+//
+// Copyright (c) 2026 Mattias Holm
+// SPDX-License-Identifier: Apache-2.0
+//
+
+public struct XADOptions: Sendable, Equatable {
+    public var enabled: Bool
+    public var strict: Bool
+    public var pagedJS: Bool
+    public var templatePath: String?
+
+    public init(
+        enabled: Bool = false,
+        strict: Bool = false,
+        pagedJS: Bool = false,
+        templatePath: String? = nil
+    ) {
+        self.enabled = enabled
+        self.strict = strict
+        self.pagedJS = pagedJS
+        self.templatePath = templatePath
+    }
+}
diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index 2bb4e67..6cc3345 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -12,18 +12,21 @@ public struct RenderConfig {
     public var xrefResolver: XrefResolver?
     public var navigationTree: [String: Any]?
     public var customTemplateName: String?
+    public var xadOptions: XADOptions
 
     public init(
         backend: Backend,
         inlineBackend: AdocInlineBackend? = nil,
         xrefResolver: XrefResolver? = nil,
         navigationTree: [String: Any]? = nil,
-        customTemplateName: String? = nil
+        customTemplateName: String? = nil,
+        xadOptions: XADOptions = .init()
     ) {
         self.backend = backend
         self.xrefResolver = xrefResolver
         self.navigationTree = navigationTree
         self.customTemplateName = customTemplateName
+        self.xadOptions = xadOptions
         self.inlineBackend = inlineBackend ?? {
             switch backend {
             case .html5:    return .html5
@@ -93,7 +96,13 @@ public final class DocumentRenderer {
             "headerTitle": docToRender.header?.title?.plain ?? "",
             "blocks": blocks,
             "footnotes": footnotes.map { renderFootnoteDefinition($0, context: inlineContext) },
-            "indexCatalog": indexEntries
+            "indexCatalog": indexEntries,
+            "xad": [
+                "enabled": config.xadOptions.enabled,
+                "strict": config.xadOptions.strict,
+                "pagedJS": config.xadOptions.pagedJS,
+                "templatePath": config.xadOptions.templatePath ?? ""
+            ]
         ]
         
         if let nav = config.navigationTree {
diff --git a/Sources/AsciiDocRender/FootnoteResolver.swift b/Sources/AsciiDocRender/FootnoteResolver.swift
index 3e379e9..8a58fd8 100644
--- a/Sources/AsciiDocRender/FootnoteResolver.swift
+++ b/Sources/AsciiDocRender/FootnoteResolver.swift
@@ -36,7 +36,8 @@ public final class FootnoteResolver {
             attributes: document.attributes,
             header: document.header,
             blocks: newBlocks,
-            span: document.span
+            span: document.span,
+            xadOptions: document.xadOptions
         )
         
         return FootnoteResolution(document: newDoc, definitions: collected)
diff --git a/Sources/asciidoc-swift/Commands.swift b/Sources/asciidoc-swift/Commands.swift
index 7044d09..0b33555 100644
--- a/Sources/asciidoc-swift/Commands.swift
+++ b/Sources/asciidoc-swift/Commands.swift
@@ -53,7 +53,7 @@ struct AsciiDocSwift: AsyncParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "asciidoc-swift",
     abstract: "Swift AsciiDoc implementation with a JSON adapter for the Eclipse TCK.",
-    subcommands: [JSONAdapter.self, HTML.self, DocBook.self, Latex.self, Lint.self, Antora.self]
+    subcommands: [JSONAdapter.self, HTML.self, XadHtml.self, XadPagedHtml.self, DocBook.self, Latex.self, Lint.self, Antora.self]
   )
 }
 
@@ -179,6 +179,18 @@ struct HTML: AsyncParsableCommand {
     @Option(help: "Path to the Stencil templates root directory.")
     var template: String = "Templates"
 
+    @Flag(name: .long, help: "Enable XAD mode.")
+    var xad: Bool = false
+
+    @Flag(name: .long, help: "Enable strict XAD parsing.")
+    var xadStrict: Bool = false
+
+    @Flag(name: .long, help: "Enable Paged.js hooks (HTML only).")
+    var xadPagedJS: Bool = false
+
+    @Option(name: .long, help: "Path to XAD template (.adoc).")
+    var xadTemplate: String?
+
     @Option(
         name: [.customShort("a"), .customLong("attribute")],
         parsing: .unconditionalSingleValue,
@@ -200,6 +212,12 @@ struct HTML: AsyncParsableCommand {
     var extensions: [String] = []
 
     mutating func run() async throws {
+        let xadOptions = makeXadOptions(
+            enabled: xad,
+            pagedJS: xadPagedJS,
+            strict: xadStrict,
+            templatePath: xadTemplate
+        )
         try renderDocument(
             backend: .html5,
             defaultExtension: "html",
@@ -208,7 +226,126 @@ struct HTML: AsyncParsableCommand {
             templateRoot: template,
             attributeAssignments: attributeAssignments,
             outputPath: output,
-            enabledExtensions: extensions
+            enabledExtensions: extensions,
+            xadOptions: xadOptions
+        )
+    }
+}
+
+struct XadHtml: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "xad-html",
+        abstract: "Render AsciiDoc to HTML with XAD enabled."
+    )
+
+    @Flag(help: "Read source from stdin. Otherwise provide a path argument.")
+    var stdin: Bool = false
+
+    @Option(help: "Path to the Stencil templates root directory.")
+    var template: String = "Templates"
+
+    @Flag(name: .long, help: "Enable strict XAD parsing.")
+    var xadStrict: Bool = false
+
+    @Option(name: .long, help: "Path to XAD template (.adoc).")
+    var xadTemplate: String?
+
+    @Option(
+        name: [.customShort("a"), .customLong("attribute")],
+        parsing: .unconditionalSingleValue,
+        help: "Set document attribute (name[=value]). Repeatable."
+    )
+    var attributeAssignments: [String] = []
+
+    @Option(name: .shortAndLong, help: "Write rendered output to this path.")
+    var output: String?
+
+    @Argument(help: "Path to the .adoc document (omit when using --stdin).")
+    var inputPath: String?
+
+    @Option(
+        name: [.customShort("e"), .customLong("extension")],
+        parsing: .upToNextOption,
+        help: "Enable an extension by name (repeatable)."
+    )
+    var extensions: [String] = []
+
+    mutating func run() async throws {
+        let xadOptions = makeXadOptions(
+            enabled: true,
+            pagedJS: false,
+            strict: xadStrict,
+            templatePath: xadTemplate
+        )
+        try renderDocument(
+            backend: .html5,
+            defaultExtension: "html",
+            stdin: stdin,
+            inputPath: inputPath,
+            templateRoot: template,
+            attributeAssignments: attributeAssignments,
+            outputPath: output,
+            enabledExtensions: extensions,
+            xadOptions: xadOptions
+        )
+    }
+}
+
+struct XadPagedHtml: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "xad-paged-html",
+        abstract: "Render AsciiDoc to HTML with XAD + Paged.js enabled."
+    )
+
+    @Flag(help: "Read source from stdin. Otherwise provide a path argument.")
+    var stdin: Bool = false
+
+    @Option(help: "Path to the Stencil templates root directory.")
+    var template: String = "Templates"
+
+    @Flag(name: .long, help: "Enable strict XAD parsing.")
+    var xadStrict: Bool = false
+
+    @Option(name: .long, help: "Path to XAD template (.adoc).")
+    var xadTemplate: String?
+
+    @Option(
+        name: [.customShort("a"), .customLong("attribute")],
+        parsing: .unconditionalSingleValue,
+        help: "Set document attribute (name[=value]). Repeatable."
+    )
+    var attributeAssignments: [String] = []
+
+    @Option(name: .shortAndLong, help: "Write rendered output to this path.")
+    var output: String?
+
+    @Argument(help: "Path to the .adoc document (omit when using --stdin).")
+    var inputPath: String?
+
+    @Option(
+        name: [.customShort("e"), .customLong("extension")],
+        parsing: .upToNextOption,
+        help: "Enable an extension by name (repeatable)."
+    )
+    var extensions: [String] = []
+
+    mutating func run() async throws {
+        let xadOptions = makeXadOptions(
+            enabled: true,
+            pagedJS: true,
+            strict: xadStrict,
+            templatePath: xadTemplate
+        )
+        try renderDocument(
+            backend: .html5,
+            defaultExtension: "html",
+            stdin: stdin,
+            inputPath: inputPath,
+            templateRoot: template,
+            attributeAssignments: attributeAssignments,
+            outputPath: output,
+            enabledExtensions: extensions,
+            xadOptions: xadOptions
         )
     }
 }
@@ -225,6 +362,18 @@ struct DocBook: AsyncParsableCommand {
     @Option(help: "Path to the Stencil templates root directory.")
     var template: String = "Templates"
 
+    @Flag(name: .long, help: "Enable XAD mode.")
+    var xad: Bool = false
+
+    @Flag(name: .long, help: "Enable strict XAD parsing.")
+    var xadStrict: Bool = false
+
+    @Flag(name: .long, help: "Enable Paged.js hooks (HTML only).")
+    var xadPagedJS: Bool = false
+
+    @Option(name: .long, help: "Path to XAD template (.adoc).")
+    var xadTemplate: String?
+
     @Option(
         name: [.customShort("a"), .customLong("attribute")],
         parsing: .unconditionalSingleValue,
@@ -246,6 +395,12 @@ struct DocBook: AsyncParsableCommand {
     var extensions: [String] = []
 
     mutating func run() async throws {
+        let xadOptions = makeXadOptions(
+            enabled: xad,
+            pagedJS: xadPagedJS,
+            strict: xadStrict,
+            templatePath: xadTemplate
+        )
         try renderDocument(
             backend: .docbook5,
             defaultExtension: "xml",
@@ -254,7 +409,8 @@ struct DocBook: AsyncParsableCommand {
             templateRoot: template,
             attributeAssignments: attributeAssignments,
             outputPath: output,
-            enabledExtensions: extensions
+            enabledExtensions: extensions,
+            xadOptions: xadOptions
         )
     }
 }
@@ -271,6 +427,18 @@ struct Latex: AsyncParsableCommand {
     @Option(help: "Path to the Stencil templates root directory.")
     var template: String = "Templates"
 
+    @Flag(name: .long, help: "Enable XAD mode.")
+    var xad: Bool = false
+
+    @Flag(name: .long, help: "Enable strict XAD parsing.")
+    var xadStrict: Bool = false
+
+    @Flag(name: .long, help: "Enable Paged.js hooks (HTML only).")
+    var xadPagedJS: Bool = false
+
+    @Option(name: .long, help: "Path to XAD template (.adoc).")
+    var xadTemplate: String?
+
     @Option(
         name: [.customShort("a"), .customLong("attribute")],
         parsing: .unconditionalSingleValue,
@@ -292,6 +460,12 @@ struct Latex: AsyncParsableCommand {
     var extensions: [String] = []
 
     mutating func run() async throws {
+        let xadOptions = makeXadOptions(
+            enabled: xad,
+            pagedJS: xadPagedJS,
+            strict: xadStrict,
+            templatePath: xadTemplate
+        )
         try renderDocument(
             backend: .latex,
             defaultExtension: "tex",
@@ -300,7 +474,8 @@ struct Latex: AsyncParsableCommand {
             templateRoot: template,
             attributeAssignments: attributeAssignments,
             outputPath: output,
-            enabledExtensions: extensions
+            enabledExtensions: extensions,
+            xadOptions: xadOptions
         )
     }
 }
@@ -536,6 +711,21 @@ struct Antora: AsyncParsableCommand {
 // Rendering helpers
 extension PlantUMLExtension.Format: ExpressibleByArgument {}
 
+private func makeXadOptions(
+    enabled: Bool,
+    pagedJS: Bool,
+    strict: Bool,
+    templatePath: String?
+) -> XADOptions {
+    let shouldEnable = enabled || pagedJS || templatePath != nil
+    return XADOptions(
+        enabled: shouldEnable,
+        strict: strict,
+        pagedJS: pagedJS,
+        templatePath: templatePath
+    )
+}
+
 private func renderDocument(
     backend: Backend,
     defaultExtension: String,
@@ -544,7 +734,8 @@ private func renderDocument(
     templateRoot: String,
     attributeAssignments: [String],
     outputPath: String?,
-    enabledExtensions: [String]
+    enabledExtensions: [String],
+    xadOptions: XADOptions
 ) throws {
     let (source, sourcePath) = try readRenderSource(stdin: stdin, inputPath: inputPath)
     let documentDirectory = sourcePath.map { URL(fileURLWithPath: $0).deletingLastPathComponent() }
@@ -581,7 +772,8 @@ private func renderDocument(
         text: preprocessedSource,
         attributes: parserAttributes,
         lockedAttributeNames: seed.locked,
-        preprocessorOptions: preprocessorOptions
+        preprocessorOptions: preprocessorOptions,
+        xadOptions: xadOptions
     )
 
     doc = extensionHost.runDidParse(document: doc)
@@ -589,7 +781,7 @@ private func renderDocument(
     let engine = StencilTemplateEngine(templateRoot: templateRoot)
     let renderer = DocumentRenderer(
         engine: engine,
-        config: RenderConfig(backend: backend)
+        config: RenderConfig(backend: backend, xadOptions: xadOptions)
     )
     let rendered = try renderer.render(document: doc)
     try writeRenderedOutput(rendered, explicitPath: outputPath, sourcePath: sourcePath, defaultExtension: defaultExtension)
diff --git a/Sources/asciidoc-swift/asciidoc-swift.docc/asciidoc-swift.md b/Sources/asciidoc-swift/asciidoc-swift.docc/asciidoc-swift.md
index 790955c..cc1a464 100644
--- a/Sources/asciidoc-swift/asciidoc-swift.docc/asciidoc-swift.md
+++ b/Sources/asciidoc-swift/asciidoc-swift.docc/asciidoc-swift.md
@@ -53,6 +53,59 @@ asciidoc-swift html [--stdin] [--template <template>] [--attribute <attribute> .
 | `<input-path>` | Path to the `.adoc` document (omit when using `--stdin`). |
 | `--stdin` | Read source from stdin. Otherwise provide a path argument. |
 | `--template <template>` | Path to the Stencil templates root directory. (default: `Templates`) |
+| `--xad` | Enable XAD mode. |
+| `--xad-strict` | Enable strict XAD parsing. |
+| `--xad-paged-js` | Enable Paged.js hooks (HTML only). |
+| `--xad-template <xad-template>` | Path to XAD template (`.adoc`). |
+| `-a`, `--attribute <attribute>` | Set document attribute (`name[=value]`). Repeatable. |
+| `-o`, `--output <output>` | Write rendered output to this path. |
+| `-e`, `--extension <extension>` | Enable an extension by name (repeatable). |
+| `-h`, `--help` | Show help information. |
+
+#### `xad-html` subcommand
+
+The xad-html subcommand converts an AsciiDoc document to HTML5 with XAD enabled.
+
+##### Usage
+
+```bash
+asciidoc-swift xad-html [--stdin] [--template <template>] [--attribute <attribute> ...] [--output <output>] [<input-path>] [--extension <extension> ...]
+```
+
+##### Arguments and Options
+
+| Option | Description |
+| :--- | :--- |
+| `<input-path>` | Path to the `.adoc` document (omit when using `--stdin`). |
+| `--stdin` | Read source from stdin. Otherwise provide a path argument. |
+| `--template <template>` | Path to the Stencil templates root directory. (default: `Templates`) |
+| `--xad-strict` | Enable strict XAD parsing. |
+| `--xad-template <xad-template>` | Path to XAD template (`.adoc`). |
+| `-a`, `--attribute <attribute>` | Set document attribute (`name[=value]`). Repeatable. |
+| `-o`, `--output <output>` | Write rendered output to this path. |
+| `-e`, `--extension <extension>` | Enable an extension by name (repeatable). |
+| `-h`, `--help` | Show help information. |
+
+#### `xad-paged-html` subcommand
+
+The xad-paged-html subcommand converts an AsciiDoc document to HTML5 with XAD enabled
+and Paged.js hooks turned on.
+
+##### Usage
+
+```bash
+asciidoc-swift xad-paged-html [--stdin] [--template <template>] [--attribute <attribute> ...] [--output <output>] [<input-path>] [--extension <extension> ...]
+```
+
+##### Arguments and Options
+
+| Option | Description |
+| :--- | :--- |
+| `<input-path>` | Path to the `.adoc` document (omit when using `--stdin`). |
+| `--stdin` | Read source from stdin. Otherwise provide a path argument. |
+| `--template <template>` | Path to the Stencil templates root directory. (default: `Templates`) |
+| `--xad-strict` | Enable strict XAD parsing. |
+| `--xad-template <xad-template>` | Path to XAD template (`.adoc`). |
 | `-a`, `--attribute <attribute>` | Set document attribute (`name[=value]`). Repeatable. |
 | `-o`, `--output <output>` | Write rendered output to this path. |
 | `-e`, `--extension <extension>` | Enable an extension by name (repeatable). |
@@ -78,6 +131,10 @@ asciidoc-swift docbook [--stdin] [--template <template>] [--attribute <attribute
 | `<input-path>` | Path to the `.adoc` document (omit when using `--stdin`). |
 | `--stdin` | Read source from stdin. Otherwise provide a path argument. |
 | `--template <template>` | Path to the Stencil templates root directory. (default: `Templates`) |
+| `--xad` | Enable XAD mode. |
+| `--xad-strict` | Enable strict XAD parsing. |
+| `--xad-paged-js` | Enable Paged.js hooks (HTML only). |
+| `--xad-template <xad-template>` | Path to XAD template (`.adoc`). |
 | `-a`, `--attribute <attribute>` | Set document attribute (`name[=value]`). Repeatable. |
 | `-o`, `--output <output>` | Write rendered output to this path. |
 | `-e`, `--extension <extension>` | Enable an extension by name (repeatable). |
@@ -103,6 +160,10 @@ asciidoc-swift latex [--stdin] [--template <template>] [--attribute <attribute>
 | `<input-path>` | Path to the `.adoc` document (omit when using `--stdin`). |
 | `--stdin` | Read source from stdin. Otherwise provide a path argument. |
 | `--template <template>` | Path to the Stencil templates root directory. (default: `Templates`) |
+| `--xad` | Enable XAD mode. |
+| `--xad-strict` | Enable strict XAD parsing. |
+| `--xad-paged-js` | Enable Paged.js hooks (HTML only). |
+| `--xad-template <xad-template>` | Path to XAD template (`.adoc`). |
 | `-a`, `--attribute <attribute>` | Set document attribute (`name[=value]`). Repeatable. |
 | `-o`, `--output <output>` | Write rendered output to this path. |
 | `-e`, `--extension <extension>` | Enable an extension by name (repeatable). |

From 6a27cc5fe55b1e20f433e3849159cb34b3db093c Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Thu, 26 Feb 2026 18:30:33 +0100
Subject: [PATCH 02/38] Initial work on XAD attributes

---
 .../AsciiDocCore/XADAttributeValue.swift      | 89 +++++++++++++++++++
 .../TypedAttributesTests.swift                | 64 +++++++++++++
 Sources/AsciiDocCore/Attributes.swift         | 85 ++++++++++++++++++
 Sources/AsciiDocCore/ISM.swift                | 20 +++++
 Sources/AsciiDocCore/Parser+Header.swift      | 10 ++-
 Sources/AsciiDocCore/Parser.swift             | 14 ++-
 Sources/AsciiDocRender/DocumentRender.swift   |  2 +
 Sources/AsciiDocRender/FootnoteResolver.swift |  1 +
 8 files changed, 282 insertions(+), 3 deletions(-)
 create mode 100644 .swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADAttributeValue.swift
 create mode 100644 .swiftpm/xcode/AsciiDoc-Swift/Tests/AsciiDocCoreTests/TypedAttributesTests.swift

diff --git a/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADAttributeValue.swift b/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADAttributeValue.swift
new file mode 100644
index 0000000..af6b209
--- /dev/null
+++ b/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADAttributeValue.swift
@@ -0,0 +1,89 @@
+//
+// Copyright (c) 2026 Mattias Holm
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+public enum XADAttributeValue: Sendable, Equatable {
+    case dictionary([String: XADAttributeValue])
+    case array([XADAttributeValue])
+    case string(String)
+    case number(Double)
+    case bool(Bool)
+    case null
+
+    static func parse(from raw: String, xadOptions: XADOptions) -> XADAttributeValue? {
+        guard xadOptions.enabled else { return nil }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let first = trimmed.first, first == "{" || first == "[" else { return nil }
+        guard let data = trimmed.data(using: .utf8) else { return nil }
+
+        var options: JSONSerialization.ReadingOptions = []
+        if #available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *) {
+            options.insert(.json5Allowed)
+        }
+
+        do {
+            let obj = try JSONSerialization.jsonObject(with: data, options: options)
+            return XADAttributeValue.fromJSON(obj)
+        } catch {
+            return nil
+        }
+    }
+
+    static func fromJSON(_ value: Any) -> XADAttributeValue? {
+        switch value {
+        case let dict as [String: Any]:
+            var mapped: [String: XADAttributeValue] = [:]
+            for (key, val) in dict {
+                if let converted = fromJSON(val) {
+                    mapped[key] = converted
+                } else {
+                    return nil
+                }
+            }
+            return .dictionary(mapped)
+        case let array as [Any]:
+            var mapped: [XADAttributeValue] = []
+            mapped.reserveCapacity(array.count)
+            for val in array {
+                guard let converted = fromJSON(val) else { return nil }
+                mapped.append(converted)
+            }
+            return .array(mapped)
+        case let str as String:
+            return .string(str)
+        case let num as NSNumber:
+            if CFGetTypeID(num) == CFBooleanGetTypeID() {
+                return .bool(num.boolValue)
+            }
+            return .number(num.doubleValue)
+        case _ as NSNull:
+            return .null
+        default:
+            return nil
+        }
+    }
+
+    func toJSONCompatible() -> Any {
+        switch self {
+        case .dictionary(let dict):
+            var out: [String: Any] = [:]
+            for (key, value) in dict {
+                out[key] = value.toJSONCompatible()
+            }
+            return out
+        case .array(let array):
+            return array.map { $0.toJSONCompatible() }
+        case .string(let value):
+            return value
+        case .number(let value):
+            return value
+        case .bool(let value):
+            return value
+        case .null:
+            return NSNull()
+        }
+    }
+}
diff --git a/.swiftpm/xcode/AsciiDoc-Swift/Tests/AsciiDocCoreTests/TypedAttributesTests.swift b/.swiftpm/xcode/AsciiDoc-Swift/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
new file mode 100644
index 0000000..dbcb032
--- /dev/null
+++ b/.swiftpm/xcode/AsciiDoc-Swift/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
@@ -0,0 +1,64 @@
+import Testing
+@testable import AsciiDocCore
+
+@Test func typedAttributesParseStandardJSON() {
+    let source = """
+    :page: {"size":"A4","margins":{"top":"24mm","right":"22mm"}}
+    :grid: {"columns":["2fr","1fr"],"gutter":"8mm"}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard let page = doc.typedAttributes["page"] else {
+        #expect(false, "Expected typed attribute 'page' to be parsed.")
+        return
+    }
+    if case .dictionary(let pageDict) = page {
+        #expect(pageDict["size"] == .string("A4"))
+        if case .dictionary(let margins)? = pageDict["margins"] {
+            #expect(margins["top"] == .string("24mm"))
+            #expect(margins["right"] == .string("22mm"))
+        } else {
+            #expect(false, "Expected margins to be a dictionary.")
+        }
+    } else {
+        #expect(false, "Expected 'page' to be a dictionary.")
+    }
+
+    if case .dictionary(let grid)? = doc.typedAttributes["grid"] {
+        if case .array(let cols)? = grid["columns"] {
+            #expect(cols.count == 2)
+            #expect(cols.first == .string("2fr"))
+            #expect(cols.last == .string("1fr"))
+        } else {
+            #expect(false, "Expected grid.columns to be an array.")
+        }
+    } else {
+        #expect(false, "Expected typed attribute 'grid' to be a dictionary.")
+    }
+}
+
+@Test func typedAttributesParseJSON5WhenAvailable() {
+    if #available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *) {
+        let source = """
+        :page: {size:"A4", margins:{top:"24mm"}}
+        """
+        let parser = AdocParser()
+        let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+        guard let page = doc.typedAttributes["page"] else {
+            #expect(false, "Expected typed attribute 'page' to be parsed with JSON5 syntax.")
+            return
+        }
+        if case .dictionary(let pageDict) = page {
+            #expect(pageDict["size"] == .string("A4"))
+            if case .dictionary(let margins)? = pageDict["margins"] {
+                #expect(margins["top"] == .string("24mm"))
+            } else {
+                #expect(false, "Expected margins to be a dictionary.")
+            }
+        } else {
+            #expect(false, "Expected 'page' to be a dictionary.")
+        }
+    }
+}
diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index 54ca967..82c8698 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -3,6 +3,91 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+import Foundation
+
+public enum XADAttributeValue: Sendable, Equatable {
+    case dictionary([String: XADAttributeValue])
+    case array([XADAttributeValue])
+    case string(String)
+    case number(Double)
+    case bool(Bool)
+    case null
+
+    static func parse(from raw: String, xadOptions: XADOptions) -> XADAttributeValue? {
+        guard xadOptions.enabled else { return nil }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let first = trimmed.first, first == "{" || first == "[" else { return nil }
+        guard let data = trimmed.data(using: .utf8) else { return nil }
+
+        var options: JSONSerialization.ReadingOptions = []
+        if #available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *) {
+            options.insert(.json5Allowed)
+        }
+
+        do {
+            let obj = try JSONSerialization.jsonObject(with: data, options: options)
+            return XADAttributeValue.fromJSON(obj)
+        } catch {
+            return nil
+        }
+    }
+
+    static func fromJSON(_ value: Any) -> XADAttributeValue? {
+        switch value {
+        case let dict as [String: Any]:
+            var mapped: [String: XADAttributeValue] = [:]
+            for (key, val) in dict {
+                if let converted = fromJSON(val) {
+                    mapped[key] = converted
+                } else {
+                    return nil
+                }
+            }
+            return .dictionary(mapped)
+        case let array as [Any]:
+            var mapped: [XADAttributeValue] = []
+            mapped.reserveCapacity(array.count)
+            for val in array {
+                guard let converted = fromJSON(val) else { return nil }
+                mapped.append(converted)
+            }
+            return .array(mapped)
+        case let str as String:
+            return .string(str)
+        case let num as NSNumber:
+            if CFGetTypeID(num) == CFBooleanGetTypeID() {
+                return .bool(num.boolValue)
+            }
+            return .number(num.doubleValue)
+        case _ as NSNull:
+            return .null
+        default:
+            return nil
+        }
+    }
+
+    public func toJSONCompatible() -> Any {
+        switch self {
+        case .dictionary(let dict):
+            var out: [String: Any] = [:]
+            for (key, value) in dict {
+                out[key] = value.toJSONCompatible()
+            }
+            return out
+        case .array(let array):
+            return array.map { $0.toJSONCompatible() }
+        case .string(let value):
+            return value
+        case .number(let value):
+            return value
+        case .bool(let value):
+            return value
+        case .null:
+            return NSNull()
+        }
+    }
+}
+
 package struct AttrEnv {
     // name → optional value (nil means unset)
     private(set) var values: [String: String?]
diff --git a/Sources/AsciiDocCore/ISM.swift b/Sources/AsciiDocCore/ISM.swift
index fe7ec25..3d865e7 100644
--- a/Sources/AsciiDocCore/ISM.swift
+++ b/Sources/AsciiDocCore/ISM.swift
@@ -399,6 +399,7 @@ public struct AdocHeader: Sendable, Equatable {
 
 public struct AdocDocument: Sendable, Equatable {
     public var attributes: [String: String?] = [:]
+    public var typedAttributes: [String: XADAttributeValue] = [:]
     public var header: AdocHeader? = nil
     public var blocks: [AdocBlock] = []
     public var span: AdocRange?
@@ -406,17 +407,36 @@ public struct AdocDocument: Sendable, Equatable {
 
     public init(
         attributes: [String: String?] = [:],
+        typedAttributes: [String: XADAttributeValue] = [:],
         header: AdocHeader? = nil,
         blocks: [AdocBlock] = [],
         span: AdocRange? = nil,
         xadOptions: XADOptions = .init()
     ) {
         self.attributes = attributes
+        self.typedAttributes = typedAttributes
         self.header = header
         self.blocks = blocks
         self.span = span
         self.xadOptions = xadOptions
     }
+
+    public init(
+        attributes: [String: String?] = [:],
+        header: AdocHeader? = nil,
+        blocks: [AdocBlock] = [],
+        span: AdocRange? = nil,
+        xadOptions: XADOptions = .init()
+    ) {
+        self.init(
+            attributes: attributes,
+            typedAttributes: [:],
+            header: header,
+            blocks: blocks,
+            span: span,
+            xadOptions: xadOptions
+        )
+    }
 }
 
 public enum AdocMathKind: Sendable, Equatable {
diff --git a/Sources/AsciiDocCore/Parser+Header.swift b/Sources/AsciiDocCore/Parser+Header.swift
index 5023944..5ddcfed 100644
--- a/Sources/AsciiDocCore/Parser+Header.swift
+++ b/Sources/AsciiDocCore/Parser+Header.swift
@@ -25,10 +25,12 @@ extension AdocParser {
     func detectHeader(
         into header: inout AdocHeader?,
         attrs docAttrs: inout [String: String?],
+        typedAttrs: inout [String: XADAttributeValue],
         it: inout TokenIter,
         env: inout AttrEnv,
         lockedAttributes: Set<String>,
-        includeDerivedAttributes: Bool
+        includeDerivedAttributes: Bool,
+        xadOptions: XADOptions
     ) {
         // ——— Header parsing (no blank lines allowed within header) ———
         // Header grammar at top of document:
@@ -145,6 +147,11 @@ extension AdocParser {
                     if !lockedAttributes.contains(name) {
                         docAttrs[name] = value
                         env.set(name, to: value)
+                        if let value, let typed = XADAttributeValue.parse(from: value, xadOptions: xadOptions) {
+                            typedAttrs[name] = typed
+                        } else {
+                            typedAttrs.removeValue(forKey: name)
+                        }
                     }
                     it.consume();
                     lastHeaderTok = tok
@@ -156,6 +163,7 @@ extension AdocParser {
                     if !lockedAttributes.contains(name) {
                         docAttrs[name] = nil
                         env.set(name, to: nil)
+                        typedAttrs.removeValue(forKey: name)
                     }
 
                     it.consume();
diff --git a/Sources/AsciiDocCore/Parser.swift b/Sources/AsciiDocCore/Parser.swift
index e965fc7..a8ab314 100644
--- a/Sources/AsciiDocCore/Parser.swift
+++ b/Sources/AsciiDocCore/Parser.swift
@@ -246,16 +246,26 @@ public struct AdocParser: Sendable {
         var it = TokenIter(tokens: toks, text: preprocessed.source.text)
         var header: AdocHeader? = nil
         var docAttrs: [String: String?] = preprocessed.attributes
+        var typedAttrs: [String: XADAttributeValue] = [:]
+        if xadOptions.enabled {
+            for (key, value) in docAttrs {
+                if let value, let typed = XADAttributeValue.parse(from: value, xadOptions: xadOptions) {
+                    typedAttrs[key] = typed
+                }
+            }
+        }
         var env = AttrEnv(initial: docAttrs)
 
         // Header detection (keep your existing logic)
         detectHeader(
             into: &header,
             attrs: &docAttrs,
+            typedAttrs: &typedAttrs,
             it: &it,
             env: &env,
             lockedAttributes: lockedAttributeNames,
-            includeDerivedAttributes: includeHeaderDerivedAttributes
+            includeDerivedAttributes: includeHeaderDerivedAttributes,
+            xadOptions: xadOptions
         )
 
         // Body blocks via parseBlocks
@@ -267,7 +277,7 @@ public struct AdocParser: Sendable {
             return AdocRange(start: first.range.start, end: last.range.end)
         }()
 
-        return AdocDocument(attributes: docAttrs, header: header, blocks: bodyBlocks, span: docSpan, xadOptions: xadOptions)
+        return AdocDocument(attributes: docAttrs, typedAttributes: typedAttrs, header: header, blocks: bodyBlocks, span: docSpan, xadOptions: xadOptions)
     }
 
 
diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index 6cc3345..d227ad3 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -91,8 +91,10 @@ public final class DocumentRenderer {
             ]
         }
 
+        let typedAttributes = docToRender.typedAttributes.mapValues { $0.toJSONCompatible() }
         var context: [String: Any] = [
             "attributes": docToRender.attributes,
+            "typedAttributes": typedAttributes,
             "headerTitle": docToRender.header?.title?.plain ?? "",
             "blocks": blocks,
             "footnotes": footnotes.map { renderFootnoteDefinition($0, context: inlineContext) },
diff --git a/Sources/AsciiDocRender/FootnoteResolver.swift b/Sources/AsciiDocRender/FootnoteResolver.swift
index 8a58fd8..fa8559e 100644
--- a/Sources/AsciiDocRender/FootnoteResolver.swift
+++ b/Sources/AsciiDocRender/FootnoteResolver.swift
@@ -34,6 +34,7 @@ public final class FootnoteResolver {
         
         let newDoc = AdocDocument(
             attributes: document.attributes,
+            typedAttributes: document.typedAttributes,
             header: document.header,
             blocks: newBlocks,
             span: document.span,

From bef8e6413f66e1e5eded8da5864bed84e01ae159 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Fri, 27 Feb 2026 06:31:56 +0100
Subject: [PATCH 03/38] Add test

---
 .../TypedAttributesTests.swift                | 64 +++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 Tests/AsciiDocCoreTests/TypedAttributesTests.swift

diff --git a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
new file mode 100644
index 0000000..dbcb032
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
@@ -0,0 +1,64 @@
+import Testing
+@testable import AsciiDocCore
+
+@Test func typedAttributesParseStandardJSON() {
+    let source = """
+    :page: {"size":"A4","margins":{"top":"24mm","right":"22mm"}}
+    :grid: {"columns":["2fr","1fr"],"gutter":"8mm"}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard let page = doc.typedAttributes["page"] else {
+        #expect(false, "Expected typed attribute 'page' to be parsed.")
+        return
+    }
+    if case .dictionary(let pageDict) = page {
+        #expect(pageDict["size"] == .string("A4"))
+        if case .dictionary(let margins)? = pageDict["margins"] {
+            #expect(margins["top"] == .string("24mm"))
+            #expect(margins["right"] == .string("22mm"))
+        } else {
+            #expect(false, "Expected margins to be a dictionary.")
+        }
+    } else {
+        #expect(false, "Expected 'page' to be a dictionary.")
+    }
+
+    if case .dictionary(let grid)? = doc.typedAttributes["grid"] {
+        if case .array(let cols)? = grid["columns"] {
+            #expect(cols.count == 2)
+            #expect(cols.first == .string("2fr"))
+            #expect(cols.last == .string("1fr"))
+        } else {
+            #expect(false, "Expected grid.columns to be an array.")
+        }
+    } else {
+        #expect(false, "Expected typed attribute 'grid' to be a dictionary.")
+    }
+}
+
+@Test func typedAttributesParseJSON5WhenAvailable() {
+    if #available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *) {
+        let source = """
+        :page: {size:"A4", margins:{top:"24mm"}}
+        """
+        let parser = AdocParser()
+        let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+        guard let page = doc.typedAttributes["page"] else {
+            #expect(false, "Expected typed attribute 'page' to be parsed with JSON5 syntax.")
+            return
+        }
+        if case .dictionary(let pageDict) = page {
+            #expect(pageDict["size"] == .string("A4"))
+            if case .dictionary(let margins)? = pageDict["margins"] {
+                #expect(margins["top"] == .string("24mm"))
+            } else {
+                #expect(false, "Expected margins to be a dictionary.")
+            }
+        } else {
+            #expect(false, "Expected 'page' to be a dictionary.")
+        }
+    }
+}

From b7db1d03e7261d4413d83b8f93e32d1acae58549 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Fri, 27 Feb 2026 06:54:02 +0100
Subject: [PATCH 04/38] Multiline xad attribute support

---
 Sources/AsciiDocCore/Parser+Header.swift      | 154 +++++++++++++++++-
 .../TypedAttributesTests.swift                | 108 +++++++++++-
 2 files changed, 249 insertions(+), 13 deletions(-)

diff --git a/Sources/AsciiDocCore/Parser+Header.swift b/Sources/AsciiDocCore/Parser+Header.swift
index 5ddcfed..c446ae8 100644
--- a/Sources/AsciiDocCore/Parser+Header.swift
+++ b/Sources/AsciiDocCore/Parser+Header.swift
@@ -143,7 +143,33 @@ extension AdocParser {
                 switch tok.kind {
                 case .attrSet(let nameR, let valueR):
                     let name = it.textFromRelative(range: nameR, token: tok)
-                    let value = valueR.map { it.textFromRelative(range: $0, token: tok) }
+                    var value = valueR.map { it.textFromRelative(range: $0, token: tok) }
+
+                    it.consume()
+                    lastHeaderTok = tok
+                    headerSeen = true
+
+                    if let initial = value {
+                        value = consumeAttributeContinuation(
+                            initial: initial,
+                            it: &it,
+                            lastHeaderTok: &lastHeaderTok
+                        )
+                    }
+
+                    if let raw = value {
+                        value = normalizeXADAttributeValue(raw, xadOptions: xadOptions)
+                    }
+
+                    if let raw = value {
+                        value = consumeAttributeMultilineJSON(
+                            initial: raw,
+                            it: &it,
+                            lastHeaderTok: &lastHeaderTok,
+                            xadOptions: xadOptions
+                        )
+                    }
+
                     if !lockedAttributes.contains(name) {
                         docAttrs[name] = value
                         env.set(name, to: value)
@@ -153,10 +179,6 @@ extension AdocParser {
                             typedAttrs.removeValue(forKey: name)
                         }
                     }
-                    it.consume();
-                    lastHeaderTok = tok
-                    
-                    headerSeen = true
                     continue attrsLoop
                 case .attrUnset(let nameR):
                     let name = it.textFromRelative(range: nameR, token: tok)
@@ -212,6 +234,128 @@ extension AdocParser {
 
 }
 
+private func stripAttributeContinuation(_ value: String) -> (String, Bool) {
+    var end = value.endIndex
+    while end > value.startIndex {
+        let before = value.index(before: end)
+        if value[before].isWhitespace {
+            end = before
+        } else {
+            break
+        }
+    }
+    guard end > value.startIndex else { return (value, false) }
+    let last = value.index(before: end)
+    guard value[last] == "\\" else { return (value, false) }
+    return (String(value[..<last]), true)
+}
+
+private func consumeAttributeContinuation(
+    initial: String,
+    it: inout TokenIter,
+    lastHeaderTok: inout Token?
+) -> String {
+    var result = initial
+    while true {
+        let (stripped, didStrip) = stripAttributeContinuation(result)
+        guard didStrip else { break }
+        result = stripped
+        guard let nextTok = it.peek(), case .text(let r) = nextTok.kind else { break }
+        let nextLine = it.textFromRelative(range: r, token: nextTok)
+        result.append(nextLine)
+        it.consume()
+        lastHeaderTok = nextTok
+    }
+    return result
+}
+
+private func normalizeXADAttributeValue(_ value: String, xadOptions: XADOptions) -> String {
+    guard xadOptions.enabled else { return value }
+    var index = value.startIndex
+    while index < value.endIndex, value[index].isWhitespace {
+        index = value.index(after: index)
+    }
+    guard index < value.endIndex, value[index] == "\\" else { return value }
+    let nextIndex = value.index(after: index)
+    guard nextIndex < value.endIndex else { return value }
+    let nextChar = value[nextIndex]
+    guard nextChar == "{" || nextChar == "[" else { return value }
+    var result = value
+    result.remove(at: index)
+    return result
+}
+
+private func consumesMultilineJSON(_ value: String, xadOptions: XADOptions) -> Bool {
+    guard xadOptions.enabled else { return false }
+    var index = value.startIndex
+    while index < value.endIndex, value[index].isWhitespace {
+        index = value.index(after: index)
+    }
+    guard index < value.endIndex else { return false }
+    let lead = value[index]
+    guard lead == "{" || lead == "[" else { return false }
+    return !isJSONBalanced(value)
+}
+
+private func isJSONBalanced(_ value: String) -> Bool {
+    var braceDepth = 0
+    var bracketDepth = 0
+    var inString = false
+    var escapeNext = false
+
+    for ch in value {
+        if inString {
+            if escapeNext {
+                escapeNext = false
+                continue
+            }
+            if ch == "\\" {
+                escapeNext = true
+                continue
+            }
+            if ch == "\"" {
+                inString = false
+            }
+            continue
+        }
+
+        if ch == "\"" {
+            inString = true
+            continue
+        }
+        if ch == "{" { braceDepth += 1 }
+        else if ch == "}" { braceDepth -= 1 }
+        else if ch == "[" { bracketDepth += 1 }
+        else if ch == "]" { bracketDepth -= 1 }
+    }
+
+    return braceDepth <= 0 && bracketDepth <= 0 && !inString
+}
+
+private func consumeAttributeMultilineJSON(
+    initial: String,
+    it: inout TokenIter,
+    lastHeaderTok: inout Token?,
+    xadOptions: XADOptions
+) -> String {
+    guard consumesMultilineJSON(initial, xadOptions: xadOptions) else { return initial }
+
+    var result = initial
+    while true {
+        guard let nextTok = it.peek(), case .text(let r) = nextTok.kind else { break }
+        let nextLine = it.textFromRelative(range: r, token: nextTok)
+        result.append("\n")
+        result.append(nextLine)
+        it.consume()
+        lastHeaderTok = nextTok
+
+        if !consumesMultilineJSON(result, xadOptions: xadOptions) {
+            break
+        }
+    }
+    return result
+}
+
 private func parseAuthorsLine(_ line: String) -> [HeaderAuthorInfo] {
     let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
     guard !trimmed.isEmpty else { return [] }
diff --git a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
index dbcb032..65b196a 100644
--- a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
+++ b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
@@ -10,7 +10,7 @@ import Testing
     let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
 
     guard let page = doc.typedAttributes["page"] else {
-        #expect(false, "Expected typed attribute 'page' to be parsed.")
+        Issue.record("Expected typed attribute 'page' to be parsed.")
         return
     }
     if case .dictionary(let pageDict) = page {
@@ -19,10 +19,10 @@ import Testing
             #expect(margins["top"] == .string("24mm"))
             #expect(margins["right"] == .string("22mm"))
         } else {
-            #expect(false, "Expected margins to be a dictionary.")
+            Issue.record("Expected margins to be a dictionary.")
         }
     } else {
-        #expect(false, "Expected 'page' to be a dictionary.")
+        Issue.record("Expected 'page' to be a dictionary.")
     }
 
     if case .dictionary(let grid)? = doc.typedAttributes["grid"] {
@@ -31,10 +31,10 @@ import Testing
             #expect(cols.first == .string("2fr"))
             #expect(cols.last == .string("1fr"))
         } else {
-            #expect(false, "Expected grid.columns to be an array.")
+            Issue.record("Expected grid.columns to be an array.")
         }
     } else {
-        #expect(false, "Expected typed attribute 'grid' to be a dictionary.")
+        Issue.record("Expected typed attribute 'grid' to be a dictionary.")
     }
 }
 
@@ -47,7 +47,7 @@ import Testing
         let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
 
         guard let page = doc.typedAttributes["page"] else {
-            #expect(false, "Expected typed attribute 'page' to be parsed with JSON5 syntax.")
+            Issue.record("Expected typed attribute 'page' to be parsed with JSON5 syntax.")
             return
         }
         if case .dictionary(let pageDict) = page {
@@ -55,10 +55,102 @@ import Testing
             if case .dictionary(let margins)? = pageDict["margins"] {
                 #expect(margins["top"] == .string("24mm"))
             } else {
-                #expect(false, "Expected margins to be a dictionary.")
+                Issue.record("Expected margins to be a dictionary.")
             }
         } else {
-            #expect(false, "Expected 'page' to be a dictionary.")
+            Issue.record("Expected 'page' to be a dictionary.")
         }
     }
 }
+@Test func typedAttributesParseMultilineStringContent() {
+    let source = """
+    :note: {"text":"line1\\nline2"}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard let note = doc.typedAttributes["note"] else {
+        Issue.record("Expected typed attribute 'note' to be parsed.")
+        return
+    }
+    if case .dictionary(let noteDict) = note {
+        #expect(noteDict["text"] == .string("line1\nline2"))
+    } else {
+        Issue.record("Expected 'note' to be a dictionary.")
+    }
+}
+
+@Test func typedAttributesParseContinuationLines() {
+    let source = """
+    :page: {"size":"A4", \\
+    "margins":{"top":"24mm"}}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+    guard let page = doc.typedAttributes["page"] else {
+        Issue.record("Expected typed attribute 'page' to be parsed.")
+        return
+    }
+    if case .dictionary(let pageDict) = page {
+        #expect(pageDict["size"] == .string("A4"))
+        if case .dictionary(let margins)? = pageDict["margins"] {
+            #expect(margins["top"] == .string("24mm"))
+        } else {
+            Issue.record("Expected margins to be a dictionary.")
+        }
+    } else {
+        Issue.record("Expected 'page' to be a dictionary.")
+    }
+}
+
+@Test func typedAttributesParseEscapedLeadingBraces() {
+    let source = """
+    :page: \\{"size":"A4"}
+    :list: \\["a","b"]
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    if case .dictionary(let pageDict)? = doc.typedAttributes["page"] {
+        #expect(pageDict["size"] == .string("A4"))
+    } else {
+        Issue.record("Expected escaped JSON object to parse.")
+    }
+    if case .array(let items)? = doc.typedAttributes["list"] {
+        #expect(items.count == 2)
+        #expect(items.first == .string("a"))
+        #expect(items.last == .string("b"))
+    } else {
+        Issue.record("Expected escaped JSON array to parse.")
+    }
+}
+
+
+@Test func typedAttributeParseMultilineAttr() {
+    let source = """
+    :page: {
+        size: "A4"
+    }
+    :list: [
+        "a", "b"
+    ]
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    if case .dictionary(let pageDict)? = doc.typedAttributes["page"] {
+        #expect(pageDict["size"] == .string("A4"))
+    } else {
+        Issue.record("Expected escaped JSON object to parse.")
+    }
+    if case .array(let items)? = doc.typedAttributes["list"] {
+        #expect(items.count == 2)
+        #expect(items.first == .string("a"))
+        #expect(items.last == .string("b"))
+    } else {
+        Issue.record("Expected escaped JSON array to parse.")
+    }
+}
+
+
+

From c9f5cd154b4b689803212e022800fc76ba974443 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Fri, 27 Feb 2026 07:06:01 +0100
Subject: [PATCH 05/38] Address various warnings

---
 Tests/AsciiDocCoreTests/FootnoteTests.swift | 8 ++++----
 Tests/AsciiDocCoreTests/ParserTests.swift   | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Tests/AsciiDocCoreTests/FootnoteTests.swift b/Tests/AsciiDocCoreTests/FootnoteTests.swift
index d668518..9fe654e 100644
--- a/Tests/AsciiDocCoreTests/FootnoteTests.swift
+++ b/Tests/AsciiDocCoreTests/FootnoteTests.swift
@@ -42,8 +42,8 @@ struct FootnoteTests {
         guard case .text(let w, _) = inlines[0] else { #expect(Bool(false)); return }
         #expect(w == "Word")
         
-        guard case .footnote(let content, let ref, let id, _) = inlines[1] else { 
-            #expect(Bool(false), "Expected footnote with ref") 
+        guard case .footnote(let content, let ref, _, _) = inlines[1] else {
+            #expect(Bool(false), "Expected footnote with ref")
             return 
         }
         #expect(ref == "myid")
@@ -89,7 +89,7 @@ struct FootnoteTests {
     @Test func resolvingFootnoteReferences() async throws {
         // Test ref resolution: footnote:foo[Text] ... footnote:foo[]
         let src = "Def footnote:foo[Main]. Ref footnote:foo[]."
-        let p = AdocParagraph(text: AdocText(plain: src))
+        let _ = AdocParagraph(text: AdocText(plain: src))
         // Note: AdocText(plain:) parses internally using default parser? 
         // No, AdocText(plain:) creates a .text node. It does NOT parse markup!
         // I need to parse inlines manually for this test to be realistic if I'm testing Resolver on pre-parsed nodes.
@@ -119,7 +119,7 @@ struct FootnoteTests {
         // Check content?
         
         // Check resolved nodes
-        guard let pr = resolution.document.blocks.first as? AdocBlock,
+        guard let pr = resolution.document.blocks.first,
               case .paragraph(let par) = pr else {
             return
         }
diff --git a/Tests/AsciiDocCoreTests/ParserTests.swift b/Tests/AsciiDocCoreTests/ParserTests.swift
index cabcbbf..706dbfc 100644
--- a/Tests/AsciiDocCoreTests/ParserTests.swift
+++ b/Tests/AsciiDocCoreTests/ParserTests.swift
@@ -307,7 +307,7 @@ struct ParserTests {
       //#expect(secs.contains(where: { $0.level == 1 && $0.title == "Doc" }))
       #expect(secs.contains(where: { $0.level == 1 && $0.title == "Section" }))
 
-      let paras = ASGInspector.paragraphs(asg)
+      let _ = ASGInspector.paragraphs(asg)
       //#expect(paras.contains("Intro para"))
 
       let ls = ASGInspector.lists(asg)

From 7a1e31a51ca7fc505f1870a3830d475c25eee279 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Fri, 27 Feb 2026 07:43:32 +0100
Subject: [PATCH 06/38] Rework attribute handling to make get / set macros
 possible

---
 Sources/AsciiDocCore/Attributes.swift      | 216 +++++++++++++++++++-
 Sources/AsciiDocCore/Parser+Block.swift    | 223 ++++++++++++++++++++-
 Sources/AsciiDocCore/Parser+DList.swift    |  12 +-
 Sources/AsciiDocCore/Parser+Example.swift  |   4 +-
 Sources/AsciiDocCore/Parser+Header.swift   |  15 +-
 Sources/AsciiDocCore/Parser+Lists.swift    |  14 +-
 Sources/AsciiDocCore/Parser+Open.swift     |   4 +-
 Sources/AsciiDocCore/Parser+Quote.swift    |   4 +-
 Sources/AsciiDocCore/Parser+Sections.swift |   4 +-
 Sources/AsciiDocCore/Parser+Sidebar.swift  |   4 +-
 Sources/AsciiDocCore/Parser.swift          |   8 +-
 11 files changed, 459 insertions(+), 49 deletions(-)

diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index 82c8698..3b6b80f 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -91,19 +91,66 @@ public enum XADAttributeValue: Sendable, Equatable {
 package struct AttrEnv {
     // name → optional value (nil means unset)
     private(set) var values: [String: String?]
-
-    package init(initial: [String: String?] = [:]) {
+    private(set) var typedValues: [String: XADAttributeValue]
+    let xadOptions: XADOptions
+
+    package init(
+        initial: [String: String?] = [:],
+        typedAttributes: [String: XADAttributeValue] = [:],
+        xadOptions: XADOptions = .init(enabled: false)
+    ) {
         self.values = initial
+        self.typedValues = typedAttributes
+        self.xadOptions = xadOptions
     }
 
     mutating func set(_ name: String, to value: String?) {
         values[name] = value
     }
 
+    mutating func applyAttributeSet(name: String, value: String?) {
+        values[name] = value
+        guard xadOptions.enabled else { return }
+        let rawValue = value ?? ""
+        if isXADPathName(name) {
+            let typed = XADAttributeValue.parse(from: rawValue, xadOptions: xadOptions) ?? .string(rawValue)
+            setTypedPath(name, value: typed)
+            return
+        }
+        if let value, let typed = XADAttributeValue.parse(from: value, xadOptions: xadOptions) {
+            typedValues[name] = typed
+        } else {
+            typedValues.removeValue(forKey: name)
+        }
+    }
+
+    mutating func applyAttributeUnset(name: String) {
+        values[name] = nil
+        guard xadOptions.enabled else { return }
+        if isXADPathName(name) {
+            setTypedPath(name, value: .null)
+        } else {
+            typedValues.removeValue(forKey: name)
+        }
+    }
+
     func value(for name: String) -> String? {
         values[name] ?? nil
     }
 
+    func resolveAttribute(_ name: String, join: String? = nil) -> String? {
+        if xadOptions.enabled, isXADPathName(name), let typed = resolveTypedPath(name) {
+            return stringify(typed, join: join)
+        }
+        if let raw = value(for: name) {
+            return raw
+        }
+        if xadOptions.enabled, let typed = typedValues[name] {
+            return stringify(typed, join: join)
+        }
+        return nil
+    }
+
     /// Expand {attr} in a string using the *current* environment.
     /// No re-parsing of markup is done; this is purely textual.
     package func expand(_ s: String) -> String {
@@ -122,7 +169,7 @@ package struct AttrEnv {
                 }
                 if j < end, s[j] == "}" {
                     let name = String(s[nameStart..<j])
-                    if let v = value(for: name) {
+                    if let v = resolveAttribute(name) {
                         result += v
                     } else {
                         // Unknown attribute → keep literal {name}
@@ -141,6 +188,169 @@ package struct AttrEnv {
 }
 
 
+private enum XADPathSegment {
+    case key(String)
+    case index(Int)
+}
+
+private func isXADPathName(_ name: String) -> Bool {
+    name.contains(".") || name.contains("[")
+}
+
+private func parseXADPathSegments(_ path: String, env: AttrEnv) -> [XADPathSegment]? {
+    var segments: [XADPathSegment] = []
+    var token = ""
+    var index = path.startIndex
+
+    func appendToken() -> Bool {
+        let trimmed = token.trimmingCharacters(in: .whitespacesAndNewlines)
+        token.removeAll(keepingCapacity: true)
+        guard !trimmed.isEmpty else { return true }
+        if trimmed.allSatisfy({ $0.isNumber }), let value = Int(trimmed) {
+            segments.append(.index(value))
+        } else {
+            segments.append(.key(trimmed))
+        }
+        return true
+    }
+
+    while index < path.endIndex {
+        let ch = path[index]
+        if ch == "." {
+            _ = appendToken()
+            index = path.index(after: index)
+            continue
+        }
+        if ch == "[" {
+            _ = appendToken()
+            let close = path[index...].firstIndex(of: "]")
+            guard let close else { return nil }
+            let content = path[path.index(after: index)..<close]
+            let resolved = resolveBracketIndex(content, env: env)
+            guard let resolved, let intValue = Int(resolved) else { return nil }
+            segments.append(.index(intValue))
+            index = path.index(after: close)
+            continue
+        }
+        token.append(ch)
+        index = path.index(after: index)
+    }
+    _ = appendToken()
+    return segments.isEmpty ? nil : segments
+}
+
+private func resolveBracketIndex(_ content: Substring, env: AttrEnv) -> String? {
+    let trimmed = content.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !trimmed.isEmpty else { return nil }
+    if trimmed.hasPrefix("{") && trimmed.hasSuffix("}") {
+        let start = trimmed.index(after: trimmed.startIndex)
+        let end = trimmed.index(before: trimmed.endIndex)
+        let name = String(trimmed[start..<end])
+        return env.resolveAttribute(name)
+    }
+    return String(trimmed)
+}
+
+private extension AttrEnv {
+    func resolveTypedPath(_ path: String) -> XADAttributeValue? {
+        guard let segments = parseXADPathSegments(path, env: self), !segments.isEmpty else {
+            return nil
+        }
+        guard case .key(let root) = segments[0], let rootValue = typedValues[root] else {
+            return nil
+        }
+        var current: XADAttributeValue? = rootValue
+        for segment in segments.dropFirst() {
+            guard let value = current else { return nil }
+            switch (value, segment) {
+            case (.dictionary(let dict), .key(let key)):
+                current = dict[key]
+            case (.array(let array), .index(let idx)):
+                guard idx >= 0, idx < array.count else { return nil }
+                current = array[idx]
+            default:
+                return nil
+            }
+        }
+        return current
+    }
+
+    func stringify(_ value: XADAttributeValue, join: String?) -> String {
+        switch value {
+        case .string(let s):
+            return s
+        case .number(let n):
+            return String(n)
+        case .bool(let b):
+            return b ? "true" : "false"
+        case .null:
+            return "null"
+        case .array(let array):
+            if let join {
+                return array.map { stringify($0, join: nil) }.joined(separator: join)
+            }
+            return jsonString(from: value)
+        case .dictionary:
+            return jsonString(from: value)
+        }
+    }
+
+    func jsonString(from value: XADAttributeValue) -> String {
+        let obj = value.toJSONCompatible()
+        guard JSONSerialization.isValidJSONObject(obj),
+              let data = try? JSONSerialization.data(withJSONObject: obj, options: []) else {
+            return ""
+        }
+        return String(data: data, encoding: .utf8) ?? ""
+    }
+
+    mutating func setTypedPath(_ path: String, value: XADAttributeValue) {
+        guard let segments = parseXADPathSegments(path, env: self), !segments.isEmpty else { return }
+        guard case .key(let root) = segments[0] else { return }
+        let updated = setTypedValue(
+            current: typedValues[root],
+            segments: segments.dropFirst(),
+            value: value
+        )
+        typedValues[root] = updated
+    }
+
+    func setTypedValue(
+        current: XADAttributeValue?,
+        segments: ArraySlice<XADPathSegment>,
+        value: XADAttributeValue
+    ) -> XADAttributeValue {
+        guard let first = segments.first else { return value }
+        let rest = segments.dropFirst()
+
+        switch first {
+        case .key(let key):
+            var dict: [String: XADAttributeValue]
+            if case .dictionary(let existing)? = current {
+                dict = existing
+            } else {
+                dict = [:]
+            }
+            let updated = setTypedValue(current: dict[key], segments: rest, value: value)
+            dict[key] = updated
+            return .dictionary(dict)
+        case .index(let idx):
+            var array: [XADAttributeValue]
+            if case .array(let existing)? = current {
+                array = existing
+            } else {
+                array = []
+            }
+            if idx >= array.count {
+                array.append(contentsOf: repeatElement(.null, count: idx - array.count + 1))
+            }
+            let updated = setTypedValue(current: array[idx], segments: rest, value: value)
+            array[idx] = updated
+            return .array(array)
+        }
+    }
+}
+
 package extension AdocInline {
     func applyingAttributes(using env: AttrEnv) -> AdocInline {
         switch self {
diff --git a/Sources/AsciiDocCore/Parser+Block.swift b/Sources/AsciiDocCore/Parser+Block.swift
index 0a634ff..3afe537 100644
--- a/Sources/AsciiDocCore/Parser+Block.swift
+++ b/Sources/AsciiDocCore/Parser+Block.swift
@@ -25,13 +25,156 @@ private func parseDirectivePayload(_ payload: String) -> (target: String, body:
     )
 }
 
+private func parseMacroAttributeList(_ body: String) -> [String: String] {
+    var result: [String: String] = [:]
+    var current = ""
+    var inQuotes = false
+    var quoteChar: Character? = nil
+
+    func flush() {
+        let part = current.trimmingCharacters(in: .whitespacesAndNewlines)
+        current = ""
+        guard !part.isEmpty else { return }
+        if let eq = part.firstIndex(of: "=") {
+            let key = part[..<eq].trimmingCharacters(in: .whitespacesAndNewlines)
+            let valueStart = part.index(after: eq)
+            var value = part[valueStart...].trimmingCharacters(in: .whitespacesAndNewlines)
+            if value.count >= 2 {
+                if (value.first == "\"" && value.last == "\"") || (value.first == "'" && value.last == "'") {
+                    value = String(value.dropFirst().dropLast())
+                }
+            }
+            if !key.isEmpty {
+                result[String(key)] = String(value)
+            }
+        } else {
+            result[part] = ""
+        }
+    }
+
+    for ch in body {
+        if inQuotes {
+            if ch == "\\" {
+                current.append(ch)
+                continue
+            }
+            if let currentQuote = quoteChar, ch == currentQuote {
+                inQuotes = false
+                quoteChar = nil
+            }
+            current.append(ch)
+            continue
+        }
+
+        if ch == "\"" || ch == "'" {
+            inQuotes = true
+            quoteChar = ch
+            current.append(ch)
+            continue
+        }
+
+        if ch == "," {
+            flush()
+            continue
+        }
+        current.append(ch)
+    }
+
+    flush()
+    return result
+}
+
+private func normalizeXADAttributeValue(_ value: String, xadOptions: XADOptions) -> String {
+    guard xadOptions.enabled else { return value }
+    var index = value.startIndex
+    while index < value.endIndex, value[index].isWhitespace {
+        index = value.index(after: index)
+    }
+    guard index < value.endIndex, value[index] == "\\" else { return value }
+    let nextIndex = value.index(after: index)
+    guard nextIndex < value.endIndex else { return value }
+    let nextChar = value[nextIndex]
+    guard nextChar == "{" || nextChar == "[" else { return value }
+    var result = value
+    result.remove(at: index)
+    return result
+}
+
+private func consumesMultilineJSON(_ value: String, xadOptions: XADOptions) -> Bool {
+    guard xadOptions.enabled else { return false }
+    var index = value.startIndex
+    while index < value.endIndex, value[index].isWhitespace {
+        index = value.index(after: index)
+    }
+    guard index < value.endIndex else { return false }
+    let lead = value[index]
+    guard lead == "{" || lead == "[" else { return false }
+    return !isJSONBalanced(value)
+}
+
+private func isJSONBalanced(_ value: String) -> Bool {
+    var braceDepth = 0
+    var bracketDepth = 0
+    var inString = false
+    var escapeNext = false
+
+    for ch in value {
+        if inString {
+            if escapeNext {
+                escapeNext = false
+                continue
+            }
+            if ch == "\\" {
+                escapeNext = true
+                continue
+            }
+            if ch == "\"" {
+                inString = false
+            }
+            continue
+        }
+
+        if ch == "\"" {
+            inString = true
+            continue
+        }
+        if ch == "{" { braceDepth += 1 }
+        else if ch == "}" { braceDepth -= 1 }
+        else if ch == "[" { bracketDepth += 1 }
+        else if ch == "]" { bracketDepth -= 1 }
+    }
+
+    return braceDepth <= 0 && bracketDepth <= 0 && !inString
+}
+
+private func consumeAttributeMultilineJSON(
+    initial: String,
+    it: inout TokenIter,
+    xadOptions: XADOptions
+) -> String {
+    guard consumesMultilineJSON(initial, xadOptions: xadOptions) else { return initial }
+
+    var result = initial
+    while true {
+        guard let nextTok = it.peek(), case .text(let r) = nextTok.kind else { break }
+        let nextLine = it.textFromRelative(range: r, token: nextTok)
+        result.append("\n")
+        result.append(nextLine)
+        it.consume()
+        if !consumesMultilineJSON(result, xadOptions: xadOptions) {
+            break
+        }
+    }
+    return result
+}
+
 extension AdocParser {
 
     // Parse a sequence of blocks until `stop` says “this token belongs to the caller”.
     // Parse blocks until `stop` returns true for the *next* token.
     func parseBlocks(
         it: inout TokenIter,
-        env: AttrEnv,
+        env: inout AttrEnv,
         stop: (Token) -> Bool
     ) -> [AdocBlock] {
         var blocks: [AdocBlock] = []
@@ -40,7 +183,7 @@ extension AdocParser {
             let before = it.index
 
 
-            if let block = parseBlock(it: &it, env: env) {
+            if let block = parseBlock(it: &it, env: &env) {
                 blocks.append(block)
             } else {
                 // Safety to avoid infinite loops: always consume something.
@@ -55,20 +198,45 @@ extension AdocParser {
     }
     func parseBlock(
         it: inout TokenIter,
-        env: AttrEnv
+        env: inout AttrEnv
     ) -> AdocBlock? {
         // Slurp block metadata (ID, roles, options, attributes, title, span)
         let meta = consumeBlockMeta(it: &it, env: env)
 
         guard let tok = it.peek() else { return nil }
 
+        if case .attrSet(let nameR, let valueR) = tok.kind {
+            let name = it.textFromRelative(range: nameR, token: tok)
+            var value = valueR.map { it.textFromRelative(range: $0, token: tok) }
+            it.consume()
+            if let raw = value {
+                value = normalizeXADAttributeValue(raw, xadOptions: env.xadOptions)
+            }
+            if let raw = value {
+                value = consumeAttributeMultilineJSON(
+                    initial: raw,
+                    it: &it,
+                    xadOptions: env.xadOptions
+                )
+            }
+            env.applyAttributeSet(name: name, value: value)
+            return nil
+        }
+
+        if case .attrUnset(let nameR) = tok.kind {
+            let name = it.textFromRelative(range: nameR, token: tok)
+            it.consume()
+            env.applyAttributeUnset(name: name)
+            return nil
+        }
+
         var inner: AdocBlock?
 
         // Lists / DLists: handled up front, since they consume multiple lines
         switch tok.kind {
         case .atxSection(let level, let titleRange):
             if let section = parseSection(from: tok, level: level, titleRange: titleRange,
-                                          it: &it, env: env) {
+                                          it: &it, env: &env) {
                 var block = AdocBlock.section(section)
                 meta.applyMeta(to: &block)
                 return block;
@@ -83,7 +251,7 @@ extension AdocParser {
                     for: key,
                     listKind: listKind,
                     it: &it,
-                    env: env,
+                    env: &env,
                     stack: &stack,
                     bibliographyStyle: isBibliography
                 ) {
@@ -102,7 +270,7 @@ extension AdocParser {
                 if let dlist = parseDList(
                     for: marker,
                     it: &it,
-                    env: env,
+                    env: &env,
                     stack: &stack
                 ) {
                     inner = .dlist(dlist)
@@ -165,12 +333,12 @@ extension AdocParser {
                 }
 
             case .quote:
-                if let q = parseQuote(it: &it, env: env) {
+                if let q = parseQuote(it: &it, env: &env) {
                     inner = .quote(q)
                 }
 
             case .verseBlock:
-                if let q = parseQuote(it: &it, env: env) {
+                if let q = parseQuote(it: &it, env: &env) {
                     let span = combinedSpan(metaSpan: meta.span, innerSpan: q.span)
                     let verse = AdocVerse(
                         text: nil,
@@ -204,17 +372,17 @@ extension AdocParser {
                 }
 
             case .sidebar:
-                if let s = parseSidebar(it: &it, env: env) {
+                if let s = parseSidebar(it: &it, env: &env) {
                     inner = .sidebar(s)
                 }
 
             case .example:
-                if let e = parseExample(it: &it, env: env) {
+                if let e = parseExample(it: &it, env: &env) {
                     inner = .example(e)
                 }
 
             case .open:
-                if let o = parseOpen(it: &it, env: env) {
+                if let o = parseOpen(it: &it, env: &env) {
                     inner = .open(o)
                 }
 
@@ -260,6 +428,39 @@ extension AdocParser {
                      break
                  }
 
+                 if name == "get", env.xadOptions.enabled {
+                     let attrs = parseMacroAttributeList(payloadParts.body ?? "")
+                     if let path = attrs["path"] {
+                         let join = attrs["join"]
+                         let span = it.spanForLine(tok)
+                         let text: String
+                         if let resolved = env.resolveAttribute(path, join: join) {
+                             text = resolved
+                         } else {
+                             text = String(tok.string)
+                         }
+                         let para = AdocParagraph(
+                             text: AdocText(plain: text, span: span),
+                             id: meta.id,
+                             title: meta.title,
+                             reftext: nil,
+                             meta: .init(),
+                             span: span
+                         )
+                         inner = .paragraph(para)
+                         break
+                     }
+                 }
+
+                 if name == "set", env.xadOptions.enabled {
+                     let attrs = parseMacroAttributeList(payloadParts.body ?? "")
+                     if let path = attrs["path"] {
+                         let rawValue = attrs["value"] ?? ""
+                         env.applyAttributeSet(name: path, value: rawValue)
+                         return nil
+                     }
+                 }
+
                  let macro = AdocBlockMacro(
                      name: name,
                      target: payloadParts.target,
diff --git a/Sources/AsciiDocCore/Parser+DList.swift b/Sources/AsciiDocCore/Parser+DList.swift
index 642f276..c2ed0ad 100644
--- a/Sources/AsciiDocCore/Parser+DList.swift
+++ b/Sources/AsciiDocCore/Parser+DList.swift
@@ -9,7 +9,7 @@ extension AdocParser {
     /// IMPORTANT: this function CONSUMES the `.dlistItem` token.
     private func makeDListItem(
         it: inout TokenIter,
-        env: AttrEnv
+        env: inout AttrEnv
     ) -> AdocDListItem {
         guard let tok = it.peek(),
               case .dlistItem(let termRange, _, let descRange) = tok.kind
@@ -96,7 +96,7 @@ extension AdocParser {
     func parseDList(
         for marker: String,
         it: inout TokenIter,
-        env: AttrEnv,
+        env: inout AttrEnv,
         stack: inout [String]
     ) -> AdocDList? {
         stack.append(marker)
@@ -123,7 +123,7 @@ extension AdocParser {
 
                 if thisMarker == marker {
                     // Same marker → sibling item at this level
-                    let item = makeDListItem(it: &it, env: env)   // consumes token
+                    let item = makeDListItem(it: &it, env: &env)   // consumes token
                     items.append(item)
                     continue outer
                 }
@@ -139,7 +139,7 @@ extension AdocParser {
 
                 // New marker not in any outer level → nested dlist under last item
                 if var lastItem = items.popLast() {
-                    if let nested = parseDList(for: thisMarker, it: &it, env: env, stack: &stack) {
+                    if let nested = parseDList(for: thisMarker, it: &it, env: &env, stack: &stack) {
                         lastItem.blocks.append(.dlist(nested))
                     }
                     items.append(lastItem)
@@ -167,12 +167,12 @@ extension AdocParser {
                         let line       = nextTok.string
                         let thisMarker = String(line[sepRange])
 
-                        if let nested = parseDList(for: thisMarker, it: &it, env: env, stack: &stack) {
+                        if let nested = parseDList(for: thisMarker, it: &it, env: &env, stack: &stack) {
                             lastItem.blocks.append(.dlist(nested))
                         }
 
                     default:
-                        if let nestedBlock = parseBlock(it: &it, env: env) {
+                        if let nestedBlock = parseBlock(it: &it, env: &env) {
                             lastItem.blocks.append(nestedBlock)
                         }
                     }
diff --git a/Sources/AsciiDocCore/Parser+Example.swift b/Sources/AsciiDocCore/Parser+Example.swift
index d8745dd..4d12d3f 100644
--- a/Sources/AsciiDocCore/Parser+Example.swift
+++ b/Sources/AsciiDocCore/Parser+Example.swift
@@ -6,7 +6,7 @@
 extension AdocParser {
     func parseExample(
         it: inout TokenIter,
-        env: AttrEnv
+        env: inout AttrEnv
     ) -> AdocExample? {
         // We expect the current token to be an example fence
         guard let open = it.peek(),
@@ -20,7 +20,7 @@ extension AdocParser {
         it.consume()
 
         // Parse inner blocks until we see a matching example fence
-        let innerBlocks: [AdocBlock] = parseBlocks(it: &it, env: env) { tok in
+        let innerBlocks: [AdocBlock] = parseBlocks(it: &it, env: &env) { tok in
             if case .blockFence(let k, let l) = tok.kind,
                k == .example, l == fenceLen {
                 return true   // stop before this token
diff --git a/Sources/AsciiDocCore/Parser+Header.swift b/Sources/AsciiDocCore/Parser+Header.swift
index c446ae8..a210895 100644
--- a/Sources/AsciiDocCore/Parser+Header.swift
+++ b/Sources/AsciiDocCore/Parser+Header.swift
@@ -171,21 +171,13 @@ extension AdocParser {
                     }
 
                     if !lockedAttributes.contains(name) {
-                        docAttrs[name] = value
-                        env.set(name, to: value)
-                        if let value, let typed = XADAttributeValue.parse(from: value, xadOptions: xadOptions) {
-                            typedAttrs[name] = typed
-                        } else {
-                            typedAttrs.removeValue(forKey: name)
-                        }
+                        env.applyAttributeSet(name: name, value: value)
                     }
                     continue attrsLoop
                 case .attrUnset(let nameR):
                     let name = it.textFromRelative(range: nameR, token: tok)
                     if !lockedAttributes.contains(name) {
-                        docAttrs[name] = nil
-                        env.set(name, to: nil)
-                        typedAttrs.removeValue(forKey: name)
+                        env.applyAttributeUnset(name: name)
                     }
 
                     it.consume();
@@ -204,6 +196,8 @@ extension AdocParser {
 
             // If we produced any part of the header, ensure attributes map is non-nil
             if headerSeen {
+                docAttrs = env.values
+                typedAttrs = env.typedValues
                 if docAttrs.isEmpty { docAttrs = [:] }
                 // Ensure we have a header object even if it was attributes-only
                 if header == nil {
@@ -228,6 +222,7 @@ extension AdocParser {
                         lockedAttributes: lockedAttributes
                     )
                 }
+                env = AttrEnv(initial: docAttrs, typedAttributes: typedAttrs, xadOptions: xadOptions)
             }
         }
     }
diff --git a/Sources/AsciiDocCore/Parser+Lists.swift b/Sources/AsciiDocCore/Parser+Lists.swift
index c723756..ca79e5c 100644
--- a/Sources/AsciiDocCore/Parser+Lists.swift
+++ b/Sources/AsciiDocCore/Parser+Lists.swift
@@ -103,7 +103,7 @@ extension AdocParser {
     /// IMPORTANT: this function CONSUMES the `.listItem` token.
     private func makeListItem(
         it: inout TokenIter,
-        env: AttrEnv,
+        env: inout AttrEnv,
         markerKey: ListMarkerKey,
         bibliographyStyle: Bool
     ) -> AdocListItem {
@@ -231,7 +231,7 @@ extension AdocParser {
         for marker: ListMarkerKey,
         listKind: AdocListKind,
         it: inout TokenIter,
-        env: AttrEnv,
+        env: inout AttrEnv,
         stack: inout [ListMarkerKey],
         bibliographyStyle: Bool = false
     ) -> AdocList? {
@@ -262,7 +262,7 @@ extension AdocParser {
 
                 if key == marker {
                     // Same marker → sibling item on this level
-                    let item = makeListItem(it: &it, env: env, markerKey: key, bibliographyStyle: bibliographyStyle) // consumes token
+                    let item = makeListItem(it: &it, env: &env, markerKey: key, bibliographyStyle: bibliographyStyle) // consumes token
                     items.append(item)
                     continue outer
                 }
@@ -283,7 +283,7 @@ extension AdocParser {
                         for: key,
                         listKind: inferredListKind(from: key),
                         it: &it,
-                        env: env,
+                        env: &env,
                         stack: &stack,
                         bibliographyStyle: false
                     ) {
@@ -318,7 +318,7 @@ extension AdocParser {
                                 for: key,
                                 listKind: inferredListKind(from: key),
                                 it: &it,
-                                env: env,
+                                env: &env,
                                 stack: &stack,
                                 bibliographyStyle: false
                             ) {
@@ -326,13 +326,13 @@ extension AdocParser {
                             }
                         } else {
                             // Invalid list marker; fall back to generic block parsing
-                            if let block = parseBlock(it: &it, env: env) {
+                            if let block = parseBlock(it: &it, env: &env) {
                                 lastItem.blocks.append(block)
                             }
                         }
 
                     default:
-                        if let block = parseBlock(it: &it, env: env) {
+                        if let block = parseBlock(it: &it, env: &env) {
                             lastItem.blocks.append(block)
                         }
                     }
diff --git a/Sources/AsciiDocCore/Parser+Open.swift b/Sources/AsciiDocCore/Parser+Open.swift
index 7a9e2e3..fd15093 100644
--- a/Sources/AsciiDocCore/Parser+Open.swift
+++ b/Sources/AsciiDocCore/Parser+Open.swift
@@ -6,7 +6,7 @@
 extension AdocParser {
     func parseOpen(
         it: inout TokenIter,
-        env: AttrEnv
+        env: inout AttrEnv
     ) -> AdocOpen? {
         guard let open = it.peek(),
               case .blockFence(let kind, let fenceLen) = open.kind,
@@ -29,7 +29,7 @@ extension AdocParser {
                 it.consume()
 
             default:
-                if let b = parseBlock(it: &it, env: env) {
+                if let b = parseBlock(it: &it, env: &env) {
                     blocks.append(b)
                 } else {
                     it.consume()
diff --git a/Sources/AsciiDocCore/Parser+Quote.swift b/Sources/AsciiDocCore/Parser+Quote.swift
index e464486..62e2c83 100644
--- a/Sources/AsciiDocCore/Parser+Quote.swift
+++ b/Sources/AsciiDocCore/Parser+Quote.swift
@@ -5,7 +5,7 @@
 
 extension AdocParser {
     // Quote (____) parsing with attribution
-    func parseQuote(it: inout TokenIter, env: AttrEnv) -> AdocQuote? {
+    func parseQuote(it: inout TokenIter, env: inout AttrEnv) -> AdocQuote? {
         guard let open = it.peek(),
               case .blockFence(let kind, let fenceLen) = open.kind,
               kind == .quote
@@ -28,7 +28,7 @@ extension AdocParser {
                 it.consume()
 
             default:
-                if let b = parseBlock(it: &it, env: env) {
+                if let b = parseBlock(it: &it, env: &env) {
                     blocks.append(b)
                 } else {
                     it.consume()
diff --git a/Sources/AsciiDocCore/Parser+Sections.swift b/Sources/AsciiDocCore/Parser+Sections.swift
index 3a37e31..d51eacd 100644
--- a/Sources/AsciiDocCore/Parser+Sections.swift
+++ b/Sources/AsciiDocCore/Parser+Sections.swift
@@ -9,7 +9,7 @@ extension AdocParser {
         level: Int,
         titleRange: Range<String.Index>,
         it: inout TokenIter,
-        env: AttrEnv
+        env: inout AttrEnv
     ) -> AdocSection? {
         // Consume the section title line
         it.consume()
@@ -23,7 +23,7 @@ extension AdocParser {
         titleText      = titleText.applyingAttributes(using: env)
 
         // Body: everything until we see a section with level <= this one
-        let bodyBlocks = parseBlocks(it: &it, env: env) { nextTok in
+        let bodyBlocks = parseBlocks(it: &it, env: &env) { nextTok in
             if case .atxSection(let nextLevel, _) = nextTok.kind {
                 return nextLevel <= level  // stop at same or higher ATX-level
             }
diff --git a/Sources/AsciiDocCore/Parser+Sidebar.swift b/Sources/AsciiDocCore/Parser+Sidebar.swift
index 10095b1..5d73751 100644
--- a/Sources/AsciiDocCore/Parser+Sidebar.swift
+++ b/Sources/AsciiDocCore/Parser+Sidebar.swift
@@ -6,7 +6,7 @@
 extension AdocParser {
     func parseSidebar(
         it: inout TokenIter,
-        env: AttrEnv
+        env: inout AttrEnv
     ) -> AdocSidebar? {
         guard let open = it.peek(),
               case .blockFence(let kind, let fenceLen) = open.kind,
@@ -16,7 +16,7 @@ extension AdocParser {
         it.consume() // consume opening fence
 
         // Parse inner blocks until we see a *matching* sidebar fence
-        let blocks = parseBlocks(it: &it, env: env) { tok in
+        let blocks = parseBlocks(it: &it, env: &env) { tok in
             if case .blockFence(let k, let l) = tok.kind,
                k == .sidebar, l == fenceLen {
                 return true
diff --git a/Sources/AsciiDocCore/Parser.swift b/Sources/AsciiDocCore/Parser.swift
index a8ab314..069ae92 100644
--- a/Sources/AsciiDocCore/Parser.swift
+++ b/Sources/AsciiDocCore/Parser.swift
@@ -254,7 +254,7 @@ public struct AdocParser: Sendable {
                 }
             }
         }
-        var env = AttrEnv(initial: docAttrs)
+        var env = AttrEnv(initial: docAttrs, typedAttributes: typedAttrs, xadOptions: xadOptions)
 
         // Header detection (keep your existing logic)
         detectHeader(
@@ -267,9 +267,13 @@ public struct AdocParser: Sendable {
             includeDerivedAttributes: includeHeaderDerivedAttributes,
             xadOptions: xadOptions
         )
+        docAttrs = env.values
+        typedAttrs = env.typedValues
 
         // Body blocks via parseBlocks
-        let bodyBlocks = parseBlocks(it: &it, env: env) { _ in false }
+        let bodyBlocks = parseBlocks(it: &it, env: &env) { _ in false }
+        docAttrs = env.values
+        typedAttrs = env.typedValues
 
         // Document span can still be computed from first/last token
         let docSpan: AdocRange? = {

From f821ec8224ced1c031a575ddb00d0184451041dd Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Fri, 27 Feb 2026 07:47:49 +0100
Subject: [PATCH 07/38] Implement get/set as well as tests for attr shorthand

---
 Sources/AsciiDocCore/Parser+Block.swift       | 11 +++--
 .../TypedAttributesTests.swift                | 44 +++++++++++++++++++
 2 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/Sources/AsciiDocCore/Parser+Block.swift b/Sources/AsciiDocCore/Parser+Block.swift
index 3afe537..da07510 100644
--- a/Sources/AsciiDocCore/Parser+Block.swift
+++ b/Sources/AsciiDocCore/Parser+Block.swift
@@ -430,7 +430,8 @@ extension AdocParser {
 
                  if name == "get", env.xadOptions.enabled {
                      let attrs = parseMacroAttributeList(payloadParts.body ?? "")
-                     if let path = attrs["path"] {
+                     let path = attrs["path"] ?? (payloadParts.target.isEmpty ? nil : payloadParts.target)
+                     if let path {
                          let join = attrs["join"]
                          let span = it.spanForLine(tok)
                          let text: String
@@ -454,9 +455,11 @@ extension AdocParser {
 
                  if name == "set", env.xadOptions.enabled {
                      let attrs = parseMacroAttributeList(payloadParts.body ?? "")
-                     if let path = attrs["path"] {
-                         let rawValue = attrs["value"] ?? ""
-                         env.applyAttributeSet(name: path, value: rawValue)
+                     let path = attrs["path"] ?? (payloadParts.target.isEmpty ? nil : payloadParts.target)
+                     if let path {
+                         let rawValue = attrs["value"] ?? payloadParts.body ?? ""
+                         let normalizedValue = normalizeXADAttributeValue(rawValue, xadOptions: env.xadOptions)
+                         env.applyAttributeSet(name: path, value: normalizedValue)
                          return nil
                      }
                  }
diff --git a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
index 65b196a..c9f5a04 100644
--- a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
+++ b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
@@ -125,6 +125,50 @@ import Testing
     }
 }
 
+@Test func typedAttributesGetMacroResolves() {
+    let source = """
+    :page: {size:"A4"}
+    get::page.size[]
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard case .paragraph(let para) = doc.blocks.first else {
+        Issue.record("Expected get macro to render as paragraph.")
+        return
+    }
+    #expect(para.text.plain == "A4")
+}
+
+@Test func typedAttributesSetMacroUpdatesValues() {
+    let source = """
+    set::page.size[Letter]
+    get::page.size[]
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard case .paragraph(let para) = doc.blocks.first else {
+        Issue.record("Expected get macro output after set macro.")
+        return
+    }
+    #expect(para.text.plain == "Letter")
+}
+
+@Test func typedAttributesResolveShorthandPath() {
+    let source = """
+    :page: {size:"A4"}
+    Size is {page.size}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard case .paragraph(let para) = doc.blocks.first else {
+        Issue.record("Expected paragraph with shorthand attribute.")
+        return
+    }
+    #expect(para.text.plain == "Size is A4")
+}
 
 @Test func typedAttributeParseMultilineAttr() {
     let source = """

From c62c4367034262bf8b862c06e646db94ddf6a47d Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Fri, 27 Feb 2026 07:51:53 +0100
Subject: [PATCH 08/38] Array indexing in attribute references

---
 Sources/AsciiDocCore/Attributes.swift         |  3 ++
 .../TypedAttributesTests.swift                | 31 +++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index 3b6b80f..a7c18ab 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -248,6 +248,9 @@ private func resolveBracketIndex(_ content: Substring, env: AttrEnv) -> String?
         let name = String(trimmed[start..<end])
         return env.resolveAttribute(name)
     }
+    if let resolved = env.resolveAttribute(String(trimmed)) {
+        return resolved
+    }
     return String(trimmed)
 }
 
diff --git a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
index c9f5a04..a18651d 100644
--- a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
+++ b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
@@ -170,6 +170,37 @@ import Testing
     #expect(para.text.plain == "Size is A4")
 }
 
+@Test func typedAttributesResolveArrayIndex() {
+    let source = """
+    :items: ["a", "b", "c"]
+    First is {items[0]}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard case .paragraph(let para) = doc.blocks.first else {
+        Issue.record("Expected paragraph with array index access.")
+        return
+    }
+    #expect(para.text.plain == "First is a")
+}
+
+@Test func typedAttributesResolveArrayIndexFromAttribute() {
+    let source = """
+    :items: ["a", "b", "c"]
+    :idx: 2
+    Value is {items[idx]}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard case .paragraph(let para) = doc.blocks.first else {
+        Issue.record("Expected paragraph with indexed attribute access.")
+        return
+    }
+    #expect(para.text.plain == "Value is c")
+}
+
 @Test func typedAttributeParseMultilineAttr() {
     let source = """
     :page: {

From 4784172939cc8cd8263aa5dd572326df4c3563c2 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 07:54:43 +0100
Subject: [PATCH 09/38] Add tests for path based overrides

---
 Sources/AsciiDocCore/Attributes.swift            | 13 ++++++++++++-
 .../AsciiDocCoreTests/TypedAttributesTests.swift | 16 ++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index a7c18ab..cb18bc2 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -113,7 +113,8 @@ package struct AttrEnv {
         guard xadOptions.enabled else { return }
         let rawValue = value ?? ""
         if isXADPathName(name) {
-            let typed = XADAttributeValue.parse(from: rawValue, xadOptions: xadOptions) ?? .string(rawValue)
+            let normalizedScalar = stripSurroundingQuotes(rawValue)
+            let typed = XADAttributeValue.parse(from: normalizedScalar, xadOptions: xadOptions) ?? .string(normalizedScalar)
             setTypedPath(name, value: typed)
             return
         }
@@ -254,6 +255,16 @@ private func resolveBracketIndex(_ content: Substring, env: AttrEnv) -> String?
     return String(trimmed)
 }
 
+private func stripSurroundingQuotes(_ value: String) -> String {
+    guard value.count >= 2 else { return value }
+    let first = value.first
+    let last = value.last
+    guard let first, let last, first == last, (first == "\"" || first == "'") else {
+        return value
+    }
+    return String(value.dropFirst().dropLast())
+}
+
 private extension AttrEnv {
     func resolveTypedPath(_ path: String) -> XADAttributeValue? {
         guard let segments = parseXADPathSegments(path, env: self), !segments.isEmpty else {
diff --git a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
index a18651d..3c9ace3 100644
--- a/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
+++ b/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
@@ -201,6 +201,22 @@ import Testing
     #expect(para.text.plain == "Value is c")
 }
 
+@Test func typedAttributesPathOverrideScalar() {
+    let source = """
+    :page: {size:"A4", margins:{top:"24mm", right:"22mm"}}
+    :page.margins.top: "18mm"
+    Top margin is {page.margins.top}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard case .paragraph(let para) = doc.blocks.first else {
+        Issue.record("Expected paragraph with path override.")
+        return
+    }
+    #expect(para.text.plain == "Top margin is 18mm")
+}
+
 @Test func typedAttributeParseMultilineAttr() {
     let source = """
     :page: {

From fdea142e84016e4e652172965b993b4cc2cab6e8 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 09:11:49 +0100
Subject: [PATCH 10/38] Implement scoped attributes

This commit implements scoped attributes,
as well as a new warning infrastructure that was needed to properly emit diagnostics.
---
 Sources/AsciiDocCore/Attributes.swift         |  20 ++
 Sources/AsciiDocCore/ISM.swift                |  13 +
 Sources/AsciiDocCore/Parser+Block.swift       | 242 +++++++++++++++++-
 Sources/AsciiDocCore/Parser+DList.swift       |   7 +-
 Sources/AsciiDocCore/Parser+Example.swift     |   5 +-
 Sources/AsciiDocCore/Parser+Header.swift      |  63 -----
 Sources/AsciiDocCore/Parser+Lists.swift       |   7 +-
 Sources/AsciiDocCore/Parser+Open.swift        |   5 +-
 Sources/AsciiDocCore/Parser+Paragraph.swift   |   6 +-
 Sources/AsciiDocCore/Parser+Quote.swift       |   4 +-
 Sources/AsciiDocCore/Parser+Sections.swift    |  48 +++-
 Sources/AsciiDocCore/Parser+Sidebar.swift     |   5 +-
 Sources/AsciiDocCore/Parser.swift             |   5 +-
 Sources/AsciiDocRender/FootnoteResolver.swift |   1 +
 .../ScopedAttributesTests.swift               | 150 +++++++++++
 15 files changed, 485 insertions(+), 96 deletions(-)
 create mode 100644 Tests/AsciiDocCoreTests/ScopedAttributesTests.swift

diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index cb18bc2..bb16c5d 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -92,8 +92,14 @@ package struct AttrEnv {
     // name → optional value (nil means unset)
     private(set) var values: [String: String?]
     private(set) var typedValues: [String: XADAttributeValue]
+    private var scopeStack: [ScopeSnapshot]
     let xadOptions: XADOptions
 
+    private struct ScopeSnapshot {
+        let values: [String: String?]
+        let typedValues: [String: XADAttributeValue]
+    }
+
     package init(
         initial: [String: String?] = [:],
         typedAttributes: [String: XADAttributeValue] = [:],
@@ -101,6 +107,7 @@ package struct AttrEnv {
     ) {
         self.values = initial
         self.typedValues = typedAttributes
+        self.scopeStack = []
         self.xadOptions = xadOptions
     }
 
@@ -108,6 +115,19 @@ package struct AttrEnv {
         values[name] = value
     }
 
+    mutating func pushScope() {
+        let snapshot = ScopeSnapshot(values: values, typedValues: typedValues)
+        scopeStack.append(snapshot)
+    }
+
+    @discardableResult
+    mutating func popScope() -> Bool {
+        guard let snapshot = scopeStack.popLast() else { return false }
+        values = snapshot.values
+        typedValues = snapshot.typedValues
+        return true
+    }
+
     mutating func applyAttributeSet(name: String, value: String?) {
         values[name] = value
         guard xadOptions.enabled else { return }
diff --git a/Sources/AsciiDocCore/ISM.swift b/Sources/AsciiDocCore/ISM.swift
index 3d865e7..9626ec1 100644
--- a/Sources/AsciiDocCore/ISM.swift
+++ b/Sources/AsciiDocCore/ISM.swift
@@ -395,13 +395,22 @@ public struct AdocHeader: Sendable, Equatable {
 
 }
 
+public struct AdocWarning: Sendable, Equatable {
+    public var message: String
+    public var span: AdocRange?
 
+    public init(message: String, span: AdocRange? = nil) {
+        self.message = message
+        self.span = span
+    }
+}
 
 public struct AdocDocument: Sendable, Equatable {
     public var attributes: [String: String?] = [:]
     public var typedAttributes: [String: XADAttributeValue] = [:]
     public var header: AdocHeader? = nil
     public var blocks: [AdocBlock] = []
+    public var warnings: [AdocWarning] = []
     public var span: AdocRange?
     public var xadOptions: XADOptions = .init()
 
@@ -410,6 +419,7 @@ public struct AdocDocument: Sendable, Equatable {
         typedAttributes: [String: XADAttributeValue] = [:],
         header: AdocHeader? = nil,
         blocks: [AdocBlock] = [],
+        warnings: [AdocWarning] = [],
         span: AdocRange? = nil,
         xadOptions: XADOptions = .init()
     ) {
@@ -417,6 +427,7 @@ public struct AdocDocument: Sendable, Equatable {
         self.typedAttributes = typedAttributes
         self.header = header
         self.blocks = blocks
+        self.warnings = warnings
         self.span = span
         self.xadOptions = xadOptions
     }
@@ -425,6 +436,7 @@ public struct AdocDocument: Sendable, Equatable {
         attributes: [String: String?] = [:],
         header: AdocHeader? = nil,
         blocks: [AdocBlock] = [],
+        warnings: [AdocWarning] = [],
         span: AdocRange? = nil,
         xadOptions: XADOptions = .init()
     ) {
@@ -433,6 +445,7 @@ public struct AdocDocument: Sendable, Equatable {
             typedAttributes: [:],
             header: header,
             blocks: blocks,
+            warnings: warnings,
             span: span,
             xadOptions: xadOptions
         )
diff --git a/Sources/AsciiDocCore/Parser+Block.swift b/Sources/AsciiDocCore/Parser+Block.swift
index da07510..0ffb053 100644
--- a/Sources/AsciiDocCore/Parser+Block.swift
+++ b/Sources/AsciiDocCore/Parser+Block.swift
@@ -5,7 +5,7 @@
 
 import Foundation
 
-private func parseDirectivePayload(_ payload: String) -> (target: String, body: String?) {
+func parseDirectivePayload(_ payload: String) -> (target: String, body: String?) {
     guard let open = payload.firstIndex(of: "["),
           let close = payload.lastIndex(of: "]"),
           close > open else {
@@ -25,7 +25,7 @@ private func parseDirectivePayload(_ payload: String) -> (target: String, body:
     )
 }
 
-private func parseMacroAttributeList(_ body: String) -> [String: String] {
+func parseMacroAttributeList(_ body: String) -> [String: String] {
     var result: [String: String] = [:]
     var current = ""
     var inQuotes = false
@@ -84,7 +84,7 @@ private func parseMacroAttributeList(_ body: String) -> [String: String] {
     return result
 }
 
-private func normalizeXADAttributeValue(_ value: String, xadOptions: XADOptions) -> String {
+func normalizeXADAttributeValue(_ value: String, xadOptions: XADOptions) -> String {
     guard xadOptions.enabled else { return value }
     var index = value.startIndex
     while index < value.endIndex, value[index].isWhitespace {
@@ -100,7 +100,7 @@ private func normalizeXADAttributeValue(_ value: String, xadOptions: XADOptions)
     return result
 }
 
-private func consumesMultilineJSON(_ value: String, xadOptions: XADOptions) -> Bool {
+func consumesMultilineJSON(_ value: String, xadOptions: XADOptions) -> Bool {
     guard xadOptions.enabled else { return false }
     var index = value.startIndex
     while index < value.endIndex, value[index].isWhitespace {
@@ -112,7 +112,7 @@ private func consumesMultilineJSON(_ value: String, xadOptions: XADOptions) -> B
     return !isJSONBalanced(value)
 }
 
-private func isJSONBalanced(_ value: String) -> Bool {
+func isJSONBalanced(_ value: String) -> Bool {
     var braceDepth = 0
     var bracketDepth = 0
     var inString = false
@@ -147,6 +147,83 @@ private func isJSONBalanced(_ value: String) -> Bool {
     return braceDepth <= 0 && bracketDepth <= 0 && !inString
 }
 
+func parseAttributeAssignmentsFromDelimitedBlock(
+    it: inout TokenIter,
+    xadOptions: XADOptions
+) -> [(name: String, value: String?, unset: Bool)]? {
+    guard let open = it.peek(), case .blockFence(let kind, _) = open.kind, kind == .listing else {
+        return nil
+    }
+    it.consume()
+
+    var lines: [String] = []
+    while let tok = it.peek() {
+        if case .blockFence(let kind, _) = tok.kind, kind == .listing {
+            it.consume()
+            break
+        }
+        lines.append(it.rawLineText(of: tok))
+        it.consume()
+    }
+
+    return parseAttributeAssignmentsFromLines(lines, xadOptions: xadOptions)
+}
+
+func parseAttributeAssignmentsFromLines(
+    _ lines: [String],
+    xadOptions: XADOptions
+) -> [(name: String, value: String?, unset: Bool)] {
+    var assignments: [(name: String, value: String?, unset: Bool)] = []
+    var index = 0
+
+    while index < lines.count {
+        let rawLine = lines[index]
+        let trimmed = rawLine.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmed.hasPrefix(":") {
+            index += 1
+            continue
+        }
+        let nameStart = trimmed.index(after: trimmed.startIndex)
+        guard let nameEnd = trimmed[nameStart...].firstIndex(of: ":") else {
+            index += 1
+            continue
+        }
+        var name = String(trimmed[nameStart..<nameEnd]).trimmingCharacters(in: .whitespacesAndNewlines)
+        var value = String(trimmed[trimmed.index(after: nameEnd)...]).trimmingCharacters(in: .whitespacesAndNewlines)
+        var unset = false
+
+        if name.hasSuffix("!") && value.isEmpty {
+            unset = true
+            name = String(name.dropLast())
+        }
+
+        if !value.isEmpty {
+            value = normalizeXADAttributeValue(value, xadOptions: xadOptions)
+            if consumesMultilineJSON(value, xadOptions: xadOptions) {
+                var merged = value
+                var nextIndex = index + 1
+                while nextIndex < lines.count, consumesMultilineJSON(merged, xadOptions: xadOptions) {
+                    merged.append("\n")
+                    merged.append(lines[nextIndex])
+                    nextIndex += 1
+                }
+                value = merged
+                index = nextIndex
+            } else {
+                index += 1
+            }
+        } else {
+            index += 1
+        }
+
+        if !name.isEmpty {
+            assignments.append((name: name, value: value.isEmpty ? "" : value, unset: unset))
+        }
+    }
+
+    return assignments
+}
+
 private func consumeAttributeMultilineJSON(
     initial: String,
     it: inout TokenIter,
@@ -175,6 +252,7 @@ extension AdocParser {
     func parseBlocks(
         it: inout TokenIter,
         env: inout AttrEnv,
+        warnings: inout [AdocWarning],
         stop: (Token) -> Bool
     ) -> [AdocBlock] {
         var blocks: [AdocBlock] = []
@@ -183,7 +261,7 @@ extension AdocParser {
             let before = it.index
 
 
-            if let block = parseBlock(it: &it, env: &env) {
+            if let block = parseBlock(it: &it, env: &env, warnings: &warnings) {
                 blocks.append(block)
             } else {
                 // Safety to avoid infinite loops: always consume something.
@@ -196,15 +274,67 @@ extension AdocParser {
         }
         return blocks
     }
+
+    func applyAttributeAssignments(
+        _ assignments: [(name: String, value: String?, unset: Bool)],
+        env: inout AttrEnv
+    ) {
+        for assignment in assignments {
+            if assignment.unset {
+                env.applyAttributeUnset(name: assignment.name)
+                continue
+            }
+            let rawValue = assignment.value
+            let normalized = rawValue.map { normalizeXADAttributeValue($0, xadOptions: env.xadOptions) }
+            env.applyAttributeSet(name: assignment.name, value: normalized)
+        }
+    }
+
+    private func parseBlockWithScopedAttributes(
+        _ assignments: [(name: String, value: String?, unset: Bool)],
+        it: inout TokenIter,
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        warningSpan: AdocRange?
+    ) -> AdocBlock? {
+        while let next = it.peek(), case .blank = next.kind {
+            it.consume()
+        }
+
+        env.pushScope()
+        applyAttributeAssignments(assignments, env: &env)
+        let block = parseBlock(it: &it, env: &env, warnings: &warnings)
+        _ = env.popScope()
+        if block == nil, env.xadOptions.enabled {
+            warnings.append(
+                AdocWarning(
+                    message: "blockattr has no following block to apply to.",
+                    span: warningSpan
+                )
+            )
+        }
+        return block
+    }
+
     func parseBlock(
         it: inout TokenIter,
-        env: inout AttrEnv
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning]
     ) -> AdocBlock? {
         // Slurp block metadata (ID, roles, options, attributes, title, span)
         let meta = consumeBlockMeta(it: &it, env: env)
 
         guard let tok = it.peek() else { return nil }
 
+        if env.xadOptions.enabled, meta.primaryStyle == "attrs" {
+            warnings.append(
+                AdocWarning(
+                    message: "attrs is only valid immediately after a section title.",
+                    span: meta.span
+                )
+            )
+        }
+
         if case .attrSet(let nameR, let valueR) = tok.kind {
             let name = it.textFromRelative(range: nameR, token: tok)
             var value = valueR.map { it.textFromRelative(range: $0, token: tok) }
@@ -230,13 +360,25 @@ extension AdocParser {
             return nil
         }
 
+        if meta.primaryStyle == "blockattr" {
+            if let assignments = parseAttributeAssignmentsFromDelimitedBlock(it: &it, xadOptions: env.xadOptions) {
+                return parseBlockWithScopedAttributes(
+                    assignments,
+                    it: &it,
+                    env: &env,
+                    warnings: &warnings,
+                    warningSpan: meta.span
+                )
+            }
+        }
+
         var inner: AdocBlock?
 
         // Lists / DLists: handled up front, since they consume multiple lines
         switch tok.kind {
         case .atxSection(let level, let titleRange):
             if let section = parseSection(from: tok, level: level, titleRange: titleRange,
-                                          it: &it, env: &env) {
+                                          it: &it, env: &env, warnings: &warnings) {
                 var block = AdocBlock.section(section)
                 meta.applyMeta(to: &block)
                 return block;
@@ -252,6 +394,7 @@ extension AdocParser {
                     listKind: listKind,
                     it: &it,
                     env: &env,
+                    warnings: &warnings,
                     stack: &stack,
                     bibliographyStyle: isBibliography
                 ) {
@@ -271,6 +414,7 @@ extension AdocParser {
                     for: marker,
                     it: &it,
                     env: &env,
+                    warnings: &warnings,
                     stack: &stack
                 ) {
                     inner = .dlist(dlist)
@@ -333,12 +477,12 @@ extension AdocParser {
                 }
 
             case .quote:
-                if let q = parseQuote(it: &it, env: &env) {
+                if let q = parseQuote(it: &it, env: &env, warnings: &warnings) {
                     inner = .quote(q)
                 }
 
             case .verseBlock:
-                if let q = parseQuote(it: &it, env: &env) {
+                if let q = parseQuote(it: &it, env: &env, warnings: &warnings) {
                     let span = combinedSpan(metaSpan: meta.span, innerSpan: q.span)
                     let verse = AdocVerse(
                         text: nil,
@@ -372,17 +516,17 @@ extension AdocParser {
                 }
 
             case .sidebar:
-                if let s = parseSidebar(it: &it, env: &env) {
+                if let s = parseSidebar(it: &it, env: &env, warnings: &warnings) {
                     inner = .sidebar(s)
                 }
 
             case .example:
-                if let e = parseExample(it: &it, env: &env) {
+                if let e = parseExample(it: &it, env: &env, warnings: &warnings) {
                     inner = .example(e)
                 }
 
             case .open:
-                if let o = parseOpen(it: &it, env: &env) {
+                if let o = parseOpen(it: &it, env: &env, warnings: &warnings) {
                     inner = .open(o)
                 }
 
@@ -409,6 +553,16 @@ extension AdocParser {
                  let payload = String(tok.string[payloadRange])
                  let payloadParts = parseDirectivePayload(payload)
 
+                 if name == "attrs", env.xadOptions.enabled {
+                     warnings.append(
+                         AdocWarning(
+                             message: "attrs is only valid immediately after a section title.",
+                             span: it.spanForLine(tok)
+                         )
+                     )
+                     return nil
+                 }
+
                  let targetForMath = payloadParts.target.isEmpty ? nil : payloadParts.target
                  if let mathKind = AdocMathKind(macroName: name),
                     let mathBody = payloadParts.body ?? targetForMath,
@@ -428,6 +582,68 @@ extension AdocParser {
                      break
                  }
 
+                 if name == "attrpush", env.xadOptions.enabled {
+                     let attrs = parseMacroAttributeList(payloadParts.body ?? "")
+                     env.pushScope()
+                     applyAttributeAssignments(
+                         attrs.map { (name: $0.key, value: $0.value, unset: false) },
+                         env: &env
+                     )
+                     return nil
+                 }
+
+                 if name == "attrpop", env.xadOptions.enabled {
+                     let popped = env.popScope()
+                     if !popped {
+                         warnings.append(
+                             AdocWarning(
+                                 message: "attrpop without a matching attrpush.",
+                                 span: it.spanForLine(tok)
+                             )
+                         )
+                     }
+                     return nil
+                 }
+
+                 if name == "blockattr", env.xadOptions.enabled {
+                     var merged: [String: String] = parseMacroAttributeList(payloadParts.body ?? "")
+
+                     while let nextTok = it.peek() {
+                         if case .blank = nextTok.kind {
+                             it.consume()
+                             continue
+                         }
+                         guard case .directive(let nextKind, let nextPayloadRange) = nextTok.kind else {
+                             break
+                         }
+                         let nextName: String = {
+                             switch nextKind {
+                             case .include: return "include"
+                             case .ifdef: return "ifdef"
+                             case .ifndef: return "ifndef"
+                             case .ifeval: return "ifeval"
+                             case .endif: return "endif"
+                             case .other(let n): return n
+                             }
+                         }()
+                         guard nextName == "blockattr" else { break }
+                         it.consume()
+                         let nextPayload = String(nextTok.string[nextPayloadRange])
+                         let nextParts = parseDirectivePayload(nextPayload)
+                         let nextAttrs = parseMacroAttributeList(nextParts.body ?? "")
+                         for (k, v) in nextAttrs { merged[k] = v }
+                     }
+
+                     let assignments = merged.map { (name: $0.key, value: $0.value, unset: false) }
+                     return parseBlockWithScopedAttributes(
+                         assignments,
+                         it: &it,
+                         env: &env,
+                         warnings: &warnings,
+                         warningSpan: it.spanForLine(tok)
+                     )
+                 }
+
                  if name == "get", env.xadOptions.enabled {
                      let attrs = parseMacroAttributeList(payloadParts.body ?? "")
                      let path = attrs["path"] ?? (payloadParts.target.isEmpty ? nil : payloadParts.target)
diff --git a/Sources/AsciiDocCore/Parser+DList.swift b/Sources/AsciiDocCore/Parser+DList.swift
index c2ed0ad..3d07547 100644
--- a/Sources/AsciiDocCore/Parser+DList.swift
+++ b/Sources/AsciiDocCore/Parser+DList.swift
@@ -97,6 +97,7 @@ extension AdocParser {
         for marker: String,
         it: inout TokenIter,
         env: inout AttrEnv,
+        warnings: inout [AdocWarning],
         stack: inout [String]
     ) -> AdocDList? {
         stack.append(marker)
@@ -139,7 +140,7 @@ extension AdocParser {
 
                 // New marker not in any outer level → nested dlist under last item
                 if var lastItem = items.popLast() {
-                    if let nested = parseDList(for: thisMarker, it: &it, env: &env, stack: &stack) {
+                    if let nested = parseDList(for: thisMarker, it: &it, env: &env, warnings: &warnings, stack: &stack) {
                         lastItem.blocks.append(.dlist(nested))
                     }
                     items.append(lastItem)
@@ -167,12 +168,12 @@ extension AdocParser {
                         let line       = nextTok.string
                         let thisMarker = String(line[sepRange])
 
-                        if let nested = parseDList(for: thisMarker, it: &it, env: &env, stack: &stack) {
+                        if let nested = parseDList(for: thisMarker, it: &it, env: &env, warnings: &warnings, stack: &stack) {
                             lastItem.blocks.append(.dlist(nested))
                         }
 
                     default:
-                        if let nestedBlock = parseBlock(it: &it, env: &env) {
+                        if let nestedBlock = parseBlock(it: &it, env: &env, warnings: &warnings) {
                             lastItem.blocks.append(nestedBlock)
                         }
                     }
diff --git a/Sources/AsciiDocCore/Parser+Example.swift b/Sources/AsciiDocCore/Parser+Example.swift
index 4d12d3f..17e8c7d 100644
--- a/Sources/AsciiDocCore/Parser+Example.swift
+++ b/Sources/AsciiDocCore/Parser+Example.swift
@@ -6,7 +6,8 @@
 extension AdocParser {
     func parseExample(
         it: inout TokenIter,
-        env: inout AttrEnv
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning]
     ) -> AdocExample? {
         // We expect the current token to be an example fence
         guard let open = it.peek(),
@@ -20,7 +21,7 @@ extension AdocParser {
         it.consume()
 
         // Parse inner blocks until we see a matching example fence
-        let innerBlocks: [AdocBlock] = parseBlocks(it: &it, env: &env) { tok in
+        let innerBlocks: [AdocBlock] = parseBlocks(it: &it, env: &env, warnings: &warnings) { tok in
             if case .blockFence(let k, let l) = tok.kind,
                k == .example, l == fenceLen {
                 return true   // stop before this token
diff --git a/Sources/AsciiDocCore/Parser+Header.swift b/Sources/AsciiDocCore/Parser+Header.swift
index a210895..3ec898e 100644
--- a/Sources/AsciiDocCore/Parser+Header.swift
+++ b/Sources/AsciiDocCore/Parser+Header.swift
@@ -264,69 +264,6 @@ private func consumeAttributeContinuation(
     return result
 }
 
-private func normalizeXADAttributeValue(_ value: String, xadOptions: XADOptions) -> String {
-    guard xadOptions.enabled else { return value }
-    var index = value.startIndex
-    while index < value.endIndex, value[index].isWhitespace {
-        index = value.index(after: index)
-    }
-    guard index < value.endIndex, value[index] == "\\" else { return value }
-    let nextIndex = value.index(after: index)
-    guard nextIndex < value.endIndex else { return value }
-    let nextChar = value[nextIndex]
-    guard nextChar == "{" || nextChar == "[" else { return value }
-    var result = value
-    result.remove(at: index)
-    return result
-}
-
-private func consumesMultilineJSON(_ value: String, xadOptions: XADOptions) -> Bool {
-    guard xadOptions.enabled else { return false }
-    var index = value.startIndex
-    while index < value.endIndex, value[index].isWhitespace {
-        index = value.index(after: index)
-    }
-    guard index < value.endIndex else { return false }
-    let lead = value[index]
-    guard lead == "{" || lead == "[" else { return false }
-    return !isJSONBalanced(value)
-}
-
-private func isJSONBalanced(_ value: String) -> Bool {
-    var braceDepth = 0
-    var bracketDepth = 0
-    var inString = false
-    var escapeNext = false
-
-    for ch in value {
-        if inString {
-            if escapeNext {
-                escapeNext = false
-                continue
-            }
-            if ch == "\\" {
-                escapeNext = true
-                continue
-            }
-            if ch == "\"" {
-                inString = false
-            }
-            continue
-        }
-
-        if ch == "\"" {
-            inString = true
-            continue
-        }
-        if ch == "{" { braceDepth += 1 }
-        else if ch == "}" { braceDepth -= 1 }
-        else if ch == "[" { bracketDepth += 1 }
-        else if ch == "]" { bracketDepth -= 1 }
-    }
-
-    return braceDepth <= 0 && bracketDepth <= 0 && !inString
-}
-
 private func consumeAttributeMultilineJSON(
     initial: String,
     it: inout TokenIter,
diff --git a/Sources/AsciiDocCore/Parser+Lists.swift b/Sources/AsciiDocCore/Parser+Lists.swift
index ca79e5c..88b030c 100644
--- a/Sources/AsciiDocCore/Parser+Lists.swift
+++ b/Sources/AsciiDocCore/Parser+Lists.swift
@@ -232,6 +232,7 @@ extension AdocParser {
         listKind: AdocListKind,
         it: inout TokenIter,
         env: inout AttrEnv,
+        warnings: inout [AdocWarning],
         stack: inout [ListMarkerKey],
         bibliographyStyle: Bool = false
     ) -> AdocList? {
@@ -284,6 +285,7 @@ extension AdocParser {
                         listKind: inferredListKind(from: key),
                         it: &it,
                         env: &env,
+                        warnings: &warnings,
                         stack: &stack,
                         bibliographyStyle: false
                     ) {
@@ -319,6 +321,7 @@ extension AdocParser {
                                 listKind: inferredListKind(from: key),
                                 it: &it,
                                 env: &env,
+                                warnings: &warnings,
                                 stack: &stack,
                                 bibliographyStyle: false
                             ) {
@@ -326,13 +329,13 @@ extension AdocParser {
                             }
                         } else {
                             // Invalid list marker; fall back to generic block parsing
-                            if let block = parseBlock(it: &it, env: &env) {
+                            if let block = parseBlock(it: &it, env: &env, warnings: &warnings) {
                                 lastItem.blocks.append(block)
                             }
                         }
 
                     default:
-                        if let block = parseBlock(it: &it, env: &env) {
+                        if let block = parseBlock(it: &it, env: &env, warnings: &warnings) {
                             lastItem.blocks.append(block)
                         }
                     }
diff --git a/Sources/AsciiDocCore/Parser+Open.swift b/Sources/AsciiDocCore/Parser+Open.swift
index fd15093..3adaece 100644
--- a/Sources/AsciiDocCore/Parser+Open.swift
+++ b/Sources/AsciiDocCore/Parser+Open.swift
@@ -6,7 +6,8 @@
 extension AdocParser {
     func parseOpen(
         it: inout TokenIter,
-        env: inout AttrEnv
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning]
     ) -> AdocOpen? {
         guard let open = it.peek(),
               case .blockFence(let kind, let fenceLen) = open.kind,
@@ -29,7 +30,7 @@ extension AdocParser {
                 it.consume()
 
             default:
-                if let b = parseBlock(it: &it, env: &env) {
+                if let b = parseBlock(it: &it, env: &env, warnings: &warnings) {
                     blocks.append(b)
                 } else {
                     it.consume()
diff --git a/Sources/AsciiDocCore/Parser+Paragraph.swift b/Sources/AsciiDocCore/Parser+Paragraph.swift
index f43bb45..a8f761c 100644
--- a/Sources/AsciiDocCore/Parser+Paragraph.swift
+++ b/Sources/AsciiDocCore/Parser+Paragraph.swift
@@ -10,9 +10,9 @@ extension AdocParser {
     ) -> AdocParagraph? {
         guard let first = it.peek() else { return nil }
 
-        // Paragraphs start only on plain text / directive lines.
+        // Paragraphs start only on plain text lines.
         switch first.kind {
-        case .text, .directive:
+        case .text:
             break
         default:
             return nil
@@ -23,7 +23,7 @@ extension AdocParser {
 
         while let t = it.peek() {
             switch t.kind {
-            case .text, .directive:
+            case .text:
                 lines.append(it.contentText(of: t))
                 lastTok = t
                 it.consume()
diff --git a/Sources/AsciiDocCore/Parser+Quote.swift b/Sources/AsciiDocCore/Parser+Quote.swift
index 62e2c83..84f4ee7 100644
--- a/Sources/AsciiDocCore/Parser+Quote.swift
+++ b/Sources/AsciiDocCore/Parser+Quote.swift
@@ -5,7 +5,7 @@
 
 extension AdocParser {
     // Quote (____) parsing with attribution
-    func parseQuote(it: inout TokenIter, env: inout AttrEnv) -> AdocQuote? {
+    func parseQuote(it: inout TokenIter, env: inout AttrEnv, warnings: inout [AdocWarning]) -> AdocQuote? {
         guard let open = it.peek(),
               case .blockFence(let kind, let fenceLen) = open.kind,
               kind == .quote
@@ -28,7 +28,7 @@ extension AdocParser {
                 it.consume()
 
             default:
-                if let b = parseBlock(it: &it, env: &env) {
+                if let b = parseBlock(it: &it, env: &env, warnings: &warnings) {
                     blocks.append(b)
                 } else {
                     it.consume()
diff --git a/Sources/AsciiDocCore/Parser+Sections.swift b/Sources/AsciiDocCore/Parser+Sections.swift
index d51eacd..b1c85eb 100644
--- a/Sources/AsciiDocCore/Parser+Sections.swift
+++ b/Sources/AsciiDocCore/Parser+Sections.swift
@@ -9,7 +9,8 @@ extension AdocParser {
         level: Int,
         titleRange: Range<String.Index>,
         it: inout TokenIter,
-        env: inout AttrEnv
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning]
     ) -> AdocSection? {
         // Consume the section title line
         it.consume()
@@ -22,14 +23,57 @@ extension AdocParser {
         var titleText  = AdocText(plain: String(titleSlice), span: titleSpan)
         titleText      = titleText.applyingAttributes(using: env)
 
+        var scopedAssignments: [(name: String, value: String?, unset: Bool)]? = nil
+
+        if let nextTok = it.peek() {
+            switch nextTok.kind {
+            case .blockMeta:
+                var meta = AdocBlockMeta()
+                meta.mergeBlockMeta(from: nextTok)
+                if meta.primaryStyle == "attrs" {
+                    it.consume()
+                    scopedAssignments = parseAttributeAssignmentsFromDelimitedBlock(it: &it, xadOptions: env.xadOptions)
+                }
+            case .directive(let kind, let payloadRange):
+                let name: String = {
+                    switch kind {
+                    case .include: return "include"
+                    case .ifdef: return "ifdef"
+                    case .ifndef: return "ifndef"
+                    case .ifeval: return "ifeval"
+                    case .endif: return "endif"
+                    case .other(let n): return n
+                    }
+                }()
+                if name == "attrs" {
+                    it.consume()
+                    let payload = String(nextTok.string[payloadRange])
+                    let payloadParts = parseDirectivePayload(payload)
+                    let attrs = parseMacroAttributeList(payloadParts.body ?? "")
+                    scopedAssignments = attrs.map { (name: $0.key, value: $0.value, unset: false) }
+                }
+            default:
+                break
+            }
+        }
+
+        if let scopedAssignments {
+            env.pushScope()
+            applyAttributeAssignments(scopedAssignments, env: &env)
+        }
+
         // Body: everything until we see a section with level <= this one
-        let bodyBlocks = parseBlocks(it: &it, env: &env) { nextTok in
+        let bodyBlocks = parseBlocks(it: &it, env: &env, warnings: &warnings) { nextTok in
             if case .atxSection(let nextLevel, _) = nextTok.kind {
                 return nextLevel <= level  // stop at same or higher ATX-level
             }
             return false
         }
 
+        if scopedAssignments != nil {
+            _ = env.popScope()
+        }
+
         // Span from this section line to last block’s end (or just the title line if empty)
         let endRange: AdocRange = {
             if let lastBlock = bodyBlocks.last {
diff --git a/Sources/AsciiDocCore/Parser+Sidebar.swift b/Sources/AsciiDocCore/Parser+Sidebar.swift
index 5d73751..e270e48 100644
--- a/Sources/AsciiDocCore/Parser+Sidebar.swift
+++ b/Sources/AsciiDocCore/Parser+Sidebar.swift
@@ -6,7 +6,8 @@
 extension AdocParser {
     func parseSidebar(
         it: inout TokenIter,
-        env: inout AttrEnv
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning]
     ) -> AdocSidebar? {
         guard let open = it.peek(),
               case .blockFence(let kind, let fenceLen) = open.kind,
@@ -16,7 +17,7 @@ extension AdocParser {
         it.consume() // consume opening fence
 
         // Parse inner blocks until we see a *matching* sidebar fence
-        let blocks = parseBlocks(it: &it, env: &env) { tok in
+        let blocks = parseBlocks(it: &it, env: &env, warnings: &warnings) { tok in
             if case .blockFence(let k, let l) = tok.kind,
                k == .sidebar, l == fenceLen {
                 return true
diff --git a/Sources/AsciiDocCore/Parser.swift b/Sources/AsciiDocCore/Parser.swift
index 069ae92..01de431 100644
--- a/Sources/AsciiDocCore/Parser.swift
+++ b/Sources/AsciiDocCore/Parser.swift
@@ -255,6 +255,7 @@ public struct AdocParser: Sendable {
             }
         }
         var env = AttrEnv(initial: docAttrs, typedAttributes: typedAttrs, xadOptions: xadOptions)
+        var warnings: [AdocWarning] = []
 
         // Header detection (keep your existing logic)
         detectHeader(
@@ -271,7 +272,7 @@ public struct AdocParser: Sendable {
         typedAttrs = env.typedValues
 
         // Body blocks via parseBlocks
-        let bodyBlocks = parseBlocks(it: &it, env: &env) { _ in false }
+        let bodyBlocks = parseBlocks(it: &it, env: &env, warnings: &warnings) { _ in false }
         docAttrs = env.values
         typedAttrs = env.typedValues
 
@@ -281,7 +282,7 @@ public struct AdocParser: Sendable {
             return AdocRange(start: first.range.start, end: last.range.end)
         }()
 
-        return AdocDocument(attributes: docAttrs, typedAttributes: typedAttrs, header: header, blocks: bodyBlocks, span: docSpan, xadOptions: xadOptions)
+        return AdocDocument(attributes: docAttrs, typedAttributes: typedAttrs, header: header, blocks: bodyBlocks, warnings: warnings, span: docSpan, xadOptions: xadOptions)
     }
 
 
diff --git a/Sources/AsciiDocRender/FootnoteResolver.swift b/Sources/AsciiDocRender/FootnoteResolver.swift
index fa8559e..4b0a316 100644
--- a/Sources/AsciiDocRender/FootnoteResolver.swift
+++ b/Sources/AsciiDocRender/FootnoteResolver.swift
@@ -37,6 +37,7 @@ public final class FootnoteResolver {
             typedAttributes: document.typedAttributes,
             header: document.header,
             blocks: newBlocks,
+            warnings: document.warnings,
             span: document.span,
             xadOptions: document.xadOptions
         )
diff --git a/Tests/AsciiDocCoreTests/ScopedAttributesTests.swift b/Tests/AsciiDocCoreTests/ScopedAttributesTests.swift
new file mode 100644
index 0000000..00be11c
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/ScopedAttributesTests.swift
@@ -0,0 +1,150 @@
+import Testing
+@testable import AsciiDocCore
+
+@Test func scopedAttributesPushPopRestoresValues() {
+    var env = AttrEnv(initial: ["role": "base"], typedAttributes: [:], xadOptions: .init(enabled: true))
+    env.applyAttributeSet(name: "page.margins.top", value: "24mm")
+
+    env.pushScope()
+    env.applyAttributeSet(name: "role", value: "compact")
+    env.applyAttributeSet(name: "page.margins.top", value: "18mm")
+
+    #expect(env.resolveAttribute("role") == "compact")
+    #expect(env.resolveAttribute("page.margins.top") == "18mm")
+
+    let popped = env.popScope()
+    #expect(popped == true)
+    #expect(env.resolveAttribute("role") == "base")
+    #expect(env.resolveAttribute("page.margins.top") == "24mm")
+}
+
+@Test func scopedAttributesPopUnderflowReturnsFalse() {
+    var env = AttrEnv()
+    let popped = env.popScope()
+    #expect(popped == false)
+}
+@Test func blockattrDirectiveAppliesToNextBlockOnly() {
+    let source = """
+    blockattr::[foo=bar]
+    {foo}
+    {foo}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    let paras = doc.blocks.compactMap { if case .paragraph(let p) = $0 { return p.text.plain } else { return nil } }
+    #expect(paras.count == 1)
+    #expect(paras.first == "bar\nbar")
+}
+
+@Test func attrpushPopScopesAttributes() {
+    let source = """
+    :foo: base
+    attrpush::[foo=inner]
+    {foo}
+    attrpop::[]
+    {foo}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    let paras = doc.blocks.compactMap { if case .paragraph(let p) = $0 { return p.text.plain } else { return nil } }
+    #expect(paras.count == 2)
+    #expect(paras.first == "inner")
+    #expect(paras.last == "base")
+}
+
+@Test func attrsDirectiveScopesSection() {
+    let source = """
+    == A
+    attrs::[foo=bar]
+    {foo}
+
+    == B
+    {foo}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard case .section(let firstSection) = doc.blocks.first else {
+        Issue.record("Expected first block to be a section.")
+        return
+    }
+    let firstParas = firstSection.blocks.compactMap { if case .paragraph(let p) = $0 { return p.text.plain } else { return nil } }
+    #expect(firstParas.first == "bar")
+
+    guard doc.blocks.count > 1, case .section(let secondSection) = doc.blocks[1] else {
+        Issue.record("Expected second block to be a section.")
+        return
+    }
+    let secondParas = secondSection.blocks.compactMap { if case .paragraph(let p) = $0 { return p.text.plain } else { return nil } }
+    #expect(secondParas.first == "{foo}")
+}
+
+@Test func blockattrBlockFormAppliesToNextBlock() {
+    let source = """
+    [blockattr]
+    ----
+    :foo: bar
+    ----
+    {foo}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    guard case .paragraph(let para) = doc.blocks.first else {
+        Issue.record("Expected paragraph output.")
+        return
+    }
+    #expect(para.text.plain == "bar")
+}
+
+@Test func blockattrTypedPathOverrideAppliesToNextBlock() {
+    let source = """
+    :page: {margins:{top:"24mm"}}
+    [blockattr]
+    ----
+    :page.margins.top: "18mm"
+    ----
+    {page.margins.top}
+    {page.margins.top}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    let paras = doc.blocks.compactMap { if case .paragraph(let p) = $0 { return p.text.plain } else { return nil } }
+    #expect(paras.count == 1)
+    #expect(paras.first == "18mm\n18mm")
+}
+
+@Test func attrsDirectiveOutsideSectionEmitsWarning() {
+    let source = """
+    attrs::[foo=bar]
+    {foo}
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    #expect(doc.warnings.contains { $0.message.contains("attrs") })
+}
+
+@Test func attrpopUnderflowEmitsWarning() {
+    let source = """
+    attrpop::[]
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    #expect(doc.warnings.contains { $0.message.contains("attrpop") })
+}
+
+@Test func blockattrWithoutFollowingBlockEmitsWarning() {
+    let source = """
+    blockattr::[foo=bar]
+    """
+    let parser = AdocParser()
+    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
+
+    #expect(doc.warnings.contains { $0.message.contains("blockattr") })
+}
+

From 0f963f1e8945235050411125ea9b337aefeb1ff1 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 09:15:24 +0100
Subject: [PATCH 11/38] Update readme

---
 README.adoc | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.adoc b/README.adoc
index 13edbf1..96e8ea6 100644
--- a/README.adoc
+++ b/README.adoc
@@ -2,6 +2,27 @@
 
 A swift implementation of AsciiDoc
 
+== XAD Overview
+
+XAD is an opt-in set of extensions that adds structured, JSON-like attributes and layout helpers for paged media output.
+Enable it by passing the `--xad` flag or by using a backend that requires XAD.
+
+Current additions include:
+
+* Typed attributes parsed from JSON/JSON5 values (dictionaries and arrays) in header attribute entries.
+* Multi-line JSON/JSON5 attribute values without explicit continuation escapes.
+* Attribute accessors for nested values (e.g. `foo.bar` and bracket indexing).
+* XAD access macros for nested values (`get::path[]` and `set::path[value]`), plus shorthand access with `{foo.bar}`.
+* Layout-oriented attributes intended for paged and PDF-style renderers.
+* Scoped attributes for block- and section-level overrides.
+
+Scoped attributes:
+
+* `attrpush::[]` and `attrpop::[]` push/pop the attribute environment.
+* `blockattr::[foo=bar]` applies attributes to the next block only.
+* `[blockattr]` followed by a listing-style block of `:name:` entries applies to the next block only.
+* `attrs::[foo=bar]` (or `[attrs]` + listing block) immediately after a section title scopes attributes to that section.
+
 == License
 
 Licensed under the Apache License, Version 2.0.

From d90785997ad8039390fb25fd285a4afaa93a82d5 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 09:26:17 +0100
Subject: [PATCH 12/38] Eliminate several Apple specific dependencies

---
 Sources/AsciiDocCore/Attributes.swift | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index bb16c5d..ec1a2a5 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -54,12 +54,15 @@ public enum XADAttributeValue: Sendable, Equatable {
             return .array(mapped)
         case let str as String:
             return .string(str)
-        case let num as NSNumber:
-            if CFGetTypeID(num) == CFBooleanGetTypeID() {
-                return .bool(num.boolValue)
-            }
-            return .number(num.doubleValue)
-        case _ as NSNull:
+        case let bool as Bool:
+            return .bool(bool)
+        case let int as Int:
+            return .number(Double(int))
+        case let double as Double:
+            return .number(double)
+        case let float as Float:
+            return .number(Double(float))
+        case is NSNull:
             return .null
         default:
             return nil

From e9c96eab16393c186c985ded05f82c6ab764155d Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 09:46:15 +0100
Subject: [PATCH 13/38] Fix JSON5 handling by switching ty YYJson

---
 Package.resolved                      | 11 ++++++++++-
 Package.swift                         |  5 ++++-
 Sources/AsciiDocCore/Attributes.swift | 14 +++++++-------
 3 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/Package.resolved b/Package.resolved
index e743f7d..d8775f0 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,5 +1,5 @@
 {
-  "originHash" : "c6ea4512e1e16b3ab843cc12fd09fe4f7046ae7901467803dc11fdd59feafad2",
+  "originHash" : "8b4f0636246db8e20a2d4049f8c471fde2c5538e097f97a2b517e4848503f9d7",
   "pins" : [
     {
       "identity" : "pathkit",
@@ -81,6 +81,15 @@
         "branch" : "main",
         "revision" : "cc57a1b3f850ddbbd3848fb422addada324fab9b"
       }
+    },
+    {
+      "identity" : "swift-yyjson",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/mattt/swift-yyjson.git",
+      "state" : {
+        "revision" : "6514373242de8a0765556dc54efdfd8a9567d71a",
+        "version" : "0.5.0"
+      }
     }
   ],
   "version" : 3
diff --git a/Package.swift b/Package.swift
index 48fab83..e2e27fe 100644
--- a/Package.swift
+++ b/Package.swift
@@ -28,12 +28,15 @@ let package = Package(
         .package(url: "https://github.com/openorbit/swift-hunspell", branch: "main"),
         .package(url: "https://github.com/openorbit/swift-yaml", branch: "main"),
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+        .package(url: "https://github.com/mattt/swift-yyjson.git", from: "0.5.0"),
     ],
     targets: [
         // Core parsing/semantic engine (Foundation + RegexBuilder only)
         .target(
             name: "AsciiDocCore",
-            dependencies: [],
+            dependencies: [
+                .product(name: "YYJSON", package: "swift-yyjson")
+            ],
             path: "Sources/AsciiDocCore",
             swiftSettings: [
                 // Keep indexes Unicode-safe, discourage unsafe operations
diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index ec1a2a5..f0c24c8 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -4,6 +4,7 @@
 //
 
 import Foundation
+import YYJSON
 
 public enum XADAttributeValue: Sendable, Equatable {
     case dictionary([String: XADAttributeValue])
@@ -19,13 +20,11 @@ public enum XADAttributeValue: Sendable, Equatable {
         guard let first = trimmed.first, first == "{" || first == "[" else { return nil }
         guard let data = trimmed.data(using: .utf8) else { return nil }
 
-        var options: JSONSerialization.ReadingOptions = []
-        if #available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *) {
-            options.insert(.json5Allowed)
-        }
+        var options: YYJSONSerialization.ReadingOptions = []
+        options.insert(.json5Allowed)
 
         do {
-            let obj = try JSONSerialization.jsonObject(with: data, options: options)
+            let obj = try YYJSONSerialization.jsonObject(with: data, options: options)
             return XADAttributeValue.fromJSON(obj)
         } catch {
             return nil
@@ -69,6 +68,7 @@ public enum XADAttributeValue: Sendable, Equatable {
         }
     }
 
+
     public func toJSONCompatible() -> Any {
         switch self {
         case .dictionary(let dict):
@@ -334,8 +334,8 @@ private extension AttrEnv {
 
     func jsonString(from value: XADAttributeValue) -> String {
         let obj = value.toJSONCompatible()
-        guard JSONSerialization.isValidJSONObject(obj),
-              let data = try? JSONSerialization.data(withJSONObject: obj, options: []) else {
+        guard YYJSONSerialization.isValidJSONObject(obj),
+              let data = try? YYJSONSerialization.data(withJSONObject: obj, options: []) else {
             return ""
         }
         return String(data: data, encoding: .utf8) ?? ""

From 1be14a11e3741c957a5b202b086a3c686da1eba2 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 10:06:20 +0100
Subject: [PATCH 14/38] Support for multiple revision lines

---
 Sources/AsciiDocCore/ISM.swift               |   6 ++
 Sources/AsciiDocCore/Parser+Header.swift     | 107 +++++++++++++------
 Tests/AsciiDocCoreTests/ParserTests.swift    |  47 +++++++-
 Tests/AsciiDocCoreTests/RoundtripTests.swift |   2 +-
 4 files changed, 127 insertions(+), 35 deletions(-)

diff --git a/Sources/AsciiDocCore/ISM.swift b/Sources/AsciiDocCore/ISM.swift
index 9626ec1..33d0978 100644
--- a/Sources/AsciiDocCore/ISM.swift
+++ b/Sources/AsciiDocCore/ISM.swift
@@ -387,10 +387,16 @@ public struct AdocAuthor: Sendable, Equatable {
     public var address: String?
 }
 
+public struct AdocRevision: Sendable, Equatable {
+    public var number: String?
+    public var date: String?
+    public var remark: String?
+}
 
 public struct AdocHeader: Sendable, Equatable {
     public var title: AdocText?
     public var authors: [AdocAuthor]? // ISM-native author model
+    public var revisions: [AdocRevision]? // XAD: multiple revision lines
     public var location: AdocLocation? // ISM-native location
 
 }
diff --git a/Sources/AsciiDocCore/Parser+Header.swift b/Sources/AsciiDocCore/Parser+Header.swift
index 3ec898e..86ff06d 100644
--- a/Sources/AsciiDocCore/Parser+Header.swift
+++ b/Sources/AsciiDocCore/Parser+Header.swift
@@ -4,6 +4,7 @@
 //
 
 import Foundation
+import YYJSON
 
 private struct HeaderAuthorInfo {
     var fullname: String
@@ -45,7 +46,7 @@ extension AdocParser {
             var lastHeaderTok: Token? = nil
             var headerSeen = false
             var parsedAuthors: [HeaderAuthorInfo]? = nil
-            var revisionInfo: HeaderRevisionInfo? = nil
+            var revisions: [HeaderRevisionInfo] = []
 
             // Optional title
             if let tok = it.peek(), case .atxSection(let lvl, let titleRel) = tok.kind, lvl == 0 {
@@ -67,7 +68,7 @@ extension AdocParser {
                 headerSeen = true
             }
 
-            // Optional author/revision line (must be immediately next, no blank in between)
+            // Optional author/revision lines (must be immediately next, no blank in between)
             var consumedAuthorLine = false
             if let tok = it.peek(), case .blank = tok.kind {
                 // blank → header ends; do nothing
@@ -76,15 +77,20 @@ extension AdocParser {
                 let line = env.expand(authorLineRaw).trimmingCharacters(in: .whitespacesAndNewlines)
                 if !line.isEmpty {
                     var handled = false
-                    if parsedAuthors == nil && header?.title != nil {
-                        if let revisionCandidate = parseRevisionLine(line) {
-                            // Only treat as revision if there wasn't an author line and it clearly matches a revision pattern.
-                            revisionInfo = revisionCandidate
-                            it.consume()
-                            lastHeaderTok = tok
-                            headerSeen = true
-                            handled = true
-                        }
+                    if parsedAuthors == nil && header?.title != nil, let revisionCandidate = parseRevisionLine(line) {
+                        // Only treat as revision if there wasn't an author line and it clearly matches a revision pattern.
+                        revisions.append(revisionCandidate)
+                        it.consume()
+                        lastHeaderTok = tok
+                        headerSeen = true
+                        handled = true
+                        consumeRevisionLines(
+                            it: &it,
+                            env: env,
+                            revisions: &revisions,
+                            lastHeaderTok: &lastHeaderTok,
+                            headerSeen: &headerSeen
+                        )
                     }
                     if !handled {
                         let authors = parseAuthorsLine(line)
@@ -114,27 +120,13 @@ extension AdocParser {
             }
 
             if consumedAuthorLine {
-                if let tok = it.peek(), case .blank = tok.kind {
-                    // nothing
-                } else if headerSeen, let tok = it.peek(), case .text(let r) = tok.kind {
-                    let revisionLineRaw = it.textFromRelative(range: r, token: tok)
-                    let revisionLine = env.expand(revisionLineRaw).trimmingCharacters(in: .whitespacesAndNewlines)
-                    if let revision = parseRevisionLine(revisionLine) {
-                        revisionInfo = revision
-                        it.consume()
-                        lastHeaderTok = tok
-                        headerSeen = true
-                    }
-                }
-            } else if revisionInfo == nil, let tok = it.peek(), case .text(let r) = tok.kind, headerSeen {
-                let revisionLineRaw = it.textFromRelative(range: r, token: tok)
-                let revisionLine = env.expand(revisionLineRaw).trimmingCharacters(in: .whitespacesAndNewlines)
-                if let revision = parseRevisionLine(revisionLine) {
-                    revisionInfo = revision
-                    it.consume()
-                    lastHeaderTok = tok
-                    headerSeen = true
-                }
+                consumeRevisionLines(
+                    it: &it,
+                    env: env,
+                    revisions: &revisions,
+                    lastHeaderTok: &lastHeaderTok,
+                    headerSeen: &headerSeen
+                )
             }
 
             // Optional list of attributes (no blank lines allowed within header)
@@ -196,6 +188,19 @@ extension AdocParser {
 
             // If we produced any part of the header, ensure attributes map is non-nil
             if headerSeen {
+                if !revisions.isEmpty {
+                    if header == nil {
+                        header = AdocHeader(title: nil, authors: nil, location: nil)
+                    }
+                    header!.revisions = revisions.map {
+                        AdocRevision(number: $0.number, date: $0.date, remark: $0.remark)
+                    }
+                    if xadOptions.enabled,
+                       !lockedAttributes.contains("doc.revisions"),
+                       let json = revisionsJSONString(from: revisions) {
+                        env.applyAttributeSet(name: "doc.revisions", value: json)
+                    }
+                }
                 docAttrs = env.values
                 typedAttrs = env.typedValues
                 if docAttrs.isEmpty { docAttrs = [:] }
@@ -217,7 +222,7 @@ extension AdocParser {
                     applyHeaderDerivedAttributes(
                         header: header,
                         authors: parsedAuthors,
-                        revision: revisionInfo,
+                        revision: revisions.last,
                         attrs: &docAttrs,
                         lockedAttributes: lockedAttributes
                     )
@@ -338,6 +343,42 @@ private func parseSingleAuthor(_ raw: String) -> HeaderAuthorInfo {
     )
 }
 
+private func consumeRevisionLines(
+    it: inout TokenIter,
+    env: AttrEnv,
+    revisions: inout [HeaderRevisionInfo],
+    lastHeaderTok: inout Token?,
+    headerSeen: inout Bool
+) {
+    while let tok = it.peek(), case .text(let r) = tok.kind {
+        let revisionLineRaw = it.textFromRelative(range: r, token: tok)
+        let revisionLine = env.expand(revisionLineRaw).trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let revision = parseRevisionLine(revisionLine) else { break }
+        revisions.append(revision)
+        it.consume()
+        lastHeaderTok = tok
+        headerSeen = true
+    }
+}
+
+private func revisionsJSONString(from revisions: [HeaderRevisionInfo]) -> String? {
+    guard !revisions.isEmpty else { return nil }
+    var array: [[String: Any]] = []
+    array.reserveCapacity(revisions.count)
+    for revision in revisions {
+        var obj: [String: Any] = [:]
+        if let number = revision.number { obj["version"] = number }
+        if let date = revision.date { obj["date"] = date }
+        if let remark = revision.remark { obj["remark"] = remark }
+        array.append(obj)
+    }
+    guard YYJSONSerialization.isValidJSONObject(array),
+          let data = try? YYJSONSerialization.data(withJSONObject: array, options: []) else {
+        return nil
+    }
+    return String(data: data, encoding: .utf8)
+}
+
 private func parseRevisionLine(_ rawLine: String) -> HeaderRevisionInfo? {
     if rawLine.contains("<") || rawLine.contains("@") { return nil }
     let trimmed = rawLine.trimmingCharacters(in: .whitespacesAndNewlines)
diff --git a/Tests/AsciiDocCoreTests/ParserTests.swift b/Tests/AsciiDocCoreTests/ParserTests.swift
index 706dbfc..8b6bfe9 100644
--- a/Tests/AsciiDocCoreTests/ParserTests.swift
+++ b/Tests/AsciiDocCoreTests/ParserTests.swift
@@ -51,7 +51,7 @@ private enum ASGInspector {
         }
       case .dlist(let dl):
         return dl.items.flatMap { $0.blocks?.flatMap(fromBlock) ?? [] }
-      case .discreteHeading, .break, .blockMacro, .leaf, .list, .dlist:
+      case .discreteHeading, .break, .blockMacro, .leaf:
         return []
       }
     }
@@ -177,6 +177,51 @@ struct ParserTests {
       #expect(doc.attributes["revremark"] == "Draft")
     }
 
+    @Test
+    func header_multiple_revision_lines() {
+      let src = """
+      = Sample Guide
+      Jane Doe <jane@example.com>
+      0.1, 2026-01-12: Initial draft
+      0.2, 2026-02-04: Added requirements
+
+      Body text
+      """
+
+      let parser = AdocParser()
+      let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+
+      #expect(doc.attributes["revnumber"] == "0.2")
+      #expect(doc.attributes["revdate"] == "2026-02-04")
+      #expect(doc.attributes["revremark"] == "Added requirements")
+
+      guard case .dictionary(let docDict)? = doc.typedAttributes["doc"] else {
+        Issue.record("Expected doc typed attributes")
+        return
+      }
+      guard case .array(let revisions)? = docDict["revisions"] else {
+        Issue.record("Expected doc.revisions typed array")
+        return
+      }
+      #expect(revisions.count == 2)
+      if revisions.count >= 2 {
+        if case .dictionary(let first)? = revisions.first {
+          #expect(first["version"] == .string("0.1"))
+          #expect(first["date"] == .string("2026-01-12"))
+          #expect(first["remark"] == .string("Initial draft"))
+        } else {
+          Issue.record("Expected first revision to be a dictionary")
+        }
+        if case .dictionary(let second)? = revisions.last {
+          #expect(second["version"] == .string("0.2"))
+          #expect(second["date"] == .string("2026-02-04"))
+          #expect(second["remark"] == .string("Added requirements"))
+        } else {
+          Issue.record("Expected second revision to be a dictionary")
+        }
+      }
+    }
+
     @Test
     func derived_header_attributes_respect_locks() {
       let src = """
diff --git a/Tests/AsciiDocCoreTests/RoundtripTests.swift b/Tests/AsciiDocCoreTests/RoundtripTests.swift
index b0cbf82..bf79950 100644
--- a/Tests/AsciiDocCoreTests/RoundtripTests.swift
+++ b/Tests/AsciiDocCoreTests/RoundtripTests.swift
@@ -92,7 +92,7 @@ private func stripSpans(_ block: AdocBlock) -> AdocBlock {
         dlist.items = dlist.items.map { item in
             var updated = item
             updated.span = nil
-            let hasKbd = item.term.inlines.contains { node in // Assuming 'p' was a typo and meant 'item'
+            let _ = item.term.inlines.contains { node in // Assuming 'p' was a typo and meant 'item'
              if case .inlineMacro(let name, let target, let body, _) = node {
                 return name == "kbd" && (target == nil || target?.isEmpty == true) && body == "Ctrl+C"
             }

From 4b9c1216b97125ecdcc4d3307348339e877ef2eb Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 14:36:07 +0100
Subject: [PATCH 15/38] Scaffolding for XAD control and macro handling

---
 Sources/AsciiDocCore/XADProcessor.swift       | 13 +++++++++++
 Sources/AsciiDocExtensions/XADExtension.swift | 23 +++++++++++++++++++
 Sources/asciidoc-swift/Commands.swift         | 10 ++++++--
 3 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 Sources/AsciiDocCore/XADProcessor.swift
 create mode 100644 Sources/AsciiDocExtensions/XADExtension.swift

diff --git a/Sources/AsciiDocCore/XADProcessor.swift b/Sources/AsciiDocCore/XADProcessor.swift
new file mode 100644
index 0000000..73c3e67
--- /dev/null
+++ b/Sources/AsciiDocCore/XADProcessor.swift
@@ -0,0 +1,13 @@
+//
+// Copyright (c) 2026 Mattias Holm
+// SPDX-License-Identifier: Apache-2.0
+//
+
+public struct XADProcessor: Sendable {
+    public init() {}
+
+    public func apply(document: AdocDocument) -> AdocDocument {
+        // AST-phase expansion will be wired here.
+        return document
+    }
+}
diff --git a/Sources/AsciiDocExtensions/XADExtension.swift b/Sources/AsciiDocExtensions/XADExtension.swift
new file mode 100644
index 0000000..08ebfb9
--- /dev/null
+++ b/Sources/AsciiDocExtensions/XADExtension.swift
@@ -0,0 +1,23 @@
+//
+// Copyright (c) 2026 Mattias Holm
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import AsciiDocCore
+
+public struct XADExtension: AsciiDocExtension {
+    public let name: String = "xad"
+    private let processor: XADProcessor
+
+    public init(processor: XADProcessor = XADProcessor()) {
+        self.processor = processor
+    }
+
+    public func willParse(source: String, attributes: [String:String]) -> (String, [String:String]) {
+        (source, attributes)
+    }
+
+    public func didParse(document: AdocDocument) -> AdocDocument {
+        processor.apply(document: document)
+    }
+}
diff --git a/Sources/asciidoc-swift/Commands.swift b/Sources/asciidoc-swift/Commands.swift
index 0b33555..297d26e 100644
--- a/Sources/asciidoc-swift/Commands.swift
+++ b/Sources/asciidoc-swift/Commands.swift
@@ -752,7 +752,8 @@ private func renderDocument(
         extensionHost: &extensionHost,
         attributes: baseAttributes,
         documentDirectory: documentDirectory,
-        enabledExtensions: enabledExtensions
+        enabledExtensions: enabledExtensions,
+        xadOptions: xadOptions
     )
 
     let (preprocessedSource, updatedAttributes) = extensionHost.runWillParse(
@@ -829,7 +830,8 @@ private func registerExtensions(
     extensionHost: inout ExtensionHost,
     attributes: [String: String],
     documentDirectory: URL?,
-    enabledExtensions: [String]
+    enabledExtensions: [String],
+    xadOptions: XADOptions
 ) {
     if let plantumlExtension = makePlantumlExtension(
         attributes: attributes,
@@ -842,6 +844,10 @@ private func registerExtensions(
     if let latexExtension = makeLatexExtension(enabledExtensions: enabledExtensions) {
         extensionHost.register(latexExtension)
     }
+
+    if xadOptions.enabled {
+        extensionHost.register(XADExtension())
+    }
 }
 
 private func makePlantumlExtension(

From bc5236e3419605f42592b35c523ccc18e8b539b3 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 15:32:21 +0100
Subject: [PATCH 16/38] Implement control logic

---
 .gitignore                                    |   1 +
 Sources/AsciiDocCore/Attributes.swift         |   4 +
 Sources/AsciiDocCore/ISM_BlockMacro.swift     |   3 +
 Sources/AsciiDocCore/Parser+Block.swift       |   4 +-
 Sources/AsciiDocCore/XADProcessor.swift       | 819 +++++++++++++++++-
 .../PlantUMLExtension.swift                   |   1 +
 Tests/AsciiDocCoreTests/XADControlTests.swift | 104 +++
 7 files changed, 933 insertions(+), 3 deletions(-)
 create mode 100644 Tests/AsciiDocCoreTests/XADControlTests.swift

diff --git a/.gitignore b/.gitignore
index 6f2876b..d8e1c88 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,3 +11,4 @@ DerivedData/
 artifacts/
 .vscode
 .cache
+.swiftpm
diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index f0c24c8..f350ebd 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -175,6 +175,10 @@ package struct AttrEnv {
         return nil
     }
 
+    package func resolveTypedValue(_ path: String) -> XADAttributeValue? {
+        resolveTypedPath(path)
+    }
+
     /// Expand {attr} in a string using the *current* environment.
     /// No re-parsing of markup is done; this is purely textual.
     package func expand(_ s: String) -> String {
diff --git a/Sources/AsciiDocCore/ISM_BlockMacro.swift b/Sources/AsciiDocCore/ISM_BlockMacro.swift
index 8462e6e..e3bafc2 100644
--- a/Sources/AsciiDocCore/ISM_BlockMacro.swift
+++ b/Sources/AsciiDocCore/ISM_BlockMacro.swift
@@ -6,6 +6,7 @@
 public struct AdocBlockMacro: Sendable, Equatable {
     public var name: String // "include", "image", etc
     public var target: String?
+    public var attributes: [String: String]
     public var id: String?
     public var title: AdocText?
     public var reftext: AdocText?
@@ -15,6 +16,7 @@ public struct AdocBlockMacro: Sendable, Equatable {
     public init(
         name: String,
         target: String? = nil,
+        attributes: [String: String] = [:],
         id: String? = nil,
         title: AdocText? = nil,
         reftext: AdocText? = nil,
@@ -22,6 +24,7 @@ public struct AdocBlockMacro: Sendable, Equatable {
         span: AdocRange? = nil) {
         self.name = name
         self.target = target
+        self.attributes = attributes
         self.id = id
         self.title = title
         self.reftext = reftext
diff --git a/Sources/AsciiDocCore/Parser+Block.swift b/Sources/AsciiDocCore/Parser+Block.swift
index 0ffb053..8c99cfb 100644
--- a/Sources/AsciiDocCore/Parser+Block.swift
+++ b/Sources/AsciiDocCore/Parser+Block.swift
@@ -680,9 +680,11 @@ extension AdocParser {
                      }
                  }
 
-                 let macro = AdocBlockMacro(
+                 let macroAttrs = parseMacroAttributeList(payloadParts.body ?? "")
+                let macro = AdocBlockMacro(
                      name: name,
                      target: payloadParts.target,
+                    attributes: macroAttrs,
                      id: meta.id, title: meta.title, reftext: nil, // use metadata consumed
                      meta: .init(), // TODO: merge meta properly?
                      span: it.spanForLine(tok)
diff --git a/Sources/AsciiDocCore/XADProcessor.swift b/Sources/AsciiDocCore/XADProcessor.swift
index 73c3e67..427b4c5 100644
--- a/Sources/AsciiDocCore/XADProcessor.swift
+++ b/Sources/AsciiDocCore/XADProcessor.swift
@@ -3,11 +3,826 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+import Foundation
+import YYJSON
+
 public struct XADProcessor: Sendable {
     public init() {}
 
     public func apply(document: AdocDocument) -> AdocDocument {
-        // AST-phase expansion will be wired here.
-        return document
+        var env = AttrEnv(
+            initial: document.attributes,
+            typedAttributes: document.typedAttributes,
+            xadOptions: document.xadOptions
+        )
+        var warnings = document.warnings
+        let processed = processBlocks(
+            document.blocks,
+            env: &env,
+            warnings: &warnings,
+            locals: [:]
+        )
+        var updated = document
+        updated.blocks = processed
+        updated.warnings = warnings
+        updated.attributes = env.values
+        updated.typedAttributes = env.typedValues
+        return updated
+    }
+}
+
+private extension XADProcessor {
+    func processBlocks(
+        _ blocks: [AdocBlock],
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue]
+    ) -> [AdocBlock] {
+        var result: [AdocBlock] = []
+        var index = 0
+
+        while index < blocks.count {
+            let block = blocks[index]
+            if case .blockMacro(let macro) = block {
+                let name = macro.name.lowercased()
+                if name == "if" {
+                    let (endIndex, output) = expandIf(
+                        from: index,
+                        blocks: blocks,
+                        env: &env,
+                        warnings: &warnings,
+                        locals: locals
+                    )
+                    result.append(contentsOf: output)
+                    index = endIndex + 1
+                    continue
+                }
+                if name == "for" {
+                    let (endIndex, output) = expandFor(
+                        from: index,
+                        blocks: blocks,
+                        env: &env,
+                        warnings: &warnings,
+                        locals: locals
+                    )
+                    result.append(contentsOf: output)
+                    index = endIndex + 1
+                    continue
+                }
+                if name == "elif" || name == "else" || name == "end" {
+                    warnings.append(
+                        AdocWarning(
+                            message: "Unexpected control directive: \(macro.name)",
+                            span: macro.span
+                        )
+                    )
+                    index += 1
+                    continue
+                }
+            }
+
+            let transformed = transformBlock(block, env: &env, warnings: &warnings, locals: locals)
+            result.append(transformed)
+            index += 1
+        }
+
+        return result
+    }
+
+    func transformBlock(
+        _ block: AdocBlock,
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue]
+    ) -> AdocBlock {
+        switch block {
+        case .section(var section):
+            section.title = expandText(section.title, env: env, locals: locals)
+            section.blocks = processBlocks(section.blocks, env: &env, warnings: &warnings, locals: locals)
+            return .section(section)
+
+        case .paragraph(var para):
+            para.text = expandText(para.text, env: env, locals: locals)
+            return .paragraph(para)
+
+        case .listing(var listing):
+            listing.text = expandText(listing.text, env: env, locals: locals)
+            return .listing(listing)
+
+        case .literalBlock(var literal):
+            literal.text = expandText(literal.text, env: env, locals: locals)
+            return .literalBlock(literal)
+
+        case .discreteHeading(var heading):
+            heading.title = expandText(heading.title, env: env, locals: locals)
+            return .discreteHeading(heading)
+
+        case .list(var list):
+            list.items = list.items.map { item in
+                var copy = item
+                copy.principal = expandText(item.principal, env: env, locals: locals)
+                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals)
+                return copy
+            }
+            return .list(list)
+
+        case .dlist(var dlist):
+            dlist.items = dlist.items.map { item in
+                var copy = item
+                copy.term = expandText(item.term, env: env, locals: locals)
+                if let principal = item.principal {
+                    copy.principal = expandText(principal, env: env, locals: locals)
+                }
+                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals)
+                return copy
+            }
+            return .dlist(dlist)
+
+        case .sidebar(var sidebar):
+            sidebar.title = sidebar.title.map { expandText($0, env: env, locals: locals) }
+            sidebar.blocks = processBlocks(sidebar.blocks, env: &env, warnings: &warnings, locals: locals)
+            return .sidebar(sidebar)
+
+        case .example(var example):
+            example.title = example.title.map { expandText($0, env: env, locals: locals) }
+            example.blocks = processBlocks(example.blocks, env: &env, warnings: &warnings, locals: locals)
+            return .example(example)
+
+        case .quote(var quote):
+            quote.title = quote.title.map { expandText($0, env: env, locals: locals) }
+            quote.attribution = quote.attribution.map { expandText($0, env: env, locals: locals) }
+            quote.citetitle = quote.citetitle.map { expandText($0, env: env, locals: locals) }
+            quote.blocks = processBlocks(quote.blocks, env: &env, warnings: &warnings, locals: locals)
+            return .quote(quote)
+
+        case .open(var open):
+            open.title = open.title.map { expandText($0, env: env, locals: locals) }
+            open.blocks = processBlocks(open.blocks, env: &env, warnings: &warnings, locals: locals)
+            return .open(open)
+
+        case .admonition(var admonition):
+            admonition.title = admonition.title.map { expandText($0, env: env, locals: locals) }
+            admonition.blocks = processBlocks(admonition.blocks, env: &env, warnings: &warnings, locals: locals)
+            return .admonition(admonition)
+
+        case .verse(var verse):
+            verse.title = verse.title.map { expandText($0, env: env, locals: locals) }
+            verse.attribution = verse.attribution.map { expandText($0, env: env, locals: locals) }
+            verse.citetitle = verse.citetitle.map { expandText($0, env: env, locals: locals) }
+            if let text = verse.text {
+                verse.text = expandText(text, env: env, locals: locals)
+            }
+            verse.blocks = processBlocks(verse.blocks, env: &env, warnings: &warnings, locals: locals)
+            return .verse(verse)
+
+        default:
+            return block
+        }
+    }
+
+    func expandIf(
+        from startIndex: Int,
+        blocks: [AdocBlock],
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue]
+    ) -> (Int, [AdocBlock]) {
+        guard case .blockMacro(let ifMacro) = blocks[startIndex] else {
+            return (startIndex, [])
+        }
+        let initialCond = conditionExpression(from: ifMacro)
+        var branches: [(cond: String?, blocks: [AdocBlock])] = [
+            (cond: initialCond, blocks: [])
+        ]
+        var currentIndex = startIndex + 1
+        var depth = 0
+
+        while currentIndex < blocks.count {
+            let block = blocks[currentIndex]
+            if case .blockMacro(let macro) = block {
+                let name = macro.name.lowercased()
+                if name == "if" || name == "for" {
+                    depth += 1
+                    branches[branches.count - 1].blocks.append(block)
+                    currentIndex += 1
+                    continue
+                }
+                if name == "end" {
+                    if depth == 0 {
+                        if let target = macro.target?.lowercased(), target == "if" || target == "for" {
+                            break
+                        }
+                        break
+                    }
+                    depth -= 1
+                    branches[branches.count - 1].blocks.append(block)
+                    currentIndex += 1
+                    continue
+                }
+                if depth == 0 && name == "elif" {
+                    branches.append((cond: conditionExpression(from: macro), blocks: []))
+                    currentIndex += 1
+                    continue
+                }
+                if depth == 0 && name == "else" {
+                    branches.append((cond: nil, blocks: []))
+                    currentIndex += 1
+                    continue
+                }
+            }
+
+            branches[branches.count - 1].blocks.append(block)
+            currentIndex += 1
+        }
+
+        if currentIndex >= blocks.count {
+            warnings.append(
+                AdocWarning(
+                    message: "Missing end for if directive",
+                    span: ifMacro.span
+                )
+            )
+            return (blocks.count - 1, Array(blocks[startIndex..<blocks.count]))
+        }
+
+        var selected: [AdocBlock] = []
+        for branch in branches {
+            if let cond = branch.cond {
+                if evaluateCondition(cond, env: env, locals: locals) {
+                    selected = branch.blocks
+                    break
+                }
+            } else {
+                selected = branch.blocks
+                break
+            }
+        }
+
+        let processed = processBlocks(selected, env: &env, warnings: &warnings, locals: locals)
+        return (currentIndex, processed)
+    }
+
+    func expandFor(
+        from startIndex: Int,
+        blocks: [AdocBlock],
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue]
+    ) -> (Int, [AdocBlock]) {
+        guard case .blockMacro(let forMacro) = blocks[startIndex] else {
+            return (startIndex, [])
+        }
+
+        var body: [AdocBlock] = []
+        var currentIndex = startIndex + 1
+        var depth = 0
+
+        while currentIndex < blocks.count {
+            let block = blocks[currentIndex]
+            if case .blockMacro(let macro) = block {
+                let name = macro.name.lowercased()
+                if name == "if" || name == "for" {
+                    depth += 1
+                    body.append(block)
+                    currentIndex += 1
+                    continue
+                }
+                if name == "end" {
+                    if depth == 0 {
+                        if let target = macro.target?.lowercased(), target == "for" || target == "if" {
+                            break
+                        }
+                        break
+                    }
+                    depth -= 1
+                    body.append(block)
+                    currentIndex += 1
+                    continue
+                }
+            }
+            body.append(block)
+            currentIndex += 1
+        }
+
+        if currentIndex >= blocks.count {
+            warnings.append(
+                AdocWarning(
+                    message: "Missing end for for directive",
+                    span: forMacro.span
+                )
+            )
+            return (blocks.count - 1, Array(blocks[startIndex..<blocks.count]))
+        }
+
+        guard let inExpr = forMacro.attributes["in"] ?? targetFallback(from: forMacro) else {
+            warnings.append(
+                AdocWarning(
+                    message: "for directive missing in expression",
+                    span: forMacro.span
+                )
+            )
+            return (currentIndex, [])
+        }
+
+        let indexName = forMacro.attributes["index"]
+        let itemName = forMacro.attributes["item"]
+        let keyName = forMacro.attributes["key"]
+        let valueName = forMacro.attributes["value"]
+
+        guard let collection = evaluateValue(inExpr, env: env, locals: locals) else {
+            warnings.append(
+                AdocWarning(
+                    message: "for directive could not resolve in expression",
+                    span: forMacro.span
+                )
+            )
+            return (currentIndex, [])
+        }
+
+        var expanded: [AdocBlock] = []
+        switch collection {
+        case .array(let items):
+            guard let indexName, let itemName else {
+                warnings.append(
+                    AdocWarning(
+                        message: "for array iteration requires index and item",
+                        span: forMacro.span
+                    )
+                )
+                return (currentIndex, [])
+            }
+            for (idx, value) in items.enumerated() {
+                var loopLocals = locals
+                loopLocals[indexName] = .number(Double(idx))
+                loopLocals[itemName] = value
+                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals)
+                expanded.append(contentsOf: processed)
+            }
+
+        case .dictionary(let dict):
+            guard let keyName, let valueName else {
+                warnings.append(
+                    AdocWarning(
+                        message: "for dictionary iteration requires key and value",
+                        span: forMacro.span
+                    )
+                )
+                return (currentIndex, [])
+            }
+            for (key, value) in dict {
+                var loopLocals = locals
+                loopLocals[keyName] = .string(key)
+                loopLocals[valueName] = value
+                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals)
+                expanded.append(contentsOf: processed)
+            }
+
+        default:
+            warnings.append(
+                AdocWarning(
+                    message: "for directive expects array or dictionary",
+                    span: forMacro.span
+                )
+            )
+        }
+
+        return (currentIndex, expanded)
+    }
+
+    func conditionExpression(from macro: AdocBlockMacro) -> String? {
+        if let cond = macro.attributes["cond"] { return cond }
+        return targetFallback(from: macro)
+    }
+
+    func targetFallback(from macro: AdocBlockMacro) -> String? {
+        let trimmed = macro.target?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}
+
+private extension XADProcessor {
+    enum ExprToken: Equatable {
+        case lparen
+        case rparen
+        case op(String)
+        case identifier(String)
+        case string(String)
+        case number(Double)
+        case bool(Bool)
+        case null
+        case variable(String)
+    }
+
+    func evaluateCondition(_ expr: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> Bool {
+        guard let value = evaluateExpression(expr, env: env, locals: locals) else { return false }
+        return isTruthy(value)
+    }
+
+    func evaluateValue(_ expr: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> XADAttributeValue? {
+        let trimmed = expr.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.hasPrefix("{") || trimmed.hasPrefix("[") {
+            if let parsed = XADAttributeValue.parse(from: trimmed, xadOptions: env.xadOptions) {
+                return parsed
+            }
+        }
+        return evaluateExpression(expr, env: env, locals: locals)
+    }
+
+    func evaluateExpression(_ expr: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> XADAttributeValue? {
+        guard let tokens = tokenize(expr) else { return nil }
+        var parser = ExprParser(tokens: tokens) { name in
+            resolveValue(name, env: env, locals: locals)
+        }
+        return parser.parseExpression()
+    }
+
+    func tokenize(_ expr: String) -> [ExprToken]? {
+        var tokens: [ExprToken] = []
+        var index = expr.startIndex
+
+        func peekChar() -> Character? {
+            guard index < expr.endIndex else { return nil }
+            return expr[index]
+        }
+
+        func advance() {
+            index = expr.index(after: index)
+        }
+
+        while let ch = peekChar() {
+            if ch.isWhitespace {
+                advance()
+                continue
+            }
+
+            if ch == "(" {
+                tokens.append(.lparen)
+                advance()
+                continue
+            }
+
+            if ch == ")" {
+                tokens.append(.rparen)
+                advance()
+                continue
+            }
+
+            if ch == "{" {
+                let start = expr.index(after: index)
+                guard let close = expr[start...].firstIndex(of: "}") else { return nil }
+                let content = expr[start..<close].trimmingCharacters(in: .whitespacesAndNewlines)
+                tokens.append(.variable(String(content)))
+                index = expr.index(after: close)
+                continue
+            }
+
+            if ch == "\"" || ch == "'" {
+                let quote = ch
+                advance()
+                var value = ""
+                while let next = peekChar() {
+                    if next == "\\" {
+                        advance()
+                        if let escaped = peekChar() {
+                            value.append(escaped)
+                            advance()
+                        }
+                        continue
+                    }
+                    if next == quote {
+                        advance()
+                        break
+                    }
+                    value.append(next)
+                    advance()
+                }
+                tokens.append(.string(value))
+                continue
+            }
+
+            if ch.isNumber || (ch == "-" && expr.index(after: index) < expr.endIndex && expr[expr.index(after: index)].isNumber) {
+                var number = String(ch)
+                advance()
+                while let next = peekChar(), next.isNumber || next == "." {
+                    number.append(next)
+                    advance()
+                }
+                if let value = Double(number) {
+                    tokens.append(.number(value))
+                    continue
+                }
+                return nil
+            }
+
+            let twoChar = String(expr[index...].prefix(2))
+            if ["==", "!=", "<=", ">="].contains(twoChar) {
+                tokens.append(.op(twoChar))
+                index = expr.index(index, offsetBy: 2)
+                continue
+            }
+            if ch == "<" || ch == ">" {
+                tokens.append(.op(String(ch)))
+                advance()
+                continue
+            }
+
+            if ch.isLetter || ch == "_" {
+                var ident = String(ch)
+                advance()
+                while let next = peekChar(), next.isLetter || next.isNumber || next == "_" || next == "." || next == "[" || next == "]" {
+                    ident.append(next)
+                    advance()
+                }
+                let lowered = ident.lowercased()
+                if lowered == "and" || lowered == "or" || lowered == "not" {
+                    tokens.append(.op(lowered))
+                } else if lowered == "true" {
+                    tokens.append(.bool(true))
+                } else if lowered == "false" {
+                    tokens.append(.bool(false))
+                } else if lowered == "null" {
+                    tokens.append(.null)
+                } else {
+                    tokens.append(.identifier(ident))
+                }
+                continue
+            }
+
+            return nil
+        }
+
+        return tokens
+    }
+
+    func resolveValue(_ name: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> XADAttributeValue? {
+        if let local = locals[name] {
+            return local
+        }
+        if let typed = env.resolveTypedValue(name) {
+            return typed
+        }
+        if let raw = env.resolveAttribute(name) {
+            return parseScalar(raw)
+        }
+        return nil
+    }
+
+    func parseScalar(_ raw: String) -> XADAttributeValue {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        let lowered = trimmed.lowercased()
+        if lowered == "true" { return .bool(true) }
+        if lowered == "false" { return .bool(false) }
+        if lowered == "null" { return .null }
+        if let number = Double(trimmed) { return .number(number) }
+        return .string(trimmed)
+    }
+
+    func isTruthy(_ value: XADAttributeValue) -> Bool {
+        switch value {
+        case .bool(let b):
+            return b
+        case .number(let n):
+            return n != 0
+        case .string(let s):
+            return !s.isEmpty
+        case .null:
+            return false
+        case .array(let array):
+            return !array.isEmpty
+        case .dictionary(let dict):
+            return !dict.isEmpty
+        }
+    }
+
+    func expandText(_ text: AdocText, env: AttrEnv, locals: [String: XADAttributeValue]) -> AdocText {
+        let expanded = expandString(text.plain, env: env, locals: locals)
+        return AdocText(plain: expanded, span: text.span)
+    }
+
+    func expandString(_ value: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> String {
+        guard !locals.isEmpty else { return env.expand(value) }
+        var localEnv = env
+        for (key, val) in locals {
+            switch val {
+            case .string(let s):
+                localEnv.applyAttributeSet(name: key, value: s)
+            case .number(let n):
+                localEnv.applyAttributeSet(name: key, value: formatNumber(n))
+            case .bool(let b):
+                localEnv.applyAttributeSet(name: key, value: b ? "true" : "false")
+            case .null:
+                localEnv.applyAttributeSet(name: key, value: "null")
+            case .array, .dictionary:
+                localEnv.applyAttributeSet(name: key, value: jsonString(from: val))
+            }
+        }
+        return localEnv.expand(value)
+    }
+
+    func formatNumber(_ value: Double) -> String {
+        if value.isFinite,
+           value.rounded() == value,
+           value >= Double(Int.min),
+           value <= Double(Int.max) {
+            return String(Int(value))
+        }
+        return String(value)
+    }
+
+    func jsonString(from value: XADAttributeValue) -> String {
+        let obj = value.toJSONCompatible()
+        guard YYJSONSerialization.isValidJSONObject(obj),
+              let data = try? YYJSONSerialization.data(withJSONObject: obj, options: []) else {
+            return ""
+        }
+        return String(data: data, encoding: .utf8) ?? ""
+    }
+}
+
+private struct ExprParser {
+    private var tokens: [XADProcessor.ExprToken]
+    private var index: Int = 0
+    private let resolver: (String) -> XADAttributeValue?
+
+    init(tokens: [XADProcessor.ExprToken], resolver: @escaping (String) -> XADAttributeValue?) {
+        self.tokens = tokens
+        self.resolver = resolver
+    }
+
+    mutating func parseExpression() -> XADAttributeValue? {
+        parseOr()
+    }
+
+    private mutating func parseOr() -> XADAttributeValue? {
+        guard var lhs = parseAnd() else { return nil }
+        while matchOp("or") {
+            guard let rhs = parseAnd() else { return nil }
+            lhs = .bool(isTruthy(lhs) || isTruthy(rhs))
+        }
+        return lhs
+    }
+
+    private mutating func parseAnd() -> XADAttributeValue? {
+        guard var lhs = parseNot() else { return nil }
+        while matchOp("and") {
+            guard let rhs = parseNot() else { return nil }
+            lhs = .bool(isTruthy(lhs) && isTruthy(rhs))
+        }
+        return lhs
+    }
+
+    private mutating func parseNot() -> XADAttributeValue? {
+        if matchOp("not") {
+            guard let value = parseNot() else { return nil }
+            return .bool(!isTruthy(value))
+        }
+        return parseComparison()
+    }
+
+    private mutating func parseComparison() -> XADAttributeValue? {
+        guard let lhs = parsePrimary() else { return nil }
+        if let op = currentOperator() {
+            advance()
+            guard let rhs = parsePrimary() else { return nil }
+            let result = compare(lhs: lhs, rhs: rhs, op: op)
+            return .bool(result)
+        }
+        return lhs
+    }
+
+    private mutating func parsePrimary() -> XADAttributeValue? {
+        guard index < tokens.count else { return nil }
+        let token = tokens[index]
+        index += 1
+        switch token {
+        case .lparen:
+            let inner = parseExpression()
+            _ = consume(.rparen)
+            return inner
+        case .string(let s):
+            return .string(s)
+        case .number(let n):
+            return .number(n)
+        case .bool(let b):
+            return .bool(b)
+        case .null:
+            return .null
+        case .variable(let name):
+            return resolver(name)
+        case .identifier(let name):
+            return resolver(name)
+        case .op:
+            return nil
+        case .rparen:
+            return nil
+        }
+    }
+
+    private mutating func matchOp(_ op: String) -> Bool {
+        guard let token = peek() else { return false }
+        if case .op(let value) = token, value == op {
+            index += 1
+            return true
+        }
+        return false
+    }
+
+    private func currentOperator() -> String? {
+        guard let token = peek() else { return nil }
+        if case .op(let value) = token, ["==", "!=", "<", "<=", ">", ">="].contains(value) {
+            return value
+        }
+        return nil
+    }
+
+    private mutating func consume(_ token: XADProcessor.ExprToken) -> Bool {
+        guard let current = peek(), current == token else { return false }
+        index += 1
+        return true
+    }
+
+    private func peek() -> XADProcessor.ExprToken? {
+        guard index < tokens.count else { return nil }
+        return tokens[index]
+    }
+
+    private mutating func advance() {
+        index += 1
+    }
+
+    private func compare(lhs: XADAttributeValue, rhs: XADAttributeValue, op: String) -> Bool {
+        switch (lhs, rhs) {
+        case (.number(let l), .number(let r)):
+            return compareNumbers(l, r, op)
+        case (.string(let l), .string(let r)):
+            return compareStrings(l, r, op)
+        case (.bool(let l), .bool(let r)):
+            return compareBools(l, r, op)
+        case (.null, .null):
+            return op == "=="
+        default:
+            let l = stringify(lhs)
+            let r = stringify(rhs)
+            if op == "==" { return l == r }
+            if op == "!=" { return l != r }
+            return false
+        }
+    }
+
+    private func compareNumbers(_ lhs: Double, _ rhs: Double, _ op: String) -> Bool {
+        switch op {
+        case "==": return lhs == rhs
+        case "!=": return lhs != rhs
+        case "<": return lhs < rhs
+        case "<=": return lhs <= rhs
+        case ">": return lhs > rhs
+        case ">=": return lhs >= rhs
+        default: return false
+        }
+    }
+
+    private func compareStrings(_ lhs: String, _ rhs: String, _ op: String) -> Bool {
+        switch op {
+        case "==": return lhs == rhs
+        case "!=": return lhs != rhs
+        case "<": return lhs < rhs
+        case "<=": return lhs <= rhs
+        case ">": return lhs > rhs
+        case ">=": return lhs >= rhs
+        default: return false
+        }
+    }
+
+    private func compareBools(_ lhs: Bool, _ rhs: Bool, _ op: String) -> Bool {
+        switch op {
+        case "==": return lhs == rhs
+        case "!=": return lhs != rhs
+        default: return false
+        }
+    }
+
+    private func stringify(_ value: XADAttributeValue) -> String {
+        switch value {
+        case .string(let s): return s
+        case .number(let n): return String(n)
+        case .bool(let b): return b ? "true" : "false"
+        case .null: return "null"
+        case .array(let array):
+            return "[\(array.map(stringify).joined(separator: ","))]"
+        case .dictionary(let dict):
+            let parts = dict.map { "\($0.key):\(stringify($0.value))" }
+            return "{\(parts.joined(separator: ","))}"
+        }
+    }
+
+    private func isTruthy(_ value: XADAttributeValue) -> Bool {
+        switch value {
+        case .bool(let b): return b
+        case .number(let n): return n != 0
+        case .string(let s): return !s.isEmpty
+        case .null: return false
+        case .array(let arr): return !arr.isEmpty
+        case .dictionary(let dict): return !dict.isEmpty
+        }
     }
 }
diff --git a/Sources/AsciiDocExtensions/PlantUMLExtension.swift b/Sources/AsciiDocExtensions/PlantUMLExtension.swift
index 171dfae..91cd4ec 100644
--- a/Sources/AsciiDocExtensions/PlantUMLExtension.swift
+++ b/Sources/AsciiDocExtensions/PlantUMLExtension.swift
@@ -260,6 +260,7 @@ public struct PlantUMLExtension: AsciiDocExtension {
         let macro = AdocBlockMacro(
             name: "image",
             target: relativeTargetPath(for: destinationURL),
+            attributes: [:],
             id: meta.id,
             title: title,
             reftext: reftext,
diff --git a/Tests/AsciiDocCoreTests/XADControlTests.swift b/Tests/AsciiDocCoreTests/XADControlTests.swift
new file mode 100644
index 0000000..2c1f772
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/XADControlTests.swift
@@ -0,0 +1,104 @@
+import Testing
+import AsciiDocCore
+
+private func paragraphTexts(from blocks: [AdocBlock]) -> [String] {
+    var out: [String] = []
+    for block in blocks {
+        switch block {
+        case .paragraph(let para):
+            out.append(para.text.plain)
+        case .section(let section):
+            out.append(contentsOf: paragraphTexts(from: section.blocks))
+        case .list(let list):
+            for item in list.items {
+                out.append(item.principal.plain)
+                out.append(contentsOf: paragraphTexts(from: item.blocks))
+            }
+        case .dlist(let dlist):
+            for item in dlist.items {
+                out.append(item.term.plain)
+                if let principal = item.principal {
+                    out.append(principal.plain)
+                }
+                out.append(contentsOf: paragraphTexts(from: item.blocks))
+            }
+        case .sidebar(let sidebar):
+            out.append(contentsOf: paragraphTexts(from: sidebar.blocks))
+        case .example(let example):
+            out.append(contentsOf: paragraphTexts(from: example.blocks))
+        case .quote(let quote):
+            out.append(contentsOf: paragraphTexts(from: quote.blocks))
+        case .open(let open):
+            out.append(contentsOf: paragraphTexts(from: open.blocks))
+        case .admonition(let admonition):
+            out.append(contentsOf: paragraphTexts(from: admonition.blocks))
+        case .verse(let verse):
+            if let text = verse.text {
+                out.append(text.plain)
+            }
+            out.append(contentsOf: paragraphTexts(from: verse.blocks))
+        default:
+            continue
+        }
+    }
+    return out
+}
+
+private func listItemTexts(from blocks: [AdocBlock]) -> [String] {
+    var out: [String] = []
+    for block in blocks {
+        switch block {
+        case .list(let list):
+            out.append(contentsOf: list.items.map { $0.principal.plain })
+        case .section(let section):
+            out.append(contentsOf: listItemTexts(from: section.blocks))
+        default:
+            continue
+        }
+    }
+    return out
+}
+
+@Suite("XAD Control Directives")
+struct XADControlTests {
+    @Test
+    func ifElseBranches() {
+        let src = """
+        :flag: true
+
+        if::[cond="{flag} == true"]
+        Hello
+        elif::[cond="{flag} == false"]
+        No
+        else::[]
+        Other
+        end::if[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let paras = paragraphTexts(from: processed.blocks)
+        #expect(paras.contains("Hello"))
+        #expect(!paras.contains("No"))
+        #expect(!paras.contains("Other"))
+    }
+
+    @Test
+    func forLoopArrayExpansion() {
+        let src = """
+        :list: ["Ann", "Bob"]
+
+        for::[in=list, index=i, item=name]
+        * {i}: {name}
+        end::for[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let items = listItemTexts(from: processed.blocks)
+        #expect(items.contains("0: Ann"))
+        #expect(items.contains("1: Bob"))
+    }
+}

From eb185a3cb5650ec30055985d6bd6cd4aab7f9467 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 15:45:00 +0100
Subject: [PATCH 17/38] Add warnings for different control issues

---
 Sources/AsciiDocCore/XADProcessor.swift       | 64 +++++++++++++++++--
 Tests/AsciiDocCoreTests/XADControlTests.swift | 41 ++++++++++++
 2 files changed, 99 insertions(+), 6 deletions(-)

diff --git a/Sources/AsciiDocCore/XADProcessor.swift b/Sources/AsciiDocCore/XADProcessor.swift
index 427b4c5..30f41af 100644
--- a/Sources/AsciiDocCore/XADProcessor.swift
+++ b/Sources/AsciiDocCore/XADProcessor.swift
@@ -69,10 +69,30 @@ private extension XADProcessor {
                     index = endIndex + 1
                     continue
                 }
-                if name == "elif" || name == "else" || name == "end" {
+                if name == "elif" {
                     warnings.append(
                         AdocWarning(
-                            message: "Unexpected control directive: \(macro.name)",
+                            message: "elif without open if block",
+                            span: macro.span
+                        )
+                    )
+                    index += 1
+                    continue
+                }
+                if name == "else" {
+                    warnings.append(
+                        AdocWarning(
+                            message: "else without open if block",
+                            span: macro.span
+                        )
+                    )
+                    index += 1
+                    continue
+                }
+                if name == "end" {
+                    warnings.append(
+                        AdocWarning(
+                            message: "end without open control block",
                             span: macro.span
                         )
                     )
@@ -196,6 +216,7 @@ private extension XADProcessor {
         ]
         var currentIndex = startIndex + 1
         var depth = 0
+        var sawElse = false
 
         while currentIndex < blocks.count {
             let block = blocks[currentIndex]
@@ -209,8 +230,13 @@ private extension XADProcessor {
                 }
                 if name == "end" {
                     if depth == 0 {
-                        if let target = macro.target?.lowercased(), target == "if" || target == "for" {
-                            break
+                        if let target = macro.target?.lowercased(), !target.isEmpty, target != "if" {
+                            warnings.append(
+                                AdocWarning(
+                                    message: "end::\(target) does not match current if block",
+                                    span: macro.span
+                                )
+                            )
                         }
                         break
                     }
@@ -220,11 +246,32 @@ private extension XADProcessor {
                     continue
                 }
                 if depth == 0 && name == "elif" {
+                    if sawElse {
+                        warnings.append(
+                            AdocWarning(
+                                message: "elif after else in if block",
+                                span: macro.span
+                            )
+                        )
+                        currentIndex += 1
+                        continue
+                    }
                     branches.append((cond: conditionExpression(from: macro), blocks: []))
                     currentIndex += 1
                     continue
                 }
                 if depth == 0 && name == "else" {
+                    if sawElse {
+                        warnings.append(
+                            AdocWarning(
+                                message: "multiple else in if block",
+                                span: macro.span
+                            )
+                        )
+                        currentIndex += 1
+                        continue
+                    }
+                    sawElse = true
                     branches.append((cond: nil, blocks: []))
                     currentIndex += 1
                     continue
@@ -289,8 +336,13 @@ private extension XADProcessor {
                 }
                 if name == "end" {
                     if depth == 0 {
-                        if let target = macro.target?.lowercased(), target == "for" || target == "if" {
-                            break
+                        if let target = macro.target?.lowercased(), !target.isEmpty, target != "for" {
+                            warnings.append(
+                                AdocWarning(
+                                    message: "end::\(target) does not match current for block",
+                                    span: macro.span
+                                )
+                            )
                         }
                         break
                     }
diff --git a/Tests/AsciiDocCoreTests/XADControlTests.swift b/Tests/AsciiDocCoreTests/XADControlTests.swift
index 2c1f772..3ed091c 100644
--- a/Tests/AsciiDocCoreTests/XADControlTests.swift
+++ b/Tests/AsciiDocCoreTests/XADControlTests.swift
@@ -101,4 +101,45 @@ struct XADControlTests {
         #expect(items.contains("0: Ann"))
         #expect(items.contains("1: Bob"))
     }
+
+    @Test
+    func endWithoutOpenWarns() {
+        let src = """
+        end::[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("end without open") })
+    }
+
+    @Test
+    func elseWithoutIfWarns() {
+        let src = """
+        else::[]
+        Hello
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("else without open if") })
+    }
+
+    @Test
+    func endTypeMismatchWarns() {
+        let src = """
+        :list: ["Ann"]
+
+        for::[in=list, index=i, item=name]
+        * {i}: {name}
+        end::if[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("does not match current for block") })
+    }
 }

From 7820cd70ee87ceed5ca852a3466ac47808cf0aa3 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 16:29:09 +0100
Subject: [PATCH 18/38] Initial macro implementation

---
 Sources/AsciiDocCore/XADProcessor.swift       | 729 ++++++++++++++++--
 Tests/AsciiDocCoreTests/XADControlTests.swift | 152 ++++
 Tests/AsciiDocCoreTests/XADMacroTests.swift   |  69 ++
 3 files changed, 883 insertions(+), 67 deletions(-)
 create mode 100644 Tests/AsciiDocCoreTests/XADMacroTests.swift

diff --git a/Sources/AsciiDocCore/XADProcessor.swift b/Sources/AsciiDocCore/XADProcessor.swift
index 30f41af..2021e01 100644
--- a/Sources/AsciiDocCore/XADProcessor.swift
+++ b/Sources/AsciiDocCore/XADProcessor.swift
@@ -6,6 +6,24 @@
 import Foundation
 import YYJSON
 
+private enum MacroKind {
+    case block
+    case inline
+}
+
+private struct MacroParam {
+    let name: String
+    let defaultValue: String?
+}
+
+private struct MacroDefinition {
+    let name: String
+    let kind: MacroKind
+    let params: [MacroParam]
+    let body: [AdocBlock]
+    let span: AdocRange?
+}
+
 public struct XADProcessor: Sendable {
     public init() {}
 
@@ -16,11 +34,17 @@ public struct XADProcessor: Sendable {
             xadOptions: document.xadOptions
         )
         var warnings = document.warnings
+        let (macroDefs, strippedBlocks) = collectMacroDefinitions(
+            from: document.blocks,
+            warnings: &warnings
+        )
         let processed = processBlocks(
-            document.blocks,
+            strippedBlocks,
             env: &env,
             warnings: &warnings,
-            locals: [:]
+            locals: [:],
+            macros: macroDefs,
+            macroStack: []
         )
         var updated = document
         updated.blocks = processed
@@ -36,7 +60,9 @@ private extension XADProcessor {
         _ blocks: [AdocBlock],
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
-        locals: [String: XADAttributeValue]
+        locals: [String: XADAttributeValue],
+        macros: [String: MacroDefinition],
+        macroStack: [String]
     ) -> [AdocBlock] {
         var result: [AdocBlock] = []
         var index = 0
@@ -44,32 +70,63 @@ private extension XADProcessor {
         while index < blocks.count {
             let block = blocks[index]
             if case .blockMacro(let macro) = block {
-                let name = macro.name.lowercased()
-                if name == "if" {
+                let name = macro.name
+                if let definition = macros[name] {
+                    switch definition.kind {
+                    case .block:
+                        let expanded = expandBlockMacro(
+                            macro,
+                            definition: definition,
+                            env: &env,
+                            warnings: &warnings,
+                            locals: locals,
+                            macros: macros,
+                            macroStack: macroStack
+                        )
+                        result.append(contentsOf: expanded)
+                    case .inline:
+                        warnings.append(
+                            AdocWarning(
+                                message: "inline macro used in block context: \(name)",
+                                span: macro.span
+                            )
+                        )
+                        result.append(block)
+                    }
+                    index += 1
+                    continue
+                }
+
+                let lowered = name.lowercased()
+                if lowered == "if" {
                     let (endIndex, output) = expandIf(
                         from: index,
                         blocks: blocks,
                         env: &env,
                         warnings: &warnings,
-                        locals: locals
+                        locals: locals,
+                        macros: macros,
+                        macroStack: macroStack
                     )
                     result.append(contentsOf: output)
                     index = endIndex + 1
                     continue
                 }
-                if name == "for" {
+                if lowered == "for" {
                     let (endIndex, output) = expandFor(
                         from: index,
                         blocks: blocks,
                         env: &env,
                         warnings: &warnings,
-                        locals: locals
+                        locals: locals,
+                        macros: macros,
+                        macroStack: macroStack
                     )
                     result.append(contentsOf: output)
                     index = endIndex + 1
                     continue
                 }
-                if name == "elif" {
+                if lowered == "elif" {
                     warnings.append(
                         AdocWarning(
                             message: "elif without open if block",
@@ -79,7 +136,7 @@ private extension XADProcessor {
                     index += 1
                     continue
                 }
-                if name == "else" {
+                if lowered == "else" {
                     warnings.append(
                         AdocWarning(
                             message: "else without open if block",
@@ -89,7 +146,7 @@ private extension XADProcessor {
                     index += 1
                     continue
                 }
-                if name == "end" {
+                if lowered == "end" {
                     warnings.append(
                         AdocWarning(
                             message: "end without open control block",
@@ -101,7 +158,14 @@ private extension XADProcessor {
                 }
             }
 
-            let transformed = transformBlock(block, env: &env, warnings: &warnings, locals: locals)
+            let transformed = transformBlock(
+                block,
+                env: &env,
+                warnings: &warnings,
+                locals: locals,
+                macros: macros,
+                macroStack: macroStack
+            )
             result.append(transformed)
             index += 1
         }
@@ -109,39 +173,413 @@ private extension XADProcessor {
         return result
     }
 
+    func collectMacroDefinitions(
+        from blocks: [AdocBlock],
+        warnings: inout [AdocWarning]
+    ) -> ([String: MacroDefinition], [AdocBlock]) {
+        var definitions: [String: MacroDefinition] = [:]
+        var output: [AdocBlock] = []
+        var index = 0
+
+        while index < blocks.count {
+            let block = blocks[index]
+            switch block {
+            case .section(var section):
+                let (childDefs, childBlocks) = collectMacroDefinitions(from: section.blocks, warnings: &warnings)
+                section.blocks = childBlocks
+                for (name, def) in childDefs { definitions[name] = def }
+                output.append(.section(section))
+                index += 1
+
+            case .blockMacro(let macro) where macro.name.lowercased() == "macro":
+                guard let name = macro.target?.trimmingCharacters(in: .whitespacesAndNewlines), !name.isEmpty else {
+                    warnings.append(
+                        AdocWarning(
+                            message: "macro definition missing name",
+                            span: macro.span
+                        )
+                    )
+                    index += 1
+                    continue
+                }
+                let (endIndex, body) = collectMacroBody(
+                    startIndex: index,
+                    macroName: name,
+                    blocks: blocks,
+                    warnings: &warnings
+                )
+                if endIndex == index {
+                    output.append(block)
+                    index += 1
+                    continue
+                }
+
+                let kind = parseMacroKind(macro.attributes["kind"])
+                let params = parseMacroParams(macro.attributes["params"])
+                let (nestedDefs, strippedBody) = collectMacroDefinitions(from: body, warnings: &warnings)
+                for (nestedName, def) in nestedDefs { definitions[nestedName] = def }
+
+                let definition = MacroDefinition(
+                    name: name,
+                    kind: kind,
+                    params: params,
+                    body: strippedBody,
+                    span: macro.span
+                )
+                if definitions[name] != nil {
+                    warnings.append(
+                        AdocWarning(
+                            message: "macro redefinition: \(name)",
+                            span: macro.span
+                        )
+                    )
+                }
+                definitions[name] = definition
+                index = endIndex + 1
+
+            case .blockMacro(let macro) where macro.name.lowercased() == "endmacro":
+                warnings.append(
+                    AdocWarning(
+                        message: "endmacro without open macro",
+                        span: macro.span
+                    )
+                )
+                index += 1
+
+            default:
+                output.append(block)
+                index += 1
+            }
+        }
+
+        return (definitions, output)
+    }
+
+    func collectMacroBody(
+        startIndex: Int,
+        macroName: String,
+        blocks: [AdocBlock],
+        warnings: inout [AdocWarning]
+    ) -> (Int, [AdocBlock]) {
+        var body: [AdocBlock] = []
+        var index = startIndex + 1
+        var depth = 0
+
+        while index < blocks.count {
+            let block = blocks[index]
+            if case .blockMacro(let macro) = block {
+                let name = macro.name.lowercased()
+                if name == "macro" {
+                    depth += 1
+                    body.append(block)
+                    index += 1
+                    continue
+                }
+                if name == "endmacro" {
+                    if depth == 0 {
+                        if let target = macro.target?.trimmingCharacters(in: .whitespacesAndNewlines),
+                           !target.isEmpty,
+                           target != macroName {
+                            warnings.append(
+                                AdocWarning(
+                                    message: "endmacro name does not match \(macroName)",
+                                    span: macro.span
+                                )
+                            )
+                        }
+                        return (index, body)
+                    }
+                    depth -= 1
+                    body.append(block)
+                    index += 1
+                    continue
+                }
+            }
+            body.append(block)
+            index += 1
+        }
+
+        warnings.append(
+            AdocWarning(
+                message: "missing endmacro for \(macroName)",
+                span: blocks[startIndex].span
+            )
+        )
+        return (startIndex, [])
+    }
+
+    func parseMacroKind(_ raw: String?) -> MacroKind {
+        switch raw?.lowercased() {
+        case "inline":
+            return .inline
+        default:
+            return .block
+        }
+    }
+
+    func parseMacroParams(_ raw: String?) -> [MacroParam] {
+        guard let raw, !raw.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            return []
+        }
+        let parts = raw.split(separator: ",")
+        var params: [MacroParam] = []
+        for part in parts {
+            let trimmed = part.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { continue }
+            if let eq = trimmed.firstIndex(of: "=") {
+                let name = trimmed[..<eq].trimmingCharacters(in: .whitespacesAndNewlines)
+                let valueStart = trimmed.index(after: eq)
+                let defaultValue = trimmed[valueStart...].trimmingCharacters(in: .whitespacesAndNewlines)
+                if !name.isEmpty {
+                    params.append(MacroParam(name: String(name), defaultValue: String(defaultValue)))
+                }
+            } else {
+                params.append(MacroParam(name: String(trimmed), defaultValue: nil))
+            }
+        }
+        return params
+    }
+
+    func bindMacroParams(
+        definition: MacroDefinition,
+        args: [String: String],
+        warnings: inout [AdocWarning],
+        span: AdocRange?
+    ) -> [String: XADAttributeValue] {
+        var locals: [String: XADAttributeValue] = [:]
+        let paramNames = Set(definition.params.map { $0.name })
+
+        for param in definition.params {
+            if let value = args[param.name] {
+                locals[param.name] = .string(value)
+            } else if let defaultValue = param.defaultValue {
+                locals[param.name] = .string(defaultValue)
+            } else {
+                warnings.append(
+                    AdocWarning(
+                        message: "missing macro parameter: \(param.name)",
+                        span: span
+                    )
+                )
+            }
+        }
+
+        for (key, _) in args where !paramNames.contains(key) {
+            warnings.append(
+                AdocWarning(
+                    message: "unknown macro parameter: \(key)",
+                    span: span
+                )
+            )
+        }
+
+        return locals
+    }
+
+    func mergeMacroLocals(
+        base: [String: XADAttributeValue],
+        params: [String: XADAttributeValue],
+        warnings: inout [AdocWarning],
+        span: AdocRange?
+    ) -> [String: XADAttributeValue] {
+        var merged = base
+        for (key, value) in params {
+            if merged[key] != nil {
+                warnings.append(
+                    AdocWarning(
+                        message: "macro parameter shadows local variable: \(key)",
+                        span: span
+                    )
+                )
+            }
+            merged[key] = value
+        }
+        return merged
+    }
+
+    func expandBlockMacro(
+        _ macro: AdocBlockMacro,
+        definition: MacroDefinition,
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue],
+        macros: [String: MacroDefinition],
+        macroStack: [String]
+    ) -> [AdocBlock] {
+        if macroStack.contains(definition.name) {
+            warnings.append(
+                AdocWarning(
+                    message: "macro recursion detected: \(definition.name)",
+                    span: macro.span
+                )
+            )
+            return [.blockMacro(macro)]
+        }
+
+        let paramLocals = bindMacroParams(
+            definition: definition,
+            args: macro.attributes,
+            warnings: &warnings,
+            span: macro.span
+        )
+        let mergedLocals = mergeMacroLocals(
+            base: locals,
+            params: paramLocals,
+            warnings: &warnings,
+            span: macro.span
+        )
+        return processBlocks(
+            definition.body,
+            env: &env,
+            warnings: &warnings,
+            locals: mergedLocals,
+            macros: macros,
+            macroStack: macroStack + [definition.name]
+        )
+    }
+
+    func expandInlineMacros(
+        _ inlines: [AdocInline],
+        env: AttrEnv,
+        macros: [String: MacroDefinition],
+        warnings: inout [AdocWarning],
+        macroStack: [String]
+    ) -> [AdocInline] {
+        var result: [AdocInline] = []
+        result.reserveCapacity(inlines.count)
+
+        for inline in inlines {
+            switch inline {
+            case .strong(let xs, let span):
+                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.strong(mapped, span: span))
+            case .emphasis(let xs, let span):
+                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.emphasis(mapped, span: span))
+            case .mono(let xs, let span):
+                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.mono(mapped, span: span))
+            case .mark(let xs, let span):
+                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.mark(mapped, span: span))
+            case .superscript(let xs, let span):
+                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.superscript(mapped, span: span))
+            case .subscript(let xs, let span):
+                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.subscript(mapped, span: span))
+            case .link(let target, let text, let span):
+                let mapped = expandInlineMacros(text, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.link(target: target, text: mapped, span: span))
+            case .xref(let target, let text, let span):
+                let mapped = expandInlineMacros(text, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.xref(target: target, text: mapped, span: span))
+            case .footnote(let content, let ref, let id, let span):
+                let mapped = expandInlineMacros(content, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                result.append(.footnote(content: mapped, ref: ref, id: id, span: span))
+            case .inlineMacro(let name, let target, let body, let span):
+                if let definition = macros[name] {
+                    if definition.kind == .inline {
+                        if macroStack.contains(definition.name) {
+                            warnings.append(
+                                AdocWarning(
+                                    message: "macro recursion detected: \(definition.name)",
+                                    span: span
+                                )
+                            )
+                            result.append(inline)
+                            continue
+                        }
+                        let args = parseMacroAttributeList(body)
+                        let paramLocals = bindMacroParams(
+                            definition: definition,
+                            args: args,
+                            warnings: &warnings,
+                            span: span
+                        )
+                        var macroEnv = env
+                        for (key, value) in paramLocals {
+                            if case .string(let str) = value {
+                                macroEnv.applyAttributeSet(name: key, value: str)
+                            }
+                        }
+                        let expandedBlocks = definition.body.map { $0.applyingAttributes(using: macroEnv) }
+                        let expandedInlines: [AdocInline]
+                        if expandedBlocks.count == 1, case .paragraph(let para) = expandedBlocks[0] {
+                            expandedInlines = para.text.inlines
+                        } else {
+                            warnings.append(
+                                AdocWarning(
+                                    message: "inline macro body must be a single paragraph: \(definition.name)",
+                                    span: span
+                                )
+                            )
+                            let text = expandedBlocks.map { $0.renderAsAsciiDoc() }.joined()
+                            expandedInlines = parseInlines(text, baseSpan: span)
+                        }
+                        let mapped = expandInlineMacros(
+                            expandedInlines,
+                            env: macroEnv,
+                            macros: macros,
+                            warnings: &warnings,
+                            macroStack: macroStack + [definition.name]
+                        )
+                        result.append(contentsOf: mapped)
+                    } else {
+                        warnings.append(
+                            AdocWarning(
+                                message: "block macro used in inline context: \(name)",
+                                span: span
+                            )
+                        )
+                        result.append(inline)
+                    }
+                } else {
+                    result.append(inline)
+                }
+            default:
+                result.append(inline)
+            }
+        }
+
+        return result
+    }
+
     func transformBlock(
         _ block: AdocBlock,
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
-        locals: [String: XADAttributeValue]
+        locals: [String: XADAttributeValue],
+        macros: [String: MacroDefinition],
+        macroStack: [String]
     ) -> AdocBlock {
         switch block {
         case .section(var section):
-            section.title = expandText(section.title, env: env, locals: locals)
-            section.blocks = processBlocks(section.blocks, env: &env, warnings: &warnings, locals: locals)
+            section.title = expandText(section.title, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+            section.blocks = processBlocks(section.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
             return .section(section)
 
         case .paragraph(var para):
-            para.text = expandText(para.text, env: env, locals: locals)
+            para.text = expandText(para.text, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
             return .paragraph(para)
 
         case .listing(var listing):
-            listing.text = expandText(listing.text, env: env, locals: locals)
+            listing.text = expandText(listing.text, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
             return .listing(listing)
 
         case .literalBlock(var literal):
-            literal.text = expandText(literal.text, env: env, locals: locals)
+            literal.text = expandText(literal.text, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
             return .literalBlock(literal)
 
         case .discreteHeading(var heading):
-            heading.title = expandText(heading.title, env: env, locals: locals)
+            heading.title = expandText(heading.title, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
             return .discreteHeading(heading)
 
         case .list(var list):
             list.items = list.items.map { item in
                 var copy = item
-                copy.principal = expandText(item.principal, env: env, locals: locals)
-                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals)
+                copy.principal = expandText(item.principal, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
                 return copy
             }
             return .list(list)
@@ -149,50 +587,50 @@ private extension XADProcessor {
         case .dlist(var dlist):
             dlist.items = dlist.items.map { item in
                 var copy = item
-                copy.term = expandText(item.term, env: env, locals: locals)
+                copy.term = expandText(item.term, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
                 if let principal = item.principal {
-                    copy.principal = expandText(principal, env: env, locals: locals)
+                    copy.principal = expandText(principal, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
                 }
-                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals)
+                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
                 return copy
             }
             return .dlist(dlist)
 
         case .sidebar(var sidebar):
-            sidebar.title = sidebar.title.map { expandText($0, env: env, locals: locals) }
-            sidebar.blocks = processBlocks(sidebar.blocks, env: &env, warnings: &warnings, locals: locals)
+            sidebar.title = sidebar.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            sidebar.blocks = processBlocks(sidebar.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
             return .sidebar(sidebar)
 
         case .example(var example):
-            example.title = example.title.map { expandText($0, env: env, locals: locals) }
-            example.blocks = processBlocks(example.blocks, env: &env, warnings: &warnings, locals: locals)
+            example.title = example.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            example.blocks = processBlocks(example.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
             return .example(example)
 
         case .quote(var quote):
-            quote.title = quote.title.map { expandText($0, env: env, locals: locals) }
-            quote.attribution = quote.attribution.map { expandText($0, env: env, locals: locals) }
-            quote.citetitle = quote.citetitle.map { expandText($0, env: env, locals: locals) }
-            quote.blocks = processBlocks(quote.blocks, env: &env, warnings: &warnings, locals: locals)
+            quote.title = quote.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            quote.attribution = quote.attribution.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            quote.citetitle = quote.citetitle.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            quote.blocks = processBlocks(quote.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
             return .quote(quote)
 
         case .open(var open):
-            open.title = open.title.map { expandText($0, env: env, locals: locals) }
-            open.blocks = processBlocks(open.blocks, env: &env, warnings: &warnings, locals: locals)
+            open.title = open.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            open.blocks = processBlocks(open.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
             return .open(open)
 
         case .admonition(var admonition):
-            admonition.title = admonition.title.map { expandText($0, env: env, locals: locals) }
-            admonition.blocks = processBlocks(admonition.blocks, env: &env, warnings: &warnings, locals: locals)
+            admonition.title = admonition.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            admonition.blocks = processBlocks(admonition.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
             return .admonition(admonition)
 
         case .verse(var verse):
-            verse.title = verse.title.map { expandText($0, env: env, locals: locals) }
-            verse.attribution = verse.attribution.map { expandText($0, env: env, locals: locals) }
-            verse.citetitle = verse.citetitle.map { expandText($0, env: env, locals: locals) }
+            verse.title = verse.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            verse.attribution = verse.attribution.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            verse.citetitle = verse.citetitle.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
             if let text = verse.text {
-                verse.text = expandText(text, env: env, locals: locals)
+                verse.text = expandText(text, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
             }
-            verse.blocks = processBlocks(verse.blocks, env: &env, warnings: &warnings, locals: locals)
+            verse.blocks = processBlocks(verse.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
             return .verse(verse)
 
         default:
@@ -205,7 +643,9 @@ private extension XADProcessor {
         blocks: [AdocBlock],
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
-        locals: [String: XADAttributeValue]
+        locals: [String: XADAttributeValue],
+        macros: [String: MacroDefinition],
+        macroStack: [String]
     ) -> (Int, [AdocBlock]) {
         guard case .blockMacro(let ifMacro) = blocks[startIndex] else {
             return (startIndex, [])
@@ -295,9 +735,35 @@ private extension XADProcessor {
         var selected: [AdocBlock] = []
         for branch in branches {
             if let cond = branch.cond {
-                if evaluateCondition(cond, env: env, locals: locals) {
-                    selected = branch.blocks
-                    break
+                let (ok, unresolved, exprWarnings) = evaluateCondition(cond, env: env, locals: locals)
+                for message in exprWarnings {
+                    warnings.append(
+                        AdocWarning(
+                            message: message,
+                            span: ifMacro.span
+                        )
+                    )
+                }
+                if !unresolved.isEmpty {
+                    warnings.append(
+                        AdocWarning(
+                            message: "unknown variable in if expression: \(unresolved.joined(separator: ", "))",
+                            span: ifMacro.span
+                        )
+                    )
+                }
+                if let ok {
+                    if ok {
+                        selected = branch.blocks
+                        break
+                    }
+                } else {
+                    warnings.append(
+                        AdocWarning(
+                            message: "invalid if expression: \(cond)",
+                            span: ifMacro.span
+                        )
+                    )
                 }
             } else {
                 selected = branch.blocks
@@ -305,7 +771,7 @@ private extension XADProcessor {
             }
         }
 
-        let processed = processBlocks(selected, env: &env, warnings: &warnings, locals: locals)
+        let processed = processBlocks(selected, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
         return (currentIndex, processed)
     }
 
@@ -314,7 +780,9 @@ private extension XADProcessor {
         blocks: [AdocBlock],
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
-        locals: [String: XADAttributeValue]
+        locals: [String: XADAttributeValue],
+        macros: [String: MacroDefinition],
+        macroStack: [String]
     ) -> (Int, [AdocBlock]) {
         guard case .blockMacro(let forMacro) = blocks[startIndex] else {
             return (startIndex, [])
@@ -381,10 +849,27 @@ private extension XADProcessor {
         let keyName = forMacro.attributes["key"]
         let valueName = forMacro.attributes["value"]
 
-        guard let collection = evaluateValue(inExpr, env: env, locals: locals) else {
+        let (collection, unresolved, exprWarnings) = evaluateValue(inExpr, env: env, locals: locals)
+        for message in exprWarnings {
+            warnings.append(
+                AdocWarning(
+                    message: message,
+                    span: forMacro.span
+                )
+            )
+        }
+        if !unresolved.isEmpty {
             warnings.append(
                 AdocWarning(
-                    message: "for directive could not resolve in expression",
+                    message: "unknown variable in for expression: \(unresolved.joined(separator: ", "))",
+                    span: forMacro.span
+                )
+            )
+        }
+        guard let collection else {
+            warnings.append(
+                AdocWarning(
+                    message: "invalid for in expression: \(inExpr)",
                     span: forMacro.span
                 )
             )
@@ -403,11 +888,19 @@ private extension XADProcessor {
                 )
                 return (currentIndex, [])
             }
+            if keyName != nil || valueName != nil {
+                warnings.append(
+                    AdocWarning(
+                        message: "for array iteration does not use key/value",
+                        span: forMacro.span
+                    )
+                )
+            }
             for (idx, value) in items.enumerated() {
                 var loopLocals = locals
                 loopLocals[indexName] = .number(Double(idx))
                 loopLocals[itemName] = value
-                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals)
+                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals, macros: macros, macroStack: macroStack)
                 expanded.append(contentsOf: processed)
             }
 
@@ -421,11 +914,19 @@ private extension XADProcessor {
                 )
                 return (currentIndex, [])
             }
+            if indexName != nil || itemName != nil {
+                warnings.append(
+                    AdocWarning(
+                        message: "for dictionary iteration does not use index/item",
+                        span: forMacro.span
+                    )
+                )
+            }
             for (key, value) in dict {
                 var loopLocals = locals
                 loopLocals[keyName] = .string(key)
                 loopLocals[valueName] = value
-                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals)
+                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals, macros: macros, macroStack: macroStack)
                 expanded.append(contentsOf: processed)
             }
 
@@ -465,27 +966,79 @@ private extension XADProcessor {
         case variable(String)
     }
 
-    func evaluateCondition(_ expr: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> Bool {
-        guard let value = evaluateExpression(expr, env: env, locals: locals) else { return false }
-        return isTruthy(value)
+    func evaluateCondition(
+        _ expr: String,
+        env: AttrEnv,
+        locals: [String: XADAttributeValue]
+    ) -> (Bool?, [String], [String]) {
+        var unresolved: [String] = []
+        var warnings: [String] = []
+        guard let value = evaluateExpression(
+            expr,
+            env: env,
+            locals: locals,
+            unresolved: &unresolved,
+            warnings: &warnings
+        ) else {
+            return (nil, unresolved, warnings)
+        }
+        return (isTruthy(value), unresolved, warnings)
     }
 
-    func evaluateValue(_ expr: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> XADAttributeValue? {
+    func evaluateValue(
+        _ expr: String,
+        env: AttrEnv,
+        locals: [String: XADAttributeValue]
+    ) -> (XADAttributeValue?, [String], [String]) {
         let trimmed = expr.trimmingCharacters(in: .whitespacesAndNewlines)
         if trimmed.hasPrefix("{") || trimmed.hasPrefix("[") {
             if let parsed = XADAttributeValue.parse(from: trimmed, xadOptions: env.xadOptions) {
-                return parsed
+                return (parsed, [], [])
             }
         }
-        return evaluateExpression(expr, env: env, locals: locals)
+        var unresolved: [String] = []
+        var warnings: [String] = []
+        let value = evaluateExpression(
+            expr,
+            env: env,
+            locals: locals,
+            unresolved: &unresolved,
+            warnings: &warnings
+        )
+        return (value, unresolved, warnings)
     }
 
-    func evaluateExpression(_ expr: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> XADAttributeValue? {
+    func evaluateExpression(
+        _ expr: String,
+        env: AttrEnv,
+        locals: [String: XADAttributeValue],
+        unresolved: inout [String],
+        warnings: inout [String]
+    ) -> XADAttributeValue? {
         guard let tokens = tokenize(expr) else { return nil }
-        var parser = ExprParser(tokens: tokens) { name in
-            resolveValue(name, env: env, locals: locals)
+        var localUnresolved: [String] = []
+        var localWarnings: [String] = []
+        var parser = ExprParser(tokens: tokens, warningSink: { message in
+            if !localWarnings.contains(message) {
+                localWarnings.append(message)
+            }
+        }) { name in
+            if let resolved = resolveValue(name, env: env, locals: locals) {
+                return resolved
+            }
+            if !localUnresolved.contains(name) {
+                localUnresolved.append(name)
+            }
+            return .null
         }
-        return parser.parseExpression()
+        let value = parser.parseExpression()
+        for name in localUnresolved where !unresolved.contains(name) {
+            unresolved.append(name)
+        }
+        for message in localWarnings where !warnings.contains(message) {
+            warnings.append(message)
+        }
+        return value
     }
 
     func tokenize(_ expr: String) -> [ExprToken]? {
@@ -646,13 +1199,33 @@ private extension XADProcessor {
         }
     }
 
-    func expandText(_ text: AdocText, env: AttrEnv, locals: [String: XADAttributeValue]) -> AdocText {
-        let expanded = expandString(text.plain, env: env, locals: locals)
-        return AdocText(plain: expanded, span: text.span)
+    func expandText(
+        _ text: AdocText,
+        env: AttrEnv,
+        locals: [String: XADAttributeValue],
+        macros: [String: MacroDefinition],
+        warnings: inout [AdocWarning],
+        macroStack: [String]
+    ) -> AdocText {
+        let localEnv = localEnvWithLocals(env, locals: locals)
+        let attributedInlines = text.inlines.map { $0.applyingAttributes(using: localEnv) }
+        let expandedInlines = expandInlineMacros(
+            attributedInlines,
+            env: localEnv,
+            macros: macros,
+            warnings: &warnings,
+            macroStack: macroStack
+        )
+        return AdocText(inlines: expandedInlines, span: text.span)
     }
 
     func expandString(_ value: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> String {
-        guard !locals.isEmpty else { return env.expand(value) }
+        let localEnv = localEnvWithLocals(env, locals: locals)
+        return localEnv.expand(value)
+    }
+
+    func localEnvWithLocals(_ env: AttrEnv, locals: [String: XADAttributeValue]) -> AttrEnv {
+        guard !locals.isEmpty else { return env }
         var localEnv = env
         for (key, val) in locals {
             switch val {
@@ -668,7 +1241,7 @@ private extension XADProcessor {
                 localEnv.applyAttributeSet(name: key, value: jsonString(from: val))
             }
         }
-        return localEnv.expand(value)
+        return localEnv
     }
 
     func formatNumber(_ value: Double) -> String {
@@ -694,10 +1267,16 @@ private extension XADProcessor {
 private struct ExprParser {
     private var tokens: [XADProcessor.ExprToken]
     private var index: Int = 0
+    private let warningSink: (String) -> Void
     private let resolver: (String) -> XADAttributeValue?
 
-    init(tokens: [XADProcessor.ExprToken], resolver: @escaping (String) -> XADAttributeValue?) {
+    init(
+        tokens: [XADProcessor.ExprToken],
+        warningSink: @escaping (String) -> Void,
+        resolver: @escaping (String) -> XADAttributeValue?
+    ) {
         self.tokens = tokens
+        self.warningSink = warningSink
         self.resolver = resolver
     }
 
@@ -813,6 +1392,9 @@ private struct ExprParser {
         case (.null, .null):
             return op == "=="
         default:
+            if lhs.typeName != rhs.typeName {
+                warningSink("type mismatch in comparison: \(lhs.typeName) vs \(rhs.typeName)")
+            }
             let l = stringify(lhs)
             let r = stringify(rhs)
             if op == "==" { return l == r }
@@ -878,3 +1460,16 @@ private struct ExprParser {
         }
     }
 }
+private extension XADAttributeValue {
+    var typeName: String {
+        switch self {
+        case .number: return "number"
+        case .string: return "string"
+        case .bool: return "bool"
+        case .null: return "null"
+        case .array: return "array"
+        case .dictionary: return "dictionary"
+        }
+    }
+}
+
diff --git a/Tests/AsciiDocCoreTests/XADControlTests.swift b/Tests/AsciiDocCoreTests/XADControlTests.swift
index 3ed091c..ac14048 100644
--- a/Tests/AsciiDocCoreTests/XADControlTests.swift
+++ b/Tests/AsciiDocCoreTests/XADControlTests.swift
@@ -142,4 +142,156 @@ struct XADControlTests {
         let processed = XADProcessor().apply(document: doc)
         #expect(processed.warnings.contains { $0.message.contains("does not match current for block") })
     }
+
+    @Test
+    func invalidIfExpressionWarns() {
+        let src = """
+        if::[cond="{flag} == "]
+        Hello
+        end::if[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("invalid if expression") })
+    }
+
+    @Test
+    func invalidForExpressionWarns() {
+        let src = """
+        for::[in={list}
+        * item
+        end::for[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("invalid for in expression") })
+    }
+
+    @Test
+    func forArrayMissingIndexWarns() {
+        let src = """
+        :list: ["Ann"]
+
+        for::[in=list, item=name]
+        * {name}
+        end::for[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("requires index and item") })
+    }
+
+    @Test
+    func forArrayWithKeyValueWarns() {
+        let src = """
+        :list: ["Ann"]
+
+        for::[in=list, index=i, item=name, key=k, value=v]
+        * {i}: {name}
+        end::for[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("does not use key/value") })
+    }
+
+    @Test
+    func forDictionaryWithIndexItemWarns() {
+        let src = """
+        :map: {a: 1}
+
+        for::[in=map, key=k, value=v, index=i, item=name]
+        * {k} = {v}
+        end::for[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("does not use index/item") })
+    }
+
+    @Test
+    func forDictionaryMissingKeyWarns() {
+        let src = """
+        :map: {a: 1}
+
+        for::[in=map, value=v]
+        * {v}
+        end::for[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("requires key and value") })
+    }
+
+    @Test
+    func unknownVariableInIfWarns() {
+        let src = """
+        if::[cond="{missing} == true"]
+        Hello
+        end::if[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("unknown variable in if expression") })
+    }
+
+    @Test
+    func unknownVariableInForWarns() {
+        let src = """
+        for::[in=missing, index=i, item=name]
+        * {name}
+        end::for[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("unknown variable in for expression") })
+    }
+
+    @Test
+    func nonIterableForWarns() {
+        let src = """
+        :value: 42
+
+        for::[in=value, index=i, item=name]
+        * {name}
+        end::for[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("expects array or dictionary") })
+    }
+
+    @Test
+    func typeMismatchComparisonWarns() {
+        let src = """
+        :flag: true
+
+        if::[cond="{flag} > 1"]
+        Hello
+        end::if[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        #expect(processed.warnings.contains { $0.message.contains("type mismatch in comparison") })
+    }
 }
diff --git a/Tests/AsciiDocCoreTests/XADMacroTests.swift b/Tests/AsciiDocCoreTests/XADMacroTests.swift
new file mode 100644
index 0000000..bb72fa5
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/XADMacroTests.swift
@@ -0,0 +1,69 @@
+import Testing
+import AsciiDocCore
+
+private func paragraphTexts(from blocks: [AdocBlock]) -> [String] {
+    var out: [String] = []
+    for block in blocks {
+        switch block {
+        case .paragraph(let para):
+            out.append(para.text.plain)
+        case .section(let section):
+            out.append(contentsOf: paragraphTexts(from: section.blocks))
+        case .sidebar(let sidebar):
+            out.append(contentsOf: paragraphTexts(from: sidebar.blocks))
+        case .example(let example):
+            out.append(contentsOf: paragraphTexts(from: example.blocks))
+        case .quote(let quote):
+            out.append(contentsOf: paragraphTexts(from: quote.blocks))
+        case .open(let open):
+            out.append(contentsOf: paragraphTexts(from: open.blocks))
+        case .admonition(let admonition):
+            out.append(contentsOf: paragraphTexts(from: admonition.blocks))
+        case .verse(let verse):
+            if let text = verse.text {
+                out.append(text.plain)
+            }
+            out.append(contentsOf: paragraphTexts(from: verse.blocks))
+        default:
+            continue
+        }
+    }
+    return out
+}
+
+@Suite("XAD Macros")
+struct XADMacroTests {
+    @Test
+    func blockMacroExpands() {
+        let src = """
+        macro::greet[params="name"]
+        Hello {name}
+        endmacro::greet[]
+
+        greet::[name=World]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let paras = paragraphTexts(from: processed.blocks)
+        #expect(paras.contains("Hello World"))
+    }
+
+    @Test
+    func inlineMacroExpands() {
+        let src = """
+        macro::hi[kind=inline, params="name"]
+        Hello {name}
+        endmacro::hi[]
+
+        Say hi:[name=Bob].
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let paras = paragraphTexts(from: processed.blocks)
+        #expect(paras.contains("Say Hello Bob."))
+    }
+}

From 897ffe5ac06b681cb8d672ae1134bfdbb63e8eb4 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sat, 28 Feb 2026 16:49:22 +0100
Subject: [PATCH 19/38] Support macros attaching to block bodies

---
 Sources/AsciiDocCore/XADProcessor.swift     | 50 +++++++++++++++++++--
 Tests/AsciiDocCoreTests/XADMacroTests.swift | 19 ++++++++
 2 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/Sources/AsciiDocCore/XADProcessor.swift b/Sources/AsciiDocCore/XADProcessor.swift
index 2021e01..ce5fdea 100644
--- a/Sources/AsciiDocCore/XADProcessor.swift
+++ b/Sources/AsciiDocCore/XADProcessor.swift
@@ -74,6 +74,10 @@ private extension XADProcessor {
                 if let definition = macros[name] {
                     switch definition.kind {
                     case .block:
+                        let (bodyBlocks, nextIndex) = consumeMacroBody(
+                            from: index + 1,
+                            blocks: blocks
+                        )
                         let expanded = expandBlockMacro(
                             macro,
                             definition: definition,
@@ -81,9 +85,11 @@ private extension XADProcessor {
                             warnings: &warnings,
                             locals: locals,
                             macros: macros,
-                            macroStack: macroStack
+                            macroStack: macroStack,
+                            bodyBlocks: bodyBlocks
                         )
                         result.append(contentsOf: expanded)
+                        index = nextIndex
                     case .inline:
                         warnings.append(
                             AdocWarning(
@@ -92,8 +98,8 @@ private extension XADProcessor {
                             )
                         )
                         result.append(block)
+                        index += 1
                     }
-                    index += 1
                     continue
                 }
 
@@ -397,6 +403,28 @@ private extension XADProcessor {
         return merged
     }
 
+    func consumeMacroBody(from startIndex: Int, blocks: [AdocBlock]) -> ([AdocBlock], Int) {
+        guard startIndex < blocks.count else {
+            return ([], startIndex)
+        }
+
+        let block = blocks[startIndex]
+        switch block {
+        case .section:
+            return ([], startIndex)
+        case .blockMacro(let macro):
+            let lowered = macro.name.lowercased()
+            switch lowered {
+            case "if", "for", "elif", "else", "end", "macro", "endmacro":
+                return ([], startIndex)
+            default:
+                return ([block], startIndex + 1)
+            }
+        default:
+            return ([block], startIndex + 1)
+        }
+    }
+
     func expandBlockMacro(
         _ macro: AdocBlockMacro,
         definition: MacroDefinition,
@@ -404,7 +432,8 @@ private extension XADProcessor {
         warnings: inout [AdocWarning],
         locals: [String: XADAttributeValue],
         macros: [String: MacroDefinition],
-        macroStack: [String]
+        macroStack: [String],
+        bodyBlocks: [AdocBlock]
     ) -> [AdocBlock] {
         if macroStack.contains(definition.name) {
             warnings.append(
@@ -428,11 +457,24 @@ private extension XADProcessor {
             warnings: &warnings,
             span: macro.span
         )
+        var macroLocals = mergedLocals
+        if !bodyBlocks.isEmpty {
+            let bodyText = bodyBlocks.map { $0.renderAsAsciiDoc() }.joined()
+            if macroLocals["body"] != nil {
+                warnings.append(
+                    AdocWarning(
+                        message: "macro body shadows local variable: body",
+                        span: macro.span
+                    )
+                )
+            }
+            macroLocals["body"] = .string(bodyText)
+        }
         return processBlocks(
             definition.body,
             env: &env,
             warnings: &warnings,
-            locals: mergedLocals,
+            locals: macroLocals,
             macros: macros,
             macroStack: macroStack + [definition.name]
         )
diff --git a/Tests/AsciiDocCoreTests/XADMacroTests.swift b/Tests/AsciiDocCoreTests/XADMacroTests.swift
index bb72fa5..fa0c96a 100644
--- a/Tests/AsciiDocCoreTests/XADMacroTests.swift
+++ b/Tests/AsciiDocCoreTests/XADMacroTests.swift
@@ -66,4 +66,23 @@ struct XADMacroTests {
         let paras = paragraphTexts(from: processed.blocks)
         #expect(paras.contains("Say Hello Bob."))
     }
+
+    @Test
+    func blockMacroUsesBody() {
+        let src = """
+        macro::wrap[params="title"]
+        {title}: {body}
+        endmacro::wrap[]
+
+        wrap::[title=Note]
+        This is body paragraph
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let paras = paragraphTexts(from: processed.blocks).map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+        #expect(paras.contains("Note: This is body paragraph"))
+        #expect(paras.filter { $0 == "This is body paragraph" }.isEmpty)
+    }
 }

From 2f0351734522b33ab40e709ba9d09ae09b9dd6b0 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sun, 1 Mar 2026 08:40:32 +0100
Subject: [PATCH 20/38] Implement docpush, docset and docput macros

---
 Sources/AsciiDocCore/XADProcessor.swift       | 261 +++++++++++++++++-
 .../XADDocVariableTests.swift                 |  64 +++++
 Tests/AsciiDocCoreTests/XADMacroTests.swift   |  34 +++
 3 files changed, 358 insertions(+), 1 deletion(-)
 create mode 100644 Tests/AsciiDocCoreTests/XADDocVariableTests.swift

diff --git a/Sources/AsciiDocCore/XADProcessor.swift b/Sources/AsciiDocCore/XADProcessor.swift
index ce5fdea..1ba08c8 100644
--- a/Sources/AsciiDocCore/XADProcessor.swift
+++ b/Sources/AsciiDocCore/XADProcessor.swift
@@ -11,6 +11,17 @@ private enum MacroKind {
     case inline
 }
 
+private let knownMacroEffects: Set<String> = ["docpush", "docset", "docput"]
+
+private struct MacroEffects {
+    let allowsAll: Bool
+    let allowed: Set<String>
+
+    func allows(_ effect: String) -> Bool {
+        allowsAll || allowed.contains(effect)
+    }
+}
+
 private struct MacroParam {
     let name: String
     let defaultValue: String?
@@ -20,6 +31,8 @@ private struct MacroDefinition {
     let name: String
     let kind: MacroKind
     let params: [MacroParam]
+    let effects: MacroEffects
+    let usedEffects: Set<String>
     let body: [AdocBlock]
     let span: AdocRange?
 }
@@ -71,6 +84,15 @@ private extension XADProcessor {
             let block = blocks[index]
             if case .blockMacro(let macro) = block {
                 let name = macro.name
+                if let handled = handleDocMutation(
+                    macro: macro,
+                    env: &env,
+                    warnings: &warnings,
+                    locals: locals
+                ), handled {
+                    index += 1
+                    continue
+                }
                 if let definition = macros[name] {
                     switch definition.kind {
                     case .block:
@@ -222,13 +244,17 @@ private extension XADProcessor {
 
                 let kind = parseMacroKind(macro.attributes["kind"])
                 let params = parseMacroParams(macro.attributes["params"])
+                let effects = parseMacroEffects(macro.attributes["effects"], warnings: &warnings, span: macro.span)
                 let (nestedDefs, strippedBody) = collectMacroDefinitions(from: body, warnings: &warnings)
                 for (nestedName, def) in nestedDefs { definitions[nestedName] = def }
+                let usedEffects = collectMacroEffects(from: strippedBody)
 
                 let definition = MacroDefinition(
                     name: name,
                     kind: kind,
                     params: params,
+                    effects: effects,
+                    usedEffects: usedEffects,
                     body: strippedBody,
                     span: macro.span
                 )
@@ -346,6 +372,76 @@ private extension XADProcessor {
         return params
     }
 
+    func parseMacroEffects(
+        _ raw: String?,
+        warnings: inout [AdocWarning],
+        span: AdocRange?
+    ) -> MacroEffects {
+        guard let raw, !raw.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            return MacroEffects(allowsAll: false, allowed: [])
+        }
+        let tokens = raw.split { $0 == "," || $0.isWhitespace }
+        var allowsAll = false
+        var allowed: Set<String> = []
+        for token in tokens {
+            let effect = token.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            guard !effect.isEmpty else { continue }
+            if effect == "all" {
+                allowsAll = true
+                continue
+            }
+            if knownMacroEffects.contains(effect) {
+                allowed.insert(effect)
+            } else {
+                warnings.append(
+                    AdocWarning(
+                        message: "unknown macro effect: \(effect)",
+                        span: span
+                    )
+                )
+            }
+        }
+        return MacroEffects(allowsAll: allowsAll, allowed: allowed)
+    }
+
+    func collectMacroEffects(from blocks: [AdocBlock]) -> Set<String> {
+        var effects: Set<String> = []
+        for block in blocks {
+            switch block {
+            case .blockMacro(let macro):
+                let name = macro.name.lowercased()
+                if knownMacroEffects.contains(name) {
+                    effects.insert(name)
+                }
+            case .section(let section):
+                effects.formUnion(collectMacroEffects(from: section.blocks))
+            case .list(let list):
+                for item in list.items {
+                    effects.formUnion(collectMacroEffects(from: item.blocks))
+                }
+            case .dlist(let dlist):
+                for item in dlist.items {
+                    effects.formUnion(collectMacroEffects(from: item.blocks))
+                }
+            case .sidebar(let sidebar):
+                effects.formUnion(collectMacroEffects(from: sidebar.blocks))
+            case .example(let example):
+                effects.formUnion(collectMacroEffects(from: example.blocks))
+            case .quote(let quote):
+                effects.formUnion(collectMacroEffects(from: quote.blocks))
+            case .open(let open):
+                effects.formUnion(collectMacroEffects(from: open.blocks))
+            case .admonition(let admonition):
+                effects.formUnion(collectMacroEffects(from: admonition.blocks))
+            case .verse(let verse):
+                effects.formUnion(collectMacroEffects(from: verse.blocks))
+            default:
+                continue
+            }
+        }
+        return effects
+    }
+
     func bindMacroParams(
         definition: MacroDefinition,
         args: [String: String],
@@ -445,6 +541,19 @@ private extension XADProcessor {
             return [.blockMacro(macro)]
         }
 
+        if !definition.effects.allowsAll {
+            let missingEffects = definition.usedEffects.subtracting(definition.effects.allowed)
+            if !missingEffects.isEmpty {
+                let ordered = missingEffects.sorted().joined(separator: ", ")
+                warnings.append(
+                    AdocWarning(
+                        message: "macro uses effects not declared: \(ordered)",
+                        span: macro.span
+                    )
+                )
+            }
+        }
+
         let paramLocals = bindMacroParams(
             definition: definition,
             args: macro.attributes,
@@ -480,6 +589,122 @@ private extension XADProcessor {
         )
     }
 
+    func handleDocMutation(
+        macro: AdocBlockMacro,
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue]
+    ) -> Bool? {
+        let lowered = macro.name.lowercased()
+        guard lowered == "docset" || lowered == "docpush" || lowered == "docput" else {
+            return nil
+        }
+        guard let rawName = macro.attributes["name"], !rawName.isEmpty else {
+            warnings.append(
+                AdocWarning(
+                    message: "missing doc variable name",
+                    span: macro.span
+                )
+            )
+            return true
+        }
+        let name = expandString(rawName, env: env, locals: locals)
+        if !name.hasPrefix("doc.") {
+            warnings.append(
+                AdocWarning(
+                    message: "doc variable name should start with doc.: \(name)",
+                    span: macro.span
+                )
+            )
+        }
+
+        func resolveValue() -> XADAttributeValue? {
+            guard let rawValue = macro.attributes["value"] else { return nil }
+            return parseDocValue(rawValue, env: env, locals: locals)
+        }
+
+        switch lowered {
+        case "docset":
+            guard let value = resolveValue() else {
+                warnings.append(
+                    AdocWarning(
+                        message: "docset requires value",
+                        span: macro.span
+                    )
+                )
+                return true
+            }
+            env.applyAttributeSet(name: name, value: attributeString(from: value))
+            return true
+
+        case "docpush":
+            guard let value = resolveValue() else {
+                warnings.append(
+                    AdocWarning(
+                        message: "docpush requires value",
+                        span: macro.span
+                    )
+                )
+                return true
+            }
+            var array: [XADAttributeValue] = []
+            if env.xadOptions.enabled, let current = env.resolveTypedValue(name) {
+                if case .array(let existing) = current {
+                    array = existing
+                } else {
+                    warnings.append(
+                        AdocWarning(
+                            message: "docpush target is not an array: \(name)",
+                            span: macro.span
+                        )
+                    )
+                }
+            }
+            array.append(value)
+            env.applyAttributeSet(name: name, value: attributeString(from: .array(array)))
+            return true
+
+        case "docput":
+            guard let keyRaw = macro.attributes["key"], !keyRaw.isEmpty else {
+                warnings.append(
+                    AdocWarning(
+                        message: "docput requires key",
+                        span: macro.span
+                    )
+                )
+                return true
+            }
+            guard let value = resolveValue() else {
+                warnings.append(
+                    AdocWarning(
+                        message: "docput requires value",
+                        span: macro.span
+                    )
+                )
+                return true
+            }
+            let key = stripSurroundingQuotes(expandString(keyRaw, env: env, locals: locals))
+            var dict: [String: XADAttributeValue] = [:]
+            if env.xadOptions.enabled, let current = env.resolveTypedValue(name) {
+                if case .dictionary(let existing) = current {
+                    dict = existing
+                } else {
+                    warnings.append(
+                        AdocWarning(
+                            message: "docput target is not a dictionary: \(name)",
+                            span: macro.span
+                        )
+                    )
+                }
+            }
+            dict[key] = value
+            env.applyAttributeSet(name: name, value: attributeString(from: .dictionary(dict)))
+            return true
+        default:
+            return nil
+        }
+    }
+
     func expandInlineMacros(
         _ inlines: [AdocInline],
         env: AttrEnv,
@@ -519,7 +744,7 @@ private extension XADProcessor {
             case .footnote(let content, let ref, let id, let span):
                 let mapped = expandInlineMacros(content, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
                 result.append(.footnote(content: mapped, ref: ref, id: id, span: span))
-            case .inlineMacro(let name, let target, let body, let span):
+            case .inlineMacro(let name, _, let body, let span):
                 if let definition = macros[name] {
                     if definition.kind == .inline {
                         if macroStack.contains(definition.name) {
@@ -1266,6 +1491,40 @@ private extension XADProcessor {
         return localEnv.expand(value)
     }
 
+    func parseDocValue(_ rawValue: String, env: AttrEnv, locals: [String: XADAttributeValue]) -> XADAttributeValue {
+        let expanded = expandString(rawValue, env: env, locals: locals)
+        let normalized = stripSurroundingQuotes(expanded)
+        if let typed = XADAttributeValue.parse(from: normalized, xadOptions: env.xadOptions) {
+            return typed
+        }
+        return .string(normalized)
+    }
+
+    func attributeString(from value: XADAttributeValue) -> String {
+        switch value {
+        case .string(let s):
+            return s
+        case .number(let n):
+            return formatNumber(n)
+        case .bool(let b):
+            return b ? "true" : "false"
+        case .null:
+            return "null"
+        case .array, .dictionary:
+            return jsonString(from: value)
+        }
+    }
+
+    func stripSurroundingQuotes(_ value: String) -> String {
+        guard value.count >= 2 else { return value }
+        let first = value.first
+        let last = value.last
+        if (first == "\"" && last == "\"") || (first == "'" && last == "'") {
+            return String(value.dropFirst().dropLast())
+        }
+        return value
+    }
+
     func localEnvWithLocals(_ env: AttrEnv, locals: [String: XADAttributeValue]) -> AttrEnv {
         guard !locals.isEmpty else { return env }
         var localEnv = env
diff --git a/Tests/AsciiDocCoreTests/XADDocVariableTests.swift b/Tests/AsciiDocCoreTests/XADDocVariableTests.swift
new file mode 100644
index 0000000..28c8e91
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/XADDocVariableTests.swift
@@ -0,0 +1,64 @@
+import Testing
+import AsciiDocCore
+
+private func docRoot(from doc: AdocDocument) -> [String: XADAttributeValue] {
+    guard case .dictionary(let dict) = doc.typedAttributes["doc"] else {
+        return [:]
+    }
+    return dict
+}
+
+@Suite("XAD Document Variables")
+struct XADDocVariableTests {
+    @Test
+    func docsetStoresScalar() {
+        let src = """
+        docset::[name="doc.status", value="draft"]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let dict = docRoot(from: processed)
+        #expect(dict["status"] == .string("draft"))
+    }
+
+    @Test
+    func docpushAppendsValues() {
+        let src = """
+        docpush::[name="doc.sections", value={id:"sec1", title:"Intro"}]
+        docpush::[name="doc.sections", value={id:"sec2", title:"Body"}]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let dict = docRoot(from: processed)
+        guard case .array(let sections)? = dict["sections"] else {
+            Issue.record("doc.sections should be an array")
+            return
+        }
+        #expect(sections.count == 2)
+    }
+
+    @Test
+    func docputUpdatesDictionary() {
+        let src = """
+        docput::[name="doc.byId", key="sec1", value={title:"Intro"}]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let dict = docRoot(from: processed)
+        guard case .dictionary(let byId)? = dict["byId"] else {
+            Issue.record("doc.byId should be a dictionary")
+            return
+        }
+        guard case .dictionary(let entry)? = byId["sec1"] else {
+            Issue.record("doc.byId.sec1 should be a dictionary")
+            return
+        }
+        #expect(entry["title"] == .string("Intro"))
+    }
+}
diff --git a/Tests/AsciiDocCoreTests/XADMacroTests.swift b/Tests/AsciiDocCoreTests/XADMacroTests.swift
index fa0c96a..6853869 100644
--- a/Tests/AsciiDocCoreTests/XADMacroTests.swift
+++ b/Tests/AsciiDocCoreTests/XADMacroTests.swift
@@ -85,4 +85,38 @@ struct XADMacroTests {
         #expect(paras.contains("Note: This is body paragraph"))
         #expect(paras.filter { $0 == "This is body paragraph" }.isEmpty)
     }
+
+    @Test
+    func macroEffectsWarning() {
+        let src = """
+        macro::setter[]
+        docset::[name="doc.status", value="draft"]
+        endmacro::setter[]
+
+        setter::[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let messages = processed.warnings.map { $0.message }
+        #expect(messages.contains { $0.contains("macro uses effects not declared") })
+    }
+
+    @Test
+    func macroEffectsAllowed() {
+        let src = """
+        macro::setter[effects="docset"]
+        docset::[name="doc.status", value="draft"]
+        endmacro::setter[]
+
+        setter::[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let messages = processed.warnings.map { $0.message }
+        #expect(messages.filter { $0.contains("macro uses effects not declared") }.isEmpty)
+    }
 }

From 473f09fb44cc87d312830983257f8588555d3660 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sun, 1 Mar 2026 08:45:11 +0100
Subject: [PATCH 21/38] Update readme

---
 README.adoc | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/README.adoc b/README.adoc
index 96e8ea6..695cef8 100644
--- a/README.adoc
+++ b/README.adoc
@@ -13,6 +13,11 @@ Current additions include:
 * Multi-line JSON/JSON5 attribute values without explicit continuation escapes.
 * Attribute accessors for nested values (e.g. `foo.bar` and bracket indexing).
 * XAD access macros for nested values (`get::path[]` and `set::path[value]`), plus shorthand access with `{foo.bar}`.
+* User-defined macros (block and inline) with parameters, defaults, and `{body}` substitution for block macros.
+* Macro recursion detection (direct and indirect) with warnings.
+* Macro side-effect allow list via `effects="docpush docset docput"` (or `effects=all`).
+* Control directives: `if`/`elif`/`else`/`end` and `for` loops, with expression validation warnings.
+* Document variables (`docset`, `docpush`, `docput`) for building registries under `doc.*`.
 * Layout-oriented attributes intended for paged and PDF-style renderers.
 * Scoped attributes for block- and section-level overrides.
 

From 73f864757c605f1fae330c8092c05f96848276db Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sun, 1 Mar 2026 08:48:01 +0100
Subject: [PATCH 22/38] Add test cases verifying recursion prevention

---
 Tests/AsciiDocCoreTests/XADMacroTests.swift | 38 +++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/Tests/AsciiDocCoreTests/XADMacroTests.swift b/Tests/AsciiDocCoreTests/XADMacroTests.swift
index 6853869..4a90e71 100644
--- a/Tests/AsciiDocCoreTests/XADMacroTests.swift
+++ b/Tests/AsciiDocCoreTests/XADMacroTests.swift
@@ -119,4 +119,42 @@ struct XADMacroTests {
         let messages = processed.warnings.map { $0.message }
         #expect(messages.filter { $0.contains("macro uses effects not declared") }.isEmpty)
     }
+
+    @Test
+    func blockMacroRecursionWarns() {
+        let src = """
+        macro::loop[]
+        loop::[]
+        endmacro::loop[]
+
+        loop::[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let messages = processed.warnings.map { $0.message }
+        #expect(messages.contains { $0.contains("macro recursion detected: loop") })
+    }
+
+    @Test
+    func inlineMacroRecursionWarns() {
+        let src = """
+        macro::a[kind=inline]
+        b:[]
+        endmacro::a[]
+
+        macro::b[kind=inline]
+        a:[]
+        endmacro::b[]
+
+        a:[]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = XADProcessor().apply(document: doc)
+        let messages = processed.warnings.map { $0.message }
+        #expect(messages.contains { $0.contains("macro recursion detected: a") })
+    }
 }

From 6748f80ab6160ba052713772df43eea22a982506 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sun, 1 Mar 2026 10:22:47 +0100
Subject: [PATCH 23/38] Implement xad AST based include

---
 .../AsciiDocCore/XADAttributeValue.swift      |  89 ---
 .../Sources/AsciiDocCore/XADOptions.swift     |  23 -
 .../TypedAttributesTests.swift                |  64 --
 Sources/AsciiDocCore/XADProcessor.swift       | 579 +++++++++++++++---
 .../Fixtures/xinclude-block.adoc              |   5 +
 .../Fixtures/xinclude-blocks.adoc             |   3 +
 .../Fixtures/xinclude-effects.adoc            |   3 +
 .../Fixtures/xinclude-inline.adoc             |   1 +
 .../AsciiDocCoreTests/XADXIncludeTests.swift  | 136 ++++
 9 files changed, 651 insertions(+), 252 deletions(-)
 delete mode 100644 .swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADAttributeValue.swift
 delete mode 100644 .swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADOptions.swift
 delete mode 100644 .swiftpm/xcode/AsciiDoc-Swift/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
 create mode 100644 Tests/AsciiDocCoreTests/Fixtures/xinclude-block.adoc
 create mode 100644 Tests/AsciiDocCoreTests/Fixtures/xinclude-blocks.adoc
 create mode 100644 Tests/AsciiDocCoreTests/Fixtures/xinclude-effects.adoc
 create mode 100644 Tests/AsciiDocCoreTests/Fixtures/xinclude-inline.adoc
 create mode 100644 Tests/AsciiDocCoreTests/XADXIncludeTests.swift

diff --git a/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADAttributeValue.swift b/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADAttributeValue.swift
deleted file mode 100644
index af6b209..0000000
--- a/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADAttributeValue.swift
+++ /dev/null
@@ -1,89 +0,0 @@
-//
-// Copyright (c) 2026 Mattias Holm
-// SPDX-License-Identifier: Apache-2.0
-//
-
-import Foundation
-
-public enum XADAttributeValue: Sendable, Equatable {
-    case dictionary([String: XADAttributeValue])
-    case array([XADAttributeValue])
-    case string(String)
-    case number(Double)
-    case bool(Bool)
-    case null
-
-    static func parse(from raw: String, xadOptions: XADOptions) -> XADAttributeValue? {
-        guard xadOptions.enabled else { return nil }
-        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard let first = trimmed.first, first == "{" || first == "[" else { return nil }
-        guard let data = trimmed.data(using: .utf8) else { return nil }
-
-        var options: JSONSerialization.ReadingOptions = []
-        if #available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *) {
-            options.insert(.json5Allowed)
-        }
-
-        do {
-            let obj = try JSONSerialization.jsonObject(with: data, options: options)
-            return XADAttributeValue.fromJSON(obj)
-        } catch {
-            return nil
-        }
-    }
-
-    static func fromJSON(_ value: Any) -> XADAttributeValue? {
-        switch value {
-        case let dict as [String: Any]:
-            var mapped: [String: XADAttributeValue] = [:]
-            for (key, val) in dict {
-                if let converted = fromJSON(val) {
-                    mapped[key] = converted
-                } else {
-                    return nil
-                }
-            }
-            return .dictionary(mapped)
-        case let array as [Any]:
-            var mapped: [XADAttributeValue] = []
-            mapped.reserveCapacity(array.count)
-            for val in array {
-                guard let converted = fromJSON(val) else { return nil }
-                mapped.append(converted)
-            }
-            return .array(mapped)
-        case let str as String:
-            return .string(str)
-        case let num as NSNumber:
-            if CFGetTypeID(num) == CFBooleanGetTypeID() {
-                return .bool(num.boolValue)
-            }
-            return .number(num.doubleValue)
-        case _ as NSNull:
-            return .null
-        default:
-            return nil
-        }
-    }
-
-    func toJSONCompatible() -> Any {
-        switch self {
-        case .dictionary(let dict):
-            var out: [String: Any] = [:]
-            for (key, value) in dict {
-                out[key] = value.toJSONCompatible()
-            }
-            return out
-        case .array(let array):
-            return array.map { $0.toJSONCompatible() }
-        case .string(let value):
-            return value
-        case .number(let value):
-            return value
-        case .bool(let value):
-            return value
-        case .null:
-            return NSNull()
-        }
-    }
-}
diff --git a/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADOptions.swift b/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADOptions.swift
deleted file mode 100644
index 9343084..0000000
--- a/.swiftpm/xcode/AsciiDoc-Swift/Sources/AsciiDocCore/XADOptions.swift
+++ /dev/null
@@ -1,23 +0,0 @@
-//
-// Copyright (c) 2026 Mattias Holm
-// SPDX-License-Identifier: Apache-2.0
-//
-
-public struct XADOptions: Sendable, Equatable {
-    public var enabled: Bool
-    public var strict: Bool
-    public var pagedJS: Bool
-    public var templatePath: String?
-
-    public init(
-        enabled: Bool = false,
-        strict: Bool = false,
-        pagedJS: Bool = false,
-        templatePath: String? = nil
-    ) {
-        self.enabled = enabled
-        self.strict = strict
-        self.pagedJS = pagedJS
-        self.templatePath = templatePath
-    }
-}
diff --git a/.swiftpm/xcode/AsciiDoc-Swift/Tests/AsciiDocCoreTests/TypedAttributesTests.swift b/.swiftpm/xcode/AsciiDoc-Swift/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
deleted file mode 100644
index dbcb032..0000000
--- a/.swiftpm/xcode/AsciiDoc-Swift/Tests/AsciiDocCoreTests/TypedAttributesTests.swift
+++ /dev/null
@@ -1,64 +0,0 @@
-import Testing
-@testable import AsciiDocCore
-
-@Test func typedAttributesParseStandardJSON() {
-    let source = """
-    :page: {"size":"A4","margins":{"top":"24mm","right":"22mm"}}
-    :grid: {"columns":["2fr","1fr"],"gutter":"8mm"}
-    """
-    let parser = AdocParser()
-    let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
-
-    guard let page = doc.typedAttributes["page"] else {
-        #expect(false, "Expected typed attribute 'page' to be parsed.")
-        return
-    }
-    if case .dictionary(let pageDict) = page {
-        #expect(pageDict["size"] == .string("A4"))
-        if case .dictionary(let margins)? = pageDict["margins"] {
-            #expect(margins["top"] == .string("24mm"))
-            #expect(margins["right"] == .string("22mm"))
-        } else {
-            #expect(false, "Expected margins to be a dictionary.")
-        }
-    } else {
-        #expect(false, "Expected 'page' to be a dictionary.")
-    }
-
-    if case .dictionary(let grid)? = doc.typedAttributes["grid"] {
-        if case .array(let cols)? = grid["columns"] {
-            #expect(cols.count == 2)
-            #expect(cols.first == .string("2fr"))
-            #expect(cols.last == .string("1fr"))
-        } else {
-            #expect(false, "Expected grid.columns to be an array.")
-        }
-    } else {
-        #expect(false, "Expected typed attribute 'grid' to be a dictionary.")
-    }
-}
-
-@Test func typedAttributesParseJSON5WhenAvailable() {
-    if #available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *) {
-        let source = """
-        :page: {size:"A4", margins:{top:"24mm"}}
-        """
-        let parser = AdocParser()
-        let doc = parser.parse(text: source, xadOptions: XADOptions(enabled: true))
-
-        guard let page = doc.typedAttributes["page"] else {
-            #expect(false, "Expected typed attribute 'page' to be parsed with JSON5 syntax.")
-            return
-        }
-        if case .dictionary(let pageDict) = page {
-            #expect(pageDict["size"] == .string("A4"))
-            if case .dictionary(let margins)? = pageDict["margins"] {
-                #expect(margins["top"] == .string("24mm"))
-            } else {
-                #expect(false, "Expected margins to be a dictionary.")
-            }
-        } else {
-            #expect(false, "Expected 'page' to be a dictionary.")
-        }
-    }
-}
diff --git a/Sources/AsciiDocCore/XADProcessor.swift b/Sources/AsciiDocCore/XADProcessor.swift
index 1ba08c8..7791ad0 100644
--- a/Sources/AsciiDocCore/XADProcessor.swift
+++ b/Sources/AsciiDocCore/XADProcessor.swift
@@ -38,7 +38,30 @@ private struct MacroDefinition {
 }
 
 public struct XADProcessor: Sendable {
-    public init() {}
+    public struct Options: Sendable {
+        public var sourceURL: URL?
+        public var includeResolvers: [IncludeResolver]
+        public var safeMode: Preprocessor.SafeMode
+        public var allowURIRead: Bool
+
+        public init(
+            sourceURL: URL? = nil,
+            includeResolvers: [IncludeResolver] = [],
+            safeMode: Preprocessor.SafeMode = .unsafe,
+            allowURIRead: Bool = true
+        ) {
+            self.sourceURL = sourceURL?.standardizedFileURL
+            self.includeResolvers = includeResolvers
+            self.safeMode = safeMode
+            self.allowURIRead = allowURIRead
+        }
+    }
+
+    private let options: Options
+
+    public init(options: Options = .init()) {
+        self.options = options
+    }
 
     public func apply(document: AdocDocument) -> AdocDocument {
         var env = AttrEnv(
@@ -47,7 +70,7 @@ public struct XADProcessor: Sendable {
             xadOptions: document.xadOptions
         )
         var warnings = document.warnings
-        let (macroDefs, strippedBlocks) = collectMacroDefinitions(
+        var (macroDefs, strippedBlocks) = collectMacroDefinitions(
             from: document.blocks,
             warnings: &warnings
         )
@@ -56,8 +79,10 @@ public struct XADProcessor: Sendable {
             env: &env,
             warnings: &warnings,
             locals: [:],
-            macros: macroDefs,
-            macroStack: []
+            macros: &macroDefs,
+            macroStack: [],
+            includeStack: [],
+            sourceURL: options.sourceURL
         )
         var updated = document
         updated.blocks = processed
@@ -74,8 +99,10 @@ private extension XADProcessor {
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
         locals: [String: XADAttributeValue],
-        macros: [String: MacroDefinition],
-        macroStack: [String]
+        macros: inout [String: MacroDefinition],
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
     ) -> [AdocBlock] {
         var result: [AdocBlock] = []
         var index = 0
@@ -93,6 +120,25 @@ private extension XADProcessor {
                     index += 1
                     continue
                 }
+                let lowered = name.lowercased()
+                if lowered == "xinclude" {
+                    if let expanded = expandXIncludeBlock(
+                        macro,
+                        env: &env,
+                        warnings: &warnings,
+                        locals: locals,
+                        macros: &macros,
+                        macroStack: macroStack,
+                        includeStack: includeStack,
+                        sourceURL: sourceURL
+                    ) {
+                        result.append(contentsOf: expanded)
+                    } else {
+                        result.append(block)
+                    }
+                    index += 1
+                    continue
+                }
                 if let definition = macros[name] {
                     switch definition.kind {
                     case .block:
@@ -106,8 +152,10 @@ private extension XADProcessor {
                             env: &env,
                             warnings: &warnings,
                             locals: locals,
-                            macros: macros,
+                            macros: &macros,
                             macroStack: macroStack,
+                            includeStack: includeStack,
+                            sourceURL: sourceURL,
                             bodyBlocks: bodyBlocks
                         )
                         result.append(contentsOf: expanded)
@@ -125,7 +173,6 @@ private extension XADProcessor {
                     continue
                 }
 
-                let lowered = name.lowercased()
                 if lowered == "if" {
                     let (endIndex, output) = expandIf(
                         from: index,
@@ -133,8 +180,10 @@ private extension XADProcessor {
                         env: &env,
                         warnings: &warnings,
                         locals: locals,
-                        macros: macros,
-                        macroStack: macroStack
+                        macros: &macros,
+                        macroStack: macroStack,
+                        includeStack: includeStack,
+                        sourceURL: sourceURL
                     )
                     result.append(contentsOf: output)
                     index = endIndex + 1
@@ -147,8 +196,10 @@ private extension XADProcessor {
                         env: &env,
                         warnings: &warnings,
                         locals: locals,
-                        macros: macros,
-                        macroStack: macroStack
+                        macros: &macros,
+                        macroStack: macroStack,
+                        includeStack: includeStack,
+                        sourceURL: sourceURL
                     )
                     result.append(contentsOf: output)
                     index = endIndex + 1
@@ -191,8 +242,10 @@ private extension XADProcessor {
                 env: &env,
                 warnings: &warnings,
                 locals: locals,
-                macros: macros,
-                macroStack: macroStack
+                macros: &macros,
+                macroStack: macroStack,
+                includeStack: includeStack,
+                sourceURL: sourceURL
             )
             result.append(transformed)
             index += 1
@@ -527,8 +580,10 @@ private extension XADProcessor {
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
         locals: [String: XADAttributeValue],
-        macros: [String: MacroDefinition],
+        macros: inout [String: MacroDefinition],
         macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?,
         bodyBlocks: [AdocBlock]
     ) -> [AdocBlock] {
         if macroStack.contains(definition.name) {
@@ -584,8 +639,10 @@ private extension XADProcessor {
             env: &env,
             warnings: &warnings,
             locals: macroLocals,
-            macros: macros,
-            macroStack: macroStack + [definition.name]
+            macros: &macros,
+            macroStack: macroStack + [definition.name],
+            includeStack: includeStack,
+            sourceURL: sourceURL
         )
     }
 
@@ -705,12 +762,347 @@ private extension XADProcessor {
         }
     }
 
+    func includeBaseDirectory(for sourceURL: URL?) -> URL? {
+        guard let sourceURL else { return nil }
+        if sourceURL.hasDirectoryPath { return sourceURL }
+        var isDirectory: ObjCBool = false
+        if FileManager.default.fileExists(atPath: sourceURL.path, isDirectory: &isDirectory), isDirectory.boolValue {
+            return sourceURL
+        }
+        return sourceURL.deletingLastPathComponent()
+    }
+
+    func includeResolvers(for sourceURL: URL?) -> [IncludeResolver] {
+        if options.includeResolvers.isEmpty {
+            let resolver = FileSystemIncludeResolver(
+                rootDirectory: includeBaseDirectory(for: sourceURL),
+                allowURIRead: options.allowURIRead,
+                safeMode: options.safeMode
+            )
+            return [resolver]
+        }
+        return options.includeResolvers
+    }
+
+    func resolveIncludeTarget(
+        _ rawTarget: String?,
+        env: AttrEnv,
+        locals: [String: XADAttributeValue],
+        warnings: inout [AdocWarning],
+        span: AdocRange?
+    ) -> String? {
+        guard let rawTarget, !rawTarget.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            warnings.append(
+                AdocWarning(
+                    message: "xinclude missing target",
+                    span: span
+                )
+            )
+            return nil
+        }
+        let expanded = expandString(rawTarget, env: env, locals: locals)
+        let normalized = stripSurroundingQuotes(expanded.trimmingCharacters(in: .whitespacesAndNewlines))
+        if normalized.isEmpty {
+            warnings.append(
+                AdocWarning(
+                    message: "xinclude missing target",
+                    span: span
+                )
+            )
+            return nil
+        }
+        return normalized
+    }
+
+    func resolveIncludeResult(target: String, sourceURL: URL?) -> IncludeResult? {
+        let sourceDirectory = includeBaseDirectory(for: sourceURL)
+        for resolver in includeResolvers(for: sourceURL) {
+            if let result = resolver.resolve(target: target, from: sourceDirectory) {
+                return result
+            }
+        }
+        guard options.safeMode != .secure else { return nil }
+        if let url = URL(string: target), url.scheme != nil, url.scheme != "file" {
+            return nil
+        }
+        let baseDirectory = sourceDirectory
+            ?? includeBaseDirectory(for: options.sourceURL)
+            ?? URL(fileURLWithPath: FileManager.default.currentDirectoryPath, isDirectory: true)
+        let resolved = URL(fileURLWithPath: target, relativeTo: baseDirectory).standardizedFileURL
+        if options.safeMode == .safe {
+            let allowed = resolved.path.hasPrefix(baseDirectory.standardizedFileURL.path)
+            if !allowed { return nil }
+        }
+        guard let text = try? String(contentsOf: resolved, encoding: .utf8) else { return nil }
+        return IncludeResult(
+            content: text,
+            directory: resolved.deletingLastPathComponent(),
+            filePath: resolved.path
+        )
+    }
+
+    func resolveIncludeSourceURL(from result: IncludeResult) -> URL? {
+        if let filePath = result.filePath {
+            if let url = URL(string: filePath), url.scheme != nil {
+                return url
+            }
+            return URL(fileURLWithPath: filePath).standardizedFileURL
+        }
+        return result.directory?.standardizedFileURL
+    }
+
+    func parseXIncludeParams(
+        _ raw: String?,
+        env: AttrEnv,
+        locals: [String: XADAttributeValue],
+        warnings: inout [AdocWarning],
+        span: AdocRange?
+    ) -> [String: XADAttributeValue] {
+        guard let raw, !raw.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            return [:]
+        }
+        let parsed = parseDocValue(raw, env: env, locals: locals)
+        guard case .dictionary(let dict) = parsed else {
+            warnings.append(
+                AdocWarning(
+                    message: "xinclude params must be a dictionary",
+                    span: span
+                )
+            )
+            return [:]
+        }
+        return dict
+    }
+
+    func expandXIncludeBlocks(
+        target: String,
+        attributes: [String: String],
+        span: AdocRange?,
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue],
+        macros: inout [String: MacroDefinition],
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
+    ) -> [AdocBlock]? {
+        guard let result = resolveIncludeResult(target: target, sourceURL: sourceURL) else {
+            warnings.append(
+                AdocWarning(
+                    message: "xinclude could not resolve target: \(target)",
+                    span: span
+                )
+            )
+            return nil
+        }
+        let includeID = result.filePath ?? target
+        if includeStack.contains(includeID) {
+            warnings.append(
+                AdocWarning(
+                    message: "xinclude recursion detected: \(includeID)",
+                    span: span
+                )
+            )
+            return nil
+        }
+
+        let includeURL = resolveIncludeSourceURL(from: result)
+        let parser = AdocParser()
+        let preprocessorOptions = Preprocessor.Options(
+            sourceURL: includeURL,
+            safeMode: options.safeMode,
+            allowURIRead: options.allowURIRead,
+            includeResolvers: includeResolvers(for: includeURL ?? sourceURL)
+        )
+        let includedDoc = parser.parse(
+            text: result.content,
+            attributes: env.values,
+            lockedAttributeNames: [],
+            includeHeaderDerivedAttributes: true,
+            preprocessorOptions: preprocessorOptions,
+            xadOptions: env.xadOptions
+        )
+        warnings.append(contentsOf: includedDoc.warnings)
+
+        let (includedDefs, strippedBlocks) = collectMacroDefinitions(from: includedDoc.blocks, warnings: &warnings)
+        for (name, def) in includedDefs {
+            if macros[name] != nil {
+                warnings.append(
+                    AdocWarning(
+                        message: "macro redefinition: \(name)",
+                        span: def.span
+                    )
+                )
+            }
+            macros[name] = def
+        }
+
+        let effects = parseMacroEffects(attributes["effects"], warnings: &warnings, span: span)
+        if !effects.allowsAll {
+            let usedEffects = collectMacroEffects(from: strippedBlocks)
+            let missingEffects = usedEffects.subtracting(effects.allowed)
+            if !missingEffects.isEmpty {
+                let ordered = missingEffects.sorted().joined(separator: ", ")
+                warnings.append(
+                    AdocWarning(
+                        message: "xinclude uses effects not declared: \(ordered)",
+                        span: span
+                    )
+                )
+            }
+        }
+
+        let paramLocals = parseXIncludeParams(attributes["params"], env: env, locals: locals, warnings: &warnings, span: span)
+        let mergedLocals = mergeMacroLocals(base: locals, params: paramLocals, warnings: &warnings, span: span)
+
+        return processBlocks(
+            strippedBlocks,
+            env: &env,
+            warnings: &warnings,
+            locals: mergedLocals,
+            macros: &macros,
+            macroStack: macroStack,
+            includeStack: includeStack + [includeID],
+            sourceURL: includeURL ?? sourceURL
+        )
+    }
+
+    func expandXIncludeBlock(
+        _ macro: AdocBlockMacro,
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue],
+        macros: inout [String: MacroDefinition],
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
+    ) -> [AdocBlock]? {
+        let target = resolveIncludeTarget(
+            macro.target ?? macro.attributes["target"],
+            env: env,
+            locals: locals,
+            warnings: &warnings,
+            span: macro.span
+        )
+        guard let target else { return nil }
+        return expandXIncludeBlocks(
+            target: target,
+            attributes: macro.attributes,
+            span: macro.span,
+            env: &env,
+            warnings: &warnings,
+            locals: locals,
+            macros: &macros,
+            macroStack: macroStack,
+            includeStack: includeStack,
+            sourceURL: sourceURL
+        )
+    }
+
+    func trimInlineWhitespace(_ inlines: [AdocInline]) -> [AdocInline] {
+        var trimmed = inlines
+        let ws = CharacterSet.whitespacesAndNewlines
+
+        func ltrim(_ value: String) -> String {
+            var scalars = value.unicodeScalars
+            while let first = scalars.first, ws.contains(first) {
+                scalars.removeFirst()
+            }
+            return String(scalars)
+        }
+
+        func rtrim(_ value: String) -> String {
+            var scalars = value.unicodeScalars
+            while let last = scalars.last, ws.contains(last) {
+                scalars.removeLast()
+            }
+            return String(scalars)
+        }
+
+        while let first = trimmed.first {
+            guard case .text(let text, let span) = first else { break }
+            let cleaned = ltrim(text)
+            if cleaned.isEmpty {
+                trimmed.removeFirst()
+                continue
+            }
+            if cleaned != text {
+                trimmed[0] = .text(cleaned, span: span)
+            }
+            break
+        }
+
+        while let last = trimmed.last {
+            guard case .text(let text, let span) = last else { break }
+            let cleaned = rtrim(text)
+            if cleaned.isEmpty {
+                trimmed.removeLast()
+                continue
+            }
+            if cleaned != text {
+                trimmed[trimmed.count - 1] = .text(cleaned, span: span)
+            }
+            break
+        }
+
+        return trimmed
+    }
+
+    func expandXIncludeInline(
+        target: String?,
+        attributes: [String: String],
+        span: AdocRange?,
+        env: inout AttrEnv,
+        warnings: inout [AdocWarning],
+        locals: [String: XADAttributeValue],
+        macros: inout [String: MacroDefinition],
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
+    ) -> [AdocInline]? {
+        let resolved = resolveIncludeTarget(
+            target,
+            env: env,
+            locals: locals,
+            warnings: &warnings,
+            span: span
+        )
+        guard let resolved else { return nil }
+        guard let blocks = expandXIncludeBlocks(
+            target: resolved,
+            attributes: attributes,
+            span: span,
+            env: &env,
+            warnings: &warnings,
+            locals: locals,
+            macros: &macros,
+            macroStack: macroStack,
+            includeStack: includeStack,
+            sourceURL: sourceURL
+        ) else {
+            return nil
+        }
+        guard blocks.count == 1, case .paragraph(let para) = blocks[0] else {
+            warnings.append(
+                AdocWarning(
+                    message: "inline xinclude must resolve to a single paragraph: \(resolved)",
+                    span: span
+                )
+            )
+            return nil
+        }
+        return trimInlineWhitespace(para.text.inlines)
+    }
+
     func expandInlineMacros(
         _ inlines: [AdocInline],
-        env: AttrEnv,
-        macros: [String: MacroDefinition],
+        env: inout AttrEnv,
         warnings: inout [AdocWarning],
-        macroStack: [String]
+        locals: [String: XADAttributeValue],
+        macros: inout [String: MacroDefinition],
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
     ) -> [AdocInline] {
         var result: [AdocInline] = []
         result.reserveCapacity(inlines.count)
@@ -718,33 +1110,54 @@ private extension XADProcessor {
         for inline in inlines {
             switch inline {
             case .strong(let xs, let span):
-                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(xs, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.strong(mapped, span: span))
             case .emphasis(let xs, let span):
-                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(xs, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.emphasis(mapped, span: span))
             case .mono(let xs, let span):
-                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(xs, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.mono(mapped, span: span))
             case .mark(let xs, let span):
-                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(xs, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.mark(mapped, span: span))
             case .superscript(let xs, let span):
-                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(xs, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.superscript(mapped, span: span))
             case .subscript(let xs, let span):
-                let mapped = expandInlineMacros(xs, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(xs, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.subscript(mapped, span: span))
             case .link(let target, let text, let span):
-                let mapped = expandInlineMacros(text, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(text, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.link(target: target, text: mapped, span: span))
             case .xref(let target, let text, let span):
-                let mapped = expandInlineMacros(text, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(text, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.xref(target: target, text: mapped, span: span))
             case .footnote(let content, let ref, let id, let span):
-                let mapped = expandInlineMacros(content, env: env, macros: macros, warnings: &warnings, macroStack: macroStack)
+                let mapped = expandInlineMacros(content, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 result.append(.footnote(content: mapped, ref: ref, id: id, span: span))
-            case .inlineMacro(let name, _, let body, let span):
+            case .inlineMacro(let name, let target, let body, let span):
+                let lowered = name.lowercased()
+                if lowered == "xinclude" {
+                    let args = parseMacroAttributeList(body)
+                    if let expanded = expandXIncludeInline(
+                        target: target,
+                        attributes: args,
+                        span: span,
+                        env: &env,
+                        warnings: &warnings,
+                        locals: locals,
+                        macros: &macros,
+                        macroStack: macroStack,
+                        includeStack: includeStack,
+                        sourceURL: sourceURL
+                    ) {
+                        result.append(contentsOf: expanded)
+                    } else {
+                        result.append(inline)
+                    }
+                    continue
+                }
                 if let definition = macros[name] {
                     if definition.kind == .inline {
                         if macroStack.contains(definition.name) {
@@ -786,10 +1199,13 @@ private extension XADProcessor {
                         }
                         let mapped = expandInlineMacros(
                             expandedInlines,
-                            env: macroEnv,
-                            macros: macros,
+                            env: &macroEnv,
                             warnings: &warnings,
-                            macroStack: macroStack + [definition.name]
+                            locals: locals,
+                            macros: &macros,
+                            macroStack: macroStack + [definition.name],
+                            includeStack: includeStack,
+                            sourceURL: sourceURL
                         )
                         result.append(contentsOf: mapped)
                     } else {
@@ -817,36 +1233,38 @@ private extension XADProcessor {
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
         locals: [String: XADAttributeValue],
-        macros: [String: MacroDefinition],
-        macroStack: [String]
+        macros: inout [String: MacroDefinition],
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
     ) -> AdocBlock {
         switch block {
         case .section(var section):
-            section.title = expandText(section.title, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
-            section.blocks = processBlocks(section.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+            section.title = expandText(section.title, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
+            section.blocks = processBlocks(section.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .section(section)
 
         case .paragraph(var para):
-            para.text = expandText(para.text, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+            para.text = expandText(para.text, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .paragraph(para)
 
         case .listing(var listing):
-            listing.text = expandText(listing.text, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+            listing.text = expandText(listing.text, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .listing(listing)
 
         case .literalBlock(var literal):
-            literal.text = expandText(literal.text, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+            literal.text = expandText(literal.text, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .literalBlock(literal)
 
         case .discreteHeading(var heading):
-            heading.title = expandText(heading.title, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+            heading.title = expandText(heading.title, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .discreteHeading(heading)
 
         case .list(var list):
             list.items = list.items.map { item in
                 var copy = item
-                copy.principal = expandText(item.principal, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
-                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+                copy.principal = expandText(item.principal, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
+                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 return copy
             }
             return .list(list)
@@ -854,50 +1272,50 @@ private extension XADProcessor {
         case .dlist(var dlist):
             dlist.items = dlist.items.map { item in
                 var copy = item
-                copy.term = expandText(item.term, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+                copy.term = expandText(item.term, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 if let principal = item.principal {
-                    copy.principal = expandText(principal, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+                    copy.principal = expandText(principal, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 }
-                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+                copy.blocks = processBlocks(item.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 return copy
             }
             return .dlist(dlist)
 
         case .sidebar(var sidebar):
-            sidebar.title = sidebar.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            sidebar.blocks = processBlocks(sidebar.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+            sidebar.title = sidebar.title.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            sidebar.blocks = processBlocks(sidebar.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .sidebar(sidebar)
 
         case .example(var example):
-            example.title = example.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            example.blocks = processBlocks(example.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+            example.title = example.title.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            example.blocks = processBlocks(example.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .example(example)
 
         case .quote(var quote):
-            quote.title = quote.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            quote.attribution = quote.attribution.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            quote.citetitle = quote.citetitle.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            quote.blocks = processBlocks(quote.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+            quote.title = quote.title.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            quote.attribution = quote.attribution.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            quote.citetitle = quote.citetitle.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            quote.blocks = processBlocks(quote.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .quote(quote)
 
         case .open(var open):
-            open.title = open.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            open.blocks = processBlocks(open.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+            open.title = open.title.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            open.blocks = processBlocks(open.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .open(open)
 
         case .admonition(var admonition):
-            admonition.title = admonition.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            admonition.blocks = processBlocks(admonition.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+            admonition.title = admonition.title.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            admonition.blocks = processBlocks(admonition.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .admonition(admonition)
 
         case .verse(var verse):
-            verse.title = verse.title.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            verse.attribution = verse.attribution.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
-            verse.citetitle = verse.citetitle.map { expandText($0, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack) }
+            verse.title = verse.title.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            verse.attribution = verse.attribution.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
+            verse.citetitle = verse.citetitle.map { expandText($0, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL) }
             if let text = verse.text {
-                verse.text = expandText(text, env: env, locals: locals, macros: macros, warnings: &warnings, macroStack: macroStack)
+                verse.text = expandText(text, env: &env, locals: locals, macros: &macros, warnings: &warnings, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             }
-            verse.blocks = processBlocks(verse.blocks, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+            verse.blocks = processBlocks(verse.blocks, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
             return .verse(verse)
 
         default:
@@ -911,8 +1329,10 @@ private extension XADProcessor {
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
         locals: [String: XADAttributeValue],
-        macros: [String: MacroDefinition],
-        macroStack: [String]
+        macros: inout [String: MacroDefinition],
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
     ) -> (Int, [AdocBlock]) {
         guard case .blockMacro(let ifMacro) = blocks[startIndex] else {
             return (startIndex, [])
@@ -1038,7 +1458,7 @@ private extension XADProcessor {
             }
         }
 
-        let processed = processBlocks(selected, env: &env, warnings: &warnings, locals: locals, macros: macros, macroStack: macroStack)
+        let processed = processBlocks(selected, env: &env, warnings: &warnings, locals: locals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
         return (currentIndex, processed)
     }
 
@@ -1048,8 +1468,10 @@ private extension XADProcessor {
         env: inout AttrEnv,
         warnings: inout [AdocWarning],
         locals: [String: XADAttributeValue],
-        macros: [String: MacroDefinition],
-        macroStack: [String]
+        macros: inout [String: MacroDefinition],
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
     ) -> (Int, [AdocBlock]) {
         guard case .blockMacro(let forMacro) = blocks[startIndex] else {
             return (startIndex, [])
@@ -1167,7 +1589,7 @@ private extension XADProcessor {
                 var loopLocals = locals
                 loopLocals[indexName] = .number(Double(idx))
                 loopLocals[itemName] = value
-                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals, macros: macros, macroStack: macroStack)
+                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 expanded.append(contentsOf: processed)
             }
 
@@ -1193,7 +1615,7 @@ private extension XADProcessor {
                 var loopLocals = locals
                 loopLocals[keyName] = .string(key)
                 loopLocals[valueName] = value
-                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals, macros: macros, macroStack: macroStack)
+                let processed = processBlocks(body, env: &env, warnings: &warnings, locals: loopLocals, macros: &macros, macroStack: macroStack, includeStack: includeStack, sourceURL: sourceURL)
                 expanded.append(contentsOf: processed)
             }
 
@@ -1468,20 +1890,25 @@ private extension XADProcessor {
 
     func expandText(
         _ text: AdocText,
-        env: AttrEnv,
+        env: inout AttrEnv,
         locals: [String: XADAttributeValue],
-        macros: [String: MacroDefinition],
+        macros: inout [String: MacroDefinition],
         warnings: inout [AdocWarning],
-        macroStack: [String]
+        macroStack: [String],
+        includeStack: [String],
+        sourceURL: URL?
     ) -> AdocText {
         let localEnv = localEnvWithLocals(env, locals: locals)
         let attributedInlines = text.inlines.map { $0.applyingAttributes(using: localEnv) }
         let expandedInlines = expandInlineMacros(
             attributedInlines,
-            env: localEnv,
-            macros: macros,
+            env: &env,
             warnings: &warnings,
-            macroStack: macroStack
+            locals: locals,
+            macros: &macros,
+            macroStack: macroStack,
+            includeStack: includeStack,
+            sourceURL: sourceURL
         )
         return AdocText(inlines: expandedInlines, span: text.span)
     }
diff --git a/Tests/AsciiDocCoreTests/Fixtures/xinclude-block.adoc b/Tests/AsciiDocCoreTests/Fixtures/xinclude-block.adoc
new file mode 100644
index 0000000..e6464e5
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/Fixtures/xinclude-block.adoc
@@ -0,0 +1,5 @@
+macro::shout[params="word"]
+{word}!
+endmacro::shout[]
+
+Included paragraph.
diff --git a/Tests/AsciiDocCoreTests/Fixtures/xinclude-blocks.adoc b/Tests/AsciiDocCoreTests/Fixtures/xinclude-blocks.adoc
new file mode 100644
index 0000000..4175617
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/Fixtures/xinclude-blocks.adoc
@@ -0,0 +1,3 @@
+== Included Section
+
+Paragraph in section.
diff --git a/Tests/AsciiDocCoreTests/Fixtures/xinclude-effects.adoc b/Tests/AsciiDocCoreTests/Fixtures/xinclude-effects.adoc
new file mode 100644
index 0000000..cdbb4a4
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/Fixtures/xinclude-effects.adoc
@@ -0,0 +1,3 @@
+docset::[name="doc.status", value="draft"]
+
+Effects paragraph.
diff --git a/Tests/AsciiDocCoreTests/Fixtures/xinclude-inline.adoc b/Tests/AsciiDocCoreTests/Fixtures/xinclude-inline.adoc
new file mode 100644
index 0000000..39a4171
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/Fixtures/xinclude-inline.adoc
@@ -0,0 +1 @@
+Inline ok
diff --git a/Tests/AsciiDocCoreTests/XADXIncludeTests.swift b/Tests/AsciiDocCoreTests/XADXIncludeTests.swift
new file mode 100644
index 0000000..f2628a2
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/XADXIncludeTests.swift
@@ -0,0 +1,136 @@
+import Testing
+import AsciiDocCore
+import Foundation
+
+private func paragraphTexts(from blocks: [AdocBlock]) -> [String] {
+    var out: [String] = []
+    for block in blocks {
+        switch block {
+        case .paragraph(let para):
+            out.append(para.text.plain)
+        case .section(let section):
+            out.append(contentsOf: paragraphTexts(from: section.blocks))
+        case .sidebar(let sidebar):
+            out.append(contentsOf: paragraphTexts(from: sidebar.blocks))
+        case .example(let example):
+            out.append(contentsOf: paragraphTexts(from: example.blocks))
+        case .quote(let quote):
+            out.append(contentsOf: paragraphTexts(from: quote.blocks))
+        case .open(let open):
+            out.append(contentsOf: paragraphTexts(from: open.blocks))
+        case .admonition(let admonition):
+            out.append(contentsOf: paragraphTexts(from: admonition.blocks))
+        case .verse(let verse):
+            if let text = verse.text {
+                out.append(text.plain)
+            }
+            out.append(contentsOf: paragraphTexts(from: verse.blocks))
+        default:
+            continue
+        }
+    }
+    return out
+}
+
+private func containsInlineMacro(_ inlines: [AdocInline], name: String) -> Bool {
+    for inline in inlines {
+        switch inline {
+        case .inlineMacro(let macroName, _, _, _):
+            if macroName == name { return true }
+        case .strong(let xs, _),
+             .emphasis(let xs, _),
+             .mono(let xs, _),
+             .mark(let xs, _),
+             .superscript(let xs, _),
+             .subscript(let xs, _):
+            if containsInlineMacro(xs, name: name) { return true }
+        case .link(_, let text, _),
+             .xref(_, let text, _):
+            if containsInlineMacro(text, name: name) { return true }
+        case .footnote(let content, _, _, _):
+            if containsInlineMacro(content, name: name) { return true }
+        default:
+            continue
+        }
+    }
+    return false
+}
+
+private func fixturesURL() -> URL {
+    URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent()
+        .appendingPathComponent("Fixtures")
+}
+
+private func xincludeProcessor() -> XADProcessor {
+    let fixtures = fixturesURL()
+    return XADProcessor(
+        options: .init(
+            sourceURL: fixtures,
+            includeResolvers: [FileSystemIncludeResolver(rootDirectory: fixtures)]
+        )
+    )
+}
+
+@Suite("XAD XInclude")
+struct XADXIncludeTests {
+    @Test
+    func blockXIncludeMergesMacros() {
+        let src = """
+        xinclude::xinclude-block.adoc[]
+        shout::[word=Hello]
+        """
+
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = xincludeProcessor().apply(document: doc)
+        let paras = paragraphTexts(from: processed.blocks)
+        #expect(paras.contains("Included paragraph."))
+        #expect(paras.contains("Hello!"))
+    }
+
+    @Test
+    func inlineXIncludeExpands() {
+        let src = "See xinclude:xinclude-inline.adoc[]."
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = xincludeProcessor().apply(document: doc)
+        let paras = paragraphTexts(from: processed.blocks)
+        #expect(paras.contains("See Inline ok."))
+    }
+
+    @Test
+    func inlineXIncludeRejectsBlocks() {
+        let src = "See xinclude:xinclude-blocks.adoc[]."
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = xincludeProcessor().apply(document: doc)
+        let messages = processed.warnings.map { $0.message }
+        #expect(messages.contains { $0.contains("inline xinclude must resolve to a single paragraph") })
+        if case .paragraph(let para) = processed.blocks.first {
+            #expect(containsInlineMacro(para.text.inlines, name: "xinclude"))
+        } else {
+            Issue.record("Expected paragraph block in xinclude inline test")
+        }
+    }
+
+    @Test
+    func xincludeEffectsWarning() {
+        let src = "xinclude::xinclude-effects.adoc[]"
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = xincludeProcessor().apply(document: doc)
+        let messages = processed.warnings.map { $0.message }
+        #expect(messages.contains { $0.contains("xinclude uses effects not declared") })
+    }
+
+    @Test
+    func xincludeEffectsAllAllows() {
+        let src = "xinclude::xinclude-effects.adoc[effects=all]"
+        let parser = AdocParser()
+        let doc = parser.parse(text: src, xadOptions: XADOptions(enabled: true))
+        let processed = xincludeProcessor().apply(document: doc)
+        let messages = processed.warnings.map { $0.message }
+        #expect(messages.filter { $0.contains("xinclude uses effects not declared") }.isEmpty)
+    }
+}

From a81b130402ff3bdd2d74d65ac89027e12f0050ed Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Sun, 1 Mar 2026 12:14:09 +0100
Subject: [PATCH 24/38] Add initial layout DSL parser

---
 Sources/AsciiDocCore/LayoutDSL.swift          | 607 ++++++++++++++++++
 .../LayoutDSLParserTests.swift                |  81 +++
 2 files changed, 688 insertions(+)
 create mode 100644 Sources/AsciiDocCore/LayoutDSL.swift
 create mode 100644 Tests/AsciiDocCoreTests/LayoutDSLParserTests.swift

diff --git a/Sources/AsciiDocCore/LayoutDSL.swift b/Sources/AsciiDocCore/LayoutDSL.swift
new file mode 100644
index 0000000..27e4735
--- /dev/null
+++ b/Sources/AsciiDocCore/LayoutDSL.swift
@@ -0,0 +1,607 @@
+//
+// Copyright (c) 2026 Mattias Holm
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+public enum LayoutExpr: Sendable, Equatable {
+    case node(LayoutNode)
+    case value(LayoutValue)
+}
+
+public struct LayoutProgram: Sendable, Equatable {
+    public var expressions: [LayoutExpr]
+
+    public init(expressions: [LayoutExpr]) {
+        self.expressions = expressions
+    }
+}
+
+public struct LayoutNode: Sendable, Equatable {
+    public var name: String
+    public var args: [LayoutArg]
+    public var children: [LayoutExpr]
+    public var span: AdocRange?
+
+    public init(name: String, args: [LayoutArg], children: [LayoutExpr], span: AdocRange?) {
+        self.name = name
+        self.args = args
+        self.children = children
+        self.span = span
+    }
+}
+
+public struct LayoutArg: Sendable, Equatable {
+    public var name: String?
+    public var value: LayoutExpr
+    public var span: AdocRange?
+
+    public init(name: String?, value: LayoutExpr, span: AdocRange?) {
+        self.name = name
+        self.value = value
+        self.span = span
+    }
+}
+
+public enum LayoutValue: Sendable, Equatable {
+    case string(String)
+    case number(Double)
+    case boolean(Bool)
+    case null
+    case array([LayoutValue])
+    case dict([String: LayoutValue])
+    case ref(LayoutRef)
+}
+
+public struct LayoutRef: Sendable, Equatable {
+    public var parts: [String]
+    public var index: LayoutIndex?
+
+    public init(parts: [String], index: LayoutIndex?) {
+        self.parts = parts
+        self.index = index
+    }
+}
+
+public enum LayoutIndex: Sendable, Equatable {
+    case number(Double)
+    case string(String)
+    case identifier(String)
+}
+
+public struct LayoutDSLParser: Sendable {
+    public init() {}
+
+    public func parse(text: String, span: AdocRange? = nil) -> (LayoutProgram?, [AdocWarning]) {
+        let tokenizer = LayoutDSLTokenizer(text: text)
+        var parser = LayoutDSLParserState(tokenizer: tokenizer, span: span)
+        let program = parser.parseProgram()
+        return (program, parser.warnings)
+    }
+}
+
+private enum LayoutDSLTokenKind: Equatable {
+    case identifier(String)
+    case string(String)
+    case number(Double)
+    case boolean(Bool)
+    case null
+    case lparen
+    case rparen
+    case lbracket
+    case rbracket
+    case lbrace
+    case rbrace
+    case colon
+    case comma
+    case semicolon
+    case dot
+    case eof
+}
+
+private struct LayoutDSLToken: Equatable {
+    let kind: LayoutDSLTokenKind
+    let span: AdocRange?
+}
+
+private struct LayoutDSLTokenizer {
+    private let text: String
+    private var index: String.Index
+    private var line: Int
+    private var column: Int
+
+    init(text: String) {
+        self.text = text
+        self.index = text.startIndex
+        self.line = 1
+        self.column = 1
+    }
+
+    mutating func nextToken() -> LayoutDSLToken {
+        skipWhitespaceAndComments()
+        guard index < text.endIndex else {
+            return LayoutDSLToken(kind: .eof, span: nil)
+        }
+
+        let start = position()
+        let ch = text[index]
+
+        switch ch {
+        case "(":
+            advance()
+            return token(.lparen, start: start)
+        case ")":
+            advance()
+            return token(.rparen, start: start)
+        case "[":
+            advance()
+            return token(.lbracket, start: start)
+        case "]":
+            advance()
+            return token(.rbracket, start: start)
+        case "{":
+            advance()
+            return token(.lbrace, start: start)
+        case "}":
+            advance()
+            return token(.rbrace, start: start)
+        case ":":
+            advance()
+            return token(.colon, start: start)
+        case ",":
+            advance()
+            return token(.comma, start: start)
+        case ";":
+            advance()
+            return token(.semicolon, start: start)
+        case ".":
+            advance()
+            return token(.dot, start: start)
+        case "\"", "'":
+            return readString(quote: ch, start: start)
+        case "-":
+            return readNumber(start: start)
+        default:
+            if ch.isNumber {
+                return readNumber(start: start)
+            }
+            if isIdentifierStart(ch) {
+                return readIdentifier(start: start)
+            }
+        }
+
+        advance()
+        return token(.eof, start: start)
+    }
+
+    private mutating func skipWhitespaceAndComments() {
+        while index < text.endIndex {
+            let ch = text[index]
+            if ch == "/" {
+                let next = text.index(after: index)
+                if next < text.endIndex, text[next] == "/" {
+                    advance()
+                    advance()
+                    while index < text.endIndex, text[index] != "\n" {
+                        advance()
+                    }
+                    continue
+                }
+            }
+            if ch == " " || ch == "\t" || ch == "\r" || ch == "\n" {
+                advance()
+                continue
+            }
+            break
+        }
+    }
+
+    private mutating func readIdentifier(start: AdocPos) -> LayoutDSLToken {
+        var value = String()
+        while index < text.endIndex {
+            let ch = text[index]
+            if isIdentifierPart(ch) {
+                value.append(ch)
+                advance()
+            } else {
+                break
+            }
+        }
+
+        switch value {
+        case "true":
+            return token(.boolean(true), start: start)
+        case "false":
+            return token(.boolean(false), start: start)
+        case "null":
+            return token(.null, start: start)
+        default:
+            return token(.identifier(value), start: start)
+        }
+    }
+
+    private mutating func readNumber(start: AdocPos) -> LayoutDSLToken {
+        var value = String()
+        if index < text.endIndex, text[index] == "-" {
+            value.append("-")
+            advance()
+        }
+        while index < text.endIndex, text[index].isNumber {
+            value.append(text[index])
+            advance()
+        }
+        if index < text.endIndex, text[index] == "." {
+            value.append(".")
+            advance()
+            while index < text.endIndex, text[index].isNumber {
+                value.append(text[index])
+                advance()
+            }
+        }
+        let number = Double(value) ?? 0
+        return token(.number(number), start: start)
+    }
+
+    private mutating func readString(quote: Character, start: AdocPos) -> LayoutDSLToken {
+        advance()
+        var value = String()
+        while index < text.endIndex {
+            let ch = text[index]
+            if ch == quote {
+                advance()
+                return token(.string(value), start: start)
+            }
+            if ch == "\\" {
+                let next = text.index(after: index)
+                if next < text.endIndex {
+                    value.append(text[next])
+                    advance()
+                    advance()
+                    continue
+                }
+            }
+            value.append(ch)
+            advance()
+        }
+        return token(.string(value), start: start)
+    }
+
+    private func isIdentifierStart(_ ch: Character) -> Bool {
+        return ch.isLetter || ch == "_"
+    }
+
+    private func isIdentifierPart(_ ch: Character) -> Bool {
+        return ch.isLetter || ch.isNumber || ch == "_" || ch == "-"
+    }
+
+    private mutating func advance() {
+        guard index < text.endIndex else { return }
+        if text[index] == "\n" {
+            line += 1
+            column = 1
+        } else {
+            column += 1
+        }
+        index = text.index(after: index)
+    }
+
+    private func position() -> AdocPos {
+        AdocPos(offset: index, line: line, column: column)
+    }
+
+    private func token(_ kind: LayoutDSLTokenKind, start: AdocPos) -> LayoutDSLToken {
+        let end = position()
+        let span = AdocRange(start: start, end: end)
+        return LayoutDSLToken(kind: kind, span: span)
+    }
+}
+
+private struct LayoutDSLParserState {
+    var tokenizer: LayoutDSLTokenizer
+    var lookahead: LayoutDSLToken?
+    var warnings: [AdocWarning] = []
+    let baseSpan: AdocRange?
+
+    init(tokenizer: LayoutDSLTokenizer, span: AdocRange?) {
+        self.tokenizer = tokenizer
+        self.baseSpan = span
+    }
+
+    mutating func parseProgram() -> LayoutProgram? {
+        let exprs = parseExprList(terminators: [.eof])
+        if exprs.isEmpty {
+            return nil
+        }
+        return LayoutProgram(expressions: exprs)
+    }
+
+    mutating func parseExprList(terminators: [LayoutDSLTokenKind]) -> [LayoutExpr] {
+        var exprs: [LayoutExpr] = []
+        while true {
+            let token = peek()
+            if token.kind == .eof {
+                break
+            }
+            if terminators.contains(where: { $0 == token.kind }) {
+                break
+            }
+            if let expr = parseExpr() {
+                exprs.append(expr)
+            } else {
+                _ = advance()
+            }
+            if consumeIf(.comma) || consumeIf(.semicolon) {
+                continue
+            }
+        }
+        return exprs
+    }
+
+    mutating func parseExpr() -> LayoutExpr? {
+        guard let token = peekIdentifierOrValueStart() else {
+            warn("expected expression", span: peek().span)
+            return nil
+        }
+        switch token.kind {
+        case .identifier(let name):
+            let saved = token
+            _ = advance()
+            if consumeIf(.lparen) {
+                let args = parseArgList(closing: .rparen)
+                _ = consumeExpected(.rparen, message: "expected ')' to close arguments")
+                let children = parseChildrenIfPresent()
+                let span = mergeSpan(saved.span, children.span)
+                let node = LayoutNode(name: name, args: args, children: children.nodes, span: span)
+                return .node(node)
+            }
+            if consumeIf(.lbracket) {
+                let children = parseExprList(terminators: [.rbracket, .eof])
+                _ = consumeExpected(.rbracket, message: "expected ']' to close children")
+                let span = mergeSpan(saved.span, peek().span)
+                let node = LayoutNode(name: name, args: [], children: children, span: span)
+                return .node(node)
+            }
+            return .value(parseRefFromFirst(name: name, span: saved.span))
+        default:
+            return parseValue().map { .value($0) }
+        }
+    }
+
+    mutating func parseChildrenIfPresent() -> (nodes: [LayoutExpr], span: AdocRange?) {
+        guard consumeIf(.lbracket) else { return ([], nil) }
+        let children = parseExprList(terminators: [.rbracket, .eof])
+        let closing = consumeExpected(.rbracket, message: "expected ']' to close children")
+        let span = mergeSpan(children.first?.span, closing?.span)
+        return (children, span)
+    }
+
+    mutating func parseArgList(closing: LayoutDSLTokenKind) -> [LayoutArg] {
+        var args: [LayoutArg] = []
+        while true {
+            let next = peek()
+            if next.kind == .eof { break }
+            if next.kind == closing { break }
+            if let arg = parseArg() {
+                args.append(arg)
+            } else {
+                _ = advance()
+            }
+            if consumeIf(.comma) { continue }
+        }
+        return args
+    }
+
+    mutating func parseArg() -> LayoutArg? {
+        let token = peek()
+        if case .identifier(let name) = token.kind {
+            let next = peekSecond()
+            if next.kind == .colon {
+                let saved = token
+                _ = advance()
+                _ = consumeExpected(.colon, message: "expected ':' after argument name")
+                if let expr = parseExpr() {
+                    return LayoutArg(name: name, value: expr, span: mergeSpan(saved.span, expr.span))
+                }
+                warn("expected expression after ':'", span: peek().span)
+                return LayoutArg(name: name, value: .value(.null), span: saved.span)
+            }
+        }
+
+        if let expr = parseExpr() {
+            return LayoutArg(name: nil, value: expr, span: expr.span)
+        }
+        return nil
+    }
+
+    mutating func parseValue() -> LayoutValue? {
+        let token = peek()
+        switch token.kind {
+        case .string(let value):
+            _ = advance()
+            return .string(value)
+        case .number(let value):
+            _ = advance()
+            return .number(value)
+        case .boolean(let value):
+            _ = advance()
+            return .boolean(value)
+        case .null:
+            _ = advance()
+            return .null
+        case .lbracket:
+            return parseArray()
+        case .lbrace:
+            return parseDict()
+        case .identifier(let name):
+            _ = advance()
+            return parseRefFromFirst(name: name, span: token.span)
+        default:
+            warn("expected value", span: token.span)
+            return nil
+        }
+    }
+
+    mutating func parseArray() -> LayoutValue {
+        _ = consumeExpected(.lbracket, message: "expected '[' to start array")
+        var values: [LayoutValue] = []
+        while true {
+            let next = peek()
+            if next.kind == .eof { break }
+            if next.kind == .rbracket { break }
+            if let value = parseValue() {
+                values.append(value)
+            } else {
+                _ = advance()
+            }
+            if consumeIf(.comma) { continue }
+        }
+        _ = consumeExpected(.rbracket, message: "expected ']' to close array")
+        return .array(values)
+    }
+
+    mutating func parseDict() -> LayoutValue {
+        _ = consumeExpected(.lbrace, message: "expected '{' to start dictionary")
+        var dict: [String: LayoutValue] = [:]
+        while true {
+            let next = peek()
+            if next.kind == .eof { break }
+            if next.kind == .rbrace { break }
+            guard let key = parseDictKey() else {
+                _ = advance()
+                continue
+            }
+            _ = consumeExpected(.colon, message: "expected ':' after dictionary key")
+            if let value = parseValue() {
+                dict[key] = value
+            } else {
+                dict[key] = .null
+            }
+            if consumeIf(.comma) { continue }
+        }
+        _ = consumeExpected(.rbrace, message: "expected '}' to close dictionary")
+        return .dict(dict)
+    }
+
+    mutating func parseDictKey() -> String? {
+        let token = peek()
+        switch token.kind {
+        case .identifier(let name):
+            _ = advance()
+            return name
+        case .string(let value):
+            _ = advance()
+            return value
+        default:
+            warn("expected dictionary key", span: token.span)
+            return nil
+        }
+    }
+
+    mutating func parseRefFromFirst(name: String, span: AdocRange?) -> LayoutValue {
+        var parts = [name]
+        var index: LayoutIndex? = nil
+        while true {
+            if consumeIf(.dot) {
+                if case .identifier(let nextName) = peek().kind {
+                    _ = advance()
+                    parts.append(nextName)
+                } else {
+                    warn("expected identifier after '.'", span: peek().span)
+                    break
+                }
+                continue
+            }
+            if consumeIf(.lbracket) {
+                index = parseIndex()
+                _ = consumeExpected(.rbracket, message: "expected ']' after index")
+                break
+            }
+            break
+        }
+        return .ref(LayoutRef(parts: parts, index: index))
+    }
+
+    mutating func parseIndex() -> LayoutIndex? {
+        let token = peek()
+        switch token.kind {
+        case .number(let value):
+            _ = advance()
+            return .number(value)
+        case .string(let value):
+            _ = advance()
+            return .string(value)
+        case .identifier(let value):
+            _ = advance()
+            return .identifier(value)
+        default:
+            warn("expected index value", span: token.span)
+            return nil
+        }
+    }
+
+    mutating func peek() -> LayoutDSLToken {
+        if let lookahead { return lookahead }
+        let token = tokenizer.nextToken()
+        lookahead = token
+        return token
+    }
+
+    mutating func peekSecond() -> LayoutDSLToken {
+        _ = peek()
+        var snapshot = tokenizer
+        return snapshot.nextToken()
+    }
+
+    mutating func advance() -> LayoutDSLToken {
+        let token = peek()
+        lookahead = nil
+        return token
+    }
+
+    mutating func consumeIf(_ kind: LayoutDSLTokenKind) -> Bool {
+        if peek().kind == kind {
+            _ = advance()
+            return true
+        }
+        return false
+    }
+
+    mutating func consumeExpected(_ kind: LayoutDSLTokenKind, message: String) -> LayoutDSLToken? {
+        if peek().kind == kind {
+            return advance()
+        }
+        warn(message, span: peek().span)
+        return nil
+    }
+
+    mutating func peekIdentifierOrValueStart() -> LayoutDSLToken? {
+        let token = peek()
+        switch token.kind {
+        case .identifier, .string, .number, .boolean, .null, .lbracket, .lbrace:
+            return token
+        default:
+            return nil
+        }
+    }
+
+    mutating func warn(_ message: String, span: AdocRange?) {
+        warnings.append(AdocWarning(message: message, span: span))
+    }
+
+    func mergeSpan(_ a: AdocRange?, _ b: AdocRange?) -> AdocRange? {
+        guard let a, let b else { return a ?? b }
+        return AdocRange(start: a.start, end: b.end)
+    }
+}
+
+private extension LayoutExpr {
+    var span: AdocRange? {
+        switch self {
+        case .node(let node):
+            return node.span
+        case .value:
+            return nil
+        }
+    }
+}
diff --git a/Tests/AsciiDocCoreTests/LayoutDSLParserTests.swift b/Tests/AsciiDocCoreTests/LayoutDSLParserTests.swift
new file mode 100644
index 0000000..a166bc9
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/LayoutDSLParserTests.swift
@@ -0,0 +1,81 @@
+import Testing
+import AsciiDocCore
+
+@Suite("Layout DSL Parser")
+struct LayoutDSLParserTests {
+    @Test
+    func parsesSimpleLayoutTree() {
+        let source = """
+        pages[
+          page(master:"title")[
+            stack(gap:"6mm")[
+              text(get("doctitle")),
+              flow(slot("titlemeta"))
+            ]
+          ],
+          page(master:"default")[
+            grid(def:get("grid.body"))[
+              place(area:"main")[ flow(slot("main"), scope:"chapter") ],
+              place(area:"sidebar")[ flow(slot("sidebar")) ]
+            ],
+            sink(kind:"footnote", scope:"page")
+          ]
+        ]
+        """
+        let parser = LayoutDSLParser()
+        let (program, warnings) = parser.parse(text: source)
+        #expect(warnings.isEmpty)
+        #expect(program?.expressions.isEmpty == false)
+        if case .node(let root)? = program?.expressions.first {
+            #expect(root.name == "pages")
+            #expect(root.children.count == 2)
+        } else {
+            Issue.record("Expected root pages node")
+        }
+    }
+
+    @Test
+    func supportsCommentsAndTrailingSeparators() {
+        let source = """
+        // header comment
+        pages[
+          page(master:"title")[text("Hello")], // inline comment
+        ];
+        """
+        let parser = LayoutDSLParser()
+        let (program, warnings) = parser.parse(text: source)
+        #expect(warnings.isEmpty)
+        #expect(program?.expressions.count == 1)
+    }
+
+    @Test
+    func parsesRefsAndIndexes() {
+        let source = """
+        grid(def:get("grid.body"))[text(get("style.font.body"))]
+        foo.bar[0]
+        """
+        let parser = LayoutDSLParser()
+        let (program, warnings) = parser.parse(text: source)
+        #expect(warnings.isEmpty)
+        #expect(program?.expressions.count == 2)
+    }
+
+    @Test
+    func warnsOnMissingClosers() {
+        let source = "pages[ page(master:\"title\")[ text(\"Hi\") ]"
+        let parser = LayoutDSLParser()
+        let (_, warnings) = parser.parse(text: source)
+        #expect(!warnings.isEmpty)
+    }
+
+    @Test
+    func parsesDictsAndArrays() {
+        let source = """
+        grid(def:{columns:["2fr","1fr"], rows:["auto"], colGap:"8mm"})
+        """
+        let parser = LayoutDSLParser()
+        let (program, warnings) = parser.parse(text: source)
+        #expect(warnings.isEmpty)
+        #expect(program?.expressions.count == 1)
+    }
+}

From 0725c74fa4423c6cd8b5e880290e34073e49c141 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Mon, 2 Mar 2026 07:18:11 +0100
Subject: [PATCH 25/38] Layout template ingestion and command line flags

---
 Package.swift                                 |   9 +-
 Sources/AsciiDocCore/XADOptions.swift         |  11 +-
 .../TemplateRegistry.swift                    | 133 ++++++++++++++++++
 Sources/AsciiDocRender/DocumentRender.swift   |   5 +-
 Sources/asciidoc-swift/Commands.swift         | 119 ++++++++++++++--
 Templates/xad/default/layout.xad              |   6 +
 .../TemplateRegistryTests.swift               |  41 ++++++
 7 files changed, 313 insertions(+), 11 deletions(-)
 create mode 100644 Sources/AsciiDocPagedRendering/TemplateRegistry.swift
 create mode 100644 Templates/xad/default/layout.xad
 create mode 100644 Tests/AsciiDocCoreTests/TemplateRegistryTests.swift

diff --git a/Package.swift b/Package.swift
index e2e27fe..718eb5d 100644
--- a/Package.swift
+++ b/Package.swift
@@ -19,6 +19,7 @@ let package = Package(
       .library(name: "AsciiDocExtensions", targets: ["AsciiDocExtensions"]),
       .library(name: "AsciiDocTools", targets: ["AsciiDocTools"]),
       .library(name: "AsciiDocAntora", targets: ["AsciiDocAntora"]),
+      .library(name: "AsciiDocPagedRendering", targets: ["AsciiDocPagedRendering"]),
 
       .executable(name: "asciidoc-swift", targets: ["asciidoc-swift"])
     ],
@@ -84,6 +85,11 @@ let package = Package(
             path: "Sources/AsciiDocAntora"
         ),
 
+        .target(
+            name: "AsciiDocPagedRendering",
+            dependencies: ["AsciiDocCore"],
+            path: "Sources/AsciiDocPagedRendering"
+        ),
 
         // CLI executable that the TCK will invoke
         .executableTarget(
@@ -94,6 +100,7 @@ let package = Package(
                 "AsciiDocExtensions",
                 "AsciiDocTools",
                 "AsciiDocAntora",
+                "AsciiDocPagedRendering",
                 .product(name: "ArgumentParser", package: "swift-argument-parser")
             ],
             path: "Sources/asciidoc-swift",
@@ -108,7 +115,7 @@ let package = Package(
         // Unit tests for the core; add fixture files under Tests/AsciiDocCoreTests/Fixtures as needed
         .testTarget(
             name: "AsciiDocCoreTests",
-            dependencies: ["AsciiDocCore", "AsciiDocTools", "AsciiDocRender"],
+            dependencies: ["AsciiDocCore", "AsciiDocTools", "AsciiDocRender", "AsciiDocPagedRendering"],
             path: "Tests/AsciiDocCoreTests",
             swiftSettings: [
                 .interoperabilityMode(.Cxx)
diff --git a/Sources/AsciiDocCore/XADOptions.swift b/Sources/AsciiDocCore/XADOptions.swift
index 9343084..7fb110a 100644
--- a/Sources/AsciiDocCore/XADOptions.swift
+++ b/Sources/AsciiDocCore/XADOptions.swift
@@ -8,16 +8,25 @@ public struct XADOptions: Sendable, Equatable {
     public var strict: Bool
     public var pagedJS: Bool
     public var templatePath: String?
+    public var layoutTemplate: String?
+    public var layoutTemplateBase: String?
+    public var layoutTemplateSearchPaths: [String]
 
     public init(
         enabled: Bool = false,
         strict: Bool = false,
         pagedJS: Bool = false,
-        templatePath: String? = nil
+        templatePath: String? = nil,
+        layoutTemplate: String? = nil,
+        layoutTemplateBase: String? = nil,
+        layoutTemplateSearchPaths: [String] = []
     ) {
         self.enabled = enabled
         self.strict = strict
         self.pagedJS = pagedJS
         self.templatePath = templatePath
+        self.layoutTemplate = layoutTemplate
+        self.layoutTemplateBase = layoutTemplateBase
+        self.layoutTemplateSearchPaths = layoutTemplateSearchPaths
     }
 }
diff --git a/Sources/AsciiDocPagedRendering/TemplateRegistry.swift b/Sources/AsciiDocPagedRendering/TemplateRegistry.swift
new file mode 100644
index 0000000..5334652
--- /dev/null
+++ b/Sources/AsciiDocPagedRendering/TemplateRegistry.swift
@@ -0,0 +1,133 @@
+//
+// Copyright (c) 2026 Mattias Holm
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+import AsciiDocCore
+
+public struct XADTemplateDescriptor: Sendable, Equatable {
+    public var name: String
+    public var baseURL: URL
+    public var layoutURL: URL
+    public var program: LayoutProgram
+
+    public init(name: String, baseURL: URL, layoutURL: URL, program: LayoutProgram) {
+        self.name = name
+        self.baseURL = baseURL
+        self.layoutURL = layoutURL
+        self.program = program
+    }
+}
+
+public struct XADTemplateRegistry: Sendable {
+    public var searchPaths: [URL]
+
+    public init(searchPaths: [URL] = []) {
+        self.searchPaths = searchPaths
+    }
+
+    public mutating func addSearchPath(_ url: URL) {
+        let normalized = url.standardizedFileURL
+        if !searchPaths.contains(where: { $0.standardizedFileURL == normalized }) {
+            searchPaths.append(normalized)
+        }
+    }
+
+    public func listTemplates(fileManager: FileManager = .default) -> [String] {
+        var names = Set<String>()
+        for root in searchPaths {
+            let xadDir = root.appendingPathComponent("xad", isDirectory: true)
+            guard let entries = try? fileManager.contentsOfDirectory(
+                at: xadDir,
+                includingPropertiesForKeys: [.isDirectoryKey],
+                options: [.skipsHiddenFiles]
+            ) else { continue }
+
+            for entry in entries {
+                guard (try? entry.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true else {
+                    continue
+                }
+                let layoutURL = entry.appendingPathComponent("layout.xad")
+                if fileManager.fileExists(atPath: layoutURL.path) {
+                    names.insert(entry.lastPathComponent)
+                }
+            }
+        }
+        return names.sorted()
+    }
+
+    public func loadTemplate(
+        named name: String,
+        baseURL: URL? = nil,
+        fileManager: FileManager = .default
+    ) -> (XADTemplateDescriptor?, [AdocWarning]) {
+        var warnings: [AdocWarning] = []
+        guard let layoutURL = resolveTemplateLayoutURL(named: name, fileManager: fileManager) else {
+            warnings.append(AdocWarning(message: "template not found: \(name)", span: nil))
+            return (nil, warnings)
+        }
+        return loadTemplate(at: layoutURL, templateName: name, baseURL: baseURL, fileManager: fileManager)
+    }
+
+    public func loadTemplate(
+        at url: URL,
+        templateName: String? = nil,
+        baseURL: URL? = nil,
+        fileManager: FileManager = .default
+    ) -> (XADTemplateDescriptor?, [AdocWarning]) {
+        var warnings: [AdocWarning] = []
+        let layoutURL: URL
+        var name = templateName ?? url.deletingPathExtension().lastPathComponent
+
+        if url.hasDirectoryPath {
+            layoutURL = url.appendingPathComponent("layout.xad")
+            name = url.lastPathComponent
+        } else {
+            layoutURL = url
+        }
+
+        guard fileManager.fileExists(atPath: layoutURL.path) else {
+            warnings.append(AdocWarning(message: "layout.xad not found at \(layoutURL.path)", span: nil))
+            return (nil, warnings)
+        }
+
+        let data: Data
+        do {
+            data = try Data(contentsOf: layoutURL)
+        } catch {
+            warnings.append(AdocWarning(message: "failed to read template: \(error.localizedDescription)", span: nil))
+            return (nil, warnings)
+        }
+        guard let text = String(data: data, encoding: .utf8) else {
+            warnings.append(AdocWarning(message: "template must be UTF-8", span: nil))
+            return (nil, warnings)
+        }
+
+        let parser = LayoutDSLParser()
+        let (program, parserWarnings) = parser.parse(text: text)
+        warnings.append(contentsOf: parserWarnings)
+
+        guard let program else {
+            warnings.append(AdocWarning(message: "template did not produce a layout program", span: nil))
+            return (nil, warnings)
+        }
+
+        let base = baseURL ?? layoutURL.deletingLastPathComponent()
+        let template = XADTemplateDescriptor(name: name, baseURL: base, layoutURL: layoutURL, program: program)
+        return (template, warnings)
+    }
+
+    private func resolveTemplateLayoutURL(named name: String, fileManager: FileManager) -> URL? {
+        for root in searchPaths {
+            let candidate = root
+                .appendingPathComponent("xad", isDirectory: true)
+                .appendingPathComponent(name, isDirectory: true)
+                .appendingPathComponent("layout.xad")
+            if fileManager.fileExists(atPath: candidate.path) {
+                return candidate
+            }
+        }
+        return nil
+    }
+}
diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index d227ad3..6240dcb 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -103,7 +103,10 @@ public final class DocumentRenderer {
                 "enabled": config.xadOptions.enabled,
                 "strict": config.xadOptions.strict,
                 "pagedJS": config.xadOptions.pagedJS,
-                "templatePath": config.xadOptions.templatePath ?? ""
+                "templatePath": config.xadOptions.templatePath ?? "",
+                "layoutTemplate": config.xadOptions.layoutTemplate ?? "",
+                "layoutTemplateBase": config.xadOptions.layoutTemplateBase ?? "",
+                "layoutTemplateSearchPaths": config.xadOptions.layoutTemplateSearchPaths
             ]
         ]
         
diff --git a/Sources/asciidoc-swift/Commands.swift b/Sources/asciidoc-swift/Commands.swift
index 297d26e..885a641 100644
--- a/Sources/asciidoc-swift/Commands.swift
+++ b/Sources/asciidoc-swift/Commands.swift
@@ -10,6 +10,7 @@ import AsciiDocCore
 import AsciiDocTools
 import AsciiDocExtensions
 import AsciiDocAntora
+import AsciiDocPagedRendering
 
 private struct AdapterInput: Decodable {
   enum Payload: String, Decodable {
@@ -216,7 +217,10 @@ struct HTML: AsyncParsableCommand {
             enabled: xad,
             pagedJS: xadPagedJS,
             strict: xadStrict,
-            templatePath: xadTemplate
+            templatePath: xadTemplate,
+            layoutTemplate: nil,
+            layoutTemplateBase: nil,
+            layoutTemplateSearchPaths: []
         )
         try renderDocument(
             backend: .html5,
@@ -275,7 +279,10 @@ struct XadHtml: AsyncParsableCommand {
             enabled: true,
             pagedJS: false,
             strict: xadStrict,
-            templatePath: xadTemplate
+            templatePath: xadTemplate,
+            layoutTemplate: nil,
+            layoutTemplateBase: nil,
+            layoutTemplateSearchPaths: []
         )
         try renderDocument(
             backend: .html5,
@@ -309,6 +316,22 @@ struct XadPagedHtml: AsyncParsableCommand {
     @Option(name: .long, help: "Path to XAD template (.adoc).")
     var xadTemplate: String?
 
+    @Option(name: .long, help: "XAD paged layout template name or path.")
+    var xadLayoutTemplate: String?
+
+    @Option(name: .long, help: "Base directory for resolving XAD paged template paths.")
+    var xadTemplateBase: String?
+
+    @Option(
+        name: .long,
+        parsing: .upToNextOption,
+        help: "Additional XAD paged template search paths."
+    )
+    var xadTemplateSearchPath: [String] = []
+
+    @Flag(name: .long, help: "List available XAD paged templates and exit.")
+    var listXadTemplates: Bool = false
+
     @Option(
         name: [.customShort("a"), .customLong("attribute")],
         parsing: .unconditionalSingleValue,
@@ -330,11 +353,44 @@ struct XadPagedHtml: AsyncParsableCommand {
     var extensions: [String] = []
 
     mutating func run() async throws {
+        let templateBaseURL = resolveTemplateBaseURL(xadTemplateBase)
+        var registry = XADTemplateRegistry(searchPaths: defaultTemplateRoots())
+        for path in resolveTemplateSearchPaths(xadTemplateSearchPath, baseURL: templateBaseURL) {
+            registry.addSearchPath(path)
+        }
+
+        if listXadTemplates {
+            let names = registry.listTemplates()
+            if names.isEmpty {
+                print("No XAD paged templates found.")
+            } else {
+                for name in names {
+                    print(name)
+                }
+            }
+            return
+        }
+
+        let templateSelection = xadLayoutTemplate ?? "default"
+        let templateResult: (XADTemplateDescriptor?, [AdocWarning])
+        if let overrideURL = resolveExistingTemplateURL(templateSelection, baseURL: templateBaseURL) {
+            templateResult = registry.loadTemplate(at: overrideURL, baseURL: templateBaseURL)
+        } else {
+            templateResult = registry.loadTemplate(named: templateSelection, baseURL: templateBaseURL)
+        }
+        emitTemplateWarnings(templateResult.1)
+        guard templateResult.0 != nil else {
+            throw ValidationError("Unable to load XAD template: \(templateSelection)")
+        }
+
         let xadOptions = makeXadOptions(
             enabled: true,
             pagedJS: true,
             strict: xadStrict,
-            templatePath: xadTemplate
+            templatePath: xadTemplate,
+            layoutTemplate: templateSelection,
+            layoutTemplateBase: xadTemplateBase,
+            layoutTemplateSearchPaths: xadTemplateSearchPath
         )
         try renderDocument(
             backend: .html5,
@@ -399,7 +455,10 @@ struct DocBook: AsyncParsableCommand {
             enabled: xad,
             pagedJS: xadPagedJS,
             strict: xadStrict,
-            templatePath: xadTemplate
+            templatePath: xadTemplate,
+            layoutTemplate: nil,
+            layoutTemplateBase: nil,
+            layoutTemplateSearchPaths: []
         )
         try renderDocument(
             backend: .docbook5,
@@ -464,7 +523,10 @@ struct Latex: AsyncParsableCommand {
             enabled: xad,
             pagedJS: xadPagedJS,
             strict: xadStrict,
-            templatePath: xadTemplate
+            templatePath: xadTemplate,
+            layoutTemplate: nil,
+            layoutTemplateBase: nil,
+            layoutTemplateSearchPaths: []
         )
         try renderDocument(
             backend: .latex,
@@ -711,18 +773,59 @@ struct Antora: AsyncParsableCommand {
 // Rendering helpers
 extension PlantUMLExtension.Format: ExpressibleByArgument {}
 
+private func defaultTemplateRoots() -> [URL] {
+    var roots: [URL] = []
+    if let bundleTemplates = Bundle.module.url(forResource: "Templates", withExtension: nil) {
+        roots.append(bundleTemplates)
+    }
+    let cwd = URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
+    roots.append(cwd.appendingPathComponent("Templates"))
+    return roots
+}
+
+private func resolveTemplateBaseURL(_ value: String?) -> URL? {
+    guard let value else { return nil }
+    return URL(fileURLWithPath: value).standardizedFileURL
+}
+
+private func resolveTemplateSearchPaths(_ values: [String], baseURL: URL?) -> [URL] {
+    let base = baseURL ?? URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
+    return values.map { URL(fileURLWithPath: $0, relativeTo: base).standardizedFileURL }
+}
+
+private func resolveExistingTemplateURL(_ value: String, baseURL: URL?) -> URL? {
+    let base = baseURL ?? URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
+    let candidate = URL(fileURLWithPath: value, relativeTo: base).standardizedFileURL
+    if FileManager.default.fileExists(atPath: candidate.path) {
+        return candidate
+    }
+    return nil
+}
+
+private func emitTemplateWarnings(_ warnings: [AdocWarning]) {
+    for warning in warnings {
+        FileHandle.standardError.write(Data("Template warning: \(warning.message)\n".utf8))
+    }
+}
+
 private func makeXadOptions(
     enabled: Bool,
     pagedJS: Bool,
     strict: Bool,
-    templatePath: String?
+    templatePath: String?,
+    layoutTemplate: String?,
+    layoutTemplateBase: String?,
+    layoutTemplateSearchPaths: [String]
 ) -> XADOptions {
-    let shouldEnable = enabled || pagedJS || templatePath != nil
+    let shouldEnable = enabled || pagedJS || templatePath != nil || layoutTemplate != nil
     return XADOptions(
         enabled: shouldEnable,
         strict: strict,
         pagedJS: pagedJS,
-        templatePath: templatePath
+        templatePath: templatePath,
+        layoutTemplate: layoutTemplate,
+        layoutTemplateBase: layoutTemplateBase,
+        layoutTemplateSearchPaths: layoutTemplateSearchPaths
     )
 }
 
diff --git a/Templates/xad/default/layout.xad b/Templates/xad/default/layout.xad
new file mode 100644
index 0000000..e75a6ce
--- /dev/null
+++ b/Templates/xad/default/layout.xad
@@ -0,0 +1,6 @@
+// Default XAD paged layout
+pages[
+  page(master:"default")[
+    flow(slot("main"))
+  ]
+]
diff --git a/Tests/AsciiDocCoreTests/TemplateRegistryTests.swift b/Tests/AsciiDocCoreTests/TemplateRegistryTests.swift
new file mode 100644
index 0000000..62ff031
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/TemplateRegistryTests.swift
@@ -0,0 +1,41 @@
+import Testing
+import Foundation
+import AsciiDocPagedRendering
+
+@Suite("XAD Template Registry")
+struct XADTemplateRegistryTests {
+    @Test
+    func loadsTemplateFromSearchPath() throws {
+        let fileManager = FileManager.default
+        let root = fileManager.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        let templatesRoot = root.appendingPathComponent("Templates")
+        let layoutDir = templatesRoot.appendingPathComponent("xad/default", isDirectory: true)
+        try fileManager.createDirectory(at: layoutDir, withIntermediateDirectories: true)
+        let layoutURL = layoutDir.appendingPathComponent("layout.xad")
+        try "pages[]".write(to: layoutURL, atomically: true, encoding: .utf8)
+        defer { try? fileManager.removeItem(at: root) }
+
+        let registry = XADTemplateRegistry(searchPaths: [templatesRoot])
+        let (template, warnings) = registry.loadTemplate(named: "default")
+
+        #expect(warnings.isEmpty)
+        #expect(template != nil)
+    }
+
+    @Test
+    func listsTemplatesFromSearchPaths() throws {
+        let fileManager = FileManager.default
+        let root = fileManager.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        let templatesRoot = root.appendingPathComponent("Templates")
+        let layoutDir = templatesRoot.appendingPathComponent("xad/demo", isDirectory: true)
+        try fileManager.createDirectory(at: layoutDir, withIntermediateDirectories: true)
+        let layoutURL = layoutDir.appendingPathComponent("layout.xad")
+        try "pages[]".write(to: layoutURL, atomically: true, encoding: .utf8)
+        defer { try? fileManager.removeItem(at: root) }
+
+        let registry = XADTemplateRegistry(searchPaths: [templatesRoot])
+        let names = registry.listTemplates()
+
+        #expect(names.contains("demo"))
+    }
+}

From d5ac205750916e853feafd15891695ba7453db68 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Mon, 2 Mar 2026 07:54:58 +0100
Subject: [PATCH 26/38] Additional integration with rendering pipeline

---
 Sources/AsciiDocRender/DocumentRender.swift | 100 ++++++++++++++++++--
 Sources/asciidoc-swift/Commands.swift       |   9 +-
 2 files changed, 97 insertions(+), 12 deletions(-)

diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index 6240dcb..0624157 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -13,6 +13,7 @@ public struct RenderConfig {
     public var navigationTree: [String: Any]?
     public var customTemplateName: String?
     public var xadOptions: XADOptions
+    public var xadLayoutProgram: LayoutProgram?
 
     public init(
         backend: Backend,
@@ -20,13 +21,15 @@ public struct RenderConfig {
         xrefResolver: XrefResolver? = nil,
         navigationTree: [String: Any]? = nil,
         customTemplateName: String? = nil,
-        xadOptions: XADOptions = .init()
+        xadOptions: XADOptions = .init(),
+        xadLayoutProgram: LayoutProgram? = nil
     ) {
         self.backend = backend
         self.xrefResolver = xrefResolver
         self.navigationTree = navigationTree
         self.customTemplateName = customTemplateName
         self.xadOptions = xadOptions
+        self.xadLayoutProgram = xadLayoutProgram
         self.inlineBackend = inlineBackend ?? {
             switch backend {
             case .html5:    return .html5
@@ -92,6 +95,19 @@ public final class DocumentRenderer {
         }
 
         let typedAttributes = docToRender.typedAttributes.mapValues { $0.toJSONCompatible() }
+        var xadContext: [String: Any] = [
+            "enabled": config.xadOptions.enabled,
+            "strict": config.xadOptions.strict,
+            "pagedJS": config.xadOptions.pagedJS,
+            "templatePath": config.xadOptions.templatePath ?? "",
+            "layoutTemplate": config.xadOptions.layoutTemplate ?? "",
+            "layoutTemplateBase": config.xadOptions.layoutTemplateBase ?? "",
+            "layoutTemplateSearchPaths": config.xadOptions.layoutTemplateSearchPaths
+        ]
+        if let program = config.xadLayoutProgram {
+            xadContext["layoutProgram"] = layoutProgramContext(program)
+        }
+
         var context: [String: Any] = [
             "attributes": docToRender.attributes,
             "typedAttributes": typedAttributes,
@@ -99,15 +115,7 @@ public final class DocumentRenderer {
             "blocks": blocks,
             "footnotes": footnotes.map { renderFootnoteDefinition($0, context: inlineContext) },
             "indexCatalog": indexEntries,
-            "xad": [
-                "enabled": config.xadOptions.enabled,
-                "strict": config.xadOptions.strict,
-                "pagedJS": config.xadOptions.pagedJS,
-                "templatePath": config.xadOptions.templatePath ?? "",
-                "layoutTemplate": config.xadOptions.layoutTemplate ?? "",
-                "layoutTemplateBase": config.xadOptions.layoutTemplateBase ?? "",
-                "layoutTemplateSearchPaths": config.xadOptions.layoutTemplateSearchPaths
-            ]
+            "xad": xadContext
         ]
         
         if let nav = config.navigationTree {
@@ -136,6 +144,78 @@ public final class DocumentRenderer {
         ]
     }
 
+    private func layoutProgramContext(_ program: LayoutProgram) -> [String: Any] {
+        return [
+            "expressions": program.expressions.map { layoutExprContext($0) }
+        ]
+    }
+
+    private func layoutExprContext(_ expr: LayoutExpr) -> [String: Any] {
+        switch expr {
+        case .node(let node):
+            return [
+                "type": "node",
+                "name": node.name,
+                "args": node.args.map { layoutArgContext($0) },
+                "children": node.children.map { layoutExprContext($0) }
+            ]
+        case .value(let value):
+            return [
+                "type": "value",
+                "value": layoutValueContext(value)
+            ]
+        }
+    }
+
+    private func layoutArgContext(_ arg: LayoutArg) -> [String: Any] {
+        return [
+            "name": arg.name ?? "",
+            "named": arg.name != nil,
+            "value": layoutExprContext(arg.value)
+        ]
+    }
+
+    private func layoutValueContext(_ value: LayoutValue) -> Any {
+        switch value {
+        case .string(let string):
+            return string
+        case .number(let number):
+            return number
+        case .boolean(let boolean):
+            return boolean
+        case .null:
+            return NSNull()
+        case .array(let values):
+            return values.map { layoutValueContext($0) }
+        case .dict(let dict):
+            var out: [String: Any] = [:]
+            for (key, entry) in dict {
+                out[key] = layoutValueContext(entry)
+            }
+            return out
+        case .ref(let ref):
+            var payload: [String: Any] = [
+                "type": "ref",
+                "parts": ref.parts
+            ]
+            if let index = ref.index {
+                payload["index"] = layoutIndexContext(index)
+            }
+            return payload
+        }
+    }
+
+    private func layoutIndexContext(_ index: LayoutIndex) -> Any {
+        switch index {
+        case .number(let number):
+            return ["type": "number", "value": number]
+        case .string(let string):
+            return ["type": "string", "value": string]
+        case .identifier(let ident):
+            return ["type": "identifier", "value": ident]
+        }
+    }
+
     private func renderBlocks(_ blocks: [AdocBlock], context: InlineContext) -> [[String: Any]] {
         var rendered: [[String: Any]] = []
         var idx = 0
diff --git a/Sources/asciidoc-swift/Commands.swift b/Sources/asciidoc-swift/Commands.swift
index 885a641..256af94 100644
--- a/Sources/asciidoc-swift/Commands.swift
+++ b/Sources/asciidoc-swift/Commands.swift
@@ -838,7 +838,8 @@ private func renderDocument(
     attributeAssignments: [String],
     outputPath: String?,
     enabledExtensions: [String],
-    xadOptions: XADOptions
+    xadOptions: XADOptions,
+    xadLayoutProgram: LayoutProgram? = nil
 ) throws {
     let (source, sourcePath) = try readRenderSource(stdin: stdin, inputPath: inputPath)
     let documentDirectory = sourcePath.map { URL(fileURLWithPath: $0).deletingLastPathComponent() }
@@ -885,7 +886,11 @@ private func renderDocument(
     let engine = StencilTemplateEngine(templateRoot: templateRoot)
     let renderer = DocumentRenderer(
         engine: engine,
-        config: RenderConfig(backend: backend, xadOptions: xadOptions)
+        config: RenderConfig(
+            backend: backend,
+            xadOptions: xadOptions,
+            xadLayoutProgram: xadLayoutProgram
+        )
     )
     let rendered = try renderer.render(document: doc)
     try writeRenderedOutput(rendered, explicitPath: outputPath, sourcePath: sourcePath, defaultExtension: defaultExtension)

From 279464b0d02fa98c34550206548fdb4e15c0f0c2 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Mon, 2 Mar 2026 07:57:53 +0100
Subject: [PATCH 27/38] Update documentation

---
 .../asciidoc-swift.docc/asciidoc-swift.md             | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Sources/asciidoc-swift/asciidoc-swift.docc/asciidoc-swift.md b/Sources/asciidoc-swift/asciidoc-swift.docc/asciidoc-swift.md
index cc1a464..254f732 100644
--- a/Sources/asciidoc-swift/asciidoc-swift.docc/asciidoc-swift.md
+++ b/Sources/asciidoc-swift/asciidoc-swift.docc/asciidoc-swift.md
@@ -94,7 +94,7 @@ and Paged.js hooks turned on.
 ##### Usage
 
 ```bash
-asciidoc-swift xad-paged-html [--stdin] [--template <template>] [--attribute <attribute> ...] [--output <output>] [<input-path>] [--extension <extension> ...]
+asciidoc-swift xad-paged-html [--stdin] [--template <template>] [--xad-layout-template <layout>] [--xad-template-base <dir>] [--xad-template-search-path <dir> ...] [--list-xad-templates] [--attribute <attribute> ...] [--output <output>] [<input-path>] [--extension <extension> ...]
 ```
 
 ##### Arguments and Options
@@ -106,11 +106,19 @@ asciidoc-swift xad-paged-html [--stdin] [--template <template>] [--attribute <at
 | `--template <template>` | Path to the Stencil templates root directory. (default: `Templates`) |
 | `--xad-strict` | Enable strict XAD parsing. |
 | `--xad-template <xad-template>` | Path to XAD template (`.adoc`). |
+| `--xad-layout-template <layout>` | XAD paged layout template name or path (default: `default`). |
+| `--xad-template-base <dir>` | Base directory for resolving XAD paged template paths. |
+| `--xad-template-search-path <dir>` | Additional XAD paged template search paths (repeatable). |
+| `--list-xad-templates` | List available XAD paged templates and exit. |
 | `-a`, `--attribute <attribute>` | Set document attribute (`name[=value]`). Repeatable. |
 | `-o`, `--output <output>` | Write rendered output to this path. |
 | `-e`, `--extension <extension>` | Enable an extension by name (repeatable). |
 | `-h`, `--help` | Show help information. |
 
+##### XAD Layout Context
+
+When using `xad-paged-html`, the parsed layout DSL is exposed in the render context under `xad.layoutProgram`. The structure is JSON-friendly and includes `expressions` with `node` and `value` entries (each node includes `name`, `args`, and `children`).
+
 
 #### `docbook` subcommand
 
@@ -200,6 +208,7 @@ asciidoc-swift lint [--stdin] [--no-spellcheck] [--no-semantic-breaks] [--spell-
 
 - [AsciiDocCore](../asciidoccore)
 - [AsciiDocRender](../asciidocrender)
+- [AsciiDocPagedRendering](../asciidocpagedrendering)
 - [AsciiDocTools](../asciidoctools)
 - [AsciiDocExtensions](../asciidocextensions)
 

From 3fbfce0be1283bd1ffd0a1b7472130ad72829cc3 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Mon, 2 Mar 2026 22:00:50 +0100
Subject: [PATCH 28/38] Initial slot collection

---
 Sources/AsciiDocRender/DocumentRender.swift   | 228 +++++++++++++++++-
 .../SlotCollectionRenderTests.swift           |  83 +++++++
 2 files changed, 310 insertions(+), 1 deletion(-)
 create mode 100644 Tests/AsciiDocCoreTests/SlotCollectionRenderTests.swift

diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index 0624157..2be8b8b 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -46,6 +46,24 @@ public final class DocumentRenderer {
     private let inlineRenderer: AdocInlineRenderer
     private var calloutSerial: Int = 0
 
+    private enum SlotMode {
+        case move
+        case copy
+    }
+
+    private struct SlotItem {
+        let block: AdocBlock
+        let order: Double
+        let index: Int
+    }
+
+    private struct SlotExtractionResult {
+        var mainBlocks: [AdocBlock]
+        var slots: [String: [SlotItem]]
+        var collections: [String: [SlotItem]]
+        var warnings: [AdocWarning]
+    }
+
     public init(engine: TemplateEngine, config: RenderConfig) {
         self.engine = engine
         self.config = config
@@ -77,7 +95,23 @@ public final class DocumentRenderer {
         let docToRender = resolution.document
         let footnotes = resolution.definitions
 
-        let blocks = renderBlocks(docToRender.blocks, context: inlineContext)
+        let slotExtraction: SlotExtractionResult
+        let blocks: [[String: Any]]
+        if config.xadOptions.enabled {
+            slotExtraction = extractSlotsAndCollections(
+                from: docToRender.blocks,
+                attributes: docToRender.attributes
+            )
+            blocks = renderBlocks(slotExtraction.mainBlocks, context: inlineContext)
+        } else {
+            slotExtraction = SlotExtractionResult(
+                mainBlocks: docToRender.blocks,
+                slots: [:],
+                collections: [:],
+                warnings: []
+            )
+            blocks = renderBlocks(docToRender.blocks, context: inlineContext)
+        }
 
         let indexResolver = IndexResolver()
         let indexCatalog = indexResolver.resolve(docToRender)
@@ -104,6 +138,15 @@ public final class DocumentRenderer {
             "layoutTemplateBase": config.xadOptions.layoutTemplateBase ?? "",
             "layoutTemplateSearchPaths": config.xadOptions.layoutTemplateSearchPaths
         ]
+        if config.xadOptions.enabled {
+            var slotContexts = renderSlotGroups(slotExtraction.slots, context: inlineContext)
+            slotContexts["main"] = blocks
+            xadContext["slots"] = slotContexts
+            xadContext["collections"] = renderSlotGroups(slotExtraction.collections, context: inlineContext)
+            if !slotExtraction.warnings.isEmpty {
+                xadContext["warnings"] = slotExtraction.warnings.map { $0.message }
+            }
+        }
         if let program = config.xadLayoutProgram {
             xadContext["layoutProgram"] = layoutProgramContext(program)
         }
@@ -567,6 +610,189 @@ public final class DocumentRenderer {
         ]
     }
 
+    private func renderSlotGroups(_ groups: [String: [SlotItem]], context: InlineContext) -> [String: Any] {
+        var rendered: [String: Any] = [:]
+        for (name, items) in groups {
+            let sorted = items.sorted {
+                if $0.order == $1.order { return $0.index < $1.index }
+                return $0.order < $1.order
+            }
+            let slotBlocks = sorted.map { $0.block }
+            rendered[name] = renderBlocks(slotBlocks, context: context)
+        }
+        return rendered
+    }
+
+    private func extractSlotsAndCollections(
+        from blocks: [AdocBlock],
+        attributes: [String: String?]
+    ) -> SlotExtractionResult {
+        var slots: [String: [SlotItem]] = [:]
+        var collections: [String: [SlotItem]] = [:]
+        var warnings: [AdocWarning] = []
+        var slotModeCache: [String: SlotMode] = [:]
+        var index = 0
+
+        func attributeValue(_ name: String) -> String? {
+            guard let value = attributes[name] else { return nil }
+            return value ?? ""
+        }
+
+        func slotMode(for slot: String) -> SlotMode {
+            if let cached = slotModeCache[slot] { return cached }
+            let raw = attributeValue("slot.mode.\(slot)") ?? attributeValue("slot.mode.default")
+            let mode: SlotMode
+            if let raw = raw?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty {
+                switch raw.lowercased() {
+                case "move":
+                    mode = .move
+                case "copy":
+                    mode = .copy
+                default:
+                    warnings.append(AdocWarning(message: "Invalid slot.mode value '\(raw)' for '\(slot)'; defaulting to move."))
+                    mode = .move
+                }
+            } else {
+                mode = .move
+            }
+            slotModeCache[slot] = mode
+            return mode
+        }
+
+        func parseOrder(_ raw: String?, context: String, span: AdocRange?) -> Double {
+            guard let raw = raw?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
+                return 0
+            }
+            if let value = Double(raw) {
+                return value
+            }
+            warnings.append(AdocWarning(message: "Invalid order '\(raw)' for \(context); defaulting to 0.", span: span))
+            return 0
+        }
+
+        func normalizedName(_ raw: String?) -> String? {
+            guard let raw = raw?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
+                return nil
+            }
+            return raw
+        }
+
+        func addSlot(_ name: String, block: AdocBlock, order: Double, index: Int) {
+            slots[name, default: []].append(SlotItem(block: block, order: order, index: index))
+        }
+
+        func addCollection(_ name: String, block: AdocBlock, order: Double, index: Int) {
+            collections[name, default: []].append(SlotItem(block: block, order: order, index: index))
+        }
+
+        func extractBlocks(_ blocks: [AdocBlock]) -> [AdocBlock] {
+            var out: [AdocBlock] = []
+            for block in blocks {
+                if let extracted = extractBlock(block) {
+                    out.append(extracted)
+                }
+            }
+            return out
+        }
+
+        func extractBlock(_ block: AdocBlock) -> AdocBlock? {
+            let meta = blockMeta(block)
+            let slotName = normalizedName(meta.attributes["slot"])
+            let collectionName = normalizedName(meta.attributes["collect"])
+            let orderContext = slotName ?? collectionName ?? "main"
+            let order = parseOrder(meta.attributes["order"], context: orderContext, span: meta.span)
+            index += 1
+            let currentIndex = index
+
+            if let collectionName {
+                addCollection(collectionName, block: block, order: order, index: currentIndex)
+            }
+
+            let effectiveSlot = slotName ?? "main"
+            if effectiveSlot != "main" {
+                addSlot(effectiveSlot, block: block, order: order, index: currentIndex)
+            }
+
+            let shouldMove = effectiveSlot != "main" && slotMode(for: effectiveSlot) == .move
+            if shouldMove {
+                return nil
+            }
+
+            if slotName != nil || collectionName != nil {
+                return block
+            }
+
+            switch block {
+            case .section(var s):
+                s.blocks = extractBlocks(s.blocks)
+                return .section(s)
+            case .sidebar(var s):
+                s.blocks = extractBlocks(s.blocks)
+                return .sidebar(s)
+            case .example(var e):
+                e.blocks = extractBlocks(e.blocks)
+                return .example(e)
+            case .quote(var q):
+                q.blocks = extractBlocks(q.blocks)
+                return .quote(q)
+            case .open(var o):
+                o.blocks = extractBlocks(o.blocks)
+                return .open(o)
+            case .admonition(var a):
+                a.blocks = extractBlocks(a.blocks)
+                return .admonition(a)
+            case .verse(var v):
+                v.blocks = extractBlocks(v.blocks)
+                return .verse(v)
+            case .list(var l):
+                l.items = l.items.map { item in
+                    var updated = item
+                    updated.blocks = extractBlocks(item.blocks)
+                    return updated
+                }
+                return .list(l)
+            case .dlist(var d):
+                d.items = d.items.map { item in
+                    var updated = item
+                    updated.blocks = extractBlocks(item.blocks)
+                    return updated
+                }
+                return .dlist(d)
+            default:
+                return block
+            }
+        }
+
+        let mainBlocks = extractBlocks(blocks)
+        return SlotExtractionResult(
+            mainBlocks: mainBlocks,
+            slots: slots,
+            collections: collections,
+            warnings: warnings
+        )
+    }
+
+    private func blockMeta(_ block: AdocBlock) -> AdocBlockMeta {
+        switch block {
+        case .section(let s): return s.meta
+        case .paragraph(let p): return p.meta
+        case .listing(let l): return l.meta
+        case .list(let l): return l.meta
+        case .dlist(let d): return d.meta
+        case .discreteHeading(let h): return h.meta
+        case .sidebar(let s): return s.meta
+        case .example(let e): return e.meta
+        case .quote(let q): return q.meta
+        case .open(let o): return o.meta
+        case .admonition(let a): return a.meta
+        case .verse(let v): return v.meta
+        case .literalBlock(let l): return l.meta
+        case .table(let t): return t.meta
+        case .math(let m): return m.meta
+        case .blockMacro(let m): return m.meta
+        }
+    }
+
     private func renderInlines(_ inlines: [AdocInline], context: InlineContext) -> String {
         inlineRenderer.render(inlines, context: context)
     }
diff --git a/Tests/AsciiDocCoreTests/SlotCollectionRenderTests.swift b/Tests/AsciiDocCoreTests/SlotCollectionRenderTests.swift
new file mode 100644
index 0000000..a96dcca
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/SlotCollectionRenderTests.swift
@@ -0,0 +1,83 @@
+import Testing
+import AsciiDocCore
+import AsciiDocRender
+
+@Suite("XAD Slot/Collection Rendering")
+struct SlotCollectionRenderTests {
+    @Test
+    func extractsSlotsAndCollections() throws {
+        let engine = CapturingTemplateEngine()
+        let config = RenderConfig(
+            backend: .html5,
+            xadOptions: XADOptions(enabled: true)
+        )
+        let renderer = DocumentRenderer(engine: engine, config: config)
+
+        let mainBlock = AdocBlock.paragraph(AdocParagraph(
+            text: AdocText(plain: "Main"),
+            meta: AdocBlockMeta()
+        ))
+
+        var sidebarMetaEarly = AdocBlockMeta()
+        sidebarMetaEarly.attributes["slot"] = "sidebar"
+        sidebarMetaEarly.attributes["order"] = "5"
+        let sidebarEarly = AdocBlock.paragraph(AdocParagraph(
+            text: AdocText(plain: "Sidebar early"),
+            meta: sidebarMetaEarly
+        ))
+
+        var sidebarMetaLate = AdocBlockMeta()
+        sidebarMetaLate.attributes["slot"] = "sidebar"
+        sidebarMetaLate.attributes["order"] = "20"
+        let sidebarLate = AdocBlock.paragraph(AdocParagraph(
+            text: AdocText(plain: "Sidebar late"),
+            meta: sidebarMetaLate
+        ))
+
+        var collectMeta = AdocBlockMeta()
+        collectMeta.attributes["collect"] = "reqs"
+        collectMeta.attributes["order"] = "2"
+        let collected = AdocBlock.paragraph(AdocParagraph(
+            text: AdocText(plain: "Req 1"),
+            meta: collectMeta
+        ))
+
+        var attributes: [String: String?] = [:]
+        attributes["slot.mode.sidebar"] = "move"
+
+        let document = AdocDocument(
+            attributes: attributes,
+            blocks: [mainBlock, sidebarLate, sidebarEarly, collected]
+        )
+
+        _ = try renderer.render(document: document)
+
+        let context = try #require(engine.lastContext)
+        let xad = try #require(context["xad"] as? [String: Any])
+
+        let slots = try #require(xad["slots"] as? [String: Any])
+        let mainBlocks = plainTextBlocks(slots["main"])
+        #expect(mainBlocks == ["Main", "Req 1"])
+
+        let sidebarBlocks = plainTextBlocks(slots["sidebar"])
+        #expect(sidebarBlocks == ["Sidebar early", "Sidebar late"])
+
+        let collections = try #require(xad["collections"] as? [String: Any])
+        let reqBlocks = plainTextBlocks(collections["reqs"])
+        #expect(reqBlocks == ["Req 1"])
+    }
+}
+
+private final class CapturingTemplateEngine: TemplateEngine {
+    var lastContext: [String: Any]?
+
+    func render(templateNamed name: String, context: [String: Any]) throws -> String {
+        lastContext = context
+        return ""
+    }
+}
+
+private func plainTextBlocks(_ value: Any?) -> [String] {
+    guard let blocks = value as? [[String: Any]] else { return [] }
+    return blocks.compactMap { $0["plain"] as? String }
+}

From ce92376ffea359eb261d8b9e83df641de84c515b Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Mon, 2 Mar 2026 22:18:16 +0100
Subject: [PATCH 29/38] Initial work on hooking up paged rendering

---
 Package.swift                                 |   1 +
 .../LayoutEvaluator.swift                     | 273 ++++++++++++++++++
 Sources/AsciiDocRender/DocumentRender.swift   |  25 +-
 Templates/html5/document.stencil              | 180 +++++++-----
 4 files changed, 404 insertions(+), 75 deletions(-)
 create mode 100644 Sources/AsciiDocPagedRendering/LayoutEvaluator.swift

diff --git a/Package.swift b/Package.swift
index 718eb5d..0e04d3d 100644
--- a/Package.swift
+++ b/Package.swift
@@ -49,6 +49,7 @@ let package = Package(
             dependencies: [
                 .product(name: "Stencil", package: "Stencil"),
                 "AsciiDocCore",
+                "AsciiDocPagedRendering",
             ],
             path: "Sources/AsciiDocRender",
             swiftSettings: [
diff --git a/Sources/AsciiDocPagedRendering/LayoutEvaluator.swift b/Sources/AsciiDocPagedRendering/LayoutEvaluator.swift
new file mode 100644
index 0000000..af3510c
--- /dev/null
+++ b/Sources/AsciiDocPagedRendering/LayoutEvaluator.swift
@@ -0,0 +1,273 @@
+import Foundation
+import AsciiDocCore
+
+public struct XADLayoutEvaluationResult {
+    public var tree: [String: Any]
+    public var warnings: [AdocWarning]
+
+    public init(tree: [String: Any], warnings: [AdocWarning]) {
+        self.tree = tree
+        self.warnings = warnings
+    }
+}
+
+public struct XADLayoutEvaluator {
+    public init() {}
+
+    public func evaluate(
+        program: LayoutProgram,
+        slots: [String: [[String: Any]]],
+        collections: [String: [[String: Any]]]
+    ) -> XADLayoutEvaluationResult {
+        var warnings: [AdocWarning] = []
+        let nodes = program.expressions.compactMap { expr in
+            evalExpr(expr, slots: slots, collections: collections, warnings: &warnings)
+        }
+        return XADLayoutEvaluationResult(
+            tree: [
+                "kind": "program",
+                "nodes": nodes
+            ],
+            warnings: warnings
+        )
+    }
+
+    private func evalExpr(
+        _ expr: LayoutExpr,
+        slots: [String: [[String: Any]]],
+        collections: [String: [[String: Any]]],
+        warnings: inout [AdocWarning]
+    ) -> Any? {
+        switch expr {
+        case .node(let node):
+            return evalNode(node, slots: slots, collections: collections, warnings: &warnings)
+        case .value(let value):
+            return evalValue(value)
+        }
+    }
+
+    private func evalNode(
+        _ node: LayoutNode,
+        slots: [String: [[String: Any]]],
+        collections: [String: [[String: Any]]],
+        warnings: inout [AdocWarning]
+    ) -> [String: Any] {
+        let args = evalArgs(node.args, slots: slots, collections: collections, warnings: &warnings)
+        let children = node.children.compactMap { evalExpr($0, slots: slots, collections: collections, warnings: &warnings) }
+
+        switch node.name {
+        case "slot":
+            let name = argString(args, key: nil) ?? "main"
+            return [
+                "kind": "source",
+                "source": "slot",
+                "name": name,
+                "blocks": slots[name] ?? []
+            ]
+
+        case "collect":
+            let name = argString(args, key: nil) ?? ""
+            return [
+                "kind": "source",
+                "source": "collect",
+                "name": name,
+                "blocks": collections[name] ?? []
+            ]
+
+        case "flow":
+            var blocks: [[String: Any]] = []
+            var sources: [[String: Any]] = []
+            for value in args.values {
+                if let extracted = extractBlocks(from: value) {
+                    blocks.append(contentsOf: extracted)
+                }
+                if let source = extractSource(from: value) {
+                    sources.append(source)
+                }
+            }
+            for child in children {
+                if let extracted = extractBlocks(from: child) {
+                    blocks.append(contentsOf: extracted)
+                }
+                if let source = extractSource(from: child) {
+                    sources.append(source)
+                }
+            }
+            var payload: [String: Any] = [
+                "kind": "flow",
+                "args": args,
+                "blocks": blocks,
+                "children": children.filter { !isSourceNode($0) }
+            ]
+            if let dataSlot = singleSlotName(from: sources) {
+                payload["dataSlot"] = dataSlot
+            }
+            if !sources.isEmpty {
+                payload["sources"] = sources
+            }
+            return payload
+
+        case "place":
+            return [
+                "kind": "place",
+                "args": args,
+                "children": children
+            ]
+
+        case "grid":
+            return [
+                "kind": "grid",
+                "args": args,
+                "children": children
+            ]
+
+        case "stack":
+            return [
+                "kind": "stack",
+                "args": args,
+                "children": children
+            ]
+
+        case "pages":
+            return [
+                "kind": "pages",
+                "children": children
+            ]
+
+        case "page":
+            return [
+                "kind": "page",
+                "args": args,
+                "children": children
+            ]
+
+        case "text":
+            let value = argString(args, key: nil) ?? ""
+            return [
+                "kind": "text",
+                "text": value
+            ]
+
+        case "counter":
+            return [
+                "kind": "counter",
+                "args": args
+            ]
+
+        case "sink":
+            return [
+                "kind": "sink",
+                "args": args
+            ]
+
+        default:
+            return [
+                "kind": node.name,
+                "args": args,
+                "children": children
+            ]
+        }
+    }
+
+    private func evalArgs(
+        _ args: [LayoutArg],
+        slots: [String: [[String: Any]]],
+        collections: [String: [[String: Any]]],
+        warnings: inout [AdocWarning]
+    ) -> [String: Any] {
+        var result: [String: Any] = [:]
+        var positionalIndex = 0
+        for arg in args {
+            let value = evalExpr(arg.value, slots: slots, collections: collections, warnings: &warnings)
+            if let name = arg.name, !name.isEmpty {
+                result[name] = value ?? NSNull()
+            } else {
+                result["$\(positionalIndex)"] = value ?? NSNull()
+                positionalIndex += 1
+            }
+        }
+        return result
+    }
+
+    private func evalValue(_ value: LayoutValue) -> Any {
+        switch value {
+        case .string(let string):
+            return string
+        case .number(let number):
+            return number
+        case .boolean(let bool):
+            return bool
+        case .null:
+            return NSNull()
+        case .array(let values):
+            return values.map { evalValue($0) }
+        case .dict(let dict):
+            var out: [String: Any] = [:]
+            for (key, entry) in dict {
+                out[key] = evalValue(entry)
+            }
+            return out
+        case .ref(let ref):
+            var payload: [String: Any] = [
+                "type": "ref",
+                "parts": ref.parts
+            ]
+            if let index = ref.index {
+                payload["index"] = evalIndex(index)
+            }
+            return payload
+        }
+    }
+
+    private func evalIndex(_ index: LayoutIndex) -> Any {
+        switch index {
+        case .number(let number):
+            return ["type": "number", "value": number]
+        case .string(let string):
+            return ["type": "string", "value": string]
+        case .identifier(let ident):
+            return ["type": "identifier", "value": ident]
+        }
+    }
+
+    private func argString(_ args: [String: Any], key: String?) -> String? {
+        if let key {
+            return args[key] as? String
+        }
+        return args["$0"] as? String
+    }
+
+    private func isSourceNode(_ value: Any) -> Bool {
+        guard let dict = value as? [String: Any] else { return false }
+        return dict["kind"] as? String == "source"
+    }
+
+    private func extractBlocks(from value: Any) -> [[String: Any]]? {
+        if let dict = value as? [String: Any],
+           dict["kind"] as? String == "source",
+           let blocks = dict["blocks"] as? [[String: Any]] {
+            return blocks
+        }
+        return nil
+    }
+
+    private func extractSource(from value: Any) -> [String: Any]? {
+        guard let dict = value as? [String: Any],
+              dict["kind"] as? String == "source",
+              let source = dict["source"] as? String,
+              let name = dict["name"] as? String else {
+            return nil
+        }
+        return ["source": source, "name": name]
+    }
+
+    private func singleSlotName(from sources: [[String: Any]]) -> String? {
+        guard sources.count == 1,
+              let source = sources.first,
+              source["source"] as? String == "slot",
+              let name = source["name"] as? String else {
+            return nil
+        }
+        return name
+    }
+}
diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index 2be8b8b..f2c03bb 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -5,6 +5,7 @@
 
 import Foundation
 import AsciiDocCore
+import AsciiDocPagedRendering
 
 public struct RenderConfig {
     public var backend: Backend
@@ -141,10 +142,24 @@ public final class DocumentRenderer {
         if config.xadOptions.enabled {
             var slotContexts = renderSlotGroups(slotExtraction.slots, context: inlineContext)
             slotContexts["main"] = blocks
+            let collectionContexts = renderSlotGroups(slotExtraction.collections, context: inlineContext)
             xadContext["slots"] = slotContexts
-            xadContext["collections"] = renderSlotGroups(slotExtraction.collections, context: inlineContext)
-            if !slotExtraction.warnings.isEmpty {
-                xadContext["warnings"] = slotExtraction.warnings.map { $0.message }
+            xadContext["collections"] = collectionContexts
+
+            var warnings = slotExtraction.warnings
+            if let program = config.xadLayoutProgram {
+                let evaluator = XADLayoutEvaluator()
+                let evaluation = evaluator.evaluate(
+                    program: program,
+                    slots: slotContexts,
+                    collections: collectionContexts
+                )
+                xadContext["layoutTree"] = evaluation.tree
+                warnings.append(contentsOf: evaluation.warnings)
+            }
+
+            if !warnings.isEmpty {
+                xadContext["warnings"] = warnings.map { $0.message }
             }
         }
         if let program = config.xadLayoutProgram {
@@ -610,8 +625,8 @@ public final class DocumentRenderer {
         ]
     }
 
-    private func renderSlotGroups(_ groups: [String: [SlotItem]], context: InlineContext) -> [String: Any] {
-        var rendered: [String: Any] = [:]
+    private func renderSlotGroups(_ groups: [String: [SlotItem]], context: InlineContext) -> [String: [[String: Any]]] {
+        var rendered: [String: [[String: Any]]] = [:]
         for (name, items) in groups {
             let sorted = items.sorted {
                 if $0.order == $1.order { return $0.index < $1.index }
diff --git a/Templates/html5/document.stencil b/Templates/html5/document.stencil
index 19b51ba..98a800c 100644
--- a/Templates/html5/document.stencil
+++ b/Templates/html5/document.stencil
@@ -66,6 +66,40 @@
         box-shadow: var(--shadow-soft);
       }
 
+      .xad-doc {
+        width: min(1100px, calc(100% - 2.5rem));
+        margin: 0 auto;
+        background: var(--surface);
+        border-radius: 18px;
+        padding: 2.5rem clamp(1.5rem, 4vw, 3rem);
+        box-shadow: var(--shadow-soft);
+      }
+
+      .xad-layout {
+        display: grid;
+        gap: 1.5rem;
+      }
+
+      .xad-grid {
+        display: grid;
+        gap: 1.5rem;
+      }
+
+      .xad-area {
+        padding: 1.5rem;
+        border: 1px solid var(--border-soft);
+        border-radius: 16px;
+        background: linear-gradient(135deg, var(--surface), var(--surface-muted));
+      }
+
+      .xad-sink {
+        padding: 1rem;
+        border: 1px dashed var(--border-soft);
+        border-radius: 12px;
+        color: var(--text-muted);
+        font-size: 0.95rem;
+      }
+
       .doc-header {
         margin-bottom: 2.5rem;
         border-bottom: 1px solid var(--border-soft);
@@ -442,77 +476,83 @@
     </style>
   </head>
   <body>
-    <div class="doc-shell">
-      {% if headerTitle or attributes["subtitle"] or attributes["author"] or attributes["revdate"] %}
-        <header class="doc-header">
-          {% if headerTitle %}
-            <h1>{{ headerTitle }}</h1>
-          {% endif %}
-          {% if attributes["subtitle"] %}
-            <p class="subtitle">{{ attributes["subtitle"] }}</p>
-          {% endif %}
-          {% if attributes["author"] or attributes["revdate"] or attributes["revnumber"] %}
-            <div class="doc-meta">
-              {% if attributes["author"] %}
-                <span>{{ attributes["author"] }}</span>
-              {% endif %}
-              {% if attributes["revnumber"] %}
-                <span>v{{ attributes["revnumber"] }}</span>
-              {% endif %}
-              {% if attributes["revdate"] %}
-                <span>{{ attributes["revdate"] }}</span>
-              {% endif %}
-            </div>
-          {% endif %}
-        </header>
-      {% endif %}
-
-      <main class="doc-body">
-        {% for block in blocks %}
-          {% include "html5/block.stencil" %}
-        {% endfor %}
-      </main>
-
-      {% if footnotes %}
-        <div id="footnotes">
-          {% for f in footnotes %}
-    <div class="footnote" id="_footnotedef_{{ f.id }}">
-    <a href="#_footnoteref_{{ f.id }}">{{ f.id }}</a>. {{ f.content }}
-    </div>
-    {% endfor %}
-</div>
-{% endif %}
-
-{% if indexCatalog %}
-<div id="index" class="sect1">
-    <h2 id="_index">Index</h2>
-    <div class="sectionbody">
-        <ul class="index">
-        {% for entry in indexCatalog %}
-            <li>{{ entry.primary }}
-                {% if entry.secondary %}
-                <ul>
-                    {% for sec in entry.secondary %}
-                    <li>{{ sec.name }}
-                        {% if sec.tertiary %}
-                        <ul>
-                            {% for tert in sec.tertiary %}
-                            <li>{{ tert }}</li>
-                            {% endfor %}
-                        </ul>
-                        {% endif %}
-                    </li>
-                    {% endfor %}
-                </ul>
+    {% if xad and xad.enabled and xad.layoutTree %}
+      {% with node=xad.layoutTree %}
+        {% include "xad/layout-node.stencil" %}
+      {% endwith %}
+    {% else %}
+      <div class="doc-shell">
+        {% if headerTitle or attributes["subtitle"] or attributes["author"] or attributes["revdate"] %}
+          <header class="doc-header">
+            {% if headerTitle %}
+              <h1>{{ headerTitle }}</h1>
+            {% endif %}
+            {% if attributes["subtitle"] %}
+              <p class="subtitle">{{ attributes["subtitle"] }}</p>
+            {% endif %}
+            {% if attributes["author"] or attributes["revdate"] or attributes["revnumber"] %}
+              <div class="doc-meta">
+                {% if attributes["author"] %}
+                  <span>{{ attributes["author"] }}</span>
+                {% endif %}
+                {% if attributes["revnumber"] %}
+                  <span>v{{ attributes["revnumber"] }}</span>
+                {% endif %}
+                {% if attributes["revdate"] %}
+                  <span>{{ attributes["revdate"] }}</span>
                 {% endif %}
-            </li>
-        {% endfor %}
-        </ul>
-    </div>
-</div>
-{% endif %}
-
-    </div>
+              </div>
+            {% endif %}
+          </header>
+        {% endif %}
+
+        <main class="doc-body">
+          {% for block in blocks %}
+            {% include "html5/block.stencil" %}
+          {% endfor %}
+        </main>
+
+        {% if footnotes %}
+          <div id="footnotes">
+            {% for f in footnotes %}
+      <div class="footnote" id="_footnotedef_{{ f.id }}">
+      <a href="#_footnoteref_{{ f.id }}">{{ f.id }}</a>. {{ f.content }}
+      </div>
+      {% endfor %}
+  </div>
+  {% endif %}
+
+  {% if indexCatalog %}
+  <div id="index" class="sect1">
+      <h2 id="_index">Index</h2>
+      <div class="sectionbody">
+          <ul class="index">
+          {% for entry in indexCatalog %}
+              <li>{{ entry.primary }}
+                  {% if entry.secondary %}
+                  <ul>
+                      {% for sec in entry.secondary %}
+                      <li>{{ sec.name }}
+                          {% if sec.tertiary %}
+                          <ul>
+                              {% for tert in sec.tertiary %}
+                              <li>{{ tert }}</li>
+                              {% endfor %}
+                          </ul>
+                          {% endif %}
+                      </li>
+                      {% endfor %}
+                  </ul>
+                  {% endif %}
+              </li>
+          {% endfor %}
+          </ul>
+      </div>
+  </div>
+  {% endif %}
+
+      </div>
+    {% endif %}
     <script src="https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/highlight.min.js"></script>
     <script>document.addEventListener("DOMContentLoaded",function(){window.hljs&&window.hljs.highlightAll();});</script>
   </body>

From 368203c37743b8c091c73001d519cca1829a90fb Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Mon, 2 Mar 2026 22:27:19 +0100
Subject: [PATCH 30/38] Add sample layouts

---
 Templates/xad/double-column/layout.xad | 15 +++++++++++++++
 Templates/xad/trivial/layout.xad       | 11 +++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 Templates/xad/double-column/layout.xad
 create mode 100644 Templates/xad/trivial/layout.xad

diff --git a/Templates/xad/double-column/layout.xad b/Templates/xad/double-column/layout.xad
new file mode 100644
index 0000000..2e8eed2
--- /dev/null
+++ b/Templates/xad/double-column/layout.xad
@@ -0,0 +1,15 @@
+// Double-column layout with a header stack.
+pages[
+  page(master:"default")[
+    stack[
+      flow(slot("title")),
+      flow(slot("abstract")),
+      flow(slot("authors")),
+      // Content assigns slot="left" and slot="right" for columns.
+      grid[
+        place(area:"left")[ flow(slot("left")) ],
+        place(area:"right")[ flow(slot("right")) ]
+      ]
+    ]
+  ]
+]
diff --git a/Templates/xad/trivial/layout.xad b/Templates/xad/trivial/layout.xad
new file mode 100644
index 0000000..34afe6a
--- /dev/null
+++ b/Templates/xad/trivial/layout.xad
@@ -0,0 +1,11 @@
+// Trivial single-column layout.
+pages[
+  page(master:"default")[
+    stack[
+      flow(slot("title")),
+      flow(slot("abstract")),
+      flow(slot("authors")),
+      flow(slot("main"))
+    ]
+  ]
+]

From fe7e4040a7a2c688b699eb486b5605b8dd6d9d89 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Mon, 2 Mar 2026 22:33:25 +0100
Subject: [PATCH 31/38] Add initial examples

---
 examples/xad/double-column/README.adoc  |  9 ++++++++
 examples/xad/double-column/content.adoc | 28 +++++++++++++++++++++++++
 examples/xad/trivial/README.adoc        |  9 ++++++++
 examples/xad/trivial/content.adoc       | 21 +++++++++++++++++++
 4 files changed, 67 insertions(+)
 create mode 100644 examples/xad/double-column/README.adoc
 create mode 100644 examples/xad/double-column/content.adoc
 create mode 100644 examples/xad/trivial/README.adoc
 create mode 100644 examples/xad/trivial/content.adoc

diff --git a/examples/xad/double-column/README.adoc b/examples/xad/double-column/README.adoc
new file mode 100644
index 0000000..cdef2d2
--- /dev/null
+++ b/examples/xad/double-column/README.adoc
@@ -0,0 +1,9 @@
+= Double Column Template Example
+
+This example pairs `content.adoc` with the `Templates/xad/double-column` layout.
+
+To render:
+
+----
+asciidoc-swift xad-paged-html --xad-layout-template double-column examples/xad/double-column/content.adoc
+----
diff --git a/examples/xad/double-column/content.adoc b/examples/xad/double-column/content.adoc
new file mode 100644
index 0000000..c1b98d7
--- /dev/null
+++ b/examples/xad/double-column/content.adoc
@@ -0,0 +1,28 @@
+= Double Column Layout Example
+Author Example <author@example.com>
+:revdate: 2026-03-02
+
+[slot=title]
+Double Column Layout Example
+
+[slot=authors]
+Author Example
+
+[slot=abstract]
+This abstract sits above a two-column layout driven by left/right slots.
+
+== Left Column
+
+[slot=left, order=10]
+Left column paragraph one.
+
+[slot=left, order=20]
+Left column paragraph two.
+
+== Right Column
+
+[slot=right, order=10]
+Right column paragraph one.
+
+[slot=right, order=20]
+Right column paragraph two.
diff --git a/examples/xad/trivial/README.adoc b/examples/xad/trivial/README.adoc
new file mode 100644
index 0000000..ad3ea9e
--- /dev/null
+++ b/examples/xad/trivial/README.adoc
@@ -0,0 +1,9 @@
+= Trivial Template Example
+
+This example pairs `content.adoc` with the `Templates/xad/trivial` layout.
+
+To render:
+
+----
+asciidoc-swift xad-paged-html --xad-layout-template trivial examples/xad/trivial/content.adoc
+----
diff --git a/examples/xad/trivial/content.adoc b/examples/xad/trivial/content.adoc
new file mode 100644
index 0000000..f76247e
--- /dev/null
+++ b/examples/xad/trivial/content.adoc
@@ -0,0 +1,21 @@
+= Trivial Layout Example
+Author Example <author@example.com>
+:revdate: 2026-03-02
+
+[slot=title]
+Trivial Layout Example
+
+[slot=authors]
+Author Example
+
+[slot=abstract]
+This is a short abstract describing the trivial single-column layout.
+
+== Introduction
+
+This document demonstrates the trivial single-column template. The body
+content flows in the main slot.
+
+== Details
+
+More content goes here to show the normal flow.

From b46555def9c74d1be98540edbe8172588382068f Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Tue, 3 Mar 2026 06:50:56 +0100
Subject: [PATCH 32/38] Fix template and add rendering via script

---
 Templates/html5/document.stencil | 10 +++++++---
 scripts/render-showcase.sh       | 20 ++++++++++++++++++++
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/Templates/html5/document.stencil b/Templates/html5/document.stencil
index 98a800c..29961c7 100644
--- a/Templates/html5/document.stencil
+++ b/Templates/html5/document.stencil
@@ -477,9 +477,13 @@
   </head>
   <body>
     {% if xad and xad.enabled and xad.layoutTree %}
-      {% with node=xad.layoutTree %}
-        {% include "xad/layout-node.stencil" %}
-      {% endwith %}
+      <div class="xad-doc">
+        <div class="xad-layout">
+          {% for node in xad.layoutTree.nodes %}
+            {% include "xad/layout-node.stencil" %}
+          {% endfor %}
+        </div>
+      </div>
     {% else %}
       <div class="doc-shell">
         {% if headerTitle or attributes["subtitle"] or attributes["author"] or attributes["revdate"] %}
diff --git a/scripts/render-showcase.sh b/scripts/render-showcase.sh
index 9450797..5f1ebb9 100755
--- a/scripts/render-showcase.sh
+++ b/scripts/render-showcase.sh
@@ -26,6 +26,26 @@ render html html
 render docbook xml
 render latex tex
 
+render_xad_example() {
+  local name="$1"
+  local template="$2"
+  local doc="${REPO_ROOT}/examples/xad/${name}/content.adoc"
+  local out="${OUTPUT_DIR}/xad-${name}.html"
+  if [[ ! -f "${doc}" ]]; then
+    echo "⚠︎ XAD example not found at ${doc}; skipping"
+    return
+  fi
+  echo "→ Rendering XAD example ${name} (${template}) to ${out}"
+  swift run -q asciidoc-swift xad-paged-html \
+    --template "${TEMPLATE_ROOT}" \
+    --xad-layout-template "${template}" \
+    --output "${out}" \
+    "${doc}"
+}
+
+render_xad_example trivial trivial
+render_xad_example double-column double-column
+
 convert_docbook_pdf() {
   local xml="${OUTPUT_DIR}/showcase.xml"
   if [[ ! -f "${xml}" ]]; then

From 0c4701093619cecc0bca206d92b059e7c951b09c Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Tue, 3 Mar 2026 07:00:08 +0100
Subject: [PATCH 33/38] Enable paged.js inclusion

---
 Sources/AsciiDocRender/DocumentRender.swift | 44 ++++++++++++++++++++-
 Templates/html5/document.stencil            |  3 ++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index f2c03bb..dbbabd8 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -130,10 +130,11 @@ public final class DocumentRenderer {
         }
 
         let typedAttributes = docToRender.typedAttributes.mapValues { $0.toJSONCompatible() }
+        let pagedEnabled = config.xadOptions.pagedJS || isPagedAttributeEnabled(document: docToRender)
         var xadContext: [String: Any] = [
             "enabled": config.xadOptions.enabled,
             "strict": config.xadOptions.strict,
-            "pagedJS": config.xadOptions.pagedJS,
+            "pagedJS": pagedEnabled,
             "templatePath": config.xadOptions.templatePath ?? "",
             "layoutTemplate": config.xadOptions.layoutTemplate ?? "",
             "layoutTemplateBase": config.xadOptions.layoutTemplateBase ?? "",
@@ -808,6 +809,47 @@ public final class DocumentRenderer {
         }
     }
 
+    private func isPagedAttributeEnabled(document: AdocDocument) -> Bool {
+        if let typed = document.typedAttributes["paged"] {
+            return isTruthy(typed)
+        }
+        if let raw = document.attributes["paged"] {
+            return isTruthy(raw)
+        }
+        return false
+    }
+
+    private func isTruthy(_ value: XADAttributeValue) -> Bool {
+        switch value {
+        case .bool(let b):
+            return b
+        case .number(let n):
+            return n != 0
+        case .string(let s):
+            return isTruthy(s)
+        case .null:
+            return false
+        case .array(let arr):
+            return !arr.isEmpty
+        case .dictionary(let dict):
+            return !dict.isEmpty
+        }
+    }
+
+    private func isTruthy(_ value: String?) -> Bool {
+        guard let value else { return false }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return true }
+        switch trimmed.lowercased() {
+        case "true", "yes", "on", "1":
+            return true
+        case "false", "no", "off", "0":
+            return false
+        default:
+            return true
+        }
+    }
+
     private func renderInlines(_ inlines: [AdocInline], context: InlineContext) -> String {
         inlineRenderer.render(inlines, context: context)
     }
diff --git a/Templates/html5/document.stencil b/Templates/html5/document.stencil
index 29961c7..d0221f0 100644
--- a/Templates/html5/document.stencil
+++ b/Templates/html5/document.stencil
@@ -557,6 +557,9 @@
 
       </div>
     {% endif %}
+    {% if xad and xad.pagedJS %}
+      <script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
+    {% endif %}
     <script src="https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/highlight.min.js"></script>
     <script>document.addEventListener("DOMContentLoaded",function(){window.hljs&&window.hljs.highlightAll();});</script>
   </body>

From 05c7ef95ed6cc6b141df2a3b3f8a09ce7e705d47 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Tue, 3 Mar 2026 07:32:47 +0100
Subject: [PATCH 34/38] Use of adoc-hosted templates

---
 .../TemplateIngestion.swift                   | 194 ++++++++++++++++++
 .../TemplateRegistry.swift                    |  40 ++--
 Sources/AsciiDocRender/DocumentRender.swift   |  39 +++-
 Sources/asciidoc-swift/Commands.swift         |   8 +-
 Templates/html5/document.stencil              |  10 +
 .../xad/default/{layout.xad => template.adoc} |   5 +
 .../{layout.xad => template.adoc}             |   5 +
 Templates/xad/layout-node.stencil             |  49 +++++
 .../xad/trivial/{layout.xad => template.adoc} |   5 +
 .../TemplateIngestionTests.swift              |  36 ++++
 .../TemplateRegistryTests.swift               |  28 ++-
 11 files changed, 382 insertions(+), 37 deletions(-)
 create mode 100644 Sources/AsciiDocPagedRendering/TemplateIngestion.swift
 rename Templates/xad/default/{layout.xad => template.adoc} (69%)
 rename Templates/xad/double-column/{layout.xad => template.adoc} (89%)
 create mode 100644 Templates/xad/layout-node.stencil
 rename Templates/xad/trivial/{layout.xad => template.adoc} (83%)
 create mode 100644 Tests/AsciiDocCoreTests/TemplateIngestionTests.swift

diff --git a/Sources/AsciiDocPagedRendering/TemplateIngestion.swift b/Sources/AsciiDocPagedRendering/TemplateIngestion.swift
new file mode 100644
index 0000000..40102c5
--- /dev/null
+++ b/Sources/AsciiDocPagedRendering/TemplateIngestion.swift
@@ -0,0 +1,194 @@
+//
+// Copyright (c) 2026 Mattias Holm
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+import AsciiDocCore
+
+public struct XADTemplateAssets: Sendable, Equatable {
+    public var css: [String]
+    public var js: [String]
+
+    public init(css: [String] = [], js: [String] = []) {
+        self.css = css
+        self.js = js
+    }
+}
+
+public struct XADTemplateDocument: Sendable, Equatable {
+    public var url: URL
+    public var attributes: [String: String?]
+    public var typedAttributes: [String: XADAttributeValue]
+    public var layoutProgram: LayoutProgram?
+    public var assets: XADTemplateAssets
+
+    public init(
+        url: URL,
+        attributes: [String: String?],
+        typedAttributes: [String: XADAttributeValue],
+        layoutProgram: LayoutProgram?,
+        assets: XADTemplateAssets
+    ) {
+        self.url = url
+        self.attributes = attributes
+        self.typedAttributes = typedAttributes
+        self.layoutProgram = layoutProgram
+        self.assets = assets
+    }
+}
+
+public struct XADTemplateIngestor: Sendable {
+    public init() {}
+
+    public func ingestTemplate(
+        at url: URL,
+        xadOptions: XADOptions = .init(enabled: true)
+    ) -> (XADTemplateDocument?, [AdocWarning]) {
+        var warnings: [AdocWarning] = []
+        let data: Data
+        do {
+            data = try Data(contentsOf: url)
+        } catch {
+            warnings.append(AdocWarning(message: "failed to read template: \(error.localizedDescription)", span: nil))
+            return (nil, warnings)
+        }
+        guard let text = String(data: data, encoding: .utf8) else {
+            warnings.append(AdocWarning(message: "template must be UTF-8", span: nil))
+            return (nil, warnings)
+        }
+
+        var options = xadOptions
+        options.enabled = true
+
+        let parser = AdocParser()
+        let preprocessorOptions = Preprocessor.Options(sourceURL: url)
+        let document = parser.parse(
+            text: text,
+            preprocessorOptions: preprocessorOptions,
+            xadOptions: options
+        )
+        warnings.append(contentsOf: document.warnings)
+
+        let assets = XADTemplateAssets(
+            css: parseAssetList(document.attributes["template.css"] ?? nil),
+            js: parseAssetList(document.attributes["template.js"] ?? nil)
+        )
+
+        let program = extractLayoutProgram(from: document.blocks, warnings: &warnings)
+        let template = XADTemplateDocument(
+            url: url,
+            attributes: document.attributes,
+            typedAttributes: document.typedAttributes,
+            layoutProgram: program,
+            assets: assets
+        )
+        return (template, warnings)
+    }
+}
+
+private func parseAssetList(_ raw: String?) -> [String] {
+    guard let raw = raw?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
+        return []
+    }
+    if raw.contains(",") {
+        return raw
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+    }
+    return raw
+        .split(whereSeparator: { $0.isWhitespace })
+        .map(String.init)
+        .filter { !$0.isEmpty }
+}
+
+private func extractLayoutProgram(
+    from blocks: [AdocBlock],
+    warnings: inout [AdocWarning]
+) -> LayoutProgram? {
+    var programs: [LayoutProgram] = []
+
+    func visit(_ blocks: [AdocBlock]) {
+        for block in blocks {
+            if let source = layoutSource(from: block) {
+                let parser = LayoutDSLParser()
+                let (program, parserWarnings) = parser.parse(text: source.text, span: source.span)
+                warnings.append(contentsOf: parserWarnings)
+                if let program {
+                    programs.append(program)
+                } else {
+                    warnings.append(
+                        AdocWarning(message: "layout block did not produce a layout program", span: source.span)
+                    )
+                }
+            }
+
+            switch block {
+            case .section(let section):
+                visit(section.blocks)
+            case .sidebar(let sidebar):
+                visit(sidebar.blocks)
+            case .example(let example):
+                visit(example.blocks)
+            case .quote(let quote):
+                visit(quote.blocks)
+            case .open(let open):
+                visit(open.blocks)
+            case .admonition(let admonition):
+                visit(admonition.blocks)
+            case .verse(let verse):
+                visit(verse.blocks)
+            case .list(let list):
+                for item in list.items {
+                    visit(item.blocks)
+                }
+            case .dlist(let dlist):
+                for item in dlist.items {
+                    visit(item.blocks)
+                }
+            default:
+                break
+            }
+        }
+    }
+
+    visit(blocks)
+
+    if programs.isEmpty {
+        warnings.append(AdocWarning(message: "template did not contain a [layout] block", span: nil))
+        return nil
+    }
+    if programs.count > 1 {
+        warnings.append(AdocWarning(message: "template contains multiple [layout] blocks; using the first one", span: nil))
+    }
+    return programs.first
+}
+
+private func layoutSource(from block: AdocBlock) -> (text: String, span: AdocRange?)? {
+    switch block {
+    case .listing(let listing):
+        if isLayoutStyle(listing.meta) {
+            return (listing.text.plain, listing.span)
+        }
+    case .literalBlock(let literal):
+        if isLayoutStyle(literal.meta) {
+            return (literal.text.plain, literal.span)
+        }
+    default:
+        break
+    }
+    return nil
+}
+
+private func isLayoutStyle(_ meta: AdocBlockMeta) -> Bool {
+    if let style = meta.attributes["style"]?.trimmingCharacters(in: .whitespacesAndNewlines),
+       style.lowercased() == "layout" {
+        return true
+    }
+    if let positional = meta.attributes["1"]?.trimmingCharacters(in: .whitespacesAndNewlines),
+       positional.lowercased() == "layout" {
+        return true
+    }
+    return false
+}
diff --git a/Sources/AsciiDocPagedRendering/TemplateRegistry.swift b/Sources/AsciiDocPagedRendering/TemplateRegistry.swift
index 5334652..8236b84 100644
--- a/Sources/AsciiDocPagedRendering/TemplateRegistry.swift
+++ b/Sources/AsciiDocPagedRendering/TemplateRegistry.swift
@@ -48,8 +48,8 @@ public struct XADTemplateRegistry: Sendable {
                 guard (try? entry.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true else {
                     continue
                 }
-                let layoutURL = entry.appendingPathComponent("layout.xad")
-                if fileManager.fileExists(atPath: layoutURL.path) {
+                let templateURL = entry.appendingPathComponent("template.adoc")
+                if fileManager.fileExists(atPath: templateURL.path) {
                     names.insert(entry.lastPathComponent)
                 }
             }
@@ -77,44 +77,32 @@ public struct XADTemplateRegistry: Sendable {
         fileManager: FileManager = .default
     ) -> (XADTemplateDescriptor?, [AdocWarning]) {
         var warnings: [AdocWarning] = []
-        let layoutURL: URL
+        let templateURL: URL
         var name = templateName ?? url.deletingPathExtension().lastPathComponent
 
         if url.hasDirectoryPath {
-            layoutURL = url.appendingPathComponent("layout.xad")
+            templateURL = url.appendingPathComponent("template.adoc")
             name = url.lastPathComponent
         } else {
-            layoutURL = url
+            templateURL = url
         }
 
-        guard fileManager.fileExists(atPath: layoutURL.path) else {
-            warnings.append(AdocWarning(message: "layout.xad not found at \(layoutURL.path)", span: nil))
+        guard fileManager.fileExists(atPath: templateURL.path) else {
+            warnings.append(AdocWarning(message: "template.adoc not found at \(templateURL.path)", span: nil))
             return (nil, warnings)
         }
 
-        let data: Data
-        do {
-            data = try Data(contentsOf: layoutURL)
-        } catch {
-            warnings.append(AdocWarning(message: "failed to read template: \(error.localizedDescription)", span: nil))
-            return (nil, warnings)
-        }
-        guard let text = String(data: data, encoding: .utf8) else {
-            warnings.append(AdocWarning(message: "template must be UTF-8", span: nil))
-            return (nil, warnings)
-        }
-
-        let parser = LayoutDSLParser()
-        let (program, parserWarnings) = parser.parse(text: text)
-        warnings.append(contentsOf: parserWarnings)
+        let ingestor = XADTemplateIngestor()
+        let (templateDoc, ingestWarnings) = ingestor.ingestTemplate(at: templateURL)
+        warnings.append(contentsOf: ingestWarnings)
 
-        guard let program else {
+        guard let program = templateDoc?.layoutProgram else {
             warnings.append(AdocWarning(message: "template did not produce a layout program", span: nil))
             return (nil, warnings)
         }
 
-        let base = baseURL ?? layoutURL.deletingLastPathComponent()
-        let template = XADTemplateDescriptor(name: name, baseURL: base, layoutURL: layoutURL, program: program)
+        let base = baseURL ?? templateURL.deletingLastPathComponent()
+        let template = XADTemplateDescriptor(name: name, baseURL: base, layoutURL: templateURL, program: program)
         return (template, warnings)
     }
 
@@ -123,7 +111,7 @@ public struct XADTemplateRegistry: Sendable {
             let candidate = root
                 .appendingPathComponent("xad", isDirectory: true)
                 .appendingPathComponent(name, isDirectory: true)
-                .appendingPathComponent("layout.xad")
+                .appendingPathComponent("template.adoc")
             if fileManager.fileExists(atPath: candidate.path) {
                 return candidate
             }
diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index dbbabd8..d576423 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -114,6 +114,26 @@ public final class DocumentRenderer {
             blocks = renderBlocks(docToRender.blocks, context: inlineContext)
         }
 
+        var templateDocument: XADTemplateDocument?
+        var templateWarnings: [AdocWarning] = []
+        var layoutProgram = config.xadLayoutProgram
+        if config.xadOptions.enabled, let templatePath = config.xadOptions.templatePath {
+            let templateURL = resolveTemplateURL(
+                templatePath,
+                relativeTo: sourceURL?.deletingLastPathComponent()
+            )
+            let ingestor = XADTemplateIngestor()
+            let (template, warnings) = ingestor.ingestTemplate(
+                at: templateURL,
+                xadOptions: config.xadOptions
+            )
+            templateDocument = template
+            templateWarnings.append(contentsOf: warnings)
+            if let program = template?.layoutProgram {
+                layoutProgram = program
+            }
+        }
+
         let indexResolver = IndexResolver()
         let indexCatalog = indexResolver.resolve(docToRender)
 
@@ -148,7 +168,8 @@ public final class DocumentRenderer {
             xadContext["collections"] = collectionContexts
 
             var warnings = slotExtraction.warnings
-            if let program = config.xadLayoutProgram {
+            warnings.append(contentsOf: templateWarnings)
+            if let program = layoutProgram {
                 let evaluator = XADLayoutEvaluator()
                 let evaluation = evaluator.evaluate(
                     program: program,
@@ -163,9 +184,18 @@ public final class DocumentRenderer {
                 xadContext["warnings"] = warnings.map { $0.message }
             }
         }
-        if let program = config.xadLayoutProgram {
+        if let program = layoutProgram {
             xadContext["layoutProgram"] = layoutProgramContext(program)
         }
+        if let templateDocument {
+            xadContext["template"] = [
+                "path": templateDocument.url.path,
+                "attributes": templateDocument.attributes,
+                "typedAttributes": templateDocument.typedAttributes.mapValues { $0.toJSONCompatible() },
+                "css": templateDocument.assets.css,
+                "js": templateDocument.assets.js
+            ]
+        }
 
         var context: [String: Any] = [
             "attributes": docToRender.attributes,
@@ -809,6 +839,11 @@ public final class DocumentRenderer {
         }
     }
 
+    private func resolveTemplateURL(_ raw: String, relativeTo baseURL: URL?) -> URL {
+        let base = baseURL ?? URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
+        return URL(fileURLWithPath: raw, relativeTo: base).standardizedFileURL
+    }
+
     private func isPagedAttributeEnabled(document: AdocDocument) -> Bool {
         if let typed = document.typedAttributes["paged"] {
             return isTruthy(typed)
diff --git a/Sources/asciidoc-swift/Commands.swift b/Sources/asciidoc-swift/Commands.swift
index 256af94..20a1f87 100644
--- a/Sources/asciidoc-swift/Commands.swift
+++ b/Sources/asciidoc-swift/Commands.swift
@@ -383,11 +383,13 @@ struct XadPagedHtml: AsyncParsableCommand {
             throw ValidationError("Unable to load XAD template: \(templateSelection)")
         }
 
+        let xadLayoutProgram = templateResult.0?.program
+        let templatePath = xadTemplate ?? templateResult.0?.layoutURL.path
         let xadOptions = makeXadOptions(
             enabled: true,
             pagedJS: true,
             strict: xadStrict,
-            templatePath: xadTemplate,
+            templatePath: templatePath,
             layoutTemplate: templateSelection,
             layoutTemplateBase: xadTemplateBase,
             layoutTemplateSearchPaths: xadTemplateSearchPath
@@ -401,7 +403,8 @@ struct XadPagedHtml: AsyncParsableCommand {
             attributeAssignments: attributeAssignments,
             outputPath: output,
             enabledExtensions: extensions,
-            xadOptions: xadOptions
+            xadOptions: xadOptions,
+            xadLayoutProgram: xadLayoutProgram
         )
     }
 }
@@ -889,7 +892,6 @@ private func renderDocument(
         config: RenderConfig(
             backend: backend,
             xadOptions: xadOptions,
-            xadLayoutProgram: xadLayoutProgram
         )
     )
     let rendered = try renderer.render(document: doc)
diff --git a/Templates/html5/document.stencil b/Templates/html5/document.stencil
index d0221f0..50b20f3 100644
--- a/Templates/html5/document.stencil
+++ b/Templates/html5/document.stencil
@@ -6,6 +6,11 @@
     <title>{{ headerTitle }}</title>
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/styles/default.min.css">
     <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/highlight.min.js"></script>
+    {% if xad and xad.template and xad.template.css %}
+      {% for href in xad.template.css %}
+    <link rel="stylesheet" href="{{ href }}">
+      {% endfor %}
+    {% endif %}
     <style>
       :root {
         --surface: #ffffff;
@@ -557,6 +562,11 @@
 
       </div>
     {% endif %}
+    {% if xad and xad.template and xad.template.js %}
+      {% for src in xad.template.js %}
+    <script src="{{ src }}"></script>
+      {% endfor %}
+    {% endif %}
     {% if xad and xad.pagedJS %}
       <script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
     {% endif %}
diff --git a/Templates/xad/default/layout.xad b/Templates/xad/default/template.adoc
similarity index 69%
rename from Templates/xad/default/layout.xad
rename to Templates/xad/default/template.adoc
index e75a6ce..23b3af4 100644
--- a/Templates/xad/default/layout.xad
+++ b/Templates/xad/default/template.adoc
@@ -1,6 +1,11 @@
+= Default Template
+
+[layout]
+----
 // Default XAD paged layout
 pages[
   page(master:"default")[
     flow(slot("main"))
   ]
 ]
+----
diff --git a/Templates/xad/double-column/layout.xad b/Templates/xad/double-column/template.adoc
similarity index 89%
rename from Templates/xad/double-column/layout.xad
rename to Templates/xad/double-column/template.adoc
index 2e8eed2..06e06c1 100644
--- a/Templates/xad/double-column/layout.xad
+++ b/Templates/xad/double-column/template.adoc
@@ -1,3 +1,7 @@
+= Double Column Template
+
+[layout]
+----
 // Double-column layout with a header stack.
 pages[
   page(master:"default")[
@@ -13,3 +17,4 @@ pages[
     ]
   ]
 ]
+----
diff --git a/Templates/xad/layout-node.stencil b/Templates/xad/layout-node.stencil
new file mode 100644
index 0000000..46dce32
--- /dev/null
+++ b/Templates/xad/layout-node.stencil
@@ -0,0 +1,49 @@
+{% if node.kind == "pages" %}
+  <div class="xad-layout">
+    {% for node in node.children %}
+      {% include "xad/layout-node.stencil" %}
+    {% endfor %}
+  </div>
+{% elif node.kind == "page" %}
+  <section class="xad-page" {% if node.args.master %}data-master="{{ node.args.master }}"{% endif %}>
+    {% for node in node.children %}
+      {% include "xad/layout-node.stencil" %}
+    {% endfor %}
+  </section>
+{% elif node.kind == "grid" %}
+  <div class="xad-grid">
+    {% for node in node.children %}
+      {% include "xad/layout-node.stencil" %}
+    {% endfor %}
+  </div>
+{% elif node.kind == "place" %}
+  <div class="xad-area" {% if node.args.area %}data-area="{{ node.args.area }}"{% endif %}>
+    {% for node in node.children %}
+      {% include "xad/layout-node.stencil" %}
+    {% endfor %}
+  </div>
+{% elif node.kind == "stack" %}
+  <div class="xad-stack">
+    {% for node in node.children %}
+      {% include "xad/layout-node.stencil" %}
+    {% endfor %}
+  </div>
+{% elif node.kind == "flow" %}
+  <div class="xad-flow" {% if node.dataSlot %}data-slot="{{ node.dataSlot }}"{% endif %}>
+    {% for block in node.blocks %}
+      {% include "html5/block.stencil" %}
+    {% endfor %}
+  </div>
+{% elif node.kind == "text" %}
+  <div class="xad-text">{{ node.text }}</div>
+{% elif node.kind == "counter" %}
+  <span class="xad-counter"></span>
+{% elif node.kind == "sink" %}
+  <div class="xad-sink" {% if node.args.kind %}data-kind="{{ node.args.kind }}"{% endif %}{% if node.args.scope %} data-scope="{{ node.args.scope }}"{% endif %}></div>
+{% else %}
+  <div class="xad-node">
+    {% for node in node.children %}
+      {% include "xad/layout-node.stencil" %}
+    {% endfor %}
+  </div>
+{% endif %}
diff --git a/Templates/xad/trivial/layout.xad b/Templates/xad/trivial/template.adoc
similarity index 83%
rename from Templates/xad/trivial/layout.xad
rename to Templates/xad/trivial/template.adoc
index 34afe6a..83aac31 100644
--- a/Templates/xad/trivial/layout.xad
+++ b/Templates/xad/trivial/template.adoc
@@ -1,3 +1,7 @@
+= Trivial Template
+
+[layout]
+----
 // Trivial single-column layout.
 pages[
   page(master:"default")[
@@ -9,3 +13,4 @@ pages[
     ]
   ]
 ]
+----
diff --git a/Tests/AsciiDocCoreTests/TemplateIngestionTests.swift b/Tests/AsciiDocCoreTests/TemplateIngestionTests.swift
new file mode 100644
index 0000000..d54f9fb
--- /dev/null
+++ b/Tests/AsciiDocCoreTests/TemplateIngestionTests.swift
@@ -0,0 +1,36 @@
+import Testing
+import Foundation
+import AsciiDocPagedRendering
+
+@Suite("XAD Template Ingestion")
+struct XADTemplateIngestionTests {
+    @Test
+    func ingestsLayoutBlockAndAssets() throws {
+        let fileManager = FileManager.default
+        let root = fileManager.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        let templateURL = root.appendingPathComponent("template.adoc")
+        try fileManager.createDirectory(at: root, withIntermediateDirectories: true)
+        defer { try? fileManager.removeItem(at: root) }
+
+        let source = """
+        = Template
+        :template.css: template.css, theme.css
+        :template.js: template.js
+
+        [layout]
+        ----
+        pages[]
+        ----
+        """
+        try source.write(to: templateURL, atomically: true, encoding: .utf8)
+
+        let ingestor = XADTemplateIngestor()
+        let (template, warnings) = ingestor.ingestTemplate(at: templateURL)
+
+        #expect(warnings.isEmpty)
+        #expect(template != nil)
+        #expect(template?.layoutProgram != nil)
+        #expect(template?.assets.css == ["template.css", "theme.css"])
+        #expect(template?.assets.js == ["template.js"])
+    }
+}
diff --git a/Tests/AsciiDocCoreTests/TemplateRegistryTests.swift b/Tests/AsciiDocCoreTests/TemplateRegistryTests.swift
index 62ff031..6fce346 100644
--- a/Tests/AsciiDocCoreTests/TemplateRegistryTests.swift
+++ b/Tests/AsciiDocCoreTests/TemplateRegistryTests.swift
@@ -11,15 +11,23 @@ struct XADTemplateRegistryTests {
         let templatesRoot = root.appendingPathComponent("Templates")
         let layoutDir = templatesRoot.appendingPathComponent("xad/default", isDirectory: true)
         try fileManager.createDirectory(at: layoutDir, withIntermediateDirectories: true)
-        let layoutURL = layoutDir.appendingPathComponent("layout.xad")
-        try "pages[]".write(to: layoutURL, atomically: true, encoding: .utf8)
+        let templateURL = layoutDir.appendingPathComponent("template.adoc")
+        let template = """
+        = Template
+        
+        [layout]
+        ----
+        pages[]
+        ----
+        """
+        try template.write(to: templateURL, atomically: true, encoding: .utf8)
         defer { try? fileManager.removeItem(at: root) }
 
         let registry = XADTemplateRegistry(searchPaths: [templatesRoot])
-        let (template, warnings) = registry.loadTemplate(named: "default")
+        let (loadedTemplate, warnings) = registry.loadTemplate(named: "default")
 
         #expect(warnings.isEmpty)
-        #expect(template != nil)
+        #expect(loadedTemplate != nil)
     }
 
     @Test
@@ -29,8 +37,16 @@ struct XADTemplateRegistryTests {
         let templatesRoot = root.appendingPathComponent("Templates")
         let layoutDir = templatesRoot.appendingPathComponent("xad/demo", isDirectory: true)
         try fileManager.createDirectory(at: layoutDir, withIntermediateDirectories: true)
-        let layoutURL = layoutDir.appendingPathComponent("layout.xad")
-        try "pages[]".write(to: layoutURL, atomically: true, encoding: .utf8)
+        let templateURL = layoutDir.appendingPathComponent("template.adoc")
+        let template = """
+        = Template
+        
+        [layout]
+        ----
+        pages[]
+        ----
+        """
+        try template.write(to: templateURL, atomically: true, encoding: .utf8)
         defer { try? fileManager.removeItem(at: root) }
 
         let registry = XADTemplateRegistry(searchPaths: [templatesRoot])

From 7e56a4c53fdda2432013cd91f9d164e116188f22 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Tue, 3 Mar 2026 07:53:31 +0100
Subject: [PATCH 35/38] Ensure layouts are passed through raw

---
 Sources/AsciiDocCore/Attributes.swift | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Sources/AsciiDocCore/Attributes.swift b/Sources/AsciiDocCore/Attributes.swift
index f350ebd..d3dc6f7 100644
--- a/Sources/AsciiDocCore/Attributes.swift
+++ b/Sources/AsciiDocCore/Attributes.swift
@@ -476,6 +476,11 @@ package extension AdocText {
     }
 }
 
+private func expandRawText(_ text: AdocText, using env: AttrEnv) -> AdocText {
+    let expanded = env.expand(text.plain)
+    return AdocText(inlines: [.text(expanded, span: text.span)], span: text.span)
+}
+
 package extension AdocParagraph {
     func applyingAttributes(using env: AttrEnv) -> AdocParagraph {
         var copy = self
@@ -490,7 +495,7 @@ package extension AdocParagraph {
 package extension AdocListing {
     func applyingAttributes(using env: AttrEnv) -> AdocListing {
         var copy = self
-        copy.text = copy.text.applyingAttributes(using: env)
+        copy.text = expandRawText(copy.text, using: env)
         if let t = copy.title { copy.title = t.applyingAttributes(using: env) }
         if let r = copy.reftext { copy.reftext = r.applyingAttributes(using: env) }
         return copy
@@ -591,7 +596,7 @@ package extension AdocBlock {
             return .verse(vv)
         case .literalBlock(let lb):
             var ll = lb
-            ll.text = ll.text.applyingAttributes(using: env)
+            ll.text = expandRawText(ll.text, using: env)
             if let t = ll.title { ll.title = t.applyingAttributes(using: env) }
             if let r = ll.reftext { ll.reftext = r.applyingAttributes(using: env) }
             return .literalBlock(ll)

From a8cba94c65a78f2f2f56b60ebc44bf84785ef58a Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Wed, 4 Mar 2026 06:58:22 +0100
Subject: [PATCH 36/38] Adjust document style to support double column layout

---
 Templates/html5/document.stencil | 41 ++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/Templates/html5/document.stencil b/Templates/html5/document.stencil
index 50b20f3..0d4650d 100644
--- a/Templates/html5/document.stencil
+++ b/Templates/html5/document.stencil
@@ -85,8 +85,27 @@
         gap: 1.5rem;
       }
 
+      .xad-page {
+        background: var(--surface);
+        border: 1px solid var(--border-soft);
+        border-radius: 20px;
+        padding: 2rem;
+        min-height: 11in;
+        box-shadow: var(--shadow-soft);
+      }
+
+      .xad-stack {
+        display: grid;
+        gap: 1.5rem;
+      }
+
+      .xad-flow {
+        min-width: 0;
+      }
+
       .xad-grid {
         display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(0, 1fr));
         gap: 1.5rem;
       }
 
@@ -456,6 +475,28 @@
         background: var(--surface-muted);
       }
 
+      @media print {
+        body {
+          background: #ffffff;
+          padding: 0;
+        }
+
+        .xad-doc {
+          width: auto;
+          margin: 0;
+          padding: 0;
+          box-shadow: none;
+          border-radius: 0;
+        }
+
+        .xad-page {
+          box-shadow: none;
+          border: none;
+          border-radius: 0;
+          page-break-after: always;
+        }
+      }
+
       /* Footnotes */
       #footnotes {
         margin-top: 3rem;

From 5b58d60c53980572f3e5d38a40b18626599928ba Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Wed, 4 Mar 2026 07:06:50 +0100
Subject: [PATCH 37/38] Improvements in column flow handling

---
 Templates/html5/document.stencil              | 10 ++++++
 .../template.adoc                             |  2 +-
 .../xad/double-column-flow/template.adoc      | 16 +++++++++
 .../README.adoc                               |  4 +--
 .../content.adoc                              |  0
 examples/xad/double-column-flow/README.adoc   |  9 +++++
 examples/xad/double-column-flow/content.adoc  | 33 +++++++++++++++++++
 scripts/render-showcase.sh                    |  3 +-
 8 files changed, 73 insertions(+), 4 deletions(-)
 rename Templates/xad/{double-column => double-column-explicit}/template.adoc (92%)
 create mode 100644 Templates/xad/double-column-flow/template.adoc
 rename examples/xad/{double-column => double-column-explicit}/README.adoc (68%)
 rename examples/xad/{double-column => double-column-explicit}/content.adoc (100%)
 create mode 100644 examples/xad/double-column-flow/README.adoc
 create mode 100644 examples/xad/double-column-flow/content.adoc

diff --git a/Templates/html5/document.stencil b/Templates/html5/document.stencil
index 0d4650d..fec01ee 100644
--- a/Templates/html5/document.stencil
+++ b/Templates/html5/document.stencil
@@ -116,6 +116,16 @@
         background: linear-gradient(135deg, var(--surface), var(--surface-muted));
       }
 
+      .xad-area[data-area="columns"] {
+        column-count: 2;
+        column-gap: 2rem;
+        column-rule: 1px solid var(--border-soft);
+      }
+
+      .xad-area[data-area="columns"] > * {
+        break-inside: avoid;
+      }
+
       .xad-sink {
         padding: 1rem;
         border: 1px dashed var(--border-soft);
diff --git a/Templates/xad/double-column/template.adoc b/Templates/xad/double-column-explicit/template.adoc
similarity index 92%
rename from Templates/xad/double-column/template.adoc
rename to Templates/xad/double-column-explicit/template.adoc
index 06e06c1..100c97b 100644
--- a/Templates/xad/double-column/template.adoc
+++ b/Templates/xad/double-column-explicit/template.adoc
@@ -1,4 +1,4 @@
-= Double Column Template
+= Double Column Explicit Template
 
 [layout]
 ----
diff --git a/Templates/xad/double-column-flow/template.adoc b/Templates/xad/double-column-flow/template.adoc
new file mode 100644
index 0000000..9852ac9
--- /dev/null
+++ b/Templates/xad/double-column-flow/template.adoc
@@ -0,0 +1,16 @@
+= Double Column Flow Template
+
+[layout]
+----
+// Double-column flow layout with a header stack.
+pages[
+  page(master:"default")[
+    stack[
+      flow(slot("title")),
+      flow(slot("abstract")),
+      flow(slot("authors")),
+      place(area:"columns")[ flow(slot("main")) ]
+    ]
+  ]
+]
+----
diff --git a/examples/xad/double-column/README.adoc b/examples/xad/double-column-explicit/README.adoc
similarity index 68%
rename from examples/xad/double-column/README.adoc
rename to examples/xad/double-column-explicit/README.adoc
index cdef2d2..6df4909 100644
--- a/examples/xad/double-column/README.adoc
+++ b/examples/xad/double-column-explicit/README.adoc
@@ -1,9 +1,9 @@
 = Double Column Template Example
 
-This example pairs `content.adoc` with the `Templates/xad/double-column` layout.
+This example pairs `content.adoc` with the `Templates/xad/double-column-explicit` layout.
 
 To render:
 
 ----
-asciidoc-swift xad-paged-html --xad-layout-template double-column examples/xad/double-column/content.adoc
+asciidoc-swift xad-paged-html --xad-layout-template double-column-explicit examples/xad/double-column-explicit/content.adoc
 ----
diff --git a/examples/xad/double-column/content.adoc b/examples/xad/double-column-explicit/content.adoc
similarity index 100%
rename from examples/xad/double-column/content.adoc
rename to examples/xad/double-column-explicit/content.adoc
diff --git a/examples/xad/double-column-flow/README.adoc b/examples/xad/double-column-flow/README.adoc
new file mode 100644
index 0000000..7480fed
--- /dev/null
+++ b/examples/xad/double-column-flow/README.adoc
@@ -0,0 +1,9 @@
+= Double Column Flow Template Example
+
+This example pairs `content.adoc` with the `Templates/xad/double-column-flow` layout.
+
+To render:
+
+----
+asciidoc-swift xad-paged-html --xad-layout-template double-column-flow examples/xad/double-column-flow/content.adoc
+----
diff --git a/examples/xad/double-column-flow/content.adoc b/examples/xad/double-column-flow/content.adoc
new file mode 100644
index 0000000..04c6bfb
--- /dev/null
+++ b/examples/xad/double-column-flow/content.adoc
@@ -0,0 +1,33 @@
+= Double Column Flow Example
+Author Example <author@example.com>
+:revdate: 2026-03-02
+
+[slot=title]
+Double Column Flow Example
+
+[slot=authors]
+Author Example
+
+[slot=abstract]
+This abstract sits above a two-column flow where content flows across columns.
+
+== Introduction
+
+[slot=main]
+This opening section introduces the main flow. It should start in the left column
+and continue into the right column as needed.
+
+[slot=main]
+A second paragraph to build enough content for column flow. Lorem ipsum dolor sit amet,
+consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+== Details
+
+[slot=main]
+This section continues in the same slot so it participates in the column flow. Use it to
+verify that headings and paragraphs stay within the two-column area.
+
+[slot=main]
+- First item in the flowing column list.
+- Second item in the flowing column list.
+- Third item in the flowing column list.
diff --git a/scripts/render-showcase.sh b/scripts/render-showcase.sh
index 5f1ebb9..98a7b7d 100755
--- a/scripts/render-showcase.sh
+++ b/scripts/render-showcase.sh
@@ -44,7 +44,8 @@ render_xad_example() {
 }
 
 render_xad_example trivial trivial
-render_xad_example double-column double-column
+render_xad_example double-column-explicit double-column-explicit
+render_xad_example double-column-flow double-column-flow
 
 convert_docbook_pdf() {
   local xml="${OUTPUT_DIR}/showcase.xml"

From 82c7dc73d31b9240e200c70e034e8beafa95f4d1 Mon Sep 17 00:00:00 2001
From: Mattias Holm <lorrden@openorbit.org>
Date: Wed, 4 Mar 2026 07:29:23 +0100
Subject: [PATCH 38/38] Ensure we rely on adoc roles for slot assignment where
 applicable

---
 Sources/AsciiDocRender/DocumentRender.swift   | 141 ++++++++++++++++--
 Templates/html5/document.stencil              |   4 +
 Templates/xad/default/template.adoc           |   1 +
 .../xad/double-column-explicit/template.adoc  |   1 +
 .../xad/double-column-flow/template.adoc      |   1 +
 Templates/xad/trivial/template.adoc           |   1 +
 .../xad/double-column-explicit/content.adoc   |  20 ++-
 examples/xad/double-column-flow/content.adoc  |  27 +++-
 examples/xad/trivial/content.adoc             |   8 +-
 9 files changed, 169 insertions(+), 35 deletions(-)

diff --git a/Sources/AsciiDocRender/DocumentRender.swift b/Sources/AsciiDocRender/DocumentRender.swift
index d576423..199381a 100644
--- a/Sources/AsciiDocRender/DocumentRender.swift
+++ b/Sources/AsciiDocRender/DocumentRender.swift
@@ -99,10 +99,7 @@ public final class DocumentRenderer {
         let slotExtraction: SlotExtractionResult
         let blocks: [[String: Any]]
         if config.xadOptions.enabled {
-            slotExtraction = extractSlotsAndCollections(
-                from: docToRender.blocks,
-                attributes: docToRender.attributes
-            )
+            slotExtraction = extractSlotsAndCollections(from: docToRender)
             blocks = renderBlocks(slotExtraction.mainBlocks, context: inlineContext)
         } else {
             slotExtraction = SlotExtractionResult(
@@ -188,13 +185,17 @@ public final class DocumentRenderer {
             xadContext["layoutProgram"] = layoutProgramContext(program)
         }
         if let templateDocument {
-            xadContext["template"] = [
+            var templateContext: [String: Any] = [
                 "path": templateDocument.url.path,
                 "attributes": templateDocument.attributes,
                 "typedAttributes": templateDocument.typedAttributes.mapValues { $0.toJSONCompatible() },
                 "css": templateDocument.assets.css,
                 "js": templateDocument.assets.js
             ]
+            if let pageCSS = pageCSS(from: templateDocument) {
+                templateContext["pageCSS"] = pageCSS
+            }
+            xadContext["template"] = templateContext
         }
 
         var context: [String: Any] = [
@@ -669,10 +670,7 @@ public final class DocumentRenderer {
         return rendered
     }
 
-    private func extractSlotsAndCollections(
-        from blocks: [AdocBlock],
-        attributes: [String: String?]
-    ) -> SlotExtractionResult {
+    private func extractSlotsAndCollections(from document: AdocDocument) -> SlotExtractionResult {
         var slots: [String: [SlotItem]] = [:]
         var collections: [String: [SlotItem]] = [:]
         var warnings: [AdocWarning] = []
@@ -680,7 +678,7 @@ public final class DocumentRenderer {
         var index = 0
 
         func attributeValue(_ name: String) -> String? {
-            guard let value = attributes[name] else { return nil }
+            guard let value = document.attributes[name] else { return nil }
             return value ?? ""
         }
 
@@ -731,6 +729,26 @@ public final class DocumentRenderer {
             collections[name, default: []].append(SlotItem(block: block, order: order, index: index))
         }
 
+        func isAbstractBlock(_ meta: AdocBlockMeta) -> Bool {
+            if let style = meta.attributes["style"], style.lowercased() == "abstract" {
+                return true
+            }
+            return meta.roles.contains { $0.lowercased() == "abstract" }
+        }
+
+        func isBibliographyBlock(_ meta: AdocBlockMeta) -> Bool {
+            if let style = meta.attributes["style"], style.lowercased() == "bibliography" {
+                return true
+            }
+            return meta.roles.contains { $0.lowercased() == "bibliography" }
+        }
+
+        func inferredSlotName(for meta: AdocBlockMeta) -> String? {
+            if isAbstractBlock(meta) { return "abstract" }
+            if isBibliographyBlock(meta) { return "bibliography" }
+            return nil
+        }
+
         func extractBlocks(_ blocks: [AdocBlock]) -> [AdocBlock] {
             var out: [AdocBlock] = []
             for block in blocks {
@@ -745,7 +763,8 @@ public final class DocumentRenderer {
             let meta = blockMeta(block)
             let slotName = normalizedName(meta.attributes["slot"])
             let collectionName = normalizedName(meta.attributes["collect"])
-            let orderContext = slotName ?? collectionName ?? "main"
+            let inferredSlot = slotName == nil && collectionName == nil ? inferredSlotName(for: meta) : nil
+            let orderContext = slotName ?? collectionName ?? inferredSlot ?? "main"
             let order = parseOrder(meta.attributes["order"], context: orderContext, span: meta.span)
             index += 1
             let currentIndex = index
@@ -754,7 +773,7 @@ public final class DocumentRenderer {
                 addCollection(collectionName, block: block, order: order, index: currentIndex)
             }
 
-            let effectiveSlot = slotName ?? "main"
+            let effectiveSlot = slotName ?? inferredSlot ?? "main"
             if effectiveSlot != "main" {
                 addSlot(effectiveSlot, block: block, order: order, index: currentIndex)
             }
@@ -764,7 +783,7 @@ public final class DocumentRenderer {
                 return nil
             }
 
-            if slotName != nil || collectionName != nil {
+            if slotName != nil || collectionName != nil || inferredSlot != nil {
                 return block
             }
 
@@ -809,7 +828,40 @@ public final class DocumentRenderer {
             }
         }
 
-        let mainBlocks = extractBlocks(blocks)
+        func makeParagraph(_ text: String, roles: [String]) -> AdocParagraph {
+            var meta = AdocBlockMeta()
+            meta.roles = roles
+            return AdocParagraph(text: AdocText(plain: text), meta: meta)
+        }
+
+        func addHeaderSlotsIfMissing() {
+            if (slots["title"]?.isEmpty ?? true),
+               let titleText = document.header?.title?.plain ?? attributeValue("doctitle"),
+               !titleText.isEmpty {
+                index += 1
+                let titlePara = makeParagraph(titleText, roles: ["doc-title"])
+                addSlot("title", block: .paragraph(titlePara), order: 0, index: index)
+            }
+
+            if (slots["authors"]?.isEmpty ?? true) {
+                if let headerAuthors = document.header?.authors, !headerAuthors.isEmpty {
+                    for author in headerAuthors {
+                        let text = formatAuthor(author)
+                        if text.isEmpty { continue }
+                        index += 1
+                        let authorPara = makeParagraph(text, roles: ["author"])
+                        addSlot("authors", block: .paragraph(authorPara), order: 0, index: index)
+                    }
+                } else if let raw = attributeValue("author"), !raw.isEmpty {
+                    index += 1
+                    let authorPara = makeParagraph(raw, roles: ["author"])
+                    addSlot("authors", block: .paragraph(authorPara), order: 0, index: index)
+                }
+            }
+        }
+
+        let mainBlocks = extractBlocks(document.blocks)
+        addHeaderSlotsIfMissing()
         return SlotExtractionResult(
             mainBlocks: mainBlocks,
             slots: slots,
@@ -854,6 +906,67 @@ public final class DocumentRenderer {
         return false
     }
 
+    private func pageCSS(from template: XADTemplateDocument) -> String? {
+        guard let mastersValue = template.typedAttributes["page.masters"] else { return nil }
+        guard case .dictionary(let masters) = mastersValue else { return nil }
+        guard case .dictionary(let defaultMaster) = masters["default"] else { return nil }
+
+        let size: String?
+        if case .string(let rawSize)? = defaultMaster["size"] {
+            size = rawSize
+        } else {
+            size = nil
+        }
+
+        var marginParts: [String] = []
+        if case .dictionary(let margins)? = defaultMaster["margins"] {
+            let top = stringValue(margins["top"])
+            let right = stringValue(margins["right"]) ?? stringValue(margins["outer"])
+            let bottom = stringValue(margins["bottom"])
+            let left = stringValue(margins["left"]) ?? stringValue(margins["inner"])
+            if let top, let right, let bottom, let left {
+                marginParts = [top, right, bottom, left]
+            }
+        }
+
+        guard size != nil || !marginParts.isEmpty else { return nil }
+        var lines: [String] = ["@page {"]
+        if let size {
+            lines.append("  size: \(size);")
+        }
+        if !marginParts.isEmpty {
+            lines.append("  margin: \(marginParts.joined(separator: " "));")
+        }
+        lines.append("}")
+        return lines.joined(separator: "\n")
+    }
+
+    private func formatAuthor(_ author: AdocAuthor) -> String {
+        if let fullname = author.fullname, !fullname.isEmpty {
+            return appendAddress(fullname, address: author.address)
+        }
+        let parts = [author.firstname, author.middlename, author.lastname].compactMap { $0?.trimmingCharacters(in: .whitespacesAndNewlines) }.filter { !$0.isEmpty }
+        if !parts.isEmpty {
+            return appendAddress(parts.joined(separator: " "), address: author.address)
+        }
+        if let initials = author.initials, !initials.isEmpty {
+            return appendAddress(initials, address: author.address)
+        }
+        return ""
+    }
+
+    private func appendAddress(_ name: String, address: String?) -> String {
+        guard let address, !address.isEmpty else { return name }
+        return "\(name) <\(address)>"
+    }
+
+    private func stringValue(_ value: XADAttributeValue?) -> String? {
+        if case .string(let raw)? = value {
+            return raw
+        }
+        return nil
+    }
+
     private func isTruthy(_ value: XADAttributeValue) -> Bool {
         switch value {
         case .bool(let b):
diff --git a/Templates/html5/document.stencil b/Templates/html5/document.stencil
index fec01ee..e941ded 100644
--- a/Templates/html5/document.stencil
+++ b/Templates/html5/document.stencil
@@ -12,6 +12,10 @@
       {% endfor %}
     {% endif %}
     <style>
+      {% if xad and xad.template and xad.template.pageCSS %}
+      {{ xad.template.pageCSS }}
+      {% endif %}
+
       :root {
         --surface: #ffffff;
         --surface-muted: #f6f7fb;
diff --git a/Templates/xad/default/template.adoc b/Templates/xad/default/template.adoc
index 23b3af4..8618b7f 100644
--- a/Templates/xad/default/template.adoc
+++ b/Templates/xad/default/template.adoc
@@ -1,4 +1,5 @@
 = Default Template
+:page.masters: {"default": {"size": "A4", "margins": {"top": "18mm", "right": "18mm", "bottom": "20mm", "left": "18mm"}, "duplex": false}}
 
 [layout]
 ----
diff --git a/Templates/xad/double-column-explicit/template.adoc b/Templates/xad/double-column-explicit/template.adoc
index 100c97b..653404d 100644
--- a/Templates/xad/double-column-explicit/template.adoc
+++ b/Templates/xad/double-column-explicit/template.adoc
@@ -1,4 +1,5 @@
 = Double Column Explicit Template
+:page.masters: {"default": {"size": "A4", "margins": {"top": "18mm", "right": "18mm", "bottom": "20mm", "left": "18mm"}, "duplex": false}}
 
 [layout]
 ----
diff --git a/Templates/xad/double-column-flow/template.adoc b/Templates/xad/double-column-flow/template.adoc
index 9852ac9..75ef252 100644
--- a/Templates/xad/double-column-flow/template.adoc
+++ b/Templates/xad/double-column-flow/template.adoc
@@ -1,4 +1,5 @@
 = Double Column Flow Template
+:page.masters: {"default": {"size": "A4", "margins": {"top": "18mm", "right": "18mm", "bottom": "20mm", "left": "18mm"}, "duplex": false}}
 
 [layout]
 ----
diff --git a/Templates/xad/trivial/template.adoc b/Templates/xad/trivial/template.adoc
index 83aac31..afb95cb 100644
--- a/Templates/xad/trivial/template.adoc
+++ b/Templates/xad/trivial/template.adoc
@@ -1,4 +1,5 @@
 = Trivial Template
+:page.masters: {"default": {"size": "A4", "margins": {"top": "18mm", "right": "18mm", "bottom": "20mm", "left": "18mm"}, "duplex": false}}
 
 [layout]
 ----
diff --git a/examples/xad/double-column-explicit/content.adoc b/examples/xad/double-column-explicit/content.adoc
index c1b98d7..86abb05 100644
--- a/examples/xad/double-column-explicit/content.adoc
+++ b/examples/xad/double-column-explicit/content.adoc
@@ -2,13 +2,7 @@
 Author Example <author@example.com>
 :revdate: 2026-03-02
 
-[slot=title]
-Double Column Layout Example
-
-[slot=authors]
-Author Example
-
-[slot=abstract]
+[abstract]
 This abstract sits above a two-column layout driven by left/right slots.
 
 == Left Column
@@ -19,6 +13,12 @@ Left column paragraph one.
 [slot=left, order=20]
 Left column paragraph two.
 
+[slot=left, order=30]
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+[slot=left, order=40]
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
 == Right Column
 
 [slot=right, order=10]
@@ -26,3 +26,9 @@ Right column paragraph one.
 
 [slot=right, order=20]
 Right column paragraph two.
+
+[slot=right, order=30]
+Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
+
+[slot=right, order=40]
+Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
diff --git a/examples/xad/double-column-flow/content.adoc b/examples/xad/double-column-flow/content.adoc
index 04c6bfb..f648326 100644
--- a/examples/xad/double-column-flow/content.adoc
+++ b/examples/xad/double-column-flow/content.adoc
@@ -2,13 +2,7 @@
 Author Example <author@example.com>
 :revdate: 2026-03-02
 
-[slot=title]
-Double Column Flow Example
-
-[slot=authors]
-Author Example
-
-[slot=abstract]
+[abstract]
 This abstract sits above a two-column flow where content flows across columns.
 
 == Introduction
@@ -27,7 +21,26 @@ consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolor
 This section continues in the same slot so it participates in the column flow. Use it to
 verify that headings and paragraphs stay within the two-column area.
 
+[slot=main]
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
+laboris nisi ut aliquip ex ea commodo consequat.
+
+[slot=main]
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
+pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt
+mollit anim id est laborum.
+
+[slot=main]
+Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque
+laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto
+beatae vitae dicta sunt explicabo.
+
 [slot=main]
 - First item in the flowing column list.
 - Second item in the flowing column list.
 - Third item in the flowing column list.
+
+[slot=main]
+Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia
+consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
diff --git a/examples/xad/trivial/content.adoc b/examples/xad/trivial/content.adoc
index f76247e..c08c4dc 100644
--- a/examples/xad/trivial/content.adoc
+++ b/examples/xad/trivial/content.adoc
@@ -2,13 +2,7 @@
 Author Example <author@example.com>
 :revdate: 2026-03-02
 
-[slot=title]
-Trivial Layout Example
-
-[slot=authors]
-Author Example
-
-[slot=abstract]
+[abstract]
 This is a short abstract describing the trivial single-column layout.
 
 == Introduction