@akanjs/devkit 3.1.0-rc.2 → 3.1.0-rc.20

package/frontendBuild/cssBlockParser.ts

@@ -0,0 +1,132 @@
+export interface CssDeclaration {
+  kind: "declaration";
+  property: string;
+  value: string;
+}
+
+export interface CssBlock {
+  kind: "block";
+  prelude: string;
+  atRule: string | null;
+  nodes: CssNode[];
+}
+
+export type CssNode = CssDeclaration | CssBlock;
+
+export class CssBlockParser {
+  readonly #css: string;
+  readonly #stack: CssBlock[] = [{ kind: "block", prelude: "", atRule: null, nodes: [] }];
+  #pendingParts: string[] = [];
+  #segmentStart = 0;
+  #parenDepth = 0;
+
+  constructor(css: string) {
+    this.#css = css;
+  }
+
+  static parse(css: string): CssBlock {
+    return new CssBlockParser(css).#run();
+  }
+
+  static walk<T>(root: CssBlock, context: T, visit: (node: CssNode, context: T) => T | null) {
+    const stack = [{ nodes: root.nodes, idx: 0, context }];
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const node = frame.nodes[frame.idx];
+      if (!node) {
+        stack.pop();
+        continue;
+      }
+      frame.idx += 1;
+      const childContext = visit(node, frame.context);
+      if (node.kind === "block" && childContext !== null)
+        stack.push({ nodes: node.nodes, idx: 0, context: childContext });
+    }
+  }
+
+  #run(): CssBlock {
+    const css = this.#css;
+    let idx = 0;
+    while (idx < css.length) {
+      const char = css[idx];
+      if (char === "/" && css[idx + 1] === "*") {
+        this.#pendingParts.push(css.slice(this.#segmentStart, idx));
+        const end = css.indexOf("*/", idx + 2);
+        idx = end === -1 ? css.length : end + 2;
+        this.#segmentStart = idx;
+        continue;
+      }
+      if (char === "\\") {
+        idx += 2;
+        continue;
+      }
+      if (char === '"' || char === "'") {
+        idx = this.#skipString(idx);
+        continue;
+      }
+      if (char === "(") this.#parenDepth += 1;
+      else if (char === ")") this.#parenDepth = Math.max(0, this.#parenDepth - 1);
+      else if (char === "{") this.#openBlock(idx);
+      else if (char === "}") this.#closeBlock(idx);
+      //? A `;` inside parentheses belongs to the value, as in an unquoted `url(data:image/png;base64,…)`.
+      else if (char === ";" && this.#parenDepth === 0) this.#endStatement(idx);
+      idx += 1;
+    }
+    this.#endStatement(css.length);
+    return this.#stack[0];
+  }
+
+  get #current(): CssBlock {
+    return this.#stack[this.#stack.length - 1];
+  }
+
+  // An unterminated string ends at the newline, as the CSS tokenizer's bad-string does.
+  #skipString(start: number): number {
+    const css = this.#css;
+    const quote = css[start];
+    let idx = start + 1;
+    while (idx < css.length) {
+      const char = css[idx];
+      if (char === "\\") idx += 2;
+      else if (char === quote) return idx + 1;
+      else if (char === "\n") return idx;
+      else idx += 1;
+    }
+    return css.length;
+  }
+
+  #takeSegment(end: number): string {
+    const text = this.#pendingParts.join("") + this.#css.slice(this.#segmentStart, end);
+    this.#pendingParts = [];
+    this.#segmentStart = end + 1;
+    return text.trim();
+  }
+
+  #openBlock(idx: number) {
+    const prelude = this.#takeSegment(idx);
+    const block: CssBlock = { kind: "block", prelude, atRule: CssBlockParser.#atRuleOf(prelude), nodes: [] };
+    this.#current.nodes.push(block);
+    this.#stack.push(block);
+    this.#parenDepth = 0;
+  }
+
+  #closeBlock(idx: number) {
+    this.#endStatement(idx);
+    if (this.#stack.length > 1) this.#stack.pop();
+    this.#parenDepth = 0;
+  }
+
+  #endStatement(idx: number) {
+    const text = this.#takeSegment(idx);
+    if (!text || text.startsWith("@")) return;
+    const colon = text.indexOf(":");
+    if (colon <= 0) return;
+    const property = text.slice(0, colon).trim();
+    if (!/^[\w-]+$/.test(property)) return;
+    this.#current.nodes.push({ kind: "declaration", property, value: text.slice(colon + 1).trim() });
+  }
+
+  static #atRuleOf(prelude: string): string | null {
+    return prelude.match(/^@[\w-]+/)?.[0].toLowerCase() ?? null;
+  }
+}

