@belte/belte 0.19.0

package/src/lib/server/sockets/types/SocketServerFrame.ts

@@ -0,0 +1,15 @@
+/*
+Wire frame the server sends over the multiplexed socket connection.
+
+`msg` is keyed by socket name (not sub id) because one publish fans
+out to every client subscribed to the socket via Bun's native
+publish — the client demuxes against every local sub of that socket.
+`end` and `err` are per-sub because they're subscription-lifecycle
+events; `err.message` is the only thrown-value field forwarded so the
+wire stays JSON-safe and server-side stack traces never reach the
+client.
+*/
+export type SocketServerFrame =
+    | { type: 'msg'; socket: string; message: unknown }
+    | { type: 'end'; sub: string }
+    | { type: 'err'; sub: string; message: string }

package/src/lib/server/sse.ts

@@ -0,0 +1,53 @@
+/*
+Wraps an AsyncIterable<Frame> in a Response whose body is
+Server-Sent Events (text/event-stream) — each frame becomes one
+`data: <json>\n\n` event. Used inside an rpc handler to expose a
+generator over plain HTTP so EventSource (or `subscribe(fn.stream)(args)`
+on the client) can consume it frame-by-frame.
+
+  export const orderFeed = GET<Args>((args) =>
+      sse(async function* () {
+          for await (const order of db.watchOrders(args)) yield order
+      }())
+  )
+
+A 15s keepalive comment (`: keepalive\n\n`) is sent between frames so
+intermediaries (proxies, load balancers) don't drop an idle connection.
+Comments are ignored by EventSource per the spec, so they're invisible to
+consumers.
+
+Cancellation flows from the consumer through ReadableStream's `cancel`
+into `iter.return()` so the handler's `for await` exits via its normal
+control path. Errors are emitted as an `event: error` frame carrying only
+the message (full error logged server-side) before the stream closes;
+EventSource surfaces this via its `error` listener and `subscribe()`
+maps it to the entry's `error` field.
+*/
+import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
+import { sseErrorFrame } from '../shared/sseErrorFrame.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { streamFromIterator } from './runtime/streamFromIterator.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
+
+const KEEPALIVE_INTERVAL_MS = 15000
+
+export function sse<Frame>(
+    iterable: AsyncIterable<Frame>,
+    init?: ResponseInit,
+): TypedResponse<Frame> {
+    const body = streamFromIterator(iterable, {
+        encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
+        encodeError: (message) => sseErrorFrame.encode(message),
+        keepaliveMs: KEEPALIVE_INTERVAL_MS,
+        keepalivePayload: ': keepalive\n\n',
+    })
+    return new Response(
+        body,
+        withResponseDefaults(init, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': NO_STORE,
+            'X-Content-Type-Options': 'nosniff',
+            Connection: 'keep-alive',
+        }),
+    ) as TypedResponse<Frame>
+}

package/src/lib/shared/BELTE_PACKAGE_NAME.ts

@@ -0,0 +1,7 @@
+/*
+The package's published npm name. The codegen and the import-name resolver
+match a consuming project's dependency (direct or aliased) against this to
+decide which specifier to emit, so keeping it in one place means a future
+rename touches a single constant.
+*/
+export const BELTE_PACKAGE_NAME = '@belte/belte'

package/src/lib/shared/CACHE_CONTROL_VALUES.ts

@@ -0,0 +1,16 @@
+/*
+Cache-Control values used by belte's framework responses. Centralised so
+the framework's policy (no-store on errors and rpc dispatch helpers,
+private/no-cache on SSR HTML, the static-asset policies) lives in one place
+and can't drift between the server core, the asset servers, and the respond
+helpers.
+*/
+export const NO_STORE = 'no-store'
+export const SSR_CACHE_CONTROL = 'private, no-cache'
+
+// Content-addressed `/_app/` chunks (name carries the hash) — cache forever.
+export const IMMUTABLE_ASSET_CACHE_CONTROL = 'public, max-age=31536000, immutable'
+// Unhashed `/_app/` entries (entry bundle, shell) — must revalidate each time.
+export const REVALIDATE_ASSET_CACHE_CONTROL = 'public, max-age=0, must-revalidate'
+// Files served from public/ at the site root — short shared cache.
+export const PUBLIC_ASSET_CACHE_CONTROL = 'public, max-age=3600'

