@belte/belte 0.19.0

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

@@ -0,0 +1,15 @@
+/*
+Wire format for a single cached response shipped from SSR to client hydration.
+Only GET/DELETE entries with a textual Content-Type are emitted — POST/PUT
+bodies can't be reconstructed without shipping the original request body,
+and binary bodies don't survive a JSON round-trip.
+*/
+export type CacheSnapshotEntry = {
+    key: string
+    url: string
+    method: 'GET' | 'DELETE'
+    status: number
+    statusText: string
+    headers: Array<[string, string]>
+    body: string
+}

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

@@ -0,0 +1,32 @@
+import type { CacheEntry } from './CacheEntry.ts'
+
+/*
+Cache map paired with a Svelte-aware per-key subscriber. Calling
+`subscribe(key)` from inside a tracking scope ($derived / $effect) registers
+that scope to re-run when the entry is invalidated; called outside tracking
+it's a no-op. Subscribers live for the lifetime of the store: the server
+uses a fresh store per request (so subscribers die with the response), the
+client uses a single module-level store (so subscribers persist for the tab).
+
+`trackLifecycle` is the store-wide counterpart used by cache.pending: unlike a
+keyed read it matches many entries (or all), so it re-derives by scanning
+entries and only needs one "in-flight membership changed" signal. Reading it in
+a tracking scope re-runs that scope whenever any call starts, settles, or is
+evicted.
+*/
+export type CacheStore = {
+    entries: Map<string, CacheEntry>
+    events: EventTarget
+    subscribe: (key: string) => void
+    trackLifecycle: () => void
+    /*
+    Keys dropped by a (policy-less) invalidate, awaiting their next read. The
+    drop erases the entry, so the next cache() call is a cold miss with no memory
+    it followed an invalidate; this set carries that signal across the gap so the
+    replacement entry is flagged a reload (cache.refreshing true) rather than a
+    first-ever load. Consumed when that entry is created; a key invalidated but
+    never re-read just lingers (bounded by distinct such keys; the server's
+    request-scoped store discards it with the response).
+    */
+    pendingRefresh: Set<string>
+}

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

@@ -0,0 +1,11 @@
+/*
+Which client surfaces a verb or socket is exposed to. Browser is the
+historical default; MCP and CLI flip on automatically when the
+declaration carries a Standard Schema (the schema is what makes the
+non-browser surfaces safe to advertise). Explicit values always win.
+*/
+export type ClientFlags = {
+    browser: boolean
+    mcp: boolean
+    cli: boolean
+}

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

@@ -0,0 +1,6 @@
+export type CompileTarget =
+    | 'bun-darwin-arm64'
+    | 'bun-darwin-x64'
+    | 'bun-linux-arm64'
+    | 'bun-linux-x64'
+    | 'bun-windows-x64'

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

@@ -0,0 +1 @@
+export type HttpVerb = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'

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

@@ -0,0 +1,9 @@
+/*
+The launcher/CLI-owned record of the last connection, kept in the data dir so it
+survives relaunch and is readable before any window or session opens. It records
+the *intent*, not a concrete embedded URL — an embedded server picks a fresh port
+each launch, so only `{ kind: 'embedded' }` is durable; a remote connection keeps
+its url. resolveLaunchTarget / resolveCliTarget read it; /connect and /start write
+it; /disconnect clears it.
+*/
+export type LastConnection = { kind: 'embedded' } | { kind: 'url'; url: string }

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

@@ -0,0 +1,12 @@
+/*
+A single declared argument of a markdown prompt, parsed from the file's
+YAML frontmatter `arguments:` list. `name` is the placeholder the body
+interpolates via `{{name}}`; `description` + `required` feed the argument
+list MCP advertises in `prompts/list`. Build-time only — markdown prompts
+carry no runtime schema object, so this drives the generated JSON Schema.
+*/
+export type PromptArgument = {
+    name: string
+    description?: string
+    required?: boolean
+}

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

