ADR 0002: Content compiles into page projections

Context

Pre sites need dynamic content, nested wildcard routes, machine-readable output, and future Har-backed source control without duplicating page implementations.

Decision

Canonical Markdown is compiled on the server into a versioned PageDocument JSON projection. One catch-all renderer displays all routes.

The projection contains resolved presentation class strings, but content may select only trusted semantic theme names. Arbitrary Tailwind input is not accepted from stored records.

pre.page.v1 is a real contract: the published JSON Schema must describe the TypeScript representation closely enough that every canonical compiled projection validates against it during content:check.

A schema-valid PageDocument is necessary but not sufficient for trust. Render-authoritative presentation and future capability references must originate from, or be re-resolved by, a trusted server projection boundary. Har may replace the filesystem as a SourceRecord provider without becoming a bypass around compilation and publication policy.

Publication is explicit and fail-closed. Only the exact canonical value visibility: "public" may produce public HTML metadata, body content, JSON, Markdown, or navigation entries.

Navigation is also a projection of content relationships rather than route-specific React. Primary and grouped secondary placement are resolved from metadata into NavigationItem records. Public content is discoverable by default; an intentionally unlinked public route must explicitly declare discoverable: false. CI verifies that every other discoverable public content route is reachable from / through projected navigation or public internal links.

Consequences

• Humans and agents can read the same source through Markdown, JSON, or HTML.
• The renderer remains independent of filesystem or Har storage.
• Design systems can change by replacing trusted theme resolution.
• The Markdown subset remains intentionally bounded and non-executable.
• Missing or invalid visibility fails validation instead of publishing or silently choosing a visibility state.
• Schema drift between TypeScript, generated projections, and the published machine contract is caught before merge.
• The visible navigation can remain compact without allowing public reference pages to become accidental orphans.