@proveanything/smartlinks 1.14.12 → 1.14.13

package/docs/portal-request-action.md

@@ -1,450 +1,289 @@
-Skip to main content
+# Requesting Built-in Portal Actions
 
-Core Portal Framework [r4.7]
+`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
 
-Code
+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)
 
-Code
+```tsx
+import { usePortalActions } from '@proveanything/portal-framework';
 
-19 May at 09:05
-Okay, I have a question for you. I have ended up with a real mess of confusions about logins, and part of that is because not everyone is implementing the login UI in the same way. What I've got is a situation. I've built out the login auth UI toolset, and it's great that I can use it in different apps. Like we have different apps. We have an app, a mobile app, we have a, a, a Hub app, et cetera, ...
+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', ...]
+```
 
-Thought for 29s
-Yes — that's very sensible, and it's actually the cleanest way out of the mess. Let me reflect back what you're describing and flag the design decisions, then we can build it.
+Combine with `BUILTIN_ACTION_META` (also exported) for labels/icons in
+your action pickers.
 
-The core idea
-Sub-apps stop owning auth UI. They only ever declare intent:
+---
 
-"I need the user to be authenticated to continue."
+## Iframe Apps (Cross-Origin)
 
-The portal owns the entire flow: open modal → run AuthKit → persist session → broadcast back down → restore the sub-app exactly where it was. The sub-app just re-renders and sees isAuthenticated: true.
+```ts
+const requestId = crypto.randomUUID();
 
-This is the right call. The current model (every app importing smartlinks-auth-ui and calling login() itself) is exactly what causes the duplicate-React-context / desync bugs we already have a memory about.
+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);
 
-Proposed contract
-One new message from sub-apps:
+  const { status, value, error } = d.payload;
+  // …handle result
+});
 
 window.parent.postMessage({
   _smartlinksIframeMessage: true,
-  type: 'smartlinks:authkit:request-login',
+  type: 'smartlinks:action:request',
   payload: {
-    reason?: 'bid' | 'claim' | string,  // optional, for analytics/copy
-    mode?: 'login' | 'signup' | 'either', // default 'either'
-    requireAuthenticated?: boolean,       // if already logged in, resolve immediately
-    requestId: string,                    // so we can reply
+    requestId,
+    actionId: '__copyLink',
+    params: { url: window.location.href },
   },
 }, '*');
-One reply back:
-
-{ type: 'smartlinks:authkit:login-result',
-  payload: { requestId, status: 'success' | 'cancelled' | 'error', user?, token? } }
-For container/widget apps (same React tree), expose the same thing as a hook so they don't need postMessage:
-
-const { requestLogin } = useSafeAuth();
-const result = await requestLogin({ reason: 'bid' });
-if (result.status === 'success') { /* place bid */ }
-State restoration — the important part
-You're right that this is what makes or breaks the UX. Options, in increasing order of robustness:
-
-Do nothing special — AuthKit flows that stay in-page (modal email/password, in-modal OTP) just work; the sub-app never unmounted, its URL/state is intact.
-For redirect flows (magic link, WhatsApp deep-link, OAuth bounce) — portal snapshots the full URL (including the sub-app's hash/query) into sessionStorage keyed by requestId before redirecting, and restores it on return. The sub-app gets remounted at the exact same deep-link.
-Resume callback — after restoration, portal re-posts the original request-login requestId to the sub-app as login-result: success so it can resume its specific action (e.g. auto-submit the bid the user was about to place).
-I'd build all three; they're additive.
-
-Config flexibility you mentioned
-Per-collection (in layout config) or per-request:
+```
 
-allowSignup: boolean — hide the "create account" tab
-signupProminence: 'primary' | 'secondary' | 'hidden' (we already have this type)
-methods?: ('email'|'phone'|'oauth')[] — restrict
-Copy override per reason (e.g. "Sign in to place a bid")
-What we'd remove / deprecate
-The current pattern where sub-apps import smartlinks-auth-ui and call login() themselves becomes the exception, only for genuinely custom auth (your bidder API example). Standard "I just need a logged-in user" goes through requestLogin.
-The smartlinks:authkit:login / :logout broadcast messages stay (for the custom-flow case), but most apps stop using them.
-Open questions before I build
-Scope — implement on portal-framework side (modal + message handler + hook) and document the contract for sub-apps? Or do you also want me to update the two problem apps (auction, claim) in this repo? (I don't think they live here, but confirming.)
-Redirect-flow state restoration — do any of your AuthKit methods currently redirect away from the page? (Magic link click-through, OAuth.) If yes, I'll wire the sessionStorage snapshot/restore. If everything is in-modal today, I'll stub it and we add it when needed.
-requestLogin for container/widget apps — add it to useSafeAuth() return value, or a separate hook useRequestLogin()? I lean toward folding into useSafeAuth so there's one entry point.
-If you confirm those three, I'll implement it.
+### Capabilities probe
 
-19 May at 09:09
-Um, yes, we have to implement the portal side framework here, right? And, um... Yes, 100% the redirect session flow is, is part of the problem. And don't forget, the auth kit should handle quite a lot of that anyway, right? Um, so for example, a WhatsApp flow or a session flow, like you-- the, the login auth kit currently that you use should handle such things like the way you currently have it, r ...
+```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).
 
