@proveanything/smartlinks 1.13.13 → 1.13.14

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.14  |  Generated: 2026-05-15T11:37:00.944Z
 
 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,7 @@ 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
 
 ---
 
@@ -316,4 +317,5 @@ 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
 - [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 |
@@ -86,6 +87,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-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.14  |  Generated: 2026-05-15T11:37:00.944Z
 
 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,7 @@ 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
 
 ---
 
@@ -316,4 +317,5 @@ 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
 - [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 |
@@ -86,6 +87,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-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.14",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",