@pygmalionjs/pygmalion 0.9.0 → 0.11.0

package/node/workspace-draft-process.mjs

@@ -0,0 +1,129 @@
+import { execFile, spawn } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+
+function signalGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+async function hasRunningGroup(pid) {
+  if (!signalGroup(pid, 0)) return false;
+  let stdout;
+  try {
+    ({ stdout } = await execute('ps', ['-ax', '-o', 'pgid=,stat='], { timeout: 5_000 }));
+  } catch {
+    if (process.platform === 'linux') {
+      try {
+        for (const entry of await readdir('/proc')) {
+          if (!/^\d+$/.test(entry)) continue;
+          const stat = await readFile(`/proc/${entry}/stat`, 'utf8').catch(error => {
+            if (error.code === 'ENOENT' || error.code === 'ESRCH') return '';
+            throw error;
+          });
+          // Parenthesized command names may contain spaces and closing parentheses.
+          const [state, , group] = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
+          if (Number(group) === pid && state !== 'Z') return true;
+        }
+        return false;
+      } catch { /* Keep the process group alive until its state can be determined. */ }
+    }
+    // An unavailable inspector cannot authorize cleanup while descendants remain.
+    return signalGroup(pid, 0);
+  }
+  return stdout.split('\n').some(line => {
+    const [group, status] = line.trim().split(/\s+/);
+    // Reaping belongs to the operating system; zombies cannot write source files.
+    return Number(group) === pid && status && !status.startsWith('Z');
+  });
+}
+
+async function terminateGroup(pid, graceMs) {
+  if (!pid || !signalGroup(pid, 'SIGTERM')) return;
+  const deadline = Date.now() + graceMs;
+  while (await hasRunningGroup(pid)) {
+    if (Date.now() >= deadline) signalGroup(pid, 'SIGKILL');
+    await delay(25);
+  }
+}
+
+/** Resolve or reject only after the command and its process group stop writing. */
+export async function executeWorkspaceDraftProcess(command, args, {
+  signal, timeout = 240_000, terminationGraceMs = 1_000, maxBuffer = 8 * 1024 * 1024, ...options
+} = {}) {
+  signal?.throwIfAborted();
+  if (process.platform === 'win32') {
+    throw new Error('Draft process group cleanup supports macOS and Linux.');
+  }
+  if (!Number.isFinite(timeout) || timeout < 0 || timeout > 2 ** 31 - 1
+    || !Number.isFinite(terminationGraceMs) || terminationGraceMs < 0
+    || !Number.isSafeInteger(maxBuffer) || maxBuffer < 0) {
+    throw new TypeError('Process timeout, termination grace, and output limits must be finite non-negative values.');
+  }
+  let child;
+  let termination;
+  let cancellation;
+  let cancelled = false;
+  let timeoutHandle;
+  const terminate = () => {
+    termination ??= terminateGroup(child?.pid, terminationGraceMs);
+    // Observe termination failure while the process close event is still pending.
+    void termination.catch(() => {});
+    return termination;
+  };
+  const cancel = reason => {
+    if (!cancelled) { cancelled = true; cancellation = reason; }
+    void terminate();
+  };
+  const onAbort = () => cancel(signal.reason ?? new DOMException('Draft execution cancelled.', 'AbortError'));
+  const closed = new Promise(resolve => {
+    // spawn owns the detached process group; execFile does not forward detached.
+    child = spawn(command, args, { ...options, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = []; const stderr = [];
+    let stdoutSize = 0; let stderrSize = 0; let spawnError;
+    const append = (chunks, chunk, size) => {
+      if (size > maxBuffer) {
+        const error = Object.assign(new Error('Draft process output exceeded its byte limit.'), {
+          code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+        });
+        cancel(error);
+      } else chunks.push(chunk);
+    };
+    child.stdout.on('data', chunk => { stdoutSize += chunk.length; append(stdout, chunk, stdoutSize); });
+    child.stderr.on('data', chunk => { stderrSize += chunk.length; append(stderr, chunk, stderrSize); });
+    child.once('error', error => { spawnError = error; });
+    child.once('close', (code, exitSignal) => {
+      const out = Buffer.concat(stdout).toString(); const err = Buffer.concat(stderr).toString();
+      const error = spawnError ?? (code === 0 ? undefined : Object.assign(
+        new Error(`Draft process failed (${exitSignal ?? code}).${err ? `\n${err}` : ''}`),
+        { code, signal: exitSignal, stdout: out, stderr: err },
+      ));
+      resolve({ error, stdout: out, stderr: err });
+    });
+    // Successful or failed leaders may leave descendants behind as well.
+    child.once('exit', terminate);
+  });
+  signal?.addEventListener('abort', onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+  if (timeout > 0) {
+    timeoutHandle = setTimeout(() => cancel(new DOMException('Draft execution timed out.', 'TimeoutError')), timeout);
+  }
+  try {
+    const result = await closed;
+    await terminate();
+    if (cancelled) throw cancellation;
+    if (result.error) throw result.error;
+    return { stdout: result.stdout, stderr: result.stderr };
+  } finally {
+    clearTimeout(timeoutHandle);
+    signal?.removeEventListener('abort', onAbort);
+  }
+}

package/node/workspace-draft-runtime.mjs

@@ -0,0 +1,67 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const WORKSPACE_DRAFT_TEMP_PREFIX = 'pygmalion-draft-preview-';
+export const WORKSPACE_DRAFT_OUTPUT_DIRECTORY = 'output';
+
+function relative(value) {
+  return typeof value === 'string' && value.length > 0 && !path.isAbsolute(value)
+    && !/^[a-z]:/i.test(value) && !/[\\\x00-\x1f\x7f?#]/.test(value)
+    && value.split('/').every(part => part && part !== '.' && part !== '..' && part !== '.git');
+}
+
+/** Own CLI cancellation listeners without exiting ahead of an active child process. */
+export function createWorkspaceDraftLifecycle() {
+  const controller = new AbortController();
+  const listeners = new Map();
+  for (const [name, exitCode] of [['SIGTERM', 143], ['SIGINT', 130]]) {
+    const listener = () => {
+      if (controller.signal.aborted) return;
+      process.exitCode = exitCode;
+      controller.abort(new DOMException('Draft execution cancelled.', 'AbortError'));
+    };
+    listeners.set(name, listener);
+    process.on(name, listener);
+  }
+  return Object.freeze({
+    signal: controller.signal,
+    dispose() { for (const [name, listener] of listeners) process.removeListener(name, listener); listeners.clear(); },
+  });
+}
+
+/** Verify that source and output belong to one SDK-created temporary layout. */
+export async function assertWorkspaceDraftDirectories({ appRoot, outputDirectory, appDirectory = '.' }) {
+  if (appDirectory !== '.' && !relative(appDirectory)) throw new TypeError('The draft application directory must be project-relative.');
+  const isolatedRoot = await realpath(appRoot);
+  const outputRoot = await realpath(outputDirectory);
+  const temporaryRoot = path.dirname(outputRoot);
+  const systemTemporary = await realpath(os.tmpdir());
+  if (path.dirname(temporaryRoot) !== systemTemporary || !path.basename(temporaryRoot).startsWith(WORKSPACE_DRAFT_TEMP_PREFIX)
+    || isolatedRoot !== path.join(temporaryRoot, 'source', appDirectory)
+    || path.basename(outputRoot) !== WORKSPACE_DRAFT_OUTPUT_DIRECTORY
+    || !(await stat(isolatedRoot)).isDirectory() || !(await stat(outputRoot)).isDirectory()) {
+    throw new Error('Draft compilation requires source and output directories from one isolated SDK preview.');
+  }
+  return Object.freeze({ appRoot: isolatedRoot, outputDirectory: outputRoot, temporaryRoot });
+}
+
+/** Import the explicit root ESM entry from this install, without falling back to the caller's dependencies. */
+export async function importIsolatedPackage({ appRoot, name }) {
+  if (typeof name !== 'string' || !/^(?:@[a-zA-Z0-9][\w.-]*\/)?[a-zA-Z0-9][\w.-]*$/.test(name)) {
+    throw new TypeError('An isolated package requires a complete package name.');
+  }
+  const directory = await realpath(path.join(appRoot, 'node_modules', name));
+  const metadata = JSON.parse(await readFile(path.join(directory, 'package.json'), 'utf8'));
+  const entry = metadata.exports?.['.']?.import;
+  if (typeof entry !== 'string' || !entry.startsWith('./') || !relative(entry.slice(2))) {
+    throw new Error(`The isolated package must declare a relative root import export: ${name}`);
+  }
+  const resolved = await realpath(path.join(directory, entry));
+  const local = path.relative(directory, resolved);
+  if (!relative(local) || !(await stat(resolved)).isFile()) {
+    throw new Error(`The isolated package entry must remain inside its package directory: ${name}`);
+  }
+  return import(pathToFileURL(resolved).href);
+}

package/node/workspace-source-session.mjs

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { workspaceSourceFingerprint as fingerprint } from './workspace-source-identity.mjs';
+import { applySourceFilePlan, previewSourceFilePlan } from './source-file-plan.mjs';
+import { createWorkspaceSourcePlanService } from './workspace-source-plan.mjs';
+import { readSourceInputs } from './source-service-inputs.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const same = (left, right) => fingerprint(left) === fingerprint(right);
+function capture(value) {
+  const freeze = item => { if (item && typeof item === 'object') { Object.values(item).forEach(freeze); Object.freeze(item); } return item; };
+  return freeze(JSON.parse(fingerprint(value)));
+}
+const baselineKey = (target, baseline) => fingerprint([target, fingerprint(baseline.document), fingerprint(baseline.mapping)]);
+
+/** Retain server proofs across external edits while keeping projection and compilation host-defined. */
+export function createWorkspaceSourceSession({
+  appRoot, allowedFiles, overlayFiles = allowedFiles, optionalFiles = [], inputFiles,
+  loadCodec, assertTarget: validateTarget, archive, currentRevision, projectBaseline,
+  compilePlan, previewPlan = previewSourceFilePlan, applyPlan = applySourceFilePlan,
+  reconcile, projectReconcileInputs, applyMessage = 'The reviewed source changes were applied.',
+}) {
+  if (![inputFiles, loadCodec, validateTarget, archive, currentRevision, projectBaseline, compilePlan, reconcile, projectReconcileInputs].every(callback => typeof callback === 'function')) {
+    throw new Error('A source session requires explicit projection, compilation, reconciliation, revision, and archive callbacks.');
+  }
+  const readInputs = (root, files, signal) => readSourceInputs(root, files, { optionalFiles, signal });
+  const baselines = new Map();
+  const working = new Map();
+  const operations = new Set();
+  let disposed = false; let busy; let archiveService;
+  const check = signal => { signal.throwIfAborted(); if (disposed) throw new Error('The source service has been disposed.'); };
+  const retain = (map, key, value) => {
+    map.delete(key); map.set(key, { ...value, createdAt: Date.now() });
+    while (map.size > 8) { const oldest = map.keys().next().value; map.get(oldest).service?.dispose(); map.delete(oldest); }
+  };
+  const lookup = (map, key) => {
+    const value = map.get(key);
+    const now = Date.now();
+    if (value && (now < value.createdAt || now - value.createdAt >= 30 * 60_000)) { value.service?.dispose(); map.delete(key); return undefined; }
+    return value;
+  };
+  const run = async (signal, operation) => {
+    if (disposed) throw new Error('The source service has been disposed.');
+    signal?.throwIfAborted();
+
+    while (busy?.controller.signal.aborted) {
+      await busy.settled; signal?.throwIfAborted();
+      if (disposed) throw new Error('The source service has been disposed.');
+    }
+    if (busy) throw new Error('Another source review is in progress.');
+    const controller = new AbortController();
+    let finish;
+    const settled = new Promise(resolve => { finish = resolve; });
+    const slot = { controller, settled }; busy = slot; operations.add(controller);
+    const abort = () => controller.abort(signal.reason);
+    signal?.addEventListener('abort', abort, { once: true });
+    try { const result = await operation(controller.signal); check(controller.signal); return result; }
+    finally { signal?.removeEventListener('abort', abort); operations.delete(controller); if (busy === slot) busy = undefined; finish(); }
+  };
+  const assertTarget = async (target, signal) => {
+    check(signal);
+    if (!target || typeof target.screenId !== 'string' || !/^[a-f0-9]{40}$/.test(target.sourceRevision ?? '')) throw new Error('An exact source target is required.');
+    await validateTarget(target, signal); check(signal);
+  };
+  const assertHead = async (target, signal) => {
+    check(signal);
+    if (await currentRevision() !== target.sourceRevision) throw new Error('The working source revision differs from the selected revision.');
+    check(signal);
+  };
+  const fromInputs = async (codec, target, sourceInputs, projectedStructure, signal) => {
+    const result = await projectBaseline({ codec, target, sourceInputs, projectedStructure }, signal);
+    check(signal); return capture(result);
+  };
+  const currentInputs = async (context, signal) => {
+    await assertHead(context.target, signal);
+    const actual = await readInputs(appRoot, Object.keys(context.inputs), signal);
+    await assertHead(context.target, signal);
+    if (!same(actual, context.inputs)) throw new Error('Working inputs changed after reconciliation. Review the source again.');
+  };
+
+  const overlay = async (context, root, signal) => {
+    if (await realpath(root) === await realpath(appRoot)) throw new Error('Reconciled inputs require an isolated source root.');
+    const original = await readInputs(root, Object.keys(context.archiveInputs), signal);
+    if (!same(original, context.archiveInputs)) throw new Error('The isolated archive differs from the retained source proof.');
+    const changes = Object.keys(original).filter(file => original[file] !== context.inputs[file]).map(file => {
+      if (context.inputs[file] === null) throw new Error('Reconciliation cannot delete a source input.');
+      return { file, beforeSha256: original[file] === null ? null : hash(original[file]), content: context.inputs[file] };
+    });
+    if (changes.length) await applySourceFilePlan(root, { version: 1, sourceRevision: context.target.sourceRevision,
+      proofs: Object.entries(original).map(([file, source]) => ({ file, sha256: source === null ? null : hash(source) })), changes,
+    }, { sourceRevision: context.target.sourceRevision, allowedFiles: overlayFiles, signal });
+    check(signal);
+    if (!same(await readInputs(root, Object.keys(context.inputs), signal), context.inputs)) throw new Error('The isolated inputs differ from the reconciled baseline.');
+  };
+  const isolated = (target, context, signal, operation) => archive(target.sourceRevision, signal, async ({ appRoot: root }) => {
+    if (context) await overlay(context, root, signal);
+    check(signal); return operation(root);
+  });
+  const clearOtherReviews = active => {
+    if (active !== archiveService) { archiveService.dispose(); archiveService = makeService(); }
+    for (const [key, context] of working) if (context.service !== active) { context.service.dispose(); working.delete(key); }
+  };
+  function makeService(context) {
+    const service = createWorkspaceSourcePlanService({
+      async assertTarget(target, signal) { await assertTarget(target, signal); if (context) await currentInputs(context, signal); },
+      async loadBaseline(target, signal) {
+        if (context) return context.baseline;
+        const codec = await loadCodec(); check(signal);
+        return isolated(target, null, signal, async root => {
+          const inputs = capture(await readInputs(root, inputFiles(codec), signal));
+          const baseline = await fromInputs(codec, target, inputs, undefined, signal);
+          retain(baselines, baselineKey(target, baseline), { target: capture(target), baseline, inputs, codec });
+          return baseline;
+        });
+      },
+      compilePlan({ target, baseline, document }, signal) {
+        return isolated(target, context, signal, root => compilePlan({ appRoot: root, sourceRevision: target.sourceRevision,
+          before: baseline.document, after: document, mapping: baseline.mapping, signal, ...(context ? { reconciledIdentity: context.identity } : {}) }));
+      },
+      previewPlan(plan, target, signal) {
+        return isolated(target, context, signal, root => previewPlan(root, plan, { sourceRevision: target.sourceRevision, allowedFiles, signal }));
+      },
+      async applyPlan(plan, target, signal) {
+        await assertHead(target, signal); clearOtherReviews(service);
+        const result = await applyPlan(appRoot, plan, { sourceRevision: target.sourceRevision, allowedFiles, signal });
+        return { applied: result.applied, message: applyMessage };
+      },
+    });
+    return service;
+  }
+  archiveService = makeService();
+  const forBaseline = input => lookup(working, baselineKey(input.target, input.baseline));
+  const forRequest = request => lookup(working, fingerprint([request.target, request.identity?.beforeFingerprint ?? '', request.identity?.mappingFingerprint ?? '']));
+  return Object.freeze({
+    load(input, signal) { const target = capture(input); return run(signal, current => archiveService.load(target, current)); },
+    compile(input, signal) { const request = capture(input); return run(signal, current => (forBaseline(request)?.service ?? archiveService).compile(request, current)); },
+    preview(input, signal) { const request = capture(input); return run(signal, current => (forRequest(request)?.service ?? archiveService).preview(request, current)); },
+    apply(input, signal) { const request = capture(input); return run(signal, current => (forRequest(request)?.service ?? archiveService).apply(request, current)); },
+    validatePreviewRequest(input, signal) { const request = capture(input); return run(signal, current => (forRequest(request)?.service ?? archiveService).validatePreviewRequest(request, current)); },
+    preparePreviewSource(input, root, signal) {
+      const request = capture(input);
+      return run(signal, async current => {
+        const context = forRequest(request);
+        await (context?.service ?? archiveService).validatePreviewRequest(request, current);
+        if (context) await overlay(context, root, current);
+      });
+    },
+    reconcile(input, signal) {
+      if (!input || typeof input !== 'object' || Object.keys(input).some(key => !['target', 'baseline', 'document'].includes(key))) {
+        throw new Error('Reconciliation accepts only a target, baseline, and document.');
+      }
+      const request = capture(input);
+      return run(signal, async current => {
+        await assertTarget(request.target, current); await assertHead(request.target, current);
+        const key = baselineKey(request.target, request.baseline);
+        const origin = lookup(baselines, key) ?? lookup(working, key);
+        if (!origin) throw new Error('The retained source baseline is unavailable. Load it again.');
+        const externalInputs = capture(await readInputs(appRoot, Object.keys(origin.inputs), current));
+        await assertHead(request.target, current);
+        const loadBaseline = ({ target, sourceInputs, projectedStructure }, operationSignal) => fromInputs(origin.codec, target, sourceInputs, projectedStructure, operationSignal);
+        const result = capture(await reconcile({ ...request, baselineInputs: origin.inputs, externalInputs, loadBaseline,
+          ...(origin.identity ? { baselineIdentity: origin.identity } : {}) }, current));
+        check(current);
+        if (result.status !== 'ready') return result;
+        const projected = projectReconcileInputs({ baselineInputs: origin.inputs, externalInputs,
+          ...(origin.identity ? { baselineIdentity: origin.identity } : {}) });
+        const baseline = await fromInputs(origin.codec, request.target, externalInputs, projected.projectedStructure, current);
+        if (!same(result.baseline, baseline) || !same(result.document, request.document)) throw new Error('The reconciled result differs from the verified baseline or complete document.');
+        const nextKey = baselineKey(request.target, baseline);
+        if (nextKey !== key) {
+          const context = { target: request.target, baseline, inputs: externalInputs, archiveInputs: origin.archiveInputs ?? origin.inputs, codec: origin.codec, identity: projected.identity };
+          await currentInputs(context, current);
+          context.service = makeService(context);
+          lookup(working, nextKey)?.service.dispose(); retain(working, nextKey, context);
+        }
+        return result;
+      });
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const controller of operations) controller.abort(new Error('The source service has been disposed.'));
+      archiveService.dispose(); for (const context of working.values()) context.service.dispose();
+      working.clear(); baselines.clear();
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {
@@ -72,6 +72,26 @@
     "./source-responsive": {
       "types": "./source-responsive.d.ts",
       "default": "./node/source-responsive.mjs"
+    },
+    "./host-runtime": {
+      "types": "./host-runtime.d.ts",
+      "default": "./node/host-runtime.mjs"
+    },
+    "./source-service": {
+      "types": "./source-service.d.ts",
+      "default": "./node/source-service.mjs"
+    },
+    "./draft-entry": {
+      "types": "./workspace-draft-entry.d.ts",
+      "default": "./node/workspace-draft-entry.mjs"
+    },
+    "./source-module": {
+      "types": "./source-module.d.ts",
+      "default": "./node/source-module.mjs"
+    },
+    "./source-reconciler": {
+      "types": "./jsx-source-reconciler.d.ts",
+      "default": "./node/jsx-source-reconciler.mjs"
     }
   },
   "files": [
@@ -138,7 +158,25 @@
     "node/source-responsive.mjs",
     "source-responsive.d.ts",
     "node/source-responsive-codec.mjs",
-    "node/source-responsive-codec.d.mts"
+    "node/source-responsive-codec.d.mts",
+    "host-runtime.d.ts",
+    "node/host-runtime.mjs",
+    "source-service.d.ts",
+    "node/source-service.mjs",
+    "workspace-draft-entry.d.ts",
+    "node/workspace-draft-entry.mjs",
+    "source-module.d.ts",
+    "node/source-module.mjs",
+    "node/workspace-draft-process.mjs",
+    "node/revision-catalog-resolver.mjs",
+    "node/source-archive-runtime.mjs",
+    "node/source-service-inputs.mjs",
+    "node/source-service-plugin.mjs",
+    "node/workspace-source-session.mjs",
+    "node/token-source-service.mjs",
+    "jsx-source-reconciler.d.ts",
+    "node/jsx-source-reconciler.mjs",
+    "node/workspace-draft-runtime.mjs"
   ],
   "scripts": {
     "dev": "vite",

package/source-module.d.ts

@@ -0,0 +1,16 @@
+export interface SourceModuleBuildResult {
+  outputFiles?: readonly { text: string }[];
+}
+
+export interface BundledSourceModuleOptions {
+  /** A trusted bundler supplied by the consuming build tool. */
+  build(options: Record<string, unknown>): Promise<SourceModuleBuildResult>;
+  /** Application aliases, plugins, dependency paths, loaders, and entry declaration. */
+  buildOptions: Record<string, unknown>;
+  /** Absolute logical filename used by CommonJS resolution; no output file is written. */
+  filename: string;
+  require?: (id: string) => unknown;
+}
+
+/** Executes trusted source code in the current process. This is not an execution sandbox. */
+export declare function evaluateBundledSourceModule<T = unknown>(options: BundledSourceModuleOptions): Promise<T>;

package/source-service.d.ts

@@ -0,0 +1,92 @@
+import type { Plugin, ViteDevServer } from 'vite';
+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, WorkspaceSourceReconcileInput, WorkspaceSourceReconcileResult } from './dist-lib/types/workspace/source/flowContracts.js';
+import type { WorkspaceTokenLibraryBaseline, WorkspaceTokenSourceRequest } from './dist-lib/types/workspace/tokens/contracts.js';
+import type { TokenLibraryDocument } from './dist-lib/types/token-library/contracts.js';
+import type { SourceFilePlanOptions } from './source-files.js';
+import type { WorkspaceSourcePlanService } from './workspace-source-plan.js';
+
+export type SourceInputs = Readonly<Record<string, string | null>>;
+export type SourceArchive = <T>(sourceRevision: string, signal: AbortSignal,
+  operation: (context: { appRoot: string; sourceRevision?: string; signal?: AbortSignal }) => Promise<T>) => Promise<T>;
+export interface SourceInputOptions { optionalFiles?: readonly string[]; signal?: AbortSignal; maxBytes?: number }
+export declare function assertSourceInputParent(root: string, file: string): Promise<void>;
+export declare function readSourceInputs(appRoot: string, files: readonly string[], options?: SourceInputOptions): Promise<Record<string, string | null>>;
+export declare function readProvenSourceFiles(appRoot: string, proofs: SourceFilePlan['proofs'], options?: SourceInputOptions): Promise<Map<string, { file: string; sha256: string | null; source: string | null }>>;
+export declare function withSourceFiles<T>(options: { files: Map<string, string>; signal?: AbortSignal }, operation: (root: string) => Promise<T>): Promise<T>;
+
+interface SourceWriters {
+  previewPlan?(root: string, plan: SourceFilePlan, options: SourceFilePlanOptions): Promise<Pick<InspectPreviewResult, 'files' | 'affectedFiles'>>;
+  applyPlan?(root: string, plan: SourceFilePlan, options: SourceFilePlanOptions): Promise<{ applied: number }>;
+}
+export interface WorkspaceSourceSessionOptions<Codec, Projection = unknown, Identity = unknown> extends SourceWriters {
+  appRoot: string;
+  allowedFiles: readonly string[];
+  overlayFiles?: readonly string[];
+  optionalFiles?: readonly string[];
+  inputFiles(codec: Codec): readonly string[];
+  loadCodec(): Promise<Codec>;
+  assertTarget(target: WorkspaceTarget, signal: AbortSignal): void | Promise<void>;
+  archive: SourceArchive;
+  currentRevision(): Promise<string>;
+  projectBaseline(input: { codec: Codec; target: WorkspaceTarget; sourceInputs: SourceInputs; projectedStructure?: Projection }, signal: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  compilePlan(input: { appRoot: string; sourceRevision: string; before: DesignDocument; after: DesignDocument; mapping: WorkspaceSourceBaseline['mapping']; signal: AbortSignal; reconciledIdentity?: Identity }): Promise<SourceFilePlan>;
+  reconcile(input: WorkspaceSourceReconcileInput & {
+    baselineInputs: SourceInputs; externalInputs: SourceInputs; baselineIdentity?: Identity;
+    loadBaseline(input: { target: WorkspaceTarget; sourceInputs: SourceInputs; projectedStructure?: Projection }, signal: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  }, signal: AbortSignal): Promise<WorkspaceSourceReconcileResult>;
+  projectReconcileInputs(input: { baselineInputs: SourceInputs; externalInputs: SourceInputs; baselineIdentity?: Identity }): { projectedStructure: Projection; identity: Identity };
+  applyMessage?: string;
+}
+export interface WorkspaceSourceSession extends WorkspaceSourcePlanService {
+  reconcile(input: WorkspaceSourceReconcileInput, signal?: AbortSignal): Promise<WorkspaceSourceReconcileResult>;
+  /** Validates the retained review before overlaying reconciled bytes into an isolated root. */
+  preparePreviewSource(input: WorkspaceFileSourceRequest, root: string, signal?: AbortSignal): Promise<void>;
+}
+export declare function createWorkspaceSourceSession<Codec, Projection = unknown, Identity = unknown>(options: WorkspaceSourceSessionOptions<Codec, Projection, Identity>): WorkspaceSourceSession;
+
+export interface LoadedTokenSource<SourceFiles = unknown, Ledger = unknown> extends WorkspaceTokenLibraryBaseline {
+  sourceFiles: SourceFiles;
+  ledger: Ledger;
+  consumerFiles: readonly string[];
+}
+export interface TokenSourceServiceOptions<Codec, SourceFiles = unknown, Ledger = unknown> extends SourceWriters {
+  appRoot: string;
+  loadCodec(): Promise<Codec>;
+  assertRevision(sourceRevision: string, signal?: AbortSignal): void | Promise<void>;
+  assertTarget(target: WorkspaceTarget, signal: AbortSignal): void | Promise<void>;
+  archive: SourceArchive;
+  loadSource(input: { appRoot: string; sourceRevision: string; codec: Codec; signal: AbortSignal }): Promise<LoadedTokenSource<SourceFiles, Ledger>>;
+  compilePlan(input: { appRoot: string; sourceRevision: string; before: TokenLibraryDocument; after: TokenLibraryDocument; codec: Codec; signal: AbortSignal; dependenciesReady: true }): Promise<SourceFilePlan>;
+  listConsumers(appRoot: string, signal: AbortSignal): Promise<readonly string[]>;
+  currentRevision(): Promise<string>;
+  regenerate(signal: AbortSignal): Promise<unknown>;
+  install(root: string, signal: AbortSignal): Promise<unknown>;
+  applyMessage?: string;
+  regenerationFailureMessage?(error: unknown): string;
+}
+export interface TokenSourceService<SourceFiles = unknown, Ledger = unknown> {
+  load(sourceRevision: string, signal?: AbortSignal): Promise<WorkspaceTokenLibraryBaseline & { sourceFiles: SourceFiles; ledger: Ledger }>;
+  compile(input: { baseline: WorkspaceTokenLibraryBaseline; document: TokenLibraryDocument }, signal?: AbortSignal): Promise<SourceFilePlan>;
+  preview(request: WorkspaceTokenSourceRequest, signal?: AbortSignal): Promise<InspectPreviewResult>;
+  validatePreviewRequest(request: WorkspaceTokenSourceRequest, signal?: AbortSignal): Promise<WorkspaceTokenSourceRequest>;
+  apply(request: WorkspaceTokenSourceRequest, signal?: AbortSignal): Promise<InspectApplyResult>;
+  dispose(): void;
+}
+export declare function createTokenSourceService<Codec, SourceFiles = unknown, Ledger = unknown>(options: TokenSourceServiceOptions<Codec, SourceFiles, Ledger>): TokenSourceService<SourceFiles, Ledger>;
+
+export declare function sourceServicePlugin<Service extends { dispose(): void | Promise<void> }>(options: {
+  name?: string;
+  endpoint: string;
+  operations: readonly (keyof Service & string)[];
+  createService(server: ViteDevServer): Service;
+  transformInput?(operation: keyof Service & string, input: unknown): unknown;
+  maxBytes?: number;
+}): {
+  plugin: Plugin;
+  validatePreviewRequest: Service extends { validatePreviewRequest: infer Method } ? Method : never;
+  preparePreviewSource: Service extends { preparePreviewSource: infer Method } ? Method : never;
+};

package/workspace-draft-entry.d.ts

@@ -0,0 +1,15 @@
+import type { WorkspaceDraftRecipe } from './dist-lib/types/workspace/source/draftRecipe.js';
+
+/** Trusted build-time declarations for the mounted application's browser entry. */
+export interface WorkspaceDraftEntryOptions {
+  documentRevision: string;
+  recipe: WorkspaceDraftRecipe;
+  /** Module resolving the SDK recipe runner. Defaults to the public package. */
+  sdkModule?: string;
+  /** An application module exporting its desired-state adapter. */
+  desiredStateAdapter?: { module: string; exportName: string };
+  failureMessage?: string;
+}
+
+/** Returns ESM source for a virtual build entry; the application supplies its own bundler and boot setup. */
+export declare function createWorkspaceDraftEntry(options: WorkspaceDraftEntryOptions): string;