@briancray/belte 0.1.0 → 0.2.1

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

@@ -1,3 +1,8 @@
+import {
+    IMMUTABLE_ASSET_CACHE_CONTROL,
+    REVALIDATE_ASSET_CACHE_CONTROL,
+} from '../../shared/cacheControlValues.ts'
+
 /*
 Bun.build emits `[name]-[hash].[ext]` for chunks; hash is alnum and >=8 chars.
 Source maps inherit the same name (e.g. foo-abc12345.js.map), so the suffix may be `.map`.
@@ -11,7 +16,7 @@ Hashed chunk filenames are content-addressed and immutable; everything else
 */
 export function cacheControlForAsset(pathname: string): string {
     if (HASHED.test(pathname)) {
-        return 'public, max-age=31536000, immutable'
+        return IMMUTABLE_ASSET_CACHE_CONTROL
     }
-    return 'public, max-age=0, must-revalidate'
+    return REVALIDATE_ASSET_CACHE_CONTROL
 }

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

@@ -0,0 +1,35 @@
+import { mimeForExtension } from './mimeForExtension.ts'
+
+/*
+A static-asset response's headers depend only on its pathname (extension →
+Content-Type, path → Cache-Control), so each distinct pathname's header bundle
+is built once and reused across every hit on that chunk — avoiding a per-request
+allocation on a cold page load that pulls dozens of files. Each bundle carries
+the plain `base` headers plus a `zstd` variant with `Content-Encoding: zstd`.
+`cacheControlFor` lets callers vary the policy: hashed-aware for `/_app/`,
+fixed for public/.
+*/
+type AssetHeaderBundle = {
+    base: HeadersInit
+    zstd: HeadersInit
+}
+
+export function createAssetHeaderCache(
+    cacheControlFor: (pathname: string) => string,
+): (pathname: string) => AssetHeaderBundle {
+    const cache = new Map<string, AssetHeaderBundle>()
+    return function headersFor(pathname) {
+        const cached = cache.get(pathname)
+        if (cached) {
+            return cached
+        }
+        const base: HeadersInit = {
+            'Content-Type': mimeForExtension(pathname),
+            Vary: 'Accept-Encoding',
+            'Cache-Control': cacheControlFor(pathname),
+        }
+        const bundle: AssetHeaderBundle = { base, zstd: { ...base, 'Content-Encoding': 'zstd' } }
+        cache.set(pathname, bundle)
+        return bundle
+    }
+}

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

@@ -1,9 +1,9 @@
+import { PUBLIC_ASSET_CACHE_CONTROL } from '../../shared/cacheControlValues.ts'
+import { acceptsZstd } from './acceptsZstd.ts'
 import { containsTraversal } from './containsTraversal.ts'
-import { mimeForExtension } from './mimeForExtension.ts'
+import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import type { Assets } from './types/Assets.ts'
 
