dsh-knowhub 0.9.0 → 0.10.0

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

@@ -0,0 +1,328 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_LOCALE = 'en';
+
+const ESCAPE_MAP = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+export function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (character) => ESCAPE_MAP[character]);
+}
+
+// Bundled catalogs are package data, not renderer code. locales/manifest.json
+// enrolls the catalogs meta.locale selects automatically; only listed files
+// are read, relative to this installed package and never from the working
+// directory, home, environment, or network. Adding a language changes data
+// only. en.json defines the canonical keys and the final fallback.
+const LOCALES_DIR = new URL('../../locales/', import.meta.url);
+// Mirrors common.schema.json#/$defs/locale.
+const LOCALE_TAG = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+const CATALOG_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/;
+
+function readLocaleData(file) {
+  try {
+    return JSON.parse(fs.readFileSync(fileURLToPath(new URL(file, LOCALES_DIR)), 'utf8'));
+  } catch (error) {
+    throw new Error(`Archify locale data ${JSON.stringify(file)} could not be loaded: ${error.message}`);
+  }
+}
+
+function loadManifest() {
+  const catalogs = readLocaleData('manifest.json')?.catalogs;
+  if (!Array.isArray(catalogs)) throw new Error('Archify locale manifest must list catalogs');
+  const byKey = new Map();
+  for (const entry of catalogs) {
+    const { locale, file } = entry || {};
+    if (typeof locale !== 'string' || locale.length > 35 || !LOCALE_TAG.test(locale)) {
+      throw new Error(`Archify locale manifest has an invalid locale tag ${JSON.stringify(locale)}`);
+    }
+    if (typeof file !== 'string' || !CATALOG_FILE.test(file)) {
+      throw new Error(`Archify locale manifest has an invalid catalog file for ${locale}`);
+    }
+    // Tags match case-insensitively, so two entries differing only in case
+    // would make selection ambiguous.
+    const key = locale.toLowerCase();
+    if (byKey.has(key)) throw new Error(`Archify locale manifest lists ${locale} more than once`);
+    byKey.set(key, { locale, file });
+  }
+  if (byKey.get(DEFAULT_LOCALE)?.locale !== DEFAULT_LOCALE) {
+    throw new Error(`Archify locale manifest must enroll the ${DEFAULT_LOCALE} source catalog`);
+  }
+  return byKey;
+}
+
+const MANIFEST = loadManifest();
+
+export const SUPPORTED_LOCALES = Object.freeze([...MANIFEST.values()].map(({ locale }) => locale));
+
+const EN = Object.freeze(readLocaleData(MANIFEST.get(DEFAULT_LOCALE).file));
+for (const [key, message] of Object.entries(EN)) {
+  if (typeof message !== 'string' || message.length === 0) {
+    throw new Error(`Archify source message ${JSON.stringify(key)} must be a non-empty string`);
+  }
+}
+
+const CANONICAL_KEYS = Object.keys(EN);
+const PLACEHOLDER_PATTERN = /\{([a-zA-Z0-9_]+)\}/g;
+
+function extractPlaceholders(message) {
+  return new Set([...String(message).matchAll(PLACEHOLDER_PATTERN)].map((match) => match[1]));
+}
+
+const CANONICAL_PLACEHOLDERS = Object.fromEntries(
+  CANONICAL_KEYS.map((key) => [key, extractPlaceholders(EN[key])]),
+);
+
+function placeholdersMatch(expected, actual) {
+  if (expected.size !== actual.size) return false;
+  for (const token of expected) if (!actual.has(token)) return false;
+  return true;
+}
+
+// Splits translation data into the entries that can replace a canonical
+// message and the ones that cannot. Rejected entries never replace a valid
+// lower-priority message.
+function classifyTranslations(translations) {
+  const supplied = Object.keys(translations || {});
+  const usable = new Map();
+  const unknownKeys = [];
+  const placeholderMismatches = [];
+  for (const key of supplied) {
+    if (!Object.hasOwn(CANONICAL_PLACEHOLDERS, key)) {
+      unknownKeys.push(key);
+      continue;
+    }
+    const value = translations[key];
+    const expected = [...CANONICAL_PLACEHOLDERS[key]].sort();
+    if (typeof value !== 'string' || value.length === 0) {
+      placeholderMismatches.push({ key, expected, actual: null });
+      continue;
+    }
+    const actual = extractPlaceholders(value);
+    if (placeholdersMatch(CANONICAL_PLACEHOLDERS[key], actual)) {
+      usable.set(key, value);
+    } else {
+      placeholderMismatches.push({ key, expected, actual: [...actual].sort() });
+    }
+  }
+  return { supplied, usable, unknownKeys, placeholderMismatches };
+}
+
+// Validates caller-supplied translation data against the canonical (English)
+// message-key set. Pure and side-effect free; coverage here describes only the
+// supplied data. resolveCatalog() reports the final resolved coverage.
+export function validateTranslations(translations = {}) {
+  const { usable, unknownKeys, placeholderMismatches } = classifyTranslations(translations);
+  return {
+    totalKeys: CANONICAL_KEYS.length,
+    coveredKeys: usable.size,
+    coverage: CANONICAL_KEYS.length ? usable.size / CANONICAL_KEYS.length : 1,
+    missingKeys: CANONICAL_KEYS.filter((key) => !Object.hasOwn(translations || {}, key)),
+    unknownKeys,
+    placeholderMismatches,
+  };
+}
+
+export function bundledLocaleFor(locale) {
+  if (typeof locale !== 'string') return null;
+  return MANIFEST.get(locale.toLowerCase())?.locale || null;
+}
+
+function isEnglishTag(locale) {
+  const key = locale.toLowerCase();
+  return key === DEFAULT_LOCALE || key.startsWith(`${DEFAULT_LOCALE}-`);
+}
+
+// Bundled catalogs load on first use and stay immutable; a diagram's
+// overrides are layered onto a copy.
+const BUNDLED_CATALOGS = new Map([[DEFAULT_LOCALE, { usable: new Map(Object.entries(EN)), messages: EN }]]);
+
+function bundledCatalog(locale) {
+  if (!BUNDLED_CATALOGS.has(locale)) {
+    const { usable } = classifyTranslations(readLocaleData(MANIFEST.get(locale.toLowerCase()).file));
+    const messages = Object.freeze(Object.fromEntries(
+      CANONICAL_KEYS.map((key) => [key, usable.get(key) ?? EN[key]]),
+    ));
+    BUNDLED_CATALOGS.set(locale, { usable, messages });
+  }
+  return BUNDLED_CATALOGS.get(locale);
+}
+
+// Resolves each canonical message as: valid meta.translations value →
+// selected bundled-catalog value → English source. Pure; returns the resolved
+// catalog with a report that separates rejected overrides from real English
+// fallback gaps. Omitted or empty translations mean no override. A tag with
+// neither a bundled catalog nor a usable override falls back to English UI
+// and language metadata.
+export function resolveCatalog(locale, translations = undefined) {
+  const override = classifyTranslations(translations);
+  const bundledLocale = bundledLocaleFor(locale);
+  const fallback = Boolean(locale) && !bundledLocale && override.usable.size === 0;
+  const resolvedLocale = !locale || fallback ? DEFAULT_LOCALE : bundledLocale || locale;
+  const bundled = bundledLocale ? bundledCatalog(bundledLocale) : null;
+  const english = isEnglishTag(resolvedLocale);
+  const messages = {};
+  const fallbackKeys = [];
+  for (const key of CANONICAL_KEYS) {
+    if (override.usable.has(key)) {
+      messages[key] = override.usable.get(key);
+    } else if (bundled?.usable.has(key)) {
+      messages[key] = bundled.usable.get(key);
+    } else {
+      messages[key] = EN[key];
+      if (!english) fallbackKeys.push(key);
+    }
+  }
+  const translatedKeys = english ? CANONICAL_KEYS.length : CANONICAL_KEYS.length - fallbackKeys.length;
+  return {
+    messages: Object.freeze(messages),
+    report: {
+      locale: locale || null,
+      resolvedLocale,
+      bundledLocale,
+      fallback,
+      totalKeys: CANONICAL_KEYS.length,
+      translatedKeys,
+      coverage: CANONICAL_KEYS.length ? translatedKeys / CANONICAL_KEYS.length : 1,
+      fallbackKeys,
+      override: {
+        suppliedKeys: override.supplied.length,
+        appliedKeys: override.usable.size,
+        unknownKeys: override.unknownKeys,
+        placeholderMismatches: override.placeholderMismatches,
+      },
+    },
+  };
+}
+
+// Per-document catalogs installed by registerLocale(). Tags are
+// case-insensitive, so the key is lowercased: renderers may pass the authored
+// meta.locale (zh-cn) or its resolved tag (zh-CN) and reach the same document
+// catalog. They never mutate a bundled catalog.
+const DOCUMENT_CATALOGS = new Map();
+
+function documentKey(locale) {
+  return typeof locale === 'string' ? locale.toLowerCase() : locale;
+}
+
+function catalogFor(locale) {
+  const key = documentKey(locale);
+  if (DOCUMENT_CATALOGS.has(key)) return DOCUMENT_CATALOGS.get(key);
+  const bundledLocale = bundledLocaleFor(locale);
+  return bundledLocale ? { locale: bundledLocale, messages: bundledCatalog(bundledLocale).messages } : null;
+}
+
+// Installs the resolved catalog for one authored locale and returns its
+// report. Re-registering the same tag replaces the previous document's
+// overrides; a fallback clears them.
+export function registerLocale(locale, translations = undefined) {
+  const { messages, report } = resolveCatalog(locale, translations);
+  if (report.fallback || !locale) {
+    DOCUMENT_CATALOGS.delete(documentKey(locale));
+  } else {
+    DOCUMENT_CATALOGS.set(documentKey(locale), { locale: report.resolvedLocale, messages });
+  }
+  return report;
+}
+
+// Agent-facing warnings for one document's meta.locale/meta.translations.
+// Pure, so the renderer and the CLI receipts (validate/deliver/finalize)
+// report the same diagnostics from the same input.
+export function localeDiagnostics(diagramType, meta) {
+  const locale = meta?.locale;
+  if (!locale) return [];
+  const report = resolveCatalog(locale, meta.translations).report;
+  const diagnostics = [];
+  const { unknownKeys, placeholderMismatches, appliedKeys } = report.override;
+  const rejected = unknownKeys.length + placeholderMismatches.length;
+  if (rejected) {
+    const kept = report.bundledLocale ? `bundled ${report.bundledLocale} message` : 'English message';
+    diagnostics.push({
+      code: 'i18n/invalid-translation',
+      severity: 'warning',
+      message: `meta.translations for locale ${JSON.stringify(locale)} has ${rejected} unusable ${rejected === 1 ? 'entry' : 'entries'} (${unknownKeys.length} unknown, ${placeholderMismatches.length} placeholder mismatch); each keeps its ${kept}.`,
+      subject: { diagramType, path: '/meta/translations' },
+      evidence: {
+        locale,
+        unknownKeys: unknownKeys.slice(0, 10),
+        unknownKeysTotal: unknownKeys.length,
+        placeholderMismatches: placeholderMismatches.slice(0, 10),
+        placeholderMismatchesTotal: placeholderMismatches.length,
+      },
+      supportedFixes: ['Remove each unknown key or rename it to a canonical message key.', 'Use exactly the {placeholders} of the English source string for each mismatched key.'],
+    });
+  }
+  if (report.fallback) {
+    diagnostics.push({
+      code: 'i18n/locale-fallback',
+      severity: 'warning',
+      message: `meta.locale ${JSON.stringify(locale)} has no bundled catalog and no usable meta.translations; the Viewer chrome and <html lang> fall back to English.`,
+      subject: { diagramType, path: '/meta/locale' },
+      evidence: { locale, bundledLocales: SUPPORTED_LOCALES },
+      supportedFixes: ['Supply meta.translations for this locale.', `Use a bundled locale: ${SUPPORTED_LOCALES.join(', ')}.`],
+    });
+  } else if (report.fallbackKeys.length) {
+    const source = [
+      report.bundledLocale && `the bundled ${report.bundledLocale} catalog`,
+      appliedKeys && `${appliedKeys} meta.translations ${appliedKeys === 1 ? 'entry' : 'entries'}`,
+    ].filter(Boolean).join(' and ');
+    const missingKeys = report.fallbackKeys.slice(0, 10);
+    diagnostics.push({
+      code: 'i18n/translation-coverage',
+      severity: 'warning',
+      message: `meta.locale ${JSON.stringify(locale)} resolves ${report.translatedKeys}/${report.totalKeys} renderer-owned messages (${Math.floor(report.coverage * 100)}%) from ${source}; ${report.fallbackKeys.length} fall back to English.`,
+      subject: { diagramType, path: '/meta/translations' },
+      evidence: {
+        locale,
+        resolvedLocale: report.resolvedLocale,
+        bundledLocale: report.bundledLocale,
+        translatedKeys: report.translatedKeys,
+        totalKeys: report.totalKeys,
+        appliedOverrideKeys: appliedKeys,
+        missingKeys,
+        missingKeysTotal: report.fallbackKeys.length,
+        // English source for the listed gaps, so a caller can translate
+        // exactly those keys without re-reading the whole catalog.
+        englishSource: Object.fromEntries(missingKeys.map((key) => [key, EN[key]])),
+      },
+      supportedFixes: ['Add each missing key to meta.translations, translating its English source string and keeping its {placeholders}.'],
+    });
+  }
+  return diagnostics;
+}
+
+export function resolveLocale(locale) {
+  return catalogFor(locale)?.locale || DEFAULT_LOCALE;
+}
+
+export function formatMessage(template, values = {}) {
+  return String(template).replace(/\{([a-zA-Z0-9_]+)\}/g, (match, key) => (
+    Object.hasOwn(values, key) ? String(values[key]) : match
+  ));
+}
+
+export function translateMessage(locale, key, values = {}) {
+  const catalog = catalogFor(locale)?.messages || EN;
+  if (!Object.hasOwn(catalog, key)) {
+    throw new Error(`Missing Archify i18n message ${JSON.stringify(key)} for ${resolveLocale(locale)}`);
+  }
+  return formatMessage(catalog[key], values);
+}
+
+export function translateCount(locale, key, count, values = {}) {
+  const suffix = count === 1 ? 'one' : 'other';
+  return translateMessage(locale, `${key}.${suffix}`, { ...values, count });
+}
+
+export function viewerCatalog(locale) {
+  const messages = catalogFor(locale)?.messages || EN;
+  return Object.fromEntries(Object.entries(messages).filter(([key]) => key.startsWith('viewer.')));
+}
+
+export function localizeTemplate(template, locale) {
+  return template.replace(/\{\{i18n:([a-zA-Z0-9_.-]+)\}\}/g, (_match, key) => escapeHtml(translateMessage(locale, key)));
+}
+
+export function catalogKeys() {
+  return [...CANONICAL_KEYS];
+}

