@proveanything/smartlinks 2.0.6 → 2.0.9

package/dist/docs/iframe-responder.md

@@ -468,3 +468,311 @@ import type {
 ### Portal back exits the app too early
 - Set `state.parentPath` on route changes for screens that should navigate "up" inside the app.
 - Make sure the receiving app listens for `smartlinks-navigate` if the SDK version in use does not already handle it.
+
+---
+
+## Streaming in a hand-rolled parent (without IframeResponder)
+
+The following applies **only if you build your own parent proxy** instead of using the `IframeResponder` class above — which already handles AI streaming for you. It is the wire protocol for forwarding SSE/streaming responses to a child app in proxy mode.
+### Goal
+
+Keep the existing architecture:
+
+- local mode: child calls API directly
+- iframe proxy mode: child never owns auth state and streams through the parent
+
+This keeps user/session authority in the parent while making AI streaming behave like the rest of the SDK transport.
+
+### What changed
+
+Previously, proxy mode only supported one-shot request/response messages:
+
+- `_smartlinksProxyRequest`
+- `_smartlinksProxyResponse`
+
+Streaming now adds a second protocol for long-lived responses:
+
+- `_smartlinksProxyStreamRequest`
+- `_smartlinksProxyStream`
+- `_smartlinksProxyStreamAbort`
+
+### New parent message handling
+
+#### 1. Listen for stream requests
+
+The iframe child may now send this message:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id: string,
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: any,
+  headers?: Record<string, string>
+}
+```
+
+Parent behavior:
+
+- treat this like a proxied API request
+- build the real API URL from your configured base URL plus `path`
+- send the request using the parent's current auth/session context
+- expect an SSE / streaming response body
+- keep the request open until the stream ends or is aborted
+
+#### 2. Forward stream lifecycle messages back to the child
+
+The parent should send messages back to the iframe using this envelope:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id: string,
+  phase: 'open' | 'event' | 'end' | 'error',
+  data?: any,
+  error?: string,
+  status?: number
+}
+```
+
+Phases:
+
+- `open`
+  - optional but recommended
+  - indicates the upstream streaming request was accepted and a body exists
+- `event`
+  - contains one parsed JSON event from an SSE `data:` frame
+  - send one message per logical event payload
+- `end`
+  - sent once when the stream finishes normally
+- `error`
+  - sent if the upstream request fails before or during streaming
+
+#### 3. Support abort from the child
+
+The child may stop reading early and send:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id: string
+}
+```
+
+Parent behavior:
+
+- look up the active stream by `id`
+- abort the underlying fetch / reader
+- clean up any local state for that stream
+- do not keep streaming after abort
+
+### SSE forwarding rules
+
+The upstream AI endpoints return SSE-like frames. The parent should:
+
+- read the response body as a stream
+- buffer text until line boundaries
+- collect `data:` lines for a single event
+- join multi-line `data:` payloads with `\n`
+- ignore blank events
+- stop on `data: [DONE]`
+- JSON-parse each event payload
+- forward parsed payloads to the iframe as `_smartlinksProxyStream` with `phase: 'event'`
+
+Minimal parsing behavior:
+
+1. accumulate bytes into text
+2. split on `\r?\n`
+3. collect each `data:` line
+4. on blank line, finalize the event
+5. if payload is `[DONE]`, finish
+6. otherwise `JSON.parse(payload)` and forward
+
+### Auth and session expectations
+
+The parent remains the source of truth for auth.
+
+That means the parent stream handler should:
+
+- use the same auth headers/token source as normal proxied requests
+- not require the iframe to know the bearer token or API key
+- naturally pick up the current logged-in user when the stream starts
+- cancel active streams if your app invalidates session state on logout or account switch
+
+In practice, the stream request should use the same header-building logic as your normal parent proxy transport.
+
+### Error handling expectations
+
+If the upstream fetch returns a non-2xx status:
+
+- try to read the JSON error body
+- derive a useful message
+- send one `_smartlinksProxyStream` message with `phase: 'error'`
+- include `status` when available
+- do not send `end` afterward
+
+If the stream body is missing unexpectedly:
+
+- send `phase: 'error'`
+
+If JSON parsing fails for a single event chunk:
+
+- safest behavior is to ignore that malformed chunk and continue
+
+### State the parent should keep
+
+Track active streams in a map keyed by `id`:
+
+```ts
+Map<string, AbortController>
+```
+
+Recommended cleanup points:
+
+- on normal stream end
+- on error
+- on child abort
+- on iframe detach/unmount
+- on parent auth reset/logout if you want all in-flight streams cancelled immediately
+
+### Parent implementation outline
+
+```ts
+const activeStreams = new Map<string, AbortController>()
+
+window.addEventListener('message', async (event) => {
+  const msg = event.data
+
+  if (msg?._smartlinksProxyStreamAbort && msg.id) {
+    activeStreams.get(msg.id)?.abort()
+    activeStreams.delete(msg.id)
+    return
+  }
+
+  if (msg?._smartlinksProxyStreamRequest && msg.id) {
+    const controller = new AbortController()
+    activeStreams.set(msg.id, controller)
+
+    try {
+      const response = await fetch(buildUrl(msg.path), {
+        method: msg.method,
+        headers: msg.headers,
+        body: msg.body ? JSON.stringify(msg.body) : undefined,
+        signal: controller.signal,
+      })
+
+      if (!response.ok || !response.body) {
+        postError(...)
+        return
+      }
+
+      postOpen(...)
+      await forwardSse(response.body, parsed => postEvent(...parsed))
+      postEnd(...)
+    } catch (err) {
+      if (err?.name !== 'AbortError') postError(...)
+    } finally {
+      activeStreams.delete(msg.id)
+    }
+  }
+})
+```
+
+### Exact protocol summary
+
+#### Child → parent
+
+Standard stream request:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id,
+  method,
+  path,
+  body,
+  headers
+}
+```
+
+Abort request:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id
+}
+```
+
+#### Parent → child
+
+Open:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'open'
+}
+```
+
+Event:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'event',
+  data: parsedJsonEvent
+}
+```
+
+End:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'end'
+}
+```
+
+Error:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'error',
+  error: 'message',
+  status?: number
+}
+```
+
+### What does not change
+
+These parts of the parent iframe integration stay the same:
+
+- normal `_smartlinksProxyRequest` request/response flow
+- upload proxy flow
+- auth login/logout postMessage handling
+- route/deep-link handling
+- resize handling
+
+This is an additive protocol, not a replacement.
+
+### Current SDK reference
+
+The SDK implementation lives in:
+
+- [src/http.ts](src/http.ts)
+- [src/iframeResponder.ts](src/iframeResponder.ts)
+- [src/types/iframeResponder.ts](src/types/iframeResponder.ts)
+- [src/api/ai.ts](src/api/ai.ts)
+
+### Practical recommendation
+
+If your parent already uses `IframeResponder`, prefer upgrading to the SDK version with these changes instead of re-implementing the protocol manually.
+
+If your parent has a custom iframe bridge, implement exactly the three new message types above and reuse your existing auth/header logic from normal proxied requests.

package/dist/docs/item-context.md

@@ -1,7 +1,5 @@
 # Item Context (container prop)
 
-> **Copy this file into `node_modules/@proveanything/smartlinks/docs/item-context.md`** in the published SDK package.
-
 When the URL points at a specific item — either a **serial proof URL** or an
 **NFC tap** — the portal derives an `ItemContext` describing what it found
 and hands it to the container as the **`itemContext`** prop.

package/dist/docs/manifests.md

@@ -32,7 +32,7 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
     "instanceResolution": true,
     "instanceParam": "widgetId",
     "files": {
-      "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.es.js" },
+      "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.esm.js" },
       "css": null
     },
     "components": [
@@ -46,13 +46,13 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
   },
   "containers": {
     "files": {
-      "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.es.js" },
+      "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.esm.js" },
       "css": null
     },
     "components": [{ "name": "PublicContainer", "description": "Full app view." }]
   },
   "executor": {
-    "files": { "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.es.js" } },
+    "files": { "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.esm.js" } },
     "factory": "createMyAppExecutor",
     "exports": ["createMyAppExecutor", "getSEO", "getLLMContent"],
     "description": "Programmatic configuration and SEO API for My App."

package/dist/docs/mobile-admin-container.md

@@ -1,6 +1,6 @@
 # Mobile Admin Container SDK
 
-> **Version:** 1.0 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+> **Version:** 1.0 · **Platform:** SmartLinks R5 · **Last updated:** 2026-09-21
 
 This document describes how to build a **Mobile Admin Container** — a SmartLinks microapp that provides an in-the-field operator/admin surface optimised for mobile devices. These containers ship as a **separate `mobileAdmin` bundle** (not inside the `containers` bundle) so that Capacitor plugins, offline helpers, and operator-only code never reach the public consumer bundle.
 
@@ -271,7 +271,7 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
   "meta": { "appId": "my-app", "name": "My App", "version": "1.0.0" },
 
   "containers": {
-    "files": { "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.es.js" }, "css": "dist/containers.css" },
+    "files": { "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.esm.js" }, "css": "dist/containers.css" },
     "components": [
       { "name": "PublicContainer", "description": "Default consumer experience" }
     ]
@@ -281,7 +281,7 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
     "files": {
       "js": {
         "umd": "dist/mobile-admin.umd.js",
-        "esm": "dist/mobile-admin.es.js"
+        "esm": "dist/mobile-admin.esm.js"
       },
       "css": null
     },
@@ -416,7 +416,7 @@ The mobile admin bundle has its own Vite config: `vite.config.mobile-admin.ts`.
 
 ```
 dist/mobile-admin.umd.js
