pages.types

Named defaults for filesystem layout metadata.

Presets let apps and extensions encode a conventional shell shape once and keep_layout.htmlfocused on route-tree intent. Explicit comments in the layout always override preset defaults.

Structured declarative auth requirement forRouteMeta.auth.

This is the data-model parity layer for the imperative @login_required / @requiresdecorators: a declarative page can now express authn-only gating, a permission set withall/anymatching, and a named policy — without embedding a live callable in frozen route metadata.

RouteMeta is static serializable data: policyis therefore a string NAME resolved later against an app policy registry, never a Callable. Plain str authvalues remain fully supported and are normalized to an equivalentAuthSpec(see normalize_auth_spec()).

AnAuthSpecalways requires an authenticated user — the gate always checksis_authenticated. The only way to express an open/optional route isRouteMeta.auth = None (or an open string token "none"/ "optional" / ""), NOT an AuthSpec. There is therefore no required flag: an authn-only gate is AuthSpec()(no permissions, no policy).

scopesis the machine-auth axis, distinct from the human permissionsaxis. Webhook / cron / provisioning endpoints gate on the token scopes carried by the resolved client (a ClientWithScopes exposing scopes: frozenset[str]), independent of human permissions: a token-resolved client holding the required scope passes even with no permissions, and a human user holding the permissions but not the scope fails the scope gate. Scope enforcement is implicitly off — aspec with no scopesruns no scope step at all, so existingverify_tokenusers are never newly 403'd (there is no separate enable flag). Scope-equality is compared in constant time (secrets.compare_digest), and a declared scope absent from app.register_scope is a startup auth_speccontract ERROR.

Route metadata from_meta.py.

All fields optional. Static META or meta() callable provides values.

auth accepts a plain str (back-compatible: "none"/"optional" are open,"required"is authn-only, any other non-empty string is a single required permission) or a structuredAuthSpecfor permission sets,all/anymatching, and named policies.

A tab item for section navigation (ChirpSection+ chirp-ui route tabs).

Optional fields match the dict shape consumed byrender_route_tabs/ tab_is_active in chirp-ui: matchcontrols active state for nested URLs. SeeSHELL-TABS-CONTRACT.mdin chirp-ui for the full shell to route-tabs data flow.

A named action from_actions.py.

A named section with tab items and breadcrumb prefix.

Register viaapp.register_section() before mount_pages(); tab items flow to chirp-uirender_route_tabs through resolve_section_context.

A layout template discovered in the filesystem.

Each_layout.html declares a shell with a {% block content %} slot and a{# target: element_id #}comment declaring which DOM element it owns.

Optional comments (see filesystem routing docs) declare navigation and swap metadata for boosted navigation helpers:

• {# domain: name #}— author-facing navigation domain boundary.
• {# shell: name #}— this layout introduces a shell boundary.
• {# swap_scope: name #} — symbolic scope (e.g. shell, page).
• {# outlet: element_id #}— primary navigation outlet for this level (defaults to target when omitted).
• {# outlet_mode: compose | replace #}— how boosted swaps targeting {# outlet: #} relate to layout composition (default compose).
• {# frames: id1, id2 #}— optional frame ids (immutable chrome).

Ordered sequence of layouts from root (outermost) to deepest.

The chain determines rendering depth based onHX-Target:

• Full page: render all layouts nested
• HX-Target: #app-content: find the layout that owns app-content, render from the next layout down
• Fragment: render just the targeted block

A_context.pyfile's context function.

Each provider is an async or sync function that receives path parameters and returns a dict of context variables.

A discovered page route with its layout chain and context providers.

Built during filesystem discovery. Used bymount_pages()to register routes with the chirp app.

A diagnostic finding from page-handler discovery.

Emitted when apage.pyfile either has no recognized HTTP method handler (kind="missing") or defines a function whose name looks like a handler attempt but isn't recognized (kind="typo").

Surfaced toapp.check() as page_handlerscontract issues; the severity mapping (ERROR for missing, WARNING for typo) is applied there, not here.