@assembly-js/app-foundation 0.0.0 → 0.0.1-rc.2

package/dist/resource-resolution.js

@@ -0,0 +1,142 @@
+// Transport-free core of provider resource resolution: the option shape, the
+// page normalizer, and the paged search. No imports, so it is safe in both
+// server code (lib/nango.ts) and client components (ResourcePicker) — keep it
+// that way; anything that talks to the broker belongs in lib/nango.ts.
+// Cursor keys used by the resolver actions in the catalog, most common first.
+// 'offset' and 'cursor' can echo the request's own cursor back (Airtable,
+// Dropbox); the requestCursor guard in normalizeResourcePage handles that.
+const DEFAULT_CURSOR_KEYS = [
+    'next_cursor',
+    'nextCursor',
+    'nextPageToken',
+    'next_page_token',
+    'nextOffset',
+    'offset',
+    'cursor',
+];
+function getPath(value, path) {
+    let current = value;
+    for (const key of path.split('.')) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function asIdOrLabel(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return '';
+}
+function extractItems(raw, itemsPath) {
+    if (itemsPath) {
+        const items = getPath(raw, itemsPath);
+        return Array.isArray(items) ? items : [];
+    }
+    if (Array.isArray(raw))
+        return raw;
+    if (raw !== null && typeof raw === 'object') {
+        for (const value of Object.values(raw)) {
+            if (Array.isArray(value))
+                return value;
+        }
+    }
+    return [];
+}
+function extractNextCursor(raw, fields, requestCursor) {
+    const paths = fields.nextCursor ? [fields.nextCursor] : DEFAULT_CURSOR_KEYS;
+    for (const path of paths) {
+        const cursor = asIdOrLabel(getPath(raw, path));
+        // A cursor identical to the one just used means the provider echoed the
+        // request back (Airtable's offset does this on the last page) — following
+        // it would loop forever, so treat it as the end of the list.
+        if (cursor && cursor !== requestCursor)
+            return cursor;
+    }
+    return undefined;
+}
+/**
+ * Normalize one raw resolver-action result into `{ id, label }` options plus
+ * the next-page cursor. Items without a usable id are dropped; a missing label
+ * falls back to the id. When `query` is given, options are filtered by
+ * case-insensitive label substring — the client-side fallback for resolver
+ * actions with no server-side search (it narrows each fetched page, so paging
+ * through "Load more" still walks the full list).
+ */
+export function normalizeResourcePage(raw, fields, opts = {}) {
+    const needle = opts.query?.trim().toLowerCase();
+    const options = [];
+    for (const item of extractItems(raw, fields.items)) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const id = asIdOrLabel(getPath(item, fields.id));
+        if (!id)
+            continue;
+        const label = asIdOrLabel(getPath(item, fields.label)) || id;
+        if (needle && !label.toLowerCase().includes(needle))
+            continue;
+        options.push({ id, label });
+    }
+    return {
+        options,
+        nextCursor: extractNextCursor(raw, fields, opts.requestCursor),
+    };
+}
+const FIND_RESOURCE_MAX_PAGES = 100;
+/**
+ * Walk normalized pages until an option matches. The generic half of "resolve
+ * a name to an id": the caller's `fetchPage` owns transport and provider
+ * quirks (retries, scope fallbacks); this owns the cursor walk, the page
+ * bound, and the echoed-cursor stop.
+ */
+export async function findResource(fetchPage, match, opts = {}) {
+    const maxPages = opts.maxPages ?? FIND_RESOURCE_MAX_PAGES;
+    let cursor;
+    for (let page = 0; page < maxPages; page++) {
+        const result = await fetchPage(cursor);
+        const hit = result.options.find(match);
+        if (hit)
+            return hit;
+        if (!result.nextCursor || result.nextCursor === cursor)
+            return null;
+        cursor = result.nextCursor;
+    }
+    return null;
+}
+/**
+ * Small process-lifetime memo with a TTL and a size cap, for resolver results
+ * that are safe to share across requests. A deployed app serves exactly one
+ * workspace and connections are workspace-scoped, so entries never leak across
+ * tenants; the TTL just keeps freshly created resources from being invisible
+ * for long.
+ */
+export class TtlCache {
+    maxEntries;
+    entries = new Map();
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() >= entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        if (ttlMs <= 0)
+            return;
+        if (!this.entries.has(key) && this.entries.size >= this.maxEntries) {
+            // Evict the oldest insertion — enough LRU-ness for a picker cache.
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+        this.entries.set(key, { value, expiresAt: Date.now() + ttlMs });
+    }
+}

