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
Read walk-through steps beside their diagram and make the interactive view an evident entry
tt-a1i89496804c6f7
diff --git a/archify/explainer/reader.css b/archify/explainer/reader.cssindex 21d8edc4..6ea77a0e 100644--- a/archify/explainer/reader.css+++ b/archify/explainer/reader.css@@ -172,7 +172,6 @@ meter{width:100%;height:8px;accent-color:var(--accent)}.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}@@ -208,7 +207,26 @@ figcaption .walk-start{margin:0;border:0}.diagram-preview [data-node-id].reader-highlight rect:not(.c-mask){stroke:var(--accent);stroke-width:2}.diagram-preview [data-edge-id].reader-highlight path{stroke:var(--accent)}.diagram-preview [data-edge-id].reader-highlight text{fill:var(--accent)}-.diagram figcaption,.image figcaption,.code figcaption,.diff figcaption{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center;gap:8px;font-size:12px;color:var(--muted);margin-top:10px;padding:0 4px}+/* Steps beside the diagram they walk through, text on the left. The reader sets the diagram column+ to the width its text needs; with less than 320px left for the steps, the diagram wraps above+ them. The diagram stays in view while long steps scroll. */+.diagram-panel .guided{flex-flow:row-reverse wrap;justify-content:center;align-items:flex-start;gap:16px 36px}+.guided>.guide-figure{flex:1 0 var(--guide-figure,100%);max-width:min(100%,var(--guide-figure-max,100%));min-width:0;display:flex;flex-direction:column}+.guided.beside>.guide-figure{position:sticky;top:12px}+.guided>.guide-text{flex:1 1 320px;min-width:0}+/* The diagram's header: its title, and the way into the interactive view. */+.diagram>figcaption{display:flex;flex-wrap:wrap;align-items:center;gap:8px 12px;min-height:28px;margin:0 0 10px;padding:0 2px;font-size:12px;color:var(--muted)}+.diagram-title{font-size:12.5px;font-weight:500;color:var(--secondary)}+.js .diagram-actions{display:flex!important;align-items:center;gap:10px;margin-left:auto}+.explore-hint{font-size:11.5px;color:var(--faint)}+.block-diagram{container-type:inline-size}+@container (max-width:640px){.explore-hint{display:none!important}}+.explore-button{height:28px;padding:0 10px;font-size:12.5px;line-height:1;color:var(--accent-ink);border-color:color-mix(in srgb,var(--accent) 32%,var(--rule))}+.explore-button .tool-icon{width:14px;height:14px;color:var(--accent)}+.explore-button:hover{background:var(--accent-soft);color:var(--accent-ink)}+.diagram>figcaption .walk-start{margin:0}+.js .diagram-preview [data-node-id]{cursor:pointer}+.image figcaption,.code figcaption,.diff figcaption{display:flex;flex-wrap:wrap;justify-content:space-between;align-items:center;gap:8px;font-size:12px;color:var(--muted);margin-top:10px;padding:0 4px}.js .diagram-semantics{display:none}.diagram-semantics{margin-top:8px;font-size:11px;color:var(--muted)}.diagram-semantics ul{padding-left:18px}diff --git a/archify/explainer/reader.js b/archify/explainer/reader.jsindex e5e49364..4d4fae82 100644--- a/archify/explainer/reader.js+++ b/archify/explainer/reader.js@@ -18,22 +18,31 @@const board = document.querySelector('.board');function layoutBoard() {const panels = all(':scope>.panel',board);+ const floor = textFloor();+ // A diagram needs enough width for its smallest label to reach the reading floor.+ const readableWidth = svg => {+ const viewWidth = svg.viewBox.baseVal?.width || svg.getBoundingClientRect().width;+ const smallest = Math.min(...all('text',svg).filter(text=>text.textContent.trim() && !text.closest('[data-legend]')).map(text=>(parseFloat(text.getAttribute('font-size')) || parseFloat(getComputedStyle(text).fontSize)) / secondary(text)));+ return Number.isFinite(smallest) && smallest > 0 ? viewWidth * floor / smallest : 0;+ };+ // Beside its steps, the diagram column is exactly that wide; without room for both, it wraps above them.+ // It grows no wider than the preview draws the diagram, so spare width goes to the steps.+ all('.guided').forEach(guide=>{+ const preview = guide.querySelector('.diagram-preview'), need = Math.ceil(readableWidth(preview.querySelector('svg')) + 2);+ guide.style.setProperty('--guide-figure',need + 'px');+ guide.style.setProperty('--guide-figure-max',Math.max(need,Math.ceil(parseFloat(getComputedStyle(preview).getPropertyValue('--native-width')) * 1.25 || 0)) + 'px');+ });const reset = () => { board.classList.remove('measured'); panels.forEach(panel=>{panel.style.gridColumn = '';panel.style.gridRow = '';}); };if (window.innerWidth <= 760 || panels.length < 2) { reset(); return; }const gap = parseFloat(getComputedStyle(board).columnGap) || 0;const column = (board.clientWidth - gap * 11) / 12;const px = span => span * column + (span - 1) * gap;- const floor = textFloor();- // A diagram needs enough width for its smallest label to reach the reading floor.const readableSpan = panel => {const svgs = all('.diagram-preview>svg',panel);if (!svgs.length) return 0;- const inset = panel.offsetWidth - panel.querySelector('.diagram-preview').clientWidth;- const need = Math.max(...svgs.map(svg=>{- const viewWidth = svg.viewBox.baseVal?.width || svg.getBoundingClientRect().width;- const smallest = Math.min(...all('text',svg).filter(text=>text.textContent.trim() && !text.closest('[data-legend]')).map(text=>(parseFloat(text.getAttribute('font-size')) || parseFloat(getComputedStyle(text).fontSize)) / secondary(text)));- return Number.isFinite(smallest) && smallest > 0 ? viewWidth * floor / smallest + inset : 0;- }));+ const body = panel.querySelector('.panel-body'), style = getComputedStyle(body);+ const inset = panel.offsetWidth - body.clientWidth + parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);+ const need = Math.max(...svgs.map(svg=>readableWidth(svg) + inset));return [3,4,5,6,7,8,9,12].find(span=>px(span) >= need) || 12;};const SPANS = [4,5,6,7,8,12];@@ -178,6 +187,8 @@}function ensureDiagramReadability() {const minimumText = textFloor();+ // Only a diagram beside its steps stays in view; stacked above them, it would slide over them.+ all('.guided').forEach(guide=>guide.classList.toggle('beside',guide.firstElementChild.getBoundingClientRect().left >= guide.lastElementChild.getBoundingClientRect().right));all('.diagram-preview>svg').forEach(svg=>{// Measure the current available width, rather than retaining a wider viewport's floor.svg.style.minWidth = '0px';@@ -195,7 +206,7 @@preview.dataset.diagramMinimumText = String(minimumText);const status = svg.closest('.block-diagram').querySelector('.diagram-fit-status');status.hidden = !insufficient;- status.textContent = insufficient ? say('This diagram cannot fit this page width with readable text. Open the full diagram to inspect it.','此图无法在当前页宽内同时完整展示并保持文字清晰。请展开交互图查看。') : '';+ status.textContent = insufficient ? say('This diagram cannot fit this page width with readable text. Open the interactive view to inspect it.','此图在当前页宽下放不下且文字会太小,请打开交互图查看。') : '';});}const preference = matchMedia('(prefers-color-scheme: dark)');@@ -287,7 +298,7 @@const selectedEdges = (diagram.semantic?.edges || []).filter(edge=>requestedEdges.includes(edge.id));const requestedNodes = [...new Set(hash.startsWith('focus=') ? [decodeURIComponent(hash.slice(6))] : hash.startsWith('route=') ? hash.slice(6).split('~').map(decodeURIComponent) : selectedEdges.flatMap(edge=>[edge.from,edge.to]))];viewerOpener = opener;- byId('diagram-dialog-title').textContent = byId(id).querySelector('figcaption span').textContent;+ byId('diagram-dialog-title').textContent = byId(id).querySelector('.diagram-title').textContent;viewerDialog.showModal(); document.body.classList.add('dialog-open');if(viewer?.id === id) { viewer.hash = hash; viewer.nodes = requestedNodes; viewer.edges = requestedEdges; sendViewer(); return; }viewer?.frame.remove();@@ -348,6 +359,11 @@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)));+ // A node clicked in the preview opens the interactive view focused on it, with its links.+ all('.diagram-preview').forEach(preview=>preview.addEventListener('click',event=>{+ const node = event.target.closest('[data-node-id]')?.dataset.nodeId, block = preview.closest('.block');+ if (node) openViewer(block.id,`focus=${encodeURIComponent(node)}`,block.querySelector('[data-open-diagram]'));+ }));// 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 = []) {@@ -449,8 +465,8 @@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 button = document.createElement('button'); button.type = 'button'; button.className = 'walk-start'; button.textContent = `▶ ${words.walkMessages}`; button.setAttribute('aria-pressed','false');+ block.querySelector('.diagram-title')?.after(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; }diff --git a/archify/explainer/render.mjs b/archify/explainer/render.mjsindex 2b739c49..624796ed 100644--- a/archify/explainer/render.mjs+++ b/archify/explainer/render.mjs@@ -19,10 +19,11 @@ const icons = {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'),};const dictionaries = {- en:{answer:'Answer',answerMark:'A',scope:'Applies to',sources:'Sources',print:'Print / PDF',image:'Image',style:'Style',styles:{clean:'Clean',editorial:'Editorial',product:'Product',swiss:'Swiss'},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:'打印 / PDF',image:'长图',style:'样式',styles:{clean:'简洁',editorial:'杂志',product:'产品',swiss:'网格'},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。'}+ en:{answer:'Answer',answerMark:'A',scope:'Applies to',sources:'Sources',print:'Print / PDF',image:'Image',style:'Style',styles:{clean:'Clean',editorial:'Editorial',product:'Product',swiss:'Swiss'},auto:'System',light:'Light',dark:'Dark',typical:'Typical value',explore:'Open interactive view',exploreHint:'Click a node to trace its links',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',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:'打印 / PDF',image:'长图',style:'样式',styles:{clean:'简洁',editorial:'杂志',product:'产品',swiss:'网格'},auto:'系统',light:'浅色',dark:'深色',typical:'典型值',explore:'打开交互图',exploreHint:'点节点看上下游',exploreTitle:'缩放、搜索节点、追踪路径和上下游,导出图片或动画',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. */@@ -64,7 +65,7 @@ export function renderExplainer(document, options = {}) {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"><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><figcaption><span>${escape(title)}</span><button class="text-button interactive" type="button" data-open-diagram="${escape(block.id)}">${words.explore} ↗</button></figcaption></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 '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"><span class="explore-hint">${words.exploreHint}</span><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; }@@ -88,7 +89,11 @@ export function renderExplainer(document, options = {}) {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"' : '';- return `<section class="panel span${item.span}${panel.blocks.some(block=>block.type === 'diagram') ? ' 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><div class="panel-body">${panel.blocks.map(block=>blockHtml(block,panel.id)).join('')}</div></section>`;+ 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])=>{diff --git a/archify/references/explainer-authoring.md b/archify/references/explainer-authoring.mdindex 8170f2f3..f7a7b1b1 100644--- a/archify/references/explainer-authoring.md+++ b/archify/references/explainer-authoring.md@@ -32,8 +32,6 @@ The browser and server must agree on keys before any request is sent: **one extr| browser | server | Finished + GET / | emphasis || server | browser | 200 OK | return |-## What does each message do? {#messages}-@steps id=handshake-steps| hello | ClientHello | Offers cipher suites and a key share. | handshake-flow | browser || reply | ServerHello | Picks a suite and sends its key share; the certificate follows encrypted. | handshake-flow | server |@@ -81,6 +79,8 @@ A diagram replaces the paragraph that would describe it. When the answer involve| A change to code | `@diff` or a ```` ```diff ```` fence || A command, config or code that does not exist yet | Plain fence |+Steps that walk through a diagram belong in the diagram's panel: the page reads them beside it, each step lighting its part, and the reader can step through them.+A small answer gets a small page: the conclusion plus one or two panels. A how-it-works, diagnosis or checklist question usually needs three to five.## Writingdiff --git a/test/explainer-browser.test.mjs b/test/explainer-browser.test.mjsindex 14b8140d..3a60bd03 100644--- a/test/explainer-browser.test.mjs+++ b/test/explainer-browser.test.mjs@@ -135,6 +135,15 @@ test('text names light their diagram nodes and walk-throughs step through stepsassert.match(result.copied,/Question: I do not follow this part/);assert.match(result.copied,/patch explainer/);assert.equal(result.open,false);+ const placement=`(function(){const guide=document.querySelector('#how .guided'),figure=guide.querySelector('.guide-figure').getBoundingClientRect(),text=guide.querySelector('.guide-text').getBoundingClientRect();return {beside:guide.classList.contains('beside'),right:figure.left>=text.right,above:figure.bottom<=text.top,fit:guide.querySelector('.diagram-preview').dataset.diagramFit};})()`;+ assert.deepEqual(await pageValue(browser,placement),{beside:true,right:true,above:false,fit:'fit'},'steps read beside the diagram they walk through');+ await browser.cdp.send('Emulation.setDeviceMetricsOverride',{width:600,height:900,deviceScaleFactor:1,mobile:false},await browser.sessionPromise);+ await pageValue(browser,'new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))');+ assert.deepEqual(await pageValue(browser,placement),{beside:false,right:false,above:true,fit:'fit'},'without room for both, the diagram wraps above its steps');+ await pageValue(browser,`document.querySelector('#native .diagram-preview [data-node-id="redis"]').dispatchEvent(new MouseEvent('click',{bubbles:true}))`);+ let focused;for(let attempt=0;attempt<40;attempt++){focused=await inspectNativeViewer(browser);if(focused.available&&focused.nodes.includes('redis'))break;await new Promise(resolve=>setTimeout(resolve,50));}+ assert.deepEqual(focused.nodes,['redis'],'a node clicked in the preview opens the interactive view focused on it');+ await keyboardActivate(browser,'[data-close-diagram]');const style=await pageValue(browser,`(function(){const toggle=document.querySelector('[data-style-toggle]');toggle.click();const open=!document.querySelector('.style-options').hidden&&toggle.getAttribute('aria-expanded')==='true';document.querySelector('[data-style-choice=swiss]').click();return {open,closed:document.querySelector('.style-options').hidden,style:document.documentElement.dataset.style,label:document.querySelector('[data-style-label]').textContent,checked:document.querySelector('[data-style-choice=swiss]').getAttribute('aria-checked'),saved:localStorage.getItem('archify-explainer-style')};})()`);assert.deepEqual(style,{open:true,closed:true,style:'swiss',label:'Swiss',checked:'true',saved:'swiss'});const image=await pageValue(browser,`window.ArchifyExplainer.pageImage().then(blob=>({type:blob.type,size:blob.size}))`);