@briancray/belte 0.1.0

package/src/build.ts

@@ -0,0 +1,144 @@
+import type { BunPlugin } from 'bun'
+import { belteResolverPlugin } from './belteResolverPlugin.ts'
+import type { SvelteConfig } from './lib/server/runtime/types/SvelteConfig.ts'
+import { loadSvelteConfig } from './lib/shared/loadSvelteConfig.ts'
+import { log } from './lib/shared/log.ts'
+import { sveltePlugin } from './sveltePlugin.ts'
+
+type ExportEntry = string | { [condition: string]: ExportEntry }
+
+/*
+Walks a package.json `exports` entry, returning the first leaf string that
+matches the supplied condition list in order. Returns undefined when no
+branch resolves.
+*/
+function pickExport(entry: ExportEntry, conditions: string[]): string | undefined {
+    if (typeof entry === 'string') {
+        return entry
+    }
+    for (const condition of conditions) {
+        if (entry[condition]) {
+            const resolved = pickExport(entry[condition], conditions)
+            if (resolved) {
+                return resolved
+            }
+        }
+    }
+    return undefined
+}
+
+/*
+Forces every `import 'svelte/...'` (from belte's own source, the consumer's
+source, or any transitive dep) to resolve against the consumer app's svelte
+install, picking the export condition that matches the build target.
+Without this, belte's symlinked source can pick up a second svelte from its
+install location, ship both runtimes, and break hydration.
+*/
+function dedupeSveltePlugin({ cwd, conditions }: { cwd: string; conditions: string[] }): BunPlugin {
+    const consumerSvelte = `${cwd}/node_modules/svelte`
+    return {
+        name: 'belte-dedupe-svelte',
+        async setup(build) {
+            const pkgFile = Bun.file(`${consumerSvelte}/package.json`)
+            if (!(await pkgFile.exists())) {
+                return
+            }
+            const consumerPackage = (await pkgFile.json()) as {
+                exports: Record<string, ExportEntry>
+            }
+            build.onResolve({ filter: /^svelte(\/.*)?$/ }, (args) => {
+                const subpath =
+                    args.path === 'svelte' ? '.' : `.${args.path.slice('svelte'.length)}`
+                const entry = consumerPackage.exports[subpath]
+                if (!entry) {
+                    return undefined
+                }
+                const resolvedFile = pickExport(entry, conditions)
+                if (!resolvedFile) {
+                    return undefined
+                }
+                return { path: `${consumerSvelte}/${resolvedFile.replace(/^\.\//, '')}` }
+            })
+        },
+    }
+}
+
+const CLIENT_ENTRY = new URL('./clientEntry.ts', import.meta.url).pathname
+
+/*
+Builds the client-side bundle into `${cwd}/dist/_app`. Clears the dist
+directory first, then runs Bun.build with the svelte-dedupe plugin, the
+svelte loader, the virtual-module resolver, and (optionally) Tailwind.
+Each emitted file is also written as a zstd-compressed `.zst` sibling
+(level 22 — paid once at build time) so the server can stream the
+precompressed bytes directly when the client supports it, and decompress
+on the fly for older clients. Exits the process on build failure with
+the build logs printed.
+*/
+export async function build({
+    cwd = process.cwd(),
+    svelteConfig,
+    minify = true,
+}: {
+    cwd?: string
+    svelteConfig?: SvelteConfig
+    minify?: boolean
+} = {}): Promise<void> {
+    const distDir = `${cwd}/dist`
+    const outDir = `${distDir}/_app`
+
+    // shell-rm is the impure boundary for "clear dist" — Bun.$ is first-party
+    await Bun.$`rm -rf ${distDir}`.quiet()
+
+    const config = svelteConfig ?? (await loadSvelteConfig(cwd))
+    const plugins: BunPlugin[] = [
+        dedupeSveltePlugin({ cwd, conditions: ['browser', 'default'] }),
+        sveltePlugin({ generate: 'client', svelteConfig: config }),
+        belteResolverPlugin({ cwd, target: 'client' }),
+    ]
+    try {
+        const tailwind = (await import('bun-plugin-tailwind')).default
+        plugins.push(tailwind)
+    } catch {
+        log.warn('bun-plugin-tailwind not installed; building without Tailwind')
+    }
+
+    const result = await Bun.build({
+        entrypoints: [CLIENT_ENTRY],
+        outdir: outDir,
+        target: 'browser',
+        splitting: true,
+        minify,
+        sourcemap: 'linked',
+        naming: {
+            entry: 'client-[hash].[ext]',
+            chunk: '[name]-[hash].[ext]',
+            asset: '[name].[ext]',
+        },
+        plugins,
+    })
+
+    if (!result.success) {
+        for (const entry of result.logs) {
+            log.error(entry)
+        }
+        process.exit(1)
+    }
+
+    const compressedByteLengths = await Promise.all(
+        result.outputs.map(async (output) => {
+            const bytes = await Bun.file(output.path).bytes()
+            const compressed = Bun.zstdCompressSync(bytes, { level: 22 })
+            await Bun.write(`${output.path}.zst`, compressed)
+            return compressed.byteLength
+        }),
+    )
+    const compressedBytes = compressedByteLengths.reduce((total, length) => total + length, 0)
+
+    log.success(
+        `wrote ${result.outputs.length} files to ${outDir} (+${result.outputs.length} .zst, ${(compressedBytes / 1024).toFixed(1)} KiB total)`,
+    )
+    for (const output of result.outputs) {
+        log.detail(`  - ${output.path}`)
+    }
+}

