@assembly-js/app-foundation 0.0.25-rc.2 → 0.0.25-rc.4

package/CLAUDE.md

@@ -120,7 +120,12 @@ The app should **detect the viewer type from the token** and render audience-app
 
 **The CRM tab is never the only path to per-client data.** The CRM tab is a shortcut: it renders with a specific `clientId`/`companyId` already in the token. But any client/company-specific data or action it exposes must *also* be reachable from the Dashboard main view — even if it takes a few clicks. Build the main view so an internal user can browse to a specific client/company (a list, or a `UserCompanySelector` that drills into a per-entity detail screen) and reach the same data and actions there. The main-view detail screen doesn't have to match the CRM-tab layout — it can reuse the same components or present them differently — but the main view must never be empty or aggregate-only when the CRM tab has per-client functionality. Don't leave `internalUrl` as a dead end.
 
+<!-- !feature:app-owned-header -->
 **More generally: every page you create needs a click path.** Next.js builds and typechecks a page nothing links to, so an orphaned route ships silently. Before a page is done, something on an already-reachable page must point at it — a `<Link>`, `router.push`, redirect, header CTA, or actions-menu item. `bun run build` enforces this (`bun run check:route-reachability` runs it alone). When a primary flow depends on managing another resource first (cases need stages, documents need templates), ship that manager's entry point together with the dependent flow — an actions-menu item on the main view plus a link on the empty state that blocks on it.
+<!-- /feature:app-owned-header -->
+<!-- feature:app-owned-header -->
+**More generally: every page you create needs a click path.** Next.js builds and typechecks a page nothing links to, so an orphaned route ships silently. Before a page is done, something on an already-reachable page must point at it — a `<Link>`, `router.push`, redirect, or actions-menu item. `bun run build` enforces this (`bun run check:route-reachability` runs it alone). When a primary flow depends on managing another resource first (cases need stages, documents need templates), ship that manager's entry point together with the dependent flow — an actions-menu item on the main view plus a link on the empty state that blocks on it.
+<!-- /feature:app-owned-header -->
 
 ### Per-client app visibility — platform setting, not the app's job
 
@@ -186,8 +191,24 @@ Because the app runs in an iframe inside the parent dashboard, several normal Ne
 - **No `window.open(..., '_self')`.** Same issue.
 - **The portal owns the chrome (header, sidebar).** Don't render your own breadcrumbs or page titles via DOM. Use `@assembly-js/app-bridge` to set them.
 - **Never put the app name in breadcrumbs.** The parent portal *automatically* prepends the app's name as breadcrumb 0. If you also pass `{ label: 'MyApp' }` as the first entry of `setBreadcrumbs`, it renders twice ("MyApp / MyApp / Reports"). For a flat one-page app pass `[]` (or skip `setBreadcrumbs` entirely). For a multi-level app pass only the sub-pages: `setBreadcrumbs([{ label: 'Reports' }, { label: 'Q4 2026' }])`. Read `.claude/skills/assembly-app-bridge-header/SKILL.md` for full examples.
+<!-- !feature:app-owned-header -->
 - **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.
+<!-- /feature:app-owned-header -->
+<!-- feature:app-owned-header -->
+
+### Your rendering surface
+
+The app renders inside the Assembly dashboard iframe — global nav to the left, the app as the main area in the right column owning its full height, including the top. **There is no host header above the app; nothing prepends the app name.**
+
+**The app owns its header.** Decide whether to have one at all and what goes in it: title, navigation, primary and secondary actions. Do not call `useAssemblyHeader` or `AssemblyBridge.header.*` — nothing listens to those calls.
+
+Assembly's own conventions, offered as reference and not as a template: page-level primary CTAs sit at the top right of a page header and sometimes inline within the content; breadcrumbs, when present, sit top-left; the dashboard uses a 60 px header row with a bottom border when it has one.
+
+**When deciding the header, title, navigation, and primary actions, prefer in this order:** (1) the user's stated preferences, (2) a light adherence to Assembly's conventions where they make sense for this app, (3) your own judgment for the app.
+
+**The `/n` notification surface is unchanged.** Render primary actions as inline `<Button>` elements in the page body — the Notification Center has no header regardless of this flag.
+<!-- /feature:app-owned-header -->
 - **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.
 - **`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
@@ -369,7 +390,12 @@ If `tsc --noEmit` is clean and the task says "verify the build", run `bun run bu
 
 `bun run build` also **fails** if any page reads `searchParams.token`. Auth is in the bearer cookie, not the URL — no page (not even a surface entry page) needs it; `getAssembly()` / `getSessionIdentity()` read the bearer. Fix as the error instructs — fetch that page's data via `useServerAction`/`authFetch` instead. Run `bun run check:token-usage` to check it on its own.
 
