@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.80

package/frontendBuild/index.ts

@@ -9,6 +9,7 @@ export * from "./cssImportResolver";
 export * from "./devChangePlanner";
 export * from "./devGeneratedIndexSync";
 export * from "./fontOptimizer";
+export * from "./fontPruner";
 export * from "./hmrChangeClassifier";
 export * from "./hmrWatcher";
 export * from "./pagesBundleBuilder";
@@ -19,7 +20,6 @@ export * from "./routesManifestArtifactSerializer";
 export * from "./sourceMtimeIndex";
 export * from "./ssrBaseArtifactBuilder";
 export * from "./styleContract";
-export * from "./styleGuard";
 export * from "./themeValidator";
 export * from "./vendorSpecifiers";
 export * from "./watchRootResolver";

package/frontendBuild/pagesBundleBuilder.ts

@@ -64,7 +64,7 @@ export class PagesBundleBuilder {
       define: this.#define(),
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
-        PagesBundleBuilder.createServerCssStubPlugin(),
+        PagesBundleBuilder.createCssStubPlugin(),
         PagesBundleBuilder.createServerUseClientFetchPlugin(),
         await createExternalizeFrameworkPlugin({ app: this.#app, extra: akanConfig.externalLibs }),
         akanConfig.barrelImports.length > 0
@@ -137,9 +137,9 @@ export class PagesBundleBuilder {
     };
   }
 
-  static createServerCssStubPlugin(): BunPlugin {
+  static createCssStubPlugin(): BunPlugin {
     return {
-      name: "akan-server-css-stub",
+      name: "akan-css-stub",
       setup(build) {
         build.onLoad({ filter: /\.css$/ }, () => ({
           contents: "",

package/frontendBuild/pagesEntrySourceGenerator.ts

@@ -1,7 +1,6 @@
-import fs from "node:fs";
 import path from "node:path";
-import ts from "typescript";
 import type { PageEntry } from "../artifact/implicitRootLayout";
+import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
 
 export class PagesEntrySourceGenerator {
   #pageEntries: PageEntry[];
@@ -22,101 +21,25 @@ export class PagesEntrySourceGenerator {
     return `export const pages = {\n${lines.join("\n")}\n};\n`;
   }
 
-  static generateStatic(pageEntries: PageEntry[]): string {
-    return new PagesEntrySourceGenerator(pageEntries).generateStatic();
+  static async generateStatic(pageEntries: PageEntry[]): Promise<string> {
+    return await new PagesEntrySourceGenerator(pageEntries).generateStatic();
   }
 
-  generateStatic(): string {
+  async generateStatic(): Promise<string> {
     const imports = this.#pageEntries.map(({ moduleAbsPath }, index) => {
       const specifier = PagesEntrySourceGenerator.#toImportSpecifier(moduleAbsPath);
       return `import * as page${index} from ${JSON.stringify(specifier)};`;
     });
-    const entries = this.#pageEntries.map(({ key, moduleAbsPath }, index) => {
-      const isAsyncDefault = PagesEntrySourceGenerator.#hasAsyncDefaultExport(moduleAbsPath);
-      return `  ${JSON.stringify(key)}: { loader: async () => page${index}, isAsyncDefault: ${isAsyncDefault} },`;
-    });
+    const entries = await Promise.all(
+      this.#pageEntries.map(async ({ key, moduleAbsPath }, index) => {
+        const isAsyncDefault = await AsyncDefaultExportDetector.detect(moduleAbsPath);
+        return `  ${JSON.stringify(key)}: { loader: async () => page${index}, isAsyncDefault: ${isAsyncDefault} },`;
+      }),
+    );
     return `${imports.join("\n")}\nexport const pages = {\n${entries.join("\n")}\n};\n`;
   }
+
   static #toImportSpecifier(moduleAbsPath: string): string {
     return path.resolve(moduleAbsPath).split(path.sep).join("/");
   }
-
-  static #hasAsyncDefaultExport(moduleAbsPath: string): boolean {
-    try {
-      const source = fs.readFileSync(path.resolve(moduleAbsPath), "utf8");
-      const sourceFile = ts.createSourceFile(
-        moduleAbsPath,
-        source,
-        ts.ScriptTarget.Latest,
-        true,
-        PagesEntrySourceGenerator.#scriptKind(moduleAbsPath),
-      );
-      return PagesEntrySourceGenerator.#sourceFileHasAsyncDefaultExport(sourceFile);
-    } catch {
-      return false;
-    }
-  }
-
-  static #sourceFileHasAsyncDefaultExport(sourceFile: ts.SourceFile): boolean {
-    const asyncBindings = new Map<string, boolean>();
-    let defaultIdentifier: string | null = null;
-
-    for (const statement of sourceFile.statements) {
-      if (ts.isFunctionDeclaration(statement)) {
-        if (PagesEntrySourceGenerator.#hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
-          return PagesEntrySourceGenerator.#hasModifier(statement, ts.SyntaxKind.AsyncKeyword);
-        }
-        if (statement.name) {
-          asyncBindings.set(
-            statement.name.text,
-            PagesEntrySourceGenerator.#hasModifier(statement, ts.SyntaxKind.AsyncKeyword),
-          );
-        }
-        continue;
-      }
-
-      if (ts.isVariableStatement(statement)) {
-        for (const declaration of statement.declarationList.declarations) {
-          if (!ts.isIdentifier(declaration.name)) continue;
-          asyncBindings.set(
-            declaration.name.text,
-            PagesEntrySourceGenerator.#isAsyncFunctionExpression(declaration.initializer),
-          );
-        }
-        continue;
-      }
-
-      if (ts.isExportAssignment(statement)) {
-        if (PagesEntrySourceGenerator.#isAsyncFunctionExpression(statement.expression)) return true;
-        if (ts.isIdentifier(statement.expression)) defaultIdentifier = statement.expression.text;
-        continue;
-      }
-
-      if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
-        const exportClause = statement.exportClause;
-        for (const specifier of exportClause.elements) {
-          if (specifier.name.text !== "default") continue;
-          defaultIdentifier = specifier.propertyName?.text ?? specifier.name.text;
-        }
-      }
-    }
-
-    return defaultIdentifier ? asyncBindings.get(defaultIdentifier) === true : false;
-  }
-
-  static #hasModifier(node: ts.Node, kind: ts.SyntaxKind): boolean {
-    return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) ?? false);
-  }
-
-  static #isAsyncFunctionExpression(node?: ts.Expression): boolean {
-    return Boolean(
-      node &&
-        (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
-        PagesEntrySourceGenerator.#hasModifier(node, ts.SyntaxKind.AsyncKeyword),
-    );
-  }
-
-  static #scriptKind(moduleAbsPath: string): ts.ScriptKind {
-    return moduleAbsPath.endsWith(".tsx") || moduleAbsPath.endsWith(".jsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
-  }
 }

