@akanjs/devkit 3.0.0-alpha.1 → 3.0.0-alpha.100

package/frontendBuild/precompressArtifacts.ts

@@ -1,26 +1,41 @@
 import fs from "node:fs";
 import path from "node:path";
+import zlib from "node:zlib";
 import type { App } from "../commandDecorators";
 
 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.
+ */
+const BROTLI_QUALITY_BY_EXT = { ".css": 11 } as const;
+const DEFAULT_BROTLI_QUALITY = 9;
+const GZIP_LEVEL = 9;
 
 export interface PrecompressArtifactsResult {
   files: number;
   inputBytes: number;
   outputBytes: number;
+  brotliBytes: number;
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  const roots = [path.join(app.dist.cwdPath, ".akan/artifact/client")];
-  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0 };
+  //* 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.
+  const roots = [
+    path.join(app.dist.cwdPath, ".akan/artifact/client"),
+    path.join(app.dist.cwdPath, ".akan/artifact/styles"),
+  ];
+  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0, brotliBytes: 0 };
 
   await Promise.all(roots.map((root) => precompressRoot(root, result)));
   if (result.files > 0) {
     app.verbose(
-      `[precompress] wrote ${result.files} gzip sidecars (${formatBytes(result.inputBytes)} -> ${formatBytes(
+      `[precompress] wrote ${result.files} sidecars (${formatBytes(result.inputBytes)} -> gzip ${formatBytes(
         result.outputBytes,
-      )})`,
+      )} / br ${formatBytes(result.brotliBytes)})`,
     );
   }
   return result;
@@ -32,16 +47,29 @@ 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 gz = Bun.gzipSync(toArrayBuffer(bytes));
-    await Bun.write(`${filePath}.gz`, gz);
+    const buffer = toArrayBuffer(bytes);
+    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)]);
     result.files += 1;
     result.inputBytes += bytes.byteLength;
     result.outputBytes += gz.byteLength;
+    result.brotliBytes += br.byteLength;
   }
 }
 
+function brotliCompress(buffer: ArrayBuffer, ext: string): Buffer {
+  const quality = BROTLI_QUALITY_BY_EXT[ext as keyof typeof BROTLI_QUALITY_BY_EXT] ?? DEFAULT_BROTLI_QUALITY;
+  return zlib.brotliCompressSync(buffer, {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: buffer.byteLength,
+    },
+  });
+}
+
 async function shouldPrecompress(filePath: string): Promise<boolean> {
-  if (filePath.endsWith(".gz")) return false;
+  if (filePath.endsWith(".gz") || filePath.endsWith(".br")) return false;
   if (!COMPRESSIBLE_EXTS.has(path.extname(filePath).toLowerCase())) return false;
   const file = Bun.file(filePath);
   if (!(await file.exists())) return false;

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";
@@ -33,6 +33,15 @@ export interface BuildRouteClientOptions {
   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 keeps one build per route and leaves this unset.
+   */
+  entries?: string[];
 }
 
 export interface BuildRouteClientResult {
@@ -61,6 +70,7 @@ export class RouteClientBuilder {
   #knownEntries: Set<string>;
   #command: "build" | "start";
   #discovery?: ClientEntryDiscovery;
+  #entries?: string[];
 
   constructor(options: BuildRouteClientOptions) {
     this.#app = options.app;
@@ -68,11 +78,13 @@ export class RouteClientBuilder {
     this.#knownEntries = options.knownEntries ?? new Set<string>();
     this.#command = options.command ?? "start";
     this.#discovery = options.discovery;
+    this.#entries = options.entries;
   }
 
   async build(): Promise<BuildRouteClientResult> {
-    const discovery = this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app));
-    const discovered = await discovery.discover(this.#seeds);
+    const discovered =
+      this.#entries ??
+      (await (this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app))).discover(this.#seeds));
     const entries = discovered.filter((e) => !this.#knownEntries.has(e));
     if (entries.length === 0) return this.#emptyResult(discovered);
 
@@ -151,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();
@@ -227,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")]);
+  });
+});

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;
+    }
+  }
 }