Features

• Transports a complete run's worth of CSE snapshots from the evaluator (worker) to the host app (browser) over a Conductor channel
• Language-agnostic: any evaluator can use it as long as it serializes its state into CseSnapshots

Installation

yarn add @sourceacademy/runner-cse-machine
# OR
npm i @sourceacademy/runner-cse-machine
# OR
pnpm add @sourceacademy/runner-cse-machine

Structure

This package (@sourceacademy/runner-cse-machine) contains the CseMachinePlugin class — a Conductor runner plugin that an evaluator registers and calls after each run to forward snapshots to the host.

The plugin owns only the transport. Serializing a language's control/stash/environment into CseSnapshots is the evaluator's responsibility and stays in the evaluator repo.

API Reference

| Name | Description | |------|-------------| | sendSnapshots(snapshots: CseSnapshot[]): void | Send the full batch of snapshots for a completed run to the host plugin. Call this once per run after all steps have been collected. |

Usage

After installation, import CseMachinePlugin and register it with the Conductor evaluator. After each run, collect your language-specific snapshots, serialize them into CseSnapshots, and call sendSnapshots.

import { CseMachinePlugin } from '@sourceacademy/runner-cse-machine';
import type { CseSnapshot } from '@sourceacademy/common-cse-machine';

// Register the plugin when setting up the evaluator
const cseMachinePlugin = conductorContext.getPlugin(CseMachinePlugin);

// After a run completes, serialize each step into a CseSnapshot
const snapshots: CseSnapshot[] = steps.map((step, i) => ({
  stepIndex: i,
  control: step.control.map(serializeControlItem),
  stash: step.stash.map(serializeValue),
  environments: serializeEnvChain(step.environments),
  currentLine: step.currentNode?.line,
}));

cseMachinePlugin.sendSnapshots(snapshots);

For a full example of how to serialize a language's control/stash/environment into CseSnapshots, see the py-slang PyCseMachinePlugin.

Further reading

• For the shared protocol types and IDs, see @sourceacademy/common-cse-machine
• For the host-side plugin that renders snapshots, see @sourceacademy/web-cse-machine
• The plugins wiki covers how Conductor plugins communicate