Add breakpointSteps to the CSE snapshot protocol

[Akshay-2007-1]

Summary

• Adds breakpointSteps: number[] to CseSnapshotMessage in @sourceacademy/common-cse-machine: a run-level array of 0-based step indices where a breakpoint (e.g. Python's breakpoint(), JS's debugger;) sits on top of the control.
• CseMachinePlugin.sendSnapshots (runner) takes it as an optional second argument (defaults to []) and forwards it in the message.
• CseMachineHostPlugin.receiveSnapshots (web) now receives it as a second parameter, passed through from the message (?? [] if absent).
• Adds a changeset (minor bump for all three affected packages — additive, non-breaking).

Why

Mirrors the stepper protocol's existing redexNodeType marker field, which host apps use to drive breakpoint-navigation (double-chevron) controls. The CSE machine protocol had no equivalent, so a CSE-machine-based evaluator (e.g. py-slang, for source-academy/py-slang#189) had no way to tell the host which steps to jump to. This is a companion change to a py-slang change that detects breakpoint() in the CSE machine and populates this array, and a frontend change that wires it into the existing updateBreakpointSteps Redux action.

Test plan

• Updated/extended unit tests in all three touched packages (common.test.ts, runner.test.ts, web.test.ts) — 66 tests passing
• tsc --noEmit clean on all three packages
• Rebuilt each package's dist/ and confirmed the new field/param is present in the emitted bundle

[changeset-bot]

🦋 Changeset detected

Latest commit: 55bc989

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

💥 An error occurred when fetching the changed packages and changesets in this PR

Some errors occurred when validating the changesets config:
The package or glob expression "@sourceacademy/web-stepper" is specified in the `ignore` option but it is not found in the project. You may have misspelled the package name or provided an invalid glob expression. Note that glob expressions must be defined according to https://www.npmjs.com/package/micromatch

[gemini-code-assist]

Code Review

This pull request introduces breakpointSteps to the CSE snapshot protocol, allowing host applications to wire breakpoint-navigation controls for CSE-machine-based evaluators. The changes update CseMachinePlugin.sendSnapshots and CseMachineHostPlugin.receiveSnapshots to support and propagate this new array of step indices. The feedback suggests making breakpointSteps optional in the CseSnapshotMessage interface to ensure backward compatibility, and defensively verifying that message.breakpointSteps is an array at runtime before passing it to receiveSnapshots.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Akshay-2007-1]

Addressed both suggestions in 5c35f18: breakpointSteps is now optional on CseSnapshotMessage, and the web plugin defensively checks Array.isArray(message.breakpointSteps) before passing it through.

[Akshay-2007-1]

@coderabbitai, any review comments?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
gh pr view 55 --repo source-academy/plugins --json title,body,files,commits -q '.'
echo "---FILES---"
gh pr diff 55 --repo source-academy/plugins

Length of output: 14705

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail
sed -n '1,80p' src/web/cse-machine/src/index.ts

Length of output: 2465

---

The changes look solid overall — I checked the current diff (commits 668a454 and 5c35f18) and confirm both previously flagged points are addressed correctly:

• breakpointSteps?: number[] is now optional on CseSnapshotMessage in src/common/cse-machine/src/index.ts.
• receiveSnapshots in src/web/cse-machine/src/index.ts guards with Array.isArray(message.breakpointSteps) ? message.breakpointSteps : [] before forwarding, which correctly handles messages from older runners or malformed payloads.

A couple of minor, non-blocking observations for your consideration:

1. No validation of breakpointSteps contents. The subscribe handler in src/web/cse-machine/src/index.ts (Line 51-61) only checks Array.isArray(message.breakpointSteps) but doesn't verify the array elements are actually numbers, or that each index falls within [0, totalSteps). Since this crosses a conduit channel boundary from a potentially malformed/older runner, a malicious or buggy payload could contain non-numeric entries or out-of-range indices, which downstream host code (e.g. the Redux updateBreakpointSteps wiring) may not expect. Given message.snapshots and message.totalSteps aren't deeply validated either, this may be an accepted tradeoff for this PR's scope — just flagging it in case you'd like tighter validation now or as a follow-up.

2. Ordering not enforced. The doc comment states breakpointSteps should be "in ascending order," but this is documentation-only — nothing enforces it in CseMachinePlugin.sendSnapshots (src/runner/cse-machine/src/index.ts). Since the runner and the py-slang breakpoint detector are the sole producers today, this is likely fine, but consumers on the host side should probably not assume sortedness without an explicit guarantee/test.

Neither of these blocks the PR — the core protocol addition, optional-field backward compatibility, and defensive parsing are all in good shape, and the test coverage across common.test.ts, runner.test.ts, and web.test.ts looks appropriately thorough for the new field.

[resolve]