@pygmalionjs/pygmalion 0.8.1 → 0.10.0

package/dist-lib/types/workspace/tokens/controller.d.ts

@@ -0,0 +1,44 @@
+import type { TokenLibraryEngine } from '../../token-library/contracts.js';
+import type { InspectApplyResult, InspectPreviewResult } from '../../editor/host.js';
+import type { WorkspaceTarget } from '../contracts.js';
+import type { WorkspaceTokenLibraryBaseline, WorkspaceTokenLibraryCapabilities, WorkspaceTokenSourceRequest } from './contracts.js';
+export interface WorkspaceTokenLibraryState {
+    status: 'idle' | 'loading' | 'ready' | 'reviewing' | 'reviewed' | 'applying' | 'applied' | 'error';
+    baseline?: WorkspaceTokenLibraryBaseline;
+    engine?: TokenLibraryEngine;
+    request?: WorkspaceTokenSourceRequest;
+    preview?: InspectPreviewResult;
+    result?: InspectApplyResult;
+    savedFingerprint?: string;
+    saving?: boolean;
+    error?: string;
+}
+/** A library owns its draft and review independently from visual screen sessions. */
+export declare class WorkspaceTokenLibraryController {
+    private state;
+    private listeners;
+    private epoch;
+    private pending;
+    private pendingSave;
+    private saveGeneration;
+    private disposed;
+    private invalidating;
+    private applying;
+    private unsubscribe;
+    private writer;
+    readonly capabilities: WorkspaceTokenLibraryCapabilities;
+    readonly sourceRevision: string;
+    constructor(sourceRevision: string, capabilities: WorkspaceTokenLibraryCapabilities);
+    getSnapshot: () => WorkspaceTokenLibraryState;
+    subscribe: (listener: () => void) => () => void;
+    private update;
+    private invalidate;
+    private current;
+    private subscribeEngine;
+    load(): Promise<boolean>;
+    saveDraft(): Promise<boolean>;
+    review(target: WorkspaceTarget): Promise<boolean>;
+    apply(): Promise<boolean>;
+    reset(): boolean;
+    dispose(): void;
+}

package/dist-lib/types/workspace/view/PrototypePlayer.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import type { DesignDocument } from '../../document/contracts.js';
+import { type PrototypeState } from '../../document/prototype.js';
+import { type PrototypeClock } from './prototypePlayback.js';
+
+export interface PrototypePlayerProps {
+    document: DesignDocument;
+    /** Uses the same document/component renderer as Edit, with authoring controls disabled. */
+    renderScene(rootId: string, state: PrototypeState): ReactNode;
+    sceneSize?(rootId: string, state: PrototypeState): {
+        width: number;
+        height: number;
+    } | undefined;
+    onClose(): void;
+    clock?: PrototypeClock;
+}
+export declare function PrototypePlayer(props: PrototypePlayerProps): import("react").JSX.Element;

package/dist-lib/types/workspace/view/StoryboardWorkspace.d.ts

@@ -0,0 +1,3 @@
+export declare const StoryboardWorkspace: import("react").FunctionComponent<{
+    sourceRevision: string;
+}>;

package/dist-lib/types/workspace/view/prototypePlayback.d.ts

@@ -0,0 +1,46 @@
+import type { DesignDocument, DocumentNode, ResolvedDocumentNode } from '../../document/contracts.js';
+import { type PrototypeEffect, type PrototypeEvent, type PrototypeStartOptions, type PrototypeState } from '../../document/prototype.js';
+export interface PrototypeClock {
+    now(): number;
+    schedule(callback: () => void, delayMs: number): unknown;
+    cancel(handle: unknown): void;
+}
+export interface PrototypePlayerSnapshot {
+    state: PrototypeState;
+    previous: PrototypeState | null;
+    effects: readonly PrototypeEffect[];
+    playing: boolean;
+}
+export interface PrototypePlayerOptions extends PrototypeStartOptions {
+    clock: PrototypeClock;
+    /** Effects describe intended links and scrolling; the adapter decides how to execute them. */
+    onEffect?(effect: PrototypeEffect): void;
+}
+export interface PrototypePlayerController {
+    getSnapshot(): PrototypePlayerSnapshot;
+    subscribe(listener: () => void): () => void;
+    dispatch(event: PrototypeEvent): void;
+    pause(): void;
+    resume(): void;
+    dispose(): void;
+}
+/** One document snapshot and one clock. Playback cannot mutate the document engine or its history. */
+export declare function createPrototypePlayer(document: DesignDocument, options: PrototypePlayerOptions): PrototypePlayerController;
+export interface PrototypePresentationScene {
+    id: string;
+    rootId: string;
+    root: ResolvedDocumentNode;
+    x: number;
+    y: number;
+    overlay: boolean;
+    backdrop: {
+        color: string;
+        opacity: number;
+    } | null;
+}
+export declare function prototypeScene(document: DesignDocument, state: PrototypeState): PrototypePresentationScene[];
+export declare function prototypeFlowOptions(document: DesignDocument): {
+    id: string;
+    label: string;
+    node: DocumentNode;
+}[];

