@pygmalionjs/pygmalion 0.5.15 → 0.5.17

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-BR5CBAD3.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-CZOpvN6z.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

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

@@ -87,6 +87,25 @@ export interface DesignChangeResult {
 export declare function setAppOrigin(origin: string): void;
 export declare function getAppOrigin(): string;
 export declare function subscribeAppOrigin(listener: () => void): () => void;
+export declare function setArtifactOrigin(origin: string): void;
+/**
+ * Origin a captured snapshot resolves its relative assets against.
+ *
+ * This is not the same question as "where does the live screen run". A capture is
+ * already rendered — it needs somewhere to fetch the images and fonts its markup
+ * still points at — while a live frame needs the checkout of a specific revision.
+ * Answering both with one value tied the catalog to a checkout that takes minutes
+ * to build, so opening the editor showed a spinner instead of the frames sitting
+ * on disk.
+ *
+ * The order is most-accurate-first: an origin the host declared, then the live
+ * one once a runtime exists, then the editor's own — which serves the same
+ * application and lets the catalog paint immediately. Assets it cannot resolve
+ * are the ones the working tree no longer has; the live origin replaces them the
+ * moment it comes up, because these readers re-run when it does.
+ */
+export declare function getArtifactOrigin(): string;
+export declare function subscribeArtifactOrigin(listener: () => void): () => void;
 /** Baseline code version of the preview (dev SHA, etc.). When a change is made, a new static screen cache of the same URL is also created. */
 export declare function setPreviewRevision(revision: string): void;
 export declare function getPreviewRevision(): string;

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

@@ -77,7 +77,7 @@ export type RoutePreviewArtifactResolution = {
     status: 'generating';
 } | {
     status: 'error';
-    reason: 'unavailable' | 'rejected';
+    reason: 'unavailable' | 'rejected' | 'not-prepared';
     message: string;
 } | {
     status: 'exact';

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

@@ -30,6 +30,7 @@ export { createDesignComponentCatalog, createDesignComponentVariantMatrix, creat
 export type { DesignCatalogBuild, DesignCatalogFrame, DesignCatalogItem, DesignCatalogKind, DesignCatalogPageDescriptor, DesignComponentCatalogOptions, DesignComponentVariantMatrix, DesignGalleryCatalogOptions, PygmalionCatalogDocumentProps, PygmalionCatalogMatrixProps, PygmalionCatalogSectionProps, } from './editor/catalog';
 export { setTokens, applyTokenOverride, resetTokenOverrides, } from './editor/tokens';
 export { setAppOrigin as setPygmalionAppOrigin } from './editor/host';
+export { setArtifactOrigin as setPygmalionArtifactOrigin } from './editor/host';
 export { setPreviewRevision as setPygmalionPreviewRevision } from './editor/host';
 export { clearRoutePreviewSnapshots as clearPygmalionPreviewCache, recommendedRoutePreviewConcurrency as getRecommendedPygmalionPreviewConcurrency, setRoutePreviewConcurrency as setPygmalionPreviewConcurrency, } from './editor/routePreview';
 export type { RoutePreviewArtifactBundle } from './editor/routePreview';
@@ -100,6 +101,25 @@ export declare const __debug: {
         } | null;
         hasShadowArtifact: boolean;
         hasSnapshot: boolean;
+        keys: {
+            which: "active" | "inactive";
+            sameAsDebugKey: boolean;
+            hasShadowArtifact: boolean;
+            hasSnapshot: boolean;
+        }[];
+        isActivePage: boolean;
+        snapshotShape: {
+            length: number;
+            bodyLength: number;
+            elements: number;
+            basePlaceholderLeft: boolean;
+            baseHref: string | null;
+            head: string;
+        } | null;
+        previewIdentityReady: boolean;
+        seedRevision: string;
+        hostRevision: string;
+        staticSurface: import("./editor/routePreviewStatus").StaticRoutePreviewSurface;
         tier: import("./editor/frameLod").FrameLifecycleTier;
         magnified: boolean;
         promotion: {

package/node/dev-mirror.mjs

@@ -29,6 +29,9 @@ const LEASE_HEARTBEAT_MS = 2_000;
 // costs a checkout and a dependency install, so the reaper errs toward keeping.
 const DEFAULT_MIRROR_GRACE_MS = 6 * 60 * 60 * 1_000;
 const LEASE_WAIT_TIMEOUT_MS = 180_000;
+// A serving editor holds this for its whole session. It marks the checkout as in
+// use for the reaper; it must never stand in the way of a sync.
+const SERVE_LEASE_LABEL = 'serve';
 
 export function resolveDevMirrorInventoryOutputRoot(inventory, mirrorAppRoot) {
   return path.resolve(inventory?.outputRoot ?? mirrorAppRoot);
@@ -469,10 +472,25 @@ export async function acquireDevMirrorLease({ repoRoot, mirrorRoot, label = 'cap
   };
 }
 
-async function waitForLeasesToClear(repoRoot, mirrorRoot, timeoutMs = LEASE_WAIT_TIMEOUT_MS) {
-  const deadline = Date.now() + timeoutMs;
+/**
+ * Leases that a sync must wait out.
+ *
+ * A reader lease is short: a capture holds one while it walks the checkout, and
+ * moving the files under it would corrupt what it is reading. A serve lease is
+ * the opposite — it lasts as long as an editor is open, and it exists so a
+ * reaper can tell a live checkout from an abandoned one. Treating the two the
+ * same wedged the second editor on a ref: it waited three minutes for a lease
+ * that, by design, never clears, and then reported the mirror as held.
+ */
+export function leasesBlockingSync(leases) {
+  return leases.filter((lease) => lease.label !== SERVE_LEASE_LABEL);
+}
+
+async function waitForLeasesToClear(repoRoot, mirrorRoot, timeoutMs) {
+  const limit = Number.isFinite(timeoutMs) ? timeoutMs : LEASE_WAIT_TIMEOUT_MS;
+  const deadline = Date.now() + limit;
   while (true) {
-    const held = await freshLeases(repoRoot, mirrorRoot);
+    const held = leasesBlockingSync(await freshLeases(repoRoot, mirrorRoot));
     if (held.length === 0) return;
     if (Date.now() >= deadline) {
       const labels = [...new Set(held.map((lease) => lease.label))].join(', ');
@@ -844,7 +862,7 @@ export function pygmalionDevMirrorPlugin(options) {
     const lease = await acquireDevMirrorLease({
       repoRoot,
       mirrorRoot: activeRoot,
-      label: 'serve',
+      label: SERVE_LEASE_LABEL,
     }).catch(() => null);
     if (lease) serveLease = { mirrorRoot: activeRoot, lease };
   };
@@ -854,6 +872,9 @@ export function pygmalionDevMirrorPlugin(options) {
     await held?.lease.release().catch(() => undefined);
   };
 
+  // Whether anything has asked for the checkout yet. The runtime is built once,
+  // on first demand, and every later demand joins the same work.
+  let runtimeRequested = false;
   let previewChild = null;
   let previewPort = null;
   let syncPromise = null;
@@ -1117,8 +1138,9 @@ export function pygmalionDevMirrorPlugin(options) {
       let warning = null;
       try {
         return await withSharedSyncLock(async () => {
-          // A capture reading this checkout must finish before it moves.
-          await waitForLeasesToClear(repoRoot, mirrorRoot);
+          // A capture reading this checkout must finish before it moves. A serving
+          // editor is not that kind of holder — see leasesBlockingSync.
+          await waitForLeasesToClear(repoRoot, mirrorRoot, options.leaseWaitTimeoutMs);
           const mirrorState = await syncDevMirrorWorktree({
             repoRoot,
             mirrorRoot,
@@ -1195,14 +1217,27 @@ export function pygmalionDevMirrorPlugin(options) {
       process.once('exit', () => {
         previewChild?.kill('SIGTERM');
       });
-      // Synchronizes once when the editor server runs. Screen mount and manual refresh requests reuse the same Promise.
-      void syncMirror().then(() =>
-        reapDevMirrorWorktrees({
-          repoRoot,
-          mirrorBaseRoot,
-          keep: [mirrorRoot],
-        })
-          .then(({ removed }) => {
+      // Nothing is prepared until something asks for it.
+      //
+      // Opening the editor used to build the checkout: fetch, worktree, install,
+      // inventory — minutes before the first pixel, on every start, even when all
+      // anyone did was look at the catalog. The captured frames are already on
+      // disk and belong to the consuming app, so browsing needs none of it.
+      //
+      // What genuinely needs the checkout asks for it: a refresh or a revision
+      // switch (below), and any request for the preview origin — the live frame,
+      // its assets, a capture. Those requests kick the work off and answer
+      // "preparing" until it lands, which is what they already did while a
+      // start-time sync was in flight.
+      const startRuntime = () => {
+        if (runtimeRequested) return;
+        runtimeRequested = true;
+        void syncMirror()
+          .then(() =>
+            reapDevMirrorWorktrees({ repoRoot, mirrorBaseRoot, keep: [mirrorRoot] }),
+          )
+          .then((result) => {
+            const removed = result?.removed ?? [];
             if (removed.length > 0) {
               console.log(
                 `[pygmalion] released ${removed.length} unused dev screen checkout(s): ${removed
@@ -1211,8 +1246,8 @@ export function pygmalionDevMirrorPlugin(options) {
               );
             }
           })
-          .catch(() => undefined),
-      );
+          .catch(() => undefined);
+      };
 
       server.middlewares.use(async (req, res, next) => {
         const url = new URL(req.url ?? '/', 'http://localhost');
@@ -1249,6 +1284,10 @@ export function pygmalionDevMirrorPlugin(options) {
           }
           let nextStatus;
           try {
+            // An explicit refresh is a demand like any other — mark the runtime as
+            // started so a later preview request joins this work instead of
+            // scheduling a second one.
+            runtimeRequested = true;
             nextStatus = await syncMirror(requestedRef);
           } catch (error) {
             json(res, 400, {
@@ -1265,7 +1304,14 @@ export function pygmalionDevMirrorPlugin(options) {
           // no longer matches the revision this origin is named after.
           const current = await verifiedStatus();
           if (current.state !== 'ready' || previewPort == null) {
-            json(res, 503, { ok: false, error: current.error ?? 'Preparing the dev screen' });
+            // This is the first thing that actually needs the checkout, so it is
+            // the thing that starts it.
+            startRuntime();
+            json(res, 503, {
+              ok: false,
+              error: current.error ?? 'Preparing the dev screen',
+              preparing: true,
+            });
             return;
           }
           proxyRequest(req, res, previewPort, prefix);

package/node/preview-artifact-plugin.mjs

@@ -207,6 +207,43 @@ export function pygmalionPreviewArtifactPlugin({
     return current;
   }
 
+  /**
+   * Answers a generation failure as what it is.
+   *
+   * A defective generator is a 500 the consumer must surface. A capture that
+   * could not run is a 503 it should wait out — the frame keeps whatever it has
+   * and says "not prepared yet" instead of painting a red failure over a screen
+   * whose only problem is that no runtime was asked for.
+   */
+  function sendGenerationFailure(response, error) {
+    if (error?.pygmalionBadGeneratorOutput) {
+      sendJson(response, 500, { ok: false, error: 'artifact_generation_failed' });
+      return;
+    }
+    sendJson(response, 503, {
+      ok: false,
+      error: 'artifact_generation_unavailable',
+      retryable: true,
+      details: [
+        error instanceof Error ? error.message.split('\n')[0] : String(error),
+      ],
+    });
+  }
+
+  /**
+   * A generator that ran and produced the wrong thing.
+   *
+   * Two very different failures reach the same catch: the capture could not run
+   * at all — the editor no longer prepares a checkout just because it started,
+   * so asking for a frame before anyone asked for the runtime is ordinary — and
+   * the capture ran but handed back something invalid or belonging to another
+   * revision. Only the second is a defect. Reporting both as one made the first
+   * shout, and quieting both would have hushed the second.
+   */
+  function badGeneratorOutput(message) {
+    return Object.assign(new Error(message), { pygmalionBadGeneratorOutput: true });
+  }
+
   async function withCaptureLease(sourceRevision, task) {
     // A capture reads the dev mirror for minutes. Hold a lease for that whole
     // window so a sync on another server cannot switch the checkout the frames
@@ -241,10 +278,10 @@ export function pygmalionPreviewArtifactPlugin({
         );
         const validation = validateRoutePreviewArtifactBundle(generated);
         if (!validation.valid) {
-          throw new Error('Generated preview artifact is invalid.');
+          throw badGeneratorOutput('Generated preview artifact is invalid.');
         }
         if (!exactArtifact(generated, namespace, sourceRevision)) {
-          throw new Error(
+          throw badGeneratorOutput(
             'Generated preview artifact identity does not match the request.',
           );
         }
@@ -426,11 +463,8 @@ export function pygmalionPreviewArtifactPlugin({
                 sourceRevision,
                 wanted,
               );
-            } catch {
-              sendJson(response, 500, {
-                ok: false,
-                error: 'artifact_generation_failed',
-              });
+            } catch (error) {
+              sendGenerationFailure(response, error);
               return;
             }
           }
@@ -458,11 +492,8 @@ export function pygmalionPreviewArtifactPlugin({
               sourceRevision,
               captureBaseUrl,
             );
-          } catch {
-            sendJson(response, 500, {
-              ok: false,
-              error: 'artifact_generation_failed',
-            });
+          } catch (error) {
+            sendGenerationFailure(response, error);
             return;
           }
         }
@@ -498,11 +529,8 @@ export function pygmalionPreviewArtifactPlugin({
                 sourceRevision,
                 captureBaseUrl,
               );
-            } catch {
-              sendJson(response, 500, {
-                ok: false,
-                error: 'artifact_generation_failed',
-              });
+            } catch (error) {
+              sendGenerationFailure(response, error);
               return;
             }
           } else {

package/package.json

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