package/src/lib/shared/HttpError.ts

@@ -0,0 +1,19 @@
+/*
+Thrown by remote-function calls when the server responds with a non-2xx
+status. Carries the raw Response so callers can inspect body, headers, or
+status text — useful for showing user-friendly error UI without having to
+opt every call site into the `.raw()` escape hatch.
+*/
+export class HttpError extends Error {
+    readonly status: number
+    readonly statusText: string
+    readonly response: Response
+
+    constructor(response: Response) {
+        super(`HTTP ${response.status} ${response.statusText || 'error'}`)
+        this.name = 'HttpError'
+        this.status = response.status
+        this.statusText = response.statusText
+        this.response = response
+    }
+}

package/src/lib/shared/RESOLVE_STREAM_PATH.ts

@@ -0,0 +1,7 @@
+/*
+Path prefix for the out-of-band resolution stream. The SSR document ships a
+single-use token in `__SSR__.streamToken`; the browser opens
+`${RESOLVE_STREAM_PATH}${token}` once to receive its pending {#await} resolutions.
+Shared so the server route and the client fetch agree on the path.
+*/
+export const RESOLVE_STREAM_PATH = '/__belte/resolve/'

package/src/lib/shared/STREAMING_CONTENT_TYPES.ts

@@ -0,0 +1,11 @@
+/*
+Content-Type prefixes belte treats as streaming bodies — SSE for the
+`sse()` helper, JSONL / NDJSON for the `jsonl()` helper. Used by
+decodeResponse to refuse a buffered decode and by streamResponse to
+choose the frame parser.
+*/
+export const STREAMING_CONTENT_TYPES = [
+    'text/event-stream',
+    'application/jsonl',
+    'application/x-ndjson',
+]

package/src/lib/shared/activeCacheStore.ts

@@ -0,0 +1,20 @@
+import { cacheStoreSlot } from './cacheStoreSlot.ts'
+import { createCacheStore } from './createCacheStore.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Resolves the active CacheStore. The runtime is registered via
+`setCacheStoreResolver` from the server entry (request-scoped via ALS)
+or the client entry (module-level singleton). If no resolver is registered,
+a single fallback store is created lazily so isolated tests still work.
+*/
+export function activeCacheStore(): CacheStore {
+    const fromResolver = cacheStoreSlot.resolver?.()
+    if (fromResolver) {
+        return fromResolver
+    }
+    if (!cacheStoreSlot.fallback) {
+        cacheStoreSlot.fallback = createCacheStore()
+    }
+    return cacheStoreSlot.fallback
+}

package/src/lib/shared/appDataDir.ts

@@ -0,0 +1,34 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/*
+Platform-standard per-user data directory for a bundle, keyed by its program
+name. cwd-independent on purpose: the path derives from `programName`, not the
+process working directory — which the OS `open` command sets to `/`, so anything
+relying on cwd (Bun's `.env` autoload, relative paths) finds nothing inside a
+launched `.app`. This is where a bundle keeps what can't be baked at compile time
+— the user's config, DB, and cache. macOS Application Support, Windows %APPDATA%,
+XDG data home elsewhere. Pure: computes the path, never touches the filesystem.
+
+`BELTE_DATA_DIR` overrides the lot on every platform, used as-is (no programName
+appended) — a cross-platform `XDG_DATA_HOME` that also works on macOS/Windows. Set
+it to point dev at a throwaway dir without touching app code; leave it unset in
+prod for the platform default. A relative value reintroduces cwd-dependence, so a
+launched `.app` (cwd `/`) needs an absolute path. Must come from a layer above the
+data-dir `.env` (shell, CWD `.env`, or binary-dir `.env`) — it can't be read from
+the very file whose location it decides.
+*/
+export function appDataDir(programName: string): string {
+    const override = process.env.BELTE_DATA_DIR
+    if (override !== undefined && override !== '') {
+        return override
+    }
+    const home = homedir()
+    if (process.platform === 'darwin') {
+        return join(home, 'Library', 'Application Support', programName)
+    }
+    if (process.platform === 'win32') {
+        return join(process.env.APPDATA ?? join(home, 'AppData', 'Roaming'), programName)
+    }
+    return join(process.env.XDG_DATA_HOME ?? join(home, '.local', 'share'), programName)
+}

