@nanocollective/roster 0.1.0-alpha.2 → 0.1.0-alpha.4

package/templates/portal/js/app.js

@@ -3,16 +3,24 @@
 import { getOrg } from "./api.js";
 import { $, el, store } from "./dom.js";
 import { icon, iconHTML } from "./icons.js";
+import { installLightbox } from "./lightbox.js";
 import { setPeople } from "./md.js";
-import { refreshAll, stampLoaded, syncNotice } from "./refresh.js";
+import {
+  countInBackground,
+  refreshAll,
+  refreshQuietly,
+  stampCounts,
+  stampLoaded,
+  syncNotice,
+} from "./refresh.js";
 import { onRender } from "./router.js";
-import { ORG_WIDE, S, VIEWS, applyHash, openCount, writeHash } from "./state.js";
+import { ORG_WIDE, S, VIEWS, applyHash, writeHash } from "./state.js";
 import { viewBrain } from "./views/brain.js";
 import { viewChanged } from "./views/changed.js";
 import { viewDocs } from "./views/docs.js";
 import { viewGraph } from "./views/graph.js";
 import { viewHealth } from "./views/health.js";
-import { viewInbox } from "./views/inbox.js";
+import { viewInbox, viewPrs } from "./views/inbox.js";
 import { viewOrg } from "./views/org.js";
 import { viewPrompt } from "./views/prompt.js";
 import { viewSetup } from "./views/setup.js";
