@abide/abide 0.47.0 → 0.49.0

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

@@ -1,4 +1,4 @@
-import { globalCacheStore } from '../../shared/globalCacheStore.ts'
+import { sharedCacheStore } from '../../shared/sharedCacheStore.ts'
 import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
 import type { InspectorCacheEntry } from './types/InspectorCacheEntry.ts'
 import type { InspectorCacheSnapshot } from './types/InspectorCacheSnapshot.ts'
@@ -48,14 +48,14 @@ function projectEntry(entry: CacheEntry, now: number): InspectorCacheEntry {
 }
 
 /*
-Snapshots the process-level cache store (the persistent one `cache(fn, { global:
-true })` writes to) for the inspector. Read at call time, so it reflects the
-store as it stands; request-scoped stores are deliberately excluded — they're
-ephemeral and already visible as per-request cache tallies.
+Snapshots the process-level cache store (the persistent one `cache(fn, { shared:
+true, ttl: Infinity })` writes to) for the inspector. Read at call time, so it
+reflects the store as it stands; request-scoped stores are deliberately
+excluded — they're ephemeral and already visible as per-request cache tallies.
 */
 export function buildCacheSnapshot(): InspectorCacheSnapshot {
     const now = Date.now()
-    const entries = Array.from(globalCacheStore().entries.values(), (entry) =>
+    const entries = Array.from(sharedCacheStore().entries.values(), (entry) =>
         projectEntry(entry, now),
     )
     return { entries }

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

@@ -1,5 +1,6 @@
 import { responseBodyKind } from '../../shared/responseBodyKind.ts'
 import { gzipResponse } from './gzipResponse.ts'
+import { STREAMED_HTML_HEADER } from './STREAMED_HTML_HEADER.ts'
 import type { RequestStore } from './types/RequestStore.ts'
 
 /*
@@ -24,7 +25,16 @@ export function finalizeResponse(
     exemptIdleTimeout: () => void,
 ): Response {
     const kind = responseBodyKind(response)
-    store.responseStreaming = kind === 'streaming'
+    /* Close-monitoring (defer the closing record + cache-stats snapshot until the body
+       actually drains) must also cover progressively-streamed SSR HTML — a live
+       ReadableStream marked by STREAMED_HTML_HEADER that classifies as 'compressible' (it
+       still gzips), NOT as 'streaming'. Read the marker before gzipResponse strips it.
+       Without this, a page with a slow `{#await}` logs ~1ms elapsed and near-empty cache
+       stats at header time instead of the true drain-time values. */
+    const streamedHtml = response.headers.has(STREAMED_HTML_HEADER)
+    store.responseStreaming = kind === 'streaming' || streamedHtml
+    /* Only true frame protocols (SSE/JSONL, socket tail) opt out of the idle-timeout cap;
+       streamed HTML pages deliberately rely on it (see STREAMED_HTML_HEADER). */
     if (kind === 'streaming') {
         exemptIdleTimeout()
     }

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

@@ -63,8 +63,16 @@ export async function snapshotEntryFromCache(
     }
     /* Read a CLONE, not the original: a reader that captured this same `entry.promise`
        before the replacement below still holds `response` and may `.clone()` it — reading
-       the original here would lock its body and throw "Body already used" for that reader. */
-    const body = await response.clone().text()
+       the original here would lock its body and throw "Body already used" for that reader.
+       The body stream can still error mid-read (reset/truncated upstream) after headers
+       resolved — degrade that to undefined (matching the fetch-rejection path) so one flaky
+       entry doesn't reject the whole snapshot batch and 500 / abort the page stream. */
+    let body: string
+    try {
+        body = await response.clone().text()
+    } catch {
+        return undefined
+    }
     entry.promise = Promise.resolve(
         new Response(body, {
             status: response.status,

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

@@ -1,5 +1,5 @@
 /*
-One global cache entry projected for the inspector — the serializable facts the
+One shared cache entry projected for the inspector — the serializable facts the
 Cache tab renders. The stored promise/Request/timer aren't included; what an
 operator wants is the entry's identity, lifecycle state, retention, and a peek
 at the held value.

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

@@ -1,10 +1,10 @@
 import type { InspectorCacheEntry } from './InspectorCacheEntry.ts'
 
 /*
-The inspector's view of the cache: the process-level (`global: true`) store's
-current entries. That's the persistent store — request-scoped caches live and
-die with their request, so they surface as per-request tallies in the feed and
-traces rather than here.
+The inspector's view of the cache: the process-level (`shared: true, ttl:
+Infinity`) store's current entries. That's the persistent store —
+request-scoped caches live and die with their request, so they surface as
+per-request tallies in the feed and traces rather than here.
 */
 export type InspectorCacheSnapshot = {
     entries: InspectorCacheEntry[]

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

@@ -17,7 +17,7 @@ export type InspectorContext = {
     app: { name: string; version: string }
     /* Eager-loads the registries, then projects the current RPC + socket catalog. */
     loadSurface: () => Promise<InspectorSurface>
-    /* Snapshots the persistent (global) cache store — current entries with their
+    /* Snapshots the persistent (shared) cache store — current entries with their
        lifecycle state, retention, tags, and a value preview. */
     cacheSnapshot: () => InspectorCacheSnapshot
     /* Snapshots the requests whose handler is executing right now — the live

package/src/lib/shared/buildArtifact.ts

@@ -0,0 +1,17 @@
+import type { BuildConfig, BuildOutput } from 'bun'
+import { exitOnBuildFailure } from './exitOnBuildFailure.ts'
+
+/*
+Runs one Bun.build and fails the process on any diagnostic, returning the
+successful output — the build-or-die pairing every one-shot build site shares
+(compile, buildCli's discovery + cli, bundleApp, buildDisconnected). Keeps the
+`Bun.build` + `exitOnBuildFailure` step atomic so a new build site can't ship
+without the failure check. The incremental client build (build.ts) does NOT use
+this: it must clean its staging dir and return `false` rather than exit, so it
+keeps its own epilogue.
+*/
+export async function buildArtifact(config: BuildConfig): Promise<BuildOutput> {
+    const result = await Bun.build(config)
+    exitOnBuildFailure(result)
+    return result
+}

package/src/lib/shared/buildRpcRequest.ts

@@ -68,8 +68,12 @@ function appendQuery(method: HttpMethod, url: string, args: unknown): string {
     if (args === undefined) {
         return url
     }
-    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
-        const got = Array.isArray(args) ? 'array' : typeof args
+    const isFormData = typeof FormData !== 'undefined' && args instanceof FormData
+    if (typeof args !== 'object' || args === null || Array.isArray(args) || isFormData) {
+        /* FormData has no own enumerable keys, so `queryStringFromArgs` would silently drop
+           every field; a query-carrying method (GET/DELETE/HEAD) can't take a body anyway.
+           Fail loudly like any other non-plain-object arg. */
+        const got = Array.isArray(args) ? 'array' : isFormData ? 'FormData' : typeof args
         throw new Error(`[abide] ${method} ${url} args must be a plain object — got ${got}`)
     }
     const suffix = queryStringFromArgs(args as Record<string, unknown>, false)

package/src/lib/shared/cache.ts

@@ -3,7 +3,6 @@ import { activeCacheStore } from './activeCacheStore.ts'
 import { cacheStores } from './cacheStores.ts'
 import { decodeResponse } from './decodeResponse.ts'
 import { getRemoteMeta } from './getRemoteMeta.ts'
-import { globalCacheStore } from './globalCacheStore.ts'
 import { HttpError } from './HttpError.ts'
 import { hydratingSlot } from './hydratingSlot.ts'
 import { invalidateEvent } from './invalidateEvent.ts'
@@ -16,6 +15,7 @@ import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
 import { SocketDisconnectedError } from './SocketDisconnectedError.ts'
 import { selectorMatcher } from './selectorMatcher.ts'
 import { selectorPrefix } from './selectorPrefix.ts'
+import { sharedCacheStore } from './sharedCacheStore.ts'
 import { openStreamProbe } from './subscribableProbes.ts'
 import { toTagSet } from './toTagSet.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
@@ -36,7 +36,7 @@ const cacheLog = abideLog.channel('abide:cache')
 
 /*
 Tallies one read and narrates it on the diagnostics channel. The sink is the
-request/tab store even when the data store is the process-level global one —
+request/tab store even when the data store is the process-level shared one —
 attribution follows the asker, so a request's closing record reflects every
 read it made. A settled retained entry (including the warm SSR sync path) is
 a hit; an unsettled entry is a coalesced join of an in-flight call; no entry
@@ -62,8 +62,10 @@ Reads a call through a cache store. `cache(fn, args?, options?)` checks the stor
 for a prior entry and returns a shared promise on hit, or invokes `fn` once and
 stores its promise on miss — a direct read-through call, not a curried invoker.
 Args lead (the common refinement); options trail in a fixed final 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.
+they can't collide with arg shapes. ttl = 0 → dedupe only; ttl > 0 → entry
+expires `ttl` ms after the promise resolves. Omitted ttl → forever for a
+producer and for a remote call on the client; a remote call on the server with
+neither ttl nor swr stated defaults to 0 (coalesce-only, see CacheOptions).
 
 Coalescing is always on: identical in-flight calls share one flight, so
 `cache(createPost, args, { ttl: 0 })` is the mutation idiom — double-submit
@@ -87,7 +89,7 @@ new reference every call and never does; a warning fires once per such call
 site), and the promise is stored and handed back as-is (no Response, no decode,
 no SSR snapshot).
 
-`options.global` puts the entry in the process-level store instead of the
+`options.shared` puts the entry in the process-level store instead of the
 request-scoped one, so a value computed in one request is reused by later
 requests — the memoise-an-external-endpoint case. Default (omitted) is
 request-scoped on the server, which keeps per-user data from leaking across
@@ -172,9 +174,9 @@ cache.read = smartRead
 
 /*
 The shared read-through core. `smart` marks the smart bare call, which enables
-unconditional SWR retention for replayable reads (see smartRead / entry.retain);
-the public cache() passes false, keeping its explicit drop-on-ttl /
-drop-on-invalidate old surface.
+unconditional SWR retention for a replayable read — but only on the client (see
+smartRead / entry.retain and the `retain` computation below); the public cache()
+passes false, keeping its explicit drop-on-ttl / drop-on-invalidate old surface.
 */
 function readThrough<Args, Return>(
     fn: AnyRemote<Args, Return> | Producer<Args, Return>,
@@ -200,30 +202,45 @@ function readThrough<Args, Return>(
     const method = isRemote ? (rawFn as RawRemoteFunction<Args>).method : undefined
     const replayable = method !== undefined && REPLAYABLE_METHODS.has(method.toUpperCase())
     validatePolicy(options, method, smart)
-    /* Unconditional SWR retention for a smart replayable read (unless opted out). */
-    const retain = smart && replayable && options?.swr !== false
+    /* SWR retention is a client concern (the tab store lives; revalidation is
+       visible). On the server there is no live UI to hold stale, so a smart read
+       never retains — it coalesces only. */
+    const retain = smart && replayable && options?.swr !== false && typeof window !== 'undefined'
     /*
-    A smart write is coalesce-only, not retained (design: same as cache(fn, body,
-    { ttl: 0 })) — a second identical submit must re-fire, never replay the first
-    result. Default a smart write's ttl to 0 when the caller left it open. Reads and
-    explicit cache() keep the caller's ttl (undefined = forever).
+    ttl defaults to 0 (coalesce-only) on the server for any remote read/write, and
+    on the client for a smart write — in both cases only when the caller stated
+    neither ttl nor swr. The server default makes retention opt-in (via an explicit
+    ttl, paired with `shared` to survive the request). An explicit swr opts out so
+    it does not trip validatePolicy's "swr + ttl:0" throw; server-side swr is a
+    client-only concept with no added server guarantee.
     */
-    const effectiveOptions =
-        smart && isRemote && !replayable && options?.ttl === undefined
-            ? { ...options, ttl: 0 }
-            : options
+    const serverTtlZero =
+        isRemote &&
+        typeof window === 'undefined' &&
+        options?.ttl === undefined &&
+        options?.swr === undefined
+    const smartWriteTtlZero = smart && isRemote && !replayable && options?.ttl === undefined
+    const effectiveOptions = serverTtlZero || smartWriteTtlZero ? { ...options, ttl: 0 } : options
     if (!isRemote) {
         warnAnonymousProducer(fn as Producer<Args, Return>)
     }
-    const store = effectiveOptions?.global ? globalCacheStore() : activeCacheStore()
+    const store = effectiveOptions?.shared ? sharedCacheStore() : activeCacheStore()
     if (!isRemote) {
         return invokeProducer(store, fn as Producer<Args, Return>, args, effectiveOptions)
     }
     const remote = rawFn as RawRemoteFunction<Args>
     const key = keyForRemoteCall(remote.method, remote.url, args)
+    if (
+        !effectiveOptions?.shared &&
+        effectiveOptions?.ttl !== undefined &&
+        effectiveOptions.ttl > 0 &&
+        store !== sharedCacheStore()
+    ) {
+        warnEphemeralTtl(key)
+    }
     store.subscribe(key)
     const existing = store.entries.get(key)
-    recordRead(effectiveOptions?.global ? activeCacheStore() : store, key, existing)
+    recordRead(effectiveOptions?.shared ? activeCacheStore() : store, key, existing)
     if (existing) {
         tagEntry(existing, effectiveOptions?.tags)
         attachPolicy(existing, effectiveOptions, () => remote(args as Args), retain)
@@ -390,6 +407,20 @@ function warnAnonymousProducer(producer: (args?: never) => unknown): void {
     )
 }
 
+/* Warn once per key when a ttl>0 read lands in an ephemeral (request-scoped)
+   store — the ttl expires with the request. `shared` (the process store) or a
+   client tab store are the retention homes; a request-scoped ttl is dead config. */
+const warnedEphemeralTtl = new Set<string>()
+function warnEphemeralTtl(key: string): void {
+    if (warnedEphemeralTtl.has(key)) {
+        return
+    }
+    warnedEphemeralTtl.add(key)
+    abideLog.warn(
+        `cache(): a request-scoped ttl expires with the request — add \`shared\` to cache "${key}" across requests, or drop the ttl.`,
+    )
+}
+
 /*
 Producer path: key on the producer's reference + args, share the
 in-flight/retained promise on hit, and store the value promise as-is on miss — no
@@ -404,7 +435,7 @@ function invokeProducer<Args, Return>(
     const key = producerKey(producer, args)
     store.subscribe(key)
     const existing = store.entries.get(key)
-    recordRead(options?.global ? activeCacheStore() : store, key, existing)
+    recordRead(options?.shared ? activeCacheStore() : store, key, existing)
     if (existing) {
         tagEntry(existing, options?.tags)
         attachPolicy(existing, options, () => producer(args), false)
@@ -502,11 +533,18 @@ function registerEntry(
     own method filter; writes never ship). The keep never applies on the
     client (the tab store outlives any unit — a kept write would block every
     future re-submit, so entries evict the moment they settle), to producer
-    entries (no request), or to the process-level `global` store (not
-    request-scoped — keeping it would leak forever).
+    entries (no request), or when the resolved store is the process-level
+    `shared` store — including a non-shared read made outside an inbound
+    request, where the resolver falls back to `sharedCacheStore()` (Decision
+    1): that store is never request-scoped, so keeping it would leak forever.
+    The `store !== sharedCacheStore()` check is what tells a genuinely
+    request-scoped store apart from that fallback.
     */
     const keepZeroTtlForRequest =
-        request !== undefined && !options?.global && typeof window === 'undefined'
+        request !== undefined &&
+        !options?.shared &&
+        typeof window === 'undefined' &&
+        store !== sharedCacheStore()
     function deleteIfCurrent() {
         evictIfCurrent(store, entry)
     }
@@ -890,10 +928,10 @@ function peek<Args, Return>(
     active.trackLifecycle(key)
     let entry = active.entries.get(key)
     if (entry === undefined) {
-        const global = globalCacheStore()
-        global.subscribe(key)
-        global.trackLifecycle(key)
-        entry = global.entries.get(key)
+        const shared = sharedCacheStore()
+        shared.subscribe(key)
+        shared.trackLifecycle(key)
+        entry = shared.entries.get(key)
     }
     if (entry === undefined || entry.settled !== true || entry.value === undefined) {
         return undefined

package/src/lib/shared/cacheStores.ts

@@ -1,10 +1,10 @@
 import { activeCacheStore } from './activeCacheStore.ts'
-import { globalCacheStore } from './globalCacheStore.ts'
+import { sharedCacheStore } from './sharedCacheStore.ts'
 import type { CacheStore } from './types/CacheStore.ts'
 
 /* Active + process-level stores, deduped (one tab store on the client). */
 export function cacheStores(): CacheStore[] {
     const active = activeCacheStore()
-    const global = globalCacheStore()
-    return active === global ? [active] : [active, global]
+    const shared = sharedCacheStore()
+    return active === shared ? [active] : [active, shared]
 }

package/src/lib/shared/canonicalJson.ts

@@ -8,7 +8,8 @@ POST/PUT/PATCH bodies; the output is a key, not a request body, so it is free to
 encode types JSON.stringify would silently flatten (Map/Set → {}), coerce
 (Date → its ISO string, via toJSON before any replacer sees it) or drop
 (undefined). Covers the value types commonly passed as rpc args: primitives,
-arrays, plain objects, Date, Map, Set, and bigint. Functions and symbols can't
+arrays, plain objects, Date, Map, Set, bigint, and FormData/File/Blob (the
+multipart upload path). Functions and symbols can't
 key anything meaningful but are tagged rather than dropped so a stray one can't
 silently collapse two distinct argument sets onto the same key.
 */
@@ -55,6 +56,28 @@ export function canonicalJson(value: unknown): string {
         const members = Array.from(value, canonicalJson).sort()
         return `Set{${members.join(',')}}`
     }
+    /* FormData is the documented multipart escape hatch for body rpcs. Its fields are
+       NOT own enumerable keys, so the generic object branch below would return `{}` for
+       every distinct upload — collapsing them onto one cache key and coalescing unrelated
+       uploads onto each other. Encode its entries (sorted, so field order doesn't change
+       the key) with File/Blob distinguished by identity attributes below. */
+    if (typeof FormData !== 'undefined' && value instanceof FormData) {
+        const entries: string[] = []
+        value.forEach((entryValue, entryKey) => {
+            entries.push(`${JSON.stringify(entryKey)}=>${canonicalJson(entryValue)}`)
+        })
+        entries.sort()
+        return `FormData{${entries.join(',')}}`
+    }
+    /* File extends Blob — check it first so a named upload keys on its name too. Contents
+       can't be read synchronously, so identity attributes are the best available key;
+       distinct files (name/size/type/mtime) get distinct keys, which is the fix. */
+    if (typeof File !== 'undefined' && value instanceof File) {
+        return `File(${JSON.stringify(value.name)},${value.size},${JSON.stringify(value.type)},${value.lastModified})`
+    }
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+        return `Blob(${value.size},${JSON.stringify(value.type)})`
+    }
     const record = value as Record<string, unknown>
     const entries = Object.keys(record)
         .sort()

package/src/lib/shared/createChannelLog.ts

@@ -24,8 +24,32 @@ function channelPatterns(): string | undefined {
     return undefined
 }
 
+/* One line for an AggregateError sub-error: its message, prefixed with the source
+   position when it carries one. A thrown `Bun.build` failure holds a `BuildMessage`
+   per diagnostic, each with a `position.file` — naming that file is the point, since
+   without it a codegen/parse failure reads as a detail-free "Bundle failed". */
+function formatAggregateEntry(entry: unknown): string {
+    if (typeof entry === 'object' && entry !== null && 'message' in entry) {
+        const message = String((entry as { message: unknown }).message)
+        const position = (entry as { position?: { file?: string; line?: number; column?: number } })
+            .position
+        if (position?.file) {
+            return `  ${position.file}:${position.line ?? 0}:${position.column ?? 0} — ${message}`
+        }
+        return `  ${message}`
+    }
+    return `  ${String(entry)}`
+}
+
 // Prefers a full stack trace when the value is an Error so logs include the call site.
+// An AggregateError (a thrown Bun.build failure among them) carries the real diagnostics
+// in `.errors` — its own message is only a summary ("Bundle failed") — so expand each one,
+// or every per-file position is dropped and the failure reads with zero detail.
 function errorParts(value: unknown): { msg: string; stack?: string } {
+    if (value instanceof AggregateError && value.errors.length > 0) {
+        const details = value.errors.map(formatAggregateEntry).join('\n')
+        return { msg: `${value.message}\n${details}` }
+    }
     if (value instanceof Error) {
         return { msg: value.message, stack: value.stack }
     }

package/src/lib/shared/exitOnBuildFailure.ts

@@ -2,9 +2,10 @@ import type { BuildOutput } from 'bun'
 import { abideLog } from './abideLog.ts'
 
 /*
-On a failed Bun.build(), logs each diagnostic and exits non-zero. Every abide
-build entrypoint (build / compile / buildCli / bundleApp) funnels its result
-through here so failure reporting can't drift between them.
+On a failed Bun.build(), logs each diagnostic and exits non-zero. The one-shot
+build entrypoints reach it through `buildArtifact` (build-or-die); the
+incremental client build (build.ts) calls it directly on its conditional-exit
+path. One reporter so build failure can't drift between them.
 */
 export function exitOnBuildFailure(result: BuildOutput): void {
     if (result.success) {

package/src/lib/shared/parseEnv.ts

@@ -9,7 +9,9 @@ counterpart to loadEnvFile (which merges into process.env) and serializeEnv
 */
 export function parseEnv(text: string): Record<string, string> {
     const result: Record<string, string> = {}
-    for (const line of text.split('\n')) {
+    // Split on CRLF or LF — a Windows-saved (or git autocrlf) .env otherwise leaves a
+    // trailing \r that breaks ENV_LINE's `$` anchor, silently dropping every line.
+    for (const line of text.split(/\r?\n/)) {
         if (!line || line.startsWith('#')) {
             continue
         }
@@ -19,11 +21,20 @@ export function parseEnv(text: string): Record<string, string> {
         }
         const [, key, rawValue] = match
         const trimmed = rawValue?.trim() ?? ''
-        const unquoted =
-            (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-            (trimmed.startsWith("'") && trimmed.endsWith("'"))
-                ? trimmed.slice(1, -1)
-                : trimmed
+        let unquoted: string
+        if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+            // Double-quoted: unescape the sequences serializeEnv writes (`\\`, `\"`, `\n`, `\r`).
+            unquoted = trimmed
+                .slice(1, -1)
+                .replace(/\\([nr"\\])/g, (_, c: string) =>
+                    c === 'n' ? '\n' : c === 'r' ? '\r' : c,
+                )
+        } else if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'")) {
+            // Single-quoted: taken verbatim (no escaping applied on the way out).
+            unquoted = trimmed.slice(1, -1)
+        } else {
+            unquoted = trimmed
+        }
         result[key as string] = unquoted
     }
     return result

package/src/lib/shared/refresh.ts

@@ -4,9 +4,9 @@ import type { CacheSelector } from './types/CacheSelector.ts'
 /*
 Refetch every cached read matching the selector, keeping the stale value visible
 until the fresh one swaps in (refreshing() true meanwhile) — the smart-call
-refetch. Because the smart read retains its value (SWR unconditional), a refresh
-always refetches-and-swaps; it never drops to a pending blank. Follows the shared
-selector grammar:
+refetch. Because the smart read retains its value on the client (SWR
+unconditional there), a refresh always refetches-and-swaps; it never drops to a
+pending blank. Follows the shared selector grammar:
 
   refresh(getFoo, args)   → that exact call
   refresh(getFoo)         → every args-variant of that rpc

package/src/lib/shared/serializeEnv.ts

@@ -1,18 +1,30 @@
-// Quote only values that wouldn't round-trip bare through parseEnv — empties and
-// anything carrying whitespace or a `#` (which would otherwise read as a comment).
+// Quote any value that wouldn't round-trip bare through parseEnv: empties, anything
+// carrying whitespace/`#` (a comment)/a quote/a backslash, or one that starts or ends with
+// a quote char (parseEnv strips a surrounding quote pair). Everything else stays bare.
 function needsQuoting(value: string): boolean {
-    return value === '' || /[\s#]/.test(value)
+    return value === '' || /[\s#"\\]/.test(value) || /^['"]|['"]$/.test(value)
+}
+
+// Escape a value for inside double quotes: backslash and quote so the closing quote can't
+// be faked, and newlines so an embedded `\n` can't inject a whole new `KEY=value` line
+// (the security fix — an unescaped token newline used to forge extra env entries).
+function escapeQuoted(value: string): string {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
 }
 
 /*
 Serializes a key→value record to `.env` text — the inverse of parseEnv, used by
 the connect-screen config form to persist the user's answers to the data-dir
-`.env`. One `KEY=value` per line; values that need it are wrapped in double
-quotes so parseEnv reads them back unchanged.
+`.env`. One `KEY=value` per line; values that need it are double-quoted and escaped
+so parseEnv reads them back unchanged and a value can never inject extra lines.
 */
 export function serializeEnv(values: Record<string, string>): string {
     const lines = Object.entries(values).map(([key, value]) =>
-        needsQuoting(value) ? `${key}="${value}"` : `${key}=${value}`,
+        needsQuoting(value) ? `${key}="${escapeQuoted(value)}"` : `${key}=${value}`,
     )
     return `${lines.join('\n')}\n`
 }

package/src/lib/shared/sharedCacheStore.ts

@@ -0,0 +1,14 @@
+import { activeCacheStore } from './activeCacheStore.ts'
+import { sharedCacheStoreSlot } from './sharedCacheStoreSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Resolves the process-level ("shared") CacheStore that `cache(fn, { shared: true })`
+entries live in. The server entry registers a module-singleton resolver so the
+store survives across requests; the client points it at the active tab store.
+When no resolver is registered it falls back to the active store, so `shared`
+degrades to request/tab-scoped rather than throwing.
+*/
+export function sharedCacheStore(): CacheStore {
+    return sharedCacheStoreSlot.resolver?.() ?? activeCacheStore()
+}

package/src/lib/shared/sharedCacheStoreSlot.ts

@@ -0,0 +1,10 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+The process-level ("shared") CacheStore slot that `cache(fn, { shared: true })`
+entries live in. The server entry registers a module-singleton store outliving
+every request; the client points it at the active tab store. When no resolver
+is registered, sharedCacheStore() falls back to the active store.
+*/
+export const sharedCacheStoreSlot = createResolverSlot<CacheStore>()

package/src/lib/shared/snippet.ts

@@ -1,18 +1,23 @@
 const SNIPPET = Symbol.for('abide.snippet')
 
-/* A `{#snippet name(args)}` snippet, called like a function: it carries a payload a
-   `{expr}` interpolation mounts in place — a DOM builder `(host) => void` on the
+/* The internal payload a snippet carries — a DOM builder `(host) => void` on the
    client, the pre-rendered HTML string on the server. The brand is a registered
    Symbol so it survives across module/bundle copies (same idiom as `html\`\``). */
-export type Snippet<Payload> = { readonly [SNIPPET]: Payload }
+export type SnippetValue = { readonly [SNIPPET]: unknown }
+
+/* The author-facing snippet type: a builder invoked with its arguments, yielding a
+   mountable value. `children` is `Snippet` (no args, invoked `children()`); a row
+   renderer is `Snippet<[Item]>` (invoked `row(item)`). The side-specific payload is
+   hidden behind `SnippetValue`. */
+export type Snippet<Args extends unknown[] = []> = (...args: Args) => SnippetValue
 
 /* Brands a snippet payload so a `{expr}` interpolation mounts it instead of
    inserting escaped text. The compiler wraps a snippet's body in this — the client
    builder closes over the defining component's scope, the server string is its SSR
    render — so a snippet value passes through props like any other value. */
 // @documentation templating
-export function snippet<Payload>(payload: Payload): Snippet<Payload> {
-    return { [SNIPPET]: payload }
+export function snippet<Payload>(payload: Payload): SnippetValue {
+    return { [SNIPPET]: payload } as SnippetValue
 }
 
 /* The payload of a snippet-branded value, or undefined for anything else — so a
@@ -20,6 +25,6 @@ export function snippet<Payload>(payload: Payload): Snippet<Payload> {
    reads a builder function; the server reads the rendered string. */
 export function snippetPayload(value: unknown): unknown {
     return value !== null && typeof value === 'object' && SNIPPET in value
-        ? (value as Snippet<unknown>)[SNIPPET]
+        ? (value as SnippetValue)[SNIPPET]
         : undefined
 }

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

@@ -2,21 +2,25 @@
 Options for cache(). The key is always auto-derived (method+url+args for a remote
 function, producer-reference+args for a plain producer): hoist a producer to a
 stable reference to share its entry across calls. `ttl` is the
-milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
-dedupe only (entry dropped once the promise settles — the mutation idiom:
-in-flight coalescing and pending() visibility, nothing retained), any other
-number = TTL.
+milliseconds-past-resolve that the entry stays live: 0 = dedupe only (entry
+dropped once the promise settles — the mutation idiom: in-flight coalescing and
+pending() visibility, nothing retained), any other number = TTL. Omitted = forever
+for a producer and for a remote call on the client; a remote call on the SERVER
+with neither `ttl` nor `swr` stated defaults to 0 (coalesce-only — the request is
+the atomic unit, nothing is retained past it; pair with `shared` + an explicit
+`ttl` to memoise across requests).
 `tags` is an array of free-form labels grouping unrelated calls so one
 `cache.invalidate({ tags })` drops every entry sharing any of them — list
 multiple when a call belongs to multiple invalidation groups. A unique tag (e.g.
 a uuid) shared by a set of calls gives them their own private invalidation group.
 
-`global` opts the entry into the process-level store instead of the default
-request-scoped one (server) — so a value computed in one request is reused by
-later requests, e.g. memoising an external endpoint the server calls. Omit it
-for per-request data: the default keeps a per-user response from leaking across
-requests. Write only `global: true`; there is no `false` form. On the client
-there is a single tab store, so the flag is a no-op there.
+`shared` opts the entry into the process-level store instead of the default
+request-scoped one (server) — a store that outlives every request. It selects
+the store only; it does NOT retain (pair it with `ttl` to memoise across
+requests). The shared store is keyed by method+url+args, never by user, so do
+not put per-user data in it — it would be served to other users. Omit `shared`
+for per-request data. Write only `shared: true`; there is no `false` form. On
+the client there is a single tab store, so the flag is a no-op there.
 
 `swr` is stale-while-revalidate: it changes what a `cache.invalidate` hit does
 to this key. Without it, an invalidate drops the entry and the next read shows
@@ -44,7 +48,7 @@ with the same wrap-time guard as the `swr` window: set one, not both.
 export type CacheOptions = {
     ttl?: number
     tags?: string[]
-    global?: boolean
+    shared?: boolean
     swr?: boolean | { throttle?: number; debounce?: number }
     throttle?: number
     debounce?: number