@tlockney/cdp-kernel 0.6.0 → 0.7.1

package/README.md

@@ -5,7 +5,9 @@ into Deno 2.9.6 (`deno jupyter`), that runs notebooks on several JavaScript runt
 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.
+inspector speaks CDP works too. The kernel can also run inside a web page,
+with cells in a Web Worker and no server
+([The browser](https://cdp-kernel.org/docs/integration-browser), experimental).
 
 **Website:** <https://cdp-kernel.org/> ·
 **Docs:** [cdp-kernel.org/docs](https://cdp-kernel.org/docs/)
@@ -33,7 +35,7 @@ runtime versions and frontends are supported, and what may change before
 - 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.
+- [anywidget](https://github.com/manzt/anywidget)-style widgets and Jupyter comms.
 - `prompt()` and `confirm()`, interrupt that keeps state, Shift-Tab
   inspection, completion and history.
 
@@ -55,7 +57,7 @@ deno run -A jsr:@tlockney/cdp-kernel/cli install --runtime deno
 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
+[Ganymede](https://ganymede-server.com/docs/install). 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.

package/dist/browser/channels.d.ts

@@ -0,0 +1,27 @@
+import type { ChannelName, KernelChannels, Received } from "../kernel-core.ts";
+import type { JsonObject, OutgoingMessage } from "../message.ts";
+/** Every channel a message travels on, iopub included. */
+export type Channel = ChannelName | "iopub";
+/** A Jupyter message as JSON, the shape a frontend sends and receives. */
+export interface JupyterMessage {
+    header: JsonObject;
+    parent_header: JsonObject;
+    metadata: JsonObject;
+    content: JsonObject;
+    buffers?: (ArrayBuffer | ArrayBufferView)[];
+    channel?: string;
+}
+export type MessageListener = (channel: Channel, msg: JupyterMessage) => void;
+export declare class PageChannels implements KernelChannels {
+    #private;
+    readonly ready: Promise<unknown>;
+    /** A message from the frontend. One without a msg_id and msg_type is dropped. */
+    deliver(channel: ChannelName, msg: JupyterMessage): void;
+    onMessage(listener: MessageListener): () => void;
+    recv(channel: ChannelName): Promise<Received | null>;
+    shellQueued(): number;
+    reply(channel: ChannelName, _peer: string, msg: OutgoingMessage): void;
+    publish(msg: OutgoingMessage): void;
+    stdinPeers(): number;
+    sendStdin(msg: OutgoingMessage): void;
+}

package/dist/browser/channels.js

@@ -0,0 +1,90 @@
+// KernelChannels inside a page: the frontend hands the kernel messages in
+// Jupyter's JSON shape (as the websocket's JSON protocol and
+// @jupyterlab/services carry them) and gets messages back the same way.
+// There is one frontend, so one peer, and no signing.
+const PEER = "page";
+class Queue {
+    #items = [];
+    #waiters = [];
+    get size() {
+        return this.#items.length;
+    }
+    push(item) {
+        const waiter = this.#waiters.shift();
+        if (waiter)
+            waiter(item);
+        else
+            this.#items.push(item);
+    }
+    pop() {
+        const item = this.#items.shift();
+        if (item !== undefined)
+            return Promise.resolve(item);
+        return new Promise((resolve) => this.#waiters.push(resolve));
+    }
+}
+function bytes(buffer) {
+    return buffer instanceof ArrayBuffer ? new Uint8Array(buffer) : new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+}
+function isHeader(value) {
+    return typeof value.msg_id === "string" && typeof value.msg_type === "string";
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export class PageChannels {
+    ready = Promise.resolve();
+    #queues = { shell: new Queue(), control: new Queue(), stdin: new Queue() };
+    #listeners = new Set();
+    /** A message from the frontend. One without a msg_id and msg_type is dropped. */
+    deliver(channel, msg) {
+        const { header, parent_header: parentHeader, metadata, content } = msg;
+        const valid = isObject(header) && isHeader(header) && isObject(content);
+        this.#queues[channel].push(valid
+            ? {
+                peer: PEER,
+                msg: {
+                    header,
+                    parentHeader: isObject(parentHeader) ? parentHeader : {},
+                    metadata: isObject(metadata) ? metadata : {},
+                    content,
+                    buffers: (msg.buffers ?? []).map(bytes),
+                },
+            }
+            : null);
+    }
+    onMessage(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    #emit(channel, msg) {
+        const out = {
+            channel,
+            header: msg.header,
+            parent_header: msg.parentHeader,
+            metadata: msg.metadata,
+            content: msg.content,
+            buffers: msg.buffers,
+        };
+        for (const listener of this.#listeners)
+            listener(channel, out);
+    }
+    recv(channel) {
+        return this.#queues[channel].pop();
+    }
+    shellQueued() {
+        return this.#queues.shell.size;
+    }
+    reply(channel, _peer, msg) {
+        this.#emit(channel, msg);
+    }
+    publish(msg) {
+        this.#emit("iopub", msg);
+    }
+    stdinPeers() {
+        return 1;
+    }
+    sendStdin(msg) {
+        this.#emit("stdin", msg);
+    }
+}