@tlockney/cdp-kernel 0.8.0 → 0.10.0

package/runtime/host.d.mts

@@ -0,0 +1,246 @@
+import type { CommApi } from "./comm.d.mts";
+
+/** The target name of the comm a Ganymede server opens to the kernel. */
+export const HOST_TARGET: "ganymede.host.v1";
+
+/** Why a host call failed. The codes are ganymede-device's. */
+export type HostErrorCode = "unavailable" | "denied" | "cancelled" | "timeout" | "failed" | "disconnected";
+
+/**
+ * A failed host call. Branch on `code` (or `name === "HostError"`): the
+ * class isn't a global, so `instanceof` isn't available in a cell.
+ *
+ * A failed host call: `unavailable` (no such method), `denied` (not
+ * granted to this notebook), `cancelled` (its signal aborted), `timeout`,
+ * `failed` (the server couldn't do it), `disconnected` (the host comm
+ * closed, such as on a server restart).
+ */
+export class HostError extends Error {
+  readonly code: HostErrorCode;
+  constructor(code: HostErrorCode, message: string);
+  static from(err: unknown): HostError;
+}
+
+/** Options for a host call. */
+export interface HostCallOptions {
+  /** Aborting it cancels the call. Default `jupyter.signal`. */
+  signal?: AbortSignal;
+}
+
+/** Parameters and results are JSON; the host API's design note lists each method's. */
+export type HostParams = { [key: string]: unknown };
+
+/** An entry `notebooks.list` returns: a folder, or a notebook this notebook may read. */
+export interface NotebookEntry {
+  path: string;
+  type: "directory" | "notebook";
+  /** Its first heading, for a notebook that has one. */
+  title?: string | null;
+  /** Its kernelspec name. */
+  kernel?: string | null;
+  /** ISO 8601. */
+  modified: string;
+}
+
+/** A cell `notebooks.search` matched. */
+export interface NotebookHit {
+  path: string;
+  title: string | null;
+  /** The cell's position in the notebook. */
+  index: number;
+  id: string | null;
+  cell_type: "code" | "markdown" | "raw";
+  /** Where the first word matched. */
+  in: "source" | "output";
+  excerpt: string;
+}
+
+/** What `notebooks.search` returns. */
+export interface NotebookSearch {
+  hits: NotebookHit[];
+  /** Matching cells, beyond `limit` too. */
+  total: number;
+  truncated: boolean;
+}
+
+/** The Ganymede server that runs this kernel, from `jupyter.host()`. */
+export interface Host {
+  /** The host API's protocol version. */
+  readonly protocol: number;
+  /** The server's version. */
+  readonly server: string;
+  /** This notebook's path under the server's root, or null when the kernel has none. */
+  readonly notebook: string | null;
+  /** The methods this notebook may call. */
+  readonly methods: readonly string[];
+  /**
+   * Whether this notebook may call `method`.
+   *
+   * @param method The method, such as `"notebooks.run"`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * host?.has("notebooks.run"); // false unless the notebook is granted runs
+   * ```
+   */
+  has(method: string): boolean;
+  /**
+   * Call a method by name. The shortcuts under `notebooks` and `self` call
+   * this.
+   *
+   * @param method The method, such as `"notebooks.read"`.
+   * @param params Its parameters, a JSON object. Default `{}`.
+   * @param options `signal` cancels the call.
+   * @returns What the server answered, as JSON.
+   * @throws {HostError} The call failed; `code` says why.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook } = await host!.call("notebooks.read", { path: "journal/a.ipynb" });
+   * notebook.cells.length;
+   * ```
+   */
+  call(method: string, params?: HostParams, options?: HostCallOptions): Promise<any>;
+  /** Other notebooks under the server's root, as far as this notebook's grant reaches. */
+  readonly notebooks: HostNotebooks;
+  /** This notebook's own cells. Not on a server yet: they reject `unavailable`. */
+  readonly self: HostSelf;
+}
+
+/** `host.notebooks`: other notebooks under the server's root. */
+export interface HostNotebooks {
+  /**
+   * The notebooks this notebook may read, and the folders, in a folder.
+   *
+   * @param params `dir`: the folder, relative to the root. Default the root.
+   * @param options `signal` cancels the call.
+   * @returns One entry per notebook or folder.
+   * @throws {HostError} `denied` when the grant doesn't reach `dir`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const entries = await host!.notebooks.list({ dir: "journal" });
+   * entries.filter((e) => e.type === "notebook").map((e) => e.title ?? e.path);
+   * ```
+   */
+  list(params?: { dir?: string }, options?: HostCallOptions): Promise<NotebookEntry[]>;
+  /**
+   * A notebook as nbformat JSON (from its open document when someone has
+   * it open), and each cell's source hash by cell id.
+   *
+   * @param params `path`: the notebook, relative to the root.
+   * @param options `signal` cancels the call.
+   * @returns The notebook and its hashes.
+   * @throws {HostError} `denied` when the grant doesn't reach `path`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook } = await host!.notebooks.read({ path: "journal/a.ipynb" });
+   * notebook.cells.length;
+   * ```
+   */
+  read(params: { path: string }, options?: HostCallOptions): Promise<{ notebook: any; hashes: { [cellId: string]: string } }>;
+  /**
+   * Cells that hold every word of `query`, in the notebooks this notebook
+   * may read: in sources, and in outputs too with `outputs: true`.
+   *
+   * @param params `query`, and optionally `dir`, `outputs`, `cell_type`
+   *   (`code`, `markdown` or `raw`) and `limit` (default 20, at most 200).
+   * @param options `signal` cancels the call.
+   * @returns The matches, how many there are in all, and whether `limit` cut them.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { hits } = await host!.notebooks.search({ query: "weekday drop", dir: "journal" });
+   * hits.map((h) => `${h.path}: ${h.excerpt}`);
+   * ```
+   */
+  search(
+    params: { query: string; dir?: string; outputs?: boolean; cell_type?: "code" | "markdown" | "raw"; limit?: number },
+    options?: HostCallOptions,
+  ): Promise<NotebookSearch>;
+  /**
+   * A notebook's named results. Not on a server yet: rejects `unavailable`.
+   *
+   * @param params `path`: the notebook.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const results = await host!.notebooks.results({ path: "journal/fremont.ipynb" });
+   * ```
+   */
+  results(params: { path: string }, options?: HostCallOptions): Promise<any>;
+  /**
+   * Run a notebook with parameters and return its results. Not on a
+   * server yet: rejects `unavailable`.
+   *
+   * @param params `path`: the notebook; `params`: its parameters.
+   * @param options `signal` cancels the run.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const run = await host!.notebooks.run({ path: "journal/fremont.ipynb", params: { counter: "2nd Ave" } });
+   * ```
+   */
+  run(params: { path: string; params?: HostParams }, options?: HostCallOptions): Promise<any>;
+}
+
+/** `host.self`: this notebook's own cells. Not on a server yet: each rejects `unavailable`. */
+export interface HostSelf {
+  /**
+   * Add a cell to this notebook.
+   *
+   * @param params The cell, as the host API's design note describes.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * await host!.self.add({ cell_type: "markdown", source: "## Index" });
+   * ```
+   */
+  add(params?: HostParams, options?: HostCallOptions): Promise<any>;
+  /**
+   * Change a cell's source, given the hash of the source it replaces.
+   *
+   * @param params The cell id, its new source and the old source's hash.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook, hashes } = await host!.notebooks.read({ path: host!.notebook! });
+   * const id = notebook.cells[0].id;
+   * await host!.self.edit({ id, source: "# New title", source_hash: hashes[id] });
+   * ```
+   */
+  edit(params?: HostParams, options?: HostCallOptions): Promise<any>;
+  /**
+   * Delete a cell, given its source's hash.
+   *
+   * @param params The cell id and its source's hash.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook, hashes } = await host!.notebooks.read({ path: host!.notebook! });
+   * const id = notebook.cells.at(-1).id;
+   * await host!.self.delete({ id, source_hash: hashes[id] });
+   * ```
+   */
+  delete(params?: HostParams, options?: HostCallOptions): Promise<any>;
+}
+
+/** Options for `jupyter.host()`. */
+export interface HostOptions {
+  /**
+   * How long to wait for a server that hasn't opened the comm, in ms.
+   * Default 1000. Once a wait goes unanswered, later calls answer `null`
+   * at once.
+   */
+  timeout?: number;
+}
+
+export function createHost(
+  comms: CommApi,
+  defaultSignal?: () => AbortSignal | undefined,
+): { host(options?: HostOptions): Promise<Host | null> };

