@weborigami/origami 0.6.10 → 0.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.6.10",
+  "version": "0.6.12",
   "description": "Web Origami language, CLI, framework, and server",
   "type": "module",
   "repository": {
@@ -13,23 +13,23 @@
   "main": "./main.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "24.10.1",
+    "@types/node": "25.3.2",
     "typescript": "5.9.3"
   },
   "dependencies": {
-    "@weborigami/async-tree": "0.6.10",
+    "@hpcc-js/wasm-graphviz": "^1.21.0",
+    "@weborigami/async-tree": "0.6.12",
     "@weborigami/json-feed-to-rss": "1.0.1",
-    "@weborigami/language": "0.6.10",
+    "@weborigami/language": "0.6.12",
     "css-tree": "3.1.0",
-    "graphviz-wasm": "3.0.2",
     "highlight.js": "11.11.1",
-    "jsdom": "27.2.0",
-    "marked": "17.0.0",
+    "jsdom": "28.1.0",
+    "marked": "17.0.3",
     "marked-gfm-heading-id": "4.1.3",
     "marked-highlight": "2.2.3",
     "marked-smartypants": "1.1.11",
     "sharp": "0.34.5",
-    "yaml": "2.8.1"
+    "yaml": "2.8.2"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/dev/changes.js

@@ -1,4 +1,10 @@
-import { args, trailingSlash, Tree } from "@weborigami/async-tree";
+import {
+  args,
+  isStringlike,
+  toString,
+  trailingSlash,
+  Tree,
+} from "@weborigami/async-tree";
 
 /**
  * Given an old tree and a new tree, return a tree of changes indicated
@@ -44,9 +50,9 @@ export default async function changes(oldMaplike, newMaplike) {
         result ??= {};
         result[oldKey] = treeChanges;
       }
-    } else if (oldValue?.toString && newValue?.toString) {
-      const oldText = oldValue.toString();
-      const newText = newValue.toString();
+    } else if (isStringlike(oldValue) && isStringlike(newValue)) {
+      const oldText = toString(oldValue);
+      const newText = toString(newValue);
       if (oldText !== newText) {
         result ??= {};
         result[oldKey] = "changed";

package/src/dev/debug2/ReadMe.md

@@ -0,0 +1,29 @@
+This folder implements the Origami debugger, a local web server whose architecture is complex enough to warrant documenting here.
+
+## Design goals
+
+1. Easily start a debug server. An Origami dev can start a server with `ori debug2 <expression>, [port]`, where `<expr>` is an Origami expression yielding a map-based tree and `port` is an optional port (default: 5000). This command should start the server and display console text indicating that the server is running on the indicated port. The dev can browse to that location to view their site.
+
+2. Watch the local project for changes and reload accordingly. If the developer edits a file and refreshes the browser, they should see the result of their edit.
+
+3. Load JavaScript code in a clean Node environment, and recreate a clean environment whenever the developer edits a file. If the dev edits a file `fn.js` to remove a global definition, the server should reload its state such that the old global is gone.
+
+4. Deliver reasonable performance for local development. Minimize the amount of interprocess communication (IPC) where possible.
+
+5. Keep the architecture simple enough that it's reliable and maintainable.
+
+## Architecture
+
+Goal #1 (easily start server) implies that the parent debug2 process is the one establishing the server port number that the dev can see, and that the port number is kept stable across reloads.
+
+To achieve goal #3 (clean Node environment), the debug2 command loads the Origami project in a child process that can be killed and restarted on each reload.
+
+These points are in tension: it would be faster (goal #4) for the child process to directly respond to requests, but it's impossible for that port number to be stable while also having a clean Node environment.
+
+As a reliable and maintainable compromise (goal #5), the child process starts its own server on an ephemeral local port. (An ephemeral port has a port number is dynamically chosen by the OS from a designated range, and which is expected to be used only for a short period of time.) The child then communicates its port number to the parent process. The parent's server (the one the dev can see) then uses that port to proxy HTTP requests to the child's server. The parent is acting as a _reverse proxy_.
+
+Requests are routed to the resource tree as follows:
+
+browser → parent server → child server → tree → child server → parent server → browser
+
+When the local project changes, the parent server creates a new child process and begins routing requests to it. In the background, it tells the previous child to drain any in-flight requests; when that's complete, the child process is killed.

package/src/dev/debug2/debug2.js

@@ -0,0 +1,301 @@
+import { OrigamiFileMap } from "@weborigami/language";
+import { fork } from "node:child_process";
+import http from "node:http";
+import path from "node:path";
+
+const PUBLIC_HOST = "127.0.0.1";
+const PUBLIC_PORT = 5000;
+
+// Module that loads the server in the child process
+const childModuleUrl = new URL("./debugChild.js", import.meta.url);
+
+// The active child process and port
+/** @typedef {import("node:child_process").ChildProcess} ChildProcess */
+/** @typedef {{ process: ChildProcess, port: number | null }} ChildInfo */
+/** @type {ChildInfo | null} */
+let activeChild = null;
+
+// The most recently started child (may not be ready yet)
+/** @type {ChildInfo | null} */
+let pendingChild = null;
+
+/**
+ * Given an Origami function, determine the runtime state's parent container,
+ * then start a new debug server with that parent as the root of the resource
+ * tree.
+ *
+ * This function expects an unevaluated expression. It will obtain the original
+ * source of the expression and pass that to the child for evaluation. This
+ * arrangement ensures the expression is evaluated in a clean Node context (not
+ * polluted by previous evaluations).
+ *
+ * @param {import("@weborigami/language").AnnotatedCode} code
+ * @param {import("@weborigami/language").RuntimeState} state
+ */
+export default async function debug2(code, state) {
+  if (
+    !(code instanceof Array) ||
+    code.source === undefined ||
+    arguments.length < 2
+  ) {
+    throw new TypeError(
+      "Dev.debug2 expects an Origami expression to evaluate: `debug2 <expression>`",
+    );
+  }
+  const { parent } = state;
+  // @ts-ignore
+  const parentPath = parent?.path;
+  if (parentPath === undefined) {
+    throw new Error("Dev.debug2 couldn't work out the parent path.");
+  }
+
+  const serverOptions = {
+    expression: code.source,
+    parent: parentPath,
+  };
+
+  const tree = new OrigamiFileMap(parentPath);
+  tree.watch();
+  tree.addEventListener?.("change", (event) => {
+    // @ts-ignore
+    const { filePath } = event.options;
+    if (isJavaScriptFile(filePath)) {
+      // Need to restart the child process
+      console.log("JavaScript file changed, restarting server…");
+      startChild(serverOptions);
+    } else if (isPackageJsonFile(filePath)) {
+      // Need to restart the child process
+      console.log("package.json changed, restarting server…");
+      startChild(serverOptions);
+    } else {
+      // Just have the child reevaluate the expression
+      console.log("File changed, reloading site…");
+      activeChild?.process.send({ type: "REEVALUATE" });
+    }
+  });
+
+  // ---- Public server
+  const publicServer = http.createServer(proxyRequest);
+  publicServer.listen(PUBLIC_PORT, PUBLIC_HOST, () => {
+    startChild(serverOptions);
+    console.log(
+      `Server running at http://localhost:${PUBLIC_PORT}. Press Ctrl+C to stop.`,
+    );
+  });
+}
+debug2.needsState = true;
+debug2.unevaluatedArgs = true;
+
+/**
+ * Give a child process a chance to finish any in-flight requests before we kill
+ * it.
+ *
+ * @param {ChildProcess} childProcess
+ */
+async function drainAndStopChild(childProcess) {
+  if (childProcess.killed) {
+    return;
+  }
+
+  // Ask it to drain first.
+  try {
+    childProcess.send({ type: "DRAIN" });
+  } catch {
+    // ignore
+  }
+
+  const drained = new Promise((resolve) => {
+    const onMessage = (msg) => {
+      if (msg && typeof msg === "object" && msg.type === "DRAINED") {
+        cleanup(resolve);
+      }
+    };
+    const onExit = () => cleanup(resolve);
+
+    function cleanup(done) {
+      childProcess.off("message", onMessage);
+      childProcess.off("exit", onExit);
+      done();
+    }
+
+    childProcess.on("message", onMessage);
+    childProcess.on("exit", onExit);
+  });
+
+  // Give it a short grace window to finish in-flight work.
+  const GRACE_MS = 1500;
+  await Promise.race([
+    drained,
+    new Promise((r) => setTimeout(r, GRACE_MS).unref()),
+  ]);
+
+  if (!childProcess.killed) {
+    childProcess.kill("SIGTERM");
+  }
+
+  // Final escalation.
+  setTimeout(() => {
+    // Child should have exited by now, but if not kill it
+    if (!childProcess.killed) {
+      childProcess.kill("SIGKILL");
+    }
+  }, GRACE_MS).unref();
+}
+
+function isJavaScriptFile(filePath) {
+  const extname = path.extname(filePath).toLowerCase();
+  const jsExtensions = [".cjs", ".js", ".mjs", ".ts"];
+  return jsExtensions.includes(extname);
+}
+
+function isPackageJsonFile(filePath) {
+  return path.basename(filePath).toLowerCase() === "package.json";
+}
+
+/**
+ * Proxy incoming requests to the active child server, or return a 503 if not
+ * ready.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ */
+function proxyRequest(request, response) {
+  if (!activeChild) {
+    response.statusCode = 503;
+    response.setHeader("content-type", "text/plain; charset=utf-8");
+    response.end("Dev server is starting…\n");
+    return;
+  }
+
+  const { port } = activeChild;
+
+  // Minimal hop-by-hop header stripping
+  const headers = { ...request.headers };
+  delete headers.connection;
+  delete headers["proxy-connection"];
+  delete headers["keep-alive"];
+  delete headers.te;
+  delete headers.trailer;
+  delete headers["transfer-encoding"];
+  delete headers.upgrade;
+
+  const upstreamRequest = http.request(
+    {
+      host: PUBLIC_HOST,
+      port,
+      method: request.method,
+      path: request.url,
+      headers,
+    },
+    (upstreamResponse) => {
+      response.writeHead(
+        upstreamResponse.statusCode ?? 502,
+        upstreamResponse.statusMessage,
+        upstreamResponse.headers,
+      );
+      upstreamResponse.pipe(response);
+    },
+  );
+
+  upstreamRequest.on("error", (err) => {
+    // Stop piping the request body
+    request.unpipe(upstreamRequest);
+    upstreamRequest.destroy();
+
+    // Only send error response if headers haven't been sent yet
+    if (!response.headersSent) {
+      response.statusCode = 502;
+      response.setHeader("content-type", "text/plain; charset=utf-8");
+      response.end(`Upstream error: ${err.message}\n`);
+    } else {
+      // Headers already sent, can't send error message - just close
+      response.destroy();
+    }
+  });
+
+  // Also handle errors on the incoming request
+  request.on("error", () => {
+    upstreamRequest.destroy();
+  });
+
+  request.pipe(upstreamRequest);
+}
+
+/**
+ * Start a new child process.
+ *
+ * This will be a pending process until it sends a READY message, at which point
+ * it becomes active and any previous active child is drained and stopped.
+ */
+function startChild(serverOptions) {
+  const { expression, parent } = serverOptions;
+
+  // Start the child process, passing parent path via an environment variable.
+  /** @type {ChildProcess} */
+  let childProcess;
+  try {
+    childProcess = fork(childModuleUrl, [], {
+      stdio: ["inherit", "inherit", "inherit", "ipc"],
+      env: {
+        ...process.env,
+        ORIGAMI_EXPRESSION: expression,
+        ORIGAMI_PARENT: parent,
+      },
+    });
+  } catch (error) {
+    throw new Error("Dev.debug2: failed to start child server:", {
+      cause: error,
+    });
+  }
+
+  // This becomes the pending child immediately
+  pendingChild = { process: childProcess, port: null };
+
+  // Listen for messages from the child about its status
+  childProcess.on("message", (/** @type {any} */ message) => {
+    if (!message || typeof message !== "object") {
+      return;
+    }
+
+    if (message.type === "READY" && typeof message.port === "number") {
+      // Only promote to active if this is still the pending child
+      if (pendingChild?.process === childProcess) {
+        const previousChild = activeChild;
+
+        activeChild = pendingChild;
+        pendingChild.port = message.port;
+        pendingChild = null;
+
+        // Drain previous child in background (don't wait)
+        if (previousChild?.process && previousChild.process !== childProcess) {
+          drainAndStopChild(previousChild.process).catch((err) =>
+            console.error("[drain]", err),
+          );
+        }
+      } else {
+        // This child was superseded by a newer one, kill it
+        // console.log("Child process superseded by newer one, killing it...");
+        childProcess.kill("SIGTERM");
+      }
+    }
+
+    if (message.type === "FATAL") {
+      // Child couldn't start (import error, etc.)
+      // Keep previous active child if any; otherwise we'll serve 500/503.
+      console.error("[child fatal]", message.error ?? message);
+      if (pendingChild?.process === childProcess) {
+        pendingChild = null;
+      }
+    }
+  });
+
+  childProcess.on("exit", (code, signal) => {
+    if (activeChild?.process === childProcess) {
+      // Active child died unexpectedly.
+      activeChild = null;
+    }
+    if (pendingChild?.process === childProcess) {
+      pendingChild = null;
+    }
+  });
+}

package/src/dev/debug2/debugChild.js

@@ -0,0 +1,143 @@
+import http from "node:http";
+import { requestListener } from "../../server/server.js";
+import expressionTree from "./expressionTree.js";
+
+/**
+ * The debug2 command runs this module in a child process, passing in a parent
+ * path in an environment variable.
+ *
+ * This module starts an HTTP server that will serve resources from that tree.
+ * When the server is ready, it sends a message to the parent process with the
+ * port number. The parent then proxies incoming requests to that port.
+ *
+ * If the parent needs to start a new child process, it will tell the old one to
+ * drain any in-flight requests and stop accepting new ones.
+ */
+
+const PUBLIC_HOST = "127.0.0.1";
+
+function fail(message) {
+  console.error(message);
+  process.send?.({ type: "FATAL", error: message });
+  process.exit(1);
+}
+
+/** @type {string} */
+// @ts-ignore
+const expression = process.env.ORIGAMI_EXPRESSION;
+if (expression === undefined) {
+  fail("Missing Origami expression");
+}
+
+/** @type {string} */
+// @ts-ignore
+const parentPath = process.env.ORIGAMI_PARENT;
+if (parentPath === undefined) {
+  fail("Missing Origami parent");
+}
+
+// An indirect pointer to the tree of resources;
+let treeHandle = {};
+
+// Initial evaluation of the expression
+await evaluateExpression();
+
+// Serve the tree of resources
+const listener = requestListener(treeHandle);
+const server = http.createServer(listener);
+
+// Track live connections so we can drain/close cleanly.
+const sockets = new Set();
+server.on("connection", (socket) => {
+  sockets.add(socket);
+  socket.on("close", () => sockets.delete(socket));
+});
+
+// Helpful to avoid the old child keeping idle sockets around forever during drain.
+server.keepAliveTimeout = 1000;
+server.headersTimeout = 5000;
+
+// Draining state
+let draining = false;
+let serverClosed = false;
+
+function beginDrain() {
+  if (draining) return;
+  draining = true;
+
+  // Stop accepting new connections.
+  server.close(() => {
+    serverClosed = true;
+    maybeFinishDrain();
+  });
+
+  // Give in-flight requests a moment, then force-close remaining sockets.
+  const GRACE_MS = 1200;
+  setTimeout(() => {
+    for (const socket of sockets) {
+      // This will also abort any in-flight requests on that socket if still active.
+      socket.destroy();
+    }
+    // socket "close" events will shrink the set; check again soon.
+    setTimeout(maybeFinishDrain, 50).unref();
+  }, GRACE_MS).unref();
+
+  // Absolute last resort: don’t hang forever.
+  const HARD_MS = 3000;
+  setTimeout(() => process.exit(0), HARD_MS).unref();
+}
+
+async function evaluateExpression() {
+  const tree = await expressionTree(expression, parentPath);
+  if (!tree) {
+    fail("Dev.debug2: expression did not evaluate to a maplike resource tree");
+  }
+  Object.setPrototypeOf(treeHandle, tree);
+
+  // Clean the handle of any named properties or symbols that have been set
+  // directly on it.
+  try {
+    for (const key of Object.getOwnPropertyNames(treeHandle)) {
+      delete treeHandle[key];
+    }
+    for (const key of Object.getOwnPropertySymbols(treeHandle)) {
+      delete treeHandle[key];
+    }
+  } catch {
+    // Ignore errors.
+  }
+}
+
+function maybeFinishDrain() {
+  if (!draining) return;
+  if (serverClosed && sockets.size === 0) {
+    process.send?.({ type: "DRAINED" });
+    process.exit(0);
+  }
+}
+
+// Drain when instructed by parent, or if parent dies.
+process.on("message", async (/** @type {any} */ message) => {
+  if (message?.type === "DRAIN") {
+    beginDrain();
+  } else if (message?.type === "REEVALUATE") {
+    await evaluateExpression();
+  }
+});
+process.on("SIGTERM", beginDrain);
+process.on("SIGINT", beginDrain);
+
+process.on("disconnect", () => {
+  // Parent process died, exit immediately
+  // console.log("Parent process disconnected, exiting...");
+  process.exit(0);
+});
+
+// Listen on ephemeral port
+server.listen(0, PUBLIC_HOST, () => {
+  // Tell parent we're ready to receive requests on our port
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : null;
+  process.send?.({ type: "READY", port });
+  // console.log(`Child server running at http://${PUBLIC_HOST}:${port}.`);
+});

package/src/dev/debug2/debugTransform.js

@@ -0,0 +1,152 @@
+import {
+  AsyncMap,
+  Tree,
+  box,
+  isPlainObject,
+  isPrimitive,
+  isUnpackable,
+  jsonKeys,
+  scope,
+  trailingSlash,
+} from "@weborigami/async-tree";
+import { projectGlobals } from "@weborigami/language";
+import indexPage from "../../origami/indexPage.js";
+import yaml from "../../origami/yaml.js";
+
+/**
+ * Transform the given map-based tree to add debugging resources:
+ *
+ * - default index.html page
+ * - default .keys.json resource
+ * - support for invoking Origami commands via keys starting with '!'
+ *
+ * Also transform a simple object result to YAML for viewing.
+ *
+ * @param {import("@weborigami/async-tree").Maplike} maplike
+ */
+export default function debugTransform(maplike) {
+  const source = Tree.from(maplike, { deep: true });
+  return Object.assign(new AsyncMap(), {
+    description: "debug resources",
+
+    async get(key) {
+      // Ask the tree if it has the key.
+      let value = await source.get(key);
+
+      if (value === undefined) {
+        // The tree doesn't have the key; try the defaults.
+        if (key === "index.html") {
+          // Generate an index page for this site
+          value = await indexPage(source);
+        } else if (key === ".keys.json") {
+          value = await jsonKeys.stringify(source);
+        } else if (typeof key === "string" && key.startsWith("!")) {
+          value = await invokeOrigamiCommand(source, key);
+        }
+      }
+
+      if (isSimpleObject(value)) {
+        // Serialize to YAML, but also allow the result to be further traversed
+        const object = value;
+        const yamlText = await yaml(object);
+        value = box(yamlText);
+        value.unpack = () =>
+          Tree.merge(object, {
+            "index.html": yamlText,
+          });
+      } else if (Tree.isMaplike(value) && !Tree.isMap(value)) {
+        // Make it a map so we can debug it
+        value = Tree.from(value);
+      }
+
+      if (Tree.isMap(value)) {
+        // Ensure this transform is applied to any map result
+        value = debugTransform(value);
+      } else if (value?.unpack) {
+        // If the value isn't a tree, but has a tree attached via an `unpack`
+        // method, wrap the unpack method to add this transform.
+        const original = value.unpack.bind(value);
+        value.unpack = async () => {
+          const content = await original();
+          if (!Tree.isTraversable(content) || typeof content === "function") {
+            return content;
+          }
+          /** @type {any} */
+          let tree = Tree.from(content);
+          return debugTransform(tree);
+        };
+      }
+      return value;
+    },
+
+    async keys() {
+      return source.keys();
+    },
+
+    // If this value is given to the server, the server will call this pack()
+    // method. We respond with the index page.
+    async pack() {
+      return this.get("index.html");
+    },
+
+    source,
+
+    trailingSlashKeys: true,
+  });
+}
+
+async function invokeOrigamiCommand(tree, key) {
+  // Key is an Origami command; invoke it.
+  const globals = await projectGlobals(tree);
+  const commandName = trailingSlash.remove(key.slice(1).trim());
+
+  // Look for command as a global or Dev command
+  const command = globals[commandName] ?? globals.Dev?.[commandName];
+  let value;
+  if (command) {
+    value = await command(tree);
+  } else {
+    // Look for command in scope
+    const parentScope = await scope(tree);
+    value = await parentScope.get(commandName);
+
+    if (value === undefined) {
+      throw new Error(`Unknown Origami command: ${commandName}`);
+    }
+  }
+
+  if (trailingSlash.has(key) && isUnpackable(value)) {
+    value = await value.unpack();
+  }
+
+  return value;
+}
+
+/**
+ * Returns true if the object is "simple": a plain object or array that does not
+ * have any getters in its deep structure.
+ *
+ * This test is used to avoid serializing complex objects to YAML.
+ *
+ * @param {any} object
+ */
+function isSimpleObject(object) {
+  if (!(object instanceof Array || isPlainObject(object))) {
+    return false;
+  }
+
+  for (const key of Object.keys(object)) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (!descriptor) {
+      continue; // not sure why this would happen
+    } else if (typeof descriptor.get === "function") {
+      return false; // Getters aren't simple
+    } else if (isPrimitive(descriptor.value)) {
+      continue; // Primitives are simple
+    } else if (!isSimpleObject(descriptor.value)) {
+      return false; // Deep structure wasn't simple
+    }
+  }
+
+  return true;
+}