package/skills/archify/renderers/shared/layout-report.mjs

@@ -0,0 +1,57 @@
+/** Serialize computed layout for dry-run / inspect (#9). */
+
+export function componentBox(c) {
+  return {
+    id: c.id,
+    type: c.type,
+    label: c.label,
+    x: Math.round(c.x),
+    y: Math.round(c.y),
+    width: c.width,
+    height: c.height,
+    ...(Number.isInteger(c.row) ? { row: c.row } : {}),
+    ...(Number.isInteger(c.col) ? { col: c.col } : {}),
+    ...(Array.isArray(c.pos) ? { pos: c.pos.map(Math.round) } : {}),
+  };
+}
+
+export function entityBox(e) {
+  return {
+    id: e.id,
+    label: e.label,
+    x: Math.round(e.x),
+    y: Math.round(e.y),
+    width: e.width,
+    height: e.height,
+    attributes: (Array.isArray(e.attributes) ? e.attributes : []).map((attribute) => attribute.name),
+    ...(Number.isInteger(e.row) ? { row: e.row } : {}),
+    ...(Number.isInteger(e.col) ? { col: e.col } : {}),
+    ...(Array.isArray(e.pos) ? { pos: e.pos.map(Math.round) } : {}),
+  };
+}
+
+export function boundaryBox(b) {
+  return {
+    kind: b.kind,
+    label: b.label,
+    x: Math.round(b.x),
+    y: Math.round(b.y),
+    width: Math.round(b.width),
+    height: Math.round(b.height),
+    wraps: b.wraps,
+  };
+}
+
+export function connectionPath(conn, routed, labelAt) {
+  return {
+    from: conn.from,
+    to: conn.to,
+    label: conn.label ?? null,
+    variant: conn.variant ?? 'default',
+    route: conn.route ?? 'auto',
+    // These points are repair inputs: rounding a fractional port makes a
+    // reused waypoint diagonal relative to the actual endpoint.
+    points: routed.points.map(([x, y]) => [x, y]),
+    ...(labelAt ? { labelAt: labelAt.map(Math.round) } : {}),
+  };
+}

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