package/runtime/host.mjs

@@ -0,0 +1,215 @@
+// @ts-self-types="./host.d.mts"
+// jupyter.host() (#461): the client for a Ganymede server's host API, which
+// lets a cell read, search and (when granted) run other notebooks. The
+// server opens a comm to target `ganymede.host.v1` when the kernel starts,
+// with its `hello` as the open's data. Calls go out as comm messages
+// `{ id, method, params }`; the server replies `{ id, result }` or
+// `{ id, error: { code, message } }` on a kernel subshell, so a cell that
+// awaits a call gets its reply. The message format and error codes are
+// ganymede-device's, so the two clients behave alike.
+//
+// Design: https://github.com/tlockney/ganymede/blob/main/docs/host-api.md
+
+export const HOST_TARGET = "ganymede.host.v1";
+
+const CODES = new Set(["unavailable", "denied", "cancelled", "timeout", "failed", "disconnected"]);
+
+export class HostError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "HostError";
+    this.code = code;
+  }
+
+  /** An abort becomes `cancelled`, a timeout signal's abort `timeout`, anything else `failed`. */
+  static from(err) {
+    if (err instanceof HostError) return err;
+    const message = typeof err?.message === "string" ? err.message : String(err);
+    if (err?.name === "AbortError") return new HostError("cancelled", message);
+    if (err?.name === "TimeoutError") return new HostError("timeout", message);
+    if (typeof err?.code === "string" && CODES.has(err.code)) return new HostError(err.code, message);
+    return new HostError("failed", message);
+  }
+}
+
+/** Why an aborted signal ended a call: `timeout` for a timeout signal, else `cancelled`. */
+function abortError(reason) {
+  const message = typeof reason?.message === "string" ? reason.message : String(reason ?? "aborted");
+  return new HostError(reason?.name === "TimeoutError" ? "timeout" : "cancelled", message);
+}
+
+/** A server's `hello`, or null when `data` isn't one. */
+function helloOf(data) {
+  if (data === null || typeof data !== "object" || typeof data.protocol !== "number") return null;
+  return {
+    protocol: data.protocol,
+    server: typeof data.server === "string" ? data.server : "",
+    notebook: typeof data.notebook === "string" ? data.notebook : null,
+    methods: Array.isArray(data.methods) ? data.methods.filter((m) => typeof m === "string") : [],
+  };
+}
+
+/**
+ * @param {import("./comm.d.mts").CommApi} comms
+ * @param {() => AbortSignal | undefined} [defaultSignal] the signal a call
+ *   watches when it is given none: jupyter.signal.
+ */
+export function createHost(comms, defaultSignal = () => undefined) {
+  /** The open host comm: { comm, hello, host, pending }, or null. */
+  let link = null;
+  /** Whoever waits for a hello: called with the link's Host, or null once there is no link. */
+  const waiters = new Set();
+  /**
+   * A comm this runtime opened went unanswered: no server. Remembered, so
+   * each `jupyter.host()` after the first answers null at once, until a
+   * server opens the comm itself.
+   */
+  let noServer = false;
+  let nextId = 0;
+
+  function settle() {
+    const host = link?.host ?? null;
+    if (host === null && link !== null) return;
+    for (const waiter of [...waiters]) waiter(host);
+  }
+
+  /** `ours`: this runtime opened the comm, not the server. */
+  function adopt(comm, data, ours = false) {
+    // A new comm replaces the old one: the server opens one per kernel start.
+    const old = link;
+    const l = { comm, host: null, pending: new Map(), ours };
+    if (!ours) noServer = false;
+    link = l;
+    if (old !== null && !old.comm.closed) old.comm.close();
+    const hello = helloOf(data);
+    if (hello !== null) l.host = makeHost(l, hello);
+    comm.onMsg(({ data }) => {
+      if (data.hello !== undefined) {
+        const hello = helloOf(data.hello);
+        if (hello !== null) {
+          l.host = makeHost(l, hello);
+          if (link === l) settle();
+        }
+        return;
+      }
+      const call = l.pending.get(data.id);
+      if (call === undefined) return;
+      if (data.error !== undefined) {
+        const { code, message } = data.error ?? {};
+        call.reject(new HostError(CODES.has(code) ? code : "failed", typeof message === "string" ? message : String(code)));
+      } else {
+        call.resolve(data.result);
+      }
+    });
+    comm.onClose(({ data }) => {
+      for (const call of l.pending.values()) {
+        call.reject(new HostError("disconnected", typeof data?.error === "string" ? `host comm closed: ${data.error}` : "host comm closed"));
+      }
+      l.pending.clear();
+      if (link === l) {
+        link = null;
+        // The frontend closed the comm this runtime opened: no server.
+        if (l.ours && l.host === null) noServer = true;
+        settle();
+      }
+    });
+    if (l.host !== null) settle();
+  }
+
+  function makeHost(l, hello) {
+    const methods = Object.freeze([...hello.methods]);
+    function call(method, params = {}, { signal = defaultSignal() } = {}) {
+      if (signal?.aborted) return Promise.reject(abortError(signal.reason));
+      if (l.comm.closed) return Promise.reject(new HostError("disconnected", "host comm closed"));
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          l.pending.delete(id);
+          if (!l.comm.closed) l.comm.send({ id, cancel: true });
+          reject(abortError(signal.reason));
+        };
+        const done = () => signal?.removeEventListener("abort", onAbort);
+        const call = {
+          resolve: (value) => (l.pending.delete(id), done(), resolve(value)),
+          reject: (error) => (l.pending.delete(id), done(), reject(error)),
+        };
+        l.pending.set(id, call);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+          l.comm.send({ id, method, params });
+        } catch (err) {
+          // Params that can't be sent, such as a BigInt: the server never
+          // got the call.
+          call.reject(new HostError("failed", `cannot send ${method}: ${err instanceof Error ? err.message : err}`));
+        }
+      });
+    }
+    const bind = (method) => (params, options) => call(method, params, options);
+    return Object.freeze({
+      protocol: hello.protocol,
+      server: hello.server,
+      notebook: hello.notebook,
+      methods,
+      has: (method) => methods.includes(method),
+      call,
+      notebooks: Object.freeze({
+        list: bind("notebooks.list"),
+        read: bind("notebooks.read"),
+        search: bind("notebooks.search"),
+        results: bind("notebooks.results"),
+        run: bind("notebooks.run"),
+      }),
+      self: Object.freeze({
+        add: bind("self.add"),
+        edit: bind("self.edit"),
+        delete: bind("self.delete"),
+      }),
+    });
+  }
+
+  comms.registerTarget(HOST_TARGET, (comm, msg) => adopt(comm, msg.data));
+
+  async function host({ timeout = 1000 } = {}) {
+    if (link?.host) return link.host;
+    // The wait for a server watches jupyter.signal, so an interrupt ends it.
+    const signal = defaultSignal();
+    if (signal?.aborted) throw abortError(signal.reason);
+    if (noServer) return null;
+    // No comm from the server (one whose comm closed, as when a runtime
+    // restarts in the same kernel): open it from here. A Ganymede server
+    // answers `{ hello }`; anything else closes it or stays silent.
+    if (link === null) adopt(comms.open(HOST_TARGET), null, true);
+    const mine = link;
+    return new Promise((resolve, reject) => {
+      let timer;
+      const onAbort = () => {
+        done();
+        reject(abortError(signal.reason));
+      };
+      const done = () => {
+        waiters.delete(waiter);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const waiter = (host) => {
+        done();
+        resolve(host);
+      };
+      waiters.add(waiter);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      // Each caller waits its own timeout; the last to give up on a comm
+      // this runtime opened closes it.
+      timer = setTimeout(() => {
+        done();
+        if (waiters.size === 0 && link === mine && mine.host === null && mine.ours) {
+          link = null;
+          noServer = true;
+          mine.comm.close();
+        }
+        resolve(null);
+      }, timeout);
+    });
+  }
+
+  return { host };
+}

