@tlockney/cdp-kernel 0.4.0 → 0.5.0

package/dist/target.js

@@ -4,17 +4,33 @@
 import { Buffer } from "node:buffer";
 import process from "node:process";
 import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { asEvaluateResult, CdpAbandoned, CdpSession } from "./cdp.js";
 import { SHIM, transformCell } from "./transform.js";
 import { hostRuntime, isInsideNodeModules, runtimeDir } from "./package.js";
+import { killOnExit } from "./children.js";
 const BINDING = "__cdpk_send";
+/** How long a target may take from spawn to a usable session. */
+const START_TIMEOUT_MS = 60_000;
 const MARKER_RE = /\x1b\[cdpk:(\d+)(m?)\]\x1b/;
 const MAX_MARKER_LEN = 24;
 // Lines the runtimes print to stderr on their own: inspector notices, and
 // Deno's npm/jsr "Download https://..." progress (which `deno jupyter`
-// sends to the server log rather than the notebook).
-const INSPECTOR_CHATTER = /^(?:\x1b\[[0-9;]*m)*(Debugger listening on |Debugger attached\.|For help, see: |Visit chrome:\/\/inspect|Waiting for the debugger to disconnect|Download(?:\x1b\[[0-9;]*m)* https?:\/\/).*\n/gm;
+// sends to the server log rather than the notebook). Each entry is the
+// line's start once colour codes are removed.
+const INSPECTOR_CHATTER = [
+    "Debugger listening on ",
+    "Debugger attached.",
+    "For help, see: https://nodejs.org/",
+    "Visit chrome://inspect",
+    "Waiting for the debugger to disconnect",
+];
+const DENO_CHATTER = [...INSPECTOR_CHATTER, "Download http://", "Download https://"];
+const ANSI_SGR = /\x1b\[[0-9;]*m/g;
+/** A colour code cut off at the end of a chunk. */
+const PARTIAL_SGR = /\x1b(?:\[[0-9;]*)?$/;
 /** `bootstrap` is the local path of runtime/bootstrap.mjs (see runtimeDir). */
 export function launchCommand(runtime, bootstrap, { executable, denoConfig } = {}) {
     // The CDP WebSocket has no authentication, so its URL must stay private:
@@ -41,6 +57,33 @@ export function launchCommand(runtime, bootstrap, { executable, denoConfig } = {
     const node = hostRuntime() === "node" ? process.execPath : "node";
     return { cmd: executable ?? node, args: [...inspect, bootstrap] };
 }
+/**
+ * The esbuild binary this host's esbuild runs, for a Node target to compile
+ * imported TypeScript Node can't strip (#73); null when it can't be found.
+ * Resolved from esbuild's own location, so it's found in a node_modules
+ * install and in Deno's npm cache alike.
+ */
+export function esbuildBinary(resolve = import.meta.resolve, platform = process.platform, arch = process.arch) {
+    if (process.env.ESBUILD_BINARY_PATH)
+        return process.env.ESBUILD_BINARY_PATH;
+    const subpath = platform === "win32" ? "esbuild.exe" : "bin/esbuild";
+    try {
+        const main = fileURLToPath(resolve("esbuild"));
+        return createRequire(main).resolve(`@esbuild/${platform}-${arch}/${subpath}`);
+    }
+    catch {
+        return null;
+    }
+}
+/** The parsed value, or undefined for text that isn't JSON. */
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function isTargetMessage(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -139,6 +182,66 @@ export class PipeDemux {
         void this.#pump();
     }
 }
+/**
+ * Removes the runtime's own stderr lines (see INSPECTOR_CHATTER) and passes
+ * everything else on. A chatter line can arrive split across chunks, so a
+ * trailing partial line that could still turn out to be one is held back
+ * until its newline arrives; any other partial line passes straight through.
+ */
+export class StderrFilter {
+    #starts;
+    #emit;
+    #held = "";
+    #atLineStart = true;
+    constructor(runtime, emit) {
+        this.#starts = runtime === "deno" ? DENO_CHATTER : INSPECTOR_CHATTER;
+        this.#emit = emit;
+    }
+    push(chunk) {
+        let text = this.#held + chunk;
+        this.#held = "";
+        let out = "";
+        if (!this.#atLineStart) {
+            // The rest of a line that already went out unfiltered.
+            const nl = text.indexOf("\n");
+            if (nl === -1) {
+                this.#emit(text);
+                return;
+            }
+            out = text.slice(0, nl + 1);
+            text = text.slice(nl + 1);
+        }
+        const lines = text.split("\n");
+        const last = lines.pop();
+        for (const line of lines)
+            if (!this.#isChatter(line, false))
+                out += line + "\n";
+        if (last && this.#isChatter(last, true))
+            this.#held = last;
+        else
+            out += last;
+        this.#atLineStart = last === "" || this.#held !== "";
+        if (out)
+            this.#emit(out);
+    }
+    /** Releases a held partial line (the process died). */
+    flush() {
+        if (this.#held)
+            this.#emit(this.#held);
+        this.#held = "";
+        this.#atLineStart = true;
+    }
+    /** Whether `line` is chatter or, when `partial`, could still become chatter. */
+    #isChatter(line, partial) {
+        let plain = line.replace(ANSI_SGR, "");
+        if (partial)
+            plain = plain.replace(PARTIAL_SGR, "");
+        // Any other escape may be a PipeDemux marker, which must never be dropped or held.
+        if (plain.includes("\x1b"))
+            return false;
+        return this.#starts.some((start) => plain.startsWith(start) || (partial && start.startsWith(plain)));
+    }
+}
 /** Promises keyed by barrier number, resolvable before or after first use. */
 export class Gates {
     #map = new Map();
@@ -167,6 +270,12 @@ export class Gates {
 export class Interrupted extends Error {
     name = "Interrupted";
 }
+/** A catch handler: a call interrupt() abandoned becomes Interrupted. */
+function interrupted(what) {
+    return (err) => {
+        throw err instanceof CdpAbandoned ? new Interrupted(`${what} interrupted`) : err;
+    };
+}
 export class Target {
     runtime;
     transform = transformCell;
@@ -180,11 +289,20 @@ export class Target {
     #messages = Promise.resolve();
     #interrupted = false;
     #paused = false;
+    /** Set once the main context is gone: the runtime is exiting (#130). */
+    #exiting = false;
+    #exited;
     #baselineGlobals = new Set();
     versions;
     constructor(runtime, child, shell, control, stdout, stderr, gates, contextId, versions) {
         this.runtime = runtime;
         this.#child = child;
+        this.#exited = new Promise((resolve) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                resolve();
+            else
+                child.once("exit", () => resolve());
+        });
         this.#shell = shell;
         this.#control = control;
         this.#stdout = stdout;
@@ -208,18 +326,41 @@ export class Target {
             env.CDPK_DENO_COMPAT = "1";
         if (runtime === "deno" && options.denoConfig !== undefined)
             env.CDPK_DENO_PROJECT = "1";
+        const esbuild = runtime === "node" ? esbuildBinary() : null;
+        if (esbuild !== null)
+            env.CDPK_ESBUILD_BINARY = esbuild;
         delete env.NO_COLOR;
         const child = spawn(cmd, args, { cwd: options.cwd, stdio: ["pipe", "pipe", "pipe"], env });
+        killOnExit(child);
+        // A start that fails or stalls must not leave the runtime running: its
+        // pipes and inspector sockets would keep this process alive (#52).
+        const sessions = [];
+        const timeoutMs = options.startTimeoutMs ?? START_TIMEOUT_MS;
+        let timer;
+        const stalled = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${cmd} did not start within ${timeoutMs / 1000}s`)), timeoutMs);
+        });
+        try {
+            return await Promise.race([Target.#start(runtime, events, cmd, child, sessions), stalled]);
+        }
+        catch (error) {
+            for (const session of sessions)
+                session.close();
+            child.kill();
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    static async #start(runtime, events, cmd, child, sessions) {
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
         const gates = new Gates();
         const stdout = new PipeDemux((text) => events.stream("stdout", text), (n) => gates.wait(n));
         const stderr = new PipeDemux((text) => events.stream("stderr", text), (n) => gates.wait(n));
-        const pushStderr = (chunk) => {
-            const text = chunk.replace(INSPECTOR_CHATTER, "");
-            if (text)
-                stderr.push(text);
-        };
+        const filter = new StderrFilter(runtime, (text) => stderr.push(text));
+        const pushStderr = (chunk) => filter.push(chunk);
         // Until the inspector URL appears, stderr carries the runtime's banner.
         const wsUrl = await new Promise((resolve, reject) => {
             let banner = "";
@@ -240,12 +381,15 @@ export class Target {
         child.stdout.on("data", (c) => stdout.push(c));
         child.once("exit", (code) => {
             gates.openAll();
+            filter.flush();
             stdout.close();
             stderr.close();
             events.exit(code);
         });
         const shell = await CdpSession.connect(wsUrl);
+        sessions.push(shell);
         const control = await CdpSession.connect(wsUrl);
+        sessions.push(control);
         const contextReady = new Promise((resolve) => {
             shell.on("Runtime.executionContextCreated", (params) => {
                 const context = params.context;
@@ -257,21 +401,33 @@ export class Target {
         await shell.send("Runtime.addBinding", { name: BINDING });
         const contextId = await contextReady;
         const target = new Target(runtime, child, shell, control, stdout, stderr, gates, contextId, { runtime: "", engine: "" });
+        // process.exit() or Deno.exit() destroys the context, then the runtime
+        // waits for its inspector clients to disconnect before it exits. Let go,
+        // so it exits and the kernel starts a fresh one (#130).
+        shell.on("Runtime.executionContextDestroyed", (params) => {
+            if (params.executionContextId === contextId)
+                target.#onExit();
+        });
         shell.on("Runtime.bindingCalled", (params) => {
             if (params.name !== BINDING || typeof params.payload !== "string")
                 return;
-            const msg = JSON.parse(params.payload);
+            // __cdpk_send is an ordinary global, so a cell can call it with
+            // anything; that mustn't take the host down (#122).
+            const msg = parseJson(params.payload);
             if (isTargetMessage(msg))
                 target.#deliver(msg, events);
         });
-        // Wait for the bootstrap's top-level await to finish installing the shim.
-        for (let i = 0; i < 200; i++) {
-            const probe = await target.#evaluateRaw(`typeof globalThis.${SHIM}?.tick === "function"`);
+        // Wait for the bootstrap's top-level await to finish installing the
+        // shim. There is no cap here: launch's start timeout bounds the wait and
+        // kills the child, so a slow bootstrap never yields a target without
+        // the shim (#134).
+        for (;;) {
+            const probe = await target.#evaluateSync(`typeof globalThis.${SHIM}?.tick === "function"`);
             if (probe.result.value === true)
                 break;
             await new Promise((r) => setTimeout(r, 25));
         }
-        const versions = await target.#evaluateRaw(`JSON.stringify(typeof Deno !== "undefined" ? { runtime: Deno.version.deno, engine: "V8 " + Deno.version.v8 } : { runtime: process.versions.node, engine: "V8 " + process.versions.v8 })`);
+        const versions = await target.#evaluateSync(`JSON.stringify(typeof Deno !== "undefined" ? { runtime: Deno.version.deno, engine: "V8 " + Deno.version.v8 } : { runtime: process.versions.node, engine: "V8 " + process.versions.v8 })`);
         Object.assign(target.versions, JSON.parse(String(versions.result.value)));
         // The runtime's own enumerable globals, before any cell: the debugger's
         // variable views show only what cells added (#18).
@@ -304,11 +460,23 @@ export class Target {
     }
     /** Resolves once all output and messages sent so far have been delivered. */
     async flush() {
-        const n = await this.#evaluateRaw(`${SHIM}.barrier()`);
+        const n = await this.#evaluateSync(`${SHIM}.barrier()`).catch(interrupted("Execution"));
         const barrier = Number(n.result.value);
         await Promise.all([this.#stdout.waitFor(barrier), this.#stderr.waitFor(barrier)]);
         await this.#messages;
     }
+    /**
+     * For expressions that return a value without awaiting. With replMode or
+     * awaitPromise, the inspector holds the result promise only weakly until
+     * its then-callback runs, even when the expression returns a plain value:
+     * a GC in that window fails the call with "Promise was collected" (#50).
+     * A plain evaluate returns the value directly.
+     */
+    #evaluateSync(expression) {
+        return this.#shell
+            .send("Runtime.evaluate", { expression, contextId: this.#contextId, returnByValue: true })
+            .then(asEvaluateResult);
+    }
     #evaluateRaw(expression, session = this.#shell) {
         return session
             .send("Runtime.evaluate", { expression, contextId: this.#contextId, replMode: true, awaitPromise: true })
@@ -323,9 +491,27 @@ export class Target {
         catch (err) {
             if (err instanceof CdpAbandoned || this.#interrupted)
                 throw new Interrupted("Execution interrupted");
+            if (this.#exiting) {
+                // The child's exit, which drops this target in the kernel, comes
+                // first, so the next cell starts a fresh one.
+                await this.#exited;
+                throw new Error(`${this.runtime} exited`);
+            }
             throw err;
         }
     }
+    #onExit() {
+        if (this.#exiting)
+            return;
+        this.#exiting = true;
+        this.#shell.close();
+        this.#control.close();
+        // In case it still doesn't exit once both sessions are gone.
+        setTimeout(() => {
+            if (this.#child.exitCode === null && this.#child.signalCode === null)
+                this.#child.kill("SIGKILL");
+        }, 2000).unref();
+    }
     /**
      * Deno calls IsolateHandle::terminate_execution from another thread. The
      * CDP equivalent is Runtime.terminateExecution, sent on a second session
@@ -341,11 +527,27 @@ export class Target {
         await this.#control.send("Runtime.terminateExecution");
         this.#shell.abandonPending();
     }
+    /**
+     * For synchronous functions. With awaitPromise the inspector would wrap
+     * even a plain return value in a promise it holds only weakly (#55).
+     */
     callFunctionOn(functionDeclaration, args) {
         return this.#shell.send("Runtime.callFunctionOn", {
             functionDeclaration,
             arguments: args,
             executionContextId: this.#contextId,
+            returnByValue: true,
+        });
+    }
+    /**
+     * For functions that return a promise. The target holds it until after
+     * the inspector's then-callback has run, so a GC can't collect it first.
+     */
+    #callAsyncFunctionOn(functionDeclaration, args) {
+        return this.#shell.send("Runtime.callFunctionOn", {
+            functionDeclaration: `function (...args) { return globalThis.${SHIM}.hold((${functionDeclaration}).apply(this, args)); }`,
+            arguments: args,
+            executionContextId: this.#contextId,
             awaitPromise: true,
             returnByValue: true,
         });
@@ -357,10 +559,12 @@ export class Target {
             : result.unserializableValue !== undefined
                 ? { unserializableValue: result.unserializableValue }
                 : { value: result.value };
-        await this.callFunctionOn(`function (n, r) { return globalThis.${SHIM}.broadcastResult(n, r); }`, [
+        // An async $display method can still be running when interrupt()
+        // abandons the call (#135).
+        await this.#callAsyncFunctionOn(`function (n, r) { return globalThis.${SHIM}.broadcastResult(n, r); }`, [
             { value: executionCount },
             arg,
-        ]);
+        ]).catch(interrupted("Execution"));
     }
     /**
      * Hands a frontend comm message to the target's comms. Resolves to
@@ -371,18 +575,12 @@ export class Target {
         this.#interrupted = false;
         let res;
         try {
-            res = await this.#shell.send("Runtime.callFunctionOn", {
-                functionDeclaration: `function (t, c, m, b) { return globalThis.${SHIM}.commDispatch(t, c, m, b); }`,
-                arguments: [
-                    { value: msgType },
-                    { value: content },
-                    { value: metadata },
-                    { value: buffers.map((b) => Buffer.from(b).toString("base64")) },
-                ],
-                executionContextId: this.#contextId,
-                awaitPromise: true,
-                returnByValue: true,
-            });
+            res = await this.#callAsyncFunctionOn(`function (t, c, m, b) { return globalThis.${SHIM}.commDispatch(t, c, m, b); }`, [
+                { value: msgType },
+                { value: content },
+                { value: metadata },
+                { value: buffers.map((b) => Buffer.from(b).toString("base64")) },
+            ]);
         }
         catch (err) {
             if (err instanceof CdpAbandoned || this.#interrupted)
@@ -407,12 +605,15 @@ export class Target {
     /**
      * Evaluates without side effects: V8 throws instead of running anything
      * that would change state (a call, a getter that writes), so completing
-     * or inspecting `obj.` never runs user code (#10).
+     * or inspecting `obj.` never runs user code (#10). Not replMode, which
+     * returns a promise the inspector holds only weakly (#55); a plain
+     * evaluate sees the cells' let and const too.
      */
     #evaluatePure(expression) {
         return this.#shell
-            .send("Runtime.evaluate", { expression, contextId: this.#contextId, replMode: true, throwOnSideEffect: true })
-            .then(asEvaluateResult, () => null);
+            .send("Runtime.evaluate", { expression, contextId: this.#contextId, throwOnSideEffect: true })
+            .then(asEvaluateResult)
+            .catch(() => null);
     }
     async propertyNames(expression) {
         const evaluated = await this.#evaluatePure(`(${expression})`);
@@ -444,8 +645,8 @@ export class Target {
         const res = await this.#shell.send("Runtime.globalLexicalScopeNames", { executionContextId: this.#contextId });
         return res.names ?? [];
     }
-    replyInput(value) {
-        this.#child.stdin.write(JSON.stringify({ value }) + "\n");
+    replyInput(value, interrupted = false) {
+        this.#child.stdin.write(JSON.stringify({ value, interrupted }) + "\n");
     }
     kill() {
         this.#shell.close();

package/dist/text.d.ts

@@ -6,7 +6,11 @@ export type IsCompleteReply = {
 } | {
     status: "invalid";
 };
-/** Bracket/quote/comment scanner deciding whether a cell is finished. */
+/**
+ * Bracket/quote/comment scanner deciding whether a cell is finished. Regex
+ * literals are recognised heuristically (see startsRegex), and a template's
+ * `${...}` is skipped like the rest of the template.
+ */
 export declare function checkIsComplete(code: string): IsCompleteReply;
 /** The dotted expression ending at the cursor, e.g. "Math.fl". */
 export declare function exprAtCursor(code: string, cursor: number): string;

package/dist/text.js

@@ -2,7 +2,53 @@
 //
 // Ported from Deno's cli/js/jupyter_kernel.js (v2.9.6), which is
 // Copyright 2018-2026 the Deno authors, MIT license.
-/** Bracket/quote/comment scanner deciding whether a cell is finished. */
+// Keywords after which a `/` starts a regex literal rather than dividing.
+const REGEX_AFTER_WORD = new Set([
+    "return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "throw",
+    "case", "do", "else", "yield", "await",
+]);
+/**
+ * Whether a `/` at `i` (not starting a comment) begins a regex literal: the
+ * usual heuristic, true unless the previous token can end an operand (a
+ * name, number, closing bracket or string). It can't tell `a++ / b` or a
+ * block's `} /re/` apart; those are rare enough in a console.
+ */
+function startsRegex(code, i) {
+    let j = i - 1;
+    while (j >= 0 && /\s/.test(code[j]))
+        j--;
+    if (j < 0)
+        return true;
+    const prev = code[j];
+    if (/[\w$]/.test(prev)) {
+        const word = /[\w$]+$/.exec(code.slice(0, j + 1))?.[0] ?? "";
+        return REGEX_AFTER_WORD.has(word);
+    }
+    return !/[)\]}'"`]/.test(prev);
+}
+/** The index just past a regex literal starting at `i`, or -1 if it doesn't end on its line. */
+function regexEnd(code, i) {
+    let inClass = false;
+    for (let j = i + 1; j < code.length; j++) {
+        const c = code[j];
+        if (c === "\n")
+            return -1;
+        if (c === "\\")
+            j++;
+        else if (c === "[")
+            inClass = true;
+        else if (c === "]")
+            inClass = false;
+        else if (c === "/" && !inClass)
+            return j + 1;
+    }
+    return -1;
+}
+/**
+ * Bracket/quote/comment scanner deciding whether a cell is finished. Regex
+ * literals are recognised heuristically (see startsRegex), and a template's
+ * `${...}` is skipped like the rest of the template.
+ */
 export function checkIsComplete(code) {
     const stack = [];
     const closers = { ")": "(", "]": "[", "}": "{" };
@@ -21,11 +67,18 @@ export function checkIsComplete(code) {
             i = end + 2;
             continue;
         }
+        if (ch === "/" && startsRegex(code, i)) {
+            const end = regexEnd(code, i);
+            if (end !== -1) {
+                i = end;
+                continue;
+            }
+        }
         if (ch === "'" || ch === '"' || ch === "`") {
             i++;
             let closed = false;
             while (i < code.length) {
-                if (code[i] === "\\" && ch !== "`") {
+                if (code[i] === "\\") {
                     i += 2;
                     continue;
                 }

package/dist/transform.d.ts

@@ -1,5 +1,14 @@
 import { LineMap } from "./sourcemap.ts";
 export declare const SHIM = "__cdpk";
+/**
+ * Each replMode cell also ends by yielding one macrotask, so the script
+ * settles with no other microtasks queued ahead of the inspector's
+ * then-callback. Until that callback runs, the inspector holds the result
+ * promise only weakly, and a GC in between fails the evaluate with "Promise
+ * was collected" (#55). A declaration has no completion value, so the
+ * cell's value is unchanged; replMode lets `let` be declared again.
+ */
+export declare const SETTLE = "\n;let __cdpk_settled = await __cdpk.tick();";
 export declare class CellSyntaxError extends Error {
     name: string;
 }

package/dist/transform.js

@@ -6,7 +6,7 @@
 // TypeScript/JSX part and acorn finds the module syntax that a script can't
 // contain:
 //   import x, { y as z } from "m"  ->  var __cdpk_m0 = await __cdpk.import("m");
-//                                     var x = __cdpk_m0.default, z = __cdpk_m0.y;
+//                                     var x = __cdpk_m0["default"], z = __cdpk_m0["y"];
 //   import("m")                    ->  __cdpk.import("m")
 //   import.meta                    ->  __cdpk.meta
 //   export const a = 1             ->  const a = 1
@@ -25,6 +25,15 @@ export const SHIM = "__cdpk";
 // interrupt a busy loop. (Within that dispatch the inspector processes no
 // other messages, so an interrupt would never be seen.)
 const PRELUDE = `'use strict'; await ${SHIM}.tick();\n`;
+/**
+ * Each replMode cell also ends by yielding one macrotask, so the script
+ * settles with no other microtasks queued ahead of the inspector's
+ * then-callback. Until that callback runs, the inspector holds the result
+ * promise only weakly, and a GC in between fails the evaluate with "Promise
+ * was collected" (#55). A declaration has no completion value, so the
+ * cell's value is unchanged; replMode lets `let` be declared again.
+ */
+export const SETTLE = `\n;let ${SHIM}_settled = await ${SHIM}.tick();`;
 export class CellSyntaxError extends Error {
     name = "SyntaxError";
 }
@@ -34,8 +43,14 @@ function jsxSettings(jsx) {
     }
     return { jsx: "transform", jsxFactory: jsx?.factory, jsxFragment: jsx?.fragment };
 }
+// esbuild compiles `import x = require("m")` to a `require` call, which a
+// cell doesn't have (#143); `import type x = require("m")` is erased.
+const IMPORT_REQUIRE = /^\s*(?:export\s+)?import\s+(?!type\s)[\w$]+\s*=\s*require\s*\(/m;
 /** esbuild's output, with its source map's `mappings` when asked for. */
 function stripTypesMapped(code, options, sourcemap) {
+    if (IMPORT_REQUIRE.test(code)) {
+        throw new CellSyntaxError('import x = require("m") is not supported in a cell; use import x from "m"');
+    }
     const compilerOptions = {
         verbatimModuleSyntax: true,
         ...(options.experimentalDecorators ? { experimentalDecorators: true } : {}),
@@ -47,6 +62,9 @@ function stripTypesMapped(code, options, sourcemap) {
             const result = transformSync(code, {
                 loader,
                 target: "esnext",
+                // Neither acorn nor V8 parses standard (TC39) decorators or
+                // `accessor` yet, so esbuild lowers them (#142).
+                supported: { decorators: false },
                 ...jsxSettings(options.jsx),
                 tsconfigRaw: { compilerOptions },
                 logLevel: "silent",
@@ -80,8 +98,9 @@ function rewriteImport(code, node, index) {
         ? `, { with: { ${node.attributes.map((a) => code.slice(a.start, a.end)).join(", ")} } }`
         : "";
     const load = `await ${SHIM}.import(${source}${attrs})`;
+    // `void`: as a cell's last statement, the import isn't its result (#139).
     if (node.specifiers.length === 0)
-        return `${load};`;
+        return `void ${load};`;
     const ns = `${SHIM}_m${index}`;
     const bindings = node.specifiers.map((spec) => {
         const local = String(spec.local.name);
@@ -140,7 +159,13 @@ export function rewriteModuleSyntax(js) {
             }
             case "ExportDefaultDeclaration": {
                 const decl = node;
-                edits.push({ start: decl.start, end: decl.declaration.start, text: "" });
+                const anonymous = (decl.declaration.type === "FunctionDeclaration" || decl.declaration.type === "ClassDeclaration") &&
+                    decl.declaration.id === null;
+                // An anonymous `function () {}` or `class {}` isn't a statement on
+                // its own; parenthesized, it's an expression and the cell's result (#143).
+                edits.push({ start: decl.start, end: decl.declaration.start, text: anonymous ? "(" : "" });
+                if (anonymous)
+                    edits.push({ start: decl.declaration.end, end: decl.declaration.end, text: ");" });
                 break;
             }
             case "ExportAllDeclaration":
@@ -202,8 +227,8 @@ function patternNames(pattern, names) {
  * surrounding script, which a global-code eval turns into a property of
  * globalThis. Inside the function the declarations become assignments to
  * those globals:
- *   const { a } = o; class K {}  ->  var a, K;
- *                                    (async () => { ({ a } = o); K = class K {}; })()
+ *   const { a } = o; class K {}  ->  var a, K; (async () => {
+ *                                    ({ a } = o); K = class K {}; })()
  * So later cells, and closures from this one, all see one binding. A `var`
  * in a top-level block or loop head is global too, as in a script; block
  * scoped and function-local declarations stay where they are. Functions
@@ -277,18 +302,21 @@ function hoistForEval(js) {
             edits.push({ start: stmt.end, end: stmt.end, text: ";" });
         }
         else if (stmt.type === "ExpressionStatement" && i === program.body.length - 1) {
-            replace(stmt, `return [${src(stmt.expression)}];`);
+            // Parenthesized, so `1, 2` returns [2] rather than [1, 2] (#140).
+            replace(stmt, `return [(${src(stmt.expression)})];`);
         }
         else {
             nestedVars(stmt);
         }
     });
-    const declare = names.size > 0 ? `var ${[...names].join(", ")};\n` : "";
+    // All on the first line, so the cell always starts on line 2, as after
+    // transformCell's one-line prelude (#150).
+    const declare = names.size > 0 ? `var ${[...names].join(", ")}; ` : "";
     const publish = functions.map((name) => ` globalThis.${name} = ${name};`).join("");
     return `${declare}(async () => { 'use strict';${publish}\n${applyEdits(js, edits)}\n})()`;
 }
 export function transformCell(code, options = {}) {
-    return PRELUDE + rewriteModuleSyntax(stripTypes(code, options));
+    return PRELUDE + rewriteModuleSyntax(stripTypes(code, options)) + SETTLE;
 }
 /**
  * transformCell, plus the map between the cell's lines and the script's,
@@ -297,7 +325,7 @@ export function transformCell(code, options = {}) {
  */
 export function transformCellWithLines(code, options = {}) {
     const stripped = stripTypesMapped(code, options, true);
-    return { script: PRELUDE + rewriteModuleSyntax(stripped.code), lines: new LineMap(stripped.mappings, newlines(PRELUDE)) };
+    return { script: PRELUDE + rewriteModuleSyntax(stripped.code) + SETTLE, lines: new LineMap(stripped.mappings, newlines(PRELUDE)) };
 }
 /**
  * Like transformCell, for a target that evaluates cells itself, as global

package/dist/wire.d.ts

@@ -11,12 +11,17 @@ export interface Header extends JsonObject {
     msg_type: string;
     version: string;
 }
+/** A header as received: the fields the kernel relies on, plus whatever else came. */
+export interface ReceivedHeader extends JsonObject {
+    msg_id: string;
+    msg_type: string;
+}
 export interface Message {
     identities: Uint8Array[];
     sig: string;
     /** Raw bytes of header, parent_header, metadata, content as received. */
     signedParts: Uint8Array[];
-    header: Header;
+    header: ReceivedHeader;
     parentHeader: JsonObject;
     metadata: JsonObject;
     content: JsonObject;
@@ -26,6 +31,8 @@ export declare function sign(key: string, parts: Uint8Array[]): string;
 export declare function verify(key: string, parts: Uint8Array[], sig: string): boolean;
 export declare function makeHeader(session: string, msgType: string): Header;
 export interface EncodeOptions {
+    /** Defaults to a fresh header; pass one to know its msg_id. */
+    header?: Header;
     identities?: Uint8Array[];
     parentHeader?: JsonObject;
     metadata?: JsonObject;