Preview exposure
DesktopWhen Screenplay runs on a machine you control, every chat’s preview runs there
too, and a browser has to reach it. Preview exposure decides how. It’s a
small interface in apps/app/lib/preview-exposure/ with two built-ins:
In the Mac app, it’s how viewers
reach the app and its previews, and only while Sharing is on: the viewer
listener is exposed when Sharing turns on, and a viewer’s frame asks for its
port’s origin when it opens. Turning Sharing off releases every port it
exposed. Your own frames always load at http://localhost:{port}.
Headless doesn’t use it: the host’s frames load
through portless at http://screenplay-<port>.localhost:1355, over the host’s
SSH tunnel.
It covers only what a browser loads: each chat’s bridge proxy (the page a
frame shows) and its frame stream. The preview itself always listens on
127.0.0.1. The server never loads a browser URL either: its own checks,
thumbnails and the agent’s page reads go to each preview’s 127.0.0.1 address,
so they work whatever URL your browser uses. Hosted sandboxes don’t use it;
each Vercel Sandbox has its own public URL.
The interface
interface PreviewExposure {
// Make a port reachable, once its listener is started. Idempotent.
expose(port: number): Promise<{ browserOrigin: string }>
// Undo expose when the chat is deleted. Never throws.
release(port: number): Promise<void>
}Built-ins
loopback: loopbackExposure()
Each port loads at http://localhost:{port}. The default everywhere but the
Mac app.
tailscale: tailscaleExposure()
Shares each port with everyone on your tailnet. Exposing a port runs
tailscale serve --bg --https=<port> http://127.0.0.1:<port>, and the port
loads at https://<mac>.<tailnet>.ts.net:<port>; releasing it runs
tailscale serve --https=<port> off. --bg keeps each port served after a
restart until it’s released.
It needs Tailscale installed, signed in and connected, with MagicDNS and HTTPS Certificates turned on for your tailnet (the DNS page of the Tailscale admin console). When any of those is missing, the preview shows an error saying which.
Picking one
selectPreviewExposure() in apps/app/lib/preview-exposure/index.ts picks
one: tailscale in the Mac app, loopback everywhere else. PREVIEW_EXPOSURE overrides it with loopback
or tailscale. An id it doesn’t know stops the server from starting.
Every replaceable part of Screenplay is picked the same way, like the Yjs host.