@belte/belte 0.19.0

package/src/lib/browser/pageStreamController.ts

@@ -0,0 +1,17 @@
+/*
+Holds the AbortController for the current page's resolution stream so a
+client-side navigation can cancel it — freeing the connection and stopping the
+server drain — instead of letting it run to completion for a page that's gone.
+Setting a new controller aborts any prior one.
+*/
+let current: AbortController | undefined
+
+export function setPageStreamController(controller: AbortController): void {
+    current?.abort()
+    current = controller
+}
+
+export function abortPageStream(): void {
+    current?.abort()
+    current = undefined
+}

package/src/lib/browser/refetchPlaceholder.ts

@@ -0,0 +1,12 @@
+import type { StreamingDeferred } from './types/StreamingDeferred.ts'
+
+/*
+The single placeholder-recovery primitive: settles a deferred {#await} read with
+a live re-fetch of its request. Used whenever a streamed resolution can't supply
+warm data — a `{ key, miss }` marker (non-snapshottable body) or a placeholder
+the stream never settled (clean EOF with leftovers, or a cut). Keeping the
+re-fetch policy in one place means the apply path and the flush path can't drift.
+*/
+export function refetchPlaceholder(deferred: StreamingDeferred): void {
+    deferred.resolve(fetch(deferred.request))
+}

package/src/lib/browser/remoteProxy.ts

@@ -0,0 +1,37 @@
+import { browserClientFlags } from '../shared/browserClientFlags.ts'
+import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import { createRemoteFunction } from '../shared/createRemoteFunction.ts'
+import type { HttpVerb } from '../shared/types/HttpVerb.ts'
+import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
+
+/*
+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: browserClientFlags,
+        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,192 @@
+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')
+            }
+            /*
+            Drop any queued frames too. We've just torn down every local
+            sub, so replaying their `sub`/`unsub`/`pub` frames on
+            reconnect would open ghost subscriptions on the server that
+            no client object tracks (and never gets an `unsub`). This
+            keeps the "no silent re-subscribe across a reconnect"
+            contract above honest — consumers re-open fresh subs.
+            */
+            const hadPending = pendingSends.length > 0
+            pendingSends = []
+            ws = undefined
+            if (active.length === 0 && !hadPending) {
+                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,57 @@
+import type { Socket } from '../server/sockets/types/Socket.ts'
+import { browserClientFlags } from '../shared/browserClientFlags.ts'
+import { createPushIterator } from '../shared/createPushIterator.ts'
+import { getSocketChannel } from './socketChannel.ts'
+
+let nextId = 0
+
+/*
+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: browserClientFlags,
+        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,153 @@
+import { hydrate } from 'svelte'
+import App from '../../App.svelte'
+import { createCacheStore } from '../shared/createCacheStore.ts'
+import { setCacheStoreResolver } from '../shared/setCacheStoreResolver.ts'
+import { setGlobalCacheStoreResolver } from '../shared/setGlobalCacheStoreResolver.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 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[]
+            /* Pending {#await} keys the client pre-creates placeholders for. */
+            streaming?: StreamingPlaceholder[]
+            /* Single-use token for the out-of-band resolution stream. */
+            streamToken?: string
+            /* A server-rendered error.svelte page — static, nothing to hydrate. */
+            error?: boolean
+        }
+    }
+}
+
+/*
+Pre-populates the client cache store with response entries captured during SSR.
+Each becomes an already-resolved Response so the first hydration pass finds the
+data via cache() without a network round-trip.
+*/
+function hydrateCacheFromSnapshot(store: CacheStore, snapshot: CacheSnapshotEntry[]): void {
+    for (const entry of snapshot) {
+        store.entries.set(entry.key, cacheEntryFromSnapshot(entry))
+    }
+}
+
+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')
+    }
+
+    /*
+    A server-rendered error.svelte (404 / page-render failure) ships static HTML
+    with no route to hydrate against — leave the markup as-is and wire nothing.
+    */
+    if (window.__SSR__.error) {
+        return
+    }
+
+    const cacheStore = createCacheStore()
+    setCacheStoreResolver(() => cacheStore)
+    /* One tab store: cache(fn, { global: true }) shares it, so global is a no-op here. */
+    setGlobalCacheStoreResolver(() => cacheStore)
+    if (window.__SSR__.cache) {
+        hydrateCacheFromSnapshot(cacheStore, window.__SSR__.cache)
+    }
+
+    /*
+    Install placeholders for pending {#await} keys before hydrate(), so cache()
+    reads hit a placeholder on first evaluation instead of firing their own
+    fetch, then open the out-of-band resolution stream to settle them. The fetch
+    runs in the background — hydration doesn't wait on it.
+    */
+    const deferreds = installStreamingPlaceholders(cacheStore, window.__SSR__.streaming ?? [])
+    if (window.__SSR__.streamToken && deferreds.size > 0) {
+        void openResolveStream(window.__SSR__.streamToken, cacheStore, deferreds)
+    }
+
+    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)
+}

