@assembly-js/app-foundation 0.0.19 → 0.0.20

package/CLAUDE.md

@@ -188,15 +188,14 @@ Because the app runs in an iframe inside the parent dashboard, several normal Ne
 - **Action buttons go in the header — set via the `useAssemblyHeader` hook.** Submit, Save, Edit, Create — any primary page-level action MUST live in the header (`primaryCta`), not a `<Button>` in the page body. Secondary actions use `secondaryCta`; overflow/tertiary actions use `actionsMenu`. Drive all of it through the `useAssemblyHeader` hook (`app/components/use-assembly-header.ts`) — **never call `AssemblyBridge.header.set*` from your own `useEffect`** (that hand-rolling is what makes header buttons vanish after a re-render). See `.claude/skills/assembly-app-bridge-header/SKILL.md` for the full API.
   **Exception: the notification surface (`/n`).** The Notification Center embeds the `/n` route in a plain `<iframe>` without app bridge header support. `useAssemblyHeader` calls are silently ignored — header CTAs never appear. On the notification surface, render primary actions as inline `<Button>` elements in the page body. Detect the notification surface by the route — code under `app/n/` IS the surface; for a shared component pass an explicit prop from the `/n` page rather than inferring from `payload.notificationId`, which is best-effort under the session-exchange flow. This exception applies ONLY to the `/n` route; all other surfaces MUST use the header. **Do not reuse a component that calls `useAssemblyHeader` on the `/n` surface** — if it also has an inline action button, both the header CTA and the inline button will render on non-notification surfaces (duplicate CTAs). Either create a separate component for `/n` or accept a prop that switches between header and inline CTAs.
 - **Theme + fonts.** The portal pushes the workspace's theme to the iframe via `app-bridge`. Don't hardcode brand colors; use neutrals + Tailwind defaults and let the parent's theme show through where appropriate.
-- **`allowedDevOrigins` is required in `next.config.ts`.** Next.js 15.3+ blocks cross-origin requests to the dev server by default. Because the app renders in an iframe whose parent origin differs from the dev server hostname (a `*.vercel.run` subdomain), the JS bundle is blocked without this config. Read the sandbox hostname from the `SANDBOX_HOST` env var (set automatically) and add it as a literal string:
+- **`next.config.ts` is platform-owned — never edit it. Your Next config lives in `app.config.ts`.** The wrapper in `next.config.ts` (`withAssemblyDev` from `@assembly-js/app-foundation/next`) spreads `app.config.ts` and applies the iframe-preview invariants on top: `allowedDevOrigins` for the sandbox host (without it the app renders but has zero interactivity — hydration JavaScript is blocked cross-origin) and disabling the React debug channel (without it the preview hangs forever for users on WebSocket-blocking networks). Put your configuration in `app.config.ts`:
   ```ts
-  // next.config.ts — the hostname is patched automatically before bun dev
-  // starts, but if you rewrite next.config.ts, include it:
-  const nextConfig: NextConfig = {
-    allowedDevOrigins: ['sb-XXXX.vercel.run'], // use $SANDBOX_HOST value
+  // app.config.ts — app-owned; the platform wrapper applies invariants on top
+  const appConfig: NextConfig = {
+    serverExternalPackages: ["sharp", "canvas", "@napi-rs/canvas"],
   };
   ```
-  Without this, the app appears to render (server HTML loads) but has zero interactivity — buttons, forms, and client components don't work because hydration JavaScript is blocked. **The dev server startup patches this automatically — but if you rewrite `next.config.ts`, preserve the `allowedDevOrigins` entry.**
+  `bun run build` fails (`check:next-config`) if `next.config.ts` is rewritten away from the wrapper form.
 - **Leave `instrumentation-client.ts` in place.** It's a dev-only preview helper (hides Next's red error overlay and relays build status to the builder preview) that no-ops in production. Don't remove or repurpose it.
 - **`localStorage` works** but is scoped per-origin — the app's own Vercel domain. Useful for caching, not for sharing state with the parent.
 - **Mobile-first layout with appropriate width.** The app renders in the iframe and must work down to 320 px. Design mobile-first: start with a single-column layout and scale up with `sm:`/`md:`/`lg:` breakpoints. **Content width depends on the app type:** most apps (tables, dashboards, boards) should use the full available width. Form-centric, single-column, or text-heavy apps that would look sparse at full width should center their content in a narrower column (`max-w-3xl mx-auto`). If the task description or plan specifies a content width, follow it; otherwise choose whichever looks better for the content. **When narrowing, place the `max-w-*` wrapper as the outermost page-level container** — outside `Tabs`, filter bars, and all other page chrome — so everything aligns to the same column. Do not narrow only the inner content of each tab panel while leaving `TabsList` or other siblings full-width.
