@observablehq/notebook-kit 1.0.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 Observable, Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# Observable Notebook Kit
+
+**Observable Notebook Kit** is an open-source command-line tool for building static sites from Observable Notebooks based on an open file format. Notebook Kit also includes a Vite plugin and a low-level JavaScript interface for deep integration of Observable Notebooks with custom web applications.
+
+Notebook Kit is available as part of [Notebooks 2.0 Technology Preview](https://observablehq.com/notebook-kit/), which includes [Observable Desktop](https://observablehq.com/notebook-kit/desktop), a notebook editor for macOS.
+
+For more, [see the documentation](https://observablehq.com/notebook-kit/kit).

package/dist/bin/build.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export default function run(args?: string[]): Promise<void>;

package/dist/bin/build.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { build } from "vite";
+import { config, observable } from "../src/vite/index.js";
+if (process.argv[1] === import.meta.filename)
+    run();
+export default async function run(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowNegative: true,
+        allowPositionals: true,
+        options: {
+            out: {
+                type: "string",
+                short: "o",
+                default: ".observable/dist"
+            },
+            root: {
+                type: "string",
+                default: "."
+            },
+            base: {
+                type: "string",
+                default: "./"
+            },
+            template: {
+                type: "string"
+            },
+            empty: {
+                type: "boolean"
+            },
+            help: {
+                type: "boolean",
+                short: "h"
+            }
+        }
+    });
+    if (values.help) {
+        console.log(`usage: notebooks build [files]
+
+  --root <dir>             path to the root directory; defaults to cwd
+  --template <path>        path to the HTML template
+  -o, --out <dir>          path to the output directory (relative to root)
+  --base <path>            serving base path; defaults to ./
+  --empty                  whether to empty the output directory before building
+  -h, --help               show this message
+`);
+        return;
+    }
+    await build({
+        ...config(),
+        plugins: [observable({ template: values.template })],
+        root: values.root,
+        base: values.base,
+        build: {
+            outDir: values.out,
+            emptyOutDir: values.empty,
+            rollupOptions: {
+                input: positionals
+            }
+        }
+    });
+}

package/dist/bin/download.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export default function run(args?: string[]): Promise<void>;

package/dist/bin/download.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { JSDOM } from "jsdom";
+import { toNotebook } from "../src/lib/notebook.js";
+import { serialize } from "../src/lib/serialize.js";
+if (process.argv[1] === import.meta.filename)
+    run();
+export default async function run(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            help: {
+                type: "boolean",
+                short: "h"
+            }
+        }
+    });
+    if (positionals.length !== 1 && !values.help)
+        throw new Error("missing <url>");
+    if (values.help) {
+        console.log(`usage: notebooks download <url>
+
+  -h, --help               show this message
+`);
+        return;
+    }
+    const globalDocument = globalThis.document;
+    globalThis.document = new JSDOM().window.document;
+    try {
+        for (const positional of positionals) {
+            let url = new URL(positional, "https://observablehq.com");
+            if (url.origin === "https://observablehq.com") {
+                url = new URL(`/document${url.pathname.replace(/^\/d\//, "/")}`, "https://api.observablehq.com");
+            }
+            const response = await fetch(url);
+            if (!response.ok)
+                throw new Error(`unable to fetch: ${url}`);
+            const { title, nodes } = await response.json();
+            for (const node of nodes)
+                if (node.mode === "js")
+                    node.mode = "ojs";
+            process.stdout.write(serialize(toNotebook({ title, cells: nodes })));
+        }
+    }
+    finally {
+        globalThis.document = globalDocument;
+    }
+}

package/dist/bin/notebooks.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/notebooks.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+const [, , command] = process.argv;
+switch (command) {
+    case "build": {
+        const { default: run } = await import("./build.js");
+        await run(process.argv.slice(3));
+        break;
+    }
+    case "download": {
+        const { default: run } = await import("./download.js");
+        await run(process.argv.slice(3));
+        break;
+    }
+    case "preview": {
+        const { default: run } = await import("./preview.js");
+        await run(process.argv.slice(3));
+        break;
+    }
+    default: {
+        console.log(`usage: notebooks <command>
+
+  preview      start the preview server
+  build        generate a static site
+  download     download an Observable Notebook as HTML
+  help         print usage information
+  version      print the version
+`);
+        if (command !== "help")
+            process.exit(1);
+        break;
+    }
+}
+export {};

