;; CSSX — Styling as Components
;; Documentation for the CSSX approach: no parallel style infrastructure,
;; just defcomp components that decide how to style their children.

;; ---------------------------------------------------------------------------
;; Overview
;; ---------------------------------------------------------------------------

(defcomp ~cssx/overview-content ()
  (~docs/page :title "CSSX Components"

    (~docs/section :title "The Idea" :id "idea"
      (p (strong "Styling is just components.") " A CSSX component is a regular "
         (code "defcomp") " that decides how to style its children. It might apply "
         "Tailwind classes, or hand-written CSS classes, or inline styles, or generate "
         "rules at runtime. The implementation is the component's private business. "
         "The consumer just calls " (code "(~cssx/btn :variant \"primary\" \"Submit\")") " and doesn't care.")
      (p "Because it's " (code "defcomp") ", you get everything for free: caching, bundling, "
         "dependency scanning, server/client rendering, composition. No parallel infrastructure."))

    (~docs/section :title "Why Not a Style Dictionary?" :id "why"
      (p "SX previously had a parallel CSS system: a style dictionary (JSON blob of "
         "atom-to-declaration mappings), a " (code "StyleValue") " type threaded through "
         "the evaluator and renderer, content-addressed hash class names (" (code "sx-a3f2b1")
         "), runtime CSS injection, and a separate caching pipeline (cookies, localStorage).")
      (p "This was ~3,000 lines of code across the spec, bootstrappers, and host implementations. "
         "It was never adopted. The codebase voted with its feet: " (code ":class") " strings "
         "with " (code "defcomp") " already covered every real use case.")
      (p "The result of that system: elements in the DOM got opaque class names like "
         (code "class=\"sx-a3f2b1\"") ". DevTools became useless. You couldn't inspect an "
         "element and understand its styling. " (strong "That was a deal breaker.")))

    (~docs/section :title "Key Advantages" :id "advantages"
      (ul :class "list-disc pl-5 space-y-2 text-stone-700"
        (li (strong "Readable DOM: ") "Elements have real class names, not content-addressed "
            "hashes. DevTools works.")
        (li (strong "Data-driven styling: ") "Components receive data and decide styling. "
            (code "(~cssx/metric :value 150)") " renders red because " (code "value > 100")
            " — logic lives in the component, not a CSS preprocessor.")
        (li (strong "One system: ") "No separate " (code "StyleValue") " type, no style "
            "dictionary JSON, no injection pipeline. Components ARE the styling abstraction.")
        (li (strong "One cache: ") "Component hash/localStorage handles everything. No "
            "separate style dict caching.")
        (li (strong "Composable: ") (code "(~card :elevated true (~cssx/metric :value v))")
            " — styling composes like any other component.")
        (li (strong "Strategy-agnostic: ") "A component can apply Tailwind classes, emit "
            (code "<style>") " blocks, use inline styles, generate CSS custom properties, or "
            "any combination. Swap strategies without touching call sites.")))

    (~docs/section :title "What Changed" :id "changes"
      (~docs/subsection :title "Removed (~3,000 lines)"
        (ul :class "list-disc pl-5 space-y-1 text-stone-600 text-sm"
          (li (code "StyleValue") " type and all plumbing (type checks in eval, render, serialize)")
          (li (code "cssx.sx") " spec module (resolve-style, resolve-atom, split-variant, hash, injection)")
          (li "Style dictionary JSON format, loading, caching (" (code "<script type=\"text/sx-styles\">") ", localStorage)")
          (li (code "style_dict.py") " (782 lines) and " (code "style_resolver.py") " (254 lines)")
          (li (code "css") " and " (code "merge-styles") " primitives")
          (li "Platform interface: " (code "fnv1a-hash") ", " (code "compile-regex") ", " (code "make-style-value") ", " (code "inject-style-value"))
          (li (code "defkeyframes") " special form")
          (li "Style dict cookies and localStorage keys")))

      (~docs/subsection :title "Kept"
        (ul :class "list-disc pl-5 space-y-1 text-stone-600 text-sm"
          (li (code "defstyle") " — simplified to bind any value (string, function, etc.)")
          (li (code "tw.css") " — the compiled Tailwind stylesheet, delivered via CSS class tracking")
          (li (code ":class") " attribute — just takes strings, no special-casing")
          (li "CSS class delivery (" (code "SX-Css") " headers, " (code "<style id=\"sx-css\">") ")")
          (li "All component infrastructure (defcomp, caching, bundling, deps)")))

      (~docs/subsection :title "Added"
        (p "Nothing. CSSX components are just " (code "defcomp") ". The only new thing is "
           "a convention: components whose primary purpose is styling.")))))


