@tlockney/cdp-kernel 0.4.0 → 0.6.0

package/README.md

@@ -1,507 +1,107 @@
 # cdp-kernel
 
-A Jupyter kernel extracted from Deno's (`deno jupyter`, v2.9.6) that drives
-any V8 runtime over the Chrome DevTools Protocol. The kernel host runs on
-Node or Deno; the code you type runs in a separate **target** runtime:
-Node or Deno over CDP. Bun, workerd and celld evaluate cells in-process
-instead (see [Bun](#bun), [workerd](#workerd) and [celld](#celld)). In
-principle, anything else whose inspector speaks CDP works too.
+A Jupyter kernel for TypeScript and JavaScript, extracted from the one built
+into Deno 2.9.6 (`deno jupyter`), that runs notebooks on several JavaScript runtimes. The kernel
+host runs on Node or Deno; the code you type runs in a separate **target**
+runtime: Node or Deno over the Chrome DevTools Protocol, or Bun, workerd and
+celld, which evaluate cells in-process. In principle, anything else whose
+inspector speaks CDP works too.
 
-This is early software. It passes a conformance suite derived from Deno's
-own Jupyter integration tests on every target, and it's packaged for npm and
-JSR as `@tlockney/cdp-kernel`, but it hasn't seen much real use yet. The
-feasibility study behind it covers the design,
-the other options considered (workerd, Bun, rusty_v8, FFI), and the
-evidence: [read it online](https://claude.ai/artifact/S66TnTmhCzPy2EW7jbeeue)
-(also in the repo as
-[`docs/life-after-deno-jupyter.html`](docs/life-after-deno-jupyter.html)). It
-was written before packaging, so it calls the project a spike.
-The scripts that produced its runtime findings are in [`probes/`](probes/).
-
-## Why this shape
+**Website:** <https://cdp-kernel.org/> ·
+**Docs:** [cdp-kernel.org/docs](https://cdp-kernel.org/docs/)
 
-Deno 2.9's kernel is already two halves joined by thirteen ops
-(denoland/deno#34083 rewrote it in JS and dropped libzmq):
+[![Try it on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/tlockney/cdp-kernel/main?urlpath=lab/tree/getting-started.ipynb)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tlockney/cdp-kernel?quickstart=1)
 
-- `cli/js/jupyter_kernel.js`: ZMTP and the Jupyter wire protocol in plain
-  JS over TCP.
-- A REPL isolate driven by CDP calls: `Runtime.evaluate` with
-  `replMode: true`, `callFunctionOn`, `getProperties`,
-  `globalLexicalScopeNames`.
+Binder opens JupyterLab with every runtime and the example notebooks,
+nothing installed. A Codespace does the same in VS Code, with the
+repository checked out ([Install › In a container](https://cdp-kernel.org/docs/install#in-a-container)).
 
-So the extraction is:
-
-- Port the protocol half to `node:net` and `node:crypto`: `src/zmtp.ts`,
-  `src/wire.ts`, `src/kernel.ts`.
-- Point the CDP half at another runtime's `--inspect` WebSocket:
-  `src/target.ts`, `src/cdp.ts`.
-- Replace what Deno's module loader did with esbuild + acorn
-  (`src/transform.ts`) and Node resolve hooks (`runtime/node-hooks.mjs`).
-- Port `Deno.jupyter` (`40_jupyter.js`) to `runtime/display.mjs`.
+This is early software. It passes a conformance suite derived from Deno's
+own Jupyter integration tests on every target, and it's packaged for npm and
+JSR as `@tlockney/cdp-kernel`, but it hasn't seen much real use yet.
+The [support policy](https://cdp-kernel.org/docs/support) says which
+runtime versions and frontends are supported, and what may change before
+1.0.
+
+## Features
+
+- The `Deno.jupyter` display API (`jupyter.display`, `md`, `html`, `svg`,
+  `image`, …) on every target.
+- TypeScript, TSX, top-level `await`, and `npm:`/`jsr:` imports, with an
+  optional lockfile.
+- Deno projects (`deno.json` import maps, JSX settings) and Workers
+  projects (`wrangler` bindings in `env`).
+- JupyterLab's visual debugger on Node and Deno targets.
+- anywidget-style widgets and Jupyter comms.
+- `prompt()` and `confirm()`, interrupt that keeps state, Shift-Tab
+  inspection, completion and history.
 
 ## Install
 
-Each install writes a Jupyter kernelspec: `cdp-node`, `cdp-deno`,
-`cdp-node-deno` (Node with the Deno compatibility namespace), `cdp-bun`,
-`cdp-workerd`, or `cdp-celld`. Then pick the kernel in JupyterLab or VS Code.
-
-**From npm** (host runs on Node 24+). CI tests Node 24 and 26 with Deno 2.9
-and the latest 2.x, on Linux and macOS. Windows isn't supported yet.
+Node 22.18+ host, from npm:
 
 ```sh
 npm install -g @tlockney/cdp-kernel
-cdp-kernel install --runtime node
-cdp-kernel install --runtime deno
-cdp-kernel install --runtime node --deno-compat
-cdp-kernel install --runtime bun
-cdp-kernel install --runtime workerd
-cdp-kernel install --runtime celld
+cdp-kernel install --runtime node   # or deno, bun, workerd, celld
 ```
 
-The kernelspec records the absolute paths of `node` and the installed
-package. Re-run `install` after upgrading either.
-
-**From JSR** (host runs on Deno):
+Deno host, from JSR:
 
 ```sh
 deno run -A jsr:@tlockney/cdp-kernel/cli install --runtime deno
 ```
 
-The kernelspec pins the release it was installed from
-(`jsr:@tlockney/cdp-kernel@<version>/cli`). On first launch the target's
-runtime modules are copied into `~/.cache/cdp-kernel/runtime/`. A Node
-target needs `node` on `PATH`, and a Bun target needs `bun` (1.4 is what's
-been tested). A workerd target uses the `workerd` in the notebook
-directory's `node_modules` (a Workers project has one through wrangler),
-or the one on `PATH` (`npm install -g workerd`; 2026-10-15 is what's been
-tested). A celld target uses `~/.local/bin/celld`, where celld's installer
-puts it, or the one on `PATH` (0.6.2 is what's been tested; celld has no
-Windows build).
-
-Deno 2.9+ refuses package versions less than 24 hours old by default
-([minimum dependency age](https://docs.deno.com/go/minimum-dependency-age)).
-In a release's first day, the install command fails with "blocked by the
-minimum dependency age policy". Pass `--min-dep-age=0` to the install
-command to get it through:
-
-```sh
-deno run -A --min-dep-age=0 jsr:@tlockney/cdp-kernel/cli install --runtime deno
-```
-
-The kernelspec it writes works on release day too. It relaunches the kernel
-with a dependency cutoff of two days after the release
-(`--min-dep-age=<date>`), so it never resolves anything published after
-that.
+Each install writes a Jupyter kernelspec (`cdp-node`, `cdp-deno`, …). Pick
+it in JupyterLab or VS Code. To run notebooks with no Python installed,
+serve JupyterLab with
+[Ganymede](https://ganymede-server.com/docs/workstation). Linux and macOS
+are supported; Windows isn't yet. See
+[Install](https://cdp-kernel.org/docs/install) for `--deno-compat`, release-day installs on Deno, target runtime
+requirements, and installing from a checkout.
 
-**From a checkout**, for working on the kernel itself:
+JupyterLab with every runtime and the examples, in a container:
 
 ```sh
-npm ci
-npm run install:node        # kernelspec cdp-node
-npm run install:deno        # kernelspec cdp-deno
-npm run install:node-deno   # kernelspec cdp-node-deno
-npm run install:bun         # kernelspec cdp-bun
-npm run install:workerd     # kernelspec cdp-workerd
-npm run install:celld       # kernelspec cdp-celld
+docker run --rm -p 8888:8888 ghcr.io/tlockney/cdp-kernel
 ```
 
-These kernelspecs point at the checkout, so don't move it after installing.
-
-In a cell:
-
-- `jupyter.display`, `jupyter.md`, `jupyter.html`, `jupyter.svg`,
-  `jupyter.image`, `jupyter.format`, `jupyter.broadcast`, and
-  `Symbol.for("Jupyter.display")`: the same API as `Deno.jupyter`.
-- `Deno.jupyter` also works:
-  - On a Deno target it is a proxy over the real namespace. Deno's own
-    getter throws outside `deno jupyter`.
-  - On Node it needs `--deno-compat`. That installs a `Deno` namespace for
-    file, env and process APIs (`runtime/deno-compat.mjs`).
-  - The shim is opt-in because libraries detect Deno with `typeof Deno`, and
-    would take Deno code paths that call APIs it doesn't cover.
-- Imports work: TypeScript, TSX, enums, top-level `await`, and `const`
-  redeclaration across cells. Specifiers can be `./local.ts`, bare packages
-  from the notebook's `node_modules`, `node:` builtins, and `npm:pkg@range`
-  or `jsr:@scope/pkg@range`.
-  - On Node, `npm:` and `jsr:` install on first use into
-    `~/.cache/cdp-kernel/npm`. An exact version (`npm:react@19.0.0`) installs
-    exactly that version. A range (`npm:react@19`) is resolved the first
-    time it's imported and stays at that version, even as other packages
-    are installed later. Caches written by cdp-kernel 0.3.0 or earlier
-    recorded ranges, which later installs could re-resolve. Delete
-    `~/.cache/cdp-kernel/npm` to start fresh. `jsr:` works with npm 12,
-    which otherwise refuses JSR's registry tarballs.
-  - **Lockfile** (cdp-kernel 0.4.0 or later). To pin versions, create a `cdp-kernel.lock.json` in the
-    notebook's directory (or above it) containing `{}`. From then on, each
-    `npm:`/`jsr:` range is recorded with the exact version it resolved to,
-    and installed at that version, so the notebook gets the same packages
-    on another machine. Commit it next to the notebook. Deno targets use
-    Deno's own resolution and lock instead. Installs into the shared cache
-    are serialized, so two kernels installing at once can't corrupt it.
-  - On Deno they use Deno's global cache, unless the notebook is in a Deno
-    project (below).
-  - On Bun they install with `bun add` into `~/.cache/cdp-kernel/bun`. Other
-    bare imports resolve from the notebook's directory, so without a
-    `node_modules` there, Bun auto-installs them.
-  - On workerd, the host bundles every import other than a builtin
-    (`node:`, `cloudflare:`) with esbuild, using Workers' resolution
-    conditions, and sends it with the cell. `npm:` and `jsr:` install into
-    the npm cache first, as on Node.
-- **Deno projects.** If a `deno.json` or `deno.jsonc` sits in the notebook's
-  directory or above it, a Deno target uses it, as `deno jupyter` does:
-  - its import map (`"@/": "./lib/"` aliases, mapped packages);
-  - its `nodeModulesDir` setting, with `package.json` dependencies from the
-    project's `node_modules`;
-  - its JSX and decorator `compilerOptions`: `jsx` (`react-jsx`,
-    `react-jsxdev`, `precompile`, `react`), `jsxImportSource`,
-    `jsxFactory`, `jsxFragmentFactory`, `experimentalDecorators`.
-
-  The import map wins over `node_modules`, as in Deno. The kernel never
-  writes to the project's lockfile. A `deno.json` that doesn't parse is
-  reported in the first cell's output, and the kernel runs as in a plain
-  directory. Outside a project, the target runs with
-  `--node-modules-dir=none --no-lock`.
-- `prompt()` and `confirm()` work over the stdin channel, except on
-  workerd. Interrupt keeps state, except for a busy cell on Bun or workerd
-  (below).
-- **Shift-Tab** shows a tooltip for the name at the cursor: its type, a
-  function's signature (and its source at the second press), a preview, and
-  its properties. Nothing is run to get it. On Node and Deno the value is
-  evaluated with V8's side-effect check (`throwOnSideEffect`), which also
-  guards completion. Bun, workerd and celld look the name up by property,
-  without calling getters. Executed cells are kept for `history_request`
-  (tail, range and search).
-
-## Bun
-
-Bun's `--inspect` speaks the WebKit Inspector Protocol, which lacks what the
-CDP backend relies on: `replMode`, `Runtime.addBinding`,
-`Runtime.terminateExecution`, and top-level `await` in `Runtime.evaluate`.
-So the Bun target has its own backend (`src/bun-target.ts`,
-`runtime/bun-channel.mjs`):
-
-- **No inspector.** The host and Bun exchange JSON lines over a pipe on
-  fd 3, which only the host holds, so there is no port to discover.
-- **Cells run in-process.** Each cell becomes global code wrapped in an
-  async function (`transformCellForEval` in `src/transform.ts`). Its
-  top-level declarations become properties of `globalThis`, so later
-  cells, and closures from this one, see them. This is the
-  tslab/IJavascript technique.
-- **Same output ordering.** stdout and stderr stay pipes, ordered against
-  display messages by the same barrier markers as the CDP targets.
-- **Interrupt.** A cell that's waiting on a promise is interrupted in place,
-  keeping state. A busy one (`while (true) {}`) can't be reached, so Bun is
-  stopped and restarts on the next cell without the earlier state. The cell
-  output says so.
-
-What differs from the CDP targets is listed under [Known gaps](#known-gaps).
-
-## workerd
-
-workerd's inspector can evaluate code, but outside a request there is no
-I/O context: timers, `fetch` and `crypto.randomUUID()` throw "Disallowed
-operation called within global scope". So the workerd target runs its
-cells inside a driver Worker (`src/workerd-target.ts`,
-`runtime/workerd-worker.mjs`):
-
-- **One session.** The host opens a single WebSocket to the driver, and
-  every cell runs inside that session's request. Cells get Workers'
-  `fetch`, `Request`, `caches`, timers and randomness, and anything one
-  cell makes carries over to the next: globals, a Durable Object stub, a
-  stream, a timer still pending.
-- **A private socket.** Outside a Workers project, the host writes a
-  workerd config into a private temporary directory and serves the driver
-  on a Unix socket there, opened with a per-launch token. There is no TCP
-  port and no inspector.
-- **Cells.** Cells are transformed as for Bun and run by workerd's
-  `UnsafeEval` binding (hence `--experimental`).
-- **Output.** `console` output and display messages come back over the
-  session as they happen, in order.
-- **Interrupt.** A cell that's waiting on something is abandoned in place,
-  keeping state, as on Bun. A busy one gets Bun's treatment too: workerd is
-  stopped and restarts on the next cell.
-
-What workerd's own process prints, such as its warnings, goes to the Jupyter
-server log, not the notebook.
-
-### Workers projects
-
-If a `wrangler.jsonc`, `wrangler.json` or `wrangler.toml` sits in the
-notebook's directory or above it, the driver runs on the project's own
-Miniflare, the simulator `wrangler dev` uses, with the project's bindings
-(`src/workers-project.ts`):
-
-- `env` holds the bindings: whatever wrangler translates for Miniflare.
-  Vars, KV, D1 and Durable Objects are tested; R2, Queues and the others
-  go through the same path but aren't.
-- The project's `main` is bundled into the driver, so its Durable Object
-  classes run, and `worker` is its default export:
-  `await worker.fetch(new Request("https://x/"), env)`.
-- State lives in the project's `.wrangler/state/cdp-kernel`, beside
-  `wrangler dev`'s own, so the two never open the same Durable Object.
-- The first cell's output names the bindings. If the project can't load,
-  for example because wrangler isn't installed in it, the first cell says
-  why and the kernel runs on plain workerd.
-
-wrangler and Miniflare come from the project's `node_modules`, so they match
-its versions. Miniflare 4 and 5 both work. Miniflare listens on a loopback
-TCP port, so there the per-launch token is what keeps other local processes
-out.
-
-## celld
-
-[celld](https://github.com/denoland/celld) runs Workers and Durable Objects
-on your own storage. Like workerd it has no I/O outside a request, so the
-celld target runs the same driver Worker over the same WebSocket session
-(`src/celld-target.ts`). Cells, output, interrupts and host-bundled imports
-all work as on workerd. The differences:
-
-- **No `UnsafeEval` needed.** celld allows a plain global `eval`, so it runs
-  without workerd's `--experimental`.
-- **One module.** The host bundles the driver, and a project's `main`, into
-  a single module, and gives celld the result with `no_bundle`. celld
-  doesn't need its own esbuild.
-- **Loopback TCP.** celld listens only on TCP, so the session is a loopback
-  WebSocket opened with a per-launch token. The kernel picks a free port
-  and runs `celld dev --no-watch` on a generated config.
-- **Projects.** In a celld project (a `wrangler.jsonc` or `wrangler.json`
-  at or above the notebook), the generated config copies the project's
-  compatibility settings and bindings: vars, KV, D1, R2, Durable Objects,
-  Queues, Workflows, services, Worker Loaders. `env` and `worker` then work
-  as on workerd. The generated config is written to the project's
-  `.celld/cdp-kernel` and removed when the kernel stops. The state stays
-  there across kernels, beside `celld dev`'s own `.celld/dev`. celld rejects `wrangler.toml`; a project
-  that can't load is reported in the first cell, and the driver runs alone.
-- **Stopping.** `celld dev` runs its node in a separate process group and
-  waits for it to stop gracefully, which a busy cell never allows. So an
-  interrupt of a busy cell kills the node, then `celld dev`.
-
-## Debugger
-
-On Node and Deno targets, JupyterLab's visual debugger works: the bug
-button in the notebook toolbar, breakpoints in the cell gutter, the call
-stack, variables and scopes, stepping, pause on exceptions, the debug
-console, and the rich variable viewer. The kernel translates the Jupyter
-debug protocol (DAP over `debug_request`) to V8's `Debugger` domain on the
-session it already holds (`src/debugger.ts`):
-
-- **Cell paths.** Each cell is named as JupyterLab names it: a temp-dir
-  prefix plus the Murmur2 hash of its code (`src/murmur2.ts`, matched
-  against ipykernel's). It's evaluated with that name as its
-  `//# sourceURL`, so breakpoints bind to the cell and frames point back at
-  it.
-- **Lines.** Breakpoint and frame lines go through the cell's source map
-  (`src/sourcemap.ts`), since esbuild rewrites the TypeScript. A breakpoint
-  on a blank or type-only line moves to the next statement.
-- **Nothing runs on its own.** The variable explorer between cells reads
-  the cells' declarations with V8's side-effect check, so a getter never
-  runs. Frames, scopes and the rich viewer evaluate on the paused frame.
-- **Kernelspec.** `metadata.debugger` is set for Node and Deno kernelspecs,
-  which is what JupyterLab checks. Reinstall older kernelspecs to get it.
-
-`CDPK_DEBUG_TRACE=1` logs every debug request, reply and event to the
-Jupyter server's log.
-
-Bun, workerd and celld don't run over an inspector, so they have no
-debugger.
-
-## Editor types
-
-Cells run untyped, as in `deno jupyter`. Notebook code your editor
-type-checks can declare the globals.
-
-**Node notebooks.** The npm package ships the declarations. Add it as a dev
-dependency, then reference it once from a cell or a `.d.ts` in the project:
-
-```ts
-/// <reference types="@tlockney/cdp-kernel/globals" />
-await jupyter.display(jupyter.md`typed`);
-const name: string | null = prompt("Name?", "", { password: false });
-```
-
-That declares `jupyter`, `prompt` and `confirm`. With the `cdp-node-deno`
-kernel, use `@tlockney/cdp-kernel/globals/deno-compat` instead: it adds the
-`Deno` namespace the compatibility shim implements. A custom display is a
-class with a `[jupyter.$display]()` method returning a MIME bundle.
-`jupyter.$display` is `Symbol.for("Jupyter.display")` at runtime, but only
-`jupyter.$display` carries the precise type.
-
-**Deno notebooks.** Use `Deno.jupyter`, which Deno already types and which a
-Deno target provides. The JSR package doesn't ship these globals, because
-JSR doesn't allow packages to augment global types.
-
-## Widgets and comms
-
-`deno jupyter` has no comms. Here they're supported in both directions, so
-anywidget-style widgets work in frontends with the `anywidget` extension:
-JupyterLab, Notebook 7 and VS Code. Install it with
-`pip install anywidget`; that's the frontend half, no Python kernel needed.
+## Quick start
 
 ```ts
-const counter = jupyter.widget({
-  esm: `export default {
-    render({ model, el }) {
-      const btn = document.createElement("button");
-      const update = () => { btn.textContent = \`count is \${model.get("count")}\`; };
-      btn.onclick = () => { model.set("count", model.get("count") + 1); model.save_changes(); };
-      model.on("change:count", update);
-      update();
-      el.append(btn);
-    },
-  };`,
-  state: { count: 0 },
-});
-counter.on("change:count", (value) => console.log("clicked to", value));
-counter; // display it
-```
-
-The model API:
-
-- `get(key)`, and `set(key, value)` or `set({ ... })`, which syncs to every
-  view.
-- `on("change:key" | "change" | "msg:custom", listener)` and `off(...)`.
-- `send(content, buffers)` for custom messages.
-- `close()`.
-
-`Uint8Array`, `ArrayBuffer` and `DataView` values in the state travel as
-binary buffers. JupyterLab restores widget state after a page reload over
-the `jupyter.widget.control` comm.
+import { format } from "npm:date-fns@4";
 
-The comm layer underneath is available directly, for other comm-based
-protocols:
-
-```ts
-const comm = jupyter.comm.open("my.target", { hello: 1 });
-comm.onMsg(({ data, buffers }) => console.log(data, buffers.length));
-comm.send({ ping: true });
-jupyter.comm.registerTarget("echo", (comm) => comm.onMsg((m) => comm.send(m.data)));
+const now: Date = new Date();
+await jupyter.display(jupyter.md`**Today** is ${format(now, "PPPP")}`);
 ```
 
-Comm handlers run like cells. Their output goes to the notebook as replies
-to the message that triggered them, an exception is shown on stderr, and
-interrupt stops a stuck handler. Messages are processed one at a time with
-cell executions, as in ipykernel, so a widget event that arrives during a
-long cell waits for the cell to finish.
-
-## How the tricky parts work
-
-| Problem | Approach |
-|---|---|
-| Inspector-evaluated code has no module referrer, so Node rejects `import()` | Static imports are rewritten to `var x = (await __cdpk.import("m")).x` (Deno's `var_decl_imports`), and `import()` and `import.meta` go through the bootstrap module. A resolve hook re-parents those imports to the notebook directory. |
-| A busy loop inside `Runtime.evaluate` blocks every inspector message, so interrupt is never seen | Each cell starts with `await __cdpk.tick()` (one macrotask), so user code runs as an ordinary task. `Runtime.terminateExecution` then arrives on a second CDP session. The host abandons the evaluate, whose promise never settles. |
-| stdout/stderr arrive over pipes and display messages over the WebSocket, so they race | Every display message is preceded by a numbered marker on both pipes. The host releases the message only after both pipes reach the marker, and holds later pipe output until the message is out. |
-| `prompt()` must be synchronous | The target sends an `input_request` through a CDP binding, then blocks on a `readSync` of stdin. The host writes the reply as one JSON line. |
-| Uncaught errors from timers would kill the target | `uncaughtException` and `unhandledrejection` handlers report them to stderr. |
-
-## Tests
-
-```sh
-npm run check  # tsc --strict over src/ and test/
-npm test       # unit tests (node:test)
-npm run e2e    # conformance suite via jupyter_client/libzmq, on every target variant
-npm run test:lab   # an anywidget counter in real JupyterLab, headless Chromium (node, deno, bun, workerd, celld)
-uv run --with nbclient --with nbformat python examples/run_notebook.py   # Deno-style notebook on deno + node-deno
-```
-
-The e2e suite follows Deno's `tests/integration/jupyter_tests.rs` and adds
-the gaps those tests leave: display ordering, TS, imports, `npm:`/`jsr:`,
-completion, and `update_display_data`. Set `CDPK_E2E_OFFLINE=1` to skip the
-registry-dependent checks. Set `CDPK_E2E_CLI` to run it through a different
-CLI: an installed npm bin, or `deno run -A src/main.ts` to test a Deno host.
-
-## Releasing
-
-One version number lives in three places: `package.json`, `deno.jsonc` and
-`src/package.ts`. `test/package.test.ts` fails if they disagree. To release:
-
-1. Bump all three, and set `RELEASE_DATE` in `src/package.ts` to today
-   (UTC). Commit, and merge to `main`.
-2. Tag and push: `git tag v0.1.1 && git push origin v0.1.1`.
-
-The `publish` workflow then:
-
-1. Checks that the tag matches the version, and that `RELEASE_DATE` is
-   today or yesterday. A JSR kernelspec's dependency cutoff comes from that
-   date, so a stale one would block the release it ships in.
-2. Runs the type check, the unit tests, and the e2e suite against the packed
-   npm tarball and against a Deno host.
-3. Publishes to JSR (`deno publish`).
-4. Publishes to npm (`npm publish`).
-
-Both registries authenticate the workflow through GitHub OIDC, so no tokens
-are stored:
-- **npm:** a trusted publisher for `tlockney/cdp-kernel` + `publish.yml`.
-- **JSR:** the package is linked to this repo in its JSR settings.
-
-Neither registry lets a version be republished. Each job skips a version
-its registry already has, so re-running a release only fills in the half
-that failed.
-
-## Known gaps
-
-- Widgets are anywidget-style (`jupyter.widget`). The classic ipywidgets
-  controls (sliders, dropdowns) are Python classes, so they're not available.
-- Inspection tooltips show what's found at runtime (type, signature,
-  preview, properties), not TypeScript types or JSDoc. On Bun, workerd and
-  celld, a getter on the path is reported but not called. History is kept
-  for the current kernel session only.
-- The debugger is for Node and Deno targets only. Breakpoints are per line,
-  conditional breakpoints and logpoints aren't supported, variables can't be
-  set from the debugger, and "copy to globals" isn't offered.
-- `npm:` on Node, Bun, workerd and celld:
-  - one npm alias per `name@range` (or exact version, when locked);
-  - the cache is shared by every notebook, so peer dependencies resolve by
-    real name from it;
-  - a project's own `package.json` doesn't decide an `npm:` import's version
-    (bare imports do use its `node_modules`).
-- No type checking. Deno doesn't type-check REPL cells either.
-- Results are formatted by each runtime's own inspector: `util.inspect` on
-  Node, Bun, workerd and celld, and `Deno.inspect` on Deno. On a fixture of
-  30 typical values, 23 format identically on Node and Deno. The rest
-  differ in two ways:
-  - strings are quoted `'…'` on Node and `"…"` on Deno, wherever they
-    appear;
-  - a displayed `Error`'s stack also lists Node's own module-loader frames.
-
-  That's deliberate: each runtime's users see the format they expect, and
-  Node's inspector has no quote-style option, short of porting Deno's
-  formatter. `test/formatting.test.ts` runs both runtimes on the fixture
-  and fails if a new kind of difference appears (#17).
-- WebGPU texture and buffer display is dropped.
-- On Bun:
-  - Interrupting a busy cell restarts Bun and loses state. An awaiting cell
-    keeps it.
-  - Top-level declarations are properties of `globalThis`. A `const` can be
-    reassigned, and declaring a global's name (`const fetch = ...`) replaces
-    that global rather than shadowing it.
-  - Only a trailing expression statement shows a result: `x` does, but
-    `if (c) { x }` doesn't.
-  - Bun 1.4 can't import a module whose path contains `?`.
-  - No `--deno-compat` namespace.
-- On workerd:
-  - All cells share one request, so it never ends. Unlike production
-    Workers, there is no per-request CPU or duration limit, and
-    `ctx.waitUntil` isn't available in a cell.
-  - No `prompt()` or `confirm()` answers: they return `null`, as without a
-    stdin channel. `jupyter.image(path)` can't read files; pass the bytes.
-  - Each imported module is bundled with its dependencies. Two imports that
-    share a dependency each get their own copy.
-  - Interrupting a busy cell restarts workerd and loses state.
-  - Top-level declarations and results behave as on Bun: declarations are
-    `globalThis` properties, and only a trailing expression shows a result.
-  - In a Workers project, `main` is bundled with esbuild directly, not with
-    wrangler's build. Custom `build` commands, `alias` and module `rules`
-    aren't applied.
-- On celld, as on workerd, except:
-  - Only the binding and compatibility keys of a project's config are
-    copied. `assets`, `triggers` and `containers` aren't, and neither is
-    `.dev.vars`. Relative paths inside the copied keys resolve from
-    `.celld/cdp-kernel`, not from the project.
-  - Interrupting a busy cell restarts celld and loses state.
-
-## Provenance
-
-`src/zmtp.ts`, `src/wire.ts`, `src/kernel.ts`, `src/text.ts` and
-`runtime/display.mjs` are ports of Deno's `cli/js/jupyter_kernel.js` and
-`cli/js/40_jupyter.js` at v2.9.6 (commit `e518fbd`), Copyright 2018-2026 the
-Deno authors, MIT license. Each file header says which parts.
+## Documentation
+
+New to Jupyter? Start with
+[Getting started](https://cdp-kernel.org/docs/getting-started).
+
+- Guides: [Writing notebooks](https://cdp-kernel.org/docs/notebooks),
+  [The `jupyter` namespace](https://cdp-kernel.org/docs/jupyter-api),
+  [Choosing a runtime](https://cdp-kernel.org/docs/runtimes),
+  [Widgets and comms](https://cdp-kernel.org/docs/widgets),
+  [Debugger](https://cdp-kernel.org/docs/debugger)
+- Reference: [Editor types](https://cdp-kernel.org/docs/editor-types),
+  [Known gaps](https://cdp-kernel.org/docs/known-gaps),
+  [Support policy](https://cdp-kernel.org/docs/support)
+- Internals: [Architecture](https://cdp-kernel.org/docs/architecture),
+  [Runtime integrations](https://cdp-kernel.org/docs/integrations)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md),
+  [Development](https://cdp-kernel.org/docs/development),
+  [Security policy](SECURITY.md)
+
+The [feasibility study](https://cdp-kernel.org/docs/feasibility-study)
+behind the project covers the design, the alternatives considered (workerd,
+Bun, rusty_v8, FFI), and the evidence.
+
+## License
+
+MIT. Parts are ports of Deno's Jupyter kernel, Copyright 2018-2026 the Deno
+authors. The debugger's MurmurHash2 follows JupyterLab's (BSD-3-Clause) and
+Gary Court's (MIT); their notices are in
+[THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES). See
+[Architecture › Provenance](https://cdp-kernel.org/docs/architecture#provenance).

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,62 @@
+Third-party notices for cdp-kernel
+
+cdp-kernel itself is under the MIT license in LICENSE. The files below carry
+code from other projects under their own licenses.
+
+--------------------------------------------------------------------------------
+
+src/murmur2.ts follows JupyterLab's packages/debugger/src/hash.ts
+(Copyright (c) Jupyter Development Team), which is distributed under the
+following license:
+
+Copyright (c) 2015-2026 Project Jupyter Contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+JupyterLab's hash.ts is in turn adapted from Gary Court's murmurhash2_gc.js
+(https://github.com/garycourt/murmurhash-js), distributed under the following
+license:
+
+Copyright (c) 2011 Gary Court
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.