Load the app browser embed's script from beside the GUI bundle

The embed page always loaded /dist/apps-embed.min.js from the server,
while the GUI bundle and the embed build are published to gui_bundle's
location (a CDN in production). The server's /dist copy can be stale, so
the embed ran an old build. It now loads apps-embed.min.js from
gui_bundle's directory, keeping /dist when gui_bundle isn't set.

doc/embedding-app-browser.md

@@ -0,0 +1,105 @@
+# Embedded app browser
+
+`GET /embed/apps` on the deployment's main GUI origin renders the same app browser
+as the dashboard's Apps tab, without the desktop or dashboard navigation.
+
+It supports search, paging, saved folders, and saved ordering. It uses the same
+installed-app and recommendation data as the dashboard, including the user's
+removed recommendations. Editing, adding, reordering, renaming, and uninstalling
+are disabled. Selecting an app opens it in a new browser tab at its own URL, the
+same way the dashboard does, and the host page stays open. The app's token isn't
+put in the URL: the app's SDK asks the embed for it once the tab loads, so the
+embed must still be open then. If the iframe is removed first, the app falls back
+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.
+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
+
+Only show the iframe after the user has signed in. The embed reads the existing
+GUI session from local storage on its own origin. It does not create accounts,
+show a login dialog, or accept a token from its parent. A missing session or
+failed load displays an unavailable/error state. Being signed in on a subdomain
+alone does not populate the main GUI origin's storage; the main GUI session must
+already exist.
+
+The route's `Content-Security-Policy: frame-ancestors` allows the GUI origin and
+the embedding page's origin when it is a subdomain of `config.domain` with the
+scheme and port from `config.origin`, and not under one of the user-content
+hosting domains (`static_hosting_domain`, `private_app_hosting_domain`, and their
+`_alt` variants). For example, `https://puter.com` permits
+`https://spreadsheet.puter.com`, and `http://puter.localhost:4100` permits
+`http://spreadsheet.puter.localhost:4100` but not
+`http://someone.site.puter.localhost:4100`. The embedding page is read from the
+iframe request's referrer, so the host must not suppress it (the browser default
+`strict-origin-when-cross-origin` is enough). All ancestors in a nested iframe
+chain must be allowed. Other GUI routes retain `X-Frame-Options: SAMEORIGIN`.
+
+The embed accepts no query parameters. Requests with a query string redirect to
+the same embed path so SDK bootstrap parameters cannot override the session or API
+origin. The host needs to allow the GUI origin in its own `frame-src` CSP if it
+sets one. If sandboxing the iframe, allow scripts, same-origin storage, popups,
+and popups to escape the sandbox.
+
+## Host integration
+
+Create the iframe 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;
+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.
+
+This example assumes `puterOrigin` comes from the host app's deployment settings
+and the caller has already established the GUI session. Translate the button and
+frame labels using the host app's localization system.
+
+```html
+<button id="more-apps" type="button">More apps</button>
+<dialog id="apps-dialog" aria-label="More apps">
+  <button id="close-apps" type="button">Close</button>
+  <div id="apps-frame"></div>
+</dialog>
+<style>
+  #apps-dialog { padding: 12px; width: min(900px, 90vw); }
+  #apps-frame iframe { width: 100%; height: min(650px, 75vh); border: 0; }
+</style>
+<script type="module">
+  const puterOrigin = 'https://puter.com'; // Use this deployment's configured origin.
+  const dialog = document.querySelector('#apps-dialog');
+  const container = document.querySelector('#apps-frame');
+  const trigger = document.querySelector('#more-apps');
+
+  trigger.addEventListener('click', () => {
+    const frame = document.createElement('iframe');
+    frame.title = 'Your apps';
+    frame.src = new URL('/embed/apps', puterOrigin).href;
+    container.replaceChildren(frame);
+    dialog.showModal();
+  });
+  document.querySelector('#close-apps').addEventListener('click', () => dialog.close());
+  dialog.addEventListener('close', () => {
+    container.replaceChildren();
+    trigger.focus();
+  });
+</script>
+```
+
+## Implementation and checks
+
+`createAppBrowser` in `src/gui/src/UI/Dashboard/AppBrowser.js` owns the shared UI
+and data behavior. `TabApps.js` injects desktop actions. `appsEmbed.js` supplies
+new-tab launching through `launchAppInTab` in `src/gui/src/helpers/appTabLaunch.js`,
+which builds 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`.
+No puter.js API or app-list endpoint changes are needed.
+
+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/backend/vitest.config.ts src/backend/server.test.ts
+```

doc/push-client.md

@@ -1,6 +1,6 @@
 # Browser push client
 
