@akanjs/devkit 3.0.0-alpha.11 → 3.0.0-alpha.111

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/frontendBuild/watchRootResolver.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { WatchRootResolver } from "./watchRootResolver";
+
+const roots: string[] = [];
+
+const makeWorkspace = async (dirs: string[]) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-watch-roots-"));
+  roots.push(root);
+  await Promise.all(dirs.map((dir) => mkdir(path.join(root, dir), { recursive: true })));
+  return root;
+};
+
+const writeManifest = (workspaceRoot: string, scope: string, libDeps: unknown) =>
+  writeFile(
+    path.join(workspaceRoot, scope, scope.startsWith("apps/") ? "akan.app.json" : "akan.lib.json"),
+    JSON.stringify({ libDeps }),
+  );
+
+interface AppStub {
+  paths?: Record<string, string[]>;
+  libDeps?: string[] | null;
+}
+
+const makeApp = (workspaceRoot: string, name: string, { paths = {}, libDeps = null }: AppStub = {}) =>
+  ({
+    cwdPath: path.join(workspaceRoot, "apps", name),
+    workspace: { workspaceRoot },
+    getTsConfig: async () => ({ compilerOptions: { paths } }),
+    getScanInfo: () => (libDeps ? { type: "app", libDeps } : null),
+  }) as unknown as App;
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("WatchRootResolver", () => {
+  test("narrows the apps container to the app being served", async () => {
+    const workspaceRoot = await makeWorkspace(["apps/app1/page", "apps/app2/page", "libs/util"]);
+    const resolved = await new WatchRootResolver(
+      makeApp(workspaceRoot, "app1", { paths: { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] } }),
+    ).resolve();
+
+    expect(resolved).toContain(path.join(workspaceRoot, "apps/app1"));
+    expect(resolved).not.toContain(path.join(workspaceRoot, "apps"));
+    expect(resolved).not.toContain(path.join(workspaceRoot, "apps/app2"));
+  });
+
+  test("narrows the libs container to the app's own dependencies", async () => {
+    const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
+    const resolved = await new WatchRootResolver(
+      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] }, libDeps: ["util"] }),
+    ).resolve();
+
+    expect(resolved).toContain(path.join(workspaceRoot, "libs/util"));
+    expect(resolved).not.toContain(path.join(workspaceRoot, "libs"));
+    expect(resolved).not.toContain(path.join(workspaceRoot, "libs/shared"));
+  });
+
+  test("drops the libs container entirely when the app depends on no lib", async () => {
+    const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util"]);
+    await writeManifest(workspaceRoot, "apps/app1", []);
+    const resolved = await new WatchRootResolver(
+      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
+    ).resolve();
+
+    expect(resolved).toEqual([path.join(workspaceRoot, "apps/app1/page")]);
+  });
+
+  test("takes the transitive closure from the synced manifests when nothing scanned in-process", async () => {
+    const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared", "libs/unused"]);
+    await writeManifest(workspaceRoot, "apps/app1", ["shared"]);
+    await writeManifest(workspaceRoot, "libs/shared", ["util"]);
+    await writeManifest(workspaceRoot, "libs/util", []);
+    await writeManifest(workspaceRoot, "libs/unused", []);
+    const resolved = await new WatchRootResolver(
+      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
+    ).resolve();
+
+    expect(resolved).toContain(path.join(workspaceRoot, "libs/shared"));
+    expect(resolved).toContain(path.join(workspaceRoot, "libs/util"));
+    expect(resolved).not.toContain(path.join(workspaceRoot, "libs/unused"));
+  });
+
+  test("keeps the libs container whole when the app manifest is missing", async () => {
+    const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
+    const resolved = await new WatchRootResolver(
+      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
+    ).resolve();
+
+    expect(resolved).toContain(path.join(workspaceRoot, "libs"));
+  });
+
+  test("keeps the libs container whole when a dependency lib is unsynced", async () => {
+    const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
+    await writeManifest(workspaceRoot, "apps/app1", ["shared"]);
+    const resolved = await new WatchRootResolver(
+      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
+    ).resolve();
+
+    expect(resolved).toContain(path.join(workspaceRoot, "libs"));
+  });
+
+  test("resolves a package alias to its own directory, filename and glob stripped", async () => {
+    const workspaceRoot = await makeWorkspace(["apps/app1/page", "pkgs/akanjs/base"]);
+    const resolved = await new WatchRootResolver(
+      makeApp(workspaceRoot, "app1", {
+        paths: {
+          akanjs: ["./pkgs/akanjs/index.ts"],
+          "akanjs/*": ["./pkgs/akanjs/*"],
+          missing: ["./pkgs/nothing/index.ts"],
+        },
+      }),
+    ).resolve();
+
+    expect(resolved).toContain(path.join(workspaceRoot, "pkgs/akanjs"));
+    expect(resolved).not.toContain(path.join(workspaceRoot, "pkgs/nothing"));
+  });
+
+  test("always watches the app's page tree", async () => {
+    const workspaceRoot = await makeWorkspace(["apps/app1/page"]);
+    const resolved = await new WatchRootResolver(makeApp(workspaceRoot, "app1")).resolve();
+
+    expect(resolved).toEqual([path.join(workspaceRoot, "apps/app1/page")]);
+  });
+});