-Thought for 4s
-Centralized auth modal flow
-Done.
+---
 
-What's shipped:
+## 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.
 
-useSafeAuth().requestLogin(opts?) — single entry point for container/widget apps. Returns { status, user?, token? }.
-smartlinks:authkit:request-login postMessage with matching smartlinks:authkit:login-result reply (carrying requestId) for iframe apps.
-Portal owns the modal (still the same AuthModal → SmartlinksAuthUI, so all your existing AuthKit redirect handling — WhatsApp, OAuth, magic link — works unchanged).
-Header login button now goes through the same requestLogin path, so there's one code path for everything.
-Already-authenticated callers resolve immediately without showing the modal.
-Docs updated in packages/portal-framework/docs/authentication.md with the new recommended pattern and the legacy "publish your own session" pattern explicitly flagged as the exception.
-Sub-app authors can now delete their bundled auth UI entirely; the auction/claim apps just await auth.requestLogin({ reason: 'bid' }).
+---
 
-19 May at 09:26
-Okay, so we need to document this. Um, we need to document it in the Smart Links SDK and, um, if you think there needs to be any additional document in the core workspace memory, let me know. Um, but basically, can you give me a-- If you can find the right documents, can you give me a new and updated version of any documents in the Smart Links SDK that'll help describe this?
+## 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.
 
-Thought for 4s
-Added portal-request-login doc
-Two SDK docs are ready to drop into node_modules/@proveanything/smartlinks/docs/:
+---
 
