@pygmalionjs/pygmalion 0.2.7 → 0.2.9

package/node/storyboard-environment.mjs

@@ -0,0 +1,1507 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import ts from 'typescript';
+import { buildSourceGraph } from './source-graph.mjs';
+import {
+  canonicalizeStoryboardExecutions,
+  PYGMALION_STORYBOARD_CANONICAL_CONTROL,
+} from './storyboard-canonical.mjs';
+
+export const PYGMALION_STORYBOARD_ENVIRONMENT_CONTROL =
+  '/__pygmalion-storyboard/environment';
+export const PYGMALION_STORYBOARD_ENVIRONMENT_QUERY =
+  '__pygmalion_environment';
+
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
+const IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.next',
+  '.turbo',
+  'build',
+  'coverage',
+  'dist',
+  'dist-lib',
+  'node_modules',
+  'public',
+]);
+const MAX_SOURCE_BYTES = 1024 * 1024;
+const MAX_ENVIRONMENT_BYTES = 16 * 1024;
+const MAX_EXECUTION_RESULTS_BYTES = 64 * 1024 * 1024;
+
+function normalizedRelativePath(root, file) {
+  return path.relative(root, file).split(path.sep).join('/');
+}
+
+async function collectSourceFiles(root, options = {}) {
+  const files = [];
+  const maxFiles = Math.max(1, Math.min(20_000, options.maxFiles ?? 5_000));
+
+  async function visit(directory) {
+    if (files.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (files.length >= maxFiles) return;
+      if (entry.isSymbolicLink()) continue;
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name) && !entry.name.startsWith('.')) {
+          await visit(absolute);
+        }
+        continue;
+      }
+      if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+        files.push(absolute);
+      }
+    }
+  }
+
+  await visit(root);
+  return files;
+}
+
+function propertyPath(node) {
+  if (ts.isIdentifier(node)) return node.text;
+  if (ts.isPropertyAccessExpression(node)) {
+    const owner = propertyPath(node.expression);
+    return owner ? `${owner}.${node.name.text}` : node.name.text;
+  }
+  return '';
+}
+
+function literalText(node, constants = new Map()) {
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  if (ts.isIdentifier(node)) return constants.get(node.text) ?? null;
+  if (
+    ts.isAsExpression(node) ||
+    ts.isTypeAssertionExpression(node) ||
+    ts.isParenthesizedExpression(node)
+  ) {
+    return literalText(node.expression, constants);
+  }
+  return null;
+}
+
+function objectStringProperty(node, name, constants) {
+  if (!node || !ts.isObjectLiteralExpression(node)) return null;
+  for (const property of node.properties) {
+    if (!ts.isPropertyAssignment(property)) continue;
+    const propertyName = literalText(property.name, constants) ??
+      (ts.isIdentifier(property.name) ? property.name.text : null);
+    if (propertyName === name) return literalText(property.initializer, constants);
+  }
+  return null;
+}
+
+function callPath(node) {
+  return ts.isCallExpression(node) ? propertyPath(node.expression) : '';
+}
+
+function storageCall(node, constants) {
+  if (!ts.isCallExpression(node)) return null;
+  const called = callPath(node);
+  const match = called.match(
+    /^(?:(?:window|globalThis)\.)?(localStorage|sessionStorage)\.(getItem|setItem|removeItem)$/,
+  );
+  if (!match) return null;
+  return {
+    storage: match[1],
+    operation: match[2],
+    key: literalText(node.arguments[0], constants),
+    value: literalText(node.arguments[1], constants),
+  };
+}
+
+function storageCallShape(node) {
+  if (!ts.isCallExpression(node)) return null;
+  const called = callPath(node);
+  const match = called.match(
+    /^(?:(?:window|globalThis)\.)?(localStorage|sessionStorage)\.(getItem|setItem|removeItem)$/,
+  );
+  if (!match) return null;
+  return {
+    node,
+    storage: match[1],
+    operation: match[2],
+    keyNode: node.arguments[0],
+    valueNode: node.arguments[1],
+  };
+}
+
+function sourcePosition(sourceFile, node) {
+  const location = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { line: location.line + 1, column: location.character + 1 };
+}
+
+function evidenceId(sourcePath, kind, capability, line, column) {
+  return `${sourcePath}:${line}:${column}:${kind}:${capability}`;
+}
+
+function addEvidence(result, sourceFile, sourcePath, node, kind, capability, detail = {}) {
+  const { line, column } = sourcePosition(sourceFile, node);
+  const id = evidenceId(sourcePath, kind, capability, line, column);
+  if (result.evidenceById.has(id)) return id;
+  result.evidenceById.set(id, {
+    id,
+    kind,
+    capability,
+    sourcePath,
+    line,
+    column,
+    ...detail,
+  });
+  return id;
+}
+
+function dimensionId(kind, name) {
+  return `${kind}:${name}`;
+}
+
+function ensureDimension(result, kind, name, values, evidenceIdValue) {
+  const id = dimensionId(kind, name);
+  let dimension = result.dimensions.get(id);
+  if (!dimension) {
+    dimension = {
+      id,
+      kind,
+      name,
+      values: new Set(),
+      evidenceIds: new Set(),
+    };
+    result.dimensions.set(id, dimension);
+  }
+  values.forEach((value) => dimension.values.add(value));
+  dimension.evidenceIds.add(evidenceIdValue);
+  return dimension;
+}
+
+function addUnresolved(result, sourceFile, sourcePath, node, kind, reason) {
+  const { line, column } = sourcePosition(sourceFile, node);
+  result.unresolved.push({
+    id: `${sourcePath}:${line}:${column}:${kind}`,
+    kind,
+    reason,
+    sourcePath,
+    line,
+    column,
+  });
+}
+
+function jsxTagName(node) {
+  if (ts.isIdentifier(node)) return node.text;
+  if (ts.isPropertyAccessExpression(node)) return propertyPath(node);
+  return '';
+}
+
+function jsxStringAttribute(attributes, name, constants) {
+  for (const property of attributes.properties) {
+    if (!ts.isJsxAttribute(property) || property.name.text !== name) continue;
+    if (!property.initializer) return '';
+    if (ts.isStringLiteral(property.initializer)) return property.initializer.text;
+    if (ts.isJsxExpression(property.initializer)) {
+      return literalText(property.initializer.expression, constants);
+    }
+  }
+  return null;
+}
+
+function addRoute(
+  result,
+  sourceFile,
+  sourcePath,
+  node,
+  route,
+  rootSpecifiers = [],
+  hasExplicitRoot = false,
+) {
+  if (!route || !route.startsWith('/')) return;
+  const { line, column } = sourcePosition(sourceFile, node);
+  let entry = result.routes.get(route);
+  if (!entry) {
+    entry = {
+      id: `route:${route}`,
+      path: route,
+      sourcePaths: new Set(),
+      rootSpecifiers: new Set(),
+      hasExplicitRoot: false,
+      declarations: [],
+    };
+    result.routes.set(route, entry);
+  }
+  entry.sourcePaths.add(sourcePath);
+  rootSpecifiers.forEach((specifier) => entry.rootSpecifiers.add(specifier));
+  entry.hasExplicitRoot ||= hasExplicitRoot;
+  entry.declarations.push({ sourcePath, line, column });
+}
+
+function addTransition(result, sourceFile, sourcePath, node, target, kind) {
+  if (!target || !target.startsWith('/')) return;
+  const { line, column } = sourcePosition(sourceFile, node);
+  result.transitions.push({
+    id: `${sourcePath}:${line}:${column}:${kind}:${target}`,
+    sourcePath,
+    target,
+    kind,
+    line,
+    column,
+  });
+}
+
+function exportedStringConstants(source, sourcePath) {
+  const scriptKind = sourcePath.endsWith('.tsx')
+    ? ts.ScriptKind.TSX
+    : sourcePath.endsWith('.jsx')
+      ? ts.ScriptKind.JSX
+      : sourcePath.endsWith('.ts')
+        ? ts.ScriptKind.TS
+        : ts.ScriptKind.JS;
+  const sourceFile = ts.createSourceFile(
+    sourcePath,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKind,
+  );
+  const result = new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    const exported = statement.modifiers?.some(
+      (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,
+    );
+    if (!exported) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name)) continue;
+      const value = literalText(declaration.initializer);
+      if (value != null) result.set(declaration.name.text, value);
+    }
+  }
+  return result;
+}
+
+function scanSource(source, sourcePath, result, context) {
+  const scriptKind = sourcePath.endsWith('.tsx')
+    ? ts.ScriptKind.TSX
+    : sourcePath.endsWith('.jsx')
+      ? ts.ScriptKind.JSX
+      : sourcePath.endsWith('.ts')
+        ? ts.ScriptKind.TS
+        : ts.ScriptKind.JS;
+  const sourceFile = ts.createSourceFile(
+    sourcePath,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKind,
+  );
+  const constants = new Map();
+  const moduleBindings = new Map();
+  const importedNames = new Map();
+  const localDeclarations = new Map();
+
+  function collectConstants(node) {
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.initializer
+    ) {
+      const value = literalText(node.initializer, constants);
+      if (value != null) constants.set(node.name.text, value);
+    }
+    ts.forEachChild(node, collectConstants);
+  }
+
+  collectConstants(sourceFile);
+
+  function collectBindings(node) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier)) {
+      const specifier = node.moduleSpecifier.text;
+      const clause = node.importClause;
+      if (clause?.name) {
+        moduleBindings.set(clause.name.text, specifier);
+        importedNames.set(clause.name.text, 'default');
+      }
+      if (clause?.namedBindings) {
+        if (ts.isNamespaceImport(clause.namedBindings)) {
+          moduleBindings.set(clause.namedBindings.name.text, specifier);
+          importedNames.set(clause.namedBindings.name.text, '*');
+        } else {
+          for (const element of clause.namedBindings.elements) {
+            moduleBindings.set(element.name.text, specifier);
+            importedNames.set(
+              element.name.text,
+              element.propertyName?.text ?? element.name.text,
+            );
+          }
+        }
+      }
+    }
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      localDeclarations.set(node.name.text, node);
+    } else if (ts.isClassDeclaration(node) && node.name) {
+      localDeclarations.set(node.name.text, node);
+    } else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+      localDeclarations.set(node.name.text, node);
+      if (node.initializer) {
+        let dynamicSpecifier = null;
+        function findDynamicImport(current) {
+          if (
+            ts.isCallExpression(current) &&
+            current.expression.kind === ts.SyntaxKind.ImportKeyword
+          ) {
+            dynamicSpecifier ??= literalText(current.arguments[0], constants);
+          }
+          ts.forEachChild(current, findDynamicImport);
+        }
+        findDynamicImport(node.initializer);
+        if (dynamicSpecifier) moduleBindings.set(node.name.text, dynamicSpecifier);
+      }
+    }
+    ts.forEachChild(node, collectBindings);
+  }
+
+  collectBindings(sourceFile);
+  for (const [localName, specifier] of moduleBindings) {
+    const importedName = importedNames.get(localName);
+    if (!importedName || importedName === 'default' || importedName === '*') {
+      continue;
+    }
+    const target = resolveSourceSpecifier(
+      sourcePath,
+      specifier,
+      context.sourceFiles,
+    );
+    const value = target
+      ? context.exportedConstants.get(target)?.get(importedName)
+      : null;
+    if (value != null) constants.set(localName, value);
+  }
+  collectConstants(sourceFile);
+
+  function rootSpecifiers(node) {
+    const specifiers = new Set();
+    const visitedDeclarations = new Set();
+    function visitReference(current) {
+      if (ts.isIdentifier(current)) {
+        const moduleSpecifier = moduleBindings.get(current.text);
+        if (moduleSpecifier) specifiers.add(moduleSpecifier);
+        const declaration = localDeclarations.get(current.text);
+        if (declaration && !visitedDeclarations.has(declaration)) {
+          visitedDeclarations.add(declaration);
+          ts.forEachChild(declaration, visitReference);
+        }
+      }
+      if (
+        ts.isCallExpression(current) &&
+        current.expression.kind === ts.SyntaxKind.ImportKeyword
+      ) {
+        const dynamicSpecifier = literalText(current.arguments[0], constants);
+        if (dynamicSpecifier) specifiers.add(dynamicSpecifier);
+      }
+      ts.forEachChild(current, visitReference);
+    }
+    if (node) visitReference(node);
+    return [...specifiers].sort();
+  }
+
+  function normalizedRoutePath(node, rawRoute) {
+    if (!rawRoute) return rawRoute;
+    if (rawRoute.startsWith('/')) return rawRoute;
+    let current = node.parent;
+    while (current) {
+      if (ts.isObjectLiteralExpression(current)) {
+        for (const property of current.properties) {
+          if (!ts.isPropertyAssignment(property)) continue;
+          const name = literalText(property.name, constants) ??
+            (ts.isIdentifier(property.name) ? property.name.text : null);
+          if (name !== 'path') continue;
+          const parentRoute = literalText(property.initializer, constants);
+          if (!parentRoute) continue;
+          const prefix = parentRoute.startsWith('/')
+            ? parentRoute
+            : `/${parentRoute}`;
+          return `${prefix.replace(/\/+$/, '')}/${rawRoute.replace(/^\/+/, '')}`;
+        }
+      }
+      current = current.parent;
+    }
+    return `/${rawRoute.replace(/^\/+/, '')}`;
+  }
+  const storageWrappers = new Map();
+  const wrappedStorageNodes = new Set();
+
+  function collectStorageWrappers(node) {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name &&
+      node.body
+    ) {
+      const parameters = node.parameters.map((parameter) =>
+        ts.isIdentifier(parameter.name) ? parameter.name.text : null,
+      );
+      const templates = [];
+
+      function visitWrapper(current) {
+        const shape = storageCallShape(current);
+        if (shape && ts.isIdentifier(shape.keyNode)) {
+          const parameterIndex = parameters.indexOf(shape.keyNode.text);
+          if (parameterIndex >= 0) {
+            const values = new Set();
+            const written = literalText(shape.valueNode, constants);
+            if (written != null) values.add(written);
+            const parent = current.parent;
+            if (ts.isBinaryExpression(parent)) {
+              const compared =
+                parent.left === current
+                  ? literalText(parent.right, constants)
+                  : parent.right === current
+                    ? literalText(parent.left, constants)
+                    : null;
+              if (compared != null) values.add(compared);
+            }
+            templates.push({
+              node: current,
+              storage: shape.storage,
+              operation: shape.operation,
+              parameterIndex,
+              values,
+            });
+          }
+        }
+        ts.forEachChild(current, visitWrapper);
+      }
+
+      visitWrapper(node.body);
+      if (templates.length > 0) storageWrappers.set(node.name.text, templates);
+    }
+    ts.forEachChild(node, collectStorageWrappers);
+  }
+
+  collectStorageWrappers(sourceFile);
+  const wrapperCallStats = new Map(
+    [...storageWrappers.keys()].map((name) => [
+      name,
+      { total: 0, resolved: 0 },
+    ]),
+  );
+
+  function collectWrapperCalls(node) {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const templates = storageWrappers.get(node.expression.text);
+      const stats = wrapperCallStats.get(node.expression.text);
+      if (templates && stats) {
+        stats.total += 1;
+        const resolved = templates.every(
+          (template) =>
+            literalText(node.arguments[template.parameterIndex], constants) != null,
+        );
+        if (resolved) stats.resolved += 1;
+      }
+    }
+    ts.forEachChild(node, collectWrapperCalls);
+  }
+
+  collectWrapperCalls(sourceFile);
+  for (const [name, templates] of storageWrappers) {
+    const stats = wrapperCallStats.get(name);
+    if (stats && stats.total > 0 && stats.total === stats.resolved) {
+      templates.forEach((template) => wrappedStorageNodes.add(template.node));
+    }
+  }
+
+  function visit(node) {
+    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const tag = jsxTagName(node.tagName);
+      if (tag === 'Route' || tag.endsWith('.Route')) {
+        const element = node.attributes.properties.find(
+          (property) =>
+            ts.isJsxAttribute(property) &&
+            property.name.text === 'element',
+        );
+        addRoute(
+          result,
+          sourceFile,
+          sourcePath,
+          node,
+          normalizedRoutePath(
+            node,
+            jsxStringAttribute(node.attributes, 'path', constants),
+          ),
+          rootSpecifiers(
+            element && ts.isJsxAttribute(element)
+              ? element.initializer
+              : undefined,
+          ),
+          Boolean(element),
+        );
+      }
+      if (
+        tag === 'Link' ||
+        tag === 'NavLink' ||
+        tag === 'Navigate' ||
+        tag.endsWith('.Link') ||
+        tag.endsWith('.NavLink') ||
+        tag.endsWith('.Navigate')
+      ) {
+        addTransition(
+          result,
+          sourceFile,
+          sourcePath,
+          node,
+          jsxStringAttribute(node.attributes, 'to', constants),
+          'jsx-navigation',
+        );
+      }
+    }
+
+    if (ts.isObjectLiteralExpression(node)) {
+      let route = null;
+      let routeLike = false;
+      let routeRoot = null;
+      for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property)) continue;
+        const name = literalText(property.name, constants) ??
+          (ts.isIdentifier(property.name) ? property.name.text : null);
+        if (name === 'path') route = literalText(property.initializer, constants);
+        if (
+          name === 'element' ||
+          name === 'Component' ||
+          name === 'children' ||
+          name === 'loader' ||
+          name === 'lazy'
+        ) {
+          routeLike = true;
+          if (
+            name === 'element' ||
+            name === 'Component' ||
+            name === 'lazy'
+          ) {
+            routeRoot = property.initializer;
+          }
+        }
+      }
+      if (routeLike) {
+        const normalizedRoute = normalizedRoutePath(node, route);
+        addRoute(
+          result,
+          sourceFile,
+          sourcePath,
+          node,
+          normalizedRoute,
+          rootSpecifiers(routeRoot),
+          Boolean(routeRoot),
+        );
+        if (!normalizedRoute) {
+          const pathProperty = node.properties.find((property) => {
+            if (!ts.isPropertyAssignment(property)) return false;
+            const name = literalText(property.name, constants) ??
+              (ts.isIdentifier(property.name) ? property.name.text : null);
+            return name === 'path';
+          });
+          if (pathProperty) {
+            addUnresolved(
+              result,
+              sourceFile,
+              sourcePath,
+              pathProperty,
+              'route',
+              'Route path is computed at runtime.',
+            );
+          }
+        }
+      }
+    }
+
+    if (ts.isCallExpression(node)) {
+      const called = callPath(node);
+      if (
+        called === 'navigate' ||
+        called.endsWith('.navigate') ||
+        called === 'router.push' ||
+        called === 'router.replace'
+      ) {
+        addTransition(
+          result,
+          sourceFile,
+          sourcePath,
+          node,
+          literalText(node.arguments[0], constants),
+          'imperative-navigation',
+        );
+      }
+      if (
+        called === 'navigator.permissions.query' ||
+        called === 'window.navigator.permissions.query'
+      ) {
+        const permission = objectStringProperty(
+          node.arguments[0],
+          'name',
+          constants,
+        );
+        if (permission) {
+          const id = addEvidence(
+            result,
+            sourceFile,
+            sourcePath,
+            node,
+            'permission',
+            permission,
+          );
+          ensureDimension(
+            result,
+            'permission',
+            permission,
+            ['granted', 'denied', 'prompt'],
+            id,
+          );
+        } else {
+          addUnresolved(
+            result,
+            sourceFile,
+            sourcePath,
+            node,
+            'permission',
+            'Permission name is computed at runtime.',
+          );
+        }
+      }
+
+      const mediaMatch = called.match(
+        /^(?:window\.)?navigator\.mediaDevices\.(enumerateDevices|getUserMedia)$/,
+      );
+      if (mediaMatch) {
+        const operation = mediaMatch[1];
+        const id = addEvidence(
+          result,
+          sourceFile,
+          sourcePath,
+          node,
+          'media-devices',
+          operation,
+        );
+        ensureDimension(
+          result,
+          'media-devices',
+          operation,
+          operation === 'enumerateDevices'
+            ? ['available', 'empty']
+            : ['passthrough', 'not-allowed', 'not-found', 'not-readable'],
+          id,
+        );
+      }
+
+      const storage = storageCall(node, constants);
+      if (storage && (storage.key || !wrappedStorageNodes.has(node))) {
+        const capability = `${storage.storage}:${storage.key ?? '<dynamic>'}`;
+        const id = addEvidence(
+          result,
+          sourceFile,
+          sourcePath,
+          node,
+          'storage',
+          capability,
+          { operation: storage.operation },
+        );
+        if (storage.key) {
+          const values = ['missing'];
+          if (storage.operation === 'setItem' && storage.value != null) {
+            values.push(storage.value);
+          }
+          ensureDimension(result, 'storage', capability, values, id);
+        } else if (!wrappedStorageNodes.has(node)) {
+          addUnresolved(
+            result,
+            sourceFile,
+            sourcePath,
+            node,
+            'storage',
+            'Storage key is computed at runtime.',
+          );
+        }
+      }
+
+      const wrapper = ts.isIdentifier(node.expression)
+        ? storageWrappers.get(node.expression.text)
+        : null;
+      if (wrapper) {
+        for (const template of wrapper) {
+          const key = literalText(
+            node.arguments[template.parameterIndex],
+            constants,
+          );
+          if (!key) {
+            addUnresolved(
+              result,
+              sourceFile,
+              sourcePath,
+              node,
+              'storage',
+              'A local storage wrapper is called with a computed key.',
+            );
+            continue;
+          }
+          const capability = `${template.storage}:${key}`;
+          const id = addEvidence(
+            result,
+            sourceFile,
+            sourcePath,
+            node,
+            'storage',
+            capability,
+            { operation: template.operation },
+          );
+          ensureDimension(
+            result,
+            'storage',
+            capability,
+            ['missing', ...template.values],
+            id,
+          );
+        }
+      }
+    }
+
+    if (ts.isBinaryExpression(node)) {
+      const leftStorage = storageCall(node.left, constants);
+      const rightStorage = storageCall(node.right, constants);
+      const storage = leftStorage ?? rightStorage;
+      const compared = leftStorage
+        ? literalText(node.right, constants)
+        : literalText(node.left, constants);
+      if (storage?.key && compared != null) {
+        const capability = `${storage.storage}:${storage.key}`;
+        const id = addEvidence(
+          result,
+          sourceFile,
+          sourcePath,
+          node,
+          'storage',
+          capability,
+          { operation: 'compare' },
+        );
+        ensureDimension(result, 'storage', capability, ['missing', compared], id);
+      }
+    }
+
+    if (ts.isStringLiteralLike(node)) {
+      const errorNames = new Map([
+        ['NotAllowedError', 'not-allowed'],
+        ['NotFoundError', 'not-found'],
+        ['NotReadableError', 'not-readable'],
+        ['OverconstrainedError', 'overconstrained'],
+      ]);
+      const failure = errorNames.get(node.text);
+      if (failure) {
+        const id = addEvidence(
+          result,
+          sourceFile,
+          sourcePath,
+          node,
+          'media-error',
+          failure,
+        );
+        ensureDimension(
+          result,
+          'media-devices',
+          'getUserMedia',
+          [failure],
+          id,
+        );
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+}
+
+function environmentForDimension(dimension, value) {
+  if (dimension.kind === 'permission') {
+    return { permissions: { [dimension.name]: value } };
+  }
+  if (dimension.kind === 'storage') {
+    const separator = dimension.name.indexOf(':');
+    const storageName = dimension.name.slice(0, separator);
+    const key = dimension.name.slice(separator + 1);
+    return {
+      [storageName]: {
+        [key]: value === 'missing' ? null : value,
+      },
+    };
+  }
+  if (dimension.kind === 'media-devices' && dimension.name === 'enumerateDevices') {
+    return {
+      mediaDevices: {
+        devices:
+          value === 'empty'
+            ? []
+            : [
+                {
+                  kind: 'audioinput',
+                  deviceId: 'pygmalion-audio-input',
+                  groupId: 'pygmalion-device-group',
+                  label: 'Pygmalion audio input',
+                },
+              ],
+      },
+    };
+  }
+  if (dimension.kind === 'media-devices' && dimension.name === 'getUserMedia') {
+    return { mediaDevices: { getUserMedia: value } };
+  }
+  return {};
+}
+
+function mergeEnvironment(base, override) {
+  const merged = structuredClone(base);
+  for (const [key, value] of Object.entries(override)) {
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      merged[key] &&
+      typeof merged[key] === 'object' &&
+      !Array.isArray(merged[key])
+    ) {
+      merged[key] = { ...merged[key], ...structuredClone(value) };
+    } else {
+      merged[key] = structuredClone(value);
+    }
+  }
+  return merged;
+}
+
+function baselineEnvironment(dimensions) {
+  const environment = {};
+  const permissions = dimensions.filter(
+    (dimension) => dimension.kind === 'permission',
+  );
+  if (permissions.length > 0) {
+    environment.permissions = Object.fromEntries(
+      permissions.map((dimension) => [dimension.name, 'prompt']),
+    );
+  }
+  if (
+    dimensions.some(
+      (dimension) =>
+        dimension.kind === 'media-devices' &&
+        dimension.name === 'enumerateDevices',
+    )
+  ) {
+    environment.mediaDevices = { devices: [] };
+  }
+  return environment;
+}
+
+function finalizeScan(result, root) {
+  const dimensions = [...result.dimensions.values()]
+    .map((dimension) => ({
+      ...dimension,
+      values: [...dimension.values].sort(),
+      evidenceIds: [...dimension.evidenceIds].sort(),
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+  const baseline = baselineEnvironment(dimensions);
+  const capabilityDimensions = dimensions.filter(
+    (dimension) =>
+      dimension.kind === 'permission' ||
+      dimension.kind === 'media-devices',
+  );
+  const capabilityEvidence = [
+    ...new Set(
+      capabilityDimensions.flatMap((dimension) => dimension.evidenceIds),
+    ),
+  ].sort();
+  const grantedPermissions = Object.fromEntries(
+    dimensions
+      .filter((dimension) => dimension.kind === 'permission')
+      .map((dimension) => [dimension.name, 'granted']),
+  );
+  const deniedPermissions = Object.fromEntries(
+    dimensions
+      .filter((dimension) => dimension.kind === 'permission')
+      .map((dimension) => [dimension.name, 'denied']),
+  );
+  const scenarios = [
+    {
+      id: 'environment:baseline',
+      label: 'Browser baseline',
+      environment: baseline,
+      evidenceIds: [],
+    },
+    ...dimensions.flatMap((dimension) =>
+      dimension.values.map((value) => ({
+        id: `${dimension.id}:${value}`,
+        label: `${dimension.name} = ${value}`,
+        environment: mergeEnvironment(
+          baseline,
+          environmentForDimension(dimension, value),
+        ),
+        evidenceIds: dimension.evidenceIds,
+      })),
+    ),
+    ...(capabilityDimensions.length > 1
+      ? [
+          {
+            id: 'environment:browser-capabilities:available',
+            label: 'Browser capabilities available',
+            environment: mergeEnvironment(baseline, {
+              ...(Object.keys(grantedPermissions).length > 0
+                ? { permissions: grantedPermissions }
+                : {}),
+              mediaDevices: {
+                devices: [
+                  {
+                    kind: 'audioinput',
+                    deviceId: 'pygmalion-audio-input',
+                    groupId: 'pygmalion-device-group',
+                    label: 'Pygmalion audio input',
+                  },
+                ],
+                getUserMedia: 'passthrough',
+              },
+            }),
+            evidenceIds: capabilityEvidence,
+          },
+          {
+            id: 'environment:browser-capabilities:unavailable',
+            label: 'Browser capabilities unavailable',
+            environment: mergeEnvironment(baseline, {
+              ...(Object.keys(deniedPermissions).length > 0
+                ? { permissions: deniedPermissions }
+                : {}),
+              mediaDevices: {
+                devices: [],
+                getUserMedia: 'not-found',
+              },
+            }),
+            evidenceIds: capabilityEvidence,
+          },
+        ]
+      : []),
+  ];
+  return {
+    version: 1,
+    sourceRoot: root,
+    dimensions,
+    scenarios,
+    evidence: [...result.evidenceById.values()].sort((a, b) =>
+      a.id.localeCompare(b.id),
+    ),
+    routes: [...result.routes.values()]
+      .map((route) => ({
+        ...route,
+        sourcePaths: [...route.sourcePaths].sort(),
+        rootSpecifiers: [...route.rootSpecifiers].sort(),
+        declarations: route.declarations.sort((a, b) =>
+          `${a.sourcePath}:${a.line}:${a.column}`.localeCompare(
+            `${b.sourcePath}:${b.line}:${b.column}`,
+          ),
+        ),
+      }))
+      .sort((a, b) => a.path.localeCompare(b.path)),
+    transitions: result.transitions.sort((a, b) => a.id.localeCompare(b.id)),
+    unresolved: result.unresolved.sort((a, b) => a.id.localeCompare(b.id)),
+  };
+}
+
+function stripSourceDirectory(file, sourceDirectory) {
+  if (sourceDirectory === '.') return file;
+  const prefix = `${sourceDirectory}/`;
+  return file.startsWith(prefix) ? file.slice(prefix.length) : file;
+}
+
+function resolveSourceSpecifier(importer, specifier, files) {
+  let base;
+  if (specifier.startsWith('@/')) {
+    base = specifier.slice(2);
+  } else if (specifier.startsWith('./') || specifier.startsWith('../')) {
+    base = path.posix.normalize(
+      path.posix.join(path.posix.dirname(importer), specifier),
+    );
+  } else {
+    return null;
+  }
+  const candidates = [
+    base,
+    ...['.ts', '.tsx', '.js', '.jsx'].map((extension) => `${base}${extension}`),
+    ...['.ts', '.tsx', '.js', '.jsx'].map((extension) =>
+      path.posix.join(base, `index${extension}`),
+    ),
+  ];
+  return candidates.find((candidate) => files.has(candidate)) ?? null;
+}
+
+function associateRouteCandidates(manifest, graph) {
+  const dependencies = {};
+  for (const [file, values] of Object.entries(graph.dependencies)) {
+    dependencies[stripSourceDirectory(file, graph.sourceDirectory)] = values.map(
+      (value) => stripSourceDirectory(value, graph.sourceDirectory),
+    );
+  }
+
+  const dependencyClosure = (roots) => {
+    const visited = new Set(roots);
+    const queue = [...visited];
+    for (let index = 0; index < queue.length; index += 1) {
+      for (const dependency of dependencies[queue[index]] ?? []) {
+        if (visited.has(dependency)) continue;
+        visited.add(dependency);
+        queue.push(dependency);
+      }
+    }
+    return visited;
+  };
+  const sourceFiles = new Set(Object.keys(dependencies));
+
+  const scenarioByEvidence = new Map();
+  for (const scenario of manifest.scenarios) {
+    for (const evidenceId of scenario.evidenceIds) {
+      let ids = scenarioByEvidence.get(evidenceId);
+      if (!ids) {
+        ids = new Set();
+        scenarioByEvidence.set(evidenceId, ids);
+      }
+      ids.add(scenario.id);
+    }
+  }
+
+  const candidates = [];
+  const edges = [];
+  const routes = manifest.routes.map((route) => {
+    const resolvedRoots = route.sourcePaths.flatMap((sourcePath) =>
+      route.rootSpecifiers
+        .map((specifier) =>
+          resolveSourceSpecifier(sourcePath, specifier, sourceFiles),
+        )
+        .filter(Boolean),
+    );
+    const reachable = dependencyClosure(
+      resolvedRoots.length > 0
+        ? resolvedRoots
+        : route.hasExplicitRoot
+          ? []
+          : route.sourcePaths,
+    );
+    const evidenceIds = manifest.evidence
+      .filter((evidence) => reachable.has(evidence.sourcePath))
+      .map((evidence) => evidence.id);
+    const scenarioIds = new Set(['environment:baseline']);
+    for (const evidenceId of evidenceIds) {
+      for (const scenarioId of scenarioByEvidence.get(evidenceId) ?? []) {
+        scenarioIds.add(scenarioId);
+      }
+    }
+    for (const scenarioId of scenarioIds) {
+      const scenario = manifest.scenarios.find((item) => item.id === scenarioId);
+      if (!scenario) continue;
+      candidates.push({
+        id: `${route.id}:${scenario.id}`,
+        route: route.path,
+        scenarioId: scenario.id,
+        environment: scenario.environment,
+        evidenceIds: scenario.evidenceIds.filter((id) => evidenceIds.includes(id)),
+      });
+    }
+    for (const transition of manifest.transitions) {
+      if (!reachable.has(transition.sourcePath)) continue;
+      edges.push({
+        id: `${route.id}:${transition.id}`,
+        from: route.path,
+        to: transition.target,
+        kind: transition.kind,
+        evidence: {
+          sourcePath: transition.sourcePath,
+          line: transition.line,
+          column: transition.column,
+        },
+      });
+    }
+    return {
+      ...route,
+      resolvedRoots: [...new Set(resolvedRoots)].sort(),
+      evidenceIds,
+      scenarioIds: [...scenarioIds].sort(),
+    };
+  });
+
+  const knownRoutes = new Set(routes.map((route) => route.path));
+  const uniqueEdges = [
+    ...new Map(
+      edges.map((edge) => [
+        `${edge.from}:${edge.to}:${edge.kind}:${edge.evidence.sourcePath}:${edge.evidence.line}`,
+        { ...edge, unresolvedTarget: !knownRoutes.has(edge.to) },
+      ]),
+    ).values(),
+  ].sort((a, b) => a.id.localeCompare(b.id));
+
+  return {
+    ...manifest,
+    routes,
+    candidates: candidates.sort((a, b) => a.id.localeCompare(b.id)),
+    edges: uniqueEdges,
+    coverage: {
+      routes: routes.length,
+      candidates: candidates.length,
+      environmentDimensions: manifest.dimensions.length,
+      unresolved: manifest.unresolved.length,
+      unresolvedTargets: uniqueEdges.filter((edge) => edge.unresolvedTarget).length,
+    },
+  };
+}
+
+/**
+ * Finds browser-environment branches from source without importing or executing
+ * the consuming application.
+ */
+export async function scanStoryboardEnvironment(root, options = {}) {
+  const sourceRoot = path.resolve(root, options.sourceDirectory ?? '.');
+  const files = await collectSourceFiles(sourceRoot, options);
+  const result = {
+    dimensions: new Map(),
+    evidenceById: new Map(),
+    routes: new Map(),
+    transitions: [],
+    unresolved: [],
+  };
+  const sources = [];
+
+  for (const file of files) {
+    let stat;
+    try {
+      stat = await fs.stat(file);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES) continue;
+    let source;
+    try {
+      source = await fs.readFile(file, 'utf8');
+    } catch {
+      continue;
+    }
+    sources.push({
+      source,
+      sourcePath: normalizedRelativePath(sourceRoot, file),
+    });
+  }
+
+  const sourceFiles = new Set(sources.map((entry) => entry.sourcePath));
+  const exportedConstants = new Map(
+    sources.map((entry) => [
+      entry.sourcePath,
+      exportedStringConstants(entry.source, entry.sourcePath),
+    ]),
+  );
+  for (const entry of sources) {
+    scanSource(entry.source, entry.sourcePath, result, {
+      sourceFiles,
+      exportedConstants,
+    });
+  }
+
+  const manifest = finalizeScan(result, sourceRoot);
+  const graph = await buildSourceGraph(path.resolve(root), {
+    sourceDirectory: options.sourceDirectory ?? '.',
+  });
+  return associateRouteCandidates(manifest, graph);
+}
+
+export function storyboardEnvironmentBootstrapSource() {
+  const queryName = JSON.stringify(PYGMALION_STORYBOARD_ENVIRONMENT_QUERY);
+  const maxBytes = MAX_ENVIRONMENT_BYTES;
+  return `;(() => {
+  const queryName = ${queryName};
+  const encoded = new URL(location.href).searchParams.get(queryName);
+  if (!encoded || encoded.length > ${maxBytes}) return;
+  const decode = (value) => {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    return JSON.parse(new TextDecoder().decode(bytes));
+  };
+  const plainRecord = (value) =>
+    value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  const environment = plainRecord(decode(encoded));
+  if (!environment) return;
+  const storageOverlays = new Map();
+  const addStorageOverlay = (storage, entries) => {
+    const record = plainRecord(entries);
+    if (!storage || !record) return;
+    const overlay = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (
+        typeof key === 'string' &&
+        key.length <= 512 &&
+        (value === null || typeof value === 'string')
+      ) {
+        overlay[key] = value;
+      }
+    }
+    storageOverlays.set(storage, overlay);
+  };
+  addStorageOverlay(globalThis.localStorage, environment.localStorage);
+  addStorageOverlay(globalThis.sessionStorage, environment.sessionStorage);
+  if (storageOverlays.size > 0 && globalThis.Storage?.prototype) {
+    const storagePrototype = globalThis.Storage.prototype;
+    const originalGetItem = storagePrototype.getItem;
+    const originalSetItem = storagePrototype.setItem;
+    const originalRemoveItem = storagePrototype.removeItem;
+    const originalClear = storagePrototype.clear;
+    Object.defineProperties(storagePrototype, {
+      getItem: {
+        configurable: true,
+        value(key) {
+          const normalizedKey = String(key);
+          const overlay = storageOverlays.get(this);
+          return overlay && Object.hasOwn(overlay, normalizedKey)
+            ? overlay[normalizedKey]
+            : originalGetItem.call(this, normalizedKey);
+        },
+      },
+      setItem: {
+        configurable: true,
+        value(key, value) {
+          const normalizedKey = String(key);
+          const overlay = storageOverlays.get(this);
+          if (overlay && Object.hasOwn(overlay, normalizedKey)) {
+            overlay[normalizedKey] = String(value);
+            return;
+          }
+          return originalSetItem.call(this, normalizedKey, String(value));
+        },
+      },
+      removeItem: {
+        configurable: true,
+        value(key) {
+          const normalizedKey = String(key);
+          const overlay = storageOverlays.get(this);
+          if (overlay && Object.hasOwn(overlay, normalizedKey)) {
+            overlay[normalizedKey] = null;
+            return;
+          }
+          return originalRemoveItem.call(this, normalizedKey);
+        },
+      },
+      clear: {
+        configurable: true,
+        value() {
+          const overlay = storageOverlays.get(this);
+          if (overlay) {
+            for (const key of Object.keys(overlay)) overlay[key] = null;
+          }
+          return originalClear.call(this);
+        },
+      },
+    });
+  }
+
+  const permissions = plainRecord(environment.permissions);
+  if (permissions && navigator.permissions?.query) {
+    const originalQuery = navigator.permissions.query.bind(navigator.permissions);
+    const createStatus = (state) => {
+      const listeners = new Set();
+      return {
+        state,
+        onchange: null,
+        addEventListener(type, listener) {
+          if (type === 'change') listeners.add(listener);
+        },
+        removeEventListener(type, listener) {
+          if (type === 'change') listeners.delete(listener);
+        },
+        dispatchEvent(event) {
+          if (event?.type !== 'change') return true;
+          for (const listener of listeners) listener.call(this, event);
+          if (typeof this.onchange === 'function') this.onchange.call(this, event);
+          return !event?.defaultPrevented;
+        },
+      };
+    };
+    Object.defineProperty(navigator.permissions, 'query', {
+      configurable: true,
+      value(descriptor) {
+        const state = descriptor && permissions[descriptor.name];
+        return state === 'granted' || state === 'denied' || state === 'prompt'
+          ? Promise.resolve(createStatus(state))
+          : originalQuery(descriptor);
+      },
+    });
+  }
+
+  const media = plainRecord(environment.mediaDevices);
+  if (media && navigator.mediaDevices) {
+    if (Array.isArray(media.devices)) {
+      const devices = media.devices
+        .filter((device) => plainRecord(device))
+        .map((device) => ({
+          kind: device.kind,
+          deviceId: String(device.deviceId ?? ''),
+          groupId: String(device.groupId ?? ''),
+          label: String(device.label ?? ''),
+          toJSON() {
+            return {
+              kind: this.kind,
+              deviceId: this.deviceId,
+              groupId: this.groupId,
+              label: this.label,
+            };
+          },
+        }));
+      Object.defineProperty(navigator.mediaDevices, 'enumerateDevices', {
+        configurable: true,
+        value: async () => devices.map((device) => ({ ...device })),
+      });
+    }
+    const failureNames = {
+      'not-allowed': 'NotAllowedError',
+      'not-found': 'NotFoundError',
+      'not-readable': 'NotReadableError',
+      overconstrained: 'OverconstrainedError',
+    };
+    const failureName = failureNames[media.getUserMedia];
+    if (failureName) {
+      Object.defineProperty(navigator.mediaDevices, 'getUserMedia', {
+        configurable: true,
+        value: async () => {
+          throw new DOMException('Pygmalion storyboard environment', failureName);
+        },
+      });
+    }
+  }
+
+  Object.defineProperty(globalThis, '__PYGMALION_STORYBOARD_ENVIRONMENT__', {
+    configurable: true,
+    value: environment,
+  });
+  const clean = new URL(location.href);
+  clean.searchParams.delete(queryName);
+  history.replaceState(history.state, '', clean.href);
+})();`;
+}
+
+export function pygmalionStoryboardRuntimePlugin() {
+  return {
+    name: 'pygmalion-storyboard-runtime',
+    enforce: 'pre',
+    transformIndexHtml: {
+      order: 'pre',
+      handler() {
+        return [
+          {
+            tag: 'script',
+            attrs: { 'data-pygmalion-storyboard-runtime': '' },
+            children: storyboardEnvironmentBootstrapSource(),
+            injectTo: 'head-prepend',
+          },
+        ];
+      },
+    },
+  };
+}
+
+async function readExecutionResults(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > MAX_EXECUTION_RESULTS_BYTES) {
+      throw new RangeError('Storyboard execution results exceed the size limit.');
+    }
+    chunks.push(buffer);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8');
+  const parsed = JSON.parse(raw || '{}');
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    !Array.isArray(parsed.executions)
+  ) {
+    throw new TypeError('Storyboard execution results require an executions array.');
+  }
+  return parsed.executions;
+}
+
+function sendJson(response, statusCode, body) {
+  response.statusCode = statusCode;
+  response.setHeader('content-type', 'application/json; charset=utf-8');
+  response.setHeader('cache-control', 'no-store');
+  response.end(JSON.stringify(body));
+}
+
+export function pygmalionStoryboardPlugin(options) {
+  const root = path.resolve(options.root);
+  const sourceDirectory = options.sourceDirectory ?? '.';
+  const endpoint =
+    options.endpoint ?? PYGMALION_STORYBOARD_ENVIRONMENT_CONTROL;
+  const canonicalEndpoint =
+    options.canonicalEndpoint ?? PYGMALION_STORYBOARD_CANONICAL_CONTROL;
+  let cached = null;
+
+  return {
+    ...pygmalionStoryboardRuntimePlugin(),
+    name: 'pygmalion-storyboard',
+    configureServer(server) {
+      cached = scanStoryboardEnvironment(root, { sourceDirectory });
+      const invalidate = (file) => {
+        if (file.startsWith(path.resolve(root, sourceDirectory))) cached = null;
+      };
+      server.watcher?.on?.('add', invalidate);
+      server.watcher?.on?.('change', invalidate);
+      server.watcher?.on?.('unlink', invalidate);
+      server.middlewares.use(endpoint, async (request, response, next) => {
+        if (request.method !== 'GET') {
+          next();
+          return;
+        }
+        try {
+          cached ??= scanStoryboardEnvironment(root, { sourceDirectory });
+          const manifest = await cached;
+          sendJson(response, 200, manifest);
+        } catch (error) {
+          cached = null;
+          sendJson(response, 500, {
+              error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      });
+      server.middlewares.use(
+        canonicalEndpoint,
+        async (request, response, next) => {
+          if (request.method !== 'POST') {
+            next();
+            return;
+          }
+          try {
+            const executions = await readExecutionResults(request);
+            cached ??= scanStoryboardEnvironment(root, { sourceDirectory });
+            const manifest = await cached;
+            sendJson(
+              response,
+              200,
+              canonicalizeStoryboardExecutions(manifest.candidates, executions),
+            );
+          } catch (error) {
+            sendJson(
+              response,
+              error instanceof RangeError ? 413 : 400,
+              {
+                error: error instanceof Error ? error.message : String(error),
+              },
+            );
+          }
+        }
+      );
+    },
+  };
+}