@proveanything/smartlinks 1.4.1 → 1.4.3

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.4.1  |  Generated: 2026-02-20T19:32:34.980Z
+Version: 1.4.3  |  Generated: 2026-02-20T22:45:10.423Z
 
 This is a concise summary of all available API functions and types.
 
@@ -10,6 +10,7 @@ For detailed guides on specific features:
 
 - **[AI & Chat Completions](ai.md)** - Chat completions, RAG (document-grounded Q&A), voice integration, streaming, tool calling, podcast generation
 - **[Widgets](widgets.md)** - Embeddable React components for parent applications
+- **[Containers](containers.md)** - Building full-app embeddable containers (lazy-loaded) 
 - **[Realtime](realtime.md)** - Real-time data updates and WebSocket connections
 - **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication
 - **[i18n](i18n.md)** - Internationalization and localization
@@ -821,6 +822,41 @@ interface AppConfigurationResponse {
 
 ### appManifest
 
+**AppBundle** (interface)
+```typescript
+interface AppBundle {
+  js: string | null;
+  css: string | null;
+  source?: string;
+  styles?: string;
+}
+```
+
+**AppWidgetDefinition** (interface)
+```typescript
+interface AppWidgetDefinition {
+  name: string;
+  description?: string;
+  sizes?: Array<'compact' | 'standard' | 'large' | string>;
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+}
+```
+
+**AppContainerDefinition** (interface)
+```typescript
+interface AppContainerDefinition {
+  name: string;
+  description?: string;
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+}
+```
+
 **AppManifest** (interface)
 ```typescript
 interface AppManifest {
@@ -832,15 +868,8 @@ interface AppManifest {
   platformRevision?: string;
   appId: string;
   };
-  widgets?: Array<{
-  name: string;
-  description?: string;
-  sizes?: string[];
-  props?: {
-  required?: string[];
-  optional?: string[];
-  };
-  }>;
+  widgets?: AppWidgetDefinition[];
+  containers?: AppContainerDefinition[];
   setup?: {
   description?: string;
   questions?: Array<{
@@ -849,12 +878,14 @@ interface AppManifest {
   type: string;
   default?: any;
   required?: boolean;
+  options?: Array<{ value: string; label: string }>;
   }>;
   configSchema?: Record<string, any>;
   saveWith?: {
   method: string;
-  scope: string;
+  scope: 'collection' | 'product' | string;
   admin?: boolean;
+  note?: string;
   };
   contentHints?: Record<string, {
   aiGenerate?: boolean;
@@ -885,44 +916,38 @@ interface AppManifest {
   name: string;
   description?: string;
   type: string;
+  options?: string[];
   }>;
   };
   metrics?: {
-  interactions?: Array<{
-  id: string;
-  description?: string;
-  }>;
-  kpis?: Array<{
-  name: string;
-  compute?: string;
-  }>;
+  interactions?: Array<{ id: string; description?: string }>;
+  kpis?: Array<{ name: string; compute?: string }>;
   };
-  [key: string]: any; // Allow additional custom fields
+  [key: string]: any;
 }
 ```
 
-**CollectionWidget** (interface)
+**CollectionAppWidget** (interface)
 ```typescript
-interface CollectionWidget {
+interface CollectionAppWidget {
   appId: string;
-  manifestUrl: string;
   manifest: AppManifest;
-  bundleSource: string;
-  bundleCss?: string; // Optional CSS file
+  widget: AppBundle;
+  container: AppBundle | null;
 }
 ```
 
 **CollectionWidgetsResponse** (interface)
 ```typescript
 interface CollectionWidgetsResponse {
-  apps: CollectionWidget[];
+  apps: CollectionAppWidget[];
 }
 ```
 
 **GetCollectionWidgetsOptions** (interface)
 ```typescript
 interface GetCollectionWidgetsOptions {
-  force?: boolean; // Bypass cache and fetch fresh data
+  force?: boolean;
 }
 ```
 

package/dist/docs/containers.md

@@ -0,0 +1,198 @@
+# SmartLinks Containers
+
+> **Copy this file into `node_modules/@proveanything/smartlinks/docs/containers.md`** in the published SDK package.
+
+Containers are the **full public app experience** packaged as an embeddable React component. Unlike widgets (lightweight previews/cards), containers render the complete public interface — all pages, routing, and features — inside a parent React application.
+
+---
+
+## Widgets vs Containers
+
+| Aspect          | Widget                             | Container                                    |
+| --------------- | ---------------------------------- | -------------------------------------------- |
+| **Purpose**     | Lightweight preview / summary      | Full app experience                          |
+| **Bundle size** | ~10KB (app-specific code only)     | ~150KB+ (full public app)                    |
+| **Loading**     | Loaded immediately with page       | Lazy-loaded on demand                        |
+| **Routing**     | None (single component)            | MemoryRouter (parent owns URL bar)           |
+| **Use case**    | Cards, thumbnails, quick glance    | "Open full view", embedded experiences       |
+| **Build output**| `widgets.umd.js` / `widgets.es.js` | `containers.umd.js` / `containers.es.js`    |
+
+### Why Separate Bundles?
+
+Imagine a homepage displaying 10 app widgets. If containers were bundled with widgets, loading 10 small widget cards would also pull in 10 full app bundles — potentially megabytes of unused code. By splitting them:
+
+1. **Widgets load fast** — parent loads `widgets.*.js` for all apps on the page (~10KB each)
+2. **Containers load on demand** — only when user clicks "Open full view" does `containers.*.js` get fetched
+
+---
+
+## Container Props
+
+Container props extend the standard `SmartLinksWidgetProps` with an additional `className` prop:
+
+```typescript
+interface SmartLinksContainerProps extends SmartLinksWidgetProps {
+  /** Optional className for the container wrapper element */
+  className?: string;
+}
+```
+
+All standard widget props apply:
+
+| Prop              | Type           | Required | Description                             |
+| ----------------- | -------------- | -------- | --------------------------------------- |
+| `collectionId`    | string         | ✅       | Collection context                      |
+| `appId`           | string         | ✅       | App identifier                          |
+| `SL`              | SmartLinks SDK | ✅       | Pre-initialized SDK instance            |
+| `productId`       | string         | ❌       | Product context                         |
+| `proofId`         | string         | ❌       | Proof context                           |
+| `user`            | object         | ❌       | Current user info                       |
+| `onNavigate`      | function       | ❌       | Navigation callback                     |
+| `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
+| `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |
+| `translations`    | object         | ❌       | Translation overrides                   |
+| `className`       | string         | ❌       | CSS class for the wrapper element       |
+
+---
+
+## 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.
+
+```
+Parent App (owns URL bar, provides globals)
+  └── <PublicContainer>                    ← Container component
+        ├── QueryClientProvider (isolated)
+        ├── MemoryRouter (internal routing)
+        ├── LanguageProvider
+        └── PublicPage (+ all sub-routes)
+```
+
+---
+
+## Usage in Parent Apps
+
+### ESM (Modern Bundlers)
+
+```typescript
+// Lazy-load the container only when needed
+const { PublicContainer } = await import('https://my-app.com/containers.es.js');
+
+<PublicContainer
+  collectionId="abc"
+  appId="my-app"
+  productId="prod-123"
+  SL={SL}
+  onNavigate={handleNavigate}
+  lang="en"
+  className="max-w-4xl mx-auto"
+/>
+```
+
+### UMD (Script Tag)
+
+```html
+<!-- Ensure shared globals are set up first (see Shared Dependencies Contract) -->
+<script src="https://my-app.com/containers.umd.js"></script>
+<script>
+  const { PublicContainer } = window.SmartLinksContainers;
+  // Render with React
+</script>
+```
+
+---
+
+## Shared Dependencies Contract
+
+Containers use the **exact same Shared Dependencies Contract** as widgets. No additional globals are needed. The parent app must expose these globals before loading container bundles:
+
+- React, ReactDOM, jsxRuntime
+- SL (SmartLinks SDK)
+- CVA (class-variance-authority) — **uppercase to avoid `cva.cva` collision**
+- ReactRouterDOM, ReactQuery
+- LucideReact, dateFns, LiquidJS
+- 12 Radix UI primitives (Slot, Dialog, Popover, Tooltip, Tabs, Accordion, Select, ScrollArea, Label, Toast, Progress, Avatar)
+
+See `widgets.md` for the complete table with globals and version expectations.
+
+> **Why `CVA` not `cva`?** The `class-variance-authority` package exports a named function called `cva`. If the UMD global is also `cva`, the wrapper resolves it as `window.cva.cva` — a double-nesting bug. Using uppercase `CVA` avoids this collision.
+
+---
+
+## Build Configuration
+
+Containers are built via a dedicated Vite config: `vite.config.container.ts`.
+
+### Enable Container Builds
+
+Add to your `.env` file:
+
+```
+VITE_ENABLE_CONTAINERS=true
+```
+
+### Build Command
+
+```bash
+# Full pipeline (main + widgets + containers)
+vite build && vite build --config vite.config.widget.ts && vite build --config vite.config.container.ts
+
+# Containers only
+vite build --config vite.config.container.ts
+```
+
+### Build Output
+
+```text
+dist/
+├── containers.umd.js    # Full app container (UMD)
+├── containers.es.js     # Full app container (ESM)
+└── containers.css       # Container styles
+```
+
+When `VITE_ENABLE_CONTAINERS` is not set, the build produces a harmless `containers.stub.js` and skips quickly.
+
+---
+
+## File Structure
+
+```
+src/containers/
+├── index.ts              # Main exports barrel + ContainerManifest
+├── types.ts              # SmartLinksContainerProps interface
+├── stub.ts               # Minimal stub for skipped builds
+└── PublicContainer.tsx   # Full public app wrapper
+```
+
+### Creating a New Container
+
+1. Create your container component in `src/containers/MyContainer.tsx`
+2. Export it from `src/containers/index.ts`
+3. Add it to the `CONTAINER_MANIFEST` in `src/containers/index.ts`
+4. Ensure it uses `MemoryRouter` (not HashRouter)
+5. Give it its own `QueryClient` to avoid cache collisions
+
+---
+
+## Key Differences from Iframe Apps
+
+| Concern           | Iframe App                        | Container                          |
+| ----------------- | --------------------------------- | ---------------------------------- |
+| **Isolation**     | Full browser isolation            | Shares parent's React tree         |
+| **URL control**   | Owns its own URL (HashRouter)     | Parent owns URL (MemoryRouter)     |
+| **Context source**| URL parameters                    | React props                        |
+| **Styling**       | Fully isolated CSS                | Inherits parent CSS variables      |
+| **Communication** | postMessage                       | Direct props / callbacks           |
+| **Auth**          | Via `SL.auth.getAccount()`        | Via `user` prop from parent        |
+
+---
+
+## Troubleshooting
+
+| Issue                      | Cause                                    | Fix                                                  |
+| -------------------------- | ---------------------------------------- | ---------------------------------------------------- |
+| Container doesn't render   | Missing shared globals                   | Ensure all Shared Dependencies are on `window`       |
+| Styles don't apply         | Missing `containers.css`                 | Load the CSS file alongside the JS bundle            |
+| 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              |

package/dist/types/appManifest.d.ts

@@ -1,6 +1,54 @@
 /**
- * SmartLinks App Manifest structure
- * Defines the configuration, widgets, setup, import, and metrics for a microapp
+ * A bundle (widget or container) as returned by the collection widgets endpoint.
+ *
+ * The server currently returns URLs only. In future it may also inline the file
+ * contents when bundles are small or frequently accessed. Clients should check
+ * for inline content first and fall back to loading the URL.
+ *
+ *   if (bundle.source) {
+ *     // 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 */
+    js: string | null;
+    /** URL to the CSS file — load if `styles` is absent */
+    css: string | null;
+    /** Inlined JavaScript source (present when server bundles it inline) */
+    source?: string;
+    /** Inlined CSS styles (present when server bundles it inline) */
+    styles?: string;
+}
+/**
+ * A single widget defined in the manifest.
+ * Presence of the `widgets` array means a widget bundle exists for this app.
+ */
+export interface AppWidgetDefinition {
+    name: string;
+    description?: string;
+    sizes?: Array<'compact' | 'standard' | 'large' | string>;
+    props?: {
+        required?: string[];
+        optional?: string[];
+    };
+}
+/**
+ * A single container defined in the manifest.
+ * Presence of the `containers` array means a container bundle exists for this app.
+ * Containers are full-page / embedded components (larger than widgets, no iframe needed).
+ */
+export interface AppContainerDefinition {
+    name: string;
+    description?: string;
+    props?: {
+        required?: string[];
+        optional?: string[];
+    };
+}
+/**
+ * SmartLinks App Manifest — the app.manifest.json structure.
  */
 export interface AppManifest {
     $schema?: string;
@@ -11,15 +59,10 @@ export interface AppManifest {
         platformRevision?: string;
         appId: string;
     };
-    widgets?: Array<{
-        name: string;
-        description?: string;
-        sizes?: string[];
-        props?: {
-            required?: string[];
-            optional?: string[];
-        };
-    }>;
+    /** Presence means a widget bundle (widgets.umd.js / widgets.css) exists */
+    widgets?: AppWidgetDefinition[];
+    /** Presence means a container bundle (containers.umd.js / containers.css) exists */
+    containers?: AppContainerDefinition[];
     setup?: {
         description?: string;
         questions?: Array<{
@@ -28,12 +71,17 @@ export interface AppManifest {
             type: string;
             default?: any;
             required?: boolean;
+            options?: Array<{
+                value: string;
+                label: string;
+            }>;
         }>;
         configSchema?: Record<string, any>;
         saveWith?: {
             method: string;
-            scope: string;
+            scope: 'collection' | 'product' | string;
             admin?: boolean;
+            note?: string;
         };
         contentHints?: Record<string, {
             aiGenerate?: boolean;
@@ -64,6 +112,7 @@ export interface AppManifest {
             name: string;
             description?: string;
             type: string;
+            options?: string[];
         }>;
     };
     metrics?: {
@@ -79,24 +128,26 @@ export interface AppManifest {
     [key: string]: any;
 }
 /**
- * Single app widget data with manifest and bundle files
+ * One app entry in the collection widgets response.
  */
-export interface CollectionWidget {
+export interface CollectionAppWidget {
     appId: string;
-    manifestUrl: string;
     manifest: AppManifest;
-    bundleSource: string;
-    bundleCss?: string;
+    /** Widget bundle — always present (apps without widgets are excluded from the response) */
+    widget: AppBundle;
+    /** Container bundle — null when the app has no containers */
+    container: AppBundle | null;
 }
 /**
- * Response from collection widgets endpoint
+ * Response from GET /api/v1/public/collection/:collectionId/widgets
  */
 export interface CollectionWidgetsResponse {
-    apps: CollectionWidget[];
+    apps: CollectionAppWidget[];
 }
 /**
  * Options for fetching collection widgets
  */
 export interface GetCollectionWidgetsOptions {
+    /** Bypass server cache and fetch fresh manifests */
     force?: boolean;
 }

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.4.1  |  Generated: 2026-02-20T19:32:34.980Z
+Version: 1.4.3  |  Generated: 2026-02-20T22:45:10.423Z
 
 This is a concise summary of all available API functions and types.
 
@@ -10,6 +10,7 @@ For detailed guides on specific features:
 
 - **[AI & Chat Completions](ai.md)** - Chat completions, RAG (document-grounded Q&A), voice integration, streaming, tool calling, podcast generation
 - **[Widgets](widgets.md)** - Embeddable React components for parent applications
+- **[Containers](containers.md)** - Building full-app embeddable containers (lazy-loaded) 
 - **[Realtime](realtime.md)** - Real-time data updates and WebSocket connections
 - **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication
 - **[i18n](i18n.md)** - Internationalization and localization
@@ -821,6 +822,41 @@ interface AppConfigurationResponse {
 
 ### appManifest
 
+**AppBundle** (interface)
+```typescript
+interface AppBundle {
+  js: string | null;
+  css: string | null;
+  source?: string;
+  styles?: string;
+}
+```
+
+**AppWidgetDefinition** (interface)
+```typescript
+interface AppWidgetDefinition {
+  name: string;
+  description?: string;
+  sizes?: Array<'compact' | 'standard' | 'large' | string>;
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+}
+```
+
+**AppContainerDefinition** (interface)
+```typescript
+interface AppContainerDefinition {
+  name: string;
+  description?: string;
+  props?: {
+  required?: string[];
+  optional?: string[];
+  };
+}
+```
+
 **AppManifest** (interface)
 ```typescript
 interface AppManifest {
@@ -832,15 +868,8 @@ interface AppManifest {
   platformRevision?: string;
   appId: string;
   };
-  widgets?: Array<{
-  name: string;
-  description?: string;
-  sizes?: string[];
-  props?: {
-  required?: string[];
-  optional?: string[];
-  };
-  }>;
+  widgets?: AppWidgetDefinition[];
+  containers?: AppContainerDefinition[];
   setup?: {
   description?: string;
   questions?: Array<{
@@ -849,12 +878,14 @@ interface AppManifest {
   type: string;
   default?: any;
   required?: boolean;
+  options?: Array<{ value: string; label: string }>;
   }>;
   configSchema?: Record<string, any>;
   saveWith?: {
   method: string;
-  scope: string;
+  scope: 'collection' | 'product' | string;
   admin?: boolean;
+  note?: string;
   };
   contentHints?: Record<string, {
   aiGenerate?: boolean;
@@ -885,44 +916,38 @@ interface AppManifest {
   name: string;
   description?: string;
   type: string;
+  options?: string[];
   }>;
   };
   metrics?: {
-  interactions?: Array<{
-  id: string;
-  description?: string;
-  }>;
-  kpis?: Array<{
-  name: string;
-  compute?: string;
-  }>;
+  interactions?: Array<{ id: string; description?: string }>;
+  kpis?: Array<{ name: string; compute?: string }>;
   };
-  [key: string]: any; // Allow additional custom fields
+  [key: string]: any;
 }
 ```
 
-**CollectionWidget** (interface)
+**CollectionAppWidget** (interface)
 ```typescript
-interface CollectionWidget {
+interface CollectionAppWidget {
   appId: string;
-  manifestUrl: string;
   manifest: AppManifest;
-  bundleSource: string;
-  bundleCss?: string; // Optional CSS file
+  widget: AppBundle;
+  container: AppBundle | null;
 }
 ```
 
 **CollectionWidgetsResponse** (interface)
 ```typescript
 interface CollectionWidgetsResponse {
-  apps: CollectionWidget[];
+  apps: CollectionAppWidget[];
 }
 ```
 
 **GetCollectionWidgetsOptions** (interface)
 ```typescript
 interface GetCollectionWidgetsOptions {
-  force?: boolean; // Bypass cache and fetch fresh data
+  force?: boolean;
 }
 ```
 

package/docs/containers.md

@@ -0,0 +1,198 @@
+# SmartLinks Containers
+
+> **Copy this file into `node_modules/@proveanything/smartlinks/docs/containers.md`** in the published SDK package.
+
+Containers are the **full public app experience** packaged as an embeddable React component. Unlike widgets (lightweight previews/cards), containers render the complete public interface — all pages, routing, and features — inside a parent React application.
+
+---
+
+## Widgets vs Containers
+
+| Aspect          | Widget                             | Container                                    |
+| --------------- | ---------------------------------- | -------------------------------------------- |
+| **Purpose**     | Lightweight preview / summary      | Full app experience                          |
+| **Bundle size** | ~10KB (app-specific code only)     | ~150KB+ (full public app)                    |
+| **Loading**     | Loaded immediately with page       | Lazy-loaded on demand                        |
+| **Routing**     | None (single component)            | MemoryRouter (parent owns URL bar)           |
+| **Use case**    | Cards, thumbnails, quick glance    | "Open full view", embedded experiences       |
+| **Build output**| `widgets.umd.js` / `widgets.es.js` | `containers.umd.js` / `containers.es.js`    |
+
+### Why Separate Bundles?
+
+Imagine a homepage displaying 10 app widgets. If containers were bundled with widgets, loading 10 small widget cards would also pull in 10 full app bundles — potentially megabytes of unused code. By splitting them:
+
+1. **Widgets load fast** — parent loads `widgets.*.js` for all apps on the page (~10KB each)
+2. **Containers load on demand** — only when user clicks "Open full view" does `containers.*.js` get fetched
+
+---
+
+## Container Props
+
+Container props extend the standard `SmartLinksWidgetProps` with an additional `className` prop:
+
+```typescript
+interface SmartLinksContainerProps extends SmartLinksWidgetProps {
+  /** Optional className for the container wrapper element */
+  className?: string;
+}
+```
+
+All standard widget props apply:
+
+| Prop              | Type           | Required | Description                             |
+| ----------------- | -------------- | -------- | --------------------------------------- |
+| `collectionId`    | string         | ✅       | Collection context                      |
+| `appId`           | string         | ✅       | App identifier                          |
+| `SL`              | SmartLinks SDK | ✅       | Pre-initialized SDK instance            |
+| `productId`       | string         | ❌       | Product context                         |
+| `proofId`         | string         | ❌       | Proof context                           |
+| `user`            | object         | ❌       | Current user info                       |
+| `onNavigate`      | function       | ❌       | Navigation callback                     |
+| `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
+| `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |
+| `translations`    | object         | ❌       | Translation overrides                   |
+| `className`       | string         | ❌       | CSS class for the wrapper element       |
+
+---
+
+## 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.
+
+```
+Parent App (owns URL bar, provides globals)
+  └── <PublicContainer>                    ← Container component
+        ├── QueryClientProvider (isolated)
+        ├── MemoryRouter (internal routing)
+        ├── LanguageProvider
+        └── PublicPage (+ all sub-routes)
+```
+
+---
+
+## Usage in Parent Apps
+
+### ESM (Modern Bundlers)
+
+```typescript
+// Lazy-load the container only when needed
+const { PublicContainer } = await import('https://my-app.com/containers.es.js');
+
+<PublicContainer
+  collectionId="abc"
+  appId="my-app"
+  productId="prod-123"
+  SL={SL}
+  onNavigate={handleNavigate}
+  lang="en"
+  className="max-w-4xl mx-auto"
+/>
+```
+
+### UMD (Script Tag)
+
+```html
+<!-- Ensure shared globals are set up first (see Shared Dependencies Contract) -->
+<script src="https://my-app.com/containers.umd.js"></script>
+<script>
+  const { PublicContainer } = window.SmartLinksContainers;
+  // Render with React
+</script>
+```
+
+---
+
+## Shared Dependencies Contract
+
+Containers use the **exact same Shared Dependencies Contract** as widgets. No additional globals are needed. The parent app must expose these globals before loading container bundles:
+
+- React, ReactDOM, jsxRuntime
+- SL (SmartLinks SDK)
+- CVA (class-variance-authority) — **uppercase to avoid `cva.cva` collision**
+- ReactRouterDOM, ReactQuery
+- LucideReact, dateFns, LiquidJS
+- 12 Radix UI primitives (Slot, Dialog, Popover, Tooltip, Tabs, Accordion, Select, ScrollArea, Label, Toast, Progress, Avatar)
+
+See `widgets.md` for the complete table with globals and version expectations.
+
+> **Why `CVA` not `cva`?** The `class-variance-authority` package exports a named function called `cva`. If the UMD global is also `cva`, the wrapper resolves it as `window.cva.cva` — a double-nesting bug. Using uppercase `CVA` avoids this collision.
+
+---
+
+## Build Configuration
+
+Containers are built via a dedicated Vite config: `vite.config.container.ts`.
+
+### Enable Container Builds
+
+Add to your `.env` file:
+
+```
+VITE_ENABLE_CONTAINERS=true
+```
+
+### Build Command
+
+```bash
+# Full pipeline (main + widgets + containers)
+vite build && vite build --config vite.config.widget.ts && vite build --config vite.config.container.ts
+
+# Containers only
+vite build --config vite.config.container.ts
+```
+
+### Build Output
+
+```text
+dist/
+├── containers.umd.js    # Full app container (UMD)
+├── containers.es.js     # Full app container (ESM)
+└── containers.css       # Container styles
+```
+
+When `VITE_ENABLE_CONTAINERS` is not set, the build produces a harmless `containers.stub.js` and skips quickly.
+
+---
+
+## File Structure
+
+```
+src/containers/
+├── index.ts              # Main exports barrel + ContainerManifest
+├── types.ts              # SmartLinksContainerProps interface
+├── stub.ts               # Minimal stub for skipped builds
+└── PublicContainer.tsx   # Full public app wrapper
+```
+
+### Creating a New Container
+
+1. Create your container component in `src/containers/MyContainer.tsx`
+2. Export it from `src/containers/index.ts`
+3. Add it to the `CONTAINER_MANIFEST` in `src/containers/index.ts`
+4. Ensure it uses `MemoryRouter` (not HashRouter)
+5. Give it its own `QueryClient` to avoid cache collisions
+
+---
+
+## Key Differences from Iframe Apps
+
+| Concern           | Iframe App                        | Container                          |
+| ----------------- | --------------------------------- | ---------------------------------- |
+| **Isolation**     | Full browser isolation            | Shares parent's React tree         |
+| **URL control**   | Owns its own URL (HashRouter)     | Parent owns URL (MemoryRouter)     |
+| **Context source**| URL parameters                    | React props                        |
+| **Styling**       | Fully isolated CSS                | Inherits parent CSS variables      |
+| **Communication** | postMessage                       | Direct props / callbacks           |
+| **Auth**          | Via `SL.auth.getAccount()`        | Via `user` prop from parent        |
+
+---
+
+## Troubleshooting
+
+| Issue                      | Cause                                    | Fix                                                  |
+| -------------------------- | ---------------------------------------- | ---------------------------------------------------- |
+| Container doesn't render   | Missing shared globals                   | Ensure all Shared Dependencies are on `window`       |
+| Styles don't apply         | Missing `containers.css`                 | Load the CSS file alongside the JS bundle            |
+| 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              |

package/package.json

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