package/frontendBuild/watchRootResolver.ts

@@ -1,7 +1,25 @@
 import fs from "node:fs";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
 
+/**
+ * The directories one app's dev watcher follows, resolved from its tsconfig `paths`.
+ *
+ * Two aliases strip down to a workspace container rather than a package, and taking either verbatim puts
+ * code the app never imports under the watcher — where a save rebuilds, restarts and reloads it for
+ * nothing, and both builders rewrite the same generated barrels:
+ *
+ * - `@apps/*` becomes the `apps/` container. Apps are leaves of the workspace graph — never one another's
+ *   dependencies — so it is replaced by this app's own directory.
+ * - `@libs/*` becomes the `libs/` container. A lib is a dependency only if the app reaches it, so it is
+ *   replaced by the app's own lib dependencies, transitively. The set is resolved once, at watcher
+ *   install: a lib that becomes a dependency mid-session needs a fresh `akan start` anyway, because the
+ *   import that made it one also needs a `sync`.
+ *
+ * Failing to resolve that set keeps the container whole, because a wrong narrowing is a dev server that
+ * silently ignores edits.
+ */
 export class WatchRootResolver {
   #app: App;
 
@@ -11,6 +29,10 @@ export class WatchRootResolver {
 
   async resolve(): Promise<string[]> {
     const tsconfig = await this.#app.getTsConfig();
+    const appDir = path.resolve(this.#app.cwdPath);
+    const appsContainer = path.dirname(appDir);
+    const libsContainer = path.resolve(this.#app.workspace.workspaceRoot, "libs");
+    const libRoots = await this.#resolveLibRoots(libsContainer);
     const set = new Set<string>();
     set.add(path.resolve(`${this.#app.cwdPath}/page`));
     for (const targets of Object.values(tsconfig.compilerOptions.paths ?? {})) {
@@ -20,9 +42,52 @@ export class WatchRootResolver {
         // Strip the trailing filename and glob so we watch the package root dir.
         const cleaned = target.replace(/\/?\*+.*$/, "").replace(/\/[^/]+\.[^/]+$/, "");
         const resolved = path.resolve(this.#app.workspace.workspaceRoot, cleaned);
-        if (fs.existsSync(resolved)) set.add(resolved);
+        if (resolved === libsContainer && libRoots) {
+          for (const root of libRoots) set.add(root);
+          continue;
+        }
+        const root = resolved === appsContainer ? appDir : resolved;
+        if (fs.existsSync(root)) set.add(root);
       }
     }
     return [...set];
   }
+
+  async #resolveLibRoots(libsContainer: string): Promise<string[] | null> {
+    const libDeps = await this.#resolveLibDeps(libsContainer);
+    if (!libDeps) return null;
+    return libDeps.map((name) => path.join(libsContainer, name)).filter((dir) => fs.existsSync(dir));
+  }
+
+  async #resolveLibDeps(libsContainer: string): Promise<string[] | null> {
+    const scanInfo = this.#app.getScanInfo({ allowEmpty: true });
+    // Already transitive, and present whenever this runs in a process that scanned. The builder and the
+    // idle watcher run in processes that did not, so they take the manifests `scan` wrote instead.
+    if (scanInfo?.type === "app") return scanInfo.libDeps;
+    const direct = await WatchRootResolver.#readManifestLibDeps(path.join(this.#app.cwdPath, "akan.app.json"));
+    if (!direct) return null;
+    const closure = new Set<string>();
+    const queue = [...direct];
+    while (queue.length > 0) {
+      const name = queue.shift();
+      if (!name || closure.has(name)) continue;
+      closure.add(name);
+      const nested = await WatchRootResolver.#readManifestLibDeps(path.join(libsContainer, name, "akan.lib.json"));
+      // An unsynced lib's own dependencies are unknowable, so no root can be ruled out.
+      if (!nested) return null;
+      queue.push(...nested);
+    }
+    return [...closure];
+  }
+
+  static async #readManifestLibDeps(manifestPath: string): Promise<string[] | null> {
+    try {
+      const parsed = JSON.parse(await readFile(manifestPath, "utf8")) as { libDeps?: unknown };
+      if (!Array.isArray(parsed.libDeps)) return null;
+      return parsed.libDeps.filter((name): name is string => typeof name === "string" && name.length > 0);
+    } catch {
+      // Missing before the first sync, and unparseable while sync is mid-write.
+      return null;
+    }
+  }
 }

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

@@ -14,11 +14,25 @@ const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "build-status",
   "builder-metrics",
 ]);
