Get started

Studio tool bus in Node

The studio's tool bus, dispatched from a Node process. It registers every verb, reads the studio's state, and gets a clean refusal from a verb that needs a map.

The Node program, printing one line per dispatch

The files

Every file the program needs, as it runs in the SDK repository.

From examples/studio-node/package.json
{
  "name": "@mountaya/example-studio-node",
  "version": "0.0.0",
  "private": true,
  "license": "MIT",
  "description": "The studio's tool bus dispatched from a Node process, with no bundler, no DOM and no React.",
  "type": "module",
  "scripts": {
    "build": "tsc --noEmit --project tsconfig.source.json",
    "dev": "node src/main.ts",
    "lint": "tsc --noEmit"
  },
  "dependencies": {
    "@mountaya/client": "0.1.0",
    "@mountaya/elements": "0.1.0",
    "@mountaya/studio": "0.1.0"
  },
  "devDependencies": {
    "@types/node": "26.6.5",
    "typescript": "7.0.2"
  }
}
From examples/studio-node/src/main.ts
import {
  createUiStore,
  inertViewer,
  type StudioToolContext,
  type ToolResult,
} from "@mountaya/studio";
import { createStudioToolBus } from "@mountaya/studio/handlers";
import { createInertStudioSeams } from "@mountaya/studio/seams";

// The claim this program runs to prove: the studio's rules need no page. Nothing here defines a
// DOM global, and an entry point that reached for one while loading would have thrown above.
if ("document" in globalThis || "window" in globalThis) {
  throw new Error("Run this where there is no DOM: it proves the studio needs none.");
}

/**
 * The bus, holding the studio's own verbs, each validated against its published contract before
 * its handler runs.
 */
const bus = createStudioToolBus();

/**
 * What a handler is invoked with. `bus` is the bus's dispatch surface and nothing else of it, so a
 * handler or a plugin chains into another verb and can take none off. `saveFile` is the one
 * `createInertStudioSeams` ships, with no disk to save to, and a seam the context leaves out (the
 * clock, the ids, the device's position, the camera planner) is answered by the studio's own
 * default. There is no `api` and no `map`, and a tool that needs either answers with a result,
 * never a throw.
 */
const context: StudioToolContext = {
  bus: bus.dispatcher,
  capabilities: new Set(["authenticated", "editor", "embedding"]),
  map: null,
  saveFile: createInertStudioSeams().saveFile,
  ui: createUiStore(),
  viewer: inertViewer,
};

/**
 * Prints one dispatch. `summary` and `error` are written for a log and for a model, and this is
 * a log: a surface a person reads branches on `code` and words the refusal itself.
 */
const report = (name: string, result: ToolResult): void => {
  console.log(
    result.ok
      ? `${name}: ${result.summary}`
      : `${name}: refused with ${result.code ?? "no code"} (${result.error})`,
  );
};

/** A read: the studio's state as a whole, straight from its stores. */
const state = await bus.dispatch(context, "studio.state.get", {});
report("studio.state.get", state);

/** A refusal: a verb that drives the map, dispatched where no map is mounted. */
const zoom = await bus.dispatch(context, "studio.map.zoomIn", {});
report("studio.map.zoomIn", zoom);

// Dispatch resolves either way, so the two outcomes are checked and not caught.
if (!state.ok || zoom.ok || zoom.code !== "no-map") {
  process.exitCode = 1;
}

Run it

Save the two files in a new folder. With Node 22.18 or later, it takes no key and makes no request:

npm install
npm run dev

It prints one line per dispatch:

studio.state.get: Studio state: no itinerary open.
studio.map.zoomIn: refused with no-map (no map is currently mounted)

The same program is examples/studio-node in the SDK repository.

Next steps

Last updated