scenescout 3.14.1 → 3.16.0

package/dist/engine/refresh.js

@@ -12,7 +12,17 @@
  * has already rotated the token, it loads the rotated profile and sends the
  * current token in place of the spent one. When the response arrives and the
  * page has stored what it got back, the session writes its state over the
- * profile and releases the lock. No two sessions ever present one token.
+ * profile and releases the lock, so two sessions do not present one token.
+ *
+ * Which requests count is decided by brokerDecision. A token in the body, the
+ * URL or a header the page set makes the request a refresh. A token that is
+ * only in the Cookie header does not by itself: a refresh cookie scoped to "/"
+ * rides on every request the page makes, scripts and images included. Such a
+ * request counts only when it is plausibly the refresh call, a POST to a path
+ * named for one or an endpoint the broker has seen rotate the cookie. Static
+ * assets never count, and a broker that cannot do its job lets the request
+ * through as the page sent it: an app left without its scripts is worse than
+ * the rare double refresh.
  *
  * Sessions may be separate processes (one MCP server per lane) sharing the
  * profile on disk, so the lock is a file, created exclusively, owner-only,
@@ -37,8 +47,14 @@ export const REFRESH_NAME_RE = /refresh/i;
 export const MIN_TOKEN_LENGTH = 16;
 /** How deep inside a JSON-valued storage entry a refresh-token field is looked for. */
 const MAX_JSON_DEPTH = 4;
