@stacksjs/defaults 0.75.361 → 0.75.366

package/ai/skills/stacks-technical-diagrams/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/ai/skills/stacks-technical-diagrams/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/ai/skills/stacks-technical-diagrams/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/ai/skills/stacks-technical-diagrams/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/ai/skills/stacks-technical-diagrams/renderers/shared/text-fit.mjs

@@ -3,7 +3,7 @@
 // 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.
+// 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
@@ -16,7 +16,7 @@
 // `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';
+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
@@ -27,7 +27,7 @@ export const nodeTextFit = {
 };
 
 // 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
+// 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));
@@ -47,3 +47,59 @@ export function minimumNodeTextWidth(text, minimum) {
 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/ai/skills/stacks-technical-diagrams/renderers/shared/utils.mjs

@@ -8,7 +8,10 @@ import {
 
 export { esc };
 
-export function renderDefinitions() {
+// `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">
@@ -25,7 +28,7 @@ export function renderDefinitions() {
           </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>
+          </pattern>${extra}
         </defs>`;
 }
 
@@ -33,12 +36,13 @@ const SIGIL_TONE = {
   frontend: 'frontend',
   start: 'frontend',
   backend: 'backend',
-  active: 'backend',
+  active: 'frontend',
   database: 'database',
-  success: 'database',
+  success: 'backend',
   cloud: 'cloud',
   waiting: 'cloud',
   security: 'security',
+  decision: 'database',
   failure: 'security',
   messagebus: 'messagebus',
   external: 'external',
@@ -46,6 +50,12 @@ const SIGIL_TONE = {
 };
 
 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"/>
@@ -66,20 +76,35 @@ const SIGIL_SHAPE = {
             <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 role stamp. It is authored SVG content rather than a
+// 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.
-export function renderSemanticSigil(kind, { x, y, size = 11 } = {}) {
-  const normalized = Object.hasOwn(SIGIL_SHAPE, kind) ? kind : 'neutral';
-  const tone = SIGIL_TONE[normalized] || 'external';
+// 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]}
@@ -96,7 +121,7 @@ ${list.map((card) => `      <div class="card">
           <h3>${esc(card.title)}</h3>
         </div>
         <ul>
-${card.items.map((item) => `          <li>&bull; ${esc(item)}</li>`).join('\n')}
+${card.items.map((item) => `          <li>${esc(item)}</li>`).join('\n')}
         </ul>
       </div>`).join('\n\n')}
     </div>`;
@@ -105,7 +130,6 @@ ${card.items.map((item) => `          <li>&bull; ${esc(item)}</li>`).join('\n')}
 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 -->';
 
@@ -120,7 +144,7 @@ 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,
+  I18N_PLACEHOLDER,
 ];
 
 export function applyTemplate(template, {
@@ -130,7 +154,6 @@ export function applyTemplate(template, {
   cards,
   locale,
   visualPreset = 'classic',
-  guidedViews = [],
   sourceEvidence = null,
 }) {
   if (!SVG_SLOT_RE.test(template)) {
@@ -155,7 +178,6 @@ export function applyTemplate(template, {
   }
   // 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) });
@@ -163,11 +185,8 @@ export function applyTemplate(template, {
     ? `<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
+  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>`)
@@ -176,7 +195,6 @@ export function applyTemplate(template, {
       : '')
     .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>`
       : '');
@@ -184,7 +202,7 @@ export function applyTemplate(template, {
 
 // 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
+// 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
@@ -200,33 +218,43 @@ export function applyTemplate(template, {
 // 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.
+// 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_TEXT = 0xfe0e;
 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 chars = Array.from(String(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 if (next === VARIATION_SELECTOR_TEXT) units += 1;
     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;
 }

package/ai/skills/stacks-technical-diagrams/renderers/shared/validator.mjs

@@ -57,7 +57,7 @@ export function validateSchema(diagramType, data) {
         additionalProperties: [`remove unsupported property ${JSON.stringify(error.params?.additionalProperty)}`],
         required: [`add required property ${JSON.stringify(error.params?.missingProperty)}`],
         type: [`use ${JSON.stringify(error.params?.type)} at ${annotated.path}`],
-        enum: [`choose one of ${JSON.stringify(error.params?.allowedValues || [])}`],
+        enum: [`choose one of the allowed values`],
         pattern: [`match the required pattern ${JSON.stringify(error.params?.pattern)}`],
         minimum: [`use a value ${error.params?.comparison || '>='} ${error.params?.limit}`],
         maximum: [`use a value ${error.params?.comparison || '<='} ${error.params?.limit}`],
@@ -66,13 +66,10 @@ export function validateSchema(diagramType, data) {
         minLength: [`provide at least ${error.params?.limit} character(s)`],
         maxLength: [`provide at most ${error.params?.limit} character(s)`],
       }[error.keyword] || [];
-      const detail = error.params && Object.keys(error.params).length
-        ? ` ${JSON.stringify(error.params)}`
-        : '';
       return {
         code: `schema/${error.keyword}`,
         severity: 'error',
-        message: `${annotatePath(error.instancePath, data)} ${error.message}${detail}`,
+        message: `${annotatePath(error.instancePath, data)} ${error.message}`,
         subject,
         evidence,
         supportedFixes,

package/ai/skills/stacks-technical-diagrams/renderers/timeline/README.md

@@ -0,0 +1,76 @@
+# Event Timeline Renderer
+
+Render `diagram_type: "timeline"` JSON files into the standard Archify HTML template.
+
+```bash
+node archify/renderers/timeline/render-timeline.mjs input.timeline.json output.html
+```
+
+`--layout-json` prints the axis segments, breaks, ticks, lanes, and placed
+events (with their millisecond timestamps and x positions) instead of HTML.
+
+## Input
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "timeline",
+  "meta": { "title": "Payment failure incident", "evidence": "illustrative", "timezone": "Asia/Shanghai" },
+  "lanes": [{ "id": "release", "label": "Release" }],
+  "events": [{ "id": "deploy", "at": "2026-10-01T10:00:00+08:00", "title": "Deploy v2.4", "lane": "release" }]
+}
+```
+
+- `at` is ISO 8601 with an explicit `Z` or `±HH:MM` offset (schema). An
+  impossible date fails `timeline/invalid-timestamp`.
+- `meta.timezone` is an IANA zone (default `UTC`) used for every tick and label;
+  ticks fall on that zone's wall clock, so a `+05:30` zone ticks on its own
+  hours. An unknown zone fails `timeline/invalid-timezone`.
+- Across timezone-offset changes, daily ticks stay at local midnight and hourly
+  ticks use real local instants. Both occurrences of a repeated hour remain;
+  skipped hours or dates do not invent ticks. Event timestamps and proportional
+  elapsed-time spacing are unchanged, so consecutive daily ticks can be 23 or 25
+  hours apart. The existing label filter still hides text that does not fit.
+- 夏令时和时区调整不会把刻度固定在时间段起点的 UTC 偏移上：日刻度保持当地
+  午夜，小时刻度仅对应真实存在的当地时刻。回拨产生的两个相同墙钟时刻都保留；
+  跳过的小时或整天不补造刻度。事件时间与轴上的实际时间距离不变，因此相邻
+  日刻度之间可以是 23 或 25 小时；空间不足的刻度文字仍按原有规则隐藏。
+- `meta.evidence` (`observed` or `illustrative`) is required and drawn as a
+  badge at the top-left of the canvas.
+- With `lanes`, every event names a declared lane (`timeline/unknown-lane`).
+  `detail` appears in the Semantic Passport; `kind` (`change`, `alert`,
+  `action`, `recovery`) colours the card and adds a legend entry.
+
+## Axis
+
+Events are sorted by time (ties keep authored order). x is linear in time with
+one scale for the whole diagram; every lane shares the same axis, so one
+instant has one x in every lane, whatever offset each timestamp was written in.
+
+`layout.breaks: "auto"` (default) compresses a quiet period longer than 8× the
+median gap between distinct timestamps and 10% of the span (at most the eight
+longest that fit while preserving room for proportional time). A break is a
+fixed-width hatched band with a zig-zag on the axis and
+the omitted duration (`≈ 1 d 11 h`); the axis caption states how many periods
+were compressed, and each break carries `data-break-ms` and an accessible label.
+Inside each segment the scale is the same constant, so distances there remain
+exact. `layout.breaks: "none"` draws one proportional axis. `layout.width`
+(default 960) is the axis width.
+
+## Cards
+
+Each event is a dot on its lane line plus a card with its exact time and title.
+Cards are centred on their instant and sit on either side of the lane line,
+packed into rows outward from it: each takes whichever side lets it sit closest
+to the line without touching an earlier card (ties go below), so simultaneous
+and close events stack instead of overprinting and a burst spreads both ways.
+Stems are drawn behind every card, and every dot sits on one shared halo layer, so events seconds apart merge into one outlined capsule. A card is a quiet surface with a tone accent
+for its kind. Titles wrap between words. On a multi-day axis a tick names its
+date only when the date changes.
+
+## Tested size
+
+`examples/archify-dev-activity.timeline.json` is observed data (20 tag and
+merge timestamps from this repository's `origin/dev`, including events 19 s
+apart, a `+05:30` committer offset, and five compressed quiet periods). It
+renders in about 0.3s and passes the showcase gates.