Skip to content

Commit 95429ec

Browse 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]>
1 parent 077c787 commit 95429ec

17 files changed

Lines changed: 599 additions & 20 deletions

File tree

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
"@solidjs/signals": patch
3+
"solid-js": patch
4+
"@solidjs/web": patch
5+
---
6+
7+
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.

‎documentation/plans/responsiveness-findings-plan.md‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,9 @@ Two items change a contract; settle them before their code.
4444
the continuation are not attributed — no frame). The finding is
4545
`UNTRACKED_ASYNC_HANDLER`, on the hold thresholds; an `action()` step or a
4646
write before the `await` clears it. `@sentry/solid-2`'s `after_settle`
47-
path is now dead and should go. Original question: (↔ Tracks: the Interactions track's settle span ends at
47+
path narrows to the one shape this does not observe — a handler that
48+
dispatches a call and returns without the promise (`save().then(set)`)
49+
— and stays for it (see Consumers → Sentry). Original question: (↔ Tracks: the Interactions track's settle span ends at
4850
`settledMs`; D1 lengthens it. Decide before Stage 1 of that plan ships a
4951
shape.) Today `withInteraction` closes the frame when the synchronous
5052
handler returns; `onClick={async () => set(await save())}` settles as
@@ -395,7 +397,40 @@ appear, and they shape which fields the records need.
395397
waiting on to replace `after_settle` and to join its INP span to a cause;
396398
item 4's findings become issues without adapter changes. The reviewer
397399
brief in `getsentry/sentry-javascript` (`docs/solid-2-observe.md`) points
398-
here from its open questions.
400+
here from its open questions. Item 1 landed and the adapter kept
401+
`after_settle`, narrowed: #3604 observes a _returned_ thenable, so
402+
`onClick={() => { save().then(set) }}` still settles `idle` at once and
403+
its call lands afterwards carrying the interaction's frame; the marker now
404+
names exactly that shape.
405+
- **Parity table stake, missed by the audits above: route-parameterised
406+
transaction names — LANDED (runtime).** Every peer framework SDK renames
407+
the `pageload`/`navigation` idle spans to the matched route pattern
408+
(`/users/:id`, source `route`); Sentry's Performance product keys on that
409+
name, and the 1.x `@sentry/solid` was two files of exactly this
410+
(`solidRouterBrowserTracingIntegration`, `withSentryRouterRouting`). The
411+
audits asked "what can Solid observe that React cannot" and never
412+
"what does a Sentry framework SDK have to do", and the e2e app had one
413+
route and no router. The data was flowing for every navigation but the
414+
first — `NavigationEvent.name` is the pattern — and missing on the server
415+
entirely. Closed on the runtime side by one declaration a router makes
416+
with the call it already uses: `withOrigin({ kind: "navigation",
417+
initial: true, … })` around its initial match, on both sides. Client: the
418+
first `"navigation"` record (`initial: true`, `at` the time origin,
419+
`writes: 0`, settled on the no-write rule, kept out of the feedback fold).
420+
Server: `RenderEvent.route` on the request's `"render"` record, filed by
421+
the server entry's `withOrigin` through the render context. Beside it,
422+
`NavigationRef.interaction` lets a router that awaits before writing
423+
(TanStack's load transaction) hand back the origin it captured with
424+
`currentOrigin()`, so its write still joins the click. Router side:
425+
`createRouterContext` declares the initial match. Adapter side (pending
426+
the release): rename the pageload root from the initial record; drive the
427+
navigation idle span from records (`instrumentNavigation: false`, start
428+
at `nav.at` with the route name) instead of painting a parallel span;
429+
`http.route` on the `http.server` span from `render.route`.
430+
**Process fix, for the next audit:** before calling an integration
431+
comparable, enumerate the peer SDKs' exports and default integrations and
432+
tick them off; give the e2e app at least two routes, one parameterised,
433+
so the transaction list is something a test asserts on.
399434

400435
## Not a runtime job
401436

‎documentation/solid-2.0/08-dev-diagnostics.md‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -807,12 +807,13 @@ The **`"render"` record** (from `@solidjs/web`, server) is one server render —
807807
```js
808808
const off = OBSERVE.records.subscribe("render", (event, live) => {
809809
// event: { mode: "string" | "stream", at, shellMs?, durationMs, boundaries,
810-
// outcome: "complete" | "abandoned" | "error" }
810+
// outcome: "complete" | "abandoned" | "error",
811+
// route?: { name?, to?, params? } }
811812
// live: { event?: RequestEvent, trace: TraceContext }
812813
});
813814
```
814815

815-
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.
816817

817818
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:
818819

@@ -1048,6 +1049,16 @@ OBSERVE
10481049
() => setLocation(to)
10491050
)
10501051
: 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();
10511062
// A runtime recording a fact of its own asks what a write here would be
10521063
// stamped with — the engine's own interaction/navigation object, or
10531064
// 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
11031114
11041115
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:
11051116
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).
11071118
- `writes` — root writes the frame performed, redirect hops included.
11081119
- `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).
11091120
- `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:
11131124
11141125
- **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.
11151126
- **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)`.
11171129
11181130
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).
11191131

0 commit comments

Comments
 (0)