package/dist/server.d.ts

@@ -1,3 +1,10 @@
 import 'server-only';
-/** Version of this package, for provenance checks in the sandbox. */
-export declare const APP_FOUNDATION_VERSION = "0.0.0";
+export * from './assembly.js';
+export * from './auth.js';
+export * from './mint-bearer.js';
+export * from './nango.js';
+export * from './app-storage.js';
+export * from './labels.js';
+export * from './api-errors.js';
+export * from './params.js';
+export * from './client.js';

package/dist/server.js

@@ -2,9 +2,19 @@
 // here; the explicit ./server subpath (rather than the `react-server` export
 // condition) is what makes a client bundle importing them fail at build time
 // instead of silently shipping ASSEMBLY_API_KEY to the browser.
-//
-// Empty for now: this 0.0.0 exists to prove the publish path end to end before
-// any module moves into it. Real helpers arrive with the migration.
 import 'server-only';
-/** Version of this package, for provenance checks in the sandbox. */
-export const APP_FOUNDATION_VERSION = '0.0.0';
+export * from './assembly.js';
+export * from './auth.js';
+export * from './mint-bearer.js';
+export * from './nango.js';
+export * from './app-storage.js';
+export * from './labels.js';
+// Returns NextResponse, so route handlers only — but nothing here reads a
+// secret, which is why a client file may still `import type` from them.
+export * from './api-errors.js';
+export * from './params.js';
+// The client-safe surface is re-exported so a server file needs one import, not
+// two. Importing './client' rather than the package's own ./client subpath keeps
+// this a single module graph — a self-import would resolve through node_modules
+// and duplicate every constant.
+export * from './client.js';

package/dist/session-exchange.d.ts

@@ -0,0 +1,20 @@
+export declare const BEARER_COOKIE_NAME = "x-assembly-bearer";
+export declare const BEARER_TTL_MS: number;
+export type MintFailure = 'rejected' | 'unavailable';
+export declare function classifyExchangeFailure(status: number): MintFailure;
+export declare function serializeBearerCookie(value: string, maxAgeSeconds: number, partitioned: boolean): string;
+export declare const BEARER_HEADER_NAME = "x-assembly-request-bearer";
+export declare const APP_CSRF_HEADER = "x-assembly-app";
+export declare function isSessionExchangeEnabled(): boolean;
+export interface ExchangedSession {
+    workspaceId: string;
+    clientId?: string;
+    internalUserId?: string;
+    companyId?: string;
+    notificationId?: string;
+    instanceId?: string;
+    /** Session token this bearer was exchanged from — lets the proxy tell a
+     *  reload of an already-exchanged token apart from a new open. */
+    sessionId?: string;
+}
+export declare function decodeBearer(bearer: string): ExchangedSession | null;

package/dist/session-exchange.js

