pages.discovery

Derive a dotted default route name from a URL path.

Parameter braces are stripped and the param name is kept bare:

/contacts/\{contact_id} → "contacts.contact_id". Typed params drop the type:/{id:int} → "id". The root path/ becomes "index"so every route has a non-empty name.

Walk a pages directory and discover all routes.

Walk a pages directory and discover routes plus handler-discovery findings.

Same asdiscover_pages() but also returns a list of PageHandlerFinding objects describing page.pyfiles that have no recognised handler or define handler-shaped typos. Findings are consumed by thepage_handlerscontract check.

Recursively walk a directory, discovering routes and layouts.

Infer route kind from file combination. Informational only.

Read{# target #}and optional shell scope comments from a layout.

Supported annotations::

{# preset: preset_name #}
{# target: element_id #}
{# domain: navigation_domain #}
{# shell: shell_name #}
{# swap_scope: symbolic_name #}
{# outlet: element_id #}
{# outlet_mode: compose | replace #}
{# frames: id1, id2 #}

Resolve a named layout preset or raise for unknown names.

Normalize{# outlet_mode: #}token to a known mode.

Load viewmodel() function from _viewmodel.py.

Load @action decorated functions from _actions.py.

Load RouteMeta from a _meta.py file.

Checks for META constant first, then meta() callable. Returns (meta, meta_provider) — one will be set, the other None. Raises ValueError if _meta.py has neither META nor meta().

Convert a meta dict to a normalizedRouteMeta, filling provided keys.

auth accepts a plain str(back-compatible), a structured AuthSpec, or a dictthat constructs an AuthSpec (e.g. {"permissions": ["a", "b"], "mode": "any"}). The result is canonicalized so the request-time gate is allocation-free.

Coerce a rawauth value to the canonical AuthSpec | Noneshape.

• dict -> AuthSpecbuilt from permissions/mode/policy/scopes(a dict auth is always a declared gate; anAuthSpecalways requires authentication, so there is norequired key). scopesis the machine-token axis, parallel to permissions.
• str / AuthSpec / None-> normalized via the shared core so the runtime meaning of every legacy string is preserved exactly.

Adict mode other than "all" / "any" raises ValueErrorat coercion time (discovery for staticMETA, request time for dynamic meta()) — fail loud rather than silently degrading an invalid mode.

Return meta withauth canonicalized to AuthSpec | None.

Applied at discovery time (staticMETA) and at request time for dynamic meta()results, so the request-time gate (enforce_route_meta_auth()) never re-allocates a spec and reserved-token confusion ("Required" / " required " / "") surfaces as a startupauth_specissue rather than a silent 403. Returns meta unchanged whenauthis already canonical (allocation-free).

Load a context() function from a _context.py file.

Uses path-based module names (_chirp_ctx_collections, etc.) so sibling directories do not overwrite each other in sys.modules.

Returns None if the module doesn't export acontextfunction.

Load a route .py file and extract handler functions.

page.pymaps to the directory URL. Other files append their stem to the URL path.

Handler functions are named after HTTP methods:get, post, etc.