@pygmalionjs/pygmalion 0.5.14 → 0.5.16

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

@@ -0,0 +1,38 @@
+import { type ReactNode } from 'react';
+import type { PygmalionSourceRef } from '../editor/projectRuntime';
+export interface SourceRefControlProps {
+    /** Revision the mirror follows now. */
+    value: string | null;
+    /** Commit currently rendered by the mirror. Used to expose a newer ref tip. */
+    currentCommit?: string | null;
+    /** Revisions the mirror can be repointed at. */
+    refs: readonly PygmalionSourceRef[];
+    onChange(ref: string): void;
+    /** Blocks selection while the mirror rebuilds. */
+    busy?: boolean;
+    /** Revision used when none is pinned, offered as the first entry. */
+    defaultRef?: string | null;
+    /** Ref that renders uncommitted work. Omitted from the list when absent. */
+    worktreeRef?: string | null;
+    /** Accessible name for the control. */
+    label?: string;
+    /** Menu label for reloading the selected revision after its tip moves. */
+    refreshLabel?: string;
+    /**
+     * Trigger content. A host renders its own status chip here, so the control
+     * blends into an existing toolbar instead of adding a second field.
+     * Defaults to the selected revision.
+     */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Selects the revision the dev mirror follows. Switching rebuilds the mirror,
+ * screen inventory, and preview on that revision, so the editor reloads.
+ *
+ * The menu is a native select layered over the trigger: the host owns how the
+ * trigger looks, while keyboard access, mobile behavior, and menu placement stay
+ * with the platform. Pygmalion owns this control because the mirror lifecycle
+ * belongs to the tool, not to a consuming application.
+ */
+export declare function SourceRefControl({ value, currentCommit, refs, onChange, busy, defaultRef, worktreeRef, label, refreshLabel, children, className, }: SourceRefControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,30 @@
+type IconProps = {
+    size?: number;
+};
+export declare const CursorIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const HandIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const ZoomIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const FrameIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const SectionIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const RowsIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const ColumnsIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const TextIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const CodeIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const MinusIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const PlusIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const UndoIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const RedoIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const TrashIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const GaugeIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const AlignLeftIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const AlignCenterIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const AlignRightIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const PlayIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const ComponentIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const EyeIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const EyeOffIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const LockIcon: ({ size }: IconProps) => import("react").JSX.Element;
+export declare const ChevronIcon: ({ size, open }: IconProps & {
+    open: boolean;
+}) => import("react").JSX.Element;
+export {};

package/node/dev-mirror.mjs

@@ -29,6 +29,9 @@ const LEASE_HEARTBEAT_MS = 2_000;
 // costs a checkout and a dependency install, so the reaper errs toward keeping.
 const DEFAULT_MIRROR_GRACE_MS = 6 * 60 * 60 * 1_000;
 const LEASE_WAIT_TIMEOUT_MS = 180_000;
+// A serving editor holds this for its whole session. It marks the checkout as in
+// use for the reaper; it must never stand in the way of a sync.
+const SERVE_LEASE_LABEL = 'serve';
 
 export function resolveDevMirrorInventoryOutputRoot(inventory, mirrorAppRoot) {
   return path.resolve(inventory?.outputRoot ?? mirrorAppRoot);
@@ -469,10 +472,25 @@ export async function acquireDevMirrorLease({ repoRoot, mirrorRoot, label = 'cap
   };
 }
 
-async function waitForLeasesToClear(repoRoot, mirrorRoot, timeoutMs = LEASE_WAIT_TIMEOUT_MS) {
-  const deadline = Date.now() + timeoutMs;
+/**
+ * Leases that a sync must wait out.
+ *
+ * A reader lease is short: a capture holds one while it walks the checkout, and
+ * moving the files under it would corrupt what it is reading. A serve lease is
+ * the opposite — it lasts as long as an editor is open, and it exists so a
+ * reaper can tell a live checkout from an abandoned one. Treating the two the
+ * same wedged the second editor on a ref: it waited three minutes for a lease
+ * that, by design, never clears, and then reported the mirror as held.
+ */
+export function leasesBlockingSync(leases) {
+  return leases.filter((lease) => lease.label !== SERVE_LEASE_LABEL);
+}
+
+async function waitForLeasesToClear(repoRoot, mirrorRoot, timeoutMs) {
+  const limit = Number.isFinite(timeoutMs) ? timeoutMs : LEASE_WAIT_TIMEOUT_MS;
+  const deadline = Date.now() + limit;
   while (true) {
-    const held = await freshLeases(repoRoot, mirrorRoot);
+    const held = leasesBlockingSync(await freshLeases(repoRoot, mirrorRoot));
     if (held.length === 0) return;
     if (Date.now() >= deadline) {
       const labels = [...new Set(held.map((lease) => lease.label))].join(', ');
@@ -844,7 +862,7 @@ export function pygmalionDevMirrorPlugin(options) {
     const lease = await acquireDevMirrorLease({
       repoRoot,
       mirrorRoot: activeRoot,
-      label: 'serve',
+      label: SERVE_LEASE_LABEL,
     }).catch(() => null);
     if (lease) serveLease = { mirrorRoot: activeRoot, lease };
   };
@@ -854,6 +872,9 @@ export function pygmalionDevMirrorPlugin(options) {
     await held?.lease.release().catch(() => undefined);
   };
 
+  // Whether anything has asked for the checkout yet. The runtime is built once,
+  // on first demand, and every later demand joins the same work.
+  let runtimeRequested = false;
   let previewChild = null;
   let previewPort = null;
   let syncPromise = null;
@@ -1117,8 +1138,9 @@ export function pygmalionDevMirrorPlugin(options) {
       let warning = null;
       try {
         return await withSharedSyncLock(async () => {
-          // A capture reading this checkout must finish before it moves.
-          await waitForLeasesToClear(repoRoot, mirrorRoot);
+          // A capture reading this checkout must finish before it moves. A serving
+          // editor is not that kind of holder — see leasesBlockingSync.
+          await waitForLeasesToClear(repoRoot, mirrorRoot, options.leaseWaitTimeoutMs);
           const mirrorState = await syncDevMirrorWorktree({
             repoRoot,
             mirrorRoot,
@@ -1195,14 +1217,27 @@ export function pygmalionDevMirrorPlugin(options) {
       process.once('exit', () => {
         previewChild?.kill('SIGTERM');
       });
-      // Synchronizes once when the editor server runs. Screen mount and manual refresh requests reuse the same Promise.
-      void syncMirror().then(() =>
-        reapDevMirrorWorktrees({
-          repoRoot,
-          mirrorBaseRoot,
-          keep: [mirrorRoot],
-        })
-          .then(({ removed }) => {
+      // Nothing is prepared until something asks for it.
+      //
+      // Opening the editor used to build the checkout: fetch, worktree, install,
+      // inventory — minutes before the first pixel, on every start, even when all
+      // anyone did was look at the catalog. The captured frames are already on
+      // disk and belong to the consuming app, so browsing needs none of it.
+      //
+      // What genuinely needs the checkout asks for it: a refresh or a revision
+      // switch (below), and any request for the preview origin — the live frame,
+      // its assets, a capture. Those requests kick the work off and answer
+      // "preparing" until it lands, which is what they already did while a
+      // start-time sync was in flight.
+      const startRuntime = () => {
+        if (runtimeRequested) return;
+        runtimeRequested = true;
+        void syncMirror()
+          .then(() =>
+            reapDevMirrorWorktrees({ repoRoot, mirrorBaseRoot, keep: [mirrorRoot] }),
+          )
+          .then((result) => {
+            const removed = result?.removed ?? [];
             if (removed.length > 0) {
               console.log(
                 `[pygmalion] released ${removed.length} unused dev screen checkout(s): ${removed
@@ -1211,8 +1246,8 @@ export function pygmalionDevMirrorPlugin(options) {
               );
             }
           })
-          .catch(() => undefined),
-      );
+          .catch(() => undefined);
+      };
 
       server.middlewares.use(async (req, res, next) => {
         const url = new URL(req.url ?? '/', 'http://localhost');
@@ -1249,6 +1284,10 @@ export function pygmalionDevMirrorPlugin(options) {
           }
           let nextStatus;
           try {
+            // An explicit refresh is a demand like any other — mark the runtime as
+            // started so a later preview request joins this work instead of
+            // scheduling a second one.
+            runtimeRequested = true;
             nextStatus = await syncMirror(requestedRef);
           } catch (error) {
             json(res, 400, {
@@ -1265,7 +1304,14 @@ export function pygmalionDevMirrorPlugin(options) {
           // no longer matches the revision this origin is named after.
           const current = await verifiedStatus();
           if (current.state !== 'ready' || previewPort == null) {
-            json(res, 503, { ok: false, error: current.error ?? 'Preparing the dev screen' });
+            // This is the first thing that actually needs the checkout, so it is
+            // the thing that starts it.
+            startRuntime();
+            json(res, 503, {
+              ok: false,
+              error: current.error ?? 'Preparing the dev screen',
+              preparing: true,
+            });
             return;
           }
           proxyRequest(req, res, previewPort, prefix);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -9,10 +9,10 @@
   },
   "type": "module",
   "module": "./dist-lib/pygmalion.js",
-  "types": "./types.d.ts",
+  "types": "./dist-lib/types/lib.d.ts",
   "exports": {
     ".": {
-      "types": "./types.d.ts",
+      "types": "./dist-lib/types/lib.d.ts",
       "default": "./dist-lib/pygmalion.js"
     },
     "./vite": {
@@ -25,7 +25,7 @@
     },
     "./dev-view": "./node/dev-view.vite.mjs",
     "./testing": {
-      "types": "./testing.d.ts",
+      "types": "./dist-lib/types/testing.d.ts",
       "default": "./dist-lib/testing.js"
     },
     "./style.css": "./dist-lib/style.css"
@@ -58,19 +58,18 @@
     "node/vite.mjs",
     "qa.d.ts",
     "storyboard.d.ts",
-    "types.d.ts",
-    "testing.d.ts",
     "vite.d.ts"
   ],
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
-    "build:lib": "vite build --config vite.lib.config.ts",
+    "build:lib": "vite build --config vite.lib.config.ts && npm run build:types",
     "test": "node --test node/*.test.mjs src/*.test.mjs src/**/*.test.mjs",
     "lint:language": "node scripts/lint-language.mjs",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run lint:language && npm test && npm run typecheck && npm run build:lib",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "build:types": "node scripts/emit-types.mjs"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/testing.d.ts

@@ -1,26 +0,0 @@
-import type { ReactElement } from 'react';
-import type {
-  ComponentRegistry,
-  NodeJSON,
-} from './types';
-
-export declare function FrozenRoutePreviewView(props: {
-  page: unknown;
-  snapshot: string;
-  height: number;
-  onDocumentReady?: (iframe: HTMLIFrameElement) => void;
-  onReplayIssuesChange?: (issues: string[]) => void;
-}): ReactElement;
-
-export declare class NodeModel {
-  constructor(
-    type: 'rows' | 'columns' | 'text' | 'component',
-    patch?: Partial<NodeJSON>,
-  );
-}
-
-export declare const editor: any;
-export declare function serializeNode(node: NodeModel): NodeJSON;
-export declare function setComponentRegistry(
-  registry: ComponentRegistry,
-): void;