@assembly-js/app-foundation 0.2.7 → 0.3.1

package/CHANGELOG.md

@@ -19,6 +19,13 @@ 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.3.1
+- [guidance] The build agent now upgrades an app's bridge to 2.1.0 and its foundation package instead of skipping a deep link, mounts the location reporter, and deep-links notifications to the specific record.
+- [new] App destinations in `NavigateDestination` now accept an optional `path` for links to an app's inner page.
+
+## 0.3.0
+- [new] `LocationReporter` is exported from `@assembly-js/app-foundation/client`, so apps born before the deeplink image can mount it in their layout and report their inner location to the host with the same surface-prefix handling as new apps.
+
 ## 0.2.7
 - [guidance] The build agent learns to call another app through its generated client and to show an empty state naming that app when the call is refused.
 

package/CLAUDE.md

@@ -48,6 +48,9 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 <!-- feature:deep-link-bridge-nav -->
 - `assembly-platform-links` — link platform records (client, company, invoice, contract, form, file) to their portal detail page via `linkTo()`; never hand-build a host URL. Also links between workspace apps by install id. Check the app's installed app-bridge first (see the skill) — `navigateTo` doesn't exist on older peers — and only link staff-only destinations (client, company, form, etc.) from the dashboard surface, never the client portal.
 <!-- /feature:deep-link-bridge-nav -->
+<!-- feature:deep-link-app-inner-location -->
+- `assembly-app-inner-location` — mount `<LocationReporter />` so the host mirrors the app's inner page in its address bar; deep-link a notification or link to a specific record with `linkTo({ to: 'app', installId, path })`, never to the app root. Never hand-write location reporting.
+<!-- /feature:deep-link-app-inner-location -->
 <!-- feature:cross-app-apis -->
 - `assembly-app-clients` — calling another workspace app through its generated client in `generated/apps/<appId>/` (`installerClient`, by verb and path), and rendering an empty state that names the app when the call is refused instead of a 500.
 <!-- /feature:cross-app-apis -->

package/bin/foundation-exports.mjs

@@ -27,7 +27,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   'ConnectionStatus', 'ConnectorError', 'ContractDocumentError', 'ConnectorErrorCode', 'CookieOutcome', 'CronHandler',
   'DEFAULT_LABELS', 'EXCHANGE_REJECTION_HEADER', 'ExchangeRejectedViewer', 'ExchangedSession',
   'FormatAirtableRecordsOpts', 'GenerateAppClientInput', 'GeneratedAppClient', 'GmailSendArgs', 'GmailSendResult', 'IntegrationClient',
-  'InternalUserAccess', 'LEGACY_APP_IDS', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
+  'InternalUserAccess', 'LEGACY_APP_IDS', 'LocationReporter', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
   'MintedBearer', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
   'NetworkCaptureRecord', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
   'PORTAL_ORIGIN_COOKIE_NAME', 'PdfText', 'PrincipalAllow', 'PrincipalKind',

package/dist/bridge-vnext.d.ts

@@ -48,6 +48,7 @@ export type NavigateDestination = {
 } | {
     to: 'app';
     installId: string;
+    path?: string;
 };
 export type NavigateToOptions = {
     replace?: boolean;
@@ -71,3 +72,17 @@ declare module '@assembly-js/app-bridge' {
         navigateTo(destination: NavigateDestination, options?: NavigateToOptions): Promise<NavigateResult>;
     }
 }
+export type LocationNavigatePayload = {
+    path: string;
+    search: string;
+    replace?: boolean;
+};
+export interface LocationBridge {
+    report(path: string, search: string, replace?: boolean): void;
+    onNavigate(handler: (payload: LocationNavigatePayload) => void): void;
+}
+declare module '@assembly-js/app-bridge' {
+    interface AssemblyBridgeApi {
+        location: LocationBridge;
+    }
+}

package/dist/client.d.ts

@@ -7,3 +7,4 @@ export * from './client-companies.js';
 export * from './pagination.js';
 export * from './theme.js';
 export * from './resource-resolution.js';
+export { LocationReporter } from './location-reporter.js';

package/dist/client.js

@@ -23,3 +23,5 @@ export * from './theme.js';
 // at compile time, but a value import from ./server would trip the server-only
 // guard for no reason.
 export * from './resource-resolution.js';
+// Browser-safe: the reporter pulls in no Node built-ins, unlike ./next.
+export { LocationReporter } from './location-reporter.js';

package/dist/location-prefix.d.ts

