Static-First Explorable Essays

Question

How should a technical article carry long-form prose and interactive figures without making every paragraph depend on runtime JavaScript? The platform blueprint answers with a static-first rule¹: ship the article as HTML, then hydrate only the figures that need state.

Local Model

The working model has five layers. MDX owns the content. Astro owns the publication shell. React islands own interactive figures. Data artifacts feed those figures before build time. Tests, Storybook states, browser checks, and scaffold validation prove that the page still renders.

Mechanism

Each essay folder contains the article, configuration, data, assets, and figure code. That keeps the local proof close to the claim: pure model logic gets unit tests, visual states get Storybook, and rendered pages get Playwright coverage.

Proof Ladder

This article now carries its first article-owned data artifact: a checked-in proof ladder derived from the platform blueprint. It names the owner and gate for each layer before future figures add runtime state.

Proof Flow

The first dedicated article figure reads the same proof-ladder data instead of copying a second diagram by hand. The SVG and gate list are static output, so the article gains a figure without adding hydration work.

Gate Inspector

The first stateful figure keeps the same data boundary. It hydrates only the inspector, then lets the reader switch proof layers while the owner, claim, and gate still come from the checked-in ladder.

Scrollytelling Primitive

The scrollytelling proof follows the blueprint’s minimal model: an Astro wrapper hydrates one small React island, the active step comes from fixed article-owned data IDs, and the route keeps a useful static first render before the observer updates. The island now passes that active step into one child figure through props, proving the first child-context boundary without adding a registry.

Cross-article scrollytelling registries are explicitly vetoed: No cross-article scrollytelling registry is accepted for this static-first route until a registry contract, article ownership model, and repeated-article choreography need are source-registered and proven.

General child-figure choreography frameworks are explicitly vetoed: No general child-figure choreography framework is accepted for this static-first route until repeated child-figure needs, a state ownership contract, and a testing strategy are source-registered and proven.

Scroll Analytics

The first scroll analytics boundary stays local to the page. When the active Scrolly step changes, the island dispatches a scrolly:step-change event whose detail contains only the artifact ID, source ID, active step ID, target ID, and trigger. The same island reduces those events into scrolly:step-aggregate session counts keyed by fixed step IDs and triggers. A route-level boundary listens for that aggregate and emits a local route:analytics-summary event with the route ID, source ID, last artifact, active step, and fixed artifact totals. A first transport adapter can queue the Scrolly aggregate through a same-origin navigator.sendBeacon endpoint when one is passed in, but this published route leaves the endpoint unconfigured. The live collector boundary is explicitly vetoed until a collector runtime is source-registered and proven. Persistent reader tracking is explicitly vetoed until reader identity, storage, retention, and consent boundaries are source-registered and proven. The third-party provider boundary is also explicitly vetoed: no provider SDK, remote script, provider project ID, cross-origin collection endpoint, cookie, fingerprint, persistent reader identity, dashboard, retention, or delivery guarantee is accepted. Cross-article analytics registries are explicitly vetoed until a registry contract, ownership model, and collector boundary are source-registered and proven.

Event

scrolly:step-change

Payload

Fixed article IDs only

Aggregation

In-memory session counts

Transport

Optional same-origin Beacon adapter, endpoint not configured

Route Summary

route:analytics-summary with local route totals

Collector

No live analytics collector is accepted for this static-first route until a source-registered runtime endpoint exists.

Reader Tracking

No persistent reader tracking is accepted for this static-first route until reader identity, storage, retention, and consent boundaries are source-registered and proven.

Provider

No third-party analytics provider is accepted for this static-first route until a provider, data contract, and privacy boundary are source-registered and proven.

Registry

No cross-article analytics registry is accepted for this static-first route until a registry contract, ownership model, and collector boundary are source-registered and proven.

Not Claimed

No live collector, third-party provider, provider SDK, persistent reader tracking, cross-article analytics registry, global analytics artifact map, or shared analytics event bus

Generated Data

