@proveanything/smartlinks 2.0.43 → 2.0.45

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.43  |  Generated: 2026-10-06T15:37:31.849Z
+Version: 2.0.45  |  Generated: 2026-10-06T17:22:34.344Z
 
 This is a concise summary of all available API functions and types.
 

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

@@ -86,11 +86,11 @@ interface AdminMobileHostContext {
   // Unified hardware event stream — callback type: AdminMobileEventCallback
   events: { subscribe: (cb: AdminMobileEventCallback) => () => void }
 
-  // Promise-based hardware actions — reject with a structured error when unavailable
+  // Promise-based hardware actions — reject with a structured error when unavailable or cancelled
   actions: {
-    requestQrScan: () => Promise<string>
-    requestNfcTap: (timeoutMs?: number) => Promise<{ uid: string; ndef?: string }>
-    requestCameraPhoto: () => Promise<Blob>
+    requestQrScan: (opts?: { signal?: AbortSignal; heightPercent?: number; prompt?: string }) => Promise<string>
+    requestNfcTap: (opts?: { timeoutMs?: number; signal?: AbortSignal; prompt?: string } | number) => Promise<{ uid: string; ndef?: string }>
+    requestCameraPhoto: (opts?: { signal?: AbortSignal }) => Promise<Blob>
     share: (payload: { title: string; url: string; text?: string }) => Promise<void>
     clipboard: {
       read: () => Promise<string>
@@ -106,6 +106,9 @@ interface AdminMobileHostContext {
     navigateBack?: () => void
   }
 
+  // UHF RFID reader — only on hosts with one (feature-detect). See "RFID" below.
+  rfid?: AdminMobileRfid
+
   // Network & device info
   network: { isOnline: () => boolean }
   device: { info: () => Promise<{ model: string; platform: string }> }
@@ -331,6 +334,92 @@ The SmartLinks Mobile launcher loads your `mobileAdmin` bundle through the platf
 
 ---
 
+## Scanning: listening vs asking
+
+Every scan reaches a container in one of two ways. Pick per screen.
+
+| | Listening — `host.events` | Asking — `host.actions.request*` |
+|---|---|---|
+| Use for | "Tap or scan anything, any time" — a stock take, a scan-to-open list | "This step needs a scan" — tag this item, scan the shelf code |
+| What the user sees | Nothing changes | NFC: a small non-blocking hint with Cancel. QR / photo: the host's camera opens |
+| What you get | An event per tap / read / key | A promise for one result |
+
+### NFC: two modes
+
+- **Listening** — subscribe to `nfc-tap`. Fires for every tap while no request is waiting.
+- **Asking** — `await host.actions.requestNfcTap({ prompt: 'Tap the bottle tag', signal })`. The next tap
+  **made after the call** resolves it, and that tap is **not** also sent as an `nfc-tap` event, so
+  nothing handles it twice. The request is non-blocking: the screen stays usable while it waits — show
+  your own "or type the code" path and abort the wait with `signal` if the user takes it. One request at
+  a time: a new call cancels the previous one.
+
+```typescript
+const controller = new AbortController()
+try {
+  const { uid } = await host.actions.requestNfcTap({ prompt: 'Tap the bottle tag', signal: controller.signal })
+  await attachTag(uid)
+} catch (err) {
+  if (err instanceof HostCancelledError) return   // they pressed Cancel, or we aborted
+  throw err
+}
+// elsewhere — the user typed the code instead:
+controller.abort()
+```
+
+### QR and photos
+
+`requestQrScan()` opens the host's camera scanner (full screen, or the bottom `heightPercent` of it) and
+resolves with the code; `requestCameraPhoto()` opens the camera and resolves with the image. Both reject
+with `HostCancelledError` when the user backs out.
+
+### RFID
+
+`host.rfid` gives a container the same reader abilities the host's own scanner uses — so an app can be
+its own scanner. It's present only when the device has a UHF reader (`hardware.rfid`); check for it.
+There's one reader, so starting any of the three below ends the one before, and everything stops when
+the container unmounts.
+
+**Keep reading** — a stock take, an intake. De-duplicated and batched, so you get each tag once instead
+of hundreds of raw reads a second:
+
+```typescript
+const session = host.rfid?.read({
+  filter: { prefix: '3034' },  // optional: only EPCs starting with this (or { epcs: [...] })
+  dedupe: 'session',           // default — each tag once; { windowMs: 5000 } or 'none' for every read
+  batchMs: 250,                // default — reads arrive in batches; 0 = one at a time
+  mode: 'trigger',             // default — reads while the operator holds the trigger; 'continuous' = now until stop()
+})
+const off = session?.onRead((reads) => {        // [{ epc, tid?, rssi?, timestamp, count }]
+  for (const r of reads) addToCount(r.epc)
+})
+// later
+session?.stop()
+```
+
+**One tag for this step** — tag an item. Resolves with the strongest tag read in the first moment of
+reading, then stops; the RFID counterpart of `requestNfcTap` (non-blocking, abortable, `prompt` hint):
+
+```typescript
+const { epc } = await host.rfid.readOne({ prompt: 'Pull the trigger over the item', signal })
+```
+
+**Find a tag** — a Geiger counter. `strength` runs 0 (not in range) to 100 (right here); by default the
+host plays faster beeps and haptics as you close in (`feedback: false` to do your own):
+
+```typescript
+const hunt = host.rfid?.locate(item.epcs)   // one EPC, or every tag on the item
+hunt?.onUpdate(({ strength, rssi, hitsPerSecond }) => setStrength(strength))
+// hunt.stop() when found
+```
+
+`status()` / `onStatus(cb)` report whether a reader is available and connected, which one (`built-in`,
+`zebra`, `tsl`), whether it's reading, and its power range; `read`/`locate` take a `power` level for the
+session.
+
+Raw reads still arrive as `rfid-burst` events whenever the reader runs, for containers that want them.
+
+---
+
 ## Event Stream
 
 For raw scan events (rather than the action-driven `host.actions.requestNfcTap`), subscribe to the unified event stream. Events flow identically on every host — the launcher normalises bridge messages, Capacitor callbacks, and Web API events into the same shape.
@@ -350,6 +439,13 @@ useEffect(() => {
 }, [host.events])
 ```
 
+Event details:
+
+- Every event may carry `timestamp` (ms since epoch).
+- `nfc-tap` — `uid` is uppercase hex without separators (`04A1B2C3D4E5F6`); `ndef` is the tag's NDEF text (usually its URL), `""` when it had none.
+- `rfid-burst` — reads arrive as they happen, typically **one EPC per event, many per second** while the trigger is held. Collect and de-duplicate them yourself. `rssi` (dBm; closer = higher) when the reader reports it.
+- `key-press` — hosts that report both edges send `action: 'down'` then `'up'` for one press; act on `'down'` (or on events without `action`). `293` is the scan trigger.
+
 Lifecycle events (`event.type === 'lifecycle'`) carry a `phase` field: `'pause' | 'resume' | 'offline' | 'online'`. Use these instead of `window` event listeners so your container works identically on all hosts.
 
 ---
@@ -372,8 +468,15 @@ class HostTimeoutError extends Error {
   capability: 'nfc' | 'qr'
   timeoutMs: number
 }
+
+class HostCancelledError extends Error {
+  capability: 'nfc' | 'qr' | 'camera'
+  by: 'user' | 'app'   // closed the scanner / pressed Cancel, or aborted by the container
+}
 ```
 
+All four are exported from `@proveanything/smartlinks`; check with `instanceof` or `err.name`.
+
 ```typescript
 try {
   const code = await host.actions.requestQrScan()

package/dist/index.d.ts

@@ -31,9 +31,9 @@ export type { Collection, CollectionResponse, CollectionCreateRequest, Collectio
 export type { Proof, ProofResponse, ProofWrite, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, GrantScope, GrantAudience, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, ProofTransfer, ProofTransferType, ProofTransferState, TransferProofOptions, TransferProofResult, } from "./types/proof.js";
 export type { QrShortCodeLookupResponse, } from "./types/qr.js";
 export type { ReverseTagLookupParams, ReverseTagLookupResponse, } from "./types/tags.js";
-export type { AdminMobileCapability, ActionableCapability, AdminMobileHostId, AdminMobileEvent, AdminMobileEventCallback, AdminMobileEventSubscriber, ScannerEventSubscriber, // @deprecated — use AdminMobileEventCallback
+export type { AdminMobileCapability, ActionableCapability, AdminMobileHostId, AdminMobileEvent, AdminMobileEventCallback, AdminMobileEventSubscriber, NfcTapRequestOptions, QrScanRequestOptions, CameraPhotoRequestOptions, AdminMobileRfid, RfidRead, RfidReaderStatus, RfidFilter, RfidReadOptions, RfidReadSession, RfidReadOneOptions, RfidLocateOptions, RfidLocateUpdate, RfidLocateSession, ScannerEventSubscriber, // @deprecated — use AdminMobileEventCallback
 AdminMobileHostContext, AdminMobileComponentManifest, AdminMobileBundleManifest, MobileAdminComponentManifest, // @deprecated — use AdminMobileComponentManifest
 MobileAdminBundleManifest, } from './mobile-admin/types.js';
-export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors.js';
+export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, HostCancelledError, } from './mobile-admin/errors.js';
 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.js';
 export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, RefreshResponse, LogoutResponse, RefreshErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, AuthKitConfigInput, AuthKitSecurityConfig, AuthKitPasswordPolicy, AuthKitSessionPolicy, AuthKitLockoutPolicy, PasswordPolicyErrorCode, LoginSecurityErrorCode, } from './types/authKit.js';

package/dist/index.js

@@ -23,4 +23,4 @@ export { headless_1 as headless };
 export { SHARED_DEPENDENCY_CONTRACT_VERSION, SHARED_DEPENDENCIES, SHARED_DEPENDENCY_SPECIFIERS, importMapPathFor, getHostSharedDependencies, } from './shared-dependencies.js';
 // Built-in AI tool catalog (design-time discovery of the core agentic toolset)
 export { AI_TOOL_NAMES, BUILTIN_AI_TOOLS, getBuiltinAiTool } from './ai-tools.js';
-export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors.js';
+export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, HostCancelledError, } from './mobile-admin/errors.js';

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

@@ -59,8 +59,29 @@ export declare class HostPermissionDeniedError extends Error {
  */
 export declare class HostTimeoutError extends Error {
     /** The capability that timed out. */
-    capability: Extract<ActionableCapability, 'nfc' | 'qr' | 'geolocation'>;
+    capability: Extract<ActionableCapability, 'nfc' | 'qr' | 'rfid' | 'geolocation'>;
     /** The timeout threshold in milliseconds. */
     timeoutMs: number;
     constructor(capability: HostTimeoutError['capability'], timeoutMs: number);
 }
+/**
+ * Thrown when a host action ends without a result because someone stopped it: the user closed the
+ * scanner / pressed Cancel on the "tap a tag" hint (`by: 'user'`), or the container aborted it with its
+ * `signal` or replaced it with a newer request (`by: 'app'`). Usually not an error to show — the user
+ * chose to stop.
+ *
+ * @example
+ *   try {
+ *     const code = await host.actions.requestQrScan();
+ *   } catch (err) {
+ *     if (err instanceof HostCancelledError) return; // they closed the scanner
+ *     throw err;
+ *   }
+ */
+export declare class HostCancelledError extends Error {
+    /** The capability whose action was cancelled. */
+    capability: ActionableCapability;
+    /** Who stopped it. */
+    by: 'user' | 'app';
+    constructor(capability: ActionableCapability, by?: 'user' | 'app');
+}

package/dist/mobile-admin/errors.js

@@ -70,3 +70,26 @@ export class HostTimeoutError extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/**
+ * Thrown when a host action ends without a result because someone stopped it: the user closed the
+ * scanner / pressed Cancel on the "tap a tag" hint (`by: 'user'`), or the container aborted it with its
+ * `signal` or replaced it with a newer request (`by: 'app'`). Usually not an error to show — the user
+ * chose to stop.
+ *
+ * @example
+ *   try {
+ *     const code = await host.actions.requestQrScan();
+ *   } catch (err) {
+ *     if (err instanceof HostCancelledError) return; // they closed the scanner
+ *     throw err;
+ *   }
+ */
+export class HostCancelledError extends Error {
+    constructor(capability, by = 'user') {
+        super(`Capability '${capability}' was cancelled by the ${by}`);
+        this.name = 'HostCancelledError';
+        this.capability = capability;
+        this.by = by;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

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

@@ -21,23 +21,199 @@ export type AdminMobileHostId = 'custom-android' | 'capacitor-ios' | 'capacitor-
  * Discriminated-union of all events the host may emit via
  * `AdminMobileHostContext.events.subscribe`.
  */
-export type AdminMobileEvent = {
+export type AdminMobileEvent = 
+/**
+ * A tag was tapped while NO `requestNfcTap()` was waiting (a waiting request takes the tap instead).
+ * `uid` is uppercase hex without separators (e.g. `04A1B2C3D4E5F6`); `ndef` is the tag's NDEF text
+ * (usually its URL), `""` when the tag had none or it couldn't be read.
+ */
+{
     type: 'nfc-tap';
     uid: string;
     ndef?: string;
-} | {
+    timestamp?: number;
+}
+/**
+ * RFID reads while the reader is running. Hosts deliver reads as they come — typically ONE EPC per
+ * event, many per second while the trigger is held — so collect and de-duplicate them yourself.
+ * `rssi` (dBm, negative; closer = higher) is the signal strength of the read when known.
+ */
+ | {
     type: 'rfid-burst';
     epcs: string[];
+    rssi?: number;
+    timestamp?: number;
 } | {
     type: 'qr-scan';
     code: string;
-} | {
+    timestamp?: number;
+}
+/**
+ * A hardware key. Hosts that report both edges send `action: 'down'` then `'up'` for one press —
+ * act on `'down'` (or on events with no `action`, from hosts that report presses only).
+ * 293 is the handheld scan trigger.
+ */
+ | {
     type: 'key-press';
     keyCode: number;
+    action?: 'down' | 'up';
+    timestamp?: number;
 } | {
     type: 'lifecycle';
     phase: 'pause' | 'resume' | 'offline' | 'online';
+    timestamp?: number;
 };
+/**
+ * Options for `host.actions.requestNfcTap`.
+ *
+ * The request is NON-BLOCKING: it only waits for a tag. Keep the screen usable while it waits (e.g.
+ * offer "enter the code instead") and abort the wait with `signal` if the user goes another way.
+ */
+export interface NfcTapRequestOptions {
+    /** Give up after this long with `HostTimeoutError`. Default: wait until tapped or aborted. */
+    timeoutMs?: number;
+    /** Abort the wait (rejects with `HostCancelledError`, `by: 'app'`). */
+    signal?: AbortSignal;
+    /** Short hint the host shows while waiting, e.g. "Tap the bottle's tag". Host default if omitted. */
+    prompt?: string;
+}
+/** Options for `host.actions.requestQrScan`. */
+export interface QrScanRequestOptions {
+    /** Close the scanner (rejects with `HostCancelledError`, `by: 'app'`). */
+    signal?: AbortSignal;
+    /** Fraction of the screen the camera view covers, from the bottom (0.3–1). Default 1 (full screen). */
+    heightPercent?: number;
+    /** Short hint shown over the camera view. */
+    prompt?: string;
+}
+/** One RFID tag read (or, when batched, one tag's reads within the batch). */
+export interface RfidRead {
+    /** The tag's EPC, uppercase hex. */
+    epc: string;
+    /** Manufacturer-burned tag ID, when the reader reports it. */
+    tid?: string;
+    /** Signal strength in dBm (negative; closer = higher). Best (highest) in the batch. */
+    rssi?: number;
+    /** When it was (last) read, ms since epoch. */
+    timestamp: number;
+    /** How many times this tag was read in the batch. */
+    count: number;
+}
+/** The reader as the host sees it. */
+export interface RfidReaderStatus {
+    /** A UHF reader is selected on this device. */
+    available: boolean;
+    /** It's connected and ready (a Bluetooth reader may be available but not connected). */
+    connected: boolean;
+    /** Which reader: the device's built-in one or an external one. */
+    reader: 'built-in' | 'zebra' | 'tsl' | 'other' | null;
+    /** The reader is reading right now. */
+    reading: boolean;
+    /** Transmit power, when the reader supports changing it. */
+    power?: {
+        level: number;
+        min: number;
+        max: number;
+    };
+}
+/** Which tags a session reports. Reads of any other tag are dropped. */
+export interface RfidFilter {
+    /** Only these EPCs. */
+    epcs?: string[];
+    /** Only EPCs starting with this (hex, e.g. your company prefix). */
+    prefix?: string;
+}
+/** Options for `host.rfid.read()`. */
+export interface RfidReadOptions {
+    filter?: RfidFilter;
+    /**
+     * `'session'` (default): each tag is reported once per session. `{ windowMs }`: again only after it
+     * hasn't been read for that long. `'none'`: every read.
+     */
+    dedupe?: 'session' | 'none' | {
+        windowMs: number;
+    };
+    /** Deliver reads in batches every this many ms (default 250). `0` = each read as it arrives. */
+    batchMs?: number;
+    /**
+     * `'trigger'` (default): the reader runs while the operator holds the handheld's trigger.
+     * `'continuous'`: it runs from now until `stop()`.
+     */
+    mode?: 'trigger' | 'continuous';
+    /** Transmit power for this session (see `status().power`); restored afterwards. */
+    power?: number;
+}
+/** A reading session from `host.rfid.read()`. One session at a time: a new one stops the previous. */
+export interface RfidReadSession {
+    /** Reads, batched per `batchMs`. Returns an unsubscribe function. */
+    onRead(cb: (reads: RfidRead[]) => void): () => void;
+    /** Distinct tags reported so far. */
+    readonly count: number;
+    /** Stop reading and end the session. */
+    stop(): void;
+}
+/** Options for `host.rfid.readOne()`. */
+export interface RfidReadOneOptions {
+    filter?: RfidFilter;
+    /** Give up after this long with `HostTimeoutError`. Default: until a tag is read or aborted. */
+    timeoutMs?: number;
+    /** Abort (rejects with `HostCancelledError`, `by: 'app'`). */
+    signal?: AbortSignal;
+    /** Short hint the host shows while waiting, e.g. "Pull the trigger over the item". */
+    prompt?: string;
+    /** `'trigger'` (default) waits for the operator's trigger; `'continuous'` reads straight away. */
+    mode?: 'trigger' | 'continuous';
+}
+/** Options for `host.rfid.locate()`. */
+export interface RfidLocateOptions {
+    /** The host plays faster beeps and haptics as the tag gets closer (default true). */
+    feedback?: boolean;
+    /** Transmit power while locating (lower narrows the field when you're close). */
+    power?: number;
+}
+/** How close the hunted tag is, updated several times a second. */
+export interface RfidLocateUpdate {
+    /** The target tag last read (when hunting several), or null if none read yet. */
+    epc: string | null;
+    /** 0 (not in range) to 100 (right here), from signal strength and read rate. */
+    strength: number;
+    /** Latest signal strength in dBm, or null. */
+    rssi: number | null;
+    /** Reads of the target per second, over the last second. */
+    hitsPerSecond: number;
+    /** When it was last read, ms since epoch, or null. */
+    lastSeen: number | null;
+}
+/** A locate session from `host.rfid.locate()`. It reads continuously until `stop()`. */
+export interface RfidLocateSession {
+    onUpdate(cb: (update: RfidLocateUpdate) => void): () => void;
+    stop(): void;
+}
+/**
+ * The host's UHF RFID reader — the same reading, single-read and find abilities the host's own scanner
+ * uses, for a container to build its own scanning screens. All three run on the one reader: starting
+ * any of them ends the one before. Everything stops when the container unmounts.
+ */
+export interface AdminMobileRfid {
+    /** The reader's current state. */
+    status(): RfidReaderStatus;
+    /** Called whenever the status changes. Returns an unsubscribe function. */
+    onStatus(cb: (status: RfidReaderStatus) => void): () => void;
+    /** Keep reading tags — a stock take, an intake — de-duplicated and batched. */
+    read(opts?: RfidReadOptions): RfidReadSession;
+    /**
+     * "This step needs a tag": resolve with one tag (the strongest read in the first moment of reading),
+     * then stop. The RFID counterpart of `requestNfcTap`.
+     */
+    readOne(opts?: RfidReadOneOptions): Promise<RfidRead>;
+    /** Find one tag (or any of several, e.g. all tags on one item) by signal strength — a Geiger counter. */
+    locate(epcs: string | string[], opts?: RfidLocateOptions): RfidLocateSession;
+}
+/** Options for `host.actions.requestCameraPhoto`. */
+export interface CameraPhotoRequestOptions {
+    /** Abandon the capture (rejects with `HostCancelledError`, `by: 'app'`). */
+    signal?: AbortSignal;
+}
 /** Callback invoked for every hardware event emitted by the host. */
 export type AdminMobileEventCallback = (event: AdminMobileEvent) => void;
 /**
@@ -105,24 +281,38 @@ export interface AdminMobileHostContext {
     /** Imperative hardware actions. */
     actions: {
         /**
-         * Open the QR scanner UI and resolve with the decoded string.
-         * Throws `HostCapabilityUnavailableError` if `'qr'` is not in `capabilities`.
-         * Throws `HostTimeoutError` if the user dismisses without scanning.
+         * Open the host's camera scanner and resolve with the decoded QR / barcode text. A deliberate
+         * action: the scanner covers the screen (or `heightPercent` of it) until a code is read.
+         * Rejects with `HostCancelledError` when the user closes the scanner (`by: 'user'`) or `signal`
+         * aborts (`by: 'app'`); `HostCapabilityUnavailableError` / `HostPermissionDeniedError` when there's
+         * no camera or no permission.
          */
-        requestQrScan: () => Promise<string>;
+        requestQrScan: (opts?: QrScanRequestOptions) => Promise<string>;
         /**
-         * Await the next NFC tap and resolve with uid + optional NDEF payload.
-         * @param timeoutMs - Milliseconds before `HostTimeoutError` is thrown (host default if omitted).
+         * "This step needs a tag": wait for the NEXT NFC tap and resolve with its uid + NDEF.
+         *
+         * Two ways to use NFC — pick per screen:
+         *  - Passive: `host.events` `nfc-tap` fires for every tap, whenever. For "tap anything, any time".
+         *  - Active (this): the next tap goes to this request and is NOT also sent as an `nfc-tap` event, so
+         *    nothing handles it twice. The host shows a small non-blocking hint (with Cancel) while waiting;
+         *    the screen stays usable — abort with `signal` if the user takes another route.
+         * Only a tap made AFTER the call counts. One request at a time: a new one cancels the previous
+         * (`HostCancelledError`, `by: 'app'`).
+         * Rejects with `HostTimeoutError` after `timeoutMs`, `HostCancelledError` on Cancel (`by: 'user'`)
+         * or abort (`by: 'app'`), `HostCapabilityUnavailableError` without NFC.
+         *
+         * A bare number is accepted as `{ timeoutMs }` (the earlier signature).
          */
-        requestNfcTap: (timeoutMs?: number) => Promise<{
+        requestNfcTap: (opts?: NfcTapRequestOptions | number) => Promise<{
             uid: string;
             ndef?: string;
         }>;
         /**
-         * Open the camera shutter once and resolve with the captured `Blob`.
-         * Throws `HostCapabilityUnavailableError` if `'camera'` is not in `capabilities`.
+         * Open the camera once and resolve with the photo as a `Blob`.
+         * Rejects with `HostCancelledError` when the user backs out or `signal` aborts;
+         * `HostCapabilityUnavailableError` / `HostPermissionDeniedError` without a camera or permission.
          */
-        requestCameraPhoto: () => Promise<Blob>;
+        requestCameraPhoto: (opts?: CameraPhotoRequestOptions) => Promise<Blob>;
         /**
          * Trigger the native share sheet.
          * Falls back to clipboard write on hosts that do not implement the Web Share API.
@@ -166,6 +356,13 @@ export interface AdminMobileHostContext {
          */
         navigateBack?: () => void;
     };
+    /**
+     * The UHF RFID reader. Present only on hosts with one (`hardware.rfid`); feature-detect:
+     * @example
+     *   const session = host.rfid?.read({ filter: { prefix: '3034' } });
+     *   session?.onRead((reads) => addToCount(reads));
+     */
+    rfid?: AdminMobileRfid;
     /** Network connectivity helpers. */
     network: {
         /** Returns whether the device currently has network access. */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.43  |  Generated: 2026-10-06T15:37:31.849Z
+Version: 2.0.45  |  Generated: 2026-10-06T17:22:34.344Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/mobile-admin-container.md

@@ -86,11 +86,11 @@ interface AdminMobileHostContext {
   // Unified hardware event stream — callback type: AdminMobileEventCallback
   events: { subscribe: (cb: AdminMobileEventCallback) => () => void }
 
-  // Promise-based hardware actions — reject with a structured error when unavailable
+  // Promise-based hardware actions — reject with a structured error when unavailable or cancelled
   actions: {
-    requestQrScan: () => Promise<string>
-    requestNfcTap: (timeoutMs?: number) => Promise<{ uid: string; ndef?: string }>
-    requestCameraPhoto: () => Promise<Blob>
+    requestQrScan: (opts?: { signal?: AbortSignal; heightPercent?: number; prompt?: string }) => Promise<string>
+    requestNfcTap: (opts?: { timeoutMs?: number; signal?: AbortSignal; prompt?: string } | number) => Promise<{ uid: string; ndef?: string }>
+    requestCameraPhoto: (opts?: { signal?: AbortSignal }) => Promise<Blob>
     share: (payload: { title: string; url: string; text?: string }) => Promise<void>
     clipboard: {
       read: () => Promise<string>
@@ -106,6 +106,9 @@ interface AdminMobileHostContext {
     navigateBack?: () => void
   }
 
+  // UHF RFID reader — only on hosts with one (feature-detect). See "RFID" below.
+  rfid?: AdminMobileRfid
+
   // Network & device info
   network: { isOnline: () => boolean }
   device: { info: () => Promise<{ model: string; platform: string }> }
@@ -331,6 +334,92 @@ The SmartLinks Mobile launcher loads your `mobileAdmin` bundle through the platf
 
 ---
 
+## Scanning: listening vs asking
+
+Every scan reaches a container in one of two ways. Pick per screen.
+
+| | Listening — `host.events` | Asking — `host.actions.request*` |
+|---|---|---|
+| Use for | "Tap or scan anything, any time" — a stock take, a scan-to-open list | "This step needs a scan" — tag this item, scan the shelf code |
+| What the user sees | Nothing changes | NFC: a small non-blocking hint with Cancel. QR / photo: the host's camera opens |
+| What you get | An event per tap / read / key | A promise for one result |
+
+### NFC: two modes
+
+- **Listening** — subscribe to `nfc-tap`. Fires for every tap while no request is waiting.
+- **Asking** — `await host.actions.requestNfcTap({ prompt: 'Tap the bottle tag', signal })`. The next tap
+  **made after the call** resolves it, and that tap is **not** also sent as an `nfc-tap` event, so
+  nothing handles it twice. The request is non-blocking: the screen stays usable while it waits — show
+  your own "or type the code" path and abort the wait with `signal` if the user takes it. One request at
+  a time: a new call cancels the previous one.
+
+```typescript
+const controller = new AbortController()
+try {
+  const { uid } = await host.actions.requestNfcTap({ prompt: 'Tap the bottle tag', signal: controller.signal })
+  await attachTag(uid)
+} catch (err) {
+  if (err instanceof HostCancelledError) return   // they pressed Cancel, or we aborted
+  throw err
+}
+// elsewhere — the user typed the code instead:
+controller.abort()
+```
+
+### QR and photos
+
+`requestQrScan()` opens the host's camera scanner (full screen, or the bottom `heightPercent` of it) and
+resolves with the code; `requestCameraPhoto()` opens the camera and resolves with the image. Both reject
+with `HostCancelledError` when the user backs out.
+
+### RFID
+
+`host.rfid` gives a container the same reader abilities the host's own scanner uses — so an app can be
+its own scanner. It's present only when the device has a UHF reader (`hardware.rfid`); check for it.
+There's one reader, so starting any of the three below ends the one before, and everything stops when
+the container unmounts.
+
+**Keep reading** — a stock take, an intake. De-duplicated and batched, so you get each tag once instead
+of hundreds of raw reads a second:
+
+```typescript
+const session = host.rfid?.read({
+  filter: { prefix: '3034' },  // optional: only EPCs starting with this (or { epcs: [...] })
+  dedupe: 'session',           // default — each tag once; { windowMs: 5000 } or 'none' for every read
+  batchMs: 250,                // default — reads arrive in batches; 0 = one at a time
+  mode: 'trigger',             // default — reads while the operator holds the trigger; 'continuous' = now until stop()
+})
+const off = session?.onRead((reads) => {        // [{ epc, tid?, rssi?, timestamp, count }]
+  for (const r of reads) addToCount(r.epc)
+})
+// later
+session?.stop()
+```
+
+**One tag for this step** — tag an item. Resolves with the strongest tag read in the first moment of
+reading, then stops; the RFID counterpart of `requestNfcTap` (non-blocking, abortable, `prompt` hint):
+
+```typescript
+const { epc } = await host.rfid.readOne({ prompt: 'Pull the trigger over the item', signal })
+```
+
+**Find a tag** — a Geiger counter. `strength` runs 0 (not in range) to 100 (right here); by default the
+host plays faster beeps and haptics as you close in (`feedback: false` to do your own):
+
+```typescript
+const hunt = host.rfid?.locate(item.epcs)   // one EPC, or every tag on the item
+hunt?.onUpdate(({ strength, rssi, hitsPerSecond }) => setStrength(strength))
+// hunt.stop() when found
+```
+
+`status()` / `onStatus(cb)` report whether a reader is available and connected, which one (`built-in`,
+`zebra`, `tsl`), whether it's reading, and its power range; `read`/`locate` take a `power` level for the
+session.
+
+Raw reads still arrive as `rfid-burst` events whenever the reader runs, for containers that want them.
+
+---
+
 ## Event Stream
 
 For raw scan events (rather than the action-driven `host.actions.requestNfcTap`), subscribe to the unified event stream. Events flow identically on every host — the launcher normalises bridge messages, Capacitor callbacks, and Web API events into the same shape.
@@ -350,6 +439,13 @@ useEffect(() => {
 }, [host.events])
 ```
 
+Event details:
+
+- Every event may carry `timestamp` (ms since epoch).
+- `nfc-tap` — `uid` is uppercase hex without separators (`04A1B2C3D4E5F6`); `ndef` is the tag's NDEF text (usually its URL), `""` when it had none.
+- `rfid-burst` — reads arrive as they happen, typically **one EPC per event, many per second** while the trigger is held. Collect and de-duplicate them yourself. `rssi` (dBm; closer = higher) when the reader reports it.
+- `key-press` — hosts that report both edges send `action: 'down'` then `'up'` for one press; act on `'down'` (or on events without `action`). `293` is the scan trigger.
+
 Lifecycle events (`event.type === 'lifecycle'`) carry a `phase` field: `'pause' | 'resume' | 'offline' | 'online'`. Use these instead of `window` event listeners so your container works identically on all hosts.
 
 ---
@@ -372,8 +468,15 @@ class HostTimeoutError extends Error {
   capability: 'nfc' | 'qr'
   timeoutMs: number
 }
+
+class HostCancelledError extends Error {
+  capability: 'nfc' | 'qr' | 'camera'
+  by: 'user' | 'app'   // closed the scanner / pressed Cancel, or aborted by the container
+}
 ```
 
+All four are exported from `@proveanything/smartlinks`; check with `instanceof` or `err.name`.
+
 ```typescript
 try {
   const code = await host.actions.requestQrScan()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.43",
+  "version": "2.0.45",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",