@pygmalionjs/pygmalion 0.8.1 → 0.10.0

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-service-inputs.mjs

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const relative = file => typeof file === 'string' && file.length > 0 && !path.isAbsolute(file)
+  && !/^[a-z]:/i.test(file) && !/[\\\x00-\x1f\x7f?#]/.test(file)
+  && !file.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
+
+/** Absence is only proven through ordinary directories, including every existing ancestor. */
+export async function assertSourceInputParent(root, file) {
+  if (!relative(file)) throw new Error('A source input requires a relative file path.');
+  let directory = root;
+  for (const part of file.split('/').slice(0, -1)) {
+    directory = path.join(directory, part);
+    let stat;
+    try { stat = await lstat(directory); }
+    catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    if (!stat.isDirectory() || await realpath(directory) !== directory) throw new Error('Source inputs cannot traverse linked directories.');
+  }
+}
+
+export async function readSourceInputs(appRoot, files, { optionalFiles = [], signal, maxBytes = 32 * 1024 * 1024 } = {}) {
+  if (!Array.isArray(files) || !files.length || files.length > 3000 || new Set(files).size !== files.length
+    || files.some(file => !relative(file)) || !Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error('Source inputs require unique relative files and a positive byte limit.');
+  const selected = [...files]; const optional = new Set(optionalFiles); const inputs = {}; let bytes = 0;
+  const root = await realpath(appRoot);
+  for (const file of selected) {
+    signal?.throwIfAborted();
+    await assertSourceInputParent(root, file);
+    const absolute = path.join(root, file);
+    let stat;
+    try { stat = await lstat(absolute); }
+    catch (error) { if (!optional.has(file) || error.code !== 'ENOENT') throw error; Object.defineProperty(inputs, file, { value: null, enumerable: true }); continue; }
+    if (!stat.isFile() || await realpath(absolute) !== absolute) throw new Error(`Source input must be a regular unlinked file: ${file}`);
+    if (bytes + stat.size > maxBytes) throw new Error('Source inputs exceed the byte limit.');
+    const buffer = await readFile(absolute); bytes += buffer.length;
+    if (bytes > maxBytes || !Buffer.from(buffer.toString('utf8')).equals(buffer)) throw new Error('Source inputs must be UTF-8 within the byte limit.');
+    Object.defineProperty(inputs, file, { value: buffer.toString('utf8'), enumerable: true, configurable: true, writable: true });
+  }
+  signal?.throwIfAborted();
+  return inputs;
+}
+
+/** Seed isolated UTF-8 source files and always remove the directory after the callback settles. */
+export async function withSourceFiles({ files, signal }, operation) {
+  const entries = files instanceof Map ? [...files] : null;
+  if (!entries || entries.length > 3000 || typeof operation !== 'function'
+    || entries.some(([file, source]) => !relative(file) || typeof source !== 'string' || Buffer.from(source).toString('utf8') !== source)) {
+    throw new Error('Isolated source files require a map of relative paths to UTF-8 strings.');
+  }
+  signal?.throwIfAborted();
+  const root = await mkdtemp(path.join(os.tmpdir(), 'pygmalion-source-'));
+  try {
+    for (const [file, source] of entries) {
+      signal?.throwIfAborted();
+      const destination = path.join(root, file);
+      await mkdir(path.dirname(destination), { recursive: true });
+      await writeFile(destination, source, { flag: 'wx' });
+    }
+    signal?.throwIfAborted();
+    const result = await operation(root);
+    signal?.throwIfAborted();
+    return result;
+  } finally { await rm(root, { recursive: true, force: true }); }
+}
+
+export async function readProvenSourceFiles(appRoot, proofs, options = {}) {
+  if (!Array.isArray(proofs) || !proofs.length || proofs.length > 500 || proofs.some(proof => !proof ||
+    !(proof.sha256 === null && options.optionalFiles?.includes(proof.file) || typeof proof.sha256 === 'string' && /^[a-f0-9]{64}$/.test(proof.sha256)))) {
+    throw new Error('Source proofs require exact hashes or explicitly allowed absence.');
+  }
+  const selected = proofs.map(({ file, sha256 }) => ({ file, sha256 }));
+  const inputs = await readSourceInputs(appRoot, selected.map(proof => proof.file), options);
+  return new Map(selected.map(proof => {
+    const source = inputs[proof.file];
+    const hash = source === null ? null : createHash('sha256').update(source).digest('hex');
+    if (hash !== proof.sha256) throw new Error(`Source changed since the baseline was loaded: ${proof.file}`);
+    return [proof.file, { ...proof, source }];
+  }));
+}

package/node/source-service-plugin.mjs

@@ -0,0 +1,57 @@
+/** Local JSON transport. Operation names and all filesystem/build callbacks come from host configuration. */
+export function sourceServicePlugin({ name = 'pygmalion-source-service', endpoint, operations, createService, transformInput = (_operation, input) => input, maxBytes = 40 * 1024 * 1024 }) {
+  if (!/^\/[A-Za-z0-9/_-]+$/.test(endpoint) || endpoint.endsWith('/') || !Array.isArray(operations) || !operations.length
+    || operations.some(operation => !/^[a-z][A-Za-z]+$/.test(operation) || ['constructor', 'dispose'].includes(operation))
+    || typeof createService !== 'function' || typeof transformInput !== 'function' || !Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    throw new Error('A source transport requires a local endpoint, operation allowlist, factory, and byte limit.');
+  }
+  operations = [...operations];
+  let service; const controllers = new Set();
+  const active = () => { if (!service) throw new Error('The source service has not started.'); return service; };
+  return {
+    validatePreviewRequest(request, signal) { return active().validatePreviewRequest(request, signal); },
+    preparePreviewSource(request, root, signal) { return active().preparePreviewSource(request, root, signal); },
+    plugin: {
+      name, apply: 'serve',
+      configureServer(server) {
+        service = createService(server);
+        if (operations.some(operation => typeof service?.[operation] !== 'function')) throw new Error('The source service must implement each configured operation.');
+        server.httpServer?.once('close', () => {
+          for (const controller of controllers) controller.abort();
+          controllers.clear();
+          Promise.resolve().then(() => service.dispose()).catch(error => server.config?.logger?.error(String(error)));
+        });
+        server.middlewares.use(async (req, res, next) => {
+          const pathname = req.url?.split('?')[0];
+          const operation = pathname?.startsWith(`${endpoint}/`) ? pathname.slice(endpoint.length + 1) : undefined;
+          if (!operations.includes(operation)) return next();
+          res.setHeader('content-type', 'application/json; charset=utf-8'); res.setHeader('cache-control', 'no-store');
+          if (req.method !== 'POST') { res.statusCode = 405; res.end(JSON.stringify({ error: 'Source operations require POST.' })); return; }
+          try {
+            if (req.headers.origin && new URL(req.headers.origin).host !== req.headers.host) throw new Error('Origin mismatch.');
+          } catch { res.statusCode = 403; res.end(JSON.stringify({ error: 'Source operations require the editor origin.' })); return; }
+          if (!/^application\/json(?:;|$)/i.test(req.headers['content-type'] ?? '')) {
+            res.statusCode = 415; res.end(JSON.stringify({ error: 'Source operations require JSON.' })); return;
+          }
+          const controller = new AbortController(); controllers.add(controller);
+          const abort = () => { if (!res.writableEnded) controller.abort(); };
+          req.once('aborted', abort); res.once('close', abort);
+          try {
+            const chunks = []; let bytes = 0;
+            for await (const chunk of req) {
+              bytes += chunk.length;
+              if (bytes > maxBytes) throw new Error('Source request exceeds the byte limit.');
+              chunks.push(chunk);
+            }
+            controller.signal.throwIfAborted();
+            const input = transformInput(operation, JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            const result = await service[operation](input, controller.signal);
+            controller.signal.throwIfAborted(); res.end(JSON.stringify(result));
+          } catch (error) {
+            if (!res.destroyed && !res.writableEnded) { res.statusCode = 409; res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) })); }
+          } finally { controllers.delete(controller); req.removeListener('aborted', abort); res.removeListener('close', abort); }
+        });
+      },
+    },
+  };
+}

package/node/source-service.mjs

@@ -0,0 +1,4 @@
+export { createWorkspaceSourceSession } from './workspace-source-session.mjs';
+export { createTokenSourceService } from './token-source-service.mjs';
+export { sourceServicePlugin } from './source-service-plugin.mjs';
+export { assertSourceInputParent, readSourceInputs, readProvenSourceFiles, withSourceFiles } from './source-service-inputs.mjs';