package/frontendBuild/routeClientBuilder.ts

@@ -4,7 +4,7 @@ import type { BaseBuildArtifact, ClientManifest, SsrManifest } from "akanjs/serv
 import type { App } from "../commandDecorators";
 import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
 import { toClientReferencePath } from "../transforms/rscUseClientTransform";
-import type { ClientEntryDiscovery } from "./clientBuildTypes";
+import type { ClientBundleTarget, ClientEntryDiscovery } from "./clientBuildTypes";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
 import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
@@ -163,12 +163,11 @@ export class RouteClientBuilder {
   }
 
   async #buildSsrBundle(bootstrapEntries: BootstrapEntries) {
-    const externalOptions = RouteClientBuilder.resolveSsrClientExternalOptions(this.#command);
     return new ClientEntriesBundler({
       app: this.#app,
       entries: bootstrapEntries.buildEntries,
       plugins: [await createBarrelImportsPlugin(this.#app)],
-      ...externalOptions,
+      ...RouteClientBuilder.resolveSsrClientBundleOptions(this.#command),
       outputSubdir: "client-ssr",
       command: this.#command,
     }).bundle();
@@ -239,20 +238,28 @@ export class RouteClientBuilder {
     return { [Bun.resolveSync("akanjs/fetch", serverEntry)]: "akanjs/fetch" };
   }
 
-  static resolveSsrClientExternalOptions(command: "build" | "start"): {
+  /**
+   * `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.
+   */
+  static resolveSsrClientBundleOptions(command: "build" | "start"): {
+    target: ClientBundleTarget;
     external: readonly string[];
     externalSubpaths?: readonly string[];
     externalAliases?: Record<string, string>;
   } {
     if (command === "start") {
       return {
+        target: "bun",
         external: SSR_CLIENT_EXTERNALS,
         externalSubpaths: ["akanjs/fetch"],
         externalAliases: RouteClientBuilder.resolveSsrClientRuntimeAliases(),
       };
     }
 
-    return { external: SSR_CLIENT_ALIAS_EXTERNALS };
+    return { target: "bun", external: SSR_CLIENT_ALIAS_EXTERNALS };
   }
 
   static resolveAkanServerEntry(): string {

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -5,7 +5,7 @@ import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
 import type { App } from "../commandDecorators";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
-import { CssCompiler } from "./cssCompiler";
+import { CssCompiler, type ImportedStylesheet } from "./cssCompiler";
 import { FontOptimizer } from "./fontOptimizer";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { RouteClientBuilder } from "./routeClientBuilder";
@@ -77,6 +77,7 @@ export class SsrBaseArtifactBuilder {
       branches: [...akanConfig.branches],
       i18n: akanConfig.i18n,
       imageConfig: akanConfig.images,
+      web: akanConfig.web,
       deepLinkAssociations: Object.values(akanConfig.mobile.targets)
         .filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0)
         .map((target) => ({
@@ -110,7 +111,7 @@ export class SsrBaseArtifactBuilder {
     const ssrBundle = await new ClientEntriesBundler({
       app: this.#app,
       entries: [rscSegmentOutletEntry],
-      ...RouteClientBuilder.resolveSsrClientExternalOptions(this.#command),
+      ...RouteClientBuilder.resolveSsrClientBundleOptions(this.#command),
       outputSubdir: "client-ssr",
       command: this.#command,
     }).bundle();
@@ -192,7 +193,7 @@ export class SsrBaseArtifactBuilder {
         Object.entries(cssByBasePath).flatMap(([basePath, baseCssText]) => {
           const cssText = [baseCssText, optimizedFonts.css].filter(Boolean).join("\n");
           if (!cssText) return [];
-          return [this.#writeCssAsset(basePath, cssText)];
+          return [this.#writeCssAsset(basePath, cssText, cssCompiler.importedStylesheetsByBasePath[basePath] ?? [])];
         }),
       ),
     );
@@ -201,7 +202,7 @@ export class SsrBaseArtifactBuilder {
     return { cssCompiler, optimizedFonts, cssAssets };
   }
 
-  async #writeCssAsset(basePath: string, cssText: string) {
+  async #writeCssAsset(basePath: string, cssText: string, imported: ImportedStylesheet[]) {
     const cssAssetName = basePath || "root";
     const preparedCssText = await prepareCssAsset(this.#command, basePath, cssText);
     const cssHash = Bun.hash(`${basePath}\n${preparedCssText}`).toString(36);
@@ -210,7 +211,23 @@ export class SsrBaseArtifactBuilder {
       `/_akan/styles/${cssAssetName}-${cssHash}.css`,
     ];
     await Bun.write(path.join(this.#absArtifactDir, cssRelPath), preparedCssText);
+    SsrBaseArtifactBuilder.#warnDroppedImports(this.#app, cssRelPath, preparedCssText, imported);
     this.#app.verbose(`[base-artifact] wrote ${preparedCssText.length} bytes of CSS for ${basePath} -> ${cssRelPath}`);
     return [basePath, { cssUrl, cssRelPath }] as const;
   }
+
+  /**
+   * Checked against the file written here rather than against the compiled text, because this is the stylesheet
+   * `base-artifact.json` points at and therefore the only one an SSR render serves. A declaration can survive
+   * the compile and still be missing from the asset — a build that ships CSS to the CSR bundle and not to the
+   * server is indistinguishable, in the browser, from a theme that was never written.
+   */
+  static #warnDroppedImports(app: App, cssRelPath: string, css: string, imported: ImportedStylesheet[]) {
+    for (const { cssPath, declaredNames } of imported) {
+      if (declaredNames.length === 0 || declaredNames.some((name) => css.includes(`${name}:`))) continue;
+      app.logger.warn(
+        `[base-artifact] @import ${cssPath} declares ${declaredNames.length} custom propert${declaredNames.length === 1 ? "y" : "ies"} and none of them are in ${cssRelPath}`,
+      );
+    }
+  }
 }

package/frontendBuild/styleContract.ts

@@ -1,29 +1,23 @@
 /**
- * styleGuard + themeValidator 결과를 배선(build/dev/lint)이 공유하는 포맷으로 정리한다.
- * severity 사다리: style 위반은 severity==="error" 인 것만, theme 위반은 전부 차단(build/CI) 대상.
- * dev 는 이 결과를 경고로만 출력한다.
+ * Reports the style contract that `akan lint` enforces, in the shape build/dev/lint share.
+ *
+ * Only contrast lives here. The vocabulary closure — raw palette classes, arbitrary colors, dropped
+ * daisyUI slots, inline color literals, interpolated arbitrary values — is enforced by the grit plugins
+ * in `lint/*.grit` during the biome run, so it is not re-scanned. Contrast cannot be a lint rule at all:
+ * it is arithmetic over resolved token *values*, which no syntactic pattern can reach.
  */
-import type { StyleGuardViolation } from "./styleGuard";
 import type { ThemeContrastViolation } from "./themeValidator";
 
 export interface StyleContractViolations {
-  style: StyleGuardViolation[];
   theme: ThemeContrastViolation[];
 }
 
-export const countBlocking = (v: StyleContractViolations): number =>
-  v.style.filter((s) => s.severity === "error").length + v.theme.length;
+export const countBlocking = (violations: StyleContractViolations): number => violations.theme.length;
 
-export const formatStyleContract = (v: StyleContractViolations): string => {
-  const lines: string[] = [];
-  for (const s of v.style) {
-    lines.push(`  [${s.severity}] ${s.rule}  ${s.path}:${s.line}`);
-    lines.push(`      ${s.snippet}`);
-    lines.push(`      → ${s.suggestion}`);
-  }
-  for (const t of v.theme) {
-    lines.push(`  [error] contrast  ${t.scope}  ${t.pair} = ${t.ratio}:1 (min ${t.threshold}:1)`);
-    lines.push(`      → ${t.suggestion}`);
-  }
-  return lines.join("\n");
-};
+export const formatStyleContract = (violations: StyleContractViolations): string =>
+  violations.theme
+    .flatMap((theme) => [
+      `  [error] contrast  ${theme.scope}  ${theme.pair} = ${theme.ratio}:1 (min ${theme.threshold}:1)`,
+      `      → ${theme.suggestion}`,
+    ])
+    .join("\n");

package/frontendBuild/themeValidator.ts

@@ -1,13 +1,17 @@
 /**
- * themeValidator — 시맨틱 토큰 페어의 WCAG 콘트라스트 자동 검사 (의존성 0).
+ * WCAG contrast checking over the semantic token pairs. No dependencies, pure functions, and no akanjs
+ * runtime import — it has to run inside the lint path.
  *
- * 토큰 구조(`--x` ↔ `--x-foreground`)라서 가능해진 검사. AI 가 생성한 팔레트가 "안 읽히는 사이트"가
- * 되는 것을 원천 차단한다. akanjs 런타임을 import 하지 않는다 — 순수 함수만.
+ * The `--x` / `--x-foreground` pairing is what makes the check possible at all: it says which two values
+ * are going to end up on top of each other. That is the guard against a generated palette shipping a site
+ * nobody can read.
  *
- * 임계값(WCAG 2.1):
- *   - 본문/주요 표면 페어(background·primary·secondary·accent·neutral·card·popover): 4.5:1 (AA normal text)
- *   - 상태/보조 페어(info·success·warning·destructive·open·muted): 3:1 (UI 컴포넌트 / 큰 텍스트 / 보조 표면)
- * 현행 styles.css 기본 팔레트(light/dark)는 이 임계값을 모두 통과한다.
+ * Thresholds (WCAG 2.1):
+ *   - body and primary surfaces (background, primary, secondary, accent, neutral, card, popover): 4.5:1,
+ *     the AA floor for normal text
+ *   - status and secondary pairs (info, success, warning, destructive, open, muted): 3:1, the AA floor for
+ *     UI components and large text
+ * The shipped light/dark palette in styles.css clears all of them.
  */
 
 export interface ThemeContrastViolation {
@@ -42,13 +46,13 @@ const PAIRS: PairDef[] = [
   { base: "open", fg: "open-foreground", threshold: 3 },
 ];
 
-// 검사 대상 스코프. 그 외 셀렉터(.campaign-x 스코프 토큰 등)는 페어 검사에서 제외.
+// Only these scopes are paired up; tokens scoped to something else (`.campaign-x`, …) are left alone.
 const THEME_SCOPES = new Set([":root", '[data-theme="dark"]', '[data-theme="light"]']);
 
 export type ThemeTokensByScope = Record<string, Record<string, string>>;
 
 export class ThemeValidator {
-  /** CSS 문자열에서 토큰을 추출해 알려진 테마 스코프 전체를 검사한다. */
+  /** Extracts tokens from the css text and checks every scope it recognizes. */
   validate(css: string): ThemeContrastViolation[] {
     const tokensByScope = ThemeValidator.parseThemeTokens(css);
     const violations: ThemeContrastViolation[] = [];
@@ -67,7 +71,7 @@ export class ThemeValidator {
       if (!bg || !front) continue;
       const bgRgb = ThemeValidator.parseHex(bg);
       const fgRgb = ThemeValidator.parseHex(front);
-      if (!bgRgb || !fgRgb) continue; // var()/비-hex 값은 검사 불가 → 건너뜀
+      if (!bgRgb || !fgRgb) continue; // a var() or non-hex value has no ratio to compute
       const ratio = ThemeValidator.contrastRatio(bgRgb, fgRgb);
       if (ratio >= threshold) continue;
       violations.push({
@@ -77,20 +81,21 @@ export class ThemeValidator {
         foreground: front,
         ratio: Math.round(ratio * 100) / 100,
         threshold,
-        suggestion: `${scope}의 --${base}(${bg})와 --${fg}(${front}) 대비가 ${ratio.toFixed(2)}:1 로 최소 ${threshold}:1 미만입니다. 한쪽을 더 밝게/어둡게 조정해 대비를 확보하세요.`,
+        suggestion: `In ${scope}, --${base} (${bg}) against --${fg} (${front}) is ${ratio.toFixed(2)}:1, under the ${threshold}:1 minimum. Lighten or darken one of them until it clears.`,
       });
     }
     return violations;
   }
 
   /**
-   * `:root` / `[data-theme="…"]` 블록에서 `--token: value` 를 파싱한다. 그룹 셀렉터
-   * (`:root, [data-theme="dark"] { … }`)는 각 셀렉터에 동일 토큰을 분배. 동일 스코프 재등장 시 나중 값이 이긴다
-   * (프레임워크-먼저 / 앱-나중 순서로 넘기면 앱 override 가 반영됨).
+   * Reads `--token: value` out of `:root` / `[data-theme="…"]` blocks. A grouped selector
+   * (`:root, [data-theme="dark"] { … }`) distributes the same tokens to each selector, and a scope that
+   * appears twice keeps the later value — so passing framework css first and the app's second reflects the
+   * app's overrides.
    */
   static parseThemeTokens(css: string): ThemeTokensByScope {
     const result: ThemeTokensByScope = {};
-    // 중첩 없는 단순 규칙 블록만 매칭(@theme/@keyframes 등 at-rule 은 셀렉터에 @ 포함이라 제외).
+    // Flat rule blocks only; an at-rule (@theme, @keyframes) carries `@` in the selector and is skipped.
     const blockRe = /(?:^|})\s*([^{}@]+?)\s*\{([^{}]*)\}/g;
     for (const block of css.matchAll(blockRe)) {
       const selectors = block[1].split(",").map((s) => s.trim());
@@ -109,11 +114,11 @@ export class ThemeValidator {
   }
 
   static #normalizeScope(selector: string): string {
-    // 따옴표 정규화: [data-theme=dark] / [data-theme='dark'] → [data-theme="dark"]
+    // Quote normalization: [data-theme=dark] / [data-theme='dark'] -> [data-theme="dark"]
     return selector.replace(/\[data-theme=['"]?([\w-]+)['"]?\]/g, '[data-theme="$1"]').trim();
   }
 
-  /** #rgb / #rgba / #rrggbb / #rrggbbaa → [r,g,b] (alpha 무시). 비-hex 는 null. */
+  /** #rgb / #rgba / #rrggbb / #rrggbbaa -> [r,g,b], alpha ignored. Null for anything not hex. */
   static parseHex(value: string): [number, number, number] | null {
     const v = value.trim();
     if (!v.startsWith("#")) return null;

package/frontendBuild/vendorSpecifiers.ts

@@ -11,6 +11,7 @@ export const VENDOR_SPECIFIERS = [
   "akanjs/base",
   "akanjs/common",
   "akanjs/constant",
+  "akanjs/fetch",
 ] as const;
 
 export type VendorSpecifier = (typeof VENDOR_SPECIFIERS)[number];

package/incrementalBuilder/devWatchBatch.test.ts

@@ -22,27 +22,25 @@ describe("prepareDevWatchBatch", () => {
     expect(prepared.event.devPlan?.files).toEqual(prepared.files);
   });
 
-  test.each([
-    "common",
-    "srvkit",
-    "ui",
-    "webkit",
-  ])("keeps %s facet add/delete generated index in the same generation", (facet) => {
-    const root = "/repo";
-    const changedFile = `${root}/libs/shared/${facet}/tmpExample.ts`;
-    const generatedIndex = `${root}/libs/shared/${facet}/index.ts`;
-    const prepared = prepareDevWatchBatch({
-      generation: 20,
-      batch: { files: [changedFile], kinds: new Set(["code"]) },
-      indexSync: { changedFiles: [generatedIndex], errors: [] },
-      changePlanner: new DevChangePlanner({ workspaceRoot: root }),
-    });
+  test.each(["common", "srvkit", "ui", "webkit"])(
+    "keeps %s facet add/delete generated index in the same generation",
+    (facet) => {
+      const root = "/repo";
+      const changedFile = `${root}/libs/shared/${facet}/tmpExample.ts`;
+      const generatedIndex = `${root}/libs/shared/${facet}/index.ts`;
+      const prepared = prepareDevWatchBatch({
+        generation: 20,
+        batch: { files: [changedFile], kinds: new Set(["code"]) },
+        indexSync: { changedFiles: [generatedIndex], errors: [] },
+        changePlanner: new DevChangePlanner({ workspaceRoot: root }),
+      });
 
-    expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
-    expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
-    expect(prepared.event.devPlan?.roles).toContain("barrel");
-    expect(prepared.event.devPlan?.actions).toContain("sync-generated");
-  });
+      expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
+      expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
+      expect(prepared.event.devPlan?.roles).toContain("barrel");
+      expect(prepared.event.devPlan?.actions).toContain("sync-generated");
+    },
+  );
 
   test("marks failed generated index sync as an error generation", () => {
     const root = "/repo";

package/incrementalBuilder/devWatchBatch.ts

@@ -1,4 +1,4 @@
-import type { BuilderEvent, ChangeBatch } from "akanjs/server";
+import type { BuilderEvent, ChangeBatch, DevChangePlan } from "akanjs/server";
 import type { DevChangePlanner, GeneratedIndexSyncResult } from "../frontendBuild";
 
 export interface PrepareDevWatchBatchOptions {
@@ -12,6 +12,8 @@ export interface PreparedDevWatchBatch {
   files: string[];
   kinds: ("code" | "css" | "config")[];
   expandedBatch: ChangeBatch;
+  /** The same plan the event carries, where `devPlan` is optional — read it here, not off the event. */
+  devPlan: DevChangePlan;
   event: Extract<BuilderEvent, { type: "invalidate" }>;
   hasSyncErrors: boolean;
 }
@@ -35,13 +37,15 @@ export const prepareDevWatchBatch = ({
   });
 
   if (indexSync.errors.length > 0 && !devPlan.actions.includes("report-error")) {
-    devPlan.actions = [...devPlan.actions, "report-error"].sort();
+    const withReport: DevChangePlan["actions"] = [...devPlan.actions, "report-error"];
+    devPlan.actions = withReport.sort();
   }
 
   return {
     files,
     kinds,
     expandedBatch,
+    devPlan,
     event: { type: "invalidate", kinds, files, generation, devPlan },
     hasSyncErrors: indexSync.errors.length > 0,
   };

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -200,7 +200,7 @@ export class IncrementalBuilderHost {
     // one at a time, into the dev error page a recycle is supposed to be invisible to. `ready` the
     // field is deliberately untouched: `onExit` reads it to tell a planned exit from a boot failure.
     this.#status = "recycling";
-    this.logger.info(`recycling builder pid=${proc.pid} (${reason})`);
+    this.logger.debug(`recycling builder pid=${proc.pid} (${reason})`);
     this.#recycleTimer = setTimeout(() => {
       this.#recycleTimer = null;
       if (this.#proc !== proc) return;

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -185,7 +185,12 @@ class IncrementalBuilder {
     if (this.#shuttingDown) return;
     this.#shuttingDown = true;
     const started = Date.now();
-    this.#logger.info(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    this.#logger.debug(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    // Stopped before the drain, or a save landing mid-drain would enqueue a batch behind the queue tail
+    // this method already awaited — and `process.exit(0)` would cut that batch off partway through
+    // writing its artifacts. The replacement rebuilds every artifact from its boot build anyway, so the
+    // batch is not lost; a half-written one would be.
+    this.#watcher?.stop();
     if (this.#cssRebuildTimer) {
       // Only reachable if a css batch landed between the idle report and this request: the fresh
       // boot build recompiles css from scratch anyway, so dropping the debounce loses nothing.
@@ -200,7 +205,7 @@ class IncrementalBuilder {
     // flushed — a `css-updated` relayed milliseconds before this line would be dropped with no error
     // anywhere, leaving the backend serving the previous bundle. See `BuilderChannel`.
     const flushed = await BuilderChannel.drain();
-    this.#logger.info(
+    this.#logger.debug(
       `drained in ${Date.now() - started}ms${flushed ? ` after flushing ${flushed} ipc write(s)` : ""}; exiting for recycle`,
     );
     process.exit(0);
@@ -303,13 +308,12 @@ class IncrementalBuilder {
     //* them to the watcher so its verification scan does not read them back as a user edit and spend a
     //* second generation rebuilding identical content.
     await this.#watcher?.absorb([...autoImport.changedFiles, ...indexSync.changedFiles]);
-    const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
+    const { files, kinds, expandedBatch, devPlan, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
       batch,
       indexSync,
       changePlanner: this.#changePlanner,
     });
-    const devPlan = event.devPlan;
     this.#logger.verbose(
       `[hmr] batch generation=${generation} kinds=${kinds.join(",")} files=${files.length} generated=${indexSync.changedFiles.length} roles=${devPlan.roles.join(",") || "(none)"} actions=${devPlan.actions.join(",") || "(none)"}`,
     );

package/index.ts

@@ -22,19 +22,15 @@ export type * from "./applicationBuildRunner";
 export type * from "./applicationReleasePackager";
 export type * from "./applicationTestPreload";
 export type * from "./artifact";
-export type * from "./builder";
 export type * from "./capacitorApp";
 export type * from "./cloud";
 export type * from "./commandDecorators";
 export type * from "./createTunnel";
 export type * from "./dependencyScanner";
 export type * from "./executors";
-export type * from "./extractDeps";
 export type * from "./fileSys";
 export type * from "./frontendBuild";
-export type * from "./getCredentials";
 export type * from "./getDirname";
-export type * from "./getModelFileData";
 export type * from "./getRelatedCnsts";
 export type * from "./guideline";
 export type * from "./incrementalBuilder";
@@ -46,7 +42,6 @@ export type * from "./recipeScanner";
 export type * from "./scanInfo";
 export type * from "./selectModel";
 export type * from "./spinner";
-export type * from "./streamAi";
 export type * from "./transforms";
 export type * from "./typeChecker";
 export type * from "./types";

package/integration/devStabilityHarness.ts

@@ -118,20 +118,12 @@ export default config;
       ),
       this.writeFile(
         "env/env.client.ts",
-        `import { getEnv } from "akanjs/base";
-
-export const env = {
-  ...getEnv(),
-} as const;
+        `export const env = {} as const;
 `,
       ),
       this.writeFile(
         "env/env.server.ts",
-        `import { getEnv } from "akanjs/base";
-
-export const env = {
-  ...getEnv(),
-} as const;
+        `export const env = {} as const;
 `,
       ),
       this.writeFile(