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

package/executors.ts

@@ -28,6 +28,7 @@ import {
   isRouteSourceFile,
   Logger,
   parseRouteModuleKey,
+  toError,
   validatePageSourceFile,
   validateSubRoutePageKey,
 } from "akanjs/common";
@@ -52,7 +53,8 @@ import { AppInfo, isAkanFrameworkDependency, LibInfo, PkgInfo, WorkspaceInfo } f
 import { Spinner } from "./spinner";
 // Type-only: `getTypeChecker` loads it on demand to keep `typescript` out of the resident module graph.
 import type { TypeChecker } from "./typeChecker";
-import type { FileContent, PackageJson, TsConfigJson } from "./types";
+import { ProjectTypecheck } from "./typecheck/projectTypecheck";
+import type { BaseDevEnv, FileContent, PackageJson, TsConfigJson } from "./types";
 import { barrelFacetDirs } from "./workspaceLayout";
 
 export interface PageRoot {
@@ -64,6 +66,10 @@ export interface PageRoot {
   keyPrefix: string;
 }
 
+export interface WrittenFileContent extends FileContent {
+  written: boolean;
+}
+
 const staticTemplateFileExtensions = new Set(
   ".avif .bmp .cjs .css .eot .gif .html .ico .jpeg .jpg .js .json .map .md .mjs .mp3 .mp4 .ogg .otf .pdf .png .svg"
     .split(" ")
@@ -265,20 +271,20 @@ export class Executor {
     const readPath = this.getPath(dirPath);
     try {
       const glob = new Bun.Glob("*");
-      return Array.from(glob.scanSync({ cwd: readPath, onlyFiles: false }));
+      return Array.from(glob.scanSync({ cwd: readPath, onlyFiles: false })).sort();
     } catch {
       return [];
     }
   }
   async getAllFiles(pattern = "**/*", { cwd }: { cwd?: string } = {}): Promise<string[]> {
     const glob = new Bun.Glob(pattern);
-    return Array.from(glob.scanSync({ cwd: cwd ?? this.cwdPath, onlyFiles: true }));
+    return Array.from(glob.scanSync({ cwd: cwd ?? this.cwdPath, onlyFiles: true })).sort();
   }
   async getFilesAndDirs(dirPath: string): Promise<{ files: string[]; dirs: string[] }> {
     const fullDirPath = this.getPath(dirPath);
     const glob = new Bun.Glob("*");
-    const files = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: true }));
-    const allEntries = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: false }));
+    const files = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: true })).sort();
+    const allEntries = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: false })).sort();
     const dirs = allEntries.filter((entry) => !files.includes(entry));
     return { files, dirs };
   }
