@pygmalionjs/pygmalion 0.4.0 → 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

@@ -208,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,
@@ -368,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist-lib",
+    "node/component-branches.mjs",
     "node/design-session.mjs",
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",