@@ -0,0 +1,13 @@
+import type { HttpVerb } from './HttpVerb.ts'
+
+/*
+Bare-response remote function — same call shape as RemoteFunction but
+resolves to the underlying Response without Content-Type decode and
+without throwing on non-2xx. Produced as `.raw` on every RemoteFunction
+so callers that need status / headers / body streaming or want to
+implement custom error handling can opt out of the decode.
+*/
+export type RawRemoteFunction<Args> = ((args: Args | FormData) => Promise<Response>) & {
+    readonly method: HttpVerb
+    readonly url: string
+}

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

@@ -0,0 +1,42 @@
+import type { ClientFlags } from './ClientFlags.ts'
+import type { HttpVerb } from './HttpVerb.ts'
+import type { RawRemoteFunction } from './RawRemoteFunction.ts'
+import type { Subscribable } from './Subscribable.ts'
+
+/*
+Remote function reference produced by GET/POST/... inside an `$rpc/**`
+module and consumed by rpc dispatch, cache(), SSR auto-hydration, and
+direct calls. Same callable signature on server and client — the bundler
+swaps the implementation for browser builds.
+
+The plain call resolves to the decoded body shape (sniffed from
+Content-Type) and throws HttpError on non-2xx. `.raw` is a sibling
+RemoteFunction whose call resolves to the underlying Response — same
+method, same url, same args, no decode. Pass `fn.raw` to cache() to
+memoise raw Responses against the same cache key as `fn` (both share one
+stored entry — the decode just happens on the way out for callers of
+`fn`). `.stream(args)` returns an iterable view of the Response body:
+SSE / JSONL handlers yield each frame; non-streaming handlers yield the
+decoded body once then complete. The result is a Subscribable, so it
+can be passed to subscribe() and shared across reactive consumers.
+For sustained broadcast / pub-sub use the `belte/server/socket` primitive —
+HTTP rpc isn't the place for long-lived multi-publisher subscriptions.
+`.fetch(req)` is the framework's request-dispatch entry point — used by
+the router to invoke the handler from an incoming HTTP request, not
+for user code.
+*/
+/*
+A body verb (POST/PUT/PATCH) also accepts a FormData in place of typed args:
+buildRpcRequest ships it as a multipart body and the server splits text fields
+into args (still schema-validated) and File parts into files(). FormData is
+stringly-typed, so this is the upload escape hatch — typed object args remain
+the default for everything else.
+*/
+export type RemoteFunction<Args, Return> = ((args: Args | FormData) => Promise<Return>) & {
+    readonly method: HttpVerb
+    readonly url: string
+    readonly clients: ClientFlags
+    readonly raw: RawRemoteFunction<Args>
+    stream(args?: Args | FormData): Subscribable<Return>
+    fetch(request: Request): Promise<Response>
+}

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

@@ -0,0 +1,57 @@
+/*
+Mirror of the Standard Schema v1 spec interface (standardschema.dev). Any
+library that implements the spec — zod, valibot, arktype, etc. — produces
+values whose `~standard` property structurally matches this shape, so users
+can pass their existing schemas to verb helpers without an adapter.
+
+Kept inline (no `@standard-schema/spec` dep) because the spec is type-only
+and tiny; adding a package for ~30 lines of interface would be churn. The
+namespace pattern below is the spec's own convention — `InferInput` /
+`InferOutput` ride along the same export.
+*/
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>
+}
+
+// biome-ignore lint/style/useNamingConvention: matches the Standard Schema spec exactly
+export namespace StandardSchemaV1 {
+    export interface Props<Input = unknown, Output = Input> {
+        readonly version: 1
+        readonly vendor: string
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>
+        readonly types?: Types<Input, Output> | undefined
+    }
+
+    export type Result<Output> = SuccessResult<Output> | FailureResult
+
+    export interface SuccessResult<Output> {
+        readonly value: Output
+        readonly issues?: undefined
+    }
+
+    export interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>
+    }
+
+    export interface Issue {
+        readonly message: string
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined
+    }
+
+    export interface PathSegment {
+        readonly key: PropertyKey
+    }
+
+    export interface Types<Input = unknown, Output = Input> {
+        readonly input: Input
+        readonly output: Output
+    }
+
+    export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+        Schema['~standard']['types']
+    >['input']
+
+    export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+        Schema['~standard']['types']
+    >['output']
+}

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

