@assistant-ui/next 0.0.1

package/README.md

@@ -0,0 +1,100 @@
+# @assistant-ui/next
+
+Next.js integration for assistant-ui: the `withAui()` config wrapper and the
+compiler for the `"use generative"` directive. Colocate a tool's **schema**,
+**server-only `execute`**, and **client-only `render`** in one file; the compiler
+emits a different module per build target so each side only loads what it needs.
+
+See [SPEC.md](./SPEC.md) for the full design.
+
+## Why
+
+`"use client"` is whole-module, so it can't keep a tool's zod schema readable on
+the server while keeping its `render` on the client. And a backend `execute`
+holds secrets (DB handles, API keys) that must never reach the browser bundle.
+`"use generative"` routes each property to the right place.
+
+Every tool **must** declare an `execute`, and you wrap the default export in
+`defineToolkit({ ... })` (both are enforced — the compiler errors otherwise). You
+don't declare a tool's kind: the compiler **infers** it from the `execute` and
+writes a `type` field back into the output.
+
+| how you author the `execute`              | kind       | where it runs                |
+| ----------------------------------------- | ---------- | ---------------------------- |
+| `execute` with a `"use client"` directive | `frontend` | client                       |
+| `execute` (plain)                         | `backend`  | server (`server-only` guard) |
+| `execute: hitl()`                         | `human`    | — (the UI supplies a result) |
+
+A plain `execute` is server-only by default — you can only run one in the browser
+by opting in with `"use client"`, so secrets can't leak by omission.
+
+## Authoring
+
+```tsx
+"use generative";
+import { z } from "zod";
+import { defineToolkit } from "@assistant-ui/react";
+import { db } from "@/db"; // server-only
+import { Chart } from "@/ui/chart"; // client-only
+
+export default defineToolkit({
+  weather: {
+    description: "Show the weather for a city.",
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => db.weather.get(city), // backend → stays on the server
+    render: (props) => <Chart data={props} />, // stays on the client
+  },
+});
+```
+
+The server build keeps `parameters` + `execute` (guarded by `import
+"server-only"`, tagged `type: "backend"`) and drops `render` and `@/ui/chart`.
+The client build keeps `parameters` + `render` (under `"use client"`) and drops
+`execute` and `@/db`. A `frontend` tool marks its `execute` with `"use client"`:
+
+```tsx
+execute: async ({ city }) => {
+  "use client";
+  return navigator.geolocation /* … runs in the browser, kept client-side */;
+},
+```
+
+## Wiring into Next.js
+
+Wrap your config. Detection is by the `"use generative"` directive — there is **no
+filename convention**; modules without the directive pass through untouched.
+
+```ts
+// next.config.ts
+import { withAui } from "@assistant-ui/next";
+
+export default withAui({
+  /* your Next config */
+});
+```
+
+`withAui` applies the loader to your TS/TSX. To limit how many files it
+scans, narrow the globs: `withAui(config, { rules: ["*.generative.tsx"] })`.
+
+Import the module **bare** from both sides — the loader rewrites it into a facade
+that resolves to the right build per layer (no query, no per-file config):
+
+```tsx
+// a client component → resolves to the client build (schema + render)
+import toolkit from "@/lib/chat.generative";
+
+// a route handler (react-server layer) → resolves to the server build (schema + execute)
+import toolkit from "@/lib/chat.generative";
+```
+
+With the AI SDK, convert the server build to a `ToolSet` (see
+`generativeTools` in `@assistant-ui/react-ai-sdk`).
+
+> **Validated on Next 16.2.6 (Turbopack).** Turbopack honors the loader-emitted
+> `"use client"`, but compiles one output per resource path — so the server build
+> is selected by its own `?generative-env=server` query rather than by build layer.
+> Clear `.next` after changing the loader (Turbopack caches loader output).
+
+## License
+
+MIT

package/SPEC.md

