@akanjs/devkit 3.2.0-rc.3 → 3.2.0-rc.6

package/apiReport/apiTargets.ts

@@ -0,0 +1,311 @@
+import ts from "typescript";
+import { ApiDeclarationPrinter } from "./apiDeclarationPrinter";
+
+export interface ApiTarget {
+  id: string;
+  name: string;
+  origin: string;
+  file: ts.SourceFile | null;
+  statements: ts.Statement[];
+  thirdParty: string | null;
+  members: ts.Symbol[] | null;
+}
+
+interface ImportBinding {
+  specifier: string;
+  imported: string;
+}
+
+//* Statements come from the emitted `.d.ts`, which also holds what the emit adds, such as a mixin class's `X_base`.
+export class ApiTargets {
+  readonly #program: ts.Program;
+  readonly #checker: ts.TypeChecker;
+  readonly #emitted: ReadonlyMap<string, string>;
+  readonly #parsed = new Map<string, ts.SourceFile>();
+  readonly #indexes = new Map<ts.SourceFile, Map<string, ts.Statement[]>>();
+  readonly #imports = new Map<ts.SourceFile, Map<string, ImportBinding>>();
+  readonly #modules = new Map<string, ts.SourceFile | null>();
+  readonly #moduleExports = new Map<ts.SourceFile, Map<string, ts.Symbol>>();
+  readonly #references = new Map<string, ApiTarget[]>();
+
+  constructor(program: ts.Program, emitted: ReadonlyMap<string, string>) {
+    this.#program = program;
+    this.#checker = program.getTypeChecker();
+    this.#emitted = emitted;
+  }
+
+  exportsOf(sourceFile: ts.SourceFile) {
+    const moduleSymbol = this.#checker.getSymbolAtLocation(sourceFile);
+    return moduleSymbol ? this.#checker.getExportsOfModule(moduleSymbol) : [];
+  }
+
+  typeTextOf(symbol: ts.Symbol) {
+    const target = symbol.flags & ts.SymbolFlags.Alias ? this.#checker.getAliasedSymbol(symbol) : symbol;
+    return this.#checker.typeToString(
+      this.#checker.getTypeOfSymbol(target),
+      undefined,
+      ts.TypeFormatFlags.NoTruncation,
+    );
+  }
+
+  ofSymbol(symbol: ts.Symbol): ApiTarget[] {
+    const target = symbol.flags & ts.SymbolFlags.Alias ? this.#checker.getAliasedSymbol(symbol) : symbol;
+    const targets = new Map<string, ApiTarget>();
+    for (const declaration of target.declarations ?? []) {
+      const resolved = this.#ofDeclaration(declaration);
+      if (resolved && !targets.has(resolved.id)) targets.set(resolved.id, resolved);
+    }
+    return [...targets.values()];
+  }
+
+  expand(targets: ApiTarget[], seen = new Set<string>()): ApiTarget[] {
+    return targets.flatMap((target) => {
+      if (!target.members) return [target];
+      if (seen.has(target.id)) return [];
+      seen.add(target.id);
+      return this.expand(
+        target.members.flatMap((member) => this.ofSymbol(member)),
+        seen,
+      );
+    });
+  }
+
+  referencesOf(target: ApiTarget): ApiTarget[] {
+    const cached = this.#references.get(target.id);
+    if (cached) return cached;
+    const file = target.file;
+    const found = file
+      ? target.statements.flatMap((statement) =>
+          this.#referencesIn(ApiDeclarationPrinter.prepared(statement), file, target.origin),
+        )
+      : [];
+    const references = this.expand(found);
+    this.#references.set(target.id, references);
+    return references;
+  }
+
+  #ofDeclaration(declaration: ts.Declaration): ApiTarget | null {
+    if (ts.isSourceFile(declaration)) {
+      return {
+        id: `${declaration.fileName}\0*`,
+        name: "*",
+        origin: declaration.fileName,
+        file: null,
+        statements: [],
+        thirdParty: ApiTargets.packageOf(declaration.fileName),
+        members: this.exportsOf(declaration),
+      };
+    }
+    const sourceFile = declaration.getSourceFile();
+    const name = ApiTargets.localNameOf(declaration);
+    if (name === null) return null;
+    const thirdParty = ApiTargets.packageOf(sourceFile.fileName);
+    const base = { id: `${sourceFile.fileName}\0${name}`, name, origin: sourceFile.fileName, members: null };
+    if (thirdParty) return { ...base, file: null, statements: [], thirdParty };
+    const file = sourceFile.isDeclarationFile ? sourceFile : this.#declarationFileOf(sourceFile);
+    if (!file) return { ...base, file: null, statements: [], thirdParty: null };
+    const statements = this.#indexOf(file).get(name);
+    if (statements) return { ...base, file, statements, thirdParty: null };
+    const nested = ApiTargets.#statementOf(declaration);
+    return {
+      ...base,
+      id: `${base.id}\0${declaration.pos}`,
+      file,
+      statements: nested && sourceFile.isDeclarationFile ? [nested] : [],
+      thirdParty: null,
+    };
+  }
+
+  #referencesIn(root: ts.Node, file: ts.SourceFile, origin: string): ApiTarget[] {
+    const found: ApiTarget[] = [];
+    const visit = (node: ts.Node) => {
+      if (ts.isTypeReferenceNode(node))
+        found.push(...this.#resolve(ApiTargets.#segmentsOf(node.typeName), node, file, origin));
+      else if (ts.isExpressionWithTypeArguments(node))
+        found.push(...this.#resolve(ApiTargets.#segmentsOf(node.expression), node, file, origin));
+      else if (ts.isTypeQueryNode(node))
+        found.push(...this.#resolve(ApiTargets.#segmentsOf(node.exprName), node, file, origin));
+      else if (ts.isComputedPropertyName(node))
+        found.push(...this.#resolve(ApiTargets.#segmentsOf(node.expression), node, file, origin));
+      else if (ts.isImportTypeNode(node)) found.push(...this.#resolveImportType(node, origin));
+      ts.forEachChild(node, visit);
+    };
+    visit(root);
+    return found;
+  }
+
+  #resolve(segments: string[] | null, at: ts.Node, file: ts.SourceFile, origin: string): ApiTarget[] {
+    const [head, next] = segments ?? [];
+    if (!head || ApiTargets.#isTypeParameter(at, head)) return [];
+    const local = this.#indexOf(file).get(head);
+    if (local) return [this.#local(file, origin, head, local)];
+    const binding = this.#importsOf(file).get(head);
+    if (!binding) return [];
+    const module = this.#moduleOf(binding.specifier, origin);
+    if (!module) return [];
+    if (binding.imported !== "*") return this.#exported(module, binding.imported);
+    return next ? this.#exported(module, next) : this.#namespaceOf(module);
+  }
+
+  #resolveImportType(node: ts.ImportTypeNode, origin: string): ApiTarget[] {
+    const argument = node.argument;
+    if (!ts.isLiteralTypeNode(argument) || !ts.isStringLiteral(argument.literal)) return [];
+    const module = this.#moduleOf(argument.literal.text, origin);
+    if (!module) return [];
+    const [name] = node.qualifier ? (ApiTargets.#segmentsOf(node.qualifier) ?? []) : [];
+    return name ? this.#exported(module, name) : this.#namespaceOf(module);
+  }
+
+  #local(file: ts.SourceFile, origin: string, name: string, statements: ts.Statement[]): ApiTarget {
+    return { id: `${origin}\0${name}`, name, origin, file, statements, thirdParty: null, members: null };
+  }
+
+  #exported(module: ts.SourceFile, name: string) {
+    const symbol = this.#moduleExportsOf(module).get(name);
+    return symbol ? this.ofSymbol(symbol) : [];
+  }
+
+  #namespaceOf(module: ts.SourceFile): ApiTarget[] {
+    return [
+      {
+        id: `${module.fileName}\0*`,
+        name: "*",
+        origin: module.fileName,
+        file: null,
+        statements: [],
+        thirdParty: null,
+        members: [...this.#moduleExportsOf(module).values()],
+      },
+    ];
+  }
+
+  #moduleExportsOf(module: ts.SourceFile) {
+    const cached = this.#moduleExports.get(module);
+    if (cached) return cached;
+    const exports = new Map(this.exportsOf(module).map((symbol) => [symbol.getName(), symbol]));
+    this.#moduleExports.set(module, exports);
+    return exports;
+  }
+
+  #moduleOf(specifier: string, origin: string) {
+    const key = `${origin}\0${specifier}`;
+    if (this.#modules.has(key)) return this.#modules.get(key) ?? null;
+    const resolved = ts.resolveModuleName(specifier, origin, this.#program.getCompilerOptions(), ts.sys).resolvedModule;
+    const fileName = resolved?.resolvedFileName;
+    const module = fileName && !ApiTargets.packageOf(fileName) ? (this.#program.getSourceFile(fileName) ?? null) : null;
+    this.#modules.set(key, module);
+    return module;
+  }
+
+  #declarationFileOf(sourceFile: ts.SourceFile) {
+    const cached = this.#parsed.get(sourceFile.fileName);
+    if (cached) return cached;
+    const text = this.#emitted.get(sourceFile.fileName);
+    if (text === undefined) return null;
+    const fileName = sourceFile.fileName.replace(/\.tsx?$/, ".d.ts");
+    const parsed = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true);
+    this.#parsed.set(sourceFile.fileName, parsed);
+    return parsed;
+  }
+
+  #indexOf(file: ts.SourceFile) {
+    const cached = this.#indexes.get(file);
+    if (cached) return cached;
+    const index = new Map<string, ts.Statement[]>();
+    const add = (name: string, statement: ts.Statement) => index.set(name, [...(index.get(name) ?? []), statement]);
+    for (const statement of file.statements) {
+      if (ts.isVariableStatement(statement)) {
+        for (const declaration of statement.declarationList.declarations)
+          if (ts.isIdentifier(declaration.name))
+            add(declaration.name.text, ApiTargets.#narrowed(statement, declaration));
+        continue;
+      }
+      const name = ApiDeclarationPrinter.isNamed(statement) ? ApiTargets.localNameOf(statement) : null;
+      if (name !== null) add(name, statement);
+    }
+    this.#indexes.set(file, index);
+    return index;
+  }
+
+  #importsOf(file: ts.SourceFile) {
+    const cached = this.#imports.get(file);
+    if (cached) return cached;
+    const bindings = new Map<string, ImportBinding>();
+    for (const statement of file.statements) {
+      if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+      const specifier = statement.moduleSpecifier.text;
+      const clause = statement.importClause;
+      if (clause?.name) bindings.set(clause.name.text, { specifier, imported: "default" });
+      const named = clause?.namedBindings;
+      if (named && ts.isNamespaceImport(named)) bindings.set(named.name.text, { specifier, imported: "*" });
+      if (named && ts.isNamedImports(named))
+        for (const element of named.elements)
+          bindings.set(element.name.text, { specifier, imported: (element.propertyName ?? element.name).text });
+    }
+    this.#imports.set(file, bindings);
+    return bindings;
+  }
+
+  static localNameOf(declaration: ts.Declaration): string | null {
+    const name = ts.getNameOfDeclaration(declaration);
+    if (name && ts.isIdentifier(name)) return name.text;
+    if (name) return null;
+    const modifiers = ts.canHaveModifiers(declaration) ? ts.getModifiers(declaration) : undefined;
+    return modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) ? "default" : null;
+  }
+
+  static packageOf(fileName: string) {
+    const normalized = fileName.replaceAll("\\", "/");
+    const idx = normalized.lastIndexOf("/node_modules/");
+    if (idx < 0) return null;
+    const [scope = "", name = ""] = normalized.slice(idx + "/node_modules/".length).split("/");
+    return scope.startsWith("@") ? `${scope}/${name}` : scope;
+  }
+
+  static #statementOf(declaration: ts.Declaration): ts.Statement | null {
+    if (ts.isVariableDeclaration(declaration)) {
+      const statement = declaration.parent.parent;
+      return ts.isVariableStatement(statement) ? ApiTargets.#narrowed(statement, declaration) : null;
+    }
+    return ApiDeclarationPrinter.isNamed(declaration) ? declaration : null;
+  }
+
+  static #narrowed(statement: ts.VariableStatement, declaration: ts.VariableDeclaration) {
+    if (statement.declarationList.declarations.length === 1) return statement;
+    const narrowed = ts.factory.updateVariableStatement(
+      statement,
+      statement.modifiers,
+      ts.factory.updateVariableDeclarationList(statement.declarationList, [declaration]),
+    );
+    ts.setOriginalNode(narrowed, statement);
+    return narrowed;
+  }
+
+  static #segmentsOf(node: ts.Node): string[] | null {
+    if (ts.isIdentifier(node)) return [node.text];
+    if (ts.isQualifiedName(node)) {
+      const left = ApiTargets.#segmentsOf(node.left);
+      return left && [...left, node.right.text];
+    }
+    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name)) {
+      const left = ApiTargets.#segmentsOf(node.expression);
+      return left && [...left, node.name.text];
+    }
+    return null;
+  }
+
+  static #isTypeParameter(at: ts.Node, name: string) {
+    for (let node = at.parent; node && !ts.isSourceFile(node); node = node.parent) {
+      const typeParameters = (node as { typeParameters?: ts.NodeArray<ts.TypeParameterDeclaration> }).typeParameters;
+      if (typeParameters?.some((parameter) => parameter.name.text === name)) return true;
+      if (ts.isMappedTypeNode(node) && node.typeParameter.name.text === name) return true;
+      if (ts.isConditionalTypeNode(node) && ApiTargets.#infers(node.extendsType, name)) return true;
+    }
+    return false;
+  }
+
+  static #infers(node: ts.Node, name: string): boolean {
+    if (ts.isInferTypeNode(node) && node.typeParameter.name.text === name) return true;
+    return ts.forEachChild(node, (child) => ApiTargets.#infers(child, name) || undefined) ?? false;
+  }
+}

