@akanjs/devkit 3.0.0-alpha.70 → 3.0.0-alpha.72

package/executors.ts

@@ -690,7 +690,30 @@ export class Executor {
         Object.entries(options.dict ?? {}).map(([key, value]) => [capitalize(key), capitalize(value)]),
       ),
     };
-    return this._applyTemplate({ ...options, dict });
+    const fileContents = await this._applyTemplate({ ...options, dict });
+    await this.#formatAppliedTemplate(fileContents);
+    return fileContents;
+  }
+
+  /**
+   * A template emits identifiers it cannot sort. `import { fetch, Task, usePage }` is correctly ordered for
+   * a model named Task and wrong for one named Zoo, and `organizeImports` fails `biome check` — so a
+   * scaffold that is not formatted on the way out is red for most model names, whatever the template says.
+   *
+   * Best-effort: `create-akan-workspace` scaffolds before `bun install`, so there is no local Biome binary
+   * and often no config above the target yet. An unformatted file is a lint fix; a failed scaffold is not.
+   */
+  async #formatAppliedTemplate(fileContents: FileContent[]) {
+    const filePaths = fileContents
+      .map((fileContent) => fileContent.filePath)
+      .filter((filePath) => filePath.endsWith(".ts") || filePath.endsWith(".tsx"));
+    if (filePaths.length === 0) return;
+    try {
+      const { fixed } = await this.getLinter().fixFiles(filePaths);
+      if (fixed.length > 0) this.logger.verbose(`Formatted ${fixed.length} scaffolded file(s)`);
+    } catch (err) {
+      this.logger.verbose(`Skipped formatting scaffolded files: ${err instanceof Error ? err.message : String(err)}`);
+    }
   }
   // Async so `typescript` (~65MB resident) is loaded only by the commands that actually typecheck,
   // not by every process that imports an executor. `typeCheckAsync` below runs in a subprocess and
@@ -913,9 +936,10 @@ export class WorkspaceExecutor extends Executor {
     return await getDirs(basePath);
   }
   async commit(message: string, { init = false, add = true }: { init?: boolean; add?: boolean } = {}) {
-    if (init) await this.exec(`git init --quiet`);
-    if (add) await this.exec(`git add .`);
-    await this.exec(`git commit --quiet -m "${message}"`);
+    if (init) await this.spawn("git", ["init", "--quiet"]);
+    if (add) await this.spawn("git", ["add", "."]);
+    // Argument vector, not a shell string: a message carrying a double quote breaks the interpolated form.
+    await this.spawn("git", ["commit", "--quiet", "-m", message]);
   }
   async #getDirHasFile(basePath: string, targetFilename: string) {
     const AVOID_DIRS = ["node_modules", "dist", "public", "webkit"];