package/src/lib/shared/belteImportName.ts

@@ -0,0 +1,44 @@
+import { BELTE_PACKAGE_NAME } from './BELTE_PACKAGE_NAME.ts'
+import { readPackageJson } from './readPackageJson.ts'
+
+/*
+Resolves the bare specifier prefix a consuming project imports belte under —
+the name belte is installed as in its package.json. A project may depend on
+belte directly (`@belte/belte`) or behind a package alias
+(`"belte": "npm:@belte/belte@..."`, or `workspace:@belte/belte@*`
+inside this repo). An alias-only install resolves only under the alias key and
+a direct install only under the canonical name, so the generated rpc / socket
+/ prompt modules must import under whichever name the project
+declared.
+
+Prefers a `belte` alias (the ergonomic surface the docs use) when present, then
+a direct canonical dependency, then any other alias targeting belte. Falls back
+to the canonical name when belte isn't found in package.json — the build can't
+resolve belte at all in that case, and the canonical name yields the clearest
+resolution error.
+*/
+export async function belteImportName(cwd: string): Promise<string> {
+    const packageJson = (await readPackageJson(cwd)) as
+        | { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        | undefined
+    if (!packageJson) {
+        return BELTE_PACKAGE_NAME
+    }
+    const dependencies = { ...packageJson.devDependencies, ...packageJson.dependencies }
+    /*
+    Alias entries whose target is belte — `npm:` for a published install,
+    `workspace:` for the in-repo examples. The key is the name the project
+    imports under; the version suffix (`@^0.2.0`, `@*`) is optional.
+    */
+    const aliasPattern = new RegExp(`^(npm|workspace):${BELTE_PACKAGE_NAME}(@.*)?$`)
+    const aliasNames = Object.entries(dependencies)
+        .filter(([, specifier]) => aliasPattern.test(specifier))
+        .map(([name]) => name)
+    if (aliasNames.includes('belte')) {
+        return 'belte'
+    }
+    if (BELTE_PACKAGE_NAME in dependencies) {
+        return BELTE_PACKAGE_NAME
+    }
+    return aliasNames[0] ?? BELTE_PACKAGE_NAME
+}

package/src/lib/shared/browserClientFlags.ts

@@ -0,0 +1,10 @@
+import type { ClientFlags } from './types/ClientFlags.ts'
+
+/*
+Client surface flags for a browser-emitted RPC/socket stub. The bundler only
+emits the browser proxy when clients.browser is true, so browser is always true
+here; mcp/cli are server-only discovery state with no meaning in the browser
+bundle, defaulted false so the public RemoteFunction/Socket shape matches the
+server side. Single source shared by remoteProxy and socketProxy.
+*/
+export const browserClientFlags: ClientFlags = { browser: true, mcp: false, cli: false }

package/src/lib/shared/buildRpcRequest.ts

@@ -0,0 +1,70 @@
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
+import { queryStringFromArgs } from './queryStringFromArgs.ts'
+import type { HttpVerb } from './types/HttpVerb.ts'
+
+/*
+Builds the Request a verb helper uses to invoke its handler. Same shape on
+both sides (server defineVerb + client remoteProxy) so the cache key
+derivation and SSR snapshot round-trip identically. $rpc URLs are flat
+(no `:name` segments): GET/DELETE/HEAD serialise args onto the query
+string; POST/PUT/PATCH send them as application/json.
+
+`baseUrl` provides the origin needed by the Request constructor — on the
+server it's the inbound request's URL (so handlers reading `request.url` see
+the caller's host), in the browser it's window.location. `headers` lets the
+server pre-populate the synthetic Request with forwarded session headers;
+the client passes nothing.
+*/
+export function buildRpcRequest({
+    method,
+    url,
+    args,
+    baseUrl,
+    headers,
+}: {
+    method: HttpVerb
+    url: string
+    args: unknown
+    baseUrl: string
+    headers?: Headers
+}): Request {
+    const requestHeaders = headers ?? new Headers()
+    if (!carriesBodyArgs(method)) {
+        const target = appendQuery(method, url, args)
+        return new Request(new URL(target, baseUrl).href, { method, headers: requestHeaders })
+    }
+    if (args === undefined) {
+        return new Request(new URL(url, baseUrl).href, { method, headers: requestHeaders })
+    }
+    /*
+    A FormData body ships as-is: the Request constructor sets its own
+    `multipart/form-data` content-type with a boundary, so the server's
+    parseArgs splits text fields into args and File parts into files().
+    Setting the header by hand would omit the boundary and break parsing.
+    */
+    if (args instanceof FormData) {
+        return new Request(new URL(url, baseUrl).href, {
+            method,
+            headers: requestHeaders,
+            body: args,
+        })
+    }
+    requestHeaders.set('content-type', 'application/json')
+    return new Request(new URL(url, baseUrl).href, {
+        method,
+        headers: requestHeaders,
+        body: JSON.stringify(args),
+    })
+}
+
+function appendQuery(method: HttpVerb, url: string, args: unknown): string {
+    if (args === undefined) {
+        return url
+    }
+    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+        const got = Array.isArray(args) ? 'array' : typeof args
+        throw new Error(`[belte] ${method} ${url} args must be a plain object — got ${got}`)
+    }
+    const suffix = queryStringFromArgs(args as Record<string, unknown>, false)
+    return suffix === '' ? url : `${url}?${suffix}`
+}

