@proveanything/smartlinks 2.0.6 → 2.0.10

package/docs/app-manifest.md

@@ -40,7 +40,9 @@ The manifest is loaded automatically by the platform for every collection page.
     "name": "My App",
     "description": "A short human-readable description of what this app does.",
     "version": "1.2.0",
-    "platformRevision": "2026-01-01"
+    "platformRevision": "R5",
+    "moduleFormat": "dual",
+    "sharedDependencies": "v5"
   },
 
   "admin": "app.admin.json",
@@ -51,7 +53,7 @@ The manifest is loaded automatically by the platform for every collection page.
     "files": {
       "js": {
         "umd": "dist/widgets.umd.js",
-        "esm": "dist/widgets.es.js"
+        "esm": "dist/widgets.esm.js"
       },
       "css": "dist/widgets.css"
     },
@@ -75,7 +77,7 @@ The manifest is loaded automatically by the platform for every collection page.
     "files": {
       "js": {
         "umd": "dist/containers.umd.js",
-        "esm": "dist/containers.es.js"
+        "esm": "dist/containers.esm.js"
       },
       "css": "dist/containers.css"
     },
@@ -95,7 +97,7 @@ The manifest is loaded automatically by the platform for every collection page.
     "files": {
       "js": {
         "umd": "dist/mobile-admin.umd.js",
-        "esm": "dist/mobile-admin.es.js"
+        "esm": "dist/mobile-admin.esm.js"
       },
       "css": null
     },
@@ -144,9 +146,56 @@ The manifest is loaded automatically by the platform for every collection page.
 | `name` | string | ✅ | Human-readable display name |
 | `description` | string | ❌ | Short description shown in app directories and AI context |
 | `version` | string | ✅ | SemVer string, e.g. `"1.2.0"` |
-| `platformRevision` | string | ❌ | ISO date string marking the platform API revision this build targets |
+| `platformRevision` | string | ❌ | Platform revision tag this build targets, e.g. `"R5"` (see [host-dependency-contract.md](host-dependency-contract.md)) |
+| `moduleFormat` | `"umd"` \| `"esm"` \| `"dual"` | ❌ | How the host loads this app's bundles. Absent = `"umd"`. See [Module format](#module-format-umd-vs-esm) below. |
+| `sharedDependencies` | string | ❌ | Shared-dependency contract version the bundle was built against, e.g. `"v5"`. Used by the host to pick a compatible ESM import map. |
+| `globals` | object | ❌ | Per-app namespaced UMD globals (R4.7+), e.g. `{ "widgets": "MyAppWidgets" }`. UMD-only; ESM bundles don't need it. |
 | `seo.priority` | number | ❌ | Controls which app's `title`/`description`/`ogImage` wins when multiple apps are on the same page. Default `0`; higher wins. See the [Executor guide](executor.md). |
 
+#### Module format (UMD vs ESM)
+
+The host provides shared libraries (React, Radix, the SmartLinks SDK, LiquidJS…) as **singletons**
+so apps never bundle their own. Two delivery mechanisms exist, and `meta.moduleFormat` tells the host
+which to use:
+
+| `moduleFormat` | Host behaviour |
+|---|---|
+| `"umd"` *(default)* | Loads `files.js.umd` via the CommonJS `require` shim; shared deps resolve from **window globals**. Every existing app works unchanged. |
+| `"dual"` | Prefers `files.js.esm` when the host has an **import map** for the declared `sharedDependencies` version; **falls back to UMD** otherwise. The safe transition setting. |
+| `"esm"` | Loads `files.js.esm` **natively**; if the host has no matching import map it fails with an actionable error rather than a bare-specifier crash. Use only once you know your hosts are on the contract. |
+
+The ESM bundle is declared in the **same** `files.js` block as `esm` (there is no separate `jsEsm`
+field):
+
+```jsonc
+"widgets": {
+  "files": {
+    "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.esm.js" },
+    "css": "dist/widgets.css"
+  }
+}
+```
+
+An ESM bundle **must externalize exactly the shared-dependency contract** — read it from the SDK
+(`SHARED_DEPENDENCY_SPECIFIERS`) rather than hard-coding it, and stamp the version you built against
+into `meta.sharedDependencies`. See [host-dependency-contract.md](host-dependency-contract.md).
+
+##### Validate before you ship: `smartlinks doctor`
+
+Run the checker (shipped with the SDK) against your built app — it reads the same contract the host
+serves, so the two can't drift:
+
+```bash
+npx smartlinks-doctor            # in the app dir, after building
+```
+
+It reads your manifest, and for every ESM surface confirms **every bare import in the bundle is a
+contract entry**. A correctly-externalized ESM bundle inlines everything except the host singletons,
+so anything else left as a bare import will either fail to resolve through the import map or silently
+double-load (the duplicate-React class of bug). It also warns when a UMD app still declares stale
+`*.es.js`/`*.esm.js` bundles the host will never load. Exit code is non-zero on violations, so it
+drops straight into CI.
+
 #### `build`
 
 Optional build provenance. Recommended for the **Lovable dev publish** flow: stamp the content