package/apiReport/changesetBump.ts

@@ -0,0 +1,19 @@
+export type Bump = "major" | "minor" | "patch";
+
+export class ChangesetBump {
+  static readonly #rank: Record<Bump, number> = { patch: 0, minor: 1, major: 2 };
+  static readonly #entry = /^\s*(["']?)([^"'#:\s][^"'#:]*?)\1\s*:\s*(["']?)(major|minor|patch)\3\s*(?:#.*)?$/;
+
+  static of(text: string, packageName: string): Bump | null {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text.replace(/^/, ""))?.[1] ?? "";
+    for (const line of frontmatter.split(/\r?\n/)) {
+      const match = ChangesetBump.#entry.exec(line);
+      if (match?.[2] === packageName) return match[4] as Bump;
+    }
+    return null;
+  }
+
+  static atLeast(bump: Bump | null, floor: Bump) {
+    return bump !== null && ChangesetBump.#rank[bump] >= ChangesetBump.#rank[floor];
+  }
+}

package/applicationBuildReporter.test.ts

@@ -51,4 +51,25 @@ describe("ApplicationBuildReporter.printSummary", () => {
       lines.indexOf("Route artifacts: dist/apps/shop/.akan/artifact"),
     );
   });
+
+  test("prints only the route JS budget warnings for a quiet build", () => {
+    const routeJsWarnings = [{ file: "apps/shop/akan.budget.json", message: "unreadable", fix: "correct it" }];
+    ApplicationBuildReporter.printRouteJsWarnings({ routeJsWarnings });
+    ApplicationBuildReporter.printRouteJsWarnings({});
+
+    expect(rawLog.mock.calls.map(([line]) => line)).toEqual([
+      "Warning: apps/shop/akan.budget.json: unreadable (correct it)",
+    ]);
+  });
+
+  test("prints each route JS budget warning of a build that only reports it", () => {
+    const routeJsWarnings = [
+      { file: "apps/shop/akan.budget.json", message: "/:lang/memo loads 133,120 bytes brotli", fix: "shrink it" },
+    ];
+    ApplicationBuildReporter.printSummary({ ...resultFor("main"), routeJsWarnings });
+
+    expect(rawLog.mock.calls.map(([line]) => line)).toContain(
+      "Warning: apps/shop/akan.budget.json: /:lang/memo loads 133,120 bytes brotli (shrink it)",
+    );
+  });
 });

