@proveanything/smartlinks 1.14.11 → 1.14.12

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

@@ -0,0 +1,450 @@
+Skip to main content
+
+Core Portal Framework [r4.7]
+
+
+
+
+Code
+
+
+
+Code
+
+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, ...
+
+
+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.
+
+The core idea
+Sub-apps stop owning auth UI. They only ever declare intent:
+
+"I need the user to be authenticated to continue."
+
+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.
+
+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.
+
+Proposed contract
+One new message from sub-apps:
+
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:request-login',
+  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
+  },
+}, '*');
+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.
+
+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 ...
+
+
+Thought for 4s
+Centralized auth modal flow
+Done.
+
+What's shipped:
+
+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?
+
+
+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):
+
+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.
+
+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 ...
+
+
+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.
+
+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:
+
+__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".
+
+Proposed addition — requestAction
+Mirror exactly what we just did for login. One verb, one contract, two transports.
+
+Container/widget hook (folded into useSafeAuth's sibling on the portal context):
+
+const portal = usePortalActions();
+const result = await portal.requestAction('__qrScanner', { /* params */ });
+// result: { status: 'completed' | 'cancelled' | 'unavailable' | 'error',
+//           value?: unknown, error?: string, requestId?: string }
+Iframe postMessage:
+
+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.
+
+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)

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

