apps/app/CONTEXT.md is the glossary for the product’s domain language.
Design decisions are recorded as ADRs in apps/app/docs/adr/. Read both
before a larger change.
Running the product
There are two ways to run apps/app locally.
Local mode (no services)
The same build switches the desktop app uses let you run the full product with
no external services: embedded Postgres, a local Yjs server, and
each chat’s code as a git worktree. You need a coding CLI such as Claude Code
installed for the agent.
cd apps/appNEXT_PUBLIC_SCREENPLAY_PROFILE=desktop NEXT_PUBLIC_YJS_HOST=local NEXT_PUBLIC_BASE_PATH= \SANDBOX_BACKEND=local SCREENPLAY_DB=pglite BLOB_STORE=local-fs AGENT_ENGINE=external \ENCRYPTION_KEY=$(openssl rand -hex 32) TERMINAL_AUTH_SECRET=$(openssl rand -hex 32) \ pnpm dev
Open http://localhost:3000. Data lives under
apps/app (.pglite/, .data/yjs/, .screenplay/blobs/), and worktrees go
under ~/.screenplay/.
Hosted mode
The multi-user build needs the real services: Postgres, a GitHub OAuth app,
Liveblocks, a sandbox provider, and at least one model provider. See
Self-hosting for what each one is.
cp apps/app/.env.local.example apps/app/.env.local # fill in the valuescd apps/app && pnpm db:migratepnpm dev
pnpm dev at the repository root starts every app through Turborepo.
Run it inside apps/app to start just the product.
Commands
From the repository root (runs across all packages via Turborepo):
pnpm dev # dev serverspnpm build # production builds (apps/app runs its migrations first)pnpm lint # ESLintpnpm typecheck # tsc --noEmitpnpm format # Prettierpnpm format:check # Prettier, checking onlypnpm test # Vitest
CI runs pnpm lint, pnpm format:check, pnpm typecheck and pnpm test on
every pull request. A lint error or an unformatted file fails it; lint warnings
don’t. Besides React’s rules, lint checks the design rules a machine can judge
(packages/eslint-config/design-rules.js): JSX text keeps its space after an
{expression}, Buttons use only the sm, icon-sm, default and lg sizes,
and status colours are never /NN tints.
In apps/app, pnpm test:watch runs Vitest in watch mode. Database helpers:
pnpm db:generate # generate a migration from schema changes (commit it)pnpm db:migrate # apply migrations to $DATABASE_URLpnpm db:push # sync the schema without a migration (throwaway dev only)pnpm db:studio # open Drizzle Studio
The dev indicator pulses nonstop, or Turbopack panics with
“EcmascriptMergedChunkVersion … no longer exists” or “[Server HMR]
Subscription error”. Turbopack rebuilds on every change to a file under
apps/app that git doesn’t ignore, even one no module imports. Something is
writing there: any folder the app writes state to during next dev belongs
in .gitignore (.pglite/, .data/ and .screenplay/ already are).
next dev hangs at “Compiling /[roomId] …”, or a build complains that
build-manifest.json is missing after you switch between the hosted and
local screenshot harness. Turbopack’s on-disk cache in apps/app/.next is
stale: rm -rf apps/app/.next and start again.
“Could not find the Next.js package” from the docs screenshot harness.
Next skips pnpm-workspace.yaml when $HOME sits inside the repository,
which the harness does on purpose, so apps/app/next.config.mjs pins
turbopack.root to the repository root. Check that the pin is still there.
Testing
pnpm test at the root runs every package’s tests through Turborepo, which
replays cached results when a package’s inputs haven’t changed. After a
dependency or config change, add --force so the tests really run:
pnpm turbo run test --filter=app --force
Besides lint and typecheck, CI runs the package tests, the app’s unit tests
in three shards, and a browser job with Chrome, Xvfb and ffmpeg installed. A test that
needs that browser stack must be named *.browser.test.ts: the unit shards
skip that name, and apps/app/test/browser-tests.test.ts fails a test that
mentions Xvfb under any other name. In the browser job,
SCREENPLAY_REQUIRE_BROWSER_STACK=1 turns a missing stack into a failure
instead of a skip, so copy that check into a new browser test after its own
stack gate.
A pull request that changes only a workflow file changes no package’s inputs,
so CI replays main’s cached test results and the browser tests never really
run. Its green check doesn’t show that the workflow change works.
To try an OpenCode chat without a model provider, run a scripted
OpenAI-compatible mock server and add it as provider.mock in the JSON you
pass in OPENCODE_CONFIG_CONTENT. Screenplay adds its own settings to a config
already in that variable rather than replacing it (opencodeDirectoriesEnv in
apps/app/lib/agent/harnesses/opencode.ts).
Linux isn’t a Mac
The desktop app renders in the Mac’s WKWebView, and nothing on Linux paints
the way it does. Headless Chromium and the screenshot harness are right for
layout, copy and behaviour, but not for pixel-level rendering:
Text snaps to whole pixels on Linux. Headless Chromium rounds text to
whole CSS pixels, so a half-pixel offset never shows in a capture, while
the Mac’s fractional font metrics can tip it into a visible 1px jump. To
show one on Linux, nudge the parent by 0.6px.
WebKitGTK’s compositor isn’t Core Animation. WebKitGTK under Xvfb
reproduces some WebKit layout bugs, and Playwright’s WebKit repaints its
screenshots in software. Neither composites or rasters layers the way the
Mac does: a label change that looked crisper in WebKitGTK went blurry on a
Mac (PR #1775,
reverted in PR #1776).
Only a real WKWebView capture proves a Mac raster or compositing fix.
Capture a system WKWebView window on a Mac (screencapture), before and
after. That is how the off-centre spinner was found: WebKit gives an
animated <svg> its own layer and pivots it off the pixel grid, so
spinners rotate their <path> instead
(PR #1783).
To check a layout or JavaScript fix in WebKit from a Linux container, where
Playwright’s WebKit may not download, run WebKitGTK under Xvfb. Install
xvfb python3-gi gir1.2-webkit2-4.1 gir1.2-gtk-3.0 imagemagick with apt,
start Xvfb :99, and open the page in a short Python GTK WebView script (use
a Python that can import gi: in the cloud container that’s python3.12, not
the default 3.13). Have the script poll a file for JavaScript to evaluate, so
you can control the page, for example the fixture world’s camera with
window.__canvasCamera.setTransform(x, y, zoom), and shoot the screen with
import -window root. It shows layout, never proof of a raster fix.
Zoomed frames blur on the Mac by choice; see
ADR 0034
before trying again.
Desktop app
pnpm --filter desktop build:sidecar # build apps/app as the bundled sidecarpnpm --filter desktop dev # run the Tauri apppnpm --filter desktop build # package Screenplay.app
This needs the Rust and Tauri toolchains. See
Desktop app.
Releasing the desktop app
Releases are cut on a Mac with one command:
pnpm --filter desktop release patch # or minor, major, or an exact X.Y.Z
It bumps the version, builds a signed and notarized .dmg, checks it with
Gatekeeper, then commits the bump, tags desktop-v<version> and publishes a
GitHub Release with the
.dmg attached, once under its version and once as Screenplay.dmg, the name
the homepage’s Download buttons link to. Nothing is tagged or published unless
the build verifies.
The Release’s notes are a short changelog for people using the app, not a list
of commits. Before the build, the script collects the pull requests merged
since the last release that change the app (skipping the homepage, docs, tests
and CI), and asks claude -p to write them up as New, Improved and Fixed. It
shows the draft so you can accept it, edit it in $EDITOR, or stop. Without
Claude Code installed, the draft lists the pull request titles. To write the
notes yourself, pass a Markdown file with --notes notes.md.
Releasing needs Node 23 or later, the gh CLI signed in, a clean working tree, and the
Apple signing keys in apps/desktop/.env.release (copy
.env.release.example).
Screenshots for design review
Design-polish tickets ship before/after screenshots on the PR. The screenshot
harness boots the local build against a seeded fixture world and captures a
named list of screens in light and dark:
pnpm --filter app screenshots:boot # a browsable, fully-populated local buildpnpm --filter app screenshots:shots --screens canvas # named screens, both themes
The harness README covers the before/after workflow,
how to add a screen, and what the local build leaves out.
Writing docs
These docs live in apps/docs/content as MDX. Run the site with
pnpm --filter docs dev, then open
http://localhost:3002/docs.
Screenshots are framed WebP images in apps/docs/public/screenshots, in a
light and a dark variant (name.light.webp, name.dark.webp). Embed one with:
<Screenshot name="hero" alt="Describe what the screenshot shows" />
The component shows the variant that matches the reader’s theme. Put two
related shots side by side (they stack on a phone) with:
Keep full-window shots for the Introduction and Core concepts, where the
whole layout is the point. Everywhere else, crop to the part the section is
about. Every
screenshot is generated: run pnpm --filter docs screenshots to regenerate them
after a UI change, and see Docs screenshots to
add one.
Pull requests
Open a pull request ready for review, not as a draft.
Before you push, merge main in and run the app’s full suite
(pnpm --filter app test), pnpm typecheck and pnpm lint. A pull request can be
merged as soon as its review looks right, before CI finishes, so a red
check found only by CI lands on main.
A pull request that changes what a user sees or configures updates the
page here that describes it, or says why not on a Docs: line in its
description.
Dependencies lists the versions held back on
purpose, and Publishing covers the npm packages
and preview deploys.
Issues
Bugs and feature requests are tracked in
GitHub issues.