@stacksjs/defaults 0.75.361 → 0.75.362

package/ai/skills/stacks-technical-diagrams/explainer/render.mjs

@@ -0,0 +1,224 @@
+import fs from 'node:fs';
+import { softwareNoticesHtml } from '../renderers/shared/software-notices.mjs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { renderInline } from './inline.mjs';
+import { parseExplainerDiff } from './diff.mjs';
+import { computeExplainerRevision } from './revision.mjs';
+import { layoutExplainerPanels } from './layout.mjs';
+import { compileExplainerChart } from './charts.mjs';
+import { packPageBundle } from './page-bundle.mjs';
+
+const css = fs.readFileSync(new URL('./reader.css', import.meta.url), 'utf8');
+const js = fs.readFileSync(new URL('./reader.js', import.meta.url), 'utf8');
+const escape = value => String(value ?? '').replace(/[&<>"']/g, character => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[character]));
+const json = value => JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+const hash = text => createHash('sha256').update(text).digest('hex');
+// Toolbar glyphs, drawn with currentColor so they follow the theme.
+const icon = path => `<svg class="tool-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="${path}"/></svg>`;
+const icons = {
+  chevron: icon('M4.5 6.5 8 10l3.5-3.5'),
+  check: icon('M3.5 8.5 6.5 11.5 12.5 4.5'),
+  image: icon('M2.5 3.5h11v9h-11zM2.5 10.5l3-3 3 3 2-2 3 3M10.5 6.25a.75.75 0 1 0 0 .01'),
+  print: icon('M4.5 6V2.5h7V6M4.5 11.5h-2v-5h11v5h-2M4.5 9.5h7v4h-7z'),
+  expand: icon('M9.5 2.5h4v4M13.5 2.5 9.5 6.5M6.5 13.5h-4v-4M2.5 13.5l4-4'),
+  close: icon('M4 4l8 8M12 4l-8 8'),
+  export: icon('M8 2.5v7M5 6.5l3 3 3-3M3 11v2.5h10V11'),
+};
+// The Archify symbol (docs/assets/archify-mark.svg), for the favicon and the colophon.
+const mark = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 360" fill="none"><path d="M151 94 81 164C67 178 60 191 60 212V248H97V212C97 204 100 199 106 193L179 120Z" fill="#0856F5"/><path d="M238 135C252 132 261 126 270 116L321 167C334 180 339 194 339 213V248H303V213C303 204 300 199 294 193Z" fill="#1DBBB7"/><rect x="146" y="16" width="110" height="104" rx="30" fill="#0856F5"/><rect x="18" y="238" width="110" height="104" rx="28" fill="#0856F5"/><rect x="274" y="238" width="108" height="104" rx="28" fill="#1DBBB7"/></svg>';
+const favicon = `data:image/svg+xml,${encodeURIComponent(mark)}`;
+const dictionaries = {
+  en:{answer:'Answer',answerMark:'A',scope:'Applies to',sources:'Sources',print:'Print / PDF',image:'Long image',imageHints:['Sharpest','Smallest','Opens anywhere'],export:'Export',style:'Style',styles:{clean:'Clean',editorial:'Editorial',product:'Product',swiss:'Swiss'},auto:'System',light:'Light',dark:'Dark',typical:'Typical value',explore:'Open interactive view',exploreTitle:'Zoom, find nodes, trace paths, upstream and downstream, export images or motion',close:'Close',loading:'Opening diagram…',graph:'Diagram structure',changes:'Structure changes',added:'Added',removed:'Removed',modified:'Modified',copy:'Copy',copied:'Copied',walk:'Step through',walkMessages:'Play messages',walkFlow:'Walk the flow',prev:'Back',next:'Next',end:'Done',ask:'Ask',askQuote:'Ask about this',askPlaceholder:'What is unclear, or what should this part cover?',askCopy:'Copy question',askCopied:'Copied. Paste it to your agent.',askCancel:'Cancel',askChips:['I do not follow this part','Go deeper','Give an example','What is this based on?'],askPage:'Page',askFile:'File',askWhere:'Where',askQuoteLabel:'Quote',askQuestion:'Question',askNote:'Copies the page, the panel and its ID, so your agent can revise just this part.',askPatch:'Revise only this panel with Archify panel replacement (patch explainer), keeping its ID.',tagline:'Turn anything you want to understand, plan, or share into an interactive visual.',facts:{panels:n=>`${n} ${n === 1 ? 'panel' : 'panels'}`,diagrams:n=>`${n} ${n === 1 ? 'diagram' : 'diagrams'} validated`,sources:n=>`${n} ${n === 1 ? 'source' : 'sources'}`,pinned:rev=>`code pinned to ${rev}`}},
+  zh:{answer:'结论',answerMark:'答',scope:'适用于',sources:'来源',print:'打印 / PDF',image:'长图',imageHints:['最清晰','体积最小','兼容最好'],export:'导出',style:'样式',styles:{clean:'简洁',editorial:'杂志',product:'产品',swiss:'网格'},auto:'系统',light:'浅色',dark:'深色',typical:'典型值',explore:'打开交互图',exploreTitle:'缩放、搜索节点、追踪路径和上下游，导出图片或动画',close:'关闭',loading:'正在打开交互图…',graph:'图的结构',changes:'结构改动',added:'新增',removed:'删除',modified:'修改',copy:'复制',copied:'已复制',walk:'逐步看',walkMessages:'逐条看消息',walkFlow:'沿流程看',prev:'上一步',next:'下一步',end:'结束',ask:'追问',askQuote:'追问这段',askPlaceholder:'哪里没看懂，或者希望这块补充什么？',askCopy:'复制追问',askCopied:'已复制，粘贴给 agent 即可',askCancel:'取消',askChips:['没看懂这块','展开讲讲','举个例子','依据是什么？'],askPage:'页面',askFile:'文件',askWhere:'位置',askQuoteLabel:'引用',askQuestion:'问题',askNote:'会一并复制页面、面板位置和 ID，agent 可以只改这一块。',askPatch:'请用 Archify 的面板替换（patch explainer）只更新这个面板，保留它的 ID。',tagline:'把你想理解、规划或分享的事，变成可以互动的可视化作品。',facts:{panels:n=>`${n} 个面板`,diagrams:n=>`${n} 张图已通过结构校验`,sources:n=>`${n} 个来源`,pinned:rev=>`代码固定在提交 ${rev}`}}
+};
+
+/** Render a validated canonical explainer with separately prepared, immutable resources. */
+export function renderExplainer(document, options = {}) {
+  const { preparedBundle, sourceText = JSON.stringify(document), sourceMap = {}, sourcePath, preparedSources = {}, preparedDiagrams = {}, diagnostics = [], pageDirectory } = options;
+  const locale = document.meta.locale || 'zh-CN';
+  // Chinese pages get Chinese controls; every other language gets the English ones.
+  const english = !locale.startsWith('zh');
+  const words = dictionaries[english ? 'en' : 'zh'];
+  const sources = preparedSources.sources || preparedSources;
+  const assets = preparedSources.assets || {};
+  const diagrams = preparedDiagrams.diagrams || preparedDiagrams;
+  const sourceSha256 = hash(sourceText);
+  const revision = computeExplainerRevision({document,sourceText,preparedSources,preparedDiagrams,dependencies:preparedBundle?.dependencies});
+  const footnotes = [];
+  const citations = new Map();
+  const inline = (text, panelId, blockId) => renderInline(String(text ?? ''), {document,sources,diagrams,panelId,blockId,footnotes,citations});
+  function unavailable(block, message) {
+    const panelIndex = document.panels.findIndex(panel => panel.blocks.includes(block));
+    const pointer = `/panels/${panelIndex}/blocks/${document.panels[panelIndex]?.blocks.indexOf(block)}`;
+    const diagnostic = {code:'explainer/render-resource',severity:'error',message,subject:{component:block.type,path:pointer,input:sourcePath,...sourceMap[pointer]},evidence:{reason:message,example:'Prepare Git excerpts and native diagrams before rendering.'},supportedFixes:[]};
+    throw Object.assign(new Error(message), {code:diagnostic.code,diagnostics:[diagnostic],archifyDiagnostics:[diagnostic]});
+  }
+  const nativeLink = (target, text) => {
+    const nativeHash = target.node ? `focus=${encodeURIComponent(target.node)}` : target.route ? `route=${encodeURIComponent(target.route[0])}~${encodeURIComponent(target.route[1])}` : '';
+    return `<a class="diagram-link" href="#${escape(target.diagram)}" data-diagram-link="${escape(target.diagram)}" data-diagram-hash="${escape(nativeHash)}"${target.edges ? ` data-diagram-edges="${escape(JSON.stringify(target.edges))}"` : ''}>${text}<span aria-hidden="true"> ↗</span></a>`;
+  };
+  function blockHtml(block, panelId) {
+    const i = text => inline(text,panelId,block.id);
+    let body;
+    switch (block.type) {
+      case 'prose': body = block.text.split(/\n\s*\n/).map(text => `<p>${i(text)}</p>`).join(''); break;
+      case 'list': { const tag = block.ordered ? 'ol' : 'ul'; if (block.checklist) { body = `<ul class="checklist">${block.items.map(text => `<li><label><input type="checkbox"><span>${i(text)}</span></label></li>`).join('')}</ul>`; break; } body = `<${tag} class="text-list">${block.items.map(text => `<li>${i(text)}</li>`).join('')}</${tag}>`; break; }
+      case 'callout': body = `<aside class="callout ${escape(block.level)}">${block.title ? `<h3>${i(block.title)}</h3>` : ''}<p>${i(block.text)}</p></aside>`; break;
+      case 'comparison': body = `<div class="table-scroll"><table><thead><tr><th scope="col">${block.labelColumn ? i(block.labelColumn) : ''}</th>${block.columns.map(text => `<th scope="col">${i(text)}</th>`).join('')}</tr></thead><tbody>${block.rows.map(row => `<tr id="${escape(row.id)}"><th scope="row">${i(row.label)}</th>${row.cells.map(cell => `<td>${cell.assessment ? `<span class="assessment ${escape(cell.assessment)}"><span class="assessment-meter" aria-hidden="true"><i></i><i></i><i></i></span><b>${i(cell.verdict || ({good:english?'Favorable':'有利',caution:english?'Tradeoff':'有代价',bad:english?'Unfavorable':'不利'}[cell.assessment]))}</b></span>` : ''}${cell.assessment && cell.text === cell.verdict ? '' : `<span class="cell-text">${i(cell.text)}</span>`}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`; break;
+      case 'facts': body = `<dl class="facts">${block.entries.map(entry => `<div><dt>${i(entry.key)}</dt><dd>${i(entry.value)}</dd></div>`).join('')}</dl>`; break;
+      case 'metric': {
+        const over = block.value !== undefined && block.limit !== undefined && block.value > block.limit;
+        const unit = escape(block.unit || '');
+        body = `<div class="metric${over ? ' metric-over-limit' : ''}" data-metric-status="${over ? 'over-limit' : block.value === undefined ? 'limit-only' : 'within-limit'}"><span class="metric-label">${i(block.label)}</span><p class="metric-value">${block.value === undefined ? `${english?'Limit':'上限'} ${escape(block.limit)}<span>${unit}</span>` : `${escape(block.value)}${block.unit ? `<span>${unit}</span>` : ''}${block.limit === undefined ? '' : `<small> / ${escape(block.limit)}${unit}</small>`}`}</p>${block.value !== undefined && block.limit > 0 ? `<meter min="0" max="${escape(block.limit)}" value="${escape(Math.max(0, Math.min(block.value,block.limit)))}" aria-label="${escape(block.label)}">${escape(block.value)} / ${escape(block.limit)}</meter>` : ''}${over ? `<p class="metric-overflow">${english?'Over limit by':'超限'} ${escape(block.value - block.limit)}${block.unit ? ` ${unit}` : ''}</p>` : ''}${block.typical ? `<span class="typical">${words.typical}</span>` : ''}${block.note ? `<p class="fine">${i(block.note)}</p>` : ''}</div>`;
+        break;
+      }
+      case 'steps': body = `<ol class="steps">${block.items.map(item => `<li id="${escape(item.id)}"><b>${item.target ? nativeLink(item.target,i(item.text)) : i(item.text)}</b>${item.detail ? `<p>${i(item.detail)}</p>` : ''}</li>`).join('')}</ol>`; break;
+      case 'diagram': { const diagram = diagrams[block.id]; if (!diagram?.svg || !diagram?.html) unavailable(block,`Missing prepared native diagram: ${block.id}`); const title = diagram.spec?.meta?.title || block.id; const svg = staticSvg(diagram.svg, block.id); const previewClass = previewPrefix(block.id); const nativeStyle = scopeNativeCss(diagram.styles ?? nativeStyles(diagram.html), '.' + previewClass, previewClass + '-', diagram.svg); const nativeWidth = Number(diagram.svg.match(/viewBox=["'][^"']*?[\d.-]+[ ,]+[\d.-]+[ ,]+([\d.]+)/)?.[1]); const lanes = diagram.spec?.lanes || [], singleLane = lanes.length === 1 ? ' single-lane bare-lanes' : lanes.length && lanes.every(lane => /^lane-\d+$/.test(lane.id)) ? ' bare-lanes' : ''; body = `<figure class="diagram"><figcaption><span class="diagram-title">${escape(title)}</span><span class="diagram-actions interactive"><button class="tool-button explore-button" type="button" data-open-diagram="${escape(block.id)}" title="${words.exploreTitle}">${icons.expand}<span>${words.explore}</span></button></span></figcaption><div class="diagram-preview ${previewClass}${singleLane}" role="img" aria-label="${escape(title)}"${block.nodeSources ? ` data-node-sources="${escape(JSON.stringify(block.nodeSources))}"` : ''}${nativeWidth > 0 ? ` style="--native-width:${Math.round(nativeWidth)}px"` : ''}><style>${nativeStyle}</style>${svg}</div></figure><p class="diagram-fit-status fine" role="status" hidden></p><details class="diagram-semantics" open><summary>${words.graph}</summary><ul>${(diagram.semantic?.nodes || []).map(node => `<li>${escape(node.label || node.id)} <code>${escape(node.id)}</code></li>`).join('')}${(diagram.semantic?.edges || []).map(edge => `<li><code>${escape(edge.from)}</code> → <code>${escape(edge.to)}</code>${edge.label ? ` · ${escape(edge.label)}` : ''}</li>`).join('')}</ul></details>${block.changes?.length ? `<dl class="changes"><dt>${words.changes}</dt>${block.changes.map(change => `<dd><span class="chip ${escape(change.change)}">${words[change.change]}</span> <code>${escape(change.target)}</code></dd>`).join('')}</dl>` : ''}`; break; }
+      case 'chart': { const text = block.text ?? preparedSources.charts?.[block.id]; if (typeof text !== 'string') unavailable(block,`Missing prepared chart data: ${block.id}`); const chart = compileExplainerChart(text); if (chart.error) unavailable(block, chart.error); body = `<figure class="chart" style="--native-width:${Math.round(chart.width)}px">${chart.svg.replace(/^<svg\b[^>]*>/, tag => tag.replace(/\s(?:width|height)="[^"]*"/g, ''))}${block.title ? `<figcaption>${i(block.title)}</figcaption>` : ''}</figure>`; break; }
+      case 'snippet': body = `<figure class="snippet"><figcaption><span class="snippet-label">${block.title ? i(block.title) : ''}${block.language ? `<code class="snippet-language">${escape(block.language)}</code>` : ''}</span><button class="text-button interactive" type="button" data-copy>${words.copy}</button></figcaption><pre><code${block.language ? ` class="language-${escape(block.language)}"` : ''}>${escape(block.text)}</code></pre></figure>`; break;
+      case 'code': { const source = sources[block.source]; if (!source?.path || typeof source.text !== 'string') unavailable(block,`Code requires a Git excerpt: ${block.source}`); body = `<figure class="code"><figcaption>${i(`[](source:${block.source})`)}<span>${escape(source.path)}:${escape(source.lines?.join('–'))}</span></figcaption><pre><code${block.language ? ` class="language-${escape(block.language)}"` : ''}>${escape(source.text)}</code></pre></figure>`; break; }
+      case 'diff': {
+        const parsed = parseExplainerDiff(block.text,{component:'diff',input:sourcePath,panelId});
+        if(parsed.diagnostics.some(diagnostic=>diagnostic.severity === 'error')) throw Object.assign(new Error(`Malformed diff: ${block.id}`),{diagnostics:parsed.diagnostics,archifyDiagnostics:parsed.diagnostics});
+        body = `<figure class="diff" data-diff-format="${parsed.format}"><figcaption>${block.caption ? `<span>${i(block.caption)}</span>` : ''}<span class="diff-summary"><span class="added">+${parsed.counts.added} ${words.added}</span> · <span class="removed">−${parsed.counts.removed} ${words.removed}</span></span></figcaption><div class="diff-scroll"><table class="diff-code" aria-label="${escape(block.caption || (english?'Code changes':'代码改动'))}"><thead><tr><th scope="col">${english?'Old':'原行'}</th><th scope="col">${english?'New':'新行'}</th><th scope="col">${english?'Change':'改动'}</th></tr></thead><tbody>${parsed.rows.map(row=>`<tr class="diff-line ${escape(row.kind)}" data-diff-kind="${escape(row.kind)}"${row.oldLine === null ? '' : ` data-old-line="${row.oldLine}"`}${row.newLine === null ? '' : ` data-new-line="${row.newLine}"`}><td class="diff-number">${row.oldLine ?? ''}</td><td class="diff-number">${row.newLine ?? ''}</td><td><code>${escape(row.raw)}</code></td></tr>`).join('')}</tbody></table></div></figure>`;
+        break;
+      }
+      case 'image': { const asset = assets[block.id]; if (!asset?.dataUrl || !/^data:image\/(png|jpeg|webp|gif);base64,/.test(asset.dataUrl)) unavailable(block,`Missing contained image: ${block.id}`); body = `<figure class="image"><img src="${escape(asset.dataUrl)}" alt="${escape(block.alt)}">${block.caption ? `<figcaption>${i(block.caption)}</figcaption>` : ''}</figure>`; break; }
+      default: throw new Error(`Unsupported explainer block: ${block.type}`);
+    }
+    return `<div class="block block-${escape(block.type)}" id="${escape(block.id)}" data-block-type="${escape(block.type)}">${body}</div>`;
+  }
+  const scopeHtml = scope => { const parts = scopeParts(scope); return parts.length > 1 ? parts.map(part=>`<span class="scope-chip">${inline(part)}</span>`).join('') : `<span>${inline(scope)}</span>`; };
+  // Render in reading order so the first citation receives number one.
+  const answerHtml = `<header class="panel-head"><span class="panel-id answer-id" aria-hidden="true">${words.answerMark}</span><h2>${words.answer}</h2></header><div class="panel-body"><p class="verdict">${inline(document.answer.summary)}</p>${document.answer.reasons?.length ? `<ol class="reasons">${document.answer.reasons.map(reason=>`<li>${inline(reason)}</li>`).join('')}</ol>` : ''}</div>${document.answer.scope ? `<p class="answer-scope"><span class="scope-label">${words.scope}</span>${scopeHtml(document.answer.scope)}</p>` : ''}`;
+  const rows=layoutExplainerPanels(document,diagrams);
+  const panels=rows.flatMap((row,rowIndex)=>row.map(item=>{
+    if(item.spacer)return `<div class="board-spacer span${item.span}" data-row="${rowIndex}" aria-hidden="true"></div>`;
+    if(item.answer)return `<section id="answer" class="panel answer-panel span${item.span}" data-row="${rowIndex}" data-span-min="${item.min}">${answerHtml}</section>`;
+    const panel=item.panel,index=document.panels.indexOf(panel);
+    const measure=panel.blocks.every(block=>['prose','list','steps','callout','facts','metric'].includes(block.type)) ? ' data-measure="text"' : '';
+    const blocks=panel.blocks.map(block=>blockHtml(block,panel.id)), figures=panel.blocks.filter(block=>block.type === 'diagram');
+    // Steps that point into the panel's one diagram are read beside it: text left, diagram right.
+    const guided=figures.length === 1 && panel.blocks.some(block=>block.type === 'steps' && block.items.some(step=>step.target?.diagram === figures[0].id));
+    const body=guided ? `<div class="panel-body guided"><div class="guide-figure">${blocks[panel.blocks.indexOf(figures[0])]}</div><div class="guide-text">${blocks.filter((_,n)=>panel.blocks[n] !== figures[0]).join('')}</div></div>` : `<div class="panel-body">${blocks.join('')}</div>`;
+    return `<section class="panel span${item.span}${figures.length ? ' diagram-panel' : ''}" id="${escape(panel.id)}" data-row="${rowIndex}" data-span-min="${item.min}"${item.explicit ? ` data-span-fixed="${item.span}"` : ''}${measure} data-title="${escape(panel.title)}"><header class="panel-head"><a class="panel-id" href="#${escape(panel.id)}" aria-label="${escape(panel.title)}">${index+1}</a><h2>${inline(panel.title,panel.id)}</h2></header>${body}</section>`;
+  })).join('');
+  for(const source of document.sources)if(!citations.has(source.id))citations.set(source.id,citations.size+1);
+  const sourceList=[...citations].map(([id,number])=>{
+    const source=sources[id] || document.sources.find(source=>source.id===id);
+    const location=source?.path ? `<code>${escape(source.path)}${source.lines?':'+escape(source.lines.join('–')):''}${source.revision?' @ '+escape(source.revision):''}</code>` : '';
+    const title=source?.url ? `<a href="${escape(source.url)}" target="_blank" rel="noopener noreferrer">${escape(source.title)}</a>` : escape(source?.title || id);
+    return `<li id="source-${escape(id)}" value="${number}">${title}${location}</li>`;
+  }).join('');
+  for (const [id,diagram] of Object.entries(diagrams)) { if (diagram.sha256 && diagram.sha256 !== hash(diagram.html)) throw new Error(`Native child hash mismatch: ${id}`); if (diagram.bytes !== undefined && diagram.bytes !== Buffer.byteLength(diagram.html)) throw new Error(`Native child byte count mismatch: ${id}`); }
+  const children = Object.fromEntries(Object.entries(diagrams).map(([id,diagram]) => [id,{diagramType:diagram.diagramType,html:diagram.html,sha256:diagram.sha256 || hash(diagram.html),bytes:diagram.bytes ?? Buffer.byteLength(diagram.html),semantic:diagram.semantic,checks:portableChecks(diagram.checks),composition:diagram.composition,specSha256:diagram.specSha256}]));
+  // What a reader can check, stated next to the maker's mark.
+  const pinned = Object.values(sources).find(source=>source?.path && source.revision)?.revision;
+  const facts = [words.facts.panels(document.panels.length),Object.keys(diagrams).length && words.facts.diagrams(Object.keys(diagrams).length),citations.size && words.facts.sources(citations.size),pinned && words.facts.pinned(String(pinned).slice(0,7))].filter(Boolean);
+  const colophon = `<div class="colophon"><a class="colophon-brand" href="https://github.com/tt-a1i/archify" target="_blank" rel="noopener noreferrer"><span class="colophon-mark" aria-hidden="true">${mark}</span><span class="colophon-words"><span class="colophon-name">Archify</span><span class="colophon-tagline">${words.tagline}</span></span></a><p class="colophon-facts">${facts.map(fact=>`<span>${escape(fact)}</span>`).join('')}</p></div>`;
+  const footnotesHtml = footnotes.length ? `<section class="typical-footnotes"><h2>${english?'Typical value notes':'典型值说明'}</h2><ol>${footnotes.map(note=>`<li id="${escape(note.id)}">${escape(note.label)}: ${escape(note.text)}</li>`).join('')}</ol></section>` : '';
+  const manifest = {version:1,artifactId:document.meta.id,revision,documentSha256:hash(JSON.stringify(document)),sourceSha256,dependencies:[...(preparedSources.dependencies || []),...(preparedDiagrams.dependencies || [])].map(({contentBase64,...entry})=>entry),children:Object.fromEntries(Object.entries(children).map(([id,child])=>[id,{sha256:child.sha256,bytes:child.bytes,diagramType:child.diagramType,checks:child.checks,composition:child.composition,specSha256:child.specSha256}])),sources:Object.fromEntries(Object.entries(sources).map(([id,source])=>[id,Object.fromEntries(Object.entries(source || {}).filter(([key])=>key !== 'text'))])),assets:Object.fromEntries(Object.entries(assets).map(([id,asset])=>[id,{sha256:asset.sha256,bytes:asset.bytes,mime:asset.mime}])),diagnostics};
+  const bundle = preparedBundle || {schemaVersion:1,kind:'archify-explainer-prepared',sourceText,sourceMap,sourcePath,document,format:'json',diagnostics,preparedSources,preparedDiagrams,dependencies:[...(preparedSources.dependencies || []),...(preparedDiagrams.dependencies || [])],source:{sha256:sourceSha256,bytes:Buffer.byteLength(sourceText)}};
+  if (!preparedBundle) bundle.digest = hash(JSON.stringify(bundle));
+  if (bundle.sourceText !== sourceText || JSON.stringify(bundle.document) !== JSON.stringify(document)) throw new Error('Prepared bundle differs from rendered source or canonical document.');
+  const page = portableBundle(bundle, pageDirectory || bundle.baseDir || (bundle.sourcePath && path.dirname(bundle.sourcePath)));
+  manifest.diagnostics = page.diagnostics;
+  manifest.dependencies = (page.dependencies || []).map(({contentBase64,...entry})=>entry);
+  return `<!doctype html>\n<html lang="${escape(locale)}" data-style="${escape(document.meta.style || 'clean')}" data-archify-artifact="explainer" data-artifact="${escape(document.meta.id)}" data-revision="${revision}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light dark"><meta name="description" content="${escape(document.answer.summary)}"><title>${escape(document.meta.title)} · Archify</title><link rel="icon" type="image/svg+xml" href="${favicon}"><style>${css}</style>${softwareNoticesHtml}</head><body><a class="skip-link" href="#board">${english?'Skip to content':'跳至正文'}</a><div class="shell"><header class="masthead"><h1>${escape(document.meta.title)}</h1><div class="tools interactive"><div class="theme-controls" role="group" aria-label="${english?'Theme':'主题'}">${['auto','light','dark'].map(theme=>`<button type="button" data-theme-choice="${theme}" aria-pressed="${theme === 'auto'}">${words[theme]}</button>`).join('')}</div><div class="tool-menu style-menu"><button type="button" class="tool-button" data-style-toggle aria-haspopup="menu" aria-expanded="false" aria-label="${words.style}"><span class="style-swatch" data-swatch="${escape(document.meta.style || 'clean')}"></span><span data-style-label>${words.styles[document.meta.style || 'clean']}</span>${icons.chevron}</button><div class="menu-options style-options" role="menu" aria-label="${words.style}" hidden>${['clean','editorial','product','swiss'].map(style=>`<button type="button" role="menuitemradio" aria-checked="${style === (document.meta.style || 'clean')}" data-style-choice="${style}" tabindex="-1"><span class="style-swatch" data-swatch="${style}"></span><span>${words.styles[style]}</span>${icons.check}</button>`).join('')}</div></div><div class="tool-menu export-menu"><button type="button" class="tool-button" data-export-toggle aria-haspopup="menu" aria-expanded="false">${icons.export}<span>${words.export}</span>${icons.chevron}</button><div class="menu-options" role="menu" aria-label="${words.export}" hidden><p class="menu-label" role="presentation">${words.image}</p>${[['png','PNG'],['webp','WebP'],['jpeg','JPG']].map(([format,label],index)=>`<button type="button" role="menuitem" tabindex="-1" data-export-image="${format}" aria-label="${words.image} ${label}">${icons.image}<span>${label}</span><small>${words.imageHints[index]}</small></button>`).join('')}<hr role="separator"><button type="button" role="menuitem" tabindex="-1" data-print>${icons.print}<span>${words.print}</span></button></div></div></div></header><main id="board"><div class="board">${panels}</div></main><footer>${footnotesHtml}<section class="sources"><h2>${words.sources}</h2><ol>${sourceList}</ol></section>${colophon}</footer></div><dialog class="viewer-dialog" id="diagram-dialog" aria-labelledby="diagram-dialog-title"><header><h2 id="diagram-dialog-title"></h2><button type="button" class="viewer-close" data-close-diagram>${icons.close}<span>${words.close}</span><kbd>Esc</kbd></button></header><p class="dialog-loading" role="status">${words.loading}</p></dialog><div id="toast" role="status" aria-live="polite"></div><script type="application/json" id="archify-explainer-prepared">${json(packPageBundle(page))}</script><script type="application/json" id="explainer-manifest">${json(manifest)}</script><script type="application/json" id="explainer-reader-words">${json(words)}</script><script>${js}</script></body></html>`;
+}
+
+// Native check filenames refer to disposable build files, not reader resources.
+function portableChecks(checks) {
+  if (!checks?.check) return checks;
+  const {file, ...check} = checks.check;
+  return {...checks,check};
+}
+
+// A page is shared, so the draft it carries names local files relative to the page, never by absolute
+// path: the reader sees no author directories. `patch explainer` resolves them against the page again.
+function portableBundle(bundle, directory) {
+  if (!directory) return bundle;
+  const local = value => {
+    if (typeof value !== 'string') return value;
+    const paths = path.win32.isAbsolute(value) && !path.posix.isAbsolute(value) ? path.win32 : path;
+    if (!paths.isAbsolute(value)) return value;
+    const relative = paths.relative(directory, value);
+    // Different Windows volumes have no relative path. Frozen content stays usable;
+    // a missing origin must not be mistaken for the output directory during patching.
+    return paths.isAbsolute(relative) ? null : relative || '.';
+  };
+  const subject = entry => entry?.subject ? {...entry,subject:{...entry.subject,...('input' in entry.subject ? {input:local(entry.subject.input)} : {}),...('output' in entry.subject ? {output:local(entry.subject.output)} : {})}} : entry;
+  const page = {...bundle,sourcePath:local(bundle.sourcePath),...('inputPath' in bundle ? {inputPath:local(bundle.inputPath)} : {}),...('baseDir' in bundle ? {baseDir:local(bundle.baseDir)} : {}),
+    preparedDiagrams:{...bundle.preparedDiagrams,diagrams:Object.fromEntries(Object.entries(bundle.preparedDiagrams?.diagrams || {}).map(([id,diagram])=>[id,{...diagram,checks:portableChecks(diagram.checks)}]))},
+    dependencies:(bundle.dependencies || []).map(entry=>entry.path ? {...entry,path:local(entry.path)} : entry),diagnostics:(bundle.diagnostics || []).map(subject)};
+  page.digest = hash(JSON.stringify({...page,digest:undefined}));
+  return page;
+}
+
+// Prefix native SVG identifiers in the preview only. Original native HTML is frozen above.
+function staticSvg(svg, id) {
+  const prefix = previewPrefix(id) + '-';
+  // Only element IDs are prefixed; data-node-id and data-edge-id stay semantic for step links.
+  const ids = new Map([...svg.matchAll(/(?<![\w-])id="([^"]+)"/g)].map(match => [match[1],prefix + match[1]]));
+  return svg.replace(/(?<![\w-])id="([^"]+)"/g,(_,value)=>`id="${escape(ids.get(value))}"`)
+    .replace(/url\(#([^\)]+)\)/g,(_,value)=>`url(#${ids.get(value) || value})`)
+    .replace(/\b(href|xlink:href)="#([^"]+)"/g,(_,attr,value)=>`${attr}="#${escape(ids.get(value) || value)}"`)
+    .replace(/\b(aria-labelledby|aria-describedby)="([^"]+)"/g,(_,attr,value)=>`${attr}="${escape(value.split(/\s+/).map(id=>ids.get(id) || id).join(' '))}"`)
+    .replace(/\s(?:tabindex="[^"]*"|role="button"|aria-pressed="[^"]*")/g,'');
+}
+
+// A scope written as "a · b · c" reads as separate conditions; anything else stays a sentence.
+function scopeParts(scope) { return scope.split(/\s+·\s+/).map(part=>part.trim()).filter(Boolean); }
+
+// Split a selector list on its top-level commas; commas inside :is(), :not() or attribute values stay.
+function selectorList(selector) {
+  const parts = []; let depth = 0, quote = '', start = 0;
+  for (let i = 0; i < selector.length; i++) {
+    const c = selector[i];
+    if (quote) { if (c === quote && selector[i-1] !== '\\') quote = ''; }
+    else if (c === '"' || c === "'") quote = c;
+    else if (c === '(' || c === '[') depth++;
+    else if (c === ')' || c === ']') depth--;
+    else if (c === ',' && !depth) { parts.push(selector.slice(start,i)); start = i + 1; }
+  }
+  return [...parts, selector.slice(start)];
+}
+const nativeStyles = html => [...String(html).matchAll(/<style\b[^>]*>[\s\S]*?<\/style>/g)].map(match => match[0]).join('\n');
+function previewPrefix(id) { return `preview-${id.replace(/[^A-Za-z0-9_-]/g,'-')}`; }
+
+// Native CSS is scoped to its static preview. No native body/chrome layout enters the reader.
+// The preview sets text in page fonts and shows only the SVG, so font faces and rules that name a
+// class absent from the SVG (Viewer chrome, toolbars, cards) are dropped.
+function scopeNativeCss(styles, scope, prefix, svg = '') {
+  const css = styles.replace(/<style[^>]*>/gi,'').replace(/<\/style>/gi,'').replace(/\/\*[\s\S]*?\*\//g,'');
+  const present = new Set(svg ? [...svg.matchAll(/\bclass="([^"]*)"/g)].flatMap(match => match[1].split(/\s+/)) : []);
+  const applies = value => !svg || [...value.replace(/:not\([^)]*\)/g,'').matchAll(/\.([A-Za-z_][\w-]*)/g)].every(match => present.has(match[1]));
+  const defaults = []; const systemDark = []; const systemLight = [];
+  function rules(input, collectThemes = true) {
+    let result = ''; let cursor = 0;
+    while (cursor < input.length) {
+      const opening = input.indexOf('{',cursor); if(opening < 0) break;
+      const selector = input.slice(cursor,opening).trim(); let depth = 1; let end = opening + 1; let quote = '';
+      for(; end < input.length && depth; end++) { const c = input[end]; if(quote) {if(c === quote && input[end-1] !== '\\') quote = '';} else if(c === '\"' || c === "'") quote = c; else if(c === '{') depth++; else if(c === '}') depth--; }
+      const body = input.slice(opening + 1,end-1).replace(/url\(#([^\)]+)\)/g,(_,id)=>`url(#${prefix}${id})`); cursor = end;
+      if(selector.startsWith('@media') || selector.startsWith('@supports') || selector.startsWith('@layer')) { result += `${selector}{${rules(body,false)}}`; continue; }
+      if(selector.startsWith('@')) continue;
+      const selectors = selectorList(selector).filter(value=>!/(^|[\s>+~])body(?:\b|$)/.test(value) && applies(value)).map(value=>{
+        let next = value.trim().replace(/#([A-Za-z][\w-]*)/g,(_,id)=>'#' + prefix + id);
+        next = next.replace(/^:root|^html\b/,scope);
+        if (next.startsWith('[data-theme=') || next.startsWith('[data-preset=')) next = scope + next;
+        return next.startsWith(scope) ? next : `${scope} ${next}`;
+      });
+      const rootSelectors = selectorList(selector).map(value=>value.trim());
+      if (collectThemes && rootSelectors.includes(':root')) defaults.push(body);
+      if (collectThemes && rootSelectors.some(value=>/^(?:\:root)?\[data-theme=[\"']?dark[\"']?\]$/.test(value))) systemDark.push(body);
+      if (collectThemes && rootSelectors.some(value=>/^(?:\:root)?\[data-theme=[\"']?light[\"']?\]$/.test(value))) systemLight.push(body);
+      if(selectors.length) result += `${selectors.join(',')}{${body}}`;
+    }
+    return result;
+  }
+  const scoped = rules(css);
+  const light = systemLight.length ? systemLight : defaults;
+  return scoped + (systemLight.length ? `${scope}:not([data-theme]){${systemLight.join(';')}}` : '') + (systemDark.length ? `@media(prefers-color-scheme:dark){${scope}:not([data-theme]){${systemDark.join(';')}}}` : '') + (light.length ? `@media print{${scope},${scope}[data-theme],${scope}:not([data-theme]){${light.join(';')}}}` : '');
+}

package/ai/skills/stacks-technical-diagrams/explainer/revision.mjs

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto';
+const hash = text => createHash('sha256').update(text).digest('hex');
+
+/** Stable authored-content identity; excludes filesystem relocation and outer reader presentation. */
+export function computeExplainerRevision({document,sourceText=JSON.stringify(document),preparedSources={},preparedDiagrams={},dependencies}) {
+  const sourceSha256 = hash(sourceText);
+  const sources = preparedSources.sources || preparedSources;
+  const assets = preparedSources.assets || {};
+  const diagrams = preparedDiagrams.diagrams || preparedDiagrams;
+  const stable = value => Array.isArray(value) ? value.map(stable) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).filter(([,entry])=>entry !== undefined).sort(([a],[b])=>a < b ? -1 : a > b ? 1 : 0).map(([key,entry])=>[key,stable(entry)])) : value;
+  const ordered = entries => entries.map(stable).sort((a,b)=>JSON.stringify(a) < JSON.stringify(b) ? -1 : JSON.stringify(a) > JSON.stringify(b) ? 1 : 0);
+  const resourceIdentity = {
+    version:1,sourceSha256,documentSha256:hash(JSON.stringify(stable(document))),
+    dependencies:ordered((dependencies || [...(preparedSources.dependencies || []),...(preparedDiagrams.dependencies || [])]).map(({kind,id,sha256,bytes})=>({kind,id,sha256,bytes}))),
+    sources:Object.fromEntries(Object.entries(sources).map(([id,source])=>[id,{title:source.title,url:source.url,path:source.path,lines:source.lines,revision:source.revision,textSha256:typeof source.text === 'string' ? hash(source.text) : undefined}])),
+    children:Object.fromEntries(Object.entries(diagrams).map(([id,child])=>[id,{htmlSha256:hash(child.html),specSha256:hash(JSON.stringify(stable(child.spec || {})))}])),
+    assets:Object.fromEntries(Object.entries(assets).map(([id,asset])=>[id,{sha256:asset.sha256,dataSha256:hash(asset.dataUrl || ''),mime:asset.mime,bytes:asset.bytes}]))
+  };
+  return hash(JSON.stringify(stable(resourceIdentity)));
+}

package/ai/skills/stacks-technical-diagrams/explainer/sources.mjs

@@ -0,0 +1,318 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { throwDiagnosticError } from '../renderers/shared/diagnostics.mjs';
+import { verifyRepositoryEvidence } from '../renderers/shared/repository-evidence.mjs';
+import { parseRepositoryRemote } from '../renderers/shared/repository-location.mjs';
+import { chartFromData, compileExplainerChart } from './charts.mjs';
+
+const MAX_CODE_BYTES = 16 * 1024 * 1024;
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+const MAX_DATA_BYTES = 2 * 1024 * 1024;
+const MAX_ASSET_BYTES = 32 * 1024 * 1024;
+const SECRET_NAME = /^(?:\.env(?:\..*)?|\.npmrc|\.netrc|\.pypirc|\.(?:ssh|aws|gnupg|kube)|(?:id_(?:rsa|dsa|ecdsa|ed25519))(?:\..*)?|(?:credentials?|secrets?)(?:[._-].*)?|.*\.(?:pem|key|p12|pfx|keystore))$/i;
+const SECRET_CONTENT = /-----BEGIN (?:[A-Z ]*PRIVATE KEY|PGP PRIVATE KEY BLOCK)-----|\b(?:AKIA|ASIA)[A-Z0-9]{16}\b|\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-(?:proj-)?[A-Za-z0-9_-]{20,})\b/i;
+const CREDENTIAL_ASSIGNMENT = /\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret)\b["']?[ \t]*[:=][ \t]*([^\r\n]*)/gi;
+const ENVIRONMENT_REFERENCE = /^(?:\$(?:[A-Za-z_][\w]*|\{[A-Za-z_][\w]*\})|(?:process\.env|os\.environ|env)(?:\.[A-Za-z_][\w]*|\[['"][A-Za-z_][\w]*['"]\])|(?:os\.getenv|getenv|env)\(\s*['"][A-Za-z_][\w]*['"]\s*\))$/;
+
+export function containsExplainerSecret(text, sourcePath = '') {
+  if (SECRET_CONTENT.test(text)) return true;
+  const configuration = /\.(?:ya?ml|toml|ini|conf|config|properties|cfg|sh|bash)$/i.test(sourcePath);
+  for (const match of text.matchAll(CREDENTIAL_ASSIGNMENT)) {
+    const value = match[1].trim().replace(/\s+(?:#|\/\/).*$/, '').replace(/[;,]\s*$/, '').trim();
+    if (!value || /^(?:null|nil|none|undefined|~)$/i.test(value) || ENVIRONMENT_REFERENCE.test(value)) continue;
+    const quoted = value.match(/^(['"`])([\s\S]*?)\1/);
+    if (quoted) {
+      if (quoted[2].length >= 4 && !ENVIRONMENT_REFERENCE.test(quoted[2])) return true;
+    } else if (configuration) {
+      // Configuration scalars are values, whereas an unquoted JS/Python identifier can be a code reference.
+      return true;
+    }
+  }
+  return false;
+}
+
+function location(document, pointer, component) {
+  const map = document?.sourceMap;
+  const entry = map instanceof Map ? map.get(pointer) : map?.[pointer];
+  return { path: pointer, component, ...(document?.sourcePath ? { input: document.sourcePath } : {}), line: Number.isInteger(entry?.line) && entry.line > 0 ? entry.line : 1,
+    ...(Number.isInteger(entry?.column) ? { column: entry.column } : {}) };
+}
+
+function fail(document, pointer, component, reason, message, fix, example) {
+  const examples = {
+    source: '{"id":"router","title":"Router","path":"src/router.js","lines":[1,3]}',
+    code: '{"id":"code","type":"code","source":"router"}',
+    image: '{"id":"image","type":"image","path":"images/figure.png","alt":"Figure"}',
+  };
+  throwDiagnosticError(message, [{ code: `explainer/${reason}`, severity: 'error', message,
+    subject: location(document, pointer, component),
+    evidence: { reason, example: example || examples[component] || examples.source }, supportedFixes: [fix] }]);
+}
+
+function safePath(document, value, pointer, component) {
+  if (typeof value !== 'string' || !value || /^[\/\\]/.test(value)
+      || /[\\:\u0000-\u001f\u007f?#]/.test(value)
+      || value.split('/').some(part => !part || part === '.' || part === '..' || part.toLowerCase() === '.git')) {
+    fail(document, pointer, component, 'source-path', 'Resource paths must stay inside their root directory.',
+      'Use a relative path with forward slashes and no dot segments.', 'src/router.js');
+  }
+  if (value.split('/').some(part => SECRET_NAME.test(part))) {
+    fail(document, pointer, component, 'secret-path', 'This resource belongs to a sensitive file class.',
+      'Reference a public source file or remove this resource.');
+  }
+  return value;
+}
+
+function gitBytes(document, repoRoot, args, pointer, limit = MAX_CODE_BYTES) {
+  const result = spawnSync('git', ['--no-replace-objects', '-C', repoRoot, ...args], { maxBuffer: limit });
+  if (result.error || result.status !== 0 || !Buffer.isBuffer(result.stdout) || result.stdout.length > limit) {
+    fail(document, pointer, 'source', 'source-read', 'The pinned repository resource could not be read within the size limit.',
+      'Use an available, readable source file smaller than 16 MiB.');
+  }
+  return result.stdout;
+}
+
+function deriveRepository(document, repoRoot) {
+  if (!repoRoot) fail(document, '/meta/repository', 'source', 'repository-root', 'Repository sources require a local repository.',
+    'Pass --repo-root with the matching local Git checkout.', '--repo-root /absolute/path/to/repository');
+  const raw = gitBytes(document, repoRoot, ['remote', 'get-url', 'origin'], '/meta/repository').toString('utf8').trim();
+  const remote = parseRepositoryRemote(raw);
+  if (!remote) fail(document, '/meta/repository', 'source', 'repository-origin', 'The repository origin cannot be represented safely.',
+    'Configure a credential-free repository origin without query or fragment.');
+  const revision = gitBytes(document, repoRoot, ['rev-parse', '--verify', 'HEAD^{commit}'], '/meta/repository').toString('utf8').trim();
+  return { url: remote.url, revision,
+    ...(remote.provider && remote.protocol === 'https:' && remote.endpoint === 'standard' ? {} : { link_mode: 'local-only' }) };
+}
+
+function resources(document) {
+  const result = [];
+  for (const [panelIndex, panel] of (document.panels || []).entries()) {
+    for (const [index, block] of (panel.blocks || []).entries()) result.push({ block, pointer: `/panels/${panelIndex}/blocks/${index}` });
+  }
+  return result;
+}
+
+function digest(bytes) {
+  return { sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length,
+    contentBase64: bytes.toString('base64') };
+}
+
+function imageMime(bytes) {
+  if (bytes.length >= 24 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+      && bytes.toString('ascii', 12, 16) === 'IHDR') return 'image/png';
+  if (bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return 'image/jpeg';
+  if (bytes.length >= 13 && /^(GIF87a|GIF89a)$/.test(bytes.toString('ascii', 0, 6))) return 'image/gif';
+  if (bytes.length >= 16 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') return 'image/webp';
+  return null;
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+
+function readImage(document, baseDir, authoredPath, pointer) {
+  if (!baseDir) fail(document, pointer, 'image', 'asset-root', 'Local images require an input directory.',
+    'Provide the original input directory as baseDir.');
+  const relative = safePath(document, authoredPath, `${pointer}/path`, 'image');
+  const expected = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[path.extname(relative).toLowerCase()];
+  if (!expected) fail(document, `${pointer}/path`, 'image', 'asset-format', 'Only local PNG, JPEG, WebP and GIF images are supported.',
+    'Use a PNG, JPEG, WebP or GIF image.');
+  const bytes = readContained(document, baseDir, relative, pointer, 'image', MAX_IMAGE_BYTES, '8 MiB');
+  const mime = imageMime(bytes);
+  if (mime !== expected) fail(document, pointer, 'image', 'asset-format', 'The image bytes do not match a supported image format.',
+    'Use a correctly encoded image whose extension matches its bytes.');
+  return { path: relative, mime, ...digest(bytes), dataUrl: `data:${mime};base64,${bytes.toString('base64')}` };
+}
+
+// Read a regular file inside baseDir without following links, and confirm it did not change meanwhile.
+function readContained(document, baseDir, relative, pointer, component, limit, limitText) {
+  const noun = component === 'image' ? 'image' : 'data file', Noun = noun[0].toUpperCase() + noun.slice(1);
+  let fd;
+  try {
+    const root = fs.realpathSync(baseDir);
+    const ancestors = [[root, fs.lstatSync(root)]];
+    let candidate = root;
+    for (const part of relative.split('/')) {
+      candidate = path.join(candidate, part);
+      const stat = fs.lstatSync(candidate);
+      if (stat.isSymbolicLink()) fail(document, `${pointer}/path`, component, 'asset-symlink', `${Noun} paths may not traverse symbolic links.`,
+        `Copy the ${noun} into the input directory as a regular file.`);
+      ancestors.push([candidate, stat]);
+    }
+    if (!ancestors.at(-1)[1].isFile()) fail(document, pointer, component, 'asset-file', `The ${noun} must be a regular file.`, `Use a regular ${noun}.`);
+    fd = fs.openSync(candidate, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const before = fs.fstatSync(fd);
+    if (!sameFile(before, ancestors.at(-1)[1]) || before.size > limit) fail(document, pointer, component, 'asset-size',
+      `The ${noun} changed or exceeds the ${limitText} size limit.`, `Use a stable ${noun} smaller than ${limitText}.`);
+    const bytes = Buffer.alloc(before.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (!count) break;
+      offset += count;
+    }
+    const unchanged = offset === bytes.length && sameFile(before, fs.fstatSync(fd))
+      && ancestors.every(([file, stat]) => { const current = fs.lstatSync(file); return !current.isSymbolicLink() && sameFile(current, stat); });
+    if (!unchanged) fail(document, pointer, component, 'asset-changed', `The ${noun} path or bytes changed while being frozen.`,
+      `Finish ${noun} updates before rendering again.`);
+    return bytes;
+  } catch (error) {
+    if (error.archifyDiagnostics) throw error;
+    fail(document, pointer, component, 'asset-read', `The ${noun} cannot be read safely inside the input directory.`,
+      `Use an accessible regular ${noun} inside the input directory.`);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+/** Prepare source locations and freeze code/image bytes; never mutate author input. */
+export async function resolveExplainerSources(document, { repoRoot, baseDir, sourceMap, sourcePath } = {}) {
+  const context = { sourceMap, sourcePath };
+  const sources = Object.create(null);
+  const assets = Object.create(null);
+  const dependencies = [];
+  const entries = document.sources || [];
+  const blocks = resources(document);
+  const codeIds = new Set();
+  const blockIds = new Set();
+  for (const { block, pointer } of blocks) {
+    if (!['code', 'image'].includes(block.type)) continue;
+    if (typeof block.id !== 'string' || !block.id || blockIds.has(block.id)) fail(context, pointer, block.type, 'resource-id',
+      'Resource blocks require a unique stable id.', 'Give each code or image block its own id.');
+    blockIds.add(block.id);
+    if (block.type === 'code') codeIds.add(block.source);
+  }
+  const repositorySources = [];
+  for (const [index, entry] of entries.entries()) {
+    const pointer = `/sources/${index}`;
+    if (typeof entry.id !== 'string' || !entry.id || Object.hasOwn(sources, entry.id)) fail(context, pointer, 'source', 'source-id',
+      'Sources require unique ids.', 'Give each source a unique id.');
+    sources[entry.id] = null;
+    if (entry.path) {
+      safePath(context, entry.path, `${pointer}/path`, 'source');
+      if (entry.lines && (!Array.isArray(entry.lines) || entry.lines.length !== 2 || !entry.lines.every(Number.isSafeInteger)
+          || entry.lines[0] < 1 || entry.lines[1] < entry.lines[0])) fail(context, `${pointer}/lines`, 'source', 'source-lines',
+        'Repository line ranges must be ordered and positive.', 'Use lines: [start, end].', '[1, 3]');
+    }
+    if (entry.url) {
+      let url; try { url = new URL(entry.url); } catch {}
+      if (!url || !['https:', 'http:'].includes(url.protocol) || url.username || url.password || /[\u0000-\u0020\u007f]/.test(entry.url)) fail(context, `${pointer}/url`, 'source', 'source-url',
+        'Source links require credential-free HTTP(S) URLs.', 'Use https://example.com/article.');
+    }
+    sources[entry.id] = Object.freeze({id:entry.id,title:entry.title,...(entry.url?{url:entry.url}:{}),...(entry.path?{path:entry.path}:{}),...(entry.lines?{lines:[...entry.lines]}:{}),...(entry.revision?{revision:entry.revision}:{})});
+    if (codeIds.has(entry.id)) {
+      if (!entry.path || !entry.lines) fail(context,pointer,'code','code-source','Code requires a Git file and line range.','Add path and lines to the source.');
+      repositorySources.push({entry,index});
+    }
+  }
+
+  let repository = null;
+  if (repositorySources.length) {
+    const metadata = document.meta?.repository ? { ...document.meta.repository } : deriveRepository(context, repoRoot);
+    for (const { entry, index } of repositorySources) {
+      if (entry.revision !== undefined && String(entry.revision).toLowerCase() !== String(metadata.revision).toLowerCase()) fail(context, `/sources/${index}/revision`, 'source', 'source-revision',
+        'All repository sources must use the document’s pinned revision.', 'Use the document repository revision or omit the source revision.');
+    }
+    let verified;
+    try {
+      verified = verifyRepositoryEvidence('architecture', { meta: { repository: metadata }, components: repositorySources.map(({ entry }) => ({
+        id: entry.id, sources: [{ path: entry.path, line: entry.lines[0], end_line: entry.lines[1] }],
+      })) }, repoRoot);
+    } catch (error) {
+      const original = error.archifyDiagnostics?.[0];
+      const match = original?.subject?.path?.match(/^\/components\/(\d+)/);
+      const index = match ? repositorySources[Number(match[1])]?.index : undefined;
+      const examples = {
+        'repository-evidence/root-required': '--repo-root /absolute/path/to/repository',
+        'repository-evidence/root-not-top-level': '--repo-root /absolute/path/to/repository',
+        'repository-evidence/root-unreadable': '--repo-root /absolute/path/to/repository',
+        'repository-evidence/revision-invalid': 'git rev-parse HEAD',
+        'repository-evidence/revision-unavailable': 'git rev-parse HEAD',
+        'repository-evidence/url-invalid': '{"url":"https://github.com/owner/repository"}',
+        'repository-evidence/origin-mismatch': 'git remote get-url origin',
+        'repository-evidence/line-out-of-range': '{"path":"src/router.js","lines":[1,3]}',
+        'repository-evidence/file-missing': '{"path":"src/router.js","lines":[1,3]}',
+      };
+      fail(context, index === undefined ? '/meta/repository' : `/sources/${index}`, 'source', 'repository-location',
+        'The declared repository location could not be verified.', 'Correct the repository origin, pinned commit, file path and line range.',
+        examples[original?.code]);
+    }
+    repository = Object.freeze({ ...verified.repository });
+    for (const { entry, index } of repositorySources) {
+      const reference = verified.nodes[entry.id][0];
+      const result = { id: entry.id, ...(entry.title === undefined ? {} : { title: entry.title }),
+        revision: repository.revision, path: reference.path, lines: Object.freeze([...entry.lines]),
+        ...(reference.href ? { url: reference.href } : {}) };
+      if (codeIds.has(entry.id)) {
+        const bytes = gitBytes(context, repoRoot, ['show', `${repository.revision}:${entry.path}`], `/sources/${index}`);
+        let text;
+        try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch {
+          fail(context, `/sources/${index}`, 'code', 'source-encoding', 'Code sources must contain UTF-8 text.', 'Use a UTF-8 text source file.');
+        }
+        if (text.includes('\0') || containsExplainerSecret(text, entry.path)) fail(context, `/sources/${index}`, 'code', 'secret-content',
+          'This source cannot be displayed because it contains sensitive or binary content.', 'Use a public source file without secrets.');
+        result.text = text.split(/\r\n|\n|\r/).slice(entry.lines[0] - 1, entry.lines[1]).join('\n');
+        const frozen = digest(bytes);
+        Object.assign(result, { sha256: frozen.sha256, bytes: frozen.bytes });
+        dependencies.push(Object.freeze({ kind: 'repository', id: entry.id, path: entry.path, revision: repository.revision, ...frozen }));
+      }
+      sources[entry.id] = Object.freeze(result);
+    }
+  }
+  // A cited repository file also carries its excerpt when the repository is at hand, so a reader can
+  // check the claim in place. A citation that cannot be verified or read stays a plain reference.
+  const cited = document.sources.map((entry,index)=>({entry,index})).filter(({entry})=>entry.path && entry.lines && !codeIds.has(entry.id));
+  if (cited.length && repoRoot) {
+    let metadata = null;
+    try { metadata = document.meta?.repository ? { ...document.meta.repository } : deriveRepository(context, repoRoot); } catch {}
+    for (const { entry, index } of metadata ? cited : []) {
+      try {
+        const verified = verifyRepositoryEvidence('architecture', { meta: { repository: metadata }, components: [{ id: entry.id, sources: [{ path: entry.path, line: entry.lines[0], end_line: entry.lines[1] }] }] }, repoRoot);
+        const reference = verified.nodes[entry.id][0];
+        const bytes = gitBytes(context, repoRoot, ['show', `${verified.repository.revision}:${entry.path}`], `/sources/${index}`);
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        if (text.includes('\0') || containsExplainerSecret(text, entry.path)) continue;
+        const frozen = digest(bytes);
+        sources[entry.id] = Object.freeze({ id: entry.id, ...(entry.title === undefined ? {} : { title: entry.title }), revision: verified.repository.revision, path: reference.path,
+          lines: Object.freeze([...entry.lines]), ...(reference.href ? { url: reference.href } : {}), text: text.split(/\r\n|\n|\r/).slice(entry.lines[0] - 1, entry.lines[1]).join('\n'), sha256: frozen.sha256, bytes: frozen.bytes });
+        dependencies.push(Object.freeze({ kind: 'repository', id: entry.id, path: entry.path, revision: verified.repository.revision, ...frozen }));
+        repository ||= Object.freeze({ ...verified.repository });
+      } catch {}
+    }
+  }
+  for (const { block, pointer } of blocks) {
+    if (block.type === 'code') {
+      const source = sources[block.source];
+      if (!source || !source.path || typeof source.text !== 'string') fail(context, `${pointer}/source`, 'code', 'code-source',
+        'Code blocks require a Git code excerpt.', 'Reference a repository source id with a valid line range.');
+    }
+  }
+  let assetBytes = 0;
+  for (const { block, pointer } of blocks) {
+    if (block.type !== 'image') continue;
+    const asset = readImage(context, baseDir, block.path, pointer);
+    assetBytes += asset.bytes;
+    if (assetBytes > MAX_ASSET_BYTES) fail(context, pointer, 'image', 'asset-budget', 'Embedded images exceed the 32 MiB document limit.',
+      'Reduce the total embedded image bytes below 32 MiB.');
+    assets[block.id] = Object.freeze({ id: block.id, alt: block.alt, ...asset });
+    dependencies.push(Object.freeze({ kind: 'image', id: block.id, path: asset.path, sha256: asset.sha256, bytes: asset.bytes, contentBase64: asset.contentBase64 }));
+  }
+  // A data chart reads its CSV or JSON once, freezes the bytes and keeps the chart text built from them.
+  const charts = Object.create(null);
+  for (const { block, pointer } of blocks) {
+    if (block.type !== 'chart' || !block.data) continue;
+    if (!baseDir) fail(context, pointer, 'chart', 'asset-root', 'A data chart requires an input directory.', 'Run finalize on the draft file next to its data.');
+    const relative = safePath(context, block.data.path, `${pointer}/data/path`, 'chart');
+    if (!/\.(?:csv|json)$/iu.test(relative)) fail(context, `${pointer}/data/path`, 'chart', 'chart-data-format', 'Chart data is a .csv or .json file.', 'data=latency.csv');
+    const bytes = readContained(context, baseDir, relative, pointer, 'chart', MAX_DATA_BYTES, '2 MiB');
+    let built;
+    try { built = chartFromData(bytes, relative, block.data); } catch { built = { error: 'The data file is not UTF-8 text.' }; }
+    const chart = built.error ? built : compileExplainerChart(built.text);
+    if (chart.error) fail(context, pointer, 'chart', 'chart-data', chart.error, '@chart type=bar data=latency.csv x=day y=p50,p99');
+    charts[block.id] = built.text;
+    dependencies.push(Object.freeze({ kind: 'data', id: block.id, path: relative, ...digest(bytes) }));
+  }
+  return { sources: Object.freeze(sources), assets: Object.freeze(assets), charts: Object.freeze(charts), dependencies: Object.freeze(dependencies), repository };
+}