@akanjs/devkit 3.0.0-alpha.1 → 3.0.0-alpha.11

package/capacitorApp.ts

@@ -24,7 +24,9 @@ interface RunIosConfig extends RunConfig {
   iosDeviceId?: string;
 }
 
-interface PrepareConfig extends RunConfig {}
+interface PrepareConfig extends RunConfig {
+  iosRunTargetKind?: IosRunTargetKind;
+}
 
 type MobileCommandEnv = Record<string, string | undefined>;
 
@@ -119,10 +121,11 @@ interface MaterializeCapacitorConfigOptions {
   localServerUrl?: string;
   localIp?: string;
 }
+type MobilePlatform = "ios" | "android";
 
 export interface LocalDevHostResolution {
   host: string;
-  source: "override" | "detected" | "loopback";
+  source: "override" | "detected" | "loopback" | "platform";
   candidates: { name: string; address: string }[];
 }
 
@@ -565,6 +568,16 @@ export function getAdbDeviceStateIssues(output: string) {
     });
 }
 
+export function getAndroidLocalServerHost(adbDevicesOutput: string | undefined, fallbackHost: string) {
+  const onlineDeviceIds =
+    adbDevicesOutput
+      ?.split(/\r?\n/)
+      .map((line) => line.trim().split(/\s+/))
+      .filter(([id, state]) => id && state === "device")
+      .map(([id]) => id) ?? [];
+  return onlineDeviceIds.length === 1 && onlineDeviceIds[0]?.startsWith("emulator-") ? "10.0.2.2" : fallbackHost;
+}
+
 export const ANDROID_MIN_SDK_VERSION = 26;
 export function raiseGradleMinSdkVersion(content: string, floor: number = ANDROID_MIN_SDK_VERSION): string | null {
   const match = content.match(/minSdkVersion\s*=\s*(\d+)/);
@@ -748,7 +761,7 @@ export class CapacitorApp {
   async save() {
     await this.project.commit();
   }
-  async #prepareIos({ operation, env, regenerate = false }: PrepareConfig) {
+  async #prepareIos({ operation, env, regenerate = false, iosRunTargetKind }: PrepareConfig) {
     await this.init({ platform: "ios", operation, env, regenerate });
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("ios");
@@ -757,9 +770,10 @@ export class CapacitorApp {
     await this.#applyDeepLinks("ios", { operation, env });
     await this.#flushIosEntitlements();
     await this.project.commit();
+    await this.#setCodeSignEntitlementsInIosIfExists("App/App.entitlements");
     await this.#generateAssets({ operation, env });
     this.app.verbose(`syncing iOS`);
-    await this.#spawnMobile("npx", ["cap", "sync", "ios"], { operation, env });
+    await this.#spawnMobile("npx", ["cap", "sync", "ios"], { operation, env }, { iosRunTargetKind });
     this.app.verbose(`sync completed.`);
   }
   async buildIos({ env = "debug", regenerate = false }: { env?: RunConfig["env"]; regenerate?: boolean } = {}) {
@@ -777,14 +791,14 @@ export class CapacitorApp {
   }
   async runIos({ operation, env, regenerate = false, noAllowProvisioningUpdates = false, iosDeviceId }: RunIosConfig) {
     if (operation === "release") await this.prepareWww();
-    await this.#prepareIos({ operation, env, regenerate });
     const runTarget = await this.#selectIosRunTarget(iosDeviceId);
+    await this.#prepareIos({ operation, env, regenerate, iosRunTargetKind: runTarget.kind });
     if (runTarget.kind === "simulator") {
       await this.#spawnMobile(
         "npx",
-        ["cap", "run", "ios", "--target", runTarget.id],
+        ["cap", "run", "ios", "--target", runTarget.id, "--no-sync"],
         { operation, env },
-        { stdio: "inherit" },
+        { stdio: "inherit", platform: "ios", iosRunTargetKind: runTarget.kind },
       );
       return;
     }
@@ -878,7 +892,10 @@ export class CapacitorApp {
     noAllowProvisioningUpdates: boolean;
   }) {
     const mobileEnv = sanitizeIosNativeRunEnv(await this.#commandEnv(operation, env));
-    const configContent = await this.#writeCapacitorConfig({ operation }, mobileEnv);
+    const configContent = await this.#writeCapacitorConfig(
+      { operation, platform: "ios", iosRunTargetKind: runTarget.kind },
+      mobileEnv,
+    );
     await this.#writeRootCapacitorConfig(configContent);
     const scheme = this.#iosScheme();
     const command = buildIosNativeRunCommand({
@@ -943,6 +960,7 @@ export class CapacitorApp {
     await this.#applyAndroidMinSdkVersion();
     await this.#applyPermissions({ operation, env });
     await this.#applyDeepLinks("android", { operation, env });
+    await this.#disableNativeKeyboardResizeInAndroid();
     await this.project.commit();
     await this.#generateAssets({ operation, env });
     await this.#ensureAndroidAssetsDir();
@@ -1010,6 +1028,24 @@ export class CapacitorApp {
   async openAndroid() {
     await this.#spawnMobile("npx", ["cap", "open", "android"], { operation: "local", env: "local" });
   }
+  async #disableNativeKeyboardResizeInAndroid() {
+    const manifestPath = path.join(this.app.cwdPath, this.androidRootPath, "app/src/main/AndroidManifest.xml");
+    let manifest = await readFile(manifestPath, "utf8");
+    let changed = false;
+    manifest = manifest.replace(/<activity\b[^>]*android:name="\.MainActivity"[^>]*>/, (activityTag) => {
+      if (activityTag.includes("android:windowSoftInputMode=")) {
+        const nextTag = activityTag.replace(
+          /android:windowSoftInputMode="[^"]*"/,
+          'android:windowSoftInputMode="adjustNothing"',
+        );
+        changed ||= nextTag !== activityTag;
+        return nextTag;
+      }
+      changed = true;
+      return activityTag.replace(/>$/, '\n            android:windowSoftInputMode="adjustNothing">');
+    });
+    if (changed) await writeFile(manifestPath, manifest);
+  }
   async #ensureAndroidAssetsDir() {
     await mkdir(path.join(this.app.cwdPath, this.androidAssetsPath), { recursive: true });
   }
@@ -1100,12 +1136,19 @@ export class CapacitorApp {
     if (html.includes("window.__AKAN_MOBILE_TARGET__")) return html;
     return html.replace(/<\/head\s*>/i, `${script}\n</head>`);
   }
-  async #writeCapacitorConfig({ operation }: Pick<RunConfig, "operation">, commandEnv: MobileCommandEnv) {
+  async #writeCapacitorConfig(
+    {
+      operation,
+      platform,
+      iosRunTargetKind,
+    }: Pick<RunConfig, "operation"> & { platform?: MobilePlatform; iosRunTargetKind?: IosRunTargetKind },
+    commandEnv: MobileCommandEnv,
+  ) {
     await mkdir(this.targetRoot, { recursive: true });
     let localIp: string | undefined;
     if (operation === "local") {
       const override = commandEnv.AKAN_PUBLIC_CLIENT_HOST ?? process.env.AKAN_PUBLIC_CLIENT_HOST;
-      const resolution = selectLocalDevHost(os.networkInterfaces(), { override });
+      const resolution = await this.#resolveLocalDevHost({ override, platform, iosRunTargetKind });
       localIp = resolution.host;
       this.#logDevHostResolution(resolution, commandEnv);
     }
@@ -1118,11 +1161,36 @@ export class CapacitorApp {
     await Bun.write(path.join(this.targetRoot, "capacitor.config.json"), content);
     return content;
   }
+  // An explicit override always wins; an emulator/simulator run reaches the host machine through a
+  // loopback alias (10.0.2.2 / localhost), so LAN detection only applies to physical-device runs.
+  async #resolveLocalDevHost({
+    override,
+    platform,
+    iosRunTargetKind,
+  }: {
+    override?: string;
+    platform?: MobilePlatform;
+    iosRunTargetKind?: IosRunTargetKind;
+  }): Promise<LocalDevHostResolution> {
+    const resolution = selectLocalDevHost(os.networkInterfaces(), { override });
+    if (resolution.source === "override") return resolution;
+    if (platform === "ios" && iosRunTargetKind === "simulator")
+      return { ...resolution, host: "localhost", source: "platform" };
+    if (platform === "android") {
+      try {
+        const host = getAndroidLocalServerHost(await this.#spawn("adb", ["devices"]), resolution.host);
+        return host === resolution.host ? resolution : { ...resolution, host, source: "platform" };
+      } catch {
+        return resolution;
+      }
+    }
+    return resolution;
+  }
   // Surface the live-reload URL a physical device must reach, and warn when auto-detection landed on
   // a likely-unreachable host so a blank WebView is not mistaken for an app bug.
   #logDevHostResolution(resolution: LocalDevHostResolution, commandEnv: MobileCommandEnv) {
     this.app.log(`Mobile live-reload server: ${this.#localCsrUrl(resolution.host, commandEnv)}`);
-    if (resolution.source === "override") return;
+    if (resolution.source === "override" || resolution.source === "platform") return;
     const suspicious = resolution.host === "127.0.0.1" || resolution.host.startsWith("169.254.");
     const alternatives = resolution.candidates.filter((candidate) => candidate.address !== resolution.host);
     if (!suspicious && alternatives.length === 0) return;
@@ -1332,20 +1400,29 @@ export class CapacitorApp {
     command: string,
     args: string[] = [],
     { operation, env }: Pick<RunConfig, "operation" | "env">,
-    options: Parameters<AppExecutor["spawn"]>[2] = {},
+    options: SpawnMobileOptions = {},
   ) {
+    const { iosRunTargetKind, platform, ...spawnOptions } = options;
     const mobileEnv = { ...(await this.#commandEnv(operation, env)), ...options.env };
-    const configContent = await this.#writeCapacitorConfig({ operation }, mobileEnv);
+    const configContent = await this.#writeCapacitorConfig(
+      { operation, platform: platform ?? this.#inferMobilePlatform(args), iosRunTargetKind },
+      mobileEnv,
+    );
     await this.#writeRootCapacitorConfig(configContent);
     try {
       return await this.#spawn(command, args, {
-        ...options,
+        ...spawnOptions,
         env: mobileEnv,
       });
     } finally {
       await this.#clearRootCapacitorConfigs();
     }
   }
+  #inferMobilePlatform(args: string[]): MobilePlatform | undefined {
+    if (args.includes("android")) return "android";
+    if (args.includes("ios")) return "ios";
+    return undefined;
+  }
   async addCamera() {
     await this.#setPermissionInIos({
       cameraUsageDescription: "$(PRODUCT_NAME) requires access to the camera to take photos.",
@@ -1446,14 +1523,31 @@ export class CapacitorApp {
       let end = index;
       while (end < lines.length && !/^\s*\};\s*$/.test(lines[end] ?? "")) end++;
       const settings = lines.slice(start, end + 1);
-      if (settings.some((setting) => setting.includes("CODE_SIGN_ENTITLEMENTS"))) continue;
+      const configName = lines.slice(end + 1, end + 8).find((setting) => setting.includes("name = ")) ?? "";
       const indent = line.match(/^\s*/)?.[0] ?? "";
-      lines.splice(index, 0, `${indent}CODE_SIGN_ENTITLEMENTS = ${entitlementsRelPath};`);
-      index++;
-      changed = true;
+      const insertSettings = [];
+      if (!settings.some((setting) => setting.includes("CODE_SIGN_ENTITLEMENTS"))) {
+        insertSettings.push(`${indent}CODE_SIGN_ENTITLEMENTS = ${entitlementsRelPath};`);
+      }
+      if (
+        configName.includes("name = Debug;") &&
+        !settings.some((setting) => setting.includes("CODE_SIGN_ALLOW_ENTITLEMENTS_MODIFICATION"))
+      ) {
+        insertSettings.push(`${indent}CODE_SIGN_ALLOW_ENTITLEMENTS_MODIFICATION = YES;`);
+      }
+      if (insertSettings.length > 0) {
+        lines.splice(index, 0, ...insertSettings);
+        index += insertSettings.length;
+        changed = true;
+      }
     }
     if (changed) await writeFile(pbxprojPath, lines.join("\n"));
   }
+  async #setCodeSignEntitlementsInIosIfExists(entitlementsRelPath: string) {
+    const entitlementsPath = path.join(this.app.cwdPath, this.iosProjectPath, entitlementsRelPath);
+    if (!(await Bun.file(entitlementsPath).exists())) return;
+    await this.#setCodeSignEntitlementsInIos(entitlementsRelPath);
+  }
   async #setUrlSchemesInAndroid(schemes: string[]) {
     const manifestPath = path.join(this.app.cwdPath, this.androidRootPath, "app/src/main/AndroidManifest.xml");
     let manifest = await readFile(manifestPath, "utf8");

