@proveanything/smartlinks 1.4.5 → 1.4.7

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.4.5  |  Generated: 2026-02-21T09:35:56.076Z
+Version: 1.4.7  |  Generated: 2026-02-21T14:49:14.374Z
 
 This is a concise summary of all available API functions and types.
 
@@ -869,28 +869,14 @@ interface AppContainerComponent {
 }
 ```
 
-**AppManifest** (interface)
+**AppAdminConfig** (interface)
 ```typescript
-interface AppManifest {
+interface AppAdminConfig {
   $schema?: string;
-  meta?: {
-  name: string;
-  description?: string;
-  version: string;
-  platformRevision?: string;
-  appId: string;
-  };
-  * Filename of the admin configuration JSON (e.g. "app.admin.json").
-  * Present when the app ships an admin UI config.
-  admin?: string;
-  widgets?: {
-  files: AppManifestFiles;
-  components: AppWidgetComponent[];
-  };
-  containers?: {
-  files: AppManifestFiles;
-  components: AppContainerComponent[];
-  };
+  * Path (relative to the app's public root) to an AI guide markdown file.
+  * Provides natural-language context for AI-assisted configuration.
+  * @example "ai-guide.md"
+  aiGuide?: string;
   setup?: {
   description?: string;
   questions?: Array<{
@@ -944,6 +930,33 @@ interface AppManifest {
   interactions?: Array<{ id: string; description?: string }>;
   kpis?: Array<{ name: string; compute?: string }>;
   };
+}
+```
+
+**AppManifest** (interface)
+```typescript
+interface AppManifest {
+  $schema?: string;
+  meta?: {
+  name: string;
+  description?: string;
+  version: string;
+  platformRevision?: string;
+  appId: string;
+  };
+  * Relative path to the admin configuration file (e.g. `"app.admin.json"`).
+  * When present, fetch this file to get the full {@link AppAdminConfig}
+  * (setup questions, import schema, tunable fields, metrics definitions).
+  * Absent when the app has no admin UI.
+  admin?: string;
+  widgets?: {
+  files: AppManifestFiles;
+  components: AppWidgetComponent[];
+  };
+  containers?: {
+  files: AppManifestFiles;
+  components: AppContainerComponent[];
+  };
   [key: string]: any;
 }
 ```

package/dist/docs/containers.md

@@ -47,7 +47,7 @@ All standard widget props apply:
 | `productId`       | string         | ❌       | Product context                         |
 | `proofId`         | string         | ❌       | Proof context                           |
 | `user`            | object         | ❌       | Current user info                       |
-| `onNavigate`      | function       | ❌       | Navigation callback                     |
+| `onNavigate`      | function       | ❌       | Navigation callback (accepts `NavigationRequest` or legacy string) |
 | `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
 | `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |
 | `translations`    | object         | ❌       | Translation overrides                   |
@@ -55,6 +55,67 @@ All standard widget props apply:
 
 ---
 
+## Cross-App Navigation
+
+Containers support the same **structured navigation requests** as widgets. When a container needs to navigate to another app within the portal, it emits a `NavigationRequest` via the `onNavigate` callback. The portal orchestrator interprets the request, preserves hierarchy context, and performs the navigation.
+
+### NavigationRequest
+
+```typescript
+interface NavigationRequest {
+  /** Target app ID to activate */
+  appId: string;
+  /** Deep link / page within the target app (forwarded as pageId) */
+  deepLink?: string;
+  /** Extra params forwarded to the target app */
+  params?: Record<string, string>;
+  /** Optionally switch to a specific product before showing the app */
+  productId?: string;
+  /** Optionally switch to a specific proof before showing the app */
+  proofId?: string;
+}
+```
+
+### Usage in Containers
+
+```typescript
+// Inside a container component
+const handleNavigateToWarranty = () => {
+  onNavigate?.({
+    appId: 'warranty-app',
+    deepLink: 'register',
+    params: { source: 'product-page' },
+  });
+};
+
+// Switch product context and open an app
+const handleViewRelatedProduct = (productId: string) => {
+  onNavigate?.({
+    appId: 'product-info',
+    productId,
+  });
+};
+```
+
+### How It Works
+
+```text
+Container button "Register Warranty"
+  → onNavigate({ appId: 'warranty', deepLink: 'register', params: { ref: 'container' } })
+  → Portal orchestrator receives NavigationRequest
+  → Calls actions.navigateToApp('warranty', 'register')
+  → Target app loads with extraParams: { pageId: 'register', ref: 'container' }
+  → collectionId, productId, proofId, theme all preserved automatically
+```
+
+### Backward Compatibility
+
+The `onNavigate` callback accepts both structured `NavigationRequest` objects and legacy strings. Existing containers that call `onNavigate('/some-path')` continue to work. **New containers should always use the structured `NavigationRequest` format.**
+
+See `widgets.md` for the full `NavigationRequest` documentation and additional examples.
+
+---
+
 ## Architecture
 
 Containers use **MemoryRouter** (not HashRouter) because the parent app owns the browser's URL bar. Context is passed via props rather than URL parameters. Each container gets its own `QueryClient` to avoid cache collisions with the parent app.
@@ -83,7 +144,10 @@ const { PublicContainer } = await import('https://my-app.com/containers.es.js');
   appId="my-app"
   productId="prod-123"
   SL={SL}
-  onNavigate={handleNavigate}
+  onNavigate={(request) => {
+    // The portal orchestrator handles NavigationRequest objects
+    // automatically when using ContentOrchestrator / OrchestratedPortal
+  }}
   lang="en"
   className="max-w-4xl mx-auto"
 />
@@ -184,6 +248,7 @@ src/containers/
 | **Styling**       | Fully isolated CSS                | Inherits parent CSS variables      |
 | **Communication** | postMessage                       | Direct props / callbacks           |
 | **Auth**          | Via `SL.auth.getAccount()`        | Via `user` prop from parent        |
+| **Navigation**    | `window.parent.postMessage`       | `onNavigate` with `NavigationRequest` |
 
 ---
 
@@ -196,3 +261,4 @@ src/containers/
 | Routing doesn't work       | Using HashRouter instead of MemoryRouter | Containers must use MemoryRouter                     |
 | Query cache conflicts      | Sharing parent's QueryClient             | Each container needs its own `QueryClient` instance  |
 | `cva.cva` runtime error    | Global set to lowercase `cva`            | Use uppercase `CVA` for the global name              |
+| Navigation does nothing    | Using legacy string with `onNavigate`    | Use structured `NavigationRequest` object instead    |

package/dist/docs/widgets.md

@@ -10,7 +10,7 @@ Widgets are self-contained React components that:
 - Run inside the parent React application (not iframes)
 - Receive standardized context props
 - Inherit styling from the parent via CSS variables
-- Can trigger navigation to the full app
+- Can trigger structured cross-app navigation within the parent portal
 
 ```text
 ┌─────────────────────────────────────────────────────────────────┐
@@ -18,8 +18,8 @@ Widgets are self-contained React components that:
 │                                                                 │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
 │  │ Competition  │  │ Music App    │  │ Warranty     │          │
-│  │ Widget       │  │ Widget       │  │ Widget       │          │
-│  │ (ESM import) │  │ (ESM import) │  │ (ESM import) │          │
+│  │ Widget       │  │ (ESM import) │  │ Widget       │          │
+│  │ (ESM import) │  │              │  │ (ESM import) │          │
 │  └──────────────┘  └──────────────┘  └──────────────┘          │
 │         ↑                 ↑                 ↑                   │
 │         │                 │                 │                   │
@@ -56,7 +56,7 @@ interface SmartLinksWidgetProps {
   SL: typeof import('@proveanything/smartlinks');
   
   // Callback to navigate within the parent application
-  onNavigate?: (path: string) => void;
+  onNavigate?: (request: NavigationRequest | string) => void;
   
   // Base URL to the full public portal for deep linking
   publicPortalUrl?: string;
@@ -80,22 +80,102 @@ interface SmartLinksWidgetProps {
 | `proofId` | `string?` | Optional proof context |
 | `user` | `object?` | Current user info if authenticated |
 | `SL` | `typeof SL` | Pre-initialized SmartLinks SDK |
-| `onNavigate` | `function?` | Callback to navigate within parent app |
+| `onNavigate` | `function?` | Callback to navigate within parent app (accepts `NavigationRequest` or legacy string) |
 | `publicPortalUrl` | `string?` | Base URL to full portal for deep links |
 | `size` | `string?` | Size hint: 'compact', 'standard', or 'large' |
 | `lang` | `string?` | Language code (e.g., 'en', 'de', 'fr') |
 | `translations` | `object?` | Translation overrides |
 
-### Navigation: onNavigate vs publicPortalUrl
+---
+
+## Cross-App Navigation
+
+Widgets can navigate to other apps within the portal using **structured navigation requests**. This allows a widget to say "open app X with these parameters" without knowing the portal's URL structure or hierarchy state. The portal orchestrator receives the request, preserves the current context (collection, product, proof, theme, auth), and performs the actual navigation.
+
+### NavigationRequest
+
+```typescript
+interface NavigationRequest {
+  /** Target app ID to activate */
+  appId: string;
+  /** Deep link / page within the target app (forwarded as pageId) */
+  deepLink?: string;
+  /** Extra params forwarded to the target app (e.g. { campaignId: '123' }) */
+  params?: Record<string, string>;
+  /** Optionally switch to a specific product before showing the app */
+  productId?: string;
+  /** Optionally switch to a specific proof before showing the app */
+  proofId?: string;
+}
+```
+
+### Usage Examples
+
+```typescript
+const MyWidget: React.FC<SmartLinksWidgetProps> = ({ onNavigate, ...props }) => {
+
+  // Navigate to another app, keeping current context
+  const handleEnterCompetition = () => {
+    onNavigate?.({
+      appId: 'competition-app',
+      deepLink: 'enter',
+      params: { campaignId: '123', ref: 'widget' },
+    });
+  };
+
+  // Navigate to a specific product's app
+  const handleViewProduct = (productId: string) => {
+    onNavigate?.({
+      appId: 'product-info',
+      productId,
+    });
+  };
+
+  // Navigate to a proof-level app
+  const handleViewWarranty = (proofId: string) => {
+    onNavigate?.({
+      appId: 'warranty-app',
+      proofId,
+      productId: 'prod-123', // required when jumping to proof level
+    });
+  };
+
+  return (
+    <Card>
+      <Button onClick={handleEnterCompetition}>Enter Competition</Button>
+      <Button onClick={() => handleViewProduct('prod-456')}>View Product</Button>
+    </Card>
+  );
+};
+```
+
+### How It Works End-to-End
+
+```text
+Widget clicks "Enter Competition"
+  → onNavigate({ appId: 'competition', deepLink: 'enter', params: { ref: 'widget' } })
+  → Portal orchestrator receives NavigationRequest
+  → Calls actions.navigateToApp('competition', 'enter')
+  → Orchestrator renders the target app with extraParams: { pageId: 'enter', ref: 'widget' }
+  → Current collectionId, productId, proofId, theme all preserved automatically
+```
+
+### Backward Compatibility
+
+The `onNavigate` callback accepts both structured `NavigationRequest` objects and legacy strings. Existing widgets that call `onNavigate('/some-path')` continue to work — the portal treats plain strings as legacy no-ops and logs them for debugging.
+
+**New widgets should always use the structured `NavigationRequest` format.**
+
+### onNavigate vs publicPortalUrl
 
 Widgets support two navigation patterns:
 
-**`onNavigate` (parent-controlled)**
-- Parent provides a callback to handle navigation
-- Widget passes a relative path (e.g., `/#/?collectionId=x&tab=details`)
-- Parent decides what to do (router push, open modal, etc.)
+**`onNavigate` (parent-controlled, recommended)**
+- Parent provides a callback that the orchestrator interprets
+- Widget emits a structured `NavigationRequest`
+- Portal handles hierarchy transitions, context preservation, and routing
 
-**`publicPortalUrl` (direct redirect)**
+**`publicPortalUrl` (direct redirect, escape hatch)**
 - Widget knows the full URL to the public portal
 - Uses `SL.iframe.redirectParent()` for navigation
 - Automatically handles iframe escape via postMessage
@@ -104,16 +184,17 @@ Widgets support two navigation patterns:
 **Priority:** If both are provided, `onNavigate` takes precedence.
 
 ```typescript
-// Parent provides callback
+// Recommended: structured navigation
 <MyWidget
-  onNavigate={(path) => router.push(path)}
-  // ...
+  onNavigate={(request) => {
+    // Portal orchestrator handles this automatically
+    // when using ContentOrchestrator / OrchestratedPortal
+  }}
 />
 
-// Widget uses direct redirect
+// Escape hatch: direct redirect
 <MyWidget
   publicPortalUrl="https://my-app.smartlinks.io"
-  // ...
 />
 ```
 
@@ -136,7 +217,6 @@ export const MyWidget: React.FC<SmartLinksWidgetProps> = ({
   user,
   SL,
   onNavigate,
-  publicPortalUrl,
   size = 'standard'
 }) => {
   // Use the SL SDK for API calls
@@ -148,19 +228,13 @@ export const MyWidget: React.FC<SmartLinksWidgetProps> = ({
     console.log('Config:', data);
   };
 
-  // Navigate to full app (supports both patterns)
-  const handleOpenApp = () => {
-    const params = new URLSearchParams({ collectionId, appId });
-    if (productId) params.set('productId', productId);
-    const relativePath = `/#/?${params.toString()}`;
-    
-    if (onNavigate) {
-      // Parent-controlled navigation
-      onNavigate(relativePath);
-    } else if (publicPortalUrl) {
-      // Direct redirect (handles iframe escape automatically)
-      SL.iframe.redirectParent(`${publicPortalUrl}${relativePath}`);
-    }
+  // Navigate to another app using structured request
+  const handleOpenFullApp = () => {
+    onNavigate?.({
+      appId,
+      deepLink: 'details',
+      params: { source: 'widget' },
+    });
   };
 
   return (
@@ -172,7 +246,7 @@ export const MyWidget: React.FC<SmartLinksWidgetProps> = ({
         <p className="text-muted-foreground mb-4">
           Widget content goes here
         </p>
-        <Button onClick={handleOpenApp}>Open App</Button>
+        <Button onClick={handleOpenFullApp}>Open App</Button>
       </CardContent>
     </Card>
   );
@@ -316,23 +390,15 @@ const CompetitionWidget = lazy(() =>
 function Portal() {
   return (
     <Suspense fallback={<WidgetSkeleton />}>
-      {/* Option 1: Parent controls navigation */}
-      <CompetitionWidget
-        collectionId="abc123"
-        appId="competition"
-        user={currentUser}
-        SL={SL}
-        onNavigate={(path) => window.open(`https://competition-app.example.com${path}`)}
-        size="standard"
-      />
-      
-      {/* Option 2: Widget handles its own navigation */}
       <CompetitionWidget
         collectionId="abc123"
         appId="competition"
         user={currentUser}
         SL={SL}
-        publicPortalUrl="https://competition-app.example.com"
+        onNavigate={(request) => {
+          // The portal orchestrator handles NavigationRequest objects
+          // automatically when using ContentOrchestrator / OrchestratedPortal
+        }}
         size="standard"
       />
     </Suspense>
@@ -411,7 +477,8 @@ Widgets use semantic class names that reference these variables:
 - ✅ Use semantic color classes for theming
 - ✅ Handle loading and error states gracefully
 - ✅ Use the provided `SL` SDK for API calls
-- ✅ Provide meaningful navigation via `onNavigate`
+- ✅ Use structured `NavigationRequest` for cross-app navigation
+- ✅ Include `params` for any extra context the target app needs
 
 ### Don'ts
 
@@ -420,6 +487,7 @@ Widgets use semantic class names that reference these variables:
 - ❌ Don't assume specific viewport sizes
 - ❌ Don't make widgets too complex (use full app for that)
 - ❌ Don't store state that should persist (use parent or SDK)
+- ❌ Don't construct portal URLs manually — use `NavigationRequest` instead
 
 ---
 
@@ -495,7 +563,7 @@ function WidgetTestPage() {
 ```
 src/widgets/
 ├── index.ts              # Main exports barrel
-├── types.ts              # SmartLinksWidgetProps and related types
+├── types.ts              # SmartLinksWidgetProps, NavigationRequest, and related types
 ├── WidgetWrapper.tsx     # Error boundary + Suspense wrapper
 └── ExampleWidget/
     ├── index.tsx         # Re-export

package/dist/types/appManifest.d.ts

@@ -6,15 +6,15 @@
  * for inline content first and fall back to loading the URL.
  *
  *   if (bundle.source) {
- *     // inline JS � create a Blob URL or inject directly
+ *     // inline JS -- create a Blob URL or inject directly
  *   } else if (bundle.js) {
  *     // load from URL
  *   }
  */
 export interface AppBundle {
-    /** URL to the JavaScript file � load if `source` is absent */
+    /** URL to the JavaScript file -- load if `source` is absent */
     js: string | null;
-    /** URL to the CSS file � load if `styles` is absent */
+    /** URL to the CSS file -- load if `styles` is absent */
     css: string | null;
     /** Inlined JavaScript source (present when server bundles it inline) */
     source?: string;
@@ -26,12 +26,12 @@ export interface AppBundle {
  */
 export interface AppManifestFiles {
     js: {
-        /** UMD bundle � used for script-tag / dynamic loading */
+        /** UMD bundle -- used for script-tag / dynamic loading */
         umd: string;
-        /** ESM bundle � used for native ES module loading */
+        /** ESM bundle -- used for native ES module loading */
         esm?: string;
     };
-    /** CSS file � absent if the bundle ships no styles */
+    /** CSS file -- absent if the bundle ships no styles */
     css?: string;
 }
 /** A single widget component defined in the manifest */
@@ -56,32 +56,22 @@ export interface AppContainerComponent {
     };
 }
 /**
- * SmartLinks App Manifest � the app.manifest.json structure.
+ * Shape of `app.admin.json` -- the separate admin configuration file pointed to
+ * by `AppManifest.admin`. Fetch this file yourself when you need setup / import /
+ * tunable / metrics details; it is not inlined in the manifest.
+ *
+ * @example
+ *   const adminUrl = new URL(manifest.admin!, appBaseUrl);
+ *   const adminConfig: AppAdminConfig = await fetch(adminUrl).then(r => r.json());
  */
-export interface AppManifest {
+export interface AppAdminConfig {
     $schema?: string;
-    meta?: {
-        name: string;
-        description?: string;
-        version: string;
-        platformRevision?: string;
-        appId: string;
-    };
     /**
-     * Filename of the admin configuration JSON (e.g. "app.admin.json").
-     * Present when the app ships an admin UI config.
+     * Path (relative to the app's public root) to an AI guide markdown file.
+     * Provides natural-language context for AI-assisted configuration.
+     * @example "ai-guide.md"
      */
-    admin?: string;
-    /** Widget bundle definition. Presence means a widget bundle exists for this app. */
-    widgets?: {
-        files: AppManifestFiles;
-        components: AppWidgetComponent[];
-    };
-    /** Container bundle definition. Presence means a container bundle exists. */
-    containers?: {
-        files: AppManifestFiles;
-        components: AppContainerComponent[];
-    };
+    aiGuide?: string;
     setup?: {
         description?: string;
         questions?: Array<{
@@ -144,6 +134,39 @@ export interface AppManifest {
             compute?: string;
         }>;
     };
+}
+/**
+ * SmartLinks App Manifest -- the app.manifest.json structure.
+ *
+ * Setup, import, tunable, and metrics configuration lives in a separate
+ * `app.admin.json` file. Use the `admin` field to locate and fetch it.
+ */
+export interface AppManifest {
+    $schema?: string;
+    meta?: {
+        name: string;
+        description?: string;
+        version: string;
+        platformRevision?: string;
+        appId: string;
+    };
+    /**
+     * Relative path to the admin configuration file (e.g. `"app.admin.json"`).
+     * When present, fetch this file to get the full {@link AppAdminConfig}
+     * (setup questions, import schema, tunable fields, metrics definitions).
+     * Absent when the app has no admin UI.
+     */
+    admin?: string;
+    /** Widget bundle definition. Presence means a widget bundle exists for this app. */
+    widgets?: {
+        files: AppManifestFiles;
+        components: AppWidgetComponent[];
+    };
+    /** Container bundle definition. Presence means a container bundle exists. */
+    containers?: {
+        files: AppManifestFiles;
+        components: AppContainerComponent[];
+    };
     [key: string]: any;
 }
 /**
@@ -152,11 +175,11 @@ export interface AppManifest {
 export interface CollectionAppWidget {
     appId: string;
     manifest: AppManifest;
-    /** Widget bundle � always present (apps without widgets are excluded from the response) */
+    /** Widget bundle -- always present (apps without widgets are excluded from the response) */
     widget: AppBundle;
-    /** Container bundle � null when the app has no containers */
+    /** Container bundle -- null when the app has no containers */
     container: AppBundle | null;
-    /** URL to the admin configuration JSON � null when the app has no admin config */
+    /** URL to the admin configuration JSON -- null when the app has no admin config */
     admin: string | null;
 }
 /**

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.4.5  |  Generated: 2026-02-21T09:35:56.076Z
+Version: 1.4.7  |  Generated: 2026-02-21T14:49:14.374Z
 
 This is a concise summary of all available API functions and types.
 
@@ -869,28 +869,14 @@ interface AppContainerComponent {
 }
 ```
 
-**AppManifest** (interface)
+**AppAdminConfig** (interface)
 ```typescript
-interface AppManifest {
+interface AppAdminConfig {
   $schema?: string;
-  meta?: {
-  name: string;
-  description?: string;
-  version: string;
-  platformRevision?: string;
-  appId: string;
-  };
-  * Filename of the admin configuration JSON (e.g. "app.admin.json").
-  * Present when the app ships an admin UI config.
-  admin?: string;
-  widgets?: {
-  files: AppManifestFiles;
-  components: AppWidgetComponent[];
-  };
-  containers?: {
-  files: AppManifestFiles;
-  components: AppContainerComponent[];
-  };
+  * Path (relative to the app's public root) to an AI guide markdown file.
+  * Provides natural-language context for AI-assisted configuration.
+  * @example "ai-guide.md"
+  aiGuide?: string;
   setup?: {
   description?: string;
   questions?: Array<{
@@ -944,6 +930,33 @@ interface AppManifest {
   interactions?: Array<{ id: string; description?: string }>;
   kpis?: Array<{ name: string; compute?: string }>;
   };
+}
+```
+
+**AppManifest** (interface)
+```typescript
+interface AppManifest {
+  $schema?: string;
+  meta?: {
+  name: string;
+  description?: string;
+  version: string;
+  platformRevision?: string;
+  appId: string;
+  };
+  * Relative path to the admin configuration file (e.g. `"app.admin.json"`).
+  * When present, fetch this file to get the full {@link AppAdminConfig}
+  * (setup questions, import schema, tunable fields, metrics definitions).
+  * Absent when the app has no admin UI.
+  admin?: string;
+  widgets?: {
+  files: AppManifestFiles;
+  components: AppWidgetComponent[];
+  };
+  containers?: {
+  files: AppManifestFiles;
+  components: AppContainerComponent[];
+  };
   [key: string]: any;
 }
 ```

package/docs/containers.md

@@ -47,7 +47,7 @@ All standard widget props apply:
 | `productId`       | string         | ❌       | Product context                         |
 | `proofId`         | string         | ❌       | Proof context                           |
 | `user`            | object         | ❌       | Current user info                       |
-| `onNavigate`      | function       | ❌       | Navigation callback                     |
+| `onNavigate`      | function       | ❌       | Navigation callback (accepts `NavigationRequest` or legacy string) |
 | `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
 | `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |
 | `translations`    | object         | ❌       | Translation overrides                   |
@@ -55,6 +55,67 @@ All standard widget props apply:
 
 ---
 
+## Cross-App Navigation
+
+Containers support the same **structured navigation requests** as widgets. When a container needs to navigate to another app within the portal, it emits a `NavigationRequest` via the `onNavigate` callback. The portal orchestrator interprets the request, preserves hierarchy context, and performs the navigation.
+
+### NavigationRequest
+
+```typescript
+interface NavigationRequest {
+  /** Target app ID to activate */
+  appId: string;
+  /** Deep link / page within the target app (forwarded as pageId) */
+  deepLink?: string;
+  /** Extra params forwarded to the target app */
+  params?: Record<string, string>;
+  /** Optionally switch to a specific product before showing the app */
+  productId?: string;
+  /** Optionally switch to a specific proof before showing the app */
+  proofId?: string;
+}
+```
+
+### Usage in Containers
+
+```typescript
+// Inside a container component
+const handleNavigateToWarranty = () => {
+  onNavigate?.({
+    appId: 'warranty-app',
+    deepLink: 'register',
+    params: { source: 'product-page' },
+  });
+};
+
+// Switch product context and open an app
+const handleViewRelatedProduct = (productId: string) => {
+  onNavigate?.({
+    appId: 'product-info',
+    productId,
+  });
+};
+```
+
+### How It Works
+
+```text
+Container button "Register Warranty"
+  → onNavigate({ appId: 'warranty', deepLink: 'register', params: { ref: 'container' } })
+  → Portal orchestrator receives NavigationRequest
+  → Calls actions.navigateToApp('warranty', 'register')
+  → Target app loads with extraParams: { pageId: 'register', ref: 'container' }
+  → collectionId, productId, proofId, theme all preserved automatically
+```
+
+### Backward Compatibility
+
+The `onNavigate` callback accepts both structured `NavigationRequest` objects and legacy strings. Existing containers that call `onNavigate('/some-path')` continue to work. **New containers should always use the structured `NavigationRequest` format.**
+
+See `widgets.md` for the full `NavigationRequest` documentation and additional examples.
+
+---
+
 ## Architecture
 
 Containers use **MemoryRouter** (not HashRouter) because the parent app owns the browser's URL bar. Context is passed via props rather than URL parameters. Each container gets its own `QueryClient` to avoid cache collisions with the parent app.
@@ -83,7 +144,10 @@ const { PublicContainer } = await import('https://my-app.com/containers.es.js');
   appId="my-app"
   productId="prod-123"
   SL={SL}
-  onNavigate={handleNavigate}
+  onNavigate={(request) => {
+    // The portal orchestrator handles NavigationRequest objects
+    // automatically when using ContentOrchestrator / OrchestratedPortal
+  }}
   lang="en"
   className="max-w-4xl mx-auto"
 />
@@ -184,6 +248,7 @@ src/containers/
 | **Styling**       | Fully isolated CSS                | Inherits parent CSS variables      |
 | **Communication** | postMessage                       | Direct props / callbacks           |
 | **Auth**          | Via `SL.auth.getAccount()`        | Via `user` prop from parent        |
+| **Navigation**    | `window.parent.postMessage`       | `onNavigate` with `NavigationRequest` |
 
 ---
 
@@ -196,3 +261,4 @@ src/containers/
 | Routing doesn't work       | Using HashRouter instead of MemoryRouter | Containers must use MemoryRouter                     |
 | Query cache conflicts      | Sharing parent's QueryClient             | Each container needs its own `QueryClient` instance  |
 | `cva.cva` runtime error    | Global set to lowercase `cva`            | Use uppercase `CVA` for the global name              |
+| Navigation does nothing    | Using legacy string with `onNavigate`    | Use structured `NavigationRequest` object instead    |

package/docs/widgets.md

@@ -10,7 +10,7 @@ Widgets are self-contained React components that:
 - Run inside the parent React application (not iframes)
 - Receive standardized context props
 - Inherit styling from the parent via CSS variables
-- Can trigger navigation to the full app
+- Can trigger structured cross-app navigation within the parent portal
 
 ```text
 ┌─────────────────────────────────────────────────────────────────┐
@@ -18,8 +18,8 @@ Widgets are self-contained React components that:
 │                                                                 │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
 │  │ Competition  │  │ Music App    │  │ Warranty     │          │
-│  │ Widget       │  │ Widget       │  │ Widget       │          │
-│  │ (ESM import) │  │ (ESM import) │  │ (ESM import) │          │
+│  │ Widget       │  │ (ESM import) │  │ Widget       │          │
+│  │ (ESM import) │  │              │  │ (ESM import) │          │
 │  └──────────────┘  └──────────────┘  └──────────────┘          │
 │         ↑                 ↑                 ↑                   │
 │         │                 │                 │                   │
@@ -56,7 +56,7 @@ interface SmartLinksWidgetProps {
   SL: typeof import('@proveanything/smartlinks');
   
   // Callback to navigate within the parent application
-  onNavigate?: (path: string) => void;
+  onNavigate?: (request: NavigationRequest | string) => void;
   
   // Base URL to the full public portal for deep linking
   publicPortalUrl?: string;
@@ -80,22 +80,102 @@ interface SmartLinksWidgetProps {
 | `proofId` | `string?` | Optional proof context |
 | `user` | `object?` | Current user info if authenticated |
 | `SL` | `typeof SL` | Pre-initialized SmartLinks SDK |
-| `onNavigate` | `function?` | Callback to navigate within parent app |
+| `onNavigate` | `function?` | Callback to navigate within parent app (accepts `NavigationRequest` or legacy string) |
 | `publicPortalUrl` | `string?` | Base URL to full portal for deep links |
 | `size` | `string?` | Size hint: 'compact', 'standard', or 'large' |
 | `lang` | `string?` | Language code (e.g., 'en', 'de', 'fr') |
 | `translations` | `object?` | Translation overrides |
 
-### Navigation: onNavigate vs publicPortalUrl
+---
+
+## Cross-App Navigation
+
+Widgets can navigate to other apps within the portal using **structured navigation requests**. This allows a widget to say "open app X with these parameters" without knowing the portal's URL structure or hierarchy state. The portal orchestrator receives the request, preserves the current context (collection, product, proof, theme, auth), and performs the actual navigation.
+
+### NavigationRequest
+
+```typescript
+interface NavigationRequest {
+  /** Target app ID to activate */
+  appId: string;
+  /** Deep link / page within the target app (forwarded as pageId) */
+  deepLink?: string;
+  /** Extra params forwarded to the target app (e.g. { campaignId: '123' }) */
+  params?: Record<string, string>;
+  /** Optionally switch to a specific product before showing the app */
+  productId?: string;
+  /** Optionally switch to a specific proof before showing the app */
+  proofId?: string;
+}
+```
+
+### Usage Examples
+
+```typescript
+const MyWidget: React.FC<SmartLinksWidgetProps> = ({ onNavigate, ...props }) => {
+
+  // Navigate to another app, keeping current context
+  const handleEnterCompetition = () => {
+    onNavigate?.({
+      appId: 'competition-app',
+      deepLink: 'enter',
+      params: { campaignId: '123', ref: 'widget' },
+    });
+  };
+
+  // Navigate to a specific product's app
+  const handleViewProduct = (productId: string) => {
+    onNavigate?.({
+      appId: 'product-info',
+      productId,
+    });
+  };
+
+  // Navigate to a proof-level app
+  const handleViewWarranty = (proofId: string) => {
+    onNavigate?.({
+      appId: 'warranty-app',
+      proofId,
+      productId: 'prod-123', // required when jumping to proof level
+    });
+  };
+
+  return (
+    <Card>
+      <Button onClick={handleEnterCompetition}>Enter Competition</Button>
+      <Button onClick={() => handleViewProduct('prod-456')}>View Product</Button>
+    </Card>
+  );
+};
+```
+
+### How It Works End-to-End
+
+```text
+Widget clicks "Enter Competition"
+  → onNavigate({ appId: 'competition', deepLink: 'enter', params: { ref: 'widget' } })
+  → Portal orchestrator receives NavigationRequest
+  → Calls actions.navigateToApp('competition', 'enter')
+  → Orchestrator renders the target app with extraParams: { pageId: 'enter', ref: 'widget' }
+  → Current collectionId, productId, proofId, theme all preserved automatically
+```
+
+### Backward Compatibility
+
+The `onNavigate` callback accepts both structured `NavigationRequest` objects and legacy strings. Existing widgets that call `onNavigate('/some-path')` continue to work — the portal treats plain strings as legacy no-ops and logs them for debugging.
+
+**New widgets should always use the structured `NavigationRequest` format.**
+
+### onNavigate vs publicPortalUrl
 
 Widgets support two navigation patterns:
 
-**`onNavigate` (parent-controlled)**
-- Parent provides a callback to handle navigation
-- Widget passes a relative path (e.g., `/#/?collectionId=x&tab=details`)
-- Parent decides what to do (router push, open modal, etc.)
+**`onNavigate` (parent-controlled, recommended)**
+- Parent provides a callback that the orchestrator interprets
+- Widget emits a structured `NavigationRequest`
+- Portal handles hierarchy transitions, context preservation, and routing
 
-**`publicPortalUrl` (direct redirect)**
+**`publicPortalUrl` (direct redirect, escape hatch)**
 - Widget knows the full URL to the public portal
 - Uses `SL.iframe.redirectParent()` for navigation
 - Automatically handles iframe escape via postMessage
@@ -104,16 +184,17 @@ Widgets support two navigation patterns:
 **Priority:** If both are provided, `onNavigate` takes precedence.
 
 ```typescript
-// Parent provides callback
+// Recommended: structured navigation
 <MyWidget
-  onNavigate={(path) => router.push(path)}
-  // ...
+  onNavigate={(request) => {
+    // Portal orchestrator handles this automatically
+    // when using ContentOrchestrator / OrchestratedPortal
+  }}
 />
 
-// Widget uses direct redirect
+// Escape hatch: direct redirect
 <MyWidget
   publicPortalUrl="https://my-app.smartlinks.io"
-  // ...
 />
 ```
 
@@ -136,7 +217,6 @@ export const MyWidget: React.FC<SmartLinksWidgetProps> = ({
   user,
   SL,
   onNavigate,
-  publicPortalUrl,
   size = 'standard'
 }) => {
   // Use the SL SDK for API calls
@@ -148,19 +228,13 @@ export const MyWidget: React.FC<SmartLinksWidgetProps> = ({
     console.log('Config:', data);
   };
 
-  // Navigate to full app (supports both patterns)
-  const handleOpenApp = () => {
-    const params = new URLSearchParams({ collectionId, appId });
-    if (productId) params.set('productId', productId);
-    const relativePath = `/#/?${params.toString()}`;
-    
-    if (onNavigate) {
-      // Parent-controlled navigation
-      onNavigate(relativePath);
-    } else if (publicPortalUrl) {
-      // Direct redirect (handles iframe escape automatically)
-      SL.iframe.redirectParent(`${publicPortalUrl}${relativePath}`);
-    }
+  // Navigate to another app using structured request
+  const handleOpenFullApp = () => {
+    onNavigate?.({
+      appId,
+      deepLink: 'details',
+      params: { source: 'widget' },
+    });
   };
 
   return (
@@ -172,7 +246,7 @@ export const MyWidget: React.FC<SmartLinksWidgetProps> = ({
         <p className="text-muted-foreground mb-4">
           Widget content goes here
         </p>
-        <Button onClick={handleOpenApp}>Open App</Button>
+        <Button onClick={handleOpenFullApp}>Open App</Button>
       </CardContent>
     </Card>
   );
@@ -316,23 +390,15 @@ const CompetitionWidget = lazy(() =>
 function Portal() {
   return (
     <Suspense fallback={<WidgetSkeleton />}>
-      {/* Option 1: Parent controls navigation */}
-      <CompetitionWidget
-        collectionId="abc123"
-        appId="competition"
-        user={currentUser}
-        SL={SL}
-        onNavigate={(path) => window.open(`https://competition-app.example.com${path}`)}
-        size="standard"
-      />
-      
-      {/* Option 2: Widget handles its own navigation */}
       <CompetitionWidget
         collectionId="abc123"
         appId="competition"
         user={currentUser}
         SL={SL}
-        publicPortalUrl="https://competition-app.example.com"
+        onNavigate={(request) => {
+          // The portal orchestrator handles NavigationRequest objects
+          // automatically when using ContentOrchestrator / OrchestratedPortal
+        }}
         size="standard"
       />
     </Suspense>
@@ -411,7 +477,8 @@ Widgets use semantic class names that reference these variables:
 - ✅ Use semantic color classes for theming
 - ✅ Handle loading and error states gracefully
 - ✅ Use the provided `SL` SDK for API calls
-- ✅ Provide meaningful navigation via `onNavigate`
+- ✅ Use structured `NavigationRequest` for cross-app navigation
+- ✅ Include `params` for any extra context the target app needs
 
 ### Don'ts
 
@@ -420,6 +487,7 @@ Widgets use semantic class names that reference these variables:
 - ❌ Don't assume specific viewport sizes
 - ❌ Don't make widgets too complex (use full app for that)
 - ❌ Don't store state that should persist (use parent or SDK)
+- ❌ Don't construct portal URLs manually — use `NavigationRequest` instead
 
 ---
 
@@ -495,7 +563,7 @@ function WidgetTestPage() {
 ```
 src/widgets/
 ├── index.ts              # Main exports barrel
-├── types.ts              # SmartLinksWidgetProps and related types
+├── types.ts              # SmartLinksWidgetProps, NavigationRequest, and related types
 ├── WidgetWrapper.tsx     # Error boundary + Suspense wrapper
 └── ExampleWidget/
     ├── index.tsx         # Re-export

package/package.json

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