sci2-ts 0.0.0-stage → 0.2.1

package/apps/viewer/src/editor.ts

@@ -0,0 +1,412 @@
+import { indentWithTab } from "@codemirror/commands";
+import { yaml as yamlLanguage } from "@codemirror/lang-yaml";
+import { lintGutter, setDiagnostics, type Diagnostic } from "@codemirror/lint";
+import { EditorState, type Extension } from "@codemirror/state";
+import { oneDark } from "@codemirror/theme-one-dark";
+import { EditorView, keymap } from "@codemirror/view";
+import { ResourceManager, gameGlobal, drawnItems, graphics, heroInPlay, replaceResources, requestRoom, roomPlane, type ResourceType, type VmSnapshot } from "../../../packages/sci/src/index.ts";
+import { basicSetup } from "codemirror";
+import { parse as parseYaml } from "yaml";
+import { EditLayer, type EditMode } from "./editor-handles.ts";
+import { sciAssembly, sciMessages, sciScript, yarn } from "./editor-languages.ts";
+import { httpFiles } from "./files.ts";
+import { OVERLAY_COLORS, createOverlay, drawRoomOverlay } from "./overlay.ts";
+import { gameProfile } from "./game-profile.ts";
+import { GameSession } from "./session.ts";
+
+/**
+ * The live room editor: a room's .room.yaml and .yarn on the left, the game on the right.
+ * Saving (⌘S, or a pause in typing with "live" on) writes the files into the mod and builds
+ * it on the dev server (tools/editor-server.ts); the built resources are swapped into the
+ * running game, which goes back to a snapshot taken just before entering the room and
+ * walks in again. The snapshot comes from a quick new hero (the game's profile in games/), so it
+ * never holds the room being edited. Outlines show what the room is made of, by name.
+ */
+
+interface BuildResult {
+  ok: boolean;
+  resources?: { type: ResourceType; number: number; data: string }[];
+  generated?: Record<string, string>;
+  flags?: string;
+  reload?: boolean;
+  ms?: number;
+  error?: { message: string; file?: string; line?: number };
+}
+
+const $ = <T extends HTMLElement>(id: string) => document.getElementById(id) as T;
+const params = new URLSearchParams(location.search);
+const statusEl = $("status");
+const status = (text: string, kind: "" | "ok" | "error" = "") => {
+  statusEl.textContent = text;
+  statusEl.className = kind;
+};
+
+// --- Which mod and room ---------------------------------------------------------------
+
+// A mod of Sierra's game, or the game of ours the dev server is serving (its rooms/).
+const mods = (await (await fetch("/__editor/mods")).json()) as { name: string; kind: "mod" | "game"; rooms: number[] }[];
+const editable = mods.filter((m) => m.rooms.length);
+if (!editable.length) {
+  status(mods[0]?.kind === "game" ? `${mods[0].name} has no rooms/<n>.room.yaml yet.` : "No mod has a <n>.room.yaml yet (see mods/README.md).", "error");
+  throw new Error("nothing to edit");
+}
+const mod = editable.find((m) => m.name === params.get("mod")) ?? editable[0]!;
+const room = mod.rooms.includes(Number(params.get("room"))) ? Number(params.get("room")) : mod.rooms[0]!;
+const modSelect = $<HTMLSelectElement>("mod"), roomSelect = $<HTMLSelectElement>("room");
+modSelect.append(...editable.map((m) => new Option(m.name, m.name, false, m === mod)));
+roomSelect.append(...mod.rooms.map((r) => new Option(String(r), String(r), false, r === room)));
+const go = (m: string, r?: number) => {
+  const q = new URLSearchParams({ mod: m, ...(r !== undefined ? { room: String(r) } : {}) });
+  location.search = q.toString();
+};
+modSelect.onchange = () => go(modSelect.value);
+roomSelect.onchange = () => go(mod.name, Number(roomSelect.value));
+document.title = `${mod.name} ${room} · Room Editor`;
+
+// --- Files, tabs and the code editor ----------------------------------------------------
+
+const files = (await (await fetch(`/__editor/files?mod=${mod.name}`)).json()) as Record<string, string>;
+const yamlName = `${room}.room.yaml`, yarnName = `${room}.yarn`;
+const scaName = `${room}.sca (compiled)`, msgName = `${room}.msg (compiled)`;
+// A room written as a script (a game of ours): its .sc and message file, not YAML.
+const scriptName = `${room}.sc`, messagesName = `${room}.msg`;
+const scriptMode = files[yamlName] === undefined && files[scriptName] !== undefined;
+const editableNames = scriptMode ? [scriptName, ...(files[messagesName] !== undefined ? [messagesName] : [])] : [yamlName, yarnName];
+const tabNames = scriptMode ? [...editableNames, scaName] : [...editableNames, "flags.yaml", scaName, msgName];
+/** What was last sent to the server, per editable file. */
+const saved = new Map(editableNames.map((n) => [n, files[n] ?? ""]));
+
+const languageOf = (name: string): Extension =>
+  name.endsWith(".yaml") ? yamlLanguage() : name.endsWith(".yarn") ? yarn : name.endsWith(".sc") ? sciScript
+    : name === scaName ? sciAssembly : name === msgName || name === messagesName ? sciMessages : [];
+
+const theme = EditorView.theme({
+  "&": { height: "100%" },
+  ".cm-content": { fontFamily: "inherit" },
+  ".cm-gutters": { fontFamily: "inherit" },
+});
+
+function makeState(name: string, text: string): EditorState {
+  const isEditable = editableNames.includes(name);
+  return EditorState.create({
+    doc: text,
+    extensions: [
+      basicSetup,
+      oneDark,
+      theme,
+      languageOf(name),
+      lintGutter(),
+      keymap.of([indentWithTab, { key: "Mod-s", run: () => (void build(), true) }]),
+      EditorState.readOnly.of(!isEditable),
+      EditorView.editable.of(isEditable),
+      EditorView.updateListener.of((u) => {
+        if (u.docChanged && isEditable) {
+          renderTabs();
+          scheduleBuild();
+        }
+      }),
+    ],
+  });
+}
+
+const states = new Map<string, EditorState>(tabNames.map((n) => [
+  n,
+  makeState(n, n === "flags.yaml" ? files[n] ?? "# No variables yet: <<set $name to true>> in Yarn adds them here.\n" : editableNames.includes(n) ? files[n] ?? "" : "Builds on save."),
+]));
+let current = editableNames[0]!;
+const view = new EditorView({ parent: $("code"), state: states.get(current)! });
+let error: BuildResult["error"];
+
+const textOf = (name: string) => (name === current ? view.state : states.get(name)!).doc.toString();
+
+const tabs = $("tabs"), problems = $("problems");
+function renderTabs(): void {
+  tabs.replaceChildren(
+    ...tabNames.map((name) => {
+      const b = document.createElement("button");
+      b.type = "button";
+      b.textContent = name;
+      b.classList.toggle("active", name === current);
+      b.classList.toggle("dirty", editableNames.includes(name) && textOf(name) !== saved.get(name));
+      b.classList.toggle("has-error", error?.file === name);
+      b.onclick = () => show(name);
+      return b;
+    }),
+  );
+}
+
+/** The error as a diagnostic on its line, in the tab it belongs to. */
+function diagnostics(name: string, state: EditorState): Diagnostic[] {
+  if (!error || error.file !== name || !error.line || error.line > state.doc.lines) return [];
+  const line = state.doc.line(error.line);
+  return [{ from: line.from, to: Math.max(line.to, line.from), severity: "error", message: error.message.replace(/^[^:]+:\d+:\s*/, "") }];
+}
+
+function show(name: string, line?: number): void {
+  states.set(current, view.state);
+  current = name;
+  view.setState(states.get(name)!);
+  view.dispatch(setDiagnostics(view.state, diagnostics(name, view.state)));
+  if (line && line <= view.state.doc.lines) {
+    const pos = view.state.doc.line(line).from;
+    view.dispatch({ selection: { anchor: pos }, effects: EditorView.scrollIntoView(pos, { y: "center" }) });
+    view.focus();
+  }
+  renderTabs();
+}
+
+/**
+ * Replaces an editable file's text with the smallest change (so the cursor, scrolling and
+ * undo behave), shown in its tab: what dragging and drawing on the game do to the YAML.
+ */
+function editText(name: string, text: string): void {
+  if (current !== name) show(name);
+  const old = view.state.doc.toString();
+  if (old === text) return;
+  let from = 0;
+  while (from < old.length && from < text.length && old[from] === text[from]) from++;
+  let oldEnd = old.length, newEnd = text.length;
+  while (oldEnd > from && newEnd > from && old[oldEnd - 1] === text[newEnd - 1]) (oldEnd--, newEnd--);
+  view.dispatch({
+    changes: { from, to: oldEnd, insert: text.slice(from, newEnd) },
+    effects: EditorView.scrollIntoView(from, { y: "nearest", yMargin: 40 }),
+  });
+}
+
+/** Replaces a read-only tab's text (flags, compiled output). */
+function setView(name: string, text: string): void {
+  const state = makeState(name, text);
+  if (name === current) view.setState(state);
+  else states.set(name, state);
+}
+
+window.addEventListener("keydown", (e) => {
+  if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "s") {
+    e.preventDefault();
+    void build();
+  }
+});
+problems.onclick = () => error?.file && editableNames.includes(error.file) && show(error.file, error.line);
+$("save").onclick = () => void build();
+renderTabs();
+
+// --- Building -------------------------------------------------------------------------
+
+const auto = $<HTMLInputElement>("auto");
+let timer: ReturnType<typeof setTimeout> | undefined;
+/** While a drag or brush stroke is in progress, builds wait for it to end. */
+let held = false;
+function scheduleBuild(): void {
+  clearTimeout(timer);
+  if (auto.checked && !held) timer = setTimeout(() => void build(), 700);
+}
+
+let building: Promise<void> | undefined;
+let again = false;
+async function build(): Promise<void> {
+  clearTimeout(timer);
+  if (building) {
+    again = true;
+    return building;
+  }
+  building = (async () => {
+    const sent = new Map(editableNames.map((n) => [n, textOf(n)]));
+    status("Building…");
+    const body = { files: Object.fromEntries([...sent].filter(([name, t]) => t !== "" || files[name] !== undefined)) };
+    let result: BuildResult;
+    try {
+      result = await (await fetch(`/__editor/save?mod=${mod.name}`, { method: "POST", body: JSON.stringify(body) })).json();
+    } catch (e) {
+      result = { ok: false, error: { message: `The dev server didn't answer: ${(e as Error).message}` } };
+    }
+    for (const [name, t] of sent) saved.set(name, t);
+    applyResult(result);
+  })();
+  await building;
+  building = undefined;
+  if (again) {
+    again = false;
+    await build();
+  }
+}
+
+function applyResult(result: BuildResult): void {
+  error = result.ok ? undefined : result.error;
+  problems.hidden = result.ok;
+  problems.textContent = error ? `${error.message}${error.file && editableNames.includes(error.file) ? "\n(click to go there)" : ""}` : "";
+  view.dispatch(setDiagnostics(view.state, diagnostics(current, view.state)));
+  if (result.ok) {
+    if (result.reload) {
+      // The game's selector or class tables changed: the running game can't take that.
+      status("Rebuilt: reloading…");
+      location.reload();
+      return;
+    }
+    if (result.flags !== undefined && tabNames.includes("flags.yaml")) setView("flags.yaml", result.flags);
+    setView(scaName, result.generated?.[`${room}.sca`] ?? "");
+    if (tabNames.includes(msgName)) setView(msgName, result.generated?.[`${room}.msg`] ?? "");
+    readExits();
+    const resources = (result.resources ?? []).map((r) => ({ type: r.type, number: r.number, data: Uint8Array.from(atob(r.data), (c) => c.charCodeAt(0)) }));
+    if (session) {
+      replaceResources(session.vm, resources);
+      restartScene();
+    } else for (const r of resources) rm.override(r, r.data);
+    status(`Built in ${result.ms} ms`, "ok");
+  } else status("Build failed: see below", "error");
+  renderTabs();
+}
+
+/** The room's exits, by name, from the YAML that built (they're outlined in their own colour). */
+let exits = new Set<string>();
+function readExits(): void {
+  try {
+    exits = new Set(Object.keys((parseYaml(saved.get(yamlName) ?? "") as { exits?: object } | null)?.exits ?? {}));
+  } catch {
+    /* keep the last good set */
+  }
+}
+
+// --- The game -------------------------------------------------------------------------
+
+// A mod's resources come from the builds (swapped in memory), not from out/mods; a game's
+// from out/games, with the builds' changes swapped in.
+const rm = await ResourceManager.open(httpFiles, ["", "PATCHES"]);
+let session: GameSession | undefined;
+await build();
+while (error) {
+  // Nothing to run until the mod builds: wait for the next successful save.
+  await new Promise((r) => setTimeout(r, 300));
+}
+session = await GameSession.create({
+  canvas: $<HTMLCanvasElement>("screen"), rm, mods: mod.kind === "mod" ? [mod.name] : [], saveNamespace: `editor:${mod.name}`, muted: true,
+});
+const vm = session.vm;
+
+/**
+ * The game just before entering the room: a hero, outside it (a new one, made by the quick
+ * route, awake in the first cave; or one made by hand if that didn't work out).
+ */
+let base: VmSnapshot | undefined;
+let entering = false;
+let readyAt = 0;
+const quickStart = gameProfile(vm)?.quickStart(vm);
+if (quickStart) {
+  status("Creating a hero…");
+  session.start({
+    fastForward: {
+      ...quickStart,
+      done: () => {
+        entering = true;
+        readyAt = performance.now();
+      },
+    },
+  });
+} else {
+  // No quick route for this game: the player makes a character, then it goes to the room.
+  session.start();
+  entering = true;
+  readyAt = performance.now();
+}
+
+function restartScene(): void {
+  if (!base || !session) return;
+  session.restore(base);
+  entering = true;
+}
+$("restart").onclick = restartScene;
+
+const roomNow = () => gameGlobal(vm, "curRoomNum");
+session.onDraw.push(() => {
+  if (!entering || session!.fastForwarding) return;
+  if (roomNow() === room) {
+    entering = false;
+    if (!error) status(`In room ${room}`, "ok");
+  } else if (heroInPlay(vm)) {
+    base ??= session!.snapshot();
+    requestRoom(vm, room);
+  } else if (performance.now() - readyAt > 4000) {
+    status("No hero yet: finish creating one in the game (Play), then it goes to the room", "error");
+  }
+});
+
+// Outlines: features, exits, sprites, walk areas, by name (on by default).
+const overlay = createOverlay();
+$("screen-box").append(overlay);
+const outlines = $<HTMLInputElement>("outlines");
+$("legend").replaceChildren(
+  ...([["features", OVERLAY_COLORS.feature], ["exits", OVERLAY_COLORS.exit], ["props", OVERLAY_COLORS.sprite], ["hero", OVERLAY_COLORS.hero], ["walkable", OVERLAY_COLORS.polygons[3]!], ["obstacles", OVERLAY_COLORS.polygons[2]!]] as const).map(([name, color]) => {
+    const s = document.createElement("span");
+    s.textContent = name;
+    s.style.setProperty("--swatch", color);
+    return s;
+  }),
+);
+const legend = $("legend");
+const drawOutlines = () => {
+  legend.style.display = outlines.checked ? "" : "none";
+  if (!outlines.checked || roomNow() !== room) overlay.replaceChildren();
+  else {
+    drawRoomOverlay(overlay, vm, { sprites: true, features: true, polygons: true, paths: true, isExit: (n) => exits.has(n) });
+    // A dialog (a plane above the room's and the status bar's) is what matters then.
+    overlay.style.opacity = dialogOpen() ? "0.12" : "1";
+  }
+};
+function dialogOpen(): boolean {
+  const g = graphics(vm);
+  const roomPriority = roomPlane(vm) ? g.prop(roomPlane(vm)!.address, "priority") : 0;
+  return [...g.planes].some((p) => vm.memory.object(p) && g.prop(p, "priority") > roomPriority + 1);
+}
+outlines.onchange = drawOutlines;
+session.onDraw.push(drawOutlines);
+readExits();
+
+// Moving things by dragging them, and painting walk areas: edits to the YAML.
+const roomOffset = (): [number, number] => {
+  const plane = roomPlane(vm);
+  return plane ? [plane.left, plane.top] : [0, 10];
+};
+const editLayer = new EditLayer({
+  yaml: () => textOf(yamlName),
+  setYaml: (text) => editText(yamlName, text),
+  roomOffset,
+  spriteBox: (name) => {
+    const [ox, oy] = roomOffset();
+    const d = drawnItems(vm).find((item) => item.item.name === name);
+    return d && { x: d.x - ox, y: d.y - oy, w: d.w, h: d.h };
+  },
+  previewProp: (name, [x, y]) => {
+    const prop = [...vm.memory.objects.values()].find((o) => o.name === name && !o.isClone);
+    if (!prop) return;
+    vm.setProp(prop, "x", x);
+    vm.setProp(prop, "y", y);
+  },
+  holdBuild: (hold) => {
+    held = hold;
+    if (hold) clearTimeout(timer);
+    else if (auto.checked) void build();
+  },
+});
+$("screen-box").append(editLayer.svg);
+const modeButtons = [...document.querySelectorAll<HTMLButtonElement>("#modes button")];
+const setMode = (mode: EditMode) => {
+  editLayer.setMode(mode);
+  for (const b of modeButtons) b.classList.toggle("active", b.dataset.mode === mode);
+  // The game's own outlines step back while the handles are up.
+  overlay.style.filter = mode === "play" ? "" : "opacity(0.35)";
+};
+for (const b of modeButtons) b.onclick = () => setMode(b.dataset.mode as EditMode);
+// Dragging and drawing change YAML: a room written as a script is edited as text.
+if (scriptMode) for (const b of modeButtons) b.hidden = b.dataset.mode !== "play";
+setMode("play");
+// Handles follow what's drawn (props move, the YAML changes); not mid-drag, which redraws itself.
+session.onDraw.push(() => {
+  if (editLayer.mode === "play") return;
+  if (!held) editLayer.render();
+  editLayer.svg.style.opacity = !held && dialogOpen() ? "0.3" : "1";
+});
+
+const sound = $("sound");
+sound.onclick = () => {
+  session!.setMuted(!session!.muted);
+  sound.textContent = session!.muted ? "Sound off" : "Sound on";
+};

