@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/archify/renderers/shared/repository-evidence.mjs

@@ -0,0 +1,239 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { throwDiagnosticError } from './diagnostics.mjs';
+import { parseRepositoryRemote, redactRepositoryRemote, repositorySourceHref } from './repository-location.mjs';
+
+const FULL_SHA_RE = /^[a-f0-9]{40}$/i;
+const CONTROL_CHARACTER_RE = /[\u0000-\u001f\u007f]/;
+
+function evidenceFailure(code, message, { subject = {}, evidence = {}, supportedFixes = [] } = {}) {
+  throwDiagnosticError(message, [{
+    code,
+    severity: 'error',
+    message,
+    subject: { surface: 'repository-evidence', ...subject },
+    evidence,
+    supportedFixes,
+  }]);
+}
+
+function runGit(repoRoot, args) {
+  // 固定 SHA 的来源必须读取原始对象，不能使用本地 replacement refs 的替换内容。
+  const result = spawnSync('git', ['--no-replace-objects', '-C', repoRoot, ...args], {
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.error) evidenceFailure('repository-evidence/git-unavailable', `Could not run Git: ${result.error.message}`, {
+    evidence: { reason: result.error.message },
+    supportedFixes: ['install Git and ensure it is available on PATH'],
+  });
+  return result;
+}
+
+function gitValue(repoRoot, args, failure) {
+  const result = runGit(repoRoot, args);
+  if (result.status !== 0) evidenceFailure('repository-evidence/git-command', failure, {
+    evidence: { gitArgs: args, exitCode: result.status },
+    supportedFixes: ['use the intended local Git repository and verify its origin and revision'],
+  });
+  return result.stdout.trim();
+}
+
+function verifiedSourcePath(value, where) {
+  const sourcePath = String(value || '');
+  if (!sourcePath || sourcePath.startsWith('/') || sourcePath.includes('\\') || CONTROL_CHARACTER_RE.test(sourcePath)) {
+    evidenceFailure('repository-evidence/path-invalid', `${where} must be a repo-relative POSIX path.`, {
+      subject: { path: where },
+      evidence: { authoredPath: sourcePath },
+      supportedFixes: ['use a repository-relative path with forward slashes'],
+    });
+  }
+  const segments = sourcePath.split('/');
+  if (segments.some((segment) => !segment || segment === '.' || segment === '..') || segments[0] === '.git') {
+    evidenceFailure('repository-evidence/path-escape', `${where} must stay inside the repository and may not address .git.`, {
+      subject: { path: where },
+      evidence: { authoredPath: sourcePath },
+      supportedFixes: ['remove empty, dot, parent, or .git path segments'],
+    });
+  }
+  return segments.join('/');
+}
+
+function sourceLineCount(content) {
+  if (!content.length) return 0;
+  const lines = content.split(/\r\n|\n|\r/);
+  return lines.length - (/(?:\r\n|\n|\r)$/.test(content) ? 1 : 0);
+}
+
+export function hasRepositoryEvidence(diagramType, diagram) {
+  if (diagramType !== 'architecture') return false;
+  const components = Array.isArray(diagram?.components) ? diagram.components : [];
+  return Boolean(diagram?.meta?.repository) || components.some((component) => Array.isArray(component?.sources) && component.sources.length);
+}
+
+export function verifyRepositoryEvidence(diagramType, diagram, repoRootInput) {
+  if (!hasRepositoryEvidence(diagramType, diagram)) return null;
+  if (diagramType !== 'architecture') evidenceFailure('repository-evidence/type-unsupported', 'Repository evidence is currently supported for architecture diagrams only.', {
+    subject: { diagramType },
+    supportedFixes: ['use architecture mode or remove repository evidence'],
+  });
+
+  const repository = diagram.meta?.repository;
+  if (!repository) evidenceFailure('repository-evidence/repository-required', 'Repository evidence requires /meta/repository.', {
+    subject: { path: '/meta/repository' },
+    supportedFixes: ['add the pinned repository metadata or remove component sources'],
+  });
+  if (!FULL_SHA_RE.test(repository.revision || '')) {
+    evidenceFailure('repository-evidence/revision-invalid', '/meta/repository/revision must be a full 40-character commit SHA.', {
+      subject: { path: '/meta/repository/revision' },
+      evidence: { revision: repository.revision },
+      supportedFixes: ['pin one full 40-character commit SHA'],
+    });
+  }
+  const location = parseRepositoryRemote(repository.url, { authored: true });
+  if (!location) {
+    evidenceFailure('repository-evidence/url-invalid', '/meta/repository/url must be a credential-free HTTP(S) or Git SSH repository address without query, fragment, or dot segments.', {
+      subject: { path: '/meta/repository/url' },
+      supportedFixes: ['declare the matching repository address without credentials; use link_mode: local-only for internal repositories'],
+    });
+  }
+  const linkMode = repository.link_mode ?? 'web';
+  if (!['web', 'local-only'].includes(linkMode)) evidenceFailure('repository-evidence/link-mode-invalid', 'Repository link_mode must be web or local-only.');
+  if (repository.provider !== undefined && (!['github', 'gitee'].includes(repository.provider) || repository.provider !== location.provider)) {
+    evidenceFailure('repository-evidence/provider-invalid', 'Repository provider must match its supported public host (github.com or gitee.com).', {
+      subject: { path: '/meta/repository/provider' },
+      supportedFixes: ['use the matching provider or omit provider and select link_mode: local-only'],
+    });
+  }
+  if (linkMode === 'web' && (!location.provider || location.protocol !== 'https:' || location.endpoint !== 'standard' || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(location.path))) {
+    evidenceFailure('repository-evidence/links-unsupported', 'Web source links require a canonical GitHub or Gitee HTTPS owner/repository URL.', {
+      subject: { path: '/meta/repository/url' },
+      supportedFixes: ['use a canonical GitHub or Gitee URL, or select link_mode: local-only to retain local verification without web links'],
+    });
+  }
+  if (!repoRootInput) {
+    evidenceFailure('repository-evidence/root-required', 'This diagram declares source evidence. Pass --repo-root <repository> so Archify can verify it before rendering.', {
+      subject: { path: '/meta/repository' },
+      supportedFixes: ['pass --repo-root with the matching local Git checkout'],
+    });
+  }
+
+  const requestedRoot = path.resolve(repoRootInput);
+  let realRoot;
+  try {
+    realRoot = fs.realpathSync(requestedRoot);
+  } catch (error) {
+    evidenceFailure('repository-evidence/root-unreadable', `Could not resolve evidence repository root "${requestedRoot}": ${error.message}`, {
+      subject: { repoRoot: requestedRoot },
+      evidence: { reason: error.message },
+      supportedFixes: ['pass one readable local repository directory'],
+    });
+  }
+  const gitRoot = gitValue(realRoot, ['rev-parse', '--show-toplevel'], `Evidence root "${realRoot}" is not a Git repository.`);
+  if (fs.realpathSync(gitRoot) !== realRoot) {
+    evidenceFailure('repository-evidence/root-not-top-level', `Evidence root must be the Git top-level directory: ${gitRoot}`, {
+      subject: { repoRoot: realRoot },
+      evidence: { gitTopLevel: gitRoot },
+      supportedFixes: [`pass --repo-root ${gitRoot}`],
+    });
+  }
+  const origin = gitValue(realRoot, ['remote', 'get-url', 'origin'], 'Evidence repository must have an origin remote.');
+  if (parseRepositoryRemote(origin)?.identity !== location.identity) {
+    const safeOrigin = redactRepositoryRemote(origin);
+    evidenceFailure('repository-evidence/origin-mismatch', `Evidence repository origin ${JSON.stringify(safeOrigin)} does not match ${JSON.stringify(repository.url)}.`, {
+      subject: { repoRoot: realRoot },
+      evidence: { localOrigin: safeOrigin, authoredRepository: repository.url },
+      supportedFixes: ['use the matching local checkout or correct the authored repository URL'],
+    });
+  }
+
+  const revision = repository.revision.toLowerCase();
+  const commit = runGit(realRoot, ['cat-file', '-e', `${revision}^{commit}`]);
+  if (commit.status !== 0) {
+    evidenceFailure('repository-evidence/revision-unavailable', `Evidence revision ${revision} is not available in the local repository.`, {
+      subject: { repoRoot: realRoot },
+      evidence: { revision },
+      supportedFixes: ['fetch the pinned commit or pin an available full commit SHA'],
+    });
+  }
+
+  const nodes = Object.create(null);
+  let referenceCount = 0;
+  const components = Array.isArray(diagram.components) ? diagram.components : [];
+  for (const [componentIndex, component] of components.entries()) {
+    if (!Array.isArray(component.sources) || component.sources.length === 0) continue;
+    const verified = [];
+    for (const [sourceIndex, authored] of component.sources.entries()) {
+      const where = `/components/${componentIndex}/sources/${sourceIndex}/path`;
+      const source = {
+        path: verifiedSourcePath(authored.path, where),
+        ...(authored.line ? { line: authored.line } : {}),
+        ...(authored.end_line ? { endLine: authored.end_line } : {}),
+        ...(authored.label ? { label: authored.label } : {}),
+      };
+      if (source.endLine && !source.line) {
+        evidenceFailure('repository-evidence/line-required', `/components/${componentIndex}/sources/${sourceIndex}/end_line requires line.`, {
+          subject: { path: `/components/${componentIndex}/sources/${sourceIndex}/end_line`, componentId: component.id },
+          supportedFixes: ['add line or remove end_line'],
+        });
+      }
+      if (source.endLine && source.endLine < source.line) {
+        evidenceFailure('repository-evidence/line-range-invalid', `/components/${componentIndex}/sources/${sourceIndex}/end_line must be greater than or equal to line.`, {
+          subject: { path: `/components/${componentIndex}/sources/${sourceIndex}`, componentId: component.id },
+          evidence: { line: source.line, endLine: source.endLine },
+          supportedFixes: ['use an end_line greater than or equal to line'],
+        });
+      }
+      const object = `${revision}:${source.path}`;
+      const type = runGit(realRoot, ['cat-file', '-t', object]);
+      if (type.status !== 0 || type.stdout.trim() !== 'blob') {
+        evidenceFailure('repository-evidence/file-missing', `${where} does not identify a file at revision ${revision}.`, {
+          subject: { path: where, componentId: component.id },
+          evidence: { sourcePath: source.path, revision },
+          supportedFixes: ['use a file path that exists at the pinned revision'],
+        });
+      }
+      if (source.line) {
+        const content = runGit(realRoot, ['show', object]);
+        if (content.status !== 0) evidenceFailure('repository-evidence/file-unreadable', `${where} could not be read at revision ${revision}.`, {
+          subject: { path: where, componentId: component.id },
+          evidence: { sourcePath: source.path, revision },
+          supportedFixes: ['verify the pinned blob is readable in the local checkout'],
+        });
+        const lineCount = sourceLineCount(content.stdout);
+        const requestedLine = source.endLine || source.line;
+        if (requestedLine > lineCount) {
+          evidenceFailure('repository-evidence/line-out-of-range', `/components/${componentIndex}/sources/${sourceIndex} requests line ${requestedLine}, but ${source.path} has ${lineCount} lines at revision ${revision}.`, {
+            subject: { path: `/components/${componentIndex}/sources/${sourceIndex}`, componentId: component.id },
+            evidence: { sourcePath: source.path, requestedLine, lineCount, revision },
+            supportedFixes: ['use a line range that exists at the pinned revision'],
+          });
+        }
+      }
+      verified.push({ ...source, ...(linkMode === 'web' ? { href: repositorySourceHref(location.provider, location.url, revision, source) } : {}) });
+      referenceCount += 1;
+    }
+    nodes[component.id] = verified;
+  }
+  if (referenceCount === 0) {
+    evidenceFailure('repository-evidence/source-required', '/meta/repository requires at least one component source reference.', {
+      subject: { path: '/meta/repository' },
+      supportedFixes: ['add at least one verified component source or remove repository metadata'],
+    });
+  }
+
+  return {
+    schemaVersion: 1,
+    verified: true,
+    repository: {
+      url: location.url,
+      revision,
+      shortRevision: revision.slice(0, 7),
+      label: location.provider === 'github' ? location.path : location.url.replace(/^(?:https?:\/\/|ssh:\/\/git@|git@)/, ''),
+      ...(linkMode === 'web' ? { href: `${location.url}/tree/${revision}` } : { linkMode }),
+    },
+    referenceCount,
+    nodes,
+  };
+}

package/skills/archify/renderers/shared/repository-location.mjs

@@ -0,0 +1,58 @@
+// Repository identity and forge links are independent of local Git object checks.
+// This module never contacts a remote server or reads the user's SSH config.
+export function parseRepositoryRemote(value, { authored = false } = {}) {
+  if (typeof value !== 'string') return null;
+  const raw = authored ? value : value.trim();
+  if (!raw || /[\s\\\u0000-\u001f\u007f?#]/.test(raw)) return null;
+  const scp = raw.match(/^git@([^/:]+):(.+)$/);
+  const scpAbsolute = Boolean(scp && scp[2].startsWith('/'));
+  const expanded = scp ? `ssh://git@${scp[1]}/${scp[2].replace(/^\//, '')}` : raw;
+  const match = expanded.match(/^(https?|ssh):\/\/([^/]+)\/(.+)$/i);
+  if (!match) return null;
+  // Validate the original path before URL parsing can collapse dot segments.
+  let segments;
+  try {
+    segments = match[3].replace(/\/$/, '').split('/');
+    // Git passes SCP paths literally; percent escapes are decoded only in URIs.
+    if (!scp) segments = segments.map(decodeURIComponent);
+  }
+  catch { return null; }
+  if (segments.some((part) => !part || part === '.' || part === '..' || /[/\\\s\u0000-\u001f\u007f?#]/.test(part))) return null;
+  let url;
+  try { url = new URL(expanded); } catch { return null; }
+  const protocol = url.protocol;
+  if (protocol === 'ssh:' && (url.username !== 'git' || url.password)) return null;
+  if (authored && protocol !== 'ssh:' && (url.username || url.password)) return null;
+  const hostname = url.hostname.toLowerCase();
+  if (!hostname) return null;
+  const provider = hostname === 'github.com' ? 'github' : hostname === 'gitee.com' ? 'gitee' : null;
+  const last = segments.length - 1;
+  if (provider) segments[last] = segments[last].replace(provider === 'github' ? /\.git$/i : /\.git$/, '');
+  if (!segments[last] || segments[last] === '.' || segments[last] === '..') return null;
+  const repositoryPath = segments.join('/');
+  // Only known forges map HTTPS and SSH to one repository namespace. Other
+  // hosts retain transport, port and remote-relative/absolute path semantics.
+  const port = url.port || (protocol === 'ssh:' ? '22' : protocol === 'https:' ? '443' : '80');
+  const endpoint = provider && ((protocol === 'https:' && port === '443') || (protocol === 'ssh:' && port === '22'))
+    ? 'standard' : `${protocol}${port}`;
+  const pathKind = provider ? 'repository' : scp && !scpAbsolute ? 'relative' : 'absolute';
+  const identityPath = provider === 'github' ? repositoryPath.toLowerCase() : repositoryPath;
+  const encodedPath = segments.map(encodeURIComponent).join('/');
+  const canonicalUrl = scp ? `git@${hostname}:${scpAbsolute ? '/' : ''}${repositoryPath}`
+    : `${protocol}//${protocol === 'ssh:' ? 'git@' : ''}${url.host}/${encodedPath}`;
+  return { identity: JSON.stringify([hostname, endpoint, pathKind, identityPath]), url: canonicalUrl, provider, protocol, path: repositoryPath, endpoint };
+}
+
+export function redactRepositoryRemote(value) {
+  return String(value || '')
+    .replace(/^((?:https?|ssh):\/\/)[^/]*@/i, '$1REDACTED@')
+    .replace(/[?#].*$/s, '?REDACTED');
+}
+
+export function repositorySourceHref(provider, url, revision, source) {
+  const encodedPath = source.path.split('/').map(encodeURIComponent).join('/');
+  const end = source.endLine && source.endLine !== source.line
+    ? `-${provider === 'github' ? 'L' : ''}${source.endLine}` : '';
+  const fragment = source.line ? `#L${source.line}${end}` : '';
+  return `${url}/blob/${revision}/${encodedPath}${fragment}`;
+}

package/skills/archify/renderers/shared/text-fit.mjs

@@ -0,0 +1,49 @@
+// Single-line node text fitting, shared by every renderer.
+//
+// Node text (`label`, `sublabel`, `tag`) renders as one <text> element with
+// text-anchor="middle" and is never wrapped. Left unmeasured, an over-long
+// value silently spills across its neighbours while validation still reports
+// a clean receipt — the failure mode this module exists to close.
+//
+// Two halves, always used together:
+//   - fittedNodeFontSize shrinks the text toward a legible minimum at render
+//     time, so ordinary overruns simply get smaller instead of overlapping.
+//   - minimumNodeTextWidth reports the width the text still needs once it has
+//     shrunk as far as it may, so validation can reject what shrinking cannot
+//     save.
+//
+// The geometry constants below are shared; the per-field `preferred` and
+// `minimum` font sizes are not, because renderers set node text at different
+// sizes (architecture sublabels are 9px, the rest are 7px).
+
+import { textUnits } from './utils.mjs';
+
+// widthFactor: px of advance width per text unit, per px of font size.
+// horizontalPadding: total px reserved inside the box so text never touches
+// the border.
+export const nodeTextFit = {
+  widthFactor: 0.6,
+  horizontalPadding: 8,
+};
+
+// Largest font size at or below `preferred` that fits `text` inside `width`,
+// floored at `minimum` — below that the text is no longer legible and the
+// caller should be reporting a problem instead.
+export function fittedNodeFontSize(text, width, preferred, minimum) {
+  const units = Math.max(1, textUnits(text));
+  const available = Math.max(1, width - nodeTextFit.horizontalPadding);
+  const fitted = Math.min(preferred, available / (units * nodeTextFit.widthFactor));
+  return Math.max(minimum, Math.floor(fitted * 10) / 10);
+}
+
+// Width `text` occupies at its legible minimum. Compare against
+// `width - nodeTextFit.horizontalPadding` to decide whether shrink-to-fit can
+// rescue it.
+export function minimumNodeTextWidth(text, minimum) {
+  return textUnits(text) * minimum * nodeTextFit.widthFactor;
+}
+
+// Available text width inside a box of `width`.
+export function availableNodeTextWidth(width) {
+  return width - nodeTextFit.horizontalPadding;
+}

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

@@ -0,0 +1,232 @@
+import {
+  escapeHtml as esc,
+  localizeTemplate,
+  resolveLocale,
+  translateMessage,
+  viewerCatalog,
+} from './i18n.mjs';
+
+export { esc };
+
+export function renderDefinitions() {
+  return `        <!-- Definitions -->
+        <defs>
+          <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" class="m-default" />
+          </marker>
+          <marker id="arrowhead-emphasis" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" class="m-emphasis" />
+          </marker>
+          <marker id="arrowhead-security" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" class="m-security" />
+          </marker>
+          <marker id="arrowhead-dashed" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" class="m-dashed" />
+          </marker>
+          <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+            <path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
+          </pattern>
+        </defs>`;
+}
+
+const SIGIL_TONE = {
+  frontend: 'frontend',
+  start: 'frontend',
+  backend: 'backend',
+  active: 'backend',
+  database: 'database',
+  success: 'database',
+  cloud: 'cloud',
+  waiting: 'cloud',
+  security: 'security',
+  failure: 'security',
+  messagebus: 'messagebus',
+  external: 'external',
+  neutral: 'external',
+};
+
+const SIGIL_SHAPE = {
+  frontend: `<rect x="2" y="3" width="12" height="10" rx="2"/>
+            <path d="M2 6.5h12"/>
+            <circle cx="4.1" cy="4.8" r=".7" class="sigil-fill"/>
+            <circle cx="6.3" cy="4.8" r=".7" class="sigil-fill"/>`,
+  backend: `<path d="M6 3 3 8l3 5M10 3l3 5-3 5"/>`,
+  database: `<ellipse cx="8" cy="4" rx="5" ry="2"/>
+            <path d="M3 4v8c0 1.1 2.2 2 5 2s5-.9 5-2V4M3 8c0 1.1 2.2 2 5 2s5-.9 5-2"/>`,
+  cloud: `<path d="M4.3 12.5h7.3a2.4 2.4 0 0 0 .2-4.8 4 4 0 0 0-7.5-1.3A3.1 3.1 0 0 0 4.3 12.5Z"/>`,
+  security: `<path d="M8 2.2 13 4v3.5c0 3.1-1.8 5.4-5 6.5-3.2-1.1-5-3.4-5-6.5V4Z"/>
+            <path d="m5.8 8 1.5 1.5 3-3"/>`,
+  messagebus: `<path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11"/>
+            <circle cx="5" cy="4.5" r="1" class="sigil-fill"/>
+            <circle cx="10.5" cy="8" r="1" class="sigil-fill"/>
+            <circle cx="7" cy="11.5" r="1" class="sigil-fill"/>`,
+  external: `<rect x="2.5" y="5" width="8.5" height="8" rx="1.5"/>
+            <path d="M8 2.5h5.5V8M13.5 2.5 7.5 8.5"/>`,
+  start: `<circle cx="8" cy="8" r="5"/>
+            <path d="m7 5.4 3.6 2.6L7 10.6Z" class="sigil-fill"/>`,
+  active: `<path d="M2 8h3l1.5-3.5L9 12l1.6-4H14"/>`,
+  waiting: `<path d="M4 2.5h8M4 13.5h8M5 3c0 2.8 2 3.2 3 5-1 1.8-3 2.2-3 5M11 3c0 2.8-2 3.2-3 5 1 1.8 3 2.2 3 5"/>`,
+  success: `<circle cx="8" cy="8" r="5.3"/>
+            <path d="m5.2 8 1.8 1.8 3.8-4"/>`,
+  failure: `<circle cx="8" cy="8" r="5.3"/>
+            <path d="m5.7 5.7 4.6 4.6m0-4.6-4.6 4.6"/>`,
+  neutral: `<rect x="3" y="3" width="10" height="10" rx="2"/>
+            <circle cx="8" cy="8" r="1.2" class="sigil-fill"/>`,
+};
+
+// A quiet, renderer-owned role stamp. It is authored SVG content rather than a
+// viewer overlay, so it survives canonical export while adding no focus target,
+// accessible name, layout box, or interaction state of its own.
+export function renderSemanticSigil(kind, { x, y, size = 11 } = {}) {
+  const normalized = Object.hasOwn(SIGIL_SHAPE, kind) ? kind : 'neutral';
+  const tone = SIGIL_TONE[normalized] || 'external';
+  const scale = size / 16;
+  return `<g aria-hidden="true" data-semantic-sigil="${esc(normalized)}" class="semantic-sigil s-${tone}" transform="translate(${x} ${y}) scale(${scale})">
+            ${SIGIL_SHAPE[normalized]}
+          </g>`;
+}
+
+export function renderCards(cards) {
+  const list = Array.isArray(cards) ? cards : [];
+  return `    <!-- Info Cards -->
+    <div class="cards">
+${list.map((card) => `      <div class="card">
+        <div class="card-header">
+          <div class="card-dot ${esc(card.dot)}"></div>
+          <h3>${esc(card.title)}</h3>
+        </div>
+        <ul>
+${card.items.map((item) => `          <li>&bull; ${esc(item)}</li>`).join('\n')}
+        </ul>
+      </div>`).join('\n\n')}
+    </div>`;
+}
+
+const SVG_SLOT_RE = /      <!-- ARCHIFY:SVG_SLOT_START -->[\s\S]*?      <!-- ARCHIFY:SVG_SLOT_END -->/;
+const CARDS_SLOT_RE = /    <!-- ARCHIFY:CARDS_SLOT_START -->[\s\S]*?    <!-- ARCHIFY:CARDS_SLOT_END -->/;
+const SUBTITLE_SLOT_RE = /^([ \t]*)<p class="subtitle">\[Subtitle description\]<\/p>[ \t]*(\r?\n)?/m;
+const GUIDED_VIEWS_PLACEHOLDER = '<!-- ARCHIFY:GUIDED_VIEWS_DATA -->';
+const SOURCE_EVIDENCE_PLACEHOLDER = '    <!-- ARCHIFY:SOURCE_EVIDENCE_DATA -->';
+const I18N_PLACEHOLDER = '    <!-- ARCHIFY:I18N_DATA -->';
+
+function serializeScriptJson(value) {
+  return JSON.stringify(value)
+    .replaceAll('<', '\\u003c')
+    .replaceAll('>', '\\u003e')
+    .replaceAll('&', '\\u0026');
+}
+
+const TEMPLATE_PLACEHOLDERS = [
+  '<html lang="en" data-theme="dark" data-preset="[VISUAL PRESET]">',
+  '<title>[PROJECT NAME] Architecture Diagram</title>',
+  '<h1>[PROJECT NAME] Architecture</h1>',
+  GUIDED_VIEWS_PLACEHOLDER,
+];
+
+export function applyTemplate(template, {
+  title,
+  subtitle,
+  svg,
+  cards,
+  locale,
+  visualPreset = 'classic',
+  guidedViews = [],
+  sourceEvidence = null,
+}) {
+  if (!SVG_SLOT_RE.test(template)) {
+    throw new Error('applyTemplate: template missing ARCHIFY:SVG_SLOT sentinel');
+  }
+  if (!CARDS_SLOT_RE.test(template)) {
+    throw new Error('applyTemplate: template missing ARCHIFY:CARDS_SLOT sentinel');
+  }
+  if (!SUBTITLE_SLOT_RE.test(template)) {
+    throw new Error('applyTemplate: template missing subtitle placeholder');
+  }
+  for (const ph of TEMPLATE_PLACEHOLDERS) {
+    if (!template.includes(ph)) {
+      throw new Error(`applyTemplate: template missing placeholder ${JSON.stringify(ph)}`);
+    }
+  }
+  // Keep existing custom templates compatible when evidence is not requested.
+  // Silently dropping verified evidence would be misleading, so the new slot
+  // becomes mandatory only for the opt-in evidence path.
+  if (sourceEvidence && !template.includes(SOURCE_EVIDENCE_PLACEHOLDER)) {
+    throw new Error(`applyTemplate: repository evidence requires placeholder ${JSON.stringify(SOURCE_EVIDENCE_PLACEHOLDER)}`);
+  }
+  // Function replacers: a literal `$&`, `$'`, `$\`` or `$$` in titles, labels,
+  // or rendered SVG must not be interpreted as a replacement pattern.
+  const guidedViewsJson = serializeScriptJson(guidedViews);
+  const sourceEvidenceJson = serializeScriptJson(sourceEvidence);
+  const resolvedLocale = resolveLocale(locale);
+  const i18nJson = serializeScriptJson({ locale: resolvedLocale, messages: viewerCatalog(resolvedLocale) });
+  const renderedSubtitle = typeof subtitle === 'string' && subtitle.trim()
+    ? `<p class="subtitle">${esc(subtitle)}</p>`
+    : '';
+  const i18nData = `    <script id="archify-i18n-data" type="application/json">${i18nJson}</script>`;
+  const localizedTemplate = localizeTemplate(template, resolvedLocale);
+  const templateWithI18n = localizedTemplate.includes(I18N_PLACEHOLDER)
+    ? localizedTemplate.replace(I18N_PLACEHOLDER, () => i18nData)
+    : localizedTemplate.replace(GUIDED_VIEWS_PLACEHOLDER, () => `${i18nData}\n    ${GUIDED_VIEWS_PLACEHOLDER}`);
+  return templateWithI18n
+    .replace(TEMPLATE_PLACEHOLDERS[0], () => `<html lang="${esc(resolvedLocale)}" data-theme="dark" data-preset="${esc(visualPreset)}">`)
+    .replace(TEMPLATE_PLACEHOLDERS[1], () => `<title>${esc(translateMessage(resolvedLocale, 'page.title', { title }))}</title>`)
+    .replace(TEMPLATE_PLACEHOLDERS[2], () => `<h1>${esc(title)}</h1>`)
+    .replace(SUBTITLE_SLOT_RE, (_match, indent, newline = '') => renderedSubtitle
+      ? `${indent}${renderedSubtitle}${newline}`
+      : '')
+    .replace(SVG_SLOT_RE, () => svg)
+    .replace(CARDS_SLOT_RE, () => cards)
+    .replace(GUIDED_VIEWS_PLACEHOLDER, () => `<script id="archify-guided-views-data" type="application/json">${guidedViewsJson}</script>`)
+    .replace(SOURCE_EVIDENCE_PLACEHOLDER, () => sourceEvidence
+      ? `    <script id="archify-source-evidence-data" type="application/json">${sourceEvidenceJson}</script>`
+      : '');
+}
+
+// CJK and other wide/fullwidth glyphs render at roughly twice the advance
+// width of ASCII in the monospace stacks the template uses. Keep halfwidth
+// forms (notably U+FF61–U+FF9F Katakana) out of this set. The explicit ranges
+// also cover vertical punctuation and supplementary East Asian scripts that
+// literal glyph ranges made difficult to audit.
+// Code points that take two columns of advance width: East Asian Wide and
+// Fullwidth per UAX #11, tracking Unicode 17.0. That takes in the BMP symbols
+// carrying emoji presentation (U+2705, U+2B50, U+26A1, U+231B, ...), which
+// render at the same square advance as the supplementary-plane emoji already
+// listed here, and Hangul Jamo Extended-A. Two boundary calls worth naming:
+// Unicode 16.0 reclassified the trigrams (U+2630-U+2637) and the monogram /
+// digram symbols (U+268A-U+268F) from Neutral to Wide, so both are in; and
+// Hangul Jamo Extended-A stops at U+A97C, its last assigned jamo, because
+// U+A97D-U+A97F are unassigned, and unassigned code points outside the CJK
+// ranges UAX #11 names default to Neutral rather than Wide. Spelled out as
+// ranges because V8 has no \p{East_Asian_Width=W} property escape.
+const FULLWIDTH_RE = /[\u1100-\u115F\u231A-\u231B\u2329-\u232A\u23E9-\u23EC\u23F0\u23F3\u25FD-\u25FE\u2614-\u2615\u2630-\u2637\u2648-\u2653\u267F\u268A-\u268F\u2693\u26A1\u26AA-\u26AB\u26BD-\u26BE\u26C4-\u26C5\u26CE\u26D4\u26EA\u26F2-\u26F3\u26F5\u26FA\u26FD\u2705\u270A-\u270B\u2728\u274C\u274E\u2753-\u2755\u2757\u2795-\u2797\u27B0\u27BF\u2B1B-\u2B1C\u2B50\u2B55\u2E80-\uA4CF\uA960-\uA97C\uAC00-\uD7A3\uF900-\uFAFF\uFE10-\uFE19\uFE30-\uFE6F\uFF01-\uFF60\uFFE0-\uFFE6\u{16FE0}-\u{18DFF}\u{1AFF0}-\u{1AFFF}\u{1B000}-\u{1B2FF}\u{1F000}-\u{1FAFF}\u{20000}-\u{3FFFD}]/u;
+
+// A variation selector (U+FE00-U+FE0F) carries no advance of its own: it
+// re-presents the character before it. VS15 (U+FE0E) asks for text
+// presentation, which renders narrow; VS16 (U+FE0F) asks for emoji
+// presentation, which renders at the square emoji advance. So a base plus a
+// selector is measured from the selector, not from the base -- otherwise
+// widening the emoji-presentation bases above turns U+2B50 U+FE0F from two
+// units into three while the glyph on screen stays one square, and leaves
+// U+2708 U+FE0F at two only because its base happens to be narrow.
+//
+// A selector following a base that cannot take emoji presentation is
+// malformed input; measuring it wide is the safe direction here, since
+// over-measuring pads a box while under-measuring spills the label out of it.
+const VARIATION_SELECTOR_FIRST = 0xfe00;
+const VARIATION_SELECTOR_LAST = 0xfe0f;
+const VARIATION_SELECTOR_TEXT = 0xfe0e;
+const VARIATION_SELECTOR_EMOJI = 0xfe0f;
+
+export function textUnits(text) {
+  const chars = Array.from(String(text ?? ''));
+  let units = 0;
+  for (let i = 0; i < chars.length; i += 1) {
+    const codePoint = chars[i].codePointAt(0);
+    if (codePoint >= VARIATION_SELECTOR_FIRST && codePoint <= VARIATION_SELECTOR_LAST) continue;
+    const next = i + 1 < chars.length ? chars[i + 1].codePointAt(0) : -1;
+    if (next === VARIATION_SELECTOR_EMOJI) units += 2;
+    else if (next === VARIATION_SELECTOR_TEXT) units += 1;
+    else units += FULLWIDTH_RE.test(chars[i]) ? 2 : 1;
+  }
+  return units;
+}