@@ -0,0 +1,19 @@
+export declare function getSurfacePrefixes(): string[];
+export declare const SURFACE_PREFIXES: string[];
+/**
+ * Detect which surface prefix the given pathname belongs to.
+ * Returns the prefix string (e.g. '/c') or '' for the internal surface.
+ */
+export declare function getSurfacePrefix(pathname: string): string;
+/**
+ * Remove a surface prefix from a pathname, returning an app-local path.
+ * '/c/orders/42' with prefix '/c' → '/orders/42'
+ * '/c' with prefix '/c' → '/'
+ */
+export declare function stripPrefix(pathname: string, prefix: string): string;
+/**
+ * Re-attach a surface prefix to an app-local path received from the host.
+ * '/orders/42' with prefix '/c' → '/c/orders/42'
+ * '/' with prefix '/c' → '/c'
+ */
+export declare function addPrefix(prefix: string, path: string): string;

package/dist/location-prefix.js

@@ -0,0 +1,60 @@
+const DEFAULT_PREFIXES = ['/c', '/n'];
+// Read surface prefixes from the build-time env value injected by withAssemblyDev.
+// Falls back to the historical /c and /n defaults so apps on an older image
+// continue to work without a rebuild.
+export function getSurfacePrefixes() {
+    const raw = process.env.NEXT_PUBLIC_ASSEMBLY_SURFACE_PREFIXES;
+    if (!raw)
+        return DEFAULT_PREFIXES;
+    try {
+        const parsed = JSON.parse(raw);
+        const prefixes = parsed
+            .filter((p) => typeof p === 'string' && p !== '/')
+            .map((p) => p.replace(/\/+$/, ''));
+        if (prefixes.length === 0)
+            return DEFAULT_PREFIXES;
+        // Longest first so /clients never matches as /c + "lients".
+        return [...prefixes].sort((a, b) => b.length - a.length);
+    }
+    catch {
+        return DEFAULT_PREFIXES;
+    }
+}
+// Kept for backwards compatibility; callers that import this directly still work.
+export const SURFACE_PREFIXES = getSurfacePrefixes();
+/**
+ * Detect which surface prefix the given pathname belongs to.
+ * Returns the prefix string (e.g. '/c') or '' for the internal surface.
+ */
+export function getSurfacePrefix(pathname) {
+    for (const prefix of getSurfacePrefixes()) {
+        if (pathname === prefix || pathname.startsWith(`${prefix}/`)) {
+            return prefix;
+        }
+    }
+    return '';
+}
+/**
+ * Remove a surface prefix from a pathname, returning an app-local path.
+ * '/c/orders/42' with prefix '/c' → '/orders/42'
+ * '/c' with prefix '/c' → '/'
+ */
+export function stripPrefix(pathname, prefix) {
+    if (!prefix)
+        return pathname;
+    if (pathname === prefix)
+        return '/';
+    return pathname.slice(prefix.length) || '/';
+}
+/**
+ * Re-attach a surface prefix to an app-local path received from the host.
+ * '/orders/42' with prefix '/c' → '/c/orders/42'
+ * '/' with prefix '/c' → '/c'
+ */
+export function addPrefix(prefix, path) {
+    if (!prefix)
+        return path;
+    if (path === '/')
+        return prefix;
+    return `${prefix}${path}`;
+}

package/dist/location-reporter.d.ts

@@ -0,0 +1 @@
+export declare function LocationReporter(): import("react").FunctionComponentElement<import("react").SuspenseProps>;

package/dist/location-reporter.js

