Keep an open dialog's buttons whole on a small phone in German

At 320px, German's longer labels pushed the Open button past the screen
edge, since the upload label couldn't shrink and the buttons could. The
upload label now gives way, cut off with an ellipsis.

.github/workflows/ai-provider-integration-tests.yaml

@@ -53,7 +53,7 @@ jobs:
             # step above fails; the tests skip themselves without the key.
             - name: Run live realtime conversation tests
               if: ${{ !cancelled() }}
-              run: npm run setupExtensions && (cd src/puter-js && npm run build) && npx vitest run --config src/puter-js/tests/api/vitest.config.ts src/puter-js/tests/api/realtime/convoLive.test.ts
+              run: npm run setupExtensions && (cd src/puter-js && npm run build) && npx vitest run --config src/puter-js/tests/api/vitest.config.ts src/puter-js/tests/api/realtime/realtimeLive.test.ts
               env:
                   CI: 'true'
                   PUTER_TEST_AI_OPENAI_API_KEY: ${{ secrets.PUTER_TEST_AI_OPENAI_API_KEY }}

CLAUDE.md

@@ -1 +1 @@
-FOLLOW ./AGENTS.md
+FOLLOW @AGENTS.md

doc/embedding-app-browser.md

@@ -14,11 +14,25 @@ to its normal sign-in. Apps that need the desktop (built-in and godmode apps,
 private apps the user can't open, or a failed token request) open `/app/<name>`
 on the GUI origin, cut off from the embed. Website shortcuts open their external
 destination with no opener.
+The embed follows the OS's light or dark setting. A host with a fixed theme adds
+`theme=dark` or `theme=light` to the fragment (`#user=<uuid>&theme=dark`), since
+Chromium doesn't pass an iframe's `color-scheme` on to the page inside it.
 Apps opened from the embed carry `utm_source=puter.com&utm_medium=referral&utm_campaign=app_browser_embed`;
 the desktop and dashboard send `utm_campaign=desktop` and `utm_campaign=dashboard`.
 
 ## Session and framing
 
+The embed shows the GUI session only to the user the host page is signed in as.
+The host names that user's `uuid` (from `puter.auth.getUser()`) in the iframe
+URL's fragment, as `/embed/apps#user=<uuid>`. The embed reads the session, asks
+`/whoami` which user it belongs to, and shows the signed-out view unless the two
+match. So a host that names no user, a malformed one, or a user other than the
+session's, gets the signed-out view, and so does a session the API refuses. A
+failed `/whoami` check shows the error state. The fragment never reaches the
+server and can only narrow what the embed shows: naming the session's own user
+gives the same view as a direct visit to the GUI. Changing the fragment of a
+loaded embed reloads it.
+
 The embed reads the existing GUI session from local storage on its own origin.
 If that storage holds no session, the embed gets the session from the GUI origin's session cookie through
 `/get-gui-token`. This matters in Safari, which gives a framed origin separate
@@ -29,7 +43,7 @@ does not create accounts, show a login dialog, or accept a token from its parent
 Being signed in on a subdomain alone does not create a session on the main GUI
 origin.
 
-Without a session, the embed shows the recommended apps (`RecommendedAppsService`)
+Without a session it can show, the embed shows the recommended apps (`RecommendedAppsService`)
 that the server put in the page, and nothing else: no installed apps, folders, or
 saved order, and no puter.js. Selecting one opens it at the same URL a signed-in
 launch uses, with no opener and no token on offer, so the app signs in on its own.
@@ -58,11 +72,18 @@ and popups to escape the sandbox.
 
 ## Host integration
 
+A first-party app that signs in with puter.js can place `<puter-user-menu>` from
+the SDK in its header instead (see `src/puter-js/src/ui/components.md`). It opens
+this embed with the signed-in user named and closes it when the app's sign-in
+changes. The rest of this section is for a host that builds the iframe itself.
+
 The iframe can be shown whether or not the user is signed in. Create it when
-“More apps” is opened, and remove it on close so reopening loads current apps
-and preferences. The host owns the modal and close control;
+“More apps” is opened, naming the signed-in user in its fragment, and remove it
+on close so reopening loads current apps and preferences. Remove it when the
+host's own sign-in changes too, such as on sign-out, so an open embed doesn't
+keep the previous user. The host owns the modal and close control;
 there is no parent messaging API and no app list or credential is sent to it.
-The app browser fills its iframe and responds to its size.
+The app browser fills its iframe and responds to its size. It shows a spinner until its apps load.
 
 This example assumes `puterOrigin` comes from the host app's deployment
 settings. Translate the button and frame labels using the host app's
@@ -84,10 +105,14 @@ localization system.
   const container = document.querySelector('#apps-frame');
   const trigger = document.querySelector('#more-apps');
 
-  trigger.addEventListener('click', () => {
+  trigger.addEventListener('click', async () => {
+    const url = new URL('/embed/apps', puterOrigin);
+    // Signed out, the embed shows the recommended apps.
+    const user = puter.auth.isSignedIn() ? await puter.auth.getUser().catch(() => null) : null;
+    if (user) url.hash = `user=${encodeURIComponent(user.uuid)}`;
     const frame = document.createElement('iframe');
     frame.title = 'Your apps';
-    frame.src = new URL('/embed/apps', puterOrigin).href;
+    frame.src = url.href;
     container.replaceChildren(frame);
     dialog.showModal();
   });
@@ -99,22 +124,103 @@ localization system.
 </script>
 ```
 
-## Implementation and checks
+## Implementation
 
 `createAppBrowser` in `src/gui/src/UI/Dashboard/AppBrowser.js` owns the shared UI
 and data behavior; its `guestApps` option is the signed-out list. `TabApps.js`
 injects desktop actions. `appsEmbed.js` supplies new-tab launching through
 `launchAppInTab` (signed in) and `guestAppLaunchUrl` (signed out) in
 `src/gui/src/helpers/appTabLaunch.js`, which build the same app URL as
-`launch_app`, and loads only the embed entry, its SDK, and shared styles.
-The normal GUI webpack build emits `bundle.min.js` and `apps-embed.min.js`.
+`launch_app`, and loads only the embed entry, its SDK, and shared styles. `embedHostUser` in
+`src/gui/src/helpers/embedHostUser.js` reads the host's user from the fragment, and
+`embedHostTheme.js` beside it applies the host's theme.
+The normal GUI webpack build emits `bundle.min.js`, `apps-embed.min.js`, and `feedback-embed.min.js`.
 The `/embed/apps` route puts the recommended list in the page's config as
 `guestApps`. No puter.js API or app-list endpoint changes are needed.
 
+## Feedback dialog
+
+`GET /embed/feedback` is the app feedback dialog (`puter.ui.showFeedbackDialog()`)
+for a first-party page, with the same framing rules, query redirect, and
+host-user binding as `/embed/apps`. It sends the feedback for the framing
+page's origin, which the server reads from the referrer and pins with
+`frame-ancestors`; opened top-level, it does nothing. Its page is transparent
+so the dialog's own scrim covers the host.
+
+puter.js uses it on a page one label under the GUI origin, other than the
+subdomains the server refuses, when the page is signed in, framing it in a
+modal `<dialog>` that stays hidden until the embed is ready. A session check that takes longer than 200ms shows a loading scrim
+with a spinner in its place; Escape or a click on it cancels. The embed posts `{ msg: 'feedbackEmbed', state }` to its parent
+(`loading`, then `ready` or `unavailable`) and finally
+`{ msg: 'feedbackDialogClosed', sent }`. It reports `unavailable` without the
+named user's session, or while that user's email still needs confirming, and
+puter.js then uses the `/action/send-feedback` popup, which can sign in. So does
+a frame that never answers, such as one the host's CSP blocks. `feedbackEmbed.js`
+is the entry, sharing `embedSession` in `src/gui/src/helpers/embedSession.js`
+with the app browser; `showFeedbackEmbed` in `src/puter-js/src/lib/guiEmbed.js`
+is the host side.
+
+## Sign-in and file pickers
+
+`GET /embed/sign-in`, `/embed/show-open-file-picker`, `/embed/show-save-file-picker`
+and `/embed/show-directory-picker` serve the same GUI popups as `/action/<action>`
+for a first-party page, with the same framing rules, query redirect, and
+`no-store` as `/embed/apps`. Any other spelling of the path (another case, a
+trailing slash) redirects to it, since the shell boots the desktop for it. They render the normal GUI shell, which names the
+framing page (read from the referrer, pinned with `frame-ancestors`) as
+`gui_params.embed_host_origin`. The GUI then runs the popup boot unchanged, with
+the framing page as `window.opener`, and `window.close()` asks the page to
+remove the frame (`src/gui/src/helpers/popupFrame.js`). Without a framing page
+to answer (opened top-level, or framed by a refused page) it does nothing. The
+popup's parameters come from the fragment instead of the query: `msg_id`,
+`options` and `request_auth`, plus `user` for a picker.
+
+The frame posts `{ msg: 'puterPopupFrame', state }` to its parent: `loading` as
+soon as the shell boots, `ready` once it shows a window or dialog, `unavailable`
+when the page has to use the popup, `provider` when the user picks a sign-in
+provider (below), and `closed` where a popup would close. Its
+answers (`puter.token`, `fileOpenPicked`, `directoryPicked`, `fileSaved`, the
+cancel messages, `sendMeFileData`) are the popup's.
+
+puter.js uses them on a page one label under the GUI origin, other than the
+subdomains the server refuses, unless the page is cross-origin isolated or in a
+frame of another site (which `frame-ancestors` refuses too).
+`showPopupFrame` in `src/puter-js/src/lib/guiEmbed.js` shows the frame in a box
+the size of the popup window, over a scrim, hidden until `ready` and behind the
+loading spinner after 200ms. Escape closes it, on the page or in the frame. One shows per popup, as each
+popup has its own window name: a second picker request of the same kind
+replaces the one showing, and a `signIn()` call made while a framed sign-in is
+open settles with it. On
+screens up to 600px wide the box fills the screen. A frame that is refused,
+never answers, or reports `unavailable` falls back to the popup, opened through
+a consent dialog when the click that asked for it has expired. A reload or navigation the frame
+starts itself (logging out, a sign-out in another tab) names the frame as its
+referrer, so the server refuses it; the page then shows its spinner and opens
+the frame again, once per `ready`.
+
+- **Sign-in** (`puter.auth.signIn()`) has no host-user binding: it is how the
+  page gets a user. The box has a close button, which rejects with
+  `auth_window_closed` as closing the popup does. Providers refuse to be
+  framed, so choosing one posts `{ state: 'provider', url }` with the
+  provider's start URL for this sign-in's `msg_id`, then `unavailable`. The
+  page opens the popup straight at that URL, once it checks the URL is the
+  GUI's `/auth/oidc/<provider>/start` for this `msg_id`, and the provider
+  returns it as this sign-in's popup. `attempt_temp_user_creation` keeps the popup, since
+  only the popup creates a temporary account.
+- **Pickers** frame only for a signed-in page. The GUI reports `unavailable`
+  unless its session belongs to the user named in `user`, and the page then uses
+  the popup, which can sign in and switch accounts. The token the GUI sends
+  before a picker's answer isn't adopted, since it is for the page's own user.
+  Dismissing the loading scrim settles the picker as cancelled.
+
+## Checks
+
 Run the GUI component/browser tests (with the SDK bundle built and Playwright
 Chromium installed), and the backend route tests:
 
 ```sh
-npx vitest run --config src/gui/vitest.config.js src/gui/src/UI/Dashboard/AppBrowser
+npx vitest run --config src/gui/vitest.config.js src/gui/src/UI/Dashboard/AppBrowser src/feedbackEmbed
+npx vitest run src/puter-js/src/lib/guiEmbed.test.js src/puter-js/src/modules/UI.showFeedbackDialog.test.js src/puter-js/src/modules/Auth.signInFrame.test.js src/puter-js/src/modules/UI.pickerFrame.test.js
+npx vitest run --config src/gui/vitest.config.js src/gui/src/helpers/popupFrame.test.js
 npx vitest run --config src/backend/vitest.config.ts src/backend/server.test.ts
 ```

src/backend/controllers/homepage/HomepageController.test.ts

@@ -27,7 +27,7 @@ import type { Actor } from '../../core/actor.js';
 import { PuterRouter } from '../../core/http/PuterRouter.js';
 import { PuterServer } from '../../server.js';
 import { setupTestServer } from '../../testUtil.js';
-import { embedFrameAncestors } from './HomepageController.js';
+import { embedFrameAncestors, embedHostOrigin } from './HomepageController.js';
 
 // ── Test harness ────────────────────────────────────────────────────
 //
@@ -550,3 +550,26 @@ describe('embedFrameAncestors', () => {
         ).toBe("'self'");
     });
 });
+
+describe('embedHostOrigin', () => {
+    const config = {
+        origin: 'https://example.test',
+        domain: 'example.test',
+        api_base_url: 'https://backend.example.test',
+        static_hosting_domain: 'site.example.test',
+    };
+
+    it.each([
+        ['https://sheets.example.test/doc/1', 'https://sheets.example.test'],
+        ['https://backend.example.test/x', null],
+        ['https://api.example.test/', null],
+        ['https://someone.site.example.test/', null],
+        ['https://a.sheets.example.test/', null],
+        ['http://sheets.example.test/', null],
+        ['https://example.test/', null],
+        ['not a url', null],
+        [undefined, null],
+    ])('%s frames as %s', (referer, expected) => {
+        expect(embedHostOrigin(config, referer)).toBe(expected);
+    });
+});

src/backend/controllers/homepage/HomepageController.ts

@@ -31,8 +31,20 @@ import type {
     PuterHomepageService,
     PageMeta,
     LaunchOptions,
+    PopupFrame,
 } from '../../services/homepage/PuterHomepageService';
 
+/**
+ * GUI popups a first-party page can show in a frame at `/embed/<action>`,
+ * instead of opening `/action/<action>` in a window.
+ */
+export const FRAMED_POPUP_ACTIONS = [
+    'sign-in',
+    'show-open-file-picker',
+    'show-save-file-picker',
+    'show-directory-picker',
+] as const;
+
 /** Longest description/og:description/twitter:description on `/app/<name>`. */
 export const APP_META_DESCRIPTION_MAX = 150;
 
@@ -61,32 +73,34 @@ export function appMetaDescription(text: string): string {
     return `${cut.replace(/[\s,;:.!?…—-]+$/, '')}…`;
 }
 
+type EmbedFramingConfig = Pick<
+    IConfig,
+    | 'origin'
+    | 'domain'
+    | 'api_base_url'
+    | 'static_hosting_domain'
+    | 'static_hosting_domain_alt'
+    | 'private_app_hosting_domain'
+    | 'private_app_hosting_domain_alt'
+>;
+
 /**
- * `frame-ancestors` for the app browser embed. A wildcard over `*.<domain>`
+ * The origin of a first-party page that may frame an `/embed/*` page, named
+ * exactly from the request's referrer, or null. A wildcard over `*.<domain>`
  * would also admit user-hosted sites whenever the hosting domains sit under it,
- * so the embedding page is named exactly, from the request's referrer. Only a
- * single label under `<domain>` qualifies, and not one this server answers
- * itself (the API, WebDAV, SDK and native-app hosts).
+ * so only a single label under `<domain>` qualifies, and not one this server
+ * answers itself (the API, WebDAV, SDK and native-app hosts).
  */
-export function embedFrameAncestors(
-    config: Pick<
-        IConfig,
-        | 'origin'
-        | 'domain'
-        | 'api_base_url'
-        | 'static_hosting_domain'
-        | 'static_hosting_domain_alt'
-        | 'private_app_hosting_domain'
-        | 'private_app_hosting_domain_alt'
-    >,
+export function embedHostOrigin(
+    config: EmbedFramingConfig,
     referer: string | undefined,
-): string {
+): string | null {
     const gui = new URL(config.origin ?? `https://${config.domain}`);
     let parent: URL;
     try {
         parent = new URL(referer ?? '');
     } catch {
-        return "'self'";
+        return null;
     }
     const host = parent.hostname.toLowerCase();
     const label = subdomainLabelOf(host, config.domain);
@@ -105,7 +119,16 @@ export function embedFrameAncestors(
         !isReservedSubdomain(label) &&
         host !== new URL(config.api_base_url).hostname &&
         !hostingDomains.some((d) => host === d || host.endsWith(`.${d}`));
-    return allowed ? `'self' ${parent.origin}` : "'self'";
+    return allowed ? parent.origin : null;
+}
+
+/** `frame-ancestors` for an `/embed/*` page: the GUI and {@link embedHostOrigin}. */
+export function embedFrameAncestors(
+    config: EmbedFramingConfig,
+    referer: string | undefined,
+): string {
+    const host = embedHostOrigin(config, referer);
+    return host ? `'self' ${host}` : "'self'";
 }
 
 /**
@@ -142,6 +165,7 @@ export class HomepageController extends PuterController {
             res: express.Response,
             metaOverrides: Partial<PageMeta> = {},
             launch: LaunchOptions = {},
+            popupFrame?: PopupFrame,
         ) => {
             const meta = { ...defaultMeta(req), ...metaOverrides };
             const actor =
@@ -150,19 +174,27 @@ export class HomepageController extends PuterController {
                         actor?: Parameters<typeof homepage.send>[0]['actor'];
                     }
                 ).actor ?? null;
-            await homepage.send({ req, res, actor }, meta, launch);
+            await homepage.send({ req, res, actor }, meta, launch, popupFrame);
         };
 
         // -- Root + path-aliased shell routes ------------------------
 
         router.get('/', {}, (req, res) => sendShell(req, res));
 
-        router.get('/embed/apps', {}, async (req, res) => {
-            // SDK bootstrap parameters must not change this page's account or API origin.
-            // Checked on the raw URL; `req.query` drops pairs past the parser's limit.
+        /**
+         * Headers shared by the `/embed/*` pages; false when the request was
+         * redirected instead. SDK bootstrap parameters must not change an
+         * embed's account or API origin, so a query string is dropped. Checked
+         * on the raw URL; `req.query` drops pairs past the parser's limit.
+         */
+        const prepareEmbed = (
+            req: express.Request,
+            res: express.Response,
+            path: string,
+        ): boolean => {
             if (req.originalUrl.includes('?')) {
-                res.redirect('/embed/apps');
-                return;
+                res.redirect(path);
+                return false;
             }
             res.removeHeader('X-Frame-Options');
             res.setHeader(
@@ -170,6 +202,11 @@ export class HomepageController extends PuterController {
                 `frame-ancestors ${embedFrameAncestors(this.config, req.get('referer'))}`,
             );
             res.setHeader('Cache-Control', 'no-store');
+            return true;
+        };
+
+        router.get('/embed/apps', {}, async (req, res) => {
+            if (!prepareEmbed(req, res, '/embed/apps')) return;
             // Shown to visitors without a session; a signed-in embed fetches
             // its own list, so a failure here only costs signed-out visitors.
             const guestApps = await this.services.recommendedApps
@@ -178,6 +215,48 @@ export class HomepageController extends PuterController {
             res.send(homepage.renderAppBrowserEmbed({ guestApps }));
         });
 
+        router.get('/embed/feedback', {}, (req, res) => {
+            if (!prepareEmbed(req, res, '/embed/feedback')) return;
+            // The feedback is recorded against this origin, which
+            // frame-ancestors has just pinned to the actual framing page.
+            res.send(
+                homepage.renderFeedbackEmbed({
+                    hostOrigin: embedHostOrigin(
+                        this.config,
+                        req.get('referer'),
+                    ),
+                }),
+            );
+        });
+
+        // The GUI runs the popup's own boot, answering the framing page
+        // instead of an opener.
+        for (const action of FRAMED_POPUP_ACTIONS) {
+            const embedPath = `/embed/${action}`;
+            router.get(embedPath, {}, async (req, res) => {
+                // Routes match case-insensitively and with a trailing slash,
+                // and the shell boots the desktop for any other spelling, so
+                // only the exact one may be framed.
+                if (req.originalUrl !== embedPath) {
+                    res.redirect(embedPath);
+                    return;
+                }
+                if (!prepareEmbed(req, res, embedPath)) return;
+                await sendShell(
+                    req,
+                    res,
+                    {},
+                    {},
+                    {
+                        hostOrigin: embedHostOrigin(
+                            this.config,
+                            req.get('referer'),
+                        ),
+                    },
+                );
+            });
+        }
+
         router.get('/settings', {}, (req, res) => sendShell(req, res));
         router.get('/settings/*splat', {}, (req, res) => sendShell(req, res));
 

src/backend/core/http/middleware/hostRedirects.test.ts

@@ -187,9 +187,9 @@ describe('createUserSubdomainNotFound', () => {
     });
 
     it('passes through reserved subdomains (api, js, native apps, etc.)', () => {
-        // `api`, `js`, `dav`, `docs`, `developer`, `editor`, `pdf`,
+        // `api`, `js`, `dav`, `docs`, `developer`, `about`, `apps`,
         // `puter-app-icons`, etc. all pass through.
-        for (const sub of ['api', 'js', 'docs', 'editor', 'puter-app-icons']) {
+        for (const sub of ['api', 'js', 'docs', 'about', 'puter-app-icons']) {
             const { out, next } = run(
                 createUserSubdomainNotFound(config),
                 makeReq({
@@ -865,13 +865,13 @@ describe('createNativeAppStatic', () => {
 
     beforeAll(() => {
         root = mkdtempSync(nodePath.join(tmpdir(), 'native-apps-'));
-        mkdirSync(nodePath.join(root, 'editor', 'assets'), { recursive: true });
+        mkdirSync(nodePath.join(root, 'about', 'assets'), { recursive: true });
         writeFileSync(
-            nodePath.join(root, 'editor', 'index.html'),
-            '<h1>editor</h1>',
+            nodePath.join(root, 'about', 'index.html'),
+            '<h1>about</h1>',
         );
         writeFileSync(
-            nodePath.join(root, 'editor', 'assets', 'app.js'),
+            nodePath.join(root, 'about', 'assets', 'app.js'),
             'console.log(1);',
         );
         mkdirSync(nodePath.join(root, 'docs', 'dist'), { recursive: true });
@@ -893,7 +893,7 @@ describe('createNativeAppStatic', () => {
 
     it('leaves a native app name alone on a host outside our domains', async () => {
         const req = staticReq({
-            subdomains: ['com', 'example', 'editor'],
+            subdomains: ['com', 'example', 'about'],
             path: '/index.html',
         });
         (req as Request & { is_custom_domain?: boolean }).is_custom_domain =
@@ -907,7 +907,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             createNativeAppStatic(config),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
         );
@@ -915,17 +915,24 @@ describe('createNativeAppStatic', () => {
         expect(next).toHaveBeenCalledTimes(1);
     });
 
-    it('passes through subdomains that are not native apps', async () => {
-        const { out, next } = await runStatic(
-            withRoot(),
-            staticReq({
-                subdomains: ['localhost', 'puter', 'api'],
-                path: '/index.html',
-            }),
-        );
-        expect(out.sent).toBeUndefined();
-        expect(next).toHaveBeenCalledTimes(1);
-    });
+    // `editor`, `markus` and `pdf` are web apps on standard host routing,
+    // even with a folder of their own under the native apps root.
+    it.each(['api', 'editor', 'markus', 'pdf'])(
+        'passes %s through, as it is not a native app',
+        async (sub) => {
+            mkdirSync(nodePath.join(root, sub), { recursive: true });
+            writeFileSync(nodePath.join(root, sub, 'index.html'), sub);
+            const { out, next } = await runStatic(
+                withRoot(),
+                staticReq({
+                    subdomains: ['localhost', 'puter', sub],
+                    path: '/index.html',
+                }),
+            );
+            expect(out.sent).toBeUndefined();
+            expect(next).toHaveBeenCalledTimes(1);
+        },
+    );
 
     it('passes through when there is no subdomain at all', async () => {
         const { next } = await runStatic(
@@ -939,13 +946,13 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
         );
         expect(out.sent).toEqual({
             path: '/index.html',
-            root: nodePath.join(root, 'editor'),
+            root: nodePath.join(root, 'about'),
         });
         expect(next).not.toHaveBeenCalled();
     });
@@ -954,11 +961,11 @@ describe('createNativeAppStatic', () => {
         const { out } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'EDITOR'],
+                subdomains: ['localhost', 'puter', 'ABOUT'],
                 path: '/index.html',
             }),
         );
-        expect(out.sent?.root).toBe(nodePath.join(root, 'editor'));
+        expect(out.sent?.root).toBe(nodePath.join(root, 'about'));
     });
 
     it('serves docs out of its dist/ subdirectory, not the app root', async () => {
@@ -979,7 +986,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/assets',
                 originalUrl: '/assets?v=2',
             }),
@@ -995,7 +1002,7 @@ describe('createNativeAppStatic', () => {
         const { out } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/assets/',
             }),
         );
@@ -1007,7 +1014,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/nope.html',
             }),
         );
@@ -1019,7 +1026,7 @@ describe('createNativeAppStatic', () => {
         const { next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
             new Error('send failed'),
@@ -1032,7 +1039,7 @@ describe('createNativeAppStatic', () => {
             runStatic(
                 withRoot(),
                 staticReq({
-                    subdomains: ['localhost', 'puter', 'editor'],
+                    subdomains: ['localhost', 'puter', 'about'],
                     path: '/../../etc/passwd',
                 }),
             ),

src/backend/core/http/middleware/hostRedirects.ts

@@ -27,15 +27,7 @@ import { HttpError, isHttpError } from '../HttpError';
 import { isLocalWorkerHost } from './localWorkerProxy';
 
 /** Native-app subdomains served via `nativeAppStatic`. */
-const NATIVE_APP_SUBDOMAINS = [
-    'about',
-    'developer',
-    'docs',
-    'editor',
-    'markus',
-    'pdf',
-    'apps',
-] as const;
+const NATIVE_APP_SUBDOMAINS = ['about', 'developer', 'docs', 'apps'] as const;
 
 /** Subset served out of a `dist/` subdirectory rather than the app root. */
 const NATIVE_APPS_WITH_DIST = new Set(['docs', 'developer']);

src/backend/server.test.ts

@@ -368,12 +368,113 @@ describe('PuterServer host header validation', () => {
         expect(api.status).toBe(404);
     });
 
+    it('lets a deployment subdomain frame the feedback embed and names it', async () => {
+        const parent = `http://spreadsheet.puter.localhost:${port}`;
+        const res = await request('/embed/feedback', {
+            host: `puter.localhost:${port}`,
+            referer: `${parent}/sheet/1`,
+        });
+        expect(res.status).toBe(200);
+        expect(res.headers['x-frame-options']).toBeUndefined();
+        expect(res.headers['content-security-policy']).toBe(
+            `frame-ancestors 'self' ${parent}`,
+        );
+        expect(res.headers['cache-control']).toBe('no-store');
+        expect(res.body).toContain('/dist/feedback-embed.min.js');
+        expect(res.body).not.toContain('/dist/bundle.min.js');
+        const config = JSON.parse(
+            res.body.match(/id="feedback-embed-config">(.*?)<\/script>/)[1],
+        );
+        expect(config).toEqual({
+            apiOrigin: `http://api.puter.localhost:${port}`,
+            hostOrigin: parent,
+        });
+
+        const hosted = await request('/embed/feedback', {
+            host: `puter.localhost:${port}`,
+            referer: `http://someone.site.puter.localhost:${port}/`,
+        });
+        expect(hosted.headers['content-security-policy']).toBe("frame-ancestors 'self'");
+        expect(
+            JSON.parse(
+                hosted.body.match(/id="feedback-embed-config">(.*?)<\/script>/)[1],
+            ).hostOrigin,
+        ).toBeNull();
+
+        const redirected = await request('/embed/feedback?puter.api_origin=https://other.test', {
+            host: `puter.localhost:${port}`,
+        });
+        expect(redirected.status).toBe(302);
+        expect(redirected.headers.location).toBe('/embed/feedback');
+    });
+
+    it.each([
+        'sign-in',
+        'show-open-file-picker',
+        'show-save-file-picker',
+        'show-directory-picker',
+    ])('lets a deployment subdomain frame the %s popup and names it to the GUI', async (action) => {
+        const parent = `http://spreadsheet.puter.localhost:${port}`;
+        const guiParams = (body: string) =>
+            JSON.parse(body.match(/gui\((\{.*\})\);/)[1]);
+        const res = await request(`/embed/${action}`, {
+            host: `puter.localhost:${port}`,
+            referer: `${parent}/sheet/1`,
+        });
+        expect(res.status).toBe(200);
+        expect(res.headers['x-frame-options']).toBeUndefined();
+        expect(res.headers['content-security-policy']).toBe(
+            `frame-ancestors 'self' ${parent}`,
+        );
+        expect(res.headers['cache-control']).toBe('no-store');
+        expect(guiParams(res.body).embed_host_origin).toBe(parent);
+
+        const hosted = await request(`/embed/${action}`, {
+            host: `puter.localhost:${port}`,
+            referer: `http://someone.site.puter.localhost:${port}/`,
+        });
+        expect(hosted.headers['content-security-policy']).toBe("frame-ancestors 'self'");
+        expect(guiParams(hosted.body).embed_host_origin).toBeNull();
+
+        const redirected = await request(`/embed/${action}?auth_token=x&embedded_in_popup=true`, {
+            host: `puter.localhost:${port}`,
+            referer: `${parent}/sheet/1`,
+        });
+        expect(redirected.status).toBe(302);
+        expect(redirected.headers.location).toBe(`/embed/${action}`);
+        expect(redirected.headers['x-frame-options']).toBe('SAMEORIGIN');
+    });
+
+    it.each(['/embed/SIGN-IN', '/embed/Show-Open-File-Picker', '/embed/sign-in/'])(
+        'lets a first-party page frame only the exact spelling of %s',
+        async (spelling) => {
+            const res = await request(spelling, {
+                host: `puter.localhost:${port}`,
+                referer: `http://spreadsheet.puter.localhost:${port}/`,
+            });
+            expect(res.status).toBe(302);
+            expect(res.headers.location).toBe(spelling.toLowerCase().replace(/\/$/, ''));
+            expect(res.headers['x-frame-options']).toBe('SAMEORIGIN');
+            expect(res.headers['content-security-policy']).toBeUndefined();
+        },
+    );
+
+    it('names no framing page to the popups it serves in a window', async () => {
+        const res = await request('/action/sign-in?embedded_in_popup=true', {
+            host: `puter.localhost:${port}`,
+            referer: `http://spreadsheet.puter.localhost:${port}/`,
+        });
+        expect(res.headers['x-frame-options']).toBe('SAMEORIGIN');
+        expect(res.headers['content-security-policy']).toBeUndefined();
+        expect(res.body).not.toContain('embed_host_origin');
+    });
+
     it.each([
         ['a user-hosted site', 'http://someone.site.puter.localhost:PORT/'],
         ['a private app host', 'http://someone.app.puter.localhost:PORT/'],
         ['the API host', 'http://api.puter.localhost:PORT/'],
         ['the WebDAV host', 'http://dav.puter.localhost:PORT/'],
-        ['a native app host', 'http://editor.puter.localhost:PORT/'],
+        ['a native app host', 'http://about.puter.localhost:PORT/'],
         ['a nested subdomain', 'http://a.spreadsheet.puter.localhost:PORT/'],
         ['another site', 'http://evil.test:PORT/'],
         ['another port', 'http://spreadsheet.puter.localhost:1/'],

src/backend/services/homepage/PuterHomepageService.test.ts

@@ -107,6 +107,31 @@ describe('app browser embed shell', () => {
     });
 });
 
+describe('feedback embed shell', () => {
+    it('carries the framing page and API origin, and loads only its own script', () => {
+        const html = makeService({
+            api_base_url: 'https://api.deployment.test',
+            gui_bundle: '/static/bundle.min.js?v=42',
+        }).renderFeedbackEmbed({ hostOrigin: 'https://notes.deployment.test' });
+        const configJson = html.match(/id="feedback-embed-config">(.*?)<\/script>/)![1];
+        expect(JSON.parse(configJson)).toEqual({
+            apiOrigin: 'https://api.deployment.test',
+            hostOrigin: 'https://notes.deployment.test',
+        });
+        expect(html).toContain('<script defer src="/static/feedback-embed.min.js?v=42"></script>');
+        expect(html).toContain('<link rel="stylesheet" href="/css/feedback-embed.css">');
+        expect(html).toContain('<main id="feedback-embed"></main>');
+        expect(html).not.toContain('bundle.min.js');
+        expect(html).not.toContain('apps-embed');
+    });
+
+    it('carries no framing page when none is allowed', () => {
+        const html = makeService({}).renderFeedbackEmbed({ hostOrigin: null });
+        const configJson = html.match(/id="feedback-embed-config">(.*?)<\/script>/)![1];
+        expect(JSON.parse(configJson).hostOrigin).toBeNull();
+    });
+});
+
 /** Capture what the service sends, and return the rendered HTML. */
 const render = async (
     service: PuterHomepageService,

src/backend/services/homepage/PuterHomepageService.ts

@@ -48,6 +48,15 @@ export interface LaunchOptions {
     on_initialized?: Array<Record<string, unknown>>;
 }
 
+/**
+ * A GUI popup a first-party page frames at `/embed/<action>`. `hostOrigin` is
+ * that page, read from the referrer and pinned with frame-ancestors; null when
+ * no allowed page frames it.
+ */
+export interface PopupFrame {
+    hostOrigin: string | null;
+}
+
 interface PuterGuiAddonsEvent {
     req: Request;
     path: string;
@@ -171,15 +180,50 @@ export class PuterHomepageService extends PuterService {
     renderAppBrowserEmbed({
         guestApps = [],
     }: { guestApps?: Array<Record<string, unknown>> } = {}): string {
-        const configJson = JSON.stringify({
-            apiOrigin: this.config.api_base_url,
-            sdkUrl:
-                this.config.env === 'dev'
-                    ? '/sdk/puter.dev.js'
-                    : (this.config.gui_puterjs_bundle ??
-                      'https://js.puter.com/v2/'),
-            guestApps,
-        }).replace(/</g, '\\u003c');
+        return this.#renderEmbed({
+            rootId: 'app-browser',
+            rootClass: 'dashboard',
+            stylesheet: 'apps-embed.css',
+            script: 'apps-embed.min.js',
+            config: {
+                apiOrigin: this.config.api_base_url,
+                sdkUrl:
+                    this.config.env === 'dev'
+                        ? '/sdk/puter.dev.js'
+                        : (this.config.gui_puterjs_bundle ??
+                          'https://js.puter.com/v2/'),
+                guestApps,
+            },
+        });
+    }
+
+    /**
+     * `hostOrigin` is the first-party page framing the dialog, which the
+     * feedback is sent for; null when no allowed page frames it.
+     */
+    renderFeedbackEmbed({ hostOrigin }: { hostOrigin: string | null }): string {
+        return this.#renderEmbed({
+            rootId: 'feedback-embed',
+            stylesheet: 'feedback-embed.css',
+            script: 'feedback-embed.min.js',
+            config: { apiOrigin: this.config.api_base_url, hostOrigin },
+        });
+    }
+
+    #renderEmbed({
+        rootId,
+        rootClass,
+        stylesheet,
+        script,
+        config,
+    }: {
+        rootId: string;
+        rootClass?: string;
+        stylesheet: string;
+        script: string;
+        config: Record<string, unknown>;
+    }): string {
+        const configJson = JSON.stringify(config).replace(/</g, '\\u003c');
 
         return `<!DOCTYPE html>
 <html lang="en">
@@ -190,27 +234,27 @@ export class PuterHomepageService extends PuterService {
     <title>${encode(String(this.config.gui_params?.title ?? 'Puter'))}</title>
     <link rel="stylesheet" href="/css/normalize.css">
     <link rel="stylesheet" href="/css/dashboard.css">
-    <link rel="stylesheet" href="/css/apps-embed.css">
+    <link rel="stylesheet" href="/css/${stylesheet}">
 </head>
 <body>
-    <main id="app-browser" class="dashboard"></main>
-    <script type="application/json" id="app-browser-config">${configJson}</script>
-    <script defer src="${encode(this.#appBrowserEmbedScript())}"></script>
+    <main id="${rootId}"${rootClass ? ` class="${rootClass}"` : ''}></main>
+    <script type="application/json" id="${rootId}-config">${configJson}</script>
+    <script defer src="${encode(this.#embedScript(script))}"></script>
 </body>
 </html>`;
     }
 
     /**
-     * The embed's script is built beside the GUI bundle, so it is served from
+     * Embed scripts are built beside the GUI bundle, so they are served from
      * wherever `gui_bundle` is (a CDN in production), with the same query.
      */
-    #appBrowserEmbedScript(): string {
+    #embedScript(name: string): string {
         const base = 'http://relative.invalid';
         const bundle = new URL(
             this.config.gui_bundle ?? '/dist/bundle.min.js',
             base,
         );
-        const script = new URL('apps-embed.min.js', bundle);
+        const script = new URL(name, bundle);
         script.search = bundle.search;
         return script.origin === base
             ? `${script.pathname}${script.search}`
@@ -268,6 +312,7 @@ export class PuterHomepageService extends PuterService {
         ctx: { req: Request; res: Response; actor?: Actor | null },
         meta: PageMeta,
         launchOptions: LaunchOptions = {},
+        popupFrame?: PopupFrame,
     ): Promise<void> {
         const { req, res, actor } = ctx;
 
@@ -292,6 +337,7 @@ export class PuterHomepageService extends PuterService {
             { req, actor: actor ?? null },
             meta,
             launchOptions,
+            popupFrame,
         );
         res.send(html);
     }
@@ -302,6 +348,7 @@ export class PuterHomepageService extends PuterService {
         ctx: { req: Request; actor: Actor | null },
         meta: PageMeta,
         launchOptions: LaunchOptions,
+        popupFrame?: PopupFrame,
     ): Promise<string> {
         const { req, actor } = ctx;
         const env = this.config.env ?? 'prod';
@@ -347,6 +394,8 @@ export class PuterHomepageService extends PuterService {
             eventsNotifications: notificationsFoldInEnabled(this.config),
             ...meta,
             launch_options: launchOptions,
+            // After `meta`, so nothing page-specific can name the opener.
+            ...(popupFrame ? { embed_host_origin: popupFrame.hostOrigin } : {}),
         };
 
         const event: PuterGuiAddonsEvent = {

src/backend/services/realtime/README.md

@@ -1,11 +1,11 @@
 # OpenAI Realtime relay
 
 The relay serves `/puterai/openai/v1/realtime` on the API host. The SDK exposes
-it through [`puter.ai.convo()`](../../../docs/src/AI/convo.md).
+it through [`puter.ai.realtime()`](../../../docs/src/AI/realtime.md).
 
 **Beta:** This API is incomplete. Its methods, options, events, and behavior may change abruptly, including breaking changes without notice.
 
-Direct clients are documented in the [Realtime WebSocket API reference](../../../docs/src/AI/realtime.md).
+Direct clients are documented in the [Realtime WebSocket API reference](../../../docs/src/AI/realtime-websocket.md).
 
 ## Transport
 
@@ -27,7 +27,7 @@ The socket opens before authentication completes. Authentication and model
 failures arrive as OpenAI-shaped error events followed by a close frame.
 
 ```js
-const conversation = await puter.ai.convo({ output: ['text'] });
+const conversation = await puter.ai.realtime({ output: ['text'] });
 conversation.on('error', (event) => console.error(event));
 conversation.on('text', ({ delta }) => console.log(delta));
 conversation.on('turn.done', () => conversation.close());

src/backend/types.ts

@@ -1102,8 +1102,9 @@ interface IConfigOptional {
     /** Force the bundled GUI even in dev. Default: false. */
     use_bundled_gui: boolean;
     /**
-     * Override the GUI bundle JS path. Default: `/dist/bundle.min.js`. The app
-     * browser embed loads `apps-embed.min.js` from the same directory.
+     * Override the GUI bundle JS path. Default: `/dist/bundle.min.js`. The
+     * `/embed/*` pages load `apps-embed.min.js` and `feedback-embed.min.js`
+     * from the same directory.
      */
     gui_bundle: string;
     /** Override the GUI CSS path when bundled. Default: `/dist/bundle.min.css`. */

src/docs/src/AI.md

@@ -200,8 +200,8 @@ These AI features are supported out of the box when using Puter.js:
 - **[`puter.ai.img2txt()`](/AI/img2txt/)** - Extract text from images (OCR)
 - **[`puter.ai.txt2vid()`](/AI/txt2vid/)** - Generate short video clips from text or a reference image with Wan, Seedance, Veo, Kling, MiniMax H3 and other models, or edit a video you supply with Gemini Omni, FLUX 3 or Kling Omni
 - **[`puter.ai.speech2speech()`](/AI/speech2speech/)** - Convert speech in one voice to another voice
-- **[`puter.ai.convo()`](/AI/convo/)** - Prepare a beta realtime conversation with optional text, microphone, playback, and interruption helpers
-- **[Realtime WebSocket API](/AI/realtime/)** - Connect directly without puter.js. This API is in beta and may change abruptly.
+- **[`puter.ai.realtime()`](/AI/realtime/)** - Prepare a beta realtime conversation with optional text, microphone, playback, and interruption helpers
+- **[Realtime WebSocket API](/AI/realtime-websocket/)** - Connect directly without puter.js. This API is in beta and may change abruptly.
 - **[`puter.ai.listModels()`](/AI/listModels/)** - List available AI chat models (and providers) that Puter currently exposes.
 - **[`puter.ai.listModelProviders()`](/AI/listModelProviders/)** - List the AI providers that Puter currently exposes.
 - **[`puter.ai.txt2speech.listEngines()`](/AI/txt2speech.listEngines/)** - List available TTS engines/models

src/docs/src/AI/convo.md

@@ -1,151 +0,0 @@
----
-title: puter.ai.convo()
-description: Prepare an OpenAI realtime conversation with optional audio and text helpers.
-platforms: [websites, apps, nodejs, workers]
----
-
-Prepares a realtime OpenAI conversation that your app can connect to when it's ready.
-
-Preparing the conversation verifies Puter sign-in. Realtime conversations require a paid Puter plan, and usage is billed to the signed-in user. Native OpenAI events and convenience methods use the same session. Microphone capture and speaker playback start when your app requests them.
-
-In Node.js, the SDK requires a global `WebSocket`, available in Node.js 22 or later.
-
-**Beta:** This API is incomplete. Its methods, options, events, and behavior may change abruptly, including breaking changes without notice.
-
-To connect without puter.js, see the [Realtime WebSocket API](/AI/realtime/).
-
-## Syntax
-
-```js
-const conversation = await puter.ai.convo(options = {});
-await conversation.connect();
-```
-
-## Parameters
-
-#### `options` (Object) (Optional)
-
-The options object accepts these fields.
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `model` | `String` | The realtime model. Defaults to `gpt-realtime-2.1-mini`. Also accepts `gpt-realtime-2.1`, `gpt-realtime-2`, `gpt-realtime-1.5`, `gpt-realtime`, and `gpt-realtime-mini`. |
-| `instructions` | `String` | Session instructions, up to 8192 characters. Defaults to the provider's default. |
-| `output` | `Array<String>` | Accepts `['text']`, `['audio']`, or both. Defaults to `['audio']`. Audio includes a transcript. Requesting both uses audio output and emits transcript deltas through the `text` event. |
-| `voice` | `String` | OpenAI voice identifier, up to 128 characters. Defaults to the provider's default. |
-| `turnDetection` | `Boolean` | Whether the provider detects the end of spoken turns automatically. Defaults to `true`. Set to `false` for manual audio commits. |
-
-## Return value
-
-A Promise resolves to a prepared conversation after options and sign-in are checked. In a browser, preparation opens the Puter sign-in prompt if needed. Preparation opens no realtime connection and requests no microphone access.
-
-The conversation exposes these properties and methods.
-
-| Member | Behavior |
-| --- | --- |
-| `state` | `prepared`, `connecting`, `connected`, or `closed`. |
-| `model` | Resolved model name. |
-| `connect()` | Opens the connection and applies settings. Resolves after the provider acknowledges session configuration. Concurrent calls share one connection Promise, including bounded retries for transient setup failures. Calling it while connected opens no additional connection. During a reconnection, it resolves when the reconnection succeeds and rejects if the conversation closes instead. |
-| `configure(options)` | Updates the given session settings and resolves after the provider acknowledges this update. Settings it isn't given, including ones set through native events, are left alone. Accepts the factory options except `model`. One update can be pending at a time. Provider rules apply to changes such as switching a voice after audio has been generated. |
-| `sendText(text)` | Adds a user message and requests a response. Text must be nonempty and at most 8192 characters. |
-| `appendAudio(pcm)` | Appends an `Int16Array` containing PCM16, 24 kHz mono audio. A chunk contains at most 12000 samples. |
-| `commitAudio()` | Commits buffered audio and requests a response. Requires turn detection to be off, through `turnDetection: false` or a native session update. The provider requires at least 100 ms of buffered audio. |
-| `interrupt(position?)` | Stops built-in playback immediately and waits for cancellation and playback-history synchronization. A reply requested but not yet started is cancelled as soon as it starts. Custom players provide `{ itemId, contentIndex, playedMs }`. An idle call resolves immediately. Readiness failures reject the returned Promise with `session_not_ready` or `session_closed`. |
-| `send(event)` | Sends a native OpenAI JSON event. |
-| `on(type, handler)` | Registers a listener and returns an unsubscribe function. Use `'*'` to receive every native and convenience event. |
-| `off(type, handler)` | Removes a listener. |
-| `close()` | Closes the session, rejects pending operations, and releases SDK-owned capture and playback resources. Repeated calls have no additional effect. |
-
-Attach listeners before connecting to receive initial session events. Closing during connection rejects the pending attempt.
-
-If the connection drops because of network loss, a server restart or a provider error, the conversation reconnects on its own. Normal closes with code 1000 end the conversation. While it reconnects, `state` is `connecting`, a `reconnecting` event fires, and pending operations reject with `connection_lost`. The new session gets every setting the provider acknowledged, from the factory options, `configure()` and native `session.update` events. Then `ready` fires again with `reconnected: true`. Listeners, the microphone and the speaker carry over. Microphone audio captured while reconnecting is dropped.
-
-The conversation also restores recent context. Before `ready` fires, it adds back up to 40 of the most recent conversation items, 48 KiB in total. Restored items are user text, user speech that has a transcript, assistant replies as text, and function calls with their outputs. User speech has a transcript only when input transcription is configured through native session settings. An assistant reply that was interrupted, or still playing when the connection dropped, is cut to what the user saw or heard. The cut is estimated from how much of the audio played, so it can be off by a few words. Images, speech without a transcript, deleted items, and replies still generating when the connection dropped are left out. Restored items get new item IDs, don't fire item events, and count as input tokens on the next response. Item IDs from before the reconnect don't work in later events. Restoration uses a contiguous suffix of restorable items. An oversized newest item leaves that suffix empty. Older items left out to fit the window fire a `context_trimmed` event with the count in `omittedItems`; this is routine and not an error. A provider refusal or a failure to send the restored items fires one `error` event with code `context_restore_failed` per restoration. In both cases the conversation stays connected. Items are preserved without truncating text, function arguments or function results.
-
-When Puter knows ahead of time that the server a session runs on will restart, it sends a `puter.reconnect` event, which also reaches your listeners. Without that notice, a restart drops the connection and the conversation reconnects as above. Within a few seconds, the conversation opens a replacement session in the background while the current one keeps working. It switches once no reply is generating or playing, no user turn is being spoken or transcribed, no function call is waiting for its output, and nothing you sent is waiting on the provider. The switch goes through the same steps as a reconnect, and the `reconnecting` event has code 1012. If the replacement can't open yet, the conversation keeps the current session and tries again later. A refusal that retrying can't fix, such as `insufficient_funds`, stops the attempts. If the server closes the session first, the conversation switches to the replacement, or reconnects if none is open.
-
-The conversation makes up to ten attempts over about a minute. In a browser that reports being offline, it first waits up to two minutes for the connection to come back. If every attempt fails, or the server refuses with an error such as `insufficient_funds`, the conversation closes. A closed conversation cannot reconnect. To start another session, prepare a new one.
-
-Native event definitions are listed in the [OpenAI realtime reference](https://developers.openai.com/api/reference/resources/realtime/server-events). Native events retain their provider fields. Sending native events preserves direct control of the session. Puter refuses `conversation.item.retrieve` events and MCP tools (`"type": "mcp"`) in `session.update` and `response.create` events. Sending one fires an `error` event with code `invalid_event`, and the conversation closes with code 1008. Audio helpers expect the session to use PCM16 at 24 kHz.
-
-## Errors and limits
-
-Failures use objects containing `code` and `message`. Preparation can reject with `invalid_argument`, `model_not_found`, `auth_required`, `auth_canceled`, or `auth_failed`. Connection can reject with `subscription_required` or `insufficient_funds`, which also show the Puter upgrade prompt. Connection and asynchronous operations can reject with provider errors, `session_closed`, `connection_lost`, `operation_timeout`, or `operation_in_progress`. Sending before readiness, or while reconnecting, throws `session_not_ready`.
-
-Invalid input throws `invalid_argument`, `invalid_event`, or `input_too_large`. A full SDK send queue throws `queue_full`. Media helpers report `unsupported_environment`, `permission_denied`, `media_error`, `media_timeout`, or `queue_full`. Runtime media errors and `context_restore_failed` arrive through the `error` event. Provider errors also arrive as native `error` events with a nested `error` object.
-
-Each native event is capped at 64 KiB. The SDK bounds JSON traversal, outgoing queues, acknowledgment waits, microphone work, and playback. All numeric limits are listed on [rate limits and quotas](/rate-limits-and-quotas/).
-
-## Convenience events
-
-The conversation emits these events alongside native events.
-
-| Event | Fields |
-| --- | --- |
-| `ready` | `model`, `provider`, and `reconnected: true` after a reconnection |
-| `reconnecting` | `code`, `reason` of the dropped connection. After a `puter.reconnect` event, `code` is 1012. |
-| `context_trimmed` | `omittedItems`, the number of restorable items left out of the restored context after a reconnection. Fires before `ready`. |
-| `text` | `delta`, `responseId` |
-| `transcript` | `role`, `text`, `final`. Assistant deltas use `final: false`. Completed assistant and user transcripts use `final: true`. User transcripts require transcription to be configured through native session settings. |
-| `audio` | `pcm`, `sampleRate`, `responseId`, `itemId`, `contentIndex`. The PCM chunk is an `Int16Array`. |
-| `interrupted` | `source` (`manual` or `speech`), `responseId` |
-| `turn.done` | `responseId`, native provider `usage`, `status` |
-| `close` | `code`, `reason` |
-
-Each event includes its `type`. When the provider event leaves out an ID, `responseId` and `itemId` are empty strings and `contentIndex` is `0`. The `interrupted` event signals local interruption immediately. Its corresponding operation resolves after the provider acknowledges cancellation and any requested truncation. Late audio from a canceled response remains visible as native events and is excluded from convenience audio and built-in playback.
-
-## Browser media
-
-The optional microphone and speaker helpers require a browser with Web Audio support. Microphone capture also requires media permissions and a secure context. Start audio from a user action so the browser can allow playback.
-
-| Member | Behavior |
-| --- | --- |
-| `microphone.start()` | Requests microphone access and streams PCM16, resampled to 24 kHz, in 20 ms chunks through an AudioWorklet. If the page or network falls behind, chunks are dropped rather than stopping capture. |
-| `microphone.mute()` | Disables capture tracks and stops forwarding captured chunks. |
-| `microphone.unmute()` | Enables capture tracks and forwarding. |
-| `microphone.stop()` | Stops capture tracks and releases capture resources. A `start()` still waiting on the permission prompt rejects with `session_closed`. |
-| `speaker.start({ bargeIn: true })` | Starts playback. Barge-in defaults to `true`. With barge-in enabled, provider speech-start events interrupt playback and synchronize played audio with conversation history. Starting the speaker requests no microphone access. |
-| `speaker.stop()` | Clears playback and releases its audio context. |
-
-Both start methods require a connected session. Capture and playback are independent, so custom audio input can use the built-in speaker, and built-in capture can use custom playback.
-
-## Examples
-
-### Have a text conversation
-
-A text conversation uses convenience methods for input and streamed output.
-
-```js
-const conversation = await puter.ai.convo({
-    output: ['text'],
-    instructions: 'Keep replies short.',
-});
-
-conversation.on('text', ({ delta }) => console.log(delta));
-conversation.on('turn.done', () => conversation.close());
-conversation.on('error', (event) => console.error(event));
-
-await conversation.connect();
-conversation.sendText('Say hello in three words.');
-```
-
-### Have a voice conversation
-
-A voice conversation enables the microphone and speaker after connection.
-
-```js
-const conversation = await puter.ai.convo();
-conversation.on('transcript', ({ role, text }) => console.log(role, text));
-conversation.on('error', (event) => console.error(event));
-
-await conversation.connect();
-await conversation.speaker.start();
-await conversation.microphone.start();
-
-// To interrupt a response and submit a replacement text turn:
-await conversation.interrupt();
-conversation.sendText('Actually, make it Wednesday.');
-
-// When the user ends the conversation:
-conversation.close();
-```

src/docs/src/AI/realtime-websocket.md

@@ -0,0 +1,126 @@
+---
+title: Realtime WebSocket API (Beta)
+description: Connect to OpenAI realtime conversations through Puter without puter.js.
+platforms: [websites, apps, nodejs, workers]
+---
+
+The Realtime WebSocket API lets your client send and receive native OpenAI realtime JSON events through Puter.
+
+Puter authenticates the user and charges their account for usage.
+
+**Beta:** This API is incomplete. Its methods, options, events, and behavior may change abruptly, including breaking changes without notice.
+
+For optional text, microphone, playback, and interruption helpers, use [`puter.ai.realtime()`](/AI/realtime/).
+
+## Connection and authentication
+
+Connect to this URL on the Puter API host:
+
+```text
+wss://api.puter.com/puterai/openai/v1/realtime?model=gpt-realtime-2.1-mini
+```
+
+The `model` query parameter defaults to `gpt-realtime-2.1-mini`. The model is fixed for the connection. A session update that changes it is rejected. It also accepts `gpt-realtime-2.1`, `gpt-realtime-2`, `gpt-realtime-1.5`, `gpt-realtime`, and `gpt-realtime-mini`.
+
+Authenticate with a Puter session, app, or full-access API token. Puter supplies the provider credential. Server clients pass this header:
+
+```text
+Authorization: Bearer <PUTER_TOKEN>
+```
+
+Browser WebSocket clients pass `realtime` and `openai-insecure-api-key.<PUTER_TOKEN>` as subprotocols. The server echoes only `realtime`. The endpoint also accepts an `auth_token` query parameter. Prefer the authorization header where supported because URLs and subprotocols can appear in logs. Authentication takes precedence in this order, header, subprotocol, then query parameter.
+
+The socket can open before authentication and provider setup finish. Listen for errors and closure immediately. Wait for `session.created`, send your session settings, then wait for `session.updated` before submitting a turn.
+
+To open a replacement while another connection remains healthy, set the optional `purpose=handover` query parameter. These attempts share a smaller per-credential budget, checked before the general connection-attempt budget. Initial connections and dropped-connection recovery use the URL without this parameter. The limits are listed in [rate limits and quotas](/rate-limits-and-quotas/).
+
+## Text example
+
+Install the `ws` package and set `PUTER_TOKEN` to your Puter token. Run this example as a Node.js ES module:
+
+```js
+import WebSocket from 'ws';
+
+const socket = new WebSocket(
+    'wss://api.puter.com/puterai/openai/v1/realtime?model=gpt-realtime-2.1-mini',
+    { headers: { Authorization: `Bearer ${process.env.PUTER_TOKEN}` } },
+);
+const send = (event) => socket.send(JSON.stringify(event));
+
+socket.on('message', (data) => {
+    const event = JSON.parse(data.toString());
+
+    if (event.type === 'session.created') {
+        send({
+            type: 'session.update',
+            session: {
+                type: 'realtime',
+                output_modalities: ['text'],
+                instructions: 'Keep replies short.',
+            },
+        });
+    }
+    if (event.type === 'session.updated') {
+        send({
+            type: 'conversation.item.create',
+            item: {
+                type: 'message',
+                role: 'user',
+                content: [{ type: 'input_text', text: 'Hello!' }],
+            },
+        });
+        send({ type: 'response.create' });
+    }
+    if (event.type === 'response.output_text.delta')
+        process.stdout.write(event.delta);
+    if (event.type === 'error')
+        console.error(event.error);
+    if (event.type === 'response.done')
+        socket.close();
+});
+socket.on('error', console.error);
+socket.on('close', (code, reason) => console.log(code, reason.toString()));
+```
+
+## Events, audio, and interruption
+
+Each message contains one JSON object with a nonempty string `type` of at most 128 characters. Binary messages are rejected. Native events retain their provider fields. The endpoint doesn't deliver `rate_limits.updated`, which describes Puter's provider account rather than yours, and it removes provider organization IDs from error messages. The endpoint exposes the WebSocket event protocol. Your client manages capture, playback, acknowledgments, and timeouts.
+
+The endpoint refuses `conversation.item.retrieve` events and MCP tools (`"type": "mcp"`) in `session.update` and `response.create` events. A refused event isn't sent to the provider. The session gets an `invalid_event` error and closes with 1008.
+
+PCM16 audio configured at 24 kHz mono is sent as base64 chunks in `input_audio_buffer.append` events. Output arrives in `response.output_audio.delta` events. With manual turn detection, commit buffered input with `input_audio_buffer.commit`, then request a reply with `response.create`.
+
+To interrupt, stop local playback immediately and send `response.cancel` with the active `response_id`. If some generated audio was not played, send `conversation.item.truncate` with its `item_id`, `content_index`, and `audio_end_ms` set to the amount actually played. Wait for `response.done` and any requested `conversation.item.truncated` acknowledgment before submitting a replacement turn.
+
+Connection loss ends the session. Reconnecting creates a new conversation. Tool execution and automatic reconnection belong to your client.
+
+## Server restarts
+
+When Puter knows ahead of time that the server a session runs on will restart, it sends each open session this event, at most once a minute:
+
+```json
+{
+    "type": "puter.reconnect",
+    "event_id": "event_puter_1767225600000",
+    "reason": "server_restarting",
+    "close_in_ms": 90000
+}
+```
+
+The `reason` field is `server_restarting`. The `close_in_ms` field, when present, is about how long until the server closes the session itself. The session keeps working until then. Open a new connection after a short, randomized delay, and once it gets `session.created` and your client is idle, with no response generating and no user turn in progress, move to it and close the old one. A connection that reaches a server that is also restarting gets a `server_restarting` error and closes with 1012. In that case keep the old session and try again after a short, randomized delay. If the server closes the old session first, the close code is 1012, and your client reconnects the same way. A restart can also drop the connection without any notice, so treat an unexpected close the same way.
+
+A new connection starts an empty conversation. To keep context, add earlier items back with `conversation.item.create` before you request a response. Event types that start with `puter.` come from Puter, not the provider.
+
+## Errors, billing, and limits
+
+API errors arrive as `{ "type": "error", "error": { "code": "...", "message": "..." } }`. Handle socket errors and close frames too. Invalid, missing, or revoked credentials use `invalid_api_key`. If Puter can't check a credential or the account's plan, the error is `internal_error` and the session closes with 1011, so try again after a short, randomized delay. Other relay codes include `permission_denied`, `model_not_found`, `insufficient_funds`, `subscription_required`, `rate_limit_exceeded`, `invalid_event`, `connection_timeout`, `provider_unavailable`, `upstream_error`, and `server_restarting`.
+
+Policy failures generally close with 1008, oversized client messages with 1009, upstream or setup failures with 1011, server restarts with 1012, and temporary server overload with 1013. Reconnect after 1011, 1012, or 1013. Authentication and model failures can arrive after the WebSocket handshake succeeds.
+
+The endpoint requires a paid Puter plan. Usage is charged after completed responses and input transcriptions. While a response generates, part of your balance is held for it, so a session opens only if your balance covers one response. If the provider connection closes before a response reports its usage, the response is charged the full amount held for it. Each account can open 20 sessions at once by default. Each JSON message you send is limited to 64 KiB, including reassembled fragments. Messages from the provider can be up to 4 MiB. Stream audio in small chunks. All message rates, queue caps, timeouts, and other bounds are published in [rate limits and quotas](/rate-limits-and-quotas/).
+
+Input transcription holds a small amount of your balance per transcribed item, priced at the transcription model you select. Two items are reserved ahead of your audio and replenished as the provider commits them, so a session holds only its spare items plus the items still awaiting a transcript. Changing the transcription model reprices the spare items. If your balance can't cover another item, audio waits while earlier items settle; once none are left to settle, the session closes with `insufficient_funds`. Failed transcriptions, items without final usage, and audio whose commit the provider never acknowledges before the connection closes are each charged that model's fixed per-item amount. Unacknowledged audio is charged one item per started 160 seconds. With server turn detection, only detected speech counts, so silence is never charged. The amounts, timeout and audio limits are listed in [rate limits and quotas](/rate-limits-and-quotas/).
+
+Provider-reported realtime models must have a known price. A missing model uses the last known model. An explicitly unpriced model closes the connection with `upstream_error`.
+
+After recording usage, the connection can continue while settled credit is positive, including a fractional balance. Each new billable operation still needs its full reservation after accounting for other outstanding holds.

src/docs/src/AI/realtime.md

@@ -1,126 +1,151 @@
 ---
-title: Realtime WebSocket API (Beta)
-description: Connect to OpenAI realtime conversations through Puter without puter.js.
+title: puter.ai.realtime()
+description: Prepare an OpenAI realtime conversation with optional audio and text helpers.
 platforms: [websites, apps, nodejs, workers]
 ---
 
-The Realtime WebSocket API lets your client send and receive native OpenAI realtime JSON events through Puter.
+Prepares a realtime OpenAI conversation that your app can connect to when it's ready.
 
-Puter authenticates the user and charges their account for usage.
+Preparing the conversation verifies Puter sign-in. Realtime conversations require a paid Puter plan, and usage is billed to the signed-in user. Native OpenAI events and convenience methods use the same session. Microphone capture and speaker playback start when your app requests them.
+
+In Node.js, the SDK requires a global `WebSocket`, available in Node.js 22 or later.
 
 **Beta:** This API is incomplete. Its methods, options, events, and behavior may change abruptly, including breaking changes without notice.
 
-For optional text, microphone, playback, and interruption helpers, use [`puter.ai.convo()`](/AI/convo/).
+To connect without puter.js, see the [Realtime WebSocket API](/AI/realtime-websocket/).
 
-## Connection and authentication
-
-Connect to this URL on the Puter API host:
-
-```text
-wss://api.puter.com/puterai/openai/v1/realtime?model=gpt-realtime-2.1-mini
-```
-
-The `model` query parameter defaults to `gpt-realtime-2.1-mini`. The model is fixed for the connection. A session update that changes it is rejected. It also accepts `gpt-realtime-2.1`, `gpt-realtime-2`, `gpt-realtime-1.5`, `gpt-realtime`, and `gpt-realtime-mini`.
-
-Authenticate with a Puter session, app, or full-access API token. Puter supplies the provider credential. Server clients pass this header:
-
-```text
-Authorization: Bearer <PUTER_TOKEN>
-```
-
-Browser WebSocket clients pass `realtime` and `openai-insecure-api-key.<PUTER_TOKEN>` as subprotocols. The server echoes only `realtime`. The endpoint also accepts an `auth_token` query parameter. Prefer the authorization header where supported because URLs and subprotocols can appear in logs. Authentication takes precedence in this order, header, subprotocol, then query parameter.
-
-The socket can open before authentication and provider setup finish. Listen for errors and closure immediately. Wait for `session.created`, send your session settings, then wait for `session.updated` before submitting a turn.
-
-To open a replacement while another connection remains healthy, set the optional `purpose=handover` query parameter. These attempts share a smaller per-credential budget, checked before the general connection-attempt budget. Initial connections and dropped-connection recovery use the URL without this parameter. The limits are listed in [rate limits and quotas](/rate-limits-and-quotas/).
-
-## Text example
-
-Install the `ws` package and set `PUTER_TOKEN` to your Puter token. Run this example as a Node.js ES module:
+## Syntax
 
 ```js
-import WebSocket from 'ws';
+const conversation = await puter.ai.realtime(options = {});
+await conversation.connect();
+```
 
-const socket = new WebSocket(
-    'wss://api.puter.com/puterai/openai/v1/realtime?model=gpt-realtime-2.1-mini',
-    { headers: { Authorization: `Bearer ${process.env.PUTER_TOKEN}` } },
-);
-const send = (event) => socket.send(JSON.stringify(event));
+## Parameters
 
-socket.on('message', (data) => {
-    const event = JSON.parse(data.toString());
+#### `options` (Object) (Optional)
 
-    if (event.type === 'session.created') {
-        send({
-            type: 'session.update',
-            session: {
-                type: 'realtime',
-                output_modalities: ['text'],
-                instructions: 'Keep replies short.',
-            },
-        });
-    }
-    if (event.type === 'session.updated') {
-        send({
-            type: 'conversation.item.create',
-            item: {
-                type: 'message',
-                role: 'user',
-                content: [{ type: 'input_text', text: 'Hello!' }],
-            },
-        });
-        send({ type: 'response.create' });
-    }
-    if (event.type === 'response.output_text.delta')
-        process.stdout.write(event.delta);
-    if (event.type === 'error')
-        console.error(event.error);
-    if (event.type === 'response.done')
-        socket.close();
+The options object accepts these fields.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `model` | `String` | The realtime model. Defaults to `gpt-realtime-2.1-mini`. Also accepts `gpt-realtime-2.1`, `gpt-realtime-2`, `gpt-realtime-1.5`, `gpt-realtime`, and `gpt-realtime-mini`. |
+| `instructions` | `String` | Session instructions, up to 8192 characters. Defaults to the provider's default. |
+| `output` | `Array<String>` | Accepts `['text']`, `['audio']`, or both. Defaults to `['audio']`. Audio includes a transcript. Requesting both uses audio output and emits transcript deltas through the `text` event. |
+| `voice` | `String` | OpenAI voice identifier, up to 128 characters. Defaults to the provider's default. |
+| `turnDetection` | `Boolean` | Whether the provider detects the end of spoken turns automatically. Defaults to `true`. Set to `false` for manual audio commits. |
+
+## Return value
+
+A Promise resolves to a prepared conversation after options and sign-in are checked. In a browser, preparation opens the Puter sign-in prompt if needed. Preparation opens no realtime connection and requests no microphone access.
+
+The conversation exposes these properties and methods.
+
+| Member | Behavior |
+| --- | --- |
+| `state` | `prepared`, `connecting`, `connected`, or `closed`. |
+| `model` | Resolved model name. |
+| `connect()` | Opens the connection and applies settings. Resolves after the provider acknowledges session configuration. Concurrent calls share one connection Promise, including bounded retries for transient setup failures. Calling it while connected opens no additional connection. During a reconnection, it resolves when the reconnection succeeds and rejects if the conversation closes instead. |
+| `configure(options)` | Updates the given session settings and resolves after the provider acknowledges this update. Settings it isn't given, including ones set through native events, are left alone. Accepts the factory options except `model`. One update can be pending at a time. Provider rules apply to changes such as switching a voice after audio has been generated. |
+| `sendText(text)` | Adds a user message and requests a response. Text must be nonempty and at most 8192 characters. |
+| `appendAudio(pcm)` | Appends an `Int16Array` containing PCM16, 24 kHz mono audio. A chunk contains at most 12000 samples. |
+| `commitAudio()` | Commits buffered audio and requests a response. Requires turn detection to be off, through `turnDetection: false` or a native session update. The provider requires at least 100 ms of buffered audio. |
+| `interrupt(position?)` | Stops built-in playback immediately and waits for cancellation and playback-history synchronization. A reply requested but not yet started is cancelled as soon as it starts. Custom players provide `{ itemId, contentIndex, playedMs }`. An idle call resolves immediately. Readiness failures reject the returned Promise with `session_not_ready` or `session_closed`. |
+| `send(event)` | Sends a native OpenAI JSON event. |
+| `on(type, handler)` | Registers a listener and returns an unsubscribe function. Use `'*'` to receive every native and convenience event. |
+| `off(type, handler)` | Removes a listener. |
+| `close()` | Closes the session, rejects pending operations, and releases SDK-owned capture and playback resources. Repeated calls have no additional effect. |
+
+Attach listeners before connecting to receive initial session events. Closing during connection rejects the pending attempt.
+
+If the connection drops because of network loss, a server restart or a provider error, the conversation reconnects on its own. Normal closes with code 1000 end the conversation. While it reconnects, `state` is `connecting`, a `reconnecting` event fires, and pending operations reject with `connection_lost`. The new session gets every setting the provider acknowledged, from the factory options, `configure()` and native `session.update` events. Then `ready` fires again with `reconnected: true`. Listeners, the microphone and the speaker carry over. Microphone audio captured while reconnecting is dropped.
+
+The conversation also restores recent context. Before `ready` fires, it adds back up to 40 of the most recent conversation items, 48 KiB in total. Restored items are user text, user speech that has a transcript, assistant replies as text, and function calls with their outputs. User speech has a transcript only when input transcription is configured through native session settings. An assistant reply that was interrupted, or still playing when the connection dropped, is cut to what the user saw or heard. The cut is estimated from how much of the audio played, so it can be off by a few words. Images, speech without a transcript, deleted items, and replies still generating when the connection dropped are left out. Restored items get new item IDs, don't fire item events, and count as input tokens on the next response. Item IDs from before the reconnect don't work in later events. Restoration uses a contiguous suffix of restorable items. An oversized newest item leaves that suffix empty. Older items left out to fit the window fire a `context_trimmed` event with the count in `omittedItems`; this is routine and not an error. A provider refusal or a failure to send the restored items fires one `error` event with code `context_restore_failed` per restoration. In both cases the conversation stays connected. Items are preserved without truncating text, function arguments or function results.
+
+When Puter knows ahead of time that the server a session runs on will restart, it sends a `puter.reconnect` event, which also reaches your listeners. Without that notice, a restart drops the connection and the conversation reconnects as above. Within a few seconds, the conversation opens a replacement session in the background while the current one keeps working. It switches once no reply is generating or playing, no user turn is being spoken or transcribed, no function call is waiting for its output, and nothing you sent is waiting on the provider. The switch goes through the same steps as a reconnect, and the `reconnecting` event has code 1012. If the replacement can't open yet, the conversation keeps the current session and tries again later. A refusal that retrying can't fix, such as `insufficient_funds`, stops the attempts. If the server closes the session first, the conversation switches to the replacement, or reconnects if none is open.
+
+The conversation makes up to ten attempts over about a minute. In a browser that reports being offline, it first waits up to two minutes for the connection to come back. If every attempt fails, or the server refuses with an error such as `insufficient_funds`, the conversation closes. A closed conversation cannot reconnect. To start another session, prepare a new one.
+
+Native event definitions are listed in the [OpenAI realtime reference](https://developers.openai.com/api/reference/resources/realtime/server-events). Native events retain their provider fields. Sending native events preserves direct control of the session. Puter refuses `conversation.item.retrieve` events and MCP tools (`"type": "mcp"`) in `session.update` and `response.create` events. Sending one fires an `error` event with code `invalid_event`, and the conversation closes with code 1008. Audio helpers expect the session to use PCM16 at 24 kHz.
+
+## Errors and limits
+
+Failures use objects containing `code` and `message`. Preparation can reject with `invalid_argument`, `model_not_found`, `auth_required`, `auth_canceled`, or `auth_failed`. Connection can reject with `subscription_required` or `insufficient_funds`, which also show the Puter upgrade prompt. Connection and asynchronous operations can reject with provider errors, `session_closed`, `connection_lost`, `operation_timeout`, or `operation_in_progress`. Sending before readiness, or while reconnecting, throws `session_not_ready`.
+
+Invalid input throws `invalid_argument`, `invalid_event`, or `input_too_large`. A full SDK send queue throws `queue_full`. Media helpers report `unsupported_environment`, `permission_denied`, `media_error`, `media_timeout`, or `queue_full`. Runtime media errors and `context_restore_failed` arrive through the `error` event. Provider errors also arrive as native `error` events with a nested `error` object.
+
+Each native event is capped at 64 KiB. The SDK bounds JSON traversal, outgoing queues, acknowledgment waits, microphone work, and playback. All numeric limits are listed on [rate limits and quotas](/rate-limits-and-quotas/).
+
+## Convenience events
+
+The conversation emits these events alongside native events.
+
+| Event | Fields |
+| --- | --- |
+| `ready` | `model`, `provider`, and `reconnected: true` after a reconnection |
+| `reconnecting` | `code`, `reason` of the dropped connection. After a `puter.reconnect` event, `code` is 1012. |
+| `context_trimmed` | `omittedItems`, the number of restorable items left out of the restored context after a reconnection. Fires before `ready`. |
+| `text` | `delta`, `responseId` |
+| `transcript` | `role`, `text`, `final`. Assistant deltas use `final: false`. Completed assistant and user transcripts use `final: true`. User transcripts require transcription to be configured through native session settings. |
+| `audio` | `pcm`, `sampleRate`, `responseId`, `itemId`, `contentIndex`. The PCM chunk is an `Int16Array`. |
+| `interrupted` | `source` (`manual` or `speech`), `responseId` |
+| `turn.done` | `responseId`, native provider `usage`, `status` |
+| `close` | `code`, `reason` |
+
+Each event includes its `type`. When the provider event leaves out an ID, `responseId` and `itemId` are empty strings and `contentIndex` is `0`. The `interrupted` event signals local interruption immediately. Its corresponding operation resolves after the provider acknowledges cancellation and any requested truncation. Late audio from a canceled response remains visible as native events and is excluded from convenience audio and built-in playback.
+
+## Browser media
+
+The optional microphone and speaker helpers require a browser with Web Audio support. Microphone capture also requires media permissions and a secure context. Start audio from a user action so the browser can allow playback.
+
+| Member | Behavior |
+| --- | --- |
+| `microphone.start()` | Requests microphone access and streams PCM16, resampled to 24 kHz, in 20 ms chunks through an AudioWorklet. If the page or network falls behind, chunks are dropped rather than stopping capture. |
+| `microphone.mute()` | Disables capture tracks and stops forwarding captured chunks. |
+| `microphone.unmute()` | Enables capture tracks and forwarding. |
+| `microphone.stop()` | Stops capture tracks and releases capture resources. A `start()` still waiting on the permission prompt rejects with `session_closed`. |
+| `speaker.start({ bargeIn: true })` | Starts playback. Barge-in defaults to `true`. With barge-in enabled, provider speech-start events interrupt playback and synchronize played audio with conversation history. Starting the speaker requests no microphone access. |
+| `speaker.stop()` | Clears playback and releases its audio context. |
+
+Both start methods require a connected session. Capture and playback are independent, so custom audio input can use the built-in speaker, and built-in capture can use custom playback.
+
+## Examples
+
+### Have a text conversation
+
+A text conversation uses convenience methods for input and streamed output.
+
+```js
+const conversation = await puter.ai.realtime({
+    output: ['text'],
+    instructions: 'Keep replies short.',
 });
-socket.on('error', console.error);
-socket.on('close', (code, reason) => console.log(code, reason.toString()));
+
+conversation.on('text', ({ delta }) => console.log(delta));
+conversation.on('turn.done', () => conversation.close());
+conversation.on('error', (event) => console.error(event));
+
+await conversation.connect();
+conversation.sendText('Say hello in three words.');
 ```
 
-## Events, audio, and interruption
+### Have a voice conversation
 
-Each message contains one JSON object with a nonempty string `type` of at most 128 characters. Binary messages are rejected. Native events retain their provider fields. The endpoint doesn't deliver `rate_limits.updated`, which describes Puter's provider account rather than yours, and it removes provider organization IDs from error messages. The endpoint exposes the WebSocket event protocol. Your client manages capture, playback, acknowledgments, and timeouts.
+A voice conversation enables the microphone and speaker after connection.
 
-The endpoint refuses `conversation.item.retrieve` events and MCP tools (`"type": "mcp"`) in `session.update` and `response.create` events. A refused event isn't sent to the provider. The session gets an `invalid_event` error and closes with 1008.
+```js
+const conversation = await puter.ai.realtime();
+conversation.on('transcript', ({ role, text }) => console.log(role, text));
+conversation.on('error', (event) => console.error(event));
 
-PCM16 audio configured at 24 kHz mono is sent as base64 chunks in `input_audio_buffer.append` events. Output arrives in `response.output_audio.delta` events. With manual turn detection, commit buffered input with `input_audio_buffer.commit`, then request a reply with `response.create`.
+await conversation.connect();
+await conversation.speaker.start();
+await conversation.microphone.start();
 
-To interrupt, stop local playback immediately and send `response.cancel` with the active `response_id`. If some generated audio was not played, send `conversation.item.truncate` with its `item_id`, `content_index`, and `audio_end_ms` set to the amount actually played. Wait for `response.done` and any requested `conversation.item.truncated` acknowledgment before submitting a replacement turn.
+// To interrupt a response and submit a replacement text turn:
+await conversation.interrupt();
+conversation.sendText('Actually, make it Wednesday.');
 
-Connection loss ends the session. Reconnecting creates a new conversation. Tool execution and automatic reconnection belong to your client.
-
-## Server restarts
-
-When Puter knows ahead of time that the server a session runs on will restart, it sends each open session this event, at most once a minute:
-
-```json
-{
-    "type": "puter.reconnect",
-    "event_id": "event_puter_1767225600000",
-    "reason": "server_restarting",
-    "close_in_ms": 90000
-}
+// When the user ends the conversation:
+conversation.close();
 ```
-
-The `reason` field is `server_restarting`. The `close_in_ms` field, when present, is about how long until the server closes the session itself. The session keeps working until then. Open a new connection after a short, randomized delay, and once it gets `session.created` and your client is idle, with no response generating and no user turn in progress, move to it and close the old one. A connection that reaches a server that is also restarting gets a `server_restarting` error and closes with 1012. In that case keep the old session and try again after a short, randomized delay. If the server closes the old session first, the close code is 1012, and your client reconnects the same way. A restart can also drop the connection without any notice, so treat an unexpected close the same way.
-
-A new connection starts an empty conversation. To keep context, add earlier items back with `conversation.item.create` before you request a response. Event types that start with `puter.` come from Puter, not the provider.
-
-## Errors, billing, and limits
-
-API errors arrive as `{ "type": "error", "error": { "code": "...", "message": "..." } }`. Handle socket errors and close frames too. Invalid, missing, or revoked credentials use `invalid_api_key`. If Puter can't check a credential or the account's plan, the error is `internal_error` and the session closes with 1011, so try again after a short, randomized delay. Other relay codes include `permission_denied`, `model_not_found`, `insufficient_funds`, `subscription_required`, `rate_limit_exceeded`, `invalid_event`, `connection_timeout`, `provider_unavailable`, `upstream_error`, and `server_restarting`.
-
-Policy failures generally close with 1008, oversized client messages with 1009, upstream or setup failures with 1011, server restarts with 1012, and temporary server overload with 1013. Reconnect after 1011, 1012, or 1013. Authentication and model failures can arrive after the WebSocket handshake succeeds.
-
-The endpoint requires a paid Puter plan. Usage is charged after completed responses and input transcriptions. While a response generates, part of your balance is held for it, so a session opens only if your balance covers one response. If the provider connection closes before a response reports its usage, the response is charged the full amount held for it. Each account can open 20 sessions at once by default. Each JSON message you send is limited to 64 KiB, including reassembled fragments. Messages from the provider can be up to 4 MiB. Stream audio in small chunks. All message rates, queue caps, timeouts, and other bounds are published in [rate limits and quotas](/rate-limits-and-quotas/).
-
-Input transcription holds a small amount of your balance per transcribed item, priced at the transcription model you select. Two items are reserved ahead of your audio and replenished as the provider commits them, so a session holds only its spare items plus the items still awaiting a transcript. Changing the transcription model reprices the spare items. If your balance can't cover another item, audio waits while earlier items settle; once none are left to settle, the session closes with `insufficient_funds`. Failed transcriptions, items without final usage, and audio whose commit the provider never acknowledges before the connection closes are each charged that model's fixed per-item amount. Unacknowledged audio is charged one item per started 160 seconds. With server turn detection, only detected speech counts, so silence is never charged. The amounts, timeout and audio limits are listed in [rate limits and quotas](/rate-limits-and-quotas/).
-
-Provider-reported realtime models must have a known price. A missing model uses the last known model. An explicitly unpriced model closes the connection with `upstream_error`.
-
-After recording usage, the connection can continue while settled credit is positive, including a fractional balance. Each new billable operation still needs its full reservation after accounting for other outstanding holds.

src/docs/src/Auth/signIn.md

@@ -6,7 +6,7 @@ platforms: [websites]
 
 Initiates the sign in process for the user.
 
-This will open a popup window with the appropriate authentication method. Puter automatically handles the authentication process and will resolve the promise when the user has signed in.
+This will open a popup window with the appropriate authentication method. Puter automatically handles the authentication process and will resolve the promise when the user has signed in. Puter's own apps on puter.com subdomains show the sign-in in a frame over the page instead, and open the popup when the user picks a sign-in provider such as Google.
 
 It is important to note that all essential methods in Puter handle authentication automatically. This method is only necessary if you want to handle authentication manually, for example if you want to build your own custom authentication flow.
 

src/docs/src/UI/showFeedbackDialog.md

@@ -8,7 +8,7 @@ Opens a dialog where the user can send you, the app's developer, feedback about
 
 The message is delivered by Puter: it is stored and emailed to the email address on your Puter account. The feedback never passes through your app's code, and the dialog tells the user what is shared with you: their username, plus their email address (as the email's reply-to, so you can respond) when their email is verified.
 
-Inside Puter, the dialog is rendered by the desktop environment. On a website, a puter.com popup hosts the dialog (signing the user in first if needed).
+Inside Puter, the dialog is rendered by the desktop environment. On a website, a puter.com popup hosts the dialog (signing the user in first if needed). Puter's own apps on puter.com subdomains show it in a frame over the page instead, when the user is signed in to both.
 
 **Feedback is opt-in.** Users can only send feedback if it's enabled for your app. Apps created in the Dev Center have feedback enabled at creation — you can turn it off with the "User Feedback" toggle in the app's settings. Apps created through `puter.apps.create` default to off; enable it by setting `feedbackEnabled`:
 

src/docs/src/rate-limits-and-quotas.md

@@ -91,7 +91,7 @@ Gemini speech-to-text first counts the audio's tokens, which times out after 30
 
 The OpenAI- and Anthropic-compatible endpoints (`/puterai/openai/v1/*`, `/puterai/anthropic/v1/messages`) require a paid plan; a free account gets `402 subscription_required`. The same models are available to every account through `puter.ai.*` and `/drivers/call`, and the model catalogue endpoints are open to everyone.
 
-Realtime sessions ([`puter.ai.convo()`](/AI/convo/), `/puterai/openai/v1/realtime`) require a paid plan, like the other OpenAI-compatible endpoints, and are capped at 20 open at once per account. An account without a plan gets an `error` event with code `subscription_required`. A session over the cap gets `rate_limit_exceeded`. Both close with 1008.
+Realtime sessions ([`puter.ai.realtime()`](/AI/realtime/), `/puterai/openai/v1/realtime`) require a paid plan, like the other OpenAI-compatible endpoints, and are capped at 20 open at once per account. An account without a plan gets an `error` event with code `subscription_required`. A session over the cap gets `rate_limit_exceeded`. Both close with 1008.
 
 | Realtime transport limit | Value | Behavior at the limit |
 | --- | --- | --- |
@@ -131,7 +131,7 @@ Realtime sessions ([`puter.ai.convo()`](/AI/convo/), `/puterai/openai/v1/realtim
 
 Send audio as a stream of small chunks. The message cap applies to text, configuration, tool output, and audio alike.
 
-The [`puter.ai.convo()`](/AI/convo/) SDK also applies these limits before sending or retaining data.
+The [`puter.ai.realtime()`](/AI/realtime/) SDK also applies these limits before sending or retaining data.
 
 | Conversation SDK limit | Value | Behavior at the limit |
 | --- | --- | --- |

src/docs/src/sidebar.js

@@ -124,17 +124,17 @@ let sidebar = [
                 path: '/AI/speech2speech',
             },
             {
-                title: '<code>convo()</code>',
-                page_title: '<code>puter.ai.convo()</code>',
-                title_tag: 'puter.ai.convo()',
+                title: '<code>realtime()</code>',
+                page_title: '<code>puter.ai.realtime()</code>',
+                title_tag: 'puter.ai.realtime()',
                 icon: '/assets/img/function.svg',
-                source: '/AI/convo.md',
-                path: '/AI/convo',
+                source: '/AI/realtime.md',
+                path: '/AI/realtime',
             },
             {
                 title: 'Realtime WebSocket API (Beta)',
-                source: '/AI/realtime.md',
-                path: '/AI/realtime',
+                source: '/AI/realtime-websocket.md',
+                path: '/AI/realtime-websocket',
             },
             {
                 title: '<code>listModels()</code>',

src/gui/src/UI/Auth/UIAuthAccountPicker.js

@@ -84,7 +84,8 @@ export function pushAccountPickerScreen (flow) {
     const accounts = Array.isArray(window.logged_in_users) ? window.logged_in_users : [];
 
     let h = '<div class="dashboard-dialog-body auth-body">';
-    h += authHeadHtml(flow, i18n('sign_in_with_puter', [], false));
+    // Everyone here has signed in to Puter before; no need to explain it.
+    h += authHeadHtml(flow, i18n('sign_in_with_puter', [], false), { openerNotice: false });
     h += `<ul class="auth-accounts" aria-label="${i18n('sign_in_with_puter')}">`;
     h += accounts.map(accountRowHtml).join('');
     h += '</ul>';

src/gui/src/UI/Auth/UIAuthLogin.js

@@ -104,7 +104,8 @@ export function pushLoginScreen (flow, options = {}) {
     const id = `auth-login-${window.uuidv4?.() ?? Date.now()}`;
 
     let h = '<div class="dashboard-dialog-body auth-body">';
-    h += authHeadHtml(flow, i18n('log_in', [], false));
+    // Logging in means already having a Puter account; no need to explain it.
+    h += authHeadHtml(flow, i18n('log_in', [], false), { openerNotice: false });
     h += '<form class="auth-form login-form" novalidate>';
     h += '<div class="dashboard-form-status" role="status" aria-live="polite"></div>';
     h += formFieldHtml({
@@ -152,6 +153,7 @@ export function pushLoginScreen (flow, options = {}) {
 
     renderProviderButtons($screen.find('.auth-provider-list'), {
         kind: 'login',
+        flow,
         referrer: () => flow.options.referrer ?? window.referrerStr ?? window.openerOrigin,
     }).then((offered) => {
         if ( offered ) $screen.find('.auth-providers').prop('hidden', false);

src/gui/src/UI/Auth/UIAuthLogin.test.js

@@ -60,6 +60,14 @@ afterEach(() => {
 });
 
 describe('login screen', () => {
+    it('leaves out the opener notice in a sign-in popup', () => {
+        window.embedded_in_popup = true;
+        window.openerOrigin = 'https://builder.puter.com';
+        void UIAuthLogin({ reload_on_success: false });
+        expect(screen().find('.auth-title')).toHaveLength(1);
+        expect(screen().find('.auth-opener-notice')).toHaveLength(0);
+    });
+
     it('asks for each field before sending anything', () => {
         const calls = captureAjax();
         void UIAuthLogin({ reload_on_success: false });
@@ -217,6 +225,29 @@ describe('OIDC buttons on the login and signup screens', () => {
         window.location = original;
         expect(assign.mock.calls[0][0]).toBe('https://puter.test/auth/oidc/google/start?flow=login&referrer=ref');
     });
+
+    it('hands a framed sign-in to the popup instead of leaving for the provider', async () => {
+        asPopup('msg_id=1');
+        window.embedded_in_frame = true;
+        window.tell_popup_frame = vi.fn();
+        try {
+            void UIAuthLogin();
+            await vi.waitFor(() => expect($('.oidc-google-btn')).toHaveLength(1));
+            const href = window.location.href;
+            $('.oidc-google-btn').trigger('click');
+            expect(window.tell_popup_frame.mock.calls).toEqual([
+                ['provider', { url: expect.stringContaining('https://puter.test/auth/oidc/google/start?flow=login') }],
+                ['unavailable'],
+            ]);
+            const start = new URL(window.tell_popup_frame.mock.calls[0][1].url);
+            expect(start.searchParams.get('embedded_in_popup')).toBe('true');
+            expect(start.searchParams.get('msg_id')).toBe('1');
+            expect(window.location.href).toBe(href);
+        } finally {
+            delete window.embedded_in_frame;
+            delete window.tell_popup_frame;
+        }
+    });
 });
 
 describe('second factor', () => {

src/gui/src/UI/Auth/UIAuthSignup.js

@@ -36,11 +36,13 @@ import openAuthFlow, {
     submitButtonHtml,
     wireAuthHead,
 } from './authFlow.js';
-import { renderProviderButtons } from './authProviders.js';
+import { mayOfferProviders, renderProviderButtons } from './authProviders.js';
 import { pushLoginScreen } from './UIAuthLogin.js';
 
 const SIGNUP_TIMEOUT_MS = 30000;
 const TURNSTILE_POLL_MS = 100;
+// How long the email form waits for the provider lookup before showing anyway.
+const PROVIDERS_WAIT_MS = 1500;
 
 /**
  * @typedef {object} SignupScreenOptions
@@ -187,6 +189,9 @@ export const signupRedirectUrl = (redirect_url) => {
 export function pushSignupScreen (flow, options = {}) {
     const id = `auth-signup-${window.uuidv4?.() ?? Date.now()}`;
     const turnstile_key = window.gui_params?.turnstileSiteKey;
+    // The email form stays hidden until the providers are known, so it
+    // doesn't show and then fold away behind "Sign up with email".
+    let awaiting_providers = mayOfferProviders() && ! options.username && ! options.email;
 
     let h = '<div class="dashboard-dialog-body auth-body">';
     h += authHeadHtml(flow, i18n('create_free_account', [], false));
@@ -200,7 +205,7 @@ export function pushSignupScreen (flow, options = {}) {
     h += '<div class="signup-with-email-wrapper" hidden>';
     h += `<button type="button" class="dashboard-dialog-btn auth-provider-btn signup-with-email-btn">${i18n('sign_up_with_email')}</button>`;
     h += '</div>';
-    h += '<form class="auth-form signup-form" novalidate>';
+    h += `<form class="auth-form signup-form" novalidate${awaiting_providers ? ' hidden' : ''}>`;
     h += formFieldHtml({
         name: 'username',
         label: i18n('username'),
@@ -307,11 +312,32 @@ export function pushSignupScreen (flow, options = {}) {
         })();
     }
 
+    // With focus on the card itself, nothing on the screen was focusable yet.
+    const focusWasParked = () => document.activeElement === flow.$dialog.get(0);
+    const stopAwaitingProviders = () => {
+        const was_awaiting = awaiting_providers;
+        awaiting_providers = false;
+        clearTimeout(form_fallback);
+        return was_awaiting;
+    };
+    const revealForm = () => {
+        if ( ! stopAwaitingProviders() || flow.isClosed() ) return;
+        showForm();
+        if ( focusWasParked() ) flow.focus();
+    };
+    const form_fallback = awaiting_providers ? setTimeout(revealForm, PROVIDERS_WAIT_MS) : undefined;
+
     renderProviderButtons($screen.find('.auth-provider-list'), {
         kind: 'signup',
+        flow,
         referrer: () => flow.options.referrer ?? window.referrerStr,
     }).then((offered) => {
-        if ( ! offered || flow.isClosed() ) return;
+        if ( ! offered ) {
+            revealForm();
+            return;
+        }
+        stopAwaitingProviders();
+        if ( flow.isClosed() ) return;
         offers_providers = true;
         $screen.find('.oidc-providers-wrapper').prop('hidden', false);
         if ( offered.signupOidcOnly ) {
@@ -327,7 +353,7 @@ export function pushSignupScreen (flow, options = {}) {
         const had_focus = $form.get(0).contains(document.activeElement);
         $form.prop('hidden', true);
         $screen.find('.signup-with-email-wrapper').prop('hidden', false);
-        if ( had_focus ) flow.focus();
+        if ( had_focus || focusWasParked() ) flow.focus();
     });
 
     $screen.find('.signup-with-email-btn').on('click', () => {

src/gui/src/UI/Auth/UIAuthSignup.test.js

@@ -29,6 +29,7 @@ const { activeAuthFlow } = await import('./authFlow.js');
 const { default: UIAuthSignup, signupRedirectUrl } = await import('./UIAuthSignup.js');
 const { default: UIAuthAccountPicker } = await import('./UIAuthAccountPicker.js');
 const { default: UIAuthRecoverPassword } = await import('./UIAuthRecoverPassword.js');
+const { default: UIAuthLogin } = await import('./UIAuthLogin.js');
 
 const providers = (body) => {
     globalThis.fetch = vi.fn(async () => reply(200, body));
@@ -110,7 +111,12 @@ describe('signup when only OIDC signups are open', () => {
         globalThis.fetch = vi.fn(() => new Promise((resolve) => {
             answer = resolve;
         }));
+        vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
         void UIAuthSignup();
+        // A slow lookup gives up the wait and shows the form.
+        vi.advanceTimersByTime(1500);
+        vi.useRealTimers();
+        expect($('.signup-form').prop('hidden')).toBe(false);
         $('[name="username"]').val('started');
         answer(reply(200, { providers: ['google'] }));
         await vi.waitFor(() => expect($('.oidc-google-btn')).toHaveLength(1));
@@ -118,6 +124,50 @@ describe('signup when only OIDC signups are open', () => {
     });
 });
 
+describe('signup while the providers are looked up', () => {
+    /** Lets promise callbacks run, but no timer, so nothing a paint could show in between. */
+    const settlePromises = async () => {
+        for ( let i = 0; i < 10; i++ ) await Promise.resolve();
+    };
+
+    it('keeps the email form hidden until the providers are known', async () => {
+        let answer;
+        globalThis.fetch = vi.fn(() => new Promise((resolve) => {
+            answer = resolve;
+        }));
+        void UIAuthSignup();
+        expect($('.signup-form').prop('hidden')).toBe(true);
+        answer(reply(200, { providers: ['google'] }));
+        await vi.waitFor(() => expect($('.oidc-google-btn')).toHaveLength(1));
+        expect($('.signup-form').prop('hidden')).toBe(true);
+        expect($('.signup-with-email-wrapper').prop('hidden')).toBe(false);
+    });
+
+    it('shows the email form when no providers are offered', async () => {
+        void UIAuthSignup();
+        await vi.waitFor(() => expect($('.signup-form').prop('hidden')).toBe(false));
+        expect($('.signup-with-email-wrapper').prop('hidden')).toBe(true);
+    });
+
+    it('shows a prefilled email form straight away', () => {
+        globalThis.fetch = vi.fn(() => new Promise(() => {}));
+        void UIAuthSignup({ email: '[email protected]' });
+        expect($('.signup-form').prop('hidden')).toBe(false);
+    });
+
+    it('reuses the login screen\'s lookup, drawing the providers before any paint', async () => {
+        providers({ providers: ['google'], signupOidcOnly: false });
+        void UIAuthLogin({ reload_on_success: false });
+        await vi.waitFor(() => expect(screen().find('.oidc-google-btn')).toHaveLength(1));
+        screen().find('.auth-to-signup').trigger('click');
+        await settlePromises();
+        expect(screen().attr('data-screen')).toBe('signup');
+        expect(screen().find('.oidc-google-btn')).toHaveLength(1);
+        expect(screen().find('.signup-with-email-wrapper').prop('hidden')).toBe(false);
+        expect(fetch).toHaveBeenCalledOnce();
+    });
+});
+
 describe('signup form', () => {
     it.each([
         [{}, 'username_required', 'username'],

src/gui/src/UI/Auth/authFlow.js

@@ -191,9 +191,15 @@ export default function openAuthFlow ({ page = false, dismissable = ! page, clos
     /** @type {Array<AuthScreen & { $el: jQuery, el_return?: Element | null }>} */
     const stack = [];
 
+    // A frame's focus() calls do nothing until the framing page focuses it,
+    // so the screen takes focus then, unless something already has it.
+    const onFrameFocus = () => {
+        if ( ! document.activeElement || document.activeElement === document.body ) flow.focus();
+    };
     const teardown = () => {
         if ( torn_down ) return;
         torn_down = true;
+        window.removeEventListener('focus', onFrameFocus);
         if ( active_flow === flow ) active_flow = null;
         // Screens waiting on the user (the second factor) hear they won't get an answer.
         while ( stack.length ) stack.pop().onLeave?.();
@@ -352,8 +358,14 @@ export default function openAuthFlow ({ page = false, dismissable = ! page, clos
     $overlay.on('keydown keyup keypress', function (e) {
         e.stopPropagation();
         if ( e.type !== 'keydown' || e.key !== 'Escape' ) return;
+        // An Escape that cancels an IME conversion is the IME's; jQuery's
+        // event doesn't carry isComposing, the browser's does.
+        if ( e.originalEvent?.isComposing || e.keyCode === 229 ) return;
         e.preventDefault();
-        if ( dismissable && ! busy ) $dialog.find('.dashboard-dialog-close').trigger('click');
+        if ( busy ) return;
+        if ( dismissable ) $dialog.find('.dashboard-dialog-close').trigger('click');
+        // A framed sign-in's ✕ is the framing page's, which close() asks.
+        else if ( window.embedded_in_frame ) window.close();
     });
     // A press on the backdrop (or a page's background) would move focus to
     // the page, and with it the keys; it stays where it was.
@@ -361,6 +373,8 @@ export default function openAuthFlow ({ page = false, dismissable = ! page, clos
         if ( e.target === this ) e.preventDefault();
     });
 
+    if ( window.embedded_in_frame ) window.addEventListener('focus', onFrameFocus);
+
     active_flow = flow;
     return flow;
 }
@@ -387,9 +401,12 @@ export const joinAuthFlow = () => {
  *
  * @param {AuthFlow} flow
  * @param {string} title Plain text.
+ * @param {{ openerNotice?: boolean }} [opts] `openerNotice: false` leaves out
+ *   the line explaining that the site uses Puter, for screens shown to someone
+ *   who already has an account here.
  * @returns {string}
  */
-export const authHeadHtml = (flow, title) => {
+export const authHeadHtml = (flow, title, { openerNotice = true } = {}) => {
     const opener = window.embedded_in_popup && isAttestedOrigin(window.openerOrigin) ? window.openerOrigin : '';
     let h = '<div class="auth-head">';
     h += authLogoHeader({
@@ -399,7 +416,7 @@ export const authHeadHtml = (flow, title) => {
         openerFallbackSrc: window.icons['website.svg'],
     });
     h += `<h1 class="auth-title">${html_encode(title)}</h1>`;
-    if ( opener ) {
+    if ( opener && openerNotice ) {
         h += `<p class="auth-opener-notice">${i18n('popup_opener_uses_puter', [new URL(opener).hostname])}</p>`;
     }
     h += '</div>';

src/gui/src/UI/Auth/authFlow.test.js

@@ -75,6 +75,56 @@ describe('openAuthFlow', () => {
         expect(flow.isClosed()).toBe(false);
     });
 
+    it('lets Escape ask the framing page to close a framed sign-in, unless busy', async () => {
+        window.embedded_in_frame = true;
+        const close = vi.spyOn(window, 'close').mockImplementation(() => {});
+        try {
+            const flow = openAuthFlow({ page: true });
+            flow.push({ name: 'a', html: '<input>' });
+            await tick();
+            flow.setBusy(true);
+            key($('.auth-dialog input').get(0), 'Escape');
+            expect(close).not.toHaveBeenCalled();
+            flow.setBusy(false);
+            // Escape that cancels an IME conversion is the IME's.
+            $('.auth-dialog input').get(0).dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', isComposing: true, bubbles: true }));
+            expect(close).not.toHaveBeenCalled();
+            key($('.auth-dialog input').get(0), 'Escape');
+            expect(close).toHaveBeenCalledTimes(1);
+            flow.finish(false);
+        } finally {
+            close.mockRestore();
+            delete window.embedded_in_frame;
+        }
+    });
+
+    it('focuses a framed screen once the framing page focuses the frame', async () => {
+        window.embedded_in_frame = true;
+        try {
+            const flow = openAuthFlow({ page: true });
+            flow.push({ name: 'a', html: '<input>' });
+            // What a frame's focus() amounts to before the page focuses it.
+            document.activeElement.blur();
+            window.dispatchEvent(new FocusEvent('focus'));
+            // jsdom lays nothing out, so the screen's fallback, the card, takes it.
+            expect($('.auth-dialog').get(0).contains(document.activeElement)).toBe(true);
+
+            // Focus the user moved elsewhere stays there.
+            const el_outside = $('<button class="outside">').appendTo('body').get(0);
+            el_outside.focus();
+            window.dispatchEvent(new FocusEvent('focus'));
+            expect(document.activeElement).toBe(el_outside);
+            el_outside.remove();
+
+            flow.finish(false);
+            document.activeElement.blur();
+            window.dispatchEvent(new FocusEvent('focus'));
+            expect(document.activeElement).toBe(document.body);
+        } finally {
+            delete window.embedded_in_frame;
+        }
+    });
+
     it('ignores the backdrop unless asked, so a stray click keeps typed credentials', async () => {
         const kept = openAuthFlow();
         kept.push({ name: 'a', html: '' });
@@ -250,6 +300,16 @@ describe('authHeadHtml', () => {
         expect($dialog_head.find('a')).toHaveLength(0);
         expect($dialog_head.find('.auth-logo').attr('alt')).toBe('');
     });
+
+    it('explains the opener in a sign-in popup unless told not to', () => {
+        window.embedded_in_popup = true;
+        window.openerOrigin = 'https://builder.puter.com';
+        const flow = openAuthFlow();
+        const $notice = $(authHeadHtml(flow, 'Log in')).find('.auth-opener-notice');
+        expect($notice).toHaveLength(1);
+        expect($notice.text()).toContain('builder.puter.com');
+        expect($(authHeadHtml(flow, 'Log in', { openerNotice: false })).find('.auth-opener-notice')).toHaveLength(0);
+    });
 });
 
 describe('authFlowOptions', () => {

src/gui/src/UI/Auth/authProviders.js

@@ -75,27 +75,46 @@ export const providerStartUrl = (provider, kind, referrer) => {
     return url;
 };
 
+/** @type {WeakMap<import('./authFlow.js').AuthFlow, Promise<{ providers?: string[], signupOidcOnly?: boolean } | null>>} */
+const lookups = new WeakMap();
+
 /**
- * Fetches the configured providers and fills `$list` with a button for each.
- * A self-hosted instance's own provider gets a generic button.
+ * The configured providers, looked up once per auth flow so moving between
+ * its screens draws them straight away instead of after another round trip.
+ *
+ * @param {import('./authFlow.js').AuthFlow} flow
+ */
+const lookUpProviders = (flow) => {
+    let lookup = lookups.get(flow);
+    if ( ! lookup ) {
+        lookup = (async () => {
+            try {
+                const res = await fetch(`${window.api_origin}/auth/oidc/providers`);
+                return res.ok ? await res.json() : null;
+            } catch {
+                return null;
+            }
+        })();
+        lookups.set(flow, lookup);
+    }
+    return lookup;
+};
+
+/**
+ * Fills `$list` with a button for each configured provider. A self-hosted
+ * instance's own provider gets a generic button.
  *
  * @param {jQuery} $list Where the buttons go.
  * @param {object} opts
  * @param {'login'|'signup'} opts.kind
  * @param {() => string | undefined} opts.referrer Read when a button is pressed.
+ * @param {import('./authFlow.js').AuthFlow} opts.flow The flow showing `$list`.
  * @returns {Promise<{ providers: string[], signupOidcOnly: boolean } | null>}
  *   Null when none are offered here or the lookup failed.
  */
-export async function renderProviderButtons ($list, { kind, referrer }) {
+export async function renderProviderButtons ($list, { kind, referrer, flow }) {
     if ( ! mayOfferProviders() ) return null;
-    let data;
-    try {
-        const res = await fetch(`${window.api_origin}/auth/oidc/providers`);
-        if ( ! res.ok ) return null;
-        data = await res.json();
-    } catch {
-        return null;
-    }
+    const data = await lookUpProviders(flow);
     if ( ! Array.isArray(data?.providers) || ! data.providers.length ) return null;
 
     const ordered = [
@@ -115,7 +134,15 @@ export async function renderProviderButtons ($list, { kind, referrer }) {
     }
     $list.html(h);
     $list.on('click', '.auth-provider-btn', function () {
-        window.location.href = providerStartUrl($(this).attr('data-provider'), kind, referrer());
+        const url = providerStartUrl($(this).attr('data-provider'), kind, referrer());
+        // A provider won't load in a frame, so the framing page opens this
+        // in a popup instead. `unavailable` covers an SDK that can't.
+        if ( window.embedded_in_frame ) {
+            window.tell_popup_frame('provider', { url });
+            window.tell_popup_frame('unavailable');
+            return;
+        }
+        window.location.href = url;
     });
     return { providers: ordered, signupOidcOnly: data.signupOidcOnly === true };
 }

src/gui/src/UI/Dashboard/AppBrowser.browser.test.js

@@ -16,6 +16,8 @@ const requests = [];
 const guiRoot = fileURLToPath(new URL('../../../', import.meta.url));
 const sessionToken = 'app-browser-test-session';
 const sessionCookie = 'app-browser-test-cookie';
+const sessionUser = '0b1c9a52-3f0e-4c7a-9a65-2f6d1e8b7c40';
+const otherUser = '7d2e4f10-8a3b-4c5d-9e6f-0a1b2c3d4e5f';
 const appRows = Array.from({ length: 105 }, (_, i) => ({
     name: `app-${i}`, title: `App ${i}`, icon: null,
 }));
@@ -62,6 +64,25 @@ beforeAll(async () => {
         if ( ! req.headers.cookie?.includes(`puter_auth_token=${sessionCookie}`) ) return res.sendStatus(401);
         res.json({ token: sessionToken });
     });
+    // The GUI session's token and the tokens of apps signed in on a sibling subdomain.
+    const whoamiByToken = {
+        [sessionToken]: { uuid: sessionUser, username: 'session-user' },
+        'app-token-session-user': { uuid: sessionUser, username: 'session-user' },
+        'app-token-other-user': { uuid: otherUser, username: 'other-user' },
+    };
+    // The SDK on a sibling subdomain sends credentialed cross-origin requests.
+    app.use(['/whoami', '/profile', '/rao'], (req, res, next) => {
+        if ( req.headers.origin ) res.set('Access-Control-Allow-Origin', req.headers.origin);
+        res.set('Access-Control-Allow-Credentials', 'true');
+        res.set('Access-Control-Allow-Headers', 'Authorization, Content-Type');
+        if ( req.method === 'OPTIONS' ) return res.sendStatus(204);
+        next();
+    });
+    app.get('/whoami', (req, res) => {
+        const user = whoamiByToken[req.headers.authorization?.replace(/^Bearer /, '')];
+        if ( ! user ) return res.sendStatus(401);
+        res.json(user);
+    });
     app.get('/get-launch-apps', (_req, res) => res.json({ recommended: [{ name: 'removed', title: 'Removed' }] }));
     app.get('/cache/last-change-timestamp', (_req, res) => res.json({ timestamp: 0 }));
     app.post('/drivers/call', (req, res) => {
@@ -81,9 +102,15 @@ beforeAll(async () => {
     app.get('/index', (_req, res) => res.send(`<title>App</title>
         <script>window.PUTER_ORIGIN = '${origin}'; window.PUTER_API_ORIGIN = '${origin}';</script>
         <script src="/sdk.js"></script>`));
-    app.get('/host', (_req, res) => res.send(`<!DOCTYPE html><html><body style="margin:0">
-        <iframe title="More apps" src="${origin}/embed/apps" style="border:0;width:100vw;height:100vh"></iframe>
+    // The host page names its signed-in user as `?user=`, as puter.js does in the fragment.
+    app.get('/host', (req, res) => res.send(`<!DOCTYPE html><html><body style="margin:0">
+        <iframe title="More apps" src="${origin}/embed/apps${req.query.user ? `#user=${req.query.user}` : ''}" style="border:0;width:100vw;height:100vh"></iframe>
     </body></html>`));
+    // An app on a sibling subdomain, signed in with puter.js, with the SDK's user menu.
+    app.get('/menu-host', (_req, res) => res.send(`<!DOCTYPE html><html><head>
+        <script>window.PUTER_ORIGIN = '${origin}'; window.PUTER_API_ORIGIN = '${origin}';</script>
+        <script src="${origin}/sdk.js"></script></head>
+        <body><header><puter-user-menu></puter-user-menu></header></body></html>`));
     app.get('/embed/apps', (_req, res) => {
         res.setHeader('Content-Security-Policy', `frame-ancestors 'self' http://*.puter.localhost:${port}`);
         res.send(`<!DOCTYPE html><html><head><meta name="viewport" content="width=device-width, initial-scale=1">
@@ -122,7 +149,7 @@ describe('embedded app browser', () => {
             page.on('pageerror', error => errors.push(error.message));
             requests.length = 0;
             try {
-                const parentUrl = `http://spreadsheet.puter.localhost:${port}/host`;
+                const parentUrl = `http://spreadsheet.puter.localhost:${port}/host?user=${sessionUser}`;
                 await page.goto(parentUrl);
                 const frame = page.frameLocator('iframe');
                 await frame.locator('.myapps-group-tile').waitFor();
@@ -182,7 +209,7 @@ describe('embedded app browser', () => {
         try {
             const page = await context.newPage();
             page.setDefaultTimeout(6000);
-            await page.goto(`http://spreadsheet.puter.localhost:${port}/host`);
+            await page.goto(`http://spreadsheet.puter.localhost:${port}/host?user=${sessionUser}`);
             const frame = page.frameLocator('iframe');
             await frame.locator('.myapps-group-tile').waitFor();
             expect(await frame.locator('[data-app-name="app-104"]').count()).toBe(1);
@@ -200,7 +227,7 @@ describe('embedded app browser', () => {
         try {
             const page = await context.newPage();
             page.setDefaultTimeout(6000);
-            await page.goto(`${origin}/embed/apps`);
+            await page.goto(`${origin}/embed/apps#user=${sessionUser}`);
             await page.locator('.myapps-search').fill('App 104');
             const popupPromise = context.waitForEvent('page');
             await page.locator('.myapps-tile').click();
@@ -275,7 +302,7 @@ describe('embedded app browser', () => {
             });
             const page = await context.newPage();
             page.setDefaultTimeout(6000);
-            await page.goto(`${origin}/embed/apps`);
+            await page.goto(`${origin}/embed/apps#user=${sessionUser}`);
             await page.locator('[data-app-name="notes"]').waitFor();
         } finally {
             guestApps = [];
@@ -290,7 +317,7 @@ describe('embedded app browser', () => {
             const page = await context.newPage();
             page.setDefaultTimeout(6000);
             await page.route('**/get-gui-token', route => route.fulfill({ status }));
-            await page.goto(`${origin}/embed/apps`);
+            await page.goto(`${origin}/embed/apps#user=${sessionUser}`);
             await page.getByRole('status').waitFor();
             expect(await page.getByRole('status').textContent()).toContain('Apps are unavailable');
             expect(await page.locator('.myapps-tile').count()).toBe(0);
@@ -300,6 +327,351 @@ describe('embedded app browser', () => {
         }
     });
 
+    describe('only shows the session to the host\'s own user', () => {
+        const notes = () => ({ name: 'notes', title: 'Notes', uuid: 'uid-notes', index_url: `http://notes.puter.localhost:${port}/index`, icon: null });
+        const signedInContext = () => browser.newContext({ storageState: {
+            cookies: [], origins: [{ origin, localStorage: [{ name: 'auth_token_v2', value: sessionToken }] }],
+        } });
+
+        it.each([
+            ['names no user', ''],
+            ['names another user', `?user=${otherUser}`],
+            ['names a malformed user', '?user=session-user'],
+        ])('shows the signed-out list when the host %s', async (_label, query) => {
+            guestApps = [notes()];
+            const context = await signedInContext();
+            requests.length = 0;
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/host${query}`);
+                const frame = page.frameLocator('iframe');
+                await frame.locator('[data-app-name="notes"]').waitFor();
+                expect(await frame.locator('.myapps-tile').count()).toBe(1);
+                expect(requests.some(req => ['/sdk.js', '/installedApps', '/drivers/call'].includes(req.path))).toBe(false);
+
+                const popupPromise = context.waitForEvent('page');
+                await frame.locator('[data-app-name="notes"]').click();
+                const popup = await popupPromise;
+                await popup.waitForURL(/\/index\?/);
+                expect(await popup.evaluate(() => window.opener)).toBeNull();
+                expect(requests.some(req => ['/auth/get-user-app-token', '/rao'].includes(req.path))).toBe(false);
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('shows the signed-out list when the API refuses the stored session', async () => {
+            guestApps = [notes()];
+            const context = await browser.newContext({ storageState: {
+                cookies: [], origins: [{ origin, localStorage: [{ name: 'auth_token_v2', value: 'revoked-session' }] }],
+            } });
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`${origin}/embed/apps#user=${sessionUser}`);
+                await page.locator('[data-app-name="notes"]').waitFor();
+                expect(await page.locator('.myapps-tile').count()).toBe(1);
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('shows a spinner while it checks the session', async () => {
+            const context = await signedInContext();
+            let respond;
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.route('**/whoami', route => { respond = () => route.continue(); });
+                await page.goto(`${origin}/embed/apps#user=${sessionUser}`);
+                await expect.poll(() => typeof respond).toBe('function');
+                const spinner = () => page.locator('#app-browser').evaluate(root => getComputedStyle(root, '::after').animationName);
+                expect(await spinner()).not.toBe('none');
+                await respond();
+                await page.locator('[data-app-name="app-104"]').waitFor();
+                expect(await spinner()).toBe('none');
+            } finally {
+                await context.close();
+            }
+        });
+
+        it('shows an unavailable state when the session check fails', async () => {
+            guestApps = [notes()];
+            const context = await signedInContext();
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.route('**/whoami', route => route.fulfill({ status: 503 }));
+                await page.goto(`${origin}/embed/apps#user=${sessionUser}`);
+                await page.getByRole('status').waitFor();
+                expect(await page.getByRole('status').textContent()).toContain('Apps are unavailable');
+                expect(await page.locator('.myapps-tile').count()).toBe(0);
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('reloads for the user a changed fragment names', async () => {
+            guestApps = [notes()];
+            const context = await signedInContext();
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`${origin}/embed/apps#user=${sessionUser}`);
+                await page.locator('[data-app-name="app-104"]').waitFor();
+                await page.evaluate(user => { window.location.hash = `user=${user}`; }, otherUser);
+                await page.locator('[data-app-name="notes"]').waitFor();
+                expect(await page.locator('[data-app-name="app-104"]').count()).toBe(0);
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+    });
+
+    describe('opened from the SDK\'s user menu', () => {
+        const menuContext = async (appToken, options = {}) => {
+            guestApps = [{ name: 'notes', title: 'Notes', uuid: 'uid-notes', index_url: `http://notes.puter.localhost:${port}/index`, icon: null }];
+            const host = `http://spreadsheet.puter.localhost:${port}`;
+            return browser.newContext({ ...options, storageState: {
+                cookies: [],
+                origins: [
+                    { origin, localStorage: [{ name: 'auth_token_v2', value: sessionToken }] },
+                    { origin: host, localStorage: appToken ? [
+                        { name: 'puter.auth.token.v2', value: appToken },
+                        { name: 'puter.auth.token.origin.v2', value: origin },
+                    ] : [] },
+                ],
+            } });
+        };
+
+        it('shows the user\'s apps to the same user and the signed-out list once the app signs out', async () => {
+            const context = await menuContext('app-token-session-user');
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                const errors = [];
+                page.on('pageerror', error => errors.push(error.message));
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                await page.locator('puter-user-menu .avatar').waitFor();
+                expect(await page.locator('puter-user-menu .avatar').textContent()).toBe('S');
+
+                await page.locator('puter-user-menu .apps-button').click();
+                const iframe = page.locator('puter-user-menu iframe');
+                expect(await iframe.getAttribute('src')).toBe(`${origin}/embed/apps#user=${sessionUser}`);
+                await page.frameLocator('puter-user-menu iframe').locator('[data-app-name="app-104"]').waitFor();
+
+                // The panel hangs under its button, inside the viewport.
+                const button = await page.locator('puter-user-menu .apps-button').boundingBox();
+                const panel = await page.locator('puter-user-menu .apps-panel').boundingBox();
+                const viewport = page.viewportSize();
+                expect(panel.y).toBeGreaterThan(button.y + button.height);
+                expect(panel.x).toBeGreaterThanOrEqual(0);
+                expect(panel.x + panel.width).toBeLessThanOrEqual(viewport.width);
+
+                // Closing keeps the embed, so reopening shows the same page.
+                const embed = page.frames().find(frame => frame.url().startsWith(`${origin}/embed/apps`));
+                await embed.evaluate(() => { window.keptAcrossOpens = true; });
+                await page.locator('puter-user-menu .apps-close').click();
+                await page.locator('puter-user-menu .apps-panel').waitFor({ state: 'hidden' });
+                await page.locator('puter-user-menu .apps-button').click();
+                expect(await embed.evaluate(() => window.keptAcrossOpens)).toBe(true);
+
+                await page.evaluate(() => puter.auth.signOut());
+                await iframe.waitFor({ state: 'detached' });
+                await page.locator('puter-user-menu .sign-in').waitFor();
+                await page.locator('puter-user-menu .apps-button').click();
+                expect(await iframe.getAttribute('src')).toBe(`${origin}/embed/apps`);
+                const frame = page.frameLocator('puter-user-menu iframe');
+                await frame.locator('[data-app-name="notes"]').waitFor();
+                expect(await frame.locator('[data-app-name="app-104"]').count()).toBe(0);
+                expect(errors).toEqual([]);
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('shows the signed-out list to an app signed in as another user', async () => {
+            const context = await menuContext('app-token-other-user');
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                await page.locator('puter-user-menu .avatar').waitFor();
+                await page.locator('puter-user-menu .apps-button').click();
+                const frame = page.frameLocator('puter-user-menu iframe');
+                await frame.locator('[data-app-name="notes"]').waitFor();
+                expect(await frame.locator('[data-app-name="app-104"]').count()).toBe(0);
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('closes the account menu when Tab leaves it', async () => {
+            const context = await menuContext('app-token-session-user');
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                await page.evaluate(() => document.body.insertAdjacentHTML('beforeend', '<button id="after">After</button>'));
+                const menu = page.locator('puter-user-menu .menu');
+                await page.locator('puter-user-menu .avatar').click();
+                await menu.waitFor();
+                await page.keyboard.press('Tab');
+                await menu.waitFor({ state: 'hidden' });
+                expect(await page.evaluate(() => document.activeElement.id)).toBe('after');
+
+                await page.locator('puter-user-menu .avatar').click();
+                await menu.waitFor();
+                await page.keyboard.press('Shift+Tab');
+                await menu.waitFor({ state: 'hidden' });
+                expect(await page.evaluate(() => document.activeElement.shadowRoot?.activeElement?.className)).toBe('apps-button');
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('moves focus to Sign in after signing out from the keyboard', async () => {
+            const context = await menuContext('app-token-session-user');
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                await page.locator('puter-user-menu .avatar').focus();
+                await page.keyboard.press('Enter');
+                await page.locator('puter-user-menu .menu').waitFor();
+                await page.keyboard.press('Enter');
+                await page.locator('puter-user-menu .sign-in').waitFor();
+                await expect.poll(() => page.evaluate(() => document.activeElement.shadowRoot?.activeElement?.className)).toBe('sign-in');
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('shows the app browser in a theme the page forces', async () => {
+            const context = await menuContext('app-token-session-user');
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.emulateMedia({ colorScheme: 'light' });
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                const menu = page.locator('puter-user-menu');
+                await menu.evaluate(el => el.setAttribute('theme', 'dark'));
+                await page.locator('puter-user-menu .apps-button').click();
+                const frame = page.frameLocator('puter-user-menu iframe');
+                await frame.locator('[data-app-name="app-104"]').waitFor();
+                const background = () => frame.locator('body').evaluate(body => getComputedStyle(body).backgroundColor);
+                expect(await background()).toBe('rgb(30, 30, 30)');
+
+                await menu.evaluate(el => el.setAttribute('theme', 'light'));
+                await expect.poll(background).toBe('rgb(255, 255, 255)');
+                await frame.locator('[data-app-name="app-104"]').waitFor();
+                expect(await page.locator('puter-user-menu .apps-panel').isVisible()).toBe(true);
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('leaves no hover shading on the Apps button once a tap closes it', async () => {
+            const context = await menuContext('app-token-session-user', {
+                viewport: { width: 390, height: 700 }, hasTouch: true, isMobile: true,
+            });
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                const button = page.locator('puter-user-menu .apps-button');
+                await button.tap();
+                await page.locator('puter-user-menu .apps-panel').waitFor();
+                await button.tap();
+                await page.locator('puter-user-menu .apps-panel').waitFor({ state: 'hidden' });
+                expect(await button.evaluate(el => getComputedStyle(el).backgroundColor)).toBe('rgba(0, 0, 0, 0)');
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('shows Sign in pressed and the account hovered', async () => {
+            const context = await menuContext(null);
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                const signIn = page.locator('puter-user-menu .sign-in');
+                await signIn.hover();
+                await page.mouse.down();
+                expect(await signIn.evaluate(el => getComputedStyle(el).color)).toBe('rgb(190, 222, 245)');
+                await page.mouse.move(0, 0);
+                await page.mouse.up();
+
+                await page.evaluate(() => puter.setAuthToken('app-token-session-user'));
+                const avatar = page.locator('puter-user-menu .avatar');
+                await avatar.waitFor();
+                expect(await avatar.evaluate(el => getComputedStyle(el).boxShadow)).toBe('none');
+                await avatar.hover();
+                expect(await avatar.evaluate(el => getComputedStyle(el).boxShadow)).not.toBe('none');
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('shows the account before its picture arrives', async () => {
+            const context = await menuContext('app-token-session-user');
+            let respond;
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.route('**/profile', route => { respond = () => route.fulfill({
+                    status: 200,
+                    headers: { 'Access-Control-Allow-Origin': `http://spreadsheet.puter.localhost:${port}`, 'Access-Control-Allow-Credentials': 'true' },
+                    contentType: 'application/json',
+                    body: JSON.stringify({ picture: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==' }),
+                }); });
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                await page.locator('puter-user-menu .avatar').waitFor({ timeout: 2000 });
+                expect(await page.locator('puter-user-menu .avatar').textContent()).toBe('S');
+                expect(await page.locator('puter-user-menu .apps-button').isVisible()).toBe(true);
+                await expect.poll(() => typeof respond).toBe('function');
+                await respond();
+                await page.locator('puter-user-menu .avatar img').waitFor();
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+
+        it('names the user an app signs in as after loading', async () => {
+            const context = await menuContext(null);
+            try {
+                const page = await context.newPage();
+                page.setDefaultTimeout(6000);
+                await page.goto(`http://spreadsheet.puter.localhost:${port}/menu-host`);
+                await page.locator('puter-user-menu .sign-in').waitFor();
+                // What `puter.auth.signIn()` does with the token its popup hands back.
+                await page.evaluate(() => puter.setAuthToken('app-token-session-user'));
+                await page.locator('puter-user-menu .avatar').waitFor();
+                await expect.poll(() => page.locator('puter-user-menu .avatar').textContent()).toBe('S');
+                await page.locator('puter-user-menu .apps-button').click();
+                expect(await page.locator('puter-user-menu iframe').getAttribute('src')).toBe(`${origin}/embed/apps#user=${sessionUser}`);
+                await page.frameLocator('puter-user-menu iframe').locator('[data-app-name="app-104"]').waitFor();
+            } finally {
+                guestApps = [];
+                await context.close();
+            }
+        });
+    });
+
     it('shows an unavailable state if the SDK cannot load', async () => {
         const context = await browser.newContext({ storageState: {
             cookies: [], origins: [{ origin, localStorage: [{ name: 'auth_token_v2', value: sessionToken }] }],
@@ -307,7 +679,7 @@ describe('embedded app browser', () => {
         try {
             const page = await context.newPage();
             await page.route('**/sdk.js', route => route.abort());
-            await page.goto(`${origin}/embed/apps`);
+            await page.goto(`${origin}/embed/apps#user=${sessionUser}`);
             await page.getByRole('status').waitFor();
             expect(await page.getByRole('status').textContent()).toContain('Apps are unavailable');
         } finally {

src/gui/src/UI/Dashboard/UIDashboard.js

@@ -24,10 +24,10 @@ import UIContextMenu from '../UIContextMenu.js';
 import UIAlert from '../UIAlert.js';
 import UIWindowSaveAccount from '../UIWindowSaveAccount.js';
 import UIAuthLogin from '../Auth/UIAuthLogin.js';
-import UIWindowFeedback from '../UIWindowFeedback.js';
 import apply_item_added_to_containers from '../../helpers/applyItemAddedToContainers.js';
 import { clear_shared_param } from '../../helpers/parseSharedPath.js';
 import UIDashboardNotifications from './UIDashboardNotifications.js';
+import UIDashboardContactDialog from './UIDashboardContactDialog.js';
 import {
     answerNotificationReceipts,
     notificationSocketAcks,
@@ -900,16 +900,8 @@ async function UIDashboard (options) {
             // Contact Us
             {
                 html: i18n('contact_us'),
-                onClick: async function () {
-                    UIWindowFeedback({
-                        window_options: {
-                            backdrop: true,
-                            close_on_backdrop_click: true,
-                            parent_center: true,
-                            stay_on_top: true,
-                            has_head: false,
-                        },
-                    });
+                onClick: function () {
+                    UIDashboardContactDialog({ $container: $el_window, returnFocusTo: $btn.get(0) });
                 },
             },
             '-',

src/gui/src/UI/Dashboard/UIDashboardContactDialog.js

@@ -0,0 +1,277 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// The dashboard's Contact Us form: a dashboard form dialog with screenshots
+// and screen recordings attached by picking, dropping or pasting them. The
+// desktop keeps UIWindowFeedback.
+
+import {
+    ATTACHMENT_ACCEPT_ATTRIBUTE,
+    MAX_ATTACHMENTS,
+    MAX_ATTACHMENT_BYTES,
+    MAX_TOTAL_ATTACHMENT_BYTES,
+    checkAttachment,
+} from '../../helpers/contact_attachments.js';
+import { isTouchPrimaryDevice } from './ContextMenu/ContextMenu.js';
+import { ICONS, SVG } from './UIDashboardDialog.js';
+import UIDashboardFormDialog from './UIDashboardFormDialog.js';
+
+const MB = 1024 * 1024;
+
+// Keep in sync with SystemController on the backend.
+const MESSAGE_MAX_LENGTH = 100_000;
+
+// Numbers interpolated into each error message, taken from the enforced limits.
+const ERROR_VALUES = {
+    contact_us_attachment_too_many: [MAX_ATTACHMENTS],
+    contact_us_attachment_too_large: [MAX_ATTACHMENT_BYTES / MB],
+    contact_us_attachment_total_too_large: [MAX_TOTAL_ATTACHMENT_BYTES / MB],
+};
+
+const CONTACT_ICONS = {
+    attach: SVG('<path d="M21.4 11.1l-9.2 9.2a6 6 0 0 1-8.5-8.5l9.2-9.2a4 4 0 0 1 5.7 5.7l-9.2 9.2a2 2 0 0 1-2.8-2.8l8.5-8.5"/>'),
+    video: SVG('<rect x="2" y="5" width="14" height="14" rx="2"/><path d="M16 10l6-3.5v11L16 14"/>'),
+};
+
+const t = (key, values = []) => i18n(key, values, false);
+
+/**
+ * Whether a drag carries files, rather than text or a link from the page.
+ *
+ * @param {DragEvent} e
+ * @returns {boolean}
+ */
+const dragHasFiles = (e) => Array.from(e.originalEvent?.dataTransfer?.types ?? []).includes('Files');
+
+/**
+ * @param {File} file
+ * @returns {string}
+ */
+const attachmentHtml = (file) => {
+    const name = html_encode(file.name);
+    // The preview's URL is let go once it has drawn; the <img> keeps the pixels.
+    const thumb = file.type.startsWith('image/')
+        ? `<img src="${html_encode(URL.createObjectURL(file))}" alt="" draggable="false">`
+        : CONTACT_ICONS.video;
+    const remove = html_encode(t('contact_us_attachment_remove_named', [file.name]));
+    return '<li class="dashboard-contact-file">'
+        + `<span class="dashboard-contact-file-thumb" aria-hidden="true">${thumb}</span>`
+        + '<span class="dashboard-contact-file-text">'
+        + `<span class="dashboard-contact-file-name" title="${name}">${name}</span>`
+        + `<span class="dashboard-contact-file-size">${html_encode(window.byte_format(file.size))}</span>`
+        + '</span>'
+        + `<button type="button" class="dashboard-contact-file-remove" aria-label="${remove}" title="${i18n('contact_us_attachment_remove')}">${ICONS.close}</button>`
+        + '</li>';
+};
+
+/**
+ * Opens the Contact Us form; the message goes to support, with any
+ * attachments as multipart form data. The checks here only fail fast: the
+ * server enforces the limits.
+ *
+ * @param {object} [opts]
+ * @param {jQuery} [opts.$container] Where the overlay mounts.
+ * @param {HTMLElement} [opts.returnFocusTo] Where focus goes on close.
+ * @returns {import('./UIDashboardFormDialog.js').FormDialog}
+ */
+export default function UIDashboardContactDialog ({ $container, returnFocusTo } = {}) {
+    /** @type {File[]} */
+    const attachments = [];
+    let sending = false;
+    // Once sent, the form is gone and a drop or paste has nothing to join.
+    let sent = false;
+
+    const dialog = UIDashboardFormDialog({
+        $container,
+        returnFocusTo,
+        title: t('contact_us'),
+        intro: `<p>${i18n('feedback_c2a')}</p>`,
+        submitLabel: t('send'),
+        fields: [{
+            name: 'message',
+            type: 'textarea',
+            label: i18n('contact_us_message'),
+            placeholder: i18n('contact_us_message_placeholder'),
+            attrs: { rows: 6, maxlength: MESSAGE_MAX_LENGTH },
+        }],
+        async onSubmit () {
+            const { message } = dialog.values();
+            if ( ! message.trim() ) {
+                dialog.setStatus(t('contact_us_message_required'), { field: 'message' });
+                return;
+            }
+
+            setSending(true);
+            try {
+                const body = new FormData();
+                body.append('message', message);
+                for ( const file of attachments ) body.append('attachments', file, file.name);
+
+                // No Content-Type: the browser sets it with the boundary.
+                const resp = await fetch(`${window.api_origin}/contactUs`, {
+                    method: 'POST',
+                    headers: { Authorization: `Bearer ${window.auth_token}` },
+                    body,
+                });
+                if ( ! resp.ok ) {
+                    dialog.setStatus(t(resp.status === 429 ? 'contact_us_rate_limited' : 'contact_us_error'));
+                    return;
+                }
+                sent = true;
+                dialog.finish({ message: t('feedback_sent_confirmation') });
+            } catch ( err ) {
+                console.error('contact-us: submit failed', err);
+                dialog.setStatus(t('contact_us_error'));
+            } finally {
+                setSending(false);
+            }
+        },
+    });
+
+    const { $dialog } = dialog;
+    const $overlay = $dialog.parent();
+    const hint_id = `${$dialog.attr('aria-labelledby')}-attach-hint`;
+
+    let h = '<div class="dashboard-contact-attachments">';
+    h += `<input type="file" class="dashboard-contact-file-input" accept="${html_encode(ATTACHMENT_ACCEPT_ATTRIBUTE)}" multiple hidden tabindex="-1">`;
+    h += `<button type="button" class="dashboard-contact-dropzone" aria-describedby="${hint_id}">`;
+    h += `<span class="dashboard-contact-dropzone-icon" aria-hidden="true">${CONTACT_ICONS.attach}</span>`;
+    h += '<span class="dashboard-contact-dropzone-text">';
+    h += `<span class="dashboard-contact-dropzone-label">${i18n(isTouchPrimaryDevice() ? 'contact_us_attach' : 'contact_us_attach_or_drop')}</span>`;
+    h += `<span class="dashboard-contact-dropzone-drop" aria-hidden="true">${i18n('contact_us_drop_to_attach')}</span>`;
+    h += `<span class="dashboard-contact-dropzone-hint" id="${hint_id}">${i18n('contact_us_attach_hint', [MAX_ATTACHMENTS, MAX_ATTACHMENT_BYTES / MB])}</span>`;
+    h += '</span>';
+    h += '</button>';
+    h += `<ul class="dashboard-contact-files" aria-label="${i18n('contact_us_attachments')}" hidden></ul>`;
+    h += '</div>';
+    $dialog.addClass('dashboard-contact-dialog')
+        .find('.dashboard-form-field[data-field="message"]').after(h);
+
+    const $dropzone = $dialog.find('.dashboard-contact-dropzone');
+    const $fileInput = $dialog.find('.dashboard-contact-file-input');
+    const $list = $dialog.find('.dashboard-contact-files');
+
+    const syncControls = () => {
+        $list.prop('hidden', attachments.length === 0);
+        // Nothing left to add once the count cap is reached.
+        $dropzone.prop('disabled', sending || attachments.length >= MAX_ATTACHMENTS);
+        $list.find('.dashboard-contact-file-remove').prop('disabled', sending);
+    };
+
+    function setSending (value) {
+        sending = value;
+        $dialog.toggleClass('dashboard-contact-sending', value);
+        syncControls();
+    }
+
+    /** @param {File[]} files */
+    const addFiles = (files) => {
+        if ( sending || sent || ! files.length ) return;
+        let rejection = null;
+        for ( const file of files ) {
+            const verdict = checkAttachment(file, attachments);
+            if ( ! verdict.ok ) {
+                // Report the first rejection but keep the files that fit.
+                rejection = rejection ?? verdict.error;
+                continue;
+            }
+            attachments.push(file);
+            const $item = $(attachmentHtml(file));
+            $item.find('img').one('load error', function () {
+                URL.revokeObjectURL(this.src);
+            });
+            $list.append($item);
+        }
+        dialog.setStatus(rejection ? t(rejection, ERROR_VALUES[rejection] ?? []) : '');
+        syncControls();
+    };
+
+    $dropzone.on('click', () => $fileInput.trigger('click'));
+    $fileInput.on('change', function () {
+        addFiles(Array.from(this.files ?? []));
+        // Reset so re-picking the same file fires `change` again.
+        this.value = '';
+    });
+
+    $list.on('click', '.dashboard-contact-file-remove', function () {
+        if ( sending ) return;
+        const $item = $(this).closest('.dashboard-contact-file');
+        const index = $list.children().index($item);
+        attachments.splice(index, 1);
+        // Focus stays in the list rather than falling back to the page.
+        const $next = $item.next().length ? $item.next() : $item.prev();
+        $item.remove();
+        dialog.setStatus('');
+        syncControls();
+        ($next.length ? $next.find('.dashboard-contact-file-remove') : $dropzone).get(0)?.focus({ preventScroll: true });
+    });
+
+    // The whole overlay takes the drop, and keeps it from the window under it.
+    let drag_depth = 0;
+    const endDrag = () => {
+        drag_depth = 0;
+        $dialog.removeClass('dashboard-contact-dragging');
+    };
+    $overlay.on('dragenter', (e) => {
+        if ( ! dragHasFiles(e) ) return;
+        e.preventDefault();
+        e.stopPropagation();
+        drag_depth++;
+        if ( ! sending && ! sent ) $dialog.addClass('dashboard-contact-dragging');
+    });
+    $overlay.on('dragover', (e) => {
+        if ( ! dragHasFiles(e) ) return;
+        e.preventDefault();
+        e.stopPropagation();
+        e.originalEvent.dataTransfer.dropEffect = sending || sent ? 'none' : 'copy';
+    });
+    $overlay.on('dragleave', (e) => {
+        // Matched to the dragenters counted, whatever this one says it carries.
+        if ( drag_depth === 0 ) return;
+        e.stopPropagation();
+        if ( --drag_depth <= 0 ) endDrag();
+    });
+    $overlay.on('drop', (e) => {
+        if ( ! dragHasFiles(e) ) return;
+        e.preventDefault();
+        e.stopPropagation();
+        endDrag();
+        addFiles(Array.from(e.originalEvent.dataTransfer.files ?? []));
+    });
+
+    // A screenshot pasted into the message is attached to it.
+    $dialog.on('paste', '.dashboard-form-input[name="message"]', (e) => {
+        const clipboard = e.originalEvent?.clipboardData;
+        const files = Array.from(clipboard?.files ?? []);
+        if ( ! files.length ) return;
+        // Some apps put the image's name or markup alongside it; that text still pastes.
+        if ( ! clipboard.getData('text/plain') ) e.preventDefault();
+        addFiles(files);
+    });
+
+    // Enter alone is a new line in the message; with Cmd or Ctrl, it sends.
+    $dialog.on('keydown', '.dashboard-form-input[name="message"]', (e) => {
+        if ( e.key !== 'Enter' || ! (e.metaKey || e.ctrlKey) ) return;
+        e.preventDefault();
+        $dialog.trigger('submit');
+    });
+
+    syncControls();
+    return dialog;
+}

src/gui/src/UI/Dashboard/UIDashboardContactDialog.test.js

@@ -0,0 +1,255 @@
+// @vitest-environment jsdom
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import jQuery from '../../lib/jquery-3.6.1/jquery-3.6.1.min.js';
+import { MAX_ATTACHMENTS } from '../../helpers/contact_attachments.js';
+
+globalThis.$ = jQuery;
+globalThis.jQuery = jQuery;
+globalThis.i18n = (key, values = []) => [key, ...values].join(' ');
+globalThis.html_encode = (value) => String(value ?? '')
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+window.html_encode = globalThis.html_encode;
+window.requestAnimationFrame = (fn) => setTimeout(fn, 0);
+window.matchMedia = () => ({ matches: false });
+window.byte_format = (bytes) => `${bytes} B`;
+URL.createObjectURL = vi.fn(() => 'blob:preview');
+URL.revokeObjectURL = vi.fn();
+
+const { default: UIDashboardContactDialog } = await import('./UIDashboardContactDialog.js');
+
+const settle = async () => {
+    for ( let i = 0; i < 10; i++ ) await new Promise(resolve => setTimeout(resolve, 0));
+};
+const message = () => $('.dashboard-form-input[name="message"]');
+const status = () => $('.dashboard-form-status').text();
+const fileNames = () => $('.dashboard-contact-file-name').map((_, el) => el.textContent).get();
+const png = (name = 'shot.png', size = 1024) => new File([new Uint8Array(size)], name, { type: 'image/png' });
+const mp4 = (name = 'clip.mp4') => new File([new Uint8Array(2048)], name, { type: 'video/mp4' });
+
+/** Picks files through the hidden file input, as the system picker would. */
+const pick = (...files) => {
+    const input = $('.dashboard-contact-file-input').get(0);
+    Object.defineProperty(input, 'files', { value: files, configurable: true });
+    $(input).trigger('change');
+};
+
+/** A native-event stand-in for jQuery to wrap, carrying `fields`. */
+const nativeEvent = (fields) => ({ preventDefault () {}, stopPropagation () {}, ...fields });
+
+/** A file drag event carrying `files`, as the browser sends it. */
+const fileDrag = (type, files = []) => $.Event(type, {
+    originalEvent: nativeEvent({ dataTransfer: { types: ['Files'], files, dropEffect: 'none' } }),
+});
+
+const submit = async () => {
+    $('.dashboard-form-dialog').trigger('submit');
+    await settle();
+};
+
+beforeEach(() => {
+    document.body.innerHTML = '';
+    globalThis.fetch = vi.fn(async () => new Response('{}', { status: 200 }));
+    window.api_origin = 'https://api.puter.test';
+    window.auth_token = 'tok-1';
+});
+
+describe('Contact Us dialog', () => {
+    it('opens as a dashboard form dialog with no attachments listed', () => {
+        UIDashboardContactDialog();
+        expect($('.dashboard-dialog-overlay .dashboard-contact-dialog').length).toBe(1);
+        expect(message().length).toBe(1);
+        expect($('.dashboard-contact-files').prop('hidden')).toBe(true);
+    });
+
+    it('asks for a message before sending', async () => {
+        UIDashboardContactDialog();
+        message().val('   ');
+        await submit();
+        expect(fetch).not.toHaveBeenCalled();
+        expect(status()).toBe('contact_us_message_required');
+        expect(message().attr('aria-invalid')).toBe('true');
+    });
+
+    it('posts the message and attachments as multipart and confirms', async () => {
+        UIDashboardContactDialog();
+        pick(png(), mp4());
+        message().val('It broke');
+        await submit();
+
+        const [url, init] = fetch.mock.calls[0];
+        expect(url).toBe('https://api.puter.test/contactUs');
+        expect(init.headers).toEqual({ Authorization: 'Bearer tok-1' });
+        expect(init.body.get('message')).toBe('It broke');
+        expect(init.body.getAll('attachments').map(f => f.name)).toEqual(['shot.png', 'clip.mp4']);
+        expect($('.dashboard-form-done').text()).toContain('feedback_sent_confirmation');
+        expect($('.dashboard-contact-attachments').length).toBe(0);
+    });
+
+    it('says when the sender is rate limited and keeps the form', async () => {
+        fetch.mockResolvedValueOnce(new Response('{}', { status: 429 }));
+        UIDashboardContactDialog();
+        message().val('Hello');
+        await submit();
+        expect(status()).toBe('contact_us_rate_limited');
+        expect(message().val()).toBe('Hello');
+        expect(message().prop('disabled')).toBe(false);
+    });
+
+    it('shows a generic error when the request fails', async () => {
+        fetch.mockRejectedValueOnce(new TypeError('offline'));
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+        UIDashboardContactDialog();
+        message().val('Hello');
+        await submit();
+        expect(status()).toBe('contact_us_error');
+    });
+
+    it('locks the attachments while sending', async () => {
+        let respond;
+        fetch.mockReturnValueOnce(new Promise(resolve => {
+            respond = resolve;
+        }));
+        UIDashboardContactDialog();
+        pick(png());
+        message().val('Hello');
+        $('.dashboard-form-dialog').trigger('submit');
+        await settle();
+
+        expect($('.dashboard-contact-dropzone').prop('disabled')).toBe(true);
+        expect($('.dashboard-contact-file-remove').prop('disabled')).toBe(true);
+        pick(png('late.png'));
+        expect(fileNames()).toEqual(['shot.png']);
+
+        respond(new Response('{}', { status: 500 }));
+        await settle();
+        expect($('.dashboard-contact-dropzone').prop('disabled')).toBe(false);
+        expect($('.dashboard-contact-file-remove').prop('disabled')).toBe(false);
+    });
+});
+
+describe('attachments', () => {
+    it('lists picked files with a preview for images', () => {
+        UIDashboardContactDialog();
+        pick(png('a.png'), mp4('b.mp4'));
+        expect(fileNames()).toEqual(['a.png', 'b.mp4']);
+        expect($('.dashboard-contact-files').prop('hidden')).toBe(false);
+        expect($('.dashboard-contact-file').eq(0).find('img').attr('src')).toBe('blob:preview');
+        expect($('.dashboard-contact-file').eq(1).find('img').length).toBe(0);
+        expect($('.dashboard-contact-file-remove').eq(0).attr('aria-label')).toBe('contact_us_attachment_remove_named a.png');
+    });
+
+    it('keeps the files that fit and reports the first rejection', () => {
+        UIDashboardContactDialog();
+        const text = new File(['x'], 'notes.txt', { type: 'text/plain' });
+        pick(png('a.png'), text, png('b.png'));
+        expect(fileNames()).toEqual(['a.png', 'b.png']);
+        expect(status()).toBe('contact_us_attachment_unsupported');
+    });
+
+    it('stops offering to attach once the count cap is reached', () => {
+        UIDashboardContactDialog();
+        pick(...Array.from({ length: MAX_ATTACHMENTS }, (_, i) => png(`${i}.png`)));
+        expect($('.dashboard-contact-dropzone').prop('disabled')).toBe(true);
+        pick(png('extra.png'));
+        expect(fileNames()).toHaveLength(MAX_ATTACHMENTS);
+        expect(status()).toBe(`contact_us_attachment_too_many ${MAX_ATTACHMENTS}`);
+    });
+
+    it('removes the file whose button is pressed and moves focus to the next one', async () => {
+        UIDashboardContactDialog();
+        pick(png('a.png'), png('b.png'), png('c.png'));
+        $('.dashboard-contact-file-remove').eq(1).trigger('click');
+        expect(fileNames()).toEqual(['a.png', 'c.png']);
+        expect(document.activeElement).toBe($('.dashboard-contact-file-remove').get(1));
+
+        message().val('Hello');
+        await submit();
+        expect(fetch.mock.calls[0][1].body.getAll('attachments').map(f => f.name)).toEqual(['a.png', 'c.png']);
+    });
+
+    it('returns focus to the attach button when the last file is removed', () => {
+        UIDashboardContactDialog();
+        pick(png());
+        $('.dashboard-contact-file-remove').trigger('click');
+        expect($('.dashboard-contact-files').prop('hidden')).toBe(true);
+        expect(document.activeElement).toBe($('.dashboard-contact-dropzone').get(0));
+    });
+
+    it('takes files dropped anywhere on the overlay, without letting the drop through', () => {
+        const onWindowDrop = vi.fn();
+        const $win = $('<div class="window"></div>').appendTo('body').on('drop', onWindowDrop);
+        UIDashboardContactDialog({ $container: $win });
+        const $overlay = $('.dashboard-dialog-overlay');
+
+        $overlay.trigger(fileDrag('dragenter'));
+        expect($('.dashboard-contact-dialog').hasClass('dashboard-contact-dragging')).toBe(true);
+        const drop = fileDrag('drop', [png('dropped.png')]);
+        $overlay.trigger(drop);
+
+        expect(drop.isDefaultPrevented()).toBe(true);
+        expect(onWindowDrop).not.toHaveBeenCalled();
+        expect(fileNames()).toEqual(['dropped.png']);
+        expect($('.dashboard-contact-dialog').hasClass('dashboard-contact-dragging')).toBe(false);
+    });
+
+    it('clears the drop highlight when the drag leaves', () => {
+        UIDashboardContactDialog();
+        const $overlay = $('.dashboard-dialog-overlay');
+        $overlay.trigger(fileDrag('dragenter'));
+        $overlay.find('.dashboard-contact-dropzone').trigger(fileDrag('dragenter'));
+        $overlay.find('.dashboard-contact-dropzone').trigger($.Event('dragleave', { originalEvent: nativeEvent({}) }));
+        expect($('.dashboard-contact-dialog').hasClass('dashboard-contact-dragging')).toBe(true);
+        $overlay.trigger($.Event('dragleave', { originalEvent: nativeEvent({}) }));
+        expect($('.dashboard-contact-dialog').hasClass('dashboard-contact-dragging')).toBe(false);
+    });
+
+    it('ignores drags that carry no files', () => {
+        UIDashboardContactDialog();
+        const drag = $.Event('dragenter', { originalEvent: nativeEvent({ dataTransfer: { types: ['text/plain'] } }) });
+        $('.dashboard-dialog-overlay').trigger(drag);
+        expect(drag.isDefaultPrevented()).toBe(false);
+        expect($('.dashboard-contact-dialog').hasClass('dashboard-contact-dragging')).toBe(false);
+    });
+
+    it('attaches an image pasted into the message', () => {
+        UIDashboardContactDialog();
+        const paste = $.Event('paste', {
+            originalEvent: nativeEvent({ clipboardData: { files: [png('pasted.png')], getData: () => '' } }),
+        });
+        message().trigger(paste);
+        expect(fileNames()).toEqual(['pasted.png']);
+        expect(paste.isDefaultPrevented()).toBe(true);
+    });
+});
+
+describe('keyboard', () => {
+    it('sends on Cmd/Ctrl+Enter but not on Enter alone', async () => {
+        UIDashboardContactDialog();
+        message().val('Hello');
+        message().trigger($.Event('keydown', { key: 'Enter' }));
+        await settle();
+        expect(fetch).not.toHaveBeenCalled();
+
+        message().trigger($.Event('keydown', { key: 'Enter', ctrlKey: true }));
+        await settle();
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+});

src/gui/src/UI/Dashboard/UIPublishDialogs.js

@@ -17,13 +17,14 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-// The Files tab's publish flows, a folder as a website and a .js file as a
-// worker: dashboard form dialogs rather than desktop windows.
+// The Files tab's publish flows, a folder as a website (optionally on a
+// custom domain) and a .js file as a worker: dashboard form dialogs rather
+// than desktop windows.
 
 import ensure_can_publish from '../../helpers/ensureCanPublish.js';
 import forget_parent_listing from '../../helpers/forgetParentListing.js';
-import { SVG } from './UIDashboardDialog.js';
 import UIDashboardFormDialog, { copyRowHtml } from './UIDashboardFormDialog.js';
+import { openLinkHtml, publishDomainFields, setupPublishDomain } from './publishDomain.js';
 import { finalizePublishName, normalizePublishName, PUBLISH_NAME_RULES } from './publishName.js';
 
 /**
@@ -36,8 +37,6 @@ import { finalizePublishName, normalizePublishName, PUBLISH_NAME_RULES } from '.
 
 const t = (key) => i18n(key, [], false);
 
-const OPEN_ICON = SVG('<path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><path d="M15 3h6v6"/><path d="M10 14L21 3"/>');
-
 /** Rows showing `path` or anything under it, on the dashboard or the desktop. */
 const each_item_at = (path, fn) => $('.item').each(function () {
     const item_path = this.dataset.path ?? '';
@@ -54,6 +53,8 @@ const KINDS = {
         nameErrors: new Set(['conflict', 'subdomain_reserved']),
         suffix: () => `.${window.hosting_domain}`,
         requiresVerification: () => !! window.require_email_verification_to_publish_website,
+        extraFields: publishDomainFields,
+        setup: setupPublishDomain,
         async publish (name, path) {
             const site = await puter.hosting.create(name, path);
             // The server's address carries the deployment's real scheme (a
@@ -136,6 +137,11 @@ const open_publish_dialog = async (kind_name, { name, path, ...opts }) => {
     }];
     fields.push(...(kind.extraFields?.() ?? []));
 
+    /** Set once the site is live; a retry for a step after it skips publishing. */
+    let published = null;
+    /** @type {import('./publishDomain.js').PublishDomain | undefined} */
+    let extra;
+
     const dialog = UIDashboardFormDialog({
         ...opts,
         title: t(kind.title),
@@ -144,30 +150,52 @@ const open_publish_dialog = async (kind_name, { name, path, ...opts }) => {
         fields,
         async onSubmit () {
             const values = dialog.values();
-            const subdomain = finalizePublishName(values.name, kind.rule);
-            dialog.field('name').val(subdomain);
-            if ( ! subdomain ) {
-                dialog.setStatus(t('publish_name_required'), { field: 'name' });
-                return;
+            const hostname = extra?.prepare(!! published) ?? null;
+            if ( hostname === false ) return;
+            if ( ! published ) {
+                const subdomain = finalizePublishName(values.name, kind.rule);
+                dialog.field('name').val(subdomain);
+                if ( ! subdomain ) {
+                    dialog.setStatus(t('publish_name_required'), { field: 'name' });
+                    return;
+                }
+                let url;
+                try {
+                    url = await kind.publish(subdomain, path, values);
+                } catch ( err ) {
+                    const code = err?.error?.code ?? err?.code;
+                    dialog.setStatus(error_message(err), kind.nameErrors.has(code) ? { field: 'name' } : undefined);
+                    return;
+                }
+                kind.markPublished(path, url);
+                published = { name: subdomain, url };
+                // The address is taken now; what's left to retry is the domain.
+                dialog.field('name').prop('readOnly', true).attr('aria-readonly', 'true');
+                update_submit_label();
             }
-            let url;
-            try {
-                url = await kind.publish(subdomain, path, values);
-            } catch ( err ) {
-                const code = err?.error?.code ?? err?.code;
-                dialog.setStatus(error_message(err), kind.nameErrors.has(code) ? { field: 'name' } : undefined);
-                return;
-            }
-            kind.markPublished(path, url);
-            const open_link = `<a class="dashboard-dialog-btn dashboard-dialog-btn-quiet dashboard-icon-btn dashboard-publish-open" href="${html_encode(url)}"`
-                + ` target="_blank" rel="noopener noreferrer" aria-label="${i18n('open_in_new_tab')}" title="${i18n('open_in_new_tab')}">${OPEN_ICON}</a>`;
+            const domain = hostname ? await extra.attach(hostname, published) : null;
+            if ( hostname && ! domain ) return;
             dialog.finish({
                 message: t(kind.published),
-                html: copyRowHtml({ value: url, label: t('publish_address'), compact: true, after: open_link }),
+                html: copyRowHtml({ value: published.url, label: t('publish_address'), compact: true, after: openLinkHtml(published.url) })
+                    + (domain ? extra.doneHtml(domain) : ''),
+                // The DNS records are shown only here.
+                keepOnBackdrop: !! domain,
             });
         },
     });
 
+    // Before the site is live the button publishes; after, it adds the domain.
+    const update_submit_label = () => {
+        let key = 'publish';
+        if ( published ) {
+            if ( extra?.claiming() ) key = 'custom_domain_verify_and_add';
+            else key = extra?.addable() ? 'custom_domain_add' : 'done';
+        }
+        dialog.$dialog.find('.dashboard-form-submit-label').text(t(key));
+    };
+    extra = kind.setup?.(dialog, { onChange: update_submit_label });
+
     // Shape the name as it's typed, keeping the caret where it was.
     const el_name = dialog.field('name').get(0);
     if ( document.activeElement === el_name ) el_name.select();

src/gui/src/UI/Dashboard/UIPublishDialogs.test.js

@@ -35,13 +35,59 @@ const { openPublishWebsiteDialog, openPublishWorkerDialog } = await import('./UI
 const { default: ensure_can_publish } = await import('../../helpers/ensureCanPublish.js');
 
 const settle = () => new Promise(resolve => setTimeout(resolve, 0));
+const flush = async () => {
+    for ( let i = 0; i < 5; i++ ) await settle();
+};
 const nameField = () => $('.dashboard-form-input[name="name"]');
 const status = () => $('.dashboard-form-status').text();
 
 const submitWith = async (name) => {
     if ( name !== undefined ) nameField().val(name);
     $('.dashboard-form-dialog').trigger('submit');
-    for ( let i = 0; i < 5; i++ ) await settle();
+    await flush();
+};
+
+const json = (code, data) => new Response(JSON.stringify(data), {
+    status: code,
+    headers: { 'Content-Type': 'application/json' },
+});
+
+/**
+ * Stands in for the `/custom-domains` API. The list call answers with
+ * `list`; anything else with its entry in `routes` (keyed `METHOD /path`),
+ * or a 404.
+ */
+const serveDomains = ({ list = { items: [], canAdd: true, pricing: { amount: 0.5, currency: 'USD' } }, routes = {} } = {}) => {
+    globalThis.fetch = vi.fn(async (url, opts = {}) => {
+        const key = `${opts.method ?? 'GET'} ${String(url).split('/custom-domains')[1]}`;
+        if ( key === 'GET ' ) return json(200, typeof list === 'function' ? list() : list);
+        return routes[key]?.(opts.body ? JSON.parse(opts.body) : undefined) ?? json(404, {});
+    });
+};
+const requests = (method) => fetch.mock.calls
+    .filter(([, opts = {}]) => (opts.method ?? 'GET') === method)
+    .map(([url, opts]) => ({ path: String(url).split('/custom-domains')[1], body: opts.body ? JSON.parse(opts.body) : undefined }));
+
+const pendingDomain = (overrides = {}) => ({
+    uuid: 'd1',
+    hostname: 'www.example.com',
+    site: 'my-site',
+    status: 'pending',
+    isApex: false,
+    records: [{ type: 'CNAME', name: 'www', value: 'my-site.puter.site', purpose: 'routing', required: true }],
+    ...overrides,
+});
+
+const domainSwitch = () => $('.dashboard-form-input[name="useDomain"]');
+const domainField = () => $('.dashboard-form-input[name="domain"]');
+const shown = (name) => $(`.dashboard-form-field[data-field="${name}"]`).prop('hidden') === false;
+const submitLabel = () => $('.dashboard-form-submit-label').text();
+const turnOnDomain = () => domainSwitch().prop('checked', true).trigger('change');
+
+/** Opens the website dialog and waits for the custom domain list. */
+const openWebsite = async () => {
+    await openPublishWebsiteDialog({ name: 'Site', path: '/alice/Site' });
+    await flush();
 };
 
 const addRow = (path) => {
@@ -59,6 +105,10 @@ beforeEach(() => {
     window.generate_identifier = () => 'clever-idea-42';
     window.update_sites_cache = vi.fn();
     window.require_email_verification_to_publish_website = false;
+    window.api_origin = 'https://api.puter.test';
+    delete window.UIUpgradeAccount;
+    // A Puter without custom domains, unless a test serves them.
+    globalThis.fetch = vi.fn(async () => json(404, {}));
     globalThis.puter = {
         fsCacheKey: (kind, path) => `${kind}:${path}`,
         _cache: { del: vi.fn() },
@@ -126,7 +176,7 @@ describe('publish website', () => {
         expect(nameField().val()).toBe('cafe');
     });
 
-        it('asks for an address when nothing usable was typed', async () => {
+    it('asks for an address when nothing usable was typed', async () => {
         await openPublishWebsiteDialog({ name: 'Site', path: '/alice/Site' });
         await submitWith('---');
         expect(status()).toBe('publish_name_required');
@@ -164,6 +214,358 @@ describe('publish website', () => {
     });
 });
 
+describe('publish website on a custom domain', () => {
+    it('leaves the option out where the server has no custom domains', async () => {
+        await openWebsite();
+        expect(shown('useDomain')).toBe(false);
+        expect(shown('domain')).toBe(false);
+        await submitWith('my-site');
+        expect(puter.hosting.create).toHaveBeenCalledWith('my-site', '/alice/Site');
+        expect(requests('POST')).toEqual([]);
+    });
+
+    it('asks for the domain once the switch is on, with what it costs', async () => {
+        serveDomains();
+        await openWebsite();
+        expect(shown('useDomain')).toBe(true);
+        expect(shown('domain')).toBe(false);
+
+        turnOnDomain();
+
+        expect(shown('domain')).toBe(true);
+        expect(document.activeElement).toBe(domainField().get(0));
+        expect($('.dashboard-form-field[data-field="domain"] .dashboard-form-hint').text())
+            .toBe('publish_custom_domain_dns_hint custom_domain_price_note');
+        expect($('.dashboard-publish-upsell').prop('hidden')).toBe(true);
+    });
+
+    it('publishes the site, adds the domain, and shows the records to set', async () => {
+        serveDomains({ routes: { 'POST ': () => json(201, pendingDomain()) } });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('https://WWW.Example.com/about');
+
+        await submitWith('my-site');
+
+        expect(puter.hosting.create).toHaveBeenCalledWith('my-site', '/alice/Site');
+        expect(requests('POST')).toEqual([{ path: '', body: { site: 'my-site', hostname: 'www.example.com' } }]);
+        expect($('.dashboard-form-done p').text()).toBe('website_published');
+        expect($('.dashboard-copy-value').first().val()).toBe('https://my-site.puter.site');
+        expect($('.dashboard-publish-domain-host').text()).toBe('www.example.com');
+        expect($('.dashboard-publish-domain-badge').attr('data-status')).toBe('pending');
+        expect($('.dashboard-dns-record-type').text()).toBe('CNAME');
+        expect($('.dashboard-dns-record .dashboard-copy-value').map((_, el) => el.value).get())
+            .toEqual(['www', 'my-site.puter.site']);
+    });
+
+    it('keeps the records up through a stray click outside the card', async () => {
+        serveDomains({ routes: { 'POST ': () => json(201, pendingDomain()) } });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('www.example.com');
+        await submitWith('my-site');
+
+        const $backdrop = $('.dashboard-dialog-overlay');
+        $backdrop.trigger('mousedown').trigger('click');
+        await flush();
+        expect($backdrop.hasClass('dashboard-dialog-show')).toBe(true);
+        expect($('.dashboard-dns-record')).toHaveLength(1);
+    });
+
+    it('checks the domain again and shows its address once connected', async () => {
+        serveDomains({
+            routes: {
+                'POST ': () => json(201, pendingDomain()),
+                'GET /d1': () => json(200, pendingDomain({ status: 'active', records: [] })),
+            },
+        });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('www.example.com');
+        await submitWith('my-site');
+
+        $('.dashboard-publish-domain-check').trigger('click');
+        await flush();
+
+        expect(requests('GET').map((r) => r.path)).toContain('/d1');
+        expect($('.dashboard-publish-domain-badge').attr('data-status')).toBe('active');
+        expect($('.dashboard-publish-domain .dashboard-copy-value').val()).toBe('https://www.example.com');
+        expect($('.dashboard-publish-domain-status').text()).toBe('custom_domain_success_note');
+        expect($('.dashboard-publish-domain-check')).toHaveLength(0);
+    });
+
+    it('announces a check in the status region already on screen', async () => {
+        serveDomains({
+            routes: {
+                'POST ': () => json(201, pendingDomain()),
+                'GET /d1': () => json(200, pendingDomain()),
+            },
+        });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('www.example.com');
+        await submitWith('my-site');
+        const el_status = $('.dashboard-publish-domain-status').get(0);
+
+        $('.dashboard-publish-domain-check').trigger('click');
+        await flush();
+
+        expect($('.dashboard-publish-domain-status').get(0)).toBe(el_status);
+        expect(el_status.textContent).toBe('custom_domain_status_pending');
+        // The redrawn records are not read out again.
+        expect($('.dashboard-dns-record').closest('[aria-live]').attr('aria-live')).toBe('off');
+    });
+
+    it('runs one domain action at a time on the done screen', async () => {
+        let answer_check;
+        serveDomains({
+            routes: {
+                'POST ': () => json(201, pendingDomain({ hostname: 'example.com', isApex: true })),
+                'GET /d1': () => new Promise((resolve) => {
+                    answer_check = () => resolve(json(200, pendingDomain({ hostname: 'example.com', isApex: true })));
+                }),
+                'POST /d1/use-www': () => json(200, pendingDomain({ redirectFrom: 'example.com' })),
+            },
+        });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('example.com');
+        await submitWith('my-site');
+
+        $('.dashboard-publish-domain-check').trigger('click');
+        await flush();
+        expect($('.dashboard-publish-domain-www').prop('disabled')).toBe(true);
+        $('.dashboard-publish-domain-www').trigger('click');
+        await flush();
+        expect(requests('POST').map((r) => r.path)).not.toContain('/d1/use-www');
+
+        answer_check();
+        await flush();
+        expect($('.dashboard-publish-domain-www').prop('disabled')).toBe(false);
+    });
+
+    it('stops before publishing when the domain is not one', async () => {
+        serveDomains();
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('localhost');
+
+        await submitWith('my-site');
+
+        expect(status()).toBe('custom_domain_error_invalid');
+        expect(domainField().attr('aria-invalid')).toBe('true');
+        expect(puter.hosting.create).not.toHaveBeenCalled();
+    });
+
+    it('keeps the live site and retries only the domain when adding it fails', async () => {
+        const add = vi.fn()
+            .mockReturnValueOnce(json(409, { code: 'custom_domain_taken', message: 'That hostname is already in use' }))
+            .mockReturnValueOnce(json(201, pendingDomain({ hostname: 'www.example.org' })));
+        serveDomains({ routes: { 'POST ': add } });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('www.example.com');
+
+        await submitWith('my-site');
+
+        expect(status()).toBe('publish_domain_failed\ncustom_domain_error_taken');
+        expect(domainField().attr('aria-invalid')).toBe('true');
+        expect(nameField().prop('readOnly')).toBe(true);
+        expect(submitLabel()).toBe('custom_domain_add');
+        // Published now, so the hint no longer speaks of "after publishing".
+        expect($('.dashboard-form-field[data-field="domain"] .dashboard-form-hint').text()).toBe('custom_domain_price_note');
+
+        domainField().val('www.example.org');
+        await submitWith();
+
+        expect(puter.hosting.create).toHaveBeenCalledTimes(1);
+        expect(add).toHaveBeenLastCalledWith({ site: 'my-site', hostname: 'www.example.org' });
+        expect($('.dashboard-publish-domain-host').text()).toBe('www.example.org');
+    });
+
+    it('finishes with just the site when the domain is turned off after a failure', async () => {
+        serveDomains({ routes: { 'POST ': () => json(409, { code: 'custom_domain_taken' }) } });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('www.example.com');
+        await submitWith('my-site');
+
+        domainSwitch().prop('checked', false).trigger('change');
+        expect(submitLabel()).toBe('done');
+        await submitWith();
+
+        expect(puter.hosting.create).toHaveBeenCalledTimes(1);
+        expect($('.dashboard-form-done p').text()).toBe('website_published');
+        expect($('.dashboard-publish-domain')).toHaveLength(0);
+    });
+
+    it('moves a domain already on the account instead of adding it again', async () => {
+        serveDomains({
+            list: { items: [pendingDomain({ site: 'old-site', status: 'active' })], canAdd: true },
+            routes: { 'PATCH /d1': () => json(200, pendingDomain({ status: 'active' })) },
+        });
+        await openWebsite();
+        turnOnDomain();
+        expect($(`#${domainField().attr('list')} option`).map((_, el) => el.value).get()).toEqual(['www.example.com']);
+        domainField().val('www.example.com').trigger('input');
+        expect($('.dashboard-form-field[data-field="domain"] .dashboard-form-hint').text()).toBe('publish_custom_domain_moves');
+
+        await submitWith('my-site');
+
+        expect(requests('POST')).toEqual([]);
+        expect(requests('PATCH')).toEqual([{ path: '/d1', body: { site: 'my-site' } }]);
+        expect($('.dashboard-publish-domain-badge').attr('data-status')).toBe('active');
+    });
+
+    it('says the www hostname serves the site and the root domain forwards to it', async () => {
+        serveDomains({
+            routes: {
+                'POST ': () => json(201, pendingDomain({
+                    redirectFrom: 'example.com',
+                    records: [
+                        { type: 'CNAME', name: 'www', value: 'my-site.puter.site', purpose: 'routing', required: true },
+                        { type: 'A', name: '@', value: '192.0.2.1', purpose: 'redirect', required: true },
+                    ],
+                })),
+            },
+        });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('www.example.com');
+        const i18n_stub = globalThis.i18n;
+        globalThis.i18n = (key, replacements) => (Array.isArray(replacements) && replacements.length ? `${key}:${replacements.join('|')}` : key);
+        try {
+            await submitWith('my-site');
+        } finally {
+            globalThis.i18n = i18n_stub;
+        }
+
+        expect($('.dashboard-publish-domain .dashboard-form-hint').last().text())
+            .toBe('custom_domain_redirect_note:www.example.com|example.com');
+    });
+
+    it('shows the ownership record for a domain held by another account', async () => {
+        const add = vi.fn(() => json(409, {
+            code: 'custom_domain_claim_required',
+            verification: { name: '_puter.www.example.com', value: 'token-1' },
+        }));
+        serveDomains({ routes: { 'POST ': add } });
+        await openWebsite();
+        turnOnDomain();
+        domainField().val('www.example.com');
+
+        await submitWith('my-site');
+
+        expect($('.dashboard-publish-claim').prop('hidden')).toBe(false);
+        expect($('.dashboard-publish-claim .dashboard-dns-record-type').text()).toBe('TXT');
+        expect($('.dashboard-publish-claim .dashboard-copy-value').map((_, el) => el.value).get())
+            .toEqual(['_puter.www.example.com', 'token-1']);
+        expect(submitLabel()).toBe('custom_domain_verify_and_add');
+        expect(status()).toBe('publish_site_live');
+
+        await submitWith();
+        expect(status()).toBe('publish_domain_failed\ncustom_domain_claim_not_found');
+
+        // A claim is for one hostname; editing it starts over.
+        domainField().val('www.example.net').trigger('input');
+        expect($('.dashboard-publish-claim').prop('hidden')).toBe(true);
+        expect(submitLabel()).toBe('custom_domain_add');
+
+        // Back to the claimed hostname, its record and the verify step return together.
+        domainField().val('www.example.com').trigger('input');
+        expect($('.dashboard-publish-claim').prop('hidden')).toBe(false);
+        expect(submitLabel()).toBe('custom_domain_verify_and_add');
+    });
+
+    describe('on a plan without custom domains', () => {
+        beforeEach(() => {
+            window.UIUpgradeAccount = vi.fn(function () {
+                this.open_as_window = vi.fn();
+            });
+        });
+
+        it('offers the upgrade in place of the field, leaving focus on the switch', async () => {
+            serveDomains({ list: { items: [], canAdd: false } });
+            await openWebsite();
+            domainSwitch().get(0).focus();
+            turnOnDomain();
+
+            expect(shown('domain')).toBe(false);
+            expect($('.dashboard-publish-upsell').prop('hidden')).toBe(false);
+            expect(document.activeElement).toBe(domainSwitch().get(0));
+            $('.dashboard-publish-upgrade').trigger('click');
+            expect(window.UIUpgradeAccount).toHaveBeenCalled();
+        });
+
+        it('does not publish while the switch asks for a domain it cannot add', async () => {
+            serveDomains({ list: { items: [], canAdd: false } });
+            await openWebsite();
+            turnOnDomain();
+            await submitWith('my-site');
+            expect(status()).toBe('publish_custom_domain_needs_plan');
+            expect(puter.hosting.create).not.toHaveBeenCalled();
+        });
+
+        it('unlocks the field once the upgrade goes through', async () => {
+            let can_add = false;
+            serveDomains({ list: () => ({ items: [], canAdd: can_add }) });
+            await openWebsite();
+            turnOnDomain();
+            $('.dashboard-publish-upgrade').trigger('click');
+
+            can_add = true;
+            window.dispatchEvent(new CustomEvent('puter:subscription:changed'));
+            await flush();
+
+            expect(shown('domain')).toBe(true);
+            expect($('.dashboard-publish-upsell').prop('hidden')).toBe(true);
+            expect(document.activeElement).toBe(domainField().get(0));
+        });
+
+        it('only listens for a plan change once it has offered the upgrade', async () => {
+            serveDomains({ list: { items: [], canAdd: false } });
+            const listen = vi.spyOn(window, 'addEventListener');
+            try {
+                await openWebsite();
+                turnOnDomain();
+                expect(listen.mock.calls.map(([type]) => type)).not.toContain('puter:subscription:changed');
+                $('.dashboard-publish-upgrade').trigger('click');
+                expect(listen.mock.calls.map(([type]) => type)).toContain('puter:subscription:changed');
+            } finally {
+                listen.mockRestore();
+            }
+        });
+
+        it('explains the plan without a button where there is no upgrade flow', async () => {
+            delete window.UIUpgradeAccount;
+            serveDomains({ list: { items: [], canAdd: false } });
+            await openWebsite();
+            turnOnDomain();
+            expect($('.dashboard-publish-upgrade')).toHaveLength(0);
+            await submitWith('my-site');
+            expect(status()).toBe('custom_domain_error_plan');
+        });
+
+        it('finishes with the live site when adding the domain turns out to need a plan', async () => {
+            serveDomains({ routes: { 'POST ': () => json(402, { code: 'subscription_required' }) } });
+            await openWebsite();
+            turnOnDomain();
+            domainField().val('www.example.com');
+            await submitWith('my-site');
+
+            expect(status()).toBe('publish_domain_failed\ncustom_domain_error_plan');
+            expect($('.dashboard-publish-upsell').prop('hidden')).toBe(false);
+            expect(submitLabel()).toBe('done');
+
+            await submitWith();
+            expect(puter.hosting.create).toHaveBeenCalledTimes(1);
+            expect(requests('POST')).toHaveLength(1);
+            expect($('.dashboard-form-done p').text()).toBe('website_published');
+            expect($('.dashboard-publish-domain')).toHaveLength(0);
+        });
+    });
+});
+
 describe('publish worker', () => {
     it('always needs a verified account', async () => {
         await openPublishWorkerDialog({ name: 'api.js', path: '/alice/api.js' });

src/gui/src/UI/Dashboard/publishDomain.js

@@ -0,0 +1,425 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// The custom domain part of the Publish Website dialog: a switch that asks
+// for a domain, an upgrade prompt where the plan doesn't include one, and,
+// once the site is live, the domain's DNS records with a status check.
+
+import { isPlausibleHostname, normalizeHostnameInput } from '../../helpers/customDomainHostname.js';
+import {
+    CUSTOM_DOMAIN_HOSTNAME_ERRORS,
+    customDomainErrorText,
+    customDomainsRequest,
+    customDomainStatus,
+    formatCustomDomainPrice,
+    mergeCustomDomainRefresh,
+} from '../../helpers/customDomains.js';
+import { has_upgrade_flow, open_upgrade_flow } from '../../helpers/planGate.js';
+import { SVG } from './UIDashboardDialog.js';
+import { copyRowHtml } from './UIDashboardFormDialog.js';
+
+/** @typedef {import('../../helpers/customDomains.js').CustomDomain} CustomDomain */
+/** @typedef {import('../../helpers/customDomains.js').CustomDomainRecord} CustomDomainRecord */
+/** @typedef {import('./UIDashboardFormDialog.js').FormDialog} FormDialog */
+/** @typedef {import('./UIDashboardFormDialog.js').FormDialogField} FormDialogField */
+
+const t = (key, args = []) => i18n(key, args, false);
+
+const ICONS = {
+    open: SVG('<path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><path d="M15 3h6v6"/><path d="M10 14L21 3"/>'),
+    globe: SVG('<circle cx="12" cy="12" r="9"/><path d="M3 12h18"/><path d="M12 3a14 14 0 0 1 0 18a14 14 0 0 1 0-18z"/>'),
+    sparkle: SVG('<path d="M12 3l1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9z"/><path d="M19 16l.8 2.2L22 19l-2.2.8L19 22l-.8-2.2L16 19l2.2-.8z"/>'),
+};
+
+const BADGE_KEYS = {
+    active: 'custom_domain_badge_active',
+    pending: 'custom_domain_badge_pending',
+    failed: 'custom_domain_badge_failed',
+};
+
+/**
+ * An icon link opening `url` in a new tab, beside a compact copy row.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export const openLinkHtml = (url) =>
+    `<a class="dashboard-dialog-btn dashboard-dialog-btn-quiet dashboard-icon-btn dashboard-publish-open" href="${html_encode(url)}"`
+    + ` target="_blank" rel="noopener noreferrer" aria-label="${i18n('open_in_new_tab')}" title="${i18n('open_in_new_tab')}">${ICONS.open}</a>`;
+
+/**
+ * DNS records as cards: the type, then the name and value, each with a Copy
+ * button the form dialog wires.
+ *
+ * @param {CustomDomainRecord[]} records
+ * @param {{ isApex?: boolean }} [domain] A root domain's routing record can
+ *   be any of the record types that alias a root.
+ * @returns {string}
+ */
+export const dnsRecordsHtml = (records, { isApex = false } = {}) => records.map((record) => {
+    const type = isApex && record.purpose === 'routing' ? t('custom_domain_record_type_apex') : record.type;
+    const field = (labelKey, value) => '<div class="dashboard-dns-record-field">'
+        + `<span class="dashboard-dns-record-label">${i18n(labelKey)}</span>`
+        + copyRowHtml({ value, label: `${type} ${t(labelKey)}`, compact: true })
+        + '</div>';
+    return '<div class="dashboard-dns-record">'
+        + '<div class="dashboard-dns-record-head">'
+        + `<span class="dashboard-dns-record-type">${html_encode(type)}</span>`
+        + (record.required === false ? `<span class="dashboard-dns-record-optional">${i18n('custom_domain_optional')}</span>` : '')
+        + '</div>'
+        + field('name', record.name)
+        + field('custom_domain_record_value', record.value)
+        + '</div>';
+}).join('');
+
+/**
+ * The done screen's account of a domain: its status, and until it's
+ * connected, the records still to set.
+ *
+ * @param {CustomDomain} domain
+ * @returns {string}
+ */
+export const domainSummaryHtml = (domain) => {
+    const status = customDomainStatus(domain);
+    let h = '<div class="dashboard-publish-domain-head">'
+        + `<span class="dashboard-publish-domain-icon">${ICONS.globe}</span>`
+        + `<span class="dashboard-publish-domain-host">${html_encode(domain.hostname)}</span>`
+        + `<span class="dashboard-publish-domain-badge" data-status="${status}">${i18n(BADGE_KEYS[status])}</span>`
+        + '</div>';
+    if ( status === 'active' ) {
+        const url = `https://${domain.hostname}`;
+        h += copyRowHtml({ value: url, label: domain.hostname, compact: true, after: openLinkHtml(url) });
+    } else {
+        if ( status === 'failed' && domain.statusDetail ) {
+            h += `<p class="dashboard-publish-domain-detail">${html_encode(domain.statusDetail)}</p>`;
+        }
+        h += `<p class="dashboard-form-hint">${i18n('custom_domain_records_c2a')}</p>`;
+        h += `<div class="dashboard-dns-records">${dnsRecordsHtml(domain.records ?? [], domain)}</div>`;
+        if ( domain.isApex ) {
+            h += `<p class="dashboard-form-hint">${i18n('custom_domain_apex_hint')}</p>`;
+            h += `<button type="button" class="dashboard-publish-link-btn dashboard-publish-domain-www">${i18n('custom_domain_no_root_alias')}</button>`;
+        }
+    }
+    if ( domain.redirectFrom ) {
+        h += `<p class="dashboard-form-hint">${i18n('custom_domain_redirect_note', [domain.hostname, domain.redirectFrom])}</p>`;
+    }
+    if ( status !== 'active' ) {
+        h += '<div class="dashboard-publish-domain-actions">'
+            + '<button type="button" class="dashboard-dialog-btn dashboard-dialog-btn-quiet dashboard-publish-domain-check">'
+            + '<span class="dashboard-form-spinner" aria-hidden="true"></span>'
+            + `<span>${i18n('custom_domain_check_status')}</span>`
+            + '</button>'
+            + '</div>';
+    }
+    return h;
+};
+
+/**
+ * The switch and the domain field. Both start hidden: the switch shows once
+ * the server answers that it has custom domains.
+ *
+ * @returns {FormDialogField[]}
+ */
+export const publishDomainFields = () => [
+    {
+        name: 'useDomain',
+        type: 'switch',
+        label: i18n('publish_custom_domain'),
+        hint: i18n('publish_custom_domain_hint'),
+        hidden: true,
+    },
+    {
+        name: 'domain',
+        label: i18n('custom_domain_hostname_label'),
+        placeholder: 'www.example.com',
+        hint: i18n('publish_custom_domain_dns_hint'),
+        hidden: true,
+        attrs: {
+            inputmode: 'url',
+            enterkeyhint: 'go',
+            autocomplete: 'off',
+            autocapitalize: 'off',
+            autocorrect: 'off',
+            spellcheck: 'false',
+            'data-gramm_editor': 'false',
+        },
+    },
+];
+
+/**
+ * @typedef {object} PublishDomain
+ * @property {() => boolean} addable Whether the switch is on and the plan
+ *   lets a domain be added.
+ * @property {(live: boolean) => string | null | false} prepare Before each
+ *   submit: null when no domain is to be added (including when the site is
+ *   `live` and the plan can't add one), false when the form can't go ahead
+ *   (the dialog says why), else the hostname to add.
+ * @property {(hostname: string, site: { name: string, url: string }) => Promise<CustomDomain | null>} attach
+ *   Adds the hostname to the live site, or moves it there when it's already
+ *   on the account. Null when it didn't; the dialog says why.
+ * @property {(domain: CustomDomain) => string} doneHtml The done screen's domain part.
+ * @property {() => boolean} claiming Whether an ownership record for the
+ *   typed hostname is on screen, waiting to be verified.
+ */
+
+/**
+ * Wires the custom domain fields of a publish form dialog.
+ *
+ * @param {FormDialog} dialog
+ * @param {object} opts
+ * @param {() => void} opts.onChange Runs when what the submit button does may
+ *   have changed: the switch, the plan, or a claim to verify.
+ * @returns {PublishDomain}
+ */
+export const setupPublishDomain = (dialog, { onChange }) => {
+    const { $dialog } = dialog;
+    const $switch = dialog.field('useDomain');
+    const $input = dialog.field('domain');
+    const $field = $input.closest('.dashboard-form-field');
+    const $hint = $field.find('.dashboard-form-hint');
+    const id = $input.attr('id');
+
+    const upgradable = has_upgrade_flow();
+    $field.after(
+        `<div class="dashboard-publish-upsell" hidden>`
+        + `<span class="dashboard-publish-upsell-icon">${ICONS.sparkle}</span>`
+        + '<div class="dashboard-publish-upsell-text">'
+        + `<p class="dashboard-publish-upsell-title">${i18n('publish_custom_domain_upsell_title')}</p>`
+        + (upgradable ? `<p class="dashboard-form-hint">${i18n('publish_custom_domain_upsell_text')}</p>` : '')
+        + '</div>'
+        + (upgradable ? `<button type="button" class="dashboard-dialog-btn dashboard-dialog-btn-primary dashboard-publish-upgrade">${i18n('billing.upgrade')}</button>` : '')
+        + '</div>'
+        + '<div class="dashboard-publish-claim" hidden>'
+        + `<p class="dashboard-publish-claim-text">${i18n('custom_domain_claim_c2a')}</p>`
+        + '<div class="dashboard-dns-records"></div>'
+        + '</div>'
+        + `<datalist id="${id}-owned"></datalist>`,
+    );
+    const $upsell = $dialog.find('.dashboard-publish-upsell');
+    const $claim = $dialog.find('.dashboard-publish-claim');
+    const $owned = $dialog.find(`#${id}-owned`);
+    $input.attr('list', `${id}-owned`);
+
+    let available = false;
+    let can_add = true;
+    let price = null;
+    /** @type {CustomDomain[]} */
+    let owned = [];
+    /** The hostname whose ownership record is on screen. */
+    let claim_for = null;
+    /** @type {CustomDomain | null} */
+    let shown = null;
+    /** Whether the site is published, so the domain is all that's left. */
+    let live = false;
+
+    const typed = () => normalizeHostnameInput($input.val());
+    const owned_named = (hostname) => owned.find((domain) => domain.hostname === hostname);
+    const wanted = () => available && $switch.prop('checked');
+    const addable = () => wanted() && can_add;
+
+    const update_hint = () => {
+        const existing = owned_named(typed());
+        $hint.text(existing
+            ? t('publish_custom_domain_moves', [`${existing.site}.${window.hosting_domain}`])
+            : [! live && t('publish_custom_domain_dns_hint'), price && t('custom_domain_price_note', [price])].filter(Boolean).join(' '));
+    };
+
+    const sync = () => {
+        const on = wanted();
+        dialog.showField('domain', on && can_add);
+        $upsell.prop('hidden', ! on || can_add);
+        $claim.prop('hidden', ! on || ! can_add || claim_for !== typed());
+        update_hint();
+        onChange();
+    };
+
+    const load = async () => {
+        let res;
+        try {
+            res = await customDomainsRequest('GET');
+        } catch {
+            return;
+        }
+        // No custom domain API on this Puter, or none for this account:
+        // the option stays out of the way.
+        if ( ! res.ok || ! Array.isArray(res.data?.items) ) return;
+        owned = res.data.items;
+        can_add = res.data.canAdd !== false;
+        price = formatCustomDomainPrice(res.data.pricing);
+        $owned.html(owned.map((domain) => `<option value="${html_encode(domain.hostname)}"></option>`).join(''));
+        if ( ! available ) {
+            available = true;
+            dialog.showField('useDomain', true);
+        }
+        sync();
+    };
+    load();
+
+    // The field takes focus as the switch reveals it. The upgrade prompt
+    // doesn't: a second Space meant for the switch would open the upgrade.
+    $switch.on('change', () => {
+        sync();
+        if ( addable() ) $input.get(0)?.focus({ preventScroll: true });
+    });
+    // A claim's record shows only while its hostname is the one typed.
+    $input.on('input', sync);
+
+    // Once an upgrade lands, the field unlocks where the prompt was. The
+    // dialog is modal, so only its own prompt can change the plan meanwhile.
+    const on_plan_change = async () => {
+        if ( ! document.contains($dialog.get(0)) ) {
+            window.removeEventListener('puter:subscription:changed', on_plan_change);
+            return;
+        }
+        const had = can_add;
+        await load();
+        if ( ! had && addable() ) $input.get(0)?.focus({ preventScroll: true });
+    };
+    $dialog.on('click', '.dashboard-publish-upgrade', () => {
+        if ( ! open_upgrade_flow() ) return;
+        window.addEventListener('puter:subscription:changed', on_plan_change);
+    });
+
+    // -- Done screen --
+
+    /** Encoded HTML into the done screen's status line; empty clears it. */
+    const set_done_status = (html, error = false) => {
+        $dialog.find('.dashboard-publish-domain-status').html(html)
+            .toggleClass('dashboard-publish-domain-status-error', error);
+    };
+    const render_done = (focus_selector) => {
+        const $section = $dialog.find('.dashboard-publish-domain-summary');
+        $section.html(domainSummaryHtml(shown));
+        const el = $section.find(focus_selector).get(0)
+            ?? $section.find('.dashboard-copy-value').get(0)
+            ?? $dialog.find('.dashboard-form-done-btn').get(0);
+        el?.focus({ preventScroll: true });
+    };
+    const DONE_ACTIONS = '.dashboard-publish-domain-check, .dashboard-publish-domain-www';
+    let done_busy = false;
+    /**
+     * Runs a done-screen request with `$btn` busy and the other actions held,
+     * since each answer redraws the domain; resolves with the response, or null.
+     */
+    const done_request = async ($btn, method, path) => {
+        done_busy = true;
+        $dialog.find(DONE_ACTIONS).prop('disabled', true);
+        $btn.addClass('dashboard-form-busy').attr('aria-busy', 'true');
+        set_done_status('');
+        try {
+            const res = await customDomainsRequest(method, path);
+            if ( res.ok ) return res;
+            set_done_status(html_encode(customDomainErrorText(res)), true);
+        } catch {
+            set_done_status(i18n('custom_domain_error_generic'), true);
+        } finally {
+            done_busy = false;
+            $dialog.find(DONE_ACTIONS).prop('disabled', false);
+            $btn.removeClass('dashboard-form-busy').removeAttr('aria-busy');
+        }
+        return null;
+    };
+    $dialog.on('click', '.dashboard-publish-domain-check', async function () {
+        if ( ! shown || done_busy ) return;
+        const res = await done_request($(this), 'GET', `/${encodeURIComponent(shown.uuid)}`);
+        if ( ! res ) return;
+        shown = mergeCustomDomainRefresh(shown, res.data);
+        render_done('.dashboard-publish-domain-check');
+        const status = customDomainStatus(shown);
+        set_done_status(status === 'active'
+            ? i18n('custom_domain_success_note', [shown.hostname, `${shown.site}.${window.hosting_domain}`])
+            : i18n(status === 'failed' ? 'custom_domain_status_failed' : 'custom_domain_status_pending', [shown.hostname]));
+    });
+    // Same domain, so the month already paid covers the www hostname.
+    $dialog.on('click', '.dashboard-publish-domain-www', async function () {
+        if ( ! shown || done_busy ) return;
+        const res = await done_request($(this), 'POST', `/${encodeURIComponent(shown.uuid)}/use-www`);
+        if ( ! res ) return;
+        shown = res.data;
+        render_done('.dashboard-publish-domain-check');
+    });
+
+    return {
+        addable,
+        prepare (live) {
+            if ( ! wanted() || (live && ! can_add) ) return null;
+            if ( ! can_add ) {
+                dialog.setStatus(t(upgradable ? 'publish_custom_domain_needs_plan' : 'custom_domain_error_plan'));
+                return false;
+            }
+            const hostname = typed();
+            $input.val(hostname);
+            if ( ! isPlausibleHostname(hostname) ) {
+                dialog.setStatus(t('custom_domain_error_invalid'), { field: 'domain' });
+                return false;
+            }
+            return hostname;
+        },
+        async attach (hostname, site) {
+            if ( ! live ) {
+                live = true;
+                update_hint();
+            }
+            const existing = owned_named(hostname);
+            const failed = (reason, field) => {
+                dialog.setStatus(`${t('publish_domain_failed', [site.url])}\n${reason}`, field ? { field } : undefined);
+                return null;
+            };
+            let res;
+            try {
+                res = existing
+                    ? await customDomainsRequest('PATCH', `/${encodeURIComponent(existing.uuid)}`, { site: site.name })
+                    : await customDomainsRequest('POST', '', { site: site.name, hostname });
+            } catch {
+                return failed(t('custom_domain_error_generic'));
+            }
+            if ( res.ok ) {
+                claim_for = null;
+                return res.data;
+            }
+            // Held by another account: shown its ownership record the first
+            // time; a retry that still can't see the record says so.
+            const verification = res.data?.verification;
+            if ( res.data?.code === 'custom_domain_claim_required' && verification ) {
+                const retry = claim_for === hostname;
+                claim_for = hostname;
+                $claim.find('.dashboard-dns-records').html(dnsRecordsHtml([{ type: 'TXT', name: verification.name, value: verification.value }]));
+                sync();
+                if ( retry ) return failed(t('custom_domain_claim_not_found'));
+                dialog.setStatus(t('publish_site_live', [site.url]), { kind: 'info' });
+                return null;
+            }
+            if ( res.status === 402 && res.data?.code === 'subscription_required' ) {
+                can_add = false;
+                sync();
+            }
+            return failed(customDomainErrorText(res), CUSTOM_DOMAIN_HOSTNAME_ERRORS.has(res.data?.code) ? 'domain' : undefined);
+        },
+        doneHtml (domain) {
+            shown = domain;
+            // The summary is redrawn after each check; the status line stays,
+            // so screen readers announce what changed and not the records again.
+            return '<section class="dashboard-publish-domain">'
+                + `<div class="dashboard-publish-domain-summary" aria-live="off">${domainSummaryHtml(domain)}</div>`
+                + '<p class="dashboard-publish-domain-status" role="status" aria-live="polite"></p>'
+                + '</section>';
+        },
+        claiming: () => addable() && claim_for !== null && claim_for === typed(),
+    };
+};

src/gui/src/UI/UIWindow.js

@@ -3446,6 +3446,10 @@ window.update_window_path = async function (el_window, target_path) {
     else if ( target_path !== '/' ) {
         try {
             puter.fs.stat({ path: target_path, consistency: 'eventual' }).then(fsentry => {
+                // the window may have moved on while this stat was in flight
+                if ( $(el_window).attr('data-path') !== html_encode(target_path) ) {
+                    return;
+                }
                 $(el_window).removeClass(`window-${ $(el_window).attr('data-uid')}`);
                 $(el_window).addClass(`window-${ fsentry.id}`);
                 $(el_window).attr('data-uid', fsentry.id);

src/gui/src/UI/UIWindowAppFeedback.js

@@ -54,7 +54,8 @@ async function UIWindowAppFeedback (options) {
         let sending = false;
         let closed = false;
 
-        const authToken = puter.authToken ?? window.auth_token;
+        // The feedback embed runs without puter.js.
+        const authToken = globalThis.puter?.authToken ?? window.auth_token;
         const target_params = options.app
             ? { app: options.app }
             : { origin: options.origin };

src/gui/src/UI/UIWindowAttachCustomDomain.js

@@ -18,31 +18,25 @@
  */
 
 import { isPlausibleHostname, normalizeHostnameInput } from '../helpers/customDomainHostname.js';
+import {
+    customDomainErrorText,
+    customDomainsRequest,
+    customDomainStatus as statusOf,
+    formatCustomDomainPrice,
+    mergeCustomDomainRefresh,
+} from '../helpers/customDomains.js';
 
 let attach_modal_seq = 0;
 
 const SUCCESS_AUTOCLOSE_MS = 1800;
 const COPIED_RESET_MS = 1400;
 
-/** API error code → message key; anything unlisted gets the generic error. */
-const ERROR_KEYS = {
-    invalid_hostname: 'custom_domain_error_invalid',
-    custom_domain_taken: 'custom_domain_error_taken',
-    custom_domain_limit_reached: 'custom_domain_error_limit',
-    custom_domain_rejected: 'custom_domain_error_rejected',
-    site_not_found: 'custom_domain_error_site',
-    custom_domain_not_found: 'custom_domain_error_not_found',
-    custom_domains_not_enabled: 'custom_domain_not_enabled',
-    custom_domains_permission_required: 'custom_domain_error_generic',
-};
-
-/** Domain status → the badge shown for it; anything else reads as pending. */
+/** Domain status → the badge shown for it. */
 const STATUS_BADGE_KEYS = {
     active: 'custom_domain_badge_active',
     pending: 'custom_domain_badge_pending',
     failed: 'custom_domain_badge_failed',
 };
-const statusOf = (domain) => (domain?.status in STATUS_BADGE_KEYS ? domain.status : 'pending');
 
 const svg = (body, strokeWidth = 2) =>
     `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="${strokeWidth}" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
@@ -55,19 +49,6 @@ const ICON_ALERT = svg('<circle cx="12" cy="12" r="9"/><path d="M12 7.5v5"/><pat
 const ICON_PLUS = svg('<path d="M12 5v14M5 12h14"/>', 2.2);
 const ICON_X = svg('<line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/>', 2.2);
 
-const format_price = (pricing) => {
-    if ( ! pricing || typeof pricing.amount !== 'number' ) return null;
-    try {
-        return new Intl.NumberFormat(undefined, {
-            style: 'currency',
-            currency: pricing.currency || 'USD',
-            minimumFractionDigits: 2,
-        }).format(pricing.amount);
-    } catch {
-        return null;
-    }
-};
-
 /**
  * "Connect a custom domain to this site" modal, behind
  * `puter.hosting.attach()`. The user picks one of their domains (moving it
@@ -254,35 +235,7 @@ async function UIWindowAttachCustomDomain (options) {
             focusedBeforeBusy = null;
         };
 
-        const api = async (method, path = '', body) => {
-            const res = await fetch(`${window.api_origin}/custom-domains${path}`, {
-                method,
-                headers: {
-                    'Authorization': `Bearer ${authToken}`,
-                    ...(body ? { 'Content-Type': 'application/json' } : {}),
-                },
-                body: body ? JSON.stringify(body) : undefined,
-            });
-            let data = null;
-            try {
-                data = await res.json();
-            } catch {
-                // Non-JSON body; callers go by the status.
-            }
-            return { status: res.status, ok: res.ok, data };
-        };
-        // A known code gets our wording; anything else shows what the server
-        // said, which beats a generic message when something is misconfigured.
-        const errorFor = (res) => {
-            if ( res.status === 402 ) return text('custom_domain_error_plan');
-            if ( res.status === 429 ) return text('custom_domain_error_rate_limited');
-            const key = ERROR_KEYS[res.data?.code];
-            if ( key ) return text(key);
-            if ( typeof res.data?.message === 'string' && res.data.message ) {
-                return res.data.message;
-            }
-            return `${text('custom_domain_error_generic')} (HTTP ${res.status})`;
-        };
+        const api = (method, path = '', body) => customDomainsRequest(method, path, body, authToken);
 
         // Escape backs out of a pending confirmation first. Escape, the
         // backdrop and the close buttons all dismiss, except while a request
@@ -503,7 +456,7 @@ async function UIWindowAttachCustomDomain (options) {
             try {
                 const res = await api('PATCH', `/${encodeURIComponent(item.uuid)}`, { site: subdomain });
                 if ( ! res.ok ) {
-                    showError('list', errorFor(res));
+                    showError('list', customDomainErrorText(res));
                     return;
                 }
                 settleOn(res.data);
@@ -524,7 +477,7 @@ async function UIWindowAttachCustomDomain (options) {
             try {
                 const res = await api('DELETE', `/${encodeURIComponent(item.uuid)}`);
                 if ( ! res.ok && res.status !== 404 ) {
-                    showError(pane, errorFor(res));
+                    showError(pane, customDomainErrorText(res));
                     return false;
                 }
                 // A removed domain is no answer to hand the caller.
@@ -611,7 +564,7 @@ async function UIWindowAttachCustomDomain (options) {
                     return;
                 }
                 if ( ! res.ok ) {
-                    showError('add', errorFor(res));
+                    showError('add', customDomainErrorText(res));
                     return;
                 }
                 hideClaim();
@@ -650,7 +603,7 @@ async function UIWindowAttachCustomDomain (options) {
                 .toggle(!!domain.statusDetail && status !== 'active');
             const $redirect = $overlay.find('.custom-domain-redirect').toggle(!!domain.redirectFrom);
             if ( domain.redirectFrom ) {
-                $redirect.html(i18n('custom_domain_redirect_note', [domain.redirectFrom, domain.hostname]));
+                $redirect.html(i18n('custom_domain_redirect_note', [domain.hostname, domain.redirectFrom]));
             }
             $overlay.find('.custom-domain-apex').toggle(domain.isApex === true);
             $overlay.find('.custom-domain-use-www').toggle(domain.isApex === true && status !== 'active');
@@ -670,22 +623,10 @@ async function UIWindowAttachCustomDomain (options) {
             try {
                 const res = await api('GET', `/${encodeURIComponent(chosen.uuid)}`);
                 if ( ! res.ok ) {
-                    showError('records', errorFor(res));
+                    showError('records', customDomainErrorText(res));
                     return;
                 }
-                // A domain that is no longer pending comes back with only its
-                // routing record, and a GET never repeats the provider or the
-                // redirect; keep what was shown when it was added.
-                const known = chosen.records ?? [];
-                const redirect = known.filter((r) => r.purpose === 'redirect');
-                const fresh = (res.data.records?.length > 1 ? res.data.records : known)
-                    .filter((r) => r.purpose !== 'redirect');
-                const next = {
-                    ...res.data,
-                    dnsProvider: chosen.dnsProvider,
-                    redirectFrom: chosen.redirectFrom,
-                    records: [...fresh.slice(0, 1), ...redirect, ...fresh.slice(1)],
-                };
+                const next = mergeCustomDomainRefresh(chosen, res.data);
                 if ( statusOf(next) === 'active' ) {
                     showSuccess(next);
                     return;
@@ -706,7 +647,7 @@ async function UIWindowAttachCustomDomain (options) {
             try {
                 const res = await api('POST', `/${encodeURIComponent(chosen.uuid)}/use-www`);
                 if ( ! res.ok ) {
-                    showError('records', errorFor(res));
+                    showError('records', customDomainErrorText(res));
                     return;
                 }
                 chosen = res.data;
@@ -758,7 +699,7 @@ async function UIWindowAttachCustomDomain (options) {
                     return;
                 }
                 renderList(res.data?.items ?? []);
-                const price = format_price(res.data?.pricing);
+                const price = formatCustomDomainPrice(res.data?.pricing);
                 if ( price ) {
                     $overlay.find('.custom-domain-price').text(text('custom_domain_price_note', [price])).show();
                 }

src/gui/src/appsEmbed.js

@@ -24,6 +24,8 @@ import { createAppBrowser } from './UI/Dashboard/AppBrowser.js';
 import { appTileLink } from './UI/Dashboard/appLink.js';
 import { installAppIconFallback } from './helpers/appIcon.js';
 import { guestAppLaunchUrl, launchAppInTab } from './helpers/appTabLaunch.js';
+import { embedHostTheme, forceColorScheme } from './helpers/embedHostTheme.js';
+import { embedSession } from './helpers/embedSession.js';
 
 window.$ = window.jQuery = jQuery;
 window.html_encode = value => encode(String(value ?? ''), { mode: 'nonAsciiPrintable' });
@@ -45,6 +47,10 @@ try {
     window.locale = JSON.parse(localStorage.getItem('user_preferences') || '{}')?.language || 'en';
 } catch { /* Corrupt preferences must not prevent loading apps. */ }
 const localeReady = loadLocale(window.locale);
+// The host names its user and theme in the fragment, which can change without a reload.
+window.addEventListener('hashchange', () => window.location.reload());
+const hostTheme = embedHostTheme(window.location.hash);
+if ( hostTheme ) forceColorScheme(document, hostTheme);
 // Apps whose launch is still fetching; a second click would open a second tab.
 const launching = new Set();
 
@@ -98,31 +104,12 @@ function launchTile ({ appName, targetLink }) {
         .finally(() => launching.delete(appName));
 }
 
-/**
- * The GUI session, from local storage or else the session cookie. Safari keys a
- * frame's local storage by the top-level origin, so under a sibling subdomain
- * the GUI's stored token is out of reach while its cookie is still sent.
- */
-async function readSession () {
-    let stored = null;
-    try {
-        stored = localStorage.getItem('auth_token_v2');
-    } catch { /* Storage the browser refuses holds no session; the cookie may. */ }
-    if ( stored ) return stored;
-    const response = await fetch('/get-gui-token', { credentials: 'include' });
-    // Only a 401 means there is no session; a rate limit or server error
-    // must not pass a signed-in user off as signed out.
-    if ( response.status === 401 ) return null;
-    if ( ! response.ok ) throw new Error(`Session lookup responded ${response.status}`);
-    return (await response.json())?.token || null;
-}
-
 /**
  * Signed in, the user's own apps through the SDK. Without a session, the
  * recommended apps the page was rendered with, and no SDK.
  */
 async function mount () {
-    window.auth_token = await readSession();
+    window.auth_token = (await embedSession(config.apiOrigin, window.location.hash))?.token ?? null;
     const guestApps = window.auth_token ? undefined : config.guestApps;
     if ( !window.auth_token && !guestApps?.length ) throw new Error('No apps to show without a session');
 

src/gui/src/css/apps-embed.css

@@ -15,6 +15,39 @@ body {
     height: 100%;
 }
 
+/* Empty until the session check and the SDK finish; matches <puter-user-menu>'s spinner. */
+#app-browser:empty {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+#app-browser:empty::after {
+    content: '';
+    width: 22px;
+    height: 22px;
+    box-sizing: border-box;
+    border: 2px solid rgba(0, 0, 0, .12);
+    border-top-color: #555;
+    border-radius: 50%;
+    animation: app-browser-spin .7s linear infinite;
+}
+
+@keyframes app-browser-spin {
+    to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    #app-browser:empty::after { animation-duration: 1.6s; }
+}
+
+@media (prefers-color-scheme: dark) {
+    #app-browser:empty::after {
+        border-color: rgba(255, 255, 255, .15);
+        border-top-color: #ccc;
+    }
+}
+
 #app-browser .dashboard-section-apps {
     width: 100%;
 }

src/gui/src/css/dashboard.css

@@ -10590,6 +10590,253 @@ body.dashboard-mode .notifications-close-all {
     overflow-wrap: anywhere;
 }
 
+/* Contact Us: a message with screenshots or recordings attached */
+.dashboard-dialog.dashboard-contact-dialog {
+    width: min(500px, 100%);
+}
+
+.dashboard-contact-dialog .dashboard-form-input[name='message'] {
+    min-height: 132px;
+}
+
+.dashboard-contact-attachments {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.dashboard-contact-dropzone {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    width: 100%;
+    margin: 0;
+    padding: 12px 14px;
+    border: 1px dashed var(--dashboard-border);
+    border-radius: 10px;
+    background: transparent;
+    color: var(--dashboard-text-primary);
+    font: inherit;
+    text-align: start;
+    cursor: pointer;
+    box-sizing: border-box;
+    transition: border-color 0.15s ease, background-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.dashboard-contact-dropzone-icon {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 34px;
+    height: 34px;
+    border-radius: 50%;
+    background: var(--select-tint);
+    color: var(--select-color);
+}
+
+.dashboard-contact-dropzone-icon svg {
+    width: 17px;
+    height: 17px;
+}
+
+.dashboard-contact-dropzone-text {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    min-width: 0;
+}
+
+.dashboard-contact-dropzone-label,
+.dashboard-contact-dropzone-drop {
+    font-size: 13px;
+    font-weight: 600;
+}
+
+.dashboard-contact-dropzone-drop {
+    display: none;
+    color: var(--select-text);
+}
+
+.dashboard-contact-dropzone-hint {
+    font-size: 12px;
+    line-height: 1.4;
+    color: var(--dashboard-text-muted);
+}
+
+@media (hover: hover) {
+    .dashboard-contact-dropzone:hover:not(:disabled) {
+        border-color: var(--select-color);
+        background: var(--select-tint-weak);
+    }
+}
+
+.dashboard-contact-dropzone:focus-visible {
+    outline: none;
+    border-color: var(--select-color);
+    box-shadow: 0 0 0 3px var(--select-ring);
+}
+
+.dashboard-contact-dropzone:disabled {
+    cursor: default;
+    opacity: 0.6;
+}
+
+/* Files dragged anywhere over the dialog land here. */
+.dashboard-contact-dragging .dashboard-contact-dropzone {
+    border-style: solid;
+    border-color: var(--select-color);
+    background: var(--select-tint);
+    box-shadow: 0 0 0 3px var(--select-ring);
+}
+
+.dashboard-contact-dragging .dashboard-contact-dropzone-label {
+    display: none;
+}
+
+.dashboard-contact-dragging .dashboard-contact-dropzone-drop {
+    display: block;
+}
+
+.dashboard-contact-files {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.dashboard-contact-files[hidden] {
+    display: none;
+}
+
+.dashboard-contact-file {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    min-width: 0;
+    padding: 6px;
+    border: 1px solid var(--dashboard-border);
+    border-radius: 10px;
+    background: var(--dashboard-input-background);
+    animation: dashboard-contact-file-in 160ms ease;
+}
+
+@keyframes dashboard-contact-file-in {
+    from {
+        opacity: 0;
+        transform: translateY(-4px);
+    }
+}
+
+.dashboard-contact-file-thumb {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 40px;
+    height: 40px;
+    border-radius: 7px;
+    overflow: hidden;
+    background: var(--dashboard-sidebar-background);
+    color: var(--dashboard-text-secondary);
+}
+
+.dashboard-contact-file-thumb img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+}
+
+.dashboard-contact-file-thumb svg {
+    width: 20px;
+    height: 20px;
+}
+
+.dashboard-contact-file-text {
+    flex: 1 1 auto;
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 0;
+}
+
+.dashboard-contact-file-name {
+    overflow: hidden;
+    font-size: 13px;
+    font-weight: 500;
+    color: var(--dashboard-text-primary);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.dashboard-contact-file-size {
+    font-size: 12px;
+    color: var(--dashboard-text-muted);
+    font-variant-numeric: tabular-nums;
+}
+
+.dashboard-contact-file-remove {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    border: none;
+    border-radius: 8px;
+    background: transparent;
+    color: var(--dashboard-text-secondary);
+    cursor: pointer;
+    transition: background 0.15s, color 0.15s;
+}
+
+.dashboard-contact-file-remove svg {
+    width: 16px;
+    height: 16px;
+}
+
+@media (hover: hover) {
+    .dashboard-contact-file-remove:hover:not(:disabled) {
+        background: var(--dashboard-hover);
+        color: var(--dashboard-text-primary);
+    }
+}
+
+.dashboard-contact-file-remove:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px var(--select-ring);
+}
+
+.dashboard-contact-file-remove:disabled {
+    cursor: default;
+    opacity: 0.5;
+}
+
+/* Sending: the files are on their way and no longer up for change. */
+.dashboard-contact-sending .dashboard-contact-file {
+    opacity: 0.7;
+}
+
+@media (pointer: coarse) {
+    .dashboard-contact-dropzone {
+        min-height: 56px;
+    }
+
+    .dashboard-contact-file-remove {
+        width: 44px;
+        height: 44px;
+    }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .dashboard-contact-file {
+        animation: none;
+    }
+}
+
 /* API token, shown once */
 .dashboard-token-warning {
     padding: 10px 12px;
@@ -10681,6 +10928,287 @@ body.dashboard-mode .notifications-close-all {
     }
 }
 
+/* ======================================
+   Publish dialog: custom domain
+   ====================================== */
+
+/* The address, once the site is live under it, reads as settled. */
+.dashboard-form-affix:has([readonly]) {
+    background: var(--dashboard-sidebar-background);
+}
+
+.dashboard-form-affix:has([readonly]):focus-within {
+    border-color: var(--dashboard-border);
+    box-shadow: none;
+}
+
+.dashboard-publish-upsell {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 12px;
+    border: 1px solid var(--dashboard-border);
+    border-radius: 12px;
+    background: var(--select-tint-weak);
+}
+
+.dashboard-publish-upsell[hidden],
+.dashboard-publish-claim[hidden] {
+    display: none;
+}
+
+.dashboard-publish-upsell-icon {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 32px;
+    height: 32px;
+    border-radius: 50%;
+    background: var(--select-tint);
+    color: var(--select-color);
+}
+
+.dashboard-publish-upsell-icon svg {
+    width: 16px;
+    height: 16px;
+}
+
+.dashboard-publish-upsell-text {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+
+.dashboard-publish-upsell-title {
+    margin: 0;
+    font-size: 13px;
+    font-weight: 600;
+    line-height: 1.4;
+    color: var(--dashboard-text-primary);
+}
+
+.dashboard-publish-upsell .dashboard-dialog-btn {
+    flex-shrink: 0;
+    min-width: 0;
+}
+
+@media (max-width: 600px) {
+    .dashboard-publish-upsell {
+        flex-wrap: wrap;
+    }
+
+    /* The text keeps to the icon's row; only the button takes its own. */
+    .dashboard-publish-upsell-text {
+        flex-basis: 0;
+    }
+
+    .dashboard-publish-upsell .dashboard-dialog-btn {
+        flex-basis: 100%;
+    }
+}
+
+.dashboard-publish-claim {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+}
+
+.dashboard-publish-claim-text {
+    margin: 0;
+    padding: 10px 12px;
+    border: 1px solid var(--dashboard-warning-border);
+    border-radius: 8px;
+    background: var(--dashboard-warning-background);
+    color: var(--dashboard-warning-text);
+    font-size: 13px;
+    line-height: 1.45;
+}
+
+/* DNS records: the type, then a copyable name and value. */
+.dashboard-dns-records {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+}
+
+/* One grid per card, so the label column fits the longest label and the
+   name and value line up. */
+.dashboard-dns-record {
+    display: grid;
+    grid-template-columns: minmax(44px, max-content) minmax(0, 1fr);
+    align-items: center;
+    gap: 8px;
+    padding: 10px;
+    border: 1px solid var(--dashboard-border);
+    border-radius: 10px;
+    background: var(--dashboard-sidebar-background);
+}
+
+.dashboard-dns-record-head {
+    grid-column: 1 / -1;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+
+.dashboard-dns-record-type {
+    padding: 2px 7px;
+    border-radius: 6px;
+    background: var(--select-tint);
+    color: var(--select-color);
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 11px;
+    font-weight: 600;
+}
+
+.dashboard-dns-record-optional {
+    font-size: 11px;
+    color: var(--dashboard-text-muted);
+}
+
+.dashboard-dns-record-field {
+    display: contents;
+}
+
+.dashboard-dns-record-label {
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--dashboard-text-secondary);
+}
+
+/* The done screen's domain, under the live address. */
+.dashboard-publish-domain {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    padding-top: 14px;
+    border-top: 1px solid var(--dashboard-border);
+}
+
+.dashboard-publish-domain-summary {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+}
+
+.dashboard-publish-domain-head {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    min-width: 0;
+}
+
+.dashboard-publish-domain-icon {
+    flex-shrink: 0;
+    display: flex;
+    color: var(--dashboard-text-muted);
+}
+
+.dashboard-publish-domain-icon svg {
+    width: 16px;
+    height: 16px;
+}
+
+.dashboard-publish-domain-host {
+    min-width: 0;
+    font-size: 14px;
+    font-weight: 600;
+    color: var(--dashboard-text-primary);
+    overflow-wrap: anywhere;
+}
+
+.dashboard-publish-domain-badge {
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    margin-left: auto;
+    padding: 2px 8px;
+    border-radius: 999px;
+    background: var(--dashboard-warning-background);
+    color: var(--dashboard-warning-text);
+    font-size: 11px;
+    font-weight: 600;
+}
+
+.dashboard-publish-domain-badge::before {
+    content: '';
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: currentColor;
+}
+
+.dashboard-publish-domain-badge[data-status='active'] {
+    background: var(--dashboard-success-background);
+    color: var(--dashboard-success-text);
+}
+
+.dashboard-publish-domain-badge[data-status='failed'] {
+    background: var(--dashboard-danger-background);
+    color: var(--dashboard-danger-text);
+}
+
+.dashboard-publish-domain-detail {
+    margin: 0;
+    font-size: 13px;
+    line-height: 1.45;
+    color: var(--dashboard-danger-text);
+    overflow-wrap: anywhere;
+}
+
+.dashboard-publish-domain-actions {
+    display: flex;
+}
+
+.dashboard-publish-domain-status {
+    margin: 0;
+    font-size: 12px;
+    line-height: 1.45;
+    color: var(--dashboard-text-secondary);
+}
+
+/* Empty, it stays in the a11y tree and gives back the gap it would claim. */
+.dashboard-publish-domain-status:empty {
+    margin-top: -10px;
+}
+
+.dashboard-publish-domain-status-error {
+    color: var(--dashboard-danger-text);
+}
+
+.dashboard-publish-link-btn {
+    align-self: flex-start;
+    padding: 0;
+    border: none;
+    background: none;
+    color: var(--dashboard-link);
+    font: inherit;
+    font-size: 12px;
+    text-align: left;
+    cursor: pointer;
+}
+
+@media (hover: hover) {
+    .dashboard-publish-link-btn:hover:not(:disabled) {
+        text-decoration: underline;
+    }
+}
+
+.dashboard-publish-link-btn:disabled {
+    opacity: 0.6;
+    cursor: default;
+}
+
+.dashboard-publish-link-btn:focus-visible {
+    outline: none;
+    border-radius: 4px;
+    box-shadow: 0 0 0 3px var(--select-ring);
+}
+
 /* ======================================
    Auth dialog (login, signup, account picker, password recovery, 2FA)
    ====================================== */
@@ -11090,7 +11618,7 @@ body.dashboard-mode .notifications-close-all {
 
 .auth-dialog .signup-terms {
     margin: 18px 0 0;
-    font-size: 12px;
+    font-size: 11px;
     line-height: 1.5;
     color: var(--dashboard-text-muted);
     text-align: center;

src/gui/src/css/feedback-embed.css

@@ -0,0 +1,17 @@
+/* Transparent, so the dialog's own scrim covers the framing page. */
+html,
+body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background: transparent;
+    font-family: "Inter", "Helvetica Neue", Helvetica, Arial, sans-serif;
+}
+
+/* A scroll over the scrim must not scroll the framing page behind it. */
+html {
+    overscroll-behavior: none;
+    /* Matches the frame's, so it stays transparent and follows the OS theme. */
+    color-scheme: light dark;
+}

src/gui/src/css/style.css

@@ -181,6 +181,20 @@ input[type=text], input[type=password], input[type=email], select {
     font-size: 14px;
 }
 
+@media (prefers-color-scheme: dark) {
+    input[type=text], input[type=password], input[type=email], select {
+        background-color: #2d2d2d;
+        border: 1px solid #555;
+        color: #e6e6e6;
+    }
+
+    input[type=text]::placeholder,
+    input[type=password]::placeholder,
+    input[type=email]::placeholder {
+        color: #999;
+    }
+}
+
 /* to prevent auto-zoom on input focus in mobile */
 .device-phone input[type=text], .device-phone input[type=password], .device-phone input[type=email], .device-phone select {
     font-size: 17px;
@@ -1478,6 +1492,18 @@ span.header-sort-icon img {
     align-items: center;
 }
 
+/* The file name shrinks so the buttons stay on one line, on screen, in a narrow dialog. */
+.window-filedialog-prompt > div {
+    min-width: 0;
+    white-space: nowrap;
+}
+
+@media (max-width: 480px) {
+    .window-filedialog-prompt .button-small {
+        padding: 0 16px;
+    }
+}
+
 .savefiledialog-filename {
     float: left;
     margin-right: 10px;
@@ -1485,10 +1511,21 @@ span.header-sort-icon img {
     border-width: 1px !important;
     height: 31px;
     flex-grow: 1;
+    min-width: 0;
     width: initial !important;
 }
 
+/* In a narrow open dialog, the upload label gives way so its buttons stay whole. */
+.window-filedialog-upload-here + div {
+    flex-shrink: 0;
+}
+
 .window-filedialog-upload-here {
+    min-width: 0;
+    margin-right: 10px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
     -webkit-font-smoothing: antialiased;
     opacity: 0.7;
     font-size: 14px;

src/gui/src/feedbackEmbed.browser.test.js

@@ -0,0 +1,252 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { chromium } from '@playwright/test';
+import express from 'express';
+import webpack from 'webpack';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inflateSync } from 'node:zlib';
+
+let browser;
+let server;
+let directory;
+let origin;
+let hostOrigin;
+let port;
+const requests = [];
+const guiRoot = fileURLToPath(new URL('../', import.meta.url));
+const sessionToken = 'feedback-embed-test-session';
+const unconfirmedToken = 'feedback-embed-test-unconfirmed';
+const sessionUser = '0b1c9a52-3f0e-4c7a-9a65-2f6d1e8b7c40';
+const unconfirmedUser = '1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f';
+const otherUser = '7d2e4f10-8a3b-4c5d-9e6f-0a1b2c3d4e5f';
+
+beforeAll(async () => {
+    directory = await mkdtemp(path.join(tmpdir(), 'puter-feedback-embed-'));
+    await new Promise((resolve, reject) => {
+        const compiler = webpack({
+            mode: 'development',
+            entry: { 'feedback-embed': path.join(guiRoot, 'src/feedbackEmbed.js') },
+            output: { path: directory, filename: '[name].min.js' },
+            module: { rules: [{ test: /jquery-3\.6\.1\.min\.js$/, type: 'javascript/auto' }] },
+        });
+        compiler.run((error, stats) => compiler.close(closeError => {
+            if ( error || closeError ) return reject(error || closeError);
+            if ( stats.hasErrors() ) return reject(new Error(stats.toString()));
+            resolve();
+        }));
+    });
+    const app = express();
+    app.use(express.json());
+    app.use((req, res, next) => {
+        requests.push({ path: req.path, query: req.query, body: req.body, auth: req.headers.authorization });
+        next();
+    });
+    app.use('/dist', express.static(directory));
+    app.use('/css', express.static(path.join(guiRoot, 'src/css')));
+    app.get('/get-gui-token', (_req, res) => res.sendStatus(401));
+    const whoamiByToken = {
+        [sessionToken]: { uuid: sessionUser, username: 'session-user', email: '[email protected]', email_confirmed: true },
+        [unconfirmedToken]: {
+            uuid: unconfirmedUser, username: 'new-user', email_confirmed: false, requires_email_confirmation: true,
+        },
+    };
+    app.get('/whoami', (req, res) => {
+        const user = whoamiByToken[req.headers.authorization?.replace(/^Bearer /, '')];
+        if ( ! user ) return res.sendStatus(401);
+        res.json(user);
+    });
+    app.get('/app-feedback/target', (req, res) => {
+        if ( req.headers.authorization !== `Bearer ${sessionToken}` ) return res.sendStatus(401);
+        if ( req.query.origin !== hostOrigin ) return res.json({ enabled: false });
+        res.json({ enabled: true, app: { name: 'notes', title: 'Notes' } });
+    });
+    app.post('/app-feedback', (req, res) => {
+        if ( req.headers.authorization !== `Bearer ${sessionToken}` ) return res.sendStatus(401);
+        res.json({});
+    });
+    // A first-party page that frames the dialog as puter.js does, recording what the embed tells it.
+    app.get('/host', (req, res) => res.send(`<!DOCTYPE html><html><body style="margin:0;background:rgb(255,0,0)">
+        <script>
+            window.received = [];
+            addEventListener('message', (e) => {
+                if ( e.origin === '${origin}' ) window.received.push(e.data);
+            });
+        </script>
+        <iframe referrerpolicy="origin" title="Send feedback" src="${origin}/embed/feedback#user=${req.query.user ?? ''}"
+            style="display:block;border:0;width:100vw;height:100vh;color-scheme:light dark"></iframe>
+        <div style="height:3000px"></div>
+    </body></html>`));
+    app.get('/embed/feedback', (_req, res) => {
+        res.setHeader('Content-Security-Policy', `frame-ancestors 'self' ${hostOrigin}`);
+        res.send(`<!DOCTYPE html><html><head><meta name="viewport" content="width=device-width, initial-scale=1">
+            <link rel="stylesheet" href="/css/normalize.css"><link rel="stylesheet" href="/css/dashboard.css">
+            <link rel="stylesheet" href="/css/feedback-embed.css"></head><body>
+            <main id="feedback-embed"></main>
+            <script type="application/json" id="feedback-embed-config">${JSON.stringify({ apiOrigin: origin, hostOrigin })}</script>
+            <script defer src="/dist/feedback-embed.min.js"></script></body></html>`);
+    });
+    server = await new Promise(resolve => {
+        const listener = app.listen(0, '127.0.0.1', () => resolve(listener));
+    });
+    port = server.address().port;
+    origin = `http://puter.localhost:${port}`;
+    hostOrigin = `http://notes.puter.localhost:${port}`;
+    browser = await chromium.launch();
+}, 60000);
+
+afterAll(async () => {
+    await browser?.close();
+    if ( server ) await new Promise(resolve => server.close(resolve));
+    if ( directory ) await rm(directory, { recursive: true, force: true });
+});
+
+/** A browser whose GUI origin is signed in with `token`, if any. */
+const signedIn = (token, options = {}) => browser.newContext({ ...options, storageState: {
+    cookies: [],
+    origins: token ? [{ origin, localStorage: [{ name: 'auth_token_v2', value: token }] }] : [],
+} });
+
+const received = page => page.evaluate(() => window.received);
+
+/** The [r, g, b] of one pixel of the page, from a screenshot. */
+const pixel = async (page, x, y) => {
+    const png = await page.screenshot({ clip: { x, y, width: 1, height: 1 }, animations: 'disabled' });
+    const data = [];
+    for ( let at = 8; at < png.length; ) {
+        const length = png.readUInt32BE(at);
+        if ( png.toString('ascii', at + 4, at + 8) === 'IDAT' ) data.push(png.subarray(at + 8, at + 8 + length));
+        at += 12 + length;
+    }
+    // One pixel: a filter byte, then its channels unchanged.
+    return [...inflateSync(Buffer.concat(data)).subarray(1, 4)];
+};
+
+describe('feedback embed', () => {
+    it('sends feedback for the framing page as the user it names, then tells it', async () => {
+        const context = await signedIn(sessionToken);
+        try {
+            const page = await context.newPage();
+            page.setDefaultTimeout(6000);
+            const errors = [];
+            page.on('pageerror', error => errors.push(error.message));
+            requests.length = 0;
+            await page.goto(`${hostOrigin}/host?user=${sessionUser}`);
+            const frame = page.frameLocator('iframe');
+            await frame.locator('.app-feedback-form').waitFor();
+            expect(await frame.locator('.app-feedback-target-title').textContent()).toBe('Notes');
+            expect(await received(page)).toEqual([
+                { msg: 'feedbackEmbed', state: 'loading' },
+                { msg: 'feedbackEmbed', state: 'ready' },
+            ]);
+            // The page behind shows through around the dialog, under its scrim.
+            expect(await frame.locator('body').evaluate(el => getComputedStyle(el).backgroundColor)).toBe('rgba(0, 0, 0, 0)');
+            await page.screenshot({ path: path.join(tmpdir(), 'puter-feedback-embed.png'), animations: 'disabled' });
+
+            await frame.locator('.app-feedback-message').fill('Love the new editor');
+            await frame.locator('.app-feedback-send-btn').click();
+            await frame.locator('.app-feedback-success').waitFor();
+            await page.waitForFunction(() => window.received.some(m => m.msg === 'feedbackDialogClosed'));
+            expect((await received(page)).at(-1)).toEqual({ msg: 'feedbackDialogClosed', sent: true });
+            expect(await frame.locator('.app-feedback-overlay').count()).toBe(0);
+
+            const submit = requests.find(req => req.path === '/app-feedback');
+            expect(submit.body).toEqual({ origin: hostOrigin, message: 'Love the new editor', context: 'web' });
+            expect(submit.auth).toBe(`Bearer ${sessionToken}`);
+            expect(errors).toEqual([]);
+        } finally {
+            await context.close();
+        }
+    }, 30000);
+
+    it('answers not sent when the user dismisses it', async () => {
+        const context = await signedIn(sessionToken);
+        try {
+            const page = await context.newPage();
+            page.setDefaultTimeout(6000);
+            await page.goto(`${hostOrigin}/host?user=${sessionUser}`);
+            const frame = page.frameLocator('iframe');
+            await frame.locator('.app-feedback-form').waitFor();
+            await frame.locator('.app-feedback-message').press('Escape');
+            await page.waitForFunction(() => window.received.some(m => m.msg === 'feedbackDialogClosed'));
+            expect((await received(page)).at(-1)).toEqual({ msg: 'feedbackDialogClosed', sent: false });
+        } finally {
+            await context.close();
+        }
+    }, 30000);
+
+    it.each(['light', 'dark'])('lets the page show through under the scrim in %s mode', async (colorScheme) => {
+        const context = await signedIn(sessionToken, { colorScheme });
+        try {
+            const page = await context.newPage();
+            page.setDefaultTimeout(6000);
+            await page.goto(`${hostOrigin}/host?user=${sessionUser}`);
+            const frame = page.frameLocator('iframe');
+            await frame.locator('.app-feedback-form').waitFor();
+            expect(await frame.locator('body').evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches))
+                .toBe(colorScheme === 'dark');
+            await page.waitForTimeout(300);
+            // The red page, dimmed by the scrim, rather than an opaque frame.
+            const [red, green, blue] = await pixel(page, 10, 10);
+            expect(red).toBeGreaterThan(green + 40);
+            expect(green).toBe(blue);
+        } finally {
+            await context.close();
+        }
+    }, 30000);
+
+    it('keeps the page behind from scrolling under the scrim', async () => {
+        const context = await signedIn(sessionToken);
+        try {
+            const page = await context.newPage();
+            page.setDefaultTimeout(6000);
+            await page.goto(`${hostOrigin}/host?user=${sessionUser}`);
+            await page.frameLocator('iframe').locator('.app-feedback-form').waitFor();
+            await page.mouse.move(10, 10);
+            await page.mouse.wheel(0, 600);
+            await page.waitForTimeout(300);
+            expect(await page.evaluate(() => window.scrollY)).toBe(0);
+        } finally {
+            await context.close();
+        }
+    }, 30000);
+
+    it.each([
+        ['no Puter session', null, sessionUser],
+        ['a session for another user', sessionToken, otherUser],
+        ['a host that names no user', sessionToken, ''],
+        ['an email still to confirm', unconfirmedToken, unconfirmedUser],
+    ])('tells the host it is unavailable with %s', async (_label, token, user) => {
+        const context = await signedIn(token);
+        try {
+            const page = await context.newPage();
+            page.setDefaultTimeout(6000);
+            requests.length = 0;
+            await page.goto(`${hostOrigin}/host?user=${user}`);
+            await page.waitForFunction(() => window.received.length >= 2);
+            expect(await received(page)).toEqual([
+                { msg: 'feedbackEmbed', state: 'loading' },
+                { msg: 'feedbackEmbed', state: 'unavailable' },
+            ]);
+            expect(await page.frameLocator('iframe').locator('.app-feedback-overlay').count()).toBe(0);
+            expect(requests.some(req => req.path.startsWith('/app-feedback'))).toBe(false);
+        } finally {
+            await context.close();
+        }
+    }, 30000);
+
+    it('does nothing when opened on its own', async () => {
+        const context = await signedIn(sessionToken);
+        try {
+            const page = await context.newPage();
+            requests.length = 0;
+            await page.goto(`${origin}/embed/feedback#user=${sessionUser}`);
+            await page.waitForLoadState('networkidle');
+            expect(await page.locator('.app-feedback-overlay').count()).toBe(0);
+            expect(requests.some(req => req.path === '/whoami')).toBe(false);
+        } finally {
+            await context.close();
+        }
+    }, 30000);
+});

src/gui/src/feedbackEmbed.js

@@ -0,0 +1,86 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import jQuery from './lib/jquery-3.6.1/jquery-3.6.1.min.js';
+import { encode } from 'html-entities';
+import { loadLocale } from './i18n/embedI18n.js';
+import UIWindowAppFeedback from './UI/UIWindowAppFeedback.js';
+import { embedSession } from './helpers/embedSession.js';
+
+window.$ = window.jQuery = jQuery;
+window.html_encode = value => encode(String(value ?? ''), { mode: 'nonAsciiPrintable' });
+
+const config = JSON.parse(document.querySelector('#feedback-embed-config').textContent);
+window.api_origin = config.apiOrigin;
+window.locale = 'en';
+try {
+    window.locale = JSON.parse(localStorage.getItem('user_preferences') || '{}')?.language || 'en';
+} catch { /* Corrupt preferences must not prevent sending feedback. */ }
+const localeReady = loadLocale(window.locale);
+
+/** Answers only the page frame-ancestors pinned, which the feedback is for. */
+const tellHost = (data) => window.parent.postMessage(data, config.hostOrigin);
+
+/** Resolves once the dialog's overlay has left the page, after its success pane and exit. */
+const overlayGone = () => new Promise((resolve) => {
+    const gone = () => !document.querySelector('.app-feedback-overlay');
+    if ( gone() ) return resolve();
+    const observer = new MutationObserver(() => {
+        if ( ! gone() ) return;
+        observer.disconnect();
+        resolve();
+    });
+    observer.observe(document.body, { childList: true });
+});
+
+/**
+ * Shows the app feedback dialog for the framing page, as the signed-in user it
+ * names. Without that user's session, or with an email still to confirm, the
+ * host is told the embed is unavailable and uses the popup, which can sign in.
+ */
+async function run () {
+    tellHost({ msg: 'feedbackEmbed', state: 'loading' });
+    let session = null;
+    try {
+        session = await embedSession(config.apiOrigin, window.location.hash);
+    } catch (e) {
+        console.error('feedback embed: session check failed', e);
+    }
+    const user = session?.user;
+    if ( !user || (user.requires_email_confirmation && !user.email_confirmed) ) {
+        tellHost({ msg: 'feedbackEmbed', state: 'unavailable' });
+        return;
+    }
+    window.auth_token = session.token;
+    window.user = user;
+    await localeReady;
+
+    tellHost({ msg: 'feedbackEmbed', state: 'ready' });
+    let sent = false;
+    try {
+        sent = await UIWindowAppFeedback({ origin: config.hostOrigin, source: 'web' });
+        await overlayGone();
+    } catch (e) {
+        console.error('feedback embed: dialog failed', e);
+    }
+    tellHost({ msg: 'feedbackDialogClosed', sent: sent === true });
+}
+
+// Opened on its own, there is no page to send feedback for or answer.
+if ( config.hostOrigin && window.parent !== window ) run();

src/gui/src/globals.js

@@ -70,7 +70,7 @@ if ( window.logged_in_users.length === 0 && window.user !== null ) {
     let tuser = window.user;
     tuser.auth_token = window.auth_token;
     window.logged_in_users.push(tuser);
-    localStorage.setItem('logged_in_users', window.logged_in_users);
+    localStorage.setItem('logged_in_users', JSON.stringify(window.logged_in_users));
 }
 
 window.last_window_zindex = 1;

src/gui/src/helpers.js

@@ -663,33 +663,20 @@ window.update_auth_data = async (auth_token, user) => {
         $('.user-email').html(html_encode(user.email));
     }
 
-    // ----------------------------------------------------
-    // load the user's profile
-    // ----------------------------------------------------
-    user.profile = {};
-    puter.auth.getProfile().then((profile) => {
-        window.user.profile.displayName = profile?.displayName ?? null;
-        window.user.profile.bio = profile?.bio ?? null;
-        if ( profile?.displayName ) {
-            $('.dashboard-profile-display-name').text(profile.displayName);
-        }
-        if ( profile?.picture ) {
-            window.user.profile.picture = html_encode(profile.picture);
-            $('.profile-pic').css('background-image', `url(${window.user.profile.picture})`);
-            // the account tab may have rendered before the profile arrived
-            $('.dashboard-profile-remove-picture').prop('hidden', false);
-        }
-    }).catch((error) => {
-        console.error('Error loading profile:', error);
-    });
-
-    // ----------------------------------------------------
+    // Keep this account's last known profile until the fresh one loads below;
+    // the account picker reads pictures from the stored copy.
+    const known_profile = window.logged_in_users.find(known => known.uuid === user.uuid)?.profile;
+    user.profile = { ...(known_profile ?? user.profile ?? {}) };
 
     const to_storable_user = user => {
         const storable_user = { ...user };
         delete storable_user.taskbar_items;
         return storable_user;
     };
+    const store_users = () => {
+        localStorage.setItem('user', JSON.stringify(to_storable_user(window.user)));
+        localStorage.setItem('logged_in_users', JSON.stringify(window.logged_in_users.map(to_storable_user)));
+    };
 
     // update this session's user data
     window.user = user;
@@ -715,10 +702,33 @@ window.update_auth_data = async (auth_token, user) => {
             userobj.auth_token = window.auth_token;
             window.logged_in_users.push(userobj);
         }
-        // update local storage
-        localStorage.setItem('logged_in_users', JSON.stringify(window.logged_in_users.map(to_storable_user)));
+        store_users();
     }
 
+    // Loaded only after puter.js holds this account's token, so it can't
+    // return the previous account's profile.
+    puter.auth.getProfile().then((profile) => {
+        // Another account may have signed in while this was loading.
+        if ( !profile || window.user !== user ) return;
+        const shown_picture = user.profile.picture ?? null;
+        user.profile = {
+            displayName: profile.displayName ?? null,
+            bio: profile.bio ?? null,
+            picture: profile.picture ? html_encode(profile.picture) : null,
+        };
+        store_users();
+        if ( profile.displayName ) {
+            $('.dashboard-profile-display-name').text(profile.displayName);
+        }
+        // the account tab may have rendered before the profile arrived
+        if ( user.profile.picture !== shown_picture ) {
+            $('.profile-pic').css('background-image', `url(${user.profile.picture || window.icons['profile.svg']})`);
+            $('.dashboard-profile-remove-picture').prop('hidden', !user.profile.picture);
+        }
+    }).catch((error) => {
+        console.error('Error loading profile:', error);
+    });
+
     window.desktop_path = `/${ window.user.username }/Desktop`;
     window.trash_path = `/${ window.user.username }/Trash`;
     window.appdata_path = `/${ window.user.username }/AppData`;

src/gui/src/helpers.updateAuthData.test.js

@@ -51,8 +51,16 @@ describe('update_auth_data', () => {
         window.logged_in_users = [];
         window.gui_origin = 'https://puter.test';
         window.available_templates = vi.fn();
+        window.icons = { 'profile.svg': '/profile.svg' };
+        globalThis.fetch = vi.fn(async () => ({ ok: true }));
+        puter.setAuthToken.mockClear();
+        puter.auth.getProfile.mockReset();
+        puter.auth.getProfile.mockResolvedValue({});
     });
 
+    const storedUsers = () => JSON.parse(localStorage.getItem('logged_in_users'));
+    const settle = () => new Promise(resolve => setTimeout(resolve));
+
     // Sign-in awaits this while its card is still up, over every ordinary window.
     it('raises a failed session-cookie sync above the sign-in card', async () => {
         globalThis.fetch = vi.fn(async () => {
@@ -62,4 +70,49 @@ describe('update_auth_data', () => {
         expect(UIAlert).toHaveBeenCalledOnce();
         expect(UIAlert.mock.calls[0][0]).toMatchObject({ stay_on_top: true });
     });
+
+    // The account picker shows pictures from the stored list, not from memory.
+    it('stores the loaded profile picture with the signed-in account', async () => {
+        puter.auth.getProfile.mockResolvedValue({ picture: 'data:image/png;base64,AAAA' });
+        await window.update_auth_data('token-a', { uuid: 'a', username: 'a' });
+        await settle();
+        expect(storedUsers()).toEqual([
+            expect.objectContaining({ uuid: 'a', profile: expect.objectContaining({ picture: 'data:image/png;base64,AAAA' }) }),
+        ]);
+    });
+
+    it('keeps the stored picture while a refreshed profile is loading', async () => {
+        window.logged_in_users = [{ uuid: 'a', username: 'a', profile: { picture: 'data:image/png;base64,AAAA' } }];
+        puter.auth.getProfile.mockReturnValue(new Promise(() => {}));
+        // a whoami refresh carries no profile
+        await window.update_auth_data('token-a', { uuid: 'a', username: 'a' });
+        expect(storedUsers()[0].profile.picture).toBe('data:image/png;base64,AAAA');
+    });
+
+    it('drops a stored picture the account no longer has', async () => {
+        window.logged_in_users = [{ uuid: 'a', username: 'a', profile: { picture: 'data:image/png;base64,AAAA' } }];
+        puter.auth.getProfile.mockResolvedValue({ picture: null });
+        await window.update_auth_data('token-a', { uuid: 'a', username: 'a' });
+        await settle();
+        expect(storedUsers()[0].profile.picture).toBeNull();
+    });
+
+    it('loads the profile with the new account\'s token', async () => {
+        await window.update_auth_data('token-b', { uuid: 'b', username: 'b' });
+        expect(puter.setAuthToken.mock.invocationCallOrder[0])
+            .toBeLessThan(puter.auth.getProfile.mock.invocationCallOrder[0]);
+    });
+
+    it('ignores a profile that arrives after another account signed in', async () => {
+        let resolveA;
+        puter.auth.getProfile.mockReturnValueOnce(new Promise(resolve => {
+            resolveA = resolve;
+        }));
+        await window.update_auth_data('token-a', { uuid: 'a', username: 'a' });
+        await window.update_auth_data('token-b', { uuid: 'b', username: 'b' });
+        resolveA({ picture: 'data:image/png;base64,AAAA' });
+        await settle();
+        expect(storedUsers().find(stored => stored.uuid === 'b').profile.picture).toBeNull();
+        expect(window.user.profile.picture).toBeNull();
+    });
 });

src/gui/src/helpers/customDomains.js

@@ -0,0 +1,168 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+// The `/custom-domains` API as the GUI talks to it, with its own session:
+// the desktop's attach dialog and the dashboard's publish dialog share it.
+
+/**
+ * @typedef {object} CustomDomainRecord
+ * @property {string} type
+ * @property {string} name
+ * @property {string} value
+ * @property {'routing'|'redirect'|string} [purpose]
+ * @property {boolean} [required]
+ */
+
+/**
+ * @typedef {object} CustomDomain
+ * @property {string} uuid
+ * @property {string} hostname
+ * @property {string} site Subdomain of the website it serves.
+ * @property {'active'|'pending'|'failed'|string} status
+ * @property {string} [statusDetail]
+ * @property {boolean} [isApex]
+ * @property {string} [redirectFrom] The root domain forwarding to `hostname`.
+ * @property {string} [dnsProvider]
+ * @property {CustomDomainRecord[]} [records]
+ */
+
+/**
+ * @typedef {object} CustomDomainResponse
+ * @property {number} status
+ * @property {boolean} ok
+ * @property {any} data The parsed JSON body, or null.
+ */
+
+/** API error code → message key; anything unlisted gets the server's message. */
+const ERROR_KEYS = {
+    invalid_hostname: 'custom_domain_error_invalid',
+    custom_domain_taken: 'custom_domain_error_taken',
+    custom_domain_limit_reached: 'custom_domain_error_limit',
+    custom_domain_rejected: 'custom_domain_error_rejected',
+    site_not_found: 'custom_domain_error_site',
+    custom_domain_not_found: 'custom_domain_error_not_found',
+    custom_domains_not_enabled: 'custom_domain_not_enabled',
+    custom_domains_permission_required: 'custom_domain_error_generic',
+};
+
+/** Error codes that mean "try another hostname". */
+export const CUSTOM_DOMAIN_HOSTNAME_ERRORS = new Set([
+    'invalid_hostname',
+    'custom_domain_taken',
+    'custom_domain_rejected',
+]);
+
+const STATUSES = new Set(['active', 'pending', 'failed']);
+
+/**
+ * A domain's status as the GUI draws it; anything unknown reads as pending.
+ *
+ * @param {Partial<CustomDomain> | null | undefined} domain
+ * @returns {'active'|'pending'|'failed'}
+ */
+export const customDomainStatus = (domain) => (STATUSES.has(domain?.status) ? domain.status : 'pending');
+
+/**
+ * The monthly price the list call reports, in the user's locale.
+ *
+ * @param {{ amount?: number, currency?: string } | null | undefined} pricing
+ * @returns {string | null}
+ */
+export const formatCustomDomainPrice = (pricing) => {
+    if ( ! pricing || typeof pricing.amount !== 'number' ) return null;
+    try {
+        return new Intl.NumberFormat(undefined, {
+            style: 'currency',
+            currency: pricing.currency || 'USD',
+            minimumFractionDigits: 2,
+        }).format(pricing.amount);
+    } catch {
+        return null;
+    }
+};
+
+/**
+ * Calls `/custom-domains{path}`. Resolves with the status and parsed body,
+ * even for an error status; rejects only when the request itself fails.
+ *
+ * @param {'GET'|'POST'|'PATCH'|'DELETE'} method
+ * @param {string} [path] Starting with `/`, after `/custom-domains`.
+ * @param {object} [body]
+ * @param {string} [authToken] Defaults to the GUI's session.
+ * @returns {Promise<CustomDomainResponse>}
+ */
+export const customDomainsRequest = async (method, path = '', body, authToken = puter.authToken ?? window.auth_token) => {
+    const res = await fetch(`${window.api_origin}/custom-domains${path}`, {
+        method,
+        headers: {
+            'Authorization': `Bearer ${authToken}`,
+            ...(body ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    let data = null;
+    try {
+        data = await res.json();
+    } catch {
+        // Non-JSON body; callers go by the status.
+    }
+    return { status: res.status, ok: res.ok, data };
+};
+
+/**
+ * Plain text for a failed response. A known code gets our wording; anything
+ * else shows what the server said, which beats a generic message when
+ * something is misconfigured.
+ *
+ * @param {CustomDomainResponse} res
+ * @returns {string}
+ */
+export const customDomainErrorText = (res) => {
+    const text = (key) => i18n(key, [], false);
+    if ( res.status === 402 ) return text('custom_domain_error_plan');
+    if ( res.status === 429 ) return text('custom_domain_error_rate_limited');
+    const key = ERROR_KEYS[res.data?.code];
+    if ( key ) return text(key);
+    if ( typeof res.data?.message === 'string' && res.data.message ) {
+        return res.data.message;
+    }
+    return `${text('custom_domain_error_generic')} (HTTP ${res.status})`;
+};
+
+/**
+ * What to show after a status check. A domain that is no longer pending
+ * comes back with only its routing record, and a GET never repeats the DNS
+ * provider or the redirect, so those are kept from what was shown before.
+ *
+ * @param {CustomDomain} known What the add (or the last check) returned.
+ * @param {CustomDomain} fresh What the GET returned.
+ * @returns {CustomDomain}
+ */
+export const mergeCustomDomainRefresh = (known, fresh) => {
+    const knownRecords = known.records ?? [];
+    const redirect = knownRecords.filter((r) => r.purpose === 'redirect');
+    const records = (fresh.records?.length > 1 ? fresh.records : knownRecords)
+        .filter((r) => r.purpose !== 'redirect');
+    return {
+        ...fresh,
+        dnsProvider: known.dnsProvider,
+        redirectFrom: known.redirectFrom,
+        records: [...records.slice(0, 1), ...redirect, ...records.slice(1)],
+    };
+};

src/gui/src/helpers/customDomains.test.js

@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+    customDomainErrorText,
+    customDomainsRequest,
+    customDomainStatus,
+    formatCustomDomainPrice,
+    mergeCustomDomainRefresh,
+} from './customDomains.js';
+
+beforeEach(() => {
+    globalThis.i18n = (key) => key;
+    globalThis.puter = { authToken: 'session-token' };
+    window.api_origin = 'https://api.puter.test';
+});
+
+describe('customDomainStatus', () => {
+    it('keeps a known status and reads anything else as pending', () => {
+        expect(customDomainStatus({ status: 'active' })).toBe('active');
+        expect(customDomainStatus({ status: 'failed' })).toBe('failed');
+        expect(customDomainStatus({ status: 'verifying' })).toBe('pending');
+        expect(customDomainStatus(null)).toBe('pending');
+    });
+});
+
+describe('formatCustomDomainPrice', () => {
+    it('formats the amount in its currency', () => {
+        expect(formatCustomDomainPrice({ amount: 0.5, currency: 'USD' })).toMatch(/0[.,]50/);
+    });
+
+    it('gives null without an amount or for a currency it cannot format', () => {
+        expect(formatCustomDomainPrice(null)).toBeNull();
+        expect(formatCustomDomainPrice({ currency: 'USD' })).toBeNull();
+        expect(formatCustomDomainPrice({ amount: 1, currency: 'not-a-currency' })).toBeNull();
+    });
+});
+
+describe('customDomainsRequest', () => {
+    it('sends the session token and a JSON body, and parses the reply', async () => {
+        globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({ uuid: 'd1' }), { status: 201 }));
+        const res = await customDomainsRequest('POST', '', { site: 'my-site', hostname: 'www.example.com' });
+        expect(fetch).toHaveBeenCalledWith('https://api.puter.test/custom-domains', {
+            method: 'POST',
+            headers: { 'Authorization': 'Bearer session-token', 'Content-Type': 'application/json' },
+            body: '{"site":"my-site","hostname":"www.example.com"}',
+        });
+        expect(res).toEqual({ status: 201, ok: true, data: { uuid: 'd1' } });
+    });
+
+    it('resolves an error status with a null body when it is not JSON', async () => {
+        globalThis.fetch = vi.fn(async () => new Response('Not Found', { status: 404 }));
+        expect(await customDomainsRequest('GET', '/d1')).toEqual({ status: 404, ok: false, data: null });
+        expect(fetch.mock.calls[0][0]).toBe('https://api.puter.test/custom-domains/d1');
+        expect(fetch.mock.calls[0][1].headers).toEqual({ 'Authorization': 'Bearer session-token' });
+    });
+});
+
+describe('customDomainErrorText', () => {
+    it('words plan, rate limit and known codes itself', () => {
+        expect(customDomainErrorText({ status: 402, data: { code: 'subscription_required' } })).toBe('custom_domain_error_plan');
+        expect(customDomainErrorText({ status: 429, data: null })).toBe('custom_domain_error_rate_limited');
+        expect(customDomainErrorText({ status: 409, data: { code: 'custom_domain_taken', message: 'x' } })).toBe('custom_domain_error_taken');
+    });
+
+    it("falls back to the server's message, then to the status", () => {
+        expect(customDomainErrorText({ status: 502, data: { message: 'Provider down' } })).toBe('Provider down');
+        expect(customDomainErrorText({ status: 500, data: null })).toBe('custom_domain_error_generic (HTTP 500)');
+    });
+});
+
+describe('mergeCustomDomainRefresh', () => {
+    const routing = { type: 'CNAME', name: 'www', value: 'my-site.puter.site', purpose: 'routing' };
+    const redirect = { type: 'A', name: '@', value: '192.0.2.1', purpose: 'redirect' };
+    const ownership = { type: 'TXT', name: '_cf', value: 'abc', purpose: 'ownership' };
+    const known = {
+        uuid: 'd1',
+        status: 'pending',
+        dnsProvider: 'example-dns',
+        redirectFrom: 'example.com',
+        records: [routing, redirect, ownership],
+    };
+
+    it('keeps the records shown before when the check returns only routing', () => {
+        const merged = mergeCustomDomainRefresh(known, { uuid: 'd1', status: 'active', records: [routing] });
+        expect(merged.status).toBe('active');
+        expect(merged.records).toEqual([routing, redirect, ownership]);
+        expect(merged.dnsProvider).toBe('example-dns');
+        expect(merged.redirectFrom).toBe('example.com');
+    });
+
+    it('takes fresh records, with the redirect after the routing one', () => {
+        const fresh_ownership = { ...ownership, value: 'def' };
+        const merged = mergeCustomDomainRefresh(known, { uuid: 'd1', status: 'pending', records: [routing, fresh_ownership] });
+        expect(merged.records).toEqual([routing, redirect, fresh_ownership]);
+    });
+});

src/gui/src/helpers/embedHostTheme.js

@@ -0,0 +1,62 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+const COLOR_SCHEME_FEATURE = /\(\s*prefers-color-scheme\s*:\s*(dark|light)\s*\)/gi;
+
+/**
+ * The theme an embedding page forces, from its `#theme=dark|light` fragment.
+ * Null when it names none, so the embed follows the OS.
+ *
+ * @param {string} hash - `location.hash`
+ * @returns {'dark' | 'light' | null}
+ */
+export const embedHostTheme = (hash) => {
+    const value = new URLSearchParams(String(hash ?? '').replace(/^#/, '')).get('theme');
+    return value === 'dark' || value === 'light' ? value : null;
+};
+
+/**
+ * Makes the document's `prefers-color-scheme` rules match `theme` whatever
+ * the OS prefers. Chromium doesn't pass a frame's `color-scheme` on to the
+ * document inside it, so the host's forced theme has to be applied here.
+ *
+ * @param {Document} doc - with its stylesheets loaded
+ * @param {'dark' | 'light'} theme
+ */
+export const forceColorScheme = (doc, theme) => {
+    doc.documentElement.style.colorScheme = theme;
+    const force = (rules) => {
+        for ( const rule of rules ) {
+            const media = rule.media?.mediaText;
+            // Always true for the forced scheme, never for the other.
+            const forced = media?.replace(COLOR_SCHEME_FEATURE, (_, scheme) => (
+                scheme.toLowerCase() === theme ? '(min-width: 0px)' : '(max-width: -1px)'
+            ));
+            if ( forced !== media ) rule.media.mediaText = forced;
+            if ( rule.cssRules ) force(rule.cssRules);
+        }
+    };
+    for ( const sheet of doc.styleSheets ) {
+        let rules;
+        try {
+            rules = sheet.cssRules;
+        } catch { continue; /* Another origin's stylesheet can't be read. */ }
+        force(rules);
+    }
+};

src/gui/src/helpers/embedHostTheme.test.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { embedHostTheme } from './embedHostTheme.js';
+
+describe('embedHostTheme', () => {
+    it('reads a forced theme from the fragment', () => {
+        expect(embedHostTheme('#theme=dark')).toBe('dark');
+        expect(embedHostTheme('#user=0b1c9a52-3f0e-4c7a-9a65-2f6d1e8b7c40&theme=light')).toBe('light');
+    });
+
+    it.each(['', '#', '#theme=', '#theme=Dark', '#theme=auto', '#scheme=dark', undefined])(
+        'is null for %j', hash => {
+            expect(embedHostTheme(hash)).toBeNull();
+        },
+    );
+});

src/gui/src/helpers/embedHostUser.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The uuid of the user an embedding page is signed in as, from its
+ * `#user=<uuid>` fragment, in lower case. Null without a well-formed one.
+ *
+ * @param {string} hash - `location.hash`
+ * @returns {string | null}
+ */
+export const embedHostUser = (hash) => {
+    const value = new URLSearchParams(String(hash ?? '').replace(/^#/, '')).get('user');
+    return value && UUID.test(value) ? value.toLowerCase() : null;
+};

src/gui/src/helpers/embedHostUser.test.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { embedHostUser } from './embedHostUser.js';
+
+const UUID = '0b1c9a52-3f0e-4c7a-9a65-2f6d1e8b7c40';
+
+describe('embedHostUser', () => {
+    it('reads the user uuid from the fragment', () => {
+        expect(embedHostUser(`#user=${UUID}`)).toBe(UUID);
+        expect(embedHostUser(`#other=1&user=${UUID}`)).toBe(UUID);
+    });
+
+    it('lower-cases the uuid', () => {
+        expect(embedHostUser(`#user=${UUID.toUpperCase()}`)).toBe(UUID);
+    });
+
+    it.each(['', '#', '#user=', '#user=admin', `#user=${UUID}x`, `#user= ${UUID}`, `#uid=${UUID}`, undefined])(
+        'is null for %j', hash => {
+            expect(embedHostUser(hash)).toBeNull();
+        },
+    );
+});

src/gui/src/helpers/embedSession.js

@@ -0,0 +1,83 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { embedHostUser } from './embedHostUser.js';
+
+/**
+ * @typedef {Object} EmbedSession
+ * @property {string} token - the GUI session's token
+ * @property {Record<string, unknown>} user - `/whoami` for that token
+ */
+
+/**
+ * The GUI session, from local storage or else the session cookie. Safari keys a
+ * frame's local storage by the top-level origin, so under a sibling subdomain
+ * the GUI's stored token is out of reach while its cookie is still sent.
+ *
+ * @returns {Promise<string | null>}
+ */
+async function readSession () {
+    let stored = null;
+    try {
+        stored = localStorage.getItem('auth_token_v2');
+    } catch { /* Storage the browser refuses holds no session; the cookie may. */ }
+    if ( stored ) return stored;
+    const response = await fetch('/get-gui-token', { credentials: 'include' });
+    // Only a 401 means there is no session; a rate limit or server error
+    // must not pass a signed-in user off as signed out.
+    if ( response.status === 401 ) return null;
+    if ( ! response.ok ) throw new Error(`Session lookup responded ${response.status}`);
+    return (await response.json())?.token || null;
+}
+
+/**
+ * `/whoami` for a GUI token, or null when the API refuses it.
+ *
+ * @param {string} token
+ * @param {string} apiOrigin
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+async function whoami (token, apiOrigin) {
+    const response = await fetch(new URL('/whoami', apiOrigin), {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if ( response.status === 401 ) return null;
+    if ( ! response.ok ) throw new Error(`Session check responded ${response.status}`);
+    const user = await response.json();
+    return user && typeof user === 'object' ? user : null;
+}
+
+/**
+ * The GUI session, only when it belongs to the user the embedding page names
+ * in its `#user=<uuid>` fragment. A host signed out, or signed in as someone
+ * else, gets null. Rejects when the session can't be checked.
+ *
+ * @param {string} apiOrigin
+ * @param {string} hash - `location.hash`
+ * @returns {Promise<EmbedSession | null>}
+ */
+export async function embedSession (apiOrigin, hash) {
+    const hostUser = embedHostUser(hash);
+    if ( ! hostUser ) return null;
+    const token = await readSession();
+    if ( ! token ) return null;
+    const user = await whoami(token, apiOrigin);
+    const uuid = typeof user?.uuid === 'string' ? user.uuid.toLowerCase() : null;
+    return uuid === hostUser ? { token, user } : null;
+}

src/gui/src/helpers/planGate.js

@@ -28,14 +28,21 @@ export const is_plan_gate_error = (error) =>
     Boolean(error && typeof error === 'object' && error.code === 'subscription_required');
 
 /**
- * Open the upgrade flow, where the deployment has one. Hosted puter.com
- * attaches `UIUpgradeAccount`; a self-hosted install has no plan to offer,
- * and the caller explains the refusal in its own words instead.
+ * Whether the deployment has an upgrade flow. Hosted puter.com attaches
+ * `UIUpgradeAccount`; a self-hosted install has no plan to offer.
+ *
+ * @returns {boolean}
+ */
+export const has_upgrade_flow = () => typeof window.UIUpgradeAccount === 'function';
+
+/**
+ * Open the upgrade flow, where the deployment has one. Without one, the
+ * caller explains the refusal in its own words instead.
  *
  * @returns {boolean} Whether the upgrade flow was opened.
  */
 export const open_upgrade_flow = () => {
-    if ( typeof window.UIUpgradeAccount !== 'function' ) return false;
+    if ( ! has_upgrade_flow() ) return false;
     (new window.UIUpgradeAccount()).open_as_window();
     return true;
 };

src/gui/src/helpers/popupFrame.js

@@ -0,0 +1,158 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * A GUI popup that a first-party page shows in a frame instead of a window,
+ * served at `/embed/<action>`. It runs the popup boot unchanged: the framing
+ * page stands in for `window.opener`, and closing asks it to remove the frame.
+ */
+
+/** Popup actions a first-party page can frame. */
+export const FRAMED_POPUP_ACTIONS = new Set([
+    'sign-in',
+    'show-open-file-picker',
+    'show-save-file-picker',
+    'show-directory-picker',
+]);
+
+/** Lifecycle messages to the framing page carry this as `msg`. */
+export const POPUP_FRAME_MSG = 'puterPopupFrame';
+
+// The popup's query parameters a framing page may pass, in the fragment.
+const FRAGMENT_PARAMS = ['msg_id', 'options', 'request_auth'];
+
+// The account checks a sign-in can show (email, phone, card), which are
+// windows rather than auth screens.
+const ACCOUNT_CHECK_WINDOWS = '.window-confirm-email-using-code, .window-confirm-phone-using-code, .window-card-verification';
+
+// What a framed popup shows first; until one is on the page the framing page
+// keeps the frame hidden behind its loading scrim.
+const VISIBLE_UI = '.window, .dashboard-dialog-overlay, .captcha-modal';
+
+/**
+ * The action a `/embed/<action>` path frames, or null for any other path.
+ *
+ * @param {string} pathname
+ * @returns {string | null}
+ */
+export const framedPopupAction = (pathname) => {
+    const match = /^\/embed\/([a-z-]+)\/?$/.exec(String(pathname ?? ''));
+    return match && FRAMED_POPUP_ACTIONS.has(match[1]) ? match[1] : null;
+};
+
+/**
+ * The popup parameters the framing page put in the fragment, and no others.
+ * The route refuses a query string, so nothing else reaches the boot.
+ *
+ * @param {string} hash - `location.hash`
+ * @returns {URLSearchParams}
+ */
+export const framedPopupParams = (hash) => {
+    const given = new URLSearchParams(String(hash ?? '').replace(/^#/, ''));
+    const params = new URLSearchParams();
+    for ( const key of FRAGMENT_PARAMS ) {
+        if ( given.has(key) ) params.set(key, given.get(key));
+    }
+    return params;
+};
+
+/**
+ * Starts a framed popup in `win`: the framing page, at the origin the server
+ * pinned with frame-ancestors, becomes `opener`, `close()` asks it to remove
+ * the frame, and it hears `ready` once the popup shows something. Returns a
+ * function that sends it a lifecycle state, with any fields that go with it,
+ * or null when there is no framing page to answer (opened on its own, or
+ * framed by a page the server refused).
+ *
+ * @param {Window} win
+ * @param {string | null | undefined} hostOrigin - `gui_params.embed_host_origin`
+ * @returns {((state: 'loading' | 'ready' | 'unavailable' | 'closed' | 'provider', fields?: Record<string, string>) => void) | null}
+ */
+export const startPopupFrame = (win, hostOrigin) => {
+    if ( ! hostOrigin || win.parent === win ) return null;
+    const parent = win.parent;
+    const tell = (state, fields = {}) =>
+        parent.postMessage({ ...fields, msg: POPUP_FRAME_MSG, state }, hostOrigin);
+
+    win.opener = parent;
+    win.close = () => tell('closed');
+    // The popup closes with `window.open('', '_self').close()` as well, which
+    // must reach the `close` above rather than navigate the frame.
+    const open = win.open.bind(win);
+    win.open = (url, target, ...rest) =>
+        url === '' && target === '_self' ? win : open(url, target, ...rest);
+
+    const announceReady = () => {
+        if ( ! win.document.querySelector(VISIBLE_UI) ) return false;
+        tell('ready');
+        return true;
+    };
+    const observer = new win.MutationObserver(() => {
+        if ( announceReady() ) observer.disconnect();
+    });
+    observer.observe(win.document.body, { childList: true, subtree: true });
+
+    tell('loading');
+    return tell;
+};
+
+/**
+ * Gives a framed popup's latest focus() back whenever the frame gains focus
+ * with nothing focused, until the user presses a key or the pointer in it. A
+ * cross-origin frame can't take focus until the framing page focuses it, which
+ * also resets it, so a save picker's file name would start unfocused.
+ *
+ * @param {Window} win
+ */
+export const focusOnFrameFocus = (win) => {
+    const focus = win.HTMLElement.prototype.focus;
+    let latest = null;
+    win.HTMLElement.prototype.focus = function (...args) {
+        latest = { el: this, args };
+        return focus.apply(this, args);
+    };
+    const forget = () => {
+        latest = null;
+        win.HTMLElement.prototype.focus = focus;
+    };
+    win.addEventListener('pointerdown', forget, { capture: true, once: true });
+    win.addEventListener('keydown', forget, { capture: true, once: true });
+    win.addEventListener('focus', () => {
+        const active = win.document.activeElement;
+        if ( ! latest?.el.isConnected || (active && active !== win.document.body) ) return;
+        focus.apply(latest.el, latest.args);
+    });
+};
+
+/**
+ * Closes a framed sign-in on Escape in one of its account checks, as Escape
+ * on its auth screens does. Those screens handle Escape themselves; the
+ * account checks are windows, which don't.
+ *
+ * @param {Window} win
+ */
+export const closeAccountChecksOnEscape = (win) => {
+    win.document.addEventListener('keydown', (e) => {
+        // Safari sends the Escape that ends an IME conversion as keyCode 229
+        // with isComposing false.
+        if ( e.key !== 'Escape' || e.defaultPrevented || e.isComposing || e.keyCode === 229 ) return;
+        const el = e.target === win.document.body ? win.document.querySelector('.window-active') : e.target;
+        if ( el?.closest?.(ACCOUNT_CHECK_WINDOWS) ) win.close();
+    });
+};

src/gui/src/helpers/popupFrame.test.js

@@ -0,0 +1,235 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+    POPUP_FRAME_MSG,
+    closeAccountChecksOnEscape,
+    focusOnFrameFocus,
+    framedPopupAction,
+    framedPopupParams,
+    startPopupFrame,
+} from './popupFrame.js';
+
+const HOST = 'https://notes.puter.test';
+
+/** A stand-in for the frame's window, with its own parent to post to. */
+const frameWindow = () => {
+    const parent = { postMessage: vi.fn() };
+    const open = vi.fn(() => 'opened');
+    return {
+        parent,
+        open,
+        opener: null,
+        close: () => {},
+        document,
+        MutationObserver: window.MutationObserver,
+    };
+};
+
+const statesSent = (win) => win.parent.postMessage.mock.calls.map(([data, origin]) => {
+    expect(origin).toBe(HOST);
+    expect(data.msg).toBe(POPUP_FRAME_MSG);
+    return data.state;
+});
+
+afterEach(() => {
+    document.body.innerHTML = '';
+});
+
+describe('framedPopupAction', () => {
+    it.each([
+        ['/embed/sign-in', 'sign-in'],
+        ['/embed/sign-in/', 'sign-in'],
+        ['/embed/show-open-file-picker', 'show-open-file-picker'],
+        ['/embed/show-save-file-picker', 'show-save-file-picker'],
+        ['/embed/show-directory-picker', 'show-directory-picker'],
+        ['/embed/apps', null],
+        ['/embed/feedback', null],
+        ['/embed/request-permission', null],
+        ['/action/sign-in', null],
+        ['/embed/sign-in/extra', null],
+        ['/', null],
+        [undefined, null],
+    ])('%s frames %s', (pathname, expected) => {
+        expect(framedPopupAction(pathname)).toBe(expected);
+    });
+});
+
+describe('framedPopupParams', () => {
+    it('keeps only the popup parameters a framing page may pass', () => {
+        const params = framedPopupParams('#msg_id=7&options=%7B%22multiple%22%3Atrue%7D&request_auth=true&user=abc&auth_token=x&attempt_temp_user_creation=true&api_origin=https%3A%2F%2Fevil.test');
+        expect(Object.fromEntries(params)).toEqual({
+            msg_id: '7',
+            options: '{"multiple":true}',
+            request_auth: 'true',
+        });
+    });
+
+    it('is empty without a fragment', () => {
+        expect([...framedPopupParams('')]).toEqual([]);
+        expect([...framedPopupParams(undefined)]).toEqual([]);
+    });
+});
+
+describe('startPopupFrame', () => {
+    it('does nothing without a framing page to answer', () => {
+        const win = frameWindow();
+        expect(startPopupFrame(win, null)).toBeNull();
+        const top = frameWindow();
+        top.parent = top;
+        expect(startPopupFrame(top, HOST)).toBeNull();
+        expect(win.opener).toBeNull();
+    });
+
+    it('makes the framing page the opener and tells it the frame is loading', () => {
+        const win = frameWindow();
+        startPopupFrame(win, HOST);
+        expect(win.opener).toBe(win.parent);
+        expect(statesSent(win)).toEqual(['loading']);
+    });
+
+    it('asks the framing page to remove the frame on close, either way the popup closes', () => {
+        const win = frameWindow();
+        startPopupFrame(win, HOST);
+        win.close();
+        win.open('', '_self').close();
+        expect(statesSent(win)).toEqual(['loading', 'closed', 'closed']);
+    });
+
+    it('sends the fields that go with a state, without letting them rename it', () => {
+        const win = frameWindow();
+        const tell = startPopupFrame(win, HOST);
+        tell('provider', { url: 'https://puter.test/auth/oidc/google/start', msg: 'x', state: 'y' });
+        expect(win.parent.postMessage).toHaveBeenLastCalledWith(
+            { url: 'https://puter.test/auth/oidc/google/start', msg: POPUP_FRAME_MSG, state: 'provider' },
+            HOST,
+        );
+    });
+
+    it('leaves other window.open calls alone', () => {
+        const win = frameWindow();
+        const open = win.open;
+        startPopupFrame(win, HOST);
+        expect(win.open('https://puter.com/terms', '_blank')).toBe('opened');
+        expect(open).toHaveBeenCalledWith('https://puter.com/terms', '_blank');
+    });
+
+    it('tells the framing page it is ready once the popup shows something', async () => {
+        const win = frameWindow();
+        startPopupFrame(win, HOST);
+        document.body.append(Object.assign(document.createElement('div'), { className: 'busy' }));
+        await Promise.resolve();
+        expect(statesSent(win)).toEqual(['loading']);
+
+        const dialog = document.createElement('div');
+        dialog.className = 'dashboard-dialog-overlay auth-dialog-page';
+        document.body.append(dialog);
+        await Promise.resolve();
+        document.body.append(Object.assign(document.createElement('div'), { className: 'window' }));
+        await Promise.resolve();
+        expect(statesSent(win)).toEqual(['loading', 'ready']);
+    });
+});
+
+describe('focusOnFrameFocus', () => {
+    /** A window of its own, so patching its focus() leaves the test's alone. */
+    const ownWindow = () => {
+        const iframe = document.createElement('iframe');
+        document.body.append(iframe);
+        const win = iframe.contentWindow;
+        const input = win.document.createElement('input');
+        win.document.body.append(input);
+        return { win, input };
+    };
+    /** The frame losing its focus, then the framing page focusing it again. */
+    const refocusFrame = (win) => {
+        win.document.activeElement?.blur();
+        win.dispatchEvent(new win.FocusEvent('focus'));
+    };
+
+    it('gives the popup\'s latest focus back each time the frame gains focus with nothing focused', () => {
+        const { win, input } = ownWindow();
+        focusOnFrameFocus(win);
+        input.focus();
+        refocusFrame(win);
+        expect(win.document.activeElement).toBe(input);
+        refocusFrame(win);
+        expect(win.document.activeElement).toBe(input);
+    });
+
+    it('leaves focus to the user once they press a key or the pointer', () => {
+        for ( const type of ['keydown', 'pointerdown'] ) {
+            const { win, input } = ownWindow();
+            const focus = win.HTMLElement.prototype.focus;
+            focusOnFrameFocus(win);
+            input.focus();
+            win.document.body.dispatchEvent(new win.Event(type, { bubbles: true }));
+            refocusFrame(win);
+            expect(win.document.activeElement).toBe(win.document.body);
+            expect(win.HTMLElement.prototype.focus).toBe(focus);
+        }
+    });
+
+    it('leaves an element that has focus, and one that has left the page', () => {
+        const { win, input } = ownWindow();
+        const nativeFocus = win.HTMLElement.prototype.focus;
+        const other = win.document.createElement('button');
+        win.document.body.append(other);
+        focusOnFrameFocus(win);
+        input.focus();
+        nativeFocus.call(other);
+        win.dispatchEvent(new win.FocusEvent('focus'));
+        expect(win.document.activeElement).toBe(other);
+
+        input.remove();
+        refocusFrame(win);
+        expect(win.document.activeElement).toBe(win.document.body);
+    });
+});
+
+describe('closeAccountChecksOnEscape', () => {
+    /** A sign-in window with its own document, whose close() is spied on. */
+    const signInWindow = () => {
+        const win = { document: document.implementation.createHTMLDocument(), close: vi.fn() };
+        closeAccountChecksOnEscape(win);
+        return win;
+    };
+    const escapeOn = (el, init = {}) => {
+        el.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true, ...init }));
+    };
+    const showWindow = (win, className = 'window window-active window-confirm-email-using-code') => {
+        const el = Object.assign(win.document.createElement('div'), { className });
+        el.innerHTML = '<input class="digit-input">';
+        win.document.body.append(el);
+        return el;
+    };
+
+    it.each([
+        'window-confirm-email-using-code',
+        'window-confirm-phone-using-code',
+        'window-card-verification',
+    ])('closes on Escape in the %s window', (cls) => {
+        const win = signInWindow();
+        escapeOn(showWindow(win, `window window-active ${cls}`).querySelector('input'));
+        expect(win.close).toHaveBeenCalledTimes(1);
+    });
+
+    it('closes on Escape with focus on the page behind an account check', () => {
+        const win = signInWindow();
+        showWindow(win);
+        escapeOn(win.document.body);
+        expect(win.close).toHaveBeenCalledTimes(1);
+    });
+
+    it('leaves Escape that something or an IME handled, other keys, and other windows alone', () => {
+        const win = signInWindow();
+        const input = showWindow(win).querySelector('input');
+        input.addEventListener('keydown', (e) => e.preventDefault(), { once: true });
+        escapeOn(input);
+        escapeOn(input, { key: 'Enter' });
+        escapeOn(input, { isComposing: true });
+        // Safari ends a conversion with keyCode 229 and isComposing false.
+        escapeOn(input, { keyCode: 229 });
+        escapeOn(showWindow(win, 'window window-alert').querySelector('input'));
+        expect(win.close).not.toHaveBeenCalled();
+    });
+});

src/gui/src/helpers/refreshItemContainer.js

@@ -32,6 +32,13 @@ const refresh_item_container = function (el_item_container, options) {
     options = options || {};
 
     let container_path =  $(el_item_container).attr('data-path');
+
+    // Only the newest refresh of a container may write to it or its window;
+    // an older one's responses belong to a folder the window has since left.
+    const refresh_id = ($(el_item_container).data('refreshId') ?? 0) + 1;
+    $(el_item_container).data('refreshId', refresh_id);
+    const is_current = () => $(el_item_container).data('refreshId') === refresh_id;
+
     let el_window = $(el_item_container).closest('.window');
     let el_window_head_icon = $(el_window).find('.window-head-icon');
     const loading_spinner = $(el_item_container).find('.explorer-loading-spinner');
@@ -60,9 +67,7 @@ const refresh_item_container = function (el_item_container, options) {
     // A timeout that will show the loading spinner if the folder is not loaded
     // after 1000ms
     let loading_timeout = setTimeout(function () {
-        // make sure the same folder is still loading
-        if ( $(loading_spinner).closest('.item-container').attr('data-path') !== container_path )
-        {
+        if ( ! is_current() ) {
             return;
         }
 
@@ -89,6 +94,9 @@ const refresh_item_container = function (el_item_container, options) {
     }
 
     if ( !is_shared_view ) puter.fs.stat({ path: container_path, consistency: options.consistency ?? 'eventual' }).then(fsentry => {
+        if ( ! is_current() ) {
+            return;
+        }
         if ( el_window ) {
             $(el_window).attr('data-uid', fsentry.id);
             $(el_window).attr('data-sort_by', fsentry.sort_by ?? 'name');
@@ -156,10 +164,8 @@ const refresh_item_container = function (el_item_container, options) {
         : puter.fs.readdir({ path: container_path, consistency: options.consistency ?? 'eventual' });
 
     entries_promise.then(async (fsentries) => {
-        // Check if the same folder is still loading since el_item_container's
-        // data-path might have changed by other operations while waiting for the response to this `readdir`.
-        if ( $(el_item_container).attr('data-path') !== container_path )
-        {
+        if ( ! is_current() ) {
+            clearTimeout(loading_timeout);
             return;
         }
 
@@ -168,6 +174,11 @@ const refresh_item_container = function (el_item_container, options) {
             // clear loading timeout
                 clearTimeout(loading_timeout);
 
+                // a newer refresh may have started during the spinner delay
+                if ( ! is_current() ) {
+                    return;
+                }
+
                 // hide loading spinner
                 $(loading_spinner).hide();
 
@@ -187,6 +198,10 @@ const refresh_item_container = function (el_item_container, options) {
 
                 // add each item to window
                 for ( let index = 0; index < fsentries.length; index++ ) {
+                    // item_icon() is awaited below, so a newer refresh can start mid-loop
+                    if ( ! is_current() ) {
+                        return;
+                    }
                     const fsentry = fsentries[index];
                     let is_disabled = false;
 
@@ -258,6 +273,9 @@ const refresh_item_container = function (el_item_container, options) {
                 if ( $(el_item_container).hasClass('desktop') ) {
                     try {
                         const trash = await puter.fs.stat({ path: window.trash_path, consistency: options.consistency ?? 'eventual' });
+                        if ( ! is_current() ) {
+                            return;
+                        }
                         UIItem({
                             appendTo: el_item_container,
                             uid: trash.id,
@@ -319,6 +337,11 @@ const refresh_item_container = function (el_item_container, options) {
         // clear loading timeout
         clearTimeout(loading_timeout);
 
+        // don't show a folder's error in the folder the window moved to
+        if ( ! is_current() ) {
+            return;
+        }
+
         // hide other messages/indicators
         $(loading_spinner).hide();
         $(empty_message).hide();

src/gui/src/helpers/refreshItemContainer.test.js

@@ -18,7 +18,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import jQuery from '../lib/jquery-3.6.1/jquery-3.6.1.min.js';
 
 vi.mock('../UI/UIItem.js', () => ({ default: vi.fn() }));
@@ -30,6 +30,11 @@ vi.mock('./listAllShared.js', () => ({ default: vi.fn() }));
 globalThis.$ = jQuery;
 globalThis.jQuery = jQuery;
 globalThis.i18n = (key) => key;
+globalThis.html_encode = (value) =>
+    jQuery('<div>')
+        .text(value ?? '')
+        .html();
+globalThis.puter = { fs: { stat: vi.fn(), readdir: vi.fn() } };
 jQuery.fn.removeItems = function () {
     return this.remove();
 };
@@ -46,6 +51,8 @@ Object.assign(window, {
     check_fsentry_against_allowed_file_types_string: () => true,
     sort_items: () => {},
     update_explorer_footer_item_count: () => {},
+    update_window_layout: () => {},
+    update_details_layout_sort_visuals: () => {},
 });
 
 const { default: refresh_item_container } =
@@ -53,6 +60,10 @@ const { default: refresh_item_container } =
 const { default: UIItem } = await import('../UI/UIItem.js');
 const { default: list_all_shared } = await import('./listAllShared.js');
 
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+
 describe('refresh_item_container in the Shared view', () => {
     it('flags rows shared through a team, and only those', async () => {
         list_all_shared.mockResolvedValue([
@@ -97,3 +108,91 @@ describe('refresh_item_container in the Shared view', () => {
         });
     });
 });
+
+const deferred = () => {
+    let resolve;
+    const promise = new Promise((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+};
+
+const fileEntry = (dir, name) => ({
+    uid: `${dir}/${name}`,
+    name,
+    path: `${dir}/${name}`,
+    is_dir: false,
+});
+
+// Points the window at a new folder the way update_window_path does, then refreshes it.
+const navigate = (path) => {
+    $('.window').attr('data-path', path);
+    $('.item-container').attr('data-path', path);
+    refresh_item_container($('.item-container'));
+};
+
+const renderedPaths = () => UIItem.mock.calls.map(([options]) => options.path);
+
+describe('refresh_item_container after the window moves to another folder', () => {
+    let pending;
+
+    beforeEach(() => {
+        pending = { stat: {}, readdir: {} };
+        puter.fs.stat.mockImplementation(({ path }) => {
+            pending.stat[path] = deferred();
+            return pending.stat[path].promise;
+        });
+        puter.fs.readdir.mockImplementation(({ path }) => {
+            pending.readdir[path] ??= deferred();
+            return pending.readdir[path].promise;
+        });
+        document.body.innerHTML =
+            '<div class="window"><div class="item-container"></div></div>';
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it('ignores a stat for the folder it left', async () => {
+        navigate('/alice');
+        navigate('/alice/Pictures');
+
+        pending.stat['/alice/Pictures'].resolve({ id: 'pictures', name: 'Pictures' });
+        pending.stat['/alice'].resolve({ id: 'home', name: 'alice' });
+        await vi.waitFor(() => expect($('.window').attr('data-uid')).toBe('pictures'));
+        await new Promise((r) => setTimeout(r, 0));
+
+        expect($('.window').attr('data-path')).toBe('/alice/Pictures');
+        expect($('.window').attr('data-uid')).toBe('pictures');
+    });
+
+    it('drops a listing that arrives just before the window moves on', async () => {
+        vi.useFakeTimers();
+        navigate('/alice/Documents');
+
+        // A listing slower than 1s waits another second before rendering.
+        await vi.advanceTimersByTimeAsync(1100);
+        pending.readdir['/alice/Documents'].resolve([fileEntry('/alice/Documents', 'a.txt')]);
+        await vi.advanceTimersByTimeAsync(0);
+
+        navigate('/alice/Pictures');
+        pending.readdir['/alice/Pictures'].resolve([fileEntry('/alice/Pictures', 'b.png')]);
+        await vi.advanceTimersByTimeAsync(1000);
+
+        expect(renderedPaths()).toEqual(['/alice/Pictures/b.png']);
+    });
+
+    it('renders a folder once when it is refreshed again before the first listing arrives', async () => {
+        navigate('/alice/Documents');
+        navigate('/alice/Pictures');
+        navigate('/alice/Documents');
+
+        pending.readdir['/alice/Documents'].resolve([fileEntry('/alice/Documents', 'a.txt')]);
+        pending.readdir['/alice/Pictures'].resolve([fileEntry('/alice/Pictures', 'b.png')]);
+        await vi.waitFor(() => expect(UIItem).toHaveBeenCalled());
+        await new Promise((r) => setTimeout(r, 10));
+
+        expect(renderedPaths()).toEqual(['/alice/Documents/a.txt']);
+    });
+});

src/gui/src/i18n/translations/en.js

@@ -129,13 +129,19 @@ const en = {
         choose_publishing_option: 'Choose how you want to publish your website:',
         contact_us: 'Contact Us',
         contact_us_attach: 'Attach Files',
+        contact_us_attach_or_drop: 'Attach files or drop them here',
         contact_us_attach_hint: 'Images and videos — up to %% files, %% MB each.',
         contact_us_attachment_remove: 'Remove attachment',
+        contact_us_attachment_remove_named: 'Remove %%',
         contact_us_attachment_too_large: 'That file is too large. Each attachment can be up to %% MB.',
         contact_us_attachment_too_many: 'You can attach up to %% files.',
         contact_us_attachment_total_too_large: 'Those files add up to more than %% MB. Try attaching fewer of them, or smaller ones.',
+        contact_us_attachments: 'Attachments',
         contact_us_attachment_unsupported: 'That file type is not supported. Attach an image (PNG, JPEG, GIF, WebP) or a video (MP4, MOV, WebM).',
+        contact_us_drop_to_attach: 'Drop to attach',
         contact_us_error: 'Something went wrong. Please try again.',
+        contact_us_message: 'Message',
+        contact_us_message_placeholder: 'How can we help? For a bug, the steps that lead to it help us most.',
         contact_us_message_required: 'Please write a message before sending.',
         contact_us_rate_limited: 'You have sent a lot of messages recently. Please try again later.',
         contact_us_verification_required: 'You must have a verified email address to use this.',
@@ -472,7 +478,16 @@ const en = {
         publish_as_website: 'Publish as website',
         publish_as_serverless_worker: 'Publish as Worker',
         publish_address: 'Address',
+        publish_custom_domain: 'Use a custom domain',
+        publish_custom_domain_dns_hint: 'After publishing, you\'ll get the DNS records to add at your domain provider.',
+        publish_custom_domain_hint: 'Serve this website from a domain you own.',
+        publish_custom_domain_moves: 'This domain is on your account. Publishing moves it here from %%, at no extra cost.',
+        publish_custom_domain_needs_plan: 'Upgrade to use a custom domain, or turn it off to publish without one.',
+        publish_custom_domain_upsell_text: 'Upgrade to serve this website from a domain you own.',
+        publish_custom_domain_upsell_title: 'Custom domains come with a paid plan',
+        publish_domain_failed: 'Your website is live at %%, but the domain wasn\'t added.',
         publish_name_required: 'Enter an address.',
+        publish_site_live: 'Your website is live at %%.',
         publish_website_intro: 'Serves %strong% at a public address anyone can visit.',
         publish_worker_intro: 'Runs %strong% at a public address anyone can call.',
         push_app_turn_off_failed: "Couldn't turn that off. Please try again.",
@@ -996,7 +1011,7 @@ const en = {
         sign_in_with_provider: 'Sign in with %%',
         sign_up_with_provider: 'Sign up with %%',
         sign_up_with_email: 'Sign up using email',
-        popup_opener_uses_puter: '%strong% is powered by Puter for its AI and cloud features.\nUse your Puter account to continue.',
+        popup_opener_uses_puter: '%strong% is powered by Puter',
         popup_opener_origin_unsupported: 'Puter cannot sign you in to this page because the browser gives it no identifiable address. Pages opened straight from a file (file://) and iframes sandboxed without allow-same-origin are not supported — serve the page over http://localhost or a real domain and try again.',
         oidc_switched_to_login_message: 'You have been logged in to an existing account.',
 

src/gui/src/index.js

@@ -60,6 +60,10 @@ window.gui = async (options) => {
     window.co_isolation_enabled = options.co_isolation_enabled;
     window.teams_ui = options.teams_ui ?? false;
 
+    // A popup a first-party page frames answers it before the SDK loads, so
+    // the page knows the frame wasn't refused.
+    window.start_popup_frame?.(options.embed_host_origin);
+
     // DEV: Load the initgui.js file if we are in development mode
     if ( !window.gui_env || window.gui_env === 'dev' ) {
         await window.loadScript('/sdk/puter.dev.js');

src/gui/src/initgui.js

@@ -46,6 +46,8 @@ import UIAuthSignup from './UI/Auth/UIAuthSignup.js';
 import UIAuthRecoverPassword from './UI/Auth/UIAuthRecoverPassword.js';
 import { PROCESS_RUNNING } from './definitions.js';
 import { isAttestedOrigin } from './helpers/attestedOrigin.js';
+import { embedHostUser } from './helpers/embedHostUser.js';
+import { closeAccountChecksOnEscape, focusOnFrameFocus, framedPopupAction, framedPopupParams, startPopupFrame } from './helpers/popupFrame.js';
 import confirm_before_unload from './helpers/confirmBeforeUnload.js';
 import create_access_token from './helpers/createAccessToken.js';
 import create_gui_token from './helpers/createGuiToken.js';
@@ -93,6 +95,7 @@ import { ThemeService } from './services/ThemeService.js';
 import { privacy_aware_path as privacy_aware_path_factory } from './util/desktop.js';
 import { resolveAPIOrigin } from './util/apiOrigin.js';
 import {
+    defersTokenToOpener,
     deliversTokenAtBoot,
     relationshipIsConsent,
     relaysTokenAtBoot,
@@ -566,6 +569,9 @@ const postAuthActions = async (action) => {
                 msg,
                 original_msg_id: msg_id,
             }, '*');
+            // Escape closes only the picker window, which would leave the
+            // page's frame open over an empty desktop.
+            if ( window.embedded_in_frame ) window.close();
         };
 
         if ( action === 'show-open-file-picker' ) {
@@ -632,12 +638,15 @@ const postAuthActions = async (action) => {
                 msg: 'sendMeFileData',
             }, '*');
 
-            // listen for 'showSaveFilePickerPopup' event from parent
-            window.addEventListener('message', async (event) => {
-                if ( event.data.msg !== 'showSaveFilePickerPopup' )
+            // listen for 'showSaveFilePickerPopup' event from parent. Only the
+            // page that asked supplies the file, once; any other window that
+            // can reach this one (a sibling frame of the framing page) can't.
+            window.addEventListener('message', async function onFileData (event) {
+                if ( event.data?.msg !== 'showSaveFilePickerPopup' || event.source !== window.opener )
                 {
                     return;
                 }
+                window.removeEventListener('message', onFileData);
 
                 // Open dialog
                 UIWindow({
@@ -650,6 +659,7 @@ const postAuthActions = async (action) => {
                     title: 'Save',
                     is_dir: true,
                     is_saveFileDialog: true,
+                    saveFileDialog_default_filename: event.data.suggestedName ?? '',
                     is_resizable: false,
                     has_head: false,
                     cover_page: true,
@@ -709,7 +719,14 @@ const postAuthActions = async (action) => {
                             catch ( err ) {
                                 // item with same name exists
                                 if ( err.code === 'item_with_same_name_exists' ) {
-                                    const alert_resp = await UIAlert({
+                                    // Escape closes the alert without an answer,
+                                    // which counts as Cancel, so the picker isn't
+                                    // left behind its busy mask.
+                                    let alert_closed;
+                                    const alert_dismissed = new Promise((resolve) => {
+                                        alert_closed = () => resolve('cancel');
+                                    });
+                                    const alert_resp = await Promise.race([UIAlert({
                                         message: `<strong>${html_encode(err.entry_name)}</strong> already exists.`,
                                         buttons: [
                                             {
@@ -723,10 +740,11 @@ const postAuthActions = async (action) => {
                                             },
                                         ],
                                         parent_uuid: $(el_filedialog_window).attr('data-element_uuid'),
-                                    });
+                                        window_options: { on_close: alert_closed },
+                                    }), alert_dismissed]);
                                     if ( alert_resp === 'replace' ) {
                                         overwrite = true;
-                                    } else if ( alert_resp === 'cancel' ) {
+                                    } else {
                                         // enable parent window
                                         $(el_filedialog_window).find('.window-disable-mask, .busy-indicator').hide();
                                         return;
@@ -1154,9 +1172,17 @@ if (jQuery) {
 {
     const pathname = window.location.pathname;
     const search_params = new URLSearchParams(window.location.search);
-    if (['true', '1'].includes(search_params.get('embedded_in_popup'))) {
+    // A popup a first-party page frames at `/embed/<action>` boots as one.
+    if (['true', '1'].includes(search_params.get('embedded_in_popup')) || framedPopupAction(pathname)) {
         window.embedded_in_popup = true;
     }
+    // Called by the bootstrap in index.js, which can't import.
+    window.start_popup_frame = (hostOrigin) => {
+        if (!framedPopupAction(pathname)) return;
+        window.tell_popup_frame = startPopupFrame(window, hostOrigin);
+        window.embedded_in_frame = !!window.tell_popup_frame;
+        if (window.embedded_in_frame) focusOnFrameFocus(window);
+    };
     // note: iframe detection is inlined because globals.js (window.is_embedded) loads after this module
     const in_iframe = window.location !== window.parent.location;
     const needs_desktop_at_root =
@@ -1411,8 +1437,16 @@ window.initgui = async function (options) {
     const url_paths = parse_url_paths(window.location.pathname);
     window.url_paths = url_paths;
 
-    // GET query params provided
-    window.url_query_params = new URLSearchParams(window.location.search);
+    // A framed popup without a framing page to answer (opened on its own, or
+    // framed by a page the server refused) has nothing to do.
+    const framed_action = framedPopupAction(window.location.pathname);
+    if (framed_action && !window.embedded_in_frame) return;
+
+    // GET query params provided. A framed popup takes the popup's parameters
+    // from its fragment; its route refuses a query string.
+    window.url_query_params = framed_action
+        ? framedPopupParams(window.location.hash)
+        : new URLSearchParams(window.location.search);
     window.signup_bonus_code = readSignupBonusCode(window.url_query_params);
 
     // Install device signal helpers; collection is lazy. The fingerprint is
@@ -1506,7 +1540,9 @@ window.initgui = async function (options) {
     // Extract 'action' from URL
     //--------------------------------------------------------------------------------------
     let action;
-    if (
+    if (framed_action) {
+        action = framed_action;
+    } else if (
         window.url_paths[0]?.toLocaleLowerCase() === 'action' &&
         window.url_paths[1]
     ) {
@@ -1520,6 +1556,8 @@ window.initgui = async function (options) {
     // action. See util/popupAuth.js.
     window.gui_action = action;
 
+    if (window.embedded_in_frame && action === 'sign-in') closeAccountChecksOnEscape(window);
+
     if (action === 'oidc-2fa') {
         const result = oidcChallenge?.token && await UIAuth2FA(oidcChallenge.token);
         if (result?.redirectUrl) {
@@ -1643,7 +1681,9 @@ window.initgui = async function (options) {
             action,
         );
         try {
-            window.openerOrigin = await resolveOpenerOrigin({
+            // A framed popup's opener is the page the server read from the
+            // referrer and pinned with frame-ancestors.
+            window.openerOrigin = window.embedded_in_frame ? window.gui_params.embed_host_origin : await resolveOpenerOrigin({
                 relaysToken: relaysTokenAtBoot(
                     action,
                     window.url_query_params.get('cross_origin_isolated') ===
@@ -1700,6 +1740,26 @@ window.initgui = async function (options) {
         // this is the referrer in terms of user acquisition
         window.referrerStr = window.openerOrigin;
 
+        // A framed picker shows only the Puter session of the user the
+        // framing page is signed in as; for anyone else the page uses the
+        // popup, which can sign in and switch accounts.
+        if (window.embedded_in_frame && defersTokenToOpener(action)) {
+            const host_user = embedHostUser(window.location.hash);
+            let session_user = null;
+            if (host_user && window.is_auth()) {
+                try {
+                    const session = await puter.os.user({ query: 'icon_size=64' });
+                    session_user = String(session?.uuid ?? '').toLowerCase();
+                } catch (e) {
+                    session_user = null;
+                }
+            }
+            if (!host_user || session_user !== host_user) {
+                window.tell_popup_frame('unavailable');
+                return;
+            }
+        }
+
         // Tell a request-permission opener that this popup can reach it. Sent
         // here, before any sign-in gate, because the SDK reads its absence as
         // "the opener link was severed by COOP" — where a close means the
@@ -1951,8 +2011,11 @@ window.initgui = async function (options) {
         );
         window.userAppToken = response?.token;
 
+        // A framed picker already holds the framing page's user, so it
+        // doesn't offer to switch.
         if (
             !picked_a_user_for_sdk_login &&
+            !(window.embedded_in_frame && defersTokenToOpener(action)) &&
             window.logged_in_users.length > 1 &&
             (!window.userAppToken ||
                 window.url_query_params.get('request_auth'))

src/gui/src/keyboard.escape.test.js

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import jQuery from './lib/jquery-3.6.1/jquery-3.6.1.min.js';
+
+vi.mock('./UI/UIAlert.js', () => ({ default: vi.fn() }));
+vi.mock('./UI/UIWindowSearch.js', () => ({ default: vi.fn() }));
+vi.mock('./helpers/launchApp.js', () => ({ default: vi.fn() }));
+vi.mock('./helpers/openItem.js', () => ({ default: vi.fn() }));
+
+globalThis.$ = jQuery;
+globalThis.jQuery = jQuery;
+globalThis.i18n = key => key;
+globalThis.def = globalThis.def ?? (value => value);
+globalThis.use = globalThis.use ?? (() => class {});
+
+await import('./keyboard.js');
+
+const escape = () => document.body.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', keyCode: 27, which: 27, bubbles: true }));
+
+describe('Escape on a file dialog', () => {
+    const closed = [];
+
+    beforeEach(() => {
+        closed.length = 0;
+        jQuery.fn.close = function () {
+            closed.push(...this.toArray());
+            return this;
+        };
+        document.body.innerHTML = '<div class="window window-active window-filedialog"></div>';
+    });
+
+    it('closes the file dialog', () => {
+        escape();
+        expect(closed).toEqual([document.querySelector('.window-filedialog')]);
+    });
+
+    it('closes only a context menu open over it', () => {
+        document.body.insertAdjacentHTML('beforeend', '<div class="context-menu"></div>');
+        escape();
+        expect(document.querySelector('.context-menu')).toBeNull();
+        expect(closed).toEqual([]);
+
+        escape();
+        expect(closed).toEqual([document.querySelector('.window-filedialog')]);
+    });
+});

src/gui/src/keyboard.js

@@ -448,6 +448,8 @@ $(document).bind('keydown', async function (e) {
     else if (
         // escape key code
         e.which === 27 &&
+        // an open context menu takes the Escape (below) instead
+        $('.context-menu').length === 0 &&
         // active window must be a FileDialog or Alert
         ($('.window-active').hasClass('window-filedialog') || $('.window-active').hasClass('window-alert')) &&
         // either don't close if an input is focused or if the input is the filename input

src/gui/webpack/BaseConfig.cjs

@@ -93,6 +93,7 @@ module.exports = async (options = {}) => {
             ...entries,
         ],
         'apps-embed': './src/appsEmbed.js',
+        'feedback-embed': './src/feedbackEmbed.js',
     };
     config.output = {
         path: path.resolve(__dirname, '../dist'),

src/puter-js/index.d.ts

@@ -44,17 +44,17 @@ export type {
     ListTTSEnginesOptions,
     ListTTSVoicesOptions,
     OcrAnnotationFormat,
-    ConvoOptions,
-    ConvoTextEvent,
-    ConvoAudioEvent,
-    ConvoTranscriptEvent,
-    ConvoInterruptedEvent,
-    ConvoTurnDoneEvent,
-    ConvoErrorEvent,
-    ConvoEventMap,
-    ConvoSessionOptions,
-    ConvoPlaybackPosition,
-    ConvoSpeakerOptions,
+    RealtimeOptions,
+    RealtimeTextEvent,
+    RealtimeAudioEvent,
+    RealtimeTranscriptEvent,
+    RealtimeInterruptedEvent,
+    RealtimeTurnDoneEvent,
+    RealtimeErrorEvent,
+    RealtimeEventMap,
+    RealtimeSessionOptions,
+    RealtimePlaybackPosition,
+    RealtimeSpeakerOptions,
     RealtimeServerEvent,
     RealtimeClientEvent,
     Speech2SpeechOptions,
@@ -391,5 +391,5 @@ export type Teams = InstanceType<import('./types/modules/teams/index.js').TeamsC
 export type UI = InstanceType<import('./types/modules/UI.js').UIConstructor>;
 export type WorkersHandler = InstanceType<import('./types/modules/Workers.js').WorkersConstructor>;
 
-export type { Conversation, ConvoError } from './types/modules/ai/convo.js';
-export type { ConvoMicrophone, ConvoSpeaker } from './types/modules/ai/convoMedia.js';
+export type { Conversation, RealtimeError } from './types/modules/ai/realtime.js';
+export type { RealtimeMicrophone, RealtimeSpeaker } from './types/modules/ai/realtimeMedia.js';

src/puter-js/src/lib/guiEmbed.js

@@ -0,0 +1,412 @@
+/**
+ * Puter GUI pages a first-party site can frame, under `/embed/*` on the GUI
+ * origin. The server lets only a page one label under that origin frame them.
+ */
+
+// After the frame loads, how long to wait for the embed's first message
+// before treating it as refused (a CSP that blocks it still fires `load`).
+const LOAD_GRACE_MS = 1000;
+// How long the embed may take to check the session before the popup is used.
+const READY_TIMEOUT_MS = 15_000;
+// A session check slower than this shows a loading scrim over the page.
+const LOADING_DELAY_MS = 200;
+
+// The loading scrim matches the feedback embed's own, which fades in over it
+// once ready. A popup frame keeps it as the scrim behind its box. Scrolling
+// over the dialog stays there rather than scrolling the page behind it.
+const embedStyle = (cls) => `
+dialog.${cls}{overscroll-behavior:contain}
+dialog.${cls}::backdrop{background:transparent}
+dialog.${cls}:focus{outline:none}
+.${cls}-loading{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;background:rgba(0,0,0,.5);opacity:0;pointer-events:none;transition:opacity .16s ease-in-out}
+.${cls}.is-loading .${cls}-loading{opacity:1;pointer-events:auto}
+.${cls}.is-loading iframe{visibility:hidden}
+.${cls}-loading span{width:28px;height:28px;box-sizing:border-box;border:3px solid rgba(255,255,255,.3);border-top-color:#fff;border-radius:50%;animation:${cls}-spin .7s linear infinite}
+@keyframes ${cls}-spin{to{transform:rotate(360deg)}}
+@media (prefers-color-scheme:dark){.${cls}-loading{background:rgba(0,0,0,.66)}}
+@media (prefers-reduced-motion:reduce){.${cls}-loading{transition:none}.${cls}-loading span{animation-duration:1.6s}}
+`;
+
+// A popup frame sits in a box the size of the popup window it replaces, over
+// the scrim, and fills the screen on a phone as the popup's tab would. It's
+// centered by margins, which snap to device pixels where a translate can
+// leave its edge on a fraction of one. Its white backing stops 1px inside the
+// rounded edge, so in dark mode it doesn't show as a light fringe around the
+// frame. The close button starts from `all:unset` so the page's own button
+// styles don't reach it.
+const BOX_STYLE = `
+.puter-popup-frame .puter-popup-frame-loading{opacity:1;pointer-events:auto}
+.puter-popup-frame:not(.is-loading) .puter-popup-frame-loading span{display:none}
+.puter-popup-frame.is-loading .puter-popup-frame-box{visibility:hidden}
+.puter-popup-frame-box{position:absolute;inset:0;margin:auto;isolation:isolate;box-sizing:border-box;width:min(var(--puter-popup-frame-width),calc(100% - 32px));height:min(var(--puter-popup-frame-height),calc(100% - 32px));border-radius:12px;overflow:hidden;box-shadow:0 24px 64px rgba(0,0,0,.35)}
+.puter-popup-frame-box::before{content:"";position:absolute;inset:1px;z-index:-1;border-radius:11px;background:#fff}
+.puter-popup-frame-close{all:unset;box-sizing:border-box;position:absolute;top:10px;right:10px;width:32px;height:32px;display:flex;align-items:center;justify-content:center;padding:0;border:0;border-radius:50%;background:transparent;color:#6b7280;cursor:pointer}
+.puter-popup-frame-close:hover{background:rgba(127,127,127,.15)}
+.puter-popup-frame-close:focus-visible{outline:2px solid #3b82f6;outline-offset:1px}
+.puter-popup-frame-close svg{width:16px;height:16px}
+@media (prefers-color-scheme:dark){.puter-popup-frame-close{color:#9ca3af}}
+@media (max-width:600px){.puter-popup-frame-box{width:100%;height:100%;border-radius:0}.puter-popup-frame-box::before{inset:0;border-radius:0}}
+.puter-popup-frame[open] .puter-popup-frame-loading,.puter-popup-frame:not(.is-loading) .puter-popup-frame-box{animation:puter-popup-frame-in .16s ease-out}
+@keyframes puter-popup-frame-in{from{opacity:0}}
+@media (prefers-reduced-motion:reduce){.puter-popup-frame[open] .puter-popup-frame-loading,.puter-popup-frame:not(.is-loading) .puter-popup-frame-box{animation:none}}
+`;
+
+const CLOSE_ICON = '<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3.5 3.5l9 9m0-9l-9 9" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" fill="none"/></svg>';
+
+// Subdomains the server answers or reserves itself, which it never lets frame
+// an embed (the backend's `isReservedSubdomain`). Framing from one would wait
+// on a refused frame before falling back.
+const RESERVED_LABELS = new Set(['www', 'api', 'js', 'dav', 'about', 'developer', 'docs', 'apps', 'puter-app-icons']);
+
+// Dismisses the single-instance embed showing at each path.
+const showingEmbeds = new Map();
+
+/**
+ * Whether a page at `pageUrl` may frame an embed served by `guiOrigin`:
+ * exactly one label under its host, on the same scheme and port, and not one
+ * of the GUI's reserved subdomains.
+ *
+ * @param {string | undefined} pageUrl
+ * @param {string} guiOrigin
+ * @returns {boolean}
+ */
+export const canFrameGuiEmbed = (pageUrl, guiOrigin) => {
+    let page;
+    let gui;
+    try {
+        page = new URL(pageUrl);
+        gui = new URL(guiOrigin);
+    } catch {
+        return false;
+    }
+    const host = page.hostname.replace(/\.$/, '').toLowerCase();
+    const suffix = `.${gui.hostname.toLowerCase()}`;
+    if ( page.protocol !== gui.protocol || page.port !== gui.port || !host.endsWith(suffix) ) return false;
+    const label = host.slice(0, -suffix.length);
+    return label.length > 0 && !label.includes('.') && !RESERVED_LABELS.has(label);
+};
+
+/**
+ * Whether every frame above `win` may frame an embed too. The server's
+ * frame-ancestors allows only the GUI and the page, so in a frame of any other
+ * site the embed is refused, and opening the popup straight away is faster.
+ *
+ * @param {Window} win - the page
+ * @param {string} guiOrigin
+ * @returns {boolean}
+ */
+export const ancestorsAllowGuiEmbed = (win, guiOrigin) => {
+    let gui;
+    try {
+        gui = new URL(guiOrigin).origin;
+    } catch {
+        return false;
+    }
+    const page = win.location.origin;
+    const ancestors = win.location.ancestorOrigins;
+    if ( ancestors ) return Array.from(ancestors).every((origin) => origin === page || origin === gui);
+    // Without ancestorOrigins (Firefox), only a same-origin ancestor can be named.
+    try {
+        for ( let w = win; w.parent !== w; w = w.parent ) {
+            if ( w.parent.location.origin !== page ) return false;
+        }
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+/**
+ * Mounts `/embed/<path>` in a modal frame, hidden until the embed reports
+ * `ready` and behind a loading scrim once its start takes longer than
+ * LOADING_DELAY_MS. Resolves what `onMessage` finishes with, what `dismissed`
+ * returns when the user cancels, or null when the frame is refused, never
+ * answers, or reports itself unavailable. Never rejects.
+ *
+ * @template T
+ * @param {Object} opts
+ * @param {string} opts.guiOrigin
+ * @param {string} opts.path - under the GUI origin, such as `/embed/feedback`
+ * @param {Record<string, string>} opts.fragment - what the embed reads from its fragment
+ * @param {string} opts.className - the dialog's class, prefixing its parts'
+ * @param {string} opts.title - the frame's accessible name
+ * @param {string} opts.stateMsg - `msg` of the embed's loading, ready and unavailable messages
+ * @param {{ width: number, height: number }} [opts.box] - shows the frame in a box this size over a scrim; without it the frame covers the page and the embed draws its own scrim
+ * @param {string} [opts.closeLabel] - puts a close button on the box, which dismisses it
+ * @param {string} [opts.allow] - the frame's permissions policy, for features the embed uses
+ * @param {boolean} [opts.escapeDismisses] - Escape on the page dismisses a ready embed too, instead of handing it the keys
+ * @param {boolean} [opts.single] - a newer embed at this path dismisses this one, as a named popup window is reused
+ * @param {() => T} opts.dismissed - the result of a dismissal: Escape or a click on the loading scrim, or the close button
+ * @param {(data: Record<string, unknown>, finish: (result: T | null) => void) => void} opts.onMessage - every other message from the embed
+ * @param {(frame: Window) => void} [opts.onFrame] - the frame's window, once it exists
+ * @returns {Promise<T | null>}
+ */
+const mountGuiEmbed = ({ guiOrigin, path, fragment, className, title, stateMsg, box, closeLabel, allow, escapeDismisses = false, single = false, dismissed, onMessage, onFrame }) => new Promise((resolve) => {
+    let origin;
+    try {
+        origin = new URL(guiOrigin).origin;
+    } catch {
+        resolve(null);
+        return;
+    }
+    const url = new URL(path, origin);
+    url.hash = new URLSearchParams(fragment).toString();
+    // Before reading the focus this one restores, which the older one hands back.
+    if ( single ) showingEmbeds.get(path)?.();
+
+    const dialog = document.createElement('dialog');
+    dialog.className = className;
+    dialog.setAttribute('aria-label', title);
+    // Inline, so the page's own `dialog` and `iframe` styles can't move,
+    // round or shrink them.
+    dialog.style.cssText = 'position:fixed;inset:0;width:100%;height:100%;min-width:0;min-height:0;max-width:none;max-height:none;margin:0;padding:0;border:0;border-radius:0;box-shadow:none;transform:none;background:transparent;overflow:hidden;';
+    const style = document.createElement('style');
+    style.textContent = embedStyle(className) + (box ? BOX_STYLE : '');
+    const frame = document.createElement('iframe');
+    frame.title = title;
+    // The embed allows a framing page it can name from the referrer.
+    frame.setAttribute('referrerpolicy', 'origin');
+    if ( allow ) frame.setAttribute('allow', allow);
+    const frameBase = 'display:block;width:100%;height:100%;min-width:0;min-height:0;max-width:none;max-height:none;margin:0;padding:0;border:0;';
+    // A frame whose color-scheme differs from its document's is painted
+    // opaque, so this matches the embed's. WebKit also gives the frame this
+    // scheme as its preferred one, so it has to follow the OS.
+    frame.style.cssText = box
+        ? frameBase
+        : `${frameBase}background:transparent;color-scheme:light dark;`;
+    const loading = document.createElement('div');
+    loading.className = `${className}-loading`;
+    loading.setAttribute('role', 'status');
+    loading.setAttribute('aria-label', 'Loading');
+    loading.setAttribute('aria-hidden', 'true');
+    loading.append(document.createElement('span'));
+    dialog.append(style, loading);
+    if ( box ) {
+        const container = document.createElement('div');
+        container.className = `${className}-box`;
+        container.style.setProperty('--puter-popup-frame-width', `${box.width}px`);
+        container.style.setProperty('--puter-popup-frame-height', `${box.height}px`);
+        container.append(frame);
+        if ( closeLabel ) {
+            const close = document.createElement('button');
+            close.type = 'button';
+            close.className = `${className}-close`;
+            close.setAttribute('aria-label', closeLabel);
+            close.title = closeLabel;
+            close.innerHTML = CLOSE_ICON;
+            close.addEventListener('click', () => dismiss());
+            container.append(close);
+        }
+        dialog.append(container);
+    } else {
+        dialog.insertBefore(frame, loading);
+    }
+
+    let settled = false;
+    let heard = false;
+    let shown = false;
+    let ready = false;
+    let timer = null;
+    let loadingTimer = null;
+    // Each embed document posts `loading` once; these tell a document that
+    // never did (one the server refused) from one that did.
+    let loads = 0;
+    let boots = 0;
+    let wasReady = false;
+    let restarted = false;
+    let restartTimer = null;
+    const restoreFocus = document.activeElement;
+    const wait = (ms) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => finish(null), ms);
+    };
+    const finish = (result) => {
+        if ( settled ) return;
+        settled = true;
+        clearTimeout(timer);
+        clearTimeout(loadingTimer);
+        clearTimeout(restartTimer);
+        window.removeEventListener('message', onWindowMessage);
+        if ( showingEmbeds.get(path) === dismiss ) showingEmbeds.delete(path);
+        dialog.remove();
+        if ( shown ) restoreFocus?.focus?.({ preventScroll: true });
+        resolve(result);
+    };
+    const dismiss = () => finish(dismissed());
+    if ( single ) showingEmbeds.set(path, dismiss);
+    // The spinner is only faded out, so assistive tech hears it only while it shows.
+    const setLoading = (on) => {
+        dialog.classList.toggle('is-loading', on);
+        if ( on ) loading.removeAttribute('aria-hidden');
+        else loading.setAttribute('aria-hidden', 'true');
+    };
+    const show = () => {
+        if ( dialog.open ) return;
+        shown = true;
+        dialog.showModal();
+    };
+    const onWindowMessage = (event) => {
+        if ( event.origin !== origin || event.source !== frame.contentWindow ) return;
+        const data = event.data;
+        if ( !data || typeof data !== 'object' ) return;
+        if ( data.msg !== stateMsg || !['loading', 'ready', 'unavailable'].includes(data.state) ) {
+            onMessage(data, finish);
+        } else if ( data.state === 'loading' ) {
+            heard = true;
+            boots++;
+            wait(READY_TIMEOUT_MS);
+        } else if ( data.state === 'ready' ) {
+            heard = true;
+            ready = true;
+            wasReady = true;
+            restarted = false;
+            clearTimeout(timer);
+            clearTimeout(loadingTimer);
+            setLoading(false);
+            show();
+            frame.focus();
+        } else {
+            finish(null);
+        }
+    };
+    // A reload or navigation the embed starts itself names the embed, not
+    // this page, as its referrer, so the server refuses to let it frame. This
+    // page opens the embed again, once, which it allows.
+    const restart = () => {
+        if ( restarted ) {
+            finish(null);
+            return;
+        }
+        restarted = true;
+        ready = false;
+        loads = boots;
+        setLoading(true);
+        // As long as its first start may take, then the popup.
+        wait(READY_TIMEOUT_MS);
+        // WebKit takes the refused URL itself as a fragment navigation of its
+        // error page, which loads nothing. The server redirects a query away,
+        // and the fragment carries over the redirect.
+        const reopen = new URL(url);
+        reopen.search = 'reopen';
+        frame.src = reopen.href;
+    };
+    window.addEventListener('message', onWindowMessage);
+    frame.addEventListener('load', () => {
+        loads++;
+        if ( ! heard ) wait(LOAD_GRACE_MS);
+        if ( ! wasReady || boots >= loads ) return;
+        // Most likely refused: the spinner covers the error page meanwhile.
+        ready = false;
+        setLoading(true);
+        const expected = loads;
+        clearTimeout(restartTimer);
+        restartTimer = setTimeout(() => {
+            if ( boots < expected ) restart();
+        }, LOAD_GRACE_MS);
+    });
+    // Once ready, Escape outside the frame would close the dialog with the
+    // embed's own dialog still open inside it, so the embed owns dismissal
+    // unless it dismisses on Escape too.
+    dialog.addEventListener('cancel', (event) => {
+        event.preventDefault();
+        if ( ready && ! escapeDismisses ) frame.focus();
+        else dismiss();
+    });
+    loading.addEventListener('click', () => {
+        if ( ! ready ) dismiss();
+    });
+
+    try {
+        frame.src = url.href;
+        // Hidden at first, so a quickly refused session shows nothing.
+        document.body.append(dialog);
+        onFrame?.(frame.contentWindow);
+        wait(READY_TIMEOUT_MS);
+        loadingTimer = setTimeout(() => {
+            setLoading(true);
+            show();
+        }, LOADING_DELAY_MS);
+    } catch {
+        finish(null);
+    }
+});
+
+/**
+ * Shows the app feedback dialog from `/embed/feedback` in a modal frame over
+ * the page, as the user named, behind a loading scrim while a slow session
+ * check runs. Resolves `{ sent }` once the dialog closes or the user cancels
+ * the loading scrim, or null when the embed can't serve this user (no
+ * matching Puter session, an email to confirm, or a refused frame), so the
+ * caller can use the popup instead. Never rejects.
+ *
+ * @param {Object} opts
+ * @param {string} opts.guiOrigin
+ * @param {string} opts.userUuid - the page's signed-in user
+ * @returns {Promise<{ sent: boolean } | null>}
+ */
+export const showFeedbackEmbed = ({ guiOrigin, userUuid }) => mountGuiEmbed({
+    guiOrigin,
+    path: '/embed/feedback',
+    fragment: { user: userUuid },
+    className: 'puter-feedback-embed',
+    title: 'Send feedback',
+    stateMsg: 'feedbackEmbed',
+    dismissed: () => ({ sent: false }),
+    onMessage: ({ msg, sent }, finish) => {
+        if ( msg === 'feedbackDialogClosed' ) finish({ sent: sent === true });
+    },
+});
+
+/** Popup actions a first-party page shows framed, each in a box its popup window's size. */
+const POPUP_FRAME_BOXES = {
+    'sign-in': { width: 600, height: 700 },
+    'show-open-file-picker': { width: 700, height: 400 },
+    'show-save-file-picker': { width: 700, height: 400 },
+    'show-directory-picker': { width: 700, height: 400 },
+};
+
+/**
+ * Shows the GUI popup for `action` in a frame over the page instead of a
+ * window, from `/embed/<action>`. The GUI runs the popup unchanged and posts
+ * its answers to this page as it would to an opener; `onMessage` sees each of
+ * them and finishes with the result. The frame closing on its own, as the
+ * popup would, finishes with `closed()`, and so does the user dismissing it.
+ * Resolves null when the frame can't serve the request (refused, never
+ * answering, or reporting itself unavailable), so the caller can open the
+ * popup instead. Never rejects.
+ *
+ * @template T
+ * @param {Object} opts
+ * @param {string} opts.guiOrigin
+ * @param {'sign-in' | 'show-open-file-picker' | 'show-save-file-picker' | 'show-directory-picker'} opts.action
+ * @param {Record<string, string>} opts.fragment - the popup's parameters, and `user` for a picker
+ * @param {string} opts.title - the frame's accessible name
+ * @param {string} [opts.closeLabel] - puts a close button on the frame
+ * @param {() => T} opts.closed
+ * @param {(data: Record<string, unknown>, finish: (result: T) => void) => void} opts.onMessage
+ * @param {(frame: Window) => void} [opts.onFrame]
+ * @returns {Promise<T | null>}
+ */
+export const showPopupFrame = ({ guiOrigin, action, fragment, title, closeLabel, closed, onMessage, onFrame }) => mountGuiEmbed({
+    guiOrigin,
+    path: `/embed/${action}`,
+    fragment,
+    className: 'puter-popup-frame',
+    title,
+    stateMsg: 'puterPopupFrame',
+    box: POPUP_FRAME_BOXES[action],
+    closeLabel,
+    // Signup and the account checks fill in a texted code, as in the popup.
+    allow: 'otp-credentials',
+    // Escape inside the frame closes it as well.
+    escapeDismisses: true,
+    // A second request for this popup, such as from a double click, replaces the
+    // first. Each popup has its own window name, so other popups stay open.
+    single: true,
+    dismissed: closed,
+    onFrame,
+    onMessage: (data, finish) => {
+        if ( data.msg === 'puterPopupFrame' && data.state === 'closed' ) finish(closed());
+        else onMessage(data, finish);
+    },
+});

src/puter-js/src/lib/guiEmbed.test.js

@@ -0,0 +1,477 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ancestorsAllowGuiEmbed, canFrameGuiEmbed, showFeedbackEmbed, showPopupFrame } from './guiEmbed.js';
+
+const GUI_ORIGIN = 'https://puter.test';
+const USER = '0b1c9a52-3f0e-4c7a-9a65-2f6d1e8b7c40';
+
+// jsdom has no top-layer dialogs.
+HTMLDialogElement.prototype.showModal = function () {
+    this.open = true;
+};
+
+const frame = () => document.querySelector('dialog.puter-feedback-embed iframe');
+
+/** A message from the embed, by default from its frame on the GUI origin. */
+const fromEmbed = (data, { origin = GUI_ORIGIN, source = frame().contentWindow } = {}) =>
+    window.dispatchEvent(new MessageEvent('message', { data, origin, source }));
+
+beforeEach(() => {
+    document.body.innerHTML = '';
+});
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+describe('canFrameGuiEmbed', () => {
+    it.each([
+        ['https://notes.puter.com/a', 'https://puter.com', true],
+        ['https://NOTES.puter.com./a', 'https://puter.com', true],
+        ['http://notes.puter.localhost:4100/', 'http://puter.localhost:4100', true],
+        ['https://puter.com/', 'https://puter.com', false],
+        ['https://a.b.puter.com/', 'https://puter.com', false],
+        ['https://notputer.com/', 'https://puter.com', false],
+        ['https://notes.puter.com.evil.com/', 'https://puter.com', false],
+        ['http://notes.puter.com/', 'https://puter.com', false],
+        ['https://notes.puter.com:8443/', 'https://puter.com', false],
+        ['https://notes.puter.site/', 'https://puter.com', false],
+        ['https://docs.puter.com/playground/', 'https://puter.com', false],
+        ['https://api.puter.com/', 'https://puter.com', false],
+        ['https://www.puter.com/', 'https://puter.com', false],
+        ['http://apps.puter.localhost:4100/', 'http://puter.localhost:4100', false],
+        [undefined, 'https://puter.com', false],
+    ])('%s under %s is %s', (page, gui, expected) => {
+        expect(canFrameGuiEmbed(page, gui)).toBe(expected);
+    });
+});
+
+describe('ancestorsAllowGuiEmbed', () => {
+    const PAGE = 'https://notes.puter.test';
+    /** A window at `origin` under `parent`; a cross-origin parent throws on `location`, as in a browser. */
+    const fakeWindow = ({ origin = PAGE, ancestorOrigins, parent } = {}) => {
+        const win = { location: { origin, ancestorOrigins } };
+        win.parent = parent ?? win;
+        return win;
+    };
+    const crossOrigin = () => {
+        const win = {};
+        Object.defineProperty(win, 'location', { get: () => { throw new DOMException('Blocked', 'SecurityError'); } });
+        win.parent = win;
+        return win;
+    };
+
+    it.each([
+        ['a top-level page', [], true],
+        ['a frame of the same page', [PAGE], true],
+        ['a frame in the GUI', [PAGE, GUI_ORIGIN], true],
+        ['a frame of another site', ['https://other.test'], false],
+        ['a frame of the page inside another site', [PAGE, 'https://other.test'], false],
+    ])('reads ancestorOrigins for %s', (_, ancestorOrigins, expected) => {
+        expect(ancestorsAllowGuiEmbed(fakeWindow({ ancestorOrigins }), GUI_ORIGIN)).toBe(expected);
+    });
+
+    it('walks same-origin parents without ancestorOrigins', () => {
+        expect(ancestorsAllowGuiEmbed(fakeWindow(), GUI_ORIGIN)).toBe(true);
+        expect(ancestorsAllowGuiEmbed(fakeWindow({ parent: fakeWindow() }), GUI_ORIGIN)).toBe(true);
+        expect(ancestorsAllowGuiEmbed(fakeWindow({ parent: crossOrigin() }), GUI_ORIGIN)).toBe(false);
+    });
+});
+
+describe('showFeedbackEmbed', () => {
+    it('loads the embed for the named user, hidden until it is ready', () => {
+        showFeedbackEmbed({ guiOrigin: `${GUI_ORIGIN}/`, userUuid: USER });
+        const url = new URL(frame().src);
+        expect(url.origin + url.pathname).toBe(`${GUI_ORIGIN}/embed/feedback`);
+        expect(url.search).toBe('');
+        expect(new URLSearchParams(url.hash.slice(1)).get('user')).toBe(USER);
+        expect(frame().getAttribute('referrerpolicy')).toBe('origin');
+        // WebKit hands the frame this as its preferred scheme; it must follow the OS.
+        expect(frame().getAttribute('style')).toContain('color-scheme: light dark');
+        expect(frame().closest('dialog').open).toBe(false);
+    });
+
+    it('shows the dialog once ready and resolves what it reports, restoring focus', async () => {
+        const trigger = document.createElement('button');
+        document.body.append(trigger);
+        trigger.focus();
+        const result = showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        const dialog = frame().closest('dialog');
+
+        fromEmbed({ msg: 'feedbackEmbed', state: 'loading' });
+        expect(dialog.open).toBe(false);
+        fromEmbed({ msg: 'feedbackEmbed', state: 'ready' });
+        expect(dialog.open).toBe(true);
+        expect(document.activeElement).toBe(frame());
+
+        fromEmbed({ msg: 'feedbackDialogClosed', sent: true });
+        await expect(result).resolves.toEqual({ sent: true });
+        expect(dialog.isConnected).toBe(false);
+        expect(document.activeElement).toBe(trigger);
+    });
+
+    it('shows a loading scrim over the page while a slow session check runs, then the dialog', async () => {
+        vi.useFakeTimers();
+        const trigger = document.createElement('button');
+        document.body.append(trigger);
+        trigger.focus();
+        const result = showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        const dialog = frame().closest('dialog');
+        fromEmbed({ msg: 'feedbackEmbed', state: 'loading' });
+        await vi.advanceTimersByTimeAsync(199);
+        expect(dialog.open).toBe(false);
+        await vi.advanceTimersByTimeAsync(1);
+        expect(dialog.open).toBe(true);
+        expect(dialog.classList.contains('is-loading')).toBe(true);
+        expect(dialog.querySelector('[role="status"]').hasAttribute('aria-hidden')).toBe(false);
+
+        fromEmbed({ msg: 'feedbackEmbed', state: 'ready' });
+        expect(dialog.classList.contains('is-loading')).toBe(false);
+        expect(dialog.querySelector('[role="status"]').getAttribute('aria-hidden')).toBe('true');
+        expect(document.activeElement).toBe(frame());
+        fromEmbed({ msg: 'feedbackDialogClosed', sent: true });
+        await expect(result).resolves.toEqual({ sent: true });
+        expect(document.activeElement).toBe(trigger);
+    });
+
+    it('never shows the loading scrim when the embed is ready quickly', async () => {
+        vi.useFakeTimers();
+        showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        const dialog = frame().closest('dialog');
+        fromEmbed({ msg: 'feedbackEmbed', state: 'ready' });
+        await vi.advanceTimersByTimeAsync(1000);
+        expect(dialog.open).toBe(true);
+        expect(dialog.classList.contains('is-loading')).toBe(false);
+    });
+
+    it('takes the loading scrim down for the popup when the embed turns out unavailable', async () => {
+        vi.useFakeTimers();
+        const trigger = document.createElement('button');
+        document.body.append(trigger);
+        trigger.focus();
+        const result = showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        await vi.advanceTimersByTimeAsync(200);
+        fromEmbed({ msg: 'feedbackEmbed', state: 'unavailable' });
+        await expect(result).resolves.toBeNull();
+        expect(document.querySelector('dialog')).toBeNull();
+        expect(document.activeElement).toBe(trigger);
+    });
+
+    it.each([
+        ['Escape', (dialog) => dialog.dispatchEvent(new Event('cancel', { cancelable: true }))],
+        ['a click on the scrim', (dialog) => dialog.querySelector('[role="status"]').click()],
+    ])('lets %s cancel while loading, without falling back to the popup', async (_label, cancel) => {
+        vi.useFakeTimers();
+        const result = showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        await vi.advanceTimersByTimeAsync(200);
+        cancel(frame().closest('dialog'));
+        await expect(result).resolves.toEqual({ sent: false });
+        expect(document.querySelector('dialog')).toBeNull();
+    });
+
+    it('resolves null without showing anything when the embed is unavailable', async () => {
+        const result = showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        const dialog = frame().closest('dialog');
+        fromEmbed({ msg: 'feedbackEmbed', state: 'loading' });
+        fromEmbed({ msg: 'feedbackEmbed', state: 'unavailable' });
+        await expect(result).resolves.toBeNull();
+        expect(dialog.open).toBe(false);
+        expect(dialog.isConnected).toBe(false);
+    });
+
+    it('ignores messages from another origin or another window', async () => {
+        const result = showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        fromEmbed({ msg: 'feedbackDialogClosed', sent: true }, { origin: 'https://other.test' });
+        fromEmbed({ msg: 'feedbackDialogClosed', sent: true }, { source: window });
+        fromEmbed({ msg: 'feedbackEmbed', state: 'ready' }, { origin: 'https://notes.puter.test' });
+        expect(frame().closest('dialog').open).toBe(false);
+
+        fromEmbed({ msg: 'feedbackDialogClosed', sent: false });
+        await expect(result).resolves.toEqual({ sent: false });
+    });
+
+    it('resolves null when the frame loads without the embed answering', async () => {
+        vi.useFakeTimers();
+        const result = showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        frame().dispatchEvent(new Event('load'));
+        await vi.advanceTimersByTimeAsync(1000);
+        await expect(result).resolves.toBeNull();
+        expect(document.querySelector('dialog')).toBeNull();
+    });
+
+    it('gives a loading embed time to check the session, then gives up', async () => {
+        vi.useFakeTimers();
+        const result = showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        fromEmbed({ msg: 'feedbackEmbed', state: 'loading' });
+        frame().dispatchEvent(new Event('load'));
+        let settled = false;
+        result.then(() => {
+            settled = true;
+        });
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(settled).toBe(false);
+        await vi.advanceTimersByTimeAsync(10_000);
+        await expect(result).resolves.toBeNull();
+    });
+
+    it('keeps the dialog open on Escape outside the frame, since the embed owns dismissal', () => {
+        showFeedbackEmbed({ guiOrigin: GUI_ORIGIN, userUuid: USER });
+        fromEmbed({ msg: 'feedbackEmbed', state: 'ready' });
+        const dialog = frame().closest('dialog');
+        const cancel = new Event('cancel', { cancelable: true });
+        dialog.dispatchEvent(cancel);
+        expect(cancel.defaultPrevented).toBe(true);
+        expect(dialog.isConnected).toBe(true);
+    });
+
+    it('resolves null for an unusable GUI origin', async () => {
+        await expect(showFeedbackEmbed({ guiOrigin: 'not a url', userUuid: USER })).resolves.toBeNull();
+        expect(document.querySelector('dialog')).toBeNull();
+    });
+});
+
+describe('showPopupFrame', () => {
+    const popupFrame = () => document.querySelector('dialog.puter-popup-frame iframe');
+    const fromPopup = (data, { origin = GUI_ORIGIN, source = popupFrame().contentWindow } = {}) =>
+        window.dispatchEvent(new MessageEvent('message', { data, origin, source }));
+    const show = (overrides = {}) => showPopupFrame({
+        guiOrigin: GUI_ORIGIN,
+        action: 'show-open-file-picker',
+        fragment: { msg_id: '3', user: USER },
+        title: 'Open file',
+        closed: () => 'closed',
+        onMessage: () => {},
+        ...overrides,
+    });
+
+    it('loads the popup action with its parameters in the fragment, hidden until ready', () => {
+        let framed;
+        show({ onFrame: (win) => {
+            framed = win;
+        } });
+        const url = new URL(popupFrame().src);
+        expect(url.origin + url.pathname).toBe(`${GUI_ORIGIN}/embed/show-open-file-picker`);
+        expect(url.search).toBe('');
+        expect(Object.fromEntries(new URLSearchParams(url.hash.slice(1)))).toEqual({ msg_id: '3', user: USER });
+        expect(popupFrame().getAttribute('referrerpolicy')).toBe('origin');
+        expect(popupFrame().closest('dialog').getAttribute('aria-label')).toBe('Open file');
+        expect(popupFrame().getAttribute('allow')).toBe('otp-credentials');
+        expect(framed).toBe(popupFrame().contentWindow);
+        expect(popupFrame().closest('dialog').open).toBe(false);
+    });
+
+    it('sizes the box like the popup window it replaces', () => {
+        show({ action: 'sign-in', fragment: { msg_id: 'a' } });
+        const box = document.querySelector('.puter-popup-frame-box');
+        expect(box.style.getPropertyValue('--puter-popup-frame-width')).toBe('600px');
+        expect(box.style.getPropertyValue('--puter-popup-frame-height')).toBe('700px');
+        expect(box.contains(popupFrame())).toBe(true);
+    });
+
+    it('shows once ready and hands every other message to the caller to finish with', async () => {
+        const seen = [];
+        const result = show({ onMessage: (data, finish) => {
+            seen.push(data.msg);
+            if ( data.msg === 'fileOpenPicked' ) finish('picked');
+        } });
+        const dialog = popupFrame().closest('dialog');
+        const status = dialog.querySelector('[role="status"]');
+        expect(status.getAttribute('aria-hidden')).toBe('true');
+        fromPopup({ msg: 'puterPopupFrame', state: 'loading' });
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        expect(dialog.open).toBe(true);
+        expect(status.getAttribute('aria-hidden')).toBe('true');
+        expect(document.activeElement).toBe(popupFrame());
+        fromPopup({ msg: 'puter.token', success: true });
+        fromPopup({ msg: 'fileOpenPicked' });
+        await expect(result).resolves.toBe('picked');
+        expect(seen).toEqual(['puter.token', 'fileOpenPicked']);
+        expect(dialog.isConnected).toBe(false);
+    });
+
+    it('opens itself again when the embed reloads into a refused frame, once per ready', async () => {
+        vi.useFakeTimers();
+        const result = show();
+        const iframe = popupFrame();
+        const dialog = iframe.closest('dialog');
+        const srcSet = vi.spyOn(iframe, 'src', 'set');
+        const load = () => iframe.dispatchEvent(new Event('load'));
+        fromPopup({ msg: 'puterPopupFrame', state: 'loading' });
+        load();
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+
+        // A reload the embed starts itself loads a document that never posts.
+        load();
+        expect(dialog.classList.contains('is-loading')).toBe(true);
+        vi.advanceTimersByTime(1000);
+        expect(srcSet).toHaveBeenCalledTimes(1);
+        // Not just the refused URL again, which WebKit takes as a fragment
+        // navigation of the error page: the server redirects the query away.
+        const opened = new URL(iframe.src);
+        const reopened = new URL(srcSet.mock.calls[0][0]);
+        expect(reopened.search).not.toBe('');
+        expect(reopened.origin + reopened.pathname + reopened.hash).toBe(opened.origin + opened.pathname + opened.hash);
+        expect(dialog.classList.contains('is-loading')).toBe(true);
+
+        // The page's own reload boots, before or after its load event.
+        fromPopup({ msg: 'puterPopupFrame', state: 'loading' });
+        load();
+        vi.advanceTimersByTime(1000);
+        expect(srcSet).toHaveBeenCalledTimes(1);
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        expect(dialog.classList.contains('is-loading')).toBe(false);
+
+        // Ready again, so a later refusal is retried too, but not twice running.
+        load();
+        vi.advanceTimersByTime(1000);
+        expect(srcSet).toHaveBeenCalledTimes(2);
+        load();
+        vi.advanceTimersByTime(1000);
+        await expect(result).resolves.toBeNull();
+        expect(srcSet).toHaveBeenCalledTimes(2);
+    });
+
+    it('falls back to the popup when the embed it opens again never loads', async () => {
+        vi.useFakeTimers();
+        const result = show();
+        const iframe = popupFrame();
+        const dialog = iframe.closest('dialog');
+        const load = () => iframe.dispatchEvent(new Event('load'));
+        fromPopup({ msg: 'puterPopupFrame', state: 'loading' });
+        load();
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+
+        // Refused after a reload of its own, then reopened on a stalled connection.
+        load();
+        vi.advanceTimersByTime(1000);
+        vi.advanceTimersByTime(14_999);
+        expect(dialog.isConnected).toBe(true);
+        vi.advanceTimersByTime(1);
+        await expect(result).resolves.toBeNull();
+        expect(dialog.isConnected).toBe(false);
+    });
+
+    it('keeps showing an embed that was ready before its load event fired', () => {
+        vi.useFakeTimers();
+        show();
+        const iframe = popupFrame();
+        const dialog = iframe.closest('dialog');
+        const srcSet = vi.spyOn(iframe, 'src', 'set');
+        const load = () => iframe.dispatchEvent(new Event('load'));
+        fromPopup({ msg: 'puterPopupFrame', state: 'loading' });
+        load();
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        load();
+        vi.advanceTimersByTime(1000);
+        expect(srcSet).toHaveBeenCalledTimes(1);
+
+        // The page's reload shows its UI while a slow image still loads.
+        fromPopup({ msg: 'puterPopupFrame', state: 'loading' });
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        load();
+        vi.advanceTimersByTime(5000);
+        expect(dialog.classList.contains('is-loading')).toBe(false);
+        expect(srcSet).toHaveBeenCalledTimes(1);
+        expect(dialog.isConnected).toBe(true);
+    });
+
+    it('closes on Escape outside the frame once ready, as Escape inside it does', async () => {
+        const result = show();
+        const dialog = popupFrame().closest('dialog');
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        const cancel = new Event('cancel', { cancelable: true });
+        dialog.dispatchEvent(cancel);
+        expect(cancel.defaultPrevented).toBe(true);
+        await expect(result).resolves.toBe('closed');
+        expect(dialog.isConnected).toBe(false);
+    });
+
+    it('finishes as closed when the popup closes itself', async () => {
+        const result = show();
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        fromPopup({ msg: 'puterPopupFrame', state: 'closed' });
+        await expect(result).resolves.toBe('closed');
+        expect(document.querySelector('dialog')).toBeNull();
+    });
+
+    it('offers a close button only when asked, which finishes as closed', async () => {
+        show();
+        expect(document.querySelector('.puter-popup-frame-close')).toBeNull();
+        document.body.innerHTML = '';
+
+        const result = show({ action: 'sign-in', closeLabel: 'Close' });
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        const close = document.querySelector('.puter-popup-frame-close');
+        expect(close.getAttribute('aria-label')).toBe('Close');
+        close.click();
+        await expect(result).resolves.toBe('closed');
+    });
+
+    it('resolves null for the popup when the frame is unavailable or refused', async () => {
+        const unavailable = show();
+        fromPopup({ msg: 'puterPopupFrame', state: 'loading' });
+        fromPopup({ msg: 'puterPopupFrame', state: 'unavailable' });
+        await expect(unavailable).resolves.toBeNull();
+
+        vi.useFakeTimers();
+        const refused = show();
+        popupFrame().dispatchEvent(new Event('load'));
+        await vi.advanceTimersByTimeAsync(1000);
+        await expect(refused).resolves.toBeNull();
+    });
+
+    it('lets the user dismiss the loading scrim, finishing as closed', async () => {
+        vi.useFakeTimers();
+        const result = show();
+        await vi.advanceTimersByTimeAsync(200);
+        document.querySelector('.puter-popup-frame-loading').click();
+        await expect(result).resolves.toBe('closed');
+    });
+
+    it('replaces a popup frame that is showing, finishing it as closed', async () => {
+        const button = document.createElement('button');
+        document.body.append(button);
+        button.focus();
+        const first = show();
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        const firstDialog = popupFrame().closest('dialog');
+        const second = show({ fragment: { msg_id: '4', user: USER } });
+        await expect(first).resolves.toBe('closed');
+        expect(firstDialog.isConnected).toBe(false);
+        expect(document.querySelectorAll('dialog.puter-popup-frame')).toHaveLength(1);
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        fromPopup({ msg: 'puterPopupFrame', state: 'closed' });
+        await expect(second).resolves.toBe('closed');
+        expect(document.activeElement).toBe(button);
+    });
+
+    it('leaves a popup frame for another action showing, as its popup window would stay open', async () => {
+        const picker = show();
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        const pickerFrame = popupFrame();
+        const signIn = show({ action: 'sign-in', fragment: { msg_id: 'a' } });
+        expect(document.querySelectorAll('dialog.puter-popup-frame')).toHaveLength(2);
+        const signInFrame = document.querySelectorAll('dialog.puter-popup-frame iframe')[1];
+        fromPopup({ msg: 'puterPopupFrame', state: 'closed' }, { source: signInFrame.contentWindow });
+        await expect(signIn).resolves.toBe('closed');
+        expect(pickerFrame.isConnected).toBe(true);
+        fromPopup({ msg: 'puterPopupFrame', state: 'closed' }, { source: pickerFrame.contentWindow });
+        await expect(picker).resolves.toBe('closed');
+    });
+
+    it('keeps the scrim behind a ready frame from dismissing it', () => {
+        show();
+        fromPopup({ msg: 'puterPopupFrame', state: 'ready' });
+        document.querySelector('.puter-popup-frame-loading').click();
+        expect(popupFrame().closest('dialog').isConnected).toBe(true);
+    });
+
+    it('ignores messages from another origin or another window', async () => {
+        const onMessage = vi.fn();
+        show({ onMessage });
+        fromPopup({ msg: 'puterPopupFrame', state: 'closed' }, { origin: 'https://other.test' });
+        fromPopup({ msg: 'fileOpenPicked' }, { source: window });
+        expect(onMessage).not.toHaveBeenCalled();
+        expect(popupFrame().closest('dialog').isConnected).toBe(true);
+    });
+});

src/puter-js/src/modules/Auth.js

@@ -3,6 +3,7 @@ import { fetchUrl } from '../lib/networkUtils.js';
 import { PuterModule } from '../lib/PuterModule.js';
 import PuterDialog from './PuterDialog.js';
 import { hasOpaqueOrigin } from '../lib/auth-popup.js';
+import { ancestorsAllowGuiEmbed, canFrameGuiEmbed, showPopupFrame } from '../lib/guiEmbed.js';
 
 /**
  * Puter user details, as returned by `getUser()`.
@@ -115,12 +116,19 @@ export class AuthModule extends PuterModule {
     /** @internal */
     pendingSignInMessageIds_ = new Set();
 
+    /** The framed sign-in in progress, which a repeated call joins. */
+    #framedSignIn = null;
+
     /**
      * Signs the user in, opening a popup with the appropriate authentication
      * method. Must be called from a user gesture (such as a click) — without
      * one, a consent dialog is shown first so the popup can be opened from the
      * user's click on it. Resolves once the user has signed in.
      *
+     * On a page one label under the Puter origin, the sign-in shows in a frame
+     * over the page instead, and continues in the popup when the user picks a
+     * federated provider or the frame can't be shown.
+     *
      * Rejects with `{ error: 'popup_blocked' }` if the browser blocked the
      * popup, `{ error: 'auth_window_closed' }` if the user closed it, `{ error:
      * 'not_available_in_app' }` when called from an app — an app's token comes
@@ -168,12 +176,128 @@ export class AuthModule extends PuterModule {
                     : this.signIn(options));
         }
 
+        if (this.#canSignInInFrame(options)) {
+            // A second call, such as from a double click or a `puter.*` call
+            // asking for implicit auth, waits on the first rather than
+            // replacing its frame, which would reject the first.
+            if (this.#framedSignIn) return this.#framedSignIn;
+            const promise = this.#signInInFrame(options).then((result) =>
+                result ?? this.#signInWithPopup(options));
+            const done = () => {
+                if (this.#framedSignIn === promise) this.#framedSignIn = null;
+            };
+            this.#framedSignIn = promise;
+            promise.then(done, done);
+            return promise;
+        }
+        return this.#signInWithPopup(options);
+    };
+
+    /**
+     * Whether this page can show the sign-in framed: a first-party page one
+     * label under the GUI origin, not in a frame of another site. Only the
+     * popup creates a temporary account, so a sign-in that asks for one keeps
+     * it.
+     */
+    #canSignInInFrame (options) {
+        return !options.attempt_temp_user_creation &&
+            !globalThis.crossOriginIsolated &&
+            !!globalThis.document?.body &&
+            canFrameGuiEmbed(globalThis.location?.href, puter.defaultGUIOrigin) &&
+            ancestorsAllowGuiEmbed(globalThis, puter.defaultGUIOrigin);
+    }
+
+    /** Runs `puter.onAuth`, if set, with the user just signed in. */
+    #notifyAuth () {
+        if (typeof puter.onAuth !== 'function') return;
+        void (async () => {
+            try {
+                const user = await puter.whoamiCache_;
+                puter.onAuth(user ?? (await puter.getUser()));
+            } catch (error) {
+                console.error(error);
+            }
+        })();
+    }
+
+    /**
+     * The sign-in in a frame over the page. Settles as the popup would, or
+     * resolves null when the popup has to take over.
+     *
+     * @returns {Promise<SignInResult | null>}
+     */
+    async #signInInFrame (options) {
+        const msg_id = crypto.randomUUID();
+        this.pendingSignInMessageIds_.add(msg_id);
+        const fragment = { msg_id };
+        if (options.request_auth) fragment.request_auth = 'true';
+        let outcome;
+        try {
+            outcome = await showPopupFrame({
+                guiOrigin: puter.defaultGUIOrigin,
+                action: 'sign-in',
+                fragment,
+                title: 'Sign in to Puter',
+                closeLabel: 'Close',
+                closed: () => ({ closed: true }),
+                onMessage: (data, finish) => {
+                    if (data.msg === 'puterPopupFrame' && data.state === 'provider') {
+                        if (this.#isProviderStart(data.url, msg_id)) finish({ providerUrl: data.url });
+                        return;
+                    }
+                    if (data.msg !== 'puter.token' || data.msg_id != msg_id) return;
+                    finish({ reply: data });
+                },
+            });
+        } finally {
+            this.pendingSignInMessageIds_.delete(msg_id);
+        }
+        if (!outcome) return null;
+        // A provider won't load in a frame, so its sign-in continues in the
+        // popup, which the provider returns as this attempt's sign-in popup.
+        if (outcome.providerUrl) {
+            return this.#signInWithPopup(options, { url: outcome.providerUrl, msgId: msg_id });
+        }
+        if (outcome.closed) {
+            throw {
+                error: 'auth_window_closed',
+                msg: 'Authentication window was closed by the user without completing the process.',
+            };
+        }
+        const { msg: _msg, msg_id: _msgId, ...result } = outcome.reply;
+        if (!result.success) throw result;
+        puter.setAuthToken(result.token);
+        this.#notifyAuth();
+        return result;
+    }
+
+    /**
+     * Whether `url` is the GUI's start of a provider sign-in that returns as
+     * the popup for sign-in `msgId`.
+     */
+    #isProviderStart (url, msgId) {
+        try {
+            const start = new URL(url);
+            return start.origin === new URL(puter.defaultGUIOrigin).origin &&
+                /^\/auth\/oidc\/[^/]+\/start$/.test(start.pathname) &&
+                start.searchParams.get('embedded_in_popup') === 'true' &&
+                start.searchParams.get('msg_id') === msgId;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * The sign-in in a popup window, opened at `start.url` for sign-in
+     * `start.msgId` when a framed sign-in hands one over.
+     */
+    #signInWithPopup (options, start = {}) {
         return new Promise((resolve, reject) => {
             const signinsession = crypto.randomUUID();
-            const msg_id = signinsession;
+            const msg_id = start.msgId ?? signinsession;
             this.pendingSignInMessageIds_.add(msg_id);
             const popupName = `Puter-sign-in-${signinsession}`;
-            const url = `${puter.defaultGUIOrigin}/action/sign-in?embedded_in_popup=true&msg_id=${msg_id}${window.crossOriginIsolated ? `&cross_origin_isolated=true&signin_session=${signinsession}` : ''}${options.attempt_temp_user_creation ? '&attempt_temp_user_creation=true' : ''}${options.request_auth ? '&request_auth=true' : ''}`;
+            const url = start.url ?? `${puter.defaultGUIOrigin}/action/sign-in?embedded_in_popup=true&msg_id=${msg_id}${window.crossOriginIsolated ? `&cross_origin_isolated=true&signin_session=${signinsession}` : ''}${options.attempt_temp_user_creation ? '&attempt_temp_user_creation=true' : ''}${options.request_auth ? '&request_auth=true' : ''}`;
 
             // Guards against settling the promise more than once across the
             // message, popup-closed, and dialog-cancel code paths.
@@ -196,17 +320,7 @@ export class AuthModule extends PuterModule {
                 consentDialog = null;
             };
 
-            const notifyAuth = () => {
-                if (typeof puter.onAuth !== 'function') return;
-                void (async () => {
-                    try {
-                        const user = await puter.whoamiCache_;
-                        puter.onAuth(user ?? (await puter.getUser()));
-                    } catch (error) {
-                        console.error(error);
-                    }
-                })();
-            };
+            const notifyAuth = () => this.#notifyAuth();
 
             if (window.crossOriginIsolated) {
                 (async () => {
@@ -366,7 +480,7 @@ export class AuthModule extends PuterModule {
                 rejectBlocked();
             }
         });
-    };
+    }
 
     /**
      * Whether the user is currently signed in.

src/puter-js/src/modules/Auth.signInFrame.test.js

@@ -0,0 +1,235 @@
+// @vitest-environment jsdom
+// @vitest-environment-options {"url": "https://notes.puter.test/doc"}
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AuthModule } from './Auth.js';
+
+// An isolated page polls the sign-in relay; nothing here answers it.
+vi.mock('../lib/networkUtils.js', () => ({ fetchUrl: vi.fn(() => new Promise(() => {})) }));
+
+const GUI_ORIGIN = 'https://puter.test';
+
+// jsdom has no top-layer dialogs.
+HTMLDialogElement.prototype.showModal = function () {
+    this.open = true;
+};
+HTMLDialogElement.prototype.close = function () {
+    this.open = false;
+};
+
+const signInFrame = () => document.querySelector('dialog.puter-popup-frame iframe');
+
+/** The framed sign-in's `msg_id`, from its fragment. */
+const frameMsgId = () => new URLSearchParams(new URL(signInFrame().src).hash.slice(1)).get('msg_id');
+
+const fromFrame = (data, source = signInFrame().contentWindow) =>
+    window.dispatchEvent(new MessageEvent('message', { data, origin: GUI_ORIGIN, source }));
+
+let auth;
+
+beforeEach(() => {
+    document.body.innerHTML = '';
+    vi.stubGlobal('puter', {
+        env: 'web',
+        defaultGUIOrigin: GUI_ORIGIN,
+        setAuthToken: vi.fn(),
+        trackOpenedWindow_: vi.fn(),
+    });
+    vi.spyOn(window, 'open').mockImplementation((url, name) => ({ name, url, closed: false }));
+    Object.defineProperty(navigator, 'userActivation', {
+        configurable: true,
+        value: { hasBeenActive: true, isActive: true },
+    });
+    auth = new AuthModule(puter);
+});
+
+afterEach(() => {
+    delete navigator.userActivation;
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+});
+
+describe('auth.signIn on a first-party page', () => {
+    it('signs in through the frame instead of a popup', async () => {
+        const result = auth.signIn();
+        const url = new URL(signInFrame().src);
+        expect(url.origin + url.pathname).toBe(`${GUI_ORIGIN}/embed/sign-in`);
+        expect(url.search).toBe('');
+        expect(auth.pendingSignInMessageIds_.has(frameMsgId())).toBe(true);
+
+        fromFrame({ msg: 'puterPopupFrame', state: 'ready' });
+        fromFrame({ msg: 'puter.token', msg_id: frameMsgId(), success: true, token: 'tok', app_uid: 'app-1', username: 'alice' });
+
+        await expect(result).resolves.toEqual({ success: true, token: 'tok', app_uid: 'app-1', username: 'alice' });
+        expect(puter.setAuthToken).toHaveBeenCalledWith('tok');
+        expect(window.open).not.toHaveBeenCalled();
+        expect(signInFrame()).toBeNull();
+        expect(auth.pendingSignInMessageIds_.size).toBe(0);
+    });
+
+    it('passes request_auth on to the frame', () => {
+        auth.signIn({ request_auth: true }).catch(() => {});
+        expect(new URLSearchParams(new URL(signInFrame().src).hash.slice(1)).get('request_auth')).toBe('true');
+    });
+
+    it('ignores a token for another sign-in or from another window', async () => {
+        const result = auth.signIn();
+        let settled = false;
+        result.then(() => {
+            settled = true;
+        }, () => {
+            settled = true;
+        });
+        fromFrame({ msg: 'puter.token', msg_id: 'other', success: true, token: 'x' });
+        fromFrame({ msg: 'puter.token', msg_id: frameMsgId(), success: true, token: 'x' }, window);
+        await Promise.resolve();
+        expect(settled).toBe(false);
+        expect(puter.setAuthToken).not.toHaveBeenCalled();
+    });
+
+    it('rejects as a closed popup when the user closes the frame', async () => {
+        const result = auth.signIn();
+        fromFrame({ msg: 'puterPopupFrame', state: 'ready' });
+        document.querySelector('.puter-popup-frame-close').click();
+        await expect(result).rejects.toMatchObject({ error: 'auth_window_closed' });
+        expect(window.open).not.toHaveBeenCalled();
+    });
+
+    it('rejects as a closed popup when the frame closes without a token', async () => {
+        const result = auth.signIn();
+        fromFrame({ msg: 'puterPopupFrame', state: 'closed' });
+        await expect(result).rejects.toMatchObject({ error: 'auth_window_closed' });
+    });
+
+    it('shares one framed sign-in between calls made while it is open', async () => {
+        const first = auth.signIn();
+        const second = auth.signIn();
+        expect(document.querySelectorAll('dialog.puter-popup-frame')).toHaveLength(1);
+        fromFrame({ msg: 'puterPopupFrame', state: 'ready' });
+        fromFrame({ msg: 'puter.token', msg_id: frameMsgId(), success: true, token: 'tok' });
+        await expect(first).resolves.toEqual({ success: true, token: 'tok' });
+        await expect(second).resolves.toEqual({ success: true, token: 'tok' });
+
+        // Once it settles, the next call starts a new one.
+        const third = auth.signIn();
+        expect(signInFrame()).not.toBeNull();
+        fromFrame({ msg: 'puterPopupFrame', state: 'closed' });
+        await expect(third).rejects.toMatchObject({ error: 'auth_window_closed' });
+    });
+
+    it('shares the framed sign-in with a call that differs in request_auth', async () => {
+        // Implicit auth (a `puter.*` call without a token) asks with request_auth.
+        const implicit = auth.signIn({ request_auth: true });
+        const explicit = auth.signIn();
+        expect(document.querySelectorAll('dialog.puter-popup-frame')).toHaveLength(1);
+        fromFrame({ msg: 'puterPopupFrame', state: 'ready' });
+        fromFrame({ msg: 'puter.token', msg_id: frameMsgId(), success: true, token: 'tok' });
+        await expect(implicit).resolves.toEqual({ success: true, token: 'tok' });
+        await expect(explicit).resolves.toEqual({ success: true, token: 'tok' });
+    });
+
+    it('rejects with the reply a failed sign-in sends, as the popup does', async () => {
+        const result = auth.signIn();
+        fromFrame({ msg: 'puter.token', msg_id: frameMsgId(), success: false, token: null });
+        await expect(result).rejects.toEqual({ success: false, token: null });
+        expect(puter.setAuthToken).not.toHaveBeenCalled();
+    });
+
+    it('continues in the popup when the frame hands off, such as for a federated provider', async () => {
+        const result = auth.signIn();
+        fromFrame({ msg: 'puterPopupFrame', state: 'loading' });
+        fromFrame({ msg: 'puterPopupFrame', state: 'unavailable' });
+        await vi.waitFor(() => expect(window.open).toHaveBeenCalledTimes(1));
+        const [url] = window.open.mock.calls[0];
+        expect(url).toContain(`${GUI_ORIGIN}/action/sign-in?embedded_in_popup=true`);
+        expect(signInFrame()).toBeNull();
+
+        const popup = window.open.mock.results[0].value;
+        const msgId = new URL(url).searchParams.get('msg_id');
+        window.dispatchEvent(new MessageEvent('message', {
+            data: { msg: 'puter.token', msg_id: msgId, success: true, token: 'tok' },
+            origin: GUI_ORIGIN,
+            source: popup,
+        }));
+        await expect(result).resolves.toMatchObject({ success: true, token: 'tok' });
+    });
+
+    it('opens the provider the user picked in the frame straight in the popup', async () => {
+        const result = auth.signIn();
+        const msgId = frameMsgId();
+        const start = `${GUI_ORIGIN}/auth/oidc/google/start?flow=login&referrer=x&embedded_in_popup=true&msg_id=${msgId}&opener_origin=https%3A%2F%2Fnotes.puter.test`;
+        const frameWindow = signInFrame().contentWindow;
+        fromFrame({ msg: 'puterPopupFrame', state: 'ready' });
+        fromFrame({ msg: 'puterPopupFrame', state: 'provider', url: start });
+        fromFrame({ msg: 'puterPopupFrame', state: 'unavailable' }, frameWindow);
+        await vi.waitFor(() => expect(window.open).toHaveBeenCalledTimes(1));
+        expect(window.open.mock.calls[0][0]).toBe(start);
+        expect(signInFrame()).toBeNull();
+        expect(auth.pendingSignInMessageIds_.has(msgId)).toBe(true);
+
+        // The provider returns the popup as a sign-in popup for the same attempt.
+        window.dispatchEvent(new MessageEvent('message', {
+            data: { msg: 'puter.token', msg_id: msgId, success: true, token: 'tok' },
+            origin: GUI_ORIGIN,
+            source: window.open.mock.results[0].value,
+        }));
+        await expect(result).resolves.toMatchObject({ success: true, token: 'tok' });
+        expect(puter.setAuthToken).toHaveBeenCalledWith('tok');
+        expect(auth.pendingSignInMessageIds_.size).toBe(0);
+    });
+
+    it.each([
+        ['another origin', (id) => `https://evil.test/auth/oidc/google/start?embedded_in_popup=true&msg_id=${id}`],
+        ['another path', (id) => `${GUI_ORIGIN}/action/sign-in?embedded_in_popup=true&msg_id=${id}&auth_token=x`],
+        ['another sign-in', () => `${GUI_ORIGIN}/auth/oidc/google/start?embedded_in_popup=true&msg_id=other`],
+        ['no popup return', (id) => `${GUI_ORIGIN}/auth/oidc/google/start?msg_id=${id}`],
+        ['no URL', () => undefined],
+    ])('opens the sign-in popup instead of a provider URL to %s', async (_, url) => {
+        auth.signIn();
+        fromFrame({ msg: 'puterPopupFrame', state: 'provider', url: url(frameMsgId()) });
+        fromFrame({ msg: 'puterPopupFrame', state: 'unavailable' });
+        await vi.waitFor(() => expect(window.open).toHaveBeenCalledTimes(1));
+        expect(window.open.mock.calls[0][0]).toContain(`${GUI_ORIGIN}/action/sign-in?embedded_in_popup=true`);
+    });
+
+    it('continues in the popup when the frame is refused', async () => {
+        vi.useFakeTimers();
+        auth.signIn();
+        signInFrame().dispatchEvent(new Event('load'));
+        await vi.advanceTimersByTimeAsync(1000);
+        expect(window.open).toHaveBeenCalledTimes(1);
+        expect(signInFrame()).toBeNull();
+    });
+
+    it('keeps the popup for a temporary account', () => {
+        auth.signIn({ attempt_temp_user_creation: true });
+        expect(signInFrame()).toBeNull();
+        expect(window.open).toHaveBeenCalledTimes(1);
+        expect(window.open.mock.calls[0][0]).toContain('attempt_temp_user_creation=true');
+    });
+
+    it('keeps the popup for a page outside the Puter origin', () => {
+        puter.defaultGUIOrigin = 'https://puter.com';
+        auth.signIn();
+        expect(signInFrame()).toBeNull();
+        expect(window.open).toHaveBeenCalledTimes(1);
+    });
+
+    it('keeps the popup for a page in a frame of another site', () => {
+        Object.defineProperty(window.location, 'ancestorOrigins', { configurable: true, value: ['https://other.test'] });
+        try {
+            auth.signIn();
+            expect(signInFrame()).toBeNull();
+            expect(window.open).toHaveBeenCalledTimes(1);
+        } finally {
+            delete window.location.ancestorOrigins;
+        }
+    });
+
+    it('keeps the popup for a cross-origin isolated page', () => {
+        vi.stubGlobal('crossOriginIsolated', true);
+        auth.signIn().catch(() => {});
+        expect(signInFrame()).toBeNull();
+        expect(window.open).toHaveBeenCalledTimes(1);
+    });
+});

src/puter-js/src/modules/UI.js

@@ -2,6 +2,8 @@ import EventListener from '../lib/EventListener.js';
 import { PuterJSError } from '../lib/PuterJSError.js';
 import FSItem from './FSItem.js';
 import PuterDialog from './PuterDialog.js';
+import { ancestorsAllowGuiEmbed, canFrameGuiEmbed, showFeedbackEmbed, showPopupFrame } from '../lib/guiEmbed.js';
+import { hasUserActivation } from '../lib/auth-popup.js';
 import { checkPermissions } from './perms/lib/holds.js';
 
 
@@ -528,6 +530,9 @@ export class UIModule extends EventListener {
     #guiFeatures = new URLSearchParams(globalThis.location?.search ?? '')
         .get('puter.gui_features')?.split(',') ?? [];
 
+    // Set while the framed feedback dialog is open on a first-party page.
+    #feedbackEmbedOpen = false;
+
     // Holds the callback functions for the various events
     // that are triggered when a watched item has changed.
     itemWatchCallbackFunctions = [];
@@ -578,6 +583,131 @@ export class UIModule extends EventListener {
         if ( popup ) this.#pickerPopups.add(popup);
     }
 
+    /** What a picker's consent dialog says, when the popup needs a click to open. */
+    static #PICKER_CONSENT = {
+        'show-open-file-picker': 'This website wants you to choose a file from your Puter account.',
+        'show-save-file-picker': 'This website wants to save a file to your Puter account.',
+        'show-directory-picker': 'This website wants you to choose a folder from your Puter account.',
+    };
+
+    /** Opens a picker's popup window, centered, at the pickers' size. */
+    #openPickerPopup (url, title) {
+        const w = 700;
+        const h = 400;
+        const left = (screen.width / 2) - (w / 2);
+        const top = (screen.height / 2) - (h / 2);
+        return window.open(
+            url,
+            title,
+            `toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=no, copyhistory=no, width=${w}, height=${h}, top=${top}, left=${left}`,
+        );
+    }
+
+    /**
+     * Shows a picker on a `web` page. A first-party page one label under the
+     * Puter origin that is signed in gets it in a frame over the page; every
+     * other page, or a frame that can't serve this user, gets the popup.
+     * `onWindow` sees the window that will ask for and answer the picker, with
+     * `framed` set for a frame, and may return a function that stops listening
+     * to it.
+     *
+     * @param {Object} opts
+     * @param {'show-open-file-picker' | 'show-save-file-picker' | 'show-directory-picker'} opts.action
+     * @param {number} opts.msgId
+     * @param {string} opts.url - the popup's URL
+     * @param {string} opts.title - the popup's window name, and the frame's accessible name
+     * @param {Record<string, string>} [opts.fragment] - the popup parameters the frame needs besides `msg_id`
+     * @param {(win: Window | null, how?: { framed: boolean }) => (() => void) | void} [opts.onWindow]
+     */
+    #showWebPicker ({ action, msgId, url, title, fragment = {}, onWindow }) {
+        if ( ! this.#canFramePicker() ) {
+            // window.open() returns synchronously and the popup cannot post
+            // back until this function yields, so there is no race.
+            const popup = this.#openPickerPopup(url, title);
+            onWindow?.(popup);
+            this.#trackPickerPopup(popup);
+            return;
+        }
+        void (async () => {
+            if ( await this.#showPickerFrame({ action, msgId, title, fragment, onWindow }) ) return;
+            // The click that asked for the picker may have expired by now, so
+            // without it the user opens the popup from a consent dialog.
+            const launched = (popup) => {
+                onWindow?.(popup);
+                this.#trackPickerPopup(popup);
+            };
+            if ( hasUserActivation() ) {
+                const popup = this.#openPickerPopup(url, title);
+                if ( popup ) {
+                    launched(popup);
+                    return;
+                }
+            }
+            let consent = null;
+            try {
+                consent = PuterDialog.show({
+                    message: UIModule.#PICKER_CONSENT[action],
+                    onContinue: () => {
+                        launched(this.#openPickerPopup(url, title));
+                        consent?.remove();
+                    },
+                    onCancel: () => {
+                        consent?.remove();
+                        this.#settleCallback(msgId, PICKER_CANCELLED);
+                    },
+                });
+            } catch {
+                // No dialog either; as with a blocked popup, the picker never opens.
+            }
+        })();
+    }
+
+    /** Whether a picker can show framed: a signed-in first-party page, not in a frame of another site. */
+    #canFramePicker () {
+        return this.env === 'web' &&
+            !globalThis.crossOriginIsolated &&
+            !!globalThis.document?.body &&
+            canFrameGuiEmbed(globalThis.location?.href, puter.defaultGUIOrigin) &&
+            ancestorsAllowGuiEmbed(globalThis, puter.defaultGUIOrigin) &&
+            !!puter.auth?.isSignedIn?.();
+    }
+
+    /**
+     * The picker in a frame over the page, for the page's signed-in user. The
+     * GUI answers it as it would the popup, through the module's message
+     * handler. Resolves false when the popup has to take over.
+     *
+     * @returns {Promise<boolean>}
+     */
+    async #showPickerFrame ({ action, msgId, title, fragment, onWindow }) {
+        const known = await Promise.resolve(puter.whoami ?? puter.whoamiCache_).catch(() => null);
+        const user = known?.uuid ? known : await puter.auth.getUser().catch(() => null);
+        if ( typeof user?.uuid !== 'string' || ! user.uuid ) return false;
+        let frame = null;
+        let stopListening;
+        // The frame only serves this page's own user, so the token it sends
+        // with the answer isn't adopted; the page keeps the one it has.
+        const closed = await showPopupFrame({
+            guiOrigin: puter.defaultGUIOrigin,
+            action,
+            fragment: { ...fragment, msg_id: String(msgId), user: user.uuid },
+            title,
+            closed: () => true,
+            onMessage: () => {},
+            onFrame: (win) => {
+                frame = win;
+                this.#pickerPopups.add(win);
+                stopListening = onWindow?.(win, { framed: true });
+            },
+        });
+        this.#pickerPopups.delete(frame);
+        stopListening?.();
+        if ( ! closed ) return false;
+        // Gone without an answer: dismissed, so it settles as a cancel.
+        this.#settleCallback(msgId, PICKER_CANCELLED);
+        return true;
+    }
+
     // Whether a message on the window may drive this module.
     #isTrustedMessageSource (e) {
         if ( this.messageTarget ) {
@@ -1378,20 +1508,12 @@ export class UIModule extends EventListener {
                     env: this.env,
                 }, '*');
             } else {
-                let w = 700;
-                let h = 400;
-                let title = 'Puter: Open Directory';
-                var left = (screen.width / 2) - (w / 2);
-                var top = (screen.height / 2) - (h / 2);
-                // Track the window we opened so the message listener accepts
-                // its reply. window.open() returns synchronously and the popup
-                // cannot post back until this function yields, so there is no
-                // race.
-                this.#trackPickerPopup(window.open(
-                    `${puter.defaultGUIOrigin}/action/show-directory-picker?embedded_in_popup=true&msg_id=${msg_id}&appInstanceID=${this.appInstanceID}&env=${this.env}&options=${JSON.stringify(options)}`,
-                    title,
-                    `toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=no, copyhistory=no, width=${w}, height=${h}, top=${top}, left=${left}`,
-                ));
+                this.#showWebPicker({
+                    action: 'show-directory-picker',
+                    msgId: msg_id,
+                    url: `${puter.defaultGUIOrigin}/action/show-directory-picker?embedded_in_popup=true&msg_id=${msg_id}&appInstanceID=${this.appInstanceID}&env=${this.env}&options=${JSON.stringify(options)}`,
+                    title: 'Puter: Open Directory',
+                });
             }
 
             this.#registerPickerCallback(msg_id, resolve, undefinedOnCancel);
@@ -1428,16 +1550,13 @@ export class UIModule extends EventListener {
                     env: this.env,
                 }, '*');
             } else {
-                let w = 700;
-                let h = 400;
-                let title = 'Puter: Open File';
-                var left = (screen.width / 2) - (w / 2);
-                var top = (screen.height / 2) - (h / 2);
-                this.#trackPickerPopup(window.open(
-                    `${puter.defaultGUIOrigin}/action/show-open-file-picker?embedded_in_popup=true&msg_id=${msg_id}&appInstanceID=${this.appInstanceID}&env=${this.env}&options=${JSON.stringify(options ?? {})}`,
-                    title,
-                    `toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=no, copyhistory=no, width=${w}, height=${h}, top=${top}, left=${left}`,
-                ));
+                this.#showWebPicker({
+                    action: 'show-open-file-picker',
+                    msgId: msg_id,
+                    url: `${puter.defaultGUIOrigin}/action/show-open-file-picker?embedded_in_popup=true&msg_id=${msg_id}&appInstanceID=${this.appInstanceID}&env=${this.env}&options=${JSON.stringify(options ?? {})}`,
+                    title: 'Puter: Open File',
+                    fragment: { options: JSON.stringify(options ?? {}) },
+                });
             }
             this.#registerPickerCallback(msg_id, resolve, undefinedOnCancel);
         });
@@ -1635,47 +1754,43 @@ export class UIModule extends EventListener {
                 // Create an object URL for the Blob
                 let objectUrl = URL.createObjectURL(blob);
 
-                let w = 700;
-                let h = 400;
-                let title = 'Puter: Save File';
-                var left = (screen.width / 2) - (w / 2);
-                var top = (screen.height / 2) - (h / 2);
-
-                // Open the picker popup first so we can bind the data handler to the
-                // exact window we opened. window.open() returns synchronously and the
-                // popup cannot post back until this function yields, so there is no race.
-                const popup = window.open(
-                    `${puter.defaultGUIOrigin}/action/show-save-file-picker?embedded_in_popup=true&msg_id=${msg_id}&appInstanceID=${this.appInstanceID}&env=${this.env}&blobUrl=${encodeURIComponent(objectUrl)}`,
-                    title,
-                    `toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=no, copyhistory=no, width=${w}, height=${h}, top=${top}, left=${left}`,
-                );
-
-                // Only hand the file content to the trusted Puter GUI popup we just
-                // opened. Without this, any framing parent or sibling iframe could post
+                // Only hand the file content to the Puter GUI window that shows
+                // the picker (its popup, or its frame on a first-party page).
+                // Without this, any framing parent or sibling iframe could post
                 // { msg: 'sendMeFileData' } and receive the content the page meant to save.
-                const onSendMeFileData = (e) => {
-                    if ( e.data?.msg !== 'sendMeFileData' ) return;
-                    // Reject anything that isn't our popup on the trusted GUI origin.
-                    if ( e.origin !== puter.defaultGUIOrigin ) return;
-                    if ( ! popup || e.source !== popup ) return;
+                // A frame that reloads asks again, so it's answered until it
+                // closes; a popup is answered once.
+                const sendFileDataTo = (picker, { framed = false } = {}) => {
+                    const onSendMeFileData = (e) => {
+                        if ( e.data?.msg !== 'sendMeFileData' ) return;
+                        // Reject anything that isn't our picker on the trusted GUI origin.
+                        if ( e.origin !== puter.defaultGUIOrigin ) return;
+                        if ( ! picker || e.source !== picker ) return;
 
-                    // Send the file data to the popup, targeting the trusted origin only.
-                    e.source.postMessage({
-                        msg: 'showSaveFilePickerPopup',
-                        content: url ? undefined : content,
-                        url: url ? url.toString() : undefined,
-                        suggestedName: suggestedName ?? '',
-                        env: this.env,
-                        uuid: msg_id,
-                    }, puter.defaultGUIOrigin);
+                        // Send the file data to the picker, targeting the trusted origin only.
+                        e.source.postMessage({
+                            msg: 'showSaveFilePickerPopup',
+                            content: url ? undefined : content,
+                            url: url ? url.toString() : undefined,
+                            suggestedName: suggestedName ?? '',
+                            env: this.env,
+                            uuid: msg_id,
+                        }, puter.defaultGUIOrigin);
 
-                    // The trusted popup has the data; remove this exact listener.
-                    window.removeEventListener('message', onSendMeFileData);
+                        // A popup has the data now; remove this exact listener.
+                        if ( ! framed ) window.removeEventListener('message', onSendMeFileData);
+                    };
+                    window.addEventListener('message', onSendMeFileData);
+                    return () => window.removeEventListener('message', onSendMeFileData);
                 };
-                window.addEventListener('message', onSendMeFileData);
 
-                // Same window, for the picker's own reply on the main listener.
-                this.#trackPickerPopup(popup);
+                this.#showWebPicker({
+                    action: 'show-save-file-picker',
+                    msgId: msg_id,
+                    url: `${puter.defaultGUIOrigin}/action/show-save-file-picker?embedded_in_popup=true&msg_id=${msg_id}&appInstanceID=${this.appInstanceID}&env=${this.env}&blobUrl=${encodeURIComponent(objectUrl)}`,
+                    title: 'Puter: Save File',
+                    onWindow: sendFileDataTo,
+                });
             }
             this.#registerPickerCallback(msg_id, resolve, undefinedOnCancel);
         });
@@ -2249,9 +2364,12 @@ export class UIModule extends EventListener {
      * have opted in by setting `feedbackEnabled` on the app — otherwise the
      * dialog tells the user feedback is unavailable.
      *
-     * In the `app` environment the Puter desktop renders the dialog; in the
-     * `web` environment a puter.com popup hosts it (signing the user in first
-     * if needed). Every other environment resolves `false`.
+     * In the `app` environment the Puter desktop renders the dialog. In the
+     * `web` environment a first-party page one label under the Puter origin
+     * shows it in a frame over the page when the user's Puter session is the
+     * one the page is signed in as; otherwise a puter.com popup hosts it
+     * (signing the user in first if needed). Every other environment
+     * resolves `false`.
      *
      * @returns {Promise<boolean>} `true` when the user submitted feedback,
      *   `false` when the dialog was dismissed or feedback is unavailable.
@@ -2276,6 +2394,10 @@ export class UIModule extends EventListener {
         if ( this.env !== 'web' ) {
             return false;
         }
+        const embedded = await this.#showFeedbackEmbed();
+        if ( embedded ) {
+            return embedded.sent;
+        }
         // The app's identity is deliberately NOT in the popup URL: the GUI
         // derives it from the browser-attested opener origin, so a link
         // can't open a feedback dialog in another app's name.
@@ -2287,6 +2409,29 @@ export class UIModule extends EventListener {
         return result?.sent === true;
     };
 
+    /**
+     * The framed feedback dialog for a first-party page that is signed in, or
+     * null when the popup has to host it. One at a time: a call while one is
+     * open resolves `{ sent: false }`, as the desktop does.
+     *
+     * @returns {Promise<{ sent: boolean } | null>}
+     */
+    async #showFeedbackEmbed () {
+        if ( ! globalThis.document?.body ) return null;
+        if ( ! canFrameGuiEmbed(globalThis.location?.href, puter.defaultGUIOrigin) ) return null;
+        if ( ! puter.auth?.isSignedIn?.() ) return null;
+        if ( this.#feedbackEmbedOpen ) return { sent: false };
+        this.#feedbackEmbedOpen = true;
+        try {
+            const known = await Promise.resolve(puter.whoami ?? puter.whoamiCache_).catch(() => null);
+            const user = known?.uuid ? known : await puter.auth.getUser().catch(() => null);
+            if ( typeof user?.uuid !== 'string' || ! user.uuid ) return null;
+            return await showFeedbackEmbed({ guiOrigin: puter.defaultGUIOrigin, userUuid: user.uuid });
+        } finally {
+            this.#feedbackEmbedOpen = false;
+        }
+    }
+
     /**
      * Opens `/action/<action>` on the GUI origin in a popup and waits for
      * its single result message. Resolves the message's data, or `null` when

src/puter-js/src/modules/UI.pickerFrame.test.js

@@ -0,0 +1,236 @@
+// @vitest-environment jsdom
+// @vitest-environment-options {"url": "https://notes.puter.test/doc"}
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { UIModule } = await import('./UI.js');
+
+// jsdom has no top-layer dialogs.
+HTMLDialogElement.prototype.showModal = function () {
+    this.open = true;
+};
+HTMLDialogElement.prototype.close = function () {
+    this.open = false;
+};
+
+const GUI_ORIGIN = 'https://puter.test';
+const USER = '0b1c9a52-3f0e-4c7a-9a65-2f6d1e8b7c40';
+
+const pickerFrame = () => document.querySelector('dialog.puter-popup-frame iframe');
+const fragment = () => Object.fromEntries(new URLSearchParams(new URL(pickerFrame().src).hash.slice(1)));
+
+const fromFrame = (data, source = pickerFrame().contentWindow) =>
+    window.dispatchEvent(new MessageEvent('message', { data, origin: GUI_ORIGIN, source }));
+
+const makeUI = () => new UIModule(
+    { env: 'web', authToken: 'token-1', APIOrigin: 'https://api.puter.test', appID: 'app-1', util: {} },
+    { appInstanceID: 'instance-1' },
+);
+
+const fakePuter = ({ signedIn = true } = {}) => {
+    globalThis.puter = {
+        defaultGUIOrigin: GUI_ORIGIN,
+        whoamiCache_: Promise.resolve({ uuid: USER }),
+        trackOpenedWindow_: vi.fn(),
+        auth: {
+            isSignedIn: () => signedIn,
+            getUser: vi.fn(async () => ({ uuid: USER })),
+        },
+    };
+};
+
+const PENDING = Symbol('pending');
+const settled = (promise) => Promise.race([promise, new Promise((r) => setTimeout(() => r(PENDING), 0))]);
+
+let popup;
+
+beforeEach(() => {
+    document.body.innerHTML = '';
+    popup = { closed: false, postMessage: vi.fn() };
+    window.open = vi.fn(() => popup);
+    Object.defineProperty(navigator, 'userActivation', {
+        configurable: true,
+        value: { hasBeenActive: true, isActive: true },
+    });
+    fakePuter();
+});
+
+afterEach(() => {
+    delete navigator.userActivation;
+    delete globalThis.puter;
+    vi.useRealTimers();
+});
+
+describe('pickers on a signed-in first-party page', () => {
+    it('shows the open file picker in a frame and resolves what it picks', async () => {
+        const ui = makeUI();
+        const result = ui.showOpenFilePicker({ multiple: false, accept: '.txt' });
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        const url = new URL(pickerFrame().src);
+        expect(url.pathname).toBe('/embed/show-open-file-picker');
+        expect(fragment()).toEqual({ options: '{"multiple":false,"accept":".txt"}', msg_id: '1', user: USER });
+
+        fromFrame({ msg: 'puterPopupFrame', state: 'ready' });
+        fromFrame({
+            msg: 'fileOpenPicked',
+            original_msg_id: '1',
+            items: [{ uid: 'uid-1', name: 'a.txt', path: '~/Desktop/a.txt' }],
+        });
+        await expect(result).resolves.toMatchObject({ uid: 'uid-1', name: 'a.txt' });
+        fromFrame({ msg: 'puterPopupFrame', state: 'closed' });
+        expect(pickerFrame()).toBeNull();
+        expect(window.open).not.toHaveBeenCalled();
+    });
+
+    it('keeps the page token instead of adopting the one the frame sends', async () => {
+        makeUI().showDirectoryPicker();
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        expect(puter.trackOpenedWindow_).not.toHaveBeenCalled();
+    });
+
+    it('settles a picker the GUI reports cancelled', async () => {
+        const result = makeUI().showDirectoryPicker();
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        expect(new URL(pickerFrame().src).pathname).toBe('/embed/show-directory-picker');
+        fromFrame({ msg: 'directoryOpenCancelled', original_msg_id: '1' });
+        fromFrame({ msg: 'puterPopupFrame', state: 'closed' });
+        await expect(result.undefinedOnCancel).resolves.toBeUndefined();
+        expect(await settled(result)).toBe(PENDING);
+    });
+
+    it('settles as cancelled when the frame is dismissed without an answer', async () => {
+        vi.useFakeTimers();
+        const result = makeUI().showOpenFilePicker();
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        await vi.advanceTimersByTimeAsync(200);
+        document.querySelector('.puter-popup-frame-loading').click();
+        await expect(result.undefinedOnCancel).resolves.toBeUndefined();
+        expect(pickerFrame()).toBeNull();
+    });
+
+    it('hands the file content to the save picker frame, and only to it', async () => {
+        const result = makeUI().showSaveFilePicker('hello', 'a.txt');
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        expect(new URL(pickerFrame().src).pathname).toBe('/embed/show-save-file-picker');
+        const frameWindow = pickerFrame().contentWindow;
+        const post = vi.spyOn(frameWindow, 'postMessage').mockImplementation(() => {});
+
+        window.dispatchEvent(new MessageEvent('message', { data: { msg: 'sendMeFileData' }, origin: GUI_ORIGIN, source: window }));
+        window.dispatchEvent(new MessageEvent('message', { data: { msg: 'sendMeFileData' }, origin: 'https://other.test', source: frameWindow }));
+        expect(post).not.toHaveBeenCalled();
+
+        fromFrame({ msg: 'sendMeFileData' });
+        expect(post).toHaveBeenCalledWith(
+            expect.objectContaining({ msg: 'showSaveFilePickerPopup', content: 'hello', suggestedName: 'a.txt' }),
+            GUI_ORIGIN,
+        );
+        fromFrame({ msg: 'fileSaved', original_msg_id: '1', saved_file: { name: 'a.txt', uid: 'uid-2' } });
+        await expect(result).resolves.toMatchObject({ name: 'a.txt' });
+    });
+
+    it('hands the file content again to a save picker frame that reloads, until it closes', async () => {
+        const result = makeUI().showSaveFilePicker('hello', 'a.txt');
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        const frameWindow = pickerFrame().contentWindow;
+        const post = vi.spyOn(frameWindow, 'postMessage').mockImplementation(() => {});
+
+        fromFrame({ msg: 'sendMeFileData' });
+        // The reloaded document asks again.
+        fromFrame({ msg: 'sendMeFileData' });
+        expect(post).toHaveBeenCalledTimes(2);
+        expect(post.mock.calls[1][0]).toMatchObject({ msg: 'showSaveFilePickerPopup', content: 'hello' });
+
+        fromFrame({ msg: 'puterPopupFrame', state: 'closed' });
+        await expect(result.undefinedOnCancel).resolves.toBeUndefined();
+        fromFrame({ msg: 'sendMeFileData' }, frameWindow);
+        expect(post).toHaveBeenCalledTimes(2);
+    });
+
+    it('opens the popup instead when the frame cannot serve the user', async () => {
+        const ui = makeUI();
+        const result = ui.showOpenFilePicker();
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        fromFrame({ msg: 'puterPopupFrame', state: 'loading' });
+        fromFrame({ msg: 'puterPopupFrame', state: 'unavailable' });
+        await vi.waitFor(() => expect(window.open).toHaveBeenCalledTimes(1));
+        expect(pickerFrame()).toBeNull();
+        expect(window.open.mock.calls[0][0]).toContain(`${GUI_ORIGIN}/action/show-open-file-picker?embedded_in_popup=true&msg_id=1`);
+        expect(puter.trackOpenedWindow_).toHaveBeenCalledWith(popup);
+
+        // The popup's answer reaches the picker as before.
+        window.dispatchEvent(new MessageEvent('message', {
+            data: { msg: 'fileOpenPicked', original_msg_id: 1, items: [{ uid: 'uid-1', name: 'a.txt' }] },
+            origin: GUI_ORIGIN,
+            source: popup,
+        }));
+        await expect(result).resolves.toMatchObject({ uid: 'uid-1' });
+    });
+
+    it('asks for a click before opening the popup once the original click has expired', async () => {
+        const result = makeUI().showOpenFilePicker();
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        Object.defineProperty(navigator, 'userActivation', {
+            configurable: true,
+            value: { hasBeenActive: true, isActive: false },
+        });
+        fromFrame({ msg: 'puterPopupFrame', state: 'unavailable' });
+        await vi.waitFor(() => expect(document.querySelector('puter-dialog')).not.toBeNull());
+        expect(window.open).not.toHaveBeenCalled();
+        expect(document.querySelector('puter-dialog').shadowRoot.querySelector('.about').textContent)
+            .toBe('This website wants you to choose a file from your Puter account.');
+
+        document.querySelector('puter-dialog').shadowRoot.querySelector('#launch-auth-popup').click();
+        expect(window.open).toHaveBeenCalledTimes(1);
+        expect(window.open.mock.calls[0][2]).toContain('width=700, height=400');
+        expect(document.querySelector('puter-dialog')).toBeNull();
+
+        const cancelled = makeUI().showDirectoryPicker();
+        await vi.waitFor(() => expect(pickerFrame()).not.toBeNull());
+        fromFrame({ msg: 'puterPopupFrame', state: 'unavailable' });
+        await vi.waitFor(() => expect(document.querySelector('puter-dialog')).not.toBeNull());
+        expect(document.querySelector('puter-dialog').shadowRoot.querySelector('.about').textContent)
+            .toBe('This website wants you to choose a folder from your Puter account.');
+        document.querySelector('puter-dialog').shadowRoot.querySelector('#launch-auth-popup-cancel').click();
+        await expect(cancelled.undefinedOnCancel).resolves.toBeUndefined();
+        expect(document.querySelector('puter-dialog')).toBeNull();
+        expect(await settled(result)).toBe(PENDING);
+        expect(await settled(result.undefinedOnCancel)).toBe(PENDING);
+    });
+
+    it('opens the popup when the page has no user to name', async () => {
+        puter.whoamiCache_ = Promise.resolve(null);
+        puter.auth.getUser = vi.fn(async () => {
+            throw new Error('nope');
+        });
+        makeUI().showDirectoryPicker();
+        await vi.waitFor(() => expect(window.open).toHaveBeenCalledTimes(1));
+        expect(pickerFrame()).toBeNull();
+    });
+});
+
+describe('pickers that keep the popup', () => {
+    it('opens it synchronously for a signed-out first-party page', () => {
+        fakePuter({ signedIn: false });
+        makeUI().showOpenFilePicker();
+        expect(window.open).toHaveBeenCalledTimes(1);
+        expect(pickerFrame()).toBeNull();
+    });
+
+    it('opens it synchronously for a page in a frame of another site', () => {
+        Object.defineProperty(window.location, 'ancestorOrigins', { configurable: true, value: ['https://other.test'] });
+        try {
+            makeUI().showOpenFilePicker();
+            expect(window.open).toHaveBeenCalledTimes(1);
+            expect(pickerFrame()).toBeNull();
+        } finally {
+            delete window.location.ancestorOrigins;
+        }
+    });
+
+    it('opens it synchronously for a page outside the Puter origin', () => {
+        globalThis.puter.defaultGUIOrigin = 'https://puter.com';
+        makeUI().showSaveFilePicker('x', 'a.txt');
+        makeUI().showDirectoryPicker();
+        expect(window.open).toHaveBeenCalledTimes(2);
+        expect(pickerFrame()).toBeNull();
+    });
+});

src/puter-js/src/modules/UI.showFeedbackDialog.test.js

@@ -0,0 +1,111 @@
+// @vitest-environment jsdom
+// @vitest-environment-options {"url": "https://notes.puter.test/doc"}
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { UIModule } = await import('./UI.js');
+
+// jsdom has no top-layer dialogs.
+HTMLDialogElement.prototype.showModal = function () {
+    this.open = true;
+};
+
+const GUI_ORIGIN = 'https://puter.test';
+const USER = '0b1c9a52-3f0e-4c7a-9a65-2f6d1e8b7c40';
+
+const makeUI = () => new UIModule(
+    { env: 'web', authToken: 'token-1', APIOrigin: 'https://api.puter.test', util: {} },
+    {},
+);
+
+const embedFrame = () => document.querySelector('dialog.puter-feedback-embed iframe');
+
+const fromEmbed = (data) => window.dispatchEvent(new MessageEvent('message', {
+    data, origin: GUI_ORIGIN, source: embedFrame().contentWindow,
+}));
+
+let popup;
+
+const fakePuter = ({ guiOrigin = GUI_ORIGIN, signedIn = true } = {}) => {
+    globalThis.puter = {
+        defaultGUIOrigin: guiOrigin,
+        auth: {
+            isSignedIn: () => signedIn,
+            getUser: vi.fn(async () => ({ uuid: USER })),
+        },
+    };
+};
+
+beforeEach(() => {
+    document.body.innerHTML = '';
+    popup = { closed: false, close: vi.fn() };
+    window.open = vi.fn(() => popup);
+    Object.defineProperty(navigator, 'userActivation', {
+        configurable: true,
+        value: { hasBeenActive: true, isActive: true },
+    });
+    fakePuter();
+});
+
+describe('ui.showFeedbackDialog on a first-party page', () => {
+    it('shows the dialog in a frame instead of a popup', async () => {
+        const result = makeUI().showFeedbackDialog();
+        await vi.waitFor(() => expect(embedFrame()).not.toBeNull());
+        fromEmbed({ msg: 'feedbackEmbed', state: 'ready' });
+        fromEmbed({ msg: 'feedbackDialogClosed', sent: true });
+        await expect(result).resolves.toBe(true);
+        expect(window.open).not.toHaveBeenCalled();
+    });
+
+    it('names the user puter.js already knows, without asking the API again', async () => {
+        globalThis.puter.whoamiCache_ = Promise.resolve({ uuid: USER });
+        const result = makeUI().showFeedbackDialog();
+        await vi.waitFor(() => expect(embedFrame()).not.toBeNull());
+        expect(new URLSearchParams(new URL(embedFrame().src).hash.slice(1)).get('user')).toBe(USER);
+        expect(globalThis.puter.auth.getUser).not.toHaveBeenCalled();
+        fromEmbed({ msg: 'feedbackDialogClosed', sent: false });
+        await expect(result).resolves.toBe(false);
+    });
+
+    it('uses the popup when the embed cannot serve the user', async () => {
+        const result = makeUI().showFeedbackDialog();
+        await vi.waitFor(() => expect(embedFrame()).not.toBeNull());
+        fromEmbed({ msg: 'feedbackEmbed', state: 'unavailable' });
+        await vi.waitFor(() => expect(window.open).toHaveBeenCalledTimes(1));
+        const url = new URL(window.open.mock.calls[0][0]);
+        expect(url.origin + url.pathname).toBe(`${GUI_ORIGIN}/action/send-feedback`);
+
+        window.dispatchEvent(new MessageEvent('message', {
+            data: { msg: 'feedbackDialogClosed', sent: true, original_msg_id: url.searchParams.get('msg_id') },
+            origin: GUI_ORIGIN,
+            source: popup,
+        }));
+        await expect(result).resolves.toBe(true);
+    });
+
+    it('answers false to a second call while the framed dialog is open', async () => {
+        const ui = makeUI();
+        const first = ui.showFeedbackDialog();
+        await vi.waitFor(() => expect(embedFrame()).not.toBeNull());
+        await expect(ui.showFeedbackDialog()).resolves.toBe(false);
+        expect(document.querySelectorAll('dialog.puter-feedback-embed')).toHaveLength(1);
+        fromEmbed({ msg: 'feedbackDialogClosed', sent: false });
+        await expect(first).resolves.toBe(false);
+    });
+
+    it('goes straight to the popup, which can sign in, when the page is signed out', async () => {
+        fakePuter({ signedIn: false });
+        makeUI().showFeedbackDialog();
+        await vi.waitFor(() => expect(window.open).toHaveBeenCalledTimes(1));
+        expect(embedFrame()).toBeNull();
+    });
+});
+
+describe('ui.showFeedbackDialog on a third-party page', () => {
+    it('uses the popup', async () => {
+        fakePuter({ guiOrigin: 'https://other-puter.test' });
+        makeUI().showFeedbackDialog();
+        await vi.waitFor(() => expect(window.open).toHaveBeenCalledTimes(1));
+        expect(embedFrame()).toBeNull();
+        expect(globalThis.puter.auth.getUser).not.toHaveBeenCalled();
+    });
+});

src/puter-js/src/modules/ai/index.js

@@ -1,5 +1,5 @@
 import { PuterModule } from '../../lib/PuterModule.js';
-import { convo } from './convo.js';
+import { realtime } from './realtime.js';
 import { chat } from './chat.js';
 import { txt2img } from './image.js';
 import { listModelProviders, listModels } from './models.js';
@@ -49,7 +49,7 @@ export class AIModule extends PuterModule {
     // runtime so destructured calls (`const { chat } = puter.ai`) keep
     // working like the old arrow fields did.
     chat = chat;
-    convo = convo;
+    realtime = realtime;
     img2txt = img2txt;
     speech2txt = speech2txt;
     speech2speech = speech2speech;
@@ -66,7 +66,7 @@ export class AIModule extends PuterModule {
             /** @type {unknown} */ (this)
         );
         for ( const name of [
-            'chat', 'convo', 'img2txt', 'speech2txt', 'speech2speech',
+            'chat', 'realtime', 'img2txt', 'speech2txt', 'speech2speech',
             'txt2img', 'txt2vid', 'listModels', 'listModelProviders',
         ] ) {
             methods[name] = methods[name].bind(this);

src/puter-js/src/modules/ai/realtime.js

@@ -4,17 +4,17 @@ import {
     CLOSE_MESSAGE_TOO_LARGE,
     RealtimeSession,
     createRealtimeSocket,
-} from './convoTransport.js';
+} from './realtimeTransport.js';
 import { RealtimeEvents } from './realtimeEvents.js';
-import { ConvoMicrophone, ConvoSpeaker } from './convoMedia.js';
-import { ConvoHistory } from './convoHistory.js';
+import { RealtimeMicrophone, RealtimeSpeaker } from './realtimeMedia.js';
+import { RealtimeHistory } from './realtimeHistory.js';
 
-/** @typedef {import('./types.js').ConvoOptions} ConvoOptions */
-/** @typedef {import('./types.js').ConvoSessionOptions} ConvoSessionOptions */
-/** @typedef {import('./types.js').ConvoPlaybackPosition} ConvoPlaybackPosition */
+/** @typedef {import('./types.js').RealtimeOptions} RealtimeOptions */
+/** @typedef {import('./types.js').RealtimeSessionOptions} RealtimeSessionOptions */
+/** @typedef {import('./types.js').RealtimePlaybackPosition} RealtimePlaybackPosition */
 /** @typedef {import('./types.js').RealtimeServerEvent} RealtimeServerEvent */
 /** @typedef {import('./types.js').RealtimeClientEvent} RealtimeClientEvent */
-/** @typedef {{ code: string; message: string }} ConvoError */
+/** @typedef {{ code: string; message: string }} RealtimeError */
 /**
  * A pending reconnect notice. A replacement session opens right away and takes
  * over once the conversation is idle.
@@ -29,7 +29,7 @@ import { ConvoHistory } from './convoHistory.js';
  *     probe: RealtimeSession | null;
  *     created: RealtimeServerEvent | null;
  *     stopProbe: (() => void) | null;
- * }} ConvoHandover
+ * }} RealtimeHandover
  * @internal
  */
 
@@ -106,7 +106,7 @@ const encoder = new TextEncoder();
 /**
  * @param {string} code
  * @param {string} message
- * @returns {ConvoError}
+ * @returns {RealtimeError}
  */
 const failure = (code, message) => ({ code, message });
 
@@ -138,7 +138,7 @@ function mergeSession(base, patch) {
 }
 
 /**
- * @param {ConvoOptions} options
+ * @param {RealtimeOptions} options
  * @param {boolean} [allowModel]
  * @returns {void}
  */
@@ -261,12 +261,12 @@ function encodeEvent(event) {
 /**
  * A prepared realtime conversation with optional media helpers.
  *
- * @extends {RealtimeEvents<import('./types.js').ConvoEventMap>}
+ * @extends {RealtimeEvents<import('./types.js').RealtimeEventMap>}
  */
 export class Conversation extends RealtimeEvents {
     /** @type {import('../../index.js').Puter} */
     #puter;
-    /** @type {ConvoOptions} */
+    /** @type {RealtimeOptions} */
     #options;
     /** @type {'prepared' | 'connecting' | 'connected' | 'closed'} */
     #state = 'prepared';
@@ -285,7 +285,7 @@ export class Conversation extends RealtimeEvents {
      *     type: string;
      *     matches: (event: RealtimeServerEvent) => boolean;
      *     resolve: (event: RealtimeServerEvent) => void;
-     *     reject: (error: ConvoError) => void;
+     *     reject: (error: RealtimeError) => void;
      *     timer: ReturnType<typeof setTimeout>;
      *     eventId?: string;
      *     anyError?: boolean;
@@ -313,7 +313,7 @@ export class Conversation extends RealtimeEvents {
     /**
      * @type {{
      *     resolve: () => void;
-     *     reject: (error: ConvoError) => void;
+     *     reject: (error: RealtimeError) => void;
      * }[]}
      */
     #reconnectWaiters = [];
@@ -330,8 +330,8 @@ export class Conversation extends RealtimeEvents {
      */
     #interruption = null;
     #cancelled = new Set();
-    #history = new ConvoHistory((id) => this.#cancelled.has(id));
-    /** @type {ConvoHandover | null} */
+    #history = new RealtimeHistory((id) => this.#cancelled.has(id));
+    /** @type {RealtimeHandover | null} */
     #handover = null;
     // Speech started and its audio isn't committed or cleared yet.
     #speaking = false;
@@ -358,17 +358,17 @@ export class Conversation extends RealtimeEvents {
     /** @type {Set<string>} */
     #committedItems = new Set();
     // Replayed `conversation.item.create` event IDs on the current session.
-    /** @type {Map<string, import('./convoHistory.js').ReplayEntry>} */
+    /** @type {Map<string, import('./realtimeHistory.js').ReplayEntry>} */
     #replayEvents = new Map();
     #replayReported = false;
-    /** @type {ConvoMicrophone} */
+    /** @type {RealtimeMicrophone} */
     microphone;
-    /** @type {ConvoSpeaker} */
+    /** @type {RealtimeSpeaker} */
     speaker;
 
     /**
      * @param {import('../../index.js').Puter} puter
-     * @param {ConvoOptions} options
+     * @param {RealtimeOptions} options
      * @internal
      */
     constructor(puter, options) {
@@ -380,8 +380,8 @@ export class Conversation extends RealtimeEvents {
             model: options.model ?? DEFAULT_MODEL,
         };
         this.#turnDetection = this.#options.turnDetection !== false;
-        this.microphone = new ConvoMicrophone(this);
-        this.speaker = new ConvoSpeaker(this);
+        this.microphone = new RealtimeMicrophone(this);
+        this.speaker = new RealtimeSpeaker(this);
     }
 
     /** @returns {'prepared' | 'connecting' | 'connected' | 'closed'} */
@@ -807,7 +807,7 @@ export class Conversation extends RealtimeEvents {
      * restarting, is retried with backoff while the current session keeps
      * working; any other refusal ends the attempts.
      *
-     * @param {ConvoHandover} handover
+     * @param {RealtimeHandover} handover
      * @returns {Promise<void>}
      */
     async #openReplacement(handover) {
@@ -887,7 +887,7 @@ export class Conversation extends RealtimeEvents {
     }
 
     /**
-     * @param {ConvoHandover} handover
+     * @param {RealtimeHandover} handover
      * @param {string} [code]
      * @returns {void}
      */
@@ -1011,7 +1011,7 @@ export class Conversation extends RealtimeEvents {
     }
 
     /**
-     * @param {ConvoSessionOptions} options
+     * @param {RealtimeSessionOptions} options
      * @returns {Promise<void>}
      */
     async configure(options) {
@@ -1025,7 +1025,7 @@ export class Conversation extends RealtimeEvents {
      * new session needs. A partial update leaves settings made through native
      * events alone.
      *
-     * @param {ConvoSessionOptions} options
+     * @param {RealtimeSessionOptions} options
      * @param {boolean} [full]
      * @param {number} [ackMs]
      * @returns {Promise<void>}
@@ -1168,7 +1168,7 @@ export class Conversation extends RealtimeEvents {
      * Stops local playback immediately and waits for cancellation and
      * truncation.
      *
-     * @param {ConvoPlaybackPosition} [position]
+     * @param {RealtimePlaybackPosition} [position]
      * @returns {Promise<void>}
      */
     interrupt(position) {
@@ -1181,7 +1181,7 @@ export class Conversation extends RealtimeEvents {
     }
 
     /**
-     * @param {ConvoPlaybackPosition | undefined} position
+     * @param {RealtimePlaybackPosition | undefined} position
      * @param {'manual' | 'speech'} source
      * @returns {Promise<void>}
      */
@@ -1323,7 +1323,7 @@ export class Conversation extends RealtimeEvents {
     }
 
     /**
-     * @param {ConvoError} error
+     * @param {RealtimeError} error
      * @returns {void}
      * @internal
      */
@@ -1347,7 +1347,7 @@ export class Conversation extends RealtimeEvents {
             promptIfUpgradeRequired(
                 error,
                 {
-                    method: 'puter.ai.convo',
+                    method: 'puter.ai.realtime',
                     subscriptionMessage:
                         'Realtime conversations require a subscription.',
                 },
@@ -1404,7 +1404,7 @@ export class Conversation extends RealtimeEvents {
             }
         }
         if (event.type === RECONNECT_NOTICE && !this.#handover) {
-            /** @type {ConvoHandover} */
+            /** @type {RealtimeHandover} */
             const handover = {
                 reason:
                     typeof event.reason === 'string' && event.reason
@@ -1707,7 +1707,7 @@ export class Conversation extends RealtimeEvents {
 
     /** @returns {string} */
     #eventId() {
-        return `puter_convo_${++this.#sequence}`;
+        return `puter_realtime_${++this.#sequence}`;
     }
     /**
      * Sends events together or not at all. `limit` caps the socket's send
@@ -1830,7 +1830,7 @@ export class Conversation extends RealtimeEvents {
         return this.#wait(type, matches, event.event_id, false, timeoutMs);
     }
     /**
-     * @param {ConvoError} error
+     * @param {RealtimeError} error
      * @returns {void}
      */
     #rejectPending(error) {
@@ -1847,10 +1847,10 @@ export class Conversation extends RealtimeEvents {
  * connection.
  *
  * @this {import('./index.js').AIModule}
- * @param {ConvoOptions} [options]
+ * @param {RealtimeOptions} [options]
  * @returns {Promise<Conversation>}
  */
-export async function convo(options = {}) {
+export async function realtime(options = {}) {
     validateOptions(options, true);
     const settings = {
         ...options,

src/puter-js/src/modules/ai/realtime.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { Conversation, convo } from './convo.js';
+import { Conversation, realtime } from './realtime.js';
 
 class FakeWebSocket extends EventTarget {
     static instances = [];
@@ -283,14 +283,14 @@ describe('conversation preparation', () => {
         'rejects invalid options before opening a socket (%j)',
         async (options) => {
             await expect(
-                convo.call({ puter: owner() }, options),
+                realtime.call({ puter: owner() }, options),
             ).rejects.toMatchObject({ code: expect.any(String) });
             expect(FakeWebSocket.instances).toHaveLength(0);
         },
     );
     it('requires authentication outside a browser', async () => {
         await expect(
-            convo.call({ puter: { ...owner(), authToken: null } }),
+            realtime.call({ puter: { ...owner(), authToken: null } }),
         ).rejects.toMatchObject({ code: 'auth_required' });
     });
     it('reports canceled browser authentication', async () => {
@@ -304,7 +304,7 @@ describe('conversation preparation', () => {
                 },
             },
         };
-        await expect(convo.call({ puter })).rejects.toMatchObject({
+        await expect(realtime.call({ puter })).rejects.toMatchObject({
             code: 'auth_canceled',
         });
     });
@@ -988,7 +988,7 @@ it('preflights both events of a text turn before sending either', async () => {
     socket().bufferedAmount =
         192 * 1024 -
         new TextEncoder().encode(
-            JSON.stringify({ ...item, event_id: 'puter_convo_99' }),
+            JSON.stringify({ ...item, event_id: 'puter_realtime_99' }),
         ).byteLength;
     expect(() => c.sendText(text)).toThrow(
         expect.objectContaining({ code: 'queue_full' }),

src/puter-js/src/modules/ai/realtimeHistory.js

@@ -4,7 +4,7 @@
  * An item `conversation.item.create` accepts: a text message, a function call
  * or a function call's output.
  *
- * @typedef {Record<string, unknown> & { type: string }} ConvoReplayItem
+ * @typedef {Record<string, unknown> & { type: string }} RealtimeReplayItem
  */
 
 /**
@@ -29,7 +29,7 @@
  * @property {string} [output]
  */
 
-/** @typedef {{ record: HistoryRecord; item: ConvoReplayItem }} ReplayEntry */
+/** @typedef {{ record: HistoryRecord; item: RealtimeReplayItem }} ReplayEntry */
 
 const ITEM_EVENTS = new Set([
     'conversation.item.added',
@@ -99,7 +99,7 @@ function partText(part) {
  *
  * @internal
  */
-export class ConvoHistory {
+export class RealtimeHistory {
     /** @type {HistoryRecord[]} */
     #records = [];
     /** @type {Map<string, HistoryRecord>} */
@@ -426,7 +426,7 @@ export class ConvoHistory {
      * The `conversation.item.create` item that recreates `record`, or `null`.
      *
      * @param {HistoryRecord} record
-     * @returns {ConvoReplayItem | null}
+     * @returns {RealtimeReplayItem | null}
      */
     #replayItem(record) {
         if (!record.final) return null;

src/puter-js/src/modules/ai/realtimeHistory.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { ConvoHistory } from './convoHistory.js';
+import { RealtimeHistory } from './realtimeHistory.js';
 
 const user = (id, content) => ({
     type: 'conversation.item.added',
@@ -10,9 +10,9 @@ const texts = (history) =>
         .replay(40, 48 * 1024)
         .entries.map(({ item }) => item.content[0].text);
 
-describe('ConvoHistory', () => {
+describe('RealtimeHistory', () => {
     it('cuts text without word breaks at the played share', () => {
-        const history = new ConvoHistory(() => false);
+        const history = new RealtimeHistory(() => false);
         history.observe({
             type: 'response.output_item.added',
             response_id: 'r',
@@ -40,7 +40,7 @@ describe('ConvoHistory', () => {
     });
 
     it('keeps a known transcript when a later copy of the item lacks it', () => {
-        const history = new ConvoHistory(() => false);
+        const history = new RealtimeHistory(() => false);
         history.observe(user('u', [{ type: 'input_audio', transcript: null }]));
         expect(texts(history)).toEqual([]);
         history.observe({
@@ -57,7 +57,7 @@ describe('ConvoHistory', () => {
     });
 
     it('keeps a bounded number of the newest items', () => {
-        const history = new ConvoHistory(() => false);
+        const history = new RealtimeHistory(() => false);
         for (let i = 0; i < 100; i++)
             history.observe(
                 user(`u${i}`, [{ type: 'input_text', text: `${i}` }]),
@@ -67,7 +67,7 @@ describe('ConvoHistory', () => {
     });
 
     it('stops at the first item over the byte budget instead of leaving a gap', () => {
-        const history = new ConvoHistory(() => false);
+        const history = new RealtimeHistory(() => false);
         history.observe(user('u1', [{ type: 'input_text', text: 'old' }]));
         history.observe(
             user('u2', [{ type: 'input_text', text: 'x'.repeat(50_000) }]),
@@ -79,7 +79,7 @@ describe('ConvoHistory', () => {
     it.each(['x'.repeat(49 * 1024), '😀'.repeat(13 * 1024)])(
         'reports an oversized newest item without truncating it',
         (text) => {
-            const history = new ConvoHistory(() => false);
+            const history = new RealtimeHistory(() => false);
             history.observe(
                 user('old', [{ type: 'input_text', text: 'tiny' }]),
             );
@@ -96,7 +96,7 @@ describe('ConvoHistory', () => {
     );
 
     it('waits on every unanswered call since the last user message', () => {
-        const history = new ConvoHistory(() => false);
+        const history = new RealtimeHistory(() => false);
         const call = (id, status = 'completed') =>
             history.observe({
                 type: 'response.output_item.done',
@@ -133,7 +133,7 @@ describe('ConvoHistory', () => {
     });
 
     it('reports the new session copies of replayed items until they are done', () => {
-        const history = new ConvoHistory(() => false);
+        const history = new RealtimeHistory(() => false);
         history.observe(user('old', [{ type: 'input_text', text: 'hi' }]));
         history.replayed(history.replay(40, 48 * 1024).entries);
         const copy = user('new', [{ type: 'input_text', text: 'hi' }]);

src/puter-js/src/modules/ai/realtimeMedia.js

@@ -1,6 +1,6 @@
-/** @typedef {import('./convo.js').Conversation} Conversation */
-/** @typedef {import('./types.js').ConvoPlaybackPosition} ConvoPlaybackPosition */
-/** @typedef {import('./types.js').ConvoSpeakerOptions} ConvoSpeakerOptions */
+/** @typedef {import('./realtime.js').Conversation} Conversation */
+/** @typedef {import('./types.js').RealtimePlaybackPosition} RealtimePlaybackPosition */
+/** @typedef {import('./types.js').RealtimeSpeakerOptions} RealtimeSpeakerOptions */
 /** @typedef {import('./types.js').RealtimeServerEvent} RealtimeServerEvent */
 
 const SAMPLE_RATE = 24000;
@@ -69,7 +69,7 @@ function audioContext(sampleRate) {
 // The worklet owns resampling. Chunks the main thread hasn't taken within
 // about half a second are dropped rather than queued.
 const CAPTURE_WORKLET = `
-class PuterConvoCapture extends AudioWorkletProcessor {
+class PuterRealtimeCapture extends AudioWorkletProcessor {
     constructor() {
         super();
         this.samples = new Int16Array(480);
@@ -108,13 +108,13 @@ class PuterConvoCapture extends AudioWorkletProcessor {
         return true;
     }
 }
-registerProcessor('puter-convo-capture', PuterConvoCapture);
+registerProcessor('puter-realtime-capture', PuterRealtimeCapture);
 `;
 
 /** Optional browser microphone capture. */
-export class ConvoMicrophone {
+export class RealtimeMicrophone {
     /** @type {Conversation} */
-    #convo;
+    #conversation;
     /** @type {MediaStream | null} */
     #stream = null;
     /** @type {AudioContext | null} */
@@ -131,11 +131,11 @@ export class ConvoMicrophone {
     #cancelStart = null;
 
     /**
-     * @param {Conversation} convo
+     * @param {Conversation} conversation
      * @internal
      */
-    constructor(convo) {
-        this.#convo = convo;
+    constructor(conversation) {
+        this.#conversation = conversation;
     }
 
     /**
@@ -145,7 +145,7 @@ export class ConvoMicrophone {
      */
     start() {
         try {
-            this.#convo.assertConnected();
+            this.#conversation.assertConnected();
         } catch (error) {
             return Promise.reject(error);
         }
@@ -184,7 +184,8 @@ export class ConvoMicrophone {
         this.#context = context;
         // A reconnect keeps capture running; chunks are dropped meanwhile.
         const current = () =>
-            generation === this.#generation && this.#convo.state !== 'closed';
+            generation === this.#generation &&
+            this.#conversation.state !== 'closed';
         const permission = navigator.mediaDevices
             .getUserMedia({
                 audio: {
@@ -228,27 +229,27 @@ export class ConvoMicrophone {
         }
         if (!current())
             throw { code: 'session_closed', message: 'Capture was stopped' };
-        this.#node = new AudioWorkletNode(context, 'puter-convo-capture');
+        this.#node = new AudioWorkletNode(context, 'puter-realtime-capture');
         this.#source = context.createMediaStreamSource(stream);
         const node = this.#node;
         node.port.onmessage = ({ data }) => {
             if (!current()) return;
             node.port.postMessage('ack');
-            if (this.#muted || this.#convo.state !== 'connected') return;
+            if (this.#muted || this.#conversation.state !== 'connected') return;
             try {
-                this.#convo.appendAudio(data.pcm);
+                this.#conversation.appendAudio(data.pcm);
             } catch (error) {
                 // A congested socket, or one closing before the conversation
                 // knows it, drops the chunk instead of ending capture: a
                 // reconnect resumes it and a final close stops it.
                 if (DROPPED_CHUNK_ERRORS.has(error?.code)) return;
                 this.stop();
-                this.#convo.reportMediaError(error);
+                this.#conversation.reportMediaError(error);
             }
         };
         node.onprocessorerror = () => {
             this.stop();
-            this.#convo.reportMediaError({
+            this.#conversation.reportMediaError({
                 code: 'media_error',
                 message: 'Microphone processor failed',
             });
@@ -298,9 +299,9 @@ export class ConvoMicrophone {
 }
 
 /** Optional bounded browser PCM playback. */
-export class ConvoSpeaker {
+export class RealtimeSpeaker {
     /** @type {Conversation} */
-    #convo;
+    #conversation;
     /** @type {AudioContext | null} */
     #context = null;
     /** @type {Promise<void> | null} */
@@ -317,7 +318,7 @@ export class ConvoSpeaker {
      * }>}
      */
     #sources = new Set();
-    /** @type {(ConvoPlaybackPosition & { responseId: string }) | null} */
+    /** @type {(RealtimePlaybackPosition & { responseId: string }) | null} */
     #last = null;
     #nextAt = 0;
     #bargeIn = true;
@@ -325,11 +326,11 @@ export class ConvoSpeaker {
     #overflowed = '';
 
     /**
-     * @param {Conversation} convo
+     * @param {Conversation} conversation
      * @internal
      */
-    constructor(convo) {
-        this.#convo = convo;
+    constructor(conversation) {
+        this.#conversation = conversation;
     }
     /**
      * @returns {boolean}
@@ -365,12 +366,12 @@ export class ConvoSpeaker {
     /**
      * Starts playback without requesting microphone access.
      *
-     * @param {ConvoSpeakerOptions} [options]
+     * @param {RealtimeSpeakerOptions} [options]
      * @returns {Promise<void>}
      */
     start(options = {}) {
         try {
-            this.#convo.assertConnected();
+            this.#conversation.assertConnected();
         } catch (error) {
             return Promise.reject(error);
         }
@@ -424,7 +425,7 @@ export class ConvoSpeaker {
             const responseId = String(event.response_id ?? '');
             if (this.#overflowed !== responseId) {
                 this.#overflowed = responseId;
-                this.#convo.reportMediaError({
+                this.#conversation.reportMediaError({
                     code: 'queue_full',
                     message: `Playback exceeds ${MAX_SCHEDULED_SECONDS} seconds`,
                 });
@@ -471,7 +472,7 @@ export class ConvoSpeaker {
                     this.#last.playedMs,
                     (offset + duration) * 1000,
                 );
-            if (!this.#sources.size) this.#convo.playbackEnded();
+            if (!this.#sources.size) this.#conversation.playbackEnded();
         };
         this.#nextAt = source.end;
         node.start(start);
@@ -483,7 +484,7 @@ export class ConvoSpeaker {
      * is scheduled, it is the end of what played for `responseId`.
      *
      * @param {string} [responseId] The response still generating, if any.
-     * @returns {ConvoPlaybackPosition | undefined}
+     * @returns {RealtimePlaybackPosition | undefined}
      * @internal
      */
     playbackPosition(responseId) {
@@ -503,7 +504,7 @@ export class ConvoSpeaker {
      * Each item with scheduled audio the listener hasn't fully heard, in play
      * order, with how much of it was heard.
      *
-     * @returns {ConvoPlaybackPosition[]}
+     * @returns {RealtimePlaybackPosition[]}
      * @internal
      */
     unheard() {
@@ -511,7 +512,7 @@ export class ConvoSpeaker {
         const heard =
             (context?.currentTime ?? 0) -
             (context?.outputLatency || context?.baseLatency || 0);
-        /** @type {Map<string, ConvoPlaybackPosition>} */
+        /** @type {Map<string, RealtimePlaybackPosition>} */
         const items = new Map();
         for (const source of this.#sources) {
             if (source.end <= heard || items.has(source.itemId)) continue;
@@ -540,7 +541,7 @@ export class ConvoSpeaker {
         this.#sources.clear();
         this.#last = null;
         this.#nextAt = 0;
-        if (playing) this.#convo.playbackEnded();
+        if (playing) this.#conversation.playbackEnded();
     }
 
     /**

src/puter-js/src/modules/ai/realtimeMedia.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, expect, it, vi } from 'vitest';
-import { ConvoMicrophone, ConvoSpeaker } from './convoMedia.js';
+import { RealtimeMicrophone, RealtimeSpeaker } from './realtimeMedia.js';
 
 class FakeContext {
     static instances = [];
@@ -43,7 +43,7 @@ class FakeWorklet {
     connect = vi.fn();
     disconnect = vi.fn();
 }
-const makeConvo = () => ({
+const makeConversation = () => ({
     state: 'connected',
     assertConnected() {
         if (this.state !== 'connected') throw { code: 'session_closed' };
@@ -73,7 +73,7 @@ afterEach(async () => {
 });
 
 it('captures PCM, acknowledges bounded worklet chunks, mutes and releases tracks', async () => {
-    const c = makeConvo();
+    const c = makeConversation();
     const audioTrack = track();
     vi.stubGlobal('navigator', {
         mediaDevices: {
@@ -83,7 +83,7 @@ it('captures PCM, acknowledges bounded worklet chunks, mutes and releases tracks
             })),
         },
     });
-    const mic = new ConvoMicrophone(c);
+    const mic = new RealtimeMicrophone(c);
     helpers.push(mic);
     const pending = mic.start();
     expect(mic.start()).toBe(pending);
@@ -115,7 +115,7 @@ it('releases a stream when permission resolves after stop', async () => {
                 }),
         },
     });
-    const mic = new ConvoMicrophone(makeConvo());
+    const mic = new RealtimeMicrophone(makeConversation());
     helpers.push(mic);
     const pending = mic.start();
     mic.stop();
@@ -134,7 +134,7 @@ it('settles start() when stopped during the permission prompt', async () => {
                 }),
         },
     });
-    const mic = new ConvoMicrophone(makeConvo());
+    const mic = new RealtimeMicrophone(makeConversation());
     helpers.push(mic);
     const pending = mic.start();
     mic.stop();
@@ -154,7 +154,7 @@ it('reports browser playback failures with SDK error codes', async () => {
             }
         },
     );
-    const speaker = new ConvoSpeaker(makeConvo());
+    const speaker = new RealtimeSpeaker(makeConversation());
     helpers.push(speaker);
     await expect(speaker.start()).rejects.toEqual({
         code: 'media_error',
@@ -162,14 +162,14 @@ it('reports browser playback failures with SDK error codes', async () => {
     });
 });
 /** A started microphone over fake browser media. */
-const startedMic = async (c = makeConvo()) => {
+const startedMic = async (c = makeConversation()) => {
     const audioTrack = track();
     const getUserMedia = vi.fn(async () => ({
         getTracks: () => [audioTrack],
         getAudioTracks: () => [audioTrack],
     }));
     vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
-    const mic = new ConvoMicrophone(c);
+    const mic = new RealtimeMicrophone(c);
     helpers.push(mic);
     await mic.start();
     const port = FakeWorklet.instances.at(-1).port;
@@ -269,7 +269,7 @@ it('captures at the device rate', async () => {
         return new FakeContext();
     });
     vi.stubGlobal('AudioContext', ContextSpy);
-    const mic = new ConvoMicrophone(makeConvo());
+    const mic = new RealtimeMicrophone(makeConversation());
     helpers.push(mic);
     await mic.start();
     expect(ContextSpy).toHaveBeenCalledWith(undefined);
@@ -284,7 +284,7 @@ it('reports a denied permission', async () => {
             },
         },
     });
-    const mic = new ConvoMicrophone(makeConvo());
+    const mic = new RealtimeMicrophone(makeConversation());
     helpers.push(mic);
     await expect(mic.start()).rejects.toMatchObject({
         code: 'permission_denied',
@@ -292,7 +292,7 @@ it('reports a denied permission', async () => {
 });
 it('rejects unsupported capture environments', async () => {
     vi.stubGlobal('navigator', {});
-    const mic = new ConvoMicrophone(makeConvo());
+    const mic = new RealtimeMicrophone(makeConversation());
     helpers.push(mic);
     await expect(mic.start()).rejects.toMatchObject({
         code: 'unsupported_environment',
@@ -310,7 +310,7 @@ it('waits on the permission prompt but times out a stuck audio context', async (
                 }),
         },
     });
-    const mic = new ConvoMicrophone(makeConvo());
+    const mic = new RealtimeMicrophone(makeConversation());
     helpers.push(mic);
     const result = expect(mic.start()).rejects.toMatchObject({
         code: 'media_timeout',
@@ -323,7 +323,7 @@ it('waits on the permission prompt but times out a stuck audio context', async (
     expect(audioTrack.stop).toHaveBeenCalled();
 });
 it('tracks played position and clears playback immediately', async () => {
-    const speaker = new ConvoSpeaker(makeConvo());
+    const speaker = new RealtimeSpeaker(makeConversation());
     helpers.push(speaker);
     await speaker.start();
     speaker.enqueue(new Int16Array(2400), {
@@ -348,8 +348,8 @@ it('tracks played position and clears playback immediately', async () => {
     expect(context.close).toHaveBeenCalled();
 });
 it('bounds scheduled playback without interrupting the reply', async () => {
-    const c = makeConvo();
-    const speaker = new ConvoSpeaker(c);
+    const c = makeConversation();
+    const speaker = new RealtimeSpeaker(c);
     helpers.push(speaker);
     await speaker.start({ bargeIn: false });
     const delta = {
@@ -371,7 +371,7 @@ it('bounds scheduled playback without interrupting the reply', async () => {
     expect(speaker.bargeIn).toBe(false);
 });
 it('subtracts output latency and covers gaps between chunks', async () => {
-    const speaker = new ConvoSpeaker(makeConvo());
+    const speaker = new RealtimeSpeaker(makeConversation());
     helpers.push(speaker);
     await speaker.start();
     const context = FakeContext.instances[0];
@@ -396,8 +396,8 @@ it('subtracts output latency and covers gaps between chunks', async () => {
 });
 
 it('reports playing until the last scheduled chunk ends', async () => {
-    const c = makeConvo();
-    const speaker = new ConvoSpeaker(c);
+    const c = makeConversation();
+    const speaker = new RealtimeSpeaker(c);
     helpers.push(speaker);
     await speaker.start();
     const context = FakeContext.instances[0];
@@ -429,7 +429,7 @@ it('reports playing until the last scheduled chunk ends', async () => {
 });
 
 it('lists every item not fully heard, in play order', async () => {
-    const speaker = new ConvoSpeaker(makeConvo());
+    const speaker = new RealtimeSpeaker(makeConversation());
     helpers.push(speaker);
     await speaker.start();
     const context = FakeContext.instances[0];
@@ -469,7 +469,7 @@ it('a late canceled permission request does not stop a newer capture', async ()
                     : Promise.resolve({ getTracks: () => [newTrack] }),
         },
     });
-    const mic = new ConvoMicrophone(makeConvo());
+    const mic = new RealtimeMicrophone(makeConversation());
     helpers.push(mic);
     const oldStart = mic.start();
     mic.stop();

src/puter-js/src/modules/ai/realtimeTransport.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { RealtimeSession } from './convoTransport.js';
+import { RealtimeSession } from './realtimeTransport.js';
 
 /** Just enough of a WebSocket to drive the session's listeners. */
 const fakeSocket = () => {

src/puter-js/src/modules/ai/types.js

@@ -602,7 +602,7 @@ export {};
 /**
  * Session settings for a live conversation.
  *
- * @typedef {Object} ConvoSessionOptions
+ * @typedef {Object} RealtimeSessionOptions
  * @property {string} [instructions] Instructions, up to 8192 characters.
  * @property {('text' | 'audio')[]} [output] Defaults to audio. Audio includes transcript events.
  * @property {string} [voice] OpenAI voice identifier, up to 128 characters.
@@ -611,12 +611,12 @@ export {};
 /**
  * Options for preparing a conversation.
  *
- * @typedef {ConvoSessionOptions & { model?: string }} ConvoOptions
+ * @typedef {RealtimeSessionOptions & { model?: string }} RealtimeOptions
  */
 /**
  * How much of an assistant audio item a custom player has played.
  *
- * @typedef {Object} ConvoPlaybackPosition
+ * @typedef {Object} RealtimePlaybackPosition
  * @property {string} itemId Assistant message item ID.
  * @property {number} contentIndex Audio content index.
  * @property {number} playedMs Played duration in milliseconds.
@@ -624,24 +624,24 @@ export {};
 /**
  * Built-in speaker options.
  *
- * @typedef {Object} ConvoSpeakerOptions
+ * @typedef {Object} RealtimeSpeakerOptions
  * @property {boolean} [bargeIn] Stop replies when user speech is detected. Defaults to true.
  */
 
 /**
- * @typedef {{ type: 'text'; delta: string; responseId: string }} ConvoTextEvent */
+ * @typedef {{ type: 'text'; delta: string; responseId: string }} RealtimeTextEvent */
 /**
- * @typedef {{ type: 'audio'; pcm: Int16Array; sampleRate: number; responseId: string; itemId: string; contentIndex: number }} ConvoAudioEvent */
+ * @typedef {{ type: 'audio'; pcm: Int16Array; sampleRate: number; responseId: string; itemId: string; contentIndex: number }} RealtimeAudioEvent */
 /**
- * @typedef {{ type: 'transcript'; role: 'user' | 'assistant'; text: string; final: boolean }} ConvoTranscriptEvent */
+ * @typedef {{ type: 'transcript'; role: 'user' | 'assistant'; text: string; final: boolean }} RealtimeTranscriptEvent */
 /**
- * @typedef {{ type: 'interrupted'; source: 'manual' | 'speech'; responseId: string }} ConvoInterruptedEvent */
+ * @typedef {{ type: 'interrupted'; source: 'manual' | 'speech'; responseId: string }} RealtimeInterruptedEvent */
 /**
  * A finished reply. `usage` and `status` are OpenAI's, unchanged.
- * @typedef {{ type: 'turn.done'; responseId: string | undefined; usage: unknown; status: unknown }} ConvoTurnDoneEvent */
+ * @typedef {{ type: 'turn.done'; responseId: string | undefined; usage: unknown; status: unknown }} RealtimeTurnDoneEvent */
 /**
  * An OpenAI `error` event, or an SDK media failure, which also carries `code` and `message` at the
  * top level.
- * @typedef {{ type: 'error'; error: { code?: string; message?: string } & Record<string, unknown>; code?: string; message?: string }} ConvoErrorEvent */
+ * @typedef {{ type: 'error'; error: { code?: string; message?: string } & Record<string, unknown>; code?: string; message?: string }} RealtimeErrorEvent */
 /** Native provider events retain their provider-owned fields.
- * @typedef {Record<string, RealtimeServerEvent> & { text: ConvoTextEvent; audio: ConvoAudioEvent; transcript: ConvoTranscriptEvent; interrupted: ConvoInterruptedEvent; 'turn.done': ConvoTurnDoneEvent; error: ConvoErrorEvent; ready: { type: 'ready'; model: string; provider: 'openai'; reconnected?: boolean }; reconnecting: { type: 'reconnecting'; code: number; reason: string }; context_trimmed: { type: 'context_trimmed'; omittedItems: number }; close: { type: 'close'; code: number; reason: string } }} ConvoEventMap */
+ * @typedef {Record<string, RealtimeServerEvent> & { text: RealtimeTextEvent; audio: RealtimeAudioEvent; transcript: RealtimeTranscriptEvent; interrupted: RealtimeInterruptedEvent; 'turn.done': RealtimeTurnDoneEvent; error: RealtimeErrorEvent; ready: { type: 'ready'; model: string; provider: 'openai'; reconnected?: boolean }; reconnecting: { type: 'reconnecting'; code: number; reason: string }; context_trimmed: { type: 'context_trimmed'; omittedItems: number }; close: { type: 'close'; code: number; reason: string } }} RealtimeEventMap */

src/puter-js/src/ui/components.md

@@ -37,6 +37,7 @@ All components use **Shadow DOM** so their styles won't leak into your page. The
 | [`<puter-spinner>`](#puter-spinner) | Loading overlay | `puter.ui.showSpinner()` / `hideSpinner()` |
 | [`<puter-color-picker>`](#puter-color-picker) | Color picker dialog | `puter.ui.showColorPicker()` |
 | [`<puter-font-picker>`](#puter-font-picker) | Font picker dialog | `puter.ui.showFontPicker()` |
+| [`<puter-user-menu>`](#puter-user-menu) | Account button and Puter's app browser, for first-party apps | none |
 
 ---
 
@@ -334,13 +335,71 @@ el.open();
 
 ---
 
+### `<puter-user-menu>`
+
+The account button and Puter's app browser for a first-party app on a Puter subdomain (`notes.puter.com`). It is internal and left out of the public docs, because the app browser only works one subdomain under the Puter origin. It follows the page's own puter.js sign-in, never the Puter session's.
+
+- Signed out, it shows **Sign in**, which calls `puter.auth.signIn()`. A temporary account counts as signed out.
+- Signed in, it shows the user's profile picture, or the username's initial when there is none. Clicking it opens a menu with:
+  - The user's picture, username and email. The email line is hidden when whoami leaves it out, such as for an app that can't read it.
+  - **Manage account**, **Usage** and **Open Puter**, links that open the GUI origin's `/dashboard/#account`, `/dashboard/#usage` and `/` in a new tab.
+  - **Send feedback**, which calls `puter.ui.showFeedbackDialog()`.
+  - **Sign out**, which calls `puter.auth.signOut()`.
+- The menu opens with focus on its first item. ArrowUp and ArrowDown move between items and wrap around, and Home and End jump to the first and last.
+- On a page exactly one label under the Puter origin, with the same scheme and port, other than Puter's own subdomains such as `api` and `docs`, an **Apps** button opens the app browser (`/embed/apps`) in a panel under the button. It names the signed-in user as `#user=<uuid>`, so the app browser shows the Puter session's apps only to that user (see `doc/embedding-app-browser.md`), and passes a forced `theme` on as `theme=`. Elsewhere the button is hidden, because the server refuses the framing.
+- The menu and the Apps panel hang under their button with a caret pointing at it, and close on Escape, a press outside them, or their button. They're in the browser's top layer where it has one, so a host's `transform`, `overflow` or `z-index` can't clip or cover them. On screens up to 600px wide, the Apps panel spans the width below the button.
+- Closing the Apps panel keeps the app browser, so reopening it keeps its scroll and search. Any change to the page's sign-in discards it, so it never stays loaded for the previous user.
+- It renders nothing outside a top-level page (`puter.env !== 'web'`), such as inside the Puter desktop.
+
+**Attributes**
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `apps-label` | `Apps` | Apps button label, panel title and iframe title |
+| `sign-in-label` | `Sign in` | Sign-in button text |
+| `sign-out-label` | `Sign out` | Sign-out menu item text |
+| `close-label` | `Close` | The Apps panel's close button label |
+| `account-label` | `Account` | Account button label, read as `Account: <username>` |
+| `manage-account-label` | `Manage account` | Menu link to the account settings |
+| `usage-label` | `Usage` | Menu link to the usage page |
+| `open-puter-label` | `Open Puter` | Menu link to Puter |
+| `feedback-label` | `Send feedback` | Menu item that opens the feedback dialog |
+| `theme` | follows the OS | `light` or `dark`, for the component and the app browser in it |
+
+Changing an attribute updates the component in place.
+
+**Parts**
+
+`apps-button`, `avatar`, `sign-in`, `menu` and `apps-panel`, for styling from the host page with `puter-user-menu::part(avatar) { ... }`.
+
+**Events**
+
+| Event | Detail | When |
+|-------|--------|------|
+| `signin` | `{ user }`, the signed-in user or `null` | Sign in finished |
+| `signout` | none | The user signed out from the menu |
+
+**Example**
+```html
+<header>
+    <h1>Notes</h1>
+    <puter-user-menu sign-in-label="Se connecter" sign-out-label="Se déconnecter"></puter-user-menu>
+</header>
+<script>
+    document.querySelector('puter-user-menu')
+        .addEventListener('signout', () => clearNotes());
+</script>
+```
+
+---
+
 ## Styling
 
-All components render inside Shadow DOM and match puter.com's native GUI appearance. Styles are encapsulated and cannot be overridden from outside the component.
+All components render inside Shadow DOM and match puter.com's native GUI appearance. Styles are encapsulated and cannot be overridden from outside the component, except through the parts `<puter-user-menu>` exposes.
 
 ## Dark mode
 
-By default, components that ship dark-mode styles auto-adapt to the OS setting (`prefers-color-scheme: dark`): `<puter-notification>`, `<puter-context-menu>`, `<puter-menubar>`, `<puter-color-picker>`, `<puter-font-picker>`.
+By default, components that ship dark-mode styles auto-adapt to the OS setting (`prefers-color-scheme: dark`): `<puter-notification>`, `<puter-context-menu>`, `<puter-menubar>`, `<puter-color-picker>`, `<puter-font-picker>`, `<puter-user-menu>`.
 
 To force a specific theme regardless of the OS preference, set the `theme` attribute on the component:
 

src/puter-js/src/ui/components/PuterUserMenu.js

@@ -0,0 +1,801 @@
+/**
+ * <puter-user-menu> - The signed-in user's account button and Puter's app
+ * browser, for a page that signs in with puter.js.
+ *
+ * Signed out (a temporary account counts as signed out), it shows a Sign in
+ * button. Signed in, it shows the user's profile picture (or initial), which
+ * opens a menu with the account, links to manage it, see its usage and open
+ * Puter, Send feedback, and Sign out. On a page one subdomain under
+ * the Puter origin, an Apps button opens Puter's app browser in a panel under
+ * it, for the same user: signed out, or signed in as an account other than
+ * the Puter session's, the browser shows only recommended apps. The browser
+ * is kept between opens and dropped whenever the page's sign-in changes.
+ * Renders nothing inside the Puter desktop.
+ *
+ * Attributes: theme, apps-label, sign-in-label, sign-out-label, close-label,
+ *   account-label, manage-account-label, usage-label, open-puter-label,
+ *   feedback-label
+ * Parts: apps-button, avatar, sign-in, menu, apps-panel
+ * Events: signin (detail.user), signout
+ */
+
+import PuterWebComponent from '../PuterWebComponent.js';
+import { defaultFontFamily } from '../PuterDefaultStyles.js';
+import { canFrameGuiEmbed } from '../../lib/guiEmbed.js';
+
+const APPS_ICON = `<svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false">${
+    [5, 12, 19].flatMap(y => [5, 12, 19].map(x => `<circle cx="${x}" cy="${y}" r="2"/>`)).join('')
+}</svg>`;
+const EXTERNAL_ICON = '<svg class="menu-external" viewBox="0 0 32 32" width="11" height="11" aria-hidden="true" focusable="false"><path d="m26 28h-20a2 2 0 0 1 -2-2v-20a2 2 0 0 1 2-2h10v2h-10v20h20v-10h2v10a2 2 0 0 1 -2 2z"/><path d="m20 2v2h6.586l-8.586 8.586 1.414 1.414 8.586-8.586v6.586h2v-10z"/></svg>';
+const CLOSE_ICON = '<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M6 6l12 12M18 6L6 18"/></svg>';
+
+const LABELS = {
+    'apps-label': 'Apps',
+    'sign-in-label': 'Sign in',
+    'sign-out-label': 'Sign out',
+    'close-label': 'Close',
+    'account-label': 'Account',
+    'manage-account-label': 'Manage account',
+    'usage-label': 'Usage',
+    'open-puter-label': 'Open Puter',
+    'feedback-label': 'Send feedback',
+};
+
+// Menu links, each opening a page of the Puter GUI in a new tab.
+const MENU_LINKS = [
+    { className: 'manage-account', label: 'manage-account-label', path: '/dashboard/#account' },
+    { className: 'usage', label: 'usage-label', path: '/dashboard/#usage' },
+    { className: 'open-puter', label: 'open-puter-label', path: '/' },
+];
+
+// Gap between a panel and the viewport edge, and between its caret and corners.
+const EDGE = 8;
+const CARET_INSET = 20;
+
+class PuterUserMenu extends PuterWebComponent {
+    static get observedAttributes () {
+        return Object.keys(LABELS);
+    }
+
+    #unsubscribe = null;
+    // Bumped on every load, so a slower earlier load can't overwrite a later one.
+    #generation = 0;
+    #ready = false;
+    #token = null;
+    #apiOrigin = null;
+    #user = null;
+    #picture = null;
+    // Set while signing out from inside the component, whose focus then moves to Sign in.
+    #focusSignIn = false;
+    // Set while a sign-in popup is open, so another click doesn't open a second one.
+    #signingIn = false;
+    #onDocumentPointerDown = (event) => {
+        if ( ! event.composedPath().includes(this) ) this._closePanels();
+    };
+    #onViewportChange = () => this._positionOpenPanels();
+
+    connectedCallback () {
+        super.connectedCallback();
+        // The SDK defines this element before it assigns `globalThis.puter`.
+        queueMicrotask(() => this._start());
+    }
+
+    disconnectedCallback () {
+        super.disconnectedCallback();
+        this.#unsubscribe?.();
+        this.#unsubscribe = null;
+        this.#generation++;
+        this._closePanels();
+        this._dropApps();
+    }
+
+    attributeChangedCallback () {
+        if ( this.$('.bar') ) this._applyLabels();
+    }
+
+    _applyTheme () {
+        super._applyTheme();
+        const frame = this.shadowRoot?.querySelector('.apps-body iframe');
+        if ( ! frame ) return;
+        frame.style.colorScheme = this._colorScheme();
+        // A forced theme is part of the app browser's URL, so a new one reloads it.
+        if ( frame.src === this._appsUrl() ) return;
+        this._dropApps();
+        if ( ! this.$('.apps-panel').hidden ) this._mountApps();
+    }
+
+    _colorScheme () {
+        return this.classList.contains('puter-theme-dark') ? 'dark' : 'light';
+    }
+
+    /** The `theme` attribute's scheme, or null when the component follows the OS. */
+    _forcedTheme () {
+        const theme = this.getAttribute('theme');
+        return theme === 'dark' || theme === 'light' ? theme : null;
+    }
+
+    _label (name) {
+        return this.getAttribute(name) || LABELS[name];
+    }
+
+    /** Only a top-level page that signs in on its own; the desktop has its own menu. */
+    _active () {
+        return globalThis.puter?.env === 'web';
+    }
+
+    _appsAllowed () {
+        return canFrameGuiEmbed(globalThis.location?.href, globalThis.puter.defaultGUIOrigin);
+    }
+
+    /** A temporary account has nothing to sign out of, so it gets Sign in. */
+    _signedIn () {
+        return Boolean(this.#token) && !this.#user?.is_temp;
+    }
+
+    _start () {
+        if ( !this.isConnected || this.#unsubscribe || !this._active() ) return;
+        this.$('.bar').hidden = false;
+        this.#unsubscribe = globalThis.puter.onAuthStateChanged(() => {
+            const puter = globalThis.puter;
+            if ( puter.authToken === this.#token && puter.APIOrigin === this.#apiOrigin ) return;
+            this._closePanels();
+            this._dropApps();
+            this._load();
+        });
+        this._load();
+    }
+
+    async _load () {
+        const generation = ++this.#generation;
+        const puter = globalThis.puter;
+        this.#ready = false;
+        this.#user = null;
+        this.#picture = null;
+        this.#token = puter.authToken;
+        this.#apiOrigin = puter.APIOrigin;
+        this._renderState();
+
+        // `setAuthToken` announces a token before it starts that token's whoami.
+        await null;
+        // A tab Puter opened for an app gets its token moments after loading.
+        if ( puter.openerLaunch_ ) await puter.openerLaunch_.catch(() => {});
+        const token = puter.authToken;
+        const user = token ? await Promise.resolve(puter.whoami ?? puter.whoamiCache_).catch(() => null) : null;
+        if ( generation !== this.#generation ) return;
+        // Answers for a token since replaced; the newer token loads again.
+        const current = token === puter.authToken;
+        this.#token = puter.authToken;
+        this.#apiOrigin = puter.APIOrigin;
+        this.#user = current && user && typeof user === 'object' ? user : null;
+        this.#ready = true;
+        this._renderState();
+
+        // The picture follows, so a slow profile doesn't hold up the account.
+        if ( !this.#user || this.#user.is_temp ) return;
+        const picture = await puter.auth.getProfilePicture().catch(() => null);
+        if ( generation !== this.#generation || token !== puter.authToken || typeof picture !== 'string' ) return;
+        this.#picture = picture;
+        this._renderState();
+    }
+
+    getStyles () {
+        return `
+            :host {
+                display: inline-flex;
+                font-family: ${defaultFontFamily};
+                -webkit-font-smoothing: antialiased;
+            }
+            [hidden] { display: none !important; }
+            .bar {
+                display: flex;
+                align-items: center;
+                gap: 8px;
+            }
+            button {
+                font-family: inherit;
+                cursor: pointer;
+                -webkit-tap-highlight-color: transparent;
+            }
+            button:focus-visible {
+                outline: 2px solid #088ef0;
+                outline-offset: 2px;
+            }
+            .apps-button {
+                display: inline-flex;
+                align-items: center;
+                justify-content: center;
+                width: 36px;
+                height: 36px;
+                padding: 0;
+                border: none;
+                border-radius: 50%;
+                background: transparent;
+                color: #414650;
+                fill: currentColor;
+            }
+            .apps-button[aria-expanded="true"] { background-color: rgba(0, 0, 0, .06); }
+            .avatar {
+                position: relative;
+                width: 32px;
+                height: 32px;
+                padding: 0;
+                overflow: hidden;
+                border: none;
+                border-radius: 50%;
+                background: linear-gradient(#34a5f8, #088ef0);
+                color: #fff;
+                font-size: 15px;
+                font-weight: 600;
+                line-height: 32px;
+                text-align: center;
+            }
+            .avatar[aria-expanded="true"] { box-shadow: 0 0 0 3px rgba(8, 142, 240, .25); }
+            .avatar img,
+            .menu-avatar img {
+                position: absolute;
+                inset: 0;
+                width: 100%;
+                height: 100%;
+                object-fit: cover;
+            }
+            .sign-in {
+                height: 32px;
+                padding: 0 16px;
+                border: 1px solid #088ef0;
+                border-radius: 4px;
+                background: linear-gradient(#34a5f8, #088ef0);
+                color: #fff;
+                font-size: 14px;
+            }
+            .sign-in:active {
+                background-color: #2798eb;
+                border-color: #2798eb;
+                color: #bedef5;
+            }
+
+            /* Panels hang under their button with a caret pointing at it. In
+               the top layer where the browser has one, so no host transform,
+               overflow or z-index can clip or cover them. */
+            .panel {
+                position: fixed;
+                inset: auto;
+                z-index: 2147483000;
+                margin: 0;
+                padding: 0;
+                overflow: visible;
+                box-sizing: border-box;
+                border: 1px solid #ddd;
+                border-radius: 12px;
+                background-color: #fff;
+                color: #333;
+                box-shadow: 0 12px 32px rgba(0, 0, 0, .16), 0 2px 6px rgba(0, 0, 0, .06);
+                font-family: ${defaultFontFamily};
+                --caret-border: #ddd;
+                --caret-fill: #fff;
+                animation: panel-in .14s ease-out;
+            }
+            .panel:focus, .panel:focus-visible { outline: none; }
+            .panel::before,
+            .panel::after {
+                content: '';
+                position: absolute;
+                top: -8px;
+                left: var(--caret-x, calc(100% - ${CARET_INSET}px));
+                transform: translateX(-50%);
+                border: 8px solid transparent;
+                border-top: none;
+                border-bottom-color: var(--caret-border);
+                pointer-events: none;
+            }
+            .panel::after {
+                top: -7px;
+                border-bottom-color: var(--caret-fill);
+            }
+            @keyframes panel-in {
+                from { opacity: 0; transform: translateY(-4px); }
+                to { opacity: 1; transform: none; }
+            }
+            @media (prefers-reduced-motion: reduce) {
+                .panel { animation: none; }
+            }
+
+            .menu {
+                min-width: 220px;
+                max-width: min(300px, calc(100vw - ${EDGE * 2}px));
+                padding: 4px 0;
+                text-align: left;
+            }
+            .menu-user {
+                display: flex;
+                align-items: center;
+                gap: 10px;
+                padding: 8px 14px 10px;
+                margin-bottom: 4px;
+                border-bottom: 1px solid #eee;
+            }
+            .menu-avatar {
+                position: relative;
+                flex: none;
+                width: 40px;
+                height: 40px;
+                overflow: hidden;
+                border-radius: 50%;
+                background: linear-gradient(#34a5f8, #088ef0);
+                color: #fff;
+                font-size: 18px;
+                font-weight: 600;
+                line-height: 40px;
+                text-align: center;
+            }
+            .menu-identity {
+                display: flex;
+                flex-direction: column;
+                min-width: 0;
+            }
+            .menu-username,
+            .menu-email {
+                overflow: hidden;
+                text-overflow: ellipsis;
+                white-space: nowrap;
+            }
+            .menu-username {
+                color: #414650;
+                font-size: 14px;
+                font-weight: 600;
+            }
+            .menu-email {
+                color: #6b7280;
+                font-size: 12px;
+            }
+            .menu-item {
+                display: flex;
+                align-items: center;
+                gap: 4px;
+                box-sizing: border-box;
+                width: 100%;
+                padding: 8px 14px;
+                border: none;
+                background: none;
+                color: #333;
+                font-size: 14px;
+                line-height: normal;
+                text-align: left;
+                text-decoration: none;
+                cursor: pointer;
+            }
+            .menu-external {
+                flex: none;
+                fill: currentColor;
+                opacity: .7;
+            }
+            .menu-separator {
+                height: 1px;
+                margin: 4px 0;
+                background-color: #eee;
+            }
+            .menu-item:focus-visible {
+                outline: none;
+                background-color: #f0f0f0;
+            }
+
+            .apps-panel {
+                width: 400px;
+                max-width: calc(100vw - ${EDGE * 2}px);
+                height: min(580px, calc(100vh - var(--panel-top, 46px) - 12px));
+                height: min(580px, calc(100dvh - var(--panel-top, 46px) - 12px));
+                min-height: 240px;
+                flex-direction: column;
+            }
+            .apps-panel:not([hidden]) { display: flex; }
+            .apps-header {
+                display: flex;
+                align-items: center;
+                justify-content: space-between;
+                flex: none;
+                gap: 8px;
+                padding: 8px 8px 8px 14px;
+                border-bottom: 1px solid #eee;
+            }
+            .apps-title {
+                color: #222;
+                font-size: 14px;
+                font-weight: 600;
+            }
+            .apps-close {
+                display: flex;
+                align-items: center;
+                justify-content: center;
+                width: 28px;
+                height: 28px;
+                padding: 0;
+                border: none;
+                border-radius: 7px;
+                background: transparent;
+                color: #555;
+            }
+            .apps-body {
+                position: relative;
+                flex: 1 1 auto;
+                min-height: 0;
+                overflow: hidden;
+                border-radius: 0 0 11px 11px;
+            }
+            .apps-body iframe {
+                display: block;
+                width: 100%;
+                height: 100%;
+                border: 0;
+                background: transparent;
+            }
+            .apps-loading {
+                position: absolute;
+                inset: 0;
+                display: none;
+                align-items: center;
+                justify-content: center;
+                pointer-events: none;
+            }
+            .apps-body.is-loading .apps-loading { display: flex; }
+            .apps-body.is-loading iframe { visibility: hidden; }
+            .apps-spinner {
+                width: 22px;
+                height: 22px;
+                box-sizing: border-box;
+                border: 2px solid rgba(0, 0, 0, .12);
+                border-top-color: #555;
+                border-radius: 50%;
+                animation: spin .7s linear infinite;
+            }
+            @keyframes spin { to { transform: rotate(360deg); } }
+            @media (prefers-reduced-motion: reduce) {
+                .apps-spinner { animation-duration: 1.6s; }
+            }
+            @media (max-width: 600px) {
+                .apps-panel {
+                    width: calc(100vw - ${EDGE * 2}px);
+                    height: calc(100vh - var(--panel-top, 54px) - ${EDGE}px);
+                    height: calc(100dvh - var(--panel-top, 54px) - ${EDGE}px);
+                }
+                .apps-header { padding: 6px 6px 6px 16px; }
+                .apps-title { font-size: 15px; }
+                .apps-close { width: 40px; height: 40px; border-radius: 10px; }
+            }
+
+            :host(.puter-theme-dark) .apps-button { color: #e6e6e6; }
+            :host(.puter-theme-dark) .apps-button[aria-expanded="true"] { background-color: rgba(255, 255, 255, .1); }
+            :host(.puter-theme-dark) .panel {
+                border-color: #3a3a3a;
+                background-color: #2a2a2a;
+                color: #e6e6e6;
+                box-shadow: 0 12px 32px rgba(0, 0, 0, .45);
+                --caret-border: #3a3a3a;
+                --caret-fill: #2a2a2a;
+            }
+            :host(.puter-theme-dark) .menu-user,
+            :host(.puter-theme-dark) .apps-header { border-color: #3a3a3a; }
+            :host(.puter-theme-dark) .menu-separator { background-color: #3a3a3a; }
+            :host(.puter-theme-dark) .menu-email { color: #a0a0a0; }
+            :host(.puter-theme-dark) .menu-username,
+            :host(.puter-theme-dark) .apps-title,
+            :host(.puter-theme-dark) .menu-item { color: #e6e6e6; }
+            :host(.puter-theme-dark) .menu-item:focus-visible { background-color: #3a3a3a; color: #fff; }
+            :host(.puter-theme-dark) .apps-close { color: #ccc; }
+            :host(.puter-theme-dark) .apps-spinner {
+                border-color: rgba(255, 255, 255, .15);
+                border-top-color: #ccc;
+            }
+
+            /* A tap leaves :hover on touch screens, which would shade a closed button. */
+            @media (hover: hover) {
+                .apps-button:hover { background-color: rgba(0, 0, 0, .06); }
+                .avatar:hover { box-shadow: 0 0 0 3px rgba(8, 142, 240, .25); }
+                .menu-item:hover { background-color: #f0f0f0; }
+                .apps-close:hover { background-color: #f0f0f0; color: #222; }
+                :host(.puter-theme-dark) .apps-button:hover { background-color: rgba(255, 255, 255, .1); }
+                :host(.puter-theme-dark) .menu-item:hover,
+                :host(.puter-theme-dark) .apps-close:hover { background-color: #3a3a3a; color: #fff; }
+            }
+        `;
+    }
+
+    render () {
+        return `
+            <div class="bar" hidden>
+                <button type="button" class="apps-button" part="apps-button" aria-haspopup="dialog" aria-expanded="false" hidden>${APPS_ICON}</button>
+                <button type="button" class="sign-in" part="sign-in" hidden></button>
+                <button type="button" class="avatar" part="avatar" aria-haspopup="menu" aria-expanded="false" hidden></button>
+            </div>
+            <div class="panel menu" part="menu" role="menu" tabindex="-1" hidden>
+                <div class="menu-user" hidden>
+                    <span class="menu-avatar" aria-hidden="true"></span>
+                    <span class="menu-identity">
+                        <span class="menu-username"></span>
+                        <span class="menu-email" hidden></span>
+                    </span>
+                </div>
+                ${MENU_LINKS.map(link => `<a class="menu-item ${link.className}" role="menuitem" target="_blank" rel="noopener"><span class="menu-label"></span>${EXTERNAL_ICON}</a>`).join('')}
+                <button type="button" class="menu-item feedback" role="menuitem"></button>
+                <div class="menu-separator" role="separator"></div>
+                <button type="button" class="menu-item sign-out" role="menuitem"></button>
+            </div>
+            <div class="panel apps-panel" part="apps-panel" role="dialog" tabindex="-1" hidden>
+                <div class="apps-header">
+                    <span class="apps-title"></span>
+                    <button type="button" class="apps-close">${CLOSE_ICON}</button>
+                </div>
+                <div class="apps-body">
+                    <div class="apps-loading" role="status"><span class="apps-spinner"></span></div>
+                </div>
+            </div>
+        `;
+    }
+
+    onReady () {
+        if ( typeof HTMLElement !== 'undefined' && 'popover' in HTMLElement.prototype ) {
+            for ( const panel of this.$$('.panel') ) panel.setAttribute('popover', 'manual');
+        }
+        this._applyLabels();
+        this.$('.apps-button').addEventListener('click', () => {
+            if ( this.$('.apps-panel').hidden ) this._openApps();
+            else this._closePanels();
+        });
+        this.$('.sign-in').addEventListener('click', () => this._signIn());
+        this.$('.avatar').addEventListener('click', () => {
+            if ( this.$('.menu').hidden ) this._openMenu();
+            else this._closePanels();
+        });
+        for ( const link of MENU_LINKS ) {
+            this.$(`.${link.className}`).addEventListener('click', () => this._closePanels());
+        }
+        this.$('.feedback').addEventListener('click', () => this._sendFeedback());
+        this.$('.sign-out').addEventListener('click', () => this._signOut());
+        this.$('.apps-close').addEventListener('click', () => this._closePanels({ returnFocus: true }));
+        this.shadowRoot.addEventListener('keydown', (event) => {
+            const open = this._openPanel();
+            if ( ! open ) return;
+            if ( event.key === 'Escape' ) {
+                event.preventDefault();
+                this._closePanels({ returnFocus: true });
+            } else if ( event.key === 'Tab' && open.classList.contains('menu') ) {
+                // Tab leaves the menu: it closes, and focus moves on from its button.
+                this._closePanels({ returnFocus: true });
+            } else if ( open.classList.contains('menu') && this._moveMenuFocus(event.key) ) {
+                event.preventDefault();
+            }
+        });
+    }
+
+    _applyLabels () {
+        const apps = this._label('apps-label');
+        const appsButton = this.$('.apps-button');
+        appsButton.setAttribute('aria-label', apps);
+        appsButton.title = apps;
+        this.$('.apps-panel').setAttribute('aria-label', apps);
+        this.$('.apps-title').textContent = apps;
+        this.$('.apps-loading').setAttribute('aria-label', apps);
+        const frame = this.$('.apps-body iframe');
+        if ( frame ) frame.title = apps;
+        const close = this.$('.apps-close');
+        close.setAttribute('aria-label', this._label('close-label'));
+        close.title = this._label('close-label');
+        this.$('.sign-in').textContent = this._label('sign-in-label');
+        this.$('.sign-out').textContent = this._label('sign-out-label');
+        this.$('.feedback').textContent = this._label('feedback-label');
+        for ( const link of MENU_LINKS ) {
+            this.$(`.${link.className} .menu-label`).textContent = this._label(link.label);
+        }
+        this._renderAvatarLabel();
+    }
+
+    _username () {
+        return typeof this.#user?.username === 'string' ? this.#user.username : '';
+    }
+
+    _renderAvatarLabel () {
+        const username = this._username();
+        const account = this._label('account-label');
+        this.$('.avatar').setAttribute('aria-label', username ? `${account}: ${username}` : account);
+    }
+
+    _renderState () {
+        const signedIn = this._signedIn();
+        const username = this._username();
+        this.$('.apps-button').hidden = !this.#ready || !this._appsAllowed();
+        this.$('.sign-in').hidden = !this.#ready || signedIn;
+
+        const avatar = this.$('.avatar');
+        avatar.hidden = !this.#ready || !signedIn;
+        this._fillAvatar(avatar, username);
+        this._renderAvatarLabel();
+        this.$('.menu-user').hidden = !username;
+        this.$('.menu-username').textContent = username;
+        this._fillAvatar(this.$('.menu-avatar'), username);
+        const email = typeof this.#user?.email === 'string' ? this.#user.email : '';
+        this.$('.menu-email').textContent = email;
+        this.$('.menu-email').hidden = !email;
+        for ( const link of MENU_LINKS ) {
+            this.$(`.${link.className}`).href = new URL(link.path, globalThis.puter.defaultGUIOrigin).href;
+        }
+        if ( avatar.hidden && !this.$('.menu').hidden ) this._closePanels();
+        if ( this.#ready && this.#focusSignIn ) {
+            this.#focusSignIn = false;
+            if ( ! this.$('.sign-in').hidden ) this.$('.sign-in').focus({ preventScroll: true });
+        }
+    }
+
+    /** The username's initial, with the profile picture over it once there is one. */
+    _fillAvatar (el, username) {
+        el.textContent = username ? username[0].toUpperCase() : '?';
+        if ( ! this.#picture ) return;
+        const img = document.createElement('img');
+        img.alt = '';
+        // The initial stays underneath for a picture the page's CSP refuses.
+        img.addEventListener('error', () => img.remove());
+        img.src = this.#picture;
+        el.append(img);
+    }
+
+    // -- Panels --
+
+    _openPanel () {
+        return [...this.$$('.panel')].find(panel => !panel.hidden) ?? null;
+    }
+
+    _triggerOf (panel) {
+        return this.$(panel.classList.contains('menu') ? '.avatar' : '.apps-button');
+    }
+
+    _showPanel (panel) {
+        this._closePanels();
+        const trigger = this._triggerOf(panel);
+        panel.hidden = false;
+        if ( typeof panel.showPopover === 'function' && !panel.matches(':popover-open') ) panel.showPopover();
+        trigger.setAttribute('aria-expanded', 'true');
+        this._positionPanel(panel, trigger);
+        document.addEventListener('pointerdown', this.#onDocumentPointerDown, true);
+        window.addEventListener('resize', this.#onViewportChange);
+        window.addEventListener('scroll', this.#onViewportChange, true);
+    }
+
+    _closePanels ({ returnFocus = false } = {}) {
+        const open = this._openPanel();
+        for ( const panel of this.$$('.panel') ) {
+            if ( typeof panel.hidePopover === 'function' && panel.matches(':popover-open') ) panel.hidePopover();
+            panel.hidden = true;
+            this._triggerOf(panel).setAttribute('aria-expanded', 'false');
+        }
+        document.removeEventListener('pointerdown', this.#onDocumentPointerDown, true);
+        window.removeEventListener('resize', this.#onViewportChange);
+        window.removeEventListener('scroll', this.#onViewportChange, true);
+        if ( returnFocus && open ) {
+            const trigger = this._triggerOf(open);
+            if ( ! trigger.hidden ) trigger.focus();
+        }
+    }
+
+    _positionOpenPanels () {
+        const panel = this._openPanel();
+        if ( panel ) this._positionPanel(panel, this._triggerOf(panel));
+    }
+
+    /** Right-aligns the panel under its trigger, inside the viewport, with the caret at the trigger. */
+    _positionPanel (panel, trigger) {
+        const rect = trigger.getBoundingClientRect();
+        // A trigger the page has hidden or laid out of view leaves nothing to hang from.
+        if ( !rect.width && !rect.height ) {
+            this._closePanels();
+            return;
+        }
+        const top = Math.round(rect.bottom + 10);
+        panel.style.setProperty('--panel-top', `${top}px`);
+        panel.style.top = `${top}px`;
+        const width = panel.offsetWidth;
+        const viewport = document.documentElement.clientWidth || window.innerWidth;
+        const left = Math.max(EDGE, Math.min(rect.right + EDGE - width, viewport - EDGE - width));
+        panel.style.left = `${Math.round(left)}px`;
+        const caret = rect.left + rect.width / 2 - left;
+        panel.style.setProperty('--caret-x', `${Math.round(Math.min(width - CARET_INSET, Math.max(CARET_INSET, caret)))}px`);
+    }
+
+    _openMenu () {
+        const menu = this.$('.menu');
+        this._showPanel(menu);
+        this.$('.menu-item').focus({ preventScroll: true });
+    }
+
+    /** Moves focus between menu items for an arrow, Home or End key; false for any other key. */
+    _moveMenuFocus (key) {
+        const items = [...this.$$('.menu .menu-item')];
+        const current = items.indexOf(this.shadowRoot.activeElement);
+        const last = items.length - 1;
+        const next = {
+            ArrowDown: current < 0 || current === last ? 0 : current + 1,
+            ArrowUp: current <= 0 ? last : current - 1,
+            Home: 0,
+            End: last,
+        }[key];
+        if ( next === undefined ) return false;
+        items[next].focus({ preventScroll: true });
+        return true;
+    }
+
+    _openApps () {
+        if ( ! this.#ready ) return;
+        if ( ! this.$('.apps-body iframe') ) this._mountApps();
+        const panel = this.$('.apps-panel');
+        this._showPanel(panel);
+        panel.focus({ preventScroll: true });
+    }
+
+    /** The app browser for the signed-in user, in the forced theme if any. */
+    _appsUrl () {
+        const url = new URL('/embed/apps', globalThis.puter.defaultGUIOrigin);
+        const hash = new URLSearchParams();
+        // The app browser shows the Puter session only to the user named here.
+        const uuid = this._signedIn() && this.#token === globalThis.puter.authToken ? this.#user?.uuid : null;
+        if ( typeof uuid === 'string' && uuid ) hash.set('user', uuid);
+        const theme = this._forcedTheme();
+        if ( theme ) hash.set('theme', theme);
+        url.hash = hash.toString();
+        return url.href;
+    }
+
+    _mountApps () {
+        const body = this.$('.apps-body');
+        const frame = document.createElement('iframe');
+        frame.title = this._label('apps-label');
+        // The app browser allows a framing page it can name from the referrer.
+        frame.setAttribute('referrerpolicy', 'origin');
+        frame.style.colorScheme = this._colorScheme();
+        body.classList.add('is-loading');
+        frame.addEventListener('load', () => body.classList.remove('is-loading'), { once: true });
+        frame.src = this._appsUrl();
+        body.append(frame);
+    }
+
+    /** Discards the app browser, so the next open loads it for whoever is signed in then. */
+    _dropApps () {
+        this.$('.apps-body iframe')?.remove();
+        this.$('.apps-body').classList.remove('is-loading');
+    }
+
+    // -- Sign-in --
+
+    _signIn () {
+        if ( this.#signingIn ) return;
+        const puter = globalThis.puter;
+        // A cross-origin isolated page can't see its popup close, so it could never retry.
+        this.#signingIn = !globalThis.crossOriginIsolated;
+        // Called inside the click, so the sign-in popup isn't blocked.
+        puter.auth.signIn().then(
+            async () => {
+                this.#signingIn = false;
+                const user = await Promise.resolve(puter.whoamiCache_).catch(() => null);
+                this.emitEvent('signin', { user: user && typeof user === 'object' ? user : null });
+            },
+            () => {
+                // Closed or refused; the button stays for another try.
+                this.#signingIn = false;
+            },
+        );
+    }
+
+    _sendFeedback () {
+        this._closePanels();
+        void globalThis.puter.ui.showFeedbackDialog();
+    }
+
+    async _signOut () {
+        this.#focusSignIn = Boolean(this.shadowRoot.activeElement);
+        this._closePanels();
+        try {
+            await globalThis.puter.auth.signOut();
+        } finally {
+            this.#focusSignIn = false;
+            // The token goes before the sign-out settles, even when it rejects.
+            if ( ! globalThis.puter.authToken ) this.emitEvent('signout');
+        }
+    }
+}
+
+export default PuterUserMenu;

src/puter-js/src/ui/components/PuterUserMenu.test.js

@@ -0,0 +1,534 @@
+// @vitest-environment jsdom
+// @vitest-environment-options {"url": "https://notes.puter.com/sheet"}
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import PuterUserMenu from './PuterUserMenu.js';
+
+const USER = { username: 'jelveh', uuid: '0b1c9a52-3f0e-4c7a-9a65-2f6d1e8b7c40', email: '[email protected]' };
+const OTHER = { username: 'sam', uuid: '7d2e4f10-8a3b-4c5d-9e6f-0a1b2c3d4e5f' };
+const TEMP = { username: 'quiet_otter_42', uuid: '5c4b3a29-1807-4f6e-9d5c-4b3a29180716', is_temp: true };
+const PICTURE = 'data:image/png;base64,iVBORw0KGgo=';
+// Where a trigger sits in the toolbar; jsdom lays nothing out.
+const TRIGGER_RECT = { left: 800, right: 836, top: 10, bottom: 46, width: 36, height: 36, x: 800, y: 10 };
+
+/** The SDK instance the component reads, holding one signed-in state at a time. */
+const fakePuter = ({ token = null, user = null, picture = null } = {}) => {
+    const listeners = new Set();
+    let currentPicture = picture;
+    const sdk = {
+        env: 'web',
+        defaultGUIOrigin: 'https://puter.com',
+        APIOrigin: 'https://api.puter.com',
+        authToken: token,
+        whoamiCache_: Promise.resolve(user),
+        onAuthStateChanged: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        ui: {
+            showFeedbackDialog: vi.fn(() => new Promise(() => {})),
+        },
+        auth: {
+            getProfilePicture: vi.fn(async () => currentPicture),
+            signIn: vi.fn(() => new Promise(() => {})),
+            signOut: vi.fn(async () => sdk.signInAs(null)),
+        },
+        // In the SDK's order: listeners hear of the token before its whoami starts.
+        signInAs (nextToken, nextUser = null, nextPicture = null) {
+            sdk.authToken = nextToken;
+            sdk.whoamiCache_ = null;
+            currentPicture = nextPicture;
+            for ( const listener of listeners ) listener();
+            sdk.whoamiCache_ = Promise.resolve(nextUser);
+        },
+        listenerCount: () => listeners.size,
+    };
+    return sdk;
+};
+
+const settle = async () => {
+    for ( let i = 0; i < 5; i++ ) await new Promise(resolve => setTimeout(resolve, 0));
+};
+
+const mount = async (attributes = {}) => {
+    const el = document.createElement('puter-user-menu');
+    for ( const [name, value] of Object.entries(attributes) ) el.setAttribute(name, value);
+    document.body.appendChild(el);
+    await settle();
+    return el;
+};
+
+const part = (el, selector) => el.shadowRoot.querySelector(selector);
+const shown = (el, selector) => {
+    const node = part(el, selector);
+    return Boolean(node) && !node.closest('[hidden]');
+};
+const frameOf = el => part(el, '.apps-body iframe');
+const appsOpen = el => shown(el, '.apps-panel');
+
+beforeAll(() => {
+    if ( ! customElements.get('puter-user-menu') ) customElements.define('puter-user-menu', PuterUserMenu);
+});
+
+beforeEach(() => {
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue(TRIGGER_RECT);
+});
+
+afterEach(() => {
+    document.body.innerHTML = '';
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+});
+
+describe('<puter-user-menu>', () => {
+    it.each(['app', 'gui'])('renders nothing in the %s environment', async (env) => {
+        vi.stubGlobal('puter', { ...fakePuter({ token: 't', user: USER }), env });
+        const el = await mount();
+        expect(shown(el, '.bar')).toBe(false);
+        expect(puter.listenerCount()).toBe(0);
+    });
+
+    it('offers sign-in and the signed-out app browser when signed out', async () => {
+        vi.stubGlobal('puter', fakePuter());
+        const el = await mount();
+        expect(shown(el, '.sign-in')).toBe(true);
+        expect(shown(el, '.avatar')).toBe(false);
+        expect(shown(el, '.apps-button')).toBe(true);
+
+        part(el, '.apps-button').click();
+        expect(appsOpen(el)).toBe(true);
+        expect(frameOf(el).src).toBe('https://puter.com/embed/apps');
+        expect(frameOf(el).getAttribute('referrerpolicy')).toBe('origin');
+    });
+
+    it('treats a temporary account as signed out', async () => {
+        const sdk = fakePuter({ token: 'temp-token', user: TEMP, picture: PICTURE });
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        expect(shown(el, '.sign-in')).toBe(true);
+        expect(shown(el, '.avatar')).toBe(false);
+        expect(sdk.auth.getProfilePicture).not.toHaveBeenCalled();
+        part(el, '.apps-button').click();
+        expect(frameOf(el).src).toBe('https://puter.com/embed/apps');
+    });
+
+    it('signs in from the button and reports the user', async () => {
+        const sdk = fakePuter();
+        sdk.auth.signIn.mockImplementation(async () => {
+            sdk.signInAs('app-token', USER);
+            return { success: true };
+        });
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        const signins = [];
+        el.addEventListener('signin', event => signins.push(event.detail));
+        part(el, '.sign-in').click();
+        expect(sdk.auth.signIn).toHaveBeenCalledTimes(1);
+        await settle();
+        expect(signins).toEqual([{ user: USER }]);
+        expect(shown(el, '.avatar')).toBe(true);
+    });
+
+    it('opens one sign-in at a time, and another once it is closed', async () => {
+        const sdk = fakePuter();
+        let close;
+        sdk.auth.signIn.mockImplementation(() => new Promise((_resolve, reject) => {
+            close = reject;
+        }));
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        part(el, '.sign-in').click();
+        part(el, '.sign-in').click();
+        expect(sdk.auth.signIn).toHaveBeenCalledTimes(1);
+
+        close({ error: 'auth_window_closed' });
+        await settle();
+        part(el, '.sign-in').click();
+        expect(sdk.auth.signIn).toHaveBeenCalledTimes(2);
+    });
+
+    it('lets a cross-origin isolated page start another sign-in, since it cannot see the popup close', async () => {
+        vi.stubGlobal('crossOriginIsolated', true);
+        const sdk = fakePuter();
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        part(el, '.sign-in').click();
+        part(el, '.sign-in').click();
+        expect(sdk.auth.signIn).toHaveBeenCalledTimes(2);
+    });
+
+    it('shows the signed-in user and names them to the app browser', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        expect(shown(el, '.sign-in')).toBe(false);
+        expect(part(el, '.avatar').textContent).toBe('J');
+        expect(part(el, '.avatar').querySelector('img')).toBeNull();
+        expect(part(el, '.avatar').getAttribute('aria-label')).toBe('Account: jelveh');
+
+        part(el, '.avatar').click();
+        expect(shown(el, '.menu')).toBe(true);
+        expect(part(el, '.avatar').getAttribute('aria-expanded')).toBe('true');
+        expect(part(el, '.menu-username').textContent).toBe('jelveh');
+        expect(part(el, '.menu-email').textContent).toBe(USER.email);
+        expect(shown(el, '.menu-email')).toBe(true);
+        expect(part(el, '.menu-avatar').textContent).toBe('J');
+
+        part(el, '.apps-button').click();
+        expect(shown(el, '.menu')).toBe(false);
+        expect(appsOpen(el)).toBe(true);
+        expect(part(el, '.apps-button').getAttribute('aria-expanded')).toBe('true');
+        expect(frameOf(el).src).toBe(`https://puter.com/embed/apps#user=${USER.uuid}`);
+    });
+
+    it('links to the account, its usage and Puter, each in a new tab', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        part(el, '.avatar').click();
+        expect(el.shadowRoot.activeElement).toBe(part(el, '.manage-account'));
+        const links = [...el.shadowRoot.querySelectorAll('.menu a.menu-item')].map(link => ({
+            label: link.textContent,
+            href: link.href,
+            target: link.target,
+            rel: link.rel,
+        }));
+        expect(links).toEqual([
+            { label: 'Manage account', href: 'https://puter.com/dashboard/#account', target: '_blank', rel: 'noopener' },
+            { label: 'Usage', href: 'https://puter.com/dashboard/#usage', target: '_blank', rel: 'noopener' },
+            { label: 'Open Puter', href: 'https://puter.com/', target: '_blank', rel: 'noopener' },
+        ]);
+
+        part(el, '.usage').dispatchEvent(new MouseEvent('click', { cancelable: true }));
+        expect(shown(el, '.menu')).toBe(false);
+    });
+
+    it('hides the email line when the account has none to show', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: OTHER }));
+        const el = await mount();
+        part(el, '.avatar').click();
+        expect(part(el, '.menu-username').textContent).toBe('sam');
+        expect(shown(el, '.menu-email')).toBe(false);
+    });
+
+    it('shows the profile picture in the menu header too', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER, picture: PICTURE }));
+        const el = await mount();
+        expect(part(el, '.menu-avatar img').getAttribute('src')).toBe(PICTURE);
+        expect(part(el, '.menu-avatar').textContent).toBe('J');
+    });
+
+    it('opens the feedback dialog from the menu', async () => {
+        const sdk = fakePuter({ token: 'app-token', user: USER });
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        part(el, '.avatar').click();
+        part(el, '.feedback').click();
+        expect(sdk.ui.showFeedbackDialog).toHaveBeenCalledTimes(1);
+        expect(shown(el, '.menu')).toBe(false);
+    });
+
+    it('moves focus through the menu with the arrow, Home and End keys', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        part(el, '.avatar').click();
+        const press = (key) => {
+            const event = new KeyboardEvent('keydown', { key, bubbles: true, composed: true, cancelable: true });
+            el.shadowRoot.activeElement.dispatchEvent(event);
+            return event;
+        };
+        const focused = () => el.shadowRoot.activeElement.classList[1];
+
+        expect(focused()).toBe('manage-account');
+        expect(press('ArrowDown').defaultPrevented).toBe(true);
+        expect(focused()).toBe('usage');
+        press('End');
+        expect(focused()).toBe('sign-out');
+        press('ArrowDown');
+        expect(focused()).toBe('manage-account');
+        press('ArrowUp');
+        expect(focused()).toBe('sign-out');
+        press('ArrowUp');
+        expect(focused()).toBe('feedback');
+        press('Home');
+        expect(focused()).toBe('manage-account');
+        expect(press('a').defaultPrevented).toBe(false);
+        expect(shown(el, '.menu')).toBe(true);
+    });
+
+    it('hangs the panel under its button with the caret pointing at it', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        part(el, '.apps-button').click();
+        const panel = part(el, '.apps-panel');
+        expect(panel.style.top).toBe('56px');
+        expect(panel.style.getPropertyValue('--panel-top')).toBe('56px');
+        expect(panel.style.left).not.toBe('');
+        expect(panel.style.getPropertyValue('--caret-x')).not.toBe('');
+    });
+
+    it('closes the panel when its button is laid out of view', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        HTMLElement.prototype.getBoundingClientRect.mockReturnValue({ left: 0, right: 0, top: 0, bottom: 0, width: 0, height: 0 });
+        part(el, '.apps-button').click();
+        expect(appsOpen(el)).toBe(false);
+    });
+
+    it('shows a spinner until the app browser loads', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        part(el, '.apps-button').click();
+        expect(part(el, '.apps-body').classList.contains('is-loading')).toBe(true);
+        frameOf(el).dispatchEvent(new Event('load'));
+        expect(part(el, '.apps-body').classList.contains('is-loading')).toBe(false);
+    });
+
+    it('keeps the app browser between opens', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        part(el, '.apps-button').click();
+        const frame = frameOf(el);
+        part(el, '.apps-close').click();
+        expect(appsOpen(el)).toBe(false);
+        expect(el.shadowRoot.activeElement).toBe(part(el, '.apps-button'));
+        part(el, '.apps-button').click();
+        expect(appsOpen(el)).toBe(true);
+        expect(frameOf(el)).toBe(frame);
+    });
+
+    it('shows the profile picture over the initial when there is one', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER, picture: PICTURE }));
+        const el = await mount();
+        const img = part(el, '.avatar img');
+        expect(img.getAttribute('src')).toBe(PICTURE);
+        expect(img.alt).toBe('');
+        expect(part(el, '.avatar').textContent).toBe('J');
+    });
+
+    it('shows the account while its picture is still loading', async () => {
+        const sdk = fakePuter({ token: 'app-token', user: USER });
+        let resolvePicture;
+        sdk.auth.getProfilePicture.mockImplementation(() => new Promise(resolve => { resolvePicture = resolve; }));
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        expect(shown(el, '.avatar')).toBe(true);
+        expect(shown(el, '.apps-button')).toBe(true);
+        expect(part(el, '.avatar').textContent).toBe('J');
+        expect(part(el, '.avatar img')).toBeNull();
+
+        resolvePicture(PICTURE);
+        await settle();
+        expect(part(el, '.avatar img').getAttribute('src')).toBe(PICTURE);
+    });
+
+    it('drops a picture that arrives after the sign-in changed', async () => {
+        const sdk = fakePuter({ token: 'app-token', user: USER });
+        let resolvePicture;
+        sdk.auth.getProfilePicture.mockImplementationOnce(() => new Promise(resolve => { resolvePicture = resolve; }));
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        sdk.signInAs('other-token', OTHER);
+        await settle();
+        resolvePicture(PICTURE);
+        await settle();
+        expect(part(el, '.avatar').textContent).toBe('S');
+        expect(part(el, '.avatar img')).toBeNull();
+    });
+
+    it('sends no user when the signed-in user is unknown', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: null }));
+        const el = await mount();
+        expect(part(el, '.avatar').textContent).toBe('?');
+        part(el, '.apps-button').click();
+        expect(frameOf(el).src).toBe('https://puter.com/embed/apps');
+    });
+
+    it('drops the app browser and reloads when the sign-in changes', async () => {
+        const sdk = fakePuter({ token: 'app-token', user: USER });
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        part(el, '.apps-button').click();
+        part(el, '.apps-close').click();
+
+        sdk.signInAs('other-token', OTHER);
+        expect(appsOpen(el)).toBe(false);
+        expect(frameOf(el)).toBeNull();
+        await settle();
+        expect(part(el, '.avatar').textContent).toBe('S');
+        part(el, '.apps-button').click();
+        expect(frameOf(el).src).toBe(`https://puter.com/embed/apps#user=${OTHER.uuid}`);
+    });
+
+    it('keeps the app browser open when the same token is set again', async () => {
+        const sdk = fakePuter({ token: 'app-token', user: USER });
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        part(el, '.apps-button').click();
+        const frame = frameOf(el);
+        sdk.signInAs('app-token', USER);
+        expect(appsOpen(el)).toBe(true);
+        expect(frameOf(el)).toBe(frame);
+    });
+
+    it('ignores a user that arrives after the token changed', async () => {
+        const sdk = fakePuter({ token: 'app-token' });
+        let resolveFirst;
+        sdk.whoamiCache_ = new Promise(resolve => {
+            resolveFirst = resolve;
+        });
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        sdk.signInAs(null);
+        resolveFirst(USER);
+        await settle();
+        expect(shown(el, '.sign-in')).toBe(true);
+        part(el, '.apps-button').click();
+        expect(frameOf(el).src).toBe('https://puter.com/embed/apps');
+    });
+
+    it('signs out from the menu, reports it and drops the user', async () => {
+        const sdk = fakePuter({ token: 'app-token', user: USER });
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        const signouts = [];
+        el.addEventListener('signout', () => signouts.push(true));
+        part(el, '.apps-button').click();
+        part(el, '.avatar').click();
+        part(el, '.sign-out').click();
+        await settle();
+        expect(sdk.auth.signOut).toHaveBeenCalledTimes(1);
+        expect(signouts).toHaveLength(1);
+        expect(frameOf(el)).toBeNull();
+        expect(shown(el, '.menu')).toBe(false);
+        expect(shown(el, '.sign-in')).toBe(true);
+    });
+
+    it('hides the app browser on a page that may not frame it', async () => {
+        vi.stubGlobal('puter', { ...fakePuter(), defaultGUIOrigin: 'https://example.com' });
+        const el = await mount();
+        expect(shown(el, '.sign-in')).toBe(true);
+        expect(shown(el, '.apps-button')).toBe(false);
+    });
+
+    it('follows the OS theme unless told otherwise, in the app browser too', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        part(el, '.apps-button').click();
+        expect(frameOf(el).style.colorScheme).toBe('light');
+
+        expect(frameOf(el).src).toBe(`https://puter.com/embed/apps#user=${USER.uuid}`);
+
+        // The forced theme is in the URL, since not every browser passes `color-scheme` on.
+        el.setAttribute('theme', 'dark');
+        await settle();
+        expect(el.classList.contains('puter-theme-dark')).toBe(true);
+        expect(frameOf(el).style.colorScheme).toBe('dark');
+        expect(frameOf(el).src).toBe(`https://puter.com/embed/apps#user=${USER.uuid}&theme=dark`);
+        expect(appsOpen(el)).toBe(true);
+        expect(part(el, '.apps-body').classList.contains('is-loading')).toBe(true);
+    });
+
+    it('opens a new app browser in the forced theme', async () => {
+        vi.stubGlobal('puter', fakePuter());
+        const el = await mount({ theme: 'light' });
+        part(el, '.apps-button').click();
+        expect(frameOf(el).style.colorScheme).toBe('light');
+        expect(frameOf(el).src).toBe('https://puter.com/embed/apps#theme=light');
+    });
+
+    it('keeps a closed app browser until the theme changes, then loads it in the new theme', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount({ theme: 'light' });
+        part(el, '.apps-button').click();
+        const frame = frameOf(el);
+        part(el, '.apps-close').click();
+        el.setAttribute('theme', 'light');
+        await settle();
+        expect(frameOf(el)).toBe(frame);
+
+        el.setAttribute('theme', 'dark');
+        await settle();
+        expect(frameOf(el)).toBeNull();
+        expect(appsOpen(el)).toBe(false);
+        part(el, '.apps-button').click();
+        expect(frameOf(el).src).toBe(`https://puter.com/embed/apps#user=${USER.uuid}&theme=dark`);
+    });
+
+    it('exposes parts for the host to style', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        const parts = [...el.shadowRoot.querySelectorAll('[part]')].map(node => node.getAttribute('part'));
+        expect(parts.sort()).toEqual(['apps-button', 'apps-panel', 'avatar', 'menu', 'sign-in']);
+    });
+
+    it('uses label attributes, including ones changed later', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount({
+            'apps-label': 'Applis',
+            'sign-out-label': 'Déconnexion',
+            'account-label': 'Compte',
+            'manage-account-label': 'Gérer le compte',
+            'usage-label': 'Utilisation',
+            'open-puter-label': 'Ouvrir Puter',
+            'feedback-label': 'Envoyer un avis',
+        });
+        expect(part(el, '.apps-button').getAttribute('aria-label')).toBe('Applis');
+        expect(part(el, '.apps-title').textContent).toBe('Applis');
+        expect(part(el, '.apps-panel').getAttribute('aria-label')).toBe('Applis');
+        expect(part(el, '.sign-out').textContent).toBe('Déconnexion');
+        expect(part(el, '.avatar').getAttribute('aria-label')).toBe('Compte: jelveh');
+        expect(part(el, '.manage-account').textContent).toBe('Gérer le compte');
+        expect(part(el, '.usage').textContent).toBe('Utilisation');
+        expect(part(el, '.open-puter').textContent).toBe('Ouvrir Puter');
+        expect(part(el, '.feedback').textContent).toBe('Envoyer un avis');
+        expect(part(el, '.manage-account .menu-external')).not.toBeNull();
+
+        el.setAttribute('close-label', 'Fermer');
+        el.setAttribute('sign-in-label', 'Connexion');
+        expect(part(el, '.apps-close').getAttribute('aria-label')).toBe('Fermer');
+        expect(part(el, '.sign-in').textContent).toBe('Connexion');
+        el.removeAttribute('apps-label');
+        expect(part(el, '.apps-title').textContent).toBe('Apps');
+    });
+
+    it.each([['.avatar', '.menu'], ['.apps-button', '.apps-panel']])(
+        'closes %s\'s panel on Escape and returns focus to it', async (trigger, panel) => {
+            vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+            const el = await mount();
+            part(el, trigger).click();
+            part(el, panel).dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, composed: true }));
+            expect(shown(el, panel)).toBe(false);
+            expect(el.shadowRoot.activeElement).toBe(part(el, trigger));
+        },
+    );
+
+    it.each([['.avatar', '.menu'], ['.apps-button', '.apps-panel']])(
+        'closes %s\'s panel on a press outside it, and not on one inside', async (trigger, panel) => {
+            vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+            const el = await mount();
+            part(el, trigger).click();
+            part(el, panel).dispatchEvent(new Event('pointerdown', { bubbles: true, composed: true }));
+            expect(shown(el, panel)).toBe(true);
+            document.body.dispatchEvent(new Event('pointerdown', { bubbles: true, composed: true }));
+            expect(shown(el, panel)).toBe(false);
+        },
+    );
+
+    it('toggles a panel closed from its own button', async () => {
+        vi.stubGlobal('puter', fakePuter({ token: 'app-token', user: USER }));
+        const el = await mount();
+        part(el, '.apps-button').click();
+        part(el, '.apps-button').click();
+        expect(appsOpen(el)).toBe(false);
+        expect(frameOf(el)).not.toBeNull();
+    });
+
+    it('stops following the sign-in once removed', async () => {
+        const sdk = fakePuter({ token: 'app-token', user: USER });
+        vi.stubGlobal('puter', sdk);
+        const el = await mount();
+        part(el, '.apps-button').click();
+        el.remove();
+        expect(sdk.listenerCount()).toBe(0);
+        expect(frameOf(el)).toBeNull();
+        expect(appsOpen(el)).toBe(false);
+    });
+});

src/puter-js/src/ui/registerComponents.js

@@ -11,6 +11,7 @@ import PuterSpinner from './components/PuterSpinner.js';
 import PuterMenubar from './components/PuterMenubar.js';
 import PuterColorPicker from './components/PuterColorPicker.js';
 import PuterFontPicker from './components/PuterFontPicker.js';
+import PuterUserMenu from './components/PuterUserMenu.js';
 
 const components = [
     ['puter-alert', PuterAlert],
@@ -21,6 +22,7 @@ const components = [
     ['puter-menubar', PuterMenubar],
     ['puter-color-picker', PuterColorPicker],
     ['puter-font-picker', PuterFontPicker],
+    ['puter-user-menu', PuterUserMenu],
 ];
 
 export function registerComponents () {

src/puter-js/tests/api/realtime/realtime.test.ts

@@ -6,7 +6,7 @@ import WebSocket, { WebSocketServer } from 'ws';
 import type { AddressInfo } from 'node:net';
 import { loadNodePuter, closeNodePuter } from '../harness/nodeSdkLoader';
 import type { EnvManifest, PuterSDK } from '../harness/types';
-import type { Conversation } from '../../../types/modules/ai/convo';
+import type { Conversation } from '../../../types/modules/ai/realtime';
 import type { RealtimeServerEvent } from '../../../types/modules/ai/types';
 import {
     setupPuterTestEnv,
@@ -14,7 +14,7 @@ import {
 } from '@heyputer/backend/testUtil.ts';
 import type { IConfig } from '@heyputer/backend/types.ts';
 
-describe('convo built SDK and browser media', () => {
+describe('realtime built SDK and browser media', () => {
     let env: PuterTestEnv;
     let upstream: WebSocketServer;
     let puter: PuterSDK;
@@ -220,7 +220,7 @@ describe('convo built SDK and browser media', () => {
     it('resolves the original built SDK connect after an initial provider restart', async () => {
         upstreamRefusals = 1;
         const before = connections.length;
-        const conversation = await puter.ai.convo({ output: ['text'] });
+        const conversation = await puter.ai.realtime({ output: ['text'] });
         try {
             const ready = conversation.connect();
             expect(conversation.connect()).toBe(ready);
@@ -234,7 +234,7 @@ describe('convo built SDK and browser media', () => {
     });
 
     it('prepares, configures, sends, interrupts and truncates using the built SDK', async () => {
-        const conversation = await puter.ai.convo({
+        const conversation = await puter.ai.realtime({
             output: ['text'],
             turnDetection: false,
         });
@@ -283,13 +283,13 @@ describe('convo built SDK and browser media', () => {
             new URL('../../../dist/puter.js', import.meta.url),
             'utf8',
         );
-        await page.route('**/__convo_test__', (route) =>
+        await page.route('**/__realtime_test__', (route) =>
             route.fulfill({
                 contentType: 'text/html',
                 body: '<!doctype html><title>Conversation media test</title>',
             }),
         );
-        await page.goto(`${env.apiOrigin}/__convo_test__`);
+        await page.goto(`${env.apiOrigin}/__realtime_test__`);
         await page.evaluate(
             ({ origin, apiOrigin }) => {
                 Object.assign(globalThis, {
@@ -315,7 +315,7 @@ describe('convo built SDK and browser media', () => {
             };
             let c;
             try {
-                c = await sdk.ai.convo();
+                c = await sdk.ai.realtime();
             } catch (error) {
                 throw new Error(`prepare: ${JSON.stringify(error)}`);
             }
@@ -432,7 +432,7 @@ describe('convo built SDK and browser media', () => {
             { ...manifest, apiOrigin: proxyOrigin },
             env.users.user.token,
         );
-        const conversation = await dropping.ai.convo({ output: ['text'] });
+        const conversation = await dropping.ai.realtime({ output: ['text'] });
         const log = watch(conversation);
         try {
             await conversation.connect();
@@ -481,7 +481,7 @@ describe('convo built SDK and browser media', () => {
             { ...manifest, apiOrigin: proxyOrigin },
             env.users.user.token,
         );
-        const conversation = await dropping.ai.convo({ output: ['text'] });
+        const conversation = await dropping.ai.realtime({ output: ['text'] });
         const log = watch(conversation);
         const auth = vi.spyOn(env.server.services.auth, 'authenticate');
         const warn = vi.spyOn(console, 'warn');
@@ -524,7 +524,7 @@ describe('convo built SDK and browser media', () => {
             { ...manifest, apiOrigin: proxyOrigin },
             env.users.user.token,
         );
-        const conversation = await dropping.ai.convo({ output: ['text'] });
+        const conversation = await dropping.ai.realtime({ output: ['text'] });
         const log = watch(conversation);
         try {
             await conversation.connect();
@@ -564,7 +564,7 @@ describe('convo built SDK and browser media', () => {
     });
 
     it('moves to a new session when a restart is announced, restoring context', async () => {
-        const conversation = await puter.ai.convo({ output: ['text'] });
+        const conversation = await puter.ai.realtime({ output: ['text'] });
         const log = watch(conversation);
         try {
             await conversation.connect();
@@ -609,7 +609,7 @@ describe('convo built SDK and browser media', () => {
     });
 
     it('closes with invalid_event when Puter refuses a native event', async () => {
-        const conversation = await puter.ai.convo({ output: ['text'] });
+        const conversation = await puter.ai.realtime({ output: ['text'] });
         const log = watch(conversation);
         try {
             await conversation.connect();
@@ -646,13 +646,13 @@ describe('convo built SDK and browser media', () => {
         });
         const page = await browser.newPage();
         try {
-            await page.route('**/__convo_mic_test__', (route) =>
+            await page.route('**/__realtime_mic_test__', (route) =>
                 route.fulfill({
                     contentType: 'text/html',
                     body: '<!doctype html><title>Microphone reconnect test</title>',
                 }),
             );
-            await page.goto(`${env.apiOrigin}/__convo_mic_test__`);
+            await page.goto(`${env.apiOrigin}/__realtime_mic_test__`);
             // Through the proxy, so the test can drop the connection.
             await page.evaluate(
                 ({ origin, apiOrigin }) => {
@@ -695,7 +695,7 @@ describe('convo built SDK and browser media', () => {
                     tracks.push(...stream.getTracks());
                     return stream;
                 };
-                const c = await g.puter.ai.convo({ output: ['text'] });
+                const c = await g.puter.ai.realtime({ output: ['text'] });
                 const events: string[] = [];
                 c.on('*', (event) => events.push(event.type));
                 await c.connect();
@@ -800,7 +800,7 @@ describe('convo built SDK and browser media', () => {
             { ...manifest, apiOrigin: proxyOrigin },
             env.users.user.token,
         );
-        const conversation = await draining.ai.convo({ output: ['text'] });
+        const conversation = await draining.ai.realtime({ output: ['text'] });
         const log = watch(conversation);
         try {
             await conversation.connect();

src/puter-js/tests/api/realtime/realtimeLive.test.ts

@@ -2,7 +2,7 @@ import WebSocket from 'ws';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { closeNodePuter, loadNodePuter } from '../harness/nodeSdkLoader';
 import type { EnvManifest, PuterSDK } from '../harness/types';
-import type { Conversation } from '../../../types/modules/ai/convo';
+import type { Conversation } from '../../../types/modules/ai/realtime';
 import type { RealtimeServerEvent } from '../../../types/modules/ai/types';
 import { optionalEnv } from '@heyputer/backend/drivers/integrationTestUtil.ts';
 import {
@@ -146,7 +146,7 @@ describe.skipIf(!apiKey)('OpenAI realtime live relay', () => {
                 'batchIncrementUsages',
             );
             const startedAt = performance.now();
-            const session = await puter.ai.convo({
+            const session = await puter.ai.realtime({
                 ...(model ? { model } : {}),
                 output: ['text'],
                 instructions: 'Reply with exactly realtime-ok',
@@ -188,7 +188,7 @@ describe.skipIf(!apiKey)('OpenAI realtime live relay', () => {
                         .map((result) => result.value),
                 );
                 process.stdout.write(
-                    `[live convo] model=${model ?? 'default'} ready=${Math.round(readyAt - startedAt)}ms firstText=${Math.round(firstDeltaAt! - readyAt)}ms reply=${JSON.stringify(text)} metering=recorded\n`,
+                    `[live realtime] model=${model ?? 'default'} ready=${Math.round(readyAt - startedAt)}ms firstText=${Math.round(firstDeltaAt! - readyAt)}ms reply=${JSON.stringify(text)} metering=recorded\n`,
                 );
             } finally {
                 session.close();
@@ -199,7 +199,7 @@ describe.skipIf(!apiKey)('OpenAI realtime live relay', () => {
         45_000,
     );
     it('restores tool and text context on a new provider session after a restart notice', async () => {
-        const session = await puter.ai.convo({
+        const session = await puter.ai.realtime({
             output: ['text'],
             instructions: 'Answer in one short sentence.',
         });
@@ -272,7 +272,7 @@ describe.skipIf(!apiKey)('OpenAI realtime live relay', () => {
             expect(text.toLowerCase()).toContain('pineapple');
             expect(errors).toEqual([]);
             process.stdout.write(
-                `[live convo] context restored after reconnect, reply=${JSON.stringify(text)}\n`,
+                `[live realtime] context restored after reconnect, reply=${JSON.stringify(text)}\n`,
             );
         } finally {
             session.close();
@@ -281,7 +281,7 @@ describe.skipIf(!apiKey)('OpenAI realtime live relay', () => {
     }, 60_000);
 
     it('receives live PCM audio and interrupts the current response', async () => {
-        const c = await puter.ai.convo({
+        const c = await puter.ai.realtime({
             output: ['audio'],
             instructions: 'Count slowly from one to fifty.',
         });
@@ -301,7 +301,7 @@ describe.skipIf(!apiKey)('OpenAI realtime live relay', () => {
             const response = await done;
             expect(response.response).toMatchObject({ status: 'cancelled' });
             process.stdout.write(
-                '[live convo] PCM audio received, response canceled, playback history truncated\n',
+                '[live realtime] PCM audio received, response canceled, playback history truncated\n',
             );
         } finally {
             c.close();

src/puter-js/tests/api/suites/ai.suite.ts

@@ -1743,10 +1743,10 @@ export default suite('ai', {
         t.assert.equal(error.message, 'Input size cannot be larger than 25 MB');
     },
 
-    'convo streams a live text turn': {
+    'realtime streams a live text turn': {
         requires: ['ai.openai'],
         fn: async (t) => {
-            const conversation = await t.puter.ai.convo({ output: ['text'], instructions: 'Reply with exactly realtime-ok.' });
+            const conversation = await t.puter.ai.realtime({ output: ['text'], instructions: 'Reply with exactly realtime-ok.' });
             let text = '';
             conversation.on('text', ({ delta }) => { text += delta; });
             let timer: ReturnType<typeof setTimeout> | undefined;
@@ -1767,8 +1767,8 @@ export default suite('ai', {
         },
     },
 
-    'convo prepares and closes without opening a provider session': async (t) => {
-        const conversation = await t.puter.ai.convo({ output: ['text'] });
+    'realtime prepares and closes without opening a provider session': async (t) => {
+        const conversation = await t.puter.ai.realtime({ output: ['text'] });
         t.assert.equal(conversation.state, 'prepared');
         t.assert.equal(conversation.model, 'gpt-realtime-2.1-mini');
         let closed = 0;
@@ -1779,9 +1779,9 @@ export default suite('ai', {
         t.assert.equal(closed, 1);
     },
 
-    'convo rejects invalid options and sending before connect': async (t) => {
-        await t.assert.rejects(() => t.puter.ai.convo({ model: 'not-a-realtime-model' }));
-        const conversation = await t.puter.ai.convo({ output: ['text'] });
+    'realtime rejects invalid options and sending before connect': async (t) => {
+        await t.assert.rejects(() => t.puter.ai.realtime({ model: 'not-a-realtime-model' }));
+        const conversation = await t.puter.ai.realtime({ output: ['text'] });
         try {
             await t.assert.rejects(async () => conversation.sendText('Hello'));
         } finally {
@@ -1789,8 +1789,8 @@ export default suite('ai', {
         }
     },
 
-    'convo rejects interruption readiness through its Promise': async (t) => {
-        const conversation = await t.puter.ai.convo({ output: ['text'] });
+    'realtime rejects interruption readiness through its Promise': async (t) => {
+        const conversation = await t.puter.ai.realtime({ output: ['text'] });
         try {
             const prepared = conversation.interrupt();
             t.assert.equal(typeof prepared.then, 'function');
@@ -1804,9 +1804,9 @@ export default suite('ai', {
         }
     },
 
-    'convo is the realtime SDK entry point': async (t) => {
+    'realtime is the only realtime SDK entry point': async (t) => {
         t.assert.equal('assistant' in t.puter.ai, false);
         t.assert.equal('conversation' in t.puter.ai, false);
-        t.assert.equal(typeof t.puter.ai.convo, 'function');
+        t.assert.equal(typeof t.puter.ai.realtime, 'function');
     },
 });

src/puter-js/tests/api/suites/components.suite.ts

@@ -30,6 +30,7 @@ const COMPONENT_TAGS = [
     'puter-menubar',
     'puter-color-picker',
     'puter-font-picker',
+    'puter-user-menu',
 ];
 
 const raf = (): Promise<void> =>

src/puter-js/tests/e2e/specs/popupFrame.spec.js

@@ -0,0 +1,339 @@
+import { test, expect, devices } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PUTER_ORIGIN = process.env.PUTER_TEST_ORIGIN || 'http://puter.localhost:4100';
+const API_ORIGIN = PUTER_ORIGIN.replace('://', '://api.');
+// One label under the GUI origin: a first-party app page.
+const FIRST_PARTY = PUTER_ORIGIN.replace('://', '://notes.');
+const SDK = readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), '../../../dist/puter.dev.js'),
+    'utf8',
+);
+
+// Locally both origins are loopback, which Chromium's local network checks
+// refuse to frame from a page the test serves itself.
+test.use({
+    launchOptions: {
+        args: ['--disable-features=LocalNetworkAccessChecks,BlockInsecurePrivateNetworkRequests,PrivateNetworkAccessForNavigations'],
+    },
+});
+
+/** Opens the first-party page, serving it and the SDK from the test. */
+const openFirstPartyPage = async (page) => {
+    await page.context().route(`${FIRST_PARTY}/**`, (route) => {
+        if ( new URL(route.request().url()).pathname === '/sdk.js' ) {
+            return route.fulfill({ contentType: 'text/javascript', body: SDK });
+        }
+        return route.fulfill({
+            contentType: 'text/html',
+            body: `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><button id="go">Go</button>
+<script>window.PUTER_ORIGIN = ${JSON.stringify(PUTER_ORIGIN)}; window.PUTER_API_ORIGIN = ${JSON.stringify(API_ORIGIN)};</script>
+<script src="/sdk.js"></script>`,
+        });
+    });
+    await page.goto(`${FIRST_PARTY}/`);
+    await page.waitForFunction(() => !!window.puter);
+};
+
+/** Runs `expr` from a click on the page, settling into `window.__result`. */
+const runFromClick = async (page, expr) => {
+    await page.evaluate((expr) => {
+        window.__result = undefined;
+        document.getElementById('go').onclick = () => {
+            Promise.resolve().then(() => (0, eval)(expr)).then(
+                (value) => {
+                    window.__result = { ok: true, value: JSON.parse(JSON.stringify(value ?? null)) };
+                },
+                (error) => {
+                    window.__result = { ok: false, error: JSON.parse(JSON.stringify(error ?? null)) };
+                },
+            );
+        };
+    }, expr);
+    await page.click('#go');
+};
+const result = (page) => page.waitForFunction(() => window.__result, null, { timeout: 60_000 }).then((h) => h.jsonValue());
+
+const frame = (page) => page.frameLocator('dialog.puter-popup-frame iframe');
+const frameReady = (page) => page.locator('dialog.puter-popup-frame[open]:not(.is-loading)').waitFor({ timeout: 60_000 });
+
+/** The red channel of a screenshot of `clip`, row by row, decoded in the page. */
+const screenshotRed = async (page, clip) => {
+    const png = await page.screenshot({ clip });
+    return page.evaluate(async (base64) => {
+        const image = await createImageBitmap(await (await fetch(`data:image/png;base64,${base64}`)).blob());
+        const context = new OffscreenCanvas(image.width, image.height).getContext('2d');
+        context.drawImage(image, 0, 0);
+        const { data } = context.getImageData(0, 0, image.width, image.height);
+        return { width: image.width, red: Array.from(data.filter((_, i) => i % 4 === 0)) };
+    }, png.toString('base64'));
+};
+
+/** Waits for the box's fade-in to finish, so screenshots show it as it stays. */
+const boxSettled = (page) => page.waitForFunction(() =>
+    document.querySelector('.puter-popup-frame-box')?.getAnimations().length === 0);
+
+test.describe('popups a first-party page shows framed', () => {
+    test('signs in, then picks and saves files, without opening a window', async ({ page }) => {
+        // The admin's Puter session, and a file of theirs to pick.
+        await page.goto('/');
+        await page.waitForFunction(() => !!window.user?.username && !!window.puter?.authToken, null, { timeout: 60_000 });
+        const username = await page.evaluate(() => window.user.username);
+        await page.evaluate((u) => puter.fs.write(`/${u}/Desktop/popup-frame.txt`, 'framed'), username);
+
+        await openFirstPartyPage(page);
+        const popups = [];
+        page.on('popup', (p) => popups.push(p));
+
+        await runFromClick(page, 'puter.auth.signIn()');
+        await frameReady(page);
+        await frame(page).locator('.auth-dialog [data-screen="accounts"] button').first().click();
+        const signedIn = await result(page);
+        expect(signedIn.ok).toBe(true);
+        expect(signedIn.value).toMatchObject({ success: true, username });
+        await expect(page.locator('dialog.puter-popup-frame')).toHaveCount(0);
+
+        await runFromClick(page, 'puter.ui.showOpenFilePicker()');
+        await frameReady(page);
+        await frame(page).locator('.item[data-name="popup-frame.txt"]').dblclick();
+        const picked = await result(page);
+        expect(picked.value).toMatchObject({ name: 'popup-frame.txt' });
+        await expect(page.locator('dialog.puter-popup-frame')).toHaveCount(0);
+
+        // A name no earlier run left behind, so the save doesn't ask to replace it.
+        const suggestedName = `popup-frame-${Date.now()}.txt`;
+        await runFromClick(page, `puter.ui.showSaveFilePicker("saved in a frame", ${JSON.stringify(suggestedName)})`);
+        await frameReady(page);
+        await expect(frame(page).locator('.savefiledialog-filename')).toHaveValue(suggestedName);
+        // As in the popup, the name has focus with all but its extension
+        // selected, so typing renames it straight away.
+        const savedName = `renamed-${suggestedName}`;
+        await page.keyboard.type(savedName.replace(/\.txt$/, ''));
+        await expect(frame(page).locator('.savefiledialog-filename')).toHaveValue(savedName);
+        await frame(page).locator('.savefiledialog-save-btn').click();
+        const saved = await result(page);
+        expect(saved.value).toMatchObject({ name: savedName });
+
+        // Escape on the alert asking to replace that file goes back to the
+        // picker, as its Cancel does, rather than leaving it behind its mask.
+        await runFromClick(page, `puter.ui.showSaveFilePicker("again", ${JSON.stringify(savedName)}).undefinedOnCancel`);
+        await frameReady(page);
+        await frame(page).locator('.savefiledialog-save-btn').click();
+        await expect(frame(page).locator('.window-alert')).toHaveCount(1);
+        await page.keyboard.press('Escape');
+        await expect(frame(page).locator('.window-alert')).toHaveCount(0);
+        await expect(frame(page).locator('.window-filedialog .window-disable-mask')).toBeHidden();
+        await frame(page).getByRole('button', { name: 'Cancel' }).click();
+        expect(await result(page)).toEqual({ ok: true, value: null });
+
+        await runFromClick(page, 'puter.ui.showDirectoryPicker().undefinedOnCancel');
+        await frameReady(page);
+        await frame(page).getByRole('button', { name: 'Cancel' }).click();
+        expect(await result(page)).toEqual({ ok: true, value: null });
+
+        // Escape closes the picker, and the frame goes with it.
+        await runFromClick(page, 'puter.ui.showOpenFilePicker().undefinedOnCancel');
+        await frameReady(page);
+        await frame(page).locator('.window-filedialog').click({ position: { x: 5, y: 5 } });
+        await page.keyboard.press('Escape');
+        expect(await result(page)).toEqual({ ok: true, value: null });
+        await expect(page.locator('dialog.puter-popup-frame')).toHaveCount(0);
+
+        expect(popups).toHaveLength(0);
+    });
+
+    test('closing the framed sign-in rejects as closing its popup would', async ({ page }) => {
+        await openFirstPartyPage(page);
+        await page.evaluate(() => {
+            document.body.style.minHeight = '4000px';
+        });
+        await runFromClick(page, 'puter.auth.signIn()');
+        await frameReady(page);
+
+        // Scrolling over the scrim leaves the page behind it where it was.
+        await page.mouse.move(5, 300);
+        await page.mouse.wheel(0, 800);
+        await page.waitForTimeout(300);
+        expect(await page.evaluate(() => window.scrollY)).toBe(0);
+
+        await page.locator('.puter-popup-frame-close').click();
+        const closed = await result(page);
+        expect(closed).toMatchObject({ ok: false, error: { error: 'auth_window_closed' } });
+        await expect(page.locator('dialog.puter-popup-frame')).toHaveCount(0);
+    });
+
+    test('the page\'s own dialog, frame and button styles leave the framed sign-in as it is', async ({ page }) => {
+        await openFirstPartyPage(page);
+        await page.addStyleTag({
+            content: `dialog { top: 50%; left: 50%; transform: translate(-50%, -50%); border-radius: 24px; }
+iframe { max-width: 420px; margin: 12px; }
+button { margin: 0 6px 8px 0; min-width: 88px; min-height: 44px; box-shadow: 0 1px 2px #000; }`,
+        });
+        await runFromClick(page, 'puter.auth.signIn()');
+        await frameReady(page);
+
+        const viewport = page.viewportSize();
+        const dialog = await page.locator('dialog.puter-popup-frame').boundingBox();
+        expect(dialog).toEqual({ x: 0, y: 0, width: viewport.width, height: viewport.height });
+        const box = await page.locator('.puter-popup-frame-box').boundingBox();
+        expect(await page.locator('.puter-popup-frame-box iframe').boundingBox()).toEqual(box);
+        const close = await page.locator('.puter-popup-frame-close').boundingBox();
+        expect([close.width, close.height]).toEqual([32, 32]);
+        expect(box.x + box.width - (close.x + close.width)).toBe(10);
+        await expect(page.locator('.puter-popup-frame-close')).toHaveCSS('box-shadow', 'none');
+    });
+
+    test.describe('in dark mode', () => {
+        test.use({ colorScheme: 'dark', deviceScaleFactor: 2 });
+
+        test('the framed sign-in\'s rounded corners show no light fringe', async ({ page }) => {
+            await openFirstPartyPage(page);
+            await runFromClick(page, 'puter.auth.signIn()');
+            await frameReady(page);
+            await boxSettled(page);
+
+            // The bottom-left corner: the dialog at the top right, the scrim
+            // at the bottom left, and the curve between them.
+            const box = await page.locator('.puter-popup-frame-box').boundingBox();
+            const { width, red } = await screenshotRed(page, { x: box.x, y: box.y + box.height - 12, width: 12, height: 12 });
+            const inside = red[width - 1];
+            const outside = red[red.length - width];
+            expect(Math.max(...red)).toBeLessThanOrEqual(Math.max(inside, outside) + 3);
+        });
+    });
+
+    test.describe('on a phone with a fractional pixel ratio', () => {
+        // A describe group can't switch browsers; the profile's is Chromium anyway.
+        const { defaultBrowserType: _browser, ...pixel7 } = devices['Pixel 7'];
+        test.use(pixel7);
+
+        test('the framed sign-in fills the screen with no line of scrim along its edge', async ({ page }) => {
+            await openFirstPartyPage(page);
+            await runFromClick(page, 'puter.auth.signIn()');
+            await frameReady(page);
+            await boxSettled(page);
+
+            // A column down the middle of the top: the white sign-in all the way up.
+            const { width } = page.viewportSize();
+            const { red } = await screenshotRed(page, { x: width / 2, y: 0, width: 1, height: 4 });
+            expect(red[0]).toBe(red[red.length - 1]);
+        });
+
+        test('the framed save picker keeps its file name and buttons on screen', async ({ page }) => {
+            await page.goto('/');
+            await page.waitForFunction(() => !!window.puter?.authToken, null, { timeout: 60_000 });
+            await openFirstPartyPage(page);
+            await runFromClick(page, 'puter.auth.signIn()');
+            await frameReady(page);
+            await frame(page).locator('.auth-dialog [data-screen="accounts"] button').first().click();
+            expect((await result(page)).ok).toBe(true);
+
+            await runFromClick(page, 'puter.ui.showSaveFilePicker("x", "a-long-suggested-file-name.txt")');
+            await frameReady(page);
+            const { width } = page.viewportSize();
+            for ( const control of ['.savefiledialog-filename', '.filedialog-cancel-btn', '.savefiledialog-save-btn'] ) {
+                const box = await frame(page).locator(control).boundingBox();
+                expect(box.x).toBeGreaterThanOrEqual(0);
+                expect(box.x + box.width).toBeLessThanOrEqual(width);
+            }
+        });
+    });
+
+    test.describe('on a small phone', () => {
+        const { defaultBrowserType: _browser, ...iPhoneSE } = devices['iPhone SE'];
+        test.use(iPhoneSE);
+
+        test('the framed open picker keeps its buttons on one line inside its bar', async ({ page }) => {
+            await page.goto('/');
+            await page.waitForFunction(() => !!window.puter?.authToken, null, { timeout: 60_000 });
+            await openFirstPartyPage(page);
+            await runFromClick(page, 'puter.auth.signIn()');
+            await frameReady(page);
+            await frame(page).locator('.auth-dialog [data-screen="accounts"] button').first().click();
+            expect((await result(page)).ok).toBe(true);
+
+            await runFromClick(page, 'puter.ui.showOpenFilePicker()');
+            await frameReady(page);
+            const bar = await frame(page).locator('.window-filedialog-prompt').boundingBox();
+            const cancel = await frame(page).locator('.filedialog-cancel-btn').boundingBox();
+            const open = await frame(page).locator('.openfiledialog-open-btn').boundingBox();
+            expect(open.y).toBe(cancel.y);
+            expect(open.x).toBeGreaterThan(cancel.x + cancel.width);
+            expect(open.y + open.height).toBeLessThan(bar.y + bar.height);
+
+            // With German's longer labels, the upload label gives way so both
+            // buttons stay whole on screen.
+            await frame(page).locator('.window-filedialog-prompt').evaluate((el) => {
+                el.querySelector('.window-filedialog-upload-here').lastChild.textContent = ' Hochladen';
+                el.querySelector('.filedialog-cancel-btn').textContent = 'Abbrechen';
+                el.querySelector('.openfiledialog-open-btn').textContent = 'Öffnen';
+            });
+            const germanOpen = await frame(page).locator('.openfiledialog-open-btn').boundingBox();
+            expect(germanOpen.x + germanOpen.width).toBeLessThanOrEqual(bar.x + bar.width);
+        });
+    });
+
+    test('a provider picked in the framed sign-in opens straight in the popup', async ({ page }) => {
+        await page.goto('/');
+        await page.waitForFunction(() => !!window.user?.username && !!window.puter?.authToken, null, { timeout: 60_000 });
+        const username = await page.evaluate(() => window.user.username);
+        // Offer Google, and stand in for its round trip: the provider returns
+        // the popup to the sign-in popup for the same attempt.
+        await page.context().route('**/auth/oidc/providers', (route) =>
+            route.fulfill({ contentType: 'application/json', body: JSON.stringify({ providers: ['google'] }) }));
+        let started = null;
+        await page.context().route('**/auth/oidc/google/start?*', (route) => {
+            started = new URL(route.request().url());
+            const back = new URL('/action/sign-in', PUTER_ORIGIN);
+            back.searchParams.set('embedded_in_popup', 'true');
+            back.searchParams.set('msg_id', started.searchParams.get('msg_id'));
+            return route.fulfill({ status: 302, headers: { location: back.href } });
+        });
+
+        await openFirstPartyPage(page);
+        const popups = [];
+        page.on('popup', (p) => popups.push(p));
+        await runFromClick(page, 'puter.auth.signIn()');
+        await frameReady(page);
+        const frameMsgId = await page.evaluate(() =>
+            new URLSearchParams(new URL(document.querySelector('dialog.puter-popup-frame iframe').src).hash.slice(1)).get('msg_id'));
+        await frame(page).locator('.auth-dialog [data-screen="accounts"]').waitFor();
+        await frame(page).locator('.auth-dialog .auth-to-login').click();
+        await frame(page).locator('.oidc-google-btn').click();
+
+        await expect.poll(() => popups.length).toBe(1);
+        await expect(page.locator('dialog.puter-popup-frame')).toHaveCount(0);
+        expect(started.origin + started.pathname).toBe(`${PUTER_ORIGIN}/auth/oidc/google/start`);
+        expect(started.searchParams.get('msg_id')).toBe(frameMsgId);
+        expect(started.searchParams.get('embedded_in_popup')).toBe('true');
+        expect(started.searchParams.get('opener_origin')).toBe(FIRST_PARTY);
+
+        const popup = popups[0];
+        await popup.locator('.auth-dialog [data-screen="accounts"] button').first().click();
+        const signedIn = await result(page);
+        expect(signedIn).toMatchObject({ ok: true, value: { success: true, username } });
+        expect(popups).toHaveLength(1);
+    });
+
+    test('a page signed in as someone else gets the picker popup', async ({ page }) => {
+        await page.goto('/');
+        await page.waitForFunction(() => !!window.puter?.authToken, null, { timeout: 60_000 });
+        await openFirstPartyPage(page);
+        await runFromClick(page, 'puter.auth.signIn()');
+        await frameReady(page);
+        await frame(page).locator('.auth-dialog [data-screen="accounts"] button').first().click();
+        await result(page);
+        // Name another user as the page's own, once sign-in's own whoami has landed.
+        await page.evaluate(async () => {
+            await puter.whoamiCache_;
+            puter.whoami = { uuid: '00000000-0000-4000-8000-000000000000' };
+        });
+
+        const popup = page.waitForEvent('popup', { timeout: 60_000 });
+        await runFromClick(page, 'puter.ui.showOpenFilePicker()');
+        expect(new URL((await popup).url()).pathname).toBe('/action/show-open-file-picker');
+        await expect(page.locator('dialog.puter-popup-frame')).toHaveCount(0);
+    });
+});