rikiki-deck 0.6.0 → 0.7.2

package/bin/lib/browser.mjs

@@ -0,0 +1,302 @@
+// ════════════════════════════════════════════════════════════════
+// The browser rikiki drives, and the server it drives it against.
+//
+// `export`, `render` and `check` all need the same five things: a Playwright
+// that is loaded only when used, a local server on a free port, a deck settled
+// enough to look at, the errors the page reported along the way, and both
+// resources closed whatever happens. This module owns all five so the commands
+// own none of them.
+// ════════════════════════════════════════════════════════════════
+
+import { readFile, stat } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { ExpectedError } from './cli-error.mjs';
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+};
+
+/** Playwright is an optional peer · loaded on first use, never at import. */
+export async function loadChromium() {
+  for (const pkg of ['playwright', 'playwright-core', '@playwright/test']) {
+    try {
+      const mod = await import(pkg);
+      if (mod.chromium) return mod.chromium;
+    } catch {
+      // Try the next one · only the last failure is worth reporting.
+    }
+  }
+  throw new ExpectedError(
+    'this command needs Playwright, which is an optional peer dependency.\n' +
+      '  Install it next to rikiki-deck:  npm i -D playwright && npx playwright install chromium\n' +
+      '  (it is optional so that decks which only run in your own browser do not\n' +
+      '   have to download one)',
+  );
+}
+
+/**
+ * Launch the full Chromium build rather than Playwright's default headless shell.
+ *
+ * The shell positions glyphs differently: a paragraph that wraps onto six lines
+ * in Chrome can fit on five there, so a card that spills in every real browser
+ * measured clean and `CONTENT_ESCAPES_BOX` stayed silent. The full build wraps
+ * like the browser the deck is actually opened in. When it is not installed the
+ * default build still runs, and `note` says the measurements may be off.
+ */
+export async function launchChromium(chromium, note = (line) => console.error(line)) {
+  try {
+    return await chromium.launch({ channel: 'chromium' });
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (!message.includes("Executable doesn't exist")) throw e;
+    note(
+      'rikiki · note · the full Chromium build is not installed · falling back to the headless shell, ' +
+        'whose text wrapping differs from a real browser · run `npx playwright install chromium`',
+    );
+    return chromium.launch();
+  }
+}
+
+/** True when `abs` is inside `root` · `/srv/deck` must not admit `/srv/deck-x`.
+ *  Exported because a path check nobody can test is a path check nobody trusts. */
+export function isInside(root, abs) {
+  return abs === root || abs.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+
+/** How far above its own folder a deck reaches.
+ *
+ *  A served deck points at the framework with `../../dist/index.js`, so serving
+ *  only the deck's directory 404s every module and the page never upgrades.
+ *  Counting the deepest `../` prefix gives the smallest root that still
+ *  contains everything the deck asks for · no wider than necessary. */
+export function rootDepthFor(html) {
+  let depth = 0;
+  for (const m of html.matchAll(/(?:src|href)\s*=\s*["']((?:\.\.\/)+)/g)) {
+    depth = Math.max(depth, m[1].split('../').length - 1);
+  }
+  return depth;
+}
+
+/** Serve `rootDir` on an ephemeral port · ES modules need http://, not file://.
+ *  Resolves to `{ origin, close }`. */
+export async function serveDir(rootDir) {
+  const root = resolve(rootDir);
+  const server = createServer(async (req, res) => {
+    let abs;
+    try {
+      const rel = decodeURIComponent((req.url ?? '/').split('?')[0]);
+      abs = resolve(root, '.' + rel);
+    } catch {
+      // A malformed percent-escape is a bad request, not a missing file.
+      res.writeHead(400, { 'content-type': 'text/plain' }).end('bad request');
+      return;
+    }
+    if (!isInside(root, abs)) {
+      res.writeHead(403, { 'content-type': 'text/plain' }).end('forbidden');
+      return;
+    }
+    try {
+      const info = await stat(abs);
+      const file = info.isDirectory() ? join(abs, 'index.html') : abs;
+      const body = await readFile(file);
+      res.writeHead(200, { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream' });
+      res.end(body);
+    } catch (cause) {
+      res.writeHead(404, { 'content-type': 'text/plain' }).end(`not found: ${req.url}`);
+      // Reported to the caller through the page's own failed requests, never
+      // swallowed here.
+      if (process.env.RIKIKI_DEBUG) console.error('rikiki · 404', req.url, String(cause));
+    }
+  });
+  await new Promise((ok) => server.listen(0, '127.0.0.1', ok));
+  const { port } = server.address();
+  return {
+    origin: `http://127.0.0.1:${port}`,
+    close: () => new Promise((ok) => server.close(ok)),
+  };
+}
+
+/** The URL a deck file takes once its smallest containing root is served. */
+export function deckLocation(deckPath) {
+  const abs = resolve(deckPath);
+  const depth = rootDepthFor(readFileSync(abs, 'utf8'));
+  const rootDir = resolve(dirname(abs), ...Array(depth).fill('..'));
+  return { rootDir, urlPath: relative(rootDir, abs).split(sep).join('/') };
+}
+
+/** The title of a slide, as a line of text.
+ *
+ *  Runs in the page. `textContent` alone joins across a `<br>`, which is how a
+ *  two-line title became "Clickstages" in a manifest whose whole job is to name
+ *  the slide you are looking at. */
+export const SLIDE_TITLE_READER = `(el) => {
+  const source = el.querySelector('h1, [slot="title"]');
+  if (!source) return null;
+  const copy = source.cloneNode(true);
+  for (const br of copy.querySelectorAll('br')) br.replaceWith(' ');
+  return copy.textContent.trim().replace(/\\s+/g, ' ') || null;
+}`;
+
+/** Wait until nothing is moving any more.
+ *
+ *  A reveal is a CSS transition, and a screenshot taken while it runs catches
+ *  the text mid-fade. The Web Animations API knows when each one is done, so
+ *  the wait is on the animations themselves; the deadline is only there for an
+ *  animation that never ends (a looping accent, a spinner). */
+export async function waitForStillFrame(page, deadlineMs = 2_000) {
+  await page
+    .evaluate(async (ms) => {
+      const ending = document
+        .getAnimations()
+        .filter((a) => a.effect?.getComputedTiming?.().iterations !== Number.POSITIVE_INFINITY)
+        .map((a) => a.finished.catch(() => {}));
+      await Promise.race([
+        Promise.all(ending),
+        new Promise((done) => setTimeout(done, ms)),
+      ]);
+      // One painted frame after the last change · the screenshot reads what the
+      // eye would see, not the state the compositor is still catching up with.
+      await new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+    }, deadlineMs)
+    .catch(() => {});
+}
+
+/** How long a deck may take to load and show its first slide. Generous on
+ *  purpose: a deck loads in well under a second, the margin is for a loaded
+ *  machine, and a deck that really never loads is reported, not retried. */
+export const PAGE_LOAD_TIMEOUT_MS = 60_000;
+
+/** How long a slide change may take before the walk gives up on it. A deck
+ *  switches slides in milliseconds; the margin is for a loaded machine (a
+ *  single-core CI runner took over 5 s once), not for the deck. */
+export const NAVIGATION_TIMEOUT_MS = 15_000;
+
+/** Go to slide `index` (1-based) and report the state actually reached.
+ *  Shared by `render` and `check` · both walk a deck the same way. */
+export async function goToSlide(page, index) {
+  await page.evaluate((i) => {
+    window.location.hash = `#${i}`;
+  }, index);
+  await page.waitForFunction(
+    (i) => document.querySelector('deck-root')?.current === i - 1,
+    index,
+    { timeout: NAVIGATION_TIMEOUT_MS },
+  );
+  await page.evaluate(() => document.fonts.ready);
+  await waitForStillFrame(page);
+}
+
+/** Advance one step inside the current slide · false when there is none left
+ *  (either the last state of the deck, or the step moved on to the next
+ *  slide). */
+export async function advanceStep(page) {
+  const before = await page.evaluate(() => {
+    const root = document.querySelector('deck-root');
+    return { slide: root.current, step: root.step };
+  });
+  await page.keyboard.press('ArrowRight');
+  try {
+    await page.waitForFunction(
+      (b) => {
+        const root = document.querySelector('deck-root');
+        return root.current !== b.slide || root.step !== b.step;
+      },
+      before,
+      { timeout: 2_000 },
+    );
+  } catch {
+    return false; // the deck did not move · this was the last state
+  }
+  await waitForStillFrame(page);
+  const after = await page.evaluate(() => {
+    const root = document.querySelector('deck-root');
+    return { slide: root.current, step: root.step };
+  });
+  return after.slide === before.slide;
+}
+
+/** Wait for the deck to be worth looking at: upgraded, on a slide, fonts and
+ *  diagrams settled. Returns false when it never got there. */
+async function settle(page, timeoutMs) {
+  try {
+    await page.waitForFunction(() => !!document.querySelector('deck-root > [active]'), null, {
+      timeout: timeoutMs,
+    });
+  } catch {
+    return false;
+  }
+  // A diagram still rendering photographs as an empty box, and a font still
+  // loading shifts every line · both are worth the wait, neither is worth
+  // failing over.
+  await page
+    .evaluate(async () => {
+      await document.fonts.ready;
+      const diagrams = Array.from(document.querySelectorAll('deck-mermaid'));
+      await Promise.all(diagrams.map((d) => d.whenRendered ?? Promise.resolve()));
+    })
+    .catch(() => {});
+  await waitForStillFrame(page);
+  return true;
+}
+
+/**
+ * Open a deck in a real browser and hand it to `fn`.
+ *
+ * `fn` receives `{ page, browser, origin, url, settled, missing, errors }`, where
+ * `missing` lists the requests the page could not load and `errors` the
+ * exceptions it threw. The browser and the server are closed on the way out,
+ * including when `fn` throws.
+ *
+ * @returns {Promise<*>} whatever `fn` returns.
+ */
+export async function withDeck(deckPath, fn, { timeoutMs = PAGE_LOAD_TIMEOUT_MS, viewport } = {}) {
+  const chromium = await loadChromium();
+  const { rootDir, urlPath } = deckLocation(deckPath);
+  const server = await serveDir(rootDir);
+  const browser = await launchChromium(chromium);
+  const missing = [];
+  const errors = [];
+
+  try {
+    const page = await browser.newPage(viewport ? { viewport } : {});
+    page.on('requestfailed', (r) => missing.push(r.url()));
+    page.on('response', (r) => {
+      if (r.status() >= 400) missing.push(`${r.url()} (HTTP ${r.status()})`);
+    });
+    page.on('pageerror', (e) => errors.push(e instanceof Error ? e.message : String(e)));
+
+    const url = `${server.origin}/${urlPath}`;
+    let loaded = true;
+    try {
+      await page.goto(url, { waitUntil: 'load', timeout: timeoutMs });
+    } catch (e) {
+      // A deck that will not even load is a result to report, not a crash: the
+      // caller turns it into a diagnostic.
+      loaded = false;
+      errors.push(e instanceof Error ? e.message : String(e));
+    }
+    const settled = loaded && (await settle(page, timeoutMs));
+    return await fn({ page, browser, origin: server.origin, url, settled, missing, errors });
+  } finally {
+    await browser.close().catch(() => {});
+    await server.close().catch(() => {});
+  }
+}

package/bin/lib/check-api.d.ts

@@ -0,0 +1,28 @@
+export interface CheckFinding {
+  element?: Element;
+  key?: string;
+  message: string;
+  suggestion?: string;
+  measurement?: Record<string, unknown>;
+}
+export interface CheckContext {
+  readonly slide: number;
+  readonly state: number;
+  readonly profile: string;
+  query<T extends Element = HTMLElement>(selector: string, options?: { shadow?: boolean }): T[];
+  report(finding: CheckFinding): void;
+}
+export interface CheckRule {
+  code: string;
+  scope: 'document' | 'slide' | 'state';
+  severity: 'error' | 'warning';
+  profiles?: string[];
+  run(ctx: CheckContext): void | Promise<void>;
+}
+export interface CheckPlugin {
+  apiVersion: 1;
+  id: string;
+  version: string;
+  rules: CheckRule[];
+}
+export function defineChecks(plugin: CheckPlugin): void;

package/bin/lib/check-api.mjs

@@ -0,0 +1,6 @@
+/** Register only while `rikiki check` has installed its browser bridge. */
+export function defineChecks(plugin) {
+  const bridge = globalThis[Symbol.for('rikiki.checks.v1')];
+  if (!bridge) throw new Error('CheckPlugin must be loaded by rikiki check (API 1)');
+  bridge.define(plugin);
+}

package/bin/lib/check-plugins.mjs

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+export const CHECK_API_VERSION = 1;
+const failure = (plugin, code, message) => ({ plugin, code, severity: 'error', message });
+
+export function findCheckConfig(deckPath, explicit) {
+  if (explicit) return resolve(explicit);
+  let dir = dirname(resolve(deckPath));
+  for (;;) {
+    const file = join(dir, 'rikiki.config.json');
+    if (existsSync(file)) return file;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Data only: no dependency's Node entry point is evaluated. */
+export function resolveCheckPlugins(deckPath, { config, plugins = [], noPlugins = false } = {}) {
+  const result = { plugins: [], diagnostics: [], notChecked: [], config: {} };
+  if (noPlugins) { result.notChecked.push('plugin checks · explicitly disabled'); return result; }
+  let file;
+  try {
+    file = findCheckConfig(deckPath, config);
+    result.config = file ? JSON.parse(readFileSync(file, 'utf8')) : {};
+    if (!result.config || typeof result.config !== 'object' || Array.isArray(result.config)
+      || (result.config.plugins !== undefined && !Array.isArray(result.config.plugins))) throw new Error('plugins must be an array');
+  } catch (error) {
+    result.diagnostics.push(failure('rikiki', 'CHECK_CONFIG_INVALID', `Cannot load check configuration: ${error.message}`));
+    result.notChecked.push('plugin checks · invalid configuration');
+    return result;
+  }
+  const base = file ? dirname(file) : dirname(resolve(deckPath));
+  const require = createRequire(pathToFileURL(join(base, 'package.json')));
+  const seen = new Map();
+  const namespaces = new Set();
+  for (const entry of [...(result.config.plugins ?? []), ...plugins]) {
+    const spec = typeof entry === 'string' ? { package: entry } : entry;
+    let id = spec?.package ?? spec?.manifest ?? 'unknown';
+    try {
+      if (!spec || typeof spec !== 'object') throw new Error('expected a package name or a plugin descriptor');
+      const manifestPath = spec.manifest
+        ? resolve(base, spec.manifest)
+        : require.resolve(`${spec.package}/rikiki.module.json`);
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      id = manifest.id;
+      if (manifest.schemaVersion !== 1 || typeof id !== 'string' || !/^[a-zA-Z0-9@/._-]+$/.test(id)
+        || typeof manifest.version !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(manifest.namespace ?? '')
+        || manifest.checks?.apiVersion !== CHECK_API_VERSION) throw new Error('unsupported module schema or check API');
+      const profile = spec.profile ?? 'recommended';
+      if (!manifest.checks.profiles?.includes(profile)) throw new Error(`unknown profile: ${profile}`);
+      const entryPath = manifest.checks.entry;
+      if (typeof entryPath !== 'string' || isAbsolute(entryPath)) throw new Error('checks.entry must be package-relative');
+      const root = realpathSync(dirname(manifestPath));
+      const script = realpathSync(resolve(root, entryPath));
+      const rel = relative(root, script);
+      if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('checks.entry escapes the module directory');
+      const identity = JSON.stringify([realpathSync(manifestPath), manifest.version, profile]);
+      if (seen.has(id)) {
+        if (seen.get(id) !== identity) throw new Error(`conflicting versions or profiles of ${id}`);
+        continue;
+      }
+      if (namespaces.has(manifest.namespace)) throw new Error(`duplicate namespace ${manifest.namespace}`);
+      seen.set(id, identity);
+      namespaces.add(manifest.namespace);
+      const skills = (manifest.skills ?? []).map(skill => {
+        if (!skill || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill.name) || typeof skill.path !== 'string') throw new Error('invalid skill descriptor');
+        const src = realpathSync(resolve(root, skill.path));
+        const rel = relative(root, src);
+        if (rel.startsWith('..') || isAbsolute(rel) || !existsSync(join(src, 'SKILL.md'))) throw new Error('invalid skill path');
+        return { name: skill.name, src };
+      });
+      result.plugins.push({ id, version: manifest.version, namespace: manifest.namespace, apiVersion: CHECK_API_VERSION,
+        profile, script, skills, status: 'pending', rules: [], executed: [] });
+    } catch (error) {
+      result.diagnostics.push(failure(String(id), 'CHECK_PLUGIN_LOAD_FAILED', `Cannot load ${id}: ${error.message}`));
+      result.notChecked.push(`plugin ${id} · loading failed`);
+    }
+  }
+  if (!result.plugins.length && !result.diagnostics.length) result.notChecked.push('plugin checks · no plugin configured');
+  return result;
+}
+
+/** Serialized into the browser. This registry has no imports or component side effects. */
+export function installCheckBridge() {
+  const registered = new Map();
+  const key = Symbol.for('rikiki.checks.v1');
+  const query = (root, selector, shadow = false) => {
+    const found = [...root.querySelectorAll(selector)];
+    if (root.matches?.(selector)) found.unshift(root);
+    if (shadow) for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot) found.push(...query(el.shadowRoot, selector, true));
+    }
+    return [...new Set(found)];
+  };
+  const pathOf = (element) => {
+    const parts = [];
+    for (let el = element; el && el !== document.body;) {
+      const tag = el.localName;
+      if (!tag) break;
+      const siblings = el.parentElement ? [...el.parentElement.children].filter(n => n.localName === tag) : [];
+      parts.unshift(el.id ? `${tag}#${CSS.escape(el.id)}` : `${tag}:nth-of-type(${Math.max(1, siblings.indexOf(el) + 1)})`);
+      const host = el.getRootNode().host;
+      if (!el.parentElement && host) { parts.unshift('::shadow'); el = host; }
+      else el = el.parentElement;
+    }
+    return parts.join(' > ');
+  };
+  const api = {
+    define(plugin) {
+      if (plugin.apiVersion !== 1 || !plugin.id || !plugin.version || !Array.isArray(plugin.rules)) throw new Error('Invalid CheckPlugin');
+      if (registered.has(plugin.id)) throw new Error(`Duplicate CheckPlugin: ${plugin.id}`);
+      const codes = new Set();
+      for (const rule of plugin.rules) {
+        if (!/^[A-Z][A-Z0-9_]+$/.test(rule.code) || codes.has(rule.code) || typeof rule.run !== 'function'
+          || !['document', 'slide', 'state'].includes(rule.scope) || !['error', 'warning'].includes(rule.severity)) throw new Error('Invalid or duplicate check rule');
+        codes.add(rule.code);
+      }
+      registered.set(plugin.id, plugin);
+    },
+    describe(id) {
+      const p = registered.get(id);
+      return p ? { id: p.id, version: p.version, apiVersion: p.apiVersion,
+        rules: p.rules.map(({ code, scope, severity, profiles }) => ({ code, scope, severity, profiles })) } : null;
+    },
+    async run({ id, profile, slide, state, documentPass }) {
+      const plugin = registered.get(id);
+      const root = document.querySelector('deck-root');
+      const slides = root ? [...root.children].filter(e => e.localName.startsWith('deck-') && e.localName !== 'deck-root') : [];
+      const active = slides[slide - 1];
+      const out = [], executed = [], failures = [];
+      for (const rule of plugin.rules) {
+        if (rule.profiles && !rule.profiles.includes(profile)) continue;
+        if (rule.scope === 'document' ? !documentPass : rule.scope === 'slide' ? state !== 0 || !active : !active) continue;
+        const scope = rule.scope === 'document' ? root ?? document : active;
+        try {
+          for (const el of query(scope, '*', true)) if (el.updateComplete) await el.updateComplete;
+          await rule.run({ slide, state, profile,
+            query: (selector, options = {}) => query(scope, selector, options.shadow ?? false),
+            report: (finding) => {
+              if (!finding || typeof finding.message !== 'string' || !finding.message.trim()
+                || (finding.key !== undefined && typeof finding.key !== 'string')
+                || (finding.suggestion !== undefined && typeof finding.suggestion !== 'string')
+                || (finding.element !== undefined && !(finding.element instanceof Element))) throw new Error('Invalid diagnostic');
+              const el = finding.element;
+              const owner = el ? slides.findIndex(s => s === el || s.contains(el) || query(s, '*', true).includes(el)) : -1;
+              const measurement = finding.measurement === undefined ? undefined : JSON.parse(JSON.stringify(finding.measurement));
+              out.push({ code: rule.code, severity: rule.severity, message: finding.message, suggestion: finding.suggestion,
+                element: el ? pathOf(el) : undefined, key: finding.key,
+                slide: owner >= 0 ? owner + 1 : rule.scope !== 'document' ? slide : undefined,
+                state: rule.scope === 'document' ? undefined : state, measurement });
+            },
+          });
+          executed.push(rule.code);
+        } catch (error) { failures.push({ code: rule.code, message: String(error?.message ?? error) }); }
+      }
+      return { diagnostics: out, executed, failures };
+    },
+  };
+  Object.defineProperty(globalThis, key, { value: api, configurable: true });
+}
+
+/** A Node timer closes the page even when synchronous plugin code blocks its JS thread. */
+async function bounded(page, operation, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([operation(), new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error('Check plugin execution timed out'));
+        void page.close({ runBeforeUnload: false }).catch(() => {});
+      }, timeoutMs);
+    })]);
+  } finally { clearTimeout(timer); }
+}
+
+export async function startCheckPlugins(page, resolution, timeoutMs = 5000) {
+  if (!resolution.plugins.length) return;
+  await page.evaluate(installCheckBridge);
+  for (const plugin of resolution.plugins) {
+    try {
+      await bounded(page, () => page.addScriptTag({ content: readFileSync(plugin.script, 'utf8') }), timeoutMs);
+      const described = await bounded(page, () => page.evaluate(id => globalThis[Symbol.for('rikiki.checks.v1')].describe(id), plugin.id), timeoutMs);
+      if (!described || described.version !== plugin.version || described.apiVersion !== CHECK_API_VERSION
+        || described.rules.some(r => !r.code.startsWith(plugin.namespace + '_'))) throw new Error('Registration does not match the manifest');
+      plugin.rules = described.rules.filter(r => !r.profiles || r.profiles.includes(plugin.profile));
+      plugin.status = 'loaded';
+    } catch (error) {
+      plugin.status = 'failed';
+      resolution.diagnostics.push(failure(plugin.id, 'CHECK_PLUGIN_LOAD_FAILED', error.message));
+      resolution.notChecked.push(`plugin ${plugin.id} · registration failed`);
+    }
+  }
+}
+
+export async function runCheckPlugins(page, resolution, { slide, state, documentPass }, timeoutMs = 5000) {
+  const diagnostics = [];
+  for (const plugin of resolution.plugins.filter(p => p.status === 'loaded')) {
+    try {
+      const result = await bounded(page, () => page.evaluate(args => globalThis[Symbol.for('rikiki.checks.v1')].run(args),
+        { id: plugin.id, profile: plugin.profile, slide, state, documentPass }), timeoutMs);
+      if (!result || !Array.isArray(result.diagnostics) || !Array.isArray(result.failures) || !Array.isArray(result.executed)) throw new Error('Invalid plugin result');
+      for (const d of result.diagnostics) {
+        const rule = plugin.rules.find(r => r.code === d.code);
+        if (!rule || d.severity !== rule.severity || typeof d.message !== 'string') throw new Error('Invalid plugin diagnostic');
+        diagnostics.push({ ...d, plugin: plugin.id });
+      }
+      plugin.executed = [...new Set([...plugin.executed, ...result.executed])];
+      for (const err of result.failures) diagnostics.push(failure(plugin.id, 'CHECK_RULE_FAILED', `${err.code}: ${err.message}`));
+      if (result.failures.length) {
+        plugin.status = 'failed';
+        resolution.notChecked.push(`plugin ${plugin.id} · rule execution failed`);
+      }
+    } catch (error) {
+      plugin.status = 'failed';
+      diagnostics.push(failure(plugin.id, 'CHECK_PLUGIN_FAILED', error.message));
+      resolution.notChecked.push(`plugin ${plugin.id} · execution incomplete`);
+    }
+  }
+  return diagnostics;
+}
+
+export function pluginReport(resolution) {
+  return resolution.plugins.map(({ script, skills, ...plugin }) => ({ ...plugin,
+    status: plugin.status === 'loaded' ? 'completed' : plugin.status }));
+}