package/src/dev/debug2/expressionTree.js

@@ -0,0 +1,50 @@
+import {
+  ConstantMap,
+  isUnpackable,
+  setParent,
+  Tree,
+} from "@weborigami/async-tree";
+import { evaluate, OrigamiFileMap, projectGlobals } from "@weborigami/language";
+import debugTransform from "./debugTransform.js";
+
+// So we can distinguish different trees in the debugger
+let version = 0;
+
+/**
+ * Evaluate the given expression using the indicated parent path to produce a
+ * resource tree, then transform that tree with debug resources and return it.
+ *
+ * @param {string} expression
+ * @param {string} parentPath
+ */
+export default async function expressionTree(expression, parentPath) {
+  const parent = new OrigamiFileMap(parentPath);
+  const globals = await projectGlobals(parent);
+
+  let maplike;
+  try {
+    // Evaluate the expression
+    maplike = await evaluate(expression, { globals, mode: "shell", parent });
+    if (isUnpackable(maplike)) {
+      maplike = await maplike.unpack();
+    }
+  } catch (/** @type {any} */ error) {
+    return new ConstantMap(error.message);
+  }
+
+  if (!Tree.isMaplike(maplike)) {
+    return new ConstantMap(
+      `Dev.debug2: expression did not evaluate to a resource tree: ${expression}`,
+    );
+  }
+
+  // Set the parent so that Origami debug commands can find things in scope
+  setParent(maplike, parent);
+
+  // Add debugging resources
+  const tree = debugTransform(maplike);
+
+  /** @type {any} */ (tree).version = version++;
+
+  return tree;
+}

