@pygmalionjs/pygmalion 0.8.1 → 0.9.0

package/node/source-structure-wrapper-codec.mjs

@@ -0,0 +1,205 @@
+/**
+ * Pure wrapper codec shared by the browser document compiler and the Node source compiler.
+ *
+ * A source group with a layout compiles to one intrinsic element carrying a generated CSS
+ * module class. This module owns the deterministic class name, the layout-to-declaration
+ * mapping, and the exact managed block syntax. Spacing spellings come from the host
+ * contract; nothing here reads files, evaluates Sass, or knows a product token.
+ */
+export const VOID_ELEMENTS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+export const WRAPPER_ALIGNMENTS = Object.freeze(['start', 'center', 'end', 'stretch']);
+const FLEX_ALIGN = { start: 'flex-start', center: 'center', end: 'flex-end', stretch: 'stretch' };
+const FLEX_DIRECTION = { horizontal: 'row', vertical: 'column' };
+const MEASURES = { crossGap: null, paddingTop: 'padding-top', paddingRight: 'padding-right', paddingBottom: 'padding-bottom', paddingLeft: 'padding-left', minWidth: 'min-width', maxWidth: 'max-width', minHeight: 'min-height', maxHeight: 'max-height' };
+const DISTRIBUTION = { start: 'flex-start', center: 'center', end: 'flex-end', 'space-between': 'space-between' };
+const SOURCE_FIELDS = ['direction', 'gap', 'padding', 'align', 'wrap', 'crossGap', 'distribute', 'columns', ...Object.keys(MEASURES).filter(key => key !== 'crossGap')];
+const MANAGED_PROPERTIES = ['display', 'flex-direction', 'grid-template-columns', 'flex-wrap', 'gap', 'row-gap', 'column-gap', 'padding', 'align-items', 'justify-content', 'justify-items', ...Object.values(MEASURES).filter(Boolean)];
+
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const identifier = value => typeof value === 'string' && /^[A-Za-z_$][\w$]{0,63}$/.test(value);
+const cssValue = value => typeof value === 'string' && value.length > 0 && value.length <= 160 && value === value.trim()
+  && !/[;{}\0\r\n]/.test(value) && !/\/\*|\*\/|\/\//.test(value);
+const stylesheetPath = value => typeof value === 'string' && value.length > 0 && value.length <= 512 && /\.s?css$/i.test(value)
+  && !value.startsWith('/') && !/^[a-z]:/i.test(value) && !/[\\\x00-\x1f\x7f?#]/.test(value)
+  && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
+const escape = value => value.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+const lineEnding = source => source.includes('\r\n') ? '\r\n' : '\n';
+const problem = (code, message) => Object.assign(new Error(message), { code });
+const stale = message => problem('structure-wrapper-stale', message);
+const masked = source => source.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, value => value.replace(/[^\n]/g, ' '));
+
+/** Returns null when the contract is usable, otherwise one explicit reason. */
+export function wrapperContractProblem(contract) {
+  if (!record(contract) || Object.keys(contract).some(key => !['stylesheet', 'styleAlias', 'tagName', 'spacing', 'align'].includes(key))) {
+    return 'A wrapper contract declares a stylesheet, a style alias, permitted spacing, and optionally a tag name and alignments.';
+  }
+  if (!stylesheetPath(contract.stylesheet)) return 'The wrapper stylesheet must be a normalized relative CSS or SCSS path.';
+  if (!identifier(contract.styleAlias)) return 'The wrapper style alias must be the JSX identifier of the imported stylesheet module.';
+  if (contract.tagName !== undefined && (typeof contract.tagName !== 'string' || !/^[a-z][a-z0-9]*$/.test(contract.tagName) || VOID_ELEMENTS.has(contract.tagName))) {
+    return 'The wrapper tag must be an intrinsic non-void element.';
+  }
+  if (!Array.isArray(contract.spacing) || !contract.spacing.length || contract.spacing.length > 200) return 'A wrapper contract lists at least one permitted spacing value.';
+  const px = new Set(); const css = new Set();
+  for (const entry of contract.spacing) {
+    if (!record(entry) || Object.keys(entry).some(key => !['px', 'css'].includes(key)) || typeof entry.px !== 'number' || !Number.isFinite(entry.px)
+      || entry.px < 0 || !cssValue(entry.css) || px.has(entry.px) || css.has(entry.css)) {
+      return 'Each permitted spacing pairs one nonnegative pixel value with one unique CSS spelling.';
+    }
+    px.add(entry.px); css.add(entry.css);
+  }
+  if (contract.align !== undefined && (!Array.isArray(contract.align) || !contract.align.length || new Set(contract.align).size !== contract.align.length
+    || contract.align.some(value => !WRAPPER_ALIGNMENTS.includes(value)))) {
+    return 'Permitted wrapper alignments must be a unique subset of start, center, end, and stretch.';
+  }
+  return null;
+}
+
+export const wrapperTagName = contract => contract.tagName ?? 'div';
+export const wrapperOpening = (contract, className) => `<${wrapperTagName(contract)} className={${contract.styleAlias}.${className}}>`;
+export const wrapperClosing = contract => `</${wrapperTagName(contract)}>`;
+export const wrapperMarker = groupId => `/* Pygmalion wrapper: ${groupId} */`;
+
+/** Deterministic CSS module identifier for one stable group ID; null when the ID cannot derive one. */
+export function wrapperClassName(groupId) {
+  if (typeof groupId !== 'string' || groupId.length > 120 || !/^[A-Za-z0-9][\w:./-]*$/.test(groupId)) return null;
+  const words = groupId.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  const name = `wrap${words.map(word => word[0].toUpperCase() + word.slice(1)).join('')}`;
+  return name.length <= 64 ? name : null;
+}
+
+/** Returns null for a layout the contract can express, otherwise one explicit reason. */
+export function wrapperLayoutProblem(layout, contract) {
+  if (!record(layout) || Object.keys(layout).some(key => ![...SOURCE_FIELDS, 'sizing', 'crossSizing'].includes(key))) return 'A wrapper layout uses only supported source layout fields.';
+  if (!Object.hasOwn(FLEX_DIRECTION, layout.direction) && layout.direction !== 'grid') return 'A wrapper layout direction is horizontal, vertical, or grid.';
+  for (const property of ['gap', 'padding', ...Object.keys(MEASURES)]) {
+    if ((property === 'gap' || property === 'padding' || layout[property] !== undefined) && !contract.spacing.some(entry => entry.px === layout[property])) return `The wrapper ${property} must be one of the permitted spacing values.`;
+  }
+  if (layout.align !== undefined && !(contract.align ?? WRAPPER_ALIGNMENTS).includes(layout.align)) return 'The wrapper alignment must be one of the permitted alignments.';
+  if (['sizing', 'crossSizing'].some(key => layout[key] !== undefined && layout[key] !== 'fixed')) return 'A wrapper element sizes by the application layout; hug sizing is not a source value.';
+  if (layout.wrap !== undefined && (typeof layout.wrap !== 'boolean' || layout.direction === 'grid')) return 'Wrapping is a boolean for flex wrappers only.';
+  if (layout.columns !== undefined && (layout.direction !== 'grid' || !Number.isInteger(layout.columns) || layout.columns < 1 || layout.columns > 1000)) return 'Grid columns must be an integer from 1 to 1000 on a grid wrapper.';
+  if (layout.distribute !== undefined && (!Object.hasOwn(DISTRIBUTION, layout.distribute) || layout.direction === 'grid' && layout.distribute === 'space-between')) return 'Invalid wrapper distribution.';
+  for (const axis of ['Width', 'Height']) if (layout[`min${axis}`] !== undefined && layout[`max${axis}`] !== undefined && layout[`min${axis}`] > layout[`max${axis}`]) return 'A wrapper minimum cannot exceed its maximum.';
+  return null;
+}
+
+/** The source-relevant fields; fixed authoring sizing is not emitted. */
+export function wrapperLayout(layout) {
+  return Object.fromEntries(SOURCE_FIELDS.filter(key => layout[key] !== undefined || key === 'columns' && layout.direction === 'grid').map(key => [key, key === 'columns' ? layout.columns ?? 2 : layout[key]]));
+}
+
+export function wrapperDeclarations(layout, contract) {
+  const reason = wrapperLayoutProblem(layout, contract);
+  if (reason) throw problem('structure-layout-invalid', reason);
+  const spacing = px => contract.spacing.find(entry => entry.px === px).css;
+  const grid = layout.direction === 'grid';
+  const declarations = { display: grid ? 'grid' : 'flex', ...(grid ? { 'grid-template-columns': `repeat(${layout.columns ?? 2}, minmax(0, 1fr))` } : { 'flex-direction': FLEX_DIRECTION[layout.direction] }), gap: spacing(layout.gap), padding: spacing(layout.padding), ...(layout.align === undefined ? {} : { 'align-items': FLEX_ALIGN[layout.align] }) };
+  if (layout.wrap !== undefined) declarations['flex-wrap'] = layout.wrap ? 'wrap' : 'nowrap';
+  if (layout.distribute !== undefined) declarations[grid ? 'justify-items' : 'justify-content'] = DISTRIBUTION[layout.distribute];
+  for (const [key, css] of Object.entries(MEASURES)) if (layout[key] !== undefined) declarations[css ?? (layout.direction === 'vertical' ? 'column-gap' : 'row-gap')] = spacing(layout[key]);
+  return declarations;
+}
+
+/** Every accepted source value must decode through the host's exact token spelling. */
+export function wrapperLayoutFromDeclarations(declarations, contract) {
+  const keys = Object.keys(declarations);
+  const grid = declarations.display === 'grid';
+  if ((!grid && declarations.display !== 'flex') || keys.some(key => !MANAGED_PROPERTIES.includes(key)) || !['gap', 'padding', grid ? 'grid-template-columns' : 'flex-direction'].every(key => keys.includes(key))) throw stale('A managed wrapper block needs its supported display, direction, gap, and padding.');
+  if (grid && ('flex-direction' in declarations || 'flex-wrap' in declarations || 'justify-content' in declarations) || !grid && ('grid-template-columns' in declarations || 'justify-items' in declarations)) throw stale('Managed wrapper display and alignment fields must agree.');
+  const direction = grid ? 'grid' : Object.keys(FLEX_DIRECTION).find(key => FLEX_DIRECTION[key] === declarations['flex-direction']);
+  const spacing = css => contract.spacing.find(entry => entry.css === css)?.px;
+  const result = { direction, gap: spacing(declarations.gap), padding: spacing(declarations.padding) };
+  if (declarations['align-items'] !== undefined) result.align = Object.keys(FLEX_ALIGN).find(key => FLEX_ALIGN[key] === declarations['align-items']);
+  if ('align-items' in declarations && result.align === undefined) throw stale('Unknown managed alignment.');
+  if (grid) {
+    const match = /^repeat\(([1-9][0-9]*), minmax\(0, 1fr\)\)$/.exec(declarations['grid-template-columns']);
+    if (!match) throw stale('Grid tracks must use the generated equal-column form.');
+    result.columns = Number(match[1]);
+  }
+  if ('flex-wrap' in declarations) {
+    if (!['wrap', 'nowrap'].includes(declarations['flex-wrap'])) throw stale('Unknown managed wrapping.');
+    result.wrap = declarations['flex-wrap'] === 'wrap';
+  }
+  const justify = grid ? 'justify-items' : 'justify-content';
+  if (justify in declarations) {
+    result.distribute = Object.keys(DISTRIBUTION).find(key => DISTRIBUTION[key] === declarations[justify]);
+    if (!result.distribute) throw stale('Unknown managed distribution.');
+  }
+  const crossGap = direction === 'vertical' ? 'column-gap' : 'row-gap';
+  if (declarations[direction === 'vertical' ? 'row-gap' : 'column-gap'] !== undefined) throw stale('The cross gap must match the wrapper direction.');
+  for (const [key, css] of Object.entries(MEASURES)) {
+    const name = css ?? crossGap;
+    if (name in declarations) {
+      result[key] = spacing(declarations[name]);
+      if (result[key] === undefined) throw stale('A managed measure must use the exact permitted spacing spelling.');
+    }
+  }
+  const reason = wrapperLayoutProblem(result, contract);
+  if (reason) throw stale(reason);
+  return wrapperLayout(result);
+}
+
+export function wrapperBlock(groupId, className, layout, contract, eol = '\n') {
+  const lines = Object.entries(wrapperDeclarations(layout, contract)).map(([property, value]) => `  ${property}: ${value};`);
+  return [wrapperMarker(groupId), `.${className} {`, ...lines, '}'].join(eol);
+}
+
+/** Locates the one managed block for a group. Null when absent; throws when present but not canonical. */
+export function findWrapperBlock(source, groupId, className) {
+  const marker = wrapperMarker(groupId);
+  const start = source.indexOf(marker);
+  if (start < 0) return null;
+  if (source.indexOf(marker, start + marker.length) >= 0) throw stale(`The managed wrapper block for ${groupId} must be unique.`);
+  if (start > 0 && source[start - 1] !== '\n') throw stale(`The managed wrapper block for ${groupId} must start its own line.`);
+  const pattern = new RegExp(`^\\r?\\n\\.${escape(className)} \\{\\r?\\n((?:  [a-z-]+: [^;{}\\r\\n]+;\\r?\\n){1,20})\\}(?=\\r?\\n|$)`);
+  const match = pattern.exec(source.slice(start + marker.length));
+  if (!match) throw stale(`The managed wrapper block for ${groupId} was edited outside its generated form.`);
+  const declarations = {};
+  for (const line of match[1].split(/\r?\n/).filter(Boolean)) {
+    const [, property, value] = /^ {2}([a-z-]+): (.+);$/.exec(line);
+    if (Object.hasOwn(declarations, property)) throw stale(`The managed wrapper block for ${groupId} repeats a declaration.`);
+    declarations[property] = value;
+  }
+  return { start, end: start + marker.length + match[0].length, declarations };
+}
+
+/** True when a selector outside the ignored ranges references the class. Comments and strings are masked. */
+export function wrapperClassReferenced(source, className, ignore = []) {
+  let text = masked(source);
+  for (const range of ignore) text = text.slice(0, range.start) + ' '.repeat(range.end - range.start) + text.slice(range.end);
+  return new RegExp(`\\.${escape(className)}(?![\\w-])`).test(text);
+}
+
+/** Layout of the managed block for a group, or null when the stylesheet has none. Throws on any unowned edit. */
+export function readWrapperLayout(source, groupId, className, contract) {
+  const block = findWrapperBlock(source, groupId, className);
+  if (!block) return null;
+  if (wrapperClassReferenced(source, className, [block])) throw stale(`Another rule also styles .${className}; the wrapper block is not the only owner.`);
+  return wrapperLayoutFromDeclarations(block.declarations, contract);
+}
+
+/** Applies removals (null) and in-place or appended blocks in order; the input string is never mutated. */
+export function applyWrapperEdits(source, edits, contract) {
+  const eol = lineEnding(source);
+  let content = source;
+  for (const [groupId, layout] of edits) {
+    const className = wrapperClassName(groupId);
+    if (!className) throw problem('structure-group-invalid', 'A wrapper group identity must derive a CSS module class name.');
+    const existing = findWrapperBlock(content, groupId, className);
+    if (layout === null) {
+      if (!existing) throw stale(`The managed wrapper block for ${groupId} is missing.`);
+      let { start, end } = existing;
+      if (content.startsWith(eol, end)) end += eol.length;
+      if (start >= 2 * eol.length && content.slice(start - 2 * eol.length, start) === eol + eol) start -= eol.length;
+      content = content.slice(0, start) + content.slice(end);
+      continue;
+    }
+    if (wrapperClassReferenced(content, className, existing ? [existing] : [])) {
+      throw problem('structure-wrapper-class-collision', `The stylesheet already styles .${className}; choose another group identity.`);
+    }
+    const block = wrapperBlock(groupId, className, layout, contract, eol);
+    if (existing) { content = content.slice(0, existing.start) + block + content.slice(existing.end); continue; }
+    content = content.length ? `${content}${content.endsWith(eol) ? '' : eol}${eol}${block}${eol}` : `${block}${eol}`;
+  }
+  return content;
+}

