@akanjs/devkit 3.1.0-rc.1 → 3.1.0-rc.11

package/frontendBuild/cssCompiler.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { declaredCustomProperties } from "./cssCompiler";
+
+describe("declaredCustomProperties", () => {
+  test("names what the regex-based version named", () => {
+    expect(declaredCustomProperties(":root { --kakao: #fee500; --naver: #1ec800; }")).toEqual(["--kakao", "--naver"]);
+    expect(declaredCustomProperties("@theme inline {\n  --color-brand: var(--brand);\n}\n")).toEqual([]);
+    expect(declaredCustomProperties("@theme { --color-x: initial; }\n:root { --brand: #111; }")).toEqual(["--brand"]);
+    expect(declaredCustomProperties(".a { color: var(--kakao); }")).toEqual([]);
+    expect(declaredCustomProperties(":root{--a:#111}\n@media (min-width:1px){:root{--a:#222;--b:#333}}")).toEqual([
+      "--a",
+      "--b",
+    ]);
+    expect(declaredCustomProperties(":root { --a : 1; --b:2 }")).toEqual(["--a", "--b"]);
+    expect(declaredCustomProperties(".a{--x:1}.b{--y:2}.c{--z:3}")).toEqual(["--x", "--y", "--z"]);
+    expect(declaredCustomProperties("--top: 1;")).toEqual(["--top"]);
+    expect(declaredCustomProperties("@property --percentage { syntax: '<number>'; inherits: false; }")).toEqual([]);
+  });
+
+  test("keeps source order across nested rules", () => {
+    expect(declaredCustomProperties(".x { --a: 1; .y { --b: 2; } --c: 3; }")).toEqual(["--a", "--b", "--c"]);
+  });
+
+  test("skips a whole @theme block, nested blocks included", () => {
+    const css = `@theme { --animate-spin: spin 1s; @keyframes spin { to { --inner: 1; } } --color-after: red; } :root { --kept: 1; }`;
+    expect(declaredCustomProperties(css)).toEqual(["--kept"]);
+  });
+
+  test("ignores comments and strings, so a comment mentioning @theme hides nothing", () => {
+    const css = [
+      "/* `@theme` extension does not work from a lib, so these are plain variables. */",
+      ":root { --kakao: #fee500; }",
+      "/* :root { --commented: 1; } */",
+      `.a::before { content: "--quoted: 1"; }`,
+    ].join("\n");
+    expect(declaredCustomProperties(css)).toEqual(["--kakao"]);
+  });
+
+  test("adversarial input finishes well under a second", () => {
+    for (const css of [
+      "@theme".repeat(100_000),
+      "@theme{".repeat(100_000),
+      `@theme ${"x".repeat(100_000)}`,
+      `:root{${"--".repeat(100_000)}`,
+      " --a".repeat(100_000),
+      "@media x{".repeat(100_000),
+    ]) {
+      const started = performance.now();
+      declaredCustomProperties(css);
+      expect(performance.now() - started).toBeLessThan(1000);
+    }
+  });
+});

package/frontendBuild/cssCompiler.ts

@@ -6,6 +6,7 @@ import type { App } from "../commandDecorators";
 import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
 import { CsrEntryFiles } from "./csrEntryFiles";
+import { CssBlockParser } from "./cssBlockParser";
 import { CssCandidateCache } from "./cssCandidateCache";
 import { CssImportResolver } from "./cssImportResolver";
 
