@webship.co/workspace 0.0.0-stage → 1.0.0-beta1

package/speech.js

@@ -0,0 +1,297 @@
+/**
+ * The assistant panel's voice settings, resolved into the objects deep-chat expects.
+ *
+ * The page used to be handed a flat bag of values and rebuild deep-chat's `speechToText` /
+ * `textToSpeech` objects itself, in a browser file nothing can require. That put the one part with
+ * real rules — which keys may be absent, which must never be empty — where it could only be checked
+ * by reading the source. The rules live here instead, the server sends the finished objects, and the
+ * page assigns them.
+ *
+ * The rules are not decoration. deep-chat silently ignores a key it does not recognise and silently
+ * ACCEPTS one it does, so both kinds of mistake are invisible at runtime:
+ *
+ *   - `commands` built with empty strings arms voice commands nobody asked for. A blank `submit`
+ *     phrase does not mean "no command"; it means a command that can trigger on almost anything.
+ *   - `commands.settings.substrings` defaults to TRUE in deep-chat, so "submit the form" fires a
+ *     `submit` command mid-sentence. It has to be turned off deliberately.
+ *   - `webSpeech: true` accepts the browser's language. A recogniser left on the wrong one does not
+ *     fail — it returns confident nonsense — so pinning it is the one setting that changes whether
+ *     dictation works at all in a second language.
+ *
+ * Azure is the other backend deep-chat supports and is deliberately not offered: it needs a
+ * subscription key and sends the audio to a third party. Everything here stays on the machine, for
+ * the same reason the RAG index is local.
+ */
+
+'use strict';
+
+/** Defaults, in one place, so the page and the resolver cannot disagree about them. */
+const DEFAULTS = {
+  // What the assistant is CALLED, and what its composer says when the box is empty.
+  name: 'AI Assistant',
+  placeholder: '',
+  voiceInput: true,
+  voiceOutput: true,
+  submitAfterSilence: 2500,
+  speechRate: 1,
+  speechPitch: 1,
+  speechVolume: 1,
+  interimResults: true,
+  stopAfterSubmit: true,
+  speechLanguage: 'en-US',
+  voiceName: '',
+  // The assistant's avatar, shown from the robot icon in its panel's header: the one it starts as, one
+  // of `avatars`, or `none` for no avatar and no icon.
+  avatar: 'druplicon',
+  // The avatars that can be picked in the panel (assistant-cast.js finds each in the avatars workspace).
+  avatars: ['druplicon'],
+  // Where the assistant keeps what the team teaches it, relative to the workspace root.
+  memory: 'core/workspace-app/.memory',
+  // The Claude Code agent the assistant runs as; `none` runs it without one.
+  agent: 'webship-workspace',
+};
+const AVATARS = ['druplicon', 'none'];
+
+/**
+ * The Workspace's default language, settings.yml `language:` (one of LANGUAGES, without `auto`): the
+ * language the assistant answers in, listens for and speaks. en-US when it is unset or not one we know.
+ */
+function workspaceLanguage(settings = {}) {
+  const v = String((settings && settings.language) || '').trim();
+  const known = LANGUAGES.find(([code]) => code !== 'auto' && code.toLowerCase() === v.toLowerCase());
+  return known ? known[0] : DEFAULTS.speechLanguage;
+}
+const languageName = (code) => (LANGUAGES.find(([c]) => c === code) || [code, code])[1];
+
+// The names in `assistant.avatars:`, each a plain machine name; the shipped list when there are none.
+const avatarList = (v) => {
+  const names = (Array.isArray(v) ? v : []).map((x) => String(x || '').trim().toLowerCase())
+    .filter((x, i, all) => /^[a-z0-9][a-z0-9_-]{0,62}$/.test(x) && x !== 'none' && all.indexOf(x) === i);
+  return names.length ? names : DEFAULTS.avatars;
+};
+const bool = (v, d) => (v === undefined || v === null ? d : v !== false && v !== 'false');
+const num = (v, d) => (Number.isFinite(Number(v)) ? Number(v) : d);
+const str = (v, d) => (typeof v === 'string' && v.trim() ? v.trim() : d);
+
+/**
+ * "Not set", spelled as a word.
+ *
+ * An empty value in settings.yml (`speech_language: ""`) is unreadable — it looks like a setting
+ * somebody forgot to finish rather than one deliberately left to the browser, and it renders in the
+ * settings form as a blank box with no clue what belongs there. So the file says `auto`, `default` or
+ * `off`, and they all resolve to the same nothing here.
+ */
+// `false` and `no` belong here as well as the obvious words: parse_yaml hands values back as
+// STRINGS, so `command_stop: false` arrives as "false" — which without this is a phrase, and the
+// microphone would sit there listening for someone to say the word "false".
+const UNSET = new Set(['auto', 'default', 'off', 'none', 'browser', 'false', 'no', '0', '']);
+const optional = (v) => {
+  const t = str(v, '');
+  return UNSET.has(t.toLowerCase()) ? '' : t;
+};
+
+/**
+ * The recogniser languages offered in the settings form.
+ *
+ * A short, deliberate list rather than the full BCP-47 registry: the browser accepts any tag, and a
+ * dropdown of nine hundred is worse than a text box. These are the ones this workspace is actually
+ * used in, with the Gulf and Levant Arabic variants — plus an empty
+ * first entry, because "follow the browser" is the right answer for most people and must stay
+ * reachable once the field is a select.
+ *
+ * A value that is not on the list is kept and shown as unknown rather than silently corrected: the
+ * settings file is the source of truth, and a form that quietly rewrites it is worse than one that
+ * admits it does not recognise a value.
+ */
+const LANGUAGES = [
+  ['auto', 'Follow the browser'],
+  ['en-US', 'English (United States)'],
+  ['en-GB', 'English (United Kingdom)'],
+  ['ar-JO', 'Arabic (Jordan)'],
+  ['ar-SA', 'Arabic (Saudi Arabia)'],
+  ['ar-AE', 'Arabic (United Arab Emirates)'],
+  ['ar-EG', 'Arabic (Egypt)'],
+  ['fr-FR', 'French (France)'],
+  ['de-DE', 'German (Germany)'],
+  ['es-ES', 'Spanish (Spain)'],
+  ['tr-TR', 'Turkish (Türkiye)'],
+];
+
+/**
+ * What the plain field microphones need — the small mic beside every text input, which is a separate
+ * implementation from deep-chat's and predates it.
+ *
+ * It has to be a separate shape because those mics are raw `SpeechRecognition`, not deep-chat: they
+ * take a `lang` string, not a `webSpeech` object. What matters is that both come from THIS module,
+ * so `speech_language` reaches all of them. Before this, 36 field mics on the settings page alone
+ * were pinned to `document.documentElement.lang` and ignored the setting entirely — which is the
+ * confident-nonsense failure again, on most of the microphones in the app.
+ */
+function fieldMicConfig(cfg) {
+  if (!cfg.voiceInput) return false;
+  return {
+    // Empty means "let the browser decide", which is what SpeechRecognition does with an unset lang.
+    lang: cfg.speechLanguage || '',
+    interimResults: cfg.interimResults !== false,
+  };
+}
+
+/**
+ * What a voice command setting means.
+ *
+ *   true / "true"   listen for the command's own word ("stop", "submit", …)
+ *   false / off     no command — and `off` must keep working, because that is what shipped
+ *   "any phrase"    listen for that instead, which is the only way to have one in another language
+ */
+function commandPhrase(value, word) {
+  if (value === true || value === 'true' || value === 'yes' || value === 'on') return word;
+  return optional(value);
+}
+/**
+ * What the assistant is called here, and what its composer says when empty.
+ *
+ * Two levels, because one dashboard runs many workspaces: `assistant:` in `settings.yml` is the
+ * default — the home page and every page that belongs to no workspace — and `assistant:` in
+ * `workspace.<name>.settings.yml` overrides it for that workspace's page and its backups page.
+ * A folder whose assistant answers for Penpot instances can say so; the rest inherit.
+ *
+ * **One rule, applied at each level: blank, or one of the unset words, means "not set here".** A
+ * workspace that says nothing takes the global value; a global that says nothing takes the shipped
+ * default. It is the same merge `presentation:` already does, and it is what lets every workspace
+ * file ship the keys with `default` in them — visible and editable in the settings form, without
+ * twenty-four copies of the name quietly pinning it against a change made in one place.
+ *
+ * What that rule costs, stated rather than discovered: a workspace cannot silence a placeholder the
+ * global has set, because "say nothing" is how it inherits. Set the placeholder per workspace
+ * instead of globally if one of them needs to be silent.
+ */
+function assistantIdentity(settings = {}, wsSettings = null) {
+  const global = (settings && settings.assistant) || {};
+  const own = (wsSettings && wsSettings.assistant) || {};
+  const level = (key) => optional(own[key]) || optional(global[key]);
+  return {
+    name: level('name') || DEFAULTS.name,
+    placeholder: level('placeholder') || DEFAULTS.placeholder,
+  };
+}
+
+/** The `assistant:` block of settings.yml, normalised. */
+function assistantSettings(settings = {}) {
+  const a = settings.assistant || {};
+  return {
+    voiceInput: bool(a.voice_input, DEFAULTS.voiceInput),
+    voiceOutput: bool(a.voice_output, DEFAULTS.voiceOutput),
+    // 0 means "never send for me": deep-chat wants the key absent for that, not zero.
+    submitAfterSilence: num(a.submit_after_silence, DEFAULTS.submitAfterSilence),
+    speechRate: num(a.speech_rate, DEFAULTS.speechRate),
+    speechPitch: num(a.speech_pitch, DEFAULTS.speechPitch),
+    speechVolume: num(a.speech_volume, DEFAULTS.speechVolume),
+    // en-US ships as the default rather than 'follow the browser': most dictation here is
+    // English, and a browser set to something else silently recognised the wrong language.
+    // `auto` is still one dropdown entry away for anyone who wants the browser's choice.
+    // Unset, it is the Workspace's own language (settings.yml `language:`), so one line sets both.
+    speechLanguage: a.speech_language === undefined
+      ? workspaceLanguage(settings)
+      : optional(a.speech_language),
+    voiceName: optional(a.voice_name),
+    avatars: avatarList(a.avatars),
+    avatar: a.avatar === 'none' ? 'none' : (avatarList(a.avatars).includes(String(a.avatar)) ? String(a.avatar) : avatarList(a.avatars)[0]),
+    agent: a.agent === undefined ? DEFAULTS.agent : (/^[a-z0-9][a-z0-9-]{0,62}$/.test(String(a.agent)) && String(a.agent) !== 'none' ? String(a.agent) : ''),
+    // A folder inside the workspace tree, never an absolute path or one that climbs out of it.
+    memory: typeof a.memory === 'string' && /^[\w.-]+(\/[\w.-]+)*$/.test(a.memory.trim()) && !/(^|\/)\.\.(\/|$)/.test(a.memory) ? a.memory.trim() : DEFAULTS.memory,
+    interimResults: bool(a.interim_results, DEFAULTS.interimResults),
+    stopAfterSubmit: bool(a.stop_after_submit, DEFAULTS.stopAfterSubmit),
+    // A voice command is an on/off choice, so the setting is a checkbox and the phrase is the
+    // command's own word: `command_stop: true` listens for "stop". A text box holding the word
+    // `off` was the wrong control for the question — it asked people to type a phrase when what
+    // they wanted was to turn something on.
+    //
+    // A STRING is still honoured, so anyone who wants a phrase of their own can write one. That
+    // matters for a second language: "stop" is not the word an Arabic speaker will say.
+    commands: {
+      submit: commandPhrase(a.command_submit, 'submit'),
+      stop: commandPhrase(a.command_stop, 'stop'),
+      pause: commandPhrase(a.command_pause, 'pause'),
+      resume: commandPhrase(a.command_resume, 'resume'),
+      removeAllText: commandPhrase(a.command_clear, 'clear'),
+    },
+  };
+}
+
+/**
+ * deep-chat's `speechToText`, or `false` to remove the microphone entirely rather than leave a
+ * button that does nothing.
+ */
+function speechToTextConfig(cfg) {
+  if (!cfg.voiceInput) return false;
+
+  // Only the commands that were actually given a phrase. An empty phrase is not a disabled command.
+  const commands = {};
+  for (const [key, phrase] of Object.entries(cfg.commands || {})) {
+    if (phrase) commands[key] = phrase;
+  }
+
+  return {
+    webSpeech: cfg.speechLanguage ? { language: cfg.speechLanguage } : true,
+    displayInterimResults: cfg.interimResults !== false,
+    stopAfterSubmit: cfg.stopAfterSubmit !== false,
+    ...(cfg.submitAfterSilence ? { submitAfterSilence: cfg.submitAfterSilence } : {}),
+    // Interim words are a guess the recogniser is still revising, so they are muted; the settled
+    // text is ordinary body colour. Tokens, not literals, so both themes follow with no second copy.
+    textColor: { interim: 'var(--text-subtle)', final: 'var(--text-default)' },
+    // The microphone in the design system rather than deep-chat's stock red, and command mode in the
+    // accent so an active listening mode is visible at a glance.
+    button: {
+      default: { container: { default: { color: 'var(--text-subtle)' } } },
+      active: { container: { default: { color: 'var(--danger, #d33)' } } },
+      commandMode: { container: { default: { color: 'var(--link)' } } },
+    },
+    ...(Object.keys(commands).length
+      ? { commands: { ...commands, settings: { substrings: false, caseSensitive: false } } }
+      : {}),
+  };
+}
+
+/**
+ * deep-chat's `textToSpeech`, or `false`. Its presence IS "read the replies aloud" — there is no
+ * separate switch, and `audio.autoPlay` in the docs is about responses carrying an audio file, which
+ * this assistant never returns.
+ */
+function textToSpeechConfig(cfg) {
+  if (!cfg.voiceOutput) return false;
+  return {
+    volume: cfg.speechVolume,
+    rate: cfg.speechRate,
+    pitch: cfg.speechPitch,
+    // A name the browser does not have falls back to its default rather than going silent. The lists
+    // differ per browser and per OS, which is why the setting is a plain string and not a menu.
+    ...(cfg.voiceName ? { voiceName: cfg.voiceName } : {}),
+    // The recogniser's language is the right default for the reply too: ask in Arabic, be answered
+    // in an Arabic voice, without setting it twice.
+    ...(cfg.speechLanguage ? { lang: cfg.speechLanguage } : {}),
+  };
+}
+
+/** What the page is handed: the flags it still needs, plus the two finished deep-chat objects. */
+function panelConfig(settings = {}, wsSettings = null) {
+  const cfg = assistantSettings(settings);
+  return {
+    ...assistantIdentity(settings, wsSettings),
+    voiceInput: cfg.voiceInput,
+    speechToText: speechToTextConfig(cfg),
+    textToSpeech: textToSpeechConfig(cfg),
+    // The narration toggle in the panel header. `voiceOutput` is only where it STARTS (settings.yml's
+    // voice_output; a choice made with the toggle is the browser's and wins). `narration` is the voice
+    // to use when it is on, always present: textToSpeech above is `false` when the setting is off, and
+    // someone who turns the toggle on still has to be spoken to in the voice they configured.
+    voiceOutput: cfg.voiceOutput,
+    narration: textToSpeechConfig({ ...cfg, voiceOutput: true }),
+    fieldMic: fieldMicConfig(cfg),
+    avatar: cfg.avatar,
+  };
+}
+
+module.exports = {
+  assistantSettings, assistantIdentity, speechToTextConfig, textToSpeechConfig, fieldMicConfig,
+  panelConfig, LANGUAGES, DEFAULTS, UNSET, AVATARS, workspaceLanguage, languageName,
+};

