@proveanything/smartlinks 1.14.11 → 1.14.13

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.14.11  |  Generated: 2026-05-19T10:35:51.071Z
+Version: 1.14.13  |  Generated: 2026-05-19T11:49:34.090Z
 
 This is a concise summary of all available API functions and types.
 
@@ -36,6 +36,11 @@ For detailed guides on specific features:
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
 - **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
 - **[Auth Kit](auth-kit.md)** - End-user authentication flows (email/password, magic link, OTP, OAuth) for microapps
+- **[Portal Request Login](portal-request-login.md)** - Sub-apps delegate user authentication to the portal; `useSafeAuth().requestLogin` hook and iframe postMessage contract, redirect-bounce handling
+- **[Portal Auth Broadcast](portal-auth-broadcast.md)** - Publishing a custom-flow session to the portal so the header, sibling apps, and SDK all stay in sync
+- **[Portal Request Action](portal-request-action.md)** - Invoking portal built-in actions (`__qrScanner`, `__share`, `__logout`, etc.) from containers, widgets, and iframes
+- **[Portal Back Button](portal-back-button.md)** - `parentPath` contract for hierarchy-aware "up" navigation; `useDeepLinkSync` integration
+- **[Contact Search](contact-search.md)** - Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
 - **[Forms](forms.md)** - Platform-managed form definitions, submissions, and schema-driven React form UI
 - **[App Objects: Cases, Threads & Records](app-objects.md)** - Generic app-scoped building blocks for support cases, discussions, bookings, registrations, and more
@@ -89,7 +94,7 @@ The Smartlinks SDK is organized into the following namespaces:
 — Identity & Access —
 - **auth** - Admin authentication and account ops: login/logout, tokens, account info.
 - **authKit** - End‑user auth flows (email/password, OAuth, phone); profiles and verification.
-- **contact** - Manage customer contacts; CRUD, lookup, upsert, erase.
+- **contact** - Manage customer contacts; CRUD, lookup, upsert, erase, and admin search. → [Guide](contact-search.md)
 
 — Messaging & Audience —
 - **comms** - Send notifications (push, email, wallet); templating, severity, delivery status. → [Guide](comms.md)

package/dist/docs/overview.md

@@ -65,6 +65,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
+| **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
 | **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
@@ -74,7 +75,9 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
 | **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
 | **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
+| **Portal Request Login** | `docs/portal-request-login.md` | How sub-apps ask the portal to authenticate the user; hook and iframe postMessage contracts |
 | **Portal Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
+| **Contact Search** | `docs/contact-search.md` | Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination |
 | **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 

package/dist/docs/portal-auth-broadcast.md

@@ -1,6 +1,12 @@
 # Publishing Auth State to the Portal
 
-> **For sub-app authors.** This guide explains how to broadcast authentication state changes to the portal so the header, account UI, and sibling apps stay in sync.
+> **⚠️ Read [`portal-request-login.md`](./portal-request-login.md) first.**
+> The recommended pattern for "I need a logged-in user before I continue"
+> is `requestLogin` — the sub-app asks the portal to run its standard
+> AuthKit flow and awaits a result. This doc covers the *other* case:
+> a sub-app that runs its **own** authentication flow and needs to
+> publish the resulting session up to the portal so the header, account
+> UI, and sibling apps stay in sync.
 
 A SmartLinks micro-app may need to run its own custom authentication flow —
 typical cases: an auction app that calls a bidder API, a competition app
@@ -11,6 +17,7 @@ app pick up the new session.
 
 This doc describes the contract the portal framework already implements.
 
+
 ---
 
 ## Container / Widget Apps (Same React Tree)