;; ---------------------------------------------------------------------------
;; Patterns
;; ---------------------------------------------------------------------------

(defcomp ~cssx/patterns-content ()
  (~docs/page :title "Patterns"

    (~docs/section :title "Class Mapping" :id "class-mapping"
      (p "The simplest pattern: a component that maps semantic keywords to class strings.")
      (highlight
        "(defcomp ~cssx/btn (&key variant disabled &rest children)\n  (button\n    :class (str \"px-4 py-2 rounded font-medium transition \"\n               (case variant\n                 \"primary\" \"bg-blue-600 text-white hover:bg-blue-700\"\n                 \"danger\"  \"bg-red-600 text-white hover:bg-red-700\"\n                 \"ghost\"   \"bg-transparent hover:bg-stone-100\"\n                 \"bg-stone-200 hover:bg-stone-300\")\n               (when disabled \" opacity-50 cursor-not-allowed\"))\n    :disabled disabled\n    children))"
        "lisp")
      (p "Consumers call " (code "(~cssx/btn :variant \"primary\" \"Submit\")") ". The Tailwind "
         "classes are readable in DevTools but never repeated across call sites."))

    (~docs/section :title "Data-Driven Styling" :id "data-driven"
      (p "Styling that responds to data values — impossible with static CSS:")
      (highlight
        "(defcomp ~cssx/metric (&key value label threshold)\n  (let ((t (or threshold 10)))\n    (div :class (str \"p-3 rounded font-bold \"\n                 (cond\n                   ((> value (* t 10)) \"bg-red-500 text-white\")\n                   ((> value t)        \"bg-amber-200 text-amber-900\")\n                   (:else              \"bg-green-100 text-green-800\")))\n      (span :class \"text-sm\" label) \": \" (span (str value)))))"
        "lisp")
      (p "The component makes a " (em "decision") " about styling based on data. "
         "No CSS preprocessor or class name convention can express \"red when value > 100\"."))

    (~docs/section :title "Style Functions" :id "style-functions"
      (p "Reusable style logic that returns class strings — no wrapping element needed:")
      (highlight
        "(define card-classes\n  (fn (&key elevated bordered)\n    (str \"rounded-lg p-4 \"\n         (if elevated \"shadow-lg\" \"shadow-sm\")\n         (when bordered \" border border-stone-200\"))))\n\n;; Usage:\n(div :class (card-classes :elevated true) ...)\n(article :class (card-classes :bordered true) ...)"
        "lisp")
      (p "Or with " (code "defstyle") " for named bindings:")
      (highlight
        "(defstyle card-base \"rounded-lg p-4 shadow-sm\")\n(defstyle card-elevated \"rounded-lg p-4 shadow-lg\")\n\n(div :class card-base ...)"
        "lisp"))

    (~docs/section :title "Responsive Layouts" :id "responsive"
      (p "Components that encode responsive breakpoints:")
      (highlight
        "(defcomp ~cssx/responsive-grid (&key cols &rest children)\n  (div :class (str \"grid gap-4 \"\n               (case (or cols 3)\n                 1 \"grid-cols-1\"\n                 2 \"grid-cols-1 md:grid-cols-2\"\n                 3 \"grid-cols-1 md:grid-cols-2 lg:grid-cols-3\"\n                 4 \"grid-cols-2 md:grid-cols-3 lg:grid-cols-4\"))\n    children))"
        "lisp"))

    (~docs/section :title "Emitting CSS Directly" :id "emitting-css"
      (p "Components are not limited to referencing existing classes. They can generate "
         "CSS — " (code "<style>") " tags, keyframes, custom properties — as part of their output:")
      (highlight
        "(defcomp ~cssx/pulse (&key color duration &rest children)\n  (<>\n    (style (str \"@keyframes sx-pulse {\"\n               \"0%,100% { opacity:1 } 50% { opacity:.5 } }\"))\n    (div :style (str \"animation: sx-pulse \" (or duration \"2s\") \" infinite;\"\n                    \"color:\" (or color \"inherit\"))\n      children)))"
        "lisp")
      (highlight
        "(defcomp ~cssx/theme (&key primary surface &rest children)\n  (<>\n    (style (str \":root {\"\n               \"--color-primary:\" (or primary \"#7c3aed\") \";\"\n               \"--color-surface:\" (or surface \"#fafaf9\") \"}\"))\n    children))"
        "lisp")
      (p "The CSS strategy is the component's private implementation detail. Consumers call "
         (code "(~cssx/pulse :color \"red\" \"Loading...\")") " or "
         (code "(~cssx/theme :primary \"#2563eb\" ...)") " without knowing or caring whether the "
         "component uses classes, inline styles, generated rules, or all three."))))


