@proveanything/smartlinks 1.11.0 → 1.11.2

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.11.0  |  Generated: 2026-04-30T11:35:44.821Z
+Version: 1.11.2  |  Generated: 2026-04-30T13:11:24.914Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/app-manifest.md

@@ -103,8 +103,8 @@ The manifest is loaded automatically by the platform for every collection page.
       {
         "name": "WarehousePickContainer",
         "description": "In-field operator admin surface.",
-        "audience": "admin-mobile",
-        "capabilities": ["nfc", "qr", "offline-queue"]
+        "capabilities": ["nfc", "qr"],
+        "offline": true
       }
     ]
   },
@@ -117,14 +117,18 @@ The manifest is loaded automatically by the platform for every collection page.
 
   "records": {
     "nutrition": {
-      "scopes": ["product", "facet", "batch"],
-      "defaultScope": "facet",
-      "label": "Nutrition info"
+      "label": "Nutrition info",
+      "cardinality": "singleton",
+      "allowFacetRules": true,
+      "scopes": ["collection", "rule", "product", "facet", "batch"],
+      "defaultScope": "product"
     },
     "cooking_steps": {
-      "scopes": ["product", "facet"],
-      "defaultScope": "product",
-      "label": "Cooking steps"
+      "label": "Cooking steps",
+      "cardinality": "singleton",
+      "allowFacetRules": false,
+      "scopes": ["collection", "product"],
+      "defaultScope": "product"
     }
   }
 }
@@ -236,8 +240,8 @@ See [mobile-admin-container.md](mobile-admin-container.md) for the `AdminMobileH
     {
       "name": "WarehousePickContainer",
       "description": "Pick orders by scanning NFC tags",
-      "audience": "admin-mobile",
-      "capabilities": ["nfc", "qr", "offline-queue"]
+      "capabilities": ["nfc", "qr"],
+      "offline": true
     }
   ]
 }
@@ -250,8 +254,8 @@ See [mobile-admin-container.md](mobile-admin-container.md) for the `AdminMobileH
 | `files.css` | CSS bundle path — set to `null` if no styles |
 | `components[].name` | Exported component name (must match the UMD bundle export) |
 | `components[].description` | Shown in the mobile launcher's app picker |
