@pygmalionjs/pygmalion 0.7.4 → 0.8.0

package/node/dev-mirror.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import { execFile } from 'node:child_process';
 import { resolvePygmalionPreviewViteCacheDir } from './preview-vite-cache.mjs';
+import { sendJson as sendJsonEnvelope } from './envelope.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -253,11 +254,8 @@ export function resolveDevMirrorWorktreePaths({
   };
 }
 
-function json(res, statusCode, body) {
-  res.statusCode = statusCode;
-  res.setHeader('content-type', 'application/json; charset=utf-8');
-  res.end(JSON.stringify(body));
-}
+// One envelope for every endpoint; see envelope.mjs.
+const json = sendJsonEnvelope;
 
 async function run(command, args, options = {}) {
   const result = await execFileAsync(command, args, {
@@ -613,7 +611,12 @@ async function reclaimStaleDevMirrorSyncLock({
   }
 }
 
-/** Serializes mirror mutation and exact read-lease acquisition across processes. */
+/**
+ * Serializes mirror mutation and exact read-lease acquisition across processes.
+ * @param {string} repoRoot
+ * @param {() => Promise<unknown>} task
+ * @param {{ onLockCandidateReady?: (info: unknown) => unknown; onStaleLockConfirmed?: (info: unknown) => unknown; lockTimeoutMs?: number }} [options]
+ */
 export async function withDevMirrorSyncLock(
   repoRoot,
   task,

package/node/envelope.mjs

@@ -0,0 +1,43 @@
+// One JSON envelope for every Pygmalion endpoint.
+//
+// Success bodies are whatever the operation returns. Failures always carry
+// `ok: false`, a machine `error` code the transport maps to TransportError,
+// and a prose `message`; `retryable`, `preparing`, and `details` ride along
+// when the operation sets them. Plugins that used to write prose into `error`
+// still can — it moves to `message` here and the code becomes request_failed.
+const MACHINE_CODE = /^[a-z][a-z0-9_]*$/;
+
+/** Shapes a failure body: machine code in `error`, prose in `message`. */
+export function errorBody(body) {
+  const source = body && typeof body === 'object' && !Array.isArray(body) ? body : { error: String(body) };
+  const { error, message, ...rest } = source;
+  const code = typeof error === 'string' && MACHINE_CODE.test(error) ? error : 'request_failed';
+  const prose =
+    typeof message === 'string' && message
+      ? message
+      : typeof error === 'string' && !MACHINE_CODE.test(error)
+        ? error
+        : undefined;
+  return {
+    ...rest,
+    ok: false,
+    error: code,
+    ...(prose === undefined ? {} : { message: prose }),
+  };
+}
+
+/**
+ * Writes a JSON response. A status at or above 400, or a body that says
+ * `ok: false`, is written through `errorBody`; anything else is written as is.
+ */
+export function sendJson(response, statusCode, body) {
+  const failed =
+    statusCode >= 400 || (body && typeof body === 'object' && !Array.isArray(body) && body.ok === false);
+  const payload = `${JSON.stringify(failed ? errorBody(body) : body)}\n`;
+  response.statusCode = statusCode;
+  response.setHeader('content-type', 'application/json; charset=utf-8');
+  response.setHeader('content-length', String(Buffer.byteLength(payload)));
+  response.setHeader('cache-control', 'no-store');
+  response.setHeader('x-content-type-options', 'nosniff');
+  response.end(payload);
+}

package/node/impact-frames.mjs

@@ -0,0 +1,94 @@
+// Which frames a source change reaches, decided where the catalog lives.
+//
+// The editor used to take the dependency closure from `inspect.impact` and
+// match it against each page's sourcePaths in the browser; the QA capture
+// then took the frames the browser had decided on. Deciding here, from the
+// revision catalog the capture worker also reads, gives both the same list.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export function normalizeSourcePath(value) {
+  return String(value)
+    .replaceAll('\\', '/')
+    .replace(/[?#].*$/, '')
+    .replace(/^\.?\//, '')
+    .replace(/\/+/g, '/');
+}
+
+export function sameSourcePath(a, b) {
+  const left = normalizeSourcePath(a);
+  const right = normalizeSourcePath(b);
+  return left === right || left.endsWith(`/${right}`) || right.endsWith(`/${left}`);
+}
+
+/**
+ * The catalog screens whose declared source paths intersect `files`, in
+ * catalog order. Each entry is `{ id, name }`: the canonical frame id the
+ * editor and the capture worker both use, and the screen's name.
+ */
+export function impactFramesFromCatalog(catalog, files) {
+  const pages = catalog?.screens?.pages;
+  if (!Array.isArray(pages) || !Array.isArray(files) || files.length === 0) return [];
+  const frames = [];
+  for (const page of pages) {
+    if (!page || typeof page !== 'object') continue;
+    const id = typeof page.importPageId === 'string' ? page.importPageId : null;
+    if (!id) continue;
+    const sourcePaths = Array.isArray(page.sourcePaths) ? page.sourcePaths : [];
+    const hit = sourcePaths.some(
+      (sourcePath) =>
+        typeof sourcePath === 'string' &&
+        files.some((file) => typeof file === 'string' && sameSourcePath(sourcePath, file)),
+    );
+    if (!hit) continue;
+    frames.push({ id, name: typeof page.name === 'string' ? page.name : id });
+  }
+  return frames;
+}
+
+async function containedFile(root, file) {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, file);
+  if (resolved !== resolvedRoot && !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error('Revision catalog file must stay inside the source root.');
+  }
+  return resolved;
+}
+
+/**
+ * Reads the revision catalog on demand and answers impact frames from it. The
+ * file is re-read only when its modification time changes; a missing or
+ * unreadable catalog answers no frames rather than failing the impact call,
+ * because the dependency closure is still useful on its own.
+ */
+export function createImpactFrameResolver({ root, catalogFile }) {
+  let cached = null;
+  async function readCatalog() {
+    if (!catalogFile) return null;
+    const file = await containedFile(root, catalogFile);
+    let stat;
+    try {
+      stat = await fs.stat(file);
+    } catch {
+      cached = null;
+      return null;
+    }
+    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+      return cached.catalog;
+    }
+    try {
+      const catalog = JSON.parse(await fs.readFile(file, 'utf8'));
+      cached = { mtimeMs: stat.mtimeMs, size: stat.size, catalog };
+      return catalog;
+    } catch {
+      cached = null;
+      return null;
+    }
+  }
+  return {
+    async resolve(files) {
+      const catalog = await readCatalog();
+      return catalog ? impactFramesFromCatalog(catalog, files) : [];
+    },
+  };
+}

package/node/inspect-plugin.mjs

@@ -4,7 +4,9 @@ import path from 'node:path';
 import MagicString from 'magic-string';
 import ts from 'typescript';
 import { findAffectedSourceFiles } from './source-graph.mjs';
+import { createImpactFrameResolver } from './impact-frames.mjs';
 import { writeSourceOperations } from './source-operations.mjs';
+import { sendJson as sendJsonEnvelope } from './envelope.mjs';
 
 export { findAffectedSourceFiles } from './source-graph.mjs';
 export { writeSourceOperations } from './source-operations.mjs';
@@ -338,8 +340,13 @@ export function pygmalionInspectPlugin({
   legacyEndpoints = [],
   normalizeValue,
   sourceDirectory = 'src',
+  catalogFile = null,
 }) {
   const controls = [endpoint, ...legacyEndpoints];
+  // Impact answers frames as well as files when the revision catalog is
+  // known: the same catalog the capture worker reads names each screen's
+  // source paths, so the editor and the QA capture agree on the frames.
+  const impactFrames = createImpactFrameResolver({ root, catalogFile });
   return {
     name: 'pygmalion-inspect',
     apply: 'serve',
@@ -449,7 +456,9 @@ export function pygmalionInspectPlugin({
             const files = await findAffectedSourceFiles(root, input?.componentFiles, {
               sourceDirectory,
             });
-            sendJson(res, 200, { files });
+            const componentFiles = Array.isArray(input?.componentFiles) ? input.componentFiles : [];
+            const frames = await impactFrames.resolve([...componentFiles, ...files]);
+            sendJson(res, 200, { files, frames });
             return;
           }
 
@@ -517,11 +526,8 @@ async function readJson(req) {
   return JSON.parse(raw);
 }
 
-function sendJson(res, status, body) {
-  res.statusCode = status;
-  res.setHeader('content-type', 'application/json; charset=utf-8');
-  res.end(JSON.stringify(body));
-}
+// One envelope for every endpoint; see envelope.mjs.
+const sendJson = sendJsonEnvelope;
 
 export async function writeStyleEdit(
   root,

package/node/preview-artifact-plugin.mjs

@@ -19,6 +19,7 @@ export {
   PYGMALION_REVISION_CATALOG_SUFFIX,
   PREVIEW_CAPTURE_PRIORITY,
 } from './contract.mjs';
+import { sendJson as sendJsonEnvelope } from './envelope.mjs';
 export const DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE =
   'artifacts/pygmalion-route-previews.json';
 
@@ -57,15 +58,8 @@ function isLocalRequestHost(value) {
   }
 }
 
-function sendJson(response, statusCode, body) {
-  const payload = `${JSON.stringify(body)}\n`;
-  response.statusCode = statusCode;
-  response.setHeader('content-type', 'application/json; charset=utf-8');
-  response.setHeader('content-length', String(Buffer.byteLength(payload)));
-  response.setHeader('cache-control', 'no-store');
-  response.setHeader('x-content-type-options', 'nosniff');
-  response.end(payload);
-}
+// One envelope for every endpoint; see envelope.mjs.
+const sendJson = sendJsonEnvelope;
 
 function requestedIdentity(params, key) {
   const value = params.get(key);

package/node/qa-capture-plugin.mjs

@@ -6,6 +6,7 @@ import os from 'node:os';
 import path from 'node:path';
 import pixelmatch from 'pixelmatch';
 import pngjs from 'pngjs';
+import { sendJson as sendJsonEnvelope } from './envelope.mjs';
 
 export const PYGMALION_QA_CAPTURE_ENDPOINT = PYGMALION_ENDPOINTS.qaCapture;
 export const PYGMALION_QA_ARTIFACT_PREFIX = PYGMALION_ENDPOINTS.qaArtifactPrefix;
@@ -1177,12 +1178,8 @@ async function readJson(req) {
   }
 }
 
-function sendJson(res, statusCode, body) {
-  res.statusCode = statusCode;
-  res.setHeader('content-type', 'application/json; charset=utf-8');
-  res.setHeader('cache-control', 'no-store');
-  res.end(JSON.stringify(body));
-}
+// One envelope for every endpoint; see envelope.mjs.
+const sendJson = sendJsonEnvelope;
 
 function sendPng(res, artifact) {
   res.statusCode = 200;

package/node/source-graph.mjs

@@ -379,6 +379,7 @@ export function directSourceUsers(usage, targetFile, { maxDepth = MAX_BARREL_DEP
   const seen = new Set();
   // 'star' means every symbol of the target is in play, which is what the
   // target itself exposes to a direct importer.
+  /** @type {Array<{ module: string; names: 'star' | Set<string>; depth: number }>} */
   const queue = [{ module: targetFile, names: 'star', depth: 0 }];
 
   while (queue.length > 0) {

package/node/storyboard-environment.mjs

@@ -16,6 +16,7 @@ import {
   canonicalizeStoryboardExecutions,
   PYGMALION_STORYBOARD_CANONICAL_CONTROL,
 } from './storyboard-canonical.mjs';
+import { sendJson as sendJsonEnvelope } from './envelope.mjs';
 
 export const PYGMALION_STORYBOARD_ENVIRONMENT_CONTROL =
   PYGMALION_ENDPOINTS.storyboardEnvironment;
@@ -1306,6 +1307,36 @@ export function storyboardEnvironmentBootstrapSource() {
       value: screenPreset,
     });
   }
+  // A preset that fixes the clock (timers.mode 'fixed') is what the Node
+  // capture runtime asks Playwright for. A live frame installs the same clock
+  // here, before application modules run, so the running screen shows the
+  // date and time its capture shows instead of the designer's wall clock.
+  // Timers keep running, as they do under Playwright's fixed time.
+  const timers = screenPreset ? plainRecord(screenPreset.timers) : null;
+  const fixedNow = timers && timers.mode === 'fixed' ? timers.now : null;
+  const fixedTime =
+    typeof fixedNow === 'string' || typeof fixedNow === 'number'
+      ? new Date(fixedNow).getTime()
+      : NaN;
+  if (Number.isFinite(fixedTime)) {
+    const RealDate = globalThis.Date ?? Date;
+    const FixedDate = function Date(...args) {
+      if (!new.target) return new RealDate(fixedTime).toString();
+      return Reflect.construct(
+        RealDate,
+        args.length === 0 ? [fixedTime] : args,
+        new.target === FixedDate ? RealDate : new.target,
+      );
+    };
+    Object.setPrototypeOf(FixedDate, RealDate);
+    FixedDate.prototype = RealDate.prototype;
+    FixedDate.now = () => fixedTime;
+    Object.defineProperty(globalThis, 'Date', {
+      configurable: true,
+      writable: true,
+      value: FixedDate,
+    });
+  }
   // 'sandbox' virtualizes the whole store per document: reads of undeclared
   // keys see a pristine profile and writes never reach the shared origin
   // storage. Hidden preview instances run with it so a walk that persists UI
@@ -1699,12 +1730,8 @@ export function sourceUsageMiddleware(root, { sourceDirectory = 'src' } = {}) {
   };
 }
 
-function sendJson(response, statusCode, body) {
-  response.statusCode = statusCode;
-  response.setHeader('content-type', 'application/json; charset=utf-8');
-  response.setHeader('cache-control', 'no-store');
-  response.end(JSON.stringify(body));
-}
+// One envelope for every endpoint; see envelope.mjs.
+const sendJson = sendJsonEnvelope;
 
 export function pygmalionStoryboardPlugin(options) {
   const root = path.resolve(options.root);

package/node/vite.mjs

@@ -344,6 +344,7 @@ export function createPygmalionVitePlugins(config) {
         ),
         legacyEndpoints: project.inspect.legacyEndpoints ?? [],
         normalizeValue: project.inspect.normalizeValue,
+        catalogFile: revisionCatalogFile,
         sourceDirectory: project.sourceDirectory,
       }),
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {
@@ -52,6 +52,7 @@
   },
   "files": [
     "dist-lib",
+    "docs/coverage-contracts.md",
     "docs/screen-state-contract.md",
     "node/contract.mjs",
     "node/contract.d.mts",
@@ -59,8 +60,10 @@
     "node/automatic-motion-runtime.mjs",
     "node/automatic-pseudo-runtime.mjs",
     "node/design-session.mjs",
+    "node/envelope.mjs",
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",
+    "node/impact-frames.mjs",
     "node/inspect-plugin.mjs",
     "node/inspect.mjs",
     "node/inspect-writeback.mjs",
@@ -99,9 +102,11 @@
     "lint": "eslint .",
     "lint:language": "node scripts/lint-language.mjs",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run lint && npm run lint:language && npm test && npm run typecheck && npm run build:lib",
+    "typecheck:node": "tsc -p tsconfig.node.json",
+    "prepublishOnly": "npm run lint && npm run lint:language && npm test && npm run typecheck && npm run typecheck:node && npm run build:lib",
     "preview": "vite preview",
     "build:types": "node scripts/emit-types.mjs",
+    "smoke:consumer": "node scripts/smoke-consumer.mjs",
     "release": "node scripts/release.mjs"
   },
   "peerDependencies": {