qubasic 0.5.0__tar.gz → 0.6.0__tar.gz

{qubasic-0.5.0 → qubasic-0.6.0}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.6.0 (2026-06-18)
+
+Correctness, scalability, and usability pass (61 fixes).
+
+### Fixed
+- **Time-travel debugging now works**: STEP records statevector checkpoints, so REWIND/FORWARD/HISTORY operate (previously `_checkpoint_sv` was never called).
+- **TRON, breakpoints, ON TIMER, ON MEASURE now fire**: the debug hooks are wired into the execution loop instead of being dead code.
+- **PLOT and ANIMATE sweep correctly**: the transpiled-circuit cache key now includes variable bindings, so parameter sweeps no longer reuse the first circuit.
+- **`$XXXX` memory addresses parse**: PEEK/POKE/DUMP/SYS/WAIT accept the canonical hex-address notation, not only `0x`/decimal/`&H`.
+- **Multi-line IF/ELSE/END IF**: the untaken branch is properly skipped (previously both branches ran).
+- **ON ERROR** reports the real ERR/ERL for build-path errors and runs handler lines through the program executor (no spurious state dumps).
+- **OPTION BASE 1** is honored in array indexing; FOR with STEP 0 is rejected; bare `NEXT` and `NEXT i, j` are supported.
+- **CSV/EXPORT** report correctly when only a statevector (no counts) is present.
+
+### Performance / scalability
+- Stabilizer is chosen before MPS for large Clifford circuits, and the full 2^n statevector is no longer rebuilt after every measured run (a 30-qubit GHZ went from ~16s to <1s).
+- STEP evolves the statevector incrementally; DENSITY and EXPECT avoid building large matrices; HEATMAP and STATS reuse work.
+
+### Quantum / LOCC
+- LOCC depolarizing noise matches the Qiskit Aer convention; amplitude- and phase-damping channels are now simulated in the LOCC engine.
+- EXPECT/ENTROPY/DENSITY/BLOCH accept a register argument in SPLIT mode; `LOCC SHOTCAP` replaces the magic shot-cap variable; SEND prefix/suffix optimization detects all control transfers.
+- Per-qubit memory-mapped noise applies to multi-qubit gates; complex single-qubit amplitudes are exposed in the qubit-state block; POKE-driven state preparation is applied at build.
+
+### Language / interface
+- User-defined TYPE record fields can be read and assigned (`p.x`); ELSEIF chains and re-parsed clauses are memoized.
+- SAVE/LOAD round-trip noise, seed, screen mode, DEF FN, and TYPE definitions; CHAIN/MERGE/INCLUDE/IMPORT honor a `QUBASIC_PATH` search path; IMPORT no longer pollutes SAVE output.
+- CLI gains `--version` and `--agent`; `--json` output is enriched (statevector, variables, manifest) and emits structured errors; the agent write-sandbox engages under `--json`/`--agent`.
+- `SET_STATE` persists into the next RUN and warns when a named state cannot fit; per-command `HELP <name>`; dependency-version warnings are suppressed before the banner.
+
 ## 0.5.0 (2026-03-30)
 
 - **Colorized histograms**: bars colored green/yellow/dim by probability in terminal

