@proveanything/smartlinks 1.13.13 → 1.13.15

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.13  |  Generated: 2026-05-15T11:06:27.909Z
+Version: 1.13.15  |  Generated: 2026-05-15T14:02:11.202Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5140,7 +5140,9 @@ interface RouteChangeMessage {
   type: 'smartlinks-route-change';
   path: string;
   context: Record<string, string>;
-  state: Record<string, string>;
+  state: Record<string, string> & {
+  parentPath?: string;
+  };
   appId?: string;
 }
 ```

package/dist/docs/building-react-components.md

@@ -308,6 +308,8 @@ Now that you understand the core concepts, see the implementation guides:
 - **[containers.md](./containers.md)** — Build full-page embedded experiences
 - **[mpa.md](./mpa.md)** — Multi-page app architecture (optional)
 - **[iframe-responder.md](./iframe-responder.md)** — Parent-side iframe integration
+- **[portal-back-button.md](./portal-back-button.md)** — Embedded-app "up" navigation and portal back-button behaviour
+- **[portal-auth-broadcast.md](./portal-auth-broadcast.md)** — Publishing custom auth flows to the portal
 
 ---
 
@@ -316,4 +318,6 @@ Now that you understand the core concepts, see the implementation guides:
 - [theme.system.md](./theme.system.md) — Theming and CSS variables
 - [ai.md](./ai.md) — AI assistant integration
 - [deep-link-discovery.md](./deep-link-discovery.md) — Deep linking patterns
+- [portal-back-button.md](./portal-back-button.md) — Portal shell back-button behavior for hierarchical embeds
+- [portal-auth-broadcast.md](./portal-auth-broadcast.md) — Custom authentication and session broadcast
 - [manifests.md](./manifests.md) — App manifest configuration

package/dist/docs/iframe-responder.md

@@ -141,6 +141,8 @@ const responder = new smartlinks.IframeResponder({
 });
 ```
 
+If your app has hierarchical screens, include `state.parentPath` in each `smartlinks-route-change` message so the portal shell can treat its top back button as "up" navigation instead of exiting the embed. See the [Portal Back Button guide](portal-back-button.md) for the contract and recommended router pattern.
+
 ### Local Development Override
 
 ```typescript
@@ -377,7 +379,7 @@ The responder handles these message types from the iframe:
   type: 'smartlinks-route-change',
   path: '/products/wine-123',
   context: { collectionId: 'acme-wines', appId: 'warranty' },
-  state: { tab: 'details' }
+  state: { tab: 'details', parentPath: '/products' }
 }
 ```
 
