@briancray/belte 0.1.0

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

@@ -0,0 +1,215 @@
+import type { Component } from 'svelte'
+import {
+    type NormalizedLayoutPrefix,
+    nearestLayoutPrefix,
+    normalizeLayoutPrefixes,
+} from '../shared/nearestLayoutPrefix.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.
+*/
+export type 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
+    mutable.url = new URL(window.location.href)
+}
+
+function syncUrl(): void {
+    const mutable = page as PageStateFor<string>
+    mutable.url = new URL(window.location.href)
+}
+
+type FetchOutcome =
+    | { kind: 'ok'; response: Response }
+    | { kind: 'network-error' }
+    | { kind: 'not-found' }
+    | { kind: 'http-error'; status: number }
+
+async function safeResolveFetch(target: string): Promise<FetchOutcome> {
+    let response: Response
+    try {
+        response = await fetch(target, { headers: { Accept: 'application/json' } })
+    } catch {
+        return { kind: 'network-error' }
+    }
+    if (response.status === 404) {
+        return { kind: 'not-found' }
+    }
+    if (!response.ok) {
+        return { kind: 'http-error', status: response.status }
+    }
+    return { kind: 'ok', response }
+}
+
+export type NavigateOptions = { replace?: boolean; scroll?: boolean }
+
+/*
+SPA navigation entrypoint. Writes history (push by default, replace on
+request), then resolves the new view. When only `search` or `hash` changes
+(same pathname), the JSON resolve fetch + loadView are skipped — only
+`page.url` is reassigned, so $derived consumers re-run without paying a
+network round-trip or remounting the page component. Falls back to a hard
+navigation if the resolve fetch or page-module import fails, mirroring the
+behaviour of the original click handler.
+*/
+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 (replace) {
+        window.history.replaceState(undefined, '', fullTarget)
+    } else {
+        window.history.pushState(undefined, '', fullTarget)
+    }
+    await applyTarget(target.pathname, fullTarget, scroll && !replace)
+}
+
+/*
+Called by both navigate() (after writing history) and the popstate handler
+(history is already current). When the pathname hasn't changed, the route
++ params + Page are the same; we just refresh `page.url`. A true pathname
+change triggers the JSON resolve fetch and a page swap.
+*/
+async function applyTarget(
+    pathname: string,
+    fullTarget: string,
+    resetScroll: boolean,
+): Promise<void> {
+    if (pathname === page.url.pathname) {
+        syncUrl()
+        return
+    }
+    const outcome = await safeResolveFetch(fullTarget)
+    if (outcome.kind !== 'ok') {
+        window.location.href = fullTarget
+        return
+    }
+    const result = (await outcome.response.json()) as SsrPayload
+    try {
+        const { Page, Layout } = await loadView(result.route)
+        applyState(result.route, result.params, Page, Layout)
+        if (resetScroll) {
+            window.scrollTo(0, 0)
+        }
+    } catch (err) {
+        console.error('[belte] navigation failed', err)
+        window.location.href = fullTarget
+    }
+}
+
+/*
+popstate fires after the browser has already restored the URL, so this just
+applies the current location without writing history again. 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, false)
+}

package/src/lib/browser/remoteProxy.ts

@@ -0,0 +1,44 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import type { RemoteFunction } from '../server/rpc/types/RemoteFunction.ts'
+import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import { createRemoteFunction } from '../shared/createRemoteFunction.ts'
+
+/*
+The browser stub is only emitted when the verb has `clients.browser:
+true`, so the value is always true here. mcp/cli flags are server-only
+discovery state and the browser bundle has no use for them; default
+false so the public RemoteFunction shape stays the same on both sides.
+*/
+const BROWSER_CLIENT_FLAGS = { browser: true, mcp: false, cli: false } as const
+
+/*
+Client-side substitute for a verb-defined handler. The bundler emits one
+call per verb export inside an `$rpc/**` module (GET / POST / …): server
+target uses defineVerb (real handler), browser target uses remoteProxy
+(fetch over the network). Both paths produce identical RemoteFunction
+shapes and identical WeakMap metadata so cache() works the same on either
+side.
+
+`url` is the flat rpc route. Args go in the JSON body (POST/PUT/PATCH) or
+the query string (GET/DELETE/HEAD). Plain `fn(args)` decodes the Response
+by Content-Type and throws HttpError on non-2xx; `.raw(args)` is the
+escape hatch that returns the Response untouched.
+*/
+export function remoteProxy<Args, Return>(
+    method: HttpVerb,
+    url: string,
+): RemoteFunction<Args, Return> {
+    return createRemoteFunction<Args, Return>({
+        method,
+        url,
+        clients: BROWSER_CLIENT_FLAGS,
+        buildRequest: (args) =>
+            buildRpcRequest({ method, url, args, baseUrl: window.location.href }),
+        /*
+        Forcing `getRequest()` once builds the Request and seeds the
+        cache meta thunk in createRemoteFunction with the same instance,
+        so cache() readers don't reconstruct it.
+        */
+        invoke: (_args, getRequest) => fetch(getRequest()),
+    })
+}