@@ -0,0 +1,10 @@
+import type { CacheSnapshotEntry } from './CacheSnapshotEntry.ts'
+
+/*
+Payload of one streamed `window.__belteResolve(...)` call. A full
+`CacheSnapshotEntry` settles the placeholder with warm data; a `{ key, miss }`
+marker means the server couldn't snapshot that body (binary, rejected, evicted)
+so the client settles the placeholder with a live re-fetch instead. Discriminate
+on the `miss` field.
+*/
+export type StreamedResolution = CacheSnapshotEntry | { key: string; miss: true }

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

@@ -0,0 +1,13 @@
+/*
+Wire descriptor for a {#await} cache read that's still pending at first flush.
+Shipped in `__SSR__.streaming` so the client can pre-create a deferred cache
+entry for the key before hydration — `cache()` then hits that placeholder
+instead of firing its own fetch, and the streamed `__belteResolve` settles it.
+`url`/`method` reconstruct the entry's Request for the rare miss fallback (a
+non-snapshottable body the client re-fetches live).
+*/
+export type StreamingPlaceholder = {
+    key: string
+    url: string
+    method: string
+}

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

@@ -0,0 +1,15 @@
+/*
+The thing `subscribe()` reads from: an AsyncIterable carrying a stable
+`name` used as the subscription registry key. Both `Socket<T>` (the
+declared broadcast primitive) and the result of `fn.stream(args)`
+(per-call HTTP stream consumer) satisfy this shape, so subscribe() can
+share one iterator across multiple readers regardless of source.
+
+The name on a Socket comes from the file path under `src/server/sockets/`.
+The name on an fn.stream(args) result is `keyForRemoteCall(method, url,
+args)` — the same key cache() uses — so two subscribers to the same
+remote-call args dedupe to one underlying fetch.
+*/
+export interface Subscribable<T> extends AsyncIterable<T> {
+    readonly name: string
+}

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

@@ -0,0 +1,5 @@
+import type { CompileOptions } from 'svelte/compiler'
+
+export type SvelteConfig = {
+    compilerOptions?: Partial<CompileOptions>
+}

package/src/lib/shared/withJsonSchema.ts

@@ -0,0 +1,20 @@
+import type { StandardSchemaV1 } from './types/StandardSchemaV1.ts'
+
+/*
+Attaches a `toJSONSchema()` projection to a Standard Schema whose library
+doesn't expose one natively. jsonSchemaForSchema probes that method to feed the
+OpenAPI document, the MCP tool schemas, the CLI flag help, and the bundle setup
+form. Zod 4 / Effect / Arktype carry their own; everything else wraps once where
+the schema is declared:
+
+  export const config = env(withJsonSchema(vSchema, (s) => toJsonSchema(s)))
+
+Mutates and returns the same schema with the method attached, so the wrapped
+value stays usable everywhere the bare schema was.
+*/
+export function withJsonSchema<Schema extends StandardSchemaV1>(
+    schema: Schema,
+    toJsonSchema: (schema: Schema) => Record<string, unknown>,
+): Schema & { toJSONSchema: () => Record<string, unknown> } {
+    return Object.assign(schema, { toJSONSchema: () => toJsonSchema(schema) })
+}

package/src/lib/shared/writeLastConnection.ts

@@ -0,0 +1,13 @@
+import { mkdir } from 'node:fs/promises'
+import { appDataDir } from './appDataDir.ts'
+import { lastConnectionPath } from './lastConnectionPath.ts'
+import type { LastConnection } from './types/LastConnection.ts'
+
+// Persists the connection intent, creating the data dir on first write.
+export async function writeLastConnection(
+    programName: string,
+    value: LastConnection,
+): Promise<void> {
+    await mkdir(appDataDir(programName), { recursive: true })
+    await Bun.write(lastConnectionPath(programName), JSON.stringify(value))
+}

