(defcomp
  ()
  (~docs/page
    :title "Spec Architecture"
    (div
      (~tw :tokens "space-y-8")
      (div
        (~tw :tokens "space-y-4")
        (p
          (~tw :tokens "text-lg text-stone-600")
          "SX is defined in SX. The canonical specification is a set of s-expression files that are both documentation and executable definition. Bootstrap compilers read these files to generate native implementations in JavaScript, Python, Rust, or any other target.")
        (p
          (~tw :tokens "text-stone-600")
          "The spec is organized into six sections: "
          (strong "Core")
          " (the language itself), "
          (strong "Adapters")
          " (rendering backends), "
          (strong "Browser")
          " (client-side runtime), "
          (strong "Reactive")
          " (signal system), "
          (strong "Host Interface")
          " (platform contract), and "
          (strong "Extensions")
          " (optional add-ons)."))
      (div
        (~tw :tokens "space-y-3")
        (h2 (~tw :tokens "text-2xl font-semibold text-stone-800") "Core")
        (p
          (~tw :tokens "text-stone-600")
          "The core is platform-independent. It defines how SX source is parsed, how expressions are evaluated, what primitives exist, and what shared rendering definitions all adapters use. These four files are the language.")
        (div
          (~tw :tokens "overflow-x-auto rounded border border-stone-200")
          (table
            (~tw :tokens "w-full text-left text-sm")
            (thead
              (tr
                (~tw :tokens "border-b border-stone-200 bg-stone-100")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "File")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "Role")))
            (tbody
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.parser))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.parser))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "parser.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Tokenization and parsing of SX source text into AST"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.evaluator))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.evaluator))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "eval.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Tree-walking evaluation of SX expressions"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.primitives))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.primitives))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "primitives.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "All built-in pure functions and their signatures"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.special-forms))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.special-forms))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "special-forms.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "All special forms — syntactic constructs with custom evaluation rules"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.renderer))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.renderer))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "render.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Shared rendering registries and utilities used by all adapters"))))))
      (div
        (~tw :tokens "space-y-3")
        (h2 (~tw :tokens "text-2xl font-semibold text-stone-800") "Adapters")
        (p
          (~tw :tokens "text-stone-600")
          "Adapters are selectable rendering backends. Each one takes the same evaluated expression tree and produces output for a specific environment. You only need the adapters relevant to your target.")
        (div
          (~tw :tokens "overflow-x-auto rounded border border-stone-200")
          (table
            (~tw :tokens "w-full text-left text-sm")
            (thead
              (tr
                (~tw :tokens "border-b border-stone-200 bg-stone-100")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "File")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "Output")
                (th
                  (~tw :tokens "px-3 py-2 font-medium text-stone-600")
                  "Environment")))
            (tbody
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.adapter-dom))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.adapter-dom))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "adapter-dom.sx"))
                (td (~tw :tokens "px-3 py-2 text-stone-700") "Live DOM nodes")
                (td (~tw :tokens "px-3 py-2 text-stone-500") "Browser"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.adapter-html))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.adapter-html))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "adapter-html.sx"))
                (td (~tw :tokens "px-3 py-2 text-stone-700") "HTML strings")
                (td (~tw :tokens "px-3 py-2 text-stone-500") "Server"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.adapter-sx))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.adapter-sx))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "adapter-sx.sx"))
                (td (~tw :tokens "px-3 py-2 text-stone-700") "SX wire format")
                (td (~tw :tokens "px-3 py-2 text-stone-500") "Server to client"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.adapter-async))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.adapter-async))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "adapter-async.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "HTML/SX with awaited I/O")
                (td (~tw :tokens "px-3 py-2 text-stone-500") "Server (async)"))))))
      (div
        (~tw :tokens "space-y-3")
        (h2 (~tw :tokens "text-2xl font-semibold text-stone-800") "Browser Runtime")
        (p
          (~tw :tokens "text-stone-600")
          "The browser runtime handles the full client-side lifecycle: parsing triggers, making HTTP requests, swapping content, managing history, and booting the page. Split into pure logic (engine), browser wiring (orchestration), startup (boot), and URL matching (router).")
        (div
          (~tw :tokens "overflow-x-auto rounded border border-stone-200")
          (table
            (~tw :tokens "w-full text-left text-sm")
            (thead
              (tr
                (~tw :tokens "border-b border-stone-200 bg-stone-100")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "File")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "Role")))
            (tbody
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.engine))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.engine))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "engine.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Pure logic — trigger parsing, swap algorithms, morph, history, SSE, indicators"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.orchestration))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.orchestration))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "orchestration.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Browser wiring — binds engine to DOM events, fetch, request lifecycle"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.boot))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.boot))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "boot.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Browser startup — mount, hydrate, script processing, head hoisting"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.router))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.router))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "router.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Client-side route matching — Flask-style patterns, param extraction"))))))
      (div
        (~tw :tokens "space-y-3")
        (h2 (~tw :tokens "text-2xl font-semibold text-stone-800") "Reactive")
        (p
          (~tw :tokens "text-stone-600")
          "Fine-grained reactive primitives for client-side islands. Signals notify subscribers on change, computed values derive lazily, effects run side-effects with cleanup, and batch coalesces updates.")
        (div
          (~tw :tokens "overflow-x-auto rounded border border-stone-200")
          (table
            (~tw :tokens "w-full text-left text-sm")
            (thead
              (tr
                (~tw :tokens "border-b border-stone-200 bg-stone-100")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "File")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "Role")))
            (tbody
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.signals))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.signals))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "signals.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Signal runtime — signal, deref, reset!, swap!, computed, effect, batch, island scope"))))))
      (div
        (~tw :tokens "space-y-3")
        (h2 (~tw :tokens "text-2xl font-semibold text-stone-800") "Host Interface")
        (p
          (~tw :tokens "text-stone-600")
          "The contract between SX and its host environment. Boundary declares what the host must provide. Forms define server-side application constructs. Page helpers offer pure data transformations for rendering.")
        (div
          (~tw :tokens "overflow-x-auto rounded border border-stone-200")
          (table
            (~tw :tokens "w-full text-left text-sm")
            (thead
              (tr
                (~tw :tokens "border-b border-stone-200 bg-stone-100")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "File")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "Role")))
            (tbody
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.boundary))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.boundary))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "boundary.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Language boundary — I/O primitives, page helpers, tier declarations"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.forms))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.forms))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "forms.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Definition forms — defhandler, defquery, defaction, defpage"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.page-helpers))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.page-helpers))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "page-helpers.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Pure data-transformation helpers for page rendering"))))))
      (div
        (~tw :tokens "space-y-3")
        (h2 (~tw :tokens "text-2xl font-semibold text-stone-800") "Dependency graph")
        (div
          (~tw :tokens "not-prose bg-stone-100 rounded-lg p-5 mx-auto max-w-3xl")
          (pre
            (~tw :tokens "text-sm leading-relaxed whitespace-pre-wrap break-words font-mono text-stone-700")
            ";; Core\nparser.sx           (standalone — no dependencies)\nprimitives.sx       (standalone — declarative registry)\nspecial-forms.sx    (standalone — declarative registry)\neval.sx             depends on: parser, primitives, special-forms\nrender.sx           (standalone — shared registries)\n\n;; Adapters\nadapter-dom.sx      depends on: render, eval\nadapter-html.sx     depends on: render, eval\nadapter-sx.sx       depends on: render, eval\nadapter-async.sx    depends on: adapter-html, adapter-sx, eval\n\n;; Browser Runtime\nengine.sx           depends on: eval, adapter-dom\norchestration.sx    depends on: engine, adapter-dom\nboot.sx             depends on: orchestration, adapter-dom, render\nrouter.sx           (standalone — pure string/list ops)\n\n;; Reactive\nsignals.sx          depends on: eval\n\n;; Host Interface\nboundary.sx         (standalone — declarative contract)\nforms.sx            depends on: eval\npage-helpers.sx     (standalone — declarative registry)\n\n;; Extensions (optional)\ncontinuations.sx    depends on: eval\ncallcc.sx           depends on: eval\ntypes.sx            depends on: eval, primitives\ndeps.sx             depends on: eval")))
      (div
        (~tw :tokens "space-y-3")
        (h2 (~tw :tokens "text-2xl font-semibold text-stone-800") "Extensions")
        (p
          (~tw :tokens "text-stone-600")
          "Optional bolt-on specifications that extend the core language. Bootstrappers include them only when the target requests them. Code that doesn't use extensions pays zero cost.")
        (div
          (~tw :tokens "overflow-x-auto rounded border border-stone-200")
          (table
            (~tw :tokens "w-full text-left text-sm")
            (thead
              (tr
                (~tw :tokens "border-b border-stone-200 bg-stone-100")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "File")
                (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "Role")))
            (tbody
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.continuations))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.continuations))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "continuations.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Delimited continuations — shift/reset"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.callcc))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.callcc))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "callcc.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Full first-class continuations — call/cc"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.types))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.types))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "types.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Gradual type system — registration-time checking, zero runtime cost"))
              (tr
                (~tw :tokens "border-b border-stone-100")
                (td
                  (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700")
                  (a
                    :href "/sx/(language.(spec.deps))"
                    (~tw :tokens "hover:underline")
                    :sx-get "/sx/(language.(spec.deps))"
                    :sx-target "#sx-content"
                    :sx-select "#sx-content"
                    :sx-swap "outerHTML"
                    :sx-push-url "true"
                    "deps.sx"))
                (td
                  (~tw :tokens "px-3 py-2 text-stone-700")
                  "Component dependency analysis — bundling, IO detection, CSS scoping"))))))
      (div
        (~tw :tokens "space-y-3")
        (h2 (~tw :tokens "text-2xl font-semibold text-stone-800") "Self-hosting")
        (p
          (~tw :tokens "text-stone-600")
          "Every spec file is written in the same restricted subset of SX that the evaluator itself defines. A bootstrap compiler for a new target only needs to understand this subset — roughly 20 special forms and 80 primitives — to generate a fully native implementation. The spec files are the single source of truth; implementations are derived artifacts.")
        (p
          (~tw :tokens "text-stone-600")
          "This is not a theoretical exercise. The JavaScript implementation ("
          (code (~tw :tokens "text-violet-700 text-sm") "sx.js")
          ") and the Python implementation ("
          (code (~tw :tokens "text-violet-700 text-sm") "shared/sx/")
          ") are both generated from these spec files via "
          (code (~tw :tokens "text-violet-700 text-sm") "bootstrap_js.py")
          " and its Python counterpart.")))))