-const PUBLIC_CACHE_CONTROL = 'public, max-age=3600'
-
 /*
 Serves files from the project's `public/` folder at the site root. Two
 sources, picked at construction:
@@ -25,27 +25,13 @@ export function createPublicAssetServer({
     publicDir: string
     publicAssets?: Assets
 }): (req: Request, url: URL) => Promise<Response | undefined> {
-    const headerCache = new Map<string, { base: HeadersInit; zstd: HeadersInit }>()
-    function headersFor(pathname: string): { base: HeadersInit; zstd: HeadersInit } {
-        const cached = headerCache.get(pathname)
-        if (cached) {
-            return cached
-        }
-        const base: HeadersInit = {
-            'Content-Type': mimeForExtension(pathname),
-            Vary: 'Accept-Encoding',
-            'Cache-Control': PUBLIC_CACHE_CONTROL,
-        }
-        const bundle = { base, zstd: { ...base, 'Content-Encoding': 'zstd' } }
-        headerCache.set(pathname, bundle)
-        return bundle
-    }
+    const headersFor = createAssetHeaderCache(() => PUBLIC_ASSET_CACHE_CONTROL)
 
     return async function servePublicAsset(req, url) {
         if (containsTraversal(req.url)) {
             return undefined
         }
-        const wantsZstd = (req.headers.get('accept-encoding') ?? '').toLowerCase().includes('zstd')
+        const wantsZstd = acceptsZstd(req)
         const { base, zstd } = headersFor(url.pathname)
         if (publicAssets) {
             const compressed = publicAssets[url.pathname]
@@ -55,7 +41,7 @@ export function createPublicAssetServer({
             if (wantsZstd) {
                 return new Response(compressed, { headers: zstd })
             }
-            return new Response(Bun.zstdDecompressSync(compressed), { headers: base })
+            return new Response(await Bun.zstdDecompress(compressed), { headers: base })
         }
         const file = Bun.file(publicDir + url.pathname)
         if (!(await file.exists())) {

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

@@ -23,11 +23,12 @@ import type { RemoteFunction } from '../rpc/types/RemoteFunction.ts'
 import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
 import { createSocketDispatcher } from '../sockets/createSocketDispatcher.ts'
 import type { SocketRoutes } from '../sockets/types/SocketRoutes.ts'
+import { acceptsZstd } from './acceptsZstd.ts'
 import { buildOpenApiSpec } from './buildOpenApiSpec.ts'
 import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
+import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
-import { mimeForExtension } from './mimeForExtension.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
 import { requestContext } from './requestContext.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
@@ -36,18 +37,38 @@ import { setActiveServer } from './setActiveServer.ts'
 import type { Assets } from './types/Assets.ts'
 import type { RequestStore } from './types/RequestStore.ts'
 
-function acceptsZstd(req: Request): boolean {
-    return (req.headers.get('accept-encoding') ?? '').toLowerCase().includes('zstd')
-}
-
 function wantsJson(req: Request): boolean {
     return (req.headers.get('accept') ?? '').includes('application/json')
 }
 
+/*
+The framework's default 500 response — a `<pre>` stack dump. Shared by the
+per-request catch and Bun.serve's global error() fallback so the two can't
+drift. Only reached when the app supplies no `handleError` hook.
+*/
+function internalErrorResponse(err: unknown): Response {
+    return new Response(`<pre>${String((err as Error)?.stack ?? err)}</pre>`, {
+        status: 500,
+        headers: {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': NO_STORE,
+        },
+    })
+}
+
+const IDENTITY_PATH = '/__belte/identity'
 const SOCKETS_PATH = '/__belte/sockets'
 const MCP_PATH = '/__belte/mcp'
 const CLI_PATH = '/__belte/cli'
 const CLI_DOWNLOAD_PREFIX = '/__belte/cli/'
+/*
+Unlike the framework's own plumbing routes above (the socket multiplex, MCP
+endpoint, CLI download), the OpenAPI document describes the app's public HTTP
+surface — the /rpc/* verbs — rather than belte internals, so it sits at the
+conventional root path where external tooling and scanners expect to find it
+(/openapi.json, alongside /swagger.json, /.well-known/*) rather than under the
+/__belte/ namespace.
+*/
 const OPENAPI_PATH = '/openapi.json'
 
 type AnyRemoteFunction = RemoteFunction<unknown, unknown>