package/dist/bin/preview.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export default function run(args?: string[]): Promise<void>;

package/dist/bin/preview.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { createServer } from "vite";
+import { config, observable } from "../src/vite/index.js";
+if (process.argv[1] === import.meta.filename)
+    run();
+export default async function run(args) {
+    const { values } = parseArgs({
+        args,
+        allowNegative: true,
+        options: {
+            root: {
+                type: "string",
+                default: "."
+            },
+            base: {
+                type: "string",
+                default: "/"
+            },
+            template: {
+                type: "string"
+            },
+            help: {
+                type: "boolean",
+                short: "h"
+            }
+        }
+    });
+    if (values.help) {
+        console.log(`usage: notebooks preview
+
+  --root <dir>             path to the root directory; defaults to cwd
+  --template <path>        path to the HTML template
+  --base <path>            serving base path; defaults to /
+  -h, --help               show this message
+`);
+        return;
+    }
+    const server = await createServer({
+        ...config(),
+        plugins: [observable({ template: values.template })],
+        root: values.root,
+        base: values.base
+    });
+    await server.listen();
+    server.printUrls();
+    server.bindCLIShortcuts({ print: true });
+}

package/dist/package.json

@@ -0,0 +1,73 @@
+{
+    "name": "@observablehq/notebook-kit",
+    "license": "ISC",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/observablehq/notebook-kit.git"
+    },
+    "version": "1.0.0",
+    "type": "module",
+    "scripts": {
+        "test": "vitest",
+        "prepublishOnly": "rm -rf dist && tsc && chmod +x dist/bin/*.js && cp -r src/styles src/templates dist/src && cp src/runtime/stdlib/*.css dist/src/runtime/stdlib",
+        "lint": "tsc --noEmit && eslint bin src types",
+        "notebooks": "tsx bin/notebooks.ts",
+        "download": "tsx bin/notebooks.ts download",
+        "docs:preview": "tsx --watch bin/notebooks.ts preview --root docs --template docs/observable.tmpl",
+        "docs:build": "tsx bin/notebooks.ts build --root docs --template docs/observable.tmpl -- $(find docs -path 'docs/.observable' -prune -o -name '*.html' -print)"
+    },
+    "bin": {
+        "notebooks": "dist/bin/notebooks.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/src/index.d.ts",
+            "import": "./dist/src/index.js"
+        },
+        "./runtime": {
+            "types": "./dist/src/runtime/index.d.ts",
+            "import": "./dist/src/runtime/index.js"
+        },
+        "./vite": {
+            "types": "./dist/src/vite/index.d.ts",
+            "import": "./dist/src/vite/index.js"
+        },
+        "./*.css": "./dist/src/styles/*.css"
+    },
+    "dependencies": {
+        "@fontsource/inter": "^5.2.6",
+        "@fontsource/source-serif-4": "^5.2.8",
+        "@fontsource/spline-sans-mono": "^5.2.6",
+        "@lezer/common": "^1.2.3",
+        "@lezer/css": "^1.2.1",
+        "@lezer/highlight": "^1.2.1",
+        "@lezer/html": "^1.3.10",
+        "@lezer/javascript": "^1.5.1",
+        "@lezer/markdown": "^1.4.3",
+        "@observablehq/inspector": "^5.0.1",
+        "@observablehq/parser": "^6.1.0",
+        "@observablehq/runtime": "^6.0.0",
+        "@sindresorhus/slugify": "^2.2.1",
+        "acorn": "^8.15.0",
+        "acorn-walk": "^8.3.4",
+        "markdown-it": "^14.1.0",
+        "markdown-it-anchor": "^9.2.0",
+        "vite": "^7.0.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.29.0",
+        "@types/jsdom": "^21.1.7",
+        "@types/markdown-it": "^14.1.2",
+        "eslint": "^9.29.0",
+        "globals": "^16.2.0",
+        "htl": "^0.3.1",
+        "jsdom": "^26.1.0",
+        "tsx": "^4.20.3",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.35.0",
+        "vitest": "^3.2.4"
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./javascript/parse.js";
+export * from "./javascript/template.js";
+export * from "./javascript/transpile.js";
+export * from "./lib/notebook.js";
+export * from "./lib/serialize.js";

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export * from "./javascript/parse.js";
+export * from "./javascript/template.js";
+export * from "./javascript/transpile.js";
+export * from "./lib/notebook.js";
+export * from "./lib/serialize.js";

package/dist/src/javascript/assignments.d.ts

@@ -0,0 +1,2 @@
+import type { Identifier, Node } from "acorn";
+export declare function checkAssignments(node: Node, references: Identifier[], input: string): void;

package/dist/src/javascript/assignments.js

@@ -0,0 +1,37 @@
+import { defaultGlobals } from "./globals.js";
+import { syntaxError } from "./syntaxError.js";
+import { simple } from "./walk.js";
+export function checkAssignments(node, references, input) {
+    function checkConst(node) {
+        switch (node.type) {
+            case "Identifier":
+                if (references.includes(node))
+                    throw syntaxError(`Assignment to external variable '${node.name}'`, node, input);
+                if (defaultGlobals.has(node.name))
+                    throw syntaxError(`Assignment to global '${node.name}'`, node, input);
+                break;
+            case "ObjectPattern":
+                node.properties.forEach((node) => checkConst(node.type === "Property" ? node.value : node));
+                break;
+            case "ArrayPattern":
+                node.elements.forEach((node) => node && checkConst(node));
+                break;
+            case "RestElement":
+                checkConst(node.argument);
+                break;
+        }
+    }
+    function checkConstLeft({ left }) {
+        checkConst(left);
+    }
+    function checkConstArgument({ argument }) {
+        checkConst(argument);
+    }
+    simple(node, {
+        AssignmentExpression: checkConstLeft,
+        AssignmentPattern: checkConstLeft,
+        UpdateExpression: checkConstArgument,
+        ForOfStatement: checkConstLeft,
+        ForInStatement: checkConstLeft
+    });
+}

package/dist/src/javascript/assignments.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/javascript/assignments.test.js

@@ -0,0 +1,33 @@
+import { assert, test } from "vitest";
+import { checkAssignments } from "./assignments.js";
+import { parseJavaScript } from "./parse.js";
+function check(input) {
+    const cell = parseJavaScript(input);
+    checkAssignments(cell.body, cell.references, input);
+}
+test("allows non-external assignments", () => {
+    assert.doesNotThrow(() => check("let foo = 1;\nfoo = 2;"));
+    assert.doesNotThrow(() => check("let foo = 1;\nfor (foo of []);"));
+});
+test("allows external references", () => {
+    assert.doesNotThrow(() => check("foo + 1;"));
+});
+test("does not allow external assignments", () => {
+    assert.throws(() => check("foo = 1;"), /external variable 'foo'/);
+    assert.throws(() => check("foo++;"), /external variable 'foo'/);
+    assert.throws(() => check("++foo;"), /external variable 'foo'/);
+    assert.throws(() => check("({foo} = {});"), /external variable 'foo'/);
+    assert.throws(() => check("({foo: bar} = {});"), /external variable 'bar'/);
+    assert.throws(() => check("([foo] = []);"), /external variable 'foo'/);
+    assert.throws(() => check("let foo = 1;\n({...bar} = {});"), /external variable 'bar'/);
+    assert.throws(() => check("let foo = 1;\n([...bar] = []);"), /external variable 'bar'/);
+    assert.throws(() => check("let foo = 1;\nbar = 1;"), /external variable 'bar'/);
+    assert.throws(() => check("function f() { foo = 1; }"), /external variable 'foo'/);
+});
+test("does not allow external assignments via for…of or for…in", () => {
+    assert.throws(() => check("for (foo of []);"), /external variable 'foo'/);
+    assert.throws(() => check("for (foo in {});"), /external variable 'foo'/);
+});
+test("does not allow global assignments", () => {
+    assert.throws(() => check("window = 1;"), /global 'window'/);
+});

package/dist/src/javascript/awaits.d.ts

@@ -0,0 +1,2 @@
+import type { Node } from "acorn";
+export declare function findAwaits(node: Node): Node[];

package/dist/src/javascript/awaits.js

@@ -0,0 +1,23 @@
+import { recursive } from "./walk.js";
+export function findAwaits(node) {
+    const nodes = [];
+    recursive(node, null, {
+        FunctionDeclaration() { },
+        FunctionExpression() { },
+        ArrowFunctionExpression() { },
+        ForOfStatement(node, state, callback) {
+            if (node.await)
+                nodes.push(node);
+            if (node.left)
+                callback(node.left, state);
+            if (node.right)
+                callback(node.right, state);
+            if (node.body)
+                callback(node.body, state);
+        },
+        AwaitExpression(node) {
+            nodes.push(node);
+        }
+    });
+    return nodes;
+}

package/dist/src/javascript/awaits.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/javascript/awaits.test.js

@@ -0,0 +1,22 @@
+import { assert, expect, test } from "vitest";
+import { findAwaits } from "./awaits.js";
+import { parseJavaScript } from "./parse.js";
+function find(input) {
+    return findAwaits(parseJavaScript(input).body);
+}
+test("finds top-level awaits", () => {
+    expect(find("await 1;")).toMatchSnapshot();
+    expect(find("(1, await 2);")).toMatchSnapshot();
+    expect(find("1 + await 2;")).toMatchSnapshot();
+    expect(find("if (true) { await 3; }")).toMatchSnapshot();
+    expect(find("for await (const f of []);")).toMatchSnapshot();
+    expect(find("for (const f of await []);")).toMatchSnapshot();
+    expect(find("let f, g; for ({[await f]: g} of await []);")).toMatchSnapshot();
+    expect(find("for (const f of []) await f;")).toMatchSnapshot();
+    expect(find("for (const f in await {});")).toMatchSnapshot();
+});
+test("ignores awaits within functions", () => {
+    assert.deepStrictEqual(find("async function f() { await 1; }"), []);
+    assert.deepStrictEqual(find("let f = (async function () { await 1; });"), []);
+    assert.deepStrictEqual(find("let f = (async () => { await 1; });"), []);
+});

package/dist/src/javascript/declarations.d.ts

@@ -0,0 +1,2 @@
+import type { Identifier, Program } from "acorn";
+export declare function findDeclarations(node: Program, input: string): Identifier[];

package/dist/src/javascript/declarations.js

@@ -0,0 +1,45 @@
+import { defaultGlobals } from "./globals.js";
+import { syntaxError } from "./syntaxError.js";
+export function findDeclarations(node, input) {
+    const declarations = [];
+    function declareLocal(node) {
+        if (defaultGlobals.has(node.name) || node.name === "arguments") {
+            throw syntaxError(`Global '${node.name}' cannot be redefined`, node, input);
+        }
+        declarations.push(node);
+    }
+    function declarePattern(node) {
+        switch (node.type) {
+            case "Identifier":
+                declareLocal(node);
+                break;
+            case "ObjectPattern":
+                node.properties.forEach((node) => declarePattern(node.type === "Property" ? node.value : node));
+                break;
+            case "ArrayPattern":
+                node.elements.forEach((node) => node && declarePattern(node));
+                break;
+            case "RestElement":
+                declarePattern(node.argument);
+                break;
+            case "AssignmentPattern":
+                declarePattern(node.left);
+                break;
+        }
+    }
+    for (const child of node.body) {
+        switch (child.type) {
+            case "VariableDeclaration":
+                child.declarations.forEach((node) => declarePattern(node.id));
+                break;
+            case "ClassDeclaration":
+            case "FunctionDeclaration":
+                declareLocal(child.id);
+                break;
+            case "ImportDeclaration":
+                child.specifiers.forEach((node) => declareLocal(node.local));
+                break;
+        }
+    }
+    return declarations;
+}

package/dist/src/javascript/files.d.ts

@@ -0,0 +1,3 @@
+import type { Node } from "acorn";
+import { Sourcemap } from "./sourcemap.js";
+export declare function rewriteFileExpressions(output: Sourcemap, body: Node): void;

package/dist/src/javascript/files.js

@@ -0,0 +1,18 @@
+import { findReferences } from "./references.js";
+import { simple } from "./walk.js";
+export function rewriteFileExpressions(output, body) {
+    const files = new Set(findReferences(body, { filterReference: ({ name }) => name === "FileAttachment" }));
+    simple(body, {
+        CallExpression(node) {
+            const { callee } = node;
+            if (callee.type !== "Identifier" || !files.has(callee))
+                return;
+            const args = node.arguments;
+            if (args.length === 0)
+                return;
+            const [arg] = args;
+            output.insertLeft(arg.start, "new URL(");
+            output.insertRight(arg.end, ", import.meta.url).href");
+        }
+    });
+}

package/dist/src/javascript/globals.d.ts

@@ -0,0 +1 @@
+export declare const defaultGlobals: Set<string>;

package/dist/src/javascript/globals.js

@@ -0,0 +1,86 @@
+export const defaultGlobals = new Set([
+    "Array",
+    "ArrayBuffer",
+    "atob",
+    "AudioContext",
+    "Blob",
+    "Boolean",
+    "BigInt",
+    "btoa",
+    "clearInterval",
+    "clearTimeout",
+    "console",
+    "crypto",
+    "CustomEvent",
+    "DataView",
+    "Date",
+    "decodeURI",
+    "decodeURIComponent",
+    "devicePixelRatio",
+    "document",
+    "encodeURI",
+    "encodeURIComponent",
+    "Error",
+    "escape",
+    "eval",
+    "fetch",
+    "File",
+    "FileList",
+    "FileReader",
+    "Float32Array",
+    "Float64Array",
+    "Function",
+    "Headers",
+    "Image",
+    "ImageData",
+    "Infinity",
+    "Int16Array",
+    "Int32Array",
+    "Int8Array",
+    "Intl",
+    "isFinite",
+    "isNaN",
+    "JSON",
+    "Map",
+    "Math",
+    "NaN",
+    "Number",
+    "navigator",
+    "Object",
+    "observable", // for observable.params.foo
+    "parseFloat",
+    "parseInt",
+    "performance",
+    "Path2D",
+    "Promise",
+    "Proxy",
+    "RangeError",
+    "ReferenceError",
+    "Reflect",
+    "RegExp",
+    "cancelAnimationFrame",
+    "requestAnimationFrame",
+    "Set",
+    "setInterval",
+    "setTimeout",
+    "String",
+    "Symbol",
+    "SyntaxError",
+    "TextDecoder",
+    "TextEncoder",
+    "this",
+    "TypeError",
+    "Uint16Array",
+    "Uint32Array",
+    "Uint8Array",
+    "Uint8ClampedArray",
+    "undefined",
+    "unescape",
+    "URIError",
+    "URL",
+    "WeakMap",
+    "WeakSet",
+    "WebSocket",
+    "Worker",
+    "window"
+]);

package/dist/src/javascript/imports/jsr.d.ts

@@ -0,0 +1,2 @@
+/** If specifier is an jsr: protocol import, resolves it. */
+export declare function resolveJsrImport(specifier: string): string;

package/dist/src/javascript/imports/jsr.js

@@ -0,0 +1,6 @@
+/** If specifier is an jsr: protocol import, resolves it. */
+export function resolveJsrImport(specifier) {
+    if (!specifier.startsWith("jsr:"))
+        return specifier;
+    return `https://esm.sh/jsr/${specifier.slice(4)}`;
+}

package/dist/src/javascript/imports/npm.d.ts

@@ -0,0 +1,2 @@
+/** If specifier is an npm: protocol import, resolves it. */
+export declare function resolveNpmImport(specifier: string): string;