<page>

Syntax

<page [path="/explicit-route"] [auth="required"]>
  <!-- page body -->
</page>

Two placement shapes:

• Inline in entry file. A <page> declared inside the entry-file <program> body. Useful for small apps. The path= attribute is REQUIRED when used inline.
• Standalone file under pages/. A <page> declared as the root element of a file under pages/. The filesystem path determines the route; no path= attribute needed. Canonical multi-page-app shape.

Worked example

Filesystem layout for a four-page app. Each file is a standalone <page> root; the filesystem determines routes.

app.scrml                       <program> root + nav chrome
pages/
  index.scrml                   /
  about.scrml                   /about
  reference/
    index.scrml                 /reference
    elements/
      engine.scrml              /reference/elements/engine

Inside each page file:

<page>
  <article>
    Page content here.
  </article>
</page>

The compiler reads the pages/ tree (per SPEC §40.8.1 filesystem-inferred multi- page-app shape) and emits per-route artifacts. Approach A closure analysis runs per page; each route ships its own chunk set.

Semantics

• Filesystem-inferred routing. Per SPEC §40.8.1, when a project has a pages/ directory at the project root, the compiler treats the project as a multi-page app. Each .scrml file under pages/ becomes a route; the file path (minus .scrml) is the URL.
• SPA shape if no pages/ exists. Projects with a top-level <program> but no pages/ directory and no <page> children are inferred as SPAs (W-PROGRAM-SPA-INFERRED info-level lint surfaces the inference).
• Auth inheritance. A <page> nested inside an <auth role="X"> wrapper inherits the role unless it has its own auth= attribute. The compiler emits W-AUTH-PAGE-INFERRED info-level when the inference applies, so the inheritance is auditable.
• Per-route artifacts. Each page gets its own initial chunk + tier-1 idle-prefetch + tier-2 hover-prefetch + tier-N on-demand chunks (Approach A artifact splitter, v0.3.0). The chunk filenames embed an FNV-1a content hash for adopter-cache stability.
• Per-role chunk variance. For routes nested inside <auth role=>, the splitter emits role-specific chunks. Anonymous visitors download strictly smaller initial bundles than logged-in roles.

Errors this feature can fire

• W-PROGRAM-SPA-INFERRED — top-level program with no pages/ tree (SPA inferred)
• W-AUTH-PAGE-INFERRED — inherits auth role from wrapper
• E-STRUCTURAL-ELEMENT-MISPLACED — <page> in unsupported context

Edge cases

• Index resolution. A file at pages/reference/index.scrml serves the route /reference — the index suffix is the canonical "directory landing" form. Alternative file shape pages/reference.scrml serves the same route — equivalent semantics per route inference.
• Dynamic segments via path= attribute. For routes that need positional parameters (e.g., /users/:id), use the explicit path= attribute. Filesystem-inferred routes are static only.
• routes/ alias. routes/ is recognized as a synonym of pages/ (S94 D-RI-PAGES). Pick one; don't mix in the same project.
• Pages do NOT nest. A <page> inside another <page> is invalid. For nested routes, use the filesystem hierarchy (pages/parent/child.scrml).

Related features

• <program> — root container; documents the multi- page shape via filesystem-routed page children.
• <auth role=> — per-role visibility wrapper for pages; drives per-role chunk variance.
• chunks.json — the per-route per-role manifest. Inspect to see what each route ships.
• data-scrml-prefetch — markup attribute the compiler emits on internal links for tier-2 hover-prefetch.

Availability

Specification

This page summarizes SPEC §40.8 (multi-page-app shape) and §40.8.1 (filesystem-inferred routing). Cross-refs to §40.9 (Approach A artifact splitter) apply when auth wrapping is involved. The normative text lives at compiler/SPEC.md in the scrmlTS repository.