@assembly-js/app-foundation 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -19,6 +19,14 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.8.0
+- [new] `useUrlState('id')` from `@assembly-js/app-foundation/client` keeps a record selection in the URL search string, so a record panel is deep-linkable without its own route.
+- [new] `bun run build` runs `check:record-urls`, which fails when a record panel is opened from React state alone, with neither the helper nor a dynamic route. It only runs on apps that carry the inner-location skill.
+- [guidance] `assembly-app-inner-location` says selection state lives in the URL and a record opened from a list must load cold from its URL.
+
+## 0.7.3
+- [guidance] The build agent's auth guide is now its own section in `CLAUDE.md` instead of sitting under "Design system", and the rule for choosing between `getAssembly()` and `getInstallerAssembly()` is stated once in `assembly-route-auth` rather than repeated in the notifications, automations and internal-users skills.
+
 ## 0.7.2
 - [guidance] The build agent now sets `allow="autoplay; fullscreen; picture-in-picture; encrypted-media"` and `allowfullscreen` on embedded video player iframes, so Vimeo and YouTube players can go fullscreen, autoplay and use picture-in-picture inside the portal.
 

package/CLAUDE.md

@@ -910,7 +910,7 @@ export async function GET(request: NextRequest) {
 }
 ```
 
-### How auth works — read this first (it's automatic, and not what you'd guess)
+## How auth works — read this first (it's automatic, and not what you'd guess)
 
 Your app authenticates every API call with a short-lived, user-scoped **bearer token**. You never handle the raw session token and you never pass a token to anything — the foundation manages the whole lifecycle:
 
@@ -929,7 +929,7 @@ Every authenticated call your app makes is one of exactly three kinds:
 2. **Installer client** — `getInstallerAssembly()`, allowed inside a user request. Use it for staff-wide reads and writes the app is entitled to on its own, including notification helpers, app storage and connectors. It acts as the installing admin, so filter anything from it before showing it to a client. A viewer cookie does not make it refuse; `getOfflineAssembly()` does.
 3. **Offline bearer** — for background work with no user in the loop (cron, webhooks). Call `getOfflineAssembly()` (see "Offline bearer" below); it mints an app-scoped bearer from your API key server-side. Only needed outside a request; it refuses when a viewer is present.
 
-#### `getAssembly()` — the only auth helper you need
+### `getAssembly()` — the only auth helper you need
 
 `getAssembly` comes from `@assembly-js/app-foundation/server`, an installed dependency — import from it, never edit or reimplement it. (Its `/client` subpath is the subset a `'use client'` module may import; `/server` covers everything server-side.) Call `getAssembly()` with **no arguments** anywhere server-side (server component, server action, route handler). It reads the bearer for the current request and returns an authenticated, per-request client:
 
@@ -942,7 +942,7 @@ const items = await assembly.listItems({});
 
 `getAssembly()` is async — always `await` it. If the bearer is missing or expired it throws `TokenInvalidError`; let it propagate, and the client helpers (`useServerAction` / `authFetch`) re-exchange and retry for you. If the platform cannot be reached to verify the bearer it throws `AuthUnavailableError` (and `getSessionIdentity()` does too) — a different error on purpose: it is not an expiry, so never catch it into `null`/signed-out and never re-exchange on it; let a route return 503, and render a retry state ("Couldn't load, try again" with a retry button) wherever a server component reads identity.
 
-#### Identity — who is the viewer?
+### Identity — who is the viewer?
 
 Server-side, `getSessionIdentity()` returns the viewer the platform verified for the bearer (no token to pass; the check is cached briefly per server instance):
 
@@ -972,7 +972,7 @@ export default function MyWidget() {
 
 Branch your UI on identity **before** making data calls — it's faster and more reliable than catching a 403.
 
-#### Fetching data — server actions via `useServerAction`
+### Fetching data — server actions via `useServerAction`
 
 Put SDK calls in `'use server'` actions that take **no token** and call `getAssembly()`. From the client, run them through `useServerAction` (`app/components/use-server-action.ts`) — it manages loading/error state and **silently re-exchanges + retries once** on a 60-minute bearer expiry, so you never write refresh logic:
 
@@ -1007,7 +1007,7 @@ For an imperative one-off (button handler, mutation), use `callAction` from `use
 - **Actions take no token.** Never accept, read, or pass a token — `getAssembly()` resolves the bearer itself. Never touch `AssemblyBridge.sessionToken.*` in a component or copy anything into your own `useState`/`useRef`.
 - **Data actions must let `TokenInvalidError` propagate** — never `try/catch` it into `null`/empty. The auto-retry only fires if the action surfaces the expiry. And never hand-roll refresh/retry; `useServerAction`/`callAction` already do it.
 
