@pygmalionjs/pygmalion 0.2.25 → 0.2.27

package/node/dev-mirror.mjs

@@ -47,6 +47,74 @@ export function devMirrorRefSlug(ref) {
   return createHash('sha256').update(raw).digest('hex').slice(0, 12);
 }
 
+/**
+ * Identity of the project a mirror checkout belongs to.
+ *
+ * Two worktrees of one repository configure the same mirror path, and each
+ * generates its own inventory into it. Sharing one checkout made each server see
+ * the other's generated files as unexpected changes and refuse to sync, so a
+ * checkout is claimed by the project that syncs it.
+ */
+export function devMirrorOwnerToken(repoRoot, appDirectory = '') {
+  const identity = `${path.resolve(repoRoot)}\u0000${appDirectory}`;
+  return createHash('sha256').update(identity).digest('hex').slice(0, 10);
+}
+
+// The claim lives beside the repository's other Pygmalion state, not inside the
+// checkout: a file in the worktree would itself be an unexpected change.
+async function mirrorClaimFile(repoRoot, mirrorRoot) {
+  const directory = path.join(await pygmalionStateDirectory(repoRoot), 'mirror-claims');
+  const key = createHash('sha256').update(path.resolve(mirrorRoot)).digest('hex').slice(0, 16);
+  return path.join(directory, `${key}.json`);
+}
+
+function isPlainMirrorStamp(value) {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    typeof value.owner === 'string' &&
+    value.owner.length > 0
+  );
+}
+
+/**
+ * Whether this project may sync the checkout at `mirrorRoot`.
+ *
+ * An unclaimed or self-claimed checkout is ours. One claimed by another project is
+ * not, and the caller moves to its own path rather than fighting over this one —
+ * which is what two worktrees of one repository were doing every time they
+ * regenerated their own inventory into the same directory.
+ */
+export async function devMirrorClaim(repoRoot, mirrorRoot, owner) {
+  let stamp = null;
+  try {
+    const raw = await fsp.readFile(await mirrorClaimFile(repoRoot, mirrorRoot), 'utf8');
+    const parsed = JSON.parse(raw);
+    stamp = isPlainMirrorStamp(parsed) ? parsed : null;
+  } catch {
+    stamp = null;
+  }
+  if (!stamp) return { owned: true, previousOwner: null };
+  return { owned: stamp.owner === owner, previousOwner: stamp.owner };
+}
+
+export async function claimDevMirror(repoRoot, mirrorRoot, owner) {
+  const file = await mirrorClaimFile(repoRoot, mirrorRoot);
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  await fsp
+    .writeFile(
+      file,
+      `${JSON.stringify({
+        owner,
+        repoRoot: path.resolve(repoRoot),
+        mirrorRoot: path.resolve(mirrorRoot),
+        claimedAt: new Date().toISOString(),
+      })}\n`,
+    )
+    .catch(() => undefined);
+}
+
 /**
  * One checkout per ref. Two editor servers pointed at different refs used to
  * share a single mirror directory and take turns running `git switch` in it, so
@@ -59,16 +127,17 @@ export function resolveDevMirrorWorktreePaths({
   mirrorAppRoot,
   appDirectory = '',
   ref = null,
+  owner = null,
 }) {
   const base = path.resolve(mirrorRoot);
-  const slug = devMirrorRefSlug(ref);
-  if (!slug) {
+  const parts = [devMirrorRefSlug(ref), owner ? String(owner) : ''].filter(Boolean);
+  if (!parts.length) {
     return {
       mirrorRoot: base,
       mirrorAppRoot: path.resolve(mirrorAppRoot ?? path.join(base, appDirectory)),
     };
   }
-  const scoped = `${base}-${slug}`;
+  const scoped = `${base}-${parts.join('-')}`;
   return {
     mirrorRoot: scoped,
     mirrorAppRoot: path.resolve(path.join(scoped, appDirectory)),
@@ -582,6 +651,9 @@ export function pygmalionDevMirrorPlugin(options) {
   );
   // The ref is repointable at runtime and each ref owns its own checkout, so the
   // active paths are recomputed per sync instead of frozen at plugin creation.
+  const ownerToken = devMirrorOwnerToken(repoRoot, appDirectory);
+  // Set once the base checkout turns out to belong to another project.
+  let mirrorOwnerScope = null;
   let mirrorRoot = mirrorBaseRoot;
   let mirrorAppRoot = mirrorAppOverride ?? path.join(mirrorBaseRoot, appDirectory);
   let viteConfig = viteConfigOverride ?? path.join(mirrorAppRoot, 'vite.config.ts');
@@ -598,6 +670,7 @@ export function pygmalionDevMirrorPlugin(options) {
       mirrorAppRoot: mirrorAppOverride,
       appDirectory,
       ref: activeRef,
+      owner: mirrorOwnerScope,
     });
     mirrorRoot = resolved.mirrorRoot;
     mirrorAppRoot = resolved.mirrorAppRoot;
@@ -729,6 +802,24 @@ export function pygmalionDevMirrorPlugin(options) {
     const lockHash = await fileHash(lockFile);
     const stamp = await fsp.readFile(stampFile, 'utf8').catch(() => '');
     if ((await exists(nodeModules)) && stamp.trim() === lockHash) return false;
+    // An owner-scoped checkout is a second copy of the same source. Borrowing the
+    // base checkout's modules when the lock file agrees keeps that isolation from
+    // costing a full install per project.
+    if (!(await exists(nodeModules)) && mirrorOwnerScope) {
+      const baseModules = path.join(
+        mirrorAppOverride ?? path.join(mirrorBaseRoot, appDirectory),
+        dependencies.modulesDirectory ?? 'node_modules',
+      );
+      const baseLock = path.join(
+        mirrorAppOverride ?? path.join(mirrorBaseRoot, appDirectory),
+        dependencies.lockFile ?? 'package-lock.json',
+      );
+      const baseLockHash = await fileHash(baseLock).catch(() => null);
+      if ((await exists(baseModules)) && baseLockHash === lockHash) {
+        await fsp.symlink(baseModules, nodeModules, 'dir').catch(() => undefined);
+        if (await exists(nodeModules)) return false;
+      }
+    }
     await run(
       dependencies.installCommand ?? 'npm',
       dependencies.installArgs ?? ['install', '--no-audit', '--no-fund'],
@@ -840,6 +931,13 @@ export function pygmalionDevMirrorPlugin(options) {
     if (syncPromise) return syncPromise;
     applyMirrorPathsForRef(ref);
     syncPromise = (async () => {
+      // A checkout another project claimed is not ours to regenerate into. Moving
+      // to our own path is what ends the tug of war between two worktrees.
+      const claim = await devMirrorClaim(repoRoot, mirrorRoot, ownerToken);
+      if (!claim.owned && mirrorOwnerScope !== ownerToken) {
+        mirrorOwnerScope = ownerToken;
+        applyMirrorPathsForRef(ref);
+      }
       status = { ...status, state: 'syncing', error: null, warning: null };
       let warning = null;
       try {
@@ -859,6 +957,7 @@ export function pygmalionDevMirrorPlugin(options) {
           });
           warning = mirrorState.warning;
           const { previous, commit, shortCommit } = mirrorState;
+          await claimDevMirror(repoRoot, mirrorRoot, ownerToken);
           const dependenciesChanged = await syncDependencies();
           await generateInventory(commit);
           await startPreview(dependenciesChanged);

package/node/storyboard-capture-runtime.mjs

@@ -589,6 +589,11 @@ async function installStoryboardPreset(context, page, preset) {
       // The script runs again after an opaque initial page reaches the app origin.
     }
   }, preset);
+  await applyStoryboardPresetMedia(page, preset);
+}
+
+async function applyStoryboardPresetMedia(page, preset) {
+  if (!preset) return;
   const media = preset.media ?? preset;
   if (media.colorScheme || media.reducedMotion) {
     await page.emulateMedia({
@@ -598,6 +603,32 @@ async function installStoryboardPreset(context, page, preset) {
   }
 }
 
+/**
+ * Writes the case environment into a page that is already running the app.
+ *
+ * The cold path passes the environment through the URL so the bootstrap can
+ * apply it before the first render. A warm page has already rendered, so the
+ * same declaration is written directly and the preset hook applies the state.
+ */
+async function declareWarmStoryboardEnvironment(page, environment) {
+  if (!environment || typeof environment !== 'object') return;
+  await page.evaluate((value) => {
+    const overlay = (storage, entries) => {
+      if (!storage || !entries || typeof entries !== 'object') return;
+      for (const [key, item] of Object.entries(entries)) {
+        try {
+          if (item == null) storage.removeItem(key);
+          else storage.setItem(key, String(item));
+        } catch {
+          // Private mode or quota — the declaration stays in-memory only.
+        }
+      }
+    };
+    overlay(window.localStorage, value.localStorage ?? value.storage?.local);
+    overlay(window.sessionStorage, value.sessionStorage ?? value.storage?.session);
+  }, environment);
+}
+
 async function executeStoryboardPreset(page, screenCase, route) {
   if (!screenCase.preset) return;
   const request = {
@@ -1002,6 +1033,25 @@ function captureResult({
  * Pygmalion owns the deterministic browser lifecycle and QA status model. The
  * host application owns only domain setup through hooks.
  */
+/**
+ * Reports whether a case can be captured on a page that is already warm.
+ *
+ * Reuse requires a declared state and no interactions. An interaction leaves
+ * the page in a state only that case knows how to undo — an open menu or modal
+ * would leak into the next snapshot — so those cases always get a fresh page.
+ * The host names the reusable group with `session`; Pygmalion never guesses it.
+ */
+export function storyboardCaptureSessionKey(screenCase) {
+  const session =
+    typeof screenCase?.session === 'string' ? screenCase.session.trim() : '';
+  if (!session) return null;
+  if ((screenCase.interactions ?? []).length > 0) return null;
+  const route = resolveStoryboardCaptureRoute(screenCase);
+  if (route == null || route === '') return null;
+  const viewport = captureViewport(screenCase);
+  return `${session}|${route}|${viewport.width}x${viewport.height}`;
+}
+
 export async function captureStoryboardCase({
   browser,
   baseUrl,
@@ -1015,6 +1065,7 @@ export async function captureStoryboardCase({
   navigationOptions = {},
   screenshotOptions = {},
   stability = {},
+  session = null,
 } = {}) {
   if (!browser || typeof browser.newContext !== 'function') {
     throw new TypeError(
@@ -1041,52 +1092,76 @@ export async function captureStoryboardCase({
     });
   }
 
-  let context = null;
-  let page = null;
+  // A warm session keeps the application booted between cases: the state is
+  // declared, so the next case only has to switch it. Boot is the expensive part
+  // (one per screen previously), and it is the part reuse removes.
+  const warm = Boolean(session?.page);
+  let context = session?.context ?? null;
+  let page = session?.page ?? null;
   let primaryError = null;
   let evidence = {};
   const evidenceErrors = [];
   try {
     throwIfAborted(signal);
-    context = await atCaptureStage('setup', () =>
-      browser.newContext({
-        viewport,
-        colorScheme: 'light',
-        reducedMotion: 'reduce',
-        locale: 'en-US',
-        timezoneId: 'UTC',
-        ...contextOptions,
-        viewport,
-      }),
-    );
-    await atCaptureStage('setup', () =>
-      context.addInitScript(() => {
-        let seed = 0x5f3759df;
-        Math.random = () => {
-          seed = (seed * 1664525 + 1013904223) >>> 0;
-          return seed / 0x100000000;
-        };
-      }),
-    );
-    page = await atCaptureStage('setup', () => context.newPage());
+    if (!warm) {
+      context = await atCaptureStage('setup', () =>
+        browser.newContext({
+          viewport,
+          colorScheme: 'light',
+          reducedMotion: 'reduce',
+          locale: 'en-US',
+          timezoneId: 'UTC',
+          ...contextOptions,
+          viewport,
+        }),
+      );
+      await atCaptureStage('setup', () =>
+        context.addInitScript(() => {
+          let seed = 0x5f3759df;
+          Math.random = () => {
+            seed = (seed * 1664525 + 1013904223) >>> 0;
+            return seed / 0x100000000;
+          };
+        }),
+      );
+      page = await atCaptureStage('setup', () => context.newPage());
+      if (session) {
+        session.context = context;
+        session.page = page;
+      }
+    }
 
     await atCaptureStage('preset', async () => {
       throwIfAborted(signal);
       const fixedTime = resolveStoryboardFixedTime(screenCase.preset);
       if (fixedTime) await page.clock.setFixedTime(fixedTime);
-      await hooks.beforePreset?.({ context, page, screenCase, route, signal });
-      await installStoryboardPreset(context, page, screenCase.preset);
+      await hooks.beforePreset?.({
+        context,
+        page,
+        screenCase,
+        route,
+        signal,
+        warm,
+      });
+      if (warm) {
+        await declareWarmStoryboardEnvironment(page, screenCase.environment);
+        await applyStoryboardPresetMedia(page, screenCase.preset);
+      } else {
+        await installStoryboardPreset(context, page, screenCase.preset);
+      }
     });
-    await atCaptureStage('navigation', () =>
-      page.goto(
-        resolveStoryboardCaptureUrl(baseUrl, route, screenCase.environment),
-        {
-          waitUntil: 'domcontentloaded',
-          timeout: 30_000,
-          ...navigationOptions,
-        },
-      ),
-    );
+    if (!warm) {
+      await atCaptureStage('navigation', () =>
+        page.goto(
+          resolveStoryboardCaptureUrl(baseUrl, route, screenCase.environment),
+          {
+            waitUntil: 'domcontentloaded',
+            timeout: 30_000,
+            ...navigationOptions,
+          },
+        ),
+      );
+    }
     await atCaptureStage('preset', async () => {
       await executeStoryboardPreset(page, screenCase, route);
       await hooks.afterPreset?.({
@@ -1109,7 +1184,10 @@ export async function captureStoryboardCase({
       );
     }
     await atCaptureStage('stabilize', async () => {
-      await page.addStyleTag({ content: FROZEN_STYLE });
+      if (!session?.frozen) {
+        await page.addStyleTag({ content: FROZEN_STYLE });
+        if (session) session.frozen = true;
+      }
       const stable = await waitForStableStoryboardDocument(page, stability);
       if (!stable) {
         throw new Error(
@@ -1148,10 +1226,16 @@ export async function captureStoryboardCase({
     }
   }
 
-  try {
-    await context?.close();
-  } catch (error) {
-    evidenceErrors.push(new StoryboardCaptureStageError('teardown', error));
+  if (session) {
+    // A failed case may leave the page in a state the next case cannot undo —
+    // the pool discards the lane instead of passing the mess along.
+    if (primaryError) session.poisoned = true;
+  } else {
+    try {
+      await context?.close();
+    } catch (error) {
+      evidenceErrors.push(new StoryboardCaptureStageError('teardown', error));
+    }
   }
 
   if (!primaryError && evidenceErrors.length === 0) {

package/node/storyboard.mjs

@@ -7,6 +7,11 @@ export {
   recommendedStoryboardExecutionConcurrency,
 } from './storyboard-canonical.mjs';
 
+export {
+  STORYBOARD_SESSION_POOL_LIMITS,
+  createStoryboardCaptureSessions,
+} from './storyboard-capture-sessions.mjs';
+
 export {
   STORYBOARD_CAPTURE_STATUSES,
   StoryboardCaptureStageError,
@@ -18,6 +23,7 @@ export {
   hashStoryboardCapture,
   normalizeStoryboardDomStructure,
   resolveStoryboardCaptureRoute,
+  storyboardCaptureSessionKey,
   resolveStoryboardCaptureUrl,
   resolveStoryboardFixedTime,
   runStoryboardAssertion,

package/package.json

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

package/storyboard.d.ts

@@ -68,6 +68,34 @@ export interface StoryboardCaptureOptions<
   screenshotOptions?: Record<string, unknown>;
   /** How long to wait for a still document, and what may keep moving. */
   stability?: StoryboardStabilityOptions;
+  /** A warm page lane owned by the session pool. Supplied by createStoryboardCaptureSessions. */
+  session?: StoryboardCaptureSession | null;
+}
+
+/** One booted page plus the group it was booted for. Owned by the session pool. */
+export interface StoryboardCaptureSession {
+  key: string;
+  context: unknown;
+  page: unknown;
+  frozen?: boolean;
+  poisoned?: boolean;
+}
+
+export interface StoryboardCaptureSessionPool<
+  TScreenCase extends Record<string, unknown> = Record<string, unknown>,
+> {
+  capture(
+    screenCase: TScreenCase,
+    context?: { isolated?: boolean; [key: string]: unknown },
+  ): Promise<StoryboardCaptureResult>;
+  stats(): {
+    warm: number;
+    cold: number;
+    boots: number;
+    discarded: number;
+    lanes: number;
+  };
+  close(): Promise<void>;
 }
 
 export interface StoryboardStabilityOptions {
@@ -100,6 +128,29 @@ export declare function captureStoryboardCase<
 >(
   options: StoryboardCaptureOptions<TScreenCase>,
 ): Promise<StoryboardCaptureResult>;
+/**
+ * Captures declared screens on warm pages, and replayed screens on fresh ones.
+ *
+ * Boot is the expensive part of a capture, and a declared state does not need
+ * one per screen. Cases that replay interactions keep the fresh-context path.
+ */
+export declare function createStoryboardCaptureSessions<
+  TScreenCase extends Record<string, unknown> = Record<string, unknown>,
+>(
+  options: Partial<StoryboardCaptureOptions<TScreenCase>> & {
+    capture?: (
+      options: StoryboardCaptureOptions<TScreenCase>,
+    ) => Promise<StoryboardCaptureResult>;
+    maximumLanes?: number;
+  },
+): StoryboardCaptureSessionPool<TScreenCase>;
+export declare const STORYBOARD_SESSION_POOL_LIMITS: {
+  readonly maximumLanes: number;
+};
+/** The warm-page group key for a case, or null when the case must boot its own page. */
+export declare function storyboardCaptureSessionKey(
+  screenCase: Record<string, unknown>,
+): string | null;
 export declare function resolveStoryboardCaptureRoute(
   screenCase: Record<string, unknown>,
 ): unknown;

package/types.d.ts

@@ -315,6 +315,8 @@ export interface DesignScreenCase extends DesignImportPage {
   sourcePath?: string;
   codeName?: string;
   coverageRoutes?: readonly string[];
+  /** Names a group of screens that can be captured on one booted page. */
+  session?: string;
 }
 
 export interface DesignBehaviorScenario {