@bakery-framework/core 2.0.0-alpha.9 → 2.0.0-rc.1

package/src/utils/http/etag.ts

@@ -17,7 +17,7 @@ export namespace ETag {
     return `W/"${hash.toString(36)}"`
   }
 
-  /** The one writer of the file-etag format — `fromFile` and the negotiation
+  /** The one writer of the file-etag format: `fromFile` and the negotiation
    * memo below must agree byte-for-byte, or a warm hit would break every
    * `If-None-Match` a cold response handed out. */
   function fileTag(size: number, mtime: number): string {
@@ -78,8 +78,8 @@ export namespace ETag {
 
   /**
    * Per-base-path record of which compressed siblings exist, anchored on the
-   * base file's mtime. `getOrCreateCachedFile` — the only writer of these
-   * files — writes the raw file and every variant together in one
+   * base file's mtime. `getOrCreateCachedFile` (the only writer of these
+   * files) writes the raw file and every variant together in one
    * `Promise.all`, so the base mtime changes whenever the variant set does;
    * that makes the mtime the invalidation signal, and no write-side hook is
    * needed (fs.ts stays unaware of this module, keeping the dependency arrow
@@ -92,7 +92,7 @@ export namespace ETag {
    *
    * Only *complete* variant sets are recorded. A partial set means either a
    * build caught mid-write (the trio lands over a few ms) or user-authored
-   * precompressed siblings next to a served `.gz` — in both cases the set can
+   * precompressed siblings next to a served `.gz`: in both cases the set can
    * change without the base mtime moving, so those fall back to per-request
    * probing, which is exactly the pre-memo behavior.
    */
@@ -102,8 +102,7 @@ export namespace ETag {
   /**
    * One stat, and the values are kept rather than discarded: a `BunFile`
    * caches its stat on first property access (~66us fresh, ~40ns after), so
-   * routing the probe through `fs.exists` — which stats a throwaway instance —
-   * made every served variant pay a second, identical stat in `fromFile`.
+   * routing the probe through `fs.exists` (which stats a throwaway instance)    * made every served variant pay a second, identical stat in `fromFile`.
    * Same existence predicate as `fs.exists`; note a missing file reports
    * size 0 and a far-future sentinel `lastModified`, never 0.
    */
@@ -119,7 +118,7 @@ export namespace ETag {
 
   /**
    * Test seam (convention 9): lets etag.test.ts count sibling probes without
-   * module-mocking `bun` or `node:fs` — which is process-global and never
+   * module-mocking `bun` or `node:fs`, which is process-global and never
    * unwinds. Same shape as `fs.__setForbiddenProbe`.
    */
   export function __setVariantProbe(fn: (path: string) => VariantStat | null) {
@@ -136,7 +135,7 @@ export namespace ETag {
     negotiationMemo.clear()
   }
 
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: content negotiation — one branch per encoding outcome
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: content negotiation, one branch per encoding outcome
   function negotiateFile(file: Bun.BunFile, req?: Request) {
     const fileName = file.name || 'file'
 
@@ -174,7 +173,7 @@ export namespace ETag {
       )
 
       // The memo is consulted only for a base that exists right now, and only
-      // when its recorded mtime matches the anchor exactly — a wiped cache
+      // when its recorded mtime matches the anchor exactly: a wiped cache
       // dir (missing base reports the far-future sentinel mtime) or any
       // rewrite falls through to a fresh probe.
       let entry = baseExists ? negotiationMemo.get(basePath) : undefined
@@ -231,13 +230,55 @@ export namespace ETag {
       if (conditionalRes) return conditionalRes
     }
 
+    // Range handling itself lives in Bun.serve, not here: any Response whose
+    // body is a *path-backed* BunFile is sliced by the runtime (206 with
+    // Content-Range on a satisfiable single range, 416 past EOF), including
+    // the negotiated compressed variants above (the range then addresses the
+    // encoded bytes, which is what RFC 9110 says a range means). What the
+    // runtime does not do is advertise: a plain 200 or a HEAD said nothing,
+    // so players that probe HEAD for `Accept-Ranges` before attempting seeks
+    // never tried. Advertised here because this is the one funnel every
+    // file-serving handler's BunFile passes through, and only here: an
+    // in-memory Blob or a `sendText` string body ignores Range entirely
+    // (served whole, 200), which is why `.name` gates the claim.
+    //
+    // Skipped when Bun's own range path is about to answer (a GET carrying a
+    // single-range `Range`): that path appends its own `Accept-Ranges: bytes`
+    // to the 206/416, and setting it here too emitted `bytes, bytes`.
+    //
+    // A **multipart** range (`bytes=0-1,10-11`) is carved back out of the
+    // skip: Bun does not do multipart (it serves the whole file as a 200 and
+    // appends nothing), so the skip left that response advertising nothing at
+    // all, which reads as "ranges not supported" to the one client that just
+    // demonstrated it wants them. Found by a downstream smoke test. The comma
+    // is the entire multipart grammar, so this cannot drift from Bun's own
+    // parse the way a real Range parser here could; RFC-legal multipart gets
+    // the 200-with-advertisement it deserves. What stays excluded-and-silent
+    // is a *malformed* single range (`Range: potato`), also served whole by
+    // Bun, but that requester sent garbage, and mirroring Bun's full validity
+    // judgment here is exactly the second-parser drift this comment refuses.
+    // HEAD ignores `Range` and gets the header even when one is present.
+    const rangeValue = req?.headers.get('range')
+    if (
+      resolvedFile.name &&
+      !(
+        req &&
+        req.method === 'GET' &&
+        rangeValue !== null &&
+        rangeValue !== undefined &&
+        !rangeValue.includes(',')
+      )
+    ) {
+      headers['Accept-Ranges'] = 'bytes'
+    }
+
     return new Response(resolvedFile, { headers })
   }
 
   /**
-   * Returns synchronously on every path that does not compress — no request,
+   * Returns synchronously on every path that does not compress: no request,
    * small body, unsupported Accept-Encoding, and crucially the 304
-   * short-circuit — and returns a Promise only when compression actually
+   * short-circuit, and returns a Promise only when compression actually
    * runs on a body large enough to offload (`ASYNC_COMPRESSION_MIN`). The
    * one call site that can receive either (`processResponse`) awaits.
    */
@@ -265,7 +306,7 @@ export namespace ETag {
       'Content-Type': type,
     }
 
-    // Negotiation only — no compression yet. The ext suffix the etag embeds
+    // Negotiation only: no compression yet. The ext suffix the etag embeds
     // is decided by the Accept-Encoding header alone, so the 304 check can
     // run first: a client that already holds the body must not cost a
     // zstd pass whose output is then thrown away.
@@ -302,7 +343,7 @@ export namespace ETag {
 
       // Off the request thread for large bodies: the sync pass measured
       // ~700us of event-loop stall per 135KB response. Below the cutoff the
-      // pool round-trip costs more than the stall it removes — numbers on
+      // pool round-trip costs more than the stall it removes: numbers on
       // `ASYNC_COMPRESSION_MIN` in fs.ts.
       if (encoderAsync && text.length >= ASYNC_COMPRESSION_MIN) {
         return encoderAsync(text).then(

package/src/utils/http/html.ts

@@ -4,7 +4,16 @@ import { Try } from '../common/try'
 import { DOMTools, headBodyCache } from './dom'
 import { ETag } from './etag'
 
-function injectBrand(res: Response) {
+/**
+ * Mark `res` as already carrying the head/body injects, so `injectIfHtml` ( * and therefore `processResponse`, which every response funnels through)  * hands it back untouched.
+ *
+ * Exported for the one caller that means "never", not "already":
+ * `DefaultErrorHandler` brands its production error page so the import map is
+ * not spliced into it. That map names every installed package (an inventory
+ * of the app's module layout), and the page carries no scripts for it (or the
+ * client bundle) to serve anyway.
+ */
+export function injectBrand(res: Response) {
   return Object.defineProperty(res, '__injected__', {
     value: true,
     enumerable: false,
@@ -19,7 +28,7 @@ function isInjected(res: Response) {
  * Rebuild `res` with `status`, carrying the injection brand across.
  *
  * `Response.status` is read-only, so changing it means constructing a new
- * Response — and a plain rebuild silently drops the `__injected__` marker,
+ * Response, and a plain rebuild silently drops the `__injected__` marker,
  * which is the only thing stopping `processResponse` running the page through
  * `injectIfHtml` a second time and emitting two import maps and two copies of
  * the client bundle. That is why this lives next to the brand rather than at
@@ -40,7 +49,7 @@ export function withStatus(res: Response, status: number): Response {
 /**
  * Server-controlled markup injected into the document. Deliberately a separate
  * argument from `params`: `params` is request-derived (for GET it is the query
- * string), so `$$head`-style keys arriving from a client must never be honoured.
+ * string), so `$$head`-style keys arriving from a client must never be honored.
  */
 export interface HtmlInjects {
   head?: string
@@ -73,7 +82,7 @@ export interface HtmlInjects {
  *                                       have sent
  *
  * Buffered responses carry a strong content ETag for the 304 machinery.
- * Streamed responses carry none — see `streamedResponse` for why that is not
+ * Streamed responses carry none. See `streamedResponse` for why that is not
  * faked.
  */
 export const STREAM_THRESHOLD_BYTES = 64 * 1024
@@ -85,7 +94,7 @@ export async function injectIfHtml(
 ): Promise<Response | null> {
   if (data instanceof Response && isInjected(data)) return data
 
-  // {{param}} substitution (and only that — the __PAGE_PARAMS__ script is a
+  // {{param}} substitution (and only that: the __PAGE_PARAMS__ script is a
   // head fragment either way) needs the whole document in one string, so a
   // params-bearing call takes the buffered path regardless of size.
   const hasParams = !!params && Object.keys(params).length > 0
@@ -123,7 +132,7 @@ export async function injectIfHtml(
   return bufferedResponse(content, params, injects, responseInit)
 }
 
-/** The one writer of the buffered injection Response — main path and the
+/** The one writer of the buffered injection Response: main path and the
  * streamed path's fallback both come through here. */
 function bufferedResponse(
   content: string,
@@ -178,7 +187,7 @@ function getConfigInjects() {
 /**
  * The final head/body fragments for one document: config injects + the
  * __PAGE_PARAMS__ script + per-call injects, with `<!--prio-->` resolved.
- * Computed once per response, up front — the streamed path must not defer this
+ * Computed once per response, up front: the streamed path must not defer this
  * into a pull callback, where the AsyncLocalStorage host context that
  * `getConfigInjects` and `DOMTools.importMap` read may no longer be live.
  */
@@ -227,7 +236,7 @@ function spliceBodyEnd(html: string, body: string): string {
  * each window and the final carry. */
 function rewriteFontsUrls(html: string): string {
   // Both alternatives in RX_GFONTS require the literal `fonts.goog`, so this
-  // substring check cannot skip a document the regex would have matched — and
+  // substring check cannot skip a document the regex would have matched, and
   // most documents have no Google Fonts link at all.
   if (!html.includes('fonts.goog')) return html
   return html.replace(RX_GFONTS, () => GFONTS_REWRITE)
@@ -261,8 +270,8 @@ export function assembleHtml(
 // The exact same three rewrites as `assembleHtml`, in the same order, without
 // holding the document in memory. The head splice happens on a bounded probe
 // (the tag is near the start of any real document) using the same
-// `spliceHead`; the body-end insert and the fonts rewrite — the two passes
-// that force a scan to the end of the document — run as chunk-boundary-safe
+// `spliceHead`; the body-end insert and the fonts rewrite (the two passes
+// that force a scan to the end of the document) run as chunk-boundary-safe
 // text stages over the same regexes. Content inserted by the body stage flows
 // through the fonts stage but not back through the body stage, which is
 // exactly the buffered path's head → body → fonts ordering.
@@ -272,7 +281,7 @@ export function assembleHtml(
  * that can be left dangling at a chunk boundary. */
 const BODY_END_HOLDBACK = '</body>'.length - 1
 
-/** Longest text RX_GFONTS can match, minus one — any incomplete match prefix
+/** Longest text RX_GFONTS can match, minus one: any incomplete match prefix
  * at a window edge is at most this long, so holding back this many characters
  * guarantees no match is ever split across two windows. */
 const FONTS_HOLDBACK = 'https://fonts.googleapis.com/css2'.length - 1
@@ -281,7 +290,7 @@ const FONTS_HOLDBACK = 'https://fonts.googleapis.com/css2'.length - 1
  * Read the response body until either EOF or enough bytes to commit to
  * streaming. Streaming needs two things the probe establishes: proof the body
  * is actually large (unless Content-Length already said so), and a `<head…>`
- * match — the no-head fallback prepends to the very start of the document,
+ * match, the no-head fallback prepends to the very start of the document,
  * which a stream that has begun emitting can no longer do. Anything that fails
  * those checks is drained and handed to the buffered path, whose output is the
  * long-standing behavior.
@@ -367,7 +376,7 @@ async function* tailText(
     }
   } finally {
     // Reached on normal EOF (no-op) and when the consumer cancels the response
-    // mid-stream — in which case the source must be cancelled too.
+    // mid-stream: in which case the source must be canceled too.
     await Try(() => reader.cancel())
   }
 }
@@ -382,9 +391,9 @@ async function* withPrefix(
 
 /**
  * Streaming equivalent of `spliceBodyEnd`: insert before the first literal
- * `</body>` (in original casing — the insert slices around the match rather
+ * `</body>` (in original casing, the insert slices around the match rather
  * than reconstructing it), else append at the very end. Once inserted the
- * stage is a passthrough, so content it inserted is never rescanned — matching
+ * stage is a passthrough, so content it inserted is never rescanned: matching
  * the buffered path's single non-global replace.
  */
 async function* bodyEndStage(
@@ -424,7 +433,7 @@ async function* bodyEndStage(
 /**
  * Streaming equivalent of `rewriteFontsUrls`. Complete matches that start in
  * the emittable region are rewritten (a complete match cannot be invalidated
- * or extended by later input — the pattern has no unbounded or trailing
+ * or extended by later input: the pattern has no unbounded or trailing
  * parts); matches or match prefixes inside the holdback stay in the carry for
  * the next window, and the final carry goes through the shared
  * `rewriteFontsUrls` itself.
@@ -452,7 +461,7 @@ async function* fontsStage(
 
     // The same fast gate the buffered path uses: no `fonts.goog` in the
     // window means no match in it, and the emit/carry split below does not
-    // depend on match presence — a match *prefix* dangling at the window edge
+    // depend on match presence, a match *prefix* dangling at the window edge
     // sits inside the holdback either way.
     if (window.includes('fonts.goog')) {
       rx.lastIndex = 0
@@ -477,8 +486,8 @@ async function* fontsStage(
 /**
  * Wrap the staged text into a streaming Response.
  *
- * Deliberately no ETag: a content hash would require buffering the body — the
- * thing this path exists to avoid — and deriving one from anything less (say,
+ * Deliberately no ETag: a content hash would require buffering the body (the
+ * thing this path exists to avoid), and deriving one from anything less (say,
  * source file size+mtime) would keep serving 304s after the config-injected
  * head/body fragments change. Large streamed pages are also where conditional
  * revalidation matters least. Callers relying on the 304 machinery get it on
@@ -494,7 +503,7 @@ function streamedResponse(
   // Buffered responses get `Cache-Control: no-cache` from ETag.sendResponse
   // (guarded the same way: only when the handler set nothing itself). With no
   // ETag that hook never fires here, and a validator-less page left without a
-  // cache policy is open to heuristic caching — a stale page, not just a
+  // cache policy is open to heuristic caching: a stale page, not just a
   // missed 304.
   if (!headers.has('Cache-Control')) {
     headers.set('Cache-Control', 'no-cache')

package/src/utils/http/ip.ts

@@ -15,7 +15,7 @@ const TRUSTED_HEADERS = [
 export function getClientIp(req: Request): string {
   // `Bakery.config`, not `getConfig()`: this runs inside the request's host
   // store, and the process config is the wrong answer under `hosts`. It was
-  // the only reader of the two that disagreed — `getHostname` and the
+  // the only reader of the two that disagreed: `getHostname` and the
   // session's `Secure` flag both read the host's `trustProxy`, so one host
   // could have its hostname and cookie resolved from its own config while
   // its client IP was resolved from the base one.

package/src/utils/http/sse.ts

@@ -3,25 +3,25 @@
  *
  * Bakery had WebSockets and nothing for one-way streaming, which is the cheaper
  * half of that pair and the right shape for progress, notifications and tailing
- * — no upgrade, no protocol, reconnects handled by the browser.
+ *: no upgrade, no protocol, reconnects handled by the browser.
  *
  * A route could always return a `Response` wrapping a `ReadableStream` and it
  * would reach the client intact: `ETag.sendResponse` returns early without an
  * `ETag` header, and `injectIfHtml` ignores anything that is not HTML. What was
- * missing is the framing, and framing is where this goes wrong — a payload
+ * missing is the framing, and framing is where this goes wrong: a payload
  * containing a newline silently truncates unless every line is prefixed, and a
  * write after the client has gone throws where nobody is catching.
  */
 
 /** One event. Every field is optional except the payload. */
 export interface SSEMessage {
-  /** Serialised with `JSON.stringify` unless it is already a string. */
+  /** Serialized with `JSON.stringify` unless it is already a string. */
   data: unknown
-  /** `event:` — the client listens for this name instead of `message`. */
+  /** `event:`: the client listens for this name instead of `message`. */
   event?: string
-  /** `id:` — echoed back as `Last-Event-ID` when the browser reconnects. */
+  /** `id:`: echoed back as `Last-Event-ID` when the browser reconnects. */
   id?: string
-  /** `retry:` — how long the browser waits before reconnecting, in ms. */
+  /** `retry:`: how long the browser waits before reconnecting, in ms. */
   retry?: number
 }
 
@@ -42,7 +42,7 @@ export interface SSEOptions {
    * Milliseconds between automatic keep-alive comments. `0` disables them.
    *
    * Defaults to 15s because idle proxies and load balancers commonly cut a
-   * connection at 30–60s, and a dead SSE stream is invisible: the browser
+   * connection at 30 to 60s, and a dead SSE stream is invisible: the browser
    * reconnects silently, so the symptom is duplicated work on the server rather
    * than an error anyone sees.
    */
@@ -55,7 +55,7 @@ export interface SSEOptions {
  * Encode one message as an SSE frame.
  *
  * **Every line of `data` is prefixed.** A payload containing a newline is
- * otherwise cut short at that newline — the rest is read as a new field, and
+ * otherwise cut short at that newline: the rest is read as a new field, and
  * the client sees a truncated message rather than an error. Pretty-printed JSON
  * and stack traces both hit this.
  */
@@ -72,7 +72,7 @@ export function encodeSSE(message: SSEMessage): string {
       : JSON.stringify(message.data)
 
   // `?? ''` rather than skipping: `JSON.stringify(undefined)` is undefined, and
-  // a frame with no `data:` line at all is a comment to the client — the event
+  // a frame with no `data:` line at all is a comment to the client. The event
   // would vanish rather than arrive empty.
   for (const line of (payload ?? '').split('\n')) lines.push(`data: ${line}`)
 
@@ -116,7 +116,7 @@ export function sse(
       controller.enqueue(encoder.encode(chunk))
     } catch {
       // The client went away between the `closed` check and the enqueue. That
-      // is a normal race on every disconnect, not an error worth surfacing —
+      // is a normal race on every disconnect, not an error worth surfacing,
       // and throwing here would reject inside a timer callback, where nothing
       // is catching.
       finish()
@@ -192,7 +192,7 @@ export function sse(
       'Cache-Control': 'no-cache, no-transform',
       Connection: 'keep-alive',
       // nginx buffers proxied responses by default, which holds every event
-      // until the buffer fills — the stream appears to work in development and
+      // until the buffer fills: the stream appears to work in development and
       // to hang in production. This is the documented opt-out.
       'X-Accel-Buffering': 'no',
     },

package/src/utils/http/url.ts

@@ -2,7 +2,7 @@
  * The request's parsed URL, parsed at most once.
  *
  * Why memoize at all: `new URL` measures ~1.7µs, and the router, the body
- * parser and the proxy handler all want the same parse of the same request —
+ * parser and the proxy handler all want the same parse of the same request,
  * so the parse was hoisted into the server's `fetch` in `packages/cli/src/worker.ts`
  * and shared.
  *
@@ -10,12 +10,12 @@
  * `(req as any).__parsedUrl`: two writers, six readers across three packages,
  * every reader spelled `(req as any).__parsedUrl || new URL(req.url)` so that
  * it silently re-parsed whenever the writer had not run first. That is a
- * writer/reader ordering hazard with no way to observe it going wrong — a
+ * writer/reader ordering hazard with no way to observe it going wrong: a
  * missed write costs microseconds, not correctness, so nothing ever fails.
  * One function collapses both roles: there is no ordering left to get wrong,
  * no `any` cast anywhere, and no writer to forget. The map also keeps the
- * framework from mutating a `Request` object it does not own — a caller's
- * `Request` goes in and comes back unchanged — and holds its keys weakly, so
+ * framework from mutating a `Request` object it does not own (a caller's
+ * `Request` goes in and comes back unchanged), and holds its keys weakly, so
  * an entry dies with the request rather than needing eviction (convention 6).
  *
  * There is deliberately no setter. Nothing outside this module needs to say

package/src/utils/http/validate.ts

@@ -1,8 +1,7 @@
 /**
  * Request-body validation for route modules.
  *
- * `defineRoute<{ title: string }>` declares a body shape and enforces nothing —
- * the scaffolder's own template says so twice: *"declares the contract — it
+ * `defineRoute<{ title: string }>` declares a body shape and enforces nothing ( * the scaffolder's own template says so twice: *"declares the contract) it
  * does not validate it. The body is still client input."* Every route was left
  * to hand-check or not, and most did not.
  *
@@ -10,7 +9,7 @@
  * core` has zero runtime dependencies and that is worth keeping, so validation
  * accepts two shapes it can consume without knowing who produced them:
  *
- *   - **Standard Schema** (`~standard`) — the shared interface zod, valibot and
+ *   - **Standard Schema** (`~standard`): the shared interface zod, valibot and
  *     arktype all implement. Bring your own library; Bakery never imports it.
  *   - **A plain function** that returns the parsed value or throws.
  *
@@ -59,7 +58,7 @@ function isStandardSchema<T>(v: Validator<T>): v is StandardSchemaLike<T> {
 /**
  * Render a Standard Schema path as dotted notation.
  *
- * Segments may be plain keys or `{ key }` objects — the spec allows both, and a
+ * Segments may be plain keys or `{ key }` objects: the spec allows both, and a
  * library that uses the object form would otherwise render as `[object Object]`
  * in the very message meant to tell someone which field is wrong.
  */

package/src/utils/isomorphic/escape.ts

@@ -4,7 +4,7 @@
  * These live in `isomorphic/` because both sides need them: the HTML pipeline
  * and the Vue plugin escape on the way out, and the client bundle escapes when
  * building DOM strings. Nothing here may reference `Bun.*`, node builtins, or
- * DOM globals — this module is compiled into the browser bundle as-is.
+ * DOM globals: this module is compiled into the browser bundle as-is.
  */
 
 const HTML_ESCAPES: Record<string, string> = {

package/src/utils/isomorphic/is.ts

@@ -4,7 +4,7 @@
  * Two implementations of this used to exist. This one keeps the *callable*
  * shape from the client copy (`is(x, 'string')` as well as `is.string(x)`,
  * which is what the global `ISFunction` type has always described) and the
- * *semantics* of the server copy — notably `is.object([]) === true`, which
+ * *semantics* of the server copy, notably `is.object([]) === true`, which
  * `misc.test.ts` asserts and which callers like `router.ts` rely on to
  * JSON-encode array response bodies.
  */
@@ -16,7 +16,7 @@ const checks = {
   bigint: (v: any): v is bigint => typeof v === 'bigint',
   symbol: (v: any): v is symbol => typeof v === 'symbol',
   function: (v: any): v is Function => typeof v === 'function',
-  /** Arrays count as objects here — see the note above before changing this. */
+  /** Arrays count as objects here. See the note above before changing this. */
   object: (v: any): v is Record<string, any> =>
     v !== null && typeof v === 'object',
   array: Array.isArray,

package/src/utils/isomorphic/misc.ts

@@ -20,7 +20,7 @@ export function any<T = any>(value: any): T {
  *
  * Isomorphic, and moving it here is what made it so: it lived in
  * `client/utils.ts` as a browser global only, so the same call in a server
- * block was a ReferenceError — reported from an app. `crypto` is a global in
+ * block was a ReferenceError, reported from an app. `crypto` is a global in
  * both runtimes; nothing here is browser-specific.
  */
 export function randomId(length = 8) {

package/src/utils/isomorphic/stringify.ts

@@ -2,9 +2,8 @@
  * Circular-safe JSON helpers.
  *
  * Three copies of this logic existed: the client `$fmt` formatter, the
- * livereload log serializer, and ad-hoc replacers on the server. They drifted —
- * the `$fmt` one shipped with a one-parameter replacer that made every object
- * render as `""` — so the kernel lives here once and callers layer their own
+ * livereload log serializer, and ad-hoc replacers on the server. They drifted ( * the `$fmt` one shipped with a one-parameter replacer that made every object
+ * render as `""`), so the kernel lives here once and callers layer their own
  * extras on top.
  */
 

package/src/utils/isomorphic/try.ts

@@ -1,7 +1,7 @@
 import type { MixedPromise, Wrapped } from '../../types'
 import { is } from './is'
 
-// These were declared again, here, byte-for-byte identical to `types.d.ts` —
+// These were declared again, here, byte-for-byte identical to `types.d.ts`:
 // the second copy convention 5 exists to prevent. `isomorphic.test.ts` catches
 // a duplicated *value* by reference identity, and a type has no runtime
 // identity to compare, so nothing saw it.

package/src/utils/shared-pool.ts

@@ -22,11 +22,29 @@ export class SharedMemoryPool {
   header!: Int32Array
   counters!: Int32Array
   rateLimits!: Int32Array
-  dataPool!: Uint8Array
 
-  constructor(sizeOrBuffer: number | SharedArrayBuffer = 1024 * 1024) {
+  /**
+   * **The default is the layout's own size, not a megabyte.**
+   *
+   * It was `1024 * 1024`, and the layout uses 9,280 bytes of it: a 64-byte
+   * header, 1 KB of counters and 8 KB of rate-limit slots. The remaining
+   * 1,039,296 bytes were a `dataPool` region that **nothing read** - grep it
+   * across every package and app, and the only reference outside this file was
+   * a test asserting it was a `Uint8Array`. So 99.1% of a `SharedArrayBuffer`
+   * allocated at import in every server process existed for one assertion.
+   *
+   * The region is gone rather than shrunk. A scratch area with no consumer is
+   * not a feature waiting to be used; it is a number nobody can size, because
+   * there is nothing to size it against. Something that needs shared scratch
+   * later adds it along with the code that reads it.
+   *
+   * A larger size is still accepted and still honored, because `bind()` reads
+   * the size out of the header rather than trusting `byteLength` - so a
+   * cluster master that allocates more and shares it still works.
+   */
+  constructor(sizeOrBuffer: number | SharedArrayBuffer = BUFFER_START_OFFSET) {
     if (typeof sizeOrBuffer === 'number') {
-      const size = Math.max(sizeOrBuffer, BUFFER_START_OFFSET + 1024)
+      const size = Math.max(sizeOrBuffer, BUFFER_START_OFFSET)
       this.buffer = new SharedArrayBuffer(size)
       this.header = new Int32Array(this.buffer, 0, HEADER_INT_COUNT)
       this.counters = new Int32Array(
@@ -39,17 +57,11 @@ export class SharedMemoryPool {
         HEADER_BYTES + COUNTERS_BYTES,
         RATE_LIMIT_SLOT_COUNT * 2,
       )
-      this.dataPool = new Uint8Array(
-        this.buffer,
-        BUFFER_START_OFFSET,
-        size - BUFFER_START_OFFSET,
-      )
-
       Atomics.store(this.header, 0, 0x42414b45)
       Atomics.store(this.header, 1, size)
       Atomics.store(this.header, 2, BUFFER_START_OFFSET)
     } else {
-      // Adopting a buffer someone else laid out is exactly what `bind` does —
+      // Adopting a buffer someone else laid out is exactly what `bind` does:
       // it read the header for the size rather than trusting `byteLength`, and
       // so did the copy that used to sit here, character for character.
       this.bind(sizeOrBuffer)
@@ -70,12 +82,7 @@ export class SharedMemoryPool {
       HEADER_BYTES + COUNTERS_BYTES,
       RATE_LIMIT_SLOT_COUNT * 2,
     )
-    const size = Atomics.load(this.header, 1) || this.buffer.byteLength
-    this.dataPool = new Uint8Array(
-      this.buffer,
-      BUFFER_START_OFFSET,
-      size - BUFFER_START_OFFSET,
-    )
+
   }
 
   incrementCounter(slot: number, delta = 1): number {

package/tsconfig.app.json

@@ -1,12 +1,12 @@
 {
   "$comment": [
-    "**Client-side code** — the plain `.ts` under your source root that ends up",
+    "**Client-side code**, the plain `.ts` under your source root that ends up",
     "in the browser bundle. Extend it:",
     "  { \"extends\": \"@bakery-framework/core/tsconfig.app.json\" }",
     "",
     "BREAKING, 2.0.0: this file used to be the single config every app",
     "extended, and it carried `bun-types` and the JSX settings. It is now the",
-    "*browser* half of a three-way split — server code extends",
+    "*browser* half of a three-way split: server code extends",
     "tsconfig.server.json, Vue SFCs extend tsconfig.vue.json.",
     "",
     "**`types` is deliberately empty.** That is the entire reason the split",
@@ -18,7 +18,7 @@
     "tsconfig.server.json; a `.tsx` file compiled under this config would pick up",
     "the automatic runtime and fail at request time while typechecking clean."
   ],
-  "_files_note": "client/globals.d.ts declares the globals the browser runtime binds onto globalThis (request, escapeHTML, is, Try, Case, match, …). It states each as `typeof import(...)` of the isomorphic module that implements it, so the declaration cannot drift from the value. Those modules are pure by convention — no Bun, no node builtins, no DOM — which is what makes them safe to pull into a project that has no bun-types.",
+  "_files_note": "client/globals.d.ts declares the globals the browser runtime binds onto globalThis (request, escapeHTML, is, Try, Case, match, …). It states each as `typeof import(...)` of the isomorphic module that implements it, so the declaration cannot drift from the value. Those modules are pure by convention (no Bun, no node builtins, no DOM), which is what makes them safe to pull into a project that has no bun-types.",
   "files": [
     "./src/client/globals.d.ts",
     "./src/shared.d.ts",

package/tsconfig.vue.json

@@ -4,18 +4,18 @@
     "  { \"extends\": \"@bakery-framework/core/tsconfig.vue.json\" }",
     "",
     "SFCs get `bun-types` like server code does, because @bakery-framework/",
-    "plugin-vue compiles and can render them on the server — a `<script>` block",
+    "plugin-vue compiles and can render them on the server, a `<script>` block",
     "is not browser-only the way a plain `.ts` under the source root is.",
     "",
     "**`tsc` cannot parse `.vue`.** This config is for `vue-tsc`, which wraps tsc",
     "and understands SFCs. Pointing plain `tsc` at a project whose `include`",
     "matches `**/*.vue` gets you either silence or a parse error, depending on",
-    "version — neither of which is a typecheck.",
+    "version, neither of which is a typecheck.",
     "",
     "`jsx: preserve` rather than Bakery's classic runtime: inside an SFC, JSX (if",
     "used at all) belongs to Vue's own transform, not to `createElement`."
   ],
-  "_files_note": "Server ambients, same as tsconfig.server.json — an SFC can reach Bakery, AppConfig and the JSX namespace.",
+  "_files_note": "Server ambients, same as tsconfig.server.json. An SFC can reach Bakery, AppConfig and the JSX namespace.",
   "files": ["./src/global.d.ts", "./src/shared.d.ts", "./src/types.d.ts"],
   "compilerOptions": {
     "lib": ["ESNext", "DOM", "DOM.Iterable"],