@proveanything/smartlinks 1.8.7 → 1.8.9

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.7  |  Generated: 2026-03-18T08:55:08.708Z
+Version: 1.8.9  |  Generated: 2026-03-19T15:02:36.521Z
 
 This is a concise summary of all available API functions and types.
 

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

@@ -0,0 +1,319 @@
+# Building React Components for SmartLinks
+
+> **Read this first** before implementing widgets or containers for the SmartLinks platform.
+
+This guide covers the fundamental concepts you need to understand to build React components that work correctly in the SmartLinks ecosystem. For implementation details, see [widgets.md](./widgets.md) and [containers.md](./containers.md).
+
+---
+
+## Table of Contents
+
+1. [Dual-Mode Rendering](#dual-mode-rendering)
+2. [The Router Contract](#the-router-contract)
+3. [The useAppContext Pattern](#the-useappcontext-pattern)
+4. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Dual-Mode Rendering
+
+Every SmartLinks component can run in **two modes**. The platform decides which mode to use based on configuration — your app doesn't choose.
+
+| Mode | How It Works | When Used |
+|------|-------------|-----------|
+| **Direct Component** | Your component runs directly in the parent's React context | Default - better performance, shared context |
+| **Iframe** | Your app runs inside an iframe with its own URL | Fallback - full isolation when needed |
+
+**Key insight:** You write your component code once, and it must work correctly in **both** modes.
+
+### What Changes Between Modes?
+
+| Aspect | Direct Component Mode | Iframe Mode |
+|--------|----------------------|-------------|
+| **Context source** | Props passed from parent | URL search parameters |
+| **Router** | Parent provides `MemoryRouter` | Your app provides `HashRouter` |
+| **Styling** | Inherits parent's CSS scope | Fully isolated CSS |
+| **SDK instance** | Shared with parent via props | Own instance from `window.SL` |
+| **Communication** | Direct callbacks (props) | `postMessage` |
+
+---
+
+## The Router Contract
+
+This is the **most important rule** to avoid runtime errors:
+
+### ❌ The Critical Rule
+
+> **Your exported component (`PublicContainer` or `PublicComponent`) must NOT be wrapped in any `<Router>` component.**
+
+If you wrap your export in `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`, React Router will throw:
+
+```
+Error: You cannot render a <Router> inside another <Router>
+```
+
+### ✅ Where Routing Goes
+
+**For Widgets (no routing needed):**
+```tsx
+// src/exports/PublicComponent.tsx
+export const PublicComponent = (props) => {
+  return <WidgetContent />; // No router needed
+};
+```
+
+**For Containers (with internal navigation):**
+```tsx
+// src/exports/PublicContainer.tsx
+import { Routes, Route } from 'react-router-dom';
+
+export const PublicContainer = (props) => {
+  return (
+    <Routes>  {/* ✅ Routes are fine */}
+      <Route path="/" element={<Home />} />
+      <Route path="/detail/:id" element={<Detail />} />
+    </Routes>
+  );
+};
+```
+
+**For Iframe Entry Point:**
+```tsx
+// src/App.tsx (only used in iframe mode)
+import { HashRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <HashRouter>  {/* ✅ HashRouter only in iframe entry point */}
+      <Routes>
+        <Route path="/" element={<Home />} />
+      </Routes>
+    </HashRouter>
+  );
+}
+```
+
+### Why This Matters
+
+```
+Direct Component Mode:
+  Portal App
+    └─ MemoryRouter ← Parent provides this
+         └─ Your Component
+              └─ [If you add another Router here, it breaks]
+
+Iframe Mode:
+  <iframe>
+    └─ Your App.tsx
+         └─ HashRouter ← You provide this
+              └─ Your Component
+```
+
+---
+
+## The useAppContext Pattern
+
+To access context (collectionId, productId, etc.) in a way that works in **both** modes, use this abstraction:
+
+### The Hook
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from React Context (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // Direct-component mode
+  if (ctx) return ctx;
+  
+  // Iframe mode — read from URL
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+### Wire It Up in Your Export
+
+```tsx
+// src/exports/PublicContainer.tsx
+import { AppContext } from '@/hooks/useAppContext';
+
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <YourComponentTree />
+    </AppContext.Provider>
+  );
+};
+```
+
+### Use It in Your Components
+
+```tsx
+// Anywhere in your component tree
+import { useAppContext } from '@/hooks/useAppContext';
+
+function MyComponent() {
+  const { collectionId, productId, SL } = useAppContext();
+  // This works in both direct-component and iframe modes!
+  
+  return <div>Collection: {collectionId}</div>;
+}
+```
+
+### Why Not Just useSearchParams()?
+
+In **direct-component mode**, there are no URL search params — context comes as props. If you use `useSearchParams()` directly, it will return empty values. The `useAppContext()` pattern handles both cases automatically.
+
+---
+
+## Common Pitfalls
+
+### ❌ "You cannot render a `<Router>` inside another `<Router>`"
+
+**Cause:** Your exported component wraps itself in a Router.
+
+**Fix:** Remove the Router wrapper from `PublicContainer.tsx` or `PublicComponent.tsx`. Only your iframe entry point (`App.tsx`) should have a Router.
+
+---
+
+### ❌ "Invalid hook call" / Minified React error #321
+
+**Cause:** Your bundle includes its own copy of React instead of using the parent's shared instance.
+
+**Fix:** Ensure your build configuration externalizes React, ReactDOM, and react/jsx-runtime:
+
+```ts
+// vite.config.container.ts or vite.config.widget.ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      external: [
+        'react',
+        'react-dom',
+        'react/jsx-runtime',
+        'react-router-dom',
+        '@proveanything/smartlinks',
+        // ... other shared dependencies
+      ],
+    },
+  },
+});
+```
+
+---
+
+### ❌ Context values are undefined in direct-component mode
+
+**Cause:** Using `useSearchParams()` or reading from `window.location` instead of using the `useAppContext()` pattern.
+
+**Fix:** Implement the `useAppContext()` hook as shown above and use it throughout your component tree.
+
+---
+
+### ❌ Navigation doesn't work
+
+**Cause:** Using `window.location` or `window.parent.postMessage` for navigation.
+
+**Fix:** Use the `onNavigate` callback from props/context with structured `NavigationRequest` objects. See [widgets.md](./widgets.md#cross-app-navigation) for details.
+
+---
+
+### ❌ Styles leak between apps
+
+**Cause:** Direct components share the parent's CSS scope — there's no iframe isolation.
+
+**Fix:** Use CSS Modules, scoped class prefixes, or Tailwind with a unique prefix. Avoid global CSS selectors in your bundle.
+
+---
+
+### ❌ CORS errors when loading bundles
+
+**Cause:** Your widget/container JavaScript or CSS is served from a different origin without CORS headers.
+
+**Fix:** Configure CORS headers on your hosting, or use inline bundle source via the SDK's `getWidgets()` API.
+
+---
+
+## Quick Diagnostic Checklist
+
+| Issue | Check |
+|-------|-------|
+| Router error | Remove all `<Router>` wrappers from your exported component |
+| Invalid hook call | Verify React is externalized in your build config |
+| Missing context | Use `useAppContext()` instead of `useSearchParams()` |
+| Duplicate React | Check `window.React === yourBundle.React` in browser console |
+| CSS conflicts | Use scoped CSS (modules/prefixes), avoid global selectors |
+
+---
+
+## File Structure Reference
+
+```
+my-app/
+├── src/
+│   ├── App.tsx                     ← Iframe entry (has HashRouter)
+│   ├── exports/
+│   │   ├── PublicContainer.tsx     ← Container export (no Router!)
+│   │   └── PublicComponent.tsx     ← Widget export (no Router!)
+│   ├── hooks/
+│   │   └── useAppContext.ts        ← Dual-mode abstraction
+│   ├── pages/
+│   │   ├── Home.tsx                ← Shared components
+│   │   └── Detail.tsx
+│   └── main.tsx                    ← Iframe bootstrap
+├── vite.config.ts                  ← Iframe build
+├── vite.config.container.ts        ← Container bundle
+└── vite.config.widget.ts           ← Widget bundle
+```
+
+---
+
+## Next Steps
+
+Now that you understand the core concepts, see the implementation guides:
+
+- **[widgets.md](./widgets.md)** — Build lightweight preview components
+- **[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
+
+---
+
+## Related Documentation
+
+- [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
+- [manifests.md](./manifests.md) — App manifest configuration

package/dist/docs/containers.md

@@ -26,6 +26,190 @@ Imagine a homepage displaying 10 app widgets. If containers were bundled with wi
 
 ---
 
+## Dual-Mode Rendering
+
+Containers can run in **two modes**, and the same container code must work in both:
+
+| Mode | How It Works | Who Provides the Router? |
+|------|-------------|--------------------------|
+| **Direct Component** | Container runs directly in the parent's React context | **The framework** — wraps your component in `MemoryRouter` |
+| **Iframe** | Container runs inside an iframe with its own URL | **Your app** — you manage your own `HashRouter` |
+
+### The Critical Rule: No Router Wrappers in Your Export
+
+> **❌ Your exported `PublicContainer` must NOT be wrapped in a `<Router>`, `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`.**
+
+**Why?** In direct-component mode, the framework already wraps your container in a `MemoryRouter`. If your component includes its own Router, React Router will throw: _"You cannot render a `<Router>` inside another `<Router>`"_.
+
+**The routing architecture:**
+
+```
+Direct Component Mode:
+  Portal Shell (HashRouter)
+    └─ ContentOrchestrator
+         └─ MemoryRouter ← framework provides this
+              └─ <YourContainer /> ← only contains <Routes>, no <Router>
+                   └─ <Route path="/" element={<Home />} />
+                   └─ <Route path="/detail/:id" element={<Detail />} />
+
+Iframe Mode:
+  <iframe src="your-app-url">
+    └─ <HashRouter> ← your App.tsx provides this
+         └─ <Routes>
+              └─ <Route path="/" element={<Home />} />
+```
+
+**Where routing goes:**
+- ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
+- ✅ Your **exported container** (`PublicContainer.tsx`) should include `<Routes>` and `<Route>` elements
+- ❌ Your **exported container** should NOT include any `<Router>` wrapper
+
+### The Router Contract
+
+In direct-component mode, the framework's `MemoryRouter` gives you full React Router capabilities:
+
+- ✅ `useNavigate()` works — navigates within your container's routes
+- ✅ `useLocation()` works — returns current location in the MemoryRouter
+- ✅ `useParams()` works — reads params from your route definitions
+- ✅ `<Routes>` / `<Route>` work — define your internal navigation
+- ✅ `useSearchParams()` works — manages search params within the MemoryRouter
+- ⚠️ `window.location` does **NOT** reflect your container's route — it reflects the portal's URL
+
+**Example: Correct Container Structure**
+
+```tsx
+// ❌ WRONG — has Router wrapper
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <MemoryRouter>  {/* ❌ Don't do this! */}
+      <Routes>
+        <Route path="/" element={<Home />} />
+      </Routes>
+    </MemoryRouter>
+  );
+};
+
+// ✅ CORRECT — no Router wrapper
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <Routes>  {/* ✅ Routes are fine, just no Router */}
+        <Route path="/" element={<Home />} />
+        <Route path="/detail/:id" element={<Detail />} />
+      </Routes>
+    </AppContext.Provider>
+  );
+};
+```
+
+### The `useAppContext()` Pattern
+
+To write containers that work identically in both modes, use this abstraction pattern:
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  initialPath?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from AppContext (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // If context exists, we're in direct-component mode
+  if (ctx) return ctx;
+  
+  // Otherwise, we're in iframe mode — read from URL params
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+**Usage in your container:**
+
+```tsx
+// src/exports/PublicContainer.tsx
+import { Routes, Route } from 'react-router-dom';
+import { AppContext } from '@/hooks/useAppContext';
+import { Home } from '@/pages/Home';
+import { Detail } from '@/pages/Detail';
+
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="/detail/:id" element={<Detail />} />
+      </Routes>
+    </AppContext.Provider>
+  );
+};
+
+// src/pages/Home.tsx
+import { useAppContext } from '@/hooks/useAppContext';
+import { useNavigate } from 'react-router-dom';
+
+export function Home() {
+  const { collectionId, productId, SL } = useAppContext();
+  const navigate = useNavigate();
+  
+  return (
+    <div>
+      <h1>Collection: {collectionId}</h1>
+      <button onClick={() => navigate('/detail/123')}>
+        View Detail
+      </button>
+    </div>
+  );
+}
+```
+
+### Deep Linking
+
+The framework sets the `MemoryRouter`'s initial route based on the `pageId` or `initialPath` prop. For example, if the portal navigates to your container with `pageId: 'settings'`, your router will start at `/settings`.
+
+To advertise deep-linkable pages, declare them in your `app.manifest.json`:
+
+```json
+{
+  "linkable": [
+    { "title": "Home", "path": "/" },
+    { "title": "Settings", "path": "/settings" },
+    { "title": "Item Detail", "path": "/item/:itemId" }
+  ]
+}
+```
+
+---
+
 ## Container Props
 
 Container props extend the standard `SmartLinksWidgetProps` with an additional `className` prop:

package/dist/docs/overview.md

@@ -45,6 +45,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | Topic | File | When to Use |
 |-------|------|-------------|
 | **API Reference** | `docs/API_SUMMARY.md` | Complete SDK function reference, types, error handling |
+| **Building React Components** | `docs/building-react-components.md` | **READ THIS FIRST** — Dual-mode rendering, router rules, useAppContext pattern |
 | **Multi-Page Architecture** | `docs/mpa.md` | Build pipeline, entry points, multi-page setup, content hashing |
 | **AI & Chat** | `docs/ai.md` | Chat completions, RAG, streaming, tool calling, voice, podcasts, TTS |
 | **Analytics** | `docs/analytics.md` | Fire-and-forget page/click/tag analytics plus admin dashboard queries |

package/dist/docs/widgets.md

@@ -30,6 +30,104 @@ Widgets are self-contained React components that:
 
 ---
 
+## Dual-Mode Rendering
+
+Widgets can run in **two modes**, and the same widget code must work in both:
+
+| Mode | How It Works | When Used |
+|------|-------------|-----------|
+| **Direct Component** | Widget runs directly in the parent's React context | Default - when loaded as ESM/UMD in the parent app |
+| **Iframe** | Widget runs inside an iframe with its own URL | Fallback or when full isolation is needed |
+
+### The Critical Rule: No Router Wrappers
+
+> **❌ Your widget component must NOT be wrapped in a `<Router>`, `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`.**
+
+**Why?** In direct component mode, the parent application already provides routing context. If your widget includes its own Router, React Router will throw: _"You cannot render a `<Router>` inside another `<Router>`"_.
+
+**Where routing goes:**
+- ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
+- ❌ Your **exported widget** (`PublicComponent.tsx`) should NOT include any Router
+
+Widgets are typically single-view components and don't need internal routing. If you need multi-page navigation, use a container instead.
+
+### The `useAppContext()` Pattern
+
+To write widgets that work identically in both modes, use this abstraction pattern:
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from AppContext (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // If context exists, we're in direct-component mode
+  if (ctx) return ctx;
+  
+  // Otherwise, we're in iframe mode — read from URL params
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+**Usage in your widget:**
+
+```tsx
+// src/exports/PublicComponent.tsx
+import { AppContext } from '@/hooks/useAppContext';
+import { WidgetContent } from '@/components/WidgetContent';
+
+export const PublicComponent = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <WidgetContent />
+    </AppContext.Provider>
+  );
+};
+
+// src/components/WidgetContent.tsx
+import { useAppContext } from '@/hooks/useAppContext';
+
+export function WidgetContent() {
+  const { collectionId, productId, SL } = useAppContext();
+  // Works in both direct-component and iframe modes!
+  return <div>Collection: {collectionId}</div>;
+}
+```
+
+---
+
 ## Widget Props Interface
 
 All widgets receive the `SmartLinksWidgetProps` interface:

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.7  |  Generated: 2026-03-18T08:55:08.708Z
+Version: 1.8.9  |  Generated: 2026-03-19T15:02:36.521Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/building-react-components.md

@@ -0,0 +1,319 @@
+# Building React Components for SmartLinks
+
+> **Read this first** before implementing widgets or containers for the SmartLinks platform.
+
+This guide covers the fundamental concepts you need to understand to build React components that work correctly in the SmartLinks ecosystem. For implementation details, see [widgets.md](./widgets.md) and [containers.md](./containers.md).
+
+---
+
+## Table of Contents
+
+1. [Dual-Mode Rendering](#dual-mode-rendering)
+2. [The Router Contract](#the-router-contract)
+3. [The useAppContext Pattern](#the-useappcontext-pattern)
+4. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Dual-Mode Rendering
+
+Every SmartLinks component can run in **two modes**. The platform decides which mode to use based on configuration — your app doesn't choose.
+
+| Mode | How It Works | When Used |
+|------|-------------|-----------|
+| **Direct Component** | Your component runs directly in the parent's React context | Default - better performance, shared context |
+| **Iframe** | Your app runs inside an iframe with its own URL | Fallback - full isolation when needed |
+
+**Key insight:** You write your component code once, and it must work correctly in **both** modes.
+
+### What Changes Between Modes?
+
+| Aspect | Direct Component Mode | Iframe Mode |
+|--------|----------------------|-------------|
+| **Context source** | Props passed from parent | URL search parameters |
+| **Router** | Parent provides `MemoryRouter` | Your app provides `HashRouter` |
+| **Styling** | Inherits parent's CSS scope | Fully isolated CSS |
+| **SDK instance** | Shared with parent via props | Own instance from `window.SL` |
+| **Communication** | Direct callbacks (props) | `postMessage` |
+
+---
+
+## The Router Contract
+
+This is the **most important rule** to avoid runtime errors:
+
+### ❌ The Critical Rule
+
+> **Your exported component (`PublicContainer` or `PublicComponent`) must NOT be wrapped in any `<Router>` component.**
+
+If you wrap your export in `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`, React Router will throw:
+
+```
+Error: You cannot render a <Router> inside another <Router>
+```
+
+### ✅ Where Routing Goes
+
+**For Widgets (no routing needed):**
+```tsx
+// src/exports/PublicComponent.tsx
+export const PublicComponent = (props) => {
+  return <WidgetContent />; // No router needed
+};
+```
+
+**For Containers (with internal navigation):**
+```tsx
+// src/exports/PublicContainer.tsx
+import { Routes, Route } from 'react-router-dom';
+
+export const PublicContainer = (props) => {
+  return (
+    <Routes>  {/* ✅ Routes are fine */}
+      <Route path="/" element={<Home />} />
+      <Route path="/detail/:id" element={<Detail />} />
+    </Routes>
+  );
+};
+```
+
+**For Iframe Entry Point:**
+```tsx
+// src/App.tsx (only used in iframe mode)
+import { HashRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <HashRouter>  {/* ✅ HashRouter only in iframe entry point */}
+      <Routes>
+        <Route path="/" element={<Home />} />
+      </Routes>
+    </HashRouter>
+  );
+}
+```
+
+### Why This Matters
+
+```
+Direct Component Mode:
+  Portal App
+    └─ MemoryRouter ← Parent provides this
+         └─ Your Component
+              └─ [If you add another Router here, it breaks]
+
+Iframe Mode:
+  <iframe>
+    └─ Your App.tsx
+         └─ HashRouter ← You provide this
+              └─ Your Component
+```
+
+---
+
+## The useAppContext Pattern
+
+To access context (collectionId, productId, etc.) in a way that works in **both** modes, use this abstraction:
+
+### The Hook
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from React Context (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // Direct-component mode
+  if (ctx) return ctx;
+  
+  // Iframe mode — read from URL
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+### Wire It Up in Your Export
+
+```tsx
+// src/exports/PublicContainer.tsx
+import { AppContext } from '@/hooks/useAppContext';
+
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <YourComponentTree />
+    </AppContext.Provider>
+  );
+};
+```
+
+### Use It in Your Components
+
+```tsx
+// Anywhere in your component tree
+import { useAppContext } from '@/hooks/useAppContext';
+
+function MyComponent() {
+  const { collectionId, productId, SL } = useAppContext();
+  // This works in both direct-component and iframe modes!
+  
+  return <div>Collection: {collectionId}</div>;
+}
+```
+
+### Why Not Just useSearchParams()?
+
+In **direct-component mode**, there are no URL search params — context comes as props. If you use `useSearchParams()` directly, it will return empty values. The `useAppContext()` pattern handles both cases automatically.
+
+---
+
+## Common Pitfalls
+
+### ❌ "You cannot render a `<Router>` inside another `<Router>`"
+
+**Cause:** Your exported component wraps itself in a Router.
+
+**Fix:** Remove the Router wrapper from `PublicContainer.tsx` or `PublicComponent.tsx`. Only your iframe entry point (`App.tsx`) should have a Router.
+
+---
+
+### ❌ "Invalid hook call" / Minified React error #321
+
+**Cause:** Your bundle includes its own copy of React instead of using the parent's shared instance.
+
+**Fix:** Ensure your build configuration externalizes React, ReactDOM, and react/jsx-runtime:
+
+```ts
+// vite.config.container.ts or vite.config.widget.ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      external: [
+        'react',
+        'react-dom',
+        'react/jsx-runtime',
+        'react-router-dom',
+        '@proveanything/smartlinks',
+        // ... other shared dependencies
+      ],
+    },
+  },
+});
+```
+
+---
+
+### ❌ Context values are undefined in direct-component mode
+
+**Cause:** Using `useSearchParams()` or reading from `window.location` instead of using the `useAppContext()` pattern.
+
+**Fix:** Implement the `useAppContext()` hook as shown above and use it throughout your component tree.
+
+---
+
+### ❌ Navigation doesn't work
+
+**Cause:** Using `window.location` or `window.parent.postMessage` for navigation.
+
+**Fix:** Use the `onNavigate` callback from props/context with structured `NavigationRequest` objects. See [widgets.md](./widgets.md#cross-app-navigation) for details.
+
+---
+
+### ❌ Styles leak between apps
+
+**Cause:** Direct components share the parent's CSS scope — there's no iframe isolation.
+
+**Fix:** Use CSS Modules, scoped class prefixes, or Tailwind with a unique prefix. Avoid global CSS selectors in your bundle.
+
+---
+
+### ❌ CORS errors when loading bundles
+
+**Cause:** Your widget/container JavaScript or CSS is served from a different origin without CORS headers.
+
+**Fix:** Configure CORS headers on your hosting, or use inline bundle source via the SDK's `getWidgets()` API.
+
+---
+
+## Quick Diagnostic Checklist
+
+| Issue | Check |
+|-------|-------|
+| Router error | Remove all `<Router>` wrappers from your exported component |
+| Invalid hook call | Verify React is externalized in your build config |
+| Missing context | Use `useAppContext()` instead of `useSearchParams()` |
+| Duplicate React | Check `window.React === yourBundle.React` in browser console |
+| CSS conflicts | Use scoped CSS (modules/prefixes), avoid global selectors |
+
+---
+
+## File Structure Reference
+
+```
+my-app/
+├── src/
+│   ├── App.tsx                     ← Iframe entry (has HashRouter)
+│   ├── exports/
+│   │   ├── PublicContainer.tsx     ← Container export (no Router!)
+│   │   └── PublicComponent.tsx     ← Widget export (no Router!)
+│   ├── hooks/
+│   │   └── useAppContext.ts        ← Dual-mode abstraction
+│   ├── pages/
+│   │   ├── Home.tsx                ← Shared components
+│   │   └── Detail.tsx
+│   └── main.tsx                    ← Iframe bootstrap
+├── vite.config.ts                  ← Iframe build
+├── vite.config.container.ts        ← Container bundle
+└── vite.config.widget.ts           ← Widget bundle
+```
+
+---
+
+## Next Steps
+
+Now that you understand the core concepts, see the implementation guides:
+
+- **[widgets.md](./widgets.md)** — Build lightweight preview components
+- **[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
+
+---
+
+## Related Documentation
+
+- [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
+- [manifests.md](./manifests.md) — App manifest configuration

package/docs/containers.md

@@ -26,6 +26,190 @@ Imagine a homepage displaying 10 app widgets. If containers were bundled with wi
 
 ---
 
+## Dual-Mode Rendering
+
+Containers can run in **two modes**, and the same container code must work in both:
+
+| Mode | How It Works | Who Provides the Router? |
+|------|-------------|--------------------------|
+| **Direct Component** | Container runs directly in the parent's React context | **The framework** — wraps your component in `MemoryRouter` |
+| **Iframe** | Container runs inside an iframe with its own URL | **Your app** — you manage your own `HashRouter` |
+
+### The Critical Rule: No Router Wrappers in Your Export
+
+> **❌ Your exported `PublicContainer` must NOT be wrapped in a `<Router>`, `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`.**
+
+**Why?** In direct-component mode, the framework already wraps your container in a `MemoryRouter`. If your component includes its own Router, React Router will throw: _"You cannot render a `<Router>` inside another `<Router>`"_.
+
+**The routing architecture:**
+
+```
+Direct Component Mode:
+  Portal Shell (HashRouter)
+    └─ ContentOrchestrator
+         └─ MemoryRouter ← framework provides this
+              └─ <YourContainer /> ← only contains <Routes>, no <Router>
+                   └─ <Route path="/" element={<Home />} />
+                   └─ <Route path="/detail/:id" element={<Detail />} />
+
+Iframe Mode:
+  <iframe src="your-app-url">
+    └─ <HashRouter> ← your App.tsx provides this
+         └─ <Routes>
+              └─ <Route path="/" element={<Home />} />
+```
+
+**Where routing goes:**
+- ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
+- ✅ Your **exported container** (`PublicContainer.tsx`) should include `<Routes>` and `<Route>` elements
+- ❌ Your **exported container** should NOT include any `<Router>` wrapper
+
+### The Router Contract
+
+In direct-component mode, the framework's `MemoryRouter` gives you full React Router capabilities:
+
+- ✅ `useNavigate()` works — navigates within your container's routes
+- ✅ `useLocation()` works — returns current location in the MemoryRouter
+- ✅ `useParams()` works — reads params from your route definitions
+- ✅ `<Routes>` / `<Route>` work — define your internal navigation
+- ✅ `useSearchParams()` works — manages search params within the MemoryRouter
+- ⚠️ `window.location` does **NOT** reflect your container's route — it reflects the portal's URL
+
+**Example: Correct Container Structure**
+
+```tsx
+// ❌ WRONG — has Router wrapper
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <MemoryRouter>  {/* ❌ Don't do this! */}
+      <Routes>
+        <Route path="/" element={<Home />} />
+      </Routes>
+    </MemoryRouter>
+  );
+};
+
+// ✅ CORRECT — no Router wrapper
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <Routes>  {/* ✅ Routes are fine, just no Router */}
+        <Route path="/" element={<Home />} />
+        <Route path="/detail/:id" element={<Detail />} />
+      </Routes>
+    </AppContext.Provider>
+  );
+};
+```
+
+### The `useAppContext()` Pattern
+
+To write containers that work identically in both modes, use this abstraction pattern:
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  initialPath?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from AppContext (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // If context exists, we're in direct-component mode
+  if (ctx) return ctx;
+  
+  // Otherwise, we're in iframe mode — read from URL params
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+**Usage in your container:**
+
+```tsx
+// src/exports/PublicContainer.tsx
+import { Routes, Route } from 'react-router-dom';
+import { AppContext } from '@/hooks/useAppContext';
+import { Home } from '@/pages/Home';
+import { Detail } from '@/pages/Detail';
+
+export const PublicContainer = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="/detail/:id" element={<Detail />} />
+      </Routes>
+    </AppContext.Provider>
+  );
+};
+
+// src/pages/Home.tsx
+import { useAppContext } from '@/hooks/useAppContext';
+import { useNavigate } from 'react-router-dom';
+
+export function Home() {
+  const { collectionId, productId, SL } = useAppContext();
+  const navigate = useNavigate();
+  
+  return (
+    <div>
+      <h1>Collection: {collectionId}</h1>
+      <button onClick={() => navigate('/detail/123')}>
+        View Detail
+      </button>
+    </div>
+  );
+}
+```
+
+### Deep Linking
+
+The framework sets the `MemoryRouter`'s initial route based on the `pageId` or `initialPath` prop. For example, if the portal navigates to your container with `pageId: 'settings'`, your router will start at `/settings`.
+
+To advertise deep-linkable pages, declare them in your `app.manifest.json`:
+
+```json
+{
+  "linkable": [
+    { "title": "Home", "path": "/" },
+    { "title": "Settings", "path": "/settings" },
+    { "title": "Item Detail", "path": "/item/:itemId" }
+  ]
+}
+```
+
+---
+
 ## Container Props
 
 Container props extend the standard `SmartLinksWidgetProps` with an additional `className` prop:

package/docs/overview.md

@@ -45,6 +45,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | Topic | File | When to Use |
 |-------|------|-------------|
 | **API Reference** | `docs/API_SUMMARY.md` | Complete SDK function reference, types, error handling |
+| **Building React Components** | `docs/building-react-components.md` | **READ THIS FIRST** — Dual-mode rendering, router rules, useAppContext pattern |
 | **Multi-Page Architecture** | `docs/mpa.md` | Build pipeline, entry points, multi-page setup, content hashing |
 | **AI & Chat** | `docs/ai.md` | Chat completions, RAG, streaming, tool calling, voice, podcasts, TTS |
 | **Analytics** | `docs/analytics.md` | Fire-and-forget page/click/tag analytics plus admin dashboard queries |

package/docs/widgets.md

@@ -30,6 +30,104 @@ Widgets are self-contained React components that:
 
 ---
 
+## Dual-Mode Rendering
+
+Widgets can run in **two modes**, and the same widget code must work in both:
+
+| Mode | How It Works | When Used |
+|------|-------------|-----------|
+| **Direct Component** | Widget runs directly in the parent's React context | Default - when loaded as ESM/UMD in the parent app |
+| **Iframe** | Widget runs inside an iframe with its own URL | Fallback or when full isolation is needed |
+
+### The Critical Rule: No Router Wrappers
+
+> **❌ Your widget component must NOT be wrapped in a `<Router>`, `<MemoryRouter>`, `<HashRouter>`, or `<BrowserRouter>`.**
+
+**Why?** In direct component mode, the parent application already provides routing context. If your widget includes its own Router, React Router will throw: _"You cannot render a `<Router>` inside another `<Router>`"_.
+
+**Where routing goes:**
+- ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
+- ❌ Your **exported widget** (`PublicComponent.tsx`) should NOT include any Router
+
+Widgets are typically single-view components and don't need internal routing. If you need multi-page navigation, use a container instead.
+
+### The `useAppContext()` Pattern
+
+To write widgets that work identically in both modes, use this abstraction pattern:
+
+```tsx
+// src/hooks/useAppContext.ts
+import { useContext, createContext, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+export interface AppContextValue {
+  collectionId: string;
+  appId: string;
+  productId?: string;
+  proofId?: string;
+  pageId?: string;
+  lang?: string;
+  user?: { id: string; email: string; name?: string };
+  SL: typeof import('@proveanything/smartlinks');
+  onNavigate?: (request: any) => void;
+}
+
+export const AppContext = createContext<AppContextValue | null>(null);
+
+/**
+ * Returns app context regardless of rendering mode.
+ * - Direct component mode: reads from AppContext (props)
+ * - Iframe mode: reads from URL search params
+ */
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  
+  // If context exists, we're in direct-component mode
+  if (ctx) return ctx;
+  
+  // Otherwise, we're in iframe mode — read from URL params
+  const [searchParams] = useSearchParams();
+  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
+
+  return useMemo(() => ({
+    collectionId: searchParams.get('collectionId') ?? '',
+    appId: searchParams.get('appId') ?? '',
+    productId: searchParams.get('productId') ?? undefined,
+    proofId: searchParams.get('proofId') ?? undefined,
+    pageId: searchParams.get('pageId') ?? undefined,
+    lang: searchParams.get('lang') ?? undefined,
+    SL,
+  }), [searchParams, SL]);
+}
+```
+
+**Usage in your widget:**
+
+```tsx
+// src/exports/PublicComponent.tsx
+import { AppContext } from '@/hooks/useAppContext';
+import { WidgetContent } from '@/components/WidgetContent';
+
+export const PublicComponent = (props: Record<string, any>) => {
+  return (
+    <AppContext.Provider value={props}>
+      <WidgetContent />
+    </AppContext.Provider>
+  );
+};
+
+// src/components/WidgetContent.tsx
+import { useAppContext } from '@/hooks/useAppContext';
+
+export function WidgetContent() {
+  const { collectionId, productId, SL } = useAppContext();
+  // Works in both direct-component and iframe modes!
+  return <div>Collection: {collectionId}</div>;
+}
+```
+
+---
+
 ## Widget Props Interface
 
 All widgets receive the `SmartLinksWidgetProps` interface:

package/package.json

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