Module nav 

File-based-pages navigation primitive - the ONE surface every embedding reaches through.

Navigation in Lumen is not a per-language script builtin: it is a command carried on the shared external-signal bus. A script host (Rhai now, candela later), the Rust SDK, a C-ABI plugin, and the future Python / C# SDKs all reach navigation by writing the reserved REQUEST_SIGNAL cell through request (which routes through crate::signals::push_external_signal -> crate::property_store::PropertyStore). The runtime’s apply_navigation system is the single resolver: it reads the request cell, resolves the target path against the registered pages (longest existing-file prefix - the framework never pattern-matches :id segments), and writes the reserved PATH_SIGNAL / SEGMENT_SIGNAL cells that <if> page gates, bind-*, and derivations react to.

This mirrors real-HTML navigation semantics (an <a href> click and a programmatic history.pushState both end at one URL that the view reacts to) and Next.js / SvelteKit file-based routing (a page == a file), while staying candela-neutral: nothing here is Rhai-specific.

Wire format

The request cell carries a single opaque string so a repeated identical op (two back()s in a row) still edge-triggers: "<seq>\u{1f}<kind>\u{1f}<arg>" where seq is a process-monotonic nonce, kind is one of {nav, back, forward}, and arg is the target path for nav (empty otherwise). Producers build it with encode_request; the resolver parses it with parse_request.

Enums

NavOp

A navigation operation. Host-neutral: every surface produces one of these.

Constants

PATH_SIGNAL

Reserved global signal holding the active page key (the resolved .lmn filename stem). <if eq="settings"> page gates compare against it; bind-text="route.path" and derivations may read it.

REQUEST_SIGNAL

Reserved global signal the navigation resolver reads. Producers write it via request; it is not meant to be bound in markup.

SEGMENT_SIGNAL

Reserved global signal holding the leftover path after the matched page prefix (e.g. navigating /user/7 when only user.lmn exists leaves /7 here). The framework never parses this into typed params - the page’s own code does.

Functions

back

Convenience: step back in history.

current

Read the current active page key. Empty before the first page mounts.

encode_request

Encode op into the reserved-request wire string with a fresh nonce so an immediately-repeated op still registers as a change.

forward

Convenience: step forward in history.

navigate

Convenience: navigate to path (equivalent to request(NavOp::Navigate(..))).

parse_request

Parse a reserved-request wire string back into (seq, op). Returns None for an unrecognised / malformed value.

request

Request a navigation from ANY thread / ANY surface. Writes the reserved request cell through the external-signal bus; the runtime’s apply_navigation system resolves it on the next tick.

resolve_path

Resolve a requested path against the set of known page keys (each a .lmn filename stem), returning (page_key, segment).

set_current

Publish the resolved active page key. Called by the runtime resolver.