@@ -439,6 +441,7 @@ import type {
 5. **Validate tokens** server-side for security
 6. **Set height dynamically** based on content using `onResize`
 7. **Sync routes** with parent navigation for better UX
+8. **Set `parentPath`** for routes that have a meaningful parent screen in the app hierarchy
 
 ## Troubleshooting
 
@@ -461,3 +464,7 @@ import type {
 - Verify cache storage option is supported (sessionStorage/localStorage)
 - Check browser storage isn't disabled
 - Clear cache and retry with `smartlinks.cache.clear()`
+
+### Portal back exits the app too early
+- Set `state.parentPath` on route changes for screens that should navigate "up" inside the app.
+- Make sure the receiving app listens for `smartlinks-navigate` if the SDK version in use does not already handle it.

package/dist/docs/mpa.md

@@ -122,6 +122,8 @@ The parent SmartLinks platform embeds apps via iframe:
 
 Context parameters (`collectionId`, `appId`, `productId`, `proofId`) are passed as URL query params and read via the iframe responder. See the [iframe Responder guide](iframe-responder.md) for the full context injection API.
 
+If the embedded app exposes nested screens, document its "up" navigation path with the [Portal Back Button guide](portal-back-button.md) so the shell's back button stays inside the app when appropriate.
+
 ---
 
 ## Related Guides
@@ -133,3 +135,4 @@ Context parameters (`collectionId`, `appId`, `productId`, `proofId`) are passed
 | [Executor Model](executor.md) | Executor bundle: SEO, LLM content, config mutations |
 | [AI-Native App Manifests](manifests.md) | How manifests wire all bundles together for AI discovery |
 | [iframe Responder](iframe-responder.md) | Reading context params inside the iframe |
+| [Portal Back Button](portal-back-button.md) | Hierarchy-aware back navigation for embedded apps |

package/dist/docs/overview.md

@@ -64,6 +64,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **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 |
 | **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 |
@@ -73,6 +74,7 @@ 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 Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
 | **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 |
 
@@ -86,6 +88,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 - **SmartLinks NPM module** — All data access and platform interaction goes through `@proveanything/smartlinks`
 - **No standalone auth** — Authentication is handled by the parent SmartLinks platform
 - **Multi-page build** — Separate bundles for public and admin — see `docs/mpa.md`
+- **Embedded back navigation** — Use `docs/portal-back-button.md` when a sub-app has a real content hierarchy
 
 ---
 

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

@@ -0,0 +1,160 @@
+# 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.
+
+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
+that exchanges a magic code for a session, a partner SSO. When that flow
+completes the app holds a `token` + `user` of its own, and the **portal**
+needs to know about it so the header, the account UI, and every sibling
+app pick up the new session.
+
+This doc describes the contract the portal framework already implements.
+
+---
+
+## Container / Widget Apps (Same React Tree)
+
+These run inside the portal's React context and share its `AuthProvider`.
+Call `useAuth()` directly:
+
+```tsx
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+
+function BidButton() {
+  const { login, logout, isAuthenticated, user } = useAuth();
+
+  async function placeBid() {
+    if (!isAuthenticated) {
+      // Run your own auth flow…
+      const { token, user, expiresAt } = await api.signInBidder(...);
+      // Publish to the portal — this is the *only* call you need:
+      await login(token, user, { source: 'auction' }, /* isNewUser */ false, expiresAt);
+    }
+    await api.placeBid(...);
+  }
+
+  return <button onClick={placeBid}>Bid</button>;
+}
+```
+
+`useAuth().login(token, user, accountData?, isNewUser?, expiresAt?)` will:
+
+- Persist the session (cookie/storage as configured).
+- Call `setBearerToken(token)` on the SDK so subsequent API calls are
+  authenticated.
+- Re-render every consumer of `useAuth()` / `useSafeAuth()` —
+  including the portal header.
+
+`useAuth().logout()` clears all of the above.
+
+---
+
+## Iframe Apps (Cross-Origin)
+
+Iframe apps don't share React context. Use the SDK's `authKit` helper —
+it posts the framework-recognised messages on `window.parent`:
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// After your custom flow succeeds:
+await authKit.publishLogin({
+  token,                // string — your API's bearer token
+  user: {               // mirrors AuthUser
+    uid: 'usr_123',
+    email: 'bidder@example.com',
+    displayName: 'Jane Bidder',
+  },
+  accountData: { tier: 'gold' }, // optional, free-form
+});
+
+// On sign-out:
+await authKit.publishLogout();
+```
+
+### Raw postMessage (fallback)
+
+If you can't use the helper (e.g. you're outside the SDK), post the raw
+messages from the iframe to its parent. The portal's `IframeResponder`
+listens for these:
+
+```ts
+// LOGIN
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:login',
+  payload: {
+    token: '<bearer>',
+    user: { uid: 'usr_123', email: 'bidder@example.com', displayName: 'Jane' },
+    accountData: { /* optional */ },
+  },
+}, '*');
+
+// LOGOUT
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:logout',
+  payload: {},
+}, '*');
+```
+
+The portal-framework's `AppIframeRenderer` translates these into:
+
+```ts
+PortalAuthProvider.login(token, user, accountData);
+// or
+PortalAuthProvider.logout();
+```
+
+— the **same** call the built-in `AuthModal` makes when the user logs in
+through the standard portal UI.
+
+---
+
+## What the Portal Does on Receipt
+
+1. Updates the `IframeResponder` cache so future context syncs carry the
+   user.
+2. Calls `PortalAuthProvider`'s bridged `login` / `logout`.
+3. `setBearerToken` runs against the parent SDK instance — your API
+   calls are now authenticated.
+4. The portal header avatar swaps in (or out).
+5. Every other container/widget/iframe app observes the new session via
+   its own `useAuth()` / context-refresh.
+
+---
+
+## Anti-Patterns
+
+❌ Storing your own auth token in `localStorage` and ignoring the portal —
+   the user will see a logged-out header above your "logged in" app.
+
+❌ Posting `smartlinks-auth-login` (with a hyphen). The correct event
+   name is `smartlinks:authkit:login` (colon-separated, namespaced).
+
+❌ Calling `setBearerToken` directly without notifying the portal —
+   your token will work until the portal next refreshes auth, then be
+   wiped.
+
+❌ Implementing logout by just clearing your own state. Always call
+   `useAuth().logout()` (container/widget) or `authKit.publishLogout()`
+   (iframe) so the whole portal session ends cleanly.
+
+---
+
+## Reading the Current Portal Session
+
+You don't need to broadcast just to *read* the session — that comes for
+free:
+
+```tsx
+// Container / widget apps
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+const { user, token, isAuthenticated } = useAuth();
+```
+
+```ts
+// Iframe apps — the IframeResponder caches the parent's user under
+// `cache.user`. Read it via the SDK's standard hooks/helpers.
+```

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

@@ -0,0 +1,95 @@
+# Portal Back Button
+
+> **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.
+
+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.
+
+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.
+
+## 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.
+
+"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.
+
+## The contract
+
+When your app posts `smartlinks-route-change` messages, include a `parentPath` field inside `state` for the current screen:
+
+```ts
+window.parent.postMessage({
+  type: 'smartlinks-route-change',
+  path: '/items/123',
+  context: { collectionId: 'auction-2026', appId: 'auction' },
+  state: {
+    parentPath: '/items',
+  },
+  appId: 'auction',
+}, '*');
+```
+
+| `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. |
+
+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
+
+Keep the hierarchy mapping close to your route definitions:
+
+```ts
+const PARENTS: Record<string, (params: any) => string | null> = {
+  '/': () => null,
+  '/items': () => null,
+  '/items/:id': () => '/items',
+  '/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;
+}
+```
+
+Then emit `parentPath` whenever the route changes:
+
+```ts
+useDeepLinkSync({
+  getParentPath: ({ pathname }) => getParentPath(pathname),
+});
+```
+
+If you do not use `useDeepLinkSync`, post the message yourself and include `parentPath` in `state`.
+
+## Receiving the up-message
+
+When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to the iframe:
+
+```ts
+{
+  type: 'smartlinks-navigate',
+  appId: 'auction',
+  path: '/items',
+  params: {},
+  target: '_self',
+}
+```
+
+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.
+
+## Reference
+
+`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.
+
+**What if my up target leaves the app?** Set `parentPath` to `''` or omit it.
+
+**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.
+
+**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.

package/dist/openapi.yaml

@@ -20564,8 +20564,9 @@ components:
             type: string
         state:
           type: object
-          additionalProperties:
-            type: string
+          additionalProperties: true
+        parentPath:
+          type: string
         appId:
           type: string
       required:

package/dist/types/iframeResponder.d.ts

@@ -38,7 +38,9 @@ export interface RouteChangeMessage {
     type: 'smartlinks-route-change';
     path: string;
     context: Record<string, string>;
-    state: Record<string, string>;
+    state: Record<string, string> & {
+        parentPath?: string;
+    };
     appId?: string;
 }
 export interface SmartlinksIframeMessage {

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.13  |  Generated: 2026-05-15T11:06:27.909Z
+Version: 1.13.15  |  Generated: 2026-05-15T14:02:11.202Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5140,7 +5140,9 @@ interface RouteChangeMessage {
   type: 'smartlinks-route-change';
   path: string;
   context: Record<string, string>;
-  state: Record<string, string>;
+  state: Record<string, string> & {
+  parentPath?: string;
+  };
   appId?: string;
 }
 ```