-| `components[].audience` | Must be `"admin-mobile"` |
-| `components[].capabilities` | Hardware/feature capabilities this component needs or can use. See [capability list](mobile-admin-container.md#hardware-capabilities--the-capability-matrix). |
+| `components[].capabilities` | Hardware capabilities this component needs or can use. See [capability list](mobile-admin-container.md#hardware-capabilities--the-capability-matrix). |
+| `components[].offline` | Set to `true` if this component queues writes locally and needs offline sync support. |
 #### `linkable`
 
 Static deep-linkable states built into the app — fixed routes that exist regardless of per-collection content. Declared once at build time.
@@ -268,25 +272,29 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 
 Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [Records-Based Admin Pattern](records-admin-pattern.md). Omit if the app does not use scoped records.
 
-The platform and the `<RecordsAdminShell>` from `@proveanything/ui-utils` read this block to render only the relevant tabs and affordances.
+The platform and the `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui` read this block to render the right scope tabs, rule editor, and cardinality-appropriate right pane.
 
 ```json
 "records": {
   "<recordType>": {
-    "scopes": ["product", "facet", "batch"],
-    "defaultScope": "facet",
-    "label": "Human-readable label"
+    "label": "Human-readable label",
+    "cardinality": "singleton",
+    "allowFacetRules": false,
+    "scopes": ["collection", "product", "variant", "batch", "facet"],
+    "defaultScope": "product"
   }
 }
 ```
 
-| Field          | Type     | Required | Description |
-|----------------|----------|----------|-------------|
-| `scopes`       | string[] | ✅ | Allowed scope kinds in resolution order. Valid values: `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"default"`. |
-| `defaultScope` | string   | ✅ | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
-| `label`        | string   | ✅ | Human-readable label for the record type, used in headings and tabs. |
+| Field             | Type     | Default | Description |
+|-------------------|----------|---------|-------------|
+| `label`           | string   | — | Human-readable label for the record type, used in headings and tabs. |
+| `cardinality`     | string   | `'singleton'` | `'singleton'` — one record wins per scope (e.g. ingredients, nutrition). `'collection'` — every matching record is returned in resolution order (e.g. FAQs, recipes). Drives which hook to use on the public side (`useResolvedRecord` vs `useCollectedRecords`) and how the shell lays out the right pane. |
+| `allowFacetRules` | boolean  | `false` | When `true`, the shell renders a **Rule** scope tab and embeds `<FacetRuleEditor>`. Add `'rule'` to `scopes` when setting this. |
+| `scopes`          | string[] | — | Allowed scope kinds in resolution order. Valid values: `"collection"`, `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"rule"`. `'rule'` is a synthetic scope holding `facetRule`-targeted records. `'collection'` replaces the legacy empty-ref catch-all — **there is no `'global'` scope**. |
+| `defaultScope`    | string   | — | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
 
-An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`).
+An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`). See [records-admin-pattern.md](records-admin-pattern.md) for the full admin + public pattern.
 
 #### `executor`
 

package/dist/docs/app-objects.md

@@ -495,7 +495,7 @@ The `ref` field is derived automatically from anchor fields when omitted:
 ```
 productId: 'prod_abc'                               → ref: 'product:prod_abc'
 productId: 'prod_abc', variantId: 'var_x'          → ref: 'product:prod_abc/variant:var_x'
-(no anchor fields)                                  → ref: '' (universal)
+(no anchor fields)                                  → ref: '' (collection-level catch-all)
 facetRule: { ... }                                  → ref: 'rule:<ulid>'
 ```
 
@@ -513,6 +513,20 @@ When multiple scoped records match a context, they are ordered by `specificity`.
 | Per `anyOf` value | +1 |
 | No anchors / no rule | 0 |
 
+### Resolution order
+
+When the public side of a records-based app needs "the data that applies to this product context", the platform walks a canonical chain from most-specific to least-specific:
+
+```
+proof  →  batch  →  variant  →  product  →  rule(*)  →  facet(*)  →  collection
+```
+
+- `rule(*)` — `facetRule`-targeted records are scored by **specificity** (number of clauses + number of constrained values). The most specific rule wins at its tier.
+- `facet(*)` — legacy single-facet anchors, walked alphabetically. Prefer `facetRule` for new work.
+- `collection` — the top of the chain and the catch-all for any record with no anchor fields. **There is no `'global'` tier above collection.**
+
+For a **singleton** record type (one answer wins), use `useResolvedRecord` — it performs this walk server-side and returns the first match plus a `matchedAt` tag. For a **collection** record type (every match is shown), use `useCollectedRecords`. See [records-admin-pattern.md §2](records-admin-pattern.md#2-resolution-order-one-canonical-chain) for the full guide.
+
 ### Singleton Cardinality
 
 By default, `create` always inserts a new row — calling it twice produces two records with identical anchor fields. **Singleton cardinality** changes that: pass `singletonPer` on creation and the server will **upsert** instead, ensuring at most one record of a given `recordType` exists per scope boundary.
@@ -592,12 +606,11 @@ for (const entry of data) {
     case 'product':    /* "Inherited from product" */ break;
     case 'facet':      /* "Tier-specific" */          break;
     case 'collection': /* "Collection default" */     break;
-    case 'universal':  /* "Default" */                break;
   }
 }
 ```
 
-Precedence follows: `rule > proof > batch > variant > product > facet > collection > universal`.
+Precedence follows: `proof > batch > variant > product > rule > facet > collection`. There is no scope above `collection` — a record with no anchor fields is a collection-level catch-all.
 
 #### React — `useResolvedRecord`
 
@@ -806,7 +819,7 @@ Examples:
 | `productId: 'prod_abc', variantId: 'var_500ml'` | `product:prod_abc/variant:var_500ml` |
 | `batchId: 'batch_q1'` | `batch:batch_q1` |
 | `facetRule: { ... }` | `rule:<ulid>` |
-| *(no anchor fields)* | `''` (universal) |
+| *(no anchor fields)* | `''` (collection-level catch-all) |
 
 `parseRef` / `buildRef` in `data/refs.ts` should be used for **display and URL round-tripping only**, never as upsert keys. For ETL use cases, set an explicit `ref` using a stable external key (see [External ID / ETL Workflow](#external-id--etl-workflow)).
 

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

@@ -16,12 +16,13 @@ This document describes how to build a **Mobile Admin Container** — a SmartLin
 4. [Hardware Capabilities & the Capability Matrix](#hardware-capabilities--the-capability-matrix)
 5. [Capacitor Plugin Baseline](#capacitor-plugin-baseline)
 6. [Manifest Declaration](#manifest-declaration)
-7. [Event Stream](#event-stream)
-8. [Error Handling](#error-handling)
-9. [Lifecycle](#lifecycle)
-10. [Build & Bundle Requirements](#build--bundle-requirements)
-11. [Example: Minimal Mobile Admin Container](#example-minimal-mobile-admin-container)
-12. [Best Practices](#best-practices)
+7. [Launcher Discovery](#launcher-discovery)
+8. [Event Stream](#event-stream)
+9. [Error Handling](#error-handling)
+10. [Lifecycle](#lifecycle)
+11. [Build & Bundle Requirements](#build--bundle-requirements)
+12. [Example: Minimal Mobile Admin Container](#example-minimal-mobile-admin-container)
+13. [Best Practices](#best-practices)
 
 ---
 
@@ -57,6 +58,8 @@ Your container **never** detects the host directly. It receives a `host` prop fr
 
 Every container mounted by the SmartLinks Mobile launcher receives a single `host` prop — `AdminMobileHostContext`. Do not reach for `window.SmartlinksScanner` or `window.Capacitor` directly; both are wrapped here.
 
+> **SDK export** — `AdminMobileHostContext`, `AdminMobileCapability`, `AdminMobileHostId`, `AdminMobileEvent`, `ScannerEventSubscriber`, `MobileAdminComponentManifest`, and `MobileAdminBundleManifest` are all exported from `@proveanything/smartlinks`. Import via `import type { AdminMobileHostContext } from '@proveanything/smartlinks'` — no local mirror needed.
+
 ```typescript
 interface AdminMobileHostContext {
   // Identity
@@ -106,7 +109,8 @@ interface AdminMobileHostContext {
   network: { isOnline: () => boolean }
   device: { info: () => Promise<{ model: string; platform: string }> }
 
-  // Host context version — for future feature-detection
+  // Informational host version — use for logging/diagnostics, not feature detection.
+  // For feature detection prefer existence checks: 'requestNfcTap' in host.actions
   _version: number
 }
 ```
@@ -114,7 +118,15 @@ interface AdminMobileHostContext {
 ### Contract rules
 
 1. **Check `host.hardware.X` before calling `host.actions.X`.** Calls to unavailable capabilities reject with `HostCapabilityUnavailableError`.
-2. **Do not call `initializeApi`.** `host.SL` is already configured with the right `baseURL`, auth, and logger.
+2. **Do not call `initializeApi`, and do not use top-level SDK imports for API calls.** `host.SL` is already configured with the right `baseURL`, auth, and logger. Code that does `import * as SL from "@proveanything/smartlinks"` and calls `SL.attestation.create(...)` will silently hit the wrong base URL — the top-level import is uninitialised in the launcher's runtime and produces no loud error. Always go through `host.SL`:
+   ```typescript
+   // ❌ Silent footgun — uninitialised SDK, wrong baseURL
+   import * as SL from '@proveanything/smartlinks'
+   await SL.attestation.create(...)
+
+   // ✅ Correct
+   await host.SL.attestation.create(...)
+   ```
 3. **Do not access `window.SmartlinksScanner` or `window.Capacitor` directly.** The host wraps both; direct access produces containers that only work on one shell.
 4. **Externalise all shared deps** (React, ReactDOM, SL, Radix, etc.) — the launcher provides them as globals. See [Build & Bundle Requirements](#build--bundle-requirements).
 
@@ -129,6 +141,36 @@ if (host.hardware.nfc) {
 }
 ```
 
+### `host.ui` — native helpers vs. your own components
+
+`host.ui.setHeaderTitle()` and `host.ui.navigateBack()` are **host-only** — there is no in-container equivalent. Call them via `host.ui` or omit them.
+
+`host.ui.toast()` and `host.ui.haptic()` are **optional conveniences**. Use them when you want native system feedback. When rendering in Storybook, unit tests, or a plain browser tab, your own `<Toaster />` is a perfectly valid substitute — you do not need to stub the entire `host.ui` surface just to get toast notifications.
+
+**Stub pattern for testing and Storybook:**
+
+```typescript
+const stubHost: Partial<AdminMobileHostContext> = {
+  hardware: { nfc: false, rfid: false, qr: true, camera: true, keyboard: false },
+  actions: {
+    requestQrScan: async () => 'STUB_QR_CODE',
+    requestNfcTap: async () => ({ uid: 'STUB_UID' }),
+    requestCameraPhoto: async () => new Blob(),
+    share: async () => {},
+    clipboard: { read: async () => '', write: async () => {} },
+  },
+  ui: {
+    toast: (opts) => console.log('[stub toast]', opts.title),
+    haptic: () => {},
+    setHeaderTitle: (t) => { if (t) document.title = t },
+    navigateBack: () => history.back(),
+  },
+  network: { isOnline: () => true },
+  user: { isAdmin: true, displayName: 'Test User', email: 'test@example.com' },
+  SL: undefined as any, // replace with your test SL instance
+}
+```
+
 ---
 
 ## Hardware Capabilities & the Capability Matrix
@@ -148,7 +190,6 @@ Containers declare which capabilities they need (or can use) in the manifest `ca
 | `"camera"` | Photo capture, gallery picker |
 | `"keyboard"` | Physical hardware trigger/action buttons |
 | `"geolocation"` | GPS coordinates |
-| `"offline-queue"` | Container needs local write queuing + sync |
 | `"push"` | Remote push notifications (FCM/APNs) |
 
 The full hardware capability matrix by host:
@@ -196,7 +237,7 @@ The custom Kotlin shell and both Capacitor shells ship the same baseline plugin
 | `@capgo/capacitor-nfc` | `"nfc"` |
 | `@capacitor/geolocation` | `"geolocation"` |
 | `@capacitor/push-notifications` | `"push"` |
-| `@capacitor/filesystem` | *(declare `"offline-queue"` if needed)* |
+| `@capacitor/filesystem` | *(used when `offline: true`; bundle it in)* |
 
 ### Tier 3 — custom-android only (not Capacitor)
 
@@ -231,8 +272,8 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
       {
         "name": "WarehousePickContainer",
         "description": "Pick orders by scanning NFC tags",
-        "audience": "admin-mobile",
-        "capabilities": ["nfc", "qr", "offline-queue"]
+        "capabilities": ["nfc", "qr"],
+        "offline": true
       }
     ]
   }
@@ -247,8 +288,29 @@ A `mobileAdmin` bundle can export multiple components targeting different operat
 |-------|------|-------------|
 | `name` | string | Exported component name (must match the UMD bundle export) |
 | `description` | string | Shown in the mobile launcher's app picker |
-| `audience` | `"admin-mobile"` | Required — tells the launcher this is an operator surface |
-| `capabilities` | string[] | Capabilities this component needs or can use. See table above. |
+| `capabilities` | string[] | Hardware capabilities this component needs or can use. See table above. |
+| `offline` | boolean | Set to `true` if this component queues writes locally and needs offline sync support. |
+
+---
+
+## Launcher Discovery
+
+The SmartLinks Mobile launcher loads your `mobileAdmin` bundle through the platform's app registry — you do not reference the manifest URL directly.
+
+**How it works:**
+
+1. A collection admin enables the app for a collection in the SmartLinks admin console.
+2. On startup (and periodically), the launcher fetches `app.manifest.json` for every enabled app in that collection via the SmartLinks platform API. These requests are authenticated with the launcher's operator session.
+3. The launcher reads `mobileAdmin.components[]`, evaluates each component's `capabilities` against the current device's hardware flags, and shows matching components in the app picker.
+4. When the operator opens a component, the launcher resolves `mobileAdmin.files.js.umd` against the app's CDN base, fetches the bundle, and mounts the component with its `host` prop.
+
+**File URL resolution:** `files.js.umd` / `files.js.esm` are paths relative to your app's CDN root (set when the app version is published). Provide relative paths — the launcher resolves them; do not hardcode absolute URLs.
+
+**Auth:** Manifest and bundle fetches use the launcher's session token. Your container is already authenticated via `host.user` and `host.SL` — do not add additional auth headers.
+
+**On load failure:** If the bundle returns a non-2xx response, the launcher shows a user-visible error and logs it — it does not crash the full launcher. If `app.manifest.json` itself cannot be fetched, the app is silently excluded from the picker for that session.
+
+> To debug a missing or stale manifest, confirm in the SmartLinks admin console that the app version is published and that the `mobileAdmin` key is present in the uploaded manifest.
 
 ---
 
@@ -318,7 +380,7 @@ try {
 |-------|------|------------|
 | mount | User opens your container | Subscribe to events, start readers |
 | unmount | User backs out / app backgrounded > 30s | Unsubscribe; persist in-flight state |
-| `lifecycle: 'offline'` | Network lost | Switch to offline-queue mode |
+| `lifecycle: 'offline'` | Network lost | Switch to offline mode; queue writes locally |
 | `lifecycle: 'online'` | Network restored | Flush queued writes |
 | `lifecycle: 'pause'` | App backgrounded | Pause readers to save battery |
 | `lifecycle: 'resume'` | App foregrounded | Resubscribe; refresh stale data |
@@ -400,7 +462,7 @@ vite build --config vite.config.mobile-admin.ts
 ```typescript
 // src/mobile-admin/WarehousePickContainer.tsx
 import { useEffect, useState } from 'react'
-import type { AdminMobileHostContext } from '@/lib/admin-mobile-host-context'
+import type { AdminMobileHostContext } from '@proveanything/smartlinks'
 
 interface Props {
   host: AdminMobileHostContext
@@ -459,9 +521,10 @@ export const MOBILE_ADMIN_MANIFEST = {
 
 - **Always check `host.hardware.X` before calling `host.actions.X`** — never assume a capability is available.
 - **Always wrap action calls in try/catch** — handle `HostPermissionDeniedError`, `HostTimeoutError`, and `HostCapabilityUnavailableError`.
-- **Use `host.ui.toast`, `host.ui.haptic`, `host.ui.setHeaderTitle`** instead of mounting your own UI chrome — these integrate with the launcher's native UI.
+- **Use `host.ui.setHeaderTitle` and `host.ui.navigateBack`** for header integration — these are host-only and have no in-container equivalent.
+- **`host.ui.toast` and `host.ui.haptic` are optional** — use them for native feedback, or fall back to your own `<Toaster />` when testing in isolation.
 - **Use `host.events.subscribe` for lifecycle events** — `'offline'`/`'online'`/`'pause'`/`'resume'` fire consistently on every host.
-- **Never call `initializeApi`** — `host.SL` is already configured.
+- **Never call `initializeApi`, never use top-level SDK imports for API calls** — `host.SL` is already configured. `SL.method()` instead of `host.SL.method()` silently uses the wrong baseURL.
 - **Bundle Capacitor plugins in** (do not externalise) — so the component degrades gracefully on PWA/browser without crashing.
-- **Declare `offline-queue` in capabilities** if your container queues writes — this signals the launcher to provision local storage support.
-- **Use `host._version`** to feature-detect newer host context fields — breaking changes bump the major version and the launcher gates incompatible combinations.
+- **Declare `offline: true`** on a component if it queues writes locally — this signals the launcher to provision offline sync support.
+- **Use `'methodName' in host.actions`** to feature-detect new host capabilities rather than comparing `host._version`. The version is informational only.