04 — Architecture

Summary

The page as engineering: seven JS files with one-line jobs, six custom elements that are seams rather than boundaries (no shadow DOM — the site's stylesheet should reach in), bubbling CustomEvents up and state down through a single owner in app.js, and a hand-rolled SVG renderer because a chart library is a third-party request. store.js handles storage's three failure modes explicitly, including the opaque-origin case a downloaded copy hits. The v1 lesson stands behind the layout: one large HTML page with everything inline was named in the correction memo, and the v2 split is what made design changes reviewable as diffs of one file.

Key concepts

• Events up, state down — every v1 inert-click symptom traced to state living in more than one place
• Same-origin as architecture — the network panel after a full pass shows only this site — checked every release
• Two views, one graph — the scene for recognition, the DAG for structure

Key ideas

• A new section is a new component with its own events — never a script block in the page.
• A capability that needs a server is a different page with its own disclosure, not an upgrade to this one.
• model.js stays DOM-free, or the test harness goes blind.

Read the document