-#### Server action or route handler?
+### Server action or route handler?
 
 A client-to-server call is a server action by default. Its argument is a TypeScript parameter, so a payload that does not match the signature fails `tsc` in your inner loop. A route handler's body is an untyped wire contract — `JSON.stringify` on one side, `request.json()` on the other — and nothing checks that the two agree until a user sends the first request, which you cannot do from the sandbox. A mismatch `tsc` would catch in an action ships silently through a route and 400s for every user.
 
@@ -1023,7 +1023,7 @@ export type ReplyBody = z.input<typeof replyBody>;
 // component:               const body: ReplyBody = { parentId, text }; // tsc rejects what the route would 400
 ```
 
-#### Client → server via route handlers — `authFetch`
+### Client → server via route handlers — `authFetch`
 
 For the route-handler calls that remain, use `authFetch` from `app/components/lib-client.ts`. The bearer rides the cookie automatically; `authFetch` adds the required CSRF header and re-exchanges + retries once on a bearer expiry:
 
@@ -1046,7 +1046,7 @@ Every state-changing request (POST/PUT/PATCH/DELETE) **must** go through `authFe
 
 In current apps `proxy.ts` lets a request that carries no cookies skip the CSRF check, so an inbound third-party call (a webhook) needs no proxy change; an older `proxy.ts` without that rule still answers 403 to a header-less POST. Authenticate the caller inside the route (signature or shared secret), fail closed when its secret is unset, and never add an unauthenticated test endpoint.
 