package/src/dev/dev.js

@@ -11,6 +11,7 @@ export { default as copy } from "./copy.js";
 export { default as audit } from "./crawler/audit.js";
 export { default as crawl } from "./crawler/crawl.js";
 export { default as debug } from "./debug.js";
+export { default as debug2 } from "./debug2/debug2.js";
 export { default as explore } from "./explore.js";
 export { default as help } from "./help.js";
 export { default as log } from "./log.js";

package/src/dev/findOpenPort.js

@@ -0,0 +1,15 @@
+import { createServer } from "node:net";
+
+// Return the first open port number on or after the given port number.
+// From https://gist.github.com/mikeal/1840641?permalink_comment_id=2896667#gistcomment-2896667
+export default function findOpenPort(port) {
+  const server = createServer();
+  return new Promise((resolve, reject) =>
+    server
+      .on("error", (/** @type {any} */ error) =>
+        error.code === "EADDRINUSE" ? server.listen(++port) : reject(error),
+      )
+      .on("listening", () => server.close(() => resolve(port)))
+      .listen(port),
+  );
+}

package/src/dev/help.yaml

@@ -45,6 +45,9 @@ Dev:
     version:
       args: ()
       description: Return the version number of the Origami language
+    visit:
+      args: (tree)
+      description: Force reading of all values from the tree
     watch:
       args: (tree, fn)
       description: Reevaluate fn when tree changes