@@ -0,0 +1,154 @@
+# `"use generative"` — specification
+
+## Problem
+
+A tool has three regions of code with three different deployment targets:
+
+| region                      | server (registration + agent loop) | client (browser) |
+| --------------------------- | ---------------------------------- | ---------------- |
+| `description` / `parameters`| needed (→ LLM, parse)              | needed (→ parse) |
+| `render`                    | **must not load** (React/CSS/DOM)  | needed           |
+| `execute`                   | depends on kind (see routing)      | depends on kind  |
+
+We want to **colocate all three in one source file** for DX, but keep `render`'s
+client deps out of the server bundle and — more importantly — keep a backend
+`execute`'s server deps (DB handles, API keys, server SDKs) out of the **client**
+bundle. The second direction is a *security* boundary, not just bundle hygiene.
+
+`"use client"` cannot express this: it is whole-module, so a `"use client"`
+generative module would also turn `parameters` into a client reference on the server,
+making the zod schema unreadable server-side. We need **sub-module, per-property**
+routing. That is what the `"use generative"` directive provides.
+
+## The directive
+
+A module opts in with a leading directive and a single default export wrapped in
+`defineToolkit`:
+
+```tsx
+"use generative";
+import { z } from "zod";
+import { defineToolkit } from "@assistant-ui/react";
+import { db } from "@/db"; // server-only dependency
+import { Chart } from "@/ui/chart"; // client-only dependency
+
+export default defineToolkit({
+  weather: {
+    description: "Show the weather for a city.",
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => db.weather.get(city), // backend (server-only)
+    render: (props) => <Chart data={props} />, // client-only
+  },
+});
+```
+
+The file is imported from both server and client code; the compiler emits a
+different module per build target so each side only loads what it needs.
+
+## Routing (by inferred kind)
+
+A tool's kind is **not authored** — declaring a `type` field is a type error. The
+compiler infers it from the `execute` and writes the resolved `type` back into
+each emitted tool object (so the runtime keeps it):
+
+| how it's authored                         | inferred kind | `render` | `execute`                        |
+| ----------------------------------------- | ------------- | -------- | -------------------------------- |
+| `execute` with a `"use client"` directive | `frontend`    | client   | **client** (bundled with render) |
+| `execute` (plain)                         | `backend`     | client   | **server** (`server-only` leaf)  |
+| `execute: hitl()`                         | `human`       | client   | — (dropped; the UI resolves it)  |
+
+Consequences:
+
+- For `frontend` entries the server keeps **schema only** — render *and* execute
+  are client concerns.
+- `backend` is the only kind that produces the server-only secrets boundary; its
+  `execute` leaf imports `server-only`, so any routing mistake that pulls it into
+  the client build fails the build instead of leaking secrets.
+- **Server-by-default is the safe default:** a plain `execute` stays server-only,
+  so a forgotten marker can't leak — you opt *into* the client with `"use client"`.
+  A frontend `execute`'s `"use client"` is stripped from the output (the module
+  already carries it).
+
+## Compile targets
+
+The compiler produces two self-contained rewrites of the source, selected by the
+bundler per build layer. Each rewrite keeps only the relevant regions and prunes
+the imports that became unused, so a dropped region's dependencies disappear.
+
+### `client` target
+
+- Keep `description`, `parameters`, `render`, and `execute` of `frontend` tools.
+- Drop `execute` of `backend` tools (and its now-unused imports).
+- Prepend `"use client"` when any `render` remains.
+
+### `server` target
+
+- Keep `description`, `parameters`, and `execute` of `backend` tools.
+- Drop every `render` (and its now-unused imports).
+- Drop `execute` of `frontend` tools.
+- Prepend `import "server-only"` when any backend `execute` remains.
+
+The `"use generative"` directive is stripped from both outputs.
+
+## Bundler integration
+
+Wrap the Next config with `withAui` from `@assistant-ui/next`
+(no filename convention — modules are matched by the `"use generative"` directive,
+and the loader passes non-generative files through untouched). It applies `./loader`,
+a webpack/Turbopack loader.
+
+The loader rewrites a **bare** generative import into a facade that delegates the
+build choice to a `react-server`-conditioned package subpath, so a single import
+resolves to the right build per layer — no query, no per-app config (see
+DESIGN.md for the mechanism):
+
+- route handler / RSC (`react-server` ON) → **server build** (schema + `execute`,
+  guarded by `server-only`)
+- client component, SSR + browser (`react-server` OFF) → **client build**
+  (schema + `render`)
+
+The concrete compile is keyed off an **internal** `?generative-env=server|client`
+query the facade generates — it is never authored by consumers, so no ambient
+module declaration is needed. (Clear `.next` after changing the loader —
+Turbopack caches loader output aggressively.)
+
+Why not infer the target from the build **layer** inside the loader? Turbopack
+compiles one output per resource path and does not give a loader a per-layer
+module instance — so the split must happen at resolve time (the `react-server`
+export condition), which is exactly what the facade routes through.
+
+## Consumption
+
+Both sides import the module **bare**; the facade resolves each to the right build:
+
+- **server:** import `./x.generative` in a route handler — it resolves to the
+  server build (schema + `execute`). With the AI SDK, `generativeTools({ toolkit,
+  frontendTools })` from `@assistant-ui/react-ai-sdk` converts it into a `ToolSet`
+  whose `execute` runs in the route, merging in the frontend-uploaded tools.
+- **client:** import `./x.generative` in a client component — it resolves to the
+  client build (schema + `render`) — and register its tool UI.
+
+Neither side ships the other's code, and the schema is never re-uploaded from
+the client per request — the server owns it.
+
+## Authoring constraints (enforced, with errors)
+
+1. A leading `"use generative"` directive.
+2. A single `export default defineToolkit({ ... })` (the wrapper is required;
+   optionally inside `satisfies` / `as`). No other exports.
+3. Every tool must declare an `execute`. Its form determines the kind: `hitl()`
+   → human; a leading `"use client"` directive → frontend (needs a block body,
+   not an expression body); otherwise backend. `type` is never authored.
+4. `render` / `execute` must be inline functions that close over **module
+   imports only**, so they can be routed/pruned without dragging local scope.
+
+## Known limitations (v1)
+
+- Bare side-effect imports (e.g. `import "./styles.css"`) cannot be attributed to
+  a region by reference analysis, so they are left untouched in both targets.
+- Output preserves TS/JSX; the loader must run before the bundler's TS/JSX pass
+  (the default in Next).
+- Turbopack honors a loader-emitted `"use client"` directive (validated on Next
+  16.2.6), but does not give a loader per-layer module instances — hence the
+  `?generative-env=server` query rather than layer inference. Clear `.next` after
+  changing the loader.

package/dist/bundler-redirect.client.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/bundler-redirect.client.js

@@ -0,0 +1,5 @@
+//#region src/bundler-redirect.client.ts
+throw new Error("@assistant-ui/next/bundler-redirect is internal; import it through the @assistant-ui/next loader.");
+//#endregion
+
+//# sourceMappingURL=bundler-redirect.client.js.map

package/dist/bundler-redirect.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundler-redirect.client.js","names":[],"sources":["../src/bundler-redirect.client.ts"],"sourcesContent":["// Internal default-condition indirection target (SSR + browser) — always\n// replaced by the @assistant-ui/next loader, which re-exports the module's\n// client build. Reaching this means the loader wasn't applied (see DESIGN.md).\nthrow new Error(\n  \"@assistant-ui/next/bundler-redirect is internal; import it through the \" +\n    \"@assistant-ui/next loader.\",\n);\n"],"mappings":";AAGA,MAAM,IAAI,MACR,mGAEF"}

package/dist/bundler-redirect.server.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/bundler-redirect.server.js

@@ -0,0 +1,5 @@
+//#region src/bundler-redirect.server.ts
+throw new Error("@assistant-ui/next/bundler-redirect is internal; import it through the @assistant-ui/next loader.");
+//#endregion
+
+//# sourceMappingURL=bundler-redirect.server.js.map

package/dist/bundler-redirect.server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundler-redirect.server.js","names":[],"sources":["../src/bundler-redirect.server.ts"],"sourcesContent":["// Internal `react-server` indirection target — always replaced by the\n// @assistant-ui/next loader, which re-exports the module's server build.\n// Reaching this means the loader wasn't applied (see DESIGN.md).\nthrow new Error(\n  \"@assistant-ui/next/bundler-redirect is internal; import it through the \" +\n    \"@assistant-ui/next loader.\",\n);\n"],"mappings":";AAGA,MAAM,IAAI,MACR,mGAEF"}