@@ -194,7 +243,7 @@ Apps such as widget toolkits often store reusable widget instances in collection
   "files": {
     "js": {
       "umd": "dist/widgets.umd.js",
-      "esm": "dist/widgets.es.js"
+      "esm": "dist/widgets.esm.js"
     },
     "css": null
   },
@@ -247,7 +296,7 @@ See [mobile-admin-container.md](mobile-admin-container.md) for the `AdminMobileH
   "files": {
     "js": {
       "umd": "dist/mobile-admin.umd.js",
-      "esm": "dist/mobile-admin.es.js"
+      "esm": "dist/mobile-admin.esm.js"
     },
     "css": null
   },
@@ -549,6 +598,56 @@ Declares what interactions and KPIs the app reports. Used by the platform's anal
 
 ---
 
+## Widget settings schema (JSON Schema)
+
+Each widget component's `settings` object uses **JSON Schema** to describe its configurable props, so schema-form renderers *and* AI orchestrators can auto-generate a config UI without per-widget code:
+
+```json
+"components": [
+  {
+    "name": "MyWidget",
+    "description": "What this widget does",
+    "sizes": ["compact", "standard", "large"],
+    "settings": {
+      "type": "object",
+      "properties": {
+        "displayMode": {
+          "type": "string", "title": "Display Mode",
+          "description": "How the widget renders",
+          "enum": ["compact", "standard", "large"],
+          "enumLabels": { "compact": "Icons only", "standard": "With names", "large": "Full cards" },
+          "default": "standard", "order": 1
+        },
+        "showImage": { "type": "boolean", "title": "Show Product Image", "default": true, "order": 2 }
+      }
+    }
+  }
+]
+```
+
+| Field | Purpose |
+|-------|---------|
+| `type`, `enum` | Standard JSON Schema validation |
+| `title` | Human-readable form label |
+| `description` | Help text shown alongside the field |
+| `enumLabels` | Friendly display names for enum values (`{ value → label }`) |
+| `default` | Pre-selected value when no config exists |
+| `order` | Field display order (lower number = higher) |
+
+The schema serves both AI orchestrators (understand what a widget accepts, configure it conversationally) and schema-form renderers (auto-generate settings UIs).
+
+## AI workflows the manifest enables
+
+SmartLinks manifests are **AI-discoverable, -configurable, and -importable**: the structured manifest plus the prose `ai-guide.md` (start from [ai-guide-template.md](ai-guide-template.md)) let AI systems set up and populate apps without custom integration code. Three workflows read the manifest:
+
+1. **Widget Builder** — reads `widgets.components[]` and each `settings` schema to embed a widget with correct props and auto-render its configuration UI.
+2. **Setup Wizard** — reads `setup` from `app.admin.json`: walks `setup.questions[]`, validates against `setup.configSchema`, optionally auto-generates content via `SL.ai`, then saves per `setup.saveWith`.
+3. **Data Importer** — reads `import` from `app.admin.json`: builds a CSV template from `import.fields[]`, normalises rows, and calls `import.saveWith.method` per row (multi-app imports merge fields into one CSV).
+
+When you change your config shape, keep all three in sync: `app.manifest.json` (widget `settings`, containers, executor, linkable), `app.admin.json` (setup / import / tunable), and `ai-guide.md` (prose guidance).
+
+This declarative model is canonical and works today. An app may **optionally** layer agent tools on top — a function that reads the declaration and returns a *context-adapted* result (e.g. "which setup questions for this collection?") — without changing the schema. That's additive and opt-in; see [agent-tools.md](agent-tools.md).
+
 ## Reading the Files at Runtime
 
 ### Manifest — available from the widgets endpoint

package/docs/app-objects.md

@@ -291,32 +291,6 @@ const summary = await app.cases.summary(collectionId, appId, {
 // Returns: { total: 142, byStatus: { open: 12, resolved: 130 }, ... }
 ```
 
