@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/registry/custom-schema.mjs

@@ -0,0 +1,137 @@
+/**
+ * lib/registry/custom-schema.mjs — validation contract for user-authored custom
+ * specialists and teams (construct-rf26.13).
+ *
+ * Hand-rolled validator, matching the style already established by
+ * lib/specialists/schema.mjs and lib/config/schema.mjs, rather than pulling in
+ * a schema-validation dependency: every error names the offending field and
+ * says what to do about it, so a scaffold failure is actionable without
+ * cross-referencing a generic validator dump. Reuses lib/specialists/schema.mjs's
+ * ALLOWED_TOOLS allowlist so a custom specialist is held to the same
+ * claudeTools contract as a built-in one.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { ALLOWED_TOOLS } from '../specialists/schema.mjs';
+
+export const MODEL_TIERS = ['fast', 'standard', 'reasoning'];
+const SKILL_REF_RE = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+const ID_RE = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Validate one custom specialist record. Returns an array of actionable error
+ * strings; empty means the record passes.
+ */
+export function validateCustomSpecialist(record, { rootDir, checkPromptFileExists = true } = {}) {
+  const errors = [];
+  const id = record?.name || '(unnamed)';
+
+  if (!record || typeof record !== 'object') {
+    return [`custom specialist: record must be an object`];
+  }
+
+  if (!record.name || !ID_RE.test(record.name)) {
+    errors.push(`${id}: "name" must be lowercase kebab-case (e.g. "widget-specialist"), got ${JSON.stringify(record.name)}`);
+  }
+
+  if (!record.description || String(record.description).trim().length < 20) {
+    errors.push(`${id}: "description" is required and must be at least 20 characters — it is load-bearing for orchestration routing`);
+  } else if (String(record.description).length > 500) {
+    errors.push(`${id}: "description" is too long (>500 chars) — keep it scannable`);
+  }
+
+  if (!record.role || typeof record.role !== 'string') {
+    errors.push(`${id}: "role" is required (e.g. "widget-specialist") — a team's "owner" field must match a specialist's "role" for the team to validate`);
+  }
+
+  if (!record.modelTier || !MODEL_TIERS.includes(record.modelTier)) {
+    errors.push(`${id}: "modelTier" must be one of ${MODEL_TIERS.join(' | ')}, got ${JSON.stringify(record.modelTier)}`);
+  }
+
+  const team = record.team || record.teamId;
+  if (!team || typeof team !== 'string') {
+    errors.push(`${id}: "team" (or "teamId") is required — reference an existing team id, or create one first with \`construct team create <id> --owner=${record.role || '<role>'}\``);
+  }
+
+  if (!Array.isArray(record.skills) || record.skills.length === 0) {
+    errors.push(`${id}: "skills" must be a non-empty array of skill bundle references (e.g. ["frontend-design/accessibility"])`);
+  } else {
+    record.skills.forEach((skill, i) => {
+      if (typeof skill !== 'string' || !SKILL_REF_RE.test(skill)) {
+        errors.push(`${id}: skills[${i}] "${skill}" is not a valid skill bundle reference — expected "<bundle>/<skill>" (e.g. "frontend-design/accessibility")`);
+      }
+    });
+  }
+
+  if (!record.fence || typeof record.fence !== 'object' || Array.isArray(record.fence)) {
+    errors.push(`${id}: "fence" is required — at minimum { "allowedPaths": [...] } to declare the permission boundary`);
+  } else if (!Array.isArray(record.fence.allowedPaths) || record.fence.allowedPaths.length === 0) {
+    errors.push(`${id}: "fence.allowedPaths" must be a non-empty array of path globs this specialist may touch`);
+  }
+
+  if (record.handoffCandidates !== undefined && !Array.isArray(record.handoffCandidates)) {
+    errors.push(`${id}: "handoffCandidates" must be an array of role ids (the delegation spec — who this specialist hands off to)`);
+  }
+
+  if (record.claudeTools) {
+    const tools = String(record.claudeTools).split(',').map((t) => t.trim()).filter(Boolean);
+    for (const tool of tools) {
+      if (!ALLOWED_TOOLS.has(tool)) {
+        errors.push(`${id}: unknown tool "${tool}" in claudeTools — host platforms silently drop unknown tool names, causing this specialist to appear to work without it`);
+      }
+    }
+  }
+
+  if (checkPromptFileExists && record.promptFile && rootDir) {
+    const promptPath = path.join(rootDir, record.promptFile);
+    if (!fs.existsSync(promptPath)) {
+      errors.push(`${id}: promptFile "${record.promptFile}" does not exist under ${rootDir}`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate one custom team record. Returns an array of actionable error
+ * strings; empty means the record passes.
+ */
+export function validateCustomTeam(record) {
+  const errors = [];
+  const id = record?.id || record?.name || '(unnamed)';
+
+  if (!record || typeof record !== 'object') {
+    return [`custom team: record must be an object`];
+  }
+
+  if (!record.name || typeof record.name !== 'string') {
+    errors.push(`${id}: "name" is required (human-readable team name, e.g. "Widget Team")`);
+  }
+
+  if (!record.owner || typeof record.owner !== 'string') {
+    errors.push(`${id}: "owner" is required — the role id that holds primary accountability (must match a specialist's "role" field)`);
+  }
+
+  if (!Array.isArray(record.roles) || record.roles.length === 0) {
+    errors.push(`${id}: "roles" must be a non-empty array of role ids that constitute this team`);
+  } else if (record.owner && !record.roles.includes(record.owner)) {
+    errors.push(`${id}: "roles" must include the owner role "${record.owner}"`);
+  }
+
+  if (!record.charter || String(record.charter).trim().length < 20) {
+    errors.push(`${id}: "charter" is required and must be at least 20 characters — a one-paragraph mission statement for what this team owns`);
+  }
+
+  for (const field of ['decisionRights', 'forbiddenDecisions', 'escalationPath', 'specialists']) {
+    if (record[field] !== undefined && !Array.isArray(record[field])) {
+      errors.push(`${id}: "${field}" must be an array of strings when present`);
+    }
+  }
+
+  if (record.contact !== undefined && (typeof record.contact !== 'object' || Array.isArray(record.contact))) {
+    errors.push(`${id}: "contact" must be an object when present (e.g. { "slack": "#team", "owner": "role-id" })`);
+  }
+
+  return errors;
+}

package/lib/registry/loader.mjs

@@ -10,12 +10,17 @@
 
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
 import { validate } from './validator.mjs';
 import { assembleRegistry, orgDirMtime, listTeamsFromRegistry, listGroupsHierarchical } from './assemble.mjs';
+import { packageRoot } from '../roots.mjs';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ROOT_DIR = path.resolve(__dirname, '..', '..');
+// packageRoot (not a local __dirname-derived constant) because under a
+// Bun-compiled binary every bundled module's import.meta.url collapses to
+// the same virtual /$bunfs/root path, losing this file's real nesting
+// under lib/registry/; packageRoot already falls back to the compiled
+// binary's real on-disk directory (see lib/roots.mjs).
+
+const ROOT_DIR = packageRoot;
 
 let _registry = null;
 let _rootDir = null;

package/lib/registry/manifests/format-engines.default.json

@@ -0,0 +1,15 @@
+{
+  "pdf": { "engine": "pandoc", "writer": null, "pdfEngine": "typst", "extraBinaries": ["typst"] },
+  "docx": { "engine": "pandoc", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "doc": { "engine": "pandoc", "writer": null, "pdfEngine": null, "extraBinaries": [], "via": "libreoffice", "intermediate": "docx" },
+  "deck": { "engine": "pandoc", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "pptx": { "engine": "pptxgenjs", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "html": { "engine": "pandoc", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "rtf": { "engine": "pandoc", "writer": "rtf", "pdfEngine": null, "extraBinaries": [] },
+  "odt": { "engine": "pandoc", "writer": "odt", "pdfEngine": null, "extraBinaries": [] },
+  "epub": { "engine": "pandoc", "writer": "epub", "pdfEngine": null, "extraBinaries": [] },
+  "tex": { "engine": "pandoc", "writer": "latex", "pdfEngine": null, "extraBinaries": [] },
+  "txt": { "engine": "pandoc", "writer": "plain", "pdfEngine": null, "extraBinaries": [] },
+  "md": { "engine": "copy", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "mdx": { "engine": "copy", "writer": null, "pdfEngine": null, "extraBinaries": [] }
+}

package/lib/registry/manifests/surface-map.default.json

@@ -0,0 +1,46 @@
+{
+  "tiers": ["agent-mcp", "thin-cli", "tui", "internal"],
+  "commands": {
+    "install": "thin-cli",
+    "init": "thin-cli",
+    "dev": "thin-cli",
+    "stop": "thin-cli",
+    "status": "thin-cli",
+    "doctor": "thin-cli",
+    "sync": "thin-cli",
+    "ingest": "agent-mcp",
+    "drop": "agent-mcp",
+    "distill": "agent-mcp",
+    "ask": "agent-mcp",
+    "search": "agent-mcp",
+    "knowledge": "agent-mcp",
+    "memory": "agent-mcp",
+    "reflect": "agent-mcp",
+    "intake": "tui",
+    "workflow": "agent-mcp",
+    "graph": "agent-mcp",
+    "capability": "agent-mcp",
+    "execution": "agent-mcp",
+    "orchestrate": "agent-mcp",
+    "models": "agent-mcp",
+    "profile": "tui",
+    "sandbox": "tui",
+    "review": "thin-cli",
+    "telemetry": "thin-cli",
+    "evals": "thin-cli",
+    "improvement": "thin-cli",
+    "ci": "thin-cli",
+    "docs": "thin-cli",
+    "export": "agent-mcp",
+    "diagram": "agent-mcp",
+    "demo": "agent-mcp",
+    "beads": "thin-cli",
+    "hook": "internal",
+    "lint:comments": "internal",
+    "lint:agents": "internal",
+    "registry:status": "internal",
+    "registry:validate": "internal",
+    "registry:generate-docs": "internal",
+    "rules": "thin-cli"
+  }
+}

package/lib/registry/retired-paths.mjs

@@ -29,6 +29,7 @@ export const RETIRED_REGISTRY_PATH_ALLOWLIST = Object.freeze([
   'scripts/patch-registry-readers-v2.mjs',
   'tests/no-monolithic-registry.test.mjs',
   'tests/migration-round-trip.test.mjs',
+  'tests/fixtures/mcp-tool-schemas/results/project_context.result.json',
 ]);
 
 export function isRetiredRegistryPathAllowed(relPath) {

package/lib/registry/surface-map.mjs

@@ -3,6 +3,12 @@
  *
  * Declarative map from CLI command name to primary surface tier. The CLI registry
  * remains the substrate; this file governs discovery posture without removing verbs.
+ * LMCP-B7: the tiers/command map ship as lib/registry/manifests/surface-map.default.json
+ * (loaded once at module init — this file's exports stay byte-identical to the prior
+ * hardcoded dict) with an optional `.cx/registry/surface-map.json` project override
+ * merged in per-call by resolveSurfaceMap()/surfaceForCommand()/validateSurfaceMap().
+ * An override may add or reassign command entries and replace the tier list; it can
+ * never remove a default entry outright (unset keys keep resolving to the default).
  *
  * Surfaces:
  *   agent-mcp — MCP tool canonical; CLI --json twin
@@ -11,64 +17,108 @@
  *   internal  — CI/harness only
  */
 
-export const SURFACE_TIERS = ['agent-mcp', 'thin-cli', 'tui', 'internal'];
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { packageRoot } from '../roots.mjs';
+
+// packageRoot (not a local import.meta.url-derived HERE) because under a
+// Bun-compiled binary every bundled module's import.meta.url collapses to
+// the same virtual /$bunfs/root path, losing this file's real nesting
+// under lib/registry/ — packageRoot already falls back to the compiled
+// binary's real on-disk directory (see lib/roots.mjs), so rebuilding the
+// known relative path from it resolves correctly in every run mode.
+
+const DEFAULT_MANIFEST_PATH = path.join(packageRoot, 'lib', 'registry', 'manifests', 'surface-map.default.json');
+
+function readJsonIfExists(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function loadDefaultManifest() {
+  const manifest = readJsonIfExists(DEFAULT_MANIFEST_PATH);
+  if (!manifest || !Array.isArray(manifest.tiers) || typeof manifest.commands !== 'object') {
+    throw new Error(`lib/registry/surface-map.mjs: missing or malformed default manifest at ${DEFAULT_MANIFEST_PATH}`);
+  }
+  return manifest;
+}
+
+const DEFAULT_MANIFEST = loadDefaultManifest();
+
+// Byte-identical to the pre-manifest hardcoded exports: both are read once at
+// module init from the default manifest, with no project override applied —
+// a direct import of these two names sees exactly the shipped defaults.
+
+export const SURFACE_TIERS = DEFAULT_MANIFEST.tiers;
 
 /** @type {Record<string, string>} */
-export const COMMAND_SURFACE = {
-  install: 'thin-cli',
-  init: 'thin-cli',
-  dev: 'thin-cli',
-  stop: 'thin-cli',
-  status: 'thin-cli',
-  doctor: 'thin-cli',
-  sync: 'thin-cli',
-  ingest: 'agent-mcp',
-  drop: 'agent-mcp',
-  distill: 'agent-mcp',
-  ask: 'agent-mcp',
-  search: 'agent-mcp',
-  knowledge: 'agent-mcp',
-  memory: 'agent-mcp',
-  reflect: 'agent-mcp',
-  intake: 'tui',
-  workflow: 'agent-mcp',
-  graph: 'agent-mcp',
-  capability: 'agent-mcp',
-  execution: 'agent-mcp',
-  orchestrate: 'agent-mcp',
-  models: 'agent-mcp',
-  profile: 'tui',
-  sandbox: 'tui',
-  review: 'thin-cli',
-  telemetry: 'thin-cli',
-  evals: 'thin-cli',
-  improvement: 'thin-cli',
-  ci: 'thin-cli',
-  docs: 'thin-cli',
-  export: 'agent-mcp',
-  diagram: 'agent-mcp',
-  demo: 'agent-mcp',
-  beads: 'thin-cli',
-  hook: 'internal',
-  'lint:comments': 'internal',
-  'lint:agents': 'internal',
-  'registry:status': 'internal',
-  'registry:validate': 'internal',
-  'registry:generate-docs': 'internal',
-  rules: 'thin-cli',
-};
-
-export function surfaceForCommand(name) {
-  if (COMMAND_SURFACE[name]) return COMMAND_SURFACE[name];
+export const COMMAND_SURFACE = DEFAULT_MANIFEST.commands;
+
+const overrideCache = new Map();
+
+function loadOverride(cwd) {
+  if (overrideCache.has(cwd)) return overrideCache.get(cwd);
+  const override = readJsonIfExists(path.join(cwd, '.cx', 'registry', 'surface-map.json'));
+  overrideCache.set(cwd, override);
+  return override;
+}
+
+/**
+ * resolveSurfaceMap({ cwd } = {})
+ *
+ * Merges the default manifest with a project's `.cx/registry/surface-map.json`
+ * override, when present. `commands` in the override are shallow-merged over
+ * the default (an override entry replaces the matching default; every other
+ * default entry survives untouched). `tiers` in the override replaces the
+ * default tier list wholesale when present.
+ */
+export function resolveSurfaceMap({ cwd = process.cwd() } = {}) {
+  const override = loadOverride(cwd);
+  if (!override) return { tiers: SURFACE_TIERS, commands: COMMAND_SURFACE };
+  const tiers = Array.isArray(override.tiers) ? override.tiers : SURFACE_TIERS;
+  const commands = { ...COMMAND_SURFACE, ...(override.commands && typeof override.commands === 'object' ? override.commands : {}) };
+  return { tiers, commands };
+}
+
+export function surfaceForCommand(name, { cwd = process.cwd() } = {}) {
+  const { commands } = resolveSurfaceMap({ cwd });
+  if (commands[name]) return commands[name];
   if (name.includes(':')) return 'internal';
   return 'thin-cli';
 }
 
-export function commandsBySurface(commands) {
-  const grouped = Object.fromEntries(SURFACE_TIERS.map((t) => [t, []]));
+export function commandsBySurface(commands, { cwd = process.cwd() } = {}) {
+  const { tiers } = resolveSurfaceMap({ cwd });
+  const grouped = Object.fromEntries(tiers.map((t) => [t, []]));
   for (const cmd of commands) {
-    const surface = cmd.surface ?? surfaceForCommand(cmd.name);
+    const surface = cmd.surface ?? surfaceForCommand(cmd.name, { cwd });
     grouped[surface]?.push(cmd.name);
   }
   return grouped;
 }
+
+/**
+ * validateSurfaceMap(commandNames, { cwd } = {})
+ *
+ * Stricter than surfaceForCommand's runtime fallback: every name must have an
+ * explicit entry in the resolved (default + override) command map. This is an
+ * opt-in registry/doctor-style check, separate from the CLI's own dispatch
+ * path, so the default fallback behavior for unregistered commands stays
+ * unaffected.
+ */
+export function validateSurfaceMap(commandNames, { cwd = process.cwd() } = {}) {
+  const { commands } = resolveSurfaceMap({ cwd });
+  const errors = commandNames
+    .filter((name) => !commands[name])
+    .map((name) => `command '${name}' has no surface-map entry (add one to .cx/registry/surface-map.json or lib/registry/manifests/surface-map.default.json)`);
+  return { valid: errors.length === 0, errors };
+}
+
+export function __clearSurfaceMapOverrideCache() {
+  overrideCache.clear();
+}

package/lib/render-visual-check.mjs

@@ -0,0 +1,240 @@
+/**
+ * lib/render-visual-check.mjs — rendered-artifact visual gate for the test:visual script.
+ *
+ * Exports a fixture through the real document-export engines (Pandoc/Typst for PDF, pptxgenjs for
+ * PPTX, Pandoc for DOCX) and asserts what a source-level check cannot: (1) for pdf/pptx — the same
+ * RENDER_REQUIRED_FORMATS output-quality.mjs already treats as render-required — every rasterized
+ * page carries real ink, not a blank/near-blank canvas from a broken template or missing font,
+ * decoded straight from the produced PNG's own IDAT stream with zlib inflate plus PNG filter
+ * reconstruction (no image-decoding dependency needed); (2) runOutputQuality's text-extraction-
+ * parity and on-disk reference-integrity checks pass against the produced file for every format,
+ * reusing the same gate publish.mjs enforces; (3) a renderer required for the requested format that
+ * is absent is reported as a typed, CI-visible failure reason, never a silent skip, because a
+ * visual claim that rests on a tool that was never invoked is not a visual claim. docx has no
+ * raster path in render-pipeline.mjs (only pdf/html/pptx/mermaid/d2), so it is validated via export
+ * plus text/reference checks only, matching the existing render-required contract.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import zlib from 'node:zlib';
+
+import { exportMarkdown, whichBin } from './document-export.mjs';
+import { runOutputQuality } from './output-quality.mjs';
+
+// Below this ink ratio a rasterized page is treated as blank: a faithful export of a
+// multi-paragraph fixture always covers more of the canvas than antialiasing noise or a stray
+// hairline would produce.
+
+const MIN_INK_RATIO = 0.01;
+
+// Formats output-quality.mjs already treats as render-required (RENDER_REQUIRED_FORMATS); only
+// these get rasterized and blank-page checked. docx has no renderer in render-pipeline.mjs.
+
+const RASTER_FORMATS = new Set(['pdf', 'pptx']);
+
+function readPngChunks(pngPath) {
+  const buf = fs.readFileSync(pngPath);
+  const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  if (!buf.subarray(0, 8).equals(sig)) throw new Error(`${pngPath}: not a PNG (bad signature)`);
+
+  let offset = 8;
+  let header = null;
+  const idatParts = [];
+  while (offset < buf.length) {
+    const len = buf.readUInt32BE(offset);
+    const type = buf.toString('ascii', offset + 4, offset + 8);
+    const data = buf.subarray(offset + 8, offset + 8 + len);
+    if (type === 'IHDR') {
+      header = {
+        width: data.readUInt32BE(0),
+        height: data.readUInt32BE(4),
+        bitDepth: data.readUInt8(8),
+        colorType: data.readUInt8(9),
+      };
+    }
+    if (type === 'IDAT') idatParts.push(data);
+    offset += 8 + len + 4;
+    if (type === 'IEND') break;
+  }
+  if (!header) throw new Error(`${pngPath}: missing IHDR chunk`);
+  if (header.bitDepth !== 8) throw new Error(`${pngPath}: unsupported bit depth ${header.bitDepth} (need 8)`);
+  const channels = { 0: 1, 2: 3, 4: 2, 6: 4 }[header.colorType];
+  if (!channels) throw new Error(`${pngPath}: unsupported color type ${header.colorType}`);
+  return { ...header, channels, raw: zlib.inflateSync(Buffer.concat(idatParts)) };
+}
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+
+// Reverses the per-scanline PNG filter (none/sub/up/average/paeth) so pixel values are real
+// sample bytes rather than filter-encoded deltas.
+
+function unfilterPng({ width, height, channels, raw }) {
+  const stride = width * channels;
+  const bpp = channels;
+  const out = Buffer.alloc(height * stride);
+  let pos = 0;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[pos];
+    pos += 1;
+    const rowStart = y * stride;
+    for (let x = 0; x < stride; x++) {
+      const val = raw[pos + x];
+      const a = x >= bpp ? out[rowStart + x - bpp] : 0;
+      const b = y > 0 ? out[rowStart - stride + x] : 0;
+      const c = x >= bpp && y > 0 ? out[rowStart - stride + x - bpp] : 0;
+      let recon;
+      if (filter === 0) recon = val;
+      else if (filter === 1) recon = val + a;
+      else if (filter === 2) recon = val + b;
+      else if (filter === 3) recon = val + Math.floor((a + b) / 2);
+      else if (filter === 4) recon = val + paeth(a, b, c);
+      else throw new Error(`unsupported PNG filter type ${filter} at row ${y}`);
+      out[rowStart + x] = recon & 0xff;
+    }
+    pos += stride;
+  }
+  return out;
+}
+
+// Fraction of pixels that are not near-white (allows antialiasing/JPEG-adjacent noise near 255).
+
+export function inkRatio(pngPath) {
+  const decoded = readPngChunks(pngPath);
+  const pixels = unfilterPng(decoded);
+  const { channels } = decoded;
+  let inked = 0;
+  let total = 0;
+  for (let i = 0; i < pixels.length; i += channels) {
+    total += 1;
+    const r = pixels[i];
+    const g = channels >= 2 ? pixels[i + 1] : r;
+    const b = channels >= 3 ? pixels[i + 2] : r;
+    if (r < 245 || g < 245 || b < 245) inked += 1;
+  }
+  return total === 0 ? 0 : inked / total;
+}
+
+function rasterizePdf(pdfPath, outDir) {
+  const result = spawnSync('pdftoppm', ['-png', '-r', '72', pdfPath, path.join(outDir, 'page')], { encoding: 'utf8' });
+  if (result.status !== 0) throw new Error(`pdftoppm failed: ${(result.stderr || '').trim()}`);
+  return fs.readdirSync(outDir)
+    .filter((f) => f.startsWith('page') && f.endsWith('.png'))
+    .sort()
+    .map((f) => path.join(outDir, f));
+}
+
+// pptx has no direct rasterizer; render-pipeline.mjs's own pptx path goes soffice -> pdf ->
+// pdftoppm, so this mirrors that exact chain rather than inventing a second one.
+
+function rasterizePptx(pptxPath, outDir, env) {
+  const soffice = whichBin('soffice', env) || whichBin('libreoffice', env);
+  if (!soffice) return { ok: false, reason: 'missing-dependency', message: 'soffice/libreoffice not on PATH' };
+  const conv = spawnSync(soffice, ['--headless', '--convert-to', 'pdf', '--outdir', outDir, pptxPath], { encoding: 'utf8' });
+  if (conv.status !== 0) return { ok: false, reason: 'unavailable-renderer', message: (conv.stderr || '').trim() || 'soffice convert failed' };
+  const pdf = path.join(outDir, `${path.parse(pptxPath).name}.pdf`);
+  if (!fs.existsSync(pdf)) return { ok: false, reason: 'unavailable-renderer', message: 'soffice produced no pdf' };
+  return { ok: true, images: rasterizePdf(pdf, outDir) };
+}
+
+const REQUIRED_ENGINES = {
+  pdf: ['pandoc', 'typst', 'pdftoppm'],
+  pptx: ['pandoc', 'soffice', 'pdftoppm'],
+  docx: ['pandoc'],
+};
+
+export function requiredEngineStatus(format, env = process.env) {
+  const names = REQUIRED_ENGINES[format] || [];
+  const missing = names.filter((name) => {
+    if (name === 'soffice') return !whichBin('soffice', env) && !whichBin('libreoffice', env);
+    return !whichBin(name, env);
+  });
+  return { format, required: names, missing, present: missing.length === 0 };
+}
+
+// Runs the full rendered-artifact gate for one format: export via the real engine, rasterize when
+// the format is render-required, assert non-blank pages, and run the shared output-quality checks
+// (text parity + references) against the produced file. Returns a typed failure (never throws)
+// when a required engine is absent, so the caller can fail the process loudly instead of skipping.
+
+export function checkRenderedArtifact({ fixturePath, format, workDir, env = process.env } = {}) {
+  const engineStatus = requiredEngineStatus(format, env);
+  if (!engineStatus.present) {
+    const message = `test:visual requires real engines for ${format} but ${engineStatus.missing.join(', ')} ${engineStatus.missing.length > 1 ? 'are' : 'is'} not on PATH. Install: ${engineStatus.missing.join(', ')}. This is a hard failure: a rendered-artifact claim cannot rest on a tool that never ran.`;
+    return { ok: false, format, skipped: false, reason: 'missing-dependency', message, failures: [message] };
+  }
+
+  const dir = workDir || fs.mkdtempSync(path.join(os.tmpdir(), `cx-visual-${format}-`));
+  const outputPath = path.join(dir, `artifact.${format}`);
+  const sourceMarkdown = fs.readFileSync(fixturePath, 'utf8');
+
+  const exported = exportMarkdown({ inputPath: fixturePath, outputPath, format, env });
+  if (!exported.ok) {
+    const message = `export failed for ${format}: ${exported.message}`;
+    return { ok: false, format, skipped: false, reason: 'export-failed', message, failures: [message] };
+  }
+
+  let images = [];
+  if (RASTER_FORMATS.has(format)) {
+    if (format === 'pdf') {
+      images = rasterizePdf(outputPath, dir);
+    } else {
+      const raster = rasterizePptx(outputPath, dir, env);
+      if (!raster.ok) {
+        const message = `rasterize failed for ${format}: ${raster.message}`;
+        return { ok: false, format, skipped: false, reason: raster.reason, message, failures: [message] };
+      }
+      images = raster.images;
+    }
+    if (images.length === 0) {
+      const message = `${format} export produced zero rasterizable pages`;
+      return { ok: false, format, skipped: false, reason: 'no-pages', message, failures: [message] };
+    }
+  }
+
+  const blankPages = [];
+  const ratios = [];
+  for (const image of images) {
+    const ratio = inkRatio(image);
+    ratios.push(ratio);
+    if (ratio < MIN_INK_RATIO) blankPages.push({ image, ratio });
+  }
+
+  const quality = runOutputQuality({
+    exportPath: outputPath,
+    format,
+    sourceMarkdown,
+    baseDir: path.dirname(fixturePath),
+    gateLevel: 'render-smoke',
+    env,
+  });
+
+  const failures = [];
+  if (blankPages.length > 0) {
+    failures.push(`${blankPages.length}/${images.length} rendered page(s) are blank (ink ratio < ${MIN_INK_RATIO}): ${blankPages.map((p) => `${path.basename(p.image)}=${p.ratio.toFixed(4)}`).join(', ')}`);
+  }
+  for (const f of quality.failures) failures.push(f);
+
+  return {
+    ok: failures.length === 0,
+    format,
+    skipped: false,
+    pageCount: images.length,
+    inkRatios: ratios,
+    quality,
+    failures,
+    message: failures.length === 0
+      ? `${format}: ${images.length ? `${images.length} page(s) rendered, all non-blank; ` : ''}text parity and references verified`
+      : failures.join('; '),
+  };
+}