@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/fileEditor.ts

@@ -17,57 +17,29 @@ export class FileEditor {
   }
 
   find(pattern: string | RegExp): number {
-    const lines = this.#content.split("\n");
     const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
-
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (!line) continue;
-      if (regex.test(line)) return i;
-    }
-
-    return -1;
+    return this.#content.split("\n").findIndex((line) => !!line && regex.test(line));
   }
 
   findAll(pattern: string | RegExp): number[] {
-    const lines = this.#content.split("\n");
     const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
-    const matches: number[] = [];
-
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (!line) continue;
-      if (regex.test(line)) matches.push(i);
-    }
-
-    return matches;
+    return this.#content.split("\n").flatMap((line, index) => (line && regex.test(line) ? [index] : []));
   }
 
   insertAfter(pattern: string | RegExp, data: string): this {
-    const lineIndex = this.find(pattern);
-
-    if (lineIndex === -1) {
-      throw new Error(`Pattern not found: ${pattern}`);
-    }
-
-    const lines = this.#content.split("\n");
-    lines.splice(lineIndex + 1, 0, data);
-    this.#content = lines.join("\n");
-
-    return this;
+    return this.#insertAt(pattern, data, 1);
   }
 
   insertBefore(pattern: string | RegExp, data: string): this {
-    const lineIndex = this.find(pattern);
-
-    if (lineIndex === -1) {
-      throw new Error(`Pattern not found: ${pattern}`);
-    }
+    return this.#insertAt(pattern, data, 0);
+  }
 
+  #insertAt(pattern: string | RegExp, data: string, offset: number): this {
+    const lineIndex = this.find(pattern);
+    if (lineIndex === -1) throw new Error(`Pattern not found: ${pattern}`);
     const lines = this.#content.split("\n");
-    lines.splice(lineIndex, 0, data);
+    lines.splice(lineIndex + offset, 0, data);
     this.#content = lines.join("\n");
-
     return this;
   }
 

package/{getDirname.test.ts → fileSys.test.ts}

@@ -1,12 +1,14 @@
 import { describe, expect, test } from "bun:test";
 import path from "node:path";
