API reference

Data access

Actions query their input artifacts through a host-provided handle rather than reading files directly, so the same code works whether data lives in browser storage or on a Promenade Compute engine:

// Inside an action's run() function
const rows = await host.sql`
  SELECT activity, COUNT(*) AS occurrences
  FROM events
  GROUP BY activity
  ORDER BY occurrences DESC
`;

Object-centric artifacts expose typed accessors for object types, event-to-object relationships, and object-to-object relationships, alongside the same host.sql()surface for ad hoc queries.

Producing artifacts

An action returns one or more new artifacts via host.produce(), each typed and carrying a provenance record the host fills in automatically (plugin id, version, parameters, input artifact references):

return host.produce({
  type: "process-model",
  format: "petri-net",
  data: petriNet,
});

View messaging

Views run in a sandboxed iframe and receive their artifact's data viapostMessage after a small ready/init handshake, then post back user interactions the host should know about (a selection change, a request to re-run an action with different parameters):

window.addEventListener("message", (event) => {
  if (event.data.type === "promenade:init") {
    render(event.data.artifact);
  }
});

window.parent.postMessage({ type: "promenade:select", nodeId }, "*");

Parameters and the inspector

Parameters declared in a plugin's manifest are rendered automatically in the inspector panel — a plugin doesn't build its own settings UI for simple cases (numbers, enums, booleans, artifact references). Custom parameter widgets are supported for cases that don't fit those primitives.

Stability

The plugin API is still evolving alongside the application itself. Breaking changes are called out in release notes, and the manifest's runtime andcontributes shape are the parts most likely to stay stable across versions. Treat the exact function signatures above as illustrative of the pattern rather than a version-pinned reference.

The current, versioned type definitions live inthe repository, alongside the built-in plugins that exercise every part of this surface.