package/src/buildCli.ts

@@ -0,0 +1,160 @@
+import type { BunPlugin } from 'bun'
+import { belteResolverPlugin } from './belteResolverPlugin.ts'
+import type { CompileTarget } from './lib/server/runtime/types/CompileTarget.ts'
+import { detectTarget } from './lib/shared/detectTarget.ts'
+import { loadSvelteConfig } from './lib/shared/loadSvelteConfig.ts'
+import { log } from './lib/shared/log.ts'
+import { programNameForPackage } from './lib/shared/programNameForPackage.ts'
+import { sveltePlugin } from './sveltePlugin.ts'
+
+const DISCOVERY_ENTRY = new URL('./discoveryEntry.ts', import.meta.url).pathname
+const CLI_ENTRY = new URL('./cliEntry.ts', import.meta.url).pathname
+
+/*
+Two-pass CLI binary build:
+
+  1. Discovery: build the discovery entry into a temporary JS bundle and
+     run it. It imports every rpc/socket module so defineVerb /
+     defineSocket populate the registries, then prints the CLI manifest
+     to stdout. The manifest is written to `dist/cli-manifest.json`.
+  2. Compile: build the CLI binary via `Bun.build({ compile })`. The
+     resolver plugin's `belte:cli-manifest` virtual reads the manifest
+     JSON written in step 1 and splices it into the bundle.
+
+The `thin` flag decides thin vs full (default full):
+  - thin: empty `belte:cli-rpcs` virtual — no handlers bundled, the
+          manifest is the only RPC surface; requires APP_URL at runtime.
+  - full: `belte:cli-rpcs` emits eager imports for every rpc module so the
+          verbRegistry is populated and the binary runs in-process (and
+          still reaches a remote server when APP_URL is set at runtime).
+`platforms` cross-compiles in either mode; thin per-platform binaries land
+in `dist/cli-thin/<platform>/` (the layout the /__belte/cli download endpoint
+serves), full ones in `dist/cli/<platform>/`.
+*/
+export async function buildCli({
+    cwd = process.cwd(),
+    target = detectTarget(),
+    outfile,
+    platforms,
+    thin: thinOverride,
+}: {
+    cwd?: string
+    target?: CompileTarget
+    outfile?: string
+    platforms?: CompileTarget[]
+    thin?: boolean
+} = {}): Promise<string[]> {
+    const distDir = `${cwd}/dist`
+    await Bun.$`mkdir -p ${distDir}`.quiet()
+    const manifestPath = `${distDir}/cli-manifest.json`
+    const discoveryOut = `${distDir}/_discovery.js`
+
+    const svelteConfig = await loadSvelteConfig(cwd)
+    const isThin = thinOverride ?? false
+    const sharedPlugins = (): BunPlugin[] => [
+        sveltePlugin({ generate: 'server', svelteConfig }),
+        belteResolverPlugin({ cwd, target: 'server', thin: isThin }),
+    ]
+
+    /*
+    Step 1 — discovery. Build a runnable bundle, execute it under bun,
+    capture stdout. We don't `bun build --compile` here because the
+    discovery output is throwaway; a plain JS bundle runs faster.
+    */
+    const discoveryResult = await Bun.build({
+        entrypoints: [DISCOVERY_ENTRY],
+        target: 'bun',
+        outdir: distDir,
+        naming: '_discovery.js',
+        plugins: sharedPlugins(),
+    })
+    if (!discoveryResult.success) {
+        for (const entry of discoveryResult.logs) {
+            log.error(entry)
+        }
+        process.exit(1)
+    }
+
+    const proc = Bun.spawn({
+        cmd: ['bun', discoveryOut],
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ])
+    if (exitCode !== 0) {
+        log.error(`discovery exited ${exitCode}:\n${stderr}`)
+        process.exit(1)
+    }
+    await Bun.write(manifestPath, stdout)
+    await Bun.$`rm -f ${discoveryOut}`.quiet()
+    const entryCount = Object.keys(JSON.parse(stdout) as Record<string, unknown>).length
+    log.info(`discovered ${entryCount} cli commands → ${manifestPath}`)
+
+    /*
+    Step 2 — compile. The cliEntry imports the now-populated
+    belte:cli-manifest virtual + the eager rpc imports (full mode only,
+    empty for thin). bun build --compile emits the standalone binary.
+    When `platforms` is set, loops once per target and writes binaries
+    into `dist/cli-thin/<platform>/<programName>` (thin — the layout the
+    download route expects) or `dist/cli/<platform>/<programName>` (full).
+    */
+    const programName = await readProgramName(cwd)
+
+    if (platforms && platforms.length > 0) {
+        const platformDir = isThin ? 'cli-thin' : 'cli'
+        const outPaths: string[] = []
+        for (const platformTarget of platforms) {
+            const shortName = platformTarget.replace(/^bun-/, '')
+            const suffix = platformTarget.includes('windows') ? '.exe' : ''
+            const platformOut = `${distDir}/${platformDir}/${shortName}/${programName}${suffix}`
+            await Bun.$`mkdir -p ${`${distDir}/${platformDir}/${shortName}`}`.quiet()
+            const result = await Bun.build({
+                entrypoints: [CLI_ENTRY],
+                target: 'bun',
+                compile: { target: platformTarget, outfile: platformOut },
+                plugins: sharedPlugins(),
+            })
+            if (!result.success) {
+                for (const entry of result.logs) {
+                    log.error(entry)
+                }
+                process.exit(1)
+            }
+            log.success(`compiled ${isThin ? 'thin' : 'full'} cli binary: ${platformOut}`)
+            outPaths.push(platformOut)
+        }
+        return outPaths
+    }
+
+    const suffix = target.includes('windows') ? '.exe' : ''
+    const outPath = outfile ?? `${distDir}/cli${suffix}`
+
+    const cliResult = await Bun.build({
+        entrypoints: [CLI_ENTRY],
+        target: 'bun',
+        compile: { target, outfile: outPath },
+        plugins: sharedPlugins(),
+    })
+    if (!cliResult.success) {
+        for (const entry of cliResult.logs) {
+            log.error(entry)
+        }
+        process.exit(1)
+    }
+
+    log.success(`compiled ${isThin ? 'thin' : 'full'} cli binary: ${outPath} (target: ${target})`)
+    return [outPath]
+}
+
+async function readProgramName(cwd: string): Promise<string> {
+    const pkgFile = Bun.file(`${cwd}/package.json`)
+    if (!(await pkgFile.exists())) {
+        return 'app'
+    }
+    const pkg = (await pkgFile.json()) as { name?: string }
+    return programNameForPackage(pkg.name)
+}