{qubasic-0.5.0/qubasic.egg-info → qubasic-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.5.0
+Version: 0.6.0
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT
@@ -468,15 +468,9 @@ BLOCH A 0                Bloch sphere for register A, qubit 0
 LOCCINFO                 Protocol metrics
 ```
 
-SPLIT: max capacity (31+31+...), no cross-register entanglement. Use SEND/IF for classical coordination.
+SPLIT: max capacity (up to 33 qubits per register), no cross-register entanglement. Use SEND/IF for classical coordination.
 
-JOINT: shared entanglement via SHARE. Limited to ~32 total qubits.
-
-### Network LOCC
-```
-CONNECT "host:port" AS C   Attach remote register (local simulation stand-in)
-DISCONNECT C               Detach
-```
+JOINT: shared entanglement via SHARE. Limited to 33 total qubits.
 
 ### LOCC optimization
 Programs with SEND execute the deterministic prefix (before first SEND) once, snapshot the statevector, then re-execute only the suffix per shot. Complexity: O(prefix + shots * suffix) instead of O(shots * total).
@@ -737,7 +731,7 @@ qubasic_core/
   mock_backend.py        MockAerSimulator for fast testing
 ```
 
-`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 16 mixins. `Engine` can be used independently for headless/agent execution.
+`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 20 mixins. Execution methods live on `QBasicTerminal`, so headless/agent use should instantiate `QBasicTerminal` (the `Engine` base is a state container only).
 
 ## License
 

{qubasic-0.5.0 → qubasic-0.6.0}/README.md

@@ -435,15 +435,9 @@ BLOCH A 0                Bloch sphere for register A, qubit 0
 LOCCINFO                 Protocol metrics
 ```
 
-SPLIT: max capacity (31+31+...), no cross-register entanglement. Use SEND/IF for classical coordination.
+SPLIT: max capacity (up to 33 qubits per register), no cross-register entanglement. Use SEND/IF for classical coordination.
 
-JOINT: shared entanglement via SHARE. Limited to ~32 total qubits.
-
-### Network LOCC
-```
-CONNECT "host:port" AS C   Attach remote register (local simulation stand-in)
-DISCONNECT C               Detach
-```
+JOINT: shared entanglement via SHARE. Limited to 33 total qubits.
 
 ### LOCC optimization
 Programs with SEND execute the deterministic prefix (before first SEND) once, snapshot the statevector, then re-execute only the suffix per shot. Complexity: O(prefix + shots * suffix) instead of O(shots * total).
@@ -704,7 +698,7 @@ qubasic_core/
   mock_backend.py        MockAerSimulator for fast testing
 ```
 
-`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 16 mixins. `Engine` can be used independently for headless/agent execution.
+`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 20 mixins. Execution methods live on `QBasicTerminal`, so headless/agent use should instantiate `QBasicTerminal` (the `Engine` base is a state container only).
 
 ## License
 

{qubasic-0.5.0 → qubasic-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qubasic"
-version = "0.5.0"
+version = "0.6.0"
 description = "Quantum BASIC Interactive Terminal"
 readme = "README.md"
 requires-python = ">=3.10"

{qubasic-0.5.0 → qubasic-0.6.0/qubasic.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.5.0
+Version: 0.6.0
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT
@@ -468,15 +468,9 @@ BLOCH A 0                Bloch sphere for register A, qubit 0
 LOCCINFO                 Protocol metrics
 ```
 
-SPLIT: max capacity (31+31+...), no cross-register entanglement. Use SEND/IF for classical coordination.
+SPLIT: max capacity (up to 33 qubits per register), no cross-register entanglement. Use SEND/IF for classical coordination.
 
-JOINT: shared entanglement via SHARE. Limited to ~32 total qubits.
-
-### Network LOCC
-```
-CONNECT "host:port" AS C   Attach remote register (local simulation stand-in)
-DISCONNECT C               Detach
-```
+JOINT: shared entanglement via SHARE. Limited to 33 total qubits.
 
 ### LOCC optimization
 Programs with SEND execute the deterministic prefix (before first SEND) once, snapshot the statevector, then re-execute only the suffix per shot. Complexity: O(prefix + shots * suffix) instead of O(shots * total).
@@ -737,7 +731,7 @@ qubasic_core/
   mock_backend.py        MockAerSimulator for fast testing
 ```
 
-`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 16 mixins. `Engine` can be used independently for headless/agent execution.
+`Engine` holds all program state. `QBasicTerminal` inherits `Engine` + 20 mixins. Execution methods live on `QBasicTerminal`, so headless/agent use should instantiate `QBasicTerminal` (the `Engine` base is a state container only).
 
 ## License
 

{qubasic-0.5.0 → qubasic-0.6.0}/qubasic.py

@@ -50,14 +50,15 @@ def main():
     import json as _json
     os.environ.setdefault('PYTHONIOENCODING', 'utf-8')
 
+    from qubasic_core import __version__
+
     args = sys.argv[1:]
     quiet = '--quiet' in args or '-q' in args
     json_mode = '--json' in args
+    agent_mode = '--agent' in args
     seed_val = None
-    if quiet:
-        args = [a for a in args if a not in ('--quiet', '-q')]
-    if json_mode:
-        args = [a for a in args if a != '--json']
+    for flag in ('--quiet', '-q', '--json', '--agent'):
+        args = [a for a in args if a != flag]
     # Parse --seed N
     filtered = []
     i = 0
@@ -70,8 +71,11 @@ def main():
             i += 1
     args = filtered
 
+    if any(a in ('-v', '--version') for a in args):
+        print(f"QUBASIC {__version__}")
+        sys.exit(0)
+
     if any(a in ('-h', '--help') for a in args):
-        from qubasic_core import __version__
         print(f"QUBASIC {__version__} — Quantum BASIC Interactive Terminal")
         print()
         print("Usage:")
@@ -79,13 +83,17 @@ def main():
         print("  qubasic script.qb        Run a script file")
         print("  qubasic --quiet script    Suppress banner and progress")
         print("  qubasic --json script     Output results as JSON")
+        print("  qubasic --agent script    Confine file writes to the working dir")
         print("  qubasic --seed N script   Set random seed for reproducibility")
+        print("  qubasic --version         Show version")
         print("  qubasic --help            Show this help")
         print()
         print("Type HELP inside the REPL for full command reference.")
         sys.exit(0)
 
     term = QBasicTerminal()
+    # JSON mode implies agent use, so confine file writes to the working dir.
+    term.agent_mode = agent_mode or json_mode
     if seed_val is not None:
         import numpy as _np
         term._seed = seed_val
@@ -93,35 +101,41 @@ def main():
 
     if args:
         path = args[0]
-        if os.path.isfile(path):
-            if quiet or json_mode:
-                import io
-                buf = io.StringIO()
-                old = sys.stdout
-                sys.stdout = buf
-                try:
-                    run_script(path, term)
-                finally:
-                    sys.stdout = old
-                if json_mode:
-                    result = {
-                        'counts': term.last_counts or {},
-                        'num_qubits': term.num_qubits,
-                        'shots': term.shots,
-                    }
-                    print(_json.dumps(result, indent=2))
-                elif not quiet:
-                    print(buf.getvalue())
+        if not os.path.isfile(path):
+            if json_mode:
+                print(_json.dumps({'error': f'FILE NOT FOUND: {path}'}, indent=2))
             else:
-                term.print_banner()
+                print(f"?FILE NOT FOUND: {path}")
+            sys.exit(1)
+        if quiet or json_mode:
+            import io
+            buf = io.StringIO()
+            old = sys.stdout
+            sys.stdout = buf
+            err = None
+            try:
                 run_script(path, term)
-            # Exit code: 0 if results exist, 1 if error
-            sys.exit(0 if term.last_counts is not None or not any(
-                term.program.get(ln, '').strip().upper() == 'MEASURE'
-                for ln in term.program) else 1)
+            except Exception as e:  # surface as structured error in JSON mode
+                err = str(e)
+            finally:
+                sys.stdout = old
+            if json_mode:
+                if err is not None:
+                    print(_json.dumps({'error': err}, indent=2))
+                    sys.exit(1)
+                print(_json.dumps(term.result(), indent=2))
+            elif not quiet:
+                print(buf.getvalue())
+                if err is not None:
+                    print(f"?ERROR: {err}")
+                    sys.exit(1)
         else:
-            print(f"?FILE NOT FOUND: {path}")
-            sys.exit(1)
+            term.print_banner()
+            run_script(path, term)
+        # Exit 0 on success; 1 if a measured program produced no counts.
+        sys.exit(0 if term.last_counts is not None or not any(
+            term.program.get(ln, '').strip().upper() == 'MEASURE'
+            for ln in term.program) else 1)
     else:
         term.repl()
 

{qubasic-0.5.0 → qubasic-0.6.0}/qubasic_core/__init__.py

@@ -28,7 +28,7 @@ __all__ = [
     'GATE_TABLE', 'GATE_ALIASES',
 ]
 
-__version__ = '0.5.0'
+__version__ = '0.6.0'
 
 def __getattr__(name):
     """Lazy import heavy modules on first access."""

{qubasic-0.5.0 → qubasic-0.6.0}/qubasic_core/analysis.py

@@ -22,24 +22,48 @@ class AnalysisMixin:
     self.locc, self.locc_mode.
     """
 
+    def _resolve_analysis_target(self, rest: str):
+        """Return (sv, n_qubits, remaining_rest) for a state-analysis command.
+
+        In LOCC SPLIT mode a leading register letter selects that register
+        (e.g. ``EXPECT A Z 0``); otherwise the active statevector is used.
+        """
+        parts = rest.split()
+        if self.locc_mode and self.locc and not self.locc.joint and parts:
+            cand = parts[0].upper()
+            if cand in self.locc.names:
+                sv, n = self._active_sv_for_reg(cand)
+                return sv, n, ' '.join(parts[1:])
+        return self._active_sv, self._active_nqubits, rest
+
     def cmd_expect(self, rest: str) -> None:
-        """EXPECT <pauli> [qubits] — compute expectation value.
-        Examples: EXPECT Z 0, EXPECT ZZ 0 1, EXPECT X 0"""
-        sv = self._active_sv
+        """EXPECT [reg] <pauli> [qubits] — compute expectation value.
+        Examples: EXPECT Z 0, EXPECT ZZ 0 1, EXPECT A Z 0 (SPLIT register A)"""
+        sv, n, rest = self._resolve_analysis_target(rest)
         if sv is None:
             if self.locc_mode and self.locc and not self.locc.joint:
-                self.io.writeln("?SPLIT mode: use STATE A / STATE B for per-register inspection")
+                self.io.writeln("?SPLIT mode: prefix a register, e.g. EXPECT A Z 0")
             else:
                 self.io.writeln("?NO STATE — RUN first")
             return
         parts = rest.split()
         if not parts:
-            self.io.writeln("?USAGE: EXPECT <Z|X|Y|ZZ|...> [qubits]")
+            self.io.writeln("?USAGE: EXPECT [reg] <Z|X|Y|ZZ|...> [qubits]")
             return
         pauli_str = parts[0].upper()
         qubits = [int(q) for q in parts[1:]] if len(parts) > 1 else list(range(len(pauli_str)))
-
-        n = self._active_nqubits
+        # Fast numpy path for diagonal (Z/I-only) observables — no qiskit copy.
+        if set(pauli_str) <= {'Z', 'I'}:
+            svf = np.ascontiguousarray(sv).ravel()
+            probs = np.abs(svf) ** 2
+            idx = np.arange(svf.size)
+            sign = np.ones(svf.size)
+            for i, p in enumerate(pauli_str):
+                if p == 'Z' and i < len(qubits):
+                    sign = sign * np.where(((idx >> qubits[i]) & 1) == 1, -1.0, 1.0)
+            val = float(np.sum(probs * sign))
+            self.io.writeln(f"  <{pauli_str}> on qubits {qubits} = {val:.6f}")
+            return
         try:
             from qiskit.quantum_info import Statevector, SparsePauliOp
             sv_q = Statevector(np.ascontiguousarray(sv).ravel())
@@ -54,17 +78,19 @@ class AnalysisMixin:
             self.io.writeln(f"?EXPECT ERROR: {e}")
 
     def cmd_entropy(self, rest: str = '') -> None:
-        """ENTROPY [qubits] — entanglement entropy of specified qubits vs rest.
-        Examples: ENTROPY 0  |  ENTROPY 0 1  |  ENTROPY (defaults to qubit 0)"""
-        sv = self._active_sv
+        """ENTROPY [reg] [qubits] — entanglement entropy of qubits vs rest.
+        Examples: ENTROPY 0 | ENTROPY 0 1 | ENTROPY A 0 (SPLIT register A)"""
+        sv, n, rest = self._resolve_analysis_target(rest)
         if sv is None:
-            self.io.writeln("?NO STATE — RUN first")
+            if self.locc_mode and self.locc and not self.locc.joint:
+                self.io.writeln("?SPLIT mode: prefix a register, e.g. ENTROPY A 0")
+            else:
+                self.io.writeln("?NO STATE — RUN first")
             return
         if rest.strip():
             partition_a = [int(q) for q in rest.replace(',', ' ').split() if q.strip()]
         else:
             partition_a = [0]
-        n = self._active_nqubits
         try:
             from qiskit.quantum_info import Statevector, entropy, partial_trace
             sv_obj = Statevector(np.ascontiguousarray(sv).ravel())
@@ -81,25 +107,27 @@ class AnalysisMixin:
         except Exception as e:
             self.io.writeln(f"?ENTROPY ERROR: {e}")
 
-    def cmd_density(self) -> None:
-        """Show density matrix (or partial trace for small systems)."""
-        sv = self._active_sv
+    def cmd_density(self, rest: str = '') -> None:
+        """Show density matrix (DENSITY [reg]); summarizes for large systems."""
+        sv, n, rest = self._resolve_analysis_target(rest)
         if sv is None:
-            self.io.writeln("?NO STATE — RUN first")
+            if self.locc_mode and self.locc and not self.locc.joint:
+                self.io.writeln("?SPLIT mode: prefix a register, e.g. DENSITY A")
+            else:
+                self.io.writeln("?NO STATE — RUN first")
             return
         sv = np.ascontiguousarray(sv).ravel()
-        rho = np.outer(sv, sv.conj())
-        n = self._active_nqubits
         dim = 2**n
         if dim > 16:
+            # |psi><psi| is rank-1, so purity is ||psi||^4 and the von Neumann
+            # entropy is 0; report directly instead of building a 2^n x 2^n matrix.
+            norm2 = float(np.vdot(sv, sv).real)
             self.io.writeln(f"  Density matrix: {dim}x{dim} (too large to display)")
-            self.io.writeln(f"  Purity: {np.real(np.trace(rho @ rho)):.6f}")
-            self.io.write(f"  Von Neumann entropy: ")
-            eigvals = np.linalg.eigvalsh(rho)
-            eigvals = eigvals[eigvals > 1e-15]
-            ent = -np.sum(eigvals * np.log2(eigvals))
-            self.io.writeln(f"{ent:.6f} bits")
+            self.io.writeln(f"  Pure state |psi><psi|: purity {norm2 ** 2:.6f}")
+            self.io.writeln(f"  Von Neumann entropy: 0.000000 bits")
+            self.io.writeln(f"  (use ENTROPY <qubits> for reduced-state entanglement)")
             return
+        rho = np.outer(sv, sv.conj())
         self.io.writeln(f"\n  Density matrix ({dim}x{dim}):\n")
         for i in range(dim):
             row = []

{qubasic-0.5.0 → qubasic-0.6.0}/qubasic_core/control_flow.py

@@ -15,7 +15,7 @@ from qubasic_core.statements import (
     LetArrayStmt, LetStmt, PrintStmt, GotoStmt, GosubStmt,
     ForStmt, NextStmt, WhileStmt, IfThenStmt,
     DataStmt, ReadStmt, OnGotoStmt, OnGosubStmt,
-    SelectCaseStmt, CaseStmt, EndSelectStmt,
+    SelectCaseStmt, CaseStmt, EndSelectStmt, ElseStmt, EndIfStmt,
     DoStmt, LoopStmt, ExitStmt,
     SwapStmt, DefFnStmt, OptionBaseStmt,
     SubStmt, EndSubStmt, FunctionStmt, EndFunctionStmt, CallStmt,
@@ -43,8 +43,11 @@ class ControlFlowMixin:
     def _cf_let_array(self, stmt: str, run_vars: dict[str, Any],
                       parsed: LetArrayStmt) -> tuple[bool, ExecOutcome]:
         name, idx_expr, val_expr = parsed.name, parsed.index_expr, parsed.value_expr
-        idx = int(self._eval_with_vars(idx_expr, run_vars))
+        base = getattr(self, '_option_base', 0)
+        idx = int(self._eval_with_vars(idx_expr, run_vars)) - base
         val = self._eval_with_vars(val_expr, run_vars)
+        if idx < 0:
+            raise RuntimeError(f"ARRAY INDEX OUT OF RANGE: {name}({idx + base})")
         if name not in self.arrays:
             self.arrays[name] = [0.0] * (idx + 1)
         while idx >= len(self.arrays[name]):
@@ -126,6 +129,8 @@ class ControlFlowMixin:
         start = self._eval_with_vars(start_expr, run_vars)
         end = self._eval_with_vars(end_expr, run_vars)
         step = self._eval_with_vars(step_expr, run_vars) if step_expr else 1
+        if step == 0:
+            raise RuntimeError(f"FOR {var}: STEP 0 would never terminate")
         try:
             if start == int(start): start = int(start)
         except (OverflowError, ValueError):
@@ -146,22 +151,25 @@ class ControlFlowMixin:
 
     def _cf_next(self, stmt: str, run_vars: dict[str, Any], loop_stack: list[dict[str, Any]],
                  parsed: NextStmt) -> tuple[bool, ExecOutcome]:
-        var = parsed.var
-        if not loop_stack or loop_stack[-1].get('var') != var:
-            if loop_stack:
-                expected = loop_stack[-1].get('var', '?')
-                raise RuntimeError(f"NEXT {var} does not match current FOR {expected}")
-            raise RuntimeError(f"NEXT {var} without matching FOR")
-        loop = loop_stack[-1]
-        loop['current'] += loop['step']
-        if (loop['step'] > 0 and loop['current'] <= loop['end']) or \
-           (loop['step'] < 0 and loop['current'] >= loop['end']):
-            run_vars[var] = loop['current']
-            self.variables[var] = loop['current']
-            return True, loop['return_ip'] + 1
-        else:
+        # Supports bare ``NEXT`` (close the innermost FOR) and ``NEXT i, j``
+        # (close i, then j). Each named variable must match the FOR on top of
+        # the loop stack at that point.
+        names = [v.strip() for v in parsed.var.split(',')] if parsed.var.strip() else ['']
+        for name in names:
+            if not loop_stack or loop_stack[-1].get('var') is None:
+                raise RuntimeError(f"NEXT {name}".rstrip() + " without matching FOR")
+            loop = loop_stack[-1]
+            cur_var = loop['var']
+            if name and cur_var != name:
+                raise RuntimeError(f"NEXT {name} does not match current FOR {cur_var}")
+            loop['current'] += loop['step']
+            if (loop['step'] > 0 and loop['current'] <= loop['end']) or \
+               (loop['step'] < 0 and loop['current'] >= loop['end']):
+                run_vars[cur_var] = loop['current']
+                self.variables[cur_var] = loop['current']
+                return True, loop['return_ip'] + 1
             loop_stack.pop()
-            return True, ExecResult.ADVANCE
+        return True, ExecResult.ADVANCE
 
     def _find_matching_wend(self, sorted_lines: list[int], ip: int) -> int:
         """Find the ip after the WEND matching the WHILE at ip.
@@ -218,8 +226,21 @@ class ControlFlowMixin:
         cond_vars = run_vars
         if self.locc_mode and self.locc:
             cond_vars = {**run_vars, **self.locc.classical}
-        result = ExecResult.ADVANCE
-        if self._eval_condition(cond_str, cond_vars):
+        cond_true = self._eval_condition(cond_str, cond_vars)
+
+        # Block form: "IF cond THEN" with no inline THEN/ELSE clauses spans
+        # following lines up to a matching ELSE / END IF.
+        if not then_clause and else_clause is None:
+            else_ip, endif_ip = self._find_if_block(sorted_lines, ip)
+            if cond_true:
+                return True, ExecResult.ADVANCE  # fall into the THEN block
+            if else_ip is not None:
+                return True, else_ip + 1          # jump to the ELSE block
+            return True, endif_ip + 1             # no ELSE: skip past END IF
+
+        # Single-line form.
+        result: ExecOutcome = ExecResult.ADVANCE
+        if cond_true:
             if then_clause:
                 r = exec_fn(then_clause, loop_stack, sorted_lines, ip, run_vars)
                 if r is not None and r is not ExecResult.ADVANCE:
@@ -230,6 +251,52 @@ class ControlFlowMixin:
                 result = r
         return True, result
 
+    @staticmethod
+    def _is_block_if(line: str) -> bool:
+        """True for a block-opening ``IF ... THEN`` (nothing after THEN)."""
+        return re.match(r'IF\b.*\bTHEN\s*$', line.strip(), re.IGNORECASE) is not None
+
+    def _find_if_block(self, sorted_lines: list[int], ip: int) -> tuple[int | None, int]:
+        """From a block IF at ip, find (else_ip, endif_ip) handling nesting."""
+        depth = 1
+        else_ip: int | None = None
+        scan = ip + 1
+        while scan < len(sorted_lines):
+            s = self.program[sorted_lines[scan]].strip()
+            su = s.upper()
+            if self._is_block_if(s):
+                depth += 1
+            elif su == 'END IF':
+                depth -= 1
+                if depth == 0:
+                    return else_ip, scan
+            elif su == 'ELSE' and depth == 1 and else_ip is None:
+                else_ip = scan
+            scan += 1
+        raise RuntimeError(f"IF block at line {sorted_lines[ip]} has no matching END IF")
+
+    def _cf_else(self, sorted_lines: list[int], ip: int) -> tuple[bool, ExecOutcome]:
+        """ELSE reached while running a THEN block: skip past the END IF."""
+        depth = 1
+        scan = ip + 1
+        while scan < len(sorted_lines):
+            s = self.program[sorted_lines[scan]].strip()
+            su = s.upper()
+            if self._is_block_if(s):
+                depth += 1
+            elif su == 'END IF':
+                depth -= 1
+                if depth == 0:
+                    return True, scan + 1
+            scan += 1
+        return True, ExecResult.ADVANCE
+
+    def _cf_return(self) -> tuple[bool, ExecOutcome]:
+        """RETURN — pop the GOSUB stack, or error if there is nothing to return to."""
+        if not self._gosub_stack:
+            raise RuntimeError("RETURN WITHOUT GOSUB")
+        return True, self._gosub_stack.pop()
+
     # ── Type-based dispatch table ────────────────────────────────────
     # Maps parsed Stmt types to handler lambdas.  Each lambda receives
     # (self, stmt, parsed, loop_stack, sorted_lines, ip, run_vars,
@@ -240,7 +307,7 @@ class ControlFlowMixin:
         RemStmt:         lambda s, st, p, ls, sl, ip, rv, ef: (True, ExecResult.ADVANCE),
         MeasureStmt:     lambda s, st, p, ls, sl, ip, rv, ef: (True, ExecResult.ADVANCE),
         EndStmt:         lambda s, st, p, ls, sl, ip, rv, ef: (True, ExecResult.END),
-        ReturnStmt:      lambda s, st, p, ls, sl, ip, rv, ef: (_ for _ in ()).throw(RuntimeError("RETURN WITHOUT GOSUB")) if not s._gosub_stack else (True, s._gosub_stack.pop()),
+        ReturnStmt:      lambda s, st, p, ls, sl, ip, rv, ef: s._cf_return(),
         # Handlers defined in control_flow.py (parsed is positional)
         WendStmt:        lambda s, st, p, ls, sl, ip, rv, ef: s._cf_wend(rv, ls, sl, ip),
         LetArrayStmt:    lambda s, st, p, ls, sl, ip, rv, ef: s._cf_let_array(st, rv, p),
@@ -260,6 +327,8 @@ class ControlFlowMixin:
         SelectCaseStmt:  lambda s, st, p, ls, sl, ip, rv, ef: s._cf_select_case(st, rv, sl, ip, parsed=p),
         CaseStmt:        lambda s, st, p, ls, sl, ip, rv, ef: s._cf_case(st, sl, ip, parsed=p),
         EndSelectStmt:   lambda s, st, p, ls, sl, ip, rv, ef: s._cf_end_select(st, parsed=p),
+        ElseStmt:        lambda s, st, p, ls, sl, ip, rv, ef: s._cf_else(sl, ip),
+        EndIfStmt:       lambda s, st, p, ls, sl, ip, rv, ef: (True, ExecResult.ADVANCE),
         DoStmt:          lambda s, st, p, ls, sl, ip, rv, ef: s._cf_do(st, rv, ls, sl, ip, parsed=p),
         LoopStmt:        lambda s, st, p, ls, sl, ip, rv, ef: s._cf_loop(st, rv, ls, sl, ip, parsed=p),
         ExitStmt:        lambda s, st, p, ls, sl, ip, rv, ef: s._cf_exit(st, ls, sl, ip, parsed=p),

{qubasic-0.5.0 → qubasic-0.6.0}/qubasic_core/debug.py

@@ -32,6 +32,7 @@ class DebugMixin:
         self._breakpoints: set[int] = set()
         self._watches: list[str] = []
         self._on_measure_target: int | None = None
+        self._on_measure_fired: bool = False
         self._on_timer_target: int | None = None
         self._on_timer_interval: float = 0.0
         self._on_timer_last: float = 0.0

{qubasic-0.5.0 → qubasic-0.6.0}/qubasic_core/demos.py

@@ -297,6 +297,7 @@ class DemoMixin:
 
     def _demo_stress(self):
         self.cmd_new()
+        self.io.writeln("  (note: STRESS builds a highly entangled 20-qubit state; this can take a while)")
         n = 20
         self.num_qubits = n
         self.program = {

{qubasic-0.5.0 → qubasic-0.6.0}/qubasic_core/display.py

@@ -25,6 +25,21 @@ class DisplayMixin:
     Requires: TerminalProtocol — uses self.num_qubits, self.arrays.
     """
 
+    def _rich_print(self, *renderables) -> None:
+        """Render rich content to a string and emit it through the IOPort.
+
+        Routing rich output through self.io (instead of straight to stdout)
+        means headless/agent callers with a custom IOPort capture tables and
+        statevectors too, and the IOPort's encoding fallback applies uniformly.
+        ANSI colour is kept only when stdout is a real terminal.
+        """
+        import io as _io
+        from rich.console import Console
+        buf = _io.StringIO()
+        force = bool(sys.stdout and sys.stdout.isatty())
+        Console(file=buf, highlight=False, force_terminal=force).print(*renderables)
+        self.io.write(buf.getvalue())
+
     def print_histogram(self, counts: dict[str, int]) -> None:
         """Measurement histogram with optional rich-table formatting."""
         total = sum(counts.values())
@@ -48,11 +63,11 @@ class DisplayMixin:
 
         max_count = max(c for _, c in display) if display else 1
         if len(sorted_counts) > MAX_HISTOGRAM_STATES:
-            _get_console().print(
+            self._rich_print(
                 f"\n  [dim]Showing top {MAX_HISTOGRAM_STATES} of "
                 f"{len(sorted_counts)} outcomes:[/dim]\n")
         else:
-            _get_console().print()
+            self._rich_print()
 
         for state, count in display:
             pct = 100 * count / total
@@ -72,8 +87,8 @@ class DisplayMixin:
                 f"{100*rest_count/total:5.1f}%", "[dim](remaining)[/dim]")
 
         try:
-            _get_console().print(table)
-            _get_console().print()
+            self._rich_print(table)
+            self._rich_print()
         except UnicodeEncodeError:
             self._print_histogram_plain(display, sorted_counts, total)
 
@@ -122,7 +137,7 @@ class DisplayMixin:
             table.add_column("State", justify="right", style="bold")
             table.add_column("Amplitude", justify="right")
             table.add_column("P", justify="right")
-            _get_console().print(f"\n  [bold]Statevector ({n} qubits):[/bold]")
+            self._rich_print(f"\n  [bold]Statevector ({n} qubits):[/bold]")
             count = 0
             for i, amp in enumerate(sv):
                 if abs(amp) > AMPLITUDE_THRESHOLD:
@@ -140,8 +155,8 @@ class DisplayMixin:
                             table.add_row("...", "", f"+{remaining} more")
                         break
             try:
-                _get_console().print(table)
-                _get_console().print()
+                self._rich_print(table)
+                self._rich_print()
                 return
             except UnicodeEncodeError:
                 pass  # fall through to plain-text path below