@stacksjs/defaults 0.75.360 → 0.75.362

package/ai/skills/stacks-technical-diagrams/explainer/browser-check.mjs

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { scanHtml } from './check.mjs';
+
+export const EXPLAINER_VIEWPORTS = Object.freeze([Object.freeze({width:1280,height:900}),Object.freeze({width:1440,height:900})]);
+async function evaluate(browser, expression, awaitPromise=false) {
+  let result;try {result=await browser.cdp.send('Runtime.evaluate',{expression,returnByValue:true,awaitPromise},await browser.sessionPromise);}catch(error){error.message += ` Inspector stage: ${expression.slice(0,100)}`;throw error;}
+  if (result.exceptionDetails) throw new Error(result.exceptionDetails.exception?.description || result.exceptionDetails.text);
+  return result.result?.value;
+}
+const expression = fn => `(${fn.toString()})()`;
+
+function measureNativePreviews() {
+  const rect=e=>{const r=e.getBoundingClientRect();return {left:r.left,right:r.right,top:r.top,bottom:r.bottom,width:r.width,height:r.height};};
+  const visible=e=>{const c=getComputedStyle(e),r=e.getBoundingClientRect();return c.display!=='none'&&c.visibility!=='hidden'&&Number(c.opacity)!==0&&r.width>0&&r.height>0;};
+  return Array.from(document.querySelectorAll('.diagram-preview svg')).map(svg=>{
+    const block=svg.closest('[data-block-type]'),panel=block.closest('.panel'),preview=svg.closest('.diagram-preview');
+    const prose=panel.querySelector('.block-prose > p')||document.querySelector('.block-prose > p'),body=parseFloat(getComputedStyle(prose||panel.querySelector('.panel-body')||block).fontSize);
+    const texts=Array.from(svg.querySelectorAll('text')).filter(e=>e.textContent.trim()&&visible(e)).map(e=>{const m=e.getScreenCTM(),sum=m.a*m.a+m.b*m.b+m.c*m.c+m.d*m.d,det=m.a*m.d-m.b*m.c,scale=Math.sqrt(Math.max(0,(sum-Math.sqrt(Math.max(0,sum*sum-4*det*det)))/2));return {text:e.textContent.trim(),size:parseFloat(getComputedStyle(e).fontSize)*scale/(e.closest('[data-edge-id]')?.7:1)};});
+    const minimum=texts.length?Math.min(...texts.map(t=>t.size)):null,bounds=rect(preview),svgBounds=rect(svg);
+    const nodes=Array.from(svg.querySelectorAll('[data-node-id]')).filter(visible).map(e=>({id:e.dataset.nodeId,...rect(e)}));
+    const outside=nodes.filter(n=>n.left<bounds.left-1||n.right>bounds.right+1||n.top<bounds.top-1||n.bottom>bounds.bottom+1);
+    return {component:block.id,minimum,body,ratio:minimum===null?null:minimum/body,smallest:texts.find(t=>t.size===minimum),rect:{width:svgBounds.width,height:svgBounds.height},computed:{width:getComputedStyle(svg).width,height:getComputedStyle(svg).height},fit:preview.dataset.diagramFit,requiredWidth:Number(preview.dataset.diagramRequiredWidth)||null,minimumText:Number(preview.dataset.diagramMinimumText)||null,minWidth:svg.style.minWidth,viewBox:svg.getAttribute('viewBox'),preview:bounds,scrollWidth:preview.scrollWidth,clientWidth:preview.clientWidth,nodes,outsidePreview:outside};
+  });
+}
+
+/** Actual CSS/CTM geometry of the current native previews, including live resize. */
+export async function inspectNativePreviewLayout(browser) {return evaluate(browser,expression(measureNativePreviews));}
+
+async function measurePublicHtml(nativeClipping=true) {
+  const visible=e=>{const c=getComputedStyle(e),r=e.getBoundingClientRect();return c.display!=='none'&&c.visibility!=='hidden'&&Number(c.opacity)!==0&&r.width>0&&r.height>0;};
+  const owner=e=>e.closest('[data-block-type],.panel')?.id || e.id || e.tagName.toLowerCase();
+  const domPath=e=>{const parts=[];for(let p=e;p;p=p.parentElement){const tag=p.localName,peers=p.parentElement?Array.from(p.parentElement.children).filter(c=>c.localName===tag):[p];parts.unshift(`${tag}:nth-of-type(${peers.indexOf(p)+1})`);}return parts.join(' > ');};
+  const identity=e=>({stableComponent:domPath(e),text:(e.textContent||'').trim().slice(0,160),label:e.getAttribute('aria-label')||e.getAttribute('title')||'',href:e.getAttribute('href')||null});
+  const ancestors=e=>{const result=[];for(let p=e.parentElement;p;p=p.parentElement)result.push(p);return result;};
+  const regions=Array.from(document.querySelectorAll('body *')).filter(visible);
+  // Chrome computes the actual containing-block/clip chain. Expanding only the
+  // observer root exposes off-viewport boxes while retaining every local clip,
+  // including SVG, nested scrollers, transforms and out-of-flow descendants.
+  const extent=Math.ceil(regions.reduce((maximum,e)=>{const r=e.getBoundingClientRect();return Math.max(maximum,Math.abs(r.left),Math.abs(r.right),Math.abs(r.top),Math.abs(r.bottom));},Math.max(innerWidth,innerHeight,document.documentElement.scrollWidth,document.documentElement.scrollHeight)))+1;
+  const intersections=nativeClipping?await new Promise((resolve,reject)=>{
+    if(!regions.length){resolve(new Map());return;}
+    const entries=new Map();let observer;
+    const timeout=setTimeout(()=>{observer.disconnect();reject(new Error('Native clipping measurement did not complete.'));},2000);
+    observer=new IntersectionObserver(batch=>{for(const entry of batch)entries.set(entry.target,entry);if(entries.size===regions.length){clearTimeout(timeout);observer.disconnect();resolve(entries);}},{root:null,rootMargin:`${extent}px`});
+    regions.forEach(e=>observer.observe(e));
+  }):new Map();
+  const overflows=(nativeClipping?regions:[]).filter(e=>{const r=intersections.get(e).intersectionRect;return r.width>0&&r.height>0&&(r.left<-1||r.right>innerWidth+1);}).slice(0,20).map(e=>{const entry=intersections.get(e),r=entry.intersectionRect;return {...identity(e),component:owner(e),tag:e.tagName,left:r.left,right:r.right,bounds:{left:entry.boundingClientRect.left,right:entry.boundingClientRect.right}};});
+  const localClipping=(nativeClipping?regions:[]).filter(e=>{const entry=intersections.get(e),r=entry.boundingClientRect,i=entry.intersectionRect;const style=getComputedStyle(e),ownCrop=(['hidden','clip'].includes(style.overflowX)&&e.scrollWidth>e.clientWidth+1)||(['hidden','clip'].includes(style.overflowY)&&e.scrollHeight>e.clientHeight+1);return (ownCrop||i.width<r.width-1||i.height<r.height-1)&&(Array.from(e.childNodes).some(n=>n.nodeType===3&&n.textContent.trim())||e.matches('a[href],button,input,select,textarea,[role=button],[role=link]'));}).map(e=>{
+    const clips=ancestors(e).filter(p=>{const s=getComputedStyle(p);return ['auto','scroll','hidden','clip'].includes(s.overflowX)||['auto','scroll','hidden','clip'].includes(s.overflowY)||s.clipPath!=='none'||s.clip!=='auto'||/(?:paint|strict|content)/.test(s.contain);}).map(p=>{const s=getComputedStyle(p),b=p.getBoundingClientRect(),t=e.getBoundingClientRect(),cropX=t.left<b.left-1||t.right>b.right+1,cropY=t.top<b.top-1||t.bottom>b.bottom+1;return {...identity(p),overflowX:s.overflowX,overflowY:s.overflowY,scrollableX:['auto','scroll'].includes(s.overflowX)&&p.scrollWidth>p.clientWidth+1,scrollableY:['auto','scroll'].includes(s.overflowY)&&p.scrollHeight>p.clientHeight+1,nonScrollableClip:(cropX&&['hidden','clip'].includes(s.overflowX))||(cropY&&['hidden','clip'].includes(s.overflowY))||s.clipPath!=='none'||s.clip!=='auto'||((cropX||cropY)&&/(?:paint|strict|content)/.test(s.contain))};});
+    const entry=intersections.get(e),r=entry.boundingClientRect,i=entry.intersectionRect,scrollable=clips.some(c=>c.scrollableX||c.scrollableY),ownStyle=getComputedStyle(e),ownCrop=(['hidden','clip'].includes(ownStyle.overflowX)&&e.scrollWidth>e.clientWidth+1)||(['hidden','clip'].includes(ownStyle.overflowY)&&e.scrollHeight>e.clientHeight+1),nonScrollable=ownCrop||clips.some(c=>c.nonScrollableClip);
+    return {...identity(e),component:owner(e),tag:e.tagName,access:scrollable?(nonScrollable?'mixed-scroll-and-clipping':'manual-scroll'):'clipped-no-manual-scroll',ownContentClipped:ownCrop,actionable:e.matches('a[href],button,input,select,textarea,[role=button],[role=link]'),keyboardReachability:'not-measured-by-clipping',bounds:{left:r.left,right:r.right,top:r.top,bottom:r.bottom},painted:{left:i.left,right:i.right,top:i.top,bottom:i.bottom,width:i.width,height:i.height},clipAncestors:clips};
+  });
+  const refs=Array.from(document.querySelectorAll('a[href^="#"]')).filter(e=>e.getAttribute('href').length>1).filter(e=>{let id=e.getAttribute('href').slice(1);try{id=decodeURIComponent(id);}catch{}return !document.getElementById(id);}).map(e=>({...identity(e),component:owner(e)}));
+  const ids=new Set(),duplicateIds=[];document.querySelectorAll('[id]').forEach(e=>{if(ids.has(e.id))duplicateIds.push(e.id);ids.add(e.id);});
+  const controls=Array.from(document.querySelectorAll('a[href],button,input,select,textarea,summary,[role="button"],[role="link"],[onclick],[tabindex]')).filter(e=>{const c=getComputedStyle(e),r=e.getBoundingClientRect();return c.display!=='none'&&c.visibility!=='hidden'&&r.width>0&&r.height>0&&!e.disabled&&e.type!=='hidden'&&!e.closest('[inert]');});
+  const keyboardIssues=controls.filter(e=>e.tabIndex<0 || (!['A','BUTTON','INPUT','SELECT','TEXTAREA','SUMMARY'].includes(e.tagName)&&!['button','link'].includes(e.getAttribute('role')))).map(e=>({...identity(e),component:owner(e),tag:e.tagName,reason:'An active control is outside sequential keyboard focus or lacks its semantic role.'}));
+  controls.forEach((e,i)=>{e.setAttribute('data-qa-key',String(i));e.setAttribute('data-qa-path',domPath(e));});
+  const occluded=controls.filter(e=>{const r=e.getBoundingClientRect();if(r.top<0||r.bottom>innerHeight)return false;const hit=document.elementFromPoint(r.x+r.width/2,r.y+r.height/2);return hit&&!e.contains(hit)&&!hit.contains(e);}).map(e=>({...identity(e),component:owner(e),tag:e.tagName}));
+  const texts=regions.filter(e=>Array.from(e.childNodes).some(n=>n.nodeType===3&&n.textContent.trim())).map(e=>({...identity(e),component:owner(e),fontSize:(function(){const size=parseFloat(getComputedStyle(e).fontSize);if(typeof e.getScreenCTM!=='function')return size;const m=e.getScreenCTM();if(!m)return size;const sum=m.a*m.a+m.b*m.b+m.c*m.c+m.d*m.d,det=m.a*m.d-m.b*m.c;return size*Math.sqrt(Math.max(0,(sum-Math.sqrt(Math.max(0,sum*sum-4*det*det)))/2));})()}));
+  const smallText=texts.filter(e=>e.fontSize<10);
+  const staticReading=Array.from(document.querySelectorAll('.answer-panel,.typical-footnotes li')).map(e=>({component:owner(e),visible:visible(e),text:e.textContent.trim()}));
+  const background=getComputedStyle(document.body).backgroundColor || getComputedStyle(document.documentElement).backgroundColor;
+  return {measurementMethod:{version:'public-html-qa-v2',clipping:nativeClipping?'native-intersection-observer-expanded-root':'not-measured-script-execution-disabled',clippingMeasured:nativeClipping,clipCoverage:nativeClipping?'native-clip-chain':'not-measured-script-disabled',documentExtentMeasured:true,rootMargin:nativeClipping?extent:null,limits:['Axis-aligned element intersections; does not inspect pixels, shadows, masks or visual quality.','Local clipping access classification uses ancestor axis-aligned bounds; mixed clips and non-rectangular clipping need human review. Keyboard traversal is separate.']},staticReading,innerWidth,innerHeight,scrollWidth:Math.ceil(document.documentElement.scrollWidth),scrollHeight:Math.ceil(document.documentElement.scrollHeight),overflowElements:overflows,localClipping,references:refs,duplicateIds,keyboardIssues,controlCount:controls.length,occluded,smallText,bodyText:document.body.innerText,background,resolvedTheme:document.documentElement.dataset.theme || (matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light'),panels:Array.from(document.querySelectorAll('.panel,[data-block-type]')).map(e=>({id:e.id,visible:visible(e),text:e.innerText})),interactiveVisible:document.querySelectorAll('.interactive').length ? Array.from(document.querySelectorAll('.interactive')).filter(visible).map(owner):[]};
+}
+
+async function keyboardTraversal(browser, controlCount) {
+  const session=await browser.sessionPromise;
+  await evaluate(browser,"(function(){document.activeElement.blur();window.scrollTo(0,0);})()");
+  const reached=new Set();
+  // Radio groups intentionally expose one tab stop; Arrow keys reach siblings.
+  const record=async()=>{const state=await evaluate(browser,"({key:document.activeElement?.dataset.qaKey,radio:document.activeElement?.type==='radio',name:document.activeElement?.name})");if(state?.key!==undefined)reached.add(state.key);return state;};
+  const arrowGroups=new Set();
+  for(let i=0;i<controlCount+3;i++) {
+    await browser.cdp.send('Input.dispatchKeyEvent',{type:'keyDown',key:'Tab',code:'Tab',windowsVirtualKeyCode:9},session);
+    await browser.cdp.send('Input.dispatchKeyEvent',{type:'keyUp',key:'Tab',code:'Tab',windowsVirtualKeyCode:9},session);
+    const state=await record();
+    if(state.radio&&!arrowGroups.has(state.name)) {
+      arrowGroups.add(state.name);
+      const siblings=await evaluate(browser,`document.querySelectorAll('input[type=radio][name="${state.name}"][data-qa-key]').length`);
+      for(let step=0;step<siblings;step++) {for(const type of ['keyDown','keyUp'])await browser.cdp.send('Input.dispatchKeyEvent',{type,key:'ArrowRight',code:'ArrowRight',windowsVirtualKeyCode:39},session);await record();}
+    }
+  }
+  const missing=await evaluate(browser,`Array.from(document.querySelectorAll('[data-qa-key]')).filter(e=>!${JSON.stringify([...reached])}.includes(e.dataset.qaKey)).map(e=>({key:e.dataset.qaKey,stableComponent:e.dataset.qaPath,text:e.textContent.trim().slice(0,160),href:e.getAttribute('href')||null,tag:e.tagName,component:e.closest('[data-block-type],.panel')?.id||e.id||e.tagName.toLowerCase(),label:e.getAttribute('aria-label')||e.textContent.trim()||e.name,tabIndex:e.tabIndex,type:e.type,reason:'This active control was not reached by Tab or native radio ArrowRight navigation.'}))`);
+  return {count:controlCount,reached:reached.size,missing,ok:reached.size===controlCount};
+}
+
+export async function inspectPublicHtml(browser,{artifactPath,width=1440,height=900,theme='light',themeControl='query',javascript=true,media='screen',keyboard=true,screenshotPath,writeScreenshot}={}) {
+  const session=await browser.sessionPromise;
+  const errors=[];
+  let clearStorage;
+  if(!['query','system'].includes(themeControl))throw new Error('themeControl must be query or system.');
+  const unsubscribe=browser.cdp.subscribe?.(message=>{
+    if(message.sessionId!==session)return;
+    if(message.method==='Runtime.exceptionThrown')errors.push(message.params.exceptionDetails.exception?.description || message.params.exceptionDetails.text);
+    if(message.method==='Runtime.consoleAPICalled'&&message.params.type==='error')errors.push(message.params.args.map(a=>a.value??a.description).join(' '));
+    if(message.method==='Log.entryAdded'&&message.params.entry.level==='error')errors.push(message.params.entry.text);
+  });
+  try {
+    await browser.cdp.send('Page.bringToFront',{},session);
+    await browser.cdp.send('Log.enable',{},session);
+    await browser.cdp.send('Emulation.setDeviceMetricsOverride',{width,height,deviceScaleFactor:1,mobile:false},session);
+    await browser.cdp.send('Emulation.setEmulatedMedia',{media,features:[{name:'prefers-color-scheme',value:theme},{name:'prefers-reduced-motion',value:'reduce'}]},session);
+    await browser.cdp.send('Emulation.setScriptExecutionDisabled',{value:!javascript},session);
+    const url=pathToFileURL(artifactPath);if(themeControl==='query')url.searchParams.set('theme',theme);else clearStorage=await browser.cdp.send('Page.addScriptToEvaluateOnNewDocument',{source:'try {localStorage.clear();sessionStorage.clear();} catch {}'},session);
+    const loaded=browser.cdp.waitFor('Page.loadEventFired',session);loaded.catch(()=>{});
+    const navigation=await browser.cdp.send('Page.navigate',{url:url.href},session);if(navigation.errorText)throw new Error(navigation.errorText);await loaded;
+    if(themeControl==='system'&&!javascript)await evaluate(browser,"(function(){try{localStorage.clear();sessionStorage.clear();return true;}catch{return false;}})()");
+    // Inspector evaluation works with page JavaScript disabled; it does not run
+    // or repair the artifact's reader. Font readiness is separate from reader JS.
+    const fontStart=Date.now();let fontStatus;
+    do {fontStatus=await evaluate(browser,"(function(){void document.body.offsetHeight;return document.fonts.status;})()");if(fontStatus==='loaded')break;await new Promise(resolve=>setTimeout(resolve,50));}while(Date.now()-fontStart<5000);
+    const fontReadiness={status:fontStatus,waitMs:Date.now()-fontStart};
+    await new Promise(resolve=>setTimeout(resolve,50));
+    const metrics=await evaluate(browser,`(${measurePublicHtml.toString()})(${javascript})`,true);
+    metrics.fontReadiness=fontReadiness;metrics.themeControl=themeControl;metrics.navigationUrl=url.href;
+    if(javascript&&keyboard)metrics.keyboardTraversal=await keyboardTraversal(browser,metrics.controlCount);
+    metrics.consoleErrors=errors;
+    if(screenshotPath) {
+      await evaluate(browser,'window.scrollTo(0,0)');
+      const result=await browser.cdp.send('Page.captureScreenshot',{format:'png',fromSurface:true,captureBeyondViewport:false},session,20000);
+      if(!result.data)throw new Error('Chrome returned an empty screenshot.');
+      const bytes=Buffer.from(result.data,'base64');if(writeScreenshot)writeScreenshot(bytes);else fs.writeFileSync(screenshotPath,bytes,{flag:'wx'});
+    }
+    return metrics;
+  } finally {unsubscribe?.();if(clearStorage)await browser.cdp.send('Page.removeScriptToEvaluateOnNewDocument',{identifier:clearStorage.identifier},session);await browser.cdp.send('Emulation.setScriptExecutionDisabled',{value:false},session);}
+}
+
+export async function inspectNativeViewer(browser) {
+  const parent=await browser.cdp.send('Page.getFrameTree',{},await browser.sessionPromise);
+  const targets=await browser.cdp.send('Target.getTargets');
+  const target=targets.targetInfos.find(t=>t.type==='iframe'&&t.parentId===parent.frameTree.frame.id&&t.url.startsWith('about:srcdoc'));
+  if(!target)return {available:false,errors:[]};
+  const attached=await browser.cdp.send('Target.attachToTarget',{targetId:target.targetId,flatten:true});
+  const errors=[];
+  const stop=browser.cdp.subscribe?.(m=>{if(m.sessionId!==attached.sessionId)return;if(m.method==='Runtime.exceptionThrown')errors.push(m.params.exceptionDetails.exception?.description||m.params.exceptionDetails.text);if(m.method==='Runtime.consoleAPICalled'&&m.params.type==='error')errors.push(m.params.args.map(a=>a.value??a.description).join(' '));});
+  try {
+    await browser.cdp.send('Runtime.enable',{},attached.sessionId);
+    const result=await browser.cdp.send('Runtime.evaluate',{expression:"({ready:document.readyState,visibility:document.visibilityState,href:location.href,active:document.querySelector('svg[data-focus-active]')?.dataset.focusActive||'',nodes:[...new Set(Array.from(document.querySelectorAll('[data-focus-selected]')).map(e=>e.dataset.nodeId).filter(Boolean))],edges:[...new Set(Array.from(document.querySelectorAll('[data-edge-id][data-focus-match]')).map(e=>e.dataset.edgeId))],hasViewer:Boolean(window.Archify?.focus)})",returnByValue:true},attached.sessionId);
+    if(result.exceptionDetails)throw new Error(result.exceptionDetails.text);
+    return {available:true,targetId:target.targetId,...result.result.value,errors};
+  } finally {stop?.();await browser.cdp.send('Target.detachFromTarget',{sessionId:attached.sessionId});}
+}
+
+async function press(browser,key) {const session=await browser.sessionPromise;const codes={Enter:13,Escape:27,' ':32};for(const type of ['keyDown','keyUp'])await browser.cdp.send('Input.dispatchKeyEvent',{type,key,code:key===' '?'Space':key,windowsVirtualKeyCode:codes[key],...(key==='Enter'&&type==='keyDown'?{text:'\r',unmodifiedText:'\r'}:{})},session);await evaluate(browser,'new Promise(resolve=>setTimeout(resolve,0))',true);}
+async function activate(browser,selector,key='Enter') {const exists=await evaluate(browser,`(function(){const e=document.querySelector(${JSON.stringify(selector)});if(!e)return false;e.scrollIntoView({block:'center'});e.focus();return document.activeElement===e;})()`);if(!exists)return false;await press(browser,key);return true;}
+
+export async function inspectExplainerBrowser(browser,options) {
+  if (browser.resetPage) await browser.resetPage();
+  const interactionErrors=[];
+  const session=await browser.sessionPromise;
+  const stop=browser.cdp.subscribe?.(message=>{if(message.sessionId!==session)return;if(message.method==='Runtime.exceptionThrown')interactionErrors.push(message.params.exceptionDetails.exception?.description||message.params.exceptionDetails.text);if(message.method==='Runtime.consoleAPICalled'&&message.params.type==='error')interactionErrors.push(message.params.args.map(a=>a.value??a.description).join(' '));});
+  try {
+  const clear=await browser.cdp.send('Page.addScriptToEvaluateOnNewDocument',{source:'try {localStorage.clear();} catch {}'},session);
+  let metrics;try{metrics=await inspectPublicHtml(browser,options);}finally{await browser.cdp.send('Page.removeScriptToEvaluateOnNewDocument',{identifier:clear.identifier},session);}
+  const failures=[];
+  const check=(name,ok,reason,component='reader',measurement)=>{if(!ok)failures.push({name,reason,component,...(measurement?{measurement}:{})});};
+  const diagram=await evaluate(browser,"document.querySelector('[data-block-type=steps] [data-diagram-link]')?.dataset.diagramLink || document.querySelector('[data-diagram-link]')?.dataset.diagramLink || document.querySelector('[data-open-diagram]')?.dataset.openDiagram || null");
+  if(diagram) {
+    const selector=await evaluate(browser,"document.querySelector('[data-block-type=steps] [data-diagram-link]')?'[data-block-type=steps] [data-diagram-link]':document.querySelector('[data-diagram-link]')?'[data-diagram-link]':'[data-open-diagram]'");
+    check('diagram-keyboard',await activate(browser,selector),'Diagram link cannot be activated by keyboard.',diagram);
+    for(let attempt=0;attempt<30;attempt++) {if(await evaluate(browser,"Boolean(document.querySelector('#diagram-dialog')?.dataset.nativeFocus)"))break;await new Promise(resolve=>setTimeout(resolve,100));}
+    const frame=await evaluate(browser,"(function(){const d=document.querySelector('#diagram-dialog'),f=d.querySelector('iframe');return {open:d.open,frame:Boolean(f),sandbox:f?.getAttribute('sandbox'),loaded:d.dataset.nativeLoaded,ready:d.dataset.nativeReady,loadingHidden:d.querySelector('.dialog-loading')?.hidden,visible:document.visibilityState,frameRect:f?{width:f.getBoundingClientRect().width,height:f.getBoundingClientRect().height}:null,error:d.querySelector('.dialog-loading')?.textContent};})()");
+    check('diagram-viewer',frame.open&&frame.frame,'Diagram activation did not open the canonical Viewer.',diagram,frame);
+    const focus=await evaluate(browser,`(function(){const link=document.querySelector(${JSON.stringify(selector)}),hash=link.dataset.diagramHash||'',edges=JSON.parse(link.dataset.diagramEdges||'[]'),bundle=JSON.parse(document.getElementById('archify-explainer-prepared').textContent),child=bundle.preparedDiagrams.diagrams[link.dataset.diagramLink||link.dataset.openDiagram],nodes=hash.startsWith('focus=')?[decodeURIComponent(hash.slice(6))]:hash.startsWith('route=')?hash.slice(6).split('~').map(decodeURIComponent):[...new Set((child.semantic?.edges||[]).filter(e=>edges.includes(e.id)).flatMap(e=>[e.from,e.to]))];let actual;try{actual=JSON.parse(document.querySelector('#diagram-dialog').dataset.nativeFocus||'null');}catch{}return {component:link.closest('[data-block-type]')?.id||link.dataset.diagramLink,nodes,edges,actual,frame:{ready:document.querySelector('#diagram-dialog').dataset.nativeReady,loaded:document.querySelector('#diagram-dialog').dataset.nativeLoaded,loadingHidden:document.querySelector('#diagram-dialog .dialog-loading').hidden}};})()`);
+    const native=await inspectNativeViewer(browser);
+    metrics.nativeViewer=native;
+    interactionErrors.push(...native.errors);
+    if(focus.nodes.length||focus.edges.length)check('diagram-focus',native.available&&native.ready==='complete'&&native.hasViewer&&Boolean(native.active)&&focus.nodes.length===native.nodes?.length&&focus.nodes.every(id=>native.nodes?.includes(id))&&(!focus.edges.length||focus.edges.length===native.edges?.length)&&focus.edges.every(id=>native.edges?.includes(id)),'The canonical Viewer did not focus the step’s exact nodes and edges.',focus.component,{...focus,dialog:frame,native});
+    await press(browser,'Escape');
+  }
+  const nativeText=await inspectNativePreviewLayout(browser);
+  for(const entry of nativeText){check('diagram-fit',entry.fit!=='insufficient'&&entry.scrollWidth<=entry.clientWidth+1&&entry.outsidePreview.length===0,'The native preview cannot fit its complete graph at the required text size.',entry.component,entry);check('diagram-text',entry.minimum!==null&&entry.minimum>=10&&(options.width<1440||entry.ratio>=0.75),'Native diagram text is below its viewport reading floor (10px; 75% of body at 1440).',entry.component,entry);}
+  metrics.nativeText=nativeText;
+  metrics.interactionFailures=failures;
+  const noJavaScript=[];
+  for(const theme of ['light','dark']) {if(browser.resetPage)await browser.resetPage();noJavaScript.push({theme,metrics:await inspectPublicHtml(browser,{...options,theme,javascript:false,keyboard:false,screenshotPath:undefined})});}
+  if(browser.resetPage)await browser.resetPage();
+  const print=await inspectPublicHtml(browser,{...options,theme:'light',media:'print',keyboard:false,screenshotPath:undefined});
+  metrics.noJavaScript=noJavaScript.map(({theme,metrics:entry})=>({theme,ok:entry.panels.length>0&&entry.panels.every(p=>p.visible&&p.text.trim())&&entry.staticReading.every(p=>p.visible&&p.text)&&entry.interactiveVisible.length===0&&noJavaScript[0].metrics.background!==noJavaScript[1].metrics.background,panels:entry.panels,interactiveVisible:entry.interactiveVisible,background:entry.background,measurementMethod:entry.measurementMethod,fontReadiness:entry.fontReadiness}));
+  const typical=await evaluate(browser,"({links:Array.from(document.querySelectorAll('.typical-ref')).map(e=>e.getAttribute('href')),notes:Array.from(document.querySelectorAll('.typical-footnotes li')).map(e=>({id:e.id,text:e.textContent,visible:getComputedStyle(e).display!=='none'&&e.getBoundingClientRect().height>0}))})");
+  metrics.print={ok:print.panels.length>0&&print.panels.every(p=>p.visible&&p.text.trim())&&print.interactiveVisible.length===0&&print.staticReading.every(p=>p.visible&&p.text)&&typical.links.every(link=>typical.notes.some(note=>link==='#'+note.id&&note.visible&&note.text.trim())),panels:print.panels,interactiveVisible:print.interactiveVisible,typical,measurementMethod:print.measurementMethod,fontReadiness:print.fontReadiness};
+  metrics.consoleErrors=[...new Set([...metrics.consoleErrors,...interactionErrors,...noJavaScript.flatMap(x=>x.metrics.consoleErrors),...print.consoleErrors])];
+  return metrics;
+  } finally {stop?.();}
+}
+
+export function explainerObservation({width,height,theme,metrics}) {
+  const overflowX=metrics.scrollWidth>metrics.innerWidth+1||metrics.overflowElements.length>0;
+  return {...metrics,width,height,theme,overflowX,overflowY:metrics.scrollHeight>metrics.innerHeight,verticalScrollAccepted:!overflowX,ok:!overflowX,readabilityOk:metrics.smallText.length===0,viewerChromeOk:metrics.occluded.length===0};
+}
+export function explainerObservationDiagnostics({artifact,allObservations}) {
+  const diagnostics=[];
+  let locations=new Map(),sourceInput;
+  try {
+    const parsed=scanHtml(fs.readFileSync(artifact,'utf8'));
+    locations=new Map(parsed.elements.filter(e=>e.attrs.id).map(e=>[e.attrs.id,e.line]));
+    const payload=parsed.scripts.find(s=>s.attrs.id==='archify-explainer-prepared');
+    if(payload) {const bundle=JSON.parse(payload.text);sourceInput=bundle.sourcePath;bundle.document.panels.forEach((panel,index)=>{locations.set(panel.id,bundle.sourceMap?.[`/panels/${index}`]?.line||locations.get(panel.id)||1);panel.blocks.forEach((block,j)=>locations.set(block.id,bundle.sourceMap?.[`/panels/${index}/blocks/${j}`]?.line||locations.get(block.id)||1));});}
+  }catch{}
+  for(const entry of allObservations) {
+    const failures=[...(entry.overflowX?[{name:'horizontal-overflow',reason:'Rendered content exceeds the horizontal viewport.',component:entry.overflowElements[0]?.component || 'document'}]:[]),...entry.keyboardIssues.map(x=>({name:'keyboard',...x})),...(entry.keyboardTraversal&&!entry.keyboardTraversal.ok?entry.keyboardTraversal.missing.map(m=>({name:'keyboard-traversal',reason:`${m.reason} ${m.tag} ${m.label}`,component:m.component})):[]),...entry.consoleErrors.map(reason=>({name:'console-error',reason,component:'reader'})),...entry.references.map(x=>({name:'reference',reason:`Unresolved reference ${x.href}.`,component:x.component})),...entry.duplicateIds.map(id=>({name:'duplicate-id',reason:`Duplicate DOM ID ${id}.`,component:'document'})),...entry.smallText.map(x=>({name:'readability',reason:`Rendered text is ${x.fontSize}px, below 10px.`,component:x.component})),...entry.occluded.map(x=>({name:'control-occluded',reason:'Another element covers an active control.',component:x.component})),...(entry.interactionFailures || []),...entry.noJavaScript.filter(x=>!x.ok).map(x=>({name:'no-javascript',reason:`Static reading content or inactive controls fail with JavaScript disabled (${x.theme}).`,component:'document'})),...(!entry.print.ok?[{name:'print',reason:'Print hides necessary reading content or displays inactive controls.',component:'document'}]:[])];
+    if(entry.resolvedTheme!==entry.theme)failures.push({name:'theme',reason:`Requested ${entry.theme}; resolved ${entry.resolvedTheme}.`,component:'theme'});
+    for(const fail of failures)diagnostics.push({code:`explainer/browser-${fail.name}`,severity:'error',message:fail.reason,subject:{artifact,...(sourceInput?{input:sourceInput}:{}),line:locations.get(fail.component)||1,component:fail.component,viewport:{width:entry.width,height:entry.height,theme:entry.theme}},evidence:{reason:fail.reason,example:repairExample(fail.name),...(fail.measurement?{measurement:fail.measurement}:{})},supportedFixes:[repairExample(fail.name)]});
+  }
+  return diagnostics;
+}
+function repairExample(name) {return name==='horizontal-overflow'?'Use min-width:0 and bounded horizontal scrolling for tables or code.':name.startsWith('keyboard')?'Use a native button/link/input with visible focus and keyboard activation.':name==='no-javascript'||name==='print'?'Keep canonical content visible and hide interactive controls in no-JavaScript and print styles.':name==='diagram-text'?'Increase the diagram panel span until projected node text reaches 75% of body text.':'Repair the reported component and re-render the source.';}

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

@@ -0,0 +1,70 @@
+import { PeleError, detectType, register, render } from './vendor/pele/core.js';
+import pie from './vendor/pele/diagrams/pie.js';
+import xychart from './vendor/pele/diagrams/xychart.js';
+import quadrantChart from './vendor/pele/diagrams/quadrantChart.js';
+import sankey from './vendor/pele/diagrams/sankey.js';
+import radar from './vendor/pele/diagrams/radar.js';
+import venn from './vendor/pele/diagrams/venn.js';
+
+register(pie, xychart, quadrantChart, sankey, radar, venn);
+
+const NATIVE = { flowchart: 'workflow or architecture', sequence: 'sequence', class: 'class', er: 'erd', state: 'lifecycle', timeline: 'timeline', gantt: 'timeline or waterfall', mindmap: 'tree', treeview: 'tree' };
+
+// A pie legend reads "Label · value (share%)" rather than Pele's "Label [value]". The labels are
+// rewritten before rendering so the legend is laid out for their real width.
+function pieLegend(text) {
+  if (!/^\s*pie\b/u.test(text)) return text;
+  const slice = /^(\s*)"((?:[^"\\]|\\.)*)"\s*:\s*(-?\d+(?:\.\d+)?)\s*$/gmu;
+  const total = [...text.matchAll(slice)].reduce((sum, match) => sum + Number(match[3]), 0);
+  if (!(total > 0)) return text;
+  return text.replace(/^(\s*pie)\s+showData\b/u, '$1').replace(slice, (_, indent, label, value) => { const share = Math.round(Number(value) / total * 100); return `${indent}"${label} · ${value}${/\p{Script=Han}/u.test(label) ? `（${share}%）` : ` (${share}%)`}" : ${value}`; });
+}
+
+/** Render a Mermaid chart to static SVG, or return a located diagnostic reason. */
+export function compileExplainerChart(text) {
+  const type = detectType(text);
+  if (type && NATIVE[type]) return { error: `Mermaid ${type} is drawn with the native ${NATIVE[type]} shorthand, which Archify validates and lets readers explore.`, example: `@${NATIVE[type].split(' ')[0]} id=...` };
+  try {
+    const result = render(pieLegend(text), { padding: 8, fontSize: 13, links: false, images: false, config: { xyChart: { width: 480, height: 260, showDataLabel: true }, quadrantChart: { chartWidth: 400, chartHeight: 400 } } });
+    // A rotated CJK axis title lies on its side; vertical writing keeps the characters upright.
+    const svg = result.svg.replace(/<g transform="translate\(([\d.-]+),([\d.-]+)\) rotate\(-90\)"><text x="0" y="[\d.-]+" text-anchor="middle">([^<]*\p{Script=Han}[^<]*)<\/text><\/g>/gu, (_, x, y, label) => `<text x="${x}" y="${y}" text-anchor="middle" writing-mode="vertical-rl">${label}</text>`);
+    return { svg, width: result.width, height: result.height, type: result.type };
+  } catch (error) {
+    if (!(error instanceof PeleError)) throw error;
+    const supported = 'pie, xychart-beta (bar and line), quadrantChart, sankey-beta, radar-beta or venn-beta';
+    return { error: error.code === 'unsupported-diagram' ? `A chart fence supports ${supported}.` : error.message.split('\n')[0], line: error.line, example: 'pie title Share\n  "A" : 60\n  "B" : 40' };
+  }
+}
+
+// A data file becomes chart text: CSV with a header row, or JSON as an array of objects. Labels come
+// from column x and one series from each column in y; a pie takes the first y column as its values.
+export function chartFromData(bytes, filePath, { kind, x, y, unit }) {
+  let rows;
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/^\uFEFF/u, '');
+  if (/\.json$/iu.test(filePath)) {
+    try { rows = JSON.parse(text); } catch { return { error: 'The data file is not valid JSON.' }; }
+    if (!Array.isArray(rows) || !rows.every(row => row && typeof row === 'object' && !Array.isArray(row))) return { error: 'JSON chart data must be an array of objects.' };
+  } else {
+    const cells = line => { const out = []; let cell = '', quoted = false; for (let i = 0; i < line.length; i++) { const c = line[i]; if (quoted) { if (c === '"' && line[i + 1] === '"') { cell += '"'; i++; } else if (c === '"') quoted = false; else cell += c; } else if (c === '"') quoted = true; else if (c === ',') { out.push(cell.trim()); cell = ''; } else cell += c; } out.push(cell.trim()); return out; };
+    const lines = text.split(/\r?\n/u).filter(line => line.trim());
+    if (lines.length < 2) return { error: 'CSV chart data needs a header row and at least one data row.' };
+    const header = cells(lines[0]);
+    rows = lines.slice(1).map(line => Object.fromEntries(cells(line).map((value, i) => [header[i], value])));
+  }
+  const columns = new Set(rows.flatMap(row => Object.keys(row)));
+  const missing = [x, ...y].find(column => !columns.has(column));
+  if (missing) return { error: `The data file has no column "${missing}". Columns: ${[...columns].join(', ')}.` };
+  if (rows.length > (kind === 'pie' ? 12 : 60)) return { error: `A ${kind} chart takes at most ${kind === 'pie' ? 12 : 60} rows; this file has ${rows.length}.` };
+  const quote = value => `"${String(value).replace(/["\\]/gu, '')}"`;
+  // A blank cell is missing data, not zero: Number('') is 0, so blanks are rejected before conversion.
+  const blank = value => value === undefined || value === null || String(value).trim() === '';
+  const numbers = column => rows.map(row => blank(row[column]) ? NaN : Number(String(row[column]).replace(/,/gu, '')));
+  for (const column of y) {
+    const bad = numbers(column).findIndex(value => !Number.isFinite(value));
+    if (bad < 0) continue;
+    if (blank(rows[bad][column])) return { error: `Column "${column}" is empty in data row ${bad + 1}. A blank is missing data, not zero: fill in the value, or leave the row out and say so in the caption.` };
+    return { error: `Column "${column}" has a non-numeric value in data row ${bad + 1}: ${rows[bad][column]}.` };
+  }
+  if (kind === 'pie') { const values = numbers(y[0]); return { text: `pie\n${rows.map((row, i) => `  ${quote(row[x])} : ${values[i]}`).join('\n')}` }; }
+  return { text: `xychart-beta\n  x-axis [${rows.map(row => quote(row[x])).join(', ')}]\n${unit ? `  y-axis ${quote(unit)}\n` : ''}${y.map(column => `  ${kind} ${quote(column)} [${numbers(column).join(', ')}]`).join('\n')}` };
+}

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

