@proveanything/smartlinks 1.11.1 → 1.11.4

package/dist/mobile-admin/types.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Hardware/software capability tokens a mobile admin host may advertise.
+ * Passed to `AdminMobileHostContext.capabilities` and to
+ * `AdminMobileComponentManifest.capabilities`.
+ */
+export type AdminMobileCapability = 'nfc' | 'nfc-advanced' | 'rfid' | 'qr' | 'camera' | 'keyboard' | 'geolocation' | 'push';
+/**
+ * Subset of `AdminMobileCapability` that can be the subject of a structured
+ * error. `'keyboard'` is excluded — it is a passive event source with no
+ * request method that can fail.
+ */
+export type ActionableCapability = Exclude<AdminMobileCapability, 'keyboard'>;
+/**
+ * Canonical identifiers for mobile admin host environments.
+ * Use for display / diagnostics only — feature-detect at runtime via
+ * `AdminMobileHostContext.capabilities` and `'method' in host.actions`.
+ */
+export type AdminMobileHostId = 'custom-android' | 'capacitor-ios' | 'capacitor-android' | 'pwa' | 'browser';
+/**
+ * Discriminated-union of all events the host may emit via
+ * `AdminMobileHostContext.events.subscribe`.
+ */
+export type AdminMobileEvent = {
+    type: 'nfc-tap';
+    uid: string;
+    ndef?: string;
+} | {
+    type: 'rfid-burst';
+    epcs: string[];
+} | {
+    type: 'qr-scan';
+    code: string;
+} | {
+    type: 'key-press';
+    keyCode: number;
+} | {
+    type: 'lifecycle';
+    phase: 'pause' | 'resume' | 'offline' | 'online';
+};
+/** Callback invoked for every hardware event emitted by the host. */
+export type AdminMobileEventCallback = (event: AdminMobileEvent) => void;
+/**
+ * The full type of `AdminMobileHostContext.events.subscribe` —
+ * takes a callback and returns a cleanup function.
+ */
+export type AdminMobileEventSubscriber = (cb: AdminMobileEventCallback) => () => void;
+/**
+ * @deprecated Renamed to `AdminMobileEventCallback` in 1.12.
+ * Will be removed in a future minor release.
+ * @see AdminMobileEventCallback
+ */
+export type ScannerEventSubscriber = AdminMobileEventCallback;
+/**
+ * The `host` prop passed to every mobile admin container component.
+ *
+ * @example
+ *   function StockTakeContainer({ host }: { host: AdminMobileHostContext }) {
+ *     const SL = host.SL; // Always use this — never import the SDK directly
+ *     return <div>...</div>;
+ *   }
+ */
+export interface AdminMobileHostContext {
+    /** SmartLinks collection this session is scoped to. */
+    collectionId: string;
+    /** App owning this container. */
+    appId: string;
+    /**
+     * Currently authenticated admin user, or `null` when unauthenticated.
+     */
+    user: {
+        uid?: string;
+        email?: string;
+        displayName?: string;
+        isAdmin: boolean;
+    } | null;
+    /**
+     * Already-initialised SDK namespace. Containers MUST use this for all API
+     * calls — never `import * as SL from '@proveanything/smartlinks'` inside a
+     * container, as that would create a second SDK instance.
+     */
+    SL: typeof import('../index');
+    /** Capabilities advertised by this host instance. */
+    capabilities: AdminMobileCapability[];
+    /**
+     * Static hardware availability flags.
+     * These reflect physical capability, not runtime permission state.
+     */
+    hardware: {
+        nfc: boolean;
+        rfid: boolean;
+        qr: boolean;
+        camera: boolean;
+        keyboard: boolean;
+    };
+    /** Hardware event stream. */
+    events: {
+        /**
+         * Subscribe to hardware events. Returns an unsubscribe function.
+         * @param cb - Called for every incoming `AdminMobileEvent`.
+         * @returns Cleanup function — call inside `useEffect` return.
+         */
+        subscribe: (cb: AdminMobileEventCallback) => () => void;
+    };
+    /** Imperative hardware actions. */
+    actions: {
+        /**
+         * Open the QR scanner UI and resolve with the decoded string.
+         * Throws `HostCapabilityUnavailableError` if `'qr'` is not in `capabilities`.
+         * Throws `HostTimeoutError` if the user dismisses without scanning.
+         */
+        requestQrScan: () => Promise<string>;
+        /**
+         * Await the next NFC tap and resolve with uid + optional NDEF payload.
+         * @param timeoutMs - Milliseconds before `HostTimeoutError` is thrown (host default if omitted).
+         */
+        requestNfcTap: (timeoutMs?: number) => Promise<{
+            uid: string;
+            ndef?: string;
+        }>;
+        /**
+         * Open the camera shutter once and resolve with the captured `Blob`.
+         * Throws `HostCapabilityUnavailableError` if `'camera'` is not in `capabilities`.
+         */
+        requestCameraPhoto: () => Promise<Blob>;
+        /**
+         * Trigger the native share sheet.
+         * Falls back to clipboard write on hosts that do not implement the Web Share API.
+         */
+        share: (payload: {
+            title: string;
+            url: string;
+            text?: string;
+        }) => Promise<void>;
+        /** Clipboard access. */
+        clipboard: {
+            read: () => Promise<string>;
+            write: (text: string) => Promise<void>;
+        };
+    };
+    /**
+     * Light-touch UI conveniences provided by the host shell.
+     * All methods are optional niceties — containers MUST degrade gracefully
+     * when absent (e.g. in Storybook or unit tests). Guard every call:
+     *
+     * @example
+     *   host.ui.toast?.({ title: 'Saved' });
+     */
+    ui: {
+        /** Show a transient status toast. Optional — see interface note. */
+        toast?: (opts: {
+            title: string;
+            description?: string;
+            variant?: 'default' | 'destructive';
+        }) => void;
+        /** Trigger a haptic pulse. Optional — see interface note. */
+        haptic?: (style?: 'light' | 'success' | 'error') => void;
+        /**
+         * Optional — host shell may not provide a managed header
+         * (browser tabs, Storybook, desktop views). Guard with `?.`.
+         */
+        setHeaderTitle?: (title: string | null) => void;
+        /**
+         * Optional — host shell may not have a native back stack
+         * (browser tabs, Storybook, desktop views). Guard with `?.`.
+         */
+        navigateBack?: () => void;
+    };
+    /** Network connectivity helpers. */
+    network: {
+        /** Returns whether the device currently has network access. */
+        isOnline: () => boolean;
+    };
+    /** Device information. */
+    device: {
+        /** Resolves with basic device model/platform metadata. */
+        info: () => Promise<{
+            model: string;
+            platform: string;
+        }>;
+    };
+    /**
+     * Host ABI version — informational only.
+     * DO NOT branch on this value. Feature-detect at runtime instead:
+     * @example
+     *   if ('requestNfcTap' in host.actions) { ... }
+     */
+    _version: number;
+}
+/** Manifest metadata for a single mobile admin container component. */
+export interface AdminMobileComponentManifest {
+    /** Component export name (matches the export in the bundle). */
+    name: string;
+    /** Human-readable description shown in the host launcher UI. */
+    description: string;
+    /**
+     * Hardware capabilities this component requires.
+     * The host will hide or disable the component when a required capability
+     * is absent from `AdminMobileHostContext.capabilities`.
+     */
+    capabilities?: AdminMobileCapability[];
+    /**
+     * When `true`, the component handles its own offline state and may be
+     * launched without network connectivity.
+     * @default false
+     */
+    offline?: boolean;
+}
+/**
+ * Shape of the `mobileAdmin` key inside `app.manifest.json`.
+ * Describes the bundle files and the components it exports.
+ */
+export interface AdminMobileBundleManifest {
+    files: {
+        js: {
+            /** UMD bundle path (relative to dist root). Used by the custom-android host. */
+            umd: string;
+            /** ESM bundle path (relative to dist root). Used by Capacitor/PWA hosts. */
+            esm: string;
+        };
+        /** CSS bundle path, or `null` if the component ships no styles. */
+        css: string | null;
+    };
+    components: AdminMobileComponentManifest[];
+}
+/**
+ * @deprecated Renamed to `AdminMobileComponentManifest` in 1.12.
+ * @see AdminMobileComponentManifest
+ */
+export type MobileAdminComponentManifest = AdminMobileComponentManifest;
+/**
+ * @deprecated Renamed to `AdminMobileBundleManifest` in 1.12.
+ * @see AdminMobileBundleManifest
+ */
+export type MobileAdminBundleManifest = AdminMobileBundleManifest;

