@pygmalionjs/pygmalion 0.9.0 → 0.11.0

package/dist-lib/testing.js

@@ -1,5 +1,5 @@
-import { bV as l, T as u } from "./runtime-Dxb-IaLN.js";
-import { bi as w, cb as y, cc as E, cd as P, be as T, as as V } from "./runtime-Dxb-IaLN.js";
+import { bW as l, T as u } from "./runtime-Bxn8116i.js";
+import { bi as y, cc as b, cd as E, ce as P, be as T, as as $ } from "./runtime-Bxn8116i.js";
 const v = {
   mirror: ["status", "refresh", "refs"],
   session: ["open", "check", "previewVisual", "applyVisual", "revertVisual"],
@@ -9,11 +9,11 @@ const v = {
   storyboard: ["environment", "sourceUsage", "componentBranches"]
 };
 function g(m = {}, t = {}) {
-  const n = [], d = t.origin ?? "", r = (e) => {
+  const n = [], d = t.origin ?? "", e = (r) => {
     var a;
     const i = {};
-    for (const o of v[e]) {
-      const s = `${e}.${String(o)}`, c = (a = m[e]) == null ? void 0 : a[o];
+    for (const o of v[r]) {
+      const s = `${r}.${String(o)}`, c = (a = m[r]) == null ? void 0 : a[o];
       i[String(o)] = (...p) => (n.push({ operation: s, request: p[0] }), c ? Promise.resolve(c(...p)) : Promise.reject(
         new u({
           operation: s,
@@ -27,21 +27,21 @@ function g(m = {}, t = {}) {
   return {
     calls: n,
     endpoints: l(t.endpoints),
-    resolveUrl: (e) => `${d}${e}`,
-    mirror: r("mirror"),
-    session: r("session"),
-    inspect: r("inspect"),
-    qa: r("qa"),
-    preview: r("preview"),
-    storyboard: r("storyboard")
+    resolveUrl: (r) => `${d}${r}`,
+    mirror: e("mirror"),
+    session: e("session"),
+    inspect: e("inspect"),
+    qa: e("qa"),
+    preview: e("preview"),
+    storyboard: e("storyboard")
   };
 }
 export {
-  w as EditorRuntimeProvider,
-  y as EditorStore,
+  y as EditorRuntimeProvider,
+  b as EditorStore,
   E as FrozenRoutePreviewView,
   P as NodeModel,
   T as createEditorRuntime,
   g as createMemoryTransport,
-  V as serializeNode
+  $ as serializeNode
 };

package/dist-lib/types/binding/duplicateMetadata.d.ts

@@ -0,0 +1,8 @@
+import type { DataCatalog } from './contracts.js';
+import type { DocumentDuplicateMetadataRemapper } from '../document/contracts.js';
+export interface DataBindingMetadataDuplicatorOptions {
+    /** Host-declared metadata containing no node references that require remapping. */
+    preservedMetadataKeys?: readonly string[];
+}
+/** Copies binding relationships while retaining only explicitly declared, reference-free metadata. */
+export declare function createDataBindingMetadataDuplicator(catalog: DataCatalog, options?: DataBindingMetadataDuplicatorOptions): DocumentDuplicateMetadataRemapper;

package/dist-lib/types/binding/index.d.ts

@@ -4,3 +4,4 @@ export * from './validate.js';
 export * from './preview.js';
 export * from './source.js';
 export * from './documentCommands.js';
+export * from './duplicateMetadata.js';

package/dist-lib/types/document/contracts.d.ts

@@ -158,6 +158,16 @@ export interface ResolvedDocumentNode {
 }
 /** Optional presentation-time instance resolution; normal editing uses canonical definitions. */
 export interface DocumentResolveOptions {
+    /**
+     * Expand a source occurrence before resolving its component subtree. The
+     * continuation retains inherited overrides and cycle checks, skips this
+     * occurrence's expansion hook, and accepts callback overrides for its subtree.
+     * A definition root is resolved through its instance, not expanded separately.
+     */
+    expandNode?: (input: {
+        node: DocumentNode;
+        instancePath: readonly string[];
+    }, resolve: (options?: DocumentResolveOptions) => ResolvedDocumentNode) => readonly ResolvedDocumentNode[];
     resolveInstance?: (input: {
         node: DocumentNode;
         /** Outer-to-inner instance IDs. IDs remain opaque, including slashes. */

package/dist-lib/types/document/prototype.d.ts

@@ -8,6 +8,8 @@
  * side effects a player must perform; time enters only through `now`.
  */
 import type { DesignDocument, DocumentDiagnostic, DocumentDuplicateMetadataRemapper, DocumentNode, DocumentResolveOptions, DocumentTransaction, ResolvedDocumentNode } from './contracts.js';
+import type { PrototypeOccurrence, PrototypeRowPath } from './prototypeOccurrence.js';
+export type { PrototypeOccurrence, PrototypeRowPath } from './prototypeOccurrence.js';
 export declare const PROTOTYPE_METADATA_KEY = "prototype";
 export declare const PROTOTYPE_INTERACTIONS_PROPERTY = "interactions";
 /** Upper bound for an authored transition in this player. */
@@ -252,14 +254,28 @@ export interface PrototypeSceneLayer {
     fill: string | null;
     node: DocumentNode;
     depth: number;
+    occurrence?: PrototypeOccurrence;
+}
+export interface PrototypeResolvedSceneNode extends Omit<ResolvedDocumentNode, 'children'> {
+    rowPath: PrototypeRowPath;
+    instancePath?: readonly string[];
+    children: PrototypeResolvedSceneNode[];
+}
+/** Supplies the same expanded scene used by the rendering surface, without owning authoring data. */
+export interface PrototypeRuntimeContext {
+    resolveScene(document: DesignDocument, state: PrototypeState, rootId: string, sceneId: string): PrototypeResolvedSceneNode;
 }
 /** Stable occurrence key. Every ID is opaque; nested instances never share canonical state. */
-export declare function prototypeVariantKey(instancePath: readonly string[]): string;
+export declare function prototypeVariantKey(instancePath: readonly string[], occurrence?: PrototypeOccurrence): string;
 /** Presentation-only variant resolution; neither the document nor shared definitions are changed. */
-export declare function prototypeResolveOptions(document: DesignDocument, variants: Readonly<Record<string, string>>): DocumentResolveOptions;
+export declare function prototypeResolveOptions(document: DesignDocument, variants: Readonly<Record<string, string>>, occurrence?: PrototypeOccurrence): DocumentResolveOptions;
 /** Resolves runtime variants explicitly; invalid choices never silently render canonical state. */
 export declare function resolvePrototypeScene(document: DesignDocument, rootId: string, variants?: Readonly<Record<string, string>>): ResolvedDocumentNode;
-export declare function prototypeSceneLayers(document: DesignDocument, rootId: string, variants?: Readonly<Record<string, string>>): PrototypeSceneLayer[];
+export declare function prototypeSceneLayers(document: DesignDocument, rootId: string, variants?: Readonly<Record<string, string>>, options?: {
+    state: PrototypeState;
+    sceneId?: string;
+    context?: PrototypeRuntimeContext;
+}): PrototypeSceneLayer[];
 export interface PrototypeSmartAnimatePair {
     name: string;
     from: PrototypeSceneLayer;
@@ -301,6 +317,7 @@ export type PrototypeRevert = {
 export interface PrototypeHold {
     nodeId: string;
     trigger: 'hover' | 'press';
+    occurrence?: PrototypeOccurrence;
     /** Screen-space bounds of the hotspot when the hold began; a surface keeps it hit-testable across navigation. */
     bounds: {
         sceneId: string;
@@ -327,7 +344,7 @@ export interface PrototypeState {
     history: string[];
     overlays: PrototypeOverlayState[];
     variables: Record<string, PrototypeValue>;
-    /** Runtime variant choices keyed by prototypeVariantKey(outer-to-inner instance path). */
+    /** Runtime variant choices keyed by the authored instance path and optional scene/row occurrence. */
     variants: Record<string, string>;
     scroll: Record<string, {
         x: number;
@@ -338,6 +355,7 @@ export interface PrototypeState {
         targetId: string;
         transition: PrototypeTransition;
         at: number;
+        occurrence?: PrototypeOccurrence;
     } | null;
     timers: PrototypeTimer[];
     holds: PrototypeHold[];
@@ -352,6 +370,7 @@ export type PrototypeEvent =
 {
     type: PrototypePointerEventType;
     path: readonly string[];
+    occurrence?: PrototypeOccurrence;
 } | {
     type: 'key';
     key: string;
@@ -397,6 +416,7 @@ export type PrototypeEffect = {
     sceneId: string;
     targetId: string;
     transition: PrototypeTransition;
+    occurrence?: PrototypeOccurrence;
 } | {
     type: 'open-url';
     url: string;
@@ -415,10 +435,11 @@ export interface PrototypeStartOptions {
     flowId?: string | null;
     startingNodeId?: string;
     now?: number;
+    context?: PrototypeRuntimeContext;
 }
 /** The initial state of a flow (or of an explicit starting screen); delay triggers on the screen are armed. */
 export declare function createPrototypeState(document: DesignDocument, options?: PrototypeStartOptions): PrototypeState;
 /** The earliest moment the state changes without input, or null when it is at rest. */
 export declare function prototypeNextDeadline(state: PrototypeState): number | null;
 /** One pure step: the event (or the passage of time) against a frozen document; time is `now`. */
-export declare function stepPrototype(document: DesignDocument, previous: PrototypeState, event: PrototypeEvent, now: number): PrototypeStepResult;
+export declare function stepPrototype(document: DesignDocument, previous: PrototypeState, event: PrototypeEvent, now: number, runtime?: PrototypeRuntimeContext): PrototypeStepResult;

package/dist-lib/types/document/prototypeOccurrence.d.ts

@@ -0,0 +1,18 @@
+/** A stable row address, ordered from the outer repeat to the inner repeat. */
+export type PrototypeRowPath = readonly {
+    repeatId: string;
+    key: string | number;
+}[];
+/** A rendered occurrence. Overlay scene IDs distinguish separate openings of one screen. */
+export interface PrototypeOccurrence {
+    sceneId: string;
+    rowPath: PrototypeRowPath;
+}
+export declare function prototypeOccurrenceValid(value: unknown): value is PrototypeOccurrence;
+export declare function prototypeRowPathPrefix(prefix: PrototypeRowPath, path: PrototypeRowPath): boolean;
+export declare function prototypeOccurrenceEqual(left: PrototypeOccurrence | undefined, right: PrototypeOccurrence | undefined): boolean;
+export declare function encodePrototypeVariantKey(instancePath: readonly string[], occurrence?: PrototypeOccurrence): string;
+export declare function decodePrototypeVariantKey(key: string): {
+    instancePath: string[];
+    occurrence?: PrototypeOccurrence;
+} | null;

package/dist-lib/types/lib.d.ts

@@ -10,6 +10,8 @@ export type { StylesPanelProps } from './workspace/edit/StylesPanel.js';
 export { TokenLibraryProvider, useTokenLibraryController, useHasTokenLibraryProvider } from './workspace/tokens/TokenLibraryContext.js';
 export { createTokenLibraryEngine, reopenTokenLibrary, validateTokenLibraryDocument, resolveTokenLibraryValue, tokenValueEditability, TokenLibraryValidationError } from './token-library/engine.js';
 export type * from './token-library/contracts.js';
+export { createTokenValueResolver } from './token-library/valueResolver.js';
+export type { TokenValueReferenceRange, TokenValueResolverOptions, ResolvedTokenText } from './token-library/valueResolver.js';
 export type * from './workspace/tokens/contracts.js';
 export { WorkspaceTokenLibraryController } from './workspace/tokens/controller.js';
 export type { WorkspaceTokenLibraryState } from './workspace/tokens/controller.js';
@@ -27,8 +29,8 @@ export type { InspectSourceRuntime, SourceWritePolicy, SourceWriteErrorCode } fr
 export { WorkspaceController } from './workspace/controller.js';
 export { createLegacyModeAdapter } from './workspace/legacyModeAdapter.js';
 export type * from './workspace/contracts.js';
-export { resolveWorkspaceTarget } from './workspace/configuration.js';
-export type { WorkspaceConfiguration, WorkspaceTargetConfiguration } from './workspace/configuration.js';
+export { createWorkspaceTargetResolver, resolveWorkspaceTarget } from './workspace/configuration.js';
+export type { WorkspaceConfiguration, WorkspaceTargetConfiguration, WorkspaceTargetResolverOptions } from './workspace/configuration.js';
 export { compileWorkspaceVisualSource, workspaceSourceFingerprint } from './workspace/source/compiler.js';
 export { compileWorkspaceDocumentSource, jsxStructureWrapperClassName } from './workspace/source/structure.js';
 export { compileWorkspaceResponsiveSource, resolveResponsiveLayout, setResponsiveLayoutOverride } from './workspace/source/responsive.js';
@@ -422,3 +424,5 @@ export { PrototypePanel } from './workspace/edit/PrototypePanel.js';
 export { PrototypePlayer } from './workspace/view/PrototypePlayer.js';
 export type { PrototypePlayerProps } from './workspace/view/PrototypePlayer.js';
 export * from './workspace/view/prototypePlayback.js';
+export { createPrototypeProjectionContext } from './workspace/edit/prototypeProjection.js';
+export type { PrototypeProjectionContext } from './workspace/edit/prototypeProjection.js';

package/dist-lib/types/token-library/valueResolver.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedTokenReference, TokenLibraryDiagnostic, TokenLibraryDocument, TokenValueResolution } from './contracts.js';
+export interface TokenValueReferenceRange {
+    start: number;
+    end: number;
+    /** Must be one of the resolution's declared references. */
+    reference: ResolvedTokenReference;
+}
+export interface TokenValueResolverOptions {
+    /** Extend a reference's replacement range to host-owned surrounding syntax, such as a function call. */
+    referenceRanges?(resolution: TokenValueResolution): readonly TokenValueReferenceRange[];
+}
+export interface ResolvedTokenText {
+    status: 'resolved' | 'blocked';
+    text?: string;
+    resolution?: TokenValueResolution;
+    diagnostics: readonly TokenLibraryDiagnostic[];
+}
+/** Resolves a captured library's declared reference graph and caches text by token and requested mode. */
+export declare function createTokenValueResolver(input: TokenLibraryDocument, options?: TokenValueResolverOptions): (tokenId: string, modeId: string) => ResolvedTokenText;

package/dist-lib/types/workspace/configuration.d.ts

@@ -33,6 +33,14 @@ export interface WorkspaceConfiguration extends WorkspaceTargetConfiguration {
     /** Undefined explicitly marks an unsupported screen or source revision. */
     resolveTarget?(target: WorkspaceTarget): WorkspaceTargetConfiguration | undefined;
 }
+export interface WorkspaceTargetResolverOptions {
+    /** The host decides whether this screen and revision have usable capabilities. */
+    resolve(target: Readonly<WorkspaceTarget>): WorkspaceTargetConfiguration | undefined;
+    /** Maximum retained target configurations; zero disables caching. Default: 8. */
+    maxEntries?: number;
+}
+/** Retain capability identities per screen and revision; unsupported targets remain retryable. */
+export declare function createWorkspaceTargetResolver({ resolve, maxEntries }: WorkspaceTargetResolverOptions): (target: WorkspaceTarget) => WorkspaceTargetConfiguration | undefined;
 /** An explicit target resolver never inherits capabilities from the root configuration. */
 export declare function resolveWorkspaceTarget(configuration: WorkspaceConfiguration, target: WorkspaceTarget): WorkspaceTargetConfiguration | undefined;
 /** Compares captured capability identities without invoking any host callbacks. */

package/dist-lib/types/workspace/edit/projection.d.ts

@@ -9,4 +9,4 @@ export interface ProjectedDocumentNode {
     children: ProjectedDocumentNode[];
 }
 /** Fixture rows affect this disposable scene only, never canonical document geometry. */
-export declare function projectDocumentScene(document: DesignDocument, data: DataProjection | null, resolveOptions?: DocumentResolveOptions): ProjectedDocumentNode;
+export declare function projectDocumentScene(document: DesignDocument, data: DataProjection | null, resolveOptions?: DocumentResolveOptions, resolveRowOptions?: (rowPath: BindingRuntimeScope['rowPath']) => DocumentResolveOptions): ProjectedDocumentNode;

package/dist-lib/types/workspace/edit/prototypeProjection.d.ts

@@ -0,0 +1,7 @@
+import type { DataProjection } from '../../binding/preview.js';
+import type { PrototypeRuntimeContext } from '../../document/prototype.js';
+export interface PrototypeProjectionContext extends PrototypeRuntimeContext {
+    readonly projection: DataProjection | null;
+}
+/** One captured data projection supplies runtime hit testing, layout and presentation rendering. */
+export declare function createPrototypeProjectionContext(data: DataProjection | null): PrototypeProjectionContext;

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

@@ -1,16 +1,17 @@
 import type { ReactNode } from 'react';
 import type { DesignDocument } from '../../document/contracts.js';
-import { type PrototypeState } from '../../document/prototype.js';
+import { type PrototypeRuntimeContext, 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): {
+    renderScene(rootId: string, state: PrototypeState, sceneId?: string): ReactNode;
+    sceneSize?(rootId: string, state: PrototypeState, sceneId?: string): {
         width: number;
         height: number;
     } | undefined;
+    context?: PrototypeRuntimeContext;
     onClose(): void;
     clock?: PrototypeClock;
 }

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

@@ -1,5 +1,5 @@
 import type { DesignDocument, DocumentNode, ResolvedDocumentNode } from '../../document/contracts.js';
-import { type PrototypeEffect, type PrototypeEvent, type PrototypeStartOptions, type PrototypeState } from '../../document/prototype.js';
+import { type PrototypeEffect, type PrototypeEvent, type PrototypeRuntimeContext, type PrototypeStartOptions, type PrototypeState } from '../../document/prototype.js';
 export interface PrototypeClock {
     now(): number;
     schedule(callback: () => void, delayMs: number): unknown;
@@ -38,7 +38,7 @@ export interface PrototypePresentationScene {
         opacity: number;
     } | null;
 }
-export declare function prototypeScene(document: DesignDocument, state: PrototypeState): PrototypePresentationScene[];
+export declare function prototypeScene(document: DesignDocument, state: PrototypeState, context?: PrototypeRuntimeContext): PrototypePresentationScene[];
 export declare function prototypeFlowOptions(document: DesignDocument): {
     id: string;
     label: string;

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/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/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/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 });
+}