;; ---------------------------------------------------------------------------
;; Async CSS
;; ---------------------------------------------------------------------------

(defcomp ~cssx/async-content ()
  (~docs/page :title "Async CSS"

    (~docs/section :title "The Pattern" :id "pattern"
      (p "A CSSX component that needs CSS it doesn't have yet can "
         (strong "fetch and cache it before rendering") ". This is just "
         (code "~shared:pages/suspense") " combined with a style component — no new infrastructure:")
      (highlight
        "(defcomp ~cssx/styled (&key css-url css-hash fallback &rest children)\n  (if (css-cached? css-hash)\n    ;; Already have it — render immediately\n    children\n    ;; Don't have it — suspense while we fetch\n    (~shared:pages/suspense :id (str \"css-\" css-hash)\n      :fallback (or fallback (span \"\"))\n      (do\n        (fetch-css css-url css-hash)\n        children))))"
        "lisp")
      (p "The consumer never knows:")
      (highlight
        "(~cssx/styled :css-url \"/css/charts.css\" :css-hash \"abc123\"\n  (~bar-chart :data metrics))"
        "lisp"))

    (~docs/section :title "Use Cases" :id "use-cases"
      (~docs/subsection :title "Federated Components"
        (p "A " (code "~cssx/btn") " from another site arrives via IPFS with a CID pointing "
           "to its CSS. The component fetches and caches it before rendering. "
           "No coordination needed between sites.")
        (highlight
          "(defcomp ~cssx/federated-widget (&key cid &rest children)\n  (let ((css-cid (str cid \"/style.css\"))\n        (cached  (css-cached? css-cid)))\n    (if cached\n      children\n      (~shared:pages/suspense :id (str \"fed-\" cid)\n        :fallback (div :class \"animate-pulse bg-stone-100 rounded h-20\")\n        (do (fetch-css (str \"https://ipfs.io/ipfs/\" css-cid) css-cid)\n            children)))))"
          "lisp"))

      (~docs/subsection :title "Heavy UI Libraries"
        (p "Code editors, chart libraries, rich text editors — their CSS only loads "
           "when the component actually appears on screen:")
        (highlight
          "(defcomp ~cssx/code-editor (&key language value on-change)\n  (~cssx/styled :css-url \"/css/codemirror.css\" :css-hash (asset-hash \"codemirror\")\n    :fallback (pre :class \"p-4 bg-stone-900 text-stone-300 rounded\" value)\n    (div :class \"cm-editor\"\n      :data-language language\n      :data-value value)))"
          "lisp"))

      (~docs/subsection :title "Lazy Themes"
        (p "Theme CSS loads on first use, then is instant on subsequent visits:")
        (highlight
          "(defcomp ~cssx/lazy-theme (&key name &rest children)\n  (let ((css-url (str \"/css/themes/\" name \".css\"))\n        (hash    (str \"theme-\" name)))\n    (~cssx/styled :css-url css-url :css-hash hash\n      :fallback children  ;; render unstyled immediately\n      children)))"
          "lisp")))

    (~docs/section :title "How It Composes" :id "composition"
      (p "Async CSS composes with everything already in SX:")
      (ul :class "list-disc pl-5 space-y-1 text-stone-700"
        (li (code "~shared:pages/suspense") " handles the async gap with fallback content")
        (li "localStorage handles caching across sessions")
        (li (code "<style id=\"sx-css\">") " is the injection target (same as CSS class delivery)")
        (li "Component content-hashing tracks what the client has")
        (li "No new types, no new delivery protocol, no new spec code")))))