@@ -0,0 +1,101 @@
+// Stateless bearer helpers for the token-exchange flow (AI-260).
+// The proxy exchanges the session token once and sets the returned bearer as an
+// HttpOnly cookie. That bearer is a signed JWT carrying the caller's identity as
+// claims, so requireAuth()/getAssemblyForRequest() resolve identity by DECODING
+// the cookie — no server-side cache. A cache can't work here anyway: on Vercel
+// the middleware that would populate it and the route handlers that read it run
+// in separate runtimes/instances and never share memory.
+//
+// decodeBearer does NOT verify the signature. The platform-api authorizer
+// re-validates the token's signature and scope on every real API call, which is
+// the security boundary; these decoded claims are advisory to the app (SDK init,
+// early authz rejects) and never the sole gate.
+export const BEARER_COOKIE_NAME = 'x-assembly-bearer';
+export const BEARER_TTL_MS = 60 * 60 * 1_000; // 60 minutes, matches bearer TTL
+// The only statuses that prove the session token ITSELF is spent or invalid:
+// 404 (unknown, or already consumed), 401 (expired, or minted for another app)
+// and 400 (malformed, or no user on the session).
+const TOKEN_REFUSED_STATUSES = new Set([400, 401, 404]);
+// Classifies a non-2xx /v1/session response. Anything outside the allowlist says
+// nothing about the token and usually leaves it unspent — a 403 is our own API
+// key failing, a 429 is the platform throttle firing before the handler, a 5xx is
+// platform-api unable to complete (its errTokenIssueFailed path deliberately
+// keeps the token intact for a retry). Defaulting those to 'unavailable' means an
+// unrecognised status is never mistaken for a replay.
+export function classifyExchangeFailure(status) {
+    return TOKEN_REFUSED_STATUSES.has(status) ? 'rejected' : 'unavailable';
+}
+// Serialize a `Set-Cookie` header value for the bearer cookie. Callers append
+// these as raw headers (response.headers.append) rather than response.cookies
+// .set(): the partitioned and unpartitioned records share the cookie name, and
+// ResponseCookies keys its store by name, so a second set() replaces the first
+// and collapses to a single header. During the CHIPS rollout we must emit BOTH
+// the partitioned record and a clear for the legacy unpartitioned one, so we
+// serialize the headers ourselves. `''` value + maxAgeSeconds 0 clears a record.
+export function serializeBearerCookie(value, maxAgeSeconds, partitioned) {
+    let cookie = `${BEARER_COOKIE_NAME}=${encodeURIComponent(value)}; Path=/; HttpOnly; Secure; SameSite=None; Max-Age=${maxAgeSeconds}`;
+    if (partitioned)
+        cookie += '; Partitioned';
+    return cookie;
+}
+// Internal request header the proxy uses to hand the freshly-minted bearer to
+// the first-load render, when the Set-Cookie it issues isn't yet visible to the
+// same request. The proxy strips any inbound value before setting it, so it
+// cannot be spoofed. Every later request carries the HttpOnly cookie instead.
+export const BEARER_HEADER_NAME = 'x-assembly-request-bearer';
+// Custom header for CSRF mitigation on state-changing requests. Its mere
+// presence is sufficient: a cross-site request physically cannot carry a
+// custom header without a CORS preflight, and this app grants none.
+export const APP_CSRF_HEADER = 'x-assembly-app';
+// Master switch for the AI-260 server-side token exchange (bearer cookie flow).
+// Defaults OFF so the exchange stays dormant in every foundation snapshot:
+// merging this code — or any coworker rebuilding the snapshot for unrelated
+// reasons — ships inert plumbing, never a behavior change. While off, proxy.ts
+// and requireAuth() behave exactly as the pre-AI-260 legacy path (direct token
+// decrypt per request). To turn it on: set the env var in the generated-app
+// build environment and rebuild the snapshot — one deliberate, reviewed switch.
+export function isSessionExchangeEnabled() {
+    return process.env.ENABLE_APP_SESSION_TOKEN_EXCHANGE === 'true';
+}
+// Decodes a base64url JWT segment to a UTF-8 string using only Web APIs (atob,
+// TextDecoder), so decodeBearer runs in BOTH the Edge middleware runtime (proxy)
+// and the Node route-handler runtime (requireAuth / getAssemblyForRequest) —
+// Buffer is unavailable on Edge.
+function decodeBase64UrlJson(segment) {
+    const b64 = segment.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+// Decodes the identity claims from a bearer JWT. Signature is NOT verified here
+// (the platform-api authorizer re-validates it on every real call — the true
+// boundary); these claims are advisory for SDK init and early authz. Returns
+// null when the token is malformed, expired, or carries no workspace — callers
+// then return 401 / re-exchange.
+export function decodeBearer(bearer) {
+    const parts = bearer.split('.');
+    if (parts.length !== 3)
+        return null;
+    let claims;
+    try {
+        claims = decodeBase64UrlJson(parts[1]);
+    }
+    catch {
+        return null;
+    }
+    if (typeof claims.exp === 'number' && claims.exp * 1_000 <= Date.now()) {
+        return null;
+    }
+    if (!claims.workspace_id)
+        return null;
+    return {
+        workspaceId: claims.workspace_id,
+        clientId: claims.client_id || undefined,
+        internalUserId: claims.internal_user_id || undefined,
+        companyId: claims.company_id || undefined,
+        notificationId: claims.notification_id || undefined,
+        instanceId: claims.instance_id || undefined,
+        sessionId: claims.session_id || undefined,
+    };
+}

package/dist/theme.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveFont(fontValue: string | null): {
+    fontFamily: string;
+    fontCssUrl: string | null;
+};
+export declare function isValidHexColor(color: string): boolean;

package/dist/theme.js

@@ -0,0 +1,20 @@
+const CDN_BASE_URL = 'https://cdn.assembly.com';
+const DEFAULT_FONT_VALUE = 'Inter';
+// Custom (non-Google) fonts hosted on CDN. Everything else is treated as a Google Font.
+const CUSTOM_FONTS = {
+    Satoshi: { cssPath: '/fonts/satoshi/satoshi.css' },
+};
+const SAFE_FONT_NAME = /^[A-Za-z0-9 +\-]+$/;
+export function resolveFont(fontValue) {
+    if (!fontValue || !SAFE_FONT_NAME.test(fontValue))
+        return { fontFamily: DEFAULT_FONT_VALUE, fontCssUrl: null };
+    const fontFamily = fontValue.replace(/\+/g, ' ');
+    const customFont = CUSTOM_FONTS[fontValue];
+    if (customFont) {
+        return { fontFamily, fontCssUrl: CDN_BASE_URL + customFont.cssPath };
+    }
+    return { fontFamily, fontCssUrl: 'https://fonts.googleapis.com/css2?family=' + fontValue + ':wght@300;400;500;600;700;800;900&display=swap' };
+}
+export function isValidHexColor(color) {
+    return /^#[0-9a-fA-F]{3,8}$/.test(color);
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.0",
+  "version": "0.0.1-rc.2",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "CLAUDE.md"
   ],
   "exports": {
     "./server": {
@@ -19,14 +20,20 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "echo \"no tests yet\" && exit 0",
-    "prepublishOnly": "npm run build"
+    "test": "bun test",
+    "prepublishOnly": "npm run build && npm run verify:dist",
+    "verify:dist": "node scripts/verify-dist-resolves.mjs"
   },
   "peerDependencies": {
+    "@assembly-js/node-sdk": ">=4.2.3-beta.2",
+    "next": ">=15",
     "server-only": "*"
   },
   "devDependencies": {
+    "@assembly-js/node-sdk": "4.2.3-beta.2",
+    "@types/bun": "^1.1.0",
     "@types/node": "^22",
+    "next": "^15.5.0",
     "server-only": "^0.0.1",
     "typescript": "^5.3.3"
   },

package/skills/assembly-ai/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: assembly-ai
+description: Use when the app needs AI features like text generation, summarization, analysis, or any LLM capability. Apps call Assembly's AI proxy — no API keys or external SDKs needed.
+---
+
+## How it works
+
+Assembly provides an AI proxy that forwards requests to OpenAI. Your app calls the Assembly API using `assembly.fetch()` from the SDK — auth headers and base URL are handled automatically. No extra API keys, no extra env vars, no OpenAI SDK.
+
+The proxy mirrors OpenAI's API shape. Call any OpenAI endpoint path via:
+`assembly.fetch('/v1/ai/openai/chat/completions', { ... })`
+`assembly.fetch('/v1/ai/openai/embeddings', { ... })`
+
+## Setup
+
+Create a helper in `lib/ai.ts` that uses the existing Assembly SDK instance:
+
+```typescript
+import { getAssembly } from './assembly';
+
+export async function chatCompletion(messages: Array<{ role: string; content: string }>, options?: { model?: string; stream?: boolean }) {
+  const assembly = await getAssembly();
+  const response = await assembly.fetch('/v1/ai/openai/chat/completions', {
+    method: 'POST',
+    body: JSON.stringify({
+      model: options?.model || 'gpt-4o-mini',
+      messages,
+      stream: options?.stream || false,
+    }),
+  });
+  if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
+  return response;
+}
+```
+
+`assembly.fetch()` automatically prepends the base URL and injects auth headers (`Authorization: Bearer` from `getAssembly()`, plus `X-Assembly-SDK-Version`). It never sends `X-API-Key` on data calls. You only provide the path and request body.
+
+## Server-side only
+
+ALL AI calls MUST happen server-side (API routes, server components, server actions). Never call the AI proxy from client components.
+
+Example Next.js API route:
+
+```typescript
+// app/api/ai/summarize/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { chatCompletion } from '@/lib/ai';
+
+export async function POST(request: NextRequest) {
+  const { text } = await request.json();
+  const response = await chatCompletion([
+    { role: 'user', content: `Summarize the following:\n\n${text}` },
+  ]);
+  const data = await response.json();
+  return NextResponse.json({ summary: data.choices[0].message.content });
+}
+```
+
+## Vision (image inputs)
+
+The proxy supports OpenAI's vision API. Use `gpt-4o` with the multi-part content format to analyze images. The `content` field becomes an array of typed parts instead of a plain string:
+
+```typescript
+export async function analyzeImage(base64DataUrl: string, prompt: string) {
+  const assembly = await getAssembly();
+  const response = await assembly.fetch('/v1/ai/openai/chat/completions', {
+    method: 'POST',
+    body: JSON.stringify({
+      model: 'gpt-4o',
+      messages: [{
+        role: 'user',
+        content: [
+          { type: 'text', text: prompt },
+          { type: 'image_url', image_url: { url: base64DataUrl } },
+        ],
+      }],
+      stream: false,
+    }),
+  });
+  if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
+  return response;
+}
+```
+
+The `base64DataUrl` must be a full data URL: `data:image/png;base64,iVBOR...`. Convert uploaded files on the client before sending to the API route:
+
+```typescript
+const toDataUrl = (file: File): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string);
+    reader.onerror = reject;
+    reader.readAsDataURL(file);
+  });
+```
+
+Keep images under ~4 MB to stay within the 6 MB Lambda payload limit (base64 adds ~33% overhead). For larger images, resize on the client before converting.
+
+## Model selection
+
+- Default to `gpt-4o-mini` for most tasks (fast, cheap, good enough)
+- Use `gpt-4o` for vision (image inputs) or when the task requires complex reasoning
+- For embeddings, use `text-embedding-3-small`
+
+## Streaming
+
+For chat or long-form generation, pass `stream: true` and forward the SSE stream:
+
+```typescript
+export async function POST(request: NextRequest) {
+  const { messages } = await request.json();
+  const response = await chatCompletion(messages, { stream: true });
+  return new Response(response.body, {
+    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
+  });
+}
+```
+
+The proxy forwards OpenAI's SSE stream directly. Parse `data:` lines on the client as usual.
+
+`assembly.fetch()` returns a standard `Response`, so `response.body` is a `ReadableStream` you can pipe directly.
+
+## Quota
+
+Usage is metered against the workspace's monthly AI quota. Do not implement your own rate limiting — Assembly handles this automatically. If the quota is exceeded, the proxy returns HTTP 429.
+
+## What NOT to do
+
+- Do NOT install the `openai` npm package — use `assembly.fetch()` via the Assembly proxy
+- Do NOT set or reference `OPENAI_API_KEY` or `OPENAI_BASE_URL` — these do not exist
+- Do NOT call `api.openai.com` directly — always go through the Assembly proxy
+- Do NOT call the AI proxy from client-side code
+- Do NOT implement your own API key management or manually set auth headers — `assembly.fetch()` handles this

package/skills/assembly-app-bridge-header/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: assembly-app-bridge-header
+description: Use any time the app sets breadcrumbs, primary CTA, secondary CTA, or actions menu in the Assembly header chrome. Always drive the header through the useAssemblyHeader hook — never call AssemblyBridge.header.set* from your own useEffect. Critical: the parent automatically prepends the app's name as breadcrumb 0 — never include it yourself, or it renders twice.
+---
+
+The Assembly header (breadcrumbs, primary/secondary CTA buttons, overflow actions menu) is controlled from your app. **Drive it with the `useAssemblyHeader` hook** — it ships in the foundation at `app/components/use-assembly-header.ts`.
+
+## The one rule: use the hook, not raw `set*`
+
+```tsx
+'use client';
+import { useAssemblyHeader } from '@/app/components/use-assembly-header';
+
+export default function ReportPage() {
+  useAssemblyHeader({
+    onRootClick: () => router.push('/'),
+    breadcrumbs: [{ label: 'Reports' }, { label: 'Q4 2026' }],
+    primaryCta: { label: 'New report', icon: 'Plus', onClick: () => setCreating(true) },
+    secondaryCta: { label: 'Export', icon: 'Archive', onClick: exportData },
+    actionsMenu: [
+      { label: 'Settings', onClick: openSettings },
+      { label: 'Delete', icon: 'Trash', color: 'red', onClick: remove },
+    ],
+  });
+  // ...
+}
+```
+
+Call it **once per page** with exactly the chrome that page needs. The hook owns the whole header surface for that page: anything you omit is cleared, and everything is torn down automatically on unmount. Pass freshly-built objects/handlers every render — that's fine, the hook keys re-renders on the visible *values* (labels/icons), not on handler identity, and reads the latest `onClick` from a ref. To hide a slot, omit it (or pass `primaryCta: null`).
+
+### ❌ Never hand-roll the effect
+
+```tsx
+// ❌ WRONG — do not call these from your own useEffect.
+useEffect(() => {
+  AssemblyBridge.header.setPrimaryCta({ label: 'Save', onClick: save });
+  return () => AssemblyBridge.header.setPrimaryCta(null);
+}, [...]);
+```
+
+Hand-rolling the imperative API is the cause of the "the button disappears after I start typing" class of bug: splitting set + teardown across two effects, or listing an unstable dependency (e.g. an inline closure or object created fresh every render) makes one effect's cleanup `null` a CTA that another effect owns, and the button never comes back after the first re-render. `useAssemblyHeader` exists precisely so you never write this. Use it.
+
+### ❌ Never let two mounted components call the hook at once
+
+```tsx
+// ❌ WRONG — AppShell scaffolds a stub CTA for a tab...
+function AppShell() {
+  useAssemblyHeader({ primaryCta: { label: 'New service', onClick: () => {} } });
+  return <CatalogTab />;
+}
+// ...and CatalogTab, built later, owns the REAL one. Two live owners.
+function CatalogTab() {
+  useAssemblyHeader({ primaryCta: { label: 'New service', onClick: openDialog } });
+}
+```
+
+The classic way this happens: a parent shell stubs a placeholder CTA during scaffolding, a child component later takes real ownership, and the stub never gets deleted. **The moment a child calls `useAssemblyHeader`, delete the parent's stub.** This race is invisible in local dev — Strict Mode's double-invoked effects happen to leave the child as last writer — and only misbehaves in the published app. The hook now enforces it at runtime: a second simultaneous caller **throws in dev** and is ignored (with a `console.error`) in production. If your preview crashes with "a second mounted component tried to drive the header," find and delete the leftover stub.
+
+## Breadcrumbs: never include the app name
+
+The parent **automatically prepends the app's name as breadcrumb 0**. Whatever you pass is appended *after* index 0. If your app needs to control what happens when the user clicks that root crumb, pass `onRootClick` to `useAssemblyHeader`.
+
+```tsx
+// ❌ WRONG — renders as "MyApp / MyApp / Reports"
+useAssemblyHeader({ breadcrumbs: [{ label: 'MyApp', onClick: goHome }, { label: 'Reports' }] });
+
+// ✅ RIGHT — renders as "MyApp / Reports"
+useAssemblyHeader({ onRootClick: goHome, breadcrumbs: [{ label: 'Reports' }] });
+```
+
+Use breadcrumbs only for hierarchical navigation, not branding. A flat one-page app omits `breadcrumbs` (or passes `[]`). A multi-level app uses one entry per level: `[{ label: 'Reports' }, { label: 'Q4 2026' }]`. A breadcrumb's `onClick` makes it clickable; omit it for the current/leaf level.
+
+## Icon and color constraints
+
+- **`icon` must be a `CtaIcon`** — the only valid values are `'Archive' | 'Plus' | 'Templates' | 'Trash' | 'Check'`. Any other string (e.g. `'Download'`, `'Settings'`, `'Edit'`) is a type error — omit the icon (it's optional) when none fit.
+- **`color`** (actions-menu items only) is optional; the only explicit value is `'red'` (for destructive actions). Omit it for the default color.
+
+`AssemblyBridge` postMessages to the parent, so everything here must live in a `'use client'` component.
+
+## Exception: the notification surface (`/n`)
+
+The Notification Center embeds the notification surface in a plain `<iframe>` **without app bridge header support**. `useAssemblyHeader` calls are silently ignored — `primaryCta`, `secondaryCta`, `actionsMenu`, and `breadcrumbs` never render. The user sees an empty header.
+
+**On the notification surface, render primary actions as inline `<Button>` elements in the page body.** This is the ONE exception to the "always use the hook" rule. Detect the notification surface by the route itself — code under `app/n/` IS the surface. For a component shared with another surface, pass an explicit prop (see below) from the `/n` page rather than inferring from `payload.notificationId`: that claim is best-effort under the session-exchange flow, so a component keying off it can silently fall back to header CTAs that never render inside the Notification Center iframe.
+
+**This exception applies ONLY to the `/n` route.** All other surfaces (dashboard, client portal, CRM tab) MUST continue using `useAssemblyHeader`.
+
+**Common mistake: reusing a component that calls `useAssemblyHeader` on `/n`.** If you share a form or action view between the notification surface and another surface, and the component calls `useAssemblyHeader` while also rendering an inline `<Button>`, both the header CTA and the inline button appear on non-notification surfaces — a duplicate. Fix by either creating a dedicated component for `/n` that uses only inline buttons, or by accepting a prop (e.g. `useInlineActions`) that switches between the header hook and inline buttons.