package/apps/viewer/src/explore/classes.d.ts

@@ -0,0 +1,7 @@
+import { type Explorer } from "./context.ts";
+export interface ClassTree {
+    element: HTMLElement;
+    select(species: number | undefined): void;
+}
+/** The class hierarchy as an indented tree, with a filter that keeps matches' ancestors. */
+export declare function createClassTree(ex: Explorer): ClassTree;

package/apps/viewer/src/explore/classes.js

@@ -0,0 +1,63 @@
+import { el } from "./context.js";
+/** The class hierarchy as an indented tree, with a filter that keeps matches' ancestors. */
+export function createClassTree(ex) {
+    const { classes } = ex.index;
+    const children = new Map();
+    for (const c of classes)
+        children.set(c.superclass, [...(children.get(c.superclass) ?? []), c]);
+    for (const list of children.values())
+        list.sort((a, b) => a.name.localeCompare(b.name));
+    const instanceCount = new Map();
+    for (const s of ex.index.scripts)
+        for (const o of s.objects)
+            instanceCount.set(o.superclass, (instanceCount.get(o.superclass) ?? 0) + 1);
+    const links = new Map();
+    const items = new Map();
+    const build = (parent) => {
+        const kids = children.get(parent);
+        if (!kids?.length)
+            return null;
+        const ul = el("ul");
+        for (const c of kids) {
+            const a = el("a", { href: ex.href(`class/${c.species}`) }, c.name);
+            links.set(c.species, a);
+            const n = instanceCount.get(c.species) ?? 0;
+            const li = el("li", {}, a, " ", el("span", { className: "count" }, n ? `${n} instance${n > 1 ? "s" : ""}` : ""), build(c.species));
+            items.set(c.species, li);
+            ul.append(li);
+        }
+        return ul;
+    };
+    // Roots: no superclass, or a superclass that isn't a known class.
+    const known = new Set(classes.map((c) => c.species));
+    for (const c of classes)
+        if (c.superclass >= 0 && !known.has(c.superclass))
+            children.set(-1, [...(children.get(-1) ?? []), c]);
+    const filter = el("input", { type: "search", placeholder: "Filter classes…" });
+    const element = el("div", { className: "tree" }, filter, build(-1));
+    filter.addEventListener("input", () => {
+        const q = filter.value.trim().toLowerCase();
+        const keep = new Set();
+        for (const c of classes) {
+            if (q && !c.name.toLowerCase().includes(q))
+                continue;
+            // Keep the match and its ancestors, so it stays in context.
+            for (let s = c.species; s !== undefined && s >= 0 && !keep.has(s); s = classes.find((x) => x.species === s)?.superclass)
+                keep.add(s);
+        }
+        for (const [species, li] of items)
+            li.style.display = keep.has(species) ? "" : "none";
+    });
+    return {
+        element,
+        select(species) {
+            for (const a of links.values())
+                a.classList.remove("active");
+            if (species === undefined)
+                return;
+            const a = links.get(species);
+            a?.classList.add("active");
+            a?.scrollIntoView({ block: "nearest" });
+        },
+    };
+}