package/src/dev/svg.js

@@ -1,9 +1,9 @@
+import { Graphviz } from "@hpcc-js/wasm-graphviz";
 import { args } from "@weborigami/async-tree";
-import graphviz from "graphviz-wasm";
 
 import dot from "./treeDot.js";
 
-let graphvizLoaded = false;
+let graphviz;
 
 /**
  * Render a tree visually in SVG format.
@@ -15,16 +15,15 @@ let graphvizLoaded = false;
  * @param {PlainObject} [options]
  */
 export default async function svg(maplike, options = {}) {
-  if (!graphvizLoaded) {
-    await graphviz.loadWASM();
-    graphvizLoaded = true;
+  if (!graphviz) {
+    graphviz = await Graphviz.load();
   }
   const tree = await args.map(maplike, "Dev.svg", { deep: true });
   const dotText = await dot(tree, options);
   if (dotText === undefined) {
     return undefined;
   }
-  const svgText = await graphviz.layout(dotText, "svg");
+  const svgText = await graphviz.dot(dotText);
   /** @type {any} */
   const result = new String(svgText);
   result.mediaType = "image/svg+xml";

package/src/origami/fetch.js

@@ -17,6 +17,6 @@ export default async function fetchBuiltin(resource, options, state) {
   const url = new URL(resource);
   const key = url.pathname;
 
-  return handleExtension(value, key, state.container);
+  return handleExtension(value, key, state?.parent);
 }
 fetchBuiltin.needsState = true;

package/src/origami/indexPage.js

@@ -61,6 +61,7 @@ ${list}
 
   /** @type {any} */
   const result = new String(html);
+  result.mediaType = "text/html; charset=utf-8";
   result.unpack = () => tree;
   return result;
 }

package/src/origami/ori.js

@@ -54,6 +54,14 @@ async function format(result) {
     return result;
   }
 
+  if (result instanceof Response) {
+    if (!result.ok) {
+      console.warn(`Response not OK: ${result.status} ${result.statusText}`);
+      return undefined;
+    }
+    return await result.arrayBuffer();
+  }
+
   /** @type {string|String|undefined} */
   let text;
 

package/src/origami/origami.js

@@ -1,10 +1,10 @@
 export { extension } from "@weborigami/async-tree";
 export { default as help } from "../dev/help.js"; // Alias
-export { default as document } from "./document.js";
-// export { default as htmlDom } from "./htmlDom.js";
 export { default as basename } from "./basename.js";
 export { default as csv } from "./csv.js";
+export { default as document } from "./document.js";
 export { default as fetch } from "./fetch.js";
+export { default as htmlDom } from "./htmlDom.js";
 export { default as htmlEscape } from "./htmlEscape.js";
 export { default as format } from "./image/format.js";
 export * as image from "./image/image.js";

package/src/server/constructResponse.js

@@ -1,32 +1,19 @@
-import {
-  extension,
-  isPacked,
-  isPlainObject,
-  isStringlike,
-  SiteMap,
-  toString,
-  Tree,
-} from "@weborigami/async-tree";
-import * as serialize from "../common/serialize.js";
+import { extension, isPacked, toString, Tree } from "@weborigami/async-tree";
+import { computedMIMEType } from "whatwg-mimetype";
 import { mediaTypeForExtension } from "./mediaTypes.js";
 
-const TypedArray = Object.getPrototypeOf(Uint8Array);
-
 /**
  * Given a resource that was returned from a route, construct an appropriate
- * HTTP Response indicating what should be sent to the client. Return null
- * if the resource is not a valid response.
+ * HTTP Response indicating what should be sent to the client.
  *
  * @param {import("node:http").IncomingMessage} request
  * @param {any} resource
- * @returns {Promise<Response|null>}
+ * @returns {Promise<Response>}
  */
 export default async function constructResponse(request, resource) {
   if (resource instanceof Response) {
     // Already a Response, return as is.
     return resource;
-  } else if (resource == null) {
-    return null;
   }
 
   // Determine media type, what data we'll send, and encoding.
@@ -53,59 +40,44 @@ export default async function constructResponse(request, resource) {
     }
   }
 
+  let body = resource;
+  if (!isPacked(resource)) {
+    // Can we treat it as text?
+    const text = toString(resource);
+    if (text) {
+      body = text;
+    }
+  }
+
+  // Determine MIME type
   let mediaType;
   if (resource.mediaType) {
     // Resource indicates its own media type.
     mediaType = resource.mediaType;
   } else {
-    // Infer expected media type from file extension on request URL.
+    // Do we know the media type based on the URL extension?
     const ext = extension.extname(url.pathname).toLowerCase();
-    mediaType = ext ? mediaTypeForExtension[ext] : undefined;
-  }
-
-  if (
-    (mediaType === "application/json" || mediaType === "text/yaml") &&
-    !isStringlike(resource)
-  ) {
-    // The request is for a JSON or YAML result, and the resource we got isn't
-    // yet a string: convert the resource to JSON or YAML now.
-    const tree = Tree.from(resource);
-    resource =
-      mediaType === "text/yaml"
-        ? await serialize.toYaml(tree)
-        : await serialize.toJson(tree);
-  } else if (
-    mediaType === undefined &&
-    (isPlainObject(resource) || resource instanceof Array)
-  ) {
-    // The resource is data, try showing it as YAML.
-    const tree = Tree.from(resource);
-    resource = await serialize.toYaml(tree);
-    mediaType = "text/yaml";
-  }
-
-  // By default, the body will be the resource we got
-  let body = resource;
-  if (!mediaType) {
-    // Maybe it's HTML?
-    const text = toString(resource);
-    if (text) {
-      mediaType = maybeHtml(text) ? "text/html" : "text/plain";
-      mediaType += "; charset=utf-8";
-      body = text;
-    }
-  } else if (
-    body instanceof TypedArray &&
-    mediaType &&
-    SiteMap.mediaTypeIsText(mediaType) &&
-    !mediaType.includes("charset")
-  ) {
-    // See if text is encoded in UTF-8.
-    const text = toString(resource);
-    if (text !== null) {
-      // We were able to decode the TypedArray as UTF-8 text.
-      body = text;
-      mediaType += "; charset=utf-8";
+    const extensionMediaType = ext ? mediaTypeForExtension[ext] : undefined;
+    if (extensionMediaType) {
+      mediaType = extensionMediaType;
+    } else {
+      // Use MIME Sniffing Standard to determine media type
+      const isString = typeof body === "string" || body instanceof String;
+      const bytes = isString ? new TextEncoder().encode(String(body)) : body;
+      let sniffedType;
+      try {
+        sniffedType = computedMIMEType(bytes);
+      } catch (error) {
+        // Ignore sniffing errors
+      }
+      if (sniffedType) {
+        if (isString && sniffedType.essence === "application/octet-stream") {
+          // Prefer text/plain for strings
+          mediaType = "text/plain";
+        } else {
+          mediaType = sniffedType.toString();
+        }
+      }
     }
   }
 
@@ -114,35 +86,12 @@ export default async function constructResponse(request, resource) {
   const validResponse = isPacked(body);
   if (!validResponse) {
     const typeName = body?.constructor?.name ?? typeof body;
-    console.error(
+    throw new Error(
       `A served tree must return a string or a TypedArray but returned an instance of ${typeName}.`,
     );
-    return null;
   }
 
   const options = mediaType ? { headers: { "Content-Type": mediaType } } : {};
   const response = new Response(body, options);
   return response;
 }
-
-// Return true if the resource appears to represent HTML
-function maybeHtml(text) {
-  if (!text) {
-    return false;
-  }
-  if (text.startsWith("<!DOCTYPE html>")) {
-    return true;
-  }
-  if (text.startsWith("<!--")) {
-    return true;
-  }
-  // Check if the text starts with an HTML tag.
-  // - start with possible whitespace
-  // - followed by '<'
-  // - followed by a letter
-  // - followed maybe by letters, digits, hyphens, underscores, colons, or periods
-  // - followed by '>', or
-  // - followed by whitespace, anything that's not '>', then a '>'
-  const tagRegex = /^\s*<[a-zA-Z][a-zA-Z0-9-_:\.]*(>|[\s]+[^>]*>)/;
-  return tagRegex.test(text);
-}

package/src/server/server.js

@@ -1,4 +1,4 @@
-import { Tree, keysFromPath } from "@weborigami/async-tree";
+import { Tree, keysFromPath, trailingSlash } from "@weborigami/async-tree";
 import { formatError } from "@weborigami/language";
 import { ServerResponse } from "node:http";
 import constructResponse from "./constructResponse.js";
@@ -64,12 +64,13 @@ export async function handleRequest(request, response, map) {
       resource = data ? await resource(data) : await resource();
     }
 
-    // Construct the response.
-    const constructed = await constructResponse(request, resource);
-    if (!constructed) {
+    if (resource == null) {
       return false;
     }
 
+    // Construct the response.
+    const constructed = await constructResponse(request, resource);
+
     // Copy the construct response to the ServerResponse and return true if
     // the response was valid.
     return copyResponse(constructed, response);
@@ -84,10 +85,10 @@ export function keysFromUrl(url) {
   const encodedKeys = keysFromPath(url.pathname);
   const keys = encodedKeys.map((key) => decodeURIComponent(key));
 
-  // If the path ends with a trailing slash, the final key will be an empty
-  // string. Change that to "index.html".
-  if (keys.at(-1) === "") {
-    keys[keys.length - 1] = "index.html";
+  // If the keys array is empty (the path was just a trailing slash) or if the
+  // path ended with a slash, add "index.html" to the end of the keys.
+  if (keys.length === 0 || trailingSlash.has(keys.at(-1))) {
+    keys.push("index.html");
   }
 
   return keys;
@@ -106,11 +107,10 @@ export function requestListener(maplike) {
     console.log(decodeURI(request.url));
     const handled = await handleRequest(request, response, tree);
     if (!handled) {
-      // Ignore exceptions that come up with sending a Not Found response.
-      try {
-        response.writeHead(404, { "Content-Type": "text/html" });
-        response.end(`Not found`, "utf-8");
-      } catch (error) {}
+      // Not found, return a 404.
+      response.statusCode = 404;
+      response.statusMessage = "Not Found";
+      response.end("Not Found", "utf-8");
     }
   };
 }