tapline-host 1.4.0 → 1.5.0

package/dist/journeyreport.js

@@ -0,0 +1,664 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { jpegOf, markBox, markRing, readPixels } from "./images.js";
+import { GIF_MAX_BYTES, encodeJourneyGif } from "./journeygif.js";
+import { formatDuration, personaWords, summaryLine, summaryNotes } from "./journey.js";
+/**
+ * The journey's visual report (AGENT-TOOLS 1.12 §17.5): the frames kept after each counted step, the findings, and
+ * the folder written at `stop`: `report.md`, `report.html`, `frames/`, `findings/`, `journey.gif`, `key-1.jpg`,
+ * `key-2.jpg`. Pictures stay in files; only the two key pictures reach the agent.
+ */
+export const FRAME_WIDTH = 360;
+/** The report lists this many findings at most (the worst first) and says how many more there were; it never blocks `stop`. */
+export const MAX_FINDINGS = 100;
+/** `ux_check` findings kept (each with a picture) while the journey runs. */
+const MAX_SEEN = 300;
+const FRAME_QUALITY = 0.7;
+/** The screen's elements as one hash: texts, values, positions and the route, not refs. */
+export function screenSignature(elements, route, alerts) {
+    const hash = createHash("sha1");
+    hash.update(JSON.stringify([route, alerts, elements.map((e) => [e.role ?? "", e.text ?? "", e.label ?? "", typeof e.value === "string" || typeof e.value === "number" || typeof e.value === "boolean" ? e.value : "", e.frame ? [Math.round(e.frame.x), Math.round(e.frame.y), Math.round(e.frame.width), Math.round(e.frame.height)] : null])]));
+    return hash.digest("hex");
+}
+export class JourneyRecorder {
+    folder;
+    source;
+    clock;
+    frames = [];
+    seen = [];
+    /** Skipped frames: the list hadn't changed and nothing animated. */
+    skipped = 0;
+    /** Frames not taken because the journey's app was not connected and in front, by where it was. */
+    away = new Map();
+    actions = new Map();
+    queue = Promise.resolve();
+    lastSignature;
+    uxCount = 0;
+    /** Times the app's photo picker was skipped (`media` with `picker`) during the journey. */
+    pickerSkips = 0;
+    pickerPictures = 0;
+    constructor(folder, source, clock) {
+        this.folder = folder;
+        this.source = source;
+        this.clock = clock;
+        mkdirSync(join(folder, "frames"), { recursive: true });
+    }
+    get name() {
+        return this.folder.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "journey";
+    }
+    /** Runs `work` after the ones before it: the pictures come in the order of the steps. */
+    later(work) {
+        const next = this.queue.then(work, work);
+        this.queue = next.catch(() => undefined);
+        return next.catch(() => undefined);
+    }
+    /**
+     * Keeps a small picture of the screen after a step. Skipped when the element list is what it was and nothing
+     * animates (AGENTS.md: don't look twice). Never fails the step.
+     */
+    frame(step, screen, touch, animating) {
+        return this.later(async () => {
+            const where = this.source.where();
+            if (where !== "front") {
+                this.away.set(where, (this.away.get(where) ?? 0) + 1);
+                return;
+            }
+            const peek = await this.source.peek();
+            // A touch is kept even when the screen did not change: the report shows where it landed.
+            if (peek !== undefined && peek.signature === this.lastSignature && !animating && touch === undefined) {
+                this.skipped++;
+                return;
+            }
+            const shot = await this.source.shot(FRAME_WIDTH, FRAME_QUALITY);
+            if (shot === undefined)
+                return;
+            const n = this.frames.length + 1;
+            const file = `frames/${String(n).padStart(3, "0")}.jpg`;
+            writeFileSync(join(this.folder, file), Buffer.from(shot.data, "base64"));
+            const size = peek?.screen;
+            const share = (x, w, extent) => [x / extent, w / extent];
+            const record = { n, step, file, at: this.clock(), screen, signature: peek?.signature ?? "" };
+            if (touch !== undefined && size !== undefined && size.w > 0 && size.h > 0) {
+                if (touch.point !== undefined)
+                    record.tap = { x: touch.point.x / size.w, y: touch.point.y / size.h };
+                if (touch.frame !== undefined) {
+                    const [x, w] = share(touch.frame.x, touch.frame.width, size.w);
+                    const [y, h] = share(touch.frame.y, touch.frame.height, size.h);
+                    record.box = { x, y, w, h };
+                    record.tap ??= { x: x + w / 2, y: y + h / 2 };
+                }
+            }
+            this.frames.push(record);
+            this.lastSignature = peek?.signature;
+        });
+    }
+    /** The action labels of the screens seen before `current`, for `ux_check`'s naming check. */
+    earlier(current) {
+        const out = [];
+        for (const [screen, list] of this.actions)
+            if (screen !== current)
+                out.push(...list);
+        return out;
+    }
+    /** A `ux_check` was made: keep its actions, and a picture per finding with the element boxed in red. */
+    uxSeen(screen, title, actions, findings) {
+        if (this.source.where() !== "front")
+            return Promise.resolve();
+        if (screen !== undefined)
+            this.actions.set(screen, actions);
+        const room = Math.max(0, MAX_SEEN - this.seen.length);
+        const fresh = findings
+            .filter((f) => !this.seen.some((s) => s.screen === screen && s.kind === f.kind && s.problem === f.problem && s.ref === f.ref))
+            .slice(0, room);
+        const mine = fresh.map((f) => {
+            const { frame: _frame, ...summary } = f;
+            return { ...summary, screen, title };
+        });
+        this.seen.push(...mine);
+        if (fresh.length === 0)
+            return Promise.resolve();
+        const k = ++this.uxCount;
+        return this.later(async () => {
+            const [peek, shot] = await Promise.all([this.source.peek(), this.source.shot(FRAME_WIDTH, FRAME_QUALITY)]);
+            if (shot === undefined)
+                return;
+            const pixels = readPixels(shot);
+            mkdirSync(join(this.folder, "findings"), { recursive: true });
+            for (const [i, f] of fresh.entries()) {
+                const target = mine[i];
+                const size = peek?.screen;
+                if (target === undefined)
+                    continue;
+                const marked = f.frame !== undefined && size !== undefined && size.w > 0 && size.h > 0
+                    ? markBox(pixels, { x: f.frame.x / size.w, y: f.frame.y / size.h, w: f.frame.width / size.w, h: f.frame.height / size.h })
+                    : pixels;
+                const file = `findings/ux-${k}-${i + 1}.jpg`;
+                writeFileSync(join(this.folder, file), Buffer.from(jpegOf(marked).data, "base64"));
+                target.shot = file;
+            }
+        });
+    }
+    /** Everything asked for is on disk. */
+    done() {
+        return this.queue;
+    }
+}
+/**
+ * Simple rules, written in the report's footer. A `ux_check` kind not named here is low.
+ */
+export const SEVERITY_RULES = [
+    "High: the goal wasn't reached; the app crashed or lost its connection; a stress moment wasn't survived; a screen leaves the user with no next step (an error or empty state with nothing to tap, or no way back).",
+    "Medium: something blocked or misled the user (a touch a user couldn't make, an error, a wrong turn, more taps than a house rule allows, no clear main action, an icon-only button with no name, cut-off text, too many choices).",
+    "Low: polish (contrast, small tap areas, thumb reach, the same action named differently, hesitation).",
+];
+const UX_SEVERITY = {
+    dead_end: "high",
+    way_back: "high",
+    main_action: "medium",
+    icon_only: "medium",
+    cut_off_text: "medium",
+    choices: "medium",
+    contrast: "low",
+    target_size: "low",
+    thumb_reach: "low",
+    naming: "low",
+};
+const ORDER = { high: 0, medium: 1, low: 2 };
+function stepWords(step) {
+    const target = step.target !== undefined ? ` ${step.target}` : "";
+    return `${step.tool}${target}`;
+}
+/** The findings of a finished journey, worst first. `steps` pictures are filled in by `markSteps`. */
+export function buildFindings(state, seen, maxTaps) {
+    const out = [];
+    const lastScreen = state.currentScreen;
+    if (state.reached === false) {
+        out.push({
+            severity: "high",
+            kind: "goal_not_reached",
+            title: `The goal wasn't reached${state.why !== undefined ? `: ${state.why}` : "."}`,
+            screen: lastScreen,
+            basis: "journey result",
+        });
+    }
+    for (const stress of state.stress) {
+        if (stress.survived === false) {
+            out.push({ severity: "high", kind: "stress", title: stress.said.replace(/^Stress: /, ""), screen: state.steps[stress.afterStep - 1]?.screen ?? lastScreen, basis: "stress moment" });
+        }
+    }
+    const once = new Set();
+    for (const step of state.steps) {
+        for (const flag of step.flags ?? []) {
+            const key = `${flag}|${step.tool}|${step.target ?? ""}|${step.screen ?? ""}`;
+            if (once.has(key))
+                continue;
+            once.add(key);
+            const at = `${stepWords(step)}: ${step.said}`;
+            if (flag === "crash")
+                out.push({ severity: "high", kind: "crash", title: `The app crashed or lost its connection at ${at}`, screen: step.screen, basis: `measured, step ${step.n}` });
+            else if (flag === "error")
+                out.push({ severity: "medium", kind: "error", title: `An error at ${at}`, screen: step.screen, basis: `measured, step ${step.n}` });
+            else if (flag === "dead_end")
+                out.push({ severity: "medium", kind: "dead_end_touch", title: `A touch a user couldn't make at ${at}`, screen: step.screen, basis: `measured, step ${step.n}` });
+            else
+                out.push({ severity: "medium", kind: "wrong_turn", title: `A wrong turn: this screen was left by going back with nothing done on it (${at})`, screen: step.screen, basis: `measured, step ${step.n}` });
+        }
+    }
+    if (maxTaps !== undefined && state.reached === true && state.tapsToGoal !== null && state.tapsToGoal > maxTaps) {
+        out.push({
+            severity: "medium",
+            kind: "max_taps_to_goal",
+            title: `The goal took ${state.tapsToGoal} taps; the house rule allows ${maxTaps}.`,
+            screen: lastScreen,
+            basis: `house rule: max_taps_to_goal ${maxTaps}`,
+        });
+    }
+    for (const f of seen) {
+        const shot = f.shot;
+        out.push({
+            severity: UX_SEVERITY[f.kind] ?? "low",
+            kind: f.kind,
+            title: f.problem,
+            screen: f.screen,
+            basis: f.basis,
+            ...(shot !== undefined ? { shot } : {}),
+        });
+    }
+    if (state.measures.hesitations >= 2) {
+        out.push({ severity: "low", kind: "hesitation", title: `${state.measures.hesitations} hesitations: reads in a row with no action, a sign the screen didn't say what to do.`, screen: lastScreen, basis: "measured" });
+    }
+    return out.map((f, i) => ({ f, i })).sort((a, b) => ORDER[a.f.severity] - ORDER[b.f.severity] || a.i - b.i).map(({ f }) => f);
+}
+export function countFindings(findings) {
+    const counts = { high: 0, medium: 0, low: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    return counts;
+}
+/** `Findings: 2 high, 3 medium, 1 low.` or `Findings: none.` */
+export function findingsLine(counts) {
+    const parts = ["high", "medium", "low"].filter((s) => counts[s] > 0).map((s) => `${counts[s]} ${s}`);
+    return `Findings: ${parts.length > 0 ? parts.join(", ") : "none"}.`;
+}
+// ---- the folder ---------------------------------------------------------------
+/** `2026-11-12-1530-log-breakfast-by-scanning-its-barcode`, in the computer's local time. */
+export function reportFolderName(goal, at) {
+    const d = new Date(at);
+    const two = (n) => String(n).padStart(2, "0");
+    const stamp = `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}-${two(d.getHours())}${two(d.getMinutes())}`;
+    const slug = goal
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return `${stamp}-${slug === "" ? "journey" : slug}`;
+}
+/** A folder name that doesn't exist yet in `root` (`-2`, `-3` when the same goal ran in the same minute). */
+/** How many journey reports a host keeps in its journeys folder (1.5 review, finding 6). */
+export const JOURNEYS_KEPT = 20;
+/**
+ * Keeps the newest `keep` report folders in `root` (by when they were last changed) and removes the rest. Only folders
+ * that hold a report or frames (what a journey writes) are counted or removed; anything else in `root` is left alone.
+ */
+export function pruneJourneys(root, keep) {
+    let removed = 0;
+    try {
+        const reports = readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(root, entry.name))
+            .filter((dir) => existsSync(join(dir, "report.md")) || existsSync(join(dir, "frames")))
+            .map((dir) => ({ dir, at: statSync(dir).mtimeMs }))
+            .sort((a, b) => b.at - a.at);
+        for (const old of reports.slice(Math.max(0, keep))) {
+            try {
+                rmSync(old.dir, { recursive: true, force: true });
+                removed++;
+            }
+            catch {
+                // in use: left for next time
+            }
+        }
+    }
+    catch {
+        // no folder yet, or it can't be read: nothing to prune
+    }
+    return removed;
+}
+export function freshFolder(root, goal, at) {
+    const base = reportFolderName(goal, at);
+    let name = base;
+    for (let n = 2; existsSync(join(root, name)); n++)
+        name = `${base}-${n}`;
+    return join(root, name);
+}
+function writeJpegFile(path, data) {
+    writeFileSync(path, Buffer.from(data, "base64"));
+}
+function readShot(folder, file) {
+    try {
+        return { mime: "image/jpeg", data: readFileSync(join(folder, file)).toString("base64") };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The frame a step's finding shows: the one made after that step, else the nearest before it. */
+function frameForStep(frames, step) {
+    let found;
+    for (const f of frames)
+        if (f.step <= step)
+            found = f;
+    return found ?? frames[0];
+}
+/** Pictures for the findings that came from steps: the frame, with a red box at the touched element where there is one. */
+function markSteps(folder, state, findings, frames) {
+    mkdirSync(join(folder, "findings"), { recursive: true });
+    findings.forEach((finding, i) => {
+        if (finding.shot !== undefined)
+            return;
+        const stepNumber = /step (\d+)$/.exec(finding.basis)?.[1];
+        const step = stepNumber !== undefined ? Number(stepNumber) : finding.kind === "goal_not_reached" || finding.kind === "max_taps_to_goal" ? state.steps.length : undefined;
+        const stressStep = finding.kind === "stress" ? state.stress.find((s) => finding.title.startsWith(s.said.replace(/^Stress: /, "")))?.afterStep : undefined;
+        const at = step ?? stressStep;
+        if (at === undefined)
+            return;
+        const frame = frameForStep(frames, at);
+        if (frame === undefined)
+            return;
+        const shot = readShot(folder, frame.file);
+        if (shot === undefined)
+            return;
+        const file = `findings/${String(i + 1).padStart(2, "0")}-${finding.kind}.jpg`;
+        let pixels = readPixels(shot);
+        if (frame.step === at && frame.box !== undefined)
+            pixels = markBox(pixels, frame.box);
+        else if (frame.step === at && frame.tap !== undefined)
+            pixels = markBox(pixels, { x: frame.tap.x - 0.06, y: frame.tap.y - 0.03, w: 0.12, h: 0.06 });
+        writeJpegFile(join(folder, file), jpegOf(pixels).data);
+        finding.shot = file;
+    });
+}
+/** At most this many pictures are decoded for the GIF (each is about 1 MB as pixels): 1.5 review, finding 6. */
+export const GIF_MAX_SOURCE_FRAMES = 150;
+/**
+ * The frames the GIF is made of, at most `max`: every tap and every first picture of a screen stays (they tell the
+ * story); the other, still pictures are thinned evenly. Chosen before anything is decoded.
+ */
+export function framesForGif(frames, max = GIF_MAX_SOURCE_FRAMES) {
+    if (frames.length <= max)
+        return [...frames];
+    const keep = new Set();
+    frames.forEach((frame, i) => {
+        const before = frames[i - 1];
+        if (i === 0 || i === frames.length - 1 || frame.tap !== undefined || before === undefined || before.screen !== frame.screen)
+            keep.add(i);
+    });
+    const rest = frames.map((_, i) => i).filter((i) => !keep.has(i));
+    const room = Math.max(0, max - keep.size);
+    if (room > 0 && rest.length > 0) {
+        const every = rest.length / room;
+        for (let k = 0; k < room; k++) {
+            const pick = rest[Math.floor(k * every)];
+            if (pick !== undefined)
+                keep.add(pick);
+        }
+    }
+    const chosen = [...keep].sort((a, b) => a - b).map((i) => frames[i]).filter((f) => f !== undefined);
+    // Taps and screen changes alone can be over the limit in a very long journey: then those are thinned evenly too.
+    if (chosen.length <= max)
+        return chosen;
+    // The first and the last stay (the start and the result); the ones between are sampled.
+    const middle = chosen.slice(1, -1);
+    const room2 = Math.max(0, max - 2);
+    const step = middle.length / Math.max(1, room2);
+    const sampled = Array.from({ length: Math.min(room2, middle.length) }, (_, k) => middle[Math.floor(k * step)]);
+    return [chosen[0], ...sampled, chosen[chosen.length - 1]].filter((f) => f !== undefined);
+}
+function buildGif(folder, all, maxBytes) {
+    const frames = framesForGif(all);
+    const gifFrames = [];
+    for (const frame of frames) {
+        const shot = readShot(folder, frame.file);
+        if (shot === undefined)
+            continue;
+        gifFrames.push({ pixels: readPixels(shot), at: frame.at, ...(frame.tap !== undefined ? { tap: frame.tap } : {}) });
+    }
+    if (gifFrames.length === 0)
+        return null;
+    const gif = encodeJourneyGif(gifFrames, { maxBytes });
+    writeFileSync(join(folder, "journey.gif"), gif.bytes);
+    return { frames: gif.frames, bytes: gif.bytes.length, dropped: gif.dropped + (all.length - frames.length) };
+}
+// ---- words --------------------------------------------------------------------
+function escapeHtml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** Text the app controls (a label, a route), made safe to sit in report.md: no link, image or tag can be written by it. */
+function escapeMarkdown(value) {
+    return value.replace(/\s*[\r\n]+\s*/g, " ").replace(/[\\`[\]<>!]/g, (c) => `\\${c}`);
+}
+function screenName(state, n) {
+    if (n === undefined)
+        return "no screen";
+    const screen = state.screens[n - 1];
+    if (screen === undefined)
+        return `screen ${n}`;
+    return `screen ${n}${screen.route.length > 0 ? ` (${screen.route.join(" › ")})` : ""}`;
+}
+function conditionWords(state) {
+    const parts = Object.entries(state.conditions).map(([k, v]) => `${k.replace("_", " ")} ${String(v)}`);
+    return parts.length > 0 ? parts.join(", ") : "none";
+}
+function resultWords(state) {
+    const base = state.reached === true ? "Reached" : "Not reached";
+    return state.why !== undefined ? `${base}: ${state.why}` : base;
+}
+function numbersTable(state) {
+    const m = state.measures;
+    const elapsed = (state.endedAt ?? state.startedAt) - state.startedAt;
+    return [
+        ["Taps", String(m.taps)],
+        ["Taps to the goal", state.tapsToGoal === null ? "not reached" : String(state.tapsToGoal)],
+        ["Typing", String(m.typing)],
+        ["Scrolls", String(m.scrolls)],
+        ["Screens entered", String(m.screensEntered)],
+        ["Time", `${formatDuration(elapsed)} (${formatDuration(m.waitMs)} waiting)`],
+        ["Wrong turns", String(m.wrongTurns)],
+        ["Dead ends", String(m.deadEnds)],
+        ["Errors hit", String(m.errors)],
+        ["Hesitations", String(m.hesitations)],
+    ];
+}
+function usedLines(state, rec) {
+    const lines = [];
+    if (state.shortcuts.length > 0)
+        lines.push(`Shortcuts used (a person doesn't have these): ${state.shortcuts.map((s) => `${s.tool} ${JSON.stringify(s.what)}`).join(", ")}.`);
+    if (rec.pickerSkips > 0)
+        lines.push(`Photo picker skipped ${rec.pickerSkips === 1 ? "once" : `${rec.pickerSkips} times`} (${rec.pickerPictures} picture${rec.pickerPictures === 1 ? "" : "s"} handed over without the OS picker): picker skipped.`);
+    if (state.eyesSwitchedAt !== undefined)
+        lines.push("Eyes: agent. The agent turned a user's eyes off during the journey (it saw ids, labels and everything in the tree and could jump), so the numbers after that are not a user's.");
+    return lines;
+}
+/**
+ * The report's own folder, in whatever slash style a step's text carries it, replaced by `<report>`: an export
+ * must not publish this computer's user name and folders.
+ */
+export function scrubFolder(text, folder) {
+    const base = folder.replace(/[\\/]+$/, "");
+    if (base === "")
+        return text;
+    const slashes = base.replace(/\\/g, "/");
+    const forms = [base, slashes, slashes.replace(/\//g, "\\"), slashes.replace(/\//g, "\\\\")];
+    // The folder also as it sits after HTML or Markdown escaping, so it goes from report.html and report.md alike.
+    const escaped = forms.flatMap((f) => [escapeHtml(f), escapeMarkdown(f)]);
+    const unique = [...new Set([...forms, ...escaped])].sort((a, b) => b.length - a.length);
+    const pattern = new RegExp(unique.map((f) => f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"), "gi");
+    return text.replace(pattern, "<report>");
+}
+function pathScreens(ctx) {
+    return ctx.state.screens.map((screen) => ({
+        n: screen.n,
+        title: screenName(ctx.state, screen.n),
+        ...(ctx.rec.frames.find((f) => f.screen === screen.n)?.file !== undefined ? { picture: ctx.rec.frames.find((f) => f.screen === screen.n)?.file } : {}),
+        steps: ctx.state.steps.filter((s) => s.screen === screen.n),
+    }));
+}
+/** One step as a line; `esc` makes the app's words safe for the format (Markdown escaping, none for HTML that escapes later). */
+function stepLine(step, esc = (v) => v) {
+    return `${step.n}. ${esc(stepWords(step))}${step.ok ? "" : ` (failed${step.code !== undefined ? `: ${esc(step.code)}` : ""})`} — ${esc(step.said)}`;
+}
+function rulesLines(ctx) {
+    const out = [];
+    if (ctx.maxTaps !== undefined)
+        out.push(`max_taps_to_goal: ${ctx.maxTaps}`);
+    for (const rule of ctx.textRules)
+        out.push(`${rule} (judged by the agent)`);
+    return out;
+}
+export function renderMarkdown(ctx) {
+    const { state } = ctx;
+    const lines = [`# Journey report: ${state.goal}`, "", summaryLine(state), findingsLine(ctx.counts), ""];
+    lines.push(`- Goal: ${state.goal}`, `- Persona: ${personaWords(state)}`, `- Conditions: ${conditionWords(state)}`, `- Result: ${resultWords(state)}`, "");
+    if (ctx.gif !== null)
+        lines.push("![The journey](journey.gif)", "");
+    lines.push("## Numbers", "", "| Measure | Value |", "| --- | --- |", ...numbersTable(state).map(([k, v]) => `| ${k} | ${v} |`), "");
+    lines.push("## The path", "");
+    const screens = pathScreens(ctx);
+    if (screens.length === 0)
+        lines.push("No screen was listed during the journey.", "");
+    for (const s of screens) {
+        lines.push(`### ${escapeMarkdown(s.title)}`, "");
+        if (s.picture !== undefined)
+            lines.push(`![${escapeMarkdown(s.title)}](${s.picture})`, "");
+        else
+            lines.push("(no picture was kept for this screen)", "");
+        for (const step of s.steps)
+            lines.push(`- ${stepLine(step, escapeMarkdown)}`);
+        if (s.steps.length > 0)
+            lines.push("");
+    }
+    lines.push("## Findings", "");
+    if (ctx.findings.length === 0)
+        lines.push("None.", "");
+    if (ctx.omitted > 0)
+        lines.push(`Showing the worst ${ctx.findings.length}; ${ctx.omitted} more findings are not listed.`, "");
+    ctx.findings.forEach((f, i) => {
+        lines.push(`### ${i + 1}. [${f.severity}] ${f.kind}`, "", escapeMarkdown(f.title), "", `- Screen: ${escapeMarkdown(screenName(state, f.screen))}`, `- Basis: ${f.basis}`, "");
+        if (f.shot !== undefined)
+            lines.push(`![Finding ${i + 1}](${f.shot})`, "");
+    });
+    if (state.stress.length > 0) {
+        lines.push("## Stress moments", "", ...state.stress.map((s) => `- ${s.said}`), "");
+    }
+    const used = usedLines(state, ctx.rec);
+    lines.push("## Shortcuts and eyes", "", ...(used.length > 0 ? used.map((l) => `- ${l}`) : ["- None: no shortcut was used, and the journey stayed in a user's eyes."]), "");
+    const notes = summaryNotes(state).filter((l) => !used.includes(l) && !l.startsWith("Eyes:") && !l.startsWith("Shortcuts used"));
+    if (notes.length > 0)
+        lines.push("## Notes", "", ...notes.map((l) => `- ${l}`), "");
+    const rules = rulesLines(ctx);
+    if (rules.length > 0)
+        lines.push("## House rules", "", ...rules.map((r) => `- ${r}`), "");
+    lines.push("---", "", "How severity is chosen:", "", ...SEVERITY_RULES.map((r) => `- ${r}`), "");
+    return lines.join("\n");
+}
+export function renderHtml(ctx) {
+    const { state } = ctx;
+    const e = escapeHtml;
+    const img = (src, alt) => `<img src="${e(src)}" alt="${e(alt)}" loading="lazy">`;
+    const body = [`<h1>Journey report: ${e(state.goal)}</h1>`, `<p class="sum">${e(summaryLine(state))}<br>${e(findingsLine(ctx.counts))}</p>`];
+    body.push(`<ul><li>Goal: ${e(state.goal)}</li><li>Persona: ${e(personaWords(state))}</li><li>Conditions: ${e(conditionWords(state))}</li><li>Result: ${e(resultWords(state))}</li></ul>`);
+    if (ctx.gif !== null)
+        body.push(`<p>${img("journey.gif", "The journey")}</p>`);
+    body.push("<h2>Numbers</h2>", `<table>${numbersTable(state).map(([k, v]) => `<tr><th>${e(k)}</th><td>${e(v)}</td></tr>`).join("")}</table>`);
+    body.push("<h2>The path</h2>");
+    const screens = pathScreens(ctx);
+    if (screens.length === 0)
+        body.push("<p>No screen was listed during the journey.</p>");
+    for (const s of screens) {
+        body.push(`<h3>${e(s.title)}</h3>`);
+        body.push(s.picture !== undefined ? `<p>${img(s.picture, s.title)}</p>` : "<p>(no picture was kept for this screen)</p>");
+        if (s.steps.length > 0)
+            body.push(`<ul>${s.steps.map((step) => `<li>${e(stepLine(step))}</li>`).join("")}</ul>`);
+    }
+    body.push("<h2>Findings</h2>");
+    if (ctx.findings.length === 0)
+        body.push("<p>None.</p>");
+    if (ctx.omitted > 0)
+        body.push(`<p>Showing the worst ${ctx.findings.length}; ${ctx.omitted} more findings are not listed.</p>`);
+    ctx.findings.forEach((f, i) => {
+        body.push(`<section class="finding ${f.severity}"><h3>${i + 1}. <span class="sev">${f.severity}</span> ${e(f.kind)}</h3><p>${e(f.title)}</p><p class="meta">Screen: ${e(screenName(state, f.screen))}<br>Basis: ${e(f.basis)}</p>${f.shot !== undefined ? `<p>${img(f.shot, `Finding ${i + 1}`)}</p>` : ""}</section>`);
+    });
+    if (state.stress.length > 0)
+        body.push("<h2>Stress moments</h2>", `<ul>${state.stress.map((s) => `<li>${e(s.said)}</li>`).join("")}</ul>`);
+    const used = usedLines(state, ctx.rec);
+    body.push("<h2>Shortcuts and eyes</h2>", `<ul>${(used.length > 0 ? used : ["None: no shortcut was used, and the journey stayed in a user's eyes."]).map((l) => `<li>${e(l)}</li>`).join("")}</ul>`);
+    const rules = rulesLines(ctx);
+    if (rules.length > 0)
+        body.push("<h2>House rules</h2>", `<ul>${rules.map((r) => `<li>${e(r)}</li>`).join("")}</ul>`);
+    body.push(`<footer><p>How severity is chosen:</p><ul>${SEVERITY_RULES.map((r) => `<li>${e(r)}</li>`).join("")}</ul></footer>`);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Journey report: ${e(state.goal)}</title>
+<style>
+:root{color-scheme:light dark;--bg:#fff;--fg:#1c1c1e;--mute:#6b6b70;--line:#d8d8dc;--high:#c4261d;--medium:#b7791f;--low:#3b6ea5}
+@media (prefers-color-scheme:dark){:root{--bg:#161618;--fg:#f2f2f4;--mute:#a0a0a8;--line:#38383c;--high:#ff6b62;--medium:#e5b04a;--low:#7ab0e8}}
+body{background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,sans-serif;max-width:46rem;margin:0 auto;padding:1rem 16px 3rem}
+img{max-width:100%;width:360px;height:auto;border:1px solid var(--line);border-radius:8px}
+table{border-collapse:collapse}th,td{text-align:left;padding:.2rem .8rem .2rem 0;border-bottom:1px solid var(--line)}
+.sum{font-weight:600}.meta,footer{color:var(--mute);font-size:.9rem}
+.finding{border-left:4px solid var(--line);padding-left:.8rem;margin:1rem 0}
+.finding.high{border-color:var(--high)}.finding.medium{border-color:var(--medium)}.finding.low{border-color:var(--low)}
+.finding.high .sev{color:var(--high)}.finding.medium .sev{color:var(--medium)}.finding.low .sev{color:var(--low)}
+.sev{text-transform:uppercase;font-size:.8em;letter-spacing:.04em}
+</style>
+</head>
+<body>
+${body.join("\n")}
+</body>
+</html>
+`;
+}
+/** Writes the report folder: waits for the pictures asked for, then the findings, GIF, key pictures, `report.md` and `report.html`. */
+export async function writeReport(options) {
+    const { state, rec } = options;
+    const notes = [];
+    await rec.done();
+    const folder = rec.folder;
+    mkdirSync(join(folder, "findings"), { recursive: true });
+    const every = buildFindings(state, rec.seen, options.maxTaps);
+    // The report lists the worst 100; the counts are of all of them.
+    const findings = every.slice(0, MAX_FINDINGS);
+    const omitted = every.length - findings.length;
+    markSteps(folder, state, findings, rec.frames);
+    const counts = countFindings(every);
+    for (const [where, n] of rec.away)
+        notes.push(`Note: ${n} frame${n === 1 ? " was" : "s were"} not kept because the app was ${where === "background" ? "in the background" : where === "disconnected" ? "not connected" : "not the journey's app"}.`);
+    let gif = null;
+    try {
+        gif = buildGif(folder, rec.frames, options.gifMaxBytes ?? GIF_MAX_BYTES);
+    }
+    catch (error) {
+        notes.push(`Note: the GIF could not be made: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (rec.frames.length === 0)
+        notes.push("Note: no pictures were kept (the app can't take screenshots, or none came back); add react-native-view-shot.");
+    const keys = [];
+    const last = rec.frames[rec.frames.length - 1];
+    if (last !== undefined) {
+        // Where the goal was reached, or where the journey stopped: with the last tap ringed, as the GIF shows it.
+        const shot = readShot(folder, last.file);
+        if (shot !== undefined) {
+            const pixels = readPixels(shot);
+            const marked = last.tap !== undefined ? markRing(pixels, last.tap) : pixels;
+            writeJpegFile(join(folder, "key-1.jpg"), jpegOf(marked).data);
+            keys.push("key-1.jpg");
+        }
+    }
+    const worst = findings.find((f) => f.shot !== undefined);
+    if (worst?.shot !== undefined) {
+        copyFileSync(join(folder, worst.shot), join(folder, "key-2.jpg"));
+        keys.push("key-2.jpg");
+    }
+    const ctx = { state, rec, findings, counts, omitted, gif, maxTaps: options.maxTaps, textRules: options.textRules ?? [] };
+    const markdown = scrubFolder(renderMarkdown(ctx), folder);
+    writeFileSync(join(folder, "report.md"), markdown, "utf8");
+    writeFileSync(join(folder, "report.html"), scrubFolder(renderHtml(ctx), folder), "utf8");
+    // An export uploads the report, its GIF and the pictures the report uses, not every raw frame.
+    // Only the report's own pictures: app text in the report can't name another file (1.5 review, finding 7).
+    const used = [...markdown.matchAll(/!\[[^\]]*\]\(([^)\s]+)\)/g)]
+        .map((m) => m[1] ?? "")
+        .filter((p) => isReportPicture(p) && existsSync(join(folder, p)));
+    const exportFiles = [...new Set(["report.md", "report.html", ...used])].sort();
+    const firstPicture = used.find((p) => p.startsWith("frames/"));
+    return { folder, name: rec.name, findings, counts, files: listFiles(folder), exportFiles, firstPicture, omitted, gif, keys, notes };
+}
+/** A picture inside the report folder: a relative path of plain names, no `..`, ending .png, .jpg or .gif. */
+export function isReportPicture(path) {
+    return /^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*\.(?:png|jpe?g|gif)$/.test(path) && !path.split("/").includes("..");
+}
+function listFiles(root, rel = "") {
+    const out = [];
+    for (const entry of readdirSyncSafe(join(root, rel))) {
+        const path = rel === "" ? entry.name : `${rel}/${entry.name}`;
+        if (entry.isDirectory)
+            out.push(...listFiles(root, path));
+        else
+            out.push(path);
+    }
+    return out.sort();
+}
+function readdirSyncSafe(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true }).map((d) => ({ name: d.name, isDirectory: d.isDirectory() }));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=journeyreport.js.map