compose-preview-server

# Compose Preview Server

The server behind `compose-preview serve`: catalog hosting, live render sessions, the playground,
and the browser viewer surfaces. Its history was extracted from
[`yschimke/compose-ai-tools`](https://github.com/yschimke/compose-ai-tools); the CLI remains there and
launches this repository's distribution.

## What this repository ships

**Archives on each GitHub release, and nothing on Maven Central.**

| Asset | What it is |
| --- | --- |
| `compose-preview-server-<v>.tar.gz` | the server: catalog hosting, the HTTP routes, the playground, the viewer surfaces. What `compose-preview serve`, `browse` and `ui-builder` launch |
| `compose-preview-mcp-<v>.tar.gz` | the MCP server, behind `compose-preview mcp serve` |

The Compose/Wasm frontend is not an asset of these releases. It is built and released by
[`yschimke/compose-ui-builder`](https://github.com/yschimke/compose-ui-builder) as
`compose-preview-ui-builder-web-<v>.zip` on that repository's own releases, and this build resolves
it from there — the server archive carries an unpacked copy either way, and the standalone zip is
for serving the editor yourself or pointing an existing `serve` at with `--ui-builder-dir`.

Nothing here is a Maven coordinate. Six modules used to publish — `compose-preview-serve`,
`compose-preview-mcp`, and four more that existed on Central only because the first one's POM named
them — and the arrangement cost more than it bought. A project dependency reaches a published POM as
a coordinate, so adding one to `:server` meant publishing the dependency too; getting that wrong
shipped `compose-preview-server:ui-builder-export-jvm:unspecified` in 3.1.0 and an unresolvable
`compose-preview-serve` from 3.3.0 through 3.8.0. Six releases nobody could resolve, for transitives
nobody wanted.

The one library consumer was compose-ai-tools' `:cli`, which compiled two wire-drift tests against
`compose-preview-serve`. Those tests launch the distribution now
([compose-ai-tools#5436](https://github.com/yschimke/compose-ai-tools/pull/5436)) — the artifact
`serve` runs anyway, so they check the wire that actually ships. Released coordinates up to and
including 3.24.0 stay resolvable on Central; there simply will not be new ones.

`render-host` exists because rendering a packed bundle and reading a preview timeline out of git
open no sockets, and a caller doing only that should not link `ktor-server-*`, `jmdns` and
`kotlin-reflect` to do it. It is **published from
[compose-ai-tools](https://github.com/yschimke/compose-ai-tools)**, not from here: that is where
everything it depends on lives, and offline behaviour belongs in that layer
([#180](https://github.com/yschimke/compose-preview-server/issues/180)). It used to be this
repository's `:render-host` module, publishing as `compose-preview-render-host`; that coordinate
stays resolvable at its final 2.x for anyone pinned to it, and the new one is on compose-ai-tools'
version line. The measured before/after and the transitives it deliberately cannot drop are recorded
in its build file there, and `checkRenderHostIsServerFree` moved with it.

The UI builder is a second repository —
[`yschimke/compose-ui-builder`](https://github.com/yschimke/compose-ui-builder) — and `:server`
consumes it as releases. Its `:ui-builder-runtime` owns authoritative persistent design state, exact
catalog validation and revision-pinned export orchestration there; `:server` supplies
HTTP/authentication and adapts its narrow render request onto the render host. The runtime therefore
has no Ktor, daemon/render-host, MCP or Compose UI dependency, while the offline render host has no
UI-builder protocol or service edge. Three jars and a BOM come from Maven Central at
`composeai-ui-builder` in `gradle/libs.versions.toml`, and the editor archive from that repository's
GitHub release; `-PcomposeUiBuilderDir` swaps all four for a checkout when working on both at once.

The build is intentionally repository-independent. Compose Preview implementation artifacts resolve
from Maven Central at the version in `gradle/libs.versions.toml`; wire contracts resolve separately
from [`compose-preview-contracts`](https://github.com/yschimke/compose-preview-contracts). There is
no `mavenLocal()` repository and no shared version catalog outside this repository. A composite
build is opt-in only — `-PlocalBuilds=tools,daemon,contracts` for the upstreams,
`-PcomposeUiBuilderDir` for the UI builder — and for unreleased contract or generator changes an
explicit
[local dependency manifest](docs/development/LOCAL_DEPENDENCIES.md) selects artifacts compiled from
local checkouts. Leaving those options unset retains the released dependency graph.

## Java

**Run the distribution on Java 17 or newer. The UI builder's PNG/SVG export needs Java 21.**

The two numbers are one difference, and it is worth stating plainly rather than leaving to be
inferred from build files. The server itself, `mcp serve`, and every artifact this repository
publishes target Java 17, because `compose-ai-tools`' CLI compiles against them on a 17 toolchain
and its `serve` / `mcp serve` commands launch this distribution's start script as a separate
process, resolving `java` from `JAVA_HOME`/`PATH`. Only the UI builder's renderer is above that
floor: the design it rasterizes is drawn by a Compose preview compiled for Java 21, packaged into
the render bundle, and unpacked into a daemon that runs on the server's own JVM.

On an older JVM the server still starts and everything else works; the UI builder loses PNG and SVG
export and says so at startup, naming the version it found and the one it needs. Point `JAVA_HOME`
at a Java 21 JDK to get it back, or pass `--ui-builder-state-dir none` to run without the UI builder
at all. The published container image
([`deploy/image/Dockerfile`](deploy/image/Dockerfile)) is built on Temurin 21 and clears both.

Both floors are declared once, as `java-server` and `java-ui-builder` in
[`gradle/libs.versions.toml`](gradle/libs.versions.toml), which is also where the reasoning lives.
`:server:checkServerJvmFloor` fails the build if anything above `java-server` reaches the
distribution's classpath, and the render bundle carries `java-ui-builder` as data so the startup
message cannot drift from the bytes it describes.

## Build

`./gradlew check` needs one JDK: 17. The UI builder's frontend lane compiles at 21 in its own
repository, and the only lane here that still wants both JDKs is `visual-harness`, which builds that
repository's Wasm distributions from a checkout. Gradle finds a 21 installed anywhere it already
scans (`/usr/lib/jvm`, SDKMAN, asdf, jabba); if it cannot, the failure is
`No matching toolchains found for requested specification: {languageVersion=21}` and the fix is to
install one, not to lower the target.

```shell
./gradlew check ktfmtCheckAll
npm --prefix serve-web ci
npm --prefix serve-web run verify
```

The independently installable visual harness lives in `preview-harness/`. The experimental
Compose/Wasm frontend lives in `wasm-ui/`. The UI builder itself — editor, renderer, artwork and the
Jetcaster fixtures — lives in
[`yschimke/compose-ui-builder`](https://github.com/yschimke/compose-ui-builder); this build resolves
its editor archive, runtime and export from that repository's releases, and the harness builds the
renderer and fixture distributions from a checkout of it. The server distribution packages the
editor at `/ui-builder/`; the existing catalog-scoped `/wasm/<system>/` preview application remains
a distinct feature and route. The editor route opens an interactive Wasm editor around the frozen
Jetcaster design; clean benchmark modes remain available to the independent visual harness. The
editor mounts an exact retained renderer runtime under `/ui-builder/runtime/<runtimeId>/` in a
sandboxed iframe and receives measured node/slot geometry without placing editor overlays in the
Compose tree. Catalog runtimes retain a small commit-pinned source descriptor after their catalog
generation is swept, so an older design revision can recover its exact runtime after a restart. The
compressed archive shares the bounded catalog blob pool; expanded historical trees are
process-local leases with an inactivity timeout and a hard count ceiling rather than an unbounded
second artifact store.

The Remote Compose authoring extension is behind the default-off compile-time option
`-PuiBuilderRemoteCompose=true`. It spans two repositories — the MCP adapter's half is generated
here, and the server's half is baked into the UI-builder export at *its* build time, so enabling the
server half means building against a UI-builder checkout with the option
(`-PcomposeUiBuilderDir=…`). See
[feature scope and verification](docs/development/UI_BUILDER_FEATURE_FLAGS.md).

## Remote catalog MCP

The server can expose every hosted catalog through one aggregate Streamable HTTP MCP endpoint at
`/mcp`. Enable it with `--agent-grants --catalog-mcp`; published resources require a
short-lived `preview` grant, while made-to-order renders and structured data products require a
`live` grant. The endpoint is separate from the stateful UI-builder authoring MCP surface, but both
use the same authenticated user approval and revocation flow. See
[the catalog MCP design and setup guide](docs/design/CATALOG_MCP.md).

## Local daemon MCP

`compose-preview-mcp` also exposes the local stdio MCP server used by editor and agent plugins.
`render_preview` remains a token-frugal semantics observation by default; a local client that can
read the same filesystem passes `inline: false` to receive the rendered PNG's absolute `pngPath`,
dimensions, SHA-256, elapsed render time, and a per-session `changed` signal instead of image bytes.
After discovery, `find_previews_for_file` maps an absolute source path — or one relative to a
registered workspace — to the preview URIs declared there. Both returned URIs can be passed
directly to `render_preview`.

## Spatial and WebXR previ