package/dist/define-toolkit.d.ts

@@ -0,0 +1,19 @@
+import { Toolkit, ToolkitDeclaration } from "@assistant-ui/core/react";
+
+//#region src/define-toolkit.d.ts
+/**
+ * Authoring helper for a `"use generative"` toolkit. Accepts the permissive
+ * {@link ToolkitDeclaration} (a `backend` tool may carry its server `execute`)
+ * and types the result as the canonical {@link Toolkit}.
+ *
+ * It has **no runtime implementation**. The `@assistant-ui/next` compiler strips
+ * the `defineToolkit(...)` wrapper (and its import) per build, so a correctly
+ * compiled `export default defineToolkit({...})` never calls this. If it *does*
+ * run, the module was not compiled by the use-generative loader — e.g.
+ * `defineToolkit` used outside a `"use generative"` file — which would ship a
+ * backend `execute` to the client. So it throws instead of silently leaking.
+ */
+declare function defineToolkit(_declaration: ToolkitDeclaration): Toolkit;
+//#endregion
+export { defineToolkit };
+//# sourceMappingURL=define-toolkit.d.ts.map

package/dist/define-toolkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-toolkit.d.ts","names":[],"sources":["../src/define-toolkit.ts"],"mappings":";;;;;AAcA;;;;;;;;AAAwE;;iBAAxD,aAAA,CAAc,YAAA,EAAc,kBAAA,GAAqB,OAAO"}

package/dist/define-toolkit.js

@@ -0,0 +1,20 @@
+//#region src/define-toolkit.ts
+/**
+* Authoring helper for a `"use generative"` toolkit. Accepts the permissive
+* {@link ToolkitDeclaration} (a `backend` tool may carry its server `execute`)
+* and types the result as the canonical {@link Toolkit}.
+*
+* It has **no runtime implementation**. The `@assistant-ui/next` compiler strips
+* the `defineToolkit(...)` wrapper (and its import) per build, so a correctly
+* compiled `export default defineToolkit({...})` never calls this. If it *does*
+* run, the module was not compiled by the use-generative loader — e.g.
+* `defineToolkit` used outside a `"use generative"` file — which would ship a
+* backend `execute` to the client. So it throws instead of silently leaking.
+*/
+function defineToolkit(_declaration) {
+	throw new Error("[assistant-ui/next] defineToolkit() has no runtime implementation — it is stripped at build time by the use-generative compiler. Reaching it means this module was not compiled (e.g. defineToolkit used outside a \"use generative\" file). Add the directive, or do not use defineToolkit here.");
+}
+//#endregion
+export { defineToolkit };
+
+//# sourceMappingURL=define-toolkit.js.map

package/dist/define-toolkit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-toolkit.js","names":[],"sources":["../src/define-toolkit.ts"],"sourcesContent":["import type { Toolkit, ToolkitDeclaration } from \"@assistant-ui/core/react\";\n\n/**\n * Authoring helper for a `\"use generative\"` toolkit. Accepts the permissive\n * {@link ToolkitDeclaration} (a `backend` tool may carry its server `execute`)\n * and types the result as the canonical {@link Toolkit}.\n *\n * It has **no runtime implementation**. The `@assistant-ui/next` compiler strips\n * the `defineToolkit(...)` wrapper (and its import) per build, so a correctly\n * compiled `export default defineToolkit({...})` never calls this. If it *does*\n * run, the module was not compiled by the use-generative loader — e.g.\n * `defineToolkit` used outside a `\"use generative\"` file — which would ship a\n * backend `execute` to the client. So it throws instead of silently leaking.\n */\nexport function defineToolkit(_declaration: ToolkitDeclaration): Toolkit {\n  throw new Error(\n    \"[assistant-ui/next] defineToolkit() has no runtime implementation — it is \" +\n      \"stripped at build time by the use-generative compiler. Reaching it means \" +\n      'this module was not compiled (e.g. defineToolkit used outside a \"use ' +\n      'generative\" file). Add the directive, or do not use defineToolkit here.',\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAcA,SAAgB,cAAc,cAA2C;CACvE,MAAM,IAAI,MACR,mSAIF;AACF"}

package/dist/hitl.d.ts

@@ -0,0 +1,18 @@
+//#region src/hitl.d.ts
+/**
+ * Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)
+ * supplies the result instead of code. Use it as the tool's `execute`:
+ *
+ * ```tsx
+ * confirm: { execute: hitl(), render: (props) => <Confirm {...props} /> }
+ * ```
+ *
+ * Like {@link defineToolkit}, it has **no runtime implementation**: the
+ * `@assistant-ui/next` compiler detects `execute: hitl()`, drops it, and stamps
+ * the tool `type: "human"`. Reaching it at runtime means the module wasn't
+ * compiled (used outside a `"use generative"` file), so it throws.
+ */
+declare function hitl(): never;
+//#endregion
+export { hitl };
+//# sourceMappingURL=hitl.d.ts.map

package/dist/hitl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.ts","names":[],"sources":["../src/hitl.ts"],"mappings":";;AAaA;;;;AAAoB;;;;;;;;iBAAJ,IAAA"}

package/dist/hitl.js

@@ -0,0 +1,21 @@
+//#region src/hitl.ts
+/**
+* Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)
+* supplies the result instead of code. Use it as the tool's `execute`:
+*
+* ```tsx
+* confirm: { execute: hitl(), render: (props) => <Confirm {...props} /> }
+* ```
+*
+* Like {@link defineToolkit}, it has **no runtime implementation**: the
+* `@assistant-ui/next` compiler detects `execute: hitl()`, drops it, and stamps
+* the tool `type: "human"`. Reaching it at runtime means the module wasn't
+* compiled (used outside a `"use generative"` file), so it throws.
+*/
+function hitl() {
+	throw new Error("[assistant-ui/next] hitl() has no runtime implementation — it marks a human-in-the-loop tool and is stripped at build time by the use-generative compiler. Reaching it means this module was not compiled (e.g. hitl() used outside a \"use generative\" file).");
+}
+//#endregion
+export { hitl };
+
+//# sourceMappingURL=hitl.js.map