package/src/lib/browser/subscribe.ts

@@ -0,0 +1,131 @@
+import { createSubscriber } from 'svelte/reactivity'
+import type { Subscribable } from '../shared/types/Subscribable.ts'
+
+type SubscriptionStatus = 'pending' | 'open' | 'done' | 'error'
+
+type Entry<T> = {
+    latest: T | undefined
+    error: Error | undefined
+    status: SubscriptionStatus
+    tap: () => void
+}
+
+const registry = new Map<string, Entry<unknown>>()
+
+/*
+Reactive consumer for streaming sources. Takes a Subscribable<T> — the
+shape both `Socket<T>` (declared under src/server/sockets/) and the result of
+`fn.stream(args)` satisfy:
+
+  const latest = $derived(subscribe(chat))                  // socket
+  const latest = $derived(subscribe(tickFeed.stream()))     // rpc stream (no args)
+  const latest = $derived(subscribe(countLog.stream({ to: 5 })))  // rpc stream
+
+Lifecycle mirrors cache(): the entry's tracker is a Svelte
+createSubscriber, so the first $derived read in a tracking scope opens
+the underlying iterator (with history replay on a Socket, or a fresh
+fetch on an rpc stream), and the last $derived to stop reading closes
+it. Many $deriveds reading the same source share one underlying
+subscription — the registry dedupes by `subscribable.name`, which is
+the socket name for declared sockets and `keyForRemoteCall(method, url,
+args)` for rpc streams. So passing fresh `fn.stream(args)` Subscribables
+across re-renders is safe: same args → same key → shared subscription.
+
+Subscribe is a no-op on the server (returns undefined) — SSR can't
+keep a stream open across the request boundary. Pages that want a
+seeded value in the initial HTML should fetch via cache() against an
+HTTP rpc handler and layer subscribe() on top for live updates after
+hydration.
+
+Errors are surfaced through subscribe.error(x) rather than thrown, so
+reading `latest` from a $derived can't crash the component. Status
+distinguishes "haven't received the first frame" (pending) from
+"stream ended cleanly" (done) and "wire layer surfaced an error"
+(error).
+*/
+export function subscribe<T>(subscribable: Subscribable<T>): T | undefined {
+    return readField(subscribable, 'latest') as T | undefined
+}
+
+subscribe.error = function subscribeError<T>(subscribable: Subscribable<T>): Error | undefined {
+    return readField(subscribable, 'error') as Error | undefined
+}
+
+subscribe.status = function subscribeStatus<T>(subscribable: Subscribable<T>): SubscriptionStatus {
+    return (readField(subscribable, 'status') as SubscriptionStatus | undefined) ?? 'pending'
+}
+
+function readField<T, K extends keyof Entry<T>>(
+    subscribable: Subscribable<T>,
+    field: K,
+): Entry<T>[K] | undefined {
+    if (typeof window === 'undefined') {
+        if (field === 'status') {
+            return 'pending' as Entry<T>[K]
+        }
+        return undefined
+    }
+    const entry = getOrCreateEntry(subscribable) as Entry<T>
+    entry.tap()
+    return entry[field]
+}
+
+function getOrCreateEntry<T>(subscribable: Subscribable<T>): Entry<T> {
+    const key = subscribable.name
+    const cached = registry.get(key) as Entry<T> | undefined
+    if (cached) {
+        return cached
+    }
+    const entry: Entry<T> = {
+        latest: undefined,
+        error: undefined,
+        status: 'pending',
+        tap: () => undefined,
+    }
+    entry.tap = createSubscriber((update) => {
+        entry.latest = undefined
+        entry.error = undefined
+        entry.status = 'pending'
+        const iterator = subscribable[Symbol.asyncIterator]()
+        let cancelled = false
+        ;(async () => {
+            try {
+                while (!cancelled) {
+                    const next = await iterator.next()
+                    if (next.done) {
+                        if (!cancelled) {
+                            if (entry.status !== 'error') {
+                                entry.status = 'done'
+                            }
+                            update()
+                        }
+                        return
+                    }
+                    entry.latest = next.value
+                    entry.status = 'open'
+                    update()
+                }
+            } catch (error) {
+                if (!cancelled) {
+                    entry.error = error instanceof Error ? error : new Error(String(error))
+                    entry.status = 'error'
+                    update()
+                }
+            }
+        })()
+        return () => {
+            cancelled = true
+            iterator.return?.(undefined)?.catch(() => undefined)
+            /*
+            Identity-guard the eviction: if a fresh Subscribable with the
+            same name has already replaced us in the registry, this stale
+            cleanup must not nuke the new entry.
+            */
+            if (registry.get(key) === (entry as Entry<unknown>)) {
+                registry.delete(key)
+            }
+        }
+    })
+    registry.set(key, entry as Entry<unknown>)
+    return entry
+}

