@akanjs/devkit 3.1.0-rc.9 → 3.1.1-rc.0

package/frontendBuild/mcpAppViewBuilder.ts

@@ -0,0 +1,245 @@
+import { mkdir, readdir, rename, rm, unlink } from "node:fs/promises";
+import path from "node:path";
+import { parseRouteModuleKey } from "akanjs/common";
+import type { BaseBuildArtifact } from "akanjs/server";
+import type { PageEntry } from "../artifact/implicitRootLayout";
+import type { App } from "../commandDecorators";
+import { McpAppPageTrimmer } from "../transforms/mcpAppPageTrimmer";
+import { PureLazyMarker } from "../transforms/pureLazyMarker";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
+import { CsrEntryFiles } from "./csrEntryFiles";
+
+type CssAsset = NonNullable<BaseBuildArtifact["cssAssets"]>[string];
+
+interface McpAppViewBuildOption {
+  basePaths: string[];
+  cssAssets: Record<string, CssAsset>;
+  /** The CSR shell's own bundle options, so a view inlines the same env and stubs the same stylesheets. */
+  options: ReturnType<typeof CsrArtifactBuilder.bundleOptions>;
+}
+
+export interface McpAppView {
+  name: string;
+  page: PageEntry;
+  /** The generated root layout that renders `System.Provider` for the page, whose `McpAppRoot` the view uses. */
+  root: PageEntry | null;
+  /** The generated wrappers of the `_overrides.tsx` the web draws outside the root layout, outermost first: they also
+   * reach what it draws beside the page, its toasts and approvals. */
+  rootOverrides: PageEntry[];
+  /** The generated wrappers of the rest of the `_overrides.tsx` over the page, outermost first, around it alone. */
+  overrides: PageEntry[];
+  basePath: string;
+}
+
+//* One single-file HTML per `.app()`, which an MCP host renders as that app's view: its entry imports the app's page,
+//* trimmed to its loads, and the page's root layout for its providers. Built beside `csr/`, never inside it: a native
+//* app packs `csr/`, which needs none of them.
+export class McpAppViewBuilder {
+  /** The folder the server reads views from: `WebRouter.mcpAppViewDir`. */
+  static readonly dirName = "mcp-apps";
+  /** `PageDefinition.promptName`, which also keeps a view's file name inside its folder. */
+  static readonly #appName = /^[A-Za-z0-9_-]{1,64}$/;
+
+  readonly #app: App;
+  readonly #command: "build" | "start";
+
+  constructor(app: App, command: "build" | "start") {
+    this.#app = app;
+    this.#command = command;
+  }
+
+  get outputDir(): string {
+    return this.#command === "build"
+      ? path.join(this.#app.dist.cwdPath, McpAppViewBuilder.dirName)
+      : path.join(this.#app.cwdPath, ".akan", "artifact", McpAppViewBuilder.dirName);
+  }
+
+  async build(
+    pageEntries: PageEntry[],
+    { basePaths, cssAssets, options }: McpAppViewBuildOption,
+  ): Promise<McpAppView[]> {
+    const views = await McpAppViewBuilder.discover(pageEntries, basePaths);
+    if (!views.length) {
+      await rm(this.outputDir, { recursive: true, force: true });
+      return views;
+    }
+    //? Built aside, then moved in a file at a time: a host may read a view while `akan start` rebuilds them.
+    const stagingDir = `${this.outputDir}.next`;
+    await rm(stagingDir, { recursive: true, force: true });
+    const generatedDir = path.join(this.#app.cwdPath, ".akan", "generated", McpAppViewBuilder.dirName);
+    await rm(generatedDir, { recursive: true, force: true });
+    await mkdir(generatedDir, { recursive: true });
+    const files = Object.fromEntries(
+      views.flatMap((view) => [
+        [path.join(generatedDir, `${view.name}.html`), McpAppViewBuilder.htmlOf(view)],
+        [path.join(generatedDir, `${view.name}.view.tsx`), McpAppViewBuilder.entryOf(view, generatedDir)],
+      ]),
+    );
+    const pagePaths = [...new Set(views.map((view) => view.page.moduleAbsPath))];
+    const result = await Bun.build({
+      ...options,
+      plugins: [...options.plugins, McpAppPageTrimmer.plugin(pagePaths), PureLazyMarker.plugin()],
+      entrypoints: views.map((view) => path.join(generatedDir, `${view.name}.html`)),
+      files,
+      root: generatedDir,
+      outdir: stagingDir,
+    });
+    if (!result.success) {
+      const logs = result.logs.map((log) => log.message).join("\n");
+      throw new Error(`[mcp-app-build] failed${logs ? `\n${logs}` : ""}`);
+    }
+    for (const view of views) await this.#inline(view, stagingDir, cssAssets[view.basePath]);
+    await this.#publish(views, stagingDir);
+    return views;
+  }
+
+  async #publish(views: McpAppView[], stagingDir: string) {
+    const names = new Set(views.map((view) => `${view.name}.html`));
+    await mkdir(this.outputDir, { recursive: true });
+    for (const name of names) await rename(path.join(stagingDir, name), path.join(this.outputDir, name));
+    for (const name of await readdir(this.outputDir))
+      if (!names.has(name)) await rm(path.join(this.outputDir, name), { recursive: true, force: true });
+    const strays = await readdir(stagingDir);
+    if (strays.length)
+      this.#app.logger.warn(
+        `[mcp-app-build] ${strays.join(", ")} reached no view; a view loads nothing beside its own file`,
+      );
+    await rm(stagingDir, { recursive: true, force: true });
+  }
+
+  /** Every `.app()` the pages declare, read off their sources without evaluating them. */
+  static async discover(pageEntries: PageEntry[], basePaths: string[]): Promise<McpAppView[]> {
+    const { RouteSourceValidator } = await import("../routeSourceValidator");
+    const roots = pageEntries.filter((entry) => parseRouteModuleKey(entry.key).isInternalRootLayout);
+    const overrides = pageEntries.filter((entry) => parseRouteModuleKey(entry.key).kind === "overrides");
+    const layoutNodes = new Set(
+      pageEntries.flatMap((entry) => {
+        const parsed = parseRouteModuleKey(entry.key);
+        return parsed.kind === "layout" && !parsed.isInternalRootLayout ? [parsed.routeSegments.join("/")] : [];
+      }),
+    );
+    const owners = new Map<string, { name: string; key: string }>();
+    const views: McpAppView[] = [];
+    for (const page of pageEntries) {
+      if (parseRouteModuleKey(page.key).kind !== "page") continue;
+      const source = await Bun.file(page.moduleAbsPath).text();
+      const apps =
+        RouteSourceValidator.validateRouteSourceExports(source, page.moduleAbsPath, "page").chain?.apps ?? [];
+      for (const name of apps) {
+        if (!McpAppViewBuilder.#appName.test(name))
+          throw new Error(
+            `[route-convention] app name "${name}" in ${page.key} must match ${McpAppViewBuilder.#appName}`,
+          );
+        //? Keyed in lower case: a case-insensitive disk would write two such views to one file.
+        const owner = owners.get(name.toLowerCase());
+        if (owner?.name === name)
+          throw new Error(`[route-convention] app "${name}" is declared by both ${owner.key} and ${page.key}`);
+        if (owner)
+          throw new Error(
+            `[route-convention] apps "${owner.name}" (${owner.key}) and "${name}" (${page.key}) differ only in case; their views would share one file`,
+          );
+        owners.set(name.toLowerCase(), { name, key: page.key });
+        const root = await McpAppViewBuilder.#rootOf(page.key, roots);
+        views.push({
+          name,
+          page,
+          root,
+          ...McpAppViewBuilder.#overridesOf(page.key, root, overrides, layoutNodes),
+          basePath: CsrEntryFiles.basePathOfPageKey(page.key, basePaths) ?? "",
+        });
+      }
+    }
+    return views;
+  }
+
+  static htmlOf(view: McpAppView): string {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>${view.name}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./${view.name}.view.tsx"></script>
+  </body>
+</html>
+`;
+  }
+
+  static entryOf(view: McpAppView, fromDir: string): string {
+    const specifier = (absPath: string) => {
+      const relative = path.relative(fromDir, absPath).split(path.sep).join("/");
+      return JSON.stringify(relative.startsWith(".") ? relative : `./${relative}`);
+    };
+    const importsOf = (entries: PageEntry[], name: string) =>
+      entries.map((entry, idx) => `import ${name}${idx} from ${specifier(entry.moduleAbsPath)};\n`).join("");
+    const namesOf = (entries: PageEntry[], name: string) => entries.map((_, idx) => `${name}${idx}`).join(", ");
+    return `import { McpAppBoot } from "akanjs/webkit";
+import * as page from ${specifier(view.page.moduleAbsPath)};
+${view.root ? `import * as root from ${specifier(view.root.moduleAbsPath)};` : "const root = {};"}
+${importsOf(view.rootOverrides, "rootOverride")}${importsOf(view.overrides, "override")}void McpAppBoot.run({
+  app: ${JSON.stringify(view.name)},
+  page,
+  root,
+  rootOverrides: [${namesOf(view.rootOverrides, "rootOverride")}],
+  overrides: [${namesOf(view.overrides, "override")}],
+  basePath: ${JSON.stringify(view.basePath)},
+});
+`;
+  }
+
+  //? By route segments, as the route tree nests them (`RouteLayering`): a folder's `_overrides.tsx` also covers the
+  //? page file named like the folder (`memo/_overrides.tsx` over `memo.tsx`), and one on a root node sits outside the
+  //? root layout — the root layout's own node, or one above it that holds no layout of its own.
+  static #overridesOf(pageKey: string, root: PageEntry | null, overrides: PageEntry[], layoutNodes: Set<string>) {
+    const pageSegments = parseRouteModuleKey(pageKey).routeSegments;
+    const rootDepth = root ? parseRouteModuleKey(root.key).routeSegments.length : 0;
+    const over = overrides
+      .map((entry) => ({ entry, segments: parseRouteModuleKey(entry.key).routeSegments }))
+      .filter(({ segments }) => segments.every((segment, idx) => pageSegments[idx] === segment))
+      .sort((a, b) => a.segments.length - b.segments.length);
+    const onRootNode = (segments: string[]) =>
+      segments.length === rootDepth || (segments.length < rootDepth && !layoutNodes.has(segments.join("/")));
+    return {
+      rootOverrides: over.filter(({ segments }) => onRootNode(segments)).map(({ entry }) => entry),
+      overrides: over.filter(({ segments }) => !onRootNode(segments)).map(({ entry }) => entry),
+    };
+  }
+
+  //? The outermost root boundary over the page: the one a page is drawn under without an ancestor root, which alone
+  //? renders `System.Provider` and so exports `McpAppRoot`.
+  static async #rootOf(pageKey: string, roots: PageEntry[]): Promise<PageEntry | null> {
+    const dirOf = (key: string) => key.slice(0, key.lastIndexOf("/") + 1);
+    const pageDir = dirOf(pageKey);
+    const over = roots
+      .filter((root) => pageDir.startsWith(dirOf(root.key)))
+      .sort((a, b) => dirOf(a.key).length - dirOf(b.key).length);
+    for (const root of over)
+      if ((await Bun.file(root.moduleAbsPath).text()).includes("export function McpAppRoot")) return root;
+    return null;
+  }
+
+  async #inline(view: McpAppView, dir: string, cssAsset: CssAsset | undefined) {
+    const htmlPath = path.join(dir, `${view.name}.html`);
+    let html = await Bun.file(htmlPath).text();
+    if (cssAsset) {
+      const artifactDir = path.join(
+        this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath,
+        ".akan",
+        "artifact",
+      );
+      const css = await Bun.file(path.join(artifactDir, cssAsset.cssRelPath)).text();
+      html = CsrArtifactBuilder.injectBeforeHeadEnd(html, CsrArtifactBuilder.createInlineStyle(css));
+    } else this.#app.logger.warn(`[mcp-app-build] no compiled stylesheet for ${view.name}; its view ships without CSS`);
+    const scripts: string[] = [];
+    html = await CsrArtifactBuilder.replaceModuleScriptSrc(html, async (src) => {
+      const jsPath = CsrArtifactBuilder.resolveHtmlAssetPath(htmlPath, src);
+      scripts.push(jsPath);
+      return await Bun.file(jsPath).text();
+    });
+    await Bun.write(htmlPath, html);
+    for (const script of scripts) await unlink(script).catch(() => undefined);
+  }
+}

package/frontendBuild/precompressArtifacts.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import zlib from "node:zlib";
+import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
+import { precompressArtifacts } from "./precompressArtifacts";
+
+const tempRoot = tempDirs("akan-devkit-precompress-");
+
+const brotliAt = (bytes: Buffer, quality: number) =>
+  zlib.brotliCompressSync(bytes, {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: bytes.byteLength,
+    },
+  });
+
+describe("precompressArtifacts", () => {
+  test("writes sidecars for client chunks, stylesheets and dictionaries, a dictionary's brotli at quality 11", async () => {
+    const distPath = await tempRoot();
+    const artifactDir = path.join(distPath, ".akan/artifact");
+    const files = {
+      "client/chunk.js": `export const x = ${JSON.stringify("chunk ".repeat(400))};`,
+      "styles/root.css": `.a{color:red}${".b{margin:0}".repeat(200)}`,
+      "dict/en-abc.js": `export default JSON.parse(${JSON.stringify(JSON.stringify({ a: { t: "word ".repeat(400) } }))});`,
+    };
+    for (const [rel, content] of Object.entries(files)) {
+      await mkdir(path.dirname(path.join(artifactDir, rel)), { recursive: true });
+      await writeFile(path.join(artifactDir, rel), content);
+    }
+    const app = { dist: { cwdPath: distPath }, verbose: () => undefined } as unknown as App;
+
+    expect((await precompressArtifacts(app)).files).toBe(3);
+    const dictPath = path.join(artifactDir, "dict/en-abc.js");
+    const dictBytes = await readFile(dictPath);
+    expect(await readFile(`${dictPath}.br`)).toEqual(brotliAt(dictBytes, 11));
+    const chunkPath = path.join(artifactDir, "client/chunk.js");
+    expect(await readFile(`${chunkPath}.br`)).toEqual(brotliAt(await readFile(chunkPath), 9));
+    expect(await Bun.file(`${dictPath}.gz`).exists()).toBe(true);
+  });
+});

package/frontendBuild/precompressArtifacts.ts

@@ -6,8 +6,10 @@ import { FontPruner } from "./fontPruner";
 
 const COMPRESSIBLE_EXTS = new Set([".css", ".html", ".js", ".json", ".svg"]);
 const MIN_COMPRESS_BYTES = 1024;
-// Brotli 11 is ~100x slower than gzip: worth it for the one CSS asset per basePath, not for hundreds of JS chunks.
-const BROTLI_QUALITY_BY_EXT = { ".css": 11 } as const;
+// Brotli 11 is ~100x slower than gzip: worth it for the one CSS asset per basePath and one dictionary per locale, not
+// for hundreds of JS chunks.
+const MAX_BROTLI_QUALITY = 11;
+const BROTLI_QUALITY_BY_EXT = { ".css": MAX_BROTLI_QUALITY } as const;
 const DEFAULT_BROTLI_QUALITY = 9;
 const GZIP_LEVEL = 9;
 const { formatBytes } = FontPruner;
@@ -20,14 +22,16 @@ export interface PrecompressArtifactsResult {
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  //* WebRouter serves client/ and styles/ through the same sidecar-aware #fileResponse.
+  //* WebRouter serves client/, styles/ and dict/ through the same sidecar-aware #fileResponse.
+  const artifactDir = path.join(app.dist.cwdPath, ".akan/artifact");
   const roots = [
-    path.join(app.dist.cwdPath, ".akan/artifact/client"),
-    path.join(app.dist.cwdPath, ".akan/artifact/styles"),
+    { root: path.join(artifactDir, "client") },
+    { root: path.join(artifactDir, "styles") },
+    { root: path.join(artifactDir, "dict"), brotliQuality: MAX_BROTLI_QUALITY },
   ];
   const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0, brotliBytes: 0 };
 
-  await Promise.all(roots.map((root) => precompressRoot(root, result)));
+  await Promise.all(roots.map(({ root, brotliQuality }) => precompressRoot(root, result, brotliQuality)));
   if (result.files > 0) {
     app.verbose(
       `[precompress] wrote ${result.files} sidecars (${formatBytes(result.inputBytes)} -> gzip ${formatBytes(
@@ -38,7 +42,11 @@ export async function precompressArtifacts(app: App): Promise<PrecompressArtifac
   return result;
 }
 
-async function precompressRoot(root: string, result: PrecompressArtifactsResult): Promise<void> {
+async function precompressRoot(
+  root: string,
+  result: PrecompressArtifactsResult,
+  brotliQuality?: number,
+): Promise<void> {
   if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) return;
   const glob = new Bun.Glob("**/*");
   for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
@@ -46,7 +54,7 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
     const bytes = await Bun.file(filePath).bytes();
     const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
     const gz = Bun.gzipSync(buffer, { level: GZIP_LEVEL });
-    const br = brotliCompress(buffer, path.extname(filePath).toLowerCase());
+    const br = brotliCompress(buffer, brotliQuality ?? brotliQualityOf(path.extname(filePath).toLowerCase()));
     await Promise.all([Bun.write(`${filePath}.gz`, gz), Bun.write(`${filePath}.br`, br)]);
     result.files += 1;
     result.inputBytes += bytes.byteLength;
@@ -55,8 +63,11 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
   }
 }
 
-function brotliCompress(buffer: ArrayBuffer, ext: string): Buffer {
-  const quality = BROTLI_QUALITY_BY_EXT[ext as keyof typeof BROTLI_QUALITY_BY_EXT] ?? DEFAULT_BROTLI_QUALITY;
+function brotliQualityOf(ext: string): number {
+  return BROTLI_QUALITY_BY_EXT[ext as keyof typeof BROTLI_QUALITY_BY_EXT] ?? DEFAULT_BROTLI_QUALITY;
+}
+
+function brotliCompress(buffer: ArrayBuffer, quality: number): Buffer {
   return zlib.brotliCompressSync(buffer, {
     params: {
       [zlib.constants.BROTLI_PARAM_QUALITY]: quality,

package/frontendBuild/routeClientBuilder.ts

@@ -169,6 +169,7 @@ export class RouteClientBuilder {
       plugins: [
         await createBarrelImportsPlugin(this.#app, {
           pipeAfter: reactFastRefresh ? RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh : undefined,
+          external: VENDOR_SPECIFIERS,
         }),
       ],
       external: VENDOR_SPECIFIERS,

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -8,6 +8,7 @@ import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "
 import type { App } from "../commandDecorators";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
 import { CssCompiler, type ImportedStylesheet } from "./cssCompiler";
+import { DictionaryAssetBuilder } from "./dictionaryAssetBuilder";
 import { FontOptimizer } from "./fontOptimizer";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { RouteClientBuilder } from "./routeClientBuilder";
@@ -56,6 +57,7 @@ export class SsrBaseArtifactBuilder {
 
     const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
     const { cssCompiler, optimizedFonts, cssAssets } = await this.#buildStyleAssets();
+    const dictAssets = await new DictionaryAssetBuilder(this.#app, this.#absArtifactDir).build(akanConfig.i18n);
     const pagesBundle = await new PagesBundleBuilder(this.#app, this.#command, pageEntries, this.#serverEnv).build();
     this.#app.verbose(
       `[base-artifact] pages bundle -> ${pagesBundle.bundlePath} (buildId=${pagesBundle.buildId}, splitting=${pagesBundle.splitting}, entry=${pagesBundle.entryBytes} bytes, outputs=${pagesBundle.outputCount}, chunks=${pagesBundle.chunkCount}, total=${pagesBundle.outputBytes} bytes)`,
@@ -75,6 +77,7 @@ export class SsrBaseArtifactBuilder {
       rscRuntimeSsrManifest,
       vendorMap,
       cssAssets,
+      dictAssets,
       pagesBundlePath:
         this.#command === "build"
           ? path.relative(this.#absArtifactDir, pagesBundle.bundlePath)

package/frontendBuild/vendorSpecifiers.ts

@@ -12,6 +12,7 @@ export const VENDOR_SPECIFIERS = [
   "akanjs/common",
   "akanjs/constant",
   "akanjs/fetch",
+  "tailwind-merge",
 ] as const;
 
 export type VendorSpecifier = (typeof VENDOR_SPECIFIERS)[number];

package/incrementalBuilder/buildBatch.proc.ts

@@ -108,10 +108,10 @@ class BuildBatch {
   async #buildShell(): Promise<void> {
     const started = Date.now();
     try {
-      await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).build();
-      this.#logger.verbose(`csr-shell ok (${Date.now() - started}ms)`);
+      await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).buildMcpAppViews();
+      this.#logger.verbose(`mcp-app-views ok (${Date.now() - started}ms)`);
     } catch (err) {
-      this.#fail("shell", "csr-shell", err);
+      this.#fail("shell", "mcp-app-views", err);
     }
   }
 

package/incrementalBuilder/buildBatchProtocol.ts

@@ -3,8 +3,8 @@ import type { BaseBuildArtifact, CssPayload, HmrTrace, PagesBundlePayload } from
 
 export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
 
-// `base` is the boot build: it always runs alone, before the builder can serve anything. `shell` is the single-file
-// CSR build an MCP Apps view needs under the dev CSR registry, made on request and reported to no tab.
+// `base` is the boot build: it always runs alone, before the builder can serve anything. `shell` is the MCP App views'
+// single-file build under the dev CSR registry, made on request and reported to no tab.
 export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr" | "shell";
 
 // JSON only: the worker is spawned per batch and receives this in its argv.

package/lint/__fixtures__/no-conditional-st-hook/bad.tsx

@@ -0,0 +1,45 @@
+export const A = () => {
+  const busy = st.use.xUploading() || !!st.use.xFormUploading().voice; // @flag
+  const shown = open && st.sel((s) => s.a); // @flag
+  const label = name ?? st.use.defaultName(); // @flag
+  const picked = open ? st.use.b() : null; // @flag
+  const latest = open ? null : st.ref((s) => s.c); // @flag
+  if (open) { const d = st.use.d(); } // @flag
+  if (open) { run(); } else { const e = st.slice.inOrg.use.e(); } // @flag
+  switch (mode) { case "a": st.use.f(); } // @flag
+  for (const item of items) st.use.g(); // @flag
+  while (more) st.use.h(); // @flag
+  try { run(); } catch { st.use.i(); } // @flag
+  const rows = items.map((item) => st.use.j()); // @flag
+  useEffect(() => { st.use.k(); }, []); // @flag
+  const tool = open && st.tool("x").desc("d").exec(() => run()); // @flag
+  const card = open ? st.tool("y").desc("d").card(() => null) : null; // @flag
+  const [l] = open ? st.useState("l", String).desc("d").init("") : []; // @flag
+  if (open) st.expose("m", String).desc("d").value("x"); // @flag
+  const save = st.tool("z").desc("d").exec(async () => { st.use.n(); }); // @flag
+  const { title = st.use.title() } = props; // @flag
+  let cached = initial; cached ||= st.use.s(); // @flag
+  cached ??= st.use.t(); // @flag
+  cached &&= st.use.u(); // @flag
+  for (let i = 0; i < st.use.count(); i++) run(i); // @flag
+  const formatted = props.format?.(st.use.v()); // @flag
+  const chained = props.api?.format(st.use.w()); // @flag
+  const computed = open ? st["use"].x() : null; // @flag
+  const computedKey = open ? st.use["y"]() : null; // @flag
+  const computedSlice = open ? st.slice["inOrg"].use.z() : null; // @flag
+  useEffect(() => { void (async () => { await load(); st.use.aa(); })(); }, []); // @flag
+  return <div onClick={() => st.use.o()} />; // @flag
+};
+export const B = () => <Load.Units renderList={(list) => <X a={st.use.p()} />} />; // @flag
+export const C = () => <Load.Stream of={q}>{(v) => <X a={st.sel((s) => s.q)} />}</Load.Stream>; // @flag
+export const useD = () => useMemo(() => st.use.r(), []); // @flag
+export const E = ({ name = st.use.defaultName() }) => <p>{name}</p>; // @flag
+export function F({ name = st.sel((s) => s.name) }) { return <p>{name}</p>; } // @flag
+export const G = () => {
+  const renderRow = (item) => <X a={st.use.bb()} />; // @flag
+  return <Load.Units renderItem={renderRow} />;
+};
+export const H = () => {
+  function row(item) { return <X a={st.ref((s) => s.cc)} />; } // @flag
+  return <ul>{items.map(row)}</ul>;
+};

package/lint/__fixtures__/no-conditional-st-hook/good.tsx

@@ -0,0 +1,33 @@
+export const A = () => {
+  const uploading = st.use.xUploading(); // @ok
+  const formUploading = st.use.xFormUploading(); // @ok
+  const busy = uploading || !!formUploading.voice; // @ok
+  const first = st.use.a() || fallback; // @ok
+  const picked = st.use.b() ? one : two; // @ok
+  if (st.use.c()) run(); // @ok
+  switch (st.use.mode()) { case "a": run(); } // @ok
+  for (const item of st.use.items()) run(item); // @ok
+  const selected = st.sel((s) => s.d); // @ok
+  const latest = st.ref((s) => s.e); // @ok
+  const save = st.tool("save").desc("d").exec(async () => { await st.do.saveX(); }); // @ok
+  const [f, setF] = st.useState("f", String).desc("d").init(""); // @ok
+  st.expose("g", String).desc("d").value(f); // @ok
+  useEffect(() => st.sub((s) => s.h, run), []); // @ok
+  return <div onClick={() => st.do.setNameOnX(st.get().name)}>{open ? <Child /> : null}</div>; // @ok
+};
+export const B = memo(() => { const a = st.use.a(); return null; }); // @ok
+export const C = forwardRef((props, ref) => { const b = st.sel((s) => s.b); return null; }); // @ok
+export const useTools = () => { const tool = (name) => st.tool(name).desc("d").exec(() => run()); tool("a"); }; // @ok
+export const D = () => <Load.Units renderItem={(item) => <Row key={item.id} id={item.id} />} />; // @ok
+export const E = () => { const busy = open && other.use.x(); return busy; }; // @ok
+export const F = () => { const Submit = useMemo(() => () => { const v = st.use.x(); return v; }, []); return <Submit />; }; // @ok
+export const G = () => { const Submit = useMemo(() => (open ? () => null : () => { const save = st.tool("s").desc("d").exec(run); return <Button onClick={save} />; }), [open]); return <Submit />; }; // @ok
+export const H = () => { for (let i = st.use.start(); i < 3; i++) run(i); return null; }; // @ok
+export const I = isNative ? () => { const a = st.use.a(); return a; } : () => null; // @ok
+export const J = () => { const a = (() => st.use.x())(); return a; }; // @ok
+export const K = () => { const Row = () => { const a = st.use.a(); return a; }; return <List row={Row} />; }; // @ok
+const renderPage = () => { const a = st.use.a(); return a; }; // @ok
+export const L = page().render(renderPage); // @ok
+export const M = () => { const v = st.use.x(); props.onPick?.(v); return v; }; // @ok
+export const N = () => { const a = st["use"].a(); const b = st.use["b"](); return a ?? b; }; // @ok
+export const O = () => { let v = cached; v = st.use.a(); return v; }; // @ok

package/lint/no-conditional-st-hook.grit

@@ -0,0 +1,146 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `st.use.<key>()`, `st.slice.<name>.use.<key>()`, `st.sel()`, `st.ref()` and the builders' last step
+// (`st.tool(…)….exec()` / `.card()`, `st.useState(…)….init()`, `st.expose(…)….value()`) are React hooks that Biome's
+// `useHookAtTopLevel` cannot see: it recognises a hook by a `use` prefix on the called name. A hook a render skips
+// shifts every later hook by one slot, and production React does not check the order — a later `useRef` then
+// receives a frozen store value and the screen dies far from the cause ("Cannot add property current, object is not
+// extensible").
+//
+// Reported: the right operand of `||` / `&&` / `??` and of `||=` / `&&=` / `??=`, a ternary branch, an `if` / `else`
+// body, a `switch` case, a loop (a `for` initializer runs once and is not one), a `catch` block, a default value,
+// the arguments of an optional call, and a callback handed to a call or a JSX prop inside a component, inline or by
+// a camelCase name (`.map`, `useEffect`, an event handler, a render prop — `Load.Units` calls `renderList` only while
+// the list is non-empty). A test position is not reported: `if (st.use.x())` always runs. Each position counts up to
+// the nearest function only, so a component defined in `useMemo` or picked by a module-level ternary is its own
+// render; a PascalCase name is a component, which React renders rather than calls.
+//
+// Not reported: a hook after an early `return` (GritQL sees no statement order), a local helper the component
+// calls (`const tool = (name) => st.tool(name)…exec(…)` runs a fixed number of times when called at top level),
+// and a hook reached through anything but the `st` identifier.
+//
+pattern st_hook_call() {
+  or {
+    `st.use.$key($args)`,
+    `st.slice.$slice.use.$key($args)`,
+    `st.sel($args)`,
+    `st.ref($args)`,
+    `$chain.exec($args)` where { $chain <: r"st\s*\.\s*tool\s*\([\s\S]*" },
+    `$chain.card($args)` where { $chain <: r"st\s*\.\s*tool\s*\([\s\S]*" },
+    `$chain.init($args)` where { $chain <: r"st\s*\.\s*useState\s*\([\s\S]*" },
+    `$chain.value($args)` where { $chain <: r"st\s*\.\s*expose\s*\([\s\S]*" },
+    // Computed access (`st["use"].x()`, `st.use[key]()`) at any step, which would take a snippet per combination.
+    JsCallExpression(callee = $callee) where {
+      $callee <: or {
+        r"st\s*(?:\.\s*use|\[\s*[\x27\x22`]use[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])",
+        r"st\s*(?:\.\s*slice|\[\s*[\x27\x22`]slice[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])\s*(?:\.\s*use|\[\s*[\x27\x22`]use[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])",
+        r"st\s*\[\s*[\x27\x22`](?:sel|ref)[\x27\x22`]\s*\]"
+      }
+    }
+  }
+}
+
+pattern function_like() {
+  or {
+    JsArrowFunctionExpression(),
+    JsFunctionExpression(),
+    JsFunctionDeclaration(),
+    JsFunctionExportDefaultDeclaration(),
+    JsMethodObjectMember(),
+    JsGetterObjectMember(),
+    JsSetterObjectMember(),
+    JsMethodClassMember(),
+    JsGetterClassMember(),
+    JsSetterClassMember(),
+    JsConstructorClassMember()
+  }
+}
+
+// An IIFE runs where it stands, so the position around it still decides whether its hooks run.
+pattern function_boundary() {
+  function_like() as $boundary where {
+    not $boundary <: within JsCallExpression(callee = $iifeCallee) where {
+      $iifeCallee <: or { $boundary, JsParenthesizedExpression(expression = $boundary) }
+    }
+  }
+}
+
+pattern callback_slot() {
+  or { JsCallArguments(), JsxExpressionAttributeValue(), JsxExpressionChild() }
+}
+
+pattern passed_by_name($name) {
+  or {
+    JsCallArguments(args = [..., $arg where { $arg <: $name }, ...]),
+    JsxExpressionAttributeValue(expression = $arg) where { $arg <: $name },
+    JsxExpressionChild(expression = $arg) where { $arg <: $name }
+  }
+}
+
+JsCallExpression() as $call where {
+  $call <: st_hook_call(),
+  or {
+    $call <: within JsLogicalExpression(right = $right) where { $right <: contains $call } until function_boundary(),
+    // The operator token is not a field GritQL can read; `[^=]*` makes the first `=` in the text the operator's.
+    $call <: within JsAssignmentExpression(right = $right) as $assignment where {
+      $assignment <: r"[^=]*(?:\|\||&&|\?\?)=[\s\S]*",
+      $right <: contains $call
+    } until function_boundary(),
+    $call <: within JsConditionalExpression(consequent = $then, alternate = $else) where {
+      or { $then <: contains $call, $else <: contains $call }
+    } until function_boundary(),
+    $call <: within JsIfStatement(consequent = $then, else_clause = $else) where {
+      or { $then <: contains $call, $else <: contains $call }
+    } until function_boundary(),
+    $call <: within JsForStatement(initializer = $init) where { not $init <: contains $call } until function_boundary(),
+    $call <: within JsForOfStatement(body = $body) where { $body <: contains $call } until function_boundary(),
+    $call <: within JsForInStatement(body = $body) where { $body <: contains $call } until function_boundary(),
+    $call <: within or {
+      JsCaseClause(),
+      JsDefaultClause(),
+      JsWhileStatement(),
+      JsDoWhileStatement(),
+      JsCatchClause()
+    } until function_boundary(),
+    $call <: within or {
+      JsFormalParameter(initializer = $default),
+      JsObjectBindingPatternShorthandProperty(init = $default),
+      JsObjectBindingPatternProperty(init = $default),
+      JsArrayBindingPatternElement(init = $default),
+      JsObjectAssignmentPatternShorthandProperty(init = $default),
+      JsObjectAssignmentPatternProperty(init = $default),
+      JsArrayAssignmentPatternElement(init = $default)
+    } where { $default <: contains $call } until function_boundary(),
+    // A `?.` ahead of the callee's first `(` or `[` sits on its own chain, so a nullish link skips the arguments.
+    $call <: within JsCallExpression(callee = $callee, arguments = $arguments) as $outerCall where {
+      $arguments <: contains $call,
+      or { $outerCall <: `$optionalCallee?.($optionalArgs)`, $callee <: r"[^\[\(]*\?\.[\s\S]*" }
+    } until function_boundary(),
+    and {
+      $call <: within function_boundary() as $nearest until function_boundary(),
+      or {
+        // The callback must be handed over inside another function: a component passed to `memo()` /
+        // `forwardRef()` at module level is not one.
+        $nearest <: within callback_slot() as $slot where { $slot <: within function_boundary() } until function_boundary(),
+        and {
+          or {
+            $nearest <: JsFunctionDeclaration(id = $name),
+            $nearest <: within JsVariableDeclarator(id = $name, initializer = JsInitializerClause(expression = $value)) where {
+              $value <: $nearest
+            } until function_boundary()
+          },
+          $name <: r"[a-z_$][\w$]*",
+          $nearest <: within or { JsFunctionBody(), JsModule() } as $scope where {
+            $scope <: contains passed_by_name($name) as $handover where { $handover <: within function_boundary() }
+          } until or { JsFunctionBody(), JsModule() }
+        }
+      }
+    }
+  },
+  register_diagnostic(
+    span = $call,
+    message = "This st hook does not run on every render — it sits behind a condition, in a loop, or in a nested function. React matches hooks by call order, so the hooks after it shift by one slot and a later one reads another hook's state; production React does not check, and the screen crashes somewhere else. Read each st.use.* into its own const at the top of the component, then combine the values: const uploading = st.use.xUploading(); const formUploading = st.use.xFormUploading(); const busy = uploading || !!formUploading.voice. For a list, move the hook into a child component rendered per item.",
+    severity = "error"
+  )
+}