+<!-- !feature:app-owned-header -->
 `bun run build` also **fails** if a page route is unreachable — no link, `router.push`, redirect, or header CTA anywhere else points at it. Fix as the error instructs by adding an entry point on a reachable page. Run `bun run check:route-reachability` to check it on its own.
+<!-- /feature:app-owned-header -->
+<!-- feature:app-owned-header -->
+`bun run build` also **fails** if a page route is unreachable — no link, `router.push`, redirect, or other entry point elsewhere points at it. Fix as the error instructs by adding an entry point on a reachable page. Run `bun run check:route-reachability` to check it on its own.
+<!-- /feature:app-owned-header -->
 
 ---
 
@@ -1081,10 +1107,12 @@ Pass `limit: 100` (the max) so the walk makes 5x fewer round trips than the ~20
 ## Client-side SDK: `@assembly-js/app-bridge`
 
 For controlling the portal chrome from your iframe. Use **only in client components** (`'use client'`).
+<!-- !feature:app-owned-header -->
 
 ### Header chrome
 
 Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.claude/skills/assembly-app-bridge-header/SKILL.md` for the full API and code examples. `AssemblyBridge` is a singleton — no init required. Use only in `'use client'` components.
+<!-- /feature:app-owned-header -->
 
 ### Session token — the foundation uses this, not you
 
@@ -1102,9 +1130,11 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't reinvent built-in Assembly features (Messages, Files, Forms, Tasks, Billing) — call the SDK methods listed above.
 - ❌ Don't use `assembly.clients.list()` — the SDK is flat. Use `assembly.listClients(...)`.
 - ❌ Don't cache decoded payloads for >30s — token rotates every 5 min and the user could be different on the next call (rare, but possible if a session is shared across tabs).
+<!-- !feature:app-owned-header -->
 - ❌ Don't render your own breadcrumbs / titles in the DOM — use `AssemblyBridge.header.*`.
 - ❌ Don't render primary page-level actions (Submit, Save, Edit, Create) as `<Button>` elements inside the page body. These MUST go in the header via the `useAssemblyHeader` hook's `primaryCta`. Contextual inline actions (e.g. row-level edit icons, list "Add item" buttons) may stay in-page. In-page primary CTAs make the UX inconsistent with the rest of the portal. **Exception: the notification surface (`/n`).** The Notification Center renders `/n` in a headerless iframe — `useAssemblyHeader` is ignored. On this surface, primary actions MUST be inline `<Button>` elements.
 - ❌ Don't call `AssemblyBridge.header.set*` from your own `useEffect`. Always go through `useAssemblyHeader` — hand-rolling the imperative API (split set/teardown effects, or an unstable dep like an inline closure created fresh each render) nulls a CTA another effect owns, and the button disappears after the first re-render.
+<!-- /feature:app-owned-header -->
 - ❌ Don't let two mounted components call `useAssemblyHeader` at once — e.g. a parent shell's scaffolding-era stub CTA left in place after a child took real ownership. Strict Mode hides the race in dev; the hook throws in dev and ignores the second caller in production. Delete the parent's stub the moment a child owns the slot.
 - ❌ Don't `window.open(url, '_self')` or set `window.location` for external links — use `<a target="_blank" rel="noreferrer">`.
 - ❌ Don't hardcode brand colors. The portal applies the workspace theme.
@@ -1150,6 +1180,8 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 3. **Call `getAssembly()` — no token argument, ever.** `getAssembly()` (RSC/server actions) and `getAssemblyForRequest(req)` (route handlers) read the bearer cookie. Identity via `getSessionIdentity()` / `useAssembly()`. Never read `searchParams.token`, thread a token, or set `x-assembly-token`.
 4. **The SDK is flat: `assembly.listClients(...)`, not `assembly.clients.list()`.** `dist/codegen/api/index.d.ts` lists every service; `services/<Resource>Service.d.ts` has the parameter shapes.
 5. **The bearer expires in 60 min; `useServerAction`/`authFetch` re-exchange it silently and retry.** You don't refresh anything or touch `AssemblyBridge.sessionToken`.
+<!-- !feature:app-owned-header -->
 6. **Use `AssemblyBridge.header.*`** for breadcrumbs/CTAs in client components. Don't render your own. (Exception: the notification surface `/n` has no header — render CTAs as inline buttons there.)
+<!-- /feature:app-owned-header -->
 7. **Don't reinvent Messages/Files/Forms/Tasks/Billing.** Wire them up via SDK.
 8. **Keep infrastructure plumbing out of chat.** Don't volunteer ASSEMBLY_ENV, COPILOT_ENV, token encryption, API key internals, or internal file names unprompted. Mid-build SDK auth warnings are expected — never surface them to the user. (Answering a user's direct technical question is fine.)

package/dist/client.d.ts

@@ -2,6 +2,7 @@ export * from './session-exchange.js';
 export * from './network-capture.js';
 export * from './paint-beacon.js';
 export * from './origin-bootstrap.js';
+export * from './cookieless-bearer.js';
 export * from './client-companies.js';
 export * from './pagination.js';
 export * from './theme.js';

package/dist/client.js

@@ -12,6 +12,8 @@ export * from './paint-beacon.js';
 // origin with the bridge allowlist, and schedule the post-paint beacon. See
 // each module's comment.
 export * from './origin-bootstrap.js';
+// In-memory bearer for browsers that refuse the cookie; inert everywhere else.
+export * from './cookieless-bearer.js';
 export * from './client-companies.js';
 export * from './pagination.js';
 export * from './theme.js';

package/dist/cookieless-bearer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether the browser is refusing to store the bearer cookie. Either the probe
+ * or the portal-origin cookie being readable proves the jar works — proxies that
+ * predate the probe write only the latter. A false "blocked" costs at most one
+ * mint, since a working cookie keeps authenticating regardless. Off-browser it
+ * returns false: no cookie jar is not the same as a blocked one.
+ */
+export declare function cookiesAreBlocked(cookieString?: string): boolean;
+/** The in-memory bearer, or null when the cookie path is carrying auth. */
+export declare function getCookielessBearer(): string | null;
+/**
+ * Adopt a freshly minted bearer for the cookie-less path and make sure the
+ * fetch patch is live. Called after a re-exchange returns one in its body.
+ */
+export declare function setCookielessBearer(value: string | null): void;
+/**
+ * Headers that ask the re-exchange route to return the bearer in its body.
+ * Shared with the renewal path in lib-client so both describe the cookie-less
+ * request the same way.
+ */
+export declare function cookielessReexchangeHeaders(): Record<string, string>;

package/dist/cookieless-bearer.js

@@ -0,0 +1,93 @@
+'use client';
+// Carries the bearer for browsers that refuse to store it: Safari blocks every
+// cross-site-iframe cookie and has no CHIPS, so the cookie is dropped on write
+// and only the first paint (which gets the bearer as a request header) works.
+//
+// window.fetch is the patch point because Next routes RSC navigations, server
+// actions and app fetches through it alike, and server actions cannot carry a
+// custom header any other way. The bearer stays in memory so it cannot outlive
+// the document or leak into history.
+import { APP_CSRF_HEADER, BEARER_IN_BODY_HEADER, CLIENT_BEARER_HEADER, COOKIE_PROBE_NAME, } from './session-exchange.js';
+import { PORTAL_ORIGIN_COOKIE_NAME, readCookie } from './origin-bootstrap.js';
+let bearer = null;
+let patched = false;
+/**
+ * Whether the browser is refusing to store the bearer cookie. Either the probe
+ * or the portal-origin cookie being readable proves the jar works — proxies that
+ * predate the probe write only the latter. A false "blocked" costs at most one
+ * mint, since a working cookie keeps authenticating regardless. Off-browser it
+ * returns false: no cookie jar is not the same as a blocked one.
+ */
+export function cookiesAreBlocked(cookieString) {
+    if (cookieString === undefined && typeof document === 'undefined') {
+        return false;
+    }
+    return (readCookie(COOKIE_PROBE_NAME, cookieString) === null &&
+        readCookie(PORTAL_ORIGIN_COOKIE_NAME, cookieString) === null);
+}
+/** The in-memory bearer, or null when the cookie path is carrying auth. */
+export function getCookielessBearer() {
+    return bearer;
+}
+/**
+ * Adopt a freshly minted bearer for the cookie-less path and make sure the
+ * fetch patch is live. Called after a re-exchange returns one in its body.
+ */
+export function setCookielessBearer(value) {
+    bearer = value || null;
+    if (bearer)
+        patchFetch();
+}
+// Same-origin only: the bearer must never ride a request to a third party the
+// app happens to call. A relative URL resolves against the document, so it is
+// same-origin by construction.
+function isSameOrigin(input) {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        const raw = typeof input === 'string'
+            ? input
+            : input instanceof URL
+                ? input.href
+                : input.url;
+        return new URL(raw, window.location.href).origin === window.location.origin;
+    }
+    catch {
+        return false;
+    }
+}
+// Patched once, and only after the cookie has been proven unavailable. A
+// Request argument carries immutable headers, so it is rebuilt rather than
+// mutated. The CSRF header rides along because a patched request may be a
+// server action, which cannot set it itself.
+function patchFetch() {
+    if (patched || typeof window === 'undefined')
+        return;
+    patched = true;
+    const originalFetch = window.fetch.bind(window);
+    window.fetch = function assemblyCookielessFetch(input, init) {
+        if (!bearer || !isSameOrigin(input)) {
+            return originalFetch(input, init);
+        }
+        if (input instanceof Request && !init) {
+            const headers = new Headers(input.headers);
+            headers.set(CLIENT_BEARER_HEADER, bearer);
+            headers.set(APP_CSRF_HEADER, '1');
+            return originalFetch(new Request(input, { headers }));
+        }
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        headers.set(CLIENT_BEARER_HEADER, bearer);
+        headers.set(APP_CSRF_HEADER, '1');
+        return originalFetch(input, { ...init, headers });
+    };
+}
+/**
+ * Headers that ask the re-exchange route to return the bearer in its body.
+ * Shared with the renewal path in lib-client so both describe the cookie-less
+ * request the same way.
+ */
+export function cookielessReexchangeHeaders() {
+    return bearer
+        ? { [CLIENT_BEARER_HEADER]: bearer, [BEARER_IN_BODY_HEADER]: '1' }
+        : { [BEARER_IN_BODY_HEADER]: '1' };
+}

package/dist/lib-client.d.ts

@@ -1,2 +1,10 @@
 export declare function reexchangeBearer(): Promise<boolean>;
 export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+/**
+ * Mint an in-memory bearer at load when the browser is refusing to store the
+ * cookie, so the first client-side navigation is already authenticated instead
+ * of 404ing its way into a renewal. A no-op wherever the cookie works.
+ *
+ * Exported for tests; runs once at module load in the browser.
+ */
+export declare function bootstrapCookielessBearer(): Promise<boolean>;

package/dist/lib-client.js

@@ -6,6 +6,7 @@
 // (proxy.ts pulls constants from that barrel).
 import { AssemblyBridge } from '@assembly-js/app-bridge';
 import { APP_CSRF_HEADER, logRenewOutcome, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
+import { cookielessReexchangeHeaders, cookiesAreBlocked, getCookielessBearer, setCookielessBearer, } from './cookieless-bearer.js';
 const REEXCHANGE_PATH = '/api/assembly-reexchange';
 // Single-flight gate for renewals. Session tokens are single-use for exchange:
 // when the 60-minute bearer expires, every in-flight fetch on the page 401s at
@@ -18,8 +19,8 @@ let renewalInFlight = null;
 // for the freshest session token (the parent keeps it alive) and posts it to the
 // re-exchange route, which mints a new bearer and sets the HttpOnly cookie — no
 // page reload. Returns true iff a fresh bearer was set. This is the only place
-// app code touches the raw session token, and only to re-mint; it is never sent
-// to the platform API.
+// app code touches the raw session token, to re-mint and keep the URL aligned
+// with the cookie; it is never sent to the platform API.
 export function reexchangeBearer() {
     if (renewalInFlight)
         return renewalInFlight;
@@ -30,6 +31,13 @@ export function reexchangeBearer() {
     return renewal;
 }
 async function renewBearer() {
+    const previousUrlToken = typeof window === 'undefined'
+        ? null
+        : new URL(window.location.href).searchParams.get('token');
+    // Re-read per attempt rather than caching: the first call on a cookie-less
+    // browser is the bootstrap (no bearer yet), and the probe is the only thing
+    // that distinguishes it from a browser whose cookie simply expired.
+    const cookieless = cookiesAreBlocked();
     let token = AssemblyBridge.sessionToken.getCurrent()?.token ?? '';
     // Proactively refresh: we're recovering from an expiry, so avoid re-minting
     // from a session token that may itself be stale.
@@ -43,22 +51,50 @@ async function renewBearer() {
         bridgeRefreshFailed = true;
     }
     if (!token) {
-        logRenewOutcome('no_token', { bridgeRefreshFailed });
+        logRenewOutcome('no_token', { bridgeRefreshFailed, cookieless });
         return false;
     }
     try {
         const res = await fetch(REEXCHANGE_PATH, {
             method: 'POST',
-            headers: { 'x-assembly-token': token, [APP_CSRF_HEADER]: '1' },
+            headers: {
+                'x-assembly-token': token,
+                [APP_CSRF_HEADER]: '1',
+                ...(cookieless ? cookielessReexchangeHeaders() : {}),
+            },
         });
         logRenewOutcome(res.ok ? 'renewed' : 'rejected', {
             bridgeRefreshFailed,
             status: res.status,
+            cookieless,
         });
+        // On the cookie-less path the fresh bearer comes back in the body, because
+        // the Set-Cookie beside it is dropped exactly like the first one was. A body
+        // without one is a route that predates this path answering the ordinary way:
+        // the cookie was renewed if this browser keeps cookies, so the route's own
+        // verdict stands rather than failing a renewal that succeeded.
+        if (res.ok && cookieless) {
+            const body = await res.json().catch(() => null);
+            if (body?.bearer)
+                setCookielessBearer(body.bearer);
+        }
+        if (res.ok && previousUrlToken !== null) {
+            try {
+                const url = new URL(window.location.href);
+                // Don't overwrite a new preview session opened while renewal was in flight.
+                if (url.searchParams.get('token') === previousUrlToken) {
+                    url.searchParams.set('token', token);
+                    window.history.replaceState(window.history.state, '', url.href);
+                }
+            }
+            catch {
+                // A history update failure must not invalidate the cookie just renewed.
+            }
+        }
         return res.ok;
     }
     catch {
-        logRenewOutcome('unavailable', { bridgeRefreshFailed });
+        logRenewOutcome('unavailable', { bridgeRefreshFailed, cookieless });
         return false;
     }
 }
@@ -90,3 +126,21 @@ export async function authFetch(input, init) {
     }
     return fetch(input, { ...init, headers });
 }
+/**
+ * Mint an in-memory bearer at load when the browser is refusing to store the
+ * cookie, so the first client-side navigation is already authenticated instead
+ * of 404ing its way into a renewal. A no-op wherever the cookie works.
+ *
+ * Exported for tests; runs once at module load in the browser.
+ */
+export function bootstrapCookielessBearer() {
+    if (typeof window === 'undefined')
+        return Promise.resolve(false);
+    if (!cookiesAreBlocked() || getCookielessBearer()) {
+        return Promise.resolve(false);
+    }
+    return reexchangeBearer();
+}
+// Self-running, mirroring origin-bootstrap: module evaluation precedes
+// hydration, so the bearer is in hand before any component's first fetch.
+void bootstrapCookielessBearer();

package/dist/mint-bearer.js

@@ -55,7 +55,13 @@ export async function mintBearerFromSessionToken(token, options) {
     try {
         const resp = await assembly.fetch('/v1/session', {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers: {
+                'Content-Type': 'application/json',
+                // Let /session validate the token in the body. The SDK's three-part
+                // key makes the authorizer reject expired tokens with a generic 403
+                // before the handler can distinguish a replay from an outage.
+                'X-API-Key': `${payload.workspaceId}/${process.env.ASSEMBLY_API_KEY ?? ''}`,
+            },
             body: JSON.stringify({
                 sessionId: payload.tokenId,
                 ...(options?.cookieSessionId

package/dist/paint-beacon.js

@@ -17,9 +17,22 @@ export const PAINTED_BEACON_PATH = '/__assembly/painted';
 export const PAINTED_BEACON_EVENT = 'assembly.painted';
 let scheduled = false;
 let fired = false;
+// Set by the app's error boundaries while they are the document's content.
+// A paint of the error boundary is not a paint of the app, and the parent
+// treats this beacon as proof the app is up — so it stays quiet and releases
+// the schedule latch, so the boundary can re-install it once the app has
+// rendered in its place.
+const ERROR_DOCUMENT_FLAG = '__assemblyErrorDocument';
+function isErrorDocument() {
+    return window[ERROR_DOCUMENT_FLAG] === true;
+}
 function firePaintBeacon() {
     if (fired)
         return;
+    if (isErrorDocument()) {
+        scheduled = false;
+        return;
+    }
     fired = true;
     if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
         navigator.sendBeacon(PAINTED_BEACON_PATH);

package/dist/session-exchange.d.ts

@@ -5,13 +5,17 @@ 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 const CLIENT_BEARER_HEADER = "x-assembly-client-bearer";
+export declare const BEARER_IN_BODY_HEADER = "x-assembly-bearer-in-body";
+export declare const COOKIE_PROBE_NAME = "assembly-cookie-probe";
+export declare function serializeCookieProbe(partitioned: boolean, clear?: boolean): string;
 export declare const TOKEN_EXPIRED_HEADER = "x-assembly-token-expired";
 export declare const EXCHANGE_REJECTION_HEADER = "x-assembly-exchange-rejection";
 export type ExchangeRejectedViewer = 'same_viewer' | 'different_viewer';
 export declare function parseExchangeRejection(value: string | null): ExchangeRejectedViewer | undefined;
 export declare function isSessionExchangeEnabled(): boolean;
 export declare const COOKIE_OUTCOME_EVENT = "assembly.cookie_outcome";
-export type CookieOutcome = 'served_from_cookie' | 'minted' | `fail_closed:${string}`;
+export type CookieOutcome = 'served_from_cookie' | 'served_from_client_bearer' | 'minted' | `fail_closed:${string}`;
 export declare function logCookieOutcome(outcome: CookieOutcome, detail?: {
     rejectedToken?: string;
 }): void;
@@ -20,6 +24,7 @@ export type RenewOutcome = 'renewed' | 'no_token' | 'rejected' | 'unavailable';
 export declare function logRenewOutcome(outcome: RenewOutcome, detail?: {
     bridgeRefreshFailed?: boolean;
     status?: number;
+    cookieless?: boolean;
 }): void;
 export declare function isDocumentRequest(request: {
     method: string;

package/dist/session-exchange.js

@@ -47,6 +47,38 @@ export const BEARER_HEADER_NAME = 'x-assembly-request-bearer';
 // 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';
+// Bearer carried by the client instead of the cookie, for browsers that refuse
+// to store it: Safari blocks every cross-site-iframe cookie and does not
+// implement CHIPS, so nothing the proxy sets is ever sent back. Distinct from
+// BEARER_HEADER_NAME so an inbound value can never be mistaken for the one the
+// proxy forwards to the render; both are stripped from every inbound request.
+export const CLIENT_BEARER_HEADER = 'x-assembly-client-bearer';
+// Asks the re-exchange route to return the minted bearer in its response body.
+// Sent only by a client that has proven the cookie is unavailable, so a browser
+// whose cookie works keeps the original response shape and never receives a
+// bearer anywhere a script could read it.
+export const BEARER_IN_BODY_HEADER = 'x-assembly-bearer-in-body';
+// Client-readable twin of the bearer cookie: same attributes, no HttpOnly, no
+// value worth having. The bearer itself is HttpOnly, so its absence is
+// invisible to the client; a browser that dropped this one dropped the bearer
+// beside it, which is what the client tests to detect cookie-less mode.
+export const COOKIE_PROBE_NAME = 'assembly-cookie-probe';
+// The probe answers "can this browser store our cookies at all", which does not
+// stop being true when the bearer expires. Giving it the bearer's TTL would make
+// a cookie-capable browser look cookie-less at every renewal, so it outlives the
+// bearer and is cleared explicitly instead.
+const COOKIE_PROBE_TTL_SECONDS = 24 * 60 * 60;
+// Serialize the probe to accompany a bearer write or clear. Attributes mirror
+// serializeBearerCookie (minus HttpOnly, and minus its TTL) so the two share a
+// fate in any browser that refuses the cookie outright — a probe that survived
+// where the bearer was refused would make the detection lie.
+export function serializeCookieProbe(partitioned, clear = false) {
+    const maxAge = clear ? 0 : COOKIE_PROBE_TTL_SECONDS;
+    let cookie = `${COOKIE_PROBE_NAME}=1; Path=/; Secure; SameSite=None; Max-Age=${maxAge}`;
+    if (partitioned)
+        cookie += '; Partitioned';
+    return cookie;
+}
 // Marker header on 401s that mean "the bearer expired — re-exchange and retry",
 // emitted by requireAuth / getAssemblyForRequest / the re-exchange route. Its
 // absence on a denial is what lets authFetch skip renewal for genuine
@@ -99,12 +131,15 @@ export function logRenewOutcome(outcome,
 // `bridgeRefreshFailed` records that the pre-renewal token refresh threw and
 // we fell back to the token already in hand — on its own that is survivable,
 // but paired with a rejection it names the parent as the failing side.
+// `cookieless` marks a renewal on the header-borne path, so its success rate
+// can be read separately from the cookie population's.
 detail) {
     console.log(JSON.stringify({
         event_type: RENEW_OUTCOME_EVENT,
         outcome,
         ...(detail?.bridgeRefreshFailed ? { bridge_refresh_failed: true } : {}),
         ...(typeof detail?.status === 'number' ? { status: detail.status } : {}),
+        ...(detail?.cookieless ? { cookieless: true } : {}),
     }));
 }
 // Two-tier detection: Sec-Fetch-Dest when the browser sends it (all evergreen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.25-rc.2",
+  "version": "0.0.25-rc.4",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

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

@@ -1,3 +1,4 @@
+<!-- !feature:app-owned-header -->
 ---
 name: assembly-app-bridge-header
 description: Use any time the app sets breadcrumbs, primary/secondary CTA, or actions menu in the header chrome. Always drive it via useAssemblyHeader — never call AssemblyBridge.header.set* from your own useEffect. The parent auto-prepends the app name as breadcrumb 0 — never include it yourself.
@@ -86,3 +87,5 @@ The Notification Center embeds the notification surface in a plain `<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.
+
+<!-- /feature:app-owned-header -->

