@pygmalionjs/pygmalion 0.8.1 → 0.9.0

package/node/source-file-proofs.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+/** Validate the same source bytes for both preview and apply. Legacy inputs omit the proof. */
+export async function validateInspectSourceProofs(root, input, { sourceRevision } = {}) {
+  if (input?.sourceProof === undefined) return;
+  const proof = input.sourceProof;
+  if (!proof || typeof proof !== 'object' || typeof proof.sourceRevision !== 'string' || !proof.sourceRevision.trim()
+    || !Array.isArray(proof.files) || proof.files.length < 1 || proof.files.length > 500) {
+    throw new Error('Source proof requires an exact revision and file hashes.');
+  }
+  if (sourceRevision !== undefined && proof.sourceRevision !== sourceRevision) {
+    throw new Error('Source proof does not match the active source revision.');
+  }
+  const base = await fsp.realpath(root);
+  const paths = new Set();
+  for (const item of proof.files) {
+    if (!item || typeof item.file !== 'string' || !item.file || path.isAbsolute(item.file)
+      || /[\\\0?#]/.test(item.file) || /^[a-z]:/i.test(item.file)
+      || item.file.split('/').some(part => !part || part === '.' || part === '..' || part === '.git')
+      || typeof item.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(item.sha256) || paths.has(item.file)) {
+      throw new Error('Source proof contains an invalid or duplicate file.');
+    }
+    paths.add(item.file);
+    const actualPath = await fsp.realpath(path.resolve(base, item.file));
+    const relative = path.relative(base, actualPath);
+    if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error('Source proof file escapes the application root.');
+    }
+    const stat = await fsp.stat(actualPath);
+    if (!stat.isFile()) throw new Error('Source proof must identify regular source files.');
+    const actual = createHash('sha256').update(await fsp.readFile(actualPath)).digest('hex');
+    if (actual !== item.sha256) throw new Error(`Source changed since the document was loaded: ${item.file}`);
+  }
+  const required = [
+    ...(input.styles ?? []).flatMap(style => [style.file, style.componentFile]),
+    ...(input.texts ?? []).map(text => text.componentFile),
+    ...(input.operations ?? []).map(operation => operation.identity?.componentFile),
+  ];
+  if (required.some(file => typeof file !== 'string' || !paths.has(file))) {
+    throw new Error('Source proof must cover every edited file and component source.');
+  }
+}

package/node/source-responsive-codec.d.mts

@@ -0,0 +1,17 @@
+import type { InspectApplyPayload, InspectMedia } from '../src/editor/inspect';
+import type { ResponsiveLayoutDocument, ResponsiveLayoutProperty, ResponsiveLayoutRange, ResponsiveLayoutSourceTarget } from '../src/workspace/source/responsiveContracts';
+export const RESPONSIVE_PROPERTIES: readonly ResponsiveLayoutProperty[];
+export const RESPONSIVE_COLLAPSED_VALUE: 'none';
+export function responsiveSizingProperty(property: string): boolean;
+export function responsiveFlexControl(property: string): boolean;
+export function sortResponsiveRanges<T extends ResponsiveLayoutRange>(ranges: readonly T[]): T[];
+export function responsiveRangePreviewWidth(ranges: readonly ResponsiveLayoutRange[], rangeId: string, preferred?: number): number;
+export function describeResponsiveValueContract(property: string, permitted?: readonly string[]): string;
+export function responsiveSourcePath(value: unknown): value is string;
+export function responsiveMediaQuery(media: InspectMedia): string;
+export function responsiveSourceHeader(range: ResponsiveLayoutRange): string;
+export function validateResponsiveRanges(ranges: unknown): void;
+export function validResponsiveValue(property: string, value: unknown, permitted?: readonly string[]): boolean;
+export function validateResponsiveTargets(targets: unknown): void;
+export function validateResponsiveState(state: unknown, ranges: readonly ResponsiveLayoutRange[], targets: readonly ResponsiveLayoutSourceTarget[]): asserts state is ResponsiveLayoutDocument;
+export function planResponsiveStyleChanges(before: ResponsiveLayoutDocument, after: ResponsiveLayoutDocument, ranges: readonly ResponsiveLayoutRange[], targets: readonly ResponsiveLayoutSourceTarget[]): InspectApplyPayload['styles'];

package/node/source-responsive-codec.mjs