;; ---------------------------------------------------------------------------
;; Live Styles
;; ---------------------------------------------------------------------------

(defcomp ~cssx/live-content ()
  (~docs/page :title "Live Styles"

    (~docs/section :title "Styles That Respond to Events" :id "concept"
      (p "Combine " (code "~live") " (SSE) or " (code "~ws") " (WebSocket) with style "
         "components, and you get styles that change in real-time in response to server "
         "events. No new infrastructure — just components receiving data through a "
         "persistent transport."))

    (~docs/section :title "SSE: Live Theme Updates" :id "sse-theme"
      (p "A " (code "~live") " component declares a persistent connection to an SSE "
         "endpoint. When the server pushes a new event, " (code "resolveSuspense")
         " replaces the content:")
      (highlight
        "(~live :src \"/api/stream/brand\"\n  (~shared:pages/suspense :id \"theme\"\n    (~cssx/theme :primary \"#7c3aed\" :surface \"#fafaf9\")))"
        "lisp")
      (p "Server pushes a new theme:")
      (highlight
        "event: sx-resolve\ndata: {\"id\": \"theme\", \"sx\": \"(~cssx/theme :primary \\\"#2563eb\\\" :surface \\\"#1e1e2e\\\")\"}"
        "text")
      (p "The " (code "~cssx/theme") " component emits CSS custom properties. Everything "
         "using " (code "var(--color-primary)") " repaints instantly:")
      (highlight
        "(defcomp ~cssx/theme (&key primary surface)\n  (style (str \":root {\"\n    \"--color-primary:\" (or primary \"#7c3aed\") \";\"\n    \"--color-surface:\" (or surface \"#fafaf9\") \"}\")))"
        "lisp"))

    (~docs/section :title "SSE: Live Dashboard Metrics" :id "sse-metrics"
      (p "Style changes driven by live data — the component decides the visual treatment:")
      (highlight
        "(~live :src \"/api/stream/dashboard\"\n  (~shared:pages/suspense :id \"cpu\"\n    (~cssx/metric :value 0 :label \"CPU\" :threshold 80))\n  (~shared:pages/suspense :id \"memory\"\n    (~cssx/metric :value 0 :label \"Memory\" :threshold 90))\n  (~shared:pages/suspense :id \"requests\"\n    (~cssx/metric :value 0 :label \"RPS\" :threshold 1000)))"
        "lisp")
      (p "Server pushes updated values. " (code "~cssx/metric") " turns red when "
         (code "value > threshold") " — the styling logic lives in the component, "
         "not in CSS selectors or JavaScript event handlers."))

    (~docs/section :title "WebSocket: Collaborative Design" :id "ws-design"
      (p "Bidirectional channel for real-time collaboration. A designer adjusts a color, "
         "all connected clients see the change:")
      (highlight
        "(~ws :src \"/ws/design-studio\"\n  (~shared:pages/suspense :id \"canvas-theme\"\n    (~cssx/theme :primary \"#7c3aed\")))"
        "lisp")
      (p "Client sends a color change:")
      (highlight
        ";; Designer picks a new primary color\n(sx-send ws-conn '(theme-update :primary \"#dc2626\"))"
        "lisp")
      (p "Server broadcasts to all connected clients via " (code "sx-resolve") " — "
         "every client's " (code "~cssx/theme") " component re-renders with the new color."))

    (~docs/section :title "Why This Works" :id "why"
      (p "Every one of these patterns is just a " (code "defcomp") " receiving data "
         "through a persistent transport. The styling strategy — CSS custom properties, "
         "class swaps, inline styles, " (code "<style>") " blocks — is the component's "
         "private business. The transport doesn't know or care.")
      (p "A parallel style system would have needed its own streaming, its own caching, "
         "its own delta protocol for each of these use cases — duplicating what components "
         "already do.")
      (p :class "mt-4 text-stone-500 italic"
         "Note: ~live and ~ws are planned (see Live Streaming). The patterns shown here "
         "will work as described once the streaming transport is implemented. The component "
         "and suspense infrastructure they depend on already exists."))))