package/dist/hitl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.js","names":[],"sources":["../src/hitl.ts"],"sourcesContent":["/**\n * Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)\n * supplies the result instead of code. Use it as the tool's `execute`:\n *\n * ```tsx\n * confirm: { execute: hitl(), render: (props) => <Confirm {...props} /> }\n * ```\n *\n * Like {@link defineToolkit}, it has **no runtime implementation**: the\n * `@assistant-ui/next` compiler detects `execute: hitl()`, drops it, and stamps\n * the tool `type: \"human\"`. Reaching it at runtime means the module wasn't\n * compiled (used outside a `\"use generative\"` file), so it throws.\n */\nexport function hitl(): never {\n  throw new Error(\n    \"[assistant-ui/next] hitl() has no runtime implementation — it marks a \" +\n      \"human-in-the-loop tool and is stripped at build time by the \" +\n      \"use-generative compiler. Reaching it means this module was not compiled \" +\n      '(e.g. hitl() used outside a \"use generative\" file).',\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,OAAc;CAC5B,MAAM,IAAI,MACR,iQAIF;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { defineToolkit } from "./define-toolkit.js";
+import { hitl } from "./hitl.js";
+import { WithAuiOptions, withAui } from "./with-aui.js";
+export { type WithAuiOptions, defineToolkit, hitl, withAui };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { defineToolkit } from "./define-toolkit.js";
+import { hitl } from "./hitl.js";
+import { withAui } from "./with-aui.js";
+export { defineToolkit, hitl, withAui };

package/dist/loader.d.ts

@@ -0,0 +1,16 @@
+//#region src/loader.d.ts
+/** The subset of the webpack/Turbopack loader context this loader reads. */
+interface GenerativeLoaderContext {
+  resourcePath?: string;
+  resourceQuery?: string;
+  sourceMap?: boolean;
+  getOptions?(): {
+    path?: string;
+  } | undefined;
+  async(): (err: unknown, code?: string, map?: object | null) => void;
+}
+/** Webpack/Turbopack loader for `"use generative"` modules. See DESIGN.md. */
+declare function generativeLoader(this: GenerativeLoaderContext, source: string): void;
+//#endregion
+export { generativeLoader as default };
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","names":[],"sources":["../src/loader.ts"],"mappings":";;UAeU,uBAAA;EACR,YAAA;EACA,aAAA;EACA,SAAA;EACA,UAAA;IAAiB,IAAA;EAAA;EACjB,KAAA,KAAU,GAAA,WAAc,IAAA,WAAe,GAAA;AAAA;;iBAuDjB,gBAAA,CACtB,IAAA,EAAM,uBAAuB,EAC7B,MAAA"}

package/dist/loader.js

@@ -0,0 +1,85 @@
+import * as nodePath from "node:path";
+import { compileGenerative, isGenerativeModule } from "@assistant-ui/x-generative-compiler";
+//#region src/loader.ts
+/** This package's name, used in the facade's re-export specifier. */
+const PKG = "@assistant-ui/next";
+/** Basenames of the react-server-conditioned indirection modules (see with-aui.ts). */
+const SERVER_INDIRECTION = "bundler-redirect.server";
+const CLIENT_INDIRECTION = "bundler-redirect.client";
+/** Whether this resolution is one of the package's indirection modules. */
+function indirectionVariant(resourcePath) {
+	const base = nodePath.basename(resourcePath);
+	if (base.startsWith(SERVER_INDIRECTION)) return "server";
+	if (base.startsWith(CLIENT_INDIRECTION)) return "client";
+	return null;
+}
+/** The concrete build forced by a `?generative-env=client|server` resource query. */
+function queryTarget(resourceQuery) {
+	if (!resourceQuery) return null;
+	const g = new URLSearchParams(resourceQuery).get("generative-env");
+	return g === "server" || g === "client" ? g : null;
+}
+/**
+* Facade for a bare generative import: delegates build selection to the
+* `react-server`-conditioned `/bundler-redirect` subpath, passing the module's
+* path via a Turbopack import attribute. See DESIGN.md.
+*/
+function buildFacade(resourcePath) {
+	return [
+		`import toolkit from "${PKG}/bundler-redirect" ${`with { turbopackLoader: "${PKG}/loader", turbopackLoaderOptions: ${JSON.stringify(JSON.stringify({ path: resourcePath }))} }`};`,
+		`export default toolkit;`,
+		``
+	].join("\n");
+}
+/**
+* Replaces an indirection module with a re-export of the chosen concrete build,
+* via a relative specifier (Turbopack won't resolve an absolute one). See
+* DESIGN.md.
+*/
+function buildIndirection(variant, fromPath, toPath) {
+	let rel = nodePath.relative(nodePath.dirname(fromPath), toPath).replace(/\\/g, "/");
+	if (!rel.startsWith(".")) rel = `./${rel}`;
+	return `export { default } from ${JSON.stringify(`${rel}?generative-env=${variant}`)};\n`;
+}
+/** Webpack/Turbopack loader for `"use generative"` modules. See DESIGN.md. */
+function generativeLoader(source) {
+	const callback = this.async();
+	const resourcePath = this.resourcePath ?? "";
+	const variant = indirectionVariant(resourcePath);
+	if (variant) {
+		const path = this.getOptions?.()?.path;
+		if (!path) {
+			callback(/* @__PURE__ */ new Error("[assistant-ui/next] indirection module loaded without a `path` option; it must be imported via the generated facade."));
+			return;
+		}
+		callback(null, buildIndirection(variant, resourcePath, path));
+		return;
+	}
+	const target = queryTarget(this.resourceQuery);
+	if (target) {
+		if (!isGenerativeModule(source)) {
+			callback(null, source);
+			return;
+		}
+		try {
+			const { code, map } = compileGenerative(source, {
+				target,
+				filename: resourcePath,
+				sourceMaps: this.sourceMap ?? false
+			});
+			callback(null, code, map);
+		} catch (error) {
+			callback(error);
+		}
+		return;
+	}
+	if (isGenerativeModule(source)) {
+		callback(null, buildFacade(resourcePath));
+		return;
+	}
+	callback(null, source);
+}
+//#endregion
+export { generativeLoader as default };
+
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","names":[],"sources":["../src/loader.ts"],"sourcesContent":["import * as nodePath from \"node:path\";\nimport {\n  compileGenerative,\n  isGenerativeModule,\n  type Target,\n} from \"@assistant-ui/x-generative-compiler\";\n\n/** This package's name, used in the facade's re-export specifier. */\nconst PKG = \"@assistant-ui/next\";\n\n/** Basenames of the react-server-conditioned indirection modules (see with-aui.ts). */\nconst SERVER_INDIRECTION = \"bundler-redirect.server\";\nconst CLIENT_INDIRECTION = \"bundler-redirect.client\";\n\n/** The subset of the webpack/Turbopack loader context this loader reads. */\ninterface GenerativeLoaderContext {\n  resourcePath?: string;\n  resourceQuery?: string;\n  sourceMap?: boolean;\n  getOptions?(): { path?: string } | undefined;\n  async(): (err: unknown, code?: string, map?: object | null) => void;\n}\n\n/** Whether this resolution is one of the package's indirection modules. */\nfunction indirectionVariant(resourcePath: string): Target | null {\n  const base = nodePath.basename(resourcePath);\n  if (base.startsWith(SERVER_INDIRECTION)) return \"server\";\n  if (base.startsWith(CLIENT_INDIRECTION)) return \"client\";\n  return null;\n}\n\n/** The concrete build forced by a `?generative-env=client|server` resource query. */\nfunction queryTarget(resourceQuery: string | undefined): Target | null {\n  if (!resourceQuery) return null;\n  // URLSearchParams strips a leading \"?\" per spec.\n  const g = new URLSearchParams(resourceQuery).get(\"generative-env\");\n  return g === \"server\" || g === \"client\" ? g : null;\n}\n\n/**\n * Facade for a bare generative import: delegates build selection to the\n * `react-server`-conditioned `/bundler-redirect` subpath, passing the module's\n * path via a Turbopack import attribute. See DESIGN.md.\n */\nfunction buildFacade(resourcePath: string): string {\n  const options = JSON.stringify(JSON.stringify({ path: resourcePath }));\n  const attr =\n    `with { turbopackLoader: \"${PKG}/loader\", ` +\n    `turbopackLoaderOptions: ${options} }`;\n  return [\n    `import toolkit from \"${PKG}/bundler-redirect\" ${attr};`,\n    `export default toolkit;`,\n    ``,\n  ].join(\"\\n\");\n}\n\n/**\n * Replaces an indirection module with a re-export of the chosen concrete build,\n * via a relative specifier (Turbopack won't resolve an absolute one). See\n * DESIGN.md.\n */\nfunction buildIndirection(\n  variant: Target,\n  fromPath: string,\n  toPath: string,\n): string {\n  let rel = nodePath\n    .relative(nodePath.dirname(fromPath), toPath)\n    .replace(/\\\\/g, \"/\");\n  if (!rel.startsWith(\".\")) rel = `./${rel}`;\n  const spec = JSON.stringify(`${rel}?generative-env=${variant}`);\n  return `export { default } from ${spec};\\n`;\n}\n\n/** Webpack/Turbopack loader for `\"use generative\"` modules. See DESIGN.md. */\nexport default function generativeLoader(\n  this: GenerativeLoaderContext,\n  source: string,\n): void {\n  const callback = this.async();\n  const resourcePath = this.resourcePath ?? \"\";\n\n  // 1) Package indirection (resolved via the `react-server` condition).\n  const variant = indirectionVariant(resourcePath);\n  if (variant) {\n    const path = this.getOptions?.()?.path;\n    if (!path) {\n      callback(\n        new Error(\n          \"[assistant-ui/next] indirection module loaded without a `path` \" +\n            \"option; it must be imported via the generated facade.\",\n        ),\n      );\n      return;\n    }\n    callback(null, buildIndirection(variant, resourcePath, path));\n    return;\n  }\n\n  // 2) Explicit concrete-build query (used by the indirection).\n  const target = queryTarget(this.resourceQuery);\n  if (target) {\n    if (!isGenerativeModule(source)) {\n      callback(null, source);\n      return;\n    }\n    try {\n      const { code, map } = compileGenerative(source, {\n        target,\n        filename: resourcePath,\n        sourceMaps: this.sourceMap ?? false,\n      });\n      callback(null, code, map);\n    } catch (error) {\n      callback(error);\n    }\n    return;\n  }\n\n  // 3) Bare import of a generative module → facade.\n  if (isGenerativeModule(source)) {\n    callback(null, buildFacade(resourcePath));\n    return;\n  }\n\n  // 4) Not a generative module.\n  callback(null, source);\n}\n"],"mappings":";;;;AAQA,MAAM,MAAM;;AAGZ,MAAM,qBAAqB;AAC3B,MAAM,qBAAqB;;AAY3B,SAAS,mBAAmB,cAAqC;CAC/D,MAAM,OAAO,SAAS,SAAS,YAAY;CAC3C,IAAI,KAAK,WAAW,kBAAkB,GAAG,OAAO;CAChD,IAAI,KAAK,WAAW,kBAAkB,GAAG,OAAO;CAChD,OAAO;AACT;;AAGA,SAAS,YAAY,eAAkD;CACrE,IAAI,CAAC,eAAe,OAAO;CAE3B,MAAM,IAAI,IAAI,gBAAgB,aAAa,EAAE,IAAI,gBAAgB;CACjE,OAAO,MAAM,YAAY,MAAM,WAAW,IAAI;AAChD;;;;;;AAOA,SAAS,YAAY,cAA8B;CAKjD,OAAO;EACL,wBAAwB,IAAI,qBAAqB,4BAHrB,IAAI,oCAFlB,KAAK,UAAU,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC,CAGjC,EAAE,IAEmB;EACtD;EACA;CACF,EAAE,KAAK,IAAI;AACb;;;;;;AAOA,SAAS,iBACP,SACA,UACA,QACQ;CACR,IAAI,MAAM,SACP,SAAS,SAAS,QAAQ,QAAQ,GAAG,MAAM,EAC3C,QAAQ,OAAO,GAAG;CACrB,IAAI,CAAC,IAAI,WAAW,GAAG,GAAG,MAAM,KAAK;CAErC,OAAO,2BADM,KAAK,UAAU,GAAG,IAAI,kBAAkB,SAChB,EAAE;AACzC;;AAGA,SAAwB,iBAEtB,QACM;CACN,MAAM,WAAW,KAAK,MAAM;CAC5B,MAAM,eAAe,KAAK,gBAAgB;CAG1C,MAAM,UAAU,mBAAmB,YAAY;CAC/C,IAAI,SAAS;EACX,MAAM,OAAO,KAAK,aAAa,GAAG;EAClC,IAAI,CAAC,MAAM;GACT,yBACE,IAAI,MACF,sHAEF,CACF;GACA;EACF;EACA,SAAS,MAAM,iBAAiB,SAAS,cAAc,IAAI,CAAC;EAC5D;CACF;CAGA,MAAM,SAAS,YAAY,KAAK,aAAa;CAC7C,IAAI,QAAQ;EACV,IAAI,CAAC,mBAAmB,MAAM,GAAG;GAC/B,SAAS,MAAM,MAAM;GACrB;EACF;EACA,IAAI;GACF,MAAM,EAAE,MAAM,QAAQ,kBAAkB,QAAQ;IAC9C;IACA,UAAU;IACV,YAAY,KAAK,aAAa;GAChC,CAAC;GACD,SAAS,MAAM,MAAM,GAAG;EAC1B,SAAS,OAAO;GACd,SAAS,KAAK;EAChB;EACA;CACF;CAGA,IAAI,mBAAmB,MAAM,GAAG;EAC9B,SAAS,MAAM,YAAY,YAAY,CAAC;EACxC;CACF;CAGA,SAAS,MAAM,MAAM;AACvB"}

