@belte/belte 0.19.0

package/src/devEntry.ts

@@ -0,0 +1,169 @@
+import { watch } from 'node:fs'
+import type { Subprocess } from 'bun'
+import { build } from './build.ts'
+import { DEFAULT_PORT } from './lib/server/runtime/DEFAULT_PORT.ts'
+import { DEV_REBUILD_MESSAGE } from './lib/server/runtime/DEV_REBUILD_MESSAGE.ts'
+import { findOpenPort } from './lib/server/runtime/findOpenPort.ts'
+import { log } from './lib/shared/log.ts'
+
+/*
+Dev orchestrator. Replaces `bun --watch` (which only watches the import graph,
+so new files / CSS / public assets never triggered a restart) with an explicit
+loop we own end to end:
+
+  1. Build the client once — uncompressed, unminified (zstd-22 on every rebuild
+     dwarfs the bundle; the server serves the plain bytes when no .zst exists).
+  2. Spawn the server as a child against a fixed dev port and BELTE_DEV=1, which
+     makes it mount the /__belte/dev live-reload channel.
+  3. Watch src/ recursively. On any change, rebuild then restart the child. SSR
+     renders pages through Bun's module cache, so a fresh module graph (a new
+     process) is the reliable way to reflect a source edit — Bun has no stable
+     in-process invalidation. The browser reconnects to the restarted server's
+     live-reload channel and reloads itself.
+
+Restarts are serialized (a build mid-flight queues the next) and the port is
+fixed so the browser tab stays valid across restarts. A failed build keeps the
+last-good server running rather than tearing the loop down.
+*/
+const cwd = process.cwd()
+const PRELOAD = new URL('./preload.ts', import.meta.url).pathname
+const SERVER_ENTRY = new URL('./serverEntry.ts', import.meta.url).pathname
+const SOURCE_DIR = `${cwd}/src`
+// Coalesce editor save bursts (and multi-file saves) into one rebuild.
+const REBUILD_DEBOUNCE_MS = 60
+/*
+Generated dir the build itself writes into src/ (route type declarations). It
+must be ignored or each rebuild's write retriggers the watcher — an endless
+rebuild loop.
+*/
+const GENERATED_DIR = '.belte'
+
+// True for paths under src/.belte (the build's own generated output).
+function isGenerated(filename: string): boolean {
+    return filename.split(/[\\/]/).includes(GENERATED_DIR)
+}
+
+// clean:false leaves the live dist in place — each build swaps _app in atomically,
+// so the running server never serves a half-built or emptied bundle.
+const buildOptions = {
+    cwd,
+    minify: false,
+    compress: false,
+    clean: false,
+    exitOnFailure: false,
+} as const
+
+let server: Subprocess | undefined
+
+function startServer(port: number): void {
+    server = Bun.spawn({
+        cmd: ['bun', '--preload', PRELOAD, SERVER_ENTRY],
+        cwd,
+        env: { ...process.env, PORT: String(port), BELTE_DEV: '1' },
+        stdio: ['inherit', 'inherit', 'inherit'],
+        // The child's POST /__belte/reload route signals a rebuild over IPC, so the
+        // trigger rides the app's own port instead of a side channel.
+        ipc(message) {
+            if (message === DEV_REBUILD_MESSAGE) {
+                void rebuild(port)
+            }
+        },
+    })
+}
+
+/* Terminate the running child and wait for it to free the port (SIGKILL watchdog for a wedged exit). */
+async function stopServer(): Promise<void> {
+    if (!server) {
+        return
+    }
+    const dying = server
+    server = undefined
+    dying.kill()
+    const watchdog = setTimeout(() => dying.kill('SIGKILL'), 3000)
+    await dying.exited
+    clearTimeout(watchdog)
+}
+
+let building = false
+let queued = false
+
+/*
+Rebuild the client, then (on success) restart the server child. Serialized: a
+change arriving mid-build sets `queued` so exactly one more rebuild runs after,
+collapsing any further changes in between. A failed build leaves the current
+child untouched — the error is logged and the last-good server keeps serving.
+*/
+async function rebuild(port: number): Promise<void> {
+    if (building) {
+        queued = true
+        return
+    }
+    building = true
+    try {
+        const succeeded = await build(buildOptions)
+        if (succeeded) {
+            await stopServer()
+            startServer(port)
+        }
+    } finally {
+        building = false
+        if (queued) {
+            queued = false
+            void rebuild(port)
+        }
+    }
+}
+
+/*
+Pick a free port once and reuse it for every restart, so the browser tab keeps
+pointing at the same address. Scans upward from the shared default so dev lands
+on the same predictable 3000+ address as `bun start`; reusing the number across
+restarts (not re-scanning) is what keeps the tab valid.
+*/
+const port = findOpenPort(DEFAULT_PORT)
+const firstBuild = await build(buildOptions)
+if (!firstBuild) {
+    log.warn('initial build failed — fix the error and save to retry')
+}
+startServer(port)
+
+/*
+BELTE_DEV_NO_WATCH=1 skips the fs watcher: rebuild only on demand via POST
+/__belte/reload (always mounted under dev), so a long-lived in-process job — e.g.
+an agent editing the app's own source — isn't yanked mid-run by a save.
+*/
+const manualRebuild = Bun.env.BELTE_DEV_NO_WATCH === '1'
+
+let debounce: ReturnType<typeof setTimeout> | undefined
+const watcher = manualRebuild
+    ? undefined
+    : watch(SOURCE_DIR, { recursive: true }, (_event, filename) => {
+          if (!filename || isGenerated(filename)) {
+              return
+          }
+          clearTimeout(debounce)
+          debounce = setTimeout(() => void rebuild(port), REBUILD_DEBOUNCE_MS)
+      })
+if (manualRebuild) {
+    log.info(`manual rebuild mode — POST http://localhost:${port}/__belte/reload to apply changes`)
+}
+
+/* Tear down the watcher and the child on shutdown so neither outlives the orchestrator. */
+const shutdown = async () => {
+    watcher?.close()
+    await stopServer()
+    process.exit(0)
+}
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)
+process.on('SIGHUP', shutdown)
+
+/*
+Last-resort sync cleanup: Bun.spawn'd children aren't reaped when the parent
+dies, so a crash (uncaught error, terminal close) would otherwise leave the
+server holding the dev port. 'exit' fires for every exit path; kill is
+synchronous, which is enough to signal the child before we go.
+*/
+process.on('exit', () => {
+    server?.kill()
+})

