@surprisal/hyperchart

Host-neutral Hyperchart authoring, machine, replay, runtime, and inspector models.

Install

npm install @surprisal/hyperchart

Requires Node.js 22.19 or newer.

Create a chart

import { chart, final, script } from "@surprisal/hyperchart";

export default chart({
  kind: "chart",
  id: "hello",
  args: {
    message: { description: "Text to print", default: "hello" },
  },
  initial: "run",
  states: {
    run: {
      kind: "state",
      action: script("node", ["-e", "console.log('done')"]),
      transitions: { DONE: "done" },
    },
    done: final(),
  },
});

Optional chart-level args metadata gives hosts serializable descriptions and JSON defaults for on-demand launch forms; it is inspection metadata, not executable validation or automatic runtime input. refs<Args>().chart() accepts subset or empty metadata and rejects every key outside Args, including typos mixed with valid keys. A script with one successful transition may select it implicitly on exit code 0. Top-level final() and failed() terminals explicitly select complete or failed run outcome; optional terminal notifications can append a scoped prompt and authoritative paths for declared artifacts. Runner/host delivery uses a persist-once outbox and per-session receipts.

Entry points

| Import | Purpose | |---|---| | @surprisal/hyperchart | DSL, types, parsing, inspection, machine, projection, replay | | @surprisal/hyperchart/runtime | generic runtime, log stores, scripts, guards, artifacts | | @surprisal/hyperchart/host | canonical chart/run models and adapters | | @surprisal/hyperchart/react | optional React inspector and run surfaces | | @surprisal/hyperchart/react/styles.css | required inspector stylesheet | | @surprisal/hyperchart/package.json | package metadata | | @surprisal/hyperchart/inspect | run inspection, inspector server, and session transcripts | | @surprisal/hyperchart/sessions | session progress, steering, and run status |

The host runtime overlay distinguishes map actions held behind a concurrency gate as waiting; admitted or invoked actions remain running. In the React inspector, agent cards show declared role/toolset metadata and resolved model/tool configuration, while a selected run state's Runtime section owns its live-session controls and actual launch-plan summary. HyperchartRunStrip accepts the lightweight chart/run summaries from readSessionSnapshot() directly and hides progress when its three summary progress fields are omitted or incomplete.

The core package has no Pi dependency. React integrations use the optional peer dependencies declared by the package.

Documentation

• Run your first chart
• Author charts
• Runtime and durability
• Complete API reference
• DSL reference and examples

Explicit actors

The core package includes statically placed, event-sourced actors with explicit receive(), FIFO send, typed call, and graph-inferred reply(). See the canonical explicit actor guide.

MIT · experimental 0.6.0

Static actor pools are available through actorPool(). Use singleton send()/call() or explicit non-empty sendBatch()/callBatch(); actor templates may target their current endpoint with send-only self(). See the canonical explicit actors guide.

Branch storage

The runtime exports v2 storage mutation/branch types, normalized tree queries, JsonlLogStore, listHyperchartBranches, getHyperchartBranch, forkHyperchartRun, and append-only rewindHyperchartRun. Every runner/inspection uses an explicit branch handle. Detached runners distinguish the owning repository projectDir from each isolated <runDir>/workspaces/<branchId> action cwd; scripts receive both as HYPERCHART_PROJECT_DIR and HYPERCHART_BRANCH_WORKSPACE.