You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 95429ec
Browse filesBrowse the repository at this point in the historyBrowse files
feat(observe): the route the document arrived on — NavigationRef.initial, NavigationRef.interaction, RenderEvent.route
A router declares its initial match with the call it already uses for
navigations, on both sides: `withOrigin({ kind: "navigation", initial:
true, … })` around the work that builds its context. Client: the engine
opens the frame at the time origin, takes no `from`, settles it on the
no-write rule — the first "navigation" record, `initial: true`, kept
out of the feedback fold. Server: the server entry's `withOrigin` files
the ref through the render context (`_declareRoute`) and the request's
"render" record carries `RenderEvent.route` — the `http.route` a
consumer names the request by.
`NavigationRef.interaction`: a router that awaits before writing hands
back the origin it captured with `currentOrigin()`; declared beats
ambient, the key's presence is the declaration.
Prod artifacts byte-identical; observe client artifacts byte-identical
(tier cap +25 B of mangler layout); engine +122 B.
Co-Authored-By: Claude via Cursor <[email protected]>
Co-authored-by: Cursor <[email protected]>
The route the document arrived on, declared by the router with the call it already uses. `NavigationRef.initial` on `OBSERVE.attribution.withOrigin`: a router wraps the work that establishes its initial match (building its context) instead of a location write, on both sides. On the client the attribution engine opens the frame at the time origin (`at` defaults to `0`, the document's own navigation start; a router mounted late passes its own), takes no `from`, and settles it `committed` with `writes: 0` when the frame closes, so the first `"navigation"` record (`NavigationEvent.initial: true`) names the route the page loaded as — the pageload's route pattern, which every navigation but the first already had. It is a declaration, not a timing: kept out of `feedback().navigations`. On the server, where there is no engine, the server entry's `withOrigin` files the ref on the render, and the request's `"render"` record carries it as `RenderEvent.route` (`{ name, to, params }`, read from the ref when the render settles) — the name a consumer gives the request (`http.route`) where the URL would scatter one page across as many names as it has parameters. New type `RenderRoute` from `@solidjs/web`.
8
+
9
+
`NavigationRef.interaction`: a router that awaits between the request and the write (guards or loaders resolved in its core before it publishes the location) captures `OBSERVE.attribution.currentOrigin()` in the request and hands it back on the ref, and the write it publishes later joins the click as if it had been synchronous. Declared beats ambient: the key's presence is the declaration, and an interaction on the stack at write time is used only when the key is absent.
10
+
11
+
`formatOrigin` renders the initial declaration `initial navigation to /users/:id (/users/42)`. Prod artifacts byte-identical; the observe tier's client artifacts byte-identical.
One record per render, delivered when it **ends**: the document returned, the stream's last fragment written, or the render torn down. `at` is `performance.now()` at the render's start; `shellMs` runs start → the shell complete — for a stream, the head and shell handed to the sink (the head is frozen from there; a fragment can no longer add to it), for a string, the document assembled (the whole render) — and is absent when the render ended before its shell; `durationMs` runs start → the end. `boundaries` counts the `<Loading>` boundaries the shell **waited on** — each also a `"boundary"` record with `streamed: false` — and not the ones that streamed after it; it is counted from the boundary records the render filed, so in an observe build it needs a `"boundary"` listener too (`0` with a `"render"` listener alone). `outcome` is `"complete"` for a render that ran to its end, `"abandoned"` when the consumer left mid-stream (the `SSR_STREAM_ABANDONED` finding is that request's account), `"error"` when the render failed (a string render threw; a stream's uncontained failure wound it down). `live.event` is the request the render served, absent for a render outside a request scope; `live.trace` is the render's trace context (what `getTraceContext()` answers during it). `solid-shell` on the response's `Server-Timing` is this record's `shellMs`, read off the same object at head commit (below, [Chrome Performance panel](#chrome-performance-panel-solidjswebperformance-tracks)). The cost is paid only with a listener installed (or in dev): a render nobody observes reads no clock.
816
+
One record per render, delivered when it **ends**: the document returned, the stream's last fragment written, or the render torn down. `at` is `performance.now()` at the render's start; `shellMs` runs start → the shell complete — for a stream, the head and shell handed to the sink (the head is frozen from there; a fragment can no longer add to it), for a string, the document assembled (the whole render) — and is absent when the render ended before its shell; `durationMs` runs start → the end. `boundaries` counts the `<Loading>` boundaries the shell **waited on** — each also a `"boundary"` record with `streamed: false` — and not the ones that streamed after it; it is counted from the boundary records the render filed, so in an observe build it needs a `"boundary"` listener too (`0` with a `"render"` listener alone). `outcome` is `"complete"` for a render that ran to its end, `"abandoned"` when the consumer left mid-stream (the `SSR_STREAM_ABANDONED` finding is that request's account), `"error"` when the render failed (a string render threw; a stream's uncontained failure wound it down). `live.event` is the request the render served, absent for a render outside a request scope; `live.trace` is the render's trace context (what `getTraceContext()` answers during it). `solid-shell` on the response's `Server-Timing` is this record's `shellMs`, read off the same object at head commit (below, [Chrome Performance panel](#chrome-performance-panel-solidjswebperformance-tracks)). The cost is paid only with a listener installed (or in dev): a render nobody observes reads no clock. `route` is the route the render resolved to, as the router declared it while building its context under this render (`OBSERVE.attribution.withOrigin` with an `initial` ref — the same call that opens the client's first `"navigation"` record): `name` the matched pattern (`/users/:id`), `to` the concrete path, `params` what it bound; read from the router's ref when the render settles, so a match refined during the render is what lands, and absent when no router declared one. It is the name a consumer gives the request (`http.route`), where the URL would scatter one page across as many names as it has parameters.
816
817
817
818
The **`"call"` record** (from `@solidjs/web`, client) is one server-function call made from the browser — the invocation's twin, seen from the caller's end:
818
819
@@ -1048,6 +1049,16 @@ OBSERVE
1048
1049
() =>setLocation(to)
1049
1050
)
1050
1051
:setLocation(to);
1052
+
// And the route the document arrived on, around the work that establishes
1053
+
// its initial match (there is no location write on a fresh document). On the
1054
+
// client this is the first "navigation" record; on the server it names the
1055
+
// request's "render" record (`RenderEvent.route`). Same call on both sides.
1056
+
OBSERVE
1057
+
?OBSERVE.attribution.withOrigin(
1058
+
{ kind:"navigation", initial:true, name:"/users/:id", to, params:match.params },
1059
+
() =>buildContext()
1060
+
)
1061
+
:buildContext();
1051
1062
// A runtime recording a fact of its own asks what a write here would be
1052
1063
// stamped with — the engine's own interaction/navigation object, or
1053
1064
// undefined — and puts it on its record (the web runtime's "call" record
@@ -1103,7 +1114,7 @@ Effect- and action-origin writes resolve through the record of the run they belo
1103
1114
1104
1115
A navigation in Solid 2 is a plain write to the location — reads pull the route's async and the runtime holds the write until the data is ready — so the engine already sees everything a navigation costs. What it cannot see is that the writes _were_ a navigation, and to which route. `OBSERVE.attribution.withOrigin({ kind:"navigation", … }, fn)` is where a router says so, around its write; every router (or hand-rolled one) adds that one call, and nothing else anywhere is router-specific. From it the engine keeps one `NavigationEvent` per frame:
1105
1116
1106
-
- `name`, `to`, `from`, `params`, `at` — what the router described; `interaction` — the link click (or other event) it ran under, when known, including through an action step (`navigate()` after a `yield`).
1117
+
- `name`, `to`, `from`, `params`, `at` — what the router described; `interaction` — the link click (or other event) it ran under, when known, including through an action step (`navigate()` after a `yield`) or declared on the ref by a router that awaited before writing; `initial` — the route the document arrived on, declared at the router's initial match (see below).
- `settledMs` and `outcome`, once its writes are through: `committed` (a plain drain took them — settle is the end of that drain, the instant the screen had them), `held` (they waited in a transition — settle is its commit, and `hold` carries the `HoldEvent` when hold tracking recorded one), or `superseded` (a later write to the same node replaced them before they landed — the user navigated again).
1109
1120
- `redirects` — present when a guard or loader sent the navigation elsewhere before it landed: the destinations abandoned along the way, in order, each with the time the redirect away from it was declared. `name`/`to`/`params` are then the final destination.
@@ -1113,7 +1124,8 @@ Two things about the frame are read late, on purpose:
1113
1124
1114
1125
- **The ref is re-read at settle.** The engine keeps the object passed to `withOrigin` and copies `name`, `to` and `params` from it again when the navigation settles (and when a hold on it is judged). A router whose match is not final at write time — a lazy route subtree that resolves inside the hold — describes coarsely (`/admin/*`), then assigns the exact pattern and params onto the same object once it knows them; the settled record, the hold's verdict and the feedback row all read the refined name. `from` and `at` are read once, when the frame opens.
1115
1126
- **A redirect is a hop, not a new navigation.** A router declares a redirect with `redirect: n` (`n >= 1`, the hop depth it already tracks). The engine re-enters the pending navigation's frame instead of opening one: the hop's write replaces the pending one with the same origin, so nothing is superseded; the record keeps the user's request time and interaction, so `settledMs` runs from the click, not the hop; the abandoned destination moves to `redirects`. With no pending navigation to fold onto, a `redirect` frame opens a navigation of its own.
1116
-
- **One rule for every router: wrap the write whose landing is the destination showing.** Solid Router's navigation is a location write whose downstream the runtime holds until route data lands, so "writes through" is "navigation done" and the frame goes around that write. A router that awaits part of its pipeline outside the graph (TanStack Router's load transaction: the location moves at once, matches are published only when the loaders resolve) wraps the _publish_ instead, and passes `at: startedAt` — the user's request time, on the `performance.now()` clock — so the span starts at the click rather than at the write. The engine has no router-specific seam beyond that: a navigation the router abandons before it publishes is the router's to report, and the wait it owns is inside `settledMs` only through `at`. (Making the loader wait itself part of the transition, so the location write is the one to wrap, is router work — planned for the Solid 2 TanStack adapter, not yet done.) `params` values may be `undefined` (an optional segment left unbound).
1127
+
- **One rule for every router: wrap the write whose landing is the destination showing.** Solid Router's navigation is a location write whose downstream the runtime holds until route data lands, so "writes through" is "navigation done" and the frame goes around that write. A router that awaits part of its pipeline outside the graph (TanStack Router's load transaction: the location moves at once, matches are published only when the loaders resolve) wraps the _publish_ instead, and passes `at: startedAt` — the user's request time, on the `performance.now()` clock — so the span starts at the click rather than at the write. The engine has no router-specific seam beyond that: a navigation the router abandons before it publishes is the router's to report, and the wait it owns is inside `settledMs` only through `at`. (Making the loader wait itself part of the transition, so the location write is the one to wrap, is router work — planned for the Solid 2 TanStack adapter, not yet done.) Such a router also loses the click: the interaction frame is gone by the time it publishes. It captures `OBSERVE.attribution.currentOrigin()` in the request and hands it back as `interaction` on the ref, and the record — and every hold and re-run the write causes — joins the click as if the write had been synchronous. Declared beats ambient: the key's presence is the declaration (`interaction: currentOrigin()` with nothing in effect at the request declares "for no interaction"), and what is on the stack at write time is used only when the key is absent. `params` values may be `undefined` (an optional segment left unbound).
1128
+
- **The first navigation has no write: declare it.** The route the document arrived on is the one a consumer naming page loads needs most, and nothing writes a location for it. A router declares it with `initial: true` around the work that establishes its initial match — building its context — on both sides, with the same call. On the client the engine opens the frame at the time origin (`at` defaults to `0`, the document's own navigation start, so the record joins Navigation Timing; a router mounted long after the load passes its own `at`), takes no `from`, and settles it `committed` with `writes: 0` when the frame closes — the existing no-write rule — so the record is delivered as the router finishes describing the route, `initial: true` on it. It is a declaration, not a timing: `settledMs` is document start → router built, and the record is kept out of `feedback().navigations`, whose `settledMs` means "what the person waited"; the holds the mount waits in are their own records. On the server there is no engine, and the same call files the ref on the render — `RenderEvent.route` (`name`, `to`, `params`, read from the ref when the render settles) names the request the way `http.route` wants it, where the URL would scatter one page across as many names as it has parameters. `formatOrigin` renders it `initial navigation to /users/:id (/users/42)`.
1117
1129
1118
1130
A navigation that changed nothing (no write survived the equality gate) settles at once with `writes: 0`. `formatOrigin` renders the kind as `navigation to /users/:id (/users/42)` — after a redirect, `navigation to /login (redirected from /users/42)` — and cause chains under a click read `— navigation to /users/:id (under click on a.nav "Alice")`. `feedback().navigations` folds settled events per route (the final one, after redirects).
0 commit comments