package/src/cliEntry.ts

@@ -0,0 +1,31 @@
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { banner, footer } from './_virtual/cli-chrome.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import manifest from './_virtual/cli-manifest.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import programName from './_virtual/cli-name.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin — side-effect import that
+// populates verbRegistry for in-process mode on full builds; empty on thin builds
+import './_virtual/cli-rpcs.ts'
+import { runCli } from './lib/cli/runCli.ts'
+
+/*
+Standalone CLI binary entry. Compiled with `bun build --compile` into
+`dist/cli` (full, default) or `dist/cli-thin` (with `--thin`). The
+bundler emits:
+  - belte:cli-manifest — the per-rpc manifest (method, url, jsonSchema)
+  - belte:cli-name     — the program name from package.json
+  - belte:cli-chrome   — optional banner/footer text from src/cli/
+
+All are virtual modules so the same source file works for thin and
+full builds; what differs is whether the verbRegistry is also bundled
+in (full mode → in-process fallback; thin mode → APP_URL required).
+*/
+const exitCode = await runCli({
+    programName,
+    manifest,
+    banner,
+    footer,
+    argv: process.argv.slice(2),
+})
+process.exit(exitCode)

package/src/clientEntry.ts

@@ -0,0 +1,7 @@
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { layouts } from './_virtual/layouts.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { pages } from './_virtual/pages.ts'
+import { startClient } from './lib/browser/startClient.ts'
+
+await startClient({ pages, layouts })