-#### Route handlers — `getAssemblyForRequest`
+### Route handlers — `getAssemblyForRequest`
 
 ```ts
 // app/api/clients/[clientId]/flavor/route.ts
@@ -1076,7 +1076,7 @@ export async function PATCH(
 
 **Auth is entirely cookie-borne: no `?token=`, no `x-assembly-token` header, no token proxy, no `TokenLink`/`useWithToken`, no client-side token at all.** The middleware put the bearer in the cookie; `getAssembly()` / `getAssemblyForRequest()` read it. That's the whole story.
 
-#### Offline bearer — background work with no user (cron, webhooks)
+### Offline bearer — background work with no user (cron, webhooks)
 
 **Anything on a schedule — a reminder, a digest, a recurring send — must first read the `assembly-scheduled-work` skill.** The route below only ever runs if `vercel.json` declares a cron for it and the route verifies `CRON_SECRET`; the offline bearer is the auth half, the skill is the scheduling half.
 
@@ -1103,7 +1103,7 @@ Rules for the offline path:
 - **`getSessionIdentity()` returns `null`** here — the bearer is the app, not a person. Anything that needs a user id (e.g. a notification `senderId`) must be chosen explicitly (a system/admin internal user), not read from identity.
 - Still bearer-only: no `?token=`, no `x-assembly-token`, no X-API-Key on data calls. The app key is used solely to mint the bearer.
 
-#### Auth guards for `[id]`-nested routes — `requireAuth` and `requireCompanyScope`
+### Auth guards for `[id]`-nested routes — `requireAuth` and `requireCompanyScope`
 
 Two pre-built helpers guard API routes that operate on company-scoped resources:
 

package/bin/check-record-urls.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Fails the build when a record opened from a list (a Dialog, Sheet, Drawer or
+// detail panel) is driven by React state alone: the host URL never changes, so a
+// reload or a shared link lands on the list instead of the record. The fix is
+// either `useUrlState('id')` from `@assembly-js/app-foundation/client` or a
+// dynamic route for the record on the internal surface. The match is a
+// heuristic on a `selected*`-style `useState` that feeds a panel-like element.
+// Dependency free on purpose: it runs inside the generated app's sandbox before
+// any deps beyond Node are guaranteed.
+//
+// Inert unless the inner-location skill was written into the app: that skill ships
+// only when the deep-link flag is on, while the layout mounts <LocationReporter />
+// in every build, so the reporter alone cannot tell an off-flag app apart.
+// On a platform update turn (ASSEMBLY_UPDATE_TURN=1) it only warns, because an
+// update never rewrites how an app navigates.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
+const APP_DIR = join(ROOT, 'app');
+const MANIFEST = join(ROOT, '.assembly', 'app.json');
+const INNER_LOCATION_SKILL = join(ROOT, '.claude', 'skills', 'assembly-app-inner-location', 'SKILL.md');
+const SOURCE_FILE = /\.(tsx|jsx)$/;
+const PAGE_FILE = /^page\.(tsx|ts|jsx|js)$/;
+
+// `const [selectedRequest, setSelectedRequest] = useState(...)`; the setter name is not trusted.
+const USE_STATE = /const\s+\[\s*([A-Za-z_$][\w$]*)\s*,\s*[A-Za-z_$][\w$]*\s*\]\s*=\s*useState\b/g;
+const RECORD_SELECTION = /^(?:selected|active|viewing|viewed|current|detail|open(?:ed)?)[A-Z_]/;
+// Selection of something that is not a record, or that is genuinely transient.
+const NOT_A_RECORD = /(?:Tab|Filter|Status|Sort|View|Option|Date|Range|Column|Mode|Step|Page|Menu)s?$|^(?:confirm|delete|remove|menu|pending)/i;
+const PANEL_ELEMENT = /<\w*(?:Dialog|Sheet|Drawer|Panel|Modal|Detail)\w*[\s>/]/;
+const OPT_OUT = /record-urls:\s*transient/;
+
+function sourceFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      out.push(...sourceFiles(full));
+    } else if (/\.(tsx|ts|jsx|js|mjs)$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Prefixes of the client and notification surfaces; a dynamic route there does
+// not give the internal dashboard a record URL.
+function nonInternalPrefixes() {
+  const prefixes = new Set(['/c', '/n']);
+  try {
+    const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
+    for (const key of ['client', 'notification']) {
+      const p = manifest?.surfaces?.[key]?.path;
+      if (typeof p === 'string' && p.startsWith('/') && p !== '/') prefixes.add(p.replace(/\/+$/, ''));
+    }
+  } catch {
+    // defaults
+  }
+  return prefixes;
+}
+
+function routeForPageFile(file) {
+  const segments = relative(APP_DIR, file).split(sep).slice(0, -1);
+  const urlSegments = segments.filter(
+    (seg) => !(seg.startsWith('(') && seg.endsWith(')')) && !seg.startsWith('@'),
+  );
+  return '/' + urlSegments.join('/');
+}
+
+if (!existsSync(APP_DIR)) process.exit(0);
+
+const files = [...sourceFiles(APP_DIR), ...sourceFiles(join(ROOT, 'components'))];
+const contents = new Map(files.map((f) => [f, readFileSync(f, 'utf8')]));
+
+if (!existsSync(INNER_LOCATION_SKILL)) process.exit(0);
+
+const prefixes = nonInternalPrefixes();
+const hasInternalRecordRoute = files.some((f) => {
+  if (!PAGE_FILE.test(f.split(sep).pop())) return false;
+  const route = routeForPageFile(f);
+  if (!route.includes('[')) return false;
+  return ![...prefixes].some((p) => route === p || route.startsWith(`${p}/`));
+});
+if (hasInternalRecordRoute) process.exit(0);
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const violations = [];
+for (const file of files) {
+  if (!SOURCE_FILE.test(file)) continue;
+  const src = contents.get(file);
+  if (/\buseUrlState\b/.test(src) || OPT_OUT.test(src) || !PANEL_ELEMENT.test(src)) continue;
+  for (const match of src.matchAll(USE_STATE)) {
+    const name = match[1];
+    if (!RECORD_SELECTION.test(name) || NOT_A_RECORD.test(name)) continue;
+    // Declared and read somewhere else in the file, i.e. it feeds the panel.
+    const uses = src.match(new RegExp(`(?<![\\w$.])${escapeRe(name)}(?![\\w$])`, 'g')) ?? [];
+    if (uses.length < 3) continue;
+    violations.push(`${relative(ROOT, file).split(sep).join('/')}  (useState: ${name})`);
+  }
+}
+
+if (violations.length > 0 && UPDATE_TURN) {
+  console.warn('');
+  console.warn('check-record-urls: record selection held in React state (this update turn is not failed for it):');
+  for (const v of violations) console.warn('  - ' + v);
+  console.warn('');
+} else if (violations.length > 0) {
+  console.error('');
+  console.error('Record selection lives only in React state — the URL never changes when a record opens:');
+  console.error('');
+  for (const v of violations) console.error('  - ' + v);
+  console.error('');
+  console.error('A reload or a shared link lands on the list, not on the record. Fix one of:');
+  console.error("  - Replace the useState with `const [id, setId] = useUrlState('id')` from");
+  console.error("    '@assembly-js/app-foundation/client' and render the record from `id`;");
+  console.error('    a cold load with ?id= must open it, and Back must close it.');
+  console.error('  - Give the record its own route (app/requests/[id]/page.tsx) and link to it.');
+  console.error('A genuinely transient UI (confirm dialog, menu) can add the comment');
+  console.error('`// record-urls: transient` to the file.');
+  process.exit(1);
+}

