@akanjs/devkit 3.0.0-alpha.9 → 3.0.0-alpha.91

package/formSetterScanner.ts

@@ -0,0 +1,92 @@
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+/**
+ * The inventory of model fields a screen writes but does not publish.
+ *
+ * A control handed `onChange={st.do.setTitleOnTask}` **by reference** names the field it writes, so it emits
+ * `data-akan-action` and `useFieldTool` publishes the field to the in-page agent. Any wrapper around that setter is
+ * an anonymous closure carrying neither, and the field goes quiet — for the agent, for an E2E selector, and for the
+ * accessibility tree.
+ *
+ * `no-unpublished-form-setter.grit` is the per-line enforcement, and it fires only on a pure forwarding wrapper,
+ * because every other shape has a legitimate reading and a lint error would be wrong. This is the other half: the
+ * per-file count of fields that ended up unreachable whatever the reason, which is the number worth watching. A
+ * warning rather than an error for the same reason — the remedy depends on why the wrapper is there.
+ *
+ * Only a handler that takes a parameter is counted. A zero-parameter handler (`onClick={() => st.do.setStatusOnUser
+ * ("active")}`) is a button setting a constant, not a form control, and its remedy is an `st.tool` beside it.
+ */
+export class FormSetterScanner {
+  static #fieldSetter = /^set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*$/;
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    return sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".tsx")).flatMap((f) => this.#scanFile(f));
+  }
+
+  #scanFile({ file, sourceFile }: SourceFileInfo): QualityWarning[] {
+    const wrapped: { setter: string; line: number }[] = [];
+    const visit = (node: ts.Node) => {
+      if (ts.isJsxAttribute(node)) {
+        const setter = FormSetterScanner.#wrappedSetterOf(node);
+        if (setter) wrapped.push({ setter, line: FormSetterScanner.#lineOf(sourceFile, node) });
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    if (!wrapped.length) return [];
+    const setters = [...new Set(wrapped.map((entry) => entry.setter))].sort();
+    return [
+      {
+        rule: "akan.agent.unpublished-form-setter",
+        scope: "agent",
+        severity: "warning",
+        message:
+          setters.length === 1
+            ? `${setters[0]} is reached through a wrapper, so that field publishes no agent tool and carries no data-akan-action.`
+            : `${setters.length} field setters are reached through a wrapper, so those fields publish no agent tool and carry no data-akan-action: ${setters.join(", ")}.`,
+        file,
+        line: wrapped[0]?.line,
+        locations: wrapped.map(({ line }) => ({ file, line })),
+      },
+    ];
+  }
+
+  /** The setter a handler prop writes behind a wrapper, or null when it is passed by reference or absent. */
+  static #wrappedSetterOf(attribute: ts.JsxAttribute): string | null {
+    if (!ts.isIdentifier(attribute.name) || !/^on[A-Z]/.test(attribute.name.text)) return null;
+    const initializer = attribute.initializer;
+    if (!initializer || !ts.isJsxExpression(initializer) || !initializer.expression) return null;
+    const handler = initializer.expression;
+    if (!ts.isArrowFunction(handler) && !ts.isFunctionExpression(handler)) return null;
+    if (!handler.parameters.length) return null;
+    return FormSetterScanner.#setterCallIn(handler.body);
+  }
+
+  static #setterCallIn(node: ts.Node): string | null {
+    let found: string | null = null;
+    const visit = (current: ts.Node) => {
+      if (found) return;
+      if (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+        const { expression, name } = current.expression;
+        if (
+          ts.isPropertyAccessExpression(expression) &&
+          ts.isIdentifier(expression.expression) &&
+          expression.expression.text === "st" &&
+          expression.name.text === "do" &&
+          FormSetterScanner.#fieldSetter.test(name.text)
+        ) {
+          found = name.text;
+          return;
+        }
+      }
+      ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return found;
+  }
+
+  static #lineOf(sourceFile: ts.SourceFile, node: ts.Node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+  }
+}

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

@@ -1,6 +1,7 @@
-import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import ts from "typescript";
+import { FileSys } from "../fileSys";
 
 //* Auto-import daemon: a source-editing sibling of DevGeneratedIndexSync. When a domain file changes,
 //* framework symbols that are used but not imported (e.g. `Int` in a *.constant.ts, `fetch` in a *.store.ts)
@@ -250,6 +251,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;
 
@@ -263,7 +268,7 @@ export class AutoImportSync {
     const resolveExtra = await this.#extraResolverFor(abs, ctx);
     const next = transformSource(source, abs, ctx, resolveExtra);
     if (next === null || next === source) return false;
-    await writeFile(abs, next);
+    await FileSys.writeTextAtomic(abs, next);
     return true;
   }
 

package/frontendBuild/buildRouteClient.test.ts

@@ -82,16 +82,42 @@ describe("route client store bootstrap", () => {
   });
 
   test("bundles akan fetch into production SSR client chunks", () => {
-    expect(RouteClientBuilder.resolveSsrClientExternalOptions("start")).toMatchObject({
+    expect(RouteClientBuilder.resolveSsrClientBundleOptions("start")).toMatchObject({
       external: expect.arrayContaining(["akanjs/fetch"]),
       externalSubpaths: ["akanjs/fetch"],
     });
 
-    expect(RouteClientBuilder.resolveSsrClientExternalOptions("build")).toEqual({
+    expect(RouteClientBuilder.resolveSsrClientBundleOptions("build")).toEqual({
+      target: "bun",
       external: ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"],
     });
   });
 
+  test("targets the server so SSR client chunks never resolve a browser export condition", async () => {
+    const root = await makeTempRoot();
+    const pkgDir = path.join(root, "node_modules/dom-conditioned-pkg");
+    await write(
+      path.join(pkgDir, "package.json"),
+      JSON.stringify({
+        name: "dom-conditioned-pkg",
+        type: "module",
+        exports: { ".": { browser: "./index.dom.js", default: "./index.js" } },
+      }),
+    );
+    await write(path.join(pkgDir, "index.dom.js"), 'export const element = document.createElement("i");\n');
+    await write(path.join(pkgDir, "index.js"), "export const element = null;\n");
+    const entry = path.join(root, "entry.ts");
+    await write(entry, 'export { element } from "dom-conditioned-pkg";\n');
+
+    for (const command of ["start", "build"] as const) {
+      const { target } = RouteClientBuilder.resolveSsrClientBundleOptions(command);
+      const built = await Bun.build({ entrypoints: [entry], target, format: "esm" });
+
+      expect(built.success).toBe(true);
+      expect(await built.outputs[0].text()).not.toContain("document.createElement");
+    }
+  });
+
   test("rewrites SSR external imports to runtime aliases", () => {
     const source = [
       'import React, { useState } from "react";',
@@ -133,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/clientBuildTypes.ts

@@ -55,6 +55,8 @@ export interface BuildClientResult {
   rscClientUrl: string;
 }
 
+export type ClientBundleTarget = "browser" | "bun";
+
 export const CLIENT_BUNDLE_NAMING = {
   entry: "[name]-[hash].[ext]",
   chunk: "chunks/[hash].[ext]",
@@ -79,6 +81,8 @@ export interface BundleClientEntriesOptions {
 }
 
 export interface BundleClientEntriesInternalOptions extends BundleClientEntriesOptions {
+  /** Module-resolution target. `"bun"` for the server-executed `client-ssr` bundle, `"browser"` otherwise. */
+  target?: ClientBundleTarget;
   external?: readonly string[];
   externalSubpaths?: readonly string[];
   externalAliases?: Partial<Record<string, string>>;

package/frontendBuild/clientEntriesBundler.ts

@@ -7,6 +7,7 @@ import {
   type BundleClientEntriesInternalOptions,
   type BundleClientEntriesResult,
   CLIENT_BUNDLE_NAMING,
+  type ClientBundleTarget,
   type ClientManifest,
   type MetafileOutput,
   type OpaqueEntryAliases,
@@ -25,6 +26,7 @@ export class ClientEntriesBundler {
   #externalSubpaths: readonly string[];
   #externalAliases: Partial<Record<string, string>>;
   #command: "build" | "start";
+  #target: ClientBundleTarget;
   #outputSubdir: string;
   #reactFastRefresh: boolean;
   #artifactDir: string;
@@ -47,6 +49,7 @@ export class ClientEntriesBundler {
     this.#externalSubpaths = options.externalSubpaths ?? [];
     this.#externalAliases = options.externalAliases ?? {};
     this.#command = options.command ?? "start";
+    this.#target = options.target ?? "browser";
     this.#outputSubdir = options.outputSubdir ?? "client";
     this.#reactFastRefresh = options.reactFastRefresh ?? false;
     this.#artifactDir = `${this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath}/.akan/artifact`;
@@ -61,7 +64,7 @@ export class ClientEntriesBundler {
       entrypoints: this.#opaqueEntries.entries,
       outdir: this.#outdir,
       splitting: true,
-      target: "browser",
+      target: this.#target,
       format: "esm",
       naming: CLIENT_BUNDLE_NAMING,
       metafile: true,

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/csrArtifactBuilder.ts

@@ -1,14 +1,18 @@
 import { mkdir, rm, unlink } from "node:fs/promises";
 import path from "node:path";
 import type { BaseBuildArtifact } from "akanjs/server";
-import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
+import { getPageKeyBasePath } from "./cssCompiler";
+import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
 export interface BuildCsrArtifactResult {
   outputDir: string;
 }
 
+type CssAsset = NonNullable<BaseBuildArtifact["cssAssets"]>[string];
+
 export class CsrArtifactBuilder {
   #app: App;
   #command: "build" | "start";
@@ -29,31 +33,39 @@ export class CsrArtifactBuilder {
 
     const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
     const akanConfig = await this.#app.getConfig();
-    const artifact = await this.#loadCsrArtifact();
-    const csrBasePaths = [...akanConfig.basePaths];
-    const htmlEntries = csrBasePaths.length > 0 ? csrBasePaths : ["index"];
+    const cssAssets = await this.#loadCssAssets();
+    const basePaths = [...akanConfig.basePaths];
+    const htmlBasePaths = basePaths.length > 0 ? basePaths : [""];
     await rm(this.#outputDir, { recursive: true, force: true });
-    await mkdir(path.join(this.#app.cwdPath, ".akan/generated/csr"), { recursive: true });
-    const generatedHtmlFiles = Object.fromEntries(htmlEntries.map((basePath) => this.#createHtmlFile(basePath)));
+    await mkdir(this.#generatedDir, { recursive: true });
+    const generatedFiles = Object.fromEntries(
+      (
+        await Promise.all(
+          htmlBasePaths.map(async (basePath) => [
+            this.#createHtmlFile(basePath),
+            await this.#createEntryFile(
+              basePath,
+              CsrArtifactBuilder.pageEntriesForBasePath(pageEntries, basePath, basePaths),
+            ),
+          ]),
+        )
+      ).flat(),
+    );
 
     const result = await Bun.build({
       target: "browser",
-      entrypoints: Object.keys(generatedHtmlFiles),
-      files: {
-        ...generatedHtmlFiles,
-        [`${this.#app.cwdPath}/.akan/generated/csr/csr.tsx`]: `
-import { bootCsr } from "akanjs/webkit";
-${PagesEntrySourceGenerator.generateStatic(pageEntries)}
-void bootCsr(pages);
-  `,
-      },
-      root: `${this.#app.cwdPath}/.akan/generated/csr`,
+      entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
+      files: generatedFiles,
+      root: this.#generatedDir,
       outdir: this.#outputDir,
       splitting: false,
       minify: true,
       env: "AKAN_PUBLIC_*",
       define: this.#define(),
       optimizeImports: akanConfig.optimizeImports,
+      // The base artifact's compiled sheet is the only stylesheet, as it is for SSR: a raw `.css` reached through
+      // the route graph is Tailwind source, and every root layout stylesheet in the graph would land in every HTML.
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
     });
 
     if (!result.success) {
@@ -61,11 +73,32 @@ void bootCsr(pages);
       throw new Error(`[csr-build] failed${logs ? `\n${logs}` : ""}`);
     }
 
-    await this.#inlineCsrArtifacts(artifact.cssAssets ?? {});
+    await this.#inlineCsrArtifacts(cssAssets);
     this.#app.verbose(`[csr-build] output -> ${this.#outputDir}`);
     return { outputDir: this.#outputDir };
   }
 
+  /** 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 pageEntries.filter((entry) => {
+      const entryBasePath = getPageKeyBasePath(entry.key, basePaths);
+      return entryBasePath === null || entryBasePath === basePath;
+    });
+  }
+
+  static htmlFilename(basePath: string): string {
+    return `${basePath || "index"}.html`;
+  }
+
+  static entryFilename(basePath: string): string {
+    return `${basePath || "index"}.csr.tsx`;
+  }
+
+  static basePathOfHtml(htmlPath: string): string {
+    const name = path.basename(htmlPath, ".html");
+    return name === "index" ? "" : name;
+  }
+
   get #outputDir(): string {
     return path.join(
       this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath,
@@ -73,6 +106,18 @@ void bootCsr(pages);
     );
   }
 
+  get #generatedDir(): string {
+    return path.join(this.#app.cwdPath, ".akan/generated/csr");
+  }
+
+  get #artifactDir(): string {
+    return path.join(this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath, ".akan/artifact");
+  }
+
+  #generatedPath(filename: string): string {
+    return path.join(this.#generatedDir, filename);
+  }
+
   #define(): Record<string, string> {
     const nodeEnv = this.#command === "build" ? "production" : (process.env.NODE_ENV ?? "development");
     return {
@@ -84,10 +129,19 @@ void bootCsr(pages);
     };
   }
 
+  async #createEntryFile(basePath: string, pageEntries: PageEntry[]): Promise<readonly [string, string]> {
+    return [
+      this.#generatedPath(CsrArtifactBuilder.entryFilename(basePath)),
+      `import { bootCsr } from "akanjs/webkit";
+${await PagesEntrySourceGenerator.generateStatic(pageEntries)}
+void bootCsr(pages);
+`,
+    ] as const;
+  }
+
   #createHtmlFile(basePath: string): readonly [string, string] {
-    const filename = `${basePath}.html`;
     return [
-      `${this.#app.cwdPath}/.akan/generated/csr/${filename}`,
+      this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath)),
       `<!doctype html>
 <html lang="${this.#lang}">
   <head>
@@ -98,41 +152,40 @@ void bootCsr(pages);
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="./csr.tsx"></script>
+    <script type="module" src="./${CsrArtifactBuilder.entryFilename(basePath)}"></script>
   </body>
 </html>
   `,
     ] as const;
   }
 
-  async #loadCsrArtifact(): Promise<Pick<BaseBuildArtifact, "cssAssets">> {
-    const artifactDir = path.join(
-      this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath,
-      ".akan/artifact",
-    );
-    const artifactFile = Bun.file(path.join(artifactDir, "base-artifact.json"));
-    if (!(await artifactFile.exists())) return { cssAssets: {} };
-    const artifact = (await artifactFile.json()) as Pick<BaseBuildArtifact, "cssAssets">;
-    return { cssAssets: artifact.cssAssets ?? {} };
+  async #loadCssAssets(): Promise<Record<string, CssAsset>> {
+    const artifactFile = Bun.file(path.join(this.#artifactDir, "base-artifact.json"));
+    if (!(await artifactFile.exists())) return {};
+    const artifact = (await artifactFile.json()) as Partial<Pick<BaseBuildArtifact, "cssAssets">>;
+    return artifact.cssAssets ?? {};
   }
 
-  async #inlineCsrArtifacts(cssAssets: Record<string, { cssUrl: string; cssRelPath: string }>): Promise<void> {
+  async #inlineCsrArtifacts(cssAssets: Record<string, CssAsset>): Promise<void> {
     const jsFiles = new Set<string>();
-    const cssFiles = new Set<string>();
     for (const htmlPath of await this.#htmlOutputPaths()) {
       const htmlFile = Bun.file(htmlPath);
       if (!(await htmlFile.exists())) continue;
-      const basePath = path.basename(htmlPath, ".html") === "index" ? "" : path.basename(htmlPath, ".html");
-      const inlined = await this.#inlineHtmlAssets(await htmlFile.text(), htmlPath, cssAssets[basePath]);
+      const basePath = CsrArtifactBuilder.basePathOfHtml(htmlPath);
+      const cssAsset = cssAssets[basePath];
+      if (!cssAsset) {
+        this.#app.logger.warn(
+          `[csr-build] base-artifact.json has no compiled stylesheet for ${basePath || "root"}; ${path.basename(htmlPath)} ships without CSS`,
+        );
+      }
+      const inlined = await this.#inlineHtmlAssets(await htmlFile.text(), htmlPath, cssAsset);
       for (const filePath of inlined.jsFiles) jsFiles.add(filePath);
-      for (const filePath of inlined.cssFiles) cssFiles.add(filePath);
       await Bun.write(htmlPath, inlined.html);
     }
     for (const filePath of jsFiles) await unlink(filePath).catch(() => undefined);
-    for (const filePath of cssFiles) await unlink(filePath).catch(() => undefined);
-    const remainingJs = await this.#listOutputFiles((filePath) => filePath.endsWith(".js"));
-    const remainingCss = await this.#listOutputFiles((filePath) => filePath.endsWith(".css"));
-    const remainingAssets = [...remainingJs, ...remainingCss];
+    const remainingAssets = await this.#listOutputFiles(
+      (filePath) => filePath.endsWith(".js") || filePath.endsWith(".css"),
+    );
     if (remainingAssets.length > 0) {
       throw new Error(`[csr-build] expected single-file HTML, but CSR assets remain:\n${remainingAssets.join("\n")}`);
     }
@@ -141,44 +194,20 @@ void bootCsr(pages);
   async #inlineHtmlAssets(
     html: string,
     htmlPath: string,
-    cssAsset?: { cssUrl: string; cssRelPath: string },
-  ): Promise<{ html: string; jsFiles: string[]; cssFiles: string[] }> {
+    cssAsset?: CssAsset,
+  ): Promise<{ html: string; jsFiles: string[] }> {
+    let next = html;
+    if (cssAsset) {
+      const css = await Bun.file(path.join(this.#artifactDir, cssAsset.cssRelPath)).text();
+      next = CsrArtifactBuilder.injectBeforeHeadEnd(next, CsrArtifactBuilder.createInlineStyle(css));
+    }
     const jsFiles: string[] = [];
-    const cssFiles = CsrArtifactBuilder.collectStylesheetHrefs(html).map((href) =>
-      CsrArtifactBuilder.resolveHtmlAssetPath(htmlPath, href),
-    );
-    let next = CsrArtifactBuilder.stripBundledStylesheetLinks(html);
     next = await CsrArtifactBuilder.replaceModuleScriptSrc(next, async (src) => {
       const jsPath = CsrArtifactBuilder.resolveHtmlAssetPath(htmlPath, src);
       jsFiles.push(jsPath);
       return await Bun.file(jsPath).text();
     });
-    const bundledCss = (
-      await Promise.all(
-        cssFiles.map((cssFile) =>
-          Bun.file(cssFile)
-            .text()
-            .catch(() => ""),
-        ),
-      )
-    )
-      .filter(Boolean)
-      .join("\n");
-    if (bundledCss) {
-      const style = CsrArtifactBuilder.createInlineStyle(bundledCss);
-      if (!next.includes(style)) next = CsrArtifactBuilder.injectBeforeHeadEnd(next, style);
-    }
-    if (cssAsset) {
-      const cssPath = path.join(
-        this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath,
-        ".akan/artifact",
-        cssAsset.cssRelPath,
-      );
-      const css = await Bun.file(cssPath).text();
-      const style = CsrArtifactBuilder.createInlineStyle(css);
-      if (!next.includes(style)) next = CsrArtifactBuilder.injectBeforeHeadEnd(next, style);
-    }
-    return { html: next, jsFiles, cssFiles };
+    return { html: next, jsFiles };
   }
 
   async #htmlOutputPaths(): Promise<string[]> {
@@ -194,23 +223,26 @@ void bootCsr(pages);
     return files.sort();
   }
 
+  /**
+   * Bun's HTML bundler hoists the module script into `<head>`, so once that script is inline its source is part
+   * of the text being searched — and a React bundle contains `<body` and `</head>` as strings. Positions are
+   * taken on a copy with script, style and comment bodies blanked, and the snippet always lands after whatever
+   * was injected before it: prepending would reverse the cascade order the caller chose.
+   */
   static injectBeforeHeadEnd(html: string, snippet: string): string {
-    const matches = [...html.matchAll(/<\/head\s*>/gi)];
-    const bodyStart = html.search(/<body(?:\s|>)/i);
-    const headEnd = matches
-      .filter((match) => match.index !== undefined && (bodyStart === -1 || match.index < bodyStart))
-      .at(-1);
-    if (!headEnd || headEnd.index === undefined) return `${snippet}\n${html}`;
-    return `${html.slice(0, headEnd.index)}${snippet}\n${html.slice(headEnd.index)}`;
-  }
-
-  static stripBundledStylesheetLinks(html: string): string {
-    return html.replace(/<link\b(?=[^>]*\brel=["']stylesheet["'])[^>]*>\s*/gi, "");
+    const scannable = CsrArtifactBuilder.blankEmbeddedContent(html);
+    const headEnd = scannable.search(/<\/head\s*>/i);
+    if (headEnd !== -1) return `${html.slice(0, headEnd)}${snippet}\n${html.slice(headEnd)}`;
+    const bodyStart = scannable.search(/<body(?:\s|>)/i);
+    if (bodyStart !== -1) return `${html.slice(0, bodyStart)}${snippet}\n${html.slice(bodyStart)}`;
+    return `${html}\n${snippet}`;
   }
 
-  static collectStylesheetHrefs(html: string): string[] {
-    const linkRe = /<link\b(?=[^>]*\brel=["']stylesheet["'])(?=[^>]*\bhref=["']([^"']+)["'])[^>]*>/gi;
-    return [...html.matchAll(linkRe)].map((match) => match[1]).filter((href): href is string => !!href);
+  static blankEmbeddedContent(html: string): string {
+    return html.replace(
+      /<script\b[^>]*>[\s\S]*?<\/script\s*>|<style\b[^>]*>[\s\S]*?<\/style\s*>|<!--[\s\S]*?-->/gi,
+      (match) => " ".repeat(match.length),
+    );
   }
 
   static createInlineStyle(css: string): string {