diff --git a/shared/sx/templates/layout.sx b/shared/sx/templates/layout.sx
index 90db457..2f96ad9 100644
--- a/shared/sx/templates/layout.sx
+++ b/shared/sx/templates/layout.sx
@@ -71,7 +71,7 @@
(h1 (or site-title ""))
(when app-label
(span :class "text-lg text-white/80 font-normal" app-label))))
- (nav :class "hidden md:flex gap-4 text-sm ml-2 justify-end items-center flex-0"
+ (nav :class "hidden md:flex flex-wrap gap-4 text-sm ml-2 justify-end items-center flex-0"
(when nav-tree nav-tree)
(when auth-menu auth-menu)
(when nav-panel nav-panel)
@@ -92,7 +92,7 @@
(<>
(div :id id
:sx-swap-oob (if oob "outerHTML" nil)
- :class (str "flex flex-col items-center md:flex-row justify-center md:justify-between w-full p-1 bg-" c "-" shade)
+ :class (str "flex flex-col items-center md:flex-row md:items-baseline justify-center md:justify-between w-full p-1 bg-" c "-" shade)
(div :class "relative nav-group"
(a :href link-href
:sx-get (if external nil link-href)
@@ -108,7 +108,7 @@
(when selected
(span :class "text-lg text-white/80 font-normal" selected))))))
(when nav
- (nav :class "hidden md:flex gap-4 text-sm ml-2 justify-end items-center flex-0"
+ (nav :class "hidden md:flex flex-wrap gap-4 text-sm ml-2 justify-end items-baseline flex-0"
nav)))
(when (and child-id (not oob))
(div :id child-id :class "flex flex-col w-full items-center"
diff --git a/sx/sx/essays.sx b/sx/sx/essays.sx
index b25cb59..e166399 100644
--- a/sx/sx/essays.sx
+++ b/sx/sx/essays.sx
@@ -1,7 +1,23 @@
;; Essay content — static content extracted from essays.py
+(defcomp ~essays-index-content ()
+ (~doc-page :title "Essays"
+ (div :class "space-y-4"
+ (p :class "text-lg text-stone-600 mb-4"
+ "Opinions, rationales, and explorations around SX and the ideas behind it.")
+ (div :class "space-y-3"
+ (map (fn (item)
+ (a :href (get item "href")
+ :sx-get (get item "href") :sx-target "#main-panel" :sx-select "#main-panel"
+ :sx-swap "outerHTML" :sx-push-url "true"
+ :class "block rounded border border-stone-200 p-4 hover:border-violet-300 hover:bg-violet-50 transition-colors"
+ (div :class "font-semibold text-stone-800" (get item "label"))
+ (when (get item "summary")
+ (p :class "text-sm text-stone-500 mt-1" (get item "summary")))))
+ essays-nav-items)))))
+
(defcomp ~essay-sx-sucks ()
- (~doc-page :title "sx sucks" (p :class "text-stone-500 text-sm italic mb-8" "In the grand tradition of " (a :href "https://htmx.org/essays/htmx-sucks/" :class "text-violet-600 hover:underline" "htmx sucks")) (~doc-section :title "The parentheses" :id "parens" (p :class "text-stone-600" "S-expressions are parentheses. Lots of parentheses. You thought LISP was dead? No, someone just decided to use it for HTML templates. Your IDE will need a parenthesis counter. Your code reviews will be 40% closing parens. Every merge conflict will be about whether a paren belongs on this line or the next.")) (~doc-section :title "Nobody asked for this" :id "nobody-asked" (p :class "text-stone-600" "The JavaScript ecosystem has React, Vue, Svelte, Solid, Qwik, and approximately 47,000 other frameworks. htmx proved you can skip them all. sx looked at this landscape and said: you know what this needs? A Lisp dialect. For HTML. Over HTTP.") (p :class "text-stone-600" "Nobody was asking for this. The zero GitHub stars confirm it. It is not even on GitHub.")) (~doc-section :title "The author has never written a line of LISP" :id "no-lisp" (p :class "text-stone-600" "The author of sx has never written a single line of actual LISP. Not Common Lisp. Not Scheme. Not Clojure. Not even Emacs Lisp. The entire s-expression evaluator was written by someone whose mental model of LISP comes from reading the first three chapters of SICP and then closing the tab.") (p :class "text-stone-600" "This is like building a sushi restaurant when your only experience with Japanese cuisine is eating supermarket California rolls.")) (~doc-section :title "AI wrote most of it" :id "ai" (p :class "text-stone-600" "A significant portion of sx — the evaluator, the parser, the primitives, the CSS scanner, this very documentation site — was written with AI assistance. The author typed prompts. Claude typed code. This is not artisanal hand-crafted software. This is the software equivalent of a microwave dinner presented on a nice plate.") (p :class "text-stone-600" "He adds features by typing stuff like \"is there rom for macros within sx.js? what benefits m,ight that bring?\", skim-reading the response, and then entering \"crack on then!\" This is not software engineering. This is improv comedy with a compiler.") (p :class "text-stone-600" "Is that bad? Maybe. Is it honest? Yes. Is this paragraph also AI-generated? You will never know.")) (~doc-section :title "No ecosystem" :id "ecosystem" (p :class "text-stone-600" "npm has 2 million packages. PyPI has 500,000. sx has zero packages, zero plugins, zero middleware, zero community, zero Stack Overflow answers, and zero conference talks. If you get stuck, your options are: read the source, or ask the one person who wrote it.") (p :class "text-stone-600" "That person is busy. Good luck.")) (~doc-section :title "Zero jobs" :id "jobs" (p :class "text-stone-600" "Adding sx to your CV will not get you hired. It will get you questioned.") (p :class "text-stone-600" "The interview will end shortly after.")) (~doc-section :title "The creator thinks s-expressions are a personality trait" :id "personality" (p :class "text-stone-600" "Look at this documentation site. It has a violet colour scheme. It has credits to htmx. It has a future possibilities page about hypothetical sx:// protocol schemes. The creator built an entire microservice — with Docker, Redis, and a custom entrypoint script — just to serve documentation about a rendering engine that runs one website.") (p :class "text-stone-600" "This is not engineering. This is a personality disorder expressed in YAML."))))
+ (~doc-page :title "sx sucks" (~doc-section :title "The parentheses" :id "parens" (p :class "text-stone-600" "S-expressions are parentheses. Lots of parentheses. You thought LISP was dead? No, someone just decided to use it for HTML templates. Your IDE will need a parenthesis counter. Your code reviews will be 40% closing parens. Every merge conflict will be about whether a paren belongs on this line or the next.")) (~doc-section :title "Nobody asked for this" :id "nobody-asked" (p :class "text-stone-600" "The JavaScript ecosystem has React, Vue, Svelte, Solid, Qwik, and approximately 47,000 other frameworks. htmx proved you can skip them all. sx looked at this landscape and said: you know what this needs? A Lisp dialect. For HTML. Over HTTP.") (p :class "text-stone-600" "Nobody was asking for this. The zero GitHub stars confirm it. It is not even on GitHub.")) (~doc-section :title "The author has never written a line of LISP" :id "no-lisp" (p :class "text-stone-600" "The author of sx has never written a single line of actual LISP. Not Common Lisp. Not Scheme. Not Clojure. Not even Emacs Lisp. The entire s-expression evaluator was written by someone whose mental model of LISP comes from reading the first three chapters of SICP and then closing the tab.") (p :class "text-stone-600" "This is like building a sushi restaurant when your only experience with Japanese cuisine is eating supermarket California rolls.")) (~doc-section :title "AI wrote most of it" :id "ai" (p :class "text-stone-600" "A significant portion of sx — the evaluator, the parser, the primitives, the CSS scanner, this very documentation site — was written with AI assistance. The author typed prompts. Claude typed code. This is not artisanal hand-crafted software. This is the software equivalent of a microwave dinner presented on a nice plate.") (p :class "text-stone-600" "He adds features by typing stuff like \"is there rom for macros within sx.js? what benefits m,ight that bring?\", skim-reading the response, and then entering \"crack on then!\" This is not software engineering. This is improv comedy with a compiler.") (p :class "text-stone-600" "Is that bad? Maybe. Is it honest? Yes. Is this paragraph also AI-generated? You will never know.")) (~doc-section :title "No ecosystem" :id "ecosystem" (p :class "text-stone-600" "npm has 2 million packages. PyPI has 500,000. sx has zero packages, zero plugins, zero middleware, zero community, zero Stack Overflow answers, and zero conference talks. If you get stuck, your options are: read the source, or ask the one person who wrote it.") (p :class "text-stone-600" "That person is busy. Good luck.")) (~doc-section :title "Zero jobs" :id "jobs" (p :class "text-stone-600" "Adding sx to your CV will not get you hired. It will get you questioned.") (p :class "text-stone-600" "The interview will end shortly after.")) (~doc-section :title "The creator thinks s-expressions are a personality trait" :id "personality" (p :class "text-stone-600" "Look at this documentation site. It has a violet colour scheme. It has credits to htmx. It has a future possibilities page about hypothetical sx:// protocol schemes. The creator built an entire microservice — with Docker, Redis, and a custom entrypoint script — just to serve documentation about a rendering engine that runs one website.") (p :class "text-stone-600" "This is not engineering. This is a personality disorder expressed in YAML."))))
(defcomp ~essay-why-sexps ()
(~doc-page :title "Why S-Expressions Over HTML Attributes" (~doc-section :title "The problem with HTML attributes" :id "problem" (p :class "text-stone-600" "HTML attributes are strings. You can put anything in a string. htmx puts DSLs in strings — trigger modifiers, swap strategies, CSS selectors. This works but it means you're parsing a language within a language within a language.") (p :class "text-stone-600" "S-expressions are already structured. Keywords are keywords. Lists are lists. Nested expressions nest naturally. There's no need to invent a trigger modifier syntax because the expression language already handles composition.")) (~doc-section :title "Components without a build step" :id "components" (p :class "text-stone-600" "React showed that components are the right abstraction for UI. The price: a build step, a bundler, JSX transpilation. With s-expressions, defcomp is just another form in the language. No transpiler needed. The same source runs on server and client.")) (~doc-section :title "When attributes are better" :id "better" (p :class "text-stone-600" "HTML attributes work in any HTML document. S-expressions need a runtime. If you want progressive enhancement that works with JS disabled, htmx is better. If you want to write HTML by hand in static files, htmx is better. sx only makes sense when you're already rendering server-side and want components."))))
diff --git a/sx/sx/layouts.sx b/sx/sx/layouts.sx
index e2c6917..fd983c9 100644
--- a/sx/sx/layouts.sx
+++ b/sx/sx/layouts.sx
@@ -11,8 +11,9 @@
(dict :label "Reference" :href "/reference/")
(dict :label "Protocols" :href "/protocols/wire-format")
(dict :label "Examples" :href "/examples/click-to-load")
- (dict :label "Essays" :href "/essays/sx-sucks")
- (dict :label "Specs" :href "/specs/"))))
+ (dict :label "Essays" :href "/essays/")
+ (dict :label "Specs" :href "/specs/")
+ (dict :label "Bootstrappers" :href "/bootstrappers/"))))
(<> (map (lambda (item)
(~nav-link
:href (get item "href")
diff --git a/sx/sx/nav-data.sx b/sx/sx/nav-data.sx
index 07b437b..635d66f 100644
--- a/sx/sx/nav-data.sx
+++ b/sx/sx/nav-data.sx
@@ -55,17 +55,28 @@
(dict :label "Retry" :href "/examples/retry")))
(define essays-nav-items (list
- (dict :label "sx sucks" :href "/essays/sx-sucks")
- (dict :label "Why S-Expressions" :href "/essays/why-sexps")
- (dict :label "The htmx/React Hybrid" :href "/essays/htmx-react-hybrid")
- (dict :label "On-Demand CSS" :href "/essays/on-demand-css")
- (dict :label "Client Reactivity" :href "/essays/client-reactivity")
- (dict :label "SX Native" :href "/essays/sx-native")
- (dict :label "The SX Manifesto" :href "/essays/sx-manifesto")
- (dict :label "Tail-Call Optimization" :href "/essays/tail-call-optimization")
- (dict :label "Continuations" :href "/essays/continuations")
- (dict :label "Godel, Escher, Bach" :href "/essays/godel-escher-bach")
- (dict :label "The Reflexive Web" :href "/essays/reflexive-web")))
+ (dict :label "Why S-Expressions" :href "/essays/why-sexps"
+ :summary "Why SX uses s-expressions instead of HTML templates, JSX, or any other syntax.")
+ (dict :label "The htmx/React Hybrid" :href "/essays/htmx-react-hybrid"
+ :summary "How SX combines the server-driven simplicity of htmx with the component model of React.")
+ (dict :label "On-Demand CSS" :href "/essays/on-demand-css"
+ :summary "The CSSX system: keyword atoms resolved to class names, CSS rules injected on first use.")
+ (dict :label "Client Reactivity" :href "/essays/client-reactivity"
+ :summary "Reactive UI updates without a virtual DOM, diffing library, or build step.")
+ (dict :label "SX Native" :href "/essays/sx-native"
+ :summary "Extending SX beyond the browser — native desktop and mobile rendering from the same source.")
+ (dict :label "The SX Manifesto" :href "/essays/sx-manifesto"
+ :summary "The design principles behind SX: simplicity, self-hosting, and s-expressions all the way down.")
+ (dict :label "Tail-Call Optimization" :href "/essays/tail-call-optimization"
+ :summary "How SX implements proper tail calls via trampolining in a language that doesn't have them.")
+ (dict :label "Continuations" :href "/essays/continuations"
+ :summary "First-class continuations in a tree-walking evaluator — theory and implementation.")
+ (dict :label "Godel, Escher, Bach" :href "/essays/godel-escher-bach"
+ :summary "Self-reference, strange loops, and what a self-hosting language has to do with GEB.")
+ (dict :label "The Reflexive Web" :href "/essays/reflexive-web"
+ :summary "A web where pages can inspect, modify, and extend their own rendering pipeline.")
+ (dict :label "sx sucks" :href "/essays/sx-sucks"
+ :summary "An honest accounting of everything wrong with SX and why you probably shouldn't use it.")))
(define specs-nav-items (list
(dict :label "Architecture" :href "/specs/")
@@ -78,26 +89,61 @@
(dict :label "DOM Adapter" :href "/specs/adapter-dom")
(dict :label "HTML Adapter" :href "/specs/adapter-html")
(dict :label "SX Wire Adapter" :href "/specs/adapter-sx")
+ (dict :label "Browser" :href "/specs/browser")
(dict :label "SxEngine" :href "/specs/engine")
- (dict :label "Orchestration" :href "/specs/orchestration")))
+ (dict :label "Orchestration" :href "/specs/orchestration")
+ (dict :label "Boot" :href "/specs/boot")
+ (dict :label "CSSX" :href "/specs/cssx")))
+
+(define bootstrappers-nav-items (list
+ (dict :label "Overview" :href "/bootstrappers/")
+ (dict :label "JavaScript" :href "/bootstrappers/javascript")))
;; Spec file registry — canonical metadata for spec viewer pages.
;; Python only handles file I/O (read-spec-file); all metadata lives here.
+;; The :prose field is an English-language description shown alongside the
+;; canonical s-expression source.
(define core-spec-items (list
- (dict :slug "parser" :filename "parser.sx" :title "Parser" :desc "Tokenization and parsing of SX source text into AST.")
- (dict :slug "evaluator" :filename "eval.sx" :title "Evaluator" :desc "Tree-walking evaluation of SX expressions.")
- (dict :slug "primitives" :filename "primitives.sx" :title "Primitives" :desc "All built-in pure functions and their signatures.")
- (dict :slug "renderer" :filename "render.sx" :title "Renderer" :desc "Shared rendering registries and utilities used by all adapters.")))
+ (dict :slug "parser" :filename "parser.sx" :title "Parser"
+ :desc "Tokenization and parsing of SX source text into AST."
+ :prose "The parser converts SX source text into an abstract syntax tree. It tokenizes the input into atoms, strings, numbers, keywords, and delimiters, then assembles them into nested list structures. The parser is intentionally minimal — s-expressions need very little syntax to parse. Special reader macros handle quasiquote (\\`), unquote (~), splice (~@), and the quote (') shorthand. The output is a tree of plain lists, symbols, keywords, strings, and numbers that the evaluator can walk directly.")
+ (dict :slug "evaluator" :filename "eval.sx" :title "Evaluator"
+ :desc "Tree-walking evaluation of SX expressions."
+ :prose "The evaluator walks the AST produced by the parser and reduces it to values. It implements lexical scoping with closures, special forms (define, let, if, cond, fn, defcomp, defmacro, quasiquote, set!, do), and function application. Macros are expanded at eval time. Component definitions (defcomp) create callable component objects that participate in the rendering pipeline. The evaluator delegates rendering expressions — HTML tags, components, fragments — to whichever adapter is active, making the same source renderable to DOM nodes, HTML strings, or SX wire format.")
+ (dict :slug "primitives" :filename "primitives.sx" :title "Primitives"
+ :desc "All built-in pure functions and their signatures."
+ :prose "Primitives are the built-in functions available in every SX environment. Each entry declares a name, parameter signature, and semantics. Bootstrap compilers implement these natively per target (JavaScript, Python, etc.). The registry covers arithmetic, comparison, string manipulation, list operations, dict operations, type predicates, and control flow helpers. All primitives are pure — they take values and return values with no side effects. Platform-specific operations (DOM access, HTTP, file I/O) are provided separately via platform bridge functions, not primitives.")
+ (dict :slug "renderer" :filename "render.sx" :title "Renderer"
+ :desc "Shared rendering registries and utilities used by all adapters."
+ :prose "The renderer defines what is renderable and how arguments are parsed, but not the output format. It maintains registries of known HTML tags, SVG tags, void elements, and boolean attributes. It specifies how keyword arguments on elements become HTML attributes, how children are collected, and how special attributes (class, style, data-*) are handled. All three adapters (DOM, HTML, SX wire) share these definitions so they agree on what constitutes valid markup. The renderer also defines the StyleValue type used by the CSSX on-demand CSS system.")))
(define adapter-spec-items (list
- (dict :slug "adapter-dom" :filename "adapter-dom.sx" :title "DOM Adapter" :desc "Renders SX expressions to live DOM nodes. Browser-only.")
- (dict :slug "adapter-html" :filename "adapter-html.sx" :title "HTML Adapter" :desc "Renders SX expressions to HTML strings. Server-side.")
- (dict :slug "adapter-sx" :filename "adapter-sx.sx" :title "SX Wire Adapter" :desc "Serializes SX for client-side rendering. Component calls stay unexpanded.")
- (dict :slug "engine" :filename "engine.sx" :title "SxEngine" :desc "Pure logic for fetch, swap, history, SSE, triggers, morph, and indicators.")
- (dict :slug "orchestration" :filename "orchestration.sx" :title "Orchestration" :desc "Browser wiring that binds engine logic to DOM events, fetch, and lifecycle.")))
+ (dict :slug "adapter-dom" :filename "adapter-dom.sx" :title "DOM Adapter"
+ :desc "Renders SX expressions to live DOM nodes. Browser-only."
+ :prose "The DOM adapter renders evaluated SX expressions into live browser DOM nodes — Elements, Text nodes, and DocumentFragments. It mirrors the HTML adapter's logic but produces DOM objects instead of strings. This is the adapter used by the browser-side SX runtime for initial mount, hydration, and dynamic updates. It handles element creation, attribute setting (including event handlers and style objects), SVG namespace handling, and fragment composition.")
+ (dict :slug "adapter-html" :filename "adapter-html.sx" :title "HTML Adapter"
+ :desc "Renders SX expressions to HTML strings. Server-side."
+ :prose "The HTML adapter renders evaluated SX expressions to HTML strings. It is used server-side to produce complete HTML pages and fragments. It handles void elements (self-closing tags like
,
), boolean attributes, style serialization, class merging, and proper escaping. The output is standard HTML5 that any browser can parse.")
+ (dict :slug "adapter-sx" :filename "adapter-sx.sx" :title "SX Wire Adapter"
+ :desc "Serializes SX for client-side rendering. Component calls stay unexpanded."
+ :prose "The SX wire adapter serializes expressions as SX source text for transmission to the browser, where sx.js renders them client-side. Unlike the HTML adapter, component calls (~name ...) are NOT expanded — they are sent to the client as-is, allowing the browser to render them with its local component registry. HTML tags ARE serialized as s-expression source. This is the format used for SX-over-HTTP responses and the page boot payload.")
+ (dict :slug "engine" :filename "engine.sx" :title "SxEngine"
+ :desc "Pure logic for fetch, swap, history, SSE, triggers, morph, and indicators."
+ :prose "The engine specifies the pure logic of the browser-side fetch/swap/history system. Like HTMX but native to SX. It defines trigger parsing (click, submit, intersect, poll, load, revealed), swap algorithms (innerHTML, outerHTML, morph, beforebegin, etc.), the morph/diff algorithm for patching existing DOM, history management (push-url, replace-url, popstate), out-of-band swap identification, Server-Sent Events parsing, retry logic with exponential backoff, request header building, response header processing, and optimistic UI updates. This file contains no browser API calls — all platform interaction is in orchestration.sx.")
+ (dict :slug "orchestration" :filename "orchestration.sx" :title "Orchestration"
+ :desc "Browser wiring that binds engine logic to DOM events, fetch, and lifecycle."
+ :prose "Orchestration is the browser wiring layer. It binds the pure engine logic to actual browser APIs: DOM event listeners, fetch(), AbortController, setTimeout/setInterval, IntersectionObserver, history.pushState, and EventSource (SSE). It implements the full request lifecycle — from trigger through fetch through swap — including CSS tracking, response type detection (SX vs HTML), OOB swap processing, script activation, element boosting, and preload. Dependency is strictly one-way: orchestration depends on engine, never the reverse.")))
-(define all-spec-items (concat core-spec-items adapter-spec-items))
+(define browser-spec-items (list
+ (dict :slug "boot" :filename "boot.sx" :title "Boot"
+ :desc "Browser startup lifecycle: mount, hydrate, script processing."
+ :prose "Boot handles the browser startup sequence and provides the public API for mounting SX content. On page load it: (1) initializes CSS tracking, (2) loads the style dictionary from inline JSON, (3) processes