The article now has its first generated data pipeline. A deterministic script reads the checked-in proof ladder, emits a generated gate summary, and exposes a check mode so stale data fails before the article builds.

Visual Baseline

The first visual-regression proof is local and article-owned. Playwright now snapshots the static proof-flow figure and one hydrated gate-inspector state, so layout drift in either proof surface has a committed baseline to compare against.

CI Proof

The first CI proof keeps local screenshot baselines and post-deploy live checks out of the Ubuntu smoke gate, then runs a separate browser command for the static-first route. GitHub Actions now checks generated data drift, unit tests, typecheck, build, Storybook, audit, and CI-safe Playwright coverage before accepting the app gates.

Live Deployment

The first live deployment proof checks the production Cloudflare Pages route at tutorials-e4t.pages.dev. The live probe verifies that the static-first route returns HTML, carries this proof marker, renders the static proof-flow figure, and hydrates the gate-inspector island.

Provider

Cloudflare Pages

Route

/essays/static-first-explorable-essays/

Probe

tests/static-first-live.spec.ts

Preview Deployment

The first preview deployment proof targets a non-production Cloudflare Pages branch alias with PREVIEW_BASE_URL. The preview probe verifies that the static-first route returns HTML, carries this preview marker, sends the preview X-Robots-Tag: noindex header, renders the static proof-flow figure, and hydrates the gate-inspector island.

Provider

Cloudflare Pages preview

Route

/essays/static-first-explorable-essays/

Probe

tests/static-first-preview.spec.ts

Rollback Proof

The first rollback proof records the Cloudflare Pages boundary and the credentialed mutation: rollback targets must be successful production deployments, and preview deployments are not valid rollback targets. The mutation runner used a redacted credential preflight, rolled production back to a named successful deployment, then restored production to the starting deployment after the live probes passed.

Provider

Cloudflare Pages production rollback

Route

/essays/static-first-explorable-essays/

Probe

tests/static-first-rollback.spec.ts

Runner

scripts/cloudflare_pages_rollback_mutation.py

Preflight

npm run deployment:rollback:check-config

Mutation status

Accepted credentialed proof. Future runs still require CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and CLOUDFLARE_PAGES_PROJECT before mutating production.

Proof artifacts

artifacts/proofs/tut-026-cloudflare-*.json

Custom-Domain Deployment

The first custom-domain deployment boundary is an explicit veto. No custom-domain deployment guarantee is accepted for this static-first route until a domain name, DNS ownership, custom hostname binding, certificate behavior, Pages production-domain mapping, and focused live checks are source-registered and proven.

Decision

explicit_veto

Accepted

The published route keeps the accepted Cloudflare Pages production, preview, rollback, and credentialed rollback mutation proofs unchanged.

Not Claimed

No DNS record, zone ownership, custom hostname binding, certificate issuance, Pages production-domain mapping, apex or www redirect, HSTS policy, or SSL mode is claimed.

Next Proof

Source-register the target domain, DNS and hostname contract, certificate behavior, Pages binding, redirect policy, and focused live checks before claiming custom-domain deployment.

Math Rendering

The first math proof keeps TeX source in article-owned data and renders it with KaTeX during the static build. The route gets HTML and MathML before any figure island hydrates.

MDX Math Parser

The parser proof leaves one source-backed expression in MDX instead of importing the static math component. Astro passes the syntax through remark-math and rehype-katex, then the static route receives KaTeX HTML and MathML.

This boundary proves the shared MDX parser path only. It does not introduce a custom compiler, shared macro system, or cross-article math registry.

Math Macros

The first shared macro proof is limited to two KaTeX rendering-option macros in the Astro MDX pipeline. They shorten repeated platform terms while keeping author-defined macro state, custom compilers, and cross-article registries out of scope.

Cross-article macro registries are explicitly vetoed: No cross-article macro registry is accepted for this static-first route until a registry contract, macro ownership model, author override policy, collision strategy, and renderer test strategy are source-registered and proven.

Author-defined macro state is explicitly vetoed: No author-defined macro state is accepted for this static-first route until an author macro model, ownership boundary, override policy, collision strategy, renderer strategy, and focused tests are source-registered and proven.