package/dist/with-aui.d.ts

@@ -0,0 +1,29 @@
+//#region src/with-aui.d.ts
+interface WithAuiOptions {
+  /**
+   * Globs scanned for the `"use generative"` directive (default: all TS/TSX).
+   * Narrow it (e.g. `["*.generative.tsx"]`) to limit what passes through the loader.
+   */
+  rules?: string[];
+}
+type NextConfigLike = {
+  turbopack?: {
+    rules?: Record<string, unknown>;
+  } | undefined;
+  webpack?: ((config: any, context: any) => any) | null | undefined;
+};
+/**
+ * Wraps a Next.js config so `"use generative"` modules are compiled per build
+ * target. Detection is by directive, not filename. See DESIGN.md.
+ *
+ * @example
+ * ```ts
+ * // next.config.ts
+ * import { withAui } from "@assistant-ui/next";
+ * export default withAui({ ...yourConfig });
+ * ```
+ */
+declare function withAui<T extends NextConfigLike>(nextConfig?: T, options?: WithAuiOptions): T;
+//#endregion
+export { WithAuiOptions, withAui };
+//# sourceMappingURL=with-aui.d.ts.map

package/dist/with-aui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-aui.d.ts","names":[],"sources":["../src/with-aui.ts"],"mappings":";UAEiB,cAAA;EAAA;;;;EAKf,KAAK;AAAA;AAAA,KAIF,cAAA;EACH,SAAA;IAAc,KAAA,GAAQ,MAAM;EAAA;EAC5B,OAAA,KAAY,MAAA,OAAa,OAAA;AAAA;;;;;AAAY;AAcvC;;;;;;iBAAgB,OAAA,WAAkB,cAAA,EAChC,UAAA,GAAY,CAAA,EACZ,OAAA,GAAS,cAAA,GACR,CAAA"}