;; ---------------------------------------------------------------------------
;; Comparison with CSS Technologies
;; ---------------------------------------------------------------------------

(defcomp ~cssx/comparison-content ()
  (~docs/page :title "Comparisons"

    (~docs/section :title "styled-components / Emotion" :id "styled-components"
      (p (a :href "https://styled-components.com" :class "text-violet-600 hover:underline" "styled-components")
         " pioneered the idea that styling belongs in components. But it generates CSS "
         "at runtime, injects " (code "<style>") " tags, and produces opaque hashed class "
         "names (" (code "class=\"sc-bdfBwQ fNMpVx\"") "). Open DevTools and you see gibberish. "
         "It also carries significant runtime cost — parsing CSS template literals, hashing, "
         "deduplicating — and needs a separate SSR extraction step (" (code "ServerStyleSheet") ").")
      (p "CSSX components share the core insight (" (em "styling is a component concern")
         ") but without the runtime machinery. When a component applies Tailwind classes, "
         "there's zero CSS generation overhead. When it does emit " (code "<style>")
         " blocks, it's explicit — not hidden behind a tagged template literal. "
         "And the DOM is always readable."))

    (~docs/section :title "CSS Modules" :id "css-modules"
      (p (a :href "https://github.com/css-modules/css-modules" :class "text-violet-600 hover:underline" "CSS Modules")
         " scope class names to avoid collisions by rewriting them at build time: "
         (code ".button") " becomes " (code ".button_abc123")
         ". This solves the global namespace problem but creates the same opacity issue — "
         "hashed names in the DOM that you can't grep for or reason about.")
      (p "CSSX components don't need scoping because component boundaries already provide "
         "isolation. A " (code "~cssx/btn") " owns its markup. There's nothing to collide with."))

    (~docs/section :title "Tailwind CSS" :id "tailwind"
      (p "Tailwind is " (em "complementary") ", not competitive. CSSX components are the "
         "semantic layer on top. Raw Tailwind in markup — "
         (code ":class \"px-4 py-2 bg-blue-600 text-white font-medium rounded hover:bg-blue-700\"")
         " — is powerful but verbose and duplicated across call sites.")
      (p "A CSSX component wraps that string once: " (code "(~cssx/btn :variant \"primary\" \"Submit\")")
         ". The Tailwind classes are still there, readable in DevTools, but consumers don't "
         "repeat them. This is the same pattern Tailwind's own docs recommend ("
         (em "\"extracting components\"") ") — CSSX components are just SX's native way of doing it."))

    (~docs/section :title "Vanilla Extract" :id "vanilla-extract"
      (p (a :href "https://vanilla-extract.style" :class "text-violet-600 hover:underline" "Vanilla Extract")
         " is zero-runtime CSS-in-JS: styles are written in TypeScript, compiled to static "
         "CSS at build time, and referenced by generated class names. It avoids the runtime "
         "cost of styled-components but still requires a build step, a bundler plugin, and "
         "TypeScript. The generated class names are again opaque.")
      (p "CSSX components need no build step for styling — they're evaluated at render time "
         "like any other component. And since the component chooses its own strategy, it can "
         "reference pre-built classes (zero runtime) " (em "or") " generate CSS on the fly — "
         "same API either way."))

    (~docs/section :title "Design Tokens / Style Dictionary" :id "design-tokens"
      (p "The " (a :href "https://amzn.github.io/style-dictionary/" :class "text-violet-600 hover:underline" "Style Dictionary")
         " pattern — a JSON/YAML file mapping token names to values, compiled to "
         "platform-specific output — is essentially what the old CSSX was. It's the "
         "industry standard for design systems.")
      (p "The problem is that it's a parallel system: separate file format, separate build "
         "pipeline, separate caching, separate tooling. CSSX components eliminate all of "
         "that by expressing tokens as component parameters: "
         (code "(~cssx/theme :primary \"#7c3aed\")") " instead of "
         (code "{\"color\": {\"primary\": {\"value\": \"#7c3aed\"}}}")
         ". Same result, no parallel infrastructure."))))