@@ -387,10 +388,13 @@ export function isIgnoredNodeModuleSource(filePath: string): boolean {
 
 /** Skips `@theme` blocks: Tailwind emits those variables only when a utility uses one. */
 export function declaredCustomProperties(css: string): string[] {
-  const withoutThemeBlocks = css.replace(/@theme[^{]*\{[^}]*\}/g, "");
-  return [...new Set([...withoutThemeBlocks.matchAll(/(?:^|[\s;{])(--[\w-]+)\s*:/g)].map(([, name]) => name))].filter(
-    (name): name is string => !!name,
-  );
+  const names = new Set<string>();
+  CssBlockParser.walk(CssBlockParser.parse(css), true, (node) => {
+    if (node.kind === "block") return node.atRule === "@theme" ? null : true;
+    if (node.property.startsWith("--")) names.add(node.property);
+    return null;
+  });
+  return [...names];
 }
 
 export function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {

package/frontendBuild/fontOptimizer.ts

@@ -425,7 +425,8 @@ export class FontOptimizer {
       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());
+      for (const filePath of filePaths.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)))
+        parts.push(await Bun.file(filePath).text());
     }
     return parts.join("");
   }

package/frontendBuild/frontendBuild.test.ts

@@ -195,6 +195,20 @@ describe("CsrArtifactBuilder", () => {
     );
   });
 