package/runtime/widget.d.mts

@@ -5,31 +5,230 @@ export const WIDGET_PROTOCOL_VERSION: "2.1.0";
 
 export type WidgetState = { [key: string]: unknown };
 
+/** Options for `jupyter.widget`. */
 export interface WidgetOptions {
-  /** The anywidget ES module: `export default { render({ model, el }) { ... } }`. */
+  /**
+   * The anywidget view module, as source:
+   * `export default { render({ model, el }) { ... } }`. A `${...}` inside
+   * a template literal here is filled in by the kernel, not the browser:
+   * escape it as `\${...}`.
+   */
   esm: string;
-  /** Optional CSS for the view. */
+  /** CSS for the view. */
   css?: string;
-  /** Initial synced state. Uint8Array/ArrayBuffer values travel as binary buffers. */
+  /**
+   * The initial synced state. `Uint8Array` and `ArrayBuffer` values travel
+   * as binary buffers. Default `{}`.
+   */
   state?: WidgetState;
 }
 
-/** An anywidget model, synced with its frontend views. Display it to show a view. */
+/**
+ * An anywidget model, from `jupyter.widget`, synced with its frontend
+ * views. Display it to show a view; display it again for a second view of
+ * the same model.
+ */
 export interface Widget {
   /** The model id (the comm id). */
   readonly id: string;
+  /** Whether the model has been closed. */
   readonly closed: boolean;
+  /**
+   * The current value of a state key.
+   *
+   * @param key The state key.
+   * @returns Its value, or `undefined`.
+   * @example
+   * ```ts
+   * const w = jupyter.widget({ esm: "export default {}", state: { count: 0 } });
+   * w.get("count"); // 0
+   * ```
+   */
   get(key: string): unknown;
-  /** Sets one key or several, and syncs the change to the frontend. */
+  /**
+   * Change one state key, or several at once, and sync the change to every
+   * view. Fires this model's own `change` listeners too. After `close` it
+   * changes the local state only.
+   *
+   * @param key The state key.
+   * @param value Its new value.
+   * @param changes Several keys and their new values, instead of `key` and
+   *   `value`.
+   * @example
+   * ```ts
+   * const w = jupyter.widget({ esm: "export default {}", state: { count: 0, label: "" } });
+   * w.set("count", 1);
+   * w.set({ count: 2, label: "two" });
+   * ```
+   * @example
+   * ```ts
+   * const progress = jupyter.widget({
+   *   esm: `export default {
+   *     render({ model, el }) {
+   *       el.innerHTML =
+   *         '<div class="progress-track"><div class="progress-fill"></div></div>' +
+   *         '<div class="progress-label"></div>';
+   *       const fill = el.querySelector(".progress-fill");
+   *       const label = el.querySelector(".progress-label");
+   *       const update = () => {
+   *         const percent = Math.round(model.get("value") * 100);
+   *         fill.style.width = percent + "%";
+   *         label.textContent = model.get("message") + " (" + percent + "%)";
+   *       };
+   *       model.on("change:value", update);
+   *       model.on("change:message", update);
+   *       update();
+   *     },
+   *   };`,
+   *   css: `
+   *     .progress-track { width: 320px; height: 10px; border-radius: 5px; background: #e5e7eb; overflow: hidden; }
+   *     .progress-fill { height: 100%; background: #2e6e64; transition: width 0.2s; }
+   *     .progress-label { margin-top: 6px; font: 13px system-ui, sans-serif; color: #444; }
+   *   `,
+   *   state: { value: 0, message: "Starting" },
+   * });
+   * await jupyter.display(progress);
+   *
+   * const files = ["january.csv", "february.csv", "march.csv", "april.csv", "may.csv"];
+   * for (const [i, file] of files.entries()) {
+   *   progress.set({ message: "Processing " + file, value: i / files.length });
+   *   await new Promise((resolve) => setTimeout(resolve, 600)); // stand-in for real work
+   * }
+   * progress.set({ message: "Done", value: 1 });
+   * ```
+   * ![A progress bar three fifths full, labelled "Processing april.csv (60%)", captured while the cell was still running.](https://cdp-kernel.org/images/widgets/progress.png)
+   */
   set(key: string, value: unknown): void;
   set(changes: WidgetState): void;
+  /**
+   * Listen for state changes or custom messages from the views.
+   * `change:key` gets the new and previous value; `change` gets all the
+   * changed keys; `msg:custom` gets a view's `model.send` content.
+   *
+   * @param event `change:<key>`, `change` or `msg:custom`.
+   * @param listener Called for each event; may be async.
+   * @example
+   * ```ts
+   * const w = jupyter.widget({ esm: "export default {}", state: { count: 0 } });
+   * w.on("change:count", (value, previous) => console.log(previous, "->", value));
+   * w.on("msg:custom", (content) => console.log("view sent", content));
+   * ```
+   * @example
+   * ```ts
+   * const temperature = jupyter.widget({
+   *   esm: `export default {
+   *     render({ model, el }) {
+   *       const slider = document.createElement("input");
+   *       slider.type = "range";
+   *       slider.min = "-20";
+   *       slider.max = "40";
+   *       const label = document.createElement("span");
+   *       const update = () => {
+   *         slider.value = String(model.get("celsius"));
+   *         label.textContent = " " + model.get("celsius") + " °C is " + model.get("fahrenheit") + " °F";
+   *       };
+   *       slider.oninput = () => {
+   *         model.set("celsius", slider.valueAsNumber);
+   *         model.save_changes();
+   *       };
+   *       model.on("change:celsius", update);
+   *       model.on("change:fahrenheit", update);
+   *       update();
+   *       el.append(slider, label);
+   *     },
+   *   };`,
+   *   state: { celsius: 20, fahrenheit: 68 },
+   * });
+   *
+   * temperature.on("change:celsius", (celsius) => {
+   *   temperature.set("fahrenheit", Math.round((Number(celsius) * 9) / 5 + 32));
+   * });
+   *
+   * temperature;
+   * ```
+   * ![A range slider moved to 30, labelled "30 °C is 86 °F".](https://cdp-kernel.org/images/widgets/temperature.png)
+   */
   on(event: `change:${string}`, listener: (value: unknown, previous: unknown) => void | Promise<void>): void;
   on(event: "change", listener: (changes: WidgetState) => void | Promise<void>): void;
   on(event: "msg:custom", listener: (content: unknown, buffers: Uint8Array[]) => void | Promise<void>): void;
+  /**
+   * Remove a listener added with `on`.
+   *
+   * @param event The event it was added for.
+   * @param listener The same function.
+   * @example
+   * ```ts
+   * const w = jupyter.widget({ esm: "export default {}", state: { count: 0 } });
+   * const log = (value: unknown) => console.log(value);
+   * w.on("change:count", log);
+   * w.off("change:count", log);
+   * ```
+   */
   off(event: string, listener: (...args: never[]) => unknown): void;
-  /** A custom message to the view's `model.on("msg:custom", ...)`. */
+  /**
+   * Send a custom message to every view's `model.on("msg:custom", ...)`.
+   *
+   * @param content JSON content.
+   * @param buffers Binary buffers. Default `[]`.
+   * @example
+   * ```ts
+   * const w = jupyter.widget({ esm: "export default {}" });
+   * w.send({ type: "reset" });
+   * ```
+   * @example
+   * ```ts
+   * const dice = jupyter.widget({
+   *   esm: `export default {
+   *     render({ model, el }) {
+   *       const button = document.createElement("button");
+   *       button.textContent = "Roll 3 dice";
+   *       button.onclick = () => model.send({ count: 3 });
+   *       const result = document.createElement("span");
+   *       result.style.marginLeft = "12px";
+   *       result.style.fontSize = "24px";
+   *       model.on("msg:custom", (message) => {
+   *         result.textContent = message.faces + "  (total " + message.total + ")";
+   *       });
+   *       el.append(button, result);
+   *     },
+   *   };`,
+   * });
+   *
+   * dice.on("msg:custom", (content) => {
+   *   const { count } = content as { count: number };
+   *   const rolls = Array.from({ length: count }, () => 1 + Math.floor(Math.random() * 6));
+   *   dice.send({
+   *     faces: rolls.map((n) => "⚀⚁⚂⚃⚄⚅"[n - 1]).join(" "),
+   *     total: rolls.reduce((a, b) => a + b, 0),
+   *   });
+   * });
+   *
+   * dice;
+   * ```
+   * ![A "Roll 3 dice" button next to three die faces and their total, the kernel's answer to a click.](https://cdp-kernel.org/images/widgets/dice.png)
+   */
   send(content: unknown, buffers?: Uint8Array[]): void;
+  /**
+   * Close the model. Its views stop syncing.
+   *
+   * @example
+   * ```ts
+   * const w = jupyter.widget({ esm: "export default {}" });
+   * w.close();
+   * ```
+   */
   close(): void;
+  /**
+   * The full state, as the frontend sees it: anywidget's model keys
+   * (`_model_name`, `_view_name` and the rest) and the widget's own.
+   *
+   * @returns Every state key and its value.
+   * @example
+   * ```ts
+   * const w = jupyter.widget({ esm: "export default {}", state: { count: 0 } });
+   * w.fullState(); // { _model_name: "AnyModel", _model_module: "anywidget", ..., count: 0 }
+   * ```
+   */
   fullState(): WidgetState;
   /** Displaying a widget shows a view of it (application/vnd.jupyter.widget-view+json). */
   [$display](): MediaBundle;