dsh-archify-projects 0.0.0-stage → 0.1.0

package/skills/archify/renderers/shared/cli.mjs

@@ -0,0 +1,451 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { applyTemplate, renderCards, esc } from './utils.mjs';
+import { validateSchema } from './validator.mjs';
+import { verifyRepositoryEvidence } from './repository-evidence.mjs';
+import { installRendererDiagnosticBoundary, throwDiagnosticError, throwDiagnosticProblems, recordDiagnostic } from './diagnostics.mjs';
+import { validateEngineeringProfile } from './engineering-profiles.mjs';
+import {
+  resolveOutputPath,
+  validateAuthoredOutputPath,
+} from './output-path.mjs';
+import {
+  captureAtomicOutput,
+  captureRegularFileBinding,
+  publishRegularFileBinding,
+  releaseRegularFileBinding,
+  removeOwnedRegularFile,
+  verifyAtomicOutput,
+} from './atomic-output.mjs';
+import { resolveLocale, translateMessage, registerLocale, SUPPORTED_LOCALES } from './i18n.mjs';
+import { prepareDiagramBrandMarks } from './brand-marks.mjs';
+
+const outputPathGuards = new Map();
+let renderCandidateSequence = 0;
+
+// meta.locale is renderer-owned Viewer UI, not authored content.
+// en and zh-CN ship as built-in catalogs.
+// Any other tag needs meta.translations (validated against the English
+// message-key set, layered over English per-key so partial/invalid entries
+// never break rendering) or it falls back to the English Viewer chrome —
+// the same "omit locale, disclose the fallback" contract as before, just
+// resolved from data instead of a hard-coded enum. See i18n.mjs.
+function applyLocaleTranslations(diagramType, diagram) {
+  const locale = diagram.meta?.locale;
+  if (!locale) return;
+  const translations = diagram.meta?.translations;
+  if (translations && Object.keys(translations).length) {
+    const report = registerLocale(locale, translations);
+    if (report.missingKeys.length || report.unknownKeys.length || report.placeholderMismatches.length) {
+      recordDiagnostic({
+        code: 'i18n/translation-coverage',
+        severity: 'warning',
+        message: `meta.translations for locale ${JSON.stringify(locale)} covers ${report.coveredKeys}/${report.totalKeys} renderer-owned messages (${Math.round(report.coverage * 100)}%); uncovered keys fall back to English.`,
+        subject: { diagramType, path: '/meta/translations' },
+        evidence: {
+          missingKeys: report.missingKeys.slice(0, 10),
+          missingKeysTotal: report.missingKeys.length,
+          unknownKeys: report.unknownKeys.slice(0, 10),
+          unknownKeysTotal: report.unknownKeys.length,
+          placeholderMismatches: report.placeholderMismatches.slice(0, 10),
+          placeholderMismatchesTotal: report.placeholderMismatches.length,
+        },
+        supportedFixes: ['Add the missing keys to meta.translations.', 'Match each translation\'s {placeholders} to the English source string.'],
+      });
+      // Coverage is a fact about this render, not just a diagnostic-mode
+      // artifact: print it to stderr unconditionally so `render`/`deliver`/
+      // `validate` disclose the fallback even without ARCHIFY_DIAGNOSTIC_FORMAT.
+      console.warn(`archify: meta.translations for locale ${JSON.stringify(locale)} covers ${report.coveredKeys}/${report.totalKeys} renderer-owned messages (${Math.round(report.coverage * 100)}%); uncovered keys fall back to English.`);
+    }
+  } else if (!SUPPORTED_LOCALES.includes(locale)) {
+    recordDiagnostic({
+      code: 'i18n/locale-fallback',
+      severity: 'warning',
+      message: `meta.locale ${JSON.stringify(locale)} has no built-in catalog and no meta.translations; the Viewer chrome and <html lang> fall back to English.`,
+      subject: { diagramType, path: '/meta/locale' },
+      supportedFixes: ['Supply meta.translations for this locale.', `Use a built-in locale: ${SUPPORTED_LOCALES.join(', ')}.`],
+    });
+    console.warn(`archify: meta.locale ${JSON.stringify(locale)} has no built-in catalog and no meta.translations; the Viewer chrome and <html lang> fall back to English.`);
+  }
+}
+
+// Common CLI head: node render-<type>.mjs [input.json] [output.html]
+// Keep this synchronous because callers also use it to establish the guarded
+// output path before testing a last-moment filesystem alias change.
+export function loadDiagram({ rendererDir, diagramType, defaultExample, argv = process.argv }) {
+  // Compilers also import this module for SVG helpers. Only CLI execution
+  // should install a process-level handler, before reading or validating input.
+  installRendererDiagnosticBoundary();
+  const skillRoot = path.resolve(rendererDir, '../..');
+  const inputPath = path.resolve(argv[2] || path.join(skillRoot, 'examples', defaultExample));
+  let input;
+  try {
+    input = fs.readFileSync(inputPath, 'utf8');
+  } catch (error) {
+    if (!isFilesystemError(error)) throw error;
+    const message = `Input could not be read: ${error.message}`;
+    throwDiagnosticError(message, [{
+      code: 'input/read', message,
+      subject: { input: inputPath },
+      evidence: { systemCode: error.code, reason: error.message },
+      supportedFixes: ['provide one readable JSON input file'],
+    }]);
+  }
+  let diagram;
+  try {
+    diagram = JSON.parse(input);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    const message = `Input JSON could not be parsed: ${error.message}`;
+    throwDiagnosticError(message, [{
+      code: 'input/json-parse', message,
+      subject: { input: inputPath },
+      evidence: { reason: error.message },
+      supportedFixes: ['repair the JSON syntax and run validation again'],
+    }]);
+  }
+  const authoredOutput = diagram?.meta?.output;
+  if (authoredOutput !== undefined) validateAuthoredOutputPath(authoredOutput);
+  validateSchema(diagramType, diagram);
+  applyLocaleTranslations(diagramType, diagram);
+  validateCrossCollectionContracts(diagramType, diagram);
+  validateEngineeringProfile(diagramType, diagram);
+  const sourceEvidence = verifyRepositoryEvidence(diagramType, diagram, process.env.ARCHIFY_REPO_ROOT);
+  const template = fs.readFileSync(path.join(skillRoot, 'assets/template.html'), 'utf8');
+  const outputRequest = {
+    requestedOutput: argv[3],
+    authoredOutput: diagram.meta?.output,
+    defaultOutput: `${diagramType}.html`,
+    inputPaths: [inputPath],
+    cwd: process.cwd(),
+  };
+  let outPath;
+  try {
+    ({ outputPath: outPath } = resolveOutputPath(outputRequest));
+  } catch (error) {
+    throwOutputError(error, path.resolve(outputRequest.requestedOutput || outputRequest.authoredOutput || outputRequest.defaultOutput));
+  }
+  outputPathGuards.set(outPath, outputRequest);
+  return { diagram, template, outPath, sourceEvidence };
+}
+
+// Brand URL capture is the only asynchronous authoring step. Typed renderers
+// opt into it through this wrapper without changing loadDiagram's long-lived
+// synchronous safety contract.
+export async function loadDiagramWithBrandMarks(options) {
+  const loaded = loadDiagram(options);
+  await prepareDiagramBrandMarks(options.diagramType, loaded.diagram);
+  return loaded;
+}
+
+const START_TYPES = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle']);
+
+function isFilesystemError(error) {
+  return typeof error?.code === 'string'
+    && typeof error?.syscall === 'string'
+    && typeof error?.errno === 'number';
+}
+
+function throwOutputError(error, output) {
+  if (error?.archifyDiagnostics || !isFilesystemError(error)) throw error;
+  const message = `Output could not be written: ${error.message}`;
+  throwDiagnosticError(message, [{
+    code: 'output/write', message,
+    subject: { output },
+    evidence: { systemCode: error.code, reason: error.message },
+    supportedFixes: ['choose a writable HTML file path and ensure its parent directories can be created'],
+  }]);
+}
+
+function throwAtomicOutputFailure(result, output) {
+  const reason = result.reason || { code: 'unclassified' };
+  const changed = result.status === 'different';
+  const candidate = reason.code.startsWith('candidate-');
+  const nonRegular = ['target-not-regular-file', 'candidate-not-regular-file'].includes(reason.code);
+  const hardlinked = ['target-hardlinked', 'candidate-hardlinked'].includes(reason.code);
+  const message = changed
+    ? 'Output target changed while the rendered artifact was being prepared.'
+    : nonRegular
+      ? candidate
+        ? 'Temporary output candidate is no longer a regular file.'
+        : 'Output already exists and is not a regular file.'
+      : hardlinked
+        ? candidate
+          ? 'Temporary output candidate has multiple hard-link names.'
+          : 'Output already exists through multiple hard-link names.'
+        : 'Output target stability could not be determined safely before commit.';
+  throwDiagnosticError(message, [{
+    code: changed
+      ? 'output/target-changed'
+      : nonRegular
+        ? 'output/target-not-regular-file'
+        : hardlinked
+          ? 'output/target-hardlinked'
+          : 'output/target-indeterminate',
+    message,
+    subject: { output },
+    evidence: { relation: reason },
+    supportedFixes: [hardlinked
+      ? 'choose a non-hardlinked output path; atomic replacement cannot update every hard-link name'
+      : 'retry after other processes stop replacing or redirecting the output path'],
+  }]);
+}
+
+function stageRenderedHtml(outputPath, html, mode) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    renderCandidateSequence += 1;
+    const candidatePath = path.join(
+      path.dirname(outputPath),
+      `.archify-render-${process.pid}-${Date.now().toString(36)}-${renderCandidateSequence}.tmp`,
+    );
+    let descriptor;
+    let identity;
+    try {
+      const noFollow = process.platform === 'win32' ? 0 : (fs.constants.O_NOFOLLOW || 0);
+      descriptor = fs.openSync(
+        candidatePath,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow,
+        mode ?? 0o666,
+      );
+      let metadata;
+      try {
+        metadata = fs.fstatSync(descriptor, { bigint: true });
+      } catch (error) {
+        // A transient first inspection failure must not strand the exclusive
+        // candidate. A successful retry binds cleanup to the still-open file;
+        // if both inspections fail, preserving the unknown entry is safer.
+        try {
+          const retry = fs.fstatSync(descriptor, { bigint: true });
+          if (retry.isFile() && retry.ino !== 0n) {
+            identity = { device: retry.dev, inode: retry.ino };
+          }
+        } catch {}
+        throw error;
+      }
+      if (!metadata.isFile() || metadata.ino === 0n) {
+        throw new Error('Temporary render candidate identity could not be verified safely.');
+      }
+      identity = { device: metadata.dev, inode: metadata.ino };
+      fs.writeFileSync(descriptor, html);
+      // Creation modes are filtered through the process umask. An atomic
+      // replacement must retain the exact permissions of an existing target,
+      // while a brand-new target should keep normal umask behavior.
+      if (mode !== null) fs.fchmodSync(descriptor, mode);
+      fs.closeSync(descriptor);
+      descriptor = undefined;
+      return { candidatePath, identity };
+    } catch (error) {
+      if (descriptor !== undefined) {
+        try { fs.closeSync(descriptor); } catch {}
+      }
+      if (error.code === 'EEXIST') continue;
+      if (identity) {
+        const cleanup = removeOwnedRegularFile(candidatePath, identity);
+        if (!['removed', 'absent', 'preserved'].includes(cleanup.status)) {
+          const cleanupError = new Error(`${error.message}; temporary render candidate cleanup also failed.`);
+          cleanupError.cause = error;
+          throw cleanupError;
+        }
+      }
+      throw error;
+    }
+  }
+  const error = new Error(`Could not reserve a temporary render candidate beside "${outputPath}".`);
+  error.code = 'EEXIST';
+  error.errno = -17;
+  error.syscall = 'open';
+  throw error;
+}
+
+// Common CLI tail: fill the template and write the standalone HTML file.
+export function writeDiagram({ outPath, template, diagramType, meta, svg, cards, sourceEvidence = null }) {
+  if (!START_TYPES.has(diagramType)) throw new Error(`writeDiagram: unknown diagram type ${JSON.stringify(diagramType)}`);
+  const outputGuard = outputPathGuards.get(outPath);
+  const html = applyTemplate(template, {
+    title: meta.title,
+    subtitle: meta.subtitle,
+    svg,
+    cards: renderCards(cards),
+    locale: meta.locale,
+    visualPreset: meta.visual_preset || 'classic',
+    sourceEvidence,
+  });
+  let candidatePath;
+  let candidateIdentity;
+  let candidateBinding;
+  try {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    const outputCapture = captureAtomicOutput(outPath);
+    if (outputCapture.status !== 'captured') throwAtomicOutputFailure(outputCapture, outPath);
+    const beforeStage = verifyAtomicOutput(outputCapture.snapshot);
+    if (beforeStage.status !== 'match') throwAtomicOutputFailure(beforeStage, outPath);
+    ({ candidatePath, identity: candidateIdentity } = stageRenderedHtml(
+      outputCapture.commitPath,
+      html,
+      outputCapture.mode,
+    ));
+
+    // The renderer may spend substantial time building HTML after loadDiagram
+    // establishes the guard. Re-run it after staging so a last-moment alias
+    // cannot redirect the commit onto an input file.
+    if (outputGuard) resolveOutputPath(outputGuard);
+    const candidateCapture = captureRegularFileBinding(candidatePath, {
+      subject: 'candidate',
+      expectedSha256: createHash('sha256').update(html).digest('hex'),
+      expectedBytes: Buffer.byteLength(html),
+      expectedIdentity: candidateIdentity,
+      ...(outputCapture.mode === null ? {} : { expectedMode: outputCapture.mode }),
+    });
+    if (candidateCapture.status !== 'captured') throwAtomicOutputFailure(candidateCapture, outPath);
+    candidateBinding = candidateCapture.binding;
+    const beforeCommit = verifyAtomicOutput(outputCapture.snapshot);
+    if (beforeCommit.status !== 'match') throwAtomicOutputFailure(beforeCommit, outPath);
+    const publication = publishRegularFileBinding(
+      candidateBinding,
+      candidatePath,
+      outputCapture.snapshot,
+      { subject: 'candidate' },
+    );
+    if (!['committed', 'committed-with-warning'].includes(publication.status)) {
+      throwAtomicOutputFailure(publication, outPath);
+    }
+    const releasedCandidate = releaseRegularFileBinding(candidateBinding);
+    candidateBinding = undefined;
+    if (releasedCandidate.status !== 'released') throwAtomicOutputFailure(releasedCandidate, outPath);
+    candidatePath = undefined;
+    candidateIdentity = undefined;
+  } catch (error) {
+    throwOutputError(error, outPath);
+  } finally {
+    outputPathGuards.delete(outPath);
+    if (candidateBinding) releaseRegularFileBinding(candidateBinding);
+    if (candidatePath && candidateIdentity) {
+      const cleanup = removeOwnedRegularFile(candidatePath, candidateIdentity);
+      if (!['removed', 'absent', 'preserved'].includes(cleanup.status)) {
+        throwAtomicOutputFailure(cleanup, outPath);
+      }
+    }
+  }
+  console.log(outPath);
+}
+
+const SEMANTIC_COLLECTIONS = {
+  architecture: 'components',
+  workflow: 'nodes',
+  sequence: 'participants',
+  dataflow: 'nodes',
+  lifecycle: 'states',
+};
+
+const RELATIONSHIP_COLLECTIONS = {
+  architecture: 'connections',
+  workflow: 'edges',
+  sequence: 'messages',
+  dataflow: 'flows',
+  lifecycle: 'transitions',
+};
+
+// Relationship IDs are optional for backwards compatibility, but once an
+// author supplies one it becomes the durable identity used by viewer links.
+// Keep uniqueness enforcement in the shared zero-install path so every typed
+// renderer fails the same way even when development dependencies are absent.
+export function validateRelationshipIds(diagramType, diagram) {
+  const collection = RELATIONSHIP_COLLECTIONS[diagramType];
+  const relationships = collection && Array.isArray(diagram[collection]) ? diagram[collection] : [];
+  const seen = new Set();
+  const problems = [];
+
+  relationships.forEach((relationship, index) => {
+    if (relationship.id === undefined || relationship.id === null || relationship.id === '') return;
+    if (seen.has(relationship.id)) {
+      problems.push(`/${collection}/${index}/id duplicates relationship id ${JSON.stringify(relationship.id)}`);
+    }
+    seen.add(relationship.id);
+  });
+
+  if (problems.length) {
+    throwDiagnosticProblems('Relationship identity validation failed', problems, {
+      code: 'relationship/duplicate-id',
+      subject: { diagramType, collection },
+    });
+  }
+}
+
+// Share relationship-ID semantic checks between the loader
+// and workflow compiler without performing filesystem operations (see #429).
+export function validateCrossCollectionContracts(diagramType, diagram) {
+  validateRelationshipIds(diagramType, diagram);
+}
+
+// Accessible name for the generated diagram SVG.
+export function svgRootAttrs(meta, explicitQualityProfile) {
+  const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';
+  const preset = ` data-preset="${esc(meta.visual_preset || 'classic')}"`;
+  const engineeringProfile = meta.engineering_profile
+    ? ` data-engineering-profile="${esc(meta.engineering_profile)}"`
+    : '';
+  const requestedProfile = explicitQualityProfile || process.env.ARCHIFY_QUALITY_PROFILE || meta.quality_profile;
+  const qualityProfile = requestedProfile === 'showcase' ? 'showcase' : 'standard';
+  const advisory = requestedProfile ? '' : ' data-quality-gates="advisory"';
+  return `role="img" lang="${esc(resolveLocale(meta.locale))}" aria-labelledby="archify-diagram-title archify-diagram-description"${animation}${preset}${engineeringProfile} data-quality-profile="${esc(qualityProfile)}"${advisory}`;
+}
+
+// Keep the accessible name inside the SVG so it survives standalone SVG
+// export and embedding. The fixed IDs are deterministic because an Archify
+// artifact intentionally contains one primary diagram SVG.
+export function svgAccessibleText(meta, kind) {
+  const description = meta.subtitle || translateMessage(meta.locale, `diagram.description.${kind}`);
+  return `        <title id="archify-diagram-title">${esc(meta.title)}</title>\n        <desc id="archify-diagram-description">${esc(description)}</desc>`;
+}
+
+export function animateAttr(meta, kind, step) {
+  if (meta.animation !== 'trace') return '';
+  // Ambient trace must finish inside the fixed six-second WebM capture. The
+  // cap affects visual delay only; authored order and semantic identity stay
+  // untouched in the JSON, DOM, and relationship contracts.
+  const safeStep = Number.isFinite(step) && step >= 0 ? Math.min(12, Math.floor(step)) : 0;
+  return ` data-animate="${kind}" style="--step:${safeStep}"`;
+}
+
+// Stable semantic hooks for the standalone HTML explorer. IDs already pass
+// the schema's conservative identifier pattern; escape again at the markup
+// boundary so these helpers remain safe if that contract expands later.
+export function focusNodeAttrs(id, label, metadata = {}, locale) {
+  const optional = [
+    ['data-node-kind', metadata.kind],
+    ['data-node-sublabel', metadata.sublabel],
+    ['data-node-tag', metadata.tag],
+    ['data-node-context', metadata.context],
+    ['data-node-brand', metadata.brand],
+    ['data-node-brand-id', metadata.brandId],
+    ['data-node-brand-status', metadata.brandStatus],
+    ['data-node-brand-source', metadata.brandSource],
+  ].filter(([, value]) => value !== undefined && value !== null && String(value).trim() !== '')
+    .map(([name, value]) => ` ${name}="${esc(String(value))}"`)
+    .join('');
+  const detail = [metadata.sublabel, metadata.context, metadata.brand]
+    .filter((value) => value !== undefined && value !== null && String(value).trim() !== '')
+    .join(', ');
+  const aria = detail
+    ? translateMessage(locale, 'node.focus.detail', { label, detail })
+    : translateMessage(locale, 'node.focus', { label });
+  return `id="node-${esc(id)}" data-node-id="${esc(id)}" data-node-label="${esc(label)}" tabindex="0" role="button" aria-label="${esc(aria)}" aria-pressed="false"${optional}`;
+}
+
+// Native SVG titles preserve a compact details-on-demand fallback when the
+// canonical SVG is embedded inline outside the full Archify viewer.
+export function focusNodeTitle(label, metadata = {}) {
+  const parts = [label, metadata.sublabel, metadata.context, metadata.tag, metadata.brand]
+    .filter((value) => value !== undefined && value !== null && String(value).trim() !== '');
+  return `<title>${esc(parts.join(' · '))}</title>`;
+}
+
+export function focusEdgeAttrs(from, to, label, key, id) {
+  const named = label ? ` data-edge-label="${esc(label)}"` : '';
+  const keyed = key !== undefined && key !== null ? ` data-edge-key="${esc(String(key))}"` : '';
+  const identified = id !== undefined && id !== null && String(id).trim() !== ''
+    ? ` data-edge-id="${esc(String(id))}"`
+    : '';
+  return `data-edge-from="${esc(from)}" data-edge-to="${esc(to)}"${named}${keyed}${identified}`;
+}