;; ---------------------------------------------------------------------------
;; Philosophy
;; ---------------------------------------------------------------------------

(defcomp ~cssx/philosophy-content ()
  (~docs/page :title "Philosophy"

    (~docs/section :title "The Collapse" :id "collapse"
      (p "The web has spent two decades building increasingly complex CSS tooling: "
         "preprocessors, CSS-in-JS, atomic CSS, utility frameworks, design tokens, style "
         "dictionaries. Each solves a real problem but adds a new system with its own "
         "caching, bundling, and mental model.")
      (p "CSSX components collapse all of this back to the simplest possible thing: "
         (strong "a function that takes data and returns markup with classes.")
         " That's what a component already is. There is no separate styling system because "
         "there doesn't need to be."))

    (~docs/section :title "Proof by Deletion" :id "proof"
      (p "The strongest validation: we built the full parallel system — style dictionary, "
         "StyleValue type, content-addressed hashing, runtime injection, localStorage "
         "caching — and then deleted it because nobody used it. The codebase already had "
         "the answer: " (code "defcomp") " with " (code ":class") " strings.")
      (p "3,000 lines of infrastructure removed. Zero lines added. Every use case still works."))

    (~docs/section :title "The Right Abstraction Level" :id "abstraction"
      (p "CSS-in-JS puts styling " (em "below") " components — you style elements, then compose "
         "them. Utility CSS puts styling " (em "beside") " components — classes in markup, logic "
         "elsewhere. Both create a seam between what something does and how it looks.")
      (p "CSSX components put styling " (em "inside") " components — at the same level as "
         "structure and behavior. A " (code "~cssx/metric") " component knows its own thresholds, "
         "its own color scheme, its own responsive behavior. Styling is just another "
         "decision the component makes, not a separate concern."))

    (~docs/section :title "Relationship to Other Plans" :id "relationships"
      (ul :class "list-disc pl-5 space-y-2 text-stone-700"
        (li (strong "Content-Addressed Components: ") "CSSX components get CIDs like any "
            "other component. A " (code "~cssx/btn") " from one site can be shared to another via "
            "IPFS. No " (code ":css-atoms") " manifest field needed — the component carries "
            "its own styling logic.")
        (li (strong "Isomorphic Rendering: ") "Components render the same on server and client. "
            "No style injection timing issues, no FOUC from late CSS loading.")
        (li (strong "Component Bundling: ") "deps.sx already handles transitive component deps. "
            "Style components are just more components in the bundle — no separate style bundling.")
        (li (strong "Live Streaming: ") "SSE and WebSocket transports push data to components. "
            "Style components react to that data like any other component — no separate style "
            "streaming protocol.")))))


;; ---------------------------------------------------------------------------
;; CSS Delivery
;; ---------------------------------------------------------------------------

