Playground is too persistent, errors are not explained

[lefticus]

The playground keeps state between file edits, and errors start to occur

• Make sure playground engine is reset between edits and re-executions of the script
• Catch and display exceptions thrown from the ChaiScript engine.

[lefticus]

@leftibot fix this.

[lefticus]

@leftibot I reopened this issue because the playground is now stuck in "resetting" mode and never actually becomes usable.

[leftibot]

Looked at playground.html (post-#15) and playground/chaiscript.js. The fix is stalling because the approach itself isn't supported by Emscripten.

What's happening

resetEngine() in playground.html:330-343 tries to reset the engine by removing the <script> tag and appending a new one with the same src:

engineScript.parentNode.removeChild(engineScript);
Module = createModuleConfig();
window.Module = Module;
engineScript = document.createElement('script');
engineScript.src = '/playground/chaiscript.js';
document.body.appendChild(engineScript);

The generated playground/chaiscript.js is a non-MODULARIZE Emscripten build — the first line is the giveaway:

var Module=typeof Module!="undefined"?Module:{};

It declares Module, worker state, scriptDirectory, embind registries, etc. at global scope and wires up a whole bunch of async bootstrapping (incl. __embind_register_* callbacks that attach the C++ API — like Module.eval — onto the Module during runtime init). Re-executing that script in the same realm is not a supported pattern: closures over the first load's state, calledRun/runtimeInitialized book-keeping, and embind's internal type registries all collide with the second pass, so onRuntimeInitialized never fires and neither does onAbort. The status just sits at "Resetting…" forever.

Two additional bugs compound this, once the engine is in that state:

1. resetEngine() sets btnRun.disabled = true (playground.html:332) with no timeout. If init never completes, the user has no way to recover — not even the "click Run to retry" path advertised by onAbort at line 310 (which also never re-enables the button).
2. scheduleLiveRun() short-circuits on !runtimeReady, so live execution is dead too.

The right fix

Rebuild the ChaiScript WASM with -sMODULARIZE=1 -sEXPORT_NAME=createChaiScriptModule. That wraps everything in a factory:

createChaiScriptModule({ print, printErr, onAbort }).then(instance => { ... });

Then "reset" is just calling the factory again to get a fresh, independent instance — no <script> surgery, no shared globals, no embind re-registration hazard. This is the standard Emscripten pattern for this exact use case. The change belongs in the ChaiScript repo's WASM build flags (not in this repo), since playground/chaiscript.js and playground/chaiscript.wasm are copied in by .github/workflows/update-wasm.yml.

Cheaper alternatives if we can't rebuild quickly

• Iframe isolation. Move the engine into an <iframe> and reload the iframe on reset. Each reload gets a clean JS realm, so the non-modularized script works fine. Heavier but robust, and entirely in this repo.
• Skip reset, reset via engine API. If the ChaiScript WASM bindings expose a way to construct a fresh ChaiScript instance (rather than a singleton Module.eval), call that instead of reloading. Best long-term option but also requires a change in the ChaiScript repo.

Mitigations worth applying regardless

Even after fixing the reset mechanism, the current code has no way out of a stuck state:

• Add a reset timeout (5–10s) that shows an error and re-enables btnRun if neither onRuntimeInitialized nor onAbort fires.
• In onAbort, set btnRun.disabled = false so the "click Run to retry" message is actually actionable.
• The Run button should remain clickable (it already doesn't gate on runtimeReady), but resetEngine() disables it on every call — consider only disabling it while a run is genuinely in flight, not across the whole reload.

Happy to open a PR with the iframe approach as an interim fix if you want something landable today, and file a separate issue in ChaiScript/ChaiScript for the MODULARIZE=1 build flag.

[lefticus]

@leftibot make a new PR that rolls back your last fix and instead just uses the saveState and restoreState features of ChaiScript to reset the state between script runs.

[leftibot]

Before I open this PR I have to flag a blocker: get_state/set_state aren't currently exposed in the playground WASM artifacts, so the JS side has nothing to call.

What the current playground/chaiscript.js + chaiscript.wasm actually expose

playground/chaiscript.js is the non-MODULARIZE glue from gh release download wasm-latest --repo ChaiScript/ChaiScript (per .github/workflows/update-wasm.yml:23). The only embind-registered entry points I can find in playground/chaiscript.wasm are the eval family (eval, evalInt, evalFloat, evalDouble, evalBool, evalString). Searching the binary's string table:

$ strings playground/chaiscript.wasm | grep -iE 'save_state|restore_state|get_state|set_state|get_locals|set_locals'
# (no matches)

The only State-related symbols present are C++-internal (chaiscript::detail::Dispatch_State, mangled template instantiations), not the outer ChaiScript_Basic::State that get_state() returns. So Module.get_state() / Module.set_state(s) simply wouldn't exist at runtime — calling them would throw TypeError: Module.get_state is not a function on every run and the playground would be worse off than before.

What needs to happen in ChaiScript/ChaiScript

For this approach to work, the embind wrapper there (wherever .function("eval", ...) lives) needs to also bind:

• ChaiScript_Basic::get_state → returning an opaque handle
• ChaiScript_Basic::set_state → taking that handle
• The State type itself registered as an opaque class (embind class_<State>("State"))

Since State contains things like m_engine_state / m_type_conversion_state (not trivially copyable through embind), the cleanest route is usually register_value_object or an opaque handle held by val. Happy to open a tracking issue over there.

Proposed path

Two options — tell me which you'd prefer:

1. Block on ChaiScript first. I file an issue on ChaiScript/ChaiScript for the get_state/set_state embind binding. Once the hourly update-wasm.yml pulls the new artifacts, I open the PR here that rolls back Fix #14: Playground is too persistent, errors are not explained #15 and uses Module.get_state() / Module.set_state(saved) around each eval call. This is the cleanest end state but gated on the upstream change.

2. Ship both together. I open the PR on ChaiScript/ChaiScript adding the binding, and open the rollback PR here in draft — landable the moment the new WASM shows up in playground/.

If you want me to proceed with option 2, a rough sketch of the client-side code (for reference — not committed anywhere yet):

let savedState = null;

function runCode() {
  const code = inputEl.value;
  if (!code.trim()) { return; }
  outputEl.innerHTML = '';

  if (savedState === null) {
    savedState = Module.get_state();   // captured once, right after init
  } else {
    Module.set_state(savedState);      // restore clean baseline
  }

  try {
    Module.eval(code);
  } catch (e) {
    appendOutput('Error: ' + formatError(e), 'chai-output-error');
  }
}

That's the full reset mechanism — no <script> surgery, no module reload, no iframe, no resetEngine(). The onAbort + error-formatting mitigations from #15 are still worth keeping as a second line of defense (an unhandled C++ exception can still abort the WASM runtime independent of state); let me know if you'd like me to keep those or drop them entirely as part of the rollback.

Which option do you want?

[lefticus]

@leftibot open an issue on ChaiScript project that provides the features you need.

[leftibot]

Filed: ChaiScript/ChaiScript#693 — Add Emscripten/embind bindings for get_state / set_state (needed for playground state reset).

What the upstream issue asks for

Three new embind functions added to emscripten/chaiscript_em.cpp (currently only the eval family is bound there — confirmed by reading that file and emscripten/chaiscript_eval.hpp on ChaiScript/ChaiScript@develop):

emscripten::function("saveState",    &chaiscript_save_state);
emscripten::function("restoreState", &chaiscript_restore_state);
emscripten::function("releaseState", &chaiscript_release_state);

backed by a small std::unordered_map<int, ChaiScript::State> registry in chaiscript_eval.hpp so JS callers deal in opaque integer handles rather than having to .delete() embind-managed State objects. Alternative (direct class_<State> binding) is laid out in the issue for the maintainer to choose.

Why a registry handle rather than binding State directly

ChaiScript_Basic::State aggregates Engine_State, Type_Conversions::Conversion_Saves, and a Boxed_Value — not trivially round-trippable through embind, and exposing it as a JS object forces .delete() discipline on every caller. A handle is simpler, keeps lifetimes on the C++ side where RAII already handles them, and matches what this playground actually needs (one baseline captured at init, restored on every run).

What happens on this repo's side

Nothing until the binding lands upstream and a new wasm-latest release is cut. At that point .github/workflows/update-wasm.yml pulls the updated playground/chaiscript.js + chaiscript.wasm automatically on its hourly cron, and I open the rollback-#15 PR here using Module.saveState() / Module.restoreState(handle) around each eval.

I'll keep an eye on ChaiScript/ChaiScript#693 and follow up here once there's something to build against.

[lefticus]

@leftibot update this issue based on the new changes in chaiscript

[leftibot]

Update: upstream binding has landed and the artifacts are in this repo as of this morning. Unblocking #14.

What changed

Diffing the WASM symbol tables on either side of today's update-wasm.yml run:

$ git show a0affe1:playground/chaiscript.wasm > /tmp/prev.wasm   # 2026-04-29
$ strings /tmp/prev.wasm | grep -E '^(saveState|restoreState|releaseState)$'
# (no matches)

$ strings playground/chaiscript.wasm | grep -E '^(saveState|restoreState|releaseState)$'   # 2026-05-02 (325a2d8)
saveState
releaseState
restoreState

So ChaiScript/ChaiScript#693 has been merged upstream and the rebuilt artifact landed in playground/chaiscript.wasm via commit 325a2d8. The three new names sit right next to evalInt/evalFloat/etc. in the binary's string table — same shape as the existing embind-registered functions — so they will surface on the Module object once onRuntimeInitialized fires.

What I'll do next

Open the rollback PR I sketched in the 2026-04-17 comment. Concretely, in playground.html:

• Delete resetEngine() (lines 330–343) and the engineScript / pendingCode / firstLoad plumbing that exists only to support <script> re-injection (lines 273–276, 288–298, 318–323, 388–390).
• In onRuntimeInitialized, capture the baseline once: baselineState = Module.saveState();.
• Rewrite runCode() to clear output, Module.restoreState(baselineState), and Module.eval(code) inside the existing try/catch. No reload, no <script> surgery, no iframe.
• Keep the Fix #14: Playground is too persistent, errors are not explained #15 error-formatting layer (formatError, appendOutput('Error: …', 'chai-output-error')) and onAbort handler — an unhandled C++ exception can still abort the runtime independently of state, and we want a visible failure mode if it does. releaseState only matters if we ever stop holding the baseline; for a single long-lived handle there is nothing to release for the page's lifetime.
• scheduleLiveRun() becomes simpler too — runtimeReady only needs to gate the very first run, not every subsequent one, since we no longer tear the engine down.

I'll get that PR up shortly and link it back here.