sx-tools: WASM kernel updates, TW/CSSX rework, content refresh, new debugging tools

Build tooling: updated OCaml bootstrapper, compile-modules, bundle.sh, sx-build-all.
WASM browser: rebuilt sx_browser.bc.js/wasm, sx-platform-2.js, .sxbc bytecode files.
CSSX/Tailwind: reworked cssx.sx templates and tw-layout, added tw-type support.
Content: refreshed essays, plans, geography, reactive islands, docs, demos, handlers.
New tools: bisect_sxbc.sh, test-spa.js, render-trace.sx, morph playwright spec.
Tests: added test-match.sx, test-examples.sx, updated test-tw.sx and web tests.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-02 11:31:57 +00:00
parent 9ed1100ef6
commit d40a9c6796
178 changed files with 13591 additions and 9110 deletions

View File

@@ -7,7 +7,7 @@
(defcomp ~sx-urls/urls-content ()
(~docs/page :title "SX URLs"
(p :class "text-stone-500 text-sm italic mb-8"
(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.")
;; -----------------------------------------------------------------
@@ -29,7 +29,7 @@
(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" :class "text-violet-600 hover:underline" "RFC 3986")
(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. "
@@ -39,15 +39,15 @@
"lisp"))
(p "More examples:")
(div :class "space-y-2"
(div (~tw :tokens "space-y-2")
(p (a :href "/sx/(geography.(hypermedia.(example.progress-bar)))"
:class "font-mono text-violet-600 hover:underline text-sm"
(~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))"
:class "font-mono text-violet-600 hover:underline text-sm"
(~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
"/(language.(spec.signals))") " — signals spec")
(p (a :href "/sx/(etc.(essay.sx-sucks))"
:class "font-mono text-violet-600 hover:underline text-sm"
(~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. "
@@ -78,26 +78,26 @@
(p "Top-level sections are structural. "
"Called with no arguments, they return their index page. "
"Called with content, they pass it through:")
(div :class "space-y-1 ml-4"
(p (a :href "/sx/(language)" :class "font-mono text-violet-600 hover:underline text-sm" "/(language)"))
(p (a :href "/sx/(geography)" :class "font-mono text-violet-600 hover:underline text-sm" "/(geography)"))
(p (a :href "/sx/(applications)" :class "font-mono text-violet-600 hover:underline text-sm" "/(applications)"))
(p (a :href "/sx/(etc)" :class "font-mono text-violet-600 hover:underline text-sm" "/(etc)"))))
(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 :class "space-y-1 ml-4"
(p (a :href "/sx/(geography.(hypermedia))" :class "font-mono text-violet-600 hover:underline text-sm"
(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))" :class "font-mono text-violet-600 hover:underline text-sm"
(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))" :class "font-mono text-violet-600 hover:underline text-sm"
(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))" :class "font-mono text-violet-600 hover:underline text-sm"
(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))" :class "font-mono text-violet-600 hover:underline text-sm"
(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))" :class "font-mono text-violet-600 hover:underline text-sm"
(p (a :href "/sx/(applications.(cssx))" (~tw :tokens "font-mono text-violet-600 hover:underline text-sm")
"/(applications.(cssx))"))))
(~docs/subsection :title "Leaf pages"
@@ -108,46 +108,46 @@
"lisp"))
(p "Every page on this site:")
(div :class "grid grid-cols-1 md:grid-cols-2 gap-x-6 gap-y-1 mt-2"
(div (~tw :tokens "grid grid-cols-1 md:grid-cols-2 gap-x-6 gap-y-1 mt-2")
;; Language
(div
(p :class "font-semibold text-stone-700 text-sm mt-2 mb-1" "Language — Docs")
(p (a :href "/sx/(language.(doc.introduction))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(doc.introduction))"))
(p (a :href "/sx/(language.(doc.getting-started))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(doc.getting-started))"))
(p (a :href "/sx/(language.(doc.components))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(doc.components))"))
(p (a :href "/sx/(language.(doc.evaluator))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(doc.evaluator))"))
(p (a :href "/sx/(language.(doc.primitives))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(doc.primitives))"))
(p (a :href "/sx/(language.(doc.special-forms))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(doc.special-forms))"))
(p (a :href "/sx/(language.(doc.server-rendering))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(doc.server-rendering))"))
(p :class "font-semibold text-stone-700 text-sm mt-2 mb-1" "Language — Specs")
(p (a :href "/sx/(language.(spec.core))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(spec.core))"))
(p (a :href "/sx/(language.(spec.parser))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(spec.parser))"))
(p (a :href "/sx/(language.(spec.evaluator))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(spec.evaluator))"))
(p (a :href "/sx/(language.(spec.signals))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(spec.signals))"))
(p (a :href "/sx/(language.(spec.(explore.signals)))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(spec.(explore.signals)))"))
(p :class "font-semibold text-stone-700 text-sm mt-2 mb-1" "Language — Other")
(p (a :href "/sx/(language.(bootstrapper.python))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(bootstrapper.python))"))
(p (a :href "/sx/(language.(bootstrapper.self-hosting))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(bootstrapper.self-hosting))"))
(p (a :href "/sx/(language.(test.eval))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(test.eval))"))
(p (a :href "/sx/(language.(test.router))" :class "font-mono text-violet-600 hover:underline text-xs" "/(language.(test.router))")))
(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 :class "font-semibold text-stone-700 text-sm mt-2 mb-1" "Geography")
(p (a :href "/sx/(geography.(reactive.(examples.counter)))" :class "font-mono text-violet-600 hover:underline text-xs" "/(geography.(reactive.(examples.counter)))"))
(p (a :href "/sx/(geography.(hypermedia.(reference.attributes)))" :class "font-mono text-violet-600 hover:underline text-xs" "/(geography.(hypermedia.(reference.attributes)))"))
(p (a :href "/sx/(geography.(hypermedia.(example.click-to-load)))" :class "font-mono text-violet-600 hover:underline text-xs" "/(geography.(hypermedia.(example.click-to-load)))"))
(p (a :href "/sx/(geography.(hypermedia.(example.infinite-scroll)))" :class "font-mono text-violet-600 hover:underline text-xs" "/(geography.(hypermedia.(example.infinite-scroll)))"))
(p (a :href "/sx/(geography.(isomorphism.bundle-analyzer))" :class "font-mono text-violet-600 hover:underline text-xs" "/(geography.(isomorphism.bundle-analyzer))"))
(p :class "font-semibold text-stone-700 text-sm mt-2 mb-1" "Applications")
(p (a :href "/sx/(applications.(sx-urls))" :class "font-mono text-violet-600 hover:underline text-xs" "/(applications.(sx-urls))") " — this page")
(p (a :href "/sx/(applications.(cssx.patterns))" :class "font-mono text-violet-600 hover:underline text-xs" "/(applications.(cssx.patterns))"))
(p (a :href "/sx/(applications.(protocol.wire-format))" :class "font-mono text-violet-600 hover:underline text-xs" "/(applications.(protocol.wire-format))"))
(p :class "font-semibold text-stone-700 text-sm mt-2 mb-1" "Etc")
(p (a :href "/sx/(etc.(essay.sx-sucks))" :class "font-mono text-violet-600 hover:underline text-xs" "/(etc.(essay.sx-sucks))"))
(p (a :href "/sx/(etc.(essay.self-defining-medium))" :class "font-mono text-violet-600 hover:underline text-xs" "/(etc.(essay.self-defining-medium))"))
(p (a :href "/sx/(etc.(philosophy.sx-manifesto))" :class "font-mono text-violet-600 hover:underline text-xs" "/(etc.(philosophy.sx-manifesto))"))
(p (a :href "/sx/(etc.(plan.spec-explorer))" :class "font-mono text-violet-600 hover:underline text-xs" "/(etc.(plan.spec-explorer))"))
(p (a :href "/sx/(etc.(plan.sx-urls))" :class "font-mono text-violet-600 hover:underline text-xs" "/(etc.(plan.sx-urls))"))))))
(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"
@@ -157,12 +157,12 @@
";; 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 :class "space-y-1 ml-4"
(p (a :href "/sx/(~essays/sx-sucks/essay-sx-sucks)" :class "font-mono text-violet-600 hover:underline text-sm"
(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)" :class "font-mono text-violet-600 hover:underline text-sm"
(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)" :class "font-mono text-violet-600 hover:underline text-sm"
(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."))
@@ -201,7 +201,7 @@
"(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))" :class "text-violet-600 hover:underline"
(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.")))
@@ -240,15 +240,15 @@
";; 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 :class "space-y-1 ml-4"
(div (~tw :tokens "space-y-1 ml-4")
(p (a :href "/sx/(geography.(hypermedia.(reference.(api.time))))"
:class "font-mono text-violet-600 hover:underline text-sm"
(~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))))"
:class "font-mono text-violet-600 hover:underline text-sm"
(~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))))"
:class "font-mono text-violet-600 hover:underline text-sm"
(~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. "
@@ -258,7 +258,7 @@
(p "More handler examples from the "
(a :href "/sx/(geography.(hypermedia.(reference.attributes)))"
:class "text-violet-600 hover:underline" "attributes reference") ":")
(~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"))))
@@ -350,38 +350,38 @@
"from section and page function names.")
(~docs/subsection :title "The six special forms"
(div :class "overflow-x-auto mt-4 mb-4"
(table :class "w-full text-sm text-left"
(div (~tw :tokens "overflow-x-auto mt-4 mb-4")
(table (~tw :tokens "w-full text-sm text-left")
(thead
(tr :class "border-b border-stone-200"
(th :class "py-2 px-3 font-semibold text-stone-700" "Form")
(th :class "py-2 px-3 font-semibold text-stone-700" "Example URL")
(th :class "py-2 px-3 font-semibold text-stone-700" "Effect")))
(tbody :class "text-stone-600"
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-mono text-violet-700" "!source")
(td :class "py-2 px-3 font-mono text-xs" "/sx/(!source.(~essays/sx-sucks/essay-sx-sucks))")
(td :class "py-2 px-3" "Show the defcomp source code"))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-mono text-violet-700" "!inspect")
(td :class "py-2 px-3 font-mono text-xs" "/sx/(!inspect.(language.(doc.primitives)))")
(td :class "py-2 px-3" "Dependencies, CSS footprint, render plan, IO refs"))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-mono text-violet-700" "!diff")
(td :class "py-2 px-3 font-mono text-xs" "/sx/(!diff.(spec.signals).(spec.eval))")
(td :class "py-2 px-3" "Side-by-side comparison of two expressions"))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-mono text-violet-700" "!search")
(td :class "py-2 px-3 font-mono text-xs" "/sx/(!search.\"define\".:in.(spec.signals))")
(td :class "py-2 px-3" "Grep within a page or spec source"))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-mono text-violet-700" "!raw")
(td :class "py-2 px-3 font-mono text-xs" "/sx/(!raw.(~some-component))")
(td :class "py-2 px-3" "Skip " (code "~layouts/doc") " wrapping — return raw content"))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-mono text-violet-700" "!json")
(td :class "py-2 px-3 font-mono text-xs" "/sx/(!json.(language.(doc.primitives)))")
(td :class "py-2 px-3" "Return data as JSON instead of rendered content"))))))
(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 "
@@ -395,30 +395,30 @@
(~docs/subsection :title "The four SX sigils"
(p "SX uses four single-character sigils, each marking a different kind of name:")
(div :class "overflow-x-auto mt-2 mb-2"
(table :class "w-full text-sm text-left"
(div (~tw :tokens "overflow-x-auto mt-2 mb-2")
(table (~tw :tokens "w-full text-sm text-left")
(thead
(tr :class "border-b border-stone-200"
(th :class "py-1 px-3 font-semibold text-stone-700" "Sigil")
(th :class "py-1 px-3 font-semibold text-stone-700" "Meaning")
(th :class "py-1 px-3 font-semibold text-stone-700" "Examples")))
(tbody :class "text-stone-600"
(tr :class "border-b border-stone-100"
(td :class "py-1 px-3 font-mono text-lg text-violet-700" "~")
(td :class "py-1 px-3" "Component")
(td :class "py-1 px-3 font-mono text-xs" "~layouts/doc ~essays/sx-sucks/essay-sx-sucks"))
(tr :class "border-b border-stone-100"
(td :class "py-1 px-3 font-mono text-lg text-violet-700" ":")
(td :class "py-1 px-3" "Keyword")
(td :class "py-1 px-3 font-mono text-xs" ":title :page :format"))
(tr :class "border-b border-stone-100"
(td :class "py-1 px-3 font-mono text-lg text-violet-700" ".")
(td :class "py-1 px-3" "Relative navigation")
(td :class "py-1 px-3 font-mono text-xs" ".slug .. ...intro"))
(tr :class "border-b border-stone-100"
(td :class "py-1 px-3 font-mono text-lg text-violet-700" "!")
(td :class "py-1 px-3" "URL special form")
(td :class "py-1 px-3 font-mono text-xs" "!source !inspect !diff")))))))
(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"
@@ -461,14 +461,14 @@
(~docs/subsection :title "Links"
(p "Standard anchor tags with SX URL hrefs. Every link below is live:")
(div :class "space-y-1 ml-4 mb-3"
(p (a :href "/sx/(language.(doc.introduction))" :class "font-mono text-violet-600 hover:underline text-sm"
(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))" :class "font-mono text-violet-600 hover:underline text-sm"
(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)))" :class "font-mono text-violet-600 hover:underline text-sm"
(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))" :class "font-mono text-violet-600 hover:underline text-sm"
(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"
@@ -488,45 +488,45 @@
(~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/" :class "text-violet-600 hover:underline" "GraphQL")
(a :href "https://graphql.org/" (~tw :tokens "text-violet-600 hover:underline") "GraphQL")
" is exact:")
(div :class "overflow-x-auto mt-4 mb-4"
(table :class "w-full text-sm text-left"
(div (~tw :tokens "overflow-x-auto mt-4 mb-4")
(table (~tw :tokens "w-full text-sm text-left")
(thead
(tr :class "border-b border-stone-200"
(th :class "py-2 px-3 font-semibold text-stone-700" "Concept")
(th :class "py-2 px-3 font-semibold text-stone-700" "GraphQL")
(th :class "py-2 px-3 font-semibold text-stone-700" "SX URLs")))
(tbody :class "text-stone-600"
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-semibold" "Endpoint")
(td :class "py-2 px-3" (code "/graphql"))
(td :class "py-2 px-3" "Catch-all " (code "/<path:expr>")))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-semibold" "Query structure")
(td :class "py-2 px-3" "Nested fields " (code "{ language { doc { ... } } }"))
(td :class "py-2 px-3" "Nested s-expressions " (code "(language (doc ...))")))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-semibold" "Resolvers")
(td :class "py-2 px-3" "Per-field functions")
(td :class "py-2 px-3" "Page functions + " (code "~components")))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-semibold" "Arguments")
(td :class "py-2 px-3" (code "doc(slug: \"intro\")"))
(td :class "py-2 px-3" (code "(doc introduction)")))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-semibold" "Scoping")
(td :class "py-2 px-3" "Flat — query-level only")
(td :class "py-2 px-3" "Structural — parens are scope boundaries"))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-semibold" "Transport")
(td :class "py-2 px-3" "POST JSON body")
(td :class "py-2 px-3" "GET — the URL IS the query"))
(tr :class "border-b border-stone-100"
(td :class "py-2 px-3 font-semibold" "Response")
(td :class "py-2 px-3" "JSON (needs rendering)")
(td :class "py-2 px-3" "Content — already meaningful")))))
(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, "
@@ -540,7 +540,7 @@
(~docs/section :title "HTTP Alignment" :id "http"
(p "SX URLs are GET requests. The query is the URL path. "
"This means:")
(ul :class "space-y-1 text-stone-600 list-disc pl-5"
(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")
@@ -555,7 +555,7 @@
;; -----------------------------------------------------------------
(~docs/section :title "The Router Spec" :id "spec"
(p "SX URLs are specified in SX itself. "
"The " (a :href "/sx/(language.(spec.router))" :class "text-violet-600 hover:underline" "router spec")
"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.")
@@ -565,7 +565,7 @@
"lisp"))
(p "These functions are "
(a :href "/sx/(language.(test.router))" :class "text-violet-600 hover:underline" "tested with 115 SX tests")
(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 "
@@ -579,7 +579,7 @@
"lisp"))
(p "The real question is who reads URLs:")
(ul :class "space-y-1 text-stone-600 list-disc pl-5"
(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"))
@@ -590,26 +590,26 @@
;; -----------------------------------------------------------------
(~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 :class "space-y-2 ml-4 mb-4"
(div (~tw :tokens "space-y-2 ml-4 mb-4")
(div
(p :class "text-stone-500 text-xs" "A page:")
(p (a :href "/sx/(language.(spec.signals))" :class "font-mono text-violet-600 hover:underline text-sm"
(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 :class "text-stone-500 text-xs" "Its tests:")
(p (a :href "/sx/(language.(test.router))" :class "font-mono text-violet-600 hover:underline text-sm"
(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 :class "text-stone-500 text-xs" "A component directly:")
(p (a :href "/sx/(~essays/sx-sucks/essay-sx-sucks)" :class "font-mono text-violet-600 hover:underline text-sm"
(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 :class "text-stone-500 text-xs" "An API endpoint:")
(p (a :href "/sx/(geography.(hypermedia.(reference.(api.time))))" :class "font-mono text-violet-600 hover:underline text-sm"
(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 :class "text-stone-500 text-xs" "A tool that analyzes the live system:")
(p (a :href "/sx/(geography.(isomorphism.bundle-analyzer))" :class "font-mono text-violet-600 hover:underline text-sm"
(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. "