@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/frontendBuild/hmrWatcher.ts

@@ -12,24 +12,12 @@ export interface WatcherOptions {
   debounceMs?: number;
   logger: Logger;
   onBatch: (batch: ChangeBatch) => void | Promise<void>;
-  /**
-   * Delay before re-checking mtimes for changes `fs.watch` never reported. Must clear Bun's ~200ms
-   * coalescing window, or a write late in the same window as a delivered event stays invisible.
-   */
+  /** Delay (ms, default 250) before the mtime re-check; must outlast Bun's ~200ms fs.watch coalescing window. */
   verifyDelayMs?: number;
 }
 
-/**
- * Recursive filesystem watcher with debounced batching. We deliberately keep
- * classification coarse (`code` / `css` / `config`) so the orchestrator can
- * decide whether a full rebuild-and-reload or a narrower action (e.g. CSS
- * hot-swap) is sufficient.
- *
- * Bun's event payloads are treated as a hint, not the answer: its recursive `fs.watch` reports about one
- * path per coalescing window and silently discards the rest, so what changed is resolved against a
- * `SourceMtimeIndex` instead (see that class for the measurements). Events still drive *when* to look,
- * which is what keeps this cheap — Bun does reliably deliver at least one event per window.
- */
+// Bun delivers at least one fs.watch event per coalescing window but drops the other paths, so events decide
+// when to look and the SourceMtimeIndex decides what changed.
 export class HmrWatcher {
   readonly #roots: string[];
   readonly #debounceMs: number;
@@ -38,7 +26,6 @@ export class HmrWatcher {
   readonly #logger: Logger;
   readonly #watchers: fs.FSWatcher[] = [];
   readonly #pending = new Map<string, Exclude<ChangeKind, "ignore">>();
-  /** Paths the watcher's own events named since the last batch — diagnostics only, see `#queue`. */
   readonly #hinted = new Set<string>();
   readonly #classifier = new HmrChangeClassifier();
   readonly #index: SourceMtimeIndex;
@@ -59,19 +46,12 @@ export class HmrWatcher {
     this.#index = new SourceMtimeIndex({ roots: this.#roots, classifier: this.#classifier });
   }
 
-  /**
-   * How many changes the mtime scan found that `fs.watch` never reported. Non-zero means this watcher is
-   * compensating for the Bun defect rather than the defect being absent, which is the number to watch if
-   * it is ever fixed upstream.
-   */
+  /** Changes the mtime scan found that fs.watch never reported; non-zero means it is compensating for Bun. */
   get unreportedChanges(): number {
     return this.#unreportedChanges;
   }
 
-  /**
-   * Watchers are installed before the baseline is taken, so an edit made during priming is reported by
-   * the event side even though the baseline already reflects it.
-   */
+  /** Installs the watchers before priming, so an edit made while priming is still reported by the event side. */
   async start(): Promise<void> {
     for (const root of this.#roots) {
       try {
@@ -88,8 +68,7 @@ export class HmrWatcher {
     }
     try {
       await this.#index.prime();
-      // Before the first batch, because a root that is unreadable at boot blinds the whole session and
-      // waiting for a save to surface it means waiting for a save that never rebuilds.
+      // At boot: edits under an unreadable root never rebuild, so no later save would surface it.
       this.#reportCoverageGaps();
       this.#logger.verbose(`[hmr] tracking ${this.#index.trackedFileCount} source files for change verification`);
     } catch (err) {
@@ -112,23 +91,14 @@ export class HmrWatcher {
     }
   }
 
-  /**
-   * Adopt writes the batch handler made itself (regenerated barrels, inserted imports) so the
-   * verification scan does not spend a second generation rebuilding content this one already consumed.
-   */
+  /** Baseline the batch handler's own writes so the verification scan does not rebuild them a second time. */
   async absorb(paths: string[]): Promise<void> {
     if (paths.length === 0) return;
     await this.#index.absorb(paths);
   }
 
-  /**
-   * An event says only *that* something happened, never reliably *what*. So with a baseline in hand it is
-   * used purely to decide when to look, and the mtime scan names the files.
-   *
-   * Taking the payload as well would double-report: Bun does deliver a real event for some of the paths a
-   * scan has already emitted, and adding it back here produced a second batch for the same save — one more
-   * generation and one more build for no change.
-   */
+  // Once primed, a payload only schedules a scan: Bun also delivers events for paths the scan already emitted,
+  // so adding payloads to the batch double-reports a save.
   #queue(abs: string): void {
     const kind = this.#classifier.classify(abs);
     if (!this.#index.primed) {
@@ -138,15 +108,12 @@ export class HmrWatcher {
       this.#scheduleFlush();
       return;
     }
-    // An ignored path still means a window happened. That is the shape of the original bug — every build
-    // ends in a burst under `.akan/`, and the burst is what Bun reports instead of the save beside it.
-    // Rescheduling on each one folds a build's whole burst into a single scan once it goes quiet.
+    // An ignored path (a build's .akan/ burst) still marks a coalescing window that may hide a real save.
     if (kind === "ignore") {
       this.#scheduleVerify();
       return;
     }
-    // Recorded only so `unreportedChanges` can tell which changes the events did name; it never decides
-    // what is in a batch.
+    // Diagnostics only, for `unreportedChanges`; it never decides what is in a batch.
     this.#hinted.add(abs);
     this.#scheduleFlush();
   }
@@ -186,10 +153,6 @@ export class HmrWatcher {
     }
   }
 
-  /**
-   * Fold in everything the mtime index has seen change, since a delivered event names at most one of the
-   * paths that moved in its window.
-   */
   async #mergeDetectedChanges(): Promise<void> {
     const detected = await this.#index.collectChanges().catch((err) => {
       this.#logger.error(`[hmr] mtime scan failed: ${(err as Error).message}`);
@@ -205,8 +168,6 @@ export class HmrWatcher {
     }
     if (unreported === 0) return;
     this.#unreportedChanges += unreported;
-    // Once at info, so it is visible that the watcher is compensating rather than the defect being absent;
-    // per-batch detail stays at verbose because a save-all trips this on every save.
     if (!this.#reportedCompensating) {
       this.#reportedCompensating = true;
       this.#logger.verbose(
@@ -218,13 +179,6 @@ export class HmrWatcher {
     );
   }
 
-  /**
-   * Say so when part of the tree cannot be read, and say so again when it recovers.
-   *
-   * A blind spot here means edits under that path are not rebuilt at all, which is indistinguishable from
-   * the dev server being broken. Keyed on the gap list itself so a persistent failure logs once rather than
-   * once per save, while a *different* gap appearing still gets its own line.
-   */
   #reportCoverageGaps(): void {
     const gaps = this.#index.coverageGaps;
     const key = gaps
@@ -247,10 +201,7 @@ export class HmrWatcher {
     );
   }
 
-  /**
-   * One scan after the coalescing window closes. A write that lands in the same window as an already
-   * delivered event produces no further event of its own, so nothing else would ever look for it.
-   */
+  // A write in the same window as a delivered event raises no event of its own, so one scan follows each window.
   #scheduleVerify(): void {
     if (this.#stopped || this.#verifyDelayMs <= 0) return;
     if (this.#verifyTimer) clearTimeout(this.#verifyTimer);
@@ -260,16 +211,8 @@ export class HmrWatcher {
     }, this.#verifyDelayMs);
   }
 
-  /**
-   * Terminates rather than looping: a scan that finds nothing schedules nothing, and the build writes its
-   * artifacts under `.akan/` — which the classifier ignores — while codegen writes are content-guarded,
-   * so a rebuild does not move a tracked mtime.
-   *
-   * The one case that does schedule another is a directory the index could not date reliably (Linux stamps
-   * directory mtimes on a 1ms clock, see `SourceMtimeIndex`). That still terminates: the next scan is
-   * `verifyDelayMs` later, by which point the timestamp has settled unless something is writing to that
-   * directory right now — in which case looking again is the right answer anyway.
-   */
+  // Terminates: build output lands in ignored .akan/ and codegen writes are content-guarded, so a rebuild moves no
+  // tracked mtime; only an unsettled directory schedules another scan.
   async #verify(): Promise<void> {
     if (this.#stopped || this.#flushing) return;
     await this.#mergeDetectedChanges();

package/frontendBuild/pagesBundleBuilder.ts

@@ -5,18 +5,15 @@ import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
 import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
 import { createExternalizeFrameworkPlugin } from "../transforms/externalizeFrameworkPlugin";
+import { loaderFor } from "../transforms/moduleSyntax";
 import { transformUseClient } from "../transforms/rscUseClientTransform";
 import { createUseClientBundlePlugin } from "../transforms/useClientBundlePlugin";
+import { bundleDefine } from "./bundleDefine";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
 export interface BuildPagesBundleResult {
-  /** Absolute path to the emitted `pages-[hash].js`. */
   bundlePath: string;
-  /**
-   * Monotonic build identifier. Bun.build emits a fresh filename whenever
-   * any input changes, but importers still benefit from a `?v=<buildId>`
-   * query-string cache bust — `buildId` is that value.
-   */
+  /** Cache-bust value for `import(bundlePath?v=<buildId>)`. */
   buildId: number;
   splitting: boolean;
   entryBytes: number;
@@ -27,10 +24,6 @@ export interface BuildPagesBundleResult {
 
 const VIRTUAL_PAGES_ENTRY = "akan-pages-entry";
 
-/**
- * Build the server-side pages bundle. The RSC worker loads the result with
- * `await import(bundlePath?v=buildId)`.
- */
 export class PagesBundleBuilder {
   #app: App;
   #command: "build" | "start";
@@ -61,7 +54,7 @@ export class PagesBundleBuilder {
         chunk: "chunks/[name]-[hash].[ext]",
         asset: "assets/[name]-[hash].[ext]",
       },
-      define: this.#define(),
+      define: bundleDefine(this.#app, this.#command, "ssr"),
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
         PagesBundleBuilder.createCssStubPlugin(),
@@ -110,17 +103,6 @@ export class PagesBundleBuilder {
     return process.env.AKAN_SERVER_PAGES_SPLITTING === "1";
   }
 
-  #define(): Record<string, string> {
-    const nodeEnv = this.#command === "build" ? "production" : (process.env.NODE_ENV ?? "development");
-    return {
-      "process.env.NODE_ENV": JSON.stringify(nodeEnv),
-      "process.env.AKAN_PUBLIC_RENDER_ENV": JSON.stringify("ssr"),
-      ...Object.fromEntries(
-        Object.entries(this.#app.getPublicEnv()).map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
-      ),
-    };
-  }
-
   static createPagesEntryPlugin(source: string): BunPlugin {
     return {
       name: "akan-pages-entry",
@@ -176,10 +158,3 @@ export class PagesBundleBuilder {
       );
   }
 }
-
-function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-  if (absPath.endsWith(".tsx")) return "tsx";
-  if (absPath.endsWith(".jsx")) return "jsx";
-  if (absPath.endsWith(".ts")) return "ts";
-  return "js";
-}

package/frontendBuild/precompressArtifacts.ts

@@ -2,17 +2,15 @@ import fs from "node:fs";
 import path from "node:path";
 import zlib from "node:zlib";
 import type { App } from "../commandDecorators";
+import { FontPruner } from "./fontPruner";
 
 const COMPRESSIBLE_EXTS = new Set([".css", ".html", ".js", ".json", ".svg"]);
 const MIN_COMPRESS_BYTES = 1024;
-/**
- * Quality 11 is roughly 100x slower than gzip, so it is spent only where it pays: there is one CSS asset
- * per basePath and it is the largest single file the app ships, worth ~20% over gzip for ~0.2s. Raising the
- * several hundred JS chunks from 9 to 11 costs ~12s of build time to save a few hundred KB, so they stay at 9.
- */
+// Brotli 11 is ~100x slower than gzip: worth it for the one CSS asset per basePath, not for hundreds of JS chunks.
 const BROTLI_QUALITY_BY_EXT = { ".css": 11 } as const;
 const DEFAULT_BROTLI_QUALITY = 9;
 const GZIP_LEVEL = 9;
+const { formatBytes } = FontPruner;
 
 export interface PrecompressArtifactsResult {
   files: number;
@@ -22,8 +20,7 @@ export interface PrecompressArtifactsResult {
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  //* styles too: WebRouter serves both prefixes through the same sidecar-aware #fileResponse, and the
-  //* one CSS asset per basePath is the largest uncompressed payload the app ships.
+  //* WebRouter serves client/ and styles/ through the same sidecar-aware #fileResponse.
   const roots = [
     path.join(app.dist.cwdPath, ".akan/artifact/client"),
     path.join(app.dist.cwdPath, ".akan/artifact/styles"),
@@ -47,7 +44,7 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
   for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
     if (!(await shouldPrecompress(filePath))) continue;
     const bytes = await Bun.file(filePath).bytes();
-    const buffer = toArrayBuffer(bytes);
+    const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
     const gz = Bun.gzipSync(buffer, { level: GZIP_LEVEL });
     const br = brotliCompress(buffer, path.extname(filePath).toLowerCase());
     await Promise.all([Bun.write(`${filePath}.gz`, gz), Bun.write(`${filePath}.br`, br)]);
@@ -75,13 +72,3 @@ async function shouldPrecompress(filePath: string): Promise<boolean> {
   if (!(await file.exists())) return false;
   return file.size >= MIN_COMPRESS_BYTES;
 }
-
-function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
-  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
-}
-
-function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes}B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
-}

package/frontendBuild/routeClientBuilder.ts

@@ -3,20 +3,12 @@ import path from "node:path";
 import type { BaseBuildArtifact, ClientManifest, SsrManifest } from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
-import { toClientReferencePath } from "../transforms/rscUseClientTransform";
+import { scanUseClientExports, toClientReferencePath } from "../transforms/rscUseClientTransform";
 import type { ClientBundleTarget, ClientEntryDiscovery } from "./clientBuildTypes";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
 import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
 
-const SSR_CLIENT_EXTERNALS = [
-  "react",
-  "react-dom",
-  "react-dom/client",
-  "react/jsx-runtime",
-  "react/jsx-dev-runtime",
-  "akanjs/fetch",
-] as const;
 const SSR_CLIENT_ALIAS_EXTERNALS = [
   "react",
   "react-dom",
@@ -24,47 +16,28 @@ const SSR_CLIENT_ALIAS_EXTERNALS = [
   "react/jsx-runtime",
   "react/jsx-dev-runtime",
 ] as const;
+const SSR_CLIENT_EXTERNALS = [...SSR_CLIENT_ALIAS_EXTERNALS, "akanjs/fetch"] as const;
 
 export interface BuildRouteClientOptions {
   app: App;
   seeds: string[];
-  /**
-   * Seeds of every route, so a build that has to run at all bundles the whole app's client entries.
-   *
-   * A page loads entries first built for other routes, and entries from two `Bun.build` runs each carry
-   * their own copy of every app and lib module — one page evaluated a lib's module-scope registration
-   * twice. The whole app costs about what one route did, since every entry already imports the client
-   * barrel, and content-hashed chunk names keep unchanged chunks at the URLs the browser already holds.
-   */
+  /** Every route's seeds: a build that runs at all bundles the whole app, since two builds each copy shared modules. */
   graphSeeds?: string[];
   artifact: BaseBuildArtifact;
   knownEntries?: Set<string>;
   routeId?: string;
   command?: "build" | "start";
   discovery?: ClientEntryDiscovery;
-  /**
-   * Client entries resolved by the caller, which skips discovery and bundles exactly this list.
-   *
-   * `AllRoutesBuilder` passes every route's entries at once so they share one `Bun.build`. Chunk
-   * splitting is scoped to a single invocation, so a dependency reachable from entries spread across
-   * several invocations is emitted once per invocation — mermaid landed in `apps/akan` four times that
-   * way. Dev passes `graphSeeds` instead, for the same reason.
-   */
+  /** Pre-resolved client entries: skips discovery and bundles exactly this list. */
   entries?: string[];
 }
 
 export interface BuildRouteClientResult {
-  /** Newly-emitted manifest rows keyed by `${absEntry}#${exportName}`, for every entry this build bundled. */
   manifestDelta: ClientManifest;
-  /** Newly-emitted ssrManifest rows keyed by entry URL. */
   ssrManifestDelta: SsrManifest;
-  /** Absolute paths of the `"use client"` leaves this build added. */
   newEntries: string[];
-  /** Absolute paths of all `"use client"` leaves discovered from this route's seeds. */
   discoveredEntries?: string[];
-  /** Absolute source files included in the browser bundles for this route's bundled entries. */
   clientDeps: string[];
-  /** Absolute source files included in the browser bundle, grouped by original client entry. */
   clientDepsByEntry?: Record<string, string[]>;
 }
 
@@ -223,16 +196,7 @@ export class RouteClientBuilder {
   }
 
   async #scanExportNames(absEntry: string): Promise<string[]> {
-    const source = await Bun.file(absEntry).text();
-    const transpiler = new Bun.Transpiler({ loader: this.#loaderFor(absEntry) });
-    return transpiler.scan(source).exports;
-  }
-
-  #loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-    if (absPath.endsWith(".tsx")) return "tsx";
-    if (absPath.endsWith(".jsx")) return "jsx";
-    if (absPath.endsWith(".ts")) return "ts";
-    return "js";
+    return scanUseClientExports(await Bun.file(absEntry).text(), absEntry, this.#app.workspace.workspaceRoot);
   }
 
   static normalizeNamedDefaultFunctionForFastRefresh(source: string): string | null {
@@ -255,12 +219,8 @@ export class RouteClientBuilder {
     return { [Bun.resolveSync("akanjs/fetch", serverEntry)]: "akanjs/fetch" };
   }
 
-  /**
-   * `target: "bun"` is load-bearing: these chunks are `await import()`-ed by the SSR renderer, so a dependency
-   * resolved through its `browser` export condition can touch `document` at module scope and throw mid-render,
-   * degrading the whole document to client rendering. Bun's `conditions` only adds to the target's defaults —
-   * `browser` still wins — so the target itself has to say server.
-   */
+  // `target: "bun"` is load-bearing: a `browser` export condition can touch `document` at module scope mid-SSR, and
+  // Bun's `conditions` only add to the target's defaults, so the target itself must say server.
   static resolveSsrClientBundleOptions(command: "build" | "start"): {
     target: ClientBundleTarget;
     external: readonly string[];

package/frontendBuild/routesManifestArtifactSerializer.ts

@@ -1,5 +1,5 @@
-import path from "node:path";
-import type { RoutesManifest, SsrManifestEntry } from "akanjs/server";
+import type { RoutesManifest } from "akanjs/server";
+import { RoutesManifestStore } from "akanjs/server/artifact/routesManifestStore";
 
 export type SerializedRoutesManifest = Omit<RoutesManifest, "knownEntries"> &
   Partial<Pick<RoutesManifest, "knownEntries">>;
@@ -11,7 +11,7 @@ export class RoutesManifestArtifactSerializer {
 
   constructor(manifest: RoutesManifest, artifactDir: string, options: { production?: boolean } = {}) {
     this.#manifest = manifest;
-    this.#artifactDir = path.resolve(artifactDir);
+    this.#artifactDir = artifactDir;
     this.#production = options.production ?? false;
   }
 
@@ -24,39 +24,8 @@ export class RoutesManifestArtifactSerializer {
   }
 
   serialize(): SerializedRoutesManifest {
-    const serialized: SerializedRoutesManifest = {
-      ...this.#manifest,
-      knownEntries: this.#manifest.knownEntries.map((entry) => this.#serializeArtifactPath(entry)),
-    };
+    const serialized: SerializedRoutesManifest = RoutesManifestStore.serialize(this.#manifest, this.#artifactDir);
     if (this.#production) delete serialized.knownEntries;
-    return {
-      ...serialized,
-      clientManifest: Object.fromEntries(
-        Object.entries(this.#manifest.clientManifest).map(([key, row]) => [this.#serializeArtifactPath(key), row]),
-      ),
-      ssrManifest: {
-        ...this.#manifest.ssrManifest,
-        moduleMap: Object.fromEntries(
-          Object.entries(this.#manifest.ssrManifest.moduleMap).map(([entryUrl, byName]) => [
-            entryUrl,
-            Object.fromEntries(
-              Object.entries(byName).map(([name, entry]) => [
-                name,
-                {
-                  ...entry,
-                  id: this.#serializeArtifactPath(entry.id),
-                  chunks: entry.chunks.map((chunk) => this.#serializeArtifactPath(chunk)),
-                } satisfies SsrManifestEntry,
-              ]),
-            ),
-          ]),
-        ),
-      },
-    };
-  }
-
-  #serializeArtifactPath(artifactPath: string): string {
-    if (!path.isAbsolute(artifactPath)) return artifactPath;
-    return path.relative(this.#artifactDir, artifactPath).split(path.sep).join("/");
+    return serialized;
   }
 }