package/src/discoveryEntry.ts

@@ -0,0 +1,81 @@
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { rpc } from './_virtual/rpc.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { sockets } from './_virtual/sockets.ts'
+import type { CliManifestEntry } from './lib/cli/types/CliManifestEntry.ts'
+import { verbRegistry } from './lib/server/rpc/verbRegistry.ts'
+import { socketOperations } from './lib/server/sockets/socketOperations.ts'
+import { socketRegistry } from './lib/server/sockets/socketRegistry.ts'
+import { commandNameForUrl } from './lib/shared/commandNameForUrl.ts'
+import { jsonSchemaForSchema } from './lib/shared/jsonSchemaForSchema.ts'
+
+/*
+One-shot script that imports every rpc + socket module so defineVerb /
+defineSocket populate the process-wide registries, then prints the CLI
+manifest to stdout as JSON. Used by buildCli to bake the manifest into
+the standalone binary at build time without resorting to static source
+parsing (which can't see toJsonSchema()/toJSONSchema() at compile time).
+*/
+await Promise.all([
+    ...Object.values(rpc).map((loader) => (loader as () => Promise<unknown>)()),
+    ...Object.values(sockets).map((loader) => (loader as () => Promise<unknown>)()),
+])
+
+const manifest: Record<string, CliManifestEntry> = {}
+
+for (const entry of verbRegistry.values()) {
+    if (!entry.clients.cli) {
+        continue
+    }
+    manifest[commandNameForUrl(entry.remote.url)] = {
+        method: entry.remote.method,
+        url: entry.remote.url,
+        jsonSchema: jsonSchemaForSchema(entry.inputSchema),
+    }
+}
+
+/*
+Sockets advertised to the CLI become commands against the socket's HTTP
+face (see socketOperations): `<base>-tail` streams live (GET +
+text/event-stream, with an optional --tail N to replay recent history
+first) and, when clientPublish is set, `<base>-publish` sends the args bag
+as a message (POST).
+*/
+for (const entry of socketRegistry.values()) {
+    if (!entry.clients.cli) {
+        continue
+    }
+    for (const operation of socketOperations(entry)) {
+        if (operation.kind === 'tail') {
+            manifest[operation.name] = {
+                method: operation.method,
+                url: operation.restUrl,
+                accept: 'text/event-stream',
+                jsonSchema: {
+                    type: 'object',
+                    description: `tail the "${operation.socketName}" socket`,
+                    properties: {
+                        tail: {
+                            type: 'number',
+                            description: 'replay last N messages before tailing live',
+                        },
+                    },
+                },
+            }
+            continue
+        }
+        const payloadSchema = jsonSchemaForSchema(entry.schema)
+        manifest[operation.name] = {
+            method: operation.method,
+            url: operation.restUrl,
+            jsonSchema: {
+                ...payloadSchema,
+                description:
+                    (payloadSchema.description as string | undefined) ??
+                    `publish a message to the "${operation.socketName}" socket`,
+            },
+        }
+    }
+}
+
+process.stdout.write(JSON.stringify(manifest))

