@proveanything/smartlinks 2.0.5 → 2.0.9

package/dist/docs/analytics.md

@@ -46,7 +46,7 @@ There are two analytics domains:
 
 The backend stores custom analytics dimensions in `metadata`, but promoted analytics fields now belong at top level and are queried from real columns.
 
-See [docs/analytics-metadata-conventions.md](analytics-metadata-conventions.md) for the recommended key set.
+See [Metadata conventions](#metadata-conventions) below for the recommended key set.
 
 ### A note on server-written events
 
@@ -663,7 +663,7 @@ Analytics metadata filtering currently works best with top-level scalar keys suc
 - `utmCampaign`
 - `pagePath`
 
-See [docs/analytics-metadata-conventions.md](analytics-metadata-conventions.md) for the recommended shared vocabulary.
+See [Metadata conventions](#metadata-conventions) for the recommended shared vocabulary.
 
 ### 4. Prefer generic endpoints for custom dashboards
 
@@ -719,3 +719,42 @@ async function loadScanDashboard(collectionId: string) {
   }
 }
 ```
+
+---
+
+## Metadata conventions
+
+Recommended standard analytics keys — a shared vocabulary so teams don't invent divergent names. Some are promoted top-level fields; others are good `metadata` keys for custom dimensions.
+
+### Promoted top-level fields
+
+Send these at the **top level**, not inside `metadata`: `visitorId`, `referrerHost`, `entryType`, `pageId`, `scanMethod`, `source` (collection/web-events only — free-form client id like `'portal'`/`'hub'`; not on tag events), `redirectMode` (tag-events only; usually server-written).
+
+### Metadata-friendly keys
+
+`referrer`, `utmSource`, `utmMedium`, `utmCampaign`, `utmContent`, `utmTerm`, `group`, `tag`, `campaign`, `placement`, `linkGroup`, `linkPlacement`, `linkPosition`, `linkTitle`, `destinationDomain`, `pagePath`, `qrCodeId`.
+
+### Guidance
+
+- Treat these as reserved standard keys; prefer them before inventing alternatives.
+- Keep values flat and scalar so they're easy to filter/break-down later.
+- Promote a field to a first-class backend column only when it becomes a hot platform-wide dimension.
+- `source` (the event column) and the query-time `source` parameter (`'events' | 'tag'`, which table to query) are unrelated fields that share a name — filter the column via the **plural** `sources` array (there is no singular `source` filter).
+
+```typescript
+analytics.collection.track({
+  sessionId: 1234567890,
+  eventType: 'click_link',
+  collectionId: 'demo-collection',
+  visitorId: 'visitor_123',
+  linkId: 'hero-cta',
+  href: 'https://example.com/buy',
+  referrerHost: 'instagram.com',
+  placement: 'hero',
+  campaign: 'summer-launch',
+  utmSource: 'email',
+  pageId: 'QR123',
+  source: 'portal',
+  metadata: { pagePath: '/c/demo-collection' },
+})
+```

package/dist/docs/app-data-storage.md

@@ -249,44 +249,6 @@ If the object starts needing richer semantics, migrate that use case to `app.rec
 
 ---
 
-## Migration from Old SDK
-
-### Old SDK → New SDK
-
-```typescript
-// OLD: Get user config
-RemoteApi.get({ path: `public/auth/app/${appId}` })
-// NEW:
-userAppData.getConfig(appId)
-
-// OLD: Set user config
-RemoteApi.post({ path: `public/auth/app/${appId}`, data })
-// NEW:
-userAppData.setConfig(appId, data)
-
-// OLD: Get user data items
-RemoteApi.get({ path: `public/auth/app/${appId}/data` })
-// NEW:
-userAppData.list(appId)
-
-// OLD: Get user data item
-RemoteApi.get({ path: `public/auth/app/${appId}/data/${itemId}` })
-// NEW:
-userAppData.get(appId, itemId)
-
-// OLD: Set user data item
-RemoteApi.post({ path: `public/auth/app/${appId}/data`, data: item })
-// NEW:
-userAppData.set(appId, item)
-
-// OLD: Delete user data item
-RemoteApi.delete({ path: `public/auth/app/${appId}/data/${itemId}` })
-// NEW:
-userAppData.remove(appId, itemId)
-```
-
----
-
 ## Complete API Reference
 
 ### `userAppData` (User-Specific Data)

package/dist/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,54 @@ 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).
+
 ## Reading the Files at Runtime
 
 ### Manifest — available from the widgets endpoint

package/dist/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/dist/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/dist/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/dist/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/dist/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…).
 
 ---