package/dist/with-aui.js

@@ -0,0 +1,45 @@
+//#region src/with-aui.ts
+const LOADER = "@assistant-ui/next/loader";
+/**
+* Wraps a Next.js config so `"use generative"` modules are compiled per build
+* target. Detection is by directive, not filename. See DESIGN.md.
+*
+* @example
+* ```ts
+* // next.config.ts
+* import { withAui } from "@assistant-ui/next";
+* export default withAui({ ...yourConfig });
+* ```
+*/
+function withAui(nextConfig = {}, options = {}) {
+	const globs = options.rules ?? ["*.ts", "*.tsx"];
+	const rules = { ...nextConfig.turbopack?.rules };
+	for (const glob of globs) {
+		const existing = rules[glob];
+		const existingLoaders = existing && typeof existing === "object" && Array.isArray(existing.loaders) ? existing.loaders : [];
+		rules[glob] = {
+			...existing,
+			loaders: [...existingLoaders, LOADER]
+		};
+	}
+	const userWebpack = nextConfig.webpack;
+	return {
+		...nextConfig,
+		turbopack: {
+			...nextConfig.turbopack,
+			rules
+		},
+		webpack(config, context) {
+			config.module.rules.push({
+				test: /\.[jt]sx?$/,
+				exclude: /node_modules/,
+				use: [LOADER]
+			});
+			return userWebpack ? userWebpack(config, context) : config;
+		}
+	};
+}
+//#endregion
+export { withAui };
+
+//# sourceMappingURL=with-aui.js.map