package/src/lib/browser/applyStreamedResolution.ts

@@ -0,0 +1,33 @@
+import { invalidateEvent } from '../shared/invalidateEvent.ts'
+import type { CacheStore } from '../shared/types/CacheStore.ts'
+import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
+import { cacheEntryFromSnapshot } from './cacheEntryFromSnapshot.ts'
+import { refetchPlaceholder } from './refetchPlaceholder.ts'
+import type { StreamingDeferred } from './types/StreamingDeferred.ts'
+
+/*
+Settles one streamed resolution against its placeholder. A snapshot overwrites
+the placeholder with a warm entry (so re-renders and later reads are sync) and
+fires an invalidate to re-run any read mounted before it arrived; a miss
+re-fetches the request live. Either way it resolves the deferred so a {#await}
+already awaiting the placeholder promise unblocks, and removes it from the
+registry so a later flush only touches genuine leftovers.
+*/
+export function applyStreamedResolution(
+    store: CacheStore,
+    deferreds: Map<string, StreamingDeferred>,
+    resolution: StreamedResolution,
+): void {
+    const deferred = deferreds.get(resolution.key)
+    deferreds.delete(resolution.key)
+    if ('miss' in resolution) {
+        if (deferred) {
+            refetchPlaceholder(deferred)
+        }
+        return
+    }
+    const entry = cacheEntryFromSnapshot(resolution)
+    store.entries.set(resolution.key, entry)
+    deferred?.resolve(entry.promise as Promise<Response>)
+    store.events.dispatchEvent(invalidateEvent([resolution.key]))
+}

package/src/lib/browser/cacheEntryFromSnapshot.ts

@@ -0,0 +1,48 @@
+import type { CacheEntry } from '../shared/types/CacheEntry.ts'
+import type { CacheSnapshotEntry } from '../shared/types/CacheSnapshotEntry.ts'
+
+/*
+Rebuilds a warm cache entry from a wire snapshot: an already-resolved Response
+plus the synchronously-decoded warm value, so cache() reads it without a network
+round-trip or a microtask hop. Shared by the initial inline snapshot hydration
+and the streamed resolution path. `settled` is true — the body shipped fully
+resolved either way.
+*/
+export function cacheEntryFromSnapshot(entry: CacheSnapshotEntry): CacheEntry {
+    const headers = new Headers(entry.headers)
+    const response = new Response(entry.body, {
+        status: entry.status,
+        statusText: entry.statusText,
+        headers,
+    })
+    return {
+        key: entry.key,
+        promise: Promise.resolve(response),
+        request: new Request(entry.url, { method: entry.method }),
+        ttl: undefined,
+        expiresAt: undefined,
+        value: warmValueFromSnapshot(entry.status, headers, entry.body),
+        settled: true,
+    }
+}
+
+/*
+Synchronously decodes a snapshot body so the warm entry reads without a
+microtask hop on first render. Mirrors decodeResponse for the textual cases the
+snapshot ships; non-2xx and 204 yield no warm value and fall back to the async
+path, which throws HttpError / returns undefined exactly as a live call would.
+Binary/xml bodies also skip the warm path and decode asynchronously.
+*/
+function warmValueFromSnapshot(status: number, headers: Headers, body: string): unknown {
+    if (status === 204 || status < 200 || status >= 300) {
+        return undefined
+    }
+    const contentType = (headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.includes('json')) {
+        return JSON.parse(body)
+    }
+    if (contentType.startsWith('text/')) {
+        return body
+    }
+    return undefined
+}