package/docs/building-react-components.md

@@ -308,6 +308,8 @@ Now that you understand the core concepts, see the implementation guides:
 - **[containers.md](./containers.md)** — Build full-page embedded experiences
 - **[mpa.md](./mpa.md)** — Multi-page app architecture (optional)
 - **[iframe-responder.md](./iframe-responder.md)** — Parent-side iframe integration
+- **[portal-back-button.md](./portal-back-button.md)** — Embedded-app "up" navigation and portal back-button behaviour
+- **[portal-auth-broadcast.md](./portal-auth-broadcast.md)** — Publishing custom auth flows to the portal
 
 ---
 
@@ -316,4 +318,6 @@ Now that you understand the core concepts, see the implementation guides:
 - [theme.system.md](./theme.system.md) — Theming and CSS variables
 - [ai.md](./ai.md) — AI assistant integration
 - [deep-link-discovery.md](./deep-link-discovery.md) — Deep linking patterns
+- [portal-back-button.md](./portal-back-button.md) — Portal shell back-button behavior for hierarchical embeds
+- [portal-auth-broadcast.md](./portal-auth-broadcast.md) — Custom authentication and session broadcast
 - [manifests.md](./manifests.md) — App manifest configuration

package/docs/iframe-responder.md

@@ -141,6 +141,8 @@ const responder = new smartlinks.IframeResponder({
 });
 ```
 
+If your app has hierarchical screens, include `state.parentPath` in each `smartlinks-route-change` message so the portal shell can treat its top back button as "up" navigation instead of exiting the embed. See the [Portal Back Button guide](portal-back-button.md) for the contract and recommended router pattern.
+
 ### Local Development Override
 
 ```typescript
