# Run Playground and Studio

> **Use case id:** `run-playground-studio`
> **Goal:** Start the local UI apps, know the port map, and understand the product rule.
> **Audiences:** developers
> **Tags:** ui, playground, studio

## Reading path

1. **Playground and Studio** (developers) → chapters: `1-two-surfaces`, `2-run-locally`, `3-ports`, `4-product-rule`

## From: Playground and Studio — 1. Two surfaces

Two separate UI apps over `@x12i/api-simulator`. They are **not** one merged workspace.

| Surface | Job | Mindset |
|---|---|---|
| Playground (`apps/playground`) | Try a request in ~30 seconds | Ephemeral, session-only |
| Studio (`apps/studio`) | Author and own a simulator | Persistent (IndexedDB), exportable |

Playground **Open in Studio** hands off the current definition via `sessionStorage`.

---

## From: Playground and Studio — 2. Run locally

From the repo root (after `npm install` and `npm run build`):

```bash
npm run build
npm run dev -w @x12i/playground   # http://127.0.0.1:5523
npm run dev -w @x12i/studio       # http://127.0.0.1:5521
```

Or use the root aliases: `npm run dev:playground` / `npm run dev:studio`.

---

## From: Playground and Studio — 3. Ports

Ports come from [`@x12i/ports-manager`](https://www.npmjs.com/package/@x12i/ports-manager) zone **`api-simulator`** (5520–5539, even = API, odd = UI). Wrapper: [`scripts/api-simulator-ports.mjs`](../../../scripts/api-simulator-ports.mjs).

| Name | Port | Role |
|------|------|------|
| `api` / library-demo / codegen | 5520 | API |
| `studio` (Vite) | 5521 | UI |
| `flowstate` compose server | 5522 | API |
| `playground` (Vite) | 5523 | UI |

```bash
npx x12i-ports zone api-simulator
```

**UI apps vs API processes:** Playground and Studio are Vite **UI** processes (odd ports). They do not need `@x12i/core-service` `/_live`. Example **API** processes that bind even ports (library-demo, FlowState compose, `node-server`) use `@x12i/core-service` for `/health` and `/_live` — see [Adapters — HTTP process compliance](../02-adapters/developers/BOOK.md#2-http-process-compliance-local-services).

---

## From: Playground and Studio — 4. Product rule

Both apps edit a UI model that maps to `SimulatorDefinition` / endpoint behaviors. The library remains the API of record; the UIs generate and preview — they do not invent a parallel DSL.

---

## Also see

- **Playground and Studio** (`04-playground-studio`) — Two UI apps over the same library: ephemeral Playground and local-first Studio.

---

_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._