Custom math compilers are explicitly vetoed: No custom math compiler is accepted for this static-first route until a compiler contract, MDX compatibility boundary, renderer strategy, authoring syntax, migration plan, and focused tests are source-registered and proven.

Macros

\StaticRoute, \HydratedIsland

Renderer

rehype-katex with KaTeX macros

Source

blueprint-001

Gate

Vitest and Playwright verify static KaTeX HTML, MathML, and the macro source annotation.

Registry Boundary

The published route keeps the existing shared KaTeX macro map frozen in Astro config for two blueprint-backed platform terms.

State Boundary

The Math Macros section renders one source-backed MDX expression without reading author-owned macro definitions, route state, browser storage, or external macro files.

Compiler Boundary

The published route keeps math rendering on the existing Astro MDX pipeline with remark-math, rehype-katex, and the frozen shared KaTeX macro map.

Not Claimed

No cross-article macro registry, global macro catalog, route-fed macro map, author-defined macro storage, macro import protocol, or macro collision resolution policy is introduced.

State Not Claimed

No author-defined macro storage, per-article override map, mutable macro registry, macro import block, macro collision policy, or browser-persisted macro state is introduced.

Compiler Not Claimed

No custom math compiler, custom markdown dialect, Mathigon-like compiler layer, MDX replacement parser, or compiler-owned authoring syntax is introduced.

Next Proof

Source-register an author macro model, ownership boundary, override and collision policy, renderer strategy, and focused tests before accepting author-defined macros.

Compiler Next Proof

Source-register a compiler contract, authoring syntax, MDX compatibility boundary, renderer strategy, migration plan, and focused tests before accepting a custom math compiler.

Code Blocks

The first code-block proof is article-owned data. It keeps technical examples inside the essay folder, attaches the source registry boundary, renders through Astro’s Shiki-backed code highlighter as static HTML, and passes the same source text into one shared copy control. Cross-article code registries are explicitly vetoed: No cross-article code registry is accepted for this static-first route until a registry contract, code ownership model, language and highlighter policy, copy-control boundary, and focused tests are source-registered and proven. Broad clipboard guarantees are explicitly vetoed: No broad clipboard guarantee is accepted for this static-first route until a clipboard contract, permission model, browser support matrix, fallback path, and focused tests are source-registered and proven. A general copy-control framework is explicitly vetoed: No general copy-control framework is accepted for this static-first route until repeated article needs, a copy ownership model, accessibility copy, support and fallback policy, delivery contract, and focused tests are source-registered and proven. A custom syntax-highlighting framework is explicitly vetoed: No custom syntax-highlighting framework is accepted for this static-first route until repeated article needs, a language and highlighter policy, theme ownership, renderer contract, accessibility checks, and focused tests are source-registered and proven.

Registry Boundary

The published route keeps code examples in this article's checked-in data artifact.

Not Claimed

No cross-article code registry, global code-snippet catalog, route-fed code map, code import protocol, or cross-route code dedupe layer is introduced.

Next Proof

Source-register a second article need, code ownership model, registry contract, language and highlighter policy, copy-control boundary, and focused tests before enabling a shared code registry.

Copy Boundary

The published route keeps the shared copy control limited to one user-click write from article-owned source text.

Clipboard Not Claimed

No background clipboard write, automatic copy, read access, browser-wide permission guarantee, cross-browser support guarantee, or clipboard history behavior is introduced.

Clipboard Next Proof

Source-register a browser clipboard contract, permission and user-activation model, support matrix, fallback behavior, accessibility copy, and focused tests before claiming a broad clipboard guarantee.

Framework Boundary

The published route keeps copy-control behavior in one shared Astro component that receives article-owned source text through props.

Framework Not Claimed

No general copy abstraction, copy provider, global copy registry, fallback command layer, support matrix, telemetry, delivery guarantee, or cross-article copy workflow is introduced.

Framework Next Proof

