bmweb-cli 0.1.0

package/runtime/core/ipovm/suspensions.js

@@ -0,0 +1,241 @@
+/**
+ * @file Wire-mode suspensions: which builtins the DRIVEN executor must hand
+ * to the renderer instead of answering itself, and the pending-action shape
+ * each produces. A live actuator (INPA's %STATE loop) parks at a state,
+ * shows a picker, and on the user's pick resumes past the yield into the
+ * job; a live input asks the user; a live job goes on the wire. The
+ * renderer does the async part and calls resume() to continue.
+ */
+
+/**
+ * What a driven run hands back when it cannot continue on its own. `kind`
+ * says why; `out` is the emissions so far (a parked machine's drawn screen
+ * IS the picker).
+ * @typedef {object} IpoStep
+ * @property {'done'|'yield'|'job'|'wait'|'input'|'message'|'toggle'|'print'|'select'|'exit'} kind -
+ *   done: the proc finished; yield: parked at a %STATE; job: a wire job to
+ *   run and feed back; wait: a timed wartezeit; input: an INPA prompt;
+ *   message: a blocking messagebox; toggle: the component picker; print:
+ *   printscreen; select: INPA's line filter; exit: the script ended itself
+ * @property {Emissions} [out] - emissions so far
+ * @property {string} [name] - yield: the state label
+ * @property {string} [job] - job: the job name
+ * @property {string|null} [sgbd] - job: the SGBD the script addressed
+ * @property {string|null} [arg] - job: the argument
+ * @property {number} [ms] - wait: how long
+ * @property {string[]} [prompts] - input: the prompt strings, title first
+ * @property {number} [refs] - input: how many out-refs (fields) it fills
+ * @property {number|null} [lo] - input: accepted range low, when declared
+ * @property {number|null} [hi] - input: accepted range high, when declared
+ * @property {IpoValue[]} [stack] - input/toggle: the call's arguments, kept for the resume store
+ * @property {string} [title] - message: the box title
+ * @property {string|null} [body] - message: the box text
+ * @property {boolean} [multiple] - toggle/select: MultipleSelectFlag
+ * @property {boolean} [argnum] - toggle: ArgNumFlag (line numbers instead of keys)
+ */
+
+/**
+ * The step kinds that park the driven loop until the renderer resumes it.
+ * @type {Set<string>}
+ */
+const IPO_SUSPEND_KINDS = new Set([
+  'file', // the save-as dialog (structures.js ipoDllFileDialog)
+  'job',
+  'wait',
+  'input',
+  'message',
+  'toggle',
+  'pick', // bmweb_pick: the host lists, the user chooses (home script)
+  'print',
+  'select',
+  'exit',
+]);
+
+/** The job builtins whose sends the driven executor hands to the renderer. */
+const IPO_JOB_BUILTINS = new Set([
+  'INPAapiJob',
+  'INP1apiJob',
+  'INPAapiJobData',
+]);
+
+/** delay(ms) -- Inpa.h's name; the disassembler's builtin_1b. */
+const IPO_WAIT_BUILTIN = 'delay';
+
+/** builtin_16 = togglelist. */
+const IPO_TOGGLELIST_BUILTIN = 'builtin_16';
+
+/** The input builtins by name, for the ones the table maps without a name. */
+const IPO_INPUT_NAME_RE = /^input(int|real|hex|string)?$/;
+
+/**
+ * The text of a job argument on the stack: a plain or bound string, or a
+ * number's text; null for anything else.
+ * @param {IpoValue} x - the argument
+ * @returns {string|null}
+ */
+function jobArgText(x) {
+  if (isPlainStr(x)) return x;
+  if (isBound(x)) return x.s;
+  if (typeof x === 'number') return String(x);
+  if (isFloat(x)) return String(x.v);
+  return null;
+}
+
+/**
+ * The 0/1 flag an argument carries (a boxed float, a bound value or a number).
+ * @param {IpoValue} v - the argument
+ * @returns {boolean}
+ */
+function flagArg(v) {
+  return !!(isFloat(v) ? v.v : isBound(v) ? Number(v.s) : Number(v));
+}
+
+/**
+ * INPA's `stop` keyword as the disassembler names it: builtin 0x14.
+ * @type {string}
+ */
+const IPO_STOP_BUILTIN = 'builtin_14';
+
+/**
+ * Builtin dispatch for the resumable path. Identical to `_builtin` EXCEPT
+ * that, in wire mode, the builtins the renderer must answer are not run
+ * offline -- they return a pending action instead. Which jobs must reach the
+ * renderer even when the VM is not driving the wire: the ones that CHANGE
+ * the car, by the write classifier's verdict (token-based, default-deny, the
+ * same one the job route enforces -- not a name prefix: ANSTEUERN_*,
+ * LAMPEN_TEST, SG_RESET are writes too).
+ * @param {IpoVm} vm - the running VM
+ * @param {IpoToken} t - the call token
+ * @param {IpoValue[]} stack - the call's arguments
+ * @returns {IpoStep|null} the pending action, or null when the builtin ran
+ */
+function ipoDriveBuiltin(vm, t, stack) {
+  const name = ipoBuiltinName(t);
+  if (IPO_JOB_BUILTINS.has(name)) {
+    const sgbd = stack.length > 0 ? jobArgText(stack[0]) : null;
+    const job = stack.length > 1 ? jobArgText(stack[1]) : null;
+    const arg = stack.length > 2 ? jobArgText(stack[2]) : null;
+    // classifier absent: never assume safe
+    const isDrive = typeof isWriteJob === 'function' ? isWriteJob(job) : true;
+    if (job && (vm.wireJobs || isDrive)) {
+      // hand the drive to the renderer; it confirms, registers for release,
+      // sends on the wire, and hands the result sets back through resume()
+      return {
+        kind: 'job',
+        job,
+        sgbd: sgbd || null,
+        arg: arg || null,
+        out: vm.out,
+      };
+    }
+  }
+  // input builtins: INPA asks the user and parks until getinputstate says
+  // confirmed. Offline they store '0' -- which a LIVE run must never send
+  // (LLERH's Select would command idle target 0). Suspend instead; the
+  // renderer shows INPA's own prompt and resume() stores the typed value.
+  // inputdigital too: offline it stores the CONFIRMING placeholder (so the
+  // static lift keeps the yes-branch), but live that would answer INPA's
+  // "Are you sure?" for the user -- and IHKA46's compressor-lock key sends
+  // on that answer. Suspend, ask, store what was pressed.
+  if (
+    vm.wireJobs &&
+    (BUILTINS[name] === bInput ||
+      BUILTINS[name] === bInputDigital ||
+      IPO_INPUT_NAME_RE.test(name))
+  ) {
+    const prompts = stack.filter((x) => isPlainStr(x) && x.trim());
+    // bounds may be ints (inputint) or doubles (builtin_40: MS43 pushes
+    // 512.0/1600.0); take the last two numerics either way
+    const nums = stack
+      .map((x) => (isPlainInt(x) ? x : isFloat(x) ? x.v : null))
+      .filter((x) => x != null && Number.isFinite(x));
+    return {
+      kind: 'input',
+      name,
+      prompts,
+      refs: stack.filter(isRef).length,
+      lo: nums.length > 1 ? nums[nums.length - 2] : null,
+      hi: nums.length > 1 ? nums[nums.length - 1] : null,
+      stack,
+      out: vm.out,
+    };
+  }
+  // A LIVE messagebox BLOCKS the script until OK, like INPA's own: the
+  // renderer shows it in sequence and resumes. Offline it is only recorded.
+  if (vm.wireJobs && BUILTINS[name] === bMessage) {
+    vm._builtin(t, stack, null);
+    const M = vm.out.messages;
+    const m = M.length ? M[M.length - 1] : { title: '', body: null };
+    return { kind: 'message', title: m.title, body: m.body, out: vm.out };
+  }
+  // INPA's Select key: select(MultipleSelectFlag) lists the current
+  // screen's named logical lines and shows only the ones picked. Park;
+  // the renderer offers the list and keeps the choice.
+  if (vm.wireJobs && name === 'select') {
+    const flag = stack.length ? stack[0] : 0;
+    return {
+      kind: 'select',
+      multiple: !!(isFloat(flag) ? flag.v : Number(flag)),
+      out: vm.out,
+    };
+  }
+  // INPA's Print key (printscreen): live, the renderer prints the page --
+  // the browser's print dialog stands in for INPA's printer
+  if (vm.wireJobs && name === 'printscreen') {
+    return { kind: 'print', out: vm.out };
+  }
+  // A LIVE togglelist is INPA's component picker: park until the renderer
+  // hands back the pick ({ort, ein}); resume re-runs the builtin with it.
+  // togglelist(MultipleSelectFlag, ArgNumFlag, ->ApiToggleString)
+  if (vm.wireJobs && name === IPO_TOGGLELIST_BUILTIN && vm._pickInput == null) {
+    return {
+      kind: 'toggle',
+      stack,
+      multiple: stack.length > 0 && flagArg(stack[0]),
+      argnum: stack.length > 1 && flagArg(stack[1]),
+      out: vm.out,
+    };
+  }
+  // BMWeb's own picker: bmweb_pick("chassis"|"module"|"vehicle", arg,
+  // ->choice). Park like a togglelist; the renderer asks the host for the
+  // list and resumes with the choice, which the re-run builtin stores.
+  if (vm.wireJobs && name === 'bmweb_pick' && vm._pickInput == null) {
+    const strs = stack.filter((x) => !isRef(x)).map((x) => asStr(x));
+    return {
+      kind: 'pick',
+      stack,
+      what: strs[0] || '',
+      arg: strs[1] || '',
+      out: vm.out,
+    };
+  }
+  if (vm.wireJobs && BUILTINS[name] === bExit) {
+    vm._builtin(t, stack, null);
+    return { kind: 'exit', out: vm.out };
+  }
+  if (vm.wireJobs && IPO_STRUCT_FNS.has(name)) {
+    ipoStructureCall(vm, name, stack);
+    return null;
+  }
+  // wartezeit: offline a noop; a guided run honours it -- the S_ZUHEIZ
+  // Pruefung waits 2000ms after DIAGNOSE_ENDE and 10000ms for the heater's
+  // run-on, and rushing those changes what the ECU answers.
+  if (vm.wireJobs && name === IPO_WAIT_BUILTIN) {
+    const ms = stack.find((x) => isPlainInt(x));
+    return { kind: 'wait', ms: ms != null ? ms : 0, out: vm.out };
+  }
+  // INPA's `stop`: end the body being run (this LINE, this ITEM, this
+  // proc) here. The corpus puts it after an error messagebox ("box, then
+  // stop, else read the results") and at the head of a screen that has
+  // nothing selected yet -- MS45's injector screen guards its STEUERN_EV_n
+  // send with `if (sel == 0) stop`, and falling through sent a job named
+  // after the on-time. Offline it stays a noop (the derived twin's stamp).
+  if (vm.wireJobs && name === IPO_STOP_BUILTIN) return 'stop';
+  // not a drive: run it exactly as the offline builtin would
+  vm._builtin(t, stack, null);
+  return null;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { IPO_SUSPEND_KINDS, ipoDriveBuiltin };
+}

