@proveanything/smartlinks 1.14.10 → 1.14.12

package/dist/api/contact.d.ts

@@ -1,4 +1,4 @@
-import { ContactResponse, ContactCreateRequest, ContactUpdateRequest, ContactListResponse, PublicContactUpsertRequest, PublicContactUpsertResponse, UserSearchResponse, ContactPatch, PublicGetMyContactResponse, PublicUpdateMyContactResponse, ContactSchemaResponse } from "../types";
+import { ContactResponse, ContactCreateRequest, ContactUpdateRequest, ContactListResponse, ContactSearchParams, ContactSearchResponse, PublicContactUpsertRequest, PublicContactUpsertResponse, UserSearchResponse, ContactPatch, PublicGetMyContactResponse, PublicUpdateMyContactResponse, ContactSchemaResponse } from "../types";
 export declare namespace contact {
     function create(collectionId: string, data: ContactCreateRequest): Promise<ContactResponse>;
     function list(collectionId: string, params?: {
@@ -6,6 +6,7 @@ export declare namespace contact {
         offset?: number;
         includeDeleted?: boolean;
     }): Promise<ContactListResponse>;
+    function search({ collectionId, q, typeahead, email, phone, id, userId, tags, tagsAll, source, locale, createdFrom, createdTo, externalIdKey, externalIdValue, customFieldKey, customFieldValue, limit, offset, }: ContactSearchParams): Promise<ContactSearchResponse>;
     function get(collectionId: string, contactId: string, params?: {
         includeDeleted?: boolean;
     }): Promise<ContactResponse>;

package/dist/api/contact.js

@@ -19,6 +19,52 @@ export var contact;
         return request(path);
     }
     contact.list = list;
+    async function search({ collectionId, q, typeahead, email, phone, id, userId, tags, tagsAll, source, locale, createdFrom, createdTo, externalIdKey, externalIdValue, customFieldKey, customFieldValue, limit, offset, }) {
+        const query = new URLSearchParams();
+        if (q !== undefined)
+            query.set("q", q);
+        if (typeahead !== undefined)
+            query.set("typeahead", String(typeahead));
+        if (email !== undefined)
+            query.set("email", email);
+        if (phone !== undefined)
+            query.set("phone", phone);
+        if (id !== undefined)
+            query.set("id", id);
+        if (userId !== undefined)
+            query.set("userId", userId);
+        if (tags !== undefined) {
+            const arr = Array.isArray(tags) ? tags : tags.split(",").map(t => t.trim());
+            arr.forEach(t => query.append("tags", t));
+        }
+        if (tagsAll !== undefined) {
+            const arr = Array.isArray(tagsAll) ? tagsAll : tagsAll.split(",").map(t => t.trim());
+            arr.forEach(t => query.append("tagsAll", t));
+        }
+        if (source !== undefined)
+            query.set("source", source);
+        if (locale !== undefined)
+            query.set("locale", locale);
+        if (createdFrom !== undefined)
+            query.set("createdFrom", createdFrom);
+        if (createdTo !== undefined)
+            query.set("createdTo", createdTo);
+        if (externalIdKey !== undefined)
+            query.set("externalIdKey", externalIdKey);
+        if (externalIdValue !== undefined)
+            query.set("externalIdValue", externalIdValue);
+        if (customFieldKey !== undefined)
+            query.set("customFieldKey", customFieldKey);
+        if (customFieldValue !== undefined)
+            query.set("customFieldValue", customFieldValue);
+        if (limit !== undefined)
+            query.set("limit", String(limit));
+        if (offset !== undefined)
+            query.set("offset", String(offset));
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/contacts/search?${query.toString()}`;
+        return request(path);
+    }
+    contact.search = search;
     async function get(collectionId, contactId, params) {
         const query = new URLSearchParams();
         if ((params === null || params === void 0 ? void 0 : params.includeDeleted) !== undefined)

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.14.10  |  Generated: 2026-05-16T17:03:23.904Z
+Version: 1.14.12  |  Generated: 2026-05-19T11:25:45.278Z
 
 This is a concise summary of all available API functions and types.
 
@@ -36,6 +36,11 @@ For detailed guides on specific features:
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
 - **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
 - **[Auth Kit](auth-kit.md)** - End-user authentication flows (email/password, magic link, OTP, OAuth) for microapps
+- **[Portal Request Login](portal-request-login.md)** - Sub-apps delegate user authentication to the portal; `useSafeAuth().requestLogin` hook and iframe postMessage contract, redirect-bounce handling
+- **[Portal Auth Broadcast](portal-auth-broadcast.md)** - Publishing a custom-flow session to the portal so the header, sibling apps, and SDK all stay in sync
+- **[Portal Request Action](portal-request-action.md)** - Invoking portal built-in actions (`__qrScanner`, `__share`, `__logout`, etc.) from containers, widgets, and iframes
+- **[Portal Back Button](portal-back-button.md)** - `parentPath` contract for hierarchy-aware "up" navigation; `useDeepLinkSync` integration
+- **[Contact Search](contact-search.md)** - Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
 - **[Forms](forms.md)** - Platform-managed form definitions, submissions, and schema-driven React form UI
 - **[App Objects: Cases, Threads & Records](app-objects.md)** - Generic app-scoped building blocks for support cases, discussions, bookings, registrations, and more
@@ -89,7 +94,7 @@ The Smartlinks SDK is organized into the following namespaces:
 — Identity & Access —
 - **auth** - Admin authentication and account ops: login/logout, tokens, account info.
 - **authKit** - End‑user auth flows (email/password, OAuth, phone); profiles and verification.
-- **contact** - Manage customer contacts; CRUD, lookup, upsert, erase.
+- **contact** - Manage customer contacts; CRUD, lookup, upsert, erase, and admin search. → [Guide](contact-search.md)
 
 — Messaging & Audience —
 - **comms** - Send notifications (push, email, wallet); templating, severity, delivery status. → [Guide](comms.md)
@@ -4460,6 +4465,40 @@ interface ContactListResponse {
 }
 ```
 
+**ContactSearchParams** (interface)
+```typescript
+interface ContactSearchParams {
+  collectionId: string
+  q?: string
+  typeahead?: boolean
+  email?: string
+  phone?: string
+  id?: string
+  userId?: string
+  tags?: string | string[]
+  tagsAll?: string | string[]
+  source?: string
+  locale?: string
+  createdFrom?: string
+  createdTo?: string
+  externalIdKey?: string
+  externalIdValue?: string
+  customFieldKey?: string
+  customFieldValue?: string
+  limit?: number
+  offset?: number
+}
+```
+
+**ContactSearchResponse** (interface)
+```typescript
+interface ContactSearchResponse {
+  items: Contact[]
+  limit: number
+  offset: number
+}
+```
+
 **PublicContactUpsertResponse** (interface)
 ```typescript
 interface PublicContactUpsertResponse {
@@ -8629,6 +8668,28 @@ Returns all proof type definitions. Proof types are templates that specify which
 **list**(collectionId: string,
     params?: { limit?: number; offset?: number; includeDeleted?: boolean }) → `Promise<ContactListResponse>`
 
+**search**({
+    collectionId,
+    q,
+    typeahead,
+    email,
+    phone,
+    id,
+    userId,
+    tags,
+    tagsAll,
+    source,
+    locale,
+    createdFrom,
+    createdTo,
+    externalIdKey,
+    externalIdValue,
+    customFieldKey,
+    customFieldValue,
+    limit,
+    offset,
+  }: ContactSearchParams) → `Promise<ContactSearchResponse>`
+
 **get**(collectionId: string,
     contactId: string,
     params?: { includeDeleted?: boolean }) → `Promise<ContactResponse>`

package/dist/docs/contact-search.md

@@ -0,0 +1,162 @@
+# Contact Search
+
+Admin-scoped endpoint for querying contacts within a collection. Supports
+free-text search, type-ahead, identity lookup, structured filters, and JSONB
+field queries. All parameters are optional and composable.
+
+**Base path:** `GET /api/admin/:collectionId/contacts/search`
+
+---
+
+## Quick examples
+
+```ts
+// Type-ahead while user types "joh" into a search box
+await contact.search({ collectionId, q: "joh", typeahead: true })
+
+// Find contacts by partial email
+await contact.search({ collectionId, email: "acme.com" })
+
+// Exact contact by UUID
+await contact.search({ collectionId, id: "uuid-here" })
+
+// All contacts tagged "vip" created this year
+await contact.search({
+  collectionId,
+  tags: ["vip"],
+  createdFrom: "2026-01-01",
+})
+
+// Find by external ID (e.g. Shopify customer ID)
+await contact.search({
+  collectionId,
+  externalIdKey: "shopify_id",
+  externalIdValue: "123456",
+})
+```
+
+---
+
+## Parameters
+
+### Free-text
+
+| Param | Type | Description |
+|---|---|---|
+| `q` | `string` | General search term. Searches `first_name`, `last_name`, `display_name`, `company`, and all identity values (`email`, `phone`). When the value contains `@` only email identities are searched; when it matches a phone pattern only phone identities are searched. |
+| `typeahead` | `boolean` | When `true`, uses prefix (`startsWith`) operators instead of substring (`contains`). Significantly cheaper per keystroke. Default limit becomes `10`; minimum `q` length is 2 characters. Use this for live search-as-you-type UIs. |
+
+### Identity filters
+
+| Param | Type | Description |
+|---|---|---|
+| `email` | `string` | Partial match against normalised email identity values. Case-insensitive. |
+| `phone` | `string` | Partial match against normalised phone identity values. |
+
+### Exact lookups
+
+These short-circuit all text/filter logic and return at most one contact.
+
+| Param | Type | Description |
+|---|---|---|
+| `id` | `string` (UUID) | Contact primary key. |
+| `userId` | `string` | Firebase auth UID linked to the contact. |
+
+### Structured filters
+
+All filters are ANDed with each other and with any text search.
+
+| Param | Type | Description |
+|---|---|---|
+| `tags` | `string \| string[]` | Comma-separated string or repeated param. Contacts must have **any** of these tags. |
+| `tagsAll` | `string \| string[]` | Contacts must have **all** of these tags. |
+| `source` | `string` | Exact match on the `source` field. |
+| `locale` | `string` | Exact match on the `locale` field (e.g. `"en-US"`). |
+| `createdFrom` | `string` (ISO-8601) | Lower bound on `created_at`. |
+| `createdTo` | `string` (ISO-8601) | Upper bound on `created_at`. |
+
+### JSONB field filters
+
+Searches inside the `external_ids` or `custom_fields` JSONB columns by
+key/value pair. Both params in a pair must be supplied together.
+
+| Param | Type | Description |
+|---|---|---|
+| `externalIdKey` | `string` | Top-level key in `externalIds` (e.g. `"shopify_id"`). |
+| `externalIdValue` | `string` | Expected value at that key. |
+| `customFieldKey` | `string` | Top-level key in `customFields`. |
+| `customFieldValue` | `string` | Expected value at that key. |
+
+### Pagination
+
+| Param | Type | Default | Max |
+|---|---|---|---|
+| `limit` | `number` | `20` (`10` in typeahead mode) | `100` (`10` in typeahead mode) |
+| `offset` | `number` | `0` | — |
+
+---
+
+## Response
+
+```ts
+{
+  items: Contact[],
+  limit: number,
+  offset: number,
+}
+```
+
+Each `Contact` item follows the shape defined in `src/types/contact.ts`.
+
+---
+
+## SDK usage
+
+```ts
+import { contact } from '@proveanything/smartlinks'
+
+const results = await contact.search({
+  collectionId: "my-collection",
+  q: "jane",
+  tags: ["vip"],
+  limit: 20,
+})
+
+for (const c of results.items) {
+  console.log(c.displayName, c.email)
+}
+```
+
+---
+
+## Performance notes
+
+The search endpoint is backed by **PostgreSQL trigram GIN indexes** via the
+`pg_trgm` extension (migration `20260519000001`). This makes `ILIKE '%query%'`
+scans fast even with millions of contacts per org.
+
+**What is a trigram?** PostgreSQL decomposes every string into overlapping
+3-character windows ("trigrams") and stores them in an inverted index. A query
+for `"acme"` is converted into trigrams `" ac", "acm", "cme", "me "` and the
+index returns only rows containing those windows — so Postgres never scans rows
+that can't match, regardless of whether the query is a prefix, suffix, or
+middle-of-word substring.
+
+**Type-ahead mode** (`typeahead: true`) is the recommended pattern for
+keystroke-by-keystroke UI. It emits `LIKE 'query%'` (prefix) operators instead
+of `LIKE '%query%'` (substring). Prefix scans are cheaper because they require
+fewer trigram lookups, making them safe to call on every keypress. Minimum query
+length is enforced at 2 characters server-side to prevent over-broad scans.
+
+**Future scale path:** At very high volumes, routing `search` through
+Elasticsearch would add typo-tolerance and relevance ranking. The API surface is
+intentionally implementation-agnostic so the backing engine can be swapped
+without client changes.
+
+---
+
+## Error codes
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `SEARCH_REQUIRED` | 400 | No searchable parameter was provided. |

package/dist/docs/overview.md

@@ -65,6 +65,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
+| **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
 | **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
@@ -74,7 +75,9 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
 | **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
 | **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
+| **Portal Request Login** | `docs/portal-request-login.md` | How sub-apps ask the portal to authenticate the user; hook and iframe postMessage contracts |
 | **Portal Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
+| **Contact Search** | `docs/contact-search.md` | Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination |
 | **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 

package/dist/docs/portal-auth-broadcast.md

@@ -1,6 +1,12 @@
 # Publishing Auth State to the Portal
 
-> **For sub-app authors.** This guide explains how to broadcast authentication state changes to the portal so the header, account UI, and sibling apps stay in sync.
+> **⚠️ Read [`portal-request-login.md`](./portal-request-login.md) first.**
+> The recommended pattern for "I need a logged-in user before I continue"
+> is `requestLogin` — the sub-app asks the portal to run its standard
+> AuthKit flow and awaits a result. This doc covers the *other* case:
+> a sub-app that runs its **own** authentication flow and needs to
+> publish the resulting session up to the portal so the header, account
+> UI, and sibling apps stay in sync.
 
 A SmartLinks micro-app may need to run its own custom authentication flow —
 typical cases: an auction app that calls a bidder API, a competition app
@@ -11,6 +17,7 @@ app pick up the new session.
 
 This doc describes the contract the portal framework already implements.
 
+
 ---
 
 ## Container / Widget Apps (Same React Tree)
@@ -52,18 +59,28 @@ function BidButton() {
 
 ## Iframe Apps (Cross-Origin)
 
-Iframe apps don't share React context. Post messages directly from the
-iframe to its parent — the portal's `IframeResponder` listens for these:
+Iframe apps don't share React context with the portal. They publish their
+session by posting framework-recognised messages on `window.parent`. The
+portal's `IframeResponder` listens for these and routes them into the same
+`login` / `logout` calls the built-in `AuthModal` makes.
+
+> **Note:** There is no `authKit.publishLogin` / `publishLogout` helper in
+> the SmartLinks SDK today. Use the raw `postMessage` calls below. If a
+> helper ships later it will wrap exactly these payloads.
 
 ```ts
-// LOGIN
+// LOGIN — after your custom auth flow returns a token + user
 window.parent.postMessage({
   _smartlinksIframeMessage: true,
   type: 'smartlinks:authkit:login',
   payload: {
     token: '<bearer>',
-    user: { uid: 'usr_123', email: 'bidder@example.com', displayName: 'Jane' },
-    accountData: { /* optional */ },
+    user: {
+      uid: 'usr_123',
+      email: 'bidder@example.com',
+      displayName: 'Jane Bidder',
+    },
+    accountData: { tier: 'gold' }, // optional, free-form
   },
 }, '*');
 
@@ -114,8 +131,9 @@ through the standard portal UI.
    wiped.
 
 ❌ Implementing logout by just clearing your own state. Always call
-   `useAuth().logout()` (container/widget) or post `smartlinks:authkit:logout`
-   (iframe) so the whole portal session ends cleanly.
+   `useAuth().logout()` (container/widget) or post the
+   `smartlinks:authkit:logout` message (iframe) so the whole portal
+   session ends cleanly.
 
 ---
 

package/dist/docs/portal-back-button.md

@@ -1,20 +1,36 @@
-# Portal Back Button
+# Portal Back Button — "Up" Navigation Inside Sub-Apps
 
-> **For sub-app authors.** This guide explains how to make the portal's top back button behave like hierarchy-aware "up" navigation inside an embedded app.
+> **For sub-app authors.** Drop this file into the SmartLinks SDK docs (e.g.
+> `docs/portal-back-button.md`) and link it from `routing.md` / `mpa.md` so
+> microapp authors discover it.
 
-When a SmartLinks app is embedded inside the portal shell, the shell can render a top-level back button. By default that button exits the app entirely. That is correct for flat screens, but wrong for apps with internal hierarchy such as lists, detail pages, wizards, or nested checkout flows.
+When a sub-app is embedded by a portal shell, the shell renders a top-level
+back button. By default that button **exits the app entirely** when tapped —
+which is wrong for any app with internal hierarchy (lists → detail, wizards,
+etc.).
 
-This document describes the contract for telling the portal where "up" goes from the current screen so the shell can keep the app mounted and route to the correct parent screen instead of leaving the embed.
+This document describes the contract for telling the portal where "up" goes
+from the current screen, so the top back button performs **hierarchy-aware
+"up" navigation** inside your app instead.
 
-## Why "up", not browser back
+---
 
-Browser back replays history. If a user navigates `list -> item A -> list -> item B`, browser back can yo-yo between detail and list screens in a way that feels wrong for an app chrome back button.
+## Why "up", not "back"
 
-"Up" navigates the content hierarchy instead: `item B -> list -> exit app`. It is single-direction and idempotent. Only your app's router knows that hierarchy, so the portal cannot infer it on its own.
+Browser back replays history. If a user navigates **list → item A → list →
+item B**, browser back yo-yos:  `B → list → A → list → ...`. That is not what
+users expect from an "up arrow" in app chrome.
 
-## The contract
+"Up" navigates the **content hierarchy**:  `B → list → exit app`. It is
+single-direction and idempotent. Only your app's router knows the hierarchy,
+so the portal can't infer it — your app must declare it.
 
-When your app posts `smartlinks-route-change` messages, include a `parentPath` field inside `state` for the current screen:
+---
+
+## The Contract
+
+With every `smartlinks-route-change` your app already posts (via
+`useDeepLinkSync` or directly), include a `parentPath` field inside `state`:
 
 ```ts
 window.parent.postMessage({
@@ -22,7 +38,8 @@ window.parent.postMessage({
   path: '/items/123',
   context: { collectionId: 'auction-2026', appId: 'auction' },
   state: {
-    parentPath: '/items',
+    parentPath: '/items',   // ← where "up" goes from /items/123
+    // ... your other app state
   },
   appId: 'auction',
 }, '*');
@@ -30,43 +47,68 @@ window.parent.postMessage({
 
 | `state.parentPath` value | Portal back-button behaviour |
 | --- | --- |
-| `'/items'` (or any string) | The portal posts `smartlinks-navigate` to the iframe with that path and keeps the app mounted. |
-| `''`, missing, or omitted | The portal falls back to the default behaviour and exits the app. |
+| `'/items'` (or any string) | Posts `smartlinks-navigate` to the iframe with that path. App stays mounted. |
+| `''` / missing / omitted   | Default: clears the active app and returns to the portal homepage. |
+
+When the portal sends the up-navigation message, your app must respond by
+navigating to that path. If you use `useDeepLinkSync` with an SDK release
+that includes the inbound `smartlinks-navigate` listener, this is automatic —
+otherwise add a listener (see "Receiving the up-message" below).
 
-The portal only uses `parentPath` when it is present on the current route. Query-string changes, tab switches, and modal state should keep the same parent path.
+---
 
-## Recommended pattern
+## Recommended sub-app pattern (React Router)
 
-Keep the hierarchy mapping close to your route definitions:
+Keep "what's above this route" co-located with your route definitions:
 
 ```ts
+// routes.ts
 const PARENTS: Record<string, (params: any) => string | null> = {
-  '/': () => null,
-  '/items': () => null,
-  '/items/:id': () => '/items',
-  '/items/:id/bid': ({ id }) => `/items/${id}`,
-  '/checkout': () => '/items',
+  '/':                () => null,           // home — back exits the app
+  '/items':           () => null,           // list — back exits the app
+  '/items/:id':       () => '/items',       // detail — back goes to list
+  '/items/:id/bid':   ({ id }) => `/items/${id}`,
+  '/checkout':        () => '/items',
 };
 
 export function getParentPath(pathname: string): string | null {
-  // Use your router's path matching here and return the parent route.
-  return null;
+  // matchPath against PARENTS keys — return parent or null
+  // (use react-router's matchPath in your real implementation)
 }
 ```
 
-Then emit `parentPath` whenever the route changes:
+```tsx
+// App.tsx
+import { useDeepLinkSync } from '@/hooks/useDeepLinkSync';
+import { getParentPath } from './routes';
+
+function App() {
+  useDeepLinkSync({
+    getParentPath: ({ pathname }) => getParentPath(pathname),
+  });
+  // ...
+}
+```
+
+If your app does not use `useDeepLinkSync`, post the message yourself:
 
 ```ts
-useDeepLinkSync({
-  getParentPath: ({ pathname }) => getParentPath(pathname),
-});
+useEffect(() => {
+  if (window.parent === window) return;
+  window.parent.postMessage({
+    type: 'smartlinks-route-change',
+    path: location.pathname,
+    context: { /* ... */ },
+    state: { parentPath: getParentPath(location.pathname) ?? '' },
+  }, '*');
+}, [location.pathname]);
 ```
 
-If you do not use `useDeepLinkSync`, post the message yourself and include `parentPath` in `state`.
+---
 
-## Receiving the up-message
+## Receiving the up-message (`smartlinks-navigate`)
 
-When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to the iframe:
+When the portal back button consumes a `parentPath`, it posts:
 
 ```ts
 {
@@ -78,18 +120,68 @@ When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to th
 }
 ```
 
-Your app should listen for that message and route accordingly. If your SDK release already includes the inbound `smartlinks-navigate` listener, this can be automatic; otherwise add a small `message` listener and call your router manually.
+Your app must listen for this and route accordingly. A minimal hook:
+
+```ts
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+
+export function useParentNavigation() {
+  const navigate = useNavigate();
+  useEffect(() => {
+    const onMessage = (e: MessageEvent) => {
+      if (e.data?.type !== 'smartlinks-navigate') return;
+      if (typeof e.data.path !== 'string') return;
+      navigate(e.data.path);
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [navigate]);
+}
+```
+
+---
+
+## Reference: Updated `RouteChangeMessage`
+
+`state` is an open `Record<string, string>` — `parentPath` is a recognised
+optional convention; everything else flows through unchanged.
+
+```ts
+interface RouteChangeMessage {
+  type: 'smartlinks-route-change';
+  path: string;
+  context: Record<string, string>;
+  state: Record<string, string> & {
+    /**
+     * Optional. The "up" target from the current screen. When present, the
+     * portal's top back button posts smartlinks-navigate with this path
+     * instead of exiting the app. Empty / missing → exits the app.
+     */
+    parentPath?: string;
+  };
+  appId?: string;
+}
+```
 
-## Reference
+No breaking change: existing apps that don't emit `parentPath` keep today's
+behaviour (one tap of the portal back exits the app).
 
-`state` remains a general `Record<string, string>`. `parentPath` is a recognised optional convention, not a breaking protocol change.
+---
 
 ## FAQ
 
-**Do I need to push every query-param change as a navigation step?** No. `parentPath` is hierarchy, not history.
+**Q: Do I need to push every query-param change as a navigation step?**
+No. `parentPath` is hierarchy, not history. A filter toggle, a tab switch,
+or a modal open on the same screen should keep the same `parentPath`.
 
-**What if my up target leaves the app?** Set `parentPath` to `''` or omit it.
+**Q: What if my "up" leaves the app?**
+Set `parentPath` to `''` (or omit it). The portal will exit the app on back.
 
-**Can I disable the portal back button on certain screens?** Not via this protocol. Use the existing `homeScope: 'entry'` portal behaviour if you need the shell back button suppressed.
+**Q: Can I disable the portal back button on certain screens?**
+Not directly via this protocol. Use the existing portal `homeScope: 'entry'`
+mechanism if you need the entire portal back button suppressed.
 
-**What about an in-app back button?** Keep it if you want. The portal back is shell chrome; an in-content back is part of the app UI.
+**Q: What about the in-app back button I already render?**
+Keep it if you want — they're not mutually exclusive. The portal back is
+chrome; an in-content back is content. Many apps will only need one.