dsh-knowhub 0.9.0 → 0.10.0

package/skills/archify/renderers/shared/sidecar-path.mjs

@@ -0,0 +1,38 @@
+import { createHash } from 'node:crypto';
+
+const SIDECAR_STEM_NAMESPACE = /\.~archify-[0-9a-f]{64}$/iu;
+
+export function sidecarStemNeedsBounding(stem, suffixes) {
+  const fits = (value) => value.length <= 255 && Buffer.byteLength(value, 'utf8') <= 255;
+  return !suffixes.every((suffix) => fits(`${stem}${suffix}`));
+}
+
+export function boundedSidecarStem(stem, suffixes, { force = false, hashDomain } = {}) {
+  if (!force && !sidecarStemNeedsBounding(stem, suffixes)
+    && !SIDECAR_STEM_NAMESPACE.test(stem)) return stem;
+  const hashInput = hashDomain ? `${hashDomain}\0${stem}` : stem;
+  const marker = `.~archify-${createHash('sha256').update(hashInput).digest('hex')}`;
+  const codePoints = [...stem];
+  while (codePoints.length
+    && sidecarStemNeedsBounding(`${codePoints.join('')}${marker}`, suffixes)) {
+    codePoints.pop();
+  }
+  return `${codePoints.join('')}${marker}`;
+}
+
+export function sidecarStemFromComponent(component) {
+  if (component.endsWith('.html')) {
+    return {
+      stem: component.slice(0, -'.html'.length),
+      options: undefined,
+    };
+  }
+  return {
+    stem: component,
+    options: { force: true, hashDomain: 'full-component' },
+  };
+}
+
+export function isBoundedSidecarStem(stem) {
+  return SIDECAR_STEM_NAMESPACE.test(stem);
+}

package/skills/archify/renderers/shared/software-notices.mjs

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+
+const files = ['NOTICE', 'LICENSE', 'LICENSE-MIT', 'THIRD_PARTY_NOTICES.md'];
+export const softwareNotices = files.map(name => `${name}\n${fs.readFileSync(new URL(`../../${name}`, import.meta.url), 'utf8').trimEnd()}`).join('\n\n');
+// JSON data preserves the exact notice text without HTML/script delimiters.
+export const softwareNoticesHtml = `<script type="application/json" id="archify-software-notices">${JSON.stringify(softwareNotices).replace(/</g, '\\u003c')}</script>`;

package/skills/archify/renderers/shared/spatial-grid.mjs

@@ -0,0 +1,66 @@
+/** Uniform spatial grid for "which items can this box reach" queries (#8). */
+
+// A cell box wider than this is not worth walking: the query returns every
+// inserted item instead, which stays a superset of what the box reaches.
+const DEFAULT_MAX_CELLS = 4096;
+
+export function createSpatialGrid(cellSize, { maxCells = DEFAULT_MAX_CELLS } = {}) {
+  const buckets = new Map();
+  const items = [];
+  // Items whose own box cannot be walked are candidates for every query.
+  const overflow = [];
+  const keyOf = (x, y) => x + ':' + y;
+  const rangeOf = (box) => ({
+    x0: Math.floor(box.minX / cellSize), x1: Math.floor(box.maxX / cellSize),
+    y0: Math.floor(box.minY / cellSize), y1: Math.floor(box.maxY / cellSize),
+  });
+  // Finite coordinates can still land outside the safe-integer range, where
+  // incrementing an index no longer advances it; and a legal coordinate can
+  // name more cells than the grid is worth. Both cases stay out of the buckets
+  // and are answered by the item list, so they never hang or allocate.
+  const walkable = (range) => Number.isSafeInteger(range.x0) && Number.isSafeInteger(range.x1)
+    && Number.isSafeInteger(range.y0) && Number.isSafeInteger(range.y1)
+    && (range.x1 - range.x0 + 1) * (range.y1 - range.y0 + 1) <= maxCells;
+
+  return {
+    insert(box, item) {
+      items.push(item);
+      const range = rangeOf(box);
+      if (!walkable(range)) {
+        overflow.push(item);
+        return;
+      }
+      for (let x = range.x0; x <= range.x1; x += 1) {
+        for (let y = range.y0; y <= range.y1; y += 1) {
+          const key = keyOf(x, y);
+          let bucket = buckets.get(key);
+          if (!bucket) { bucket = []; buckets.set(key, bucket); }
+          bucket.push(item);
+        }
+      }
+    },
+    query(box) {
+      const range = rangeOf(box);
+      if (!walkable(range)) return items.slice();
+      const seen = new Set();
+      const found = [];
+      for (let x = range.x0; x <= range.x1; x += 1) {
+        for (let y = range.y0; y <= range.y1; y += 1) {
+          const bucket = buckets.get(keyOf(x, y));
+          if (!bucket) continue;
+          for (const item of bucket) {
+            if (seen.has(item)) continue;
+            seen.add(item);
+            found.push(item);
+          }
+        }
+      }
+      for (const item of overflow) {
+        if (seen.has(item)) continue;
+        seen.add(item);
+        found.push(item);
+      }
+      return found;
+    },
+  };
+}