package/apps/viewer/src/explore/classes.ts

@@ -0,0 +1,61 @@
+import type { ClassInfo } from "../../../../packages/sci/src/index.ts";
+import { el, type Explorer } from "./context.ts";
+
+export interface ClassTree {
+  element: HTMLElement;
+  select(species: number | undefined): void;
+}
+
+/** The class hierarchy as an indented tree, with a filter that keeps matches' ancestors. */
+export function createClassTree(ex: Explorer): ClassTree {
+  const { classes } = ex.index;
+  const children = new Map<number, ClassInfo[]>();
+  for (const c of classes) children.set(c.superclass, [...(children.get(c.superclass) ?? []), c]);
+  for (const list of children.values()) list.sort((a, b) => a.name.localeCompare(b.name));
+  const instanceCount = new Map<number, number>();
+  for (const s of ex.index.scripts) for (const o of s.objects) instanceCount.set(o.superclass, (instanceCount.get(o.superclass) ?? 0) + 1);
+
+  const links = new Map<number, HTMLAnchorElement>();
+  const items = new Map<number, HTMLLIElement>();
+  const build = (parent: number): HTMLUListElement | null => {
+    const kids = children.get(parent);
+    if (!kids?.length) return null;
+    const ul = el("ul");
+    for (const c of kids) {
+      const a = el("a", { href: ex.href(`class/${c.species}`) }, c.name);
+      links.set(c.species, a);
+      const n = instanceCount.get(c.species) ?? 0;
+      const li = el("li", {}, a, " ", el("span", { className: "count" }, n ? `${n} instance${n > 1 ? "s" : ""}` : ""), build(c.species));
+      items.set(c.species, li);
+      ul.append(li);
+    }
+    return ul;
+  };
+  // Roots: no superclass, or a superclass that isn't a known class.
+  const known = new Set(classes.map((c) => c.species));
+  for (const c of classes) if (c.superclass >= 0 && !known.has(c.superclass)) children.set(-1, [...(children.get(-1) ?? []), c]);
+  const filter = el("input", { type: "search", placeholder: "Filter classes…" });
+  const element = el("div", { className: "tree" }, filter, build(-1));
+
+  filter.addEventListener("input", () => {
+    const q = filter.value.trim().toLowerCase();
+    const keep = new Set<number>();
+    for (const c of classes) {
+      if (q && !c.name.toLowerCase().includes(q)) continue;
+      // Keep the match and its ancestors, so it stays in context.
+      for (let s: number | undefined = c.species; s !== undefined && s >= 0 && !keep.has(s); s = classes.find((x) => x.species === s)?.superclass) keep.add(s);
+    }
+    for (const [species, li] of items) li.style.display = keep.has(species) ? "" : "none";
+  });
+
+  return {
+    element,
+    select(species) {
+      for (const a of links.values()) a.classList.remove("active");
+      if (species === undefined) return;
+      const a = links.get(species);
+      a?.classList.add("active");
+      a?.scrollIntoView({ block: "nearest" });
+    },
+  };
+}

