# WAI Studio on the web

One front end for the WAI toolchain, with two hosts, chosen when the page starts:

- **hosted**: the core in WebAssembly, in the tab. What you open is read there; nothing is
  uploaded, and there is no account. The WAI site serves it at `/studio/`.
- **local**: served by `wai dev` at `/_wai/`, on the origin it already serves on loopback.
  The core in WebAssembly does what a tab can, and the local `wai` does the rest, reached
  through the dev stack's own routes (`/_wai/api/`).

## The panels

| Panel | Hosted | Through `wai dev` |
|---|---|---|
| Inspect | A `.wai` file opened or dropped: its envelope, its capabilities with the registry's row for each, its provenance (what it refines, what it was derived from, its security), SPEC §4's verdict at this sink, and its receipts when its receipt index is opened with it | The same, and the local `wai`'s own report, with every codec it holds |
| Verify and receipts | Receipt indexes with their group receipts, and the object where it is opened too, checked in the tab by the verifier `wai verify` runs, each line with its reason code | The same |
| Encode, decode, package | The mandatory floor: decode PNG, FLAC and zstd, encode PNG and zstd; any registered capability's bytes wrapped in an envelope | The same, and every codec the local `wai` holds |
| Rooms | A room's signed description from its service; join it as a viewer, through the room client; a pre-call test of a relay (its WebSocket binding and its SETUP, timed) | The same, against the dev room |
| Run | — | The stack `wai dev` started: its routes, each service and the loopback address it listens on, the room service's health, the relay's session records, each log as it grows |
| Quantum | Quantum Studio (`../quantum-studio/`), unchanged, as a panel | The same |

The **command palette** (the top bar's button, or Ctrl+K, ⌘K on macOS) lists every operation
of the WAI catalogue by its id. One this host runs opens the panel that runs it; one it does
not says where it runs: its command line, its `wai mcp` tool, the service route it is served
at, or Studio served by `wai dev`.

## The actions come from the catalogue

The operation catalogue (`../catalogue/ops.json`, written by `wai ops export` from the table
in `wai-rs`) names every operation. `scripts/actions.mjs` generates Studio's action table from
it (`src/actions.generated.js`), and `src/bindings.js` binds by hand the operations Studio
runs: their panel, and how each host runs them (in the tab, through the local `wai`, or by the
page). `node scripts/actions.mjs --check` fails on drift:

- an action with no operation: a binding, a call of the core, or an operation `wai dev` runs
  for the page, whose id the catalogue does not hold;
- an operation placed `client` or `both` (it runs on this side of a service, as a page does)
  with no action;
- a mismatched name: the generated table not what the catalogue generates; a binding run in
  the tab whose call is not the core's `noun_verb`; a call of the core or an operation of
  `wai dev` bound to another host than the one that runs it; an operation id in the source that
  names no operation.

Until the catalogue is on main, `ops.pending.json` is a copy of its export from the pull
request that brings it, and the check reads that; once `../catalogue/ops.json` exists, the
check reads it and fails until the copy is deleted.

## The core

`core/` (`wai-studio-core`) is the `wai` crate the command line is built from, with the floor
and the receipt checks, bound for WebAssembly. Each call is an operation of the catalogue,
named `noun_verb`, and answers the JSON envelope (`envelope/1`) the command line prints with
`--json`: `envelope_inspect`, `envelope_wrap`, `envelope_unwrap`, `media_decode`,
`media_encode`, `receipt_verify`, `registry_list`. It reads no file and opens no connection.

```sh
cd core && cargo build --locked --release --target wasm32-unknown-unknown
wasm-bindgen --target web --out-dir pkg --out-name wai_studio_core \
  "$CARGO_TARGET_DIR/wasm32-unknown-unknown/release/wai_studio_core.wasm"
```

The floor's zstd is C: its archive for wasm32 needs an archiver that indexes WebAssembly
objects, `llvm-ar` (`AR_wasm32_unknown_unknown`); macOS's own `ar` writes one the linker finds
no symbol in. `e2e/run.sh` picks `llvm-ar` where there is one.

## Building and hosting

```sh
npm ci && node build.mjs --core-pkg core/pkg [--quantum ../quantum-studio/dist]
```

writes `dist/`: `wai-studio.js`, `wai-studio-worker.js`, `wai-studio.css`, `tokens.css`, the
core in `pkg/`, Quantum Studio in `quantum/` when given, `index.html` (the local host's page)
and `hosted.html` (the hosted host standing alone), and `BUILD.json` with each file's SHA-256.

`wai dev` serves `dist/` at `/_wai/` when it finds it: `$WAI_STUDIO`, or `share/wai/studio`
beside the `wai` binary. A host page mounts Studio on an element:

```html
<div id="wai-studio" data-host="hosted" data-embedded
     data-core-pkg="/studio/pkg/wai_studio_core.js" data-worker="/studio/wai-studio-worker.js"
     data-service="/room-api" data-room-page="/studio/room.html"
     data-moq-transport="/room/room-transport.js" data-moq-session="/room/room-session.js"
     data-moq-pkg="/room/moq/pkg/wai_room_moq.js"
     data-quantum-script="/quantum-studio/studio.js" data-quantum-css="/quantum-studio/studio.css"
     data-quantum-pkg="/quantum-ide/pkg/wai_quantum_ide.js" data-quantum-worker="/quantum-studio/worker.js"
     data-quantum-service="/quantum-jobs"></div>
<script type="module" src="/studio/wai-studio.js"></script>
```

## The dev stack's routes for Studio

`wai dev` opens no listener for Studio. Under `/_wai/api/` on its origin:

| Route | What it answers |
|---|---|
| `GET /_wai/api/state` | the stack: origin, room service, relay, each service with its process and loopback address, its logs, what the local `wai` decodes and encodes |
| `GET /_wai/api/log?name=&from=` | a log (`relay`, `room`, `conversation`) from a byte on |
| `GET /_wai/api/sessions` | the relay's session records |
| `POST /_wai/api/op/<id>` | `envelope.inspect`, `media.decode` or `media.encode`, run by the local `wai` on the bytes sent, in a directory of its own, removed after |

Every request must name the origin as its host (`127.0.0.1:<port>`, `localhost:<port>` or
`[::1]:<port>`), carry `X-WAI-Studio: 1`, and state no other origin or fetch site.

## Testing it

```sh
bash e2e/run.sh [--browsers chromium,webkit,firefox]
```

builds `wai`, the relay, the room service, the core, the room client's packages, the quantum
engine, Quantum Studio and Studio; runs the unit tests (`test/`: the generation and every rule
of the drift check, the palette's "where it runs", the local core's calls, and each panel's
calls on the core) and the drift check; then `e2e/studio.e2e.mjs` against a `wai dev` stack, on
both hosts, in Chromium, WebKit and Firefox:

- each panel the host shows loads, and Run on the local host alone;
- Inspect and Verify on vectors of `../http-conformance/`, their results those its cases
  expect;
- the floor decoded and encoded in the tab, a payload wrapped and inspected;
- the dev room joined as a viewer, and the pre-call test against its relay;
- the stack in Run, every service on loopback;
- Quantum Studio mounted;
- the palette: every operation, one this host runs opening its panel, one it does not saying
  where it runs;
- axe finds no WCAG 2.2 A or AA violation on any panel; no console error, no failed request;
  nothing scrolls sideways at a phone's width.

`core/` has its own tests (`cargo test --locked`), and `wai-rs/tests/cli_studio.rs` runs `wai
dev` against a stand-in relay and room service: `/_wai/` answers, every socket the stack
listens on is on loopback, and the local `wai` runs an operation for the page.

Apache-2.0.