@@ -377,7 +379,7 @@ The responder handles these message types from the iframe:
   type: 'smartlinks-route-change',
   path: '/products/wine-123',
   context: { collectionId: 'acme-wines', appId: 'warranty' },
-  state: { tab: 'details' }
+  state: { tab: 'details', parentPath: '/products' }
 }
 ```
 
@@ -439,6 +441,7 @@ import type {
 5. **Validate tokens** server-side for security
 6. **Set height dynamically** based on content using `onResize`
 7. **Sync routes** with parent navigation for better UX
+8. **Set `parentPath`** for routes that have a meaningful parent screen in the app hierarchy
 
 ## Troubleshooting
 
@@ -461,3 +464,7 @@ import type {
 - Verify cache storage option is supported (sessionStorage/localStorage)
 - Check browser storage isn't disabled
 - Clear cache and retry with `smartlinks.cache.clear()`
+
+### Portal back exits the app too early
+- Set `state.parentPath` on route changes for screens that should navigate "up" inside the app.
+- Make sure the receiving app listens for `smartlinks-navigate` if the SDK version in use does not already handle it.

package/docs/mpa.md

@@ -122,6 +122,8 @@ The parent SmartLinks platform embeds apps via iframe:
 
 Context parameters (`collectionId`, `appId`, `productId`, `proofId`) are passed as URL query params and read via the iframe responder. See the [iframe Responder guide](iframe-responder.md) for the full context injection API.
 
+If the embedded app exposes nested screens, document its "up" navigation path with the [Portal Back Button guide](portal-back-button.md) so the shell's back button stays inside the app when appropriate.
+
 ---
 
 ## Related Guides
@@ -133,3 +135,4 @@ Context parameters (`collectionId`, `appId`, `productId`, `proofId`) are passed
 | [Executor Model](executor.md) | Executor bundle: SEO, LLM content, config mutations |
 | [AI-Native App Manifests](manifests.md) | How manifests wire all bundles together for AI discovery |
 | [iframe Responder](iframe-responder.md) | Reading context params inside the iframe |
+| [Portal Back Button](portal-back-button.md) | Hierarchy-aware back navigation for embedded apps |

package/docs/overview.md

@@ -64,6 +64,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **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 |
 | **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 |
@@ -73,6 +74,7 @@ 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 Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
 | **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 |
 
@@ -86,6 +88,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 - **SmartLinks NPM module** — All data access and platform interaction goes through `@proveanything/smartlinks`
 - **No standalone auth** — Authentication is handled by the parent SmartLinks platform
 - **Multi-page build** — Separate bundles for public and admin — see `docs/mpa.md`
+- **Embedded back navigation** — Use `docs/portal-back-button.md` when a sub-app has a real content hierarchy
 
 ---
 

package/docs/portal-auth-broadcast.md

@@ -0,0 +1,160 @@
+# 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.
+
+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
+that exchanges a magic code for a session, a partner SSO. When that flow
+completes the app holds a `token` + `user` of its own, and the **portal**
+needs to know about it so the header, the account UI, and every sibling
+app pick up the new session.
+
+This doc describes the contract the portal framework already implements.
+
+---
+
+## Container / Widget Apps (Same React Tree)
+
+These run inside the portal's React context and share its `AuthProvider`.
+Call `useAuth()` directly:
+
+```tsx
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+
+function BidButton() {
+  const { login, logout, isAuthenticated, user } = useAuth();
+
+  async function placeBid() {
+    if (!isAuthenticated) {
+      // Run your own auth flow…
+      const { token, user, expiresAt } = await api.signInBidder(...);
+      // Publish to the portal — this is the *only* call you need:
+      await login(token, user, { source: 'auction' }, /* isNewUser */ false, expiresAt);
+    }
+    await api.placeBid(...);
+  }
+
+  return <button onClick={placeBid}>Bid</button>;
+}
+```
+
+`useAuth().login(token, user, accountData?, isNewUser?, expiresAt?)` will:
+
+- Persist the session (cookie/storage as configured).
+- Call `setBearerToken(token)` on the SDK so subsequent API calls are
+  authenticated.
+- Re-render every consumer of `useAuth()` / `useSafeAuth()` —
+  including the portal header.
+
+`useAuth().logout()` clears all of the above.
+
+---
+
+## Iframe Apps (Cross-Origin)
+
+Iframe apps don't share React context. Use the SDK's `authKit` helper —
+it posts the framework-recognised messages on `window.parent`:
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// After your custom flow succeeds:
+await authKit.publishLogin({
+  token,                // string — your API's bearer token
+  user: {               // mirrors AuthUser
+    uid: 'usr_123',
+    email: 'bidder@example.com',
+    displayName: 'Jane Bidder',
+  },
+  accountData: { tier: 'gold' }, // optional, free-form
+});
+
+// On sign-out:
+await authKit.publishLogout();
+```
+
+### Raw postMessage (fallback)
+
+If you can't use the helper (e.g. you're outside the SDK), post the raw
+messages from the iframe to its parent. The portal's `IframeResponder`
+listens for these:
+
+```ts
+// LOGIN
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:login',
+  payload: {
+    token: '<bearer>',
+    user: { uid: 'usr_123', email: 'bidder@example.com', displayName: 'Jane' },
+    accountData: { /* optional */ },
+  },
+}, '*');
+
+// LOGOUT
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:logout',
+  payload: {},
+}, '*');
+```
+
+The portal-framework's `AppIframeRenderer` translates these into:
+
+```ts
+PortalAuthProvider.login(token, user, accountData);
+// or
+PortalAuthProvider.logout();
+```
+
+— the **same** call the built-in `AuthModal` makes when the user logs in
+through the standard portal UI.
+
+---
+
+## What the Portal Does on Receipt
+
+1. Updates the `IframeResponder` cache so future context syncs carry the
+   user.
+2. Calls `PortalAuthProvider`'s bridged `login` / `logout`.
+3. `setBearerToken` runs against the parent SDK instance — your API
+   calls are now authenticated.
+4. The portal header avatar swaps in (or out).
+5. Every other container/widget/iframe app observes the new session via
+   its own `useAuth()` / context-refresh.
+
+---
+
+## Anti-Patterns
+
+❌ Storing your own auth token in `localStorage` and ignoring the portal —
+   the user will see a logged-out header above your "logged in" app.
+
+❌ Posting `smartlinks-auth-login` (with a hyphen). The correct event
+   name is `smartlinks:authkit:login` (colon-separated, namespaced).
+
+❌ Calling `setBearerToken` directly without notifying the portal —
+   your token will work until the portal next refreshes auth, then be
+   wiped.
+
+❌ Implementing logout by just clearing your own state. Always call
+   `useAuth().logout()` (container/widget) or `authKit.publishLogout()`
+   (iframe) so the whole portal session ends cleanly.
+
+---
+
+## Reading the Current Portal Session
+
+You don't need to broadcast just to *read* the session — that comes for
+free:
+
+```tsx
+// Container / widget apps
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+const { user, token, isAuthenticated } = useAuth();
+```
+
+```ts
+// Iframe apps — the IframeResponder caches the parent's user under
+// `cache.user`. Read it via the SDK's standard hooks/helpers.
+```