@@ -0,0 +1,236 @@
+# Requesting Login from the Portal
+
+This is the **recommended** way for a micro-app to get a logged-in user. The
+sub-app does not render any auth UI of its own — it asks the portal to run
+its standard AuthKit flow and awaits a result. The portal owns the modal,
+WhatsApp / OAuth / magic-link redirects, session persistence, and the
+header avatar swap.
+
+Use `requestLogin` whenever the answer to "what do I want?" is simply
+*"a logged-in user before I continue"*. Only fall back to
+[publishing your own session](./portal-auth-broadcast.md) when the app runs
+a genuinely custom auth flow (e.g. its own bidder API).
+
+---
+
+## Why this exists
+
+Historically every sub-app imported `@proveanything/smartlinks-auth-ui` and
+rendered its own login modal. That meant:
+
+- Two React copies of `AuthContext` could exist at once → silent session
+  desync between the header and the sub-app.
+- Each app re-implemented the same WhatsApp / OAuth / magic-link flow.
+- Redirect bounces would land back on the portal with no memory of which
+  sub-app had triggered the login.
+
+The portal now owns the entire flow. Sub-apps just declare intent.
+
+---
+
+## Container / Widget Apps (Same React Tree)
+
+These share the portal's React context. Use `useSafeAuth()` from the
+portal framework:
+
+```tsx
+import { useSafeAuth } from '@proveanything/portal-framework';
+
+function PlaceBidButton() {
+  const auth = useSafeAuth();
+
+  async function onClick() {
+    const result = await auth?.requestLogin?.({ reason: 'bid' });
+    if (result?.status === 'success' || result?.status === 'already-authenticated') {
+      // auth.user / auth.token are now populated.
+      await api.placeBid(...);
+    }
+    // 'cancelled' → user dismissed the modal.
+    // 'unavailable' → portal has no AuthKit configured.
+  }
+
+  return <button onClick={onClick}>Place bid</button>;
+}
+```
+
+`requestLogin` is also exposed as `useAuthRequest().requestLogin` if you
+prefer a dedicated hook, but the folded `useSafeAuth()` shape is preferred
+so callers have one entry point for both session reads and login intent.
+
+### Options
+
+```ts
+auth.requestLogin({
+  reason?: string,                       // analytics / copy hint
+  mode?: 'login' | 'signup' | 'either',  // default 'either'
+  signupProminence?: SignupProminence,   // overrides modal default
+  resolveIfAuthenticated?: boolean,      // default true
+});
+```
+
+| Option | Default | Effect |
+|---|---|---|
+| `reason` | — | Free-form tag. Surfaced to analytics; some templates use it for copy. |
+| `mode` | `'either'` | `'signup'` biases the modal to the registration tab. |
+| `signupProminence` | portal default | One of `'minimal' | 'balanced' | 'emphasized'`. |
+| `resolveIfAuthenticated` | `true` | When already logged in, resolve immediately without showing the modal. Set `false` to force a fresh prompt (e.g. re-auth before a sensitive action). |
+
+### Result
+
+```ts
+type LoginRequestResult = {
+  status: 'success' | 'already-authenticated' | 'cancelled' | 'unavailable';
+  user?:  PortalAuthBridgeUser | null;
+  token?: string | null;
+};
+```
+
+- `success` — fresh login completed inside the modal.
+- `already-authenticated` — there was already a session; nothing was shown.
+- `cancelled` — user dismissed the modal without logging in.
+- `unavailable` — no AuthKit is configured on this portal. Treat as
+  not-logged-in and surface an appropriate message; the user cannot log
+  in from this portal at all.
+
+---
+
+## Iframe Apps (Cross-Origin)
+
+Iframe apps don't share React context with the portal. They post a request
+message and listen for a single correlated reply:
+
+```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:authkit:login-result') return;
+  if (d.payload?.requestId !== requestId) return;
+  window.removeEventListener('message', handler);
+
+  const { status, user, token } = d.payload;
+  if (status === 'success' || status === 'already-authenticated') {
+    // user + token populated — resume the action that needed auth
+    placeBid();
+  }
+});
+
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:request-login',
+  payload: {
+    requestId,
+    reason: 'bid',
+    mode: 'either',
+    resolveIfAuthenticated: true,
+  },
+}, '*');
+```
+
+The portal opens its modal, runs the standard AuthKit flow (including any
+WhatsApp / OAuth / magic-link redirect bounces), then posts exactly one
+`login-result` back with the same `requestId`.
+
+### Message contract
+
+**Request — child → parent**
+
+```ts
+{
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:request-login',
+  payload: {
+    requestId: string,             // generate per request; echoed in the reply
+    reason?: string,
+    mode?: 'login' | 'signup' | 'either',
+    signupProminence?: 'minimal' | 'balanced' | 'emphasized',
+    resolveIfAuthenticated?: boolean,
+  }
+}
+```
+
+**Reply — parent → child**
+
+```ts
+{
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:login-result',
+  payload: {
+    requestId: string,             // matches the request
+    status: 'success' | 'already-authenticated' | 'cancelled' | 'unavailable',
+    user?:  { uid, email?, displayName?, photoURL?, phoneNumber?, accountData? } | null,
+    token?: string | null,
+  }
+}
+```
+
+Only one reply is sent per `requestId`. Stacking multiple request-logins
+cancels prior pending requests — they receive `status: 'cancelled'`.
+
+---
+
+## Redirect-Bounce Flows (WhatsApp, OAuth, Magic Link)
+
+These are handled **inside the portal's AuthModal by AuthKit itself** —
+your iframe stays mounted at the same URL throughout. There is no
+sub-app state restoration to wire up; the modal closes when the redirect
+resolves and the portal posts back your `login-result`.
+
+If you have a sub-app that lives on a route the user navigates away from
+during the redirect, snapshot whatever you need into your own
+`sessionStorage` before calling `requestLogin`, the same as for any other
+async UX. The portal does not (yet) snapshot sub-app state on your behalf.
+
+---
+
+## Reading the Current Session
+
+You don't need to call `requestLogin` just to read the current session —
+that comes for free:
+
+```tsx
+// Container / widget
+import { useSafeAuth } from '@proveanything/portal-framework';
+const { user, token, isAuthenticated } = useSafeAuth() ?? {};
+```
+
+```ts
+// Iframe — the IframeResponder caches the parent's user under `cache.user`.
+// Read via the SDK's standard hooks/helpers.
+```
+
+---
+
+## Anti-Patterns
+
+❌ Sub-apps importing `@proveanything/smartlinks-auth-ui` and rendering
+   their own `<SmartlinksAuthUI />` modal. This is what `requestLogin`
+   replaces — duplicate React contexts cause silent header desync.
+
+❌ Posting `request-login` and then also opening a local fallback modal.
+   Pick one; the portal modal is canonical.
+
+❌ Reusing a single `requestId` across multiple calls. Generate a new ID
+   per request so replies can be correlated unambiguously.
+
+❌ Treating `unavailable` as an error to retry. It means the portal has no
+   AuthKit configured — surface a "login isn't available here" message.
+
+❌ Setting `resolveIfAuthenticated: false` for normal "gate this action"
+   use cases — you'll re-prompt logged-in users for no reason. Only use
+   it for genuine step-up auth.
+
+---
+
+## Relationship to `portal-auth-broadcast.md`
+
+| Concern | Use |
+|---|---|
+| "Log the user in so I can call my API" | **`requestLogin`** (this doc) |
+| "I ran my own custom auth flow, here's the resulting session" | [`portal-auth-broadcast.md`](./portal-auth-broadcast.md) |
+| "Log the user out of the whole portal" | `useAuth().logout()` (container/widget) or `smartlinks:authkit:logout` postMessage (iframe) |
+
+Both flows ultimately drive the same `PortalAuthProvider.login` /
+`logout` calls and produce the same observable side effects (header
+avatar, `useAuth()` re-render, `setBearerToken` on the SDK).