package/src/lib/shared/writeRoutesDts.ts

@@ -0,0 +1,67 @@
+import { pageUrlForFile } from './pageUrlForFile.ts'
+import { parseRouteSegments } from './parseRouteSegments.ts'
+
+/*
+Walks a `[name]` / `[...rest]` route URL and returns the param shape it
+declares. Catch-all segments map to `string` under their declared name —
+the server's toBunRoutePattern renames Bun's `*` key back to that name
+when dispatching, so the page component sees `params.rest`, not
+`params['*']`.
+*/
+function paramsForRoute(routeUrl: string): Record<string, 'string'> {
+    return Object.fromEntries(
+        parseRouteSegments(routeUrl)
+            .filter((segment) => segment.kind === 'param')
+            .map((segment) => [segment.name, 'string'] as const),
+    )
+}
+
+function renderParamsShape(shape: Record<string, 'string'>): string {
+    const keys = Object.keys(shape)
+    if (keys.length === 0) {
+        return 'Record<string, never>'
+    }
+    return `{ ${keys.map((key) => `${JSON.stringify(key)}: string`).join('; ')} }`
+}
+
+/*
+Emits a `.d.ts` that augments belte's `Routes` interface with one entry per
+page file in the project. Page picks this up as a discriminated union keyed
+on `route`, so `if (page.route === '/media/[id]') page.params.id` is typed
+automatically without consumers writing route types by hand.
+The file is written to `src/.belte/routes.d.ts` so the consumer's existing
+src tsconfig include picks it up with no extra configuration. The augmented
+module is keyed on the name the project imports belte under (`importName`),
+so the augmentation matches the consumer's `page` import whether belte is
+installed directly (`@belte/belte`) or behind an alias.
+*/
+export async function writeRoutesDts({
+    cwd,
+    pageFiles,
+    importName,
+}: {
+    cwd: string
+    pageFiles: string[]
+    importName: string
+}): Promise<void> {
+    const entries = pageFiles
+        .map((file) => ({
+            route: pageUrlForFile(file),
+            params: paramsForRoute(pageUrlForFile(file)),
+        }))
+        .toSorted((a, b) => a.route.localeCompare(b.route))
+        .map(
+            ({ route, params }) => `        ${JSON.stringify(route)}: ${renderParamsShape(params)}`,
+        )
+        .join('\n')
+    const contents = `// Generated by belte. Do not edit by hand.
+declare module '${importName}/browser/page' {
+    interface Routes {
+${entries}
+    }
+}
+
+export {}
+`
+    await Bun.write(`${cwd}/src/.belte/routes.d.ts`, contents)
+}

package/src/lib/test/clearVerbRegistry.ts

@@ -0,0 +1,11 @@
+import { verbRegistry } from '../server/rpc/verbRegistry.ts'
+
+/*
+Empties the process-wide verb registry. defineVerb registers on construction
+and never removes, so verbs declared in one test stay discoverable by name in
+the next. Call in beforeEach to isolate a suite that defines verbs inline,
+keeping createTestClient's name lookup unambiguous across tests.
+*/
+export function clearVerbRegistry(): void {
+    verbRegistry.clear()
+}

package/src/lib/test/createTestClient.ts