@@ -20,6 +28,7 @@ import { viewStaff } from "./views/staff.js";
 
 const SCREEN = {
   inbox: viewInbox,
+  prs: viewPrs,
   org: viewOrg,
   staff: viewStaff,
   docs: viewDocs,
@@ -43,6 +52,9 @@ const NEEDS = ["org", "name", "opsName", "staff"];
 
 export async function boot() {
   initTheme();
+  /* Before the first render, and once: it is delegated, so it covers every image any screen
+     draws from here on, including the setup screen. */
+  installLightbox();
 
   /* Before there is a tenant the server answers every data route with `mode: setup`. That is
      not an error state: it is the first thing a new user ever sees, and the whole page becomes
@@ -51,6 +63,12 @@ export async function boot() {
   if (first && first.mode === "setup") {
     document.body.dataset.setup = "1";
     $("#orgname").textContent = "no org yet";
+    /* Every one of these reads a tenant, so during setup they answer 409 and the sidebar is a
+       row of four dead ends beside an empty Staff heading. There is one thing to do on this
+       screen; the navigation comes back with the org. */
+    for (const el of document.querySelectorAll("#inboxnav, #prsnav, #orgnav, #staffnav, #docsnav, #refreshall, .sect, #stafflist")) {
+      el.hidden = true;
+    }
     for (const slot of document.querySelectorAll("[data-icon]")) {
       slot.innerHTML = iconHTML(slot.dataset.icon);
     }
@@ -74,14 +92,18 @@ export async function boot() {
   paintSidebar();
 
   $("#inboxnav").onclick = () => { S.view = "inbox"; render(); };
+  $("#prsnav").onclick = () => { S.view = "prs"; render(); };
   $("#staffnav").onclick = () => { S.view = "staff"; render(); };
   $("#orgnav").onclick = () => { S.view = "org"; render(); };
   $("#docsnav").onclick = () => { S.view = "docs"; render(); };
   $("#refreshall").onclick = () => refreshAll(false);
 
-  // Coming back to the tab after a run should show the run.
+  /* Coming back to the tab after a run should show the run — and coming back to it thirty
+     seconds after leaving it should show nothing at all. Clicking into the window used to
+     re-read every repo on GitHub and repaint the screen under you; now it looks first and
+     only repaints when something actually moved. */
   addEventListener("focus", () => {
-    if (S.loadedAt && Date.now() - S.loadedAt > 30000) refreshAll(false);
+    if (S.loadedAt && Date.now() - S.loadedAt > 60000) refreshQuietly();
   });
   addEventListener("keydown", (e) => {
     if (e.key === "r" && !e.metaKey && !e.ctrlKey &&
@@ -92,6 +114,11 @@ export async function boot() {
   });
   setInterval(stampLoaded, 30000);
 
+  /* What is waiting on you is the first thing this page should be able to tell you, and it used
+     to be the one thing it would not say until you clicked Inbox. One request, shared with
+     whichever screen renders next. */
+  countInBackground();
+
   // Only the state changes here. This used to re-run half of boot on every navigation,
   // which stacked up a focus listener, a keydown listener and an interval each time.
   addEventListener("hashchange", () => {
@@ -230,8 +257,7 @@ function render() {
   const roster = S.data.staff.map((s) => s.handle).join(" ");
   if (roster !== paintedRoster) paintSidebar();
   markSidebar();
-  const ic = $("#inboxcount");
-  if (ic) ic.textContent = S.inbox ? String(openCount()) : "";
+  stampCounts();
   writeHash(true);
   stampLoaded();
 

package/templates/portal/js/dialog.js

@@ -7,11 +7,47 @@
  */
 
 import { el, grow } from "./dom.js";
+import { attachMentions } from "./mention.js";
 
 /**
+ * Whether a click was on the backdrop, which is not the same question as "is the target the
+ * dialog".
+ *
+ * Picking a name from the `@` list used to close the whole dialog and throw away what you had
+ * typed. The list hides itself on mousedown so the caret survives the pick, so by the time the
+ * `click` lands the row is gone and the event retargets to the nearest thing still under the
+ * pointer, which is the dialog. A target test alone reads that as a backdrop click.
+ *
+ * So the pointer has to actually be outside the dialog's own box. `detail` of 0 is a click
+ * synthesised by the keyboard, which reports 0,0 and would otherwise look like the top corner
+ * of the page.
+ */
+export function onBackdrop(e, rect) {
+  if (!rect || e.currentTarget !== e.target || !e.detail) return false;
+  return (
+    e.clientX < rect.left ||
+    e.clientX > rect.right ||
+    e.clientY < rect.top ||
+    e.clientY > rect.bottom
+  );
+}
+
+/**
+ * @param decorate  given the textarea, returns a node to sit under it. This is how the reply
+ *   box carries its attachments: the control has to write into the box it is beside.
+ * @param allowEmpty  saying nothing is an answer for some of these. Closing an issue without
+ *   a parting comment is the normal case, not a cancelled dialog.
  * @returns the text, or null if they cancelled.
  */
-export function askText({ title, hint, value = "", placeholder = "", confirm = "Continue" }) {
+export function askText({
+  title,
+  hint,
+  value = "",
+  placeholder = "",
+  confirm = "Continue",
+  decorate,
+  allowEmpty = false,
+}) {
   const box = document.createElement("dialog");
   // The shim in the tests has no dialog element. Falling back keeps a view renderable there
   // rather than throwing halfway through a paint.
@@ -25,6 +61,12 @@ export function askText({ title, hint, value = "", placeholder = "", confirm = "
 
   const ta = el("textarea", { value, placeholder, rows: 5 });
   box.append(ta);
+  /* Before the ⌘⏎ handler below, so that when the `@` list is open its own Enter wins. Every
+     dialog this function opens is prose that may need to reach somebody, and a mention is how
+     it reaches them. */
+  attachMentions(ta);
+  const under = decorate?.(ta);
+  if (under) box.append(under);
 
   const cancel = el("button", { className: "ghbtn", textContent: "Cancel" });
   const go = el("button", { className: "ghbtn primary", textContent: confirm });
@@ -42,12 +84,13 @@ export function askText({ title, hint, value = "", placeholder = "", confirm = "
       answer = text;
       box.close();
     };
+    const said = () => ta.value.trim() || (allowEmpty ? "" : null);
     cancel.onclick = () => done(null);
-    go.onclick = () => done(ta.value.trim() || null);
+    go.onclick = () => done(said());
     ta.addEventListener("keydown", (e) => {
       if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
         e.preventDefault();
-        done(ta.value.trim() || null);
+        done(said());
       }
     });
     // Escape and the backdrop both close it, and both mean no.
@@ -56,7 +99,7 @@ export function askText({ title, hint, value = "", placeholder = "", confirm = "
       resolve(answer);
     });
     box.addEventListener("click", (e) => {
-      if (e.target === box) done(null);
+      if (onBackdrop(e, box.getBoundingClientRect?.())) done(null);
     });
 
     document.body.append(box);

package/templates/portal/js/dom.js

@@ -35,6 +35,31 @@ export function markCurrent(list, btn) {
   btn.setAttribute("aria-current", "true");
 }
 
+/**
+ * Placeholder shapes, for the seconds a screen spends asking GitHub.
+ *
+ * The inbox reads every repo in the org, which is several seconds on a cold cache, and what
+ * stood there meanwhile was the word "Asking GitHub…" in an otherwise empty box beside an
+ * empty box. Nothing about that says the shape of what is coming, so the page looked broken
+ * rather than busy.
+ *
+ * `kind` names the shape: "row" for a list item, "line" for a paragraph, "head" for a title.
+ * They are decorative, so they are hidden from assistive technology and the live region
+ * elsewhere on the screen does the announcing.
+ */
+export function skeleton(kind, n = 1) {
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const box = el("div", { className: "sk sk-" + kind });
+    box.setAttribute("aria-hidden", "true");
+    if (kind === "row") {
+      box.append(el("div", { className: "skbar t" }), el("div", { className: "skbar m" }));
+    }
+    out.push(box);
+  }
+  return out;
+}
+
 export function store(k, v) {
   try {
     return v === undefined ? localStorage.getItem(k) : localStorage.setItem(k, v);

package/templates/portal/js/icons.js

@@ -1,6 +1,6 @@
 /* Icons.
  *
- * Twenty-four Lucide glyphs (lucide.dev, ISC), vendored as path data rather than pulled from
+ * Lucide glyphs (lucide.dev, ISC), vendored as path data rather than pulled from
  * a CDN or a font. The portal is local-first and offline, so an icon that needs the network
  * is an icon that is sometimes a blank square.
  *
@@ -53,8 +53,15 @@ const PATHS = {
     "<rect width=\"20\" height=\"14\" x=\"2\" y=\"3\" rx=\"2\" /> <line x1=\"8\" x2=\"16\" y1=\"21\" y2=\"21\" /> <line x1=\"12\" x2=\"12\" y1=\"17\" y2=\"21\" />",
   "moon":
     "<path d=\"M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401\" />",
+  "paperclip":
+    "<path d=\"m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l8.57-8.57A4 4 0 1 1 18 8.84l-8.59 8.57a2 2 0 0 1-2.83-2.83l8.49-8.48\" />",
   "person":
     "<circle cx=\"12\" cy=\"8\" r=\"5\" /> <path d=\"M20 21a8 8 0 0 0-16 0\" />",
+  "play":
+    "<path d=\"M5 5a2 2 0 0 1 3.008-1.728l11.997 6.998a2 2 0 0 1 .003 3.458l-12 7A2 2 0 0 1 5 19z\" />",
+  // The pair for the lightbox's zoom controls. `dash` above is the other half.
+  "plus":
+    "<path d=\"M5 12h14\" /> <path d=\"M12 5v14\" />",
   "refresh":
     "<path d=\"M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8\" /> <path d=\"M21 3v5h-5\" /> <path d=\"M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16\" /> <path d=\"M8 16H3v5\" />",
   "rename":

package/templates/portal/js/lightbox.js

@@ -0,0 +1,273 @@
+/* Looking properly at a picture.
+ *
+ * An image inside a document is laid out for the page it is in, which for a screenshot of a
+ * user interface means unreadable: the thing you wanted to see is the small print. Every other
+ * surface here has an answer for "show me that bigger" and this one did not.
+ *
+ * So any image the portal renders as *content* opens over the page, fitted to the window, and
+ * zooms. Gallery tiles are deliberately not included: they already have a click, which opens
+ * the file, and the file's own view is one of the images this does catch.
+ *
+ * Deliberately not a `<dialog>`. The rest of the portal uses one, and it is right for a form,
+ * but this needs its own key handling, wheel handling and pointer capture, and `showModal`
+ * brings a focus trap and a backdrop that then have to be worked around rather than used.
+ */
+
+import { el } from "./dom.js";
+import { icon } from "./icons.js";
+
+/** Images that open. `.md img` is every rendered document; `zoomable` is opt-in elsewhere. */
+const SELECTOR = ".md img, img.zoomable";
+
+const MIN_SCALE = 0.1;
+
+/**
+ * How far in it will go, and why it is not just a number.
+ *
+ * A scaled `<img>` is a composited layer, and the compositor allocates it at the *rendered*
+ * size. A flat ceiling of 16 turned a 1544x784 screenshot into a 310-megapixel layer, about
+ * 1.2GB of texture, and froze the tab for the best part of a minute. That is not a zoom level
+ * anybody asked for; it is a number that was never checked against a real picture.
+ *
+ * So the ceiling comes off the image. The budget is what may be rendered at once; the floor of
+ * 1 keeps actual size reachable however large the source is, and the cap of 8 stops a 100px
+ * icon being allowed to fill a wall.
+ */
+const MAX_RENDERED_PIXELS = 16e6;
+const ABSOLUTE_MAX = 8;
+
+export function maxScaleFor(natural) {
+  const px = (natural.width || 1) * (natural.height || 1);
+  return Math.min(ABSOLUTE_MAX, Math.max(1, Math.sqrt(MAX_RENDERED_PIXELS / px)));
+}
+
+let open = null;
+
+/**
+ * Zoom about a point, as arithmetic.
+ *
+ * The pixel under the cursor has to stay under the cursor. Without that the image drifts away
+ * from whatever you were trying to look at, which is the difference between a zoom and a
+ * nuisance, and it is the one part of this that is wrong in a way no screenshot shows.
+ *
+ * Pure, and separate from the element, so it can be checked rather than eyeballed.
+ *
+ * @param at     {scale, tx, ty}, the current transform
+ * @param px,py  the fixed point, in stage coordinates
+ * @param max    the ceiling, from `maxScaleFor`
+ * @returns the new transform, or `at` unchanged when it is already against a stop
+ */
+export function zoomAbout(at, factor, px, py, max = ABSOLUTE_MAX) {
+  const scale = Math.min(max, Math.max(MIN_SCALE, at.scale * factor));
+  if (scale === at.scale) return at;
+  const k = scale / at.scale;
+  return { scale, tx: px - (px - at.tx) * k, ty: py - (py - at.ty) * k };
+}
+
+/**
+ * The fitted transform: the whole thing visible, centred, and never enlarged to get there.
+ *
+ * Blowing a 200px image up to fill a 1400px window is not "fitting" it, it is making it worse,
+ * so the scale is capped at 1 and a small picture sits small in the middle.
+ */
+export function fitInside(natural, stage) {
+  const [w, h] = [natural.width || 1, natural.height || 1];
+  const [bw, bh] = [stage.width || 1, stage.height || 1];
+  const scale = Math.min(bw / w, bh / h, 1);
+  return { scale, tx: (bw - w * scale) / 2, ty: (bh - h * scale) / 2 };
+}
+
+/**
+ * One delegated listener, installed at boot.
+ *
+ * Per-image handlers would have to be attached by every render site, and there are four of
+ * them: markdown in a doc page, markdown in a brain document, an image surface, and the file
+ * viewer. A render that forgot would be an image that silently does not open, which is exactly
+ * the sort of thing nobody notices for a month.
+ */
+export function installLightbox() {
+  document.addEventListener?.("click", (e) => {
+    const img = e.target?.closest?.(SELECTOR);
+    if (!img || !img.currentSrc && !img.getAttribute?.("src")) return;
+    // A picture inside a link is the link's to handle. Following it is what was asked for.
+    if (img.closest("a")) return;
+    e.preventDefault();
+    show(img.currentSrc || img.getAttribute("src"), img.getAttribute("alt") || "");
+  });
+
+  /* Navigating away closes it. The overlay is appended to the body rather than into the view,
+     so without this it outlives the page it was opened from: a doc image left open over the
+     Inbox, with no obvious relationship to anything on screen. */
+  addEventListener?.("hashchange", close);
+}
+
+/** Open one. Exported so a caller with a src and no element can use it too. */
+export function show(src, alt = "") {
+  close();
+
+  const img = el("img", { src, alt, draggable: false });
+  const stage = el("div", { className: "lbstage" }, [img]);
+
+  const caption = alt ? el("figcaption", { className: "lbcap", textContent: alt }) : null;
+  const shut = el("button", {
+    className: "lbx",
+    title: "Close (Esc)",
+    "aria-label": "Close",
+  }, [icon("close", "ic")]);
+  const hint = el("span", {
+    className: "lbhint",
+    textContent: "scroll to zoom · drag to move · click to fit",
+  });
+
+  /* Zoom has always worked from the keyboard and the wheel. Neither is discoverable, and on a
+     mouse without a usable wheel the keyboard was the only way in at all.
+     The percentage is a button rather than a readout: "how big is this" and "put it back" are
+     the same question, and it is the one control here that says what the state is. */
+  const out = el("button", {
+    className: "lbctl",
+    title: "Zoom out (-)",
+    "aria-label": "Zoom out",
+  }, [icon("dash", "ic")]);
+  const level = el("button", { className: "lbctl lblevel", title: "Fit to the window (0)" });
+  const into = el("button", {
+    className: "lbctl",
+    title: "Zoom in (+)",
+    "aria-label": "Zoom in",
+  }, [icon("plus", "ic")]);
+  const zoombar = el("div", { className: "lbzoom" }, [out, level, into]);
+
+  const box = el("div", {
+    className: "lightbox",
+    role: "dialog",
+    "aria-modal": "true",
+    "aria-label": alt || "image",
+  }, [stage, shut, hint, zoombar, ...(caption ? [caption] : [])]);
+
+  /* Scale and offset are kept here rather than read back off the transform, because reading a
+     matrix back and re-deriving them accumulates error over a few dozen wheel events. */
+  let scale = 1;
+  let fit = 1;
+  let ceiling = ABSOLUTE_MAX;
+  let tx = 0;
+  let ty = 0;
+
+  const draw = () => {
+    img.style.transform = `translate(${tx}px, ${ty}px) scale(${scale})`;
+    box.dataset.zoomed = String(scale > fit * 1.001);
+    /* Percentage of actual size, not of fitted: 100% has to mean one image pixel per screen
+       pixel, or the number is about the window rather than about the picture. */
+    level.textContent = `${Math.round(scale * 100)}%`;
+    // Disabled at the stops, because a button that does nothing reads as a broken one.
+    out.disabled = scale <= MIN_SCALE + 1e-9;
+    into.disabled = scale >= ceiling - 1e-9;
+  };
+
+  const reset = () => {
+    const natural = {
+      width: img.naturalWidth || img.width,
+      height: img.naturalHeight || img.height,
+    };
+    const at = fitInside(natural, stage.getBoundingClientRect?.() ?? { width: 0, height: 0 });
+    fit = at.scale;
+    ceiling = maxScaleFor(natural);
+    ({ scale, tx, ty } = at);
+    draw();
+  };
+
+  const zoomAt = (factor, px, py) => {
+    ({ scale, tx, ty } = zoomAbout({ scale, tx, ty }, factor, px, py, ceiling));
+    draw();
+  };
+
+  const centre = () => {
+    const r = stage.getBoundingClientRect?.() ?? { width: 0, height: 0 };
+    return [r.width / 2, r.height / 2];
+  };
+
+  img.addEventListener("load", reset);
+  if (img.complete) reset();
+
+  box.addEventListener(
+    "wheel",
+    (e) => {
+      e.preventDefault();
+      const r = stage.getBoundingClientRect();
+      // ctrl+wheel is what a trackpad pinch arrives as, and it comes in much larger steps.
+      const step = e.ctrlKey ? 0.01 : 0.0015;
+      zoomAt(Math.exp(-e.deltaY * step), e.clientX - r.left, e.clientY - r.top);
+    },
+    { passive: false },
+  );
+
+  /* Drag to pan, and the same gesture decides what a release means: a press that moved is a
+     pan, a press that did not is a click. Without the distance test, panning an image always
+     ended by toggling the zoom you had just set. */
+  let from = null;
+  let moved = false;
+  img.addEventListener("pointerdown", (e) => {
+    from = { x: e.clientX, y: e.clientY, tx, ty };
+    moved = false;
+    img.setPointerCapture?.(e.pointerId);
+  });
+  img.addEventListener("pointermove", (e) => {
+    if (!from) return;
+    const dx = e.clientX - from.x;
+    const dy = e.clientY - from.y;
+    if (Math.abs(dx) + Math.abs(dy) > 3) moved = true;
+    tx = from.tx + dx;
+    ty = from.ty + dy;
+    draw();
+  });
+  img.addEventListener("pointerup", (e) => {
+    const wasDrag = moved;
+    from = null;
+    img.releasePointerCapture?.(e.pointerId);
+    if (wasDrag) return;
+    // Fitted: go to actual size under the cursor. Zoomed at all: back to fitted.
+    const r = stage.getBoundingClientRect();
+    if (scale > fit * 1.001) reset();
+    else zoomAt(1 / fit, e.clientX - r.left, e.clientY - r.top);
+  });
+
+  // The buttons zoom about the middle of the stage, which is the only fixed point they have.
+  out.onclick = () => zoomAt(0.8, ...centre());
+  into.onclick = () => zoomAt(1.25, ...centre());
+  level.onclick = reset;
+
+  // The backdrop is the way out, and the image is not the backdrop.
+  box.addEventListener("pointerdown", (e) => {
+    if (e.target === box || e.target === stage) close();
+  });
+  shut.onclick = close;
+
+  const keys = (e) => {
+    if (e.key === "Escape") return close();
+    if (e.key === "0") return reset();
+    if (e.key === "+" || e.key === "=") return zoomAt(1.25, ...centre());
+    if (e.key === "-" || e.key === "_") return zoomAt(0.8, ...centre());
+  };
+  addEventListener("keydown", keys);
+
+  const onResize = () => reset();
+  addEventListener("resize", onResize);
+
+  const returnTo = document.activeElement;
+  open = { box, keys, onResize, returnTo };
+
+  document.body.append(box);
+  // The page behind must not scroll under an overlay: the scrollbar is still live otherwise,
+  // and a wheel event that misses the image scrolls the document instead of zooming.
+  document.body.dataset.lightbox = "1";
+  shut.focus?.();
+}
+
+export function close() {
+  if (!open) return;
+  const { box, keys, onResize, returnTo } = open;
+  open = null;
+  removeEventListener("keydown", keys);
+  removeEventListener("resize", onResize);
+  box.remove?.();
+  delete document.body.dataset.lightbox;
+  returnTo?.focus?.();
+}

package/templates/portal/js/md.js

@@ -6,6 +6,7 @@
 
 import { esc } from "./dom.js";
 import { iconHTML } from "./icons.js";
+import { yamlHTMLFromEscaped } from "./yaml.js";
 
 /* Who this org is, so `@cto` can be told from `@some-stranger`. Registered once at boot
    rather than threaded through every call site, because every call site would pass the
@@ -144,10 +145,13 @@ export function mdlite(src, opts = {}) {
     chips(
       s
         .replace(/`([^`]+)`/g, "<code>$1</code>")
-        .replace(
-          /!\[([^\]]*)\]\(([^)\s]+)\)/g,
-          (_m, alt, src2) =>
-            '<img src="' + mdAsset(src2, opts) + '" alt="' + alt + '" loading="lazy">',
+        .replace(/!\[([^\]]*)\]\(([^)\s]+)\)/g, (_m, alt, src2) =>
+          // `![](clip.mp4)` is how a recording gets written into a note, and GitHub plays it.
+          // An <img> pointing at a video is a broken-image icon, so it becomes a player.
+          /\.(mp4|m4v|webm|mov|ogv)(\?|#|$)/i.test(src2)
+            ? '<video src="' + mdAsset(src2, opts) + '" controls preload="metadata" class="player">' +
+              "</video>"
+            : '<img src="' + mdAsset(src2, opts) + '" alt="' + alt + '" loading="lazy">',
         )
         // Non-greedy and allowing an inner asterisk, because "**bold with *this* inside**" is
         // ordinary in these files and the old pattern silently left the stars on the page.
@@ -187,11 +191,19 @@ export function mdlite(src, opts = {}) {
     }
 
     if (line.trim().startsWith("```")) {
+      // The fence's language was thrown away, which is most of why a YAML example in the docs
+      // read as a grey block while the same file in the Org screen is coloured.
+      const lang = line.trim().slice(3).trim().toLowerCase();
       const buf = [];
       i++;
       while (i < lines.length && !lines[i].trim().startsWith("```")) buf.push(lines[i++]);
       i++;
-      out.push("<pre><code>" + buf.join("\n") + "</code></pre>");
+      const body = buf.join("\n");
+      out.push(
+        "<pre" + (lang ? ' class="lang-' + esc(lang) + '"' : "") + "><code>" +
+          (lang === "yaml" || lang === "yml" ? yamlHTMLFromEscaped(body) : body) +
+          "</code></pre>",
+      );
       continue;
     }
 
@@ -340,7 +352,12 @@ function mdPath(href, opts) {
 }
 
 function mdAsset(src, opts) {
-  const path = /^(https?:|data:)/.test(src) ? null : mdPath(src, opts);
+  if (/^(https?:|data:)/.test(src)) return src;
+  /* A screenshot in the docs is not in anybody's brain repo, so it cannot go through
+     /api/file, which resolves inside the workspace. It comes off the framework's own docs
+     directory instead, through a route that serves nothing else. */
+  if (opts.docs) return "/api/docasset?path=" + encodeURIComponent(src.replace(/^\.?\//, ""));
+  const path = mdPath(src, opts);
   return path ? "/api/file?path=" + encodeURIComponent(opts.file.staffDir + "/" + path) : src;
 }