@@ -105,12 +126,6 @@ export async function createServer({
     const cliName = cliProgramName ?? 'app'
     const cliCwd = process.cwd()
     const servePublicAsset = createPublicAssetServer({ publicDir, publicAssets })
-    /*
-    Forward-declared so the per-request closures below can reference it. The
-    value is assigned by Bun.serve() further down; closures only fire after
-    that, so the read-before-write is safe at runtime.
-    */
-    let server!: Server<unknown>
     const layoutPrefixes = layouts ? normalizeLayoutPrefixes(Object.keys(layouts)) : []
 
     const diskZstdPaths = new Set<string>(
@@ -150,32 +165,8 @@ export async function createServer({
 
     const logRequests = isDebugEnabled('belte')
 
-    /*
-    Header objects for a pathname depend only on the pathname's extension
-    and the immutable HASHED test. Cache them so repeat hits on the same
-    chunk reuse a single frozen header bag instead of allocating per
-    request.
-    */
-    type AssetHeaderBundle = {
-        base: HeadersInit
-        zstd: HeadersInit
-    }
-    const assetHeaderCache = new Map<string, AssetHeaderBundle>()
-    function headersForAsset(pathname: string): AssetHeaderBundle {
-        const cached = assetHeaderCache.get(pathname)
-        if (cached) {
-            return cached
-        }
-        const base: HeadersInit = {
-            'Content-Type': mimeForExtension(pathname),
-            Vary: 'Accept-Encoding',
-            'Cache-Control': cacheControlForAsset(pathname),
-        }
-        const zstd: HeadersInit = { ...base, 'Content-Encoding': 'zstd' }
-        const bundle = { base, zstd }
-        assetHeaderCache.set(pathname, bundle)
-        return bundle
-    }
+    // Per-pathname asset header bundles, hashed-chunk-aware Cache-Control.
+    const headersForAsset = createAssetHeaderCache(cacheControlForAsset)
 
     async function serveStaticAsset(req: Request, url: URL): Promise<Response> {
         /*
@@ -206,7 +197,7 @@ export async function createServer({
             if (wantsZstd) {
                 return new Response(compressed, { headers: zstdHeaders })
             }
-            return new Response(Bun.zstdDecompressSync(compressed), { headers: baseHeaders })
+            return new Response(await Bun.zstdDecompress(compressed), { headers: baseHeaders })
         }
         const diskPath = distDir + url.pathname
         if (wantsZstd && diskZstdPaths.has(url.pathname)) {
@@ -374,9 +365,7 @@ export async function createServer({
         const store: RequestStore = {
             url,
             req,
-            signal: req.signal,
             cache: createCacheStore(),
-            server,
         }
         return requestContext.run(store, async () => {
             const start = logRequests ? Bun.nanoseconds() : 0
@@ -388,16 +377,7 @@ export async function createServer({
                     response = await app.handleError(error, req)
                 } else {
                     log.error(error)
-                    response = new Response(
-                        `<pre>${String((error as Error)?.stack ?? error)}</pre>`,
-                        {
-                            status: 500,
-                            headers: {
-                                'Content-Type': 'text/html; charset=utf-8',
-                                'Cache-Control': NO_STORE,
-                            },
-                        },
-                    )
+                    response = internalErrorResponse(error)
                 }
             }
             if (logRequests) {
@@ -417,7 +397,8 @@ export async function createServer({
     a busy socket doesn't iterate JS per subscriber per message.
     */
     const socketDispatcher = createSocketDispatcher(sockets)
-    server = Bun.serve({
+    // Server<unknown> pins Bun's WebSocketData generic so upgrade({ data: {} }) typechecks.
+    const server: Server<unknown> = Bun.serve({
         port,
 
         websocket: {
@@ -436,6 +417,23 @@ export async function createServer({
 
         async fetch(req, bunServer) {
             const url = new URL(req.url)
+            /*
+            Identity probe — answered directly, ahead of any app.handle middleware,
+            so the bundle's connect screen can confirm a URL really is a belte
+            server (and which app) before pointing the desktop window at it. It
+            must stay reachable even when the app guards everything behind auth,
+            hence the early return that bypasses dispatchRequest.
+            */
+            if (url.pathname === IDENTITY_PATH) {
+                return Response.json(
+                    {
+                        belte: true,
+                        name: appInfo?.name ?? cliName,
+                        version: appInfo?.version ?? '0.0.0',
+                    },
+                    { headers: { 'Cache-Control': NO_STORE } },
+                )
+            }
             if (url.pathname === SOCKETS_PATH) {
                 if (bunServer.upgrade(req, { data: {} })) {
                     return undefined as unknown as Response
@@ -515,13 +513,7 @@ export async function createServer({
 
         error(err) {
             log.error(err)
-            return new Response(`<pre>${String(err.stack ?? err)}</pre>`, {
-                status: 500,
-                headers: {
-                    'Content-Type': 'text/html; charset=utf-8',
-                    'Cache-Control': NO_STORE,
-                },
-            })
+            return internalErrorResponse(err)
         },
     })
 

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

@@ -20,29 +20,47 @@ type RegistryManifests = {
 }
 
 let manifests: RegistryManifests | undefined
-let loadedAll = false
+let loading: Promise<void> | undefined
 
 export function setRegistryManifests(value: RegistryManifests): void {
     manifests = value
-    loadedAll = false
+    loading = undefined
 }
 
 /*
 On first call, eagerly imports every rpc + socket + prompt module so
 defineVerb / defineSocket / definePrompt fire and populate the
-registries. Idempotent — repeat calls are no-ops. Eager loading is
-acceptable here because enumeration (MCP tool/resource/prompt lists,
-the OpenAPI document) fundamentally requires the full surface; the
-alternative of per-call lazy loading produces flaky first-call latency.
+registries. Idempotent — repeat calls reuse the same in-flight promise,
+so concurrent first requests (e.g. /openapi.json + an MCP tools/list)
+trigger exactly one load instead of racing to fire the full import set
+each. Eager loading is acceptable here because enumeration (MCP
+tool/resource/prompt lists, the OpenAPI document) fundamentally requires
+the full surface; the alternative of per-call lazy loading produces flaky
+first-call latency.
 */
-export async function ensureRegistriesLoaded(): Promise<void> {
-    if (loadedAll || !manifests) {
-        return
+export function ensureRegistriesLoaded(): Promise<void> {
+    if (!manifests) {
+        return Promise.resolve()
     }
-    await Promise.all([
-        ...Object.values(manifests.rpc).map((loader) => loader()),
-        ...Object.values(manifests.sockets).map((loader) => loader()),
-        ...Object.values(manifests.prompts).map((loader) => loader()),
-    ])
-    loadedAll = true
+    if (!loading) {
+        const { rpc, sockets, prompts } = manifests
+        loading = Promise.all([
+            ...Object.values(rpc).map((loader) => loader()),
+            ...Object.values(sockets).map((loader) => loader()),
+            ...Object.values(prompts).map((loader) => loader()),
+        ])
+            .then(() => undefined)
+            /*
+            Clear the memo on failure so a transient import error (a
+            module that throws at load, fixed by the next HMR pass)
+            doesn't poison every later enumeration request for the
+            process lifetime. The rejection still propagates to this
+            caller; the reset only affects subsequent calls.
+            */
+            .catch((error) => {
+                loading = undefined
+                throw error
+            })
+    }
+    return loading
 }

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

@@ -1,15 +1,14 @@
-import type { Server } from 'bun'
 import type { CacheStore } from '../../../shared/types/CacheStore.ts'
 
 /*
 Per-request state propagated through AsyncLocalStorage. Every field is
 populated once at the server's fetch boundary; helpers and verb-defined
 remote functions read from it without threading arguments through user code.
+The inbound request's AbortSignal is reached via `req.signal` rather than a
+separate field.
 */
 export type RequestStore = {
     url: URL
     req: Request
-    signal: AbortSignal
     cache: CacheStore
-    server: Server<unknown>
 }

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

@@ -0,0 +1,24 @@
+/*
+Merges a caller's `ResponseInit` over a respond helper's default headers.
+The helper's defaults seed the header set; the caller's headers overlay them
+per-key (so an explicit `cache-control` wins over the helper's `no-store`),
+and the rest of `init` (status, statusText) passes straight through. Shared
+by `json` / `jsonl` / `sse` / `error` / `redirect` so every helper accepts a
+final `ResponseInit` with identical override semantics.
+
+A helper that owns the status itself (`error`, `redirect`) passes it as the
+final `status` argument; it is applied last so it always wins over any
+`init.status`, keeping that precedence inside the helper rather than relying
+on each call site spreading in the right order.
+*/
+export function withResponseDefaults(
+    init: ResponseInit | undefined,
+    defaultHeaders: Record<string, string>,
+    status?: number,
+): ResponseInit {
+    const headers = new Headers(defaultHeaders)
+    new Headers(init?.headers).forEach((value, key) => {
+        headers.set(key, value)
+    })
+    return { ...init, headers, ...(status !== undefined && { status }) }
+}

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -3,6 +3,10 @@ import { log } from '../../shared/log.ts'
 import { lookupSocket } from './lookupSocket.ts'
 import type { SocketClientFrame } from './types/SocketClientFrame.ts'
 import type { SocketRoutes } from './types/SocketRoutes.ts'
+import type { SocketServerFrame } from './types/SocketServerFrame.ts'
+
+// Reused across every inbound binary frame rather than allocated per message.
+const textDecoder = new TextDecoder()
 
 type SocketDispatcher = {
     open(ws: ServerWebSocket<unknown>): void
@@ -60,8 +64,8 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         return promise
     }
 
-    function send(ws: ServerWebSocket<unknown>, frame: unknown): void {
-        if (ws.readyState !== 1) {
+    function send(ws: ServerWebSocket<unknown>, frame: SocketServerFrame): void {
+        if (ws.readyState !== WebSocket.OPEN) {
             return
         }
         ws.send(JSON.stringify(frame))
@@ -154,10 +158,9 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         const replayCount =
             frame.replay === undefined ? history.length : Math.min(frame.replay, history.length)
         if (replayCount > 0) {
-            const start = history.length - replayCount
-            for (let index = start; index < history.length; index++) {
-                send(ws, { type: 'msg', socket: frame.socket, message: history[index] })
-            }
+            history.slice(history.length - replayCount).forEach((message) => {
+                send(ws, { type: 'msg', socket: frame.socket, message })
+            })
         }
     }
 
@@ -232,7 +235,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             if (!state) {
                 return
             }
-            const text = typeof data === 'string' ? data : data.toString('utf8')
+            const text = typeof data === 'string' ? data : textDecoder.decode(data)
             let frame: SocketClientFrame
             try {
                 frame = JSON.parse(text) as SocketClientFrame

package/src/lib/server/sse.ts

@@ -26,22 +26,27 @@ maps it to the entry's `error` field.
 import { NO_STORE } from '../shared/cacheControlValues.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>): TypedResponse<Frame> {
+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) => `event: error\ndata: ${JSON.stringify({ message })}\n\n`,
         keepaliveMs: KEEPALIVE_INTERVAL_MS,
         keepalivePayload: ': keepalive\n\n',
     })
-    return new Response(body, {
-        headers: {
+    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>
+        }),
+    ) as TypedResponse<Frame>
 }

package/src/lib/shared/belteImportName.test.ts

@@ -0,0 +1,58 @@
+import { afterAll, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { belteImportName } from './belteImportName.ts'
+
+const roots: string[] = []
+afterAll(() => roots.forEach((root) => rmSync(root, { recursive: true, force: true })))
+
+// Writes a package.json into a fresh temp dir and returns the dir.
+async function projectWith(packageJson: unknown): Promise<string> {
+    const root = mkdtempSync(`${tmpdir()}/belte-import-name-`)
+    roots.push(root)
+    await Bun.write(`${root}/package.json`, JSON.stringify(packageJson))
+    return root
+}
+
+test('uses the canonical name for a direct dependency', async () => {
+    const cwd = await projectWith({ dependencies: { '@briancray/belte': '^0.2.0' } })
+    expect(await belteImportName(cwd)).toBe('@briancray/belte')
+})
+
+test('uses the `belte` alias key for an npm alias', async () => {
+    const cwd = await projectWith({ dependencies: { belte: 'npm:@briancray/belte@^0.2.0' } })
+    expect(await belteImportName(cwd)).toBe('belte')
+})
+
+test('uses the `belte` alias key for a workspace alias', async () => {
+    const cwd = await projectWith({ dependencies: { belte: 'workspace:@briancray/belte@*' } })
+    expect(await belteImportName(cwd)).toBe('belte')
+})
+
+test('uses a non-`belte` alias key when that is how belte is declared', async () => {
+    const cwd = await projectWith({ dependencies: { framework: 'npm:@briancray/belte' } })
+    expect(await belteImportName(cwd)).toBe('framework')
+})
+
+test('prefers the `belte` alias over a direct canonical dependency', async () => {
+    const cwd = await projectWith({
+        dependencies: { '@briancray/belte': '^0.2.0', belte: 'npm:@briancray/belte@^0.2.0' },
+    })
+    expect(await belteImportName(cwd)).toBe('belte')
+})
+
+test('finds the alias in devDependencies', async () => {
+    const cwd = await projectWith({ devDependencies: { belte: 'npm:@briancray/belte@^0.2.0' } })
+    expect(await belteImportName(cwd)).toBe('belte')
+})
+
+test('falls back to the canonical name when belte is absent', async () => {
+    const cwd = await projectWith({ dependencies: { svelte: '^5.0.0' } })
+    expect(await belteImportName(cwd)).toBe('@briancray/belte')
+})
+
+test('falls back to the canonical name when package.json is missing', async () => {
+    const root = mkdtempSync(`${tmpdir()}/belte-import-name-`)
+    roots.push(root)
+    expect(await belteImportName(root)).toBe('@briancray/belte')
+})

package/src/lib/shared/belteImportName.ts

@@ -0,0 +1,45 @@
+import { beltePackageName } from './beltePackageName.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 (`@briancray/belte`) or behind a package alias
+(`"belte": "npm:@briancray/belte@..."`, or `workspace:@briancray/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 actually
+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 packageJsonPath = `${cwd}/package.json`
+    if (!(await Bun.file(packageJsonPath).exists())) {
+        return beltePackageName
+    }
+    const packageJson = (await Bun.file(packageJsonPath).json()) as {
+        dependencies?: Record<string, string>
+        devDependencies?: Record<string, string>
+    }
+    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):${beltePackageName}(@.*)?$`)
+    const aliasNames = Object.entries(dependencies)
+        .filter(([, specifier]) => aliasPattern.test(specifier))
+        .map(([name]) => name)
+    if (aliasNames.includes('belte')) {
+        return 'belte'
+    }
+    if (beltePackageName in dependencies) {
+        return beltePackageName
+    }
+    return aliasNames[0] ?? beltePackageName
+}

package/src/lib/shared/beltePackageName.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 beltePackageName = '@briancray/belte'

package/src/lib/shared/cacheControlValues.ts

@@ -1,8 +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) lives in one place and can't drift between
-the server core and the respond 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/canonicalJson.ts

@@ -16,9 +16,5 @@ function sortedKeysReplacer(_key: string, value: unknown): unknown {
     }
     const record = value as Record<string, unknown>
     const sortedKeys = Object.keys(record).sort()
-    const sorted: Record<string, unknown> = {}
-    for (const key of sortedKeys) {
-        sorted[key] = record[key]
-    }
-    return sorted
+    return Object.fromEntries(sortedKeys.map((key) => [key, record[key]]))
 }