@proveanything/smartlinks 1.11.4 → 1.11.6

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.11.4  |  Generated: 2026-04-30T13:59:47.020Z
+Version: 1.11.6  |  Generated: 2026-05-01T13:42:06.488Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/app-objects.md

@@ -85,6 +85,7 @@ Zones are **automatically filtered** based on the caller's role:
 ### Zone Writing Rules
 
 - **Non-admin callers** attempting to write to the `admin` zone are silently ignored
+- **Authenticated record owners** can write to `data` and `owner` by default; individual keys can be restricted via the `ownerEdit` app config policy (see [Owner Edit Policy](#owner-edit-policy) below)
 - **Public callers** can write to `data` and `owner` (if visibility allows)
 - **Admins** can write to all three zones
 
@@ -1098,6 +1099,61 @@ The `enforce` values are **merged over** the caller's request body, so you can l
 
 ---
 
+## Owner Edit Policy
+
+Gives per-zone, field-level control over what an **authenticated record owner** can update via `PATCH /api/v1/public/collection/:collectionId/app/:appId/records/:recordId`.
+
+Set the policy in the same app config document used for `publicCreate` (stored at `sites/{collectionId}/apps/{appId}`):
+
+```json
+{
+  "ownerEdit": {
+    "records": {
+      "data":  { "allow": ["paypalEmail"] },
+      "owner": { "allow": ["paypalEmail", "paypalEmailUpdatedAt"] }
+    }
+  }
+}
+```
+
+### Zone visibility and write access
+
+| Zone    | Who can read           | Who can write (owner)                                    |
+|---------|------------------------|----------------------------------------------------------|
+| `data`  | public                 | Allow-listed keys only (if policy set); all keys if not  |
+| `owner` | owner + admin          | Allow-listed keys only (if policy set); all keys if not  |
+| `admin` | admin                  | Never — admin zone is always immutable to owners         |
+
+### Allow-list semantics
+
+| Config                     | Behaviour                                                                     |
+|----------------------------|-------------------------------------------------------------------------------|
+| No `ownerEdit` key         | Default-allow — both zones fully writable (no change to existing behaviour)   |
+| `allow` array with keys    | Only the listed keys are accepted from the PATCH body; the rest are silently ignored and their existing values preserved |
+| `allow: []` (empty array)  | Zone is effectively read-only for the owner                                   |
+
+Accepted keys are **merged** onto the existing zone blob — you do not need to re-send unchanged values.
+
+### Example: commission record with protected fields
+
+An app that lets owners update their payout email but not their commission total:
+
+```json
+{
+  "ownerEdit": {
+    "records": {
+      "owner": { "allow": ["paypalEmail", "paypalEmailUpdatedAt"] }
+    }
+  }
+}
+```
+
+A PATCH body of `{ "owner": { "paypalEmail": "x@y.com", "totalCommission": 99 } }` will update `paypalEmail` only. `totalCommission` is silently ignored and its existing value is preserved.
+
+> **App design note:** If your app creates records with sensitive fields that owners should never modify (e.g. computed totals, server-assigned fields), add an `ownerEdit` policy from the start. It is significantly easier to relax restrictions later than to tighten them after data has been mutated.
+
+---
+
 ## Anonymous Edit Tokens
 
 Enables an anonymous caller to amend a record they just created — without authentication — by presenting a short-lived secret token.

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

@@ -4,7 +4,7 @@
 
 This document describes how to build a **Mobile Admin Container** — a SmartLinks microapp that provides an in-the-field operator/admin surface optimised for mobile devices. These containers ship as a **separate `mobileAdmin` bundle** (not inside the `containers` bundle) so that Capacitor plugins, offline helpers, and operator-only code never reach the public consumer bundle.
 
-> **See also:** [containers.md](containers.md) covers the public consumer container. The [Multiple Consumer Components](containers.md#multiple-consumer-components) section explains the consumer vs. admin bundle split.
+> **See also:** [containers.md](containers.md) covers the public consumer container. The [Multiple Consumer Components](containers.md#multiple-consumer-components) section explains the consumer vs. admin bundle split. For the full `host.native` facade contract (share, clipboard, haptics, NFC, RFID, storage, etc.) see [native-facade.md](native-facade.md).
 
 ---
 
@@ -23,6 +23,7 @@ This document describes how to build a **Mobile Admin Container** — a SmartLin
 11. [Build & Bundle Requirements](#build--bundle-requirements)
 12. [Example: Minimal Mobile Admin Container](#example-minimal-mobile-admin-container)
 13. [Best Practices](#best-practices)
+14. [Native Capability Facade](#native-capability-facade)
 
 ---
 
@@ -58,7 +59,7 @@ 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.
+> **SDK export** — `AdminMobileHostContext`, `AdminMobileCapability`, `ActionableCapability`, `AdminMobileHostId`, `AdminMobileEvent`, `AdminMobileEventCallback`, `AdminMobileEventSubscriber`, `AdminMobileComponentManifest`, `AdminMobileBundleManifest`, and `NativeFacade` (plus all sub-facade interfaces) are 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 {
@@ -112,6 +113,10 @@ interface AdminMobileHostContext {
   // Informational host version — use for logging/diagnostics, not feature detection.
   // For feature detection prefer existence checks: 'requestNfcTap' in host.actions
   _version: number
+
+  // Full native capability facade — share, clipboard, haptics, NFC, RFID, storage, etc.
+  // Optional: not every host stub populates it. See native-facade.md.
+  native?: NativeFacade
 }
 ```
 
@@ -542,3 +547,26 @@ export const MOBILE_ADMIN_MANIFEST = {
 - **Bundle Capacitor plugins in** (do not externalise) — so the component degrades gracefully on PWA/browser without crashing.
 - **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.
+
+---
+
+## Native Capability Facade
+
+`host.native` gives containers access to a broader set of device capabilities — share sheet, clipboard, full haptics API, storage, QR, NFC, RFID (Kotlin only), auth, and cross-shell events — through a single interface that falls back gracefully across all host environments.
+
+```typescript
+// Check host.hardware.* for physical availability, then call via host.native
+if (host.hardware.nfc && host.native?.nfc) {
+  const { uid } = await host.native.nfc.read({ timeoutMs: 10_000 })
+}
+
+// Storage always available (Preferences → localStorage → in-memory Map)
+await host.native?.storage.set('lastScan', uid)
+
+// Share sheet with web fallback
+await host.native?.share.share({ title: 'Found tag', url: `https://app.example/tags/${uid}` })
+```
+
+`host.native` is optional on `AdminMobileHostContext` — host stubs (Storybook, unit tests) need not implement it. `native.rfid` is additionally optional within `NativeFacade` itself, as it only exists on `custom-android`.
+
+For the full sub-facade table, fallback chains, and what's intentionally not wrapped, see **[native-facade.md](native-facade.md)**.

package/dist/docs/native-facade.md

@@ -0,0 +1,170 @@
+# Native Capability Facade (`host.native` / `SL.native`)
+
+> **Version:** 1.12 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+
+The `NativeFacade` is a thin contract layer between microapps and the device capabilities available on the current host shell (Kotlin, Capacitor iOS/Android, PWA, or browser). It lets a microapp call `host.native.share.share({...})` without knowing whether it's running over `window.SmartlinksScanner`, a Capacitor plugin, or `navigator.share`.
+
+**The SDK owns the contract** (`src/native/types.ts`, re-exported from `@proveanything/smartlinks`). Each host implementation is responsible for wiring up the sub-facades and populating:
+- `AdminMobileHostContext.native` (container prop, typed in the SDK), and
+- `window.SL.native` (for UMD microapps that don't receive a host prop — host concern, not SDK).
+
+---
+
+## Table of Contents
+
+1. [Access patterns](#access-patterns)
+2. [What's in the facade](#whats-in-the-facade)
+3. [What's NOT in the facade](#whats-not-in-the-facade)
+4. [Error contract](#error-contract)
+5. [Type reference](#type-reference)
+
+---
+
+## Access patterns
+
+### Inside a Mobile Admin Container (recommended)
+
+```typescript
+import type { AdminMobileHostContext } from '@proveanything/smartlinks'
+
+function MyContainer({ host }: { host: AdminMobileHostContext }) {
+  const handleShare = async () => {
+    await host.native?.share.share({ title: 'SmartLinks', url: window.location.href })
+  }
+
+  const handleScan = async () => {
+    // Only present when the host provides a QR reader
+    const code = await host.native?.qr.scan()
+    if (code) processCode(code)
+  }
+}
+```
+
+Always call via `host.native?.<facade>.<method>()` — `native` is optional because not every host exposes the full surface (e.g. a minimal browser stub may omit `rfid`).
+
+For hardware-gated capabilities (NFC, RFID, QR, camera) also check `host.capabilities` or `host.hardware.*` before calling, as those flags reflect physical availability on the current device:
+
+```typescript
+if (host.hardware.nfc && host.native?.nfc) {
+  const { uid } = await host.native.nfc.read({ timeoutMs: 10_000 })
+}
+```
+
+### Inside a UMD microapp (no host prop)
+
+```typescript
+// window.SL.native is populated by the host at boot — host concern, not SDK
+const native = (window as any).SL?.native as import('@proveanything/smartlinks').NativeFacade | undefined
+const code = await native?.qr.scan()
+```
+
+---
+
+## What's in the facade
+
+These capabilities have meaningful fallbacks across Kotlin / Capacitor / web. Always go through the facade.
+
+| Sub-facade | Key methods | Fallback chain |
+|---|---|---|
+| `native.share` | `share({ title, url, text? })`, `canShare()` | Capacitor Share → `navigator.share` → copy to clipboard + toast |
+| `native.clipboard` | `write(text)`, `read()` | Capacitor Clipboard → `navigator.clipboard` → `execCommand('copy')` |
+| `native.haptics` | `impact(style?)`, `notification(style)`, `selection()` | Capacitor Haptics → `navigator.vibrate` → no-op |
+| `native.network` | `getStatus()`, `addListener('change', cb)` | Capacitor Network → `navigator.onLine` + `'online'`/`'offline'` events |
+| `native.device` | `getInfo()`, `getId()`, `getLanguageCode()` | Capacitor Device → UA parsing + cached UUID in `localStorage` |
+| `native.storage` | `get(key)`, `set(key, value)`, `remove(key)`, `keys()` | Capacitor Preferences → `localStorage` → in-memory `Map` (private mode) |
+| `native.qr` | `scan(opts?)` | Capacitor MLKit Barcode → html5-qrcode / `BarcodeDetector` |
+| `native.auth` | `signInWithGoogle()`, `signOut()` | Kotlin bridge → Capacitor Browser + OAuth → web redirect |
+| `native.nfc` | `read(opts?)`, `writeNdef(opts)`, `programTag(opts)`, `lockTag(opts)`, `isLocked(opts)` | Kotlin bridge → Web NFC (`NDEFReader`) → `HostCapabilityUnavailableError` |
+| `native.rfid` | `startScan(opts?)`, `stopScan()`, `subscribe(cb)` | Kotlin bridge only — throws `HostCapabilityUnavailableError` on all other hosts |
+| `native.events` | `subscribe(type, cb)`, `emit(type, payload?)` | Internal pub/sub bridging Kotlin `onSmartlinksData` + Capacitor listeners |
+| `native.webSource` | `get()`, `set({ mode, channel?, liveUrl? })` | Kotlin bridge + Capacitor Preferences mirror |
+
+> **`native.rfid` is the only optional sub-facade** on `NativeFacade` — it is only populated on `custom-android` hosts. All other sub-facades are present on every host, though individual methods may throw `HostCapabilityUnavailableError` when the underlying capability is absent.
+
+> **`native.device` vs `host.device`** — `host.device.info()` is a simplified convenience that returns `{ model, platform }`. `host.native?.device.getInfo()` returns the full `DeviceInfo` (adds `osVersion`, `manufacturer`, `isVirtual`) and also provides `getId()` and `getLanguageCode()`. Use `host.device` when the convenience is enough.
+
+> **`native.network` vs `host.network`** — `host.network.isOnline()` is a boolean convenience. `host.native?.network.getStatus()` returns `{ connected, connectionType }` including `'wifi'` / `'cellular'` distinction.
+
+---
+
+## What's NOT in the facade
+
+These capabilities intentionally have no `SL.native` wrapper. Call the Capacitor plugin directly, or use the web API. The host provides them as Tier 1 or Tier 2 plugins (see [Capacitor Plugin Baseline](mobile-admin-container.md#capacitor-plugin-baseline)).
+
+| Capability | Why not wrapped |
+|---|---|
+| `@capacitor/push-notifications` | Push only exists in Capacitor builds; no cross-shell registration flow. Import and call directly; detect Capacitor first. |
+| `@capacitor/local-notifications` | Same — no Kotlin or web equivalent worth abstracting. |
+| `@capacitor/camera` | Plugin already abstracts iOS/Android. PWA's `<input capture>` is too different in shape to unify. |
+| `@capacitor/filesystem` | No web equivalent (storage quotas, sandbox rules differ). Use `URL.createObjectURL` + download anchor on web. |
+| `@capacitor/geolocation` | `navigator.geolocation` already works in WebViews; the Capacitor plugin wraps the same OS APIs. No facade adds value. |
+| `@capacitor/keyboard`, `@capacitor/screen-*`, `@capacitor/splash-screen`, `@capacitor/status-bar`, `@capacitor/dialog`, `@capacitor/app` | Per-host boot-time config or platform-chrome concerns; not part of the microapp contract. |
+| `@capacitor/browser` | In-app browser for OAuth is intentionally Capacitor-only. For opening external URLs use `native.share.share({ url })`. |
+| `@capawesome/capacitor-file-picker` | Picker UX too divergent across web (`<input type="file">`) and native to wrap usefully. |
+
+If a capability later needs consistent behaviour across shells (e.g. notifications reach enough hosts to warrant throttling / routing via the facade), promote it into `NativeFacade` by adding an interface to `src/native/types.ts` and a row to the table above.
+
+---
+
+## Error contract
+
+All facade methods reject with one of the three structured errors from `@proveanything/smartlinks`. A single catch block handles every capability and host combination:
+
+```typescript
+import {
+  HostCapabilityUnavailableError,
+  HostPermissionDeniedError,
+  HostTimeoutError,
+} from '@proveanything/smartlinks'
+
+try {
+  const { uid } = await host.native?.nfc.read({ timeoutMs: 10_000 }) ?? {}
+} catch (err) {
+  if (err instanceof HostCapabilityUnavailableError) {
+    // host.capabilities won't list 'nfc' — we should have checked first
+    host.ui.toast?.({ title: 'NFC not available on this device', variant: 'destructive' })
+  } else if (err instanceof HostPermissionDeniedError) {
+    host.ui.toast?.({ title: 'NFC permission denied', variant: 'destructive' })
+  } else if (err instanceof HostTimeoutError) {
+    host.ui.toast?.({ title: `No tag detected after ${err.timeoutMs / 1000}s` })
+  } else {
+    throw err
+  }
+}
+```
+
+---
+
+## Type reference
+
+All types below are exported from `@proveanything/smartlinks`:
+
+```typescript
+import type {
+  NativeFacade,          // root — use on AdminMobileHostContext.native
+  NativeCapability,      // union of sub-facade keys: 'share' | 'clipboard' | ...
+  ShareFacade,
+  ClipboardFacade,
+  HapticsFacade,
+  HapticImpactStyle,     // 'light' | 'medium' | 'heavy'
+  HapticNotificationStyle,
+  NetworkFacade,
+  NetworkStatus,
+  DeviceFacade,
+  DeviceInfo,
+  StorageFacade,
+  QrFacade,
+  QrScanOptions,
+  AuthFacade,
+  NfcFacade,
+  NfcReadResult,
+  RfidFacade,
+  RfidScanOptions,
+  EventsFacade,
+  WebSourceFacade,
+  WebSourceMode,
+  WebSourceConfig,
+} from '@proveanything/smartlinks'
+```
+
+The facade interfaces are contract-only — no runtime implementation is shipped in the SDK. You only need them for TypeScript type-checking (authoring containers or host stubs).

package/dist/index.d.ts

@@ -27,3 +27,4 @@ export type { AdminMobileCapability, ActionableCapability, AdminMobileHostId, Ad
 AdminMobileHostContext, AdminMobileComponentManifest, AdminMobileBundleManifest, MobileAdminComponentManifest, // @deprecated — use AdminMobileComponentManifest
 MobileAdminBundleManifest, } from './mobile-admin/types';
 export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors';
+export type { NativeCapability, NativeFacade, ShareFacade, ClipboardFacade, HapticImpactStyle, HapticNotificationStyle, HapticsFacade, NetworkStatus, NetworkFacade, DeviceInfo, DeviceFacade, StorageFacade, QrScanOptions, QrFacade, AuthFacade, NfcReadResult, NfcFacade, RfidScanOptions, RfidFacade, EventsFacade, WebSourceMode, WebSourceConfig, WebSourceFacade, } from './native/types';

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

@@ -1,3 +1,4 @@
+import type { NativeFacade } from '../native/types';
 /**
  * Hardware/software capability tokens a mobile admin host may advertise.
  * Passed to `AdminMobileHostContext.capabilities` and to
@@ -185,6 +186,16 @@ export interface AdminMobileHostContext {
      *   if ('requestNfcTap' in host.actions) { ... }
      */
     _version: number;
+    /**
+     * Full native capability facade populated by the host at mount time.
+     * Not all sub-facades are present on every host — check before calling:
+     * @example
+     *   const code = await host.native?.qr.scan();
+     *   const { identifier } = await host.native?.device.getId() ?? {};
+     * For UMD microapps that do not receive a `host` prop, the same object
+     * is available at `window.SL.native` (host concern, not SDK).
+     */
+    native?: NativeFacade;
 }
 /** Manifest metadata for a single mobile admin container component. */
 export interface AdminMobileComponentManifest {

package/dist/native/types.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Contract types for the `SL.native` / `host.native` facade.
+ *
+ * These are **interface-only** — no runtime implementation lives here.
+ * The facade is implemented per-host (Sidekick, Capacitor builds, PWA) and
+ * exposed to containers via `AdminMobileHostContext.native` or (for UMD
+ * microapps) via `window.SL.native`. The SDK owns the shape; the host owns
+ * the wiring.
+ *
+ * All facade methods reject with one of the structured errors from
+ * `@proveanything/smartlinks` (`HostCapabilityUnavailableError`,
+ * `HostPermissionDeniedError`, `HostTimeoutError`) so a single catch handler
+ * covers every host and capability.
+ */
+/**
+ * Keys of the `NativeFacade` interface — one token per sub-facade.
+ * Use `hasCapability(key)` on the host to check availability before calling.
+ */
+export type NativeCapability = 'share' | 'clipboard' | 'haptics' | 'network' | 'device' | 'storage' | 'qr' | 'auth' | 'nfc' | 'rfid' | 'events' | 'webSource';
+/** Share sheet / URL sharing. */
+export interface ShareFacade {
+    /**
+     * Trigger the native share sheet.
+     * Falls back to `navigator.share`, then silently copies `url` to clipboard.
+     */
+    share(payload: {
+        title: string;
+        url: string;
+        text?: string;
+    }): Promise<void>;
+    /** Returns `true` when a share sheet is available on this host. */
+    canShare(): Promise<boolean>;
+}
+/** Clipboard read / write. */
+export interface ClipboardFacade {
+    /** Write plain text to the clipboard. */
+    write(text: string): Promise<void>;
+    /** Read plain text from the clipboard. Returns `''` if empty or denied. */
+    read(): Promise<string>;
+}
+/** Haptic feedback. */
+export type HapticImpactStyle = 'light' | 'medium' | 'heavy';
+export type HapticNotificationStyle = 'success' | 'warning' | 'error';
+export interface HapticsFacade {
+    /** Physical impact pulse. Falls back to `navigator.vibrate`. */
+    impact(style?: HapticImpactStyle): Promise<void>;
+    /** Notification-style feedback. Falls back to `navigator.vibrate`. */
+    notification(style: HapticNotificationStyle): Promise<void>;
+    /** Selection-changed feedback. No-op when unsupported. */
+    selection(): Promise<void>;
+}
+/** Network status. */
+export interface NetworkStatus {
+    connected: boolean;
+    connectionType: 'wifi' | 'cellular' | 'none' | 'unknown';
+}
+export interface NetworkFacade {
+    /** Returns current connection status. */
+    getStatus(): Promise<NetworkStatus>;
+    /**
+     * Subscribe to connectivity changes. Returns an unsubscribe function.
+     * Falls back to `window` `'online'`/`'offline'` events on web.
+     */
+    addListener(event: 'change', cb: (status: NetworkStatus) => void): () => void;
+}
+/** Device metadata. */
+export interface DeviceInfo {
+    model: string;
+    platform: 'ios' | 'android' | 'web';
+    osVersion: string;
+    manufacturer: string;
+    isVirtual: boolean;
+}
+export interface DeviceFacade {
+    /** Hardware and OS metadata. */
+    getInfo(): Promise<DeviceInfo>;
+    /**
+     * Stable device identifier — UUID persisted in `@capacitor/preferences`
+     * (native) or `localStorage` (web).
+     */
+    getId(): Promise<{
+        identifier: string;
+    }>;
+    /** Current locale language code, e.g. `'en'`, `'fr'`. */
+    getLanguageCode(): Promise<{
+        value: string;
+    }>;
+}
+/**
+ * Persistent key-value storage.
+ * Backed by `@capacitor/preferences` on native; `localStorage` on web;
+ * in-memory `Map` in private-browsing / third-party-cookie contexts.
+ */
+export interface StorageFacade {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+}
+/** QR / barcode scan. */
+export interface QrScanOptions {
+    /** BarcodeFormat strings to restrict scanning (e.g. `['QR_CODE', 'EAN_13']`). */
+    formats?: string[];
+}
+export interface QrFacade {
+    /**
+     * Open the barcode scanner UI and resolve with the decoded string.
+     * Uses Capacitor MLKit on native; html5-qrcode (or `BarcodeDetector`) on web.
+     * Throws `HostTimeoutError` when the user dismisses without scanning.
+     */
+    scan(opts?: QrScanOptions): Promise<string>;
+}
+/** Authentication. */
+export interface AuthFacade {
+    /**
+     * Initiate Google Sign-In. Returns the raw ID token for exchange with the
+     * SmartLinks auth backend. Falls back to an OAuth redirect flow on web.
+     */
+    signInWithGoogle(): Promise<{
+        idToken: string;
+    }>;
+    signOut(): Promise<void>;
+}
+/** NFC tag operations. */
+export interface NfcReadResult {
+    uid: string;
+    /** Raw NDEF payload (hex or base64 depending on host), when present. */
+    ndef?: string;
+}
+export interface NfcFacade {
+    /**
+     * Wait for the next NFC tap and return the tag's UID + optional NDEF.
+     * Throws `HostTimeoutError` after `opts.timeoutMs` (default: 30 s).
+     */
+    read(opts?: {
+        timeoutMs?: number;
+    }): Promise<NfcReadResult>;
+    /** Write an NDEF record to a tag by UID. */
+    writeNdef(opts: {
+        uid: string;
+        payload: string;
+    }): Promise<void>;
+    /** Program an NTAG 21x / 424 profile. Host-specific; Kotlin only on advanced ops. */
+    programTag(opts: {
+        uid: string;
+        profile: string;
+        [key: string]: unknown;
+    }): Promise<void>;
+    /** Lock a tag against further writes. */
+    lockTag(opts: {
+        uid: string;
+    }): Promise<void>;
+    /** Returns whether the tag is currently locked. */
+    isLocked(opts: {
+        uid: string;
+    }): Promise<boolean>;
+}
+/** RFID mass-scan (UHF). Only available on `custom-android`. */
+export interface RfidScanOptions {
+    /** Transmission power in dBm. */
+    power?: number;
+    /** Gen2 session flag (0–3). */
+    sessionFlag?: number;
+}
+export interface RfidFacade {
+    /** Start the RFID reader. Throws `HostCapabilityUnavailableError` on non-Kotlin hosts. */
+    startScan(opts?: RfidScanOptions): Promise<void>;
+    stopScan(): Promise<void>;
+    /** Subscribe to EPC bursts. Returns an unsubscribe function. */
+    subscribe(cb: (epcs: string[]) => void): () => void;
+}
+/** Cross-shell event bus. */
+export interface EventsFacade {
+    /**
+     * Subscribe to named events from any of: the Kotlin bridge
+     * (`onSmartlinksData`), Capacitor plugin listeners, or internal pub/sub.
+     * Returns an unsubscribe function.
+     */
+    subscribe(type: string, cb: (payload: unknown) => void): () => void;
+    /** Publish an event into the same bus. Useful for container ↔ container comms. */
+    emit(type: string, payload?: unknown): void;
+}
+/** OTA / web-source switching. */
+export type WebSourceMode = 'live' | 'bundled' | 'channel';
+export interface WebSourceConfig {
+    mode: WebSourceMode;
+    /** Only set when `mode === 'channel'`. */
+    channel?: string;
+    /** Only set when `mode === 'live'`. */
+    liveUrl?: string;
+}
+export interface WebSourceFacade {
+    /** Returns the currently active web source config. */
+    get(): Promise<WebSourceConfig>;
+    /** Switch web source mode. Takes effect on next app boot. */
+    set(config: WebSourceConfig): Promise<void>;
+}
+/**
+ * The full native capability facade exposed by the host on
+ * `AdminMobileHostContext.native` (containers) and `window.SL.native` (UMD
+ * microapps).
+ *
+ * Each sub-facade is present only when the host implements it. Check
+ * `'nfc' in host.native` (or `host.capabilities` for hardware-gated features)
+ * before calling.
+ *
+ * @example
+ *   const { native } = host;
+ *   if (native?.qr) {
+ *     const code = await native.qr.scan();
+ *   }
+ */
+export interface NativeFacade {
+    share: ShareFacade;
+    clipboard: ClipboardFacade;
+    haptics: HapticsFacade;
+    network: NetworkFacade;
+    device: DeviceFacade;
+    /** Cross-host persistent storage (`@capacitor/preferences` / `localStorage` fallback). */
+    storage: StorageFacade;
+    qr: QrFacade;
+    auth: AuthFacade;
+    nfc: NfcFacade;
+    /** RFID mass-scan. Only populated on `custom-android` hosts. */
+    rfid?: RfidFacade;
+    events: EventsFacade;
+    webSource: WebSourceFacade;
+}

package/dist/native/types.js

@@ -0,0 +1,15 @@
+/**
+ * Contract types for the `SL.native` / `host.native` facade.
+ *
+ * These are **interface-only** — no runtime implementation lives here.
+ * The facade is implemented per-host (Sidekick, Capacitor builds, PWA) and
+ * exposed to containers via `AdminMobileHostContext.native` or (for UMD
+ * microapps) via `window.SL.native`. The SDK owns the shape; the host owns
+ * the wiring.
+ *
+ * All facade methods reject with one of the structured errors from
+ * `@proveanything/smartlinks` (`HostCapabilityUnavailableError`,
+ * `HostPermissionDeniedError`, `HostTimeoutError`) so a single catch handler
+ * covers every host and capability.
+ */
+export {};

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.11.4  |  Generated: 2026-04-30T13:59:47.020Z
+Version: 1.11.6  |  Generated: 2026-05-01T13:42:06.488Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/app-objects.md

@@ -85,6 +85,7 @@ Zones are **automatically filtered** based on the caller's role:
 ### Zone Writing Rules
 
 - **Non-admin callers** attempting to write to the `admin` zone are silently ignored
+- **Authenticated record owners** can write to `data` and `owner` by default; individual keys can be restricted via the `ownerEdit` app config policy (see [Owner Edit Policy](#owner-edit-policy) below)
 - **Public callers** can write to `data` and `owner` (if visibility allows)
 - **Admins** can write to all three zones
 
@@ -1098,6 +1099,61 @@ The `enforce` values are **merged over** the caller's request body, so you can l
 
 ---
 
+## Owner Edit Policy
+
+Gives per-zone, field-level control over what an **authenticated record owner** can update via `PATCH /api/v1/public/collection/:collectionId/app/:appId/records/:recordId`.
+
+Set the policy in the same app config document used for `publicCreate` (stored at `sites/{collectionId}/apps/{appId}`):
+
+```json
+{
+  "ownerEdit": {
+    "records": {
+      "data":  { "allow": ["paypalEmail"] },
+      "owner": { "allow": ["paypalEmail", "paypalEmailUpdatedAt"] }
+    }
+  }
+}
+```
+
+### Zone visibility and write access
+
+| Zone    | Who can read           | Who can write (owner)                                    |
+|---------|------------------------|----------------------------------------------------------|
+| `data`  | public                 | Allow-listed keys only (if policy set); all keys if not  |
+| `owner` | owner + admin          | Allow-listed keys only (if policy set); all keys if not  |
+| `admin` | admin                  | Never — admin zone is always immutable to owners         |
+
+### Allow-list semantics
+
+| Config                     | Behaviour                                                                     |
+|----------------------------|-------------------------------------------------------------------------------|
+| No `ownerEdit` key         | Default-allow — both zones fully writable (no change to existing behaviour)   |
+| `allow` array with keys    | Only the listed keys are accepted from the PATCH body; the rest are silently ignored and their existing values preserved |
+| `allow: []` (empty array)  | Zone is effectively read-only for the owner                                   |
+
+Accepted keys are **merged** onto the existing zone blob — you do not need to re-send unchanged values.
+
+### Example: commission record with protected fields
+
+An app that lets owners update their payout email but not their commission total:
+
+```json
+{
+  "ownerEdit": {
+    "records": {
+      "owner": { "allow": ["paypalEmail", "paypalEmailUpdatedAt"] }
+    }
+  }
+}
+```
+
+A PATCH body of `{ "owner": { "paypalEmail": "x@y.com", "totalCommission": 99 } }` will update `paypalEmail` only. `totalCommission` is silently ignored and its existing value is preserved.
+
+> **App design note:** If your app creates records with sensitive fields that owners should never modify (e.g. computed totals, server-assigned fields), add an `ownerEdit` policy from the start. It is significantly easier to relax restrictions later than to tighten them after data has been mutated.
+
+---
+
 ## Anonymous Edit Tokens
 
 Enables an anonymous caller to amend a record they just created — without authentication — by presenting a short-lived secret token.

package/docs/mobile-admin-container.md

@@ -4,7 +4,7 @@
 
 This document describes how to build a **Mobile Admin Container** — a SmartLinks microapp that provides an in-the-field operator/admin surface optimised for mobile devices. These containers ship as a **separate `mobileAdmin` bundle** (not inside the `containers` bundle) so that Capacitor plugins, offline helpers, and operator-only code never reach the public consumer bundle.
 
-> **See also:** [containers.md](containers.md) covers the public consumer container. The [Multiple Consumer Components](containers.md#multiple-consumer-components) section explains the consumer vs. admin bundle split.
+> **See also:** [containers.md](containers.md) covers the public consumer container. The [Multiple Consumer Components](containers.md#multiple-consumer-components) section explains the consumer vs. admin bundle split. For the full `host.native` facade contract (share, clipboard, haptics, NFC, RFID, storage, etc.) see [native-facade.md](native-facade.md).
 
 ---
 
@@ -23,6 +23,7 @@ This document describes how to build a **Mobile Admin Container** — a SmartLin
 11. [Build & Bundle Requirements](#build--bundle-requirements)
 12. [Example: Minimal Mobile Admin Container](#example-minimal-mobile-admin-container)
 13. [Best Practices](#best-practices)
+14. [Native Capability Facade](#native-capability-facade)
 
 ---
 
@@ -58,7 +59,7 @@ 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.
+> **SDK export** — `AdminMobileHostContext`, `AdminMobileCapability`, `ActionableCapability`, `AdminMobileHostId`, `AdminMobileEvent`, `AdminMobileEventCallback`, `AdminMobileEventSubscriber`, `AdminMobileComponentManifest`, `AdminMobileBundleManifest`, and `NativeFacade` (plus all sub-facade interfaces) are 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 {
@@ -112,6 +113,10 @@ interface AdminMobileHostContext {
   // Informational host version — use for logging/diagnostics, not feature detection.
   // For feature detection prefer existence checks: 'requestNfcTap' in host.actions
   _version: number
+
+  // Full native capability facade — share, clipboard, haptics, NFC, RFID, storage, etc.
+  // Optional: not every host stub populates it. See native-facade.md.
+  native?: NativeFacade
 }
 ```
 
@@ -542,3 +547,26 @@ export const MOBILE_ADMIN_MANIFEST = {
 - **Bundle Capacitor plugins in** (do not externalise) — so the component degrades gracefully on PWA/browser without crashing.
 - **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.
+
+---
+
+## Native Capability Facade
+
+`host.native` gives containers access to a broader set of device capabilities — share sheet, clipboard, full haptics API, storage, QR, NFC, RFID (Kotlin only), auth, and cross-shell events — through a single interface that falls back gracefully across all host environments.
+
+```typescript
+// Check host.hardware.* for physical availability, then call via host.native
+if (host.hardware.nfc && host.native?.nfc) {
+  const { uid } = await host.native.nfc.read({ timeoutMs: 10_000 })
+}
+
+// Storage always available (Preferences → localStorage → in-memory Map)
+await host.native?.storage.set('lastScan', uid)
+
+// Share sheet with web fallback
+await host.native?.share.share({ title: 'Found tag', url: `https://app.example/tags/${uid}` })
+```
+
+`host.native` is optional on `AdminMobileHostContext` — host stubs (Storybook, unit tests) need not implement it. `native.rfid` is additionally optional within `NativeFacade` itself, as it only exists on `custom-android`.
+
+For the full sub-facade table, fallback chains, and what's intentionally not wrapped, see **[native-facade.md](native-facade.md)**.

package/docs/native-facade.md

@@ -0,0 +1,170 @@
+# Native Capability Facade (`host.native` / `SL.native`)
+
+> **Version:** 1.12 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+
+The `NativeFacade` is a thin contract layer between microapps and the device capabilities available on the current host shell (Kotlin, Capacitor iOS/Android, PWA, or browser). It lets a microapp call `host.native.share.share({...})` without knowing whether it's running over `window.SmartlinksScanner`, a Capacitor plugin, or `navigator.share`.
+
+**The SDK owns the contract** (`src/native/types.ts`, re-exported from `@proveanything/smartlinks`). Each host implementation is responsible for wiring up the sub-facades and populating:
+- `AdminMobileHostContext.native` (container prop, typed in the SDK), and
+- `window.SL.native` (for UMD microapps that don't receive a host prop — host concern, not SDK).
+
+---
+
+## Table of Contents
+
+1. [Access patterns](#access-patterns)
+2. [What's in the facade](#whats-in-the-facade)
+3. [What's NOT in the facade](#whats-not-in-the-facade)
+4. [Error contract](#error-contract)
+5. [Type reference](#type-reference)
+
+---
+
+## Access patterns
+
+### Inside a Mobile Admin Container (recommended)
+
+```typescript
+import type { AdminMobileHostContext } from '@proveanything/smartlinks'
+
+function MyContainer({ host }: { host: AdminMobileHostContext }) {
+  const handleShare = async () => {
+    await host.native?.share.share({ title: 'SmartLinks', url: window.location.href })
+  }
+
+  const handleScan = async () => {
+    // Only present when the host provides a QR reader
+    const code = await host.native?.qr.scan()
+    if (code) processCode(code)
+  }
+}
+```
+
+Always call via `host.native?.<facade>.<method>()` — `native` is optional because not every host exposes the full surface (e.g. a minimal browser stub may omit `rfid`).
+
+For hardware-gated capabilities (NFC, RFID, QR, camera) also check `host.capabilities` or `host.hardware.*` before calling, as those flags reflect physical availability on the current device:
+
+```typescript
+if (host.hardware.nfc && host.native?.nfc) {
+  const { uid } = await host.native.nfc.read({ timeoutMs: 10_000 })
+}
+```
+
+### Inside a UMD microapp (no host prop)
+
+```typescript
+// window.SL.native is populated by the host at boot — host concern, not SDK
+const native = (window as any).SL?.native as import('@proveanything/smartlinks').NativeFacade | undefined
+const code = await native?.qr.scan()
+```
+
+---
+
+## What's in the facade
+
+These capabilities have meaningful fallbacks across Kotlin / Capacitor / web. Always go through the facade.
+
+| Sub-facade | Key methods | Fallback chain |
+|---|---|---|
+| `native.share` | `share({ title, url, text? })`, `canShare()` | Capacitor Share → `navigator.share` → copy to clipboard + toast |
+| `native.clipboard` | `write(text)`, `read()` | Capacitor Clipboard → `navigator.clipboard` → `execCommand('copy')` |
+| `native.haptics` | `impact(style?)`, `notification(style)`, `selection()` | Capacitor Haptics → `navigator.vibrate` → no-op |
+| `native.network` | `getStatus()`, `addListener('change', cb)` | Capacitor Network → `navigator.onLine` + `'online'`/`'offline'` events |
+| `native.device` | `getInfo()`, `getId()`, `getLanguageCode()` | Capacitor Device → UA parsing + cached UUID in `localStorage` |
+| `native.storage` | `get(key)`, `set(key, value)`, `remove(key)`, `keys()` | Capacitor Preferences → `localStorage` → in-memory `Map` (private mode) |
+| `native.qr` | `scan(opts?)` | Capacitor MLKit Barcode → html5-qrcode / `BarcodeDetector` |
+| `native.auth` | `signInWithGoogle()`, `signOut()` | Kotlin bridge → Capacitor Browser + OAuth → web redirect |
+| `native.nfc` | `read(opts?)`, `writeNdef(opts)`, `programTag(opts)`, `lockTag(opts)`, `isLocked(opts)` | Kotlin bridge → Web NFC (`NDEFReader`) → `HostCapabilityUnavailableError` |
+| `native.rfid` | `startScan(opts?)`, `stopScan()`, `subscribe(cb)` | Kotlin bridge only — throws `HostCapabilityUnavailableError` on all other hosts |
+| `native.events` | `subscribe(type, cb)`, `emit(type, payload?)` | Internal pub/sub bridging Kotlin `onSmartlinksData` + Capacitor listeners |
+| `native.webSource` | `get()`, `set({ mode, channel?, liveUrl? })` | Kotlin bridge + Capacitor Preferences mirror |
+
+> **`native.rfid` is the only optional sub-facade** on `NativeFacade` — it is only populated on `custom-android` hosts. All other sub-facades are present on every host, though individual methods may throw `HostCapabilityUnavailableError` when the underlying capability is absent.
+
+> **`native.device` vs `host.device`** — `host.device.info()` is a simplified convenience that returns `{ model, platform }`. `host.native?.device.getInfo()` returns the full `DeviceInfo` (adds `osVersion`, `manufacturer`, `isVirtual`) and also provides `getId()` and `getLanguageCode()`. Use `host.device` when the convenience is enough.
+
+> **`native.network` vs `host.network`** — `host.network.isOnline()` is a boolean convenience. `host.native?.network.getStatus()` returns `{ connected, connectionType }` including `'wifi'` / `'cellular'` distinction.
+
+---
+
+## What's NOT in the facade
+
+These capabilities intentionally have no `SL.native` wrapper. Call the Capacitor plugin directly, or use the web API. The host provides them as Tier 1 or Tier 2 plugins (see [Capacitor Plugin Baseline](mobile-admin-container.md#capacitor-plugin-baseline)).
+
+| Capability | Why not wrapped |
+|---|---|
+| `@capacitor/push-notifications` | Push only exists in Capacitor builds; no cross-shell registration flow. Import and call directly; detect Capacitor first. |
+| `@capacitor/local-notifications` | Same — no Kotlin or web equivalent worth abstracting. |
+| `@capacitor/camera` | Plugin already abstracts iOS/Android. PWA's `<input capture>` is too different in shape to unify. |
+| `@capacitor/filesystem` | No web equivalent (storage quotas, sandbox rules differ). Use `URL.createObjectURL` + download anchor on web. |
+| `@capacitor/geolocation` | `navigator.geolocation` already works in WebViews; the Capacitor plugin wraps the same OS APIs. No facade adds value. |
+| `@capacitor/keyboard`, `@capacitor/screen-*`, `@capacitor/splash-screen`, `@capacitor/status-bar`, `@capacitor/dialog`, `@capacitor/app` | Per-host boot-time config or platform-chrome concerns; not part of the microapp contract. |
+| `@capacitor/browser` | In-app browser for OAuth is intentionally Capacitor-only. For opening external URLs use `native.share.share({ url })`. |
+| `@capawesome/capacitor-file-picker` | Picker UX too divergent across web (`<input type="file">`) and native to wrap usefully. |
+
+If a capability later needs consistent behaviour across shells (e.g. notifications reach enough hosts to warrant throttling / routing via the facade), promote it into `NativeFacade` by adding an interface to `src/native/types.ts` and a row to the table above.
+
+---
+
+## Error contract
+
+All facade methods reject with one of the three structured errors from `@proveanything/smartlinks`. A single catch block handles every capability and host combination:
+
+```typescript
+import {
+  HostCapabilityUnavailableError,
+  HostPermissionDeniedError,
+  HostTimeoutError,
+} from '@proveanything/smartlinks'
+
+try {
+  const { uid } = await host.native?.nfc.read({ timeoutMs: 10_000 }) ?? {}
+} catch (err) {
+  if (err instanceof HostCapabilityUnavailableError) {
+    // host.capabilities won't list 'nfc' — we should have checked first
+    host.ui.toast?.({ title: 'NFC not available on this device', variant: 'destructive' })
+  } else if (err instanceof HostPermissionDeniedError) {
+    host.ui.toast?.({ title: 'NFC permission denied', variant: 'destructive' })
+  } else if (err instanceof HostTimeoutError) {
+    host.ui.toast?.({ title: `No tag detected after ${err.timeoutMs / 1000}s` })
+  } else {
+    throw err
+  }
+}
+```
+
+---
+
+## Type reference
+
+All types below are exported from `@proveanything/smartlinks`:
+
+```typescript
+import type {
+  NativeFacade,          // root — use on AdminMobileHostContext.native
+  NativeCapability,      // union of sub-facade keys: 'share' | 'clipboard' | ...
+  ShareFacade,
+  ClipboardFacade,
+  HapticsFacade,
+  HapticImpactStyle,     // 'light' | 'medium' | 'heavy'
+  HapticNotificationStyle,
+  NetworkFacade,
+  NetworkStatus,
+  DeviceFacade,
+  DeviceInfo,
+  StorageFacade,
+  QrFacade,
+  QrScanOptions,
+  AuthFacade,
+  NfcFacade,
+  NfcReadResult,
+  RfidFacade,
+  RfidScanOptions,
+  EventsFacade,
+  WebSourceFacade,
+  WebSourceMode,
+  WebSourceConfig,
+} from '@proveanything/smartlinks'
+```
+
+The facade interfaces are contract-only — no runtime implementation is shipped in the SDK. You only need them for TypeScript type-checking (authoring containers or host stubs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.11.4",
+  "version": "1.11.6",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",