package/src/lib/browser/socketChannel.ts

@@ -0,0 +1,182 @@
+import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
+import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
+
+type SubCallbacks = {
+    onMessage(message: unknown): void
+    onError(message: string): void
+    onEnd(): void
+}
+
+type Channel = {
+    subscribe(
+        sub: string,
+        socket: string,
+        replay: number | undefined,
+        callbacks: SubCallbacks,
+    ): void
+    unsubscribe(sub: string): void
+    publish(socket: string, message: unknown): void
+}
+
+const SOCKETS_PATH = '/__belte/sockets'
+
+let singleton: Channel | undefined
+
+/*
+Lazily opens the single multiplexed ws used by every socket proxy on
+the page. Routes inbound frames:
+  `msg` → all local subs of that socket
+  `end` → the matching sub
+  `err` → the matching sub
+
+`msg` frames carry no sub id: one publish from the server fans out to
+every connected ws via Bun's native publish, and each ws delivers the
+message to every local sub of that socket. `end`/`err` are per-sub
+because they're subscription-lifecycle events, not data.
+
+Outbound frames sent before `ws.onopen` fires are queued and flushed
+on open. The channel reconnects on close with bounded backoff;
+in-flight subs are torn down with a synthetic error so consumers'
+`for await` loops can surface the disconnect, then the connection
+comes back up and fresh subs can be opened. We intentionally do not
+silently re-subscribe across a reconnect — most socket consumers need
+to reconcile state on a fresh connection (e.g. re-fetch a snapshot
+before reapplying deltas), so the framework hands the disconnect to
+user code instead of papering over it.
+*/
+export function getSocketChannel(): Channel {
+    if (singleton) {
+        return singleton
+    }
+    const subs = new Map<string, { socket: string; callbacks: SubCallbacks }>()
+    const subsBySocket = new Map<string, Set<string>>()
+    let ws: WebSocket | undefined
+    let pendingSends: string[] = []
+    let backoffMs = 250
+
+    function flushPending(): void {
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            return
+        }
+        for (const message of pendingSends) {
+            ws.send(message)
+        }
+        pendingSends = []
+    }
+
+    function send(frame: SocketClientFrame): void {
+        const message = JSON.stringify(frame)
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(message)
+            return
+        }
+        pendingSends.push(message)
+        connect()
+    }
+
+    function connect(): void {
+        if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+            return
+        }
+        const scheme = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+        ws = new WebSocket(`${scheme}//${window.location.host}${SOCKETS_PATH}`)
+        ws.addEventListener('open', () => {
+            backoffMs = 250
+            flushPending()
+        })
+        ws.addEventListener('message', (event) => {
+            let frame: SocketServerFrame
+            try {
+                frame = JSON.parse(event.data) as SocketServerFrame
+            } catch {
+                return
+            }
+            if (frame.type === 'msg') {
+                /*
+                One Bun-published frame fans out to every local sub of
+                that socket on this ws — addressed by socket name, not
+                per-sub id.
+                */
+                const targets = subsBySocket.get(frame.socket)
+                if (!targets) {
+                    return
+                }
+                for (const subId of targets) {
+                    subs.get(subId)?.callbacks.onMessage(frame.message)
+                }
+                return
+            }
+            if (frame.type === 'end') {
+                const sub = subs.get(frame.sub)
+                if (!sub) {
+                    return
+                }
+                dropSub(frame.sub)
+                sub.callbacks.onEnd()
+                return
+            }
+            if (frame.type === 'err') {
+                const sub = subs.get(frame.sub)
+                if (!sub) {
+                    return
+                }
+                dropSub(frame.sub)
+                sub.callbacks.onError(frame.message)
+                return
+            }
+        })
+        ws.addEventListener('close', () => {
+            const active = [...subs.entries()]
+            subs.clear()
+            subsBySocket.clear()
+            for (const [, sub] of active) {
+                sub.callbacks.onError('socket channel disconnected')
+            }
+            ws = undefined
+            if (active.length === 0 && pendingSends.length === 0) {
+                return
+            }
+            setTimeout(connect, backoffMs)
+            backoffMs = Math.min(backoffMs * 2, 5000)
+        })
+    }
+
+    function dropSub(id: string): void {
+        const entry = subs.get(id)
+        if (!entry) {
+            return
+        }
+        subs.delete(id)
+        const set = subsBySocket.get(entry.socket)
+        if (set) {
+            set.delete(id)
+            if (set.size === 0) {
+                subsBySocket.delete(entry.socket)
+            }
+        }
+    }
+
+    singleton = {
+        subscribe(id, socket, replay, callbacks) {
+            subs.set(id, { socket, callbacks })
+            let set = subsBySocket.get(socket)
+            if (!set) {
+                set = new Set()
+                subsBySocket.set(socket, set)
+            }
+            set.add(id)
+            send({ type: 'sub', sub: id, socket, replay })
+        },
+        unsubscribe(id) {
+            if (!subs.has(id)) {
+                return
+            }
+            dropSub(id)
+            send({ type: 'unsub', sub: id })
+        },
+        publish(socket, message) {
+            send({ type: 'pub', socket, message })
+        },
+    }
+    return singleton
+}

