@daugasauron/dolly 0.1.4 → 0.1.5-rc.0

package/src/browser.mjs

@@ -3,26 +3,28 @@ import { holdIndicators, showIndicators } from "./page-indicators.mjs";
 import { hostRegistry } from "../host/modules.mjs";
 import { pageChords } from "./page-chords.mjs";
 import { terminalText } from "./terminal-text.mjs";
-import { DOLLY_IMAGES, DOLLY_STATIC_SOURCES, imageBase, loadImages } from "./images.mjs";
+import { bootstrapSources, imageBase, imageDefinition, loadImages } from "./images.mjs";
 import * as processConstants from "./process-constants.mjs";
 
 // The terminal's own look: its canvas, the hidden keyboard, the boot log and
-// the status line. A host module brings the look of what it adds; the page, the
-// boot log's font (the site's is Iosevka, dist/IosevkaTerm-SemiBold.woff2).
+// the status line, which lie in boot()'s element and style nothing else of the
+// page. A host module brings the look of what it adds; the page, the boot log's
+// font (the site's is Iosevka, dist/IosevkaTerm-SemiBold.woff2).
 const style = `
-  .dolly-terminal { position: relative; overflow: hidden; outline: none; caret-color: transparent; }
-  #display { display: block; width: 100%; height: 100%; cursor: text; touch-action: none; }
-  #display[hidden] { display: none; }
-  #keyboard { position: fixed; left: -10000px; top: 0; width: 1px; height: 1px; opacity: 0; caret-color: transparent; }
-  #bootstrap-log { position: absolute; inset: 0; z-index: 1; margin: 0; padding: 1rem 1.15rem; overflow: auto;
+  .dolly-terminal { position: relative; overflow: hidden; outline: none; caret-color: transparent;
+    display: flex; flex-direction: column; }
+  .dolly-terminal #display { display: block; width: 100%; flex: 1 1 0; min-height: 0; cursor: text; touch-action: none; }
+  .dolly-terminal #display[hidden] { display: none; }
+  .dolly-terminal #keyboard { position: fixed; left: -10000px; top: 0; width: 1px; height: 1px; opacity: 0; caret-color: transparent; }
+  .dolly-terminal #bootstrap-log { position: absolute; inset: 0; z-index: 1; margin: 0; padding: 1rem 1.15rem; overflow: auto;
     white-space: pre-wrap; color: #e8e3d7; background: #262626; font: 600 20px/1.35 "Dolly IosevkaTerm SemiBold", monospace;
     scrollbar-width: thin; scrollbar-color: #f2d45c #262626; }
-  #bootstrap-log[hidden] { display: none; }
-  #session-status { position: fixed; right: 1rem; top: 1rem; z-index: 5; max-width: calc(100vw - 2rem);
+  .dolly-terminal #bootstrap-log[hidden] { display: none; }
+  .dolly-terminal #session-status { position: absolute; right: 1rem; top: 1rem; z-index: 5; max-width: calc(100% - 2rem);
     padding: 0.5rem 0.75rem; color: #e8e3d7; background: #262626; border: 1px solid #77736c; font-size: 14px; }
-  #session-status[hidden] { display: none; }
+  .dolly-terminal #session-status[hidden] { display: none; }
   html[data-indicators="hidden"] .page-indicator { display: none; }
-  @media (max-width: 640px) { #bootstrap-log { padding: 0.65rem 0.75rem; } }
+  @media (max-width: 640px) { .dolly-terminal #bootstrap-log { padding: 0.65rem 0.75rem; } }
 `;
 
 function element(tag, properties, attributes = {}) {
@@ -39,13 +41,18 @@ function element(tag, properties, attributes = {}) {
 // written over the restored image before its ENTRY starts. `site`, given, is the
 // root of the routes a module may link to (session/, sessions/, docs/). It
 // resolves to the page's API (window.__dolly on the site) once the image's ENTRY runs.
-export function boot(mount, { images, image, modules, site, http = {}, files = {} } = {}) {
-  return run(mount, { images, modules, site, http }, async () => {
-    const definition = DOLLY_IMAGES.find(candidate => candidate.image === image);
+export function boot(mount, { images, image, modules, site, http = {}, files = {}, session } = {}) {
+  return run(mount, { images, modules, site, http }, async registry => {
+    // A saved session (snapshot@0) restores its image as it was saved: files are for a fresh start.
+    const selected = session === undefined ? null
+      : await registry.selectBoot({ image, mode: "snapshot", loadSession: true, session });
+    if (session !== undefined && !selected) throw new Error("opening a saved session needs snapshot@0 among the page's modules");
+    const definition = imageDefinition(selected?.image ?? image);
     if (!definition || typeof files !== "object" || files === null) throw new Error("invalid Dolly boot options");
     if (definition.entry === null) throw new Error(`${image} has no ENTRY; it only builds`);
-    return { image, label: "PRECOMPILED SYSTEM", required: definition.hostRequirements ?? [],
-      start: () => ({ message: { files }, transfers: [] }) };
+    return { image: definition.image, label: selected?.label ?? "PRECOMPILED SYSTEM", configuration: selected?.configuration,
+      required: [...new Set([...definition.hostRequirements, ...selected ? [selected.module] : []])],
+      start: () => ({ message: { files: selected ? {} : files }, transfers: [] }) };
   });
 }
 
@@ -61,8 +68,8 @@ export function boot(mount, { images, image, modules, site, http = {}, files = {
 //   configure message ({ message, transfers }), or null once an image without
 //   ENTRY is built;
 // - message(message): each message of the Worker;
-// - running(ready, host): the context host modules' entryStarted is given
-//   beside `image`, and members of the page's handle.
+// - running(host): the context host modules' entryStarted is given beside
+//   `image`, and members of the page's handle.
 export async function run(mount, { images, modules, site, http }, route) {
   if (!document.querySelector("style[data-dolly]")) {
     document.head.append(element("style", { textContent: style }, { "data-dolly": "" }));
@@ -75,9 +82,8 @@ export async function run(mount, { images, modules, site, http }, route) {
   mount.classList.add("dolly-terminal");
   mount.replaceChildren(canvas, keyboard, bootstrapLog, status);
   const bootstrapOutput = buildLog(bootstrapLog);
-  bootstrapOutput.clear();
   const appendBootstrap = text => bootstrapOutput.append(text);
-  pageChords(keyboard);
+  pageChords(mount, keyboard);
   const bootstrapDecoder = new TextDecoder();
 
   let runtimeWorker;
@@ -111,13 +117,15 @@ export async function run(mount, { images, modules, site, http }, route) {
     const how = failure ? `failed: ${failure}` : signal ? `was ended by ${signalName ?? `signal ${signal}`}`
       : `exited with status ${code}`;
     const notice = mount.appendChild(element("div", { id: "image-ended" }, { role: "alert" }));
-    notice.style.cssText = "position:fixed;left:0;right:0;bottom:0;z-index:9;padding:0.6rem 1rem;" +
+    notice.style.cssText = "position:absolute;left:0;right:0;bottom:0;z-index:9;padding:0.6rem 1rem;" +
       "color:#e8e3d7;background:#262626;border-top:1px solid #f2d45c;font-size:16px";
     const links = [{ text: "Reload to start again", href: location.href }, ...offers].map(({ text, href }) =>
       Object.assign(document.createElement("a"), { textContent: text, href, style: "color:#f2d45c;margin-left:1.5ch" }));
     notice.append(`This image has ended: its program ${how}.`, ...links);
-    mount.style.height = `calc(100% - ${notice.offsetHeight}px)`;
-    Object.assign(canvas.style, { objectFit: "contain", objectPosition: "left top" });
+    // The notice takes the element's bottom strip; the last frame and the log keep the rest.
+    Object.assign(canvas.style, { flex: "none", height: `calc(100% - ${notice.offsetHeight}px)`, objectFit: "contain",
+      objectPosition: "left top" });
+    bootstrapLog.style.bottom = `${notice.offsetHeight}px`;
     links[0].focus();
     document.documentElement.dataset.dollyStatus = "exited";
   }
@@ -139,20 +147,13 @@ export async function run(mount, { images, modules, site, http }, route) {
     const registry = await hostRegistry(modules);
     const selected = await route(registry);
     const { image } = selected;
-    const bootstrapSources = [
-      ...DOLLY_IMAGES.map((definition) => ({
-        path: `/${definition.dollyfile}`,
-        byteLength: definition.byteLength,
-      })),
-      ...DOLLY_STATIC_SOURCES,
-    ];
     appendBootstrap(`DOLLY / ${image.toUpperCase()} / ${selected.label}\n\n`);
     host = await registry.createHost("browser", selected.enabled ?? selected.required, {
       send: (message, transfers = []) => runtimeWorker.postMessage(message, transfers),
       resources: { mount, canvas, keyboard, applicationBase: imageBase, site: site && new URL(site), showStatus, fatal,
         indicators: { hold: holdIndicators, show: showIndicators } },
       configuration: { ...selected.configuration, http: { ...selected.configuration?.http, embedding: http,
-        sources: bootstrapSources, inherited: selected.inherited } },
+        sources: bootstrapSources(), inherited: selected.inherited } },
     });
     host.require(selected.required);
     const started = selected.start ? await selected.start(host, appendBootstrap) : { message: {}, transfers: [] };
@@ -189,7 +190,6 @@ export async function run(mount, { images, modules, site, http }, route) {
     runtimeWorker.postMessage({
       type: "configure",
       image,
-      mode: "snapshot",
       images: imageBase.href,
       modules: registry.urls,
       hostModules: host.enabled,
@@ -213,11 +213,8 @@ export async function run(mount, { images, modules, site, http }, route) {
     }).finally(() => { rejectReady = null; });
     appendBootstrap(bootstrapDecoder.decode());
     runtimeReady = true;
-    if (ready.routeImage !== image || (image !== "custom" && ready.image !== image)) {
-      throw new Error("runtime image mismatch");
-    }
     document.documentElement.dataset.image = ready.image;
-    const { context, page } = await selected.running?.(ready, host) ?? {};
+    const { context, page } = await selected.running?.(host) ?? {};
     await host.entryStarted({ image, ...context });
     runtimeWorker.postMessage({ type: "entry-ready-ack" });
     // A module that shows the canvas replaces the bootstrap log.

package/src/build-log.mjs

@@ -2,10 +2,21 @@
 export function buildLog(element) {
   const maximum = 1024 * 1024;
   let length = 0, escape = "", carriageReturn = false;
+  // The log follows its end while the reader is there, as their last scroll left
+  // it, once a frame: an append reads no layout, which in a log of a megabyte
+  // took Chrome 12 ms each.
+  let following = true, scrolling = false;
+  element.addEventListener("scroll", () => {
+    following = element.scrollHeight - element.scrollTop - element.clientHeight < 24;
+  });
+  function follow() {
+    if (!following || scrolling) return;
+    scrolling = true;
+    requestAnimationFrame(() => { scrolling = false; element.scrollTop = element.scrollHeight; });
+  }
   return {
     clear() { element.replaceChildren(); length = 0; escape = ""; carriageReturn = false; },
     append(text) {
-      const follow = element.scrollHeight - element.scrollTop - element.clientHeight < 24;
       text = escape + String(text);
       escape = /\x1b(?:\[[0-9;:]{0,128})?$/.exec(text)?.[0] ?? "";
       if (escape) text = text.slice(0, -escape.length);
@@ -24,7 +35,7 @@ export function buildLog(element) {
         if (first.length <= excess) { length -= first.length; first.remove(); }
         else { first.deleteData(0, excess); length -= excess; }
       }
-      if (follow) element.scrollTop = element.scrollHeight;
+      follow();
     },
   };
 }

package/src/build-worker.mjs

@@ -0,0 +1,182 @@
+// The site's runtime Worker (worker-image.mjs): it builds an image from its
+// recipe, from the compiler seed or the base image the page hands it, caches
+// it and runs it, telling the page its identity, or, for the image builder,
+// hands the page the cached artifact (buildOnly); or it restores a custom
+// image the site built before. Images cross to and from Wasm memory a piece
+// at a time: the page holds them as Blobs, never in a JS heap.
+import { DOLLY_IMAGE_BUILD_ID } from "../dist/dolly-image-build-id.mjs";
+import { imageBase, imageDefinition } from "./images.mjs";
+import { scanSnapshotRecords, MAX_SNAPSHOT_BYTES as snapshotSizeLimit } from "./snapshot-records.mjs";
+import { describeImageArtifact, saveImageArtifact, sha256 } from "./image-artifact.mjs";
+import { imageInputs } from "./image-inputs.mjs";
+import { inspectDollyfile, MAX_DOLLYFILE_BYTES, recipeRows } from "./dollyfile-view.mjs";
+import { checkedCustomArtifact } from "./custom-image.mjs";
+import { siteReference, decodeStaticAsset } from "./static-asset.mjs";
+import { checkedMemoryRange, kernelArtifact, runImage } from "./worker-image.mjs";
+
+const encoder = new TextEncoder();
+const PIECE = 8 * 1024 * 1024;
+
+// The kernel's capture of the image, TOTAL bytes, as unshared copies of the
+// pieces it reads into the staging window of PIECE bytes.
+function* capturedPieces(kernel, memory, total) {
+  const window = checkedMemoryRange(memory, kernel.dolly_snapshot_restore_address(BigInt(PIECE)), PIECE);
+  let produced = 0;
+  for (;;) {
+    const size = Number(kernel.dolly_snapshot_capture_read());
+    if (size === 0) break;
+    if (size > window.size || size > total - produced) throw new Error("Wasm published an invalid system snapshot piece");
+    produced += size;
+    yield new Uint8Array(memory.buffer, window.address, size).slice();
+  }
+  if (produced !== total) throw new Error("Dolly system snapshot capture failed");
+}
+
+// A catalog recipe as this site publishes it, checked against its pin.
+async function catalogRecipe(definition) {
+  const response = await fetch(new URL(definition.dollyfile, imageBase), { credentials: "same-origin", redirect: "error" });
+  const bytes = response.ok ? await response.arrayBuffer() : new ArrayBuffer(0);
+  if (await sha256(bytes) !== definition.sha256) throw new Error(`${definition.dollyfile} does not match its pin`);
+  return inspectDollyfile(new TextDecoder().decode(bytes), definition.dollyfile);
+}
+
+await runImage(async (config, host) => {
+  const { image, mode, customSource } = config;
+  const definition = imageDefinition(image);
+  const custom = image === "custom";
+  if (!(definition || custom) || !["snapshot", "rebuild"].includes(mode) || (mode === "snapshot" && !custom)) {
+    throw new Error("invalid Dolly image selection");
+  }
+  if ((custom || customSource !== undefined) && (typeof customSource !== "string" ||
+      encoder.encode(customSource).byteLength > MAX_DOLLYFILE_BYTES || customSource.includes("\0"))) {
+    throw new Error("invalid uploaded Dollyfile");
+  }
+  const recipe = custom ? inspectDollyfile(customSource) : definition;
+  const locator = custom ? "FILE:/etc/dolly/upload.Dollyfile" : siteReference(definition.dollyfile);
+  const prepareRecipe = (files, rows) => {
+    files.write("/etc/dolly/recipe.locator", locator);
+    if (custom) files.write("/etc/dolly/upload.Dollyfile", customSource);
+    if (rows !== undefined) files.write("/etc/dolly/recipe.rows", rows);
+  };
+  // Copies a whole snapshot, a Blob, into the kernel's checked staging range a
+  // piece at a time; its size.
+  const stageSnapshot = async (kernel, memory, blob) => {
+    const range = checkedMemoryRange(memory, kernel.dolly_snapshot_restore_address(BigInt(blob.size)), blob.size);
+    for (let offset = 0; offset < range.size; offset += PIECE) {
+      const piece = new Uint8Array(await blob.slice(offset, Math.min(offset + PIECE, range.size)).arrayBuffer());
+      new Uint8Array(memory.buffer, range.address + offset, piece.length).set(piece);
+    }
+    return range.size;
+  };
+  if (mode === "snapshot") {
+    const artifact = await checkedCustomArtifact(customSource, config.customArtifact);
+    config.customArtifact = undefined;
+    host.require(artifact.hostRequirements);
+    host.admit(artifact.hostRequirements);
+    return {
+      name: image,
+      prepare({ files }) {
+        prepareRecipe(files);
+        files.write("/etc/dolly/image.manifest", `${artifact.manifest.join("\n")}\n`);
+      },
+      async restore({ kernel, memory, stage }) {
+        stage("loading precompiled userspace snapshot...");
+        const size = await stageSnapshot(kernel, memory, artifact.bytes);
+        artifact.bytes = undefined;
+        return { status: kernel.dolly_bootstrap_snapshot(BigInt(size)) };
+      },
+    };
+  }
+
+  const declared = recipe.hostRequirements;
+  const recipeSha256 = custom ? await sha256(encoder.encode(customSource)) : definition.sha256;
+  // /bin/dollyfile executes the rows this page's parser compiles.
+  const rows = recipeRows(custom ? recipe : await catalogRecipe(definition), recipeSha256);
+  const baseReference = custom ? recipe.from : definition.artifacts.find(reference => reference.operation === "from");
+  const artifacts = new Map();
+  if (config.artifacts !== undefined && (!Array.isArray(config.artifacts) || config.artifacts.length > 256)) {
+    throw new Error("invalid build artifacts");
+  }
+  for (const candidate of config.artifacts ?? []) {
+    if (candidate?.buildId !== DOLLY_IMAGE_BUILD_ID || !/^[0-9a-f]{64}$/.test(candidate.recipeSha256) ||
+        !(candidate.bytes instanceof Blob)) throw new Error("build artifact integrity mismatch");
+    const artifact = await describeImageArtifact(candidate.bytes, candidate.recipeSha256);
+    if (artifact.sha256 !== candidate.sha256) throw new Error("build artifact integrity mismatch");
+    artifacts.set(candidate.recipeSha256, artifact);
+  }
+  config.artifacts = undefined;
+  // A build runs the engine and its tools with the build host's modules, and
+  // the programs of the images it reads with their modules: one the build host
+  // does not enable answers ENOSYS.
+  host.admit([...declared, ...host.enabled, ...[...artifacts.values()].flatMap(artifact => artifact.hostRequirements)]);
+  const inputs = imageInputs([...artifacts.values()]);
+  const base = baseReference ? artifacts.get(baseReference.sha256) : null;
+  if (baseReference && !base) throw new Error("base image artifact was not provided");
+  let seed = null, built = false;
+  return {
+    name: image,
+    async prepare({ files, stage }) {
+      // A root build starts from the compiler seed, a snapshot like any image.
+      if (!base) {
+        stage("loading root compiler seed...");
+        // Static hosts may serve the seed as verified parts.
+        const url = kernelArtifact("dolly.data");
+        seed = await (await decodeStaticAsset(await fetch(url), url, {}, snapshotSizeLimit)).blob();
+      }
+      prepareRecipe(files, rows);
+      // The engine reads each input from its Blob as it restores it: the kernel never holds an input's snapshot.
+      host.kernel.setBuildInputs([...artifacts.values()].map(artifact => artifact.bytes));
+      [...artifacts.values()].forEach((artifact, input) =>
+        files.input(`/etc/dolly/artifacts/${artifact.recipeSha256}.snapshot`, input, artifact.bytes.size));
+      // The kernel restores a snapshot against the list of its paths.
+      const manifest = base?.manifest ?? [...(await scanSnapshotRecords(seed.stream(), () => false)).records.keys()];
+      files.write("/etc/dolly/image.manifest", `${manifest.join("\n")}\n`);
+    },
+    async restore({ kernel, memory, files, stage }) {
+      stage("building userspace from the Dollyfile...");
+      let status;
+      if (base) {
+        stage(`loading builder from ${baseReference.location}...`);
+        status = kernel.dolly_process_bootstrap_resume_prepare(BigInt(await stageSnapshot(kernel, memory, base.bytes)), 1);
+      } else {
+        status = kernel.dolly_process_bootstrap_prepare(BigInt(await stageSnapshot(kernel, memory, seed)));
+        seed = null;
+      }
+      let supervisor;
+      if (status === 0) {
+        supervisor = await host.kernel.supervisor(kernel);
+        status = (await supervisor.spawn(base ? ["/bin/dollyfile", locator] : ["/usr/libexec/dolly/process-bin/bootstrap"])).status;
+      }
+      for (const artifact of artifacts.values()) files.remove(`/etc/dolly/artifacts/${artifact.recipeSha256}.snapshot`);
+      artifacts.clear();
+      host.kernel.setBuildInputs([]);
+      if (status !== 0) return { status };
+      // Kernel memory never shrinks: its size now is the build's high-water mark.
+      stage(`capturing userspace image (kernel memory ${Math.round(memory.buffer.byteLength / 2 ** 20)} MiB)...`);
+      const total = Number(kernel.dolly_snapshot_capture_begin());
+      if (total === 0 || total > snapshotSizeLimit) throw new Error("Dolly system snapshot capture failed");
+      const artifact = await describeImageArtifact(capturedPieces(kernel, memory, total), recipeSha256, inputs);
+      stage("caching completed image...");
+      const saved = await saveImageArtifact(artifact, custom ? `custom:${recipe.image}` : `/${definition.dollyfile}`);
+      stage(saved ? "saved completed image artifact" : "image built; local cache unavailable");
+      if (config.buildOnly) {
+        self.postMessage({ type: "image-built", artifact });
+        return { status };
+      }
+      // The image runs here with its own modules. The page keeps its identity,
+      // which a session saved on it names, not its bytes.
+      host.require(artifact.hostRequirements);
+      host.admit(artifact.hostRequirements);
+      const { buildId, sha256: digest, byteLength } = artifact;
+      self.postMessage({ type: "image-built", artifact: { buildId, recipeSha256, sha256: digest, byteLength, inputs: artifact.inputs } });
+      built = true;
+      return { status, supervisor };
+    },
+    finish({ kernel, stage }) {
+      if (!built) return;
+      stage("finishing image bootstrap...");
+      const status = kernel.dolly_bootstrap_finish();
+      if (status !== 0) throw new Error(`Dolly bootstrap failed with status ${status}`);
+    },
+  };
+});

package/src/custom-image.mjs

@@ -0,0 +1,59 @@
+import { DOLLY_IMAGE_BUILD_ID } from "../dist/dolly-image-build-id.mjs";
+import { describeImageArtifact, loadImageArtifact, loadImageArtifactDescriptor, sha256 } from "./image-artifact.mjs";
+import { inspectDollyfile } from "./dollyfile-view.mjs";
+
+export async function loadCustomImage(source, descriptor) {
+  inspectDollyfile(source);
+  if (descriptor?.buildId !== DOLLY_IMAGE_BUILD_ID ||
+      descriptor.recipeSha256 !== await sha256(new TextEncoder().encode(source))) {
+    throw new Error("Completed custom image does not match this Dollyfile/runtime. Rebuild it.");
+  }
+  const artifact = await loadImageArtifact(descriptor);
+  if (!artifact) throw new Error("Completed custom image is missing or changed in the browser cache. Rebuild the exact image, or open /sessions to recover saved files. Saved sessions have not been changed.");
+  return artifact;
+}
+
+// Whether this browser's image cache still records the completed custom image
+// ARTIFACT (its descriptor): a session saved on it can then be restored, which
+// checks the image's bytes.
+export async function customImageCached(artifact) {
+  const cached = await loadImageArtifactDescriptor(artifact.recipeSha256, artifact.inputs);
+  return cached?.sha256 === artifact.sha256 && cached.byteLength === artifact.byteLength;
+}
+
+export async function checkedCustomArtifact(source, candidate) {
+  inspectDollyfile(source);
+  if (candidate?.buildId !== DOLLY_IMAGE_BUILD_ID || !(candidate.bytes instanceof Blob) ||
+      candidate.recipeSha256 !== await sha256(new TextEncoder().encode(source))) {
+    throw new Error("Invalid completed custom image");
+  }
+  const artifact = await describeImageArtifact(candidate.bytes, candidate.recipeSha256, candidate.inputs);
+  if (candidate.sha256 !== artifact.sha256) throw new Error("Completed custom image integrity mismatch");
+  return artifact;
+}
+
+// Call only from the user's Open image gesture after a build completes.
+// Only a fixed app route is navigable; the recipe never supplies a host URL.
+// With the Dollyfile, the tab inherits the completed artifact and what the
+// host modules of the building page hand down (their restrictions).
+export function openCustomImage({ source, ...inherited }) {
+  const target = window.open("about:blank", "_blank");
+  if (!target) throw new Error("Popup blocked. Choose Open image to retry.");
+  try {
+    target.sessionStorage.setItem("dolly-custom-source", source);
+    target.sessionStorage.setItem("dolly-custom-inherited", JSON.stringify(inherited));
+    target.opener = null;
+    target.location.replace(new URL("../custom/run/", import.meta.url));
+  } catch (error) {
+    target.close();
+    throw error;
+  }
+}
+
+// The custom image this tab was opened with: its Dollyfile and, after a build,
+// what it inherits; undefined when the tab has none.
+export function storedCustomImage() {
+  const source = sessionStorage.getItem("dolly-custom-source");
+  if (!source) return undefined;
+  return { source, ...JSON.parse(sessionStorage.getItem("dolly-custom-inherited") ?? "{}") };
+}

package/src/dollyfile-graph.mjs

@@ -0,0 +1,127 @@
+import { inspectDollyfile, recipeFileName, imageFileName } from "./dollyfile-view.mjs";
+import { sha256 } from "./static-asset.mjs";
+
+const key = object => `${object.type}:${object.name}`;
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+// The recipe graph of one image, as /bin/dollyfile reads it: the root and the
+// FROM/INSTALL/USE/COPY images it imports, each with its own imports. `read(url)`
+// returns a recipe's bytes; this checks every pin. `artifacts` are the images
+// a build of the root reads: its own rows and, before each INSTALL or USE, the rows
+// that package's recipe installs, which the package names and does not hold. It is an inspection graph,
+// not a dependency solver: runtime assertions may resolve against files and
+// environment that recipes do not declare. Pass the same `recipes` cache to
+// reuse parsed recipes across graphs.
+export async function loadRecipeGraph(read, rootLocation, recipes = new Map()) {
+  const records = [], edges = [], artifacts = [];
+  const active = new Set(), images = new Map(), imageNames = new Map();
+
+  function parse(location) {
+    if (!recipes.has(location)) {
+      recipes.set(location, (async () => {
+        const bytes = await read(location);
+        return { ...inspectDollyfile(decoder.decode(bytes), location), sha256: await sha256(bytes) };
+      })());
+    }
+    return recipes.get(location);
+  }
+
+  async function load(location, expected, root) {
+    if (active.has(location)) throw new Error(`${location}: recipe cycle`);
+    const parsed = await parse(location);
+    if (expected && parsed.sha256 !== expected) throw new Error(`${location}: stale recipe pin`);
+    // An uploaded root is labeled "Dollyfile"; every site path names its recipe's file.
+    const file = recipeFileName(location);
+    if (file !== "" && imageFileName(file) !== parsed.name) {
+      throw new Error(`${location}: ${parsed.role.toUpperCase()} ${parsed.name} must match its file name`);
+    }
+    if ((imageNames.get(parsed.name) ?? location) !== location) {
+      throw new Error(`${location}: image ${parsed.name} is already ${imageNames.get(parsed.name)}`);
+    }
+    imageNames.set(parsed.name, location);
+    if (!root && images.has(location)) return images.get(location);
+    active.add(location);
+    const record = { ...parsed, location, dependencies: [], imports: new Map(), artifactTargets: [], installs: [], installTargets: [] };
+    records.push(record);
+    const visible = new Map();
+    const published = new Map();
+    const operations = [
+      ...record.artifacts,
+      ...record.requirements.map(value => ({ ...value, operation: "requirement" })),
+      ...record.exports.map(value => ({ ...value, operation: "export" })),
+    ].sort((a, b) => a.line - b.line);
+    for (const operation of operations) {
+      if (["from", "install", "use", "copy"].includes(operation.operation)) {
+        const target = await load(operation.location, operation.sha256, false);
+        const installs = ["install", "use"].includes(operation.operation);
+        if (operation.operation === "from" ? target.role === "package" : installs && target.role !== "package") {
+          throw new Error(`${location}:${operation.line}: ${target.name} is a ${target.role}: ` +
+            "FROM takes an application or toolchain, INSTALL and USE a package");
+        }
+        // Host requirements are never inherited: a package's must be declared here.
+        if (operation.operation === "install") {
+          const missing = target.hostRequirements.filter(name => !record.hostRequirements.includes(name));
+          if (missing.length) {
+            throw new Error(`${location}:${operation.line}: ${target.name} needs REQUIRES HOST ${missing.join(", ")}`);
+          }
+        }
+        record.artifactTargets.push({ reference: operation, target });
+        if (root && installs) {
+          for (const needed of target.installs) {
+            if (!artifacts.some(held => held.sha256 === needed.sha256)) artifacts.push({ ...needed, line: operation.line });
+          }
+        }
+        // What a package uses is the build's alone: it is not among what arrives with it.
+        if (operation.operation === "install") {
+          const row = { operation: "install", location: operation.location, sha256: operation.sha256, line: operation.line, image: target.image };
+          for (const needed of [...target.installs, row]) {
+            if (!record.installs.some(held => held.sha256 === needed.sha256)) record.installs.push({ ...needed, line: operation.line });
+          }
+          for (const needed of [...target.installTargets, target]) {
+            if (!record.installTargets.includes(needed)) record.installTargets.push(needed);
+          }
+        }
+        if (root) artifacts.push({ ...operation, image: target.image });
+        // A package keeps nothing of its base nor of what it installs; COPY takes files only.
+        const imports = operation.operation !== "copy" && record.role !== "package";
+        const imported = installs ? [...target.installTargets, target]
+          : operation.operation === "from" ? [target] : [];
+        for (const source of imported) {
+          for (const [name, provider] of source.scopeExporters) {
+            visible.set(name, provider);
+            if (imports) published.set(name, provider);
+          }
+        }
+      } else if (operation.operation === "export") {
+        if (operation.details.length !== 0 || !visible.has(key(operation))) {
+          visible.set(key(operation), { module: record, exported: operation });
+        }
+      } else if (operation.operation === "requirement") {
+        const requirement = record.requirements.find(item => item.line === operation.line);
+        const provider = visible.get(key(operation));
+        if (provider) {
+          const edge = { consumer: record, requirement, provider: provider.module, exported: provider.exported };
+          edges.push(edge);
+          record.dependencies.push(edge);
+          record.imports.set(key(operation), provider);
+        }
+      }
+    }
+    // A recipe's own exports describe its completed state and win over imported
+    // ones. Bare TOOL and ENV names resolve against the last provider seen: a
+    // package, an inherited base, or runtime state.
+    for (const exported of record.exports) {
+      const provider = visible.get(key(exported));
+      const resolved = (exported.details.length === 0 || exported.type === "ENV") && provider && provider.module !== record
+        ? { ...exported, details: provider.exported.details } : exported;
+      published.set(key(exported), { module: record, exported: resolved });
+    }
+    record.scopeExporters = published;
+    if (!root) images.set(location, record);
+    active.delete(location);
+    return record;
+  }
+
+  const root = await load(rootLocation, null, true);
+  return { root, records, edges, exporters: root.scopeExporters, artifacts };
+}