brustjs 0.1.24-alpha → 0.1.26-alpha

package/runtime/cookies.ts

@@ -0,0 +1,61 @@
+import { __scope } from './request-context.ts'
+
+export interface CookieOptions {
+  maxAge?: number
+  expires?: Date
+  path?: string
+  domain?: string
+  secure?: boolean
+  httpOnly?: boolean
+  sameSite?: 'Strict' | 'Lax' | 'None'
+}
+
+// RFC 6265 cookie-name is a token: no control chars, whitespace, or separators.
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+
+/** Serialize a single Set-Cookie value. The value is URL-encoded; attributes
+ * are appended in a stable order. Mirrors the standard cookie attribute names.
+ *
+ * Hardening: the name is validated as an RFC 6265 token, and the final line is
+ * asserted CRLF-free — so a stray `\r\n` in a name/path/domain (which are NOT
+ * URL-encoded, unlike the value) can't smuggle an extra response header. */
+export function serializeCookie(name: string, value: string, opts: CookieOptions = {}): string {
+  if (!COOKIE_NAME.test(name)) {
+    throw new Error(`invalid cookie name ${JSON.stringify(name)} (must be an RFC 6265 token)`)
+  }
+  let out = `${name}=${encodeURIComponent(value)}`
+  if (opts.maxAge !== undefined) out += `; Max-Age=${opts.maxAge}`
+  if (opts.expires !== undefined) out += `; Expires=${opts.expires.toUTCString()}`
+  if (opts.path !== undefined) out += `; Path=${opts.path}`
+  if (opts.domain !== undefined) out += `; Domain=${opts.domain}`
+  if (opts.secure) out += '; Secure'
+  if (opts.httpOnly) out += '; HttpOnly'
+  if (opts.sameSite !== undefined) out += `; SameSite=${opts.sameSite}`
+  if (/[\r\n]/.test(out)) {
+    throw new Error('cookie contains CR/LF — refusing to emit (header-injection guard)')
+  }
+  return out
+}
+
+/** Per-request cookie helper. `get` reads the incoming request cookies; `set`
+ * and `delete` stage a Set-Cookie onto the active request scope, flushed onto
+ * the response by routes.ts. Outside a request scope, `set`/`delete` are no-ops
+ * (dev-warn under BRUST_DEV). */
+export const cookies = {
+  get(name: string): string | undefined {
+    return __scope()?.reqCookies[name]
+  },
+  set(name: string, value: string, opts?: CookieOptions): void {
+    const s = __scope()
+    if (!s) {
+      if (process.env.BRUST_DEV === '1') {
+        console.warn(`[brust] cookies.set('${name}') outside a request scope — no-op`)
+      }
+      return
+    }
+    s.setCookies.push(serializeCookie(name, value, opts))
+  },
+  delete(name: string, opts?: Pick<CookieOptions, 'path' | 'domain'>): void {
+    cookies.set(name, '', { ...opts, maxAge: 0 })
+  },
+}

package/runtime/define-actions.ts