package/dist/with-aui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-aui.js","names":[],"sources":["../src/with-aui.ts"],"sourcesContent":["const LOADER = \"@assistant-ui/next/loader\";\n\nexport interface WithAuiOptions {\n  /**\n   * Globs scanned for the `\"use generative\"` directive (default: all TS/TSX).\n   * Narrow it (e.g. `[\"*.generative.tsx\"]`) to limit what passes through the loader.\n   */\n  rules?: string[];\n}\n\n// Loosely typed so this module doesn't need `next` as a dependency.\ntype NextConfigLike = {\n  turbopack?: { rules?: Record<string, unknown> } | undefined;\n  webpack?: ((config: any, context: any) => any) | null | undefined;\n};\n\n/**\n * Wraps a Next.js config so `\"use generative\"` modules are compiled per build\n * target. Detection is by directive, not filename. See DESIGN.md.\n *\n * @example\n * ```ts\n * // next.config.ts\n * import { withAui } from \"@assistant-ui/next\";\n * export default withAui({ ...yourConfig });\n * ```\n */\nexport function withAui<T extends NextConfigLike>(\n  nextConfig: T = {} as T,\n  options: WithAuiOptions = {},\n): T {\n  const globs = options.rules ?? [\"*.ts\", \"*.tsx\"];\n  // Merge into the user's rules: if a glob already has a `{ loaders }` rule,\n  // append ours rather than clobbering it (see DESIGN.md).\n  const rules: Record<string, unknown> = { ...nextConfig.turbopack?.rules };\n  for (const glob of globs) {\n    const existing = rules[glob];\n    const existingLoaders =\n      existing &&\n      typeof existing === \"object\" &&\n      Array.isArray((existing as { loaders?: unknown }).loaders)\n        ? (existing as { loaders: unknown[] }).loaders\n        : [];\n    rules[glob] = {\n      ...(existing as object),\n      loaders: [...existingLoaders, LOADER],\n    };\n  }\n\n  const userWebpack = nextConfig.webpack;\n\n  return {\n    ...nextConfig,\n    turbopack: {\n      ...nextConfig.turbopack,\n      rules,\n    },\n    webpack(config: any, context: any) {\n      // Turbopack-only facade; under webpack, import concrete builds explicitly\n      // with `?generative-env=server` / `=client`.\n      config.module.rules.push({\n        test: /\\.[jt]sx?$/,\n        exclude: /node_modules/,\n        use: [LOADER],\n      });\n      return userWebpack ? userWebpack(config, context) : config;\n    },\n  } as T;\n}\n"],"mappings":";AAAA,MAAM,SAAS;;;;;;;;;;;;AA2Bf,SAAgB,QACd,aAAgB,CAAC,GACjB,UAA0B,CAAC,GACxB;CACH,MAAM,QAAQ,QAAQ,SAAS,CAAC,QAAQ,OAAO;CAG/C,MAAM,QAAiC,EAAE,GAAG,WAAW,WAAW,MAAM;CACxE,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,WAAW,MAAM;EACvB,MAAM,kBACJ,YACA,OAAO,aAAa,YACpB,MAAM,QAAS,SAAmC,OAAO,IACpD,SAAoC,UACrC,CAAC;EACP,MAAM,QAAQ;GACZ,GAAI;GACJ,SAAS,CAAC,GAAG,iBAAiB,MAAM;EACtC;CACF;CAEA,MAAM,cAAc,WAAW;CAE/B,OAAO;EACL,GAAG;EACH,WAAW;GACT,GAAG,WAAW;GACd;EACF;EACA,QAAQ,QAAa,SAAc;GAGjC,OAAO,OAAO,MAAM,KAAK;IACvB,MAAM;IACN,SAAS;IACT,KAAK,CAAC,MAAM;GACd,CAAC;GACD,OAAO,cAAc,YAAY,QAAQ,OAAO,IAAI;EACtD;CACF;AACF"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@assistant-ui/next",
+  "version": "0.0.1",
+  "description": "Next.js integration for assistant-ui: the withAui() config wrapper and the \"use generative\" directive compiler that colocates a tool's schema, server-only execute, and client-only render in one file.",
+  "keywords": [
+    "assistant-ui",
+    "next",
+    "nextjs",
+    "generative",
+    "rsc",
+    "use client",
+    "server-only",
+    "compiler",
+    "loader"
+  ],
+  "author": "AgentbaseAI Inc.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./loader": {
+      "types": "./dist/loader.d.ts",
+      "default": "./dist/loader.js"
+    },
+    "./bundler-redirect": {
+      "react-server": "./dist/bundler-redirect.server.js",
+      "default": "./dist/bundler-redirect.client.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "SPEC.md",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "aui-build",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@assistant-ui/x-generative-compiler": "workspace:^"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@types/node": "^25.9.1",
+    "vitest": "^4.1.7"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://www.assistant-ui.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assistant-ui/assistant-ui.git",
+    "directory": "packages/next"
+  },
+  "bugs": {
+    "url": "https://github.com/assistant-ui/assistant-ui/issues"
+  }
+}

package/src/bundler-redirect.client.ts

@@ -0,0 +1,7 @@
+// Internal default-condition indirection target (SSR + browser) — always
+// replaced by the @assistant-ui/next loader, which re-exports the module's
+// client build. Reaching this means the loader wasn't applied (see DESIGN.md).
+throw new Error(
+  "@assistant-ui/next/bundler-redirect is internal; import it through the " +
+    "@assistant-ui/next loader.",
+);

package/src/bundler-redirect.server.ts

@@ -0,0 +1,7 @@
+// Internal `react-server` indirection target — always replaced by the
+// @assistant-ui/next loader, which re-exports the module's server build.
+// Reaching this means the loader wasn't applied (see DESIGN.md).
+throw new Error(
+  "@assistant-ui/next/bundler-redirect is internal; import it through the " +
+    "@assistant-ui/next loader.",
+);

package/src/index.ts

@@ -0,0 +1,3 @@
+export { withAui, type WithAuiOptions } from "./with-aui";
+export { defineToolkit } from "./define-toolkit";
+export { hitl } from "./hitl";

package/src/loader.ts

