@pygmalionjs/pygmalion 0.8.1 → 0.9.0

package/node/workspace-source-plan.mjs

@@ -0,0 +1,195 @@
+import { createHash } from 'node:crypto';
+import { captureSourceFilePlan } from './source-file-plan.mjs';
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const same = (left, right) => fingerprint(left) === fingerprint(right);
+function freeze(value) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+}
+const capture = value => freeze(JSON.parse(fingerprint(value)));
+function limit(value, maximum, label) {
+  const selected = value ?? maximum;
+  if (!Number.isSafeInteger(selected) || selected < 1 || selected > maximum) throw new Error(`${label} must be a positive integer no greater than ${maximum}.`);
+  return selected;
+}
+function targetIdentity(target) {
+  if (!record(target) || !text(target.screenId) || !text(target.sourceRevision)
+    || Object.keys(target).some(key => !['screenId', 'sourceRevision'].includes(key))) throw new Error('A source target requires an exact screen and source revision.');
+}
+function documentIdentity(document, target) {
+  if (!record(document) || document.schemaVersion !== 1 || !text(document.id)
+    || document.sourceRevision !== target.sourceRevision || !text(document.rootId)
+    || !record(document.nodes) || !record(document.nodes[document.rootId]) || !record(document.metadata)
+    || (document.metadata.screenId !== undefined && document.metadata.screenId !== target.screenId)) {
+    throw new Error('The complete design document must belong to the selected source target.');
+  }
+}
+function baselineIdentity(baseline, target) {
+  if (!record(baseline)) throw new Error('A source baseline requires a document and mapping.');
+  documentIdentity(baseline.document, target);
+  const mapping = baseline.mapping;
+  if (!record(mapping) || mapping.version !== 1 || !same(mapping.target, target)
+    || mapping.documentId !== baseline.document.id || mapping.baselineFingerprint !== fingerprint(baseline.document)
+    || !Array.isArray(mapping.rules) || !Array.isArray(mapping.files) || !mapping.files.length || mapping.files.length > 3000) {
+    throw new Error('The complete source mapping must identify its baseline, target, and file proofs.');
+  }
+  const files = new Set();
+  for (const proof of mapping.files) {
+    if (!record(proof) || !text(proof.file) || /[\\\x00-\x1f\x7f?#]/.test(proof.file)
+      || proof.file.startsWith('/') || /^[a-z]:/i.test(proof.file)
+      || proof.file.split('/').some(part => !part || ['.', '..', '.git'].includes(part))
+      || (proof.sha256 !== null && (typeof proof.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(proof.sha256))) || files.has(proof.file)) {
+      throw new Error('Source mapping proofs require unique relative files and exact SHA-256 hashes or explicit absence.');
+    }
+    files.add(proof.file);
+  }
+}
+function requestIdentity(target, baseline, document, plan) {
+  const parts = { version: 1, target, documentId: document.id, beforeFingerprint: fingerprint(baseline.document),
+    afterFingerprint: fingerprint(document), mappingFingerprint: fingerprint(baseline.mapping), payloadFingerprint: fingerprint(plan) };
+  return { ...parts, fingerprint: fingerprint(parts) };
+}
+function completePreview(result, plan) {
+  const files = new Set(plan.changes.map(change => change.file));
+  const complete = entries => Array.isArray(entries) && entries.length === files.size
+    && new Set(entries).size === files.size && entries.every(file => files.has(file));
+  if (!record(result) || !Array.isArray(result.files) || !complete(result.files.map(entry => entry?.file))
+    || !complete(result.affectedFiles) || result.files.some(entry => !text(entry.diff))) {
+    throw new Error('Review must include each changed file exactly once with a nonempty diff and affected-file entry.');
+  }
+}
+
+/**
+ * Authorize only plans compiled from a fresh host baseline and completely reviewed for one target.
+ * This service performs no source I/O. Host callbacks own compilation semantics and current file proofs.
+ */
+export function createWorkspaceSourcePlanService(options) {
+  const callbacks = Object.fromEntries(['loadBaseline', 'compilePlan', 'previewPlan', 'applyPlan', 'assertTarget'].map(name => [name, options?.[name]]));
+  if (Object.values(callbacks).some(callback => typeof callback !== 'function')) throw new Error('A source plan service requires baseline, compiler, preview, apply, and target callbacks.');
+  const ttl = limit(options.receiptTtlMs, 30 * 60_000, 'Receipt lifetime');
+  const capacity = limit(options.maxReceipts, 8, 'Receipt capacity');
+  const now = options.now ?? Date.now;
+  if (typeof now !== 'function') throw new Error('The source receipt clock must be callable.');
+  const clock = () => { const value = now(); if (!Number.isFinite(value)) throw new Error('The source receipt clock must return a finite timestamp.'); return value; };
+  const receipts = new Map(); const operations = new Set();
+  let disposed = false; let busy = null; let revision = 0;
+  const keyOf = (target, document) => hash(fingerprint({ target, document }));
+  const expired = (receipt, time) => time < receipt.createdAt || time - receipt.createdAt >= ttl;
+
+  const run = async (exclusive, externalSignal, operation) => {
+    if (disposed) throw new Error('The source plan service has been disposed.');
+    if (exclusive && busy) throw new Error('Another source plan operation is in progress.');
+    externalSignal?.throwIfAborted();
+    const controller = new AbortController();
+    const current = { controller };
+    const failureCleanups = [];
+    const abort = () => controller.abort(externalSignal.reason);
+    const check = () => {
+      controller.signal.throwIfAborted();
+      if (disposed) throw new Error('The source plan service has been disposed.');
+    };
+    operations.add(current); if (exclusive) busy = current;
+    try {
+      externalSignal?.addEventListener('abort', abort, { once: true });
+      const result = await operation({ signal: controller.signal, check, onFailure: cleanup => failureCleanups.push(cleanup) });
+      check(); return result;
+    } catch (error) {
+      for (const cleanup of failureCleanups) cleanup();
+      throw error;
+    } finally {
+      externalSignal?.removeEventListener('abort', abort); operations.delete(current);
+      if (busy === current) busy = null;
+    }
+  };
+  const assertTarget = async (target, operation) => {
+    operation.check(); targetIdentity(target);
+    await callbacks.assertTarget(target, operation.signal); operation.check();
+  };
+  const currentReceipt = (key, receipt, operation) => {
+    operation.check();
+    if (!receipt || receipts.get(key) !== receipt || expired(receipt, clock())) {
+      receipts.delete(key);
+      throw new Error('The compiled source receipt is missing, expired, or consumed. Compile and review again.');
+    }
+  };
+  const validate = async (input, operation, requireReview) => {
+    const request = capture(input);
+    if (!record(request) || request.sourceKind !== 'file-plan') throw new Error('A compiled file-plan request is required.');
+    targetIdentity(request.target); documentIdentity(request.document, request.target);
+    await assertTarget(request.target, operation);
+    const key = keyOf(request.target, request.document); const receipt = receipts.get(key);
+    currentReceipt(key, receipt, operation);
+    const identity = requestIdentity(receipt.target, receipt.baseline, receipt.document, receipt.plan);
+    if (!same(request.payload, receipt.plan) || !same(request.identity, identity)) throw new Error('The request must match the complete compiled document, source mapping, target, and file plan.');
+    if (requireReview && receipt.reviewed !== identity.fingerprint) throw new Error('Review the complete source diff for this target before applying or building.');
+    return { request, key, receipt };
+  };
+  return {
+    load(input, signal) {
+      return run(false, signal, async operation => {
+        const target = capture(input); await assertTarget(target, operation);
+        const baseline = capture(await callbacks.loadBaseline(target, operation.signal));
+        operation.check(); baselineIdentity(baseline, target); operation.check(); return baseline;
+      });
+    },
+    compile(input, signal) {
+      return run(true, signal, async operation => {
+        const { target, baseline, document } = capture(input);
+        targetIdentity(target); baselineIdentity(baseline, target); documentIdentity(document, target);
+        if (document.id !== baseline.document.id || document.rootId !== baseline.document.rootId) throw new Error('The edited document must retain the source baseline identity.');
+        if (same(document, baseline.document)) throw new Error('There are no document changes to compile.');
+        const key = keyOf(target, document); receipts.delete(key);
+        await assertTarget(target, operation);
+        const actual = capture(await callbacks.loadBaseline(target, operation.signal));
+        operation.check(); baselineIdentity(actual, target);
+        if (!same(baseline, actual)) throw new Error('The supplied baseline differs from the current host source baseline.');
+        const compiled = await callbacks.compilePlan(capture({ target, baseline: actual, document }), operation.signal);
+        operation.check();
+        const plan = capture(captureSourceFilePlan(compiled, { sourceRevision: target.sourceRevision, allowedFiles: actual.mapping.files.map(proof => proof.file) }));
+        if (!same(plan.proofs, actual.mapping.files)) throw new Error('The compiled plan must retain every source mapping proof exactly.');
+        if (plan.changes.some(change => change.beforeSha256 === hash(change.content))) throw new Error('Every compiled source change must produce different content.');
+        const createdAt = clock(); operation.check();
+        for (const [oldKey, receipt] of receipts) if (expired(receipt, createdAt)) receipts.delete(oldKey);
+        const receipt = { target, baseline: actual, document, plan, createdAt, reviewed: null };
+        receipts.set(key, receipt);
+        operation.onFailure(() => { if (receipts.get(key) === receipt) receipts.delete(key); });
+        while (receipts.size > capacity) receipts.delete(receipts.keys().next().value);
+        return plan;
+      });
+    },
+    preview(input, signal) {
+      return run(true, signal, async operation => {
+        const { request, key, receipt } = await validate(input, operation, false);
+        receipt.reviewed = null;
+        const result = capture(await callbacks.previewPlan(receipt.plan, request.target, operation.signal));
+        currentReceipt(key, receipt, operation); completePreview(result, receipt.plan);
+        receipt.reviewed = request.identity.fingerprint;
+        operation.onFailure(() => { receipt.reviewed = null; });
+        return capture({ ...result, revision: ++revision });
+      });
+    },
+    validatePreviewRequest(input, signal) {
+      return run(true, signal, async operation => (await validate(input, operation, true)).request);
+    },
+    apply(input, signal) {
+      return run(true, signal, async operation => {
+        const { request, receipt } = await validate(input, operation, true);
+        // Once a writer starts, every cached review requires recompilation, including failed or aborted writes.
+        receipts.clear(); operation.check();
+        const result = capture(await callbacks.applyPlan(receipt.plan, request.target, operation.signal));
+        operation.check();
+        if (!record(result) || !Number.isSafeInteger(result.applied) || result.applied < 1) throw new Error('The source writer did not record the reviewed changes. Compile and review again.');
+        return result;
+      });
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true; receipts.clear();
+      for (const operation of operations) operation.controller.abort(new Error('The source plan service has been disposed.'));
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {
@@ -48,12 +48,34 @@
       "types": "./dist-lib/types/testing.d.ts",
       "default": "./dist-lib/testing.js"
     },
-    "./style.css": "./dist-lib/style.css"
+    "./style.css": "./dist-lib/style.css",
+    "./binding-source": {
+      "types": "./binding-source.d.ts",
+      "default": "./node/source-bindings.mjs"
+    },
+    "./draft-preview": {
+      "types": "./draft-preview.d.ts",
+      "default": "./node/workspace-draft-preview.mjs"
+    },
+    "./source-files": {
+      "types": "./source-files.d.ts",
+      "default": "./node/source-file-plan.mjs"
+    },
+    "./source-structure": {
+      "types": "./source-structure.d.ts",
+      "default": "./node/source-structure.mjs"
+    },
+    "./source-plan": {
+      "types": "./workspace-source-plan.d.ts",
+      "default": "./node/workspace-source-plan.mjs"
+    },
+    "./source-responsive": {
+      "types": "./source-responsive.d.ts",
+      "default": "./node/source-responsive.mjs"
+    }
   },
   "files": [
     "dist-lib",
-    "docs/coverage-contracts.md",
-    "docs/screen-state-contract.md",
     "node/contract.mjs",
     "node/contract.d.mts",
     "node/component-branches.mjs",
@@ -79,6 +101,12 @@
     "node/source-diff.mjs",
     "node/source-graph.mjs",
     "node/source-operations.mjs",
+    "node/source-file-proofs.mjs",
+    "node/workspace-source-identity.mjs",
+    "node/workspace-source-identity.d.mts",
+    "node/workspace-draft-preview-plugin.mjs",
+    "node/workspace-draft-preview.mjs",
+    "draft-preview.d.ts",
     "node/storyboard-canonical.mjs",
     "node/storyboard-capture-scheduler.mjs",
     "node/storyboard-capture-sessions.mjs",
@@ -92,13 +120,31 @@
     "qa.d.ts",
     "storyboard.d.ts",
     "runtime.d.ts",
-    "vite.d.ts"
+    "vite.d.ts",
+    "node/source-bindings.mjs",
+    "binding-source.d.ts",
+    "node/source-file-plan.mjs",
+    "node/source-file-lock.mjs",
+    "source-files.d.ts",
+    "node/source-archive.mjs",
+    "node/token-source-references.mjs",
+    "node/source-structure.mjs",
+    "source-structure.d.ts",
+    "node/workspace-source-plan.mjs",
+    "workspace-source-plan.d.ts",
+    "node/source-structure-reconcile.mjs",
+    "node/source-structure-wrapper-codec.mjs",
+    "node/source-structure-wrapper-codec.d.mts",
+    "node/source-responsive.mjs",
+    "source-responsive.d.ts",
+    "node/source-responsive-codec.mjs",
+    "node/source-responsive-codec.d.mts"
   ],
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
     "build:lib": "vite build --config vite.lib.config.ts && npm run build:types",
-    "test": "node --test node/*.test.mjs src/*.test.mjs src/**/*.test.mjs",
+    "test": "node --test 'node/**/*.test.mjs' 'src/**/*.test.mjs'",
     "lint": "eslint .",
     "lint:language": "node scripts/lint-language.mjs",
     "typecheck": "tsc --noEmit",

package/source-files.d.ts

@@ -0,0 +1,35 @@
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { InspectPreviewResult } from './dist-lib/types/editor/host.js';
+
+export interface SourceFilePlanOptions {
+  sourceRevision: string;
+  allowedFiles: readonly string[];
+  excludedSourcePrefixes?: readonly string[];
+  signal?: AbortSignal;
+}
+/** Capture and validate a serializable plan without reading or changing source files. */
+export declare function captureSourceFilePlan(plan: SourceFilePlan, options: SourceFilePlanOptions): SourceFilePlan;
+export declare function previewSourceFilePlan(root: string, plan: SourceFilePlan, options: SourceFilePlanOptions): Promise<Pick<InspectPreviewResult, 'files' | 'affectedFiles'>>;
+export declare function applySourceFilePlan(root: string, plan: SourceFilePlan, options: SourceFilePlanOptions): Promise<{ applied: number; changed: number; files: string[] }>;
+
+export interface TokenSourceReferenceEdit { start: number; end: number; before: string; after: string }
+export interface TokenSourceReferenceDiagnostic { code: string; message: string; file: string; start?: number; name?: string }
+/** Diagnostics block the complete rewrite; offsets address UTF-16 source positions. */
+export declare function rewriteTokenSourceReferences(input: {
+  file: string;
+  source: string;
+  renames: readonly { from: string; to: string | null }[];
+}): {
+  source: string;
+  edits: TokenSourceReferenceEdit[];
+  diagnostics: TokenSourceReferenceDiagnostic[];
+  references: { name: string; start: number; end: number; kind: 'static' | 'finite' }[];
+};
+
+/**
+ * Build/validation workers must settle before the callback returns and its archive is removed.
+ * Cancellation waits for callback settlement and cleanup, then rejects even if the callback returned.
+ */
+export declare function withSourceArchive<T>(options: {
+  projectRoot: string; sourceRevision: string; appDirectory?: string; signal?: AbortSignal;
+}, operation: (context: Readonly<{ appRoot: string; sourceRevision: string; signal: AbortSignal }>) => Promise<T>): Promise<T>;

package/source-responsive.d.ts

@@ -0,0 +1,10 @@
+import type { InspectApplyPayload } from './dist-lib/types/editor/inspect.js';
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { ResponsiveLayoutDocument, ResponsiveLayoutRange, ResponsiveLayoutSourceTarget, WorkspaceResponsiveSourceMapping } from './dist-lib/types/workspace/source/responsiveContracts.js';
+export interface ResponsiveSourceInputFile { file: string; source: string; sha256: string }
+export declare function readResponsiveLayoutSource(input: { files: readonly ResponsiveSourceInputFile[]; ranges: readonly ResponsiveLayoutRange[]; targets: readonly ResponsiveLayoutSourceTarget[] }): ResponsiveLayoutDocument;
+export declare function compileResponsiveSourcePlan(input: {
+  appRoot: string; sourceRevision: string; mapping: WorkspaceResponsiveSourceMapping;
+  before: ResponsiveLayoutDocument; after: ResponsiveLayoutDocument;
+  additionalStyles?: InspectApplyPayload['styles']; signal?: AbortSignal;
+}): Promise<SourceFilePlan>;

package/source-structure.d.ts

@@ -0,0 +1,155 @@
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { WorkspaceStructureGroupLayout, WorkspaceStructureWrapperDeclaration } from './dist-lib/types/workspace/source/contracts.js';
+
+export interface JsxStructureAnchor { nodeId: string; file: string; start: number; end: number; expected: string }
+export type JsxStructureGroupLayout = WorkspaceStructureGroupLayout;
+/**
+ * Host declaration for element wrappers. A group with a layout compiles to
+ * `<tagName className={styleAlias.<derived class>}>` plus one managed block in the
+ * stylesheet; spacing pairs document pixel values with the host's exact CSS spellings.
+ */
+export type JsxStructureWrapperContract = WorkspaceStructureWrapperDeclaration;
+/** The contract and the complete stylesheet bytes matching the JSX source being read. */
+export interface JsxStructureWrapperEvidence { contract: JsxStructureWrapperContract; source: string }
+export type JsxStructureOperation =
+  | { kind: 'reorder'; parentId: string; children: readonly string[] }
+  /** Index addresses the final list after removing the node from its original parent. */
+  | { kind: 'reparent'; nodeId: string; parentId: string; index: number }
+  /** A layout requires the plan's wrapper contract; without one the group is an anonymous fragment. */
+  | { kind: 'group'; nodeIds: readonly string[]; groupId: string; layout?: JsxStructureGroupLayout }
+  /** Removes an anonymous fragment or a generated wrapper element together with its managed block. */
+  | { kind: 'ungroup'; nodeId: string };
+export interface JsxStructureDiagnostic { code: string; message: string; file?: string; nodeId?: string }
+export interface JsxStructureSourceNode {
+  nodeId: string; parentId: string | null; children: string[];
+  kind: 'element' | 'expression' | 'fragment' | 'text';
+  tagName?: string;
+  /** Only a static string literal is reported; bindings and CSS module expressions are not evaluated. */
+  className?: string;
+  /** Present only for a generated wrapper element proved against its managed stylesheet block. */
+  layout?: JsxStructureGroupLayout;
+  wrapper?: { className: string };
+  runtimePath: number[]; start: number; end: number;
+}
+/** Persist alongside the source in the same reviewed file plan; offsets are UTF-16 source positions. */
+export interface JsxStructureIdentity {
+  version: 1;
+  file: string;
+  sourceSha256: string;
+  rootId: string;
+  opaqueNodeIds: string[];
+  anchors: { nodeId: string; start: number; end: number }[];
+  /** Generated wrapper groups; absent when the island has none. */
+  wrappers?: { nodeId: string; className: string }[];
+}
+/** Checks the supplied anchor snippets and full AST projection before returning serializable evidence. */
+export declare function createJsxStructureIdentity(input: {
+  file: string; source: string; rootId: string; anchors: readonly JsxStructureAnchor[]; opaqueNodeIds?: readonly string[];
+  /** Required to record wrapper groups; the stylesheet must be the bytes reviewed with this source. */
+  wrapper?: JsxStructureWrapperEvidence;
+}): JsxStructureIdentity;
+/**
+ * Throws on stale bytes, malformed identity, missing nodes or ambiguous ranges. Never guesses IDs.
+ * Recorded wrappers require the wrapper evidence; a wrapper whose element or managed block was
+ * edited by hand fails closed instead of degrading to a plain element.
+ */
+export declare function reimportJsxStructureSource(input: {
+  file: string; source: string; identity: JsxStructureIdentity; wrapper?: JsxStructureWrapperEvidence;
+}): { anchors: JsxStructureAnchor[]; nodes: JsxStructureSourceNode[] };
+/**
+ * Throws for invalid source, ambiguous roots, or opaque offsets outside the projected tree.
+ * Runtime paths exclude blank multiline indentation and comment-only expressions. Expressions
+ * that evaluate to false or undefined still occupy one slot; their values are never evaluated.
+ */
+export declare function inspectJsxStructureSource(input: {
+  file: string; source: string; rootStart: number; opaqueNodeStarts?: readonly number[];
+}): { anchors: JsxStructureAnchor[]; nodes: JsxStructureSourceNode[] };
+/**
+ * Pure source compilation; the host audits allowed containers and the complete canonical-document delta.
+ * Expressions move only as complete opaque chunks within one static JSX tree. Rendered text and
+ * standalone comments in an edited parent block ambiguous hierarchy changes. Groups without a layout
+ * are anonymous fragments, which do not provide a DOM box. With a wrapper contract, a group with a
+ * layout emits one intrinsic element and a managed block in the contract stylesheet, which must be
+ * supplied in `files` and allowed for writing. Neither form certifies preservation of component
+ * reconciliation state across a React remount. Props, handlers, and expression source are preserved
+ * without evaluation or fixture substitution.
+ */
+export declare function compileJsxStructurePlan(input: {
+  sourceRevision: string;
+  files: readonly { file: string; source: string; sha256: string }[];
+  anchors: readonly JsxStructureAnchor[];
+  operations: readonly JsxStructureOperation[];
+  allowedFiles: readonly string[];
+  excludedSourcePrefixes?: readonly string[];
+  wrapper?: JsxStructureWrapperContract;
+}): { status: 'ready'; payload: SourceFilePlan; anchors: JsxStructureAnchor[] }
+  | { status: 'unchanged'; anchors: JsxStructureAnchor[] }
+  | { status: 'blocked'; diagnostics: JsxStructureDiagnostic[] };
+
+export interface JsxStructureReconciliationInput {
+  file: string;
+  baseline: { sourceRevision: string; source: string; identity: JsxStructureIdentity };
+  external: {
+    /** May equal the baseline commit for explicitly checked working-copy changes. */
+    sourceRevision: string;
+    source: string;
+    sha256: string;
+    /**
+     * Complete host-supplied correspondence to the current AST. Retained IDs explicitly mean
+     * the same source-owned nodes; new IDs must be fresh. Core never infers this mapping from
+     * names, positions, snippets, runtime values, or example data. Every range and hash is checked.
+     */
+    identity: JsxStructureIdentity;
+  };
+  /** Complete audited draft structure relative to baseline; the host checks other document deltas. */
+  operations: readonly JsxStructureOperation[];
+  allowedFiles: readonly string[];
+  excludedSourcePrefixes?: readonly string[];
+  /** Required when either identity records wrapper groups or the draft adds one. */
+  wrapper?: {
+    contract: JsxStructureWrapperContract;
+    baselineSource: string;
+    externalSource: string;
+    externalSha256: string;
+  };
+}
+export interface JsxStructureReconciliationShape {
+  kind: JsxStructureSourceNode['kind'];
+  parentId: string | null;
+  children: string[];
+  layout: JsxStructureGroupLayout | null;
+}
+export interface JsxStructureReconciliationDiagnostic extends JsxStructureDiagnostic {
+  action: 'refresh-source' | 'map-identities' | 'resolve-overlap';
+  baseline?: JsxStructureReconciliationShape | null;
+  external?: JsxStructureReconciliationShape | null;
+  draft?: JsxStructureReconciliationShape | null;
+}
+export interface ReconciledJsxStructureSource {
+  file: string;
+  baselineSourceRevision: string;
+  baselineSourceSha256: string;
+  /** The external revision is retained; the baseline is never silently relabeled. */
+  sourceRevision: string;
+  externalSourceSha256: string;
+  source: string;
+  /** Persist with the resulting source using a separately reviewed, exact file plan. */
+  identity: JsxStructureIdentity;
+  /** The contract stylesheet after the merge; present only when wrapper input was supplied. */
+  stylesheetSource?: string;
+  anchors: JsxStructureAnchor[];
+  nodes: JsxStructureSourceNode[];
+  diagnostics: readonly [];
+}
+export type JsxStructureReconciliationResult =
+  | (ReconciledJsxStructureSource & { status: 'ready'; payload: SourceFilePlan })
+  | (ReconciledJsxStructureSource & { status: 'unchanged' })
+  | { status: 'conflict'; diagnostics: readonly JsxStructureReconciliationDiagnostic[] };
+/**
+ * Pure, explicit three-way reconciliation. Disjoint child-list changes merge; overlapping lists,
+ * removals, incompatible boundaries, competing wrapper layouts and ambiguous identities require
+ * explicit conflict resolution. External props and expression bytes survive structure-only edits.
+ * Host source ownership and document/binding validation still apply. A ready plan proves the
+ * latest external bytes only.
+ */
+export declare function reconcileJsxStructurePlan(input: JsxStructureReconciliationInput): JsxStructureReconciliationResult;

package/workspace-source-plan.d.ts

@@ -0,0 +1,44 @@
+import type { DesignDocument } from './dist-lib/types/document/contracts.js';
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { InspectApplyResult, InspectPreviewResult } from './dist-lib/types/editor/host.js';
+import type { WorkspaceTarget } from './dist-lib/types/workspace/contracts.js';
+import type { WorkspaceFileSourceRequest, WorkspaceSourceBaseline } from './dist-lib/types/workspace/source/flowContracts.js';
+
+export interface WorkspaceSourcePlanCompileInput {
+  target: WorkspaceTarget;
+  baseline: WorkspaceSourceBaseline;
+  document: DesignDocument;
+}
+
+export interface WorkspaceSourcePlanServiceOptions {
+  /** Callbacks receive detached, deeply frozen JSON captures and must settle on cancellation. */
+  loadBaseline(target: WorkspaceTarget, signal: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  /** Owns full document validation and the source semantics of every changed field. */
+  compilePlan(input: WorkspaceSourcePlanCompileInput, signal: AbortSignal): Promise<SourceFilePlan>;
+  /** Must check current file proofs; the service checks complete, nonempty diff coverage. */
+  previewPlan(plan: SourceFilePlan, target: WorkspaceTarget, signal: AbortSignal): Promise<Pick<InspectPreviewResult, 'files' | 'affectedFiles'> & Partial<Pick<InspectPreviewResult, 'qa'>>>;
+  /** Must recheck current source revision and proofs and apply the complete plan atomically. */
+  applyPlan(plan: SourceFilePlan, target: WorkspaceTarget, signal: AbortSignal): Promise<InspectApplyResult>;
+  assertTarget(target: WorkspaceTarget, signal: AbortSignal): void | Promise<void>;
+  /** Default and maximum: 30 minutes. Review never extends this lifetime. */
+  receiptTtlMs?: number;
+  /** Default and maximum: 8 compiled document receipts. */
+  maxReceipts?: number;
+  now?: () => number;
+}
+
+export interface WorkspaceSourcePlanService {
+  /** Loads may run concurrently; every other operation is mutually exclusive. */
+  load(target: WorkspaceTarget, signal?: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  /** Reloads and compares the complete baseline before issuing a bounded server receipt. */
+  compile(input: WorkspaceSourcePlanCompileInput, signal?: AbortSignal): Promise<SourceFilePlan>;
+  preview(request: WorkspaceFileSourceRequest, signal?: AbortSignal): Promise<InspectPreviewResult>;
+  /** A writer attempt consumes all receipts. Cancellation does not establish rollback. */
+  apply(request: WorkspaceFileSourceRequest, signal?: AbortSignal): Promise<InspectApplyResult>;
+  /** Required before preparing an immutable built artifact from a browser-supplied file plan. */
+  validatePreviewRequest(request: WorkspaceFileSourceRequest, signal?: AbortSignal): Promise<WorkspaceFileSourceRequest>;
+  /** Aborts in-flight callbacks, clears receipts, and rejects their later completions. */
+  dispose(): void;
+}
+
+export declare function createWorkspaceSourcePlanService(options: WorkspaceSourcePlanServiceOptions): WorkspaceSourcePlanService;