package/draft-preview.d.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { WorkspaceSourceRequest } from './dist-lib/types/workspace/source/flowContracts.js';
+import type { WorkspaceTokenSourceRequest } from './dist-lib/types/workspace/tokens/contracts.js';
+import type { WorkspaceApplicationSurface } from './dist-lib/types/workspace/contracts.js';
+
+export type WorkspaceDraftSourceRequest = WorkspaceSourceRequest | WorkspaceTokenSourceRequest;
+
+export interface WorkspaceDraftPreviewServiceOptions {
+  projectRoot: string;
+  appDirectory?: string;
+  /** Existing node_modules directory reused by the trusted isolated build. */
+  dependenciesRoot?: string;
+  /**
+   * Stage proven working-copy inputs in the disposable archive. Full request proofs are checked afterward.
+   * `appRoot` holds exactly `sourceRevision` (the request target), materialized from the repository
+   * history rather than the working tree, so another revision than the checkout can be built honestly.
+   */
+  prepareSource?(context: { appRoot: string; request: WorkspaceDraftSourceRequest; sourceRevision: string; signal: AbortSignal }): Promise<void>;
+  /** Must stop and settle when aborted; outputDirectory must contain a completed static app. */
+  build(context: { appRoot: string; outputDirectory: string; request: WorkspaceDraftSourceRequest; sourceRevision: string; signal: AbortSignal }): Promise<void>;
+  /** Return true after handling a host API request. False or void allows static routing. */
+  handleRequest?(request: IncomingMessage, response: ServerResponse, context: { request: WorkspaceDraftSourceRequest; sourceRevision: string }): boolean | void | Promise<boolean | void>;
+  /** Active builds and ready origins count toward this bound. Default: 3. */
+  maxRuns?: number;
+  maxOutputFiles?: number;
+  maxOutputBytes?: number;
+}
+
+export declare function createWorkspaceDraftPreviewService(options: WorkspaceDraftPreviewServiceOptions): {
+  /** The host must validate file-plan requests with its canonical compiler before preparing a build. */
+  prepare(input: { request: WorkspaceDraftSourceRequest; documentRevision: string; route: string }, options?: { signal?: AbortSignal }): Promise<WorkspaceApplicationSurface>;
+  /** Abort builds, close origins, and remove every temporary archive. */
+  dispose(): Promise<void>;
+};
+
+/** Minimal Vite-compatible boundary; headless service consumers do not require Vite types. */
+export declare function workspaceDraftPreviewPlugin(options: {
+  service: ReturnType<typeof createWorkspaceDraftPreviewService>;
+  endpoint?: string;
+  /** The built app reports its recipe result through the workspace ready-message protocol. */
+  waitForReady?: boolean;
+  /** Validate file-plan source semantics with the host compiler, not only browser-supplied fingerprints. */
+  resolveRequest(input: unknown, options: { signal: AbortSignal }):
+    { request: WorkspaceDraftSourceRequest; documentRevision: string; route: string } |
+    Promise<{ request: WorkspaceDraftSourceRequest; documentRevision: string; route: string }>;
+}): {
+  name: string;
+  apply: 'serve';
+  configureServer(server: {
+    httpServer?: { once(event: 'close', listener: () => void): unknown } | null;
+    config: { logger: { error(message: string): void } };
+    middlewares: { use(handler: (request: IncomingMessage, response: ServerResponse, next: () => void) => void | Promise<void>): unknown };
+  }): void;
+};