package/src/lib/browser/socketProxy.ts

@@ -0,0 +1,64 @@
+import type { Socket } from '../server/sockets/types/Socket.ts'
+import { createPushIterator } from '../shared/createPushIterator.ts'
+import { getSocketChannel } from './socketChannel.ts'
+
+let nextId = 0
+
+/*
+Browser stub is only emitted when `clients.browser: true`, so the value
+is always true here. mcp/cli flags are server-only discovery state; the
+browser bundle has no use for them. Default false so the public Socket
+shape stays consistent on both sides.
+*/
+const BROWSER_CLIENT_FLAGS = { browser: true, mcp: false, cli: false } as const
+
+/*
+Client-side substitute for a server-declared Socket. The bundler emits
+one call per socket export under `src/server/sockets/`: server target uses
+defineSocket (real fan-out), browser target uses socketProxy (subscribe
+over the multiplexed ws channel). Both paths produce identical Socket
+shapes so user code reads the same on either side.
+
+Bare iteration opens a subscription with full history replay; `.tail(n)`
+opens one that replays the last `n` items (default `0`, clamped server-
+side to the topic's history max). Each subscription mints its own id
+used to route lifecycle frames (`end`, `err`). Calling `.publish` sends
+a `pub` frame the server validates against the topic's
+`allowClientPublish` policy — there is no client-side enforcement, so a
+publish attempt on a server-only topic is silently dropped server-side.
+
+Backpressure is unbounded — a slow consumer with a chatty socket will
+grow the per-iterator buffer; bounded policies belong in a future
+socketProxy API, not the wire layer.
+*/
+export function socketProxy<T>(name: string): Socket<T> {
+    /*
+    replay === undefined → full history replay (bare for-await);
+    replay: number → trailing-n replay, clamped by the server.
+    */
+    function iterate(replay: number | undefined): AsyncIterable<T> {
+        return {
+            [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
+                const id = `s${++nextId}`
+                const channel = getSocketChannel()
+                const iter = createPushIterator<T>(() => channel.unsubscribe(id))
+                channel.subscribe(id, name, replay, {
+                    onMessage: (value) => iter.push(value as T),
+                    onEnd: () => iter.end(),
+                    onError: (message) => iter.error(message),
+                })
+                return iter
+            },
+        }
+    }
+
+    return {
+        name,
+        clients: BROWSER_CLIENT_FLAGS,
+        publish(message: T) {
+            getSocketChannel().publish(name, message)
+        },
+        tail: (count = 0) => iterate(count),
+        [Symbol.asyncIterator]: () => iterate(undefined)[Symbol.asyncIterator](),
+    }
+}

package/src/lib/browser/startClient.ts