package/skills/archify/renderers/shared/svg-path-analysis.mjs

@@ -0,0 +1,135 @@
+// 仅分析静态检查器需要的路径子集，不作为通用 SVG 渲染器。
+const NUMBER = /[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/y;
+const COMMANDS = /^[MLHVQZACSTmlhvqzacst]$/;
+const ARITY = { M: 2, L: 2, H: 1, V: 1, Q: 4 };
+
+function failure(tokenOffset, reason, command, unsupported = false) {
+  return { ok: false, error: {
+    code: unsupported ? 'artifact/svg-path-unsupported' : 'artifact/svg-path-malformed',
+    tokenOffset, reason, ...(command ? { command } : {}),
+  } };
+}
+
+function tokenize(source) {
+  const tokens = [];
+  let offset = 0;
+  let comma = null;
+  while (offset < source.length) {
+    const character = source[offset];
+    if (/[ \t\r\n]/.test(character)) { offset += 1; continue; }
+    if (character === ',') {
+      if (comma !== null || tokens.at(-1)?.kind !== 'number') return failure(offset, 'unexpected comma');
+      comma = offset++;
+      continue;
+    }
+    if (COMMANDS.test(character)) {
+      if (comma !== null) return failure(comma, 'a comma must separate numbers');
+      tokens.push({ kind: 'command', value: character, offset: offset++ });
+      continue;
+    }
+    NUMBER.lastIndex = offset;
+    const number = NUMBER.exec(source);
+    if (!number) return failure(offset, 'expected a number or supported path command');
+    const value = Number(number[0]);
+    if (!Number.isFinite(value)) return failure(offset, 'coordinate is not finite');
+    tokens.push({ kind: 'number', value, offset });
+    offset = NUMBER.lastIndex;
+    comma = null;
+  }
+  return comma === null ? { ok: true, tokens } : failure(comma, 'trailing comma');
+}
+
+/** 每步消费一个命令或完整参数组；失败不返回部分几何。偏移基于传入的 d 字符串。 */
+export function analyzeSvgPath(source) {
+  if (typeof source !== 'string') return failure(0, 'path data must be a string');
+  const lexed = tokenize(source);
+  if (!lexed.ok) return lexed;
+  const { tokens } = lexed;
+  const subpaths = [];
+  let index = 0;
+  let command = null;
+  let commandOffset = 0;
+  let current = [0, 0];
+  let subpath;
+
+  function move(point) {
+    current = point;
+    subpath = { points: [point], segments: [], straightSegments: [], closed: false };
+    subpaths.push(subpath);
+  }
+  function line(point) {
+    const segment = { start: current, end: point };
+    subpath.segments.push(segment);
+    subpath.straightSegments.push(segment);
+    subpath.points.push(point);
+    current = point;
+  }
+
+  while (index < tokens.length) {
+    if (tokens[index].kind === 'command') {
+      command = tokens[index].value;
+      commandOffset = tokens[index++].offset;
+    } else if (!command) {
+      return failure(tokens[index].offset, 'a command is required after closepath');
+    }
+    const upper = command.toUpperCase();
+    if (!subpath && upper !== 'M') return failure(commandOffset, 'the first command must be moveto', command);
+    if (!Object.hasOwn(ARITY, upper) && upper !== 'Z') {
+      return failure(commandOffset, 'path command is not supported by artifact analysis', command, true);
+    }
+    if (upper === 'Z') {
+      line(subpath.points[0]);
+      subpath.closed = true;
+      command = null;
+      continue;
+    }
+    const parameters = [];
+    const parameterOffset = tokens[index]?.offset ?? source.length;
+    for (let count = 0; count < ARITY[upper]; count += 1) {
+      const token = tokens[index];
+      if (!token || token.kind !== 'number') {
+        return failure(token?.offset ?? source.length, `command ${command} requires ${ARITY[upper]} parameters`, command);
+      }
+      parameters.push(token.value);
+      index += 1;
+    }
+    const relative = command !== upper;
+    const point = (x, y) => relative ? [current[0] + x, current[1] + y] : [x, y];
+    let end;
+    let control;
+    if (upper === 'H') end = [relative ? current[0] + parameters[0] : parameters[0], current[1]];
+    else if (upper === 'V') end = [current[0], relative ? current[1] + parameters[0] : parameters[0]];
+    else if (upper === 'Q') {
+      control = point(parameters[0], parameters[1]);
+      end = point(parameters[2], parameters[3]);
+    } else end = point(parameters[0], parameters[1]);
+    if (![...end, ...(control || [])].every(Number.isFinite)) {
+      return failure(parameterOffset, 'computed coordinate is not finite', command);
+    }
+    if (upper === 'M') {
+      move(end);
+      // moveto 后的额外参数组是 lineto，不能变成额外子路径。
+      command = relative ? 'l' : 'L';
+      continue;
+    }
+    if (subpath.closed) move(current);
+    if (upper !== 'Q') { line(end); continue; }
+
+    const start = current;
+    const cross = (control[0] - start[0]) * (end[1] - start[1]) - (control[1] - start[1]) * (end[0] - start[0]);
+    if (Math.abs(cross) <= 1e-9) subpath.straightSegments.push({ start, end });
+    // 保留既有八步 Q 采样；非共线曲线不冒充结构框的直线边界。
+    for (let step = 1; step <= 8; step += 1) {
+      const amount = step / 8;
+      const remaining = 1 - amount;
+      const next = [0, 1].map(axis => remaining * remaining * start[axis]
+        + 2 * remaining * amount * control[axis] + amount * amount * end[axis]);
+      if (!next.every(Number.isFinite)) return failure(parameterOffset, 'sampled coordinate is not finite', command);
+      subpath.segments.push({ start: current, end: next });
+      subpath.points.push(next);
+      current = next;
+    }
+    current = end;
+  }
+  return { ok: true, subpaths };
+}

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

@@ -0,0 +1,105 @@
+// 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, SEMANTIC_SIGIL_INSET, SEMANTIC_SIGIL_SIZE, SEMANTIC_SIGIL_FOOTPRINT, SOURCE_BADGE_FOOTPRINT } 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;
+}
+
+// Adapted from Souptik Chakraborty's #220: shift only labels which reach a
+// corner icon. Unlike the original hard gate, a narrow valid node uses a
+// separate text row; its authored bounds and acceptance remain unchanged.
+export function nodeLabelLayout({ width, height, rows, side = 'left', brand = false, source = false, step = '' }) {
+  const result = { x: width / 2, ys: rows.map(row => row.y), sigilY: SEMANTIC_SIGIL_INSET, sigilSize: SEMANTIC_SIGIL_SIZE };
+  const labelWidth = minimumNodeTextWidth(rows[0].text, rows[0].font);
+  const stepEnd = step ? (side === 'left' ? 23 : 10) + minimumNodeTextWidth(step, 8) + 3 : 0;
+  const left = Math.max(side === 'left' ? SEMANTIC_SIGIL_FOOTPRINT + 2 : 4, stepEnd);
+  const right = width - (brand ? 26 : side === 'right' ? SEMANTIC_SIGIL_FOOTPRINT + 2 : 4)
+    - (source ? SOURCE_BADGE_FOOTPRINT : 0);
+  if (result.x - labelWidth / 2 >= left && result.x + labelWidth / 2 <= right) return result;
+  if (labelWidth <= right - left) {
+    // Round away from the icon, retaining the node centre whenever possible.
+    result.x = Math.min(Math.floor((right - labelWidth / 2) * 10) / 10,
+      Math.max(result.x, Math.ceil((left + labelWidth / 2) * 10) / 10));
+    return result;
+  }
+  // Keep the existing font sizes and put the text below the decoration rail.
+  // Conservative ascent/descent bounds also protect CJK and fallback fonts.
+  let bottom = Math.max(brand ? 22 : SEMANTIC_SIGIL_FOOTPRINT, source ? 19 : 0);
+  const ys = rows.map(row => {
+    const y = Math.max(row.y, Math.ceil((bottom + 2 + row.font * 1.2) * 10) / 10);
+    bottom = y + row.font * 0.3;
+    return y;
+  });
+  if (bottom <= height - 2) {
+    result.ys = ys;
+    return result;
+  }
+  if (source) {
+    // A source badge adds a second decoration on the right. On short boxes,
+    // restoring the original rows would put the title back under that badge.
+    // Try compact leading before giving up the dedicated text rail. Retain
+    // every font size and the authored box; only this crowded fallback packs
+    // the rows, with a full em above each baseline and 0.3 em below it.
+    let compactBottom = Math.max(brand ? 22 : SEMANTIC_SIGIL_FOOTPRINT, 19) + 1;
+    const compactYs = rows.map(row => {
+      const y = Math.ceil((compactBottom + 1 + row.font) * 10) / 10;
+      compactBottom = y + row.font * 0.3;
+      return y;
+    });
+    // The compact fallback may also use the otherwise reserved bottom
+    // padding; the entire descent still stays inside the fixed box.
+    if (compactBottom <= height - 0.5) {
+      result.ys = compactYs;
+      return result;
+    }
+  }
+  // A deliberately short fixed box may have no spare row. Preserve its text
+  // and geometry, and fit only the decorative sigil in the space above it.
+  result.sigilY = 1;
+  result.sigilSize = Math.max(1, Math.min(SEMANTIC_SIGIL_SIZE,
+    Math.floor(rows[0].y - rows[0].font * 1.2 - 3)));
+  return result;
+}

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

