@akanjs/devkit 3.0.0-alpha.10 → 3.0.0-alpha.101

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/sourceMtimeIndex.ts

@@ -377,7 +377,7 @@ export class SourceMtimeIndex {
     return !name || name.startsWith(".") || name === "node_modules";
   }
 
-  /** `WatchRootResolver` can return `apps/<app>/page` alongside `apps/`; walking both doubles the work. */
+  /** `WatchRootResolver` can return `apps/<app>/page` alongside `apps/<app>`; walking both doubles the work. */
   static #pruneNestedRoots(roots: string[]): string[] {
     const resolved = [...new Set(roots.map((root) => path.resolve(root)))].sort();
     return resolved.filter(

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")]);
+  });
+});