+/**
+ * Where a dev child process writes. `"pipe"` is not only about keeping a TUI's frame clean: a Bun child
+ * that inherits the controlling terminal snapshots its termios at spawn and writes that snapshot back
+ * when it exits, so a builder spawned while something holds the terminal raw turns it raw again on the
+ * first recycle. See the XXX comment on `Spinner.oraOptions`.
+ */
+export type DevStdioMode = "inherit" | "pipe";
+
 interface IncrementalBuilderHostOptions {
   app: App;
   entry: string;
   env: Record<string, string>;
+  stdio?: DevStdioMode;
   onMessage: (message: BuilderMessage) => void;
+  /**
+   * Required when `stdio` is `"pipe"`: an undrained pipe fills and blocks the builder's next write.
+   * Text arrives as decoded chunks, not lines — a consumer that needs lines splits them itself.
+   */
+  onOutput?: (kind: "stdout" | "stderr", text: string) => void;
 }
 
 /**
@@ -63,7 +77,9 @@ export class IncrementalBuilderHost {
   app: App;
   ready = false;
   readonly #onMessage: (message: BuilderMessage) => void;
-  #proc: Bun.Subprocess<"ignore", "inherit", "inherit"> | null = null;
+  readonly #stdio: DevStdioMode;
+  readonly #onOutput: ((kind: "stdout" | "stderr", text: string) => void) | null;
+  #proc: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #status: IncrementalBuilderStatus = "stopped";
   #restartAttempts = 0;
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
@@ -83,11 +99,13 @@ export class IncrementalBuilderHost {
    */
   readonly #inFlight = new Map<number, "build-route" | "build-csr">();
   #startOptions: IncrementalBuilderStartOptions = {};
-  constructor({ app, entry, env, onMessage }: IncrementalBuilderHostOptions) {
+  constructor({ app, entry, env, stdio = "inherit", onMessage, onOutput }: IncrementalBuilderHostOptions) {
     this.app = app;
     this.entry = entry;
     this.env = env;
+    this.#stdio = stdio;
     this.#onMessage = onMessage;
+    this.#onOutput = onOutput ?? null;
   }
   get status() {
     return this.#status;
@@ -115,11 +133,11 @@ export class IncrementalBuilderHost {
     // the flag is what tells it to re-announce what it booted with.
     const afterRecycle = this.#spawnAfterRecycle;
     this.#spawnAfterRecycle = false;
-    let proc!: Bun.Subprocess<"ignore", "inherit", "inherit">;
+    let proc!: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe">;
     proc = Bun.spawn(["bun", this.entry], {
       cwd: this.app.cwdPath,
       env: { ...this.env, AKAN_WATCH: "1", ...(afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {}) },
-      stdio: ["ignore", "inherit", "inherit"],
+      stdio: ["ignore", this.#stdio, this.#stdio],
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
         if (!msg || typeof msg !== "object") return;
@@ -167,8 +185,25 @@ export class IncrementalBuilderHost {
       },
     });
     this.#proc = proc;
+    // Re-attached per spawn, not once per host: a recycle or a crash-restart brings new pipes.
+    if (this.#stdio === "pipe" && this.#onOutput) {
+      void this.#drain(proc.stdout as unknown as ReadableStream<Uint8Array> | undefined, "stdout");
+      void this.#drain(proc.stderr as unknown as ReadableStream<Uint8Array> | undefined, "stderr");
+    }
     this.logger.verbose(`builder spawned pid=${proc.pid} entry=${this.entry}${isRestart ? " restart=1" : ""}`);
   }
+  async #drain(stream: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
+    if (!stream) return;
+    const decoder = new TextDecoder();
+    try {
+      for await (const chunk of stream) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (text) this.#onOutput?.(kind, text);
+      }
+    } catch {
+      // The stream closes when the builder exits; nothing further to surface here.
+    }
+  }
   #scheduleRestart() {
     if (this.#manualStop || this.#restartTimer) return;
     this.#status = "restarting";
@@ -200,7 +235,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;
@@ -278,7 +313,15 @@ export class IncrementalBuilderHost {
     this.ready = false;
     this.#status = "stopped";
   }
-  static async create(app: App, env: Record<string, string>, onMessage: (message: BuilderMessage) => void) {
+  static async create(
+    app: App,
+    env: Record<string, string>,
+    onMessage: (message: BuilderMessage) => void,
+    {
+      stdio = "inherit",
+      onOutput,
+    }: { stdio?: DevStdioMode; onOutput?: (kind: "stdout" | "stderr", text: string) => void } = {},
+  ) {
     const candidates = [
       path.join(app.workspace.workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts"),
       path.join(
@@ -289,7 +332,8 @@ export class IncrementalBuilderHost {
       path.join(import.meta.dir, "incrementalBuilder.proc.ts"),
     ];
     for (const c of candidates)
-      if (await Bun.file(c).exists()) return new IncrementalBuilderHost({ app, entry: c, env, onMessage });
+      if (await Bun.file(c).exists())
+        return new IncrementalBuilderHost({ app, entry: c, env, stdio, onMessage, onOutput });
     throw new Error(`[cli] frontend builder entry not found; looked in: ${candidates.join(", ")}`);
   }
 }