@@ -52,18 +59,28 @@ function BidButton() {
 
 ## Iframe Apps (Cross-Origin)
 
-Iframe apps don't share React context. Post messages directly from the
-iframe to its parent — the portal's `IframeResponder` listens for these:
+Iframe apps don't share React context with the portal. They publish their
+session by posting framework-recognised messages on `window.parent`. The
+portal's `IframeResponder` listens for these and routes them into the same
+`login` / `logout` calls the built-in `AuthModal` makes.
+
+> **Note:** There is no `authKit.publishLogin` / `publishLogout` helper in
+> the SmartLinks SDK today. Use the raw `postMessage` calls below. If a
+> helper ships later it will wrap exactly these payloads.
 
 ```ts
-// LOGIN
+// LOGIN — after your custom auth flow returns a token + user
 window.parent.postMessage({
   _smartlinksIframeMessage: true,
   type: 'smartlinks:authkit:login',
   payload: {
     token: '<bearer>',
-    user: { uid: 'usr_123', email: 'bidder@example.com', displayName: 'Jane' },
-    accountData: { /* optional */ },
+    user: {
+      uid: 'usr_123',
+      email: 'bidder@example.com',
+      displayName: 'Jane Bidder',
+    },
+    accountData: { tier: 'gold' }, // optional, free-form
   },
 }, '*');
 
@@ -114,8 +131,9 @@ through the standard portal UI.
    wiped.
 
 ❌ Implementing logout by just clearing your own state. Always call
-   `useAuth().logout()` (container/widget) or post `smartlinks:authkit:logout`
-   (iframe) so the whole portal session ends cleanly.
+   `useAuth().logout()` (container/widget) or post the
+   `smartlinks:authkit:logout` message (iframe) so the whole portal
+   session ends cleanly.
 
 ---
 

package/dist/docs/portal-back-button.md

@@ -1,20 +1,36 @@
-# Portal Back Button
+# Portal Back Button — "Up" Navigation Inside Sub-Apps
 
-> **For sub-app authors.** This guide explains how to make the portal's top back button behave like hierarchy-aware "up" navigation inside an embedded app.
+> **For sub-app authors.** Drop this file into the SmartLinks SDK docs (e.g.
+> `docs/portal-back-button.md`) and link it from `routing.md` / `mpa.md` so
+> microapp authors discover it.
 
-When a SmartLinks app is embedded inside the portal shell, the shell can render a top-level back button. By default that button exits the app entirely. That is correct for flat screens, but wrong for apps with internal hierarchy such as lists, detail pages, wizards, or nested checkout flows.
+When a sub-app is embedded by a portal shell, the shell renders a top-level
+back button. By default that button **exits the app entirely** when tapped —
+which is wrong for any app with internal hierarchy (lists → detail, wizards,
+etc.).
 
-This document describes the contract for telling the portal where "up" goes from the current screen so the shell can keep the app mounted and route to the correct parent screen instead of leaving the embed.
+This document describes the contract for telling the portal where "up" goes
+from the current screen, so the top back button performs **hierarchy-aware
+"up" navigation** inside your app instead.
 
-## Why "up", not browser back
+---
 
-Browser back replays history. If a user navigates `list -> item A -> list -> item B`, browser back can yo-yo between detail and list screens in a way that feels wrong for an app chrome back button.
+## Why "up", not "back"
 
-"Up" navigates the content hierarchy instead: `item B -> list -> exit app`. It is single-direction and idempotent. Only your app's router knows that hierarchy, so the portal cannot infer it on its own.
+Browser back replays history. If a user navigates **list → item A → list →
+item B**, browser back yo-yos:  `B → list → A → list → ...`. That is not what
+users expect from an "up arrow" in app chrome.
 
-## The contract
+"Up" navigates the **content hierarchy**:  `B → list → exit app`. It is
+single-direction and idempotent. Only your app's router knows the hierarchy,
+so the portal can't infer it — your app must declare it.
 
-When your app posts `smartlinks-route-change` messages, include a `parentPath` field inside `state` for the current screen:
+---
+
+## The Contract
+
+With every `smartlinks-route-change` your app already posts (via
+`useDeepLinkSync` or directly), include a `parentPath` field inside `state`:
 
 ```ts
 window.parent.postMessage({
@@ -22,7 +38,8 @@ window.parent.postMessage({
   path: '/items/123',
   context: { collectionId: 'auction-2026', appId: 'auction' },
   state: {
-    parentPath: '/items',
+    parentPath: '/items',   // ← where "up" goes from /items/123
+    // ... your other app state
   },
   appId: 'auction',
 }, '*');
@@ -30,43 +47,68 @@ window.parent.postMessage({
 
 | `state.parentPath` value | Portal back-button behaviour |
 | --- | --- |
-| `'/items'` (or any string) | The portal posts `smartlinks-navigate` to the iframe with that path and keeps the app mounted. |
-| `''`, missing, or omitted | The portal falls back to the default behaviour and exits the app. |
+| `'/items'` (or any string) | Posts `smartlinks-navigate` to the iframe with that path. App stays mounted. |
+| `''` / missing / omitted   | Default: clears the active app and returns to the portal homepage. |
+
+When the portal sends the up-navigation message, your app must respond by
+navigating to that path. If you use `useDeepLinkSync` with an SDK release
+that includes the inbound `smartlinks-navigate` listener, this is automatic —
+otherwise add a listener (see "Receiving the up-message" below).
 
-The portal only uses `parentPath` when it is present on the current route. Query-string changes, tab switches, and modal state should keep the same parent path.
+---
 
-## Recommended pattern
+## Recommended sub-app pattern (React Router)
 
-Keep the hierarchy mapping close to your route definitions:
+Keep "what's above this route" co-located with your route definitions:
 
 ```ts
+// routes.ts
 const PARENTS: Record<string, (params: any) => string | null> = {
-  '/': () => null,
-  '/items': () => null,
-  '/items/:id': () => '/items',
-  '/items/:id/bid': ({ id }) => `/items/${id}`,
-  '/checkout': () => '/items',
+  '/':                () => null,           // home — back exits the app
+  '/items':           () => null,           // list — back exits the app
+  '/items/:id':       () => '/items',       // detail — back goes to list
+  '/items/:id/bid':   ({ id }) => `/items/${id}`,
+  '/checkout':        () => '/items',
 };
 
 export function getParentPath(pathname: string): string | null {
-  // Use your router's path matching here and return the parent route.
-  return null;
+  // matchPath against PARENTS keys — return parent or null
+  // (use react-router's matchPath in your real implementation)
 }
 ```
 
-Then emit `parentPath` whenever the route changes:
+```tsx
+// App.tsx
+import { useDeepLinkSync } from '@/hooks/useDeepLinkSync';
+import { getParentPath } from './routes';
+
+function App() {
+  useDeepLinkSync({
+    getParentPath: ({ pathname }) => getParentPath(pathname),
+  });
+  // ...
+}
+```
+
+If your app does not use `useDeepLinkSync`, post the message yourself:
 
 ```ts
-useDeepLinkSync({
-  getParentPath: ({ pathname }) => getParentPath(pathname),
-});
+useEffect(() => {
+  if (window.parent === window) return;
+  window.parent.postMessage({
+    type: 'smartlinks-route-change',
+    path: location.pathname,
+    context: { /* ... */ },
+    state: { parentPath: getParentPath(location.pathname) ?? '' },
+  }, '*');
+}, [location.pathname]);
 ```
 
-If you do not use `useDeepLinkSync`, post the message yourself and include `parentPath` in `state`.
+---
 
-## Receiving the up-message
+## Receiving the up-message (`smartlinks-navigate`)
 
-When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to the iframe:
+When the portal back button consumes a `parentPath`, it posts:
 
 ```ts
 {
@@ -78,18 +120,68 @@ When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to th
 }
 ```
 
-Your app should listen for that message and route accordingly. If your SDK release already includes the inbound `smartlinks-navigate` listener, this can be automatic; otherwise add a small `message` listener and call your router manually.
+Your app must listen for this and route accordingly. A minimal hook:
+
+```ts
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+
+export function useParentNavigation() {
+  const navigate = useNavigate();
+  useEffect(() => {
+    const onMessage = (e: MessageEvent) => {
+      if (e.data?.type !== 'smartlinks-navigate') return;
+      if (typeof e.data.path !== 'string') return;
+      navigate(e.data.path);
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [navigate]);
+}
+```
+
+---
+
+## Reference: Updated `RouteChangeMessage`
+
+`state` is an open `Record<string, string>` — `parentPath` is a recognised
+optional convention; everything else flows through unchanged.
+
+```ts
+interface RouteChangeMessage {
+  type: 'smartlinks-route-change';
+  path: string;
+  context: Record<string, string>;
+  state: Record<string, string> & {
+    /**
+     * Optional. The "up" target from the current screen. When present, the
+     * portal's top back button posts smartlinks-navigate with this path
+     * instead of exiting the app. Empty / missing → exits the app.
+     */
+    parentPath?: string;
+  };
+  appId?: string;
+}
+```
 
-## Reference
+No breaking change: existing apps that don't emit `parentPath` keep today's
+behaviour (one tap of the portal back exits the app).
 
-`state` remains a general `Record<string, string>`. `parentPath` is a recognised optional convention, not a breaking protocol change.
+---
 
 ## FAQ
 
-**Do I need to push every query-param change as a navigation step?** No. `parentPath` is hierarchy, not history.
+**Q: Do I need to push every query-param change as a navigation step?**
+No. `parentPath` is hierarchy, not history. A filter toggle, a tab switch,
+or a modal open on the same screen should keep the same `parentPath`.
 
-**What if my up target leaves the app?** Set `parentPath` to `''` or omit it.
+**Q: What if my "up" leaves the app?**
+Set `parentPath` to `''` (or omit it). The portal will exit the app on back.
 
-**Can I disable the portal back button on certain screens?** Not via this protocol. Use the existing `homeScope: 'entry'` portal behaviour if you need the shell back button suppressed.
+**Q: Can I disable the portal back button on certain screens?**
+Not directly via this protocol. Use the existing portal `homeScope: 'entry'`
+mechanism if you need the entire portal back button suppressed.
 
-**What about an in-app back button?** Keep it if you want. The portal back is shell chrome; an in-content back is part of the app UI.
+**Q: What about the in-app back button I already render?**
+Keep it if you want — they're not mutually exclusive. The portal back is
+chrome; an in-content back is content. Many apps will only need one.

package/dist/docs/portal-request-action.md

@@ -0,0 +1,289 @@
+# Requesting Built-in Portal Actions
+
+`requestAction` is the general-purpose sibling of
+[`requestLogin`](./portal-request-login.md). It lets a sub-app
+(container, widget, or iframe) trigger any of the portal's built-in
+capabilities — open the QR scanner, log out, copy the current link,
+navigate to another app — and await a result.
+
+Use it whenever the answer to *"what do I want?"* is one of the
+portal's standardized capabilities. The portal owns the implementation;
+your sub-app declares intent.
+
+---
+
+## Why this exists
+
+Linkpage-style apps, action grids and CTAs across the platform all need
+the same primitives: scan a QR, take a photo, copy a link, jump to
+another app, log the user out. Without a shared contract every app
+re-implemented these against direct browser APIs, fragmenting UX and
+breaking cross-iframe boundaries. `requestAction` is the contract.
+
+---
+
+## Container / Widget Apps (Same React Tree)
+
+```tsx
+import { usePortalActions } from '@proveanything/portal-framework';
+
+function ShareButton() {
+  const portal = usePortalActions();
+  async function onClick() {
+    const result = await portal?.requestAction('__share', {
+      title: 'Check this out',
+      url: window.location.href,
+    });
+    // result.status === 'success' | 'cancelled' | 'unavailable' | 'error' | 'triggered'
+  }
+  return <button onClick={onClick}>Share</button>;
+}
+```
+
+`usePortalActions()` returns `null` when no `ActionRequestProvider` is
+mounted upstream — treat that the same as `status: 'unavailable'`.
+
+### Discovering available actions
+
+```ts
+const ids = portal?.getAvailableActions() ?? [];
+// → ['__refresh','__share','__copyLink','__navigate','__login','__logout',
+//    '__account','__qrScanner','__barcodeScanner','__nfcScanner', ...]
+```
+
+Combine with `BUILTIN_ACTION_META` (also exported) for labels/icons in
+your action pickers.
+
+---
+
+## Iframe Apps (Cross-Origin)
+
+```ts
+const requestId = crypto.randomUUID();
+
+window.addEventListener('message', function handler(ev) {
+  const d = ev.data;
+  if (!d || d._smartlinksIframeMessage !== true) return;
+  if (d.type !== 'smartlinks:action:result') return;
+  if (d.payload?.requestId !== requestId) return;
+  window.removeEventListener('message', handler);
+
+  const { status, value, error } = d.payload;
+  // …handle result
+});
+
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:action:request',
+  payload: {
+    requestId,
+    actionId: '__copyLink',
+    params: { url: window.location.href },
+  },
+}, '*');
+```
+
+### Capabilities probe
+
+```ts
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:action:capabilities',
+  payload: { requestId },
+}, '*');
+// reply: type 'smartlinks:action:capabilities:result'
+//   payload: { requestId, actions: string[], meta: Record<id, {label, icon, description, available}> }
+```
+
+Use this to hide actions the host doesn't support (e.g. `__nfcScanner`
+on iOS web).
+
+---
+
+## Built-in actions
+
+| Action ID | Kind | Params | Success value |
+|---|---|---|---|
+| `__refresh` | sync | — | — |
+| `__share` | sync | `{ title?, text?, url? }` | `{ method: 'native' \| 'clipboard' }` |
+| `__copyLink` | sync | `{ text?, url? }` | `{ url }` |
+| `__navigate` | sync | `{ appId, deepLink?, deepLinkParams? }` | — |
+| `__login` | sync | `{ reason?, mode?, resolveIfAuthenticated? }` | `{ user, token }` |
+| `__logout` | sync | — | — |
+| `__account` | sync | login params | login → `{ user, token }`; logout → — |
+| `__qrScanner` | overlay | `{ suppressNavigation?: boolean }` | `{ text, format, resolved?: { collectionId, productId?, proofId? } }` |
+| `__barcodeScanner` | overlay | `{ suppressNavigation?: boolean }` | `{ text, format }` |
+| `__nfcScanner` | overlay | `{ suppressNavigation?: boolean }` | `{ serial, payload? }` (Android only) |
+| `__language` | overlay | — | — |
+| `__profile` | page | — | — |
+| `__settings` | page | — | — |
+
+> **`__login` vs `requestLogin`:** For the common case of "I just need a
+> logged-in user before continuing", prefer
+> [`requestLogin`](./portal-request-login.md) — it is a typed convenience
+> wrapper around `requestAction('__login', ...)` with a richer result
+> contract. Use `__login` / `__account` via `requestAction` only when you
+> are composing with other built-in actions in the same flow.
+
+---
+
+## App-registered actions
+
+Sub-apps may register their own action IDs via `siteInjections.actions`
+on `OrchestratedPortal`. Those IDs become callable through the same
+`requestAction` / postMessage contract as built-ins. Unlike built-ins they
+are not guaranteed to be present on every portal — always probe
+`getAvailableActions()` before using them.
+
+---
+
+## Result shape
+
+```ts
+type ActionRequestResult = {
+  status:
+    | 'success'      // action completed (sync actions may carry a value; capture overlays always do)
+    | 'cancelled'    // user dismissed the overlay without completing
+    | 'unavailable'  // unknown action or capability not present on this host
+    | 'error';       // action threw
+  value?: unknown;
+  error?: string;
+  requestId?: string; // echoed on postMessage replies
+};
+```
+
+All actions now resolve to one of these four terminal statuses. There is no
+`triggered` intermediate status — capture-mode overlays (QR, barcode, NFC)
+keep the caller's promise pending until the user completes the scan or
+dismisses the overlay.
+
+---
+
+## Scanner actions in detail
+
+QR, barcode, and NFC scanner actions open the portal's scanner overlay and
+**await user input** — the promise (or postMessage reply) is held open until
+the user either completes a scan or dismisses the overlay.
+
+By default the portal also performs its standard navigation after a
+successful scan (e.g. resolving a SmartLinks proof URL). Pass
+`suppressNavigation: true` when you want the raw value and no portal routing.
+
+```ts
+// Container / widget — get the scanned value, skip portal navigation
+const result = await portal.requestAction('__qrScanner', {
+  suppressNavigation: true,
+})
+if (result.status === 'success') {
+  const { text, format, resolved } = result.value as QrScanResult
+  // text    — raw scanned string
+  // format  — e.g. 'QR_CODE', 'EAN_13'
+  // resolved — if the text decoded to a SmartLinks URL:
+  //   { collectionId, productId?, proofId? }
+}
+if (result.status === 'cancelled') {
+  // user closed the scanner without scanning
+}
+```
+
+```ts
+// Container / widget — let the portal navigate AND get the value
+const result = await portal.requestAction('__qrScanner')
+// portal navigates to the scanned link; sub-app also gets the value
+```
+
+```ts
+// Iframe — same contract via postMessage
+const requestId = crypto.randomUUID()
+
+window.addEventListener('message', function handler(ev) {
+  const d = ev.data
+  if (!d?._smartlinksIframeMessage) return
+  if (d.type !== 'smartlinks:action:result') return
+  if (d.payload?.requestId !== requestId) return
+  window.removeEventListener('message', handler)
+
+  if (d.payload.status === 'success') {
+    const { text, format, resolved } = d.payload.value
+    // use the scan result
+  }
+})
+
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:action:request',
+  payload: {
+    requestId,
+    actionId: '__qrScanner',
+    params: { suppressNavigation: true },
+  },
+}, '*')
+```
+
+### Scan value types
+
+```ts
+type QrScanResult = {
+  text: string
+  format: string                           // 'QR_CODE', 'EAN_13', etc.
+  resolved?: {
+    collectionId: string
+    productId?: string
+    proofId?: string
+  }
+}
+
+type BarcodeScanResult = {
+  text: string
+  format: string
+}
+
+type NfcScanResult = {
+  serial: string
+  payload?: string
+}
+```
+
+---
+
+## Relationship to `LinkTarget`
+
+Linkpage-style UIs persist a `LinkTarget` of kind `'action'`:
+
+```ts
+type ActionLinkTarget = {
+  kind: 'action';
+  actionId: string;
+  params?: Record<string, unknown>;
+};
+```
+
+At runtime, resolve it through the portal:
+
+```ts
+await portal?.requestAction(target.actionId, target.params);
+```
+
+Never persist a resolved URL when an action is intended — the action
+contract may change platform-side, the persisted ID won't.
+
+---
+
+## Anti-patterns
+
+❌ Calling `navigator.share` / `clipboard.writeText` directly from a
+   sub-app when `__share` / `__copyLink` exist — you lose host-level
+   error handling and capability negotiation.
+
+❌ Re-implementing logout by clearing your own state. Always go through
+   `__logout` (or `useAuth().logout()` in-tree) so the whole portal
+   session ends cleanly.
+
+❌ Hard-coding action IDs the host might not support. Probe
+   `getAvailableActions()` or the capabilities postMessage first.
+
+❌ Reusing a single `requestId` across postMessage calls.
+
+❌ Not awaiting the result of capture-mode scanner actions. The promise
+   stays pending until the user scans or cancels — fire and forget will
+   leak the listener.