package/src/lib/browser/types/Errors.ts

@@ -0,0 +1,9 @@
+import type { Component } from 'svelte'
+
+/*
+Manifest of directory prefix → error.svelte module loader. The deepest prefix
+that is an ancestor of the failed path wins (nearest-only, like layouts). An
+error.svelte renders on the server for an unknown route (404) or a throw during
+a page render; the component receives `{ status, message }` props.
+*/
+export type Errors = Record<string, () => Promise<{ default: Component }>>

package/src/lib/browser/types/Layouts.ts

@@ -0,0 +1,7 @@
+import type { Component } from 'svelte'
+
+/*
+Manifest of directory prefix → layout.svelte module loader. The deepest
+prefix that is an ancestor of a route wins (no stacking).
+*/
+export type Layouts = Record<string, () => Promise<{ default: Component }>>

package/src/lib/browser/types/Pages.ts

@@ -0,0 +1,7 @@
+import type { Component } from 'svelte'
+
+/*
+Manifest of route URL → page.svelte module loader. Produced by the resolver
+plugin from `page.svelte` files anywhere under src/browser/pages.
+*/
+export type Pages = Record<string, () => Promise<{ default: Component }>>

package/src/lib/browser/types/StreamingDeferred.ts

@@ -0,0 +1,9 @@
+/*
+A pending {#await} read's deferred entry. `resolve` settles the placeholder
+promise the cache handed out (with the streamed Response or a live re-fetch);
+`request` is what to re-fetch on a miss or a cut stream.
+*/
+export type StreamingDeferred = {
+    resolve: (response: Promise<Response>) => void
+    request: Request
+}

package/src/lib/bundle/BundleMenu.ts

@@ -0,0 +1,11 @@
+import type { BundleMenuItem } from './BundleMenuItem.ts'
+
+/*
+A top-level bundle menu, inserted into the macOS menu bar between the standard
+Edit and Window menus. `label` titles the menu; `items` are its entries top to
+bottom.
+*/
+export type BundleMenu = {
+    label: string
+    items: BundleMenuItem[]
+}

package/src/lib/bundle/BundleMenuItem.ts

@@ -0,0 +1,24 @@
+/*
+A single entry in a bundle menu. Serializable data — the native shim builds the
+matching NSMenuItem. Either a divider or a clickable item that dispatches a
+`belte:menu` CustomEvent into the page (detail `{ name }`); the app's own code
+handles it:
+
+    window.addEventListener('belte:menu', (event) => {
+        if (event.detail.name === 'sync') syncNow()
+    })
+
+Emitting an event (rather than calling a verb directly) is what lets a menu
+drive parameterised work: a click carries no arguments, so the app computes
+them and makes the call itself. `shortcut` is the key for the Cmd-based
+equivalent (e.g. `'r'` → Cmd-R).
+
+A `navigate` item moves the window instead of talking to the page: clicking it
+calls `webview_navigate` with the given URL (the native side, on the UI thread).
+That's how the built-in Server menu drives the connect screen — `emit` reaches
+the loaded page, `navigate` repoints the window itself.
+*/
+export type BundleMenuItem =
+    | { separator: true }
+    | { label: string; shortcut?: string; emit: string }
+    | { label: string; shortcut?: string; navigate: string }