@@ -0,0 +1,260 @@
+import {
+  escapeHtml as esc,
+  localizeTemplate,
+  resolveLocale,
+  translateMessage,
+  viewerCatalog,
+} from './i18n.mjs';
+
+export { esc };
+
+// `extra` appends type-owned definitions (the entity renderer's cardinality
+// markers) inside the same <defs>. Callers that pass nothing keep the exact
+// bytes the five longer-standing renderers already emit.
+export function renderDefinitions(extra = '') {
+  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>${extra}
+        </defs>`;
+}
+
+const SIGIL_TONE = {
+  frontend: 'frontend',
+  start: 'frontend',
+  backend: 'backend',
+  active: 'frontend',
+  database: 'database',
+  success: 'backend',
+  cloud: 'cloud',
+  waiting: 'cloud',
+  security: 'security',
+  decision: 'database',
+  failure: 'security',
+  messagebus: 'messagebus',
+  external: 'external',
+  neutral: 'external',
+};
+
+const SIGIL_SHAPE = {
+  calendar: `<rect x="2" y="3.5" width="12" height="10.5" rx="2"/><path d="M5 2v3M11 2v3M2 7h12M5 10h2M9 10h2"/>`,
+  clock: `<circle cx="8" cy="8" r="6"/><path d="M8 4v4l3 2"/>`,
+  person: `<circle cx="8" cy="4.5" r="2.5"/><path d="M3 14v-2a5 5 0 0 1 10 0v2"/>`,
+  briefcase: `<rect x="2" y="5" width="12" height="9" rx="2"/><path d="M5 5V2h6v3M2 9h12M7 9v2h2V9"/>`,
+  flag: `<path d="M3 14V2h10l-2 3 2 3H3"/>`,
+  moon: `<path d="M13.5 10A6 6 0 0 1 6 2.5 6 6 0 1 0 13.5 10Z"/>`,
+  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"/>`,
+  decision: `<path d="M8 2.2 13.8 8 8 13.8 2.2 8Z"/>`,
+  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"/>`,
+  stop: `<circle cx="8" cy="8" r="5.3"/>
+            <rect x="6.1" y="6.1" width="3.8" height="3.8" rx=".5" class="sigil-fill"/>`,
+  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 corner symbol (type default or authored icon). It is
+// 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.
+// Shared with label clearance so the reserved rail matches the actual icon.
+export const SEMANTIC_SIGIL_INSET = 6;
+export const SEMANTIC_SIGIL_SIZE = 11;
+export const SEMANTIC_SIGIL_FOOTPRINT = SEMANTIC_SIGIL_INSET + SEMANTIC_SIGIL_SIZE;
+// The viewer installs a runtime "sources" beacon on the node's top-right
+// rail, just left of the brand mark. Layout must reserve the same footprint
+// so labels never sit under the badge.
+export const SOURCE_BADGE_FOOTPRINT = 38;
+
+export function renderSemanticSigil(kind, { x, y, size = SEMANTIC_SIGIL_SIZE, icon } = {}) {
+  if (icon === 'none') return '';
+  const selected = icon ?? kind;
+  const normalized = Object.hasOwn(SIGIL_SHAPE, selected) ? selected : 'neutral';
+  const tone = SIGIL_TONE[kind] || '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>${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 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>',
+  I18N_PLACEHOLDER,
+];
+
+export function applyTemplate(template, {
+  title,
+  subtitle,
+  svg,
+  cards,
+  locale,
+  visualPreset = 'classic',
+  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 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>`;
+  return localizeTemplate(template, resolvedLocale)
+    .replace(I18N_PLACEHOLDER, () => i18nData)
+    .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(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;
+
+// Variation selectors contribute no separate unit. This is a conservative
+// width estimate, not a measurement of the selected glyph: its actual advance
+// depends on the font and presentation (Unicode UAX #11).
+// VS16 requests emoji presentation, so reserve two units for the sequence.
+// VS15 retains the base's width estimate; forcing every text-presentation
+// sequence to one unit undercounts wide bases, including CJK characters whose
+// font ignores that selector. Neutral bases remain one unit. Some selected
+// text glyphs can be narrower than this estimate; prefer extra space to overflow.
+const VARIATION_SELECTOR_FIRST = 0xfe00;
+const VARIATION_SELECTOR_LAST = 0xfe0f;
+const VARIATION_SELECTOR_EMOJI = 0xfe0f;
+
+// Width measurement is pure and the same labels are measured many times per
+// compile, so the unit count is memoized by its input string.
+const TEXT_UNITS_CACHE = new Map();
+const MAX_TEXT_UNITS_CACHE_ENTRIES = 4096;
+const MAX_CACHED_TEXT_LENGTH = 1024;
+
+export function textUnits(text) {
+  const cacheKey = String(text ?? '');
+  const cachedUnits = TEXT_UNITS_CACHE.get(cacheKey);
+  if (cachedUnits !== undefined) return cachedUnits;
+  const chars = Array.from(cacheKey);
+  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 units += FULLWIDTH_RE.test(chars[i]) ? 2 : 1;
+  }
+  // Keep repeated in-process compiles bounded, including unusually long labels.
+  if (cacheKey.length <= MAX_CACHED_TEXT_LENGTH) {
+    if (TEXT_UNITS_CACHE.size >= MAX_TEXT_UNITS_CACHE_ENTRIES) {
+      TEXT_UNITS_CACHE.delete(TEXT_UNITS_CACHE.keys().next().value);
+    }
+    TEXT_UNITS_CACHE.set(cacheKey, units);
+  }
+  return units;
+}