@proveanything/smartlinks 1.11.2 → 1.11.5

package/dist/docs/API_SUMMARY.md

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

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`, `AdminMobileHostId`, `AdminMobileEvent`, `ScannerEventSubscriber`, `MobileAdminComponentManifest`, and `MobileAdminBundleManifest` are all exported from `@proveanything/smartlinks`. Import via `import type { AdminMobileHostContext } from '@proveanything/smartlinks'` — no local mirror needed.
+> **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 {
@@ -82,8 +83,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: {
@@ -97,12 +98,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
@@ -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
 }
 ```
 
@@ -143,9 +148,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:**
 
@@ -222,12 +228,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 |
@@ -385,7 +402,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.
 
 ---
 
@@ -521,10 +540,33 @@ 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.
 - **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

@@ -23,5 +23,8 @@ export type { Collection, CollectionResponse, CollectionCreateRequest, Collectio
 export type { Proof, ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, } from "./types/proof";
 export type { QrShortCodeLookupResponse, } from "./types/qr";
 export type { ReverseTagLookupParams, ReverseTagLookupResponse, } from "./types/tags";
-export type { AdminMobileCapability, AdminMobileHostId, AdminMobileEvent, ScannerEventSubscriber, AdminMobileHostContext, MobileAdminComponentManifest, MobileAdminBundleManifest, } from './mobile-admin/types';
+export type { AdminMobileCapability, ActionableCapability, AdminMobileHostId, AdminMobileEvent, AdminMobileEventCallback, AdminMobileEventSubscriber, ScannerEventSubscriber, // @deprecated — use AdminMobileEventCallback
+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/errors.d.ts

@@ -5,6 +5,7 @@
  * All three classes call `Object.setPrototypeOf(this, new.target.prototype)` so
  * `instanceof` works correctly when transpiled to ES5.
  */
+import type { ActionableCapability, AdminMobileHostId } from './types';
 /**
  * Thrown when a container requests a hardware action that the current host
  * does not support (e.g. calling `requestNfcTap` on a `'pwa'` host).
@@ -20,10 +21,10 @@
  */
 export declare class HostCapabilityUnavailableError extends Error {
     /** The capability that was requested but is unavailable. */
-    capability: 'nfc' | 'rfid' | 'qr' | 'camera';
-    /** `AdminMobileHostId` string of the host that rejected the request. */
-    host: string;
-    constructor(capability: HostCapabilityUnavailableError['capability'], host: string);
+    capability: ActionableCapability;
+    /** The host on which the capability is unavailable. */
+    host: AdminMobileHostId;
+    constructor(capability: ActionableCapability, host: AdminMobileHostId);
 }
 /**
  * Thrown when the user denies a runtime permission request (e.g. camera or
@@ -40,8 +41,8 @@ export declare class HostCapabilityUnavailableError extends Error {
  */
 export declare class HostPermissionDeniedError extends Error {
     /** The capability for which permission was denied. */
-    capability: 'nfc' | 'rfid' | 'qr' | 'camera';
-    constructor(capability: HostPermissionDeniedError['capability']);
+    capability: ActionableCapability;
+    constructor(capability: ActionableCapability);
 }
 /**
  * Thrown when a time-bounded host action (NFC tap, QR scan) exceeds its
@@ -58,7 +59,7 @@ export declare class HostPermissionDeniedError extends Error {
  */
 export declare class HostTimeoutError extends Error {
     /** The capability that timed out. */
-    capability: 'nfc' | 'qr';
+    capability: Extract<ActionableCapability, 'nfc' | 'qr' | 'geolocation'>;
     /** The timeout threshold in milliseconds. */
     timeoutMs: number;
     constructor(capability: HostTimeoutError['capability'], timeoutMs: number);

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

@@ -1,9 +1,16 @@
+import type { NativeFacade } from '../native/types';
 /**
  * Hardware/software capability tokens a mobile admin host may advertise.
  * Passed to `AdminMobileHostContext.capabilities` and to
- * `MobileAdminComponentManifest.capabilities`.
+ * `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
@@ -31,8 +38,19 @@ export type AdminMobileEvent = {
     type: 'lifecycle';
     phase: 'pause' | 'resume' | 'offline' | 'online';
 };
-/** Callback signature for `AdminMobileHostContext.events.subscribe`. */
-export type ScannerEventSubscriber = (event: AdminMobileEvent) => void;
+/** 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.
  *
@@ -82,7 +100,7 @@ export interface AdminMobileHostContext {
          * @param cb - Called for every incoming `AdminMobileEvent`.
          * @returns Cleanup function — call inside `useEffect` return.
          */
-        subscribe: (cb: ScannerEventSubscriber) => () => void;
+        subscribe: (cb: AdminMobileEventCallback) => () => void;
     };
     /** Imperative hardware actions. */
     actions: {
@@ -137,8 +155,16 @@ export interface AdminMobileHostContext {
         }) => void;
         /** Trigger a haptic pulse. Optional — see interface note. */
         haptic?: (style?: 'light' | 'success' | 'error') => void;
-        setHeaderTitle: (title: string | null) => void;
-        navigateBack: () => 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: {
@@ -160,9 +186,19 @@ 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 MobileAdminComponentManifest {
+export interface AdminMobileComponentManifest {
     /** Component export name (matches the export in the bundle). */
     name: string;
     /** Human-readable description shown in the host launcher UI. */
@@ -184,7 +220,7 @@ export interface MobileAdminComponentManifest {
  * Shape of the `mobileAdmin` key inside `app.manifest.json`.
  * Describes the bundle files and the components it exports.
  */
-export interface MobileAdminBundleManifest {
+export interface AdminMobileBundleManifest {
     files: {
         js: {
             /** UMD bundle path (relative to dist root). Used by the custom-android host. */
@@ -195,5 +231,15 @@ export interface MobileAdminBundleManifest {
         /** CSS bundle path, or `null` if the component ships no styles. */
         css: string | null;
     };
-    components: MobileAdminComponentManifest[];
+    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/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.2  |  Generated: 2026-04-30T13:11:24.914Z
+Version: 1.11.5  |  Generated: 2026-04-30T16:31:53.616Z
 
 This is a concise summary of all available API functions and types.
 

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`, `AdminMobileHostId`, `AdminMobileEvent`, `ScannerEventSubscriber`, `MobileAdminComponentManifest`, and `MobileAdminBundleManifest` are all exported from `@proveanything/smartlinks`. Import via `import type { AdminMobileHostContext } from '@proveanything/smartlinks'` — no local mirror needed.
+> **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 {
@@ -82,8 +83,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: {
@@ -97,12 +98,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
@@ -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
 }
 ```
 
@@ -143,9 +148,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:**
 
@@ -222,12 +228,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 |
@@ -385,7 +402,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.
 
 ---
 
@@ -521,10 +540,33 @@ 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.
 - **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.2",
+  "version": "1.11.5",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",