@@ -1369,7 +1393,7 @@ export class AppExecutor extends SysExecutor {
       //* generated against and typechecked. Drop the cache so the build phases re-read it without them.
       this.#excludeDevOnlyPages = true;
       this.#pageKeys = null;
-      if (await this.exists(this.dist.cwdPath)) await this.dist.exec(`rm -rf ${this.dist.cwdPath}`);
+      await this.dist.removeDir(this.dist.cwdPath);
       await Promise.all([this.dist.mkdir("private"), this.dist.mkdir("public")]);
       //* Lib assets are symlinks in the app dir (see syncAssets). dist is the docker build context and the
       //* release tarball root, neither of which follows a link out of itself, so materialize them here.

package/fileEditor.ts

@@ -1,23 +1,23 @@
 export class FileEditor {
-  private filePath: string;
-  private content: string;
+  #filePath: string;
+  #content: string;
 
   private constructor(filePath: string, content: string) {
-    this.filePath = filePath;
-    this.content = content;
+    this.#filePath = filePath;
+    this.#content = content;
   }
 
   static async create(filePath: string): Promise<FileEditor> {
     try {
       const content = await Bun.file(filePath).text();
       return new FileEditor(filePath, content);
-    } catch (error) {
+    } catch (_error) {
       throw new Error(`Failed to read file: ${filePath}`);
     }
   }
 
   find(pattern: string | RegExp): number {
-    const lines = this.content.split("\n");
+    const lines = this.#content.split("\n");
     const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
 
     for (let i = 0; i < lines.length; i++) {
@@ -30,7 +30,7 @@ export class FileEditor {
   }
 
   findAll(pattern: string | RegExp): number[] {
-    const lines = this.content.split("\n");
+    const lines = this.#content.split("\n");
     const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
     const matches: number[] = [];
 
@@ -50,9 +50,9 @@ export class FileEditor {
       throw new Error(`Pattern not found: ${pattern}`);
     }
 
-    const lines = this.content.split("\n");
+    const lines = this.#content.split("\n");
     lines.splice(lineIndex + 1, 0, data);
-    this.content = lines.join("\n");
+    this.#content = lines.join("\n");
 
     return this;
   }
@@ -64,43 +64,43 @@ export class FileEditor {
       throw new Error(`Pattern not found: ${pattern}`);
     }
 
-    const lines = this.content.split("\n");
+    const lines = this.#content.split("\n");
     lines.splice(lineIndex, 0, data);
-    this.content = lines.join("\n");
+    this.#content = lines.join("\n");
 
     return this;
   }
 
   replace(pattern: string | RegExp, replacement: string): this {
     const regex = typeof pattern === "string" ? new RegExp(pattern, "g") : pattern;
-    this.content = this.content.replace(regex, replacement);
+    this.#content = this.#content.replace(regex, replacement);
     return this;
   }
 
   append(data: string): this {
-    this.content += `\n${data}`;
+    this.#content += `\n${data}`;
     return this;
   }
 
   prepend(data: string): this {
-    this.content = `${data}\n${this.content}`;
+    this.#content = `${data}\n${this.#content}`;
     return this;
   }
 
   async save(): Promise<void> {
     try {
-      await Bun.write(this.filePath, this.content);
-    } catch (error) {
-      throw new Error(`Failed to save file: ${this.filePath}`);
+      await Bun.write(this.#filePath, this.#content);
+    } catch (_error) {
+      throw new Error(`Failed to save file: ${this.#filePath}`);
     }
   }
 
   getContent(): string {
-    return this.content;
+    return this.#content;
   }
 
   setContent(content: string): this {
-    this.content = content;
+    this.#content = content;
     return this;
   }
 }

package/frontendBuild/autoImportSync.test.ts

@@ -355,3 +355,61 @@ describe("AutoImportSync.syncForBatch", () => {
     expect(await readFile(indexFile, "utf8")).not.toContain("@libs/shared/client");
   });
 });
+
+describe("AutoImportSync — scope", () => {
+  const writeAt = async (root: string, rel: string, source: string) => {
+    const abs = path.join(root, rel);
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeFile(abs, source);
+    return abs;
+  };
+
+  // `lib/__lib/` is generated and gitignored: `akan sync` rewrites it, which is also what makes the
+  // watcher hand it to the syncer, so an edit there is churn that the next sync discards.
+  test("leaves the generated lib/__lib stubs alone and still syncs lib/__scalar", async () => {
+    const root = await makeTempRoot();
+    const needsImport = "export class A {\n  count = field(Int);\n}\n";
+    const generated = await writeAt(root, "libs/shared/lib/__lib/lib.constant.ts", needsImport);
+    const scalar = await writeAt(root, "libs/shared/lib/__scalar/money/money.constant.ts", needsImport);
+
+    const result = await new AutoImportSync({ workspaceRoot: root }).syncForBatch([generated, scalar]);
+
+    expect(result.errors).toEqual([]);
+    expect(result.changedFiles).toEqual([scalar]);
+    expect(await readFile(generated, "utf8")).toBe(needsImport);
+    expect(await readFile(scalar, "utf8")).toContain('import { Int } from "akanjs/base";');
+  });
+
+  // The transform is pure and the write is conditional on a difference, so a second pass over its own
+  // output writes nothing — without that the watcher would re-fire on the syncer's own edit.
+  test("a second pass over its own output changes nothing", async () => {
+    const root = await makeTempRoot();
+    const file = await writeAt(
+      root,
+      "libs/shared/lib/task/task.constant.ts",
+      "export class A {\n  count = field(Int);\n}\n",
+    );
+    const sync = new AutoImportSync({ workspaceRoot: root });
+
+    expect((await sync.syncForBatch([file])).changedFiles).toEqual([file]);
+    const afterFirst = await readFile(file, "utf8");
+    expect((await sync.syncForBatch([file])).changedFiles).toEqual([]);
+    expect(await readFile(file, "utf8")).toBe(afterFirst);
+  });
+
+  // One try/catch per file: a file that cannot be read is reported and the rest of the batch still runs.
+  test("a failing file is reported without abandoning the batch", async () => {
+    const root = await makeTempRoot();
+    const missing = path.join(root, "libs/shared/lib/task/gone.constant.ts");
+    const good = await writeAt(
+      root,
+      "libs/shared/lib/task/task.constant.ts",
+      "export class A {\n  count = field(Int);\n}\n",
+    );
+
+    const result = await new AutoImportSync({ workspaceRoot: root }).syncForBatch([missing, good]);
+
+    expect(result.changedFiles).toEqual([good]);
+    expect(result.errors).toEqual([]);
+  });
+});

package/frontendBuild/autoImportSync.ts

@@ -250,6 +250,10 @@ export class AutoImportSync {
     const parts = rel.split(path.sep).filter(Boolean);
     const [scope, project, facet] = parts;
     if ((scope !== "apps" && scope !== "libs") || !project || !facet) return null;
+    //* `lib/__lib/` holds the generated per-lib re-export stubs — gitignored, and rewritten by every
+    //* `akan sync`, which is also what makes the watcher report them. An edit there is churn at best and
+    //* silently discarded at worst. `lib/__scalar/` is real source and stays in scope.
+    if (facet === "lib" && parts[3] === "__lib") return null;
     const role = roleFor(facet, base);
     if (!role) return null;
 

package/frontendBuild/buildRouteClient.test.ts

@@ -159,28 +159,25 @@ describe("route client store bootstrap", () => {
     await write(uiEntry, 'export { ClientPathWrapper } from "./System/Client";\n');
     await write(clientEntry, '"use client";\nexport const ClientPathWrapper = () => null;\n');
 
-    const discovery = new GraphClientEntryDiscovery(
-      { barrelImports: ["akanjs/ui"], externalLibs: [], optimizeImports: true },
-      async (specifier) => {
-        if (specifier === "akanjs/ui") {
-          return {
-            pkgName: "akanjs/ui",
-            entryFile: uiEntry,
-            pkgDir: path.dirname(uiEntry),
-            preserveFilePath: true,
-          };
-        }
-        if (specifier === "akanjs/ui/System/Client.tsx") {
-          return {
-            pkgName: "akanjs/ui/System/Client.tsx",
-            entryFile: clientEntry,
-            pkgDir: path.dirname(clientEntry),
-            preserveFilePath: true,
-          };
-        }
-        return null;
-      },
-    );
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: ["akanjs/ui"] }, async (specifier) => {
+      if (specifier === "akanjs/ui") {
+        return {
+          pkgName: "akanjs/ui",
+          entryFile: uiEntry,
+          pkgDir: path.dirname(uiEntry),
+          preserveFilePath: true,
+        };
+      }
+      if (specifier === "akanjs/ui/System/Client.tsx") {
+        return {
+          pkgName: "akanjs/ui/System/Client.tsx",
+          entryFile: clientEntry,
+          pkgDir: path.dirname(clientEntry),
+          preserveFilePath: true,
+        };
+      }
+      return null;
+    });
 
     expect(await discovery.discover([seed])).toEqual([clientEntry]);
   });

