akanjs 3.0.2 → 3.1.0-rc.0

package/server/rscWorker.tsx

@@ -6,6 +6,8 @@ import type {
   PathRoute,
   RedirectStatus,
   ResolvedHead,
+  RouteRender,
+  RouteViewport,
 } from "akanjs/client";
 import { type AkanI18nConfig, DEFAULT_AKAN_I18N, getBasePathFromPathname, Logger } from "akanjs/common";
 import {
@@ -24,6 +26,8 @@ import {
 } from "akanjs/fetch";
 import type { ReactNode } from "react";
 import { renderToReadableStream } from "react-server-dom-webpack/server.node";
+import { ViewportMeta } from "../client/viewportMeta";
+import { toManifestJson, webManifestHref } from "../client/webManifest";
 import type { PagePromptRunInput } from "../signal/mcp/pagePrompt";
 import { getCurrentTrace, runTraced, SignalTrace } from "../signal/trace";
 import type { ClientManifest } from "./artifact";
@@ -40,7 +44,7 @@ import {
 import { createAkanLocaleAlternateHeadSnapshot, mergeAkanHeadSnapshots, renderAkanHeadSnapshot } from "./head";
 import { LogForwarder } from "./logging/logForwarder";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
-import { RouteElementComposer } from "./routeElementComposer";
+import { RouteElementComposer, type RouteNotFoundInPlace } from "./routeElementComposer";
 import {
   type AkanRscPatchDecision,
   createAkanRouterState,
@@ -69,7 +73,12 @@ import {
   shouldUseRscWorkerFullResultCache,
 } from "./rscWorkerCache";
 import type { RscTraceMetadata } from "./ssrTypes";
-import { createSystemPageDocument, getPathnameLocale, getSystemPageHomeHref } from "./systemPageDocument";
+import {
+  createSystemPageDocument,
+  getPathnameLocale,
+  getSystemPageHomeHref,
+  SystemPageMain,
+} from "./systemPageDocument";
 
 interface InitMsg {
   type: "init";
@@ -123,6 +132,11 @@ interface PagePromptRunMsg {
   requestId: string;
   input: PagePromptRunInput;
 }
+interface WebManifestMsg {
+  type: "web-manifest";
+  requestId: string;
+  basePath: string | null;
+}
 type InMsg =
   | InitMsg
   | RenderMsg
@@ -132,7 +146,8 @@ type InMsg =
   | InvalidateCacheMsg
   | LogLevelMsg
   | PagePromptsMsg
-  | PagePromptRunMsg;
+  | PagePromptRunMsg
+  | WebManifestMsg;
 type RenderControl =
   | { type: "redirect"; location: string; method: "replace" | "push"; status: RedirectStatus }
   | { type: "not-found" }
@@ -306,9 +321,20 @@ export class RscRenderer {
       case "page-prompt.run":
         void this.#answer(msg.requestId, "page-prompt.result", () => this.#pagePrompts.run(msg.input));
         return;
+      case "web-manifest":
+        void this.#answer(msg.requestId, "web-manifest.result", () => this.#webManifest(msg.basePath));
+        return;
     }
   }
 
+  async #webManifest(basePath: string | null): Promise<unknown> {
+    const pathname = `/${this.#i18n.defaultLocale}${basePath ? `/${basePath}` : ""}`;
+    const rootLayouts = RouteTreeBuilder.matchFallback(pathname, this.#fallbackRoutes)?.fallbackRoute.renderRootLayouts;
+    const manifests = await Promise.all((rootLayouts ?? []).map((render) => render.getLayoutManifest?.()));
+    const manifest = manifests.find((entry) => entry !== undefined);
+    return manifest ? toManifestJson(manifest) : null;
+  }
+
   async #answer(requestId: string, type: string, fn: () => Promise<unknown>): Promise<void> {
     try {
       this.#send({ type, requestId, result: await fn() });
@@ -458,11 +484,18 @@ export class RscRenderer {
         const beforeLoadedKeys = RouteTreeBuilder.getCacheStats().loadedModuleKeys;
         const cacheDecision = match ? this.#getResultCacheEntry(request, urlObj) : { entry: null };
         const cacheEntry = cacheDecision.entry;
+        const targetFrame = match
+          ? await RouteElementComposer.resolveSsrFramePathRoute({
+              pathRoute: match.pathRoute,
+              basePath: this.#getBasePath(urlObj),
+            })
+          : null;
         const targetRouterState = match
           ? createAkanRouterState({
               pathRoute: match.pathRoute,
               href: urlObj.href,
               buildId: this.#pagesBundleBuildId,
+              transition: targetFrame?.pageState.transition,
             })
           : null;
         const searchParams = RouteTreeBuilder.parseSearchParams(urlObj.search);
@@ -569,12 +602,15 @@ export class RscRenderer {
         }
         let element: ReactNode;
         let effectivePatchDecision = safePatchDecision;
+        const notFoundProbe = { hit: false };
+        const notFound = this.#notFoundInPlace(urlObj, notFoundProbe);
         if (match && safePatchDecision.status === "patch" && safePatchDecision.patch) {
           const suffixElement = await this.#renderMatchedSuffix(
             urlObj,
             match,
             safePatchDecision.patch.patchStartIndex,
             searchParams,
+            notFound,
           );
           if (suffixElement === null) {
             effectivePatchDecision = {
@@ -582,9 +618,9 @@ export class RscRenderer {
               reason: "suffix-compose-fallback",
               commonPrefixLength: safePatchDecision.commonPrefixLength,
             };
-            element = await this.#renderMatched(urlObj, match, searchParams);
+            element = await this.#renderMatched(urlObj, match, searchParams, notFound);
           } else element = suffixElement;
-        } else if (match) element = await this.#renderMatched(urlObj, match, searchParams);
+        } else if (match) element = await this.#renderMatched(urlObj, match, searchParams, notFound);
         else element = await this.#renderNotFound(urlObj);
         const traceCacheKey =
           effectivePatchDecision.status === "patch" ? (patchCacheEntry?.key ?? cacheEntry?.key) : cacheEntry?.key;
@@ -604,6 +640,7 @@ export class RscRenderer {
           }),
           status: match ? undefined : 404,
           trace,
+          notFoundProbe,
           onComplete: ({ chunks, bytes, chunksCount, control, lateControlSent }) => {
             const cacheState = shouldStoreRouteCache({
               policy: getRequestPolicy(),
@@ -827,6 +864,8 @@ export class RscRenderer {
       collectChunks?: boolean;
       status?: number;
       trace?: RscTraceMetadata;
+      /** Raised by a render that answered `router.notFound()` in place, which React never reports as an error. */
+      notFoundProbe?: { hit: boolean };
       onComplete?: (
         result: Omit<FlightRenderResult, "cancelled">,
       ) => Promise<RouteCacheRenderState> | RouteCacheRenderState;
@@ -881,17 +920,29 @@ export class RscRenderer {
       reportedTheme = theme;
       this.#send({ type: "theme", requestId: options.requestId, theme });
     };
-    const sendLateRedirect = () => {
-      if (!options.requestId || lateControlSent || controlRef.current?.type !== "redirect") return;
-      
+    const readProbe = () => {
+      if (!controlRef.current && options.notFoundProbe?.hit) controlRef.current = { type: "not-found" };
+    };
+
+    const sendLateControl = () => {
+      const control = controlRef.current;
+      if (!options.requestId || lateControlSent || !control || control.type === "error") return;
       lateControlSent = true;
-      this.#send({
-        type: "late-redirect",
-        requestId: options.requestId,
-        location: controlRef.current.location,
-        method: controlRef.current.method,
-        status: controlRef.current.status,
-      });
+      if (control.type === "redirect") {
+        this.#send({
+          type: "late-redirect",
+          requestId: options.requestId,
+          location: control.location,
+          method: control.method,
+          status: control.status,
+        });
+        return;
+      }
+      if (!options.notFoundProbe?.hit)
+        this.#logger.warn(
+          `render[${options.requestId}] not-found raised below a route render after the stream started; that subtree renders nothing — call router.notFound() from the page or layout body`,
+        );
+      this.#send({ type: "late-not-found", requestId: options.requestId });
     };
     try {
       for (;;) {
@@ -900,12 +951,22 @@ export class RscRenderer {
           return { chunks, bytes, chunksCount, control: null, lateControlSent, cancelled: true };
         }
         const { value, done } = await reader.read();
+        readProbe();
         if (controlRef.current && !sentChunk) {
           await reader.cancel();
           return { chunks, bytes, chunksCount, control: controlRef.current, lateControlSent, cancelled: false };
         }
-        if (controlRef.current && sentChunk) sendLateRedirect();
+        if (controlRef.current && sentChunk) sendLateControl();
         if (done) break;
+
+        if (!sentChunk && options.requestId) {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          readProbe();
+          if (controlRef.current) {
+            await reader.cancel();
+            return { chunks, bytes, chunksCount, control: controlRef.current, lateControlSent, cancelled: false };
+          }
+        }
         const chunk = value instanceof Uint8Array ? value : new Uint8Array(value as ArrayBufferLike);
         bytes += chunk.byteLength;
         chunksCount += 1;
@@ -926,7 +987,8 @@ export class RscRenderer {
       if (options.requestId) this.#activeRenderReaders.delete(options.requestId);
       reader.releaseLock();
     }
-    if (controlRef.current && sentChunk) sendLateRedirect();
+    readProbe();
+    if (controlRef.current && sentChunk) sendLateControl();
     if (controlRef.current && !sentChunk)
       return { chunks, bytes, chunksCount, control: controlRef.current, lateControlSent, cancelled: false };
     if (options.requestId) {
@@ -1211,6 +1273,8 @@ export class RscRenderer {
       digest,
     });
     if (!body) return null;
+    const viewport = await RscRenderer.#rootViewport(route.renderRootLayouts);
+    const manifestLink = await this.#renderManifestLink(url, route.renderRootLayouts);
     const routeHead =
       "resolveHead" in route
         ? await RouteElementComposer.resolveHeadWithSnapshot({
@@ -1224,7 +1288,8 @@ export class RscRenderer {
       <html lang={params.lang ?? getPathnameLocale(pathname, this.#i18n)} suppressHydrationWarning>
         <head key="head">
           <meta key="charset" charSet="utf-8" />
-          <meta key="viewport" name="viewport" content="width=device-width, initial-scale=1" />
+          {this.#renderViewport(viewport)}
+          {manifestLink}
           <meta key="robots" name="robots" content="noindex" />
           {routeHeadSnapshot
             ? renderAkanHeadSnapshot(routeHeadSnapshot)
@@ -1240,7 +1305,8 @@ export class RscRenderer {
   async #renderMatched(
     url: URL,
     match: { pathRoute: PathRoute; params: Record<string, string> },
-    searchParams = RouteTreeBuilder.parseSearchParams(url.search),
+    searchParams: Record<string, string | string[]>,
+    notFound: RouteNotFoundInPlace,
   ): Promise<ReactNode> {
     this.#logger.verbose(
       `composing route element pathname=${url.pathname} search=${url.search || "(none)"} params=${JSON.stringify(match.params)}`,
@@ -1250,10 +1316,13 @@ export class RscRenderer {
       basePath: this.#getBasePath(url),
     });
     setRequestFrameState(pathRoute.pageState);
+    await RouteElementComposer.checkArgs({ pathRoute, params: match.params, searchParams });
     
     const rootThemes = await Promise.all(pathRoute.renderRootLayouts.map((render) => render.getLayoutTheme?.()));
     const rootTheme = rootThemes.find((theme) => theme !== undefined);
     if (rootTheme) setRequestTheme(rootTheme);
+    const viewport = await RscRenderer.#rootViewport(pathRoute.renderRootLayouts);
+    const manifestLink = await this.#renderManifestLink(url, pathRoute.renderRootLayouts);
     const routeHead = await RouteElementComposer.resolveHeadWithSnapshot({
       pathRoute,
       params: match.params,
@@ -1265,13 +1334,15 @@ export class RscRenderer {
       params: match.params,
       searchParams,
       navKey: url.pathname + url.search,
+      notFound,
     });
     
     return (
       <html lang={match.params.lang ?? this.#i18n.defaultLocale} suppressHydrationWarning>
         <head key="head">
           <meta key="charset" charSet="utf-8" />
-          <meta key="viewport" name="viewport" content="width=device-width, initial-scale=1" />
+          {this.#renderViewport(viewport, rootTheme)}
+          {manifestLink}
           {routeHeadSnapshot
             ? renderAkanHeadSnapshot(routeHeadSnapshot)
             : (routeHead.node ?? this.#renderDefaultHead())}
@@ -1287,7 +1358,8 @@ export class RscRenderer {
     url: URL,
     match: { pathRoute: PathRoute; params: Record<string, string> },
     patchStartIndex: number,
-    searchParams = RouteTreeBuilder.parseSearchParams(url.search),
+    searchParams: Record<string, string | string[]>,
+    notFound: RouteNotFoundInPlace,
   ): Promise<ReactNode | null> {
     this.#logger.verbose(
       `composing route suffix pathname=${url.pathname} start=${patchStartIndex} params=${JSON.stringify(match.params)}`,
@@ -1297,6 +1369,7 @@ export class RscRenderer {
       basePath: this.#getBasePath(url),
     });
     setRequestFrameState(pathRoute.pageState);
+    await RouteElementComposer.checkArgs({ pathRoute, params: match.params, searchParams });
     await RouteElementComposer.resolveSuffixLoadings(pathRoute, patchStartIndex);
     return RouteElementComposer.composeSuffix({
       pathRoute,
@@ -1304,6 +1377,7 @@ export class RscRenderer {
       searchParams,
       patchStartIndex,
       navKey: url.pathname + url.search,
+      notFound,
     });
   }
 
@@ -1329,21 +1403,61 @@ export class RscRenderer {
     return this.#renderSystemNotFound(url);
   }
 
+  #notFoundInPlace(url: URL, probe: { hit: boolean }): RouteNotFoundInPlace {
+    return {
+      pathname: url.pathname,
+      onNotFound: () => {
+        probe.hit = true;
+      },
+      systemFallback: () => (
+        <SystemPageMain kind="not-found" pathname={url.pathname} homeHref={this.#systemHomeHref(url)} />
+      ),
+    };
+  }
+
+  #systemHomeHref(url: URL): string {
+    return getSystemPageHomeHref({
+      pathname: url.pathname,
+      i18n: this.#i18n,
+      basePaths: this.#basePaths,
+      headerBasePath: untrackedRequest()?.headers.get("x-base-path"),
+    });
+  }
+
   #renderSystemNotFound(url: URL): ReactNode {
     return createSystemPageDocument({
       kind: "not-found",
       pathname: url.pathname,
       lang: getPathnameLocale(url.pathname, this.#i18n),
-      homeHref: getSystemPageHomeHref({
-        pathname: url.pathname,
-        i18n: this.#i18n,
-        basePaths: this.#basePaths,
-        headerBasePath: untrackedRequest()?.headers.get("x-base-path"),
-      }),
+      homeHref: this.#systemHomeHref(url),
       stylesheetHref: this.#getStylesheetHref(url.pathname),
     });
   }
 
+  static async #rootViewport(renderRootLayouts: RouteRender[]): Promise<RouteViewport | undefined> {
+    const viewports = await Promise.all(renderRootLayouts.map((render) => render.getLayoutViewport?.()));
+    return viewports.find((viewport) => viewport !== undefined);
+  }
+
+  #renderViewport(viewport: RouteViewport | undefined, theme?: string): ReactNode {
+    return (
+      <>
+        <meta key="viewport" name="viewport" content={ViewportMeta.content(viewport)} />
+        {ViewportMeta.themeColors(viewport, theme).map(({ content, media }) => (
+          <meta key={`theme-color:${media ?? ""}`} name="theme-color" content={content} media={media} />
+        ))}
+      </>
+    );
+  }
+
+  async #renderManifestLink(url: URL, renderRootLayouts: RouteRender[]): Promise<ReactNode> {
+    const manifests = await Promise.all(renderRootLayouts.map((render) => render.getLayoutManifest?.()));
+    if (!manifests.some((manifest) => manifest !== undefined)) return null;
+    
+    const basePath = getBasePathFromPathname(url.pathname, { basePaths: this.#basePaths, i18n: this.#i18n });
+    return <link key="manifest" rel="manifest" href={webManifestHref(basePath)} />;
+  }
+
   #renderDefaultHead(): ReactNode {
     return <title key="title">{process.env.AKAN_PUBLIC_APP_NAME ?? "Akan App"}</title>;
   }

package/server/rscWorkerHost.ts

@@ -9,7 +9,7 @@ import type { ClientManifest } from "./artifact";
 import type { RouteCacheInvalidation, RouteCacheRenderState } from "./cachePolicy";
 import { ChildOutputReader } from "./logging/childOutputReader";
 import { MemoryLimit } from "./memoryLimit";
-import type { RscTraceMetadata, SsrLateRedirect } from "./ssrTypes";
+import type { RscTraceMetadata, SsrLateControl } from "./ssrTypes";
 import type { BaseBuildArtifact, CssAsset } from "./types";
 
 const DEFAULT_RSC_HOST_MAX_PENDING_CHUNKS = 256;
@@ -23,6 +23,7 @@ export interface RscPending {
   onCacheState?: (state: RouteCacheRenderState) => void;
   onRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
   onLateRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
+  onLateNotFound?: () => void;
   onNotFound?: () => void;
 }
 
@@ -48,7 +49,7 @@ export type RscRenderResult =
       theme?: AkanTheme;
       status?: number;
       trace?: RscTraceMetadata;
-      lateControl: Promise<SsrLateRedirect | null>;
+      lateControl: Promise<SsrLateControl | null>;
       cacheState: Promise<RouteCacheRenderState>;
       cancel: (reason?: unknown) => void;
     }
@@ -159,9 +160,9 @@ export function createRscHostRenderStream(input: {
   let theme: AkanTheme | undefined;
   let status: number | undefined;
   let trace: RscTraceMetadata | undefined;
-  let resolveLateControl!: (control: SsrLateRedirect | null) => void;
+  let resolveLateControl!: (control: SsrLateControl | null) => void;
   let resolveCacheState!: (state: RouteCacheRenderState) => void;
-  const lateControl = new Promise<SsrLateRedirect | null>((resolve) => {
+  const lateControl = new Promise<SsrLateControl | null>((resolve) => {
     resolveLateControl = resolve;
   });
   const cacheState = new Promise<RouteCacheRenderState>((resolve) => {
@@ -169,7 +170,7 @@ export function createRscHostRenderStream(input: {
   });
   let lateControlSettled = false;
   let cacheStateSettled = false;
-  const settleLateControl = (control: SsrLateRedirect | null) => {
+  const settleLateControl = (control: SsrLateControl | null) => {
     if (lateControlSettled) return;
     lateControlSettled = true;
     resolveLateControl(control);
@@ -277,6 +278,7 @@ export function createRscHostRenderStream(input: {
           },
           onLateRedirect: (location, method, status) =>
             settleLateControl({ type: "redirect", location, method, status }),
+          onLateNotFound: () => settleLateControl({ type: "not-found" }),
           onCacheState: settleCacheState,
           onNotFound: () => {
             settleLateControl(null);
@@ -326,11 +328,13 @@ type RscInMsg =
       method?: RscRedirectMethod;
       status?: RscRedirectStatus;
     }
+  | { type: "late-not-found"; requestId: string }
   | { type: "not-found"; requestId: string }
   | { type: "metrics"; metrics: AkanMetricsReport }
   | { type: "log.records"; records: LogRecord[]; dropped?: number }
   | { type: "page-prompts.result"; requestId: string; result: PagePromptEntry[] }
   | { type: "page-prompt.result"; requestId: string; result: PagePromptRun }
+  | { type: "web-manifest.result"; requestId: string; result: unknown }
   | {
       type: "error";
       requestId: string;
@@ -475,6 +479,11 @@ export class RscWorker {
     return this.#call<PagePromptRun>((requestId) => ({ type: "page-prompt.run", requestId, input }));
   }
 
+  /** The root layout's `.manifest()` for `basePath`, in the browser's keys; `null` when it declares none. */
+  webManifest(basePath: string | null): Promise<unknown> {
+    return this.#call<unknown>((requestId) => ({ type: "web-manifest", requestId, basePath }));
+  }
+
   #call<T>(message: (requestId: string) => object): Promise<T> {
     const requestId = crypto.randomUUID();
     return new Promise<T>((resolve, reject) => {
@@ -805,6 +814,9 @@ export class RscWorker {
           .get(message.requestId)
           ?.onLateRedirect?.(message.location, message.method ?? "replace", message.status ?? 307);
         return;
+      case "late-not-found":
+        this.#pending.get(message.requestId)?.onLateNotFound?.();
+        return;
       case "not-found":
         this.#resolvePending(message.requestId, (p) => p.onNotFound?.());
         return;
@@ -817,6 +829,7 @@ export class RscWorker {
         return;
       case "page-prompts.result":
       case "page-prompt.result":
+      case "web-manifest.result":
         this.#settleCall(message.requestId, (call) => call.resolve(message.result));
         return;
       case "error":

package/server/sitemap.ts

@@ -34,6 +34,20 @@ export function isSitemapPath(pathname: string, basePaths: readonly string[]): b
   return normalizePathname(pathname) === "/sitemap.xml";
 }
 
+/** The basePath a `/manifest.webmanifest` request asks for: by a visible prefix, else by the request's basePath. */
+export function getWebManifestBasePath(
+  pathname: string,
+  basePaths: readonly string[],
+  headerBasePath?: string | null,
+): string | null | undefined {
+  const segments = normalizePathname(pathname).split("/").filter(Boolean);
+  if (segments.at(-1) !== "manifest.webmanifest" || segments.length > 2) return undefined;
+  const known = basePaths.map(normalizeSegment);
+  if (segments.length === 2) return known.includes(segments[0] ?? "") ? (segments[0] ?? null) : undefined;
+  const fromHeader = normalizeSegment(headerBasePath ?? "");
+  return known.includes(fromHeader) ? fromHeader : null;
+}
+
 export function getSitemapBasePath(
   pathname: string,
   basePaths: readonly string[],

package/server/ssrFromRscRenderer.tsx

@@ -9,7 +9,13 @@ import { renderToReadableStream } from "react-dom/server.browser";
 import { createFromNodeStream } from "react-server-dom-webpack/client.node";
 import { parsePositiveInt } from "./cachePolicy";
 import { concatBytes } from "./rscHttp";
-import type { SsrChunkRegistryStats, SsrDocumentOptions, SsrFromRscInput, SsrLateRedirect } from "./ssrTypes";
+import type {
+  SsrChunkRegistryStats,
+  SsrDocumentOptions,
+  SsrFromRscInput,
+  SsrLateControl,
+  SsrLateRedirect,
+} from "./ssrTypes";
 
 const DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES = 1024;
 const DEFAULT_MAX_PENDING_INLINE_RSC_SCRIPTS = 32;
@@ -196,7 +202,7 @@ export class ExpectedLateRedirectStderrSuppressor {
   #lateRedirect = false;
   #lateControlSettled = false;
 
-  private constructor(lateControl: Promise<SsrLateRedirect | null>) {
+  private constructor(lateControl: Promise<SsrLateControl | null>) {
     lateControl
       .then((control) => {
         this.#lateRedirect = control?.type === "redirect";
@@ -210,7 +216,7 @@ export class ExpectedLateRedirectStderrSuppressor {
       });
   }
 
-  static start(lateControl?: Promise<SsrLateRedirect | null>): ExpectedLateRedirectStderrSuppressor | null {
+  static start(lateControl?: Promise<SsrLateControl | null>): ExpectedLateRedirectStderrSuppressor | null {
     if (!lateControl) return null;
     
     if (process.env.NODE_ENV === "production" && process.env.AKAN_SUPPRESS_LATE_REDIRECT_STDERR !== "1") return null;
@@ -337,7 +343,7 @@ export function interleaveRscScriptsWithHtml(
   rscClientStream: ReadableStream<Uint8Array>,
   options: {
     bootstrapModuleScripts?: string;
-    lateControl?: Promise<SsrLateRedirect | null>;
+    lateControl?: Promise<SsrLateControl | null>;
     maxPendingRscScripts?: number;
     onPendingRscScriptsSize?: (size: number) => void;
     onComplete?: () => void;
@@ -433,7 +439,7 @@ export function interleaveRscScriptsWithHtml(
         const rscPump = pumpRscScripts();
         const lateControlPump = options.lateControl?.then((control) => {
           try {
-            if (!control || errored) return;
+            if (control?.type !== "redirect" || errored) return;
             pendingControlScripts.push(encoder.encode(createSoftRedirectScript(control)));
             notifyScriptAvailable();
           } finally {
@@ -691,7 +697,7 @@ export class SsrFromRscRenderer {
 
   static #suppressExpectedLateRedirectError(
     thenable: PromiseLike<ReactNode>,
-    lateControl?: Promise<SsrLateRedirect | null>,
+    lateControl?: Promise<SsrLateControl | null>,
   ): Promise<ReactNode> {
     const promise = Promise.resolve(thenable);
     if (!lateControl) return promise;

package/server/ssrTypes.ts

@@ -26,6 +26,8 @@ export interface SsrLateRedirect {
   status: 303 | 307 | 308;
 }
 
+export type SsrLateControl = SsrLateRedirect | { type: "not-found" };
+
 export interface RscTraceMetadata {
   navId?: string;
   pathname: string;
@@ -57,7 +59,7 @@ export interface SsrFromRscInput {
   importmap?: Record<string, string>;
   theme?: AkanTheme;
   injectThemeInitScript?: boolean;
-  lateControl?: Promise<SsrLateRedirect | null>;
+  lateControl?: Promise<SsrLateControl | null>;
   onCancel?: (reason?: unknown) => void;
   /** Buffers until `stream.allReady` (`pageConfig.ssr: "block"`); `AKAN_SSR_WAIT_FOR_ALL_READY=1` forces it globally. */
   waitForAllReady?: boolean;

package/server/systemPageDocument.tsx

@@ -57,9 +57,45 @@ a { color: inherit; }
 .akan-system-details { margin-top: 28px; max-height: 260px; overflow: auto; border-radius: 18px; background: rgba(26, 26, 26, 0.82); border: 1px solid rgba(240, 32, 32, 0.22); padding: 16px; color: rgba(255, 255, 255, 0.78); font-size: 0.82rem; line-height: 1.55; white-space: pre-wrap; }
 `;
 
-export function createSystemPageDocument(options: SystemPageOptions): ReactNode {
+/** The card alone, styled by the app's own tokens: what a not-found raised after the layouts streamed renders in place. */
+export const SystemPageMain = (options: Omit<SystemPageOptions, "lang" | "stylesheetHref" | "script">) => {
   const copy = SYSTEM_PAGE_STATUS_COPY[options.kind];
   const details = options.showDetails ? getSystemPageErrorDetails(options.error) : null;
+  return (
+    <main className="akan-system-page min-h-screen bg-background text-foreground">
+      <section
+        className="akan-system-card rounded-3xl border border-foreground/10 bg-foreground/4 p-8 shadow-2xl backdrop-blur-xl"
+        aria-labelledby="akan-system-title"
+      >
+        <p className="akan-system-status text-primary">{copy.status}</p>
+        <p className="akan-system-eyebrow text-primary">{copy.eyebrow}</p>
+        <h1 id="akan-system-title" className="akan-system-title font-black">
+          {copy.title}
+        </h1>
+        <p className="akan-system-description text-foreground/70">{copy.description}</p>
+        <p className="akan-system-path border border-foreground/10 bg-muted/50" aria-label="Requested path">
+          {options.pathname}
+        </p>
+        <div className="akan-system-actions">
+          <a className="akan-system-action" href={options.homeHref}>
+            {copy.actionLabel}
+          </a>
+          <a className="akan-system-action akan-system-secondary" href={options.pathname}>
+            Try again
+          </a>
+        </div>
+        {details ? (
+          <pre className="akan-system-details" aria-label="Development error details">
+            {details}
+          </pre>
+        ) : null}
+      </section>
+    </main>
+  );
+};
+
+export function createSystemPageDocument(options: SystemPageOptions): ReactNode {
+  const copy = SYSTEM_PAGE_STATUS_COPY[options.kind];
   const title = `${copy.status} - ${copy.eyebrow}`;
 
   return (
@@ -75,35 +111,7 @@ export function createSystemPageDocument(options: SystemPageOptions): ReactNode
         <style data-akan-system-page>{SYSTEM_PAGE_STYLE}</style>
       </head>
       <body>
-        <main className="akan-system-page min-h-screen bg-background text-foreground">
-          <section
-            className="akan-system-card rounded-3xl border border-foreground/10 bg-foreground/4 p-8 shadow-2xl backdrop-blur-xl"
-            aria-labelledby="akan-system-title"
-          >
-            <p className="akan-system-status text-primary">{copy.status}</p>
-            <p className="akan-system-eyebrow text-primary">{copy.eyebrow}</p>
-            <h1 id="akan-system-title" className="akan-system-title font-black">
-              {copy.title}
-            </h1>
-            <p className="akan-system-description text-foreground/70">{copy.description}</p>
-            <p className="akan-system-path border border-foreground/10 bg-muted/50" aria-label="Requested path">
-              {options.pathname}
-            </p>
-            <div className="akan-system-actions">
-              <a className="akan-system-action" href={options.homeHref}>
-                {copy.actionLabel}
-              </a>
-              <a className="akan-system-action akan-system-secondary" href={options.pathname}>
-                Try again
-              </a>
-            </div>
-            {details ? (
-              <pre className="akan-system-details" aria-label="Development error details">
-                {details}
-              </pre>
-            ) : null}
-          </section>
-        </main>
+        <SystemPageMain {...options} />
         {options.script ? (
           
           <script dangerouslySetInnerHTML={{ __html: options.script }} />

package/server/types.tsx

@@ -1,6 +1,7 @@
 import type { AkanWebConfig } from "akanjs";
 import type { PromiseOrObject } from "akanjs/base";
 import type { AkanI18nConfig } from "akanjs/common";
+import type { WebsocketRoomCursor } from "akanjs/signal";
 import type { ClientManifest } from "./artifact";
 import type { SsrManifest } from "./ssrTypes";
 
@@ -8,6 +9,7 @@ export type WebsocketRoute = (
   ws: Bun.ServerWebSocket<unknown>,
   data: unknown[],
   event?: "message" | "subscribe" | "unsubscribe",
+  request?: { since?: WebsocketRoomCursor },
 ) => PromiseOrObject<unknown>;
 
 export type WebsocketRoutes = Record<string, WebsocketRoute>;