@assembly-js/app-foundation 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -19,6 +19,9 @@ 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.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/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

@@ -71,3 +71,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.0",
   "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",