package/src/lib/browser/flushUnresolvedPlaceholders.ts

@@ -0,0 +1,16 @@
+import { refetchPlaceholder } from './refetchPlaceholder.ts'
+import type { StreamingDeferred } from './types/StreamingDeferred.ts'
+
+/*
+Drains any placeholder the resolution stream never settled — a clean EOF with
+leftovers, or a cut (idleTimeout cap, dropped connection). Each unresolved
+deferred re-fetches its request live, so the {#await} resolves from a normal
+request instead of hanging on a deferred that will never settle. A fully-drained
+stream leaves the registry empty, so this is a no-op then.
+*/
+export function flushUnresolvedPlaceholders(deferreds: Map<string, StreamingDeferred>): void {
+    for (const deferred of deferreds.values()) {
+        refetchPlaceholder(deferred)
+    }
+    deferreds.clear()
+}

package/src/lib/browser/installStreamingPlaceholders.ts

@@ -0,0 +1,32 @@
+import type { CacheStore } from '../shared/types/CacheStore.ts'
+import type { StreamingPlaceholder } from '../shared/types/StreamingPlaceholder.ts'
+import type { StreamingDeferred } from './types/StreamingDeferred.ts'
+
+/*
+Pre-creates a deferred cache entry per pending key before hydration. cache()
+finds the placeholder (a pending promise, no warm value) and returns it instead
+of firing a fetch, so the {#await} awaits the resolution stream rather than
+racing it with a duplicate request. Returns the registry the resolver settles.
+*/
+export function installStreamingPlaceholders(
+    store: CacheStore,
+    placeholders: StreamingPlaceholder[],
+): Map<string, StreamingDeferred> {
+    const deferreds = new Map<string, StreamingDeferred>()
+    for (const placeholder of placeholders) {
+        const request = new Request(placeholder.url, { method: placeholder.method })
+        let resolve!: StreamingDeferred['resolve']
+        const promise = new Promise<Response>((settle) => {
+            resolve = settle
+        })
+        store.entries.set(placeholder.key, {
+            key: placeholder.key,
+            promise,
+            request,
+            ttl: undefined,
+            expiresAt: undefined,
+        })
+        deferreds.set(placeholder.key, { resolve, request })
+    }
+    return deferreds
+}

package/src/lib/browser/openResolveStream.ts

@@ -0,0 +1,42 @@
+import { RESOLVE_STREAM_PATH } from '../shared/RESOLVE_STREAM_PATH.ts'
+import { streamResponse } from '../shared/streamResponse.ts'
+import type { CacheStore } from '../shared/types/CacheStore.ts'
+import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
+import { applyStreamedResolution } from './applyStreamedResolution.ts'
+import { flushUnresolvedPlaceholders } from './flushUnresolvedPlaceholders.ts'
+import { setPageStreamController } from './pageStreamController.ts'
+import type { StreamingDeferred } from './types/StreamingDeferred.ts'
+
+/*
+Opens the out-of-band resolution stream (token from `__SSR__.streamToken`) and
+applies each StreamedResolution to its placeholder as it arrives. The stream is
+NDJSON, so it shares the canonical `streamResponse` frame parser the rpc/CLI/MCP
+drains use rather than re-implementing line framing. The reader gives a reliable
+end signal the inline document stream couldn't: on clean EOF or a cut (a non-ok
+response or mid-stream error throws here), any still-pending placeholder
+re-fetches live; on abort (navigation) the gone page's reads are left alone.
+Registered with setPageStreamController so a navigation can cancel it and free
+the connection.
+*/
+export async function openResolveStream(
+    token: string,
+    store: CacheStore,
+    deferreds: Map<string, StreamingDeferred>,
+): Promise<void> {
+    const controller = new AbortController()
+    setPageStreamController(controller)
+    try {
+        const response = await fetch(`${RESOLVE_STREAM_PATH}${token}`, {
+            signal: controller.signal,
+        })
+        for await (const resolution of streamResponse<StreamedResolution>(response)) {
+            applyStreamedResolution(store, deferreds, resolution)
+        }
+    } catch {
+        // Navigated away mid-stream — the page is gone; don't re-fetch its reads.
+    }
+    // Clean EOF or a cut (non-abort error): re-fetch anything still pending.
+    if (!controller.signal.aborted) {
+        flushUnresolvedPlaceholders(deferreds)
+    }
+}

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