package/skills/archify/renderers/shared/desktop-readability.mjs

@@ -0,0 +1,132 @@
+export const DESKTOP_READABILITY_VIEWPORT = Object.freeze({ width: 1440, height: 900 });
+export const DESKTOP_READER_MIN_WIDTH = 960;
+export const DESKTOP_READER_HORIZONTAL_CHROME = 30;
+export const DESKTOP_READER_DIAGRAM_WIDTH = DESKTOP_READER_MIN_WIDTH - DESKTOP_READER_HORIZONTAL_CHROME;
+export const MIN_PROJECTED_NODE_TEXT_PX = 6;
+export const DECLARED_WIDE_READER_CONTRACT = 'declared-wide-v1';
+export const DECLARED_WIDE_READER_RATIO = 1.55;
+export const DECLARED_WIDE_READER_MAX_WIDTH = 1920;
+export const DECLARED_WIDE_REFERENCE_BODY_HORIZONTAL_PX = 64;
+export const DECLARED_WIDE_REFERENCE_DIAGRAM_HORIZONTAL_PX = 30;
+
+export function projectedNodeTextPx(sourceFontPx, viewBoxWidth, diagramWidth = DESKTOP_READER_DIAGRAM_WIDTH) {
+  if (![sourceFontPx, viewBoxWidth, diagramWidth].every(Number.isFinite) || viewBoxWidth <= 0 || diagramWidth <= 0) {
+    return Number.NaN;
+  }
+  return sourceFontPx * Math.min(1, diagramWidth / viewBoxWidth);
+}
+
+export function minimumReadableSourceTextPx(
+  viewBoxWidth,
+  diagramWidth = DESKTOP_READER_DIAGRAM_WIDTH,
+  minimumProjectedPx = MIN_PROJECTED_NODE_TEXT_PX,
+) {
+  if (![viewBoxWidth, diagramWidth, minimumProjectedPx].every(Number.isFinite)
+    || viewBoxWidth <= 0
+    || diagramWidth <= 0
+    || minimumProjectedPx <= 0) {
+    return Number.NaN;
+  }
+  return minimumProjectedPx / Math.min(1, diagramWidth / viewBoxWidth);
+}
+
+// This is deliberately separate from the legacy 930px projection. Architecture
+// boundary convergence depends on that legacy default, while only a recognized
+// v2 wide Reader may use this declared-width proof.
+export function declaredWideReadabilityBudget({
+  viewBoxWidth,
+  viewBoxHeight,
+  minimumSourceTextPx,
+  requestedMinimumTextPx,
+  viewportWidth = DESKTOP_READABILITY_VIEWPORT.width,
+  bodyHorizontalPx = DECLARED_WIDE_REFERENCE_BODY_HORIZONTAL_PX,
+  diagramHorizontalPx = DECLARED_WIDE_REFERENCE_DIAGRAM_HORIZONTAL_PX,
+  minimumReaderWidth = DESKTOP_READER_MIN_WIDTH,
+  maximumReaderWidth = DECLARED_WIDE_READER_MAX_WIDTH,
+} = {}) {
+  const values = [
+    viewBoxWidth, viewBoxHeight, minimumSourceTextPx, requestedMinimumTextPx,
+    viewportWidth, bodyHorizontalPx, diagramHorizontalPx, minimumReaderWidth, maximumReaderWidth,
+  ];
+  if (!values.every(Number.isFinite) || viewBoxWidth <= 0 || viewBoxHeight <= 0
+    || minimumSourceTextPx <= 0 || requestedMinimumTextPx <= 0 || viewportWidth <= 0
+    || bodyHorizontalPx < 0 || diagramHorizontalPx < 0 || minimumReaderWidth <= 0
+    || maximumReaderWidth < minimumReaderWidth || viewBoxWidth / viewBoxHeight < DECLARED_WIDE_READER_RATIO) {
+    return null;
+  }
+  const requestedTargetPx = Math.max(MIN_PROJECTED_NODE_TEXT_PX, requestedMinimumTextPx);
+  const requestedScale = Math.min(1, requestedTargetPx / minimumSourceTextPx);
+  const desiredReaderWidth = Math.max(minimumReaderWidth, viewBoxWidth * requestedScale + diagramHorizontalPx);
+  const viewportCap = Math.max(0, viewportWidth - bodyHorizontalPx);
+  const cap = Math.min(maximumReaderWidth, viewportCap);
+  const actualReaderWidth = Math.min(desiredReaderWidth, cap);
+  const guaranteedSvgWidth = Math.max(0, actualReaderWidth - diagramHorizontalPx);
+  const projectedMinimumTextPx = projectedNodeTextPx(minimumSourceTextPx, viewBoxWidth, guaranteedSvgWidth);
+  const limit = actualReaderWidth < desiredReaderWidth
+    ? (viewportCap <= maximumReaderWidth ? 'viewport-cap' : 'reader-cap')
+    : 'source-size';
+  return {
+    requestedTargetPx,
+    requestedScale,
+    desiredReaderWidth,
+    viewportCap,
+    maximumReaderWidth,
+    actualReaderWidth,
+    guaranteedSvgWidth,
+    projectedMinimumTextPx,
+    hardFloorPx: MIN_PROJECTED_NODE_TEXT_PX,
+    hardFloorMet: projectedMinimumTextPx >= MIN_PROJECTED_NODE_TEXT_PX,
+    requestedTargetMet: projectedMinimumTextPx >= requestedMinimumTextPx,
+    limit,
+  };
+}
+
+// Vertical chrome that always stacks with the SVG at the 1440x900 desktop
+// viewport, measured from the delivered Viewer with the shortest one-line
+// header and no cards: body padding 12, header 39, diagram padding/border 75.
+// Cards are excluded so the prediction stays a lower bound.
+export const DESKTOP_FIXED_VERTICAL_CHROME_PX = Object.freeze({ body: 12, header: 39, diagram: 75 });
+
+// A canvas the Reader can neither narrow (viewBox ratio below the wide
+// threshold) nor scroll readably (no intrinsic-height fit) renders at the full
+// reader width, so its page height is a function of the viewBox alone. Returns
+// null when the Reader has a way to fit the page; otherwise the certain
+// overflow at 1440x900 before any cards are counted.
+export function predictedFixedWidthOverflow({
+  viewBoxWidth,
+  viewBoxHeight,
+  readerFit,
+  diagramType,
+  viewport = DESKTOP_READABILITY_VIEWPORT,
+  bodyHorizontalPx = DECLARED_WIDE_REFERENCE_BODY_HORIZONTAL_PX,
+  diagramHorizontalPx = DECLARED_WIDE_REFERENCE_DIAGRAM_HORIZONTAL_PX,
+  chrome = DESKTOP_FIXED_VERTICAL_CHROME_PX,
+} = {}) {
+  if (![viewBoxWidth, viewBoxHeight].every(Number.isFinite) || viewBoxWidth <= 0 || viewBoxHeight <= 0) return null;
+  const ratio = viewBoxWidth / viewBoxHeight;
+  if (readerFit === 'intrinsic-height'
+      || (readerFit === 'authored-height' && diagramType === 'architecture')
+      || ratio >= DECLARED_WIDE_READER_RATIO) return null;
+  const svgWidthPx = viewport.width - bodyHorizontalPx - diagramHorizontalPx;
+  const svgHeightPx = Math.round(svgWidthPx * viewBoxHeight / viewBoxWidth);
+  const fixedChromePx = chrome.body + chrome.header + chrome.diagram;
+  const pageHeightPx = svgHeightPx + fixedChromePx;
+  if (pageHeightPx <= viewport.height) return null;
+  return {
+    viewportWidth: viewport.width,
+    viewportHeight: viewport.height,
+    ratio: Math.round(ratio * 100) / 100,
+    wideRatio: DECLARED_WIDE_READER_RATIO,
+    svgWidthPx,
+    svgHeightPx,
+    fixedChromePx,
+    pageHeightPx,
+    overflowPx: pageHeightPx - viewport.height,
+  };
+}
+
+export function describeFixedWidthOverflow(issue) {
+  const maximumViewBoxHeight = Math.floor(issue.viewBoxWidth / issue.wideRatio);
+  const wideViewBoxWidth = Math.ceil(issue.viewBoxHeight * issue.wideRatio);
+  return `Preserve every node, relationship, and label. This ${issue.viewBoxWidth}x${issue.viewBoxHeight} canvas (ratio ${issue.ratio}) declares no intrinsic-height fit and is below the ${issue.wideRatio} wide ratio, so the desktop Reader can neither narrow it nor accept vertical scroll: it renders ${issue.svgHeightPx}px tall at the full ${issue.svgWidthPx}px width and the page reaches ${issue.pageHeightPx}px before cards against ${issue.viewportHeight}px, a certain visual-check failure. Either compact vertical spacing so meta.viewBox height is at most ${maximumViewBoxHeight} at this width, or spread content sideways so the width is at least ${wideViewBoxWidth} at this height; for architecture, omitting meta.viewBox lets the renderer size the canvas and declare the fit.`;
+}