package/frontendBuild/clientEntryDiscovery.ts

@@ -34,7 +34,7 @@ const shouldSkipNodeModule = (absPath: string) => NODE_MODULES_RE.test(absPath)
  * the traversal matches the module graph the bundler will actually see.
  */
 export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
-  #akanConfig: AkanConfig;
+  #akanConfig: Pick<AkanConfig, "barrelImports">;
   #resolvePackage: PackageResolver;
   #analyzer: BarrelAnalyzer;
   #tsTranspiler = new Bun.Transpiler({ loader: "tsx" });
@@ -57,7 +57,7 @@ export class GraphClientEntryDiscovery implements ClientEntryDiscovery {
   #unresolvedPaths = new Set<string>();
   #unresolvedSpecifiers = new Set<string>();
 
-  constructor(akanConfig: AkanConfig, resolvePackage: PackageResolver) {
+  constructor(akanConfig: Pick<AkanConfig, "barrelImports">, resolvePackage: PackageResolver) {
     this.#akanConfig = akanConfig;
     this.#resolvePackage = resolvePackage;
     this.#analyzer = new BarrelAnalyzer({ resolvePackage });

package/frontendBuild/fontOptimizer.ts

@@ -43,7 +43,9 @@ export class FontOptimizer {
   #woff2Ready: Promise<void> | null = null;
 
   static #ksX1001Text: string | null = null;
-  static readonly #cacheVersion = 1;
+  // 2: the key moved to sha256 over a deterministically ordered `auto` text, so v1 entries cannot be
+  // compared against and their subsets were built from `page`/`ui` only.
+  static readonly #cacheVersion = 2;
 
   constructor(app: App, command: FontOptimizerCommand = "start") {
     this.#app = app;
@@ -96,9 +98,18 @@ export class FontOptimizer {
       }
       // `auto` derives the subset from app source text, which no font config hash can capture.
       if (this.#getFontSubsets(font).includes("auto"))
-        sources.push({ autoSubsetText: this.#hashFontConfig(await this.#collectAutoSubsetText()) });
+        sources.push({ autoSubsetText: this.#cacheDigest(await this.#collectAutoSubsetText()) });
     }
-    return this.#hashFontConfig({ version: FontOptimizer.#cacheVersion, fonts, sources });
+    return this.#cacheDigest({ version: FontOptimizer.#cacheVersion, fonts, sources });
+  }
+
+  /**
+   * Cache keys get a cryptographic digest, not the 32-bit FNV `#hashFontConfig` computes for filenames:
+   * a collision there serves a stale subset as if it were current, while a filename only has to be short
+   * and stable.
+   */
+  #cacheDigest(value: unknown) {
+    return new Bun.CryptoHasher("sha256").update(this.#stableStringify(value)).digest("hex");
   }
 
   async #fileStamp(filePath: string): Promise<{ mtimeMs: number; size: number } | null> {
@@ -387,26 +398,34 @@ export class FontOptimizer {
     return "";
   }
 
+  /**
+   * Every source that can put a glyph on screen, concatenated in a **stable** order.
+   *
+   * The order is load-bearing even though a glyph set is not: `#buildCacheKey` hashes this string, so
+   * reading the roots concurrently and pushing as each file resolved made the key depend on i/o
+   * scheduling — measured 8 distinct keys over 8 runs against unchanged sources, which means the cache
+   * never hit and every build re-subset the fonts.
+   *
+   * `lib` is in the roots because that is where user-facing text actually lives: a dictionary's
+   * `[en, ko]` pairs are the Korean in the app, and a subset built from `page` and `ui` alone renders
+   * them as tofu — while hashing the same partial text also stopped a new label from invalidating.
+   */
   async #collectAutoSubsetText() {
     //* Synced lib pages hold app-visible text too, and a glob never crosses the symlink that mounts them.
     const libPageRoots = (await this.#app.getPageRoots()).filter((root) => root.keyPrefix).map((root) => root.dir);
-    const roots = [...["page", "ui"].map((dir) => path.join(this.#app.cwdPath, dir)), ...libPageRoots];
+    const roots = [...["page", "ui", "lib"].map((dir) => path.join(this.#app.cwdPath, dir)), ...libPageRoots];
     const glob = new Bun.Glob("**/*.{ts,tsx,js,jsx,html,md}");
     const parts: string[] = [];
-    await Promise.all(
-      roots.map(async (root) => {
-        if (
-          !(await stat(root).then(
-            (entry) => entry.isDirectory(),
-            () => false,
-          ))
-        )
-          return;
-        for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
-          parts.push(await Bun.file(filePath).text());
-        }
-      }),
-    );
+    for (const root of [...new Set(roots)].sort()) {
+      const isDir = await stat(root).then(
+        (entry) => entry.isDirectory(),
+        () => false,
+      );
+      if (!isDir) continue;
+      const filePaths: string[] = [];
+      for await (const filePath of glob.scan({ cwd: root, absolute: true })) filePaths.push(filePath);
+      for (const filePath of filePaths.sort()) parts.push(await Bun.file(filePath).text());
+    }
     return parts.join("");
   }
 

package/frontendBuild/index.ts

@@ -20,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/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/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.proc.ts

@@ -186,6 +186,11 @@ class IncrementalBuilder {
     this.#shuttingDown = true;
     const started = Date.now();
     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.
@@ -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";