fix(explorer): close a folder's window when the folder is deleted, however it was opened

Windows opened by path, such as with Ctrl-click on a breadcrumb or sidebar
entry, never received the marker used to find a deleted folder's windows,
so they stayed open on a folder that no longer existed.

.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 }}

.github/workflows/puterjs-tests.yaml

@@ -176,7 +176,10 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
 
+      # Missing when the PR leg failed; `coverage (pr)` already reports that.
       - name: Download PR coverage
+        id: pr-coverage
+        continue-on-error: true
         uses: actions/download-artifact@v8
         with:
           name: puterjs-coverage-pr
@@ -186,6 +189,7 @@ jobs:
       # base run) — then report without the comparison column.
       - name: Download base coverage
         id: base-coverage
+        if: steps.pr-coverage.outcome == 'success'
         continue-on-error: true
         uses: actions/download-artifact@v8
         with:
@@ -193,7 +197,7 @@ jobs:
           path: coverage-base
 
       - name: Report coverage on PR
-        if: steps.base-coverage.outcome == 'success'
+        if: steps.pr-coverage.outcome == 'success' && steps.base-coverage.outcome == 'success'
         uses: davelosert/vitest-coverage-report-action@v2
         with:
           name: puter.js SDK
@@ -202,7 +206,7 @@ jobs:
           json-summary-compare-path: coverage-base/coverage-summary.json
 
       - name: Report coverage on PR (no base comparison)
-        if: steps.base-coverage.outcome != 'success'
+        if: steps.pr-coverage.outcome == 'success' && steps.base-coverage.outcome != 'success'
         uses: davelosert/vitest-coverage-report-action@v2
         with:
           name: puter.js SDK

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,182 @@ 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.
+
+## Upgrade
+
+`GET /embed/upgrade` is the deployment's upgrade dialog for a first-party page,
+served like the popups above: the GUI shell with the same framing rules, query
+redirect, exact-path redirect and `no-store`, naming the framing page as
+`gui_params.embed_host_origin`. It runs only when framed by an allowed page.
+
+puter.js frames it on a signed-in first-party page (the same pages as the
+pickers) for `puter.ui.requestUpgrade(details)`, and for the Upgrade button of
+the usage limit dialog a refused call shows there. Elsewhere both keep their
+behavior: inside an app `requestUpgrade()` asks the desktop, and on any other
+page the usage limit dialog opens the dashboard's upgrade page in a new tab.
+
+The frame covers the page with no box or close button, and the GUI page is
+transparent (`html.popup-frame-transparent`) so the dialog's own scrim covers
+the host. The frame allows `payment` as well as `otp-credentials`. Escape on the
+page is left to the dialog, since one there shouldn't drop a payment in
+progress. Its fragment names `user` (the page's signed-in user) and, when the
+refusal gave them, `reason` (`funds`, `subscription` or `storage`) and `method`.
+
+The GUI reports `unavailable` unless its session belongs to `user`, the account
+has no verification or password change waiting (which the frame couldn't be
+closed from), and the deployment defines `window.UIUpgradeAccount` with
+`UIUpgradeAccount.embeddable === true`. Otherwise it runs:
+
+```js
+new UIUpgradeAccount({ attribution: { appUid, reason, method }, onClose }).open_as_window();
+```
+
+`appUid` is the app the framing page's origin resolves to, never one the
+fragment names. `open_as_window()` resolves once the dialog shows, and the GUI
+then posts `ready`. While the page still hides the frame, which Chromium and
+WebKit lay out at 0x0, the GUI posts `ready` first and opens the dialog once
+the frame has a viewport, so a window it opens doesn't center on 0x0.
+`onClose({ upgraded })` must run exactly once, when the
+dialog closes or when it declines to open for the account; the GUI then posts
+`{ msg: 'puterPopupFrame', state: 'closed', upgraded }` and the page removes
+the frame. If `open_as_window()` rejects, the GUI posts `unavailable` instead. `requestUpgrade()` resolves `{ upgraded }`. A call made while the
+frame shows settles with it rather than replacing it, and a call refused while
+it shows still rejects but opens no usage limit dialog over it.
+
+When the frame can't show the upgrade (refused, never ready, `unavailable`, or
+no user to name), puter.js opens the dashboard's upgrade page in a new tab with
+what was refused, through a consent dialog when the click has expired or the
+tab is blocked, and `requestUpgrade()` resolves `{ upgraded: false }`.
+
+## Email confirmation
+
+`GET /embed/request-email-confirmation` walks a first-party page's user through
+confirming their email, served like the upgrade: the GUI shell with the same
+framing rules, redirects and `no-store`, run only when framed by an allowed
+page. puter.js frames it on a signed-in first-party page for
+`puter.ui.requestEmailConfirmation()`. Inside an app the desktop shows the same
+windows over the app instead.
+
+Like the upgrade, the frame covers the page with no box or close button, over a
+transparent GUI page, and its fragment names `user`. Escape closes it, on the
+page or on the save-account or code window. On a window, Escape closes that
+window as its close button does, so a code already sent still answers. The GUI
+reports `unavailable` unless its session belongs to `user` and the account has
+no phone, card or password check waiting.
+An email check is fine: the boot skips its own email gate for this action, so
+the user gets one code window they can close.
+
+The GUI then runs `ensureConfirmedEmail` (`src/gui/src/helpers/ensureConfirmedEmail.js`),
+which the desktop's handler uses too: a temporary account gets the save-account
+window first, then an unconfirmed email gets the code window, each at most
+once. When the page's whoami already reads the email as confirmed,
+`requestEmailConfirmation()` resolves `{ response: true }` without framing
+anything, and a confirmation in the frame marks that whoami confirmed for the
+calls after it. An email the GUI reads as confirmed shows nothing. Before
+opening a window the GUI waits for the frame to have a viewport, as the upgrade
+does. It then posts
+`{ msg: 'puterPopupFrame', state: 'closed', confirmed }`, and
+`requestEmailConfirmation()` resolves `{ response: confirmed }`, the field an
+app reads from the desktop's answer. A call made while the frame shows settles
+with it. A frame that is refused, never ready, or `unavailable` resolves
+`{ response: false }`, since there's no popup to fall back to.
+
+## 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 src/puter-js/src/modules/UI.requestUpgrade.test.js src/puter-js/src/lib/upgradePrompt.test.js src/puter-js/src/modules/UsageLimitDialog.upgrade.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/clients/event/types.ts

@@ -420,7 +420,11 @@ export type EventMap = {
         old_username: string;
         new_username: string;
     };
-    'user.email-changed': { user_id: number; new_email: string };
+    'user.email-changed': {
+        user_id: number;
+        old_email: string | null;
+        new_email: string;
+    };
     /** An account was suspended, or its suspension lifted. Local events. */
     'user.suspended': { userId: number };
     'user.unsuspended': { userId: number };

src/backend/clients/s3/S3Client.test.ts

@@ -21,6 +21,8 @@
 import { GetObjectCommand } from '@aws-sdk/client-s3';
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { existsSync } from 'node:fs';
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -200,6 +202,77 @@ describe('S3Client — remote endpoint configuration', () => {
     });
 });
 
+describe('S3Client — bucket in another region', () => {
+    let server: Server;
+    let client: S3Client;
+    let signedRegions: string[];
+
+    // Answers like a bucket that lives in us-west-2: a request signed for any
+    // other region gets S3's 301 naming the bucket's region.
+    beforeEach(async () => {
+        signedRegions = [];
+        server = createServer((req, res) => {
+            const region =
+                /Credential=[^/]+\/\d{8}\/([^/]+)\//.exec(
+                    req.headers.authorization ?? '',
+                )?.[1] ?? '';
+            signedRegions.push(region);
+            if (region !== 'us-west-2') {
+                res.writeHead(301, {
+                    'content-type': 'application/xml',
+                    'x-amz-bucket-region': 'us-west-2',
+                });
+                res.end(
+                    '<?xml version="1.0" encoding="UTF-8"?><Error><Code>PermanentRedirect</Code><Message>The bucket you are attempting to access must be addressed using the specified endpoint.</Message></Error>',
+                );
+                return;
+            }
+            res.writeHead(200, {
+                'content-type': 'text/plain',
+                'content-length': '5',
+            });
+            res.end('hello');
+        });
+        await new Promise<void>((resolve) =>
+            server.listen(0, '127.0.0.1', resolve),
+        );
+        const { port } = server.address() as AddressInfo;
+        client = new S3Client({
+            port: 0,
+            extensions: [],
+            s3: {
+                s3Config: {
+                    endpoint: `http://127.0.0.1:${port}`,
+                    accessKeyId: 'fakeAccessKeyId',
+                    secretAccessKey: 'fakeSecretAccessKey',
+                    forcePathStyle: true,
+                },
+            },
+        } as unknown as IConfig);
+        await client.onServerStart();
+    });
+
+    afterEach(async () => {
+        await client.onServerShutdown();
+        server.closeAllConnections();
+        await new Promise<void>((resolve) => server.close(() => resolve()));
+    });
+
+    it("retries a read in the bucket's region when S3 redirects it", async () => {
+        const result = await client
+            .get('ap-northeast-2')
+            .send(
+                new GetObjectCommand({
+                    Bucket: 'other-bucket',
+                    Key: 'index.html',
+                }),
+            );
+
+        expect(await result.Body?.transformToString()).toBe('hello');
+        expect(signedRegions).toEqual(['ap-northeast-2', 'us-west-2']);
+    });
+});
+
 describe('S3Client — legacy storage migration', () => {
     let client: S3Client;
     let dir: string;

src/backend/clients/s3/S3Client.ts

@@ -235,6 +235,9 @@ export class S3Client extends PuterClient {
 
         const client = new AwsS3Client({
             region,
+            // Rows without a stored region are read with the server's own, so
+            // retry where S3's 301 says the bucket actually lives.
+            followRegionRedirects: true,
             requestStreamBufferSize: 32 * 1024,
             requestHandler: new NodeHttpHandler({
                 socketTimeout: 5000,

src/backend/controllers/auth/AuthController.test.ts

@@ -7468,6 +7468,11 @@ describe('AuthController user-protected mutations (validation paths)', () => {
             { expiresIn: '1h' },
         );
 
+        const heard: Array<Record<string, unknown>> = [];
+        eventClient.on('user.email-changed', (_k, data) => {
+            heard.push(data as Record<string, unknown>);
+        });
+
         const req = makeReq({});
         (req as unknown as { query: Record<string, string> }).query = {
             token: linkJwt,
@@ -7475,6 +7480,11 @@ describe('AuthController user-protected mutations (validation paths)', () => {
         const res = makeRes();
         await controller.handleChangeEmailConfirm(req, res);
         expect(res.sent).toMatch(/Email changed successfully/);
+        expect(heard).toContainEqual({
+            user_id: user.id,
+            old_email: user.email ?? null,
+            new_email: newEmail,
+        });
 
         const after = await server.stores.user.getById(user.id, {
             force: true,

src/backend/controllers/auth/AuthController.ts

@@ -2647,6 +2647,7 @@ export class AuthController extends PuterController {
                 'user.email-changed' as never,
                 {
                     user_id: user.id,
+                    old_email: user.email ?? null,
                     new_email: newEmail,
                 } as never,
                 {},

src/backend/controllers/auth/oidcLoginReturn.ts

@@ -15,7 +15,6 @@ export interface OidcLoginContinuation {
     embeddedInPopup: boolean;
     openerOrigin: string | null;
     messageId: string | null;
-    switchedToLogin: boolean;
 }
 
 interface OidcReturnDeps {
@@ -56,7 +55,6 @@ export function completeOidcLoginReturn(
         data.userUuid !== user.uuid ||
         typeof data.redirectUri !== 'string' ||
         typeof data.embeddedInPopup !== 'boolean' ||
-        typeof data.switchedToLogin !== 'boolean' ||
         (data.openerOrigin !== null && typeof data.openerOrigin !== 'string') ||
         (data.messageId !== null && typeof data.messageId !== 'string')
     ) {
@@ -91,6 +89,5 @@ export function completeOidcLoginReturn(
             ),
         );
     }
-    if (data.switchedToLogin) append('oidc_switched', 'login');
     return target;
 }

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,24 @@ 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, plus the upgrade dialog,
+ * which it would otherwise open in a dashboard tab, and the email confirmation,
+ * which it otherwise can't show.
+ */
+export const FRAMED_POPUP_ACTIONS = [
+    'sign-in',
+    'show-open-file-picker',
+    'show-save-file-picker',
+    'show-directory-picker',
+    'upgrade',
+    'request-email-confirmation',
+] as const;
+
 /** Longest description/og:description/twitter:description on `/app/<name>`. */
 export const APP_META_DESCRIPTION_MAX = 150;
 
@@ -61,32 +77,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 +123,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 +169,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 +178,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 +206,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 +219,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/controllers/oidc/OIDCController.test.ts

@@ -1620,7 +1620,7 @@ describe('OIDCController signup callback', () => {
         expect(captured.redirectUrl).toContain('action=signup');
     });
 
-    it('creates a fresh user without oidc_switched on first signup', async () => {
+    it('creates a fresh user on first signup', async () => {
         const state = oidc().signState({
             provider: 'custom',
             redirect_uri: TEST_ORIGIN + '/',
@@ -1646,11 +1646,9 @@ describe('OIDCController signup callback', () => {
         );
         expect(captured.cookies).toHaveLength(1);
         expect(captured.redirectUrl).toBe(TEST_ORIGIN + '/');
-        // Fresh creation — must NOT advertise "you've actually been signed in".
-        expect(captured.redirectUrl).not.toContain('oidc_switched=login');
     });
 
-    it('adds oidc_switched=login when signup hits an already-linked account', async () => {
+    it('signs in to an already-linked account on signup, returning as a login would', async () => {
         // Seed an account linked on (provider, sub) so the signup callback
         // resolves to `linked-sub` rather than creating a new user.
         const sub = `sub-${Math.random().toString(36).slice(2, 8)}`;
@@ -1686,7 +1684,7 @@ describe('OIDCController signup callback', () => {
             res,
         );
         expect(captured.cookies).toHaveLength(1);
-        expect(captured.redirectUrl).toContain('oidc_switched=login');
+        expect(captured.redirectUrl).toBe(TEST_ORIGIN + '/');
     });
 
     it('redirects to action=signup with auth_error when user resolution fails (unconfirmed email)', async () => {

src/backend/controllers/oidc/OIDCController.ts

@@ -688,14 +688,7 @@ export class OIDCController extends PuterController {
                 );
             }
 
-            // If we landed on an existing account (either via the
-            // provider_sub or via email match), signal the GUI so it can
-            // render a "signed in" flow rather than "account created".
-            const extra =
-                resolved.origin === 'created'
-                    ? undefined
-                    : { oidc_switched: 'login' };
-            await this.#finishLogin(req, res, user, stateDecoded, extra);
+            await this.#finishLogin(req, res, user, stateDecoded);
         };
         router.get('/auth/oidc/callback/signup', cbOpts, signupCb);
         router.post('/auth/oidc/callback/signup', cbOpts, signupCb);
@@ -834,17 +827,14 @@ if (window.opener) {
         attempt = 0,
     ): Promise<
         | { error: string; code?: string; requestCode?: string }
-        | {
-              user: import('../../stores/user/UserStore.js').UserRow;
-              origin: 'linked-sub' | 'linked-email' | 'created';
-          }
+        | { user: import('../../stores/user/UserStore.js').UserRow }
     > {
         // 1. Existing provider/sub link.
         const linked = await this.services.oidc.findUserByProviderSub(
             provider,
             userinfo.sub,
         );
-        if (linked) return { user: linked, origin: 'linked-sub' };
+        if (linked) return { user: linked };
 
         // 2/3. Email match branch.
         const claimedEmail =
@@ -881,7 +871,7 @@ if (window.opener) {
                         error: outcome.error ?? 'Failed to link provider.',
                     };
                 }
-                return { user: byEmail, origin: 'linked-email' };
+                return { user: byEmail };
             }
         }
 
@@ -911,7 +901,7 @@ if (window.opener) {
                 requestCode: outcome.requestCode,
             };
         }
-        return { user: outcome.user, origin: 'created' };
+        return { user: outcome.user };
     }
 
     async #processCallback(
@@ -1000,7 +990,6 @@ if (window.opener) {
         res: Response,
         user: UserRow,
         stateDecoded: Record<string, unknown>,
-        extraQueryParams?: Record<string, string>,
     ): Promise<void> {
         const origin = (this.config.origin ?? '').replace(/\/$/, '');
         const continuation: OidcLoginContinuation = {
@@ -1018,7 +1007,6 @@ if (window.opener) {
                 stateDecoded.msg_id == null
                     ? null
                     : String(stateDecoded.msg_id),
-            switchedToLogin: extraQueryParams?.oidc_switched === 'login',
         };
         if (user.otp_enabled) {
             const challenge = this.services.token.sign(

src/backend/controllers/oidc/OIDCController.twoFactor.http.test.ts

@@ -139,7 +139,7 @@ describe('OIDC account second-factor login', () => {
             expect(await response.json()).toMatchObject({
                 proceed: true,
                 next_step: 'complete',
-                redirectUrl: `${env.origin}/dashboard${flow === 'signup' ? '?oidc_switched=login' : ''}`,
+                redirectUrl: `${env.origin}/dashboard`,
             });
             expect(
                 response.headers

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/drivers/ai-chat/ChatCompletionDriver.test.ts

@@ -2222,3 +2222,166 @@ describe('ChatCompletionDriver.countTokens', () => {
         ).rejects.toMatchObject({ statusCode: 400 });
     });
 });
+
+describe('ChatCompletionDriver service speed', () => {
+    it.each([
+        [{ serviceSpeed: 'ultrafast' }, 'fast', 0.028],
+        [{ speed: 'fast' }, 'fast', 0.028],
+        [{ serviceSpeed: 'standard', speed: 'fast' }, 'standard', 0.014],
+    ] as const)('uses the Claude catalog rate card for %j', async (options, speed, cents) => {
+        const sent: Record<string, unknown>[] = [];
+        vi.stubGlobal('fetch', async (input: Request | string, init?: RequestInit) => {
+            const body = input instanceof Request
+                ? await input.clone().json()
+                : JSON.parse(String(init?.body));
+            sent.push(body);
+            return new Response(JSON.stringify({
+                id: 'claude-speed-test', type: 'message', role: 'assistant',
+                model: body.model, stop_reason: 'end_turn',
+                content: [{ type: 'text', text: 'OK' }],
+                usage: { input_tokens: 10, output_tokens: 5, speed },
+            }), { headers: { 'content-type': 'application/json' } });
+        });
+        const d = new ChatCompletionDriver(
+            { providers: { claude: { apiKey: 'test-key' }, ollama: { enabled: false } } } as never,
+            server.clients, server.stores, server.services,
+        );
+        try {
+            await d.onServerStart();
+            const result = await withTestActor(() => d.complete({
+                model: 'claude-opus-5-5', provider: 'claude',
+                messages: [{ role: 'user', content: 'Hello' }],
+                fallback: false, max_tokens: 32, normalize: true, ...options,
+            }));
+            expect(sent).toHaveLength(1);
+            expect(sent[0]!.speed).toBe(speed === 'fast' ? 'fast' : undefined);
+            expect(result).toMatchObject({
+                message: { content: 'OK' }, usage: { usd_cents: cents },
+            });
+        } finally {
+            d.onServerShutdown();
+            vi.unstubAllGlobals();
+        }
+    });
+
+    it.each([
+        null, false, true, 0, 1, -1, NaN, Infinity, '', 'invalid', 'FAST',
+        'fast ', ' fast', 'ultraFast', [], ['fast'], {}, { speed: 'fast' },
+        { toString: 'fast' },
+    ])('rejects invalid speed %j before sending a request', async (serviceSpeed) => {
+        await expect(
+            withTestActor(() =>
+                driver.complete({
+                    model: 'fake',
+                    messages: [{ role: 'user', content: 'Hello' }],
+                    serviceSpeed: serviceSpeed as never,
+                }),
+            ),
+        ).rejects.toMatchObject({
+            statusCode: 400,
+            legacyCode: 'invalid_service_speed',
+        });
+    });
+
+    it.each([
+        ['openai-responses', true],
+        ['openai-responses', false],
+        ['openai-completion', false],
+    ] as const)(
+        'settles unavailable tiers at standard rates on %s with provider fallback disabled (admission rejection: %s)',
+        async (provider, rejectFast) => {
+            const sent: Record<string, unknown>[] = [];
+            vi.stubGlobal(
+                'fetch',
+                async (_input: unknown, init?: RequestInit) => {
+                    const body =
+                        _input instanceof Request
+                            ? await _input.clone().json()
+                            : JSON.parse(String(init?.body));
+                    sent.push(body);
+                    if (rejectFast && body.service_tier !== 'default') {
+                        return new Response(
+                            JSON.stringify({
+                                error: {
+                                    message: `${body.service_tier} service_tier capacity unavailable`,
+                                    type: 'invalid_request_error',
+                                },
+                            }),
+                            {
+                                status: 400,
+                                headers: { 'content-type': 'application/json' },
+                            },
+                        );
+                    }
+                    return new Response(
+                        JSON.stringify({
+                            id: 'response-test',
+                            object: 'response',
+                            model: body.model,
+                            status: 'completed',
+                            service_tier: 'default',
+                            output: [
+                                {
+                                    type: 'message',
+                                    role: 'assistant',
+                                    content: [
+                                        { type: 'output_text', text: 'OK' },
+                                    ],
+                                },
+                            ],
+                            usage: {
+                                input_tokens: 10,
+                                output_tokens: 2,
+                                input_tokens_details: { cached_tokens: 0 },
+                            },
+                        }),
+                        { headers: { 'content-type': 'application/json' } },
+                    );
+                },
+            );
+            const d = new ChatCompletionDriver(
+                {
+                    providers: {
+                        'openai-completion': { apiKey: 'test-key' },
+                        ollama: { enabled: false },
+                    },
+                } as never,
+                server.clients,
+                server.stores,
+                server.services,
+            );
+            try {
+                await d.onServerStart();
+                const result = (await withTestActor(() =>
+                    d.complete({
+                        model: 'gpt-6.1-sol',
+                        provider,
+                        messages: [{ role: 'user', content: 'Hello' }],
+                        serviceSpeed: 'ultrafast',
+                        fallback: false,
+                        max_tokens: 32,
+                        normalize: true,
+                    }),
+                )) as {
+                    message: { content: string };
+                    usageDetails: { serviceSpeed: string };
+                    usage: { usd_cents: number };
+                };
+                expect(sent.map((body) => body.service_tier)).toEqual(
+                    rejectFast
+                        ? ['ultrafast', 'priority', 'default']
+                        : ['ultrafast'],
+                );
+                expect(sent.every((body) => body.model === 'gpt-6.1-sol')).toBe(
+                    true,
+                );
+                expect(result.message.content).toBe('OK');
+                expect(result.usageDetails.serviceSpeed).toBe('standard');
+                expect(result.usage.usd_cents).toBeCloseTo(0.004, 8);
+            } finally {
+                d.onServerShutdown();
+                vi.unstubAllGlobals();
+            }
+        },
+    );
+});

src/backend/drivers/ai-chat/ChatCompletionDriver.ts

@@ -78,6 +78,11 @@ import type {
     UsageDetails,
 } from './types.js';
 import { normalize_tools_object } from './utils/FunctionCalling.js';
+import {
+    selectServiceSpeed,
+    lowerServiceSpeed,
+    isServiceSpeedUnavailable,
+} from './utils/serviceSpeed.js';
 import {
     messagesHavePuterPaths,
     modelSupportsModality,
@@ -674,6 +679,16 @@ export class ChatCompletionDriver extends PuterDriver {
     }
 
     async complete(args: ICompleteArguments): Promise<IChatCompleteResult> {
+        if (
+            args.serviceSpeed !== undefined &&
+            !['standard', 'fast', 'ultrafast'].includes(args.serviceSpeed)
+        ) {
+            throw new HttpError(
+                400,
+                'serviceSpeed must be standard, fast, or ultrafast',
+                { legacyCode: 'invalid_service_speed' },
+            );
+        }
         const abortSignal = Context.get('abortSignal');
         abortSignal?.throwIfAborted();
         const actor = Context.get('actor');
@@ -700,15 +715,16 @@ export class ChatCompletionDriver extends PuterDriver {
             args.model = this.#providers[intendedProvider].getDefaultModel();
         }
 
-        let model = await this.#resolveLoadedModel(
+        const initialModel = await this.#resolveLoadedModel(
             args.model,
             intendedProvider,
         );
-        if (!model) {
+        if (!initialModel) {
             throw new HttpError(400, `Model not found: ${args.model}`, {
                 legacyCode: 'bad_request',
             });
         }
+        let model: IChatModel = initialModel;
         // A pinned provider without a route for the model normally resolves
         // to another vendor; with `fallback: false` that is the one thing the
         // caller asked us not to do.
@@ -840,18 +856,6 @@ export class ChatCompletionDriver extends PuterDriver {
         // The instant the current attempt is priced at, from its hold to its
         // charge, so a rate change mid-request can't split the two.
         let pricingTime = new Date();
-        if (!useFakeProvider) {
-            ({
-                hold,
-                fundsCap,
-                costFactor,
-                promptTokenEstimate: attemptPromptTokenEstimate,
-            } = await this.#applyCreditGate(actor, model, args, {
-                promptTokenEstimate,
-                requestedMaxTokens,
-                pricingTime,
-            }));
-        }
 
         // First attempt
         const provider = this.#providers[model.provider!];
@@ -899,24 +903,134 @@ export class ChatCompletionDriver extends PuterDriver {
             return attempt;
         };
 
+        let variantSpeed: ICompleteArguments['serviceSpeed'];
+        let creditGateError: unknown;
         const runAttempt = async (
             attemptProvider: IChatProvider,
-            attemptModel: IChatModel,
+            baseModel: IChatModel,
         ) => {
-            if (!useFakeProvider) {
-                await this.#resolvePuterPaths(attemptProvider, args, actor);
-            }
-            // Last point where a caller who left costs nothing.
-            abortSignal?.throwIfAborted();
-            return attemptProvider.complete(
-                {
-                    ...args,
+            const offers =
+                args.serviceSpeed !== undefined &&
+                args.serviceSpeed !== 'standard'
+                    ? ((await attemptProvider.serviceSpeedModels?.(
+                          baseModel,
+                      )) ?? {})
+                    : {};
+            let requestedSpeed =
+                args.serviceSpeed ??
+                (baseModel.provider === 'claude' && args.speed === 'fast'
+                    ? 'fast'
+                    : undefined);
+            for (;;) {
+                const selection = selectServiceSpeed(
+                    baseModel,
+                    { ...args, serviceSpeed: requestedSpeed },
+                    (id) => {
+                        const variant = this.#resolveModel(
+                            id,
+                            baseModel.provider!,
+                        );
+                        return variant &&
+                            variant.provider === baseModel.provider
+                            ? variant
+                            : undefined;
+                    },
+                    offers,
+                );
+                const attemptModel = selection.model;
+                const requestArgs = {
+                    ...selection.args,
                     model: attemptModel.id,
                     provider: attemptModel.provider,
-                },
-                this.#catalogEntries.get(attemptModel),
-                pricingTime,
-            );
+                };
+                const catalogModel = this.#resolveModel(
+                    attemptModel.id,
+                    attemptModel.provider!,
+                );
+                const rawModel = this.#catalogEntries.get(
+                    catalogModel ?? baseModel,
+                );
+                const snapshot = rawModel
+                    ? {
+                          ...rawModel,
+                          costs: attemptModel.costs,
+                          pricingOverrides: attemptModel.pricingOverrides,
+                          serviceSpeedPricing: attemptModel.serviceSpeedPricing,
+                      }
+                    : attemptModel;
+                if (!useFakeProvider) {
+                    try {
+                        ({
+                            hold,
+                            fundsCap,
+                            costFactor,
+                            promptTokenEstimate: attemptPromptTokenEstimate,
+                        } = await this.#applyCreditGate(
+                            actor,
+                            attemptModel,
+                            requestArgs,
+                            {
+                                promptTokenEstimate,
+                                requestedMaxTokens,
+                                pricingTime,
+                            },
+                        ));
+                    } catch (error) {
+                        creditGateError = error;
+                        throw error;
+                    }
+                    await this.#resolvePuterPaths(
+                        attemptProvider,
+                        requestArgs,
+                        actor,
+                    );
+                }
+                abortSignal?.throwIfAborted();
+                try {
+                    const result = await attemptProvider.complete(
+                        requestArgs,
+                        snapshot,
+                        pricingTime,
+                    );
+                    model = attemptModel;
+                    variantSpeed =
+                        attemptModel.id !== baseModel.id
+                            ? selection.speed
+                            : undefined;
+                    if (
+                        args.serviceSpeed !== undefined &&
+                        'message' in result
+                    ) {
+                        const messageResult = result as IChatMessageResult;
+                        const details =
+                            messageResult.usageDetails ??
+                            usageDetailsFromUsage(messageResult.usage, model);
+                        messageResult.usageDetails = {
+                            ...details,
+                            serviceSpeed:
+                                variantSpeed ??
+                                details?.serviceSpeed ??
+                                details?.speed ??
+                                'standard',
+                        };
+                    }
+                    return result;
+                } catch (error) {
+                    await hold.release();
+                    hold = NO_CREDIT_HOLD;
+                    if (
+                        args.serviceSpeed === undefined ||
+                        selection.speed === 'standard' ||
+                        !isServiceSpeedUnavailable(
+                            error,
+                            attemptModel.id !== baseModel.id,
+                        )
+                    )
+                        throw error;
+                    requestedSpeed = lowerServiceSpeed(selection.speed);
+                    pricingTime = new Date();
+                }
+            }
         };
 
         try {
@@ -984,29 +1098,17 @@ export class ChatCompletionDriver extends PuterDriver {
                 // The previous attempt released its hold when it failed, so
                 // this one starts from nothing held.
                 pricingTime = new Date();
-                if (!useFakeProvider) {
-                    ({
-                        hold,
-                        fundsCap,
-                        costFactor,
-                        promptTokenEstimate: attemptPromptTokenEstimate,
-                    } = await this.#applyCreditGate(actor, fallback, args, {
-                        promptTokenEstimate,
-                        requestedMaxTokens,
-                        pricingTime,
-                    }));
-                }
 
                 tried.add(routeId(fallback.provider!, fallback.id));
 
                 try {
                     res = await runAttempt(fbProvider, fallback);
-                    model = fallback;
                     lastError = null;
                     console.warn(
                         `[ai-chat] fallback served (${completionId}, ${first.provider}:${first.model} -> ${fallback.provider}:${fallback.id}, first ${first.status ?? 'none'}${first.upstreamType ? `/${first.upstreamType}` : ''})`,
                     );
                 } catch (fbErr) {
+                    if (fbErr === creditGateError) throw fbErr;
                     await hold.release();
                     hold = NO_CREDIT_HOLD;
                     abortSignal?.throwIfAborted();
@@ -1162,6 +1264,20 @@ export class ChatCompletionDriver extends PuterDriver {
                         usageDetailsFromUsage(usage, model),
                     );
                 }
+                if (
+                    args.serviceSpeed !== undefined &&
+                    chatStream.usageDetails
+                ) {
+                    const details = chatStream.usageDetails;
+                    chatStream.setUsageDetails({
+                        ...details,
+                        serviceSpeed:
+                            variantSpeed ??
+                            details.serviceSpeed ??
+                            details.speed ??
+                            'standard',
+                    });
+                }
                 withClaudeThinkingTokens(
                     enrichedUsage,
                     model,
@@ -1474,12 +1590,7 @@ export class ChatCompletionDriver extends PuterDriver {
         const metering = this.services.metering;
         const { requestedMaxTokens, pricingTime } = estimates;
         let { promptTokenEstimate } = estimates;
-        // A provider can name its own cost keys for this request (Claude's
-        // fast-mode rate card), cap its output, and size an extra reservation
-        // the per-token math can't see (a web-search/advisor tool that could
-        // run several times before the model answers) — the same clamps it
-        // applies when building the request, so the hold and the request
-        // agree.
+        // Providers reserve tool calls using the same caps they send upstream.
         const pricing =
             this.#providers[model.provider!]?.requestPricing?.(args, model, {
                 promptTokenEstimate,

src/backend/drivers/ai-chat/providers/OpenAICompatProvider.ts

@@ -41,6 +41,7 @@ import {
     meterChatUsage,
     type MeterChatUsageOptions,
 } from '../utils/meterChatUsage.js';
+import { servedServiceSpeed } from '../utils/serviceSpeed.js';
 import { catalogPrice, costKeys } from '../utils/pricing.js';
 import { normalizeModelKey } from '../utils/modelRouting.js';
 import * as OpenAIUtil from '../utils/OpenAIUtil.js';
@@ -232,6 +233,8 @@ export class OpenAICompatProvider implements IChatProvider {
                   )
                 : {}),
         };
+        if (args.serviceSpeed !== undefined && args.service_tier !== undefined)
+            shared.service_tier = args.service_tier;
         const params = this.vendorParams(shared, args, model, actor);
 
         let pricingTime = attemptPricingTime ?? new Date();
@@ -271,15 +274,29 @@ export class OpenAICompatProvider implements IChatProvider {
                     source,
                     model,
                 );
-                if (usageDetails) source.setUsageDetails?.(usageDetails);
+                const serviceSpeed = servedServiceSpeed(source);
+                if (usageDetails)
+                    source.setUsageDetails?.({
+                        ...usageDetails,
+                        ...(args.serviceSpeed !== undefined
+                            ? { serviceSpeed }
+                            : {}),
+                    });
                 const metered = meterChatUsage(
                     this.#metering,
                     actor,
                     this.meteringModelKey(model.id),
                     model,
                     usage,
-                    { ...meterOptions, pricingTime },
+                    { ...meterOptions, pricingTime, serviceSpeed },
                 );
+                if (args.serviceSpeed !== undefined && !usageDetails) {
+                    const details = OpenAIUtil.usageDetailsFromTrackedUsage(
+                        metered.usage,
+                    );
+                    if (details)
+                        source.setUsageDetails?.({ ...details, serviceSpeed });
+                }
                 source.setUsageCosts(metered.costs);
                 return this.reportedUsage(metered.usage);
             },

src/backend/drivers/ai-chat/providers/alibaba/catalog.ts

@@ -174,6 +174,9 @@ export const mapAlibabaCatalogModel = (
             : undefined;
     return {
         ...existing,
+        serviceSpeedVariants: {
+            fast: id === 'glm-5.2' ? 'glm-5.2-fast-preview' : `${id}-prime`,
+        },
         id,
         puterId,
         name: raw.name ?? existing?.name ?? id,

src/backend/drivers/ai-chat/providers/alibaba/models.ts

@@ -37,6 +37,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-max-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 160,
@@ -60,6 +61,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -81,6 +83,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -102,6 +105,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.6-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -123,6 +127,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.6-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 19,
@@ -143,6 +148,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -164,6 +170,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -188,6 +195,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-max-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -210,6 +218,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-max-0902-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -234,6 +243,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 5,
@@ -257,6 +267,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3-coder-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -282,6 +293,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-397b-a17b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 60,
@@ -305,6 +317,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-122b-a10b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -328,6 +341,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-35b-a3b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 25,
@@ -351,6 +365,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-27b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -376,6 +391,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.6-35b-a3b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 24.8,
@@ -399,6 +415,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.6-27b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 60,
@@ -422,6 +439,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3-vl-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 20,
@@ -447,6 +465,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3-omni-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 43,
@@ -469,6 +488,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-mt-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 246,
@@ -491,6 +511,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-2025-01-25-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -511,6 +532,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-2025-04-28-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -531,6 +553,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-2025-07-14-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -553,6 +576,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-2025-12-01-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -574,6 +598,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-2026-05-20-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -594,6 +619,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-2026-06-08-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -614,6 +640,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-2026-05-17-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -635,6 +662,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-preview-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -657,6 +685,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-plus-2026-02-15-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -678,6 +707,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-plus-2026-04-20-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -700,6 +730,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 10,
@@ -722,6 +753,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 3,
@@ -743,6 +775,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -765,6 +798,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-27b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -785,6 +819,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-2.4t-a95b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -809,6 +844,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-omni-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -832,6 +868,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-omni-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 140,
@@ -855,6 +892,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-omni-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -877,6 +915,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-mt-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 16,
@@ -897,6 +936,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-mt-lite-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 12,
@@ -919,6 +959,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'glm-5.1-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 140,
@@ -938,6 +979,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'glm-5.2-fast-preview' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 140,
@@ -958,6 +1000,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'glm-5.2-fast-preview-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 280,
@@ -981,6 +1024,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'deepseek-v4-flash-0731-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 44,
@@ -1003,6 +1047,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'deepseek-v4.1-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -1023,6 +1068,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'deepseek-v4-pro-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 240,
@@ -1045,6 +1091,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'deepseek-v4-pro-0813-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 132,
@@ -1065,6 +1112,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k2.7-code-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 95,

src/backend/drivers/ai-chat/providers/azure/AzureChatProvider.ts

@@ -20,6 +20,10 @@
 import { HttpError } from '@heyputer/backend/src/core/http/HttpError.js';
 import { OpenAI } from 'openai';
 import { ChatCompletionCreateParams } from 'openai/resources/index.js';
+import {
+    serviceSpeedBillingModel,
+    servedServiceSpeed,
+} from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { FSService } from '../../../../services/fs/FSService.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
@@ -153,6 +157,7 @@ export class AzureChatProvider implements IChatProvider {
 
     async complete(
         params: ICompleteArguments,
+        resolved?: IChatModel,
     ): ReturnType<IChatProvider['complete']> {
         const {
             max_tokens,
@@ -180,7 +185,9 @@ export class AzureChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Inline compaction is a Responses-API feature; chat.completions can't
         // express `context_management` or a `compaction` content block.
@@ -194,7 +201,9 @@ export class AzureChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Validate messages
         if (!Array.isArray(messages)) {
@@ -207,9 +216,11 @@ export class AzureChatProvider implements IChatProvider {
         model = model ?? this.#defaultModel;
 
         const modelUsed =
-            this.models().find((m) =>
+            resolved ??
+            (this.models().find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
-            ) || this.models().find((m) => m.id === this.getDefaultModel())!;
+            ) ||
+                this.models().find((m) => m.id === this.getDefaultModel())!);
 
         // messages.unshift({
         //     role: 'system',
@@ -279,6 +290,9 @@ export class AzureChatProvider implements IChatProvider {
                   }),
             messages: messages,
             model: modelUsed.id,
+            ...(params.service_tier !== undefined
+                ? { service_tier: params.service_tier }
+                : {}),
             ...(mappedTools?.length ? { tools: mappedTools } : {}),
             ...(max_tokens !== undefined
                 ? { max_completion_tokens: max_tokens }
@@ -315,7 +329,12 @@ export class AzureChatProvider implements IChatProvider {
         );
 
         return OpenAiUtil.handle_completion_output({
-            usage_calculator: ({ usage }) => {
+            usage_calculator: ({
+                service_tier,
+                usage,
+                setUsageCosts,
+                setUsageDetails,
+            }) => {
                 const cachedTokens =
                     usage.prompt_tokens_details?.cached_tokens ?? 0;
                 const trackedUsage = {
@@ -335,9 +354,20 @@ export class AzureChatProvider implements IChatProvider {
 
                 const costsOverrideFromModel = buildCostsOverride(
                     trackedUsage,
-                    modelUsed,
+                    serviceSpeedBillingModel(
+                        modelUsed,
+                        servedServiceSpeed({ service_tier }),
+                    ),
                 );
 
+                setUsageCosts(costsOverrideFromModel);
+                if (params.serviceSpeed !== undefined)
+                    setUsageDetails({
+                        ...OpenAiUtil.usageDetailsFromTrackedUsage(
+                            trackedUsage,
+                        )!,
+                        serviceSpeed: servedServiceSpeed({ service_tier }),
+                    });
                 this.#meteringService.utilRecordUsageObject(
                     trackedUsage,
                     actor!,

src/backend/drivers/ai-chat/providers/azure/AzureResponsesProvider.ts

@@ -19,6 +19,10 @@
 
 import { OpenAI } from 'openai';
 import { ResponseCreateParams } from 'openai/resources/responses/responses.mjs';
+import {
+    serviceSpeedBillingModel,
+    servedServiceSpeed,
+} from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { FSService } from '../../../../services/fs/FSService.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
@@ -152,37 +156,41 @@ export class AzureResponsesProvider implements IChatProvider {
             : {};
     }
 
-    async complete({
-        messages,
-        model,
-        max_tokens,
-        moderation,
-        tools,
-        tool_choice,
-        parallel_tool_calls,
-        include,
-        conversation,
-        compaction,
-        context_management,
-        previous_response_id,
-        instructions,
-        metadata,
-        prompt,
-        prompt_cache_key,
-        prompt_cache_retention,
-        store,
-        top_p,
-        truncation,
-        background,
-        service_tier,
-        verbosity,
-        stream,
-        reasoning,
-        reasoning_effort,
-        temperature,
-        text,
-        outputFormat,
-    }: ICompleteArguments): ReturnType<IChatProvider['complete']> {
+    async complete(
+        {
+            messages,
+            model,
+            max_tokens,
+            moderation,
+            tools,
+            tool_choice,
+            parallel_tool_calls,
+            include,
+            conversation,
+            compaction,
+            context_management,
+            previous_response_id,
+            instructions,
+            metadata,
+            prompt,
+            prompt_cache_key,
+            prompt_cache_retention,
+            store,
+            top_p,
+            truncation,
+            background,
+            service_tier,
+            serviceSpeed: requestedServiceSpeed,
+            verbosity,
+            stream,
+            reasoning,
+            reasoning_effort,
+            temperature,
+            text,
+            outputFormat,
+        }: ICompleteArguments,
+        resolved?: IChatModel,
+    ): ReturnType<IChatProvider['complete']> {
         // Validate messages
         if (!Array.isArray(messages)) {
             throw new HttpError(400, '`messages` must be an array', {
@@ -200,12 +208,13 @@ export class AzureResponsesProvider implements IChatProvider {
         model = model ?? this.#defaultModel;
 
         const modelUsed =
-            this.models({ no_restrictions: true }).find((m) =>
+            resolved ??
+            (this.models({ no_restrictions: true }).find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
             ) ||
-            this.models({ no_restrictions: true }).find(
-                (m) => m.id === this.getDefaultModel(),
-            )!;
+                this.models({ no_restrictions: true }).find(
+                    (m) => m.id === this.getDefaultModel(),
+                )!);
 
         const userIdentifier = upstreamUserIdentifier(actor);
         // Cache key defaults to the actor identifier; see upstreamUserIdentifier.
@@ -335,9 +344,11 @@ export class AzureResponsesProvider implements IChatProvider {
         return OpenAiUtil.handle_completion_output_responses_api({
             usage_calculator: ({
                 usage,
+                service_tier,
                 webSearchCalls,
                 tool_usage,
                 setUsageCosts,
+                setUsageDetails,
             }) => {
                 const numWebSearches: number =
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -363,7 +374,10 @@ export class AzureResponsesProvider implements IChatProvider {
 
                 const costsOverrideFromModel = buildCostsOverride(
                     trackedUsage,
-                    modelUsed,
+                    serviceSpeedBillingModel(
+                        modelUsed,
+                        servedServiceSpeed({ service_tier }),
+                    ),
                 );
                 if (numWebSearches) {
                     costsOverrideFromModel.web_search_calls =
@@ -374,6 +388,14 @@ export class AzureResponsesProvider implements IChatProvider {
                     });
                 }
 
+                setUsageCosts?.(costsOverrideFromModel);
+                if (requestedServiceSpeed !== undefined)
+                    setUsageDetails?.({
+                        ...OpenAiUtil.usageDetailsFromTrackedUsage(
+                            trackedUsage,
+                        )!,
+                        serviceSpeed: servedServiceSpeed({ service_tier }),
+                    });
                 this.#meteringService.utilRecordUsageObject(
                     trackedUsage,
                     actor,

src/backend/drivers/ai-chat/providers/azure/models.test.ts

@@ -40,7 +40,11 @@ const STANDALONE = [
 ];
 
 // Fields an Azure deployment genuinely differs from its source on, by puterId.
-const OVERRIDES: Record<string, string[]> = {};
+const OVERRIDES: Record<string, string[]> = {
+    'azure:x-ai/grok-4.3': ['serviceSpeedRates'],
+    'azure:x-ai/grok-4-20-non-reasoning': ['serviceSpeedRates'],
+    'azure:x-ai/grok-4-20-reasoning': ['serviceSpeedRates'],
+};
 
 const IDENTITY = ['id', 'puterId', 'aliases'];
 
@@ -65,6 +69,18 @@ const mirrored = AZURE_MODELS.filter(
 ).map((m) => [m.puterId!, m] as const);
 
 describe('AZURE_MODELS mirroring', () => {
+    it('inherits OpenAI fast rates without enabling direct-only speed tiers', () => {
+        for (const model of AZURE_MODELS) {
+            expect(model.serviceSpeedRates?.ultrafast).toBeUndefined();
+            if (model.puterId?.startsWith('azure:x-ai/')) {
+                expect(model.serviceSpeedRates?.fast).toBeUndefined();
+            }
+        }
+        const azure = AZURE_MODELS.find((model) => model.id === 'gpt-5.4')!;
+        expect(azure.serviceSpeedRates).toEqual({
+            fast: sourceOf(azure)!.serviceSpeedRates!.fast,
+        });
+    });
     it('has a direct-provider source for every entry not listed as standalone', () => {
         const orphans = mirrored
             .filter(([, m]) => !sourceOf(m))

src/backend/drivers/ai-chat/providers/azure/models.ts

@@ -22,10 +22,8 @@ import { OPEN_AI_MODELS } from '../openai/models.js';
 import { XAI_MODELS } from '../xai/models.js';
 
 /**
- * An Azure deployment of a model we also serve direct. Every field but the
- * identity comes from the source entry, so prices, long-context tiers and
- * limits can't drift from it. `name` is the vendor-qualified name both catalogs
- * share (`openai/gpt-5.4`); extra fields override the source.
+ * Azure shares its source model's list prices, context tiers, and limits.
+ * Identity and available service speeds belong to the deployment.
  */
 const mirror = (
     source: readonly IChatModel[],
@@ -41,6 +39,11 @@ const mirror = (
         puterId: `azure:${name}`,
         id: azure.id,
         ...shared,
+        serviceSpeedRates:
+            source === OPEN_AI_MODELS &&
+            shared.serviceSpeedRates?.fast !== undefined
+                ? { fast: shared.serviceSpeedRates.fast }
+                : undefined,
         aliases: [name],
         ...azure,
     };
@@ -127,6 +130,13 @@ export const AZURE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 250,
+                cached_tokens: 25,
+                completion_tokens: 2000,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -171,6 +181,13 @@ export const AZURE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 45,
+                cached_tokens: 4.5,
+                completion_tokens: 360,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 25,

src/backend/drivers/ai-chat/providers/claude/ClaudeProvider.integration.test.ts

@@ -147,6 +147,22 @@ describe.skipIf(skipUnlessEnv(ENV_VAR))('ClaudeProvider (integration)', () => {
         },
     );
 
+    it('returns a completion from claude-fable-5-2', { timeout: INTEGRATION_TEST_TIMEOUT_MS }, async () => {
+        const provider = buildProvider();
+        const result = await withTestActor(() =>
+            provider.complete({
+                model: 'claude-fable-5-2',
+                messages: [{ role: 'user', content: 'Reply with OK.' }],
+                reasoning_effort: 'low',
+                max_tokens: 128,
+            }),
+        );
+        const content = (result as {
+            message: { content: Array<{ type: string; text?: string }> };
+        }).message.content;
+        expect(content.find((block) => block.type === 'text')?.text?.length).toBeGreaterThan(0);
+    });
+
     // (a) Claude Code-shaped system blocks, attribution header first — the
     // pipeline must never merge or reorder system blocks: the header is
     // only recognized by Anthropic when it is the sole content of an

src/backend/drivers/ai-chat/providers/claude/ClaudeProvider.test.ts

@@ -1173,6 +1173,7 @@ describe('ClaudeProvider.complete request shape', () => {
     });
 
     it.each([
+        'claude-fable-5-2',
         'claude-fable-5-1',
         'claude-haiku-5-5',
         'claude-opus-5-5',
@@ -1198,6 +1199,7 @@ describe('ClaudeProvider.complete request shape', () => {
     );
 
     it.each([
+        'claude-fable-5-2',
         'claude-fable-5-1',
         'claude-haiku-5-5',
         'claude-opus-5-5',
@@ -1303,6 +1305,73 @@ describe('ClaudeProvider model resolution', () => {
         );
     });
 
+    it.each([
+        'claude-fable-5-2',
+        'claude-fable-5-2-latest',
+        'claude-fable-5.2',
+        'anthropic/claude-fable-5-2',
+    ])(
+        'routes %s to Fable 5.2 with published rates',
+        async (model) => {
+            const { provider } = makeProvider();
+            messagesCreateMock.mockResolvedValueOnce({
+                content: [{ type: 'text', text: 'ok' }],
+                usage: {
+                    input_tokens: 100,
+                    output_tokens: 50,
+                    cache_read_input_tokens: 1000,
+                    cache_creation_input_tokens: 200,
+                    cache_creation: {
+                        ephemeral_5m_input_tokens: 150,
+                        ephemeral_1h_input_tokens: 50,
+                    },
+                },
+            });
+
+            await withTestActor(() =>
+                provider.complete({
+                    model,
+                    messages: [{ role: 'user', content: 'hi' }],
+                }),
+            );
+
+            expect(messagesCreateMock.mock.calls[0]![0].model).toBe(
+                'claude-fable-5-2',
+            );
+            const fable52 = CLAUDE_MODELS.find(
+                (m) => m.id === 'claude-fable-5-2',
+            )!;
+            expect(fable52.costs).toMatchObject({
+                input_tokens: 800,
+                output_tokens: 4000,
+                cache_read_input_tokens: 20,
+                ephemeral_5m_input_tokens: 1000,
+                ephemeral_1h_input_tokens: 1600,
+            });
+            expect(fable52.serviceSpeedRates?.fast).toMatchObject({
+                input_tokens: 1600,
+                output_tokens: 8000,
+                cache_read_input_tokens: 40,
+                ephemeral_5m_input_tokens: 2000,
+                ephemeral_1h_input_tokens: 3200,
+            });
+            expect(fable52.context).toBe(1_000_000);
+            expect(fable52.max_tokens).toBe(128_000);
+            const [, , prefix, overrides] = recordSpy.mock.calls[0]!;
+            expect(prefix).toBe('claude:claude-fable-5-2');
+            expect(overrides).toMatchObject({
+                input_tokens: 100 * Number(fable52.costs.input_tokens),
+                output_tokens: 50 * Number(fable52.costs.output_tokens),
+                cache_read_input_tokens:
+                    1000 * Number(fable52.costs.cache_read_input_tokens),
+                ephemeral_5m_input_tokens:
+                    150 * Number(fable52.costs.ephemeral_5m_input_tokens),
+                ephemeral_1h_input_tokens:
+                    50 * Number(fable52.costs.ephemeral_1h_input_tokens),
+            });
+        },
+    );
+
     it('routes the bare claude-fable alias to fable 5.1 rather than fable 5', async () => {
         const { provider } = makeProvider();
         messagesCreateMock.mockResolvedValueOnce(baseResponse);
@@ -2311,16 +2380,20 @@ describe('ClaudeProvider metering', () => {
         expect('thinking_tokens' in overrides).toBe(false);
     });
 
-    it('bills at the fast_* rates when the upstream reports usage.speed:"fast"', async () => {
+    it.each(['claude-opus-5-5', 'claude-fable-5-2'])('bills at fast rates for %s when the upstream reports fast usage', async (model) => {
         const { provider } = makeProvider();
         messagesCreateMock.mockResolvedValueOnce({
             content: [{ type: 'text', text: 'hi' }],
-            usage: { input_tokens: 10, output_tokens: 5, speed: 'fast' },
+            usage: {
+                input_tokens: 10, output_tokens: 5, speed: 'fast',
+                cache_creation: { ephemeral_5m_input_tokens: 7, ephemeral_1h_input_tokens: 3 },
+                cache_read_input_tokens: 20,
+            },
         });
 
         const result = (await withTestActor(() =>
             provider.complete({
-                model: 'claude-opus-5-5',
+                model,
                 messages: [{ role: 'user', content: 'hi' }],
                 speed: 'fast',
             }),
@@ -2331,11 +2404,15 @@ describe('ClaudeProvider metering', () => {
         expect('input_tokens' in result.usage).toBe(false);
         expect(result.usageDetails.speed).toBe('fast');
 
-        const opus = CLAUDE_MODELS.find((m) => m.id === 'claude-opus-5-5')!;
+        const selectedModel = CLAUDE_MODELS.find((m) => m.id === model)!;
         const [, , prefix, overrides] = recordSpy.mock.calls[0]!;
-        expect(prefix).toBe('claude:claude-opus-5-5');
-        expect(overrides.fast_input_tokens).toBe(10 * Number(opus.costs.fast_input_tokens));
-        expect(overrides.fast_output_tokens).toBe(5 * Number(opus.costs.fast_output_tokens));
+        expect(prefix).toBe(`claude:${model}`);
+        const fastRates = selectedModel.serviceSpeedRates!.fast as Record<string, number>;
+        expect(overrides.fast_input_tokens).toBe(10 * fastRates.input_tokens);
+        expect(overrides.fast_output_tokens).toBe(5 * fastRates.output_tokens);
+        expect(overrides.fast_ephemeral_5m_input_tokens).toBe(7 * fastRates.ephemeral_5m_input_tokens);
+        expect(overrides.fast_ephemeral_1h_input_tokens).toBe(3 * fastRates.ephemeral_1h_input_tokens);
+        expect(overrides.fast_cache_read_input_tokens).toBe(20 * fastRates.cache_read_input_tokens);
     });
 
     it('bills at standard rates when fast mode was requested but not granted by the upstream', async () => {
@@ -2357,13 +2434,15 @@ describe('ClaudeProvider metering', () => {
         expect('fast_input_tokens' in result.usage).toBe(false);
     });
 
-    it('retries at standard speed on Claude when fast mode is rate limited', async () => {
+    it.each([
+        [429, "This request would exceed your organization's rate limit of 0 fast mode input tokens per minute"],
+        [529, 'Overloaded'],
+        [529, 'Fast mode capacity unavailable'],
+    ])('retries at standard speed on Claude after fast capacity failure %s', async (status, message) => {
         const { provider } = makeProvider();
         const fastLimited = Object.assign(
-            new Error(
-                "This request would exceed your organization's rate limit of 0 fast mode input tokens per minute",
-            ),
-            { status: 429 },
+            new Error(message),
+            { status },
         );
         messagesCreateMock.mockRejectedValueOnce(fastLimited).mockResolvedValueOnce({
             content: [{ type: 'text', text: 'hi' }],
@@ -2587,13 +2666,13 @@ describe('ClaudeProvider.requestPricing', () => {
     const haiku = CLAUDE_MODELS.find((m) => m.id === 'claude-haiku-4-5-20251001')!;
     const opus55 = CLAUDE_MODELS.find((m) => m.id === 'claude-opus-5-5')!;
 
-    it('returns fast cost keys only when the model has fast rates and fast was requested', () => {
+    it('leaves token reservation keys to the selected catalog rate card', () => {
         const { provider } = makeProvider();
         expect(
             provider.requestPricing({ speed: 'fast', tools: [] } as never, opus55, {
                 promptTokenEstimate: 10,
             }),
-        ).toMatchObject({ inputKey: 'fast_input_tokens', outputKey: 'fast_output_tokens' });
+        ).toEqual({});
         expect(
             provider.requestPricing({ speed: 'fast', tools: [] } as never, haiku, {
                 promptTokenEstimate: 10,

src/backend/drivers/ai-chat/providers/claude/ClaudeProvider.ts

@@ -43,6 +43,7 @@ import {
 } from '../../utils/mediaParts.js';
 import { isToolChoice, toolChoiceFromWire } from '../../utils/openaiParams.js';
 import { buildCostsOverride } from '../../utils/pricing.js';
+import { serviceSpeedCosts } from '../../utils/serviceSpeed.js';
 import type {
     AIChatStream,
     AIChatTextStream,
@@ -107,20 +108,21 @@ const toAnthropicMediaPart = (part: any): any => {
     return part;
 };
 
-/** A 429 from fast mode's separate quota, not the model's normal limits. */
-const isFastModeRateLimit = (e: unknown): boolean => {
+/** Fast quota or overload failures can be retried at standard speed. */
+const isFastModeUnavailable = (e: unknown): boolean => {
     const err = e as { status?: unknown; message?: unknown };
     return (
-        err?.status === 429 &&
-        typeof err.message === 'string' &&
-        /fast mode/i.test(err.message)
+        typeof err?.message === 'string' &&
+        ((err?.status === 429 && /fast mode/i.test(err.message)) ||
+            (err?.status === 529 && /overload|fast mode/i.test(err.message)))
     );
 };
 
 // Models whose current turn rejects a non-default temperature/top_p/top_k
-// outright. Fable 5/5.1, Sonnet 5/5.5, Haiku 5.5, and Opus 4.7+.
+// outright. Fable 5/5.1/5.2, Sonnet 5/5.5, Haiku 5.5, and Opus 4.7+.
 const OMITS_SAMPLING_PARAMS = new Set([
     'claude-haiku-5-5',
+    'claude-fable-5-2',
     'claude-fable-5-1',
     'claude-fable-5',
     'claude-sonnet-5-5',
@@ -133,6 +135,7 @@ const OMITS_SAMPLING_PARAMS = new Set([
 
 const SUPPORTS_EFFORT = new Set([
     'claude-haiku-5-5',
+    'claude-fable-5-2',
     'claude-fable-5-1',
     'claude-fable-5',
     'claude-sonnet-5-5',
@@ -298,20 +301,12 @@ export class ClaudeProvider implements IChatProvider {
         return `claude:${modelId}`;
     }
 
-    /**
-     * Sizes the credit hold for Claude-only extras the generic per-token math
-     * can't see: fast mode's own rate card, and a web-search/advisor tool that
-     * could run several times before the model answers.
-     */
+    /** Reserves tools that can run several times before the model answers. */
     requestPricing(
         args: ICompleteArguments,
         model: IChatModel,
         est: { promptTokenEstimate: number },
-    ): { inputKey?: string; outputKey?: string; extraCost?: number } {
-        const fast =
-            args.speed === 'fast' &&
-            model.costs?.fast_output_tokens !== undefined;
-
+    ): { extraCost?: number } {
         let extraCost = 0;
         for (const raw of args.tools ?? []) {
             const tool = raw as Record<string, unknown>;
@@ -350,12 +345,6 @@ export class ClaudeProvider implements IChatProvider {
         }
 
         return {
-            ...(fast
-                ? {
-                      inputKey: 'fast_input_tokens',
-                      outputKey: 'fast_output_tokens',
-                  }
-                : {}),
             ...(extraCost > 0 ? { extraCost } : {}),
         };
     }
@@ -364,11 +353,9 @@ export class ClaudeProvider implements IChatProvider {
         try {
             return await this.#completeOnce(args);
         } catch (e) {
-            // Fast mode has its own quota. Anthropic's advice on that 429 is to
-            // drop `speed` and run at standard speed; doing it here keeps the
-            // request on Claude instead of marking the route unhealthy and
-            // replaying it on a reseller.
-            if (args.speed === 'fast' && isFastModeRateLimit(e)) {
+            // Retry fast-capacity failures on Claude at standard speed before
+            // considering a different provider.
+            if (args.speed === 'fast' && isFastModeUnavailable(e)) {
                 return await this.#completeOnce({ ...args, speed: undefined });
             }
             throw e;
@@ -637,7 +624,7 @@ export class ClaudeProvider implements IChatProvider {
             : undefined;
         const fast =
             args.speed === 'fast' &&
-            modelUsed.costs?.fast_output_tokens !== undefined;
+            modelUsed.serviceSpeedRates?.fast !== undefined;
         const safeguardsPolicy = applySafeguardsPolicy(
             args.safeguards,
             args.anthropicBetas,
@@ -1071,6 +1058,7 @@ export class ClaudeProvider implements IChatProvider {
         // keeps reasoning visible in the stream.
         if (
             modelId === 'claude-haiku-5-5' ||
+            modelId === 'claude-fable-5-2' ||
             modelId === 'claude-fable-5-1' ||
             modelId === 'claude-fable-5' ||
             modelId === 'claude-sonnet-5-5' ||
@@ -1505,7 +1493,8 @@ export class ClaudeProvider implements IChatProvider {
 
         const fast =
             raw.speed === 'fast' &&
-            modelUsed.costs?.fast_output_tokens !== undefined;
+            modelUsed.serviceSpeedRates?.fast !== undefined;
+        // Keep published usage keys while resolving rates from the common catalog shape.
         const executorUsage: Record<string, number> = fast
             ? Object.fromEntries(
                   Object.entries(exec).map(([k, v]) => [`fast_${k}`, v]),
@@ -1517,7 +1506,24 @@ export class ClaudeProvider implements IChatProvider {
         const fetches = raw.server_tool_use?.web_fetch_requests ?? 0;
         if (fetches) executorUsage.web_fetch_requests = fetches;
 
-        const executorCosts = buildCostsOverride(executorUsage, modelUsed);
+        const fastRates = fast
+            ? serviceSpeedCosts(modelUsed, 'fast')
+            : undefined;
+        const billingModel = fastRates
+            ? {
+                  ...modelUsed,
+                  costs: {
+                      ...modelUsed.costs,
+                      ...Object.fromEntries(
+                          Object.keys(exec).map((key) => [
+                              `fast_${key}`,
+                              fastRates[key],
+                          ]),
+                      ),
+                  },
+              }
+            : modelUsed;
+        const executorCosts = buildCostsOverride(executorUsage, billingModel);
 
         let advisorUsage: Record<string, number> | undefined;
         let advisorCosts: Record<string, number> | undefined;

src/backend/drivers/ai-chat/providers/claude/models.ts

@@ -55,6 +55,46 @@ export const CLAUDE_MODELS: IChatModel[] = [
         context: 1_000_000,
         max_tokens: 128_000,
     },
+    {
+        puterId: 'anthropic:anthropic/claude-fable-5-2',
+        id: 'claude-fable-5-2',
+        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
+        open_weights: false,
+        tool_call: true,
+        release_date: '2026-11-09',
+        aliases: [
+            'claude-fable-5-2-latest',
+            'claude-fable-5.2',
+            'anthropic/claude-fable-5-2',
+        ],
+        name: 'Claude Fable 5.2',
+        midConversationSystem: true,
+        costs_currency: 'usd-cents',
+        input_cost_key: 'input_tokens',
+        output_cost_key: 'output_tokens',
+        // Source: https://www.anthropic.com/claude-fable-and-mythos-5-2
+        serviceSpeedRates: {
+            fast: {
+                input_tokens: 1600,
+                output_tokens: 8000,
+                ephemeral_5m_input_tokens: 1600 * 1.25,
+                ephemeral_1h_input_tokens: 1600 * 2,
+                cache_read_input_tokens: 1600 * 0.025,
+            },
+        },
+        costs: {
+            tokens: 1_000_000,
+            input_tokens: 800,
+            ephemeral_5m_input_tokens: 800 * 1.25,
+            ephemeral_1h_input_tokens: 800 * 2,
+            // 0.025x input, not the usual 0.1x.
+            cache_read_input_tokens: 800 * 0.025,
+            output_tokens: 4000,
+            web_search_requests: 1_000_000, // $10/1k requests
+        },
+        context: 1000000,
+        max_tokens: 128000,
+    },
     {
         puterId: 'anthropic:anthropic/claude-fable-5-1',
         id: 'claude-fable-5-1',
@@ -190,6 +230,15 @@ export const CLAUDE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'input_tokens',
         output_cost_key: 'output_tokens',
+        serviceSpeedRates: {
+            fast: {
+                input_tokens: 800,
+                output_tokens: 4000,
+                ephemeral_5m_input_tokens: 1000,
+                ephemeral_1h_input_tokens: 1600,
+                cache_read_input_tokens: 40,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             input_tokens: 400,
@@ -199,12 +248,6 @@ export const CLAUDE_MODELS: IChatModel[] = [
             cache_read_input_tokens: 400 * 0.05,
             output_tokens: 2000,
             web_search_requests: 1_000_000,
-            // Fast mode (`speed:'fast'`), live-verified.
-            fast_input_tokens: 800,
-            fast_output_tokens: 4000,
-            fast_ephemeral_5m_input_tokens: 1000,
-            fast_ephemeral_1h_input_tokens: 1600,
-            fast_cache_read_input_tokens: 40, // 0.05x fast_input_tokens
         },
         context: 1000000,
         max_tokens: 128000,
@@ -223,6 +266,15 @@ export const CLAUDE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'input_tokens',
         output_cost_key: 'output_tokens',
+        serviceSpeedRates: {
+            fast: {
+                input_tokens: 1000,
+                output_tokens: 5000,
+                ephemeral_5m_input_tokens: 1250,
+                ephemeral_1h_input_tokens: 2000,
+                cache_read_input_tokens: 100,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             input_tokens: 500,
@@ -231,11 +283,6 @@ export const CLAUDE_MODELS: IChatModel[] = [
             cache_read_input_tokens: 500 * 0.1,
             output_tokens: 2500,
             web_search_requests: 1_000_000,
-            fast_input_tokens: 1000,
-            fast_output_tokens: 5000,
-            fast_ephemeral_5m_input_tokens: 1250,
-            fast_ephemeral_1h_input_tokens: 2000,
-            fast_cache_read_input_tokens: 100,
         },
         context: 1000000,
         max_tokens: 128000,
@@ -258,6 +305,15 @@ export const CLAUDE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'input_tokens',
         output_cost_key: 'output_tokens',
+        serviceSpeedRates: {
+            fast: {
+                input_tokens: 1000,
+                output_tokens: 5000,
+                ephemeral_5m_input_tokens: 1250,
+                ephemeral_1h_input_tokens: 2000,
+                cache_read_input_tokens: 100,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             input_tokens: 500,
@@ -266,11 +322,6 @@ export const CLAUDE_MODELS: IChatModel[] = [
             cache_read_input_tokens: 500 * 0.1,
             output_tokens: 2500,
             web_search_requests: 1_000_000,
-            fast_input_tokens: 1000,
-            fast_output_tokens: 5000,
-            fast_ephemeral_5m_input_tokens: 1250,
-            fast_ephemeral_1h_input_tokens: 2000,
-            fast_cache_read_input_tokens: 100,
         },
         context: 1000000,
         max_tokens: 128000,

src/backend/drivers/ai-chat/providers/gemini/GeminiChatProvider.ts

@@ -84,8 +84,14 @@ export class GeminiChatProvider extends OpenAICompatProvider {
             chat: {
                 completions: {
                     create: (params, options) => {
-                        const { model } = params as { model: string };
-                        if (!GEMINI_NATIVE_MODELS.has(model)) {
+                        const { model, service_tier } = params as {
+                            model: string;
+                            service_tier?: string;
+                        };
+                        if (
+                            !GEMINI_NATIVE_MODELS.has(model) &&
+                            (service_tier === undefined || !native)
+                        ) {
                             return compat.chat.completions.create(
                                 params,
                                 options,
@@ -103,7 +109,12 @@ export class GeminiChatProvider extends OpenAICompatProvider {
                 },
             },
         };
-        const models = native ? GEMINI_MODELS : COMPAT_ONLY_MODELS;
+        const models: IChatModel[] = native
+            ? GEMINI_MODELS
+            : COMPAT_ONLY_MODELS.map((model) => ({
+                  ...model,
+                  serviceSpeeds: ['standard'],
+              }));
         super(meteringService, {
             client,
             defaultModel: 'gemini-2.5-flash',
@@ -183,7 +194,10 @@ export class GeminiChatProvider extends OpenAICompatProvider {
     }
 
     protected override meteredUsage(source: UsageSource, model: IChatModel) {
-        if (GEMINI_NATIVE_MODELS.has(model.id)) {
+        if (
+            GEMINI_NATIVE_MODELS.has(model.id) ||
+            'promptTokenCount' in (source.usage ?? {})
+        ) {
             return nativeMeteredUsage(
                 source.usage as unknown as
                     GenerateContentResponseUsageMetadata | undefined,

src/backend/drivers/ai-chat/providers/gemini/geminiNative.ts

@@ -80,6 +80,7 @@ interface ChatParams {
     temperature?: number;
     reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
     stream?: boolean;
+    service_tier?: string;
 }
 
 /** Ids made up for calls Gemini returned without one; never sent back. */
@@ -240,6 +241,12 @@ const toGenerateContentRequest = (
         ? toolConfigOf(params.tool_choice)
         : undefined;
     const config: GenerateContentConfig = {
+        ...(params.service_tier !== undefined
+            ? {
+                  serviceTier:
+                      params.service_tier as GenerateContentConfig['serviceTier'],
+              }
+            : {}),
         ...(signal ? { abortSignal: signal } : {}),
         ...(systemInstruction ? { systemInstruction } : {}),
         ...(params.max_completion_tokens !== undefined

src/backend/drivers/ai-chat/providers/gemini/models.ts

@@ -142,6 +142,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: ARGON_LAUNCH_COSTS,
         pricingOverrides: listPricingFrom(
             '2026-12-01T00:00:00Z',
@@ -174,6 +175,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
         // Google serves this endpoint with gemini-3.6-flash and bills its rates.
+        serviceSpeedRates: { fast: 1.8 },
         costs: FLASH_LAUNCH_COSTS,
         pricingOverrides: FLASH_LIST_PRICING,
     },
@@ -201,6 +203,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -228,6 +231,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: FLASH_LAUNCH_COSTS,
         pricingOverrides: FLASH_LIST_PRICING,
     },
@@ -250,6 +254,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
         // Google serves this endpoint with gemini-3.8-flash and bills its rates.
+        serviceSpeedRates: { fast: 1.8 },
         costs: FLASH_LAUNCH_COSTS,
         pricingOverrides: FLASH_LIST_PRICING,
     },
@@ -270,6 +275,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: FLASH_LAUNCH_COSTS,
         pricingOverrides: FLASH_LIST_PRICING,
     },
@@ -291,6 +297,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 25,
@@ -318,6 +325,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -344,6 +352,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -374,6 +383,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 10,
@@ -402,6 +412,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -448,6 +459,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,

src/backend/drivers/ai-chat/providers/infron/InfronProvider.ts

@@ -266,6 +266,15 @@ export class InfronProvider extends OpenAICompatProvider {
         return coerced_models;
     }
 
+    async serviceSpeedModels(model: IChatModel) {
+        const variant = (await this.models()).find(
+            (entry) => entry.id === `${model.id}:priority`,
+        );
+        return variant
+            ? { fast: { ...variant, provider: model.provider } }
+            : {};
+    }
+
     protected override vendorParams(
         params: Record<string, unknown>,
         _args: unknown,

src/backend/drivers/ai-chat/providers/minimax/models.ts

@@ -43,6 +43,8 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.5 },
+        serviceSpeedVariants: { fast: 'minimax-m3-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M (input <= 512k tokens)
@@ -70,6 +72,7 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'minimax-m2.7-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M
@@ -122,6 +125,7 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'minimax-m2.5-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M
@@ -174,6 +178,7 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'minimax-m2.1-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M
@@ -222,6 +227,7 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'minimax-m2-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M

src/backend/drivers/ai-chat/providers/mistral/MistralAiProvider.test.ts

@@ -20,13 +20,12 @@
 /**
  * Offline unit tests for MistralAIProvider.
  *
- * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock
- * redis) and constructs MistralAIProvider directly against the live
- * wired `MeteringService` so the recording side is exercised end-to-
- * end. The Mistral SDK is mocked at the module boundary (the real
- * network egress point) so the provider never reaches the network.
- * The companion integration test (MistralAiProvider.integration.test.ts)
- * exercises the real Mistral endpoint.
+ * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock redis) and
+ * constructs MistralAIProvider directly against the live wired
+ * `MeteringService` so the recording side is exercised end-to- end. The Mistral
+ * SDK is mocked at the module boundary (the real network egress point) so the
+ * provider never reaches the network. The companion integration test
+ * (MistralAiProvider.integration.test.ts) exercises the real Mistral endpoint.
  */
 
 import { Context } from '../../../../core/context.js';
@@ -147,7 +146,9 @@ describe('MistralAIProvider construction', () => {
     it('constructs the Mistral SDK with the configured API key', () => {
         makeProvider();
         expect(mistralCtor).toHaveBeenCalledTimes(1);
-        expect(mistralCtor).toHaveBeenCalledWith({ apiKey: 'test-key' });
+        expect(mistralCtor).toHaveBeenCalledWith(
+            expect.objectContaining({ apiKey: 'test-key' }),
+        );
     });
 });
 
@@ -606,7 +607,11 @@ describe('MistralAIProvider.complete non-stream output', () => {
             if (stream) {
                 streamMock.mockResolvedValueOnce(
                     asAsyncIterable([
-                        { data: { choices: [{ delta: { content: 'hello' } }] } },
+                        {
+                            data: {
+                                choices: [{ delta: { content: 'hello' } }],
+                            },
+                        },
                         { data: { choices: [], usage } },
                     ]),
                 );
@@ -643,7 +648,11 @@ describe('MistralAIProvider.complete non-stream output', () => {
                 expect(result).toMatchObject({ message: { content: 'hello' } });
             }
             expect(recordSpy).toHaveBeenCalledWith(
-                { prompt_tokens: 5, cached_tokens: 1008, completion_tokens: 30 },
+                {
+                    prompt_tokens: 5,
+                    cached_tokens: 1008,
+                    completion_tokens: 30,
+                },
                 SYSTEM_ACTOR,
                 `mistral:${model}`,
                 {
@@ -688,8 +697,7 @@ describe('MistralAIProvider.complete non-stream output', () => {
         });
 
         expect(recordSpy).toHaveBeenCalledTimes(1);
-        const [usage, actor, prefix, overrides] =
-            recordSpy.mock.calls[0]!;
+        const [usage, actor, prefix, overrides] = recordSpy.mock.calls[0]!;
         expect(usage).toEqual({
             prompt_tokens: 100,
             completion_tokens: 50,
@@ -718,15 +726,11 @@ describe('MistralAIProvider.complete non-stream output', () => {
                         content: [
                             {
                                 type: 'thinking',
-                                thinking: [
-                                    { type: 'text', text: 'step one.' },
-                                ],
+                                thinking: [{ type: 'text', text: 'step one.' }],
                             },
                             {
                                 type: 'thinking',
-                                thinking: [
-                                    { type: 'text', text: 'step two.' },
-                                ],
+                                thinking: [{ type: 'text', text: 'step two.' }],
                             },
                             { type: 'text', text: 'the answer' },
                         ],
@@ -916,8 +920,7 @@ describe('MistralAIProvider.complete streaming', () => {
 
         // mistral-small-2603: prompt=15, completion=60.
         expect(recordSpy).toHaveBeenCalledTimes(1);
-        const [, , prefix, overrides] =
-            recordSpy.mock.calls[0]!;
+        const [, , prefix, overrides] = recordSpy.mock.calls[0]!;
         expect(prefix).toBe('mistral:mistral-small-2603');
         expect(overrides).toMatchObject({
             prompt_tokens: 4 * 15,
@@ -1115,7 +1118,7 @@ describe('MistralAIProvider image_url coercion', () => {
         usage: { promptTokens: 1, completionTokens: 1 },
     };
 
-    it('rewrites canonical image_url parts to the SDK\'s camelCase imageUrl', async () => {
+    it("rewrites canonical image_url parts to the SDK's camelCase imageUrl", async () => {
         const { provider } = makeProvider();
         completeMock.mockResolvedValueOnce(baseCompletion);
 
@@ -1175,7 +1178,8 @@ describe('MistralAIProvider image_url coercion', () => {
                             },
                             {
                                 type: 'image_url',
-                                image_url: 'https://example.com/already-flat.png',
+                                image_url:
+                                    'https://example.com/already-flat.png',
                             },
                         ],
                     },
@@ -1251,7 +1255,9 @@ describe('MistralAIProvider image_url coercion', () => {
                             { type: 'text', text: 'what is in this image?' },
                             {
                                 type: 'image_url',
-                                image_url: { url: 'https://example.com/photo.jpg' },
+                                image_url: {
+                                    url: 'https://example.com/photo.jpg',
+                                },
                             },
                         ],
                     },
@@ -1260,7 +1266,11 @@ describe('MistralAIProvider image_url coercion', () => {
         );
 
         const [args] = completeMock.mock.calls[0]!;
-        const parts = args.messages[0].content as { type: string; text?: string; imageUrl?: unknown }[];
+        const parts = args.messages[0].content as {
+            type: string;
+            text?: string;
+            imageUrl?: unknown;
+        }[];
         const textPart = parts.find((p) => p.type === 'text');
         const imgPart = parts.find((p) => p.type === 'image_url');
         expect(textPart?.text).toBe('what is in this image?');
@@ -1300,3 +1310,41 @@ describe('MistralAIProvider.checkModeration', () => {
         );
     });
 });
+
+describe('Mistral service speed wire mapping', () => {
+    it('adds the tier after SDK serialization and removes its internal header', async () => {
+        makeProvider();
+        const options = mistralCtor.mock.calls[0][0] as {
+            httpClient: import('@mistralai/mistralai/lib/http.js').HTTPClient;
+        };
+        let sent: Request | undefined;
+        vi.stubGlobal('fetch', async (input: Request) => {
+            sent = input;
+            return new Response('{}', {
+                headers: { 'content-type': 'application/json' },
+            });
+        });
+        try {
+            await options.httpClient.request(
+                new Request('https://api.mistral.ai/v1/chat/completions', {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        'x-puter-service-tier': 'auto',
+                    },
+                    body: JSON.stringify({
+                        model: 'mistral-medium-latest',
+                        messages: [],
+                    }),
+                }),
+            );
+            expect(sent?.headers.has('x-puter-service-tier')).toBe(false);
+            expect(await sent?.json()).toMatchObject({
+                model: 'mistral-medium-latest',
+                service_tier: 'auto',
+            });
+        } finally {
+            vi.unstubAllGlobals();
+        }
+    });
+});

src/backend/drivers/ai-chat/providers/mistral/MistralAiProvider.ts

@@ -17,6 +17,8 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import { HTTPClient } from '@mistralai/mistralai/lib/http.js';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { Mistral } from '@mistralai/mistralai';
 import { ChatCompletionResponse } from '@mistralai/mistralai/models/components/chatcompletionresponse.js';
 import { MistralError } from '@mistralai/mistralai/models/errors/mistralerror.js';
@@ -26,6 +28,7 @@ import { Context } from '../../../../core/context.js';
 import { HttpError } from '../../../../core/http/HttpError.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import type {
+    IChatModel,
     IChatCompleteResult,
     IChatProvider,
     ICompleteArguments,
@@ -106,6 +109,7 @@ const coerceMistralUsage = (usage: UsageInfo) => {
         prompt_tokens: (usage.promptTokens ?? 0) - cachedTokens,
         completion_tokens: usage.completionTokens ?? 0,
         prompt_tokens_details: { cached_tokens: cachedTokens },
+        service_tier: usage.additionalProperties?.service_tier,
     };
 };
 
@@ -115,7 +119,24 @@ export class MistralAIProvider implements IChatProvider {
     #meteringService: MeteringService;
 
     constructor(config: { apiKey: string }, meteringService: MeteringService) {
+        const httpClient = new HTTPClient();
+        // The SDK strips service_tier during body serialization.
+        httpClient.addHook('beforeRequest', async (request) => {
+            const tier = request.headers.get('x-puter-service-tier');
+            if (!tier) return;
+            const headers = new Headers(request.headers);
+            headers.delete('x-puter-service-tier');
+            const body = await request.json();
+            return new Request(request, {
+                headers,
+                body: JSON.stringify({
+                    ...body,
+                    service_tier: tier === 'auto' ? 'auto' : 'standard_only',
+                }),
+            });
+        });
         this.#client = new Mistral({
+            httpClient,
             apiKey: config.apiKey,
         });
         this.#meteringService = meteringService;
@@ -181,17 +202,22 @@ export class MistralAIProvider implements IChatProvider {
         return `mistral:${modelId}`;
     }
 
-    async complete({
-        messages,
-        stream,
-        model,
-        tools,
-        max_tokens,
-        temperature,
-        normalize,
-        response,
-        custom,
-    }: ICompleteArguments): Promise<IChatCompleteResult> {
+    async complete(
+        {
+            messages,
+            stream,
+            model,
+            tools,
+            max_tokens,
+            temperature,
+            normalize,
+            response,
+            custom,
+            service_tier,
+            serviceSpeed: requestedServiceSpeed,
+        }: ICompleteArguments,
+        resolved?: IChatModel,
+    ): Promise<IChatCompleteResult> {
         // Mistral's reasoning prompt mode: with `prompt_mode: 'reasoning'`,
         // reasoning-capable models return their thinking as structured ThinkChunk
         // content (which the splitter below separates into `reasoning`)
@@ -217,10 +243,13 @@ export class MistralAIProvider implements IChatProvider {
         }
 
         const selectedModel =
-            (await this.models()).find((m) =>
+            resolved ??
+            ((await this.models()).find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
             ) ||
-            (await this.models()).find((m) => m.id === this.getDefaultModel())!;
+                (await this.models()).find(
+                    (m) => m.id === this.getDefaultModel(),
+                )!);
         const actor = Context.get('actor');
         let completion: Awaited<
             ReturnType<Mistral['chat']['complete' | 'stream']>
@@ -242,6 +271,9 @@ export class MistralAIProvider implements IChatProvider {
                 // The SDK retries nothing by default and has no timeout once a
                 // signal is passed; a stream is bounded by its caller instead.
                 {
+                    ...(service_tier !== undefined
+                        ? { headers: { 'x-puter-service-tier': service_tier } }
+                        : {}),
                     signal: stream
                         ? Context.get('upstreamSignal')
                         : withSdkTimeout(Context.get('upstreamSignal')),
@@ -398,7 +430,8 @@ export class MistralAIProvider implements IChatProvider {
             },
             completion: completion as ChatCompletionResponse,
             stream,
-            usage_calculator: ({ usage, setUsageCosts }) => {
+            usage_calculator: ({ usage, setUsageCosts, setUsageDetails }) => {
+                const serviceSpeed = servedServiceSpeed({ usage });
                 // `coerceMistralUsage` has already taken cached reads out of
                 // `prompt_tokens`.
                 const metered = meterChatUsage(
@@ -407,8 +440,16 @@ export class MistralAIProvider implements IChatProvider {
                     this.meteringModelKey(selectedModel.id),
                     selectedModel,
                     OpenAIUtil.extractMeteredUsage(usage),
+                    { serviceSpeed },
                 );
                 setUsageCosts(metered.costs);
+                if (requestedServiceSpeed !== undefined)
+                    setUsageDetails({
+                        ...OpenAIUtil.usageDetailsFromTrackedUsage(
+                            metered.usage,
+                        )!,
+                        serviceSpeed,
+                    });
                 return metered.usage;
             },
         });

src/backend/drivers/ai-chat/providers/mistral/models.ts

@@ -42,6 +42,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 136,
@@ -75,6 +76,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 150,
@@ -105,6 +107,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -135,6 +138,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -159,6 +163,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 140,
@@ -188,6 +193,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -213,6 +219,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 20,
@@ -238,6 +245,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -262,6 +270,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 10,

src/backend/drivers/ai-chat/providers/moonshot/models.ts

@@ -30,6 +30,7 @@ export const MOONSHOT_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k3.1-pro-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200, // $2.00 per 1M
@@ -77,6 +78,7 @@ export const MOONSHOT_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k3-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 300, // $3.00 per 1M
@@ -104,6 +106,7 @@ export const MOONSHOT_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k2.6-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 95, // $0.95 per 1M
@@ -126,6 +129,7 @@ export const MOONSHOT_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k2.7-code-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 95,

src/backend/drivers/ai-chat/providers/openai/OpenAiChatCompletionsProvider.ts

@@ -20,6 +20,7 @@
 import { HttpError } from '@heyputer/backend/src/core/http/HttpError.js';
 import { OpenAI } from 'openai';
 import { ChatCompletionCreateParams } from 'openai/resources/index.js';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import type {
@@ -117,6 +118,7 @@ export class OpenAiChatProvider implements IChatProvider {
 
     async complete(
         params: ICompleteArguments,
+        resolved?: IChatModel,
     ): ReturnType<IChatProvider['complete']> {
         const {
             max_tokens,
@@ -134,6 +136,11 @@ export class OpenAiChatProvider implements IChatProvider {
         } = params;
         let { messages, model } = params;
         const cacheOptions = promptCacheOptionsToWire(prompt_cache_options);
+        if (params.service_tier === 'ultrafast' && this.#responsesProvider) {
+            return resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params);
+        }
         if (
             tools?.filter((e) => isWebSearchTool(e as Record<string, unknown>))
                 .length
@@ -147,7 +154,9 @@ export class OpenAiChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Inline compaction is a Responses-API feature; chat.completions can't
         // express `context_management` or a `compaction` content block.
@@ -161,7 +170,9 @@ export class OpenAiChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Only the Responses API writes 12h cache entries or takes a lifetime
         // on a `prompt_cache_breakpoint`; Chat Completions rejects both.
@@ -176,7 +187,9 @@ export class OpenAiChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Validate messages
         if (!Array.isArray(messages)) {
@@ -189,9 +202,11 @@ export class OpenAiChatProvider implements IChatProvider {
         model = model ?? this.#defaultModel;
 
         const modelUsed =
-            this.models().find((m) =>
+            resolved ??
+            (this.models().find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
-            ) || this.models().find((m) => m.id === this.getDefaultModel())!;
+            ) ||
+                this.models().find((m) => m.id === this.getDefaultModel())!);
 
         // messages.unshift({
         //     role: 'system',
@@ -248,6 +263,9 @@ export class OpenAiChatProvider implements IChatProvider {
                 : {}),
             messages: messages,
             model: modelUsed.id,
+            ...(params.service_tier !== undefined
+                ? { service_tier: params.service_tier }
+                : {}),
             ...(mappedTools?.length ? { tools: mappedTools } : {}),
             ...(max_tokens !== undefined
                 ? { max_completion_tokens: max_tokens }
@@ -284,7 +302,13 @@ export class OpenAiChatProvider implements IChatProvider {
         );
 
         return OpenAiUtil.handle_completion_output({
-            usage_calculator: ({ usage, setUsageCosts, setUsageDetails }) => {
+            usage_calculator: ({
+                usage,
+                service_tier,
+                setUsageCosts,
+                setUsageDetails,
+            }) => {
+                const serviceSpeed = servedServiceSpeed({ service_tier });
                 // GPT-5.6 and later report cache writes inside
                 // `prompt_tokens`, like cached reads; Chat Completions only
                 // writes the default 30m entries, billed at 1.25x input.
@@ -296,13 +320,17 @@ export class OpenAiChatProvider implements IChatProvider {
                     this.meteringModelKey(modelUsed.id),
                     modelUsed,
                     trackedUsage,
+                    { serviceSpeed },
                 );
                 setUsageCosts(metered.costs);
-                setUsageDetails(
-                    OpenAiUtil.usageDetailsFromTrackedUsage(metered.usage, {
+                setUsageDetails({
+                    ...OpenAiUtil.usageDetailsFromTrackedUsage(metered.usage, {
                         writeTtl: '30m',
                     })!,
-                );
+                    ...(params.serviceSpeed !== undefined
+                        ? { serviceSpeed }
+                        : {}),
+                });
                 return metered.usage;
             },
             stream,

src/backend/drivers/ai-chat/providers/openai/OpenAiChatResponsesProvider.ts

@@ -19,6 +19,7 @@
 
 import { OpenAI } from 'openai';
 import { ResponseCreateParams } from 'openai/resources/responses/responses.mjs';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import type {
@@ -134,38 +135,42 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
         return rate ? { extraCost: rate } : {};
     }
 
-    async complete({
-        messages,
-        model,
-        max_tokens,
-        moderation,
-        tools,
-        tool_choice,
-        parallel_tool_calls,
-        include,
-        conversation,
-        compaction,
-        context_management,
-        previous_response_id,
-        instructions,
-        metadata,
-        prompt,
-        prompt_cache_key,
-        prompt_cache_retention,
-        prompt_cache_options,
-        store,
-        top_p,
-        truncation,
-        background,
-        service_tier,
-        verbosity,
-        stream,
-        reasoning,
-        reasoning_effort,
-        temperature,
-        text,
-        outputFormat,
-    }: ICompleteArguments): ReturnType<IChatProvider['complete']> {
+    async complete(
+        {
+            messages,
+            model,
+            max_tokens,
+            moderation,
+            tools,
+            tool_choice,
+            parallel_tool_calls,
+            include,
+            conversation,
+            compaction,
+            context_management,
+            previous_response_id,
+            instructions,
+            metadata,
+            prompt,
+            prompt_cache_key,
+            prompt_cache_retention,
+            prompt_cache_options,
+            store,
+            top_p,
+            truncation,
+            background,
+            service_tier,
+            serviceSpeed: requestedServiceSpeed,
+            verbosity,
+            stream,
+            reasoning,
+            reasoning_effort,
+            temperature,
+            text,
+            outputFormat,
+        }: ICompleteArguments,
+        resolved?: IChatModel,
+    ): ReturnType<IChatProvider['complete']> {
         // Validate messages
         if (!Array.isArray(messages)) {
             throw new HttpError(400, '`messages` must be an array', {
@@ -183,12 +188,13 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
         model = model ?? this.#defaultModel;
 
         const modelUsed =
-            this.models({ no_restrictions: true }).find((m) =>
+            resolved ??
+            (this.models({ no_restrictions: true }).find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
             ) ||
-            this.models({ no_restrictions: true }).find(
-                (m) => m.id === this.getDefaultModel(),
-            )!;
+                this.models({ no_restrictions: true }).find(
+                    (m) => m.id === this.getDefaultModel(),
+                )!);
 
         // messages.unshift({
         //     role: 'system',
@@ -322,6 +328,7 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
         return OpenAiUtil.handle_completion_output_responses_api({
             usage_calculator: ({
                 usage,
+                service_tier,
                 webSearchCalls,
                 setUsageCosts,
                 setUsageDetails,
@@ -347,23 +354,31 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
                     // model is a reasoning model, not a static per-model
                     // cost-table entry — the model's rates would otherwise
                     // price it (wrongly) at the input/output token rate.
-                    webSearchCalls
-                        ? {
-                              costOverrides: {
-                                  web_search_calls:
-                                      webSearchCalls *
-                                      (webSearchCallRate(tools, modelUsed.id) ??
-                                          0),
-                              },
-                          }
-                        : {},
+                    {
+                        serviceSpeed: servedServiceSpeed({ service_tier }),
+                        ...(webSearchCalls
+                            ? {
+                                  costOverrides: {
+                                      web_search_calls:
+                                          webSearchCalls *
+                                          (webSearchCallRate(
+                                              tools,
+                                              modelUsed.id,
+                                          ) ?? 0),
+                                  },
+                              }
+                            : {}),
+                    },
                 );
                 setUsageCosts?.(metered.costs);
-                setUsageDetails?.(
-                    OpenAiUtil.usageDetailsFromTrackedUsage(metered.usage, {
+                setUsageDetails?.({
+                    ...(requestedServiceSpeed !== undefined
+                        ? { serviceSpeed: servedServiceSpeed({ service_tier }) }
+                        : {}),
+                    ...OpenAiUtil.usageDetailsFromTrackedUsage(metered.usage, {
                         writeTtl: '30m',
                     })!,
-                );
+                });
                 return metered.usage;
             },
             stream,

src/backend/drivers/ai-chat/providers/openai/models.ts

@@ -46,6 +46,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 100,
@@ -72,6 +73,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2, ultrafast: 6 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -98,6 +100,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -124,6 +127,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 10,
@@ -150,6 +154,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2, ultrafast: 6 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 1000,
@@ -176,6 +181,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
         // OpenAI's promotional pricing, guaranteed only through 2026-11-21.
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 400,
@@ -201,6 +207,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -226,6 +233,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 20,
@@ -251,6 +259,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 1250,
+                cached_tokens: 125,
+                completion_tokens: 7500,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 500,
@@ -295,6 +310,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 500,
+                cached_tokens: 50,
+                completion_tokens: 3000,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -338,6 +360,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 150,
+                cached_tokens: 15,
+                completion_tokens: 900,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 75,
@@ -425,6 +454,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 350,
+                cached_tokens: 35,
+                completion_tokens: 2800,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 175,
@@ -446,6 +482,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 250,
+                cached_tokens: 25,
+                completion_tokens: 2000,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -467,6 +510,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 425,
+                cached_tokens: 212.5,
+                completion_tokens: 1700,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -490,6 +540,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 25,
+                cached_tokens: 12.5,
+                completion_tokens: 100,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -509,6 +566,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 350,
+                cached_tokens: 87.5,
+                completion_tokens: 1400,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -530,6 +594,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 70,
+                cached_tokens: 17.5,
+                completion_tokens: 280,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -571,6 +642,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 425,
+                cached_tokens: 212.5,
+                completion_tokens: 1700,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,

src/backend/drivers/ai-chat/providers/openrouter/OpenRouterProvider.test.ts

@@ -20,15 +20,14 @@
 /**
  * Offline unit tests for OpenRouterProvider.
  *
- * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock
- * redis) and constructs OpenRouterProvider directly against the live
- * wired `MeteringService` so the recording side is exercised end-to-
- * end. OpenRouter is OpenAI-compatible, so the OpenAI SDK is mocked
- * at the module boundary; the model catalog is fetched via `axios`
- * which is mocked at its module boundary too. Both are the real
- * network egress points.
- * The companion integration test (OpenRouterProvider.integration.test.ts)
- * exercises the real OpenRouter endpoint.
+ * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock redis) and
+ * constructs OpenRouterProvider directly against the live wired
+ * `MeteringService` so the recording side is exercised end-to- end. OpenRouter
+ * is OpenAI-compatible, so the OpenAI SDK is mocked at the module boundary; the
+ * model catalog is fetched via `axios` which is mocked at its module boundary
+ * too. Both are the real network egress points. The companion integration test
+ * (OpenRouterProvider.integration.test.ts) exercises the real OpenRouter
+ * endpoint.
  */
 
 import { Writable } from 'node:stream';
@@ -300,16 +299,20 @@ describe('OpenRouterProvider model catalog', () => {
     it('coerces string prices and normalizes conditional tiers', async () => {
         const { provider } = makeProvider();
         const models = await provider.models();
-        const sol = models.find((m) => m.id === 'openrouter:openai/gpt-6.1-sol')!;
+        const sol = models.find(
+            (m) => m.id === 'openrouter:openai/gpt-6.1-sol',
+        )!;
         expect(sol.costs).toEqual({
             tokens: 1_000_000,
             prompt: 200,
             completion: 1000,
         });
-        expect(sol.pricingOverrides).toEqual([{
-            minPromptTokens: 272000,
-            costs: { prompt: 400, completion: 1500 },
-        }]);
+        expect(sol.pricingOverrides).toEqual([
+            {
+                minPromptTokens: 272000,
+                costs: { prompt: 400, completion: 1500 },
+            },
+        ]);
     });
 
     it('caches the coerced model list after the first axios round-trip', async () => {
@@ -368,9 +371,12 @@ describe('OpenRouterProvider model catalog', () => {
 
     it('does not reinterpret catalog-added timestamps as release dates', async () => {
         const { provider } = makeProvider();
-        expect((await provider.models()).every(model => model.release_date === undefined)).toBe(true);
+        expect(
+            (await provider.models()).every(
+                (model) => model.release_date === undefined,
+            ),
+        ).toBe(true);
     });
-
 });
 
 // ── Disallowed model gate ───────────────────────────────────────────
@@ -868,11 +874,14 @@ describe('OpenRouterProvider billed cost through the driver', () => {
             event.factor = factor;
         };
         server.clients.event.on('ai.cost.factor.*', listener as never);
-        return () => server.clients.event.off('ai.cost.factor.*', listener as never);
+        return () =>
+            server.clients.event.off('ai.cost.factor.*', listener as never);
     };
 
-    /** µ¢ the ledger was handed for every usage recorded so far. */
-    const ledgerTotal = (spy: MockInstance<MeteringService['batchIncrementUsages']>) =>
+    /** Μ¢ the ledger was handed for every usage recorded so far. */
+    const ledgerTotal = (
+        spy: MockInstance<MeteringService['batchIncrementUsages']>,
+    ) =>
         spy.mock.calls
             .flatMap(([, usages]) => usages)
             .reduce((total, usage) => total + (usage.costOverride ?? 0), 0);
@@ -928,7 +937,10 @@ describe('OpenRouterProvider billed cost through the driver', () => {
     it('reports what a billed completion was charged, after the cost factor', async () => {
         const driver = await makeDriver();
         const stopFactor = withCostFactor(1.6);
-        const recorded = vi.spyOn(server.services.metering, 'batchIncrementUsages');
+        const recorded = vi.spyOn(
+            server.services.metering,
+            'batchIncrementUsages',
+        );
         createMock.mockResolvedValueOnce({
             choices: [
                 {
@@ -1023,7 +1035,10 @@ describe('OpenRouterProvider billed cost through the driver', () => {
     it('ends a stream with what it was charged at the catalog rates, after the cost factor', async () => {
         const driver = await makeDriver();
         const stopFactor = withCostFactor(1.6);
-        const recorded = vi.spyOn(server.services.metering, 'batchIncrementUsages');
+        const recorded = vi.spyOn(
+            server.services.metering,
+            'batchIncrementUsages',
+        );
         createMock.mockReturnValueOnce(
             asAsyncIterable([
                 { choices: [{ delta: { content: 'hello' } }] },
@@ -1126,31 +1141,180 @@ describe('OpenRouterProvider.checkModeration', () => {
     });
 });
 
-
 describe('OpenRouter catalog refresh validation', () => {
     it('keeps missing model fields and prices unknown and blocks unpriced inference', async () => {
-        axiosRequestMock.mockResolvedValue({ data: { data: [{ id: 'fixture/model', name: 'Fixture' }] } });
+        axiosRequestMock.mockResolvedValue({
+            data: { data: [{ id: 'fixture/model', name: 'Fixture' }] },
+        });
         const { provider } = makeProvider();
         const [model] = await provider.models();
         expect(model.costs).toEqual({ tokens: 1_000_000 });
         expect(model.context).toBeUndefined();
         expect(model.max_tokens).toBe(0);
-        await expect(withTestActor(() => provider.complete({ model: 'openrouter:fixture/model', messages: [] })))
-            .rejects.toMatchObject({ legacyCode: 'model_pricing_unavailable' });
+        await expect(
+            withTestActor(() =>
+                provider.complete({
+                    model: 'openrouter:fixture/model',
+                    messages: [],
+                }),
+            ),
+        ).rejects.toMatchObject({ legacyCode: 'model_pricing_unavailable' });
         expect(createMock).not.toHaveBeenCalled();
     });
 
-    it.each(['malformed', 'failed', 'ambiguous conditional price'])('retains last-good data after a %s refresh', async failure => {
-        vi.useFakeTimers({ toFake: ['Date'] });
-        vi.spyOn(console, 'warn').mockImplementation(() => {});
+    it.each(['malformed', 'failed', 'ambiguous conditional price'])(
+        'retains last-good data after a %s refresh',
+        async (failure) => {
+            vi.useFakeTimers({ toFake: ['Date'] });
+            vi.spyOn(console, 'warn').mockImplementation(() => {});
+            const { provider } = makeProvider();
+            const good = await provider.models();
+            vi.advanceTimersByTime(15 * 60 * 1000 + 1);
+            if (failure === 'failed')
+                axiosRequestMock.mockRejectedValueOnce(
+                    new Error('unavailable'),
+                );
+            else if (failure === 'malformed')
+                axiosRequestMock.mockResolvedValueOnce({ data: {} });
+            else
+                axiosRequestMock.mockResolvedValueOnce({
+                    data: {
+                        data: [
+                            {
+                                ...SAMPLE_API_MODELS[0],
+                                pricing: {
+                                    prompt: '0.000002',
+                                    overrides: [
+                                        { min_prompt_tokens: 10, prompt: '' },
+                                    ],
+                                },
+                            },
+                        ],
+                    },
+                });
+            expect(await provider.models()).toBe(good);
+        },
+    );
+});
+
+describe('OpenRouter service speed offerings', () => {
+    it('loads and caches tier prices while reserving for endpoint and context differences', async () => {
         const { provider } = makeProvider();
-        const good = await provider.models();
-        vi.advanceTimersByTime(15 * 60 * 1000 + 1);
-        if (failure === 'failed') axiosRequestMock.mockRejectedValueOnce(new Error('unavailable'));
-        else if (failure === 'malformed') axiosRequestMock.mockResolvedValueOnce({ data: {} });
-        else axiosRequestMock.mockResolvedValueOnce({ data: { data: [{ ...SAMPLE_API_MODELS[0], pricing: {
-            prompt: '0.000002', overrides: [{ min_prompt_tokens: 10, prompt: '' }],
-        } }] } });
-        expect(await provider.models()).toBe(good);
+        const base = {
+            ...(await provider.models())[0],
+            provider: 'openrouter',
+        };
+        axiosRequestMock.mockClear();
+        axiosRequestMock.mockResolvedValueOnce({
+            data: {
+                data: {
+                    endpoints: [
+                        {
+                            service_tier: 'priority',
+                            pricing: {
+                                prompt: '0.000004',
+                                completion: '0.00002',
+                                input_cache_read: '0.0000002',
+                            },
+                        },
+                        {
+                            service_tier: 'priority',
+                            pricing: {
+                                prompt: '0.000005',
+                                completion: '0.00001',
+                            },
+                        },
+                        {
+                            service_tier: 'ultrafast',
+                            pricing: {
+                                prompt: '0.000012',
+                                completion: '0.00006',
+                                overrides: [
+                                    {
+                                        min_prompt_tokens: 272000,
+                                        prompt: '0.000024',
+                                        completion: '0.00009',
+                                    },
+                                ],
+                            },
+                        },
+                        {
+                            service_tier: 'priority',
+                            pricing: { prompt: 'invalid' },
+                        },
+                    ],
+                },
+            },
+        });
+        const offers = await provider.serviceSpeedModels(base);
+        expect(offers.fast?.costs).toMatchObject({
+            prompt: 500,
+            completion: 2000,
+            input_cache_read: 20,
+        });
+        expect(offers.ultrafast?.costs).toMatchObject({
+            prompt: 2400,
+            completion: 9000,
+        });
+        expect(await provider.serviceSpeedModels(base)).toBe(offers);
+        expect(axiosRequestMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('uses standard when the tier catalog cannot be fetched', async () => {
+        const { provider } = makeProvider();
+        const base = {
+            ...(await provider.models())[0],
+            provider: 'openrouter',
+        };
+        axiosRequestMock.mockRejectedValueOnce(new Error('Unavailable'));
+        expect(await provider.serviceSpeedModels(base)).toEqual({});
+    });
+});
+
+describe('OpenRouter speed billing', () => {
+    it('requires an authoritative bill instead of charging the reservation ceiling', async () => {
+        const { selectServiceSpeed } =
+            await import('../../utils/serviceSpeed.js');
+        const { provider } = makeProvider();
+        const base = {
+            ...(await provider.models())[0],
+            provider: 'openrouter',
+        };
+        const selected = selectServiceSpeed(
+            base,
+            {
+                model: base.id,
+                messages: [{ role: 'user', content: 'Hello' }],
+                serviceSpeed: 'fast',
+            },
+            () => undefined,
+            {
+                fast: {
+                    ...base,
+                    costs: { ...base.costs, prompt: 500, completion: 2000 },
+                },
+            },
+        );
+        const completion = {
+            choices: [
+                {
+                    index: 0,
+                    message: { role: 'assistant', content: 'OK' },
+                    finish_reason: 'stop',
+                },
+            ],
+            usage: { prompt_tokens: 10, completion_tokens: 1 },
+        };
+        createMock.mockResolvedValueOnce({
+            ...completion,
+            service_tier: 'priority',
+            usage: { ...completion.usage, cost: undefined },
+        });
+        await expect(
+            withTestActor(() =>
+                provider.complete(selected.args, selected.model),
+            ),
+        ).rejects.toMatchObject({ legacyCode: 'model_pricing_unavailable' });
+        expect(recordSpy).not.toHaveBeenCalled();
     });
 });

src/backend/drivers/ai-chat/providers/openrouter/OpenRouterProvider.ts

@@ -22,8 +22,10 @@ import { OpenAI } from 'openai';
 import { HttpError, isHttpError } from '../../../../core/http/HttpError.js';
 import { UpstreamResponseError } from '../../../util/upstreamErrors.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
-import type { IChatModel, ICompleteArguments } from '../../types.js';
+import type { IChatModel, ICompleteArguments, ModelCost } from '../../types.js';
+import { BoundedTtlMap } from '../../../../util/boundedTtlMap.js';
 import { cachedRemoteCatalog } from '../../utils/cachedRemoteCatalog.js';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { catalogPrice } from '../../utils/pricing.js';
 import { mapOpenRouterPricing } from './pricing.js';
 import { sdkClientOptions } from '../../utils/sdkClient.js';
@@ -64,6 +66,75 @@ const isPolicyBlock = (err: unknown): boolean => {
 export class OpenRouterProvider extends OpenAICompatProvider {
     #apiBaseUrl: string;
 
+    #speedCatalogs = new BoundedTtlMap<
+        string,
+        () => Promise<Partial<Record<'fast' | 'ultrafast', IChatModel>>>
+    >({ maxEntries: 256 });
+
+    async serviceSpeedModels(model: IChatModel) {
+        let load = this.#speedCatalogs.get(model.id);
+        if (!load) {
+            load = cachedRemoteCatalog({
+                name: 'OpenRouter speed catalog',
+                fallback: {} as Partial<
+                    Record<'fast' | 'ultrafast', IChatModel>
+                >,
+                fetch: async (signal) => {
+                    const id = model.id.replace(/^openrouter:/, '');
+                    const response = await axios.request({
+                        url: `${this.#apiBaseUrl}/models/${id}/endpoints`,
+                        method: 'GET',
+                        signal,
+                        maxContentLength: 2 * 1024 * 1024,
+                    });
+                    const offers: Partial<
+                        Record<'fast' | 'ultrafast', IChatModel>
+                    > = {};
+                    for (const endpoint of response.data?.data?.endpoints ??
+                        []) {
+                        const speed =
+                            endpoint.service_tier === 'ultrafast'
+                                ? 'ultrafast'
+                                : ['priority', 'fast'].includes(
+                                        endpoint.service_tier,
+                                    )
+                                  ? 'fast'
+                                  : undefined;
+                        if (!speed || !endpoint.pricing) continue;
+                        const pricing = mapOpenRouterPricing(endpoint.pricing);
+                        if (
+                            pricing.costs.prompt === undefined ||
+                            pricing.costs.completion === undefined
+                        )
+                            continue;
+                        // Reserve for the most expensive eligible endpoint and context tier.
+                        const costs: ModelCost = {
+                            ...offers[speed]?.costs,
+                            tokens: model.costs.tokens,
+                        };
+                        for (const rates of [
+                            pricing.costs,
+                            ...pricing.overrides.map(
+                                (override) => override.costs,
+                            ),
+                        ]) {
+                            for (const [key, value] of Object.entries(rates))
+                                costs[key] = Math.max(costs[key] ?? 0, value);
+                        }
+                        offers[speed] = {
+                            ...model,
+                            costs,
+                            pricingOverrides: [],
+                        };
+                    }
+                    return offers;
+                },
+            });
+            this.#speedCatalogs.set(model.id, load);
+        }
+        return load();
+    }
+
     constructor(config: ChatProviderConfig, meteringService: MeteringService) {
         const apiBaseUrl = config.apiBaseUrl || 'https://openrouter.ai/api/v1';
         super(meteringService, {
@@ -202,8 +273,17 @@ export class OpenRouterProvider extends OpenAICompatProvider {
         return { ...params, usage: { include: true } };
     }
 
-    protected override meteredUsage(source: UsageSource) {
+    protected override meteredUsage(source: UsageSource, model: IChatModel) {
         const usage = source.usage as OpenrouterUsage;
+        if (
+            model.serviceSpeedPricing &&
+            servedServiceSpeed(source) !== 'standard' &&
+            catalogPrice(usage.cost) === undefined
+        ) {
+            throw new HttpError(503, 'Service tier billing is unavailable', {
+                legacyCode: 'model_pricing_unavailable',
+            });
+        }
         return {
             usage: {
                 prompt:

src/backend/drivers/ai-chat/providers/xai/XAIProvider.test.ts

@@ -20,13 +20,12 @@
 /**
  * Offline unit tests for XAIProvider.
  *
- * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock
- * redis) and constructs XAIProvider directly against the live wired
- * `MeteringService` so the recording side is exercised end-to-end.
- * xAI is OpenAI-compatible so the OpenAI SDK is mocked at the module
- * boundary; that's the real network egress point. The companion
- * integration test (XAIProvider.integration.test.ts) exercises the
- * real xAI endpoint.
+ * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock redis) and
+ * constructs XAIProvider directly against the live wired `MeteringService` so
+ * the recording side is exercised end-to-end. xAI is OpenAI-compatible so the
+ * OpenAI SDK is mocked at the module boundary; that's the real network egress
+ * point. The companion integration test (XAIProvider.integration.test.ts)
+ * exercises the real xAI endpoint.
  */
 
 import { Writable } from 'node:stream';
@@ -933,8 +932,7 @@ describe('XAIProvider.complete non-stream output', () => {
         // namespace, actor, and a costsOverride priced from
         // models.ts (grok-4.6: prompt=200, completion=600, cached=50).
         expect(recordSpy).toHaveBeenCalledTimes(1);
-        const [usage, actor, prefix, overrides] =
-            recordSpy.mock.calls[0]!;
+        const [usage, actor, prefix, overrides] = recordSpy.mock.calls[0]!;
         expect(usage).toEqual({
             prompt_tokens: 90,
             completion_tokens: 50,
@@ -1022,8 +1020,7 @@ describe('XAIProvider.complete non-stream output', () => {
             }),
         );
 
-        const [usage, , , overrides] =
-            recordSpy.mock.calls[0]!;
+        const [usage, , , overrides] = recordSpy.mock.calls[0]!;
         expect(usage.cached_tokens).toBe(0);
         // 0 cached tokens × any rate = 0 metered cost.
         expect(overrides).toMatchObject({ cached_tokens: 0 });
@@ -1081,8 +1078,7 @@ describe('XAIProvider.complete streaming', () => {
 
         // grok-build-0.1 costs: prompt=100, completion=200, cached=20.
         expect(recordSpy).toHaveBeenCalledTimes(1);
-        const [, , prefix, overrides] =
-            recordSpy.mock.calls[0]!;
+        const [, , prefix, overrides] = recordSpy.mock.calls[0]!;
         expect(prefix).toBe('xai:grok-build-0.1');
         expect(overrides).toEqual({
             prompt_tokens: 3 * 100,
@@ -1200,3 +1196,60 @@ describe('XAIProvider.checkModeration', () => {
         );
     });
 });
+
+describe('xAI service speed billing', () => {
+    it('records the reported Priority charge with cached input and reasoning', async () => {
+        const { selectServiceSpeed } =
+            await import('../../utils/serviceSpeed.js');
+        const { provider } = makeProvider();
+        const base = {
+            ...(await provider.models()).find(
+                (entry) => entry.id === 'grok-4.7',
+            )!,
+            provider: 'xai',
+        };
+        const selected = selectServiceSpeed(
+            base,
+            {
+                model: base.id,
+                messages: [{ role: 'user', content: 'Hello' }],
+                serviceSpeed: 'ultrafast',
+            },
+            () => undefined,
+        );
+        createMock.mockResolvedValueOnce({
+            choices: [
+                {
+                    index: 0,
+                    message: { role: 'assistant', content: 'OK' },
+                    finish_reason: 'stop',
+                },
+            ],
+            service_tier: 'priority',
+            usage: {
+                prompt_tokens: 1247,
+                completion_tokens: 1,
+                total_tokens: 1282,
+                prompt_tokens_details: { cached_tokens: 1152 },
+                completion_tokens_details: { reasoning_tokens: 34 },
+                cost_in_usd_ticks: 19520000,
+            },
+        });
+        const result = await withTestActor(() =>
+            provider.complete(selected.args, selected.model),
+        );
+        expect(result).toMatchObject({
+            usageDetails: {
+                serviceSpeed: 'fast',
+                outputTokens: 35,
+                reasoningTokens: 34,
+            },
+        });
+        expect(recordSpy).toHaveBeenCalledWith(
+            expect.objectContaining({ billedUsage: 1, completion_tokens: 35 }),
+            expect.anything(),
+            'xai:grok-4.7',
+            expect.objectContaining({ billedUsage: 195200 }),
+        );
+    });
+});

src/backend/drivers/ai-chat/providers/xai/XAIProvider.ts

@@ -19,6 +19,8 @@
 
 import { OpenAI } from 'openai';
 import { ChatCompletionCreateParams } from 'openai/resources/index.js';
+import { catalogPrice } from '../../utils/pricing.js';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import * as OpenAIUtil from '../../utils/OpenAIUtil.js';
@@ -74,7 +76,15 @@ export class XAIProvider implements IChatProvider {
     }
 
     async complete(
-        { messages, stream, model, tools, max_tokens }: ICompleteArguments,
+        {
+            messages,
+            stream,
+            model,
+            tools,
+            max_tokens,
+            service_tier,
+            serviceSpeed: requestedServiceSpeed,
+        }: ICompleteArguments,
         resolved?: IChatModel,
     ): Promise<IChatCompleteResult> {
         const actor = Context.get('actor');
@@ -88,6 +98,7 @@ export class XAIProvider implements IChatProvider {
                 {
                     messages,
                     model: modelUsed.id,
+                    ...(service_tier !== undefined ? { service_tier } : {}),
                     ...(tools ? { tools } : {}),
                     ...(max_tokens !== undefined ? { max_tokens } : {}),
                     stream,
@@ -107,18 +118,49 @@ export class XAIProvider implements IChatProvider {
         }
 
         return OpenAIUtil.handle_completion_output({
-            usage_calculator: ({ usage, setUsageCosts }) => {
+            usage_calculator: ({
+                usage,
+                service_tier: servedTier,
+                setUsageCosts,
+                setUsageDetails,
+            }) => {
+                const serviceSpeed = servedServiceSpeed({
+                    service_tier: servedTier,
+                });
                 // xAI reports cached reads inside `prompt_tokens`; bill them
                 // only at the cached rate.
                 const metered = OpenAIUtil.extractMeteredUsage(usage);
+                const reasoningTokens =
+                    usage.completion_tokens_details?.reasoning_tokens ?? 0;
+                const trackedUsage = OpenAIUtil.splitCachedPrompt(usage);
+                trackedUsage.completion_tokens += reasoningTokens;
+                const reportedTicks = catalogPrice(
+                    (usage as typeof usage & { cost_in_usd_ticks?: number })
+                        .cost_in_usd_ticks,
+                );
                 const { costs } = meterChatUsage(
                     this.#meteringService,
                     actor,
                     this.meteringModelKey(modelUsed.id),
                     modelUsed,
-                    OpenAIUtil.splitCachedPrompt(usage),
+                    trackedUsage,
+                    {
+                        serviceSpeed,
+                        authoritativeUsd:
+                            reportedTicks === undefined
+                                ? undefined
+                                : reportedTicks / 10_000_000_000,
+                    },
                 );
                 setUsageCosts(costs);
+                if (requestedServiceSpeed !== undefined)
+                    setUsageDetails?.({
+                        ...OpenAIUtil.usageDetailsFromTrackedUsage(
+                            trackedUsage,
+                        )!,
+                        serviceSpeed,
+                        ...(reasoningTokens ? { reasoningTokens } : {}),
+                    });
                 return metered;
             },
             stream,

src/backend/drivers/ai-chat/providers/xai/models.ts

@@ -42,6 +42,7 @@ export const XAI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -65,6 +66,7 @@ export const XAI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -87,6 +89,7 @@ export const XAI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -109,6 +112,7 @@ export const XAI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -151,6 +155,7 @@ export const XAI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -186,6 +191,7 @@ export const XAI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -217,6 +223,7 @@ export const XAI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -246,6 +253,7 @@ export const XAI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 100,

src/backend/drivers/ai-chat/types.ts

@@ -26,6 +26,8 @@
 
 export type ModelCost = Record<string, number>;
 
+export type ServiceSpeed = 'standard' | 'fast' | 'ultrafast';
+
 export interface ModelModalities {
     input: string[];
     output: string[];
@@ -67,6 +69,22 @@ export interface IChatModel<T extends ModelCost = ModelCost> extends Record<
         output_multiplier: number;
     };
     pricingOverrides?: ModelPricingOverride[];
+    /**
+     * A token-rate multiplier or explicit per-key rates merged with standard
+     * costs.
+     */
+    serviceSpeedRates?: Partial<
+        Record<'fast' | 'ultrafast', number | ModelCost>
+    >;
+    serviceSpeedVariants?: { fast?: string };
+    /** Request-local pricing snapshot; never part of the model catalog. */
+    serviceSpeedPricing?: {
+        speed: ServiceSpeed;
+        standardCosts: ModelCost;
+        standardOverrides?: ModelPricingOverride[];
+        fastCosts?: ModelCost;
+        ultrafastCosts?: ModelCost;
+    };
     context?: number;
     max_tokens: number;
     subscriberOnly?: boolean;
@@ -76,6 +94,8 @@ export interface IChatModel<T extends ModelCost = ModelCost> extends Record<
     tool_call?: boolean;
     responses_api?: boolean;
     responses_api_only?: boolean;
+    /** Restricts service speeds for deployments with a limited API dialect. */
+    serviceSpeeds?: ServiceSpeed[];
     /**
      * Omitted preserves sampling; reasoningDisabled requires explicit effort
      * none.
@@ -163,6 +183,7 @@ export interface UsageDetails {
     webFetchRequests?: number;
     speed?: 'fast' | 'standard';
     serviceTier?: string;
+    serviceSpeed?: ServiceSpeed;
     /**
      * Per-pass breakdown when the upstream ran several passes (compaction,
      * advisor).
@@ -198,6 +219,7 @@ export interface ICompleteArguments {
      * request on another provider that serves the same model.
      */
     fallback?: boolean;
+    serviceSpeed?: ServiceSpeed;
     stream?: boolean;
     model: string;
     test_mode?: boolean;
@@ -217,10 +239,7 @@ export interface ICompleteArguments {
     taskBudget?: { total: number; remaining?: number };
     /** Claude only: top-level automatic `cache_control`. */
     cacheControl?: CacheControl;
-    /**
-     * Claude only; forwarded only when the model's catalog entry has
-     * `fast_output_tokens`.
-     */
+    /** Claude only; fast is forwarded when the catalog declares fast rates. */
     speed?: 'fast' | 'standard';
     /** Claude only. */
     safeguards?: SafeguardRequest[];
@@ -260,7 +279,15 @@ export interface ICompleteArguments {
     truncation?: 'auto' | 'disabled' | undefined;
     background?: boolean;
     service_tier?:
-        'auto' | 'default' | 'flex' | 'scale' | 'priority' | undefined;
+        | 'auto'
+        | 'default'
+        | 'flex'
+        | 'scale'
+        | 'priority'
+        | 'fast'
+        | 'ultrafast'
+        | 'standard'
+        | undefined;
     max_tokens?: number;
     temperature?: number;
     reasoning?: { effort: ReasoningEffort } | undefined;
@@ -328,6 +355,10 @@ export interface IChatMessageResult {
 export type IChatCompleteResult = IChatStreamResult | IChatMessageResult;
 
 export interface IChatProvider {
+    /** Account/catalog-specific speed offerings, fetched before the credit hold. */
+    serviceSpeedModels?(
+        model: IChatModel,
+    ): Promise<Partial<Record<'fast' | 'ultrafast', IChatModel>>>;
     models(extra_params?: unknown): IChatModel[] | Promise<IChatModel[]>;
     getDefaultModel(): string;
     /**

src/backend/drivers/ai-chat/utils/OpenAIUtil.js

@@ -650,12 +650,15 @@ export const create_chat_stream_handler =
             block.end();
         };
 
+        let serviceTier;
         let last_usage = null;
         let last_extra_content = null;
         let finish_reason = null;
         for await (let chunk of completion) {
             await chatStream.waitForDrain();
             chunk = deviations.chunk_but_like_actually(chunk);
+            if (chunk.service_tier !== undefined)
+                serviceTier = chunk.service_tier;
             const chunk_usage = deviations.index_usage_from_stream_chunk(chunk);
             if (chunk_usage) last_usage = chunk_usage;
             if (chunk.choices.length < 1) continue;
@@ -746,6 +749,7 @@ export const create_chat_stream_handler =
         const usage = last_usage
             ? usage_calculator({
                   usage: last_usage,
+                  service_tier: serviceTier,
                   extra_content: last_extra_content,
                   setUsageCosts: (c) => chatStream.setUsageCosts(c),
                   setUsageDetails: (d) => {
@@ -779,6 +783,7 @@ export const create_chat_stream_handler_responses_api =
         const message = chatStream.message();
         const textblock = message.contentBlock({ type: 'text' });
 
+        let serviceTier;
         let last_usage = null;
         let completed = false;
         let sawFunctionCall = false;
@@ -787,6 +792,8 @@ export const create_chat_stream_handler_responses_api =
         let toolUsage = null;
         for await (const chunk of completion) {
             await chatStream.waitForDrain();
+            if (chunk.response?.service_tier !== undefined)
+                serviceTier = chunk.response.service_tier;
             if (chunk.type === 'response.failed' || chunk.type === 'error') {
                 throw new Error(
                     chunk.response?.error?.message ??
@@ -918,6 +925,7 @@ export const create_chat_stream_handler_responses_api =
         const usage = last_usage
             ? usage_calculator({
                   usage: last_usage,
+                  service_tier: serviceTier,
                   webSearchCalls,
                   tool_usage: toolUsage,
                   setUsageCosts: (c) => chatStream.setUsageCosts(c),
@@ -972,6 +980,7 @@ export const handle_completion_output = async (
     /**
      * @type {Record<string, unknown> & {
      *     usage_calculator: (args: {
+     *         service_tier?: string;
      *         usage: import('openai/resources/completions.mjs').CompletionUsage;
      *         setUsageCosts: (costs: Record<string, number>) => void;
      *         setUsageDetails: (
@@ -1066,6 +1075,7 @@ export const handle_completion_output = async (
  * @param {((text: string) => Promise<{ flagged: boolean }>) | undefined} [params.moderate]
  * @param {(args: {
  *     usage: import('openai/resources/responses/responses.mjs').ResponseUsage;
+ *     service_tier?: string;
  *     webSearchCalls?: number;
  *     tool_usage?: Record<string, unknown>;
  *     setUsageCosts?: (costs: Record<string, number>) => void;

src/backend/drivers/ai-chat/utils/meterChatUsage.ts

@@ -19,13 +19,15 @@
 
 import type { Actor } from '../../../core/actor.js';
 import type { MeteringService } from '../../../services/metering/MeteringService.js';
-import type { IChatModel } from '../types.js';
+import type { IChatModel, ServiceSpeed } from '../types.js';
+import { serviceSpeedBillingModel } from './serviceSpeed.js';
 import { buildCostsOverride } from './pricing.js';
 
 /** Microcents per US dollar. */
 const MICROCENTS_PER_USD = 100_000_000;
 
 export interface MeterChatUsageOptions {
+    serviceSpeed?: ServiceSpeed;
     /**
      * What the upstream says it billed, in USD. Recorded as one `billedUsage`
      * line instead of pricing the tokens, which are still recorded at zero.
@@ -77,10 +79,15 @@ export const meterChatUsage = (
         authoritativeUsd,
         costOverrides,
         pricingTime,
+        serviceSpeed = 'standard',
     }: MeterChatUsageOptions = {},
 ): { usage: Record<string, number>; costs: Record<string, number> } => {
     const priced = {
-        ...buildCostsOverride(usage, model, pricingTime),
+        ...buildCostsOverride(
+            usage,
+            serviceSpeedBillingModel(model, serviceSpeed),
+            pricingTime,
+        ),
         ...costOverrides,
     };
     if (authoritativeUsd !== undefined) {

src/backend/drivers/ai-chat/utils/serviceSpeed.fuzz.test.ts

@@ -0,0 +1,150 @@
+/*
+ * 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.
+ *
+ * Puter 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 Puter. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { IChatModel, ServiceSpeed } from '../types.js';
+import { ALIBABA_MODELS } from '../providers/alibaba/models.js';
+import { AZURE_MODELS } from '../providers/azure/models.js';
+import { BYTEPLUS_MODELS } from '../providers/byteplus/models.js';
+import { CLAUDE_MODELS } from '../providers/claude/models.js';
+import { DEEPSEEK_MODELS } from '../providers/deepseek/models.js';
+import { GEMINI_MODELS } from '../providers/gemini/models.js';
+import { GROQ_MODELS } from '../providers/groq/models.js';
+import { HOONIFY_MODELS } from '../providers/hoonify/models.js';
+import { META_MODELS } from '../providers/meta/models.js';
+import { MINIMAX_MODELS } from '../providers/minimax/models.js';
+import { MISTRAL_MODELS } from '../providers/mistral/models.js';
+import { MOONSHOT_MODELS } from '../providers/moonshot/models.js';
+import { OPEN_AI_MODELS } from '../providers/openai/models.js';
+import { XAI_MODELS } from '../providers/xai/models.js';
+import { ZAI_MODELS } from '../providers/zai/models.js';
+import { shouldPresentAsOpenAI } from './normalizeToOpenAI.js';
+import {
+    isServiceSpeedUnavailable,
+    lowerServiceSpeed,
+    selectServiceSpeed,
+    servedServiceSpeed,
+    serviceSpeedBillingModel,
+} from './serviceSpeed.js';
+
+const catalogs: Array<[string, IChatModel[]]> = [
+    ['alibaba', ALIBABA_MODELS],
+    ['azure-openai', AZURE_MODELS],
+    ['byteplus', BYTEPLUS_MODELS],
+    ['claude', CLAUDE_MODELS],
+    ['deepseek', DEEPSEEK_MODELS],
+    ['gemini', GEMINI_MODELS],
+    ['groq', GROQ_MODELS],
+    ['hoonify', HOONIFY_MODELS],
+    ['meta', META_MODELS],
+    ['minimax', MINIMAX_MODELS],
+    ['mistral', MISTRAL_MODELS],
+    ['moonshotai', MOONSHOT_MODELS],
+    ['openai-completion', OPEN_AI_MODELS],
+    ['openai-responses', OPEN_AI_MODELS],
+    ['xai', XAI_MODELS],
+    ['zai', ZAI_MODELS],
+];
+const speeds: ServiceSpeed[] = ['standard', 'fast', 'ultrafast'];
+
+describe('service speed seeded fuzzing', () => {
+    it('preserves catalog, request, normalization, and billing invariants across model changes', () => {
+        let seed = 0x51eed;
+        const pick = <T>(values: T[]): T => {
+            seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+            return values[seed % values.length]!;
+        };
+        const seenProviders = new Set<string>();
+        for (let index = 0; index < 10_000; index++) {
+            const [provider, catalog] = pick(catalogs);
+            seenProviders.add(provider);
+            const base = { ...structuredClone(pick(catalog)), provider };
+            const before = structuredClone(base);
+            Object.freeze(base.costs);
+            Object.freeze(base);
+            const args = Object.freeze({
+                model: base.id,
+                messages: [{ role: 'user', content: `Case ${index}` }],
+                serviceSpeed: pick([...speeds, undefined]),
+                normalize: pick([true, false, undefined]),
+                temperature: pick([0, 0.5, 1]),
+                service_tier: pick(['flex' as const, 'ultrafast' as const, undefined]),
+                speed: pick(['standard' as const, 'fast' as const, undefined]),
+            });
+            const selected = selectServiceSpeed(base, args, (id) => {
+                const variant = catalog.find((entry) => entry.id === id);
+                return variant && { ...variant, provider };
+            });
+            expect(base).toEqual(before);
+            expect(selected.args.messages).toBe(args.messages);
+            expect(selected.args.temperature).toBe(args.temperature);
+            expect(selected.model.provider).toBe(provider);
+            expect(selected.model.release_date).toBe(base.release_date);
+            expect(
+                shouldPresentAsOpenAI(selected.args, selected.model.release_date),
+            ).toBe(shouldPresentAsOpenAI(args, base.release_date));
+            if (args.serviceSpeed === undefined) {
+                expect(selected.args).toBe(args);
+                expect(selected.model).toBe(base);
+                continue;
+            }
+            expect(speeds.indexOf(selected.speed)).toBeLessThanOrEqual(
+                speeds.indexOf(args.serviceSpeed),
+            );
+            expect(selected.args.serviceSpeed).toBe(selected.speed);
+            if (args.serviceSpeed === 'standard') {
+                expect(selected.args.speed).not.toBe('fast');
+                expect(selected.args.service_tier).not.toBe('ultrafast');
+            }
+            for (const cost of Object.values(selected.model.costs)) {
+                expect(Number.isFinite(cost)).toBe(true);
+                expect(cost).toBeGreaterThanOrEqual(0);
+            }
+            if (selected.model.serviceSpeedPricing) {
+                const settled = serviceSpeedBillingModel(selected.model, 'standard');
+                expect(settled.costs).toEqual(base.costs);
+                expect(settled.pricingOverrides).toEqual(base.pricingOverrides);
+            }
+            let speed = selected.speed;
+            for (let attempts = 0; speed !== 'standard'; attempts++) {
+                expect(attempts).toBeLessThan(2);
+                speed = lowerServiceSpeed(speed);
+            }
+        }
+        expect([...seenProviders].sort()).toEqual(catalogs.map(([provider]) => provider).sort());
+    });
+
+    it('handles malformed upstream tier and admission-error metadata without coercion or retries', () => {
+        const values = [null, false, 0, 429, '', 'unrelated', [], {},
+            ['service_tier capacity unavailable'],
+            { toString: null }, { toString: 'priority capacity unavailable' }];
+        for (const value of values) {
+            expect(isServiceSpeedUnavailable(value)).toBe(false);
+            for (const status of [undefined, 400, 401, 403, 404, 429, 500, 503]) {
+                for (const variant of [false, true]) {
+                    expect(isServiceSpeedUnavailable({ status, message: value }, variant)).toBe(false);
+                    expect(isServiceSpeedUnavailable({ status, error: { message: value } }, variant)).toBe(false);
+                }
+            }
+            expect(servedServiceSpeed({ usage: value })).toBe('standard');
+            expect(servedServiceSpeed({ service_tier: value })).toBe('standard');
+            expect(servedServiceSpeed({ usage: { speed: value, service_tier: value } })).toBe('standard');
+        }
+    });
+});

src/backend/drivers/ai-chat/utils/serviceSpeed.integration.test.ts

@@ -0,0 +1,148 @@
+/*
+ * 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 {
+    makeMeteringStub,
+    optionalEnv,
+    withTestActor,
+} from '../../integrationTestUtil.js';
+import type {
+    IChatMessageResult,
+    IChatProvider,
+    ICompleteArguments,
+} from '../types.js';
+import { OpenAiResponsesChatProvider } from '../providers/openai/OpenAiChatResponsesProvider.js';
+import { GeminiChatProvider } from '../providers/gemini/GeminiChatProvider.js';
+import { MiniMaxProvider } from '../providers/minimax/MiniMaxProvider.js';
+import { MoonshotProvider } from '../providers/moonshot/MoonshotProvider.js';
+import { MistralAIProvider } from '../providers/mistral/MistralAiProvider.js';
+import { selectServiceSpeed } from './serviceSpeed.js';
+
+type Case = {
+    name: string;
+    env: string;
+    provider: string;
+    model: string;
+    build: (key: string) => IChatProvider;
+};
+const cases: Case[] = [
+    {
+        name: 'OpenAI Ultrafast',
+        env: 'PUTER_TEST_AI_OPENAI_API_KEY',
+        provider: 'openai-responses',
+        model: 'gpt-6.1-sol',
+        build: (key) =>
+            new OpenAiResponsesChatProvider(
+                { apiKey: key },
+                makeMeteringStub(),
+            ),
+    },
+    {
+        name: 'Gemini Priority',
+        env: 'PUTER_TEST_AI_GEMINI_API_KEY',
+        provider: 'gemini',
+        model: 'gemini-3.8-flash',
+        build: (key) =>
+            new GeminiChatProvider({ apiKey: key }, makeMeteringStub()),
+    },
+    {
+        name: 'MiniMax Priority',
+        env: 'PUTER_TEST_AI_MINIMAX_API_KEY',
+        provider: 'minimax',
+        model: 'minimax-m3',
+        build: (key) =>
+            new MiniMaxProvider({ apiKey: key }, makeMeteringStub()),
+    },
+    {
+        name: 'Moonshot Highspeed',
+        env: 'PUTER_TEST_AI_MOONSHOT_API_KEY',
+        provider: 'moonshotai',
+        model: 'kimi-k3.1-pro',
+        build: (key) =>
+            new MoonshotProvider({ apiKey: key }, makeMeteringStub()),
+    },
+    {
+        name: 'Mistral served tier',
+        env: 'PUTER_TEST_AI_MISTRAL_API_KEY',
+        provider: 'mistral',
+        model: 'mistral-medium-latest',
+        build: (key) =>
+            new MistralAIProvider({ apiKey: key }, makeMeteringStub()),
+    },
+];
+
+for (const testCase of cases) {
+    describe.skipIf(!optionalEnv(testCase.env))(
+        `serviceSpeed ${testCase.name} (integration)`,
+        () => {
+            it(
+                'completes with a selected speed and normalized text',
+                { timeout: 90_000 },
+                async () => {
+                    const provider = testCase.build(optionalEnv(testCase.env)!);
+                    const catalog = (await provider.models()).map((model) => ({
+                        ...model,
+                        provider: testCase.provider,
+                    }));
+                    const base = catalog.find(
+                        (model) =>
+                            model.id === testCase.model ||
+                            model.aliases?.includes(testCase.model),
+                    )!;
+                    expect(base).toBeDefined();
+                    const args: ICompleteArguments = {
+                        model: base.id,
+                        messages: [
+                            { role: 'user', content: 'Reply with exactly OK.' },
+                        ],
+                        serviceSpeed: 'ultrafast',
+                        max_tokens: 256,
+                        reasoning_effort: 'low',
+                        normalize: true,
+                    };
+                    const selection = selectServiceSpeed(base, args, (id) =>
+                        catalog.find((model) => model.id === id),
+                    );
+                    expect(selection.speed).toBe(
+                        testCase.provider === 'openai-responses'
+                            ? 'ultrafast'
+                            : 'fast',
+                    );
+                    const result = (await withTestActor(() =>
+                        provider.complete(
+                            { ...selection.args, model: selection.model.id },
+                            selection.model,
+                        ),
+                    )) as IChatMessageResult;
+                    expect(typeof result.message.content).toBe('string');
+                    expect(result.message.content.length).toBeGreaterThan(0);
+                    if (
+                        ['openai-responses', 'gemini', 'minimax'].includes(
+                            testCase.provider,
+                        )
+                    )
+                        expect(result.usageDetails?.serviceSpeed).toBe(
+                            selection.speed,
+                        );
+                },
+            );
+        },
+    );
+}

src/backend/drivers/ai-chat/utils/serviceSpeed.test.ts

@@ -0,0 +1,368 @@
+/*
+ * 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 { Writable } from 'node:stream';
+import { AIChatStream } from './Streaming.js';
+import {
+    handle_completion_output,
+    handle_completion_output_responses_api,
+} from './OpenAIUtil.js';
+import type { IChatModel, ServiceSpeed } from '../types.js';
+import {
+    selectServiceSpeed,
+    servedServiceSpeed,
+    serviceSpeedBillingModel,
+    isServiceSpeedUnavailable,
+} from './serviceSpeed.js';
+import { meterChatUsage } from './meterChatUsage.js';
+import { OPEN_AI_MODELS } from '../providers/openai/models.js';
+import { XAI_MODELS } from '../providers/xai/models.js';
+import { GEMINI_MODELS } from '../providers/gemini/models.js';
+import { CLAUDE_MODELS } from '../providers/claude/models.js';
+
+const model = (provider: string, id: string): IChatModel => ({
+    provider,
+    id,
+    serviceSpeedRates: [...OPEN_AI_MODELS, ...XAI_MODELS, ...GEMINI_MODELS, ...CLAUDE_MODELS]
+        .find((entry) => entry.id === id)?.serviceSpeedRates,
+    costs_currency: 'usd-cents',
+    input_cost_key: 'prompt_tokens',
+    output_cost_key: 'completion_tokens',
+    max_tokens: 1000,
+    costs: {
+        tokens: 1_000_000,
+        prompt_tokens: 200,
+        completion_tokens: 1000,
+        cached_tokens: 10,
+        web_search_requests: 1_000_000,
+    },
+});
+const request = (serviceSpeed?: ServiceSpeed) => ({
+    model: 'test',
+    messages: [{ role: 'user', content: 'Hello' }],
+    serviceSpeed,
+});
+const noVariant = () => undefined;
+
+describe('service speed selection', () => {
+    it.each([2, { prompt_tokens: 400, completion_tokens: 2000 }])(
+        'uses catalog rates independently of provider and model names: %j',
+        (rates) => {
+            const entry = {
+                ...model('catalog-provider', 'renamed-model'),
+                serviceSpeedRates: { fast: rates },
+            };
+            const selected = selectServiceSpeed(entry, request('ultrafast'), noVariant);
+            expect(selected.speed).toBe('fast');
+            expect(selected.model.costs.prompt_tokens).toBe(400);
+            expect(selected.model.costs.completion_tokens).toBe(2000);
+            expect(entry.costs.prompt_tokens).toBe(200);
+        },
+    );
+    it('preserves an omitted option and native parameters', () => {
+        const entry = model('openai-responses', 'gpt-6.1-sol');
+        const args = { ...request(), service_tier: 'flex' as const };
+        const selected = selectServiceSpeed(entry, args, noVariant);
+        expect(selected.model).toBe(entry);
+        expect(selected.args).toBe(args);
+    });
+    it.each([
+        'deepseek',
+        'zai',
+        'groq',
+        'byteplus',
+        'together-ai',
+        'meta',
+        'ollama',
+        'hoonify',
+        'neuralwatt',
+        'fake-chat',
+    ])('uses standard when %s has no verified faster offering', (provider) => {
+        const selected = selectServiceSpeed(
+            model(provider, 'some-model'),
+            request('ultrafast'),
+            noVariant,
+        );
+        expect(selected.speed).toBe('standard');
+        expect(selected.args.service_tier).toBeUndefined();
+    });
+    it.each(['standard', 'fast', 'ultrafast'] as const)(
+        'selects %s without changing the model or catalog prices',
+        (speed) => {
+            const entry = model('openai-responses', 'gpt-6.1-sol');
+            const selected = selectServiceSpeed(
+                entry,
+                request(speed),
+                noVariant,
+            );
+            expect(selected.speed).toBe(speed);
+            expect(selected.model.id).toBe(entry.id);
+            expect(selected.model.costs.prompt_tokens).toBe(
+                200 * { standard: 1, fast: 2, ultrafast: 6 }[speed],
+            );
+            expect(selected.model.costs.web_search_requests).toBe(1_000_000);
+            expect(entry.costs.prompt_tokens).toBe(200);
+        },
+    );
+    it('downgrades ultrafast to fast on a model without ultrafast', () => {
+        const selected = selectServiceSpeed(
+            model('xai', 'grok-4.7'),
+            request('ultrafast'),
+            noVariant,
+        );
+        expect(selected.speed).toBe('fast');
+        expect(selected.args.service_tier).toBe('priority');
+    });
+    it('keeps a compatibility-only Gemini deployment at standard speed', () => {
+        const entry = {
+            ...model('gemini', 'gemini-3.8-flash'),
+            serviceSpeeds: ['standard'] as ServiceSpeed[],
+        };
+        expect(
+            selectServiceSpeed(entry, request('ultrafast'), noVariant).speed,
+        ).toBe('standard');
+    });
+    it('uses Claude speed independently of its service tier', () => {
+        const entry = model('claude', 'claude-opus-5-5');
+        expect(
+            selectServiceSpeed(entry, request('ultrafast'), noVariant).args
+                .speed,
+        ).toBe('fast');
+        expect(
+            selectServiceSpeed(entry, request('ultrafast'), noVariant).args
+                .service_tier,
+        ).toBeUndefined();
+        expect(
+            servedServiceSpeed({
+                usage: { speed: 'fast', service_tier: 'standard' },
+            }),
+        ).toBe('fast');
+    });
+    it.each([
+        ['minimax', 'minimax-m2.7', 'minimax-m2.7-highspeed'],
+        ['moonshotai', 'kimi-k3.1-pro', 'kimi-k3.1-pro-highspeed'],
+        ['alibaba', 'glm-5.3', 'glm-5.3-prime'],
+        ['alibaba', 'glm-5.2', 'glm-5.2-fast-preview'],
+        ['infron', 'infron:vendor/model', 'infron:vendor/model:priority'],
+    ])(
+        'selects an equivalent %s variant and preserves normalization policy',
+        (provider, id, variantId) => {
+            const base = {
+                ...model(provider, id),
+                serviceSpeedVariants: { fast: variantId },
+                release_date: '2026-08-01',
+            };
+            const variant = {
+                ...model(provider, variantId),
+                release_date: '2026-10-01',
+            };
+            const selected = selectServiceSpeed(
+                base,
+                request('ultrafast'),
+                (candidate) => (candidate === variantId ? variant : undefined),
+            );
+            expect(selected.model.id).toBe(variantId);
+            expect(selected.model.release_date).toBe(base.release_date);
+            expect(selected.speed).toBe('fast');
+            expect(
+                selectServiceSpeed(base, request('fast'), noVariant).speed,
+            ).toBe('standard');
+        },
+    );
+    it('keeps caller media on Gemini compatibility when native speed cannot carry it', () => {
+        const args = {
+            ...request('fast'),
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'video_url',
+                            video_url: { url: 'data:video/mp4;base64,AA==' },
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(
+            selectServiceSpeed(
+                model('gemini', 'gemini-3.8-flash'),
+                args,
+                noVariant,
+            ).speed,
+        ).toBe('standard');
+    });
+});
+
+describe('served speed billing', () => {
+    it.each(['standard', 'fast', 'ultrafast'] as const)(
+        'settles an ultrafast hold at the served %s rate',
+        (speed) => {
+            const selected = selectServiceSpeed(
+                model('openai-responses', 'gpt-6.1-sol'),
+                request('ultrafast'),
+                noVariant,
+            ).model;
+            const recorded: Array<Record<string, number> | undefined> = [];
+            const meter = {
+                utilRecordUsageObject: (
+                    _usage: Record<string, number>,
+                    _actor: unknown,
+                    _key: string,
+                    costs?: Record<string, number>,
+                ) => {
+                    recorded.push(costs);
+                },
+            };
+            const result = meterChatUsage(
+                meter as never,
+                undefined,
+                'openai:gpt-6.1-sol',
+                selected,
+                { prompt_tokens: 10, completion_tokens: 5, cached_tokens: 20 },
+                { serviceSpeed: speed },
+            );
+            expect(result.costs.prompt_tokens).toBe(
+                2000 * { standard: 1, fast: 2, ultrafast: 6 }[speed],
+            );
+            expect(result.costs.cached_tokens).toBe(
+                200 * { standard: 1, fast: 2, ultrafast: 6 }[speed],
+            );
+            expect(recorded).toEqual([result.costs]);
+        },
+    );
+    it('restores standard scheduled and long-context rates after a downgrade', () => {
+        const entry = model('openai-responses', 'gpt-6.1-sol');
+        entry.pricingOverrides = [
+            {
+                minPromptTokens: 100,
+                costs: { prompt_tokens: 400, completion_tokens: 1500 },
+            },
+        ];
+        const selected = selectServiceSpeed(
+            entry,
+            request('ultrafast'),
+            noVariant,
+        ).model;
+        expect(
+            serviceSpeedBillingModel(selected, 'standard').pricingOverrides,
+        ).toEqual(entry.pricingOverrides);
+        expect(
+            serviceSpeedBillingModel(selected, 'fast').pricingOverrides?.[0]
+                .costs.prompt_tokens,
+        ).toBe(800);
+    });
+    it.each([
+        [{ service_tier: 'priority' }, 'fast'],
+        [{ usage: { serviceTier: 'priority' } }, 'fast'],
+        [{ usage: { service_tier: 'standard' } }, 'standard'],
+        [{ service_tier: 'ultrafast' }, 'ultrafast'],
+        [{}, 'standard'],
+    ])('reads actual speed from %j', (source, speed) => {
+        expect(servedServiceSpeed(source)).toBe(speed);
+    });
+});
+
+describe('speed admission failures', () => {
+    it.each([
+        [{ status: 429, message: 'Fast mode rate limit exceeded' }, true],
+        [{ status: 403, message: 'Ultrafast access unavailable' }, true],
+        [{ status: 400, message: 'service_tier is not supported' }, true],
+        [{ status: 401, message: 'Invalid API key' }, false],
+        [{ status: 429, message: 'Rate limit exceeded' }, false],
+        [{ status: 400, message: 'Invalid messages' }, false],
+    ])('classifies %j without swallowing unrelated errors', (error, retry) => {
+        expect(isServiceSpeedUnavailable(error)).toBe(retry);
+    });
+    it('downgrades a missing speed variant without retrying an invalid base model', () => {
+        const error = { status: 404, message: 'Model not found' };
+        expect(isServiceSpeedUnavailable(error, true)).toBe(true);
+        expect(isServiceSpeedUnavailable(error)).toBe(false);
+    });
+});
+
+describe('streamed service tier metadata', () => {
+    it('retains a tier from an earlier Chat Completions chunk until usage arrives', async () => {
+        let servedTier: string | undefined;
+        const result = await handle_completion_output({
+            stream: true,
+            completion: (async function* () {
+                yield {
+                    service_tier: 'priority',
+                    choices: [{ index: 0, delta: { content: 'OK' } }],
+                };
+                yield {
+                    choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+                };
+                yield {
+                    choices: [],
+                    usage: { prompt_tokens: 10, completion_tokens: 1 },
+                };
+            })(),
+            usage_calculator: (source) => {
+                servedTier = source.service_tier;
+                return source.usage;
+            },
+        });
+        const chatStream = new AIChatStream({
+            stream: new Writable({
+                write(_chunk, _encoding, callback) {
+                    callback();
+                },
+            }),
+        });
+        await result.init_chat_stream!({ chatStream });
+        expect(servedTier).toBe('priority');
+    });
+
+    it('uses the final Responses tier when the provider downgrades a stream', async () => {
+        let servedTier: string | undefined;
+        const result = await handle_completion_output_responses_api({
+            stream: true,
+            completion: (async function* () {
+                yield {
+                    type: 'response.created',
+                    response: { service_tier: 'ultrafast' },
+                };
+                yield { type: 'response.output_text.delta', delta: 'OK' };
+                yield {
+                    type: 'response.completed',
+                    response: {
+                        service_tier: 'default',
+                        usage: { input_tokens: 10, output_tokens: 1 },
+                    },
+                };
+            })(),
+            usage_calculator: (source) => {
+                servedTier = source.service_tier;
+                return source.usage;
+            },
+        });
+        const chatStream = new AIChatStream({
+            stream: new Writable({
+                write(_chunk, _encoding, callback) {
+                    callback();
+                },
+            }),
+        });
+        await result.init_chat_stream!({ chatStream });
+        expect(servedTier).toBe('default');
+    });
+});

src/backend/drivers/ai-chat/utils/serviceSpeed.ts

@@ -0,0 +1,261 @@
+/*
+ * 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 { requiredInputModalities } from './mediaParts.js';
+import type {
+    IChatModel,
+    ICompleteArguments,
+    ModelCost,
+    ServiceSpeed,
+} from '../types.js';
+
+export const lowerServiceSpeed = (speed: ServiceSpeed): ServiceSpeed =>
+    speed === 'ultrafast' ? 'fast' : 'standard';
+
+const tokenRates = (costs: ModelCost, multiplier: number): ModelCost =>
+    Object.fromEntries(
+        Object.entries(costs).map(([key, value]) => [
+            key,
+            key !== 'tokens' &&
+            /token|^prompt$|^completion$|^input_cache_/.test(key)
+                ? value * multiplier
+                : value,
+        ]),
+    );
+
+export const serviceSpeedCosts = (
+    model: IChatModel,
+    speed: 'fast' | 'ultrafast',
+): ModelCost | undefined => {
+    if (model.serviceSpeeds && !model.serviceSpeeds.includes(speed))
+        return undefined;
+    const rates = model.serviceSpeedRates?.[speed];
+    return typeof rates === 'number'
+        ? tokenRates(model.costs, rates)
+        : rates
+          ? { ...model.costs, ...rates }
+          : undefined;
+};
+
+export interface ServiceSpeedSelection {
+    model: IChatModel;
+    args: ICompleteArguments;
+    speed: ServiceSpeed;
+}
+
+/** Select only an equivalent model from the same provider's loaded catalog. */
+export const selectServiceSpeed = (
+    model: IChatModel,
+    args: ICompleteArguments,
+    findVariant: (id: string) => IChatModel | undefined,
+    offers: Partial<Record<'fast' | 'ultrafast', IChatModel>> = {},
+): ServiceSpeedSelection => {
+    if (args.serviceSpeed === undefined)
+        return { model, args, speed: 'standard' };
+    const provider = model.provider;
+    const fast =
+        offers.fast?.costs ??
+        (provider === 'gemini' &&
+        (requiredInputModalities(args.messages).some(
+            (modality) => !['text', 'image'].includes(modality),
+        ) ||
+            args.messages.some(
+                (message) =>
+                    Array.isArray(message.content) &&
+                    message.content.some(
+                        (part: Record<string, unknown>) =>
+                            part &&
+                            [
+                                'input_audio',
+                                'audio_url',
+                                'document',
+                                'file',
+                                'input_file',
+                            ].includes(String(part.type)),
+                    ),
+            ))
+            ? undefined
+            : serviceSpeedCosts(model, 'fast'));
+    const ultra =
+        offers.ultrafast?.costs ?? serviceSpeedCosts(model, 'ultrafast');
+    let speed = args.serviceSpeed;
+    const variantId = model.serviceSpeedVariants?.fast;
+    const variant =
+        offers.fast && offers.fast.id !== model.id
+            ? offers.fast
+            : variantId
+              ? findVariant(variantId)
+              : undefined;
+    while (speed !== 'standard') {
+        if (speed === 'ultrafast' && ultra) break;
+        if (speed === 'fast' && (fast || variant)) break;
+        speed = lowerServiceSpeed(speed);
+    }
+    const request: ICompleteArguments = {
+        ...args,
+        serviceSpeed: speed,
+        speed: undefined,
+        service_tier: undefined,
+    };
+    if (speed === 'fast' && variant) {
+        return {
+            model: { ...variant, release_date: model.release_date },
+            args: request,
+            speed,
+        };
+    }
+    if (provider === 'gemini' && fast)
+        request.service_tier = speed === 'fast' ? 'priority' : 'standard';
+    else if (provider === 'claude')
+        request.speed = speed === 'fast' ? 'fast' : 'standard';
+    else if (provider === 'mistral')
+        request.service_tier = speed === 'fast' ? 'auto' : 'default';
+    else if (
+        provider === 'minimax' &&
+        model.serviceSpeedRates?.fast !== undefined
+    )
+        request.service_tier = speed === 'fast' ? 'priority' : 'standard';
+    else if (fast || ultra)
+        request.service_tier =
+            speed === 'ultrafast'
+                ? 'ultrafast'
+                : speed === 'fast'
+                  ? 'priority'
+                  : 'default';
+    if (
+        speed === 'standard' &&
+        [
+            'openai-completion',
+            'openai-responses',
+            'azure-openai',
+            'azure-openai-responses',
+            'openrouter',
+        ].includes(provider ?? '')
+    )
+        request.service_tier = 'default';
+    const selectedCosts =
+        speed === 'ultrafast' ? ultra : speed === 'fast' ? fast : undefined;
+    return {
+        args: request,
+        speed,
+        model: selectedCosts
+            ? {
+                  ...model,
+                  costs: selectedCosts,
+                  pricingOverrides: model.pricingOverrides?.map((override) => ({
+                      ...override,
+                      costs: Object.fromEntries(
+                          Object.entries(override.costs).map(([key, value]) => [
+                              key,
+                              model.costs[key] > 0
+                                  ? (value *
+                                        (selectedCosts[key] ??
+                                            model.costs[key])) /
+                                    model.costs[key]
+                                  : value,
+                          ]),
+                      ),
+                  })),
+                  serviceSpeedPricing: {
+                      speed,
+                      standardCosts: model.costs,
+                      standardOverrides: model.pricingOverrides,
+                      fastCosts: fast,
+                      ultrafastCosts: ultra,
+                  },
+              }
+            : model,
+    };
+};
+
+/** The response is authoritative; an absent tier never earns a premium. */
+export const servedServiceSpeed = (
+    source: Record<string, unknown>,
+): ServiceSpeed => {
+    const usage = source.usage as Record<string, unknown> | undefined;
+    const tier =
+        usage?.speed ??
+        usage?.serviceTier ??
+        usage?.service_tier ??
+        source.service_tier;
+    return tier === 'ultrafast'
+        ? 'ultrafast'
+        : tier === 'fast' || tier === 'priority'
+          ? 'fast'
+          : 'standard';
+};
+
+export const serviceSpeedBillingModel = (
+    model: IChatModel,
+    speed: ServiceSpeed,
+): IChatModel => {
+    const pricing = model.serviceSpeedPricing;
+    if (!pricing || pricing.speed === speed) return model;
+    const costs =
+        speed === 'fast'
+            ? (pricing.fastCosts ?? pricing.standardCosts)
+            : pricing.standardCosts;
+    return {
+        ...model,
+        costs,
+        pricingOverrides: pricing.standardOverrides?.map((override) => ({
+            ...override,
+            costs: Object.fromEntries(
+                Object.entries(override.costs).map(([key, value]) => [
+                    key,
+                    pricing.standardCosts[key] > 0
+                        ? (value * (costs[key] ?? pricing.standardCosts[key])) /
+                          pricing.standardCosts[key]
+                        : value,
+                ]),
+            ),
+        })),
+    };
+};
+
+/** Retry only failures that explicitly concern admission to the faster tier. */
+export const isServiceSpeedUnavailable = (
+    error: unknown,
+    variant = false,
+): boolean => {
+    const e = error as {
+        status?: number;
+        statusCode?: number;
+        message?: unknown;
+        error?: { message?: unknown };
+    };
+    const status = e?.status ?? e?.statusCode;
+    const message = e?.error?.message ?? e?.message ?? '';
+    if (typeof message !== 'string') return false;
+    if (
+        variant &&
+        [400, 404].includes(status ?? 0) &&
+        /model.*(?:not found|not exist|unavailable)/i.test(message)
+    )
+        return true;
+    return (
+        [400, 403, 429, 503].includes(status ?? 0) &&
+        /fast mode|ultrafast|service[_ ]?tier|priority (?:tier|processing|capacity)|speed parameter/i.test(
+            message,
+        ) &&
+        /unavailable|unsupported|not support|rate.limit|quota|capacity|not enabled|not allowed|access|exceed|invalid value/i.test(
+            message,
+        )
+    );
+};

src/backend/drivers/apps/AppDriver.js

@@ -330,14 +330,11 @@ export class AppDriver extends PuterDriver {
     }
 
     /**
-     * Paged app listing. Unlike `/query/app`, which answers only for apps named
-     * by the caller and so must not confirm ones it may not see, this is the
-     * listing surface a launcher reads: `protected` apps are filtered by the
-     * permission check below, and everything else is listable by design. Narrow
-     * it with `predicate: ['user-can-edit']` to the caller's own.
+     * Paged listing of the caller's own apps. Apps owned by anyone else are
+     * reachable only by name or uid, through `read` and `/query/app`.
      */
     async select(args = {}) {
-        const { predicate, params = {} } = args;
+        const { params = {} } = args;
         const actor = requireContextActor();
         this.#requireUserOrAppActor(actor);
 
@@ -353,16 +350,12 @@ export class AppDriver extends PuterDriver {
         const includeTotal = args.includeTotal === true;
         const paginated = hasCursor || offset !== undefined || includeTotal;
 
-        const filters = {};
-        // predicate: ['user-can-edit'] → scope to owner
-        const ownerScoped =
-            Array.isArray(predicate) && predicate[0] === 'user-can-edit';
-        if (ownerScoped) {
-            filters.ownerUserId = actor.user.id;
-        }
+        // Always the caller's own. `predicate: ['user-can-edit']` asks for the
+        // same thing and is accepted for older clients.
+        const ownerUserId = actor.user.id;
 
         let apps = await this.appStore.list({
-            ...filters,
+            ownerUserId,
             limit: paginated ? limit + 1 : limit,
             offset,
             afterId: payload?.id !== undefined ? Number(payload.id) : undefined,
@@ -371,23 +364,18 @@ export class AppDriver extends PuterDriver {
         let cursor;
         if (paginated && apps.length > limit) {
             apps = apps.slice(0, limit);
-            // The cursor tracks the last fetched row, not the last visible
-            // one, so rows hidden by the permission filter below aren't
-            // re-scanned on the next page.
             cursor = sealCursor(
                 { id: Number(apps[apps.length - 1].id) },
                 this.config.jwt_secret_v2,
             );
         }
 
-        // Protected apps are filtered by one batched grant check; stats and
-        // the shared views are each one batched lookup across the page.
-        const visible = await this.services.app.filterReadable(apps, actor);
+        // Stats and the shared views are each one batched lookup per page.
         const [statsByUid, views] = await Promise.all([
-            this.appStore.getAppsStats(visible.map((a) => a.uid)),
-            this.services.app.views(visible, actor),
+            this.appStore.getAppsStats(apps.map((a) => a.uid)),
+            this.services.app.views(apps, actor),
         ]);
-        const items = visible.map((app, i) =>
+        const items = apps.map((app, i) =>
             toAppReadView(app, views[i], {
                 viewer: actor.user,
                 stats: statsByUid.get(app.uid),
@@ -396,14 +384,9 @@ export class AppDriver extends PuterDriver {
         );
         if (!paginated) return items;
 
-        let total;
-        if (includeTotal) {
-            total = ownerScoped
-                ? await this.appStore.count({ ownerUserId: actor.user.id })
-                : await this.appStore.count({
-                      visibleToUserId: actor.user?.id ?? null,
-                  });
-        }
+        const total = includeTotal
+            ? await this.appStore.count({ ownerUserId })
+            : undefined;
 
         return {
             items,

src/backend/drivers/apps/AppDriver.test.ts

@@ -509,7 +509,7 @@ describe('AppDriver.read', () => {
 // ── select ──────────────────────────────────────────────────────────
 
 describe('AppDriver.select', () => {
-    it('returns visible apps including those owned by other users', async () => {
+    it("returns only the caller's apps when no predicate is sent", async () => {
         const a = await makeUser();
         const b = await makeUser();
         const aName = uniqueName('a');
@@ -538,7 +538,7 @@ describe('AppDriver.select', () => {
         )) as Array<Record<string, unknown>>;
         const names = result.map((r) => r.name);
         expect(names).toContain(aName);
-        expect(names).toContain(bName);
+        expect(names).not.toContain(bName);
     });
 
     it('predicate `user-can-edit` filters to actor-owned apps only', async () => {
@@ -1670,11 +1670,10 @@ describe('AppDriver.select pagination', () => {
         expect(page.total).toBe(names.length);
     });
 
-    it("hides other users' protected apps from paginated catalog listings", async () => {
+    it("pages through only the caller's apps, protected ones included", async () => {
         const a = await makeApps(3);
-        const [visible1, hidden, visible2] = a.names;
         const created = await withActor(a.actor, () =>
-            driver.read({ id: { name: hidden } }),
+            driver.read({ id: { name: a.names[1] } }),
         );
         const row = await server.stores.app.getByUid(
             (created as Record<string, unknown>).uid as string,
@@ -1685,20 +1684,29 @@ describe('AppDriver.select pagination', () => {
         );
         await server.stores.app.invalidateByUid(row!.uid as string);
 
-        const b = await makeUser();
-        const seen: string[] = [];
-        let cursor: string | null | undefined = null;
-        do {
-            const page = (await withActor(b.actor, () =>
-                driver.select({ limit: 50, cursor }),
-            )) as { items: Array<{ name: string }>; cursor?: string };
-            seen.push(...page.items.map((r) => r.name));
-            cursor = page.cursor;
-        } while (cursor);
+        const listAll = async (actor: Actor) => {
+            const seen: string[] = [];
+            let total: number | undefined;
+            let cursor: string | null | undefined = null;
+            do {
+                const page = (await withActor(actor, () =>
+                    driver.select({ limit: 2, cursor, includeTotal: true }),
+                )) as {
+                    items: Array<{ name: string }>;
+                    cursor?: string;
+                    total?: number;
+                };
+                seen.push(...page.items.map((r) => r.name));
+                total ??= page.total;
+                cursor = page.cursor;
+            } while (cursor);
+            return { seen, total };
+        };
 
-        expect(seen).toContain(visible1);
-        expect(seen).toContain(visible2);
-        expect(seen).not.toContain(hidden);
+        expect(await listAll(a.actor)).toEqual({ seen: a.names, total: 3 });
+
+        const b = await makeUser();
+        expect(await listAll(b.actor)).toEqual({ seen: [], total: 0 });
     });
 });
 
@@ -2517,22 +2525,6 @@ describe('AppDriver.select query-count regression', () => {
 // -- select / read parity --
 
 describe('AppDriver.select / read parity', () => {
-    const findViaBroadSelect = async (
-        actor: Actor,
-        uid: string,
-    ): Promise<Record<string, unknown> | undefined> => {
-        let cursor: string | null | undefined = null;
-        do {
-            const page = (await withActor(actor, () =>
-                driver.select({ limit: 50, cursor }),
-            )) as { items: Array<Record<string, unknown>>; cursor?: string };
-            const found = page.items.find((r) => r.uid === uid);
-            if (found) return found;
-            cursor = page.cursor;
-        } while (cursor);
-        return undefined;
-    };
-
     it('every select item (minus stats) deep-equals the corresponding read', async () => {
         const { actor } = await makeUser();
         const names: string[] = [];
@@ -2640,7 +2632,7 @@ describe('AppDriver.select / read parity', () => {
         ).toBe(false);
     });
 
-    it('dangling hosted app via select: owner keeps index_url, others do not', async () => {
+    it('dangling hosted app: owner keeps index_url in select, others do not in read', async () => {
         const owner = await makeUser();
         const other = await makeUser();
         const sub = uniqueName('qcdangsel');
@@ -2672,13 +2664,12 @@ describe('AppDriver.select / read parity', () => {
                 ?.reason,
         ).toBe('hosted_backing_unavailable');
 
-        const otherItem = await findViaBroadSelect(
-            other.actor,
-            created.uid as string,
-        );
-        expect(otherItem?.index_url).toBeUndefined();
+        const otherItem = (await withActor(other.actor, () =>
+            driver.read({ uid: created.uid }),
+        )) as Record<string, unknown>;
+        expect(otherItem.index_url).toBeUndefined();
         expect(
-            (otherItem?.privateAccess as { hasAccess?: boolean } | undefined)
+            (otherItem.privateAccess as { hasAccess?: boolean } | undefined)
                 ?.hasAccess,
         ).toBe(false);
     });

src/backend/server.test.ts

@@ -368,12 +368,115 @@ 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',
+        'upgrade',
+        'request-email-confirmation',
+    ])('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/', '/embed/Upgrade', '/embed/upgrade/', '/embed/Request-Email-Confirmation'])(
+        '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/auth/TokenService.test.ts

@@ -20,6 +20,7 @@
 import { createHmac } from 'node:crypto';
 import jwt from 'jsonwebtoken';
 import { describe, expect, it } from 'vitest';
+import { isTokenForAnotherUser } from '../../../gui/src/helpers/tokenUser.js';
 import { TokenService } from './TokenService.js';
 
 const V2_SECRET = 'test-v2-secret';
@@ -384,3 +385,21 @@ describe('TokenService payload key handling', () => {
         },
     );
 });
+
+describe('session token read by the desktop', () => {
+    // The desktop reads the user out of a token another tab stored, to tell
+    // an account switch from a renewed token for the same account.
+    it('names its user in the form the desktop decodes', () => {
+        const svc = createTokenService();
+        const userUid = '5d4adce0-a381-4982-9c02-6e2540026238';
+        const otherUid = 'a1b2c3d4-0000-4000-8000-00000000beef';
+        const token = svc.sign('auth', {
+            type: 'gui',
+            version: '2',
+            user_uid: userUid,
+        });
+
+        expect(isTokenForAnotherUser(token, { uuid: userUid })).toBe(false);
+        expect(isTokenForAnotherUser(token, { uuid: otherUid })).toBe(true);
+    });
+});

src/backend/services/events/userHandlers.worker.integration.test.ts

@@ -144,11 +144,22 @@ const createInline = async (
     return String(response.body.subId);
 };
 
-const delivered = (count = 1): Promise<void> =>
-    vi.waitFor(() => expect(sinkPosts.length).toBeGreaterThanOrEqual(count), {
-        timeout: 30_000,
-        interval: 50,
-    });
+/**
+ * The post each label made, in order, once all have arrived. Matched by label
+ * since earlier tests' subscriptions stay live and post to the same sink.
+ */
+const delivered = async (...labels: string[]): Promise<SinkPost[]> => {
+    await vi.waitFor(
+        () =>
+            expect(sinkPosts.map((post) => post.label)).toEqual(
+                expect.arrayContaining(labels),
+            ),
+        { timeout: 30_000, interval: 50 },
+    );
+    return labels.map((label) =>
+        sinkPosts.find((post) => post.label === label)!,
+    );
+};
 
 beforeAll(async () => {
     env = await setupPuterTestEnv({
@@ -255,14 +266,11 @@ describe('an inline handler in a user scope, end to end', () => {
             await env.server.services.fs.touch(holder.id, {
                 path: `${holder.anchor}/note.txt`,
             });
-            await delivered();
+            const [post] = await delivered('inline');
 
-            expect(sinkPosts[0]).toMatchObject({
-                label: 'inline',
-                path: `${holder.anchor}/note.txt`,
-            });
+            expect(post.path).toBe(`${holder.anchor}/note.txt`);
             const { actor } = await env.server.services.auth.authenticate(
-                sinkPosts[0].token!,
+                post.token!,
             );
             expect(actor!.user?.id).toBe(holder.id);
             expect(actor!.effectiveApp?.uid).toBe(appUid);
@@ -297,14 +305,14 @@ describe('an inline handler in a user scope, end to end', () => {
                 await env.server.services.fs.touch(holder.id, {
                     path: `${holder.anchor}/shared-${i}.txt`,
                 });
-            await delivered(2);
-            const runAs = new Set<number>();
-            for (const post of sinkPosts)
-                runAs.add(
-                    (await env.server.services.auth.authenticate(post.token!))
-                        .actor!.user!.id,
+            // The first test's 'inline' handler also posts for holders[0].
+            const posts = await delivered('first', 'second');
+            for (const [i, post] of posts.entries()) {
+                const { actor } = await env.server.services.auth.authenticate(
+                    post.token!,
                 );
-            expect(runAs).toEqual(new Set(holders.map((h) => h.id)));
+                expect(actor!.user!.id).toBe(holders[i].id);
+            }
             create.mockRestore();
         },
     );

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/localworker/LocalWorkerService.shutdown.test.ts

@@ -78,7 +78,10 @@ describe('LocalWorkerService shutdown disposal', () => {
         disposals[0].mockImplementationOnce(async () => {
             await held;
         });
-        vi.useFakeTimers();
+        vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+        // The test server keeps arming timers from real callbacks while fakes
+        // are installed, so only what shutdown arms synchronously is checked.
+        const arm = vi.spyOn(globalThis, 'setTimeout');
         try {
             let finished = false;
             const draining = Promise.resolve(service.onServerShutdown()).then(
@@ -86,12 +89,13 @@ describe('LocalWorkerService shutdown disposal', () => {
                     finished = true;
                 },
             );
+            expect(arm.mock.calls.map(([, ms]) => ms)).toEqual([5_000]);
             await vi.advanceTimersByTimeAsync(4_999);
             expect(finished).toBe(false);
             await vi.advanceTimersByTimeAsync(1);
             await draining;
-            expect(vi.getTimerCount()).toBe(0);
         } finally {
+            arm.mockRestore();
             release();
             vi.useRealTimers();
         }

src/backend/services/realtime/OpenAIRealtimeRelayService.test.ts

@@ -2860,8 +2860,12 @@ describe('OpenAIRealtimeRelayService relay', () => {
                 ),
             ).toHaveLength(64),
         );
+        // Holds are reserved and usage recorded one at a time, which a loaded
+        // runner takes past vi.waitFor's default second.
+        const settled = (check: () => Promise<void> | void) =>
+            vi.waitFor(check, { timeout: 5_000 });
         // The pool grew one item per commit, with nothing spare at the cap.
-        await vi.waitFor(async () =>
+        await settled(async () =>
             expect(
                 await server.services.metering.getOutstandingHolds(actor),
             ).toBe(64 * 10_896_000),
@@ -2890,7 +2894,7 @@ describe('OpenAIRealtimeRelayService relay', () => {
         for (let batch = 0; batch < 8; batch++) {
             for (let i = Math.max(1, batch * 8); i < (batch + 1) * 8; i++)
                 complete(i);
-            await vi.waitFor(() =>
+            await settled(() =>
                 expect(
                     recorded.mock.calls
                         .flatMap(([, rows]) => rows)
@@ -2906,13 +2910,13 @@ describe('OpenAIRealtimeRelayService relay', () => {
                 .filter((row) => row.usageType.includes('transcription_'))
                 .reduce((sum, row) => sum + row.costOverride!, 0),
         ).toBe(640);
-        await vi.waitFor(async () =>
+        await settled(async () =>
             expect(
                 await server.services.metering.getOutstandingHolds(actor),
             ).toBe(2 * 10_896_000),
         );
         c.ws.close();
-        await vi.waitFor(async () =>
+        await settled(async () =>
             expect(
                 await server.services.metering.getOutstandingHolds(actor),
             ).toBe(0),

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/stores/app/AppStore.js

@@ -686,12 +686,7 @@ export class AppStore extends PuterStore {
         return apps;
     }
 
-    /**
-     * Count apps matching the same equality filters as `list`.
-     * `visibleToUserId` counts the public catalog for one caller —
-     * non-protected apps plus their own; apps visible only via explicit
-     * permission grants are not included.
-     */
+    /** Count apps matching the same equality filters as `list`. */
     async count(filters = {}) {
         const where = [];
         const params = [];
@@ -704,12 +699,6 @@ export class AppStore extends PuterStore {
             where.push('`app_owner` = ?');
             params.push(filters.appOwner);
         }
-        if (filters.visibleToUserId !== undefined) {
-            where.push(
-                '(`protected` IS NULL OR `protected` = false OR `owner_user_id` = ?)',
-            );
-            params.push(filters.visibleToUserId);
-        }
 
         const whereClause = where.length ? `WHERE ${where.join(' AND ')}` : '';
         const rows = await this.clients.db.read(

src/backend/stores/app/AppStore.test.js

@@ -1292,31 +1292,14 @@ describe('AppStore CRUD and cache invalidation', () => {
         ).toBe('Bumped');
     });
 
-    it('counts apps by owner, creator and per-caller visibility', async () => {
+    it('counts apps by owner and creator', async () => {
         const countOwner = 4600;
-        const viewer = 4601;
         const open = await createApp({}, { ownerUserId: countOwner });
         await createApp({}, { ownerUserId: countOwner, appOwner: open.id });
-        const hidden = await createApp({}, { ownerUserId: countOwner });
-        await db.write('UPDATE `apps` SET `protected` = 1 WHERE `id` = ?', [
-            hidden.id,
-        ]);
+        await createApp({}, { ownerUserId: countOwner });
 
         expect(await appStore.count({ ownerUserId: countOwner })).toBe(3);
         expect(await appStore.count({ appOwner: open.id })).toBe(1);
-
-        // The protected app is invisible to a stranger but visible to its
-        // owner.
-        const strangerView = await appStore.count({
-            ownerUserId: countOwner,
-            visibleToUserId: viewer,
-        });
-        expect(strangerView).toBe(2);
-        const ownerView = await appStore.count({
-            ownerUserId: countOwner,
-            visibleToUserId: countOwner,
-        });
-        expect(ownerView).toBe(3);
     });
 
     // -- filetype association batch + recent opens ----------------------
@@ -1542,18 +1525,22 @@ describe('AppStore detailed stats', () => {
     let db;
 
     const APP_UID = `app-stats-${Date.now()}`;
-    const nowSeconds = Math.floor(Date.now() / 1000);
+    // The windows come from the clock, so it is pinned: mid-week and
+    // mid-month, and minutes clear of midnight in any time zone.
+    const NOW = new Date('2026-06-17T12:07:30Z');
+    const nowSeconds = Math.floor(NOW.getTime() / 1000);
 
     beforeAll(async () => {
         server = await setupTestServer();
         appStore = server.stores.app;
         db = server.clients.db;
         await clearAppCache(server.clients.redis);
+        vi.useFakeTimers({ toFake: ['Date'], now: NOW });
 
-        // Two users; the repeat shares a timestamp so it is always same-hour.
+        // Two users in one hour. Windows end at now, exclusive.
         for (const [userId, offset] of [
-            [1, 0],
-            [1, 0],
+            [1, 60],
+            [1, 60],
             [2, 120],
         ]) {
             await db.write(
@@ -1564,6 +1551,7 @@ describe('AppStore detailed stats', () => {
     });
 
     afterAll(async () => {
+        vi.useRealTimers();
         await server?.shutdown();
     });
 

src/backend/testUtil.ts

@@ -154,6 +154,9 @@ export const setupTestServer = async (
             redis: { useMock: true },
             // Suites run system jobs themselves, not on the poll timer.
             jobs: { enabled: false },
+            // The health loop's timed `SELECT 1` would land in tests that
+            // count queries.
+            server_health: { disabled_checks: ['database-liveness'] },
             s3: { localConfig: { inMemory: true } },
             no_default_user: true,
             no_devwatch: true,

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/backend/vitest.config.ts

@@ -37,6 +37,9 @@ const repoRoot = path.resolve(backendDir, '../..');
 const isPgmockMode =
     (process.env.PUTER_TEST_DB_ENGINE ?? '').toLowerCase() === 'postgres';
 const pgmockTimeoutMs = 600_000;
+// Loaded CI runners stall timers well past the 5 s / 10 s defaults; a real
+// hang still fails, just later.
+const ciTimeouts = { testTimeout: 20_000, hookTimeout: 60_000 };
 
 // Tests that always boot pgmock regardless of PUTER_TEST_DB_ENGINE. Too slow
 // for CI; run locally or via `npm run test:backend:postgres`.
@@ -103,9 +106,11 @@ export const lowerDecoratorsPlugin = {
             loader: 'ts',
             target: 'es2024',
             sourcefile: id,
-            sourcemap: 'inline',
+            sourcemap: 'external',
         });
-        return { code: result.code, map: null };
+        // Without the map, coverage and stack traces report esbuild's
+        // output lines instead of the source's.
+        return { code: result.code, map: result.map };
     },
 };
 
@@ -145,7 +150,9 @@ export default defineConfig(({ mode }) => ({
                   hookTimeout: pgmockTimeoutMs,
                   fileParallelism: false,
               }
-            : {}),
+            : isCi
+              ? ciTimeouts
+              : {}),
         coverage: {
             provider: 'v8',
             reporter: isCi

src/dev-center/js/apps.js

@@ -1339,7 +1339,7 @@ async function saveEditedApp (mode) {
         // Update title
         $(`.app-title[data-uid="${uid}"]`).html(html_encode(app.title));
         // Update app link
-        $(`.app-url[data-uid="${uid}"]`).html(applink(app));
+        $(`.app-url[data-uid="${uid}"]`).html(html_encode(applink(app)));
         $(`.app-url[data-uid="${uid}"]`).attr('href', applink(app));
         // Update icons
         $(`.app-icon[data-uid="${uid}"]`).attr('src', html_encode(app.icon ? app.icon : './img/app.svg'));

src/dev-center/js/dev-center.js

@@ -38,22 +38,27 @@ window.user = null;
     }
 })();
 
-// domain and APIOrigin
-if ( window.url_params.has('puter.domain') ) {
-    window.domain = window.url_params.get('puter.domain');
+// domain and port are built into links and deploy URLs, so anything other
+// than a bare hostname and a numeric port is ignored
+const domainParam = window.url_params.get('puter.domain');
+if ( domainParam && /^[a-z0-9-]+(\.[a-z0-9-]+)*$/i.test(domainParam) ) {
+    window.domain = domainParam;
 }
 
+const portParam = window.url_params.get('puter.port');
+window.port = portParam && /^\d{1,5}$/.test(portParam) ? portParam : '';
+
 // static hosting domain
 window.static_hosting_domain = 'puter.site';
-   if ( window.domain === 'puter.localhost' ) {
-       window.static_hosting_domain = 'site.puter.localhost';
-   } else if ( window.domain && window.domain !== 'puter.com' ) {
-       window.static_hosting_domain = `site.${window.domain}`;
-   }
+if ( window.domain === 'puter.localhost' ) {
+    window.static_hosting_domain = 'site.puter.localhost';
+} else if ( window.domain && window.domain !== 'puter.com' ) {
+    window.static_hosting_domain = `site.${window.domain}`;
+}
 
 // add port to static_hosting_domain if provided
-if ( window.url_params.has('puter.port') && window.url_params.get('puter.port') ) {
-    window.static_hosting_domain = `${window.static_hosting_domain }:${ html_encode(window.url_params.get('puter.port'))}`;
+if ( window.port ) {
+    window.static_hosting_domain = `${window.static_hosting_domain}:${window.port}`;
 }
 
 // protocol
@@ -63,12 +68,6 @@ if ( window.url_params.has('puter.protocol') && window.url_params.get('puter.pro
     window.protocol = 'http';
 }
 
-// port
-window.port = '';
-if ( window.url_params.has('puter.port') && window.url_params.get('puter.port') ) {
-    window.port = html_encode(window.url_params.get('puter.port'));
-}
-
 // source_path
 if ( window.url_params.has('source_path') ) {
     window.source_path = window.url_params.get('source_path');

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/chat.md

@@ -30,6 +30,7 @@ An object containing the following properties:
 | Option | Type | Description |
 |--------|------|-------------|
 | `model` | `String` | The model you want to use for the completion. If not specified, defaults to `gpt-5.4-nano`. More than 500 models are available from providers including OpenAI, Anthropic, Google, Alibaba Cloud, xAI, Mistral, OpenRouter, Infron, and others. For a full list, see the [AI models list](https://developer.puter.com/ai/models/) page. |
+| `serviceSpeed` | `String` | Preferred service speed, `"standard"`, `"fast"`, or `"ultrafast"`. Unavailable speeds fall back from ultrafast to fast, then standard. Omitting it preserves the model's default service. Faster service may cost more. See [Service speed](#service-speed) and [Model-specific features](#model-specific-features). |
 | `stream` | `Boolean` | A boolean indicating whether you want to stream the completion. Defaults to `false`. |
 | `max_tokens` | `Number` | The maximum number of tokens to generate in the completion. By default, the specific model's maximum is used. |
 | `temperature` | `Number` | A number between 0 and 2 indicating the randomness of the completion. Lower values make the output more focused and deterministic, while higher values make it more random. By default, the model's own temperature is used. See [Model-specific features](#model-specific-features). |
@@ -138,6 +139,8 @@ by a newline. Use the async iterator to receive every chunk as an object.
 
 In case of an error, the `Promise` will reject with an error message.
 
+An unrecognized `serviceSpeed` value rejects with `invalid_service_speed`.
+
 For streaming responses, an error from the AI provider is returned as a chunk
 with `type: "error"` and a `message` describing the failure. This also happens
 if the provider stops sending the response before it is complete. Check for
@@ -370,10 +373,20 @@ const response = await puter.ai.chat('Hello', {
 
 With `provider` set as well, the request is answered by that provider or fails. If that provider does not serve the model, the request fails with a `400` instead of going to another provider. The error is the same one you would get if every provider had failed, for example `400 upstream_provider_unavailable` or `429 upstream_rate_limited`.
 
+## Service speed
+
+The `serviceSpeed` option selects service capacity independently of reasoning effort. If the requested speed is unavailable for the selected model, the request uses the next supported speed in the order `ultrafast`, `fast`, `standard`.
+
+A faster tier that rejects a request because its capacity or access is unavailable can retry at a lower speed on the same provider. The `fallback` option controls retries on other providers separately. Once streaming output starts, a failed stream ends with an error instead of restarting at another speed.
+
+The `usageDetails.serviceSpeed` field reports the served speed. Billing uses the tier or equivalent model that served the request. A provider downgrade is billed at the lower tier's rates. Response normalization follows the same rule as a request without this option, including when a faster equivalent model is selected.
+
 ## Model-specific features
 
 ### OpenAI models
 
+Fast service is available on models with a published Fast rate card. Ultrafast is available for GPT-6.1 Sol and GPT-6 Astra. Other models fall back to fast or standard. Cache and long-context rates apply to the served tier.
+
 #### `temperature`
 
 Some OpenAI reasoning models ignore `temperature` and `top_p`. GPT-5.6, GPT-6 Sol/Luna, and GPT-6.1 Terra accept them only with `reasoning_effort: 'none'`, and GPT-6 Astra, GPT-6.1 Sol, and GPT-5.3 Codex always ignore them.
@@ -418,6 +431,8 @@ The `usageDetails` object on every result carries the same counts under provider
 
 ### Anthropic models
 
+Fast service is available on Claude models with a Fast rate card. Ultrafast falls back to fast. When the account has no Fast quota, the request retries at standard speed. The upstream service tier and inference speed are separate fields.
+
 #### Prompt Caching
 
 Specific to Anthropic models, you can use the cache control feature, allowing you to optimize costs for repeated prompts.
@@ -442,6 +457,8 @@ You can find the implementation in our [prompt caching example](/playground/ai-c
 
 ### Gemini models
 
+Fast service uses Priority inference on supported text and image requests. Other media use standard service to preserve input handling.
+
 #### `temperature`
 
 `gemini-4-argon` ignores `temperature`. `gemini-3.1-flash-lite` and `gemini-3-flash-preview` use it.
@@ -543,6 +560,8 @@ for await (const part of resp) {
 
 ### Moonshot Kimi models
 
+Models with an equivalent Highspeed variant select that variant for fast service. Other models use standard service.
+
 #### `reasoning_effort`
 
 Kimi K3.1 Pro accepts `low`, `high` and `max`, uses `max` when you leave it unset, and fails with `400 bad_request` on any other value.
@@ -557,6 +576,30 @@ Moonshot's Kimi K3 and Kimi K3.1 Pro models cache prompt prefixes on their own a
 
 Muse Spark always reasons, so `none` is ignored for it.
 
+### xAI models
+
+Fast service requests Priority processing. Token charges, including cached input and reasoning, follow the served tier.
+
+### MiniMax models
+
+MiniMax M3 uses Priority admission for fast service. Earlier models with an equivalent Highspeed variant use that variant. Other models use standard service.
+
+### Mistral models
+
+Fast service requests Priority when the account and model are eligible. The provider can serve the request at standard speed.
+
+### Alibaba Cloud models
+
+Models with an equivalent Prime or Fast variant select that variant for fast service. Other models use standard service.
+
+### OpenRouter models
+
+Faster tiers come from the selected model's endpoint catalog. A tier can fall back upstream. Billing uses the endpoint that serves the request.
+
+### Infron models
+
+Models with a Priority offering select that offering for fast service. Other models use standard service.
+
 ## Examples
 
 ### Ask GPT-6 Luna a question
@@ -1092,3 +1135,23 @@ Policy 8 - Account Management: Each Enterprise and Ultimate customer is assigned
 </body>
 </html>
 ```
+
+### Select service speed
+
+For example, request the fastest supported service:
+
+```html;ai-chat-service-speed
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script type="module">
+        const response = await puter.ai.chat('Explain closures in one paragraph.', {
+            model: 'gpt-6.1-sol',
+            serviceSpeed: 'ultrafast',
+        });
+        puter.print(response.message.content);
+        puter.print(response.usageDetails.serviceSpeed);
+    </script>
+</body>
+</html>
+```

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/Objects/chatresponse.md

@@ -64,7 +64,7 @@ Extra detail on why generation stopped (e.g. a refusal classification). Provider
 
 #### `usageDetails` (Object)
 
-A provider-neutral usage breakdown, present alongside `usage` on every result. `inputTokens` excludes cache reads/writes; `outputTokens` includes reasoning tokens. Fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWrite5mTokens`, `cacheWrite30mTokens`, `cacheWrite1hTokens`, `cacheWrite12hTokens`, `reasoningTokens`, `webSearchRequests`, `webFetchRequests`, `speed` (`"fast"` or `"standard"`), `serviceTier`, and `iterations` (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call). Each `cacheWrite*Tokens` field counts the tokens written to the cache with that lifetime: Claude and Moonshot write 5 minute and 1 hour entries, OpenAI writes 30 minute and 12 hour entries.
+A provider-neutral usage breakdown, present alongside `usage` on every result. `inputTokens` excludes cache reads/writes; `outputTokens` includes reasoning tokens. Fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWrite5mTokens`, `cacheWrite30mTokens`, `cacheWrite1hTokens`, `cacheWrite12hTokens`, `reasoningTokens`, `webSearchRequests`, `webFetchRequests`, `speed` (`"fast"` or `"standard"`), `serviceTier`, `serviceSpeed` (`"standard"`, `"fast"`, or `"ultrafast"` when requested), and `iterations` (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call). Each `cacheWrite*Tokens` field counts the tokens written to the cache with that lifetime: Claude and Moonshot write 5 minute and 1 hour entries, OpenAI writes 30 minute and 12 hour entries.
 
 Prefer `usageDetails` over `usage` for anything beyond the raw billing totals. Claude's `usage.thinking_tokens` is informational: it's included in `output_tokens` and not billed separately — `usageDetails.reasoningTokens` carries the same count.
 

src/docs/src/Objects/chatresponsechunk.md

@@ -102,7 +102,7 @@ Extra detail on why generation stopped (e.g. a refusal classification). Provider
 
 #### `usageDetails` (Object)
 
-A provider-neutral usage breakdown, present on the final `usage` chunk. `inputTokens` excludes cache reads/writes; `outputTokens` includes reasoning tokens. Fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWrite5mTokens`, `cacheWrite30mTokens`, `cacheWrite1hTokens`, `cacheWrite12hTokens`, `reasoningTokens`, `webSearchRequests`, `webFetchRequests`, `speed` (`"fast"` or `"standard"`), `serviceTier`, and `iterations` (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call). Each `cacheWrite*Tokens` field counts the tokens written to the cache with that lifetime: Claude and Moonshot write 5 minute and 1 hour entries, OpenAI writes 30 minute and 12 hour entries.
+A provider-neutral usage breakdown, present on the final `usage` chunk. `inputTokens` excludes cache reads/writes; `outputTokens` includes reasoning tokens. Fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWrite5mTokens`, `cacheWrite30mTokens`, `cacheWrite1hTokens`, `cacheWrite12hTokens`, `reasoningTokens`, `webSearchRequests`, `webFetchRequests`, `speed` (`"fast"` or `"standard"`), `serviceTier`, `serviceSpeed` (`"standard"`, `"fast"`, or `"ultrafast"` when requested), and `iterations` (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call). Each `cacheWrite*Tokens` field counts the tokens written to the cache with that lifetime: Claude and Moonshot write 5 minute and 1 hour entries, OpenAI writes 30 minute and 12 hour entries.
 
 #### `message` (String)
 

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/examples.js

@@ -49,6 +49,12 @@ const examples = [
                 slug: 'ai-chatgpt',
                 source: '/playground/examples/ai-chatgpt.html',
             },
+            {
+                title: 'Select Service Speed',
+                description: 'Request faster AI service and inspect the speed that served the response.',
+                slug: 'ai-chat-service-speed',
+                source: '/playground/examples/ai-chat-service-speed.html',
+            },
             {
                 title: 'Image Analysis',
                 description: 'Analyze images with AI using Puter.js GPT Vision API. Run and modify this code example instantly in your browser.',

src/docs/src/playground/examples/ai-chat-service-speed.html

@@ -0,0 +1,13 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script type="module">
+        const response = await puter.ai.chat('Explain closures in one paragraph.', {
+            model: 'gpt-6.1-sol',
+            serviceSpeed: 'ultrafast',
+        });
+        puter.print(response.message.content);
+        puter.print(response.usageDetails.serviceSpeed);
+    </script>
+</body>
+</html>

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 |
 | --- | --- | --- |
@@ -226,6 +226,11 @@ Image and video inputs to [`txt2img()`](/AI/txt2img/) and [`txt2vid()`](/AI/txt2
 
 puter.js uploads a `Blob`, a `File` or a `data:` URI over 1 MiB to a temporary Puter file for the call. It counts against the user's storage until puter.js deletes it after the call.
 
+
+### Chat service speed catalogs
+
+OpenRouter speed endpoint catalogs are cached for 15 minutes, with at most 256 model entries per backend process. A catalog fetch times out after 10 seconds and accepts at most 2 MiB. Failed fetches are remembered for 30 seconds. If no usable speed offering is available, the request uses standard service.
+
 ### Remote chat image inlining
 
 For chat providers that require remote image URLs to be inlined (currently Moonshot):

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/IPC.enablePush.test.js

@@ -46,7 +46,7 @@ vi.mock('./UI/UIWindowFontPicker.js', stub);
 vi.mock('./UI/UIPermissionDialog.js', () => ({ default: permissionDialog }));
 vi.mock('./UI/UIEnablePushDialog.js', () => ({ default: dialog }));
 vi.mock('./UI/UIWindowSaveAccount.js', stub);
-vi.mock('./UI/UIWindowSignup.js', stub);
+vi.mock('./UI/Auth/UIAuthSignup.js', stub);
 vi.mock('./UI/UINotification.js', stub);
 vi.mock('./helpers/godmodeTokens.js', () => ({ renewGodmodeToken: vi.fn() }));
 vi.mock('./helpers/watchItems.js', () => ({ addItemWatcher: vi.fn() }));

src/gui/src/IPC.errors.test.js

@@ -23,7 +23,7 @@ vi.mock('./UI/UIWindowEmailConfirmationRequired.js', stub);
 vi.mock('./UI/UIWindowFontPicker.js', stub);
 vi.mock('./UI/UIPermissionDialog.js', stub);
 vi.mock('./UI/UIWindowSaveAccount.js', stub);
-vi.mock('./UI/UIWindowSignup.js', stub);
+vi.mock('./UI/Auth/UIAuthSignup.js', stub);
 vi.mock('./UI/UINotification.js', stub);
 vi.mock('./helpers/godmodeTokens.js', () => ({ renewGodmodeToken: vi.fn() }));
 vi.mock('./helpers/watchItems.js', () => ({ addItemWatcher: vi.fn() }));

src/gui/src/IPC.js

@@ -18,7 +18,9 @@
  */
 
 import download from './helpers/download.js';
+import ensureConfirmedEmail from './helpers/ensureConfirmedEmail.js';
 import item_icon from './helpers/itemIcon.js';
+import { atPath } from './helpers/pathElements.js';
 import socialLink from './helpers/socialLink.js';
 import update_mouse_position from './helpers/updateMousePosition.js';
 import path from './lib/path.js';
@@ -31,12 +33,10 @@ import UIWindow from './UI/UIWindow.js';
 import UIWindowAppFeedback from './UI/UIWindowAppFeedback.js';
 import UIWindowAttachCustomDomain from './UI/UIWindowAttachCustomDomain.js';
 import UIWindowColorPicker from './UI/UIWindowColorPicker.js';
-import UIWindowEmailConfirmationRequired from './UI/UIWindowEmailConfirmationRequired.js';
 import UIWindowFontPicker from './UI/UIWindowFontPicker.js';
 import UIPermissionDialog from './UI/UIPermissionDialog.js';
 import UIEnablePushDialog from './UI/UIEnablePushDialog.js';
-import UIWindowSaveAccount from './UI/UIWindowSaveAccount.js';
-import UIWindowSignup from './UI/UIWindowSignup.js';
+import UIAuthSignup from './UI/Auth/UIAuthSignup.js';
 import UINotification from './UI/UINotification.js';
 
 import { renewGodmodeToken } from './helpers/godmodeTokens.js';
@@ -235,49 +235,12 @@ const ipc_listener = async (event, handled) => {
     // requestEmailConfirmation
     //--------------------------------------------------------
     else if ( event.data.msg === 'requestEmailConfirmation' ) {
-        // If the user has an email and it is confirmed, respond with success
-        if ( window.user.email && window.user.email_confirmed ) {
-            target_iframe.contentWindow.postMessage({
-                original_msg_id: msg_id,
-                msg: 'requestEmailConfirmationResponded',
-                response: true,
-            }, '*');
-        }
-
-        // If the user is a temporary user, show the save account window
-        if ( window.user.is_temp &&
-            !await UIWindowSaveAccount({
-                send_confirmation_code: true,
-                message: 'Please create an account to proceed.',
-                window_options: {
-                    backdrop: true,
-                    close_on_backdrop_click: false,
-                },
-            }) ) {
-            target_iframe.contentWindow.postMessage({
-                original_msg_id: msg_id,
-                msg: 'requestEmailConfirmationResponded',
-                response: false,
-            }, '*');
-            return;
-        }
-        else if ( !window.user.email_confirmed && !await UIWindowEmailConfirmationRequired() ) {
-            target_iframe.contentWindow.postMessage({
-                original_msg_id: msg_id,
-                msg: 'requestEmailConfirmationResponded',
-                response: false,
-            }, '*');
-            return;
-        }
-
-        const email_confirm_resp = await UIWindowEmailConfirmationRequired({
-            email: window.user.email,
-        });
-
+        // Above the app's window, which stays on top in the dashboard.
+        const confirmed = await ensureConfirmedEmail(i18n('save_account_to_proceed'), { stay_on_top: true });
         target_iframe.contentWindow.postMessage({
             original_msg_id: msg_id,
             msg: 'requestEmailConfirmationResponded',
-            response: email_confirm_resp,
+            response: confirmed,
         }, '*');
     }
     //--------------------------------------------------------
@@ -611,7 +574,7 @@ const ipc_listener = async (event, handled) => {
     //--------------------------------------------------------
     else if ( event.data.msg === 'showOpenFilePicker' ) {
         // Auth
-        if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+        if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
         {
             return;
         }
@@ -677,7 +640,7 @@ const ipc_listener = async (event, handled) => {
     //--------------------------------------------------------
     else if ( event.data.msg === 'showDirectoryPicker' ) {
         // Auth
-        if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+        if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
         {
             return;
         }
@@ -783,7 +746,7 @@ const ipc_listener = async (event, handled) => {
     //--------------------------------------------------------
     else if ( event.data.msg === 'mouseMoved' ) {
         // Auth
-        if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+        if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
         {
             return;
         }
@@ -818,7 +781,7 @@ const ipc_listener = async (event, handled) => {
     //--------------------------------------------------------
     else if ( event.data.msg === 'contextMenu' ) {
         // Auth
-        if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+        if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
         {
             return;
         }
@@ -1384,7 +1347,7 @@ const ipc_listener = async (event, handled) => {
 
         // auth
         try {
-            if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+            if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
             {
                 respond(false);
                 return;
@@ -1490,7 +1453,7 @@ const ipc_listener = async (event, handled) => {
         try {
             // auth
             try {
-                if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+                if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
                 {
                     respond(false);
                     return;
@@ -1543,7 +1506,7 @@ const ipc_listener = async (event, handled) => {
         enable_push_dialog_guard.markOpened();
         try {
             try {
-                if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+                if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
                 {
                     respond('unavailable');
                     return;
@@ -1592,7 +1555,7 @@ const ipc_listener = async (event, handled) => {
         custom_domain_dialog_guard.markOpened();
         try {
             try {
-                if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) ) {
+                if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) ) {
                     respond(null);
                     return;
                 }
@@ -1624,7 +1587,7 @@ const ipc_listener = async (event, handled) => {
     //--------------------------------------------------------
     else if ( event.data.msg === 'showFontPicker' ) {
         // auth
-        if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+        if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
         {
             return;
         }
@@ -1657,7 +1620,7 @@ const ipc_listener = async (event, handled) => {
     //--------------------------------------------------------
     else if ( event.data.msg === 'showColorPicker' ) {
         // Auth
-        if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+        if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
         {
             return;
         }
@@ -1699,7 +1662,7 @@ const ipc_listener = async (event, handled) => {
         }
 
         //auth
-        if ( !window.is_auth() && !(await UIWindowSignup({ referrer: app_name })) )
+        if ( !window.is_auth() && !(await UIAuthSignup({ referrer: app_name })) )
         {
             return;
         }
@@ -1740,7 +1703,7 @@ const ipc_listener = async (event, handled) => {
             $(`.item[data-uid="${res.uid}"]`).removeItems();
             // now add new items
             UIItem({
-                appendTo: $(`.item-container[data-path="${html_encode(path.dirname(target_path))}" i]`),
+                appendTo: atPath('.item-container', path.dirname(target_path)),
                 immutable: res.immutable || res.writable === false,
                 associated_app_name: res.associated_app?.name,
                 path: target_path,
@@ -1754,7 +1717,7 @@ const ipc_listener = async (event, handled) => {
                 suggested_apps: res.suggested_apps,
             });
             // sort each window
-            $(`.item-container[data-path="${html_encode(path.dirname(target_path))}" i]`).each(function () {
+            atPath('.item-container', path.dirname(target_path)).each(function () {
                 window.sort_items(this, $(this).attr('data-sort_by'), $(this).attr('data-sort_order'));
             });
             $(el_filedialog_window).close();

src/gui/src/IPC.requestEmailConfirmation.test.js

@@ -0,0 +1,146 @@
+// @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 { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import jQuery from './lib/jquery-3.6.1/jquery-3.6.1.min.js';
+
+globalThis.def = globalThis.def ?? ((cls) => cls);
+globalThis.use = globalThis.use ?? (() => ({}));
+globalThis.$ = globalThis.jQuery = jQuery;
+globalThis.i18n = (key) => key;
+
+const { stub, confirmEmail, saveAccount } = vi.hoisted(() => ({
+    stub: () => ({ default: () => {} }),
+    confirmEmail: vi.fn(),
+    saveAccount: vi.fn(),
+}));
+vi.mock('./helpers/download.js', stub);
+vi.mock('./helpers/itemIcon.js', stub);
+vi.mock('./helpers/socialLink.js', stub);
+vi.mock('./helpers/updateMousePosition.js', stub);
+vi.mock('./UI/UIAlert.js', stub);
+vi.mock('./UI/UIContextMenu.js', stub);
+vi.mock('./UI/UIItem.js', stub);
+vi.mock('./UI/UIPopover.js', stub);
+vi.mock('./UI/UIPrompt.js', stub);
+vi.mock('./UI/UIWindow.js', stub);
+vi.mock('./UI/UIWindowAppFeedback.js', stub);
+vi.mock('./UI/UIWindowColorPicker.js', stub);
+vi.mock('./UI/UIWindowEmailConfirmationRequired.js', () => ({ default: confirmEmail }));
+vi.mock('./UI/UIWindowFontPicker.js', stub);
+vi.mock('./UI/UIPermissionDialog.js', stub);
+vi.mock('./UI/UIEnablePushDialog.js', stub);
+vi.mock('./UI/UIWindowSaveAccount.js', () => ({ default: saveAccount }));
+vi.mock('./UI/Auth/UIAuthSignup.js', stub);
+vi.mock('./UI/UINotification.js', stub);
+vi.mock('./helpers/godmodeTokens.js', () => ({ renewGodmodeToken: vi.fn() }));
+vi.mock('./helpers/watchItems.js', () => ({ addItemWatcher: vi.fn() }));
+vi.mock('./helpers/verification_gates.js', () => ({
+    openVerificationGateWindow: vi.fn(),
+}));
+
+let iframe;
+let posted;
+
+beforeAll(async () => {
+    window.when_puter_happens = [];
+    window.appCallbackFunctions = {};
+    await import('./IPC.js');
+    globalThis.puter = { services: undefined, util: { rpc: { send: vi.fn() } } };
+    for (const fn of window.when_puter_happens) await fn();
+});
+
+beforeEach(() => {
+    confirmEmail.mockReset();
+    saveAccount.mockReset();
+    document.body.innerHTML = '';
+    const win = document.createElement('div');
+    win.setAttribute('data-app_uuid', 'app-1');
+    iframe = document.createElement('iframe');
+    iframe.setAttribute('data-app', 'notes');
+    win.append(iframe);
+    document.body.append(win);
+    posted = vi.spyOn(iframe.contentWindow, 'postMessage').mockImplementation(() => {});
+    window.app_instance_ids = new Set(['inst-1']);
+    window.iframe_for_app_instance = (id) => (id === 'inst-1' ? iframe : null);
+    window.window_for_app_instance = () => win;
+    window.is_auth = () => true;
+    window.ipc_handlers = {};
+    globalThis.services = { get: () => ({ get_by_uuid: () => ({ name: 'caller', uuid: 'inst-1' }) }) };
+});
+
+const request = () =>
+    window.dispatchEvent(
+        new MessageEvent('message', {
+            data: { appInstanceID: 'inst-1', env: 'app', msg: 'requestEmailConfirmation', uuid: 'cb-1' },
+            source: iframe.contentWindow,
+            origin: 'https://app.example',
+        }),
+    );
+
+const settle = () => new Promise((r) => setTimeout(r, 20));
+
+const replies = () => posted.mock.calls
+    .map(([data]) => data)
+    .filter((data) => data.msg === 'requestEmailConfirmationResponded');
+
+describe('requestEmailConfirmation', () => {
+    it('answers a confirmed email true once, without a dialog', async () => {
+        window.user = { email: '[email protected]', email_confirmed: true };
+        request();
+        await settle();
+        expect(replies()).toEqual([{ original_msg_id: 'cb-1', msg: 'requestEmailConfirmationResponded', response: true }]);
+        expect(confirmEmail).not.toHaveBeenCalled();
+        expect(saveAccount).not.toHaveBeenCalled();
+    });
+
+    it.each([true, false])('shows an unconfirmed email one dialog and answers its result, %s', async (answer) => {
+        window.user = { email: '[email protected]', email_confirmed: false };
+        confirmEmail.mockResolvedValueOnce(answer);
+        request();
+        await settle();
+        expect(confirmEmail).toHaveBeenCalledTimes(1);
+        // The app's window stays on top in the dashboard, so the dialog has to as well.
+        expect(confirmEmail).toHaveBeenCalledWith({ window_options: { stay_on_top: true } });
+        expect(replies()).toEqual([{ original_msg_id: 'cb-1', msg: 'requestEmailConfirmationResponded', response: answer }]);
+    });
+
+    it('answers false once when a temporary account isn\'t saved', async () => {
+        window.user = { is_temp: true };
+        saveAccount.mockResolvedValueOnce(false);
+        request();
+        await settle();
+        expect(saveAccount).toHaveBeenCalledTimes(1);
+        expect(saveAccount.mock.calls[0][0].window_options).toMatchObject({ stay_on_top: true });
+        expect(confirmEmail).not.toHaveBeenCalled();
+        expect(replies()).toEqual([{ original_msg_id: 'cb-1', msg: 'requestEmailConfirmationResponded', response: false }]);
+    });
+
+    it('asks a temporary account that confirmed while saving for nothing more', async () => {
+        window.user = { is_temp: true };
+        saveAccount.mockImplementationOnce(async () => {
+            window.user = { is_temp: false, email: '[email protected]', email_confirmed: true };
+            return true;
+        });
+        request();
+        await settle();
+        expect(confirmEmail).not.toHaveBeenCalled();
+        expect(replies()).toEqual([{ original_msg_id: 'cb-1', msg: 'requestEmailConfirmationResponded', response: true }]);
+    });
+});

src/gui/src/UI/Auth/UIAuth2FA.js

@@ -0,0 +1,292 @@
+/*
+ * 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 second factor of a login: a code from the user's authenticator app,
+// or one of their recovery codes. Verifies the challenge the first factor
+// (a password, or an identity provider) was answered with.
+
+import { SVG } from '../Dashboard/UIDashboardDialog.js';
+import openAuthFlow, { keepCurrentSession, setAuthStatus } from './authFlow.js';
+
+const CODE_LENGTH = 6;
+const RECOVERY_CODE_LENGTH = 8;
+// How long a wrong code stays on screen before the boxes clear for another try.
+const WRONG_CODE_MS = 1200;
+
+const SHIELD_ICON = SVG('<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>');
+
+/**
+ * Sends a code for the challenge. Both routes are `guiOriginOnly` and carry
+ * no `subdomain`, so they go to the root origin: on `api_origin` the
+ * subdomain gate skips them and Express 404s.
+ *
+ * @param {'otp'|'recovery-code'} route
+ * @param {string} token The first factor's challenge.
+ * @param {string} code
+ * @returns {Promise<{ ok: true, data: object } | { ok: false, error: string }>}
+ *   `error` is an i18n key.
+ */
+export const verifySecondFactor = async (route, token, code) => {
+    try {
+        const resp = await fetch(`${window.gui_origin}/login/${route}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ token, code }),
+        });
+        if ( resp.status === 429 ) return { ok: false, error: 'confirm_code_generic_too_many_requests' };
+        const data = await resp.json();
+        if ( ! data?.proceed ) return { ok: false, error: 'confirm_code_generic_incorrect' };
+        return { ok: true, data };
+    } catch {
+        return { ok: false, error: 'something_went_wrong' };
+    }
+};
+
+/**
+ * A screen's head: the shield, a title and what to do.
+ *
+ * @param {string} title i18n key.
+ * @param {string} instructions i18n key.
+ * @returns {string}
+ */
+const headHtml = (title, instructions) => '<div class="auth-head">'
+    + `<div class="auth-badge" aria-hidden="true">${SHIELD_ICON}</div>`
+    + `<h1 class="auth-title">${i18n(title)}</h1>`
+    + `<p class="auth-subtitle">${i18n(instructions)}</p>`
+    + '</div>';
+
+/**
+ * Shows the recovery code screen over the code screen; Back returns to it.
+ *
+ * @param {import('./authFlow.js').AuthFlow} flow
+ * @param {string} token
+ * @param {(data: object) => void} onVerified
+ */
+const pushRecoveryScreen = (flow, token, onVerified) => {
+    let h = '<div class="dashboard-dialog-body auth-body">';
+    h += headHtml('login2fa_recovery_title', 'login2fa_recovery_instructions');
+    h += '<form class="auth-form login-2fa-recovery-form" novalidate>';
+    h += '<div class="dashboard-form-status" role="status" aria-live="polite"></div>';
+    h += `<input type="text" class="dashboard-dialog-input login-2fa-recovery-input" maxlength="${RECOVERY_CODE_LENGTH}"`;
+    h += ` placeholder="${html_encode(i18n('login2fa_recovery_placeholder', [], false))}" aria-label="${i18n('login2fa_recovery_title')}"`;
+    h += ' autocomplete="off" autocapitalize="characters" autocorrect="off" spellcheck="false">';
+    h += '</form>';
+    h += '</div>';
+
+    const $screen = flow.push({ name: 'recovery-code', html: h });
+    const $input = $screen.find('.login-2fa-recovery-input');
+    let verifying = false;
+
+    const verify = async () => {
+        // Codes are 8-char base32; a pasted one usually carries the newline
+        // it was copied with.
+        const value = String($input.val() ?? '').trim().toUpperCase();
+        if ( value.length !== RECOVERY_CODE_LENGTH || verifying ) return;
+        verifying = true;
+        flow.setBusy(true);
+        setAuthStatus($screen, i18n('verifying', [], false), { kind: 'info' });
+        const result = await verifySecondFactor('recovery-code', token, value);
+        verifying = false;
+        if ( flow.isClosed() ) {
+            if ( result.ok ) keepCurrentSession();
+            return;
+        }
+        if ( result.ok ) {
+            onVerified(result.data);
+            return;
+        }
+        flow.setBusy(false);
+        setAuthStatus($screen, i18n(result.error, [], false), { field: '.login-2fa-recovery-input' });
+        $input.get(0)?.select();
+    };
+
+    $input.on('input', verify);
+    $screen.find('form').on('submit', (e) => {
+        e.preventDefault();
+        verify();
+    });
+};
+
+/**
+ * Shows the code screen in `flow`. Back leaves it unanswered.
+ *
+ * @param {import('./authFlow.js').AuthFlow} flow
+ * @param {string} token The first factor's challenge.
+ * @param {{ onBack?: () => void }} [opts] `onBack` makes Back available when
+ *   this is the flow's first screen.
+ * @returns {Promise<object | null>} What the server answered a verified code
+ *   with (the session's token and user, and where to go); null when the user
+ *   went back or the flow closed.
+ */
+export function pushTwoFactorScreen (flow, token, { onBack } = {}) {
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (value) => {
+            if ( done ) return;
+            done = true;
+            resolve(value);
+        };
+
+        let h = '<div class="dashboard-dialog-body auth-body">';
+        h += headHtml('login2fa_otp_title', 'login2fa_otp_instructions');
+        h += '<form class="auth-form login-2fa-form" novalidate>';
+        h += '<div class="dashboard-form-status" role="status" aria-live="polite"></div>';
+        h += `<div class="login-2fa-code-inputs" role="group" aria-label="${i18n('login2fa_otp_title')}">`;
+        for ( let i = 0; i < CODE_LENGTH; i++ ) {
+            // The first box takes a whole code from autofill or a paste.
+            h += `<input type="text" class="dashboard-dialog-input" inputmode="numeric" pattern="[0-9]*" data-idx="${i}"`;
+            h += ` aria-label="${i + 1}" autocomplete="${i === 0 ? 'one-time-code' : 'off'}">`;
+        }
+        h += '</div>';
+        h += `<div class="auth-link-row"><button type="button" class="auth-link login-2fa-to-recovery">${i18n('login2fa_use_recovery_code')}</button></div>`;
+        h += '</form>';
+        h += '</div>';
+
+        const $screen = flow.push({
+            name: 'two-factor',
+            html: h,
+            onBack: onBack ?? undefined,
+            onLeave: () => finish(null),
+        });
+        const $inputs = $screen.find('.login-2fa-code-inputs input');
+        let verifying = false;
+
+        const code = () => $inputs.map(function () {
+            return $(this).val();
+        }).get().join('');
+
+        const verified = (data) => finish(data);
+
+        const verify = async (value) => {
+            if ( verifying || value.length !== CODE_LENGTH ) return;
+            verifying = true;
+            flow.setBusy(true);
+            $inputs.prop('disabled', true);
+            setAuthStatus($screen, i18n('verifying', [], false), { kind: 'info' });
+            const result = await verifySecondFactor('otp', token, value);
+            verifying = false;
+            // Dismissed while the code was out: stay signed in as before.
+            if ( flow.isClosed() ) {
+                if ( result.ok ) keepCurrentSession();
+                return;
+            }
+            if ( result.ok ) {
+                verified(result.data);
+                return;
+            }
+            flow.setBusy(false);
+            $inputs.prop('disabled', false);
+            setAuthStatus($screen, i18n(result.error, [], false));
+            $inputs.addClass('login-2fa-wrong').attr('aria-invalid', 'true');
+            setTimeout(() => {
+                if ( verifying ) return;
+                $inputs.val('').removeClass('login-2fa-wrong').removeAttr('aria-invalid');
+                if ( ! $screen.prop('hidden') ) $inputs.first().trigger('focus');
+            }, WRONG_CODE_MS);
+        };
+
+        /** Spreads digits over the boxes from `start`, and verifies a full code. */
+        const fill = (digits, start) => {
+            for ( let i = 0; i < digits.length && start + i < CODE_LENGTH; i++ ) {
+                $inputs.eq(start + i).val(digits[i]);
+            }
+            const next = Math.min(start + digits.length, CODE_LENGTH - 1);
+            $inputs.eq(next).trigger('focus');
+            verify(code());
+        };
+
+        $inputs.on('input', function () {
+            const idx = Number($(this).attr('data-idx'));
+            const digits = String($(this).val() ?? '').replace(/\D/g, '');
+            $inputs.removeClass('login-2fa-wrong').removeAttr('aria-invalid');
+            if ( ! digits ) {
+                $(this).val('');
+                return;
+            }
+            // One digit typed, or a whole code autofilled into this box.
+            $(this).val(digits[0]);
+            if ( digits.length > 1 ) {
+                fill(digits.slice(1), idx + 1);
+                return;
+            }
+            if ( idx < CODE_LENGTH - 1 ) $inputs.eq(idx + 1).trigger('focus');
+            verify(code());
+        });
+
+        $inputs.on('keydown', function (e) {
+            const idx = Number($(this).attr('data-idx'));
+            if ( e.key === 'Backspace' && ! $(this).val() && idx > 0 ) {
+                e.preventDefault();
+                $inputs.eq(idx - 1).val('').trigger('focus');
+            } else if ( e.key === 'ArrowLeft' && idx > 0 ) {
+                e.preventDefault();
+                $inputs.eq(idx - 1).trigger('focus');
+            } else if ( e.key === 'ArrowRight' && idx < CODE_LENGTH - 1 ) {
+                e.preventDefault();
+                $inputs.eq(idx + 1).trigger('focus');
+            }
+        });
+
+        $inputs.on('focus', function () {
+            this.select();
+        });
+
+        $inputs.on('paste', function (e) {
+            e.preventDefault();
+            const clipboard = e.originalEvent?.clipboardData ?? window.clipboardData;
+            const pasted = String(clipboard?.getData('text') ?? '').replace(/\D/g, '').slice(0, CODE_LENGTH);
+            if ( ! pasted ) return;
+            $inputs.val('');
+            fill(pasted, 0);
+        });
+
+        $screen.find('form').on('submit', (e) => {
+            e.preventDefault();
+            verify(code());
+        });
+
+        $screen.find('.login-2fa-to-recovery').on('click', () => {
+            if ( flow.isBusy() ) return;
+            $inputs.val('').removeClass('login-2fa-wrong').removeAttr('aria-invalid');
+            setAuthStatus($screen, '');
+            pushRecoveryScreen(flow, token, verified);
+        });
+    });
+}
+
+/**
+ * Asks for the second factor of a login on a page of its own (an identity
+ * provider's login that came back needing one). The card stays up, busy,
+ * once the code is verified: the caller is expected to navigate.
+ *
+ * @param {string} token The first factor's challenge.
+ * @returns {Promise<object | null>} The server's answer to a verified code;
+ *   null when the user chose to go back to the login.
+ */
+export default function UIAuth2FA (token) {
+    const flow = openAuthFlow({ page: true });
+    const answer = pushTwoFactorScreen(flow, token, {
+        onBack: () => flow.settle(null),
+    });
+    answer.then((data) => {
+        if ( data ) flow.setBusy(true);
+        flow.settle(data);
+    });
+    return flow.result;
+}

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

@@ -0,0 +1,150 @@
+/*
+ * 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 account picker: the accounts signed in on this browser, to continue
+// as one of them, log in to another, or create one. In a sign-in popup,
+// picking an account is the user's consent to sign the opener in.
+
+import { SVG } from '../Dashboard/UIDashboardDialog.js';
+import openAuthFlow, { authHeadHtml, joinAuthFlow, wireAuthHead } from './authFlow.js';
+import { pushLoginScreen } from './UIAuthLogin.js';
+import { pushSignupScreen } from './UIAuthSignup.js';
+
+const CHEVRON_ICON = SVG('<path d="M9 18l6-6-6-6"/>');
+
+/**
+ * One account's row.
+ *
+ * @param {{ uuid: string, username: string, email?: string, profile?: { picture?: string } }} account
+ * @returns {string}
+ */
+const accountRowHtml = (account) => {
+    const username = String(account.username ?? '');
+    const initial = username.charAt(0).toUpperCase();
+    let h = '<li>';
+    h += `<button type="button" class="auth-account" data-uuid="${html_encode(account.uuid)}">`;
+    h += `<span class="auth-account-avatar" aria-hidden="true">${html_encode(initial)}</span>`;
+    h += '<span class="auth-account-text">';
+    h += `<span class="auth-account-name">${html_encode(username)}</span>`;
+    if ( account.email ) h += `<span class="auth-account-detail">${html_encode(account.email)}</span>`;
+    h += '</span>';
+    h += '<span class="dashboard-form-spinner auth-account-spinner" aria-hidden="true"></span>';
+    h += `<span class="auth-account-chevron" aria-hidden="true">${CHEVRON_ICON}</span>`;
+    h += '</button>';
+    h += '</li>';
+    return h;
+};
+
+/**
+ * Lays each account's picture over its initial. Set as a property, never
+ * through markup; a picture that fails to load leaves the initial.
+ *
+ * @param {jQuery} $screen
+ * @param {Array<{ uuid: string, profile?: { picture?: string } }>} accounts
+ */
+const paintPictures = ($screen, accounts) => {
+    for ( const account of accounts ) {
+        const picture = account.profile?.picture;
+        if ( typeof picture !== 'string' || ! picture ) continue;
+        const el_avatar = $screen.find('.auth-account').filter((_, el) => el.dataset.uuid === String(account.uuid))
+            .find('.auth-account-avatar').get(0);
+        if ( ! el_avatar ) continue;
+        const img = document.createElement('img');
+        img.alt = '';
+        img.draggable = false;
+        img.addEventListener('error', () => img.remove(), { once: true });
+        img.src = picture;
+        el_avatar.appendChild(img);
+    }
+};
+
+/**
+ * Shows the account picker in `flow`.
+ *
+ * @param {import('./authFlow.js').AuthFlow} flow
+ * @returns {jQuery}
+ */
+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">';
+    // 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>';
+    h += '</div>';
+    h += '<div class="dashboard-dialog-footer auth-footer">';
+    h += `<button type="button" class="auth-link auth-to-login">${i18n('add_another_account')}</button>`;
+    h += '<span class="auth-footer-sep" aria-hidden="true">·</span>';
+    h += `<button type="button" class="auth-link auth-to-signup">${i18n('create_account')}</button>`;
+    h += '</div>';
+
+    // Nothing to type here; focus lands on the card, not on an account.
+    const $screen = flow.push({ name: 'accounts', html: h, autofocus: false });
+    wireAuthHead($screen);
+    paintPictures($screen, accounts);
+
+    $screen.find('.auth-to-login').on('click', () => {
+        if ( flow.isBusy() ) return;
+        if ( ! flow.goTo('login') ) pushLoginScreen(flow);
+    });
+    $screen.find('.auth-to-signup').on('click', () => {
+        if ( flow.isBusy() ) return;
+        if ( ! flow.goTo('signup') ) pushSignupScreen(flow);
+    });
+
+    $screen.find('.auth-account').on('click', async function () {
+        if ( flow.isBusy() ) return;
+        const uuid = this.dataset.uuid;
+        const account = accounts.find((candidate) => String(candidate.uuid) === uuid);
+        if ( ! account ) return;
+        flow.setBusy(true);
+        $screen.find('.auth-account').prop('disabled', true);
+        $(this).addClass('dashboard-form-busy').attr('aria-busy', 'true');
+
+        await window.update_auth_data(account.auth_token, account);
+        if ( flow.options.reload_on_success ) {
+            // Disable the browser's own "leave this page?" prompt.
+            window.onbeforeunload = null;
+            location.reload();
+            return;
+        }
+        flow.finish(true);
+    });
+
+    return $screen;
+}
+
+/**
+ * Asks which of the accounts signed in on this browser to continue as.
+ *
+ * @param {Partial<import('./authFlow.js').AuthFlowOptions> & { page?: boolean }} [options]
+ *   The picker can't be dismissed: it stands between a sign-in popup and
+ *   the token it hands out, and on a signed-out boot it is the page.
+ * @returns {Promise<boolean>} True once an account is picked or signed in,
+ *   unless the page reloads first.
+ */
+export default function UIAuthAccountPicker (options = {}) {
+    const joined = joinAuthFlow();
+    if ( joined ) return joined;
+    const flow = openAuthFlow({ page: options.page, dismissable: false, options });
+    pushAccountPickerScreen(flow);
+    return flow.result;
+}

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

@@ -0,0 +1,293 @@
+/*
+ * 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 login screen: email or username and password, the identity provider
+// buttons, and the ways to the signup and password recovery screens.
+
+import { bindPasswordReveal, formFieldHtml } from '../Dashboard/UIDashboardFormDialog.js';
+import openAuthFlow, {
+    authHeadHtml,
+    joinAuthFlow,
+    keepCurrentSession,
+    navigateAfterSignIn,
+    setAuthStatus,
+    setFormBusy,
+    submitButtonHtml,
+    wireAuthHead,
+} from './authFlow.js';
+import { renderProviderButtons } from './authProviders.js';
+import { pushTwoFactorScreen } from './UIAuth2FA.js';
+import { pushRecoverPasswordScreen } from './UIAuthRecoverPassword.js';
+import { pushSignupScreen } from './UIAuthSignup.js';
+
+/**
+ * @typedef {object} LoginScreenOptions
+ * @property {string} [email_or_username] Prefills the first field.
+ * @property {string} [authError] Shown when the screen opens.
+ * @property {string} [auth_id] Sent with the login when it follows a
+ *   `reauth_required` 401, so the backend re-attaches the same identity.
+ * @property {string} [reauth_reason]
+ */
+
+/**
+ * Clears credentials a link may have put in the address bar.
+ */
+const clearCredentialsFromUrl = () => {
+    const search = window.location.search;
+    if ( search && (search.includes('password=') || search.includes('username=') || search.includes('email=')) ) {
+        history.replaceState({}, document.title, window.location.origin + window.location.pathname);
+    }
+};
+
+/**
+ * What to tell the user about a failed login request.
+ *
+ * @param {{ status?: number, responseText?: string }} err
+ * @returns {{ text?: string, html?: string }}
+ */
+export const loginErrorMessage = (err) => {
+    const response_text = err?.responseText || '';
+    try {
+        const json = JSON.parse(response_text);
+        if ( json?.message ) return { text: String(json.message) };
+    } catch {
+        // Not JSON.
+    }
+    if ( err?.status === 404 ) {
+        // Not the whole 404 page.
+        return { text: `Error 404: "${window.gui_origin}/login" not found` };
+    }
+    if ( response_text ) return { text: response_text };
+    // No answer at all usually means the server couldn't be reached; on a
+    // self-hosted instance that's most likely its configuration.
+    if ( window.app_domain !== 'puter.com' ) {
+        const origin = html_encode(window.gui_origin);
+        return {
+            html: '<div class="auth-status-help">'
+                + `<p>Error reaching "${origin}/login". This is likely to be a configuration issue.</p>`
+                + '<p>Make sure of the following:</p>'
+                + '<ul>'
+                + '<li><code>domain</code> in config.json is set to the domain you\'re using to access puter</li>'
+                + '<li>DNS resolves for the domain, and the <code>api.</code> subdomain on that domain</li>'
+                + '<li><code>http_port</code> is set to the port Puter is listening on (<code>auto</code> will use <code>4100</code> unless that port is in use)</li>'
+                + '<li><code>pub_port</code> is set to the external port (ex: <code>443</code> if you\'re using a reverse proxy that serves over https)</li>'
+                + '</ul></div>',
+        };
+    }
+    return { text: `Failed to log in: Error ${err?.status ?? ''}`.trim() };
+};
+
+/**
+ * Shows the login screen in `flow`.
+ *
+ * @param {import('./authFlow.js').AuthFlow} flow
+ * @param {LoginScreenOptions} [options]
+ * @returns {jQuery}
+ */
+export function pushLoginScreen (flow, options = {}) {
+    const id = `auth-login-${window.uuidv4?.() ?? Date.now()}`;
+
+    let h = '<div class="dashboard-dialog-body auth-body">';
+    // 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({
+        name: 'email_or_username',
+        label: i18n('email_or_username'),
+        value: options.email_or_username ?? '',
+        attrs: { autocomplete: 'username', autocapitalize: 'off', autocorrect: 'off', spellcheck: 'false' },
+    }, id);
+    h += formFieldHtml({
+        name: 'password',
+        type: 'password',
+        label: i18n('password'),
+        attrs: { autocomplete: 'current-password' },
+    }, id);
+    h += `<div class="auth-forgot-row"><button type="button" class="auth-link forgot-password-link">${i18n('forgot_pass_c2a')}</button></div>`;
+    h += submitButtonHtml(i18n('log_in', [], false), 'login-btn');
+    h += '</form>';
+    h += '<div class="auth-providers" hidden>';
+    h += `<div class="auth-divider"><span>${i18n('or')}</span></div>`;
+    h += '<div class="auth-provider-list"></div>';
+    h += '</div>';
+    h += '</div>';
+    if ( flow.options.show_signup_button ) {
+        h += '<div class="dashboard-dialog-footer auth-footer">';
+        h += `<button type="button" class="auth-link auth-to-signup">${i18n('create_free_account')}</button>`;
+        h += '</div>';
+    }
+
+    const $screen = flow.push({
+        name: 'login',
+        html: h,
+        autofocus: ! window.disable_login_autofocus,
+    });
+    const $form = $screen.find('.login-form');
+    const $user = $form.find('[name="email_or_username"]');
+    const $password = $form.find('[name="password"]');
+
+    wireAuthHead($screen);
+    bindPasswordReveal($form);
+    if ( options.authError ) setAuthStatus($screen, options.authError);
+
+    $form.on('input', '.dashboard-form-input', function () {
+        $(this).removeAttr('aria-invalid');
+    });
+
+    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);
+    });
+
+    $screen.find('.forgot-password-link').on('click', () => {
+        if ( flow.isBusy() ) return;
+        pushRecoverPasswordScreen(flow, { email_or_username: String($user.val() ?? '').trim() });
+    });
+
+    $screen.find('.auth-to-signup').on('click', () => {
+        if ( flow.isBusy() ) return;
+        if ( ! flow.goTo('signup') ) pushSignupScreen(flow);
+    });
+
+    // The form first, so the end of busy can hand focus back to a field.
+    const unlock = () => {
+        setFormBusy($form, false);
+        flow.setBusy(false);
+    };
+
+    $form.on('submit', async (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        if ( flow.isBusy() ) return;
+
+        const email_username = String($user.val() ?? '').trim();
+        const password = String($password.val() ?? '');
+        if ( ! email_username ) {
+            setAuthStatus($screen, i18n('login_email_username_required', [], false), { field: '[name="email_or_username"]' });
+            return;
+        }
+        if ( ! password ) {
+            setAuthStatus($screen, i18n('login_password_required', [], false), { field: '[name="password"]' });
+            return;
+        }
+        setAuthStatus($screen, '');
+
+        // After a `reauth_required` 401, the login re-attaches the same
+        // stable identity.
+        const reauth = options.auth_id ? { auth_id: options.auth_id, reauth_reason: options.reauth_reason } : {};
+        const body = window.is_email(email_username)
+            ? { email: email_username, password, ...reauth }
+            : { username: email_username, password, ...reauth };
+
+        flow.setBusy(true);
+        setFormBusy($form, true);
+
+        let data;
+        try {
+            data = await new Promise((resolve, reject) => {
+                $.ajax({
+                    url: `${window.gui_origin}/login`,
+                    type: 'POST',
+                    async: true,
+                    headers: window.custom_headers ?? {},
+                    contentType: 'application/json',
+                    data: JSON.stringify(body),
+                    success: resolve,
+                    error: reject,
+                });
+            });
+        } catch ( err ) {
+            clearCredentialsFromUrl();
+            unlock();
+            if ( flow.isClosed() ) return;
+            const message = loginErrorMessage(err);
+            setAuthStatus($screen, message.text ?? '', { html: message.html });
+            // A refused password is typed again; a refused name is fixed there.
+            $password.get(0)?.focus({ preventScroll: true });
+            $password.get(0)?.select?.();
+            return;
+        }
+        // Dismissed while the request was out: the caller already heard no,
+        // so this browser stays signed in as it was.
+        if ( flow.isClosed() ) {
+            if ( data?.token ) keepCurrentSession();
+            return;
+        }
+
+        if ( data?.next_step === 'otp' ) {
+            // The second factor is a screen of its own; Back returns here.
+            flow.setBusy(false);
+            const verified = await pushTwoFactorScreen(flow, data.otp_jwt_token);
+            if ( ! verified ) {
+                setFormBusy($form, false);
+                if ( ! flow.isClosed() ) flow.focus();
+                return;
+            }
+            flow.setBusy(true);
+            data = verified;
+        }
+
+        try {
+            await window.update_auth_data(data.token, data.user);
+        } catch ( err ) {
+            unlock();
+            // Back from a verified code, whose screen would otherwise stay up, busy.
+            if ( $screen.prop('hidden') ) flow.goTo('login');
+            setAuthStatus($screen, err?.message || i18n('something_went_wrong', [], false));
+            return;
+        }
+
+        if ( flow.options.reload_on_success ) {
+            // A clean URL, so no credentials stay in it. The card stays up,
+            // busy, while the page goes.
+            navigateAfterSignIn(flow.options.redirect_url || window.location.origin + window.location.pathname);
+            return;
+        }
+        flow.finish(true);
+    });
+
+    return $screen;
+}
+
+/**
+ * Asks the user to log in.
+ *
+ * @param {Partial<import('./authFlow.js').AuthFlowOptions> & LoginScreenOptions & {
+ *   page?: boolean, dismissable?: boolean, closeOnBackdrop?: boolean,
+ * }} [options] `page`, `dismissable` and `closeOnBackdrop` as in `openAuthFlow`.
+ * @returns {Promise<boolean>} True once signed in, unless the page reloads
+ *   first; false when the user dismisses it. Joins an auth flow that is
+ *   already open instead of opening another.
+ */
+export default function UIAuthLogin (options = {}) {
+    const joined = joinAuthFlow();
+    if ( joined ) return joined;
+    const flow = openAuthFlow({
+        page: options.page,
+        dismissable: options.dismissable,
+        closeOnBackdrop: options.closeOnBackdrop,
+        options,
+    });
+    pushLoginScreen(flow, options);
+    return flow.result;
+}

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

@@ -0,0 +1,386 @@
+// @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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { reply, resetAuthGlobals, screen, tick } from './authTestSetup.js';
+
+vi.mock('../UIWindowEmailConfirmationRequired.js', () => ({ default: vi.fn() }));
+vi.mock('../UIWindowPhoneVerificationRequired.js', () => ({ default: vi.fn() }));
+vi.mock('../UIWindowCardVerificationRequired.js', () => ({ default: vi.fn() }));
+
+const { activeAuthFlow } = await import('./authFlow.js');
+const { default: UIAuthLogin, loginErrorMessage } = await import('./UIAuthLogin.js');
+const { default: UIAuth2FA } = await import('./UIAuth2FA.js');
+
+const completed = { proceed: true, next_step: 'complete', token: 'gui-token', user: { username: 'user' }, redirectUrl: 'https://puter.test/dashboard' };
+
+/** Captures the login request; returns its callbacks. */
+const captureAjax = () => {
+    const calls = [];
+    vi.spyOn($, 'ajax').mockImplementation((opts) => {
+        calls.push(opts);
+    });
+    return calls;
+};
+
+const submitLogin = (user = 'user', password = 'correct-password') => {
+    $('[name="email_or_username"]').val(user);
+    $('[name="password"]').val(password);
+    $('.login-form').trigger('submit');
+};
+
+const enterOtp = (code) => {
+    const inputs = $('.login-2fa-code-inputs input');
+    [...code].forEach((digit, index) => inputs.eq(index).val(digit));
+    inputs.last().trigger('input');
+};
+
+beforeEach(() => {
+    resetAuthGlobals();
+});
+afterEach(() => {
+    activeAuthFlow()?.finish(false);
+    vi.restoreAllMocks();
+});
+
+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 });
+        $('.login-form').trigger('submit');
+        expect(screen().find('.dashboard-form-status').text()).toBe('login_email_username_required');
+        expect($('[name="email_or_username"]').attr('aria-invalid')).toBe('true');
+        $('[name="email_or_username"]').val('user');
+        $('.login-form').trigger('submit');
+        expect(screen().find('.dashboard-form-status').text()).toBe('login_password_required');
+        expect(calls).toHaveLength(0);
+    });
+
+    it('logs in by username or email, forwarding a reauth identity', async () => {
+        const calls = captureAjax();
+        const result = UIAuthLogin({ reload_on_success: false, auth_id: 'aid', reauth_reason: 'rotated' });
+        submitLogin(' [email protected] ');
+        expect(JSON.parse(calls[0].data)).toEqual({ email: '[email protected]', password: 'correct-password', auth_id: 'aid', reauth_reason: 'rotated' });
+        expect($('.login-btn').hasClass('dashboard-form-busy')).toBe(true);
+        calls[0].success({ token: 't', user: { username: 'someone' } });
+        await expect(result).resolves.toBe(true);
+        expect(window.update_auth_data).toHaveBeenCalledWith('t', { username: 'someone' });
+        expect(activeAuthFlow()).toBeNull();
+    });
+
+    it('shows the server message, unlocks, and puts the user back on the password', async () => {
+        const calls = captureAjax();
+        void UIAuthLogin({ reload_on_success: false });
+        submitLogin('user', 'nope');
+        calls[0].error({ status: 400, responseText: JSON.stringify({ message: '<b>Wrong</b> password' }) });
+        await tick();
+        // Text, never markup from the server.
+        expect(screen().find('.dashboard-form-status').text()).toBe('<b>Wrong</b> password');
+        expect(screen().find('.dashboard-form-status b')).toHaveLength(0);
+        expect($('[name="password"]').prop('disabled')).toBe(false);
+        expect(activeAuthFlow().isBusy()).toBe(false);
+    });
+
+    it('stays signed in as before when dismissed while the login is out', async () => {
+        window.auth_token = 'current-token';
+        const calls = captureAjax();
+        const result = UIAuthLogin();
+        submitLogin();
+        $('.dashboard-dialog-close').trigger('click');
+        await expect(result).resolves.toBe(false);
+        calls[0].success({ token: 't', user: { username: 'other' } });
+        await tick();
+        expect(window.update_auth_data).not.toHaveBeenCalled();
+        // The server answered by moving the session cookie; it comes back.
+        expect(fetch).toHaveBeenCalledWith('https://puter.test/session/sync-cookie', expect.objectContaining({
+            headers: { Authorization: 'Bearer current-token' },
+        }));
+    });
+
+    it('leaves the session cookie alone when a dismissed login only asked for a code', async () => {
+        window.auth_token = 'current-token';
+        const calls = captureAjax();
+        void UIAuthLogin();
+        submitLogin();
+        $('.dashboard-dialog-close').trigger('click');
+        calls[0].success({ proceed: true, next_step: 'otp', otp_jwt_token: 'c' });
+        await tick();
+        expect(fetch.mock.calls.some(([url]) => String(url).endsWith('/session/sync-cookie'))).toBe(false);
+    });
+
+    it('encodes a prefilled username', () => {
+        void UIAuthLogin({ email_or_username: '"><img src=x onerror=alert(1)>' });
+        expect($('.auth-dialog img[src="x"]')).toHaveLength(0);
+        expect($('[name="email_or_username"]').val()).toBe('"><img src=x onerror=alert(1)>');
+    });
+
+    it('hides the signup link when asked to', () => {
+        void UIAuthLogin({ show_signup_button: false });
+        expect($('.auth-to-signup')).toHaveLength(0);
+    });
+
+    it('opens forgot password in place, prefilled, and comes back', () => {
+        void UIAuthLogin();
+        $('[name="email_or_username"]').val('someone');
+        $('.forgot-password-link').trigger('click');
+        expect(screen().attr('data-screen')).toBe('recover-password');
+        expect(screen().find('[name="email_or_username"]').val()).toBe('someone');
+        screen().find('.auth-to-login').trigger('click');
+        expect(screen().attr('data-screen')).toBe('login');
+        expect($('.auth-screen')).toHaveLength(1);
+    });
+
+    it('switches to signup and back without stacking screens', () => {
+        void UIAuthLogin();
+        $('.auth-to-signup').trigger('click');
+        expect(screen().attr('data-screen')).toBe('signup');
+        screen().find('.auth-to-login').trigger('click');
+        expect($('.auth-screen')).toHaveLength(1);
+    });
+
+    it('joins a login that is already open', async () => {
+        const first = UIAuthLogin({ reload_on_success: false });
+        const second = UIAuthLogin({ reload_on_success: false });
+        expect($('.auth-dialog')).toHaveLength(1);
+        $('.dashboard-dialog-close').trigger('click');
+        await expect(first).resolves.toBe(false);
+        await expect(second).resolves.toBe(false);
+    });
+
+    it('explains an unreachable self-hosted server', () => {
+        window.app_domain = 'my.host';
+        expect(loginErrorMessage({ status: 0 }).html).toContain('config.json');
+        window.app_domain = 'puter.com';
+        expect(loginErrorMessage({ status: 0 }).text).toBe('Failed to log in: Error 0');
+        expect(loginErrorMessage({ status: 404, responseText: '<html>' }).text).toContain('404');
+    });
+});
+
+describe('OIDC buttons on the login and signup screens', () => {
+    const PROVIDERS_URL = 'https://api.puter.test/auth/oidc/providers';
+    const asPopup = (query) => {
+        window.embedded_in_popup = true;
+        window.gui_action = 'sign-in';
+        window.url_query_params = new URLSearchParams(query);
+    };
+    const askedForProviders = () => fetch.mock.calls.some(([url]) => url === PROVIDERS_URL);
+
+    beforeEach(() => {
+        globalThis.fetch = vi.fn(async () => reply(200, { providers: ['google'] }));
+    });
+
+    it.each(['login', 'signup'])('hides them in a cross-origin-isolated relay popup (%s)', async (kind) => {
+        asPopup('embedded_in_popup=true&msg_id=1&cross_origin_isolated=true&signin_session=s');
+        void UIAuthLogin();
+        if ( kind === 'signup' ) $('.auth-to-signup').trigger('click');
+        await tick();
+        expect(askedForProviders()).toBe(false);
+        expect(screen().find('.oidc-google-btn')).toHaveLength(0);
+    });
+
+    it.each(['login', 'signup'])('keeps them in a regular sign-in popup (%s)', async (kind) => {
+        asPopup('embedded_in_popup=true&msg_id=1');
+        void UIAuthLogin();
+        if ( kind === 'signup' ) $('.auth-to-signup').trigger('click');
+        await vi.waitFor(() => expect(screen().find('.oidc-google-btn')).toHaveLength(1));
+    });
+
+    it('starts the provider login with where to come back to', async () => {
+        void UIAuthLogin({ referrer: 'ref' });
+        await vi.waitFor(() => expect($('.oidc-google-btn')).toHaveLength(1));
+        expect($('.auth-providers').prop('hidden')).toBe(false);
+        const assign = vi.fn();
+        const original = window.location;
+        delete window.location;
+        window.location = { ...original, set href (url) {
+            assign(url);
+        }, get href () {
+            return original.href;
+        } };
+        $('.oidc-google-btn').trigger('click');
+        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', () => {
+    it('passes leading-zero codes to the verifier and keeps the continuation data', async () => {
+        fetch.mockResolvedValue(reply(200, completed));
+        const result = UIAuth2FA('first-factor-challenge');
+        enterOtp('001234');
+        await expect(result).resolves.toEqual(completed);
+        expect(fetch).toHaveBeenCalledWith('https://puter.test/login/otp', expect.objectContaining({
+            body: JSON.stringify({ token: 'first-factor-challenge', code: '001234' }),
+        }));
+    });
+
+    it('takes a whole code autofilled into the first box', async () => {
+        fetch.mockResolvedValue(reply(200, completed));
+        const result = UIAuth2FA('t');
+        $('.login-2fa-code-inputs input').first().val('987654').trigger('input');
+        await expect(result).resolves.toEqual(completed);
+        expect(JSON.parse(fetch.mock.calls[0][1].body).code).toBe('987654');
+    });
+
+    it('keeps a failed challenge open for a recovery-code retry', async () => {
+        fetch.mockResolvedValueOnce(reply(200, { proceed: false })).mockResolvedValueOnce(reply(200, completed));
+        const result = UIAuth2FA('first-factor-challenge');
+        enterOtp('001234');
+        await vi.waitFor(() => expect(screen().find('.dashboard-form-status').text()).toBe('confirm_code_generic_incorrect'));
+        $('.login-2fa-to-recovery').trigger('click');
+        expect(screen().attr('data-screen')).toBe('recovery-code');
+        $('.login-2fa-recovery-input').val(' abcdefg2\n').trigger('input');
+        await expect(result).resolves.toEqual(completed);
+        expect(fetch.mock.calls[1][0]).toBe('https://puter.test/login/recovery-code');
+        expect(JSON.parse(fetch.mock.calls[1][1].body)).toEqual({ token: 'first-factor-challenge', code: 'ABCDEFG2' });
+    });
+
+    it('reports throttling without completing', async () => {
+        fetch.mockResolvedValue(reply(429, {}));
+        const result = UIAuth2FA('t');
+        let settled = false;
+        result.then(() => {
+            settled = true;
+        });
+        enterOtp('001234');
+        await vi.waitFor(() => expect(screen().find('.dashboard-form-status').text()).toBe('confirm_code_generic_too_many_requests'));
+        expect(settled).toBe(false);
+    });
+
+    it('ignores incomplete recovery codes', () => {
+        void UIAuth2FA('t');
+        $('.login-2fa-to-recovery').trigger('click');
+        $('.login-2fa-recovery-input').val('ABC').trigger('input');
+        expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('resolves null when the user goes back from a standalone challenge', async () => {
+        const result = UIAuth2FA('t');
+        $('.auth-dialog-back').trigger('click');
+        await expect(result).resolves.toBeNull();
+        expect(fetch).not.toHaveBeenCalled();
+    });
+});
+
+describe('password login with a second factor', () => {
+    it('completes only after the challenge succeeds', async () => {
+        fetch.mockImplementation(async (url) => (String(url).endsWith('/providers') ? reply(200, { providers: [] }) : reply(200, completed)));
+        const calls = captureAjax();
+        const result = UIAuthLogin({ reload_on_success: false });
+        submitLogin();
+        const submitted = calls[0].success({ proceed: true, next_step: 'otp', otp_jwt_token: 'password-challenge' });
+        await vi.waitFor(() => expect(screen().attr('data-screen')).toBe('two-factor'));
+        expect(window.update_auth_data).not.toHaveBeenCalled();
+        enterOtp('001234');
+        await submitted;
+        await expect(result).resolves.toBe(true);
+        expect(window.update_auth_data).toHaveBeenCalledWith(completed.token, completed.user);
+        expect(JSON.parse(fetch.mock.calls.at(-1)[1].body).token).toBe('password-challenge');
+    });
+
+    it('shows a failure to finish signing in on the login screen, not a stuck code screen', async () => {
+        fetch.mockImplementation(async (url) => (String(url).endsWith('/providers') ? reply(200, { providers: [] }) : reply(200, completed)));
+        window.update_auth_data = vi.fn(async () => {
+            throw new Error('Storage is full');
+        });
+        const calls = captureAjax();
+        void UIAuthLogin({ reload_on_success: false });
+        submitLogin();
+        calls[0].success({ proceed: true, next_step: 'otp', otp_jwt_token: 'c' });
+        await vi.waitFor(() => expect(screen().attr('data-screen')).toBe('two-factor'));
+        enterOtp('001234');
+        await vi.waitFor(() => expect(screen().attr('data-screen')).toBe('login'));
+        expect(screen().find('.dashboard-form-status').text()).toBe('Storage is full');
+        expect($('.login-btn').prop('disabled')).toBe(false);
+        expect(activeAuthFlow().isBusy()).toBe(false);
+    });
+
+    it('stays signed in as before when dismissed while the code is out', async () => {
+        window.auth_token = 'current-token';
+        let answer;
+        fetch.mockImplementation(async (url) => {
+            if ( String(url).endsWith('/providers') ) return reply(200, { providers: [] });
+            if ( String(url).endsWith('/login/otp') ) return new Promise((resolve) => {
+                answer = resolve;
+            });
+            return reply(204, null);
+        });
+        const calls = captureAjax();
+        const result = UIAuthLogin({ reload_on_success: false });
+        submitLogin();
+        const submitted = calls[0].success({ proceed: true, next_step: 'otp', otp_jwt_token: 'c' });
+        await vi.waitFor(() => expect(screen().attr('data-screen')).toBe('two-factor'));
+        enterOtp('001234');
+        await vi.waitFor(() => expect(answer).toBeTypeOf('function'));
+        $('.dashboard-dialog-close').trigger('click');
+        await expect(result).resolves.toBe(false);
+        answer(reply(200, completed));
+        await submitted;
+        await vi.waitFor(() => expect(fetch).toHaveBeenCalledWith('https://puter.test/session/sync-cookie', expect.objectContaining({
+            headers: { Authorization: 'Bearer current-token' },
+        })));
+        expect(window.update_auth_data).not.toHaveBeenCalled();
+    });
+
+    it('returns to the enabled password form when the user goes back', async () => {
+        const calls = captureAjax();
+        const result = UIAuthLogin({ reload_on_success: false });
+        submitLogin();
+        const submitted = calls[0].success({ proceed: true, next_step: 'otp', otp_jwt_token: 'c' });
+        await vi.waitFor(() => expect(screen().attr('data-screen')).toBe('two-factor'));
+        $('.auth-dialog-back').trigger('click');
+        await submitted;
+        expect(screen().attr('data-screen')).toBe('login');
+        expect($('.login-btn').prop('disabled')).toBe(false);
+        expect(window.update_auth_data).not.toHaveBeenCalled();
+        $('.dashboard-dialog-close').trigger('click');
+        await expect(result).resolves.toBe(false);
+    });
+});

src/gui/src/UI/Auth/UIAuthRecoverPassword.js

@@ -0,0 +1,149 @@
+/*
+ * 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 password recovery screen: mails a link to set a new password.
+
+import { formFieldHtml } from '../Dashboard/UIDashboardFormDialog.js';
+import { SVG } from '../Dashboard/UIDashboardDialog.js';
+import openAuthFlow, {
+    authHeadHtml,
+    joinAuthFlow,
+    setAuthStatus,
+    setFormBusy,
+    submitButtonHtml,
+    wireAuthHead,
+} from './authFlow.js';
+import { pushLoginScreen } from './UIAuthLogin.js';
+
+const SENT_ICON = SVG('<circle cx="12" cy="12" r="9"/><path d="M8 12.5l2.5 2.5L16 9.5"/>');
+
+/**
+ * The message of a failed request.
+ *
+ * @param {{ responseText?: string }} err
+ * @returns {string}
+ */
+const errorMessage = (err) => {
+    const text = err?.responseText || '';
+    try {
+        const json = JSON.parse(text);
+        return json.message || json.error || text;
+    } catch {
+        return text || i18n('something_went_wrong', [], false);
+    }
+};
+
+/**
+ * Shows the password recovery screen in `flow`.
+ *
+ * @param {import('./authFlow.js').AuthFlow} flow
+ * @param {{ email_or_username?: string }} [opts] Prefills the field.
+ * @returns {jQuery}
+ */
+export function pushRecoverPasswordScreen (flow, { email_or_username = '' } = {}) {
+    const id = `auth-recover-${window.uuidv4?.() ?? Date.now()}`;
+
+    let h = '<div class="dashboard-dialog-body auth-body">';
+    h += authHeadHtml(flow, i18n('recover_password', [], false));
+    h += '<form class="auth-form pass-recovery-form" novalidate>';
+    h += '<div class="dashboard-form-status" role="status" aria-live="polite"></div>';
+    h += formFieldHtml({
+        name: 'email_or_username',
+        label: i18n('email_or_username'),
+        value: email_or_username,
+        attrs: { autocomplete: 'username', autocapitalize: 'off', autocorrect: 'off', spellcheck: 'false' },
+    }, id);
+    h += submitButtonHtml(i18n('send_password_recovery_email', [], false), 'send-recovery-email');
+    h += '</form>';
+    h += '</div>';
+    h += '<div class="dashboard-dialog-footer auth-footer">';
+    h += `<button type="button" class="auth-link auth-to-login">${i18n('log_in')}</button>`;
+    h += '</div>';
+
+    const $screen = flow.push({ name: 'recover-password', html: h });
+    const $form = $screen.find('.pass-recovery-form');
+    const $input = $form.find('[name="email_or_username"]');
+    wireAuthHead($screen);
+
+    $screen.find('.auth-to-login').on('click', () => {
+        if ( flow.isBusy() ) return;
+        if ( ! flow.goTo('login') ) pushLoginScreen(flow, { email_or_username: String($input.val() ?? '').trim() });
+    });
+
+    $form.on('submit', async (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        if ( flow.isBusy() ) return;
+        const value = String($input.val() ?? '').trim();
+        if ( ! value ) {
+            setAuthStatus($screen, i18n('login_email_username_required', [], false), { field: '[name="email_or_username"]' });
+            return;
+        }
+        setAuthStatus($screen, '');
+        flow.setBusy(true);
+        setFormBusy($form, true);
+
+        let res;
+        try {
+            res = await new Promise((resolve, reject) => {
+                $.ajax({
+                    url: `${window.api_origin}/send-pass-recovery-email`,
+                    type: 'POST',
+                    async: true,
+                    contentType: 'application/json',
+                    data: JSON.stringify(window.is_email(value) ? { email: value } : { username: value }),
+                    statusCode: {
+                        401: (xhr) => window.handle401(xhr),
+                    },
+                    success: resolve,
+                    error: reject,
+                });
+            });
+        } catch ( err ) {
+            flow.setBusy(false);
+            setFormBusy($form, false);
+            setAuthStatus($screen, errorMessage(err), { field: '[name="email_or_username"]' });
+            return;
+        }
+        flow.setBusy(false);
+
+        // The form gives way to what the server said happened; the way back
+        // to the login stays below it.
+        $form.replaceWith('<div class="dashboard-form-done auth-done" role="status">'
+            + `${SENT_ICON}<p>${html_encode(res?.message ?? '')}</p></div>`);
+        $screen.find('.auth-to-login').get(0)?.focus({ preventScroll: true });
+    });
+
+    return $screen;
+}
+
+/**
+ * Asks for the account whose password to reset, on its own.
+ *
+ * @param {{ page?: boolean, dismissable?: boolean }} [options]
+ * @returns {Promise<unknown>} Settles only if the user dismisses the card or
+ *   signs in from it without the page reloading.
+ */
+export default function UIAuthRecoverPassword (options = {}) {
+    const joined = joinAuthFlow();
+    if ( joined ) return joined;
+    const flow = openAuthFlow({ page: options.page, dismissable: options.dismissable });
+    pushRecoverPasswordScreen(flow);
+    return flow.result;
+}

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

@@ -0,0 +1,544 @@
+/*
+ * 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 signup screen: the identity provider buttons, the email form behind
+// them, and the account checks (email, phone, card) a new account may have
+// to pass once created.
+
+import check_password_strength from '../../helpers/checkPasswordStrength.js';
+import { bonusRequirementsKey, checkSignupBonusCode } from '../../helpers/signupBonusCode.js';
+import { bindPasswordReveal, formFieldHtml } from '../Dashboard/UIDashboardFormDialog.js';
+import UIWindowCardVerificationRequired from '../UIWindowCardVerificationRequired.js';
+import UIWindowEmailConfirmationRequired from '../UIWindowEmailConfirmationRequired.js';
+import UIWindowPhoneVerificationRequired from '../UIWindowPhoneVerificationRequired.js';
+import openAuthFlow, {
+    authHeadHtml,
+    joinAuthFlow,
+    navigateAfterSignIn,
+    setAuthStatus,
+    setFormBusy,
+    submitButtonHtml,
+    wireAuthHead,
+} from './authFlow.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
+ * @property {string} [username] Prefills the field.
+ * @property {string} [email] Prefills the field.
+ * @property {string} [authError] Shown when the screen opens.
+ */
+
+/**
+ * What a checked bonus code grants, above the form and the provider buttons.
+ *
+ * @param {jQuery} $screen
+ * @param {{ valid: boolean, display?: { title: string, description: string }, requirements?: object } | null} result
+ */
+const renderBonusNotice = ($screen, result) => {
+    const $notice = $screen.find('.signup-bonus-notice');
+    if ( ! result ) {
+        $notice.prop('hidden', true).empty();
+        return;
+    }
+    if ( ! result.valid ) {
+        $notice.addClass('signup-bonus-notice-invalid')
+            .html(`<p>${i18n('signup_bonus_code_invalid_retry')}</p>`)
+            .prop('hidden', false);
+        return;
+    }
+    const requirements_key = bonusRequirementsKey(result.requirements);
+    let h = `<strong>${html_encode(result.display.title)}</strong>`;
+    h += `<p>${html_encode(result.display.description)}</p>`;
+    if ( requirements_key ) h += `<p class="signup-bonus-requirements">${i18n(requirements_key)}</p>`;
+    $notice.removeClass('signup-bonus-notice-invalid').html(h).prop('hidden', false);
+};
+
+/**
+ * Covers the page with the reason signups are refused here.
+ *
+ * @param {string} message Plain text.
+ */
+const showSignupBlocked = (message) => {
+    const overlay = document.createElement('div');
+    overlay.classList.add('signup-blocked-overlay');
+    overlay.innerHTML = `
+        <div class="signup-blocked-content">
+            <img src="${html_encode(window.icons['logo.svg'] || window.icons['logo-white.svg'] || '')}" style="width:64px;margin-bottom:24px;" alt="" />
+            <p>${html_encode(message || 'Signup Not Allowed')}</p>
+            <p>If you already have an account, try <a href="/action/login">logging in</a>. Otherwise, contact <a href="mailto:support@puter.com">support@puter.com</a> for assistance.</p>
+        </div>
+    `;
+    document.body.appendChild(overlay);
+};
+
+/**
+ * Runs the checks a new account has to pass, in the server's order (see
+ * assertVerifiedAccount): email → phone (SMS) → card, or card → phone →
+ * email when the account clears email last.
+ *
+ * @param {object} user The new account, as the signup answered.
+ * @param {boolean} show_email Ask for the emailed code here.
+ * @param {boolean} reload_on_success
+ * @param {boolean} page Signup was a page, so the checks cover it too
+ *   rather than float over whatever was under it.
+ * @returns {Promise<boolean>} Whether the email was confirmed (true when not asked).
+ */
+const runVerificationGates = async (user, show_email, reload_on_success, page) => {
+    const window_options = page ? { cover_page: true, has_head: false } : {};
+    let email_verified = true;
+    const emailGate = async () => {
+        if ( ! show_email ) return;
+        // No ✕: the signup card it replaced is already gone, so there's
+        // nothing to go back to.
+        email_verified = await UIWindowEmailConfirmationRequired({
+            show_close_button: false,
+            stay_on_top: true,
+            has_head: true,
+            reload_on_success,
+            window_options,
+        });
+    };
+    // A user the SMS path keeps failing may take the card fallback instead;
+    // that resolves 'card' and clears the card gate along with the phone
+    // gate (see UIWindowPhoneVerificationRequired).
+    let card_cleared_by_fallback = false;
+    const phoneGate = async () => {
+        if ( ! user?.requires_phone_verification ) return;
+        let phone_ok = false;
+        do {
+            phone_ok = await UIWindowPhoneVerificationRequired({
+                show_close_button: false,
+                stay_on_top: true,
+                has_head: true,
+                window_options,
+            });
+        } while ( ! phone_ok );
+        card_cleared_by_fallback = phone_ok === 'card';
+    };
+    const cardGate = async () => {
+        if ( ! user?.requires_card_verification || card_cleared_by_fallback ) return;
+        let card_ok = false;
+        do {
+            card_ok = await UIWindowCardVerificationRequired({
+                show_close_button: false,
+                stay_on_top: true,
+                has_head: true,
+                window_options,
+            });
+        } while ( ! card_ok );
+    };
+    if ( user?.email_gate_last ) {
+        await cardGate();
+        await phoneGate();
+        await emailGate();
+    } else {
+        await emailGate();
+        await phoneGate();
+        await cardGate();
+    }
+    return email_verified;
+};
+
+/**
+ * Where to go after a signup that reloads. Signup can interrupt a direct app
+ * landing (the login cover page's "Sign up", the account picker's "Create
+ * Account", the must_login_or_signup fallback); landing on '/' afterwards
+ * would drop the app the URL asked for, so app landings are kept and the
+ * reloaded boot replays them. The query string is left behind, as login
+ * does, so no credentials stay in it.
+ *
+ * @param {string | undefined} redirect_url
+ * @returns {string}
+ */
+export const signupRedirectUrl = (redirect_url) => {
+    if ( redirect_url ) return redirect_url;
+    const on_app_landing = /^\/(?:desktop\/)?app\/[^/]+\/?$/.test(window.location.pathname);
+    return on_app_landing ? window.location.origin + window.location.pathname : '/';
+};
+
+/**
+ * Shows the signup screen in `flow`.
+ *
+ * @param {import('./authFlow.js').AuthFlow} flow
+ * @param {SignupScreenOptions} [options]
+ * @returns {jQuery}
+ */
+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));
+    // Above the provider buttons, not in the form: the form hides behind
+    // them, and an identity provider's refusal shows here too.
+    h += '<div class="dashboard-form-status auth-screen-status" role="status" aria-live="polite"></div>';
+    h += '<div class="signup-bonus-notice" hidden></div>';
+    h += '<div class="auth-providers oidc-providers-wrapper" hidden>';
+    h += '<div class="auth-provider-list"></div>';
+    h += '</div>';
+    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${awaiting_providers ? ' hidden' : ''}>`;
+    h += formFieldHtml({
+        name: 'username',
+        label: i18n('username'),
+        value: options.username ?? '',
+        attrs: { autocomplete: 'username', autocapitalize: 'off', autocorrect: 'off', spellcheck: 'false', 'data-gramm_editor': 'false' },
+    }, id);
+    h += formFieldHtml({
+        name: 'email',
+        type: 'email',
+        label: i18n('email'),
+        value: options.email ?? '',
+        attrs: { autocomplete: 'email', inputmode: 'email', autocapitalize: 'off', autocorrect: 'off', spellcheck: 'false', 'data-gramm_editor': 'false' },
+    }, id);
+    h += formFieldHtml({
+        name: 'password',
+        type: 'password',
+        label: i18n('password'),
+        attrs: { autocomplete: 'new-password' },
+    }, id);
+    h += formFieldHtml({
+        name: 'confirm_password',
+        type: 'password',
+        label: i18n('signup_confirm_password'),
+        attrs: { autocomplete: 'new-password' },
+    }, id);
+    // Bot trap: the server ignores a request that fills it in.
+    h += '<input type="text" name="p102xyzname" class="p102xyzname" value="" tabindex="-1" autocomplete="off" aria-hidden="true">';
+    if ( turnstile_key ) {
+        h += `<div class="auth-turnstile"><div class="cf-turnstile" data-sitekey="${html_encode(turnstile_key)}" data-appearance="interaction-only"></div></div>`;
+    }
+    h += submitButtonHtml(i18n('create_free_account', [], false), 'signup-btn');
+    h += '</form>';
+    h += `<p class="signup-terms">${i18n('tos_fineprint', [], false)}</p>`;
+    h += '</div>';
+    h += '<div class="dashboard-dialog-footer auth-footer">';
+    h += `<button type="button" class="auth-link auth-to-login">${i18n('log_in')}</button>`;
+    h += '</div>';
+
+    const $screen = flow.push({
+        name: 'signup',
+        html: h,
+        autofocus: ! window.disable_signup_autofocus,
+    });
+    const $form = $screen.find('.signup-form');
+    const field = (name) => $form.find(`[name="${name}"]`);
+    const $turnstile = $form.find('.cf-turnstile');
+    let turnstile_widget = null;
+    let offers_providers = false;
+
+    wireAuthHead($screen);
+    bindPasswordReveal($form);
+    if ( options.authError ) setAuthStatus($screen, options.authError);
+
+    $form.on('input', '.dashboard-form-input', function () {
+        $(this).removeAttr('aria-invalid');
+    });
+
+    const showForm = () => {
+        $form.prop('hidden', false);
+        $screen.find('.signup-with-email-wrapper').prop('hidden', true);
+    };
+
+    // Form signups are closed here, so the providers are the only way in.
+    const showOidcOnly = () => {
+        $form.prop('hidden', true);
+        $screen.find('.signup-with-email-wrapper').prop('hidden', true);
+        $screen.find('.oidc-providers-wrapper').prop('hidden', false);
+    };
+
+    // Turnstile renders into the form once its script has loaded.
+    const initTurnstile = () => {
+        if ( ! turnstile_key || ! $turnstile.length || flow.isClosed() ) return;
+        if ( ! window.turnstile ) {
+            setTimeout(initTurnstile, TURNSTILE_POLL_MS);
+            return;
+        }
+        turnstile_widget = window.turnstile.render($turnstile.get(0), {
+            sitekey: turnstile_key,
+            callback: (token) => {
+                $turnstile.attr('data-token', token).addClass('captcha-completed');
+            },
+            'expired-callback': () => {
+                $turnstile.removeAttr('data-token').removeClass('captcha-completed');
+            },
+        });
+    };
+    initTurnstile();
+
+    if ( window.signup_bonus_code ) {
+        (async () => {
+            let fingerprint = null;
+            try {
+                fingerprint = await window.getDeviceFingerprint?.();
+            } catch {
+                // The check works without device signals.
+            }
+            const result = await checkSignupBonusCode(window.signup_bonus_code, {
+                origin: window.gui_origin,
+                fingerprint,
+            });
+            // Unknown (null) keeps the code; signup has the final say.
+            if ( result && ! result.valid ) window.signup_bonus_code = null;
+            renderBonusNotice($screen, result);
+        })();
+    }
+
+    // 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 ) {
+            revealForm();
+            return;
+        }
+        stopAwaitingProviders();
+        if ( flow.isClosed() ) return;
+        offers_providers = true;
+        $screen.find('.oidc-providers-wrapper').prop('hidden', false);
+        if ( offered.signupOidcOnly ) {
+            showOidcOnly();
+            return;
+        }
+        // The email form waits behind its own button, unless the user has
+        // already typed into it.
+        const started = $form.find('.dashboard-form-input').filter(function () {
+            return !! $(this).val();
+        }).length > 0;
+        if ( started ) return;
+        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 || focusWasParked() ) flow.focus();
+    });
+
+    $screen.find('.signup-with-email-btn').on('click', () => {
+        showForm();
+        field('username').get(0)?.focus({ preventScroll: true });
+    });
+
+    $screen.find('.auth-to-login').on('click', () => {
+        if ( flow.isBusy() ) return;
+        if ( ! flow.goTo('login') ) pushLoginScreen(flow);
+    });
+
+    const resetTurnstile = () => {
+        try {
+            if ( window.turnstile && turnstile_widget !== null ) {
+                window.turnstile.reset(turnstile_widget);
+                $turnstile.removeAttr('data-token').removeClass('captcha-completed');
+            }
+        } catch ( e ) {
+            console.log(e);
+        }
+    };
+
+    const fail = (text, field_name) => {
+        setAuthStatus($screen, text, field_name ? { field: `[name="${field_name}"]` } : {});
+    };
+
+    $form.on('submit', async (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        if ( flow.isBusy() ) return;
+
+        const username = String(field('username').val() ?? '').trim();
+        const email = String(field('email').val() ?? '').trim();
+        const password = String(field('password').val() ?? '');
+        const confirm_password = String(field('confirm_password').val() ?? '');
+
+        if ( ! username ) return fail(i18n('username_required', [], false), 'username');
+        if ( ! email ) return fail(i18n('email_required', [], false), 'email');
+        if ( ! window.is_email(email) ) return fail(i18n('email_invalid', [], false), 'email');
+        if ( ! password ) return fail(i18n('password_required', [], false), 'password');
+        if ( ! check_password_strength(password).overallPass ) return fail(i18n('password_strength_error', [], false), 'password');
+        if ( ! confirm_password ) return fail(i18n('confirm_password_required', [], false), 'confirm_password');
+        if ( password !== confirm_password ) return fail(i18n('passwords_do_not_match', [], false), 'confirm_password');
+
+        let turnstile_token = null;
+        if ( window.turnstile && turnstile_key ) {
+            turnstile_token = $turnstile.attr('data-token');
+            if ( ! turnstile_token ) return fail(i18n('captcha_required', [], false));
+        }
+        setAuthStatus($screen, '');
+
+        flow.setBusy(true);
+        setFormBusy($form, true);
+
+        // A device signal for abuse prevention; signup never waits on or
+        // fails because of it.
+        let fingerprint = null;
+        try {
+            fingerprint = await window.getDeviceFingerprint?.();
+        } catch {
+            // Omitted.
+        }
+
+        const request = {
+            username,
+            email,
+            password,
+            referrer: flow.options.referrer ?? window.referrerStr,
+            send_confirmation_code: flow.options.send_confirmation_code,
+            p102xyzname: String($form.find('.p102xyzname').val() ?? ''),
+            'cf-turnstile-response': turnstile_token,
+        };
+        if ( fingerprint ) request.fingerprint = fingerprint;
+        if ( window.signup_bonus_code ) request.bonusCode = window.signup_bonus_code;
+
+        let data;
+        try {
+            data = await new Promise((resolve, reject) => {
+                $.ajax({
+                    url: `${window.gui_origin}/signup`,
+                    type: 'POST',
+                    async: true,
+                    headers: window.custom_headers ?? {},
+                    contentType: 'application/json',
+                    data: JSON.stringify(request),
+                    success: resolve,
+                    error: reject,
+                    timeout: SIGNUP_TIMEOUT_MS,
+                });
+            });
+        } catch ( err ) {
+            setFormBusy($form, false);
+            flow.setBusy(false);
+            resetTurnstile();
+            handleError(err);
+            return;
+        }
+
+        try {
+            await window.update_auth_data(data.token, data.user);
+        } catch ( err ) {
+            setFormBusy($form, false);
+            flow.setBusy(false);
+            fail(err?.message || i18n('signup_error', [], false));
+            return;
+        }
+
+        const reload_on_success = flow.options.reload_on_success;
+        const show_email = ! reload_on_success
+            && !! (flow.options.send_confirmation_code || data.user?.requires_email_confirmation);
+        let email_verified = true;
+        if ( data.user?.requires_phone_verification || data.user?.requires_card_verification || show_email ) {
+            // The checks are windows of their own; the card makes way for them.
+            flow.close();
+            email_verified = await runVerificationGates(data.user, show_email, reload_on_success, flow.page);
+        }
+
+        if ( reload_on_success ) {
+            navigateAfterSignIn(signupRedirectUrl(flow.options.redirect_url));
+            return;
+        }
+        flow.finish(email_verified);
+    });
+
+    const handleError = (err) => {
+        const error_text = err?.responseText || '';
+        let json = null;
+        try {
+            json = JSON.parse(error_text);
+        } catch {
+            // Not JSON.
+        }
+
+        if ( json?.code === 'signup_blocked' ) {
+            showSignupBlocked(json.message);
+            return;
+        }
+        // Form signups closed after this screen loaded. Without provider
+        // buttons (some popups), the server's message below says so instead.
+        if ( json?.code === 'signup_oidc_only' && offers_providers ) {
+            showOidcOnly();
+            return;
+        }
+        if ( json?.code === 'bonus_code_invalid' ) {
+            // The next attempt signs up without it; the offer no longer applies.
+            window.signup_bonus_code = null;
+            renderBonusNotice($screen, null);
+            fail(i18n('signup_bonus_code_invalid_retry', [], false));
+            return;
+        }
+        if ( json?.code === 'response_timeout' || err?.statusText === 'timeout' || error_text.includes('timeout') ) {
+            fail(i18n('server_timeout', [], false));
+            return;
+        }
+        if ( json?.message ) {
+            fail(String(json.message));
+            return;
+        }
+        fail(error_text || i18n('signup_error', [], false));
+    };
+
+    return $screen;
+}
+
+/**
+ * Asks the user to create an account.
+ *
+ * @param {Partial<import('./authFlow.js').AuthFlowOptions> & SignupScreenOptions & {
+ *   page?: boolean, dismissable?: boolean, closeOnBackdrop?: boolean,
+ * }} [options] `page`, `dismissable` and `closeOnBackdrop` as in `openAuthFlow`.
+ * @returns {Promise<boolean>} True once signed up (or false if a requested
+ *   email confirmation wasn't completed), unless the page reloads first;
+ *   false when the user dismisses it. Joins an auth flow that is already
+ *   open instead of opening another.
+ */
+export default function UIAuthSignup (options = {}) {
+    const joined = joinAuthFlow();
+    if ( joined ) return joined;
+    const flow = openAuthFlow({
+        page: options.page,
+        dismissable: options.dismissable,
+        closeOnBackdrop: options.closeOnBackdrop,
+        options,
+    });
+    pushSignupScreen(flow, options);
+    return flow.result;
+}

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

@@ -0,0 +1,378 @@
+// @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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { reply, resetAuthGlobals, screen, tick } from './authTestSetup.js';
+
+const gates = vi.hoisted(() => ({ email: vi.fn(), phone: vi.fn(), card: vi.fn() }));
+vi.mock('../UIWindowEmailConfirmationRequired.js', () => ({ default: gates.email }));
+vi.mock('../UIWindowPhoneVerificationRequired.js', () => ({ default: gates.phone }));
+vi.mock('../UIWindowCardVerificationRequired.js', () => ({ default: gates.card }));
+
+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));
+};
+
+const fillForm = () => {
+    $('[name="username"]').val('someone');
+    $('[name="email"]').val('[email protected]');
+    $('[name="password"]').val('a-Strong-pass-1');
+    $('[name="confirm_password"]').val('a-Strong-pass-1');
+};
+
+const captureAjax = () => {
+    const calls = [];
+    vi.spyOn($, 'ajax').mockImplementation((opts) => {
+        calls.push(opts);
+    });
+    return calls;
+};
+
+beforeEach(() => {
+    resetAuthGlobals();
+    gates.email.mockReset();
+    gates.phone.mockReset();
+    gates.card.mockReset();
+});
+afterEach(() => {
+    activeAuthFlow()?.finish(false);
+    vi.restoreAllMocks();
+});
+
+describe('signup when only OIDC signups are open', () => {
+    const open = async () => {
+        void UIAuthSignup({ reload_on_success: false });
+        await vi.waitFor(() => expect($('.oidc-google-btn')).toHaveLength(1));
+    };
+
+    it('offers the email form behind a button normally', async () => {
+        providers({ providers: ['google'], signupOidcOnly: false });
+        await open();
+        expect($('.signup-with-email-wrapper').prop('hidden')).toBe(false);
+        expect($('.signup-form').prop('hidden')).toBe(true);
+        $('.signup-with-email-btn').trigger('click');
+        expect($('.signup-form').prop('hidden')).toBe(false);
+    });
+
+    it('drops the email form', async () => {
+        providers({ providers: ['google'], signupOidcOnly: true });
+        await open();
+        expect($('.signup-form').prop('hidden')).toBe(true);
+        expect($('.signup-with-email-wrapper').prop('hidden')).toBe(true);
+    });
+
+    it('switches to the providers when a form signup is refused for it', async () => {
+        providers({ providers: ['google'], signupOidcOnly: false });
+        await open();
+        const calls = captureAjax();
+        $('.signup-with-email-btn').trigger('click');
+        fillForm();
+        $('.signup-form').trigger('submit');
+        await vi.waitFor(() => expect(calls).toHaveLength(1));
+        calls[0].error({ responseText: JSON.stringify({ code: 'signup_oidc_only', message: 'closed' }) });
+        await tick();
+        expect($('.signup-form').prop('hidden')).toBe(true);
+    });
+
+    it.each([false, true])('keeps an error it opened with in view (OIDC only: %s)', async (signupOidcOnly) => {
+        providers({ providers: ['google'], signupOidcOnly });
+        void UIAuthSignup({ authError: 'Your account could not be created.' });
+        await vi.waitFor(() => expect($('.oidc-google-btn')).toHaveLength(1));
+        expect($('.signup-form').prop('hidden')).toBe(true);
+        const $status = screen().find('.dashboard-form-status');
+        expect($status.text()).toBe('Your account could not be created.');
+        expect($status.closest('[hidden]')).toHaveLength(0);
+    });
+
+    it('leaves a form the user already typed into', async () => {
+        let answer;
+        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));
+        expect($('.signup-form').prop('hidden')).toBe(false);
+    });
+});
+
+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'],
+        [{ username: 'a' }, 'email_required', 'email'],
+        [{ username: 'a', email: 'nope' }, 'email_invalid', 'email'],
+        [{ username: 'a', email: '[email protected]' }, 'password_required', 'password'],
+        [{ username: 'a', email: '[email protected]', password: 'weak' }, 'password_strength_error', 'password'],
+        [{ username: 'a', email: '[email protected]', password: 'a-Strong-pass-1' }, 'confirm_password_required', 'confirm_password'],
+        [{ username: 'a', email: '[email protected]', password: 'a-Strong-pass-1', confirm_password: 'other' }, 'passwords_do_not_match', 'confirm_password'],
+    ])('checks %j before sending', (values, message, field) => {
+        const calls = captureAjax();
+        void UIAuthSignup();
+        for ( const [name, value] of Object.entries(values) ) $(`[name="${name}"]`).val(value);
+        $('.signup-form').trigger('submit');
+        expect(screen().find('.dashboard-form-status').text()).toBe(message);
+        expect($(`[name="${field}"]`).attr('aria-invalid')).toBe('true');
+        expect(calls).toHaveLength(0);
+    });
+
+    it('asks for the CAPTCHA when Turnstile is on', async () => {
+        window.gui_params = { turnstileSiteKey: 'key' };
+        window.turnstile = { render: vi.fn(() => 'widget'), reset: vi.fn() };
+        const calls = captureAjax();
+        void UIAuthSignup();
+        expect(window.turnstile.render).toHaveBeenCalledWith($('.cf-turnstile').get(0), expect.objectContaining({ sitekey: 'key' }));
+        fillForm();
+        $('.signup-form').trigger('submit');
+        expect(screen().find('.dashboard-form-status').text()).toBe('captcha_required');
+        window.turnstile.render.mock.calls[0][1].callback('tok');
+        $('.signup-form').trigger('submit');
+        await vi.waitFor(() => expect(calls).toHaveLength(1));
+        expect(JSON.parse(calls[0].data)['cf-turnstile-response']).toBe('tok');
+        calls[0].error({ responseText: '{"message":"no"}' });
+        await tick();
+        expect(window.turnstile.reset).toHaveBeenCalledWith('widget');
+    });
+
+    it('sends the honeypot, referrer, bonus code and confirmation setting', async () => {
+        window.signup_bonus_code = 'BONUS';
+        globalThis.fetch = vi.fn(async () => reply(200, { valid: true, display: { title: 'T', description: 'D' } }));
+        const calls = captureAjax();
+        void UIAuthSignup({ referrer: 'app-x', send_confirmation_code: true });
+        fillForm();
+        $('.p102xyzname').val('bot');
+        $('.signup-form').trigger('submit');
+        await vi.waitFor(() => expect(calls).toHaveLength(1));
+        expect(JSON.parse(calls[0].data)).toMatchObject({
+            username: 'someone',
+            email: '[email protected]',
+            referrer: 'app-x',
+            send_confirmation_code: true,
+            p102xyzname: 'bot',
+            bonusCode: 'BONUS',
+        });
+        expect(calls[0].timeout).toBe(30000);
+    });
+
+    it('drops a refused bonus code and says so', async () => {
+        window.signup_bonus_code = 'BAD';
+        const calls = captureAjax();
+        void UIAuthSignup();
+        fillForm();
+        $('.signup-form').trigger('submit');
+        await vi.waitFor(() => expect(calls).toHaveLength(1));
+        calls[0].error({ responseText: JSON.stringify({ code: 'bonus_code_invalid' }) });
+        await tick();
+        expect(window.signup_bonus_code).toBeNull();
+        expect(screen().find('.dashboard-form-status').text()).toBe('signup_bonus_code_invalid_retry');
+        expect($('.signup-btn').prop('disabled')).toBe(false);
+    });
+
+    it('puts focus back in the form after the server refuses, so Enter can retry', async () => {
+        const calls = captureAjax();
+        void UIAuthSignup();
+        fillForm();
+        $('[name="confirm_password"]').get(0).focus();
+        $('.signup-form').trigger('submit');
+        await vi.waitFor(() => expect(calls).toHaveLength(1));
+        calls[0].error({ responseText: '{"message":"This username is not available."}' });
+        await tick();
+        expect(screen().find('.dashboard-form-status').text()).toBe('This username is not available.');
+        expect(document.activeElement).toBe($('[name="confirm_password"]').get(0));
+    });
+
+    it('covers the page when signups are blocked here', async () => {
+        const calls = captureAjax();
+        void UIAuthSignup();
+        fillForm();
+        $('.signup-form').trigger('submit');
+        await vi.waitFor(() => expect(calls).toHaveLength(1));
+        calls[0].error({ responseText: JSON.stringify({ code: 'signup_blocked', message: '<i>No</i>' }) });
+        await tick();
+        expect($('.signup-blocked-overlay').text()).toContain('<i>No</i>');
+        expect($('.signup-blocked-overlay i')).toHaveLength(0);
+    });
+
+    it('runs the account checks after the card makes way, then settles', async () => {
+        gates.email.mockResolvedValue(true);
+        gates.phone.mockResolvedValueOnce(false).mockResolvedValueOnce('card');
+        const calls = captureAjax();
+        const result = UIAuthSignup({ reload_on_success: false, send_confirmation_code: true });
+        fillForm();
+        $('.signup-form').trigger('submit');
+        await vi.waitFor(() => expect(calls).toHaveLength(1));
+        calls[0].success({ token: 't', user: { requires_phone_verification: true, requires_card_verification: true } });
+        await expect(result).resolves.toBe(true);
+        expect($('.auth-dialog-overlay.dashboard-dialog-show')).toHaveLength(0);
+        // email → phone (retried until passed) → card, which the phone's card fallback cleared.
+        expect(gates.email).toHaveBeenCalledOnce();
+        // Closing a check without an answer would strand the caller.
+        for ( const gate of [gates.email, gates.phone] ) {
+            expect(gate.mock.calls[0][0].show_close_button).toBe(false);
+        }
+        expect(gates.phone).toHaveBeenCalledTimes(2);
+        expect(gates.card).not.toHaveBeenCalled();
+    });
+
+    it.each([
+        [true, { cover_page: true, has_head: false }],
+        [false, {}],
+    ])('covers the page with the account checks when signup was a page (%s)', async (page, window_options) => {
+        gates.email.mockResolvedValue(true);
+        gates.phone.mockResolvedValue(true);
+        gates.card.mockResolvedValue(true);
+        const calls = captureAjax();
+        const result = UIAuthSignup({ page, reload_on_success: false, send_confirmation_code: true });
+        fillForm();
+        $('.signup-form').trigger('submit');
+        await vi.waitFor(() => expect(calls).toHaveLength(1));
+        calls[0].success({ token: 't', user: { requires_phone_verification: true, requires_card_verification: true } });
+        await result;
+        for ( const gate of [gates.email, gates.phone, gates.card] ) {
+            expect(gate.mock.calls[0][0].window_options).toEqual(window_options);
+        }
+    });
+
+    it('keeps an app landing after a signup that reloads', () => {
+        expect(signupRedirectUrl('/x')).toBe('/x');
+        expect(signupRedirectUrl(undefined)).toBe('/');
+    });
+});
+
+describe('account picker', () => {
+    beforeEach(() => {
+        window.logged_in_users = [
+            { uuid: 'u1', username: 'alice', email: '[email protected]', auth_token: 'ta', profile: { picture: 'data:image/png;base64,AA' } },
+            { uuid: 'u2', username: '<b>bob</b>', auth_token: 'tb' },
+        ];
+    });
+
+    it('lists the accounts, encoded, and can not be dismissed', () => {
+        void UIAuthAccountPicker({ reload_on_success: false, page: true });
+        expect($('.auth-account')).toHaveLength(2);
+        expect($('.auth-account b')).toHaveLength(0);
+        expect($('.auth-account-avatar img').attr('src')).toBe('data:image/png;base64,AA');
+        expect($('.dashboard-dialog-close')).toHaveLength(0);
+    });
+
+    it('signs in as the picked account', async () => {
+        const result = UIAuthAccountPicker({ reload_on_success: false });
+        $('.auth-account[data-uuid="u2"]').trigger('click');
+        await expect(result).resolves.toBe(true);
+        expect(window.update_auth_data).toHaveBeenCalledWith('tb', window.logged_in_users[1]);
+    });
+
+    it('logs in to another account with a way back to the list', async () => {
+        captureAjax();
+        void UIAuthAccountPicker({ reload_on_success: false });
+        $('.auth-to-login').trigger('click');
+        expect(screen().attr('data-screen')).toBe('login');
+        $('.auth-dialog-back').trigger('click');
+        expect(screen().attr('data-screen')).toBe('accounts');
+        $('.auth-to-signup').trigger('click');
+        expect(screen().attr('data-screen')).toBe('signup');
+    });
+});
+
+describe('password recovery', () => {
+    it('asks for the account, then shows what the server said', async () => {
+        const calls = captureAjax();
+        void UIAuthRecoverPassword({ page: true });
+        $('.pass-recovery-form').trigger('submit');
+        expect(screen().find('.dashboard-form-status').text()).toBe('login_email_username_required');
+        $('[name="email_or_username"]').val('[email protected]');
+        $('.pass-recovery-form').trigger('submit');
+        expect(calls[0].url).toBe('https://api.puter.test/send-pass-recovery-email');
+        expect(JSON.parse(calls[0].data)).toEqual({ email: '[email protected]' });
+        calls[0].success({ message: 'Sent <b>it</b>' });
+        await tick();
+        expect($('.auth-done').text()).toBe('Sent <b>it</b>');
+        expect($('.pass-recovery-form')).toHaveLength(0);
+        // The page has a way on to the login.
+        $('.auth-to-login').trigger('click');
+        expect(screen().attr('data-screen')).toBe('login');
+    });
+
+    it('shows a refusal on the form', async () => {
+        const calls = captureAjax();
+        void UIAuthRecoverPassword();
+        $('[name="email_or_username"]').val('someone');
+        $('.pass-recovery-form').trigger('submit');
+        expect(JSON.parse(calls[0].data)).toEqual({ username: 'someone' });
+        calls[0].error({ responseText: JSON.stringify({ message: 'Too many' }) });
+        await tick();
+        expect(screen().find('.dashboard-form-status').text()).toBe('Too many');
+        expect($('[name="email_or_username"]').prop('disabled')).toBe(false);
+    });
+});

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

@@ -0,0 +1,500 @@
+/*
+ * 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 card that sign-in, sign-up, the account picker, password recovery and
+// the second factor share: a dashboard dialog whose screens replace each
+// other in place, with a Back button, instead of opening windows over each
+// other. One flow is open at a time.
+//
+// Two presentations. A dialog dims what is under it, and docks as a bottom
+// sheet on phones. A page (a cover page, or any sign-in popup) has nothing
+// to go back to: an opaque page under a centered card, and the whole screen
+// on phones and in popups.
+
+import { isAttestedOrigin } from '../../helpers/attestedOrigin.js';
+import { authLogoHeader, wireAuthLogoHeader } from '../../helpers/authLogoHeader.js';
+import { get_auth_redirect_url } from '../../helpers/authRedirect.js';
+import { syncSessionCookie } from '../../util/sessionAuth.js';
+import { isTouchPrimaryDevice } from '../Dashboard/ContextMenu/ContextMenu.js';
+import mountDashboardOverlay from '../Dashboard/dashboardOverlay.js';
+import { ICONS, SVG } from '../Dashboard/UIDashboardDialog.js';
+
+const BACK_ICON = SVG('<path d="M15 18l-6-6 6-6"/>');
+
+/** @type {AuthFlow | null} */
+let active_flow = null;
+
+/**
+ * @typedef {object} AuthScreen
+ * @property {string} name Matched by `goTo`.
+ * @property {string} html The screen's markup. A `.auth-title` names the
+ *   dialog while the screen shows.
+ * @property {boolean} [autofocus] Focus the first field on show; default true.
+ * @property {() => void} [onBack] Makes Back available on the first screen,
+ *   where it runs this instead of returning to an earlier screen.
+ * @property {() => void} [onLeave] Runs when the screen is taken off the
+ *   stack: by Back, `goTo`, or the flow closing.
+ */
+
+/**
+ * What every screen of a flow does once the user is signed in. Set from the
+ * options of the call that opened the flow; screens it leads to share them.
+ *
+ * @typedef {object} AuthFlowOptions
+ * @property {boolean} reload_on_success Navigate to `redirect_url` on success,
+ *   rather than settle the flow with `true`.
+ * @property {string} [redirect_url] Defaults to the page the flow started on.
+ * @property {string} [referrer] Sent with a signup, for user acquisition.
+ * @property {boolean} send_confirmation_code Ask a new account to confirm its
+ *   email with a code.
+ * @property {boolean} show_signup_button Offer to create an account from
+ *   the login screen.
+ */
+
+/**
+ * @param {Partial<AuthFlowOptions>} [options]
+ * @returns {AuthFlowOptions}
+ */
+export const authFlowOptions = (options = {}) => ({
+    reload_on_success: options.reload_on_success ?? true,
+    // Stay on the page the flow started from (e.g. an /app/<name> landing);
+    // standalone auth pages go to the root dashboard.
+    redirect_url: options.redirect_url === undefined ? get_auth_redirect_url() : options.redirect_url,
+    referrer: options.referrer,
+    send_confirmation_code: options.send_confirmation_code ?? false,
+    show_signup_button: options.show_signup_button ?? true,
+});
+
+/**
+ * Leaves for `url` once signed in. A URL that differs from this page's only
+ * in its hash (a dashboard `#tab`) would just scroll, never reload, so the
+ * page reloads at it instead.
+ *
+ * @param {string} url
+ */
+export const navigateAfterSignIn = (url) => {
+    window.onbeforeunload = null;
+    const target = new URL(url, window.location.href);
+    const here = new URL(window.location.href);
+    target.hash = '';
+    here.hash = '';
+    if ( target.href !== here.href ) {
+        window.location.replace(url);
+        return;
+    }
+    history.replaceState(history.state, '', new URL(url, window.location.href).href);
+    window.location.reload();
+};
+
+/**
+ * Hands the session cookie back to the account this page is signed in as.
+ * A sign-in the server completes after the user dismissed the card has
+ * already moved the cookie to the other account, and the endpoints that
+ * read the cookie (password, 2FA) would act on that one.
+ */
+export const keepCurrentSession = () => {
+    void syncSessionCookie({ origin: window.gui_origin || window.location.origin, authToken: window.auth_token });
+};
+
+/**
+ * @typedef {object} AuthFlow
+ * @property {AuthFlowOptions} options
+ * @property {jQuery} $overlay
+ * @property {jQuery} $dialog
+ * @property {boolean} page Whether it shows as a page rather than a dialog.
+ * @property {boolean} dismissable
+ * @property {Promise<unknown>} result Settles once, with `settle`/`finish`'s
+ *   value, or `false` when the user dismisses the flow.
+ * @property {(screen: AuthScreen) => jQuery} push Shows a screen over the
+ *   current one; returns its element.
+ * @property {() => void} back
+ * @property {(name: string) => boolean} goTo Returns to an earlier screen by
+ *   name, if there is one.
+ * @property {(busy: boolean) => void} setBusy While busy, only ✕ dismisses
+ *   the flow and Back is disabled. Ending it returns focus to where it was,
+ *   once that control is enabled again.
+ * @property {() => boolean} isBusy
+ * @property {() => void} close Takes the card down without settling.
+ * @property {(value: unknown) => void} settle
+ * @property {(value: unknown) => void} finish `close`, then `settle`.
+ * @property {() => boolean} isClosed
+ * @property {() => void} focus Brings focus back to the current screen.
+ */
+
+/** The open flow, if any. */
+export const activeAuthFlow = () => (active_flow && ! active_flow.isClosed() ? active_flow : null);
+
+/**
+ * The first enabled, visible field of a screen.
+ *
+ * @param {jQuery} $screen
+ * @returns {HTMLElement | undefined}
+ */
+const firstField = ($screen) => $screen
+    .find('input:not([type=hidden]):not(.p102xyzname), select, textarea')
+    .filter(':visible:not(:disabled):not([readonly])')
+    .get(0);
+
+/**
+ * @param {object} opts
+ * @param {boolean} [opts.page] Show as a page; see the top of this file.
+ *   Sign-in popups always are.
+ * @param {boolean} [opts.dismissable] Offer ✕ and Escape; defaults to
+ *   `!page`.
+ * @param {boolean} [opts.closeOnBackdrop] A press on the dimmed area
+ *   dismisses it too. Off by default: a stray click must not lose typed
+ *   credentials.
+ * @param {Partial<AuthFlowOptions>} [opts.options]
+ * @returns {AuthFlow}
+ */
+export default function openAuthFlow ({ page = false, dismissable = ! page, closeOnBackdrop = false, options } = {}) {
+    // A newer flow wins; the old one's caller hears it was dismissed.
+    activeAuthFlow()?.finish(false);
+
+    const id = `auth-${window.uuidv4?.() ?? Date.now()}`;
+    const as_page = !! page || !! window.embedded_in_popup;
+
+    let h = '<div class="dashboard-dialog auth-dialog" role="dialog" aria-modal="true" tabindex="-1">';
+    h += '<div class="auth-dialog-bar">';
+    h += `<button type="button" class="auth-dialog-back" hidden aria-label="${i18n('back')}" title="${i18n('back')}">${BACK_ICON}</button>`;
+    if ( dismissable ) {
+        h += `<button type="button" class="dashboard-dialog-close" aria-label="${i18n('close')}" title="${i18n('close')}">${ICONS.close}</button>`;
+    }
+    h += '</div>';
+    h += '</div>';
+
+    let resolve;
+    const result = new Promise((r) => {
+        resolve = r;
+    });
+    let busy = false;
+    /** @type {HTMLElement | null} */
+    let el_busy_return = null;
+    let settled = false;
+    let torn_down = false;
+    /** @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?.();
+    };
+
+    const { $overlay, $dialog, close: closeOverlay, isClosed } = mountDashboardOverlay({
+        html: h,
+        // A page already fills the screen. Resizing it under iOS's own pan to
+        // the focused field makes the form jump up and down as the keyboard opens.
+        fitKeyboard: ! as_page,
+        canDismiss: (via) => dismissable
+            && (via === 'close' || (! busy && (via !== 'backdrop' || closeOnBackdrop))),
+        onDismiss: () => {
+            teardown();
+            flow.settle(false);
+        },
+    });
+    $overlay.addClass('auth-dialog-overlay');
+    if ( as_page ) $overlay.addClass('auth-dialog-page');
+
+    const $back = $dialog.find('.auth-dialog-back');
+    const top = () => stack[stack.length - 1];
+
+    const focusScreen = (screen) => {
+        if ( ! screen || isClosed() ) return;
+        // A keyboard popping up mid-animation on a phone hides half the
+        // card; there the user taps the field they want.
+        const el_field = screen.autofocus !== false && ! isTouchPrimaryDevice()
+            ? firstField(screen.$el) ?? screen.$el.find('.auth-provider-btn').filter(':visible').get(0)
+            : undefined;
+        (el_field ?? $dialog.get(0))?.focus({ preventScroll: true });
+    };
+
+    // Back and ✕ float over the top of the screen. Once it scrolls, the bar
+    // under them turns opaque, so what passes beneath neither shows through
+    // nor takes their taps.
+    const syncScrolled = () => {
+        const el_body = top()?.$el.find('.auth-body').get(0);
+        $dialog.toggleClass('auth-dialog-scrolled', !! el_body && el_body.scrollTop > 0);
+    };
+    $dialog.get(0).addEventListener('scroll', syncScrolled, { capture: true, passive: true });
+
+    const refresh = () => {
+        const screen = top();
+        syncScrolled();
+        $back.prop('hidden', ! (stack.length > 1 || screen?.onBack));
+        $back.prop('disabled', busy);
+        const el_title = screen?.$el.find('.auth-title').get(0);
+        $dialog.attr('aria-labelledby', el_title?.id || null);
+    };
+
+    /** Takes the top screen off the stack and shows the one under it. */
+    const pop = () => {
+        const screen = stack.pop();
+        screen.$el.remove();
+        screen.onLeave?.();
+        const under = top();
+        under.$el.prop('hidden', false);
+        return under;
+    };
+
+    /** @type {AuthFlow} */
+    const flow = {
+        options: authFlowOptions(options),
+        $overlay,
+        $dialog,
+        page: as_page,
+        dismissable,
+        result,
+        push (screen) {
+            const under = top();
+            if ( under ) {
+                under.el_return = $dialog.get(0).contains(document.activeElement) ? document.activeElement : null;
+                under.$el.prop('hidden', true);
+            }
+            const $el = $(`<section class="auth-screen" data-screen="${html_encode(screen.name)}">${screen.html}</section>`);
+            $el.find('.auth-title').first().attr('id', `${id}-title-${stack.length}`);
+            $dialog.append($el);
+            const record = { ...screen, $el };
+            stack.push(record);
+            refresh();
+            focusScreen(record);
+            return $el;
+        },
+        back () {
+            if ( busy || isClosed() ) return;
+            if ( stack.length > 1 ) {
+                const under = pop();
+                refresh();
+                const el_return = under.el_return;
+                if ( el_return && under.$el.get(0).contains(el_return) && ! el_return.disabled ) {
+                    el_return.focus({ preventScroll: true });
+                } else {
+                    focusScreen(under);
+                }
+                return;
+            }
+            top()?.onBack?.();
+        },
+        goTo (name) {
+            const index = stack.findIndex((screen) => screen.name === name);
+            if ( index === -1 ) return false;
+            while ( stack.length > index + 1 ) pop();
+            refresh();
+            focusScreen(top());
+            return true;
+        },
+        setBusy (value) {
+            const was_busy = busy;
+            busy = !! value;
+            // Busy screens lock their fields, and a disabled field drops focus
+            // to the page, where the desktop's shortcuts would take the keys.
+            const el_dialog = $dialog.get(0);
+            const el_active = document.activeElement;
+            if ( busy && ! was_busy ) {
+                el_busy_return = el_active !== el_dialog && el_dialog.contains(el_active) ? el_active : null;
+            }
+            if ( busy && el_dialog.contains(el_active) ) el_dialog.focus({ preventScroll: true });
+            $dialog.toggleClass('auth-dialog-busy', busy).attr('aria-busy', busy ? 'true' : null);
+            refresh();
+            if ( busy || ! was_busy ) return;
+            // A failed request hands the keys back to where the user was, so
+            // Enter can retry. A screen that already moved focus keeps it.
+            const el_return = el_busy_return;
+            el_busy_return = null;
+            if ( el_return && document.activeElement === el_dialog && el_dialog.contains(el_return)
+                && ! el_return.disabled && ! el_return.closest('[hidden]') ) {
+                el_return.focus({ preventScroll: true });
+            }
+        },
+        isBusy: () => busy,
+        close () {
+            if ( isClosed() ) return;
+            teardown();
+            closeOverlay();
+        },
+        settle (value) {
+            if ( settled ) return;
+            settled = true;
+            resolve(value);
+        },
+        finish (value) {
+            flow.close();
+            flow.settle(value);
+        },
+        isClosed,
+        focus: () => focusScreen(top()),
+    };
+
+    $back.on('click', () => flow.back());
+
+    // Keys typed here are the card's. The desktop's shortcuts listen on the
+    // document (Enter opens the selected item, Delete trashes it, letters
+    // search the desktop), so they must not reach it. Escape is handled here
+    // for the same reason.
+    $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 ( 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.
+    $overlay.on('mousedown', function (e) {
+        if ( e.target === this ) e.preventDefault();
+    });
+
+    if ( window.embedded_in_frame ) window.addEventListener('focus', onFrameFocus);
+
+    active_flow = flow;
+    return flow;
+}
+
+/**
+ * Joins the flow that is already open, if any: a second sign-in prompt
+ * (an app asking while the user is mid-login) waits on the first rather than
+ * stacking another card over it.
+ *
+ * @returns {Promise<unknown> | null}
+ */
+export const joinAuthFlow = () => {
+    const open = activeAuthFlow();
+    if ( ! open ) return null;
+    // Bring focus back to the card, without taking it from a field the
+    // user is typing in there.
+    if ( ! open.$dialog.get(0).contains(document.activeElement) ) open.focus();
+    return open.result;
+};
+
+/**
+ * The top of a screen: the Puter logo (beside the opener's, in a sign-in
+ * popup), the screen's title, and, in a popup, which site sent the user.
+ *
+ * @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, { openerNotice = true } = {}) => {
+    const opener = window.embedded_in_popup && isAttestedOrigin(window.openerOrigin) ? window.openerOrigin : '';
+    let h = '<div class="auth-head">';
+    h += authLogoHeader({
+        logoSrc: window.icons['logo-white.svg'],
+        logoHref: logoHref(flow),
+        openerOrigin: opener,
+        openerFallbackSrc: window.icons['website.svg'],
+    });
+    h += `<h1 class="auth-title">${html_encode(title)}</h1>`;
+    if ( opener && openerNotice ) {
+        h += `<p class="auth-opener-notice">${i18n('popup_opener_uses_puter', [new URL(opener).hostname])}</p>`;
+    }
+    h += '</div>';
+    return h;
+};
+
+/**
+ * On a cover page, the logo is a way out: desktop users stay on the desktop,
+ * everyone else goes to the root dashboard.
+ *
+ * @param {AuthFlow} flow
+ * @returns {string} Empty where the logo leads nowhere.
+ */
+const logoHref = (flow) => {
+    if ( ! flow.page || window.embedded_in_popup ) return '';
+    return window.location.pathname === '/desktop' ? '/desktop' : '/';
+};
+
+/**
+ * Wires a screen's head once it is on the page.
+ *
+ * @param {jQuery} $screen
+ */
+export const wireAuthHead = ($screen) => {
+    wireAuthLogoHeader($screen.get(0));
+};
+
+/**
+ * Sets a screen's status line. Plain text unless `html` is given, which the
+ * caller has already encoded.
+ *
+ * @param {jQuery} $screen
+ * @param {string} text Empty clears it.
+ * @param {{ kind?: 'error'|'info'|'success', html?: string, field?: string }} [opts]
+ *   `field` is a selector for the control to mark invalid and focus.
+ */
+export const setAuthStatus = ($screen, text, { kind = 'error', html, field } = {}) => {
+    const $status = $screen.find('.dashboard-form-status').first();
+    if ( html !== undefined ) $status.html(html);
+    else $status.text(text ?? '');
+    const shown = !! (text || html);
+    $status
+        .toggleClass('dashboard-form-status-error', shown && kind === 'error')
+        .toggleClass('dashboard-form-status-info', shown && kind === 'info')
+        .toggleClass('auth-status-success', shown && kind === 'success');
+    $screen.find('[aria-invalid]').removeAttr('aria-invalid');
+    if ( ! shown ) return;
+    const el_status = $status.get(0);
+    el_status?.scrollIntoView?.({ block: 'nearest' });
+    if ( field ) {
+        const el_field = $screen.find(field).attr('aria-invalid', 'true').get(0);
+        if ( el_field && ! el_field.disabled ) el_field.focus({ preventScroll: true });
+    }
+};
+
+/**
+ * Shows a form's submit button as working, and locks the form's fields,
+ * while `busy`.
+ *
+ * @param {jQuery} $form
+ * @param {boolean} busy
+ */
+export const setFormBusy = ($form, busy) => {
+    $form.find('input, select, textarea, button').prop('disabled', busy);
+    $form.find('.auth-submit')
+        .toggleClass('dashboard-form-busy', busy)
+        .attr('aria-busy', busy ? 'true' : null);
+};
+
+/**
+ * The submit button of an auth form: full width, with a spinner while busy.
+ *
+ * @param {string} label Plain text.
+ * @param {string} [extraClass]
+ * @returns {string}
+ */
+export const submitButtonHtml = (label, extraClass = '') =>
+    `<button type="submit" class="dashboard-dialog-btn dashboard-dialog-btn-primary auth-submit ${extraClass}">`
+    + '<span class="dashboard-form-spinner" aria-hidden="true"></span>'
+    + `<span class="dashboard-form-submit-label">${html_encode(label)}</span>`
+    + '</button>';

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

@@ -0,0 +1,365 @@
+// @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 { resetAuthGlobals, tick } from './authTestSetup.js';
+
+const { default: openAuthFlow, activeAuthFlow, authFlowOptions, authHeadHtml, joinAuthFlow, navigateAfterSignIn } = await import('./authFlow.js');
+
+const key = (target, k) => target.dispatchEvent(new KeyboardEvent('keydown', { key: k, bubbles: true }));
+const backdropClick = () => {
+    const el = $('.auth-dialog-overlay').last().get(0);
+    el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, detail: 1 }));
+    el.dispatchEvent(new MouseEvent('click', { bubbles: true, detail: 1 }));
+};
+
+beforeEach(() => {
+    resetAuthGlobals();
+    activeAuthFlow()?.finish(false);
+});
+
+describe('openAuthFlow', () => {
+    it('mounts one card over everything, not a window', async () => {
+        const flow = openAuthFlow();
+        flow.push({ name: 'a', html: '<h1 class="auth-title">A</h1>' });
+        await tick();
+        expect($('.auth-dialog-overlay.dashboard-dialog-overlay')).toHaveLength(1);
+        expect($('.window')).toHaveLength(0);
+        expect($('.auth-dialog').attr('aria-labelledby')).toBe($('.auth-title').attr('id'));
+    });
+
+    it('shows as a page, without ✕, for cover pages and every popup', () => {
+        openAuthFlow({ page: true }).finish(false);
+        window.embedded_in_popup = true;
+        const flow = openAuthFlow();
+        expect(flow.page).toBe(true);
+        expect($('.auth-dialog-overlay').last().hasClass('auth-dialog-page')).toBe(true);
+    });
+
+    it('lets ✕ and Escape dismiss a dialog, settling false', async () => {
+        const flow = openAuthFlow();
+        flow.push({ name: 'a', html: '<input>' });
+        key($('.auth-dialog input').get(0), 'Escape');
+        await expect(flow.result).resolves.toBe(false);
+        expect(activeAuthFlow()).toBeNull();
+
+        const second = openAuthFlow();
+        second.push({ name: 'a', html: '' });
+        $('.dashboard-dialog-close').last().trigger('click');
+        await expect(second.result).resolves.toBe(false);
+    });
+
+    it('keeps a page up: no ✕, Escape and backdrop do nothing', async () => {
+        const flow = openAuthFlow({ page: true });
+        flow.push({ name: 'a', html: '<input>' });
+        await tick();
+        expect($('.dashboard-dialog-close')).toHaveLength(0);
+        key($('.auth-dialog input').get(0), 'Escape');
+        backdropClick();
+        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: '' });
+        await tick();
+        backdropClick();
+        expect(kept.isClosed()).toBe(false);
+        kept.finish(false);
+
+        const closing = openAuthFlow({ closeOnBackdrop: true });
+        closing.push({ name: 'a', html: '' });
+        await tick();
+        backdropClick();
+        await expect(closing.result).resolves.toBe(false);
+    });
+
+    it('holds Escape while busy; only ✕ dismisses then', async () => {
+        const flow = openAuthFlow();
+        flow.push({ name: 'a', html: '<input>' });
+        flow.setBusy(true);
+        key($('.auth-dialog input').get(0), 'Escape');
+        expect(flow.isClosed()).toBe(false);
+        $('.dashboard-dialog-close').trigger('click');
+        await expect(flow.result).resolves.toBe(false);
+    });
+
+    it('keeps typed keys from reaching the desktop shortcuts on the document', () => {
+        const flow = openAuthFlow({ page: true });
+        flow.push({ name: 'a', html: '<input>' });
+        const seen = vi.fn();
+        document.addEventListener('keydown', seen);
+        key($('.auth-dialog input').get(0), 'Delete');
+        key($('.auth-dialog input').get(0), 'Enter');
+        document.removeEventListener('keydown', seen);
+        expect(seen).not.toHaveBeenCalled();
+    });
+
+    it('keeps focus in the card while busy, since a locked field would drop it to the page', () => {
+        const flow = openAuthFlow();
+        flow.push({ name: 'a', html: '<input>' });
+        const el_input = $('.auth-dialog input').get(0);
+        el_input.focus();
+        flow.setBusy(true);
+        el_input.disabled = true;
+        expect(document.activeElement).toBe($('.auth-dialog').get(0));
+    });
+
+    it('hands focus back to where it was once busy ends, so Enter can retry', () => {
+        const flow = openAuthFlow();
+        flow.push({ name: 'a', html: '<input class="one"><input class="two">' });
+        const el_two = $('.auth-dialog .two').get(0);
+        el_two.focus();
+        flow.setBusy(true);
+        el_two.disabled = true;
+        el_two.disabled = false;
+        flow.setBusy(false);
+        expect(document.activeElement).toBe(el_two);
+
+        // A screen that moved focus on its own keeps it there.
+        flow.setBusy(true);
+        $('.auth-dialog .one').get(0).focus();
+        flow.setBusy(false);
+        expect(document.activeElement).toBe($('.auth-dialog .one').get(0));
+    });
+
+    it('keeps focus in the card when the backdrop is pressed', async () => {
+        const flow = openAuthFlow();
+        flow.push({ name: 'a', html: '<input>' });
+        const press = new MouseEvent('mousedown', { bubbles: true, cancelable: true, detail: 1 });
+        $('.auth-dialog-overlay').get(0).dispatchEvent(press);
+        expect(press.defaultPrevented).toBe(true);
+        $('.auth-dialog-overlay').get(0).dispatchEvent(new MouseEvent('click', { bubbles: true, detail: 1 }));
+        expect(flow.isClosed()).toBe(false);
+
+        const inside = new MouseEvent('mousedown', { bubbles: true, cancelable: true, detail: 1 });
+        $('.auth-dialog input').get(0).dispatchEvent(inside);
+        expect(inside.defaultPrevented).toBe(false);
+    });
+
+    it('stacks screens, keeping what was typed, with Back and goTo', () => {
+        const flow = openAuthFlow();
+        flow.push({ name: 'login', html: '<input class="typed">' });
+        $('.typed').val('kept');
+        expect($('.auth-dialog-back').prop('hidden')).toBe(true);
+
+        const left = vi.fn();
+        flow.push({ name: 'signup', html: '<p>signup</p>', onLeave: left });
+        expect($('[data-screen="login"]').prop('hidden')).toBe(true);
+        expect($('.auth-dialog-back').prop('hidden')).toBe(false);
+
+        flow.back();
+        expect(left).toHaveBeenCalledOnce();
+        expect($('[data-screen="signup"]')).toHaveLength(0);
+        expect($('[data-screen="login"]').prop('hidden')).toBe(false);
+        expect($('.typed').val()).toBe('kept');
+
+        flow.push({ name: 'signup', html: '' });
+        flow.push({ name: 'recover', html: '' });
+        expect(flow.goTo('login')).toBe(true);
+        expect($('.auth-screen')).toHaveLength(1);
+        expect(flow.goTo('nope')).toBe(false);
+    });
+
+    it('marks the card scrolled while the showing screen is, so the bar covers what passes under it', () => {
+        const flow = openAuthFlow();
+        const scroll = (screen, top) => {
+            const el = $(`[data-screen="${screen}"] .auth-body`).get(0);
+            el.scrollTop = top;
+            el.dispatchEvent(new Event('scroll'));
+        };
+        flow.push({ name: 'a', html: '<div class="auth-body"></div>' });
+        expect($('.auth-dialog').hasClass('auth-dialog-scrolled')).toBe(false);
+        scroll('a', 40);
+        expect($('.auth-dialog').hasClass('auth-dialog-scrolled')).toBe(true);
+        flow.push({ name: 'b', html: '<div class="auth-body"></div>' });
+        expect($('.auth-dialog').hasClass('auth-dialog-scrolled')).toBe(false);
+        flow.back();
+        expect($('.auth-dialog').hasClass('auth-dialog-scrolled')).toBe(true);
+        scroll('a', 0);
+        expect($('.auth-dialog').hasClass('auth-dialog-scrolled')).toBe(false);
+    });
+
+    it('offers Back on a first screen that asks for it', () => {
+        const flow = openAuthFlow({ page: true });
+        const back = vi.fn();
+        flow.push({ name: 'only', html: '', onBack: back });
+        expect($('.auth-dialog-back').prop('hidden')).toBe(false);
+        $('.auth-dialog-back').trigger('click');
+        expect(back).toHaveBeenCalledOnce();
+    });
+
+    it('tells waiting screens when the flow closes', () => {
+        const flow = openAuthFlow();
+        const left = vi.fn();
+        flow.push({ name: 'a', html: '', onLeave: left });
+        flow.finish(true);
+        expect(left).toHaveBeenCalledOnce();
+    });
+
+    it('lets a second prompt join the open flow instead of stacking another card', async () => {
+        expect(joinAuthFlow()).toBeNull();
+        const flow = openAuthFlow();
+        flow.push({ name: 'a', html: '' });
+        const joined = joinAuthFlow();
+        expect($('.auth-dialog')).toHaveLength(1);
+        flow.finish(true);
+        await expect(joined).resolves.toBe(true);
+    });
+
+    it('leaves the field being typed in when a second prompt joins', () => {
+        const flow = openAuthFlow();
+        flow.push({ name: 'a', html: '<input class="first"><input class="second">' });
+        $('.second').get(0).focus();
+        joinAuthFlow();
+        expect(document.activeElement).toBe($('.second').get(0));
+
+        // Focus that wandered off the card is brought back to it.
+        $('.second').get(0).blur();
+        joinAuthFlow();
+        expect($('.auth-dialog').get(0).contains(document.activeElement)).toBe(true);
+    });
+});
+
+describe('authHeadHtml', () => {
+    it('makes the logo a keyboard-reachable way out only on a cover page', () => {
+        const page = openAuthFlow({ page: true });
+        const $page_head = $(authHeadHtml(page, 'Log in'));
+        expect($page_head.find('a.auth-logo-link').attr('href')).toBe('/');
+        expect($page_head.find('.auth-logo').attr('alt')).toBe('Puter');
+        page.finish(false);
+
+        const dialog = openAuthFlow();
+        const $dialog_head = $(authHeadHtml(dialog, 'Log in'));
+        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', () => {
+    it('defaults to reloading on success, to the page the flow started on', () => {
+        const options = authFlowOptions();
+        expect(options.reload_on_success).toBe(true);
+        expect(options.redirect_url).toBe(window.location.href);
+        expect(options.show_signup_button).toBe(true);
+        expect(options.send_confirmation_code).toBe(false);
+    });
+
+    it('keeps an explicit empty redirect', () => {
+        expect(authFlowOptions({ redirect_url: '' }).redirect_url).toBe('');
+    });
+});
+
+describe('navigateAfterSignIn', () => {
+    const withLocation = (href, run) => {
+        const original = window.location;
+        const replace = vi.fn();
+        const reload = vi.fn();
+        delete window.location;
+        window.location = { href, replace, reload };
+        const spy = vi.spyOn(history, 'replaceState').mockImplementation(() => {});
+        let states;
+        try {
+            run();
+        } finally {
+            window.location = original;
+            states = spy.mock.calls.map((call) => call[2]);
+            spy.mockRestore();
+        }
+        return { replace, reload, states };
+    };
+
+    it('goes to another page by replacing this one', () => {
+        const { replace, reload } = withLocation('https://puter.test/action/login', () => {
+            navigateAfterSignIn('/');
+        });
+        expect(replace).toHaveBeenCalledWith('/');
+        expect(reload).not.toHaveBeenCalled();
+    });
+
+    // Replacing with a hash-only change would scroll, never reload.
+    it('reloads when only the hash would change, as on a dashboard tab', () => {
+        const { replace, reload, states } = withLocation('https://puter.test/#files', () => {
+            navigateAfterSignIn('https://puter.test/#files');
+        });
+        expect(replace).not.toHaveBeenCalled();
+        expect(reload).toHaveBeenCalledOnce();
+        expect(states).toEqual(['https://puter.test/#files']);
+    });
+});

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

@@ -0,0 +1,148 @@
+/*
+ * 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 "Sign in with Google" (and other identity provider) buttons of the
+// login and signup screens. A button navigates to the backend's OIDC start
+// route, which comes back to the page the flow started from.
+
+import { get_oidc_return_to } from '../../helpers/authRedirect.js';
+import { KNOWN_OIDC_PROVIDERS, OIDC_GENERIC_PROVIDER_ICON, humanizeOidcProviderId } from '../../util/openid.js';
+import { offersFederatedSignInInPopup } from '../../util/popupAuth.js';
+
+const GOOGLE_ICON = '<img alt="" src="data:image/webp;base64,UklGRu4GAABXRUJQVlA4WAoAAAAQAAAAXwAAXwAAQUxQSAUDAAABoATJtmnbGs+23+vZtm3btm3btnHxjG/btm3bnI197tljzjXjtSNiAnAjmbNs8x5DR40e2qtFhTzuVJ2e+rrE/ODKwsZe5J90n9CfXVw6vLEvifIH87OHVOK0mLxSLpSyd4vZhyuGkP+amL45j7lVYn6+rQpfSYDvFzO0QgIdYeZJCTbNRpnfJeDXLTSQsH/X6yiBj1TrIoEPgnZzCXwwtMtL4AOhnfP/wPpC/X0Jux/Uj4jySzsGVskJADkq9dn4JKEP1NuJ6gMDELvrrTF6QP9fjX0FQc2xLZme0E8Tfko20LOmZdAD+tWF/lVlqNb7I9IFBt+hpUD9CZGuMNhT2ONh8GJvWPyK1QZedhdyS7j5Bqkf3Kwo3A3w8yTneTgq3NyOdOZMhqPplM/h6Z+Urp6UF+ZX8HQGZZIrVylw9SvGnRqP33ev2QdSEwlzpIaYTlCOUtSLQpGujN/hRePIFMZDbgyOrGUcdGNe5CBjoRtbIimMMW4ciVxgDHQjxb0LkRTGGF8OMha6kRZZyzjkxrHIFMbDbmyPdGX84cbiSDmGFPNiZASU0V60SvAV4y4vyiS4yhCNSuXZxb5lIOEMyngFRSF+nqg85YsAOjNuSoQ/GdLJXhpjfgbplE/tCbN2Bp0pMtHaBAoy5khOY78yHkjiJOdZW3OEOSmJihxZaymPUPMlgTc40sfQy5RnkWx3kjQ3c0ioI5LClyRpZWSRcJF8T5aMNbFKuHti4B2WnDVwUcj541SnyVeVlCp/KeQ0xE6jiZzNppD1jNDzxcO/PJG9BUhF9gl/B4jtNEQeGBAv55gnRfFfUI+oiMhLOwZWyRnJXKbltLOfim4nDt5XMn0N5Jz/e/Eb6OW9KMtDcx8GQrOLB6ug2zG8fdBuENoB6Jf5PaiVMPlkQP1hdEUov5aH2QpfBXETTK+y91dnGM9/zdh2BFj2bkNn8iHMEqeN7MiJgMe+pPZwP4Sef9J9vL8vD8oMH6tOT309zo+P7BlcAs7mLNu8x9BRY4b1aVO9MG4cAQBWUDggwgMAABAVAJ0BKmAAYAA+bSyTRqQiIaEtVEyQgA2JbAC++hZa3jl94/Jj2rrA/Tvv9y7x+OzH+L5o/8p7APMA/TPpD+YD+bf4T9bPfW/mfqo/wHqAf0v/hdYB6AH7Aemp+5HwS/uN+6XtXdQB1N/Rj+m/RWYp6GESYsQNCm+TZ3BvtEgBK+isF38GQzHNMrw+tkbAm5lUM4rWqU9srOS+RuAUa8nFYoFrGH73Fzd++s+LPyEGAAD+Yg+gQRuJCapqteWj86DdkHmfHdS+mWVn7Ue8RiK5AaWCIe7RXaDKn0baNe80expR5tTBclgnd+SEzNZ6N3NL1suPhGwRqKzB5wNnWUXD7R0IkT5uIwUhTsO/1ucVEMKvTZRe4j7WwrA+e53P8J1/cdIvKtrtZv9AH5u1heZ1dGQELuxMxbQUnrw6IUh0YLBKEjNnR3JIsFNwkC+WLw4wkCMati73lcMjT6U2KIYsr0g5bPzSmo3ir9qRjtIqthpPIvuvYt8AbMewSj96NIqTM14M6ABtOaY87d8HOU7baFGGQjU1f8vf7SV5AjDrfW0VVzQcBez+PYiPApyQUAozEmZFKBDvX9ifFFacoulG9NCPDXa1mRPVwzrKuN3VfwUfv8Bx8QJ88prsOCDd8UvNDnUzbRqBXOmQ4co+/xYy/iQV89GHs4pb0D2LYwv6aY8yPLCrYyAPUe4dKEh/FBqRBJ/716CJVMTCrvB+gSgPwNjN5LlnNQqkBsHnSqdUFddjvBKNdm6zm8ggLFJl14S37sJW1fAEbiB0IqxcqlJOWol+ecJy9xdESchmlROmo/4/9V34VN2cw8NUB5POPUNzivyMFfgF27QTFXgya/LF3OsfHMF6Itejgy4ab38VPFjez5f8Z/b/dhYV21SflE4KtUj8LZDrQXRp+Pzdf/gWfvm2oLh0x+Fr+ggo2jjG3DFn95Wj1P3ra1RtzYE8ffXBeR2lDhL+GPJiiZaVinGMkjVYup0AghAhIfVgFtsL8lhMyJY84ccksHz92o1/J3NfrGSM8NwOv7ieeBjq2eqCOmrUHpG3mlr8Hj/fR4d+orLlpipLTh3+cRY7suXQXw9SPYZieoKS/JE9y0f+BcWCzdNshWl2oVpeK2qm36iFltfGZUvXdfBKufE9RkZcyOBDUVeONlBchjuaLPNd6fSlk41Pp57nF5MmES2Kl7HqY+f2pvS71eIgUXpqtAFIY94JSmNre+g49tL8VnZlJNqgVhj/De//5zH/84h//5uJfunlawY99GgDkm8cYFbIAAAA">';
+const MICROSOFT_ICON = '<svg aria-hidden="true" viewBox="0 0 23 23" fill="none"><rect x="1" y="1" width="10" height="10" fill="#f25022"/><rect x="12" y="1" width="10" height="10" fill="#7fba00"/><rect x="1" y="12" width="10" height="10" fill="#00a4ef"/><rect x="12" y="12" width="10" height="10" fill="#ffb900"/></svg>';
+const APPLE_ICON = '<svg aria-hidden="true" viewBox="0 0 384 512" fill="currentColor"><path d="M318.7 268.7c-.2-36.7 16.4-64.4 50-84.8-18.8-26.9-47.2-41.7-84.7-44.6-35.5-2.8-74.3 20.7-88.5 20.7-15 0-49.4-19.7-76.4-19.7C63.3 141.2 4 184.8 4 273.5q0 39.3 14.4 81.2c12.8 36.7 59 126.7 107.2 125.2 25.2-.6 43-17.9 75.8-17.9 31.8 0 48.3 17.9 76.4 17.9 48.6-.7 90.4-82.5 102.6-119.3-65.2-30.7-61.7-90-61.7-91.9zm-56.6-164.2c27.3-32.4 24.8-61.9 24-72.5-24.1 1.4-52 16.4-67.9 34.9-17.5 19.8-27.8 44.3-25.6 71.9 26.1 2 49.9-11.4 69.5-34.3z"/></svg>';
+
+const KNOWN = {
+    google: { icon: GOOGLE_ICON, login: 'sign_in_with_google', signup: 'sign_up_with_google' },
+    microsoft: { icon: MICROSOFT_ICON, login: 'sign_in_with_microsoft', signup: 'sign_up_with_microsoft' },
+    apple: { icon: APPLE_ICON, login: 'sign_in_with_apple', signup: 'sign_up_with_apple' },
+};
+
+// Shown in this order whatever order the server lists them in.
+const KNOWN_ORDER = ['google', 'microsoft', 'apple'];
+
+/**
+ * Whether this page may offer a federated sign-in at all. A federated hop
+ * navigates a popup away and the provider returns it as a plain sign-in
+ * popup, losing whatever the popup was opened to do (and, for a permission
+ * prompt, handing the opener a token instead of a decision). A
+ * cross-origin-isolated opener can only get the token through the session
+ * relay, which the provider's return doesn't keep.
+ *
+ * @returns {boolean}
+ */
+export const mayOfferProviders = () => ! (window.embedded_in_popup
+    && ( ! offersFederatedSignInInPopup(window.gui_action)
+        || window.url_query_params?.get('cross_origin_isolated') === 'true'));
+
+/**
+ * The URL that starts a provider's sign-in.
+ *
+ * @param {string} provider
+ * @param {'login'|'signup'} kind
+ * @param {string | undefined} referrer
+ * @returns {string}
+ */
+export const providerStartUrl = (provider, kind, referrer) => {
+    let url = `${window.gui_origin}/auth/oidc/${encodeURIComponent(provider)}/start?flow=${kind}`;
+    // Return to the interface the flow started from (the backend whitelists the path).
+    const return_to = get_oidc_return_to();
+    if ( return_to ) url += `&return_to=${encodeURIComponent(return_to)}`;
+    if ( referrer ) url += `&referrer=${encodeURIComponent(referrer)}`;
+    // A provider sign-in can create the account, so a signup link's code rides along.
+    if ( window.signup_bonus_code ) url += `&bonusCode=${encodeURIComponent(window.signup_bonus_code)}`;
+    if ( window.embedded_in_popup && window.url_query_params?.get('msg_id') ) {
+        url += `&embedded_in_popup=true&msg_id=${encodeURIComponent(window.url_query_params.get('msg_id'))}`;
+        if ( window.openerOrigin ) url += `&opener_origin=${encodeURIComponent(window.openerOrigin)}`;
+    }
+    return url;
+};
+
+/** @type {WeakMap<import('./authFlow.js').AuthFlow, Promise<{ providers?: string[], signupOidcOnly?: boolean } | null>>} */
+const lookups = new WeakMap();
+
+/**
+ * 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, flow }) {
+    if ( ! mayOfferProviders() ) return null;
+    const data = await lookUpProviders(flow);
+    if ( ! Array.isArray(data?.providers) || ! data.providers.length ) return null;
+
+    const ordered = [
+        ...KNOWN_ORDER.filter((provider) => data.providers.includes(provider)),
+        ...data.providers.filter((provider) => ! KNOWN_OIDC_PROVIDERS.includes(provider)),
+    ];
+    let h = '';
+    for ( const provider of ordered ) {
+        const known = KNOWN[provider];
+        const label = known
+            ? i18n(known[kind])
+            : i18n(kind === 'login' ? 'sign_in_with_provider' : 'sign_up_with_provider', [humanizeOidcProviderId(provider)]);
+        const icon = known ? known.icon : OIDC_GENERIC_PROVIDER_ICON;
+        h += `<button type="button" class="dashboard-dialog-btn auth-provider-btn oidc-${known ? provider : 'custom'}-btn" data-provider="${html_encode(provider)}">`;
+        h += `<span class="auth-provider-icon" aria-hidden="true">${icon}</span><span>${label}</span>`;
+        h += '</button>';
+    }
+    $list.html(h);
+    $list.on('click', '.auth-provider-btn', function () {
+        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/Auth/authTestSetup.js

@@ -0,0 +1,66 @@
+/*
+ * 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/>.
+ */
+
+// Shared jsdom setup for the auth dialog tests: the globals the GUI
+// installs at boot, reset between tests.
+
+import { vi } from 'vitest';
+import jQuery from '../../lib/jquery-3.6.1/jquery-3.6.1.min.js';
+
+globalThis.def = globalThis.def ?? ((value) => value);
+globalThis.$ = jQuery;
+globalThis.jQuery = jQuery;
+globalThis.i18n = (key, args) => (Array.isArray(args) && args.length ? `${key}:${args.join(',')}` : key);
+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 });
+
+export const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+/** A JSON fetch response. */
+export const reply = (status, data) => new Response(JSON.stringify(data), { status });
+
+/** Resets the boot globals the screens read. */
+export const resetAuthGlobals = () => {
+    document.body.innerHTML = '';
+    window.gui_origin = 'https://puter.test';
+    window.api_origin = 'https://api.puter.test';
+    window.app_domain = 'puter.com';
+    window.gui_params = {};
+    window.icons = {};
+    window.uuidv4 = () => `id-${Math.random().toString(36).slice(2)}`;
+    window.is_email = (value) => String(value).includes('@');
+    window.embedded_in_popup = false;
+    window.gui_action = undefined;
+    window.openerOrigin = undefined;
+    window.referrerStr = undefined;
+    window.signup_bonus_code = null;
+    window.url_query_params = new URLSearchParams('');
+    window.custom_headers = undefined;
+    window.turnstile = undefined;
+    window.logged_in_users = [];
+    window.auth_token = undefined;
+    window.update_auth_data = vi.fn(async () => {});
+    globalThis.fetch = vi.fn(async () => reply(200, { providers: [] }));
+};
+
+/** The screen showing in the auth card. */
+export const screen = () => $('.auth-dialog .auth-screen:not([hidden])');

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 {