akanjs 0.0.1 → 2.0.0-beta.1

package/devkit/transforms/barrelImportsPlugin.ts

@@ -0,0 +1,451 @@
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import ts from "typescript";
+import type { App } from "../commandDecorators";
+import { BarrelAnalyzer, type BarrelExportMap, type PackageEntry } from "./barrelAnalyzer";
+
+export interface BarrelImportsPluginOptions {
+  /** Absolute paths whose content should be returned unchanged (e.g. node_modules). */
+  skipPath?: (absPath: string) => boolean;
+  /**
+   * Optional transform applied after the barrel rewrite in the same onLoad
+   * pass. Useful to chain further transforms (e.g. `"use client"` stubbing)
+   * that would otherwise be blocked — Bun's `onLoad` cannot fall through to a
+   * second plugin once a response is returned.
+   * Return the transformed source, or `null` to indicate no change.
+   */
+  pipeAfter?: (source: string, args: { path: string }) => string | Promise<string | null> | null;
+}
+
+export const createBarrelImportsPlugin = async (
+  app: App,
+  { skipPath = defaultSkipPath, pipeAfter }: BarrelImportsPluginOptions = {},
+): Promise<BunPlugin> => {
+  const akanConfig = await app.getConfig();
+  const barrels = [...new Set(akanConfig.barrelImports)].filter(Boolean);
+  const analyzer = new BarrelAnalyzer({
+    resolvePackage: await createTsconfigPackageResolver(app),
+  });
+
+  return {
+    name: "barrel-imports",
+    setup(build) {
+
+      build.onLoad(
+        {
+          filter:
+            /^(?:(?!.*[\\/]node_modules[\\/]).*|.*[\\/]node_modules[\\/]akanjs[\\/].*)\.(tsx|ts|jsx|js)(\?v=\d+)?$/,
+        },
+        async (args) => {
+          const realPath = args.path.replace(/\?v=\d+$/, "");
+          const loader = loaderFor(realPath);
+          if (skipPath(realPath)) {
+            const raw = await Bun.file(realPath).text();
+            return { contents: raw, loader };
+          }
+
+          let source = await Bun.file(realPath).text();
+
+          const hasMacroAttr = MACRO_ATTR_RE.test(source);
+
+          if (!hasMacroAttr && barrels.length > 0) {
+            
+            let maybe = false;
+            for (const b of barrels) {
+              if (source.includes(b)) {
+                maybe = true;
+                break;
+              }
+            }
+            if (maybe) {
+              const rewritten = await rewriteBarrelImports(source, barrels, analyzer);
+              if (rewritten !== null) source = rewritten;
+            }
+          }
+
+          if (pipeAfter) {
+            const piped = await pipeAfter(source, { path: realPath });
+            if (piped !== null) source = piped;
+          }
+
+          return { contents: source, loader };
+        },
+      );
+    },
+  };
+};
+
+/**
+ * Build a `resolvePackage` that maps a package specifier (like `akanjs/ui`)
+ * to its barrel entry file using the workspace tsconfig `paths`. If no direct
+ * mapping exists, falls back to node_modules resolution.
+ */
+export const createTsconfigPackageResolver = async (
+  app: App,
+): Promise<(pkgName: string) => Promise<PackageEntry | null>> => {
+  const tsconfig = await app.getTsConfig();
+  const tsconfigPaths = tsconfig.compilerOptions.paths ?? {};
+
+  const wildcardEntries = Object.entries(tsconfigPaths)
+    .filter(([k]) => k.endsWith("/*"))
+    .map(([k, v]) => ({
+      prefix: k.slice(0, -1), // keep trailing `/`
+      replacements: v,
+    }))
+    .sort((a, b) => b.prefix.length - a.prefix.length);
+
+  return async (pkgName) => {
+    const exact = tsconfigPaths[pkgName];
+    if (exact && exact.length > 0) {
+      const raw = exact[0];
+      if (!raw) return null;
+      const entryFile = path.resolve(app.workspace.workspaceRoot, raw);
+      if (!(await Bun.file(entryFile).exists())) return null;
+
+      const parsed = path.parse(entryFile);
+      const lastSlash = pkgName.lastIndexOf("/");
+      if (parsed.name !== "index" && lastSlash !== -1) {
+        const facet = pkgName.slice(lastSlash + 1);
+        const parentSpec = pkgName.slice(0, lastSlash);
+        if (facet === parsed.name && parentSpec.length > 0) {
+          return { pkgName: parentSpec, entryFile, pkgDir: parsed.dir };
+        }
+      }
+      return { pkgName, entryFile, pkgDir: path.dirname(entryFile) };
+    }
+
+    for (const { prefix, replacements } of wildcardEntries) {
+      if (!pkgName.startsWith(prefix)) continue;
+      const suffix = pkgName.slice(prefix.length);
+      for (const repl of replacements) {
+        if (!repl) continue;
+        const replPath = repl.endsWith("/*") ? repl.slice(0, -1) : repl;
+        const candidate = path.resolve(app.workspace.workspaceRoot, replPath + suffix);
+
+        for (const ext of CANDIDATE_EXTS) {
+          const file = `${candidate}${ext}`;
+          if (await Bun.file(file).exists()) {
+            const lastSlash = pkgName.lastIndexOf("/");
+            if (lastSlash !== -1) {
+              const parentSpec = pkgName.slice(0, lastSlash);
+              if (parentSpec.length > 0) {
+                return { pkgName: parentSpec, entryFile: file, pkgDir: path.dirname(file) };
+              }
+            }
+            return { pkgName, entryFile: file, pkgDir: path.dirname(file) };
+          }
+        }
+        for (const ext of CANDIDATE_EXTS) {
+          const file = path.join(candidate, `index${ext}`);
+          if (await Bun.file(file).exists()) {
+            return { pkgName, entryFile: file, pkgDir: candidate };
+          }
+        }
+      }
+
+      return null;
+    }
+
+    const exported = await resolveNodePackageExport(app.workspace.workspaceRoot, pkgName);
+    if (exported) return exported;
+
+    const pkgJsonPath = path.join(app.workspace.workspaceRoot, "node_modules", pkgName, "package.json");
+    if (!(await Bun.file(pkgJsonPath).exists())) return null;
+    try {
+      const pkgJson = JSON.parse(await Bun.file(pkgJsonPath).text()) as {
+        main?: string;
+        module?: string;
+      };
+      const rel = pkgJson.module ?? pkgJson.main ?? "index.js";
+      const entryFile = path.resolve(path.dirname(pkgJsonPath), rel);
+      if (!(await Bun.file(entryFile).exists())) return null;
+      return { pkgName, entryFile, pkgDir: path.dirname(pkgJsonPath) };
+    } catch {
+      return null;
+    }
+  };
+};
+
+const CANDIDATE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+
+const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
+const AKANJS_NODE_MODULE_RE = /[\\/]node_modules[\\/]akanjs[\\/]/;
+const defaultSkipPath = (absPath: string) => NODE_MODULES_RE.test(absPath) && !AKANJS_NODE_MODULE_RE.test(absPath);
+
+type ExportValue = string | string[] | { [condition: string]: ExportValue | undefined };
+
+const resolveNodePackageExport = async (workspaceRoot: string, specifier: string): Promise<PackageEntry | null> => {
+  const packageName = getPackageName(specifier);
+  if (!packageName) return null;
+  const pkgJsonPath = path.join(workspaceRoot, "node_modules", packageName, "package.json");
+  if (!(await Bun.file(pkgJsonPath).exists())) return null;
+
+  try {
+    const pkgDir = path.dirname(pkgJsonPath);
+    const pkgJson = JSON.parse(await Bun.file(pkgJsonPath).text()) as {
+      exports?: Record<string, ExportValue>;
+      module?: string;
+      main?: string;
+    };
+    const subpath = specifier === packageName ? "." : `.${specifier.slice(packageName.length)}`;
+    const exported = resolvePackageExport(pkgJson.exports, subpath);
+    const rel = exported ?? (subpath === "." ? (pkgJson.module ?? pkgJson.main ?? "index.js") : null);
+    if (!rel || !rel.startsWith(".")) return null;
+    const entryFile = await resolveFileCandidate(path.resolve(pkgDir, rel));
+    if (!entryFile) return null;
+    const pkgEntryName = specifier;
+    return { pkgName: pkgEntryName, entryFile, pkgDir: path.dirname(entryFile), preserveFilePath: true };
+  } catch {
+    return null;
+  }
+};
+
+const resolveExportValue = (value: ExportValue | undefined): string | null => {
+  if (!value) return null;
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const resolved = resolveExportValue(item);
+      if (resolved) return resolved;
+    }
+    return null;
+  }
+  for (const condition of ["source", "import", "default", "types"]) {
+    const resolved = resolveExportValue(value[condition]);
+    if (resolved) return resolved;
+  }
+  return null;
+};
+
+const resolvePackageExport = (exportsMap: Record<string, ExportValue> | undefined, subpath: string): string | null => {
+  if (!exportsMap) return null;
+  const exact = resolveExportValue(exportsMap[subpath]);
+  if (exact) return exact;
+
+  for (const [key, value] of Object.entries(exportsMap)) {
+    const starIdx = key.indexOf("*");
+    if (starIdx === -1) continue;
+    const prefix = key.slice(0, starIdx);
+    const suffix = key.slice(starIdx + 1);
+    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue;
+    const wildcard = subpath.slice(prefix.length, subpath.length - suffix.length);
+    const resolved = resolveExportValue(value);
+    if (resolved) return resolved.replace("*", wildcard);
+  }
+
+  return null;
+};
+
+const getPackageName = (specifier: string): string | null => {
+  const parts = specifier.split("/");
+  if (!parts[0]) return null;
+  if (specifier.startsWith("@")) return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
+  return parts[0];
+};
+
+const resolveFileCandidate = async (candidate: string): Promise<string | null> => {
+  if (await Bun.file(candidate).exists()) return candidate;
+  if (path.extname(candidate)) return null;
+  for (const ext of CANDIDATE_EXTS) {
+    const file = `${candidate}${ext}`;
+    if (await Bun.file(file).exists()) return file;
+  }
+  for (const ext of CANDIDATE_EXTS) {
+    const file = path.join(candidate, `index${ext}`);
+    if (await Bun.file(file).exists()) return file;
+  }
+  return null;
+};
+
+const MACRO_ATTR_RE = /with\s*\{\s*type\s*:\s*["']macro["']\s*\}/;
+
+/** Exposed for testing. */
+export const rewriteBarrelImports = async (
+  source: string,
+  barrels: string[],
+  analyzer: BarrelAnalyzer,
+): Promise<string | null> => {
+  const statements = findImportStatements(source);
+  if (statements.length === 0) return null;
+
+  let changed = false;
+  let out = source;
+  for (let i = statements.length - 1; i >= 0; i--) {
+    const stmt = statements[i];
+    if (!stmt) continue;
+    if (!barrels.includes(stmt.specifier)) continue;
+    const map = await analyzer.analyze(stmt.specifier);
+    if (!map || map.size === 0) continue;
+    const replacement = rewriteSingleStatement(stmt, map);
+    if (replacement === null) continue;
+    out = out.slice(0, stmt.start) + replacement + out.slice(stmt.end);
+    changed = true;
+  }
+  return changed ? out : null;
+};
+
+interface ImportStatement {
+  start: number;
+  end: number;
+  clause: string;
+  specifier: string;
+  trailingSemicolon: boolean;
+  raw: string;
+}
+
+const findImportStatements = (source: string): ImportStatement[] => {
+  const statements: ImportStatement[] = [];
+  const sourceFile = ts.createSourceFile("barrel-imports.tsx", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const importClause = statement.importClause;
+    if (!importClause) continue;
+    const statementStart = statement.getStart(sourceFile);
+    const statementEnd = statement.end;
+    statements.push({
+      start: statementStart,
+      end: statementEnd,
+      clause: source.slice(importClause.getStart(sourceFile), importClause.end).trim(),
+      specifier: statement.moduleSpecifier.text,
+      trailingSemicolon: source.slice(statement.moduleSpecifier.end, statement.end).includes(";"),
+      raw: source.slice(statementStart, statementEnd),
+    });
+  }
+  return statements;
+};
+
+interface NamedImportItem {
+  imported: string;
+  local: string;
+  isType: boolean;
+}
+
+interface ParsedClause {
+  defaultImport?: string;
+  namespaceImport?: string;
+  named?: NamedImportItem[];
+  /** Whole clause is `import type { ... } from "..."`. */
+  typeOnly: boolean;
+}
+
+const parseImportClause = (clause: string): ParsedClause | null => {
+  let rest = clause.trim();
+  let typeOnly = false;
+  if (rest.startsWith("type ")) {
+    typeOnly = true;
+    rest = rest.slice(5).trim();
+  }
+  const parsed: ParsedClause = { typeOnly };
+  
+  const commaMatch = /^(\w+)\s*,\s*(.+)$/.exec(rest);
+  if (commaMatch) {
+    parsed.defaultImport = commaMatch[1];
+    rest = commaMatch[2] ?? "";
+  } else if (/^\w+$/.test(rest)) {
+    parsed.defaultImport = rest;
+    return parsed;
+  }
+  if (rest.startsWith("*")) {
+    const ns = /^\*\s+as\s+(\w+)$/.exec(rest);
+    if (!ns) return null;
+    parsed.namespaceImport = ns[1];
+    return parsed;
+  }
+  if (rest.startsWith("{")) {
+    const close = rest.indexOf("}");
+    if (close === -1) return null;
+    const inner = rest.slice(1, close);
+    parsed.named = parseNamedImportList(inner);
+    return parsed;
+  }
+  return parsed;
+};
+
+const parseNamedImportList = (body: string): NamedImportItem[] => {
+  const out: NamedImportItem[] = [];
+  for (const raw of body.split(",")) {
+    const s = raw.trim();
+    if (!s) continue;
+    let isType = false;
+    let rest = s;
+    if (rest.startsWith("type ")) {
+      isType = true;
+      rest = rest.slice(5).trim();
+    }
+    const asMatch = /^(\w+)\s+as\s+(\w+)$/.exec(rest);
+    if (asMatch) {
+      out.push({ imported: asMatch[1] ?? "", local: asMatch[2] ?? "", isType });
+      continue;
+    }
+    if (/^\w+$/.test(rest)) {
+      out.push({ imported: rest, local: rest, isType });
+    }
+  }
+  return out;
+};
+
+const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): string | null => {
+  const clause = parseImportClause(stmt.clause);
+  if (!clause) return null;
+  
+  if (clause.namespaceImport) return null;
+  
+  if (clause.typeOnly && !clause.defaultImport) return null;
+  if (!clause.named || clause.named.length === 0) {
+    
+    return null;
+  }
+
+  const remaining: NamedImportItem[] = [];
+  const rewrites = new Map<string, NamedImportItem[]>();
+  for (const item of clause.named) {
+    if (item.isType) {
+      remaining.push(item);
+      continue;
+    }
+    const target = map.get(item.imported);
+    if (!target) {
+      remaining.push(item);
+      continue;
+    }
+    const list = rewrites.get(target.subpath) ?? [];
+    
+    list.push({ imported: target.originalName, local: item.local, isType: false });
+    rewrites.set(target.subpath, list);
+  }
+
+  if (rewrites.size === 0) return null;
+
+  const lines: string[] = [];
+  
+  const tail = ";";
+
+  if (clause.defaultImport || remaining.length > 0) {
+    const parts: string[] = [];
+    if (clause.defaultImport) parts.push(clause.defaultImport);
+    if (remaining.length > 0) {
+      parts.push(`{ ${remaining.map(serializeNamedItem).join(", ")} }`);
+    }
+    lines.push(`import ${parts.join(", ")} from "${stmt.specifier}"${tail}`);
+  }
+
+  for (const [subpath, items] of rewrites) {
+    lines.push(`import { ${items.map(serializeNamedItem).join(", ")} } from "${subpath}"${tail}`);
+  }
+
+  return lines.join("\n");
+};
+
+const serializeNamedItem = (item: NamedImportItem): string => {
+  const prefix = item.isType ? "type " : "";
+  if (item.imported === item.local) return `${prefix}${item.imported}`;
+  return `${prefix}${item.imported} as ${item.local}`;
+};
+
+const loaderFor = (absPath: string): "ts" | "tsx" | "js" | "jsx" => {
+  if (absPath.endsWith(".tsx")) return "tsx";
+  if (absPath.endsWith(".jsx")) return "jsx";
+  if (absPath.endsWith(".ts")) return "ts";
+  return "js";
+};

package/devkit/transforms/externalizeFrameworkPlugin.ts

@@ -0,0 +1,159 @@
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import type { App } from "../commandDecorators";
+
+/**
+ * Keep framework/runtime singletons external while bundling authored
+ * workspace sources and ordinary npm dependencies into the pages bundle.
+ *
+ * Why a plugin instead of `Bun.build({ external })` or
+ * `Bun.build({ packages: "external" })`:
+ *   - `packages: "external"` externalizes every bare specifier, including
+ *     `@apps/*` / `@libs/*` — workspace packages that must stay bundled
+ *     so the `"use client"` plugin can rewrite their exports — and ordinary
+ *     npm dependencies like `dayjs` / `clsx`, which the production runtime
+ *     package.json does not install for the SSR pages artifact.
+ *   - Top-level `external: [...]` applies to macro-time module resolution
+ *     too; any `with { type: "macro" }` import chain that transitively
+ *     resolves `react` during build then fails with `ENOENT "react"`.
+ *
+ * An `onResolve` plugin only participates in the output-graph walk, so
+ * macros evaluate against the real modules in node_modules while the
+ * emitted bundle keeps bare specifiers only for runtime singletons that
+ * are installed in the generated production package.json.
+ *
+ * Externalization rules (applied in order):
+ *   1. Relative specifiers (`./`, `../`) are NEVER externalized — they
+ *      always resolve to the current package's source tree and must be
+ *      inlined so transitive `"use client"` stubs work.
+ *   2. Specifiers listed in `include` (workspace aliases like
+ *      `@apps/*`, `@libs/*`) are NEVER externalized.
+ *   3. React / RSC runtime packages and framework host packages are
+ *      externalized so the runtime supplies a single shared instance.
+ *   4. Other bare npm packages are bundled so the Docker runtime does not
+ *      need to install every transitive page dependency separately.
+ */
+export interface ExternalizeFrameworkOptions {
+  app: App;
+  /**
+   * Prefixes that should be BUNDLED (kept internal). Defaults to
+   * `@apps/` and `@libs/` which are the workspace aliases used by the
+   * framework's app template.
+   */
+  include?: string[];
+  /**
+   * Extra bare specifiers to force-externalize beyond the allowlist
+   * defaults. Not commonly needed since the default rule already
+   * externalizes every non-workspace specifier.
+   */
+  extra?: string[];
+}
+
+const DEFAULT_INCLUDE = ["akanjs/", "@apps/", "@libs/"];
+
+const DEFAULT_EXCLUDE_EXACT = new Set<string>(["akanjs/webkit", "akanjs/server", "akanjs/cli", "akanjs/devkit"]);
+const DEFAULT_EXCLUDE_PREFIX = ["akanjs/server/", "akanjs/cli/", "akanjs/devkit/"];
+const RUNTIME_EXTERNAL_EXACT = new Set<string>([
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-server-dom-webpack",
+  "react-server-dom-webpack/server.node",
+  "react-server-dom-webpack/client.node",
+  "react-server-dom-webpack/client.browser",
+]);
+const RUNTIME_EXTERNAL_PREFIX = ["react-dom/", "react-server-dom-webpack/"];
+
+const CANDIDATE_EXTS = [".tsx", ".ts", ".jsx", ".js", ".mjs", ".cjs"];
+
+export async function createExternalizeFrameworkPlugin(options: ExternalizeFrameworkOptions): Promise<BunPlugin> {
+  const tsconfig = await options.app.getTsConfig();
+  const includePrefixes = options.include ?? DEFAULT_INCLUDE;
+  const extraExact = new Set(options.extra ?? []);
+  const workspaceRoot = options.app.workspace.workspaceRoot;
+  const tsconfigPaths = tsconfig.compilerOptions.paths ?? {};
+
+  const rootEntries = Object.entries(tsconfigPaths)
+    .filter(([k]) => !k.endsWith("/*"))
+    .map(([k, v]) => ({ pkg: k, entryFile: v[0] ?? null }))
+    .filter((e): e is { pkg: string; entryFile: string } => e.entryFile !== null);
+  const wildcardEntries = Object.entries(tsconfigPaths)
+    .filter(([k]) => k.endsWith("/*"))
+    .map(([k, v]) => ({ prefix: k.slice(0, -1), replacements: v }))
+    .sort((a, b) => b.prefix.length - a.prefix.length);
+
+  async function resolveWorkspaceSubpath(spec: string): Promise<string | null> {
+    if (!workspaceRoot) return null;
+    
+    for (const { prefix, replacements } of wildcardEntries) {
+      if (!spec.startsWith(prefix)) continue;
+      const suffix = spec.slice(prefix.length);
+      for (const repl of replacements) {
+        const replPath = repl?.endsWith("/*") ? repl.slice(0, -1) : (repl ?? "");
+        if (!replPath) continue;
+        const candidate = path.resolve(workspaceRoot, replPath + suffix);
+        const hit = await firstExisting(candidate);
+        if (hit) return hit;
+      }
+    }
+
+    for (const { pkg, entryFile } of rootEntries) {
+      if (spec !== pkg && !spec.startsWith(`${pkg}/`)) continue;
+      if (spec === pkg) continue; 
+      const suffix = spec.slice(pkg.length + 1);
+      const pkgDir = path.dirname(path.resolve(workspaceRoot, entryFile));
+      const candidate = path.join(pkgDir, suffix);
+      const hit = await firstExisting(candidate);
+      if (hit) return hit;
+    }
+    return null;
+  }
+
+  return {
+    name: "akan-externalize-framework",
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, async (args) => {
+        const spec = args.path;
+
+        if (spec === "." || spec === ".." || spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/"))
+          return undefined;
+        
+        if (extraExact.has(spec) || DEFAULT_EXCLUDE_EXACT.has(spec)) return { path: spec, external: true };
+        for (const prefix of DEFAULT_EXCLUDE_PREFIX) {
+          if (spec.startsWith(prefix)) return { path: spec, external: true };
+        }
+        if (RUNTIME_EXTERNAL_EXACT.has(spec)) return { path: spec, external: true };
+        for (const prefix of RUNTIME_EXTERNAL_PREFIX) {
+          if (spec.startsWith(prefix)) return { path: spec, external: true };
+        }
+
+        for (const prefix of includePrefixes) {
+          if (!spec.startsWith(prefix)) continue;
+          const resolved = await resolveWorkspaceSubpath(spec);
+          if (resolved) return { path: resolved };
+
+          return undefined;
+        }
+
+        return undefined;
+      });
+    },
+  };
+}
+
+async function firstExisting(basePath: string): Promise<string | null> {
+  
+  if (await Bun.file(basePath).exists()) return basePath;
+  
+  for (const ext of CANDIDATE_EXTS) {
+    const candidate = `${basePath}${ext}`;
+    if (await Bun.file(candidate).exists()) return candidate;
+  }
+  
+  for (const ext of CANDIDATE_EXTS) {
+    const candidate = path.join(basePath, `index${ext}`);
+    if (await Bun.file(candidate).exists()) return candidate;
+  }
+  return null;
+}