package/src/compile.ts

@@ -0,0 +1,64 @@
+import type { BunPlugin } from 'bun'
+import { belteResolverPlugin } from './belteResolverPlugin.ts'
+import { build } from './build.ts'
+import type { CompileTarget } from './lib/server/runtime/types/CompileTarget.ts'
+import { detectTarget } from './lib/shared/detectTarget.ts'
+import { loadSvelteConfig } from './lib/shared/loadSvelteConfig.ts'
+import { log } from './lib/shared/log.ts'
+import { sveltePlugin } from './sveltePlugin.ts'
+
+const SERVER_ENTRY = new URL('./serverEntry.ts', import.meta.url).pathname
+
+/*
+Produces a standalone Bun executable for the server. Runs the client `build`
+first so the resolver plugin can embed the zstd-compressed assets into
+the binary, then invokes Bun.build in compile mode against the server
+entry. Defaults
+the target to the host platform and appends `.exe` for windows targets.
+Returns the path of the emitted binary; exits the process on build failure.
+*/
+export async function compile({
+    cwd = process.cwd(),
+    target = detectTarget(),
+    outfile,
+}: {
+    cwd?: string
+    target?: CompileTarget
+    outfile?: string
+} = {}): Promise<string> {
+    const svelteConfig = await loadSvelteConfig(cwd)
+    await build({ cwd, svelteConfig })
+
+    const outPath = outfile ?? `${cwd}/dist/app${target.includes('windows') ? '.exe' : ''}`
+
+    const plugins: BunPlugin[] = [
+        sveltePlugin({ generate: 'server', svelteConfig }),
+        belteResolverPlugin({ cwd, embedAssets: true, target: 'server' }),
+    ]
+
+    const result = await Bun.build({
+        entrypoints: [SERVER_ENTRY],
+        target: 'bun',
+        format: 'esm',
+        minify: true,
+        /*
+        Bytecode embeds precompiled JS module metadata directly into the
+        standalone binary, dramatically cutting cold-start time for large
+        apps. Requires `target: 'bun'` + an explicit `format` because the
+        default for `bytecode` alone is CommonJS; we need ESM bytecode.
+        */
+        bytecode: true,
+        compile: { target, outfile: outPath },
+        plugins,
+    })
+
+    if (!result.success) {
+        for (const entry of result.logs) {
+            log.error(entry)
+        }
+        process.exit(1)
+    }
+
+    log.success(`compiled standalone binary: ${outPath} (target: ${target})`)
+    return outPath
+}

package/src/devEntry.ts

@@ -0,0 +1,33 @@
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { layouts } from './_virtual/layouts.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { pages } from './_virtual/pages.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { prompts } from './_virtual/prompts.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { rpc } from './_virtual/rpc.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { sockets } from './_virtual/sockets.ts'
+import { build } from './build.ts'
+
+/*
+Dev-only entry. Each `bun --watch` restart re-runs the client build (so the
+browser-served bundle matches the freshly-evaluated server modules) and then
+eagerly invokes every dynamic loader for pages, layouts, rpc handlers, and
+sockets. That pulls those files into Bun's import graph from boot, so the
+watcher sees edits to a page or component on the *first* save instead of
+needing the page to be visited once to warm the dynamic import. Finally
+hands off to the normal server entry, which expects the same virtual
+modules — they're already cached, so it just runs createServer().
+*/
+await build({ cwd: process.cwd(), minify: false })
+
+await Promise.all([
+    ...Object.values(pages).map((loader) => (loader as () => Promise<unknown>)()),
+    ...Object.values(layouts).map((loader) => (loader as () => Promise<unknown>)()),
+    ...Object.values(rpc).map((loader) => (loader as () => Promise<unknown>)()),
+    ...Object.values(sockets).map((loader) => (loader as () => Promise<unknown>)()),
+    ...Object.values(prompts).map((loader) => (loader as () => Promise<unknown>)()),
+])
+
+await import('./serverEntry.ts')

package/src/discoveryEntry.ts