package/docs/portal-back-button.md

@@ -0,0 +1,95 @@
+# Portal Back Button
+
+> **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.
+
+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.
+
+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.
+
+## 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.
+
+"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.
+
+## The contract
+
+When your app posts `smartlinks-route-change` messages, include a `parentPath` field inside `state` for the current screen:
+
+```ts
+window.parent.postMessage({
+  type: 'smartlinks-route-change',
+  path: '/items/123',
+  context: { collectionId: 'auction-2026', appId: 'auction' },
+  state: {
+    parentPath: '/items',
+  },
+  appId: 'auction',
+}, '*');
+```
+
+| `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. |
+
+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
+
+Keep the hierarchy mapping close to your route definitions:
+
+```ts
+const PARENTS: Record<string, (params: any) => string | null> = {
+  '/': () => null,
+  '/items': () => null,
+  '/items/:id': () => '/items',
+  '/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;
+}
+```
+
+Then emit `parentPath` whenever the route changes:
+
+```ts
+useDeepLinkSync({
+  getParentPath: ({ pathname }) => getParentPath(pathname),
+});
+```
+
+If you do not use `useDeepLinkSync`, post the message yourself and include `parentPath` in `state`.
+
+## Receiving the up-message
+
+When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to the iframe:
+
+```ts
+{
+  type: 'smartlinks-navigate',
+  appId: 'auction',
+  path: '/items',
+  params: {},
+  target: '_self',
+}
+```
+
+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.
+
+## Reference
+
+`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.
+
+**What if my up target leaves the app?** Set `parentPath` to `''` or omit it.
+
+**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.
+
+**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.

package/openapi.yaml

@@ -20564,8 +20564,9 @@ components:
             type: string
         state:
           type: object
-          additionalProperties:
-            type: string
+          additionalProperties: true
+        parentPath:
+          type: string
         appId:
           type: string
       required:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.13.13",
+  "version": "1.13.15",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",