@@ -0,0 +1,133 @@
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+export const RESPONSIVE_PROPERTIES = Object.freeze(['flex-direction', 'flex-wrap', 'align-items', 'justify-content', 'gap', 'padding', 'width', 'height', 'min-width', 'max-width', 'min-height', 'max-height', 'display']);
+/** A collapsed state is the only authored display change: a media range declares none and the base keeps the source display. */
+export const RESPONSIVE_COLLAPSED_VALUE = 'none';
+const SIZING_PROPERTY = /^(?:min-|max-)?(?:width|height)$/;
+export const responsiveSizingProperty = property => SIZING_PROPERTY.test(property);
+/** Flex controls need a flex source container; sizing and the collapsed state do not. */
+export const responsiveFlexControl = property => property !== 'display' && !SIZING_PROPERTY.test(property);
+const enums = {
+  'flex-direction': ['row', 'row-reverse', 'column', 'column-reverse'], 'flex-wrap': ['nowrap', 'wrap', 'wrap-reverse'],
+  'align-items': ['stretch', 'flex-start', 'flex-end', 'center', 'baseline'],
+  'justify-content': ['flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly'],
+  display: ['flex', 'inline-flex', 'block', 'inline-block', 'grid', 'inline-grid', RESPONSIVE_COLLAPSED_VALUE],
+};
+const lengthUnits = ['px', 'rem', 'em', '%', 'vw', 'vh'];
+const sizingKeywords = ['auto', 'min-content', 'max-content', 'fit-content'];
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, keys) => record(value) && Object.keys(value).every(key => keys.includes(key));
+const name = value => typeof value === 'string' && /^[A-Za-z_][\w-]*$/.test(value);
+export const responsiveSourcePath = value => typeof value === 'string' && value.length > 0 && !/[\\\0\r\n?#]/.test(value)
+  && !value.startsWith('/') && !/^[a-z]:/i.test(value) && !value.split('/').some(part => !part || part === '.' || part === '..' || part === '.git');
+export function responsiveMediaQuery(media) {
+  return [media.minWidth !== undefined ? `(min-width: ${media.minWidth}px)` : '', media.maxWidth !== undefined ? `(max-width: ${media.maxWidth}px)` : ''].filter(Boolean).join(' and ');
+}
+export function responsiveSourceHeader(range) {
+  return range.source?.kind === 'scss-include' ? `@include ${range.source.name}(${range.source.argument})` : `@media ${responsiveMediaQuery(range.media)}`;
+}
+/**
+ * Breakpoint order: the base first, then max-width ranges by descending width, then bounded and
+ * min-width ranges by ascending minimum width. Media ranges never overlap, so for a proven catalog
+ * this reads from the narrowest viewport to the widest while keeping each cascade family in its
+ * conventional source order. The order is the declared order; hosts declare ranges in it.
+ */
+export function sortResponsiveRanges(ranges) {
+  const key = range => range.media?.minWidth !== undefined ? [1, range.media.minWidth] : [0, -(range.media?.maxWidth ?? Infinity)];
+  return [ranges[0], ...ranges.slice(1).map((range, index) => ({ range, index })).sort((left, right) => {
+    const [a, b] = [key(left.range), key(right.range)];
+    return a[0] - b[0] || a[1] - b[1] || left.index - right.index;
+  }).map(item => item.range)];
+}
+const covered = (ranges, width) => ranges.some(range => range.media && width >= (range.media.minWidth ?? 0) && width <= (range.media.maxWidth ?? Infinity));
+/** A preview width that resolves to the selected range; the base needs a width no media range covers. */
+export function responsiveRangePreviewWidth(ranges, rangeId, preferred = 1024) {
+  const range = ranges.find(item => item.id === rangeId);
+  if (!range) throw new Error('The responsive preview range is not declared.');
+  if (range.media) return Math.min(Math.max(preferred, range.media.minWidth ?? 0, 1), range.media.maxWidth ?? 4000);
+  if (!covered(ranges, preferred)) return preferred;
+  const candidates = ranges.flatMap(item => item.media ? [(item.media.maxWidth ?? 4000) + 1, (item.media.minWidth ?? 0) - 1] : [])
+    .filter(width => width >= 1 && width <= 4000 && !covered(ranges, width));
+  return candidates.sort((left, right) => Math.abs(left - preferred) - Math.abs(right - preferred) || right - left)[0] ?? preferred;
+}
+export function validateResponsiveRanges(ranges) {
+  if (!Array.isArray(ranges) || !ranges.length || ranges.length > 20) throw new Error('Responsive ranges require one base and at most nineteen media ranges.');
+  const ids = new Set(); const intervals = [];
+  for (const [index, range] of ranges.entries()) {
+    if (!exact(range, ['id', 'label', 'media', 'source']) || !name(range.id) || typeof range.label !== 'string' || !range.label.trim() || ids.has(range.id)) throw new Error('Responsive ranges require unique stable IDs and labels.');
+    ids.add(range.id);
+    if (!index) { if (range.id !== 'base' || range.media !== undefined || range.source !== undefined) throw new Error('The first responsive range must be base without a media directive.'); continue; }
+    const media = range.media;
+    if (!exact(media, ['minWidth', 'maxWidth']) || !Object.keys(media).length || Object.values(media).some(value => !Number.isInteger(value) || value < 0 || value > 4000)
+      || (media.minWidth ?? 0) > (media.maxWidth ?? Infinity)) throw new Error('Responsive media requires an exact width interval between zero and four thousand pixels.');
+    const interval = [media.minWidth ?? 0, media.maxWidth ?? Infinity];
+    if (intervals.some(previous => interval[0] <= previous[1] && previous[0] <= interval[1])) throw new Error('Responsive media ranges must not overlap.');
+    intervals.push(interval);
+    if (range.source !== undefined && !(exact(range.source, ['kind']) && range.source.kind === 'media')
+      && !(exact(range.source, ['kind', 'name', 'argument', 'proofFile']) && range.source.kind === 'scss-include' && name(range.source.name)
+        && typeof range.source.argument === 'string' && /^\$[A-Za-z_][\w-]*$/.test(range.source.argument) && responsiveSourcePath(range.source.proofFile))) throw new Error('Responsive source directives require an explicit media rule or a proven local mixin and variable.');
+  }
+  if (sortResponsiveRanges(ranges).some((range, index) => range !== ranges[index])) throw new Error('Responsive media ranges must follow breakpoint order: max-width ranges by descending width, then bounded and min-width ranges by ascending minimum width.');
+}
+export function validResponsiveValue(property, value, permitted) {
+  if (typeof value !== 'string' || !value || value.trim() !== value || value.length > 160 || /[;{}\0\r\n]/.test(value) || value.includes('</') || /!important/i.test(value)) return false;
+  if (permitted !== undefined) return Array.isArray(permitted) && permitted.includes(value);
+  if (enums[property]) return enums[property].includes(value);
+  const length = token => token === '0' || /^(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em|%|vw|vh)$/.test(token);
+  if (property === 'gap' || property === 'padding') {
+    const parts = value.split(/\s+/); return parts.length <= (property === 'gap' ? 2 : 4) && parts.every(length);
+  }
+  return length(value) || sizingKeywords.includes(value) || (property.startsWith('max-') && value === 'none');
+}
+/** One sentence a panel can show next to a rejected value. */
+export function describeResponsiveValueContract(property, permitted) {
+  if (permitted !== undefined) return `${property} accepts only the host-permitted spellings: ${permitted.join(', ')}.`;
+  if (property === 'display') return 'display collapses a media range with none; the base range keeps the source display.';
+  if (enums[property]) return `${property} accepts ${enums[property].join(', ')}.`;
+  const lengths = `a length in ${lengthUnits.join(', ')} or 0`;
+  if (property === 'gap') return `gap accepts one or two lengths (${lengths}).`;
+  if (property === 'padding') return `padding accepts one to four lengths (${lengths}).`;
+  return `${property} accepts ${lengths}, ${sizingKeywords.join(', ')}${property.startsWith('max-') ? ' or none' : ''}.`;
+}
+export function validateResponsiveTargets(targets) {
+  if (!Array.isArray(targets) || !targets.length || targets.length > 100) throw new Error('Responsive mappings require explicit source targets.');
+  const ids = new Set(); const sources = new Set();
+  for (const target of targets) {
+    if (!exact(target, ['nodeId', 'file', 'className', 'componentFile', 'affectedFrames', 'properties', 'permittedValues']) || typeof target.nodeId !== 'string' || !target.nodeId || ids.has(target.nodeId)
+      || !responsiveSourcePath(target.file) || !target.file.endsWith('.module.scss') || !responsiveSourcePath(target.componentFile) || !/\.[cm]?[jt]sx?$/.test(target.componentFile) || !name(target.className)
+      || !Array.isArray(target.properties) || !target.properties.length || new Set(target.properties).size !== target.properties.length || target.properties.some(property => !RESPONSIVE_PROPERTIES.includes(property))
+      || !Array.isArray(target.affectedFrames) || !target.affectedFrames.length || target.affectedFrames.some(frame => !exact(frame, ['id', 'name']) || typeof frame.id !== 'string' || !frame.id || typeof frame.name !== 'string' || !frame.name)) throw new Error('Responsive targets require unique node identities, admitted properties, source paths and affected frames.');
+    const address = JSON.stringify([target.file, target.className]);
+    if (sources.has(address)) throw new Error('A responsive source class must have one canonical owner.');
+    sources.add(address); ids.add(target.nodeId);
+    if (target.permittedValues !== undefined && (!record(target.permittedValues) || Object.entries(target.permittedValues).some(([property, values]) => !target.properties.includes(property)
+      || !Array.isArray(values) || !values.length || values.some(value => !validResponsiveValue(property, value, values))))) throw new Error('Responsive permitted values must be nonempty safe source spellings for admitted properties.');
+  }
+}
+export function validateResponsiveState(state, ranges, targets) {
+  validateResponsiveRanges(ranges); validateResponsiveTargets(targets);
+  if (!exact(state, ['version', 'ranges', 'styles']) || state.version !== 1 || !record(state.styles) || fingerprint(state.ranges) !== fingerprint(ranges)) throw new Error('Responsive authored state must preserve the host range catalog.');
+  if (Object.keys(state.styles).length !== targets.length || targets.some(target => !Object.hasOwn(state.styles, target.nodeId))) throw new Error('Responsive authored state must preserve every mapped source owner.');
+  for (const target of targets) {
+    const styles = state.styles[target.nodeId];
+    if (!record(styles) || Object.keys(styles).some(id => !ranges.some(range => range.id === id)) || !record(styles.base)
+      || target.properties.some(property => !Object.hasOwn(styles.base, property))) throw new Error('Every responsive property requires an authored base declaration.');
+    for (const [id, declarations] of Object.entries(styles)) {
+      if (!record(declarations) || Object.entries(declarations).some(([property, value]) => !target.properties.includes(property)
+        || !validResponsiveValue(property, value, target.permittedValues?.[property]))) throw new Error('Responsive values must match the host properties and value contract.');
+      if (Object.hasOwn(declarations, 'display') && (id === 'base') === (declarations.display === RESPONSIVE_COLLAPSED_VALUE)) throw new Error('A collapsed state declares display none only inside a media range; the base range keeps the source display.');
+    }
+  }
+}
+export function planResponsiveStyleChanges(before, after, ranges, targets) {
+  validateResponsiveState(before, ranges, targets); validateResponsiveState(after, ranges, targets);
+  const changes = [];
+  for (const target of targets) for (const range of ranges) {
+    const previous = before.styles[target.nodeId][range.id] ?? {}; const next = after.styles[target.nodeId][range.id] ?? {};
+    const declarations = {};
+    for (const property of target.properties) if (previous[property] !== next[property]) declarations[property] = next[property] ?? '';
+    if (Object.keys(declarations).length) changes.push({ file: target.file, className: target.className, componentFile: target.componentFile,
+      declarations, affectedFrames: [...target.affectedFrames], ...(range.media ? { media: { ...range.media } } : {}) });
+  }
+  if (changes.length > 100) throw new Error('Responsive source changes exceed the inspect operation limit.');
+  return changes;
+}

package/node/source-responsive.mjs

@@ -0,0 +1,189 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { writeInspectChanges } from './inspect-writeback.mjs';
+import { validateInspectSourceProofs } from './source-file-proofs.mjs';
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+import { planResponsiveStyleChanges, responsiveFlexControl, responsiveMediaQuery, responsiveSourceHeader, responsiveSourcePath, validateResponsiveRanges, validateResponsiveState, validateResponsiveTargets } from './source-responsive-codec.mjs';
+
+const hash = source => createHash('sha256').update(source).digest('hex');
+const inspectMarker = (target, range) => `/* Pygmalion responsive: .${target.className} @media ${responsiveMediaQuery(range.media)} */`;
+const marker = (target, range) => `/* Pygmalion responsive: .${target.className} ${responsiveSourceHeader(range)} */`;
+const abort = signal => { if (signal?.aborted) throw signal.reason ?? new Error('Responsive source planning was aborted.'); };
+
+// A bounded declaration reader, not a Sass evaluator. Unowned cascade rules are rejected.
+function masked(source) {
+  return source.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, value => value.replace(/[^\n]/g, ' '));
+}
+function blocks(source) {
+  const text = masked(source); const stack = []; const result = []; let start = 0;
+  for (let index = 0; index < text.length; index++) {
+    if (text[index] === '{') {
+      const block = { header: text.slice(start, index).trim(), start, open: index, close: -1, parent: stack.at(-1) ?? null, declarations: [] };
+      stack.push(block); result.push(block); start = index + 1;
+    } else if (text[index] === ';') {
+      stack.at(-1)?.declarations.push(source.slice(start, index)); start = index + 1;
+    } else if (text[index] === '}') {
+      const block = stack.pop(); if (!block) throw new Error('Responsive source contains unmatched braces.');
+      if (text.slice(start, index).trim()) block.declarations.push(source.slice(start, index));
+      block.close = index; start = index + 1;
+    }
+  }
+  if (stack.length) throw new Error('Responsive source contains unmatched braces.');
+  return result;
+}
+function declarations(block, properties) {
+  const result = {};
+  for (const raw of block.declarations) {
+    const cleaned = raw.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '').trim();
+    const match = /^([\w-]+)\s*:\s*([\s\S]+)$/.exec(cleaned);
+    if (!match || !properties.includes(match[1])) continue;
+    if (Object.hasOwn(result, match[1])) throw new Error('Responsive source contains duplicate declarations.');
+    result[match[1]] = match[2].trim();
+  }
+  return result;
+}
+function normalizedState(state) {
+  const next = structuredClone(state);
+  for (const styles of Object.values(next.styles)) for (const [id, values] of Object.entries(styles)) if (id !== 'base' && !Object.keys(values).length) delete styles[id];
+  return next;
+}
+// The existing writer removes declarations one at a time. A managed range block that no longer
+// carries any declaration is removed with its marker so cleared overrides leave no empty rule behind.
+function pruneEmptyManagedBlocks(source, targets, ranges) {
+  let content = source;
+  const whitespaceOnly = block => block.declarations.every(raw => !raw.trim());
+  for (const target of targets) for (const range of ranges.slice(1)) {
+    const text = marker(target, range); const index = content.indexOf(text);
+    if (index < 0) continue;
+    const parsed = blocks(content);
+    const directive = parsed.find(block => !block.parent && block.open > index && content.slice(index + text.length, block.open).trim() === responsiveSourceHeader(range));
+    if (!directive) continue;
+    const children = parsed.filter(block => block.parent === directive);
+    if (!whitespaceOnly(directive) || children.length !== 1 || children[0].header !== `.${target.className}` || !whitespaceOnly(children[0]) || parsed.some(block => block.parent === children[0])) continue;
+    let start = index; let end = directive.close + 1;
+    if (content[end] === '\n') end += 1;
+    while (start > 0 && content[start - 1] === '\n' && content[start - 2] === '\n') start -= 1;
+    content = content.slice(0, start) + content.slice(end);
+  }
+  return content;
+}
+
+/** Read authored declarations only. The host owns mixin semantics and supplies exact file proofs. */
+export function readResponsiveLayoutSource({ files, ranges, targets }) {
+  validateResponsiveRanges(ranges); validateResponsiveTargets(targets);
+  const sources = new Map();
+  for (const file of files) {
+    if (!responsiveSourcePath(file.file) || sources.has(file.file) || typeof file.source !== 'string' || !/^[a-f\d]{64}$/.test(file.sha256) || hash(file.source) !== file.sha256) throw new Error('Responsive source inputs require unique paths and exact byte hashes.');
+    sources.set(file.file, file.source);
+  }
+  for (const range of ranges) if (range.source?.kind === 'scss-include') {
+    const source = sources.get(range.source.proofFile);
+    if (source === undefined) throw new Error('The responsive mixin source proof is missing.');
+    const text = masked(source);
+    const variable = range.source.argument.slice(1);
+    if (!new RegExp(`@mixin\\s+${range.source.name}\\s*\\(`).test(text) || !new RegExp(`\\$${variable}\\s*:`).test(text)) throw new Error('The responsive mixin and breakpoint variable must exist in the proven source.');
+  }
+  const state = { version: 1, ranges: structuredClone(ranges), styles: {} };
+  for (const target of targets) {
+    const source = sources.get(target.file);
+    if (source === undefined || !sources.has(target.componentFile)) throw new Error('Responsive source requires the stylesheet and importing component.');
+    const parsed = blocks(source); const styles = {}; const owned = new Set();
+    const base = parsed.filter(block => !block.parent && block.header === `.${target.className}`);
+    if (base.length !== 1) throw new Error('Responsive source requires one unambiguous top-level class.');
+    if (base[0].declarations.some(raw => /^\s*@(?:include|extend|apply)\b/.test(masked(raw)))) throw new Error('Responsive source cannot infer declarations introduced by an unexpanded directive.');
+    styles.base = declarations(base[0], target.properties); owned.add(base[0]);
+    // Flex controls need actual source flex semantics; sizing-only and collapse-only owners may omit them.
+    if (target.properties.some(responsiveFlexControl)) {
+      const display = declarations(base[0], ['display']).display;
+      if (display !== 'flex' && display !== 'inline-flex') throw new Error('Responsive layout controls require an existing flex source container.');
+    }
+    for (const range of ranges.slice(1)) {
+      const text = marker(target, range); const index = source.indexOf(text);
+      if (index < 0) continue;
+      if (source.indexOf(text, index + text.length) >= 0) throw new Error('Responsive source markers must be unique.');
+      const header = responsiveSourceHeader(range);
+      const directive = parsed.find(block => !block.parent && block.open > index && source.slice(index + text.length, block.open).trim() === header);
+      if (!directive) throw new Error('The responsive marker does not match its proven source directive.');
+      const matches = parsed.filter(block => block.parent === directive && block.header === `.${target.className}`);
+      if (matches.length !== 1) throw new Error('A managed responsive range requires one exact class.');
+      const values = declarations(matches[0], target.properties); if (Object.keys(values).length) styles[range.id] = values;
+      owned.add(matches[0]);
+    }
+    const classReference = new RegExp(`\\.${target.className}(?![\\w-])`);
+    for (const block of parsed) {
+      let ancestor = block.parent; let nested = false;
+      while (ancestor) { if (owned.has(ancestor)) nested = true; ancestor = ancestor.parent; }
+      if (!owned.has(block) && (classReference.test(block.header) || nested) && Object.keys(declarations(block, target.properties)).length) throw new Error('An unowned selector or media rule also controls this responsive source.');
+    }
+    state.styles[target.nodeId] = styles;
+  }
+  validateResponsiveState(state, ranges, targets);
+  return state;
+}
+
+/** Return a complete SCSS file plan using existing inspect writers in a private temporary root. */
+export async function compileResponsiveSourcePlan({ appRoot, sourceRevision, mapping: inputMapping, before: inputBefore, after: inputAfter, additionalStyles: inputStyles = [], signal }) {
+  abort(signal);
+  const { mapping, before, after, additionalStyles } = JSON.parse(fingerprint({ mapping: inputMapping, before: inputBefore, after: inputAfter, additionalStyles: inputStyles }));
+  if (mapping?.version !== 1 || mapping.target?.sourceRevision !== sourceRevision) throw new Error('Responsive source plan requires the exact mapped source revision.');
+  const styles = planResponsiveStyleChanges(before, after, mapping.ranges, mapping.targets);
+  if (!Array.isArray(additionalStyles)) throw new Error('Additional visual styles must be an array.');
+  const addresses = new Set();
+  for (const style of [...styles, ...additionalStyles]) for (const property of Object.keys(style.declarations)) {
+    const address = fingerprint([style.file, style.className, style.media ?? null, property]);
+    if (addresses.has(address)) throw new Error('Responsive and visual operations overlap on one source declaration.');
+    addresses.add(address);
+  }
+  const payload = { styles: [...styles, ...additionalStyles], texts: [], operations: [], sourceProof: { sourceRevision,
+    files: mapping.files.filter(proof => proof.sha256 !== null) } };
+  await validateInspectSourceProofs(appRoot, payload, { sourceRevision });
+  const files = [];
+  for (const proof of mapping.files) {
+    abort(signal);
+    if (!responsiveSourcePath(proof.file)) throw new Error('Invalid responsive proof path.');
+    if (proof.sha256 === null) {
+      try { await fs.lstat(path.join(appRoot, proof.file)); throw new Error('A responsive absence proof is stale.'); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    } else files.push({ ...proof, source: await fs.readFile(path.join(appRoot, proof.file), 'utf8') });
+  }
+  const baseline = readResponsiveLayoutSource({ files, ranges: mapping.ranges, targets: mapping.targets });
+  if (fingerprint(normalizedState(before)) !== fingerprint(baseline)) throw new Error('Responsive baseline does not match the actual source declarations.');
+  if (!payload.styles.length) return { version: 1, sourceRevision, proofs: structuredClone(mapping.files), changes: [] };
+  const temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'pygmalion-responsive-'));
+  try {
+    const temporaryProofs = [];
+    for (const file of files) {
+      abort(signal);
+      let content = file.source;
+      for (const target of mapping.targets.filter(target => target.file === file.file)) for (const range of mapping.ranges.slice(1)) {
+        if (range.source?.kind === 'scss-include') content = content.replace(marker(target, range), inspectMarker(target, range));
+      }
+      const destination = path.join(temporary, file.file); await fs.mkdir(path.dirname(destination), { recursive: true }); await fs.writeFile(destination, content);
+      temporaryProofs.push({ file: file.file, sha256: hash(content) });
+    }
+    abort(signal);
+    await writeInspectChanges(temporary, { ...payload, sourceProof: { sourceRevision, files: temporaryProofs } }, { sourceRevision });
+    const nextFiles = [];
+    for (const file of files) {
+      let content = await fs.readFile(path.join(temporary, file.file), 'utf8');
+      // The existing writer owns declarations; this bridge only translates proven directive spellings.
+      for (const target of mapping.targets.filter(target => target.file === file.file)) for (const range of mapping.ranges.slice(1)) {
+        if (range.source?.kind !== 'scss-include') continue;
+        const mediaHeader = `${inspectMarker(target, range)}\n@media ${responsiveMediaQuery(range.media)} {`;
+        if (content.includes(mediaHeader)) content = content.replace(mediaHeader, `${marker(target, range)}\n${responsiveSourceHeader(range)} {`);
+        else content = content.replace(inspectMarker(target, range), marker(target, range));
+      }
+      content = pruneEmptyManagedBlocks(content, mapping.targets.filter(target => target.file === file.file), mapping.ranges);
+      nextFiles.push({ file: file.file, source: content, sha256: hash(content) });
+    }
+    abort(signal);
+    const reimported = readResponsiveLayoutSource({ files: nextFiles, ranges: mapping.ranges, targets: mapping.targets });
+    if (fingerprint(reimported) !== fingerprint(normalizedState(after))) throw new Error('Responsive source output does not round-trip to the authored draft.');
+    return { version: 1, sourceRevision, proofs: structuredClone(mapping.files), changes: nextFiles.flatMap(file => {
+      const previous = files.find(input => input.file === file.file);
+      return file.source === previous.source ? [] : [{ file: file.file, beforeSha256: previous.sha256, content: file.source }];
+    }).sort((a, b) => a.file.localeCompare(b.file)) };
+  } finally { await fs.rm(temporary, { recursive: true, force: true }); }
+}