-import { getDirname } from "./getDirname";
+import { pathToFileURL } from "node:url";
+import { getDirname } from "./fileSys";
 
 describe("getDirname", () => {
   test("converts file URLs to filesystem paths", () => {
-    const dirname = getDirname("file:///tmp/akan%20workspace/index.ts");
+    const filePath = path.resolve("/tmp/akan workspace/index.ts");
+    const dirname = getDirname(pathToFileURL(filePath).href);
 
-    expect(dirname).toBe(path.join("/tmp", "akan workspace"));
+    expect(dirname).toBe(path.dirname(filePath));
   });
 
   test("keeps Windows drive paths valid when running on Windows", () => {

package/fileSys.ts

@@ -1,6 +1,10 @@
 import { lstat, rename, rm, stat } from "node:fs/promises";
+import nodePath from "node:path";
+import { fileURLToPath } from "node:url";
 import { Logger } from "akanjs/common";
 
+export const getDirname = (url: string) => nodePath.dirname(fileURLToPath(url));
+
 export class FileSys {
   static logger = new Logger("FileSys");
   static async fileExists(path: string) {
@@ -39,24 +43,33 @@ export class FileSys {
   static async writeText(path: string, content: string) {
     return await Bun.file(path).write(content);
   }
-  /**
-   * Replaces a file in one `rename`, so a concurrent reader sees either the old bytes or the new ones.
-   * Generated barrels are written by every dev server watching the same `libs/` tree while those same
-   * servers' watchers are reading them, and a half-written barrel reads back as a user edit.
-   *
-   * The temp file is a sibling because `rename` is only atomic within a filesystem, and it lands in a
-   * watched directory — the `.tmp` suffix is what `HmrChangeClassifier` ignores it by.
-   */
+  // One `rename`, so a watcher never reads a half-written barrel as a user edit. The temp is a sibling (rename is atomic
+  // only within a filesystem), and its `.tmp` suffix is what `HmrChangeClassifier` ignores it by.
   static async writeTextAtomic(filePath: string, content: string) {
     const temp = `${filePath}.${process.pid}.${Date.now().toString(36)}.tmp`;
     try {
       await Bun.write(temp, content);
-      await rename(temp, filePath);
+      await FileSys.replace(temp, filePath);
     } catch (error) {
       await rm(temp, { force: true }).catch(() => undefined);
       throw error;
     }
   }
+  static readonly #replaceAttempts = 100;
+  // Windows refuses to rename over a file another process has open (EPERM, or EACCES/EBUSY). A reader holds it for one
+  // read, so the rename is retried for a few seconds instead of failing.
+  static async replace(temp: string, target: string) {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await rename(temp, target);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        const busy = process.platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY");
+        if (!busy || attempt >= FileSys.#replaceAttempts) throw error;
+        await Bun.sleep(Math.min(10 * attempt, 50));
+      }
+    }
+  }
   static async writeJson(path: string, content: object) {
     return await Bun.file(path).write(`${JSON.stringify(content, null, 2)}\n`);
   }

package/formSetterScanner.ts

@@ -1,22 +1,9 @@
 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.
- */
+// Only a setter passed by reference publishes its field (`data-akan-action`, agent tool). The grit rule flags only pure
+// forwarding wrappers; this counts every field left unpublished whatever the reason. A zero-parameter handler is a
+// button setting a constant, not a form control, so it is not counted.
 export class FormSetterScanner {
   static #fieldSetter = /^set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*$/;
 

package/frontendBuild/allRoutesBuilder.ts

@@ -14,11 +14,6 @@ export interface BuildAllRoutesResult {
   seedIndex: RouteSeedIndex;
 }
 
-/**
- * Walk every route in `pages` and produce its client bundle up-front.
- * Intended to run under `akan build` (production) so the serve path
- * never needs to compile.
- */
 export class AllRoutesBuilder {
   #app: App;
   #artifact: BaseBuildArtifact;
@@ -47,23 +42,16 @@ 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>();
+    // Every route's entries go into one Bun.build: chunk splitting only dedupes within a single build.
+    const allEntries = new Set<string>();
     for (const entry of seedIndex.entries) {
       const seeds = Array.from(new Set([...seedIndex.globalLayoutFiles, ...entry.seeds]));
-      for (const discovered of await this.#discovery.discover(seeds)) {
-        if (seen.has(discovered)) continue;
-        seen.add(discovered);
-        allEntries.push(discovered);
-      }
+      for (const discovered of await this.#discovery.discover(seeds)) allEntries.add(discovered);
       this.#routeIds.push(entry.routeId);
     }
-    this.#app.verbose(`[build-all] ${allEntries.length} client entries across ${this.#routeIds.length} routes`);
+    this.#app.verbose(`[build-all] ${allEntries.size} client entries across ${this.#routeIds.length} routes`);
 
-    const delta = await this.#buildEntries(allEntries);
+    const delta = await this.#buildEntries([...allEntries]);
     this.#mergeDelta(delta);
     this.#merged.knownEntries = Array.from(this.#knownSet);
 
@@ -113,10 +101,8 @@ export class AllRoutesBuilder {
   }
 
   #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;
-    }
+    Object.assign(this.#merged.clientManifest, delta.manifestDelta);
+    Object.assign(this.#merged.ssrManifest.moduleMap, delta.ssrManifestDelta.moduleMap);
     for (const abs of delta.newEntries) this.#knownSet.add(abs);
   }
 }

package/frontendBuild/autoImportSync.test.ts

@@ -1,21 +1,18 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { tempDirs } from "../testHelpers";
 import { AutoImportSync, transformSource } from "./autoImportSync";
 
-const tempRoots: string[] = [];
+const makeTempRoot = tempDirs("akan-auto-import-");
 
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-auto-import-"));
-  tempRoots.push(root);
-  return root;
+const seed = async (root: string, rel: string, content: string) => {
+  const abs = path.join(root, rel);
+  await mkdir(path.dirname(abs), { recursive: true });
+  await writeFile(abs, content);
+  return abs;
 };
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 const constantCtx = { role: "constant", scope: "libs", project: "shared" } as const;
 const documentCtx = { role: "document", scope: "libs", project: "shared" } as const;
 const serviceCtx = { role: "service", scope: "libs", project: "shared" } as const;
@@ -161,6 +158,19 @@ describe("transformSource — client role (package client entry)", () => {
     );
   });
 
+  test("never claims fetch from a file that calls the platform fetch", () => {
+    const globalOnly = `"use client";\n\nexport const toBlob = async (url: string) => await (await fetch(url)).blob();\n`;
+    const mixed = `"use client";\n\nexport const C = async (url: string) => (await fetch(url)).ok && fetch.me() && st.foo;\n`;
+    const passed = `"use client";\n\nexport const load = (get = fetch) => get("/a");\n`;
+
+    expect(transformSource(globalOnly, "CropImage.tsx", clientLibCtx)).toBeNull();
+    expect(transformSource(mixed, "C.Zone.tsx", clientLibCtx)).toBe(
+      `"use client";\nimport { st } from "@libs/shared/client";\n\nexport const C = async (url: string) => (await fetch(url)).ok && fetch.me() && st.foo;\n`,
+    );
+    expect(transformSource(passed, "load.ts", clientLibCtx)).toBeNull();
+    expect(transformSource(globalOnly, "x.store.ts", storeCtx)).toBeNull();
+  });
+
   test("handles webkit .ts files (no jsx) the same as tsx", () => {
     const source = `import { getEnv } from "akanjs/base";\n\nexport const load = () => fetch.me();\n`;
     const out = transformSource(source, "cookie.ts", clientLibCtx);
@@ -171,13 +181,6 @@ describe("transformSource — client role (package client entry)", () => {
 });
 
 describe("AutoImportSync.syncForBatch", () => {
-  const seed = async (root: string, rel: string, content: string) => {
-    const abs = path.join(root, rel);
-    await mkdir(path.dirname(abs), { recursive: true });
-    await writeFile(abs, content);
-    return abs;
-  };
-
   test("writes the fix once, then is idempotent", async () => {
     const root = await makeTempRoot();
     const abs = await seed(
@@ -296,9 +299,7 @@ describe("AutoImportSync.syncForBatch", () => {
 
   test("leaves JS globals and ambiguous domain names alone", async () => {
     const root = await makeTempRoot();
-    // `Map` is a real model here but must not shadow the JS global.
     await seed(root, "libs/x/lib/map/map.constant.ts", `export class Map extends via {}\n`);
-    // `Dup` is exported by two files → ambiguous → skipped.
     await seed(root, "libs/x/lib/a/a.constant.ts", `export class Dup {}\n`);
     await seed(root, "libs/x/lib/b/b.constant.ts", `export class Dup {}\n`);
     const consumer = await seed(
@@ -335,7 +336,7 @@ describe("AutoImportSync.syncForBatch", () => {
 
   test("srvkit: does not import a barrel whose file is absent", async () => {
     const root = await makeTempRoot();
-    await seed(root, "libs/x/lib/dict.ts", `export const x = 1;\n`); // no lib/srv.ts
+    await seed(root, "libs/x/lib/dict.ts", `export const x = 1;\n`);
     const file = await seed(root, "libs/x/srvkit/api.ts", `export const f = () => Err.of(srv.user);\n`);
     const sync = new AutoImportSync({ workspaceRoot: root });
 
@@ -357,20 +358,11 @@ describe("AutoImportSync.syncForBatch", () => {
 });
 
 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 generated = await seed(root, "libs/shared/lib/__lib/lib.constant.ts", needsImport);
+    const scalar = await seed(root, "libs/shared/lib/__scalar/money/money.constant.ts", needsImport);
 
     const result = await new AutoImportSync({ workspaceRoot: root }).syncForBatch([generated, scalar]);
 
@@ -380,11 +372,9 @@ describe("AutoImportSync — scope", () => {
     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(
+    const file = await seed(
       root,
       "libs/shared/lib/task/task.constant.ts",
       "export class A {\n  count = field(Int);\n}\n",
@@ -397,11 +387,10 @@ describe("AutoImportSync — scope", () => {
     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(
+    const good = await seed(
       root,
       "libs/shared/lib/task/task.constant.ts",
       "export class A {\n  count = field(Int);\n}\n",

package/frontendBuild/autoImportSync.ts

@@ -3,11 +3,7 @@ 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)
-//* are inserted automatically. Detection is a closed-registry scan: we only look for a fixed, framework-owned
-//* set of identifiers per file role, so no type information is required. Writes only happen on a real diff,
-//* which keeps the watcher from looping on its own edits.
+//* Closed-registry scan (no type information); writes only on a real diff, or the watcher loops on its own edits.
 
 export interface AutoImportSyncResult {
   changedFiles: string[];
@@ -39,13 +35,9 @@ interface FileContext {
 interface ImportTarget {
   specifier: string;
   kind: ImportKind;
-  //* When true, emitted as a type-only import (`import type { X }`, or inline `type X` when mixed with
-  //* value names from the same specifier). Only meaningful for `kind: "named"`.
   typeOnly?: boolean;
 }
 
-//* A registry rule: the identifiers `names` should be imported from `specifier` with the given `kind`.
-//* `specifier` may depend on the file's package (e.g. the client entrypoint).
 interface ImportRule {
   names: string[];
   specifier: string | ((ctx: FileContext) => string);
@@ -55,23 +47,19 @@ interface ImportRule {
 
 const TEST_FILE_RE = /\.(test|spec)\.(ts|tsx)$/;
 
-//* Shared rules reused across roles. Domain (`lib/<model>/`) files sit at a fixed depth, so the
-//* relative barrels `../cnst`, `../db`, `../srv`, `../dict` are always correct for them.
+//* Domain files sit at a fixed depth (`lib/<model>/`), so the relative barrels below are always correct for them.
 const AKAN_BASE: ImportRule = {
   names: ["Int", "Float", "ID", "Any", "Upload", "enumOf", "dayjs"],
   specifier: "akanjs/base",
   kind: "named",
 };
-//* Type-only exports of akanjs/base — emitted as `type` imports (e.g. `import { type Dayjs, dayjs }`).
 const AKAN_BASE_TYPES: ImportRule = { names: ["Dayjs"], specifier: "akanjs/base", kind: "named", typeOnly: true };
 const CNST_NS: ImportRule = { names: ["cnst"], specifier: "../cnst", kind: "namespace" };
 const DB_NS: ImportRule = { names: ["db"], specifier: "../db", kind: "namespace" };
 const SRV_NS: ImportRule = { names: ["srv"], specifier: "../srv", kind: "namespace" };
 const ERR_DICT: ImportRule = { names: ["Err"], specifier: "../dict", kind: "named" };
 
-//* The closed registry, keyed by file role. Derived from an import-frequency scan across apps/libs;
-//* only high-confidence, framework-owned identifiers are listed (domain model/scalar refs are resolved
-//* separately). Order matters only when the same name could appear twice — keep names unique per role.
+//* Keep names unique per role: targetFor takes the first rule that lists a name.
 const RULES: Record<FileRole, ImportRule[]> = {
   constant: [AKAN_BASE, AKAN_BASE_TYPES, { names: ["via"], specifier: "akanjs/constant", kind: "named" }],
   document: [
@@ -143,8 +131,6 @@ const RULES: Record<FileRole, ImportRule[]> = {
   ],
 };
 
-//* Domain imports resolve open-ended model/scalar class refs against a per-package index, rather than
-//* a fixed registry. Only these roles opt in, and each may pull from the listed sibling file kinds.
 type DomainKind = "constant" | "document" | "signal";
 type DomainIndex = Map<string, { file: string; kind: DomainKind }[]>;
 const PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/;
@@ -153,17 +139,17 @@ const DOMAIN_ROLE_KINDS: Partial<Record<FileRole, DomainKind[]>> = {
   dictionary: ["constant", "document", "signal"],
   common: ["constant"],
 };
-//* lib barrel imports (srvkit/common): identifier -> generated `lib/<barrel>.ts` file + import shape.
-//* Their specifier depth is per-file (see `#libBarrelResolver`), so they can't live in the RULES table.
+//* srvkit/common import the lib barrels from a per-file depth, so they cannot live in the RULES table.
 const LIB_BARRELS: Record<string, { barrel: string; kind: ImportKind }> = {
   Err: { barrel: "dict", kind: "named" },
   db: { barrel: "db", kind: "namespace" },
   cnst: { barrel: "cnst", kind: "namespace" },
   srv: { barrel: "srv", kind: "namespace" },
 };
-//* ECMAScript/TS structural globals never resolved as domain symbols, so that a package model named
-//* e.g. `Map` cannot shadow the JS `Map` used in `new Map()`. Domain-y globals like `File` are allowed
-//* on purpose (they are real models here).
+//* Importing Akan's `fetch` over the platform global silently rebinds `fetch(url)`, so such a name is claimed
+//* only when every reference is member-shaped (`fetch.viewX()`).
+const GLOBAL_NAMES = new Set(["fetch"]);
+//* Structural globals a package model must not shadow (`new Map()`); `File` is left out on purpose — it is a real model.
 const DOMAIN_DENYLIST = new Set([
   "Map",
   "Set",
@@ -204,7 +190,6 @@ const DOMAIN_DENYLIST = new Set([
 
 export class AutoImportSync {
   readonly #workspaceRoot: string;
-  //* Per-package domain index (symbol -> source file), invalidated when a package's model file changes.
   readonly #domainCache = new Map<string, DomainIndex>();
 
   constructor({ workspaceRoot }: AutoImportSyncOptions) {
@@ -216,8 +201,6 @@ export class AutoImportSync {
     const errors: string[] = [];
     const seen = new Set<string>();
 
-    // Drop cached domain indexes for any package whose model files changed in this batch, so a newly
-    // added/renamed model is visible to references resolved later in the same batch.
     for (const file of files) {
       const pkgRoot = this.#domainPkgRootOf(file);
       if (pkgRoot) this.#domainCache.delete(pkgRoot);
@@ -240,8 +223,6 @@ export class AutoImportSync {
     return { changedFiles, errors };
   }
 
-  //* Resolve the role + package location for a file, or null when the file is out of scope
-  //* (outside apps/libs, a generated/declaration/test file, or a facet+extension we do not handle).
   #contextFor(abs: string): FileContext | null {
     const rel = path.relative(this.#workspaceRoot, abs);
     if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
@@ -251,9 +232,7 @@ 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.
+    //* `lib/__lib/` is rewritten by every `akan sync`, so an edit there is discarded; `lib/__scalar/` is real source.
     if (facet === "lib" && parts[3] === "__lib") return null;
     const role = roleFor(facet, base);
     if (!role) return null;
@@ -272,10 +251,6 @@ export class AutoImportSync {
     return true;
   }
 
-  //* Build the dynamic resolver for identifiers the static registry does not cover, or undefined when
-  //* the role has none. `srvkit`/`common` resolve the package's generated lib barrels (variable depth);
-  //* the domain roles resolve open-ended model/scalar refs against the per-package index. `common`
-  //* uses both — barrels first, then domain (the two symbol sets are disjoint).
   async #extraResolverFor(abs: string, ctx: FileContext) {
     const resolvers: ((symbol: string) => ImportTarget | null)[] = [];
     if (ctx.role === "srvkit" || ctx.role === "common") resolvers.push(await this.#libBarrelResolver(abs, ctx));
@@ -291,22 +266,17 @@ export class AutoImportSync {
     };
   }
 
-  //* Resolve an unbound PascalCase identifier to a relative import of the package model/scalar that
-  //* exports it (only when exactly one package file of an allowed kind exports that name).
   async #domainResolver(abs: string, ctx: FileContext, kinds: DomainKind[]) {
     const index = await this.#domainIndex(path.join(this.#workspaceRoot, ctx.scope, ctx.project));
     const fileDir = path.dirname(abs);
     return (symbol: string): ImportTarget | null => {
       if (!PASCAL_CASE_RE.test(symbol) || DOMAIN_DENYLIST.has(symbol)) return null;
       const entries = (index.get(symbol) ?? []).filter((entry) => kinds.includes(entry.kind));
-      if (entries.length !== 1) return null; // unknown or ambiguous → leave it alone
+      if (entries.length !== 1) return null;
       return { specifier: relativeSpecifier(fileDir, entries[0].file), kind: "named" };
     };
   }
 
-  //* srvkit/common files import the package's generated lib barrels from a variable depth
-  //* (`../lib/dict`, `../../lib/dict`, …). Resolve each barrel name to a path relative to this file,
-  //* but only for barrels that actually exist (so an absent `lib/srv.ts` never yields a broken import).
   async #libBarrelResolver(abs: string, ctx: FileContext) {
     const fileDir = path.dirname(abs);
     const libDir = path.join(this.#workspaceRoot, ctx.scope, ctx.project, "lib");
@@ -326,7 +296,6 @@ export class AutoImportSync {
     return index;
   }
 
-  //* The apps/libs package root for a model file (`*.constant/document/signal.ts` under `lib/`), else null.
   #domainPkgRootOf(file: string): string | null {
     const rel = path.relative(this.#workspaceRoot, path.resolve(file));
     if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
@@ -337,9 +306,6 @@ export class AutoImportSync {
   }
 }
 
-//* Which facet+extension combinations get auto-imports, and the role that drives their registry.
-//* `client` covers every file that pulls domain symbols from the package client entrypoint:
-//* lib UI (.tsx), the `ui`/`page` facets (.tsx), and the `webkit` facet (.ts/.tsx).
 const roleFor = (facet: string, base: string): FileRole | null => {
   if (facet === "lib") {
     if (base.endsWith(".constant.ts")) return "constant";
@@ -367,8 +333,7 @@ const targetFor = (symbol: string, ctx: FileContext): ImportTarget | null => {
   return null;
 };
 
-//* Returns the rewritten source, or null when nothing needs to change. `resolveExtra` (when supplied)
-//* handles identifiers not matched by the framework registry — domain model refs and srvkit barrels.
+/** The rewritten source, or null when nothing changes. */
 export const transformSource = (
   source: string,
   fileName: string,
@@ -378,13 +343,12 @@ export const transformSource = (
   const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKindFor(fileName));
   const bound = collectBoundNames(sf);
   const used = collectUsedReferences(sf);
+  const bareGlobals = collectBareGlobalReferences(sf);
 
-  // Group the needed symbols by their import target: framework registry first, then dynamic resolver.
-  // Named groups map each name to whether it is type-only, so we can emit `import type`/inline `type`.
   const namedBySpecifier = new Map<string, Map<string, boolean>>();
   const namespaceImports: { name: string; specifier: string }[] = [];
   for (const name of used) {
-    if (bound.has(name)) continue;
+    if (bound.has(name) || bareGlobals.has(name)) continue;
     const target = targetFor(name, ctx) ?? resolveExtra?.(name) ?? null;
     if (!target) continue;
     if (target.kind === "namespace") namespaceImports.push({ name, specifier: target.specifier });
@@ -418,8 +382,7 @@ export const transformSource = (
   for (const ns of namespaceImports) newStatements.push(`import * as ${ns.name} from "${ns.specifier}";`);
 
   if (newStatements.length > 0) {
-    // If the anchor import is itself being merged, fold the new lines into that edit to avoid a
-    // zero-width insertion sharing a boundary with the merge replacement.
+    // A zero-width insertion at the anchor's boundary would collide with the anchor's own merge edit.
     const anchorEdit = anchor ? edits.find((edit) => edit.start === anchor.getStart(sf)) : undefined;
     if (anchorEdit) anchorEdit.text = `${anchorEdit.text}\n${newStatements.join("\n")}`;
     else if (anchor)
@@ -438,8 +401,7 @@ export const transformSource = (
   return out === source ? null : out;
 };
 
-//* Every name introduced into scope: import bindings plus local declarations. Over-collecting only
-//* suppresses an insertion (safe); under-collecting would risk a duplicate import (unsafe).
+//* Over-collecting only suppresses an insertion; under-collecting would add a duplicate import.
 const collectBoundNames = (sf: ts.SourceFile): Set<string> => {
   const names = new Set<string>();
   const visit = (node: ts.Node) => {
@@ -478,8 +440,19 @@ const collectUsedReferences = (sf: ts.SourceFile): Set<string> => {
   return used;
 };
 
-//* True when the identifier reads a binding, as opposed to being a member name, property key, or
-//* declaration name. e.g. in `cnst.Coordinate`, `cnst` is a reference but `Coordinate` is not.
+const collectBareGlobalReferences = (sf: ts.SourceFile): Set<string> => {
+  const bare = new Set<string>();
+  const visit = (node: ts.Node) => {
+    if (ts.isIdentifier(node) && GLOBAL_NAMES.has(node.text) && isReferencePosition(node)) {
+      const parent = node.parent;
+      if (!(parent && ts.isPropertyAccessExpression(parent) && parent.expression === node)) bare.add(node.text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sf, visit);
+  return bare;
+};
+
 const isReferencePosition = (node: ts.Identifier): boolean => {
   const parent = node.parent;
   if (!parent) return true;
@@ -494,7 +467,7 @@ const isReferencePosition = (node: ts.Identifier): boolean => {
 
 interface ExistingNamedImport {
   decl: ts.ImportDeclaration;
-  names: Map<string, boolean>; // name -> type-only (whole-clause `import type` or inline `type`)
+  names: Map<string, boolean>;
 }
 
 const collectExistingNamedImports = (importDecls: ts.ImportDeclaration[]): Map<string, ExistingNamedImport> => {
@@ -505,7 +478,7 @@ const collectExistingNamedImports = (importDecls: ts.ImportDeclaration[]): Map<s
     if (!clause || !bindings || !ts.isNamedImports(bindings)) continue;
     if (!ts.isStringLiteral(decl.moduleSpecifier)) continue;
     const specifier = decl.moduleSpecifier.text;
-    if (map.has(specifier)) continue; // first same-specifier named import wins as the merge site
+    if (map.has(specifier)) continue;
     const names = new Map<string, boolean>();
     for (const el of bindings.elements) names.set(el.name.text, clause.isTypeOnly || el.isTypeOnly);
     map.set(specifier, { decl, names });
@@ -513,8 +486,6 @@ const collectExistingNamedImports = (importDecls: ts.ImportDeclaration[]): Map<s
   return map;
 };
 
-//* Render a named import, hoisting to `import type { … }` when every name is type-only and otherwise
-//* prefixing each type-only name with inline `type`. Names sorted case-insensitively (Biome order).
 const formatNamedImport = (specifier: string, names: Map<string, boolean>): string => {
   const entries = [...names.entries()].sort((a, b) => compareNames(a[0], b[0]));
   if (entries.every(([, isType]) => isType))
@@ -534,8 +505,7 @@ const directivePrologueEnd = (sf: ts.SourceFile): number => {
 
 const scriptKindFor = (fileName: string) => (fileName.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
 
-//* Case-insensitive primary order with a case-sensitive tie-break (uppercase first), matching Biome's
-//* import specifier sort — so e.g. `Dayjs` precedes `dayjs`.
+// Matches Biome's import-specifier sort: case-insensitive, uppercase first on a tie (`Dayjs` before `dayjs`).
 const compareNames = (a: string, b: string): number => {
   const [la, lb] = [a.toLowerCase(), b.toLowerCase()];
   if (la !== lb) return la < lb ? -1 : 1;
@@ -549,8 +519,6 @@ const fileExists = async (file: string) =>
     .then((s) => s.isFile())
     .catch(() => false);
 
-// ---- Domain index ---------------------------------------------------------------------------------
-
 const domainKindOf = (base: string): DomainKind | null => {
   if (base.endsWith(".constant.ts")) return "constant";
   if (base.endsWith(".document.ts")) return "document";
@@ -558,7 +526,6 @@ const domainKindOf = (base: string): DomainKind | null => {
   return null;
 };
 
-//* Scan a package `lib/` for model files and index their exported PascalCase declarations.
 const buildDomainIndex = async (libDir: string): Promise<DomainIndex> => {
   const index: DomainIndex = new Map();
   for (const file of await collectDomainFiles(libDir)) {
@@ -604,7 +571,6 @@ const exportedPascalNames = (source: string, fileName: string): string[] => {
   return names.filter((name) => PASCAL_CASE_RE.test(name));
 };
 
-//* Relative module specifier from a file's directory to a target file, extension stripped, `./`-anchored.
 const relativeSpecifier = (fromDir: string, toFile: string): string => {
   const rel = path
     .relative(fromDir, toFile)