@@ -0,0 +1,258 @@
+import type { Component } from 'svelte'
+import {
+    type NormalizedLayoutPrefix,
+    nearestLayoutPrefix,
+    normalizeLayoutPrefixes,
+} from '../shared/nearestLayoutPrefix.ts'
+import { abortPageStream } from './pageStreamController.ts'
+import type { Layouts } from './types/Layouts.ts'
+import type { Pages } from './types/Pages.ts'
+
+/*
+Augmentable route table. The codegen step emits a `declare module 'belte/browser/page'`
+block that fills this interface with `routePath: paramShape` pairs derived
+from the project's `src/browser/pages/**` tree. A bare belte install has no routes,
+so the fallback arm below keeps the union inhabited before the generated
+d.ts lands.
+
+Declared as an `interface` (not a `type` alias) because the generated d.ts
+augments it via `declare module … { interface Routes { … } }`, and module
+augmentation only merges into interfaces.
+*/
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated routes.d.ts
+export interface Routes {}
+
+type RouteKey = keyof Routes extends never ? string : keyof Routes
+type ParamsFor<R extends RouteKey> = R extends keyof Routes ? Routes[R] : Record<string, string>
+
+type PageStateFor<R extends RouteKey> = {
+    route: R
+    params: ParamsFor<R>
+    url: URL
+}
+
+/*
+Discriminated union keyed on `route`, so consumers that narrow on `page.route`
+get the matching `page.params` shape automatically. `url` is the live
+WHATWG URL for the currently-displayed location; navigation reassigns the
+reference so $derived subscribers re-run on every nav (not just on the
+fields they happen to touch).
+*/
+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>({
+    route: '',
+    params: {},
+    url: new URL('http://localhost/'),
+})
+
+/*
+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`
+shape; users only ever see route/params/url.
+*/
+export const renderState = $state<{
+    Layout: Component | undefined
+    Page: Component | undefined
+}>({
+    Layout: undefined,
+    Page: undefined,
+})
+
+let boundPages: Pages | undefined
+let boundLayouts: Layouts | undefined
+let layoutPrefixes: NormalizedLayoutPrefix[] = []
+
+type SsrPayload = { route: string; params: Record<string, string> }
+
+/*
+Wires the route + layout tables produced by the bundler's virtual manifests
+and seeds page state from the SSR payload. Called once from startClient
+before `hydrate(App)` so the first render sees Page/Layout/params already
+populated. Subsequent `navigate()` calls reuse `boundPages` / `boundLayouts`.
+*/
+export async function bindPage({
+    pages,
+    layouts,
+    ssr,
+}: {
+    pages: Pages
+    layouts?: Layouts
+    ssr: SsrPayload
+}): Promise<void> {
+    boundPages = pages
+    boundLayouts = layouts
+    layoutPrefixes = layouts ? normalizeLayoutPrefixes(Object.keys(layouts)) : []
+    const { Page, Layout } = await loadView(ssr.route)
+    applyState(ssr.route, ssr.params, Page, Layout)
+}
+
+async function loadView(
+    route: string,
+): Promise<{ Page: Component; Layout: Component | undefined }> {
+    if (!boundPages) {
+        throw new Error('[belte] page is not initialized — call bindPage first')
+    }
+    const pageLoader = boundPages[route]
+    if (!pageLoader) {
+        throw new Error(`[belte] unknown route: ${route}`)
+    }
+    const layoutPrefix = nearestLayoutPrefix(route, layoutPrefixes)
+    const [pageMod, layoutMod] = await Promise.all([
+        pageLoader(),
+        layoutPrefix && boundLayouts ? boundLayouts[layoutPrefix]() : Promise.resolve(undefined),
+    ])
+    return { Page: pageMod.default, Layout: layoutMod?.default }
+}
+
+function applyState(
+    route: string,
+    params: Record<string, string>,
+    Page: Component,
+    Layout: Component | undefined,
+): void {
+    renderState.Layout = Layout
+    renderState.Page = Page
+    const mutable = page as PageStateFor<string>
+    mutable.route = route
+    mutable.params = params
+    syncUrl()
+}
+
+function syncUrl(): void {
+    const mutable = page as PageStateFor<string>
+    mutable.url = new URL(window.location.href)
+}
+
+/*
+Resolves the JSON view payload for a target URL, or undefined when the fetch
+fails for any reason (network error or non-2xx, including 404). The caller
+falls back to a hard navigation in every failure case, so the failure modes
+don't need to be distinguished.
+*/
+async function safeResolveFetch(target: string): Promise<Response | undefined> {
+    try {
+        const response = await fetch(target, { headers: { Accept: 'application/json' } })
+        return response.ok ? response : undefined
+    } catch {
+        return undefined
+    }
+}
+
+function hasRoute(route: string): boolean {
+    return Boolean(boundPages?.[route])
+}
+
+type ResolvedView = {
+    route: string
+    params: Record<string, string>
+    Page: Component
+    Layout: Component | undefined
+}
+
+/*
+Resolves a target into the Page/Layout components to render, or undefined
+when the target isn't an SPA route: the resolve fetch failed, the body wasn't
+a known route (e.g. a raw JSON endpoint that 200s on `Accept: json`), or the
+page module import threw. Callers fall back to a hard navigation in every
+undefined case. A missing/unknown route is expected and stays silent; a known
+route whose module fails to import is a real error and is surfaced.
+*/
+async function resolveView(fullTarget: string): Promise<ResolvedView | undefined> {
+    const response = await safeResolveFetch(fullTarget)
+    if (!response) {
+        return undefined
+    }
+    const result = (await response.json()) as SsrPayload
+    if (!result.route || !hasRoute(result.route)) {
+        return undefined
+    }
+    try {
+        const { Page, Layout } = await loadView(result.route)
+        return { route: result.route, params: result.params, Page, Layout }
+    } catch (err) {
+        console.error('[belte] navigation failed', err)
+        return undefined
+    }
+}
+
+function writeHistory(replace: boolean, fullTarget: string): void {
+    if (replace) {
+        window.history.replaceState(undefined, '', fullTarget)
+    } else {
+        window.history.pushState(undefined, '', fullTarget)
+    }
+}
+
+export type NavigateOptions = { replace?: boolean; scroll?: boolean }
+
+/*
+SPA navigation entrypoint. When only `search` or `hash` changes (same
+pathname) the JSON resolve fetch + loadView are skipped — history is written
+and `page.url` reassigned so $derived consumers re-run without a network
+round-trip or page remount. On a pathname change the target view is resolved
+*before* history is touched: a non-SPA target (raw JSON endpoint, unknown
+route, failed import) hard-navigates cleanly via `location.href`, because a
+pushed entry whose URL no longer matches its in-memory document corrupts
+back/forward (Safari restores the stale document under the new URL).
+*/
+export async function navigate(href: string, options: NavigateOptions = {}): Promise<void> {
+    const { replace = false, scroll = true } = options
+    const target = new URL(href, window.location.href)
+    if (target.origin !== window.location.origin) {
+        window.location.href = href
+        return
+    }
+    const fullTarget = `${target.pathname}${target.search}${target.hash}`
+    if (target.pathname === page.url.pathname) {
+        writeHistory(replace, fullTarget)
+        syncUrl()
+        return
+    }
+    /* Leaving this page: cancel its still-open resolution stream (if any) so the
+    connection frees instead of running to completion for a page that's gone. */
+    abortPageStream()
+    const view = await resolveView(fullTarget)
+    if (!view) {
+        window.location.href = fullTarget
+        return
+    }
+    writeHistory(replace, fullTarget)
+    applyState(view.route, view.params, view.Page, view.Layout)
+    if (scroll && !replace) {
+        window.scrollTo(0, 0)
+    }
+}
+
+/*
+popstate fires after the browser has already restored the URL, so this never
+writes history — it just applies the current location. A same-pathname change
+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) {
+        syncUrl()
+        return
+    }
+    abortPageStream()
+    const view = await resolveView(fullTarget)
+    if (!view) {
+        window.location.href = fullTarget
+        return
+    }
+    applyState(view.route, view.params, view.Page, view.Layout)
+}
+
+/*
+popstate fires after the browser has already restored the URL. Scroll
+position is left alone — the browser's built-in history scroll restoration
+wins for back/forward.
+*/
+export function handlePopstate(): void {
+    const fullTarget = `${window.location.pathname}${window.location.search}${window.location.hash}`
+    void applyTarget(window.location.pathname, fullTarget)
+}