concurrent-c-node 0.22.0__tar.gz → 0.22.1__tar.gz

{concurrent_c_node-0.22.0 → concurrent_c_node-0.22.1}/PKG-INFO

@@ -1,13 +1,17 @@
 Metadata-Version: 2.4
 Name: concurrent-c-node
-Version: 0.22.0
+Version: 0.22.1
 Summary: JavaScript and npm packages from Python over the Concurrent-C bridge: one spawned Node child per domain, host-controlled lifetime.
 License: MIT
 Project-URL: Repository, https://github.com/sreekotay/concurrent-c
 Project-URL: Documentation, https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/README.md
-Keywords: javascript,node,npm,interop,concurrent-c
+Keywords: javascript,node,npm,interop,concurrent-c,jupyter
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+Provides-Extra: jupyter
+Requires-Dist: ipython>=7; extra == "jupyter"
 
 # concurrent-c-node
 
@@ -36,9 +40,12 @@ semver.satisfies('1.2.3', '^1.0.0')  # True
 js.destroy()                         # or: with cc_node.create() as js:
 ```
 
-Unlike [`concurrent-c-python`](https://github.com/sreekotay/concurrent-c/tree/main/npm/cc-python)
-(in-process by default), every `create()` here is a separate Node —
-real addons, crash isolation, measurable wire. N domains = N processes.
+The other direction (Python from Node):
+[`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
+(in-process by default; vs pymport / ncp / pythonia in that README).
+
+Every `create()` here is a separate Node — real addons, crash isolation,
+measurable wire. N domains = N processes.
 
 | | this package | CC hosted (`cc_js_new(false, …)`) |
 |---|---|---|
@@ -49,13 +56,84 @@ real addons, crash isolation, measurable wire. N domains = N processes.
 | Parallelism | N children | one process |
 | Crash | child dies; parent lives | shared fate |
 
+**Cheat sheet**
+
+- Always a child `node`. A call blocks until JS answers; thenables wait
+  in the child. No `{ async: true }`.
+- Scalars / `None` materialize; empty `{}` stays a handle; everything
+  else is a `JsHandle` until `str()` / attrs / a call.
+- `%load_ext cc_node` then `%%js` — one kernel domain
+  (`cc_node.kernel()`), not a child per cell.
+- `eval()` is one RTT, no extra globals. `%%js` / `eval_cell` install
+  cwd `require` once.
+- `--bind` is `Object.assign(globalThis, …)` of names you name (wire
+  types only; no pickle). Missing names refuse.
+- First Ctrl-C finishes the in-flight call (wire stays in sync).
+  Interrupt again to kill the child.
+
 ```
-pip install concurrent-c-node          # needs node on PATH
+pip install concurrent-c-node                 # needs node on PATH
+pip install 'concurrent-c-node[jupyter]'      # magics (IPython)
 python -m cc_node.examples.use_node
 python -m cc_node.examples.bench_wire
 python -m cc_node.benchmarks.multi_domain
+python -m cc_node.benchmarks.vs_alts          # vs DIY node / pythonmonkey / mini-racer
+```
+
+## Jupyter / Colab
+
+Colab and the usual Jupyter kernel are **Python** — this package. Same
+calling convention as a script: a cell blocks until Node answers;
+thenables wait in the child. Magics share **one** domain for the
+kernel, not a spawn per cell (~28ms).
+
+```python
+%pip install concurrent-c-node
+# if `node` is missing (typical Colab):
+!apt-get install -y nodejs
+%load_ext cc_node
+
+%%js
+const path = require('path')
+path.join('a', 'b')          // last expression comes back as Python
+```
+
+```python
+xs = [1, 2, 3, 4]
+
+%%js -b xs -t chunks
+xs.map(x => x * 2)           // wire types only; no pickle fallback
 ```
 