package/node/source-structure-reconcile.mjs

@@ -0,0 +1,186 @@
+import { createHash } from 'node:crypto';
+import { compileJsxStructurePlan, createJsxStructureIdentity, reimportJsxStructureSource } from './source-structure.mjs';
+import { workspaceSourceFingerprint } from './workspace-source-identity.mjs';
+
+const hash = source => createHash('sha256').update(source, 'utf8').digest('hex');
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const revision = value => typeof value === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+function freeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+}
+function failure(diagnostic, action = 'resolve-overlap') {
+  return freeze({ status: 'conflict', diagnostics: [{ ...diagnostic, action }] });
+}
+const layoutOf = node => node?.layout ?? null;
+function shape(node) { return node ? { kind: node.kind, parentId: node.parentId, children: [...node.children], layout: layoutOf(node) } : null; }
+function tree(projection) {
+  return new Map(projection.nodes.map(node => [node.nodeId, node]));
+}
+function equalTrees(left, right) {
+  return left.size === right.size && [...left].every(([id, node]) => same(shape(node), shape(right.get(id))));
+}
+function sourceResult(file, baseline, external, source, identity, projection, payload, stylesheetSource) {
+  const result = { status: payload ? 'ready' : 'unchanged', file,
+    baselineSourceRevision: baseline.sourceRevision, baselineSourceSha256: baseline.identity.sourceSha256,
+    sourceRevision: external.sourceRevision, externalSourceSha256: external.sha256,
+    source, identity, anchors: projection.anchors, nodes: projection.nodes, diagnostics: [] };
+  if (payload) result.payload = payload;
+  if (stylesheetSource !== undefined) result.stylesheetSource = stylesheetSource;
+  return freeze(result);
+}
+function updatedIdentity(file, source, rootId, anchors, opaqueNodeIds, wrapper) {
+  const present = new Set(anchors.map(anchor => anchor.nodeId));
+  return createJsxStructureIdentity({ file, source, rootId, anchors, opaqueNodeIds: opaqueNodeIds.filter(id => present.has(id)), wrapper });
+}
+/** Wrapper groups need the stylesheet at both revisions; its bytes are proved like the JSX. */
+function wrapperInput(wrapper, file) {
+  if (wrapper === undefined) return { ok: true };
+  if (!record(wrapper) || Object.keys(wrapper).some(key => !['contract', 'baselineSource', 'externalSource', 'externalSha256'].includes(key))
+    || typeof wrapper.baselineSource !== 'string' || typeof wrapper.externalSource !== 'string' || !record(wrapper.contract) || typeof wrapper.contract.stylesheet !== 'string') {
+    return { ok: false, failure: failure({ code: 'structure-reconcile-input-invalid', message: 'Wrapper reconciliation requires the host contract and the complete baseline and latest stylesheet bytes.', file }, 'refresh-source') };
+  }
+  if (typeof wrapper.externalSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(wrapper.externalSha256) || hash(wrapper.externalSource) !== wrapper.externalSha256) {
+    return { ok: false, failure: failure({ code: 'structure-source-stale', message: 'The latest stylesheet bytes no longer match their supplied SHA-256 proof. Read and review the latest source again.', file: wrapper.contract.stylesheet }, 'refresh-source') };
+  }
+  return { ok: true };
+}
+const changedFile = (compiled, file, fallback) => compiled.status === 'ready' ? compiled.payload.changes.find(change => change.file === file)?.content ?? fallback : fallback;
+
+/**
+ * Three-way structure reconciliation with explicit host-supplied current-source identity.
+ * IDs are never inferred from snippets, names, runtime values, or positional similarity.
+ * Only a new plan against the external bytes is returned; baseline proofs are never relabeled.
+ */
+export function reconcileJsxStructurePlan(input) {
+  let captured;
+  try { captured = JSON.parse(workspaceSourceFingerprint(input)); }
+  catch { return failure({ code: 'structure-reconcile-input-invalid', message: 'Reconciliation requires complete serializable source, identity, and draft operation captures.' }, 'refresh-source'); }
+  const { file, baseline, external, operations, allowedFiles, excludedSourcePrefixes = [], wrapper } = captured ?? {};
+  if (!record(baseline) || !record(external) || !revision(baseline.sourceRevision) || !revision(external.sourceRevision)
+    || typeof baseline.source !== 'string' || typeof external.source !== 'string' || !Array.isArray(operations)) {
+    return failure({ code: 'structure-reconcile-input-invalid', message: 'Provide both exact source revisions, complete source bytes, and the audited draft structure operations.', ...(typeof file === 'string' ? { file } : {}) }, 'refresh-source');
+  }
+  if (!baseline.identity || !external.identity) {
+    return failure({ code: 'structure-reconcile-identity-required', message: 'Provide complete baseline and external identity tables. Explicitly map retained IDs, allocate new IDs, and omit only deleted nodes.', file }, 'map-identities');
+  }
+  if (typeof external.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(external.sha256) || hash(external.source) !== external.sha256) {
+    return failure({ code: 'structure-source-stale', message: 'The latest source bytes no longer match their supplied SHA-256 proof. Read and review the latest source again.', file }, 'refresh-source');
+  }
+  const checked = wrapperInput(wrapper, file);
+  if (!checked.ok) return checked.failure;
+  const evidence = source => wrapper ? { contract: wrapper.contract, source } : undefined;
+  const stylesheetFiles = source => wrapper ? [{ file: wrapper.contract.stylesheet, source, sha256: hash(source) }] : [];
+  const contract = wrapper ? { wrapper: wrapper.contract } : {};
+  let before; let current;
+  try {
+    before = reimportJsxStructureSource({ file, source: baseline.source, identity: baseline.identity, wrapper: evidence(wrapper?.baselineSource) });
+    current = reimportJsxStructureSource({ file, source: external.source, identity: external.identity, wrapper: evidence(wrapper?.externalSource) });
+  } catch (error) {
+    return failure(error?.diagnostic ?? { code: 'structure-reconcile-identity-invalid', message: error instanceof Error ? error.message : String(error), file },
+      error?.diagnostic?.code?.includes('stale') ? 'refresh-source' : 'map-identities');
+  }
+  const originalNodes = tree(before); const externalNodes = tree(current);
+  if (baseline.identity.rootId !== external.identity.rootId) {
+    return failure({ code: 'structure-reconcile-root-conflict', message: 'The external identity must explicitly retain the source island root ID. Select and map the corresponding root before reconciling.', file, nodeId: baseline.identity.rootId }, 'map-identities');
+  }
+  const originalOpaque = new Set(baseline.identity.opaqueNodeIds); const externalOpaque = new Set(external.identity.opaqueNodeIds);
+  const identityConflicts = [];
+  for (const [id, node] of originalNodes) {
+    const latest = externalNodes.get(id);
+    if (latest && (node.kind !== latest.kind || originalOpaque.has(id) !== externalOpaque.has(id))) {
+      identityConflicts.push({ code: 'structure-reconcile-boundary-conflict', message: 'A retained ID changed node kind or opaque boundary. Confirm its source ownership and explicit identity mapping.', file, nodeId: id,
+        action: 'map-identities', baseline: shape(node), external: shape(latest) });
+    }
+  }
+  if (identityConflicts.length) return freeze({ status: 'conflict', diagnostics: identityConflicts });
+
+  let draftCompiled;
+  try {
+    draftCompiled = compileJsxStructurePlan({ sourceRevision: baseline.sourceRevision,
+      files: [{ file, source: baseline.source, sha256: baseline.identity.sourceSha256 }, ...stylesheetFiles(wrapper?.baselineSource)],
+      anchors: before.anchors, operations, allowedFiles, excludedSourcePrefixes, ...contract });
+  } catch (error) {
+    return failure({ code: 'structure-reconcile-draft-invalid', message: error instanceof Error ? error.message : String(error), file });
+  }
+  if (draftCompiled.status === 'blocked') return freeze({ status: 'conflict', diagnostics: draftCompiled.diagnostics.map(diagnostic => ({ ...diagnostic, action: 'resolve-overlap' })) });
+  const draftSource = changedFile(draftCompiled, file, baseline.source);
+  const draftStylesheet = wrapper ? changedFile(draftCompiled, wrapper.contract.stylesheet, wrapper.baselineSource) : undefined;
+  let draftIdentity; let draft;
+  try {
+    draftIdentity = updatedIdentity(file, draftSource, baseline.identity.rootId, draftCompiled.anchors, baseline.identity.opaqueNodeIds, evidence(draftStylesheet));
+    draft = reimportJsxStructureSource({ file, source: draftSource, identity: draftIdentity, wrapper: evidence(draftStylesheet) });
+  } catch (error) {
+    return failure(error?.diagnostic ?? { code: 'structure-reconcile-draft-invalid', message: error instanceof Error ? error.message : String(error), file });
+  }
+  const draftNodes = tree(draft);
+  // An unchanged draft accepts the explicitly mapped latest tree. If the entire draft tree is
+  // already present externally, keep its latest bytes without replaying groups or moves twice.
+  if (draftCompiled.status === 'unchanged' || equalTrees(draftNodes, externalNodes)) {
+    return sourceResult(file, baseline, external, external.source, external.identity, current, undefined, wrapper?.externalSource);
+  }
+  const conflicts = [];
+  const conflict = (code, message, id) => conflicts.push({ code, message, file, nodeId: id, action: 'resolve-overlap',
+    baseline: shape(originalNodes.get(id)), external: shape(externalNodes.get(id)), draft: shape(draftNodes.get(id)) });
+  for (const [id, original] of originalNodes) {
+    const latest = externalNodes.get(id); const desired = draftNodes.get(id);
+    if (!desired) {
+      if (latest && (!same(original.children, latest.children) || original.parentId !== latest.parentId)) {
+        conflict('structure-reconcile-delete-conflict', 'The draft removes a node whose external parent or children changed. Resolve that removal against the latest hierarchy.', id);
+      }
+    } else if (!latest) {
+      if (!same(original.children, desired.children) || original.parentId !== desired.parentId) {
+        conflict('structure-reconcile-missing-node', 'An externally deleted node is still changed by the draft. Restore its explicit identity or revise the draft move.', id);
+      }
+    } else {
+      if (!same(original.children, desired.children) && !same(original.children, latest.children)) {
+        conflict('structure-reconcile-children-conflict', 'Both sources changed this direct-child list. Choose an explicit final order before reconciling.', id);
+      }
+      if (original.parentId !== desired.parentId && original.parentId !== latest.parentId) {
+        conflict('structure-reconcile-parent-conflict', 'Both sources moved this node. Choose its final parent before reconciling.', id);
+      }
+      if (!same(layoutOf(original), layoutOf(desired)) && !same(layoutOf(original), layoutOf(latest))) {
+        conflict('structure-reconcile-layout-conflict', 'Both sources changed this wrapper layout. Choose its final layout before reconciling.', id);
+      }
+    }
+  }
+  for (const id of draftNodes.keys()) {
+    if (!originalNodes.has(id) && externalNodes.has(id)) conflict('structure-reconcile-new-id-conflict', 'The draft and external source both introduced this ID. Map their identities or allocate a distinct draft ID.', id);
+  }
+  if (conflicts.length) return freeze({ status: 'conflict', diagnostics: conflicts });
+
+  let merged;
+  try {
+    merged = compileJsxStructurePlan({ sourceRevision: external.sourceRevision,
+      files: [{ file, source: external.source, sha256: external.sha256 }, ...stylesheetFiles(wrapper?.externalSource)], anchors: current.anchors,
+      operations, allowedFiles, excludedSourcePrefixes, ...contract });
+  } catch (error) {
+    return failure({ code: 'structure-reconcile-merge-invalid', message: error instanceof Error ? error.message : String(error), file });
+  }
+  if (merged.status === 'blocked') return freeze({ status: 'conflict', diagnostics: merged.diagnostics.map(diagnostic => ({ ...diagnostic, action: 'resolve-overlap' })) });
+  const source = changedFile(merged, file, external.source);
+  const stylesheetSource = wrapper ? changedFile(merged, wrapper.contract.stylesheet, wrapper.externalSource) : undefined;
+  let mergedIdentity; let projection;
+  try {
+    mergedIdentity = updatedIdentity(file, source, external.identity.rootId, merged.anchors, external.identity.opaqueNodeIds, evidence(stylesheetSource));
+    projection = reimportJsxStructureSource({ file, source, identity: mergedIdentity, wrapper: evidence(stylesheetSource) });
+  } catch (error) {
+    return failure(error?.diagnostic ?? { code: 'structure-reconcile-merge-invalid', message: error instanceof Error ? error.message : String(error), file });
+  }
+  const mergedNodes = tree(projection);
+  const expected = new Map();
+  for (const [id, node] of externalNodes) {
+    const original = originalNodes.get(id); const desired = draftNodes.get(id);
+    if (original && !desired) continue;
+    expected.set(id, { ...node,
+      parentId: original && desired.parentId !== original.parentId ? desired.parentId : node.parentId,
+      children: original && !same(desired.children, original.children) ? desired.children : node.children,
+      layout: original && !same(layoutOf(desired), layoutOf(original)) ? layoutOf(desired) : layoutOf(node) });
+  }
+  for (const [id, node] of draftNodes) if (!originalNodes.has(id)) expected.set(id, node);
+  if (!equalTrees(expected, mergedNodes)) {
+    return failure({ code: 'structure-reconcile-result-conflict', message: 'The replayed operations do not match the combined explicit hierarchies. Resolve the final structure before applying.', file });
+  }
+  return sourceResult(file, baseline, external, source, mergedIdentity, projection, merged.status === 'ready' ? merged.payload : undefined, stylesheetSource);
+}