-### Use Case: Support Dashboard
-
-Build a live support dashboard showing open cases by priority:
-
-```typescript
-const openCases = await app.cases.list(collectionId, appId, {
-  status: 'open',
-  sort: 'priority:desc',
-  limit: 50
-}, true);
-
-// Aggregate by category
-const stats = await app.cases.aggregate(collectionId, appId, {
-  filters: { status: 'open' },
-  groupBy: ['category', 'priority'],
-  metrics: ['count']
-}, true);
-
-// Time series: cases created per week
-const trend = await app.cases.aggregate(collectionId, appId, {
-  timeSeriesField: 'created_at',
-  timeSeriesInterval: 'week',
-  metrics: ['count']
-}, true);
-```
-
 ---
 
 ## Threads
@@ -382,53 +356,6 @@ await app.threads.update(collectionId, appId, question.id, {
 }, true);
 ```
 
-### Use Case: Forum-Style Discussions
-
-List recent discussions with reply counts:
-
-```typescript
-// Get active threads
-const activeThreads = await app.threads.list(collectionId, appId, {
-  status: 'open',
-  sort: 'lastReplyAt:desc',
-  limit: 20
-});
-
-// Filter by tag
-const cleaningThreads = await app.threads.list(collectionId, appId, {
-  tag: 'cleaning'
-});
-
-// Aggregate: most active discussion topics
-const topicStats = await app.threads.aggregate(collectionId, appId, {
-  groupBy: ['status'],
-  metrics: ['count', 'reply_count']
-});
-```
-
-### Use Case: Product Comments
-
-Attach comments to a specific product:
-
-```typescript
-// Create a comment thread for a product
-await app.threads.create(collectionId, appId, {
-  visibility: 'public',
-  parentType: 'product',
-  parentId: product.id,
-  authorId: user.contactId,
-  body: { text: 'Love this product! Best purchase ever.' },
-  tags: ['positive']
-});
-
-// List all comments for a product
-const productComments = await app.threads.list(collectionId, appId, {
-  parentType: 'product',
-  parentId: product.id,
-  sort: 'createdAt:desc'
-});
-```
-
 ### Anchoring to app entities and proofs
 
 Anchor a thread to your own entity with `parentType` + `parentId`. `parentId` is a
@@ -948,81 +875,6 @@ const expiringSoon = await app.records.list(collectionId, appId, {
 }, true);
 ```
 
-### Example: Appointment Booking
-
-```typescript
-// Customer books a service appointment
-const booking = await app.records.create(collectionId, appId, {
-  recordType: 'service_appointment',
-  visibility: 'owner',
-  contactId: user.contactId,
-  startsAt: '2026-03-15T10:00:00Z',
-  expiresAt: '2026-03-15T11:00:00Z', // 1-hour appointment
-  data: {
-    serviceType: 'installation',
-    location: 'Customer site',
-    technician: null // assigned later
-  },
-  owner: {
-    address: '123 Main St',
-    phone: '555-1234',
-    notes: 'Call before arrival'
-  }
-});
-
-// Admin assigns technician
-await app.records.update(collectionId, appId, booking.id, {
-  data: {
-    serviceType: 'installation',
-    location: 'Customer site',
-    technician: 'tech_john'
-  },
-  admin: {
-    cost: 150.00,
-    travelTime: 30
-  }
-}, true);
-
-// List today's appointments
-const today = new Date().toISOString().split('T')[0];
-const todaysAppointments = await app.records.list(collectionId, appId, {
-  recordType: 'service_appointment',
-  startsAt: `gte:${today}T00:00:00Z`,
-  sort: 'startsAt:asc'
-}, true);
-```
-
-### Example: Usage Tracking
-
-```typescript
-// Log product usage (could be triggered by IoT device)
-await app.records.create(collectionId, appId, {
-  recordType: 'usage_log',
-  visibility: 'admin',
-  productId: product.id,
-  proofId: proof.id,
-  startsAt: new Date().toISOString(),
-  data: {
-    metric: 'power_on',
-    duration: 3600, // seconds
-    location: 'geo:37.7749,-122.4194'
-  }
-}, true);
-
-// Aggregate usage metrics
-const usageStats = await app.records.aggregate(collectionId, appId, {
-  filters: {
-    record_type: 'usage_log',
-    created_at: {
-      gte: '2026-02-01',
-      lte: '2026-02-28'
-    }
-  },
-  groupBy: ['product_id'],
-  metrics: ['count']
-}, true);
-```
-
 ---
 
 ## Public Create Policies