@@ -0,0 +1,46 @@
+'use client';
+import { Suspense, createElement, useEffect, useRef } from 'react';
+import { usePathname, useSearchParams, useRouter } from 'next/navigation';
+import { AssemblyBridge } from '@assembly-js/app-bridge';
+import { getSurfacePrefix, stripPrefix, addPrefix } from './location-prefix.js';
+function LocationReporterInner() {
+    const pathname = usePathname();
+    const searchParams = useSearchParams();
+    const router = useRouter();
+    // Mutable ref so the onNavigate closure always sees the current prefix
+    // without needing to re-register the handler on every pathname change.
+    const prefixRef = useRef('');
+    const prefix = getSurfacePrefix(pathname);
+    prefixRef.current = prefix;
+    // Bridges below 2.1 type `location` (see bridge-vnext.ts) but lack it at runtime.
+    const bridgeLocation = AssemblyBridge.location;
+    // Report location on every client-side route change.
+    useEffect(() => {
+        if (!bridgeLocation)
+            return;
+        const path = stripPrefix(pathname, prefix);
+        const qs = searchParams.toString();
+        bridgeLocation.report(path, qs ? `?${qs}` : '');
+    }, [bridgeLocation, pathname, searchParams, prefix]);
+    // Register the navigate handler once; rely on prefixRef for the current prefix.
+    useEffect(() => {
+        if (!bridgeLocation)
+            return;
+        bridgeLocation.onNavigate(({ path, search, replace }) => {
+            const dest = addPrefix(prefixRef.current, path) + (search ?? '');
+            if (replace) {
+                router.replace(dest);
+            }
+            else {
+                router.push(dest);
+            }
+        });
+    }, [bridgeLocation, router]);
+    return null;
+}
+// useSearchParams requires a Suspense boundary to avoid de-opting the route
+// to full client-side rendering in Next.js App Router. createElement keeps
+// the package free of a jsx compiler setting.
+export function LocationReporter() {
+    return createElement(Suspense, { fallback: null }, createElement(LocationReporterInner));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -56,6 +56,7 @@
     "@neondatabase/serverless": "^1.1.0",
     "@types/bun": "^1.1.0",
     "@types/node": "^22",
+    "@types/react": "^19.3.0",
     "drizzle-orm": "^0.45.2",
     "esbuild": "^0.25.12",
     "next": "^15.5.0",

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

@@ -0,0 +1,19 @@
+<!-- feature:deep-link-app-inner-location -->
+---
+name: assembly-app-inner-location
+description: Use whenever the app has inner pages the host should mirror in its address bar, or when a notification, email or link should open this app on a specific record instead of its root. Covers mounting LocationReporter and pointing notifications at a specific record.
+---
+
+## What the reporter does
+
+The host mirrors the app's inner page in its own address bar and can open the app straight at an inner page. That only works if the app reports its location, and `<LocationReporter />` from the foundation package does exactly that. The reporter needs `AssemblyBridge.location`, which ships in app-bridge 2.1.0, and a `navigateTo`-only 2.0.0 bridge lacks it. Check with `grep -q onNavigate node_modules/@assembly-js/app-bridge/dist/index.d.ts && echo supported || echo unsupported`; if `unsupported`, run `bun add @assembly-js/app-bridge@2.1.0` (exact stable release, never a prerelease or range), then `bunx tsc --noEmit`, before mounting the reporter.
+
+- 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.
+
+## 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.
+
+To link from a button inside the app to an inner page, use `linkTo` as described in `assembly-platform-links` (the `app` destination takes an optional `path`).
+<!-- /feature:deep-link-app-inner-location -->

package/skills/assembly-platform-links/SKILL.md

@@ -14,7 +14,13 @@ Before writing any `linkTo()` or `AssemblyBridge.navigateTo()` call, check what
 grep -q navigateTo node_modules/@assembly-js/app-bridge/dist/index.d.ts && echo supported || echo unsupported
 ```
 
-If it reports `unsupported`, do not use this skill — there is no supported way for this app to trigger platform navigation yet. Skip the link rather than ship a button that silently does nothing.
+If it reports `unsupported`, upgrade the app in this same turn instead of skipping the link:
+
+1. Confirm the app is on the foundation package: `grep -q app-foundation package.json`. If it is not (vendored `lib/`), say the security update must land first and stop — do not attempt the migration in a feature turn.
+2. Pin the bridge to the exact stable release: `bun add @assembly-js/app-bridge@2.1.0`. Never pin a prerelease (`-beta`, `-rc`, `-next`) or a range.
+3. Bump the foundation dependency listed in `package.json` to `^0.3.0`, the floor that exports `linkTo` and `LocationReporter` (`bun add <that package name>@^0.3.0`).
+4. Run `bunx tsc --noEmit` and `bun run build`, and confirm the existing header and toast bridge calls still type-check. Fix any break before continuing.
+5. Re-run the check above, then proceed with this skill.
 
 ## When to reach for this skill
 
@@ -74,7 +80,7 @@ The host rejects staff-only destinations when the viewer is a client in the port
 | `article` | `articleId` | — | Yes |
 | `files` | — | `channelId` | Yes |
 | `channel` | — | `channelId` | Yes |
-| `app` | `installId` | — | Yes, if the target app is installed for that viewer |
+| `app` | `installId` | `path` | Yes, if the target app is installed for that viewer |
 | `home` | — | — | No — staff only |
 | `product` | — | — | No — staff only |
 | `helpdesk` | — | — | Yes |