(defcomp ~cssx/delivery-content ()
  (~docs/page :title "CSS Delivery"

    (~docs/section :title "Multiple Strategies" :id "strategies"
      (p "A CSSX component chooses its own styling strategy — and each strategy has its "
         "own delivery path:")
      (ul :class "list-disc pl-5 space-y-1 text-stone-700"
        (li (strong "Tailwind classes: ") "Delivered via the on-demand protocol below. "
            "The server ships only the rules the page actually uses.")
        (li (strong "Inline styles: ") "No delivery needed — " (code ":style") " attributes "
            "are part of the markup.")
        (li (strong "Emitted " (code "<style>") " blocks: ") "Components can emit CSS rules "
            "directly. They arrive as part of the rendered HTML — keyframes, custom properties, "
            "scoped rules, anything.")
        (li (strong "External stylesheets: ") "Components can reference pre-loaded CSS files "
            "or lazy-load them via " (code "~shared:pages/suspense") " (see " (a :href "/sx/(applications.(cssx.async))" "Async CSS") ").")
        (li (strong "Custom properties: ") "A " (code "~cssx/theme") " component sets "
            (code "--color-primary") " etc. via a " (code "<style>") " block. Everything "
            "using " (code "var()") " repaints automatically."))
      (p "The protocol below handles the Tailwind utility class case — the most common "
         "strategy — but it's not the only game in town."))

    (~docs/section :title "On-Demand Tailwind Delivery" :id "on-demand"
      (p "When components use Tailwind utility classes, SX ships " (em "only the CSS rules "
         "actually used on the page") ", computed at render time. No build step, no purging, "
         "no unused CSS.")
      (p "The server pre-parses the full Tailwind CSS file into an in-memory registry at "
         "startup. When a response is rendered, SX scans all " (code ":class") " values in "
         "the output, looks up only those classes, and embeds the matching rules."))

    (~docs/section :title "The Protocol" :id "protocol"
      (p "First page load gets the full set of used rules. Subsequent navigations send a "
         "hash of what the client already has, and the server ships only the delta:")
      (highlight
        "# First page load:\nGET / HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Type: text/html\n# Full CSS in <style id=\"sx-css\"> + hash in <meta name=\"sx-css-classes\">\n\n# Subsequent navigation:\nGET /about HTTP/1.1\nSX-Css: a1b2c3d4\n\nHTTP/1.1 200 OK\nContent-Type: text/sx\nSX-Css-Hash: e5f6g7h8\nSX-Css-Add: bg-blue-500,text-white,rounded-lg\n# Only new rules in <style data-sx-css>"
        "bash")
      (p "The client merges new rules into the existing " (code "<style id=\"sx-css\">")
         " block and updates its hash. No flicker, no duplicate rules."))

    (~docs/section :title "Component-Aware Scanning" :id "scanning"
      (p "CSS scanning happens at two levels:")
      (ul :class "list-disc pl-5 space-y-1 text-stone-700"
        (li (strong "Registration time: ") "When a component is defined via " (code "defcomp")
            ", its body is scanned for class strings. The component records which CSS classes "
            "it uses.")
        (li (strong "Render time: ") "The rendered output is scanned for any classes the "
            "static scan missed — dynamically constructed class strings, conditional classes, etc."))
      (p "This means the CSS registry knows roughly what a page needs before rendering, "
         "and catches any stragglers after."))

    (~docs/section :title "Trade-offs" :id "tradeoffs"
      (ul :class "list-disc pl-5 space-y-2 text-stone-700"
        (li (strong "Full Tailwind in memory: ") "The parsed CSS registry is ~4MB. This is "
            "a one-time startup cost per app instance.")
        (li (strong "Regex scanning: ") "Class detection uses regex, so dynamically "
            "constructed class names (e.g. " (code "(str \"bg-\" color \"-500\")") ") can be "
            "missed. Use complete class strings in " (code "case") "/" (code "cond") " branches.")
        (li (strong "No @apply: ") "Tailwind's " (code "@apply") " is a build-time feature. "
            "On-demand delivery works with utility classes directly.")
        (li (strong "Tailwind-shaped: ") "The registry parser understands Tailwind's naming "
            "conventions. Non-Tailwind CSS works via " (code "<style>") " blocks in components.")))))