@pygmalionjs/pygmalion 0.2.44 → 0.5.0

package/node/storyboard-environment.mjs

@@ -2,7 +2,11 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import ts from 'typescript';
-import { buildSourceGraph } from './source-graph.mjs';
+import { buildSourceGraph, findSourceUsage } from './source-graph.mjs';
+import {
+  componentBranchesMiddleware,
+  PYGMALION_COMPONENT_BRANCHES_CONTROL,
+} from './component-branches.mjs';
 import {
   canonicalizeStoryboardExecutions,
   PYGMALION_STORYBOARD_CANONICAL_CONTROL,
@@ -10,6 +14,9 @@ import {
 
 export const PYGMALION_STORYBOARD_ENVIRONMENT_CONTROL =
   '/__pygmalion-storyboard/environment';
+export const PYGMALION_SOURCE_USAGE_CONTROL =
+  '/__pygmalion-storyboard/source-usage';
+const MAX_SOURCE_USAGE_REQUEST = 100;
 export const PYGMALION_STORYBOARD_ENVIRONMENT_QUERY =
   '__pygmalion_environment';
 
@@ -1285,12 +1292,29 @@ export function storyboardEnvironmentBootstrapSource() {
     value && typeof value === 'object' && !Array.isArray(value) ? value : null;
   const environment = plainRecord(decode(encoded));
   if (!environment) return;
+  // The Node capture runtime installs the host screen preset with an init
+  // script before any page script runs; in-editor session walks reach the
+  // same global through the boot URL so fixtures that read it at module or
+  // mount time (auth role overrides, static mic levels) behave identically.
+  const screenPreset = plainRecord(environment.screenPreset);
+  if (screenPreset) {
+    Object.defineProperty(globalThis, '__PYGMALION_SCREEN_PRESET__', {
+      configurable: true,
+      value: screenPreset,
+    });
+  }
+  // 'sandbox' virtualizes the whole store per document: reads of undeclared
+  // keys see a pristine profile and writes never reach the shared origin
+  // storage. Hidden preview instances run with it so a walk that persists UI
+  // state (a collapsed sidebar, a dismissed notice) cannot poison sibling
+  // instances or the designer's own tab. Declared entries seed the sandbox.
+  const sandboxed = environment.storageIsolation === 'sandbox';
   const storageOverlays = new Map();
   const addStorageOverlay = (storage, entries) => {
     const record = plainRecord(entries);
-    if (!storage || !record) return;
+    if (!storage || (!record && !sandboxed)) return;
     const overlay = {};
-    for (const [key, value] of Object.entries(record)) {
+    for (const [key, value] of Object.entries(record ?? {})) {
       if (
         typeof key === 'string' &&
         key.length <= 512 &&
@@ -1315,9 +1339,11 @@ export function storyboardEnvironmentBootstrapSource() {
         value(key) {
           const normalizedKey = String(key);
           const overlay = storageOverlays.get(this);
-          return overlay && Object.hasOwn(overlay, normalizedKey)
-            ? overlay[normalizedKey]
-            : originalGetItem.call(this, normalizedKey);
+          if (overlay && Object.hasOwn(overlay, normalizedKey)) {
+            return overlay[normalizedKey];
+          }
+          if (overlay && sandboxed) return null;
+          return originalGetItem.call(this, normalizedKey);
         },
       },
       setItem: {
@@ -1325,7 +1351,7 @@ export function storyboardEnvironmentBootstrapSource() {
         value(key, value) {
           const normalizedKey = String(key);
           const overlay = storageOverlays.get(this);
-          if (overlay && Object.hasOwn(overlay, normalizedKey)) {
+          if (overlay && (sandboxed || Object.hasOwn(overlay, normalizedKey))) {
             overlay[normalizedKey] = String(value);
             return;
           }
@@ -1337,7 +1363,7 @@ export function storyboardEnvironmentBootstrapSource() {
         value(key) {
           const normalizedKey = String(key);
           const overlay = storageOverlays.get(this);
-          if (overlay && Object.hasOwn(overlay, normalizedKey)) {
+          if (overlay && (sandboxed || Object.hasOwn(overlay, normalizedKey))) {
             overlay[normalizedKey] = null;
             return;
           }
@@ -1351,6 +1377,7 @@ export function storyboardEnvironmentBootstrapSource() {
           if (overlay) {
             for (const key of Object.keys(overlay)) overlay[key] = null;
           }
+          if (sandboxed) return;
           return originalClear.call(this);
         },
       },
@@ -1441,17 +1468,25 @@ export function storyboardEnvironmentBootstrapSource() {
 })();`;
 }
 
+export const PYGMALION_STORYBOARD_RUNTIME_ATTRIBUTE =
+  'data-pygmalion-storyboard-runtime';
+
 export function pygmalionStoryboardRuntimePlugin() {
   return {
     name: 'pygmalion-storyboard-runtime',
     enforce: 'pre',
     transformIndexHtml: {
       order: 'pre',
-      handler() {
+      handler(html) {
+        // Composed stacks include this plugin twice (the storyboard plugin
+        // embeds it and hosts also add it directly). Vite applies each hook's
+        // tags before the next hook runs, so a copy already in the document
+        // means another instance injected first — one bootstrap is enough.
+        if (html?.includes(PYGMALION_STORYBOARD_RUNTIME_ATTRIBUTE)) return;
         return [
           {
             tag: 'script',
-            attrs: { 'data-pygmalion-storyboard-runtime': '' },
+            attrs: { [PYGMALION_STORYBOARD_RUNTIME_ATTRIBUTE]: '' },
             children: storyboardEnvironmentBootstrapSource(),
             injectTo: 'head-prepend',
           },
@@ -1484,6 +1519,47 @@ async function readExecutionResults(request) {
   return parsed.executions;
 }
 
+/**
+ * Serves symbol-level usage for the files a catalog sheet traces to.
+ *
+ * A batch, not one request per file: the scan is a whole-project pass, so
+ * asking 23 times both wastes it and leaves a long tail of entries whose
+ * answer has not arrived — which reads as "unused" exactly when it is least
+ * true.
+ */
+export function sourceUsageMiddleware(root, { sourceDirectory = 'src' } = {}) {
+  const projectRoot = path.resolve(root);
+  return async (request, response, next) => {
+    if (request.method !== 'GET') {
+      next();
+      return;
+    }
+    try {
+      const url = new URL(request.url ?? '/', 'http://localhost');
+      const files = (url.searchParams.get('files') ?? '')
+        .split(',')
+        .map((file) => file.trim())
+        .filter(Boolean);
+      if (files.length === 0) {
+        sendJson(response, 400, { error: 'Expected a files parameter.' });
+        return;
+      }
+      if (files.length > MAX_SOURCE_USAGE_REQUEST) {
+        sendJson(response, 413, {
+          error: `At most ${MAX_SOURCE_USAGE_REQUEST} files can be requested at once.`,
+        });
+        return;
+      }
+      const usage = await findSourceUsage(projectRoot, files, { sourceDirectory });
+      sendJson(response, 200, { usage });
+    } catch (error) {
+      sendJson(response, 400, {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  };
+}
+
 function sendJson(response, statusCode, body) {
   response.statusCode = statusCode;
   response.setHeader('content-type', 'application/json; charset=utf-8');
@@ -1527,6 +1603,17 @@ export function pygmalionStoryboardPlugin(options) {
           });
         }
       });
+      // Component branch discovery — the editor's "discovered branches" list
+      // and the host's dimension-declaration gate read the same manifest.
+      server.middlewares.use(
+        PYGMALION_COMPONENT_BRANCHES_CONTROL,
+        componentBranchesMiddleware(root),
+      );
+      // Symbol-level usage — what the catalog storyboard means by "used by".
+      server.middlewares.use(
+        PYGMALION_SOURCE_USAGE_CONTROL,
+        sourceUsageMiddleware(root, { sourceDirectory }),
+      );
       server.middlewares.use(
         canonicalEndpoint,
         async (request, response, next) => {

package/node/vite.mjs

@@ -69,6 +69,7 @@ import {
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
   pygmalionPreviewArtifactPlugin,
 } from './preview-artifact-plugin.mjs';
+import { createPreviewCaptureWorkerChannel } from './preview-capture-worker.mjs';
 import {
   DEFAULT_QA_CAPTURE_MAX_FRAMES,
   PYGMALION_QA_ARTIFACT_PREFIX,
@@ -207,6 +208,12 @@ export function createPygmalionVitePlugins(config) {
 
   const project = resolvePygmalionProject(config);
   const plugins = [
+    // The environment bootstrap must run in the editor host too, not only in
+    // the capture preview server: in-editor hidden instances (flow sessions,
+    // sweeps, live boots) carry declarative environments and the storage
+    // sandbox in their boot URL. Without the query parameter the bootstrap
+    // is a no-op, so ordinary app tabs are unaffected.
+    pygmalionStoryboardRuntimePlugin(),
     pygmalionStoryboardPlugin({
       root: project.appRoot,
       sourceDirectory: project.sourceDirectory,
@@ -217,17 +224,55 @@ export function createPygmalionVitePlugins(config) {
   // it lazily because a capture starts long after the plugin list is assembled.
   let devMirror = null;
 
-  if (project.preview.artifactFile || project.preview.generateArtifact) {
+  // A host either hands over a generator function or names a warm capture
+  // worker script; the function wins when both are present so existing
+  // configurations keep their exact behavior.
+  let generateArtifact = project.preview.generateArtifact;
+  let captureWorkerChannel = null;
+  if (!generateArtifact && project.preview.captureWorker) {
+    const captureWorker = optionalObject(project.preview.captureWorker);
+    if (
+      typeof captureWorker.script !== 'string' ||
+      captureWorker.script.trim() === ''
+    ) {
+      throw new Error(
+        'Pygmalion preview.captureWorker.script must be a non-empty string',
+      );
+    }
+    captureWorkerChannel = createPreviewCaptureWorkerChannel({
+      script: path.resolve(project.appRoot, captureWorker.script),
+      args: captureWorker.args,
+      env: captureWorker.env,
+      cwd: project.appRoot,
+      idleMs: captureWorker.idleMs,
+      jobTimeoutMs: captureWorker.jobTimeoutMs,
+    });
+    generateArtifact = captureWorkerChannel.generateArtifact;
+  }
+
+  if (project.preview.artifactFile || generateArtifact) {
     plugins.push(
       pygmalionPreviewArtifactPlugin({
         root: project.appRoot,
         artifactFile: project.preview.artifactFile,
         endpoint: project.preview.artifactEndpoint,
-        generateArtifact: project.preview.generateArtifact,
+        generateArtifact,
         acquireLease: (label) => devMirror?.acquireLease(label) ?? null,
       }),
     );
   }
+  if (captureWorkerChannel) {
+    const channel = captureWorkerChannel;
+    plugins.push({
+      name: 'pygmalion-preview-capture-worker',
+      apply: 'serve',
+      configureServer(server) {
+        server.httpServer?.once('close', () => {
+          void channel.dispose();
+        });
+      },
+    });
+  }
 
   if (
     project.qa !== false &&
@@ -329,6 +374,11 @@ export function createPygmalionVitePlugins(config) {
   return plugins;
 }
 
+export {
+  PYGMALION_COMPONENT_BRANCHES_CONTROL,
+  scanComponentBranches,
+  scanComponentBranchesFile,
+} from './component-branches.mjs';
 export {
   PYGMALION_DEV_CONTROL,
   PYGMALION_DEV_PREFIX,
@@ -380,6 +430,7 @@ export {
   DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
   pygmalionPreviewArtifactPlugin,
+  createPreviewCaptureWorkerChannel,
   DEFAULT_QA_CAPTURE_MAX_FRAMES,
   PYGMALION_QA_ARTIFACT_PREFIX,
   PYGMALION_QA_CAPTURE_ENDPOINT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.2.44",
+  "version": "0.5.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -32,12 +32,14 @@
   },
   "files": [
     "dist-lib",
+    "node/component-branches.mjs",
     "node/design-session.mjs",
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",
     "node/inspect-plugin.mjs",
     "node/preview-artifact-plugin.mjs",
     "node/preview-artifact-store.mjs",
+    "node/preview-capture-worker.mjs",
     "node/preview-vite-cache.mjs",
     "node/qa-capture-plugin.mjs",
     "node/route-preview-artifact-v2.mjs",
@@ -64,7 +66,7 @@
     "dev": "vite",
     "build": "tsc && vite build",
     "build:lib": "vite build --config vite.lib.config.ts",
-    "test": "node --test node/*.test.mjs src/**/*.test.mjs",
+    "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",
@@ -93,6 +95,7 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.0",
+    "happy-dom": "^20.11.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwindcss": "^4.0.0",