package/host-runtime.d.ts

@@ -0,0 +1,73 @@
+import type { SpawnOptions } from 'node:child_process';
+import type { PygmalionRevisionCatalog } from './dist-lib/types/editor/revisionCatalog.js';
+
+export interface WorkspaceDraftProcessOptions extends Omit<SpawnOptions, 'signal' | 'detached' | 'stdio' | 'timeout' | 'killSignal'> {
+  signal?: AbortSignal;
+  /** Milliseconds before cancellation. Zero disables the deadline. Default: 240,000. */
+  timeout?: number;
+  /** Milliseconds between SIGTERM and SIGKILL. Default: 1,000. */
+  terminationGraceMs?: number;
+  /** Maximum bytes per output stream. Default: 8 MiB. */
+  maxBuffer?: number;
+}
+
+/** macOS/Linux: waits for process-group cleanup on success, failure, cancellation, and timeout. */
+export declare function executeWorkspaceDraftProcess(
+  command: string, args: readonly string[], options?: WorkspaceDraftProcessOptions,
+): Promise<{ stdout: string; stderr: string }>;
+
+export interface RevisionCatalogResolver {
+  /** Only complete SHA-1 or SHA-256 commits are accepted; returned catalogs are frozen copies. */
+  resolve(sourceRevision: string, signal?: AbortSignal): Promise<PygmalionRevisionCatalog>;
+  currentRevision(signal?: AbortSignal): Promise<string>;
+  /** Least recently used first; expired and current-build entries are omitted. */
+  retained(): string[];
+  /** Cancels owned generation, discards cached results, and rejects subsequent requests. */
+  dispose(): void;
+}
+
+export interface RevisionCatalogResolverOptions {
+  projectRoot?: string;
+  /** Repository-relative application directory. Default: the repository root. */
+  appDirectory?: string;
+  currentCatalog(signal?: AbortSignal): unknown | Promise<unknown>;
+  generate(context: { archiveRoot: string; sourceRevision: string; signal: AbortSignal }): unknown | Promise<unknown>;
+  /** Defaults to commits reachable from HEAD or repository branches, remotes, and tags. */
+  reachable?(sourceRevision: string, signal: AbortSignal): boolean | Promise<boolean>;
+  /** Custom extraction must await its callback and stop workers before removing source files. */
+  archive?<T>(sourceRevision: string, signal: AbortSignal,
+    operation: (context: Readonly<{ appRoot: string; sourceRevision: string; signal: AbortSignal }>) => Promise<T>): Promise<T>;
+  /** Defaults to 4 archived catalogs; zero disables retention. */
+  maxEntries?: number;
+  /** Absolute lifetime since generation, in milliseconds. Default: 30 minutes. */
+  maxAgeMs?: number;
+}
+
+/** Shares requests for each revision and serializes archive/build work across revisions. */
+export declare function createRevisionCatalogResolver(options: RevisionCatalogResolverOptions): RevisionCatalogResolver;
+
+/** Returns dependency search paths from the first byte-identical lockfile, or [] for an archive-local install. */
+export declare function resolveSourceArchiveDependencies(options: {
+  archiveRoot: string; dependencyRoots: readonly string[]; lockfile?: string;
+}): Promise<string[]>;
+
+/** Rejects host worktrees, Git metadata, and missing or linked required directories. */
+export declare function assertIsolatedSourceRoot(options: {
+  archiveRoot: string; hostRoot: string; requiredDirectories?: readonly string[];
+}): Promise<string>;
+
+/** Converts SIGTERM/SIGINT into cancellation and exit status; dispose removes its process listeners. */
+export declare function createWorkspaceDraftLifecycle(): Readonly<{
+  signal: AbortSignal;
+  dispose(): void;
+}>;
+
+/** Requires canonical source/output directories belonging to one SDK draft-preview temporary root. */
+export declare function assertWorkspaceDraftDirectories(options: {
+  appRoot: string; outputDirectory: string; appDirectory?: string;
+}): Promise<Readonly<{ appRoot: string; outputDirectory: string; temporaryRoot: string }>>;
+
+/** Imports the installed package's explicit exports['.'].import entry; no parent-install fallback. */
+export declare function importIsolatedPackage<T = Record<string, unknown>>(options: {
+  appRoot: string; name: string;
+}): Promise<T>;

