@pygmalionjs/pygmalion 0.6.31 → 0.6.33

package/node/vite.mjs

@@ -4,6 +4,7 @@ import {
   PYGMALION_DEV_PREFIX,
   PYGMALION_WORKTREE_SOURCE_REF,
   pygmalionDevMirrorPlugin,
+  resolveExactCheckoutSourceRoot,
 } from './dev-mirror.mjs';
 import {
   PYGMALION_INSPECT_CONTROL,
@@ -68,6 +69,7 @@ import {
   DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
   PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX,
+  PYGMALION_REVISION_CATALOG_SUFFIX,
   pygmalionPreviewArtifactPlugin,
 } from './preview-artifact-plugin.mjs';
 import { createPreviewCaptureWorkerChannel } from './preview-capture-worker.mjs';
@@ -233,6 +235,17 @@ export function createPygmalionVitePlugins(config) {
   // worker script; the function wins when both are present so existing
   // configurations keep their exact behavior.
   let generateArtifact = project.preview.generateArtifact;
+  const revisionCatalog =
+    project.preview.catalog === false
+      ? false
+      : optionalObject(project.preview.catalog);
+  const revisionCatalogFile =
+    revisionCatalog === false
+      ? undefined
+      : optionalNonEmptyString(
+          revisionCatalog.file,
+          'preview.catalog.file',
+        );
   let captureWorkerChannel = null;
   if (!generateArtifact && project.preview.captureWorker) {
     const captureWorker = optionalObject(project.preview.captureWorker);
@@ -255,15 +268,47 @@ export function createPygmalionVitePlugins(config) {
     generateArtifact = captureWorkerChannel.generateArtifact;
   }
 
-  if (project.preview.artifactFile || generateArtifact) {
+  if (project.preview.artifactFile || generateArtifact || revisionCatalogFile) {
     plugins.push(
       pygmalionPreviewArtifactPlugin({
         root: project.appRoot,
         artifactFile: project.preview.artifactFile,
         endpoint: project.preview.artifactEndpoint,
+        catalogFile: revisionCatalogFile,
+        catalogEndpoint:
+          revisionCatalog === false ? undefined : revisionCatalog.endpoint,
         generateArtifact,
         acquireLease: (label) => devMirror?.acquireLease(label) ?? null,
-        sourceRoot: () => devMirror?.activeAppRoot?.() ?? project.appRoot,
+        acquireSourceLease: async (sourceRevision, label) => {
+          if (devMirror?.acquireSourceLease) {
+            return devMirror.acquireSourceLease(sourceRevision, label);
+          }
+          const current = resolveGitSourceState(project.projectRoot);
+          if (current.dirty || current.revision !== sourceRevision) return null;
+          const exactSourceRoot = await resolveExactCheckoutSourceRoot({
+            checkoutRoot: project.projectRoot,
+            sourceRoot: project.appRoot,
+            expectedRevision: sourceRevision,
+          });
+          if (!exactSourceRoot) return null;
+          return {
+            sourceRoot: exactSourceRoot,
+            sourceRevision: current.revision,
+            async validate() {
+              const latest = resolveGitSourceState(project.projectRoot);
+              if (latest.dirty || latest.revision !== sourceRevision) {
+                return false;
+              }
+              const latestSourceRoot = await resolveExactCheckoutSourceRoot({
+                checkoutRoot: project.projectRoot,
+                sourceRoot: project.appRoot,
+                expectedRevision: sourceRevision,
+              });
+              return latestSourceRoot === exactSourceRoot;
+            },
+            async release() {},
+          };
+        },
         requestRuntime: () => devMirror?.requestRuntime?.(),
         // No mirror plugin means no checkout to prepare, so generation is
         // always allowed to proceed as it did before.
@@ -442,6 +487,7 @@ export {
   DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
   PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX,
+  PYGMALION_REVISION_CATALOG_SUFFIX,
   pygmalionPreviewArtifactPlugin,
   createPreviewCaptureWorkerChannel,
   DEFAULT_QA_CAPTURE_MAX_FRAMES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.6.31",
+  "version": "0.6.33",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {

package/vite.d.ts

@@ -22,9 +22,18 @@ export interface PygmalionInventoryConfig {
   outputRoot?: string;
   /**
    * Generator-owned paths relative to the host application root. The dedicated
-   * mirror restores only these paths before checking for unexpected changes.
+   * mirror restores these paths before synchronization and rejects any change
+   * the generator leaves outside them.
    */
   outputs?: string[];
+  /**
+   * Ignored runtime/configuration files the generator must not change. Paths
+   * are relative to appRoot; each entry must name a file, not a directory.
+   * Pygmalion compares bounded content signatures immediately around generation
+   * without walking .git, node_modules, or other unrelated trees. At most 64
+   * files totaling 16 MiB may be declared.
+   */
+  runtimeInputs?: string[];
   generate?: (context: PygmalionInventoryContext) => void | Promise<void>;
 }
 
@@ -71,6 +80,16 @@ export interface PygmalionPreviewCaptureWorkerConfig {
   jobTimeoutMs?: number;
 }
 
+export interface PygmalionRevisionCatalogConfig {
+  /**
+   * JSON catalog generated inside each source checkout, relative to appRoot.
+   * The mirror inventory step should own this file and stamp its exact commit.
+   */
+  file: string;
+  /** Defaults to `${artifactEndpoint}/catalog`. */
+  endpoint?: string;
+}
+
 export interface PygmalionPreviewCaptureProgressEvent {
   phase: 'queued' | 'preparing' | 'capturing' | 'retrying' | 'finalizing';
   completed: number;
@@ -83,6 +102,15 @@ export interface PygmalionPreviewCaptureGeneratorOptions {
   onProgress?: (progress: PygmalionPreviewCaptureProgressEvent) => void;
 }
 
+export interface PygmalionPreviewFrameRequest {
+  id: string;
+  fingerprint?: string;
+  /** Identity of the complete capture recipe represented by `fingerprint`. */
+  recipeFingerprint?: string;
+  /** Opaque JSON recipe forwarded unchanged to the host capture generator. */
+  recipe?: Readonly<Record<string, unknown>>;
+}
+
 export interface PygmalionPreviewConfig {
   configFile?: string;
   viteConfig?: string;
@@ -104,7 +132,7 @@ export interface PygmalionPreviewConfig {
     request: {
       namespace: string;
       sourceRevision: string;
-      frames?: readonly { id: string; fingerprint?: string }[];
+      frames?: readonly PygmalionPreviewFrameRequest[];
       captureBaseUrl?: string;
     },
     options?: PygmalionPreviewCaptureGeneratorOptions,
@@ -114,6 +142,8 @@ export interface PygmalionPreviewConfig {
    * `generateArtifact` is absent. When both are set, `generateArtifact` wins.
    */
   captureWorker?: PygmalionPreviewCaptureWorkerConfig;
+  /** Exact-checkout screen catalog served before preview artifacts are probed. */
+  catalog?: false | PygmalionRevisionCatalogConfig;
 }
 
 export interface PygmalionQaConfig
@@ -186,17 +216,21 @@ export declare function createPygmalionVitePlugins(
 
 export declare const PYGMALION_PREVIEW_ARTIFACT_ENDPOINT: string;
 export declare const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX: string;
+export declare const PYGMALION_REVISION_CATALOG_SUFFIX: string;
 export declare const DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE: string;
 export declare function pygmalionPreviewArtifactPlugin(options?: {
   root?: string;
   artifactFile?: string;
   endpoint?: string;
+  /** Requires `acquireSourceLease`; the catalog is never read without one. */
+  catalogFile?: string;
+  catalogEndpoint?: string;
   disabled?: () => boolean;
   generateArtifact?: (
     request: {
       namespace: string;
       sourceRevision: string;
-      frames?: readonly { id: string; fingerprint?: string }[];
+      frames?: readonly PygmalionPreviewFrameRequest[];
       captureBaseUrl?: string;
     },
     options?: PygmalionPreviewCaptureGeneratorOptions,
@@ -207,13 +241,36 @@ export declare function pygmalionPreviewArtifactPlugin(options?: {
     | { release(): void | Promise<void> }
     | null
     | Promise<{ release(): void | Promise<void> } | null>;
+  /** Holds an exact checkout for catalog reads and the whole artifact capture. */
+  acquireSourceLease?: (
+    sourceRevision: string,
+    label: string,
+  ) =>
+    | {
+        sourceRoot: string;
+        sourceRevision: string;
+        /** Revalidates direct worktrees that cannot be held by a mirror lease. */
+        validate?(): boolean | Promise<boolean>;
+        release(): void | Promise<void>;
+      }
+    | null
+    | Promise<{
+        sourceRoot: string;
+        sourceRevision: string;
+        /** Revalidates direct worktrees that cannot be held by a mirror lease. */
+        validate?(): boolean | Promise<boolean>;
+        release(): void | Promise<void>;
+      } | null>;
+  requestRuntime?: () => void;
+  runtimePrepared?: () => boolean;
+  artifactStoreMaxBytes?: number;
 }): PluginOption;
 export interface PygmalionPreviewCaptureWorkerChannel {
   generateArtifact(
     request: {
       namespace: string;
       sourceRevision: string;
-      frames?: readonly { id: string; fingerprint?: string }[];
+      frames?: readonly PygmalionPreviewFrameRequest[];
       captureBaseUrl?: string;
     },
     options?: PygmalionPreviewCaptureGeneratorOptions,