@@ -0,0 +1,128 @@
+import * as nodePath from "node:path";
+import {
+  compileGenerative,
+  isGenerativeModule,
+  type Target,
+} from "@assistant-ui/x-generative-compiler";
+
+/** This package's name, used in the facade's re-export specifier. */
+const PKG = "@assistant-ui/next";
+
+/** Basenames of the react-server-conditioned indirection modules (see with-aui.ts). */
+const SERVER_INDIRECTION = "bundler-redirect.server";
+const CLIENT_INDIRECTION = "bundler-redirect.client";
+
+/** The subset of the webpack/Turbopack loader context this loader reads. */
+interface GenerativeLoaderContext {
+  resourcePath?: string;
+  resourceQuery?: string;
+  sourceMap?: boolean;
+  getOptions?(): { path?: string } | undefined;
+  async(): (err: unknown, code?: string, map?: object | null) => void;
+}
+
+/** Whether this resolution is one of the package's indirection modules. */
+function indirectionVariant(resourcePath: string): Target | null {
+  const base = nodePath.basename(resourcePath);
+  if (base.startsWith(SERVER_INDIRECTION)) return "server";
+  if (base.startsWith(CLIENT_INDIRECTION)) return "client";
+  return null;
+}
+
+/** The concrete build forced by a `?generative-env=client|server` resource query. */
+function queryTarget(resourceQuery: string | undefined): Target | null {
+  if (!resourceQuery) return null;
+  // URLSearchParams strips a leading "?" per spec.
+  const g = new URLSearchParams(resourceQuery).get("generative-env");
+  return g === "server" || g === "client" ? g : null;
+}
+
+/**
+ * Facade for a bare generative import: delegates build selection to the
+ * `react-server`-conditioned `/bundler-redirect` subpath, passing the module's
+ * path via a Turbopack import attribute. See DESIGN.md.
+ */
+function buildFacade(resourcePath: string): string {
+  const options = JSON.stringify(JSON.stringify({ path: resourcePath }));
+  const attr =
+    `with { turbopackLoader: "${PKG}/loader", ` +
+    `turbopackLoaderOptions: ${options} }`;
+  return [
+    `import toolkit from "${PKG}/bundler-redirect" ${attr};`,
+    `export default toolkit;`,
+    ``,
+  ].join("\n");
+}
+
+/**
+ * Replaces an indirection module with a re-export of the chosen concrete build,
+ * via a relative specifier (Turbopack won't resolve an absolute one). See
+ * DESIGN.md.
+ */
+function buildIndirection(
+  variant: Target,
+  fromPath: string,
+  toPath: string,
+): string {
+  let rel = nodePath
+    .relative(nodePath.dirname(fromPath), toPath)
+    .replace(/\\/g, "/");
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  const spec = JSON.stringify(`${rel}?generative-env=${variant}`);
+  return `export { default } from ${spec};\n`;
+}
+
+/** Webpack/Turbopack loader for `"use generative"` modules. See DESIGN.md. */
+export default function generativeLoader(
+  this: GenerativeLoaderContext,
+  source: string,
+): void {
+  const callback = this.async();
+  const resourcePath = this.resourcePath ?? "";
+
+  // 1) Package indirection (resolved via the `react-server` condition).
+  const variant = indirectionVariant(resourcePath);
+  if (variant) {
+    const path = this.getOptions?.()?.path;
+    if (!path) {
+      callback(
+        new Error(
+          "[assistant-ui/next] indirection module loaded without a `path` " +
+            "option; it must be imported via the generated facade.",
+        ),
+      );
+      return;
+    }
+    callback(null, buildIndirection(variant, resourcePath, path));
+    return;
+  }
+
+  // 2) Explicit concrete-build query (used by the indirection).
+  const target = queryTarget(this.resourceQuery);
+  if (target) {
+    if (!isGenerativeModule(source)) {
+      callback(null, source);
+      return;
+    }
+    try {
+      const { code, map } = compileGenerative(source, {
+        target,
+        filename: resourcePath,
+        sourceMaps: this.sourceMap ?? false,
+      });
+      callback(null, code, map);
+    } catch (error) {
+      callback(error);
+    }
+    return;
+  }
+
+  // 3) Bare import of a generative module → facade.
+  if (isGenerativeModule(source)) {
+    callback(null, buildFacade(resourcePath));
+    return;
+  }
+
+  // 4) Not a generative module.
+  callback(null, source);
+}

package/src/with-aui.ts

@@ -0,0 +1,69 @@
+const LOADER = "@assistant-ui/next/loader";
+
+export interface WithAuiOptions {
+  /**
+   * Globs scanned for the `"use generative"` directive (default: all TS/TSX).
+   * Narrow it (e.g. `["*.generative.tsx"]`) to limit what passes through the loader.
+   */
+  rules?: string[];
+}
+
+// Loosely typed so this module doesn't need `next` as a dependency.
+type NextConfigLike = {
+  turbopack?: { rules?: Record<string, unknown> } | undefined;
+  webpack?: ((config: any, context: any) => any) | null | undefined;
+};
+
+/**
+ * Wraps a Next.js config so `"use generative"` modules are compiled per build
+ * target. Detection is by directive, not filename. See DESIGN.md.
+ *
+ * @example
+ * ```ts
+ * // next.config.ts
+ * import { withAui } from "@assistant-ui/next";
+ * export default withAui({ ...yourConfig });
+ * ```
+ */
+export function withAui<T extends NextConfigLike>(
+  nextConfig: T = {} as T,
+  options: WithAuiOptions = {},
+): T {
+  const globs = options.rules ?? ["*.ts", "*.tsx"];
+  // Merge into the user's rules: if a glob already has a `{ loaders }` rule,
+  // append ours rather than clobbering it (see DESIGN.md).
+  const rules: Record<string, unknown> = { ...nextConfig.turbopack?.rules };
+  for (const glob of globs) {
+    const existing = rules[glob];
+    const existingLoaders =
+      existing &&
+      typeof existing === "object" &&
+      Array.isArray((existing as { loaders?: unknown }).loaders)
+        ? (existing as { loaders: unknown[] }).loaders
+        : [];
+    rules[glob] = {
+      ...(existing as object),
+      loaders: [...existingLoaders, LOADER],
+    };
+  }
+
+  const userWebpack = nextConfig.webpack;
+
+  return {
+    ...nextConfig,
+    turbopack: {
+      ...nextConfig.turbopack,
+      rules,
+    },
+    webpack(config: any, context: any) {
+      // Turbopack-only facade; under webpack, import concrete builds explicitly
+      // with `?generative-env=server` / `=client`.
+      config.module.rules.push({
+        test: /\.[jt]sx?$/,
+        exclude: /node_modules/,
+        use: [LOADER],
+      });
+      return userWebpack ? userWebpack(config, context) : config;
+    },
+  } as T;
+}