@@ -302,17 +308,19 @@ export class Executor {
     filePath: string,
     content: string | object,
     { overwrite = true, silent = false }: { overwrite?: boolean; silent?: boolean } = {},
-  ): Promise<FileContent> {
+  ): Promise<WrittenFileContent> {
     const writePath = this.getPath(filePath);
     const dir = path.dirname(writePath);
     if (!(await FileSys.dirExists(dir))) await mkdir(dir, { recursive: true });
     let contentStr = typeof content === "string" ? content : JsonFormatter.stringify(content, writePath);
+    let written = true;
 
     if (await FileSys.fileExists(writePath)) {
       const currentContent = await FileSys.readText(writePath);
       if (currentContent === contentStr || !overwrite) {
         this.logger.verbose(`File ${writePath} is unchanged`);
         contentStr = currentContent;
+        written = false;
       } else {
         await FileSys.writeText(writePath, contentStr);
         if (Logger.isVerbose()) this.logger.rawLog(chalk.yellow(`File Update: ${filePath}`));
@@ -321,7 +329,7 @@ export class Executor {
       await FileSys.writeText(writePath, contentStr);
       if (!silent) this.logger.rawLog(chalk.green(`File Create: ${filePath}`));
     }
-    return { filePath: writePath, content: contentStr };
+    return { filePath: writePath, content: contentStr, written };
   }
   async writeJson(filePath: string, content: object) {
     await this.writeFile(filePath, content);
@@ -418,7 +426,7 @@ export class Executor {
     },
     dict: { [key: string]: string } = {},
     options: { [key: string]: unknown } = {},
-  ): Promise<FileContent | null> {
+  ): Promise<WrittenFileContent | null> {
     const convertPath = (target: string) =>
       Object.entries(dict).reduce(
         (converted, [key, value]) => converted.replace(new RegExp(`__${key}__`, "g"), value),
@@ -451,11 +459,13 @@ export class Executor {
     } else if (staticTemplateFileExtensions.has(path.extname(targetPath).toLowerCase())) {
       const convertedTargetPath = convertPath(targetPath);
       const writePath = this.getPath(convertedTargetPath);
+      if (!overwrite && (await FileSys.fileExists(writePath)))
+        return { filePath: writePath, content: "", written: false };
       const dirname = path.dirname(writePath);
       if (!(await FileSys.dirExists(dirname))) await mkdir(dirname, { recursive: true });
       await copyFile(templatePath, writePath);
       this.logger.verbose(`Apply template ${templatePath} to ${convertedTargetPath}`);
-      return { filePath: writePath, content: "" };
+      return { filePath: writePath, content: "", written: true };
     } else return null;
   }
   async _applyTemplate({
@@ -472,7 +482,7 @@ export class Executor {
     dict?: { [key: string]: string };
     options?: { [key: string]: unknown };
     overwrite?: boolean;
-  }): Promise<FileContent[]> {
+  }): Promise<WrittenFileContent[]> {
     const templateRoot = await this.#resolveTemplateRoot();
     const templatePath = `${templateRoot}${template ? `/${template}` : ""}`;
     if ((await stat(templatePath)).isFile()) {
@@ -486,7 +496,7 @@ export class Executor {
         dict,
         options,
       );
-      return fileContent ? [fileContent] : ([] as FileContent[]);
+      return fileContent ? [fileContent] : ([] as WrittenFileContent[]);
     } else {
       const subdirs = await readDirEntries(templatePath);
       const fileContents = (
@@ -504,7 +514,7 @@ export class Executor {
                 dict,
                 options,
               );
-              return fileContent ? [fileContent] : ([] as FileContent[]);
+              return fileContent ? [fileContent] : ([] as WrittenFileContent[]);
             } else
               return await this._applyTemplate({
                 basePath: path.join(basePath, subdir),
@@ -539,7 +549,7 @@ export class Executor {
     overwrite?: boolean;
   }): Promise<FileContent[]> {
     const fileContents = await this._applyTemplate({ ...options, dict: withCapitalizedDict(options.dict) });
-    await this.#formatAppliedTemplate(fileContents);
+    await this.#formatAppliedTemplate(fileContents.filter((fileContent) => fileContent.written));
     return fileContents;
   }
 
@@ -554,7 +564,7 @@ export class Executor {
       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)}`);
+      this.logger.verbose(`Skipped formatting scaffolded files: ${toError(err).message}`);
     }
   }
   // Async so `typescript` (~65MB resident) loads only in the commands that typecheck.
@@ -572,7 +582,7 @@ export class Executor {
   }
   async typeCheckAsync(filePath: string) {
     const path = this.getPath(filePath);
-    const entry = await this.#resolveTypecheckWorkerEntry();
+    const entry = await ProjectTypecheck.workerEntry(process.cwd());
     const proc = Bun.spawn([process.execPath, entry], {
       cwd: this.cwdPath,
       env: {
@@ -603,18 +613,6 @@ export class Executor {
       message: result.message,
     };
   }
-  async #resolveTypecheckWorkerEntry() {
-    const dirname = getDirname(import.meta.url);
-    const candidates = [
-      path.join(process.cwd(), "pkgs/@akanjs/devkit/typecheck/typecheck.proc.ts"),
-      path.join(process.cwd(), "node_modules/@akanjs/devkit/typecheck/typecheck.proc.ts"),
-      path.join(dirname, "typecheck/typecheck.proc.ts"),
-      path.join(dirname, "typecheck.proc.js"),
-      path.join(dirname, "typecheck.proc.ts"),
-    ];
-    for (const candidate of candidates) if (await Bun.file(candidate).exists()) return candidate;
-    throw new Error(`[devkit] typecheck worker entry not found; looked in: ${candidates.join(", ")}`);
-  }
   getLinter() {
     this.linter ??= new Linter(this.cwdPath);
     return this.linter;
@@ -662,19 +660,25 @@ export class WorkspaceExecutor extends Executor {
   } = {}) {
     return new WorkspaceExecutor({ workspaceRoot, repoName });
   }
+  /** The public env a native build was told to reproduce (`--public-env`): it outranks `.env`, which outranks the rest. */
+  static publicEnvPin: Record<string, string> | null = null;
+  static readonly localServeDomain = "localhost";
   static getBaseDevEnv(envPath?: string) {
     // Bun auto-loads .env, so we use process.env directly
-    const sourceEnv = envPath ? { ...process.env, ...parseEnvFile(envPath) } : process.env;
+    const sourceEnv = {
+      ...(envPath ? { ...process.env, ...parseEnvFile(envPath) } : process.env),
+      ...WorkspaceExecutor.publicEnvPin,
+    };
 
     const appName = sourceEnv.AKAN_PUBLIC_APP_NAME;
     const workspaceRoot = sourceEnv.AKAN_WORKSPACE_ROOT;
     const workspaceId = sourceEnv.AKAN_WORKSPACE_ID;
 
-    const repoName = sourceEnv.AKAN_PUBLIC_REPO_NAME;
-    if (!repoName) throw new Error("AKAN_PUBLIC_REPO_NAME is not set");
-
-    const serveDomain = sourceEnv.AKAN_PUBLIC_SERVE_DOMAIN;
-    if (!serveDomain) throw new Error("AKAN_PUBLIC_SERVE_DOMAIN is not set");
+    const repoName =
+      sourceEnv.AKAN_PUBLIC_REPO_NAME ||
+      resolveRepoName(envPath ? path.dirname(envPath) : (workspaceRoot ?? process.cwd()));
+    const serveDomain = sourceEnv.AKAN_PUBLIC_SERVE_DOMAIN || WorkspaceExecutor.localServeDomain;
+    const defaulted = (["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"] as const).filter((key) => !sourceEnv[key]);
 
     const portOffset = parseInt(sourceEnv.PORT_OFFSET ?? "0");
 
@@ -694,8 +698,20 @@ export class WorkspaceExecutor extends Executor {
       env,
       portOffset,
       workspaceId,
+      defaulted,
     };
   }
+  //? A build or tunnel for a real environment carries these into an image, a bundle or a host name it dials.
+  static assertDeployableEnv(baseDevEnv: BaseDevEnv, environment: string, purpose: string) {
+    const defaulted = environment === "local" ? [] : (baseDevEnv.defaulted ?? []);
+    if (!defaulted.length) return;
+    const values = { AKAN_PUBLIC_REPO_NAME: baseDevEnv.repoName, AKAN_PUBLIC_SERVE_DOMAIN: baseDevEnv.serveDomain };
+    const standIns = defaulted.map((key) => `${key} (would be "${values[key]}")`).join(" and ");
+    throw new Error(
+      `${purpose} for the "${environment}" environment needs ${standIns} set, not a local default. ` +
+        `Set ${defaulted.length > 1 ? "them" : "it"} in the workspace .env or the shell, or use AKAN_PUBLIC_ENV=local.`,
+    );
+  }
   getWorkspaceId<AllowEmpty extends boolean = false>({
     allowEmpty,
   }: {
@@ -1156,10 +1172,12 @@ export class AppExecutor extends SysExecutor {
     return basePort + appIndex + portOffset;
   }
   getCommandEnv(env: Record<string, string> = {}): Record<string, string> {
-    const { portOffset } = WorkspaceExecutor.getBaseDevEnv();
+    const { portOffset, repoName, serveDomain } = WorkspaceExecutor.getBaseDevEnv();
     const PORT = (8282 + portOffset).toString();
     return {
       ...process.env,
+      AKAN_PUBLIC_REPO_NAME: repoName,
+      AKAN_PUBLIC_SERVE_DOMAIN: serveDomain,
       AKAN_PUBLIC_APP_NAME: this.name,
       AKAN_WORKSPACE_ROOT: this.workspace.workspaceRoot,
       NODE_NO_WARNINGS: "1",
@@ -1320,7 +1338,7 @@ export class AppExecutor extends SysExecutor {
         pageKeys.push(key);
       }
     }
-    pageKeys.sort();
+    pageKeys.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     this.#pageKeys = this.#excludeDevOnlyPages ? this.#dropDevOnlyPages(pageKeys, devOnlyKeys, devOnlyDirs) : pageKeys;
     return this.#pageKeys;
   }
@@ -1578,7 +1596,9 @@ export class PkgExecutor extends Executor {
     devDependencies: string[] = [],
   ): Promise<Pick<PackageJson, "dependencies" | "devDependencies">> {
     const dependencyNames = [...new Set(dependencies)].sort();
-    const devDependencyNames = [...new Set(devDependencies)].filter((dep) => !dependencyNames.includes(dep)).sort();
+    const devDependencyNames = [...new Set(devDependencies)]
+      .filter((dep) => !dependencyNames.includes(dep))
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     const dependencyVersions = new Map<string, string>();
     const missingDeps: string[] = [];
     for (const dep of [...dependencyNames, ...devDependencyNames]) {

package/frontendBuild/autoImportSync.test.ts

@@ -253,7 +253,9 @@ describe("AutoImportSync.syncForBatch", () => {
 
     const result = await sync.syncForBatch([uiFile, pageFile, webkitFile]);
     expect(result.errors).toEqual([]);
-    expect(result.changedFiles.sort()).toEqual([pageFile, webkitFile, uiFile].sort());
+    expect(result.changedFiles.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(
+      [pageFile, webkitFile, uiFile].sort(),
+    );
     expect(await readFile(uiFile, "utf8")).toContain(`import { st } from "@apps/akan/client";`);
     expect(await readFile(pageFile, "utf8")).toContain(`import { cnst } from "@apps/akan/client";`);
     expect(await readFile(webkitFile, "utf8")).toContain(`import { fetch } from "@libs/shared/client";`);

package/frontendBuild/clientEntryDiscovery.ts

@@ -6,7 +6,7 @@ import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
 import type { AkanConfig, ClientEntryDiscovery, ScannedImport } from "./clientBuildTypes";
 
-const USE_CLIENT_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
+const USE_CLIENT_RE = /^\s*(?:\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
 const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
 const AKANJS_NODE_MODULE_RE = /[\\/]node_modules[\\/]akanjs[\\/]/;
 // Bun's scanImports also surfaces CSS and asset imports, none of which can be a client component.

package/frontendBuild/csrArtifactBuilder.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { tempDirs, writeText } from "../testHelpers";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
 
 const makeTempRoot = tempDirs("akan-csr-artifact-");
 
@@ -31,4 +32,33 @@ console.info(await result.outputs[0].text());
     expect(stdout).toContain("envmark:debug");
     expect(stdout).not.toContain("envmark:local");
   });
+
+  //? An OTA release is keyed on the bundle's hash, so a no-op build from another checkout must not stage one.
+  test("bundles the same app identically from two checkout paths", async () => {
+    const app = { getPublicEnv: () => ({ AKAN_PUBLIC_ENV: "main" }) };
+    const buildFrom = async (root: string) => {
+      await writeText(
+        path.join(root, "node_modules/wasmdep/package.json"),
+        '{ "name": "wasmdep", "main": "index.js" }\n',
+      );
+      await writeText(
+        path.join(root, "node_modules/wasmdep/index.js"),
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: the fixture module's own source holds a template literal
+        'var isNode = typeof process == "object" && !!process.versions?.node;\nmodule.exports = isNode ? `${__dirname}/` : "";\n',
+      );
+      await writeText(path.join(root, "entry.ts"), 'import dir from "wasmdep";\nconsole.info(dir);\n');
+      const result = await Bun.build({
+        ...CsrArtifactBuilder.bundleOptions(app as never, "build"),
+        entrypoints: [path.join(root, "entry.ts")],
+      });
+      expect(result.success).toBe(true);
+      return await result.outputs[0]?.text();
+    };
+    const [first, second] = [await makeTempRoot(), await makeTempRoot()];
+
+    const [firstOutput, secondOutput] = [await buildFrom(first), await buildFrom(second)];
+
+    expect(firstOutput).toBe(secondOutput);
+    expect(firstOutput).not.toContain(path.basename(first));
+  });
 });

package/frontendBuild/csrArtifactBuilder.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
+import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
 import { bundleDefine } from "./bundleDefine";
 import { CsrEntryFiles } from "./csrEntryFiles";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
@@ -61,8 +62,9 @@ export class CsrArtifactBuilder {
       ).flat(),
     );
 
+    const options = CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports);
     const result = await Bun.build({
-      ...CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports),
+      ...options,
       entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
       files: generatedFiles,
       root: this.#generatedDir,
@@ -75,6 +77,7 @@ export class CsrArtifactBuilder {
     }
 
     await this.#inlineCsrArtifacts(cssAssets);
+    if (this.#command === "build") await CsrArtifactBuilder.writePublicEnv(this.#app, options.define);
     this.#app.verbose(`[csr-build] output -> ${this.#outputDir}`);
     return { outputDir: this.#outputDir };
   }
@@ -88,10 +91,25 @@ export class CsrArtifactBuilder {
       define: bundleDefine(app, command, "csr"),
       optimizeImports,
       // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
-      plugins: [PagesBundleBuilder.createCssStubPlugin()],
+      plugins: [PagesBundleBuilder.createCssStubPlugin(), createBrowserDirnamePlugin()],
     };
   }
 
+  /** Where a build records the `AKAN_PUBLIC_*` it inlined, which nothing in the minified bundle names. */
+  static publicEnvPath(app: App) {
+    return path.join(app.dist.cwdPath, ".akan", "artifact", "csr-public-env.json");
+  }
+
+  static async writePublicEnv(app: App, define: Record<string, string>) {
+    const prefix = "process.env.";
+    const publicEnv = Object.fromEntries(
+      Object.entries(define)
+        .filter(([key]) => key.startsWith(`${prefix}AKAN_PUBLIC_`))
+        .map(([key, value]) => [key.slice(prefix.length), JSON.parse(value) as unknown]),
+    );
+    await Bun.write(CsrArtifactBuilder.publicEnvPath(app), `${JSON.stringify(publicEnv, null, 2)}\n`);
+  }
+
   /** The routes one basePath's HTML boots: its own plus every route outside any basePath, matching `bootCsr`. */
   static pageEntriesForBasePath(pageEntries: PageEntry[], basePath: string, basePaths: string[]): PageEntry[] {
     return CsrEntryFiles.pageEntriesForBasePath(pageEntries, basePath, basePaths);
@@ -217,7 +235,7 @@ void bootCsr(pages);
     for await (const filePath of glob.scan({ cwd: this.#outputDir, absolute: true })) {
       if (predicate(filePath)) files.push(filePath);
     }
-    return files.sort();
+    return files.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   }
 
   // Bun hoists the module script into <head> and a React bundle contains "</head>" as text, so positions come from a
@@ -231,9 +249,10 @@ void bootCsr(pages);
     return `${html}\n${snippet}`;
   }
 
+  // An unclosed body runs to EOF, as the HTML tokenizer reads it; that also keeps the scan linear.
   static blankEmbeddedContent(html: string): string {
     return html.replace(
-      /<script\b[^>]*>[\s\S]*?<\/script\s*>|<style\b[^>]*>[\s\S]*?<\/style\s*>|<!--[\s\S]*?-->/gi,
+      /<script\b[^>]*>[\s\S]*?(?:<\/script(?:[\s/][^<>]*)?>|$)|<style\b[^>]*>[\s\S]*?(?:<\/style(?:[\s/][^<>]*)?>|$)|<!--[\s\S]*?(?:--!?>|$)/gi,
       (match) => " ".repeat(match.length),
     );
   }

package/frontendBuild/csrDevPatcher.test.ts

@@ -379,7 +379,10 @@ describe("CsrDevPatcher", () => {
     await expect(patcher.update([], { roots: [file("ui/E1.tsx")], onlyRoots: true })).rejects.toThrow();
     await expect(patcher.update([], { roots: [file("ui/E4.tsx")], onlyRoots: true })).rejects.toThrow();
     const graph = (await bundler.writer.readJson<CsrDevGraph>("graph.json")) as CsrDevGraph;
-    expect(graph.pending.sort()).toEqual(["apps/demo/ui/E1.tsx", "apps/demo/ui/E4.tsx"]);
+    expect(graph.pending.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([
+      "apps/demo/ui/E1.tsx",
+      "apps/demo/ui/E4.tsx",
+    ]);
   });
 
   test("a route's check that adds its own root leaves another route's failed root pending", async () => {

package/frontendBuild/cssBlockParser.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "bun:test";
+import { type CssBlock, CssBlockParser, type CssNode } from "./cssBlockParser";
+
+const blocksOf = (block: CssBlock) => block.nodes.filter((node): node is CssBlock => node.kind === "block");
+const declarationsOf = (block: CssBlock) =>
+  block.nodes.flatMap((node) => (node.kind === "declaration" ? [[node.property, node.value]] : []));
+
+const expectLinear = (run: () => unknown) => {
+  const started = performance.now();
+  run();
+  expect(performance.now() - started).toBeLessThan(1000);
+};
+
+describe("CssBlockParser.parse", () => {
+  test("reads consecutive blocks with their preludes and declarations", () => {
+    const root = CssBlockParser.parse(`a { --x: 1; } b { --y: 2 } c{--z:3}`);
+    expect(blocksOf(root).map((block) => block.prelude)).toEqual(["a", "b", "c"]);
+    expect(blocksOf(root).map(declarationsOf)).toEqual([[["--x", "1"]], [["--y", "2"]], [["--z", "3"]]]);
+  });
+
+  test("nests at-rules and nested rules, keeping a block's own declarations apart from its children's", () => {
+    const root = CssBlockParser.parse(
+      `@media (min-width: 1px) { :root { --a: 1; } } .card { color: red; &:hover { color: blue; } --b: 2; }`,
+    );
+    const [media, card] = blocksOf(root);
+    expect(media.atRule).toBe("@media");
+    expect(media.prelude).toBe("@media (min-width: 1px)");
+    expect(declarationsOf(blocksOf(media)[0])).toEqual([["--a", "1"]]);
+    expect(card.atRule).toBeNull();
+    expect(declarationsOf(card)).toEqual([
+      ["color", "red"],
+      ["--b", "2"],
+    ]);
+    expect(blocksOf(card).map((block) => block.prelude)).toEqual(["&:hover"]);
+  });
+
+  test("treats at-rule statements as neither blocks nor declarations", () => {
+    const root = CssBlockParser.parse(
+      `@source "./**/*";\n@import "tailwindcss";\n@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));\n:root { --a: 1; }`,
+    );
+    expect(root.nodes).toEqual([
+      { kind: "block", prelude: ":root", atRule: null, nodes: [{ kind: "declaration", property: "--a", value: "1" }] },
+    ]);
+  });
+
+  test("ignores braces, semicolons and comment markers inside strings, comments and escapes", () => {
+    const root = CssBlockParser.parse(
+      [
+        `/* :root { --commented: 1; } */`,
+        `.a::before { content: "} ; /* {"; --q: 'x;y'; }`,
+        `.w-\\[10px\\]\\{ { --escaped: 1; }`,
+        `.b { background: url(data:image/png;base64,AAAA); --after: 2; }`,
+      ].join("\n"),
+    );
+    expect(blocksOf(root).map((block) => block.prelude)).toEqual([".a::before", ".w-\\[10px\\]\\{", ".b"]);
+    expect(blocksOf(root).map(declarationsOf)).toEqual([
+      [
+        ["content", `"} ; /* {"`],
+        ["--q", "'x;y'"],
+      ],
+      [["--escaped", "1"]],
+      [
+        ["background", "url(data:image/png;base64,AAAA)"],
+        ["--after", "2"],
+      ],
+    ]);
+  });
+
+  test("drops comments from preludes and values", () => {
+    const root = CssBlockParser.parse(`/* lead */ :root /* mid */ , [data-theme="dark"] { --a: /* x */ #fff; }`);
+    const [block] = blocksOf(root);
+    expect(block.prelude).toBe(`:root  , [data-theme="dark"]`);
+    expect(declarationsOf(block)).toEqual([["--a", "#fff"]]);
+  });
+
+  test("closes what the input leaves open and tolerates a stray closing brace", () => {
+    const root = CssBlockParser.parse(`} :root { --a: 1; .x { --b: 2`);
+    const [rootBlock] = blocksOf(root);
+    expect(declarationsOf(rootBlock)).toEqual([["--a", "1"]]);
+    expect(declarationsOf(blocksOf(rootBlock)[0])).toEqual([["--b", "2"]]);
+    expect(CssBlockParser.parse(`.a { content: "unterminated\n--b: 2; }`).nodes).toHaveLength(1);
+    expect(CssBlockParser.parse(`.a { --b: 1 } /* unterminated`).nodes).toHaveLength(1);
+  });
+});
+
+describe("CssBlockParser.walk", () => {
+  test("visits in source order, passing each block's context to its children", () => {
+    const root = CssBlockParser.parse(
+      `.a { --x: 1; @media m { --y: 2; } --z: 3; } @theme { --skipped: 1; } .b { --w: 4 }`,
+    );
+    const visited: string[] = [];
+    CssBlockParser.walk(root, "", (node: CssNode, path: string) => {
+      if (node.kind === "declaration") {
+        visited.push(`${path}${node.property}`);
+        return null;
+      }
+      return node.atRule === "@theme" ? null : `${path}${node.prelude}>`;
+    });
+    expect(visited).toEqual([".a>--x", ".a>@media m>--y", ".a>--z", ".b>--w"]);
+  });
+
+  test("walks a deeply nested tree without recursion", () => {
+    const root = CssBlockParser.parse(`${"@media x{".repeat(100_000)}:root{--deep:1}`);
+    let found = "";
+    CssBlockParser.walk(root, true, (node) => {
+      if (node.kind === "declaration") found = node.property;
+      return true;
+    });
+    expect(found).toBe("--deep");
+  });
+});
+
+describe("CssBlockParser linear time", () => {
+  test("adversarial runs finish well under a second", () => {
+    expectLinear(() => CssBlockParser.parse(`}${" ".repeat(100_000)}`));
+    expectLinear(() => CssBlockParser.parse(`:root{${"--".repeat(100_000)}`));
+    expectLinear(() => CssBlockParser.parse("@theme".repeat(100_000)));
+    expectLinear(() => CssBlockParser.parse("/*".repeat(100_000)));
+    expectLinear(() => CssBlockParser.parse(`"${"\\".repeat(100_000)}`));
+    expectLinear(() => CssBlockParser.parse("(".repeat(100_000)));
+    expectLinear(() => CssBlockParser.parse(":root{--a:#fff}".repeat(100_000)));
+  });
+});

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