@@ -0,0 +1,78 @@
+import type { AppModule } from '../server/AppModule.ts'
+import { dispatchVerbInProcess } from '../server/rpc/dispatchVerbInProcess.ts'
+import { findVerbByCommandName } from '../server/rpc/findVerbByCommandName.ts'
+import type { VerbRegistryEntry } from '../server/rpc/types/VerbRegistryEntry.ts'
+import { decodeResponse } from '../shared/decodeResponse.ts'
+
+/*
+Each property is a callable: invoking it decodes the body (and throws
+HttpError on non-2xx, like a real remote call), while `.raw(args)` returns
+the underlying Response untouched for status/header/streaming assertions.
+*/
+type TestInvoker = ((args?: unknown) => Promise<unknown>) & {
+    raw: (args?: unknown) => Promise<Response>
+}
+
+type AnyApi = Record<string, TestInvoker>
+
+/*
+In-process client for tests. Like createClient's in-process mode it discovers
+verbs from the registry (populated by the test's defineVerb calls) and routes
+through dispatchVerbInProcess — same synthesize-and-fetch the CLI and MCP
+surfaces use, so they can't drift on how a verb is invoked. Each call runs
+inside runWithRequestScope, the same seam createServer crosses for a live
+request, so request-scoped helpers behave identically to production — a fresh
+per-request cache(), the cookie jar with Set-Cookie flush, request()/server()
+resolution, and handleError/500 fallback on a throw.
+
+`headers` pre-populates the synthetic Request (auth, cookies) for handlers that
+read inbound identity; `app.handleError` lets a suite assert its custom error
+response. No `url` — this never hits the network, so it needs the rpc modules
+imported into the process, not a running server.
+*/
+export function createTestClient<Api extends AnyApi = AnyApi>(opts?: {
+    baseUrl?: string
+    headers?: HeadersInit
+    app?: AppModule
+}): Api {
+    const baseUrl = opts?.baseUrl ?? 'http://localhost/'
+
+    /*
+    Fresh Headers per call: buildRpcRequest mutates it (sets content-type on
+    body verbs), so a shared instance would leak that mutation across calls.
+    */
+    function send(entry: VerbRegistryEntry, args: unknown): Promise<Response> {
+        return dispatchVerbInProcess({
+            entry,
+            args,
+            baseUrl,
+            headers: new Headers(opts?.headers),
+            app: opts?.app,
+        })
+    }
+
+    function buildInvoker(entry: VerbRegistryEntry): TestInvoker {
+        const invoker = (async (args?: unknown) =>
+            decodeResponse(await send(entry, args))) as TestInvoker
+        invoker.raw = (args?: unknown) => send(entry, args)
+        return invoker
+    }
+
+    // Memoise per-name so repeated accesses skip the registry scan + closure alloc.
+    const invokerCache = new Map<string, TestInvoker | undefined>()
+
+    return new Proxy({} as Api, {
+        get(_target, prop): TestInvoker | undefined {
+            if (typeof prop !== 'string') {
+                return undefined
+            }
+            if (invokerCache.has(prop)) {
+                return invokerCache.get(prop)
+            }
+            const entry = findVerbByCommandName(prop)
+            const invoker = entry ? buildInvoker(entry) : undefined
+            invokerCache.set(prop, invoker)
+            return invoker
+        },
+    })
+}

package/src/preload.ts

@@ -0,0 +1,20 @@
+import { plugin } from 'bun'
+import { belteResolverPlugin } from './belteResolverPlugin.ts'
+import { loadSvelteConfig } from './lib/shared/loadSvelteConfig.ts'
+import { sveltePlugin } from './sveltePlugin.ts'
+
+const mode = (process.env.BELTE_SVELTE_MODE ?? 'server') as 'server' | 'client'
+const svelteConfig = await loadSvelteConfig()
+
+await plugin(sveltePlugin({ generate: mode, svelteConfig }))
+await plugin(belteResolverPlugin({ target: mode }))
+
+await plugin({
+    name: 'css-noop',
+    setup(build) {
+        build.onLoad({ filter: /\.css$/ }, () => ({
+            contents: 'export default {};',
+            loader: 'js',
+        }))
+    },
+})

package/src/scaffold.ts