@@ -0,0 +1,168 @@
+import { runtimeArgs } from '../renderers/shared/bun-runtime.mjs';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseExplainer } from './parse.mjs';
+import { computeExplainerRevision } from './revision.mjs';
+import { unpackPageBundle } from './page-bundle.mjs';
+
+export const isExplainerHtml = html => /<html\b[^>]*\bdata-archify-artifact\s*=\s*["']explainer["']/i.test(html) || (html.includes('archify-explainer-prepared') && scanHtml(html).scripts.some(s=>s.attrs.id==='archify-explainer-prepared'));
+const hash = value => createHash('sha256').update(value).digest('hex');
+const decode = value => value.replace(/&(?:amp|lt|gt|quot|apos|#39|#x[0-9a-f]+|#\d+);/gi, token => {
+  const names = {'&amp;':'&','&lt;':'<','&gt;':'>','&quot;':'"','&apos;':"'",'&#39;':"'"};
+  if (names[token.toLowerCase()]) return names[token.toLowerCase()];
+  const n = token[2].toLowerCase() === 'x' ? parseInt(token.slice(3,-1),16) : Number(token.slice(2,-1));
+  return n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '\uFFFD';
+});
+
+// Bounded HTML token scanner: quoted attributes, comments, and raw-text elements
+// are consumed together, so a JSON string containing markup is never a DOM ID.
+export function scanHtml(html) {
+  const elements = [];
+  const scripts = [];
+  const token = /<!--[\s\S]*?(?:-->|$)|<![^>]*>|<(\/?)([a-z][\w:-]*)(?=[\s/>])(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
+  let match, line = 1, lineOffset = 0;
+  while ((match = token.exec(html))) {
+    if (!match[2] || match[1]) continue;
+    const tag = match[2].toLowerCase();
+    const attrs = {};
+    const attr = /([^\s=<>"'`/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+    const raw = match[0].slice(match[0].indexOf(match[2]) + match[2].length, -1);
+    let a;
+    while ((a = attr.exec(raw))) attrs[a[1].toLowerCase()] = decode(a[2] ?? a[3] ?? a[4] ?? '');
+    // Advance once through the input, including skipped raw text, instead of
+    // recounting every preceding line for each element of a large native SVG.
+    for (let newline = html.indexOf('\n', lineOffset); newline >= 0 && newline < match.index; newline = html.indexOf('\n', newline + 1)) line++;
+    lineOffset = match.index;
+    const element = {tag,attrs,line,index:match.index};
+    elements.push(element);
+    if (['script','style','textarea','title'].includes(tag)) {
+      const end = new RegExp(`</${tag}\\s*>`,'gi');
+      end.lastIndex = token.lastIndex;
+      const closing = end.exec(html);
+      const text = html.slice(token.lastIndex, closing?.index ?? html.length);
+      if (tag === 'script') scripts.push({...element,text});
+      token.lastIndex = closing ? end.lastIndex : html.length;
+    }
+  }
+  return {elements,scripts};
+}
+
+export function checkExplainerHtml(html, { file = '<html>', checkNative = true } = {}) {
+  const bytes = Buffer.from(html);
+  const {elements,scripts} = scanHtml(html);
+  const diagnostics = [];
+  const checks = [];
+  const issue = (code,reason,example,element,component='document') => diagnostics.push({
+    code:`explainer/${code}`,severity:'error',message:reason,
+    subject:{input:file,line:element?.line || 1,component,...(element?.attrs?.id ? {id:element.attrs.id} : {})},
+    evidence:{reason,example},supportedFixes:[example],
+  });
+  const add = (name, before, details=[]) => checks.push({name,ok:diagnostics.length===before,details});
+  let before = diagnostics.length;
+  if (elements.find(e=>e.tag==='html')?.attrs['data-archify-artifact']!=='explainer') issue('artifact-family','The document is missing its explainer family marker.','<html data-archify-artifact="explainer">');
+  const ids = new Map();
+  for (const e of elements) {
+    if (e.attrs.id) {
+      if (ids.has(e.attrs.id)) issue('duplicate-id',`Duplicate DOM ID: ${e.attrs.id}.`,'Give each panel, block, source and SVG preview a unique stable ID.',e);
+      ids.set(e.attrs.id,e);
+    }
+    if (Object.keys(e.attrs).some(key=>/^on/.test(key))) issue('inline-handler','Inline event attributes are not permitted.','Use the packaged reader event handlers.',e);
+    if (e.tag === 'script' && e.attrs.src) issue('external-runtime','The explainer runtime must be self-contained.','Embed the packaged reader script.',e);
+    if (['iframe','object','embed'].includes(e.tag)) issue('external-frame','Frames must be created from immutable native payloads on demand.','Keep a static native SVG preview and the frozen child HTML payload.',e);
+    for (const attr of ['href','src','xlink:href']) {
+      const value=e.attrs[attr];
+      if (!value) continue;
+      if (/^(?:javascript|vbscript):/i.test(value)) issue('unsafe-url','An executable URL is not allowed.','Use an https URL or a stable #anchor.',e);
+      if (value.startsWith('#') && !ids.has(decodeURIComponentSafe(value.slice(1)))) { /* resolved after all IDs */ }
+    }
+    if (e.tag==='img' && !/^data:image\/(?:png|jpeg|webp|gif);base64,/i.test(e.attrs.src || '')) issue('external-image','Images must contain their frozen local bytes.','Use a prepared local image with a data:image URL.',e,'image');
+  }
+  for (const e of elements) {
+    if (e.attrs.href?.startsWith('#') && e.attrs.href.length>1 && !ids.has(decodeURIComponentSafe(e.attrs.href.slice(1)))) issue('unresolved-reference',`Unresolved anchor: ${e.attrs.href}.`,'Link to an existing panel, block or source ID.',e,'reference');
+  }
+  add('explainer_structure',before,[`${ids.size} unique DOM IDs`]);
+  function payload(id) {
+    const found=scripts.filter(s=>s.attrs.id===id);
+    if (found.length!==1 || found[0].attrs.type!=='application/json') { issue('payload',`Expected one application/json payload: ${id}.`,`<script type="application/json" id="${id}">…</script>`,found[0]); return null; }
+    if (/[<>&\u2028\u2029]/.test(found[0].text)) issue('payload-escaping',`Unsafe raw characters in ${id}.`,'Escape <, >, &, U+2028 and U+2029 as JSON Unicode escapes.',found[0]);
+    try { return JSON.parse(found[0].text); } catch { issue('payload-json',`Invalid JSON payload: ${id}.`,'Re-render the validated source instead of editing embedded payloads.',found[0]); return null; }
+  }
+  before=diagnostics.length;
+  let bundle=payload('archify-explainer-prepared');
+  try { bundle=unpackPageBundle(bundle); } catch { issue('native-hash','A compressed native diagram payload cannot be inflated.','Re-render the native diagram and freeze its original HTML bytes.'); bundle=null; }
+  const document=bundle?.document;
+  const source=bundle ? {text:bundle.sourceText} : null;
+  const manifest=payload('explainer-manifest');
+  const children=bundle?.preparedDiagrams?.diagrams;
+  if (bundle && (bundle.kind!=='archify-explainer-prepared' || bundle.schemaVersion!==1 || hash(JSON.stringify({...bundle,digest:undefined}))!==bundle.digest)) issue('bundle-hash','The canonical prepared bundle does not match its digest.','Re-prepare and render the original draft with immutable resources.');
+  if (bundle && typeof bundle.sourceText==='string') {
+    const parsed=parseExplainer(bundle.sourceText,{inputPath:bundle.sourcePath,output:document?.meta?.output});
+    if (!parsed.document || parsed.diagnostics.some(d=>d.severity!=='warning') || JSON.stringify(parsed.document)!==JSON.stringify(document)) issue('source-document-binding','The canonical document differs from its embedded authored draft.','Re-parse the embedded draft and render its normalized document.');
+    if (bundle.source?.sha256!==hash(bundle.sourceText) || bundle.source?.bytes!==Buffer.byteLength(bundle.sourceText)) issue('bundle-source-hash','The prepared source bytes do not match their identity.','Freeze the exact original UTF-8 draft bytes.');
+  }
+  if (document && manifest && source) {
+    if (document.diagram_type!=='explainer' || document.schema_version!==1 || !Array.isArray(document.panels) || !Array.isArray(document.sources)) issue('canonical-document','The canonical explainer envelope is invalid.','Use schema_version:1, diagram_type:"explainer", panels:[] and sources:[].');
+    if (typeof source.text!=='string' || hash(source.text || '')!==manifest.sourceSha256) issue('source-hash','The embedded source does not match its immutable source hash.','Re-render the original draft and retain its exact SHA-256 source hash.');
+    try {
+      if (manifest.revision!==computeExplainerRevision(bundle)) issue('content-revision','The content revision does not bind the draft and frozen resources.','Recompute the revision from the canonical draft, source locations, child diagrams and contained assets.');
+    } catch {issue('content-revision','The content revision cannot be computed from invalid frozen resources.','Re-prepare the original draft and every declared resource.');}
+    if (hash(JSON.stringify(document))!==manifest.documentSha256) issue('document-hash','The canonical document does not match its manifest hash.','Re-render after changing the canonical document.');
+    if (manifest.artifactId!==document.meta?.id || elements.find(e=>e.tag==='html')?.attrs['data-revision']!==manifest.revision) issue('artifact-identity','Artifact ID or revision disagrees with the manifest.','Use the renderer-generated identity and revision.');
+    for (const panel of document.panels || []) {
+      for (const item of [panel,...(panel.blocks || [])]) if (!ids.has(item.id)) issue('canonical-id',`Canonical ID is absent from the rendered document: ${item.id}.`,'Render every authored panel and block with its stable ID.');
+    }
+    for (const src of document.sources || []) if (!ids.has(`source-${src.id}`)) issue('source-target',`Source target is missing: ${src.id}.`,'Render every declared source in the source list.');
+  }
+  add('explainer_payload_identity',before);
+  before=diagnostics.length;
+  const dependencies=bundle?.dependencies;
+  if (manifest?.dependencies && JSON.stringify(manifest.dependencies)!==JSON.stringify((dependencies || []).map(({contentBase64,...entry})=>entry))) issue('manifest-dependencies','The compact manifest disagrees with the canonical dependency identities.','Generate dependency metadata from the canonical prepared bundle.');
+  if (!Array.isArray(dependencies)) issue('dependency-manifest','The frozen dependency manifest is missing.','Store dependencies:[] even when no external resources are used.');
+  const depIds=new Set();
+  for (const dep of dependencies || []) {
+    const key=`${dep.kind}:${dep.id}`;
+    if (depIds.has(key)) issue('dependency-duplicate',`Duplicate dependency: ${key}.`,'Freeze each resource once.');
+    depIds.add(key);
+    const frozen=typeof dep.contentBase64==='string' ? Buffer.from(dep.contentBase64,'base64') : null;
+    if (!frozen || frozen.toString('base64')!==dep.contentBase64 || !Number.isSafeInteger(dep.bytes) || dep.bytes!==frozen.length || hash(frozen)!==dep.sha256) issue('dependency-hash',`Frozen dependency identity is corrupt: ${key}.`,'Regenerate the dependency bytes, byte count and SHA-256 from the source.');
+  }
+  for (const [id,asset] of Object.entries(manifest?.assets || {})) {
+    const dep=(dependencies || []).find(d=>d.kind==='image' && d.id===id);
+    if (!dep || dep.sha256!==asset.sha256 || dep.bytes!==asset.bytes) issue('asset-binding',`Image asset is not bound to its frozen dependency: ${id}.`,'Freeze the image before rendering.');
+    const img=elements.find(e=>e.tag==='img' && e.attrs.src===`data:${asset.mime};base64,${dep?.contentBase64}`);
+    if (!img) issue('asset-content',`Rendered image bytes differ from the frozen asset: ${id}.`,'Render the frozen data URL without replacing its bytes.');
+  }
+  for (const [id,src] of Object.entries(bundle?.preparedSources?.sources || {})) if (typeof src.text==='string') {
+    const dep=(dependencies || []).find(d=>d.kind==='repository' && d.id===id);
+    if (!dep || dep.sha256!==src.sha256 || dep.bytes!==src.bytes || !/^[0-9a-f]{40}$/.test(src.revision || '') || dep.revision!==src.revision) issue('source-binding',`Code excerpt is missing pinned frozen bytes: ${id}.`,'Resolve the repository source against a full Git commit before rendering.');
+  }
+  add('explainer_dependencies',before,[`${dependencies?.length || 0} frozen dependencies`]);
+  before=diagnostics.length;
+  const childReceipts=[];
+  const expected=(document?.panels || []).flatMap(p=>p.blocks || []).filter(b=>b.type==='diagram').map(b=>b.id);
+  if (!children || typeof children!=='object' || Array.isArray(children) || expected.length!==Object.keys(children).length || expected.some(id=>!children[id])) issue('native-count','Native diagram payloads do not match canonical diagram blocks.','Embed one native payload per diagram block; zero diagrams is valid.');
+  for (const [id,child] of Object.entries(children || {})) {
+    const binding=manifest?.children?.[id];
+    if (typeof child.html!=='string' || hash(child.html || '')!==child.sha256 || Buffer.byteLength(child.html || '')!==child.bytes || binding?.sha256!==child.sha256 || binding?.bytes!==child.bytes) { issue('native-hash',`Native diagram payload is corrupt: ${id}.`,'Re-render the native diagram and freeze its original HTML bytes.',ids.get(id),'diagram'); continue; }
+    if (isExplainerHtml(child.html)) {issue('native-family',`Nested explainers are not native diagrams: ${id}.`,'Use an existing Archify native diagram type.',ids.get(id),'diagram');continue;}
+    if (checkNative) {
+      const directory=fs.mkdtempSync(path.join(os.tmpdir(),'archify-explainer-check-'));
+      try {
+        const artifactPath=path.join(directory,'child.html'); fs.writeFileSync(artifactPath,child.html);
+        const run=spawnSync(process.execPath,runtimeArgs([fileURLToPath(new URL('../scripts/check-render-output.mjs',import.meta.url)),artifactPath]),{encoding:'utf8',maxBuffer:8*1024*1024,timeout:60000});
+        let receipt; try {receipt=JSON.parse(run.stdout);} catch {receipt=null;}
+        childReceipts.push({id,receipt});
+        if (run.status!==0 || !receipt?.ok || receipt.artifact?.sha256!==child.sha256 || receipt.composition?.profile!==(bundle?.quality || document?.meta?.quality_profile || 'standard')) issue('native-check',`Native diagram failed its existing composition checks: ${id}.`,'Fix the nested diagram using the native checker diagnostics.',ids.get(id),'diagram');
+      } finally {fs.rmSync(directory,{recursive:true,force:true});}
+    }
+  }
+  add('explainer_native_diagrams',before,childReceipts.map(({id,receipt})=>`${id}: ${receipt?.ok ? 'pass':'fail'}`));
+  const profile=bundle?.quality || document?.meta?.quality_profile || 'standard';
+  const errors=diagnostics.length;
+  return {ok:errors===0,file,family:'explainer',artifact:{sha256:hash(bytes),bytes:bytes.length},checks,composition:{schemaVersion:1,profile,status:errors ? 'fail':'pass',summary:{errors,warnings:0},issues:diagnostics,nativeDiagrams:childReceipts},diagnostics};
+}
+function decodeURIComponentSafe(value) { try {return decodeURIComponent(value);} catch {return value;} }