Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
feat(spaces): presence cursors over the React video and window-drag teleport in Electron (CUA-1414) (#5030)
Francesco Bonaccia77bd52c0e61
diff --git a/apps/cua-spaces-desktop/README.md b/apps/cua-spaces-desktop/README.mdindex 00a7d754c1..32496ce311 100644--- a/apps/cua-spaces-desktop/README.md+++ b/apps/cua-spaces-desktop/README.md@@ -293,9 +293,10 @@ and the Keyvault broker.the copies dismissed (`src/notch-feed.ts`); Dismiss hides and revokes orwipes nothing. The app reads the broker every 10 s while it runs, so accessis never silent. An app dropped on a tile opens that Space's Teleport review- at the app (the page's `?dropped=` names; the host holds the paths). A window- dragged onto the notch is not wired yet (no window-drag monitor in this- host).+ at the app (the page's `?dropped=` names; the host holds the paths). A real+ window dragged onto a tile (the SDK's window-drag monitor, which the notch+ model follows; it needs the Accessibility permission) does the same for+ that window's app.- **Presence prompts** are the system's, shown by the daemon (Touch ID'ssheet, Windows Hello, the desktop's polkit dialog). On Windows and Linux thehost brings the app forward first, so the dialog opens over it.@@ -432,10 +433,22 @@ measures both on one Space.only. Scrolls go to the page until the viewer has the keyboard. On a Mac,⌘ goes to a Linux or Windows Space as Control (⌘C arrives as Ctrl+C), anda ⌘ chord goes whole (press and release: Chromium drops its key-up).-5. **Pausing.** Every session closes while the page is hidden (the window is+5. **Presence.** The viewer and the picture-in-picture panels draw the+ other participants' cursors over the picture, and yours at the pointer,+ as the SwiftUI app's `PresenceOverlay` does: the SDK's cursor art and+ presence colors, a name pill for everyone but you, placed over the+ letterboxed picture, shown only while the stream is live. The page joins+ with `presence.join` (`src/bridge/presence.ts`: `Space.joinPresence` as+ the signed-in account, else this computer's user, with the app core's+ name and id), the events go to that window only, and the page draws with+ the shared `PresenceLayer`+ (`libs/cua/crates/cua-spacesd-html5/web/src/core/presenceLayer.ts`).+ `CUA_SPACES_TEST_PRESENCE=1` joins every Space as two synthetic+ participants circling the picture, for screenshots.+6. **Pausing.** Every session closes while the page is hidden (the window isminimized or on another desktop). They reopen with fresh tickets when itshows again.-6. **Picture in picture.** A Stream section row's PiP button (`stream.pip`)+7. **Picture in picture.** A Stream section row's PiP button (`stream.pip`)opens a floating window (`src/pip.ts`): on top of every window anddesktop, no frame, the stream's shape, 480 px wide where the last one wasleft. It shows the web UI's `/pip` view, a session of its own on the@@ -746,4 +759,5 @@ Swift app's files stay as they are.| `CUA_SPACES_NO_FUSES=1` | Build time: leave the Electron fuses as Electron ships them (QA builds only) || `CUA_SPACES_ARCHS` | Build time: `native` packs only the arches with a native folder, or a list (`x64`, `arm64,x64`); unset packs all (a release) || `CUA_SPACES_TEST_STREAM_URL` | Answer every `spaces.openStream` with this URL (`{id}`, `{tier}` filled in), for the WebCodecs harness |+| `CUA_SPACES_TEST_PRESENCE=1` | Answer every `presence.join` with two synthetic participants circling the picture (screenshots, the WebCodecs harness) || `CUA_BIN`, `CUA_HOME` | Where to find `cua` and `~/.cua`. A `CUA_BIN` that doesn't exist means no cua (demo data) |diff --git a/apps/cua-spaces-desktop/src/bridge/host.ts b/apps/cua-spaces-desktop/src/bridge/host.tsindex dbf40f5325..b6f23c47fd 100644--- a/apps/cua-spaces-desktop/src/bridge/host.ts+++ b/apps/cua-spaces-desktop/src/bridge/host.ts@@ -148,20 +148,21 @@ export interface BridgeEvent {}export class BridgeEvents {- private readonly listeners = new Set<(e: BridgeEvent) => void>();+ private readonly listeners = new Set<(e: BridgeEvent, to?: unknown) => void>();- emit(event: string, payload?: unknown): void {+ /** `to`: only that window gets it (a presence session's events); none: every window. */+ emit(event: string, payload?: unknown, to?: unknown): void {const e: BridgeEvent = payload === undefined ? { event } : { event, payload };for (const l of [...this.listeners]) {try {- l(e);+ l(e, to);} catch (error) {console.error("[cua-spaces] bridge event listener failed", error);}}}- subscribe(listener: (e: BridgeEvent) => void): () => void {+ subscribe(listener: (e: BridgeEvent, to?: unknown) => void): () => void {this.listeners.add(listener);return () => this.listeners.delete(listener);}diff --git a/apps/cua-spaces-desktop/src/bridge/index.ts b/apps/cua-spaces-desktop/src/bridge/index.tsindex d2bcf66491..7cc76fd0bb 100644--- a/apps/cua-spaces-desktop/src/bridge/index.ts+++ b/apps/cua-spaces-desktop/src/bridge/index.ts@@ -23,6 +23,7 @@ import { hostStatus, machinesMethods } from "./machines";import { ELECTRON_METHODS, METHODS } from "./methods";import { notificationsMethods } from "./notifications";import { onboardingMethods } from "./onboarding";+import { presenceMethods } from "./presence";import { relayUsageMethods } from "./relay-usage";import { sessionMethods, sessionState } from "./session";import { settingsMethods } from "./settings";@@ -64,6 +65,7 @@ export const AREAS = [streamMethods,onboardingMethods,relayUsageMethods,+ presenceMethods,];export interface Bridge {diff --git a/apps/cua-spaces-desktop/src/bridge/ipc.ts b/apps/cua-spaces-desktop/src/bridge/ipc.tsindex d564105e80..4c3549ec68 100644--- a/apps/cua-spaces-desktop/src/bridge/ipc.ts+++ b/apps/cua-spaces-desktop/src/bridge/ipc.ts@@ -3,7 +3,7 @@// The bridge on Electron's IPC: the preload's one request channel// (`ELECTRON_BRIDGE_CHANNEL`) into the method table, and its events out to-// every window on `ELECTRON_EVENT_CHANNEL`. Only the app's own pages, in+// every window (or the one window an event is for) on `ELECTRON_EVENT_CHANNEL`. Only the app's own pages, in// their main frame, may call in (the SwiftUI host's origin check).import { BrowserWindow, ipcMain, type IpcMainInvokeEvent } from "electron";import { ELECTRON_BRIDGE_CHANNEL, ELECTRON_EVENT_CHANNEL, PRELOAD_INIT_CHANNEL, type PreloadInit } from "../channels";@@ -41,9 +41,9 @@ export function installBridgeIpc({ registry, events, platform, videoStats }: Brireturn registry.dispatch(request, { window: BrowserWindow.fromWebContents(event.sender) });});- events?.subscribe((e: BridgeEvent) => {+ events?.subscribe((e: BridgeEvent, to?: unknown) => {for (const win of BrowserWindow.getAllWindows()) {- if (!win.isDestroyed()) win.webContents.send(ELECTRON_EVENT_CHANNEL, e);+ if (!win.isDestroyed() && (to === undefined || to === win)) win.webContents.send(ELECTRON_EVENT_CHANNEL, e);}});}diff --git a/apps/cua-spaces-desktop/src/bridge/methods.ts b/apps/cua-spaces-desktop/src/bridge/methods.tsindex 11df20cc94..e4e1ab2b71 100644--- a/apps/cua-spaces-desktop/src/bridge/methods.ts+++ b/apps/cua-spaces-desktop/src/bridge/methods.ts@@ -45,8 +45,9 @@ export const METHODS = [] as const;/** A live desktop's media ticket for the page's WebCodecs player, the- * first run's state (the SwiftUI app draws its first run natively), and the- * account's relay allowance. */-export const ELECTRON_METHODS = ["onboarding.get", "onboarding.complete", "spaces.openStream", "relay.usage"] as const;+ * first run's state (the SwiftUI app draws its first run natively), the+ * account's relay allowance, and presence over the page's video (the+ * SwiftUI app draws it natively). */+export const ELECTRON_METHODS = ["onboarding.get", "onboarding.complete", "spaces.openStream", "relay.usage", "presence.join", "presence.publish", "presence.leave"] as const;export type Method = (typeof METHODS)[number] | (typeof ELECTRON_METHODS)[number];diff --git a/apps/cua-spaces-desktop/src/bridge/presence.ts b/apps/cua-spaces-desktop/src/bridge/presence.tsnew file mode 100644index 0000000000..972c64f8d0--- /dev/null+++ b/apps/cua-spaces-desktop/src/bridge/presence.ts@@ -0,0 +1,234 @@+// SPDX-License-Identifier: FSL-1.1-MIT+// Copyright (c) 2026 Cua AI, Inc.++// Presence over the video the page draws (`presence.join`, `presence.publish`,+// `presence.leave`; the web bridge's ops/presence.ts): one `PresenceService`+// session per page and Space, joined through the cua SDK+// (`Space.joinPresence`), as the SwiftUI app's `LiveStreamSession` and the+// Tauri app's `presence_join` do. This only moves data; the page folds the+// events into the SDK's `PresenceView` and draws.+//+// - `presence.join` joins as the signed-in account (else this computer's+// user), with the app core's name and principal id, and answers the+// caller, the roster and the render delay for the transport;+// - every event goes to the joining window only, as `presence.event`+// `{handle, event}`, in the TS SDK's `PresenceEvent` shape (the binding's+// records already are);+// - `presence.publish` moves your cursor (the SDK throttles to 30 Hz, newest+// wins, show and hide at once);+// - `presence.leave`, the window closing or loading a new page (a reload),+// or the stream ending leaves.+//+// `CUA_SPACES_TEST_PRESENCE=1` joins every Space as a synthetic session with+// two participants circling the picture, for screenshots and the WebCodecs+// harness (`CUA_SPACES_TEST_STREAM_URL`).+import { userInfo } from "node:os";+import type { PresenceCursor, PresenceEvent, PresenceIdentity, PresenceMember, PresenceParticipant } from "../native/generated/index";+import type { AppModel } from "../model/app-model";+import { string } from "./args";+import type { BridgeContext } from "./context";+import { Failure, type BridgeArgs, type Handlers } from "./host";++/** How long a join may take before the page goes without presence. */+export const JOIN_TIMEOUT_MS = 10_000;+/** One `nextEvent` wait; the pump checks for a leave between waits. */+export const EVENT_WAIT_MS = 1_000;+/** Remote cursors are drawn this far in the past, per transport (the Tauri app's). */+export const STREAM_DELAY_MS = 100;+export const DATAGRAM_DELAY_MS = 66;+/** Consecutive failed waits before the session is given up (the SwiftUI app's `presenceRetries`). */+export const MAX_FAILURES = 5;++/** The parts of the SDK's `SpacePresence` this uses. */+export interface PresenceSessionLike {+ me(): Promise<PresenceParticipant>;+ roster(): Promise<PresenceMember[]>;+ nextEvent(timeoutMs: bigint | undefined): Promise<PresenceEvent | undefined>;+ updateCursor(cursor: PresenceCursor): Promise<void>;+ usesDatagrams(): boolean;+ leave(): Promise<void>;+}++/** Joins a Space's presence as `identity`. */+export type PresenceJoiner = (spaceId: string, identity: PresenceIdentity) => Promise<PresenceSessionLike>;++/** Who this app joins as (the Tauri app's `identity`, the SwiftUI app's `presenceName`): the core's name and id for the signed-in account, else this computer's user. */+export function presenceIdentity(model: Pick<AppModel, "native" | "identity" | "account">, osUser: string | undefined): PresenceIdentity {+ const p = model.identity ? model.account?.profile() : null;+ return {+ id: model.native.appPresencePrincipalId(p?.email, p?.subject, p?.username, osUser),+ displayName: model.native.appPresenceName(p?.name, p?.email, p?.username, undefined, osUser),+ color: "",+ agent: false,+ };+}++const isTimeout = (error: unknown) => (error as { tag?: unknown } | null)?.tag === "Timeout";++interface Joined {+ session: PresenceSessionLike;+ window: unknown;+ left: boolean;+}++/** The live sessions by handle, and the pumps that forward their events. */+export class PresenceSessions {+ private next = 0;+ private readonly live = new Map<string, Joined>();++ constructor(+ private readonly join: PresenceJoiner,+ /** Sends one event to one window. */+ private readonly send: (window: unknown, payload: { handle: string; event: PresenceEvent }) => void,+ ) {}++ async open(spaceId: string, identity: PresenceIdentity, window: unknown) {+ const session = await this.join(spaceId, identity);+ const [me, members] = await Promise.all([session.me(), session.roster()]);+ const handle = `p${++this.next}`;+ const joined: Joined = { session, window, left: false };+ this.live.set(handle, joined);+ onGone(window, () => this.leave(handle));+ void this.pump(handle, joined);+ const datagrams = session.usesDatagrams();+ return { handle, me, members, delayMs: datagrams ? DATAGRAM_DELAY_MS : STREAM_DELAY_MS, datagrams };+ }++ async publish(handle: string, cursor: Pick<PresenceCursor, "x" | "y" | "visible" | "windowId">): Promise<void> {+ const joined = this.live.get(handle);+ if (!joined) throw Failure.notFound(`no presence session ${handle}`);+ await joined.session.updateCursor({+ displayId: "",+ ...(cursor.windowId ? { windowId: cursor.windowId } : {}),+ x: cursor.x,+ y: cursor.y,+ visible: cursor.visible,+ pressed: false,+ shape: "arrow",+ shapeSource: "unspecified",+ atMs: 0,+ receivedMs: 0,+ });+ }++ leave(handle: string): void {+ const joined = this.live.get(handle);+ if (!joined) return;+ this.live.delete(handle);+ joined.left = true;+ }++ /** Live handles (tests). */+ get handles(): string[] {+ return [...this.live.keys()];+ }++ /** Forwards events until a leave, the stream's end or repeated failures; then leaves the Space. */+ private async pump(handle: string, joined: Joined): Promise<void> {+ let failures = 0;+ while (!joined.left) {+ let event: PresenceEvent | undefined;+ try {+ event = await joined.session.nextEvent(BigInt(EVENT_WAIT_MS));+ failures = 0;+ } catch (error) {+ if (isTimeout(error)) continue;+ if (++failures >= MAX_FAILURES) break;+ continue;+ }+ if (!event) break;+ if (!joined.left) this.send(joined.window, { handle, event });+ }+ this.leave(handle);+ await joined.session.leave().catch(() => {});+ }+}++type Once = { once?: (event: string, f: () => void) => void };++/** Calls `f` when an Electron window closes or loads a new page, whose own sessions are gone (no Electron here: duck-typed). */+function onGone(window: unknown, f: () => void): void {+ let done = false;+ const once = () => {+ if (done) return;+ done = true;+ f();+ };+ const w = window as (Once & { webContents?: Once }) | null;+ w?.once?.("closed", once);+ w?.webContents?.once?.("did-navigate", once);+}++const finite = (args: BridgeArgs, key: string): number => {+ const v = args[key];+ if (typeof v !== "number" || !Number.isFinite(v)) throw Failure.badArgs(`${key}: number`);+ return v;+};++export function presenceMethods(ctx: BridgeContext, joiner?: PresenceJoiner): Handlers {+ const { model, events, env } = ctx;+ const join: PresenceJoiner =+ joiner ??+ (env.CUA_SPACES_TEST_PRESENCE === "1"+ ? async () => syntheticPresence()+ : async (spaceId, identity) => model.backend.joinPresence(spaceId, identity, JOIN_TIMEOUT_MS));+ const sessions = new PresenceSessions(join, (window, payload) => events.emit("presence.event", payload, window));+ let osUser: string | undefined;+ try {+ osUser = userInfo().username || undefined;+ } catch {+ osUser = undefined;+ }+ return {+ "presence.join": async (args, caller) => {+ const spaceId = string(args, "spaceId");+ if (!model.spaces.some((s) => s.id === spaceId) && env.CUA_SPACES_TEST_PRESENCE !== "1") throw Failure.notFound(`no Space ${spaceId}`);+ return sessions.open(spaceId, presenceIdentity(model, osUser), caller.window);+ },+ "presence.publish": async (args) => {+ const windowId = args.windowId;+ if (windowId !== undefined && typeof windowId !== "string") throw Failure.badArgs("windowId: string");+ if (typeof args.visible !== "boolean") throw Failure.badArgs("visible: boolean");+ await sessions.publish(string(args, "handle"), { x: finite(args, "x"), y: finite(args, "y"), visible: args.visible, windowId: windowId || undefined });+ return null;+ },+ "presence.leave": (args) => {+ sessions.leave(string(args, "handle"));+ return null;+ },+ };+}++/**+ * A session with two participants circling the picture (Ada slowly, an+ * agent faster, the agent's cursor a hand), one move each per ~33 ms. Your+ * own cursor is accepted and dropped.+ */+export function syntheticPresence(now: () => number = Date.now): PresenceSessionLike {+ const me: PresenceParticipant = { participantId: "you", principalId: "user:you", displayName: "You", color: "#4363d8", kind: "human" };+ const others: { p: PresenceParticipant; period: number; radius: number; shape: string }[] = [+ { p: { participantId: "ada", principalId: "user:ada", displayName: "Ada Lovelace", color: "#e6194b", kind: "human" }, period: 9_000, radius: 0.28, shape: "arrow" },+ { p: { participantId: "agent", principalId: "agent:claude", displayName: "Claude", color: "#f58231", kind: "agent" }, period: 5_000, radius: 0.18, shape: "pointer" },+ ];+ let turn = 0;+ let left = false;+ const at = (o: (typeof others)[number], t: number): PresenceCursor => {+ const a = (2 * Math.PI * (t % o.period)) / o.period;+ return { displayId: "", x: 0.5 + o.radius * Math.cos(a), y: 0.5 + o.radius * Math.sin(a), visible: true, pressed: false, shape: o.shape, shapeSource: "probe", atMs: t, receivedMs: t };+ };+ return {+ me: async () => me,+ roster: async () => [{ participant: me }, ...others.map((o) => ({ participant: o.p, cursor: at(o, now()) }))],+ nextEvent: async () => {+ await new Promise((r) => setTimeout(r, 33 / others.length));+ if (left) return undefined;+ const o = others[turn++ % others.length]!;+ return { kind: "cursor_moved", participantId: o.p.participantId, cursor: at(o, now()) };+ },+ updateCursor: async () => {},+ usesDatagrams: () => false,+ leave: async () => {+ left = true;+ },+ };+}diff --git a/apps/cua-spaces-desktop/src/main.ts b/apps/cua-spaces-desktop/src/main.tsindex ef564c6bfe..2680b886d4 100644--- a/apps/cua-spaces-desktop/src/main.ts+++ b/apps/cua-spaces-desktop/src/main.ts@@ -22,7 +22,7 @@ import { recordLaunch, refreshAfterUpdate } from "./model/update-refresh";import { loadNative } from "./native/load";import { nativeDir } from "./native/location";import { connectNotch, type NotchCore } from "./notch";-import { dropOnSpace, feedNotch, notchThumbnail, openSpaceFromNotch, type NotchFeedUi } from "./notch-feed";+import { dropOnSpace, feedNotch, notchTeleport, notchThumbnail, openSpaceFromNotch, teleportFromNotch, type NotchFeedUi } from "./notch-feed";import { createPipWindows } from "./pip";import { electronKeyvaultPrompts } from "./prompts";import { APP_ORIGIN, handleAppProtocol, registerSchemePrivileges } from "./protocol";@@ -183,12 +183,17 @@ async function startNativeHost(showRoute: (route: string) => void, globalShortcuopenAccess: () => showRoute("/keyvault?view=access"),// Hides the indicator and the tiles' key; nothing is revoked or wiped.dismissAccess: () => model.keyvault.dismiss(),- // No window-drag monitor yet (no `teleport` below), so no drag commits.- teleport: (spaceId) => showRoute(`/spaces/${encodeURIComponent(spaceId)}`),+ // A window dragged onto a tile: the Teleport review for its app there.+ teleport: (spaceId, app) => void teleportFromNotch(model, notchUi, spaceId, app),drop: (spaceId, paths) => void dropOnSpace(model, notchUi, spaceId, paths),},+ teleport: notchTeleport(() => model.backend.teleportHandle()),});- if (notch) feedNotch(notch, model);+ if (notch) {+ feedNotch(notch, model);+ // Window drags need the SDK: look again once it is in.+ if (!model.startup.isReady) model.startup.onReady.push(() => notch.recheckPermission());+ }return { env, bridge, background };}diff --git a/apps/cua-spaces-desktop/src/model/backend.ts b/apps/cua-spaces-desktop/src/model/backend.tsindex ef1ba51531..8cdb991aca 100644--- a/apps/cua-spaces-desktop/src/model/backend.ts+++ b/apps/cua-spaces-desktop/src/model/backend.ts@@ -27,6 +27,8 @@ import type {SpaceShares,SpaceWindow,SpaceLike,+ SpacePresenceLike,+ PresenceIdentity,TeleportLike,} from "../native/generated/index";import { words } from "./errors";@@ -85,6 +87,8 @@ export interface SpacesBackend {teleportContext(id: string): Promise<{ teleport: TeleportLike; space: SpaceLike } | null>;/** The SDK's teleport handle, for drops (no Space needed). */teleportHandle(): TeleportLike | null;+ /** Joins a Space's presence as `identity`, waiting up to `timeoutMs` for the roster. */+ joinPresence(id: string, identity: PresenceIdentity, timeoutMs: number): Promise<SpacePresenceLike>;/** A Space's app icons in one call (`Space.appIcons`, through its one icon cache): 64 px PNG or SVG bytes, null where it has none. */appIcons(id: string, requests: SpaceAppIconRequest[]): Promise<(Uint8Array | null)[]>;}@@ -470,6 +474,10 @@ export class LiveSpacesBackend implements SpacesBackend {return this.teleport;}+ async joinPresence(id: string, identity: PresenceIdentity, timeoutMs: number): Promise<SpacePresenceLike> {+ return (await this.cua.spaces().space(id)).joinPresence(identity, BigInt(timeoutMs));+ }+async appIcons(id: string, requests: SpaceAppIconRequest[]): Promise<(Uint8Array | null)[]> {try {const icons = await (await this.cua.spaces().space(id)).appIcons(requests);diff --git a/apps/cua-spaces-desktop/src/model/pending.ts b/apps/cua-spaces-desktop/src/model/pending.tsindex c0d899c009..44a7cdd4d4 100644--- a/apps/cua-spaces-desktop/src/model/pending.ts+++ b/apps/cua-spaces-desktop/src/model/pending.ts@@ -13,6 +13,7 @@ import type {SpaceAppIconRequest,SpaceCreateProgress,SpaceLike,+ PresenceIdentity,TeleportLike,} from "../native/generated/index";import type { LiveSpacesBackend, SpacesBackend } from "./backend";@@ -120,6 +121,7 @@ export class PendingSpacesBackend implements SpacesBackend {tool = async (tool: string, args: Record<string, unknown>) => (await this.b()).tool(tool, args);teleportContext = async (id: string): Promise<{ teleport: TeleportLike; space: SpaceLike } | null> => (await this.b()).teleportContext(id);teleportHandle = () => this.current?.teleportHandle() ?? null;+ joinPresence = async (id: string, identity: PresenceIdentity, timeoutMs: number) => (await this.b()).joinPresence(id, identity, timeoutMs);appIcons = async (id: string, requests: SpaceAppIconRequest[]) => (await this.b()).appIcons(id, requests);}diff --git a/apps/cua-spaces-desktop/src/notch-feed.ts b/apps/cua-spaces-desktop/src/notch-feed.tsindex 14d669f5b6..db102f7831 100644--- a/apps/cua-spaces-desktop/src/notch-feed.ts+++ b/apps/cua-spaces-desktop/src/notch-feed.ts@@ -12,11 +12,15 @@// go, and the Space shown; a notification says what landed or why not.// An app bundle among them opens the Teleport review for that app in that// Space, as a drop on the Space's well does (`?dropped=` on its page).+// - A real window dragged onto a tile (the SDK's window-drag monitor, which+// the notch model follows: `notchTeleport`) opens the Teleport review for+// that window's app in that Space, the same way as its bundle dropped there.import { basename } from "node:path";import { fileOffers, sendOffered } from "./bridge/files";import type { AppModel } from "./model/app-model";import { words } from "./model/errors";-import type { Notch } from "./notch";+import type { TeleportLike } from "./native/generated/index";+import type { Notch, NotchTeleport } from "./notch";export interface NotchFeedUi {/** Shows a Space in the main window (its page); `dropped`: the names of the apps and files just dropped on its tile, which the page treats as a drop on the well. */@@ -63,6 +67,45 @@ export async function dropOnSpace(model: AppModel, ui: NotchFeedUi, spaceId: str}}+/**+ * A window dragged onto a tile committed to that Space: the Teleport review+ * for its app (the SwiftUI app's `onTeleport`), as its bundle dropped on the+ * tile. An app the SDK found no bundle for opens the Space only.+ */+export function teleportFromNotch(model: AppModel, ui: NotchFeedUi, spaceId: string, app: unknown): Promise<void> {+ const path = (app as { hostPath?: unknown } | null)?.hostPath;+ if (typeof path === "string" && isAppBundle(path)) return dropOnSpace(model, ui, spaceId, [path]);+ openSpaceFromNotch(model, ui, spaceId);+ return Promise.resolve();+}++/**+ * The SDK's teleport handle as the notch model follows window drags with it,+ * read when asked: none before the SDK is in (drags are then unsupported;+ * check again once it is). Starting the monitor waits for its event tap, so+ * it runs after the current task, never inside the notch's own calls.+ */+export function notchTeleport(handle: () => TeleportLike | null): NotchTeleport {+ return {+ windowDragSupported: () => handle()?.windowDragSupported() ?? false,+ windowDragPermitted: () => handle()?.windowDragPermitted() ?? false,+ requestWindowDragPermission: () => handle()?.requestWindowDragPermission() ?? false,+ startWindowDrag: (listener) =>+ new Promise((resolve, reject) =>+ setImmediate(() => {+ const teleport = handle();+ if (!teleport) return reject(new Error("the cua SDK is not running"));+ try {+ resolve(teleport.startWindowDrag(listener as Parameters<TeleportLike["startWindowDrag"]>[0]));+ } catch (error) {+ reject(error);+ }+ }),+ ),+ captureWindowThumbnail: (windowId, maxWidth) => handle()?.captureWindowThumbnail(windowId, maxWidth) ?? null,+ };+}+/*** Feeds the notch the Spaces, the "Spaces tab in the notch" setting, the live* Keyvault sign-ins (less the copies dismissed from the notch: the SwiftUIdiff --git a/apps/cua-spaces-desktop/test/bridge-native.test.ts b/apps/cua-spaces-desktop/test/bridge-native.test.tsindex 71a153949a..7a5a22c4e1 100644--- a/apps/cua-spaces-desktop/test/bridge-native.test.ts+++ b/apps/cua-spaces-desktop/test/bridge-native.test.ts@@ -170,8 +170,8 @@ describe.skipIf(!built)("the bridge on the app core", () => {for (const [method, args] of cases) problems.push(...shapeProblems(method, await call(method, args)));expect(problems).toEqual([]);// Every ported method has its case (or is checked below).- // (Teleport and the Keyvault: vault-native.test.ts; This machine, Devices, Settings and the rest: host-bridge.test.ts; the relay allowance: relay-usage.test.ts.)- const elsewhere = new Set(["session.signIn", "spaces.create", "spaces.delete", "spaces.openStream", "relay.usage", ...AGENT_METHODS, ...VAULT_METHODS, ...HOST_METHODS]);+ // (Teleport and the Keyvault: vault-native.test.ts; This machine, Devices, Settings and the rest: host-bridge.test.ts; the relay allowance: relay-usage.test.ts; presence: presence-bridge.test.ts.)+ const elsewhere = new Set(["session.signIn", "spaces.create", "spaces.delete", "spaces.openStream", "relay.usage", "presence.join", "presence.publish", "presence.leave", ...AGENT_METHODS, ...VAULT_METHODS, ...HOST_METHODS]);const ported = bridge.registry.methods.filter((m) => !NOT_YET.includes(m) && !elsewhere.has(m));expect(ported.filter((m) => !cases.some(([c]) => c === m))).toEqual([]);});@@ -180,7 +180,7 @@ describe.skipIf(!built)("the bridge on the app core", () => {const info = (await call("app.info")) as { platform: string; host: string; version: string; methods: string[] };expect(info).toMatchObject({ platform: "macos", host: "electron", version: "1.2.3" });expect(info.methods[0]).toBe("app.info");- expect(info.methods.at(-1)).toBe("relay.usage");+ expect(info.methods.at(-1)).toBe("presence.leave");});it("answers New Space's options while starting and once ready", () => {@@ -476,7 +476,7 @@ describe.skipIf(!built)("the bridge on the app core", () => {"clouds.connect": { target: { provider: "aws", region: "us-west-2" }, makeDefault: false },};// This machine, Devices, Settings and the rest: host-bridge.test.ts reads them with their arguments.- const skip = new Set<OpName>(["spaces.create", "spaces.delete", "session.signIn", "session.signOut", "session.openExternal", "spaces.openStream", "relay.usage", ...VAULT_OPS, ...(HOST_OPS as OpName[])]);+ const skip = new Set<OpName>(["spaces.create", "spaces.delete", "session.signIn", "session.signOut", "session.openExternal", "spaces.openStream", "relay.usage", "presence.join", "presence.publish", "presence.leave", ...VAULT_OPS, ...(HOST_OPS as OpName[])]);const problems: string[] = [];const checked: string[] = [];for (const op of OPERATIONS) {diff --git a/apps/cua-spaces-desktop/test/bridge-spaces.test.ts b/apps/cua-spaces-desktop/test/bridge-spaces.test.tsindex 2d5c2aefb6..a05060b6c9 100644--- a/apps/cua-spaces-desktop/test/bridge-spaces.test.ts+++ b/apps/cua-spaces-desktop/test/bridge-spaces.test.ts@@ -11,7 +11,7 @@ import { tmpdir } from "node:os";import * as path from "node:path";import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";import { createBridge, type Bridge } from "../src/bridge";-import { dropOnSpace, feedNotch, notchThumbnail, openSpaceFromNotch, type NotchFeedUi } from "../src/notch-feed";+import { dropOnSpace, feedNotch, notchThumbnail, openSpaceFromNotch, teleportFromNotch, type NotchFeedUi } from "../src/notch-feed";import { spaceStreams } from "../src/bridge/space-detail";import { AppModel } from "../src/model/app-model";import { CloudModel } from "../src/model/cloud";@@ -348,5 +348,18 @@ describe.skipIf(!built)("a Space's detail, files, sharing and clouds on the appexpect(notes).toEqual([]);expect(model.selectedSpaceId).toBe(aurora);});++ it("opens the Teleport review for a window dragged onto a tile, as its app dropped there", async () => {+ const { u, shown, dropped } = ui();+ await teleportFromNotch(model, u, aurora, { id: "notes", name: "Notes", hostPath: "/System/Applications/Notes.app" });+ expect(shown).toEqual([aurora]);+ expect(dropped).toEqual([["Notes.app"]]);+ expect(await call("spaces.droppedFiles", { names: ["Notes.app"] })).toEqual(["/System/Applications/Notes.app"]);+ expect(backend.sent).toEqual([]);+ // An app with no bundle: the Space only.+ await teleportFromNotch(model, u, aurora, { id: "x", name: "Some Tool" });+ expect(shown).toEqual([aurora, aurora]);+ expect(dropped.at(-1)).toBeUndefined();+ });});});diff --git a/apps/cua-spaces-desktop/test/fixtures.ts b/apps/cua-spaces-desktop/test/fixtures.tsindex 01cb53b6e8..0161271580 100644--- a/apps/cua-spaces-desktop/test/fixtures.ts+++ b/apps/cua-spaces-desktop/test/fixtures.ts@@ -18,6 +18,7 @@ import type {SpaceAppIconRequest,SpaceCreateProgress,SpaceLike,+ SpacePresenceLike,TeleportLike,} from "../src/native/generated/index";import type { LocalRuntimes, SpaceThumbnailData, SpacesBackend } from "../src/model/backend";@@ -250,6 +251,10 @@ export class FixtureSpacesBackend implements SpacesBackend {teleportHandle() {return this.teleport;}+ /** Presence: no Space here has it. */+ async joinPresence(id: string): Promise<SpacePresenceLike> {+ throw new Error(`${id} has no presence`);+ }async appIcons(_id: string, requests: SpaceAppIconRequest[]) {this.iconRequests.push(requests);return requests.map((r) => this.guestIcons.get(r.appName) ?? null);diff --git a/apps/cua-spaces-desktop/test/notch.test.ts b/apps/cua-spaces-desktop/test/notch.test.tsindex 10a1a5637c..170e4e5aaa 100644--- a/apps/cua-spaces-desktop/test/notch.test.ts+++ b/apps/cua-spaces-desktop/test/notch.test.ts@@ -8,6 +8,7 @@ import * as path from "node:path";import { PassThrough } from "node:stream";import { describe, expect, it, vi } from "vitest";import { helperPath, notchSupported, startNotch, type NotchActions } from "../src/notch";+import { notchTeleport } from "../src/notch-feed";import { fakeCore, manualClock, MOTION } from "./fakeNotchCore";const require = createRequire(import.meta.url);@@ -227,3 +228,29 @@ describe("the notch end to end (fake helper)", () => {expect(children).toHaveLength(1);});});++describe("window drags onto the notch", () => {+ it("follows window drags with the SDK's teleport handle once there is one", async () => {+ let handle: { windowDragSupported(): boolean; windowDragPermitted(): boolean; requestWindowDragPermission(): boolean; startWindowDrag: ReturnType<typeof vi.fn>; captureWindowThumbnail(): ArrayBuffer } | null = null;+ const t = notchTeleport(() => handle as never);+ expect(t.windowDragSupported()).toBe(false);+ expect(t.windowDragPermitted()).toBe(false);+ await expect(t.startWindowDrag({ onEvent() {} })).rejects.toThrow(/not running/);+ const monitor = { stop: vi.fn() };+ handle = {+ windowDragSupported: () => true,+ windowDragPermitted: () => true,+ requestWindowDragPermission: () => true,+ startWindowDrag: vi.fn(() => monitor),+ captureWindowThumbnail: () => new ArrayBuffer(3),+ };+ expect(t.windowDragSupported()).toBe(true);+ const listener = { onEvent() {} };+ const started = t.startWindowDrag(listener);+ // Not inside the caller's own call: the event tap may take a while to start.+ expect(handle.startWindowDrag).not.toHaveBeenCalled();+ expect(await started).toBe(monitor);+ expect(handle.startWindowDrag).toHaveBeenCalledWith(listener);+ expect((t.captureWindowThumbnail(7, 320) as ArrayBuffer).byteLength).toBe(3);+ });+});diff --git a/apps/cua-spaces-desktop/test/presence-bridge.test.ts b/apps/cua-spaces-desktop/test/presence-bridge.test.tsnew file mode 100644index 0000000000..b06c497b9e--- /dev/null+++ b/apps/cua-spaces-desktop/test/presence-bridge.test.ts@@ -0,0 +1,166 @@+// SPDX-License-Identifier: FSL-1.1-MIT+// Copyright (c) 2026 Cua AI, Inc.++// `presence.join`, `presence.publish`, `presence.leave`: one SDK presence+// session per page and Space, its events to the joining window only, in the+// web contract's shapes.+import { EventEmitter } from "node:events";+import { describe, expect, it, vi } from "vitest";+import { OP_SHAPES, SHAPE_DEFS } from "../../cua-spaces-web/src/bridge/contracts/shapes";+import { validate } from "../../cua-spaces-web/src/bridge/contracts/schema";+import type { BridgeContext } from "../src/bridge/context";+import { BridgeEvents } from "../src/bridge/host";+import { presenceIdentity, presenceMethods, syntheticPresence, type PresenceSessionLike } from "../src/bridge/presence";+import type { PresenceCursor, PresenceEvent, PresenceIdentity } from "../src/native/generated/index";++const ADA = { participantId: "p1", principalId: "user:ada", displayName: "Ada", color: "#e6194b", kind: "human" };+const BOB = { participantId: "p2", principalId: "user:bob", displayName: "Bob", color: "#4363d8", kind: "human" };++/** A session whose events the test feeds. */+function fakeSession() {+ const queue: (PresenceEvent | undefined | Error)[] = [];+ const waiting: ((e: PresenceEvent | undefined | Error) => void)[] = [];+ const cursors: PresenceCursor[] = [];+ let left = 0;+ const session: PresenceSessionLike = {+ me: async () => ADA,+ roster: async () => [{ participant: ADA }, { participant: BOB }],+ nextEvent: () =>+ new Promise((resolve, reject) => {+ const take = (e: PresenceEvent | undefined | Error) => (e instanceof Error ? reject(e) : resolve(e));+ const next = queue.shift();+ if (next !== undefined || queue.length > 0) take(next);+ else waiting.push(take);+ }),+ updateCursor: async (c) => void cursors.push(c),+ usesDatagrams: () => true,+ leave: async () => void (left += 1),+ };+ const push = (e: PresenceEvent | undefined | Error) => {+ const w = waiting.shift();+ if (w) w(e);+ else queue.push(e);+ };+ return { session, push, cursors, left: () => left };+}++function context(signedIn = true) {+ const events = new BridgeEvents();+ const ctx = {+ model: {+ spaces: [{ id: "local:a" }],+ identity: signedIn ? "[email protected]" : null,+ account: { profile: () => ({ name: "Ada Lovelace", email: "[email protected]", subject: "sub-1" }) },+ native: {+ appPresenceName: (name?: string, _e?: string, _u?: string, _f?: string, os?: string) => name ?? os ?? "",+ appPresencePrincipalId: (email?: string, _s?: string, _u?: string, os?: string) => (email ? `user:${email}` : `os:${os}`),+ },+ },+ events,+ env: {},+ } as unknown as BridgeContext;+ return { ctx, events };+}++const tick = () => new Promise((r) => setTimeout(r, 0));++describe("presence", () => {+ it("joins as the signed-in account, else this computer's user", () => {+ const { ctx } = context();+ expect(presenceIdentity(ctx.model, "ada")).toEqual({ id: "user:[email protected]", displayName: "Ada Lovelace", color: "", agent: false });+ const out = context(false);+ expect(presenceIdentity(out.ctx.model, "ada")).toEqual({ id: "os:ada", displayName: "ada", color: "", agent: false });+ });++ it("answers the join in the contract's shape and sends the session's events to the joining window only", async () => {+ const { ctx, events } = context();+ const fake = fakeSession();+ const joins: { spaceId: string; identity: PresenceIdentity }[] = [];+ const m = presenceMethods(ctx, async (spaceId, identity) => {+ joins.push({ spaceId, identity });+ return fake.session;+ });+ const sent: { event: string; payload: unknown; to: unknown }[] = [];+ events.subscribe((e, to) => sent.push({ event: e.event, payload: e.payload, to }));+ const win = Object.assign(new EventEmitter(), { webContents: new EventEmitter() });+ const info = await m["presence.join"]!({ spaceId: "local:a" }, { window: win });+ expect(validate(OP_SHAPES["presence.join"], info, SHAPE_DEFS)).toEqual([]);+ expect(info).toMatchObject({ handle: "p1", me: ADA, delayMs: 66, datagrams: true });+ expect(joins.map((j) => j.spaceId)).toEqual(["local:a"]);++ const moved: PresenceEvent = { kind: "cursor_moved", participantId: "p2", cursor: { displayId: "", x: 0.1, y: 0.2, visible: true, pressed: false, shape: "arrow", shapeSource: "probe", atMs: 1, receivedMs: 2 } };+ fake.push(moved);+ await tick();+ expect(sent).toEqual([{ event: "presence.event", payload: { handle: "p1", event: moved }, to: win }]);++ // A timeout is a quiet second, not the end.+ fake.push(Object.assign(new Error("timed out"), { tag: "Timeout" }));+ await tick();+ expect(fake.left()).toBe(0);++ expect(await m["presence.publish"]!({ handle: "p1", x: 0.5, y: 0.25, visible: true, windowId: "w7" }, {})).toBeNull();+ expect(fake.cursors).toEqual([expect.objectContaining({ x: 0.5, y: 0.25, visible: true, windowId: "w7", displayId: "" })]);+ await expect(m["presence.publish"]!({ handle: "p1", x: "left", y: 0, visible: true }, {})).rejects.toMatchObject({ code: "bad_args" });++ // Closing the window leaves.+ win.emit("closed");+ fake.push({ kind: "keep_alive" });+ await tick();+ await tick();+ expect(fake.left()).toBe(1);+ expect(sent).toHaveLength(1);+ await expect(m["presence.publish"]!({ handle: "p1", x: 0, y: 0, visible: false }, {})).rejects.toMatchObject({ code: "not_found" });+ });++ it("leaves when the window loads a new page", async () => {+ const { ctx } = context();+ const fake = fakeSession();+ const m = presenceMethods(ctx, async () => fake.session);+ const win = Object.assign(new EventEmitter(), { webContents: new EventEmitter() });+ await m["presence.join"]!({ spaceId: "local:a" }, { window: win });+ win.webContents.emit("did-navigate");+ fake.push({ kind: "keep_alive" });+ await tick();+ await tick();+ expect(fake.left()).toBe(1);+ });++ it("leaves when asked, and when the stream ends", async () => {+ const { ctx } = context();+ const a = fakeSession();+ const b = fakeSession();+ const sessions = [a.session, b.session];+ const m = presenceMethods(ctx, async () => sessions.shift()!);+ await m["presence.join"]!({ spaceId: "local:a" }, {});+ expect(m["presence.leave"]!({ handle: "p1" }, {})).toBeNull();+ a.push({ kind: "keep_alive" });+ await tick();+ await tick();+ expect(a.left()).toBe(1);++ await m["presence.join"]!({ spaceId: "local:a" }, {});+ b.push(undefined);+ await tick();+ await tick();+ expect(b.left()).toBe(1);+ });++ it("refuses a Space this app doesn't list", async () => {+ const { ctx } = context();+ const join = vi.fn();+ await expect(presenceMethods(ctx, join)["presence.join"]!({ spaceId: "local:gone" }, {})).rejects.toMatchObject({ code: "not_found" });+ expect(join).not.toHaveBeenCalled();+ });++ it("plays two participants circling the picture for screenshots", async () => {+ const s = syntheticPresence(() => 1_000);+ const roster = await s.roster();+ expect(roster.map((m) => m.participant.displayName)).toEqual(["You", "Ada Lovelace", "Claude"]);+ const e = await s.nextEvent(undefined);+ expect(e).toMatchObject({ kind: "cursor_moved", participantId: "ada" });+ expect(e?.cursor?.x).toBeGreaterThan(0);+ expect(e?.cursor?.x).toBeLessThan(1);+ await s.leave();+ expect(await s.nextEvent(undefined)).toBeUndefined();+ });+});diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIVideoSurfaces.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIVideoSurfaces.swiftindex 36771a98ef..0f5f291577 100644--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIVideoSurfaces.swift+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIVideoSurfaces.swift@@ -25,6 +25,9 @@ import WebKit/// alone (the view's `KeyCapture`), a click on the page, or the page's/// "Stop controlling" gives it back. Scrolls go to the page until/// it has the keyboard. The system pointer always stays as it is.+/// - The viewer draws presence over the picture (`PresenceOverlay`, the+/// native window's): the other participants' cursors and yours, published+/// to them. The page draws none here (`presence.*` are Electron's)./// - A slot shows nothing until its first frame; the page shows/// "Connecting…" under it. A stream that can't open or fails tells the/// page (`video.surface` `failed`), which shows its fallback (Open window@@ -110,6 +113,7 @@ final class WebUIVideoSurfaces: NSObject, WKScriptMessageHandler {var layout = VideoSurfaceLayout.nonevar phase = VideoSurfacePhase.connectingvar frames: AnyCancellable?+ var presence: AnyCancellable?var bound = falseinit(_ update: VideoSurfaceUpdate) {id = update.surfaceId@@ -163,7 +167,8 @@ final class WebUIVideoSurfaces: NSObject, WKScriptMessageHandler {viewHeight: webView.bounds.height, flipped: webView.isFlipped)surface.view.interactive = u.interactivesurface.view.input.isInteractive = u.interactive- surface.view.input.showsCursorOverlay = u.interactive+ // The guest's cursor shows only where presence draws none of yours (the native window's rule).+ surface.view.input.showsCursorOverlay = u.interactive && surface.view.presence?.presenceView == nilsurface.view.apply(surface.layout)show(surface)// Keys never stay with a viewer that page UI covers or that left the screen.@@ -172,6 +177,8 @@ final class WebUIVideoSurfaces: NSObject, WKScriptMessageHandler {private func attach(_ u: VideoSurfaceUpdate, in webView: WKWebView) -> Surface {let surface = Surface(u)+ // Only the viewer joins presence (`openStream`), so only it draws it.+ if u.tier == .full { surface.view.addPresence() }surface.view.isHidden = truesurface.view.focusOwner = webViewsurface.view.input.keyboardHome = webView@@ -231,6 +238,14 @@ final class WebUIVideoSurfaces: NSObject, WKScriptMessageHandler {input.onInput = { [weak session] events in session?.send(events) }session.presentation.viewDidAttach()input.onDetach = { [weak session] in session?.presentation.viewDidDetach() }+ if let overlay = surface.view.presence {+ overlay.session = session+ surface.presence = session.objectWillChange.receive(on: DispatchQueue.main).sink { [weak session, weak surface] _ in+ guard let session, let surface else { return }+ surface.view.syncPresence(with: session)+ }+ surface.view.syncPresence(with: session)+ }surface.frames = session.$frame.receive(on: DispatchQueue.main).sink { [weak self, weak session, weak surface] frame inguard let self, let session, let surface else { return }let input = surface.view.input@@ -307,6 +322,8 @@ final class WebUIVideoSurfaces: NSObject, WKScriptMessageHandler {surface.view.input.keyboardReturn.forget()watchClicksWhileDropped()surface.frames?.cancel()+ surface.presence?.cancel()+ surface.view.presence?.stop()surface.view.input.onDetach?()surface.view.input.onDetach = nilsurface.view.input.onInput = nil@@ -409,6 +426,8 @@ final class WebUIVideoSurfaces: NSObject, WKScriptMessageHandler {/// scrolls go to the page until it has the keyboard.final class VideoSurfaceView: NSView {let input = LiveStreamInputView()+ /// The viewer's presence cursors, over the picture (none on tiles).+ private(set) var presence: PresenceOverlayView?var interactive = false/// Where scrolls go while the viewer doesn't have the keyboard.weak var focusOwner: NSView?@@ -431,6 +450,27 @@ final class VideoSurfaceView: NSView {frame = layout.containerinput.frame = layout.videoinput.layer?.cornerRadius = layout.radius+ presence?.frame = layout.video+ }++ /// Adds the presence layer over the picture. It takes no clicks or keys+ /// (its `hitTest` is nil), so input still reaches `input`.+ func addPresence() {+ guard presence == nil else { return }+ let overlay = PresenceOverlayView(frame: input.frame)+ addSubview(overlay, positioned: .above, relativeTo: input)+ presence = overlay+ }++ /// What the presence layer draws, from its session (as the SwiftUI+ /// `PresenceOverlay` reads it on every change).+ func syncPresence(with session: LiveStreamSession) {+ guard let presence else { return }+ presence.surfaceSize = session.surfaceSize+ presence.presenceView = session.presenceView+ presence.windowID = session.presenceWindowID+ presence.isStreamLive = session.status == .streaming+ input.showsCursorOverlay = interactive && session.presenceView == nil}override func hitTest(_ point: NSPoint) -> NSView? {diff --git a/apps/cua-spaces-web/src/bridge/README.md b/apps/cua-spaces-web/src/bridge/README.mdindex 8471bf6f07..f5a664f042 100644--- a/apps/cua-spaces-web/src/bridge/README.md+++ b/apps/cua-spaces-web/src/bridge/README.md@@ -133,7 +133,11 @@ Space's video in the page), `onboarding.get` / `onboarding.complete`login"; the SwiftUI app's is native, so there `session.get` reads it asdone), and `relay.usage` (the account's relay allowance this month,`ops/relay-usage.ts`, for Settings' Relay usage row and the notice above-every page once it is used up; other hosts show neither). Electron reads+every page once it is used up; other hosts show neither), and+`presence.join` / `presence.publish` / `presence.leave` (the other+participants' cursors over the video it draws, `ops/presence.ts`; events+`presence.event` go to the joining window only; the Mac app draws presence+natively). Electron readsdrag regions from the CSS, so the adapter sends none there.### SwiftUI WKWebView: `webkit-protocol.ts`diff --git a/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts b/apps/cua-spaces-web/src/bridge/__tests__/contract-args.tsindex af7ba31b07..002555e275 100644--- a/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts+++ b/apps/cua-spaces-web/src/bridge/__tests__/contract-args.ts@@ -95,6 +95,9 @@ export const DEMO_ARGS: { [K in OpName]: OpArgs<K> } = {"agents.setupDriver": { agents: ["codex"] },"spaces.openStream": { spaceId: SPACE, tier: "tile" },"relay.usage": {},+ "presence.join": { spaceId: SPACE },+ "presence.publish": { handle: "p1", x: 0.5, y: 0.5, visible: true },+ "presence.leave": { handle: "p1" },"about.get": {},"about.set": { channel: "beta" },"about.checkNow": {},@@ -135,4 +138,7 @@ export const DEMO_ARGS: { [K in OpName]: OpArgs<K> } = {/** Operations the demo host refuses on purpose, and why. */export const DEMO_REFUSES: Partial<Record<OpName, string>> = {"spaces.openStream": "the demo host has no video; the page keeps its drawn thumbnail",+ "presence.join": "the demo host has no video to draw cursors over",+ "presence.publish": "the demo host has no video to draw cursors over",+ "presence.leave": "the demo host has no video to draw cursors over",};diff --git a/apps/cua-spaces-web/src/bridge/__tests__/coverage.test.ts b/apps/cua-spaces-web/src/bridge/__tests__/coverage.test.tsindex 0f891b2af9..98b83f54b5 100644--- a/apps/cua-spaces-web/src/bridge/__tests__/coverage.test.ts+++ b/apps/cua-spaces-web/src/bridge/__tests__/coverage.test.ts@@ -15,6 +15,7 @@ import { KEYVAULT_MANAGE_ARGS } from "../ops/keyvault-manage";import { KEYVAULT_SETUP_ARGS } from "../ops/keyvault-setup";import { STREAM_ARGS } from "../ops/stream";import { RELAY_USAGE_ARGS } from "../ops/relay-usage";+import { PRESENCE_ARGS } from "../ops/presence";import type { HostWindow } from "../detect";import { ELECTRON_BRIDGE_CHANNEL } from "../electron-channels";import { OPERATIONS, type OpArgs, type OpName } from "../protocol";@@ -119,6 +120,7 @@ const ARGS: { [K in OpName]: OpArgs<K> } = {"startup.act": { action: "allowAccess" },...STREAM_ARGS,...RELAY_USAGE_ARGS,+ ...PRESENCE_ARGS,};const unsupportedOn = (op: OpName, host: "webkit" | "tauri") =>diff --git a/apps/cua-spaces-web/src/bridge/adapters/demo.ts b/apps/cua-spaces-web/src/bridge/adapters/demo.tsindex 0beef4b2c7..a7141de9b3 100644--- a/apps/cua-spaces-web/src/bridge/adapters/demo.ts+++ b/apps/cua-spaces-web/src/bridge/adapters/demo.ts@@ -39,6 +39,7 @@ import { demoAgentKeysHandlers } from "./demo/agent-keys";import { demoKeyvaultManageHandlers, demoKeyvaultManageState, withDemoCopies, type DemoKeyvaultManageState } from "./demo/keyvault-manage";import { demoKeyvaultSetupHandlers, demoKeyvaultSetupState, demoNoVaultOverview, type DemoKeyvaultSetupState } from "./demo/keyvault-setup";import { unsupportedStreamOps } from "../ops/stream";+import { unsupportedPresenceOps } from "../ops/presence";import { demoTeleportHandlers } from "./demo/teleport";import { createDemoSettings } from "./demo/settings";import { demoAgentSetup, demoPersistentAgents, demoRunRecords, runAt, writtenEvents, type DemoRunRecord } from "./demo-agents";@@ -474,6 +475,7 @@ export function createDemoAdapter(options: DemoOptions = {}): DataAdapter & { re...demoKeyvaultManageHandlers(ctx, overview),...demoStartupHandlers(ctx),...unsupportedStreamOps("demo"),+ ...unsupportedPresenceOps("demo"),};return {diff --git a/apps/cua-spaces-web/src/bridge/adapters/tauri.ts b/apps/cua-spaces-web/src/bridge/adapters/tauri.tsindex 53e1ab42cc..a733574955 100644--- a/apps/cua-spaces-web/src/bridge/adapters/tauri.ts+++ b/apps/cua-spaces-web/src/bridge/adapters/tauri.ts@@ -57,6 +57,7 @@ import { tauriHostSetupOps } from "../ops/host-setup";import { TAURI_SPACE_DETAIL_UNSUPPORTED, tauriSpaceDetailOps } from "../ops/space-detail";import { STREAM_OPERATIONS } from "../ops/stream";import { RELAY_USAGE_OPERATIONS } from "../ops/relay-usage";+import { PRESENCE_OPERATIONS } from "../ops/presence";import { tauriTelemetryOps } from "../ops/telemetry";import { tauriStartupOps } from "../ops/startup";@@ -88,6 +89,7 @@ export const TAURI_UNSUPPORTED: readonly OpName[] = [...TAURI_SPACE_DETAIL_UNSUPPORTED,...STREAM_OPERATIONS,...RELAY_USAGE_OPERATIONS,+ ...PRESENCE_OPERATIONS,];/** `persistent_agent_list`'s snake_case agents, as `PersistentAgent`s (as `src/native/persistent.ts` maps them). */diff --git a/apps/cua-spaces-web/src/bridge/adapters/webkit.ts b/apps/cua-spaces-web/src/bridge/adapters/webkit.tsindex cb1f0b3255..791cae3d1d 100644--- a/apps/cua-spaces-web/src/bridge/adapters/webkit.ts+++ b/apps/cua-spaces-web/src/bridge/adapters/webkit.ts@@ -56,6 +56,7 @@ import { webkitSettingsOps } from "../ops/settings";import { startupFromHost, webkitStartupOps } from "../ops/startup";import { unsupportedStreamOps, type StreamTicket } from "../ops/stream";import { unsupportedRelayUsageOps, type RelayUsage } from "../ops/relay-usage";+import { unsupportedPresenceOps, type PresenceJoinInfo } from "../ops/presence";import type { SpaceRow } from "../contracts/spaces";import {isWebkitResponse,@@ -586,6 +587,14 @@ export function createWebkitAdapter(: unsupportedStreamOps("webkit")),// The relay allowance: Electron reads it; the Mac app not yet....(electron ? { "relay.usage": () => request<RelayUsage | null>("relay.usage") } : unsupportedRelayUsageOps("webkit")),+ // Presence over the page's own video: the Mac app draws it natively.+ ...(electron+ ? {+ "presence.join": (args: OpArgs<"presence.join">) => request<PresenceJoinInfo>("presence.join", { ...args }),+ "presence.publish": (args: OpArgs<"presence.publish">) => request<null>("presence.publish", { ...args }),+ "presence.leave": (args: OpArgs<"presence.leave">) => request<null>("presence.leave", { ...args }),+ }+ : unsupportedPresenceOps("webkit")),};const onEvent = (detail: WebkitEventDetail) => {diff --git a/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json b/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.jsonindex a9591bb349..d862eaff83 100644--- a/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json+++ b/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json@@ -1756,6 +1756,79 @@"machine"]},+ "PresenceCursor": {+ "type": "object",+ "properties": {+ "displayId": {+ "type": "string"+ },+ "windowId": {+ "type": "string"+ },+ "x": {+ "type": "number"+ },+ "y": {+ "type": "number"+ },+ "visible": {+ "type": "boolean"+ },+ "pressed": {+ "type": "boolean"+ },+ "shape": {+ "type": "string"+ },+ "shapeSource": {+ "type": "string"+ },+ "atMs": {+ "type": "number"+ },+ "receivedMs": {+ "type": "number"+ }+ },+ "required": [+ "displayId",+ "x",+ "y",+ "visible",+ "pressed",+ "shape",+ "shapeSource",+ "atMs",+ "receivedMs"+ ]+ },+ "PresenceParticipant": {+ "type": "object",+ "properties": {+ "participantId": {+ "type": "string"+ },+ "principalId": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "color": {+ "type": "string"+ },+ "kind": {+ "type": "string"+ }+ },+ "required": [+ "participantId",+ "principalId",+ "displayName",+ "color",+ "kind"+ ]+ },"RemoteWindow": {"type": "object","properties": {@@ -4212,6 +4285,53 @@"notifications.markAllRead": {"type": "null"},+ "presence.join": {+ "type": "object",+ "properties": {+ "handle": {+ "type": "string"+ },+ "me": {+ "$ref": "#/$defs/PresenceParticipant"+ },+ "members": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "participant": {+ "$ref": "#/$defs/PresenceParticipant"+ },+ "cursor": {+ "$ref": "#/$defs/PresenceCursor"+ }+ },+ "required": [+ "participant"+ ]+ }+ },+ "delayMs": {+ "type": "number"+ },+ "datagrams": {+ "type": "boolean"+ }+ },+ "required": [+ "handle",+ "me",+ "members",+ "delayMs",+ "datagrams"+ ]+ },+ "presence.leave": {+ "type": "null"+ },+ "presence.publish": {+ "type": "null"+ },"relay.usage": {"type": ["object",diff --git a/apps/cua-spaces-web/src/bridge/contracts/shapes.ts b/apps/cua-spaces-web/src/bridge/contracts/shapes.tsindex 864fb3c8eb..2a50c8ac62 100644--- a/apps/cua-spaces-web/src/bridge/contracts/shapes.ts+++ b/apps/cua-spaces-web/src/bridge/contracts/shapes.ts@@ -59,6 +59,7 @@ import type { AgentSetupOutcome, DriveGrantInput, DriveMountInput, DriveRequestIimport type { AgentKeysReport } from "../ops/agent-keys";import type { SentFileInfo, SpaceThumbnail, SpaceUsage, SpaceWindows } from "../ops/space-detail";import type { RelayUsage } from "../ops/relay-usage";+import type { PresenceCursorWire, PresenceJoinInfo, PresenceParticipantWire } from "../ops/presence";import type { StartupState } from "../ops/startup";import type { StreamTicket } from "../ops/stream";import type { GlobalShortcut, HostSettings, HostSignIn, OpName, SessionSnapshot, SettingsSnapshot, SettingsValues } from "../protocol";@@ -588,6 +589,25 @@ const AgentOpenFileShape = ref(}),);const shares = list(ShareShape);+const PresenceParticipantShape = ref(+ "PresenceParticipant",+ obj<PresenceParticipantWire>()({ participantId: str, principalId: str, displayName: str, color: str, kind: str }),+);+const PresenceCursorShape = ref(+ "PresenceCursor",+ obj<PresenceCursorWire>()({+ displayId: str,+ windowId: opt(str),+ x: num,+ y: num,+ visible: bool,+ pressed: bool,+ shape: str,+ shapeSource: str,+ atMs: num,+ receivedMs: num,+ }),+);export const OP_SHAPES: Record<OpName, Schema> = {"spaces.list": list(SpaceRowShape),@@ -756,6 +776,15 @@ export const OP_SHAPES: Record<OpName, Schema> = {upgradeUrl: nullable(str),}),),+ "presence.join": obj<PresenceJoinInfo>()({+ handle: str,+ me: PresenceParticipantShape,+ members: list(object({ participant: PresenceParticipantShape, cursor: opt(PresenceCursorShape) })),+ delayMs: num,+ datagrams: bool,+ }),+ "presence.publish": nul,+ "presence.leave": nul,"about.get": AboutShape,"about.set": AboutShape,diff --git a/apps/cua-spaces-web/src/bridge/coverage.ts b/apps/cua-spaces-web/src/bridge/coverage.tsindex 0ae903e5f4..a0bf221ac3 100644--- a/apps/cua-spaces-web/src/bridge/coverage.ts+++ b/apps/cua-spaces-web/src/bridge/coverage.ts@@ -40,6 +40,7 @@ import { HOST_SETUP_COVERAGE } from "./ops/host-setup";import { SPACE_DETAIL_COVERAGE } from "./ops/space-detail";import { STREAM_COVERAGE } from "./ops/stream";import { RELAY_USAGE_COVERAGE } from "./ops/relay-usage";+import { PRESENCE_COVERAGE } from "./ops/presence";import { TELEMETRY_COVERAGE } from "./ops/telemetry";import { STARTUP_COVERAGE } from "./ops/startup";@@ -159,6 +160,7 @@ export const HOST_COVERAGE = {...STARTUP_COVERAGE,...STREAM_COVERAGE,...RELAY_USAGE_COVERAGE,+ ...PRESENCE_COVERAGE,} as const satisfies Record<OpName, OpCoverage>;/**diff --git a/apps/cua-spaces-web/src/bridge/ops/presence.ts b/apps/cua-spaces-web/src/bridge/ops/presence.tsnew file mode 100644index 0000000000..caae276b08--- /dev/null+++ b/apps/cua-spaces-web/src/bridge/ops/presence.ts@@ -0,0 +1,106 @@+// SPDX-License-Identifier: FSL-1.1-MIT+// Copyright (c) 2026 Cua AI, Inc.++/**+ * Presence over a live stream the page draws (WebCodecs): the other+ * participants' cursors, and yours published to them. One `PresenceService`+ * session per Space per window, joined through the cua SDK in the host+ * (`Space.joinPresence`, as the SwiftUI app's `LiveStreamSession` and the+ * Tauri app's `presence_join`). The page folds the events into the SDK's+ * `PresenceView` and draws with the shared `PresenceLayer`+ * (`components/video/presence.ts`).+ *+ * | Operation | Electron | SwiftUI | Tauri |+ * |---|---|---|---|+ * | `presence.join {spaceId}` | the host method `presence.join` (`src/bridge/presence.ts`) | unsupported: its native viewer draws presence (`PresenceOverlay`) | unsupported: its viewer windows join with `presence_join` |+ * | `presence.publish {handle, x, y, visible, windowId?}` | `presence.publish` | unsupported | unsupported |+ * | `presence.leave {handle}` | `presence.leave` | unsupported | unsupported |+ *+ * Events arrive on the joining window only, as `presence.event`+ * `{handle, event}` (`event` in the TS SDK's `PresenceEvent` shape).+ */++import { UnsupportedOperationError, type BridgeMode } from "../adapter";+import type { OpCoverage } from "../coverage";++/** A participant (the TS SDK's `PresenceParticipant`). */+export interface PresenceParticipantWire {+ participantId: string;+ principalId: string;+ displayName: string;+ color: string;+ kind: string;+}++/** A cursor (the TS SDK's `PresenceCursor`). */+export interface PresenceCursorWire {+ displayId: string;+ windowId?: string;+ x: number;+ y: number;+ visible: boolean;+ pressed: boolean;+ shape: string;+ shapeSource: string;+ atMs: number;+ receivedMs: number;+}++/** What `presence.join` answers. */+export interface PresenceJoinInfo {+ /** Names the session in `publish`, `leave` and its events. */+ handle: string;+ me: PresenceParticipantWire;+ members: { participant: PresenceParticipantWire; cursor?: PresenceCursorWire }[];+ /** Render delay for remote cursors on this transport (ms). */+ delayMs: number;+ datagrams: boolean;+}++/** The local pointer, normalized to the streamed surface. */+export interface PresencePointerArgs {+ handle: string;+ x: number;+ y: number;+ visible: boolean;+ windowId?: string;+}++/** The pushed event's name and payload. */+export const PRESENCE_EVENT = "presence.event";++export interface PresenceOps {+ "presence.join": { args: { spaceId: string }; result: PresenceJoinInfo };+ "presence.publish": { args: PresencePointerArgs; result: null };+ "presence.leave": { args: { handle: string }; result: null };+}++export const PRESENCE_OPERATIONS = ["presence.join", "presence.publish", "presence.leave"] as const satisfies readonly (keyof PresenceOps)[];++const UNSUPPORTED = {+ webkit: "the Mac app draws presence natively over its own video (PresenceOverlay)",+ tauri: "the Tauri app's viewer windows join presence themselves (presence_join)",+};++export const PRESENCE_COVERAGE = {+ "presence.join": { webkit: { methods: [] }, electron: { methods: ["presence.join"] }, tauri: [], unsupported: UNSUPPORTED },+ "presence.publish": { webkit: { methods: [] }, electron: { methods: ["presence.publish"] }, tauri: [], unsupported: UNSUPPORTED },+ "presence.leave": { webkit: { methods: [] }, electron: { methods: ["presence.leave"] }, tauri: [], unsupported: UNSUPPORTED },+} as const satisfies Record<keyof PresenceOps, OpCoverage>;++/** Hosts where the page draws no presence. */+export function unsupportedPresenceOps(mode: BridgeMode) {+ const no = (op: keyof PresenceOps) => () => Promise.reject(new UnsupportedOperationError(mode, op));+ return {+ "presence.join": no("presence.join") as () => Promise<PresenceJoinInfo>,+ "presence.publish": no("presence.publish") as () => Promise<null>,+ "presence.leave": no("presence.leave") as () => Promise<null>,+ };+}++/** Arguments that take each down its usual path (coverage tests). */+export const PRESENCE_ARGS = {+ "presence.join": { spaceId: "local:design-review" },+ "presence.publish": { handle: "p1", x: 0.5, y: 0.5, visible: true },+ "presence.leave": { handle: "p1" },+};diff --git a/apps/cua-spaces-web/src/bridge/protocol.ts b/apps/cua-spaces-web/src/bridge/protocol.tsindex 611f23f31e..6332db9377 100644--- a/apps/cua-spaces-web/src/bridge/protocol.ts+++ b/apps/cua-spaces-web/src/bridge/protocol.ts@@ -45,6 +45,7 @@ import type { HostSetupOps } from "./ops/host-setup";import type { SpaceDetailOps } from "./ops/space-detail";import { STREAM_OPERATIONS, type StreamOps } from "./ops/stream";import { RELAY_USAGE_OPERATIONS, type RelayUsageOps } from "./ops/relay-usage";+import { PRESENCE_OPERATIONS, type PresenceOps } from "./ops/presence";import type { TelemetryOps } from "./ops/telemetry";import { STARTUP_EVENTS, STARTUP_OPERATIONS, type StartupHostEvent, type StartupOps } from "./ops/startup";@@ -179,7 +180,8 @@ export interface HostOperationsHostSetupOps,StartupOps,StreamOps,- RelayUsageOps {+ RelayUsageOps,+ PresenceOps {"spaces.list": { args: Record<string, never>; result: SpaceRow[] };/** `os`: the plan's OS, for a host that draws its own pending row (the SwiftUI app's notch). */"spaces.create": { args: { config: SpaceCreateConfig; pendingId: string; os?: SpaceOs }; result: SpaceRow };@@ -281,6 +283,7 @@ export const OPERATIONS = [...VOLUME_OPERATIONS,...STREAM_OPERATIONS,...RELAY_USAGE_OPERATIONS,+ ...PRESENCE_OPERATIONS,...SETTINGS_OPERATIONS,...NOTIFICATIONS_OPERATIONS,"telemetry.track",diff --git a/apps/cua-spaces-web/src/bridge/webkit-protocol.ts b/apps/cua-spaces-web/src/bridge/webkit-protocol.tsindex bfe042e944..c87b27ec93 100644--- a/apps/cua-spaces-web/src/bridge/webkit-protocol.ts+++ b/apps/cua-spaces-web/src/bridge/webkit-protocol.ts@@ -153,8 +153,9 @@ export type WebkitMethod = (typeof WEBKIT_METHODS)[number];* (`ops/stream.ts`), and its first run is this page's (`onboarding.get`,* `onboarding.complete`); the Mac app draws video and its first run* natively. It also reads the account's relay allowance- * (`relay.usage`, `ops/relay-usage.ts`). */-export const ELECTRON_HOST_METHODS = ["onboarding.get", "onboarding.complete", "spaces.openStream", "relay.usage"] as const;+ * (`relay.usage`, `ops/relay-usage.ts`) and joins presence for the video+ * the page draws (`presence.*`, `ops/presence.ts`). */+export const ELECTRON_HOST_METHODS = ["onboarding.get", "onboarding.complete", "spaces.openStream", "relay.usage", "presence.join", "presence.publish", "presence.leave"] as const;/** `onboarding.get` and `onboarding.complete`'s answer: whether the first run finished, and as what. */export interface WkOnboarding {diff --git a/apps/cua-spaces-web/src/components/pip/pip-view.test.tsx b/apps/cua-spaces-web/src/components/pip/pip-view.test.tsxindex e04965edb7..cae18b15bc 100644--- a/apps/cua-spaces-web/src/components/pip/pip-view.test.tsx+++ b/apps/cua-spaces-web/src/components/pip/pip-view.test.tsx@@ -30,6 +30,8 @@ function electron(platform = "darwin") {const desktop: CuaDesktopBridge = {invoke: async (_channel, request) => {const r = request as { id: string } & Call;+ // Presence (the panel joins it): none here; components/video/presence.test.ts covers it.+ if (r.method.startsWith("presence.")) return { id: r.id, ok: false, error: { message: "no presence", code: "unsupported" } };calls.push({ method: r.method, args: r.args });return { id: r.id, ok: true, result: r.method === "spaces.openStream" ? { wsUrl: "ws://127.0.0.1:1/m", expiresAt: null } : null };},diff --git a/apps/cua-spaces-web/src/components/video/presence.test.ts b/apps/cua-spaces-web/src/components/video/presence.test.tsnew file mode 100644index 0000000000..ae7ce7943b--- /dev/null+++ b/apps/cua-spaces-web/src/components/video/presence.test.ts@@ -0,0 +1,174 @@+// SPDX-License-Identifier: FSL-1.1-MIT+// Copyright (c) 2026 Cua AI, Inc.++import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++import type { CuaDesktopBridge } from "@/bridge/detect";+import type { PresenceJoinInfo } from "@/bridge/ops/presence";++import { attachPresence, resetPresenceSessions } from "./presence";+import { WebCodecsSlots, type PresenceFactory } from "./webcodecs-slots";++const ME = { participantId: "p1", principalId: "user:ada", displayName: "Ada", color: "#e6194b", kind: "human" };+const BOB = { participantId: "p2", principalId: "user:bob", displayName: "Bob", color: "#4363d8", kind: "human" };++function cursor(x: number, y: number, windowId?: string) {+ return { displayId: "", ...(windowId ? { windowId } : {}), x, y, visible: true, pressed: false, shape: "arrow", shapeSource: "unspecified", atMs: 0, receivedMs: 0 };+}++/** A shell that joins `spaceId` as Ada with Bob already there, and pushes events to the page. */+function fakeShell(join: Partial<PresenceJoinInfo> = {}) {+ const calls: { method: string; args: Record<string, unknown> }[] = [];+ const listeners = new Set<(payload: unknown) => void>();+ const desktop: CuaDesktopBridge = {+ invoke: async (_channel, request) => {+ const r = request as { id: string; method: string; args: Record<string, unknown> };+ calls.push({ method: r.method, args: r.args });+ if (r.method === "presence.join") {+ const info: PresenceJoinInfo = { handle: "h1", me: ME, members: [{ participant: BOB, cursor: cursor(0.5, 0.5) }], delayMs: 0, datagrams: false, ...join };+ return { id: r.id, ok: true, result: info };+ }+ return { id: r.id, ok: true, result: null };+ },+ on: (_channel, listener) => {+ listeners.add(listener);+ return () => listeners.delete(listener);+ },+ };+ const push = (handle: string, event: unknown) => listeners.forEach((l) => l({ event: "presence.event", payload: { handle, event } }));+ return { desktop, calls, push, listeners };+}++function surface() {+ const host = document.createElement("div");+ const canvas = document.createElement("canvas");+ host.append(canvas);+ document.body.append(host);+ return { host, canvas };+}++const flush = () => new Promise((r) => setTimeout(r, 0));+const nextFrame = () => new Promise((r) => requestAnimationFrame(() => r(null)));++beforeEach(() => resetPresenceSessions());+afterEach(() => {+ document.body.innerHTML = "";+ vi.restoreAllMocks();+});++describe("presence over the page's video", () => {+ it("draws the other participants with their name and color, only while the stream is live", async () => {+ const shell = fakeShell();+ const { host, canvas } = surface();+ const p = attachPresence(shell.desktop, canvas, host, { spaceId: "local:a", interactive: true });+ await flush();+ await nextFrame();+ const layer = host.querySelector<HTMLElement>(".presence-layer");+ expect(layer?.style.display).toBe("none");+ const bob = host.querySelector<HTMLElement>('.presence-cursor[data-participant="p2"]');+ expect(bob?.textContent).toBe("Bob");+ expect(bob?.innerHTML).toContain("#4363d8");+ // You are never drawn as someone else.+ expect(host.querySelector('.presence-cursor[data-participant="p1"]:not([data-me])')).toBeNull();++ p.setLive(true);+ expect(layer?.style.display).toBe("");+ p.setLive(false);+ expect(layer?.style.display).toBe("none");+ p.detach();+ expect(host.querySelector(".presence-layer")).toBeNull();+ });++ it("folds the host's events for its own session only, and draws a window's cursors on that window only", async () => {+ const shell = fakeShell({ members: [] });+ const desk = surface();+ const win = surface();+ const a = attachPresence(shell.desktop, desk.canvas, desk.host, { spaceId: "local:a", interactive: true });+ const b = attachPresence(shell.desktop, win.canvas, win.host, { spaceId: "local:a", windowId: "w7", interactive: true });+ await flush();+ // One participant per Space per page, however many slots show it.+ expect(shell.calls.filter((c) => c.method === "presence.join")).toHaveLength(1);+ shell.push("h1", { kind: "joined", participant: BOB });+ shell.push("h1", { kind: "cursor_moved", participantId: "p2", cursor: cursor(0.25, 0.25, "w7") });+ shell.push("other", { kind: "joined", participant: { ...BOB, participantId: "p3", displayName: "Eve" } });+ await nextFrame();+ expect(win.host.querySelector('.presence-cursor[data-participant="p2"]')).not.toBeNull();+ expect(desk.host.querySelector('.presence-cursor[data-participant="p2"]')).toBeNull();+ expect(win.host.querySelector('.presence-cursor[data-participant="p3"]')).toBeNull();++ a.detach();+ await flush();+ expect(shell.calls.some((c) => c.method === "presence.leave")).toBe(false);+ b.detach();+ await flush();+ expect(shell.calls.filter((c) => c.method === "presence.leave")).toEqual([{ method: "presence.leave", args: { handle: "h1" } }]);+ expect(shell.listeners.size).toBe(0);+ });++ it("publishes your pointer over the picture, and a hide when it leaves", async () => {+ const shell = fakeShell({ members: [] });+ const { host, canvas } = surface();+ vi.spyOn(canvas, "getBoundingClientRect").mockReturnValue({ left: 0, top: 0, width: 200, height: 100, right: 200, bottom: 100, x: 0, y: 0, toJSON: () => ({}) });+ const p = attachPresence(shell.desktop, canvas, host, { spaceId: "local:a", interactive: true });+ await flush();+ p.setLive(true);+ canvas.dispatchEvent(Object.assign(new Event("pointermove"), { clientX: 50, clientY: 25 }));+ canvas.dispatchEvent(new Event("pointerleave"));+ await flush();+ const published = shell.calls.filter((c) => c.method === "presence.publish").map((c) => c.args);+ expect(published).toEqual([+ { handle: "h1", x: 0.25, y: 0.25, visible: true },+ { handle: "h1", x: 0, y: 0, visible: false },+ ]);+ p.detach();+ });++ it("leaves the video alone when the Space has no presence", async () => {+ const shell = fakeShell();+ shell.desktop.invoke = async (_c, request) => ({ id: (request as { id: string }).id, ok: false, error: { code: "unsupported", message: "no presence" } });+ const { host, canvas } = surface();+ const p = attachPresence(shell.desktop, canvas, host, { spaceId: "local:a", interactive: true });+ await flush();+ p.setLive(true);+ expect(host.querySelector(".presence-layer")).toBeNull();+ p.detach();+ });+});++describe("the WebCodecs slots", () => {+ it("draw presence on viewer slots only, live with the stream, and take it down with the slot", async () => {+ const attached: { options: Parameters<PresenceFactory>[3]; live: boolean[]; detached: boolean }[] = [];+ const factory: PresenceFactory = (_d, _c, _h, options) => {+ const rec = { options, live: [] as boolean[], detached: false };+ attached.push(rec);+ return { setLive: (l) => rec.live.push(l), detach: () => (rec.detached = true) };+ };+ const desktop: CuaDesktopBridge = {+ invoke: async (_c, request) => ({ id: (request as { id: string }).id, ok: true, result: { wsUrl: "ws://127.0.0.1:1/x", expiresAt: null } }),+ platform: "linux",+ };+ let onFrame: ((w: number, h: number) => void) | undefined;+ const slots = new WebCodecsSlots(+ desktop,+ document,+ (o) => {+ onFrame = o.onFrame;+ return { start() {}, stop() {} };+ },+ null,+ factory,+ );+ const el = document.createElement("div");+ document.body.append(el);+ const stopTile = slots.register(el, { spaceId: "local:a", tier: "tile", interactive: false, radius: 8 }, () => {});+ expect(attached).toHaveLength(0);+ stopTile();+ const stop = slots.register(el, { spaceId: "local:a", tier: "full", interactive: true, radius: 0, windowId: "w7", epoch: 2 }, () => {});+ expect(attached.map((a) => a.options)).toEqual([{ spaceId: "local:a", windowId: "w7", interactive: true }]);+ await flush();+ onFrame?.(1280, 720);+ expect(attached[0]?.live.at(-1)).toBe(true);+ stop();+ expect(attached[0]?.detached).toBe(true);+ });+});diff --git a/apps/cua-spaces-web/src/components/video/presence.ts b/apps/cua-spaces-web/src/components/video/presence.tsnew file mode 100644index 0000000000..a1d797cda1--- /dev/null+++ b/apps/cua-spaces-web/src/components/video/presence.ts@@ -0,0 +1,190 @@+// SPDX-License-Identifier: FSL-1.1-MIT+// Copyright (c) 2026 Cua AI, Inc.++/**+ * Presence cursors over the video the page draws (the Electron shell's+ * WebCodecs slots): the other participants' cursors where the SDK's+ * `PresenceView` puts them, and yours at the local pointer, published to+ * them. The drawing is the shared `PresenceLayer` (the cua-spacesd HTML5+ * viewer's and the Tauri app's): the SDK's cursor art, presence colors and+ * name pills, placed over the letterboxed picture as the SwiftUI app's+ * `PresenceOverlay` does.+ *+ * One session per Space per page, shared by every slot showing it (the Space+ * page's inline desktop and nothing else, or one PiP window), so one person+ * is one participant however many slots they have open. Reference-counted:+ * the last release leaves. The host joins through the cua SDK+ * (`presence.join`, `bridge/ops/presence.ts`) and pushes the session's events+ * to this window only.+ */++import { HEARTBEAT_INTERVAL_MS, PresenceView, type PresenceEvent } from "@trycua/cua/spaces/presence";++import { PresenceLayer } from "../../../../../libs/cua/crates/cua-spacesd-html5/web/src/core/presenceLayer";+import type { CuaDesktopBridge } from "@/bridge/detect";+import { ELECTRON_BRIDGE_CHANNEL, ELECTRON_EVENT_CHANNEL } from "@/bridge/electron-channels";+import { PRESENCE_EVENT, type PresenceJoinInfo, type PresencePointerArgs } from "@/bridge/ops/presence";+import { isWebkitResponse } from "@/bridge/webkit-protocol";++/** How often staleness is checked (a timer, not rAF, so a hidden page still expires cursors). */+export const EXPIRE_EVERY_MS = 1_000;++let requestSeq = 0;++async function call<T>(desktop: CuaDesktopBridge, method: string, args: Record<string, unknown>): Promise<T> {+ const reply = await desktop.invoke(ELECTRON_BRIDGE_CHANNEL, { id: `presence-${++requestSeq}`, method, args });+ if (!isWebkitResponse(reply)) throw new Error("the shell answered without an envelope");+ if (!reply.ok) throw new Error(reply.error?.message ?? `${method} failed`);+ return reply.result as T;+}++/** One joined session: the SDK's model, fed by the host's events. */+export class SharedPresence {+ readonly view: PresenceView;+ private readonly stops: (() => void)[] = [];++ constructor(+ private readonly desktop: CuaDesktopBridge,+ readonly info: PresenceJoinInfo,+ private readonly now: () => number,+ ) {+ this.view = PresenceView.from(info.me, info.members, info.delayMs, now());+ this.view.setHeartbeatIntervalMs(HEARTBEAT_INTERVAL_MS);+ }++ start(): void {+ const off = this.desktop.on?.(ELECTRON_EVENT_CHANNEL, (raw) => {+ const e = raw as { event?: unknown; payload?: { handle?: unknown; event?: PresenceEvent } } | null;+ if (e?.event !== PRESENCE_EVENT || e.payload?.handle !== this.info.handle || !e.payload.event) return;+ this.view.apply(e.payload.event, this.now());+ });+ if (off) this.stops.push(off);+ const timer = setInterval(() => this.view.expire(this.now()), EXPIRE_EVERY_MS);+ this.stops.push(() => clearInterval(timer));+ }++ get me(): string {+ return this.info.me.participantId;+ }++ /** Your color, as the Space assigned it. */+ get myColor(): string {+ return this.view.participant(this.me)?.color || this.info.me.color;+ }++ publish(pointer: Omit<PresencePointerArgs, "handle">): void {+ void call(this.desktop, "presence.publish", { handle: this.info.handle, ...pointer }).catch(() => {});+ }++ stop(): void {+ for (const s of this.stops.splice(0)) s();+ void call(this.desktop, "presence.leave", { handle: this.info.handle }).catch(() => {});+ }+}++interface Entry {+ session: Promise<SharedPresence | null>;+ refs: number;+}++const sessions = new Map<string, Entry>();++/**+ * Joins (or reuses) the page's session for `spaceId`. Resolves to null when+ * the Space has no presence (or the host can't join): the video still+ * plays, with no cursors. Call the returned release exactly once.+ */+export function acquirePresence(+ desktop: CuaDesktopBridge,+ spaceId: string,+ now: () => number = Date.now,+): { session: Promise<SharedPresence | null>; release: () => void } {+ let entry = sessions.get(spaceId);+ if (!entry) {+ const session = call<PresenceJoinInfo>(desktop, "presence.join", { spaceId })+ .then((info) => {+ const s = new SharedPresence(desktop, info, now);+ s.start();+ return s;+ })+ .catch(() => null);+ entry = { session, refs: 0 };+ sessions.set(spaceId, entry);+ }+ entry.refs += 1;+ const held = entry;+ let released = false;+ return {+ session: held.session,+ release: () => {+ if (released) return;+ released = true;+ held.refs -= 1;+ if (held.refs > 0) return;+ if (sessions.get(spaceId) === held) sessions.delete(spaceId);+ void held.session.then((s) => s?.stop());+ },+ };+}++/** Tests: forget every session. */+export function resetPresenceSessions(): void {+ sessions.clear();+}++export interface PresenceAttachment {+ /** The stream under it is live (cursors show) or not (nothing shows, the system cursor stays). */+ setLive(live: boolean): void;+ /** Takes the cursors down and releases the session. */+ detach(): void;+}++/**+ * Draws presence over one slot's canvas (its parent hosts the layer) for the+ * slot's Space and target (`windowId`: one window; unset: the desktop).+ * Nothing shows until `setLive(true)`: no cursor floats over a cover that+ * says "Connecting…" or "Failed".+ */+export function attachPresence(+ desktop: CuaDesktopBridge,+ canvas: HTMLCanvasElement,+ host: HTMLElement,+ options: { spaceId: string; windowId?: string; interactive: boolean },+ now: () => number = Date.now,+): PresenceAttachment {+ const { session, release } = acquirePresence(desktop, options.spaceId, now);+ let live = false;+ let layer: PresenceLayer | null = null;+ let detached = false;+ const show = () => {+ if (layer) layer.root.style.display = live ? "" : "none";+ };+ void session.then((s) => {+ if (detached || !s) return;+ layer = new PresenceLayer({+ surface: canvas,+ host,+ view: () => s.view,+ me: () => ({ id: s.me, color: s.myColor }),+ ...(options.windowId ? { windowId: options.windowId } : {}),+ interactive: options.interactive,+ live: () => live,+ onPointer: (p) => s.publish(p),+ now,+ });+ show();+ });+ return {+ setLive(next) {+ live = next;+ show();+ },+ detach() {+ if (detached) return;+ detached = true;+ layer?.destroy();+ layer = null;+ release();+ },+ };+}diff --git a/apps/cua-spaces-web/src/components/video/webcodecs-slots.test.tsx b/apps/cua-spaces-web/src/components/video/webcodecs-slots.test.tsxindex eac8d3f397..632aa574a2 100644--- a/apps/cua-spaces-web/src/components/video/webcodecs-slots.test.tsx+++ b/apps/cua-spaces-web/src/components/video/webcodecs-slots.test.tsx@@ -44,6 +44,8 @@ function fakeDesktop(reply: (args: { spaceId: string; tier: string }) => Reply =const desktop: CuaDesktopBridge = {invoke: async (channel: string, request?: unknown) => {const r = request as Request;+ // Presence (the viewer joins it): none here; presence.test.ts covers it.+ if (r.method.startsWith("presence.")) return { id: r.id, ok: false, error: { message: "no presence", code: "unsupported" } };calls.push({ channel, method: r.method, args: r.args });return { id: r.id, ...reply(r.args) };},@@ -454,7 +456,8 @@ describe("<StreamSurface> in the Electron shell", () => {const calls: string[] = [];electron({invoke: (_channel: string, request?: unknown) => {- const r = request as { id: string; args: { spaceId: string } };+ const r = request as { id: string; method: string; args: { spaceId: string } };+ if (r.method !== "spaces.openStream") return Promise.resolve({ id: r.id, ok: false, error: { message: "no presence", code: "unsupported" } });calls.push(r.args.spaceId);return new Promise((resolve) => pending.push((reply) => resolve({ id: r.id, ...reply })));},diff --git a/apps/cua-spaces-web/src/components/video/webcodecs-slots.ts b/apps/cua-spaces-web/src/components/video/webcodecs-slots.tsindex 38cffeb8ee..4a095dbd70 100644--- a/apps/cua-spaces-web/src/components/video/webcodecs-slots.ts+++ b/apps/cua-spaces-web/src/components/video/webcodecs-slots.ts@@ -37,6 +37,10 @@* instead of the desktop (`windowId`, picture in picture): its input goes* in the background, and the session opens again with activation when the* Space says that window needs it (`would_require_activation`).+ *+ * The viewer slots (`full`: the Space page's desktop, a PiP window) draw+ * presence over the picture (`presence.ts`): the other participants'+ * cursors and yours, shown only while the slot is live.*/import { MediaSession, type MediaSessionOptions, type MediaTicket } from "../../../../../libs/cua/crates/cua-spacesd-html5/web/src/core/mediaSession";@@ -47,6 +51,7 @@ import type { StreamTarget, StreamTicket } from "@/bridge/ops/stream";import type { SlotOptions, SlotStatus } from "@/lib/video-slots";import { KeyCapture } from "./key-capture";+import { attachPresence, type PresenceAttachment } from "./presence";import { VideoStats } from "./video-stats";import { NO_VIDEO_HERE, webCodecsHost } from "./webcodecs-host";@@ -91,6 +96,14 @@ export function needsActivation(ack: Record<string, unknown>): boolean {}export type SessionFactory = (options: MediaSessionOptions) => SessionLike;+/** Draws presence over a viewer slot's canvas (`attachPresence`; tests replace it). */+export type PresenceFactory = (+ desktop: CuaDesktopBridge,+ canvas: HTMLCanvasElement,+ host: HTMLElement,+ options: { spaceId: string; windowId?: string; interactive: boolean },+) => PresenceAttachment;+interface Slot {id: string;el: HTMLElement;@@ -103,6 +116,8 @@ interface Slot {generation: number;/** A window's session that opens with activation (the Space asked for it). */activate: boolean;+ /** Presence over a viewer slot (none on tiles). */+ presence: PresenceAttachment | null;detach: (() => void)[];}@@ -130,6 +145,7 @@ export class WebCodecsSlots {private readonly doc: Document = document,private readonly createSession: SessionFactory = (o) => new MediaSession(o),stats?: VideoStats | null,+ private readonly createPresence: PresenceFactory = attachPresence,) {this.stats = stats !== undefined ? stats : desktop.videoStats ? new VideoStats() : null;}@@ -150,7 +166,14 @@ export class WebCodecsSlots {outline: "none",});el.append(canvas);- const slot: Slot = { id, el, options, listener, canvas, session: null, status: { phase: "connecting", focused: false }, generation: 0, activate: false, detach: [] };+ const slot: Slot = { id, el, options, listener, canvas, session: null, status: { phase: "connecting", focused: false }, generation: 0, activate: false, presence: null, detach: [] };+ if (options.tier === "full") {+ slot.presence = this.createPresence(this.desktop, canvas, el, {+ spaceId: options.spaceId,+ ...(options.windowId ? { windowId: options.windowId } : {}),+ interactive: options.interactive,+ });+ }this.stats?.open(id, options.spaceId, options.tier);this.slots.set(id, slot);if (this.slots.size === 1) this.doc.addEventListener("visibilitychange", this.onVisibility);@@ -160,6 +183,7 @@ export class WebCodecsSlots {if (!this.slots.delete(id)) return;this.close(slot);for (const off of slot.detach.splice(0)) off();+ slot.presence?.detach();canvas.remove();this.stats?.close(id);if (this.slots.size === 0) this.doc.removeEventListener("visibilitychange", this.onVisibility);@@ -187,6 +211,7 @@ export class WebCodecsSlots {}if (next.phase === slot.status.phase && next.focused === slot.status.focused && next.reason === slot.status.reason && next.opening === slot.status.opening) return;slot.status = next;+ slot.presence?.setLive(next.phase === "live");slot.listener(next);}diff --git a/apps/cua-spaces-web/tsconfig.json b/apps/cua-spaces-web/tsconfig.jsonindex 929384fd0e..f5ecb375d6 100644--- a/apps/cua-spaces-web/tsconfig.json+++ b/apps/cua-spaces-web/tsconfig.json@@ -18,7 +18,8 @@"noEmit": true,"types": ["vite/client", "node"],"paths": {- "@/*": ["./src/*"]+ "@/*": ["./src/*"],+ "@trycua/cua/spaces/presence": ["../../libs/cua/typescript/src/spaces/presence.ts"]}},"include": ["src", "e2e", "vite.config.ts", "scripts"]diff --git a/apps/cua-spaces-web/vite.config.ts b/apps/cua-spaces-web/vite.config.tsindex 00aa038d29..b723406562 100644--- a/apps/cua-spaces-web/vite.config.ts+++ b/apps/cua-spaces-web/vite.config.ts@@ -10,6 +10,9 @@ import react, { reactCompilerPreset } from "@vitejs/plugin-react";import { defineConfig } from "vitest/config";const src = (path: string) => fileURLToPath(new URL(`./src/${path}`, import.meta.url));+// The cua SDK's browser-safe presence model and cursor art, from source, as+// the shared presence layer (libs/cua/crates/cua-spacesd-html5) imports it.+const presence = fileURLToPath(new URL("../../libs/cua/typescript/src/spaces/presence.ts", import.meta.url));export default defineConfig({plugins: [@@ -35,6 +38,7 @@ export default defineConfig({resolve: {alias: [{ find: /^@\//, replacement: `${src("")}` },+ { find: /^@trycua\/cua\/spaces\/presence$/, replacement: presence },],},// Scan every source file up front: routes are code-split, so otherwise their