Portable page architecturePortable page architectureCurrent / Boundary

Portable page architecture

Fictional sample. Every metric, status, organization, and decision on this page exists only to demonstrate the report engine; replace it with verified project evidence before use.

This starter records one system decision in enough detail for implementation and later reversal. It keeps the trust boundary visible instead of hiding it in framework code.

System boundary

The source, compiler, artifact, and browser boundary

Decision

Use one declarative compilation path

Keep Markdown, metadata, confined partials, and local assets as the public source. Compile them into static output using package-owned renderers and a bounded event-delegated runtime.

Force Consequence
Offline portability No remote runtime or author-time network fetch
Agent ergonomics No JSX, CSS, or JavaScript required
Security review Data-only directives with explicit constraints
Deterministic output Package versions and local source determine bytes

Runtime flow

Offline compilation boundaryDeclarative local input passes through validation and compile-time rendering into a static browser artifact.
Offline compilation boundaryDeclarative local input passes through validation and compile-time rendering into a static browser artifact. Nodes: 4; flow layers: 4. Layers along the flow: 1. Local source [Input and output]. 2. Validated model. 3. Semantic renderer [Build-time rendering]. 4. Static artifact [Input and output]. Connections along the flow: Local source → Validated model: parse; Validated model → Semantic renderer: typed data; Semantic renderer → Static artifact: HTML + assets.Local sourceValidated modelSemantic rendererStatic artifactparsetyped dataHTML + assets
  • Input and output
  • Build-time rendering
Diagram in words

Nodes: 4; flow layers: 4.

Layers along the flow

  1. Local source [Input and output]
  2. Validated model
  3. Semantic renderer [Build-time rendering]
  4. Static artifact [Input and output]

Connections along the flow

  • Local source → Validated model: parse
  • Validated model → Semantic renderer: typed data
  • Semantic renderer → Static artifact: HTML + assets

Alternatives and consequences

Alternatives considered

One registry, model, renderer, and bounded runtime keep every supported page on the same contract.

Positive

Authors provide data and semantic intent; the package owns browser behavior.

Trade-off

New interaction classes require a package release instead of arbitrary author JavaScript.

Guardrail

All filesystem references are confined before reads and all output works locally.

  • Does the source remain declarative?
  • Is every local path confined before reading?
  • Does the artifact work without a network or server?
  • Is the new behavior covered at its public boundary?

Rollout

Adopt the decision

  1. Replace the sample decision and evidence in the declarative source.
  2. Build semantic output through the shared compiler.
  3. Open the artifact through file:// at desktop and mobile widths.
  4. Revisit the decision when a verified requirement no longer fits the boundary.

Contents