@pygmalionjs/pygmalion 0.2.39 → 0.2.41

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 "./App-CJz8NrxS.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./App-kzN-1Je6.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

package/node/preview-artifact-plugin.mjs

@@ -85,6 +85,11 @@ function generationAllowed(url) {
   return !['0', 'false', 'no'].includes(raw.trim().toLowerCase());
 }
 
+function resolutionOnly(url) {
+  const raw = url.searchParams.get('resolve');
+  return raw != null && ['1', 'true', 'yes'].includes(raw.trim().toLowerCase());
+}
+
 function requestedFrames(url) {
   const raw = url.searchParams.get('frames');
   if (raw == null) return undefined;
@@ -373,6 +378,15 @@ export function pygmalionPreviewArtifactPlugin({
           return;
         }
         if (wanted !== undefined) {
+          if (resolutionOnly(url)) {
+            const resolution = await artifactStore.resolveFrameSelection(
+              namespace,
+              sourceRevision,
+              wanted,
+            );
+            sendJson(response, 200, { ok: true, ...resolution });
+            return;
+          }
           let picked = await artifactStore.readFrameSelection(
             namespace,
             sourceRevision,

package/node/preview-artifact-store.mjs

@@ -18,6 +18,7 @@ const LOCK_TIMEOUT_MS = 30_000;
 const LOCK_STALE_MS = 120_000;
 const LOCK_POLL_MS = 40;
 const OBJECT_HASH = /^[a-f0-9]{64}$/u;
+const OBJECT_CACHE_MAX_BYTES = 64 * 1024 * 1024;
 
 function sha256(value) {
   return createHash('sha256').update(value).digest('hex');
@@ -182,8 +183,7 @@ function upsertFrame(entries, next) {
       (entry) =>
         entry.id !== next.id ||
         entry.fingerprint !== next.fingerprint ||
-        (next.fingerprint == null &&
-          entry.sourceRevision !== next.sourceRevision),
+        entry.sourceRevision !== next.sourceRevision,
     ),
     next,
   ];
@@ -216,6 +216,34 @@ export function createPreviewArtifactStore({
   const legacyFile = path.resolve(artifactFile);
   const root = path.resolve(storeDirectory);
   let legacyCache = null;
+  const objectCache = new Map();
+  let objectCacheBytes = 0;
+
+  const rememberObject = (hash, artifact, bytes) => {
+    const previous = objectCache.get(hash);
+    if (previous) objectCacheBytes -= previous.bytes;
+    objectCache.delete(hash);
+    objectCache.set(hash, { artifact, bytes });
+    objectCacheBytes += bytes;
+    while (objectCacheBytes > OBJECT_CACHE_MAX_BYTES && objectCache.size > 1) {
+      const oldestHash = objectCache.keys().next().value;
+      const oldest = objectCache.get(oldestHash);
+      objectCache.delete(oldestHash);
+      objectCacheBytes -= oldest?.bytes ?? 0;
+    }
+  };
+
+  const forgetObject = (hash) => {
+    const cached = objectCache.get(hash);
+    if (!cached) return;
+    objectCache.delete(hash);
+    objectCacheBytes -= cached.bytes;
+  };
+
+  const legacyFileSignature = async () => {
+    const stat = await fs.stat(legacyFile);
+    return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(':');
+  };
 
   const namespaceHash = (namespace) => sha256(namespace);
   const manifestPath = (namespace) =>
@@ -242,6 +270,7 @@ export function createPreviewArtifactStore({
     const serialized = JSON.stringify(artifact);
     const hash = sha256(serialized);
     const target = objectPath(hash);
+    rememberObject(hash, artifact, Buffer.byteLength(serialized));
     try {
       await fs.access(target);
       return hash;
@@ -253,11 +282,20 @@ export function createPreviewArtifactStore({
 
   const readObject = async (hash) => {
     if (!OBJECT_HASH.test(hash)) return null;
+    const cached = objectCache.get(hash);
+    if (cached) {
+      objectCache.delete(hash);
+      objectCache.set(hash, cached);
+      return cached.artifact;
+    }
     try {
       const raw = await fs.readFile(objectPath(hash), 'utf8');
       const artifact = JSON.parse(raw);
-      if (sha256(JSON.stringify(artifact)) !== hash) return null;
-      return validateRoutePreviewArtifactBundle(artifact).valid ? artifact : null;
+      const serialized = JSON.stringify(artifact);
+      if (sha256(serialized) !== hash) return null;
+      if (!validateRoutePreviewArtifactBundle(artifact).valid) return null;
+      rememberObject(hash, artifact, Buffer.byteLength(serialized));
+      return artifact;
     } catch {
       return null;
     }
@@ -392,7 +430,10 @@ export function createPreviewArtifactStore({
         await Promise.all(
           [...previousObjectReferences]
             .filter((hash) => !retainedObjectReferences.has(hash))
-            .map((hash) => fs.rm(objectPath(hash), { force: true })),
+            .map(async (hash) => {
+              await fs.rm(objectPath(hash), { force: true });
+              forgetObject(hash);
+            }),
         );
 
         if (materializeLegacy) {
@@ -417,6 +458,7 @@ export function createPreviewArtifactStore({
           if (materialized) {
             await writeJsonAtomic(legacyFile, materialized);
             legacyCache = {
+              signature: await legacyFileSignature(),
               hash: sha256(JSON.stringify(materialized)),
               status: 'valid',
               artifact: materialized,
@@ -430,6 +472,21 @@ export function createPreviewArtifactStore({
   };
 
   const importLegacyArtifact = async () => {
+    let signature;
+    try {
+      signature = await legacyFileSignature();
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        legacyCache = {
+          signature: 'missing',
+          status: 'missing',
+          artifact: null,
+        };
+        return legacyCache;
+      }
+      throw error;
+    }
+    if (legacyCache?.signature === signature) return legacyCache;
     let raw;
     try {
       raw = await fs.readFile(legacyFile, 'utf8');
@@ -441,12 +498,17 @@ export function createPreviewArtifactStore({
     try {
       artifact = JSON.parse(raw);
     } catch {
-      return { status: 'invalid', artifact: null };
+      legacyCache = { signature, status: 'invalid', artifact: null };
+      return legacyCache;
     }
     const hash = sha256(JSON.stringify(artifact));
-    if (legacyCache?.hash === hash) return legacyCache;
     if (!validateRoutePreviewArtifactBundle(artifact).valid) {
-      legacyCache = { hash, status: 'invalid', artifact: null };
+      legacyCache = {
+        signature,
+        hash,
+        status: 'invalid',
+        artifact: null,
+      };
       return legacyCache;
     }
     // The compatibility contract treats this file as one exact snapshot. Frame
@@ -454,7 +516,7 @@ export function createPreviewArtifactStore({
     // idempotent entries below ensure restarting Vite cannot promote this seed
     // above a newer partial capture merely by importing it again.
     await publishArtifact(artifact, { materializeLegacy: false });
-    legacyCache = { hash, status: 'valid', artifact };
+    legacyCache = { signature, hash, status: 'valid', artifact };
     return legacyCache;
   };
 
@@ -484,20 +546,64 @@ export function createPreviewArtifactStore({
     return materializeManifest(manifest);
   };
 
+  const indexFrameCandidates = (manifest, wanted) => {
+    const wantedIds = new Set(wanted.map((request) => request.id));
+    const candidatesById = new Map();
+    for (const entry of manifest?.frames ?? []) {
+      if (!wantedIds.has(entry.id)) continue;
+      const candidates = candidatesById.get(entry.id) ?? [];
+      candidates.push(entry);
+      candidatesById.set(entry.id, candidates);
+    }
+    for (const candidates of candidatesById.values()) {
+      candidates.sort((left, right) => right.generation - left.generation);
+    }
+    return candidatesById;
+  };
+
+  /** Resolves freshness from the compact manifest without loading frame payloads. */
+  const resolveFrameSelection = async (namespace, sourceRevision, wanted) => {
+    const manifest = await readManifest(namespace);
+    const candidatesById = indexFrameCandidates(manifest, wanted);
+    const exact = [];
+    const missing = [];
+    const stale = [];
+    for (const request of wanted) {
+      const candidates = candidatesById.get(request.id) ?? [];
+      if (!candidates.length) {
+        missing.push(request.id);
+        continue;
+      }
+      const current = candidates.some(
+        (entry) =>
+          entry.sourceRevision === sourceRevision &&
+          (request.fingerprint == null ||
+            entry.fingerprint === request.fingerprint),
+      );
+      (current ? exact : stale).push(request.id);
+    }
+    return { exact, missing, stale };
+  };
+
   const readFrameSelection = async (namespace, sourceRevision, wanted) => {
     const manifest = await readManifest(namespace);
     let aggregate = null;
     if (manifest) {
+      // Index once per read. The earlier path filtered the complete manifest for
+      // every wanted frame, which made a storyboard probe O(wanted × entries).
+      const candidatesById = indexFrameCandidates(manifest, wanted);
       for (const request of wanted) {
-        const candidates = manifest.frames
-          .filter((entry) => entry.id === request.id)
-          .sort((a, b) => b.generation - a.generation);
+        const candidates = candidatesById.get(request.id) ?? [];
         const exact = candidates.filter((entry) =>
-          request.fingerprint != null
-            ? entry.fingerprint === request.fingerprint
-            : entry.sourceRevision === sourceRevision,
+          entry.sourceRevision === sourceRevision &&
+          (request.fingerprint == null ||
+            entry.fingerprint === request.fingerprint),
         );
-        const ordered = [...exact, ...candidates.filter((entry) => !exact.includes(entry))];
+        const exactSet = new Set(exact);
+        const ordered = [
+          ...exact,
+          ...candidates.filter((entry) => !exactSet.has(entry)),
+        ];
         for (const entry of ordered) {
           const artifact = await readObject(entry.object);
           if (
@@ -505,7 +611,23 @@ export function createPreviewArtifactStore({
             artifact.namespace === namespace &&
             artifact.frames[request.id]
           ) {
-            aggregate = mergeRoutePreviewArtifactV3(aggregate, artifact);
+            const frame = artifact.frames[request.id];
+            const withProvenance = {
+              ...artifact,
+              frames: {
+                ...artifact.frames,
+                [request.id]: {
+                  ...frame,
+                  ...(entry.sourceRevision == null
+                    ? {}
+                    : { sourceRevision: entry.sourceRevision }),
+                },
+              },
+            };
+            aggregate = mergeRoutePreviewArtifactV3(
+              aggregate,
+              withProvenance,
+            );
             break;
           }
         }
@@ -514,7 +636,7 @@ export function createPreviewArtifactStore({
     return selectRoutePreviewArtifactFrames(
       aggregate ?? emptyBundle(namespace, sourceRevision),
       wanted,
-      { includeStale: true },
+      { includeStale: true, sourceRevision },
     );
   };
 
@@ -526,5 +648,6 @@ export function createPreviewArtifactStore({
     readExactArtifact,
     readFrameSelection,
     readLatestArtifact,
+    resolveFrameSelection,
   };
 }

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,9 +626,9 @@ 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, options = {}) {
   if (!isPlainRecord(bundle) || !isPlainRecord(bundle.frames)) {
@@ -647,7 +651,12 @@ export function selectRoutePreviewArtifactFrames(bundle, wanted, options = {}) {
       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;
@@ -674,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.');
   }
@@ -692,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-environment.mjs

@@ -29,6 +29,31 @@ const MAX_SOURCE_BYTES = 1024 * 1024;
 const MAX_ENVIRONMENT_BYTES = 16 * 1024;
 const MAX_EXECUTION_RESULTS_BYTES = 64 * 1024 * 1024;
 
+function normalizeRoutePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const pathname = value.trim().split(/[?#]/, 1)[0].replace(/\/{2,}/g, '/');
+  const rooted = pathname.startsWith('/') ? pathname : `/${pathname}`;
+  return rooted.length > 1 ? rooted.replace(/\/+$/, '') : rooted;
+}
+
+function routePatternMatches(pattern, concrete) {
+  const normalizedPattern = normalizeRoutePath(pattern);
+  const normalizedConcrete = normalizeRoutePath(concrete);
+  if (!normalizedPattern || !normalizedConcrete) return false;
+  const patternSegments = normalizedPattern.split('/').filter(Boolean);
+  const concreteSegments = normalizedConcrete.split('/').filter(Boolean);
+  let concreteIndex = 0;
+  for (const segment of patternSegments) {
+    if (segment === '*' || segment.startsWith('*')) return true;
+    const concreteSegment = concreteSegments[concreteIndex];
+    if (segment.endsWith('?') && concreteSegment == null) continue;
+    if (concreteSegment == null) return false;
+    if (!segment.startsWith(':') && segment !== concreteSegment) return false;
+    concreteIndex += 1;
+  }
+  return concreteIndex === concreteSegments.length;
+}
+
 function normalizedRelativePath(root, file) {
   return path.relative(root, file).split(path.sep).join('/');
 }
@@ -1151,12 +1176,14 @@ function associateRouteCandidates(manifest, graph, fileDigests = new Map()) {
     };
   });
 
-  const knownRoutes = new Set(routes.map((route) => route.path));
+  const knownRoutes = routes.map((route) => route.path);
+  const targetIsKnown = (target) =>
+    knownRoutes.some((route) => routePatternMatches(route, target));
   const uniqueEdges = [
     ...new Map(
       edges.map((edge) => [
         `${edge.from}:${edge.to}:${edge.kind}:${edge.evidence.sourcePath}:${edge.evidence.line}`,
-        { ...edge, unresolvedTarget: !knownRoutes.has(edge.to) },
+        { ...edge, unresolvedTarget: !targetIsKnown(edge.to) },
       ]),
     ).values(),
   ].sort((a, b) => a.id.localeCompare(b.id));

package/package.json

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

package/storyboard.d.ts

@@ -318,7 +318,7 @@ export interface RoutePreviewArtifactFrameRequest {
 export declare function selectRoutePreviewArtifactFrames(
   bundle: unknown,
   wanted: readonly (RoutePreviewArtifactFrameRequest | string)[],
-  options?: { includeStale?: boolean },
+  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[];
@@ -1204,6 +1206,26 @@ export interface StoryboardGraphEdgeInput {
   label?: string;
 }
 
+export interface StoryboardPathInput {
+  /** Stable author-owned identity used as the edge id prefix. */
+  id: string;
+  /** Ordered screen ids visited by this path. */
+  screenIds: readonly string[];
+  kind?: string;
+  label?: string;
+}
+
+export interface StoryboardDefinition {
+  paths?: readonly StoryboardPathInput[];
+  edges?: readonly StoryboardGraphEdgeInput[];
+  startScreenIds?: readonly string[];
+  nonVisualScenarioIds?: readonly string[];
+}
+
+export declare function createStoryboardPathEdges(
+  paths: readonly StoryboardPathInput[],
+): StoryboardGraphEdgeInput[];
+
 export interface StoryboardGraphBuildOptions {
   screens: readonly DesignScreenCase[];
   assets?: readonly DesignImportAsset[];
@@ -1450,6 +1472,8 @@ export interface StoryboardDiscoveryGraphOptions {
   manifest: StoryboardDiscoveryManifest;
   pages: readonly StoryboardResolvedPage[];
   assets?: readonly DesignImportAsset[];
+  /** Host-authored user journeys layered over source-inferred transitions. */
+  storyboard?: StoryboardDefinition;
 }
 
 export interface StoryboardDiscoveryResult {
@@ -1486,6 +1510,7 @@ export declare function resolveStoryboardScreenCases(
   pages: readonly StoryboardResolvedPage[],
   manifest: StoryboardDiscoveryManifest,
 ): DesignScreenCase[];
+export declare function createStoryboardRouteScenarioId(route: string): string;
 export declare function getStoryboardDiscoveryBaselineEnvironment(
   manifest: StoryboardDiscoveryManifest,
 ): StoryboardEnvironment | undefined;
@@ -1945,6 +1970,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. */
@@ -1989,6 +2016,8 @@ export declare function PygmalionEditor(props: {
   ) => Promise<InspectPreviewResult>;
   /** Check the reverse dependency closure of the changed source file. */
   onInspectImpact?: (componentFiles: string[]) => Promise<InspectImpactResult>;
+  /** Authored screen paths and starts merged with source-discovered navigation. */
+  storyboard?: StoryboardDefinition;
   /** Detect portable browser branches from source before route frames boot. Default true. */
   storyboardDiscovery?: boolean;
   /** Vite endpoint that returns the generated generic storyboard environment manifest. */