@@ -46,6 +46,10 @@ export interface EndpointOptions {
   middleware?: Middleware[]
   /** Build-time MCP tool description (read by the manifest extractor). */
   description?: string
+  /** Declared domain errors, keyed by code. Each value is a StandardSchema for
+   * the error's `data` payload. TYPE-ONLY: flows into the treaty client's typed
+   * error union; the runtime ignores it (handlers throw `ActionError`). */
+  errors?: Record<string, StandardSchemaV1>
 }
 export interface EndpointDef {
   method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'
@@ -72,8 +76,19 @@ type QueryOf<O> = O extends { query: infer S }
     ? InferOutput<S>
     : unknown
   : Record<string, string>
+/** Discriminated error union derived from `opts.errors`. Each declared code maps
+ * to `{ code; message; data }` where `data` is the schema's inferred output. */
+type ErrorOf<O> = O extends { errors: infer E }
+  ? {
+      [K in keyof E & string]: {
+        code: K
+        message: string
+        data: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : unknown
+      }
+    }[keyof E & string]
+  : never
 
-export type EndpointEntry = { input: unknown; output: unknown }
+export type EndpointEntry = { input: unknown; output: unknown; error: unknown }
 export type EndpointMap = Record<string, Partial<Record<EndpointDef['method'], EndpointEntry>>>
 
 export function isValidEndpointPath(p: string): boolean {
@@ -88,32 +103,44 @@ export interface ActionsBuilder<Acc extends EndpointMap = {}> {
     path: P,
     handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>,
     opts?: O,
-  ): ActionsBuilder<Acc & { [K in P]: { GET: { input: QueryOf<O>; output: Awaited<R> } } }>
+  ): ActionsBuilder<
+    Acc & { [K in P]: { GET: { input: QueryOf<O>; output: Awaited<R>; error: ErrorOf<O> } } }
+  >
   post<P extends string, O extends EndpointOptions, R>(
     path: P,
     handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>,
     opts?: O,
-  ): ActionsBuilder<Acc & { [K in P]: { POST: { input: BodyOf<O>; output: Awaited<R> } } }>
+  ): ActionsBuilder<
+    Acc & { [K in P]: { POST: { input: BodyOf<O>; output: Awaited<R>; error: ErrorOf<O> } } }
+  >
   put<P extends string, O extends EndpointOptions, R>(
     path: P,
     handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>,
     opts?: O,
-  ): ActionsBuilder<Acc & { [K in P]: { PUT: { input: BodyOf<O>; output: Awaited<R> } } }>
+  ): ActionsBuilder<
+    Acc & { [K in P]: { PUT: { input: BodyOf<O>; output: Awaited<R>; error: ErrorOf<O> } } }
+  >
   patch<P extends string, O extends EndpointOptions, R>(
     path: P,
     handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>,
     opts?: O,
-  ): ActionsBuilder<Acc & { [K in P]: { PATCH: { input: BodyOf<O>; output: Awaited<R> } } }>
+  ): ActionsBuilder<
+    Acc & { [K in P]: { PATCH: { input: BodyOf<O>; output: Awaited<R>; error: ErrorOf<O> } } }
+  >
   delete<P extends string, O extends EndpointOptions, R>(
     path: P,
     handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>,
     opts?: O,
-  ): ActionsBuilder<Acc & { [K in P]: { DELETE: { input: BodyOf<O>; output: Awaited<R> } } }>
+  ): ActionsBuilder<
+    Acc & { [K in P]: { DELETE: { input: BodyOf<O>; output: Awaited<R>; error: ErrorOf<O> } } }
+  >
   head<P extends string, O extends EndpointOptions, R>(
     path: P,
     handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>,
     opts?: O,
-  ): ActionsBuilder<Acc & { [K in P]: { HEAD: { input: QueryOf<O>; output: Awaited<R> } } }>
+  ): ActionsBuilder<
+    Acc & { [K in P]: { HEAD: { input: QueryOf<O>; output: Awaited<R>; error: ErrorOf<O> } } }
+  >
 }
 
 export function defineActions(): ActionsBuilder {

package/runtime/index.js

@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-android-arm64')
         const bindingPackageVersion = require('brustjs-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-android-arm-eabi')
         const bindingPackageVersion = require('brustjs-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-win32-x64-gnu')
         const bindingPackageVersion = require('brustjs-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-win32-x64-msvc')
         const bindingPackageVersion = require('brustjs-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-win32-ia32-msvc')
         const bindingPackageVersion = require('brustjs-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-win32-arm64-msvc')
         const bindingPackageVersion = require('brustjs-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('brustjs-darwin-universal')
       const bindingPackageVersion = require('brustjs-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-darwin-x64')
         const bindingPackageVersion = require('brustjs-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-darwin-arm64')
         const bindingPackageVersion = require('brustjs-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-freebsd-x64')
         const bindingPackageVersion = require('brustjs-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-freebsd-arm64')
         const bindingPackageVersion = require('brustjs-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-x64-musl')
           const bindingPackageVersion = require('brustjs-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-x64-gnu')
           const bindingPackageVersion = require('brustjs-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-arm64-musl')
           const bindingPackageVersion = require('brustjs-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-arm64-gnu')
           const bindingPackageVersion = require('brustjs-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-arm-musleabihf')
           const bindingPackageVersion = require('brustjs-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-arm-gnueabihf')
           const bindingPackageVersion = require('brustjs-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-loong64-musl')
           const bindingPackageVersion = require('brustjs-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-loong64-gnu')
           const bindingPackageVersion = require('brustjs-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-riscv64-musl')
           const bindingPackageVersion = require('brustjs-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-riscv64-gnu')
           const bindingPackageVersion = require('brustjs-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-linux-ppc64-gnu')
         const bindingPackageVersion = require('brustjs-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-linux-s390x-gnu')
         const bindingPackageVersion = require('brustjs-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-openharmony-arm64')
         const bindingPackageVersion = require('brustjs-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-openharmony-x64')
         const bindingPackageVersion = require('brustjs-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-openharmony-arm')
         const bindingPackageVersion = require('brustjs-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.1.24-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.24-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.26-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.26-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {

package/runtime/index.ts

@@ -781,8 +781,17 @@ export type { BrustPageProps, HeadEntry } from './islands/brust-page.tsx'
 export { defineStore, signal, computed, effect, batch } from './store/index.ts'
 export type { StoreHandle, Snapshot, Signal, Computed } from './store/index.ts'
 
+// S2 — request-scoped loader cache/dedupe helpers. `runInRequestCache` (the
+// scope opener) is owned by the runtime route handler and intentionally NOT
+// exported.
+export { dedupe, cachedFetch } from './loader-cache.ts'
+
 export { buildIslands } from './islands/build.ts'
 export type { IslandsBuildResult, BuildIslandsOptions } from './islands/build.ts'
 
 export { cache } from './cache.ts'
 export type { InvalidateArgs } from './cache.ts'
+
+export { getRequestContext } from './request-context.ts'
+export { cookies } from './cookies.ts'
+export type { CookieOptions } from './cookies.ts'

package/runtime/islands/bootstrap.ts

@@ -16,6 +16,8 @@
 import { createRoot, hydrateRoot, type Root } from 'react-dom/client'
 import { createElement } from 'react'
 import { applyStoreSnapshot } from '../store/client-hydrate.ts'
+import { __navStart, __navCommit, __navError, __navInit } from '../navigation/store.ts'
+import { installActiveNav } from '../navigation/active-nav.ts'
 
 // Track React roots created by hydrateOne so we can unmount them before
 // removing their DOM in swapMainContent. Without this, removing the DOM
@@ -205,11 +207,12 @@ export function isInternalLink(a: HTMLAnchorElement, event: MouseEvent): boolean
 
 let inFlight: AbortController | null = null
 
-async function navigate(url: URL, push: boolean): Promise<void> {
+export async function navigate(url: URL, push: boolean): Promise<void> {
   inFlight?.abort()
   const ac = new AbortController()
   inFlight = ac
   try {
+    __navStart(url.pathname, url.search)
     const resp = await fetch(`/_brust/page${url.pathname}${url.search}`, {
       signal: ac.signal,
       headers: { Accept: 'application/json' },
@@ -229,8 +232,10 @@ async function navigate(url: URL, push: boolean): Promise<void> {
     if (push) history.pushState({}, '', url.href)
     window.scrollTo(0, 0)
     hydrateMarkersIn(main as HTMLElement)
+    __navCommit(url.pathname, url.search)
   } catch (err) {
     if ((err as Error).name === 'AbortError') return
+    __navError(url.pathname, err)
     console.warn('[brust] SPA navigation failed, falling back to full reload:', err)
     location.href = url.href
   } finally {
@@ -260,10 +265,14 @@ function installInterceptor(): void {
 if (typeof document !== 'undefined') {
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', () => {
+      __navInit(location.pathname, location.search)
+      installActiveNav()
       hydrateMarkersIn(document.body)
       installInterceptor()
     })
   } else {
+    __navInit(location.pathname, location.search)
+    installActiveNav()
     hydrateMarkersIn(document.body)
     installInterceptor()
   }

package/runtime/islands/island.tsx

@@ -13,8 +13,11 @@ export interface IslandProps<P> {
    * component (no anonymous default export). */
   component: ComponentType<P>
   /** Props passed to the component on both server and client. Must be
-   * JSON-serializable (no functions, classes, DOM nodes, etc.). */
-  props: P
+   * JSON-serializable (no functions, classes, DOM nodes, etc.). Optional — a
+   * propless island (e.g. one that reads only global/client state) may omit it;
+   * it defaults to `{}`. On native routes, omitting `props` lowers to an empty
+   * props_path the renderer fills with `{}`. */
+  props?: P
   /** When to hydrate. Default 'load'. */
   hydrate?: HydrateTrigger
   /** Native routes only: render this island server-side (renderToString during
@@ -74,7 +77,8 @@ export function Island<P extends object>({
         'export or a minified/inlined function.',
     )
   }
-  const propsJson = JSON.stringify(props)
+  const resolvedProps = (props ?? {}) as P
+  const propsJson = JSON.stringify(resolvedProps)
   return createElement(
     'div',
     {
@@ -82,6 +86,6 @@ export function Island<P extends object>({
       'data-brust-props': propsJson,
       'data-brust-hydrate': hydrate,
     },
-    createElement(Component, props),
+    createElement(Component, resolvedProps),
   )
 }

package/runtime/islands/native-render.ts

@@ -149,7 +149,9 @@ export async function resolveIslandContext(
 ): Promise<Record<string, string>> {
   const out: Record<string, string> = {}
   for (const entry of manifest) {
-    const props = pathInto(data, entry.propsPath)
+    // Empty propsPath = a propless island → `{}`. (pathInto('') returns the whole
+    // context, which is NOT what an absent `props` attr means.)
+    const props = entry.propsPath === '' ? {} : pathInto(data, entry.propsPath)
     // `?? null` handles undefined props; the `?? 'null'` belt-and-braces covers
     // the case where JSON.stringify itself returns undefined (e.g. a function
     // value), so entityEncode never receives undefined. Hoisted ABOVE the ssr

package/runtime/loader-cache.ts

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+const cacheCtx = new AsyncLocalStorage<Map<string, Promise<unknown>>>()
+
+export function runInRequestCache<T>(fn: () => T): T {
+  return cacheCtx.run(new Map(), fn)
+}
+
+/** Request-scoped memoize: share the in-flight promise + cache result for the
+ * scope's lifetime. Outside a scope → passthrough. Reject → guarded delete
+ * (identity-checked) so a stale catch can't evict a newer entry.
+ *
+ * NOTE: the reject cleanup runs one microtask after rejection, so a caller that
+ * dedupes the SAME key within that gap receives the about-to-reject promise (and
+ * thus the rejection) — acceptable: the result is one shared failure, not a hang. */
+export function dedupe<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const map = cacheCtx.getStore()
+  if (!map) return fn()
+  const existing = map.get(key) as Promise<T> | undefined
+  if (existing) return existing
+  const p = fn()
+  map.set(key, p)
+  p.catch(() => {
+    if (map.get(key) === p) map.delete(key)
+  })
+  return p
+}
+
+/** Idempotent (GET/HEAD) fetch deduped per request; non-idempotent → bypass.
+ * Returns a fresh clone every call (the stored Response is never exposed).
+ *
+ * NOTE: the cache key is `method + url` ONLY — it does NOT include `init`
+ * headers/body. Two `cachedFetch(sameUrl, {headers:…})` calls with DIFFERENT
+ * headers in one request share the FIRST call's response. Intended for plain
+ * idempotent GETs (the common loader case); if a caller varies `init` per call
+ * on the same URL, use `fetch` directly. */
+export function cachedFetch(url: string, init?: RequestInit): Promise<Response> {
+  const method = (init?.method ?? 'GET').toUpperCase()
+  if (method !== 'GET' && method !== 'HEAD') return fetch(url, init)
+  // `dedupe` infers T = Response from the fetch thunk, so `r` is already Response.
+  return dedupe(`${method} ${url}`, () => fetch(url, init)).then((r) => r.clone())
+}