package/tab-modal.js

@@ -0,0 +1,75 @@
+/**
+ * A modal with its sections as tabs down the left, and the chosen one's content on the right.
+ *
+ * The editor modal used to be one scroll of everything, with its sections as links inside the page or
+ * as a back button and a list. A set of related views (all the settings, everything about a workitem)
+ * reads better as a set: the names stay in view, the one you are on is marked, and a link to it survives
+ * as `#<id>/<tab>`. Each tab is a fragment URL; the pane loads it into itself, so a tab nobody opens is
+ * never rendered.
+ *
+ * Tabs are real buttons in a tablist. Selection, the arrow keys, the filter and the address live in
+ * public/ui.js; this renders the markup and nothing else.
+ */
+
+const { esc } = require('./html');
+const { iconHtml } = require('./icons');
+
+/**
+ * @param {object} o
+ * @param {string} o.id        names the modal in the address: #<id>/<tab>
+ * @param {string} o.title     heading of the left column
+ * @param {string} [o.subtitle]
+ * @param {{label: string, url: string}} [o.back]  a way out above the tabs, loaded into the whole modal
+ * @param {boolean} [o.filter] a filter box above the tabs, for a long list
+ * @param {boolean} [o.hash]   keep #<id>/<tab> in the address, so the place can be linked to and reopened
+ * @param {{id: string, label: string, tabs: {id: string, label: string, url: string, icon?: string, hint?: string, badge?: string}[]}[]} o.groups
+ * @param {string} [o.active]  the tab to open on; the first one when it is not found
+ */
+function tabModalHtml({ id, title, subtitle = '', back = null, filter = false, hash = false, groups, active = '' }) {
+  const all = groups.flatMap((g) => g.tabs);
+  if (!all.length) return '<div class="msg error">Nothing to show here.</div>';
+  const current = all.find((t) => t.id === active) || all[0];
+  const pane = `tm-${id}-pane`;
+  const tab = (t) => {
+    const on = t === current;
+    return `<button type="button" role="tab" class="tabmodal-tab${on ? ' is-selected' : ''}"
+        id="tm-${esc(id)}-${esc(t.id)}" data-tab="${esc(t.id)}" data-label="${esc(t.label)}"
+        data-hint="${esc(t.hint || '')}" aria-selected="${on ? 'true' : 'false'}" aria-controls="${esc(pane)}"
+        tabindex="${on ? '0' : '-1'}" hx-get="${esc(t.url)}" hx-target="#${esc(pane)}" hx-swap="innerHTML">
+        ${iconHtml(t.icon || 'tabler:point', 0.9)}<span class="tabmodal-tab-label">${esc(t.label)}</span>${t.badge ? `<span class="tabmodal-badge">${esc(t.badge)}</span>` : ''}
+      </button>`;
+  };
+  return `
+<div class="tabmodal" data-tabmodal="${esc(id)}"${hash ? ' data-hash' : ''}>
+  <nav class="tabmodal-nav" aria-label="${esc(title)}">
+    ${back ? `<button type="button" class="tabmodal-back" hx-get="${esc(back.url)}" hx-target="#editor-modal-body" hx-swap="innerHTML">
+      <span uk-icon="icon: arrow-left; ratio: .8"></span> ${esc(back.label)}</button>` : ''}
+    <div class="tabmodal-title">
+      <h2>${esc(title)}</h2>
+      ${subtitle ? `<span class="uk-text-meta">${esc(subtitle)}</span>` : ''}
+    </div>
+    ${filter ? `<input type="search" class="tabmodal-filter uk-input uk-form-small" placeholder="Filter" aria-label="Filter ${esc(title)}" autocomplete="off">` : ''}
+    <div class="tabmodal-tabs" role="tablist" aria-orientation="vertical" aria-label="${esc(title)}">
+      ${groups.map((g) => `
+      <div class="tabmodal-group" role="presentation" data-group="${esc(g.id)}">
+        ${g.label ? `<p class="tabmodal-group-label" role="presentation">${esc(g.label)}</p>` : ''}
+        ${g.tabs.map(tab).join('')}
+      </div>`).join('')}
+    </div>
+  </nav>
+  <section class="tabmodal-main">
+    <header class="tabmodal-head">
+      <h3 class="tabmodal-heading">${esc(current.label)}</h3>
+      <span class="tabmodal-sub uk-text-meta">${esc(current.hint || '')}</span>
+    </header>
+    <div class="tabmodal-pane" id="${esc(pane)}" role="tabpanel" aria-labelledby="tm-${esc(id)}-${esc(current.id)}"
+         tabindex="0" aria-live="polite">
+      <div class="tabmodal-loading" hx-get="${esc(current.url)}" hx-trigger="load" hx-target="#${esc(pane)}" hx-swap="innerHTML">
+        <span class="uk-text-meta">Loading…</span>
+      </div>
+    </div>
+  </section>
+</div>`;
+}
+
+module.exports = { tabModalHtml };