@@ -0,0 +1,227 @@
+import { throwDiagnosticError } from './diagnostics.mjs';
+import { rectsOverlap, segmentIntersectsRect } from './geometry.mjs';
+import { esc, textUnits } from './utils.mjs';
+import { translateMessage } from './i18n.mjs';
+
+const DEFAULT_FONT_SIZE = 8;
+const DEFAULT_ITEM_GAP = 22;
+const DEFAULT_LINE_GAP = 22;
+const DEFAULT_SWATCH_GAP = 8;
+const TEXT_ADVANCE_EM = 0.62;
+const INTERACTIVE_BADGE_ALLOWANCE = 21;
+
+export function relationshipLegendObstacles(relations, { pointsFor, labelRectFor } = {}) {
+  const obstacles = [];
+  for (const [index, relation] of (Array.isArray(relations) ? relations : []).entries()) {
+    const points = typeof pointsFor === 'function' ? pointsFor(relation, index) : [];
+    const finitePoints = (Array.isArray(points) ? points : []).filter((point) => (
+      Array.isArray(point) && point.length === 2 && point.every(Number.isFinite)
+    ));
+    for (let pointIndex = 0; pointIndex < finitePoints.length - 1; pointIndex += 1) {
+      obstacles.push({
+        kind: 'relationship-segment',
+        start: finitePoints[pointIndex],
+        end: finitePoints[pointIndex + 1],
+      });
+    }
+    const labelRect = typeof labelRectFor === 'function' ? labelRectFor(relation, index) : null;
+    if (labelRect && [labelRect.x, labelRect.y, labelRect.width, labelRect.height].every(Number.isFinite)) {
+      obstacles.push({ kind: 'relationship-label', ...labelRect });
+    }
+  }
+  return obstacles;
+}
+
+export function resolveLegend(config, catalog, presentKinds) {
+  const mode = config?.mode || 'auto';
+  if (mode === 'hidden') return [];
+  const present = presentKinds instanceof Set ? presentKinds : new Set(presentKinds || []);
+  const overrides = config?.entries || {};
+
+  return catalog.flatMap((catalogEntry) => {
+    const override = overrides[catalogEntry.kind] || {};
+    const selectedByMode = mode === 'all' || present.has(catalogEntry.kind);
+    const visible = override.visible === true || (selectedByMode && override.visible !== false);
+    if (!visible) return [];
+    return [{
+      ...catalogEntry,
+      label: override.label || catalogEntry.label,
+      present: present.has(catalogEntry.kind),
+      interactive: catalogEntry.interactive !== false && present.has(catalogEntry.kind),
+    }];
+  });
+}
+
+// Labels render slightly larger than the layout font size; measure the
+// rendered size so a long label cannot run into the next entry.
+function renderedLegendFontSize(fontSize) {
+  return fontSize < 8 ? fontSize + 0.5 : fontSize + 2;
+}
+
+function measuredEntryWidth(entry, fontSize, swatchGap) {
+  const swatchWidth = entry.swatchWidth ?? 14;
+  return Math.ceil(
+    swatchWidth
+    + swatchGap
+    + textUnits(entry.label) * renderedLegendFontSize(fontSize) * TEXT_ADVANCE_EM
+    + (entry.interactive ? INTERACTIVE_BADGE_ALLOWANCE : 0)
+    + (entry.trailingWidth ?? 0),
+  );
+}
+
+// One pure footprint calculation owns both auto-viewBox sizing and final SVG
+// placement. Callers must not maintain a second approximation of legend width
+// or row count; that would make generated geometry disagree with validation.
+export function legendFootprint(entries, {
+  width,
+  fontSize = DEFAULT_FONT_SIZE,
+  itemGap = DEFAULT_ITEM_GAP,
+  lineGap = DEFAULT_LINE_GAP,
+  swatchGap = DEFAULT_SWATCH_GAP,
+} = {}) {
+  if (!entries.length) {
+    return { measured: [], rows: [], rowCount: 0, minWidth: 0, extraHeight: 0 };
+  }
+  const measured = entries.map((entry) => ({
+    ...entry,
+    width: measuredEntryWidth(entry, fontSize, entry.swatchGap ?? swatchGap),
+  }));
+  const rows = [[]];
+  let cursor = 0;
+  for (const entry of measured) {
+    const row = rows.at(-1);
+    const required = (row.length ? itemGap : 0) + entry.width;
+    if (row.length && cursor + required > width) {
+      rows.push([entry]);
+      cursor = entry.width;
+    } else {
+      row.push(entry);
+      cursor += required;
+    }
+  }
+  return {
+    measured,
+    rows,
+    rowCount: rows.length,
+    minWidth: measured.reduce((width, entry) => Math.max(width, entry.width), 0),
+    extraHeight: (rows.length - 1) * lineGap,
+  };
+}
+
+export function measureLegend(entries, {
+  x,
+  baselineY,
+  width,
+  fontSize = DEFAULT_FONT_SIZE,
+  itemGap = DEFAULT_ITEM_GAP,
+  lineGap = DEFAULT_LINE_GAP,
+  swatchGap = DEFAULT_SWATCH_GAP,
+  minTitleY = 0,
+  obstacles = [],
+  unfit = 'error',
+  diagramType = 'diagram',
+} = {}) {
+  if (!entries.length) return { entries: [], rowCount: 0, titleY: null };
+  const footprint = legendFootprint(entries, { width, fontSize, itemGap, lineGap, swatchGap });
+  const tooWide = footprint.measured.find((entry) => entry.width > width);
+  if (tooWide) {
+    if (unfit === 'hide') return null;
+    const message = `[legend/label-too-wide] ${diagramType} legend label for "${tooWide.kind}" needs ${tooWide.width}px but only ${width}px is available.`;
+    throwDiagnosticError(message, [{
+      code: 'legend/label-too-wide',
+      severity: 'error',
+      message,
+      subject: { diagramType, path: `/meta/legend/entries/${tooWide.kind}/label` },
+      evidence: { kind: tooWide.kind, measuredWidthPx: tooWide.width, availableWidthPx: width },
+      supportedFixes: ['shorten the legend label or use a wider viewBox'],
+    }]);
+  }
+
+  const titleY = baselineY - footprint.extraHeight - 20;
+  const legendTopY = titleY - 10;
+  if (legendTopY < minTitleY) {
+    if (unfit === 'hide') return null;
+    const message = `[legend/vertical-overflow] ${diagramType} legend needs ${footprint.rowCount} rows, which would start at y=${legendTopY} above the available legend band at y=${minTitleY}.`;
+    throwDiagnosticError(message, [{
+      code: 'legend/vertical-overflow',
+      severity: 'error',
+      message,
+      subject: { diagramType, path: '/meta/legend' },
+      evidence: { rowCount: footprint.rowCount, requiredTopY: legendTopY, availableTopY: minTitleY },
+      supportedFixes: ['shorten legend labels, hide nonessential entries, or use a wider viewBox'],
+    }]);
+  }
+
+  const positioned = [];
+  footprint.rows.forEach((row, rowIndex) => {
+    let entryX = x;
+    const baseline = baselineY - (footprint.rowCount - rowIndex - 1) * lineGap;
+    for (const entry of row) {
+      positioned.push({ ...entry, x: entryX, baseline, row: rowIndex });
+      entryX += entry.width + itemGap;
+    }
+  });
+
+  const legendRects = [
+    { kind: 'title', x, y: legendTopY, width: 48, height: 14 },
+    ...positioned.map((entry) => ({
+      kind: entry.kind,
+      x: entry.x,
+      y: entry.baseline - 10,
+      width: entry.width,
+      height: 14,
+    })),
+  ];
+  const collision = legendRects.find((legendRect) => obstacles.some((obstacle) => (
+    Array.isArray(obstacle.start) && Array.isArray(obstacle.end)
+      ? segmentIntersectsRect({ start: obstacle.start, end: obstacle.end }, legendRect)
+      : rectsOverlap(obstacle, legendRect)
+  )));
+  if (collision) {
+    if (unfit === 'hide') return null;
+    const message = `[legend/content-overlap] ${diagramType} legend entry "${collision.kind}" overlaps authored relationship geometry.`;
+    throwDiagnosticError(message, [{
+      code: 'legend/content-overlap',
+      severity: 'error',
+      message,
+      subject: { diagramType, path: '/meta/legend' },
+      evidence: { legendKind: collision.kind, legendRect: collision },
+      supportedFixes: ['shorten or hide legend entries, use a wider viewBox, or move the authored relationship route/label out of the legend band'],
+    }]);
+  }
+
+  return {
+    entries: positioned,
+    rowCount: footprint.rowCount,
+    titleY,
+    fontSize,
+  };
+}
+
+// `labelClass`/`labelWeight` let a renderer state that its legend labels are
+// the same ink and weight as the value they describe; both default to the
+// shared presentation, so callers that pass nothing keep their exact bytes.
+export function renderLegend({ entries, layout, renderSwatch, locale, labelClass = 't-muted', labelWeight = 500 }) {
+  if (!entries.length) return '';
+  const measured = measureLegend(entries, layout);
+  if (!measured) return '';
+  const hasInteractiveEntries = measured.entries.some((entry) => entry.interactive);
+  const renderedFontSize = renderedLegendFontSize(measured.fontSize);
+  const rootAttributes = hasInteractiveEntries ? ' data-legend="" data-legend-bridge=""' : ' data-legend=""';
+  const parts = [
+    `        <g${rootAttributes}>`,
+    `          <text x="${layout.x}" y="${measured.titleY}" class="t-primary" font-size="12" font-weight="650">${esc(translateMessage(locale, 'legend.title'))}</text>`,
+  ];
+
+  for (const entry of measured.entries) {
+    const interactive = entry.interactive
+      ? ` data-legend-kind="${esc(entry.kind)}" data-legend-label="${esc(entry.label)}"`
+      : '';
+    parts.push(`          <g data-legend-semantic-kind="${esc(entry.kind)}"${interactive} data-legend-x="${entry.x}" data-legend-baseline="${entry.baseline}" data-legend-width="${entry.width}">`);
+    parts.push(`            ${renderSwatch(entry)}`);
+    parts.push(`            <text x="${entry.x + (entry.swatchWidth ?? 14) + (entry.swatchGap ?? DEFAULT_SWATCH_GAP)}" y="${entry.baseline}" class="${labelClass}" font-size="${renderedFontSize}" font-weight="${labelWeight}">${esc(entry.label)}</text>`);
+    parts.push('          </g>');
+  }
+  parts.push('        </g>');
+  return parts.join('\n');
+}

