Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Link explainer text to diagrams, add walk-throughs and follow-up questions

tt-a1iee76204b132a
diff --git a/archify/explainer/reader.css b/archify/explainer/reader.css
index 34ddc68f..43ed3668 100644
--- a/archify/explainer/reader.css
+++ b/archify/explainer/reader.css
@@ -138,6 +138,20 @@ meter{width:100%;height:8px;accent-color:var(--accent)}
.steps li:not(:last-child)::after{content:"";position:absolute;left:11px;top:25px;bottom:3px;width:1.5px;background:var(--rule)}
.steps b{display:block;font-size:14.5px;line-height:1.6;color:var(--ink)}
.steps p{font-size:13.5px;line-height:1.65;color:var(--muted);margin-top:1px}
+/* Text linked to a diagram node, and the step-through controls */
+.term{text-decoration:underline dotted color-mix(in srgb,var(--accent) 55%,transparent);text-underline-offset:3px;text-decoration-thickness:1.5px;border-radius:3px;transition:background .15s}
+.term:hover,.term.term-lit{background:var(--accent-soft);color:var(--accent-ink);text-decoration-color:var(--accent)}
+.walk-start{margin-bottom:10px;font-size:12px;color:var(--accent);border-color:color-mix(in srgb,var(--accent) 35%,var(--rule))}
+.walk-start[aria-pressed=true]{background:var(--accent-soft)}
+figcaption .walk-start{margin:0;border:0}
+.walk-bar{position:sticky;top:8px;z-index:2;display:flex;flex-wrap:wrap;align-items:center;gap:8px;margin:0 0 12px;padding:6px 8px;border:1px solid var(--rule);border-radius:10px;background:color-mix(in srgb,var(--panel) 92%,transparent);backdrop-filter:blur(6px);box-shadow:var(--shadow);font-size:12px}
+.walk-text{flex:1 1 220px;min-width:0;color:var(--ink);font-size:13px}
+.walk-text:empty{display:none}
+.walk-bar button{font-size:12px;padding:2px 10px}
+.walk-count{min-width:44px;text-align:center;color:var(--muted);font-variant-numeric:tabular-nums}
+.steps li.walk-current::before{background:var(--accent);color:#fff;border-color:var(--accent)}
+.steps li.walk-current b,.steps li.walk-current .diagram-link{color:var(--accent-ink)}
+.steps li:not(.walk-current):has(~ .walk-current) b,.steps:has(.walk-current) li:not(.walk-current) p{opacity:.55}
.diagram-link{color:var(--ink)}
.diagram-link>span{color:var(--faint);font-weight:400;transition:color .15s}
.diagram-link:hover{color:var(--accent);text-decoration:none}
@@ -148,7 +162,7 @@ meter{width:100%;height:8px;accent-color:var(--accent)}
.diagram-panel .panel-body{display:flex;flex-direction:column;padding:14px 16px 16px}
.block-diagram{flex:1;display:flex;flex-direction:column}
.diagram{flex:1;display:flex;flex-direction:column}
-.diagram-preview{flex:1;min-width:0;max-width:100%;overflow:auto;display:flex;align-items:center;padding:0}
+.diagram-preview{flex:1;min-width:0;max-width:100%;overflow:auto;display:flex;align-items:flex-start;padding:0}
.diagram-preview>svg{display:block;width:min(100%,calc(var(--native-width,100vw) * 1.25))!important;margin-inline:auto;height:auto!important;min-height:0!important;max-height:none!important;max-width:none!important}
.diagram-preview>svg>rect[fill^="url("],.diagram-preview [data-legend]{display:none}
/* A single lane is the whole diagram, and lanes the shorthand adds only to stack branches carry no
@@ -218,6 +232,28 @@ footer{padding:28px 0 32px}
.colophon{margin-top:20px;font-size:11px;color:var(--faint);letter-spacing:.04em}
.colophon code{font-size:10px}
+/* Follow-up questions */
+.ask-button{margin-left:auto;flex-shrink:0;font-size:12px;padding:1px 9px;color:var(--muted);border-color:transparent;background:none;opacity:.7;transition:opacity .15s,color .15s,border-color .15s}
+.panel:hover .ask-button,.ask-button:focus-visible{opacity:1;border-color:var(--rule-strong)}
+.ask-button:hover{color:var(--accent);border-color:color-mix(in srgb,var(--accent) 40%,var(--rule))}
+.ask-floating{position:absolute;z-index:20;font-size:12px;padding:3px 10px;border-radius:999px;background:var(--ink);color:var(--paper);border:0;box-shadow:0 4px 14px rgb(0 0 0/.18)}
+.ask-floating:hover{background:var(--accent);color:#fff}
+.ask-dialog{width:min(520px,calc(100vw - 32px));padding:0}
+.ask-dialog form{margin:0;display:flex;flex-direction:column;gap:12px;padding:16px 18px 18px}
+.ask-dialog header{display:flex;align-items:center;justify-content:space-between;gap:12px}
+.ask-dialog h2{font-size:14.5px;font-weight:600;overflow-wrap:anywhere}
+.ask-dialog header button{border:0;background:none;font-size:18px;line-height:1;padding:2px 6px;color:var(--muted)}
+.ask-dialog blockquote{margin:0;padding:8px 12px;border-radius:8px;background:var(--sunk);box-shadow:inset 3px 0 0 var(--accent);font-size:13px;color:var(--secondary);max-height:120px;overflow:auto}
+.ask-chips{display:flex;flex-wrap:wrap;gap:6px}
+.ask-chips button{font-size:12px;padding:2px 10px;border-radius:999px;color:var(--secondary)}
+.ask-chips button:hover{color:var(--accent);border-color:var(--accent)}
+.ask-dialog textarea{font:inherit;font-size:13.5px;color:var(--ink);background:var(--panel);border:1px solid var(--rule-strong);border-radius:8px;padding:8px 10px;resize:vertical}
+.ask-dialog textarea:focus{outline:2px solid var(--accent);outline-offset:0;border-color:transparent}
+.ask-dialog footer{display:flex;justify-content:flex-end;gap:8px}
+.ask-dialog .primary{background:var(--accent);border-color:var(--accent);color:#fff}
+:root[data-theme=dark] .ask-dialog .primary{color:#0c0d10}
+@media print{.ask-button,.ask-floating{display:none!important}}
+
/* Dialogs */
dialog{color:var(--ink);background:var(--panel);border:1px solid var(--rule);border-radius:12px;box-shadow:0 24px 80px rgb(0 0 0/.25)}
dialog::backdrop{background:rgb(10 10 12/.55);backdrop-filter:blur(2px)}
diff --git a/archify/explainer/reader.js b/archify/explainer/reader.js
index 7af795c5..e13efc37 100644
--- a/archify/explainer/reader.js
+++ b/archify/explainer/reader.js
@@ -293,23 +293,179 @@
viewerDialog.addEventListener('close',()=>{ document.body.classList.remove('dialog-open'); viewerOpener?.focus({preventScroll:true}); });
window.addEventListener('message',event=>{ if(!viewer || event.source !== viewer.frame.contentWindow || event.data?.token !== viewer.token) return; if(event.data.kind === 'archify-explainer-ready') {viewer.ready = true; viewerDialog.dataset.nativeReady = 'true'; viewerDialog.querySelector('.dialog-loading').hidden = true; sendViewer();} else if(event.data.kind === 'archify-explainer-focus-result') {viewerDialog.dataset.nativeFocus = JSON.stringify({nodes:event.data.nodes,edges:event.data.edges,active:event.data.active});} else if(event.data.kind === 'archify-explainer-escape') closeViewer(); });
all('[data-open-diagram]').forEach(button=>button.addEventListener('click',()=>openViewer(button.dataset.openDiagram,'',button)));
+ // One spotlight for every text-to-diagram link: the named nodes and edges stay lit, the rest dims.
+ const previewOf = id => byId(id)?.querySelector('.diagram-preview');
+ function spotlight(preview, nodes = [], edges = []) {
+ if (!preview) return;
+ let matched = false;
+ all('[data-node-id],[data-edge-id]',preview).forEach(element=>{const hit = nodes.includes(element.dataset.nodeId) || edges.includes(element.dataset.edgeId); matched ||= hit; element.classList.toggle('reader-highlight',hit);});
+ preview.classList.toggle('focusing',matched);
+ }
+ const targetOf = link => {
+ const hash = link.dataset.diagramHash || '';
+ let edges = []; try { edges = JSON.parse(link.dataset.diagramEdges || '[]'); } catch {}
+ return {preview:previewOf(link.dataset.diagramLink),nodes:hash.startsWith('focus=') ? [decodeURIComponent(hash.slice(6))] : hash.startsWith('route=') ? hash.slice(6).split('~').map(decodeURIComponent) : [],edges};
+ };
all('[data-diagram-link]').forEach(link=>{
link.addEventListener('click',event=>{ event.preventDefault(); openViewer(link.dataset.diagramLink,link.dataset.diagramHash || '',link); });
- const highlight = active => {
- const preview = byId(link.dataset.diagramLink)?.querySelector('.diagram-preview'); if(!preview) return;
- const target = link.dataset.diagramHash || '';
- const nodes = target.startsWith('focus=') ? [decodeURIComponent(target.slice(6))] : target.startsWith('route=') ? target.slice(6).split('~').map(decodeURIComponent) : [];
- let edges = []; try { edges = JSON.parse(link.dataset.diagramEdges || '[]'); } catch {}
- let matched = false;
- all('[data-node-id],[data-edge-id]',preview).forEach(element=>{const hit = active && (nodes.includes(element.dataset.nodeId) || edges.includes(element.dataset.edgeId)); matched ||= hit; element.classList.toggle('reader-highlight',hit);});
- preview.classList.toggle('focusing',matched);
- };
+ const highlight = active => { const {preview,nodes,edges} = targetOf(link); spotlight(preview,active ? nodes : [],active ? edges : []); };
link.addEventListener('mouseenter',()=>highlight(true)); link.addEventListener('mouseleave',()=>highlight(false)); link.addEventListener('focus',()=>highlight(true)); link.addEventListener('blur',()=>highlight(false));
});
+ // A name in the text that is also a node label is linked to that node, once per panel, both ways:
+ // hovering the word lights the node, hovering the node lights the word.
+ function linkTerms() {
+ const terms = new Map();
+ all('.diagram-preview').forEach(preview=>all('[data-node-id][data-node-label]',preview).forEach(node=>{
+ const label = node.dataset.nodeLabel.trim();
+ const target = {diagram:preview.closest('.block').id,node:node.dataset.nodeId};
+ if ((/\p{Script=Han}/u.test(label) ? label.length >= 2 : label.length >= 3) && !terms.has(label.toLowerCase())) terms.set(label.toLowerCase(),target);
+ // A plain-word ID ("server" for "Server :443") also names the node in English prose.
+ if (/^[a-z]{3,}$/.test(target.node) && !terms.has(target.node)) terms.set(target.node,target);
+ }));
+ if (!terms.size) return;
+ const pattern = new RegExp([...terms.keys()].sort((a,b)=>b.length - a.length).map(label=>label.replace(/[.*+?^${}()|[\]\\]/g,'\\$&'))
+ .join('|'),'giu');
+ const word = /[\p{L}\p{N}_]/u;
+ all('.panel').forEach(panel=>{
+ const seen = new Set();
+ const walker = document.createTreeWalker(panel.querySelector('.panel-body') || panel,NodeFilter.SHOW_TEXT,{acceptNode:text=>text.parentElement.closest('.block-diagram,.block-chart,pre,code,a,button,svg,figcaption,.term,.diagram-semantics,thead') ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT});
+ const texts = []; while (walker.nextNode()) texts.push(walker.currentNode);
+ for (const text of texts) {
+ const value = text.nodeValue, parts = []; let last = 0;
+ for (const match of value.matchAll(pattern)) {
+ const before = value[match.index - 1], after = value[match.index + match[0].length];
+ if (seen.has(match[0].toLowerCase()) || (!/\p{Script=Han}/u.test(match[0]) && ((before && word.test(before)) || (after && word.test(after))))) continue;
+ seen.add(match[0].toLowerCase()); parts.push(value.slice(last,match.index),match[0]); last = match.index + match[0].length;
+ }
+ if (!parts.length) continue;
+ const fragment = document.createDocumentFragment();
+ parts.forEach((part,index)=>{ if (index % 2 === 0) { fragment.append(part); return; } const target = terms.get(part.toLowerCase()), span = document.createElement('span'); span.className = 'term'; span.dataset.diagram = target.diagram; span.dataset.node = target.node; span.textContent = part; fragment.append(span); });
+ fragment.append(value.slice(last)); text.replaceWith(fragment);
+ }
+ });
+ all('.term').forEach(term=>{ const lit = on => spotlight(previewOf(term.dataset.diagram),on ? [term.dataset.node] : []); term.addEventListener('mouseenter',()=>lit(true)); term.addEventListener('mouseleave',()=>lit(false)); });
+ all('.diagram-preview').forEach(preview=>{
+ const id = preview.closest('.block').id;
+ preview.addEventListener('mouseover',event=>{ const node = event.target.closest('[data-node-id]')?.dataset.nodeId; all('.term').forEach(term=>term.classList.toggle('term-lit',term.dataset.diagram === id && term.dataset.node === node)); });
+ preview.addEventListener('mouseleave',()=>all('.term-lit').forEach(term=>term.classList.remove('term-lit')));
+ });
+ }
+ // Walk-through: step lists that point into a diagram, and sequence diagrams message by message.
+ // Each step lights its part of the diagram; arrow keys move, Escape ends.
+ let walking = null;
+ function walk(control, items, show) {
+ const stop = () => { walking?.end(); };
+ if (walking?.control === control) { stop(); return; }
+ stop();
+ let index = 0;
+ const bar = document.createElement('div'); bar.className = 'walk-bar';
+ bar.innerHTML = `<button type="button" data-walk="prev">← ${words.prev}</button><span class="walk-count"></span><button type="button" data-walk="next">${words.next} →</button><span class="walk-text" aria-live="polite"></span><button type="button" data-walk="end">${words.end}</button>`;
+ // A diagram's bar sits above the diagram, so it stays in view while a tall diagram scrolls past.
+ const figure = control.closest('figcaption')?.closest('figure'); if (figure) figure.before(bar); else control.after(bar);
+ control.setAttribute('aria-pressed','true');
+ // The bar changes the panel height the board was planned with.
+ const replan = () => requestAnimationFrame(()=>{ layoutBoard(); ensureDiagramReadability(); });
+ replan();
+ const render = () => { bar.querySelector('.walk-count').textContent = `${index + 1} / ${items.length}`; bar.querySelector('.walk-text').textContent = show(index) || ''; };
+ const move = delta => { index = Math.max(0,Math.min(items.length - 1,index + delta)); render(); };
+ bar.addEventListener('click',event=>{ const action = event.target.closest('[data-walk]')?.dataset.walk; if (action === 'end') stop(); else if (action) move(action === 'next' ? 1 : -1); });
+ const keys = event => { if (event.target.closest('input,textarea') || viewerDialog.open) return; if (event.key === 'ArrowRight') { event.preventDefault(); move(1); } else if (event.key === 'ArrowLeft') { event.preventDefault(); move(-1); } else if (event.key === 'Escape') stop(); };
+ document.addEventListener('keydown',keys);
+ walking = {control,end:()=>{ document.removeEventListener('keydown',keys); bar.remove(); control.setAttribute('aria-pressed','false'); show(-1); walking = null; replan(); }};
+ render();
+ }
+ function setupWalks() {
+ all('ol.steps').forEach(list=>{
+ const steps = all(':scope>li',list).filter(item=>item.querySelector('[data-diagram-link]'));
+ if (steps.length < 2) return;
+ const button = document.createElement('button'); button.type = 'button'; button.className = 'walk-start interactive'; button.textContent = `▶ ${words.walk}`; button.setAttribute('aria-pressed','false');
+ list.before(button);
+ button.addEventListener('click',()=>walk(button,steps,index=>{
+ steps.forEach((step,i)=>step.classList.toggle('walk-current',i === index));
+ all('.diagram-preview').forEach(preview=>spotlight(preview));
+ if (index < 0) return;
+ const {preview,nodes,edges} = targetOf(steps[index].querySelector('[data-diagram-link]'));
+ spotlight(preview,nodes,edges);
+ const box = preview?.getBoundingClientRect();
+ if (box && (box.bottom < 0 || box.top > innerHeight)) preview.scrollIntoView({block:'nearest',behavior:'smooth'});
+ }));
+ });
+ all('.block-diagram').forEach(block=>{
+ if (diagrams[block.id]?.diagramType !== 'sequence') return;
+ const preview = block.querySelector('.diagram-preview'), messages = all('[data-edge-id]',preview);
+ if (messages.length < 2) return;
+ const button = document.createElement('button'); button.type = 'button'; button.className = 'text-button walk-start'; button.textContent = `▶ ${words.walkMessages}`; button.setAttribute('aria-pressed','false');
+ block.querySelector('figcaption button')?.before(button);
+ const label = id => preview.querySelector(`[data-node-id="${CSS.escape(id)}"]`)?.dataset.nodeLabel || id;
+ button.addEventListener('click',()=>walk(button,messages,index=>{
+ if (index < 0) { spotlight(preview); return; }
+ const message = messages[index];
+ spotlight(preview,[message.dataset.edgeFrom,message.dataset.edgeTo],[message.dataset.edgeId]);
+ const box = message.getBoundingClientRect();
+ if (box.top < 0 || box.bottom > innerHeight - 80) message.scrollIntoView({block:'center',behavior:'smooth'});
+ return `${label(message.dataset.edgeFrom)} → ${label(message.dataset.edgeTo)}${say(': ',':')}${message.dataset.edgeLabel || ''}`;
+ }));
+ });
+ }
all('[data-copy]').forEach(button=>button.addEventListener('click',()=>{
const text = button.closest('figure').querySelector('pre code').textContent;
Promise.resolve(navigator.clipboard?.writeText(text)).then(()=>{button.textContent = words.copied;setTimeout(()=>{button.textContent = words.copy;},1600);},()=>notify(say('Copy failed.','复制失败。')));
}));
+ // Follow-up questions: a reader asks about a panel, or about selected text in it, and copies a
+ // message that names the page, the panel ID and the quote, so the agent can revise just that panel.
+ function setupAsk() {
+ const dialog = document.createElement('dialog'); dialog.className = 'ask-dialog';
+ dialog.innerHTML = `<form method="dialog"><header><h2></h2><button type="button" data-ask-cancel aria-label="${words.askCancel}">×</button></header><blockquote hidden></blockquote><div class="ask-chips">${words.askChips.map(chip=>`<button type="button" data-chip>${chip}</button>`).join('')}</div><textarea rows="3" placeholder="${words.askPlaceholder}"></textarea><footer><button type="button" data-ask-cancel>${words.askCancel}</button><button type="submit" class="primary">${words.askCopy}</button></footer></form>`;
+ document.body.append(dialog);
+ const area = dialog.querySelector('textarea'), quoteBox = dialog.querySelector('blockquote');
+ let context = null;
+ const open = (panel, quote = '') => {
+ const number = panel.id === 'answer' ? words.answer : panel.querySelector('.panel-id')?.textContent.trim();
+ const title = panel.id === 'answer' ? words.answer : panel.dataset.title || panel.querySelector('h2')?.textContent.trim();
+ context = {panel,quote,number,title};
+ dialog.querySelector('h2').textContent = `${words.ask} · ${panel.id === 'answer' ? title : `${number} ${title}`}`;
+ quoteBox.hidden = !quote; quoteBox.textContent = quote;
+ area.value = ''; dialog.showModal(); area.focus();
+ };
+ dialog.querySelectorAll('[data-chip]').forEach(chip=>chip.addEventListener('click',()=>{ area.value = area.value ? `${area.value}\n${chip.textContent}` : chip.textContent; area.focus(); }));
+ dialog.querySelectorAll('[data-ask-cancel]').forEach(button=>button.addEventListener('click',()=>dialog.close()));
+ dialog.querySelector('form').addEventListener('submit',event=>{
+ event.preventDefault();
+ const {panel,quote,number,title} = context, page = document.querySelector('h1')?.textContent.trim();
+ const file = location.protocol === 'file:' ? decodeURIComponent(location.pathname) : location.href.split('#')[0];
+ const quoteMark = text => english ? `"${text}"` : `「${text}」`;
+ const lines = [
+ `${words.askPage}${say(': ',':')}${quoteMark(page)}`,
+ `${words.askFile}${say(': ',':')}${file}`,
+ `${words.askWhere}${say(': ',':')}${panel.id === 'answer' ? title : say(`Panel ${number} ${quoteMark(title)}`,`面板 ${number}${quoteMark(title)}`)}${say(` (ID: ${panel.id})`,`(ID: ${panel.id})`)}`,
+ ...(quote ? [`${words.askQuoteLabel}${say(': ',':')}${quoteMark(quote)}`] : []),
+ `${words.askQuestion}${say(': ',':')}${area.value.trim() || words.askChips[0]}`,
+ ...(panel.id === 'answer' ? [] : [words.askPatch]),
+ ];
+ const text = lines.join('\n');
+ Promise.resolve(navigator.clipboard?.writeText(text)).then(()=>{ dialog.close(); notify(words.askCopied); },()=>{ area.value = text; area.select(); });
+ });
+ all('.panel').forEach(panel=>{
+ const button = document.createElement('button'); button.type = 'button'; button.className = 'ask-button interactive'; button.textContent = words.ask;
+ button.addEventListener('click',()=>open(panel));
+ panel.querySelector('.panel-head')?.append(button);
+ });
+ const floating = document.createElement('button'); floating.type = 'button'; floating.className = 'ask-floating'; floating.textContent = words.askQuote; floating.hidden = true;
+ document.body.append(floating);
+ let selected = null;
+ document.addEventListener('selectionchange',()=>{
+ const selection = getSelection(), text = selection.toString().replace(/\s+/g,' ').trim();
+ const panel = selection.rangeCount ? selection.getRangeAt(0).commonAncestorContainer.parentElement?.closest?.('.panel') || (selection.getRangeAt(0).commonAncestorContainer.closest?.('.panel')) : null;
+ if (!panel || text.length < 2 || dialog.open) { floating.hidden = true; selected = null; return; }
+ const box = selection.getRangeAt(0).getBoundingClientRect();
+ selected = {panel,text:text.slice(0,400)};
+ floating.style.left = `${Math.max(8,Math.min(innerWidth - 120,box.left + box.width / 2 - 45 + scrollX))}px`;
+ floating.style.top = `${box.top + scrollY - 38}px`;
+ floating.hidden = false;
+ });
+ floating.addEventListener('mousedown',event=>event.preventDefault());
+ floating.addEventListener('click',()=>{ if (selected) open(selected.panel,selected.text); floating.hidden = true; });
+ }
// Checklist ticks are the reader's own progress; keep them per page and block across reloads.
all('.checklist').forEach(list=>{
const key = `archify-checklist:${root.dataset.artifact}:${list.closest('.block').id}`, boxes = all('input',list);
@@ -324,6 +480,9 @@
root.classList.add('js');
applyTheme();
cropDiagramPreviews();
+ linkTerms();
+ setupWalks();
+ setupAsk();
layoutBoard();
const relayout = () => { layoutBoard(); ensureDiagramReadability(); };
Promise.resolve(document.fonts?.ready).then(()=>requestAnimationFrame(()=>requestAnimationFrame(relayout)));
diff --git a/archify/explainer/render.mjs b/archify/explainer/render.mjs
index c2a4685c..0662548d 100644
--- a/archify/explainer/render.mjs
+++ b/archify/explainer/render.mjs
@@ -13,8 +13,8 @@ const escape = value => String(value ?? '').replace(/[&<>"']/g, 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');
const dictionaries = {
- en:{answer:'Answer',answerMark:'A',scope:'Applies to',sources:'Sources',print:'Print',auto:'System',light:'Light',dark:'Dark',typical:'Typical value',explore:'Explore diagram',close:'Close',loading:'Opening diagram…',graph:'Diagram structure',changes:'Structure changes',added:'Added',removed:'Removed',modified:'Modified',copy:'Copy',copied:'Copied'},
- zh:{answer:'结论',answerMark:'答',scope:'适用于',sources:'来源',print:'打印',auto:'系统',light:'浅色',dark:'深色',typical:'典型值',explore:'展开探索',close:'关闭',loading:'正在打开交互图…',graph:'图的结构',changes:'结构改动',added:'新增',removed:'删除',modified:'修改',copy:'复制',copied:'已复制'}
+ en:{answer:'Answer',answerMark:'A',scope:'Applies to',sources:'Sources',print:'Print',auto:'System',light:'Light',dark:'Dark',typical:'Typical value',explore:'Explore diagram',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',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',askPatch:'Revise only this panel with Archify panel replacement (patch explainer), keeping its ID.'},
+ zh:{answer:'结论',answerMark:'答',scope:'适用于',sources:'来源',print:'打印',auto:'系统',light:'浅色',dark:'深色',typical:'典型值',explore:'展开探索',close:'关闭',loading:'正在打开交互图…',graph:'图的结构',changes:'结构改动',added:'新增',removed:'删除',modified:'修改',copy:'复制',copied:'已复制',walk:'逐步看',walkMessages:'逐条看消息',prev:'上一步',next:'下一步',end:'结束',ask:'追问',askQuote:'追问这段',askPlaceholder:'哪里没看懂,或者希望这块补充什么?',askCopy:'复制追问',askCopied:'已复制,粘贴给 agent 即可',askCancel:'取消',askChips:['没看懂这块','展开讲讲','举个例子','依据是什么?'],askPage:'页面',askFile:'文件',askWhere:'位置',askQuoteLabel:'引用',askQuestion:'问题',askPatch:'请用 Archify 的面板替换(patch explainer)只更新这个面板,保留它的 ID。'}
};
/** Render a validated canonical explainer with separately prepared, immutable resources. */
diff --git a/archify/references/explainer-authoring.md b/archify/references/explainer-authoring.md
index 37185101..14be0861 100644
--- a/archify/references/explainer-authoring.md
+++ b/archify/references/explainer-authoring.md
@@ -90,7 +90,7 @@ Write for a reader who will act on the page and may check it. Use the user's lan
- The conclusion is read first; every panel after it supports, qualifies or applies it. Stop once nothing is left to support.
- Cover what the reader needs to act on the answer: the mechanism behind the conclusion, how to check it, and the cases where it does not hold. The next question a careful reader would ask gets a panel, a table row or a line in scope; a fact the reader could get wrong without it is not optional.
- Each panel takes one question and each sentence makes one claim. A claim a table or diagram already shows is not restated; the text adds its reason or exception.
-- Keep one term per thing across the title, panels, diagram labels and table headers, and prefer the reader's own term.
+- Keep one term per thing across the title, panels, diagram labels and table headers, and prefer the reader's own term. The page links a name in the text to the node with that label, so a reader can point at it in the diagram.
- Give results with their evidence: a number with its unit, a file position, a source. When a value is unknown or estimated, say so in scope.
- Cite a `@source` for each claim the reader cannot check alone: protocol details, thresholds, benchmark figures, API behaviour. A rule of thumb without a source is labelled as one, or left out.
- Recompute every derived number before delivery and show the arithmetic once: “990 of 1000 requests at 80 ms → P99 = 80 ms; 11 slow → P99 = 600 ms.” Totals in tables add up.
diff --git a/test/explainer-browser.test.mjs b/test/explainer-browser.test.mjs
index af533f55..29a0c1af 100644
--- a/test/explainer-browser.test.mjs
+++ b/test/explainer-browser.test.mjs
@@ -105,3 +105,35 @@ test('public system-theme mode starts with fresh storage and stable DOM identiti
await browser.resetPage();const disabled=await inspectPublicHtml(browser,{artifactPath:file,width:1440,theme:'dark',themeControl:'system',javascript:false,keyboard:false});assert.equal(await pageValue(browser,'Boolean(window.artifactRan)'),false);assert.equal(disabled.fontReadiness.status,'loaded');assert.equal(disabled.measurementMethod.clipCoverage,'not-measured-script-disabled');assert.equal(disabled.measurementMethod.documentExtentMeasured,true);assert.equal(disabled.background,'rgb(23, 23, 23)');
}finally{await browser.close();}
});
+test('text names light their diagram nodes and walk-throughs step through steps and messages',{skip:!chrome},async()=>{
+ const {renderExplainer}=await import('../archify/explainer/render.mjs');const {compileExplainerDiagram,prepareExplainerDiagrams}=await import('../archify/explainer/diagrams.mjs');
+ const spec=compileExplainerDiagram('sequence',['actor api | API | backend','actor redis | Redis | database','api | redis | Read cache','redis | api | Return cache'],{title:'Cache lookup',id:'native',quality:'showcase'});
+ const doc=formalDocument();doc.meta.id='walk-browser';doc.meta.quality_profile='showcase';doc.panels.push({id:'how',title:'Where does the request go?',blocks:[{id:'native',type:'diagram',diagramType:'sequence',spec},{id:'why',type:'prose',text:'The API asks Redis first, and Redis answers from memory.'},{id:'step',type:'steps',items:[{id:'read-step',text:'Read cache',target:{diagram:'native',node:'api',edges:['api-to-redis-1']}},{id:'return-step',text:'Return cache',target:{diagram:'native',node:'redis',edges:['redis-to-api-1']}}]}]});
+ const preparedDiagrams=await prepareExplainerDiagrams(doc,{baseDir:dir,sourcePath:path.join(dir,'walk.json'),quality:'showcase'});
+ const file=artifact('walk',renderExplainer(doc,{sourceText:JSON.stringify(doc),preparedDiagrams,preparedSources:{sources:{example:{title:'Example'}}}}));
+ const browser=new ChromeVisualBrowser(chrome);try {
+ await inspectPublicHtml(browser,{artifactPath:file,width:1440,keyboard:false});
+ const result=await pageValue(browser,`(function(){
+ const terms=[...document.querySelectorAll('#why .term')].map(t=>t.textContent);
+ const redis=document.querySelector('#why .term[data-node="redis"]');redis.dispatchEvent(new MouseEvent('mouseenter'));
+ const lit=[...document.querySelectorAll('#native .reader-highlight')].map(e=>e.dataset.nodeId||e.dataset.edgeId);redis.dispatchEvent(new MouseEvent('mouseleave'));
+ const steps=document.querySelector('ol.steps').previousElementSibling;steps.click();document.querySelector('.walk-bar [data-walk=next]').click();
+ const current=document.querySelector('.walk-current')?.id,stepLit=[...document.querySelectorAll('#native .reader-highlight')].map(e=>e.dataset.nodeId||e.dataset.edgeId);
+ document.querySelector('.walk-bar [data-walk=end]').click();const ended=!document.querySelector('.walk-bar')&&!document.querySelector('.walk-current');
+ const messages=document.querySelector('#native figcaption .walk-start');messages.click();
+ const text=document.querySelector('.walk-text').textContent;
+ document.querySelector('#how .ask-button').click();document.querySelector('.ask-dialog [data-chip]').click();
+ let copied='';navigator.clipboard.writeText=value=>{copied=value;return Promise.resolve();};document.querySelector('.ask-dialog [type=submit]').click();
+ return new Promise(resolve=>setTimeout(()=>resolve({terms,lit,current,stepLit,ended,text,copied,open:document.querySelector('.ask-dialog').open}),50));})()`);
+ assert.deepEqual(result.terms,['API','Redis'],'each name is linked once per panel');
+ assert.deepEqual(result.lit,['redis']);
+ assert.equal(result.current,'return-step');
+ assert.ok(result.stepLit.includes('redis-to-api-1'));
+ assert.equal(result.ended,true);
+ assert.equal(result.text,'API → Redis: Read cache');
+ assert.match(result.copied,/Where: Panel 2 "Where does the request go\?" \(ID: how\)/);
+ assert.match(result.copied,/Question: I do not follow this part/);
+ assert.match(result.copied,/patch explainer/);
+ assert.equal(result.open,false);
+ }finally{await browser.close();}
+});