;; SX URLs — Comprehensive documentation for s-expression URL addressing.
;; Lives under the Applications section: /(applications.(sx-urls))

;; ---------------------------------------------------------------------------
;; Main documentation page
;; ---------------------------------------------------------------------------

(defcomp ()
  (~docs/page :title "SX URLs"
    (p (~tw :tokens "text-stone-500 text-sm italic mb-8")
      "S-expression URLs — where the address of a thing and the thing itself are the same kind of thing.")

    ;; -----------------------------------------------------------------
    (~docs/section :title "What Is an SX URL?" :id "what"
      (p "An SX URL is a URL whose path is an s-expression. Instead of "
         "a flat sequence of slash-separated path segments, the URL encodes "
         "a nested function call that the server evaluates to produce a page.")
      (p "Every page on this site is addressed by an SX URL. You are currently reading:")
      (~docs/code :src (highlight
        "/sx/(applications.(sx-urls))"
        "lisp"))
      (p "This is a function call: " (code "applications") " is called with the result of "
         (code "(sx-urls)") ". The server evaluates it, wraps the content in a layout, "
         "and returns the page. "
         "The URL is simultaneously a query, a render instruction, and an address."))

    ;; -----------------------------------------------------------------
    (~docs/section :title "Dots as Spaces" :id "dots"
      (p "Spaces in URLs are ugly — they become " (code "%20") " in the address bar, "
         "break when copy-pasted into terminals, and confuse proxies. "
         "Dots are unreserved in "
         (a :href "https://www.rfc-editor.org/rfc/rfc3986" (~tw :tokens "text-violet-600 hover:underline") "RFC 3986")
         ", never percent-encoded, and read naturally.")
      (p "The rule: " (strong "dot = space, nothing more") ". "
         "Before parsing, the server replaces every dot with a space. "
         "Parens carry all structural meaning.")
      (~docs/code :src (highlight
        ";; What you type in the browser:\n/(language.(doc.introduction))\n\n;; After dot→space transform:\n(language (doc introduction))\n\n;; This is standard SX. Parens are nesting. Atoms are arguments.\n;; 'introduction' is a string slug, 'doc' is a function, 'language' is a function."
        "lisp"))

      (p "More examples:")
      (div (~tw :tokens "space-y-2")
        (p (a :href "/sx/(geography.(hypermedia.(example.progress-bar)))"
              (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
              "/(geography.(hypermedia.(example.progress-bar)))") " — progress bar example")
        (p (a :href "/sx/(language.(spec.signals))"
              (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
              "/(language.(spec.signals))") " — signals spec")
        (p (a :href "/sx/(etc.(essay.sx-sucks))"
              (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
              "/(etc.(essay.sx-sucks))") " — the honest critique"))

      (p "The dot-to-space transform is the " (em "only") " URL-specific syntax. "
         "Everything else is standard s-expression parsing."))

    ;; -----------------------------------------------------------------
    (~docs/section :title "Nesting Is Scoping" :id "nesting"
      (p "REST URLs have an inherent ambiguity: "
         "does a filter apply to the last segment, or the whole path? "
         "S-expression nesting makes scope explicit.")
      (~docs/code :src (highlight
        ";; REST — ambiguous:\n/users/123/posts?filter=published\n;; Does 'filter' apply to posts? To the user? To the whole query?\n;; The answer depends on API documentation.\n\n;; SX URLs — explicit scoping:\n/(users.(posts.123.(filter.published)))   ;; filter scoped to posts\n/(users.posts.123.(filter.published))     ;; filter scoped to the whole expression\n\n;; These are structurally different. The paren boundaries ARE scope boundaries.\n;; No documentation needed — the syntax tells you."
        "lisp"))

      (p "This extends to every level of nesting on this site:")
      (~docs/code :src (highlight
        ";; These all have different scoping:\n/(language.(spec.signals))              ;; 'signals' scoped to spec\n/(language.(spec.(explore.signals)))     ;; 'signals' scoped to explore\n/(language.(spec.(explore.signals.:section.\"batch\")))  ;; keyword scoped to explore call"
        "lisp"))
      (p "What took REST thirty years of convention documents to approximate, "
         "SX URLs express in the syntax itself."))

    ;; -----------------------------------------------------------------
    (~docs/section :title "The URL Hierarchy" :id "hierarchy"
      (p "Every URL on this site follows a hierarchical structure. "
         "Sections are functions that receive the result of their inner expressions.")

      (~docs/subsection :title "Section functions"
        (p "Top-level sections are structural. "
           "Called with no arguments, they return their index page. "
           "Called with content, they pass it through:")
        (div (~tw :tokens "space-y-1 ml-4")
          (p (a :href "/sx/(language)" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm") "/(language)"))
          (p (a :href "/sx/(geography)" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm") "/(geography)"))
          (p (a :href "/sx/(applications)" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm") "/(applications)"))
          (p (a :href "/sx/(etc)" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm") "/(etc)"))))

      (~docs/subsection :title "Sub-sections"
        (p "Sub-sections nest inside sections:")
        (div (~tw :tokens "space-y-1 ml-4")
          (p (a :href "/sx/(geography.(hypermedia))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(hypermedia))"))
          (p (a :href "/sx/(geography.(reactive))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(reactive))"))
          (p (a :href "/sx/(geography.(isomorphism))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(isomorphism))"))
          (p (a :href "/sx/(language.(doc))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(language.(doc))"))
          (p (a :href "/sx/(language.(spec))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(language.(spec))"))
          (p (a :href "/sx/(applications.(cssx))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(applications.(cssx))"))))

      (~docs/subsection :title "Leaf pages"
        (p "Leaf pages are the innermost function calls. "
           "The slug becomes a string argument to the page function:")
        (~docs/code :src (highlight
          ";; doc(\"introduction\") — the slug auto-quotes to a string\n/(language.(doc.introduction))\n\n;; spec(\"core\") — same pattern, different function\n/(language.(spec.core))\n\n;; explore(\"signals\") — nested deeper\n/(language.(spec.(explore.signals)))\n\n;; example(\"progress-bar\") — three levels of nesting\n/(geography.(hypermedia.(example.progress-bar)))"
          "lisp"))

        (p "Every page on this site:")
        (div (~tw :tokens "grid grid-cols-1 md:grid-cols-2 gap-x-6 gap-y-1 mt-2")
          ;; Language
          (div
            (p (~tw :tokens "font-semibold text-stone-700 text-sm mt-2 mb-1") "Language — Docs")
            (p (a :href "/sx/(language.(doc.introduction))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(doc.introduction))"))
            (p (a :href "/sx/(language.(doc.getting-started))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(doc.getting-started))"))
            (p (a :href "/sx/(language.(doc.components))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(doc.components))"))
            (p (a :href "/sx/(language.(doc.evaluator))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(doc.evaluator))"))
            (p (a :href "/sx/(language.(doc.primitives))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(doc.primitives))"))
            (p (a :href "/sx/(language.(doc.special-forms))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(doc.special-forms))"))
            (p (a :href "/sx/(language.(doc.server-rendering))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(doc.server-rendering))"))
            (p (~tw :tokens "font-semibold text-stone-700 text-sm mt-2 mb-1") "Language — Specs")
            (p (a :href "/sx/(language.(spec.core))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(spec.core))"))
            (p (a :href "/sx/(language.(spec.parser))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(spec.parser))"))
            (p (a :href "/sx/(language.(spec.evaluator))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(spec.evaluator))"))
            (p (a :href "/sx/(language.(spec.signals))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(spec.signals))"))
            (p (a :href "/sx/(language.(spec.(explore.signals)))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(spec.(explore.signals)))"))
            (p (~tw :tokens "font-semibold text-stone-700 text-sm mt-2 mb-1") "Language — Other")
            (p (a :href "/sx/(language.(bootstrapper.python))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(bootstrapper.python))"))
            (p (a :href "/sx/(language.(bootstrapper.self-hosting))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(bootstrapper.self-hosting))"))
            (p (a :href "/sx/(language.(test.eval))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(test.eval))"))
            (p (a :href "/sx/(language.(test.router))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(language.(test.router))")))
          ;; Geography + Applications + Etc
          (div
            (p (~tw :tokens "font-semibold text-stone-700 text-sm mt-2 mb-1") "Geography")
            (p (a :href "/sx/(geography.(reactive.(examples.counter)))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(geography.(reactive.(examples.counter)))"))
            (p (a :href "/sx/(geography.(hypermedia.(reference.attributes)))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(geography.(hypermedia.(reference.attributes)))"))
            (p (a :href "/sx/(geography.(hypermedia.(example.click-to-load)))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(geography.(hypermedia.(example.click-to-load)))"))
            (p (a :href "/sx/(geography.(hypermedia.(example.infinite-scroll)))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(geography.(hypermedia.(example.infinite-scroll)))"))
            (p (a :href "/sx/(geography.(isomorphism.bundle-analyzer))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(geography.(isomorphism.bundle-analyzer))"))
            (p (~tw :tokens "font-semibold text-stone-700 text-sm mt-2 mb-1") "Applications")
            (p (a :href "/sx/(applications.(sx-urls))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(applications.(sx-urls))") " — this page")
            (p (a :href "/sx/(applications.(cssx.patterns))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(applications.(cssx.patterns))"))
            (p (a :href "/sx/(applications.(protocol.wire-format))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(applications.(protocol.wire-format))"))
            (p (~tw :tokens "font-semibold text-stone-700 text-sm mt-2 mb-1") "Etc")
            (p (a :href "/sx/(etc.(essay.sx-sucks))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(etc.(essay.sx-sucks))"))
            (p (a :href "/sx/(etc.(essay.self-defining-medium))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(etc.(essay.self-defining-medium))"))
            (p (a :href "/sx/(etc.(philosophy.sx-manifesto))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(etc.(philosophy.sx-manifesto))"))
            (p (a :href "/sx/(etc.(plan.spec-explorer))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(etc.(plan.spec-explorer))"))
            (p (a :href "/sx/(etc.(plan.sx-urls))" (~tw :tokens "font-mono text-violet-600 hover:underline text-xs") "/(etc.(plan.sx-urls))"))))))

    ;; -----------------------------------------------------------------
    (~docs/section :title "Direct Component URLs" :id "direct"
      (p "Every " (code "defcomp") " in the component environment is directly "
         "addressable by its " (code "~name") " — no page function, no routing wiring, no case statement.")
      (~docs/code :src (highlight
        ";; Any component is instantly a URL:\n/(~essays/sx-sucks/essay-sx-sucks)                ;; the essay\n/(~plans/sx-urls/plan-sx-urls-content)            ;; the SX URLs plan\n/(~docs-content/docs-evaluator-content)           ;; evaluator docs\n/(~analyzer/bundle-analyzer-content)              ;; bundle analyzer tool"
        "lisp"))
      (p "Try it:")
      (div (~tw :tokens "space-y-1 ml-4")
        (p (a :href "/sx/(~essays/sx-sucks/essay-sx-sucks)" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
              "/(~essays/sx-sucks/essay-sx-sucks)"))
        (p (a :href "/sx/(~plans/sx-urls/plan-sx-urls-content)" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
              "/(~plans/sx-urls/plan-sx-urls-content)"))
        (p (a :href "/sx/(~docs-content/docs-evaluator-content)" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
              "/(~docs-content/docs-evaluator-content)")))
      (p "New components are URL-accessible the moment they are defined. "
         "No registration, no routing table update, no deploy."))

    ;; -----------------------------------------------------------------
    (~docs/section :title "Routing Is Functional Application" :id "functional"
      (p "A URL is a function call. The server evaluates it. "
         "There is no routing table, no pattern matching, no controller dispatch. "
         "The URL " (em "is") " the code.")

      (~docs/subsection :title "Section functions pass through"
        (p (code "language") ", " (code "geography") ", " (code "applications") ", " (code "etc")
           " are identity on their argument. They exist to provide structure:")
        (~docs/code :src (highlight
          ";; Section function definition:\n(define language\n  (fn (content)\n    (if (nil? content) nil content)))\n\n;; /(language.(doc.introduction))\n;; Eval steps:\n;;   1. (doc \"introduction\") → page content AST\n;;   2. (language <content>) → passes content through\n;;   3. Wrap in (~layouts/doc :path \"...\" <content>)"
          "lisp"))
        (p "Section functions with no argument return their index page:")
        (~docs/code :src (highlight
          "(define home\n  (fn (content)\n    (if (nil? content) '(~docs-content/home-content) content)))\n\n;; /(home) → (~docs-content/home-content)\n;; /       → same thing"
          "lisp")))

      (~docs/subsection :title "Page functions dispatch on slug"
        (p "Page functions take a slug string and return a quoted component expression:")
        (~docs/code :src (highlight
          "(define doc\n  (fn (slug)\n    (if (nil? slug)\n      '(~docs-content/docs-introduction-content)\n      (case slug\n        \"introduction\" '(~docs-content/docs-introduction-content)\n        \"getting-started\" '(~docs-content/docs-getting-started-content)\n        \"components\" '(~docs-content/docs-components-content)\n        \"evaluator\" '(~docs-content/docs-evaluator-content)\n        \"primitives\"\n          (let ((data (primitives-data)))\n            `(~docs-content/docs-primitives-content\n               :prims (~docs/primitives-tables :primitives ,data)))\n        :else '(~docs-content/docs-introduction-content)))))"
          "lisp"))
        (p "The " (code "'") " (quote) is critical: page functions return "
           (em "unevaluated ASTs") ". The router evaluates the page function to get the AST, "
           "then passes it through " (code "aser") " (the wire-format renderer) which expands "
           "components and handles HTML tags."))

      (~docs/subsection :title "Data-dependent pages"
        (p "Some pages need server data. The page function calls an IO helper, "
           "then splices data into the component call with quasiquote:")
        (~docs/code :src (highlight
          "(define isomorphism\n  (fn (slug)\n    (case slug\n      \"bundle-analyzer\"\n        (let ((data (bundle-analyzer-data)))    ;; IO: reads component env\n          `(~analyzer/bundle-analyzer-content\n            :pages ,(get data \"pages\")\n            :total-components ,(get data \"total-components\")\n            :pure-count ,(get data \"pure-count\")\n            :io-count ,(get data \"io-count\")))\n      :else '(~plans/isomorphic/plan-isomorphic-content))))"
          "lisp"))
        (p "Visit "
           (a :href "/sx/(geography.(isomorphism.bundle-analyzer))" (~tw :tokens "text-violet-600 hover:underline")
              "/(geography.(isomorphism.bundle-analyzer))") " to see this in action — "
           "the page function calls " (code "bundle-analyzer-data") ", "
           "which analyzes the live component environment and returns statistics.")))

    ;; -----------------------------------------------------------------
    (~docs/section :title "Server-Side: URL → eval → Response" :id "server"
      (p "The Python route handler is generic infrastructure. "
         "All routing semantics live in the SX spec (" (code "router.sx") "). "
         "The handler does four things:")

      (~docs/subsection :title "The handler"
        (~docs/code :src (highlight
          ";; Python handler (sx_router.py) — simplified:\n\nasync def eval_sx_url(raw_path):\n    # 1. Build env: all components + all page functions\n    env = get_component_env() | get_page_helpers(\"sx\")\n\n    # 2. Spec function: parse URL, auto-quote unknowns\n    #    This is bootstrapped from router.sx → sx_ref.py\n    expr = prepare_url_expr(path, env)\n\n    # 3. Evaluate: page functions resolve, data fetched\n    page_ast = await async_eval(expr, env, ctx)\n\n    # 4. Wrap in layout, render to HTML\n    wrapped = [Symbol(\"~layouts/doc\"), Keyword(\"path\"), path, page_ast]\n    content_sx = await _eval_slot(wrapped, env, ctx)\n    return full_page_sx(content_sx)"
          "python"))
        (p "The handler imports " (code "prepare_url_expr") " from the bootstrapped "
           (code "sx_ref.py") " — the same function the JavaScript client uses for "
           "client-side route resolution. One spec, two hosts."))

      (~docs/subsection :title "Auto-quoting: soft eval"
        (p "When the parser reads " (code "(language (doc introduction))")
           ", all three atoms are symbols. But " (code "introduction")
           " isn't a function — it's a slug. The " (code "auto-quote-unknowns") " function "
           "walks the AST and replaces unknown symbols with their string name:")
        (~docs/code :src (highlight
          ";; From router.sx — the auto-quoting spec:\n(define auto-quote-unknowns :effects []\n  (fn (expr env)\n    (if (not (list? expr)) expr\n      (if (empty? expr) expr\n        ;; Head stays as symbol (function position)\n        (cons (first expr)\n              (map (fn (child)\n                     (cond\n                       (list? child)\n                         (auto-quote-unknowns child env)\n                       (= (type-of child) \"symbol\")\n                         (let ((name (symbol-name child)))\n                           (if (or (env-has? env name)\n                                   (starts-with? name \":\")\n                                   (starts-with? name \"~\")\n                                   (starts-with? name \"!\"))\n                             child     ;; known → keep as symbol\n                             name))    ;; unknown → string\n                       :else child))\n                   (rest expr)))))))"
          "lisp"))
        (p "This is checked against the " (em "actual environment") " at request time — "
           "not a hardcoded list. If you define a new page function, "
           "it's immediately recognized as a function name, not a slug."))

      (~docs/subsection :title "Defhandler endpoints"
        (p "API endpoints are defined with " (code "defhandler") " and use the same "
           "nested SX URL structure. These are live endpoints on this site — "
           "they return SX wire format that the client renders:")
        (~docs/code :src (highlight
          ";; From sx/sx/handlers/ref-api.sx — live API endpoint:\n(defhandler ref-time :method \"GET\"\n  :path \"/sx/(geography.(hypermedia.(reference.(api.time))))\"\n  (span :id \"time\" (str \"Server time: \" (format-time (now)))))\n\n;; The endpoint is an SX expression that returns SX.\n;; The URL IS the address. The handler IS the content."
          "lisp"))
        (p "Try these live endpoints — each returns SX wire format:")
        (div (~tw :tokens "space-y-1 ml-4")
          (p (a :href "/sx/(geography.(hypermedia.(reference.(api.time))))"
                (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(hypermedia.(reference.(api.time))))") " — current server time")
          (p (a :href "/sx/(geography.(hypermedia.(reference.(api.swap-item))))"
                (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(hypermedia.(reference.(api.swap-item))))") " — a timestamped item")
          (p (a :href "/sx/(geography.(hypermedia.(example.(api.click))))"
                (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(hypermedia.(example.(api.click))))") " — click-to-load demo content"))

        (p "Notice the URL structure: the API endpoint " (em "is") " a nested expression. "
           (code "(geography (hypermedia (reference (api time))))") " — "
           "the handler lives at the same address as its content. "
           "There is no separation between \"the API\" and \"the page.\"")

        (p "More handler examples from the "
           (a :href "/sx/(geography.(hypermedia.(reference.attributes)))"
              (~tw :tokens "text-violet-600 hover:underline") "attributes reference") ":")
        (~docs/code :src (highlight
          ";; POST handler — receives form data, returns SX:\n(defhandler ref-greet :method \"POST\"\n  :path \"/sx/(geography.(hypermedia.(reference.(api.greet))))\"\n  (let ((name (request-form \"name\")))\n    (div :id \"result\" :class \"p-4 border rounded\"\n      (p (str \"Hello, \" (if (empty? name) \"world\" name) \"!\")))))\n\n;; DELETE handler — receives path parameter:\n(defhandler ref-delete-item :method \"DELETE\"\n  :path \"/sx/(geography.(hypermedia.(reference.(api.(item.<sx:item_id>)))))\"\n  \"\")\n\n;; GET handler with query params:\n(defhandler ref-trigger-search :method \"GET\"\n  :path \"/sx/(geography.(hypermedia.(reference.(api.trigger-search))))\"\n  (let ((q (request-arg \"q\")))\n    (div :id \"search-results\"\n      (p (str \"Results for: \" q)))))"
          "lisp"))))

    ;; -----------------------------------------------------------------
    (~docs/section :title "Client-Side: eval in the Browser" :id "client"
      (p "The same URL algebra runs in the browser. When you click a link on this site, "
         "the client-side router checks if the page can be rendered locally "
         "without a server round-trip.")

      (~docs/subsection :title "The client route check"
        (~docs/code :src (highlight
          ";; From orchestration.sx — client-side route decision:\n;;\n;; 1. Match the URL against the page registry\n;; 2. Check if target layout matches current layout\n;; 3. Check if all component dependencies are loaded\n;; 4. If pure (no IO): render client-side, no server request\n;; 5. If data-dependent: fetch data, then render\n;; 6. If layout changes: fall through to server (needs OOB header)\n\n(define try-client-route :effects [mutation io]\n  (fn (pathname target-sel)\n    (let ((match (find-matching-route pathname _page-routes)))\n      (if (nil? match)\n        false   ;; no match → server handles it\n        (if (not (= (get match \"layout\") (current-page-layout)))\n          false ;; layout change → server (needs OOB update)\n          ;; ... render client-side\n          )))))"
          "lisp"))
        (p "Pure pages (no " (code "has-data") " flag) render instantly in the browser. "
           "Data pages fetch from the server, then render client-side. "
           "Layout changes always go to the server for OOB shell updates."))

      (~docs/subsection :title "URL parsing in the browser"
        (p "The " (code "prepare-url-expr") " function from " (code "router.sx") " is bootstrapped "
           "to JavaScript as " (code "Sx.prepareUrlExpr") ". The browser uses it for "
           "client-side navigation, relative URL resolution, and the address bar REPL:")
        (~docs/code :src (highlight
          ";; From router.sx — bootstrapped to both Python and JavaScript:\n(define prepare-url-expr :effects []\n  (fn (url-path env)\n    (let ((expr (url-to-expr url-path)))\n      (if (empty? expr)\n        expr\n        (auto-quote-unknowns expr env)))))\n\n;; url-to-expr: strip /, dots→spaces, parse\n;; auto-quote-unknowns: unknown symbols → strings\n;; Result: ready for standard eval"
          "lisp"))
        (p "One spec, two hosts. The Python server and JavaScript client share "
           "the same URL parsing, auto-quoting, and resolution logic. "
           "The spec is in " (code "router.sx") "; the bootstrappers compile it to "
           (code "sx_ref.py") " and " (code "sx-browser.js") ".")))

    ;; -----------------------------------------------------------------
    (~docs/section :title "Relative URLs as Function Application" :id "relative"
      (p "Relative URLs are not string manipulation — they are structural transforms "
         "on the expression tree. The dots tell you how many levels of nesting to pop. "
         "This is function application over URL structure.")

      (~docs/subsection :title "One dot: apply at current level"
        (p "A single dot appends at the current nesting depth. "
           "It's like calling a function with an extra argument:")
        (~docs/code :src (highlight
          ";; Current page: /(geography.(hypermedia.(example.progress-bar)))\n;;\n;; .click-to-load\n;; = \"at the current level, apply click-to-load\"\n;; → /(geography.(hypermedia.(example.click-to-load)))\n;;\n;; The inner expression (example.progress-bar) becomes (example.click-to-load).\n;; The outer nesting (geography.(hypermedia.(...))) is preserved."
          "lisp"))
        (p "This is a sibling navigation — same parent, different leaf."))

      (~docs/subsection :title "Two dots: pop one level, apply"
        (p "Two dots remove the innermost nesting level, then optionally apply a new one. "
           "Like " (code "cd ..") " in a filesystem — but structural, not string-based:")
        (~docs/code :src (highlight
          ";; Current: /(geography.(hypermedia.(example.progress-bar)))\n;;\n;; ..                    → /(geography.(hypermedia.(example)))\n;; ..inline-edit         → /(geography.(hypermedia.(example.inline-edit)))\n;; ..reference           → /(geography.(hypermedia.(reference)))\n;;\n;; Pop the innermost expression, replace with the new slug.\n;; The outer nesting is preserved."
          "lisp")))

      (~docs/subsection :title "Three+ dots: pop multiple levels"
        (p "Each additional dot pops one more level of nesting. "
           "N dots = pop N-1 levels:")
        (~docs/code :src (highlight
          ";; Current: /(geography.(hypermedia.(example.progress-bar)))\n;;\n;; ...           → /(geography.(hypermedia))       ;; pop 2 levels\n;; ....          → /(geography)                    ;; pop 3 levels\n;; .....         → /                               ;; pop 4 levels (root)\n;;\n;; Combine with a slug to navigate across sections:\n;; ...reactive.(examples)  → /(geography.(reactive.(examples)))  ;; pop 2, into reactive\n;; ....language.(doc.intro)\n;;   → /(language.(doc.intro))                       ;; pop 3, into language"
          "lisp")))

      (~docs/subsection :title "Why this is functional, not textual"
        (p "REST relative URLs are string operations — remove path segments, append new ones. "
           "This breaks when the hierarchy is structural rather than linear.")
        (~docs/code :src (highlight
          ";; REST relative: ../inline-edit on /geography/hypermedia/examples/progress-bar\n;; → /geography/hypermedia/examples/inline-edit\n;; Works! But only because the hierarchy happens to be flat.\n\n;; What about navigating to a sibling section?\n;; REST: ../../reference/attributes\n;; How many ../ do you need? You have to count path segments.\n;; The answer changes if the base path changes.\n\n;; SX relative: ..reference.attributes\n;; from /(geography.(hypermedia.(example.progress-bar)))\n;; → /(geography.(hypermedia.(reference.attributes)))\n;;\n;; The dots operate on nesting depth, not string segments.\n;; Add a level of nesting? The relative URL still works.\n;; Restructure the tree? Relative links within a subtree are unaffected."
          "lisp"))
        (p "Relative SX URLs are " (em "structurally stable") " — "
           "they navigate the expression tree, not the string representation."))

      (~docs/subsection :title "Keyword arguments: functional parameters"
        (p "URLs can carry keyword arguments that parameterize the innermost expression. "
           "Keywords use the same " (code ":name") " syntax as SX function calls:")
        (~docs/code :src (highlight
          ";; Set a keyword on a page:\n/(language.(spec.(explore.signals.:page.3)))\n→ (language (spec (explore signals :page 3)))\n\n;; :page is a keyword argument to the explore function.\n;; It's the same syntax you'd use when calling a component:\n;; (~paginator :current-page 3 :total-pages 10)\n\n;; Delta values — relative keyword modification:\n;; .:page.+1   → increment current :page by 1\n;; .:page.-1   → decrement current :page by 1\n;;\n;; This is pagination as URL algebra:\n;; Current: /(language.(spec.(explore.signals.:page.3)))\n;; .:page.+1 → /(language.(spec.(explore.signals.:page.4)))\n;; No JavaScript, no state management. A URL transform."
          "lisp")))

      (~docs/subsection :title "The resolve-relative-url spec"
        (p "Relative resolution is defined in " (code "router.sx") " as a pure function. "
           "It parses the current URL's expression structure, pops levels, "
           "splices the new content, and serializes back:")
        (~docs/code :src (highlight
          ";; From router.sx — pure function, no IO:\n(define resolve-relative-url :effects []\n  (fn (current-url relative-url)\n    ;; Parse current URL's expression\n    ;; Count dots to determine pop level\n    ;; Pop that many nesting levels\n    ;; Append new content\n    ;; Serialize back to URL format\n    ...))\n\n;; Tested with 50+ cases in test-router.sx:\n(resolve-relative-url\n  \"/sx/(geography.(hypermedia.(example.progress-bar)))\"\n  \"..inline-edit\")\n→ \"/sx/(geography.(hypermedia.(example.inline-edit)))\"\n\n(resolve-relative-url\n  \"/sx/(language.(spec.(explore.signals.:page.3)))\"\n  \".:page.+1\")\n→ \"/sx/(language.(spec.(explore.signals.:page.4)))\""
          "lisp"))
        (p "This function is bootstrapped to both Python and JavaScript. "
           "Server-side redirects and client-side link resolution use the same code.")))

    ;; -----------------------------------------------------------------
    (~docs/section :title "URL Special Forms" :id "special-forms"
      (p "Special forms are meta-operations on URLs. They transform how content "
         "is resolved or displayed. The " (code "!") " prefix distinguishes them "
         "from section and page function names.")

      (~docs/subsection :title "The six special forms"
        (div (~tw :tokens "overflow-x-auto mt-4 mb-4")
          (table (~tw :tokens "w-full text-sm text-left")
            (thead
              (tr (~tw :tokens "border-b border-stone-200")
                (th (~tw :tokens "py-2 px-3 font-semibold text-stone-700") "Form")
                (th (~tw :tokens "py-2 px-3 font-semibold text-stone-700") "Example URL")
                (th (~tw :tokens "py-2 px-3 font-semibold text-stone-700") "Effect")))
            (tbody (~tw :tokens "text-stone-600")
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-2 px-3 font-mono text-violet-700") "!source")
                (td (~tw :tokens "py-2 px-3 font-mono text-xs") "/sx/(!source.(~essays/sx-sucks/essay-sx-sucks))")
                (td (~tw :tokens "py-2 px-3") "Show the defcomp source code"))
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-2 px-3 font-mono text-violet-700") "!inspect")
                (td (~tw :tokens "py-2 px-3 font-mono text-xs") "/sx/(!inspect.(language.(doc.primitives)))")
                (td (~tw :tokens "py-2 px-3") "Dependencies, CSS footprint, render plan, IO refs"))
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-2 px-3 font-mono text-violet-700") "!diff")
                (td (~tw :tokens "py-2 px-3 font-mono text-xs") "/sx/(!diff.(spec.signals).(spec.eval))")
                (td (~tw :tokens "py-2 px-3") "Side-by-side comparison of two expressions"))
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-2 px-3 font-mono text-violet-700") "!search")
                (td (~tw :tokens "py-2 px-3 font-mono text-xs") "/sx/(!search.\"define\".:in.(spec.signals))")
                (td (~tw :tokens "py-2 px-3") "Grep within a page or spec source"))
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-2 px-3 font-mono text-violet-700") "!raw")
                (td (~tw :tokens "py-2 px-3 font-mono text-xs") "/sx/(!raw.(~some-component))")
                (td (~tw :tokens "py-2 px-3") "Skip " (code "~layouts/doc") " wrapping — return raw content"))
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-2 px-3 font-mono text-violet-700") "!json")
                (td (~tw :tokens "py-2 px-3 font-mono text-xs") "/sx/(!json.(language.(doc.primitives)))")
                (td (~tw :tokens "py-2 px-3") "Return data as JSON instead of rendered content"))))))

      (~docs/subsection :title "How special forms are parsed"
        (p "The " (code "parse-sx-url") " function in " (code "router.sx") " detects and "
           "decomposes special form URLs:")
        (~docs/code :src (highlight
          ";; From router.sx — special form detection:\n(define parse-sx-url :effects []\n  (fn (url)\n    ;; Returns a typed descriptor:\n    ;; {:type \"special-form\" :form \"!source\" :inner \"(~essay)\"}\n    ;; {:type \"absolute\" :raw \"/(language.(doc.intro))\"}\n    ;; {:type \"relative\" :raw \"..eval\"}\n    ;; {:type \"direct-component\" :name \"~essay-sx-sucks\"}\n    ...))\n\n;; The ! prefix is detected in the expression head:\n;; /(!source.(~essay)) → head is !source → special form\n;; /(language.(doc.intro)) → head is language → normal\n\n;; Each special form takes the inner expression as its argument:\n;; !source wraps whatever follows in a source viewer\n;; !inspect wraps whatever follows in an analysis view\n;; !diff takes two inner expressions"
          "lisp"))
        (p "Special forms compose with the rest of the URL algebra. "
           (code "!source") " can wrap any valid SX URL expression — "
           "a page function call, a direct component, or a nested section:"))

      (~docs/subsection :title "The four SX sigils"
        (p "SX uses four single-character sigils, each marking a different kind of name:")
        (div (~tw :tokens "overflow-x-auto mt-2 mb-2")
          (table (~tw :tokens "w-full text-sm text-left")
            (thead
              (tr (~tw :tokens "border-b border-stone-200")
                (th (~tw :tokens "py-1 px-3 font-semibold text-stone-700") "Sigil")
                (th (~tw :tokens "py-1 px-3 font-semibold text-stone-700") "Meaning")
                (th (~tw :tokens "py-1 px-3 font-semibold text-stone-700") "Examples")))
            (tbody (~tw :tokens "text-stone-600")
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-1 px-3 font-mono text-lg text-violet-700") "~")
                (td (~tw :tokens "py-1 px-3") "Component")
                (td (~tw :tokens "py-1 px-3 font-mono text-xs") "~layouts/doc  ~essays/sx-sucks/essay-sx-sucks"))
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-1 px-3 font-mono text-lg text-violet-700") ":")
                (td (~tw :tokens "py-1 px-3") "Keyword")
                (td (~tw :tokens "py-1 px-3 font-mono text-xs") ":title  :page  :format"))
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-1 px-3 font-mono text-lg text-violet-700") ".")
                (td (~tw :tokens "py-1 px-3") "Relative navigation")
                (td (~tw :tokens "py-1 px-3 font-mono text-xs") ".slug  ..  ...intro"))
              (tr (~tw :tokens "border-b border-stone-100")
                (td (~tw :tokens "py-1 px-3 font-mono text-lg text-violet-700") "!")
                (td (~tw :tokens "py-1 px-3") "URL special form")
                (td (~tw :tokens "py-1 px-3 font-mono text-xs") "!source  !inspect  !diff")))))))

    ;; -----------------------------------------------------------------
    (~docs/section :title "The Evaluation Model" :id "eval"
      (p "When the server receives an SX URL, it evaluates it in four steps:")

      (~docs/subsection :title "Step 1: Parse"
        (p "Strip the leading " (code "/") ", replace dots with spaces, parse as SX. "
           "This is the " (code "url-to-expr") " function from " (code "router.sx") ":")
        (~docs/code :src (highlight
          ";; Input:  /sx/(language.(doc.introduction))\n;; Strip prefix:  (language.(doc.introduction))\n;; Dots→spaces:   (language (doc introduction))\n;; Parse:         [Symbol(\"language\"), [Symbol(\"doc\"), Symbol(\"introduction\")]]"
          "lisp")))

      (~docs/subsection :title "Step 2: Auto-quote"
        (p "Unknown symbols become strings. Known functions stay as symbols. "
           "This is " (code "auto-quote-unknowns") " — checked against the live env:")
        (~docs/code :src (highlight
          ";; 'language' is in env (section function) → stays Symbol\n;; 'doc' is in env (page function) → stays Symbol\n;; 'introduction' is NOT in env → becomes \"introduction\"\n;;\n;; Result: [Symbol(\"language\"), [Symbol(\"doc\"), \"introduction\"]]"
          "lisp")))

      (~docs/subsection :title "Step 3: Evaluate"
        (p "Standard inside-out evaluation — same as any SX expression:")
        (~docs/code :src (highlight
          ";; 1. Eval \"introduction\" → \"introduction\" (string, self-evaluating)\n;; 2. Eval (doc \"introduction\") → calls doc function\n;;    → returns '(~docs-content/docs-introduction-content)\n;; 3. Eval (language <ast>) → calls language function\n;;    → passes content through (identity)\n;; 4. Result: [Symbol(\"~docs-content/docs-introduction-content\")]"
          "lisp")))

      (~docs/subsection :title "Step 4: Wrap and render"
        (p "The router wraps the result in " (code "~layouts/doc") " with the URL as " (code ":path") ":")
        (~docs/code :src (highlight
          ";; Wrap:   (~layouts/doc :path \"/sx/(language.(doc.introduction))\" <content>)\n;; Render: aser expands ~layouts/doc → nav, breadcrumbs, layout shell\n;;         aser expands ~docs-content/docs-introduction-content → page HTML\n;; Return: full HTML page (or OOB wire format for HTMX requests)"
          "lisp")))

      (p "The entire routing layer is one function call. There is no routing table, "
         "no URL pattern matching, no middleware chain. The URL is an expression. "
         "The server evaluates it. The result is a page."))

    ;; -----------------------------------------------------------------
    (~docs/section :title "SX URLs in Hypermedia" :id "hypermedia"
      (p "SX URLs integrate with the SX hypermedia attributes. "
         "Links, fetches, and progressive enhancement all accept SX URLs.")

      (~docs/subsection :title "Links"
        (p "Standard anchor tags with SX URL hrefs. Every link below is live:")
        (div (~tw :tokens "space-y-1 ml-4 mb-3")
          (p (a :href "/sx/(language.(doc.introduction))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(language.(doc.introduction))") " — Introduction")
          (p (a :href "/sx/(etc.(essay.sx-sucks))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(etc.(essay.sx-sucks))") " — SX Sucks (the honest critique)")
          (p (a :href "/sx/(geography.(hypermedia.(example.progress-bar)))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(hypermedia.(example.progress-bar)))") " — Progress bar demo")
          (p (a :href "/sx/(language.(test.router))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(language.(test.router))") " — Router spec tests (115 tests)")))

      (~docs/subsection :title "sx-get — HTMX-style fetching"
        (p (code "sx-get") " fetches content from an SX URL and swaps it into the DOM:")
        (~docs/code :src (highlight
          ";; Fetch and swap a section:\n(div :sx-get \"/sx/(geography.(hypermedia.(example.progress-bar)))\"\n     :sx-trigger \"click\"\n     :sx-target \"#content\"\n     :sx-swap \"innerHTML\"\n  \"Load Progress Bar Example\")\n\n;; Paginated content with keyword deltas:\n(button :sx-get \".:page.+1\"\n        :sx-trigger \"click\"\n        :sx-target \"#results\"\n        :sx-swap \"innerHTML\"\n  \"Next Page\")"
          "lisp")))

      (~docs/subsection :title "Pagination — URLs as algebra"
        (p "The relative URL algebra makes pagination trivial. "
           "No state, no event handlers — just URLs:")
        (~docs/code :src (highlight
          ";; Paginator component — pure URL navigation:\n(defcomp ~paginator (&key current-page total-pages)\n  (nav :class \"flex gap-2\"\n    (when (> current-page 1)\n      (a :href \".:page.-1\" \"Previous\"))  ;; delta: decrement :page\n    (span (str \"Page \" current-page \" of \" total-pages))\n    (when (< current-page total-pages)\n      (a :href \".:page.+1\" \"Next\"))))   ;; delta: increment :page\n\n;; On /(language.(spec.(explore.signals.:page.3))):\n;;   \"Previous\" → .:page.-1 → :page becomes 2\n;;   \"Next\"     → .:page.+1 → :page becomes 4\n;;\n;; Each link is a static href. Server renders the right page.\n;; Back button works. Bookmarkable. Shareable. Cacheable."
          "lisp"))))

    ;; -----------------------------------------------------------------
    (~docs/section :title "GraphSX: URLs as Queries" :id "graphsx"
      (p "The SX URL scheme is not just a routing convention — it is a query language. "
         "The structural parallel with "
         (a :href "https://graphql.org/" (~tw :tokens "text-violet-600 hover:underline") "GraphQL")
         " is exact:")

      (div (~tw :tokens "overflow-x-auto mt-4 mb-4")
        (table (~tw :tokens "w-full text-sm text-left")
          (thead
            (tr (~tw :tokens "border-b border-stone-200")
              (th (~tw :tokens "py-2 px-3 font-semibold text-stone-700") "Concept")
              (th (~tw :tokens "py-2 px-3 font-semibold text-stone-700") "GraphQL")
              (th (~tw :tokens "py-2 px-3 font-semibold text-stone-700") "SX URLs")))
          (tbody (~tw :tokens "text-stone-600")
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "py-2 px-3 font-semibold") "Endpoint")
              (td (~tw :tokens "py-2 px-3") (code "/graphql"))
              (td (~tw :tokens "py-2 px-3") "Catch-all " (code "/<path:expr>")))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "py-2 px-3 font-semibold") "Query structure")
              (td (~tw :tokens "py-2 px-3") "Nested fields " (code "{ language { doc { ... } } }"))
              (td (~tw :tokens "py-2 px-3") "Nested s-expressions " (code "(language (doc ...))")))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "py-2 px-3 font-semibold") "Resolvers")
              (td (~tw :tokens "py-2 px-3") "Per-field functions")
              (td (~tw :tokens "py-2 px-3") "Page functions + " (code "~components")))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "py-2 px-3 font-semibold") "Arguments")
              (td (~tw :tokens "py-2 px-3") (code "doc(slug: \"intro\")"))
              (td (~tw :tokens "py-2 px-3") (code "(doc introduction)")))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "py-2 px-3 font-semibold") "Scoping")
              (td (~tw :tokens "py-2 px-3") "Flat — query-level only")
              (td (~tw :tokens "py-2 px-3") "Structural — parens are scope boundaries"))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "py-2 px-3 font-semibold") "Transport")
              (td (~tw :tokens "py-2 px-3") "POST JSON body")
              (td (~tw :tokens "py-2 px-3") "GET — the URL IS the query"))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "py-2 px-3 font-semibold") "Response")
              (td (~tw :tokens "py-2 px-3") "JSON (needs rendering)")
              (td (~tw :tokens "py-2 px-3") "Content — already meaningful")))))

      (p "The killer difference: in GraphQL, query and rendering are separate concerns. "
         "You fetch JSON, then a React app renders it. In SX, "
         (strong "the query language and the rendering language are the same thing") ". "
         (code "(language (doc introduction))") " is simultaneously a query, a render instruction, and a URL.")

      (p "And because SX URLs are GET requests, they are cacheable, bookmarkable, "
         "shareable, and indexable — everything GraphQL had to sacrifice by using POST."))

    ;; -----------------------------------------------------------------
    (~docs/section :title "HTTP Alignment" :id "http"
      (p "SX URLs are GET requests. The query is the URL path. "
         "This means:")
      (ul (~tw :tokens "space-y-1 text-stone-600 list-disc pl-5")
        (li (strong "Cacheable") " — CDNs cache by URL, and these are URLs")
        (li (strong "Bookmarkable") " — save " (code "/sx/(language.(spec.signals))") " in your browser")
        (li (strong "Shareable") " — paste it in chat, it works")
        (li (strong "Indexable") " — crawlers follow " (code "<a href>") " links")
        (li (strong "No client library") " — " (code "curl") " returns content"))

      (p "HTTP verbs align naturally with SX URL semantics:")
      (~docs/code :src (highlight
        ";; GET — pure evaluation, cacheable:\nGET /sx/(language.(doc.introduction))\n\n;; POST — side effects via defhandler:\nPOST /sx/(geography.(hypermedia.(reference.(api.greet))))\n\n;; DELETE — with path parameters:\nDELETE /sx/(geography.(hypermedia.(reference.(api.(item.42)))))\n\n;; PUT — full replacement:\nPUT /sx/(geography.(hypermedia.(example.(api.putpatch))))"
        "lisp")))

    ;; -----------------------------------------------------------------
    (~docs/section :title "The Router Spec" :id "spec"
      (p "SX URLs are specified in SX itself. "
         "The " (a :href "/sx/(language.(spec.router))" (~tw :tokens "text-violet-600 hover:underline") "router spec")
         " (" (code "router.sx") ") defines URL parsing, matching, relative resolution, "
         "special form detection, and auto-quoting as pure functions.")

      (p "Key functions:")
      (~docs/code :src (highlight
        ";; URL → expression (dots→spaces, parse):\n(url-to-expr \"(language.(doc.intro))\")\n→ (language (doc intro))\n\n;; Auto-quote unknowns against env:\n(auto-quote-unknowns '(language (doc intro)) env)\n→ (language (doc \"intro\"))     ;; intro not in env → string\n\n;; Full pipeline:\n(prepare-url-expr \"(language.(doc.intro))\" env)\n→ (language (doc \"intro\"))     ;; ready for eval\n\n;; Classify URL type:\n(parse-sx-url \"/sx/(language.(doc.intro))\")\n→ {:type \"absolute\" :raw \"/sx/(language.(doc.intro))\"}\n\n(parse-sx-url \"/sx/(!source.(~essay))\")\n→ {:type \"special-form\" :form \"!source\" :inner \"(~essay)\"}\n\n(parse-sx-url \"..eval\")\n→ {:type \"relative\" :raw \"..eval\"}\n\n;; Resolve relative URLs:\n(resolve-relative-url\n  \"/sx/(geography.(hypermedia.(example.progress-bar)))\"\n  \"..inline-edit\")\n→ \"/sx/(geography.(hypermedia.(example.inline-edit)))\""
        "lisp"))

      (p "These functions are "
         (a :href "/sx/(language.(test.router))" (~tw :tokens "text-violet-600 hover:underline") "tested with 115 SX tests")
         " covering structural navigation, keyword operations, "
         "delta values, special form parsing, and bare-dot shorthand. "
         "The spec bootstraps to Python (" (code "sx_ref.py") ") and "
         "JavaScript (" (code "sx-browser.js") ") — server and client share the same URL algebra."))

    ;; -----------------------------------------------------------------
    (~docs/section :title "The Lisp Tax" :id "parens"
      (p "People will object to the parentheses. Consider what they already accept:")
      (~docs/code :src (highlight
        ";; Developers write this every day:\nhttps://api.site.com/v2/users/123/posts?filter=published&sort=date&order=desc&limit=10\n\n;; And would complain about this?\nhttps://site.com/(users.(posts.123.(filter.published.sort.date.limit.10)))\n\n;; The second is shorter, structured, unambiguous, and composable."
        "lisp"))

      (p "The real question is who reads URLs:")
      (ul (~tw :tokens "space-y-1 text-stone-600 list-disc pl-5")
        (li (strong "End users") " barely look at URLs — they live in address bars that autocomplete")
        (li (strong "Developers") " will love the structure once they understand it")
        (li (strong "Crawlers") " do not care about syntax — they follow links"))
      (p "And this site is " (em "about") " SX, " (em "implemented in") " SX. "
         "Every URL is a live example. Visiting a page is evaluating an expression. "
         "The parentheses are not a tax — they are the point."))

    ;; -----------------------------------------------------------------
    (~docs/section :title "The Site Is a REPL" :id "repl"
      (p "The address bar is the input line. The page is the output. Try these:")
      (div (~tw :tokens "space-y-2 ml-4 mb-4")
        (div
          (p (~tw :tokens "text-stone-500 text-xs") "A page:")
          (p (a :href "/sx/(language.(spec.signals))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(language.(spec.signals))")))
        (div
          (p (~tw :tokens "text-stone-500 text-xs") "Its tests:")
          (p (a :href "/sx/(language.(test.router))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(language.(test.router))")))
        (div
          (p (~tw :tokens "text-stone-500 text-xs") "A component directly:")
          (p (a :href "/sx/(~essays/sx-sucks/essay-sx-sucks)" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(~essays/sx-sucks/essay-sx-sucks)")))
        (div
          (p (~tw :tokens "text-stone-500 text-xs") "An API endpoint:")
          (p (a :href "/sx/(geography.(hypermedia.(reference.(api.time))))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(hypermedia.(reference.(api.time))))")))
        (div
          (p (~tw :tokens "text-stone-500 text-xs") "A tool that analyzes the live system:")
          (p (a :href "/sx/(geography.(isomorphism.bundle-analyzer))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
                "/(geography.(isomorphism.bundle-analyzer))"))))
      (p "You do not need to explain what SX is. "
         "Show someone a URL, and they immediately understand the philosophy. "
         "The entire site is a self-hosting demonstration — "
         "the medium defines itself with itself."))))