package/devkit/transforms/index.ts

@@ -0,0 +1,5 @@
+export * from "./barrelAnalyzer";
+export * from "./barrelImportsPlugin";
+export * from "./externalizeFrameworkPlugin";
+export * from "./rscUseClientTransform";
+export * from "./useClientBundlePlugin";

package/devkit/transforms/rscUseClientTransform.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+
+const USE_CLIENT_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
+const IMPLICIT_ROOT_LAYOUT_RE =
+  /[/\\]\.akan[/\\]generated[/\\](?:implicit-root-layout|root-layouts[/\\].*__root_layout)\.(tsx|ts|jsx|js)$/;
+
+export interface UseClientTransformArgs {
+  path: string;
+  workspaceRoot?: string;
+}
+
+export function toClientReferencePath(absPath: string, workspaceRoot: string): string {
+  return path.relative(path.resolve(workspaceRoot), path.resolve(absPath)).split(path.sep).join("/");
+}
+
+/**
+ * Returns the stubbed module source if `source` is a client module, else null.
+ * The returned source is TypeScript-compatible (loader "ts" is safe).
+ */
+export function transformUseClient(source: string, args: UseClientTransformArgs): string | null {
+  if (!USE_CLIENT_RE.test(source)) return null;
+  if (IMPLICIT_ROOT_LAYOUT_RE.test(args.path)) return null;
+  const transpiler = new Bun.Transpiler({ loader: loaderFor(args.path) });
+  const { exports } = transpiler.scan(source);
+  if (exports.length === 0) return null;
+
+  const referencePath = args.workspaceRoot ? toClientReferencePath(args.path, args.workspaceRoot) : args.path;
+  const filePathLit = JSON.stringify(referencePath);
+  const lines: string[] = [`import { registerClientReference } from "react-server-dom-webpack/server.node";`];
+
+  for (const name of exports) {
+    const nameLit = JSON.stringify(name);
+    const errMsg = JSON.stringify(
+      `Attempted to call '${name}' from '${referencePath}' on the server, but it is a client-only export.`,
+    );
+    const proxy = `() => { throw new Error(${errMsg}); }`;
+    const binding =
+      name === "default"
+        ? `export default registerClientReference(${proxy}, ${filePathLit}, ${nameLit});`
+        : `export const ${name} = registerClientReference(${proxy}, ${filePathLit}, ${nameLit});`;
+    lines.push(binding);
+  }
+
+  return lines.join("\n");
+}
+
+function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
+  if (absPath.endsWith(".tsx")) return "tsx";
+  if (absPath.endsWith(".jsx")) return "jsx";
+  if (absPath.endsWith(".ts")) return "ts";
+  return "js";
+}