package/applicationBuildReporter.ts

@@ -40,12 +40,20 @@ export class ApplicationBuildReporter {
       for (const line of RouteJsBudget.formatTable(result.routeJs)) Logger.rawLog(line);
       Logger.rawLog("");
     }
+    if (result.routeJsWarnings?.length) {
+      ApplicationBuildReporter.printRouteJsWarnings(result);
+      Logger.rawLog("");
+    }
     Logger.rawLog(`Route artifacts: ${result.artifactDir}`);
     Logger.rawLog(`Server output: ${result.outputDir}`);
     Logger.rawLog(`Done in ${ApplicationBuildReporter.formatDuration(result.durationMs)}`);
     if (result.environment === "local") Logger.rawLog(ApplicationBuildReporter.localBuildNotice);
   }
 
+  static printRouteJsWarnings({ routeJsWarnings = [] }: Pick<ApplicationBuildResult, "routeJsWarnings">) {
+    for (const { file, message, fix } of routeJsWarnings) Logger.rawLog(`Warning: ${file}: ${message} (${fix})`);
+  }
+
   static readonly localBuildNotice =
     "Built for local: the server runs without endpoint rate limits, and boots on local defaults (Redis on localhost, the first database mode) where a deployment would stop to ask. For a host others can reach, run `akan build <app> --env main` with AKAN_PUBLIC_REPO_NAME and AKAN_PUBLIC_SERVE_DOMAIN set in the shell or the workspace .env.";
 