-sdk-doc-additions/portal-request-login.md (new — the canonical guide) — Documents the requestLogin contract: container/widget hook (useSafeAuth().requestLogin), iframe postMessage request/reply (smartlinks:authkit:request-login / smartlinks:authkit:login-result), options, result statuses (success / already-authenticated / cancelled / unavailable), redirect-bounce behavior, and anti-patterns.
-sdk-doc-additions/portal-auth-broadcast.md (updated) — Now opens with a pointer to portal-request-login.md and is explicitly scoped to the custom-auth case (sub-app runs its own flow and publishes the resulting session). The login/logout postMessage payloads are unchanged.
-When you copy them into the SDK, also add two rows to API_SUMMARY.md under an "AuthKit / Portal Bridge" section (it doesn't exist yet):
+## Result shape
 
-Doc	Purpose
-portal-request-login.md	Sub-app asks the portal to log the user in (recommended)
-portal-auth-broadcast.md	Sub-app publishes a session from its own custom auth flow
-Workspace memory: I don't think a new memory is needed. The existing index already has entries for the auth singleton, safe-bridge pattern, and admin-proxy sync. The requestLogin contract is a sub-app authoring pattern that lives naturally in the SDK docs above — it's not a recurring constraint the agent has to remember to avoid violating. If you want, I can add a one-line core rule like "Sub-apps must use requestLogin for standard auth; never render their own SmartlinksAuthUI modal" — say the word and I'll add it.
+```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
+};
+```
 
-19 May at 09:27
-And actually, I want to add to this. Is there any other things we should do? So for example, one of the apps I have is an app called Linktree, um, sorry, Linkpage. And the Linkpage often like links to other actions in the system. And one of the things it can do is has, it has essentially these ability to link to other pages as well as built-in apps as well as external things. And I wonder if we sh ...
+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.
 
+---
 
-Thought for 4s
-Read
-builtin-actions.ts
-Yes — this is a very natural extension and worth doing. The plumbing already exists; you'd just be exposing it through a programmatic channel instead of only navigation zones.
+## Scanner actions in detail
 
-What's already there
-packages/portal-framework/src/orchestrator/builtin-actions.ts already defines a closed set of reserved action IDs that the framework owns and renders consistently:
+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.
 
-__language     __qrScanner     __barcodeScanner   __nfcScanner
-__refresh      __share         __account          __profile          __settings
-Today these are placed by config into headers/side menus/tabs. They are not callable from inside an app. Linkpage currently can only navigate (via LinkTarget) — it can't say "open the QR scanner" or "log out".
+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.
 
-Proposed addition — requestAction
-Mirror exactly what we just did for login. One verb, one contract, two transports.
+```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
+}
+```
 
-Container/widget hook (folded into useSafeAuth's sibling on the portal context):
+```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
+```
 
-const portal = usePortalActions();
-const result = await portal.requestAction('__qrScanner', { /* params */ });
-// result: { status: 'completed' | 'cancelled' | 'unavailable' | 'error',
-//           value?: unknown, error?: string, requestId?: string }
-Iframe postMessage:
+```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: {} },
-}, '*');
-// reply: { type: 'smartlinks:action:result',
-//          payload: { requestId, status, value?, error? } }
-Standard return shapes per action — published in the SDK doc so Linkpage and others know what to expect:
-
-Action	value on completed
-__qrScanner / __barcodeScanner	{ text, format, resolved?: { collectionId, productId?, proofId? } }
-__nfcScanner	{ serial, payload? }
-__share	{ method: 'native' | 'clipboard' }
-__language	{ language }
-__account (login) / __profile / __settings	{ user? }
-__refresh	{}
-__logout (new)	{}
-__takePhoto (proposed)	{ dataUrl } or { assetId }
-Why this is the right shape
-It's the same primitive. requestLogin becomes literally requestAction('__account', { mode }) under the hood — you keep the dedicated requestLogin as a typed convenience and document it as such.
-One layout-builder source of truth. BUILTIN_ACTION_META already drives the Linkpage-style picker. The same enum becomes the dropdown in any "pick an action" UI.
-Capability negotiation comes free. getAvailableActions() (and a capabilities field in the iframe context sync) lets Linkpage hide "NFC scan" on iOS web, "take photo" without a camera, "logout" when not logged in, etc. — much cleaner than every app re-detecting.
-Mobile shell maps onto the same enum. When the Capacitor host wants to override __qrScanner with the native camera, it registers the same action ID — sub-apps don't change.
-What I'd add to the set
-Genuinely missing today:
-
-__logout — symmetric with login, currently no clean way to trigger.
-__takePhoto — distinct from QR scan; returns image/asset.
-__pickAsset — opens the same AssetPicker the admin UI uses (useful for any "let the user pick a saved image" flow).
-__copyLink — distinct from __share; deterministic clipboard with toast.
-__navigate — wraps SL.navigation.resolveLink(linkTarget).navigate(); lets iframes use the portal's link resolver without re-implementing it.
-I'd not add: file download, generic toast, dialog. Those are app concerns, not portal capabilities.
-
-What to be careful about
-Keep the surface closed. Only __-prefixed IDs the framework ships. Don't let apps register their own — that's what apps and LinkTarget's 'app' / 'deep' kinds are for. The action registry is for host capabilities.
-Permissioning. __logout from a random iframe should probably require user confirmation; __settings exposing account deletion definitely should. Decide per-action whether the portal prompts.
-Linkpage UX vs programmatic. Linkpage's links should resolve through the same requestAction path so a link configured as "open QR scanner" behaves identically to a programmatic call. Don't fork two execution paths.
-Don't replace LinkTarget. LinkTarget stays the persisted shape (it's what's saved in config). requestAction is the runtime API. Linkpage stores a LinkTarget of a new kind: { kind: 'action'; actionId; params? } — and the resolver dispatches that to requestAction.
-Recommendation
-Build it in two phases:
-
-Phase 1 — programmatic API + iframe contract + LinkTarget 'action' kind. Wire requestAction to the existing built-in actions (no new actions yet). Update Linkpage to use it.
-Phase 2 — add __logout, __takePhoto, __pickAsset, __copyLink, __navigate. Document return shapes in the SDK.
-Want me to write up a plan for Phase 1, or go straight to implementing it?
-
-19 May at 09:46
-Um, great. Let's go and add these. This is great
-
-
-Thought for 7s
-Added sync actions & doc
-Add requestAction core API
-Add new built-in actions
-Extend LinkTarget with action kind
-Document requestAction in SDK docs
-Shipped the requestAction contract end-to-end:
-
-ActionRequestProvider (packages/portal-framework/src/orchestrator/ActionRequestProvider.tsx) — usePortalActions().requestAction(actionId, params) + iframe postMessage bridge (smartlinks:action:request / :result) + capabilities probe (smartlinks:action:capabilities).
-Synchronous built-ins executed inline: __refresh, __share, __copyLink, __navigate, __login, __logout, __account (adaptive). Overlay built-ins (__qrScanner, __profile, etc.) dispatch through SiteInjectionContext.triggerAction and resolve triggered for now.
-BUILTIN_ACTION_META extended with LOGIN, LOGOUT, COPY_LINK, NAVIGATE entries so Linkpage-style pickers list them automatically.
-Mounted inside SiteInjectionProvider in both OrchestratedPortal branches, exported from the framework root.
-portal-request-action.md — full SDK doc covering hook + iframe contract, capability discovery, the LinkTarget 'action' kind, and anti-patterns.
-Returning values from overlay actions (e.g. QR text back to the caller) is the natural next pass — the envelope already supports value; only the overlay components need a resolve() callback wired in.
-
-19 May at 11:37
-Okay, so can you take a step back for a second? 'Cause I'm getting confused about all the docs. So I now have four different docs that all say SDK doc additions. Can you tell me which ones I actually still need? Which ones are already in the SDK? Which ones have been supplemented? Can we delete the ones we no longer need, look at the SDK and check everything's right, and give me a single summary o ...
-
-
-Thought for 3s
-Used 5 tools
-
-Here's the audit:
-
-What's where
-File in sdk-doc-additions/	In installed SDK?	Status
-portal-auth-broadcast.md (158 lines)	Yes, older 136-line version	Supersedes — our copy adds the pointer to requestLogin and reframes this as the custom-auth-only path
-portal-back-button.md (187 lines)	Yes, older 95-line version	Supersedes — our copy is the expanded version from the earlier back-button work
-portal-request-login.md (240 lines)	No	New — missing from SDK
-portal-request-action.md (194 lines)	No	New — missing from SDK
-API_SUMMARY.md in the SDK has no "AuthKit / Portal Bridge" section yet — none of the four docs are linked from it.
-
-Recommendation
-Keep all four. None are redundant — the two that exist in the SDK are stale versions that need replacing, and the other two are net-new. Deleting any of them would lose content the SDK doesn't have yet.
-
-What's actually missing from the SDK right now
-Replace docs/portal-auth-broadcast.md with our 158-line revision (adds the "read requestLogin first" pointer and scopes this doc to custom-auth flows only).
-Replace docs/portal-back-button.md with our 187-line revision.
-Add docs/portal-request-login.md (canonical login contract).
-Add docs/portal-request-action.md (general-purpose built-in actions contract).
-Add to API_SUMMARY.md a new "AuthKit / Portal Bridge" section with rows for all four docs (currently no entries point to any of them).
-Want me to also verify our portal-back-button.md revision against the implementation in OrchestratedPortal / useNavigationState, or leave it as-is?
-
-Security
-2
-Errors (outdated)
-Code
-Ask Lovable...
-
-
-Add files
-Drop any files here to add them to your message
-
-Search code
-.github/workflows
-sync-package-lock.yml
-.lovable
-plan.md
-deploy/portal
-server
-cloudbuild.yaml
-Dockerfile
-nginx.conf
-package.json
-README.md
-tsconfig.server.json
-vite.portal.config.ts
-packages/portal-framework
-docs
-sdk-doc-additions
-portal-auth-broadcast.md
-portal-back-button.md
-portal-request-action.md
-portal-request-login.md
-ai-assistant.md
-ai-content-extraction.md
-architecture.md
-authentication.md
-cross-app-communication.md
-direct-component-rendering.md
-embed-mode.md
-routing.md
-site-injection.md
-src
-GETTING_STARTED.md
-package.json
-README.md
-rollup.config.js
-tsconfig.build.json
-tsconfig.json
-public
-app.admin.json
-app.manifest.json
-robots.txt
-scripts
-check-lockfile-sync.mjs
-src
-components
-docs
-hooks
-i18n
-integrations/supabase
-lib
-pages
-types
-utils
-widgets
-App.css
-App.tsx
-index.css
-main.tsx
-platform.ts
-preview-main.tsx
-PreviewApp.tsx
-vite-env.d.ts
-supabase
-config.toml
-.dockerignore
-.env
-.env.example
-.gitignore
-bun.lock
-components.json
-eslint.config.js
-index.html
-package.json
-postcss.config.js
-preview.html
-tailwind.config.ts
-tsconfig.app.json
-tsconfig.json
-tsconfig.node.json
-vite.config.ts
-vite.config.widget.ts
-packages/portal-framework/docs/sdk-doc-additions/portal-auth-broadcast.md
-packages/portal-framework/docs/sdk-doc-additions/portal-back-button.md
-packages/portal-framework/docs/sdk-doc-additions/portal-request-login.md
-packages/portal-framework/docs/sdk-doc-additions/portal-request-action.md
-1
-2
-3
-4
-5
-6
-7
-8
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
-29
-30
-31
-32
-33
-34
-35
-36
-37
-38
-39
-40
-41
-42
-43
-44
-45
-46
-47
-48
-49
-50
-51
-52
-53
-54
-55
-56
-57
-58
-59
-60
-61
-62
-63
-# Requesting Built-in Portal Actions
-
-> **Where to put this file:** copy into the SmartLinks SDK at
-> `node_modules/@proveanything/smartlinks/docs/portal-request-action.md`
-> and add a row to `API_SUMMARY.md`'s "AuthKit / Portal Bridge" section.
-
-`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.
+  payload: {
+    requestId,
+    actionId: '__qrScanner',
+    params: { suppressNavigation: true },
+  },
+}, '*')
+```
 
-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.
+### Scan value types
 
----
+```ts
+type QrScanResult = {
+  text: string
+  format: string                           // 'QR_CODE', 'EAN_13', etc.
+  resolved?: {
+    collectionId: string
+    productId?: string
+    proofId?: string
+  }
+}
 