package/runtime/core/ipovm/tape.js

@@ -0,0 +1,206 @@
+/**
+ * @file Static scans over a proc's token tape, used without executing it:
+ * the byte-offset index a jump seeks through, where a proc's decoded tokens
+ * end, the segment re-basing of jump targets past a %STATE label, the
+ * keypress-guard flags an item body tests, and the quit-mode confirmation
+ * box a state machine pops.
+ */
+
+/**
+ * One decoded token of a proc, as tools/export/ipo_exec.py emits it. Only
+ * the fields the VM reads are listed; which ones are present depends on `op`.
+ * @typedef {object} IpoToken
+ * @property {string} op - frame | const | var | procref | store | binop | jfalse |
+ *   jump | ITEM | LINE | call | calluser | dllcall | state | ret | unk | ...
+ * @property {number} [at] - byte offset of the token in the .IPO
+ * @property {string} [t] - a const's pool tag ('s' string, 'i' int, 'd' double, 'b' bool)
+ * @property {*} [v] - a const's value
+ * @property {number} [sc] - a var/store's scope (absent = GLOBAL)
+ * @property {number} [n] - a var/store's slot, a procref/calluser's id, a call's builtin number
+ * @property {boolean} [ref] - a store through a by-reference parameter
+ * @property {number} [kind] - a procref's kind (see IPO_REF_*)
+ * @property {string} [name] - a binop's operator or a call's builtin name
+ * @property {number} [to] - a jump's target byte offset
+ * @property {number} [nr] - an ITEM's F-key number
+ * @property {string} [label] - an ITEM's caption or a LINE's name
+ * @property {string} [keys] - a LINE's component key string (for the picker)
+ */
+
+/**
+ * The {byteOffset -> tokenIndex} index of a proc, so a resolved jump target is
+ * a seek.
+ * @param {IpoToken[]} toks - the proc's tokens
+ * @returns {Map<number, number>}
+ */
+function ipoByteIndex(toks) {
+  const index = new Map();
+  for (let i = 0; i < toks.length; i++) {
+    if (toks[i].at != null) index.set(toks[i].at, i);
+  }
+  return index;
+}
+
+/**
+ * Where a proc's decoded tokens end: the first undecoded byte. A proc's block
+ * header sizes only its own section, so garbage past the real end (unk
+ * tokens) would spin.
+ * @param {IpoToken[]} toks - the proc's tokens
+ * @returns {number} token index of the first `unk`, or toks.length
+ */
+function ipoProcEnd(toks) {
+  for (let j = 0; j < toks.length; j++) {
+    if (toks[j].op === 'unk') return j;
+  }
+  return toks.length;
+}
+
+/**
+ * JUMP TARGETS PAST A STATE ARE SEGMENT-RELATIVE. The compiler emits a jump's
+ * u16 as a dword index from its enclosing BLOCK -- the proc body, an
+ * ITEM/LINE body, or (the part the walker does not model) a %STATE segment:
+ * each state label opens a new block whose dwords count from the token after
+ * the state's own exit jump (the body the driven resume enters).
+ *
+ * The walker resolves every target against the proc/ITEM base, so a target
+ * inside a state segment lands short by the states' label bytes -- across the
+ * corpus only 41% of intra-segment jumps hit a real token that way, while
+ * re-basing per segment resolves 95.8% (and S_ZUHEIZ's Pruefung becomes
+ * semantically exact: the measure loop's jfalse skips ONE store, the Weiter
+ * guard exits to the %ENDE block). Offline execution never runs past the
+ * first state (it halts there), so only the DRIVEN path needs this; the
+ * offline executor stays byte-identical to ipo_vm.py.
+ *
+ * A corrected target may land ON a `state` token: that is a generic park
+ * (the current machine segment is what setstatemachine last set), which the
+ * driven loop's yield handling already provides.
+ * @param {IpoToken[]} toks - the proc's tokens
+ * @returns {Map<number, number>} jump token index -> re-based target byte offset
+ */
+function ipoSegRemap(toks) {
+  const remap = new Map();
+  if (!toks.length || toks[0].at == null) return remap;
+  const at = (i) => toks[i].at;
+  let walker = at(0) + 4; // dword 0 of the proc's own block
+  let seg = walker;
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (t.op === 'ITEM' || t.op === 'LINE') {
+      const nxt = i + 1 < toks.length ? at(i + 1) : at(i) + 4;
+      walker = nxt;
+      seg = nxt;
+    } else if (t.op === 'state') {
+      let j = i + 1;
+      if (j < toks.length && toks[j].op === 'jump') j += 1; // exit edge
+      seg = j < toks.length ? at(j) : at(i);
+    } else if (t.to != null) {
+      const u16 = t.to - walker;
+      if (u16 >= 0 && u16 % 4 === 0 && seg !== walker) {
+        remap.set(i, seg + u16);
+      }
+    }
+  }
+  return remap;
+}
+
+/**
+ * Global slots an item body gates its whole action on -- keypress flags.
+ * INPA wraps a key's action in `if flag == 1 ...`; pressing the key means the
+ * flag is true, so run_item must force it -- but ONLY a guard flag (a GLOBAL
+ * compared by `eq` feeding a `jfalse`, before the body stores anything),
+ * never a global read as real data. Ported from ipo_vm.py _keypress_guards.
+ * @param {IpoToken[]} toks - the menu proc's tokens
+ * @param {number} start - first token index of the body
+ * @param {number} end - token index the body ends at (exclusive)
+ * @param {{numericOnly?: boolean}} [opts] - numericOnly: a slot compared
+ *   against a STRING ("ON") is state the body keeps, not a flag -- a preset
+ *   of 1 can never satisfy that compare and only destroys the value (the
+ *   live item VM's concern; the offline derivation keeps the Python twin's
+ *   exact behaviour)
+ * @returns {Set<number>} the guard flags' global slot numbers
+ */
+function keypressGuards(toks, start, end, opts = {}) {
+  const guards = new Set(),
+    stored = new Set();
+  const lim = Math.min(end, toks.length);
+  for (let k = start; k < lim; k++) {
+    const t = toks[k],
+      op = t.op;
+    if (op === 'store' && (t.sc == null ? GLOBAL : t.sc) === GLOBAL) {
+      stored.add(t.n);
+    }
+    if (
+      op === 'var' &&
+      (t.sc == null ? GLOBAL : t.sc) === GLOBAL &&
+      !stored.has(t.n)
+    ) {
+      const b = k + 1 < end ? toks[k + 1] : {};
+      const c = k + 2 < end ? toks[k + 2] : {};
+      if (
+        opts.numericOnly &&
+        b.op === 'const' &&
+        b.t === 's' &&
+        !/^-?\d+$/.test(String(b.v).trim())
+      )
+        continue;
+      if (b.op === 'const' && c.op === 'binop' && c.name === 'eq') {
+        let gated = false;
+        for (let j = k + 3; j < Math.min(k + 6, end); j++) {
+          if (toks[j].op === 'jfalse') {
+            gated = true;
+            break;
+          }
+        }
+        if (gated) guards.add(t.n);
+      }
+    }
+  }
+  return guards;
+}
+
+/**
+ * The quit-mode confirmation a machine pops after a successful drive:
+ *     if (slotN == 1) messagebox(title, prefix + <ORT>)
+ * (ZKE5 sm_steuern: slot 29 = the "with Quitting" toggle, box "ACTIVATED
+ * DIGITAL VALUE / Signal : <ORT>"). Scanned from the bytecode so the slot and
+ * the words are INPA's own, never invented.
+ * @param {IpoToken[]} toks - the state machine's tokens
+ * @returns {{slot: number, title: string, prefix: string}|null} null when
+ *   the machine has no such box
+ */
+function scanQuitBox(toks) {
+  if (!Array.isArray(toks)) return null;
+  for (let i = 0; i + 4 < toks.length; i++) {
+    const a = toks[i],
+      b = toks[i + 1],
+      c = toks[i + 2];
+    if (a.op !== 'var' || b.op !== 'const' || b.v !== 1) continue;
+    if (c.op !== 'binop' || c.name !== 'eq') continue;
+    // guarded body within reach: frame, const title, const prefix, ...,
+    // call messagebox
+    for (let j = i + 3; j < Math.min(i + 14, toks.length); j++) {
+      const t = toks[j];
+      if (t.op === 'call' && t.name === 'messagebox') {
+        const strs = [];
+        for (let k = i + 3; k < j; k++) {
+          if (toks[k].op === 'const' && toks[k].t === 's') strs.push(toks[k].v);
+        }
+        if (strs.length >= 2) {
+          return { slot: a.n, title: strs[0], prefix: strs[1] };
+        }
+        break;
+      }
+      if (t.op === 'state' || t.op === 'jump') break;
+    }
+  }
+  return null;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    ipoByteIndex,
+    ipoProcEnd,
+    ipoSegRemap,
+    keypressGuards,
+    scanQuitBox,
+  };
+}

