feat(observe): the route the document arrived on — NavigationRef.initial, NavigationRef.interaction, RenderEvent.route

[ryansolid]

Why

Every navigation record already carries the matched route pattern (NavigationEvent.name) — except the first. Nothing writes a location on a fresh document, so the route the page loaded as was never declared, and on the server it was missing entirely: the request had a URL and no route. That is the one fact a consumer naming page loads and requests needs most — Sentry's Performance product (and every peer framework SDK) keys on the route-parameterised transaction name (/users/:id, source route); without it one page scatters across as many names as it has parameters. The audits missed it because they asked what Solid can observe that React cannot, not what a framework SDK has to do; the plan records the miss and the process fix.

What

One declaration a router makes with the call it already uses, on both sides:

OBSERVE
  ? OBSERVE.attribution.withOrigin(
      { kind: "navigation", initial: true, name, to, params },
      () => buildContext()
    )
  : buildContext();

• Client (signals engine). An initial frame opens at the time origin (at defaults to 0 — the document's own navigation start, so the record joins Navigation Timing; a router mounted late passes its own), takes no from, and settles 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. NavigationEvent.initial: true. It is a declaration, not a timing: kept out of feedback().navigations, whose settledMs means "what the person waited". formatOrigin: initial navigation to /users/:id (/users/42).
• Server (solid-js server entry + web). There is no engine, so the server entry gives the core's withOrigin its one server meaning: an initial ref is filed through the render context (_declareRoute, the _recordBoundary pattern — installed by the renderer under the "render" record's gate) and the request's "render" record carries RenderEvent.route ({ name, to, params }, read from the ref at settle so a match refined during the render lands). A non-initial ref and a call outside a render are fn() as before. Two copies of the entry over one core each wrap once, reading their own sharedConfig; only the rendering copy has a context.
• NavigationRef.interaction. A router that awaits between request and write (TanStack's load transaction) loses the click — the frame is gone when it publishes. It captures OBSERVE.attribution.currentOrigin() in the request and hands it back on the ref; the record and every hold and re-run its write causes join 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 declares "for no interaction"); the stack is consulted only when the key is absent. This is what makes the contract complete for the async-writing class of router.

Public API changes

• @solidjs/signals: NavigationRef.initial?: boolean, NavigationRef.interaction?: ChangeOrigin (both accepted by OBSERVE.attribution.withOrigin); NavigationEvent.initial?: true; formatOrigin prefixes initial for such a frame.
• solid-js (server entry): OBSERVE.attribution.withOrigin gains behaviour for initial refs under a render (files the route); otherwise unchanged.
• @solidjs/web: RenderEvent.route?: RenderRoute; new exported type RenderRoute { name?, to?, params? } (server and client entries, types only).
• No diagnostic codes, no options, no behaviour change for existing navigation declarations.

Cost

• Prod artifacts byte-identical (md5 at both ends; the server entry's import is placed after the runtime exports so the module graph's evaluation order is unchanged).
• Observe tier client artifacts (signals observe core, solid.observe.js, web.observe.js) byte-identical; on the Rolldown harness (size: measure with Rolldown instead of size-limit/esbuild; re-base caps #3679) the tier scenario moves +6 B of shared-mangler layout (16,336 → 16,342 B against next @ 61a33af) — cap 16.34 → 16.35 KB with the note.
• Engine scenario +23 B (30,513 → 30,536 B) for initial/interaction handling and the formatOrigin prefix — cap 30.52 → 30.54 KB. Every prod scenario byte-identical.
• Hot paths untouched (originStart runs once per navigation); the engine-cost tripwire passes.

Tests

• attribution-navigation.test.ts +8: initial declaration (time origin, no from, no interaction, writes: 0, committed, ref re-read at settle, router-supplied at, feedback fold exclusion, no-engine passthrough); interaction (async-write join composing with feat(signals): interactions wait for the handler's promise; UNTRACKED_ASYNC_HANDLER #3604's open interaction, declared-beats-ambient, declared-none).
• New packages/web/test/server/server-render-route.spec.tsx (9): renderToString/renderToStream, settle-time re-read, later declaration replaces, only given fields, non-initial declares nothing, no router → no route, no listener → plain call, slot members intact.
• Web observe.type-tests.ts covers RenderRoute.

Note: packages/web server suite has 19 pre-existing failures on clean next in this checkout (owner-path/sourceNames shapes — same set with and without this change); none touch these files.

Docs

RFC 08: navigation section (initial, interaction, the "first navigation has no write" rule), the "render" record's route, the withOrigin snippet. Skill: history("navigation") note. Plan: the parity miss, what closed it, and the audit process fix.

Follow-ups (separate PRs)

• @solidjs/router: createRouterContext declares the initial match (draft, pending this release).
• @sentry/solid-2: rename the pageload root from the initial record; drive the navigation idle span from records; http.route from render.route (amends #24517 once released).

— Claude via Cursor

Made with Cursor

[changeset-bot]

🦋 Changeset detected

Latest commit: 95429ec

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@solidjs/signals	Patch
solid-js	Patch
@solidjs/web	Patch
test-integration	Patch
@solidjs/diagnostics	Patch
@solidjs/element	Patch
@solidjs/h	Patch
@solidjs/html	Patch
@solidjs/universal	Patch
@solidjs/babel-plugin	Patch
@solidjs/compiler	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coveralls]

Coverage Report for CI Build 36458493477

Coverage remained the same at 73.772%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	1183
Covered Lines:	922
Line Coverage:	77.94%
Relevant Branches:	914
Covered Branches:	625
Branch Coverage:	68.38%
Branches in Coverage %:	Yes
Coverage Strength:	27.06 hits per line

---

💛 - Coveralls

[codspeed]

Merging this PR will not alter performance

✅ 180 untouched benchmarks
⏩ 3 skipped benchmarks¹

---

_{Comparing feat/initial-route-declaration (95429ec) with next (077c787)}

Footnotes

1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[ryansolid]

Rebased onto next @ 656f0df (after #3684, #3682, #3692 and the rc release). The only conflict was the size ledger; attribution.ts auto-merged cleanly with #3692 and the attribution suite passes on the result (235/235), as do server-render-route.spec.tsx (9/9) and the web type tests.

Re-measured against a fresh next baseline on the esbuild harness next runs today:

scenario	next	this PR	cap
app: CSR, observe tier	17,854 B	17,854 B (±0)	17.87 KB (unchanged)
app: CSR, observe tier + attribution engine	31,973 B	32,073 B (+100 B)	31.99 → 32.08 KB

Every prod scenario byte-identical. The tier scenario's pre-rebase +25 B of mangler layout is gone, so that ratchet is dropped and the note says so; the engine cap lands on the same 32.08 KB as before. PR body updated to match. Once #3679 lands I'll port these two notes into scenarios.js and re-measure with Rolldown, as with the other size-touching PRs.

— Claude via Cursor

[github-actions]

Size (brotli, eager entry chunk)

scenario	head	vs base	cap		lazy chunks (not counted)
signals: core floor (createSignal/Memo/Effect/Root/flush)	9.51 KB	0 B	9.51 KB	✅
signals: + createStore	16.58 KB	0 B	16.59 KB	✅
signals: + isPending/latest	12.15 KB	0 B	12.16 KB	✅
app: render + one signal (the simple-app floor)	12.05 KB	0 B	12.05 KB	✅
app: hydrating (no stores) with Show/For/Loading/Errored/lazy	19.62 KB	0 B	19.63 KB	✅	lazy-page.js 0.04 KB
app: hydrating + every store primitive family	30.48 KB	0 B	30.48 KB	✅	lazy-page.js 0.04 KB
app: CSR with Show/For/Loading/Errored/lazy	14.91 KB	0 B	14.91 KB	✅	lazy-page.js 0.04 KB
app: CSR, observe tier (same app on the observe artifacts)	16.34 KB	+6 B (+0.0%)	16.35 KB	✅	lazy-page.js 0.04 KB
app: CSR, observe tier + attribution engine enabled	30.54 KB	+23 B (+0.1%)	30.54 KB	✅	lazy-page.js 0.04 KB
frames: eager client consumer (frames client + transport, lazy codec)	11.77 KB	0 B	11.77 KB	✅
page: base server components (hydrating + dynamic + frames + sf reference)	44.73 KB	0 B	44.73 KB	✅	decode.js 6.07 KB, lazy-page.js 0.04 KB
page: live server components (base + live/GET + action + isPending/latest)	48.98 KB	0 B	48.98 KB	✅	decode.js 6.07 KB, lazy-page.js 0.04 KB

_{Bundled with Rolldown (what Vite ships), brotli q11, decimal KB. Caps in scripts/size/scenarios.js; the floor and page caps in floor-caps.json are frozen (lower only, or Size-Exception: in the PR body).}