-## Why this exists
+type BarcodeScanResult = {
+  text: string
+  format: string
+}
 
-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.
+type NfcScanResult = {
+  serial: string
+  payload?: string
+}
+```
 
 ---
 
-## Container / Widget Apps (Same React Tree)
+## Relationship to `LinkTarget`
 
-```tsx
-import { usePortalActions } from '@proveanything/portal-framework';
+Linkpage-style UIs persist a `LinkTarget` of kind `'action'`:
 
-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>;
-}
+```ts
+type ActionLinkTarget = {
+  kind: 'action';
+  actionId: string;
+  params?: Record<string, unknown>;
+};
 ```
 
-`usePortalActions()` returns `null` when no `ActionRequestProvider` is
-mounted upstream — treat that the same as `status: 'unavailable'`.
-
-### Discovering available actions
+At runtime, resolve it through the portal:
 
 ```ts
-const ids = portal?.getAvailableActions() ?? [];
-// → ['__refresh','__share','__copyLink','__navigate','__login','__logout',
-//    '__account','__qrScanner','__barcodeScanner','__nfcScanner', ...]
+await portal?.requestAction(target.actionId, target.params);
 ```
 
-Combine with `BUILTIN_ACTION_META` (also exported) for labels/icons in
-your action pickers.
+Never persist a resolved URL when an action is intended — the action
+contract may change platform-side, the persisted ID won't.
 
 ---
 
-## Iframe Apps (Cross-Origin)
+## 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.