package/skills/archify/renderers/shared/node-card-style.mjs

@@ -0,0 +1,32 @@
+// Shared card styling for the architecture and workflow renderers. Every
+// preset gets the cleaner cards and label chips; blueprint keeps its drafting
+// dash patterns and square corners.
+const TONES = ['frontend', 'backend', 'database', 'cloud', 'security', 'messagebus', 'external'];
+
+export const NODE_CARD_ATTR = 'data-node-ui=""';
+
+export function nodeCardStyle() {
+  const all = 'svg[data-node-ui]';
+  const solid = `${all}:is([data-preset="classic"], [data-preset="signal-flow"], [data-preset="editorial"])`;
+  const blueprint = `${all}[data-preset="blueprint"]`;
+  const editorial = `${all}[data-preset="editorial"]`;
+  const dark = `:is([data-theme="dark"] ${all}, ${all}[data-theme="dark"])`;
+  const node = '[data-node-id] > rect:not(.c-mask)';
+  const frameLabel = '[data-graph-role="structural-frame-label-mask"]';
+  const edgeLabel = 'g[data-edge-from] > rect.c-mask';
+  return `        <style>
+          ${all} ${node} { stroke-width: 1.25px; }
+${TONES.map((tone) => `          ${dark} ${node}.c-${tone} { fill: color-mix(in srgb, var(--${tone}-stroke) 13%, var(--mask)); stroke: color-mix(in srgb, var(--${tone}-stroke) 72%, var(--mask)); }`).join('\n')}
+          ${solid} .c-region { fill: color-mix(in srgb, var(--cloud-stroke) 3%, transparent); stroke: color-mix(in srgb, var(--cloud-stroke) 42%, var(--lane-stroke)); stroke-dasharray: none; }
+          ${all} .c-security-group { stroke: color-mix(in srgb, var(--security-stroke) 58%, var(--lane-stroke)); }
+          ${solid} .c-security-group { stroke-dasharray: 4 3; }
+          ${solid} .c-lane { stroke: var(--lane-stroke); stroke-dasharray: none; }
+          ${all} ${frameLabel} { rx: 5px; fill: color-mix(in srgb, var(--cloud-stroke) 10%, var(--mask)); stroke: color-mix(in srgb, var(--cloud-stroke) 38%, var(--mask)); stroke-width: .8px; }
+          ${all} [data-composition-frame-kind="security-group"] > ${frameLabel} { fill: color-mix(in srgb, var(--security-stroke) 9%, var(--mask)); stroke: color-mix(in srgb, var(--security-stroke) 36%, var(--mask)); }
+          ${all} .phase-rule { opacity: .5; stroke-dasharray: none; }
+          ${all} .phase-chip { stroke: var(--lane-stroke); stroke-width: .75px; }
+          ${all} ${edgeLabel} { rx: 7px; stroke: var(--lane-stroke); stroke-width: .75px; }
+          ${blueprint} :is(${frameLabel}, ${edgeLabel}, .phase-chip) { rx: 2px; }
+          ${editorial} :is(${frameLabel}, ${edgeLabel}, .phase-chip) { rx: 3px; }
+        </style>`;
+}