brustjs 0.1.23-alpha → 0.1.24-alpha

package/runtime/routes.ts

@@ -18,6 +18,7 @@ import {
   resolveComponentContext,
 } from './islands/native-render.ts'
 import type { IslandCache } from './islands/native-render.ts'
+import { isActionError, type ActionError, type ActionErrorBody } from './action-error.ts'
 import type { EndpointDef } from './define-actions.ts'
 import { isRespondSentinel, makeRespond } from './define-actions.ts'
 import { validate } from './standard-schema.ts'
@@ -180,6 +181,54 @@ export function isNativeVerdict(x: unknown): x is NativeVerdict {
   )
 }
 
+/** Loader context passed to native chain loaders. */
+export interface NativeLoaderCtx {
+  params: Record<string, string>
+  path: string
+  req: BrustRequest
+}
+
+/** Result of running a native route's chain loaders top-down: either a merged
+ * flat context object (all loader results shallow-merged, child keys win), or
+ * the first verdict encountered (top-down) which short-circuits the chain. */
+export type NativeChainResult = { data: Record<string, unknown> } | { verdict: NativeVerdict }
+
+/** Run a native route's `flat.chain` loaders top-down (parent → leaf) and merge
+ * their results into ONE flat context object.
+ *
+ * Semantics (T3 — native <Outlet> loader chain):
+ *  - Each chain node may lack a loader → skip it.
+ *  - Results merge shallow: `merged = { ...merged, ...result }` — later (child)
+ *    keys win over earlier (parent) keys.
+ *  - First verdict wins: if any loader returns a `notFound()`/`redirect()`
+ *    verdict (top-down), STOP — remaining loaders are NOT run — and return it.
+ *  - `chain.length === 1` (or only the leaf has a loader) → behaves exactly as
+ *    the old leaf-only read (no regression).
+ *
+ * The caller is responsible for wrapping this in a SINGLE `runInStoreContext`
+ * (one Map per request) so parent loader store writes are visible to child
+ * loaders — mirroring the React path. This helper itself does NOT open a store
+ * scope. */
+export async function runNativeChainLoaders(
+  chain: Route[],
+  ctx: NativeLoaderCtx,
+): Promise<NativeChainResult> {
+  let merged: Record<string, unknown> = {}
+  for (const node of chain) {
+    if (!node.loader) continue
+    // `as never` bypasses per-route Params narrowing — NativeLoaderCtx is the
+    // default-instantiated loader ctx shape ({ params, path, req }).
+    const result = await node.loader(ctx as never)
+    if (isNativeVerdict(result)) {
+      return { verdict: result }
+    }
+    if (result && typeof result === 'object') {
+      merged = { ...merged, ...(result as Record<string, unknown>) }
+    }
+  }
+  return { data: merged }
+}
+
 /** Middleware contract — Express/Koa-style chain. Receives a structured
  * request and a `next()` that runs the rest of the chain (eventually the
  * loader + render). Return a `RouteResponse` to short-circuit, or call
@@ -332,8 +381,12 @@ function validateRoute(r: Route, basePath: string): void {
     if (r.websocket !== undefined) {
       throw new Error(`Route ${where}: 'native: true' cannot coexist with 'websocket'`)
     }
+    // T2 — `native: true` MAY have children, but only if the ENTIRE subtree is
+    // also native. The build synthesizes a per-leaf wrapper that composes the
+    // whole route chain into one native template; a non-native node anywhere in
+    // that chain can't be inlined (it would render via React, breaking native).
     if (r.children !== undefined) {
-      throw new Error(`Route ${where}: 'native: true' cannot have nested children`)
+      assertNativeSubtree(r.children, where)
     }
     if (r.cache !== undefined) {
       throw new Error(`Route ${where}: 'native: true' cannot coexist with 'cache' (deferred)`)
@@ -369,6 +422,24 @@ function validateRoute(r: Route, basePath: string): void {
   }
 }
 
+/** T2 — recursively assert every node in a native subtree is also `native: true`.
+ * A native chain is composed into one native template at build time, so a
+ * non-native node anywhere in the subtree would have to render via React,
+ * breaking the native fast path. */
+function assertNativeSubtree(children: Route[], where: string): void {
+  for (const child of children) {
+    if (child.native !== true) {
+      // Name the offending CHILD, not the native parent — `where` is the parent.
+      throw new Error(
+        `native route cannot mix native and non-native components in one chain (offending child: ${child.path ?? child.Component?.name ?? '(no path)'}, under: ${where})`,
+      )
+    }
+    if (child.children !== undefined) {
+      assertNativeSubtree(child.children, child.path ?? where)
+    }
+  }
+}
+
 /** Walk the nested route tree, emitting one FlatRoute per leaf or index node.
  * Composes paths, middleware, errorBoundary, and cache per the rules in
  * the design spec (S3). */
