@pygmalionjs/pygmalion 0.8.1 → 0.10.0

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 };
+}

package/node/token-source-references.mjs

@@ -0,0 +1,136 @@
+import path from 'node:path';
+import ts from 'typescript';
+
+const names = /--[A-Za-z0-9_\-\u0080-\uFFFF]+/g;
+const unwrap = node => node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) && node.type.getText() === 'const') ? unwrap(node.expression) : node;
+const walk = (node, visit) => { visit(node); ts.forEachChild(node, child => walk(child, visit)); };
+
+/** Conservative source coverage: any diagnostic returns the original source and no edits. */
+export function rewriteTokenSourceReferences({ file, source, renames }) {
+  const diagnostics = []; const references = []; const proposed = new Map(); const handled = new Set();
+  const changes = new Map();
+  const report = (code, message, start, name) => diagnostics.push({ code, message, file, ...(start === undefined ? {} : { start }), ...(name ? { name } : {}) });
+  if (typeof source !== 'string' || typeof file !== 'string' || !Array.isArray(renames)) throw new TypeError('Source reference scanning requires a file, source, and rename list.');
+  for (const { from, to } of renames) {
+    if (!/^--[A-Za-z0-9_-]+$/.test(from) || to !== null && !/^--[A-Za-z0-9_-]+$/.test(to) || changes.has(from)) report('invalid-rename', 'Rename entries require unique, exact supported custom-property names.');
+    else changes.set(from, to);
+  }
+  const destinations = [...changes.values()].filter(value => value !== null);
+  if (new Set(destinations).size !== destinations.length) report('rename-collision', 'Two custom properties cannot be renamed to the same name.');
+  const edit = (start, end, after) => {
+    const before = source.slice(start, end); const prior = proposed.get(start);
+    if (prior && (prior.end !== end || prior.after !== after)) report('overlapping-edit', 'Shared source requires incompatible replacements.', start);
+    else if (before !== after) proposed.set(start, { start, end, before, after });
+  };
+  const reference = (name, start, end, kind = 'static') => {
+    references.push({ name, start, end, kind }); handled.add(start);
+    if (!changes.has(name)) return;
+    const to = changes.get(name);
+    if (to === null) report('token-in-use', 'A removed custom property still has a source reference.', start, name);
+    else if (kind === 'static') edit(start, end, to);
+  };
+  const overlaps = (prefix, suffix = '') => [...changes.keys()].some(name => name.startsWith(prefix) && name.endsWith(suffix));
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.JSX, source);
+  const comments = [];
+  while (scanner.scan() !== ts.SyntaxKind.EndOfFileToken) {
+    if ([ts.SyntaxKind.SingleLineCommentTrivia, ts.SyntaxKind.MultiLineCommentTrivia].includes(scanner.getToken())) comments.push([scanner.getTokenPos(), scanner.getTextPos()]);
+  }
+  const inComment = offset => comments.some(([start, end]) => offset >= start && offset < end);
+  const extension = path.extname(file).toLowerCase();
+  if (['.css', '.scss'].includes(extension)) {
+    const quoted = [...source.matchAll(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g)].map(match => [match.index, match.index + match[0].length]);
+    for (const match of source.matchAll(/var\(([^)]*)\)/g)) {
+      if (!inComment(match.index) && /\$|#\{|\\/.test(match[1]) && overlaps(match[1].match(/^\s*(--[\w-]*)/)?.[1] ?? '')) report('source-coverage', 'Dynamic or escaped stylesheet names require a host-resolved source contract.', match.index);
+    }
+    for (const match of source.matchAll(/(--[\w-]*)(?:#\{[^}]*\}|\$[\w-]+)/g)) {
+      if (!inComment(match.index) && overlaps(match[1])) report('source-coverage', 'Interpolated stylesheet names require a host-resolved source contract.', match.index);
+    }
+    for (const match of source.matchAll(names)) {
+      const start = match.index; const end = start + match[0].length;
+      if (inComment(start)) continue;
+      const literal = quoted.some(([left, right]) => start >= left && end <= right);
+      const before = source.slice(0, start); const after = source.slice(end);
+      if (!literal && (/var\(\s*$/.test(before) || /^\s*:/.test(after) || /@property\s+$/.test(before))) reference(match[0], start, end);
+    }
+  } else if (['.ts', '.tsx', '.js', '.jsx', '.mjs', '.mts', '.cjs', '.cts'].includes(extension)) {
+    const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ['.tsx', '.jsx'].includes(extension) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    if (/** @type {ts.SourceFile & { parseDiagnostics: unknown[] }} */ (parsed).parseDiagnostics.length) report('source-coverage', 'The source cannot be parsed completely.');
+    const contexts = new Map();
+    walk(parsed, node => {
+      if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        const raw = node.getText(parsed); const prefix = raw.match(/--[\w-]*/)?.[0] ?? '';
+        if ((raw.includes('var(') || prefix) && overlaps(prefix)) report('source-coverage', 'Concatenated custom-property names require a host-resolved source contract.', node.getStart(parsed));
+      }
+      if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        const start = node.getStart(parsed) + 1; const raw = source.slice(start, node.end - 1);
+        const parent = node.parent;
+        const propertyName = ts.isPropertyAssignment(parent) && parent.name === node;
+        const apiName = ts.isCallExpression(parent) && parent.arguments[0] === node && ts.isPropertyAccessExpression(parent.expression)
+          && ['setProperty', 'getPropertyValue', 'removeProperty'].includes(parent.expression.name.text);
+        for (const match of node.text.matchAll(names)) {
+          const position = start + match.index;
+          if (raw !== node.text) { if (changes.has(match[0])) report('source-coverage', 'Escaped string references require an explicit source contract.', start, match[0]); continue; }
+          if (/var\(\s*$/.test(raw.slice(0, match.index)) || match[0] === raw && (propertyName || apiName)) reference(match[0], position, position + match[0].length);
+        }
+      }
+      if (!ts.isTemplateExpression(node)) return;
+      const prefixMatch = node.head.text.match(/(?:var\(\s*)?(--[\w-]*)$/);
+      if (!prefixMatch && !node.head.text.includes('var(')) return;
+      const prefix = prefixMatch?.[1] ?? '';
+      if (!overlaps(prefix)) return;
+      const span = node.templateSpans[0];
+      const suffix = node.templateSpans.length === 1 && span.literal.text.match(/^([\w-]*)\s*\)$/);
+      let callback = node.parent;
+      while (callback && !ts.isFunctionLike(callback)) callback = callback.parent;
+      let argument = callback;
+      while (argument?.parent && ts.isParenthesizedExpression(argument.parent)) argument = argument.parent;
+      const call = argument?.parent;
+      const binding = callback && ts.isArrowFunction(callback) && callback.parameters[0]?.name;
+      const first = binding && ts.isArrayBindingPattern(binding) && binding.elements[0];
+      const variable = first && ts.isBindingElement(first) && !first.initializer && !first.dotDotDotToken && ts.isIdentifier(first.name) ? first.name : null;
+      const receiver = call && ts.isCallExpression(call) && unwrap(call.arguments[0]) === callback && ts.isPropertyAccessExpression(call.expression)
+        && call.expression.name.text === 'map' ? unwrap(call.expression.expression) : null;
+      const rows = receiver && ts.isArrayLiteralExpression(receiver) ? receiver.elements.map(unwrap) : [];
+      if (ts.isTaggedTemplateExpression(node.parent) || !/^var\(\s*--[\w-]*$/.test(node.head.text) || !suffix || !variable || !ts.isIdentifier(span.expression) || span.expression.text !== variable.text
+        || !rows.length || rows.some(row => !ts.isArrayLiteralExpression(row) || !row.elements.length || !ts.isStringLiteral(row.elements[0]))) {
+        report('source-coverage', 'Dynamic custom properties require a direct literal tuple map and one bound interpolation.', node.getStart(parsed)); return;
+      }
+      const context = contexts.get(callback) ?? { callback, variable, rows, uses: [] };
+      context.uses.push({ prefix, suffix: suffix[1], node, expression: span.expression }); contexts.set(callback, context);
+    });
+    for (const { callback, variable, rows, uses } of contexts.values()) {
+      const replacements = [];
+      for (const row of rows) {
+        const item = row.elements[0]; const start = item.getStart(parsed) + 1; const values = new Set();
+        for (const use of uses) {
+          const name = use.prefix + item.text + use.suffix; reference(name, start, item.end - 1, 'finite');
+          const to = changes.has(name) ? changes.get(name) : name;
+          if (to === null) continue;
+          if (!to.startsWith(use.prefix) || !to.endsWith(use.suffix)) { report('source-coverage', 'The renamed property cannot use the existing template prefix and suffix.', start, name); continue; }
+          values.add(to.slice(use.prefix.length, use.suffix ? -use.suffix.length : undefined));
+        }
+        if (values.size > 1) report('source-coverage', 'A shared tuple key would change another custom-property reference.', start);
+        const value = [...values][0] ?? item.text; replacements.push(value);
+        if (value !== item.text) {
+          if (!/^[\w-]+$/.test(value) || source.slice(start, item.end - 1) !== item.text) report('source-coverage', 'Tuple edits require plain literal keys.', start);
+          else edit(start, item.end - 1, value);
+          walk(callback.body, node => {
+            if (ts.isIdentifier(node) && node.text === variable.text && !uses.some(use => use.expression === node)) report('source-coverage', 'The tuple key has another use that this rename cannot prove.', node.getStart(parsed));
+          });
+        }
+      }
+      if (replacements.some((value, index) => replacements.indexOf(value) !== index && rows[replacements.indexOf(value)].elements[0].text !== rows[index].elements[0].text)) report('rename-collision', 'Renaming would merge distinct tuple keys.');
+    }
+  } else report('source-coverage', 'This source language has no custom-property reference contract.');
+  for (const match of source.matchAll(names)) {
+    if (changes.has(match[0]) && !handled.has(match.index) && !inComment(match.index)) report('source-coverage', 'A custom-property occurrence is outside a proven CSS reference.', match.index, match[0]);
+  }
+  for (const { name, start } of references) {
+    if (destinations.includes(name) && !changes.has(name)) report('rename-collision', 'The rename target already has another source reference.', start, name);
+  }
+  const edits = [...proposed.values()].sort((left, right) => left.start - right.start);
+  if (edits.some((entry, index) => index && entry.start < edits[index - 1].end)) report('overlapping-edit', 'Source replacements overlap.');
+  if (diagnostics.length) return { source, edits: [], diagnostics, references };
+  for (const entry of edits.toReversed()) source = source.slice(0, entry.start) + entry.after + source.slice(entry.end);
+  return { source, edits, diagnostics, references };
+}