+| | |
+|---|---|
+| `%load_ext cc_node` | register magics; does **not** spawn until first `%%js` |
+| `%js 1+1` / `%%js` | eval on `cc_node.kernel()`; last expression is the result |
+| `-b xs` / `--bind xs,n` | publish those Python names on `globalThis` for the cell |
+| `-t chunks` / `--to` | store the result in the notebook namespace |
+| `%js_stats` | handle-table size (spawns if needed) |
+| `%js_reset` | `destroy()` the kernel child; next `%%js` spawns again |
+| `cc_node.kernel()` | the same domain the magics use; `create()` is still a private child |
+| `JsHandle` display | cheap `JsHandle #3` — repr does not cross the wire |
+
+`eval()` is unchanged (one RTT, no extra globals). `%%js` / `eval_cell`
+install cwd `require` once so cells look like Node (`require('path')`).
+`--bind` is `Object.assign(globalThis, …)` — missing names and non-wire
+types (`DataFrame`, a set) fail articulately. Reserved names
+(`require`, `process`, `globalThis`, …) refuse so a bind cannot shadow
+Node.
+
+**Interrupt.** First Ctrl-C does not abandon the in-flight reply (that
+would desync the wire and drop callbacks). The call finishes, the result
+is discarded, the domain stays up. Interrupt again to **kill** the
+child — cooperative `destroy()` cannot stop a JS `for (;;) {}`. Same
+honesty as the rest of the bridge.
+
+JS kernels (`tslab`, Deno Jupyter) are
+[`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python);
+Colab is not that. There, default `create()` blocks the kernel thread —
+`py.task` / `{ isolated: true }` when the loop must stay live.
+
 ## Measured
 
 [`bench_wire`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/cc_node/examples/bench_wire.py)
@@ -73,6 +151,30 @@ python -m cc_node.benchmarks.multi_domain
 Wire: line-JSON on dedicated fds (stdio stays yours). Bulk spill: private
 0700 dir, 0600 files, removed with the bridge.
 
+### Vs pythonmonkey / mini-racer / DIY node
+
+Most “JS from Python” libraries are **not Node**. Bulk is a **sum** over
+1M floats (`.length` on an in-process wrapper is free and lies). Snapshot:
+[`cc_node_vs_alts_20260813.txt`](https://github.com/sreekotay/concurrent-c/blob/main/perf/baselines/cc_node_vs_alts_20260813.txt)
+· harness: [`benchmarks/vs_alts.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/cc_node/benchmarks/vs_alts.py).
+
+| | cc-node | DIY JSON stdio | `node -e` each | pythonmonkey | mini-racer |
+|---|---|---|---|---|---|
+| identity RTT | **20µs** | 39µs | 25ms | **<1µs** | 114µs |
+| callback | **36µs** | — | — | 1µs | — |
+| 8MB typed / list | **6.2ms shm** / 359ms | — / 197ms | — | — / 630ms proxy | — / 78ms |
+| `require('fs')` | yes | yes | yes | no | no |
+| process | child `node` | child `node` | new process/call | SpiderMonkey in-process | V8 isolate |
+
+Tiny scalars: pythonmonkey’s in-process SM beats a child. Real Node
+(`require('fs')`, native addons, callbacks, stdout stays yours): this
+package. Isolated `node -e` per call is ~1000× a persistent child.
+Optional engines SKIP if not importable — not package deps.
+
+The other direction (Python from Node):
+[`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
+vs pymport / ncp / pythonia.
+
 ## Surface
 
 - Plain data (numbers, str, bool, `None`, lists, non-empty dicts) by
@@ -80,6 +182,8 @@ Wire: line-JSON on dedicated fds (stdio stays yours). Bulk spill: private
   `String()`). Non-finite floats are tagged.
 - Handles are per-domain. `stats()` / `release()` / idempotent
   `destroy()`; afterwards: `bridge is closed`.
+- `eval_cell(src, bindings=)` is the notebook door (`%%js`): cwd
+  `require` once, optional `globalThis` binds; `eval()` stays one RTT.
 - Crash isolation, not a sandbox. `destroy()` is cooperative; an
   in-flight CPU-bound call finishes or you kill the child
   ([`bridge_stress.md`](https://github.com/sreekotay/concurrent-c/blob/main/stress/bridge/bridge_stress.md)).
@@ -176,7 +280,9 @@ Both bridges (npm OIDC + PyPI OIDC):
 # fallbacks: --npm-local / --pypi-twine
 ```
 
-Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`.  
+Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`,
+`benchmarks.vs_alts`.
+Jupyter: `%load_ext cc_node`.
 Stress: [`stress/bridge/`](https://github.com/sreekotay/concurrent-c/tree/main/stress/bridge).  
 Own hot path in C/CC → native module (40–90ns) —
 [JS / Python interop](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).

{concurrent_c_node-0.22.0 → concurrent_c_node-0.22.1}/README.md

@@ -25,9 +25,12 @@ semver.satisfies('1.2.3', '^1.0.0')  # True
 js.destroy()                         # or: with cc_node.create() as js:
 ```
 
-Unlike [`concurrent-c-python`](https://github.com/sreekotay/concurrent-c/tree/main/npm/cc-python)
-(in-process by default), every `create()` here is a separate Node —
-real addons, crash isolation, measurable wire. N domains = N processes.
+The other direction (Python from Node):
+[`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
+(in-process by default; vs pymport / ncp / pythonia in that README).
+
+Every `create()` here is a separate Node — real addons, crash isolation,
+measurable wire. N domains = N processes.
 
 | | this package | CC hosted (`cc_js_new(false, …)`) |
 |---|---|---|
@@ -38,13 +41,84 @@ real addons, crash isolation, measurable wire. N domains = N processes.
 | Parallelism | N children | one process |
 | Crash | child dies; parent lives | shared fate |
 
+**Cheat sheet**
+
+- Always a child `node`. A call blocks until JS answers; thenables wait
+  in the child. No `{ async: true }`.
+- Scalars / `None` materialize; empty `{}` stays a handle; everything
+  else is a `JsHandle` until `str()` / attrs / a call.
+- `%load_ext cc_node` then `%%js` — one kernel domain
+  (`cc_node.kernel()`), not a child per cell.
+- `eval()` is one RTT, no extra globals. `%%js` / `eval_cell` install
+  cwd `require` once.
+- `--bind` is `Object.assign(globalThis, …)` of names you name (wire
+  types only; no pickle). Missing names refuse.
+- First Ctrl-C finishes the in-flight call (wire stays in sync).
+  Interrupt again to kill the child.
+
 ```
-pip install concurrent-c-node          # needs node on PATH
+pip install concurrent-c-node                 # needs node on PATH
+pip install 'concurrent-c-node[jupyter]'      # magics (IPython)
 python -m cc_node.examples.use_node
 python -m cc_node.examples.bench_wire
 python -m cc_node.benchmarks.multi_domain
+python -m cc_node.benchmarks.vs_alts          # vs DIY node / pythonmonkey / mini-racer
+```
+
+## Jupyter / Colab
+
+Colab and the usual Jupyter kernel are **Python** — this package. Same
+calling convention as a script: a cell blocks until Node answers;
+thenables wait in the child. Magics share **one** domain for the
+kernel, not a spawn per cell (~28ms).
+
+```python
+%pip install concurrent-c-node
+# if `node` is missing (typical Colab):
+!apt-get install -y nodejs
+%load_ext cc_node
+
+%%js
+const path = require('path')
+path.join('a', 'b')          // last expression comes back as Python
+```
+
+```python
+xs = [1, 2, 3, 4]
+
+%%js -b xs -t chunks
+xs.map(x => x * 2)           // wire types only; no pickle fallback
 ```
 
+| | |
+|---|---|
+| `%load_ext cc_node` | register magics; does **not** spawn until first `%%js` |
+| `%js 1+1` / `%%js` | eval on `cc_node.kernel()`; last expression is the result |
+| `-b xs` / `--bind xs,n` | publish those Python names on `globalThis` for the cell |
+| `-t chunks` / `--to` | store the result in the notebook namespace |
+| `%js_stats` | handle-table size (spawns if needed) |
+| `%js_reset` | `destroy()` the kernel child; next `%%js` spawns again |
+| `cc_node.kernel()` | the same domain the magics use; `create()` is still a private child |
+| `JsHandle` display | cheap `JsHandle #3` — repr does not cross the wire |
+
+`eval()` is unchanged (one RTT, no extra globals). `%%js` / `eval_cell`
+install cwd `require` once so cells look like Node (`require('path')`).
+`--bind` is `Object.assign(globalThis, …)` — missing names and non-wire
+types (`DataFrame`, a set) fail articulately. Reserved names
+(`require`, `process`, `globalThis`, …) refuse so a bind cannot shadow
+Node.
+
+**Interrupt.** First Ctrl-C does not abandon the in-flight reply (that
+would desync the wire and drop callbacks). The call finishes, the result
+is discarded, the domain stays up. Interrupt again to **kill** the
+child — cooperative `destroy()` cannot stop a JS `for (;;) {}`. Same
+honesty as the rest of the bridge.
+
+JS kernels (`tslab`, Deno Jupyter) are
+[`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python);
+Colab is not that. There, default `create()` blocks the kernel thread —
+`py.task` / `{ isolated: true }` when the loop must stay live.
+
 ## Measured
 
 [`bench_wire`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/cc_node/examples/bench_wire.py)
@@ -62,6 +136,30 @@ python -m cc_node.benchmarks.multi_domain
 Wire: line-JSON on dedicated fds (stdio stays yours). Bulk spill: private
 0700 dir, 0600 files, removed with the bridge.
 
+### Vs pythonmonkey / mini-racer / DIY node
+
+Most “JS from Python” libraries are **not Node**. Bulk is a **sum** over
+1M floats (`.length` on an in-process wrapper is free and lies). Snapshot:
+[`cc_node_vs_alts_20260813.txt`](https://github.com/sreekotay/concurrent-c/blob/main/perf/baselines/cc_node_vs_alts_20260813.txt)
+· harness: [`benchmarks/vs_alts.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/cc_node/benchmarks/vs_alts.py).
+
+| | cc-node | DIY JSON stdio | `node -e` each | pythonmonkey | mini-racer |
+|---|---|---|---|---|---|
+| identity RTT | **20µs** | 39µs | 25ms | **<1µs** | 114µs |
+| callback | **36µs** | — | — | 1µs | — |
+| 8MB typed / list | **6.2ms shm** / 359ms | — / 197ms | — | — / 630ms proxy | — / 78ms |
+| `require('fs')` | yes | yes | yes | no | no |
+| process | child `node` | child `node` | new process/call | SpiderMonkey in-process | V8 isolate |
+
+Tiny scalars: pythonmonkey’s in-process SM beats a child. Real Node
+(`require('fs')`, native addons, callbacks, stdout stays yours): this
+package. Isolated `node -e` per call is ~1000× a persistent child.
+Optional engines SKIP if not importable — not package deps.
+
+The other direction (Python from Node):
+[`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
+vs pymport / ncp / pythonia.
+
 ## Surface
 
 - Plain data (numbers, str, bool, `None`, lists, non-empty dicts) by
@@ -69,6 +167,8 @@ Wire: line-JSON on dedicated fds (stdio stays yours). Bulk spill: private
   `String()`). Non-finite floats are tagged.
 - Handles are per-domain. `stats()` / `release()` / idempotent
   `destroy()`; afterwards: `bridge is closed`.
+- `eval_cell(src, bindings=)` is the notebook door (`%%js`): cwd
+  `require` once, optional `globalThis` binds; `eval()` stays one RTT.
 - Crash isolation, not a sandbox. `destroy()` is cooperative; an
   in-flight CPU-bound call finishes or you kill the child
   ([`bridge_stress.md`](https://github.com/sreekotay/concurrent-c/blob/main/stress/bridge/bridge_stress.md)).
@@ -165,7 +265,9 @@ Both bridges (npm OIDC + PyPI OIDC):
 # fallbacks: --npm-local / --pypi-twine
 ```
 
-Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`.  
+Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`,
+`benchmarks.vs_alts`.
+Jupyter: `%load_ext cc_node`.
 Stress: [`stress/bridge/`](https://github.com/sreekotay/concurrent-c/tree/main/stress/bridge).  
 Own hot path in C/CC → native module (40–90ns) —
 [JS / Python interop](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).

{concurrent_c_node-0.22.0 → concurrent_c_node-0.22.1}/cc_node/__init__.py

@@ -18,6 +18,9 @@ exceptions cross back as JS errors and vice versa, messages intact.
 Handles never cross domains; every door after destroy() answers
 articulately; destroy is idempotent and `with cc_node.create() as js:`
 scopes it.
+
+Notebooks (Jupyter / Colab): `%load_ext cc_node` then `%%js` — one
+kernel-scoped domain (`cc_node.kernel()`), same calling convention.
 """
 import array
 import atexit
@@ -25,12 +28,29 @@ import base64
 import json
 import math
 import os
+import re
+import select
 import shutil
 import subprocess
+import sys
 import tempfile
 
-__all__ = ["create", "JsError", "JsHandle", "__version__"]
-__version__ = "0.22.0"
+__all__ = [
+    "create", "kernel", "reset_kernel", "JsError", "JsHandle",
+    "load_ipython_extension", "unload_ipython_extension", "__version__",
+]
+__version__ = "0.22.1"
+
+_NO_NODE = (
+    "cc-node: no node executable (install Node, or set CC_NODE_BIN). "
+    "Colab/Jupyter: `!apt-get install -y nodejs` then retry, or pass "
+    "create(node=...) / CC_NODE_BIN."
+)
+_BIND_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_BIND_RESERVED = frozenset({
+    "require", "globalThis", "global", "process", "module", "exports",
+    "window", "self",
+})
 
 # Typed buffers cross as typed arrays; big ones spill through shared
 # memory (tmpfs where available) — one memcpy per side, receiver
@@ -97,9 +117,20 @@ class JsHandle:
         return self._d._req("str", h=self._h)
 
     def __repr__(self):
+        # Cheap: a wire str() is a round trip and can hang a display hook.
         return "<JsHandle #%d%s>" % (self._h,
                                      " (closed)" if self._d.closed else "")
 
+    def _repr_html_(self):
+        state = " closed" if self._d.closed else ""
+        return (
+            '<code title="domain-owned JS proxy; str() / attrs cross the wire">'
+            "JsHandle #%d%s</code>" % (self._h, state)
+        )
+
+    def _repr_pretty_(self, p, cycle):
+        p.text(repr(self))
+
     def __del__(self):
         # Never nest a sync wire op from GC into an in-flight _req — that
         # steals the outer reply (e.g. returning a callback arg handle).
@@ -117,6 +148,7 @@ class Bridge:
         broker = os.path.join(os.path.dirname(os.path.abspath(__file__)),
                               "broker.cjs")
         node = node or os.environ.get("CC_NODE_BIN", "node")
+        self._node_bin = node
         # Spills live in a private 0700 per-bridge directory (predictable
         # names in a shared /dev/shm invite pre-creation races and
         # umask-dependent exposure); the child writes its spills there
@@ -143,13 +175,14 @@ class Bridge:
             for fd in (req_r, req_w, resp_r, resp_w):
                 os.close(fd)
             shutil.rmtree(self._shm_dir, ignore_errors=True)
-            raise JsError(
-                "cc-node: no node executable (install Node, or set "
-                "CC_NODE_BIN)") from None
+            raise JsError(_NO_NODE) from None
         os.close(req_r)
         os.close(resp_w)
         self._wire_w = os.fdopen(req_w, "wb")
-        self._wire_r = os.fdopen(resp_r, "rb")
+        # Raw reply fd + leftover buffer: select then read, so SIGINT can
+        # land without mixing select() with a buffered file object.
+        self._resp_fd = resp_r
+        self._resp_buf = bytearray()
         self.closed = False
         self._nid = 1
         self._cbs = {}
@@ -160,6 +193,8 @@ class Bridge:
         self._pending_release = []
         self._close_pending = False
         self._destroy_done = False
+        self._cell_require_ready = False
+        self._cell_runner = None
         _live.append(self)
 
     # ---- wire ----
@@ -211,12 +246,84 @@ class Bridge:
             raise JsError(msg["e"])
         return self._decode_result(msg)
 
+    def _read_chunk(self):
+        fd = self._resp_fd
+        if fd is None:
+            return b""
+        if sys.platform == "win32":
+            try:
+                return os.read(fd, 65536)
+            except OSError:
+                return b""
+        while True:
+            try:
+                select.select([fd], [], [])
+            except InterruptedError:
+                continue
+            except OSError:
+                return b""
+            try:
+                return os.read(fd, 65536)
+            except InterruptedError:
+                continue
+            except OSError:
+                return b""
+
+    def _read_line(self):
+        """One wire line (without the LF), or b'' on EOF."""
+        while True:
+            nl = self._resp_buf.find(b"\n")
+            if nl >= 0:
+                line = bytes(self._resp_buf[:nl])
+                del self._resp_buf[:nl + 1]
+                return line
+            chunk = self._read_chunk()
+            if not chunk:
+                return b""
+            self._resp_buf.extend(chunk)
+
+    def _kill_child(self):
+        """Hard death from inside an in-flight wait. Cooperative close
+        cannot interrupt a JS CPU loop; SIGKILL of the child is the
+        second-interrupt door. `_req`'s finally runs `_finish_destroy`."""
+        self.closed = True
+        self._close_pending = True
+        try:
+            if self._p.poll() is None:
+                self._p.kill()
+        except Exception:
+            pass
+
+    def _complete_reply(self, msg, hits):
+        if hits:
+            try:
+                self._take_reply(msg)
+            except JsError:
+                raise
+            raise KeyboardInterrupt(
+                "cc-node: call finished after interrupt; result discarded"
+            ) from None
+        return self._take_reply(msg)
+
     def _wait_reply(self, rid):
-        parked = self._parked.pop(rid, None)
-        if parked is not None:
-            return self._take_reply(parked)
+        hits = 0
         while True:
-            line = self._wire_r.readline()
+            parked = self._parked.pop(rid, None)
+            if parked is not None:
+                return self._complete_reply(parked, hits)
+            try:
+                line = self._read_line()
+            except KeyboardInterrupt:
+                hits += 1
+                if hits == 1:
+                    sys.stderr.write(
+                        "cc-node: JS still running — interrupt again to "
+                        "destroy this domain\n")
+                    sys.stderr.flush()
+                    continue
+                self._kill_child()
+                raise KeyboardInterrupt(
+                    "cc-node: interrupted; domain destroyed") from None
             if not line:
                 self.closed = True
                 raise JsError("cc-node: the node child exited")
@@ -226,7 +333,7 @@ class Bridge:
                 continue
             mid = msg.get("id")
             if mid == rid:
-                return self._take_reply(msg)
+                return self._complete_reply(msg, hits)
             if mid is not None:
                 # Nested _req (GC release, etc.) can overtake; park by id.
                 self._parked[mid] = msg
@@ -407,6 +514,59 @@ class Bridge:
     def eval(self, src):
         return self._req("eval", src=src)
 
+    def eval_cell(self, src, bindings=None):
+        """Eval JS in this domain. Optional `bindings` are published on
+        `globalThis` for the call (`Object.assign`). Installs cwd
+        `require` once so a notebook cell can `require('path')` like
+        Node. `eval()` itself does not install `require` and does not
+        take bindings — one RTT, unchanged."""
+        if self.closed:
+            raise JsError("cc-node: bridge is closed")
+        self._ensure_cell_require()
+        if not bindings:
+            return self.eval(src)
+        names = {}
+        for k, v in bindings.items():
+            self._check_bind_name(k)
+            names[k] = v
+        runner = self._cell_runner
+        if runner is None:
+            runner = self.eval(
+                "(b, src) => { Object.assign(globalThis, b); "
+                "return (0, eval)(src); }")
+            self._cell_runner = runner
+        return runner(names, src)
+
+    def _ensure_cell_require(self):
+        if self._cell_require_ready or self.closed:
+            return
+        install = self.eval(
+            "(m) => { globalThis.require = "
+            "m.createRequire(process.cwd() + '/'); }")
+        mod = self.require("module")
+        try:
+            install(mod)
+            self._cell_require_ready = True
+        finally:
+            try:
+                self.release(mod)
+            except Exception:
+                pass
+            try:
+                self.release(install)
+            except Exception:
+                pass
+
+    @staticmethod
+    def _check_bind_name(name):
+        if not isinstance(name, str) or not _BIND_NAME.match(name):
+            raise JsError(
+                "cc-node: --bind name %r is not a JS identifier" % (name,))
+        if name in _BIND_RESERVED:
+            raise JsError(
+                "cc-node: --bind name %r is reserved (would shadow a "
+                "Node global)" % (name,))
+
     def release(self, handle):
         if not isinstance(handle, JsHandle) or handle._d is not self:
             raise JsError("cc-node: handle belongs to another bridge")
@@ -449,7 +609,7 @@ class Bridge:
         # land — closing the reply fd under its write is an EPIPE crash
         # in the child.
         try:
-            while self._wire_r.readline():
+            while self._read_line():
                 pass
         except Exception:
             pass
@@ -461,9 +621,12 @@ class Bridge:
             except Exception:
                 pass
         try:
-            self._wire_r.close()
+            if self._resp_fd is not None:
+                os.close(self._resp_fd)
         except Exception:
             pass
+        self._resp_fd = None
+        self._cell_runner = None
         shutil.rmtree(self._shm_dir, ignore_errors=True)
         if self in _live:
             _live.remove(self)
@@ -480,3 +643,48 @@ class Bridge:
 
 def create(node=None):
     return Bridge(node=node)
+
+
+_kernel = None
+
+
+def kernel(node=None):
+    """Process-wide domain for notebooks. Lazy; magics share it.
+    Scripts that want a private child still call `create()`."""
+    global _kernel
+    b = _kernel
+    if b is not None and not b.closed:
+        if node is not None and node != b._node_bin:
+            raise JsError(
+                "cc-node: kernel() already live with a different node; "
+                "reset_kernel() / %js_reset first")
+        return b
+    b = create(node=node)
+    try:
+        b._ensure_cell_require()
+    except Exception:
+        b.destroy()
+        raise
+    _kernel = b
+    return b
+
+
+def reset_kernel():
+    """Destroy the kernel-scoped domain. Next `kernel()` / `%%js` spawns."""
+    global _kernel
+    b = _kernel
+    _kernel = None
+    if b is not None:
+        try:
+            b.destroy()
+        except Exception:
+            pass
+
+
+def load_ipython_extension(ip):
+    from .magics import load_ipython_extension as _load
+    _load(ip)
+
+
+def unload_ipython_extension(ip):
+    reset_kernel()