-Puter's desktop shows pushes through `/sw.js`. Core registers it, and shows Settings → Notifications, only when the `pushEnabled` gui param is `true`; core never sets it. A backend extension that delivers pushes sets it with `services.homepage.setGuiParam('pushEnabled', true)` and can load its own code into the worker with `services.homepage.registerServiceWorkerScript(path)`.
+Puter's desktop shows pushes through `/sw.js`. Core shows Settings → Notifications only when the `pushEnabled` gui param is `true`; core never sets it. The worker is registered only when push is turned on in the browser, and a load removes one left without a subscription. A backend extension that delivers pushes sets it with `services.homepage.setGuiParam('pushEnabled', true)` and can load its own code into the worker with `services.homepage.registerServiceWorkerScript(path)`.
 
 Core subscribes the browser to a push service only when the server also publishes `pushWebPushKey` (see [Built-in Web Push client](#built-in-web-push-client)), and it has no `/push/*` routes of its own. The device, app, preference and subscription endpoints below come from that extension. On a deployment without one, such as most self-hosted servers, they answer core's plain 404 (`code: 'not_found'`), which `puter.notifications` reports as `push_unavailable` and the Notifications tab shows as unavailable. A device the extension can't find is `device_not_found`.
 
@@ -22,12 +22,13 @@ When the browser replaces the subscription (`pushsubscriptionchange`), `sw.js` p
 
 Before a notification is pushed, the server asks the open clients whether they received it live. It sends `notif.receipt` with `{ uid }` on the user's sockets for the app that sent it, or on the desktop's sockets for Puter's own notifications. The SDK remembers the uids its page received through `onNotification()`, `onPush()` or the desktop's feed, and answers once its page has that notification, or with `{ received: false }` when it never gets it. The server waits up to 5 seconds (`notificationAckTimeoutMs`).
 
-An answer carries `visibilityState`, `focused` and `showsOwn`, the last being whether the page shows the notification itself. A website page shows it itself when it is hidden or unfocused, has an `onPush()` handler and notification permission, and no other tab of the same site is focused. Inside the desktop, the desktop shows it, and an app's `onPush()` result is never shown as a browser notification.
+An answer carries `visibilityState` and `focused` as they were when the page received the notification. Pages never show a browser notification themselves; pushes do.
 
-- An answer from a page that is visible and focused, or that shows the notification itself, stops the push.
-- Otherwise the notification is pushed. A website's pushes go only to the browsers that subscribed through its own worker, never to Puter's `/sw.js`. An app inside the desktop pushes through `/sw.js`, which shows the app's name and icon.
-- A hidden desktop tab shows no banner, so answers only from hidden desktop tabs don't stop a push of Puter's own notifications.
-- A client that can't answer, such as an older puter.js, holds the push back while it is connected.
+- An answer from a page that was visible and focused stops the push (`handled` on `notif.delivery.settled`). An older client that doesn't send `focused` counts while visible.
+- Otherwise the notification is pushed, to every browser the user subscribed. A website's pushes go only to the browsers that subscribed through its own worker, never to Puter's `/sw.js`. An app inside the desktop pushes through `/sw.js`, which shows the app's name and icon.
+- A client that can't answer, such as an older puter.js, doesn't hold the push back.
+
+The ask reaches only the sockets in the asking region. So that other regions hear about a page too, a page that receives a notification live while visible and focused also sends `notif.handled` with `{ uid }` on the socket it came on. Core relays it as the node-local `notif.handled` event with the socket's user and app, at most 60 a minute per user; an extension that delivers pushes decides what to do with it.
 
 ## Registering
 

src/backend/clients/event/types.ts

@@ -117,7 +117,7 @@ export type EventMap = {
         model_used: string;
         service_used: string;
         intended_service: string;
-        model_details: {
+        model_details?: {
             id: string;
             provider: string;
             input_cost_key: string;
@@ -636,6 +636,18 @@ export type EventMap = {
         /** A peer region holds a socket for the user. */
         peerRegions: boolean;
         responders: NotifDeliveryResponder[];
+        /** A page here got it live while visible and focused. */
+        handled: boolean;
+    };
+    /**
+     * A page reported that it got a notification live while visible and
+     * focused. Node-local; `appUid` is the reporting socket's app, absent for
+     * the desktop.
+     */
+    'notif.handled': {
+        userId: number;
+        appUid?: string;
+        uid: string;
     };
 
     // ---- Metering ----
@@ -1067,10 +1079,11 @@ export type EventKey = keyof EventMap & string;
 // Generates a wildcard for every non-final dot-separated prefix of K.
 export type WildcardPrefixes<K extends string> =
     K extends `${infer Head}.${infer Tail}`
-        ? | `${Head}.*`
-          | (Tail extends `${string}.${string}`
-                ? `${Head}.${WildcardPrefixes<Tail>}`
-                : never)
+        ?
+              | `${Head}.*`
+              | (Tail extends `${string}.${string}`
+                    ? `${Head}.${WildcardPrefixes<Tail>}`
+                    : never)
         : never;
 
 export type ListenKey = EventKey | WildcardPrefixes<EventKey>;
@@ -1081,18 +1094,16 @@ export type MatchingEvents<P extends ListenKey> = P extends `${infer Prefix}.*`
 
 /** Acked, not acked, no socket anywhere, or sockets only in a peer region. */
 export type NotifDeliveryOutcome =
-    'received' | 'unreceived' | 'no-socket' | 'remote-only';
+    | 'received'
+    | 'unreceived'
+    | 'no-socket'
+    | 'remote-only';
 
 /** One socket's receipt for a live notification. */
 export interface NotifDeliveryResponder {
     visibilityState: 'visible' | 'hidden' | 'unknown';
     /** The page's window has focus. Absent from older clients. */
     focused?: boolean;
-    /**
-     * The page shows its own browser notification while hidden or unfocused.
-     * Absent from older clients.
-     */
-    showsOwn?: boolean;
 }
 
 export type EventMetadata = {

src/backend/controllers/homepage/HomepageController.ts

@@ -22,6 +22,7 @@ import path from 'node:path';
 import { PuterController } from '../types.js';
 import { toAppShellView } from '../../util/appShellView.js';
 import type { PuterRouter } from '../../core/http/PuterRouter';
+import type { IConfig } from '../../types';
 import type {
     PuterHomepageService,
     PageMeta,
@@ -43,9 +44,9 @@ const APP_LANDING_LIMIT = {
 };
 
 /**
- * App descriptions can run long; search snippets and social cards want a
- * short blurb. Collapses whitespace, then cuts at a word boundary with an
- * ellipsis so the result never exceeds `APP_META_DESCRIPTION_MAX`.
+ * App descriptions can run long; search snippets and social cards want a short
+ * blurb. Collapses whitespace, then cuts at a word boundary with an ellipsis so
+ * the result never exceeds `APP_META_DESCRIPTION_MAX`.
  */
 export function appMetaDescription(text: string): string {
     const clean = text.replace(/\s+/g, ' ').trim();
@@ -56,6 +57,47 @@ export function appMetaDescription(text: string): string {
     return `${cut.replace(/[\s,;:.!?…—-]+$/, '')}…`;
 }
 
+/**
+ * `frame-ancestors` for the app browser embed. 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.
+ */
+export function embedFrameAncestors(
+    config: Pick<
+        IConfig,
+        | 'origin'
+        | 'domain'
+        | 'static_hosting_domain'
+        | 'static_hosting_domain_alt'
+        | 'private_app_hosting_domain'
+        | 'private_app_hosting_domain_alt'
+    >,
+    referer: string | undefined,
+): string {
+    const gui = new URL(config.origin ?? `https://${config.domain}`);
+    let parent: URL;
+    try {
+        parent = new URL(referer ?? '');
+    } catch {
+        return "'self'";
+    }
+    const host = parent.hostname.toLowerCase();
+    const hostingDomains = [
+        config.static_hosting_domain,
+        config.static_hosting_domain_alt,
+        config.private_app_hosting_domain,
+        config.private_app_hosting_domain_alt,
+    ]
+        .map((d) => (d ?? '').toLowerCase().split(':')[0])
+        .filter(Boolean);
+    const allowed =
+        parent.protocol === gui.protocol &&
+        parent.port === gui.port &&
+        host.endsWith(`.${config.domain.toLowerCase()}`) &&
+        !hostingDomains.some((d) => host === d || host.endsWith(`.${d}`));
+    return allowed ? `'self' ${parent.origin}` : "'self'";
+}
+
 /**
  * Routes that render the Puter GUI shell, plus a catch-all static fallback
  * under `<gui_assets_root>/src` for non-dist/src paths (images, fonts, lib
@@ -105,6 +147,21 @@ export class HomepageController extends PuterController {
 
         router.get('/', {}, (req, res) => sendShell(req, res));
 
+        router.get('/embed/apps', {}, (req, res) => {
+            // SDK bootstrap parameters must not change this page's account or API origin.
+            if (Object.keys(req.query).length) {
+                res.redirect('/embed/apps');
+                return;
+            }
+            res.removeHeader('X-Frame-Options');
+            res.setHeader(
+                'Content-Security-Policy',
+                `frame-ancestors ${embedFrameAncestors(this.config, req.get('referer'))}`,
+            );
+            res.setHeader('Cache-Control', 'no-store');
+            res.send(homepage.renderAppBrowserEmbed());
+        });
+
         router.get('/settings', {}, (req, res) => sendShell(req, res));
         router.get('/settings/*splat', {}, (req, res) => sendShell(req, res));
 

src/backend/server.test.ts

@@ -336,6 +336,58 @@ describe('PuterServer host header validation', () => {
         expect(api.headers['x-frame-options']).toBeUndefined();
     });
 
+    it('allows deployment subdomains to frame the app browser embed', async () => {
+        const parent = `http://spreadsheet.puter.localhost:${port}`;
+        for (const path of ['/embed/apps', '/embed/apps/']) {
+            const res = await request(path, {
+                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/apps-embed.min.js');
+            expect(res.body).not.toContain('/dist/bundle.min.js');
+            expect(res.body).toContain(`http://api.puter.localhost:${port}`);
+        }
+        const gui = await request('/embed/apps', {
+            host: `puter.localhost:${port}`,
+            referer: `http://puter.localhost:${port}/dashboard`,
+        });
+        expect(gui.headers['content-security-policy']).toBe("frame-ancestors 'self'");
+        const dashboard = await request('/dashboard', { host: `puter.localhost:${port}` });
+        expect(dashboard.headers['x-frame-options']).toBe('SAMEORIGIN');
+        const api = await request('/embed/apps', { host: `api.puter.localhost:${port}` });
+        expect(api.status).toBe(404);
+    });
+
+    it.each([
+        ['a user-hosted site', 'http://someone.site.puter.localhost:PORT/'],
+        ['a private app host', 'http://someone.app.puter.localhost:PORT/'],
+        ['another site', 'http://evil.test:PORT/'],
+        ['another port', 'http://spreadsheet.puter.localhost:1/'],
+        ['a suppressed referrer', undefined],
+    ])('keeps the embed same-origin only when framed by %s', async (_label, referer) => {
+        const res = await request('/embed/apps', {
+            host: `puter.localhost:${port}`,
+            ...(referer ? { referer: referer.replace('PORT', String(port)) } : {}),
+        });
+        expect(res.status).toBe(200);
+        expect(res.headers['content-security-policy']).toBe("frame-ancestors 'self'");
+    });
+
+    it('strips SDK bootstrap query parameters from the embed route', async () => {
+        const res = await request('/embed/apps?puter.app_instance_id=other&puter.api_origin=https://other.test', {
+            host: `puter.localhost:${port}`,
+        });
+        expect(res.status).toBe(302);
+        expect(res.headers.location).toBe('/embed/apps');
+        expect(res.headers['x-frame-options']).toBe('SAMEORIGIN');
+    });
+
     it('blocks a request the ip.validate listeners veto', async () => {
         const handler = (_key: unknown, data: unknown) => {
             (data as { allow: boolean }).allow = false;

src/backend/services/events/registry.ts

@@ -121,7 +121,9 @@ export interface ProjectedNotifEvent extends ProjectedEventBase {
 }
 
 export type ProjectedEvent =
-    ProjectedFsEvent | ProjectedKvEvent | ProjectedNotifEvent;
+    | ProjectedFsEvent
+    | ProjectedKvEvent
+    | ProjectedNotifEvent;
 
 export type GapReason =
     | 'matched_subscription_limit'
@@ -270,7 +272,9 @@ export interface NotifPublicSubject extends SubjectSpec<
 }
 
 export type PublicSubject =
-    FsPublicSubject | KvPublicSubject | NotifPublicSubject;
+    | FsPublicSubject
+    | KvPublicSubject
+    | NotifPublicSubject;
 
 export interface UnpublishedInternalEvent {
     event: EventKey;
@@ -508,6 +512,10 @@ export const UNPUBLISHED_INTERNAL_EVENTS = [
         event: 'notif.delivery.settled',
         reason: 'A node-local report on how the live socket copy of a notification went; the notification itself publishes through `notif.created`.',
     },
+    {
+        event: 'notif.handled',
+        reason: 'A node-local report that a page saw a notification live, for extensions deciding whether to push it; not a change to the notification.',
+    },
 ] as const satisfies readonly UnpublishedInternalEvent[];
 
 // Every `fs.*`/`kv.*`/`notif.*` bus key needs a decision. A new key that is in

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

@@ -49,6 +49,54 @@ const makeReq = (over: Partial<Request> = {}): Request =>
         ...over,
     }) as unknown as Request;
 
+describe('app browser embed shell', () => {
+    it.each([
+        [{ env: 'dev' }, '/sdk/puter.dev.js'],
+        [{ env: 'prod' }, 'https://js.puter.com/v2/'],
+        [{ gui_puterjs_bundle: '/custom-sdk.js' }, '/custom-sdk.js'],
+    ])('uses the deployment SDK configuration %j', (config, sdkUrl) => {
+        const service = makeService({
+            ...config,
+            api_base_url: 'https://api.deployment.test',
+            domain: 'deployment.test',
+        });
+        const html = service.renderAppBrowserEmbed();
+        const configJson = html.match(/id="app-browser-config">(.*?)<\/script>/)![1];
+        expect(JSON.parse(configJson)).toEqual({
+            apiOrigin: 'https://api.deployment.test', sdkUrl,
+        });
+        expect(html).toContain('/dist/apps-embed.min.js');
+        expect(html).not.toContain('/dist/bundle.min.js');
+        expect(html).not.toContain('gui(');
+    });
+
+    it.each([
+        [{}, '/dist/apps-embed.min.js'],
+        [
+            { gui_bundle: 'https://gui-cdn.deployment.test/bundle.min.js' },
+            'https://gui-cdn.deployment.test/apps-embed.min.js',
+        ],
+        [
+            { gui_bundle: '/static/bundle.min.js?v=42' },
+            '/static/apps-embed.min.js?v=42',
+        ],
+    ])('loads its script from beside the GUI bundle %j', (config, script) => {
+        const html = makeService(config).renderAppBrowserEmbed();
+        expect(html).toContain(`<script defer src="${script}"></script>`);
+    });
+
+    it('escapes configured values without breaking its JSON bootstrap', () => {
+        const sdkUrl = '/sdk.js?value=</script><script>unexpected()</script>';
+        const html = makeService({
+            gui_params: { title: '<script>unexpected()</script>' },
+            gui_puterjs_bundle: sdkUrl,
+        }).renderAppBrowserEmbed();
+        expect(html).not.toContain('<script>unexpected()');
+        const configJson = html.match(/id="app-browser-config">(.*?)<\/script>/)![1];
+        expect(JSON.parse(configJson).sdkUrl).toBe(sdkUrl);
+    });
+});
+
 /** Capture what the service sends, and return the rendered HTML. */
 const render = async (
     service: PuterHomepageService,

src/backend/services/homepage/PuterHomepageService.ts

@@ -167,6 +167,52 @@ export class PuterHomepageService extends PuterService {
         this.#guiParams[key] = val;
     }
 
+    renderAppBrowserEmbed(): 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/'),
+        }).replace(/</g, '\\u003c');
+
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="robots" content="noindex">
+    <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">
+</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>
+</body>
+</html>`;
+    }
+
+    /**
+     * The embed's script is built beside the GUI bundle, so it is served from
+     * wherever `gui_bundle` is (a CDN in production), with the same query.
+     */
+    #appBrowserEmbedScript(): 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);
+        script.search = bundle.search;
+        return script.origin === base
+            ? `${script.pathname}${script.search}`
+            : script.href;
+    }
+
     /** `scriptPath` is a same-origin absolute path, like `/ext/push/worker.js`. */
     registerServiceWorkerScript(scriptPath: string): void {
         if (

src/backend/services/notification/NotificationService.ts

@@ -23,10 +23,14 @@ import { handlerDepthOf, type Actor } from '../../core/actor.js';
 import { Context } from '../../core/context.js';
 import type { NotifEventContext } from '../events/registry.js';
 import { PuterService } from '../types.js';
+import { checkRateLimit } from '../../core/http/middleware/rateLimit.js';
 import {
+    NOTIF_HANDLED_EVENT,
+    NOTIF_HANDLED_PER_MINUTE,
     NotificationSocketAdapter,
     notificationAckTimeoutMs,
     notificationsFoldInEnabled,
+    type NotifSocket,
     type ReceiptScope,
 } from './notificationSocket.js';
 import {
@@ -404,6 +408,11 @@ export class NotificationService extends PuterService {
         return this.#socket().receipt(scope);
     }
 
+    /** Installs the `notif.handled` verb on one connection. */
+    attachSocket(socket: NotifSocket, actor: Actor): void {
+        this.#socket().attachSocket(socket, actor);
+    }
+
     /**
      * Drop notifications past the retention window, in batches, and report how
      * many went. Deleting is all there is to it: nothing is pushed, because a
@@ -439,6 +448,12 @@ export class NotificationService extends PuterService {
             ackTimeoutMs: () => notificationAckTimeoutMs(this.config),
             heldInPeerRegion: (userId, appUid) =>
                 this.#heldInPeerRegion(userId, appUid),
+            allowHandled: (userId) =>
+                checkRateLimit(
+                    `socket:${NOTIF_HANDLED_EVENT}:${userId}`,
+                    NOTIF_HANDLED_PER_MINUTE,
+                    60_000,
+                ),
         });
         return this.#adapter;
     }

src/backend/services/notification/notificationDelivery.test.ts

@@ -32,7 +32,10 @@ import {
 import type { EventMap } from '../../clients/event/types.js';
 import type { PuterServer } from '../../server.js';
 import { accountSocketRoom, SocketService } from '../socket/SocketService.js';
-import { NOTIF_RECEIPT_EVENT } from './notificationSocket.js';
+import {
+    NOTIF_HANDLED_EVENT,
+    NOTIF_RECEIPT_EVENT,
+} from './notificationSocket.js';
 import {
     allocateEphemeralPort,
     createTestUser,
@@ -309,12 +312,13 @@ describe('live notification delivery receipts', () => {
             complete: true,
             peerRegions: false,
             responders: [{ visibilityState: 'hidden' }],
+            handled: false,
         };
         expect(settled).toEqual(expected);
         expect(state.settled).toEqual([expected]);
     });
 
-    it('passes a tab`s focus and own display through, typed strictly', async () => {
+    it('passes a tab`s focus through, typed strictly', async () => {
         const answers = [
             {
                 received: true,
@@ -326,7 +330,6 @@ describe('live notification delivery receipts', () => {
                 received: true,
                 visibilityState: 'nope',
                 focused: 1,
-                showsOwn: 'yes',
             },
         ];
         for (const answer of answers) {
@@ -341,11 +344,39 @@ describe('live notification delivery receipts', () => {
         expect(settled.outcome).toBe('received');
         expect(settled.responders).toEqual(
             expect.arrayContaining([
-                { visibilityState: 'hidden', focused: false, showsOwn: true },
+                { visibilityState: 'hidden', focused: false },
                 { visibilityState: 'unknown' },
             ]),
         );
         expect(settled.responders).toHaveLength(2);
+        expect(settled.handled).toBe(false);
+    });
+
+    it('counts as handled only a visible tab that is focused, or an older one that is visible', async () => {
+        const cases: Array<[Record<string, unknown>, boolean]> = [
+            [{ visibilityState: 'visible', focused: true }, true],
+            [{ visibilityState: 'visible', focused: false }, false],
+            [{ visibilityState: 'hidden', focused: true }, false],
+            [{ visibilityState: 'visible' }, true],
+        ];
+        for (const [answer, handled] of cases) {
+            const tab = await connect({ acks: [NOTIF_RECEIPT_EVENT] });
+            tab.on(NOTIF_RECEIPT_EVENT, (_data: unknown, ack: Ack) =>
+                ack({ received: true, ...answer }),
+            );
+
+            const { settled } = await ask();
+
+            expect(settled.handled, JSON.stringify(answer)).toBe(handled);
+            tab.disconnect();
+            await vi.waitFor(() =>
+                expect(
+                    state.server.services.socket.has({
+                        room: accountSocketRoom(state.userId),
+                    }),
+                ).toBe(false),
+            );
+        }
     });
 
     it('settles as unreceived when every tab answers that it never got it', async () => {
@@ -549,6 +580,7 @@ describe('live receipts from an app’s own sockets', () => {
             complete: true,
             peerRegions: false,
             responders: [{ visibilityState: 'visible' }],
+            handled: true,
         };
         expect(settled).toEqual(expected);
         expect(state.settled).toEqual([expected]);
@@ -719,3 +751,59 @@ describe('app receipts where the adapter cannot count servers', () => {
         });
     });
 });
+
+describe('a page reporting a notification it handled', () => {
+    const { state, connect, appSocket } = withAppReceipts({ cluster: true });
+    const reports: Array<EventMap['notif.handled']> = [];
+    const onHandled = (_key: string, data: unknown) => {
+        reports.push(data as EventMap['notif.handled']);
+    };
+
+    beforeAll(() => {
+        state.server.clients.event.on('notif.handled', onHandled);
+    });
+
+    afterEach(() => {
+        reports.length = 0;
+    });
+
+    afterAll(() => {
+        state.server?.clients.event.off('notif.handled', onHandled);
+    });
+
+    it('relays a desktop tab`s report for its user, without an app', async () => {
+        const tab = await connect({});
+        const uid = uuidv4();
+
+        tab.emit(NOTIF_HANDLED_EVENT, { uid });
+
+        await vi.waitFor(() =>
+            expect(reports).toEqual([{ userId: state.userId, uid }]),
+        );
+    });
+
+    it('relays an app page`s report with the app it acts as', async () => {
+        const page = await appSocket();
+        const uid = uuidv4();
+
+        page.emit(NOTIF_HANDLED_EVENT, { uid });
+
+        await vi.waitFor(() =>
+            expect(reports).toEqual([
+                { userId: state.userId, uid, appUid: OWN_APP },
+            ]),
+        );
+    });
+
+    it('drops a report without a notification uid', async () => {
+        const tab = await connect({});
+
+        tab.emit(NOTIF_HANDLED_EVENT, { uid: 'not-a-uid' });
+        tab.emit(NOTIF_HANDLED_EVENT, null);
+        tab.emit(NOTIF_HANDLED_EVENT, { uid: uuidv4() });
+
+        await vi.waitFor(() => expect(reports).toHaveLength(1));
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        expect(reports).toHaveLength(1);
+    });
+});

src/backend/services/notification/notificationSocket.ts

@@ -17,7 +17,9 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import { validate as validateUuid } from 'uuid';
 import type { EventClient } from '../../clients/event/EventClient.js';
+import type { Actor } from '../../core/actor.js';
 import type {
     EventMap,
     NotifDeliveryOutcome,
@@ -53,7 +55,10 @@ import type { IConfig } from '../../types.js';
  */
 
 export type NotifWire =
-    'notif.message' | 'notif.unreads' | 'notif.ack' | 'notif.removed';
+    | 'notif.message'
+    | 'notif.unreads'
+    | 'notif.ack'
+    | 'notif.removed';
 
 export const NOTIF_DELIVERY_EVENT = 'outer.notif.delivery';
 
@@ -67,6 +72,15 @@ export const DEFAULT_NOTIFICATION_ACK_TIMEOUT_MS = 5_000;
  */
 export const NOTIF_RECEIPT_EVENT = 'notif.receipt';
 
+/**
+ * Sent by a page with `{ uid }` when it got that notification live while
+ * visible and focused, so a region that didn't ask the page can still hear it.
+ */
+export const NOTIF_HANDLED_EVENT = 'notif.handled';
+
+/** `notif.handled` reports one user's sockets may send per minute. */
+export const NOTIF_HANDLED_PER_MINUTE = 60;
+
 /** One unread as the replay payload carries it. */
 export interface UnreadNotification {
     uid: string;
@@ -122,12 +136,16 @@ const responderOf = (response: unknown): NotifDeliveryResponder | null => {
         ...(typeof answer.focused === 'boolean'
             ? { focused: answer.focused }
             : {}),
-        ...(typeof answer.showsOwn === 'boolean'
-            ? { showsOwn: answer.showsOwn }
-            : {}),
     };
 };
 
+/**
+ * Visible and focused. An older client doesn't say whether it's focused, so it
+ * counts while visible.
+ */
+export const handledBy = (responder: NotifDeliveryResponder): boolean =>
+    responder.visibilityState === 'visible' && responder.focused !== false;
+
 interface AdapterDeps {
     event: EventClient;
     socket: SocketService;
@@ -138,6 +156,13 @@ interface AdapterDeps {
         userId: number,
         appUid: string | null,
     ) => Promise<boolean>;
+    /** Spends one of the user's `notif.handled` reports; false past the limit. */
+    allowHandled: (userId: number) => Promise<boolean>;
+}
+
+/** The part of a socket `attachSocket` installs its verb on. */
+export interface NotifSocket {
+    on(event: string, listener: (...args: never[]) => void): unknown;
 }
 
 type SettledDelivery = EventMap['notif.delivery.settled'];
@@ -253,6 +278,7 @@ export class NotificationSocketAdapter {
                 complete: asked.complete,
                 peerRegions,
                 responders,
+                handled: responders.some(handledBy),
             };
             this.#deps.event.emit(
                 'notif.delivery.settled',
@@ -266,6 +292,28 @@ export class NotificationSocketAdapter {
         }
     }
 
+    /**
+     * Relays a page's `notif.handled` as the node-local `notif.handled` event,
+     * scoped to the socket's user and app.
+     */
+    attachSocket(socket: NotifSocket, actor: Actor): void {
+        const userId = actor.user?.id;
+        if (userId === undefined) return;
+        const appUid = actor.effectiveApp?.uid;
+        socket.on(NOTIF_HANDLED_EVENT, ((payload: unknown) => {
+            const uid = (payload as { uid?: unknown } | null)?.uid;
+            if (typeof uid !== 'string' || !validateUuid(uid)) return;
+            void this.#deps.allowHandled(userId).then((ok) => {
+                if (!ok) return;
+                this.#deps.event.emit(
+                    'notif.handled',
+                    { userId, uid, ...(appUid ? { appUid } : {}) },
+                    {},
+                );
+            });
+        }) as (...args: never[]) => void);
+    }
+
     /** Whether this region holds a socket for the recipient right now. */
     hasSocket(userId: number): boolean {
         return this.#deps.socket.has({ room: userId });

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

@@ -39,6 +39,7 @@ import {
     MAX_REALTIME_MESSAGE_BYTES,
     MAX_UPSTREAM_MESSAGE_BYTES,
     OpenAIRealtimeRelayService,
+    promptMessagesOf,
     REALTIME_PATH,
     type RealtimeUsage,
     type RealtimeTranscriptionUsage,
@@ -122,6 +123,65 @@ describe('realtimeUsageRows', () => {
     });
 });
 
+describe('promptMessagesOf', () => {
+    it('reads message text, transcripts and function output from items', () => {
+        expect(
+            promptMessagesOf({
+                type: 'conversation.item.create',
+                item: {
+                    type: 'message',
+                    role: 'assistant',
+                    content: [
+                        { type: 'output_text', text: 'Hi' },
+                        { type: 'output_audio', transcript: 'Spoken' },
+                        { type: 'input_audio', audio: 'AAAA' },
+                    ],
+                },
+            }),
+        ).toEqual([
+            { role: 'assistant', content: 'Hi' },
+            { role: 'assistant', content: 'Spoken' },
+        ]);
+        expect(
+            promptMessagesOf({
+                type: 'conversation.item.create',
+                item: { type: 'function_call_output', output: '{"ok":1}' },
+            }),
+        ).toEqual([{ role: 'tool', content: '{"ok":1}' }]);
+    });
+
+    it('reads response instructions and out-of-band input', () => {
+        expect(
+            promptMessagesOf({
+                type: 'response.create',
+                response: {
+                    instructions: 'Summarize.',
+                    input: [
+                        { type: 'item_reference', id: 'item_1' },
+                        {
+                            type: 'message',
+                            role: 'user',
+                            content: [{ type: 'input_text', text: 'Text' }],
+                        },
+                    ],
+                },
+            }),
+        ).toEqual([
+            { role: 'system', content: 'Summarize.' },
+            { role: 'user', content: 'Text' },
+        ]);
+    });
+
+    it('returns nothing for audio and other events', () => {
+        expect(
+            promptMessagesOf({ type: 'input_audio_buffer.append', audio: 'x' }),
+        ).toEqual([]);
+        expect(
+            promptMessagesOf({ type: 'session.update', session: {} }),
+        ).toEqual([]);
+    });
+});
+
 describe('realtimeTranscriptionRows', () => {
     it('prices token usage by transcription model', () => {
         const rows = realtimeTranscriptionRows('gpt-4o-mini-transcribe', {
@@ -1380,6 +1440,139 @@ describe('OpenAIRealtimeRelayService relay', () => {
         }
     });
 
+    describe('prompt checks', () => {
+        type Check = {
+            completionId: string;
+            allow: boolean;
+            parameters: { model: string; messages: unknown[] };
+        };
+        let checks: Check[];
+        let costs: Record<string, unknown>[];
+        let refuse: (check: Check) => boolean;
+        const validate = (_key: string, data: Check) => {
+            checks.push(structuredClone(data));
+            if (refuse(data)) data.allow = false;
+        };
+        const costCalculated = (_key: string, data: Record<string, unknown>) =>
+            void costs.push(data);
+
+        beforeEach(() => {
+            checks = [];
+            costs = [];
+            refuse = () => false;
+            server.clients.event.on('ai.prompt.validate', validate as never);
+            server.clients.event.on(
+                'ai.prompt.cost-calculated',
+                costCalculated as never,
+            );
+        });
+        afterEach(() => {
+            server.clients.event.off('ai.prompt.validate', validate as never);
+            server.clients.event.off(
+                'ai.prompt.cost-calculated',
+                costCalculated as never,
+            );
+        });
+
+        it('checks the text sent before each response and logs its cost under the same id', async () => {
+            const c = open(
+                `${relayUrl}?model=gpt-realtime-mini&auth_token=${user.token}`,
+            );
+            await c.waitFor('session.created');
+            c.ws.send(
+                JSON.stringify({
+                    type: 'session.update',
+                    session: { instructions: 'Be brief.' },
+                }),
+            );
+            c.ws.send(
+                JSON.stringify({
+                    type: 'conversation.item.create',
+                    item: {
+                        type: 'message',
+                        role: 'user',
+                        content: [{ type: 'input_text', text: 'Hello' }],
+                    },
+                }),
+            );
+            c.ws.send(JSON.stringify({ type: 'response.create' }));
+            await vi.waitFor(() => expect(costs).toHaveLength(1));
+            expect(checks).toEqual([
+                expect.objectContaining({
+                    allow: true,
+                    parameters: {
+                        model: 'gpt-realtime-mini',
+                        messages: [
+                            { role: 'system', content: 'Be brief.' },
+                            { role: 'user', content: 'Hello' },
+                        ],
+                    },
+                }),
+            ]);
+            expect(costs[0]).toMatchObject({
+                completionId: checks[0].completionId,
+                input_tokens: 7,
+                output_tokens: 3,
+                input_ucents: 7 * 60,
+                output_ucents: 3 * 240,
+                total_ucents: 7 * 60 + 3 * 240,
+                model_used: 'gpt-realtime-mini',
+            });
+
+            // A response with no new text is still logged.
+            c.ws.send(JSON.stringify({ type: 'response.create' }));
+            await vi.waitFor(() => expect(costs).toHaveLength(2));
+            expect(checks[1].parameters.messages).toEqual([]);
+            expect(costs[1].completionId).toBe(checks[1].completionId);
+            c.ws.close();
+        });
+
+        it('closes the session when the check refuses the text', async () => {
+            refuse = (check) =>
+                JSON.stringify(check.parameters.messages).includes('refuse me');
+            const c = open(`${relayUrl}?auth_token=${user.token}`);
+            await c.waitFor('session.created');
+            c.ws.send(
+                JSON.stringify({
+                    type: 'response.create',
+                    response: { instructions: 'refuse me' },
+                }),
+            );
+            expect(await c.waitFor('error')).toMatchObject({
+                error: { code: 'permission_denied' },
+            });
+            expect((await c.closed).code).toBe(1008);
+            expect(costs).toHaveLength(0);
+        });
+
+        it('checks pending text on its own once it passes 64 KiB', async () => {
+            const c = open(`${relayUrl}?auth_token=${user.token}`);
+            await c.waitFor('session.created');
+            const item = (text: string) =>
+                JSON.stringify({
+                    type: 'conversation.item.create',
+                    item: {
+                        type: 'message',
+                        role: 'user',
+                        content: [{ type: 'input_text', text }],
+                    },
+                });
+            c.ws.send(item('a'.repeat(40 * 1024)));
+            c.ws.send(item('b'.repeat(40 * 1024)));
+            c.ws.send(JSON.stringify({ type: 'response.create' }));
+            await vi.waitFor(() => expect(costs).toHaveLength(1));
+            expect(
+                checks.map((check) =>
+                    (check.parameters.messages as { content: string }[]).map(
+                        (m) => m.content[0],
+                    ),
+                ),
+            ).toEqual([['a'], ['b']]);
+            expect(costs[0].completionId).toBe(checks[1].completionId);
+            c.ws.close();
+        });
+    });
+
     it('does not allocate credential limiter buckets for many unique invalid signatures', async () => {
         const before = upstreamRequests.length;
         const auth = vi.spyOn(server.services.auth, 'authenticate');

src/backend/services/realtime/OpenAIRealtimeRelayService.ts

@@ -17,11 +17,12 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import type { IncomingMessage, Server as HttpServer } from 'node:http';
 import type { Duplex } from 'node:stream';
 import express from 'express';
 import type { AnyTokenPayload } from '../auth/types.js';
+import type { EventMap } from '../../clients/event/types.js';
 import WebSocket, { WebSocketServer, type RawData } from 'ws';
 import type { Actor } from '../../core/actor.js';
 import {
@@ -201,6 +202,8 @@ const RECONNECT_NOTICE_INTERVAL_MS = 60_000;
 const TRANSCRIPTION_DONE =
     'conversation.item.input_audio_transcription.completed';
 const METERING_DRIVER = 'openai-realtime';
+// Text awaiting a prompt check; past this it is checked without a response.
+const MAX_PENDING_PROMPT_CHARS = 64 * 1024;
 // Provider organization IDs, as OpenAI puts them in some error messages.
 const ORG_ID = /\borg-[A-Za-z0-9]{8,}/g;
 
@@ -477,6 +480,50 @@ const clientEventRefusal = (event: RealtimeEvent): string | null => {
     return null;
 };
 
+type PromptMessage = { role: string; content: string };
+
+const itemPromptMessages = (item: unknown): PromptMessage[] => {
+    if (!isRecord(item)) return [];
+    if (item.type === 'function_call_output') {
+        return typeof item.output === 'string' && item.output
+            ? [{ role: 'tool', content: item.output }]
+            : [];
+    }
+    if (item.type !== 'message' || !Array.isArray(item.content)) return [];
+    const role = typeof item.role === 'string' ? item.role : 'user';
+    return item.content.flatMap((part) => {
+        if (!isRecord(part)) return [];
+        const text = part.text ?? part.transcript;
+        return typeof text === 'string' && text
+            ? [{ role, content: text }]
+            : [];
+    });
+};
+
+/** The text a client event adds to the model's context, as chat messages. */
+export const promptMessagesOf = (event: unknown): PromptMessage[] => {
+    if (!isRecord(event)) return [];
+    if (event.type === 'conversation.item.create') {
+        return itemPromptMessages(event.item);
+    }
+    const config =
+        event.type === 'session.update'
+            ? event.session
+            : event.type === 'response.create'
+              ? event.response
+              : undefined;
+    if (!isRecord(config)) return [];
+    const messages: PromptMessage[] =
+        typeof config.instructions === 'string' && config.instructions
+            ? [{ role: 'system', content: config.instructions }]
+            : [];
+    if (Array.isArray(config.input)) {
+        for (const item of config.input)
+            messages.push(...itemPromptMessages(item));
+    }
+    return messages;
+};
+
 /** Whichever of two pricings of the same usage costs more. */
 export const costlierRows = (
     a: UsageInput[],
@@ -900,6 +947,14 @@ export class OpenAIRealtimeRelayService extends PuterService {
         let requested = 0;
         // Credit holds of responses whose usage isn't recorded yet.
         const responseHolds = new Map<string, Promise<CreditHold | null>>();
+        // Text sent since the last prompt check, checked when the next
+        // response starts. Each started response maps to the completion id
+        // its check logged, or null if the check refused it.
+        const checkPrompts =
+            this.clients.event.hasListeners('ai.prompt.validate');
+        let promptMessages: PromptMessage[] = [];
+        let promptChars = 0;
+        const responseCompletions = new Map<string, Promise<string | null>>();
         // Committed input items awaiting usage, each with the transcription
         // model in force at commit and the credit held for it.
         const pendingTranscriptions = new Map<
@@ -1062,13 +1117,15 @@ export class OpenAIRealtimeRelayService extends PuterService {
                     identity?.type === 'app-under-user'
                         ? identity.session
                         : undefined;
-                if (!(
-                    sessionUids?.has(sessionUid ?? '') ||
-                    sessionUids?.has(parentUid ?? '') ||
-                    (tokenUid &&
-                        identity?.type === 'access-token' &&
-                        identity.token_uid === tokenUid)
-                ))
+                if (
+                    !(
+                        sessionUids?.has(sessionUid ?? '') ||
+                        sessionUids?.has(parentUid ?? '') ||
+                        (tokenUid &&
+                            identity?.type === 'access-token' &&
+                            identity.token_uid === tokenUid)
+                    )
+                )
                     return;
                 if (token) {
                     kv.del(realtimeAuthKey(token));
@@ -1430,6 +1487,82 @@ export class OpenAIRealtimeRelayService extends PuterService {
             }
         };
 
+        // Runs the host's prompt check on the pending text, which also logs
+        // it. A refusal closes the session.
+        const checkPrompt = async (): Promise<string | null> => {
+            const completionId = randomUUID().replaceAll('-', '').slice(0, 25);
+            const check: EventMap['ai.prompt.validate'] = {
+                username: actor!.user?.username || '',
+                actor,
+                completionId,
+                allow: true,
+                intended_service: METERING_DRIVER,
+                parameters: { model: billingModel, messages: promptMessages },
+            };
+            promptMessages = [];
+            promptChars = 0;
+            try {
+                await this.clients.event.emitAndWait(
+                    'ai.prompt.validate',
+                    check,
+                    {},
+                );
+            } catch (err) {
+                console.warn('[realtime] prompt check failed', err);
+            }
+            if (check.allow !== false) return completionId;
+            reject('permission_denied', 'Prompt blocked by policy');
+            return null;
+        };
+        const notePrompt = (event: RealtimeEvent) => {
+            for (const message of promptMessagesOf(event)) {
+                if (
+                    promptChars + message.content.length >
+                    MAX_PENDING_PROMPT_CHARS
+                )
+                    void checkPrompt();
+                promptMessages.push(message);
+                promptChars += message.content.length;
+            }
+        };
+        // Adds a response's cost to the row its prompt check logged.
+        const logResponseCost = async (
+            id: string,
+            rows: UsageInput[],
+            usage: unknown,
+        ) => {
+            const completion = responseCompletions.get(id);
+            if (!completion) return;
+            responseCompletions.delete(id);
+            const completionId = await completion;
+            if (!completionId) return;
+            const input = { tokens: 0, ucents: 0 };
+            const output = { tokens: 0, ucents: 0 };
+            for (const row of rows) {
+                const side = row.usageType.endsWith('_output') ? output : input;
+                side.tokens += row.usageAmount;
+                side.ucents += row.costOverride ?? 0;
+            }
+            this.clients.event.emit(
+                'ai.prompt.cost-calculated',
+                {
+                    completionId,
+                    username: actor!.user?.username || '',
+                    usage,
+                    input_tokens: input.tokens,
+                    output_tokens: output.tokens,
+                    input_ucents: input.ucents,
+                    output_ucents: output.ucents,
+                    total_ucents: input.ucents + output.ucents,
+                    costs_currency: 'usd-cents',
+                    model_used: billingModel,
+                    service_used: 'openai',
+                    intended_service: METERING_DRIVER,
+                },
+                {},
+            );
+        };
+
         // One transcription item's credit at `name`'s price and cost factor,
         // or null when the account can't cover it. Reservations run one at a
         // time, so a session's own holds don't race each other's balance check.
@@ -1565,6 +1698,8 @@ export class OpenAIRealtimeRelayService extends PuterService {
                     if (typeof id !== 'string') break;
                     inFlightIds.add(id);
                     holdResponse(id);
+                    if (checkPrompts)
+                        responseCompletions.set(id, checkPrompt());
                     if (closed) {
                         upstream?.send(
                             JSON.stringify({
@@ -1575,18 +1710,15 @@ export class OpenAIRealtimeRelayService extends PuterService {
                     }
                     break;
                 }
-                case 'response.done':
+                case 'response.done': {
                     inFlight = Math.max(0, inFlight - 1);
+                    const usage = event.response?.usage ?? undefined;
+                    const rows = realtimeUsageRows(billingModel, usage);
+                    meter(rows, takeHold(event.response?.id));
                     if (typeof event.response?.id === 'string') {
                         inFlightIds.delete(event.response.id);
+                        void logResponseCost(event.response.id, rows, usage);
                     }
-                    meter(
-                        realtimeUsageRows(
-                            billingModel,
-                            event.response?.usage ?? undefined,
-                        ),
-                        takeHold(event.response?.id),
-                    );
                     if (inFlight === 0) {
                         onIdle?.();
                         if (
@@ -1598,6 +1730,7 @@ export class OpenAIRealtimeRelayService extends PuterService {
                             endUpstream();
                     }
                     break;
+                }
                 case 'input_audio_buffer.speech_started': {
                     // Detected speech is committed when it stops, from where
                     // the provider says it began.
@@ -1839,6 +1972,7 @@ export class OpenAIRealtimeRelayService extends PuterService {
                 pending.shift();
                 pendingBytes -= (next.data as Buffer).length;
                 if (event.type === 'response.create') requested++;
+                if (checkPrompts) notePrompt(event);
                 sendUpstream(next.data, next.isBinary);
             }
             return undefined;

src/backend/services/realtime/README.md

@@ -105,11 +105,13 @@ excludes outstanding holds and accepts fractional positive credit. Admission of
 new billable work continues to use the atomic hold path, which includes every
 outstanding reservation.
 
-Text, transcripts and raw audio are forwarded without new content logging.
-The relay does not invoke `ai.prompt.validate`. A realtime adapter needs the host
-listeners' chat payload and denial contracts before that hook can safely apply
-to instructions and conversation text. Raw audio and generated transcripts need
-separate policy decisions.
+When the host listens for `ai.prompt.validate`, each response that starts runs
+it on the text the client sent since the previous check: session and response
+instructions, message text and transcripts, and function call output, as chat
+messages. The response's cost follows as `ai.prompt.cost-calculated` under the
+same completion id. A refusal closes the session with `permission_denied`; the
+response may already be streaming by then. Pending text past 64 KiB is checked
+on its own. Audio is not checked.
 
 Credential checks run in batches of at most 16 with no overlapping sweeps.
 Session and access-token revocation events close affected sockets and invalidate

src/backend/services/socket/SocketService.ts

@@ -699,7 +699,8 @@ export class SocketService extends PuterService {
             // `{ auth: { ... } }`, not the query string. puter-js uses
             // `io(url, { auth: { auth_token } })`.
             const handshakeAuth = socket.handshake.auth as
-                Record<string, unknown> | undefined;
+                | Record<string, unknown>
+                | undefined;
             const tokenRaw =
                 typeof handshakeAuth?.auth_token === 'string'
                     ? handshakeAuth.auth_token
@@ -1085,6 +1086,7 @@ export class SocketService extends PuterService {
             // them. Off unless events are enabled, in which case the verbs
             // answer with `events_disabled` rather than going unanswered.
             this.services.events.attachSocket(socket, actor);
+            this.services.notification.attachSocket(socket, actor);
 
             // Everything below is the desktop session's own traffic: two verbs
             // that reach the user's other tabs, and a connect announcement
@@ -1221,7 +1223,8 @@ export class SocketService extends PuterService {
                 // their next poll of /cache/last-change-timestamp.
                 const originalSocketId = (
                     data.response as
-                        { original_client_socket_id?: string } | undefined
+                        | { original_client_socket_id?: string }
+                        | undefined
                 )?.original_client_socket_id;
                 await this.send({ room: userId }, 'cache.updated', {
                     timestamp,
@@ -1235,7 +1238,9 @@ export class SocketService extends PuterService {
     #handleUploadProgress(data: UploadProgressPayload): void {
         const meta = data.meta ?? {};
         const userId = (meta.user_id ?? meta.userId) as
-            number | string | undefined;
+            | number
+            | string
+            | undefined;
         if (!userId) {
             console.warn('[socket] upload-progress missing user_id', { meta });
             return;

src/backend/types.ts

@@ -256,12 +256,7 @@ export interface IPreludeConfig {
      * an RCS agent provisioned in the Prelude account to actually use RCS.
      */
     preferredChannel?:
-        | 'sms'
-        | 'rcs'
-        | 'whatsapp'
-        | 'viber'
-        | 'zalo'
-        | 'telegram';
+        'sms' | 'rcs' | 'whatsapp' | 'viber' | 'zalo' | 'telegram';
 }
 
 /**
@@ -1106,7 +1101,10 @@ interface IConfigOptional {
     builtin_apps: Record<string, string>;
     /** Force the bundled GUI even in dev. Default: false. */
     use_bundled_gui: boolean;
-    /** Override the GUI bundle JS path. Default: `/dist/bundle.min.js`. */
+    /**
+     * Override the GUI bundle JS path. Default: `/dist/bundle.min.js`. The app
+     * browser embed loads `apps-embed.min.js` from the same directory.
+     */
     gui_bundle: string;
     /** Override the GUI CSS path when bundled. Default: `/dist/bundle.min.css`. */
     gui_css: string;
@@ -1393,7 +1391,8 @@ export interface ServerDrainInfo {
 }
 
 export interface WithCostsReporting extends WithLifecycle {
-    getReportedCosts?: () => // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getReportedCosts?: () =>
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         | Promise<Record<string, any>[]>
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         | Record<string, any>[];

src/docs/src/Notifications/disable.md

@@ -6,7 +6,7 @@ platforms: [websites, apps]
 
 Turns push notifications off for your app. Notifications still reach your app live while it's open.
 
-On a website, it ends this browser's push subscription for your app and removes it from Puter. Only the subscription Puter made is removed, so a subscription another push service made on your site stays as it is. Pages of your site in this browser, including ones open in other tabs, stop showing notifications themselves while they're in the background, so a notification goes out as a push to the user's other browsers instead. The browser's permission isn't changed, so a later [`enable()`](/Notifications/enable/) turns pushes back on without a prompt.
+On a website, it ends this browser's push subscription for your app and removes it from Puter. Only the subscription Puter made is removed, so a subscription another push service made on your site stays as it is. The browser's permission isn't changed, so a later [`enable()`](/Notifications/enable/) turns pushes back on without a prompt.
 
 The choice sticks. Page loads don't turn pushes back on, because [`onPush()`](/Notifications/onPush/) only keeps a subscription current after [`enable()`](/Notifications/enable/). Call [`enable()`](/Notifications/enable/) from a click to turn them on again.
 

src/docs/src/Notifications/notify.md

@@ -4,7 +4,7 @@ description: Send a notification from your app to its user, or to the other side
 platforms: [websites, apps]
 ---
 
-Sends a notification to the user your app runs for, or with `to` to the other side of a [key-value share](/KV/share/). It goes to your app, not the Puter desktop's notifications panel. Every open page of your app gets it live, on any of the user's devices, through [`onNotification()`](/Notifications/onNotification/) and [`onPush()`](/Notifications/onPush/). When no open page shows it to the user within 5 seconds, it also goes out as a push to the browsers where the user [turned pushes on](/Notifications/enable/) for your app. [When a notification is pushed](/Notifications/push/#when-a-notification-is-pushed) has the exact rule.
+Sends a notification to the user your app runs for, or with `to` to the other side of a [key-value share](/KV/share/). It goes to your app, not the Puter desktop's notifications panel. Every open page of your app gets it live, on any of the user's devices, through [`onNotification()`](/Notifications/onNotification/) and [`onPush()`](/Notifications/onPush/). When no open page is visible and focused as it arrives, it also goes out as a push to the browsers where the user [turned pushes on](/Notifications/enable/) for your app. [When a notification is pushed](/Notifications/push/#when-a-notification-is-pushed) has the exact rule.
 
 Only an app can send notifications, meaning an app running on Puter or a website using Puter.js. Every notification carries your app's name. On a website with nobody signed in, the call asks the user to sign in first, as other Puter.js calls do.
 

src/docs/src/Notifications/on.md

@@ -10,7 +10,7 @@ For `click`, the handler can open the screen the notification is about.
 
 Clicks reach your app in two ways:
 
-- **On a website**, from a tap on a push, or on a notification a page of your site showed itself. When a page of your site is open, the tap focuses it and calls its `click` handlers. A page without a `click` handler goes to the notification's `url` instead, which is the `url` your [`onPush()`](/Notifications/onPush/) handler returned, or else the notification's `target`. When no page is open, the tap opens that `url`, and the new page's first `click` handler gets the click.
+- **On a website**, from a tap on a push. When a page of your site is open, the tap focuses it and calls its `click` handlers. A page without a `click` handler goes to the notification's `url` instead, which is the `url` your [`onPush()`](/Notifications/onPush/) handler returned, or else the notification's `target`. When no page is open, the tap opens that `url`, and the new page's first `click` handler gets the click.
 - **Inside the Puter desktop**, from a tap on a push that Puter shows. Puter opens your app, or brings it to the front, and delivers the click.
 
 A click that arrives before your first `click` handler is added, such as the one that opened your app, goes to that first handler, once. Handlers added after it don't get it, so add your handler early during startup. On a website, a page a tap opened drops the click when no `click` handler is added within 10 seconds of the page loading.

src/docs/src/Notifications/onPush.md

@@ -6,7 +6,7 @@ platforms: [websites, apps]
 
 Handles the notifications your app sends with `channel: key` in [`notify()`](/Notifications/notify/). While a page of your app is open with this handler, the handler runs in the page as each one arrives. On a website, it also runs in your service worker when a push arrives, and what it returns decides what the push shows.
 
-A page with a handler tells Puter that it received each notification, before your handler runs. When the page is visible and focused, nothing is pushed. When it's hidden or its window isn't focused, a page of your website shows the notification itself, unless another window of your site is focused. It shows the handler's result, or the notification's own title and text when no handler matches the notification's `channel`. It does this only after the user turned pushes on in this browser with [`enable()`](/Notifications/enable/). Inside the Puter desktop, the page doesn't show it, and it goes out as a push through Puter instead. [When a notification is pushed](/Notifications/push/#when-a-notification-is-pushed) has the full rule.
+A page with a handler tells Puter that it received each notification, before your handler runs. When the page is visible and focused, nothing is pushed, and your handler is the only thing that runs. When it's hidden or its window isn't focused, the notification goes out as a push to every browser where the user turned pushes on, this one included. The page doesn't show a notification itself. [When a notification is pushed](/Notifications/push/#when-a-notification-is-pushed) has the full rule.
 
 The user turns pushes on once per browser with [`enable()`](/Notifications/enable/). After that, each page load's [`onPush()`](/Notifications/onPush/) call keeps this browser's subscription current without asking again. Different keys share that one subscription. After [`disable()`](/Notifications/disable/), after the user turns your app off or removes this browser in Puter, or after [`puter.auth.signOut()`](/Auth/signOut/), page loads don't subscribe again until your page calls [`enable()`](/Notifications/enable/) from a click.
 
@@ -51,7 +51,7 @@ A [sensitive](/Notifications/notify/#parameters) notification shows only your ap
 
 #### `options` (Object) (optional)
 - `serviceWorker` (String): The path of the worker that imports `push-sw.js`. Defaults to `/puter-sw.js`.
-- `onError` (Function): Called with `{ message, code }` when the handler throws in the page or runs past 5 seconds there (`push_handler_timeout`), when the live listener stops, when keeping the subscription current fails, or when the confirmation push after [`enable()`](/Notifications/enable/) doesn't arrive within 30 seconds (`push_verification_timeout`). When the handler fails, the notification shows its own title and text. Errors that [`enable()`](/Notifications/enable/) rejects with, such as `push_unavailable`, `push_disabled`, `push_revoked` and `too_many_requests`, aren't reported here. Neither is a browser the user removed in Puter, since [`enable()`](/Notifications/enable/) turns pushes back on there. Without `onError`, errors go to the console.
+- `onError` (Function): Called with `{ message, code }` when the handler throws in the page or runs past 5 seconds there (`push_handler_timeout`), when the live listener stops, when keeping the subscription current fails, or when the confirmation push after [`enable()`](/Notifications/enable/) doesn't arrive within 30 seconds (`push_verification_timeout`). Errors that [`enable()`](/Notifications/enable/) rejects with, such as `push_unavailable`, `push_disabled`, `push_revoked` and `too_many_requests`, aren't reported here. Neither is a browser the user removed in Puter, since [`enable()`](/Notifications/enable/) turns pushes back on there. Without `onError`, errors go to the console.
 
 ## Handler limits
 

src/docs/src/Notifications/push.md

@@ -10,19 +10,9 @@ A website on its own domain needs three steps, and an app inside the Puter deskt
 
 ## When a notification is pushed
 
-Every open page of your app gets each notification live, on any of the user's devices, through [`onNotification()`](/Notifications/onNotification/) and [`onPush()`](/Notifications/onPush/). Puter then asks those pages whether they received it. If a page answers within 5 seconds that it's visible and focused, or that it shows the notification itself, nothing is pushed. Otherwise Puter pushes it. A page answers only while it has an [`onNotification()`](/Notifications/onNotification/) or [`onPush()`](/Notifications/onPush/) listener.
+Every open page of your app gets each notification live, on any of the user's devices, through [`onNotification()`](/Notifications/onNotification/) and [`onPush()`](/Notifications/onPush/). A page that's visible and focused when the notification arrives tells Puter, and nothing is pushed. Otherwise Puter pushes it to every browser where the user turned pushes on. While a page of your app is open, the push can take up to 5 seconds to go out. A page tells Puter only while it has an [`onNotification()`](/Notifications/onNotification/) or [`onPush()`](/Notifications/onPush/) listener.
 
-A page of your website shows the notification itself when all of these are true:
-
-- The page is hidden, or its window isn't focused.
-- It has an [`onPush()`](/Notifications/onPush/) handler.
-- The user turned pushes on in this browser with [`enable()`](/Notifications/enable/), and hasn't turned them off with [`disable()`](/Notifications/disable/).
-- The user allowed notifications for your site in this browser.
-- No other window of your site is focused.
-
-It shows what the handler returns, or the notification's own title and text when no handler matches the notification's `channel`. Inside the Puter desktop, a page doesn't show notifications itself, so a notification goes out as a push whenever your app's window isn't focused.
-
-So a push goes out when no page of your app is open, or when the open pages are in the background and can't show the notification themselves. A page that loads an older version of Puter.js, such as one bundled from npm, holds the push back while it's visible. A page with a version from before Puter asked pages whether they received a notification holds it back whenever it's open.
+So a push goes out when no page of your app is open, or when every open page is hidden or in a window that isn't focused. Pages never show notifications themselves, so a page in the background gets the push like the user's other browsers do. Inside the Puter desktop, a notification goes out as a push whenever your app's window isn't focused. A page that loads an older version of Puter.js, such as one bundled from npm, holds the push back while it's visible.
 
 ## Where a push goes
 
@@ -168,7 +158,7 @@ To notify another user, share data with them with `notify: true` and send throug
 
 ## When the user taps
 
-On a website, a tap on a push, or on a notification a page of your site showed itself, focuses an open page of your site and calls its [`on('click')`](/Notifications/on/) handlers. With no page open, it opens the handler's `url`, or else the notification's `target`, and the new page's first [`on('click')`](/Notifications/on/) handler gets the click. A tap reaches one page, once: when an open page doesn't answer within about half a second, the tap opens its URL instead, and the slow page doesn't get it, unless that page is already at the tap's URL. If that page wasn't loaded through your worker, such as one opened before the worker was installed, the URL opens in a new tab. Inside the Puter desktop, a tap opens your app and hands the click to [`on('click')`](/Notifications/on/).
+On a website, a tap on a push focuses an open page of your site and calls its [`on('click')`](/Notifications/on/) handlers. With no page open, it opens the handler's `url`, or else the notification's `target`, and the new page's first [`on('click')`](/Notifications/on/) handler gets the click. A tap reaches one page, once: when an open page doesn't answer within about half a second, the tap opens its URL instead, and the slow page doesn't get it, unless that page is already at the tap's URL. If that page wasn't loaded through your worker, such as one opened before the worker was installed, the URL opens in a new tab. Inside the Puter desktop, a tap opens your app and hands the click to [`on('click')`](/Notifications/on/).
 
 A push can also carry up to two buttons, which your [`onPush()`](/Notifications/onPush/) handler returns as `actions`. The pressed button's id reaches [`on('click')`](/Notifications/on/) as `action`. [Add Buttons to Push Notifications](/recipes/add-buttons-to-push-notifications/) shows how.
 
@@ -180,13 +170,13 @@ When the user reads a notification in your app, call [`dismiss()`](/Notification
 
 A notification with a `group` replaces your earlier one in the same group, on the device and in your app, and alerts the user again. A group can name a chat, a thread or a person, such as `dm:[email protected]`. [`notify()`](/Notifications/notify/#groups) has the rule.
 
-With `sensitive: true`, pushes and the notification a page shows itself name only your app instead of showing the title and text. [`onNotification()`](/Notifications/onNotification/) still gets the whole notification. [`notify()`](/Notifications/notify/#parameters) says what else a sensitive push leaves out.
+With `sensitive: true`, pushes name only your app instead of showing the title and text. [`onNotification()`](/Notifications/onNotification/) still gets the whole notification. [`notify()`](/Notifications/notify/#parameters) says what else a sensitive push leaves out.
 
 ## A minimal page
 
-To try it, serve the page below from a site that has `/puter-sw.js`. It registers the handler, turns pushes on from a click, and sends a notification 5 seconds after you click Send. Switch to another tab during those 5 seconds. The page is then in the background, so it shows the notification itself and nothing is pushed.
+To try it, serve the page below from a site that has `/puter-sw.js`. It registers the handler, turns pushes on from a click, and sends a notification 5 seconds after you click Send. Switch to another tab during those 5 seconds. The page is then in the background, so the notification goes out as a push and your worker shows it. If you stay on the page, it gets the notification live and nothing is pushed.
 
-A real push goes out only when no page of your site can show the notification. To see one, turn pushes on, close every tab of your site, and send from somewhere else, such as a [Puter Worker](/Workers/) that runs as your app or an [events handler](/Events/handlers/).
+To reach the user with every tab of your site closed, send from somewhere else, such as a [Puter Worker](/Workers/) that runs as your app or an [events handler](/Events/handlers/).
 
 ```html
 <html>
@@ -347,7 +337,7 @@ The browser can be allowed to show notifications while the operating system hide
 | The `onError` of [`onPush()`](/Notifications/onPush/) gets `push_verification_timeout` | The worker doesn't import `push-sw.js`, or the confirmation push didn't arrive within 30 seconds. The next page load tries again. |
 | A push shows the plain title and text, not your handler's result | This browser hasn't run [`onPush()`](/Notifications/onPush/) for that `channel` yet, or the handler threw, took over 5 seconds, or used an outside variable. Check the worker's console. |
 | Pushes stop until the user opens your site again | The browser replaced its push subscription for your site, as browsers sometimes do. Your service worker keeps the new one, and the next page load that calls [`onPush()`](/Notifications/onPush/) registers it with Puter. Pushes sent before that don't arrive. |
-| No push while your site is open in a tab | The open page received the notification live. It shows one only when it's hidden or its window isn't focused. |
+| No push while your site is open in a tab | The open page received the notification live while it was visible and focused. |
 | No push at all | The browser isn't running, the operating system hides its notifications ([above](#operating-system-settings)), the user reached the [push limit](/rate-limits-and-quotas/#notifications) for your app, or the user has no usage credit left. |
 
 ## Push delivery

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

@@ -509,7 +509,7 @@ The notification limits count notifications written. A notification that replace
 
 Notifications one side of a KV share sends the other through its handle count against the recipient's `app.message` limits, and also against the limit for that sender, recipient and app, across all their shares in that app. Over either one, the call fails with the same error, so the sender can't tell which limit it hit. A call that the recipient's limits refuse still counts against the share limit. The pushes count against the recipient's push limits and are billed to the recipient.
 
-A notification goes out as a push only when no open page of the app answers within 5 seconds that it's visible and focused, or that it shows the notification itself. The push limits count only pushes sent, and a replacement that goes out as a push counts like any other. An app gets the lower push limits while it's younger than 30 days or not approved for listing. A website using Puter.js starts out unlisted, so it gets the lower limits. Over a push limit, the call still succeeds and the notification still reaches the app live, but it isn't pushed.
+A notification goes out as a push only when no open page of the app is visible and focused when it arrives. The push limits count only pushes sent, and a replacement that goes out as a push counts like any other. An app gets the lower push limits while it's younger than 30 days or not approved for listing. A website using Puter.js starts out unlisted, so it gets the lower limits. Over a push limit, the call still succeeds and the notification still reaches the app live, but it isn't pushed.
 
 A push carries about 4 KB, and one that doesn't fit has its text shortened. Turning pushes on in another browser past the app's browser limit removes that app's least recently seen one. A browser is also removed when its push service answers `404` or `410`, after 10 failed sends and over 3 days without receiving a push or renewing its registration, or after 60 days without either. A page that calls [`onPush()`](/Notifications/onPush/) renews it on load.
 

src/docs/src/recipes/notify-chat-members-of-new-messages.md

@@ -104,10 +104,10 @@ puter.notifications.on('click', ({ data }) => {
 
 Here `openRoomById()` is your app's own function that shows a room.
 
-While the chat is open, the notification reaches this handler in the page, and
-the page shows it only when its tab is hidden or its window isn't focused. The
-message itself arrives through the room's `watch()`. While the chat is closed,
-the same handler runs in your service worker to decide what the push shows.
+While the chat is open, the notification reaches this handler in the page. When
+the tab is visible and focused, nothing is pushed. Otherwise the notification
+goes out as a push, and the same handler runs in your service worker to decide
+what it shows. The message itself arrives through the room's `watch()`.
 
 ## Turn Notifications On
 

src/docs/src/recipes/reach-a-user-when-your-app-is-closed.md

@@ -89,7 +89,7 @@ async function sendMessageNotification () {
 document.getElementById('send').addEventListener('click', sendMessageNotification);
 ```
 
-The `group` makes a newer notification for the same chat replace this one, instead of adding another. Every open page gets the notification live, and a page that's visible and focused, or shows the notification itself, holds the push back. So a notification sent from the page the user is looking at isn't pushed. [When a notification is pushed](/Notifications/push/#when-a-notification-is-pushed) has the full rule. To send while the user's tabs are closed, call [`notify()`](/Notifications/notify/) from somewhere that keeps running, such as a [Puter Worker](/Workers/) with [`user.puter.notifications.notify()`](/Notifications/notify/), or an [events handler](/Events/handlers/) with [`user.notifications.notify()`](/Notifications/notify/). [Push notifications for your app](/Notifications/push/#sending-a-notification) has the details, and [Run Code in the Background](/recipes/run-code-in-the-background/) sets up an events handler. To notify another user, see [Notify Chat Members of New Messages](/recipes/notify-chat-members-of-new-messages/).
+The `group` makes a newer notification for the same chat replace this one, instead of adding another. Every open page gets the notification live, and a page that's visible and focused holds the push back. So a notification sent from the page the user is looking at isn't pushed. [When a notification is pushed](/Notifications/push/#when-a-notification-is-pushed) has the full rule. To send while the user's tabs are closed, call [`notify()`](/Notifications/notify/) from somewhere that keeps running, such as a [Puter Worker](/Workers/) with [`user.puter.notifications.notify()`](/Notifications/notify/), or an [events handler](/Events/handlers/) with [`user.notifications.notify()`](/Notifications/notify/). [Push notifications for your app](/Notifications/push/#sending-a-notification) has the details, and [Run Code in the Background](/recipes/run-code-in-the-background/) sets up an events handler. To notify another user, see [Notify Chat Members of New Messages](/recipes/notify-chat-members-of-new-messages/).
 
 A website using Puter.js starts out unlisted, so it gets the lower push limits for new apps. A notification over a limit still reaches your app live. The numbers are on [Rate Limits and Quotas](/rate-limits-and-quotas/#notifications).
 

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

@@ -0,0 +1,226 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { chromium } from '@playwright/test';
+import express from 'express';
+import webpack from 'webpack';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let browser;
+let server;
+let directory;
+let origin;
+let port;
+const requests = [];
+const guiRoot = fileURLToPath(new URL('../../../', import.meta.url));
+const sessionToken = 'app-browser-test-session';
+const appRows = Array.from({ length: 105 }, (_, i) => ({
+    name: `app-${i}`, title: `App ${i}`, icon: null,
+}));
+const kv = {
+    dashboard_apps_order: JSON.stringify(['app-104', 'app-1', 'app-2']),
+    dashboard_app_groups: JSON.stringify([{ id: 'work', name: 'Work', apps: ['app-1', 'app-2'] }]),
+    dashboard_removed_apps: JSON.stringify(['removed']),
+};
+// What puter.apps.get returns for an app; set per test.
+let appRead = name => ({ uid: `uid-${name}`, name, index_url: `http://${name}.puter.localhost:${port}/index` });
+
+beforeAll(async () => {
+    directory = await mkdtemp(path.join(tmpdir(), 'puter-app-browser-'));
+    await new Promise((resolve, reject) => {
+        const compiler = webpack({
+            mode: 'development',
+            entry: { 'apps-embed': path.join(guiRoot, 'src/appsEmbed.js') },
+            output: { path: directory, filename: '[name].min.js' },
+            module: { rules: [{ test: /jquery-3\.6\.1\.min\.js$/, type: 'javascript/auto' }] },
+        });
+        compiler.run((error, stats) => compiler.close(closeError => {
+            if ( error || closeError ) return reject(error || closeError);
+            if ( stats.hasErrors() ) return reject(new Error(stats.toString()));
+            resolve();
+        }));
+    });
+    const app = express();
+    app.use(express.json({ type: ['application/json', 'text/plain'] }));
+    app.use((req, res, next) => {
+        requests.push({ path: req.path, body: req.body, auth: req.headers.authorization });
+        next();
+    });
+    app.use('/dist', express.static(directory));
+    app.use('/css', express.static(path.join(guiRoot, 'src/css')));
+    app.get('/sdk.js', (_req, res) => res.sendFile(path.resolve(guiRoot, '../puter-js/dist/puter.js')));
+    app.get('/installedApps', (req, res) => {
+        if ( req.headers.authorization !== `Bearer ${sessionToken}` ) return res.sendStatus(401);
+        const offset = (Number(req.query.page) - 1) * 100;
+        res.json(appRows.slice(offset, offset + 100));
+    });
+    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) => {
+        if ( req.body.auth_token !== sessionToken ) return res.sendStatus(401);
+        if ( req.body.interface === 'puter-apps' ) {
+            return res.json({ success: true, result: appRead(req.body.args.id.name) });
+        }
+        res.json({ success: true, result: kv[req.body.args?.key] ?? null });
+    });
+    app.post('/auth/get-user-app-token', (req, res) => {
+        if ( req.headers.authorization !== `Bearer ${sessionToken}` ) return res.sendStatus(401);
+        res.json({ token: `token-for-${req.body.app_uid}` });
+    });
+    app.post('/rao', (_req, res) => res.json({}));
+    app.get('/app/:name', (_req, res) => res.send('<title>Opened app</title>'));
+    // An app's own page, which signs in with the token the embed hands it.
+    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>
+    </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">
+            <link rel="stylesheet" href="/css/normalize.css"><link rel="stylesheet" href="/css/dashboard.css">
+            <link rel="stylesheet" href="/css/apps-embed.css"></head><body>
+            <main id="app-browser" class="dashboard"></main>
+            <script type="application/json" id="app-browser-config">${JSON.stringify({ apiOrigin: origin, sdkUrl: '/sdk.js' })}</script>
+            <script defer src="/dist/apps-embed.min.js"></script></body></html>`);
+    });
+    server = await new Promise(resolve => {
+        const listener = app.listen(0, '127.0.0.1', () => resolve(listener));
+    });
+    port = server.address().port;
+    origin = `http://puter.localhost:${port}`;
+    browser = await chromium.launch();
+}, 60000);
+
+afterAll(async () => {
+    await browser?.close();
+    if ( server ) await new Promise(resolve => server.close(resolve));
+    if ( directory ) await rm(directory, { recursive: true, force: true });
+});
+
+describe('embedded app browser', () => {
+    it.each([{ width: 1100, height: 720 }, { width: 390, height: 700 }])(
+        'browses and launches apps across subdomains at $width px', async viewport => {
+            const context = await browser.newContext({ viewport, storageState: {
+                cookies: [], origins: [{ origin, localStorage: [
+                    { name: 'auth_token_v2', value: sessionToken },
+                    { name: 'user_preferences', value: viewport.width < 500 ? '{invalid' : '{"language":"en"}' },
+                ] }],
+            } });
+            const page = await context.newPage();
+            page.setDefaultTimeout(6000);
+            const errors = [];
+            page.on('pageerror', error => errors.push(error.message));
+            requests.length = 0;
+            try {
+                const parentUrl = `http://spreadsheet.puter.localhost:${port}/host`;
+                await page.goto(parentUrl);
+                const frame = page.frameLocator('iframe');
+                await frame.locator('.myapps-group-tile').waitFor();
+                expect(await frame.locator('.myapps-reorder-btn, .myapps-add-tile, .myapps-tile-remove').count()).toBe(0);
+                expect(await frame.locator('.myapps-search-wrap').evaluate(el => getComputedStyle(el).paddingTop)).toBe('16px');
+                expect(await frame.locator('.myapps-tile').first().getAttribute('data-app-name')).toBe('app-104');
+                expect(await frame.locator('[data-app-name="removed"]').count()).toBe(0);
+                expect(requests.filter(req => req.path === '/installedApps')).toHaveLength(2);
+                await frame.locator('.myapps-group-tile').click();
+                const name = frame.locator('.myapps-group-name');
+                expect(await name.getAttribute('readonly')).not.toBeNull();
+                await frame.locator('.myapps-group-panel .myapps-tile').first().waitFor();
+                await frame.locator('.myapps-group-open').waitFor();
+                await page.screenshot({ path: path.join(tmpdir(), `puter-app-browser-${viewport.width}.png`), animations: 'disabled' });
+                const panel = await frame.locator('.myapps-group-panel').boundingBox();
+                expect(panel.width).toBeGreaterThan(150);
+                expect(panel.x).toBeGreaterThanOrEqual(0);
+                expect(panel.x + panel.width).toBeLessThanOrEqual(viewport.width + 1);
+                await frame.locator('.myapps-group-panel .myapps-tile').first().press('Escape');
+                await frame.locator('.myapps-group-overlay').waitFor({ state: 'detached' });
+                await frame.locator('.myapps-search').fill('App 104');
+                expect(await frame.locator('.myapps-tile').count()).toBe(1);
+                const popupPromise = context.waitForEvent('page');
+                await frame.locator('.myapps-tile').click();
+                const popup = await popupPromise;
+                await popup.waitForURL(/\/index\?/);
+                const appUrl = new URL(popup.url());
+                expect(appUrl.origin).toBe(`http://app-104.puter.localhost:${port}`);
+                expect(appUrl.searchParams.get('puter.app.name')).toBe('app-104');
+                expect(appUrl.searchParams.get('puter.origin')).toBe(origin);
+                expect(appUrl.searchParams.has('puter.auth.token')).toBe(false);
+                expect(appUrl.searchParams.get('utm_campaign')).toBe('app_browser_embed');
+                expect(page.url()).toBe(parentUrl);
+                await popup.waitForFunction(() => window.puter?.authToken === 'token-for-uid-app-104');
+                expect(await popup.evaluate(() => window.opener)).toBeNull();
+                // The app's own SDK reports its open too; this is the embed's.
+                const embedOpens = requests.filter(req => req.path === '/rao' && req.auth === `Bearer ${sessionToken}`);
+                expect(embedOpens.map(req => req.body.app_uid)).toEqual(['uid-app-104']);
+                expect(requests.filter(req => req.path === '/drivers/call' && req.body.interface !== 'puter-apps')
+                    .every(req => req.body.method === 'get')).toBe(true);
+                expect(errors).toEqual([]);
+            } finally {
+                await context.close();
+            }
+        }, 30000,
+    );
+
+    it('opens the desktop landing, cut off from the embed, for an app it can\'t launch itself', async () => {
+        const context = await browser.newContext({ storageState: {
+            cookies: [], origins: [{ origin, localStorage: [{ name: 'auth_token_v2', value: sessionToken }] }],
+        } });
+        const previousRead = appRead;
+        appRead = name => ({ ...previousRead(name), privateAccess: { hasAccess: false } });
+        try {
+            const page = await context.newPage();
+            page.setDefaultTimeout(6000);
+            await page.goto(`${origin}/embed/apps`);
+            await page.locator('.myapps-search').fill('App 104');
+            const popupPromise = context.waitForEvent('page');
+            await page.locator('.myapps-tile').click();
+            const popup = await popupPromise;
+            await popup.waitForURL(`${origin}/app/app-104`);
+            expect(await popup.evaluate(() => window.opener)).toBeNull();
+        } finally {
+            appRead = previousRead;
+            await context.close();
+        }
+    });
+
+    it('does not start login or load the SDK when the existing session is absent', async () => {
+        const page = await browser.newPage();
+        requests.length = 0;
+        try {
+            await page.goto(`${origin}/embed/apps`);
+            await page.getByRole('status').waitFor();
+            expect(requests.some(req => ['/sdk.js', '/installedApps', '/login', '/signup'].includes(req.path))).toBe(false);
+        } finally {
+            await page.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 }] }],
+        } });
+        try {
+            const page = await context.newPage();
+            await page.route('**/sdk.js', route => route.abort());
+            await page.goto(`${origin}/embed/apps`);
+            await page.getByRole('status').waitFor();
+            expect(await page.getByRole('status').textContent()).toContain('Apps are unavailable');
+        } finally {
+            await context.close();
+        }
+    });
+
+    it('blocks a parent outside the deployment domain', async () => {
+        const page = await browser.newPage();
+        requests.length = 0;
+        try {
+            await page.goto(`http://outside.localhost:${port}/host`);
+            expect(requests.some(req => req.path === '/embed/apps')).toBe(true);
+            expect(requests.some(req => req.path === '/dist/apps-embed.min.js')).toBe(false);
+        } finally {
+            await page.close();
+        }
+    });
+});

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

@@ -0,0 +1,185 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import jQuery from '../../lib/jquery-3.6.1/jquery-3.6.1.min.js';
+import { encode } from 'html-entities';
+import { createAppBrowser } from './AppBrowser.js';
+import { APPS_ORDER_KV_KEY } from './appOrder.js';
+import { APP_GROUPS_KV_KEY } from './appGroups.js';
+import { REMOVED_APPS_KV_KEY } from './removedApps.js';
+
+let installed;
+let recommended;
+let saved;
+let browser;
+let $root;
+const onLaunch = vi.fn();
+
+beforeEach(() => {
+    globalThis.$ = globalThis.jQuery = jQuery;
+    globalThis.html_encode = value => encode(String(value ?? ''));
+    globalThis.i18n = key => key;
+    window.icons = {};
+    window.api_origin = 'https://api.test.local';
+    window.auth_token = 'test-session';
+    window.matchMedia = () => ({ matches: false });
+    globalThis.ResizeObserver = class { observe () {} disconnect () {} };
+    HTMLElement.prototype.scrollTo = function ({ left }) { this.scrollLeft = left; };
+    installed = [
+        { name: 'sheet', title: 'Spreadsheet' },
+        { name: 'notes', title: 'Notes' },
+        { name: 'editor', title: 'Editor' },
+    ];
+    recommended = [{ name: 'camera', title: 'Camera' }];
+    saved = new Map([
+        [APPS_ORDER_KV_KEY, JSON.stringify(['notes', 'sheet', 'camera', 'editor'])],
+        [APP_GROUPS_KV_KEY, JSON.stringify([{ id: 'work', name: 'Work', apps: ['notes', 'sheet'] }])],
+        [REMOVED_APPS_KV_KEY, JSON.stringify(['camera'])],
+    ]);
+    vi.stubGlobal('fetch', vi.fn(async url => ({
+        json: async () => String(url).includes('/installedApps') ? installed : { recommended },
+    })));
+    vi.stubGlobal('puter', {
+        authToken: 'test-session',
+        kv: { get: async key => saved.get(key), set: vi.fn() },
+    });
+    onLaunch.mockClear();
+});
+
+afterEach(() => {
+    browser?._resizeObserver?.disconnect();
+    $(document).off('keydown.myapps-keyboard');
+    $(document).off('keydown.myapps-group');
+    document.body.innerHTML = '';
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+async function mount (options = {}) {
+    browser = createAppBrowser({ editable: false, onLaunch, ...options });
+    document.body.innerHTML = `<main><section class="dashboard-section-apps active">${browser.html()}</section></main>`;
+    $root = $('main');
+    const container = document.querySelector('.myapps-container');
+    Object.defineProperties(container, {
+        clientWidth: { value: 600 },
+        clientHeight: { value: 400 },
+    });
+    browser.init($root);
+    await browser.loadApps($root);
+}
+
+describe('shared app browser', () => {
+    it('uses saved order, folders, and removed recommendations in read-only mode', async () => {
+        await mount();
+        expect(browser._apps.map(app => app.name)).toEqual(['notes', 'sheet', 'editor']);
+        expect($('.myapps-group-tile')).toHaveLength(1);
+        expect($('.myapps-reorder-btn, .myapps-add-tile')).toHaveLength(0);
+        expect(fetch.mock.calls[0][1].headers.Authorization).toBe('Bearer test-session');
+    });
+
+    it('searches inside folders and delegates launches without desktop actions', async () => {
+        await mount();
+        $('.myapps-search').val('spread').trigger('input');
+        expect($('.myapps-tile')).toHaveLength(1);
+        $('.myapps-tile').trigger('click');
+        expect(onLaunch).toHaveBeenCalledWith({ appName: 'sheet', targetLink: '' });
+        expect($('.window')).toHaveLength(0);
+        $('.myapps-search').val('missing').trigger('input');
+        expect($('.myapps-empty').text()).toBe('no_apps_match');
+        expect(browser._page).toBe(0);
+        expect($('.myapps-add-tile')).toHaveLength(0);
+    });
+
+    it('opens folders but cannot rename, reorder, remove, or persist changes', async () => {
+        await mount();
+        $('.myapps-group-tile').trigger('click');
+        expect($('.myapps-group-name').prop('readOnly')).toBe(true);
+        expect($('.myapps-group-panel .myapps-tile')).toHaveLength(2);
+        $('.myapps-group-name').val('Changed').trigger('blur');
+        browser._setReorderMode($root, true);
+        $('.myapps-tile').first().trigger($.Event('pointerdown', { button: 0, pointerType: 'mouse' }));
+        $('.myapps-tile').first().trigger('contextmenu');
+        browser.saveOrder();
+        browser.saveGroups();
+        expect(browser._reorderMode).toBe(false);
+        expect(browser._drag).toBeNull();
+        expect(browser._groups[0].name).toBe('Work');
+        expect(puter.kv.set).not.toHaveBeenCalled();
+        $('.myapps-group-panel .myapps-tile').first().trigger('click');
+        expect(onLaunch).toHaveBeenCalled();
+    });
+
+    it('retains the dashboard editing controls and isolates component state', async () => {
+        await mount({ editable: true });
+        expect($('.myapps-reorder-btn, .myapps-add-tile')).toHaveLength(2);
+        browser._setReorderMode($root, true);
+        expect(browser._reorderMode).toBe(true);
+        const other = createAppBrowser({ editable: false });
+        expect(other._apps).toBeNull();
+        expect(other._groups).toEqual([]);
+        expect(other._launchingApps).not.toBe(browser._launchingApps);
+    });
+
+    it('opens dashboard launches in a new tab through desktop actions', async () => {
+        const tab = { close: vi.fn() };
+        vi.spyOn(window, 'open').mockReturnValue(tab);
+        const actions = {
+            launchApp: vi.fn(async () => ({ launchResult: { launched: true } })),
+        };
+        await mount({ editable: true, onLaunch: undefined, actions });
+        $('.myapps-search').val('editor').trigger('input');
+        $('.myapps-tile[data-app-name="editor"]').trigger('click');
+        expect(window.open).toHaveBeenCalledWith('', '_blank');
+        expect(actions.launchApp).toHaveBeenCalledWith({ name: 'editor', newTab: tab });
+        await vi.waitFor(() => expect(browser._launchingApps.size).toBe(0));
+        expect($('.window')).toHaveLength(0);
+    });
+
+    it('launches in-page when the browser refuses the tab', async () => {
+        vi.spyOn(window, 'open').mockReturnValue(null);
+        const actions = {
+            launchApp: vi.fn(async () => ({ launchResult: { launched: true } })),
+            beginTileLaunch: vi.fn(),
+            settleTileLaunch: vi.fn(),
+        };
+        await mount({ editable: true, onLaunch: undefined, actions });
+        $('.myapps-search').val('editor').trigger('input');
+        const tile = $('.myapps-tile[data-app-name="editor"]').get(0);
+        $(tile).trigger('click');
+        expect(actions.launchApp).toHaveBeenCalledWith({
+            name: 'editor', maximized: true,
+            window_options: { morph_from_dashboard_tile: true },
+        });
+        expect(actions.beginTileLaunch).toHaveBeenCalledWith(tile);
+        await vi.waitFor(() => expect(actions.settleTileLaunch).toHaveBeenCalledWith(tile));
+        expect(browser._launchingApps.size).toBe(0);
+    });
+
+    it('launches the app store from the dashboard add-app dialog', async () => {
+        const actions = {
+            launchApp: vi.fn(async () => {}),
+            settleTileLaunch: vi.fn(),
+        };
+        puter.apps = { get: async name => ({ name, title: name }) };
+        await mount({ editable: true, onLaunch: undefined, actions });
+        $('.myapps-add-tile').trigger('click');
+        $('.myapps-add-option[data-add-option="browse"]').trigger('click');
+        await vi.waitFor(() => expect(actions.launchApp).toHaveBeenCalledWith(
+            expect.objectContaining({ name: 'app-center', maximized: true }),
+        ));
+        expect($('.myapps-add-modal')).toHaveLength(0);
+    });
+
+    it('renders an empty list and an API failure without offering authentication', async () => {
+        installed = [];
+        recommended = [];
+        await mount();
+        expect($('.myapps-empty').text()).toBe('no_apps_installed');
+        fetch.mockRejectedValue(new Error('unauthorized'));
+        browser._apps = null;
+        const log = vi.spyOn(console, 'error').mockImplementation(() => {});
+        await browser.loadApps($root);
+        expect($('.myapps-empty').text()).toBe('apps_load_failed');
+        expect($('.window, form')).toHaveLength(0);
+        log.mockRestore();
+    });
+});

src/gui/src/UI/Dashboard/TabFiles.js

@@ -4394,15 +4394,26 @@ const TabFiles = {
      * @returns {Promise<void>}
      */
     async openRow (row) {
+        const isDir = row.getAttribute('data-is_dir') === '1';
+        // A file opens in a new browser tab. The tab is opened now, inside
+        // the user's gesture, because popup blockers refuse one opened after
+        // the awaits below; open_item closes it if the file opens no app.
+        // Without 'noopener': the app asks this tab for its token (see
+        // launch_app). Blocked (e.g. the second file of a multi-select
+        // Enter), the file opens in-page. A file in the Trash opens nothing
+        // (open_item only says why), so it gets no tab to flash open and shut.
+        const target = row.getAttribute('data-shortcut_to_path') || row.getAttribute('data-path') || '';
+        const inTrash = target.startsWith(`${window.trash_path}/`);
+        const newTab = isDir || inTrash ? null : window.open('', '_blank');
         // Not for ever: the rename settles in rename_file's last step, which
         // a failure after the rename itself (refreshing websites) never reaches.
         if ( row._pendingRename ) await Promise.race([row._pendingRename, new Promise(resolve => setTimeout(resolve, 5000))]);
-        if ( row.getAttribute('data-is_dir') === '1' ) {
+        if ( isDir ) {
             const folderPath = row.getAttribute('data-path');
             this.pushNavHistory(folderPath);
             this.renderDirectory(folderPath);
         } else {
-            open_item({ item: row });
+            open_item({ item: row, ...(newTab ? { newTab } : {}) });
         }
     },
 
@@ -5180,6 +5191,8 @@ const TabFiles = {
             },
             // Custom open handler for Dashboard (avoids window_nav_history issues)
             onOpen: (el) => _this.openRow(el),
+            // Like opening the row, Open With opens the app in a new tab.
+            openWithInNewTab: true,
             onShowProperties: ({ name, path: item_path, uid }) => {
                 // Dashboard uses a responsive modal instead of the desktop UIWindow.
                 UIItemPropertiesModal({

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

@@ -27,6 +27,11 @@ vi.mock('../UIAlert.js', () => ({ default: vi.fn() }));
 vi.mock('../UIWindowProgress.js', () => ({ default: vi.fn() }));
 vi.mock('../UIContextMenu.js', () => ({ default: vi.fn() }));
 vi.mock('../../helpers/generateFileContextMenu.js', () => ({ default: vi.fn(async () => []) }));
+// Loaded for its imports' side effects (i18n among them); only opening is stubbed.
+vi.mock('../../helpers/openItem.js', async (importOriginal) => ({
+    ...(await importOriginal()),
+    default: vi.fn(),
+}));
 vi.mock('../../helpers/itemIcon.js', async (importOriginal) => {
     const actual = await importOriginal();
     return { default: vi.fn(actual.default) };
@@ -42,6 +47,7 @@ window.icons = {};
 
 const { default: TabFiles, failedUploadsMessage, rebasePath, typeSelectTarget } = await import('./TabFiles.js');
 const { default: generateFileContextMenu } = await import('../../helpers/generateFileContextMenu.js');
+const { default: open_item } = await import('../../helpers/openItem.js');
 const { default: itemIcon } = await import('../../helpers/itemIcon.js');
 
 const TRASH = '/alice/Trash';
@@ -1253,6 +1259,50 @@ describe('TabFiles opening a folder being renamed', () => {
     });
 });
 
+describe('TabFiles opening a file', () => {
+    beforeEach(() => {
+        window.trash_path = TRASH;
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        open_item.mockClear();
+    });
+
+    it('opens it in a new tab', async () => {
+        const tab = { close: vi.fn() };
+        vi.spyOn(window, 'open').mockReturnValue(tab);
+        mountListing(['notes.txt'], '/alice/Documents');
+        const row = $('.files .row')[0];
+
+        await TabFiles.openRow(row);
+
+        expect(window.open).toHaveBeenCalledWith('', '_blank');
+        expect(open_item).toHaveBeenCalledWith({ item: row, newTab: tab });
+    });
+
+    it('opens no tab for a file in the Trash, which only explains why it can\'t open', async () => {
+        vi.spyOn(window, 'open');
+        mountListing(['notes.txt']);
+        const row = $('.files .row')[0];
+
+        await TabFiles.openRow(row);
+
+        expect(window.open).not.toHaveBeenCalled();
+        expect(open_item).toHaveBeenCalledWith({ item: row });
+    });
+
+    it('opens a tab for a shortcut in the Trash whose file is not', async () => {
+        vi.spyOn(window, 'open').mockReturnValue({ close: vi.fn() });
+        mountListing(['notes.txt']);
+        const row = $('.files .row')[0];
+        row.setAttribute('data-shortcut_to_path', '/alice/Documents/notes.txt');
+
+        await TabFiles.openRow(row);
+
+        expect(window.open).toHaveBeenCalledOnce();
+    });
+});
+
 describe('TabFiles.folderMoved', () => {
     beforeEach(() => {
         TabFiles.$el_window = $('<div>');

src/gui/src/UI/Dashboard/UIDashboardNotifications.js

@@ -29,7 +29,7 @@ import {
     storedTapHandler,
     tapRoute,
 } from '../../helpers/notificationTap.js';
-import { showLocalBanner, startPushWorker } from '../../helpers/pushWorker.js';
+import { startPushWorker } from '../../helpers/pushWorker.js';
 import { syncBrowserPush } from '../../helpers/pushSync.js';
 import { get_app_by_uid } from '../../helpers/getAppByUid.js';
 import launch_app from '../../helpers/launchApp.js';
@@ -637,9 +637,6 @@ export default function UIDashboardNotifications ({ $el_window, socket }) {
 
         const fresh = incoming.filter((entry) => ! surfaced.has(entry.uid));
         for ( const entry of fresh ) surfaced.add(entry.uid);
-        for ( const entry of fresh ) {
-            void showLocalBanner(entry, { replay, acknowledged: ! isUnread(entry) });
-        }
         for ( const entry of result.added ) justAdded.add(entry.uid);
         render();
         announce(fresh);

src/gui/src/UI/UIDesktop.js

@@ -61,7 +61,7 @@ import {
     setPushTapHandler,
     storedTapHandler,
 } from '../helpers/notificationTap.js';
-import { closeLocalBanner, showLocalBanner, startPushWorker } from '../helpers/pushWorker.js';
+import { closeLocalBanner, startPushWorker } from '../helpers/pushWorker.js';
 import { syncBrowserPush } from '../helpers/pushSync.js';
 import { get_app_by_uid } from '../helpers/getAppByUid.js';
 import { httpsIconFor, notificationTarget, senderNameFor } from './Dashboard/notificationCenter.js';
@@ -289,7 +289,6 @@ async function UIDesktop (options) {
      * row isn't marked twice.
      */
     const show_notification = ({ uid, notification, app_uid }, { replay = false } = {}) => {
-        void showLocalBanner({ uid, notification }, { replay });
         // A notification can be re-sent under its own uid when what it says has
         // grown — several people sharing with you is one notification that
         // counts them. Refresh the one on screen rather than stacking a copy.

src/gui/src/UI/UIWindow.js

@@ -704,12 +704,12 @@ async function UIWindow (options) {
         attach_dashboard_app_drawer(el_window, options);
     }
 
-    // Let the Apps tab refresh its tiles' running dots (see TabApps).
+    // Let the Apps tab refresh its tiles' running dots (see AppBrowser.js).
     if ( window.is_dashboard_mode && options.app ) {
         document.dispatchEvent(new CustomEvent('dashboard-app-windows-changed'));
     }
 
-    // A launch from a dashboard Apps-tab tile (TabApps passes
+    // A launch from a dashboard Apps-tab tile (AppBrowser.js passes
     // morph_from_dashboard_tile) morphs the tile's icon into the opening
     // window — the reverse of hideWindow's minimize morph. The window is
     // already appended, displayed, and at its final (maximized) geometry
@@ -2882,7 +2882,7 @@ function delete_window_element (el_window) {
         window.window_counter = 0;
     }
     // Every close path funnels through here — after the element is gone,
-    // let the Apps tab turn the app tile's running dot off (see TabApps).
+    // let the Apps tab turn the app tile's running dot off (see AppBrowser.js).
     if ( window.is_dashboard_mode && was_app ) {
         document.dispatchEvent(new CustomEvent('dashboard-app-windows-changed'));
     }
@@ -4664,7 +4664,7 @@ function dashboard_rendered_app_icon (app_name) {
 // -- Drawer intro exposure decay --
 // The drawer's opening flash (see attach_dashboard_app_drawer) is pedagogy:
 // it teaches that the app's controls live in the tongue. Like the
-// dashboard's deep-link intro (TabApps.js), the lesson decays — after this
+// dashboard's deep-link intro (AppBrowser.js), the lesson decays — after this
 // many deliveries, new windows keep the bare tongue and the flash stops
 // occluding the app's top edge. A delivery is counted once per window:
 // either the flash played while the user could see it, or the user opened
@@ -4969,7 +4969,7 @@ function attach_dashboard_app_drawer (el_window, options) {
  * Tiles whose click feedback has played (or is playing) for the launch
  * currently in flight. A fresh app launch has a server round-trip between
  * the click and the window's creation; so the click is acknowledged
- * instantly, TabApps plays the icon half of the open morph immediately
+ * instantly, AppBrowser.js plays the icon half of the open morph immediately
  * (begin_dashboard_tile_launch) and the mark here tells the window's half
  * not to replay it when the window finally opens (morph_window_from_tile).
  */

src/gui/src/appsEmbed.js

@@ -0,0 +1,114 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import jQuery from './lib/jquery-3.6.1/jquery-3.6.1.min.js';
+import { encode } from 'html-entities';
+import { loadLocale } from './i18n/embedI18n.js';
+import { createAppBrowser } from './UI/Dashboard/AppBrowser.js';
+import { appTileLink } from './UI/Dashboard/appLink.js';
+import { installAppIconFallback } from './helpers/appIcon.js';
+import { launchAppInTab } from './helpers/appTabLaunch.js';
+
+window.$ = window.jQuery = jQuery;
+window.html_encode = value => encode(String(value ?? ''), { mode: 'nonAsciiPrintable' });
+window.icons = {
+    'app.svg': new URL('./icons/app.svg', import.meta.url).href,
+    'app-default.svg': new URL('./icons/app-default.svg', import.meta.url).href,
+};
+
+const root = document.querySelector('#app-browser');
+const config = JSON.parse(document.querySelector('#app-browser-config').textContent);
+window.api_origin = config.apiOrigin;
+window.PUTER_API_ORIGIN = config.apiOrigin;
+window.PUTER_GUI_ORIGIN = window.location.origin;
+window.gui_origin = window.location.origin;
+window.puter_gui_enabled = true;
+window.puter_socket_enabled = false;
+window.locale = 'en';
+try {
+    window.locale = JSON.parse(localStorage.getItem('user_preferences') || '{}')?.language || 'en';
+} catch { /* Corrupt preferences must not prevent loading apps. */ }
+const localeReady = loadLocale(window.locale);
+// Apps whose launch is still fetching; a second click would open a second tab.
+const launching = new Set();
+
+/**
+ * Opens a tile's app in a new tab at its own URL, as the dashboard does.
+ * Website shortcuts, and apps that need the desktop, open their tile link.
+ */
+function launchTile ({ appName, targetLink }) {
+    const href = appTileLink({ appName, targetLink }, window.location.origin);
+    if ( targetLink || !appName ) {
+        if ( href ) window.open(href, '_blank', 'noopener,noreferrer');
+        return;
+    }
+    if ( launching.has(appName) ) return;
+    // Opened inside the click so popup blockers allow it, and without
+    // 'noopener' so the app's SDK can ask this page for its token.
+    const tab = window.open('', '_blank');
+    if ( ! tab ) return;
+    launching.add(appName);
+    launchAppInTab({
+        name: appName,
+        tab,
+        guiOrigin: window.location.origin,
+        apiOrigin: config.apiOrigin,
+        authToken: window.auth_token,
+        locale: window.locale,
+    })
+        .catch((err) => {
+            console.error(`Failed to launch ${appName}:`, err);
+            return false;
+        })
+        .then((opened) => {
+            if ( opened || tab.closed ) return;
+            // The desktop's /app/<name> landing handles access and errors.
+            tab.opener = null;
+            tab.location.href = href;
+        })
+        .finally(() => launching.delete(appName));
+}
+
+async function mount () {
+    window.auth_token = localStorage.getItem('auth_token_v2');
+    if ( ! window.auth_token ) throw new Error('Missing session');
+
+    await Promise.all([new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = config.sdkUrl;
+        script.onload = resolve;
+        script.onerror = reject;
+        document.head.appendChild(script);
+    }), localeReady]);
+    puter.setAPIOrigin(config.apiOrigin);
+    installAppIconFallback();
+
+    const browser = createAppBrowser({
+        editable: false,
+        onLaunch: launchTile,
+    });
+    const $root = $(root);
+    $root.html(`<section class="dashboard-section dashboard-section-apps active">${browser.html()}</section>`);
+    browser.init($root);
+}
+
+mount().catch(async () => {
+    await localeReady;
+    root.innerHTML = `<p class="myapps-empty" role="status">${i18n('app_browser_unavailable')}</p>`;
+});

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

@@ -0,0 +1,31 @@
+html,
+body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    font-family: "Inter", "Helvetica Neue", Helvetica, Arial, sans-serif;
+    color: var(--dashboard-text);
+    background: var(--dashboard-background);
+}
+
+#app-browser {
+    display: block;
+    width: 100%;
+    height: 100%;
+}
+
+#app-browser .dashboard-section-apps {
+    width: 100%;
+}
+
+/* The dashboard's narrow-screen padding clears its hamburger button, which embeds don't have. */
+#app-browser .myapps-search-wrap {
+    padding-top: 16px;
+    padding-bottom: 16px;
+    margin-bottom: 8px;
+}
+
+#app-browser .myapps-group-name[readonly] {
+    cursor: default;
+}

src/gui/src/css/dashboard.css

@@ -950,7 +950,7 @@ input.myapps-search::-webkit-search-decoration {
     appearance: none;
 }
 
-/* Frozen while reorder mode is on (see TabApps._setReorderMode). */
+/* Frozen while reorder mode is on (see _setReorderMode in AppBrowser.js). */
 input.myapps-search:disabled {
     opacity: 0.55;
 }
@@ -1016,7 +1016,7 @@ input.myapps-search:disabled {
 }
 
 .myapps-container {
-    /* Pager geometry is inherited from .myapps-tab; TabApps.js reads it here
+    /* Pager geometry is inherited from .myapps-tab; AppBrowser.js reads it here
        (computeLayout) to size pages. */
     flex: 1;
     min-height: 0;
@@ -1294,7 +1294,7 @@ input.myapps-search:disabled {
 
 /* Uninstall: the tile shrinks away in place, then the surviving tiles
    FLIP-slide into the closed-up grid (see showUninstallModal). Duration is
-   mirrored by TILE_REMOVE_ANIM_MS in TabApps.js. */
+   mirrored by TILE_REMOVE_ANIM_MS in AppBrowser.js. */
 .myapps-tile.myapps-tile-removing {
     transition: transform 0.18s ease-in, opacity 0.18s ease-in;
     transform: scale(0.5);
@@ -1414,7 +1414,7 @@ input.myapps-search:disabled {
 }
 
 /* Pending: the well fills over the dwell the drop is waiting out
-   (DRAG_MERGE_DWELL_MS in TabApps.js) — for the ordinary gesture (carry the
+   (DRAG_MERGE_DWELL_MS in AppBrowser.js) — for the ordinary gesture (carry the
    icon over, stop) the fill IS the countdown, so leaving before it completes
    is an informed choice rather than a surprise. */
 body.myapps-reordering .myapps-tile-merge-pending::before {
@@ -1491,7 +1491,7 @@ body.myapps-reordering .myapps-tile.myapps-tile-merge-armed .myapps-tile-icon {
     opacity: 0;
     transform: scale(0.92);
     transform-origin: center;
-    /* Mirrors GROUP_PANEL_OPEN_MS / GROUP_PANEL_CLOSE_MS in TabApps.js; the
+    /* Mirrors GROUP_PANEL_OPEN_MS / GROUP_PANEL_CLOSE_MS in AppBrowser.js; the
        curve is the window morph's, so a folder opening and an app opening
        feel like the same gesture at two scales. */
     transition: transform 0.24s cubic-bezier(0.32, 0.72, 0, 1), opacity 0.2s ease;
@@ -4597,7 +4597,7 @@ select.share-modal-row-mode:focus {
 /* A tile installed by a deep-link landing, not yet arrived: rendered in
    place — layout, page count, and the wayfinding flip all see it — but held
    invisible for the intro's arrival beat to reveal (see _spliceDeepLinkApp /
-   _revealArrivingTile in TabApps.js). */
+   _revealArrivingTile in AppBrowser.js). */
 .myapps-tile-installing {
     opacity: 0;
     transform: scale(0.55);
@@ -4605,7 +4605,7 @@ select.share-modal-row-mode:focus {
 }
 
 /* The arrival itself: an INSTALLATION, staged over 1400ms (mirrored by
-   DEEP_LINK_INSTALL_ARRIVE_MS in TabApps.js) with the grammar users know
+   DEEP_LINK_INSTALL_ARRIVE_MS in AppBrowser.js) with the grammar users know
    from every app store:
      1. the slot opens — the folder well's own surface — and the icon
         materializes into it DIM (grayscale, translucent, slightly small):
@@ -4750,7 +4750,7 @@ body.myapps-reordering .myapps-tile {
     touch-action: none;
 }
 
-/* -- Reorder mode (touch; see TabApps._setReorderMode) --
+/* -- Reorder mode (touch; see _setReorderMode in AppBrowser.js) --
    touch-action must be locked down BEFORE the finger goes down — the browser
    reads it at gesture start, so the mid-drag body.myapps-reordering rule
    above can't stop a touch the scroller has already claimed. While the mode
@@ -9092,7 +9092,7 @@ body.dashboard-mode .window-dashboard-headless .window-body-app {
 
 /* Running dot: marks Apps-tab tiles whose app has a live window (visible or
    minimized), macOS-dock style — sits centered in the gap between the 56px
-   icon and the label. Kept/removed by updateRunningDots in TabApps.js. */
+   icon and the label. Kept/removed by updateRunningDots in AppBrowser.js. */
 .myapps-tile {
     position: relative;
 }

src/gui/src/helpers.js

@@ -31,6 +31,7 @@ import update_username_in_gui from './helpers/updateUsernameInGui.js';
 import { notifyItemWatchers } from './helpers/watchItems.js';
 import { select_uploaded_items } from './helpers/uploadSelection.js';
 import { templateMenuItem } from './helpers/templateMenuItem.js';
+import { uuidv4 } from './helpers/uuidv4.js';
 import mime from './lib/mime.js';
 import path from './lib/path.js';
 import UIAlert from './UI/UIAlert.js';
@@ -259,10 +260,7 @@ window.usage_bar_color = (percent) => {
  * let id = window.uuidv4(); // Generate a new UUID
  *
  */
-window.uuidv4 = () => {
-    return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, c =>
-        (c ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> c / 4).toString(16));
-};
+window.uuidv4 = uuidv4;
 
 /**
  * Checks if the provided string is a valid email format.

src/gui/src/helpers/appLaunchApi.js

@@ -0,0 +1,111 @@
+/*
+ * 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/>.
+ */
+
+/** Server calls an app launch makes, kept free of desktop globals for the app browser embed. */
+
+/**
+ * @typedef {object} AppLaunchServer
+ * @property {string} [apiOrigin]
+ * @property {string} [authToken] - the GUI session token
+ */
+
+/**
+ * Fetches the token the app signs in with.
+ *
+ * @param {{ appUid?: string } & AppLaunchServer} options
+ */
+export const fetchUserAppTokenForLaunch = async ({
+    appUid,
+    apiOrigin = window.api_origin,
+    authToken = window.auth_token,
+} = {}) => {
+    if ( ! appUid ) {
+        return {
+            token: null,
+            reason: 'missing-app-uid',
+        };
+    }
+
+    try {
+        const response = await fetch(`${apiOrigin}/auth/get-user-app-token`, {
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${authToken}`,
+            },
+            body: JSON.stringify({ app_uid: appUid }),
+            method: 'POST',
+        });
+
+        let responseBody;
+        try {
+            responseBody = await response.json();
+        } catch ( error ) {
+            responseBody = null;
+        }
+
+        if ( response.ok && responseBody?.token ) {
+            return {
+                token: responseBody.token,
+            };
+        }
+
+        return {
+            token: null,
+            reason: 'token-request-failed',
+            status: response.status,
+            responseCode: responseBody?.code ?? responseBody?.error?.code,
+            responseMessage: responseBody?.message ?? responseBody?.error?.message,
+            responseBody,
+            attempts: 1,
+        };
+    } catch ( error ) {
+        return {
+            token: null,
+            reason: 'network-error',
+            error,
+            attempts: 1,
+        };
+    }
+};
+
+/**
+ * Records the open with the server (`/rao`), which keeps the user's recent apps.
+ *
+ * @param {{ appUid: string, socketId?: string } & AppLaunchServer} options
+ */
+export const reportAppOpen = ({
+    appUid,
+    socketId,
+    apiOrigin = window.api_origin,
+    authToken = window.auth_token,
+}) => {
+    $.ajax({
+        url: `${apiOrigin}/rao`,
+        type: 'POST',
+        data: JSON.stringify({
+            original_client_socket_id: socketId,
+            app_uid: appUid,
+        }),
+        async: true,
+        contentType: 'application/json',
+        headers: {
+            'Authorization': `Bearer ${authToken}`,
+        },
+    });
+};

src/gui/src/helpers/appLaunchUrl.js

@@ -0,0 +1,102 @@
+/*
+ * 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 URL an app is launched at, in a desktop window or its own tab. Kept free
+ * of desktop globals so the app browser embed builds the same URL.
+ */
+
+// This can be any trusted URL that won't be used for other apps
+export const BUILTIN_PREFIX = 'https://builtins.namespaces.puter.com/';
+
+// Newer IPC dialogs this GUI can answer, comma-separated. The SDK consults
+// this before posting a message an older GUI has no handler for: such a
+// message is never replied to, and a reply timeout can't stand in for the
+// check because legitimate replies only arrive when the user closes the dialog.
+const GUI_FEATURES = 'feedback-dialog,enable-push,custom-domains,push-status,disable-push';
+
+/**
+ * Where an app was launched from, sent to the app as `utm_campaign` so its
+ * analytics can tell the GUI's launch surfaces apart.
+ *
+ * @typedef {'desktop' | 'dashboard' | 'app_browser_embed'} LaunchSurface
+ */
+
+/**
+ * The app's index URL with the params that name the launch.
+ *
+ * @param {object} options
+ * @param {{ uid?: string, uuid?: string, name: string, index_url?: string }} options.app
+ * @param {string} [options.name] - the name the app was launched by
+ * @param {string} options.appInstanceID
+ * @param {string} options.guiOrigin
+ * @param {string} options.appDomain
+ * @returns {URL}
+ */
+export const appLaunchUrl = ({ app, name = app.name, appInstanceID, guiOrigin, appDomain }) => {
+    let url;
+    if ( ! app.index_url ) {
+        url = new URL(`https://${name}.${appDomain}/index.html`);
+    } else if ( app.index_url.startsWith(BUILTIN_PREFIX) ) {
+        url = new URL(`${guiOrigin}/builtin/${app.index_url.slice(BUILTIN_PREFIX.length)}`);
+    } else {
+        url = new URL(app.index_url);
+    }
+    url.searchParams.append('puter.app_instance_id', appInstanceID);
+    url.searchParams.append('puter.app.id', app.uuid ?? app.uid);
+    url.searchParams.append('puter.app.name', app.name);
+    return url;
+};
+
+/**
+ * Appends the params that tell the app where Puter is and how it was
+ * launched.
+ *
+ * @param {URL} url
+ * @param {object} options
+ * @param {string} options.appDomain
+ * @param {string} options.pageUrl - the GUI page launching the app
+ * @param {string} [options.apiOrigin]
+ * @param {Record<string, string>} [options.params] - extra params from the caller
+ * @param {string} options.locale
+ * @param {unknown} [options.args]
+ * @param {LaunchSurface} options.surface
+ */
+export const appendLaunchContext = (url, { appDomain, pageUrl, apiOrigin, params, locale, args, surface }) => {
+    url.searchParams.append('puter.domain', appDomain);
+
+    const page = new URL(pageUrl);
+    url.searchParams.append('puter.origin', page.origin);
+    url.searchParams.append('puter.hostname', page.hostname);
+    url.searchParams.append('puter.port', page.port);
+    url.searchParams.append('puter.protocol', page.protocol.slice(0, -1));
+
+    if ( apiOrigin ) {
+        url.searchParams.append('puter.api_origin', apiOrigin);
+    }
+    for ( const property in params ?? {} ) {
+        url.searchParams.append(property, params[property]);
+    }
+    url.searchParams.append('puter.locale', locale);
+    url.searchParams.append('puter.gui_features', GUI_FEATURES);
+    url.searchParams.append('puter.args', JSON.stringify(args ?? {}));
+    url.searchParams.append('utm_source', 'puter.com');
+    url.searchParams.append('utm_medium', 'referral');
+    url.searchParams.append('utm_campaign', surface);
+};

src/gui/src/helpers/appLaunchUrl.test.js

@@ -0,0 +1,74 @@
+/*
+ * 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 { appLaunchUrl, appendLaunchContext } from './appLaunchUrl.js';
+
+const base = { appInstanceID: 'instance-1', guiOrigin: 'https://puter.test', appDomain: 'puter.test' };
+
+describe('appLaunchUrl', () => {
+    it('keeps the index_url\'s own params and names the launch after them', () => {
+        const url = appLaunchUrl({ ...base, app: { uid: 'app-1', name: 'notes', index_url: 'https://notes.example.com/?mode=1' } });
+        expect([...url.searchParams]).toEqual([
+            ['mode', '1'],
+            ['puter.app_instance_id', 'instance-1'],
+            ['puter.app.id', 'app-1'],
+            ['puter.app.name', 'notes'],
+        ]);
+    });
+
+    it('serves a built-in app from the GUI', () => {
+        const url = appLaunchUrl({ ...base, app: { uid: 'app-1', name: 'settings', index_url: 'https://builtins.namespaces.puter.com/settings' } });
+        expect(`${url.origin}${url.pathname}`).toBe('https://puter.test/builtin/settings');
+    });
+
+    it('falls back to the app\'s subdomain without an index_url', () => {
+        const url = appLaunchUrl({ ...base, app: { uid: 'app-1', name: 'notes' } });
+        expect(`${url.origin}${url.pathname}`).toBe('https://notes.puter.test/index.html');
+    });
+});
+
+describe('appendLaunchContext', () => {
+    it('tells the app where the GUI and API are', () => {
+        const url = new URL('https://notes.example.com/');
+        appendLaunchContext(url, {
+            appDomain: 'puter.test',
+            pageUrl: 'http://puter.test:4100/embed/apps',
+            apiOrigin: 'http://api.puter.test:4100',
+            params: { extra: 'x' },
+            locale: 'en',
+            args: { a: 1 },
+            surface: 'dashboard',
+        });
+        expect(Object.fromEntries(url.searchParams)).toMatchObject({
+            'puter.domain': 'puter.test',
+            'puter.origin': 'http://puter.test:4100',
+            'puter.hostname': 'puter.test',
+            'puter.port': '4100',
+            'puter.protocol': 'http',
+            'puter.api_origin': 'http://api.puter.test:4100',
+            'extra': 'x',
+            'puter.locale': 'en',
+            'puter.args': '{"a":1}',
+            'utm_source': 'puter.com',
+            'utm_medium': 'referral',
+            'utm_campaign': 'dashboard',
+        });
+    });
+});

src/gui/src/helpers/appTabLaunch.js

@@ -0,0 +1,135 @@
+/*
+ * 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 { BUILTIN_PREFIX, appLaunchUrl, appendLaunchContext } from './appLaunchUrl.js';
+import { fetchUserAppTokenForLaunch, reportAppOpen } from './appLaunchApi.js';
+import { uuidv4 } from './uuidv4.js';
+
+/**
+ * Launch data for apps opened in their own browser tab: the app's token and
+ * the item it was opened with (whose signed URLs don't expire). Both stay out
+ * of the tab's URL, and so out of its history; the app's SDK asks this tab for
+ * them once it loads (see requestLaunchFromOpener in puter.js).
+ */
+
+// Long enough for a slow app to load; after that the app signs in on its own.
+const OFFER_TTL_MS = 2 * 60 * 1000;
+
+/**
+ * @typedef {object} AppTabLaunch
+ * @property {string} appInstanceID
+ * @property {Window} tab - the tab the app was opened in
+ * @property {string} origin - origin of the URL the tab was sent to
+ * @property {string} token
+ * @property {Record<string, string> | null} item - the opened item's `puter.item.*` params
+ */
+
+/** @type {Map<string, AppTabLaunch & { timer: ReturnType<typeof setTimeout> }>} */
+const offers = new Map();
+let listening = false;
+
+const withdraw = (appInstanceID) => {
+    const offer = offers.get(appInstanceID);
+    if ( ! offer ) return;
+    clearTimeout(offer.timer);
+    offers.delete(appInstanceID);
+};
+
+const onMessage = (event) => {
+    const data = event.data;
+    if ( data?.msg !== 'puter.requestLaunch' || typeof data.appInstanceID !== 'string' ) return;
+    const offer = offers.get(data.appInstanceID);
+    // Only the tab this launch opened, still showing the app it was opened
+    // for, gets the launch data — and only once.
+    if ( !offer || event.source !== offer.tab || event.origin !== offer.origin ) return;
+    withdraw(data.appInstanceID);
+    offer.tab.postMessage({
+        msg: 'puter.launch',
+        appInstanceID: data.appInstanceID,
+        token: offer.token,
+        item: offer.item,
+    }, offer.origin);
+};
+
+/**
+ * Holds an app tab's launch data until the app asks for it from `origin`.
+ *
+ * @param {AppTabLaunch} offer
+ */
+export const offerAppTabLaunch = ({ appInstanceID, tab, origin, token, item }) => {
+    if ( ! listening ) {
+        window.addEventListener('message', onMessage);
+        listening = true;
+    }
+    withdraw(appInstanceID);
+    offers.set(appInstanceID, {
+        appInstanceID,
+        tab,
+        origin,
+        token,
+        item,
+        timer: setTimeout(() => withdraw(appInstanceID), OFFER_TTL_MS),
+    });
+};
+
+/**
+ * Opens an app in `tab` at its own URL, the way launch_app's `newTab` does,
+ * for pages without the desktop (the app browser embed). Resolves false,
+ * leaving the tab as it is, for a launch that needs the desktop: a built-in
+ * or godmode app, a private app the user can't open, or a token that
+ * couldn't be fetched. Also false when the user closed the tab meanwhile.
+ *
+ * @param {object} options
+ * @param {string} options.name - the app's name
+ * @param {Window} options.tab - opened by the caller, inside the click and
+ *   without `noopener`, so the app can ask it for its token
+ * @param {string} options.guiOrigin
+ * @param {string} options.apiOrigin
+ * @param {string} options.authToken - the GUI session token
+ * @param {string} options.locale
+ * @returns {Promise<boolean>} whether the tab was sent to the app
+ */
+export const launchAppInTab = async ({ name, tab, guiOrigin, apiOrigin, authToken, locale }) => {
+    const app = await puter.apps.get(name);
+    if ( app.index_url?.startsWith(BUILTIN_PREFIX)
+        || app.godmode === true || app.godmode === 1
+        || app.privateAccess?.hasAccess === false ) {
+        return false;
+    }
+
+    const appUid = app.uid ?? app.uuid;
+    const { token } = await fetchUserAppTokenForLaunch({ appUid, apiOrigin, authToken });
+    if ( !token || tab.closed ) return false;
+
+    const appInstanceID = uuidv4();
+    const appDomain = new URL(guiOrigin).hostname;
+    const url = appLaunchUrl({ app, name, appInstanceID, guiOrigin, appDomain });
+    appendLaunchContext(url, {
+        appDomain,
+        pageUrl: guiOrigin,
+        apiOrigin,
+        locale,
+        surface: 'app_browser_embed',
+    });
+
+    offerAppTabLaunch({ appInstanceID, tab, origin: url.origin, token, item: null });
+    tab.location.href = url.href;
+    reportAppOpen({ appUid, apiOrigin, authToken });
+    return true;
+};

src/gui/src/helpers/appTabLaunch.test.js

@@ -0,0 +1,167 @@
+// @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, describe, expect, it, vi } from 'vitest';
+import { launchAppInTab, offerAppTabLaunch } from './appTabLaunch.js';
+
+const ORIGIN = 'https://notes.example.com';
+const ITEM = { 'puter.item.uid': 'file-1', 'puter.item.read_url': 'https://api.puter.test/file?signature=r' };
+let nextId = 0;
+
+const offer = () => {
+    const appInstanceID = `instance-${++nextId}`;
+    const tab = { postMessage: vi.fn() };
+    offerAppTabLaunch({ appInstanceID, tab, origin: ORIGIN, token: 'app-token', item: ITEM });
+    return { appInstanceID, tab };
+};
+
+const request = ({ appInstanceID, source, origin = ORIGIN }) => {
+    window.dispatchEvent(new MessageEvent('message', {
+        data: { msg: 'puter.requestLaunch', env: 'app-tab', appInstanceID },
+        origin,
+        source,
+    }));
+};
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+describe('offerAppTabLaunch', () => {
+    it('answers the tab it was offered to, at its origin, once', () => {
+        const { appInstanceID, tab } = offer();
+        request({ appInstanceID, source: tab });
+        request({ appInstanceID, source: tab });
+        expect(tab.postMessage).toHaveBeenCalledOnce();
+        expect(tab.postMessage).toHaveBeenCalledWith({
+            msg: 'puter.launch',
+            appInstanceID,
+            token: 'app-token',
+            item: ITEM,
+        }, ORIGIN);
+    });
+
+    it('ignores another window that knows the instance id', () => {
+        const { appInstanceID, tab } = offer();
+        const other = { postMessage: vi.fn() };
+        request({ appInstanceID, source: other });
+        expect(other.postMessage).not.toHaveBeenCalled();
+        expect(tab.postMessage).not.toHaveBeenCalled();
+    });
+
+    it('ignores the tab once it has navigated to another origin', () => {
+        const { appInstanceID, tab } = offer();
+        request({ appInstanceID, source: tab, origin: 'https://elsewhere.example' });
+        expect(tab.postMessage).not.toHaveBeenCalled();
+    });
+
+    it('withdraws an offer nobody asked for in time', () => {
+        vi.useFakeTimers();
+        const { appInstanceID, tab } = offer();
+        vi.advanceTimersByTime(2 * 60 * 1000);
+        request({ appInstanceID, source: tab });
+        expect(tab.postMessage).not.toHaveBeenCalled();
+    });
+});
+
+describe('launchAppInTab', () => {
+    const app = { uid: 'app-123', name: 'notes', index_url: 'https://notes.example.com/start?mode=1' };
+    const launch = (tab, overrides = {}) => launchAppInTab({
+        name: 'notes',
+        tab,
+        guiOrigin: 'https://puter.test',
+        apiOrigin: 'https://api.puter.test',
+        authToken: 'session',
+        locale: 'fr',
+        ...overrides,
+    });
+    const arrange = ({ appRow = app, tokenResponse = { ok: true, json: async () => ({ token: 'app-token' }) } } = {}) => {
+        vi.stubGlobal('puter', { apps: { get: vi.fn(async () => appRow) } });
+        vi.stubGlobal('fetch', vi.fn(async () => tokenResponse));
+        vi.stubGlobal('$', { ajax: vi.fn() });
+    };
+    const newTab = () => ({ location: { href: '' }, postMessage: vi.fn(), closed: false });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    it('sends the tab to the app\'s URL and answers its request for the token', async () => {
+        arrange();
+        const tab = newTab();
+        expect(await launch(tab)).toBe(true);
+
+        const url = new URL(tab.location.href);
+        expect(`${url.origin}${url.pathname}`).toBe('https://notes.example.com/start');
+        expect(Object.fromEntries(url.searchParams)).toMatchObject({
+            'mode': '1',
+            'puter.app.id': 'app-123',
+            'puter.app.name': 'notes',
+            'puter.domain': 'puter.test',
+            'puter.origin': 'https://puter.test',
+            'puter.api_origin': 'https://api.puter.test',
+            'puter.locale': 'fr',
+            'puter.args': '{}',
+            'utm_source': 'puter.com',
+            'utm_medium': 'referral',
+            'utm_campaign': 'app_browser_embed',
+        });
+        expect(url.searchParams.has('puter.auth.token')).toBe(false);
+        expect(fetch).toHaveBeenCalledWith('https://api.puter.test/auth/get-user-app-token', expect.objectContaining({
+            headers: expect.objectContaining({ 'Authorization': 'Bearer session' }),
+        }));
+        expect($.ajax).toHaveBeenCalledWith(expect.objectContaining({ url: 'https://api.puter.test/rao' }));
+
+        const appInstanceID = url.searchParams.get('puter.app_instance_id');
+        request({ appInstanceID, source: tab, origin: 'https://notes.example.com' });
+        expect(tab.postMessage).toHaveBeenCalledWith(
+            expect.objectContaining({ msg: 'puter.launch', appInstanceID, token: 'app-token', item: null }),
+            'https://notes.example.com',
+        );
+    });
+
+    it.each([
+        ['a built-in app', { ...app, index_url: 'https://builtins.namespaces.puter.com/settings' }],
+        ['a godmode app', { ...app, godmode: 1 }],
+        ['a private app the user can\'t open', { ...app, privateAccess: { hasAccess: false } }],
+    ])('leaves %s to the desktop', async (_label, appRow) => {
+        arrange({ appRow });
+        const tab = newTab();
+        expect(await launch(tab)).toBe(false);
+        expect(tab.location.href).toBe('');
+        expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('leaves the tab alone when the token can\'t be fetched', async () => {
+        arrange({ tokenResponse: { ok: false, status: 500, json: async () => ({}) } });
+        const tab = newTab();
+        expect(await launch(tab)).toBe(false);
+        expect(tab.location.href).toBe('');
+        expect($.ajax).not.toHaveBeenCalled();
+    });
+
+    it('calls the launch off when the user closed the tab meanwhile', async () => {
+        arrange();
+        const tab = { ...newTab(), closed: true };
+        expect(await launch(tab)).toBe(false);
+        expect(tab.location.href).toBe('');
+        expect($.ajax).not.toHaveBeenCalled();
+    });
+});

src/gui/src/helpers/generateFileContextMenu.js

@@ -44,6 +44,7 @@ import { is_default_app } from './defaultApp.js';
  * @param {Array} options.suggested_apps - Optional pre-loaded suggested apps
  * @param {string} options.associated_app_name - Optional associated app
  * @param {Function} options.onOpen - Optional custom open handler (used by Dashboard)
+ * @param {boolean} options.openWithInNewTab - Open the "Open With" apps in a new browser tab instead of an in-page window (used by Dashboard)
  * @param {Function} options.onShowProperties - Optional custom properties handler (used by Dashboard); receives {name, path, uid, element}
  * @param {Function} options.onShare - Optional custom share handler (used by Dashboard); receives {name, path, uid, element}
  * @param {Function} options.onPublishWebsite - Optional custom publish-as-website handler (used by Dashboard); receives {uid, name, path}
@@ -118,7 +119,9 @@ const generate_file_context_menu = async function (options) {
     // Open With
     // -------------------------------------------
     if ( !is_trashed && !is_trash && (options.associated_app_name === null || options.associated_app_name === undefined) ) {
-        const openWithItems = await generateOpenWithItems(el_item, fsentry, options.suggested_apps);
+        const openWithItems = await generateOpenWithItems(el_item, fsentry, options.suggested_apps, {
+            inNewTab: !! options.openWithInNewTab,
+        });
         menu_items.push({
             html: i18n('open_with'),
             items: openWithItems,
@@ -504,7 +507,7 @@ const generate_file_context_menu = async function (options) {
  * @param {Array} suggested_apps - Optional pre-loaded suggested apps
  * @returns {Promise<Array>} Array of menu items for "Open With" submenu
  */
-async function generateOpenWithItems (el_item, fsentry, suggested_apps) {
+async function generateOpenWithItems (el_item, fsentry, suggested_apps, { inNewTab = false } = {}) {
     let items = [];
 
     // Try to find suitable apps if not provided
@@ -530,15 +533,21 @@ async function generateOpenWithItems (el_item, fsentry, suggested_apps) {
                 icon: `<img src="${html_encode(suggested_app.icon ?? window.icons['app.svg'])}" style="width:16px; height: 16px; margin-bottom: -4px;">`,
                 onClick: async function () {
                     var extension = path.extname($(el_item).attr('data-path')).toLowerCase();
-                    if (
+                    const asks_to_make_default =
                         ! is_default_app(window.user_preferences[`default_apps${extension}`], suggested_app)
                         &&
                         (
                             (!window.user_preferences[`default_apps${extension}`] && index > 0)
                             ||
                             (window.user_preferences[`default_apps${extension}`])
-                        )
-                    ) {
+                        );
+                    // A tab has to be opened while a click still counts as a
+                    // user gesture, or the popup blocker refuses it: this one,
+                    // or the answer to the prompt below. Refused, the app
+                    // opens in-page. Without 'noopener': the app asks this
+                    // tab for its token (see launch_app).
+                    let newTab = inNewTab && ! asks_to_make_default ? window.open('', '_blank') : null;
+                    if ( asks_to_make_default ) {
                         const alert_resp = await UIAlert({
                             message: `${i18n('change_always_open_with')} ${html_encode(suggested_app.title)}?`,
                             body_icon: suggested_app.icon,
@@ -557,12 +566,14 @@ async function generateOpenWithItems (el_item, fsentry, suggested_apps) {
                             window.user_preferences[`default_apps${extension}`] = suggested_app.uuid;
                             window.mutate_user_preferences(window.user_preferences);
                         }
+                        if ( inNewTab ) newTab = window.open('', '_blank');
                     }
                     launch_app({
                         name: suggested_app.name,
                         file_path: $(el_item).attr('data-path'),
                         window_title: $(el_item).attr('data-name'),
                         file_uid: $(el_item).attr('data-uid'),
+                        ...(newTab ? { newTab } : {}),
                     });
                 },
             });

src/gui/src/helpers/generateFileContextMenu.test.js

@@ -18,7 +18,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import jQuery from '../lib/jquery-3.6.1/jquery-3.6.1.min.js';
 
 vi.mock('../UI/UIAlert.js', () => ({ default: vi.fn() }));
@@ -40,14 +40,18 @@ vi.mock('./sharedAccess.js', () => ({
 
 globalThis.$ = globalThis.jQuery = jQuery;
 globalThis.i18n = (key) => key;
+globalThis.html_encode = (value) => jQuery('<div>').text(value).html();
 globalThis.def = globalThis.def ?? ((value) => value);
 globalThis.use = globalThis.use ?? (() => class {});
 window.feature_flags = {};
 window.clipboard = [];
 window.trash_path = '/me/Trash';
+window.icons = {};
 
 const { default: generate_file_context_menu } =
     await import('./generateFileContextMenu.js');
+const { default: launch_app } = await import('./launchApp.js');
+const { default: UIAlert } = await import('../UI/UIAlert.js');
 
 const sharedRow = () => {
     const row = document.createElement('div');
@@ -84,3 +88,74 @@ it('does not offer it on a share held through a team', async () => {
         'share_remove_from_shared',
     );
 });
+
+describe('Open With', () => {
+    const editor = { name: 'editor', title: 'Editor', uuid: 'app-editor' };
+    const viewer = { name: 'viewer', title: 'Viewer', uuid: 'app-viewer' };
+
+    /** Clicks the Open With entry for the app at `index`. */
+    const openWith = async (index, options = {}) => {
+        const row = sharedRow();
+        row.setAttribute('data-uid', 'file-1');
+        const items = await generate_file_context_menu({
+            element: row,
+            fsentry: { name: 'notes.txt', path: '/ann/uid-1/notes.txt' },
+            suggested_apps: [editor, viewer],
+            ...options,
+        });
+        const submenu = items.find((item) => item.html === 'open_with').items;
+        await submenu[index].onClick();
+    };
+
+    beforeEach(() => {
+        window.user_preferences = {};
+        window.mutate_user_preferences = vi.fn();
+        vi.spyOn(window, 'open').mockImplementation(() => tab);
+    });
+
+    let tab;
+    beforeEach(() => {
+        tab = { close: vi.fn() };
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+        launch_app.mockClear();
+        UIAlert.mockReset();
+    });
+
+    it('opens the app in a new tab when asked to', async () => {
+        await openWith(0, { openWithInNewTab: true });
+        expect(window.open).toHaveBeenCalledWith('', '_blank');
+        expect(launch_app).toHaveBeenCalledWith(expect.objectContaining({
+            name: 'editor',
+            file_uid: 'file-1',
+            newTab: tab,
+        }));
+    });
+
+    it('opens the tab after the make-default prompt is answered', async () => {
+        let openedBeforeAnswer = null;
+        UIAlert.mockImplementation(async () => {
+            openedBeforeAnswer = window.open.mock.calls.length > 0;
+            return 'yes';
+        });
+        await openWith(1, { openWithInNewTab: true });
+        expect(openedBeforeAnswer).toBe(false);
+        expect(window.open).toHaveBeenCalledOnce();
+        expect(window.mutate_user_preferences).toHaveBeenCalled();
+        expect(launch_app).toHaveBeenCalledWith(expect.objectContaining({ name: 'viewer', newTab: tab }));
+    });
+
+    it('opens in-page when the popup blocker refuses the tab', async () => {
+        window.open.mockReturnValue(null);
+        await openWith(0, { openWithInNewTab: true });
+        expect(launch_app.mock.calls[0][0]).not.toHaveProperty('newTab');
+    });
+
+    it('opens in-page on the desktop', async () => {
+        await openWith(0);
+        expect(window.open).not.toHaveBeenCalled();
+        expect(launch_app.mock.calls[0][0]).not.toHaveProperty('newTab');
+    });
+});

src/gui/src/helpers/launchApp.js

@@ -28,6 +28,9 @@ import { confirmUrlFileAccess } from './confirmUrlFileAccess.js';
 import { mintGodmodeToken, reusableGodmodeToken, trackGodmodeToken } from './godmodeTokens.js';
 import { withoutNotificationClick } from './notificationTap.js';
 import { syncBrowserPush } from './pushSync.js';
+import { offerAppTabLaunch } from './appTabLaunch.js';
+import { BUILTIN_PREFIX, appLaunchUrl, appendLaunchContext } from './appLaunchUrl.js';
+import { fetchUserAppTokenForLaunch, reportAppOpen } from './appLaunchApi.js';
 
 const normalizePrivateAccessDecision = (privateAccess) => {
     if ( !privateAccess || typeof privateAccess !== 'object' ) {
@@ -67,62 +70,26 @@ const endLaunchTransaction = (transaction, outcome) => {
     }
 };
 
-const fetchUserAppTokenForLaunch = async ({ appUid } = {}) => {
-    if ( ! appUid ) {
-        return {
-            token: null,
-            reason: 'missing-app-uid',
-        };
-    }
+/**
+ * Moves the app to the front of the recent apps and records the open with
+ * the server (`/rao`).
+ */
+const record_app_open = (app_info) => {
+    window.launch_apps.recent.unshift(app_info);
+    // dedupe by name, then cap at window.launch_recent_apps_count
+    window.launch_apps.recent = [...new Map(window.launch_apps.recent.map(v => [v.name, v])).values()];
+    window.launch_apps.recent = window.launch_apps.recent.slice(0, window.launch_recent_apps_count);
 
-    try {
-        const response = await fetch(`${window.api_origin }/auth/get-user-app-token`, {
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${ window.auth_token}`,
-            },
-            body: JSON.stringify({ app_uid: appUid }),
-            method: 'POST',
-        });
-
-        let responseBody;
-        try {
-            responseBody = await response.json();
-        } catch ( error ) {
-            responseBody = null;
-        }
-
-        if ( response.ok && responseBody?.token ) {
-            return {
-                token: responseBody.token,
-            };
-        }
-
-        return {
-            token: null,
-            reason: 'token-request-failed',
-            status: response.status,
-            responseCode: responseBody?.code ?? responseBody?.error?.code,
-            responseMessage: responseBody?.message ?? responseBody?.error?.message,
-            responseBody,
-            attempts: 1,
-        };
-    } catch ( error ) {
-        return {
-            token: null,
-            reason: 'network-error',
-            error,
-            attempts: 1,
-        };
-    }
+    reportAppOpen({ appUid: app_info.uid ?? app_info.uuid, socketId: window.socket?.id });
 };
 
-/**
- * Launches an app.
- *
- * @param {*} options.name - The name of the app to launch.
- */
-const launch_app = async (options) => {
+/** The `puter.item.*` params held back from a tab's URL, or null when none. */
+const heldBackItem = (item_params) => {
+    const item = Object.fromEntries(item_params);
+    return Object.keys(item).length ? item : null;
+};
+
+const runLaunch = async (options) => {
     let transaction;
     // Ends once the app signals over IPC, i.e. when it can actually be used.
     // Only apps built on the SDK ever signal, so this one is deliberately
@@ -195,6 +162,13 @@ const launch_app = async (options) => {
     app_info.uuid = app_info.uuid ?? app_info.uid;
     app_info.uid = app_info.uid ?? app_info.uuid;
 
+    if ( options.newTab && (options.name === 'explorer' || options.name === 'trash'
+        || app_info.index_url?.startsWith(BUILTIN_PREFIX)) ) {
+        options.newTab.close();
+        options.newTab = undefined;
+    }
+    const newTab = options.newTab;
+
     // If no `options.name` is provided, use the app name from the app_info
     options.name = options.name ?? app_info.name;
     const resolvedAppName = { 'launch.app': options.name ?? 'unknown' };
@@ -208,7 +182,7 @@ const launch_app = async (options) => {
         const fallbackArgs = privateAccessDecision.fallbackArgs ?? {};
 
         if ( fallbackAppName && privateLaunchRedirectDepth < 1 && fallbackAppName !== options.name ) {
-            const fallbackLaunchOutcome = await launch_app({
+            const fallbackLaunchOutcome = await runLaunch({
                 ...options,
                 name: fallbackAppName,
                 args: fallbackArgs,
@@ -242,6 +216,8 @@ const launch_app = async (options) => {
             return fallbackLaunchOutcome ?? { launchResult: redirectedLaunchResult };
         }
 
+        // The alert shows on this page, which a blank tab in front would hide.
+        newTab?.close();
         // Unencoded: UIAlert encodes its message itself.
         const deniedAppTitle = app_info.title ?? app_info.name ?? options.name;
         await UIAlert(deniedAppTitle
@@ -442,41 +418,31 @@ const launch_app = async (options) => {
     // All other apps
     //------------------------------------
     else {
-        process = new PortalProcess({
-            uuid,
-            name: app_info.name,
-            parent: options.parent_instance_id,
-            meta: {
-                launch_options: options,
-                app_info: app_info,
-            },
-        });
-        const svc_process = globalThis.services.get('process');
-        svc_process.register(process);
+        // A new tab is outside the desktop: no process for it to track.
+        if ( ! newTab ) {
+            process = new PortalProcess({
+                uuid,
+                name: app_info.name,
+                parent: options.parent_instance_id,
+                meta: {
+                    launch_options: options,
+                    app_info: app_info,
+                },
+            });
+            const svc_process = globalThis.services.get('process');
+            svc_process.register(process);
+        }
 
         //-----------------------------------
         // iframe_url
         //-----------------------------------
-        let iframe_url;
-
-        // This can be any trusted URL that won't be used for other apps
-        const BUILTIN_PREFIX = 'https://builtins.namespaces.puter.com/';
-
-        if ( ! app_info.index_url ) {
-            iframe_url = new URL(`https://${options.name}.${ window.app_domain }/index.html`);
-        } else if ( app_info.index_url.startsWith(BUILTIN_PREFIX) ) {
-            const name = app_info.index_url.slice(BUILTIN_PREFIX.length);
-            iframe_url = new URL(`${window.gui_origin}/builtin/${name}`);
-        } else {
-            iframe_url = new URL(app_info.index_url);
-        }
-
-        // add app_instance_id to URL
-        iframe_url.searchParams.append('puter.app_instance_id', uuid);
-
-        // add app_id to URL
-        iframe_url.searchParams.append('puter.app.id', app_info.uuid);
-        iframe_url.searchParams.append('puter.app.name', app_info.name);
+        const iframe_url = appLaunchUrl({
+            app: app_info,
+            name: options.name,
+            appInstanceID: uuid,
+            guiOrigin: window.gui_origin,
+            appDomain: window.app_domain,
+        });
 
         // add parent_app_instance_id to URL
         if ( options.parent_instance_id ) {
@@ -497,17 +463,20 @@ const launch_app = async (options) => {
             iframe_url.searchParams.append('puter.source_app.name', options.source_app_name);
         }
 
+        // A tab's URL would land the item's signed read/write URLs (which
+        // don't expire) in browser history, so a tab gets them with its token.
+        const item_params = newTab ? new URLSearchParams() : iframe_url.searchParams;
         if ( file_signature ) {
             append_signed_item_params(
-                iframe_url.searchParams,
+                item_params,
                 file_signature,
                 options.file_path ? privacy_aware_path(options.file_path) : file_signature.path,
             );
         }
         else if ( options.readURL ) {
-            iframe_url.searchParams.append('puter.item.name', options.filename);
-            iframe_url.searchParams.append('puter.item.path', privacy_aware_path(options.file_path));
-            iframe_url.searchParams.append('puter.item.read_url', options.readURL);
+            item_params.append('puter.item.name', options.filename);
+            item_params.append('puter.item.path', privacy_aware_path(options.file_path));
+            item_params.append('puter.item.read_url', options.readURL);
         }
 
         const is_godmode = app_info.godmode === true || app_info.godmode === 1;
@@ -522,10 +491,13 @@ const launch_app = async (options) => {
                 ?? await mintGodmodeToken(launch_app_uid);
             if ( godmode_token.ok ) {
                 launch_token = godmode_token.token;
-                trackGodmodeToken(
-                    uuid, launch_app_uid, godmode_token.token,
-                    godmode_token.expiresAt, godmode_token.mintedAt, iframe_url.href,
-                );
+                // Renewal is posted to the app's window, which a tab doesn't have.
+                if ( ! newTab ) {
+                    trackGodmodeToken(
+                        uuid, launch_app_uid, godmode_token.token,
+                        godmode_token.expiresAt, godmode_token.mintedAt, iframe_url.href,
+                    );
+                }
             } else {
                 tokenResult = { token: null, reason: 'godmode-token-request-failed', ...godmode_token };
             }
@@ -537,7 +509,11 @@ const launch_app = async (options) => {
         }
 
         if ( launch_token ) {
-            iframe_url.searchParams.append('puter.auth.token', launch_token);
+            // A tab's URL would land the token in browser history; the tab
+            // asks for it instead (offered below).
+            if ( ! newTab ) {
+                iframe_url.searchParams.append('puter.auth.token', launch_token);
+            }
             if ( is_godmode ) {
                 iframe_url.searchParams.append('puter.auth.username', window.user.username);
             }
@@ -548,6 +524,8 @@ const launch_app = async (options) => {
                 tokenResult,
             });
 
+            // The alert shows on this page, which a blank tab in front would hide.
+            newTab?.close();
             const tokenErrorAppTitle = app_info?.title ?? app_info?.name ?? options?.name;
             await UIAlert(tokenErrorAppTitle
                 ? i18n('app_launch_failed_retry', { app: tokenErrorAppTitle }, false)
@@ -568,44 +546,65 @@ const launch_app = async (options) => {
             return { launchResult: tokenFailureLaunchResult };
         }
 
-        iframe_url.searchParams.append('puter.domain', window.app_domain);
+        appendLaunchContext(iframe_url, {
+            appDomain: window.app_domain,
+            pageUrl: window.location.href,
+            apiOrigin: window.api_origin,
+            params: options.params,
+            locale: window.locale,
+            args: withoutNotificationClick(options.args),
+            surface: window.is_dashboard_mode ? 'dashboard' : 'desktop',
+        });
 
-        // get URL parts
-        const url = new URL(window.location.href);
-
-        iframe_url.searchParams.append('puter.origin', url.origin);
-        iframe_url.searchParams.append('puter.hostname', url.hostname);
-        iframe_url.searchParams.append('puter.port', url.port);
-        iframe_url.searchParams.append('puter.protocol', url.protocol.slice(0, -1));
-
-        if ( window.api_origin )
-        {
-            iframe_url.searchParams.append('puter.api_origin', window.api_origin);
+        // Closed by the user while the launch was on its way: they called it off.
+        if ( newTab?.closed ) {
+            endLaunchTransaction(transaction, 'new-tab-closed');
+            return {
+                launchResult: {
+                    launched: false,
+                    requestedAppName,
+                    openedAppName: null,
+                    appInstanceID: null,
+                    appUid: launch_app_uid ?? null,
+                    redirectedToFallback: privateLaunchRedirectDepth > 0,
+                    deniedPrivateAccess: false,
+                    privateAccess: privateAccessDecision ?? undefined,
+                },
+            };
         }
 
-        // Add options.params to URL
-        if ( options.params ) {
-            for ( const property in options.params ) {
-                iframe_url.searchParams.append(property, options.params[property]);
+        if ( newTab ) {
+            // Marks the opened item (the uid isn't a credential), so the SDK
+            // can tell it's coming before the rest arrives.
+            if ( item_params.has('puter.item.uid') ) {
+                iframe_url.searchParams.append('puter.item.uid', item_params.get('puter.item.uid'));
             }
+            offerAppTabLaunch({
+                appInstanceID: uuid,
+                tab: newTab,
+                origin: iframe_url.origin,
+                token: launch_token,
+                item: heldBackItem(item_params),
+            });
+            newTab.location.href = iframe_url.href;
+            record_app_open(app_info);
+            // A tab never signals over IPC, so it has no interactive span to count.
+            transaction?.annotate({ 'launch.ipc_tracked': false });
+            endLaunchTransaction(transaction, 'opened-in-new-tab');
+            return {
+                launchResult: {
+                    launched: true,
+                    requestedAppName,
+                    openedAppName: options.name,
+                    appInstanceID: uuid,
+                    appUid: launch_app_uid ?? null,
+                    redirectedToFallback: privateLaunchRedirectDepth > 0,
+                    deniedPrivateAccess: false,
+                    privateAccess: privateAccessDecision ?? undefined,
+                },
+            };
         }
 
-        // Add locale to URL
-        iframe_url.searchParams.append('puter.locale', window.locale);
-
-        // Newer IPC dialogs this GUI can answer, comma-separated. The SDK
-        // consults this before posting a message an older GUI has no handler
-        // for: such a message is never replied to, and a reply timeout can't
-        // stand in for the check because legitimate replies only arrive when
-        // the user closes the dialog.
-        iframe_url.searchParams.append('puter.gui_features', 'feedback-dialog,enable-push,custom-domains,push-status,disable-push');
-
-        // Add options.args to URL
-        iframe_url.searchParams.append('puter.args', JSON.stringify(withoutNotificationClick(options.args) ?? {}));
-
-        // ...and finally append utm_source=puter.com to the URL
-        iframe_url.searchParams.append('utm_source', 'puter.com');
-
         // register app_instance_uid
         window.app_instance_ids.add(uuid);
 
@@ -763,31 +762,8 @@ const launch_app = async (options) => {
             void syncBrowserPush({ appUid: launch_app_uid });
         }
 
-        // send post request to /rao to record app open
         if ( options.name !== 'explorer' ) {
-            // add the app to the beginning of the array
-            window.launch_apps.recent.unshift(app_info);
-
-            // dedupe the array by uuid, uid, and id
-            window.launch_apps.recent = [...new Map(window.launch_apps.recent.map(v => [v.name, v])).values()];
-
-            // limit to window.launch_recent_apps_count
-            window.launch_apps.recent = window.launch_apps.recent.slice(0, window.launch_recent_apps_count);
-
-            // send post request to /rao to record app open
-            $.ajax({
-                url: `${window.api_origin }/rao`,
-                type: 'POST',
-                data: JSON.stringify({
-                    original_client_socket_id: window.socket?.id,
-                    app_uid: app_info.uid ?? app_info.uuid,
-                }),
-                async: true,
-                contentType: 'application/json',
-                headers: {
-                    'Authorization': `Bearer ${window.auth_token}`,
-                },
-            });
+            record_app_open(app_info);
         }
     }
 
@@ -866,4 +842,27 @@ const launch_app = async (options) => {
     return process;
 };
 
+/**
+ * Launches an app.
+ *
+ * @param {*} options.name - The name of the app to launch.
+ * @param {Window} [options.newTab] - A tab the caller opened (synchronously,
+ *   so popup blockers allow it, and without `noopener`, so the app can ask it
+ *   for its token and opened item) to send the app's URL to, instead of
+ *   opening an in-page window. The launch owns the tab: it is closed when the
+ *   launch fails. Explorer and built-in apps are part of the desktop, so for
+ *   them the tab is closed and the app opens in-page.
+ */
+const launch_app = async (options) => {
+    const tab = options.newTab;
+    try {
+        const outcome = await runLaunch(options);
+        if ( tab && getLaunchResult(outcome)?.launched === false ) tab.close();
+        return outcome;
+    } catch ( err ) {
+        tab?.close();
+        throw err;
+    }
+};
+
 export default launch_app;

src/gui/src/helpers/launchApp.test.js

@@ -0,0 +1,244 @@
+// @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';
+
+vi.mock('../UI/UIWindow.js', () => ({ default: vi.fn() }));
+vi.mock('../UI/UIAlert.js', () => ({ default: vi.fn() }));
+vi.mock('./pushSync.js', () => ({ syncBrowserPush: vi.fn() }));
+vi.mock('./appTabLaunch.js', () => ({ offerAppTabLaunch: vi.fn() }));
+
+globalThis.def = globalThis.def ?? (value => value);
+
+const { default: UIWindow } = await import('../UI/UIWindow.js');
+const { default: UIAlert } = await import('../UI/UIAlert.js');
+const { offerAppTabLaunch } = await import('./appTabLaunch.js');
+const { default: launch_app } = await import('./launchApp.js');
+
+const app = {
+    uid: 'app-123',
+    name: 'notes',
+    title: 'Notes',
+    index_url: 'https://notes.example.com/start?mode=1',
+};
+
+let register;
+let transactions;
+
+beforeEach(() => {
+    register = vi.fn();
+    globalThis.i18n = key => key;
+    globalThis.$ = { ajax: vi.fn() };
+    transactions = [];
+    window.Transaction = class {
+        constructor (name, attributes) {
+            this.name = name;
+            this.attributes = { ...attributes };
+            transactions.push(this);
+        }
+        start () {}
+        annotate (attributes) {
+            Object.assign(this.attributes, attributes);
+        }
+        end () {}
+    };
+    window.uuidv4 = () => 'instance-1';
+    window.icons = {};
+    window.app_domain = 'puter.app';
+    window.api_origin = 'https://api.puter.test';
+    window.auth_token = 'session';
+    window.locale = 'en';
+    window.launch_apps = { recent: [] };
+    window.launch_recent_apps_count = 5;
+    window.app_instance_ids = new Set();
+    globalThis.services = { get: () => ({ register }) };
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+        ok: true,
+        json: async () => ({ token: 'app-token' }),
+    })));
+});
+
+afterEach(() => {
+    delete window.is_dashboard_mode;
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+});
+
+describe('launch_app with a new tab', () => {
+    it('sends the tab to index_url with the params an in-page iframe gets, minus the token', async () => {
+        const tab = { location: { href: '' }, close: vi.fn() };
+        const outcome = await launch_app({ name: 'notes', app_obj: { ...app }, newTab: tab });
+
+        const url = new URL(tab.location.href);
+        expect(`${url.origin}${url.pathname}`).toBe('https://notes.example.com/start');
+        expect(Object.fromEntries(url.searchParams)).toMatchObject({
+            'mode': '1',
+            'puter.app_instance_id': 'instance-1',
+            'puter.app.id': 'app-123',
+            'puter.app.name': 'notes',
+            'puter.domain': 'puter.app',
+            'puter.api_origin': 'https://api.puter.test',
+            'puter.locale': 'en',
+            'puter.args': '{}',
+            'utm_source': 'puter.com',
+        });
+        expect(url.searchParams.has('puter.auth.token')).toBe(false);
+        expect(offerAppTabLaunch).toHaveBeenCalledWith({
+            appInstanceID: 'instance-1',
+            tab,
+            origin: 'https://notes.example.com',
+            token: 'app-token',
+            item: null,
+        });
+        expect(outcome.launchResult).toMatchObject({ launched: true, openedAppName: 'notes' });
+        expect(UIWindow).not.toHaveBeenCalled();
+        expect(register).not.toHaveBeenCalled();
+        expect(window.app_instance_ids.size).toBe(0);
+        expect(window.launch_apps.recent[0].name).toBe('notes');
+        expect($.ajax).toHaveBeenCalledWith(expect.objectContaining({ url: 'https://api.puter.test/rao' }));
+    });
+
+    it.each([
+        [false, 'desktop'],
+        [true, 'dashboard'],
+    ])('tags the launch with the surface it came from (dashboard mode: %s)', async (dashboardMode, campaign) => {
+        window.is_dashboard_mode = dashboardMode;
+        const tab = { location: { href: '' }, close: vi.fn() };
+        await launch_app({ name: 'notes', app_obj: { ...app }, newTab: tab });
+
+        const url = new URL(tab.location.href);
+        expect(Object.fromEntries(url.searchParams)).toMatchObject({
+            'utm_source': 'puter.com',
+            'utm_medium': 'referral',
+            'utm_campaign': campaign,
+        });
+    });
+
+    it('counts the launch as one with no interactive span to wait for', async () => {
+        const tab = { location: { href: '' }, close: vi.fn() };
+        await launch_app({ name: 'notes', app_obj: { ...app }, newTab: tab });
+
+        const ready = transactions.find(t => t.name === 'app-is-ready');
+        expect(ready.attributes).toMatchObject({
+            'launch.ipc_tracked': false,
+            outcome: 'opened-in-new-tab',
+        });
+    });
+
+    it('hands the opened file over with the token, keeping its signed URLs out of the tab URL', async () => {
+        const tab = { location: { href: '' }, close: vi.fn() };
+        window.privacy_aware_path = p => p;
+        await launch_app({
+            name: 'notes',
+            app_obj: { ...app },
+            newTab: tab,
+            file_path: '~/notes.txt',
+            token: 'file-token',
+            file_signature: {
+                uid: 'file-1',
+                fsentry_name: 'notes.txt',
+                read_url: 'https://api.puter.test/file?signature=r',
+                write_url: 'https://api.puter.test/writeFile?signature=w',
+                metadata_url: 'https://api.puter.test/itemMetadata?signature=r',
+            },
+        });
+
+        const url = new URL(tab.location.href);
+        expect([...url.searchParams.keys()].filter(k => k.startsWith('puter.item.'))).toEqual(['puter.item.uid']);
+        expect(url.searchParams.get('puter.item.uid')).toBe('file-1');
+        expect(offerAppTabLaunch).toHaveBeenCalledWith(expect.objectContaining({
+            token: 'file-token',
+            item: expect.objectContaining({
+                'puter.item.uid': 'file-1',
+                'puter.item.name': 'notes.txt',
+                'puter.item.path': '~/notes.txt',
+                'puter.item.read_url': 'https://api.puter.test/file?signature=r',
+                'puter.item.write_url': 'https://api.puter.test/writeFile?signature=w',
+            }),
+        }));
+    });
+
+    it('closes the tab when the app token is unavailable', async () => {
+        fetch.mockResolvedValue({ ok: false, status: 500, json: async () => ({}) });
+        const tab = { location: { href: '' }, close: vi.fn() };
+        const log = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const outcome = await launch_app({ name: 'notes', app_obj: { ...app }, newTab: tab });
+        log.mockRestore();
+
+        expect(outcome.launchResult.launched).toBe(false);
+        expect(tab.location.href).toBe('');
+        expect(tab.close).toHaveBeenCalled();
+        expect(offerAppTabLaunch).not.toHaveBeenCalled();
+    });
+
+    it('calls the launch off when the user closed the tab meanwhile', async () => {
+        const tab = { location: { href: '' }, close: vi.fn(), closed: true };
+        const outcome = await launch_app({ name: 'notes', app_obj: { ...app }, newTab: tab });
+
+        expect(outcome.launchResult.launched).toBe(false);
+        expect(tab.location.href).toBe('');
+        expect(offerAppTabLaunch).not.toHaveBeenCalled();
+        expect(window.launch_apps.recent).toEqual([]);
+        expect($.ajax).not.toHaveBeenCalled();
+        expect(UIAlert).not.toHaveBeenCalled();
+    });
+
+    it.each([
+        ['the app token is unavailable', { ...app }, () => {
+            fetch.mockResolvedValue({ ok: false, status: 500, json: async () => ({}) });
+        }],
+        ['access to a private app is denied', {
+            ...app,
+            privateAccess: { hasAccess: false },
+        }, () => {}],
+    ])('closes the tab before alerting that %s', async (_label, app_obj, arrange) => {
+        arrange();
+        const tab = { location: { href: '' }, close: vi.fn() };
+        let tabClosedAtAlert;
+        UIAlert.mockImplementation(async () => {
+            tabClosedAtAlert = tab.close.mock.calls.length > 0;
+        });
+        const log = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const outcome = await launch_app({ name: 'notes', app_obj, newTab: tab });
+        log.mockRestore();
+
+        expect(outcome.launchResult.launched).toBe(false);
+        expect(UIAlert).toHaveBeenCalledOnce();
+        expect(tabClosedAtAlert).toBe(true);
+    });
+
+    it('closes the tab and opens a built-in app in-page', async () => {
+        const tab = { location: { href: '' }, close: vi.fn() };
+        const builtin = { ...app, index_url: 'https://builtins.namespaces.puter.com/dev-center' };
+        window.gui_origin = 'https://puter.test';
+        // Everything after the window opens isn't what this test is about.
+        UIWindow.mockImplementation(() => {
+            throw new Error('in-page window');
+        });
+        await expect(launch_app({ name: 'notes', app_obj: builtin, newTab: tab }))
+            .rejects.toThrow('in-page window');
+
+        expect(tab.close).toHaveBeenCalled();
+        expect(tab.location.href).toBe('');
+        expect(UIWindow).toHaveBeenCalledWith(expect.objectContaining({
+            iframe_url: expect.stringContaining('puter.auth.token=app-token'),
+        }));
+    });
+});

src/gui/src/helpers/notificationFeed.js

@@ -47,13 +47,13 @@ const receiptLog = (sdk) =>
 export const notificationSocketAcks = (sdk = globalThis.puter) =>
     receiptLog(sdk) ? ['notif.receipt'] : [];
 
-/** Notes each live `notif.message` in the receipt log and answers the server's asks from it. */
+/** Notes each live `notif.message` in the receipt log, reporting over `socket` one the desktop handled, and answers the server's asks from it. */
 export const answerNotificationReceipts = (socket, sdk = globalThis.puter) => {
     const log = receiptLog(sdk);
     if ( ! log ) return;
     socket.on('notif.message', (message) => {
         if ( typeof message?.uid !== 'string' ) return;
-        if ( ! isAppOnlyNotification(message.notification) ) log._noteReceived(message.uid);
+        if ( ! isAppOnlyNotification(message.notification) ) log._noteReceived(message.uid, undefined, socket);
     });
     socket.on('notif.receipt', (data, ack) => log._answerReceipt(data, ack));
 };

src/gui/src/helpers/notificationFeed.test.js

@@ -407,7 +407,7 @@ describe('notification receipts', () => {
         expect(notificationSocketAcks(undefined)).toEqual([]);
     });
 
-    it('notes each live notif.message and answers asks from the log', () => {
+    it('notes each live notif.message with the socket it came on and answers asks from the log', () => {
         const sdk = sdkWithLog();
         const socket = fakeSocket();
         answerNotificationReceipts(socket, sdk);
@@ -416,7 +416,7 @@ describe('notification receipts', () => {
         const ack = vi.fn();
         socket.handlers['notif.receipt'][0]({ uid: 'n-1' }, ack);
 
-        expect(sdk.notifications._noteReceived).toHaveBeenCalledWith('n-1');
+        expect(sdk.notifications._noteReceived).toHaveBeenCalledWith('n-1', undefined, socket);
         expect(sdk.notifications._answerReceipt).toHaveBeenCalledWith({ uid: 'n-1' }, ack);
     });
 
@@ -429,7 +429,7 @@ describe('notification receipts', () => {
         socket.handlers['notif.message'][0]({ uid: 'n-3', notification: { type: 'share.received' } });
 
         expect(sdk.notifications._noteReceived).toHaveBeenCalledTimes(1);
-        expect(sdk.notifications._noteReceived).toHaveBeenCalledWith('n-3');
+        expect(sdk.notifications._noteReceived).toHaveBeenCalledWith('n-3', undefined, socket);
     });
 
     it('registers nothing with a puter.js that has no log', () => {

src/gui/src/helpers/openItem.js

@@ -29,7 +29,7 @@ import { is_window_on_screen, user_facing_windows } from './windowVisibility.js'
 // Files whose app launch is still in flight, by file uid. Between the click
 // and the window's creation there is nothing in the DOM to restore, so a
 // re-click during that stretch would mint a duplicate instance — mark the
-// launch and swallow re-clicks instead (same idea as TabApps._launchingApps).
+// launch and swallow re-clicks instead (same idea as _launchingApps in AppBrowser.js).
 // Entries carry a timestamp so a launch that dies without settling (an
 // unexpected throw before launch_app is reached) can't swallow clicks forever.
 const launching_file_uids = new Map();
@@ -44,7 +44,14 @@ const file_launch_in_flight = (uid) => {
     return true;
 };
 
-const open_item = async function (options) {
+const runOpen = async function (options) {
+    // The tab goes to the first launch that takes it; open_item closes it if
+    // nothing does.
+    const take_tab = () => {
+        const tab = options.newTab;
+        options.newTab = undefined;
+        return tab;
+    };
     let el_item = options.item;
     const $el_parent_window = $(el_item).closest('.window');
     const parent_win_id = $($el_parent_window).attr('data-id');
@@ -65,7 +72,7 @@ const open_item = async function (options) {
     //----------------------------------------------------------------
     const app_name = $(el_item).attr('data-app');
     if ( app_name ) {
-        launch_app({ name: app_name });
+        launch_app({ name: app_name, newTab: take_tab() });
         return;
     }
 
@@ -78,7 +85,7 @@ const open_item = async function (options) {
             const text = typeof content === 'string' ? content : await content.text();
             const data = JSON.parse(text);
             if ( data.app ) {
-                launch_app({ name: data.app });
+                launch_app({ name: data.app, newTab: take_tab() });
                 return;
             }
         } catch (e) {
@@ -160,7 +167,14 @@ const open_item = async function (options) {
 
             // If we have a valid URL, open it
             if ( url && (url.startsWith('http://') || url.startsWith('https://')) ) {
-                window.open(url, '_blank', 'noopener,noreferrer');
+                const tab = take_tab();
+                if ( tab ) {
+                    // A link the user saved, not an app: it gets no way back here.
+                    tab.opener = null;
+                    tab.location.href = url;
+                } else {
+                    window.open(url, '_blank', 'noopener,noreferrer');
+                }
             } else {
                 // Show a more detailed error message
                 UIAlert(`Could not determine the URL for this web shortcut.
@@ -269,13 +283,15 @@ Please try recreating the link.`);
     // The user's own windows only: a file opened in an instance another app
     // launched in the background is not a window the row can switch to, so the
     // click launches the file the normal way instead of surfacing that one.
+    // Opening in a tab only swallows the re-click: the tab is where the
+    // file goes, whatever windows have it open in the page.
     else if ( window.is_dashboard_mode && !associated_app_name && target_file_uid
-        && (user_facing_windows($(`.window[data-file_uid="${html_encode(target_file_uid)}"]`)).length
+        && ((!options.newTab && user_facing_windows($(`.window[data-file_uid="${html_encode(target_file_uid)}"]`)).length)
             || file_launch_in_flight(target_file_uid)) ) {
         const $win = $(user_facing_windows($(`.window[data-file_uid="${html_encode(target_file_uid)}"]`))).last();
         // No window yet means the first click's launch is still in
         // flight — swallow the re-click instead of duplicating it.
-        if ( $win.length ) {
+        if ( $win.length && !options.newTab ) {
             if ( is_window_on_screen($win.get(0)) ) {
                 $win.focusWindow();
             } else {
@@ -290,6 +306,7 @@ Please try recreating the link.`);
         launch_app({
             name: associated_app_name,
             maximized: options.maximized ?? window.is_dashboard_mode,
+            newTab: take_tab(),
         });
     }
     //----------------------------------------------------------------
@@ -342,6 +359,7 @@ Please try recreating the link.`);
                 window_title: path.basename(item_path),
                 maximized: options.maximized ?? window.is_dashboard_mode,
                 file_uid: file_uid,
+                newTab: take_tab(),
             });
             if ( target_file_uid ) launch_promise.finally(() => launching_file_uids.delete(target_file_uid));
             return;
@@ -378,8 +396,10 @@ Please try recreating the link.`);
         // download
         //---------------------------------------------
         if ( suggested_apps.length === 0 ) {
-            // Not launching after all — lift the in-flight guard.
+            // Not launching after all — lift the in-flight guard, and don't
+            // leave a blank tab open behind the prompt.
             if ( target_file_uid ) launching_file_uids.delete(target_file_uid);
+            take_tab()?.close();
             //---------------------------------------------
             // If .zip file, unzip it
             //---------------------------------------------
@@ -424,10 +444,30 @@ Please try recreating the link.`);
                 file_uid: fsuid,
                 maximized: options.maximized ?? window.is_dashboard_mode,
                 file_signature: open_item_meta.signature,
+                newTab: take_tab(),
             });
             if ( target_file_uid ) launch_promise.finally(() => launching_file_uids.delete(target_file_uid));
         }
     }
 };
 
+/**
+ * Opens an item: enters a folder, or opens a file or app.
+ *
+ * @param {object} options
+ * @param {HTMLElement} options.item - the item's element
+ * @param {Window} [options.newTab] - a blank tab the caller opened inside the
+ *   user's gesture; an app the item opens in goes there instead of an in-page
+ *   window (see launch_app). Closed when the item opens no app.
+ * @param {boolean} [options.maximized]
+ * @param {boolean} [options.new_window]
+ */
+const open_item = async function (options) {
+    try {
+        return await runOpen(options);
+    } finally {
+        options.newTab?.close();
+    }
+};
+
 export default open_item;

src/gui/src/helpers/openItem.test.js

@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import jQuery from '../lib/jquery-3.6.1/jquery-3.6.1.min.js';
+
+vi.mock('../UI/UIWindow.js', () => ({ default: vi.fn() }));
+vi.mock('../UI/UIAlert.js', () => ({ default: vi.fn(async () => undefined) }));
+vi.mock('../i18n/i18n.js', () => ({ default: key => key }));
+vi.mock('./launchApp.js', () => ({ default: vi.fn(async () => ({ launchResult: { launched: true } })) }));
+vi.mock('./itemIcon.js', () => ({ default: vi.fn() }));
+vi.mock('./defaultApp.js', () => ({ resolve_default_app: vi.fn(async () => null) }));
+
+globalThis.$ = globalThis.jQuery = jQuery;
+globalThis.html_encode = value => jQuery('<div>').text(value).html();
+
+const { default: launch_app } = await import('./launchApp.js');
+const { default: UIAlert } = await import('../UI/UIAlert.js');
+const { resolve_default_app } = await import('./defaultApp.js');
+const { default: open_item } = await import('./openItem.js');
+
+const row = ({ name = 'notes.txt', path = '/user/notes.txt', uid = 'file-1' } = {}) => {
+    const el = document.createElement('div');
+    for ( const [key, value] of Object.entries({
+        'data-uid': uid,
+        'data-path': path,
+        'data-name': name,
+        'data-is_dir': '0',
+        'data-shortcut_to': '',
+        'data-shortcut_to_path': '',
+        'data-associated_app_name': '',
+    }) ) {
+        el.setAttribute(key, value);
+    }
+    document.body.appendChild(el);
+    return el;
+};
+
+const newTab = () => ({ opener: window, location: { href: '' }, close: vi.fn() });
+
+beforeEach(() => {
+    window.trash_path = '/user/Trash';
+    window.is_dashboard_mode = true;
+    window.api_origin = 'https://api.puter.test';
+    jQuery.ajax = vi.fn(async () => null);
+    window.suggest_apps_for_fsentry = vi.fn(async () => []);
+});
+
+afterEach(() => {
+    vi.clearAllMocks();
+    document.body.innerHTML = '';
+});
+
+describe('open_item with a new tab', () => {
+    it("hands the tab to the file's default app", async () => {
+        const app = { name: 'editor' };
+        resolve_default_app.mockResolvedValueOnce(app);
+        const tab = newTab();
+        await open_item({ item: row(), newTab: tab });
+
+        expect(launch_app).toHaveBeenCalledWith(expect.objectContaining({
+            name: 'editor',
+            file_uid: 'file-1',
+            newTab: tab,
+        }));
+        expect(tab.close).not.toHaveBeenCalled();
+    });
+
+    it('closes the tab before offering a download when no app opens the file', async () => {
+        const tab = newTab();
+        let closedBeforeAlert = false;
+        UIAlert.mockImplementation(async () => {
+            closedBeforeAlert = tab.close.mock.calls.length === 1;
+        });
+        await open_item({ item: row({ name: 'data.bin', path: '/user/data.bin' }), newTab: tab });
+
+        expect(launch_app).not.toHaveBeenCalled();
+        expect(closedBeforeAlert).toBe(true);
+        expect(tab.close).toHaveBeenCalledOnce();
+    });
+
+    it('closes the tab for a file in the trash', async () => {
+        const tab = newTab();
+        await open_item({ item: row({ path: '/user/Trash/notes.txt' }), newTab: tab });
+        expect(tab.close).toHaveBeenCalledOnce();
+        expect(launch_app).not.toHaveBeenCalled();
+    });
+
+    it('sends the tab to a web link, cut off from the dashboard', async () => {
+        const tab = newTab();
+        localStorage.setItem('weblink_link-1', 'https://example.com/page');
+        await open_item({ item: row({ name: 'site.weblink', path: '/user/site.weblink', uid: 'link-1' }), newTab: tab });
+
+        expect(tab.opener).toBeNull();
+        expect(tab.location.href).toBe('https://example.com/page');
+        expect(tab.close).not.toHaveBeenCalled();
+    });
+});

src/gui/src/helpers/pushWorker.js

@@ -17,11 +17,9 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-// The page's side of `/sw.js`: registration, routed taps, hidden-tab banners.
+// The page's side of `/sw.js`: routed taps, and updates once push is on.
 
-import { httpsIconFor, isShareNotification } from '../UI/Dashboard/notificationCenter.js';
 import {
-    APP_MESSAGE_TYPE,
     dispatchPushTap,
     normalizePushTap,
     pushTapFromParams,
@@ -34,7 +32,6 @@ import { webPushClient } from './webPushClient.js';
 export const WORKER_URL = '/sw.js';
 export const WORKER_CLICK_MESSAGE = 'puter-notification-click';
 export const WORKER_CLICK_ACK_MESSAGE = 'puter-notification-click-ack';
-export const WORKER_SHOW_MESSAGE = 'puter-show-notification';
 
 /**
  * @param {Object} [params] - `window.gui_params`
@@ -46,91 +43,6 @@ export const pushWorkerEnabled = (params, nav) => (
     && typeof nav?.serviceWorker?.register === 'function'
 );
 
-/**
- * @param {{ replay?: boolean, acknowledged?: boolean, notification?: Object,
- *     visibilityState?: string, permission?: string }} input
- * @returns {boolean}
- */
-export const shouldShowLocalBanner = ({ replay = false, acknowledged = false, notification, visibilityState, permission }) => (
-    ! replay
-    && ! acknowledged
-    && visibilityState === 'hidden'
-    && permission === 'granted'
-    && !! notification
-    && typeof notification === 'object'
-    && notification.silent !== true
-);
-
-const nonEmpty = (value) => (typeof value === 'string' && value.trim() !== '' ? value : undefined);
-
-/**
- * @param {string} uid
- * @param {Object} notification
- * @param {string|null} [appUid] - The app the row names; wins over the value's
- * @returns {Object} The push payload shape `sw.js` shows
- */
-export const pushMessageFor = (uid, notification, appUid = null) => {
-    const group = nonEmpty(notification.group);
-    const message = { uid, group: group ?? uid };
-    if ( notification.type === APP_MESSAGE_TYPE ) {
-        const app = nonEmpty(appUid) ?? nonEmpty(notification.app?.uid);
-        // An app's group is its own, as the server names it on a push.
-        if ( app && group ) message.group = `${app}:${group}`;
-        if ( notification.sensitive === true ) {
-            return { ...message, title: nonEmpty(notification.app?.name), ...(app ? { target: { app } } : {}) };
-        }
-        const path = nonEmpty(notification.target);
-        if ( app ) message.target = { app, ...(path ? { path } : {}) };
-        if ( notification.data !== undefined ) message.data = notification.data;
-    } else if ( isShareNotification(notification) ) {
-        const path = nonEmpty(notification.fields?.target?.path);
-        if ( path ) message.target = { path };
-    }
-    const body = nonEmpty(notification.text);
-    const icon = httpsIconFor(notification);
-    return {
-        ...message,
-        title: nonEmpty(notification.title),
-        ...(body ? { body } : {}),
-        ...(icon ? { icon } : {}),
-    };
-};
-
-/**
- * Only while push is on in this browser, and only for Puter's own notifications: an app's message is shown by the app's page while it is open, and by the app's own push while it is closed.
- * @param {{ uid: string, notification: Object }} item
- * @param {{ replay?: boolean, acknowledged?: boolean }} [meta]
- * @param {{ params?: Object, doc?: Document, nav?: Navigator, NotificationApi?: { permission: string } }} [env]
- * @returns {Promise<boolean>} Whether one was handed to the worker
- */
-export const showLocalBanner = async ({ uid, notification }, { replay = false, acknowledged = false } = {}, {
-    params = globalThis.gui_params,
-    doc = globalThis.document,
-    nav = globalThis.navigator,
-    NotificationApi = globalThis.Notification,
-} = {}) => {
-    if ( ! pushWorkerEnabled(params, nav) ) return false;
-    if ( notification?.type === APP_MESSAGE_TYPE ) return false;
-    if ( ! shouldShowLocalBanner({
-        replay,
-        acknowledged,
-        notification,
-        visibilityState: doc?.visibilityState,
-        permission: NotificationApi?.permission,
-    }) ) return false;
-    try {
-        const registration = await nav.serviceWorker.getRegistration?.('/');
-        const worker = registration?.active;
-        if ( ! worker ) return false;
-        if ( ! await registration.pushManager?.getSubscription() ) return false;
-        worker.postMessage({ type: WORKER_SHOW_MESSAGE, puter: pushMessageFor(uid, notification) });
-        return true;
-    } catch ( err ) {
-        console.warn('Could not show a browser notification:', err);
-        return false;
-    }
-};
-
 let started = false;
 
 /**
@@ -164,11 +76,15 @@ export const startPushWorker = async ({
         event.source?.postMessage?.({ type: WORKER_CLICK_ACK_MESSAGE, id: event.data.id });
         dispatchPushTap(event.data.notification);
     });
+    // Turning push on registers the worker. One left without a subscription
+    // goes, so nothing but push installs it.
     try {
-        // Scripts the worker imports are fetched fresh on each update check.
-        await nav.serviceWorker.register(WORKER_URL, { scope: '/', updateViaCache: 'none' });
+        const registration = await nav.serviceWorker.getRegistration?.('/');
+        if ( ! registration ) return;
+        if ( await registration.pushManager?.getSubscription() ) await registration.update?.();
+        else await registration.unregister();
     } catch ( err ) {
-        console.warn('Could not register the service worker:', err);
+        console.warn('Could not update the service worker:', err);
     }
 };
 

src/gui/src/helpers/pushWorker.test.js

@@ -18,175 +18,13 @@
  */
 
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import {
-    closeLocalBanner,
-    pushMessageFor,
-    pushWorkerEnabled,
-    shouldShowLocalBanner,
-    showLocalBanner,
-} from './pushWorker.js';
+import { closeLocalBanner, pushWorkerEnabled } from './pushWorker.js';
 
 afterEach(() => {
     vi.resetModules();
     vi.restoreAllMocks();
 });
 
-const share = {
-    type: 'share.received',
-    title: 'alice shared a file with you',
-    icon: 'shared.svg',
-    fields: { target: { path: '/alice/Shared/a.txt', name: 'a.txt' } },
-};
-
-describe('shouldShowLocalBanner', () => {
-    const live = { notification: share, visibilityState: 'hidden', permission: 'granted' };
-
-    it('shows one for a live arrival in a hidden tab with permission', () => {
-        expect(shouldShowLocalBanner(live)).toBe(true);
-    });
-
-    it('shows none while the tab is visible', () => {
-        expect(shouldShowLocalBanner({ ...live, visibilityState: 'visible' })).toBe(false);
-    });
-
-    it('shows none for a replay, an acknowledged or a silent one', () => {
-        expect(shouldShowLocalBanner({ ...live, replay: true })).toBe(false);
-        expect(shouldShowLocalBanner({ ...live, acknowledged: true })).toBe(false);
-        expect(shouldShowLocalBanner({ ...live, notification: { ...share, silent: true } })).toBe(false);
-    });
-
-    it('shows none without permission granted', () => {
-        expect(shouldShowLocalBanner({ ...live, permission: 'default' })).toBe(false);
-        expect(shouldShowLocalBanner({ ...live, permission: 'denied' })).toBe(false);
-        expect(shouldShowLocalBanner({ ...live, permission: undefined })).toBe(false);
-    });
-});
-
-describe('pushMessageFor', () => {
-    it('targets the app and path an app message names, with its data and https icon', () => {
-        expect(pushMessageFor('n1', {
-            type: 'app.message',
-            title: 'New reply',
-            text: 'see you',
-            icon: 'https://example.com/i.png',
-            target: '/rooms/7',
-            data: { room: 7 },
-            group: 'room-7',
-            app: { uid: 'app-1', name: 'Chat' },
-        })).toEqual({
-            uid: 'n1',
-            group: 'app-1:room-7',
-            title: 'New reply',
-            body: 'see you',
-            icon: 'https://example.com/i.png',
-            target: { app: 'app-1', path: '/rooms/7' },
-            data: { room: 7 },
-        });
-    });
-
-    it('shows only the app name for a sensitive app message', () => {
-        expect(pushMessageFor('n1', {
-            type: 'app.message',
-            title: 'Code 1234',
-            text: 'secret',
-            sensitive: true,
-            app: { uid: 'app-1', name: 'Bank' },
-        })).toEqual({ uid: 'n1', group: 'n1', title: 'Bank', target: { app: 'app-1' } });
-    });
-
-    it('points a share at the item it names and drops a non-https icon', () => {
-        expect(pushMessageFor('n2', share)).toEqual({
-            uid: 'n2',
-            group: 'n2',
-            title: 'alice shared a file with you',
-            target: { path: '/alice/Shared/a.txt' },
-        });
-    });
-
-    it("tags an app message's group with its app, so two apps never share one", () => {
-        const message = (app, over = {}) => ({ type: 'app.message', title: 't', group: 'room-7', app: { uid: app }, ...over });
-        expect(pushMessageFor('n1', message('app-1')).group).toBe('app-1:room-7');
-        expect(pushMessageFor('n1', message('app-2')).group).toBe('app-2:room-7');
-        expect(pushMessageFor('n1', message('app-1', { sensitive: true })).group).toBe('app-1:room-7');
-        expect(pushMessageFor('n1', message('app-b'), 'app-a').group).toBe('app-a:room-7');
-        expect(pushMessageFor('n1', message('app-1', { group: undefined })).group).toBe('n1');
-        expect(pushMessageFor('n2', { ...share, group: 'room-7' }).group).toBe('room-7');
-    });
-
-    it("uses the row's app uid over the one the message names", () => {
-        expect(pushMessageFor('n1', { type: 'app.message', title: 't' }, 'app-9').target).toEqual({ app: 'app-9' });
-        expect(pushMessageFor('n1', { type: 'app.message', title: 't', app: { uid: 'app-b' } }, 'app-a').target)
-            .toEqual({ app: 'app-a' });
-        expect(pushMessageFor('n1', { type: 'app.message', title: 't', app: { uid: 'app-b' } }, '').target)
-            .toEqual({ app: 'app-b' });
-    });
-});
-
-describe('showLocalBanner', () => {
-    const env = ({
-        visibilityState = 'hidden',
-        permission = 'granted',
-        active = { postMessage: vi.fn() },
-        pushEnabled = true,
-        subscribed = true,
-    } = {}) => ({
-        params: { pushEnabled },
-        doc: { visibilityState },
-        NotificationApi: { permission },
-        nav: {
-            serviceWorker: {
-                register: vi.fn(),
-                getRegistration: vi.fn(async () => (active
-                    ? { active, pushManager: { getSubscription: async () => (subscribed ? {} : null) } }
-                    : undefined)),
-            },
-        },
-        active,
-    });
-
-    it('hands one notification to the worker, tagged by its uid', async () => {
-        const e = env();
-        expect(await showLocalBanner({ uid: 'n1', notification: share }, {}, e)).toBe(true);
-        expect(e.nav.serviceWorker.getRegistration).toHaveBeenCalledWith('/');
-        expect(e.active.postMessage).toHaveBeenCalledOnce();
-        expect(e.active.postMessage).toHaveBeenCalledWith({
-            type: 'puter-show-notification',
-            puter: pushMessageFor('n1', share),
-        });
-    });
-
-    it('hands nothing over while visible, for a replay, or without a worker', async () => {
-        const visible = env({ visibilityState: 'visible' });
-        expect(await showLocalBanner({ uid: 'n1', notification: share }, {}, visible)).toBe(false);
-        expect(visible.nav.serviceWorker.getRegistration).not.toHaveBeenCalled();
-
-        const replay = env();
-        expect(await showLocalBanner({ uid: 'n1', notification: share }, { replay: true }, replay)).toBe(false);
-        expect(replay.active.postMessage).not.toHaveBeenCalled();
-
-        expect(await showLocalBanner({ uid: 'n1', notification: share }, {}, env({ active: null }))).toBe(false);
-    });
-
-    it('hands nothing over while push is off in this browser', async () => {
-        const off = env({ subscribed: false });
-        expect(await showLocalBanner({ uid: 'n1', notification: share }, {}, off)).toBe(false);
-        expect(off.active.postMessage).not.toHaveBeenCalled();
-    });
-
-    it("hands nothing over for an app's message, even one from an app that may push", async () => {
-        const e = { ...env(), holdsPush: vi.fn(async () => true) };
-        const message = { type: 'app.message', title: 'Hi', text: 'see you', app: { uid: 'app-1', name: 'Chat' } };
-        expect(await showLocalBanner({ uid: 'n1', notification: message, appUid: 'app-1' }, {}, e)).toBe(false);
-        expect(e.active.postMessage).not.toHaveBeenCalled();
-    });
-
-    it('hands nothing over where push is off for the deployment', async () => {
-        const off = env({ pushEnabled: false });
-        expect(await showLocalBanner({ uid: 'n1', notification: share }, {}, off)).toBe(false);
-        expect(off.nav.serviceWorker.getRegistration).not.toHaveBeenCalled();
-    });
-});
-
 describe('pushWorkerEnabled', () => {
     it('needs the deployment flag and a browser with service workers', () => {
         const nav = { serviceWorker: { register: () => {} } };
@@ -200,13 +38,14 @@ describe('pushWorkerEnabled', () => {
 describe('startPushWorker', () => {
     const UID = '0b6a2c1e-6f1d-4a57-9c1e-3d2f8a9b7c10';
 
-    const makeNav = (registrations = []) => {
+    /** `registration`: the `/sw.js` already installed, if any. */
+    const makeNav = (registration = null) => {
         const listeners = {};
         return {
             listeners,
             serviceWorker: {
                 register: vi.fn(async () => ({})),
-                getRegistrations: vi.fn(async () => registrations),
+                getRegistration: vi.fn(async () => registration),
                 addEventListener: vi.fn((type, fn) => {
                     listeners[type] = fn;
                 }),
@@ -214,6 +53,12 @@ describe('startPushWorker', () => {
         };
     };
 
+    const installed = (subscription) => ({
+        pushManager: { getSubscription: vi.fn(async () => subscription) },
+        update: vi.fn(async () => {}),
+        unregister: vi.fn(async () => true),
+    });
+
     const load = async () => {
         const worker = await import('./pushWorker.js');
         const tap = await import('./notificationTap.js');
@@ -228,13 +73,14 @@ describe('startPushWorker', () => {
         ...over,
     });
 
-    it('registers /sw.js at the root scope, acks its taps and routes them', async () => {
+    it('registers no worker before push is turned on, acks its taps and routes them', async () => {
         const mod = await load();
         const handler = vi.fn();
         mod.setPushTapHandler(handler);
         const nav = makeNav();
         await start(mod, { nav });
-        expect(nav.serviceWorker.register).toHaveBeenCalledWith('/sw.js', { scope: '/', updateViaCache: 'none' });
+        expect(nav.serviceWorker.register).not.toHaveBeenCalled();
+        expect(nav.serviceWorker.getRegistration).toHaveBeenCalledWith('/');
 
         const source = { postMessage: vi.fn() };
         nav.listeners.message({ data: { type: 'other', notification: { uid: UID } }, source });
@@ -254,11 +100,25 @@ describe('startPushWorker', () => {
     });
 
     it('leaves an existing /sw.js alone where push is off, and registers nothing', async () => {
-        const puter = { active: { scriptURL: 'https://puter.test/sw.js' }, unregister: vi.fn(async () => true) };
-        const nav = makeNav([puter]);
+        const worker = installed(null);
+        const nav = makeNav(worker);
         await start(await load(), { nav, params: { pushEnabled: false } });
         expect(nav.serviceWorker.register).not.toHaveBeenCalled();
-        expect(puter.unregister).not.toHaveBeenCalled();
+        expect(worker.unregister).not.toHaveBeenCalled();
+    });
+
+    it('updates the worker this browser subscribed through', async () => {
+        const worker = installed({ endpoint: 'https://push.example/1' });
+        await start(await load(), { nav: makeNav(worker) });
+        expect(worker.update).toHaveBeenCalled();
+        expect(worker.unregister).not.toHaveBeenCalled();
+    });
+
+    it('removes a worker left without a subscription', async () => {
+        const worker = installed(null);
+        await start(await load(), { nav: makeNav(worker) });
+        expect(worker.unregister).toHaveBeenCalled();
+        expect(worker.update).not.toHaveBeenCalled();
     });
 
     it('hands over the notification uid a page was opened for and clears it', async () => {

src/gui/src/helpers/uuidv4.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * A random UUID v4. Unlike `crypto.randomUUID`, works outside a secure context
+ * (a self-hosted GUI on plain http).
+ *
+ * @returns {string}
+ */
+export const uuidv4 = () => {
+    return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, c =>
+        (c ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> c / 4).toString(16));
+};

src/gui/src/i18n/embedI18n.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import en from './translations/en.js';
+import { installI18n } from './i18nCore.js';
+
+installI18n({ en });
+
+/**
+ * Loads only the preferred language, so embeds don't ship every translation.
+ * Unknown or unavailable languages keep English.
+ * @param {string} locale
+ */
+export async function loadLocale (locale) {
+    if ( typeof locale !== 'string' || locale === 'en' || ! /^[a-z]+$/.test(locale) ) return;
+    try {
+        const { default: language } = await import(
+            /* webpackExclude: /translations\.js$/ */ `./translations/${locale}.js`
+        );
+        installI18n({ en, [locale]: language });
+    } catch {
+        // English is already installed.
+    }
+}

src/gui/src/i18n/embedI18n.test.js

@@ -0,0 +1,26 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+beforeAll(() => {
+    globalThis.window = globalThis;
+    globalThis.html_encode = value => String(value);
+});
+
+describe('embed translations', () => {
+    it('starts in English and loads only the requested language', async () => {
+        const { loadLocale } = await import('./embedI18n.js');
+        window.locale = 'de';
+        expect(i18n('close')).toBe('Close');
+        await loadLocale('de');
+        expect(i18n('close')).toBe('Schließen');
+        expect(i18n('app_browser_unavailable')).toBe('Apps are unavailable. Please reopen this browser from your app.');
+    });
+
+    it('keeps English for unknown or unsafe language values', async () => {
+        const { loadLocale } = await import('./embedI18n.js');
+        for ( const locale of ['xx', '../translations', 'en', null] ) {
+            window.locale = locale;
+            await loadLocale(locale);
+            expect(i18n('close')).toBe('Close');
+        }
+    });
+});

src/gui/src/i18n/i18n.js

@@ -18,75 +18,10 @@
  */
 
 import translations from './translations/translations.js';
+import { installI18n } from './i18nCore.js';
 
 window.listSupportedLanguages = () => Object.keys(translations).map(lang => translations[lang]);
 
-const variables = {
-    docs: 'https://docs.puter.com/',
-    terms: 'https://puter.com/terms',
-    privacy: 'https://puter.com/privacy',
-};
+installI18n(translations);
 
-function ReplacePlaceholders (str, arg_variables = {}) {
-    const all_variables = { ...variables, ...arg_variables };
-    str = str.replace(/{{link=(.*?)}}(.*?){{\/link}}/g, (_, key, text) => `<a href="${all_variables[key]}" target="_blank">${text}</a>`);
-    str = str.replace(/{{(.*?)}}/g, (_, key) => all_variables[key]);
-    return str;
-}
-
-window.i18n = function (key, replacements = [], encode_html = true) {
-    let arg_variables = {};
-    if ( Array.isArray(replacements) === false ) {
-        if ( typeof replacements === 'object' ) {
-            arg_variables = replacements;
-            replacements = [];
-        } else {
-            replacements = [replacements];
-        }
-    }
-
-    let language = translations[window.locale] ?? translations['en'];
-    let str = language.dictionary[key] ?? translations['en'].dictionary[key];
-
-    if ( ! str ) {
-        str = key;
-    }
-    str = ReplacePlaceholders(str, arg_variables);
-    if ( encode_html ) {
-        str = html_encode(str);
-        // html_encode doesn't render line breaks
-        str = str.replace(/\n/g, '<br />');
-    }
-    // replace %% occurrences with the values in replacements
-    // %% is for simple text replacements
-    // %strong% is for <strong> tags
-    // e.g. "Hello, %strong%" => "Hello, <strong>World</strong>"
-    // e.g. "Hello, %%" => "Hello, World"
-    // e.g. "Hello, %strong%, %%!" => "Hello, <strong>World</strong>, Universe!"
-    for ( let i = 0; i < replacements.length; i++ ) {
-        // sanitize the replacement
-        replacements[i] = encode_html ? html_encode(replacements[i]) : replacements[i];
-        // Function replacements below: a string one would expand `$&`, `$'`
-        // and the like inside the value (a team named "R&D $& Co").
-        const value = replacements[i];
-        // find first occurrence of %strong%
-        let index = str.indexOf('%strong%');
-        // find first occurrence of %%
-        let index2 = str.indexOf('%%');
-        // decide which one to replace
-        if ( index === -1 && index2 === -1 ) {
-            break;
-        } else if ( index === -1 ) {
-            str = str.replace('%%', () => value);
-        } else if ( index2 === -1 ) {
-            str = str.replace('%strong%', () => `<strong>${ value }</strong>`);
-        } else if ( index < index2 ) {
-            str = str.replace('%strong%', () => `<strong>${ value }</strong>`);
-        } else {
-            str = str.replace('%%', () => value);
-        }
-    }
-    return str;
-};
-
-export default {};
+export default {};

src/gui/src/i18n/i18nCore.js

@@ -0,0 +1,92 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+const variables = {
+    docs: 'https://docs.puter.com/',
+    terms: 'https://puter.com/terms',
+    privacy: 'https://puter.com/privacy',
+};
+
+function ReplacePlaceholders (str, arg_variables = {}) {
+    const all_variables = { ...variables, ...arg_variables };
+    str = str.replace(/{{link=(.*?)}}(.*?){{\/link}}/g, (_, key, text) => `<a href="${all_variables[key]}" target="_blank">${text}</a>`);
+    str = str.replace(/{{(.*?)}}/g, (_, key) => all_variables[key]);
+    return str;
+}
+
+/**
+ * Installs `window.i18n` over the given language table, which must include `en`.
+ * @param {Record<string, { dictionary: Record<string, string> }>} translations
+ */
+export function installI18n (translations) {
+    window.i18n = function (key, replacements = [], encode_html = true) {
+        let arg_variables = {};
+        if ( Array.isArray(replacements) === false ) {
+            if ( typeof replacements === 'object' ) {
+                arg_variables = replacements;
+                replacements = [];
+            } else {
+                replacements = [replacements];
+            }
+        }
+
+        let language = translations[window.locale] ?? translations['en'];
+        let str = language.dictionary[key] ?? translations['en'].dictionary[key];
+
+        if ( ! str ) {
+            str = key;
+        }
+        str = ReplacePlaceholders(str, arg_variables);
+        if ( encode_html ) {
+            str = html_encode(str);
+            // html_encode doesn't render line breaks
+            str = str.replace(/\n/g, '<br />');
+        }
+        // replace %% occurrences with the values in replacements
+        // %% is for simple text replacements
+        // %strong% is for <strong> tags
+        // e.g. "Hello, %strong%" => "Hello, <strong>World</strong>"
+        // e.g. "Hello, %%" => "Hello, World"
+        // e.g. "Hello, %strong%, %%!" => "Hello, <strong>World</strong>, Universe!"
+        for ( let i = 0; i < replacements.length; i++ ) {
+            // sanitize the replacement
+            replacements[i] = encode_html ? html_encode(replacements[i]) : replacements[i];
+            // Function replacements below: a string one would expand `$&`, `$'`
+            // and the like inside the value (a team named "R&D $& Co").
+            const value = replacements[i];
+            // find first occurrence of %strong%
+            let index = str.indexOf('%strong%');
+            // find first occurrence of %%
+            let index2 = str.indexOf('%%');
+            // decide which one to replace
+            if ( index === -1 && index2 === -1 ) {
+                break;
+            } else if ( index === -1 ) {
+                str = str.replace('%%', () => value);
+            } else if ( index2 === -1 ) {
+                str = str.replace('%strong%', () => `<strong>${ value }</strong>`);
+            } else if ( index < index2 ) {
+                str = str.replace('%strong%', () => `<strong>${ value }</strong>`);
+            } else {
+                str = str.replace('%%', () => value);
+            }
+        }
+        return str;
+    };
+}

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

@@ -22,6 +22,7 @@ const en = {
     english_name: 'English',
     code: 'en',
     dictionary: {
+        app_browser_unavailable: 'Apps are unavailable. Please reopen this browser from your app.',
         about: 'About',
         account: 'Account',
         account_password: 'Verify Account Password',

src/gui/src/sw.js

@@ -29,7 +29,6 @@
 
 const DEFAULT_TITLE = 'New notification';
 const DEFAULT_ICON = '/favicons/android-icon-192x192.png';
-const SHOW_MESSAGE = 'puter-show-notification';
 const CLICK_MESSAGE = 'puter-notification-click';
 const CLICK_ACK_MESSAGE = 'puter-notification-click-ack';
 const SUBSCRIPTION_CHANGED_MESSAGE = 'puter-push-subscription-changed';
@@ -205,19 +204,6 @@ async function routeClick (scope, click, startedAt = Date.now(), budgetMs = CLIC
     await scope.clients.openWindow(clickUrl(click, origin));
 }
 
-async function hasVisibleWindow (scope) {
-    const origin = scope.location.origin;
-    const windowClients = await scope.clients.matchAll({ type: 'window', includeUncontrolled: true });
-    return windowClients.some((client) => (
-        sameOriginUrl(client.url, origin) && client.visibilityState === 'visible'
-    ));
-}
-
-async function showPageMessage (scope, message) {
-    if ( await hasVisibleWindow(scope) ) return;
-    await showMessage(scope.registration, message, scope.location.origin);
-}
-
 async function postToWindows (scope, message) {
     const origin = scope.location.origin;
     const windowClients = await scope.clients.matchAll({ type: 'window', includeUncontrolled: true });
@@ -254,8 +240,6 @@ self.addEventListener('message', (event) => {
     if ( !message || !event.source || !sameOriginUrl(event.source.url, self.location.origin) ) return;
     if ( message.type === CLICK_ACK_MESSAGE ) {
         pendingClickAcks.get(message.id)?.();
-    } else if ( message.type === SHOW_MESSAGE ) {
-        event.waitUntil(showPageMessage(self, message.puter));
     }
 });
 

src/gui/src/sw.test.js

@@ -222,36 +222,13 @@ describe('service worker push', () => {
         expect(worker.shown).toEqual([{ title: 'New notification', options: { icon: DEFAULT_ICON } }]);
     });
 
-    it('shows a page\'s message only while no Puter window is visible', async () => {
-        const visible = loadWorker({ windows: [windowClient(`${ORIGIN}/desktop`, { visibilityState: 'visible' })] });
-        await visible.fire('message', {
-            data: { type: 'puter-show-notification', puter: { uid: 'n1', title: 'Hi' } },
-            source: { url: `${ORIGIN}/` },
-        });
-        expect(visible.shown).toEqual([]);
-        expect(visible.scope.clients.matchAll).toHaveBeenCalledWith({ type: 'window', includeUncontrolled: true });
-
-        const otherOrigin = loadWorker({ windows: [windowClient('https://elsewhere.example/', { visibilityState: 'visible' })] });
-        await otherOrigin.fire('message', {
-            data: { type: 'puter-show-notification', puter: { uid: 'n1', title: 'Hi' } },
-            source: { url: `${ORIGIN}/` },
-        });
-        expect(otherOrigin.shown.map((n) => n.title)).toEqual(['Hi']);
-    });
-
-    it('shows a page\'s message from this origin and ignores other messages', async () => {
+    it('shows nothing a page posts, only pushes', async () => {
         const worker = loadWorker();
         await worker.fire('message', {
             data: { type: 'puter-show-notification', puter: { uid: 'n1', title: 'Hi' } },
             source: { url: `${ORIGIN}/` },
         });
-        worker.listeners.message({ data: { type: 'other' }, source: { url: `${ORIGIN}/` }, waitUntil: () => {} });
-        worker.listeners.message({
-            data: { type: 'puter-show-notification', puter: { title: 'x' } },
-            source: { url: 'https://elsewhere.example/' },
-            waitUntil: () => {},
-        });
-        expect(worker.shown.map((n) => n.title)).toEqual(['Hi']);
+        expect(worker.shown).toEqual([]);
     });
 });
 

src/gui/webpack/BaseConfig.cjs

@@ -79,21 +79,27 @@ module.exports = async (options = {}) => {
     }
 
     const config = {};
-    config.entry = [
-        './src/init_sync.js',
-        './src/init_async.js',
-        './src/initgui.js',
-        './src/helpers.js',
-        './src/IPC.js',
-        './src/globals.js',
-        './src/i18n/i18n.js',
-        './src/keyboard.js',
-        './src/index.js',
-        ...entries,
-    ];
+    config.entry = {
+        bundle: [
+            './src/init_sync.js',
+            './src/init_async.js',
+            './src/initgui.js',
+            './src/helpers.js',
+            './src/IPC.js',
+            './src/globals.js',
+            './src/i18n/i18n.js',
+            './src/keyboard.js',
+            './src/index.js',
+            ...entries,
+        ],
+        'apps-embed': './src/appsEmbed.js',
+    };
     config.output = {
         path: path.resolve(__dirname, '../dist'),
-        filename: 'bundle.min.js',
+        filename: '[name].min.js',
+    };
+    config.module = {
+        rules: [{ test: /jquery-3\.6\.1\.min\.js$/, type: 'javascript/auto' }],
     };
     config.resolve = {
         modules: [
@@ -114,4 +120,4 @@ module.exports = async (options = {}) => {
         }),
     ];
     return config;
-};
+};

src/gui/webpack/EmitPlugin.cjs

@@ -87,6 +87,7 @@ module.exports = async ({ dir, options }) => {
 
     return new webpack.BannerPlugin({
         banner: prefix_text,
+        include: /bundle\.min\.js$/,
         raw: true,
     });
 };

src/puter-js/src/index.js

@@ -8,6 +8,7 @@ import { isFramedDocument } from './lib/appModeGate.js';
 import {
     isGodmodeTokenPayload,
     isUserSessionTokenPayload,
+    requestLaunchFromOpener,
     urlWithoutQueryParam,
 } from './lib/launchToken.js';
 import path from 'path-browserify';
@@ -258,6 +259,25 @@ export class Puter {
         resolvers: [],
     };
 
+    /**
+     * Pending while a tab the GUI opened for this app waits for its launch
+     * (token and opened item); sign-in and the launched-with-items handlers
+     * wait on it. Null otherwise.
+     *
+     * @internal
+     * @type {Promise<void> | null}
+     */
+    openerLaunch_ = null;
+
+    /**
+     * `puter.item.*` params of the item the GUI opened this tab with, standing
+     * in for the URL params a framed launch carries.
+     *
+     * @internal
+     * @type {URLSearchParams | null}
+     */
+    openerLaunchItem_ = null;
+
     // Holds the unique app instance ID that is provided by the host environment
     appInstanceID;
 
@@ -761,6 +781,28 @@ export class Puter {
 
             this.initSubmodules();
 
+            // A top-level tab the GUI opened for an app launch. Its URL params
+            // aren't trusted here (see isFramedDocument), and secrets stay out
+            // of its URL, so the token and opened item come from the GUI tab
+            // that opened it instead.
+            const openerLaunch = this.appInstanceID
+                ? requestLaunchFromOpener({
+                    guiOrigin: this.defaultGUIOrigin,
+                    appInstanceID: this.appInstanceID,
+                })
+                : null;
+            if (openerLaunch) {
+                this.openerLaunch_ = openerLaunch.then((launch) => {
+                    this.openerLaunch_ = null;
+                    if (launch?.item) {
+                        this.openerLaunchItem_ = new URLSearchParams(
+                            launch.item,
+                        );
+                    }
+                    if (launch?.token) this.setAuthToken(launch.token);
+                });
+            }
+
             // Print a CTA for developers to publish their app on the Puter App Store
             this.printDevCTA();
 

src/puter-js/src/index.webBoot.test.js

@@ -48,6 +48,43 @@ afterEach(() => {
     globalThis.XMLHttpRequest = origXHR;
 });
 
+/** Boots `Puter` as on a top-level page, where `process` is undefined. */
+const constructWeb = (Puter) => {
+    const realProcess = globalThis.process;
+    Object.defineProperty(globalThis, 'process', {
+        configurable: true,
+        get() {
+            const caller = (new Error().stack ?? '').split('\n')[2] ?? '';
+            return /src\/index\.js:\d+/.test(caller) ? undefined : realProcess;
+        },
+    });
+    try {
+        return new Puter();
+    } finally {
+        Object.defineProperty(globalThis, 'process', {
+            value: realProcess,
+            configurable: true,
+            writable: true,
+        });
+    }
+};
+
+describe('web-env boot of a reloaded app tab', () => {
+    // The opener is cut off once the first load is handed its launch, and a
+    // reload keeps the URL that marks the opened item. App code can run in the
+    // same task as the boot, so this is read with no await in between.
+    it('reports no launch item to wait for, from the first synchronous read', async () => {
+        history.replaceState(null, '', '/app/?puter.app_instance_id=i-1&puter.item.uid=f-1');
+        vi.resetModules();
+        const { Puter } = await import('./index.js');
+        const puter = constructWeb(Puter);
+
+        expect(puter.env).toBe('web');
+        expect(puter.openerLaunch_).toBeNull();
+        expect(puter.ui.wasLaunchedWithItems()).toBe(false);
+    });
+});
+
 describe('web-env boot with a stored token', () => {
     it('opens only one authenticated socket', async () => {
         localStorage.setItem(STORAGE_KEY, APP_TOKEN);

src/puter-js/src/lib/launchToken.js

@@ -55,3 +55,108 @@ export const isUserSessionTokenPayload = (payload) => {
     const kind = payload.t ?? payload.type;
     return kind === 'gui' || kind === 'session' || kind === 's';
 };
+
+// How long a tab waits for the GUI that opened it before signing in on its own.
+export const OPENER_LAUNCH_TIMEOUT_MS = 5000;
+
+/**
+ * What the GUI hands a tab it opened for an app launch.
+ *
+ * @typedef {object} OpenerLaunch
+ * @property {string | null} token - the app's token
+ * @property {Record<string, string> | null} item - `puter.item.*` params of
+ *   the item the app was opened with, as a framed launch has in its URL
+ */
+
+/** Keeps only `puter.item.*` string params. */
+const launchItemParams = (item) => {
+    if (!item || typeof item !== 'object') return null;
+    const params = Object.fromEntries(
+        Object.entries(item).filter(
+            ([key, value]) =>
+                key.startsWith('puter.item.') && typeof value === 'string',
+        ),
+    );
+    return Object.keys(params).length ? params : null;
+};
+
+/**
+ * Asks the Puter GUI tab that opened this one for the launch it opened the
+ * tab for (the app's token and opened item), so neither has to travel in the
+ * tab's URL. Only a reply from the opener itself at `guiOrigin` counts: a
+ * crafted link can name an instance id but can't make the GUI answer for it.
+ * Whatever the outcome, the opener is then cut off so the app can't reach the
+ * GUI tab.
+ *
+ * @param {object} options
+ * @param {string} options.guiOrigin - the configured GUI origin, never one from the URL
+ * @param {string} options.appInstanceID
+ * @param {typeof globalThis} [options.scope] - Global to use; injectable for tests.
+ * @param {number} [options.timeoutMs]
+ * @returns {Promise<OpenerLaunch | null> | null} null when there is no GUI
+ *   opener to ask, or (resolved) when no answer came
+ */
+export const requestLaunchFromOpener = ({
+    guiOrigin,
+    appInstanceID,
+    scope = globalThis,
+    timeoutMs = OPENER_LAUNCH_TIMEOUT_MS,
+}) => {
+    let opener = null;
+    try {
+        opener = scope.opener ?? null;
+    } catch {
+        opener = null;
+    }
+    // `closed` is readable cross-origin: a GUI tab that's gone can't answer.
+    // Synchronous, so a caller has nothing to wait on (a reloaded tab, say).
+    if (!opener || opener.closed || !guiOrigin || !appInstanceID) {
+        return null;
+    }
+    // An opener of this page's own origin is the app itself (a pop-out, say),
+    // not the GUI, and is the app's to keep. A cross-origin one throws here.
+    try {
+        const origin = scope.location.origin;
+        if (origin !== guiOrigin && opener.location.origin === origin) {
+            return null;
+        }
+    } catch {
+        // Possibly the GUI: ask it.
+    }
+
+    return new Promise((resolve) => {
+        let timer = null;
+        const finish = (launch) => {
+            scope.removeEventListener('message', onMessage);
+            clearTimeout(timer);
+            try {
+                scope.opener = null;
+            } catch {
+                // Nothing more to protect if it can't be cleared.
+            }
+            resolve(launch);
+        };
+        const onMessage = (event) => {
+            if (event.origin !== guiOrigin || event.source !== opener) return;
+            if (event.data?.msg !== 'puter.launch') return;
+            if (event.data.appInstanceID !== appInstanceID) return;
+            const token = event.data.token;
+            finish({
+                token: typeof token === 'string' && token ? token : null,
+                item: launchItemParams(event.data.item),
+            });
+        };
+        scope.addEventListener('message', onMessage);
+        timer = setTimeout(() => finish(null), timeoutMs);
+        try {
+            // Delivered only if the opener is at guiOrigin. `env` keeps the
+            // GUI's app IPC from treating this as a message from a framed app.
+            opener.postMessage(
+                { msg: 'puter.requestLaunch', env: 'app-tab', appInstanceID },
+                guiOrigin,
+            );
+        } catch {
+            finish(null);
+        }
+    });
+};

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

@@ -1,7 +1,8 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import {
     isGodmodeTokenPayload,
     isUserSessionTokenPayload,
+    requestLaunchFromOpener,
     urlWithoutQueryParam,
 } from './launchToken.js';
 
@@ -117,3 +118,108 @@ describe('isGodmodeTokenPayload', () => {
         expect(isGodmodeTokenPayload(null)).toBe(false);
     });
 });
+
+describe('requestLaunchFromOpener', () => {
+    const GUI = 'https://puter.com';
+
+    /** A top-level tab whose opener answers with `reply` (or not at all). */
+    const makeScope = ({ reply } = {}) => {
+        const listeners = new Set();
+        const scope = {
+            addEventListener: (_type, fn) => listeners.add(fn),
+            removeEventListener: (_type, fn) => listeners.delete(fn),
+            listeners,
+        };
+        scope.emit = (event) => {
+            for (const fn of [...listeners]) fn(event);
+        };
+        scope.opener = {
+            postMessage: vi.fn((data, targetOrigin) => {
+                if (reply) queueMicrotask(() => reply(scope, data, targetOrigin));
+            }),
+        };
+        return scope;
+    };
+
+    it('takes the launch the GUI opener sends for this instance, then cuts the opener off', async () => {
+        const scope = makeScope({
+            reply: (s, data) => s.emit({
+                origin: GUI,
+                source: opener,
+                data: {
+                    msg: 'puter.launch',
+                    appInstanceID: data.appInstanceID,
+                    token: 'tok',
+                    item: { 'puter.item.uid': 'f-1', 'puter.item.read_url': 'r', other: 'x', 'puter.item.size': 5 },
+                },
+            }),
+        });
+        const opener = scope.opener;
+        const launch = await requestLaunchFromOpener({ guiOrigin: GUI, appInstanceID: 'i-1', scope });
+        expect(launch).toEqual({
+            token: 'tok',
+            item: { 'puter.item.uid': 'f-1', 'puter.item.read_url': 'r' },
+        });
+        expect(opener.postMessage).toHaveBeenCalledWith(
+            { msg: 'puter.requestLaunch', env: 'app-tab', appInstanceID: 'i-1' },
+            GUI,
+        );
+        expect(scope.opener).toBeNull();
+        expect(scope.listeners.size).toBe(0);
+    });
+
+    it('ignores replies from another origin, another window, or another instance', async () => {
+        vi.useFakeTimers();
+        try {
+            const scope = makeScope();
+            const opener = scope.opener;
+            const pending = requestLaunchFromOpener({ guiOrigin: GUI, appInstanceID: 'i-1', scope, timeoutMs: 1000 });
+            const data = { msg: 'puter.launch', appInstanceID: 'i-1', token: 'bad' };
+            scope.emit({ origin: 'https://evil.example', source: opener, data });
+            scope.emit({ origin: GUI, source: {}, data });
+            scope.emit({ origin: GUI, source: opener, data: { ...data, appInstanceID: 'i-2' } });
+            vi.advanceTimersByTime(1000);
+            expect(await pending).toBeNull();
+            expect(scope.opener).toBeNull();
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    it('leaves alone a page this app opened from its own origin', () => {
+        const scope = makeScope();
+        scope.location = { origin: 'https://app.example' };
+        scope.opener.location = { origin: 'https://app.example' };
+        const opener = scope.opener;
+        expect(requestLaunchFromOpener({ guiOrigin: GUI, appInstanceID: 'i-1', scope })).toBeNull();
+        expect(opener.postMessage).not.toHaveBeenCalled();
+        expect(scope.opener).toBe(opener);
+    });
+
+    it('asks a cross-origin opener, as the GUI is', () => {
+        const scope = makeScope();
+        scope.location = { origin: 'https://app.example' };
+        Object.defineProperty(scope.opener, 'location', {
+            get () {
+                throw new DOMException('Blocked a frame', 'SecurityError');
+            },
+        });
+        expect(requestLaunchFromOpener({ guiOrigin: GUI, appInstanceID: 'i-1', scope })).toBeInstanceOf(Promise);
+        expect(scope.opener.postMessage).toHaveBeenCalledOnce();
+    });
+
+    // Synchronously, so there is no pending launch for callers to wait on.
+    it('returns null without asking when there is no opener', () => {
+        const scope = makeScope();
+        scope.opener = null;
+        expect(requestLaunchFromOpener({ guiOrigin: GUI, appInstanceID: 'i-1', scope })).toBeNull();
+    });
+
+    it('returns null without waiting when the GUI tab was closed', () => {
+        const scope = makeScope();
+        scope.opener.closed = true;
+        expect(requestLaunchFromOpener({ guiOrigin: GUI, appInstanceID: 'i-1', scope })).toBeNull();
+        expect(scope.opener.postMessage).not.toHaveBeenCalled();
+        expect(scope.listeners.size).toBe(0);
+    });
+});

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

@@ -160,6 +160,14 @@ export class AuthModule extends PuterModule {
             });
         }
 
+        // A tab the GUI opened is signed in by the token the GUI hands over.
+        if (puter.openerLaunch_) {
+            return puter.openerLaunch_.then(() =>
+                puter.authToken
+                    ? { success: true, token: puter.authToken }
+                    : this.signIn(options));
+        }
+
         return new Promise((resolve, reject) => {
             const signinsession = crypto.randomUUID();
             const msg_id = signinsession;
@@ -389,6 +397,10 @@ export class AuthModule extends PuterModule {
      * }}
      */
     getUser = function (...args) {
+        // A tab the GUI opened gets its token moments after loading.
+        if (!puter.authToken && puter.openerLaunch_) {
+            return puter.openerLaunch_.then(() => puter.auth.getUser(...args));
+        }
         if (!puter.authToken) {
             // Fake the server response for backwards compatibility
             // We already know this will fail
@@ -442,6 +454,9 @@ export class AuthModule extends PuterModule {
      */
     async getProfile(username) {
         try {
+            if (!this.authToken && this.puter.openerLaunch_) {
+                await this.puter.openerLaunch_;
+            }
             if (username === undefined) {
                 if (!this.authToken) return null;
             } else if (
@@ -550,6 +565,9 @@ export class AuthModule extends PuterModule {
      * @returns {Promise<User>}
      */
     async whoami() {
+        if (!this.authToken && this.puter.openerLaunch_) {
+            await this.puter.openerLaunch_;
+        }
         if (!this.authToken) {
             // Fake the server response for backwards compatibility
             // We already know this will fail

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

@@ -1,7 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-const { fetchUrlMock } = vi.hoisted(() => ({ fetchUrlMock: vi.fn() }));
+const { fetchUrlMock, xhrMocks } = vi.hoisted(() => ({
+    fetchUrlMock: vi.fn(),
+    xhrMocks: { initXhr: vi.fn(), setupXhrEventHandlers: vi.fn() },
+}));
 vi.mock('../lib/networkUtils.js', () => ({ fetchUrl: fetchUrlMock }));
+vi.mock('../lib/utils.js', async (importOriginal) => ({
+    ...(await importOriginal()),
+    ...xhrMocks,
+}));
 
 const { AuthModule } = await import('./Auth.js');
 
@@ -306,3 +313,68 @@ describe('signOut', () => {
         expect(puter.resetAuthToken).toHaveBeenCalled();
     });
 });
+
+describe('in a tab the GUI opened, before its token arrives', () => {
+    /** A puter whose token lands when `handOver` is called. */
+    const awaitingHandOver = () => {
+        const puter = { authToken: null, APIOrigin: API_ORIGIN };
+        let handOver;
+        puter.openerLaunch_ = new Promise((resolve) => {
+            handOver = () => {
+                puter.authToken = 'app-token';
+                puter.openerLaunch_ = null;
+                resolve();
+            };
+        });
+        return { puter, handOver };
+    };
+
+    it('whoami waits for the token instead of failing', async () => {
+        fetchUrlMock.mockResolvedValue(respond({ username: 'alice' }));
+        const { puter, handOver } = awaitingHandOver();
+        const user = new AuthModule(puter).whoami();
+        handOver();
+        await expect(user).resolves.toEqual({ username: 'alice' });
+    });
+
+    it('getProfile waits for the token instead of answering null', async () => {
+        const { puter, handOver } = awaitingHandOver();
+        const result = new AuthModule(puter).getProfile();
+        handOver();
+        expect(await result).toEqual(profile);
+    });
+
+    it('getUser waits for the token instead of throwing', async () => {
+        const { puter, handOver } = awaitingHandOver();
+        const auth = new AuthModule(puter);
+        puter.auth = auth;
+        const xhr = {};
+        xhrMocks.initXhr.mockReturnValue(xhr);
+        xhrMocks.setupXhrEventHandlers.mockImplementation(
+            (target, _success, _error, resolve) => {
+                target.send = () => resolve({ username: 'alice' });
+            },
+        );
+        vi.stubGlobal('puter', puter);
+        try {
+            const user = auth.getUser();
+            handOver();
+            await expect(user).resolves.toEqual({ username: 'alice' });
+            expect(xhrMocks.initXhr).toHaveBeenCalledWith(
+                '/whoami', API_ORIGIN, 'app-token', 'get',
+            );
+        } finally {
+            vi.unstubAllGlobals();
+        }
+    });
+
+    it('still fails once no token came', async () => {
+        const puter = { authToken: null, APIOrigin: API_ORIGIN };
+        puter.openerLaunch_ = Promise.resolve().then(() => {
+            puter.openerLaunch_ = null;
+        });
+        await expect(new AuthModule(puter).whoami()).rejects.toMatchObject({
+            status: 401,
+        });
+    });
+});

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

@@ -83,3 +83,31 @@ describe('authenticateWithPuter with more than one concurrent caller', () => {
         ]);
     });
 });
+
+describe('authenticateWithPuter in a tab the GUI opened', () => {
+    it('waits for the handed-over token instead of prompting', async () => {
+        const puterArg = { env: 'web', authToken: null, appID: undefined, util: {} };
+        const ui = new UIModule(puterArg, {});
+        let handOver;
+        globalThis.puter.openerLaunch_ = new Promise((resolve) => {
+            handOver = resolve;
+        });
+        const auth = ui.authenticateWithPuter();
+
+        puterArg.authToken = 'app-token';
+        globalThis.puter.openerLaunch_ = null;
+        handOver();
+        await auth;
+        expect(globalThis.puter.auth.signIn).not.toHaveBeenCalled();
+    });
+
+    it('prompts as usual when no token came', async () => {
+        const ui = makeUI();
+        globalThis.puter.auth.signIn = vi.fn(async () => {});
+        globalThis.puter.openerLaunch_ = Promise.resolve().then(() => {
+            globalThis.puter.openerLaunch_ = null;
+        });
+        await ui.authenticateWithPuter();
+        expect(globalThis.puter.auth.signIn).toHaveBeenCalledOnce();
+    });
+});

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

@@ -293,6 +293,12 @@ const getGUIOrigin = (origin) => {
     }
 };
 
+/** Whether `params` carry a launch item: its name, uid and read URL. */
+const hasLaunchItemParams = (params) =>
+    params.has('puter.item.name') &&
+    params.has('puter.item.uid') &&
+    params.has('puter.item.read_url');
+
 const MAX_REQUESTED_PERMISSIONS = 16;
 
 // Short on purpose: a request usually spends a user gesture while it waits.
@@ -1076,13 +1082,17 @@ export class UIModule extends EventListener {
      */
     /**
      * The item the app was launched with, read from the `puter.item.*` URL
-     * params the host appends, or null when there is none.
+     * params the host appends (or, in a tab the GUI opened, the same params
+     * it handed over), or null when there is none.
      *
      * @returns {FSItem|null}
      */
-    #launchItemFromURL () {
-        const URLParams = new URLSearchParams(globalThis.location.search);
-        if ( !URLParams.has('puter.item.name') || !URLParams.has('puter.item.uid') || !URLParams.has('puter.item.read_url') ) {
+    #launchItem () {
+        let URLParams = new URLSearchParams(globalThis.location.search);
+        if ( !hasLaunchItemParams(URLParams) && puter.openerLaunchItem_ ) {
+            URLParams = puter.openerLaunchItem_;
+        }
+        if ( ! hasLaunchItemParams(URLParams) ) {
             return null;
         }
         let fpath = URLParams.get('puter.item.path');
@@ -1104,6 +1114,26 @@ export class UIModule extends EventListener {
         });
     }
 
+    /**
+     * Calls `callback` with the launch item, once a tab the GUI opened has
+     * received it. Nothing when the app wasn't launched with one.
+     *
+     * @param {(items: FSItem[]) => void} callback
+     */
+    #withLaunchItem (callback) {
+        const deliver = () => {
+            const launchItem = this.#launchItem();
+            if ( launchItem ) {
+                callback([launchItem]);
+            }
+        };
+        if ( puter.openerLaunch_ ) {
+            puter.openerLaunch_.then(deliver);
+        } else {
+            deliver();
+        }
+    }
+
     onItemsOpened (callback) {
         // DEPRECATED - this is also called when items are dropped on the app, which in new versions should be handled
         // with the 'drop' event.
@@ -1113,10 +1143,7 @@ export class UIModule extends EventListener {
         // This should also be done only the very first time the callback is set (hence the if(!this.#onItemsOpened) check) since
         // the URL parameters will be checked every time the callback is set which can cause problems if the callback is set multiple times.
         if ( ! this.#onItemsOpened ) {
-            const launchItem = this.#launchItemFromURL();
-            if ( launchItem ) {
-                callback([launchItem]);
-            }
+            this.#withLaunchItem(callback);
         }
 
         this.#onItemsOpened = callback;
@@ -1132,9 +1159,12 @@ export class UIModule extends EventListener {
      */
     wasLaunchedWithItems () {
         const URLParams = new URLSearchParams(globalThis.location.search);
-        return URLParams.has('puter.item.name') &&
-            URLParams.has('puter.item.uid') &&
-            URLParams.has('puter.item.read_url');
+        if ( hasLaunchItemParams(URLParams) || puter.openerLaunchItem_ ) {
+            return true;
+        }
+        // A tab the GUI opened marks an opened item with its uid alone; the
+        // rest is still on its way from the GUI.
+        return !!puter.openerLaunch_ && URLParams.has('puter.item.uid');
     };
 
     /**
@@ -1151,10 +1181,7 @@ export class UIModule extends EventListener {
         // This should also be done only the very first time the callback is set (hence the if(!this.#onLaunchedWithItems) check) since
         // the URL parameters will be checked every time the callback is set which can cause problems if the callback is set multiple times.
         if ( ! this.#onLaunchedWithItems ) {
-            const launchItem = this.#launchItemFromURL();
-            if ( launchItem ) {
-                callback([launchItem]);
-            }
+            this.#withLaunchItem(callback);
         }
 
         this.#onLaunchedWithItems = callback;
@@ -2735,6 +2762,11 @@ export class UIModule extends EventListener {
             return;
         }
 
+        // The GUI that opened this tab may be about to hand over a token.
+        if ( puter.openerLaunch_ ) {
+            return puter.openerLaunch_.then(() => this.authenticateWithPuter());
+        }
+
         // if authToken is already present, resolve immediately
         if ( this.authToken ) {
             return new Promise((resolve) => {

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

@@ -356,4 +356,33 @@ describe('launch items', () => {
 
         expect(launched).not.toHaveBeenCalled();
     });
+
+    it('waits for the item a tab the GUI opened is handed', async () => {
+        vi.stubGlobal('location', { search: '?puter.item.uid=uid-1' });
+        let handOver;
+        globalThis.puter.openerLaunch_ = new Promise((resolve) => {
+            handOver = resolve;
+        });
+        const ui = makeUI();
+        const launched = vi.fn();
+        ui.onLaunchedWithItems(launched);
+        expect(ui.wasLaunchedWithItems()).toBe(true);
+        expect(launched).not.toHaveBeenCalled();
+
+        globalThis.puter.openerLaunchItem_ = new URLSearchParams(launchSearch().slice(1));
+        globalThis.puter.openerLaunch_ = null;
+        handOver();
+        await vi.waitFor(() => expect(launched).toHaveBeenCalledOnce());
+        expect(launched.mock.calls[0][0][0].readURL).toBe('https://api.test/file?uid=uid-1');
+        expect(ui.wasLaunchedWithItems()).toBe(true);
+    });
+
+    it('ignores an item uid alone in the URL when nothing is being handed over', () => {
+        vi.stubGlobal('location', { search: '?puter.item.uid=uid-1' });
+        const ui = makeUI();
+        const launched = vi.fn();
+        ui.onLaunchedWithItems(launched);
+        expect(ui.wasLaunchedWithItems()).toBe(false);
+        expect(launched).not.toHaveBeenCalled();
+    });
 });

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

@@ -23,7 +23,7 @@ import {
     takeClick,
 } from './lib/pushStore.js';
 import { closeNotification, reconcileDismissed } from './lib/osNotifications.js';
-import { ReceiptLog } from './lib/receipts.js';
+import { HANDLED_EVENT, ReceiptLog, handledHere } from './lib/receipts.js';
 import { toClick } from './lib/shapes.js';
 import {
     currentWebPush,
@@ -41,7 +41,7 @@ import { listDevices } from './listDevices.js';
 import { markShown } from './markShown.js';
 import { notify } from './notify.js';
 import { onNotification } from './onNotification.js';
-import { onPush, shownFrom } from './onPush.js';
+import { onPush } from './onPush.js';
 import { removeDevice } from './removeDevice.js';
 import { hasPermission, requestPermission } from './requestPermission.js';
 import { status } from './status.js';
@@ -52,8 +52,6 @@ export const CLICK_BROADCAST = 'notificationClick';
 export const WORKER_CLICK_MESSAGE = 'puter-notification-click';
 /** What the page answers a tap with when a click handler took it. */
 export const WORKER_CLICK_ACK_MESSAGE = 'puter-notification-click-ack';
-/** What a page posts `push-sw.js` to show a notification it received live. */
-export const WORKER_SHOW_MESSAGE = 'puter-push-show';
 /** What a worker posts when the browser replaced the push subscription. */
 export const SUBSCRIPTION_CHANGED_MESSAGE = 'puter-push-subscription-changed';
 /** Query parameter `push-sw.js` adds to a page it opens for a tap. */
@@ -66,8 +64,6 @@ const PUSH_LOCK = 'puter-push';
 
 /** As long as `push-sw.js` gives a handler. */
 const HANDLER_TIMEOUT_MS = 5_000;
-/** How long an older `push-sw.js`, which never answers, is waited for. */
-const WORKER_SHOW_TIMEOUT_MS = 2_000;
 /** How long after load a page a tap opened waits for a `click` handler. */
 const UNREAD_TAP_MS = 10_000;
 /** How long a load only asks the server about a subscription it confirmed. */
@@ -155,12 +151,6 @@ const ifNoTabHolds = async (name, run) => {
     }
 };
 
-/** Hidden, or in a window without focus. */
-const pageAway = () => {
-    const doc = globalThis.document;
-    return doc?.visibilityState === 'hidden' || doc?.hasFocus?.() === false;
-};
-
 /** `promise`, or `push_handler_timeout` after the time a worker would give it. */
 const withinHandlerTime = async (promise) => {
     let timer;
@@ -185,17 +175,6 @@ const withinHandlerTime = async (promise) => {
     }
 };
 
-/** Where a tap goes: on `base`'s origin, with relative paths read from it. */
-export const tapUrl = (url, base) => {
-    const from = new URL(base);
-    try {
-        const resolved = new URL(url ?? '', from);
-        return resolved.origin === from.origin ? resolved.href : from.href;
-    } catch {
-        return from.href;
-    }
-};
-
 /** Where taps resolve: the worker's scope if this page is in it, else `/`. */
 const tapBaseFor = (worker, pageUrl) => {
     const scope = workerScope(worker);
@@ -205,48 +184,6 @@ const tapBaseFor = (worker, pageUrl) => {
     };
 };
 
-/** The tap base a page saved for `scope`, else `scope`. */
-const savedTapBase = async (scope) => {
-    try {
-        const base = await idbGet(HANDLERS_STORE, TAP_BASE_PREFIX + scope);
-        if (
-            typeof base === 'string' &&
-            new URL(base).origin === new URL(scope).origin
-        )
-            return base;
-    } catch {
-        // Nothing saved, or IndexedDB is unavailable.
-    }
-    return scope;
-};
-
-/**
- * Hands the notification to `push-sw.js`, which shows it unless another window
- * of the app has focus. Resolves whether the worker answered.
- */
-const showThroughWorker = (registration, title, options) => {
-    const worker = registration.active;
-    if (!worker || typeof globalThis.MessageChannel !== 'function')
-        return Promise.resolve(false);
-    return new Promise((resolve) => {
-        const channel = new MessageChannel();
-        const done = (answered) => {
-            clearTimeout(timer);
-            channel.port1.close();
-            resolve(answered);
-        };
-        const timer = setTimeout(() => done(false), WORKER_SHOW_TIMEOUT_MS);
-        channel.port1.onmessage = () => done(true);
-        try {
-            worker.postMessage({ type: WORKER_SHOW_MESSAGE, title, options }, [
-                channel.port2,
-            ]);
-        } catch {
-            done(false);
-        }
-    });
-};
-
 /**
  * An app's notifications to the user it runs for.
  *
@@ -286,8 +223,6 @@ export class NotificationsModule extends EventListener {
     #stopWaitingForAuth = null;
     /** @type {{ url: string; scope?: string } | null} */
     #worker = null;
-    /** Whether the page's push worker is registered, as last looked up. */
-    #workerRegistered = false;
     /**
      * The load-time sync, per worker URL.
      *
@@ -304,14 +239,7 @@ export class NotificationsModule extends EventListener {
     /** This page's hold on each key's handler lock, with its handler count. */
     #handlerLocks = new Map();
     #watchingPageCache = false;
-    #receipts = new ReceiptLog(() => this.#showsOwn());
-    /**
-     * Whether the signed-in user turned push on here, as last read or set. A
-     * page shows notifications itself only while it is.
-     */
-    #optedIn = false;
-    /** Bumped on every change, so a read that started before one is dropped. */
-    #optInVersion = 0;
+    #receipts = new ReceiptLog();
     /** @type {BroadcastChannel | null} */
     #optInChannel = null;
     /**
@@ -464,11 +392,18 @@ export class NotificationsModule extends EventListener {
         };
     }
 
-    /** @internal This page received `uid` live, in a feed or the desktop. */
-    _noteReceived(uid, handler) {
+    /**
+     * @internal This page received `uid` live, in a feed or the desktop, over
+     * `socket` or else the events socket. While visible and focused, the page
+     * tells the server it handled it, so no push goes out for it.
+     */
+    _noteReceived(uid, handler, socket) {
         // A dismiss-only listener leaves postings for push delivery.
         if (handler === this.#pushListener && this.#pushHandlers.size === 0) return;
-        this.#receipts.note(uid);
+        const fresh = !this.#receipts.has(uid);
+        if (!handledHere(this.#receipts.note(uid)) || !fresh) return;
+        const via = socket ?? this.puter.events?.channel?.socket;
+        if (via?.connected) via.emit(HANDLED_EVENT, { uid });
     }
 
     /** @internal Closes this browser's copy even when the row was already dismissed. */
@@ -594,7 +529,6 @@ export class NotificationsModule extends EventListener {
                 'push_verification_canceled',
             );
         }
-        this.#workerRegistered = true;
         void this.#finishSync(
             syncing,
             worker,
@@ -731,18 +665,6 @@ export class NotificationsModule extends EventListener {
     #useWorker(worker) {
         this.#worker = worker;
         if (this.puter.env === 'web') void this.#saveTapBase(worker);
-        void (async () => {
-            try {
-                const registration =
-                    await globalThis.navigator?.serviceWorker?.getRegistration(
-                        worker.scope ?? worker.url,
-                    );
-                if (this.#worker === worker)
-                    this.#workerRegistered = !!registration;
-            } catch {
-                if (this.#worker === worker) this.#workerRegistered = false;
-            }
-        })();
     }
 
     async #saveTapBase(worker) {
@@ -757,18 +679,6 @@ export class NotificationsModule extends EventListener {
         }
     }
 
-    /** Whether this page shows a browser notification itself while it is away. */
-    #showsOwn() {
-        return (
-            this.puter.env === 'web' &&
-            this.#optedIn &&
-            this.#pushFeed !== null &&
-            this.#pushHandlers.size > 0 &&
-            this.#workerRegistered &&
-            globalThis.Notification?.permission === 'granted'
-        );
-    }
-
     async #userUuid() {
         const known =
             this.puter.whoami ?? (await this.puter.whoamiCache_) ?? null;
@@ -785,35 +695,26 @@ export class NotificationsModule extends EventListener {
 
     async #recordOptIn(on) {
         if (this.puter.env !== 'web') return;
-        this.#setOptedIn(on);
         try {
             const uuid = await this.#userUuid();
             if (uuid) await setOptIn(uuid, on);
         } catch (error) {
             warnStorage(error);
         }
-        this.#optInChanged();
     }
 
     async #forgetOptIns() {
-        this.#setOptedIn(false);
         try {
             await forgetPushState();
         } catch (error) {
             warnStorage(error);
         }
-        this.#optInChanged();
     }
 
-    #setOptedIn(on) {
-        this.#optedIn = on;
-        this.#optInVersion++;
-    }
-
-    /** The user's opt-in, read into `#optedIn`; null when it can't be read. */
+    /** The user's opt-in; null when it can't be read. */
     async #readOptIn() {
+        // A tab that syncs stops when another turns push off.
         this.#listenForOptInChanges();
-        const version = this.#optInVersion;
         /** @type {boolean | null} */
         let on = false;
         try {
@@ -825,12 +726,11 @@ export class NotificationsModule extends EventListener {
             warnStorage(error);
             on = null;
         }
-        if (version === this.#optInVersion) this.#optedIn = on === true;
         return on;
     }
 
-    /** Other tabs re-read the opt-in; `off` also stops their syncs. */
-    #optInChanged(kind = 'changed') {
+    /** Stops other tabs' syncs once push is turned off here. */
+    #optInChanged(kind) {
         this.#listenForOptInChanges();
         try {
             this.#optInChannel?.postMessage(kind);
@@ -848,7 +748,6 @@ export class NotificationsModule extends EventListener {
         this.#optInChannel = new BroadcastChannel(OPT_IN_CHANNEL);
         this.#optInChannel.onmessage = (event) => {
             if (event.data === 'off') this.#stopSyncs();
-            void this.#readOptIn();
         };
     }
 
@@ -931,7 +830,6 @@ export class NotificationsModule extends EventListener {
             !(await usesPuterKey(subscription, answer.publicKey))
         )
             return false;
-        this.#workerRegistered = true;
         return true;
     }
 
@@ -983,7 +881,6 @@ export class NotificationsModule extends EventListener {
     async #finishSync(syncing, worker, what) {
         try {
             await syncing;
-            this.#workerRegistered = true;
         } catch (error) {
             await this.#followRefusal(error, worker);
             if (QUIET_SYNC_ERRORS.has(error?.code)) return;
@@ -1096,7 +993,6 @@ export class NotificationsModule extends EventListener {
             this.#restartOnAuthChange();
             return;
         }
-        if (this.puter.env === 'web') void this.#readOptIn();
         /** @type {Promise<{ off: () => Promise<void> } | null>} */
         const feed = (async () => {
             try {
@@ -1160,13 +1056,9 @@ export class NotificationsModule extends EventListener {
 
     async #dispatchPush(notification) {
         const entries = this.#pushHandlers.get(notification.channel ?? '');
-        let result;
         for (const { handler, onError } of entries ? [...entries] : []) {
             try {
-                result =
-                    (await withinHandlerTime(
-                        (async () => handler(notification))(),
-                    )) ?? result;
+                await withinHandlerTime((async () => handler(notification))());
             } catch (error) {
                 if (onError) onError(error);
                 else
@@ -1176,51 +1068,6 @@ export class NotificationsModule extends EventListener {
                     );
             }
         }
-        await this.#showIfAway(notification, result);
-    }
-
-    /**
-     * A website page that is hidden or in an unfocused window shows what the
-     * push would have, through `push-sw.js` so a focused window of the app
-     * holds it back. Inside the Puter desktop, the desktop's banner shows it.
-     */
-    async #showIfAway(notification, result) {
-        if (this.puter.env !== 'web' || !this.#optedIn || !pageAway() || this.#dismissed.has(notification.uid)) return;
-        if (globalThis.Notification?.permission !== 'granted') return;
-        try {
-            const worker = this.#worker ?? workerFor('web');
-            const registration =
-                await globalThis.navigator.serviceWorker?.getRegistration(
-                    worker.scope ?? worker.url,
-                );
-            this.#workerRegistered = !!registration;
-            if (!registration) return;
-            const { title, url, ...shown } = shownFrom(notification, result);
-            const scope =
-                registration.scope ?? `${globalThis.location.origin}/`;
-            const sensitive = notification.sensitive === true;
-            const options = {
-                ...shown,
-                renotify: shown.tag !== notification.uid,
-                data: {
-                    puter: {
-                        uid: notification.uid,
-                        target: sensitive ? null : notification.target,
-                        data: sensitive ? null : notification.data,
-                        url: tapUrl(url, await savedTapBase(scope)),
-                    },
-                },
-            };
-            if (this.#dismissed.has(notification.uid)) return;
-            if (!await showThroughWorker(registration, title, options))
-                await registration.showNotification(title, options);
-            if (this.#dismissed.has(notification.uid)) await this._closeNotification(notification.uid);
-        } catch (error) {
-            console.warn(
-                '[puter.notifications] could not show a notification',
-                error,
-            );
-        }
     }
 
     /**

src/puter-js/src/modules/notifications/lib/receipts.js

@@ -5,6 +5,12 @@
  */
 export const RECEIPT_EVENT = 'notif.receipt';
 
+/**
+ * Sent with `{ uid }` when the page received that notification live while
+ * visible and focused, so no push goes out for it from any region.
+ */
+export const HANDLED_EVENT = 'notif.handled';
+
 const REMEMBERED = 500;
 const MAX_WAITING = 100;
 // Longer than the server waits. A late answer is ignored there, but it still
@@ -14,46 +20,71 @@ const WAIT_MS = 10_000;
 /**
  * @typedef {Object} Receipt
  * @property {true} received
- * @property {'visible' | 'hidden' | 'unknown'} visibilityState
- * @property {boolean} focused The page's window has focus.
- * @property {boolean} showsOwn The page shows a browser notification itself
- *   while hidden or unfocused.
+ * @property {'visible' | 'hidden' | 'unknown'} visibilityState When the page
+ *   received it.
+ * @property {boolean} focused The page's window had focus when it received it.
  */
 
 const MISSED = Object.freeze({ received: false });
 
 /** @typedef {{ ack: Function; timer: ReturnType<typeof setTimeout> | null }} WaitingAsk */
 
+/**
+ * The page counts as handling a notification it received while visible and
+ * focused; otherwise the notification goes out as a push.
+ *
+ * @param {Receipt} receipt
+ */
+export const handledHere = (receipt) =>
+    receipt.visibilityState === 'visible' && receipt.focused;
+
+/** @returns {Receipt} */
+const receiptNow = () => {
+    const doc = globalThis.document;
+    const state = doc?.visibilityState;
+    return {
+        received: true,
+        visibilityState:
+            state === 'visible' || state === 'hidden' ? state : 'unknown',
+        focused: doc?.hasFocus?.() === true,
+    };
+};
+
 /** Notifications this page received live, for the server's receipt asks. */
 export class ReceiptLog {
-    /** @type {Set<string>} */
-    #received = new Set();
+    /** @type {Map<string, Receipt>} */
+    #received = new Map();
     /** @type {Map<string, WaitingAsk[]>} */
     #waiting = new Map();
     #waitingCount = 0;
-    /** @type {() => boolean} */
-    #showsOwn;
-
-    /** @param {() => boolean} [showsOwn] */
-    constructor(showsOwn = () => false) {
-        this.#showsOwn = showsOwn;
-    }
 
     /** @param {string} uid */
+    has(uid) {
+        return this.#received.has(uid);
+    }
+
+    /**
+     * Records `uid` with the page's state now, which every answer about it
+     * gives.
+     *
+     * @param {string} uid
+     * @returns {Receipt}
+     */
     note(uid) {
-        this.#received.add(uid);
+        const receipt = this.#received.get(uid) ?? receiptNow();
+        this.#received.set(uid, receipt);
         if (this.#received.size > REMEMBERED) {
-            this.#received.delete(this.#received.values().next().value);
+            this.#received.delete(this.#received.keys().next().value);
         }
         const asks = this.#waiting.get(uid);
-        if (!asks) return;
+        if (!asks) return receipt;
         this.#waiting.delete(uid);
         this.#waitingCount -= asks.length;
-        const answer = this.#receipt();
         for (const ask of asks) {
             if (ask.timer) clearTimeout(ask.timer);
-            ask.ack(answer);
+            ask.ack(receipt);
         }
+        return receipt;
     }
 
     /**
@@ -70,8 +101,9 @@ export class ReceiptLog {
             ack(MISSED);
             return;
         }
-        if (this.#received.has(uid)) {
-            ack(this.#receipt());
+        const receipt = this.#received.get(uid);
+        if (receipt) {
+            ack(receipt);
             return;
         }
         if (this.#waitingCount >= MAX_WAITING) {
@@ -101,17 +133,4 @@ export class ReceiptLog {
         this.#waitingCount--;
         ask.ack(MISSED);
     }
-
-    /** @returns {Receipt} */
-    #receipt() {
-        const doc = globalThis.document;
-        const state = doc?.visibilityState;
-        return {
-            received: true,
-            visibilityState:
-                state === 'visible' || state === 'hidden' ? state : 'unknown',
-            focused: doc?.hasFocus?.() === true,
-            showsOwn: this.#showsOwn() === true,
-        };
-    }
 }

src/puter-js/src/modules/notifications/notifications.test.js

@@ -1145,10 +1145,12 @@ describe('receipts', () => {
         received: true,
         visibilityState: 'unknown',
         focused: false,
-        showsOwn: false,
         ...over,
     });
 
+    /** A socket.io client that records what the page sends on it. */
+    const ackSocket = (connected = true) => ({ connected, emit: vi.fn() });
+
     it('acknowledges a notification a feed already received', async () => {
         const events = makeEvents();
         const notifications = makeModule({ events });
@@ -1204,15 +1206,23 @@ describe('receipts', () => {
         expect(second).toHaveBeenCalledWith(received());
     });
 
-    it('sends the page visibility and focus with the acknowledgement', async () => {
+    it('sends the page visibility and focus from when the notification arrived', async () => {
         const events = makeEvents();
         const notifications = makeModule({ events });
         await notifications.onNotification(() => {});
-        events.state.push(event('n-1'));
         vi.stubGlobal('document', {
             visibilityState: 'hidden',
             hasFocus: () => true,
         });
+        try {
+            events.state.push(event('n-1'));
+        } finally {
+            vi.unstubAllGlobals();
+        }
+        vi.stubGlobal('document', {
+            visibilityState: 'visible',
+            hasFocus: () => false,
+        });
 
         const ack = vi.fn();
         try {
@@ -1226,22 +1236,69 @@ describe('receipts', () => {
         );
     });
 
-    it('says the desktop never shows its own browser notification', () => {
-        const notifications = makeModule({ env: 'gui' });
-        vi.stubGlobal('document', {
-            visibilityState: 'visible',
-            hasFocus: () => false,
+    describe('reporting a notification the page handled', () => {
+        const withPage = (state, run) => {
+            vi.stubGlobal('document', state);
+            try {
+                return run();
+            } finally {
+                vi.unstubAllGlobals();
+            }
+        };
+        const focused = { visibilityState: 'visible', hasFocus: () => true };
+
+        it('reports one received while visible and focused, once, on its socket', () => {
+            const notifications = makeModule({ env: 'gui' });
+            const socket = ackSocket();
+
+            withPage(focused, () => {
+                notifications._noteReceived('n-1', undefined, socket);
+                notifications._noteReceived('n-1', undefined, socket);
+            });
+
+            expect(socket.emit.mock.calls).toEqual([
+                ['notif.handled', { uid: 'n-1' }],
+            ]);
+        });
+
+        it.each([
+            ['hidden', { visibilityState: 'hidden', hasFocus: () => true }],
+            ['out of focus', { visibilityState: 'visible', hasFocus: () => false }],
+        ])('reports nothing received while %s', (_label, state) => {
+            const notifications = makeModule({ env: 'gui' });
+            const socket = ackSocket();
+
+            withPage(state, () =>
+                notifications._noteReceived('n-1', undefined, socket),
+            );
+
+            expect(socket.emit).not.toHaveBeenCalled();
+        });
+
+        it('reports a feed`s notification on the events socket', async () => {
+            const events = makeEvents();
+            const socket = ackSocket();
+            events.channel = { socket };
+            const notifications = makeModule({ events });
+            await notifications.onNotification(() => {});
+
+            withPage(focused, () => events.state.push(event('n-1')));
+
+            expect(socket.emit).toHaveBeenCalledWith('notif.handled', {
+                uid: 'n-1',
+            });
+        });
+
+        it('reports nothing over a socket that is not connected', () => {
+            const notifications = makeModule({ env: 'gui' });
+            const socket = ackSocket(false);
+
+            withPage(focused, () =>
+                notifications._noteReceived('n-1', undefined, socket),
+            );
+
+            expect(socket.emit).not.toHaveBeenCalled();
         });
-        const ack = vi.fn();
-        try {
-            notifications._noteReceived('n-1');
-            notifications._answerReceipt({ uid: 'n-1' }, ack);
-        } finally {
-            vi.unstubAllGlobals();
-        }
-        expect(ack).toHaveBeenCalledWith(
-            received({ visibilityState: 'visible', focused: false }),
-        );
     });
 
     it('answers received: false once a notification it never got stops being waited for', async () => {

src/puter-js/src/modules/notifications/onPush.js

@@ -4,68 +4,6 @@ import { webPushSupported, workerFor } from './lib/webPush.js';
 /** Same rule the server applies to a notification's `channel`. */
 const KEY_PATTERN = /^[a-z0-9-]{1,32}$/;
 
-/** Fields a handler's result may set on the shown notification. */
-const SHOWN_FIELDS = ['title', 'body', 'icon', 'badge', 'image', 'tag', 'url'];
-
-const DEFAULT_TITLE = 'New notification';
-
-/** The tag the server gives the same notification's push. */
-export const pushTag = (notification) => {
-    const appUid = notification.app?.uid;
-    return notification.group && appUid && !notification.sensitive
-        ? `${appUid}:${notification.group}`
-        : notification.uid;
-};
-
-/**
- * The handler's result, reduced to what a notification can show. A sensitive
- * notification names only the app, as its push does, whatever the handler
- * returns.
- */
-export const shownFrom = (notification, result) => {
-    const appIcon = notification.app?.icon;
-    if (notification.sensitive) {
-        const name = notification.app?.name;
-        return {
-            title: name || DEFAULT_TITLE,
-            ...(name ? { body: `New notification from ${name}` } : {}),
-            ...(appIcon ? { icon: appIcon } : {}),
-            tag: notification.uid,
-        };
-    }
-    const icon = notification.icon ?? appIcon;
-    const shown = {
-        title: notification.title || DEFAULT_TITLE,
-        ...(notification.text ? { body: notification.text } : {}),
-        ...(icon ? { icon } : {}),
-        tag: pushTag(notification),
-        ...(notification.target ? { url: notification.target } : {}),
-    };
-    if (!result || typeof result !== 'object') return shown;
-    for (const field of SHOWN_FIELDS) {
-        if (typeof result[field] === 'string' && result[field] !== '')
-            shown[field] = result[field];
-    }
-    if (typeof result.requireInteraction === 'boolean')
-        shown.requireInteraction = result.requireInteraction;
-    if (Array.isArray(result.actions)) {
-        shown.actions = [];
-        for (const entry of result.actions) {
-            if (!entry || typeof entry.action !== 'string' ||
-                !entry.action.trim() || entry.action.length > 64 ||
-                typeof entry.title !== 'string' ||
-                !entry.title.trim() || entry.title.length > 64) continue;
-            shown.actions.push({
-                action: entry.action,
-                title: entry.title,
-                ...(typeof entry.icon === 'string' && entry.icon ? { icon: entry.icon } : {}),
-            });
-            if (shown.actions.length === 2) break;
-        }
-    }
-    return shown;
-};
-
 let evalBlockedWarned = false;
 
 /**
@@ -99,12 +37,12 @@ const workerSource = (handler) => {
 
 /**
  * Handles this app's notifications sent with `channel: key`, live while the app
- * is connected and as a browser push while it isn't.
+ * is connected and as a browser push when no page of it is visible and focused.
  *
  * The handler gets the notification and may return `{ title, body, icon, badge,
- * image, tag, url, requireInteraction, actions }` to change what is shown. On a
- * website it is also saved for `push-sw.js`, which runs it when a push arrives
- * with no page open, so it must be self-contained (see the docs for the limits). Once
+ * image, tag, url, requireInteraction, actions }` to change what a push shows.
+ * On a website it is also saved for `push-sw.js`, which runs it when a push
+ * arrives, so it must be self-contained (see the docs for the limits). Once
  * the user turned notifications on here with `enable()`, this keeps the
  * browser's subscription current without asking again.
  *

src/puter-js/src/modules/notifications/webPush.test.js

@@ -62,9 +62,8 @@ vi.mock('./lib/pushStore.js', () => {
 
 const { syncWebPush, removeWebPush, fromBase64Url, workerFor } =
     await import('./lib/webPush.js');
-const { NotificationsModule, tapUrl } = await import('./index.js');
+const { NotificationsModule } = await import('./index.js');
 const { PuterJSError } = await import('../../lib/PuterJSError.js');
-const { shownFrom } = await import('./onPush.js');
 
 const ORIGIN = 'https://app.example';
 const SCRIPT = `${ORIGIN}/puter-sw.js`;
@@ -889,93 +888,6 @@ describe('workerFor', () => {
     });
 });
 
-describe('shownFrom', () => {
-    const notification = {
-        uid: 'n1',
-        title: 'Hi',
-        text: 'body',
-        icon: null,
-        target: '/chat/1',
-        group: null,
-        app: { uid: 'app-1', name: 'Chat' },
-    };
-
-    it('defaults to the notification`s own fields', () => {
-        expect(shownFrom(notification, undefined)).toEqual({
-            title: 'Hi',
-            body: 'body',
-            tag: 'n1',
-            url: '/chat/1',
-        });
-    });
-
-    it('takes only the shown fields a handler returns as strings', () => {
-        expect(
-            shownFrom(notification, { title: 'New', body: 7, onclick: 'x' }),
-        ).toEqual({ title: 'New', body: 'body', tag: 'n1', url: '/chat/1' });
-    });
-
-    it('keeps the first two valid buttons and only their display fields', () => {
-        expect(shownFrom(notification, { actions: [
-            null, {}, { action: '', title: 'Empty' },
-            { action: ' ', title: 'Blank' }, { action: 1, title: 'Number' },
-            { action: 'x'.repeat(65), title: 'Long id' },
-            { action: 'bad', title: '' }, { action: 'bad', title: ' ' },
-            { action: 'bad', title: 1 }, { action: 'bad', title: 'x'.repeat(65) },
-            { action: 'accept', title: 'Accept', icon: '/accept.png', extra: 'dropped' },
-            { action: 'd'.repeat(64), title: 'D'.repeat(64), icon: 3 },
-            { action: 'third', title: 'Third' },
-        ] }).actions).toEqual([
-            { action: 'accept', title: 'Accept', icon: '/accept.png' },
-            { action: 'd'.repeat(64), title: 'D'.repeat(64) },
-        ]);
-    });
-
-    it.each([null, 'accept', { action: 'accept', title: 'Accept' }])(
-        'ignores non-array actions: %s', (actions) => {
-            expect(shownFrom(notification, { actions })).not.toHaveProperty('actions');
-        },
-    );
-
-    it('tags a grouped notification as the server tags its push', () => {
-        expect(shownFrom({ ...notification, group: 'room-1' }).tag).toBe(
-            'app-1:room-1',
-        );
-    });
-
-    it('falls back to the app`s icon', () => {
-        const app = { ...notification.app, icon: 'https://cdn.test/app.png' };
-        expect(shownFrom({ ...notification, app }).icon).toBe(
-            'https://cdn.test/app.png',
-        );
-    });
-
-    it('names only the app for a sensitive notification, whatever the handler says', () => {
-        expect(
-            shownFrom(
-                { ...notification, group: 'room-1', sensitive: true },
-                { title: 'Secret', body: 'secret', actions: [{ action: 'secret', title: 'Secret' }] },
-            ),
-        ).toEqual({
-            title: 'Chat',
-            body: 'New notification from Chat',
-            tag: 'n1',
-        });
-    });
-});
-
-describe('tapUrl', () => {
-    it('reads relative paths from the worker`s scope and stays on its origin', () => {
-        const scope = `${ORIGIN}/app/`;
-        expect(tapUrl(undefined, scope)).toBe(`${ORIGIN}/app/`);
-        expect(tapUrl('chat/1', scope)).toBe(`${ORIGIN}/app/chat/1`);
-        expect(tapUrl('/chat/1', scope)).toBe(`${ORIGIN}/chat/1`);
-        expect(tapUrl('https://elsewhere.example/x', scope)).toBe(
-            `${ORIGIN}/app/`,
-        );
-    });
-});
-
 /** Web Locks for this test's tabs only, with shared mode and `ifAvailable`. */
 const fakeLocks = () => {
     const locks = new Map();
@@ -1862,12 +1774,11 @@ describe('onPush', () => {
         });
     });
 
-    describe('live delivery while the user is elsewhere', () => {
+    describe('live delivery', () => {
         let nav;
         const page = ({ visibilityState = 'visible', focused = true } = {}) => {
             globalThis.document = { visibilityState, hasFocus: () => focused };
         };
-        const away = () => page({ visibilityState: 'hidden', focused: false });
 
         beforeEach(() => {
             store.set(OPT_IN, true);
@@ -1882,383 +1793,37 @@ describe('onPush', () => {
         });
 
         it.each([
+            ['focused', {}],
             ['hidden', { visibilityState: 'hidden', focused: false }],
             ['visible in an unfocused window', { focused: false }],
         ])(
-            'shows the handler`s result when the page is %s',
+            'runs the handler and leaves showing it to the push when the page is %s',
             async (_, state) => {
                 page(state);
+                const handler = vi.fn(() => ({ title: 'From the handler' }));
                 const { module, feed } = makeModule();
-                await module.onPush('chat', () => ({
-                    title: 'From the handler',
-                }));
+                await module.onPush('chat', handler);
                 await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-                expect(nav.registration.showNotification).toHaveBeenCalledWith(
-                    'From the handler',
-                    expect.objectContaining({
-                        tag: 'n1',
-                        renotify: false,
-                        data: {
-                            puter: expect.objectContaining({
-                                uid: 'n1',
-                                url: `${ORIGIN}/`,
-                            }),
-                        },
-                    }),
+                expect(handler).toHaveBeenCalledWith(
+                    expect.objectContaining({ uid: 'n1' }),
                 );
+                expect(nav.registration.showNotification).not.toHaveBeenCalled();
             },
         );
 
-        it.each([true, false, 'true', 1, null, undefined])(
-            'passes only a boolean requireInteraction to the browser: %s',
-            async (requireInteraction) => {
-                away();
-                const { module, feed } = makeModule();
-                await module.onPush('chat', () => ({ requireInteraction }));
-                await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-                const options =
-                    nav.registration.showNotification.mock.calls[0][1];
-                if (typeof requireInteraction === 'boolean')
-                    expect(options.requireInteraction).toBe(requireInteraction);
-                else expect(options).not.toHaveProperty('requireInteraction');
-            },
-        );
-
-        it('passes action buttons through the page display path', async () => {
-            away();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => ({
-                actions: [{ action: 'accept', title: 'Accept' }],
-            }));
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(nav.registration.showNotification).toHaveBeenCalledWith('Hi', expect.objectContaining({
-                actions: [{ action: 'accept', title: 'Accept' }],
-            }));
-        });
-
-        it('closes the OS notification this page showed when its uid is dismissed', async () => {
-            away();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => {});
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            const { data } = nav.registration.showNotification.mock.calls[0][1];
-            const close = vi.fn();
-            nav.registration.getNotifications = vi.fn(async () => [{ data, close }]);
-            await module._receiveDismissal('n1');
-            expect(close).toHaveBeenCalledOnce();
-        });
-
-        it('keeps a late live posting from reopening a dismissed notification', async () => {
-            away();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => {});
-            await module._receiveDismissal('n1');
-            module._noteReceived('n1');
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Late' });
-            expect(nav.registration.showNotification).not.toHaveBeenCalled();
-        });
-
-        it('keeps a slow handler from showing an already dismissed notification', async () => {
-            away();
-            const { module, feed } = makeModule();
-            let finish;
-            await module.onPush('chat', () => new Promise((resolve) => { finish = resolve; }));
-            const delivery = feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            await module._receiveDismissal('n1');
-            finish({ title: 'Too late' });
-            await delivery;
-            expect(nav.registration.showNotification).not.toHaveBeenCalled();
-        });
-
-        it('shows a notification no handler takes, as sent', async () => {
-            away();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => ({ title: 'not this one' }));
-            await feed.deliver({
-                uid: 'n1',
-                channel: null,
-                title: 'Hi',
-                text: 'there',
-                target: '/c/1',
-            });
-            expect(nav.registration.showNotification).toHaveBeenCalledWith(
-                'Hi',
-                expect.objectContaining({
-                    body: 'there',
-                    data: {
-                        puter: expect.objectContaining({
-                            url: `${ORIGIN}/c/1`,
-                        }),
-                    },
-                }),
-            );
-        });
-
-        it('tags a grouped notification as its push and alerts again', async () => {
-            away();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => {});
-            await feed.deliver({
-                uid: 'n1',
-                channel: 'chat',
-                title: 'Hi',
-                group: 'room-1',
-                app: { uid: 'app-1', name: 'Chat' },
-            });
-            expect(nav.registration.showNotification).toHaveBeenCalledWith(
-                'Hi',
-                expect.objectContaining({
-                    tag: 'app-1:room-1',
-                    renotify: true,
-                }),
-            );
-        });
-
-        it('names only the app for a sensitive notification', async () => {
-            away();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => ({ title: 'Secret' }));
-            await feed.deliver({
-                uid: 'n1',
-                channel: 'chat',
-                title: 'Secret',
-                target: '/secret',
-                data: { id: 1 },
-                sensitive: true,
-                app: { uid: 'app-1', name: 'Chat' },
-            });
-            expect(nav.registration.showNotification).toHaveBeenCalledWith(
-                'Chat',
-                {
-                    body: 'New notification from Chat',
-                    tag: 'n1',
-                    renotify: false,
-                    data: {
-                        puter: {
-                            uid: 'n1',
-                            target: null,
-                            data: null,
-                            url: `${ORIGIN}/`,
-                        },
-                    },
-                },
-            );
-        });
-
-        it('shows the notification when its handler outlasts 5 seconds', async () => {
-            vi.useFakeTimers();
-            away();
-            const onError = vi.fn();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => new Promise(() => {}), {
-                onError,
-            });
-            const delivered = feed.deliver({
-                uid: 'n1',
-                channel: 'chat',
-                title: 'Hi',
-            });
-            await vi.advanceTimersByTimeAsync(5_000);
-            await delivered;
-            expect(onError).toHaveBeenCalledWith(
-                expect.objectContaining({ code: 'push_handler_timeout' }),
-            );
-            expect(nav.registration.showNotification).toHaveBeenCalledWith(
-                'Hi',
-                expect.any(Object),
-            );
-        });
-
-        it('looks up the registration of the worker it was given', async () => {
-            away();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => {}, {
-                serviceWorker: '/js/sw.js',
-            });
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(nav.serviceWorker.getRegistration).toHaveBeenLastCalledWith(
-                '/js/sw.js',
-            );
-        });
-
-        it('reads the tap URL from the saved tap base', async () => {
-            away();
-            nav.registration.scope = `${ORIGIN}/puter/`;
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => ({ url: 'chat/1' }), {
-                serviceWorker: '/puter/puter-sw.js',
-            });
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(
-                nav.registration.showNotification.mock.calls[0][1].data.puter
-                    .url,
-            ).toBe(`${ORIGIN}/chat/1`);
-        });
-
-        it('reads the tap URL from the worker`s scope', async () => {
-            away();
-            nav.registration.scope = `${ORIGIN}/app/`;
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => {});
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(
-                nav.registration.showNotification.mock.calls[0][1].data.puter
-                    .url,
-            ).toBe(`${ORIGIN}/app/`);
-        });
-
-        it('hands the notification to push-sw.js, which may hold it back', async () => {
-            away();
-            const posted = [];
-            nav.registration.active = {
-                scriptURL: SCRIPT,
-                postMessage: (message, [port]) => {
-                    posted.push(message);
-                    port.postMessage({ shown: false });
-                },
-            };
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => ({ actions: [{ action: 'accept', title: 'Accept' }] }));
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(posted).toEqual([
-                {
-                    type: 'puter-push-show',
-                    title: 'Hi',
-                    options: expect.objectContaining({ tag: 'n1', actions: [{ action: 'accept', title: 'Accept' }] }),
-                },
-            ]);
-            expect(nav.registration.showNotification).not.toHaveBeenCalled();
-        });
-
-        it('shows it itself when an older push-sw.js never answers', async () => {
-            vi.useFakeTimers();
-            away();
-            nav.registration.active = {
-                scriptURL: SCRIPT,
-                postMessage: vi.fn(),
-            };
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => {});
-            const delivered = feed.deliver({
-                uid: 'n1',
-                channel: 'chat',
-                title: 'Hi',
-            });
-            await vi.advanceTimersByTimeAsync(2_000);
-            await delivered;
-            expect(nav.registration.active.postMessage).toHaveBeenCalled();
-            expect(nav.registration.showNotification).toHaveBeenCalledTimes(1);
-        });
-
-        it('shows nothing while push is off here for the user', async () => {
-            store.delete(OPT_IN);
-            away();
-            const { module, feed } = makeModule();
+        it('never says it shows its own notification', async () => {
+            page({ visibilityState: 'hidden', focused: false });
+            const { module } = makeModule();
             await module.onPush('chat', () => {});
             await flush();
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(nav.registration.showNotification).not.toHaveBeenCalled();
-        });
-
-        it('shows nothing after disable()', async () => {
-            away();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => {});
-            await flush();
-            await module.disable();
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(nav.registration.showNotification).not.toHaveBeenCalled();
-        });
-
-        it('shows nothing while the page has focus', async () => {
-            page();
-            const { module, feed } = makeModule();
-            await module.onPush('chat', () => {});
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(nav.registration.showNotification).not.toHaveBeenCalled();
-        });
-
-        it('shows nothing inside the Puter desktop, which shows its own banner', async () => {
-            page({ focused: false });
-            const { module, feed } = makeModule({ env: 'app' });
-            await module.onPush('chat', () => {});
-            await feed.deliver({ uid: 'n1', channel: 'chat', title: 'Hi' });
-            expect(nav.registration.showNotification).not.toHaveBeenCalled();
-        });
-    });
-
-    describe('receipts', () => {
-        const answer = (module) => {
             const ack = vi.fn();
             module._noteReceived('n1');
             module._answerReceipt({ uid: 'n1' }, ack);
-            return ack.mock.calls[0][0];
-        };
-
-        it('says the page shows its own notification while its push feed runs', async () => {
-            store.set(OPT_IN, true);
-            withBrowser(makeNav());
-            const { module } = makeModule();
-            expect(answer(module).showsOwn).toBe(false);
-            const listener = await module.onPush('chat', () => {});
-            await flush();
-            expect(answer(module).showsOwn).toBe(true);
-            await listener.off();
-            expect(answer(module).showsOwn).toBe(false);
-        });
-
-        it('says it does not while push is off here, so pushes reach other devices', async () => {
-            withBrowser(makeNav({ existing: makeSubscription() }));
-            mockRequest.mockResolvedValue({ removed: true });
-            const { module } = makeModule();
-            await module.onPush('chat', () => {});
-            await flush();
-            expect(answer(module).showsOwn).toBe(false);
-
-            store.set(OPT_IN, true);
-            const { module: optedIn } = makeModule();
-            await optedIn.onPush('chat', () => {});
-            await flush();
-            expect(answer(optedIn).showsOwn).toBe(true);
-            await optedIn.disable();
-            expect(answer(optedIn).showsOwn).toBe(false);
-        });
-
-        it('hears another tab turn push off or on', async () => {
-            store.set(OPT_IN, true);
-            withBrowser(makeNav({ existing: makeSubscription() }));
-            server((route) =>
-                route === '/push/web/subscriptions'
-                    ? { status: 'active', device: { uid: 'd1' } }
-                    : { removed: true },
-            );
-            const { module: hidden } = makeModule();
-            await hidden.onPush('chat', () => {});
-            await vi.waitFor(() => expect(answer(hidden).showsOwn).toBe(true));
-
-            const { module: other } = makeModule();
-            await other.disable();
-            await vi.waitFor(() => expect(answer(hidden).showsOwn).toBe(false));
-
-            await other.enable();
-            await vi.waitFor(() => expect(answer(hidden).showsOwn).toBe(true));
-        });
-
-        it('says it does not without a registered worker or permission', async () => {
-            store.set(OPT_IN, true);
-            const nav = makeNav();
-            nav.serviceWorker.getRegistration.mockResolvedValue(undefined);
-            withBrowser(nav);
-            const { module } = makeModule();
-            await module.onPush('chat', () => {});
-            await flush();
-            expect(answer(module).showsOwn).toBe(false);
-
-            withBrowser(makeNav(), 'denied');
-            const { module: denied } = makeModule();
-            await denied.onPush('chat', () => {});
-            await flush();
-            expect(answer(denied).showsOwn).toBe(false);
+            expect(ack).toHaveBeenCalledWith({
+                received: true,
+                visibilityState: 'hidden',
+                focused: false,
+            });
         });
     });
 });

src/puter-js/src/push-sw.js

@@ -35,7 +35,6 @@
     const CHALLENGE_MESSAGE = 'puter-push-challenge';
     const CLICK_MESSAGE = 'puter-notification-click';
     const CLICK_ACK_MESSAGE = 'puter-notification-click-ack';
-    const SHOW_MESSAGE = 'puter-push-show';
     const CHANGED_MESSAGE = 'puter-push-subscription-changed';
     const CLICK_PARAM = 'puter.notification';
     const SHOWN_FIELDS = ['title', 'body', 'icon', 'badge', 'image', 'tag', 'url'];
@@ -238,20 +237,6 @@
         }
     }
 
-    // A page that got a notification live while away; held back while another window of the app has focus.
-    async function showForPage (message, source) {
-        for ( const win of await windows({ topLevel: true }) ) {
-            if ( win.focused && win.id !== source?.id ) return false;
-        }
-        const options = message.options && typeof message.options === 'object' ? message.options : {};
-        try {
-            await self.registration.showNotification(str(message.title) ?? DEFAULT_TITLE, options);
-        } catch {
-            await self.registration.showNotification(DEFAULT_TITLE, { data: options.data });
-        }
-        return true;
-    }
-
     async function forgetOldClicks () {
         const cutoff = Date.now() - CLICK_KEEP_MS;
         await idb(CLICKS, 'readwrite', (s) => {
@@ -376,16 +361,6 @@
         if ( ! message || typeof message !== 'object' ) return;
         if ( message.type === CLICK_ACK_MESSAGE ) {
             pendingClickAcks.get(message.id)?.();
-        } else if ( message.type === SHOW_MESSAGE ) {
-            event.waitUntil((async () => {
-                let shown = false;
-                try {
-                    shown = await showForPage(message, event.source);
-                } catch ( err ) {
-                    console.warn('[puter] could not show a notification', err);
-                }
-                event.ports?.[0]?.postMessage({ shown });
-            })());
         }
     });
 

src/puter-js/src/push-sw.test.js

@@ -747,59 +747,17 @@ describe('push-sw notificationclick', () => {
     });
 });
 
-describe('push-sw notifications a page shows', () => {
-    const show = async (worker, source, options = {}) => {
+describe('push-sw messages from a page', () => {
+    it('shows nothing a page posts, only pushes', async () => {
+        const worker = loadWorker();
         const port = { postMessage: vi.fn() };
         await worker.fire('message', {
-            data: {
-                type: 'puter-push-show',
-                title: 'Hi',
-                options: { tag: 'n1', data: { puter: { uid: 'n1' } }, ...options },
-            },
-            source,
+            data: { type: 'puter-push-show', title: 'Hi', options: { tag: 'n1' } },
+            source: { id: 'w1' },
             ports: [port],
         });
-        return port.postMessage.mock.calls[0]?.[0];
-    };
-
-    it('shows one for a page that is away, and says so', async () => {
-        const away = windowClient(`${ORIGIN}/`, { visibilityState: 'hidden' });
-        const worker = loadWorker({ windows: [away, windowClient(`${ORIGIN}/b`)] });
-        expect(await show(worker, away)).toEqual({ shown: true });
-        expect(worker.shown).toEqual([
-            { title: 'Hi', options: { tag: 'n1', data: { puter: { uid: 'n1' } } } },
-        ]);
-    });
-
-    it('holds it back while another window of the app has focus', async () => {
-        const away = windowClient(`${ORIGIN}/`);
-        const worker = loadWorker({
-            windows: [away, windowClient(`${ORIGIN}/b`, { focused: true })],
-        });
-        expect(await show(worker, away)).toEqual({ shown: false });
-        expect(worker.shown).toEqual([]);
-    });
-
-    it('passes the page`s action buttons to showNotification', async () => {
-        const worker = loadWorker();
-        const actions = [{ action: 'accept', title: 'Accept' }, { action: 'decline', title: 'Decline' }];
-        expect(await show(worker, null, { actions })).toEqual({ shown: true });
-        expect(worker.shown[0].options.actions).toEqual(actions);
-    });
-
-    it('shows it while only a nested frame of the app has focus', async () => {
-        const away = windowClient(`${ORIGIN}/`);
-        const worker = loadWorker({
-            windows: [away, windowClient(`${ORIGIN}/embed`, { focused: true, frameType: 'nested' })],
-        });
-        expect(await show(worker, away)).toEqual({ shown: true });
-    });
-
-    it('ignores other messages', async () => {
-        const worker = loadWorker();
-        await worker.fire('message', { data: { type: 'something-else' } });
-        await worker.fire('message', { data: null });
         expect(worker.shown).toEqual([]);
+        expect(port.postMessage).not.toHaveBeenCalled();
     });
 });