package/inspect.d.ts

@@ -1,6 +1,8 @@
 import type { InspectApplyPayload } from './dist-lib/types/lib';
 
 export interface PygmalionInspectWritebackOptions {
+  /** If supplied, source proofs must use this exact source revision. */
+  sourceRevision?: string;
   sourceDirectory?: string;
   normalizeValue?: (property: string, value: string) => string;
 }

package/jsx-source-reconciler.d.ts

@@ -0,0 +1,35 @@
+import type { WorkspaceTarget } from './dist-lib/types/workspace/contracts.js';
+import type { WorkspaceSourceBaseline, WorkspaceSourceReconcileInput, WorkspaceSourceReconcileResult } from './dist-lib/types/workspace/source/flowContracts.js';
+import type { compileWorkspaceDocumentSource } from './dist-lib/types/workspace/source/structure.js';
+import type { JsxStructureAnchor, JsxStructureIdentity, JsxStructureSourceNode, JsxStructureWrapperEvidence } from './source-structure.js';
+
+export type ReconcileSourceInputs = Readonly<Record<string, string | null>>;
+export interface ReconcileSourceProjection { anchors: JsxStructureAnchor[]; nodes: JsxStructureSourceNode[] }
+export interface JsxSourceReconcilerOptions {
+  file: string;
+  identityFile: string;
+  rootId: string;
+  definitionId: string;
+  screenId: string;
+  documentId: string;
+  opaqueNodeIds: readonly string[];
+  /** The owner validates original expressions and allowed source structure. */
+  projectSource(input: { source: string; identity: JsxStructureIdentity | null; sourceInputs: ReconcileSourceInputs }): ReconcileSourceProjection;
+  resolveWrapper?(inputs: ReconcileSourceInputs): JsxStructureWrapperEvidence | undefined;
+  /** Pass the SDK's document compiler; injecting it avoids loading the browser bundle in Node. */
+  compileDocumentSource: typeof compileWorkspaceDocumentSource;
+  /** Explicit policy for a unique byte-identical island; changed or duplicate islands remain conflicts. Default: false. */
+  allowUnchangedIslandRelocation?: boolean;
+}
+export interface JsxReconcileInputs {
+  baselineInputs: ReconcileSourceInputs;
+  externalInputs: ReconcileSourceInputs;
+  baselineIdentity?: JsxStructureIdentity;
+}
+export interface JsxSourceReconciler {
+  projectInputs(input: JsxReconcileInputs): { identity: JsxStructureIdentity; projectedStructure: ReconcileSourceProjection };
+  reconcile(input: WorkspaceSourceReconcileInput & JsxReconcileInputs & {
+    loadBaseline(input: { target: WorkspaceTarget; sourceInputs: ReconcileSourceInputs; projectedStructure: ReconcileSourceProjection }, signal?: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  }, signal?: AbortSignal): Promise<WorkspaceSourceReconcileResult>;
+}
+export declare function createJsxSourceReconciler(options: JsxSourceReconcilerOptions): JsxSourceReconciler;

package/node/design-session.mjs

@@ -12,6 +12,7 @@ import { normalizeViteMode } from './dev-mirror.mjs';
 import { writeStyleEdit, writeTextEdit } from './inspect-plugin.mjs';
 import { createUnifiedDiff } from './source-diff.mjs';
 import { writeSourceOperations } from './source-operations.mjs';
+import { validateInspectSourceProofs } from './source-file-proofs.mjs';
 import { resolvePygmalionPreviewViteCacheDir } from './preview-vite-cache.mjs';
 import { sendJson as sendJsonEnvelope } from './envelope.mjs';
 
@@ -696,6 +697,7 @@ export function pygmalionDesignSessionPlugin(options) {
       if (dirty) throw new Error(`There are unconfirmed changes in the edit session task folder:${dirty.split('\n')[0]}`);
 
       const sessionAppRoot = appRootForWorktree(session.worktreeRoot);
+      await validateInspectSourceProofs(sessionAppRoot, input.changes, { sourceRevision: session.baseDevSha });
       const files = collectVisualFiles(sessionAppRoot, changes);
       const before = new Map();
       for (const [relativeFile, absoluteFile] of files) {
@@ -748,6 +750,7 @@ export function pygmalionDesignSessionPlugin(options) {
       if (dirty) throw new Error(`There are unconfirmed changes in the edit session task folder:${dirty.split('\n')[0]}`);
 
       const sessionAppRoot = appRootForWorktree(session.worktreeRoot);
+      await validateInspectSourceProofs(sessionAppRoot, input.changes, { sourceRevision: session.baseDevSha });
       const files = collectVisualFiles(sessionAppRoot, { styles, texts, operations });
       const backups = new Map();
       for (const [relativeFile, absoluteFile] of files) {

package/node/host-runtime.mjs

@@ -0,0 +1,4 @@
+export { executeWorkspaceDraftProcess } from './workspace-draft-process.mjs';
+export { createRevisionCatalogResolver } from './revision-catalog-resolver.mjs';
+export { assertIsolatedSourceRoot, resolveSourceArchiveDependencies } from './source-archive-runtime.mjs';
+export { createWorkspaceDraftLifecycle, assertWorkspaceDraftDirectories, importIsolatedPackage } from './workspace-draft-runtime.mjs';

package/node/inspect-plugin.mjs

@@ -24,8 +24,10 @@ export { writeSourceOperations } from './source-operations.mjs';
 // POST /__pygmalion-inspect/impact — Check dedependency closure of changed files.
 // The editor doesn't know the endpoint URL — the onInspectApply callback in design-editor.tsx POSTs here.
 
+// Only a real import statement at the start of a line registers; the same text inside a
+// string literal or comment must not create a registration for an undefined identifier.
 const CSS_MODULE_IMPORT_RE =
-  /import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+\.module\.scss)['"]\s*;?/g;
+  /^[ \t]*import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+\.module\.scss)['"]\s*;?/gm;
 
 export const PYGMALION_INSPECT_CONTROL = PYGMALION_ENDPOINTS.inspectControl;
 

package/node/inspect-writeback.mjs

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { writeStyleEdit, writeTextEdit } from './inspect-plugin.mjs';
 import { createUnifiedDiff } from './source-diff.mjs';
 import { writeSourceOperations } from './source-operations.mjs';
+import { validateInspectSourceProofs } from './source-file-proofs.mjs';
+import { withSourceFileLock } from './source-file-lock.mjs';
 
 const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '.cjs', '.cts']);
 
@@ -100,8 +102,9 @@ async function applyInspectChanges(root, changes, options) {
   };
 }
 
-export async function previewInspectChanges(root, input, options = {}) {
+async function previewInspectChangesUnlocked(root, input, options = {}) {
   const appRoot = path.resolve(root);
+  await validateInspectSourceProofs(appRoot, input, options);
   const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
   const changes = normalizeInspectChanges(input);
   const files = collectInspectFiles(appRoot, changes, sourceDirectory);
@@ -136,8 +139,9 @@ export async function previewInspectChanges(root, input, options = {}) {
   }
 }
 
-export async function writeInspectChanges(root, input, options = {}) {
+async function writeInspectChangesUnlocked(root, input, options = {}) {
   const appRoot = path.resolve(root);
+  await validateInspectSourceProofs(appRoot, input, options);
   const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
   const changes = normalizeInspectChanges(input);
   const files = collectInspectFiles(appRoot, changes, sourceDirectory);
@@ -161,3 +165,15 @@ export async function writeInspectChanges(root, input, options = {}) {
     throw error;
   }
 }
+
+export async function previewInspectChanges(root, input, options = {}) {
+  const snapshot = structuredClone(input);
+  const configuration = { ...options };
+  return withSourceFileLock(root, base => previewInspectChangesUnlocked(base, snapshot, configuration));
+}
+
+export async function writeInspectChanges(root, input, options = {}) {
+  const snapshot = structuredClone(input);
+  const configuration = { ...options };
+  return withSourceFileLock(root, base => writeInspectChangesUnlocked(base, snapshot, configuration));
+}

package/node/jsx-source-reconciler.mjs

@@ -0,0 +1,155 @@
+import { createHash } from 'node:crypto';
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+import { createJsxStructureIdentity, reconcileJsxStructurePlan, reimportJsxStructureSource } from './source-structure.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const same = (left, right) => fingerprint(left) === fingerprint(right);
+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;
+}
+const capture = value => freeze(JSON.parse(fingerprint(value)));
+function fail(code, message, file) {
+  throw Object.assign(new Error(message), { diagnostics: [{ code: `source-reconcile-${code}`, message, ...(file ? { file } : {}) }] });
+}
+const sourceLayout = layout => layout ? { direction: layout.direction, gap: layout.gap, padding: layout.padding, ...(layout.align === undefined ? {} : { align: layout.align }) } : null;
+
+/** Reconciles one explicitly declared, unchanged source island while delegating product ownership to its projector. */
+export function createJsxSourceReconciler({
+  file, identityFile, rootId, definitionId, screenId, documentId, opaqueNodeIds,
+  projectSource, resolveWrapper = () => undefined, compileDocumentSource,
+  allowUnchangedIslandRelocation = false,
+}) {
+  if ([file, identityFile, rootId, definitionId, screenId, documentId].some(value => typeof value !== 'string' || !value)
+    || file === identityFile || !Array.isArray(opaqueNodeIds) || new Set(opaqueNodeIds).size !== opaqueNodeIds.length
+    || opaqueNodeIds.some(value => typeof value !== 'string' || !value)
+    || ![projectSource, resolveWrapper, compileDocumentSource].every(value => typeof value === 'function')) {
+    throw new TypeError('A source reconciler requires explicit files, node identities, and projection/compiler callbacks.');
+  }
+  opaqueNodeIds = [...opaqueNodeIds];
+  function capturedInputs(value) {
+    if (!record(value) || Object.keys(value).length > 500 || !Object.hasOwn(value, identityFile)
+      || typeof value[file] !== 'string' || !value[file]) fail('inputs-invalid', 'Complete source and identity inputs are required.');
+    let size = 0;
+    for (const [inputFile, content] of Object.entries(value)) {
+      if (content === null && inputFile === identityFile) continue;
+      if (typeof content !== 'string' || Buffer.from(content).toString('utf8') !== content) fail('inputs-invalid', 'Source inputs must be UTF-8 strings.', inputFile);
+      size += Buffer.byteLength(content);
+    }
+    if (size > 32 * 1024 * 1024) fail('inputs-invalid', 'Source inputs exceed the reconciliation size limit.');
+  }
+  function sourceIdentity(inputs, baselineIdentity) {
+    const source = inputs[file];
+    const supplied = baselineIdentity ?? (inputs[identityFile] === null ? null : JSON.parse(inputs[identityFile]));
+    const wrapper = resolveWrapper(inputs);
+    const projectedStructure = capture(projectSource({ source, identity: supplied, sourceInputs: inputs }));
+    const identity = supplied ?? createJsxStructureIdentity({
+      file, source, rootId, anchors: projectedStructure.anchors, opaqueNodeIds, ...(wrapper ? { wrapper } : {}),
+    });
+    return { identity, projectedStructure, wrapper };
+  }
+  function projectInputs(input) {
+    const { baselineInputs, externalInputs, baselineIdentity } = capture({
+      baselineInputs: input.baselineInputs, externalInputs: input.externalInputs,
+      ...(input.baselineIdentity === undefined ? {} : { baselineIdentity: input.baselineIdentity }),
+    });
+    capturedInputs(baselineInputs); capturedInputs(externalInputs);
+    if (!same(Object.keys(baselineInputs).sort(), Object.keys(externalInputs).sort())) fail('input-set-conflict', 'The complete source input sets differ.');
+    for (const inputFile of Object.keys(baselineInputs)) {
+      if (![file, identityFile].includes(inputFile) && baselineInputs[inputFile] !== externalInputs[inputFile]) {
+        fail('dependency-conflict', 'A source dependency changed and requires separate review.', inputFile);
+      }
+    }
+    const original = sourceIdentity(baselineInputs, baselineIdentity);
+    const oldRoot = original.projectedStructure.anchors.find(anchor => anchor.nodeId === rootId);
+    if (!oldRoot) fail('island-conflict', 'The declared source island is missing.', file);
+    const source = externalInputs[file];
+    const start = source.indexOf(oldRoot.expected);
+    if (start < 0 || source.indexOf(oldRoot.expected, start + oldRoot.expected.length) !== -1) {
+      fail('island-conflict', 'The source island changed or no longer has a unique unchanged match.', file);
+    }
+    if (source !== baselineInputs[file] && !allowUnchangedIslandRelocation) {
+      fail('relocation-disabled', 'The source owner has not allowed unchanged island relocation.', file);
+    }
+    const offset = start - oldRoot.start;
+    const anchors = original.projectedStructure.anchors.map(anchor => ({ ...anchor, start: anchor.start + offset, end: anchor.end + offset }));
+    const wrapper = resolveWrapper(externalInputs);
+    const identity = createJsxStructureIdentity({ file, source, rootId, anchors, opaqueNodeIds: original.identity.opaqueNodeIds, ...(wrapper ? { wrapper } : {}) });
+    if (externalInputs[identityFile] !== baselineInputs[identityFile]
+      && (externalInputs[identityFile] === null || !same(JSON.parse(externalInputs[identityFile]), identity))) {
+      fail('ledger-conflict', 'The external identity ledger differs from the proven current source correspondence.', identityFile);
+    }
+    return capture({ identity, projectedStructure: projectSource({ source, identity, sourceInputs: externalInputs }) });
+  }
+  function verifyProofs(mapping, inputs) {
+    if (!Array.isArray(mapping?.files) || !mapping.files.length) fail('proofs-invalid', 'Baseline source proofs are required.');
+    const seen = new Set();
+    for (const proof of mapping.files) {
+      if (!proof || typeof proof.file !== 'string' || seen.has(proof.file) || !Object.hasOwn(inputs, proof.file)
+        || proof.sha256 !== (inputs[proof.file] === null ? null : hash(inputs[proof.file]))) {
+        fail('proofs-invalid', 'Baseline proofs do not match the source bytes.', proof?.file);
+      }
+      seen.add(proof.file);
+    }
+    if (!seen.has(file) || !seen.has(identityFile)) fail('proofs-invalid', 'Source and identity proofs are both required.');
+  }
+  function verifyProjection(document, projection) {
+    for (const node of projection.nodes) {
+      const current = document.nodes[node.nodeId];
+      const parentId = node.nodeId === rootId ? definitionId : node.parentId;
+      if (!current || current.parentId !== parentId || !same(current.children, node.children) || !same(sourceLayout(current.layout), sourceLayout(node.layout))) {
+        fail('document-conflict', 'The reconciled source hierarchy differs from the edited document.');
+      }
+    }
+  }
+  async function reconcile(input, signal) {
+    try {
+      signal?.throwIfAborted();
+      const loadBaseline = input?.loadBaseline;
+      if (typeof loadBaseline !== 'function') fail('loader-invalid', 'A source baseline loader is required.');
+      const { target, baseline, document, baselineInputs, externalInputs, baselineIdentity } = capture({
+        target: input.target, baseline: input.baseline, document: input.document,
+        baselineInputs: input.baselineInputs, externalInputs: input.externalInputs,
+        ...(input.baselineIdentity === undefined ? {} : { baselineIdentity: input.baselineIdentity }),
+      });
+      if (target?.screenId !== screenId || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(target.sourceRevision ?? '')
+        || baseline?.document?.id !== documentId || document?.id !== documentId
+        || baseline.document.sourceRevision !== target.sourceRevision || document.sourceRevision !== target.sourceRevision
+        || !same(baseline.mapping?.target, target)) fail('target-conflict', 'Screen, document, and exact source revision must match.');
+      capturedInputs(baselineInputs); capturedInputs(externalInputs);
+      verifyProofs(baseline.mapping, baselineInputs);
+      const original = sourceIdentity(baselineInputs, baselineIdentity);
+      const latest = projectInputs({ baselineInputs, externalInputs, ...(baselineIdentity === undefined ? {} : { baselineIdentity }) });
+      const verifiedBaseline = capture(await loadBaseline(freeze({ target, sourceInputs: baselineInputs, projectedStructure: original.projectedStructure }), signal));
+      signal?.throwIfAborted();
+      if (!same(verifiedBaseline, baseline)) fail('baseline-conflict', 'The supplied baseline differs from the document projected from its source.');
+      const planned = compileDocumentSource({ target, before: baseline.document, after: document, mapping: baseline.mapping });
+      if (planned.status === 'blocked') return freeze({ status: 'conflict', diagnostics: planned.diagnostics });
+      const wrapper = original.wrapper;
+      const stylesheetFile = wrapper?.contract.stylesheet;
+      const reconciled = reconcileJsxStructurePlan({
+        file, baseline: { sourceRevision: target.sourceRevision, source: baselineInputs[file], identity: original.identity },
+        external: { sourceRevision: target.sourceRevision, source: externalInputs[file], sha256: hash(externalInputs[file]), identity: latest.identity },
+        operations: planned.operations, allowedFiles: wrapper ? [file, stylesheetFile] : [file],
+        ...(wrapper ? { wrapper: { contract: wrapper.contract, baselineSource: baselineInputs[stylesheetFile], externalSource: externalInputs[stylesheetFile], externalSha256: hash(externalInputs[stylesheetFile]) } } : {}),
+      });
+      if (reconciled.status === 'conflict') return reconciled;
+      const projection = reimportJsxStructureSource({ file, source: reconciled.source, identity: reconciled.identity,
+        ...(wrapper ? { wrapper: { contract: wrapper.contract, source: reconciled.stylesheetSource ?? externalInputs[stylesheetFile] } } : {}) });
+      verifyProjection(document, projection);
+      const current = capture(await loadBaseline(freeze({ target, sourceInputs: externalInputs, projectedStructure: latest.projectedStructure }), signal));
+      signal?.throwIfAborted();
+      verifyProofs(current.mapping, externalInputs);
+      if (!same(current.document, baseline.document)) fail('source-document-conflict', 'The current source projection changed the original document contract.');
+      const checked = compileDocumentSource({ target, before: current.document, after: document, mapping: current.mapping });
+      if (checked.status === 'blocked') return freeze({ status: 'conflict', diagnostics: checked.diagnostics });
+      signal?.throwIfAborted();
+      return freeze({ status: 'ready', baseline: JSON.parse(fingerprint(current)), document });
+    } catch (error) {
+      signal?.throwIfAborted();
+      return freeze({ status: 'conflict', diagnostics: error?.diagnostics ?? [{ code: 'source-reconcile-invalid', message: error instanceof Error ? error.message : String(error) }] });
+    }
+  }
+  return Object.freeze({ projectInputs, reconcile });
+}

package/node/preview-artifact-store.mjs

@@ -1230,7 +1230,6 @@ export function createPreviewArtifactStore({
   ) => {
     const manifest = await readManifest(namespace);
     let aggregate = null;
-    const contentFreshIds = new Set();
     const sourcePendingIds = new Set();
     if (manifest) {
       // Index once per read. The earlier path filtered the complete manifest for
@@ -1272,12 +1271,21 @@ export function createPreviewArtifactStore({
             artifact.frames[request.id]
           ) {
             const frame = artifact.frames[request.id];
+            const acceptedAsFresh = exactSet.has(entry);
             const withProvenance = {
               ...artifact,
               frames: {
                 ...artifact.frames,
                 [request.id]: {
                   ...frame,
+                  // A matching recipe plus unchanged observed source files is
+                  // a content proof for the requested fingerprint. Serve that
+                  // proof under the requested identity so browser bootstrap
+                  // reaches the same exact verdict as the manifest resolver.
+                  // The original capture revision remains truthful provenance.
+                  ...(acceptedAsFresh && request.fingerprint != null
+                    ? { fingerprint: request.fingerprint }
+                    : {}),
                   ...(entry.sourceRevision == null
                     ? {}
                     : { sourceRevision: entry.sourceRevision }),
@@ -1288,8 +1296,7 @@ export function createPreviewArtifactStore({
               aggregate,
               withProvenance,
             );
-            if (exactSet.has(entry)) {
-              contentFreshIds.add(request.id);
+            if (acceptedAsFresh) {
               sourcePendingIds.delete(request.id);
             }
             break;
@@ -1304,10 +1311,6 @@ export function createPreviewArtifactStore({
     );
     return {
       ...selection,
-      // The wire-level selector only knows fingerprints. A frame whose recipe
-      // and observed files were verified against the requested source context is
-      // also current, even when its coarse source fingerprint changed.
-      stale: selection.stale.filter((id) => !contentFreshIds.has(id)),
       ...(sourcePendingIds.size
         ? { sourcePending: [...sourcePendingIds] }
         : {}),