Skip to content

feat(docs): run the real sysml REPL in the browser with walkthroughs; make the landing diagram editable - #869

Merged
HuiJun merged 3 commits into
developfrom
feature/browser-repl-walkthroughs
Oct 3, 2026
Merged

HuiJun merged 3 commits into
developfrom
feature/browser-repl-walkthroughs

Conversation

@devin-ai-integration

Copy link
Copy Markdown
Contributor

What and why

The landing page is popular, but its browser REPL was a small JavaScript shell over five sysml-engine RPCs. It had six commands, you couldn't declare anything at the prompt, and there were no walkthroughs. This PR replaces it with the real REPL and adds an editable landing diagram.

CLI page: the real sysml REPL in the page (docs/cli.md, docs/assets/sysml-repl.js)

  • cmd/sysml is built for js/wasm with -tags sysml_prod. It is about 11.9 MB gzipped and is only downloaded when you start it. make docs-engine-assets, which the Pages workflow already runs, now builds it next to sysml-engine and copies the runtime-showcase models into docs/assets/repl-examples/.
  • sysml-repl.js hosts it. It runs the REPL on an in-memory filesystem, so %load and %save work. stdin is fed one line per prompt, and both the sysml> and ...> prompts are rendered.
  • Up and Down recall history, which is stored in localStorage and survives reloads. A multi-line block is stored as one entry. Shift+Enter adds a line. Tab completes through the REPL's own completer, exposed to the page as globalThis.sysmlReplComplete (cmd/sysml/complete_js.go). Ctrl-L clears the screen, Ctrl-C clears the line and Ctrl-D ends the session.
  • Seven guided walkthroughs live in docs/assets/repl-walkthroughs.json. Each one types its commands into the prompt:
    1. Units
    2. The Saturn V mass rollup
    3. The delta-v analysis, with %sweep
    4. A failing %satisfy
    5. Stepping Apollo 11's action, with %step and %tokens
    6. The spacecraft-comms clock
    7. A state machine you write yourself, with %send, %trace, and %save/%clear/%load
  • The page states what a browser can't do. Commands that need an SMT solver report it as unavailable, and the prod build leaves out codegen, Flexo sync, v1 migration, FMI and PDF.

Landing page: the diagram can be edited (overrides/home.html)

  • "View the model" is now "Edit the model". It opens the diagram's SysML source in a text box. As you type, sysml-engine re-parses and re-instantiates the model and redraws the parts and interfaces.
  • A parse error is shown with its line and column, and the last diagram that parsed cleanly stays on screen. "Run the model" executes the edited ModelJourney, and Reset puts the original model back.

CLI REPL walkthrough
Landing diagram after an edit
Landing diagram with a parse error

How it was verified

  • New TestBrowserREPLWalkthroughs (tests/wasm/browser_repl_test.go and testdata/browser-repl.mjs):
    • It builds the sysml_prod js binary and runs every walkthrough step through sysml-repl.js under Node, using the real example files.
    • Each step's output must contain that step's expect strings, and no step may panic.
    • The gzipped binary must fit a 13 MB budget.
  • go vet and staticcheck were run for the host, js and wasip1 builds, plus gosec on ./cmd/sysml and ./tests/wasm. scripts/check-doc-links.py and scripts/changelog.py check were run too.
  • The site was built strict with MkDocs, served statically and driven with Playwright in Chromium:
    • Walkthrough steps ran end to end, including Apollo 11 and the mass rollup.
    • History works, including multi-line entries, and is restored after a reload.
    • Tab completes and lists candidates. Ctrl-L clears.
    • On the CLI page, the REPL mounts and runs after Material instant navigation and after Back/Forward.
    • The palette toggle and a 390 px viewport work, with no horizontal overflow.
    • There were no page errors.
  • Landing editor: adding a part and an interface draws a new box and wire. Deleting a ; shows line 56:24: missing ';' and keeps the last good diagram. Run and Reset still work.

Checklist

  • make test and make lint pass locally: I ran the new test and the existing wasm landing-model test, plus lint on the changed packages. I did not run the full make test; CI covers it.
  • Tests added or updated for the change
  • Documentation extended where it already covers the surface (see CONTRIBUTING.md)
  • Changelog entry added as changes/unreleased/<slug>.<section>.md, not as an edit to CHANGELOG.md
  • baselines regenerated and make docs-counts run if a gate count moved: not applicable, no gate count moved
  • No internal work-item labels (waves, slices, F4, K5) in the body, docs, or changelog

Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/3c199970a2f14e5a8984ccab7a7fd242
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/3c199970a2f14e5a8984ccab7a7fd242?variant=devin
Requested by: @HuiJun

… make the landing diagram editable

The CLI page's toy shell over sysml-engine is replaced by cmd/sysml built
for js/wasm with -tags sysml_prod, hosted by docs/assets/sysml-repl.js on an
in-memory filesystem holding the runtime-showcase models. Seven guided
walkthroughs type their commands into the prompt; Up/Down history persists
across visits and Tab completes through Session.Complete, exposed to the
page as sysmlReplComplete. TestBrowserREPLWalkthroughs runs every
walkthrough through the page host and pins its output.

The landing diagram's source opens in an editor: the engine re-parses and
re-instantiates the model as you type and redraws parts and interfaces,
keeping the last good diagram while a parse error is shown.

Co-Authored-By: jason.han <hanhuijun@gmail.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor Author

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@devin-ai-integration

Copy link
Copy Markdown
Contributor Author

Browser-tested the locally rebuilt MkDocs site with the real WebAssembly runtimes (Chromium, desktop and 390px viewports).

Interactive REPL and editable model
  • All 36 steps across seven walkthroughs matched their expected output.
  • Multiline input (Shift+Enter), whole-block history persisted across reload, all three Tab completion modes, user-typed %save/%clear/%load, and Ctrl-C/L/D with restart passed.
  • %check reports that a WebAssembly build cannot start an external SMT solver, and later commands still work.
  • Landing editor: adding a part and interface redraws 5 parts / 4 interfaces, and the edited ModelJourney executes the changed route. A missing ; shows the diagnostic with line and column while the last good diagram stays; Reset restores the original model.
Walkthrough execution Edited ModelJourney execution
State-machine walkthrough Edited model route
Navigation and responsive checks

Material instant navigation and Back/Forward kept the document and remounted one working REPL. The light/dark toggle works. Both pages fit a 390px viewport without document overflow. No unhandled page JavaScript errors.

Mobile REPL Mobile editor
390px REPL 390px model editor

…kill

Co-Authored-By: jason.han <hanhuijun@gmail.com>
@HuiJun
HuiJun marked this pull request as ready for review October 3, 2026 22:22
devin-ai-integration[bot]

This comment was marked as resolved.

…e landing editor

Co-Authored-By: jason.han <hanhuijun@gmail.com>
@HuiJun
HuiJun merged commit 53e1152 into develop Oct 3, 2026
@HuiJun
HuiJun deleted the feature/browser-repl-walkthroughs branch October 3, 2026 22:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant