docs(worker): the mechanism was corrected everywhere EXCEPT the code it describes

Re-review of finding 1. Comments only; no behaviour change. pytest 31 passed.

b403c71 replaced a false reason for the unconditional await ("a loop that stops
yielding cannot be stopped") with a more careful one. Then the browser
experiment for finding 6 disproved the replacement too, and I updated the report
and trinket's spec — but not these three, which b403c71 had written hours
earlier and which still said the scene "freezes", with "no events dispatched, no
flush". So the same claim was wrong here twice in a row, the second time in the
one place a reader of _async_rate actually looks.

What the experiment showed — build with `if remaining <= 0.0: return`, sync,
run — is narrower and much harder to notice:

  * the scene KEEPS ANIMATING; _flush_if_due() is synchronous, so outbound
    updates need no yield at all;
  * Stop KEEPS WORKING; terminate() needs nothing from this thread;
  * INBOUND events silently stop arriving — the host delivers them by calling
    __trinket_vpython_dispatch, which only gets a turn when the coroutine gives
    one up.

Inbound dispatch is the only half that needs the yield. The failure mode is
therefore a scene that animates, a Stop button that works, and mouse events that
quietly do nothing — which is exactly why the first browser test written for it
passed against the broken build.

All three sites now say that, and each says the browser is where it was
established rather than presenting it as deduction. The docstring also notes why
the CPython test asserts a bystander coroutine instead: yielding is the
property, and a co-scheduled task is its only visible consequence here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G7y9rTA1r8r8EhEnPSQenR

Author: sspickle

tests/test_trinket_worker.py

@@ -194,12 +194,20 @@ async def loop():
 def test_rate_still_yields_when_user_code_overruns_the_period(worker_env):
     """Safety: over-period work must not turn rate() into a non-yielding return.
 
-    In a worker the host delivers browser events by CALLING the transport's
-    dispatch, which only gets a turn when the running coroutine gives one up. A
-    rate() that returns without awaiting therefore freezes the scene — no events
-    dispatched, no flush — while the program runs flat out. (Stop survives it:
-    that is worker.terminate() on the page side and needs nothing from this
-    thread. Which makes the symptom subtler, not milder.)
+    What that costs was measured in a browser, not reasoned about, and it is
+    narrower than it sounds. The scene keeps animating: the flush above is
+    synchronous, so outbound updates go out without any yield. Stop keeps
+    working: that is worker.terminate() on the page side, needing nothing from
+    this thread. The one thing that breaks is INBOUND — the host delivers
+    browser events by CALLING the transport's dispatch, and that call only gets
+    a turn when the running coroutine gives one up, so scene.bind handlers and
+    mouse picks silently never fire.
+
+    That is why this test asserts a bystander coroutine gets to run rather than
+    anything about output: yielding is the property, and in CPython a
+    co-scheduled task is the only visible consequence of it. The browser half
+    (a click handler firing during an over-period loop) lives in trinket's
+    worker-vpython.spec.js; both fail on the same mutation.
     """
     vp, _ = worker_env
     calls = 5
@@ -224,8 +232,9 @@ async def loop():
     gained = asyncio.run(loop())
     assert gained >= calls, (
         'rate() yielded %d times in %d over-period calls — a loop that stops '
-        'yielding starves the event loop, so no browser event is dispatched and '
-        'no update is flushed: the scene freezes while the program runs on'
+        'yielding starves the event loop, so the host never gets to deliver a '
+        'browser event: the scene still animates and Stop still works, but '
+        'scene.bind handlers and mouse picks silently never fire'
         % (gained, calls))
 
 

vpython/trinket_worker.py

@@ -128,19 +128,26 @@ async def _async_rate(maxRate):
         # flush we just issued onto the page without an added wait.
         remaining = 0.0 if last is None else (last + period) - time.monotonic()
         # Always await, even at zero. When user code overruns the period the
-        # remainder is negative and there is nothing left to wait for — but a
-        # bare return would never yield to the event loop, and in a worker run
-        # nothing else does either: the host delivers browser events by CALLING
-        # __trinket_vpython_dispatch, and that call only gets a turn when the
-        # running coroutine gives one up. A rate() that stops yielding therefore
-        # freezes the scene — no events dispatched, no flush, a program running
-        # flat out with a picture that never changes.
+        # remainder is negative and there is nothing left to wait for, which
+        # makes an early `return` here look free. It is not, and what it costs
+        # was established by building that version and running it in a browser
+        # (see trinket's worker-vpython.spec.js) rather than by reasoning:
         #
-        # It does NOT break Stop: Stop is worker.terminate() on the page side,
-        # which is unconditional and needs no cooperation from this thread
-        # (trinket's worker-client.js says so at the top). That makes the
-        # symptom subtler, not milder — a frozen animation from a program that
-        # is still running reads as "vpython is broken" rather than as a hang.
+        #   * The scene KEEPS ANIMATING. _flush_if_due() above is synchronous —
+        #     it postMessages without yielding — so outbound updates go out
+        #     exactly as before and the picture moves normally.
+        #   * Stop KEEPS WORKING. That is worker.terminate() on the page side,
+        #     unconditional, needing nothing from this thread (trinket's
+        #     worker-client.js says so at the top).
+        #   * INBOUND EVENTS SILENTLY STOP ARRIVING. The host delivers them by
+        #     CALLING __trinket_vpython_dispatch, and that call only gets a turn
+        #     when the running coroutine gives one up. Nothing else in a worker
+        #     run does. So scene.bind handlers, mouse picks and the rest simply
+        #     never fire.
+        #
+        # Inbound dispatch is the ONLY half that needs this yield, which is what
+        # makes losing it so hard to spot: a scene that animates, a Stop button
+        # that works, and mouse events that quietly do nothing.
         #
         # asyncio.sleep(0) yields. Clamping at 0 also means a loop that falls
         # behind simply stays behind rather than banking debt and then bursting