@pygmalionjs/pygmalion 0.6.2 → 0.6.3

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 "./FrozenRoutePreview-X4XRmf9G.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-V9-gxIyv.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

package/dist-lib/types/canvas/ObjectControls.d.ts

@@ -6,20 +6,17 @@ export type Rect = {
     height: number;
 };
 export declare function resizedRect(base: Rect, edge: ResizeEdge, dx: number, dy: number, minWidth: number, minHeight: number): Rect;
-export declare function ObjectControls({ kind, onResize, onDelete, deleteDisabled, status, readOnly, resizeEnabled, deleteEnabled, }: {
+export declare function ObjectControls({ kind, onResize, onDelete, deleteDisabled, status, readOnly, }: {
     kind: 'frame' | 'section';
     onResize: (edge: ResizeEdge, e: React.MouseEvent) => void;
     onDelete: (e: React.MouseEvent) => void;
     deleteDisabled?: boolean;
     status?: string;
     /**
-     * Draws the outline and size read-out without mutating affordances by
-     * default. Callers may opt viewport resizing back in without also exposing
-     * destructive object deletion.
+     * Draws the outline and the size read-out without the grips. View-only
+     * still wants to show WHICH object is being read; it must not offer a
+     * handle to drag or a button to delete, because an affordance is a
+     * promise and this mode cannot keep it.
      */
     readOnly?: boolean;
-    /** Overrides the read-only default for viewport-like resize operations. */
-    resizeEnabled?: boolean;
-    /** Overrides the read-only default for destructive deletion. */
-    deleteEnabled?: boolean;
 }): import("react").JSX.Element;

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

@@ -0,0 +1,20 @@
+export declare const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX = "/progress";
+export type PygmalionPreviewCaptureProgressPhase = 'idle' | 'queued' | 'preparing' | 'capturing' | 'retrying' | 'finalizing';
+export interface PygmalionPreviewCaptureProgress {
+    active: boolean;
+    phase: PygmalionPreviewCaptureProgressPhase;
+    completed: number;
+    total: number;
+    jobCount: number;
+    frameId?: string;
+    captureStatus?: string;
+    updatedAt?: number;
+}
+export declare function previewCaptureProgressEndpoint(artifactEndpoint: string): string;
+export declare function normalizePreviewCaptureProgress(value: unknown): PygmalionPreviewCaptureProgress | null;
+/**
+ * Reads the local preview worker's current progress from the artifact plugin.
+ * Idle polling is deliberately slower; an active capture tightens the interval
+ * so a multi-minute job stays legible without holding a streaming connection.
+ */
+export declare function usePygmalionPreviewCaptureProgress(artifactEndpoint?: string): PygmalionPreviewCaptureProgress;

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

@@ -13,11 +13,6 @@ export interface PygmalionDevMirrorStatus {
     warning: string | null;
     error: string | null;
     appOrigin: string | null;
-    /** Present when the proxy child is absent or serves another ref's checkout. */
-    runtimeDrift?: {
-        expectedAppRoot: string;
-        actualAppRoot: string | null;
-    };
 }
 /** One revision the mirror can be repointed at. */
 export interface PygmalionSourceRef {

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

@@ -717,12 +717,6 @@ export declare class EditorStore {
     previewHistory: string[];
     /** Edit Mode (top right toggle) — If false, block manipulation of canvas (view only). */
     editMode: boolean;
-    /**
-     * The one frame whose preview surface accepts pointer/wheel input in
-     * view-only. Entering it is explicit (double-click); ordinary selection
-     * remains a safe read of the frame and its inspector.
-     */
-    viewOnlyInteractionPageId: string | null;
     /** Shows the Reflect (Change Summary) panel. */
     applyOpen: boolean;
     private editModeInitialized;
@@ -738,14 +732,6 @@ export declare class EditorStore {
      */
     initEditMode(editMode: boolean): void;
     toggleEditMode(): void;
-    /**
-     * Lets a view-only reader operate one preview without opening the full-screen
-     * player. This selects the frame as well, so its declared preview controls
-     * and viewport controls remain available in the right panel.
-     */
-    enterViewOnlyInteraction(pageId: string): boolean;
-    exitViewOnlyInteraction(): void;
-    isViewOnlyInteractionActive(pageId: string): boolean;
     setApplyOpen(v: boolean): void;
     tool: 'select' | 'hand' | 'zoom' | 'section';
     /** A section is a first-class object. Its display bounds include its rectangle and member frames. */

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

@@ -20,6 +20,8 @@ import { type ViewportPresetDef } from './editor/viewportPresets';
 import { type PreviewEnvironmentControlDef } from './editor/previewEnvironmentControls';
 
 export { setComponentRegistry } from './editor/registry';
+export { PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX, previewCaptureProgressEndpoint, usePygmalionPreviewCaptureProgress, } from './editor/previewCaptureProgress';
+export type { PygmalionPreviewCaptureProgress, PygmalionPreviewCaptureProgressPhase, } from './editor/previewCaptureProgress';
 export type { ComponentRegistry, RegistryEntry, RegistryPropValue, } from './editor/registry';
 export { enumerateDesignComponentConnectionCases, getDesignComponentConnection, getDesignComponentConnectionForComponent, getDesignComponentConnections, setDesignComponentConnections, validateDesignComponentConnections, } from './editor/componentConnections';
 export type { DesignComponentConnectionCase, DesignComponentConnectionCases, DesignComponentConnectionDef, DesignComponentReference, DesignConnectionDiagnostic, DesignConnectionPropertyDef, DesignConnectionPropertyKind, } from './editor/componentConnections';

package/node/dev-mirror.mjs

@@ -37,47 +37,6 @@ export function resolveDevMirrorInventoryOutputRoot(inventory, mirrorAppRoot) {
   return path.resolve(inventory?.outputRoot ?? mirrorAppRoot);
 }
 
-/** A running preview belongs to one immutable app root for its whole process. */
-export function devPreviewNeedsRestart({
-  force = false,
-  running = false,
-  activeAppRoot = null,
-  nextAppRoot,
-}) {
-  if (force) return true;
-  if (!running) return false;
-  if (typeof activeAppRoot !== 'string' || !activeAppRoot.trim()) return true;
-  return path.resolve(activeAppRoot) !== path.resolve(nextAppRoot);
-}
-
-/**
- * A commit is not ready when the proxy child still serves another ref's root.
- * Returning drifted makes the ordinary boot gate request the same resync that
- * repairs a checkout whose HEAD moved underneath the server.
- */
-export function devMirrorPreviewDriftStatus(
-  status,
-  { running = false, activeAppRoot = null, expectedAppRoot },
-) {
-  if (status?.state !== 'ready' || typeof expectedAppRoot !== 'string') {
-    return status;
-  }
-  const actual =
-    running && typeof activeAppRoot === 'string' && activeAppRoot.trim()
-      ? path.resolve(activeAppRoot)
-      : null;
-  const expected = path.resolve(expectedAppRoot);
-  if (actual === expected) return status;
-  return {
-    ...status,
-    state: 'drifted',
-    runtimeDrift: { expectedAppRoot: expected, actualAppRoot: actual },
-    error: actual
-      ? `dev screen runtime drifted: expected ${expected}, serving ${actual}`
-      : `dev screen runtime stopped: expected ${expected}`,
-  };
-}
-
 /**
  * Directory-safe form of a source ref, used to give each ref its own checkout.
  */
@@ -918,7 +877,6 @@ export function pygmalionDevMirrorPlugin(options) {
   let runtimeRequested = false;
   let previewChild = null;
   let previewPort = null;
-  let previewAppRoot = null;
   let syncPromise = null;
   let sharedLockPathPromise = null;
   // Assigned once the server is configured. A capture asks for the checkout
@@ -1004,18 +962,6 @@ export function pygmalionDevMirrorPlugin(options) {
    */
   const verifiedStatus = async () => {
     if (status.state !== 'ready' || !status.commit) return status;
-    const runtimeStatus = devMirrorPreviewDriftStatus(status, {
-      running:
-        previewChild != null &&
-        previewChild.exitCode == null &&
-        previewPort != null,
-      activeAppRoot: previewAppRoot,
-      expectedAppRoot: mirrorAppRoot,
-    });
-    if (runtimeStatus !== status) {
-      status = runtimeStatus;
-      return status;
-    }
     if (Date.now() - lastVerifiedAt < STATUS_VERIFY_TTL_MS) return status;
     lastVerifiedAt = Date.now();
     const actual = await git(mirrorRoot, 'rev-parse', 'HEAD').catch(() => null);
@@ -1027,7 +973,6 @@ export function pygmalionDevMirrorPlugin(options) {
     const child = previewChild;
     previewChild = null;
     previewPort = null;
-    previewAppRoot = null;
     if (!child || child.exitCode != null) return;
     child.kill('SIGTERM');
   };
@@ -1107,29 +1052,15 @@ export function pygmalionDevMirrorPlugin(options) {
     await run(command, args, { cwd: path.resolve(inventory.cwd ?? editorRoot) });
   };
 
-  const startPreview = async (forceRestart, sourceIdentity = ref) => {
-    const running =
-      previewChild != null &&
-      previewChild.exitCode == null &&
-      previewPort != null;
-    const restart = devPreviewNeedsRestart({
-      force: forceRestart,
-      running,
-      activeAppRoot: previewAppRoot,
-      nextAppRoot: mirrorAppRoot,
-    });
+  const startPreview = async (restart, sourceIdentity = ref) => {
     if (restart) await stopPreview();
     if (previewChild && previewChild.exitCode == null && previewPort != null) return;
 
-    // Keep the process identity local. `mirrorAppRoot` is mutable and can point
-    // at another ref by the time readiness or the exit callback runs.
-    const appRoot = mirrorAppRoot;
-    const appViteConfig = viteConfig;
     previewPort = await pickPort(preferredPreviewPort);
     const viteBin = path.resolve(
       options.viteBin ??
         path.join(
-          appRoot,
+          mirrorAppRoot,
           dependencies.modulesDirectory ?? 'node_modules',
           'vite',
           'bin',
@@ -1150,34 +1081,32 @@ export function pygmalionDevMirrorPlugin(options) {
         '--strictPort',
       ],
       {
-        cwd: appRoot,
+        cwd: mirrorAppRoot,
         env: {
           ...process.env,
           PYGMALION_PREVIEW_MODE: '1',
           // The child outlives a killed parent otherwise — it watches this pid.
           PYGMALION_PREVIEW_PARENT_PID: String(process.pid),
-          PYGMALION_APP_ROOT: appRoot,
-          PYGMALION_VITE_CONFIG: appViteConfig,
+          PYGMALION_APP_ROOT: mirrorAppRoot,
+          PYGMALION_VITE_CONFIG: viteConfig,
           PYGMALION_PREVIEW_BASE: `${prefix}/`,
           PYGMALION_VITE_CACHE_DIR: resolvePygmalionPreviewViteCacheDir({
-            appRoot,
+            appRoot: mirrorAppRoot,
             instance: `mirror:${sourceIdentity}:${prefix}`,
             modulesDirectory: dependencies.modulesDirectory,
           }),
           // Legacy names keep older preview configs working.
-          PYGMALION_DEV_FRONTEND_ROOT: appRoot,
+          PYGMALION_DEV_FRONTEND_ROOT: mirrorAppRoot,
           PYGMALION_DEV_BASE: `${prefix}/`,
         },
         stdio: ['ignore', 'inherit', 'inherit'],
       },
     );
     previewChild = child;
-    previewAppRoot = appRoot;
     child.once('exit', (code) => {
       if (previewChild !== child) return;
       previewChild = null;
       previewPort = null;
-      previewAppRoot = null;
       if (status.state === 'ready' && code !== 0) {
         status = {
           ...status,
@@ -1186,7 +1115,7 @@ export function pygmalionDevMirrorPlugin(options) {
         };
       }
     });
-    await waitUntilReady(previewPort, appRoot, prefix);
+    await waitUntilReady(previewPort, mirrorAppRoot, prefix);
   };
 
   const syncMirror = async (nextRef) => {

package/node/preview-artifact-plugin.mjs

@@ -8,6 +8,7 @@ import { createPreviewArtifactStore } from './preview-artifact-store.mjs';
 
 export const PYGMALION_PREVIEW_ARTIFACT_ENDPOINT =
   '/__pygmalion-route-preview/artifact';
+export const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX = '/progress';
 export const DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE =
   'artifacts/pygmalion-route-previews.json';
 
@@ -33,6 +34,17 @@ export const PREVIEW_CAPTURE_PRIORITY = Object.freeze({
 });
 const DEFAULT_CAPTURE_PRIORITY = PREVIEW_CAPTURE_PRIORITY.canvas;
 const MAX_CAPTURE_PRIORITY = 1_000;
+const CAPTURE_PROGRESS_PHASES = new Set([
+  'queued',
+  'preparing',
+  'capturing',
+  'retrying',
+  'finalizing',
+]);
+
+function captureProgressEndpoint(endpoint) {
+  return `${endpoint.replace(/\/$/, '')}${PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX}`;
+}
 
 function isLocalRequestHost(value) {
   const raw = Array.isArray(value) ? value[0] : value;
@@ -287,6 +299,7 @@ export function pygmalionPreviewArtifactPlugin({
       'Preview artifact runtime readiness option must be a function.',
     );
   }
+  const progressEndpoint = captureProgressEndpoint(endpoint);
 
   const artifactStore = createPreviewArtifactStore({
     artifactFile: resolvedArtifact,
@@ -299,6 +312,103 @@ export function pygmalionPreviewArtifactPlugin({
   });
   const identityQueues = new Map();
   const inFlightRequests = new Map();
+  const captureJobs = new Map();
+  let captureJobCounter = 0;
+
+  function readCaptureProgress() {
+    const jobs = [...captureJobs.values()];
+    if (jobs.length === 0) {
+      return {
+        active: false,
+        phase: 'idle',
+        completed: 0,
+        total: 0,
+        jobCount: 0,
+      };
+    }
+    const phases = new Set(jobs.map((job) => job.phase));
+    const phase = phases.has('capturing')
+      ? 'capturing'
+      : phases.has('retrying')
+        ? 'retrying'
+        : phases.has('finalizing')
+          ? 'finalizing'
+          : phases.has('preparing')
+            ? 'preparing'
+            : 'queued';
+    const latest = jobs.reduce((left, right) =>
+      left.updatedAt >= right.updatedAt ? left : right,
+    );
+    return {
+      active: true,
+      phase,
+      completed: jobs.reduce((sum, job) => sum + job.completed, 0),
+      total: jobs.reduce((sum, job) => sum + job.total, 0),
+      jobCount: jobs.length,
+      ...(latest.frameId ? { frameId: latest.frameId } : {}),
+      ...(latest.captureStatus
+        ? { captureStatus: latest.captureStatus }
+        : {}),
+      updatedAt: latest.updatedAt,
+    };
+  }
+
+  function startCaptureProgress(expectedTotal = 0) {
+    captureJobCounter += 1;
+    const id = `preview-capture-${captureJobCounter}`;
+    const job = {
+      phase: 'preparing',
+      completed: 0,
+      total:
+        Number.isInteger(expectedTotal) && expectedTotal >= 0
+          ? expectedTotal
+          : 0,
+      updatedAt: Date.now(),
+    };
+    captureJobs.set(id, job);
+    return {
+      update(progress) {
+        if (!progress || typeof progress !== 'object') return;
+        if (
+          progress.phase != null &&
+          !CAPTURE_PROGRESS_PHASES.has(progress.phase)
+        ) {
+          return;
+        }
+        const completed = Number(progress.completed ?? job.completed);
+        const total = Number(progress.total ?? job.total);
+        if (
+          !Number.isInteger(completed) ||
+          !Number.isInteger(total) ||
+          completed < 0 ||
+          total < 0 ||
+          completed > total
+        ) {
+          return;
+        }
+        job.phase = progress.phase ?? job.phase;
+        job.completed = completed;
+        job.total = total;
+        job.frameId =
+          typeof progress.frameId === 'string' && progress.frameId.trim()
+            ? progress.frameId.trim()
+            : undefined;
+        job.captureStatus =
+          typeof progress.captureStatus === 'string' &&
+          progress.captureStatus.trim()
+            ? progress.captureStatus.trim()
+            : undefined;
+        job.updatedAt = Date.now();
+      },
+      finalizing() {
+        job.phase = 'finalizing';
+        job.updatedAt = Date.now();
+      },
+      finish() {
+        captureJobs.delete(id);
+      },
+    };
+  }
 
   /**
    * Captures on one identity run one at a time — they share the checkout and
@@ -446,27 +556,36 @@ export function pygmalionPreviewArtifactPlugin({
           sourceRevision,
         );
         if (existing) return existing;
-        const generated = await withCaptureLease(sourceRevision, () =>
-          generateArtifact({
-            namespace,
-            sourceRevision,
-            ...(captureBaseUrl ? { captureBaseUrl } : {}),
-          }),
-        );
-        const validation = validateRoutePreviewArtifactBundle(generated);
-        if (!validation.valid) {
-          throw badGeneratorOutput('Generated preview artifact is invalid.');
-        }
-        if (!exactArtifact(generated, namespace, sourceRevision)) {
-          throw badGeneratorOutput(
-            'Generated preview artifact identity does not match the request.',
+        const progress = startCaptureProgress();
+        try {
+          const generated = await withCaptureLease(sourceRevision, () =>
+            generateArtifact(
+              {
+                namespace,
+                sourceRevision,
+                ...(captureBaseUrl ? { captureBaseUrl } : {}),
+              },
+              { onProgress: progress.update },
+            ),
           );
+          const validation = validateRoutePreviewArtifactBundle(generated);
+          if (!validation.valid) {
+            throw badGeneratorOutput('Generated preview artifact is invalid.');
+          }
+          if (!exactArtifact(generated, namespace, sourceRevision)) {
+            throw badGeneratorOutput(
+              'Generated preview artifact identity does not match the request.',
+            );
+          }
+          progress.finalizing();
+          await artifactStore.publishArtifact(generated, {
+            sourceRevision,
+            recordRevision: true,
+          });
+          return generated;
+        } finally {
+          progress.finish();
         }
-        await artifactStore.publishArtifact(generated, {
-          sourceRevision,
-          recordRevision: true,
-        });
-        return generated;
       }),
     );
   }
@@ -494,39 +613,47 @@ export function pygmalionPreviewArtifactPlugin({
         const absent = new Set([...before.missing, ...before.stale]);
         const remaining = wanted.filter((frame) => absent.has(frame.id));
         if (remaining.length === 0) return before;
-
-        const generated = await withCaptureLease(sourceRevision, () =>
-          generateArtifact({
-            namespace,
+        const progress = startCaptureProgress(remaining.length);
+        try {
+          const generated = await withCaptureLease(sourceRevision, () =>
+            generateArtifact(
+              {
+                namespace,
+                sourceRevision,
+                frames: remaining,
+                ...(captureBaseUrl ? { captureBaseUrl } : {}),
+              },
+              { onProgress: progress.update },
+            ),
+          );
+          const validation = validateRoutePreviewArtifactBundle(generated);
+          if (!validation.valid || generated.version !== 3) {
+            throw new Error('Generated preview artifact is invalid.');
+          }
+          if (!exactArtifact(generated, namespace, sourceRevision)) {
+            throw new Error(
+              'Generated preview artifact identity does not match the request.',
+            );
+          }
+          progress.finalizing();
+          await artifactStore.publishArtifact(generated, {
             sourceRevision,
-            frames: remaining,
-            ...(captureBaseUrl ? { captureBaseUrl } : {}),
-          }),
-        );
-        const validation = validateRoutePreviewArtifactBundle(generated);
-        if (!validation.valid || generated.version !== 3) {
-          throw new Error('Generated preview artifact is invalid.');
-        }
-        if (!exactArtifact(generated, namespace, sourceRevision)) {
-          throw new Error(
-            'Generated preview artifact identity does not match the request.',
+            recordRevision: false,
+          });
+          // Retention is allowed to decline a newly generated object when older
+          // entries have earned higher read recency. That cache decision must not
+          // discard the result from the request that just paid to generate it.
+          const responseArtifact = mergeRoutePreviewArtifactV3(
+            before.bundle,
+            generated,
           );
+          return selectRoutePreviewArtifactFrames(responseArtifact, wanted, {
+            includeStale: true,
+            sourceRevision,
+          });
+        } finally {
+          progress.finish();
         }
-        await artifactStore.publishArtifact(generated, {
-          sourceRevision,
-          recordRevision: false,
-        });
-        // Retention is allowed to decline a newly generated object when older
-        // entries have earned higher read recency. That cache decision must not
-        // discard the result from the request that just paid to generate it.
-        const responseArtifact = mergeRoutePreviewArtifactV3(
-          before.bundle,
-          generated,
-        );
-        return selectRoutePreviewArtifactFrames(responseArtifact, wanted, {
-          includeStale: true,
-          sourceRevision,
-        });
       }, priority),
     );
   }
@@ -542,6 +669,28 @@ export function pygmalionPreviewArtifactPlugin({
       void artifactStore.applyRetention?.(undefined)?.catch?.(() => undefined);
       server.middlewares.use(async (request, response, next) => {
         const url = new URL(request.url ?? '/', 'http://localhost');
+        if (url.pathname === progressEndpoint) {
+          if (request.method !== 'GET') {
+            response.setHeader('allow', 'GET');
+            sendJson(response, 405, {
+              ok: false,
+              error: 'method_not_allowed',
+            });
+            return;
+          }
+          if (!isLocalRequestHost(request.headers.host)) {
+            sendJson(response, 403, {
+              ok: false,
+              error: 'local_host_required',
+            });
+            return;
+          }
+          sendJson(response, 200, {
+            ok: true,
+            progress: readCaptureProgress(),
+          });
+          return;
+        }
         if (url.pathname !== endpoint) {
           next();
           return;