akanjs 3.0.0-beta.25 → 3.0.0-beta.27

package/client/csrTypes.ts

@@ -174,6 +174,8 @@ export interface Route {
   path: string;
   renderPage?: RouteRender;
   renderLayout?: RouteRender;
+  /** `renderLayout` is a generated `__root_layout`: a root boundary the page generator found. */
+  isRootLayout?: boolean;
   /** Synthetic layout render from a `_overrides.tsx` at this node; wraps the subtree in a UI-override provider. */
   renderOverrides?: RouteRender;
   pageIncludesOwnLayout?: boolean;

package/client/device.ts

@@ -15,14 +15,13 @@ let debugSeq = 0;
 
 const isFrameDebugEnabled = () => {
   if (typeof window === "undefined") return false;
-  const windowWithTarget = window as typeof window & { __AKAN_MOBILE_TARGET__?: unknown };
-  const search = new URLSearchParams(window.location.search);
-  return (
-    Boolean(windowWithTarget.__AKAN_MOBILE_TARGET__) ||
-    search.has("akanMobileTarget") ||
-    search.get("akanFrameDebug") === "1" ||
-    window.localStorage.getItem("akan:debug:frame") === "1"
-  );
+  if (new URLSearchParams(window.location.search).get("akanFrameDebug") === "1") return true;
+  try {
+    return window.localStorage.getItem("akan:debug:frame") === "1";
+  } catch {
+    
+    return false;
+  }
 };
 
 export function debugFrame(event: string, payload: DebugPayload = {}) {
@@ -33,7 +32,8 @@ export function debugFrame(event: string, payload: DebugPayload = {}) {
     now: Math.round(performance.now()),
     ...payload,
   };
-  console.info(`[akan:frame:${debugSessionId}:${debugSeq}] ${event}`, details, JSON.stringify(details));
+  
+  console.debug(`[akan:frame:${debugSessionId}:${debugSeq}] ${event}`, details);
 }
 
 interface DeviceInitOption {

package/common/Logger.ts

@@ -77,6 +77,15 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
   error: clc.red,
 };
 
+const consoleMethodMap = {
+  trace: "debug",
+  verbose: "debug",
+  debug: "debug",
+  info: "info",
+  warn: "warn",
+  error: "error",
+} as const satisfies { [key in LogLevel]: "debug" | "info" | "warn" | "error" };
+
 const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
 
 const redactedAttrKey = /password|passwd|token|jwt|authorization|cookie|secret|api[-_]?key|private[-_]?key/i;
@@ -332,7 +341,22 @@ export class Logger {
     if (!Logger.consoleOutput) return;
     if (typeof window === "undefined")
       (process[entry.stream] as unknown as NodeJS.WriteStream | undefined)?.write(entry.message);
-    else console.log(entry.message);
+    else Logger.#writeBrowserConsole(entry.record, entry.message);
+  }
+
+  static #writeBrowserConsole(record: LogRecord, rendered: string) {
+    const level = record.level ?? "info";
+    const context = record.context ? `[${record.context}] ` : "";
+    const attrs = record.attrs ? ` ${Logger.formatAttrs(record.attrs)}` : "";
+    const text = Logger.#inNativeShell()
+      ? `[${record.name}] ${context}${record.message}${attrs}`
+      : rendered.replace(/\n+$/, "");
+    
+    console[consoleMethodMap[level]](text);
+  }
+  static #inNativeShell() {
+    const platform = (globalThis as { __AKAN_NATIVE__?: { platform?: string } }).__AKAN_NATIVE__?.platform;
+    return platform !== undefined && platform !== "web";
   }
   static #write(name: string | undefined, message: string, context: string, logLevel: LogLevel, attrs?: LogAttrs) {
     const stream = logLevel === "error" ? "stderr" : "stdout";
