@pygmalionjs/pygmalion 0.2.19 → 0.2.21

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

@@ -27,6 +27,7 @@ export const ROUTE_PREVIEW_ARTIFACT_V3_LIMITS = Object.freeze({
   diagnosticCountPerFrame: 256,
   identifierLength: 512,
   tokenLength: 128,
+  fingerprintLength: 256,
   selectorLength: 4_096,
   labelLength: 1_024,
   messageLength: 4_096,
@@ -65,6 +66,23 @@ function validOptionalIdentifier(value) {
   return value == null || validIdentifier(value);
 }
 
+/**
+ * A frame fingerprint is opaque to this layer: the consumer decides what a frame
+ * depends on. Only shape is enforced, so a hash, a revision, or a composite key
+ * all pass, and none of them can smuggle in a record key.
+ */
+function validFingerprint(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= ROUTE_PREVIEW_ARTIFACT_V3_LIMITS.fingerprintLength &&
+    value === value.trim() &&
+    // Hyphens and colons are ordinary in a hash or a composite key, so only
+    // whitespace and control characters are refused.
+    !/[\s\u0000-\u001f\u007f]/u.test(value)
+  );
+}
+
 function validViewport(value) {
   return (
     isPlainRecord(value) &&
@@ -380,6 +398,12 @@ 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.
+        ...(rawCapture.fingerprint == null
+          ? {}
+          : { fingerprint: String(rawCapture.fingerprint) }),
         ...(compact.frames[frameId] == null
           ? {}
           : { snapshot: compact.frames[frameId] }),
@@ -459,6 +483,13 @@ export function validateRoutePreviewArtifactV3(bundle) {
       errors.push(`Frame "${frameId}" status or viewport is invalid.`);
       continue;
     }
+    if (
+      rawFrame.fingerprint !== undefined &&
+      !validFingerprint(rawFrame.fingerprint)
+    ) {
+      errors.push(`Frame "${frameId}" fingerprint is invalid.`);
+      continue;
+    }
     const diagnostics = rawFrame.diagnostics;
     if (
       !Array.isArray(diagnostics) ||
@@ -543,6 +574,136 @@ export function validateRoutePreviewArtifactBundle(bundle) {
     : validateRoutePreviewArtifactV2(bundle);
 }
 
+/**
+ * Assets a set of frames still needs. A frame lists its head and stylesheet
+ * assets by hash, so a subset or a merge can drop what nothing references
+ * instead of carrying every asset the bundle ever held.
+ */
+function referencedAssets(frames) {
+  const head = new Set();
+  const stylesheets = new Set();
+  const screenshots = new Set();
+  for (const frame of Object.values(frames)) {
+    if (!isPlainRecord(frame)) continue;
+    for (const reference of frame.snapshot?.head ?? []) {
+      if (!isPlainRecord(reference) || typeof reference.hash !== 'string') continue;
+      (reference.kind === 'stylesheet' ? stylesheets : head).add(reference.hash);
+    }
+    if (isPlainRecord(frame.screenshot) && typeof frame.screenshot.hash === 'string') {
+      screenshots.add(frame.screenshot.hash);
+    }
+  }
+  return { head, stylesheets, screenshots };
+}
+
+function keepAssets(record, keys) {
+  const kept = {};
+  for (const key of Object.keys(record ?? {}).sort()) {
+    if (keys.has(key)) kept[key] = record[key];
+  }
+  return kept;
+}
+
+function withFrames(bundle, frames) {
+  const used = referencedAssets(frames);
+  return {
+    version: 3,
+    namespace: bundle.namespace,
+    ...(bundle.sourceRevision == null ? {} : { sourceRevision: bundle.sourceRevision }),
+    assets: {
+      head: keepAssets(bundle.assets?.head, used.head),
+      stylesheets: keepAssets(bundle.assets?.stylesheets, used.stylesheets),
+      screenshots: keepAssets(bundle.assets?.screenshots, used.screenshots),
+    },
+    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.
+ */
+export function selectRoutePreviewArtifactFrames(bundle, wanted) {
+  if (!isPlainRecord(bundle) || !isPlainRecord(bundle.frames)) {
+    throw new TypeError('Route preview artifact is invalid.');
+  }
+  if (!Array.isArray(wanted)) {
+    throw new TypeError('Wanted frames must be an array.');
+  }
+  const frames = {};
+  const missing = [];
+  const stale = [];
+  for (const request of wanted) {
+    const id = isPlainRecord(request) ? request.id : request;
+    if (typeof id !== 'string' || !id) {
+      throw new TypeError('Wanted frame id must be a non-empty string.');
+    }
+    const frame = Object.hasOwn(bundle.frames, id) ? bundle.frames[id] : null;
+    if (!isPlainRecord(frame)) {
+      missing.push(id);
+      continue;
+    }
+    const fingerprint = isPlainRecord(request) ? request.fingerprint : undefined;
+    if (fingerprint != null && frame.fingerprint !== fingerprint) {
+      stale.push(id);
+      continue;
+    }
+    frames[id] = frame;
+  }
+  return { bundle: withFrames(bundle, frames), missing, stale };
+}
+
+/**
+ * Folds freshly captured frames into a stored bundle.
+ *
+ * Publishing per frame is what makes a capture proportional to what changed: one
+ * screen can be replaced without re-rendering the other seventy.
+ */
+export function mergeRoutePreviewArtifactV3(base, incoming) {
+  if (!isPlainRecord(incoming) || !isPlainRecord(incoming.frames)) {
+    throw new TypeError('Incoming route preview artifact is invalid.');
+  }
+  if (base == null) return withFrames(incoming, { ...incoming.frames });
+  if (!isPlainRecord(base) || !isPlainRecord(base.frames)) {
+    throw new TypeError('Stored route preview artifact is invalid.');
+  }
+  if (base.namespace !== incoming.namespace) {
+    throw new TypeError('Route preview artifacts belong to different namespaces.');
+  }
+  const frames = { ...base.frames, ...incoming.frames };
+  if (Object.keys(frames).length > ROUTE_PREVIEW_ARTIFACT_V3_LIMITS.frameCount) {
+    throw new RangeError('Route preview artifact has too many frames.');
+  }
+  const assets = {
+    head: { ...(base.assets?.head ?? {}), ...(incoming.assets?.head ?? {}) },
+    stylesheets: {
+      ...(base.assets?.stylesheets ?? {}),
+      ...(incoming.assets?.stylesheets ?? {}),
+    },
+    screenshots: {
+      ...(base.assets?.screenshots ?? {}),
+      ...(incoming.assets?.screenshots ?? {}),
+    },
+  };
+  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 }),
+      assets,
+    },
+    frames,
+  );
+}
+
 export function reconstructRoutePreviewArtifactSnapshotV3(bundle, frameId) {
   const report = validateRoutePreviewArtifactV3(bundle);
   if (!report.valid) {

package/node/vite.mjs

@@ -210,6 +210,10 @@ export function createPygmalionVitePlugins(config) {
     }),
   ];
 
+  // Assigned below when the mirror plugin is built. The artifact plugin resolves
+  // it lazily because a capture starts long after the plugin list is assembled.
+  let devMirror = null;
+
   if (project.preview.artifactFile || project.preview.generateArtifact) {
     plugins.push(
       pygmalionPreviewArtifactPlugin({
@@ -217,6 +221,7 @@ export function createPygmalionVitePlugins(config) {
         artifactFile: project.preview.artifactFile,
         endpoint: project.preview.artifactEndpoint,
         generateArtifact: project.preview.generateArtifact,
+        acquireLease: (label) => devMirror?.acquireLease(label) ?? null,
       }),
     );
   }
@@ -253,8 +258,7 @@ export function createPygmalionVitePlugins(config) {
   }
 
   if (project.mirror !== false) {
-    plugins.push(
-      pygmalionDevMirrorPlugin({
+    const mirrorPlugin = pygmalionDevMirrorPlugin({
         editorRoot: project.editorRoot,
         projectRoot: project.projectRoot,
         appDirectory: project.appDirectory,
@@ -280,8 +284,9 @@ export function createPygmalionVitePlugins(config) {
           PYGMALION_DEV_CONTROL,
           'mirror.control',
         ),
-      }),
-    );
+    });
+    devMirror = mirrorPlugin.pygmalion ?? null;
+    plugins.push(mirrorPlugin);
   }
 
   if (project.sessions !== false) {

package/package.json

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

package/storyboard.d.ts

@@ -225,6 +225,8 @@ export interface RoutePreviewArtifactV3Capture {
     bytes: Uint8Array;
   };
   diagnostics?: readonly StoryboardCaptureDiagnostic[];
+  /** What this frame was captured from, compared per frame instead of per bundle. */
+  fingerprint?: string;
 }
 
 export interface RoutePreviewArtifactBundleV3 {
@@ -258,6 +260,22 @@ export declare function createRoutePreviewArtifactV3(input: {
   sourceRevision?: string;
   captures: Record<string, RoutePreviewArtifactV3Capture>;
 }): RoutePreviewArtifactBundleV3;
+export interface RoutePreviewArtifactFrameRequest {
+  id: string;
+  fingerprint?: string;
+}
+export declare function selectRoutePreviewArtifactFrames(
+  bundle: unknown,
+  wanted: readonly (RoutePreviewArtifactFrameRequest | string)[],
+): {
+  bundle: RoutePreviewArtifactBundleV3;
+  missing: string[];
+  stale: string[];
+};
+export declare function mergeRoutePreviewArtifactV3(
+  base: unknown,
+  incoming: unknown,
+): RoutePreviewArtifactBundleV3;
 export declare function validateRoutePreviewArtifactV3(bundle: unknown): {
   valid: boolean;
   errors: string[];

package/types.d.ts

@@ -161,6 +161,17 @@ export interface TokenDef {
   group?: string;
 }
 
+export interface ViewportPresetDef {
+  /** Button text. The panel column is narrow, so keep it to a few characters. */
+  label: string;
+  /** Frame width in CSS pixels. */
+  width: number;
+  /** Frame height. Omit to resize width only and leave the current height alone. */
+  height?: number;
+  /** Tooltip text. Defaults to the dimensions. */
+  description?: string;
+}
+
 export const DESIGN_IMPORT_KINDS: readonly [
   'icons',
   'design-tokens',
@@ -623,6 +634,12 @@ export declare function setComponentRegistry(r: ComponentRegistry): void;
 
 export declare function setTokens(t: TokenDef[]): void;
 
+/** Declares the frame widths the panel offers. A malformed entry throws at mount. */
+export declare function setViewportPresets(
+  presets: readonly ViewportPresetDef[],
+): void;
+export declare function getViewportPresets(): ViewportPresetDef[];
+
 /** Updates the standard route of the running route iframe. The existing editing status is maintained. */
 export declare function setPygmalionAppOrigin(origin: string): void;
 /** Update the static screen cache when a preview of the same URL points to a new code version. */
@@ -806,9 +823,16 @@ export interface PreviewArtifactExpectation {
   sourceRevision: string;
 }
 
+export interface PreviewArtifactFrameRequest {
+  id: string;
+  fingerprint?: string;
+}
+
 export interface PreviewArtifactTransportRequest extends PreviewArtifactExpectation {
   signal?: AbortSignal;
   captureBaseUrl?: string;
+  /** Frames to fetch. Omitted asks for the whole bundle, as earlier versions did. */
+  frames?: readonly PreviewArtifactFrameRequest[];
 }
 
 export type PreviewArtifactTransport = (
@@ -872,6 +896,10 @@ export type PreviewArtifactBootstrapResult =
 export declare function createPreviewRecipeFingerprint(
   recipes: readonly PreviewRecipeIdentity[],
 ): string;
+export declare function createPreviewFrameFingerprint(
+  screen: StoryboardCaptureRecipeInput & { id?: string },
+  options?: { dependencyDigest?: string },
+): string;
 export declare function createPreviewCacheNamespace(
   options: PreviewCacheNamespaceOptions,
 ): string;
@@ -1620,6 +1648,8 @@ export declare function PygmalionEditor(props: {
   registry?: ComponentRegistry;
   tokens?: TokenDef[];
   initialPages?: InitialPageDef[];
+  /** Named frame widths the application supports — rendered as one-click buttons beside the W/H boxes. */
+  viewportPresets?: readonly ViewportPresetDef[];
   /** icons/tokens/atoms/components/screens Controller for getting inventory and full DOM layers. */
   designImport?: DesignImportController;
   /** Called with cumulative changes when editing asset panel tokens — Host is responsible for write-back (file saving). */

package/vite.d.ts

@@ -503,14 +503,17 @@ export declare function reconstructRoutePreviewArtifactSnapshots(
 export {
   ROUTE_PREVIEW_ARTIFACT_V3_LIMITS,
   createRoutePreviewArtifactV3,
+  mergeRoutePreviewArtifactV3,
   reconstructRoutePreviewArtifactScreenshotV3,
   reconstructRoutePreviewArtifactSnapshotV3,
   reconstructRoutePreviewArtifactSnapshotsV3,
+  selectRoutePreviewArtifactFrames,
   validateRoutePreviewArtifactBundle,
   validateRoutePreviewArtifactV3,
 } from './storyboard';
 export type {
   RoutePreviewArtifactBundleV3,
+  RoutePreviewArtifactFrameRequest,
   RoutePreviewArtifactV3Capture,
   StoryboardCaptureDiagnostic,
   StoryboardCaptureStatus,