@pygmalionjs/pygmalion 0.2.38 → 0.2.40

package/node/route-dependency-digest.mjs

@@ -0,0 +1,62 @@
+function normalizedRoutePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    const pathname = new URL(value.trim(), 'http://pygmalion.invalid').pathname;
+    return `/${pathname.split('/').filter(Boolean).join('/')}`;
+  } catch {
+    return null;
+  }
+}
+
+function matches(pattern, route) {
+  for (let index = 0; index < pattern.length; index += 1) {
+    const segment = pattern[index];
+    if (segment === '*' || (segment.startsWith(':') && segment.endsWith('*'))) {
+      return true;
+    }
+    if (route[index] == null) return false;
+    if (!segment.startsWith(':') && segment !== route[index]) return false;
+  }
+  return route.length === pattern.length;
+}
+
+/** Resolves a concrete route against exact, `:param`, and `*` manifest paths. */
+export function resolvePreviewRouteDependencyDigest(route, entries) {
+  const normalized = normalizedRoutePath(route);
+  if (!normalized || !Array.isArray(entries)) return undefined;
+  const routeSegments = normalized.split('/').filter(Boolean);
+  const candidates = [];
+  for (const [order, entry] of entries.entries()) {
+    if (
+      typeof entry?.path !== 'string' ||
+      typeof entry?.dependencyDigest !== 'string' ||
+      !entry.dependencyDigest
+    ) {
+      continue;
+    }
+    const pattern = normalizedRoutePath(entry.path);
+    if (!pattern) continue;
+    if (pattern === normalized) return entry.dependencyDigest;
+    const segments = pattern.split('/').filter(Boolean);
+    if (!matches(segments, routeSegments)) continue;
+    candidates.push({
+      digest: entry.dependencyDigest,
+      literalCount: segments.filter(
+        (segment) => !segment.startsWith(':') && segment !== '*',
+      ).length,
+      wildcardCount: segments.filter(
+        (segment) => segment === '*' || segment.endsWith('*'),
+      ).length,
+      length: segments.length,
+      order,
+    });
+  }
+  candidates.sort(
+    (left, right) =>
+      right.literalCount - left.literalCount ||
+      left.wildcardCount - right.wildcardCount ||
+      right.length - left.length ||
+      right.order - left.order,
+  );
+  return candidates[0]?.digest;
+}

package/node/route-preview-artifact-v3.mjs