package/apps/viewer/src/explore/context.d.ts

@@ -0,0 +1,33 @@
+import { type GameIndex, type MessageFile, type ObjectInfo, type Palette, type ResourceManager, type ScriptWorld } from "../../../../packages/sci/src/index.ts";
+/** Everything the explorer's views share. */
+export interface Explorer {
+    rm: ResourceManager;
+    /** Mods loaded over the game (their saves are kept apart). */
+    mods: string[];
+    world: ScriptWorld;
+    index: GameIndex;
+    basePalette: Palette;
+    /** Navigates to a hash route, e.g. "room/710" (the current tab is kept). */
+    href(route: string): string;
+    messages(n: number): Promise<MessageFile | undefined>;
+    pic(n: number): Promise<HTMLCanvasElement | undefined>;
+    object(script: number, offset: number): ObjectInfo | undefined;
+    objectsNamed(name: string): ObjectInfo[];
+}
+type Child = Node | string | null | undefined | false;
+/** `el("a", { href }, "text", child)`: a tiny DOM builder. */
+export declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, props?: Partial<HTMLElementTagNameMap[K]> & Record<string, unknown>, ...children: Child[]): HTMLElementTagNameMap[K];
+export declare const hex: (n: number) => string;
+/** Property values: small numbers as decimal, the rest (addresses, flags) as hex too. */
+export declare const showValue: (v: number) => string;
+export declare function createExplorer(rm: ResourceManager, mods: string[], world: ScriptWorld, index: GameIndex, basePalette: Palette, currentTab: () => string): Explorer;
+/** A small copy of a canvas as a data URL, for map thumbnails. */
+export declare function thumbnail(canvas: HTMLCanvasElement, width?: number): string;
+/**
+ * The room editor's address for room `n`, if a mod describes it in a .room.yaml (preferring
+ * the mods loaded here). The dev server's /__editor/mods lists them; elsewhere, none.
+ */
+export declare function editorUrl(n: number, preferred?: string[]): Promise<string | undefined>;
+/** An "Edit room n" link to the editor, filled in once we know the room is editable. */
+export declare function editorLink(n: number, preferred?: string[]): HTMLAnchorElement;
+export {};