package/bin/foundation-exports.mjs

@@ -57,5 +57,5 @@ export const NON_CLIENT_EXPORTS = new Set([
   'redactUrl', 'replaceChildRows', 'requireAuth', 'requireCompanyScope', 'resolveFont',
   'resolveResource', 'sendThrottled', 'serializeBearerCookie', 'serializeBearerExpiryCookie', 'serializeCookieProbe',
   'setCookielessBearer', 'slackErrorCode', 'slackFindChannelId', 'slackListChannels',
-  'slackPostMessage', 'slackResolveMentions', 'snippetFromRequestBody', 'verifyBearer',
+  'slackPostMessage', 'slackResolveMentions', 'snippetFromRequestBody', 'useUrlState', 'verifyBearer',
 ]);

package/dist/client.d.ts

@@ -8,3 +8,4 @@ export * from './pagination.js';
 export * from './theme.js';
 export * from './resource-resolution.js';
 export { LocationReporter } from './location-reporter.js';
+export { useUrlState } from './url-state.js';

package/dist/client.js

@@ -25,3 +25,5 @@ export * from './theme.js';
 export * from './resource-resolution.js';
 // Browser-safe: the reporter pulls in no Node built-ins, unlike ./next.
 export { LocationReporter } from './location-reporter.js';
+// Keeps a record selection in the search string so the reporter mirrors it to the host URL.
+export { useUrlState } from './url-state.js';

package/dist/url-state.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The query string with `key` set to `value` (or removed when null), as a
+ * `?`-prefixed string or '' when nothing is left. Other params, including the
+ * host's embed-session ones, are carried through untouched.
+ */
+export declare function withSearchParam(search: URLSearchParams, key: string, value: string | null): string;
+export type SetUrlState = (value: string | null, opts?: {
+    replace?: boolean;
+}) => void;
+/**
+ * State that lives in the page's search string (`?id=abc`) instead of React
+ * state. The location reporter already mirrors the search string into the host
+ * URL, so a record panel driven by this hook is deep-linkable without its own
+ * route: a cold load with `?id=` reopens it and Back closes it.
+ *
+ * Plain Next navigation, so it behaves the same with no bridge present. The
+ * component must render under a Suspense boundary, as for any `useSearchParams`.
+ */
+export declare function useUrlState(key: string): [string | null, SetUrlState];

package/dist/url-state.js