Source-register repeated article needs, a copy ownership model, accessibility copy, support and fallback policy, delivery contract, and focused tests before claiming a general copy-control framework.

Highlighter Boundary

The published route keeps syntax highlighting on the existing Astro Code component and Shiki output for one article-owned code block.

Highlighter Not Claimed

No custom highlighter runtime, custom markdown dialect, code transform framework, theme registry, language plugin registry, or framework-owned renderer contract is introduced.

Highlighter Next Proof

Source-register repeated article needs, a language and highlighter policy, theme ownership model, renderer contract, accessibility checks, and focused tests before claiming a custom syntax-highlighting framework.

export const articleCodeBlockProof = {
  sourceId: "blueprint-001",
  artifact: "./data/code-blocks.json",
  gate: "Vitest + Playwright + build"
} as const;

Appendix

The first appendix proof is article-owned data. It keeps extended material inside the essay folder, names the same source registry boundary, and stays compact enough to render as static HTML.

A general appendix framework is explicitly vetoed here. The route keeps this appendix inside article-owned data and rejects cross-article appendix registries, shared extended-material models, registry-owned ordering, backlink systems, remote appendix fetches, custom markdown dialects, and generalized footnote, glossary, and appendix bundles until their ownership, ordering, renderer, registry, and focused-test boundaries are source-registered and proven.

Glossary

The first glossary proof is article-owned data. It defines the platform terms that recur across prose, figures, and gates without adding a global terminology system.

Article-owned data artifact

A lightweight JSON, CSV, or asset file that lives inside one essay folder and feeds that essay's prose, figures, or verification gates.

Source blueprint-001, BLUEPRINT.md sections 5, 6, and 7. Gate: Vitest validates this glossary artifact, and Playwright verifies the rendered term list.

Island hydration

The pattern where the article ships as static HTML, then hydrates only the interactive React components that need browser state.

Source blueprint-001, BLUEPRINT.md sections 3 and 5. Gate: The static-first browser smoke keeps the rendered glossary and hydrated figure boundary on the same route.

Static-first essay

A long-form technical article that renders prose and source-backed structure as HTML before adding optional hydrated figures.

Source blueprint-001, BLUEPRINT.md sections 2 and 5. Gate: The scaffold validator keeps the article folder contract registered beside this glossary proof.

Cross-article glossary frameworks are explicitly vetoed here: No cross-article glossary framework is accepted for this static-first route until repeated article needs, term ownership, slug and reference rules, renderer behavior, registry boundaries, and focused tests are source-registered and proven. A general glossary framework is explicitly vetoed here: No general glossary framework is accepted for this static-first route until repeated article needs, term ownership, framework-owned definitions, slug and collision policy, backlink behavior, renderer contract, and focused tests are source-registered and proven.

Source Notes

The first citation proof is article-owned data. The note below resolves a rendered claim to the registered blueprint source and keeps the proof gate beside the article. A full citation manager and footnote list component are explicitly vetoed: No full citation manager or footnote list component is accepted for this static-first route until a citation data model, reference syntax, backlink contract, ownership boundary, and renderer strategy are source-registered and proven.

1. Back to claimStatic-first platform layers. The blueprint requires MDX essays, frontmatter, citations, article metadata, publication-shell footnotes, article-owned data, and verification gates for source-backed long-form articles.

   Source

   blueprint-001

   Locator

   BLUEPRINT.md sections 2, 5, and 6

   Gate

   Vitest validates this source-note artifact, and Playwright verifies the rendered reference and note.

System Boundary

explicit_veto

Accepted

The published route keeps the existing source-note data article-owned and renders one blueprint-backed reference through the shared SourceNoteReference component.

Not Claimed

No full citation manager, general bibliography parser, BibTeX or CSL import path, global citation data store, or cross-article citation registry is introduced.

Next Proof

Source-register a citation and footnote model, article versus shared ownership boundary, reference syntax, backlink behavior, parser or renderer strategy, and focused tests before enabling a full citation or footnote system.

Limits