package/apps/viewer/src/explore/context.js

@@ -0,0 +1,96 @@
+import { ResourceType, celToRgba, mergePalette, parseMessages, parsePic, } from "../../../../packages/sci/src/index.js";
+/** `el("a", { href }, "text", child)`: a tiny DOM builder. */
+export function el(tag, props = {}, ...children) {
+    const node = Object.assign(document.createElement(tag), props);
+    for (const c of children)
+        if (c !== null && c !== undefined && c !== false)
+            node.append(c);
+    return node;
+}
+export const hex = (n) => `$${n.toString(16).padStart(4, "0")}`;
+/** Property values: small numbers as decimal, the rest (addresses, flags) as hex too. */
+export const showValue = (v) => (v >= 0x8000 ? `${v - 0x10000}` : v > 255 ? `${v} (${hex(v)})` : `${v}`);
+export function createExplorer(rm, mods, world, index, basePalette, currentTab) {
+    const messageCache = new Map();
+    const picCache = new Map();
+    const objects = new Map();
+    const byName = new Map();
+    for (const s of index.scripts) {
+        for (const o of s.objects) {
+            objects.set(`${o.script}:${o.offset}`, o);
+            byName.set(o.name, [...(byName.get(o.name) ?? []), o]);
+        }
+    }
+    return {
+        rm, mods, world, index, basePalette,
+        href: (route) => `#/${currentTab()}/${route}`,
+        object: (script, offset) => objects.get(`${script}:${offset}`),
+        objectsNamed: (name) => byName.get(name) ?? [],
+        messages(n) {
+            let p = messageCache.get(n);
+            if (!p) {
+                p = rm.has({ type: ResourceType.Message, number: n })
+                    ? rm.load({ type: ResourceType.Message, number: n }).then((r) => parseMessages(r.data))
+                    : Promise.resolve(undefined);
+                messageCache.set(n, p);
+            }
+            return p;
+        },
+        pic(n) {
+            let p = picCache.get(n);
+            if (!p) {
+                p = rm.has({ type: ResourceType.Pic, number: n }) ? rm.load({ type: ResourceType.Pic, number: n }).then((r) => renderPic(r.data, basePalette)) : Promise.resolve(undefined);
+                picCache.set(n, p);
+            }
+            return p;
+        },
+    };
+}
+// Remap colours (shadows, torch light) only mean something at run time: approximate.
+const REMAP = new Map([[253, 64], [254, 110]]);
+function renderPic(data, base) {
+    const pic = parsePic(data);
+    const palette = mergePalette(base, pic.palette);
+    const canvas = el("canvas", { width: pic.width, height: pic.height });
+    const ctx = canvas.getContext("2d");
+    for (const cel of [...pic.cels].sort((a, b) => a.priority - b.priority)) {
+        if (!cel.width || !cel.height)
+            continue;
+        const layer = el("canvas", { width: cel.width, height: cel.height });
+        layer.getContext("2d").putImageData(new ImageData(celToRgba(cel, palette, { remap: REMAP }), cel.width, cel.height), 0, 0);
+        ctx.drawImage(layer, cel.x, cel.y);
+    }
+    return canvas;
+}
+/** A small copy of a canvas as a data URL, for map thumbnails. */
+export function thumbnail(canvas, width = 96) {
+    const height = Math.round((canvas.height / canvas.width) * width * 1.2);
+    const small = el("canvas", { width, height });
+    const ctx = small.getContext("2d");
+    ctx.imageSmoothingQuality = "high";
+    ctx.drawImage(canvas, 0, 0, width, height);
+    return small.toDataURL();
+}
+// --- Rooms the editor can open ------------------------------------------------------------
+let editable;
+/**
+ * The room editor's address for room `n`, if a mod describes it in a .room.yaml (preferring
+ * the mods loaded here). The dev server's /__editor/mods lists them; elsewhere, none.
+ */
+export async function editorUrl(n, preferred = []) {
+    editable ??= fetch("/__editor/mods")
+        .then((r) => (r.ok ? r.json() : []))
+        .catch(() => []);
+    const mods = (await editable).filter((m) => m.rooms.includes(n));
+    const mod = mods.find((m) => preferred.includes(m.name)) ?? mods[0];
+    return mod && `/editor.html?mod=${encodeURIComponent(mod.name)}&room=${n}`;
+}
+/** An "Edit room n" link to the editor, filled in once we know the room is editable. */
+export function editorLink(n, preferred = []) {
+    const a = el("a", { className: "edit-link", target: "_blank", hidden: true, title: "Open this room in the room editor" }, `Edit room ${n}`);
+    void editorUrl(n, preferred).then((url) => {
+        if (url)
+            (a.href = url), (a.hidden = false);
+    });
+    return a;
+}