@pygmalionjs/pygmalion 0.6.33 → 0.6.34

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

@@ -27,6 +27,8 @@ export interface CaptureSupplyFrame {
     recipe?: RoutePreviewFrameRecipe;
 }
 export interface CaptureSupplyPlan {
+    /** Canvas that owned the viewport when this plan was built. */
+    activeCanvas?: string;
     /** Chunks of the active canvas, nearest first. */
     active: CaptureSupplyFrame[][];
     /** Chunks of the other canvases, in the order the frames were given. */

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

@@ -27,6 +27,21 @@ export declare function mirrorBootRetryDelayMs(attempt: number): number;
 export interface MirrorGateStatus {
     state: string;
 }
+/** The idle status fields that can identify an immutable source before checkout. */
+export interface IdleMirrorSourceStatus extends MirrorGateStatus {
+    sourceRef: string | null;
+}
+/**
+ * Returns an immutable source revision that can safely create the first lazy
+ * preview demand.
+ *
+ * An idle mirror has no checked-out `commit` yet. When it was configured with
+ * a full Git object id, however, that ref already names the exact revision the
+ * catalog endpoint will verify after preparation. Named refs, worktree mode,
+ * and abbreviated ids can move or be ambiguous, so they remain pending until
+ * the server reports the resolved commit.
+ */
+export declare function idleMirrorSourceRevision(status: IdleMirrorSourceStatus): string | null;
 export interface SettleMirrorStatusOptions<S extends MirrorGateStatus> {
     /** Status of the initial request; returned as-is when already settled. */
     initial: S;

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

@@ -5,6 +5,7 @@ export interface RoutePreviewArtifactStatusInput {
     resolution: RoutePreviewArtifactResolution;
     captureStatus?: RoutePreviewArtifactV3Status;
     diagnostic?: string;
+    liveInteractionReady?: boolean;
 }
 export interface RoutePreviewArtifactStatusPresentation {
     title: string;
@@ -45,4 +46,4 @@ export declare function resolveStaticRoutePreviewSurface({ hasScreenshot, hasDom
     preferDom?: boolean;
 }): StaticRoutePreviewSurface;
 /** Turns artifact freshness and capture state into one unambiguous frame badge. */
-export declare function resolveRoutePreviewArtifactStatus({ stale, resolution, captureStatus, diagnostic, }: RoutePreviewArtifactStatusInput): RoutePreviewArtifactStatusPresentation | null;
+export declare function resolveRoutePreviewArtifactStatus({ stale, resolution, captureStatus, diagnostic, liveInteractionReady, }: RoutePreviewArtifactStatusInput): RoutePreviewArtifactStatusPresentation | null;

package/node/dev-mirror.mjs

@@ -843,6 +843,9 @@ export async function acquireExactDevMirrorSourceLease({
       return {
         sourceRoot: exactSourceRoot,
         sourceRevision: expectedRevision,
+        // Synchronization and reaping honor the heartbeat lease until release,
+        // so retention may safely inspect this root while the caller holds it.
+        sourceRootStable: true,
         release,
       };
     } catch (error) {

package/node/preview-artifact-plugin.mjs

@@ -788,6 +788,12 @@ export function pygmalionPreviewArtifactPlugin({
     return { sourceRevision, sourceRoot: lease.sourceRoot };
   }
 
+  function retentionSourceContextFromLease(lease, sourceRevision) {
+    return lease?.sourceRootStable === true
+      ? sourceContextFromLease(lease, sourceRevision)
+      : undefined;
+  }
+
   /**
    * Refines a conservative cache decision only while the requested checkout is
    * pinned. Fingerprint hits, recipe mismatches, and frames without observed
@@ -872,6 +878,11 @@ export function pygmalionPreviewArtifactPlugin({
         const progress = startCaptureProgress();
         try {
           const generated = await withCaptureLease(sourceRevision, async (lease) => {
+            const sourceContext = sourceContextFromLease(lease, sourceRevision);
+            const retentionSourceContext = retentionSourceContextFromLease(
+              lease,
+              sourceRevision,
+            );
             const captured = await generateArtifact(
               {
                 namespace,
@@ -889,10 +900,10 @@ export function pygmalionPreviewArtifactPlugin({
                 'Generated preview artifact identity does not match the request.',
               );
             }
-            const observedDependenciesByFrame = lease?.sourceRoot
+            const observedDependenciesByFrame = sourceContext
               ? await artifactStore.observeArtifactDependencies(
                   captured,
-                  lease.sourceRoot,
+                  sourceContext.sourceRoot,
                 )
               : undefined;
             await validateSourceLease(lease, sourceRevision);
@@ -900,6 +911,9 @@ export function pygmalionPreviewArtifactPlugin({
             await artifactStore.publishArtifact(captured, {
               sourceRevision,
               recordRevision: true,
+              ...(retentionSourceContext
+                ? { sourceContext: retentionSourceContext }
+                : {}),
               ...(observedDependenciesByFrame
                 ? { observedDependenciesByFrame }
                 : {}),
@@ -941,6 +955,10 @@ export function pygmalionPreviewArtifactPlugin({
         try {
           return await withCaptureLease(sourceRevision, async (lease) => {
             const sourceContext = sourceContextFromLease(lease, sourceRevision);
+            const retentionSourceContext = retentionSourceContextFromLease(
+              lease,
+              sourceRevision,
+            );
             const before = await artifactStore.readFrameSelection(
               namespace,
               sourceRevision,
@@ -976,10 +994,10 @@ export function pygmalionPreviewArtifactPlugin({
                 'Generated preview artifact frames do not match the request.',
               );
             }
-            const observedDependenciesByFrame = lease?.sourceRoot
+            const observedDependenciesByFrame = sourceContext
               ? await artifactStore.observeArtifactDependencies(
                   captured,
-                  lease.sourceRoot,
+                  sourceContext.sourceRoot,
                 )
               : undefined;
             await validateSourceLease(lease, sourceRevision);
@@ -988,6 +1006,9 @@ export function pygmalionPreviewArtifactPlugin({
               sourceRevision,
               recordRevision: false,
               frameRequests: remaining,
+              ...(retentionSourceContext
+                ? { sourceContext: retentionSourceContext }
+                : {}),
               ...(observedDependenciesByFrame
                 ? { observedDependenciesByFrame }
                 : {}),

package/node/preview-artifact-store.mjs

@@ -596,7 +596,10 @@ export function createPreviewArtifactStore({
    * is what keeps a concurrent reader from losing a bundle it is about to
    * fetch.
    */
-  const evictToBudget = async (manifest, { at, sourceContext } = {}) => {
+  const evictToBudget = async (
+    manifest,
+    { at, sourceContext, admittedFrameObjects = new Set() } = {},
+  ) => {
     const referenced = new Map();
     const remember = async (hash) => {
       if (!referenced.has(hash)) referenced.set(hash, await objectByteSize(hash));
@@ -627,7 +630,13 @@ export function createPreviewArtifactStore({
       candidates.push({
         kind: 'frame',
         entry,
-        rank: EVICTION_RANK[await classifyFrameEntry(entry, sourceContext)],
+        // A caller that supplied normalized observations recorded from the
+        // artifact's own snapshot has already paid to produce this object.
+        // Protect that admission from older unknown entries without rereading
+        // a source root that may not be physically pinned.
+        rank: admittedFrameObjects.has(entry.object)
+          ? EVICTION_RANK.valid
+          : EVICTION_RANK[await classifyFrameEntry(entry, sourceContext)],
         // Protection within a rank, never across it: the last copy of a frame
         // is worth more than a surplus copy, but an invalid sole entry is still
         // garbage and goes before a valid one.
@@ -872,6 +881,7 @@ export function createPreviewArtifactStore({
             ...(stored?.frames ?? []),
           ].map((entry) => entry.object),
         );
+        const admittedFrameObjects = new Set();
         if (recordRevision && sourceRevision) {
           const wholeObject = await writeObject(artifact);
           const nextRevision = {
@@ -922,6 +932,7 @@ export function createPreviewArtifactStore({
               generation,
               ...(observed ? { sourceFiles: observed } : {}),
             };
+            if (observed) admittedFrameObjects.add(object);
             const alreadyRecorded = frames.some(
               (entry) =>
                 entry.id === nextFrame.id &&
@@ -941,6 +952,7 @@ export function createPreviewArtifactStore({
         const trimmed = await evictToBudget(manifest, {
           at,
           sourceContext: exactSourceContext,
+          admittedFrameObjects,
         });
         manifest = trimmed.dropped
           ? { ...trimmed.manifest, lastEviction: trimmed.dropped }

package/package.json

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