@belte/belte 0.19.0 → 0.19.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@belte/belte",
-    "version": "0.19.0",
+    "version": "0.19.2",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

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

@@ -1,9 +1,11 @@
 import type { Component } from 'svelte'
+import { activePage } from '../shared/activePage.ts'
 import {
     type NormalizedLayoutPrefix,
     nearestLayoutPrefix,
     normalizeLayoutPrefixes,
 } from '../shared/nearestLayoutPrefix.ts'
+import type { PageSnapshot } from '../shared/types/PageSnapshot.ts'
 import { abortPageStream } from './pageStreamController.ts'
 import type { Layouts } from './types/Layouts.ts'
 import type { Pages } from './types/Pages.ts'
@@ -42,13 +44,37 @@ 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>({
+/*
+Client-side singleton the resolver returns. navigate()/applyState mutate it;
+because it's $state, reads taken through the `page` proxy inside a $derived
+re-run on every nav. Never populated server-side — there the resolver reads
+the per-request ALS store instead, so concurrent renders don't share it.
+*/
+export const clientPageState: PageSnapshot = $state({
     route: '',
     params: {},
     url: new URL('http://localhost/'),
 })
 
+/*
+Public page state. A getter proxy over the side's registered resolver
+(activePage): client → clientPageState singleton, server → the per-request
+ALS snapshot. Property reads on the client resolve to the $state singleton, so
+reactivity flows; on the server each render reads its own request scope. Users
+only ever see route/params/url.
+*/
+export const page = {
+    get route() {
+        return activePage().route
+    },
+    get params() {
+        return activePage().params
+    },
+    get url() {
+        return activePage().url
+    },
+} as unknown as Page
+
 /*
 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`
@@ -116,15 +142,13 @@ function applyState(
 ): void {
     renderState.Layout = Layout
     renderState.Page = Page
-    const mutable = page as PageStateFor<string>
-    mutable.route = route
-    mutable.params = params
+    clientPageState.route = route
+    clientPageState.params = params
     syncUrl()
 }
 
 function syncUrl(): void {
-    const mutable = page as PageStateFor<string>
-    mutable.url = new URL(window.location.href)
+    clientPageState.url = new URL(window.location.href)
 }
 
 /*
@@ -207,7 +231,7 @@ export async function navigate(href: string, options: NavigateOptions = {}): Pro
         return
     }
     const fullTarget = `${target.pathname}${target.search}${target.hash}`
-    if (target.pathname === page.url.pathname) {
+    if (target.pathname === clientPageState.url.pathname) {
         writeHistory(replace, fullTarget)
         syncUrl()
         return
@@ -234,7 +258,7 @@ 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) {
+    if (pathname === clientPageState.url.pathname) {
         syncUrl()
         return
     }

package/src/lib/browser/startClient.ts

@@ -3,13 +3,21 @@ import App from '../../App.svelte'
 import { createCacheStore } from '../shared/createCacheStore.ts'
 import { setCacheStoreResolver } from '../shared/setCacheStoreResolver.ts'
 import { setGlobalCacheStoreResolver } from '../shared/setGlobalCacheStoreResolver.ts'
+import { setPageResolver } from '../shared/setPageResolver.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 {
+    bindPage,
+    clientPageState,
+    handlePopstate,
+    navigate,
+    page,
+    renderState,
+} from './page.svelte.ts'
 import type { Layouts } from './types/Layouts.ts'
 import type { Pages } from './types/Pages.ts'
 
@@ -107,6 +115,8 @@ export async function startClient({
     setCacheStoreResolver(() => cacheStore)
     /* One tab store: cache(fn, { global: true }) shares it, so global is a no-op here. */
     setGlobalCacheStoreResolver(() => cacheStore)
+    /* One document: the `page` proxy resolves to this $state singleton, mutated by navigate(). */
+    setPageResolver(() => clientPageState)
     if (window.__SSR__.cache) {
         hydrateCacheFromSnapshot(cacheStore, window.__SSR__.cache)
     }

package/src/lib/mcp/dispatchMcpRequest.ts

@@ -1,8 +1,7 @@
-import { promptRegistry } from '../server/prompts/promptRegistry.ts'
 import { ensureRegistriesLoaded } from '../server/runtime/registryManifests.ts'
 import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
 import { getMcpResourceServer } from './mcpResourceServerSlot.ts'
-import { buildPrompts, buildTools, callTool } from './mcpSurface.ts'
+import { buildPrompts, buildTools, callTool, renderPrompt } from './mcpSurface.ts'
 import type { JsonRpcRequest } from './types/JsonRpcRequest.ts'
 import type { JsonRpcResponse } from './types/JsonRpcResponse.ts'
 import type { McpServerOptions } from './types/McpServerOptions.ts'
@@ -33,14 +32,13 @@ function getPrompt(
     name: string,
     args: Record<string, unknown> | undefined,
 ): Record<string, unknown> {
-    const entry = promptRegistry.get(name)
-    if (!entry) {
-        throw new Error(`unknown prompt: ${name}`)
-    }
-    const rendered = entry.prompt.render((args ?? {}) as Record<string, string>)
+    const { description, messages } = renderPrompt(name, args)
     return {
-        ...(entry.prompt.description ? { description: entry.prompt.description } : {}),
-        messages: [{ role: 'user', content: { type: 'text', text: rendered } }],
+        ...(description ? { description } : {}),
+        messages: messages.map((message) => ({
+            role: message.role,
+            content: { type: 'text', text: message.text },
+        })),
     }
 }
 

package/src/lib/mcp/mcpSurface.ts

@@ -230,16 +230,31 @@ export async function callTool(
 }
 
 /*
-Renders a prompt to the message(s) that seed a conversation. A markdown
-prompt is a single user turn whose text is the interpolated template.
-Throws on an unknown prompt name.
+Renders a prompt: looks it up, interpolates the caller's args, and returns its
+optional description plus the message(s) that seed a conversation. A markdown
+prompt is a single user turn whose text is the interpolated template. Throws on
+an unknown prompt name. The one place prompt rendering lives — dispatchMcpRequest
+wraps this in the prompts/get wire shape, the agent loop reads the messages plain.
 */
-export function getPromptMessages(name: string, args?: Record<string, unknown>): PromptMessage[] {
+export function renderPrompt(
+    name: string,
+    args?: Record<string, unknown>,
+): { description?: string; messages: PromptMessage[] } {
     const entry = promptRegistry.get(name)
     if (!entry) {
         throw new Error(`unknown prompt: ${name}`)
     }
-    return [{ role: 'user', text: entry.prompt.render((args ?? {}) as Record<string, string>) }]
+    return {
+        ...(entry.prompt.description ? { description: entry.prompt.description } : {}),
+        messages: [
+            { role: 'user', text: entry.prompt.render((args ?? {}) as Record<string, string>) },
+        ],
+    }
+}
+
+// The conversation-seeding messages for a prompt, without the wire-shape wrapping.
+export function getPromptMessages(name: string, args?: Record<string, unknown>): PromptMessage[] {
+    return renderPrompt(name, args).messages
 }
 
 /*
@@ -248,10 +263,20 @@ Projects the app's MCP surface for an in-process consumer bound to `request`
 the model acts with the caller's identity. Used by `agent()`.
 */
 export function mcpSurface(request: Request): McpSurface {
+    // Built on first read and memoized: an engine that advertises tools but never
+    // reads prompts (or reaches tools over HTTP, reading neither) skips the unused build.
+    let tools: ToolDescriptor[] | undefined
+    let prompts: PromptDescriptor[] | undefined
     return {
-        tools: buildTools(),
+        get tools() {
+            tools ??= buildTools()
+            return tools
+        },
+        get prompts() {
+            prompts ??= buildPrompts()
+            return prompts
+        },
         call: (name, args) => callTool(name, args, request),
-        prompts: buildPrompts(),
         getPrompt: getPromptMessages,
         async listResources() {
             const server = getMcpResourceServer()

package/src/lib/server/agent.ts

@@ -41,7 +41,16 @@ export type AgentFrame =
     | { type: 'text'; delta: string }
     | { type: 'tool_use'; id: string; name: string; input: unknown }
     | { type: 'tool_result'; id: string; name: string; ok: boolean }
-    | { type: 'done'; stop: 'end' | 'tool_use' | 'max_tokens' | 'refusal' }
+    /*
+    `stop` is the reason the engine's loop ended. `error` covers an abnormal
+    stop the model didn't choose — a provider error/limit (e.g. Claude Code's
+    max-turns) or the engine's own tool-loop cap — so a client can tell a cut-off
+    answer from a clean `end`.
+    */
+    | {
+          type: 'done'
+          stop: 'end' | 'tool_use' | 'max_tokens' | 'refusal' | 'error'
+      }
 
 // The app's tool/prompt/resource surface handed to an engine (already gated).
 export type AgentSurface = McpSurface

package/src/lib/server/runtime/createServer.ts

@@ -262,17 +262,17 @@ export async function createServer({
         ])
         const ErrorView = errorMod.default as Component
         const Layout = layoutMod?.default as Component | undefined
+        // status is a number (and stack optional); the page-params shape is
+        // string-keyed generically, so the error props ride through as-is.
+        const errorParams = { status, message, stack } as unknown as Record<string, string>
+        /* Publish to the store too, so the `page` proxy resolves these during the error render
+           (renderError bypasses renderPage, which is where normal renders set them). */
+        store.route = pathname
+        store.params = errorParams
         const rendered = await render(App, {
             props: {
                 state: {
-                    page: {
-                        route: pathname,
-                        // status is a number (and stack optional); the page-params
-                        // shape is string-keyed generically, so the error props
-                        // ride through to the component as-is.
-                        params: { status, message, stack } as unknown as Record<string, string>,
-                        url: store.url,
-                    },
+                    page: { route: pathname, params: errorParams, url: store.url },
                     render: { Layout, Page: ErrorView },
                 },
             },
@@ -293,6 +293,9 @@ export async function createServer({
         params: Record<string, string>,
         store: RequestStore,
     ): Promise<Response> {
+        /* Publish the match so the `page` proxy resolves route/params during SSR render. */
+        store.route = routeUrl
+        store.params = params
         const json = wantsJson(store.req)
         if (json) {
             return Response.json(

package/src/lib/server/runtime/types/RequestStore.ts

@@ -12,6 +12,13 @@ export type RequestStore = {
     req: Request
     cache: CacheStore
     /*
+    The matched page route and its decoded params, set just before the page
+    renders so the `page` proxy resolves them inside layout-scoped components
+    during SSR. Undefined on rpc/socket requests and until a page match lands.
+    */
+    route?: string
+    params?: Record<string, string>
+    /*
     The request's cookie jar, materialized lazily by the first cookies() call
     and flushed to Set-Cookie headers when the scope returns. Undefined while a
     request never touches cookies, so the common path parses and emits nothing.

package/src/lib/shared/activePage.ts

@@ -0,0 +1,20 @@
+import { pageSlot } from './pageSlot.ts'
+import type { PageSnapshot } from './types/PageSnapshot.ts'
+
+/*
+Resolves the active page snapshot. The runtime is registered via
+`setPageResolver` from the server entry (request-scoped via ALS) or the
+client entry (module-level singleton). If no resolver is registered, a single
+fallback snapshot is created lazily so isolated tests still work. Mirrors
+activeCacheStore.
+*/
+export function activePage(): PageSnapshot {
+    const fromResolver = pageSlot.resolver?.()
+    if (fromResolver) {
+        return fromResolver
+    }
+    if (!pageSlot.fallback) {
+        pageSlot.fallback = { route: '', params: {}, url: new URL('http://localhost/') }
+    }
+    return pageSlot.fallback
+}

package/src/lib/shared/pageSlot.ts

@@ -0,0 +1,17 @@
+import type { PageSnapshot } from './types/PageSnapshot.ts'
+
+/*
+Internal slot the runtime entries register their page resolver into. The
+server entry installs an ALS-backed resolver (request-scoped, so concurrent
+and streaming renders never share state); the client entry installs a
+module-singleton resolver. `fallback` is a single lazy snapshot used only
+when no resolver is registered — keeps isolated tests working without forcing
+them to spin up the runtime. Mirrors cacheStoreSlot.
+*/
+export const pageSlot: {
+    resolver: (() => PageSnapshot | undefined) | undefined
+    fallback: PageSnapshot | undefined
+} = {
+    resolver: undefined,
+    fallback: undefined,
+}

package/src/lib/shared/setPageResolver.ts

@@ -0,0 +1,7 @@
+import { pageSlot } from './pageSlot.ts'
+import type { PageSnapshot } from './types/PageSnapshot.ts'
+
+// Registers the runtime's page resolver. Called once per side at boot.
+export function setPageResolver(fn: () => PageSnapshot | undefined): void {
+    pageSlot.resolver = fn
+}

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

@@ -0,0 +1,11 @@
+/*
+Side-agnostic shape of the active page state: the matched route, its decoded
+params, and the live request/location URL. The browser `page` proxy reads its
+public fields through this; the server resolver reads them off the per-request
+store, the client resolver off the module singleton.
+*/
+export type PageSnapshot = {
+    route: string
+    params: Record<string, string>
+    url: URL
+}

package/src/serverEntry.ts

@@ -35,6 +35,7 @@ import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
 import { runningAsStandaloneBinary } from './lib/shared/runningAsStandaloneBinary.ts'
 import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
 import { setGlobalCacheStoreResolver } from './lib/shared/setGlobalCacheStoreResolver.ts'
+import { setPageResolver } from './lib/shared/setPageResolver.ts'
 
 /*
 Resolve config into process.env before anything reads it (createServer reads
@@ -67,6 +68,21 @@ exitWithParent()
 
 setCacheStoreResolver(() => requestContext.getStore()?.cache)
 
+/*
+Request-scoped page resolver: the `page` proxy reads route/params/url off the
+ALS store, so layout-scoped components see the live match during SSR without a
+module singleton leaking across concurrent or streaming renders. route/params
+land just before render; url is set at the request boundary, so 404/error
+renders still get a correct page.url.
+*/
+setPageResolver(() => {
+    const store = requestContext.getStore()
+    if (!store) {
+        return undefined
+    }
+    return { route: store.route ?? '', params: store.params ?? {}, url: store.url }
+})
+
 /*
 Process-level store for cache(fn, { global: true }) — one per server process,
 outlives every request so memoised external calls are shared across them.