@stacksjs/defaults 0.75.361 → 0.75.362

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

@@ -0,0 +1,300 @@
+import { createHash } from 'node:crypto';
+import { compileExplainerDiagram } from './diagrams.mjs';
+
+const TYPES = new Set(['architecture','workflow','sequence','dataflow','lifecycle','erd','class','tree','timeline','waterfall']);
+const ID = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const stable = (kind, value) => `${kind}-${createHash('sha256').update(value).digest('hex').slice(0, 12)}`;
+const pointerKey = value => String(value).replaceAll('~','~0').replaceAll('/','~1');
+const csv = value => value ? value.split(',').map(part => part.trim()).filter(Boolean) : [];
+const rowLabel = value => {
+  const match = value.match(/^(.*?)\s+\{#([^}\s]+)\}$/u);
+  return match ? {label:match[1].trim(),id:match[2]} : {label:value};
+};
+
+/** Restricted author syntax; canonical JSON uses the same model and source locations.
+ * Failures return document:null and repairable diagnostics; no partial document is delivered.
+ * Source-map start/end values are offsets in the original JS string, not byte offsets.
+ */
+export function parseExplainer(sourceText, { inputPath, output } = {}) {
+  if (typeof sourceText !== 'string') throw new TypeError('Explainer input must be a string');
+  // The CLI owns the destination directory. Authored meta.output stays portable.
+  if (typeof output === 'string') output = output.split(/[\\/]/u).at(-1);
+  const sourceMap = Object.create(null);
+  const diagnostics = [];
+  const format = sourceText.trimStart().startsWith('{') || sourceText.trimStart().startsWith('[') ? 'json' : 'markdown';
+  const starts = [0];
+  for (let i = 0; i < sourceText.length; i++) if (sourceText[i] === '\n') starts.push(i + 1);
+  const lines = sourceText.split('\n').map(line => line.replace(/\r$/, ''));
+  function locate(start, end = start) {
+    let lo = 0, hi = starts.length;
+    while (lo + 1 < hi) { const mid = (lo + hi) >> 1; if (starts[mid] <= start) lo = mid; else hi = mid; }
+    return {line:lo + 1,column:start - starts[lo] + 1,start,end};
+  }
+  function map(pointer, value, descriptor) {
+    sourceMap[pointer] = {...descriptor};
+    if (Array.isArray(value)) value.forEach((entry,index) => map(`${pointer}/${index}`,entry,descriptor));
+    else if (value && typeof value === 'object') Object.entries(value).forEach(([key,entry]) => map(`${pointer}/${pointerKey(key)}`,entry,descriptor));
+  }
+  function fail(line, component, reason, example, path = '/') {
+    diagnostics.push({code:`explainer/parse-${component}`,severity:'error',message:reason,
+      subject:{line,column:1,component,path,...(inputPath ? {input:inputPath} : {})},
+      evidence:{reason,example},supportedFixes:[`Use the documented syntax, for example: ${example}`]});
+  }
+  function unsupported(text, line, component) {
+    if (/^\s*(?:>{1,}|#{3,}\s|(?:---|\*\*\*|___)\s*$|```|~~~|[-*+]\s+\[[ xX]\])/u.test(text)) fail(line,component,'This Markdown block is outside the restricted author grammar.','## What happens?\nA short paragraph.');
+  }
+  let document;
+  if (format === 'json') {
+    try {
+      document = JSON.parse(sourceText);
+      // Scan the already parsed JSON to preserve exact nested value locations and detect
+      // duplicate keys, which JSON.parse silently overwrites. No eval or JSON rewriting.
+      let pos = 0;
+      const skip = () => { while (/\s/u.test(sourceText[pos] || '') && pos < sourceText.length) pos++; };
+      const stringEnd = () => { const start = pos++; while (pos < sourceText.length) { const c = sourceText[pos++]; if (c === '\\') pos++; else if (c === '"') break; } return JSON.parse(sourceText.slice(start,pos)); };
+      function scan(pointer) {
+        skip(); const start = pos;
+        if (sourceText[pos] === '{') {
+          pos++; skip(); const keys = new Set();
+          while (sourceText[pos] !== '}') {
+            skip(); const keyStart = pos; const key = stringEnd();
+            if (keys.has(key)) fail(locate(keyStart).line,'json','Duplicate JSON keys would discard authored content.','Use each object key once.',`${pointer}/${pointerKey(key)}`);
+            keys.add(key); skip(); pos++; scan(`${pointer}/${pointerKey(key)}`); skip(); if (sourceText[pos] === ',') pos++; else break;
+          }
+          pos++;
+        } else if (sourceText[pos] === '[') {
+          pos++; skip(); let index = 0;
+          while (sourceText[pos] !== ']') { scan(`${pointer}/${index++}`); skip(); if (sourceText[pos] === ',') pos++; else break; }
+          pos++;
+        } else if (sourceText[pos] === '"') stringEnd();
+        else { while (pos < sourceText.length && !/[\s,\]}]/u.test(sourceText[pos])) pos++; }
+        sourceMap[pointer] = locate(start,pos);
+      }
+      scan('');
+      if (document && !Array.isArray(document) && typeof document === 'object') {
+        if (document.meta && typeof document.meta === 'object' && output) document.meta.output = output;
+      }
+    } catch (error) {
+      const match = String(error.message).match(/position (\d+)/u);
+      const lineMatch = String(error.message).match(/line (\d+)/u);
+      fail(match ? locate(Number(match[1])).line : Number(lineMatch?.[1] || 1),'json','Input is not valid JSON.','{"schema_version":1,"diagram_type":"explainer",...}');
+    }
+  } else {
+    document = {schema_version:1,diagram_type:'explainer',meta:{},answer:{summary:''},panels:[],sources:[]};
+    let panel = null, panelIndex = -1, titleSeen = false, answerSeen = false, reasonsAllowed = false, cursor = 0;
+    const descriptor = (line, endLine = line + 1) => locate(starts[line] ?? sourceText.length, starts[endLine] ?? sourceText.length);
+    const closePanel = end => { if (panelIndex >= 0) sourceMap[`/panels/${panelIndex}`].end = end; };
+    function heading(line, prefix) {
+      const match = line.slice(prefix.length).trim().match(/^(.*?)(?:\s+\{(?:#([^}\s]+))?(?:\s*span=(\d+))?\})?$/u);
+      return {title:match[1].trim(),id:match[2],...(match[3]?{span:Number(match[3])}:{})};
+    }
+    function addBlock(block, at, until, rows = []) {
+      if (!panel) { fail(at + 1,block.type,'Blocks must follow a question panel heading.','## What should I know?'); return; }
+      // A block named after its own panel points at the same place; keep both reachable instead of failing.
+      // Diagrams keep their ID because node and route links name it.
+      if (block.id && block.id === panel.id && block.type !== 'diagram') block.id = `${panel.id}-${block.type}`;
+      block.id ||= stable(block.type,`${panel.id}\0${JSON.stringify(block)}`);
+      if (block.type === 'comparison') for (const row of block.rows) row.id ||= stable('row', `${block.id}\0${row.label}`);
+      const pointer = `/panels/${panelIndex}/blocks/${panel.blocks.length}`;
+      panel.blocks.push(block); map(pointer,block,descriptor(at,until));
+      const property = {facts:'entries',comparison:'rows',steps:'items',list:'items'}[block.type];
+      if (property) rows.forEach((row,index) => { if (block[property]?.[index] !== undefined) map(`${pointer}/${property}/${index}`,block[property][index],descriptor(row.line,row.line+1)); });
+    }
+    function cells(raw, line) {
+      const trimmed = raw.trim();
+      let value = trimmed.startsWith('|') ? trimmed.slice(1) : trimmed;
+      if (value.endsWith('|') && !/(^|[^\\])(\\\\)*\\\|$/u.test(value)) value = value.slice(0,-1);
+      const result = []; let cell = '', code = false;
+      for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        if (char === '\\' && ['|','\\'].includes(value[i+1])) { cell += value[++i]; continue; }
+        if (char === '`') code = !code;
+        if (char === '|' && !code) { result.push(cell.trim()); cell = ''; } else cell += char;
+      }
+      result.push(cell.trim());
+      if (code) fail(line + 1,'rows','Unclosed inline code in a table row.','| label | `literal` |');
+      return result;
+    }
+    function attributes(raw,line) {
+      const attrs = Object.create(null), positional = []; let pos = 0;
+      while (pos < raw.length) {
+        while (/\s/u.test(raw[pos] || '') && pos < raw.length) pos++;
+        if (pos >= raw.length) break;
+        const token = raw.slice(pos).match(/^([^\s=]+)(=)?/u);
+        if (!token) { fail(line + 1,'directive','Malformed directive arguments.','@metric label="Latency" value=12 unit=ms'); break; }
+        const key = token[1]; pos += token[0].length;
+        if (!token[2]) { positional.push(key); continue; }
+        let value = '';
+        if (raw[pos] === '"' || raw[pos] === "'") {
+          const quote = raw[pos++]; let closed = false;
+          while (pos < raw.length) { const c = raw[pos++]; if (c === quote) { closed = true; break; } if (c === '\\' && [quote,'\\'].includes(raw[pos])) value += raw[pos++]; else value += c; }
+          if (!closed) fail(line + 1,'directive','Quoted directive value is not closed.','title="A short title"');
+          if (pos < raw.length && !/\s/u.test(raw[pos])) fail(line+1,'directive','Arguments must be separated by whitespace.','label="Latency" value=12');
+        } else { const start = pos; while (pos < raw.length && !/\s/u.test(raw[pos])) pos++; value = raw.slice(start,pos); }
+        if (Object.hasOwn(attrs,key)) fail(line+1,'directive','Duplicate arguments would discard authored content.','Use each key once.');
+        attrs[key] = value;
+      }
+      return {attrs,positional};
+    }
+    function rowWidth(rows,min,max,component) {
+      for (const row of rows) if (row.cells.length < min || row.cells.length > max) fail(row.line+1,component,`Expected ${min === max ? min : `${min}–${max}`} cells in this directive row.`,`| ${Array.from({length:min},(_,i)=>`field${i+1}`).join(' | ')} |`);
+    }
+    function boolean(value, at, component) {
+      if (value === undefined) return undefined;
+      if (!['true','false'].includes(value)) fail(at+1,component,'Boolean arguments require true or false.','multiple=true');
+      return value === 'true';
+    }
+    function number(value, at, component) {
+      if (value === undefined) return undefined;
+      if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/iu.test(value) || !Number.isFinite(Number(value))) fail(at+1,component,'Numeric arguments require a finite number.','value=12.5');
+      return Number(value);
+    }
+    function select(attrs, keys) { return Object.fromEntries(keys.filter(key => attrs[key] !== undefined).map(key=>[key,attrs[key]])); }
+    function directive(at) {
+      const match = lines[at].trim().match(/^@([a-z][a-z-]*)(?:\s+(.*))?$/u);
+      if (!match) { fail(at+1,'directive','Malformed type directive.','@facts\n| key | value |'); cursor++; return; }
+      let type = match[1]; const {attrs:a,positional} = attributes(match[2] || '',at);
+      if (TYPES.has(type)) { positional.unshift(type); type='diagram'; }
+      cursor = at + 1; const rows=[]; let literal;
+      let literalStart;
+      if (type === 'diff' && /^```diff\s*$/u.test(lines[cursor]?.trim() || '')) {
+        cursor++; const begin=cursor; literalStart=begin; while (cursor<lines.length && lines[cursor].trim()!=='```') cursor++;
+        if (cursor===lines.length) fail(at+1,'diff','The diff fence is not closed.','@diff\n```diff\n-old\n+new\n```');
+        const end=starts[cursor] ?? sourceText.length;
+        literal=sourceText.slice(starts[begin] ?? sourceText.length,end).replace(/\r?\n$/u,''); if (cursor<lines.length) cursor++;
+      } else {
+        // A directive row never starts with an empty cell; "|| id |" is a line-number prefix copied from a file viewer.
+        while (cursor<lines.length && lines[cursor].trim() && !/^(?:#{1,2}\s|@)/u.test(lines[cursor].trim())) { rows.push({cells:cells(lines[cursor].replace(/^(\s*)\|\|(?=\s)/u,'$1|'),cursor),line:cursor}); cursor++; }
+        // A callout with no rows takes the plain paragraph that follows it as its text.
+        if (type==='callout' && !rows.length && a.text===undefined) {
+          let next=cursor; while (next<lines.length && !lines[next].trim()) next++;
+          const paragraph=[]; while (next<lines.length && lines[next].trim() && !/^(?:#{1,2}\s|@|\||[-*+]\s|\d+\.\s|```|~~~)/u.test(lines[next].trim())) { paragraph.push({cells:[lines[next].trim()],line:next}); next++; }
+          if (paragraph.length) { rows.push(...paragraph); cursor=next; }
+        }
+      }
+      const allowed = {
+        source:['title','url','path','lines','revision'],meta:['locale','quality_profile','style','repo_url','repo_revision','repo_provider','repo_link_mode'],answer:['scope'],
+        prose:['id','text'],list:['id','ordered'],callout:['id','level','title','text'],facts:['id'],metric:['id','label','value','limit','unit','note','typical'],steps:['id'],diagram:['id','source','spec','title','changes'],code:['id','source','language'],diff:['id','caption'],image:['id','path','alt','caption'],comparison:['id','columns','label'],chart:['id','title','type','data','x','y','unit']
+      }[type];
+      if (!allowed) { fail(at+1,'directive',`Unsupported component @${type}.`,'@facts\n| key | value |'); return; }
+      for (const key of Object.keys(a)) if (!allowed.includes(key)) fail(at+1,type,`Unsupported argument ${key}.`,`@${type} ${allowed.map(key=>`${key}=...`).join(' ')}`);
+      if (!['source','diagram'].includes(type) && positional.length) fail(at+1,type,'This directive accepts key=value arguments only.',`@${type} id=stable-id`);
+      if (['meta','answer'].includes(type) && rows.length) fail(rows[0].line+1,type,'This directive accepts header arguments only.','@meta locale=en quality_profile=showcase');
+      if (type==='source') {
+        if (positional.length!==1) fail(at+1,type,'Source declarations require an ID.','@source docs title="Documentation" url=https://example.com/docs');
+        const source={id:positional[0],...select(a,['title','url','path','revision'])};
+        if (a.lines!==undefined) { const range=a.lines.match(/^(\d+):(\d+)$/u); if (!range) fail(at+1,type,'Repository lines require start:end.','lines=10:20'); source.lines=range?[Number(range[1]),Number(range[2])]:[]; }
+        if(rows.length) fail(at+1,type,'Source declarations do not accept rows.','@source demo title="Timing model"');
+        const pointer=`/sources/${document.sources.length}`;document.sources.push(source);map(pointer,source,descriptor(at,cursor));return;
+      }
+      if (type==='meta') { Object.assign(document.meta,select(a,['locale','quality_profile','style'])); if(a.repo_url || a.repo_revision) document.meta.repository={url:a.repo_url,revision:a.repo_revision,...(a.repo_provider?{provider:a.repo_provider}:{}),...(a.repo_link_mode?{link_mode:a.repo_link_mode}:{})}; for(const key of ['locale','quality_profile','style','repository'])if(document.meta[key]!==undefined)map(`/meta/${key}`,document.meta[key],descriptor(at,cursor));return; }
+      if (type==='answer') { if(a.scope!==undefined){document.answer.scope=a.scope;sourceMap['/answer/scope']=descriptor(at,cursor);}return; }
+      let block={type,...(a.id?{id:a.id}:{})};
+      switch(type) {
+        case 'prose': rowWidth(rows,1,1,type);block.text=a.text??rows.map(r=>r.cells[0]).join('\n');break;
+        case 'list': rowWidth(rows,1,1,type);block.items=rows.map(r=>r.cells[0]);if(a.ordered!==undefined)block.ordered=boolean(a.ordered,at,type);break;
+        case 'callout': rowWidth(rows,1,1,type);Object.assign(block,{level:a.level||'note',...select(a,['title']),text:a.text??rows.map(r=>r.cells[0]).join('\n')});break;
+        case 'facts':rowWidth(rows,2,2,type);block.entries=rows.map(r=>({key:r.cells[0],value:r.cells[1]}));break;
+        case 'metric':Object.assign(block,select(a,['label','unit','note']));for(const key of ['value','limit'])if(a[key]!==undefined)block[key]=number(a[key],at,type);if(a.typical!==undefined)block.typical=boolean(a.typical,at,type);break;
+        case 'steps':rowWidth(rows,2,7,type);block.items=rows.map(r=>{let [id,text,detail,diagram,node,route,edges]=r.cells;if(node?.includes('~')&&!route){route=node;node='';}const target=diagram?{diagram,...(node?{node}:{}),...(route?{route:route.split('~')}:{}),...(edges?{edges:csv(edges)}:{})}:undefined;if(!diagram&&(node||route||edges))fail(r.line+1,type,'A step node, route or edge reference needs its diagram ID.','| step | Read cache | | cache-flow | redis | | |');return{id,text,...(detail?{detail}:{}),...(target?{target}:{})};});break;
+        case 'diagram': {
+          if(positional.length!==1)fail(at+1,type,'A diagram requires exactly one native type.','@diagram sequence source=cache.sequence.json');
+          block.diagramType=positional[0];
+          if(a.source!==undefined)block.source=a.source;
+          if(a.spec!==undefined) { try{block.spec=JSON.parse(a.spec);}catch{fail(at+1,type,'Inline diagram spec must be valid JSON.','@diagram sequence spec=\'{"schema_version":1,...}\'');} }
+          if(rows.length&&(a.spec!==undefined||a.source!==undefined))fail(at+1,type,'Choose shorthand rows, spec or source, not several.','@diagram sequence source=cache.sequence.json');
+          // A "source:<id>" cell ties that row's node to a declared source; the reader shows it on hover.
+          for(const r of rows){const index=r.cells.findIndex(cell=>/^source:[A-Za-z][\w-]*$/u.test(cell));if(index<0)continue;const node=r.cells[0].replace(/^(?:actor|entity)\s+/u,'').trim();if(index>0&&!r.cells[0].includes('>'))(block.nodeSources||={})[node]=r.cells[index].slice(7);r.cells=r.cells.filter((_,i)=>i!==index);}
+          if(rows.length&&a.spec===undefined&&a.source===undefined)try{block.spec=compileExplainerDiagram(block.diagramType,rows.map(r=>({cells:r.cells,line:r.line+1})),{id:a.id||stable('diagram',`${panel?.id}\0${JSON.stringify(rows.map(r=>r.cells))}`),title:a.title||panel?.title||document.meta.title,line:at+1,quality:document.meta.quality_profile});}catch(error){const found=error.archifyDiagnostics||error.diagnostics;if(found?.length)diagnostics.push(...found);else fail(at+1,type,'The diagram shorthand could not compile.','@diagram sequence source=cache.sequence.json');}
+          if(a.changes!==undefined)block.changes=csv(a.changes).map(value=>{const [target,change]=value.split(':');return{target,change};});break;
+        }
+        case 'code':Object.assign(block,select(a,['source','language']));break;
+        case 'diff':block.text=literal??rows.map(r=>r.cells.join(' | ')).join('\n');Object.assign(block,select(a,['caption']));break;
+        case 'image':Object.assign(block,select(a,['path','alt','caption']));break;
+        case 'chart':{if(!a.data||!a.x||!a.y)fail(at+1,type,'A data chart names its file, label column and value columns.','@chart type=bar data=latency.csv x=day y=p50,p99');if(a.type!==undefined&&!['bar','line','pie'].includes(a.type))fail(at+1,type,'A data chart is a bar, line or pie chart.','@chart type=line data=latency.csv x=day y=p99');Object.assign(block,select(a,['title']),{data:{path:a.data,kind:a.type||'bar',x:a.x,y:csv(a.y),...(a.unit?{unit:a.unit}:{})}});break;}
+        case 'comparison':rowWidth(rows,2,500,type);if(a.label)block.labelColumn=a.label;block.columns=csv(a.columns);block.rows=rows.map(r=>({...rowLabel(r.cells[0]),cells:r.cells.slice(1).map(assessment)}));break;
+      }
+      if (['metric','code','image','chart'].includes(type)&&rows.length)fail(at+1,type,'This component accepts header arguments only.',`@${type} ${allowed.filter(k=>k!=='id').map(k=>`${k}=...`).join(' ')}`);
+      if(type!=='diff')for(const row of rows)for(const text of row.cells)unsupported(text,row.line+1,type);
+      addBlock(block,at,cursor,rows);
+      if(type==='diff'&&panel) {
+        const pointer=`/panels/${panelIndex}/blocks/${panel.blocks.length-1}/text`;
+        sourceMap[pointer]=literalStart!==undefined?locate(starts[literalStart]??sourceText.length,(starts[literalStart]??sourceText.length)+literal.length):descriptor(rows[0]?.line??at,cursor);
+      }
+    }
+    function assessment(text) {
+      // Citations may follow the assessment; they stay with the cell text.
+      const match = text.match(/^(.*?)\s*\{(good|caution|bad)(?::([^}]+))?\}((?:\s*\[[^\]]*\]\([^)\s]*\))*)\s*$/u);
+      // A cell holding only a badge ({bad:Drop}) shows the badge; its label doubles as the cell text.
+      return match?{text:`${match[1].trim()}${match[4].trim()}`||match[3]?.trim()||'',assessment:match[2],...(match[3]?{verdict:match[3].trim()}:{})}:{text};
+    }
+    while(cursor<lines.length) {
+      const at=cursor, trimmed=lines[at].trim();
+      if(!trimmed){cursor++;continue;}
+      if(trimmed.startsWith('# ')) {
+        if(titleSeen||panel)fail(at+1,'heading','Use one document title before all panels.','# What should we choose? {#choice}');
+        const h=heading(trimmed,'# ');document.meta.title=h.title;document.meta.id=h.id||stable('explainer',h.title);titleSeen=true;map('/meta',document.meta,descriptor(at));cursor++;continue;
+      }
+      if(trimmed.startsWith('## ')) {
+        closePanel(starts[at]);const h=heading(trimmed,'## ');panel={id:h.id||stable('panel',h.title),title:h.title,...(h.span!==undefined?{span:h.span}:{}),blocks:[]};panelIndex=document.panels.length;document.panels.push(panel);map(`/panels/${panelIndex}`,panel,descriptor(at,lines.length));cursor++;continue;
+      }
+      if(trimmed.startsWith('@')){reasonsAllowed=false;directive(at);continue;}
+      const fence=trimmed.match(/^(```+|~~~+)\s*([A-Za-z0-9_+.#-]*)\s*(.*)$/u);
+      if(fence) {
+        reasonsAllowed=false;
+        const {attrs:fa,positional:fp}=attributes(fence[3]||'',at);
+        if(fp.length||Object.keys(fa).some(key=>key!=='title'))fail(at+1,'snippet','A code fence accepts a language and an optional title only.','```bash title="Run the tests"');
+        cursor=at+1;const begin=cursor;while(cursor<lines.length&&lines[cursor].trim()!==fence[1])cursor++;
+        if(cursor===lines.length)fail(at+1,'snippet','The code fence is not closed.','```bash\nnpm test\n```');
+        const from=starts[begin]??sourceText.length,literal=sourceText.slice(from,starts[cursor]??sourceText.length).replace(/\r?\n$/u,'');
+        if(cursor<lines.length)cursor++;
+        if(!literal.trim()){fail(at+1,'snippet','A code fence needs content.','```bash\nnpm test\n```');continue;}
+        const language=fence[2];
+        addBlock(language==='diff'?{type:'diff',text:literal,...(fa.title?{caption:fa.title}:{})}:language==='mermaid'?{type:'chart',...(fa.title?{title:fa.title}:{}),text:literal}:{type:'snippet',...(language?{language}:{}),...(fa.title?{title:fa.title}:{}),text:literal},at,cursor);
+        if(panel)sourceMap[`/panels/${panelIndex}/blocks/${panel.blocks.length-1}/text`]=locate(from,from+literal.length);
+        continue;
+      }
+      if(trimmed.startsWith('|')) {
+        const rows=[];while(cursor<lines.length&&lines[cursor].trim().startsWith('|')){rows.push({cells:cells(lines[cursor],cursor),line:cursor});cursor++;}
+        if(rows.length<3||!rows[1].cells.every(cell=>/^:?-{3,}:?$/u.test(cell)))fail(at+1,'comparison','A Markdown table needs a header, separator and data rows.','| Criterion | A | B |\n| --- | --- | --- |\n| Cost | Low {good} | High {bad} |');
+        const columns=rows[0]?.cells.slice(1)||[];const data=rows.slice(2);for(const r of data)if(r.cells.length!==columns.length+1)fail(r.line+1,'comparison','All table rows must match the header width.','| Cost | Low {good} | High {bad} |');
+        addBlock({type:'comparison',...(rows[0]?.cells[0]?{labelColumn:rows[0].cells[0]}:{}),columns,rows:data.map(r=>({...rowLabel(r.cells[0]),cells:r.cells.slice(1).map(assessment)}))},at,cursor,data);continue;
+      }
+      const list=trimmed.match(/^(?:([-*+])|(\d+)\.)\s+(.+)$/u);
+      if(list) {
+        const rows=[];const ordered=Boolean(list[2]);while(cursor<lines.length){const found=lines[cursor].trim().match(/^(?:([-*+])|(\d+)\.)\s+(.+)$/u);if(!found||Boolean(found[2])!==ordered)break;if(/^\s{2,}/u.test(lines[cursor]))fail(cursor+1,'list','Nested lists are unsupported.','- One flat item');unsupported(found[3],cursor+1,'list');rows.push({cells:[found[3]],line:cursor});cursor++;}
+        if(!panel){if(!reasonsAllowed||ordered||document.answer.reasons)fail(at+1,'answer','Use one flat unordered reason list after the conclusion.','A conclusion.\n\n- First reason\n- Second reason');document.answer.reasons=rows.map(r=>r.cells[0]);map('/answer/reasons',document.answer.reasons,descriptor(at,cursor));rows.forEach((r,i)=>map(`/answer/reasons/${i}`,r.cells[0],descriptor(r.line)));}else{const task=/^\[[ xX]\]\s+/u,tasks=rows.filter(r=>task.test(r.cells[0])).length;if(tasks&&(ordered||tasks<rows.length))fail(at+1,'list','Write every checklist item as "- [ ] item" in one unordered list.','- [ ] Check the deposit terms\n- [ ] Photograph the meter readings');addBlock({type:'list',ordered,...(tasks?{checklist:true}:{}),items:rows.map(r=>tasks?r.cells[0].replace(task,''):r.cells[0])},at,cursor,rows);}continue;
+      }
+      const chunks=[];while(cursor<lines.length&&lines[cursor].trim()&&!/^(?:#{1,2}\s|@|\||[-*+]\s|\d+\.\s|```|~~~)/u.test(lines[cursor].trim())){unsupported(lines[cursor],cursor+1,'prose');chunks.push(lines[cursor].trim());cursor++;}
+      if(cursor===at){unsupported(trimmed,at+1,'prose');cursor++;continue;}
+      const text=chunks.join('\n');
+      if(!panel) {
+        if(!titleSeen)fail(at+1,'answer','The document title must precede the short answer.','# A title\n\nA direct answer.');
+        if(answerSeen)fail(at+1,'answer','The short answer is one paragraph before the panels.','A direct answer in one paragraph.\n\n## Why?');
+        document.answer.summary=text;answerSeen=true;reasonsAllowed=true;map('/answer',document.answer,descriptor(at,cursor));
+      } else addBlock({type:'prose',text},at,cursor);
+    }
+    closePanel(sourceText.length);
+    if(!titleSeen)fail(1,'title','A document requires one # title.','# What should we choose?');
+    if(!answerSeen)fail(1,'answer','A short answer is required before question panels.','# A title\n\nA direct answer.\n\n## Why?');
+    if(!document.panels.length)fail(1,'panel','At least one question panel is required.','## Why does this happen?');
+    if(output)document.meta.output=output;
+  }
+  const identities=new Map();
+  function identity(value,pointer,component) {
+    if(typeof value!=='string')return;
+    const line=sourceMap[pointer]?.line||sourceMap[pointer.replace(/\/id$/u,'')]?.line||1;
+    if(!ID.test(value)||value.length>100)fail(line,component,'IDs must begin with an ASCII letter and contain letters, numbers, hyphens or underscores.','id=cache-flow',pointer);
+    const previous=identities.get(value);
+    if(previous)fail(line,component,`Duplicate ID "${value}": the ${previous.component} on line ${previous.line} already uses it. Panels, blocks, diagrams and steps share one ID namespace.`,component==='panel'?`## Another question? {#${value}-2}`:`omit id=, or use id=${value}-${component}`,pointer);
+    identities.set(value,{pointer,component,line});
+  }
+  if(document&&typeof document==='object'&&!Array.isArray(document)) {
+    identity(document.meta?.id,'/meta/id','document');
+    for(const [pi,p]of (Array.isArray(document.panels)?document.panels:[]).entries()) {
+      identity(p?.id,`/panels/${pi}/id`,'panel');
+      for(const [bi,b]of (Array.isArray(p?.blocks)?p.blocks:[]).entries())identity(b?.id,`/panels/${pi}/blocks/${bi}/id`,b?.type||'block');
+    }
+  }
+  return {document:diagnostics.some(d=>d.severity==='error')?null:document,sourceMap,format,sourceText,diagnostics};
+}

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

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseValidatedExplainer, rebindPreparedBundle, validatePreparedTargets } from './prepare.mjs';
+import { resolveExplainerSources } from './sources.mjs';
+import { prepareExplainerDiagrams } from './diagrams.mjs';
+import { computeExplainerRevision } from './revision.mjs';
+import { unpackPageBundle } from './page-bundle.mjs';
+import { throwDiagnosticError } from '../renderers/shared/diagnostics.mjs';
+
+function fail(reason, message, input, panelId, example) {
+  throwDiagnosticError(message, [{code:`explainer/patch-${reason}`,severity:'error',message,
+    subject:{input,panelId,line:1,component:'panel'},evidence:{reason,example},supportedFixes:[example]}]);
+}
+function embedded(html, id, input) {
+  const matches = [...html.matchAll(new RegExp(`<script\\b[^>]*\\bid=["']${id}["'][^>]*>([\\s\\S]*?)<\\/script>`, 'gi'))];
+  if(matches.length !== 1) fail('payload','The artifact must contain one original draft and prepared resource payload.',input,undefined,'Use an artifact produced by the formal explainer CLI.');
+  try { return JSON.parse(matches[0][1]); } catch { fail('payload','Embedded draft payload is invalid.',input,undefined,'Rebuild the artifact from its original draft.'); }
+}
+/** Replace an authored stable panel while retaining immutable resources outside that panel. */
+export async function preparePanelPatch({artifactPath,panelId,replacementPath,repoRoot,quality,writingMode,expectedArtifact}) {
+  const artifactBytes=fs.readFileSync(artifactPath);
+  if(expectedArtifact && (artifactBytes.length!==expectedArtifact.bytes || createHash('sha256').update(artifactBytes).digest('hex')!==expectedArtifact.sha256)) fail('artifact-changed','The original artifact changed after validation.',artifactPath,panelId,'Finish other writes to the artifact and retry the panel patch.');
+  const html = artifactBytes.toString('utf8');
+  let previous;
+  try { previous = unpackPageBundle(embedded(html,'archify-explainer-prepared',artifactPath)); } catch (error) { if (error.diagnostics) throw error; fail('payload','Embedded native diagram payload cannot be inflated.',artifactPath,panelId,'Rebuild the original artifact before patching.'); }
+  // The page names local files relative to itself; resolve them before reading or re-preparing.
+  const near = value => typeof value === 'string' ? path.resolve(path.dirname(artifactPath), value) : value;
+  const draft = {...previous,sourcePath:near(previous.sourcePath)};
+  if(typeof draft.sourceText !== 'string' || draft.sourceText !== previous.sourceText
+    || createHash('sha256').update(draft.sourceText).digest('hex') !== previous.source?.sha256
+    || createHash('sha256').update(JSON.stringify({...previous,digest:undefined})).digest('hex') !== previous.digest) {
+    fail('payload','The embedded original draft is not bound to the prepared resources.',artifactPath,panelId,'Rebuild the original artifact before patching.');
+  }
+  const oldParsed = parseValidatedExplainer(draft.sourceText,{inputPath:draft.sourcePath || artifactPath,writingMode:'off'});
+  if(JSON.stringify(oldParsed.document)!==JSON.stringify(previous.document)) fail('payload','The original draft and normalized document disagree.',artifactPath,panelId,'Rebuild the original artifact before patching.');
+  const index = oldParsed.document.panels.findIndex(panel=>panel.id===panelId);
+  if(index<0) fail('target','The requested panel does not exist.',artifactPath,panelId,'Choose a stable panel id from the original artifact.');
+  const range=oldParsed.sourceMap[`/panels/${index}`];
+  if(!Number.isInteger(range?.start)||!Number.isInteger(range?.end)) fail('range','The original draft has no replaceable panel range.',artifactPath,panelId,'Rebuild the artifact using the current parser.');
+  const replacementBytes = fs.readFileSync(replacementPath);
+  const replacement = replacementBytes.toString('utf8');
+  if(!Buffer.from(replacement).equals(replacementBytes)) fail('source-encoding','Panel replacement must contain valid UTF-8 bytes.',replacementPath,panelId,'Save the replacement panel as UTF-8 text.');
+  const sourceText = draft.sourceText.slice(0,range.start)+replacement+draft.sourceText.slice(range.end);
+  const parsed=parseValidatedExplainer(sourceText,{inputPath:draft.sourcePath || artifactPath,writingMode:writingMode || previous.writingMode || 'warn'});
+  if(parsed.document.panels.length!==oldParsed.document.panels.length || parsed.document.panels[index]?.id!==panelId) {
+    fail('identity','A panel replacement must retain the target stable id and panel count.',replacementPath,panelId,oldParsed.format==='json'?'{"id":"'+panelId+'","title":"Question?","blocks":[...]}':'## Question? {#'+panelId+'}\n\nReplacement content.');
+  }
+  const expected=structuredClone(oldParsed.document);
+  expected.panels[index]=parsed.document.panels[index];
+  if(JSON.stringify(expected)!==JSON.stringify(parsed.document)) fail('scope','The replacement changes content outside the selected panel.',replacementPath,panelId,'Replace only the target panel; preserve document metadata, sources and other panels.');
+  const oldBlocks=new Map(oldParsed.document.panels[index].blocks.map(block=>[block.id,block]));
+  const changed=parsed.document.panels[index].blocks.filter(block=>JSON.stringify(oldBlocks.get(block.id))!==JSON.stringify(block));
+  // Already verified immutable code excerpts remain usable after the original checkout disappears.
+  const changedCodeIds=new Set(changed.filter(block=>block.type==='code' && typeof previous.preparedSources?.sources?.[block.source]?.text !== 'string').map(block=>block.source));
+  const selectedQuality=quality || previous.quality || 'standard';
+  const qualityChanged=selectedQuality !== previous.quality;
+  const oldDiagramBlocks=new Map(oldParsed.document.panels.flatMap(panel=>panel.blocks).filter(block=>block.type==='diagram').map(block=>[block.id,block]));
+  const reusedDiagramSources=new Set();
+  const frozenDiagramInput=block=>{
+    if(block.type==='diagram' && block.source && oldDiagramBlocks.get(block.id)?.source===block.source && previous.preparedDiagrams?.diagrams?.[block.id]?.spec) {
+      reusedDiagramSources.add(block.id);
+      return {...block,source:undefined,spec:previous.preparedDiagrams.diagrams[block.id].spec};
+    }
+    return block;
+  };
+  const partial={...parsed.document,panels:[{...parsed.document.panels[index],blocks:changed.filter(block=>
+    (block.type!=='code'||changedCodeIds.has(block.source))
+    && !(block.type==='image' && oldBlocks.get(block.id)?.path===block.path && previous.preparedSources?.assets?.[block.id])
+    && !(block.type==='chart' && block.data && JSON.stringify(oldBlocks.get(block.id)?.data)===JSON.stringify(block.data) && previous.preparedSources?.charts?.[block.id]))
+    .map(frozenDiagramInput)}],sources:parsed.document.sources.filter(source=>changedCodeIds.has(source.id))};
+  const common={repoRoot,baseDir:previous.baseDir===null ? null : near(previous.baseDir) || path.dirname(draft.sourcePath || artifactPath),sourceMap:parsed.sourceMap,sourcePath:draft.sourcePath || artifactPath,quality:selectedQuality};
+  const partialMap={...parsed.sourceMap};
+  for(const [partialIndex,block] of partial.panels[0].blocks.entries()) {
+    const originalIndex=parsed.document.panels[index].blocks.findIndex(entry=>entry.id===block.id);
+    const originalPrefix=`/panels/${index}/blocks/${originalIndex}`;
+    for(const [pointer,location] of Object.entries(parsed.sourceMap)) if(pointer===originalPrefix || pointer.startsWith(`${originalPrefix}/`)) partialMap[`/panels/0/blocks/${partialIndex}${pointer.slice(originalPrefix.length)}`]=location;
+  }
+  for(const [partialIndex,source] of partial.sources.entries()) {
+    const originalIndex=parsed.document.sources.findIndex(entry=>entry.id===source.id);
+    const originalPrefix=`/sources/${originalIndex}`;
+    for(const [pointer,location] of Object.entries(parsed.sourceMap)) if(pointer===originalPrefix || pointer.startsWith(`${originalPrefix}/`)) partialMap[`/sources/${partialIndex}${pointer.slice(originalPrefix.length)}`]=location;
+  }
+  const newSources=await resolveExplainerSources(partial,{...common,sourceMap:partialMap});
+  // A profile change needs fresh native validation for every child, including
+  // untouched panels. Frozen original specs keep this independent of old files.
+  const diagramDocument=qualityChanged ? {...parsed.document,panels:parsed.document.panels.map(panel=>({...panel,blocks:panel.blocks.map(frozenDiagramInput)}))} : partial;
+  const newDiagrams=await prepareExplainerDiagrams(diagramDocument,{...common,sourceMap:qualityChanged ? parsed.sourceMap : partialMap});
+  newDiagrams.dependencies=newDiagrams.dependencies.map(entry=>{
+    if(!reusedDiagramSources.has(entry.id)) return entry;
+    const original=(previous.dependencies || []).find(dep=>dep.kind==='diagram-spec' && dep.id===entry.id);
+    if(!original) fail('payload','The original diagram has no frozen specification evidence.',artifactPath,panelId,'Rebuild the original artifact before patching.');
+    newDiagrams.diagrams[entry.id].specification=previous.preparedDiagrams.diagrams[entry.id].specification;
+    return {...original,path:near(original.path),retained:true};
+  });
+  const preparedSources={...previous.preparedSources,sources:{...previous.preparedSources.sources,...newSources.sources},assets:{...previous.preparedSources.assets,...newSources.assets},charts:{...previous.preparedSources.charts,...newSources.charts}};
+  const preparedDiagrams={...previous.preparedDiagrams,diagrams:{...previous.preparedDiagrams.diagrams,...newDiagrams.diagrams}};
+  const activeBlocks=parsed.document.panels.flatMap(panel=>panel.blocks);
+  const imageIds=new Set(activeBlocks.filter(block=>block.type==='image').map(block=>block.id));
+  const diagramIds=new Set(activeBlocks.filter(block=>block.type==='diagram').map(block=>block.id));
+  const dataChartIds=new Set(activeBlocks.filter(block=>block.type==='chart'&&block.data).map(block=>block.id));
+  preparedSources.assets=Object.fromEntries(Object.entries(preparedSources.assets).filter(([id])=>imageIds.has(id)));
+  preparedSources.charts=Object.fromEntries(Object.entries(preparedSources.charts).filter(([id])=>dataChartIds.has(id)));
+  if(!Object.keys(preparedSources.charts).length)delete preparedSources.charts;
+  preparedDiagrams.diagrams=Object.fromEntries(Object.entries(preparedDiagrams.diagrams).filter(([id])=>diagramIds.has(id)));
+  validatePreparedTargets(parsed.document,preparedDiagrams.diagrams,common);
+  const dependencyKey=entry=>`${entry.kind}:${entry.id}`;
+  const newDependencies=[...(newSources.dependencies||[]),...(newDiagrams.dependencies||[])];
+  const preparedIds=new Set(newDependencies.map(dependencyKey));
+  const localDependency=(entry,baseDir)=>({...entry,...(entry.kind==='repository'||entry.inline||!entry.path?{}:{path:path.resolve(baseDir,entry.path)})});
+  const dependencies=[...(previous.dependencies||[]).filter(entry=>!preparedIds.has(dependencyKey(entry)) && (entry.kind!=='image'||imageIds.has(entry.id)) && (entry.kind!=='data'||dataChartIds.has(entry.id)) && (entry.kind!=='diagram-spec'||diagramIds.has(entry.id))).map(entry=>localDependency(entry,path.dirname(artifactPath))),
+    ...newDependencies.map(entry=>localDependency(entry,common.baseDir))];
+  // Old dependencies are embedded immutable bytes. Only newly prepared resources are reread/verified.
+  const bundle=rebindPreparedBundle({...previous,sourcePath:common.sourcePath,baseDir:common.baseDir,preparedSources,preparedDiagrams,dependencies,quality:selectedQuality,writingMode:writingMode || previous.writingMode || 'warn'},parsed);
+  bundle.dependencies = dependencies.map(entry => ({...entry, retained: entry.retained===true || !preparedIds.has(dependencyKey(entry))}));
+  return {bundle:rebindPreparedBundle(bundle,parsed),sourceText,sourcePath:draft.sourcePath || artifactPath,previousRevision:computeExplainerRevision(previous),previousSourceSha256:previous.source.sha256,panelId};
+}

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

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseExplainer } from './parse.mjs';
+import { validateExplainer } from './validate.mjs';
+import { resolveExplainerSources } from './sources.mjs';
+import { parseInline } from './inline.mjs';
+import { prepareExplainerDiagrams, validateExplainerDiagramTarget } from './diagrams.mjs';
+import { throwDiagnosticError } from '../renderers/shared/diagnostics.mjs';
+
+const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const MAX_SOURCE_BYTES = 16 * 1024 * 1024;
+const identity = bytes => ({ sha256: createHash('sha256').update(bytes).digest('hex'), bytes: Buffer.byteLength(bytes) });
+const digest = bundle => identity(JSON.stringify({ ...bundle, digest: undefined })).sha256;
+function fail(code, message, input, reason, example = 'Retry from the unchanged original draft and local resources.') {
+  throwDiagnosticError(message, [{ code: `explainer/${code}`, severity: 'error', message,
+    subject: { input, line: 1, component: 'document' }, evidence: { reason, example }, supportedFixes: [example] }]);
+}
+export function parseValidatedExplainer(sourceText, options = {}) {
+  if (Buffer.byteLength(sourceText) > MAX_SOURCE_BYTES) fail('source-limit', 'Explainer draft exceeds the 16 MiB source budget.', options.inputPath, 'source-byte-limit', 'Reduce the draft below 16 MiB and use relative native diagram sources for large specifications.');
+  const parsed = parseExplainer(sourceText, { inputPath: options.inputPath, output: options.output });
+  if (!parsed.document || parsed.diagnostics.some(entry => entry.severity !== 'warning')) {
+    throwDiagnosticError('Explainer draft could not be parsed.', parsed.diagnostics);
+  }
+  const validated = validateExplainer(parsed.document, { sourceMap: parsed.sourceMap, inputPath: options.inputPath, writingMode: options.writingMode });
+  if (!validated.ok) throwDiagnosticError('Explainer draft is invalid.', validated.diagnostics);
+  return { ...parsed, diagnostics: [...parsed.diagnostics, ...validated.diagnostics] };
+}
+export async function prepareExplainer(sourceText, options = {}) {
+  const inputPath = path.resolve(options.inputPath);
+  const parsed = parseValidatedExplainer(sourceText, { ...options, inputPath });
+  const baseDir = options.baseDir || path.dirname(inputPath);
+  const quality = options.quality || parsed.document.meta?.quality_profile || 'standard';
+  const common = { repoRoot: options.repoRoot, baseDir, sourceMap: parsed.sourceMap, sourcePath: inputPath, quality };
+  const preparedSources = await resolveExplainerSources(parsed.document, common);
+  const preparedDiagrams = await prepareExplainerDiagrams(parsed.document, common);
+  validatePreparedTargets(parsed.document, preparedDiagrams.diagrams, common);
+  const dependencies = [...(preparedSources.dependencies || []), ...(preparedDiagrams.dependencies || [])].map(entry => ({ ...entry, id: entry.id || entry.blockId,
+    ...(entry.kind === 'repository' || entry.inline ? {} : { path: path.resolve(baseDir, entry.path) }) }));
+  const bundle = { schemaVersion: 1, kind: 'archify-explainer-prepared', ...parsed, sourcePath: inputPath, baseDir,
+    quality, writingMode: options.writingMode || 'warn', source: identity(Buffer.from(sourceText)),
+    preparedSources: { sources: preparedSources.sources, assets: preparedSources.assets, ...(Object.keys(preparedSources.charts || {}).length ? { charts: preparedSources.charts } : {}), ...(preparedSources.repository ? { repository: preparedSources.repository } : {}) },
+    preparedDiagrams: { diagrams: preparedDiagrams.diagrams }, dependencies };
+  bundle.digest = digest(bundle);
+  assertPreparedDependencies(bundle);
+  return bundle;
+}
+export function assertPreparedDependencies(bundle) {
+  for (const dependency of bundle.dependencies || []) {
+    // Repository excerpts were read from the pinned Git object, never the mutable checkout.
+    if (dependency.kind === 'repository' || dependency.inline || dependency.retained) {
+      if (typeof dependency.contentBase64 === 'string') {
+        const frozen = identity(Buffer.from(dependency.contentBase64, 'base64'));
+        if (frozen.sha256 !== dependency.sha256 || frozen.bytes !== dependency.bytes) fail('prepared-mismatch', 'Frozen resource bytes do not match their identity.', bundle.sourcePath, 'frozen-resource-byte-mismatch');
+      } else if (dependency.retained) fail('prepared-invalid', 'Retained resources require their original frozen bytes.', bundle.sourcePath, 'missing-frozen-resource');
+      continue;
+    }
+    let actual;
+    try { actual = identity(fs.readFileSync(dependency.path)); } catch (error) {
+      fail('dependency-changed', 'A frozen explainer resource is no longer readable.', bundle.sourcePath, error.code || 'read-failed');
+    }
+    if (actual.sha256 !== dependency.sha256 || actual.bytes !== dependency.bytes) {
+      fail('dependency-changed', 'An explainer resource changed during preparation.', bundle.sourcePath, 'frozen-resource-byte-mismatch');
+    }
+  }
+}
+export function writePreparedBundle(directory, bundle) {
+  const file = path.join(directory, 'explainer.prepared.json');
+  const bytes = Buffer.from(JSON.stringify(bundle));
+  if (bytes.length > MAX_BUNDLE_BYTES) fail('resource-limit', 'Prepared explainer exceeds the resource budget.', bundle.sourcePath, 'bundle-byte-limit');
+  fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 });
+  return file;
+}
+export function readPreparedBundle(file, sourceText, inputPath, { checkDependencies = true, expectedInputPath = inputPath, quality, writingMode } = {}) {
+  let bundle;
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size > MAX_BUNDLE_BYTES) throw new Error('bundle-byte-limit');
+    bundle = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) { fail('prepared-invalid', 'Prepared explainer could not be read.', inputPath, error.code || 'invalid-bundle'); }
+  const canonical = value => { try { return fs.realpathSync.native(path.resolve(value)); } catch { return path.resolve(value); } };
+  if (typeof (bundle.inputPath || bundle.sourcePath) !== 'string' || canonical(bundle.inputPath || bundle.sourcePath) !== canonical(expectedInputPath)) {
+    fail('prepared-mismatch', 'Prepared explainer belongs to a different author input path.', inputPath, 'draft-path-mismatch');
+  }
+  const source = identity(Buffer.from(sourceText));
+  if (bundle?.kind !== 'archify-explainer-prepared' || bundle.schemaVersion !== 1 || bundle.digest !== digest(bundle)
+    || source.sha256 !== bundle.source?.sha256 || source.bytes !== bundle.source?.bytes || bundle.sourceText !== sourceText) {
+    fail('prepared-mismatch', 'Prepared explainer does not match the original draft bytes.', inputPath, 'draft-or-bundle-digest-mismatch');
+  }
+  if (quality && quality !== bundle.quality) fail('prepared-mismatch', 'Prepared explainer uses a different quality profile.', inputPath, 'quality-profile-mismatch', 'Prepare the original draft again under the requested quality profile.');
+  if (writingMode && writingMode !== (bundle.writingMode || 'warn')) fail('prepared-mismatch', 'Prepared explainer uses a different writing check mode.', inputPath, 'writing-mode-mismatch', 'Prepare the original draft again under the requested writing check mode.');
+  const parsed = parseValidatedExplainer(sourceText, { inputPath: bundle.sourcePath, writingMode: bundle.writingMode || 'warn' });
+  if (JSON.stringify(parsed.document) !== JSON.stringify(bundle.document)) fail('prepared-mismatch', 'Prepared document differs from the authored draft.', inputPath, 'normalized-document-mismatch');
+  if (checkDependencies) assertPreparedDependencies(bundle);
+  return bundle;
+}
+export function rebindPreparedBundle(bundle, parsed) {
+  const next = { ...bundle, ...parsed, source: identity(Buffer.from(parsed.sourceText)) };
+  next.digest = digest(next);
+  return next;
+}
+
+export function validatePreparedTargets(document, diagrams, options = {}) {
+  const visit = (value, pointer, panelId, component) => {
+    if (typeof value === 'string') {
+      const location = options.sourceMap?.[pointer] || {};
+      const inline = parseInline(value, { line: location.line || 1, input: options.sourcePath, panelId, component });
+      for (const reference of inline.references) {
+        if (!['node','route'].includes(reference.kind)) continue;
+        const target = reference.kind === 'node' ? {diagram:reference.diagram,node:reference.node} : {diagram:reference.diagram,route:[reference.from,reference.to]};
+        const line = (location.line || 1) + (value.slice(0,reference.offset).match(/\n/g)?.length || 0);
+        validateExplainerDiagramTarget(diagrams,target,{...options,pointer,line});
+      }
+    } else if (Array.isArray(value)) value.forEach((entry,index)=>visit(entry,`${pointer}/${index}`,panelId,component));
+    else if (value && typeof value === 'object') for(const [key,entry] of Object.entries(value)) {
+      if (['spec','source','path','language','target','changes'].includes(key) || (['diff','snippet'].includes(component) && key==='text')) continue;
+      visit(entry,`${pointer}/${key}`,panelId,component);
+    }
+  };
+  visit(document.answer,'/answer',undefined,'answer');
+  document.panels.forEach((panel,index)=>{
+    visit(panel.title,`/panels/${index}/title`,panel.id,'panel');
+    panel.blocks.forEach((block,blockIndex)=>{
+      const pointer=`/panels/${index}/blocks/${blockIndex}`;
+      visit(block,pointer,panel.id,block.type);
+      if(block.type==='steps') block.items.forEach((item,itemIndex)=>{
+        if(item.target)validateExplainerDiagramTarget(diagrams,item.target,{...options,pointer:`${pointer}/items/${itemIndex}/target`,line:options.sourceMap?.[`${pointer}/items/${itemIndex}`]?.line || options.sourceMap?.[pointer]?.line || 1});
+      });
+    });
+  });
+}