@@ -0,0 +1,41 @@
+'use client';
+import { useCallback } from 'react';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+/**
+ * The query string with `key` set to `value` (or removed when null), as a
+ * `?`-prefixed string or '' when nothing is left. Other params, including the
+ * host's embed-session ones, are carried through untouched.
+ */
+export function withSearchParam(search, key, value) {
+    const next = new URLSearchParams(search);
+    if (value === null || value === '')
+        next.delete(key);
+    else
+        next.set(key, value);
+    const qs = next.toString();
+    return qs ? `?${qs}` : '';
+}
+/**
+ * State that lives in the page's search string (`?id=abc`) instead of React
+ * state. The location reporter already mirrors the search string into the host
+ * URL, so a record panel driven by this hook is deep-linkable without its own
+ * route: a cold load with `?id=` reopens it and Back closes it.
+ *
+ * Plain Next navigation, so it behaves the same with no bridge present. The
+ * component must render under a Suspense boundary, as for any `useSearchParams`.
+ */
+export function useUrlState(key) {
+    const pathname = usePathname();
+    const router = useRouter();
+    const searchParams = useSearchParams();
+    const value = searchParams.get(key);
+    const setValue = useCallback((next, opts) => {
+        const url = pathname + withSearchParam(new URLSearchParams(searchParams.toString()), key, next);
+        // Push by default so Back undoes the selection.
+        if (opts?.replace)
+            router.replace(url, { scroll: false });
+        else
+            router.push(url, { scroll: false });
+    }, [pathname, router, searchParams, key]);
+    return [value, setValue];
+}

package/package.json

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

package/skills/assembly-app-inner-location/SKILL.md

@@ -11,6 +11,10 @@ The host mirrors the app's inner page in its own address bar and can open the ap
 - Mount `<LocationReporter />` once, in `app/layout.tsx`, imported from `@assembly-js/app-foundation/client`. If it is already there, leave it.
 - Never write custom `location.report` or `location.onNavigate` code, and never hand-write a `LocationSync` component. The reporter already handles surface prefixes and route changes.
 
+## Records get a URL
+
+Keep which record is open in the URL, not in `useState`: `const [id, setId] = useUrlState('id')` from `@assembly-js/app-foundation/client` for a panel, Sheet or Dialog, or a route like `app/requests/[id]/page.tsx`. A record opened from a list must load cold from its URL and Back must close it. `bun run build` fails `check:record-urls` for a `selectedId`-style `useState` feeding a record panel; use the helper or a route to fix it.
+
 ## Notifications deep-link to the record, not the app root
 
 When the app sends an email or in-product notification about a specific record (a document request, a submission), the destination is set by the notification's `ctaParams` and surface, not by `linkTo`. Pass `ctaParams` that identify the record (`ctaParams: { requestId: request.id }`) and render that record from an existing inner route of this app, one that works when opened cold. Follow `assembly-notifications` for the send-and-open pattern.

package/skills/assembly-automations/SKILL.md

@@ -271,8 +271,6 @@ Every event also lands in the workspace's audit log, where a workspace admin rea
 
 The platform runs the action by calling the record's `baseUrl`, and `requireAuth` cannot authenticate that call. `lib/assembly-actions.ts` re-exports the wrapper from the foundation package — write that re-export, don't paste a second copy of the handler.
 
-Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
-
 ```ts
 // lib/assembly-actions.ts
 export {

package/skills/assembly-internal-users/SKILL.md

@@ -18,8 +18,6 @@ Never call `assembly.getTokenPayload()` for this — see `assembly-session-token
 
 If `internalUserId` is set, the current viewer is staff. (`clientId` is set for client viewers — see `assembly-client-users` skill.)
 
-Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
-
 ## SDK methods
 
 - `listInternalUsers({ nextToken, limit })` — paged list of all staff in the workspace

package/skills/assembly-notifications/SKILL.md

@@ -16,8 +16,6 @@ For a required condition alert (a retainer reaching 90%, going over its allowanc
 
 Every notification is three decisions: **audience** (internal users and/or clients), **channel** (in-product, email, or both), and **context on arrival** (what the recipient sees and can do). Get those right; the rest is mechanics.
 
-Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
-
 ### Internal vs client experience
 
 The audience changes the experience and the code: