soul.demarkus.io:6309/demarkus-library/adr/0003-htmx-ssr-philosophy.md/v10 draft reader meta

ADR 0003 — SSR-first, htmx-hard, no JSON

promoted-via: knowledge promoted: mark://latebit/projects/demarkus-library/adr/0003-htmx-ssr-philosophy.md@v1

Status: accepted (2026-06-10). The load-bearing front-end principle for demarkus-library. Deliberately strict: we are pushing the hypermedia approach as far as it goes and treating every escape hatch as a tracked concession.

Decision

The application is hypermedia-driven (HATEOAS). The server renders HTML; htmx is the only general interaction layer; there is no JSON API and no client-side application state. This is not "SSR with some htmx" — it is htmx-hard: the default answer to any interaction is "return server-rendered HTML and swap it in."

The rules (hard)

  1. The server owns all rendering. Every response is HTML — a full page or a fragment built by html/template. The browser receives finished markup, never data to assemble. goldmark→bluemonday→template is the only render path.
  2. No JSON tier, ever. Handlers return HTML via c.Render/c.HTML, never c.JSON. No REST/JSON projection, no GraphQL, no serialized view models crossing the wire. (Health check returns plain text; that's the lone non-HTML response and it's not application data.)
  3. No client-side state. Application state lives on the server (session + the world). The DOM is the only client state, and the server is its source of truth. No stores, no client router, no reactivity layer.
  4. Interactivity is hx-* attributes. Navigation (hx-boost), search (hx-get debounced), version/panel swaps, pagination, forms (hx-post → PUBLISH) — all are htmx returning server-rendered fragments into a target. Reach for an attribute before a line of JS.
  5. Self-hosted assets. htmx is vendored in-repo and served from the Go binary (/static/htmx.min.js, pinned to the latest htmx — currently 4.0.0) — not a CDN. Single binary, no runtime dependency, no third-party origin, version pinned and reviewable. Keep it current: bump to the latest htmx release as they ship. (Embodied 2026-06-10.)
  6. Fragments are first-class. Templates are factored so the inner content block can render standalone (for an htmx swap) or inside the page chrome (full load). A fragment request and a full navigation hit the same handler and the same template — no duplicate rendering paths.
  7. Degrade without JS. Because the server renders every route in full, hx-boost navigation and form posts work with JS disabled. htmx is enhancement, never the renderer. Keep it that way: no interaction may be only reachable through htmx.

How far we push it (the experiment)

We will attempt the entire app as hypermedia before admitting any island:

  • Catalog search (LOOKUP): debounced hx-get, results as an HTML <table> to click through. No JSON, no client filtering.
  • Editions (VERSIONS) + citations (backlinks): fragment swaps into a panel.
  • The cataloging desk (writes): form hx-post → PUBLISH; live preview via hx-post to a server render endpoint that returns rendered HTML — the server previews, not a client markdown lib.
  • The AI librarian (Phase 4): streaming via SSE (htmx 4 first-party hx-sse) — a token stream and a live tool-call trace, still server-driven HTML over the wire.

JS islands — last resort, tracked

A real island (custom JS beyond htmx + its official extensions) is allowed ONLY when hypermedia genuinely cannot do the job, and each one is recorded as a concession in this ADR with the reason. Pre-agreed candidates from the plan:

  • CodeMirror — the editor textarea needs real code-editing affordances (Phase 3).
  • Canvas graph — force-directed citation graph (post-v1).

Anything else must clear the bar: "this interaction is impossible or unacceptable as server HTML + htmx." Prefer an htmx extension or a tiny _hyperscript snippet over bespoke JS before conceding an island. No island is added silently — it gets a line here and a log/comment at the site.

Conceded islands

  • mermaid (2026-06-12) — diagram rendering is client-side by nature (the server cannot rasterize mermaid without a headless browser, which is a far larger concession). Vendored mermaid.min.js 11.15.0; loaded lazily by islands.js only when a page contains a language-mermaid block; degrades to the readable source code block; render failure restores the source block.
  • KaTeX (2026-06-12) — math typesetting; same server-side rasterization argument. Vendored 0.17.0 (js + auto-render + css + woff2 fonts); loaded lazily on delimiter presence (\(…\) inline, $$…$$/\[…\] display — single-$ deliberately unsupported, dollar-amount false positives); degrades to readable TeX source. trust: false, throwOnError: false.
  • Both islands ride one tiny loader (/static/islands.js) that re-scans on htmx:after:settle so fragment swaps keep working. Server side, math is shielded from markdown by the goldmark passthrough extension; bluemonday still sanitizes everything (islands render from text content, never raw HTML).

Consequences

  • No Node build, no bundler, no SPA framework — fits demarkus's single-Go-binary ethos and makes Phase 5's shareable, server-rendered links free.
  • The win is conceptual surface area: one rendering path, one source of truth, no client/server state sync. The risk is hitting an interaction htmx strains on — the island rule is the pressure valve, kept deliberately narrow so we actually learn where the ceiling is.
  • .coderabbit.yaml enforces this on the web adapter: flag any c.JSON, any client-side framework, any CDN asset reference, any island added without an ADR line.