@@ -0,0 +1,33 @@
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { rpc } from './_virtual/rpc.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { sockets } from './_virtual/sockets.ts'
+import { verbRegistry } from './lib/server/rpc/verbRegistry.ts'
+import { commandNameForUrl } from './lib/shared/commandNameForUrl.ts'
+import { jsonSchemaForSchema } from './lib/shared/jsonSchemaForSchema.ts'
+
+/*
+One-shot script that imports every rpc + socket module so defineVerb /
+defineSocket populate the process-wide registries, then prints the CLI
+manifest to stdout as JSON. Used by buildCli to bake the manifest into
+the standalone binary at build time without resorting to static source
+parsing (which can't see toJsonSchema()/toJSONSchema() at compile time).
+*/
+await Promise.all([
+    ...Object.values(rpc).map((loader) => (loader as () => Promise<unknown>)()),
+    ...Object.values(sockets).map((loader) => (loader as () => Promise<unknown>)()),
+])
+
+const manifest: Record<string, unknown> = {}
+for (const entry of verbRegistry.values()) {
+    if (!entry.clients.cli) {
+        continue
+    }
+    manifest[commandNameForUrl(entry.remote.url)] = {
+        method: entry.remote.method,
+        url: entry.remote.url,
+        jsonSchema: jsonSchemaForSchema(entry.schema, entry.jsonSchema),
+    }
+}
+
+process.stdout.write(JSON.stringify(manifest))

package/src/lib/browser/cache.ts