package/test-reports.js

@@ -0,0 +1,260 @@
+/**
+ * What a run left behind: the report, the failure screenshots, the DOM dumps and the recordings.
+ *
+ * A project can carry more than one report — a Drupal tree has a `tests/reports/` per module that
+ * ships tests — so everything here is a list, and the row summarises the newest.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('./html');
+const { humanSize, humanTime, VIDEO_RE } = require('./format');
+const { workspaceDir } = require('./workspaces');
+
+// A project's test report, if it ran the tests. webship-js (Playwright + Cucumber) writes
+// <module>/tests/reports/cucumber_report.{html,json}, so the search is bounded to that
+// shape rather than walking a built Drupal site — a project has ~20k files under
+// web/core alone.
+//
+// The JSON is what the row and the modal read. The HTML is a cucumber-html-reporter page
+// that pulls Bootstrap, jQuery and moment from CDNs, so on an offline box it renders
+// unstyled and its collapsibles do nothing; the summary is built from the JSON instead and
+// works with no network at all.
+function reportLabel(r) {
+  const parts = r.rel.split(path.sep).filter((x) => x && x !== '.' && x !== 'tests' && x !== 'reports');
+  return parts.length ? parts[parts.length - 1] : 'this project';
+}
+
+function testingStackOf(dir, project) {
+  const root = path.join(dir, project);
+  if (fs.existsSync(path.join(root, '.ddev', 'commands', 'web', 'init-full-automated-testing'))) return 'webship';
+  if (fs.existsSync(path.join(root, 'cucumber.js')) || fs.existsSync(path.join(root, 'tests', 'step-definitions'))) return 'webship-js';
+  return 'none';
+}
+
+/** Can this project actually start a suite right now? Three things have to be
+ *  true, and each has a different fix, so the row says which one is missing
+ *  rather than only "tests": a suite to run, the JS dependencies installed, and
+ *  the shared libraries chromium links against baked into the web image (a
+ *  container without them fails every scenario at browser launch with
+ *  "libnspr4.so: cannot open shared object file"). */
+function testingReadiness(dir, project) {
+  const root = path.join(dir, project);
+  const stack = testingStackOf(dir, project);
+  const deps = fs.existsSync(path.join(root, 'node_modules', '@cucumber', 'cucumber'));
+  const libs = fs.existsSync(path.join(root, '.ddev', 'web-build', 'Dockerfile.playwright'));
+  const missing = [];
+  if (stack === 'none') missing.push('a testing stack');
+  if (!deps) missing.push('the JS dependencies');
+  if (!libs) missing.push('the browser libraries');
+  return { stack, deps, libs, ready: missing.length === 0, missing };
+}
+
+const REPORT_SEARCH_DIRS = ['packages', 'web/modules/custom', 'web/modules/contrib', 'tests', '.'];
+
+function findTestReports(dir, project) {
+  const root = path.join(dir, project);
+  const found = [];
+  for (const sub of REPORT_SEARCH_DIRS) {
+    const base = path.join(root, sub);
+    let entries = [];
+    try { entries = fs.readdirSync(base, { withFileTypes: true }); } catch (_) { continue; }
+    // <sub>/<module>/tests/reports/, plus <sub>/tests/reports/ for sub === '.'
+    const candidates = entries.filter((e) => e.isDirectory()).map((e) => path.join(base, e.name, 'tests', 'reports'));
+    candidates.push(path.join(base, 'reports'));
+    for (const c of candidates) {
+      const html = path.join(c, 'cucumber_report.html');
+      const json = path.join(c, 'cucumber_report.json');
+      if (!fs.existsSync(json) && !fs.existsSync(html)) continue;
+      const rel = path.relative(root, c);
+      // A run leaves more than the report: webship-js writes a PNG and a DOM dump per
+      // failed step into tests/screenshots/, and a recording per scenario into
+      // tests/videos/. They are the evidence, so the modal links them rather than only
+      // saying a scenario failed.
+      const testsDir = path.dirname(c);
+      // Empty artifacts are dropped, not listed. A crashed run can leave a 0-byte recording
+      // or screenshot, and webship-js writes a DOM dump for every failed step even when the
+      // page never rendered — 81 of the 795 dumps in this tree are the literal empty
+      // document `<html><head></head><body></body></html>`, 11 of the 21 in the one report
+      // the test workspace shows. A link to a blank page is worse than no link.
+      //
+      // Judged exactly rather than by a size threshold: the smallest REAL dump here is 454
+      // bytes of captured JSON, so a "too small to matter" cutoff would discard real
+      // evidence. Only files small enough to be empty are opened, so this costs nothing on
+      // the ones that matter.
+      const isEmptyDocument = (full, size) => {
+        if (size > 400) return false;
+        try {
+          return /<body[^>]*>\s*<\/body>/i.test(fs.readFileSync(full, 'utf8'));
+        } catch (_) { return false; }
+      };
+      const sideFiles = (name, re) => {
+        try {
+          const base = path.join(testsDir, name);
+          return fs.readdirSync(base)
+            .filter((f) => re.test(f))
+            .map((f) => {
+              const full = path.join(base, f);
+              let size = 0, mtimeMs = 0;
+              try { const st = fs.statSync(full); size = st.size; mtimeMs = st.mtimeMs; } catch (_) { /* vanished */ }
+              return { file: path.relative(root, full), name: f, size, mtimeMs, full };
+            })
+            .filter((f) => !(/\.html?$/i.test(f.name)
+              ? (f.size === 0 || isEmptyDocument(f.full, f.size))
+              : artifactIsEmpty(f.full, f.name, f.size, f.mtimeMs)))
+            .map(({ full, ...rest }) => rest)
+            .sort((a, b) => b.mtimeMs - a.mtimeMs || a.name.localeCompare(b.name));
+        } catch (_) { return []; }
+      };
+      found.push({ rel, html: fs.existsSync(html) ? path.relative(root, html) : null,
+        json: fs.existsSync(json) ? path.relative(root, json) : null,
+        mtime: fs.statSync(fs.existsSync(json) ? json : html).mtime,
+        shots: sideFiles('screenshots', /\.(png|jpe?g)$/i),
+        doms: sideFiles('screenshots', /\.html?$/i),
+        videos: sideFiles('videos', VIDEO_RE),
+        pdfs: [...sideFiles('reports', /\.pdf$/i), ...sideFiles('.', /\.pdf$/i)],
+        contrib: rel.includes(`web${path.sep}modules${path.sep}contrib`) });
+    }
+  }
+  // The copy under web/modules/contrib is the installed one; the source copy is the one
+  // to show when both exist, and they are usually byte-identical anyway.
+  const seen = new Set();
+  return found
+    .sort((a, b) => Number(a.contrib) - Number(b.contrib) || b.mtime - a.mtime)
+    .filter((r) => { const k = r.html || r.json; if (seen.has(path.basename(path.dirname(k)))) return false; return true; });
+}
+
+// Scenario tallies from the cucumber JSON. A scenario counts as failed if any step failed,
+// skipped only if nothing in it ran — otherwise a partly-run scenario would be reported
+// as a pass.
+function testReportSummary(dir, project, report) {
+  if (!report || !report.json) return null;
+  let data;
+  try { data = JSON.parse(fs.readFileSync(path.join(dir, project, report.json), 'utf8')); } catch (_) { return null; }
+  if (!Array.isArray(data)) return null;
+  const out = { features: [], scenarios: 0, passed: 0, failed: 0, skipped: 0, mtime: report.mtime };
+  for (const feat of data) {
+    const f = { name: feat.name || '(unnamed)', scenarios: [] };
+    for (const sc of feat.elements || []) {
+      if (sc.type && sc.type !== 'scenario') continue;
+      const states = (sc.steps || []).map((st) => (st.result || {}).status);
+      const status = states.includes('failed') ? 'failed'
+        : states.some((x) => x === 'passed') ? 'passed' : 'skipped';
+      const ms = (sc.steps || []).reduce((n, st) => n + ((st.result || {}).duration || 0), 0) / 1e6;
+      f.scenarios.push({ name: sc.name || '(unnamed)', status, ms });
+      out.scenarios += 1;
+      out[status] += 1;
+    }
+    if (f.scenarios.length) out.features.push(f);
+  }
+  return out;
+}
+
+// Both are looked up per project row, and rows re-render on every job poll.
+let _reportCache = new Map();
+let _reportCacheAt = 0;
+function invalidateTestReports() {
+  _reportCache = new Map();
+  _reportCacheAt = 0;
+}
+
+function testReportFor(dir, project) {
+  const now = Date.now();
+  if (now - _reportCacheAt > 2000) { _reportCache = new Map(); _reportCacheAt = now; }
+  const k = `${dir}/${project}`;
+  if (!_reportCache.has(k)) {
+    const reports = findTestReports(dir, project);
+    _reportCache.set(k, reports.length ? { report: reports[0], summary: testReportSummary(dir, project, reports[0]) } : null);
+  }
+  return _reportCache.get(k);
+}
+
+// One page of a report's screenshots or recordings. Shared by the fragment route and by the
+// delete action, so a deletion re-renders byte-identical markup instead of a second copy of it.
+//
+// The report modal loads these lazily and paged, because 303 inline <img> and 240 links made
+// "Tests" a multi-minute load.
+function testMediaHtml(key, project, kind, wantPage) {
+  const dir = workspaceDir(key);
+  const t = testReportFor(dir, project);
+  if (!t) return '<p class="uk-text-meta">No report.</p>';
+  const items = kind === 'videos' ? t.report.videos : t.report.shots;   // already newest first
+  if (!items.length) {
+    // Reached both when a report never had any and when they have just been deleted.
+    return `<p class="uk-text-meta">No ${kind === 'videos' ? 'recordings' : 'screenshots'} in this report — a run writes its own.</p>`;
+  }
+  const PER = 15;
+  const pages = Math.max(1, Math.ceil(items.length / PER));
+  const page = Math.min(pages, Math.max(1, wantPage || 1));
+  const slice = items.slice((page - 1) * PER, page * PER);
+  const fileUrl = (rel) => `/files/${encodeURIComponent(key)}/${encodeURIComponent(project)}/${rel.split(path.sep).map(encodeURIComponent).join('/')}`;
+  const viewUrl = (name) => `/fragments/${encodeURIComponent(key)}/test-view/${encodeURIComponent(project)}?kind=${kind}&name=${encodeURIComponent(name)}`;
+  // A screenshot and its DOM dump share a stem, so the row links the page it was taken from.
+  const domFor = (name) => t.report.doms.find((d) => d.name.replace(/\.html?$/i, '') === name.replace(/\.(png|jpe?g)$/i, ''));
+  // Deleting asks in the confirm dialog, targets this list, and never takes a path: the action looks
+  // the name up in the report's own file list, exactly as the viewer does.
+  const del = (extra) => `hx-post="/actions/test-media-delete" hx-vals='{"workspace":"${esc(key)}","projectName":"${esc(project)}","kind":"${kind}",${extra},"confirm":"yes"}' hx-target="#test-media-${kind}" hx-swap="innerHTML" hx-trigger="confirmed-remove"`;
+
+  const rows = slice.map((f) => {
+    const failed = /^failed_/i.test(f.name) || /FAILED/i.test(f.name);
+    const dom = kind === 'shots' ? domFor(f.name) : null;
+    const label = esc(f.name.replace(/^failed_/i, '').replace(/\.(png|jpe?g|webm|mp4|mov|mkv|ogv)$/i, ''));
+    const meta = `${f.mtimeMs ? esc(humanTime(new Date(f.mtimeMs))) + ' · ' : ''}${esc(humanSize(f.size))}`;
+    const deleteOne = `<button type="button" class="uk-button uk-button-danger uk-button-small arm-step test-media-del"
+      title="${esc(`Delete ${f.name}${dom ? ' and its DOM dump' : ''}`)}" ${del(`"name":"${esc(f.name)}"`)}><span uk-icon="icon: trash; ratio: .6"></span></button>`;
+    if (kind === 'shots') {
+      return `
+          <li class="test-shot-card">
+            <button type="button" class="test-shot-thumb" title="${esc(f.name)}"
+                    hx-get="${viewUrl(f.name)}" hx-target="#editor-modal-body" hx-swap="innerHTML">
+              <img src="${fileUrl(f.file)}" alt="${esc(f.name)}" loading="lazy">
+            </button>
+            <span class="test-shot-caption uk-text-meta" title="${esc(f.name)}">${label}</span>
+            <span class="test-shot-meta uk-text-meta">${meta}${failed ? ' <span class="uk-label uk-label-danger">failed</span>' : ''}
+              ${dom ? `<a href="${fileUrl(dom.file)}" target="_blank" title="The DOM dump captured with this screenshot">DOM</a>` : ''}
+              <a href="${fileUrl(f.file)}" target="_blank" title="Open the raw file in a new tab"><span uk-icon="icon: link-external; ratio: .55"></span></a>
+              ${deleteOne}</span>
+          </li>`;
+    }
+    return `
+          <li class="test-media-row">
+            <button type="button" class="test-media-name" title="${esc(f.name)}"
+                    hx-get="${viewUrl(f.name)}" hx-target="#editor-modal-body" hx-swap="innerHTML">
+              <span uk-icon="icon: play-circle; ratio: .8"></span>
+              ${label}
+            </button>
+            <span class="test-media-meta uk-text-meta">${meta}${failed ? ' <span class="uk-label uk-label-danger">failed</span>' : ''}</span>
+            <span class="test-media-actions">
+              <a class="uk-button uk-button-default uk-button-small" href="${fileUrl(f.file)}" target="_blank" title="Open the raw file in a new tab"><span uk-icon="icon: link-external; ratio: .6"></span></a>
+              ${deleteOne}
+            </span>
+          </li>`;
+  }).join('');
+
+  const pageUrl = (n) => `/fragments/${encodeURIComponent(key)}/test-media/${encodeURIComponent(project)}?kind=${kind}&page=${n}`;
+  const pager = pages > 1 ? `
+          <div class="test-media-pager uk-text-meta">
+            <button type="button" class="uk-button uk-button-default uk-button-small" ${page <= 1 ? 'disabled' : `hx-get="${pageUrl(page - 1)}" hx-target="#test-media-${kind}" hx-swap="innerHTML"`}>‹</button>
+            <span>${(page - 1) * PER + 1}–${Math.min(page * PER, items.length)} of ${items.length} · page ${page} of ${pages} · newest first</span>
+            <button type="button" class="uk-button uk-button-default uk-button-small" ${page >= pages ? 'disabled' : `hx-get="${pageUrl(page + 1)}" hx-target="#test-media-${kind}" hx-swap="innerHTML"`}>›</button>
+          </div>` : '';
+
+  // Clearing the lot is one button, and it says how many and what else goes with them — the DOM
+  // dumps are written per failed step and are useless once their screenshot is gone.
+  const domCount = kind === 'shots' ? t.report.doms.length : 0;
+  const bulk = `
+          <div class="test-media-bulk">
+            <button type="button" class="uk-button uk-button-danger uk-button-small arm-step"
+                    title="${esc(`Delete all ${items.length} ${kind === 'videos' ? 'recordings' : 'screenshots'}${domCount ? ` and ${domCount} DOM dumps` : ''} of this report`)}"
+                    ${del('"all":"yes"')}><span uk-icon="icon: trash; ratio: .7"></span> Delete all ${items.length} ${kind === 'videos' ? 'recordings' : 'screenshots'}${domCount ? ` + ${domCount} DOM dumps` : ''}</button>
+            <span class="uk-text-meta">Evidence from a finished run — the next run writes its own.</span>
+          </div>`;
+
+  return `${bulk}<ul class="${kind === 'shots' ? 'test-shot-grid' : 'test-media-list'}">${rows}</ul>${pager}`;
+}
+
+module.exports = {
+  findTestReports, testReportSummary, testReportFor, invalidateTestReports, testMediaHtml,
+  reportLabel, testingStackOf, testingReadiness, REPORT_SEARCH_DIRS,
+};