@pygmalionjs/pygmalion 0.8.0 → 0.9.0

package/node/token-source-references.mjs

@@ -0,0 +1,136 @@
+import path from 'node:path';
+import ts from 'typescript';
+
+const names = /--[A-Za-z0-9_\-\u0080-\uFFFF]+/g;
+const unwrap = node => node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) && node.type.getText() === 'const') ? unwrap(node.expression) : node;
+const walk = (node, visit) => { visit(node); ts.forEachChild(node, child => walk(child, visit)); };
+
+/** Conservative source coverage: any diagnostic returns the original source and no edits. */
+export function rewriteTokenSourceReferences({ file, source, renames }) {
+  const diagnostics = []; const references = []; const proposed = new Map(); const handled = new Set();
+  const changes = new Map();
+  const report = (code, message, start, name) => diagnostics.push({ code, message, file, ...(start === undefined ? {} : { start }), ...(name ? { name } : {}) });
+  if (typeof source !== 'string' || typeof file !== 'string' || !Array.isArray(renames)) throw new TypeError('Source reference scanning requires a file, source, and rename list.');
+  for (const { from, to } of renames) {
+    if (!/^--[A-Za-z0-9_-]+$/.test(from) || to !== null && !/^--[A-Za-z0-9_-]+$/.test(to) || changes.has(from)) report('invalid-rename', 'Rename entries require unique, exact supported custom-property names.');
+    else changes.set(from, to);
+  }
+  const destinations = [...changes.values()].filter(value => value !== null);
+  if (new Set(destinations).size !== destinations.length) report('rename-collision', 'Two custom properties cannot be renamed to the same name.');
+  const edit = (start, end, after) => {
+    const before = source.slice(start, end); const prior = proposed.get(start);
+    if (prior && (prior.end !== end || prior.after !== after)) report('overlapping-edit', 'Shared source requires incompatible replacements.', start);
+    else if (before !== after) proposed.set(start, { start, end, before, after });
+  };
+  const reference = (name, start, end, kind = 'static') => {
+    references.push({ name, start, end, kind }); handled.add(start);
+    if (!changes.has(name)) return;
+    const to = changes.get(name);
+    if (to === null) report('token-in-use', 'A removed custom property still has a source reference.', start, name);
+    else if (kind === 'static') edit(start, end, to);
+  };
+  const overlaps = (prefix, suffix = '') => [...changes.keys()].some(name => name.startsWith(prefix) && name.endsWith(suffix));
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.JSX, source);
+  const comments = [];
+  while (scanner.scan() !== ts.SyntaxKind.EndOfFileToken) {
+    if ([ts.SyntaxKind.SingleLineCommentTrivia, ts.SyntaxKind.MultiLineCommentTrivia].includes(scanner.getToken())) comments.push([scanner.getTokenPos(), scanner.getTextPos()]);
+  }
+  const inComment = offset => comments.some(([start, end]) => offset >= start && offset < end);
+  const extension = path.extname(file).toLowerCase();
+  if (['.css', '.scss'].includes(extension)) {
+    const quoted = [...source.matchAll(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g)].map(match => [match.index, match.index + match[0].length]);
+    for (const match of source.matchAll(/var\(([^)]*)\)/g)) {
+      if (!inComment(match.index) && /\$|#\{|\\/.test(match[1]) && overlaps(match[1].match(/^\s*(--[\w-]*)/)?.[1] ?? '')) report('source-coverage', 'Dynamic or escaped stylesheet names require a host-resolved source contract.', match.index);
+    }
+    for (const match of source.matchAll(/(--[\w-]*)(?:#\{[^}]*\}|\$[\w-]+)/g)) {
+      if (!inComment(match.index) && overlaps(match[1])) report('source-coverage', 'Interpolated stylesheet names require a host-resolved source contract.', match.index);
+    }
+    for (const match of source.matchAll(names)) {
+      const start = match.index; const end = start + match[0].length;
+      if (inComment(start)) continue;
+      const literal = quoted.some(([left, right]) => start >= left && end <= right);
+      const before = source.slice(0, start); const after = source.slice(end);
+      if (!literal && (/var\(\s*$/.test(before) || /^\s*:/.test(after) || /@property\s+$/.test(before))) reference(match[0], start, end);
+    }
+  } else if (['.ts', '.tsx', '.js', '.jsx', '.mjs', '.mts', '.cjs', '.cts'].includes(extension)) {
+    const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ['.tsx', '.jsx'].includes(extension) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    if (/** @type {ts.SourceFile & { parseDiagnostics: unknown[] }} */ (parsed).parseDiagnostics.length) report('source-coverage', 'The source cannot be parsed completely.');
+    const contexts = new Map();
+    walk(parsed, node => {
+      if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        const raw = node.getText(parsed); const prefix = raw.match(/--[\w-]*/)?.[0] ?? '';
+        if ((raw.includes('var(') || prefix) && overlaps(prefix)) report('source-coverage', 'Concatenated custom-property names require a host-resolved source contract.', node.getStart(parsed));
+      }
+      if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        const start = node.getStart(parsed) + 1; const raw = source.slice(start, node.end - 1);
+        const parent = node.parent;
+        const propertyName = ts.isPropertyAssignment(parent) && parent.name === node;
+        const apiName = ts.isCallExpression(parent) && parent.arguments[0] === node && ts.isPropertyAccessExpression(parent.expression)
+          && ['setProperty', 'getPropertyValue', 'removeProperty'].includes(parent.expression.name.text);
+        for (const match of node.text.matchAll(names)) {
+          const position = start + match.index;
+          if (raw !== node.text) { if (changes.has(match[0])) report('source-coverage', 'Escaped string references require an explicit source contract.', start, match[0]); continue; }
+          if (/var\(\s*$/.test(raw.slice(0, match.index)) || match[0] === raw && (propertyName || apiName)) reference(match[0], position, position + match[0].length);
+        }
+      }
+      if (!ts.isTemplateExpression(node)) return;
+      const prefixMatch = node.head.text.match(/(?:var\(\s*)?(--[\w-]*)$/);
+      if (!prefixMatch && !node.head.text.includes('var(')) return;
+      const prefix = prefixMatch?.[1] ?? '';
+      if (!overlaps(prefix)) return;
+      const span = node.templateSpans[0];
+      const suffix = node.templateSpans.length === 1 && span.literal.text.match(/^([\w-]*)\s*\)$/);
+      let callback = node.parent;
+      while (callback && !ts.isFunctionLike(callback)) callback = callback.parent;
+      let argument = callback;
+      while (argument?.parent && ts.isParenthesizedExpression(argument.parent)) argument = argument.parent;
+      const call = argument?.parent;
+      const binding = callback && ts.isArrowFunction(callback) && callback.parameters[0]?.name;
+      const first = binding && ts.isArrayBindingPattern(binding) && binding.elements[0];
+      const variable = first && ts.isBindingElement(first) && !first.initializer && !first.dotDotDotToken && ts.isIdentifier(first.name) ? first.name : null;
+      const receiver = call && ts.isCallExpression(call) && unwrap(call.arguments[0]) === callback && ts.isPropertyAccessExpression(call.expression)
+        && call.expression.name.text === 'map' ? unwrap(call.expression.expression) : null;
+      const rows = receiver && ts.isArrayLiteralExpression(receiver) ? receiver.elements.map(unwrap) : [];
+      if (ts.isTaggedTemplateExpression(node.parent) || !/^var\(\s*--[\w-]*$/.test(node.head.text) || !suffix || !variable || !ts.isIdentifier(span.expression) || span.expression.text !== variable.text
+        || !rows.length || rows.some(row => !ts.isArrayLiteralExpression(row) || !row.elements.length || !ts.isStringLiteral(row.elements[0]))) {
+        report('source-coverage', 'Dynamic custom properties require a direct literal tuple map and one bound interpolation.', node.getStart(parsed)); return;
+      }
+      const context = contexts.get(callback) ?? { callback, variable, rows, uses: [] };
+      context.uses.push({ prefix, suffix: suffix[1], node, expression: span.expression }); contexts.set(callback, context);
+    });
+    for (const { callback, variable, rows, uses } of contexts.values()) {
+      const replacements = [];
+      for (const row of rows) {
+        const item = row.elements[0]; const start = item.getStart(parsed) + 1; const values = new Set();
+        for (const use of uses) {
+          const name = use.prefix + item.text + use.suffix; reference(name, start, item.end - 1, 'finite');
+          const to = changes.has(name) ? changes.get(name) : name;
+          if (to === null) continue;
+          if (!to.startsWith(use.prefix) || !to.endsWith(use.suffix)) { report('source-coverage', 'The renamed property cannot use the existing template prefix and suffix.', start, name); continue; }
+          values.add(to.slice(use.prefix.length, use.suffix ? -use.suffix.length : undefined));
+        }
+        if (values.size > 1) report('source-coverage', 'A shared tuple key would change another custom-property reference.', start);
+        const value = [...values][0] ?? item.text; replacements.push(value);
+        if (value !== item.text) {
+          if (!/^[\w-]+$/.test(value) || source.slice(start, item.end - 1) !== item.text) report('source-coverage', 'Tuple edits require plain literal keys.', start);
+          else edit(start, item.end - 1, value);
+          walk(callback.body, node => {
+            if (ts.isIdentifier(node) && node.text === variable.text && !uses.some(use => use.expression === node)) report('source-coverage', 'The tuple key has another use that this rename cannot prove.', node.getStart(parsed));
+          });
+        }
+      }
+      if (replacements.some((value, index) => replacements.indexOf(value) !== index && rows[replacements.indexOf(value)].elements[0].text !== rows[index].elements[0].text)) report('rename-collision', 'Renaming would merge distinct tuple keys.');
+    }
+  } else report('source-coverage', 'This source language has no custom-property reference contract.');
+  for (const match of source.matchAll(names)) {
+    if (changes.has(match[0]) && !handled.has(match.index) && !inComment(match.index)) report('source-coverage', 'A custom-property occurrence is outside a proven CSS reference.', match.index, match[0]);
+  }
+  for (const { name, start } of references) {
+    if (destinations.includes(name) && !changes.has(name)) report('rename-collision', 'The rename target already has another source reference.', start, name);
+  }
+  const edits = [...proposed.values()].sort((left, right) => left.start - right.start);
+  if (edits.some((entry, index) => index && entry.start < edits[index - 1].end)) report('overlapping-edit', 'Source replacements overlap.');
+  if (diagnostics.length) return { source, edits: [], diagnostics, references };
+  for (const entry of edits.toReversed()) source = source.slice(0, entry.start) + entry.after + source.slice(entry.end);
+  return { source, edits, diagnostics, references };
+}

package/node/workspace-draft-preview-plugin.mjs

@@ -0,0 +1,70 @@
+import { randomUUID } from 'node:crypto';
+
+/** Local transport for a host-configured isolated builder. The browser supplies no build commands. */
+export function workspaceDraftPreviewPlugin({ service, resolveRequest, waitForReady = false, endpoint = '/__pygmalion-workspace-draft-preview' }) {
+  if (!/^\/[A-Za-z0-9/_-]+$/.test(endpoint) || typeof resolveRequest !== 'function') {
+    throw new Error('Draft preview requires a local endpoint and a host request resolver.');
+  }
+  const leases = new Map();
+  return {
+    name: 'pygmalion-workspace-draft-preview',
+    apply: 'serve',
+    configureServer(server) {
+      server.httpServer?.once('close', () => {
+        for (const controller of leases.values()) controller.abort();
+        leases.clear();
+        void service.dispose().catch(error => server.config.logger.error(String(error)));
+      });
+      server.middlewares.use(async (req, res, next) => {
+        if (req.url?.split('?')[0] !== endpoint) return next();
+        try {
+          if (req.headers.origin && new URL(req.headers.origin).host !== req.headers.host) {
+            res.statusCode = 403; res.end(JSON.stringify({ error: 'Draft preview requires the editor origin.' })); return;
+          }
+        } catch { res.statusCode = 403; res.end(); return; }
+        if (req.method === 'DELETE') {
+          const lease = new URL(req.url, 'http://local.invalid').searchParams.get('lease');
+          leases.get(lease)?.abort(); leases.delete(lease);
+          res.statusCode = 204; res.end(); return;
+        }
+        if (req.method !== 'POST') { res.statusCode = 405; res.end(); return; }
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        req.once('aborted', abort);
+        res.once('close', abort);
+        res.setHeader('content-type', 'application/json; charset=utf-8');
+        res.setHeader('cache-control', 'no-store');
+        try {
+          if (!/^application\/json(?:;|$)/i.test(req.headers['content-type'] ?? '')) {
+            res.statusCode = 415; res.end(JSON.stringify({ error: 'Draft preview requires a JSON request.' })); return;
+          }
+          const chunks = []; let bytes = 0;
+          for await (const chunk of req) {
+            bytes += chunk.length;
+            if (bytes > 10 * 1024 * 1024) throw new Error('Draft preview request exceeds the size limit.');
+            chunks.push(chunk);
+          }
+          controller.signal.throwIfAborted();
+          const input = await resolveRequest(JSON.parse(Buffer.concat(chunks).toString('utf8')), { signal: controller.signal });
+          controller.signal.throwIfAborted();
+          const surface = await service.prepare(input, { signal: controller.signal });
+          controller.signal.throwIfAborted();
+          const lease = randomUUID();
+          leases.set(lease, controller);
+          controller.signal.addEventListener('abort', () => leases.delete(lease), { once: true });
+          res.setHeader('x-pygmalion-preview-lease', lease);
+          res.end(JSON.stringify({ surface: waitForReady ? { ...surface, waitForReady: true } : surface, lease }));
+        } catch (error) {
+          controller.abort();
+          if (!res.destroyed && !res.writableEnded) {
+            res.statusCode = 409;
+            res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+          }
+        } finally {
+          req.removeListener('aborted', abort);
+          res.removeListener('close', abort);
+        }
+      });
+    },
+  };
+}

package/node/workspace-draft-preview.mjs

@@ -0,0 +1,231 @@
+import { materializeSourceArchive } from './source-archive.mjs';
+import { createHash } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { writeInspectChanges } from './inspect-writeback.mjs';
+import { validateInspectSourceProofs } from './source-file-proofs.mjs';
+import { applySourceFilePlan } from './source-file-plan.mjs';
+import { workspaceSourceFingerprint } from './workspace-source-identity.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const same = (left, right) => workspaceSourceFingerprint(left) === workspaceSourceFingerprint(right);
+function freeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+}
+function relative(value) {
+  return typeof value === 'string' && value.length > 0 && !/[\\\x00-\x1f\x7f]/.test(value)
+    && !path.posix.isAbsolute(value) && !/^[a-z]:/i.test(value)
+    && !value.split('/').some(part => !part || part === '.' || part === '..' || part === '.git');
+}
+function positive(value, fallback) {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < 1) throw new Error('Preview resource limits must be positive integers.');
+  return selected;
+}
+function validateRoute(route) {
+  if (typeof route !== 'string' || !route.startsWith('/') || route.startsWith('//') || /[\\\x00-\x20\x7f]/.test(route)) throw new Error('The preview route must be an application-relative URL.');
+  const rawPath = decodeURIComponent(route.split(/[?#]/)[0]);
+  if (rawPath.split('/').some(part => part === '.' || part === '..') || rawPath.includes('\\')) throw new Error('The preview route cannot escape the application.');
+  return route;
+}
+
+/** Verify the complete browser capture before materializing source or invoking a build. */
+function captureInput(input) {
+  const captured = JSON.parse(workspaceSourceFingerprint(input));
+  const { request, documentRevision, route } = captured ?? {};
+  const { target, document, identity, payload } = request ?? {};
+  if (request?.sourceKind !== undefined && request.sourceKind !== 'file-plan') throw new Error('The draft preview request has an unsupported source kind.');
+  if (!target || !document || !identity || !payload || !/^(?:[a-f\d]{40}|[a-f\d]{64})$/.test(target.sourceRevision ?? '')
+    || typeof target.screenId !== 'string' || !target.screenId.trim() || identity.version !== 1
+    || document.schemaVersion !== 1 || document.id !== identity.documentId || document.sourceRevision !== target.sourceRevision
+    || !same(identity.target, target) || identity.afterFingerprint !== workspaceSourceFingerprint(document)
+    || identity.payloadFingerprint !== workspaceSourceFingerprint(payload)) throw new Error('The draft preview request has inconsistent document, payload, or source identity.');
+  const { fingerprint, ...parts } = identity;
+  if (fingerprint !== workspaceSourceFingerprint(parts) || documentRevision !== hash(identity.afterFingerprint)) throw new Error('The draft revision must hash the complete captured document identity.');
+  let before; let mapping;
+  try {
+    before = JSON.parse(identity.beforeFingerprint);
+    mapping = JSON.parse(identity.mappingFingerprint);
+  } catch { throw new Error('The draft preview requires complete source baseline and mapping fingerprints.'); }
+  if (workspaceSourceFingerprint(before) !== identity.beforeFingerprint || workspaceSourceFingerprint(mapping) !== identity.mappingFingerprint
+    || before.id !== document.id || before.sourceRevision !== target.sourceRevision || mapping.version !== 1
+    || mapping.documentId !== document.id || mapping.baselineFingerprint !== identity.beforeFingerprint || !same(mapping.target, target)) throw new Error('The captured source baseline, mapping, and file proofs must agree.');
+  if (request.sourceKind === 'file-plan') {
+    if (payload.version !== 1 || payload.sourceRevision !== target.sourceRevision || !Array.isArray(payload.proofs)
+      || !same(mapping.files, payload.proofs)) throw new Error('The captured file plan, mapping, and file proofs must agree.');
+  } else if (!payload.sourceProof || payload.sourceProof.sourceRevision !== target.sourceRevision || !same(mapping.files, payload.sourceProof.files)) {
+    throw new Error('The captured source baseline, mapping, and file proofs must agree.');
+  }
+  validateRoute(route);
+  return freeze(captured);
+}
+
+async function captureOutput(outputDirectory, { maxOutputFiles, maxOutputBytes }, signal) {
+  const files = new Map(); let total = 0;
+  const visit = async (directory, prefix) => {
+    const directoryStat = await fsp.lstat(directory);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) throw new Error('Build output directories must not be symbolic links.');
+    for (const entry of await fsp.readdir(directory, { withFileTypes: true })) {
+      signal.throwIfAborted();
+      const key = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (!relative(key)) throw new Error('Build output contains an unsafe path.');
+      const absolute = path.join(directory, entry.name);
+      const stat = await fsp.lstat(absolute);
+      if (stat.isDirectory()) { await visit(absolute, key); continue; }
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Build output must contain regular files only.');
+      if (files.size >= maxOutputFiles || total + stat.size > maxOutputBytes) throw new Error('The built preview exceeds its output resource limits.');
+      const bytes = await fsp.readFile(absolute, { signal });
+      if (bytes.length !== stat.size) throw new Error('Build output changed while it was captured.');
+      total += bytes.length; files.set(key, bytes);
+    }
+  };
+  await visit(outputDirectory, '');
+  if (!files.has('index.html')) throw new Error('The built application requires index.html.');
+  return files;
+}
+
+const mimeTypes = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.map': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.ico': 'image/x-icon',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.wasm': 'application/wasm', '.txt': 'text/plain; charset=utf-8' };
+function closeServer(server) {
+  if (!server) return Promise.resolve();
+  return new Promise(resolve => { server.close(() => resolve()); server.closeAllConnections(); });
+}
+
+/**
+ * Build in a disposable archive and serve only captured bytes from a separate loopback origin.
+ * The host must first validate file-plan requests against its canonical source compiler.
+ * Identity consistency and archived file proofs do not establish a document-to-source mapping.
+ * The archive is the request's exact commit; a request for another revision than the
+ * checked-out one builds that revision's files, never the working tree relabelled.
+ */
+export function createWorkspaceDraftPreviewService(options) {
+  if (!options || typeof options.projectRoot !== 'string' || typeof options.build !== 'function') throw new Error('A draft preview service requires a project root and trusted build callback.');
+  if (options.prepareSource !== undefined && typeof options.prepareSource !== 'function') throw new Error('Source preparation must be a trusted host callback.');
+  const projectRoot = path.resolve(options.projectRoot);
+  const appDirectory = options.appDirectory ?? '.';
+  if (appDirectory !== '.' && !relative(appDirectory)) throw new Error('The application directory must be project-relative.');
+  const maxRuns = positive(options.maxRuns, 3);
+  const limits = { maxOutputFiles: positive(options.maxOutputFiles, 10000), maxOutputBytes: positive(options.maxOutputBytes, 128 * 1024 * 1024) };
+  const build = options.build; const handleRequest = options.handleRequest; const prepareSource = options.prepareSource;
+  const dependenciesRoot = options.dependenciesRoot ? path.resolve(options.dependenciesRoot) : null;
+  const runs = new Set(); let disposed = false; let disposal;
+
+  const prepare = (input, { signal } = {}) => {
+    if (disposed) return Promise.reject(new Error('The draft preview service has been disposed.'));
+    if (signal?.aborted) return Promise.reject(signal.reason ?? new Error('Draft preview was aborted.'));
+    if (runs.size >= maxRuns) return Promise.reject(new Error('The draft preview service has reached its active run limit.'));
+    let captured;
+    try { captured = captureInput(input); } catch (error) { return Promise.reject(error); }
+    const controller = new AbortController();
+    const run = { controller, server: null, files: null, temporary: null, done: null };
+    const abort = () => { controller.abort(signal?.reason); void closeServer(run.server); };
+    signal?.addEventListener('abort', abort, { once: true });
+    runs.add(run);
+    run.done = (async () => {
+      let ready = false;
+      try {
+        run.temporary = await fsp.mkdtemp(path.join(os.tmpdir(), 'pygmalion-draft-preview-'));
+        controller.signal.throwIfAborted();
+        // The archive holds exactly the requested commit, whatever the repository's
+        // working tree or HEAD currently contains. Every host callback receives that
+        // commit so a build for one revision can never be labelled as another.
+        const sourceRevision = captured.request.target.sourceRevision;
+        const appRoot = await materializeSourceArchive(projectRoot, appDirectory, sourceRevision, run.temporary, controller.signal);
+        controller.signal.throwIfAborted();
+        // A trusted host may stage its reviewed working-copy inputs in this archive.
+        // Full request proofs are still checked below, after the callback settles.
+        if (prepareSource) await prepareSource({ appRoot, request: captured.request, sourceRevision, signal: controller.signal });
+        controller.signal.throwIfAborted();
+        if (captured.request.sourceKind === 'file-plan') {
+          await applySourceFilePlan(appRoot, captured.request.payload, {
+            sourceRevision: captured.request.target.sourceRevision,
+            allowedFiles: captured.request.payload.changes.map(change => change.file),
+            signal: controller.signal,
+          });
+        } else {
+          await validateInspectSourceProofs(appRoot, captured.request.payload, { sourceRevision: captured.request.target.sourceRevision });
+          controller.signal.throwIfAborted();
+          await writeInspectChanges(appRoot, captured.request.payload);
+        }
+        controller.signal.throwIfAborted();
+        if (dependenciesRoot) {
+          const dependencies = await fsp.realpath(dependenciesRoot);
+          if (!(await fsp.stat(dependencies)).isDirectory()) throw new Error('The dependency root must identify an existing node_modules directory.');
+          await fsp.symlink(dependencies, path.join(appRoot, 'node_modules'), 'dir');
+        }
+        const outputDirectory = path.join(run.temporary, 'output');
+        await fsp.mkdir(outputDirectory);
+        await build({ appRoot, outputDirectory, request: captured.request, sourceRevision, signal: controller.signal });
+        controller.signal.throwIfAborted();
+        run.files = await captureOutput(outputDirectory, limits, controller.signal);
+        await fsp.rm(run.temporary, { recursive: true, force: true }); run.temporary = null;
+        controller.signal.throwIfAborted();
+        let authority;
+        const server = http.createServer((request, response) => {
+          void (async () => {
+            response.setHeader('cache-control', 'no-store'); response.setHeader('x-content-type-options', 'nosniff');
+            if (request.headers.host !== authority) { response.writeHead(403).end('Unexpected preview origin.'); return; }
+            if (handleRequest) {
+              const handled = await handleRequest(request, response, { request: captured.request, sourceRevision });
+              if (handled || response.headersSent || response.writableEnded) return;
+            }
+            if (!['GET', 'HEAD'].includes(request.method)) { response.writeHead(405, { allow: 'GET, HEAD' }).end(); return; }
+            let pathname;
+            try { pathname = decodeURIComponent(new URL(request.url, `http://${authority}`).pathname); }
+            catch { response.writeHead(400).end(); return; }
+            if (pathname.includes('\\') || pathname.split('/').some(part => part === '..' || part === '.')) { response.writeHead(400).end(); return; }
+            let key = pathname.slice(1) || 'index.html';
+            let bytes = run.files?.get(key);
+            if (!bytes && !path.posix.extname(key)) { key = 'index.html'; bytes = run.files?.get(key); }
+            if (!bytes) { response.writeHead(404).end(); return; }
+            response.writeHead(200, { 'content-type': mimeTypes[path.posix.extname(key)] ?? 'application/octet-stream', 'content-length': bytes.length });
+            response.end(request.method === 'HEAD' ? undefined : bytes);
+          })().catch(() => { if (response.headersSent) response.destroy(); else response.writeHead(500).end('Preview request failed.'); });
+        });
+        run.server = server;
+        await new Promise((resolve, reject) => {
+          const aborted = () => reject(controller.signal.reason ?? new Error('Draft preview was aborted.'));
+          const cleanup = () => { controller.signal.removeEventListener('abort', aborted); server.off('error', failed); };
+          const failed = error => { cleanup(); reject(error); };
+          controller.signal.addEventListener('abort', aborted, { once: true });
+          server.once('error', failed);
+          server.listen({ host: '127.0.0.1', port: 0, signal: controller.signal }, () => { cleanup(); resolve(); });
+        });
+        controller.signal.throwIfAborted();
+        authority = `127.0.0.1:${server.address().port}`;
+        ready = true;
+        return Object.freeze({ url: `http://${authority}${captured.route}`, documentRevision: captured.documentRevision });
+      } finally {
+        if (!ready) {
+          await closeServer(run.server);
+          if (run.temporary) await fsp.rm(run.temporary, { recursive: true, force: true });
+          run.files?.clear(); runs.delete(run); signal?.removeEventListener('abort', abort);
+        }
+      }
+    })();
+    controller.signal.addEventListener('abort', () => {
+      void closeServer(run.server).then(() => {
+        if (!run.temporary) { run.files?.clear(); runs.delete(run); signal?.removeEventListener('abort', abort); }
+      });
+    }, { once: true });
+    return run.done;
+  };
+
+  return Object.freeze({ prepare, dispose() {
+    if (disposal) return disposal;
+    disposed = true;
+    const active = [...runs]; active.forEach(run => run.controller.abort(new Error('The draft preview service was disposed.')));
+    disposal = (async () => {
+      await Promise.allSettled(active.map(run => run.done));
+      await Promise.all(active.map(async run => { await closeServer(run.server); if (run.temporary) await fsp.rm(run.temporary, { recursive: true, force: true }); run.files?.clear(); runs.delete(run); }));
+    })();
+    return disposal;
+  } });
+}
+
+export { workspaceDraftPreviewPlugin } from './workspace-draft-preview-plugin.mjs';

package/node/workspace-source-identity.d.mts

@@ -0,0 +1 @@
+export declare function workspaceSourceFingerprint(value: unknown): string;

package/node/workspace-source-identity.mjs

@@ -0,0 +1,21 @@
+/** Full JSON identity with sorted object keys; array order and every value are retained. */
+export function workspaceSourceFingerprint(value) {
+  const ancestors = new Set();
+  const encode = (item) => {
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return JSON.stringify(item);
+    if (typeof item === 'number' && Number.isFinite(item)) return Object.is(item, -0) ? '-0' : String(item);
+    if (!item || typeof item !== 'object' || ancestors.has(item)
+      || (!Array.isArray(item) && ![Object.prototype, null].includes(Object.getPrototypeOf(item)))) throw new Error('Source fingerprints require complete, finite JSON values.');
+    ancestors.add(item);
+    try {
+      if (Object.getOwnPropertySymbols(item).length) throw new Error('Source fingerprints cannot omit symbol properties.');
+      if (Array.isArray(item)) {
+        if (Object.keys(item).length !== item.length || Array.from({ length: item.length }, (_, index) => index).some((index) => !Object.hasOwn(item, index))) throw new Error('Source fingerprints require dense JSON arrays.');
+        return `[${item.map(encode).join(',')}]`;
+      }
+      return `{${Object.keys(item).sort().map((key) => `${JSON.stringify(key)}:${encode(item[key])}`).join(',')}}`;
+    } finally { ancestors.delete(item); }
+  };
+  return encode(value);
+}
+