@@ -0,0 +1,92 @@
+import { Glob } from 'bun'
+import { log } from './lib/shared/log.ts'
+
+const TEMPLATE_DIR = new URL('../template', import.meta.url).pathname
+
+/*
+Copies the bundled template directory into `${cwd}/${name}`. Refuses to write
+into a non-empty directory so an accidental run doesn't overwrite real work.
+*/
+export async function scaffold({
+    cwd = process.cwd(),
+    name,
+}: {
+    cwd?: string
+    name: string
+}): Promise<string> {
+    const trimmed = name.trim()
+    if (trimmed === '') {
+        throw new Error('[belte] project name is required: bunx belte scaffold <name>')
+    }
+    const target = resolveTarget(cwd, trimmed)
+    if (await targetIsNonEmpty(target)) {
+        throw new Error(`[belte] target directory is not empty: ${target}`)
+    }
+    if (!(await Bun.file(`${TEMPLATE_DIR}/package.json`).exists())) {
+        throw new Error(`[belte] template missing at ${TEMPLATE_DIR}`)
+    }
+    await copyTree(TEMPLATE_DIR, target)
+    log.success(`scaffolded belte project at ${target}`)
+    log.detail('  next steps:')
+    if (target !== cwd) {
+        log.detail(`    cd ${trimmed}`)
+    }
+    log.detail('    bun install')
+    log.detail('    bun run dev')
+    return target
+}
+
+/*
+Copies every file under `from` into `to`, preserving relative paths. Uses
+Bun.Glob to enumerate (dotfiles included) and Bun.write to materialize each
+file — Bun.write auto-creates parent directories.
+*/
+async function copyTree(from: string, to: string): Promise<void> {
+    const files = await Array.fromAsync(
+        new Glob('**/*').scan({ cwd: from, onlyFiles: true, dot: true }),
+    )
+    await Promise.all(
+        files.map(async (relativePath) => {
+            const source = Bun.file(`${from}/${relativePath}`)
+            await Bun.write(`${to}/${relativePath}`, source)
+        }),
+    )
+}
+
+/*
+Resolves the user-supplied name against the working directory. Absolute
+paths (`/tmp/foo`) and `~`-prefixed paths are used as-is; relative names
+are joined onto `cwd`.
+*/
+function resolveTarget(cwd: string, name: string): string {
+    if (name === '.' || name === './') {
+        return cwd
+    }
+    if (name.startsWith('/')) {
+        return name
+    }
+    if (name.startsWith('~/')) {
+        const home = process.env.HOME ?? ''
+        return `${home}${name.slice(1)}`
+    }
+    return `${cwd}/${name}`
+}
+
+/*
+True when the target exists and contains at least one entry. Uses Bun.Glob
+rather than fs.readdir to honor the project's "Bun-first" rule. A missing
+directory is reported as empty so first-time scaffolds proceed.
+*/
+async function targetIsNonEmpty(target: string): Promise<boolean> {
+    try {
+        for await (const _ of new Glob('*').scan({ cwd: target, onlyFiles: false, dot: true })) {
+            return true
+        }
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return false
+        }
+        throw error
+    }
+    return false
+}

package/src/serverBuildPlugins.ts

@@ -0,0 +1,25 @@
+import type { BunPlugin } from 'bun'
+import { belteResolverPlugin } from './belteResolverPlugin.ts'
+import type { SvelteConfig } from './lib/shared/types/SvelteConfig.ts'
+import { sveltePlugin } from './sveltePlugin.ts'
+
+/*
+The server-target Bun.build plugin pair shared by compile / buildCli /
+bundleApp: the svelte loader (server generate) plus belte's virtual-module
+resolver. `embedAssets` flips on the zstd asset embed used by the standalone
+server binary; the CLI + launcher builds leave it off.
+*/
+export function serverBuildPlugins({
+    cwd,
+    svelteConfig,
+    embedAssets = false,
+}: {
+    cwd: string
+    svelteConfig?: SvelteConfig
+    embedAssets?: boolean
+}): BunPlugin[] {
+    return [
+        sveltePlugin({ generate: 'server', svelteConfig }),
+        belteResolverPlugin({ cwd, embedAssets, target: 'server' }),
+    ]
+}