open-standards/wai/wai-studio

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.

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

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:

<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

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.