-dist/mobile-admin.es.js
+dist/mobile-admin.esm.js
 dist/mobile-admin.css    (if needed)
 ```
 

package/dist/docs/mpa.md

@@ -56,9 +56,9 @@ vite build
 | Step | Config / Script | Gate env var | Output |
 |------|----------------|-------------|--------|
 | 1 | `vite.config.ts` | Always runs | `index.html`, `admin.html`, `assets/*` |
-| 2 | `vite.config.widget.ts` | `VITE_ENABLE_WIDGETS=true` | `widgets.umd.js`, `widgets.es.js`, `widgets.css` |
-| 3 | `vite.config.container.ts` | `VITE_ENABLE_CONTAINERS=true` | `containers.umd.js`, `containers.es.js`, `containers.css` |
-| 4 | `vite.config.executor.ts` | `VITE_ENABLE_EXECUTOR!=false` | `executor.umd.js`, `executor.es.js` |
+| 2 | `vite.config.widget.ts` | `VITE_ENABLE_WIDGETS=true` | `widgets.umd.js`, `widgets.esm.js`, `widgets.css` |
+| 3 | `vite.config.container.ts` | `VITE_ENABLE_CONTAINERS=true` | `containers.umd.js`, `containers.esm.js`, `containers.css` |
+| 4 | `vite.config.executor.ts` | `VITE_ENABLE_EXECUTOR!=false` | `executor.umd.js`, `executor.esm.js` |
 | 5 | `scripts/hash-bundles.mjs` | Always runs | Renames bundles with content hashes; patches `dist/app.manifest.json` |
 
 Steps 2–4 produce a harmless stub file when their gate env var is not set. Step 5 detects and skips stub files automatically.
@@ -107,7 +107,7 @@ dist/
 └── executor-[hash].es.js           ← Executor bundle (ESM)
 ```
 
-> Widget and container CSS files are only present when the bundle ships custom styles. Most apps set `"css": null` in the manifest because they rely entirely on Tailwind/shadcn from the parent. See the [AI-Native App Manifests](manifests.md) guide for the CSS null warning.
+> Widget and container CSS files are only present when the bundle ships custom styles. Most apps set `"css": null` in the manifest because they rely entirely on Tailwind/shadcn from the parent. See the [App Configuration Files](app-manifest.md) for the CSS null warning.
 
 ---
 
@@ -133,6 +133,6 @@ If the embedded app exposes nested screens, document its "up" navigation path wi
 | [Widgets](widgets.md) | Widget bundle: components, props, settings |
 | [Containers](containers.md) | Container bundle: full-app embeds |
 | [Executor Model](executor.md) | Executor bundle: SEO, LLM content, config mutations |
-| [AI-Native App Manifests](manifests.md) | How manifests wire all bundles together for AI discovery |
+| [App Configuration Files](app-manifest.md) | Manifest + admin reference; widget settings schema; AI workflows |
 | [iframe Responder](iframe-responder.md) | Reading context params inside the iframe |
 | [Portal Back Button](portal-back-button.md) | Hierarchy-aware back navigation for embedded apps |

package/dist/docs/native-facade.md

@@ -1,6 +1,6 @@
 # Native Capability Facade (`host.native` / `SL.native`)
 
-> **Version:** 1.12 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+> **Version:** 1.12 · **Platform:** SmartLinks R5 · **Last updated:** 2026-09-21
 
 The `NativeFacade` is a thin contract layer between microapps and the device capabilities available on the current host shell (Kotlin, Capacitor iOS/Android, PWA, or browser). It lets a microapp call `host.native.share.share({...})` without knowing whether it's running over `window.SmartlinksScanner`, a Capacitor plugin, or `navigator.share`.
 

package/dist/docs/overview.md

@@ -1,25 +1,21 @@
 # SmartLinks Microapp Development Guide
 
-> **Platform revision:** R5 · **SDK:** `@proveanything/smartlinks@^2` (current `latest`, 2.0.5) · React 19 · Vite 8 · Tailwind 4  
-> **Last updated:** 2026-03-03
+> **Platform revision:** R5 · **SDK:** `@proveanything/smartlinks@^2` · React 19 · Vite 8 · Router 7 · Tailwind 4 · TS 6.
+> The canonical version/host stack lives in [host-dependency-contract.md](host-dependency-contract.md).
 
 ---
 
 ## What Is a SmartLinks Microapp?
 
-SmartLinks microapps are **modular, embeddable React applications** that extend the SmartLinks digital twin platform. They provide specialised functionality — product information displays, warranty registration, competitions, pamphlet generators, and more — while inheriting context, authentication, and theming from the parent platform.
+SmartLinks connects **physical products to digital experiences**: each item has a digital identity — a **proof** — that a consumer reaches by scanning a QR / NFC tag, then claims and enriches over time. A **microapp** is a focused, embeddable React experience a brand adds to that product's digital life: product info, warranty registration, authenticity checks, manuals, competitions, loyalty, post-purchase support, and more.
 
-### The Digital Twin Ecosystem
+Rather than baking every feature into the core platform, functionality is distributed across purpose-built apps, so a brand adds exactly the experiences its product needs. Each app:
 
-SmartLinks is a **digital twin platform** that connects physical products to digital experiences. Each physical item (a wine bottle, a luxury handbag, a piece of equipment) has a corresponding digital identity — a "proof" — that can be scanned, claimed, and enriched with data over time.
-
-Microapps are the **extensibility layer** of this ecosystem. Rather than building monolithic features into the core platform, functionality is distributed across purpose-built apps that:
-
-- **Embed seamlessly** via iframes in the SmartLinks Portal (public) and Admin Console (management)
-- **Share context** through URL parameters (collection, product, or proof being viewed)
-- **Inherit identity** from the parent platform's authentication system
-- **Adapt visually** to the brand's theme configuration
-- **Communicate bidirectionally** with the parent via postMessage for deep linking and navigation
+- **Embeds** in the SmartLinks Portal (public) and Admin Console (management)
+- **Shares context** through URL parameters (collection, product, proof)
+- **Inherits identity** from the parent platform's auth
+- **Adapts** to the brand's theme
+- **Communicates** with the parent via postMessage for deep linking and navigation
 
 ### Deployment Modes
 
@@ -45,7 +41,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 
 > Product endpoints: use `products` (plural) for new integrations. The older `product` (singular) namespace remains for backward compatibility and is deprecated.
 
-> **Minimum SDK version: `1.4.1`** — Ensure `@proveanything/smartlinks` is at least this version. If not, update with `npm install @proveanything/smartlinks@latest`.
+> **SDK baseline: `@proveanything/smartlinks@^2.0`** (R5). Install/update with `npm install @proveanything/smartlinks@^2.0`. Individual features may need a higher minor — see the relevant doc. The single source of truth for the R5 host/version stack is [`host-dependency-contract.md`](host-dependency-contract.md).
 
 | Topic | File | When to Use |
 |-------|------|-------------|
@@ -71,7 +67,6 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
-| **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
 | **Real-time Messaging** | `docs/realtime.md` | Adding Ably real-time features (chat, live updates) |
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
@@ -89,6 +84,21 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Proof Share Grants** | `docs/proof-share-grants.md` | Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner) |
 | **Proof Ownership Transfer** | `docs/proof-ownership-transfer.md` | Moving a proof's single owner (directed transfer / open release), accept/cancel, and the state machine |
 | **appConfig / Feature Flags** | `docs/appConfig.md` | `appConfig` settings contract — installed apps, `system.features`/`entitledAppGroups`/`meters`, `isFeatureEnabled()` helper |
+| **App Objects** | `docs/app-objects.md` | Queryable domain objects — `app.records` / `app.cases` / `app.threads`: JSONB zones, visibility, policies, aggregations |
+| **App Data Storage** | `docs/app-data-storage.md` | Decision guide: pick between `appConfiguration` / `userAppData` / `app.records` |
+| **Attestations** | `docs/attestations.md` | Postgres attestations API (proof-level user/admin data; replaces the legacy Firestore path) |
+| **Caching** | `docs/caching.md` | SDK GET cache tiers + TTLs, `invalidateCache({ exact })`, and `force`/push guidance |
+| **Comms & Broadcasts** | `docs/comms.md` | Transactional comms, campaigns, consent, push |
+| **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
+| **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
+| **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
+| **Sequences** | `docs/sequences.md` | Atomic monotonic number allocation (raffle / queue / edition) |
+| **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
+| **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
+| **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |
+| **Product Facets** | `docs/PRODUCT_FACETS_SDK.md` | Facet API reference (admin + public endpoints, types) |
+| **AI Tools & Skills** | `docs/ai-tools-and-skills.md` | Platform AI capability registry (web research, extraction, images) |
+| **Proof Comms Triggers** | `docs/proof-comms-triggers.md` | Transactional comms fired as a side-effect of proof actions |
 
 ---
 
@@ -99,6 +109,15 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 - **Context via URL params** — All contextual data is passed through URL parameters
 - **SmartLinks NPM module** — All data access and platform interaction goes through `@proveanything/smartlinks`
 - **No standalone auth** — Authentication is handled by the parent SmartLinks platform
+
+> **Use the host-provided `SL`, don't instantiate your own.** When your app runs in a
+> container/iframe, the host injects an already-initialized, authenticated SDK instance (the
+> `SL` prop / the externalized `@proveanything/smartlinks` singleton). Import and use *that*.
+> Calling `initializeApi()` yourself to spin up a **second** SDK instance is a common source
+> of bugs: it won't share the host's auth (so it looks signed-out), won't share the host's
+> cache (duplicate requests, stale data), and in proxy mode it bypasses the host's request
+> routing. Rule of thumb: **host-provided `SL` for anything the platform owns** (auth, config,
+> data, cache); only app-owned state is yours.
 - **Multi-page build** — Separate bundles for public and admin — see `docs/mpa.md`
 - **Embedded back navigation** — Use `docs/portal-back-button.md` when a sub-app has a real content hierarchy
 

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

@@ -1,8 +1,7 @@
 # Portal Back Button — "Up" Navigation Inside Sub-Apps
 
-> **For sub-app authors.** Drop this file into the SmartLinks SDK docs (e.g.
-> `docs/portal-back-button.md`) and link it from `routing.md` / `mpa.md` so
-> microapp authors discover it.
+> **For sub-app authors.** How to cooperate with the portal shell's top-level
+> back/up control. See also [`mpa.md`](mpa.md).
 
 When a sub-app is embedded by a portal shell, the shell renders a top-level
 back button. By default that button **exits the app entirely** when tapped —

package/dist/docs/widgets.md

@@ -14,7 +14,7 @@ Widgets are self-contained React components that:
 
 ```text
 ┌─────────────────────────────────────────────────────────────────┐
-│ Parent SmartLinks Portal (React 18)                             │
+│ Parent SmartLinks Portal (React 19)                             │
 │                                                                 │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
 │  │ Competition  │  │ Music App    │  │ Warranty     │          │
@@ -53,53 +53,7 @@ Widgets are typically single-view components and don't need internal routing. If
 
 ### 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]);
-}
-```
+Widgets read their context through the shared **`useAppContext()`** hook so the same code works in both direct-component and iframe modes. The hook and `AppContext` provider are defined once — see **[building-react-components.md](building-react-components.md#the-useappcontext-pattern)** for the full implementation (don't re-define it per app).
 
 **Usage in your widget:**
 
@@ -344,7 +298,7 @@ Declare support in `app.manifest.json`:
     "files": {
       "js": {
         "umd": "dist/widgets.umd.js",
-        "esm": "dist/widgets.es.js"
+        "esm": "dist/widgets.esm.js"
       },
       "css": null
     },
@@ -511,7 +465,7 @@ export { MyWidget } from './MyWidget';
 // Update the manifest
 export const WIDGET_MANIFEST = {
   version: '1.0.0',
-  reactVersion: '18.x',
+  reactVersion: '19.x',
   widgets: [
     // ... existing widgets
     {
@@ -570,7 +524,7 @@ The project includes a separate Vite config for building widgets:
 # Build widgets only
 vite build --config vite.config.widget.ts
 
-# Output: dist/widgets.es.js
+# Output: dist/widgets.esm.js
 ```
 
 ### Build Configuration
@@ -582,23 +536,11 @@ The widget build:
 - Minifies with esbuild for production
 - Outputs to `/dist` alongside the main app (not a separate folder)
 
-### Externalized Dependencies (Peer Dependencies)
-
-The widget bundle does **not** include these libraries—the parent app must provide them:
+### Externalized dependencies
 
-| Package | Why Externalized |
-|---------|------------------|
-| `react`, `react-dom` | Parent's React context |
-| `@proveanything/smartlinks` | Passed via props as `SL` |
-| `@proveanything/smartlinks-auth-ui` | Auth UI components (also available globally as `window.SmartlinksAuthUI`) |
-| `tailwind-merge` | Utility for merging Tailwind classes |
-| `clsx` | Utility for conditional class names |
-| `class-variance-authority` | Utility for component variants |
+The widget bundle does **not** include the host's shared libraries (React, the SDK, Radix, LiquidJS, …) — it **externalizes** them and resolves them from the host at runtime, so the bundle stays tiny and there's exactly one shared instance.
 
-These are standard packages that any modern React + Tailwind app will have. Externalizing them:
-1. Reduces bundle size significantly
-2. Removes JSDoc comments that inflate the bundle
-3. Ensures consistent behavior with parent's versions
+**The canonical, versioned list is the shared-dependency contract — don't hand-maintain your own here.** Import it from the SDK (`SHARED_DEPENDENCY_SPECIFIERS`) for your build's `external` list, and see **[host-dependency-contract.md](host-dependency-contract.md)** for the full table, the Vite `external`/`globals` config, and the *never bundle your own React* rule. `@proveanything/smartlinks-auth-ui` is externalized too (host global `window.SmartlinksAuthUI`) — do not ship a second copy.
 
 ### Enabling Widget Builds
 
@@ -626,7 +568,7 @@ import * as SL from '@proveanything/smartlinks';
 
 // Dynamic import from app's CDN
 const CompetitionWidget = lazy(() => 
-  import('https://competition-app.example.com/widgets.es.js')
+  import('https://competition-app.example.com/widgets.esm.js')
     .then(m => ({ default: m.CompetitionWidget }))
 );
 
@@ -670,7 +612,7 @@ import { WidgetWrapper, CompetitionWidget } from 'competition-app/widgets';
 import { WIDGET_MANIFEST } from 'competition-app/widgets';
 
 // Verify React version compatibility
-if (!WIDGET_MANIFEST.reactVersion.startsWith('18')) {
+if (!WIDGET_MANIFEST.reactVersion.startsWith('19')) {
   console.warn('Widget React version mismatch');
 }
 
@@ -741,7 +683,7 @@ Each app exports a `WIDGET_MANIFEST` for discovery:
 ```typescript
 export const WIDGET_MANIFEST = {
   version: '1.0.0',        // Widget bundle version
-  reactVersion: '18.x',    // Required React version
+  reactVersion: '19.x',    // Required React version
   widgets: [
     {
       name: 'ExampleWidget',