package/frontendBuild/cssCandidateCache.test.ts

@@ -23,6 +23,22 @@ describe("CssCandidateCache token extraction", () => {
     expect(candidates).not.toContain("_td");
   });
 
+  test("keeps a bracket nested one level inside another whole, rather than cutting it at the inner `]`", async () => {
+    const candidates = await scan(
+      `const c = "hidden [[data-theme=light]_&]:block has-[[aria-expanded=true]]:opacity-100 [&_[data-x]]:p-2 [&:has([data-state=open])]:p-1";`,
+    );
+    expect(candidates).toEqual(
+      expect.arrayContaining([
+        "[[data-theme=light]_&]:block",
+        "has-[[aria-expanded=true]]:opacity-100",
+        "[&_[data-x]]:p-2",
+        "[&:has([data-state=open])]:p-1",
+      ]),
+    );
+    expect(candidates).not.toContain("[[data-theme=light]_");
+    expect(candidates).not.toContain("[&_[data-x]");
+  });
+
   test("keeps Tailwind v4's variable shorthand whole, and leaves a call's argument its own candidate", async () => {
     const candidates = await scan(
       `const c = "max-md:top-(--keyboard-top) min-h-(--x) bg-(color:--brand)/50"; cn("flex"); fn(value);`,

package/frontendBuild/cssCandidateCache.ts

@@ -1,10 +1,12 @@
 import { stat } from "node:fs/promises";
 
-// The leading `[` alternation keeps arbitrary variants (`[&_td]:px-3`) whole. Brackets hold no whitespace: a labelled
-// tuple type scanned as a class compiles to a rule lightningcss cannot parse, and it then drops every variant rule.
-// Parentheses pass only as Tailwind v4's variable shorthand, `(--x)` or `(length:--x)`, so `cn("flex")` still yields
-// `flex` on its own.
-const CANDIDATE_RE = /-?(?:[\w@]|\[[^\]\s]+\])[\w:/.-]*(?:(?:\[[^\]\s]+\]|\((?:[a-z-]+:)?--[^)\s]+\))[\w:/.-]*)*/g;
+// The leading `[` alternation keeps arbitrary variants (`[&_td]:px-3`) whole, and a bracket may hold one nested
+// bracket (`[&_[data-slot=x]]:p-2`, `has-[[aria-expanded=true]]:x`), or the candidate is cut at the inner `]` and the
+// rule silently never compiles. Brackets hold no whitespace: a labelled tuple type scanned as a class compiles to a
+// rule lightningcss cannot parse, and it then drops every variant rule. Parentheses pass only as Tailwind v4's
+// variable shorthand, `(--x)` or `(length:--x)`, so `cn("flex")` still yields `flex` on its own.
+const CANDIDATE_RE =
+  /-?(?:[\w@]|\[(?:[^[\]\s]|\[[^[\]\s]+\])+\])[\w:/.-]*(?:(?:\[(?:[^[\]\s]|\[[^[\]\s]+\])+\]|\((?:[a-z-]+:)?--[^)\s]+\))[\w:/.-]*)*/g;
 
 interface CachedFile {
   mtimeMs: number;
@@ -20,7 +22,7 @@ interface CacheFile {
 /** Tailwind candidates per source file, on disk: the batch worker that compiles CSS exits before the next save. */
 export class CssCandidateCache {
   // Bump when the token regex or the entry shape changes, so stale extractions are not reused.
-  static readonly #version = 4;
+  static readonly #version = 5;
   readonly #path: string;
   readonly #entries = new Map<string, CachedFile>();
   #dirty = false;

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([]);
   });