@proveanything/smartlinks 1.14.10 → 1.14.12

package/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/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)