@pygmalionjs/pygmalion 0.2.26 → 0.2.28

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-capture-sessions.mjs

@@ -0,0 +1,109 @@
+import {
+  captureStoryboardCase,
+  storyboardCaptureSessionKey,
+} from './storyboard-capture-runtime.mjs';
+
+export const STORYBOARD_SESSION_POOL_LIMITS = Object.freeze({
+  maximumLanes: 16,
+});
+
+function assertPositiveLaneLimit(value) {
+  const lanes = value ?? STORYBOARD_SESSION_POOL_LIMITS.maximumLanes;
+  if (
+    !Number.isInteger(lanes) ||
+    lanes < 1 ||
+    lanes > STORYBOARD_SESSION_POOL_LIMITS.maximumLanes
+  ) {
+    throw new RangeError(
+      `Storyboard session lanes must be an integer from 1 to ${STORYBOARD_SESSION_POOL_LIMITS.maximumLanes}.`,
+    );
+  }
+  return lanes;
+}
+
+async function closeLane(lane) {
+  try {
+    await lane.context?.close();
+  } catch {
+    // The lane is being discarded — a close failure has nothing left to protect.
+  }
+}
+
+/**
+ * Captures storyboard cases on warm pages when the case declares its state.
+ *
+ * One booted application can serve many screens: a declared state is reached by
+ * switching state, not by loading the app again. Cases that replay interactions
+ * keep the fresh-context path, because only the case itself knows how to undo
+ * what a click opened.
+ *
+ * A lane is a booted page plus the key it was booted for. Lanes are leased, so
+ * two workers never drive the same page, and a lane that saw a failure is
+ * discarded rather than handed to the next case.
+ */
+export function createStoryboardCaptureSessions({
+  capture = captureStoryboardCase,
+  maximumLanes,
+  ...defaults
+} = {}) {
+  const laneLimit = assertPositiveLaneLimit(maximumLanes);
+  const idle = new Map();
+  const open = new Set();
+  const stats = { warm: 0, cold: 0, boots: 0, discarded: 0 };
+
+  function leaseLane(key) {
+    const available = idle.get(key);
+    const lane = available?.pop();
+    if (available && available.length === 0) idle.delete(key);
+    if (lane) return lane;
+    if (open.size >= laneLimit) return null;
+    const created = { key, context: null, page: null, frozen: false };
+    open.add(created);
+    return created;
+  }
+
+  async function releaseLane(lane) {
+    if (lane.poisoned || !lane.page) {
+      open.delete(lane);
+      if (lane.context) stats.discarded += 1;
+      await closeLane(lane);
+      return;
+    }
+    const available = idle.get(lane.key);
+    if (available) available.push(lane);
+    else idle.set(lane.key, [lane]);
+  }
+
+  return {
+    async capture(screenCase, context = {}) {
+      const key = storyboardCaptureSessionKey(screenCase);
+      // Retry passes ask for isolation on purpose — a reused page is exactly
+      // what they are trying to rule out as the cause.
+      const lane = key && context.isolated !== true ? leaseLane(key) : null;
+      if (!lane) {
+        stats.cold += 1;
+        return capture({ ...defaults, screenCase });
+      }
+      const booted = Boolean(lane.page);
+      if (booted) stats.warm += 1;
+      else {
+        stats.cold += 1;
+        stats.boots += 1;
+      }
+      try {
+        return await capture({ ...defaults, screenCase, session: lane });
+      } finally {
+        await releaseLane(lane);
+      }
+    },
+    stats() {
+      return { ...stats, lanes: open.size };
+    },
+    async close() {
+      const lanes = [...open];
+      open.clear();
+      idle.clear();
+      await Promise.all(lanes.map((lane) => closeLane(lane)));
+    },
+  };
+}

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.28",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -46,6 +46,7 @@
     "node/source-operations.mjs",
     "node/storyboard-canonical.mjs",
     "node/storyboard-capture-scheduler.mjs",
+    "node/storyboard-capture-sessions.mjs",
     "node/storyboard-capture-runtime.mjs",
     "node/storyboard-environment.mjs",
     "node/storyboard.mjs",

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 {