package/src/lib/shared/bundleLayout.ts

@@ -0,0 +1,36 @@
+import { basename, dirname, join } from 'node:path'
+
+/*
+Where a bundle's files live relative to its binary directory (the dir holding the
+launcher + server — `dirname(process.execPath)` at runtime). A macOS `.app` nests
+binaries under `Contents/MacOS`, the webview lib under `Contents/Frameworks`, and
+data under `Contents/Resources` — the only one `codesign` seals as a *resource*,
+so the shipped `.env` survives signing. Every other platform keeps everything
+flat beside the binaries. The single source the bundler writes against and the
+boot readers resolve from, so build and runtime can't disagree. Pure: computes
+paths, never touches disk.
+*/
+export function bundleLayout(binaryDir: string): {
+    binDir: string
+    libDir: string
+    resourcesDir: string
+    envPath: string
+} {
+    const isMacApp = basename(binaryDir) === 'MacOS' && basename(dirname(binaryDir)) === 'Contents'
+    if (isMacApp) {
+        const contents = dirname(binaryDir)
+        const resourcesDir = join(contents, 'Resources')
+        return {
+            binDir: binaryDir,
+            libDir: join(contents, 'Frameworks'),
+            resourcesDir,
+            envPath: join(resourcesDir, '.env'),
+        }
+    }
+    return {
+        binDir: binaryDir,
+        libDir: binaryDir,
+        resourcesDir: binaryDir,
+        envPath: join(binaryDir, '.env'),
+    }
+}

package/src/lib/shared/bundled.ts

@@ -0,0 +1,34 @@
+declare global {
+    interface Window {
+        // Set by the native webview's init script (openWebview) on every document
+        // it loads — local or remote. Absent in a plain browser tab.
+        __BELTE_BUNDLE__?: boolean
+    }
+}
+
+/*
+True when this code runs inside the belte desktop bundle rather than a plain web
+app in a browser. Isomorphic: one name, same meaning on both sides — "am I part of
+the bundle" — though each side detects it differently.
+
+Client: the native webview runs an init script on every document it loads
+(openWebview's webview_init), so the flag is present whether the page came from the
+bundle's own embedded server or a *remote* one. A plain browser tab never runs that
+script — even when it hits the embedded localhost server — so it reads false there.
+This is the "in a webview" signal, robust to local-or-remote.
+
+Server: the launcher sets BELTE_PARENT_PID when it spawns the embedded server (see
+spawnEmbeddedServer), so its presence marks "I am the bundle's embedded server
+process." A remote server is never part of a bundle, so it reads false — matching
+the client view that a remote page's *data source* is outside the bundle even while
+its *rendering context* (the webview) is inside it.
+
+Distinct from runningAsStandaloneBinary(), which is also true for a plain compiled
+(install-tarball) server binary — still a web app, not a bundle.
+*/
+export function bundled(): boolean {
+    if (typeof window === 'undefined') {
+        return Boolean(Bun.env.BELTE_PARENT_PID)
+    }
+    return window.__BELTE_BUNDLE__ === true
+}