package/node/source-structure.mjs

@@ -0,0 +1,404 @@
+import { createHash } from 'node:crypto';
+import ts from 'typescript';
+import { VOID_ELEMENTS as VOID, applyWrapperEdits, readWrapperLayout, wrapperClassName, wrapperClosing, wrapperContractProblem,
+  wrapperLayout, wrapperLayoutProblem, wrapperOpening, wrapperTagName } from './source-structure-wrapper-codec.mjs';
+export { reconcileJsxStructurePlan } from './source-structure-reconcile.mjs';
+
+const fingerprint = source => createHash('sha256').update(source, 'utf8').digest('hex');
+const relative = value => typeof value === 'string' && value.length > 0 && !/^[a-z]:/i.test(value)
+  && !/[\\\x00-\x1f\x7f?#]/.test(value) && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
+const identity = value => typeof value === 'string' && value.trim() === value && value.length > 0 && !['__proto__', 'constructor', 'prototype'].includes(value);
+const boundedText = value => typeof value === 'string' && !value.includes('\0') && Buffer.byteLength(value, 'utf8') <= 32 * 1024 * 1024
+  && Buffer.from(value, 'utf8').toString('utf8') === value;
+const container = node => ts.isJsxElement(node) || ts.isJsxFragment(node);
+const selectable = node => container(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxExpression(node) || ts.isJsxText(node);
+// A same-line whitespace child is rendered text; blank multiline indentation is not.
+const blankText = value => value.length === 0 || /^[ \t\r\n]*$/.test(value) && /[\r\n]/.test(value);
+function fail(code, message, location = {}) { throw Object.assign(new Error(message), { diagnostic: { code, message, ...location } }); }
+function parse(file, source) {
+  if (!relative(file) || typeof source !== 'string' || !/\.(?:[cm]?[jt]s|[jt]sx)$/i.test(file)) fail('structure-file-invalid', 'A JSX source requires a normalized JavaScript or TypeScript path.', { file });
+  const kind = /\.tsx$/i.test(file) ? ts.ScriptKind.TSX : /\.(?:[cm]?ts)$/i.test(file) ? ts.ScriptKind.TS : ts.ScriptKind.JSX;
+  const ast = /** @type {import('typescript').SourceFile & { parseDiagnostics: readonly import('typescript').Diagnostic[] }} */ (ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, kind));
+  if (ast.parseDiagnostics.length) fail('structure-syntax-invalid', 'Source must parse before and after structural changes.', { file });
+  return ast;
+}
+function bounds(node, ast) { return { start: ts.isJsxText(node) ? node.pos : node.getStart(ast), end: node.end }; }
+function tag(node, ast) {
+  return ts.isJsxElement(node) ? node.openingElement.tagName.getText(ast) : ts.isJsxSelfClosingElement(node) ? node.tagName.getText(ast) : undefined;
+}
+function island(node) {
+  while (container(node.parent) && node.parent.children.includes(node)) node = node.parent;
+  return node;
+}
+/** Host wrapper evidence for identity and reimport: the contract plus the complete stylesheet bytes. */
+function wrapperEvidence(wrapper, file) {
+  if (wrapper === undefined) return undefined;
+  if (!wrapper || typeof wrapper !== 'object' || Array.isArray(wrapper) || Object.keys(wrapper).some(key => !['contract', 'source'].includes(key)) || !boundedText(wrapper.source)) {
+    fail('structure-wrapper-invalid', 'Wrapper evidence requires the host contract and the complete stylesheet source.', { file });
+  }
+  const problem = wrapperContractProblem(wrapper.contract);
+  if (problem) fail('structure-wrapper-invalid', problem, { file });
+  return wrapper;
+}
+/** A generated wrapper is exactly the canonical element and its managed stylesheet block; anything else is a plain element. */
+function generatedWrapper(text, nodeId, contract, stylesheet) {
+  const className = wrapperClassName(nodeId);
+  if (!className || !text.startsWith(wrapperOpening(contract, className)) || !text.endsWith(wrapperClosing(contract))) return null;
+  let layout;
+  try { layout = readWrapperLayout(stylesheet, nodeId, className, contract); }
+  catch (error) { fail(error.code ?? 'structure-wrapper-stale', error.message, { file: contract.stylesheet, nodeId }); }
+  return layout ? { className, layout } : null;
+}
+
+/** Read a host-selected JSX root without evaluating props, handlers, or expressions. */
+export function inspectJsxStructureSource({ file, source, rootStart, opaqueNodeStarts = [] }) {
+  const ast = parse(file, source); const candidates = [];
+  const visit = node => {
+    if ((container(node) || ts.isJsxSelfClosingElement(node)) && node.getStart(ast) === rootStart) candidates.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(ast);
+  if (candidates.length !== 1) fail('structure-root-invalid', 'The selected root must identify one complete JSX element or fragment.', { file });
+  if (!Array.isArray(opaqueNodeStarts) || opaqueNodeStarts.some(start => !Number.isSafeInteger(start) || start < 0)
+    || new Set(opaqueNodeStarts).size !== opaqueNodeStarts.length) fail('structure-opaque-invalid', 'Opaque roots require unique source offsets.', { file });
+  const opaque = new Set(opaqueNodeStarts); const seen = new Set(); const anchors = []; const nodes = [];
+  const project = (node, parentId, runtimePath) => {
+    const { start, end } = bounds(node, ast); const nodeId = `${file}:${start}`;
+    const kind = ts.isJsxFragment(node) ? 'fragment' : ts.isJsxExpression(node) ? 'expression' : ts.isJsxText(node) ? 'text' : 'element';
+    const projected = { nodeId, parentId, children: [], kind, runtimePath, start, end };
+    const tagName = tag(node, ast); if (tagName) projected.tagName = tagName;
+    const attributes = ts.isJsxElement(node) ? node.openingElement.attributes : ts.isJsxSelfClosingElement(node) ? node.attributes : undefined;
+    const attribute = attributes?.properties.find(item => ts.isJsxAttribute(item) && item.name.getText(ast) === 'className');
+    const literal = attribute && ts.isJsxAttribute(attribute) ? attribute.initializer : undefined;
+    if (literal && ts.isStringLiteral(literal)) projected.className = literal.text;
+    else if (literal && ts.isJsxExpression(literal) && literal.expression && ts.isStringLiteral(literal.expression)) projected.className = literal.expression.text;
+    anchors.push({ nodeId, file, start, end, expected: source.slice(start, end) }); nodes.push(projected);
+    if (opaque.has(start)) { seen.add(start); return nodeId; }
+    if (container(node)) {
+      let index = 0;
+      for (const child of node.children) {
+        if (ts.isJsxText(child) && blankText(source.slice(child.pos, child.end))) continue;
+        if (ts.isJsxExpression(child) && !child.expression) continue;
+        projected.children.push(project(child, nodeId, [...runtimePath, index++]));
+      }
+    }
+    return nodeId;
+  };
+  project(candidates[0], null, []);
+  if (seen.size !== opaque.size) fail('structure-opaque-invalid', 'Every opaque offset must identify a visited source node.', { file });
+  return { anchors, nodes };
+}
+
+/** Capture stable IDs for exact emitted source; persist with that source in the same reviewed plan. */
+export function createJsxStructureIdentity({ file, source, rootId, anchors, opaqueNodeIds = [], wrapper }) {
+  if (typeof source !== 'string' || !Array.isArray(anchors) || !Array.isArray(opaqueNodeIds)
+    || anchors.some(anchor => anchor?.file !== file || source.slice(anchor.start, anchor.end) !== anchor.expected)) {
+    fail('structure-identity-invalid', 'Identity evidence must describe the complete emitted source ranges.', { file });
+  }
+  const result = { version: 1, file, sourceSha256: fingerprint(source), rootId,
+    opaqueNodeIds: [...opaqueNodeIds], anchors: anchors.map(({ nodeId, start, end }) => ({ nodeId, start, end })) };
+  // Generated wrappers are recorded from the emitted element and its managed block, then proved again as a reimport.
+  const { wrappers } = restore({ file, source, evidence: result, wrapper, detect: true });
+  if (wrappers.length) result.wrappers = wrappers;
+  restore({ file, source, evidence: result, wrapper, detect: false });
+  return result;
+}
+
+/** Rebuild hierarchy from the AST, retaining only IDs proved against the exact source bytes. */
+export function reimportJsxStructureSource({ file, source, identity, wrapper }) {
+  const { anchors, nodes } = restore({ file, source, evidence: identity, wrapper, detect: false });
+  return { anchors, nodes };
+}
+
+function restore({ file, source, evidence, wrapper: wrapperInput, detect }) {
+  const wrapper = wrapperEvidence(wrapperInput, file);
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence) || evidence.version !== 1
+    || Object.keys(evidence).some(key => !['version', 'file', 'sourceSha256', 'rootId', 'opaqueNodeIds', 'anchors', 'wrappers'].includes(key))
+    || !relative(file) || evidence.file !== file || !boundedText(source)
+    || !/^[a-f0-9]{64}$/.test(evidence.sourceSha256 ?? '') || !identity(evidence.rootId)
+    || !Array.isArray(evidence.anchors) || !evidence.anchors.length || evidence.anchors.length > 5000
+    || !Array.isArray(evidence.opaqueNodeIds) || evidence.opaqueNodeIds.length > evidence.anchors.length) {
+    fail('structure-identity-invalid', 'Source identity requires a bounded, exact file, root and complete anchor table.', { file });
+  }
+  if (fingerprint(source) !== evidence.sourceSha256) fail('structure-identity-stale', 'The source bytes differ from their persisted identity. Reconcile source before importing.', { file });
+  const byId = new Map(); const byRange = new Map();
+  for (const anchor of evidence.anchors) {
+    if (!anchor || typeof anchor !== 'object' || Array.isArray(anchor)
+      || Object.keys(anchor).some(key => !['nodeId', 'start', 'end'].includes(key))
+      || !identity(anchor.nodeId) || byId.has(anchor.nodeId) || !Number.isSafeInteger(anchor.start) || !Number.isSafeInteger(anchor.end)
+      || anchor.start < 0 || anchor.end <= anchor.start || anchor.end > source.length || byRange.has(`${anchor.start}:${anchor.end}`)) {
+      fail('structure-identity-invalid', 'Every persisted identity must name a unique, complete source range.', { file });
+    }
+    byId.set(anchor.nodeId, anchor); byRange.set(`${anchor.start}:${anchor.end}`, anchor.nodeId);
+  }
+  const recorded = evidence.wrappers === undefined ? [] : evidence.wrappers;
+  if (!Array.isArray(recorded) || recorded.length > byId.size || new Set(recorded.map(entry => entry?.nodeId)).size !== recorded.length
+    || recorded.some(entry => !entry || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).some(key => !['nodeId', 'className'].includes(key))
+      || !identity(entry.nodeId) || !byId.has(entry.nodeId) || entry.className !== wrapperClassName(entry.nodeId))) {
+    fail('structure-identity-invalid', 'Recorded wrapper groups must name persisted nodes with their derived class names.', { file });
+  }
+  if (recorded.length && !wrapper) fail('structure-identity-invalid', 'Recorded wrapper groups require the host wrapper contract and stylesheet.', { file });
+  const root = byId.get(evidence.rootId);
+  if (!root || new Set(evidence.opaqueNodeIds).size !== evidence.opaqueNodeIds.length
+    || evidence.opaqueNodeIds.some(id => !byId.has(id))) fail('structure-identity-invalid', 'Root and opaque boundaries must name distinct persisted source nodes.', { file });
+  const projected = inspectJsxStructureSource({ file, source, rootStart: root.start,
+    opaqueNodeStarts: evidence.opaqueNodeIds.map(id => byId.get(id).start) });
+  const ids = new Map(projected.nodes.map(node => [node.nodeId, byRange.get(`${node.start}:${node.end}`)]));
+  if (ids.size !== byId.size || [...ids.values()].some(id => id === undefined) || ids.get(projected.nodes[0].nodeId) !== evidence.rootId) {
+    fail('structure-identity-mismatch', 'The persisted identity must cover exactly the complete projected AST tree.', { file });
+  }
+  const nodes = projected.nodes.map(node => ({ ...node, nodeId: ids.get(node.nodeId),
+    parentId: node.parentId === null ? null : ids.get(node.parentId), children: node.children.map(id => ids.get(id)) }));
+  const detected = new Map();
+  if (wrapper) {
+    for (const node of nodes) {
+      if (node.kind !== 'element' || node.tagName !== wrapperTagName(wrapper.contract)) continue;
+      const box = generatedWrapper(source.slice(node.start, node.end), node.nodeId, wrapper.contract, wrapper.source);
+      if (box) detected.set(node.nodeId, box);
+    }
+  }
+  if (!detect && (detected.size !== recorded.length || recorded.some(entry => detected.get(entry.nodeId)?.className !== entry.className))) {
+    fail('structure-identity-mismatch', 'Recorded wrapper groups must match the generated elements and their stylesheet blocks exactly.', { file });
+  }
+  for (const node of nodes) {
+    const box = detected.get(node.nodeId);
+    if (box) { node.layout = box.layout; node.wrapper = { className: box.className }; }
+  }
+  return {
+    anchors: projected.anchors.map(anchor => ({ ...anchor, nodeId: ids.get(anchor.nodeId) })),
+    nodes,
+    wrappers: [...detected].map(([nodeId, box]) => ({ nodeId, className: box.className })),
+  };
+}
+
+/** Compile source-owned hierarchy operations to an immutable-source file plan; never write files. */
+export function compileJsxStructurePlan(input) {
+  try { return compile(input); }
+  catch (error) {
+    if (error?.diagnostic) return { status: 'blocked', diagnostics: [error.diagnostic] };
+    throw error;
+  }
+}
+
+function compile(input) {
+  const { sourceRevision, files, anchors, operations, allowedFiles, excludedSourcePrefixes = [], wrapper } = input ?? {};
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(sourceRevision ?? '') || !Array.isArray(files) || !files.length || files.length > 1000
+    || !Array.isArray(anchors) || !anchors.length || anchors.length > 5000 || !Array.isArray(operations) || operations.length > 100
+    || !Array.isArray(allowedFiles) || !Array.isArray(excludedSourcePrefixes)) fail('structure-input-invalid', 'Structural compilation requires an exact revision, bounded source evidence, and explicit file policy.');
+  if (wrapper !== undefined) { const problem = wrapperContractProblem(wrapper); if (problem) fail('structure-wrapper-invalid', problem); }
+  const allowed = new Set(allowedFiles); const excluded = excludedSourcePrefixes.map(value => typeof value === 'string' ? value.replace(/\/$/, '') : value);
+  if ([...allowed, ...excluded].some(value => !relative(value))) fail('structure-policy-invalid', 'Source policies require normalized relative paths.');
+  const sources = new Map(); let bytes = 0;
+  for (const entry of files) {
+    if (!entry || !relative(entry.file) || sources.has(entry.file) || typeof entry.source !== 'string' || !/^[a-f0-9]{64}$/.test(entry.sha256 ?? '')) fail('structure-file-invalid', 'Source files require unique paths and complete hashes.');
+    const encoded = Buffer.from(entry.source, 'utf8'); bytes += encoded.length;
+    if (encoded.toString('utf8') !== entry.source || bytes > 32 * 1024 * 1024 || entry.source.includes('\0')) fail('structure-file-invalid', 'Source files require bounded UTF-8 content.', { file: entry.file });
+    if (fingerprint(entry.source) !== entry.sha256) fail('structure-source-stale', 'The complete source file no longer matches its hash.', { file: entry.file });
+    sources.set(entry.file, { ...entry, ast: null, matches: null, roots: [] });
+  }
+  const models = new Map(); const ranges = new Map(); const byNode = new Map();
+  for (const anchor of anchors) {
+    const source = sources.get(anchor?.file);
+    if (!anchor || !identity(anchor.nodeId) || models.has(anchor.nodeId) || !source || !Number.isSafeInteger(anchor.start) || !Number.isSafeInteger(anchor.end)
+      || anchor.start < 0 || anchor.end <= anchor.start || anchor.end > source.source.length || typeof anchor.expected !== 'string') fail('structure-anchor-invalid', 'Source anchors require unique identities and complete JSX ranges.');
+    if (source.source.slice(anchor.start, anchor.end) !== anchor.expected) fail('structure-source-stale', 'The source anchor no longer matches its exact snippet.', { file: anchor.file, nodeId: anchor.nodeId });
+    if (!source.ast) {
+      source.ast = parse(anchor.file, source.source); source.matches = new Map();
+      const visit = node => { if (selectable(node)) { const range = bounds(node, source.ast); source.matches.set(`${range.start}:${range.end}`, node); } ts.forEachChild(node, visit); };
+      visit(source.ast);
+    }
+    const key = `${anchor.file}:${anchor.start}:${anchor.end}`; const node = source.matches.get(`${anchor.start}:${anchor.end}`);
+    if (!node || ranges.has(key)) fail('structure-anchor-invalid', 'Each anchor must identify a distinct complete JSX node.', { file: anchor.file, nodeId: anchor.nodeId });
+    ranges.set(key, anchor.nodeId); byNode.set(node, anchor.nodeId);
+    models.set(anchor.nodeId, { ...anchor, node, source, island: island(node), parentId: null, nested: [], children: null, tail: '', active: true });
+  }
+  for (const source of sources.values()) {
+    const ordered = [...models.values()].filter(model => model.source === source).sort((left, right) => left.start - right.start || right.end - left.end);
+    const stack = [];
+    for (const model of ordered) {
+      while (stack.length && stack.at(-1).end <= model.start) stack.pop();
+      if (stack.length && model.end > stack.at(-1).end) fail('structure-overlap', 'Source anchors must have disjoint or fully nested ranges.', { file: model.file });
+      if (stack.length) stack.at(-1).nested.push(model.nodeId); else source.roots.push(model.nodeId);
+      stack.push(model);
+      if (container(model.node.parent) && model.node.parent.children.includes(model.node)) model.parentId = byNode.get(model.node.parent) ?? null;
+    }
+  }
+  const changedParents = new Set();
+  const get = nodeId => { const model = models.get(nodeId); if (!model?.active) fail('structure-node-missing', 'The operation targets an absent source-owned node.', { nodeId }); return model; };
+  const writableFile = (file, nodeId) => { if (!allowed.has(file) || excluded.some(prefix => file === prefix || file.startsWith(`${prefix}/`))) fail('structure-file-excluded', 'The host has not allowed structural edits in this source file.', { file, nodeId }); };
+  const writable = model => writableFile(model.file, model.nodeId);
+  const stylesheet = wrapper ? sources.get(wrapper.stylesheet) : undefined;
+  // Null removes a managed block; a layout writes it in place or appends it. Applied once after JSX rendering.
+  const wrapperEdits = new Map(); const removedOriginals = new Set();
+  const requireStylesheet = nodeId => {
+    if (!stylesheet) fail('structure-wrapper-stylesheet-missing', 'Wrapper groups require the declared stylesheet source in the same plan.', { file: wrapper.stylesheet, nodeId });
+    writableFile(wrapper.stylesheet, nodeId);
+  };
+  const managedWrapper = model => {
+    if (!wrapper || !model.node || !ts.isJsxElement(model.node) || tag(model.node, model.source.ast) !== wrapperTagName(wrapper)) return null;
+    const className = wrapperClassName(model.nodeId);
+    if (!className || !model.expected.startsWith(wrapperOpening(wrapper, className)) || !model.expected.endsWith(wrapperClosing(wrapper))) return null;
+    requireStylesheet(model.nodeId);
+    return generatedWrapper(model.expected, model.nodeId, wrapper, stylesheet.source);
+  };
+  const children = model => {
+    writable(model);
+    if (model.children) return model.children;
+    const node = model.node; const name = tag(node, model.source.ast);
+    if (!container(node) && !ts.isJsxSelfClosingElement(node) || name && (!/^[a-z][a-z0-9]*$/.test(name) || VOID.has(name))) fail('structure-receiver-unsupported', 'Only intrinsic non-void JSX elements and fragments can receive structural changes.', { nodeId: model.nodeId });
+    const attributes = ts.isJsxElement(node) ? node.openingElement.attributes : ts.isJsxSelfClosingElement(node) ? node.attributes : null;
+    if (attributes?.properties.some(attribute => ts.isJsxSpreadAttribute(attribute) || ['children', 'dangerouslySetInnerHTML'].includes(attribute.name.getText(model.source.ast)))) fail('structure-receiver-unsupported', 'A source receiver cannot have spread, children, or inner-HTML attributes.', { nodeId: model.nodeId });
+    model.children = [];
+    if (ts.isJsxSelfClosingElement(node)) return model.children;
+    const opening = ts.isJsxElement(node) ? node.openingElement : node.openingFragment;
+    const closing = ts.isJsxElement(node) ? node.closingElement : node.closingFragment;
+    let cursor = opening.end;
+    for (const child of node.children) {
+      if (ts.isJsxText(child) && blankText(model.source.source.slice(child.pos, child.end))) continue;
+      if (ts.isJsxText(child) || ts.isJsxExpression(child) && !child.expression) fail('structure-trivia-ambiguous', 'Rendered JSX text and standalone comments cannot be reassigned by a hierarchy edit.', { nodeId: model.nodeId });
+      const id = byNode.get(child);
+      if (!id) fail('structure-child-unowned', 'Every direct JSX child of an edited parent requires an exact source anchor.', { nodeId: model.nodeId });
+      model.children.push({ id, leading: model.source.source.slice(cursor, child.getStart(model.source.ast)) }); cursor = child.end;
+    }
+    model.tail = model.source.source.slice(cursor, closing.getStart(model.source.ast));
+    return model.children;
+  };
+  const parentOf = model => { if (!model.parentId) fail('structure-root-unsupported', 'A source root cannot be removed or moved without its owned JSX parent.', { nodeId: model.nodeId }); return get(model.parentId); };
+  const position = (list, id) => { const index = list.findIndex(item => item.id === id); if (index < 0) fail('structure-parent-mismatch', 'The source parent does not contain the selected node.', { nodeId: id }); return index; };
+  for (const operation of operations) {
+    if (!operation || !['reorder', 'reparent', 'group', 'ungroup'].includes(operation.kind)) fail('structure-operation-invalid', 'The requested structural operation is unsupported.');
+    const keys = { reorder: ['kind', 'parentId', 'children'], reparent: ['kind', 'nodeId', 'parentId', 'index'], group: ['kind', 'nodeIds', 'groupId', 'layout'], ungroup: ['kind', 'nodeId'] }[operation.kind];
+    if (Object.keys(operation).some(key => !keys.includes(key))) fail('structure-operation-invalid', 'A structural operation contains an unsupported field.');
+    if (operation.kind === 'reorder') {
+      const parent = get(operation.parentId); const list = children(parent);
+      if (!Array.isArray(operation.children) || operation.children.length !== list.length || new Set(operation.children).size !== list.length || operation.children.some(id => !list.some(item => item.id === id))) fail('structure-children-mismatch', 'A reorder must name every current direct child exactly once.', { nodeId: parent.nodeId });
+      parent.children = operation.children.map(id => list.find(item => item.id === id)); changedParents.add(parent.nodeId);
+    } else if (operation.kind === 'reparent') {
+      const node = get(operation.nodeId); const from = parentOf(node); const parent = get(operation.parentId);
+      if (node.file !== parent.file || node.island !== parent.island) fail('structure-scope-crossing', 'Nodes cannot cross source files, expression, function, or conditional render boundaries.', { nodeId: node.nodeId });
+      for (let cursor = parent; cursor; cursor = cursor.parentId ? get(cursor.parentId) : null) if (cursor === node) fail('structure-cycle', 'A node cannot become its own descendant.', { nodeId: node.nodeId });
+      const sourceChildren = children(from); const targetChildren = children(parent); const oldIndex = position(sourceChildren, node.nodeId);
+      const maximum = targetChildren.length - (from === parent ? 1 : 0);
+      if (!Number.isSafeInteger(operation.index) || operation.index < 0 || operation.index > maximum) fail('structure-index-invalid', 'The destination index must address the final direct-child list.', { nodeId: parent.nodeId });
+      const [entry] = sourceChildren.splice(oldIndex, 1); targetChildren.splice(operation.index, 0, entry); node.parentId = parent.nodeId;
+      changedParents.add(from.nodeId); changedParents.add(parent.nodeId);
+    } else if (operation.kind === 'group') {
+      const previousGroup = models.get(operation.groupId);
+      if (!Array.isArray(operation.nodeIds) || !operation.nodeIds.length || new Set(operation.nodeIds).size !== operation.nodeIds.length || !identity(operation.groupId) || previousGroup?.active) fail('structure-group-invalid', 'A fragment group requires distinct children and an available stable identity.');
+      let box = null;
+      if (operation.layout !== undefined) {
+        if (!wrapper) fail('structure-wrapper-undeclared', 'A group with a layout requires a host wrapper declaration.', { nodeId: operation.groupId });
+        const problem = wrapperLayoutProblem(operation.layout, wrapper);
+        if (problem) fail('structure-layout-invalid', problem, { nodeId: operation.groupId });
+        const className = wrapperClassName(operation.groupId);
+        if (!className) fail('structure-group-invalid', 'A wrapper group identity must derive a CSS module class name.', { nodeId: operation.groupId });
+        requireStylesheet(operation.groupId);
+        box = { className, layout: wrapperLayout(operation.layout) };
+      }
+      const selected = operation.nodeIds.map(get); const parent = parentOf(selected[0]); const list = children(parent);
+      if (previousGroup && (previousGroup.file !== parent.file || previousGroup.island !== parent.island
+        || previousGroup.node && !ts.isJsxFragment(previousGroup.node) && !previousGroup.removedWrapper)) fail('structure-group-invalid', 'A removed fragment identity can only be reused within its original source island.');
+      const first = position(list, selected[0].nodeId);
+      if (selected.some((node, index) => node.parentId !== parent.nodeId || list[first + index]?.id !== node.nodeId)) fail('structure-group-invalid', 'A fragment group requires one contiguous, ordered sibling range.');
+      const entries = list.splice(first, selected.length); const leading = entries[0].leading; entries[0] = { ...entries[0], leading: '' };
+      const group = { nodeId: operation.groupId, file: parent.file, source: parent.source, node: null, island: parent.island, parentId: parent.nodeId, children: entries, nested: [], tail: '', active: true, wrapper: box };
+      models.set(group.nodeId, group); selected.forEach(node => { node.parentId = group.nodeId; });
+      if (box) wrapperEdits.set(group.nodeId, box.layout);
+      list.splice(first, 0, { id: group.nodeId, leading }); changedParents.add(parent.nodeId);
+    } else {
+      const group = get(operation.nodeId); const parent = parentOf(group);
+      let removed = null;
+      if (group.node && !ts.isJsxFragment(group.node)) {
+        removed = managedWrapper(group);
+        if (!removed) fail('structure-ungroup-unsupported', 'Only anonymous JSX fragments and generated wrapper elements can be removed without discarding element behavior.', { nodeId: group.nodeId });
+      }
+      const list = children(parent); const members = children(group); const index = position(list, group.nodeId); const entry = list[index];
+      const promoted = members.map(member => ({ ...member }));
+      if (promoted.length) promoted[0].leading = entry.leading + promoted[0].leading;
+      const leftover = (promoted.length ? '' : entry.leading) + group.tail;
+      list.splice(index, 1, ...promoted);
+      if (list[index + promoted.length]) list[index + promoted.length].leading = leftover + list[index + promoted.length].leading;
+      else parent.tail = leftover + parent.tail;
+      promoted.forEach(member => { get(member.id).parentId = parent.nodeId; }); group.active = false; changedParents.add(parent.nodeId);
+      if (removed) { group.removedWrapper = removed; removedOriginals.add(group.nodeId); wrapperEdits.set(group.nodeId, null); }
+      // A wrapper created earlier in this batch leaves no block; an original block already removed stays removed.
+      else if (group.wrapper) { if (removedOriginals.has(group.nodeId)) wrapperEdits.set(group.nodeId, null); else wrapperEdits.delete(group.nodeId); }
+    }
+  }
+  const modified = [...changedParents].map(id => models.get(id)).filter(model => model.active && model.node);
+  for (const left of modified) for (const right of modified) {
+    if (left !== right && left.file === right.file && left.start < right.end && right.start < left.end && left.island !== right.island) fail('structure-overlap', 'One batch cannot edit both an opaque expression and a render tree inside it.', { file: left.file });
+  }
+  const part = text => ({ text, positions: new Map() });
+  const join = parts => {
+    let text = ''; const positions = new Map();
+    for (const item of parts) {
+      for (const [id, range] of item.positions) {
+        if (positions.has(id)) fail('structure-anchor-duplicate', 'A source-owned node would be emitted more than once.', { nodeId: id });
+        positions.set(id, { start: text.length + range.start, end: text.length + range.end });
+      }
+      text += item.text;
+    }
+    return { text, positions };
+  };
+  const rendering = new Set();
+  const region = (source, start, end, nested) => {
+    let cursor = start; const parts = [];
+    for (const id of nested) {
+      const child = models.get(id);
+      // Recreated groups are emitted by their current parent, never by an old source range.
+      if (!child.node || child.start < start || child.end > end) continue;
+      parts.push(part(source.source.slice(cursor, child.start)), render(child)); cursor = child.end;
+    }
+    parts.push(part(source.source.slice(cursor, end))); return join(parts);
+  };
+  const render = model => {
+    if (!model.active) fail('structure-anchor-loss', 'An inactive source anchor remained in the emitted hierarchy.', { nodeId: model.nodeId });
+    if (rendering.has(model.nodeId)) fail('structure-cycle', 'A structural edit created a source cycle.', { nodeId: model.nodeId });
+    rendering.add(model.nodeId);
+    let result;
+    if (!model.children) result = region(model.source, model.start, model.end, model.nested);
+    else {
+      let opening; let closing;
+      if (!model.node) {
+        opening = part(model.wrapper ? wrapperOpening(wrapper, model.wrapper.className) : '<>');
+        closing = part(model.wrapper ? wrapperClosing(wrapper) : '</>');
+      } else if (ts.isJsxSelfClosingElement(model.node)) {
+        opening = part(model.expected.replace(/\/>$/, '>')); closing = part(`</${tag(model.node, model.source.ast)}>`);
+        if (!model.children.length) { opening = part(model.expected); closing = part(''); }
+      } else {
+        const open = ts.isJsxElement(model.node) ? model.node.openingElement : model.node.openingFragment;
+        const close = ts.isJsxElement(model.node) ? model.node.closingElement : model.node.closingFragment;
+        opening = region(model.source, model.start, open.end, model.nested); closing = part(model.source.source.slice(close.getStart(model.source.ast), model.end));
+      }
+      result = join([opening, ...model.children.flatMap(child => [part(child.leading), render(get(child.id))]), part(model.tail), closing]);
+    }
+    rendering.delete(model.nodeId); result.positions.set(model.nodeId, { start: 0, end: result.text.length }); return result;
+  };
+  const updatedAnchors = []; const changes = [];
+  for (const source of sources.values()) {
+    const result = region(source, 0, source.source.length, source.roots);
+    if (result.text !== source.source) {
+      parse(source.file, result.text);
+      changes.push({ file: source.file, beforeSha256: source.sha256, content: result.text });
+    }
+    for (const [nodeId, range] of result.positions) updatedAnchors.push({ nodeId, file: source.file, ...range, expected: result.text.slice(range.start, range.end) });
+  }
+  if (wrapperEdits.size) {
+    let content;
+    try { content = applyWrapperEdits(stylesheet.source, wrapperEdits, wrapper); }
+    catch (error) { fail(error.code ?? 'structure-wrapper-stale', error.message, { file: wrapper.stylesheet }); }
+    for (const [nodeId, layout] of wrapperEdits) {
+      if (layout === null) continue;
+      let restored;
+      try { restored = readWrapperLayout(content, nodeId, wrapperClassName(nodeId), wrapper); }
+      catch (error) { fail(error.code ?? 'structure-wrapper-stale', error.message, { file: wrapper.stylesheet, nodeId }); }
+      if (!restored || JSON.stringify(restored) !== JSON.stringify(layout)) fail('structure-wrapper-stale', 'The generated wrapper block does not read back to its layout.', { file: wrapper.stylesheet, nodeId });
+    }
+    if (content !== stylesheet.source) changes.push({ file: wrapper.stylesheet, beforeSha256: stylesheet.sha256, content });
+  }
+  if (updatedAnchors.length !== [...models.values()].filter(model => model.active).length) fail('structure-anchor-loss', 'The emitted source does not contain every retained source anchor exactly once.');
+  updatedAnchors.sort((left, right) => left.file.localeCompare(right.file) || left.start - right.start || right.end - left.end);
+  if (!changes.length) return { status: 'unchanged', anchors: updatedAnchors };
+  return { status: 'ready', payload: { version: 1, sourceRevision, proofs: files.map(({ file, sha256 }) => ({ file, sha256 })), changes }, anchors: updatedAnchors };
+}