This article rewrites the accepted platform blueprint. It does not promote third-party downloads, copy inspected site prose, or claim that every future article needs the same figure technology. Canvas and WebGL remain article-level choices. The deployment stack now includes an explicit custom-domain veto; it still does not claim Cloudflare build-setting enforcement, unauthenticated rollback mutation, or rollback safety beyond the tested Cloudflare Pages production route. The shared source-note reference, one explicit full citation and footnote-system veto, first static math renderer, MDX math parser path, narrow shared math macros, one explicit cross-article macro registry veto, one explicit author-defined macro state veto, one explicit custom math compiler veto, one Astro Code/Shiki-highlighted article block, one explicit custom syntax-highlighting framework veto, one reusable copy control fed by article-owned code, one explicit cross-article code registry veto, one explicit broad clipboard guarantee veto, one explicit general copy-control framework veto, one article-owned glossary, one explicit cross-article glossary framework veto, one explicit general glossary framework veto, one article-owned appendix, one explicit general appendix framework veto, one reusable scrollytelling primitive, one child-figure scrolly context, one explicit cross-article scrollytelling registry veto, one explicit general child-figure choreography framework veto, one local scroll analytics event, one in-memory analytics aggregate, one optional same-origin Beacon transport adapter, one local route analytics summary, and one explicit custom-domain deployment veto are proven. A full citation or footnote system, custom-domain deployment guarantee, live analytics collector, persistent reader tracking, third-party analytics provider, cross-article analytics registry, cross-article scrollytelling registry, cross-article macro registry, cross-article code registry, broad clipboard guarantee, general copy-control framework, custom syntax-highlighting framework, cross-article glossary framework, general glossary framework, general appendix framework, author-defined macro state, custom math compiler, and general child-figure choreography framework are explicitly vetoed for this route until source-registered citation data, reference syntax, backlink, renderer, runtime, identity, storage, provider, registry, ownership, code, clipboard, glossary, appendix, highlighter, macro, compiler, domain, DNS, certificate, hostname, and privacy boundaries exist. Source-registered third-party provider integration remains a future proof.

Publish Readiness

This pass moves the article out of shell status for the tested platform boundary. The accepted stack covers source-registered prose, article-owned data, static and hydrated figures, the reusable scrollytelling primitive and its first child-figure context, one explicit cross-article scrollytelling registry veto, one explicit general child-figure choreography framework veto, generated data, local visual baselines, CI-safe browser proof, live and preview deployment probes, rollback mutation proof, one explicit custom-domain deployment veto, source notes, the shared source-note reference component, one explicit full citation and footnote-system veto, appendix material, one explicit general appendix framework veto, glossary terms, one explicit cross-article glossary framework veto, one explicit general glossary framework veto, static code blocks, Astro Code/Shiki syntax highlighting, one explicit custom syntax-highlighting framework veto, the reusable copy control, one explicit cross-article code registry veto, one explicit broad clipboard guarantee veto, one explicit general copy-control framework veto, static KaTeX math rendering, the MDX math parser path, narrow shared math macros, one explicit cross-article macro registry veto, one explicit author-defined macro state veto, one explicit custom math compiler veto, local scroll analytics, in-memory analytics aggregation, an optional same-origin Beacon transport adapter, one local route analytics summary, one explicit live collector veto, one explicit persistent reader tracking veto, one explicit third-party provider veto, and one explicit cross-article analytics registry veto.

• Accepted: the static-first article is publishable as a proof-backed platform article under source registry entry blueprint-001.
• Remaining: future work should source-register a full citation or footnote model before building it, source-register custom-domain checks before proving them, then prove Cloudflare build-setting enforcement and any source-registered cross-article code registry, broad clipboard guarantee, custom syntax-highlighting framework, cross-article glossary framework, general glossary framework, general appendix framework, author-defined macro state, custom math compiler, cross-article scrollytelling registry, general child-figure choreography framework, live analytics collector, persistent reader tracking, third-party analytics provider, cross-article macro registry, or cross-article analytics registry beyond the unconfigured Beacon adapter.