@pygmalionjs/pygmalion 0.8.1 → 0.10.0

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;

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

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