package/docs/app-records-pattern.md

@@ -6,7 +6,7 @@
 >
 > Status: **standard**. New apps MUST follow this contract; existing apps SHOULD migrate.
 >
-> SDK: `@proveanything/smartlinks` ≥ **1.11**.
+> SDK: `@proveanything/smartlinks` ≥ **2.0** (R5).
 > Admin shell (React only): `@proveanything/smartlinks-utils-ui` ≥ **0.7.6** — required for the admin side if using the React shell; not needed in public widgets.
 
 ---
@@ -347,7 +347,7 @@ interface EditorContext<TData> {
 
 ## 7. Migration checklist (existing apps)
 
-1. **Update SDKs:** `@proveanything/smartlinks@^1.11`, `@proveanything/smartlinks-utils-ui@^0.7.6`.
+1. **Update SDKs:** `@proveanything/smartlinks@^2.0`, `@proveanything/smartlinks-utils-ui@^2.0`.
 2. **Add `cardinality` and `allowFacetRules`** to every entry under `records` in `app.admin.json`.
 3. **Add `'rule'` (and `'collection'` if missing) to `scopes`** wherever `allowFacetRules: true`.
 4. **Pass `cardinality`** to `<RecordsAdminShell>`.

package/docs/building-react-components.md

@@ -212,26 +212,18 @@ In **direct-component mode**, there are no URL search params — context comes a
 
 **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:
+**Fix:** Externalize the shared-dependency contract — read it from the SDK so it can't drift:
 
 ```ts
 // vite.config.container.ts or vite.config.widget.ts
+import { SHARED_DEPENDENCY_SPECIFIERS } from '@proveanything/smartlinks'
 export default defineConfig({
-  build: {
-    rollupOptions: {
-      external: [
-        'react',
-        'react-dom',
-        'react/jsx-runtime',
-        'react-router-dom',
-        '@proveanything/smartlinks',
-        // ... other shared dependencies
-      ],
-    },
-  },
+  build: { rollupOptions: { external: [...SHARED_DEPENDENCY_SPECIFIERS] } },
 });
 ```
 
+> The full list + `globals` map is canonical in [host-dependency-contract.md](host-dependency-contract.md). Never bundle your own React (two instances = a hard crash).
+
 ---
 
 ### ❌ Context values are undefined in direct-component mode
@@ -320,4 +312,4 @@ Now that you understand the core concepts, see the implementation guides:
 - [deep-link-discovery.md](./deep-link-discovery.md) — Deep linking patterns
 - [portal-back-button.md](./portal-back-button.md) — Portal shell back-button behavior for hierarchical embeds
 - [portal-auth-broadcast.md](./portal-auth-broadcast.md) — Custom authentication and session broadcast
-- [manifests.md](./manifests.md) — App manifest configuration
+- [app-manifest.md](./app-manifest.md) — App configuration files (manifest + admin)

package/docs/caching.md

@@ -119,13 +119,32 @@ Different API resources have different cache lifetimes:
 ```typescript
 import { invalidateCache } from '@smartlinks/sdk';
 
-// Clear cache for a specific collection
+// Substring match (default): clears the collection AND everything under it
+// (settings, widgets, products, proofs) — a prefix wipe.
 invalidateCache('/collection/abc123');
 
+// Exact match: clears ONLY that entry, not its sub-resources. Use this to avoid
+// accidental cascade wipes.
+invalidateCache('/collection/abc123', { exact: true });
+
 // Clear all product caches
 invalidateCache('/product/');
 ```
 
+### Don't force-refresh from a container-hosted app
+
+`getWidgets(collectionId, { force: true })` (and `getAppConfig(..., { force: true })`)
+bypass the cache and re-fetch. Inside a **container/iframe app**, the host has usually
+already fetched that data and shares its own cache — forcing a refetch duplicates the
+request the host just made. `force: true` was a **polling-era workaround** for not being
+able to tell when something changed; **prefer the default (cached) path** in hosted apps.
+
+> **Direction:** the platform is moving to a **push-based** model — app/config updates are
+> pushed centrally and invalidate the relevant caches immediately, so a normal GET returns
+> fresh data (and, with conditional requests/ETags, returns "not modified" cheaply) without
+> anyone polling or forcing. As that lands, `force: true` should disappear from app code
+> entirely. Don't build new flows around it.
+
 ### Clear All Caches
 
 ```typescript
@@ -164,23 +183,3 @@ try {
 }
 ```
 
-## Migration from Old Behavior
-
-If you previously relied on caches persisting across refreshes:
-
-```typescript
-// Old (implicit) behavior:
-// - SessionStorage survived refreshes
-// - Apps might see stale data after F5
-
-// New (explicit) behavior:
-configureSdkCache({
-  clearOnPageLoad: true, // default - fresh data on refresh
-});
-
-// If you REALLY need old behavior (not recommended):
-configureSdkCache({
-  clearOnPageLoad: false,
-  persistence: 'indexeddb', // move to IndexedDB instead
-});
-```

package/docs/container-tracking.md

@@ -1,6 +1,8 @@
 # Container Tracking
 
 > Physical or logical groupings with hierarchical nesting, item membership, and attestation history.
+>
+> **Not [containers.md](containers.md)** — that's the embeddable app *bundle*. This doc is about grouping physical/logical **items** (cases, pallets, shipments…).
 
 ---
 

package/docs/containers.md

@@ -1,6 +1,6 @@
 # SmartLinks Containers
 
-> **Copy this file into `node_modules/@proveanything/smartlinks/docs/containers.md`** in the published SDK package.
+> **Not [container-tracking.md](container-tracking.md).** This doc is the embeddable full-app **bundle**; that one is about grouping physical/logical *items*.
 
 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.
 
@@ -15,7 +15,7 @@ Containers are the **full public app experience** packaged as an embeddable Reac
 | **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`    |
+| **Build output**| `widgets.umd.js` / `widgets.esm.js` | `containers.umd.js` / `containers.esm.js`    |
 
 ### Why Separate Bundles?
 
@@ -104,54 +104,7 @@ export const PublicContainer = (props: Record<string, any>) => {
 
 ### 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]);
-}
-```
+Containers read their context through the same shared **`useAppContext()`** hook as widgets, so one codebase works in both direct-component and iframe modes. See **[building-react-components.md](building-react-components.md#the-useappcontext-pattern)** for the canonical hook + `AppContext` provider — don't re-define it. Containers additionally carry an **`initialPath?`** field on the context (the entry route the host asked for).
 
 **Usage in your container:**
 
@@ -323,7 +276,7 @@ Parent App (owns URL bar, provides globals)
 
 ```typescript
 // Lazy-load the container only when needed
-const { PublicContainer } = await import('https://my-app.com/containers.es.js');
+const { PublicContainer } = await import('https://my-app.com/containers.esm.js');
 
 <PublicContainer
   collectionId="abc"
@@ -345,27 +298,22 @@ const { PublicContainer } = await import('https://my-app.com/containers.es.js');
 <!-- 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
+  // The UMD global is PER-APP NAMESPACED — read the name from the manifest
+  // (manifest.meta.globals.containers), e.g. "SmartLinksContainers__myApp".
+  // Do NOT use a bare `window.SmartLinksContainers` — it collides across apps.
+  const globalName = manifest.meta.globals.containers;
+  const { PublicContainer } = window[globalName];
+  // Render with React (or prefer the ESM path: import from containers.esm.js)
 </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)
+## Shared dependencies
 
-See `widgets.md` for the complete table with globals and version expectations.
+Containers externalize the **exact same shared-dependency contract** as widgets — resolved from host globals (UMD) or the import map (ESM); no extra globals are needed. **The full versioned list, window-global names, and Vite `external`/`globals` config are canonical in [host-dependency-contract.md](host-dependency-contract.md)** — externalize exactly that set (from the SDK's `SHARED_DEPENDENCY_SPECIFIERS`) and never bundle your own React.
 
-> **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.
+> **Why `CVA` not `cva`?** `class-variance-authority` exports a function named `cva`; if the UMD global were also `cva`, the wrapper resolves it as `window.cva.cva` — a double-nesting bug. The contract uses uppercase `CVA` to avoid the collision.
 
 ---
 
@@ -396,7 +344,7 @@ vite build --config vite.config.container.ts
 ```text
 dist/
 ├── containers.umd.js    # Full app container (UMD)
-├── containers.es.js     # Full app container (ESM)
+├── containers.esm.js    # Full app container (ESM)
 └── containers.css       # Container styles
 ```
 

package/docs/executor.md

@@ -1,12 +1,12 @@
 # SmartLinks Executor Model
 
-> **SDK minimum:** `@proveanything/smartlinks@1.4.1`
+> **SDK:** `@proveanything/smartlinks@^2.0` (R5 baseline; build against 2.0.7+)
 
 ---
 
 ## What Is an Executor?
 
-An executor is a **standalone JavaScript library** (`executor.umd.js` / `executor.es.js`) that a SmartLinks app ships alongside its widget and container bundles. It exposes programmatic functions that external systems — AI orchestrators, the Hub server, setup wizards — can call **without rendering the app's UI**.
+An executor is a **standalone JavaScript library** (`executor.umd.js` / `executor.esm.js`) that a SmartLinks app ships alongside its widget and container bundles. It exposes programmatic functions that external systems — AI orchestrators, the Hub server, setup wizards — can call **without rendering the app's UI**.
 
 Every app can optionally ship an executor. The executor pattern solves three problems that iframe-based apps can't address on their own:
 
@@ -38,7 +38,7 @@ Every executor is declared in `app.manifest.json` so the platform can discover a
   },
   "executor": {
     "files": {
-      "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.es.js" }
+      "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.esm.js" }
     },
     "factory": "createMyAppExecutor",
     "exports": ["createMyAppExecutor", "getSEO", "getLLMContent"],
@@ -61,7 +61,7 @@ Every executor is declared in `app.manifest.json` so the platform can discover a
 
 ```typescript
 // ESM (modern bundlers, Deno, Node 18+)
-const { createMyAppExecutor } = await import('https://my-app.smartlinks.app/dist/executor.es.js');
+const { createMyAppExecutor } = await import('https://my-app.smartlinks.app/dist/executor.esm.js');
 
 // UMD (script tag, legacy environments)
 // After loading executor.umd.js:

package/docs/host-dependency-contract.md

@@ -130,3 +130,30 @@ must stay pinned:
   a direct dependency.
 
 Both are compile-time/build-time concerns for the app's own toolchain; neither is a host global.
+
+## Reading the contract programmatically (one source of truth)
+
+Don't hard-code the externalized list — import it from the SDK, so hosts and apps
+never drift:
+
+```ts
+import {
+  SHARED_DEPENDENCY_CONTRACT_VERSION, // 'v5'
+  SHARED_DEPENDENCIES,                // [{ specifier, globalName, minVersion, importMapPath }, …] (25)
+  SHARED_DEPENDENCY_SPECIFIERS,       // bare specifiers — drop straight into a bundler `external` list
+  getHostSharedDependencies,          // what the live host advertises at runtime, or null
+} from '@proveanything/smartlinks'
+
+// Build config: externalize exactly the contract.
+export const external = [...SHARED_DEPENDENCY_SPECIFIERS]
+
+// Runtime: degrade gracefully on an older host that lacks the import map.
+const host = getHostSharedDependencies()
+if (host && host.version !== SHARED_DEPENDENCY_CONTRACT_VERSION) {
+  console.warn(`Built against ${SHARED_DEPENDENCY_CONTRACT_VERSION}, host serves ${host.version}`)
+}
+```
+
+The host publishes its live contract on `window.__SMARTLINKS_SHARED__` (`{ version, specifiers }`),
+which `getHostSharedDependencies()` reads. Import-map shim paths follow `importMapPathFor(specifier)`
+(`/sl-shared/<version>/<slug>.js`), so both the portal and the SDK generate identical paths.