@@ -327,7 +326,7 @@ Server components, route handlers, and server actions run in **Node on Vercel**
 
 - **Visual work** (draw a chart, render on a canvas) is **client** work — load the library with `next/dynamic` + `ssr: false`, never in server code.
 - **Fuzzy extraction** (pull fields from a document, classify, summarize) is usually better done through the **AI proxy** (see `assembly-ai`) than a parsing lib — no native binding, no serverless hazard.
-- **Genuine server-side data work** (transform an image, parse bytes) must use a Node-native library: add native/CommonJS packages (e.g. `sharp`) to `serverExternalPackages` in `next.config.ts` (bundling breaks the binding), and give any dep that's loaded dynamically or transitively a static, string-literal import in server code — the deploy tracer can't follow dynamic requires, so such a package silently won't exist in the deployed function even though preview works.
+- **Genuine server-side data work** (transform an image, parse bytes) must use a Node-native library: add native/CommonJS packages (e.g. `sharp`) to `serverExternalPackages` in `app.config.ts` (bundling breaks the binding), and give any dep that's loaded dynamically or transitively a static, string-literal import in server code — the deploy tracer can't follow dynamic requires, so such a package silently won't exist in the deployed function even though preview works.
 - **Browser-only packages** (touch `window`/`document`/`DOMMatrix`/`HTMLCanvasElement` at import *or during operations*) can't run server-side at all — `serverExternalPackages` doesn't help and dynamic `import()` only defers the crash. Use a Node-native alternative or move the work client-side.
 
 ---
@@ -1124,7 +1123,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't hand-roll UI components (`<button>`, `<input>`, `<dialog>`, `<table>`, etc.) when a shadcn component exists. See the Design system section for install instructions. Using `Link`/`<a className={buttonVariants(...)}>` for a button-looking link is the intentional exception.
 
 - ❌ Don't add a manual close button (a `<DialogClose>` render or any X button) inside `DialogContent`. `DialogContent` already ships a built-in close button (`showCloseButton` defaults to `true`); adding another produces two overlapping X icons in the top-right corner. Only pass `showCloseButton={false}` when a custom affordance genuinely replaces the built-in one.
-- ❌ Don't skip `allowedDevOrigins` in `next.config.ts`. The iframe preview will render static HTML but JavaScript never loads (no hydration, no interactivity). If you rewrite `next.config.ts`, read `$SANDBOX_HOST` from the shell env and add it as a literal string in the config.
+- ❌ Don't edit `next.config.ts` — it's the platform-owned wrapper that keeps the preview working (cross-origin hydration, WebSocket-blocked networks), and `bun run build` fails if it's rewritten. Your Next configuration belongs in `app.config.ts`.
 - ❌ Don't import a native or browser-only library into server code without the serverless setup — `bun run build` passes but the deployed route crashes at request time. Decide the layer first per "Server runs in serverless Node" above.
 - ❌ Don't use `Select` or `Combobox` to pick any Assembly person or organization record (clients, internal users, team members, staff, companies). Always use `UserCompanySelector` — in forms, filters, dropdowns, "assign to" controls, everywhere.
 - ❌ Don't use `Combobox` when the user asks for a "dropdown" or "select" — use `Select`. Only use `Combobox` when the user explicitly needs type-to-search/filter functionality for non-user/non-company data.

