@belte/belte 0.19.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @belte/belte
 
+## 0.19.1
+
+### Patch Changes
+
+- [`c392c5a`](https://github.com/briancray/belte/commit/c392c5abf08a070617e7bfa1094cc38a20cba002) - read the page store during SSR via a request-scoped resolver ([`85f4c7a`](https://github.com/briancray/belte/commit/85f4c7a486191847772553cd62b34315a15a6438))
+
 ## 0.18.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@belte/belte",
-    "version": "0.19.0",
+    "version": "0.19.1",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

package/src/lib/browser/page.svelte.ts

@@ -1,9 +1,11 @@
 import type { Component } from 'svelte'
+import { activePage } from '../shared/activePage.ts'
 import {
     type NormalizedLayoutPrefix,
     nearestLayoutPrefix,
     normalizeLayoutPrefixes,
 } from '../shared/nearestLayoutPrefix.ts'
+import type { PageSnapshot } from '../shared/types/PageSnapshot.ts'
 import { abortPageStream } from './pageStreamController.ts'
 import type { Layouts } from './types/Layouts.ts'
 import type { Pages } from './types/Pages.ts'
@@ -42,13 +44,37 @@ export type Page = keyof Routes extends never
     ? PageStateFor<string>
     : { [R in keyof Routes]: PageStateFor<R> }[keyof Routes]
 
-// biome-ignore lint/suspicious/noExplicitAny: discriminated-union init needs a single arm
-export const page: Page = $state<any>({
+/*
+Client-side singleton the resolver returns. navigate()/applyState mutate it;
+because it's $state, reads taken through the `page` proxy inside a $derived
+re-run on every nav. Never populated server-side — there the resolver reads
+the per-request ALS store instead, so concurrent renders don't share it.
+*/
+export const clientPageState: PageSnapshot = $state({
     route: '',
     params: {},
     url: new URL('http://localhost/'),
 })
 
+/*
+Public page state. A getter proxy over the side's registered resolver
+(activePage): client → clientPageState singleton, server → the per-request
+ALS snapshot. Property reads on the client resolve to the $state singleton, so
+reactivity flows; on the server each render reads its own request scope. Users
+only ever see route/params/url.
+*/
+export const page = {
+    get route() {
+        return activePage().route
+    },
+    get params() {
+        return activePage().params
+    },
+    get url() {
+        return activePage().url
+    },
+} as unknown as Page
+
 /*
 Internal renderer state — the Layout/Page components App.svelte mounts.
 Kept on a separate $state object so it doesn't leak into the public `page`
@@ -116,15 +142,13 @@ function applyState(
 ): void {
     renderState.Layout = Layout
     renderState.Page = Page
-    const mutable = page as PageStateFor<string>
-    mutable.route = route
-    mutable.params = params
+    clientPageState.route = route
+    clientPageState.params = params
     syncUrl()
 }
 
 function syncUrl(): void {
-    const mutable = page as PageStateFor<string>
-    mutable.url = new URL(window.location.href)
+    clientPageState.url = new URL(window.location.href)
 }
 
 /*
@@ -207,7 +231,7 @@ export async function navigate(href: string, options: NavigateOptions = {}): Pro
         return
     }
     const fullTarget = `${target.pathname}${target.search}${target.hash}`
-    if (target.pathname === page.url.pathname) {
+    if (target.pathname === clientPageState.url.pathname) {
         writeHistory(replace, fullTarget)
         syncUrl()
         return
@@ -234,7 +258,7 @@ only refreshes `page.url`; a pathname change resolves and swaps the page, or
 hard-navigates when the restored URL isn't an SPA route.
 */
 async function applyTarget(pathname: string, fullTarget: string): Promise<void> {
-    if (pathname === page.url.pathname) {
+    if (pathname === clientPageState.url.pathname) {
         syncUrl()
         return
     }

package/src/lib/browser/startClient.ts

@@ -3,13 +3,21 @@ import App from '../../App.svelte'
 import { createCacheStore } from '../shared/createCacheStore.ts'
 import { setCacheStoreResolver } from '../shared/setCacheStoreResolver.ts'
 import { setGlobalCacheStoreResolver } from '../shared/setGlobalCacheStoreResolver.ts'
+import { setPageResolver } from '../shared/setPageResolver.ts'
 import type { CacheSnapshotEntry } from '../shared/types/CacheSnapshotEntry.ts'
 import type { CacheStore } from '../shared/types/CacheStore.ts'
 import type { StreamingPlaceholder } from '../shared/types/StreamingPlaceholder.ts'
 import { cacheEntryFromSnapshot } from './cacheEntryFromSnapshot.ts'
 import { installStreamingPlaceholders } from './installStreamingPlaceholders.ts'
 import { openResolveStream } from './openResolveStream.ts'
-import { bindPage, handlePopstate, navigate, page, renderState } from './page.svelte.ts'
+import {
+    bindPage,
+    clientPageState,
+    handlePopstate,
+    navigate,
+    page,
+    renderState,
+} from './page.svelte.ts'
 import type { Layouts } from './types/Layouts.ts'
 import type { Pages } from './types/Pages.ts'
 
@@ -107,6 +115,8 @@ export async function startClient({
     setCacheStoreResolver(() => cacheStore)
     /* One tab store: cache(fn, { global: true }) shares it, so global is a no-op here. */
     setGlobalCacheStoreResolver(() => cacheStore)
+    /* One document: the `page` proxy resolves to this $state singleton, mutated by navigate(). */
+    setPageResolver(() => clientPageState)
     if (window.__SSR__.cache) {
         hydrateCacheFromSnapshot(cacheStore, window.__SSR__.cache)
     }

package/src/lib/server/runtime/createServer.ts

@@ -293,6 +293,9 @@ export async function createServer({
         params: Record<string, string>,
         store: RequestStore,
     ): Promise<Response> {
+        /* Publish the match so the `page` proxy resolves route/params during SSR render. */
+        store.route = routeUrl
+        store.params = params
         const json = wantsJson(store.req)
         if (json) {
             return Response.json(

package/src/lib/server/runtime/types/RequestStore.ts

@@ -12,6 +12,13 @@ export type RequestStore = {
     req: Request
     cache: CacheStore
     /*
+    The matched page route and its decoded params, set just before the page
+    renders so the `page` proxy resolves them inside layout-scoped components
+    during SSR. Undefined on rpc/socket requests and until a page match lands.
+    */
+    route?: string
+    params?: Record<string, string>
+    /*
     The request's cookie jar, materialized lazily by the first cookies() call
     and flushed to Set-Cookie headers when the scope returns. Undefined while a
     request never touches cookies, so the common path parses and emits nothing.

package/src/lib/shared/activePage.ts

@@ -0,0 +1,20 @@
+import { pageSlot } from './pageSlot.ts'
+import type { PageSnapshot } from './types/PageSnapshot.ts'
+
+/*
+Resolves the active page snapshot. The runtime is registered via
+`setPageResolver` from the server entry (request-scoped via ALS) or the
+client entry (module-level singleton). If no resolver is registered, a single
+fallback snapshot is created lazily so isolated tests still work. Mirrors
+activeCacheStore.
+*/
+export function activePage(): PageSnapshot {
+    const fromResolver = pageSlot.resolver?.()
+    if (fromResolver) {
+        return fromResolver
+    }
+    if (!pageSlot.fallback) {
+        pageSlot.fallback = { route: '', params: {}, url: new URL('http://localhost/') }
+    }
+    return pageSlot.fallback
+}

package/src/lib/shared/pageSlot.ts

@@ -0,0 +1,17 @@
+import type { PageSnapshot } from './types/PageSnapshot.ts'
+
+/*
+Internal slot the runtime entries register their page resolver into. The
+server entry installs an ALS-backed resolver (request-scoped, so concurrent
+and streaming renders never share state); the client entry installs a
+module-singleton resolver. `fallback` is a single lazy snapshot used only
+when no resolver is registered — keeps isolated tests working without forcing
+them to spin up the runtime. Mirrors cacheStoreSlot.
+*/
+export const pageSlot: {
+    resolver: (() => PageSnapshot | undefined) | undefined
+    fallback: PageSnapshot | undefined
+} = {
+    resolver: undefined,
+    fallback: undefined,
+}

package/src/lib/shared/setPageResolver.ts

@@ -0,0 +1,7 @@
+import { pageSlot } from './pageSlot.ts'
+import type { PageSnapshot } from './types/PageSnapshot.ts'
+
+// Registers the runtime's page resolver. Called once per side at boot.
+export function setPageResolver(fn: () => PageSnapshot | undefined): void {
+    pageSlot.resolver = fn
+}

package/src/lib/shared/types/PageSnapshot.ts

@@ -0,0 +1,11 @@
+/*
+Side-agnostic shape of the active page state: the matched route, its decoded
+params, and the live request/location URL. The browser `page` proxy reads its
+public fields through this; the server resolver reads them off the per-request
+store, the client resolver off the module singleton.
+*/
+export type PageSnapshot = {
+    route: string
+    params: Record<string, string>
+    url: URL
+}

package/src/serverEntry.ts

@@ -35,6 +35,7 @@ import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
 import { runningAsStandaloneBinary } from './lib/shared/runningAsStandaloneBinary.ts'
 import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
 import { setGlobalCacheStoreResolver } from './lib/shared/setGlobalCacheStoreResolver.ts'
+import { setPageResolver } from './lib/shared/setPageResolver.ts'
 
 /*
 Resolve config into process.env before anything reads it (createServer reads
@@ -67,6 +68,21 @@ exitWithParent()
 
 setCacheStoreResolver(() => requestContext.getStore()?.cache)
 
+/*
+Request-scoped page resolver: the `page` proxy reads route/params/url off the
+ALS store, so layout-scoped components see the live match during SSR without a
+module singleton leaking across concurrent or streaming renders. route/params
+land just before render; url is set at the request boundary, so 404/error
+renders still get a correct page.url.
+*/
+setPageResolver(() => {
+    const store = requestContext.getStore()
+    if (!store) {
+        return undefined
+    }
+    return { route: store.route ?? '', params: store.params ?? {}, url: store.url }
+})
+
 /*
 Process-level store for cache(fn, { global: true }) — one per server process,
 outlives every request so memoised external calls are shared across them.