package/skills/assembly-notifications/SKILL.md

@@ -72,13 +72,20 @@ export default async function NotificationSurface({
 
 ### CTAs on the notification surface — inline buttons, NOT the header
 
+<!-- !feature:app-owned-header -->
 The Notification Center embeds the notification surface (`/n`) in a plain `<iframe>` **without app bridge header support**. `useAssemblyHeader` calls on this surface are silently ignored — `primaryCta`, `secondaryCta`, and `actionsMenu` never render.
 
 **On the notification surface, render primary action buttons (Approve, Reject, Submit, Mark Complete, etc.) as inline `<Button>` elements in the page body.** This is the one exception to the portal-wide rule that CTAs must go in the header. The exception applies ONLY to the `/n` route — all other surfaces must continue using `useAssemblyHeader`.
+<!-- /feature:app-owned-header -->
+<!-- feature:app-owned-header -->
+**On the notification surface, render primary action buttons (Approve, Reject, Submit, Mark Complete, etc.) as inline `<Button>` elements in the page body.**
+<!-- /feature:app-owned-header -->
 
 Detect the notification surface by the route itself — code under `app/n/` IS the surface. For a component shared with other surfaces, pass an explicit `variant="notification"` prop from the `/n` page rather than inferring it from `payload.notificationId`: the claim is best-effort under the session-exchange flow, so a component that keys off it can silently fall back to header CTAs that never render inside the Notification Center iframe.
+<!-- !feature:app-owned-header -->
 
 **Do not reuse a component that calls `useAssemblyHeader` on the notification surface.** A component that calls `useAssemblyHeader` AND renders an inline action button produces duplicate CTAs on non-notification surfaces — the header button and the inline button both appear. Either create a dedicated component for `/n` that uses only inline buttons, or accept a prop that switches between header and inline CTAs.
+<!-- /feature:app-owned-header -->
 
 ## Creating a notification