package/bin/check-next-config.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Fails the build when next.config has been rewritten away from the
+// platform-owned wrapper form. Dependency-free on purpose: it runs inside the
+// generated app's sandbox before any deps beyond Node exist.
+//
+// next.config.ts is platform boilerplate: `export default withAssemblyDev(appConfig)`.
+// The wrapper (from @assembly-js/app-foundation/next) applies the dev-preview
+// invariants — allowedDevOrigins from the sandbox host, and disabling the React
+// debug channel, whose loss silently hangs hydration forever on Next 16.3+ when
+// the dev WebSocket can't connect. Agents legitimately need Next config
+// (serverExternalPackages etc.) — that lives in app.config.ts, which the
+// wrapper spreads. Prose rules get skipped; a failing build doesn't.
+//
+// An app without app.config.ts predates the wrapper split (cloned from an older
+// foundation). There the wrapper form was never the contract, so this check
+// exits 0 — those apps are protected by the boot/restart patch scripts instead.
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const CONFIG_FILES = ['next.config.ts', 'next.config.mjs', 'next.config.js'];
+const APP_CONFIG_FILES = ['app.config.ts', 'app.config.mjs', 'app.config.js'];
+
+if (!APP_CONFIG_FILES.some((f) => existsSync(join(ROOT, f)))) {
+  process.exit(0); // pre-wrapper app: not this check's contract
+}
+
+const present = CONFIG_FILES.filter((f) => existsSync(join(ROOT, f)));
+
+// A second config file shadows the wrapper: Next loads only one of them, and
+// its pick may be the unwrapped copy — so validating just the canonical file
+// would bless a config the server never runs.
+if (present.length > 1) {
+  console.error(
+    `check-next-config: multiple next.config files found (${present.join(', ')}). ` +
+      'next.config.ts is the platform-owned wrapper — delete the other config file(s) ' +
+      'and put your Next configuration in app.config.ts instead.',
+  );
+  process.exit(1);
+}
+
+const configFile = present[0];
+if (!configFile) {
+  console.error(
+    'check-next-config: no next.config.{ts,mjs,js} found. Restore the platform-owned wrapper:\n\n' +
+      '  import { withAssemblyDev } from "@assembly-js/app-foundation/next";\n' +
+      '  import appConfig from "./app.config";\n' +
+      '  export default withAssemblyDev(appConfig);\n',
+  );
+  process.exit(1);
+}
+
+const content = readFileSync(join(ROOT, configFile), 'utf8');
+const importsWrapper = /from\s+['"]@assembly-js\/app-foundation\/next['"]/.test(content);
+const exportsWrapped = /export\s+default\s+withAssemblyDev\s*\(/.test(content);
+
+if (importsWrapper && exportsWrapped) {
+  process.exit(0);
+}
+
+console.error(
+  `check-next-config: ${configFile} is platform-owned and must stay in the wrapper form:\n\n` +
+    '  import { withAssemblyDev } from "@assembly-js/app-foundation/next";\n' +
+    '  import appConfig from "./app.config";\n' +
+    '  export default withAssemblyDev(appConfig);\n\n' +
+    'Put your Next configuration (serverExternalPackages, experimental flags, …) in app.config.ts — ' +
+    'the wrapper spreads it and applies the Assembly dev-preview invariants on top. ' +
+    'Editing next.config.ts directly drops those invariants and permanently breaks the preview ' +
+    'for users on WebSocket-blocking networks.',
+);
+process.exit(1);

package/dist/next.d.ts

@@ -0,0 +1,2 @@
+import type { NextConfig } from 'next';
+export declare function withAssemblyDev(config?: NextConfig): NextConfig;

package/dist/next.js

@@ -0,0 +1,25 @@
+export function withAssemblyDev(config = {}) {
+    // Production builds (deploys) have no dev server, no HMR socket, and no
+    // sandbox host — the wrapper is a pass-through there.
+    if (process.env.NODE_ENV === 'production')
+        return config;
+    const sandboxHost = process.env.SANDBOX_HOST;
+    const allowedDevOrigins = sandboxHost
+        ? [...new Set([sandboxHost, ...(config.allowedDevOrigins ?? [])])]
+        : config.allowedDevOrigins;
+    // A dev WebSocket that never connects would otherwise hang hydration forever
+    // on Next 16.3+. Debug data falls back to the flight stream, so
+    // nothing user-visible is lost. Cast because this package type-checks against
+    // its Next 15 devDependency, which predates the flag; runtimes that predate
+    // it ignore the unknown key.
+    const experimental = {
+        ...config.experimental,
+        reactDebugChannel: false,
+    };
+    return {
+        ...config,
+        ...(allowedDevOrigins ? { allowedDevOrigins } : {}),
+        devIndicators: config.devIndicators ?? false,
+        experimental,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -22,6 +22,10 @@
     "./lib-client": {
       "types": "./dist/lib-client.d.ts",
       "default": "./dist/lib-client.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
     }
   },
   "scripts": {