akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/server/ssrFromRscRenderer.tsx

@@ -5,6 +5,8 @@ import { type AkanRequestStore, type AkanTheme, pushRequestFallback, requestStor
 import type { ReactNode } from "react";
 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, SsrFromRscInput, SsrLateRedirect } from "./ssrTypes";
 
 const DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES = 1024;
@@ -45,9 +47,7 @@ export class SsrChunkRegistry<T> {
     let entry = uniqueKeys
       .map((key) => this.#entriesByKey.get(key))
       .find((item): item is SsrChunkRegistryEntry<T> => Boolean(item));
-    if (!entry) {
-      entry = { keys: new Set(), lruKey: uniqueKeys[0] as string, value };
-    }
+    entry ??= { keys: new Set(), lruKey: uniqueKeys[0] as string, value };
     entry.value = value;
 
     for (const key of uniqueKeys) {
@@ -97,7 +97,7 @@ export function encodeInlineRscChunk(chunk: Uint8Array): InlineRscChunk {
   }
 }
 
-export function htmlEscapeJsonString(value: string): string {
+function htmlEscapeJsonString(value: string): string {
   return JSON.stringify(value)
     .replace(/</g, "\\u003c")
     .replace(/>/g, "\\u003e")
@@ -132,13 +132,6 @@ function sanitizeFlightRows(
   const debugInfoRowRe = /^[0-9a-z]+:D/;
   let buffered: Uint8Array<ArrayBuffer> = new Uint8Array(0);
 
-  const concatBytes = (left: Uint8Array, right: Uint8Array): Uint8Array<ArrayBuffer> => {
-    const combined = new Uint8Array(left.byteLength + right.byteLength);
-    combined.set(left, 0);
-    combined.set(right, left.byteLength);
-    return combined;
-  };
-
   const sanitizeRow = (row: Uint8Array): Uint8Array => {
     let text: string;
     try {
@@ -217,7 +210,7 @@ export class ExpectedLateRedirectStderrSuppressor {
 
   static start(lateControl?: Promise<SsrLateRedirect | null>): ExpectedLateRedirectStderrSuppressor | null {
     if (!lateControl) return null;
-
+    
     if (process.env.NODE_ENV === "production" && process.env.AKAN_SUPPRESS_LATE_REDIRECT_STDERR !== "1") return null;
     const suppressor = new ExpectedLateRedirectStderrSuppressor(lateControl);
     ExpectedLateRedirectStderrSuppressor.#active.add(suppressor);
@@ -355,7 +348,11 @@ export function interleaveRscScriptsWithHtml(
   const bootstrapDetector = new InlineBootstrapDetector();
   const pendingRscScripts: Uint8Array[] = [];
   const pendingControlScripts: Uint8Array[] = [];
-  const maxPendingRscScripts = SsrFromRscRendererConfig.maxPendingInlineRscScripts(options.maxPendingRscScripts);
+  const explicitMax = options.maxPendingRscScripts;
+  const maxPendingRscScripts =
+    explicitMax !== undefined && Number.isFinite(explicitMax) && explicitMax > 0
+      ? Math.floor(explicitMax)
+      : (parsePositiveInt(process.env.AKAN_MAX_PENDING_INLINE_RSC_SCRIPTS) ?? DEFAULT_MAX_PENDING_INLINE_RSC_SCRIPTS);
   const queueDrainResolvers: Array<() => void> = [];
   const scriptAvailableResolvers: Array<() => void> = [];
   let errored = false;
@@ -476,8 +473,8 @@ export function interleaveRscScriptsWithHtml(
         controller.close();
       };
 
+      const requestContext = options.requestStore ?? options.request;
       const runPump = () => {
-        const requestContext = options.requestStore ?? options.request;
         const cleanup = requestContext ? pushRequestFallback(requestContext) : undefined;
         return pump()
           .catch(fail)
@@ -486,7 +483,6 @@ export function interleaveRscScriptsWithHtml(
             options.onComplete?.();
           });
       };
-      const requestContext = options.requestStore ?? options.request;
       if (requestContext && requestStorage) void requestStorage.run(requestContext, runPump);
       else void runPump();
     },
@@ -498,14 +494,6 @@ export function interleaveRscScriptsWithHtml(
   });
 }
 
-class SsrFromRscRendererConfig {
-  static maxPendingInlineRscScripts(explicit?: number): number {
-    if (explicit !== undefined && Number.isFinite(explicit) && explicit > 0) return Math.floor(explicit);
-    const parsed = Number.parseInt(process.env.AKAN_MAX_PENDING_INLINE_RSC_SCRIPTS ?? "", 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_PENDING_INLINE_RSC_SCRIPTS;
-  }
-}
-
 class InlineBootstrapDetector {
   readonly #decoder = new TextDecoder();
   #buffer = "";
@@ -564,14 +552,6 @@ export class SsrFromRscRenderer {
   self.__RSC_CLOSE__ = function(){ self.__RSC_CLOSED__ = true; };
 })();`;
 
-  /**
-   * Where this deployment mounts its endpoints, for the tab's `fetchClient`. It cannot come off the client
-   * bundle: only `AKAN_PUBLIC_*` is inlined there, at build time, and the prefix is a runtime option of the
-   * process serving the page. It cannot come through a React prop either — `FetchClient` fixes its origin when
-   * the module graph initializes, which is before any component renders. So it rides the classic bootstrap,
-   * the one thing guaranteed to run ahead of every module script. Omitted when it matches what the bundle
-   * already assumes, so the default deployment pays no bytes.
-   */
   static #prefixBootstrap() {
     const api = getApiPrefix();
     const ws = getWsPrefix();
@@ -599,7 +579,6 @@ export class SsrFromRscRenderer {
   }
 
   async render(input: SsrFromRscInput): Promise<ReadableStream<Uint8Array>> {
-
     const [rscForSsr, rscForClient] = input.rscStream.tee();
 
     const ssrNodeStream = Readable.fromWeb(sanitizeFlightForSsrStream(rscForSsr) as never);
@@ -638,16 +617,14 @@ export class SsrFromRscRenderer {
       injectThemeInitScript: input.injectThemeInitScript,
     });
 
-    return SsrFromRscRenderer.#appendRscScriptsAfterHtml(
-      withHeadScripts,
-      SsrFromRscRenderer.#sanitizeFlightForClient(rscForClient),
-      input.bootstrapModules,
-      input.request,
-      input.requestStore,
-      input.lateControl,
-      () => stderrSuppressor?.stop(),
-      input.onCancel,
-    );
+    return interleaveRscScriptsWithHtml(withHeadScripts, sanitizeFlightForClientStream(rscForClient), {
+      bootstrapModuleScripts: SsrFromRscRenderer.#createBootstrapModuleScriptTags(input.bootstrapModules),
+      lateControl: input.lateControl,
+      onComplete: () => stderrSuppressor?.stop(),
+      onCancel: input.onCancel,
+      request: input.request,
+      requestStore: input.requestStore,
+    });
   }
 
   static #installWebpackShims(): void {
@@ -659,13 +636,16 @@ export class SsrFromRscRenderer {
     if (g.__rsc_ssr_shims_installed__) return;
     g.__rsc_ssr_shims_installed__ = true;
 
-    const registry = new SsrChunkRegistry<Record<string, unknown>>(SsrFromRscRenderer.#getSsrChunkRegistryMaxEntries());
+    const registry = new SsrChunkRegistry<Record<string, unknown>>(
+      parsePositiveInt(process.env.AKAN_SSR_CHUNK_REGISTRY_MAX_ENTRIES) ?? DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES,
+    );
     g.__webpack_chunk_load__ = async (chunkId: string) => {
       if (registry.get(chunkId)) {
         SsrFromRscRenderer.#chunkRegistryStats.ssrChunkCacheHitCount += 1;
         return;
       }
       const mod = (await import(chunkId)) as Record<string, unknown>;
+      
       const canonical = chunkId.replace(/\?v=\d+$/, "");
       registry.set([chunkId, canonical], mod);
       SsrFromRscRenderer.#chunkRegistryStats.ssrChunkLoadCount += 1;
@@ -674,30 +654,17 @@ export class SsrFromRscRenderer {
     };
     g.__webpack_require__ = (id: string) => {
       const mod = registry.get(id);
-      if (!mod) {
-        throw new Error(`[ssrFromRsc] module not loaded yet: ${id}`);
-      }
+      if (!mod) throw new Error(`[ssrFromRsc] module not loaded yet: ${id}`);
       return mod;
     };
   }
 
-  /**
-   * React rejects `stream.allReady` for any fatal error raised after the shell flushed — an abort landing
-   * mid-flush, a `flushCompletedQueues` invariant — and it attaches a handler to that promise itself only on
-   * the shell-error path, because `completeShell` replaces `onShellError` with a noop. Shell-first streaming
-   * never reads `allReady`, so an unheld rejection reaches `process.on("unhandledRejection")`, and under
-   * federation that took the whole replica down over one request's render.
-   *
-   * Holding it keeps the failure scoped to the stream that raised it. The response cannot become a 5xx — the
-   * shell's headers and markup are already on the wire — so the client gets a truncated document and the stack
-   * goes to the log; every other request and socket on the replica survives.
-   */
   static holdPostShellErrors(stream: { allReady: Promise<void> }, report: (error: unknown) => void): void {
     void stream.allReady.catch(report);
   }
 
   static #reportRenderError(error: unknown, input: SsrFromRscInput, phase = "render"): void {
-    const description = SsrFromRscRenderer.#describeError(error);
+    const description = error instanceof Error ? (error.stack ?? error.message) : String(error);
     if (SsrFromRscRenderer.#isExpectedRequestAbort(error)) {
       SsrFromRscRenderer.#logger.debug(`[SSR] ${phase} aborted: ${description}`);
       return;
@@ -706,12 +673,6 @@ export class SsrFromRscRenderer {
     SsrFromRscRenderer.#logger.error(`[SSR] ${phase} failed path=${path}: ${description}`);
   }
 
-  static #describeError(error: unknown): string {
-    if (!(error instanceof Error)) return String(error);
-    return error.stack ?? error.message;
-  }
-
-  /** A client that navigated away, or a stream we cancelled ourselves: expected, and not the replica's problem. */
   static #isExpectedRequestAbort(error: unknown): boolean {
     if (!(error instanceof Error)) return false;
     return (
@@ -740,24 +701,6 @@ export class SsrFromRscRenderer {
     return error.message === "Connection closed." || error.name === "AkanRedirectError";
   }
 
-  static #getSsrChunkRegistryMaxEntries(): number {
-    const parsed = Number.parseInt(process.env.AKAN_SSR_CHUNK_REGISTRY_MAX_ENTRIES ?? "", 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES;
-  }
-
-  /**
-   * Splice bootstrap-only head scripts immediately after the `<head>` opening
-   * tag in the outgoing HTML stream.
-   *
-   * We do this as a stream transform (rather than as a React child inside
-   * `<head>`) so importmaps are acquired before any modulepreload can start.
-   * The spec is strict: once the browser starts a module script fetch for a
-   * preload, the document's "allow-import-maps" bit flips to false and no
-   * further importmap can be acquired.
-   *
-   * The transform operates on UTF-8 bytes until it has spliced the tag, then
-   * becomes a pure passthrough to avoid any further per-chunk overhead.
-   */
   static #injectHeadScriptsIntoHead(
     stream: ReadableStream<Uint8Array>,
     options: {
@@ -789,7 +732,7 @@ export class SsrFromRscRenderer {
       if (!htmlTheme) return html;
       return html.replace(htmlOpenRe, (tag) => {
         if (/\sdata-theme\s*=/.test(tag)) return tag;
-        return tag.replace(/>$/, ` data-theme="${SsrFromRscRenderer.#escapeHtmlAttr(htmlTheme)}">`);
+        return tag.replace(/>$/, ` data-theme="${escapeHtmlAttr(htmlTheme)}">`);
       });
     };
 
@@ -816,7 +759,7 @@ export class SsrFromRscRenderer {
             if (tail) controller.enqueue(encoder.encode(tail));
             return;
           }
-
+          
           const tail = decoder.decode();
           const rest = withHtmlTheme(buffered + tail);
           if (rest) controller.enqueue(encoder.encode(rest));
@@ -825,47 +768,11 @@ export class SsrFromRscRenderer {
     );
   }
 
-  static #escapeHtmlAttr(value: string): string {
-    return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  static #createBootstrapModulePreloadTags(bootstrapModules: string[] = []): string {
+    return bootstrapModules.map((src) => `<link rel="modulepreload" href="${escapeHtmlAttr(src)}">`).join("");
   }
 
-  static #createBootstrapModulePreloadTags(bootstrapModules?: string[]): string {
-    if (!bootstrapModules?.length) return "";
-    return bootstrapModules
-      .map((src) => `<link rel="modulepreload" href="${SsrFromRscRenderer.#escapeHtmlAttr(src)}">`)
-      .join("");
-  }
-
-  static #createBootstrapModuleScriptTags(bootstrapModules?: string[]): string {
-    if (!bootstrapModules?.length) return "";
-    return bootstrapModules
-      .map((src) => `<script type="module" src="${SsrFromRscRenderer.#escapeHtmlAttr(src)}"></script>`)
-      .join("");
-  }
-
-  static #sanitizeFlightForClient(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-    return sanitizeFlightForClientStream(stream);
-  }
-
-  static #appendRscScriptsAfterHtml(
-    htmlStream: ReadableStream<Uint8Array>,
-    rscClientStream: ReadableStream<Uint8Array>,
-    bootstrapModules?: string[],
-    request?: Request,
-    requestStore?: AkanRequestStore,
-    lateControl?: Promise<SsrLateRedirect | null>,
-    onComplete?: () => void,
-    onCancel?: (reason?: unknown) => void,
-  ): ReadableStream<Uint8Array> {
-    const bootstrapModuleScripts = SsrFromRscRenderer.#createBootstrapModuleScriptTags(bootstrapModules);
-
-    return interleaveRscScriptsWithHtml(htmlStream, rscClientStream, {
-      bootstrapModuleScripts,
-      lateControl,
-      onComplete,
-      onCancel,
-      request,
-      requestStore,
-    });
+  static #createBootstrapModuleScriptTags(bootstrapModules: string[] = []): string {
+    return bootstrapModules.map((src) => `<script type="module" src="${escapeHtmlAttr(src)}"></script>`).join("");
   }
 }

package/server/ssrTypes.ts

@@ -42,12 +42,7 @@ export interface RscTraceMetadata {
   patchHeadSafe?: boolean;
   patchHeadSnapshot?: string;
   routeState?: string;
-  /**
-   * Resolved from the matched route's `pageConfig.ssr === "block"`. Rides the
-   * trace so the host (which never resolves pageConfig itself) can decide
-   * whether the full-document SSR pass buffers until every Suspense boundary
-   * resolves. Absent/`false` means stream the shell first.
-   */
+  /** The route's `pageConfig.ssr === "block"`, carried here because the host never resolves pageConfig itself. */
   ssrBlocking?: boolean;
 }
 
@@ -57,34 +52,13 @@ export interface SsrFromRscInput {
   rscStream: ReadableStream<Uint8Array>;
   ssrManifest: SsrManifest;
   bootstrapModules?: string[];
-  /** Extra inline JS appended to the framework's bootstrap script. The HMR
-   * dev client lives here so the browser wires up its reload channel before
-   * any application module evaluates. */
   extraBootstrapInline?: string;
-  /**
-   * Bare specifier -> served URL mapping for the `<script type="importmap">`
-   * the HTML stream should prepend to `<head>`. Used so per-route client
-   * chunks (which externalize `react`, `react-dom/client`, ...) resolve
-   * those specifiers to the base build's vendor entries at load time,
-   * guaranteeing one React instance across rscClient and every route
-   * chunk.
-   *
-   * Injection happens via a stream transform, not React children, because the
-   * spec is strict: import maps must be acquired before any module script fetch
-   * starts, including modulepreload. Akan writes bootstrap module preloads
-   * directly after this importmap and delays the executable module script until
-   * the Fizz HTML stream has completed.
-   */
+
   importmap?: Record<string, string>;
   theme?: AkanTheme;
   injectThemeInitScript?: boolean;
   lateControl?: Promise<SsrLateRedirect | null>;
   onCancel?: (reason?: unknown) => void;
-  /**
-   * When true, buffer the whole document until every Suspense boundary resolves
-   * (`stream.allReady`) before emitting a byte, matching `pageConfig.ssr:
-   * "block"`. Defaults to shell-first streaming so `Loading` fallbacks surface.
-   * The `AKAN_SSR_WAIT_FOR_ALL_READY=1` env var forces blocking globally.
-   */
+  /** Buffers until `stream.allReady` (`pageConfig.ssr: "block"`); `AKAN_SSR_WAIT_FOR_ALL_READY=1` forces it globally. */
   waitForAllReady?: boolean;
 }

package/server/staticPath.ts

@@ -1,21 +1,5 @@
 import path from "node:path";
 
-/**
- * The file a URL path names inside one directory, or `null` when it names something outside it.
- *
- * Every static route the web router serves goes through here, so this is the single place a request path stops
- * being a string and becomes a file. The order matters: percent-decoding first (so `%2e%2e` is seen as `..`),
- * then a NUL check (a truncating byte in a path), then `path.resolve` to collapse the traversal, then
- * containment against the base **with a separator** — without it `/public-secrets` passes a `/public` check.
- *
- * Symlinks are followed, like nginx and `serve-static` do: `akan sync` builds `public/libs/<lib>` as a link to
- * `<workspaceRoot>/libs/<lib>/public`, so a link out of the tree is how a lib ships its assets, not an attack.
- * Refusing those would 404 every lib asset under `akan start` and nothing else — `akan build` copies `public/`
- * with `dereference: true`, so a built app has no links left to refuse. Traversal is what the string checks
- * above stop, and they run before any of this touches the filesystem.
- *
- * Callers check existence after this, so a path that resolves to nothing is handed back and 404s there.
- */
 export const resolveStaticPath = (baseDir: string, urlPath: string): string | null => {
   let decoded: string;
   try {

package/server/systemPageDocument.tsx

@@ -112,14 +112,18 @@ export function getSystemPageErrorDetails(error: unknown): string {
   return String(error);
 }
 
+export function getPathnameLocale(pathname: string, i18n: AkanI18nConfig): string {
+  const [segment] = pathname.split("/").filter(Boolean);
+  return segment && i18n.locales.includes(segment) ? segment : i18n.defaultLocale;
+}
+
 export function getSystemPageHomeHref({
   pathname,
   i18n = DEFAULT_AKAN_I18N,
   basePaths = [],
   headerBasePath,
 }: SystemPageHomeHrefOptions): string {
-  const segments = pathname.split("/").filter(Boolean);
-  const locale = i18n.locales.includes(segments[0] ?? "") ? segments[0] : i18n.defaultLocale;
+  const locale = getPathnameLocale(pathname, i18n);
   const basePath = getBasePathFromPathname(pathname, {
     basePaths,
     i18n,
@@ -127,3 +131,62 @@ export function getSystemPageHomeHref({
   });
   return `/${[locale, basePath].filter(Boolean).join("/")}`;
 }
+
+export interface SubRouteIndexOptions {
+  locale: string;
+  basePaths: string[];
+  subRoutes?: Record<string, string[]>;
+}
+
+const SUB_ROUTE_INDEX_STYLE = `
+.akan-sub-route-list { margin: 26px 0 0; padding: 0; list-style: none; display: grid; gap: 10px; }
+.akan-sub-route-link { display: grid; gap: 4px; border: 1px solid rgba(255, 255, 255, 0.12); border-radius: 18px; background: rgba(26, 26, 26, 0.72); padding: 16px 18px; text-decoration: none; }
+.akan-sub-route-link:hover { border-color: var(--akan-primary); background: rgba(255, 73, 59, 0.08); }
+.akan-sub-route-name { color: var(--akan-foreground); font-size: 1.1rem; font-weight: 800; letter-spacing: -0.02em; }
+.akan-sub-route-path { color: rgba(255, 255, 255, 0.66); font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 0.85rem; }
+.akan-sub-route-hosts { color: var(--akan-accent); font-size: 0.76rem; letter-spacing: 0.06em; overflow-wrap: anywhere; }
+`;
+
+export const getSubRouteIndexHref = (locale: string, basePath: string): string => `/${locale}/${basePath}`;
+
+export function createSubRouteIndexDocument({ locale, basePaths, subRoutes = {} }: SubRouteIndexOptions): ReactNode {
+  return (
+    <html lang={locale}>
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="robots" content="noindex" />
+        <title>Sub routes</title>
+        <style data-akan-system-page>{`${SYSTEM_PAGE_STYLE}${SUB_ROUTE_INDEX_STYLE}`}</style>
+      </head>
+      <body>
+        <main className="akan-system-page">
+          <section className="akan-system-card" aria-labelledby="akan-sub-route-title">
+            <p className="akan-system-eyebrow">Local dev</p>
+            <h1 id="akan-sub-route-title" className="akan-system-title">
+              Pick a sub route.
+            </h1>
+            <p className="akan-system-description">
+              This app serves every route under a sub path, so the site root has no page of its own. Only local runs see
+              this list; deployed hosts map straight onto one sub route.
+            </p>
+            <ul className="akan-sub-route-list">
+              {basePaths.map((basePath) => {
+                const hosts = subRoutes[basePath] ?? [];
+                return (
+                  <li key={basePath}>
+                    <a className="akan-sub-route-link" href={getSubRouteIndexHref(locale, basePath)}>
+                      <span className="akan-sub-route-name">{basePath}</span>
+                      <span className="akan-sub-route-path">{getSubRouteIndexHref(locale, basePath)}</span>
+                      {hosts.length ? <span className="akan-sub-route-hosts">{hosts.join(", ")}</span> : null}
+                    </a>
+                  </li>
+                );
+              })}
+            </ul>
+          </section>
+        </main>
+      </body>
+    </html>
+  );
+}

package/server/systemPages.tsx

@@ -1,7 +1,9 @@
 import type { ReactNode } from "react";
-import { createSubRouteIndexDocument, getSubRouteIndexHref, type SubRouteIndexOptions } from "./subRouteIndexDocument";
 import {
+  createSubRouteIndexDocument,
   createSystemPageDocument,
+  getSubRouteIndexHref,
+  type SubRouteIndexOptions,
   SYSTEM_PAGE_STATUS_COPY,
   type SystemPageKind,
   type SystemPageOptions,
@@ -15,7 +17,7 @@ export interface SubRouteIndexResponseOptions extends SubRouteIndexOptions {
   method?: string;
 }
 
-export { createSystemPageDocument, getSystemPageHomeHref } from "./systemPageDocument";
+export { getSystemPageHomeHref } from "./systemPageDocument";
 
 export async function createSystemPageResponse(options: SystemPageResponseOptions): Promise<Response> {
   return await renderDocumentResponse({