ARCHITECTURE.md

Architecture

OrgSwift parses org into an element tree and renders that tree. Parsing happens once; each output format is a walk over the result.

Sources/OrgSwift/
  AST/
    OrgDocument.swift                 the element tree
    OrgParser.swift                   source → OrgDocument      (blocks)
    OrgInlineParser.swift             text   → [OrgObject]      (inlines)
    OrgHTMLTreeRenderer.swift         OrgDocument → HTML
    OrgAttributedStringRenderer.swift [OrgObject] → AttributedString
  OrgRenderer.swift                   the public entry point, plus OrgRenderOptions
  Escaping.swift, Links.swift, …      shared helpers: escaping, URL sanitising and
                                      repository-relative resolution, line predicates
  Skeleton.swift                      the HTML → semantic-skeleton reduction used by tests

OrgRenderer.renderToHTML is a thin façade over OrgParser.parse + OrgHTMLTreeRenderer. It, OrgRenderOptions, and CodeHighlighter are the whole public API most callers need.

Why a tree

The renderer this replaced went from source straight to an HTML string in a single pass, doing inline work by regex-substituting markup into escaped text and protecting the results with placeholder tokens. That worked, but it baked HTML into the parse: any second output format would have meant re-deriving the parse rather than reusing it.

With a tree, OrgAttributedStringRenderer is roughly 140 lines and shares the parse entirely. It is Foundation-only — no SwiftUI — so it works server-side, in a CLI, anywhere; a SwiftUI layer would sit on top of it for the inline runs inside each block.

The types mirror orgo's model.rs — OrgElement/OrgObject against orgo's Element/Object, OrgTableRow.{cells,rule} against TableRow::{Cells,Rule}, the same ListKind/Checkbox vocabulary. That makes future tree-level conformance possible: today the corpus compares rendered HTML reduced to a skeleton, which is a string-level proxy for "do these two agree on structure", and matching trees would let that question be asked directly.

Resolution is simpler on a tree, too. Link targets stay typed — .external, .file, .id — so repository-relative resolution applies to the .file case in the renderer instead of a resolver closure threaded through the parse. An unsafe or unresolvable target degrades to its text rather than becoming a bad anchor.

Conformance

Measured against the org-conformance corpus, whose goldens come from orgo (itself diffed against Emacs ox-html), reduced by the shared skeleton algorithm:

11 / 12 — every case except outofscope, which is scope: out in the corpus (deliberately unsupported constructs, where orgo itself may differ).

ConformanceTests gates this: a regression fails, and outofscope starting to match fails too, forcing the record in its expectations map to be updated. GAPS.md carries the detail.

Notes from the migration

The tree renderer replaced the single-pass one only after it was shown to be equivalent: every corpus case, each option combination, identical URL resolution, unsafe-scheme rejection, and a 28-construct battery drawn from the old renderer's own test inputs. That battery earned its keep — it caught three behaviours the corpus never reaches (#+CAPTION:/#+NAME: wrapping a non-image block in <figure class="org-block">, the nested [[dest][[img]]] badge form, and bare email autolinks), each of which would otherwise have regressed a consumer.

One behaviour changed on purpose. A range whose halves are inactive timestamps, [a]--[b], is now joined into one range; the old renderer joined active ranges only and left -- as text. orgo applies the -- rule to both bracket kinds, requiring only that the halves agree on activeness, so the new behaviour is the more correct one. It is asserted directly in joinsInactiveTimestampRanges.

Next

A SwiftUI renderer belongs in a separate product depending on this one, so the parser and HTML renderer stay Foundation-only and callers who want HTML never import SwiftUI. Tables are the interesting part: Grid/GridRow with .gridColumnAlignment(), wrapped in a horizontal ScrollView for phone-width overflow — the approach MarkdownUI uses. OrgTable already carries the rows, the rule position, and the per-column alignments that needs.