@@ -398,9 +398,9 @@ export function createRoutePreviewArtifactV3(input) {
       {
         status: rawCapture.status,
         viewport: copyViewport(rawCapture.viewport),
-        // What this frame was captured from. A consumer compares its own
-        // fingerprint against this one, so a frame survives a revision bump
-        // whose files it does not depend on.
+        // Content identity within the source revision that captured this frame.
+        // Store selections preserve the revision as per-frame provenance when
+        // frames from separate revisions share one response bundle.
         ...(rawCapture.fingerprint == null
           ? {}
           : { fingerprint: String(rawCapture.fingerprint) }),
@@ -490,6 +490,10 @@ export function validateRoutePreviewArtifactV3(bundle) {
       errors.push(`Frame "${frameId}" fingerprint is invalid.`);
       continue;
     }
+    if (!validOptionalIdentifier(rawFrame.sourceRevision)) {
+      errors.push(`Frame "${frameId}" source revision is invalid.`);
+      continue;
+    }
     const diagnostics = rawFrame.diagnostics;
     if (
       !Array.isArray(diagnostics) ||
@@ -622,11 +626,11 @@ function withFrames(bundle, frames) {
 /**
  * Picks the frames a consumer asked for and reports what it must still capture.
  *
- * A frame is usable when it exists and its stored fingerprint matches the
- * requested one. Requests without a fingerprint accept whatever is stored, which
- * keeps the whole-bundle callers of earlier versions working.
+ * A frame is usable when it exists and its stored revision and fingerprint match
+ * the requested provenance. Callers that omit either constraint retain the
+ * looser compatibility behavior of earlier versions.
  */
-export function selectRoutePreviewArtifactFrames(bundle, wanted) {
+export function selectRoutePreviewArtifactFrames(bundle, wanted, options = {}) {
   if (!isPlainRecord(bundle) || !isPlainRecord(bundle.frames)) {
     throw new TypeError('Route preview artifact is invalid.');
   }
@@ -647,8 +651,14 @@ export function selectRoutePreviewArtifactFrames(bundle, wanted) {
       continue;
     }
     const fingerprint = isPlainRecord(request) ? request.fingerprint : undefined;
-    if (fingerprint != null && frame.fingerprint !== fingerprint) {
+    const frameSourceRevision = frame.sourceRevision ?? bundle.sourceRevision;
+    if (
+      (options.sourceRevision != null &&
+        frameSourceRevision !== options.sourceRevision) ||
+      (fingerprint != null && frame.fingerprint !== fingerprint)
+    ) {
       stale.push(id);
+      if (options.includeStale === true) frames[id] = frame;
       continue;
     }
     frames[id] = frame;
@@ -673,7 +683,23 @@ export function mergeRoutePreviewArtifactV3(base, incoming) {
   if (base.namespace !== incoming.namespace) {
     throw new TypeError('Route preview artifacts belong to different namespaces.');
   }
-  const frames = { ...base.frames, ...incoming.frames };
+  const mixedRevisions = base.sourceRevision !== incoming.sourceRevision;
+  const preserveRevision = (frames, sourceRevision) =>
+    Object.fromEntries(
+      Object.entries(frames).map(([id, frame]) => [
+        id,
+        mixedRevisions &&
+        isPlainRecord(frame) &&
+        frame.sourceRevision == null &&
+        sourceRevision != null
+          ? { ...frame, sourceRevision }
+          : frame,
+      ]),
+    );
+  const frames = {
+    ...preserveRevision(base.frames, base.sourceRevision),
+    ...preserveRevision(incoming.frames, incoming.sourceRevision),
+  };
   if (Object.keys(frames).length > ROUTE_PREVIEW_ARTIFACT_V3_LIMITS.frameCount) {
     throw new RangeError('Route preview artifact has too many frames.');
   }
@@ -691,13 +717,15 @@ export function mergeRoutePreviewArtifactV3(base, incoming) {
   return withFrames(
     {
       namespace: incoming.namespace,
-      // The newest capture names the bundle, but a frame keeps the fingerprint it
-      // was captured with, so the two no longer have to agree.
-      ...(incoming.sourceRevision == null
-        ? base.sourceRevision == null
-          ? {}
-          : { sourceRevision: base.sourceRevision }
-        : { sourceRevision: incoming.sourceRevision }),
+      // A mixed bundle has no honest bundle-wide revision. Its frames carry
+      // their own provenance instead, including known revisions on both sides.
+      ...(mixedRevisions
+        ? {}
+        : incoming.sourceRevision == null
+          ? base.sourceRevision == null
+            ? {}
+            : { sourceRevision: base.sourceRevision }
+          : { sourceRevision: incoming.sourceRevision }),
       assets,
     },
     frames,

package/node/storyboard.mjs

@@ -42,9 +42,11 @@ export {
 export {
   ROUTE_PREVIEW_ARTIFACT_V3_LIMITS,
   createRoutePreviewArtifactV3,
+  mergeRoutePreviewArtifactV3,
   reconstructRoutePreviewArtifactScreenshotV3,
   reconstructRoutePreviewArtifactSnapshotV3,
   reconstructRoutePreviewArtifactSnapshotsV3,
+  selectRoutePreviewArtifactFrames,
   validateRoutePreviewArtifactBundle,
   validateRoutePreviewArtifactV3,
 } from './route-preview-artifact-v3.mjs';

package/node/vite.mjs

@@ -55,12 +55,15 @@ import {
 import {
   ROUTE_PREVIEW_ARTIFACT_V3_LIMITS,
   createRoutePreviewArtifactV3,
+  mergeRoutePreviewArtifactV3,
   reconstructRoutePreviewArtifactScreenshotV3,
   reconstructRoutePreviewArtifactSnapshotV3,
   reconstructRoutePreviewArtifactSnapshotsV3,
+  selectRoutePreviewArtifactFrames,
   validateRoutePreviewArtifactBundle,
   validateRoutePreviewArtifactV3,
 } from './route-preview-artifact-v3.mjs';
+import { resolvePreviewRouteDependencyDigest } from './route-dependency-digest.mjs';
 import {
   DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
@@ -366,9 +369,12 @@ export {
   validateRoutePreviewArtifactV2,
   ROUTE_PREVIEW_ARTIFACT_V3_LIMITS,
   createRoutePreviewArtifactV3,
+  mergeRoutePreviewArtifactV3,
   reconstructRoutePreviewArtifactScreenshotV3,
   reconstructRoutePreviewArtifactSnapshotV3,
   reconstructRoutePreviewArtifactSnapshotsV3,
+  selectRoutePreviewArtifactFrames,
+  resolvePreviewRouteDependencyDigest,
   validateRoutePreviewArtifactBundle,
   validateRoutePreviewArtifactV3,
   DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.2.38",
+  "version": "0.2.40",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -37,9 +37,12 @@
     "node/dev-view.vite.mjs",
     "node/inspect-plugin.mjs",
     "node/preview-artifact-plugin.mjs",
+    "node/preview-artifact-store.mjs",
+    "node/preview-vite-cache.mjs",
     "node/qa-capture-plugin.mjs",
     "node/route-preview-artifact-v2.mjs",
     "node/route-preview-artifact-v3.mjs",
+    "node/route-dependency-digest.mjs",
     "node/source-revision.mjs",
     "node/source-diff.mjs",
     "node/source-graph.mjs",

package/storyboard.d.ts

@@ -318,6 +318,7 @@ export interface RoutePreviewArtifactFrameRequest {
 export declare function selectRoutePreviewArtifactFrames(
   bundle: unknown,
   wanted: readonly (RoutePreviewArtifactFrameRequest | string)[],
+  options?: { includeStale?: boolean; sourceRevision?: string },
 ): {
   bundle: RoutePreviewArtifactBundleV3;
   missing: string[];

package/types.d.ts

@@ -994,6 +994,8 @@ export interface RoutePreviewArtifactV3ScreenshotAsset {
 export interface RoutePreviewArtifactV3Frame {
   readonly status: RoutePreviewArtifactV3Status;
   readonly viewport: RoutePreviewArtifactV3Viewport;
+  readonly sourceRevision?: string;
+  readonly fingerprint?: string;
   readonly snapshot?: RoutePreviewArtifactBundleV2['frames'][string];
   readonly screenshot?: RoutePreviewArtifactV3ScreenshotReference;
   readonly diagnostics: readonly RoutePreviewArtifactV3Diagnostic[];
@@ -1945,6 +1947,8 @@ export declare function PygmalionEditor(props: {
   registry?: ComponentRegistry;
   tokens?: TokenDef[];
   initialPages?: InitialPageDef[];
+  /** Canvas shown on first mount. Useful when an earlier catalog canvas is expensive to render. */
+  initialCanvas?: string;
   /** Explicit external-design to registered-code component mappings. */
   componentConnections?: readonly DesignComponentConnectionDef[];
   /** Named frame widths the application supports — rendered as one-click buttons beside the W/H boxes. */

package/vite.d.ts

@@ -76,6 +76,7 @@ export interface PygmalionPreviewConfig {
   generateArtifact?: (request: {
     namespace: string;
     sourceRevision: string;
+    frames?: readonly { id: string; fingerprint?: string }[];
     captureBaseUrl?: string;
   }) => unknown | Promise<unknown>;
 }
@@ -158,8 +159,15 @@ export declare function pygmalionPreviewArtifactPlugin(options?: {
   generateArtifact?: (request: {
     namespace: string;
     sourceRevision: string;
+    frames?: readonly { id: string; fingerprint?: string }[];
     captureBaseUrl?: string;
   }) => unknown | Promise<unknown>;
+  acquireLease?: (
+    reason: string,
+  ) =>
+    | { release(): void | Promise<void> }
+    | null
+    | Promise<{ release(): void | Promise<void> } | null>;
 }): PluginOption;
 export interface PygmalionGitSourceState {
   commit: string;
@@ -511,6 +519,10 @@ export {
   validateRoutePreviewArtifactBundle,
   validateRoutePreviewArtifactV3,
 } from './storyboard';
+export declare function resolvePreviewRouteDependencyDigest(
+  route: string,
+  entries: readonly { path?: string; dependencyDigest?: string }[],
+): string | undefined;
 export type {
   RoutePreviewArtifactBundleV3,
   RoutePreviewArtifactFrameRequest,