@@ -367,7 +391,7 @@ export class Logger {
     if (!Logger.consoleOutput) return;
     if (typeof window === "undefined" && method !== "console" && (process as unknown as NodeJS.Process | undefined))
       process[stream].write(msg);
-    else console[outputStream === "error" ? "error" : "log"](msg.trim());
+    else console[outputStream === "error" ? "error" : Logger.#inNativeShell() ? "debug" : "log"](msg.trim());
   }
   static {
     if (envValue("AKAN_PUBLIC_LOG_LEVEL") === "log" && typeof window === "undefined")

package/common/RouteLayering.ts

@@ -0,0 +1,52 @@
+interface LayeredRoute<Render> {
+  /** The tree segment: `/`, `/:lang`, `/(group)`, `/foo`. */
+  path: string;
+  renderLayout?: Render;
+  /** A generated `__root_layout`: one of the root boundaries the page generator found. */
+  isRootLayout?: boolean;
+  renderOverrides?: Render;
+  /** `false` for a named page file, which sits beside its directory's layout rather than under it. */
+  pageIncludesOwnLayout?: boolean;
+}
+
+export interface RouteLayer<Render> {
+  /** The URL pattern down to this node; a route group adds nothing to it. */
+  path: string;
+  pathSegments: string[];
+  isRoot: boolean;
+  /** The root layout above or at this node, overrides left out: once there is one, nothing below is a root. */
+  rootLayouts: Render[];
+  renderRootLayouts: Render[];
+  renderLayouts: Render[];
+  /** What a page file at this node renders inside: without this node's layout for a named page file. */
+  pageRenderRootLayouts: Render[];
+  pageRenderLayouts: Render[];
+}
+
+export class RouteLayering {
+  static readonly #group = /^\/\(.*\)$/;
+
+  static of<Render>(route: LayeredRoute<Render>, parent: RouteLayer<Render> | null): RouteLayer<Render> {
+    const parentSegments = parent?.pathSegments ?? [];
+    const parentRootLayouts = parent?.rootLayouts ?? [];
+    const parentRootRenders = parent?.renderRootLayouts ?? [];
+    const parentLayouts = parent?.renderLayouts ?? [];
+    const segment = RouteLayering.#group.test(route.path) ? "" : route.path;
+    const path = parentSegments.filter((part) => part !== "/").join("") + segment;
+    const isRoot = parentRootLayouts.length === 0 && (route.isRootLayout === true || !route.renderLayout);
+    const overrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
+
+    const nodeRenders = [...overrideRenders, ...(route.renderLayout ? [route.renderLayout] : [])];
+    const pageNodeRenders = route.pageIncludesOwnLayout === false ? overrideRenders : nodeRenders;
+    return {
+      path,
+      pathSegments: [...parentSegments, ...(segment ? [segment] : [])],
+      isRoot,
+      rootLayouts: isRoot && route.renderLayout ? [...parentRootLayouts, route.renderLayout] : parentRootLayouts,
+      renderRootLayouts: isRoot ? [...parentRootRenders, ...nodeRenders] : parentRootRenders,
+      renderLayouts: isRoot ? parentLayouts : [...parentLayouts, ...nodeRenders],
+      pageRenderRootLayouts: isRoot ? [...parentRootRenders, ...pageNodeRenders] : parentRootRenders,
+      pageRenderLayouts: isRoot ? parentLayouts : [...parentLayouts, ...pageNodeRenders],
+    };
+  }
+}

package/common/hmrPhase.ts

@@ -5,6 +5,7 @@ declare global {
   var __AKAN_HMR_PHASE__: AkanHmrPhase | undefined;
 }
 
+/** @deprecated Always `null`: the dev client that set the phase applies modules through its registry now. */
 export function getAkanHmrPhase(): AkanHmrPhase {
   if (typeof globalThis === "undefined") return null;
   const phase = globalThis.__AKAN_HMR_PHASE__;
@@ -12,6 +13,7 @@ export function getAkanHmrPhase(): AkanHmrPhase {
   return null;
 }
 
+/** @deprecated Always `false`, for the reason `getAkanHmrPhase` is always `null`. */
 export function isAkanHmrApplying(): boolean {
   return getAkanHmrPhase() !== null;
 }

package/common/index.ts

@@ -128,6 +128,7 @@ export {
 export { deepObjectify, objectify, plainFieldsOf } from "./objectify";
 export { pathGet, pathGetLoose, pathSet, toPathSegments } from "./objectPath";
 export { formatPhone, isPhoneNumber } from "./phone";
+export { type RouteLayer, RouteLayering } from "./RouteLayering";
 export { randomPick, randomPicks } from "./randomPick";
 export { hostFromRequest, isJsonContentType, originFromRequest } from "./requestOrigin";
 export { RestClient, type RestClientOptions, type RestRequestOptions } from "./restClient";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.25",
+  "version": "3.0.0-beta.27",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/artifact/devBuildRecovery.ts

@@ -0,0 +1,12 @@
+import type { DevBuildStatus } from "./ipcTypes";
+
+export class DevBuildRecovery {
+
+  static recovers(previous: DevBuildStatus | undefined, status: DevBuildStatus): boolean {
+    if (!previous || previous.ok || !status.ok) return false;
+    if (status.phase === "route" && status.scope !== undefined && previous.scope !== undefined)
+      return status.scope === previous.scope && status.generation >= previous.generation;
+    if (status.generation !== previous.generation) return status.generation > previous.generation;
+    return status.phase === "backend";
+  }
+}

package/server/artifact/index.ts

@@ -1,4 +1,5 @@
 export * from "./builderRpc";
+export * from "./devBuildRecovery";
 export * from "./ipcTypes";
 export * from "./routeClientCache";
 export * from "./routeSeedIndexStore";

package/server/artifact/ipcTypes.ts

@@ -52,6 +52,8 @@ export interface DevBuildStatus {
   ok: boolean;
   files: string[];
   message?: string;
+  /** The route a route build's status speaks for. */
+  scope?: string;
 }
 
 export type BuilderReq = {

package/server/di/diLifecycle.ts

@@ -118,7 +118,7 @@ export class DiLifecycle {
   constructor({ env, modules = [], disableModules = [], disableLibs = [] }: DiLifecycleProps, ...libs: AkanLib[]) {
     this.#env = env;
     const databaseMode = DiLifecycle.#databaseMode();
-    this.logger.info(`Database mode: ${DatabaseModes.describe(databaseMode)}`);
+    this.logger.debug(`Database mode: ${DatabaseModes.describe(databaseMode)}`);
     
     this.#predefinedAdaptor = { ...getPredefinedAdaptor(databaseMode) };
     this.#libs = libs;

package/server/hmr/clientScript.ts

@@ -52,12 +52,12 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   function connect(){
     try { socket = new WebSocket(url); }
     catch(e){ console.error("[akan-hmr] ws init failed", e); schedule(); return; }
-    socket.addEventListener("open", function(){ attempts = 0; });
     socket.addEventListener("message", function(ev){
       var msg;
       try { msg = JSON.parse(ev.data); } catch (e){ return; }
       if (!msg || typeof msg.type !== "string") return;
       if (msg.type === "hello") {
+        attempts = 0;
         var dropped = Array.isArray(msg.failingPhases) && dropBuildErrorsExcept(msg.failingPhases);
         if (dropped && systemPage) {
           reloadForUpdate("the build that failed to render this page recovered");
@@ -387,7 +387,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     var current = buildErrorStates[phase];
     if (!current) return;
     var generation = typeof msg.generation === "number" ? msg.generation : 0;
-    var sameGeneration = phase === "backend" || phase === "scan" || phase === "route";
+    var sameGeneration = phase === "backend" || phase === "route";
     var recovered = sameGeneration ? generation >= current.generation : generation > current.generation;
     if (!recovered) return;
     delete buildErrorStates[phase];
@@ -405,6 +405,12 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     return dropped;
   }
 
+  function clearRenderError(){
+    if (!buildErrorStates.build) return;
+    delete buildErrorStates.build;
+    showBuildRecovered({});
+  }
+
   function showBuildRecovered(msg){
     if (hasBuildErrors()) {
       renderBuildErrorOverlay();
@@ -462,9 +468,12 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     return prefix ? prefix + "\\n" + msg.message : msg.message;
   }
 
+  var rscRefreshSeq = 0;
+  var rscRefreshedSeq = 0;
   function refreshRsc(msg){
     var receivedAt = Date.now();
-    var refresh = function(){ doRefreshRsc(msg, receivedAt); };
+    var seq = ++rscRefreshSeq;
+    var refresh = function(){ if (seq === rscRefreshSeq) doRefreshRsc(msg, receivedAt, seq); };
     var settle = function(){
       return self.__akan && typeof self.__akan.whenSettled === "function" ? self.__akan.whenSettled() : null;
     };
@@ -477,7 +486,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     settled.then(refresh, refresh);
   }
 
-  function doRefreshRsc(msg, receivedAt){
+  function doRefreshRsc(msg, receivedAt, seq){
     var started = performance.now();
     var overlayToken = beginHmrOverlay("Refreshing page...");
     try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}
@@ -488,9 +497,13 @@ export const HMR_CLIENT_SCRIPT = `(function(){
       return;
     }
     Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){
-      lastBuildId = msg.buildId;
+      if (!(seq < rscRefreshedSeq)) {
+        rscRefreshedSeq = seq;
+        lastBuildId = msg.buildId;
+      }
       recordTrace("rsc-refresh", msg, receivedAt, Date.now());
       endHmrOverlay(overlayToken);
+      clearRenderError();
       console.debug && console.debug("[akan-hmr] RSC refreshed", {
         buildId: msg.buildId,
         generation: msg.generation,

package/server/hmr/csrDevRuntime.ts

@@ -207,21 +207,25 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
       const entry = script?.dataset.akanCsrEntry;
       if (!entry) throw new Error("[akan-csr] the app script carries no data-akan-csr-entry");
       this.#generation = generation;
-      this.#refresh = this.#load(refresh).exports as RefreshRuntime;
-      
-      this.#refresh.injectIntoGlobalHook(host);
-      this.#run(entry);
+      this.#run(entry, () => {
+        const runtime = this.#load(refresh).exports as RefreshRuntime;
+        
+        runtime.injectIntoGlobalHook(host);
+        this.#refresh = runtime;
+      });
     }
 
     startLibrary({ generation, refresh, bootstrap, vendorFile, epoch }: LibraryStart) {
       this.#library = { vendorFile, epoch };
       this.#generation = generation;
-      this.#refresh = this.#load(refresh).exports as RefreshRuntime;
-      this.#run(bootstrap);
+      this.#run(bootstrap, () => {
+        this.#refresh = this.#load(refresh).exports as RefreshRuntime;
+      });
     }
 
-    #run(entry: string) {
+    #run(entry: string, loadRefresh: () => void) {
       try {
+        loadRefresh();
         this.#load(entry);
       } catch (error) {
         this.#startFailed = true;

package/server/hmr/csrDevShell.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveStaticPath } from "../staticPath";
 import {
@@ -38,6 +39,8 @@ export class CsrDevShell {
   readonly #appWaitMs: number;
   readonly #appPollMs: number;
   readonly #bootWaitMs: number;
+  
+  readonly #sourceMaps = new Map<string, { stamp: string; body: string }>();
 
   constructor(
     artifactDir: string,
@@ -109,7 +112,8 @@ ${stylesheet}  </head>
     const deadline = Date.now() + this.#appWaitMs;
     for (;;) {
       const manifest = await this.readManifest();
-      if (!manifest || appGenerationOf(manifest) >= generation || Date.now() >= deadline || signal?.aborted) return;
+      if (!manifest || manifest.generation < generation || appGenerationOf(manifest) >= generation) return;
+      if (Date.now() >= deadline || signal?.aborted) return;
       await Bun.sleep(this.#appPollMs);
     }
   }
@@ -135,9 +139,26 @@ ${stylesheet}  </head>
 
   async #serveSourceMap(name: string): Promise<Response> {
     const generatedFile = name.slice(0, -".map".length);
-    const layoutFile = Bun.file(path.join(this.#dir, `${generatedFile}.layout.json`));
-    if (!(await layoutFile.exists())) return new Response("Not Found", { status: 404 });
-    const layout = (await layoutFile.json()) as CsrDevLayout;
+    const layoutPath = path.join(this.#dir, `${generatedFile}.layout.json`);
+    const stat = await fs.stat(layoutPath).catch(() => null);
+    if (!stat) return new Response("Not Found", { status: 404 });
+    const stamp = `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+    const cached = this.#sourceMaps.get(generatedFile);
+    const body = cached?.stamp === stamp ? cached.body : await this.#mergeSourceMap(generatedFile, layoutPath);
+    if (!body) return new Response("Not Found", { status: 404 });
+    this.#sourceMaps.delete(generatedFile);
+    this.#sourceMaps.set(generatedFile, { stamp, body });
+    for (const oldest of this.#sourceMaps.keys()) {
+      if (this.#sourceMaps.size <= 4) break;
+      this.#sourceMaps.delete(oldest);
+    }
+    return new Response(body, { headers: CsrDevShell.#headers("application/json", "no-store") });
+  }
+
+  async #mergeSourceMap(generatedFile: string, layoutPath: string): Promise<string | null> {
+    const layoutText = await fs.readFile(layoutPath, "utf8").catch(() => null);
+    if (!layoutText) return null;
+    const layout = JSON.parse(layoutText) as CsrDevLayout;
     const sections = await Promise.all(
       layout.modules.map(async ([id, line]) => {
         const file = Bun.file(path.join(this.#dir, csrDevModuleFile(id, ".js.map")));
@@ -149,7 +170,7 @@ ${stylesheet}  </head>
       sections.filter((section) => section !== null),
       layout.lineCount,
     );
-    return new Response(JSON.stringify(map), { headers: CsrDevShell.#headers("application/json", "no-store") });
+    return JSON.stringify(map);
   }
 
   static #js(body: string | Blob, cacheControl: string): Response {

package/server/hmr/devArtifactPruner.ts

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { CssAsset } from "../types";
+
+export class DevArtifactPruner {
+  
+  static readonly #defaultGraceMs = 60_000;
+  static readonly #pagesFile = /^pages-[^/\\]+\.js$/;
+  readonly #logger = new Logger("DevArtifactPruner");
+  readonly #artifactDir: string;
+  readonly #graceMs: number;
+  #pruning: Promise<void> = Promise.resolve();
+
+  constructor(artifactDir: string, { graceMs = DevArtifactPruner.#defaultGraceMs }: { graceMs?: number } = {}) {
+    this.#artifactDir = path.resolve(artifactDir);
+    this.#graceMs = graceMs;
+  }
+
+  prunePages(runningPath: string): Promise<void> {
+    return this.#queue(async () => {
+      const running = await fs.stat(runningPath).catch(() => null);
+      if (!running) return;
+      const keep = new Set([path.resolve(runningPath), ...(await this.#baseArtifact()).pages]);
+      const serverDir = path.join(this.#artifactDir, "server");
+      const before = Math.min(running.mtimeMs, Date.now() - this.#graceMs);
+      await this.#removeOlder(serverDir, (name) => DevArtifactPruner.#pagesFile.test(name), keep, before);
+    });
+  }
+
+  pruneStyles(cssAssets: Record<string, CssAsset>): Promise<void> {
+    return this.#queue(async () => {
+      const current = Object.values(cssAssets).map((asset) => path.join(this.#artifactDir, asset.cssRelPath));
+      const keep = new Set([...current, ...(await this.#baseArtifact()).styles]);
+      const stylesDir = path.join(this.#artifactDir, "styles");
+      await this.#removeOlder(stylesDir, (name) => name.endsWith(".css"), keep, Date.now() - this.#graceMs);
+    });
+  }
+
+  #queue(prune: () => Promise<void>): Promise<void> {
+    this.#pruning = this.#pruning.then(prune).catch((error: unknown) => {
+      this.#logger.verbose(`[dev-artifact] prune skipped: ${String(error)}`);
+    });
+    return this.#pruning;
+  }
+
+  async #removeOlder(dir: string, matches: (name: string) => boolean, keep: Set<string>, before: number) {
+    const names = await fs.readdir(dir).catch(() => [] as string[]);
+    let removed = 0;
+    for (const name of names) {
+      const file = path.join(dir, name);
+      if (!matches(name) || keep.has(file)) continue;
+      const stat = await fs.stat(file).catch(() => null);
+      if (!stat || stat.mtimeMs >= before) continue;
+      
+      if (
+        await fs.rm(file, { force: true }).then(
+          () => true,
+          () => false,
+        )
+      )
+        removed += 1;
+    }
+    if (removed > 0) this.#logger.verbose(`[dev-artifact] removed ${removed} superseded file(s) from ${dir}`);
+  }
+
+  async #baseArtifact(): Promise<{ pages: string[]; styles: string[] }> {
+    const text = await fs.readFile(path.join(this.#artifactDir, "base-artifact.json"), "utf8").catch(() => null);
+    const artifact = text
+      ? (JSON.parse(text) as { pagesBundlePath?: string; cssAssets?: Record<string, CssAsset> })
+      : null;
+    return {
+      pages: artifact?.pagesBundlePath ? [path.resolve(this.#artifactDir, artifact.pagesBundlePath)] : [],
+      styles: Object.values(artifact?.cssAssets ?? {}).map((asset) => path.join(this.#artifactDir, asset.cssRelPath)),
+    };
+  }
+}