Vendored asset versions

  • htmx 2.0.10 (2026-06-10) — current latest; initial vendor. (Briefly 2.0.4 the same day before bumping to latest.)
  • mermaid 11.15.0 (2026-06-12) — islands concession above.
  • KaTeX 0.17.0 (2026-06-12) — islands concession above; woff2 fonts only (modern-browser format; the css's woff/ttf fallbacks 404 by design).

Conceded islands — Phase 4 (2026-07-03)

  • htmx SSE extension (sse.min.js 2.2.4, vendored + pinned beside htmx) — the pre-agreed streaming-librarian spend named in this ADR's experiment list. Declarative attributes only (sse-connect/sse-swap/ sse-close): the librarian pane's live answers stream trace/token/ rendered/done frames of server-rendered content into hx-swap targets — no hand-written EventSource code. Degrades: the ask form is a real POST that runs the ask server-side and PRG-redirects to the finished answer; SSE is enhancement, never the renderer.
  • Pane click-engagement toggle (2026-07-03, islands.js) — clicking into a pane moves the visual attention marker (an .engaged class) without touching the URL focus (which owns layout + the live read; re-focusing collapses panes and reads as navigation). Presentational-only: no fetch, no URL change, no client state, reset by the next server render — the same register as the graph hover-highlight. htmx attributes cannot express click-scoped CSS toggling; without JS the server-truth focus marker stands.

Related non-island notes: the reader-overlay Esc handler, palette glue, and overlay summon/dismiss already ride islands.js under ADR 0005/0006 grants; the transcript's bottom-anchored chat scroll is pure CSS (column-reverse), deliberately NOT an island.

Vendored asset versions (continued)

  • htmx-ext-sse 2.2.4 (2026-07-02) — SSE island above.

htmx 4 upgrade (2026-09-09)

  • htmx 4.0.0 (released 2026-08-28; npm tag next, latest stays 2.x until early 2027) replaces 2.0.10. Vendored dist/htmx.min.js; the SSE extension is now first-party (dist/ext/hx-sse.min.js, vendored as /static/hx-sse.min.js, replaces htmx-ext-sse 2.2.4). Extensions load by script inclusion; hx-ext is gone.
  • Inheritance is explicit: <body hx-boost:inherited="true">; child hx-boost="false" still wins (own attribute checked first).
  • History has no DOM cache: back/forward re-fetch the URL with HX-Request: true + HX-History-Restore-Request: true (no HX-Boosted) and swap the body. wantsFragment in reading_handlers.go treats that as a full-page request; without it the back button swapped a bare fragment into the body.
  • SSE vocabulary rewired: htmx 4 swaps only unnamed SSE frames; named events become DOM events (sse-swap removed). trace/token/rendered now go out unnamed as <hx-partial hx-target="find .ask-…" hx-swap="…"> (targets resolve relative to the connecting block, so no ids); answer/done stay named, hx-sse:close="done" closes. See sseFrame in librarian_stream.go.
  • Error responses swap by default in 4; kept the htmx 2 rule via <meta name="htmx-config" content='{"noSwap":[204,304,"4xx","5xx"]}'> because Echo's default error body is JSON. Follow-up: render HTML error fragments, then drop the meta and let 4xx/5xx swap.
  • Events renamed: islands.js listens for htmx:after:settle (on document); hx-on::after-request became hx-on::after:request.
  • 60s default request timeout is new; hx-sse clears it once the stream responds, so long answers are unaffected.
  • htmx.ajax("GET", url, "#selector") still valid; next <selector> targets, delay:/once/changed triggers, hx-headers JSON, HX-Request/HX-Boosted/HX-Current-URL/HX-Redirect all unchanged.
  • Official checker: npx htmx.org@4.0.0 upgrade-check -- ./internal/adapter/inbound/web/templates. Its edit.html hx-headers warning is a false positive (the header sits on the requesting textarea itself).

htmx 4 upgrade, live-test corrections (2026-09-09)

  • Error handling moved off the htmx-config meta: noSwap short-circuits before hx-status, and a boosted 404 click still pushed the URL. Now every body carries {{template "hx-body"}} (page.html): hx-boost:inherited="true" hx-status:4xx:inherited="swap:none push:false" hx-status:5xx:inherited="swap:none push:false". Verified in Chrome: 404 link leaves URL and panes untouched, no JSON in body.
  • Verified end to end with Playwright against Google Chrome (channel: 'chrome', no Chrome extension needed): boosted nav sends HX-Boosted, back sends HX-History-Restore-Request and gets the full page without reload, preview cards, ⌃K palette, librarian SSE (hx-partial frames swap <p>pong</p>, hx-on::after:request resets the form).
  • Pre-existing, NOT a regression: document-body links wrapped by the hover preview carry hx-get on the <a> itself, so neither htmx 2 nor 4 boosts them (a click is a full page load). Fix candidate: move the preview attributes onto the .preview-host span (hx-trigger="mouseenter delay:300ms once", hx-target="find .preview-card") so the anchor stays boostable.
  • Drive scripts live in the session scratchpad (pw/drive.js, compare.js, status.js); worth turning into a project run skill.
trail
  1. soul.demarkus.io:6309 v10