@pygmalionjs/pygmalion 0.6.33 → 0.6.35

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,34 @@ 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;
+}
+/** One listed ref whose exact revision can start a lazy checkout. */
+export interface IdleMirrorListedSourceRef {
+    name: string;
+    fullName?: string;
+    sourceRevision?: string;
+}
+/** The ref-list fields needed to resolve an idle named source. */
+export interface IdleMirrorSourceRefs {
+    refs: readonly IdleMirrorListedSourceRef[];
+    defaultRef: string | null;
+    worktreeRef?: 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. A named ref can also create
+ * that first demand when the ref-list endpoint supplies its full object id.
+ * The abbreviated display commit is intentionally ignored: it can be
+ * ambiguous and cannot satisfy the exact source lease.
+ */
+export declare function idleMirrorSourceRevision(status: IdleMirrorSourceStatus, sourceRefs?: IdleMirrorSourceRefs): 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/projectRuntime.d.ts

@@ -22,7 +22,10 @@ export interface PygmalionDevMirrorStatus {
 /** One revision the mirror can be repointed at. */
 export interface PygmalionSourceRef {
     name: string;
+    /** Abbreviated commit used for compact branch-tip labels. */
     commit: string;
+    /** Full immutable object id used for preview and artifact identity. */
+    sourceRevision?: string;
     fullName: string;
     kind: 'local' | 'remote';
 }

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

@@ -350,15 +350,21 @@ function escapeRegExp(value) {
  * of asking for a ref string.
  */
 export async function listSourceRefs(repoRoot, remote = 'origin') {
-  const format = '%(refname:short)%09%(objectname:short=8)%09%(refname)';
+  const format =
+    '%(refname:short)%09%(objectname:short=8)%09%(objectname)%09%(refname)';
   const read = async (...patterns) => {
     const raw = await git(repoRoot, 'for-each-ref', `--format=${format}`, ...patterns);
     if (!raw) return [];
     return raw
       .split('\n')
       .map((line) => line.split('\t'))
-      .filter((parts) => parts.length === 3 && parts[0])
-      .map(([name, commit, fullName]) => ({ name, commit, fullName }));
+      .filter((parts) => parts.length === 4 && parts[0])
+      .map(([name, commit, sourceRevision, fullName]) => ({
+        name,
+        commit,
+        sourceRevision,
+        fullName,
+      }));
   };
   const remotes = (await read(`refs/remotes/${remote}`))
     // `%(refname:short)` may abbreviate refs/remotes/origin/HEAD to just
@@ -375,15 +381,19 @@ export async function listSourceRefs(repoRoot, remote = 'origin') {
   // `dev@a0d5fdbf → 3e8cca5b`, an invitation to go backwards.
   const remoteTipPrefix = `refs/remotes/${remote}/`;
   const remoteTips = new Map(
-    remotes.map((item) => [item.fullName.slice(remoteTipPrefix.length), item.commit]),
+    remotes.map((item) => [item.fullName.slice(remoteTipPrefix.length), item]),
   );
-  const locals = (await read('refs/heads')).map((item) => ({
-    ...item,
-    // A branch the remote does not have resolves locally (the fetch fails and
-    // becomes a warning), so its own tip is the honest answer there.
-    commit: remoteTips.get(item.name) ?? item.commit,
-    kind: 'local',
-  }));
+  const locals = (await read('refs/heads')).map((item) => {
+    const remoteTip = remoteTips.get(item.name);
+    return {
+      ...item,
+      // A branch the remote does not have resolves locally (the fetch fails and
+      // becomes a warning), so its own tip is the honest answer there.
+      commit: remoteTip?.commit ?? item.commit,
+      sourceRevision: remoteTip?.sourceRevision ?? item.sourceRevision,
+      kind: 'local',
+    };
+  });
   const seen = new Set();
   return [...locals, ...remotes].filter((item) => {
     if (seen.has(item.name)) return false;
@@ -843,6 +853,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.35",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {