pyctures 0.1.0__py3-none-any.whl

pyctures/__init__.py

@@ -0,0 +1,890 @@
+"""Pyctures: Python 2D and 3D graphics, drawn in a web browser.
+
+This module is the Python half of Pyctures. The same source runs in your own
+CPython (``pyctures run``) and in the browser with Pyodide (``pyctures build``):
+the browser half loads this very file as the module ``pyctures``.
+
+NAMESPACE MAPPING. ``js``, ``canvas``, ``ctx``, ``THREE`` and ``addons`` are
+proxies for objects that live in the browser page. Using one RECORDS a command;
+nothing crosses to JavaScript until the frame ends (``draw()`` returns,
+``await frame()``, or ``await flush()``). So a whole frame is one message.
+
+  - ``a.b``         a lazy reference (nothing sent until it is used)
+  - ``a.b(...)``    a call with ``this = a``; the result gets a handle number at
+                    once, on the Python side, so it can be used in the same frame
+  - ``A.B(...)``    a capitalised name is a constructor: ``new A.B(...)``
+  - ``a.b = v``     a property write; the value is also remembered here, so
+                    reading it back (``a.b``) needs no round trip
+  - ``a.b += 1``    maths on a value that lives in the page is DEFERRED: it is
+                    sent as an expression and worked out there
+  - ``await a.b``   a real read, answered at the end of the frame
+  - keyword args    become one trailing options object (``antialias=True``)
+  - snake_case      ``fill_rect``, ``fill_style`` reach ``fillRect``, ``fillStyle``
+  - functions       passed as callbacks (addEventListener) come back as events
+
+Command shape (the contract with ``web/pyctures.js``). Every command is
+``[kind, line, ...]``, ``line`` being the user's source line that made it::
+
+  ['get',  line, newH, objH, name]
+  ['set',  line, objH, name, value]
+  ['call', line, newH, objH, name, args]
+  ['new',  line, newH, objH, name, args]
+  ['fcall',line, newH, fnH, args]
+  ['fnew', line, newH, fnH, args]
+  ['free', line, h]
+  ['read', line, readId, value, newH]   (newH: where a promise's object lands)
+
+Values: plain JSON, or {"$h": h}, {"$e": expr}, {"$cb": id}, {"$d": {...}}.
+
+The host calls ``start(source, info_json)`` once, then ``tick(payload_json)``
+once per frame, and ``stop()``. Each returns a JSON reply:
+``{"cmds", "out", "err", "running", "error", "errorLine"}``.
+"""
+import sys, io, json, time, math, traceback, threading, types, linecache
+
+__version__ = "0.1.0"
+
+VERSION = "10"
+USER_FILE = "main.py"
+
+# Fixed handles the frame defines before anything runs.
+H_WINDOW, H_CANVAS, H_THREE, H_CTX, H_ADDONS = 1, 2, 3, 4, 5
+
+
+class _State:
+    def __init__(self):
+        self.cmds = []
+        self.next_read = 1
+        self.reads = {}          # read id -> result once answered
+        self.callbacks = {}      # callback id -> Python function
+        self.next_cb = 1
+        self.tasks = []          # live coroutines: [coro, waiting]
+        self.ns = None           # the user's namespace
+        self.out = io.StringIO()
+        self.err = io.StringIO()
+        self.started = 0.0
+        self.frame_no = 0
+        self.thread = None
+        self.busy = False
+        self.stopped = False
+        self.pictures = {}       # (text, size) -> a canvas with the text drawn once
+        self.measuring = False   # measure mode: time each part of a frame
+        self.sections = {}       # name -> ms this frame (measure mode)
+
+
+# WHICH RUN A THREAD IS WORKING FOR. A host may run every frame as its own
+# request on its own thread, and a frame from a run the user has just stopped
+# can still be finishing while the next run starts. If both shared one state,
+# the old frame's commands landed in the new run (objects the new preview never
+# made). So each start()/tick() pins its run's state to its thread, and `S`
+# reads through that pin; with no pin, it is the latest run.
+_tls = threading.local()
+_latest = [_State()]
+
+
+class _Current:
+    __slots__ = ()
+
+    def __getattr__(self, name):
+        return getattr(getattr(_tls, "state", None) or _latest[0], name)
+
+    def __setattr__(self, name, value):
+        setattr(getattr(_tls, "state", None) or _latest[0], name, value)
+
+
+S = _Current()
+
+# Never reset between runs: a reference from the LAST run that is collected
+# during this one sends a 'free' for its number, and that number must not
+# belong to anything new.
+_next_handle = [1000]
+
+
+def _user_line():
+    f = sys._getframe(1)
+    while f is not None:
+        if f.f_code.co_filename == USER_FILE:
+            return f.f_lineno
+        f = f.f_back
+    return 0
+
+
+def _emit(*cmd):
+    S.cmds.append([cmd[0], _user_line(), *cmd[1:]])
+
+
+def _new_handle():
+    _next_handle[0] += 1
+    return _next_handle[0]
+
+
+class PreviewValueError(TypeError):
+    pass
+
+
+_READ_HINT = ("this value lives in the preview, not in Python — "
+              "read it with  value = await <expression>")
+
+
+class _Read:
+    """An awaitable for one value the frame has to send back.
+
+    A PROMISE is awaited in the page: what it resolves to comes back as data,
+    or, when it is an object (a GPU adapter, a device, a loaded font), as a
+    reference that can be used like any other. Its handle number is reserved
+    here, with the read, so the two sides never disagree on it.
+    """
+    __slots__ = ("rid",)
+
+    def __init__(self, encoded):
+        self.rid = S.next_read
+        S.next_read += 1
+        _emit("read", self.rid, encoded, _new_handle())
+
+    def __await__(self):
+        result = yield self
+        if isinstance(result, dict) and len(result) == 1:
+            if "$h" in result:
+                return JsRef(result["$h"], owned=True)
+            if "$error" in result:
+                raise RuntimeError(result["$error"])
+        return result
+
+
+class _Frame:
+    """'await frame()' — park until the next frame (also sends this one)."""
+    __slots__ = ("until",)
+
+    def __init__(self, seconds=0.0):
+        self.until = time.monotonic() + seconds
+
+    def __await__(self):
+        yield self
+
+
+def frame():
+    return _Frame()
+
+
+def flush():
+    """Send what has been drawn so far, now, and carry on next frame."""
+    return _Frame()
+
+
+def sleep(seconds):
+    return _Frame(seconds)
+
+
+# ---------------------------------------------------------------- expressions
+
+class _Expr:
+    __slots__ = ("tree",)
+
+    def __init__(self, tree):
+        object.__setattr__(self, "tree", tree)
+
+    def _enc(self):
+        return {"$e": self.tree}
+
+    def __await__(self):
+        return _Read(self._enc()).__await__()
+
+    def __bool__(self):
+        raise PreviewValueError(_READ_HINT)
+
+    def __repr__(self):
+        return "<preview expression>"
+
+
+def _expr_of(v):
+    if isinstance(v, _Expr):
+        return v.tree
+    if isinstance(v, JsRef):
+        return ["ref", v._enc()]
+    return ["v", _encode(v)]
+
+
+def _binop(op):
+    def fwd(self, other):
+        return _Expr([op, _expr_of(self), _expr_of(other)])
+
+    def rev(self, other):
+        return _Expr([op, _expr_of(other), _expr_of(self)])
+    return fwd, rev
+
+
+for _name, _op in (("add", "+"), ("sub", "-"), ("mul", "*"), ("truediv", "/"),
+                   ("mod", "%"), ("pow", "**"), ("floordiv", "//")):
+    _f, _r = _binop(_op)
+    setattr(_Expr, "__%s__" % _name, _f)
+    setattr(_Expr, "__r%s__" % _name, _r)
+_Expr.__neg__ = lambda self: _Expr(["neg", _expr_of(self)])
+
+
+# ---------------------------------------------------------------- references
+
+class JsRef:
+    """A JavaScript object in the preview frame, seen from Python."""
+    __slots__ = ("_h", "_parent", "_name", "_shadow", "_kids", "_owned", "_cmd", "__weakref__")
+
+    def __init__(self, handle=None, parent=None, name=None, owned=False, cmd=None):
+        object.__setattr__(self, "_h", handle)
+        object.__setattr__(self, "_parent", parent)
+        object.__setattr__(self, "_name", name)
+        object.__setattr__(self, "_shadow", {})
+        object.__setattr__(self, "_kids", {})
+        object.__setattr__(self, "_owned", owned)
+        # The unsent command that made this value. While it is still unsent and
+        # the value is unused, a discarded result needs no handle at all.
+        object.__setattr__(self, "_cmd", cmd)
+
+    def _use(self):
+        object.__setattr__(self, "_cmd", None)
+
+    # A lazy member becomes a real handle the first time it is used as one.
+    def _handle(self):
+        self._use()
+        if self._h is None:
+            h = _new_handle()
+            _emit("get", h, self._parent._handle(), self._name)
+            object.__setattr__(self, "_h", h)
+            object.__setattr__(self, "_owned", True)
+        return self._h
+
+    def _enc(self):
+        return {"$h": self._handle()}
+
+    def __getattr__(self, name):
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        self._use()
+        shadow = self._shadow
+        if name in shadow:
+            return shadow[name]
+        kid = self._kids.get(name)
+        if kid is None:
+            kid = JsRef(parent=self, name=name)
+            self._kids[name] = kid
+        return kid
+
+    def __setattr__(self, name, value):
+        self._use()
+        _emit("set", self._handle(), name, _encode(value))
+        if isinstance(value, (int, float, str, bool)) or value is None:
+            self._shadow[name] = value
+        else:
+            self._shadow.pop(name, None)
+        self._kids.pop(name, None)
+
+    def __getitem__(self, key):
+        return self.__getattr__(str(key))
+
+    def __setitem__(self, key, value):
+        self.__setattr__(str(key), value)
+
+    def __call__(self, *args, **kwargs):
+        enc = [_encode(a) for a in args]
+        if kwargs:
+            enc.append({"$d": {k: _encode(v) for k, v in kwargs.items()}})
+        self._use()
+        h = _new_handle()
+        if self._parent is not None and self._h is None:
+            kind = "new" if self._name[:1].isupper() else "call"
+            _emit(kind, h, self._parent._handle(), self._name, enc)
+        else:
+            _emit("fcall", h, self._handle(), enc)
+        return JsRef(h, owned=True, cmd=S.cmds[-1])
+
+    def new(self, *args, **kwargs):
+        enc = [_encode(a) for a in args]
+        if kwargs:
+            enc.append({"$d": {k: _encode(v) for k, v in kwargs.items()}})
+        h = _new_handle()
+        if self._parent is not None and self._h is None:
+            _emit("new", h, self._parent._handle(), self._name, enc)
+        else:
+            _emit("fnew", h, self._handle(), enc)
+        return JsRef(h, owned=True)
+
+    def __await__(self):
+        if self._h is None and self._parent is not None:
+            enc = {"$e": ["get", _expr_of(self._parent), self._name]}
+        else:
+            enc = self._enc()
+        return _Read(enc).__await__()
+
+    def __bool__(self):
+        return True
+
+    def __del__(self):
+        try:
+            cmd = self._cmd
+            if cmd is not None and S.cmds and any(c is cmd for c in S.cmds[-64:]):
+                cmd[2] = 0   # never used and not sent yet: do not keep it
+            elif self._owned and self._h is not None and not S.stopped:
+                S.cmds.append(["free", 0, self._h])
+        except Exception:
+            pass
+
+    def __repr__(self):
+        if self._parent is not None and self._h is None:
+            return "<preview %s>" % self._name
+        return "<preview object #%s>" % self._h
+
+
+# Arithmetic on a reference to a value in the frame is deferred.
+def _ref_expr(op, rev=False):
+    def f(self, other):
+        lhs = ["get", _expr_of(self._parent), self._name] if (self._h is None and self._parent is not None) else _expr_of(self)
+        rhs = _expr_of(other)
+        return _Expr([op, rhs, lhs] if rev else [op, lhs, rhs])
+    return f
+
+
+for _name, _op in (("add", "+"), ("sub", "-"), ("mul", "*"), ("truediv", "/"),
+                   ("mod", "%"), ("pow", "**"), ("floordiv", "//")):
+    setattr(JsRef, "__%s__" % _name, _ref_expr(_op))
+    setattr(JsRef, "__r%s__" % _name, _ref_expr(_op, rev=True))
+
+
+def _cmp_error(self, other):
+    raise PreviewValueError(_READ_HINT)
+
+
+for _name in ("lt", "le", "gt", "ge"):
+    setattr(JsRef, "__%s__" % _name, _cmp_error)
+    setattr(_Expr, "__%s__" % _name, _cmp_error)
+
+
+# ---------------------------------------------------------------- values
+
+def _encode(v):
+    if v is None or isinstance(v, (bool, int, float, str)):
+        if isinstance(v, float) and (v != v or v in (float("inf"), float("-inf"))):
+            return {"$e": ["num", "NaN" if v != v else ("Infinity" if v > 0 else "-Infinity")]}
+        return v
+    if isinstance(v, JsRef):
+        return v._enc()
+    if isinstance(v, _Expr):
+        return v._enc()
+    if isinstance(v, (list, tuple)):
+        return [_encode(x) for x in v]
+    if isinstance(v, dict):
+        return {"$d": {str(k): _encode(x) for k, x in v.items()}}
+    if callable(v):
+        cid = S.next_cb
+        S.next_cb += 1
+        S.callbacks[cid] = v
+        return {"$cb": cid}
+    tolist = getattr(v, "tolist", None)   # numpy arrays and scalars
+    if tolist is not None:
+        return _encode(tolist())
+    return str(v)
+
+
+class Event(dict):
+    """An event from the preview: event.key, event.x … (also event["key"])."""
+    def __getattr__(self, name):
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name)
+
+
+# ---------------------------------------------------------------- input state
+
+keys = set()
+
+
+class _Mouse:
+    def __init__(self):
+        self.x = 0.0
+        self.y = 0.0
+        self.down = False
+
+    def __repr__(self):
+        return "mouse(x=%g, y=%g, down=%s)" % (self.x, self.y, self.down)
+
+
+mouse = _Mouse()
+
+
+# ---------------------------------------------------------------- sprites
+
+class Sprite:
+    """A picture (an image, or any emoji/text) that moves. Draws itself with ctx."""
+
+    def __init__(self, picture, x=0, y=0, size=48):
+        self.picture = picture
+        self.x, self.y = x, y
+        self.vx = self.vy = 0.0
+        self.angle = 0.0
+        self.size = size
+        self.visible = True
+
+    def update(self, dt):
+        self.x += self.vx * dt
+        self.y += self.vy * dt
+
+    def draw(self):
+        if not self.visible:
+            return
+        c = ctx
+        c.save()
+        c.translate(self.x, self.y)
+        if self.angle:
+            c.rotate(self.angle)
+        s = self.size
+        if isinstance(self.picture, str):
+            # Emoji/text is drawn ONCE into a small canvas and stamped from then
+            # on: redrawing text every frame is the slow path on phones.
+            box = s * 1.3
+            c.drawImage(_picture(self.picture, s), -box / 2, -box / 2, box, box)
+        else:
+            c.drawImage(self.picture, -s / 2, -s / 2, s, s)
+        c.restore()
+
+    def touches(self, other):
+        r = (self.size + other.size) * 0.4
+        return (self.x - other.x) ** 2 + (self.y - other.y) ** 2 < r * r
+
+
+def _picture(text, size):
+    key = (text, size)
+    pic = S.pictures.get(key)
+    if pic is None:
+        ratio = (S.ns or {}).get("pixel_ratio", 1) or 1
+        px = max(1, int(size * 1.3 * ratio + 0.5))
+        pic = js.document.createElement("canvas")
+        pic.width = px
+        pic.height = px
+        g = pic.getContext("2d")
+        g.font = "%dpx system-ui, sans-serif" % int(size * ratio)
+        g.textAlign = "center"
+        g.textBaseline = "middle"
+        g.fillText(text, px / 2, px / 2 + size * ratio * 0.06)
+        S.pictures[key] = pic
+    return pic
+
+
+def load_image(src):
+    """An image for drawImage or a Sprite. Draws once it has loaded."""
+    img = js.Image()
+    img.src = src
+    return img
+
+
+# ---------------------------------------------------------------- the namespace
+
+js = JsRef(H_WINDOW)
+canvas = JsRef(H_CANVAS)
+THREE = JsRef(H_THREE)
+ctx = JsRef(H_CTX)
+addons = JsRef(H_ADDONS)
+
+class measure:
+    """Time a section of your frame: `with measure("physics"): ...`. Shown in measure mode."""
+    __slots__ = ("name", "t0")
+
+    def __init__(self, name):
+        self.name = str(name)
+
+    def __enter__(self):
+        self.t0 = time.perf_counter() if S.measuring else 0.0
+        return self
+
+    def __exit__(self, *exc):
+        if self.t0:
+            sec = S.sections
+            sec[self.name] = sec.get(self.name, 0.0) + (time.perf_counter() - self.t0) * 1000
+        return False
+
+
+EXPORTS = ("js", "canvas", "ctx", "THREE", "addons", "frame", "flush", "sleep",
+           "keys", "mouse", "Sprite", "load_image", "Event", "measure")
+
+
+# ---------------------------------------------------------------- breakpoints
+#
+# A pause HOLDS the thread running the frame, so only a host that answers
+# other requests meanwhile (one thread per request) can pause. The
+# ``pyctures`` command line does not use breakpoints; they are kept so the
+# module stays the same everywhere it runs. The host asks debug_state() and answers with debug_resume()
+# from those other requests. Only the user's file is traced.
+
+class _Debug:
+    def __init__(self):
+        self.on = False
+        self.bps = set()
+        self.mode = None      # 'over' | 'into' | 'out' after a step
+        self.depth = 0
+        self.paused = False
+        self.line = 0
+        self.vars = {}
+        self.action = None
+        self.seq = 0          # one number per pause, so the host answers each once
+
+
+DBG = _Debug()
+_STEP = {"stepOver": "over", "stepInto": "into", "stepOut": "out"}
+
+
+def _user_depth(frame):
+    d = 0
+    while frame is not None:
+        if frame.f_code.co_filename == USER_FILE:
+            d += 1
+        frame = frame.f_back
+    return d
+
+
+def _vars(frame):
+    out = {}
+    names = dict(frame.f_globals) if frame.f_globals is not None else {}
+    names.update(frame.f_locals)
+    for name, value in names.items():
+        if name.startswith("_") or name in EXPORTS:
+            continue
+        if isinstance(value, types.ModuleType) or (callable(value) and not isinstance(value, type)):
+            continue
+        try:
+            if isinstance(value, (int, float, str, bool, type(None))):
+                out[name] = {"value": value, "type": type(value).__name__}
+            elif isinstance(value, (list, tuple, dict, set)):
+                out[name] = {"value": repr(value)[:200], "type": type(value).__name__, "length": len(value)}
+            else:
+                out[name] = {"value": repr(value)[:200], "type": type(value).__name__}
+        except Exception:
+            out[name] = {"value": "<unreadable>", "type": type(value).__name__}
+    return out
+
+
+def _local_trace(frame, event, arg):
+    if event == "line" and DBG.on and not S.stopped:
+        line = frame.f_lineno
+        mode = DBG.mode
+        d = _user_depth(frame) if mode else 0
+        if (line in DBG.bps or mode == "into"
+                or (mode == "over" and d <= DBG.depth)
+                or (mode == "out" and d < DBG.depth)):
+            _pause(frame, line)
+    return _local_trace
+
+
+def _global_trace(frame, event, arg):
+    if frame.f_code.co_filename != USER_FILE:
+        return None
+    return _local_trace
+
+
+def _pause(frame, line):
+    # This run's state, not whatever run is latest: a new run (or a reloaded
+    # page) must still release a pause left behind.
+    state = getattr(_tls, "state", None) or _latest[0]
+    DBG.mode = None
+    DBG.line = line
+    DBG.vars = _vars(frame)
+    DBG.action = None
+    DBG.seq += 1
+    DBG.paused = True
+    try:
+        while DBG.action is None and not state.stopped:
+            time.sleep(0.02)
+    finally:
+        DBG.paused = False
+    action = DBG.action
+    if action == "stop" or state.stopped:
+        raise KeyboardInterrupt("Stopped")
+    DBG.mode = _STEP.get(action)
+    DBG.depth = _user_depth(frame)
+
+
+def debug_set(lines_json, on):
+    DBG.on = bool(on)
+    DBG.bps = set(json.loads(lines_json))
+    DBG.mode = None
+    return "ok"
+
+
+def debug_state():
+    return json.dumps({"paused": DBG.paused, "seq": DBG.seq, "line": DBG.line,
+                       "vars": DBG.vars if DBG.paused else {}}, default=str)
+
+
+def debug_resume(action):
+    DBG.action = action
+    return "ok"
+
+
+class _Traced:
+    """Trace the user's file for the length of one start() or tick()."""
+    def __enter__(self):
+        if DBG.on:
+            sys.settrace(_global_trace)
+
+    def __exit__(self, *exc):
+        if DBG.on:
+            sys.settrace(None)
+        return False
+
+
+# ---------------------------------------------------------------- running
+
+def _drive(task, value=None):
+    """Step one coroutine until it waits; returns False when it has finished."""
+    coro = task[0]
+    try:
+        waiting = coro.send(value)
+    except StopIteration:
+        return False
+    task[1] = waiting
+    return True
+
+
+def _format_error(e):
+    tb = traceback.extract_tb(e.__traceback__)
+    user = [fr for fr in tb if fr.filename == USER_FILE]
+    lines = ["Traceback (most recent call last):"]
+    for fr in user:
+        lines.append('  line %d, in %s' % (fr.lineno, fr.name))
+        if fr.line:
+            lines.append("    " + fr.line.strip())
+    line = user[-1].lineno if user else 0
+    if isinstance(e, SyntaxError) and e.filename == USER_FILE and e.lineno:
+        # A mistake in how the file is written: it never ran, so there is no
+        # traceback into it, only the line the parser stopped at.
+        line = e.lineno
+        lines.append("  line %d" % line)
+        if e.text:
+            lines.append("    " + e.text.strip())
+        lines.append("%s: %s" % (type(e).__name__, e.msg))
+        return "\n".join(lines), line
+    lines.append("%s: %s" % (type(e).__name__, e))
+    return "\n".join(lines), line
+
+
+def _reply(error=None, error_line=0):
+    cmds, S.cmds = S.cmds, []
+    out = S.out.getvalue()
+    err = S.err.getvalue()
+    S.out = io.StringIO()
+    S.err = io.StringIO()
+    running = S.ns is not None and not error and (
+        bool(S.tasks) or bool(S.callbacks)
+        or any(callable(S.ns.get(n)) for n in _LIVE_NAMES))
+    reply = {
+        "cmds": cmds, "out": out, "err": err, "running": running,
+        "error": error, "errorLine": error_line,
+    }
+    if S.measuring:
+        reply["t"] = S.sections
+        S.sections = {}
+    return json.dumps(reply, default=str)
+
+
+_LIVE_NAMES = ("draw", "update", "on_key_down", "on_key_up",
+               "on_mouse_down", "on_mouse_move", "on_mouse_up")
+
+
+def _apply_info(p):
+    ns = S.ns
+    if ns is None:
+        return
+    for k in ("width", "height", "pixel_ratio"):
+        if k in p:
+            ns[k] = p[k]
+
+
+def _apply_events(p):
+    ns = S.ns
+    for ev in p.get("events", ()):
+        e = Event(ev.get("e") or {})
+        kind = ev.get("k")
+        if kind == "cb":
+            fn = S.callbacks.get(ev.get("id"))
+            if fn is not None:
+                r = fn(e)
+                if hasattr(r, "send"):
+                    # Kept only while it is still waiting: a callback that
+                    # finishes without awaiting must not be driven again.
+                    task = [r, None]
+                    if _drive(task):
+                        S.tasks.append(task)
+            continue
+        t = e.get("type")
+        if t == "keydown":
+            keys.add(e.get("key"))
+            fn = ns.get("on_key_down")
+            if callable(fn):
+                fn(e.get("key"))
+        elif t == "keyup":
+            keys.discard(e.get("key"))
+            fn = ns.get("on_key_up")
+            if callable(fn):
+                fn(e.get("key"))
+        elif t in ("pointerdown", "pointermove", "pointerup"):
+            mouse.x, mouse.y = e.get("x", mouse.x), e.get("y", mouse.y)
+            if t == "pointerdown":
+                mouse.down = True
+            elif t == "pointerup":
+                mouse.down = False
+            fn = ns.get({"pointerdown": "on_mouse_down", "pointermove": "on_mouse_move",
+                         "pointerup": "on_mouse_up"}[t])
+            if callable(fn):
+                fn(mouse.x, mouse.y)
+
+
+def _step_tasks(answers):
+    now = time.monotonic()
+    alive = []
+    for task in S.tasks:
+        waiting = task[1]
+        if isinstance(waiting, _Read):
+            if waiting.rid not in answers:
+                alive.append(task)
+                continue
+            keep = _drive(task, answers[waiting.rid])
+        elif isinstance(waiting, _Frame):
+            if waiting.until > now:
+                alive.append(task)
+                continue
+            keep = _drive(task)
+        else:
+            keep = _drive(task)
+        if keep:
+            alive.append(task)
+    S.tasks = alive
+
+
+def _call_frame_functions(dt):
+    ns = S.ns
+    for name, args in (("update", (dt,)), ("draw", ())):
+        fn = ns.get(name)
+        if not callable(fn):
+            continue
+        if any(t[2:] == [name] for t in S.tasks):
+            continue  # last frame's async draw is still waiting on a read
+        takes = getattr(getattr(fn, "__code__", None), "co_argcount", 1)
+        t0 = time.perf_counter() if S.measuring else 0.0
+        r = fn(*args) if (name != "update" or takes) else fn()
+        if t0:
+            S.sections[name] = S.sections.get(name, 0.0) + (time.perf_counter() - t0) * 1000
+        if hasattr(r, "send"):
+            task = [r, None, name]
+            if _drive(task):
+                S.tasks.append(task)
+
+
+def start(source, info_json):
+    """Run the file's top level. Returns the first frame's reply (JSON)."""
+    _latest[0].stopped = True
+    _latest[0] = _State()
+    _tls.state = _latest[0]
+    # FRESH ROOT NAMES EVERY RUN. A name like `js` remembers what was looked
+    # up through it (js.document, THREE.DoubleSide) as handles in the preview
+    # page; a new run has a new page, so reused names pointed at objects that
+    # no longer exist ("that object no longer exists in the preview").
+    global js, canvas, THREE, ctx, addons
+    js, canvas, THREE = JsRef(H_WINDOW), JsRef(H_CANVAS), JsRef(H_THREE)
+    ctx, addons = JsRef(H_CTX), JsRef(H_ADDONS)
+    keys.clear()
+    mouse.x = mouse.y = 0.0
+    mouse.down = False
+    S.thread = threading.get_ident()
+    S.busy = True
+    S.started = time.monotonic()
+    info = json.loads(info_json)
+    S.measuring = bool(info.get("measure"))
+    ns = {"__name__": "__main__", "__builtins__": __builtins__}
+    for name in EXPORTS:
+        ns[name] = globals()[name]
+    S.ns = ns
+    _apply_info(info)
+    old_out, old_err = sys.stdout, sys.stderr
+    sys.stdout, sys.stderr = S.out, S.err
+    tracer = _Traced()
+    try:
+        tracer.__enter__()
+        import ast
+        flags = getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0)
+        # Tracebacks quote the line that failed: let them find the source.
+        linecache.cache[USER_FILE] = (len(source), None, source.splitlines(True), USER_FILE)
+        code = compile(source, USER_FILE, "exec", flags=flags)
+        result = eval(code, ns)
+        if hasattr(result, "send"):
+            task = [result, None]
+            if _drive(task):
+                S.tasks.append(task)
+        if callable(ns.get("setup")):
+            r = ns["setup"]()
+            if hasattr(r, "send"):
+                task = [r, None]
+                if _drive(task):
+                    S.tasks.append(task)
+        _call_frame_functions(0.0)
+    except BaseException as e:  # noqa: BLE001 — every failure is the user's to read
+        msg, line = _format_error(e)
+        S.ns = None
+        return _reply(msg, line)
+    finally:
+        tracer.__exit__()
+        sys.stdout, sys.stderr = old_out, old_err
+        S.busy = False
+    return _reply()
+
+
+def tick(payload_json):
+    """One frame: events and read answers in, this frame's commands out (JSON)."""
+    _tls.state = _latest[0]
+    if S.ns is None:
+        return _reply("Nothing is running", 0)
+    S.thread = threading.get_ident()
+    S.busy = True
+    p = json.loads(payload_json)
+    S.frame_no += 1
+    S.measuring = bool(p.get("measure"))
+    t_tick = time.perf_counter() if S.measuring else 0.0
+    old_out, old_err = sys.stdout, sys.stderr
+    sys.stdout, sys.stderr = S.out, S.err
+    tracer = _Traced()
+    try:
+        tracer.__enter__()
+        if "bps" in p:
+            DBG.bps = set(p["bps"])
+        _apply_info(p)
+        answers = {int(k): v for k, v in (p.get("reads") or {}).items()}
+        _apply_events(p)
+        _step_tasks(answers)
+        _call_frame_functions(float(p.get("dt", 0.0)))
+    except BaseException as e:  # noqa: BLE001
+        msg, line = _format_error(e)
+        S.ns = None
+        return _reply(msg, line)
+    finally:
+        tracer.__exit__()
+        sys.stdout, sys.stderr = old_out, old_err
+        S.busy = False
+    if t_tick:
+        S.sections["python"] = (time.perf_counter() - t_tick) * 1000
+    return _reply()
+
+
+def stop():
+    """Stop: drop the program, and interrupt it if it is stuck in a loop."""
+    _tls.state = _latest[0]
+    S.stopped = True
+    S.ns = None
+    S.tasks = []
+    DBG.action = "stop"
+    tid = S.thread
+    # Only while a frame is actually running: a finished frame's thread id may
+    # already belong to another request.
+    if S.busy and tid is not None and tid != threading.get_ident():
+        try:
+            import ctypes
+            ctypes.pythonapi.PyThreadState_SetAsyncExc(ctypes.c_ulong(tid), ctypes.py_object(KeyboardInterrupt))
+        except Exception:
+            pass
+    return "stopped"
+
+