+/**
+ * Whether a value could be a token: long enough, no whitespace, and not an
+ * address. An app that keeps the URL it refreshes at under a refresh-named key
+ * ("/auth/refresh", "https://…/token") stores a path, which every request to
+ * that path would otherwise seem to carry.
+ */
 function looksLikeToken(value) {
-    return typeof value === "string" && value.length >= MIN_TOKEN_LENGTH && !/\s/.test(value);
+    return typeof value === "string" && value.length >= MIN_TOKEN_LENGTH && !/\s/.test(value) && !/^(\/|[a-z][a-z0-9+.-]*:\/\/)/i.test(value);
 }
 /** Refresh-token fields inside a JSON value, by dotted path. */
 function jsonFields(value, at, depth, out) {
@@ -66,7 +82,7 @@ export function refreshTokenSlots(state) {
     if (Array.isArray(s.cookies)) {
         for (const c of s.cookies) {
             if (typeof c?.name === "string" && REFRESH_NAME_RE.test(c.name) && looksLikeToken(c.value)) {
-                out.push({ slot: `cookie ${c.name} (${String(c.domain ?? "")}${String(c.path ?? "")})`, value: c.value });
+                out.push({ slot: `cookie ${c.name} (${String(c.domain ?? "")}${String(c.path ?? "")})`, value: c.value, cookie: c.name });
             }
         }
     }
@@ -106,29 +122,151 @@ function wireForms(value) {
     return encoded === value ? [value] : [value, encoded];
 }
 /**
- * The known refresh token a request carries — in its body, a header (a Cookie
- * header included) or its URL — or null. `known` is what the session last
- * loaded from the profile; a token the page got some other way is not the
- * role's and is left alone.
+ * Headers the browser adds to a request by itself. A token found in one of
+ * these was not sent by the page as an act of refreshing: a cookie scoped to
+ * "/" rides on every request the page makes, and a page whose own address
+ * carries a token passes it on as the Referer of everything it loads.
+ */
+function browserAddedHeader(name) {
+    const n = name.toLowerCase();
+    return n === "cookie" || n === "referer" || n === "origin" || n === "host" || n.startsWith("sec-") || n.startsWith(":");
+}
+/**
+ * The known refresh token a request carries, and where, or null. `known` is
+ * what the session last loaded from the profile; a token the page got some
+ * other way is not the role's and is left alone. A token in the body, the URL
+ * or a header the page set wins over one that is only in the Cookie header.
  */
-export function presentedToken(req, known) {
+export function tokenPresence(req, known) {
     if (known.length === 0)
         return null;
-    const haystacks = [req.body ?? "", req.url, ...Object.values(req.headers)];
+    const carries = (haystack, t) => wireForms(t.value).some((form) => haystack.includes(form));
+    const explicit = Object.entries(req.headers)
+        .filter(([name]) => !browserAddedHeader(name))
+        .map(([, value]) => value);
     for (const t of known) {
-        for (const form of wireForms(t.value)) {
-            if (haystacks.some((h) => h.includes(form)))
-                return t;
-        }
+        if (req.body && carries(req.body, t))
+            return { slot: t, via: "body" };
+        if (carries(req.url, t))
+            return { slot: t, via: "url" };
+        if (explicit.some((h) => carries(h, t)))
+            return { slot: t, via: "header" };
     }
+    const cookie = Object.entries(req.headers).find(([name]) => name.toLowerCase() === "cookie")?.[1] ?? "";
+    for (const t of known)
+        if (cookie && carries(cookie, t))
+            return { slot: t, via: "cookie" };
     return null;
 }
+/**
+ * Requests for a page's static assets. They are never brokered, waited on or
+ * dropped, whatever cookie rides on them: holding a script back behind the
+ * refresh lock leaves the app under test without its code.
+ */
+export const STATIC_RESOURCE_TYPES = new Set(["script", "stylesheet", "image", "font", "media", "manifest", "texttrack"]);
+export function isStaticAsset(method, resourceType) {
+    return (method === "GET" || method === "HEAD") && STATIC_RESOURCE_TYPES.has(resourceType);
+}
+/**
+ * Path segments that name a token refresh. Whole segments, as the write
+ * policy's auth segments are, never substrings: `/api/tokens` mints an API
+ * token and `/refreshments` is a menu.
+ */
+const REFRESH_SEGMENT_RE = /^(refresh|refresh[-_]?token|token|renew|reauth|reauthenticate)$/i;
+/** A path whose last one or two segments name a token refresh: /auth/refresh, /oauth/token, /api/token/refresh. */
+export function refreshLikePath(pathname) {
+    const segments = pathname.split("/").filter(Boolean);
+    return segments.slice(-2).some((seg) => REFRESH_SEGMENT_RE.test(seg));
+}
+/** An endpoint as the broker remembers it: the method and the path, without the query. */
+export function endpointKey(method, url) {
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        pathname = url.split("?")[0];
+    }
+    return `${method.toUpperCase()} ${pathname}`;
+}
+/**
+ * Path segments of a sign-in, a sign-up or a sign-out. A cookie such a request
+ * sets is a new sign-in, perhaps as somebody else, not a refresh: the broker
+ * neither learns the endpoint nor saves the cookie over the role's profile.
+ */
+const SIGN_IN_SEGMENT_RE = /^(login|log-in|signin|sign-in|logout|log-out|signout|sign-out|signup|sign-up|register|verify|otp|magic-link|callback|authorize|sso)$/i;
+/** Whether an endpoint seen to rotate the token may be learned as the refresh call: any but a sign-in, sign-up or sign-out. */
+export function learnableEndpoint(url) {
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        return false;
+    }
+    return !pathname
+        .split("/")
+        .filter(Boolean)
+        .slice(-2)
+        .some((seg) => SIGN_IN_SEGMENT_RE.test(seg));
+}
+/** A body that asks for a grant other than a refresh (a password or code sign-in) is not a refresh, whatever cookie rides on it. */
+function otherGrant(body) {
+    const m = /grant_type["']?\s*[=:]\s*["']?([A-Za-z_:.-]+)/.exec(body ?? "");
+    return m !== null && !/refresh/i.test(m[1]);
+}
+/**
+ * Whether a token that is only in the Cookie header could make this request a
+ * refresh, so that header is worth reading at all. A cookie alone never does,
+ * since a cookie scoped to "/" rides on every request. Only a request that is
+ * plausibly the refresh call counts: one the broker has learned rotates the
+ * token (`learned`, by endpointKey), or a POST, PUT or PATCH to a path whose
+ * last one or two segments name a refresh.
+ */
+export function cookieMayCount(method, url, learned) {
+    if (learned.has(endpointKey(method, url)))
+        return true;
+    if (method !== "POST" && method !== "PUT" && method !== "PATCH")
+        return false;
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        return false;
+    }
+    return refreshLikePath(pathname);
+}
+/**
+ * Whether a request goes through the refresh lock. A static asset never does.
+ * A request carrying a known token in its body, URL or a header the page set
+ * does. A token that is only in the Cookie header counts only for a request
+ * that is plausibly the refresh call (cookieMayCount), and not for one whose
+ * body asks for another grant.
+ */
+export function brokerDecision(req, known, learned) {
+    if (isStaticAsset(req.method, req.resourceType))
+        return { kind: "pass", why: "static asset" };
+    const found = tokenPresence(req, known);
+    if (!found)
+        return { kind: "pass", why: "no known token" };
+    if (found.via !== "cookie")
+        return { kind: "broker", sent: found.slot, via: found.via };
+    if (!cookieMayCount(req.method, req.url, learned))
+        return { kind: "pass", why: "only in a cookie" };
+    if (otherGrant(req.body))
+        return { kind: "pass", why: "another grant" };
+    return { kind: "broker", sent: found.slot, via: "cookie" };
+}
 export function planRefresh(sent, current) {
     if (current.some((c) => c.value === sent.value))
         return { kind: "send" };
     const same = current.find((c) => c.slot === sent.slot);
     return same ? { kind: "swap", to: same } : { kind: "unknown" };
 }
+export function profileLoadWhileHeld(isNavigation) {
+    return isNavigation ? "cookies" : "storage";
+}
 /** Replace a spent token with the current one in a body, URL or header value, in whichever wire form it appears. */
 export function swapToken(text, from, to) {
     let out = text.split(from).join(to);
@@ -173,12 +311,103 @@ export function rotationStored(state, sent) {
  * page's storage state, which has no sessionStorage, with the sessionStorage
  * of the profile on disk kept beside it. Without it, an app whose sign-in also
  * lives in sessionStorage would lose that half on every brokered refresh.
- * A profile that could not be read (null) leaves the page's state as it is.
+ * The same goes for IndexedDB, which a storage state holds only when it was
+ * asked for: an origin the page's state has no IndexedDB entry for keeps the
+ * one on disk. An origin whose state does list IndexedDB, even an empty list,
+ * is the page's as it now is. With `storageFrom` "disk" the origins
+ * (localStorage and IndexedDB) are the profile's on disk and only the cookies
+ * are the page's (writeBackStorageFrom). A profile that could not be read
+ * (null) leaves the page's state as it is.
  */
-export function profileAfterRotation(pageState, profileOnDisk) {
+export function profileAfterRotation(pageState, profileOnDisk, storageFrom = "page") {
     if (profileOnDisk === null)
         return pageState;
-    return withSessionStorage(pageState, splitProfile(profileOnDisk).sessionStorage);
+    const disk = splitProfile(profileOnDisk);
+    if (storageFrom === "disk" && pageState && typeof pageState === "object") {
+        return withSessionStorage({ ...pageState, origins: disk.storageState.origins ?? [] }, disk.sessionStorage);
+    }
+    return withSessionStorage(withIndexedDB(pageState, disk.storageState.origins), disk.sessionStorage);
+}
+/**
+ * Where a write-back takes each origin's storage from (profileAfterRotation's
+ * `storageFrom`). A swap that loaded only the profile's cookies while it held
+ * a navigation (profileLoadWhileHeld) left the page's storage as it was
+ * before the other session's rotation, so writing that back would put spent
+ * tokens over the current ones on disk: the storage stays the profile's, and
+ * only the cookies, where the rotation it presented lives, are the page's.
+ * A token presented from storage is the page's to store, so its storage is
+ * taken from the page as it is now.
+ */
+export function writeBackStorageFrom(loaded, presented) {
+    return loaded === "cookies" && presented.cookie !== undefined ? "disk" : "page";
+}
+/** `state` with each disk origin's IndexedDB carried over where the state has none of its own (profileAfterRotation). */
+function withIndexedDB(state, diskOrigins) {
+    const kept = diskOrigins.filter((o) => !!o && typeof o === "object" && typeof o.origin === "string" && Array.isArray(o.indexedDB));
+    if (kept.length === 0 || !state || typeof state !== "object")
+        return state;
+    const origins = Array.isArray(state.origins) ? [...state.origins] : [];
+    for (const disk of kept) {
+        const at = origins.findIndex((o) => !!o && typeof o === "object" && o.origin === disk.origin);
+        if (at === -1)
+            origins.push({ origin: disk.origin, localStorage: [], indexedDB: disk.indexedDB });
+        else if (origins[at].indexedDB === undefined)
+            origins[at] = { ...origins[at], indexedDB: disk.indexedDB };
+    }
+    return { ...state, origins };
+}
+/**
+ * The lines an action's result carries for what the refresh broker did since
+ * the last action result (a write-back can finish after the action that
+ * started it): one line per kind of event, counted, in a fixed order. Counts only: no
+ * token, slot value or endpoint is named. Empty when it did nothing.
+ */
+export function refreshNotice(events) {
+    const count = (kind) => events.filter((e) => e === kind).length;
+    const times = (n) => (n > 1 ? ` (${n} times)` : "");
+    const lines = [];
+    const refreshed = count("refreshed");
+    if (refreshed > 0)
+        lines.push(`↻ token refreshed under the role's lock and stored in its profile${times(refreshed)}`);
+    const swapped = count("swapped");
+    if (swapped > 0)
+        lines.push(`↻ another session had rotated the role's token; loaded its profile and sent the current one${times(swapped)}`);
+    const learned = count("learned");
+    if (learned > 0)
+        lines.push(`↻ learned ${learned} endpoint${learned === 1 ? "" : "s"} that rotate${learned === 1 ? "s" : ""} the role's token; brokered from now on`);
+    const failed = count("failed");
+    if (failed > 0)
+        lines.push(`⚠ ${failed === 1 ? "a refresh" : `${failed} refreshes`} could not be brokered (see the action log)`);
+    return lines.map((l) => `\n${l}`).join("");
+}
+/**
+ * The cookies a response's Set-Cookie headers set, by name. A header value may
+ * hold several cookies joined by newlines, as some browsers report them.
+ */
+function setCookiePairs(setCookies) {
+    const out = new Map();
+    for (const line of setCookies.flatMap((l) => l.split("\n"))) {
+        const pair = line.split(";")[0];
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            continue;
+        out.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());
+    }
+    return out;
+}
+/**
+ * The known cookie tokens a response's Set-Cookie headers replace with a new
+ * token: the request that got this response refreshed them. A cookie set to an
+ * empty or short value is being cleared (a sign-out), not rotated.
+ */
+export function rotatedCookies(setCookies, known) {
+    const set = setCookiePairs(setCookies);
+    return known.filter((t) => {
+        if (t.cookie === undefined)
+            return false;
+        const next = set.get(t.cookie);
+        return looksLikeToken(next) && next !== t.value;
+    });
 }
 /**
  * The rotated refresh token a refresh response carries, for a page that did
@@ -198,16 +427,9 @@ export function rotatedFromResponse(body, setCookies) {
         // Not a JSON body: the Set-Cookie headers are all there is to read.
     }
     if (found.size === 0) {
-        for (const line of setCookies) {
-            const pair = line.split(";")[0];
-            const eq = pair.indexOf("=");
-            if (eq <= 0)
-                continue;
-            const name = pair.slice(0, eq).trim();
-            const value = pair.slice(eq + 1).trim();
+        for (const [name, value] of setCookiePairs(setCookies))
             if (REFRESH_NAME_RE.test(name) && looksLikeToken(value))
                 found.add(value);
-        }
     }
     return found.size === 1 ? [...found][0] : null;
 }
@@ -224,6 +446,26 @@ export function swapProfileToken(state, from, to) {
     }
     return s;
 }
+/**
+ * The headers the broker sends a request with when it has to send the request
+ * itself, which it does only to put the current token in a Cookie header (a
+ * browser keeps the Cookie header it built, whatever a route override says).
+ * The page's own headers are kept; the ones the HTTP client sets for itself
+ * (host, content length, connection, the encodings it can decode) and
+ * pseudo-headers are left out, and `cookie` is the line to send.
+ */
+export function headersForResend(headers, cookie) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        const n = name.toLowerCase();
+        if (n.startsWith(":") || ["host", "content-length", "connection", "transfer-encoding", "accept-encoding", "cookie"].includes(n))
+            continue;
+        out[n] = value;
+    }
+    if (cookie)
+        out.cookie = cookie;
+    return out;
+}
 // ── Whether the broker runs ──────────────────────────────────────────────────
 export const REFRESH_BROKER_ENV = "SCENESCOUT_REFRESH_BROKER";
 /**
@@ -255,6 +497,60 @@ export const DEFAULT_WAIT_MS = 45_000;
 export function lockPathFor(profileFile) {
     return `${profileFile}.lock`;
 }
+// ── Endpoints learned to rotate the token ──────────────────────────────────
+/**
+ * Where the broker keeps the endpoints it has seen rotate the role's refresh
+ * token, beside the profile: every session of the role reads it, so a session
+ * brokers an endpoint another session learned, even in another process.
+ */
+export function endpointsPathFor(profileFile) {
+    return `${profileFile}.endpoints`;
+}
+/** At most this many learned endpoints are kept, newest first. */
+export const MAX_LEARNED_ENDPOINTS = 20;
+const ENDPOINT_KEY_RE = /^(GET|POST|PUT|PATCH) \/\S{0,500}$/;
+/** The learned endpoints on disk. None when there is no file yet; a file that is not the broker's teaches nothing. */
+export function readLearnedEndpoints(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return []; // written by rename, so never half-written: whatever this is, it is not a list of endpoints
+    }
+    const list = parsed?.endpoints;
+    if (!Array.isArray(list))
+        return [];
+    return list.filter((e) => typeof e === "string" && ENDPOINT_KEY_RE.test(e)).slice(0, MAX_LEARNED_ENDPOINTS);
+}
+/** The list with `key` added first, once, and the oldest dropped past the cap. A key that is not an endpoint changes nothing. */
+export function withLearnedEndpoint(list, key) {
+    if (!ENDPOINT_KEY_RE.test(key))
+        return [...list];
+    return [key, ...list.filter((e) => e !== key)].slice(0, MAX_LEARNED_ENDPOINTS);
+}
+/** Write the learned endpoints owner-only, by rename, so a reader never sees half a file. Call it holding the lock. */
+export function writeLearnedEndpoints(file, list) {
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.rmSync(temp, { force: true });
+    const fd = fs.openSync(temp, "wx", LOCK_FILE_MODE);
+    try {
+        fs.writeFileSync(fd, JSON.stringify({ endpoints: list }));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(temp, file);
+}
 /** Whether a lock last touched at `mtimeMs` is stale at `now`. */
 export function isStale(mtimeMs, now, staleMs) {
     return now - mtimeMs > staleMs;
@@ -275,6 +571,20 @@ function readNonce(file) {
     }
 }
 /** One attempt: the lock, or null when another process holds a live one. */
+/**
+ * What an error from creating the lock file means. EEXIST: another process
+ * holds it. On Windows, creating a file whose previous copy is still being
+ * deleted (a lock just released) fails with EPERM, EBUSY or EACCES instead;
+ * that is the lock changing hands, so it is waited out like a held lock, not
+ * reported as a failure. Anything else is a real error.
+ */
+export function lockCreateError(code, platform = process.platform) {
+    if (code === "EEXIST")
+        return "held";
+    if (platform === "win32" && (code === "EPERM" || code === "EBUSY" || code === "EACCES"))
+        return "busy";
+    return "error";
+}
 export function tryAcquireLock(file, opts = {}) {
     const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
     const now = opts.now ?? Date.now;
@@ -289,8 +599,11 @@ export function tryAcquireLock(file, opts = {}) {
         }
     }
     catch (err) {
-        if (err.code !== "EEXIST")
+        const meaning = lockCreateError(err.code, opts.platform);
+        if (meaning === "error")
             throw err;
+        if (meaning === "busy")
+            return null; // being deleted as it changes hands: try again next poll
         let mtimeMs;
         try {
             mtimeMs = fs.statSync(file).mtimeMs;

package/dist/engine/replay.js

@@ -19,8 +19,16 @@
  * escaping and the grouping are table-tested.
  */
 import path from "node:path";
+import { isSafeRelativePath } from "./plain.js";
 /** Most frames one recorded session keeps. A long run is thousands of actions, and a project folder is not a video store. */
 export const RECORD_MAX_FRAMES = 600;
+/** A name reduced to one plain path segment: letters, digits, dot, dash and underscore, never leading with a dot or dash. */
+export function plainSegment(text, fallback) {
+    return (text
+        .replace(/[^a-z0-9._-]+/gi, "-")
+        .replace(/^[.-]+/, "")
+        .slice(0, 60) || fallback);
+}
 /**
  * Where a recorded frame is stored, relative to the memory directory — and
  * the path the live view serves it at, so it is always written with forward
@@ -29,11 +37,7 @@ export const RECORD_MAX_FRAMES = 600;
  * nothing about where the engine writes.
  */
 export function framePath(session, index, action) {
-    const plain = (text, fallback) => text
-        .replace(/[^a-z0-9._-]+/gi, "-")
-        .replace(/^[.-]+/, "")
-        .slice(0, 60) || fallback;
-    return `recordings/${plain(session, "session")}/${String(index).padStart(4, "0")}-${plain(action, "step")}.jpg`;
+    return `recordings/${plainSegment(session, "session")}/${String(index).padStart(4, "0")}-${plainSegment(action, "step")}.jpg`;
 }
 /**
  * The file a viewer's frame request names, or null when it is not one of this
@@ -136,9 +140,18 @@ export function evidenceFor(steps, foundAt, most = 4) {
         frame: x.frame,
     }));
 }
+/** A finding's own picture, shown open under it: the evidence a reader looks for first. */
+function renderPicture(p, id, framePrefix = "", savedAt = "") {
+    const src = escapeHtml(framePrefix + p.file);
+    return (`<figure class="picture"><a class="frame" href="${src}" target="_blank" rel="noreferrer" data-testid="finding-picture-open" data-finding="${escapeHtml(id)}">` +
+        `<img loading="lazy" ${GONE} src="${src}"${p.width && p.height ? ` width="${p.width}" height="${p.height}"` : ""} alt="What the finding is about, when it was filed">` +
+        `<p class="gone-note">This picture is not beside this file. Pictures live in the run's <code>recordings/</code> folder, which travels with it.</p></a>` +
+        `<figcaption>${escapeHtml(p.caption)}${savedAt ? `<span class="onDisk">${escapeHtml(savedAt + "/" + p.file)}</span>` : ""}</figcaption></figure>`);
+}
 function renderEvidence(e, framePrefix = "", savedAt = "") {
+    const picture = e.picture ? renderPicture(e.picture, e.id, framePrefix, savedAt) : "";
     if (e.frames.length === 0)
-        return "";
+        return picture;
     const shots = e.frames
         .map((f) => `<figure><img loading="lazy" ${GONE} src="${escapeHtml(framePrefix + f.frame)}" alt="The page when this step ran">` +
         `<p class="gone-note">This frame is not beside this file. Frames live in the run's <code>recordings/</code> folder, which travels with it.</p>` +
@@ -146,8 +159,10 @@ function renderEvidence(e, framePrefix = "", savedAt = "") {
         (savedAt ? `<span class="onDisk">${escapeHtml(savedAt + "/" + f.frame)}</span>` : "") +
         `</figcaption></figure>`)
         .join("");
-    return `<details class="evidence"><summary>Evidence — the ${e.frames.length} step${e.frames.length === 1 ? "" : "s"} on screen before this was filed</summary><div class="shots">${shots}</div></details>`;
+    return `${picture}<details class="evidence"><summary>Evidence — the ${e.frames.length} step${e.frames.length === 1 ? "" : "s"} on screen before this was filed</summary><div class="shots">${shots}</div></details>`;
 }
+/** The report's sections the header links to, by heading. */
+const SECTION_ANCHORS = { "In plain words": "plain", "Technical detail": "technical" };
 /**
  * The report's markdown as elements. A deliberately small subset — headings,
  * tables, lists, code fences, the report's own <details> repro blocks — built
@@ -184,12 +199,28 @@ export function renderMarkdown(md, evidence = [], framePrefix = "", savedAt = ""
         else if ((m = /^(#{1,6}) (.*)$/.exec(line))) {
             flush();
             const level = Math.min(6, m[1].length + 1);
-            out.push(`<h${level}>${inline(m[2])}</h${level}>`);
+            // The two parts of the report are what the header links to.
+            const anchor = m[1] === "##" ? SECTION_ANCHORS[m[2]] : undefined;
+            out.push(`<h${level}${anchor ? ` id="${anchor}"` : ""}>${inline(m[2])}</h${level}>`);
+            i += 1;
+        }
+        else if ((m = /^!\[([^\]]*)\]\(([^)\s]+)\)$/.exec(line))) {
+            // A finding's picture. The path is the report's own, relative to the run's
+            // folder, and anything else (a scheme, an absolute path, `..`) is dropped.
+            flush();
+            if (isSafeRelativePath(m[2])) {
+                const src = (m[2].startsWith("recordings/") ? framePrefix : "") + m[2];
+                out.push(`<figure class="picture"><a href="${escapeHtml(src)}" target="_blank" rel="noreferrer" data-testid="report-picture-open"><img loading="lazy" ${GONE} src="${escapeHtml(src)}" alt="${escapeHtml(m[1])}"></a>` +
+                    `<p class="gone-note">This picture is not beside this file. It lives in the run's folder, which travels with it.</p>` +
+                    (savedAt ? `<span class="onDisk">${escapeHtml(savedAt + "/" + m[2])}</span>` : "") +
+                    `</figure>`);
+            }
             i += 1;
         }
         else if ((m = /^<details><summary>(.*)<\/summary>$/.exec(line))) {
             flush();
-            out.push(`<details><summary>${inline(m[1])}</summary>`);
+            const testid = m[1] === "Technical detail" ? "report-technical-toggle" : "report-details-toggle";
+            out.push(`<details><summary data-testid="${testid}">${inline(m[1])}</summary>`);
             i += 1;
         }
         else if (/^<\/details>$/.test(line)) {
@@ -298,6 +329,10 @@ ol.steps { list-style:none; margin:0; padding:0; }
 .step .d { color:var(--muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
 .step .frame { display:block; margin:4px 0 10px; }
 .step .frame img { max-width:min(100%,720px); max-height:360px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; }
+figure.picture { margin:6px 0 14px; max-width:min(100%,720px); }
+figure.picture img { max-width:100%; height:auto; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
+figure.picture figcaption { margin-top:4px; color:var(--muted); font-size:12px; }
+figure.picture figcaption .onDisk { display:block; font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
 details.evidence { margin:6px 0 18px; padding:8px 12px; background:var(--panel); border:1px solid var(--line); border-radius:8px; }
 details.evidence > summary { cursor:pointer; color:var(--muted); font-size:13px; }
 details.evidence .shots { display:flex; flex-wrap:wrap; gap:14px; margin-top:12px; }
@@ -317,6 +352,11 @@ header .served code { font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,m
 figure.gone .gone-note, a.gone .gone-note { display:block; }
 figure.gone img, a.gone img { display:none; }
 a.frame.gone { display:block; max-width:min(100%,720px); }
+figure.picture { margin:8px 0 14px; max-width:min(100%,720px); }
+figure.picture img { width:auto; max-width:100%; max-height:420px; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
+details > summary { cursor:pointer; }
+details:not(.session):not(.evidence) { margin:4px 0 18px; padding:6px 12px; border:1px solid var(--line); border-radius:8px; background:var(--panel); }
+details:not(.session):not(.evidence) > summary { color:var(--muted); font-size:13px; }
 details.evidence figcaption { margin-top:4px; color:var(--muted); font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
 `;
 /**
@@ -366,6 +406,19 @@ function exitWatch(savedFile) {
         "  });\n" +
         "})();</script>");
 }
+/** The header's links: the report's parts it holds, then the steps. */
+function navLinks(markdown) {
+    const has = (heading) => markdown.split("\n").includes(`## ${heading}`);
+    return [
+        has("In plain words")
+            ? `<a href="#plain" data-testid="report-plain-link">In plain words</a>`
+            : `<a href="#report" data-testid="report-top-link">Report</a>`,
+        has("Technical detail") ? `<a href="#technical" data-testid="report-technical-link">Technical detail</a>` : "",
+        `<a href="#steps" data-testid="report-steps-link">Steps</a>`,
+    ]
+        .filter(Boolean)
+        .join("");
+}
 /** The whole document: one file, no external assets, opens from the file system. */
 export function buildReplayHtml(input) {
     const framed = input.sessions.some((s) => s.steps.some((x) => x.frame));
@@ -385,7 +438,7 @@ export function buildReplayHtml(input) {
   <h1>SceneScout run</h1>
   <span class="meta">${escapeHtml(input.project)} · written ${escapeHtml(stamp(input.at))}${input.version ? ` · v${escapeHtml(input.version)}` : ""}</span>
   ${savedAt ? `<p class="served">This page is served by the engine and goes when it does. The copy that stays is <code>${escapeHtml(savedAt)}/report.html</code>, beside the frames it shows.</p>` : ""}
-  <nav><a href="#report">Report</a><a href="#steps">Steps</a></nav>
+  <nav>${navLinks(input.markdown)}</nav>
 </header>
 ${savedAt
         ? `<div id="gone-bar" role="alert" data-testid="run-engine-gone" hidden>