package/executors.test.ts

@@ -149,8 +149,10 @@ describe("Executor filesystem helpers", () => {
       "AI Development Guide",
     );
     expect(await readFile(path.join(root, "workspace/docs/GENERATED.md"), "utf8")).toContain("Generated Akan Files");
+    // Rules and their plugin registrations live in the package's base config, so a framework release reaches an
+    // existing workspace on `bun update` — the workspace file only extends it and scopes its own files.
     expect(await readFile(path.join(root, "workspace/biome.json"), "utf8")).toContain(
-      "./node_modules/@akanjs/devkit/lint/no-import-client-functions.grit",
+      '"extends": ["@akanjs/devkit/biome.base.json"]',
     );
   });
 

package/executors.ts

@@ -42,6 +42,7 @@ import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from
 import { FileSys } from "./fileSys";
 import { getDirname } from "./getDirname";
 import { Linter } from "./linter";
+import { resolveRepoName } from "./repoIdentity";
 import { AppInfo, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
 import { Spinner } from "./spinner";
 // Type-only: the implementation is loaded on demand in `getTypeChecker` to keep `typescript` out of
@@ -788,7 +789,7 @@ export class WorkspaceExecutor extends Executor {
   static #execs = new Map<string, WorkspaceExecutor>();
   static fromRoot({
     workspaceRoot = process.cwd(),
-    repoName = path.basename(process.cwd()),
+    repoName = resolveRepoName(workspaceRoot),
   }: {
     workspaceRoot?: string;
     repoName?: string;

package/frontendBuild/allRoutesBuilder.ts

@@ -47,11 +47,24 @@ export class AllRoutesBuilder {
     this.#app.verbose(`[build-all] discovered ${seedIndex.entries.length} routes`);
     this.#discovery = await GraphClientEntryDiscovery.create(this.#app);
 
+    // Discovery first, bundling second. Chunk splitting only dedupes within one `Bun.build`, so a
+    // dependency shared by entries from different routes was emitted once per route that reached it.
+    // Discovery is cached and does no bundling, so collecting every entry up front costs almost nothing.
+    const allEntries: string[] = [];
+    const seen = new Set<string>();
     for (const entry of seedIndex.entries) {
       const seeds = Array.from(new Set([...seedIndex.globalLayoutFiles, ...entry.seeds]));
-      const delta = await this.#buildRoute(entry.routeId, seeds);
-      this.#mergeRoute(entry.routeId, delta);
+      for (const discovered of await this.#discovery.discover(seeds)) {
+        if (seen.has(discovered)) continue;
+        seen.add(discovered);
+        allEntries.push(discovered);
+      }
+      this.#routeIds.push(entry.routeId);
     }
+    this.#app.verbose(`[build-all] ${allEntries.length} client entries across ${this.#routeIds.length} routes`);
+
+    const delta = await this.#buildEntries(allEntries);
+    this.#mergeDelta(delta);
     this.#merged.knownEntries = Array.from(this.#knownSet);
 
     const manifest: RoutesManifest = {
@@ -76,28 +89,34 @@ export class AllRoutesBuilder {
     return { manifest, manifestPath, seedIndex };
   }
 
-  async #buildRoute(routeId: string, seeds: string[]): Promise<BuildRouteClientResult> {
+  async #buildEntries(entries: string[]): Promise<BuildRouteClientResult> {
     if (!this.#discovery) throw new Error("[build-all] client entry discovery is not initialized");
+    if (entries.length === 0)
+      return {
+        manifestDelta: {},
+        ssrManifestDelta: { moduleLoading: null, moduleMap: {} },
+        newEntries: [],
+        clientDeps: [],
+      };
     const started = Date.now();
     const delta = await new RouteClientBuilder({
       app: this.#app,
-      routeId,
-      seeds,
+      seeds: [],
+      entries,
       artifact: this.#artifact,
       knownEntries: this.#knownSet,
       discovery: this.#discovery,
       command: this.#command,
     }).build();
-    this.#app.verbose(`[build-all] ${routeId} +${delta.newEntries.length} entries (${Date.now() - started}ms)`);
+    this.#app.verbose(`[build-all] bundled ${delta.newEntries.length} entries (${Date.now() - started}ms)`);
     return delta;
   }
 
-  #mergeRoute(routeId: string, delta: BuildRouteClientResult): void {
+  #mergeDelta(delta: BuildRouteClientResult): void {
     for (const [key, row] of Object.entries(delta.manifestDelta)) this.#merged.clientManifest[key] = row;
     for (const [url, byName] of Object.entries(delta.ssrManifestDelta.moduleMap)) {
       this.#merged.ssrManifest.moduleMap[url] = byName;
     }
     for (const abs of delta.newEntries) this.#knownSet.add(abs);
-    this.#routeIds.push(routeId);
   }
 }

package/frontendBuild/cssCandidateCache.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CssCandidateCache } from "./cssCandidateCache";
+
+const scan = async (source: string) => {
+  const dir = await mkdtemp(path.join(tmpdir(), "css-candidate-"));
+  const file = path.join(dir, "probe.tsx");
+  await writeFile(file, source);
+  return await new CssCandidateCache(path.join(dir, "cache.json")).load().then((c) => c.candidatesFor(file));
+};
+
+describe("CssCandidateCache token extraction", () => {
+  test("keeps plain utilities, variants and arbitrary values whole", async () => {
+    const candidates = await scan(`const c = "w-full hover:bg-muted md:w-1/2 text-[#fff]";`);
+    expect(candidates).toEqual(expect.arrayContaining(["w-full", "hover:bg-muted", "md:w-1/2", "text-[#fff]"]));
+  });
+
+  // A candidate that opens with `[` used to be torn into `_td` + `px-3`, so every descendant-variant
+  // rule in the framework compiled to nothing and its element rendered unstyled with no diagnostic.
+  test("keeps an arbitrary variant that starts with a bracket", async () => {
+    const candidates = await scan(`const c = "[&_td]:px-3 [&>*]:gap-2 [&_tbody_tr]:border-t";`);
+    expect(candidates).toEqual(expect.arrayContaining(["[&_td]:px-3", "[&>*]:gap-2", "[&_tbody_tr]:border-t"]));
+    expect(candidates).not.toContain("_td");
+  });
+
+  // A labelled tuple type looks like an arbitrary property, and compiles to a rule whose declaration is
+  // TypeScript. `optimize()` cannot parse that, and drops far more than the offending rule on its way
+  // out — every variant in the build went missing, so nothing hovered, focused or responded to a
+  // breakpoint. Tailwind writes a space in an arbitrary value as `_`, so whitespace rules the token out.
+  test("ignores a labelled tuple type that only looks like an arbitrary property", async () => {
+    const candidates = await scan(
+      `type A = [key: string, make: () => unknown][];\ntype B = [setQueryArgs: (a: Args) => Args, options?: Policy];`,
+    );
+    expect(candidates.filter((candidate) => candidate.startsWith("["))).toEqual([]);
+  });
+});

package/frontendBuild/cssCandidateCache.ts

@@ -1,7 +1,19 @@
 import { stat } from "node:fs/promises";
 
-/** Every identifier-ish token in a source file is a potential tailwind class. */
-const CANDIDATE_RE = /-?[\w@][\w:/.-]*(?:\[[^\]]+\][\w:/.-]*)*/g;
+/**
+ * Every identifier-ish token in a source file is a potential tailwind class. The leading alternation
+ * matters: an arbitrary variant starts with `[` (`[&_td]:px-3`, `[&>*]:gap-2`), and a pattern anchored
+ * on a word character tears it into `_td` plus `px-3` instead — both meaningless, so the rule compiles
+ * to nothing and the element silently renders unstyled.
+ *
+ * Brackets must hold no whitespace. Tailwind spells a space in an arbitrary value `_`, so a bracket
+ * group containing one is never a class — but it is exactly the shape of a labelled tuple type
+ * (`[key: string, make: () => unknown]`). Scanned as a candidate, that compiles to an arbitrary
+ * *property* rule carrying TypeScript as its declaration, which the lightningcss pass in `optimize()`
+ * cannot parse; its error recovery then drops a whole span of the stylesheet — in practice every
+ * variant rule in the build, leaving hover, focus, responsive and dark styles silently absent.
+ */
+const CANDIDATE_RE = /-?(?:[\w@]|\[[^\]\s]+\])[\w:/.-]*(?:\[[^\]\s]+\][\w:/.-]*)*/g;
 
 interface CachedFile {
   mtimeMs: number;
@@ -27,7 +39,7 @@ interface CacheFile {
  */
 export class CssCandidateCache {
   /** Bump when the token regex or the entry shape changes, so stale extractions are not reused. */
-  static readonly #version = 1;
+  static readonly #version = 3;
   readonly #path: string;
   readonly #entries = new Map<string, CachedFile>();
   #dirty = false;

package/frontendBuild/cssCompiler.ts

@@ -46,6 +46,8 @@ export class CssCompiler {
   #fileExistsCache = new Map<string, Promise<boolean>>();
   #resolvedFileCache = new Map<string, Promise<string | null>>();
   #resolvedSpecifierCache = new Map<string, Promise<string | null>>();
+  /** Every stylesheet this compile reached, entry points and `@import` targets alike. */
+  #discoveredCssPaths = new Set<string>();
 
   #fileExists(absPath: string): Promise<boolean> {
     let cached = this.#fileExistsCache.get(absPath);
@@ -76,13 +78,16 @@ export class CssCompiler {
   }
   async getCss({ refresh }: { refresh?: boolean } = {}) {
     if (this.#cssText !== null && !refresh) return this.#cssText;
+    this.#discoveredCssPaths.clear();
     const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh });
     this.#cssText = await this.compileCss(cssPaths, sourcePaths);
+    await this.#warnUnreachableStylesheets();
     return this.#cssText;
   }
 
   async getCssByBasePath({ refresh }: { refresh?: boolean } = {}): Promise<Record<string, string>> {
     if (this.#cssTextByBasePath !== null && !refresh) return this.#cssTextByBasePath;
+    this.#discoveredCssPaths.clear();
     const akanConfig = await this.#app.getConfig({ refresh });
     const pageKeys = await this.#app.getPageKeys({ refresh });
     const basePaths = [...akanConfig.basePaths];
@@ -111,9 +116,26 @@ export class CssCompiler {
       }),
     ]);
     this.#cssTextByBasePath = Object.fromEntries(cssEntries);
+    await this.#warnUnreachableStylesheets();
     return this.#cssTextByBasePath;
   }
 
+  /**
+   * A stylesheet under `page/` reaches the build only by being imported from a route source. One that nothing
+   * imports compiles to nothing and reports success, which is indistinguishable from an empty theme — so say it
+   * out loud once per compile rather than leaving it to be noticed as unstyled elements in the browser.
+   */
+  async #warnUnreachableStylesheets() {
+    const pageDir = path.join(this.#app.cwdPath, "page");
+    const glob = new Bun.Glob("**/*.css");
+    for await (const cssPath of glob.scan({ cwd: pageDir, absolute: true })) {
+      // `(libs)` is a link farm: the same file is discovered under its real path in `libs/`, never this one.
+      if (cssPath.includes(`${path.sep}(libs)${path.sep}`)) continue;
+      if (this.#discoveredCssPaths.has(cssPath)) continue;
+      this.#logger.warn(`css ${path.relative(this.#app.cwdPath, cssPath)} is imported by no route and never compiled`);
+    }
+  }
+
   async discoverCss({ refresh }: { refresh?: boolean } = {}): Promise<string[]> {
     const { cssPaths } = await this.discoverCssAndSources({ refresh });
     return cssPaths;
@@ -180,7 +202,33 @@ export class CssCompiler {
       }
     }
 
-    return { cssPaths: [...cssFiles], sourcePaths: [...sourceFiles] };
+    const tokenPaths = await this.#libTokenStylesheets(sourceFiles);
+    const cssPaths = [...new Set([...tokenPaths, ...cssFiles])];
+    for (const cssPath of cssPaths) this.#discoveredCssPaths.add(cssPath);
+    return { cssPaths, sourcePaths: [...sourceFiles] };
+  }
+
+  /**
+   * `libs/<lib>/ui/tokens.css` of every lib the page graph reached, so a lib can own the fixed colours its own
+   * components need instead of each consuming app re-declaring them. Ordered ahead of the app's stylesheets:
+   * the app is the last word on any variable both declare.
+   */
+  async #libTokenStylesheets(sourceFiles: Set<string>): Promise<string[]> {
+    const libsRoot = path.join(this.#app.workspace.workspaceRoot, "libs");
+    const libNames = new Set<string>();
+    for (const filePath of sourceFiles) {
+      const relPath = path.relative(libsRoot, filePath);
+      if (relPath.startsWith("..") || path.isAbsolute(relPath)) continue;
+      const [libName] = relPath.split(path.sep);
+      if (libName) libNames.add(libName);
+    }
+    const tokenPaths = await Promise.all(
+      [...libNames].sort().map(async (libName) => {
+        const tokensPath = path.join(libsRoot, libName, "ui/tokens.css");
+        return (await this.#fileExists(tokensPath)) ? tokensPath : null;
+      }),
+    );
+    return tokenPaths.filter((tokensPath): tokensPath is string => !!tokensPath);
   }
   async compileCss(cssPaths: string[], sourcePaths: string[]): Promise<string> {
     if (cssPaths.length === 0) return "";
@@ -222,12 +270,22 @@ export class CssCompiler {
 
   async #loadStylesheet(id: string, fromBase: string) {
     const p = await this.#resolveCssImport(id, fromBase);
+    this.#discoveredCssPaths.add(p);
     const content = await Bun.file(p).text();
     return { path: p, base: path.dirname(p), content };
   }
 
+  /**
+   * Every specifier is verified here, path-shaped ones included. An `@import` the pipeline cannot resolve is
+   * a build error and never a no-op: the vocabulary closure means a component whose token declaration failed
+   * to load renders unstyled, which nothing downstream can distinguish from a design choice.
+   */
   async #resolveCssImport(id: string, fromBase: string): Promise<string> {
-    if (id.startsWith(".") || id.startsWith("/")) return path.resolve(fromBase, id);
+    if (id.startsWith(".") || id.startsWith("/")) {
+      const filePath = path.resolve(fromBase, id);
+      if (await this.#fileExists(filePath)) return filePath;
+      throw new Error(`[css] failed to resolve stylesheet import "${id}" from ${fromBase} (no file at ${filePath})`);
+    }
     const resolver = await this.#getCssImportResolver();
     const resolved = await resolver.resolve(id, fromBase);
     if (resolved) return resolved;

package/frontendBuild/cssImportResolver.ts

@@ -106,14 +106,15 @@ export class CssImportResolver {
       const pkg = await Bun.file(pkgPath).json();
       const subpath = id === pkgName ? "." : `.${id.slice(pkgName.length)}`;
       const exportValue = pkg.exports?.[subpath];
-      const styleEntry =
-        (typeof exportValue === "string"
+      const exportedEntry =
+        typeof exportValue === "string"
           ? exportValue
-          : exportValue?.style || exportValue?.import || exportValue?.default) ||
-        pkg.exports?.["."]?.style ||
-        pkg.style ||
-        "index.css";
-      return await this.#firstExisting(path.resolve(pkgDir, styleEntry));
+          : exportValue?.style || exportValue?.import || exportValue?.default;
+      if (exportedEntry) return await this.#firstExisting(path.resolve(pkgDir, exportedEntry));
+      //* A subpath names a file inside the package, so it resolves literally. Falling back to the package's own
+      //* style entry here would load a different stylesheet than the author asked for and report success.
+      if (subpath !== ".") return await this.#firstExisting(path.resolve(pkgDir, subpath));
+      return await this.#firstExisting(path.resolve(pkgDir, pkg.exports?.["."]?.style || pkg.style || "index.css"));
     } catch {
       return null;
     }

package/frontendBuild/frontendBuild.test.ts

@@ -391,6 +391,20 @@ describe("CssImportResolver", () => {
     expect(await resolver.resolve("@libs/ui/missing", root)).toBeNull();
   });
 
+  test("never substitutes the package stylesheet for a subpath that does not exist", async () => {
+    const root = await makeTempRoot();
+    await write(
+      path.join(root, "node_modules/vendor/package.json"),
+      JSON.stringify({ name: "vendor", style: "index.css" }),
+    );
+    await write(path.join(root, "node_modules/vendor/index.css"), ".vendor {}\n");
+
+    const resolver = new CssImportResolver(root, {});
+
+    expect(await resolver.resolve("vendor", root)).toBe(path.join(root, "node_modules/vendor/index.css"));
+    expect(await resolver.resolve("vendor/ui/tokens.css", root)).toBeNull();
+  });
+
   test("resolves css from single-package Akan workspace subpaths", async () => {
     const root = await makeTempRoot();
     await write(path.join(root, "pkgs/akanjs/ui/styles.css"), "body {}\n");
@@ -428,4 +442,44 @@ describe("CssCompiler", () => {
 
     expect(css).toContain(".text-fuchsia-500");
   });
+
+  test("fails loudly on a stylesheet import that resolves to nothing", async () => {
+    const root = await makeTempRoot();
+    const cssPath = path.join(root, "apps/demo/page/styles.css");
+    await write(cssPath, '@import "../../../libs/shared/ui/tokens.css";\n');
+
+    const compiler = new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath: path.join(root, "apps/demo"),
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+    } as never);
+
+    await expect(compiler.compileCss([cssPath], [])).rejects.toThrow(
+      /failed to resolve stylesheet import "\.\.\/\.\.\/\.\.\/libs\/shared\/ui\/tokens\.css"/,
+    );
+  });
+
+  test("compiles lib-owned tokens ahead of the app stylesheets that may override them", async () => {
+    const root = await makeTempRoot();
+    const appDir = path.join(root, "apps/demo");
+    await write(
+      path.join(appDir, "page/_index.tsx"),
+      'import "./styles.css";\nimport { Card } from "@libs/shared/ui";\nexport default () => <Card />;\n',
+    );
+    await write(path.join(appDir, "page/styles.css"), ":root { --brand: #111111; }\n");
+    await write(path.join(root, "libs/shared/ui/index.ts"), "export const Card = () => null;\n");
+    await write(path.join(root, "libs/shared/ui/tokens.css"), ":root { --kakao: #fee500; }\n");
+    await write(path.join(root, "libs/unused/ui/tokens.css"), ":root { --unused: #000000; }\n");
+
+    const compiler = new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath: appDir,
+      getPageKeys: async () => ["./_index.tsx"],
+      getConfig: async () => ({ barrelImports: [] }),
+      getTsConfig: async () => ({ compilerOptions: { paths: { "@libs/*": ["./libs/*"] } } }),
+    } as never);
+    const { cssPaths } = await compiler.discoverCssAndSources();
+
+    expect(cssPaths).toEqual([path.join(root, "libs/shared/ui/tokens.css"), path.join(appDir, "page/styles.css")]);
+  });
 });