feat(observe): declare the route the document arrived on

[ryansolid]

Stacked on #641 (base branch migrate-public-hydration-api); GitHub retargets to next when that merges. solid-js / @solidjs/web 2.0.0-rc.13 ship NavigationRef.initial and RenderEvent.route (solidjs/solid#3683, in rc.12), so this branch bumps to ^2.0.0-rc.13 and moves the peer floor to ^2.0.0-rc.12. Verified on the published packages: pnpm test client 40 files / 445 tests, server 7 / 44, type tests, pnpm build, attw all green.

What

The router already declares every navigation to the observe tier around its location write (OBSERVE.attribution.withOrigin), so consumers get the route pattern for every navigation — except the first. A fresh document has no location write, so the route the page loaded as was never declared, and on the server the request had a URL and no route.

Now RouterComponent wraps the work that builds its context in the same call, with initial: true on the ref:

const routerState = OBSERVE
  ? OBSERVE.attribution.withOrigin(
      describeInitial(matchPath, untrack(integration.signal[0]).value),
      buildContext
    )
  : buildContext();

• Client: the engine opens the frame at the time origin and settles it as the context is built — the first "navigation" record, initial: true, writes: 0, at: 0, no from. Kept out of feedback().navigations by the engine.
• Server: there is no engine; the same call files the ref on the render, and the request's "render" record carries RenderEvent.route ({ name, to, params }), read at settle so a lazy subtree that resolved during the render names the exact route (pinned).
• describeNavigation and describeInitial share the match description (routeName, routeParams); name/params remain getters read at settle.
• Folded out of shipped bundles with OBSERVE, as the navigation declaration is.

Also in this PR (rc.10 moves the touched files need)

• NavigationRef is imported from solid-js (the frame refs moved beside withOrigin in rc.10).
• test/observe-navigation.spec.tsx uses attribution.history("navigation") in place of the removed attribution.navigations().

Public API

No router option or export changes; one new call site. Peer dependency floor: solid-js / @solidjs/web peers move from ^2.0.0-rc.10 to ^2.0.0-rc.12, the first release with the fields this declaration uses (and without the sharedConfig types #641 replaces).

Tests

• test/observe-navigation.spec.tsx +3: mounting declares the initial route (fields, at: 0, writes: 0, committed); an empty arrival normalized onto base is that one record (writes: 1), not a navigation; the declaration is not a feedback().navigations row.
• test/server/observe-render-route.spec.tsx (new, 6): url prop, root /, request-event URL precedence, lazy subtree refined at settle (stream path), empty arrival + base names the render by the base, no router → no route.

Why it matters

Sentry's Performance product (and every peer framework SDK) names transactions by route pattern; @sentry/solid-2 will rename the pageload root from the initial record and set http.route from render.route. Any other Solid router adopts the same contract with the same one call.

— Claude via Cursor

Made with Cursor

[changeset-bot]

🦋 Changeset detected

Latest commit: f1f0772

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

This PR includes changesets to release 1 package

Name	Type
@solidjs/router	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

[ryansolid]

Follow-up pushed (b5a1cc8): the base-normalization write. With base set and an empty arrival (hash history with no hash, memoryHistory(""), a static render with no url) createRouterContext writes the base path inside the wrapped build; that write went through the setter's withOrigin, opened a nested navigation frame, and took the write — so the initial record kept to: "" (matched to nothing → name: "/") and a phantom "" → /app navigation followed. Now a write from no location is not declared as a navigation (the arrival is already declared by the initial frame, which the write then stamps), and the initial ref's fields are getters read at settle, so the record is one, to: "/app", name: "/app", writes: 1, committed. Pinned on both sides (memoryHistory("") + base client; no-url static render + base server).

— Claude via Cursor

[ryansolid]

rc.13 is out, so this is no longer waiting on a Solid release. Rebased onto #641 (migrate-public-hydration-api) and retargeted there — rc.12 dropped sharedConfig from solid-js's public types, so the bump this PR needs cannot land on next before that migration; GitHub retargets to next when #641 merges. Added 1d21adf: solid-js / @solidjs/web ^2.0.0-rc.13, peer floor ^2.0.0-rc.12; #641's planned bump commit will resolve to the same lines.

Verified on the published packages (no linked runtime): client 40 files / 445 tests, server 7 / 44, type tests, pnpm build, @arethetypeswrong/cli all green — the flash-seeding failures noted earlier were the linking artifact and do not occur on rc.13. Marked ready for review.

— Claude via Cursor