@@ -0,0 +1,132 @@
+import { hydrate } from 'svelte'
+import App from '../../App.svelte'
+import { createCacheStore } from '../shared/createCacheStore.ts'
+import { setCacheStoreResolver } from '../shared/setCacheStoreResolver.ts'
+import type { CacheSnapshotEntry } from '../shared/types/CacheSnapshotEntry.ts'
+import type { CacheStore } from '../shared/types/CacheStore.ts'
+import { bindPage, handlePopstate, navigate, page, renderState } from './page.svelte.ts'
+import type { Layouts } from './types/Layouts.ts'
+import type { Pages } from './types/Pages.ts'
+
+declare global {
+    interface Window {
+        __SSR__: {
+            route: string
+            params: Record<string, string>
+            cache?: CacheSnapshotEntry[]
+        }
+    }
+}
+
+/*
+Pre-populates the client cache store with response entries captured during
+SSR. Each entry becomes an already-resolved Response so the first hydration
+pass finds the data via cache() without issuing a network round-trip.
+*/
+function hydrateCacheFromSnapshot(store: CacheStore, snapshot: CacheSnapshotEntry[]): void {
+    for (const entry of snapshot) {
+        const response = new Response(entry.body, {
+            status: entry.status,
+            statusText: entry.statusText,
+            headers: new Headers(entry.headers),
+        })
+        store.entries.set(entry.key, {
+            key: entry.key,
+            promise: Promise.resolve(response),
+            request: new Request(entry.url, { method: entry.method }),
+            ttl: undefined,
+            expiresAt: undefined,
+        })
+    }
+}
+
+function isInternalLinkEvent(event: MouseEvent): HTMLAnchorElement | undefined {
+    if (event.defaultPrevented) {
+        return undefined
+    }
+    if (event.button !== 0) {
+        return undefined
+    }
+    if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) {
+        return undefined
+    }
+    const anchor = (event.target as HTMLElement | null)?.closest?.('a')
+    if (!anchor) {
+        return undefined
+    }
+    if (anchor.target && anchor.target !== '_self') {
+        return undefined
+    }
+    if (anchor.hasAttribute('download')) {
+        return undefined
+    }
+    if (anchor.getAttribute('rel')?.includes('external')) {
+        return undefined
+    }
+    const href = anchor.getAttribute('href')
+    if (!href || href.startsWith('#')) {
+        return undefined
+    }
+    const url = new URL(href, window.location.href)
+    if (url.origin !== window.location.origin) {
+        return undefined
+    }
+    return anchor
+}
+
+/*
+Hydrates the SSR'd document against the SSR payload on `window.__SSR__`,
+then intercepts internal link clicks (delegating to navigate) and popstate
+events. The page module owns the route/Page/Layout state and the
+URL-resolution logic; this entry just wires the cache store, runs the
+initial bind, and attaches the global listeners. App.svelte receives the
+public `page` proxy plus the internal renderState so the same reactive
+objects update across navigations.
+*/
+export async function startClient({
+    pages,
+    layouts,
+}: {
+    pages: Pages
+    layouts?: Layouts
+}): Promise<void> {
+    const target = document.getElementById('app')
+    if (!target) {
+        throw new Error('[belte] missing #app target')
+    }
+
+    const cacheStore = createCacheStore()
+    setCacheStoreResolver(() => cacheStore)
+    if (window.__SSR__.cache) {
+        hydrateCacheFromSnapshot(cacheStore, window.__SSR__.cache)
+    }
+
+    try {
+        await bindPage({ pages, layouts, ssr: window.__SSR__ })
+        hydrate(App, { target, props: { state: { page, render: renderState } } })
+    } catch (err) {
+        console.error('[belte] initial hydration failed', err)
+    }
+
+    document.addEventListener('click', (event) => {
+        const anchor = isInternalLinkEvent(event)
+        if (!anchor) {
+            return
+        }
+        const url = new URL(anchor.href, window.location.href)
+        /*
+        Hash-only same-page navigations fall through to the browser so the
+        native scroll-into-view for `#anchor` targets keeps working.
+        Anything else (pathname, search, or pathname+hash combo) goes
+        through navigate() — it pushes history, refreshes page state, and
+        short-circuits the JSON resolve when only search/hash differ.
+        */
+        if (url.pathname === window.location.pathname && url.search === window.location.search) {
+            return
+        }
+        event.preventDefault()
+        void navigate(`${url.pathname}${url.search}${url.hash}`)
+    })
+
+    window.addEventListener('popstate', handlePopstate)
+}