@pygmalionjs/pygmalion 0.2.26 → 0.2.27

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.26",
+  "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 {