package/node/source-structure-wrapper-codec.d.mts

@@ -0,0 +1,20 @@
+import type { WorkspaceStructureGroupLayout, WorkspaceStructureWrapperDeclaration } from '../src/workspace/source/contracts';
+
+export interface WrapperBlock { start: number; end: number; declarations: Record<string, string> }
+export const VOID_ELEMENTS: ReadonlySet<string>;
+export const WRAPPER_ALIGNMENTS: readonly ['start', 'center', 'end', 'stretch'];
+export function wrapperContractProblem(contract: unknown): string | null;
+export function wrapperTagName(contract: WorkspaceStructureWrapperDeclaration): string;
+export function wrapperOpening(contract: WorkspaceStructureWrapperDeclaration, className: string): string;
+export function wrapperClosing(contract: WorkspaceStructureWrapperDeclaration): string;
+export function wrapperMarker(groupId: string): string;
+export function wrapperClassName(groupId: string): string | null;
+export function wrapperLayoutProblem(layout: unknown, contract: WorkspaceStructureWrapperDeclaration): string | null;
+export function wrapperLayout(layout: WorkspaceStructureGroupLayout & { sizing?: string; crossSizing?: string }): WorkspaceStructureGroupLayout;
+export function wrapperDeclarations(layout: WorkspaceStructureGroupLayout, contract: WorkspaceStructureWrapperDeclaration): Record<string, string>;
+export function wrapperLayoutFromDeclarations(declarations: Record<string, string>, contract: WorkspaceStructureWrapperDeclaration): WorkspaceStructureGroupLayout;
+export function wrapperBlock(groupId: string, className: string, layout: WorkspaceStructureGroupLayout, contract: WorkspaceStructureWrapperDeclaration, eol?: string): string;
+export function findWrapperBlock(source: string, groupId: string, className: string): WrapperBlock | null;
+export function wrapperClassReferenced(source: string, className: string, ignore?: readonly { start: number; end: number }[]): boolean;
+export function readWrapperLayout(source: string, groupId: string, className: string, contract: WorkspaceStructureWrapperDeclaration): WorkspaceStructureGroupLayout | null;
+export function applyWrapperEdits(source: string, edits: ReadonlyMap<string, WorkspaceStructureGroupLayout | null>, contract: WorkspaceStructureWrapperDeclaration): string;