@@ -0,0 +1,191 @@
+import type { RawRemoteFunction } from '../server/rpc/types/RawRemoteFunction.ts'
+import type { RemoteFunction } from '../server/rpc/types/RemoteFunction.ts'
+import { activeCacheStore } from '../shared/activeCacheStore.ts'
+import { canonicalJson } from '../shared/canonicalJson.ts'
+import { decodeResponse } from '../shared/decodeResponse.ts'
+import { getRemoteMeta } from '../shared/getRemoteMeta.ts'
+import { keyForRemoteCall } from '../shared/keyForRemoteCall.ts'
+import type { CacheOptions } from '../shared/types/CacheOptions.ts'
+
+type AnyRemote<Args, Return> = RemoteFunction<Args, Return> | RawRemoteFunction<Args>
+
+/*
+Curries a remote-function call against the request-scoped cache store.
+`cache(fn, options?)` returns an invoker; calling that invoker with args
+checks the store for a prior entry (keyed by fn.method + fn.url + args) and
+returns a shared promise on hit, or invokes the underlying raw call once
+and stores the resulting Response promise on miss. Splitting configuration
+(the outer call) from invocation (the inner call) keeps options anchored
+in a fixed position so they can't collide with arg shapes. TTL = undefined
+→ forever; ttl = 0 → dedupe only; ttl > 0 → entry expires `ttl` ms after
+the promise resolves.
+
+The invoker's return type mirrors the function you passed:
+
+  cache(getPost)({ id })       // → Promise<Post>      (decoded body)
+  cache(getPost.raw)({ id })   // → Promise<Response>  (raw escape hatch)
+
+Both share one stored entry — the cache only ever holds the underlying
+Response promise; the decoded view is derived on the way out for callers
+of the non-raw variant.
+
+Reactivity is implicit: the invoker calls `store.subscribe(key)`, which
+registers the surrounding $derived / $effect scope. Invalidating the key
+then re-runs that scope, which calls cache() again and gets a fresh entry.
+Outside a tracking scope subscribe() is a no-op, so cache() works the same
+in server code and plain client code.
+*/
+export function cache<Args, Return>(
+    fn: RemoteFunction<Args, Return>,
+    options?: CacheOptions,
+): (args?: Args) => Promise<Return>
+export function cache<Args>(
+    fn: RawRemoteFunction<Args>,
+    options?: CacheOptions,
+): (args?: Args) => Promise<Response>
+export function cache<Args, Return>(
+    fn: AnyRemote<Args, Return>,
+    options?: CacheOptions,
+): (args?: Args) => Promise<Return | Response> {
+    /*
+    The "raw" variant lacks its own `.raw` sibling; only the decoded
+    callable carries one. Tell them apart by that presence and dispatch the
+    decode step accordingly.
+    */
+    const isRaw = !('raw' in fn)
+    const rawFn = isRaw ? (fn as RawRemoteFunction<Args>) : (fn as RemoteFunction<Args, Return>).raw
+    return (args) => {
+        const responsePromise = invokeWithCache(rawFn, args, options)
+        return isRaw ? responsePromise : (responsePromise.then(decodeResponse) as Promise<Return>)
+    }
+}
+
+function invokeWithCache<Args>(
+    rawFn: RawRemoteFunction<Args>,
+    args: Args | undefined,
+    options: CacheOptions | undefined,
+): Promise<Response> {
+    const store = activeCacheStore()
+    const key = resolveKey(rawFn, args, options?.key)
+    store.subscribe(key)
+    const existing = store.entries.get(key)
+    if (existing) {
+        return shareable(existing.promise)
+    }
+    const promise = rawFn(args as Args)
+    const request = getRemoteMeta(promise)
+    if (!request) {
+        throw new Error(
+            '[belte] cache() received a function whose call did not record metadata — was it produced by a verb helper?',
+        )
+    }
+    const ttl = options?.ttl
+    const entry = {
+        key,
+        promise,
+        request,
+        ttl,
+        expiresAt: undefined as number | undefined,
+    }
+    store.entries.set(key, entry)
+    function deleteIfCurrent() {
+        if (store.entries.get(key) === entry) {
+            store.entries.delete(key)
+        }
+    }
+    promise.then(() => {
+        /*
+            On the server the cache store is request-scoped and gets GC'd
+            with the response; skip ttl=0 eviction so the SSR snapshot can
+            still pick the entry up. In the browser ttl=0 stays "dedupe
+            in-flight only" — evict the moment the promise settles.
+            */
+        if (ttl === 0) {
+            if (typeof window !== 'undefined') {
+                deleteIfCurrent()
+            }
+            return
+        }
+        if (ttl !== undefined) {
+            entry.expiresAt = Date.now() + ttl
+            setTimeout(() => {
+                if ((entry.expiresAt ?? 0) <= Date.now()) {
+                    deleteIfCurrent()
+                }
+            }, ttl).unref?.()
+        }
+    }, deleteIfCurrent)
+    return shareable(promise)
+}
+
+/*
+Returns a promise that resolves to a fresh clone of the underlying Response.
+Multiple readers can each consume the body independently — the stored
+promise's Response is never consumed directly, so clones always succeed.
+*/
+function shareable(promise: Promise<Response>): Promise<Response> {
+    return promise.then((response) => response.clone())
+}
+
+cache.invalidate = function invalidate<Args, Return>(
+    arg?: AnyRemote<Args, Return> | CacheOptions['key'],
+): void {
+    const store = activeCacheStore()
+    if (arg === undefined) {
+        const keys = Array.from(store.entries.keys())
+        store.entries.clear()
+        emit(store, keys)
+        return
+    }
+    if (typeof arg === 'function') {
+        /*
+        `arg.url` is the route template; per-call args appear as `?...`
+        (GET/DELETE) or after a space (canonical-json body) — see
+        keyForRemoteCall. Passing either `fn` or `fn.raw` invalidates the
+        same set because they share method+url.
+        */
+        const prefix = `${arg.method} ${arg.url}`
+        const affected: string[] = []
+        for (const key of store.entries.keys()) {
+            if (key === prefix || key.startsWith(`${prefix}?`) || key.startsWith(`${prefix} `)) {
+                affected.push(key)
+            }
+        }
+        affected.forEach((key) => store.entries.delete(key))
+        emit(store, affected)
+        return
+    }
+    const target = canonicalKey(arg)
+    if (store.entries.delete(target)) {
+        emit(store, [target])
+    }
+}
+
+function resolveKey<Args>(
+    rawFn: RawRemoteFunction<Args>,
+    args: Args | undefined,
+    override: CacheOptions['key'],
+): string {
+    if (override !== undefined) {
+        return canonicalKey(override)
+    }
+    return keyForRemoteCall(rawFn.method, rawFn.url, args)
+}
+
+function canonicalKey(value: CacheOptions['key']): string {
+    if (typeof value === 'string') {
+        return value
+    }
+    return canonicalJson(value)
+}
+
+/*
+Detail is a Set so each subscriber's `has(key)` check is O(1) regardless of
+how many keys a single invalidate touches.
+*/
+function emit(store: ReturnType<typeof activeCacheStore>, keys: string[]): void {
+    if (keys.length === 0) {
+        return
+    }
+    store.events.dispatchEvent(new CustomEvent('invalidate', { detail: new Set(keys) }))
+}