+  test("blanks embedded bodies the way the HTML tokenizer closes them", () => {
+    const blank = (html: string) => CsrArtifactBuilder.blankEmbeddedContent(html).trim();
+
+    expect(blank("<script>a</script >")).toBe("");
+    expect(blank("<script>a</script\t\n bar>")).toBe("");
+    expect(blank("<SCRIPT>a</SCRIPT>")).toBe("");
+    expect(blank("<style>a</style foo>")).toBe("");
+    expect(blank("<!-- a --!></head>")).toBe("</head>");
+    expect(blank("<script>a</scripts></head>")).toBe("");
+    expect(blank("<!-- a </head>")).toBe("");
+    expect(CsrArtifactBuilder.blankEmbeddedContent(`<!--${"<!--".repeat(50_000)}`)).toHaveLength(200_004);
+    expect(CsrArtifactBuilder.blankEmbeddedContent(`<script>${"</script\t".repeat(50_000)}`)).toHaveLength(450_008);
+  });
+
   test("gives each basePath its own routes plus the routes outside every basePath", () => {
     const entries = [
       { key: "./_layout.tsx", moduleAbsPath: "/repo/page/_layout.tsx" },

package/frontendBuild/hmrWatcher.ts

@@ -197,7 +197,7 @@ export class HmrWatcher {
     const gaps = this.#index.coverageGaps;
     const key = gaps
       .map((gap) => `${gap.code}:${gap.path}`)
-      .sort()
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
       .join("|");
     if (key === this.#reportedGaps) return;
     this.#reportedGaps = key;

package/frontendBuild/pagesBundleBuilder.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import { PagesBundleBuilder } from "./pagesBundleBuilder";
+
+const macroImport = `import { getSerializedSignal } from "./sig" with { type: "macro" };`;
+const macroFetchProto =
+  "const fetchProto = FetchClient.build<typeof signal>(cnst, getSerializedSignal(), { Err: pageProto.Err });";
+const serverImport = `import { fetch as serverFetch } from "./sig";`;
+const serverFetchProto =
+  "const fetchProto = FetchClient.build<typeof signal>(cnst, serverFetch.serializedSignal, { Err: pageProto.Err, base: serverFetch });";
+
+const generatedUseClient = (lines: { importLine?: string; fetchProtoLine?: string } = {}) =>
+  [
+    'import { makePageProto, registerClientRuntime } from "akanjs/client";',
+    'import { FetchClient } from "akanjs/fetch";',
+    'import * as cnst from "./cnst";',
+    'import type * as dict from "./dict";',
+    lines.importLine ?? macroImport,
+    'import type * as signal from "./sig";',
+    "",
+    "// dict.ts is cumulative, so a lib dictionary is a subset of the mounting app's. Translator state is global,",
+    "const dictionary = {};",
+    "const pageProto = makePageProto<typeof dict>(dictionary);",
+    lines.fetchProtoLine ?? macroFetchProto,
+    'export const runtime = registerClientRuntime({ ...pageProto, ...fetchProto }, { scope: "lib" });',
+    "",
+    "export const { msg, Err, usePage, sig, fetch } = runtime;",
+    "",
+  ].join("\n");
+
+const transform = (source: string) => PagesBundleBuilder.transformServerUseClientFetchSource(source);
+
+describe("PagesBundleBuilder.transformServerUseClientFetchSource", () => {
+  test("swaps the signal macro for the live server fetch in the generated useClient.ts", () => {
+    expect(transform(generatedUseClient())).toBe(
+      generatedUseClient({ importLine: serverImport, fetchProtoLine: serverFetchProto }),
+    );
+  });
+
+  test("accepts the spacing and quoting variants the regex-based version accepted", () => {
+    const source = generatedUseClient({
+      importLine: `import   {getSerializedSignal}   from './sig'   with {type : 'macro'};`,
+      fetchProtoLine: [
+        "const fetchProto=FetchClient.build<typeof signal>(",
+        "  cnst,",
+        "  getSerializedSignal(),",
+        "  { Err: pageProto.Err },",
+        ");",
+      ].join("\n"),
+    }).replace("import type * as dict", `import { x } from "./x" with { type: "macro" };\nimport type * as dict`);
+    const transformed = transform(source);
+    expect(transformed).toContain(`\n${serverImport}\n`);
+    expect(transformed).toContain(`\n${serverFetchProto}\nexport const runtime`);
+    expect(transformed).not.toContain("getSerializedSignal");
+  });
+
+  test("keeps an export modifier in front of the rewritten declaration", () => {
+    const transformed = transform(generatedUseClient({ fetchProtoLine: `export ${macroFetchProto}` }));
+    expect(transformed).toContain(`\nexport ${serverFetchProto}\n`);
+  });
+
+  test("leaves comments and strings that spell the statements alone", () => {
+    const source = generatedUseClient().replace(
+      "const dictionary = {};",
+      `// ${macroFetchProto}\nconst note = "${macroImport.replaceAll('"', "'")}";\nconst dictionary = {};`,
+    );
+    const transformed = transform(source);
+    expect(transformed).toContain(`// ${macroFetchProto}\n`);
+    expect(transformed).toContain(`const note = "${macroImport.replaceAll('"', "'")}";`);
+    expect(transformed).toContain(`\n${serverImport}\n`);
+    expect(transformed).toContain(`\n${serverFetchProto}\n`);
+  });
+
+  test("returns sources it does not recognise unchanged", () => {
+    const transformed = generatedUseClient({ importLine: serverImport, fetchProtoLine: serverFetchProto });
+    expect(transform(transformed)).toBe(transformed);
+    const typeOnly = generatedUseClient({ importLine: macroImport.replace("import {", "import type {") });
+    expect(transform(typeOnly)).toContain(`import type { getSerializedSignal } from "./sig" with { type: "macro" };`);
+    const aliased = generatedUseClient({
+      importLine: macroImport.replace("getSerializedSignal", "getSerializedSignal as g"),
+    });
+    expect(transform(aliased)).toContain(`import { getSerializedSignal as g } from "./sig" with { type: "macro" };`);
+    const withoutMacro = 'import { x } from "./y";\n';
+    expect(transform(withoutMacro)).toBe(withoutMacro);
+  });
+
+  test("adversarial input finishes well under a second", () => {
+    const marker = `${macroImport}\nFetchClient.build\n`;
+    for (const source of [
+      marker + "const fetchProto=FetchClient.build<".repeat(100_000),
+      marker + `import { getSerializedSignal } from "./sig" with { type: `.repeat(100_000),
+      marker + "{".repeat(100_000),
+    ]) {
+      const started = performance.now();
+      transform(source);
+      expect(performance.now() - started).toBeLessThan(1000);
+    }
+  });
+});

package/frontendBuild/pagesBundleBuilder.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import type { BunPlugin } from "bun";
+import ts from "typescript";
 import type { PageEntry } from "../artifact/implicitRootLayout";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
@@ -25,6 +26,12 @@ export interface BuildPagesBundleResult {
   chunkCount: number;
 }
 
+interface TextSpan {
+  start: number;
+  end: number;
+  text: string;
+}
+
 const VIRTUAL_PAGES_ENTRY = "akan-pages-entry";
 
 export class PagesBundleBuilder {
@@ -174,14 +181,62 @@ export class PagesBundleBuilder {
 
   static transformServerUseClientFetchSource(source: string): string {
     if (!source.includes(`with { type: "macro" }`) || !source.includes("FetchClient.build")) return source;
-    return source
-      .replace(
-        /import\s+\{\s*getSerializedSignal\s*\}\s+from\s+["']\.\/sig["']\s+with\s+\{\s*type\s*:\s*["']macro["']\s*\};/,
-        `import { fetch as serverFetch } from "./sig";`,
-      )
-      .replace(
-        /const\s+fetchProto\s*=\s*FetchClient\.build<[^;]+;/,
-        "const fetchProto = FetchClient.build<typeof signal>(cnst, serverFetch.serializedSignal, { Err: pageProto.Err, base: serverFetch });",
-      );
+    const tokens = PagesBundleBuilder.#tokenize(source);
+    const edits: TextSpan[] = [];
+    const importAt = PagesBundleBuilder.#indexOfTokens(tokens, PagesBundleBuilder.#macroImportTokens);
+    if (importAt !== -1)
+      edits.push({
+        start: tokens[importAt].start,
+        end: tokens[importAt + PagesBundleBuilder.#macroImportTokens.length - 1].end,
+        text: `import { fetch as serverFetch } from "./sig";`,
+      });
+    const fetchProtoAt = PagesBundleBuilder.#indexOfTokens(tokens, PagesBundleBuilder.#fetchProtoTokens);
+    const fetchProtoEnd = fetchProtoAt === -1 ? undefined : tokens.slice(fetchProtoAt).find(({ text }) => text === ";");
+    if (fetchProtoEnd)
+      edits.push({
+        start: tokens[fetchProtoAt].start,
+        end: fetchProtoEnd.end,
+        text: "const fetchProto = FetchClient.build<typeof signal>(cnst, serverFetch.serializedSignal, { Err: pageProto.Err, base: serverFetch });",
+      });
+    let transformed = source;
+    for (const { start, end, text } of edits.sort((a, b) => b.start - a.start))
+      transformed = transformed.slice(0, start) + text + transformed.slice(end);
+    return transformed;
+  }
+
+  static readonly #macroImportTokens = [
+    "import",
+    "{",
+    "getSerializedSignal",
+    "}",
+    "from",
+    '"./sig"',
+    "with",
+    "{",
+    "type",
+    ":",
+    '"macro"',
+    "}",
+    ";",
+  ] as const;
+  static readonly #fetchProtoTokens = ["const", "fetchProto", "=", "FetchClient", ".", "build", "<"] as const;
+
+  //? The scanner, not the parser: parsing recurses per nesting level and overflows the stack on a deep `{` run.
+  static #tokenize(source: string): TextSpan[] {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, source);
+    const tokens: TextSpan[] = [];
+    for (let kind = scanner.scan(); kind !== ts.SyntaxKind.EndOfFileToken; kind = scanner.scan()) {
+      const text =
+        kind === ts.SyntaxKind.StringLiteral ? JSON.stringify(scanner.getTokenValue()) : scanner.getTokenText();
+      tokens.push({ text, start: scanner.getTokenStart(), end: scanner.getTokenEnd() });
+    }
+    return tokens;
+  }
+
+  static #indexOfTokens(tokens: TextSpan[], pattern: readonly string[]): number {
+    for (let idx = 0; idx + pattern.length <= tokens.length; idx += 1) {
+      if (pattern.every((text, offset) => tokens[idx + offset].text === text)) return idx;
+    }
+    return -1;
   }
 }

package/frontendBuild/routeClientBuilder.ts

@@ -244,7 +244,7 @@ export class RouteClientBuilder {
   //? a probe export and only the ones the parser reports as exports are declarations.
   static #declaredNamedDefaultFunctions(source: string, filePath?: string) {
     const candidates = [
-      ...source.matchAll(/(^|\n)(\s*)export\s+default\s+(async\s+)?function\s+([A-Za-z_$][\w$]*)(?=\s*(?:<|\())/g),
+      ...source.matchAll(/(^|\n)([^\S\n]*)export\s+default\s+(async\s+)?function\s+([A-Za-z_$][\w$]*)(?=\s*(?:<|\())/g),
     ].map((match) => ({
       index: match.index,
       text: match[0],

package/frontendBuild/sourceMtimeIndex.test.ts

@@ -50,7 +50,7 @@ describe("SourceMtimeIndex", () => {
 
     for (const [i, abs] of files.entries()) await rewrite(abs, `${i}00`);
 
-    expect((await index.collectChanges()).sort()).toEqual([...files].sort());
+    expect((await index.collectChanges()).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([...files].sort());
   });
 
   test("reports a change once, then stops reporting it", async () => {

package/frontendBuild/themeValidator.test.ts

@@ -37,6 +37,67 @@ describe("ThemeValidator.parseThemeTokens", () => {
     const tokens = ThemeValidator.parseThemeTokens(css);
     expect(Object.keys(tokens)).toEqual([":root"]);
   });
+
+  test("reads every block, not every other one", () => {
+    const css = `.a {} :root { --background: #fff; } .b {} [data-theme='light'] { --background: #eee; } [data-theme="dark"] { --background: #111; }`;
+    expect(ThemeValidator.parseThemeTokens(css)).toEqual({
+      ":root": { background: "#fff" },
+      '[data-theme="light"]': { background: "#eee" },
+      '[data-theme="dark"]': { background: "#111" },
+    });
+  });
+
+  test("reads the first block after @source and @import lines", () => {
+    const css = [
+      `@source "./**/*";`,
+      `@import "tailwindcss";`,
+      `@plugin "tailwind-scrollbar";`,
+      `:root { --background: #ffffff; --foreground: #0a0a0a; }`,
+      `[data-theme="dark"] { --background: #0a0a0a; --foreground: #fafafa; }`,
+      `[data-theme="light"] { --background: #fafafa; --foreground: #171717; }`,
+    ].join("\n");
+    expect(Object.keys(ThemeValidator.parseThemeTokens(css))).toEqual([
+      ":root",
+      '[data-theme="dark"]',
+      '[data-theme="light"]',
+    ]);
+  });
+
+  test("keeps a block's own declarations, skipping comments and nested rules", () => {
+    const css = `:root { /* --background: #000; */ --background: #fff; .x { --foreground: #000; } --foreground: #111 }`;
+    expect(ThemeValidator.parseThemeTokens(css)).toEqual({ ":root": { background: "#fff", foreground: "#111" } });
+  });
+
+  test("merges a scope declared twice, the later value winning", () => {
+    const css = `:root { --background: #fff; --foreground: #000; } :root { --foreground: #111; }`;
+    expect(ThemeValidator.parseThemeTokens(css)).toEqual({ ":root": { background: "#fff", foreground: "#111" } });
+  });
+
+  test("reads through @layer and keys a conditional scope by its condition", () => {
+    const css = [
+      `@layer base { :root { --background: #fff; --foreground: #000; } }`,
+      `@media (prefers-color-scheme: dark) { :root { --background: #000; } }`,
+    ].join("\n");
+    expect(ThemeValidator.parseThemeTokens(css)).toEqual({
+      ":root": { background: "#fff", foreground: "#000" },
+      "@media (prefers-color-scheme: dark) :root": { background: "#000" },
+    });
+  });
+
+  test("adversarial input finishes well under a second", () => {
+    for (const css of [
+      " ".repeat(100_000),
+      `}${" ".repeat(100_000)}`,
+      `:root{${"--".repeat(100_000)}`,
+      `:root{---:${" ".repeat(100_000)}`,
+      ":root{--background:#fff}".repeat(100_000),
+      `${"@media x{".repeat(100_000)}:root{--background:#fff}`,
+    ]) {
+      const started = performance.now();
+      ThemeValidator.parseThemeTokens(css);
+      expect(performance.now() - started).toBeLessThan(1000);
+    }
+  });
 });
 
 describe("ThemeValidator.validate", () => {
@@ -58,12 +119,32 @@ describe("ThemeValidator.validate", () => {
     const css = `:root { --primary: var(--brand); --primary-foreground: #000000; }`;
     expect(validator.validate(css)).toHaveLength(0);
   });
+
+  test("checks a conditional scope over the scope it overrides", () => {
+    const css = [
+      `:root { --background: #ffffff; --foreground: #000000; }`,
+      `@media (prefers-color-scheme: dark) { :root { --background: #111111; } }`,
+    ].join("\n");
+    const violations = validator.validate(css);
+    expect(violations.map(({ scope, pair }) => [scope, pair])).toEqual([
+      ["@media (prefers-color-scheme: dark) :root", "background / foreground"],
+    ]);
+  });
 });
 
 describe("shipped framework palette", () => {
+  const css = readFileSync(path.resolve(import.meta.dir, "../../../akanjs/ui/styles.css"), "utf8");
+
+  test("pkgs/akanjs/ui/styles.css parses :root, dark and light", () => {
+    const tokens = ThemeValidator.parseThemeTokens(css);
+    expect(Object.keys(tokens)).toEqual([":root", '[data-theme="dark"]', '[data-theme="light"]']);
+    expect(tokens[":root"].background).toBe("#0a0a0a");
+    expect(tokens['[data-theme="dark"]'].background).toBe("#0a0a0a");
+    expect(tokens['[data-theme="light"]'].background).toBe("#ffffff");
+    for (const scopeTokens of Object.values(tokens)) expect(Object.keys(scopeTokens).length).toBeGreaterThanOrEqual(26);
+  });
+
   test("pkgs/akanjs/ui/styles.css passes WCAG contrast for all scopes", () => {
-    const stylesPath = path.resolve(import.meta.dir, "../../../akanjs/ui/styles.css");
-    const css = readFileSync(stylesPath, "utf8");
     const violations = validator.validate(css);
     expect(violations).toEqual([]);
   });

package/frontendBuild/themeValidator.ts

@@ -1,4 +1,5 @@
 // No akanjs runtime import: this runs inside the lint path.
+import { type CssBlock, CssBlockParser } from "./cssBlockParser";
 
 export interface ThemeContrastViolation {
   scope: string;
@@ -34,6 +35,7 @@ const PAIRS: PairDef[] = [
 ];
 
 const THEME_SCOPES = new Set([":root", '[data-theme="dark"]', '[data-theme="light"]']);
+const CONDITIONAL_AT_RULES = new Set(["@media", "@supports", "@container"]);
 
 export type ThemeTokensByScope = Record<string, Record<string, string>>;
 
@@ -42,8 +44,9 @@ export class ThemeValidator {
     const tokensByScope = ThemeValidator.parseThemeTokens(css);
     const violations: ThemeContrastViolation[] = [];
     for (const [scope, tokens] of Object.entries(tokensByScope)) {
-      if (!THEME_SCOPES.has(scope)) continue;
-      violations.push(...this.validateScope(tokens, scope));
+      const underlying = THEME_SCOPES.has(scope) ? null : [...THEME_SCOPES].find((name) => scope.endsWith(` ${name}`));
+      const effective = underlying ? ThemeValidator.#overlayPairs(tokensByScope[underlying] ?? {}, tokens) : tokens;
+      violations.push(...this.validateScope(effective, scope));
     }
     return violations;
   }
@@ -75,23 +78,42 @@ export class ThemeValidator {
   /** A scope declared twice keeps the later value, so pass the framework css before the app's. */
   static parseThemeTokens(css: string): ThemeTokensByScope {
     const result: ThemeTokensByScope = {};
-    const blockRe = /(?:^|})\s*([^{}@]+?)\s*\{([^{}]*)\}/g;
-    for (const block of css.matchAll(blockRe)) {
-      const selectors = block[1].split(",").map((s) => s.trim());
-      const relevant = selectors.filter((s) => THEME_SCOPES.has(ThemeValidator.#normalizeScope(s)));
-      if (relevant.length === 0) continue;
-      const decls: Record<string, string> = {};
-      for (const decl of block[2].matchAll(/--([\w-]+)\s*:\s*([^;]+?)\s*(?:;|$)/g)) {
-        decls[decl[1]] = decl[2].trim();
+    CssBlockParser.walk(CssBlockParser.parse(css), "", (node, condition) => {
+      if (node.kind !== "block") return null;
+      if (node.atRule === "@layer") return condition;
+      if (node.atRule) return CONDITIONAL_AT_RULES.has(node.atRule) ? node.prelude.replace(/\s+/g, " ") : null;
+      const scopes = node.prelude
+        .split(",")
+        .map((selector) => ThemeValidator.#normalizeScope(selector))
+        .filter((scope) => THEME_SCOPES.has(scope));
+      if (scopes.length === 0) return null;
+      const tokens = ThemeValidator.#customProperties(node);
+      for (const scope of scopes) {
+        const key = condition ? `${condition} ${scope}` : scope;
+        result[key] = Object.assign(result[key] ?? {}, tokens);
       }
-      for (const selector of relevant) {
-        const scope = ThemeValidator.#normalizeScope(selector);
-        result[scope] = { ...(result[scope] ?? {}), ...decls };
-      }
-    }
+      return null;
+    });
     return result;
   }
 
+  static #customProperties(block: CssBlock): Record<string, string> {
+    const tokens: Record<string, string> = {};
+    for (const node of block.nodes) {
+      if (node.kind === "declaration" && node.property.startsWith("--")) tokens[node.property.slice(2)] = node.value;
+    }
+    return tokens;
+  }
+
+  static #overlayPairs(underlying: Record<string, string>, tokens: Record<string, string>): Record<string, string> {
+    const effective: Record<string, string> = {};
+    for (const name of PAIRS.flatMap(({ base, fg }) => [base, fg])) {
+      const value = tokens[name] ?? underlying[name];
+      if (value) effective[name] = value;
+    }
+    return effective;
+  }
+
   static #normalizeScope(selector: string): string {
     return selector.replace(/\[data-theme=['"]?([\w-]+)['"]?\]/g, '[data-theme="$1"]').trim();
   }

package/getRelatedCnsts.ts

@@ -1,4 +1,5 @@
 import { readFileSync, realpathSync } from "node:fs";
+import { dirname } from "node:path";
 import ora from "ora";
 import * as ts from "typescript";
 
@@ -45,7 +46,7 @@ export const parseTsConfig = (tsConfigPath: string = "./tsconfig.json") => {
     return ts.sys.readFile(path);
   });
 
-  return ts.parseJsonConfigFileContent(configFile.config, ts.sys, realpathSync(tsConfigPath).replace(/[^/\\]+$/, ""));
+  return ts.parseJsonConfigFileContent(configFile.config, ts.sys, dirname(realpathSync(tsConfigPath)));
 };
 
 const collectFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine, includeExports: boolean) => {

package/incrementalBuilder/buildBatch.proc.ts

@@ -33,13 +33,17 @@ class BuildBatch {
   }
 
   async run(): Promise<BuildBatchResult> {
-    if (this.#request.needs.includes("base")) await this.#buildBase();
-    if (this.#request.needs.includes("csr")) await this.#buildCsr();
-    if (this.#request.needs.includes("shell")) await this.#buildShell();
-    if (this.#request.needs.includes("ssr")) await this.#buildSsrRegistry();
+    const { needs } = this.#request;
+    //? A CSR artifact inlines the stylesheets, so it waits for this batch's compile of them; the registry reads none.
+    const cssFirst = needs.includes("css") && needs.includes("csr") && resolveDevCsrMode() === "artifact";
+    if (needs.includes("base")) await this.#buildBase();
+    if (cssFirst) await this.#buildCss();
+    if (needs.includes("csr")) await this.#buildCsr();
+    if (needs.includes("shell")) await this.#buildShell();
+    if (needs.includes("ssr")) await this.#buildSsrRegistry();
     // Css before pages: it scans the sources and reads nothing pages produces, so a class edit need not wait for pages.
-    if (this.#request.needs.includes("css")) await this.#buildCss();
-    if (this.#request.needs.includes("pages")) await this.#buildPages();
+    if (needs.includes("css") && !cssFirst) await this.#buildCss();
+    if (needs.includes("pages")) await this.#buildPages();
     return this.#result;
   }
 
@@ -112,7 +116,8 @@ class BuildBatch {
   }
 
   async #rebuildCsrArtifact(started: number): Promise<void> {
-    await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).build();
+    const cssAssets = this.#result.cssAssets ?? this.#request.cssAssets;
+    await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets }).build();
     this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
     // A CSR tab takes none of the SSR refresh messages, so a rebuilt artifact reaches it only as this reload.
     if (this.#request.changedFiles.length === 0) return;

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -178,6 +178,69 @@ process.send({ type: "build-batch-result", data: { generation, errors: {}, artif
     expect(batches.filter((needs) => needs === "shell")).toHaveLength(1);
   }, 30_000);
 
+  test("builds the shell again once the css it inlined is replaced, though the generation has not moved", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    const ledger = path.join(root, "batches.log");
+    const gate = path.join(root, "css-lands");
+    const landed = { "": { cssUrl: "/_akan/styles/root-next.css", cssRelPath: "styles/root-next.css" } };
+    // The registry's boot build stands in for a save's css compile, held until the first shell is built.
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `import fs from "node:fs";
+const { generation, needs, cssAssets } = JSON.parse(process.argv[2]);
+fs.appendFileSync(${JSON.stringify(ledger)}, needs.join(",") + " " + JSON.stringify(cssAssets) + "\\n");
+const orphaned = () => process.exit(1);
+process.on("disconnect", orphaned);
+const deadline = Date.now() + 15_000;
+if (needs.includes("ssr")) while (!fs.existsSync(${JSON.stringify(gate)}) && Date.now() < deadline) await Bun.sleep(20);
+const css = needs.includes("ssr") ? { cssAssets: ${JSON.stringify(landed)} } : {};
+process.send({ type: "build-batch-result", data: { generation, errors: {}, artifact: {}, optimizedFonts: { css: "", files: [] }, ...css } });
+process.off("disconnect", orphaned);
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+        AKAN_DEV_CSR_PATCHER: "off",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    const answers = () => messages.filter((message) => message.type === "build-csr-res");
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({ type: "build-csr", id: 7, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "the first build-csr-res", () => answers().length === 1);
+      await writeText(gate, "");
+      await until(proc, "boot-armed", () => messages.some((message) => message.type === "boot-armed"));
+      proc.send({ type: "build-csr", id: 8, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "the second build-csr-res", () => answers().length === 2);
+    } finally {
+      await writeText(gate, "");
+      proc.kill();
+      await proc.exited;
+    }
+    expect(answers()).toEqual([
+      { type: "build-csr-res", id: 7, ok: true },
+      { type: "build-csr-res", id: 8, ok: true },
+    ]);
+    const shells = (await Bun.file(ledger).text()).split("\n").filter((line) => line.startsWith("shell "));
+    expect(shells).toEqual(["shell null", `shell ${JSON.stringify(landed)}`]);
+  }, 30_000);
+
   test("a killed boot build is tried again after the crash window, before boot-armed; a route build's check waits likewise", async () => {
     // Inside the checkout so the route's client bundle resolves the framework from its source.
     const { root } = track(await createTempApp("demo", path.join(import.meta.dir, "..", "local")));