Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
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.cssindex 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.jsindex 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.mjsindex 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.mdindex 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.mjsindex 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 identitiawait 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();}+});