package/dist/mobile-admin/types.js

@@ -0,0 +1 @@
+export {};

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.11.1  |  Generated: 2026-04-30T12:17:30.051Z
+Version: 1.11.4  |  Generated: 2026-04-30T13:59:47.020Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/app-manifest.md

@@ -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"
     }
   }
 }
@@ -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/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/docs/mobile-admin-container.md

@@ -58,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`, `ActionableCapability`, `AdminMobileHostId`, `AdminMobileEvent`, `AdminMobileEventCallback`, `AdminMobileEventSubscriber`, `AdminMobileComponentManifest`, and `AdminMobileBundleManifest` are all exported from `@proveanything/smartlinks`. Import via `import type { AdminMobileHostContext } from '@proveanything/smartlinks'` — no local mirror needed. `ScannerEventSubscriber`, `MobileAdminComponentManifest`, and `MobileAdminBundleManifest` still export as deprecated aliases.
+
 ```typescript
 interface AdminMobileHostContext {
   // Identity
@@ -80,8 +82,8 @@ interface AdminMobileHostContext {
     keyboard: boolean
   }
 
-  // Unified hardware event stream
-  events: { subscribe: ScannerEventSubscriber }
+  // Unified hardware event stream — callback type: AdminMobileEventCallback
+  events: { subscribe: (cb: AdminMobileEventCallback) => () => void }
 
   // Promise-based hardware actions — reject with a structured error when unavailable
   actions: {
@@ -95,12 +97,12 @@ interface AdminMobileHostContext {
     }
   }
 
-  // Host-provided UI helpers
+  // Host-provided UI helpers — all optional, see §3 note
   ui: {
-    toast: (opts: { title: string; description?: string; variant?: 'default' | 'destructive' }) => void
-    haptic: (style?: 'light' | 'success' | 'error') => void
-    setHeaderTitle: (title: string | null) => void
-    navigateBack: () => void
+    toast?: (opts: { title: string; description?: string; variant?: 'default' | 'destructive' }) => void
+    haptic?: (style?: 'light' | 'success' | 'error') => void
+    setHeaderTitle?: (title: string | null) => void
+    navigateBack?: () => void
   }
 
   // Network & device info
@@ -141,9 +143,10 @@ 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.
+All four `host.ui` methods are **optional by design**. A container may run in the Sidekick mobile shell, a standalone PWA or browser tab, Storybook, or a screenshot harness — none of those environments is guaranteed to have a native toast system, a managed header, or a back stack. Forcing every host implementer to provide them would exclude the web and desktop use-cases the rest of the contract explicitly supports. Always guard with `?.`:
 
-`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.
+- `host.ui.toast?.({...})` / `host.ui.haptic?.('success')` — optional native feedback. Fall back to your own `<Toaster />` when absent.
+- `host.ui.setHeaderTitle?.('Scanning…')` / `host.ui.navigateBack?.()` — host-shell integrations with no in-container equivalent. Silently no-op when the host doesn't implement them.
 
 **Stub pattern for testing and Storybook:**
 
@@ -220,12 +223,23 @@ The custom Kotlin shell and both Capacitor shells ship the same baseline plugin
 | `@capacitor/device` | `host.device.info()` |
 | `@capacitor/share` | `host.actions.share()` |
 | `@capacitor/clipboard` | `host.actions.clipboard.*` |
-| `@capacitor/preferences` | `host.storage.*` *(planned)* |
+| `@capacitor/preferences` | `host.storage.*` *(planned — see note below)* |
 | `@capacitor/app` | host-managed (back button, deep links) |
 | `@capacitor/status-bar` | host-managed |
 | `@capacitor/keyboard` | host-managed |
 | `@capacitor/toast` | wired into `host.ui.toast()` |
 
+> **`host.storage` — planned shape.** Once released, the surface will wrap `@capacitor/preferences` directly:
+> ```ts
+> host.storage: {
+>   get(key: string): Promise<string | null>
+>   set(key: string, value: string): Promise<void>
+>   remove(key: string): Promise<void>
+>   keys(): Promise<string[]>
+> }
+> ```
+> Until then: `localStorage` works on web hosts; use `@capacitor/preferences` directly (bundle it in) on native.
+
 ### Tier 2 — capability-gated (declare in manifest)
 
 | Plugin | Capability flag |
@@ -383,7 +397,9 @@ try {
 | `lifecycle: 'pause'` | App backgrounded | Pause readers to save battery |
 | `lifecycle: 'resume'` | App foregrounded | Resubscribe; refresh stale data |
 
-Use `host.events.subscribe` for all lifecycle events — it fires identically on every host.
+Use `host.events.subscribe` for all lifecycle events — all five host types (`custom-android`, `capacitor-ios`, `capacitor-android`, `pwa`, `browser`) are guaranteed to emit every `'pause'`/`'resume'`/`'offline'`/`'online'` phase. No `window.addEventListener('online')` fallback is needed.
+
+> **Planned** — `phase: 'mount' | 'unmount'` events are on the roadmap. These will fire when the container becomes visible / is removed from the host view stack, enabling deferred reader start-up without a `useEffect` dependency.
 
 ---
 
@@ -460,7 +476,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
@@ -519,8 +535,8 @@ 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.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.
+- **All four `host.ui` methods are optional** (`toast`, `haptic`, `setHeaderTitle`, `navigateBack`) — guard every call with `?.`. See the `host.ui` section above.
+- **`host.ui.setHeaderTitle` and `host.ui.navigateBack`** integrate with the host shell and have no in-container equivalent; call with `?.`.
 - **Use `host.events.subscribe` for lifecycle events** — `'offline'`/`'online'`/`'pause'`/`'resume'` fire consistently on every host.
 - **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.