package/runtime/core/ipovm/values.js

@@ -0,0 +1,241 @@
+/**
+ * @file The .IPO virtual machine's value model: the boxes a VM value travels
+ * in, the predicates that tell them apart, and the two errors the executor
+ * throws.
+ *
+ * The VM (core/ipovm/vm.js) EXECUTES .IPO screen/menu programs in the
+ * browser. It is the JS twin of tools/decompile/ipo_vm.py: it runs the same
+ * decoded token tape (tools/export/ipo_exec.py output: {procs, byid, pool},
+ * a derivation of the .IPO with constants inlined and jumps resolved to byte
+ * offsets) and produces the same emissions (drawn lines, menu items, jobs,
+ * dialogs), so screens can be executed rather than frozen.
+ *
+ * THE MODEL, ported from ipo_vm.py (not bestvm.js -- BEST2 is a byte-register
+ * machine; .IPO is a STACK machine):
+ *   - a per-call-frame operand stack; `frame` (0x0f) clears it, a call
+ *     consumes it. Scope 0 = script globals, 2/3 = the frame's own slots.
+ *   - jumps are token seeks: t.to is a byte offset, resolved through a
+ *     {byteOffset -> tokenIndex} index built per proc.
+ *   - builtins take an OUT-PARAMETER (a procref on the stack), never return a
+ *     value -- INPAapiResultInt(->dest, KEY, i), inttostring(src, ->dest).
+ *   - host interaction (job results, dialog state) is injected, like
+ *     bestvm's `send`. The default OkHost answers offline; production swaps
+ *     in a live host.
+ *
+ * VALUE IDENTITY. A drawn value must remember which result KEY filled it so
+ * the poller can refresh it live; a scaled/concatenated value must keep that
+ * key through the arithmetic. ipo_vm.py carries this on _Bound (a str
+ * subclass) and _Slot; JS has no str subclass, so values that carry identity
+ * are boxed as {__bound:true, ...} / {__slot:true, ...}. Bare strings/ints
+ * stay bare, so `typeof x === 'string'` still tests "a plain literal".
+ */
+
+/**
+ * Variable scope of a `var`/`store` token: 0 = script globals. (The other
+ * scopes, 2 and 3, are the current frame's own slots -- see LOCAL.)
+ * @type {number}
+ */
+const GLOBAL = 0;
+/**
+ * Variable scope of a frame-local slot (scope 3 is treated the same by
+ * mkSlot: only "global or not" matters to a slot's identity).
+ * @type {number}
+ */
+const LOCAL = 2;
+
+/**
+ * Procref kinds pushed by a `procref` token: what the reference names.
+ * A local ref (IPO_REF_LOCAL) remembers the frame it was taken in; the
+ * others are indices into the exec's `byid` table by type.
+ */
+const IPO_REF_LOCAL = 2;
+const IPO_REF_SCREEN = 64;
+const IPO_REF_MENU = 65;
+const IPO_REF_STATE = 66;
+const IPO_REF_STATE_ALT = 67;
+
+/**
+ * An unset slot: reads as empty text but still names its slot, so a later
+ * draw can look up the Result* key bound to it. Mirrors ipo_vm.py's _Slot.
+ * @typedef {object} IpoSlot
+ * @property {true} __slot - box tag
+ * @property {number} sc - scope, GLOBAL or LOCAL
+ * @property {number} n - slot number
+ */
+
+/**
+ * Text that remembers where it came from. Mirrors ipo_vm.py's _Bound (a str
+ * subclass); here it is a box and the display text is `s`.
+ * @typedef {object} IpoBound
+ * @property {true} __bound - box tag
+ * @property {string} s - the text
+ * @property {IpoSlot|null} slot - the slot it was built from
+ * @property {string|null} key - the Result* key bound to it
+ * @property {string[]} extra - other keys folded into it by concatenation
+ * @property {Record<string, string>|null} amap - a lookup table it came from
+ *   (StrArrayRead), so a painter can map the value to a caption
+ */
+
+/**
+ * A FLOAT, boxed. JS has one number type, but INPA distinguishes int from
+ * real and several builtins select arguments BY TYPE: analogout takes the
+ * first two *ints* as (row, col) and reads its min/max/warn bounds from the
+ * *floats* after them. An unboxed 120.0 is Number.isInteger-true and would
+ * be misread as a col. Pool doubles (tag 'd') are boxed so the int/float
+ * split survives; every numeric helper unwraps them.
+ * @typedef {object} IpoFloat
+ * @property {true} __float - box tag
+ * @property {number} v - the value
+ */
+
+/**
+ * A procref on the stack: ['ref', kind, n, ownerFrame]. A local ref (kind
+ * IPO_REF_LOCAL) remembers the frame it was taken in, so a callee writing
+ * through its by-reference parameter lands in the CALLER's slot, not its own.
+ * @typedef {['ref', number, number, (Map<number, IpoValue>|null)]} IpoRef
+ */
+
+/**
+ * Anything a VM slot or stack cell can hold.
+ * @typedef {string|number|boolean|null|IpoSlot|IpoBound|IpoFloat|IpoRef} IpoValue
+ */
+
+/** A malformed program or a missing proc: the caller's mistake, not a halt. */
+class IpoError extends Error {}
+
+/**
+ * Control-flow stop thrown by the offline executor: a `state` yield, or the
+ * step budget. Never an error -- run() swallows it and returns the emissions.
+ */
+class Halt extends Error {}
+
+// ---------------------------------------------------------------- boxes --
+
+/**
+ * Box an unset slot so its identity survives until a draw looks it up.
+ * @param {number} sc - scope of the slot
+ * @param {number} n - slot number
+ * @returns {IpoSlot}
+ */
+function mkSlot(sc, n) {
+  return { __slot: true, sc: sc === LOCAL ? LOCAL : GLOBAL, n };
+}
+
+/**
+ * Is x an unset-slot box?
+ * @param {IpoValue} x - any VM value
+ * @returns {x is IpoSlot}
+ */
+function isSlot(x) {
+  return x != null && x.__slot === true;
+}
+
+/**
+ * Box text that carries its origin.
+ * @param {IpoSlot|null|undefined} slot - the slot it was built from
+ * @param {*} text - display text (stringified; null reads as '')
+ * @param {string|null|undefined} key - the Result* key bound to it
+ * @returns {IpoBound}
+ */
+function mkBound(slot, text, key) {
+  return {
+    __bound: true,
+    s: text == null ? '' : String(text),
+    slot: slot || null,
+    key: key || null,
+    extra: [],
+    amap: null,
+  };
+}
+
+/**
+ * Is x a bound-text box?
+ * @param {IpoValue} x - any VM value
+ * @returns {x is IpoBound}
+ */
+function isBound(x) {
+  return x != null && x.__bound === true;
+}
+
+/**
+ * str(x): the display text of any VM value. A slot reads '', a bound value
+ * its text, a boxed float its number.
+ * @param {IpoValue} x - any VM value
+ * @returns {string}
+ */
+function asStr(x) {
+  if (x == null) return '';
+  if (isBound(x)) return x.s;
+  if (isSlot(x)) return '';
+  if (isFloat(x)) return String(x.v);
+  return String(x);
+}
+
+/**
+ * Is x a plain string literal (not a bound box, not a slot)?
+ * @param {IpoValue} x - any VM value
+ * @returns {x is string}
+ */
+function isPlainStr(x) {
+  return typeof x === 'string';
+}
+
+/**
+ * Is x a plain integer (an unboxed whole number)?
+ * @param {IpoValue} x - any VM value
+ * @returns {x is number}
+ */
+function isPlainInt(x) {
+  return typeof x === 'number' && Number.isInteger(x);
+}
+
+/**
+ * Is x a procref pushed on the stack?
+ * @param {IpoValue} x - any VM value
+ * @returns {x is IpoRef}
+ */
+function isRef(x) {
+  return Array.isArray(x) && x.length >= 3 && x[0] === 'ref';
+}
+
+/**
+ * Box a real so it keeps its float identity (see IpoFloat).
+ * @param {number} v - the value
+ * @returns {IpoFloat}
+ */
+function mkFloat(v) {
+  return { __float: true, v };
+}
+
+/**
+ * Is x a boxed float?
+ * @param {IpoValue} x - any VM value
+ * @returns {x is IpoFloat}
+ */
+function isFloat(x) {
+  return x != null && x.__float === true;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    GLOBAL,
+    LOCAL,
+    IPO_REF_LOCAL,
+    IPO_REF_SCREEN,
+    IPO_REF_MENU,
+    IPO_REF_STATE,
+    IPO_REF_STATE_ALT,
+    IpoError,
+    Halt,
+    mkSlot,
+    isSlot,
+    mkBound,
+    isBound,
+    asStr,
+    isPlainStr,
+    isPlainInt,
+    isRef,
+    mkFloat,
+    isFloat,
+  };
+}