@@ -416,6 +487,17 @@ function makeFlat(chain: Route[], fullPath: string): FlatRoute {
   }
   const leaf = chain[chain.length - 1]
   const cache = leaf.cache
+  // T2 — a native leaf demands an all-native chain (the build composes the
+  // whole chain into one native template). Reject a native leaf reached through
+  // a non-native ancestor. NOTE: this is the PRIMARY (not redundant) guard for the
+  // non-native-parent → native-child direction — `assertNativeSubtree` only runs
+  // from a native PARENT (validateRoute's `if (r.native)` block), so a non-native
+  // parent never triggers it; this check is what catches that case.
+  if (leaf.native === true && chain.some((node) => node.native !== true)) {
+    throw new Error(
+      `native route cannot mix native and non-native components in one chain (route: ${leaf.path ?? fullPath})`,
+    )
+  }
   const nativeTemplate = leaf.native === true && leaf.Component ? leaf.Component.name : undefined
   return { fullPath, chain, middleware, errorBoundary, cache, nativeTemplate }
 }
@@ -632,43 +714,48 @@ export function makeRenderer(
       // deferred to v2.x. If your middleware needs to mutate, use a React
       // route for now.
       if (flat.nativeTemplate !== undefined) {
-        let data: unknown = {}
-        const leaf = flat.chain[flat.chain.length - 1]
-        if (leaf.loader) {
-          const ctx = { params: call.params, path: call.path, req: call.req }
-          try {
-            // Native loaders may write to a defineStore; run them in a per-request
-            // store scope so those writes are isolated per request. No snapshot is
-            // collected and no <script> is injected on native paths — Spec B owns
-            // native store delivery (hard non-goal here).
-            data = await runInStoreContext(() => leaf.loader!(ctx as any))
-          } catch (err) {
-            console.error(`[brust] loader failed for native route ${flat.fullPath}:`, err)
-            // FAST LANE: native routes take dispatch_single_chunk (no chunk
-            // channel), so every native fallback MUST pack + return a length.
-            return packSingleChunkResponse(view, encoder, {
-              status: 500,
-              contentType: 'text/html; charset=utf-8',
-              body: 'internal error',
-            })
-          }
+        let data: Record<string, unknown>
+        const ctx = { params: call.params, path: call.path, req: call.req }
+        let chainResult: NativeChainResult
+        try {
+          // Run the WHOLE route chain's loaders top-down (parent → leaf) and
+          // merge into ONE flat context (child keys win), mirroring the React
+          // chain-loader path. Wrap the entire loop in a SINGLE per-request
+          // store scope so a parent loader's defineStore writes are visible to
+          // child loaders (one Map per request — NOT one per loader). No
+          // snapshot is collected and no <script> is injected on native paths —
+          // Spec B owns native store delivery (hard non-goal here).
+          chainResult = await runInStoreContext(() => runNativeChainLoaders(flat.chain, ctx))
+        } catch (err) {
+          console.error(`[brust] loader failed for native route ${flat.fullPath}:`, err)
+          // FAST LANE: native routes take dispatch_single_chunk (no chunk
+          // channel), so every native fallback MUST pack + return a length.
+          return packSingleChunkResponse(view, encoder, {
+            status: 500,
+            contentType: 'text/html; charset=utf-8',
+            body: 'internal error',
+          })
         }
         let renderStatus: number | undefined
-        if (isNativeVerdict(data)) {
-          if (!data.render) {
+        if ('verdict' in chainResult) {
+          // First verdict wins (top-down). Remaining loaders already skipped.
+          const verdict = chainResult.verdict
+          if (!verdict.render) {
             // redirect — no template render; fast-lane packed response with Location.
             return packSingleChunkResponse(view, encoder, {
-              status: data.status,
+              status: verdict.status,
               contentType: 'text/html; charset=utf-8',
               body: '',
-              headers: data.headers,
+              headers: verdict.headers,
             })
           }
           // notFound — render the route's own template, but with the verdict's status.
-          renderStatus = data.status
-          data = data.data ?? {}
+          renderStatus = verdict.status
+          data = (verdict.data ?? {}) as Record<string, unknown>
+        } else {
+          data = chainResult.data
         }
-        const json = JSON.stringify(data ?? {})
+        const json = JSON.stringify(data)
         // Sub-project J — islands + components. If this template has an enriched
         // islands manifest or a components manifest, merge per-island context vars
         // (island_<id>_props, plus island_<id>_html for ssr entries) and per-component
@@ -1013,7 +1100,8 @@ async function navigationBranch(
 
 /** Render a native (jinja) route to its full HTML document for a SPA navigation.
  *
- * Mirrors the render-branch native path: run the leaf loader, merge island /
+ * Mirrors the render-branch native path: run the whole route chain's loaders
+ * (top-down, merged), merge island /
  * component manifest context, then call the SYNC `napiRenderJinja`, which writes
  * a framed `[meta_len u16 BE][meta JSON][body]` response into the SAB and returns
  * its length. Here — unlike the render branch, which returns that length so Rust
@@ -1030,24 +1118,25 @@ async function renderNativeRouteToHtml(
   workerId: bigint,
 ): Promise<string> {
   const templateName = flat.nativeTemplate as string
-  const leaf = flat.chain[flat.chain.length - 1]
-
-  let data: unknown = {}
-  if (leaf.loader) {
-    // Per-request store scope for native loader writes (isolation only). No
-    // snapshot collected / no <script> injected — Spec B owns native delivery.
-    data = await runInStoreContext(() =>
-      leaf.loader!({ params: call.params, path: call.path, req: call.req } as any),
-    )
-  }
 
-  if (isNativeVerdict(data)) {
+  // Run the WHOLE route chain's loaders top-down and merge into ONE flat context
+  // (child keys win), mirroring the full-render branch. One per-request store
+  // scope wraps the entire loop (isolation only — no snapshot / no <script>).
+  const chainResult = await runInStoreContext(() =>
+    runNativeChainLoaders(flat.chain, {
+      params: call.params,
+      path: call.path,
+      req: call.req,
+    }),
+  )
+
+  if ('verdict' in chainResult) {
     // SPA nav can't emit a redirect/404 in-place; force the client's full-reload
     // fallback so the document path produces the authoritative status.
     throw new Error('native verdict on SPA navigation — falling back to full reload')
   }
 
-  let ctx = (data ?? {}) as Record<string, unknown>
+  let ctx = chainResult.data
   const manifest = loadIslandManifest(templateName)
   const compManifest = loadComponentManifest(templateName)
   if ((manifest && manifest.length > 0) || (compManifest && compManifest.length > 0)) {
@@ -1295,6 +1384,19 @@ async function decodeActionBody(
   }
 }
 
+function actionErrorResponse(err: ActionError): RouteResponse {
+  // Flat domain-error body `{ code, message, data? }` — `code` is the client-side
+  // discriminator (vs the framework's enveloped `{ error: { … } }`). `data` is
+  // included only when present so the wire shape omits the key entirely otherwise.
+  const body: ActionErrorBody = { code: err.code, message: err.message }
+  if (err.data !== undefined) body.data = err.data
+  return {
+    status: err.status,
+    body: JSON.stringify(body),
+    contentType: 'application/json; charset=utf-8',
+  }
+}
+
 export async function dispatchAction(
   call: Extract<RouteCall, { kind: 'action' }>,
   byId: Map<string, EndpointDef>,
@@ -1374,6 +1476,7 @@ export async function dispatchAction(
         contentType: 'application/json; charset=utf-8',
       }
     } catch (err) {
+      if (isActionError(err)) return actionErrorResponse(err)
       const e = err instanceof Error ? err : new Error(String(err))
       console.error(`[brust] action ${def.method} ${def.path} threw:`, err)
       return {
@@ -1389,11 +1492,15 @@ export async function dispatchAction(
   try {
     response = await chain()
   } catch (err) {
-    console.error('[brust] action middleware uncaught:', err)
-    response = {
-      status: 500,
-      body: '{"error":{"message":"internal error"}}',
-      contentType: 'application/json; charset=utf-8',
+    if (isActionError(err)) {
+      response = actionErrorResponse(err)
+    } else {
+      console.error('[brust] action middleware uncaught:', err)
+      response = {
+        status: 500,
+        body: '{"error":{"message":"internal error"}}',
+        contentType: 'application/json; charset=utf-8',
+      }
     }
   }
   return {