Suppose the application is a small, strange machine: a Lisp-flavored authoring layer over JavaScript, running in an iPhone browser, sheltered by a service worker, decorated by a WebGL side-channel, and asked to preserve human work across interruption. Then the architecture should be stated without shame. The shell must be distinct from the data, the cache distinct from the truth, the compiled behavior distinct from the prose that authored it, and the ornament distinct from the meaning. Once those distinctions are held cleanly, the stack stops being a makeshift trick and becomes a maintainable instrument.
The correct explanation begins with a refusal: do not describe the system by framework names or by developer mood. Describe it by the transitions the operator depends on. A request arrives. A shell appears. A versioned worker mediates assets. A durable local state is restored. Authored forms become inspectable behavior. Meaning is rendered in the DOM. Optional GPU light is added. Checkpoints are written. Re-entry remains possible. If each transition is clean, the application is trustworthy. If any transition is muddled, the application becomes a rumor sustained by luck.
A visible page is not yet a ready tool. The shell may be present while the worker is stale, the state invalid, or the compiler still loading its forms. Therefore readiness must be earned, not assumed from first paint.
The worker has authority over asset versioning, not domain truth. Local persistence has authority over resumable drafts, not canonical records. The compiler has authority over behavior generation, not business meaning. Most bugs in clever browser software are not logic errors but confused authorities.
A Lisp layer over JavaScript is justified only if it makes repeated patterns smaller while leaving generated behavior inspectable. The maintainer must still be able to trace event to state transition to render effect without joining a priesthood.
That layer is the DOM. CSS may refine it. WebGL may deepen it. But the canonical visible meaning should survive when animation is reduced, when the GPU path fails, and when the tab resumes in a half-awake state. Reliability prefers survivable substrates.
The phone sleeps. Memory is pressured. Networks fade. New shells arrive. Storage schemas evolve. A serious browser application is therefore a re-entry machine: it can explain its current version, migrate a saved draft once, rebind event handlers cleanly, and continue without pretending the interruption never happened.
The architecture is simple once spoken plainly: boot is not restore, restore is not compile, compile is not render, render is not ornament, and none of them are persistence. The machine becomes reliable when these acts are performed in order and never allowed to counterfeit one another.
The initial document should explain version, required assets, and pending recovery work. Footgun: treating first paint as full readiness. Defense: publish a distinct ready state after restore and bind complete.
Let it version assets, serve offline, and announce upgrades. Footgun: sneaking business logic into the worker until it becomes a second application. Defense: keep worker responsibilities narrow and inspectable.
Validate schema, migrate once, and only then let the interface speak authoritatively. Footgun: rendering stale or unversioned payloads as if they were current truth. Defense: explicit migration and invalidation paths.
The authored layer should collapse repetition, not obscure control flow. Footgun: macro cleverness that hides lifecycle edges. Defense: stable intermediate output, named hooks, and grep-friendly generated code.
The interface should remain readable with animation off and GPU absent. Footgun: binding core truth to visual flourish. Defense: keep DOM text and controls authoritative, with enhancement layered on top.
Shaders may visualize rhythm, latency, or touch. Footgun: moving state meaning into the canvas because the effect is seductive. Defense: ensure the GPU path can disappear without destroying comprehension.
Cache Storage for shell assets, IndexedDB for real payloads, localStorage only for tiny session hints. Footgun: one blob to rule them all. Defense: separate stores, versioned payloads, reset/export paths, and timestamps.
New code should announce itself, checkpoint local work, and swap by consent or at a deliberate quiet point. Footgun: surprise refresh during active work. Defense: visible update state and resumable reload.
A wise engineer assumes the browser will do exactly what browsers do: cache too well, suspend at bad moments, preserve ambiguous state, flatter ornamental code, and make partial success look like total success. The defense is not paranoia. It is specific structure.
Defense: immutable asset names, explicit worker version display, and an upgrade banner that stages reload instead of springing it.
Defense: version every payload, migrate once, and give the operator visible reset and export controls rather than silent corruption.
Defense: capability checks, pause paths, reduced-motion respect, and a rule that canonical text never lives only in the GPU path.
Defense: idempotent restore, rebind-on-resume, and UI language that tells the operator exactly what was recovered and what needs revalidation.
Defense: checkpoint before swap, defer reload during active editing, and expose "new build available" as a state instead of detonating the page.
Defense: deterministic generated output, one stable vocabulary for lifecycle events, and traces that map authored forms back to emitted behavior.
A maintainable stack is easier to keep when its obligations can be written as a contract. Not framework law, just a small set of promises the code can be checked against.
The first screen may announce version and pending recovery work, but it must not imply trusted state before restore and validation complete.
The same saved payload should produce the same resumed state, and a second restore pass should not duplicate handlers, records, or effects.
The authored layer may compress repetition, but emitted runtime behavior must preserve stable names for lifecycle, events, and state transitions.
If a human cannot recover the core state from the DOM alone, too much authority has drifted into style, shader, or hidden in-memory structures.
GPU effects, network sync, and live reload improve the tool when present, but their absence should degrade atmosphere or convenience, not truth.
A new build stages itself, checkpoints local work, and offers a clean re-entry. It never silently rewrites the operator's current world.
The essay above states the architecture. This drill tests whether its discipline survives contact with temptation.
{
"project_name": "landings",
"repo_path": "/Users/uprootiny/landings",
"git_remote": "https://github.com/uprootiny/landings.git",
"git_branch": "main",
"git_commit": "40cd78c86a3dcc64bde687541081cd7d074a5fa8",
"generated_at": "2026-05-17T07:55:22+03:00",
"generator": "OpenAI Codex GPT-5",
"session_source": "codex",
"session_locator": "/Users/uprootiny/.codex/sessions/2026/05",
"artifact_path": "heedless-siblings/index.html"
}