package/applicationBuildRunner.test.ts

@@ -7,6 +7,7 @@ import { ProductionLockfile } from "./akanConfig/productionLockfile";
 import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS, ApplicationBuildRunner } from "./applicationBuildRunner";
 import type { App } from "./commandDecorators";
 import { AppExecutor, Executor } from "./executors";
+import { AllRoutesBuilder, type BuildAllRoutesResult, VendorNarrowing } from "./frontendBuild";
 import { bundleDefine } from "./frontendBuild/bundleDefine";
 import { createTempApp } from "./testHelpers";
 import { ProjectTypecheck } from "./typecheck/projectTypecheck";
@@ -307,6 +308,72 @@ console.info(new SampleService().name);
     }
   });
 
+  const buildSsrUntilVendors = async (routeChunkWritten: boolean) => {
+    const { root, workspace } = await createTempApp("portal");
+    const keys = ["AKAN_PUBLIC_ENV", "AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"] as const;
+    const shellEnv = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+    await Promise.all(["main.ts", "server.ts"].map((file) => writeFile(path.join(root, "apps", "portal", file), "")));
+    const app = AppExecutor.from(workspace, "portal");
+    app.prepareCommand = async () => ({ env: {} });
+    app.getPageKeys = async () => ["_index.tsx"];
+    const order: string[] = [];
+    let narrowed: Record<string, readonly string[]> = {};
+    const entryExports = VendorNarrowing.prototype.entryExports;
+    const bundle = spyOn(Bun, "build").mockImplementation(
+      async () => ({ success: true, outputs: [], logs: [] }) as unknown as Bun.BuildOutput,
+    );
+    const routes = spyOn(AllRoutesBuilder.prototype, "build").mockImplementation(async () => {
+      order.push("routes");
+      if (routeChunkWritten)
+        await Bun.write(
+          path.join(app.dist.cwdPath, ".akan/artifact/client/page-a1.js"),
+          'import{st}from"akanjs/store";',
+        );
+      const clientManifest = { "page#default": { id: "/_akan/client/page-a1.js", chunks: [], name: "default" } };
+      return { manifest: { routeIds: ["/"], clientManifest } } as unknown as BuildAllRoutesResult;
+    });
+    const vendors = spyOn(VendorNarrowing.prototype, "entryExports").mockImplementation(function (
+      this: VendorNarrowing,
+      entries,
+    ) {
+      order.push("vendors");
+      narrowed = entryExports.call(this, entries);
+      throw new Error("stopped at the vendor build");
+    });
+    try {
+      const failure = await new ApplicationBuildRunner(app, { fast: true }).build().then(
+        () => "built",
+        (error: unknown) => (error instanceof Error ? error.message : String(error)),
+      );
+      return { failure, order, narrowed };
+    } finally {
+      bundle.mockRestore();
+      routes.mockRestore();
+      vendors.mockRestore();
+      for (const key of keys) {
+        if (shellEnv[key] === undefined) delete process.env[key];
+        else process.env[key] = shellEnv[key];
+      }
+      await rm(root, { recursive: true, force: true });
+    }
+  };
+
+  test("bundles the routes before the vendor entries, which export only the names the route chunks import", async () => {
+    const { failure, order, narrowed } = await buildSsrUntilVendors(true);
+
+    expect(failure).toBe("stopped at the vendor build");
+    expect(order).toEqual(["routes", "vendors"]);
+    expect(Object.entries(narrowed).find(([entry]) => entry.endsWith("akanjs-store.ts"))?.[1]).toEqual(["st"]);
+  });
+
+  test("stops before the vendor entries when a route's client entry is not where the scan reads", async () => {
+    const { failure, order } = await buildSsrUntilVendors(false);
+
+    expect(failure).toContain("no file under");
+    expect(failure).toContain("/_akan/client/page-a1.js");
+    expect(order).toEqual(["routes"]);
+  });
+
   test("akan typecheck names the script/ files nothing imports, and a build's typecheck leaves them out", async () => {
     const { root, app } = await createTempApp("portal");
     const run = spyOn(ProjectTypecheck.prototype, "run").mockImplementation(async () => "");

package/applicationBuildRunner.ts

@@ -55,7 +55,10 @@ export interface ApplicationBuildRunnerOptions {
   environment?: string;
   /** Bundles `env/env.server.<environment>.<profile>.ts`, which may hold no secret, in place of the environment's file. */
   profile?: string;
-  /** `update` writes akan.budget.json, then enforces it; `report` names an overage without failing the build. */
+  /**
+   * `enforce` fails on an overage, a route with no entry, or a missing or unreadable akan.budget.json; `update` and
+   * `raise` rewrite the file first; `report` only warns.
+   */
   budget?: RouteJsBudgetMode;
 }
 export interface BuildOptions {
@@ -437,6 +440,7 @@ void run().catch((error) => {
     const vendorExports = await VendorImportScanner.exportsUsedIn(
       path.join(this.#app.dist.cwdPath, ".akan/artifact/client"),
       NARROWABLE_VENDOR_SPECIFIERS,
+      Object.values(allRoutes.manifest.clientManifest).map(({ id }) => id),
     );
     const base = await new SsrBaseArtifactBuilder(this.#app, "build", {
       serverEnv: this.#serverEnvPlugin(baseDevEnv.env, branches),
@@ -456,6 +460,7 @@ void run().catch((error) => {
     const budgetPath = path.join(this.#app.cwdPath, RouteJsBudget.fileName);
     const { summary: status, warnings } = await RouteJsBudget.check(sizes, {
       mode: this.#budget,
+      app: this.#app.name,
       budgetPath,
       source: path.relative(this.#app.workspace.workspaceRoot, budgetPath),
       environment,

package/artifact/implicitRootLayout.ts

@@ -71,10 +71,21 @@ export function getRootBoundarySegments(key: string): string[] | null {
   return prefix.split("/").filter(Boolean);
 }
 
+//? The generated root layout serves SSR, CSR and MCP App views alike; an SSR page renders only System's SSR shell.
+export const ROOT_LAYOUT_SYSTEM = {
+  specifier: "akanjs/ui/System/index.tsx",
+  ssrShell: "akanjs/ui/System/SSR.tsx",
+  importsNoSsrPageRenders: ["./CSR", "./App"],
+} as const;
+
 function implicitRootLayoutKey(segments: string[]): string {
   return `./${[...segments, "__root_layout"].join("/")}.tsx`;
 }
 
+export function isImplicitRootLayoutKey(key: string): boolean {
+  return key.endsWith("/__root_layout.tsx");
+}
+
 function implicitRootLayoutAbsPath(appCwdPath: string, segments: string[]): string {
   const filename = segments.length ? `${segments.join("__")}__root_layout.tsx` : "__root_layout.tsx";
   return path.join(path.resolve(appCwdPath), IMPLICIT_LAYOUT_DIR, filename);
@@ -218,7 +229,7 @@ ${layoutBinding}  return `;
     ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
 import { assertGuardOnChain, loadFonts, RouteGuards, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
-import { System } from "akanjs/ui/System/index.tsx";
+import { System } from "${ROOT_LAYOUT_SYSTEM.specifier}";
 import type { McpAppRootProps } from "akanjs/webkit";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};

package/codeAgent/skills/akan-debug/SKILL.md

@@ -15,8 +15,12 @@ the server errors logged meanwhile, console errors and warnings, and layout smel
   stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a
   running one.
 - Paths are comma-separated (`akan preview <app> /board,/board/new`) and get the default locale when they lack
-  one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off. A `/_akan` route such as Studio
-  (`/_akan/studio?view=runtime`), a signal route or a file opens as written.
+  one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off. What the server answers outside a
+  locale opens as written: a `/_akan` route such as Studio (`/_akan/studio?view=runtime`), a route under the
+  API prefix, `/__csr`, `/__rsc`, `/.well-known`, `/openapi.json`, the default `/mcp`, `/favicon.ico`,
+  `/robots.txt`, `/sitemap.xml`, `manifest.webmanifest` and a file in the app's `public/`. A full URL
+  (`http://localhost:<port>/oauth/token`) opens exactly as written: use it for an endpoint mounted outside the
+  API prefix or a custom MCP path. A page `--changed` finds always gets the locale.
   `--changed` adds the pages your uncommitted page and layout edits reach. A dynamic route needs a concrete
   path (`/memo/1`); `akan context --app <app>` lists every route with its params and search names.
 - The viewport is a 390x844 phone; `--desktop` is 1280x800. `--csr` loads each page in the CSR boot the native

package/codeAgent/skills/akan-transport/SKILL.md

@@ -27,6 +27,8 @@ description: "Guard and tune endpoints on the wire: writing a Can<Verb><Model> g
 - `{ rateLimit: { calls, windowMs?, by? } }` per endpoint, `option.setRateLimit` per app, `plug(RateLimit)` for a
   business key.
 - A mutation repeated under one `Idempotency-Key` header runs once and replays its first answer.
+- A browser send that changes nothing read back (typing status, a cursor move) passes `{ keepsReads: true }`, so it
+  neither ends in-flight query sharing nor drops prefetched pages.
 - `{ method: "PATCH" | "PUT" | "DELETE" }` moves a mutation off `POST` — only when a foreign protocol forces it.
 - `errors: { 409: ["ticket.error.locked"] }` names the errors an endpoint throws on purpose.
 

package/commandDecorators/argMeta.ts

@@ -53,6 +53,7 @@ export interface ArgMeta<Context = CommandContext> {
 export interface InternalArgOption {
   nullable?: boolean;
   onlyApp?: boolean;
+  services?: boolean;
 }
 export interface InternalArgMeta {
   key: string;
@@ -112,5 +113,8 @@ export type Pkg = PkgExecutor;
 export const Module = createInternalArgToken<ModuleExecutor, "Module">("Module");
 export type Module = ModuleExecutor;
 
+/** Module, or a service module (`lib/_<name>`) named as `<sys>:_<name>`. */
+export const ModuleOrService = createInternalArgToken<ModuleExecutor, "Module">("Module", { services: true });
+
 export const Workspace = createInternalArgToken<WorkspaceExecutor, "Workspace">("Workspace");
 export type Workspace = WorkspaceExecutor;