@pygmalionjs/pygmalion 0.2.7 → 0.2.8

package/node/vite.mjs

@@ -25,6 +25,32 @@ import {
   prepareSourceOperations,
   writeSourceOperations,
 } from './source-operations.mjs';
+import {
+  PYGMALION_STORYBOARD_ENVIRONMENT_CONTROL,
+  PYGMALION_STORYBOARD_ENVIRONMENT_QUERY,
+  pygmalionStoryboardPlugin,
+  pygmalionStoryboardRuntimePlugin,
+  scanStoryboardEnvironment,
+  storyboardEnvironmentBootstrapSource,
+} from './storyboard-environment.mjs';
+import {
+  canonicalizeStoryboardExecutions,
+  executeStoryboardCandidates,
+  fingerprintStoryboardSnapshot,
+  normalizeStoryboardSnapshot,
+  PYGMALION_STORYBOARD_CANONICAL_CONTROL,
+  recommendedStoryboardExecutionConcurrency,
+} from './storyboard-canonical.mjs';
+import {
+  convertRoutePreviewArtifactV1ToV2,
+  convertRoutePreviewArtifactV2ToV1,
+  createRoutePreviewArtifactV2,
+  isSafeFrozenRoutePreviewSnapshot,
+  reconstructRoutePreviewArtifactSnapshot,
+  reconstructRoutePreviewArtifactSnapshots,
+  ROUTE_PREVIEW_ARTIFACT_V2_LIMITS,
+  validateRoutePreviewArtifactV2,
+} from './route-preview-artifact-v2.mjs';
 
 function requiredPath(value, name, base) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -117,10 +143,17 @@ export function resolvePygmalionProject(config) {
 }
 
 export function createPygmalionVitePlugins(config) {
-  if (process.env.PYGMALION_PREVIEW_MODE === '1') return [];
+  if (process.env.PYGMALION_PREVIEW_MODE === '1') {
+    return [pygmalionStoryboardRuntimePlugin()];
+  }
 
   const project = resolvePygmalionProject(config);
-  const plugins = [];
+  const plugins = [
+    pygmalionStoryboardPlugin({
+      root: project.appRoot,
+      sourceDirectory: project.sourceDirectory,
+    }),
+  ];
 
   if (project.inspect !== false) {
     plugins.push(
@@ -210,9 +243,21 @@ export {
   PYGMALION_INSPECT_CONTROL,
   PYGMALION_SESSION_CONTROL,
   PYGMALION_SESSION_PREFIX,
+  PYGMALION_STORYBOARD_ENVIRONMENT_CONTROL,
+  PYGMALION_STORYBOARD_ENVIRONMENT_QUERY,
+  PYGMALION_STORYBOARD_CANONICAL_CONTROL,
+  canonicalizeStoryboardExecutions,
+  executeStoryboardCandidates,
+  fingerprintStoryboardSnapshot,
+  normalizeStoryboardSnapshot,
+  recommendedStoryboardExecutionConcurrency,
   pygmalionDesignSessionPlugin,
   pygmalionDevMirrorPlugin,
   pygmalionInspectPlugin,
+  pygmalionStoryboardPlugin,
+  pygmalionStoryboardRuntimePlugin,
+  scanStoryboardEnvironment,
+  storyboardEnvironmentBootstrapSource,
   buildSourceGraph,
   collectAffectedSourceFiles,
   findAffectedSourceFiles,
@@ -221,4 +266,12 @@ export {
   writeSourceOperations,
   writeStyleEdit,
   writeTextEdit,
+  convertRoutePreviewArtifactV1ToV2,
+  convertRoutePreviewArtifactV2ToV1,
+  createRoutePreviewArtifactV2,
+  isSafeFrozenRoutePreviewSnapshot,
+  reconstructRoutePreviewArtifactSnapshot,
+  reconstructRoutePreviewArtifactSnapshots,
+  ROUTE_PREVIEW_ARTIFACT_V2_LIMITS,
+  validateRoutePreviewArtifactV2,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -32,9 +32,12 @@
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",
     "node/inspect-plugin.mjs",
+    "node/route-preview-artifact-v2.mjs",
     "node/source-diff.mjs",
     "node/source-graph.mjs",
     "node/source-operations.mjs",
+    "node/storyboard-canonical.mjs",
+    "node/storyboard-environment.mjs",
     "node/vite.mjs",
     "types.d.ts",
     "testing.d.ts",

package/types.d.ts

@@ -86,6 +86,30 @@ export type DesignSerializable =
   | { readonly [key: string]: DesignSerializable };
 
 export type DesignScreenPreset = Readonly<Record<string, DesignSerializable>>;
+export type StoryboardPermissionState = 'granted' | 'denied' | 'prompt';
+export type StoryboardMediaFailure =
+  | 'not-allowed'
+  | 'not-found'
+  | 'not-readable'
+  | 'overconstrained';
+
+export interface StoryboardMediaDevice {
+  kind: 'audioinput' | 'audiooutput' | 'videoinput';
+  deviceId: string;
+  groupId?: string;
+  label?: string;
+}
+
+export interface StoryboardEnvironment {
+  localStorage?: Readonly<Record<string, string | null>>;
+  sessionStorage?: Readonly<Record<string, string | null>>;
+  permissions?: Readonly<Record<string, StoryboardPermissionState>>;
+  mediaDevices?: {
+    devices?: readonly StoryboardMediaDevice[];
+    getUserMedia?: 'passthrough' | StoryboardMediaFailure;
+  };
+}
+
 export type DesignScreenAssertionVisibility = 'visible' | 'hidden';
 
 export interface DesignScreenAttributeAssertion {
@@ -124,6 +148,7 @@ export interface DesignImportPage {
   state?: string;
   scenarioId?: string;
   interactions?: readonly DesignScreenInteraction[];
+  environment?: StoryboardEnvironment;
   preset?: DesignScreenPreset;
   assertions?: readonly DesignScreenAssertion[];
 }
@@ -353,6 +378,7 @@ export interface DesignImportInitialPage extends InitialPageDef {
   state?: string;
   scenarioId?: string;
   interactions?: DesignScreenInteraction[];
+  environment?: StoryboardEnvironment;
   preset?: DesignScreenPreset;
   assertions?: DesignScreenAssertion[];
 }
@@ -412,10 +438,34 @@ export declare function setPygmalionAppOrigin(origin: string): void;
 export declare function setPygmalionPreviewRevision(revision: string): void;
 /** Sets the number of actual app iframes to run simultaneously in the entire editor. */
 export declare function setPygmalionPreviewConcurrency(value: number): void;
+/** Returns the adaptive live-preview lane count for the current browser. */
+export declare function getRecommendedPygmalionPreviewConcurrency(
+  capabilities?: {
+    hardwareConcurrency?: number;
+    deviceMemory?: number;
+  },
+): number;
 /** Removes all route screens fixed in memory and IndexedDB. If a namespace is given, only the corresponding cache is deleted. */
 export declare function clearPygmalionPreviewCache(namespace?: string): void;
-
-export interface RoutePreviewArtifactBundle {
+export declare const STORYBOARD_ENVIRONMENT_QUERY: string;
+export declare const STORYBOARD_ENVIRONMENT_CONTROL: string;
+export declare function createStoryboardRouteUrl(
+  appOrigin: string,
+  route: string,
+  environment?: StoryboardEnvironment,
+): string;
+export declare function setStoryboardBaselineEnvironment(
+  environment?: StoryboardEnvironment,
+): void;
+export declare function getStoryboardBaselineEnvironment():
+  | StoryboardEnvironment
+  | undefined;
+export declare function mergeStoryboardEnvironment(
+  base?: StoryboardEnvironment,
+  override?: StoryboardEnvironment,
+): StoryboardEnvironment | undefined;
+
+export interface RoutePreviewArtifactBundleV1 {
   version: 1;
   namespace: string;
   /** Source SHA at the time of creation. It must match the value before the first ':' of runtime previewRevision. */
@@ -423,6 +473,36 @@ export interface RoutePreviewArtifactBundle {
   snapshots: Record<string, string>;
 }
 
+export interface RoutePreviewArtifactBundleV2 {
+  version: 2;
+  namespace: string;
+  sourceRevision?: string;
+  assets: {
+    head: Record<string, string>;
+    stylesheets: Record<string, string>;
+  };
+  frames: Record<
+    string,
+    {
+      document: {
+        doctype: string;
+        htmlAttributes: string;
+        headAttributes: string;
+        bodyAttributes: string;
+      };
+      head: {
+        kind: 'head' | 'stylesheet';
+        hash: string;
+      }[];
+      body: string;
+    }
+  >;
+}
+
+export type RoutePreviewArtifactBundle =
+  | RoutePreviewArtifactBundleV1
+  | RoutePreviewArtifactBundleV2;
+
 export interface InitialPageDef {
   name: string;
   /** Owning canvas, such as 'Design System' or 'Screens'. Defaults to 'default'. */
@@ -453,6 +533,7 @@ export interface InitialPageDef {
   state?: string;
   scenarioId?: string;
   interactions?: DesignScreenInteraction[];
+  environment?: StoryboardEnvironment;
   preset?: DesignScreenPreset;
   assertions?: DesignScreenAssertion[];
 }
@@ -821,7 +902,7 @@ export declare function PygmalionEditor(props: {
   previewCacheNamespace?: string;
   /** A canonical screen snapshot created during build. When the namespace matches, it is injected into the cache before the first render. */
   previewArtifacts?: RoutePreviewArtifactBundle;
-  /** Number of actual app previews to run simultaneously. Default is 12, safe upper limit is 32. */
+  /** Number of actual app previews to run simultaneously. Defaults to an adaptive 12–32 lanes. */
   previewConcurrency?: number;
   /** Controlled by external status such as host route ▶ Whether the preview is opened or not. */
   previewOpen?: boolean;
@@ -839,6 +920,10 @@ export declare function PygmalionEditor(props: {
   onInspectPreview?: (payload: InspectApplyPayload) => Promise<InspectPreviewResult>;
   /** Check the reverse dependency closure of the changed source file. */
   onInspectImpact?: (componentFiles: string[]) => Promise<InspectImpactResult>;
+  /** Detect portable browser branches from source before route frames boot. Default true. */
+  storyboardDiscovery?: boolean;
+  /** Vite endpoint that returns the generated generic storyboard environment manifest. */
+  storyboardDiscoveryEndpoint?: string;
 }): ReactElement;
 
 /** Edit token values ​​in code (live override + onTokensChange notification). */

package/vite.d.ts

@@ -180,6 +180,268 @@ export interface PygmalionSourceGraphOptions {
   sourceDirectory?: string;
 }
 
+export type PygmalionStoryboardEnvironmentKind =
+  | 'permission'
+  | 'media-devices'
+  | 'storage';
+
+export interface PygmalionStoryboardEnvironmentEvidence {
+  id: string;
+  kind: string;
+  capability: string;
+  sourcePath: string;
+  line: number;
+  column: number;
+  operation?: string;
+}
+
+export interface PygmalionStoryboardEnvironmentDimension {
+  id: string;
+  kind: PygmalionStoryboardEnvironmentKind;
+  name: string;
+  values: string[];
+  evidenceIds: string[];
+}
+
+export interface PygmalionStoryboardEnvironmentScenario {
+  id: string;
+  label: string;
+  environment: import('./types').StoryboardEnvironment;
+  evidenceIds: string[];
+}
+
+export interface PygmalionStoryboardEnvironmentUnresolved {
+  id: string;
+  kind: string;
+  reason: string;
+  sourcePath: string;
+  line: number;
+  column: number;
+}
+
+export interface PygmalionStoryboardEnvironmentManifest {
+  version: 1;
+  sourceRoot: string;
+  dimensions: PygmalionStoryboardEnvironmentDimension[];
+  scenarios: PygmalionStoryboardEnvironmentScenario[];
+  evidence: PygmalionStoryboardEnvironmentEvidence[];
+  routes: {
+    id: string;
+    path: string;
+    sourcePaths: string[];
+    rootSpecifiers: string[];
+    resolvedRoots: string[];
+    hasExplicitRoot: boolean;
+    declarations: {
+      sourcePath: string;
+      line: number;
+      column: number;
+    }[];
+    evidenceIds: string[];
+    scenarioIds: string[];
+  }[];
+  candidates: {
+    id: string;
+    route: string;
+    scenarioId: string;
+    environment: import('./types').StoryboardEnvironment;
+    evidenceIds: string[];
+  }[];
+  edges: {
+    id: string;
+    from: string;
+    to: string;
+    kind: string;
+    evidence: {
+      sourcePath: string;
+      line: number;
+      column: number;
+    };
+    unresolvedTarget: boolean;
+  }[];
+  coverage: {
+    routes: number;
+    candidates: number;
+    environmentDimensions: number;
+    unresolved: number;
+    unresolvedTargets: number;
+  };
+  unresolved: PygmalionStoryboardEnvironmentUnresolved[];
+}
+
+export interface PygmalionStoryboardEnvironmentScanOptions {
+  sourceDirectory?: string;
+  maxFiles?: number;
+}
+
+export interface PygmalionStoryboardCandidateExecution {
+  candidateId: string;
+  status: 'captured' | 'failed';
+  snapshot?: string;
+  error?: string;
+}
+
+export interface PygmalionStoryboardCandidateExecutionContext {
+  signal: AbortSignal;
+  index: number;
+  total: number;
+}
+
+export type PygmalionStoryboardCanonicalWarningCode =
+  | 'branch-not-observed'
+  | 'capture-failed'
+  | 'duplicate-execution'
+  | 'invalid-snapshot'
+  | 'missing-execution'
+  | 'unknown-candidate';
+
+export interface PygmalionStoryboardCanonicalWarning {
+  code: PygmalionStoryboardCanonicalWarningCode;
+  severity: 'warning' | 'error';
+  candidateId: string;
+  route: string;
+  scenarioId: string;
+  evidenceIds: string[];
+  message: string;
+}
+
+export interface PygmalionStoryboardCanonicalFrame {
+  id: string;
+  fingerprint: string;
+  snapshot: string;
+  candidateIds: string[];
+  routes: string[];
+  scenarioIds: string[];
+  evidenceIds: string[];
+}
+
+export interface PygmalionStoryboardCanonicalManifest {
+  version: 1;
+  frames: PygmalionStoryboardCanonicalFrame[];
+  aliases: Record<string, string>;
+  warnings: PygmalionStoryboardCanonicalWarning[];
+  coverage: {
+    expected: number;
+    executed: number;
+    captured: number;
+    canonical: number;
+    duplicates: number;
+    failed: number;
+    missing: number;
+    unreproduced: number;
+    complete: boolean;
+  };
+}
+
+export declare function normalizeStoryboardSnapshot(snapshot: string): string | null;
+export declare function fingerprintStoryboardSnapshot(snapshot: string): string | null;
+export declare function canonicalizeStoryboardExecutions(
+  candidates: PygmalionStoryboardEnvironmentManifest['candidates'],
+  executions: PygmalionStoryboardCandidateExecution[],
+): PygmalionStoryboardCanonicalManifest;
+export declare function executeStoryboardCandidates(
+  candidates: PygmalionStoryboardEnvironmentManifest['candidates'],
+  capture: (
+    candidate: PygmalionStoryboardEnvironmentManifest['candidates'][number],
+    context: PygmalionStoryboardCandidateExecutionContext,
+  ) => string | Promise<string>,
+  options?: {
+    concurrency?: number;
+    timeoutMs?: number;
+  },
+): Promise<PygmalionStoryboardCandidateExecution[]>;
+export declare function recommendedStoryboardExecutionConcurrency(
+  capabilities?: {
+    parallelism?: number;
+    totalMemoryBytes?: number;
+  },
+): number;
+
+export interface PygmalionRoutePreviewArtifactV1 {
+  version: 1;
+  namespace: string;
+  sourceRevision?: string;
+  snapshots: Record<string, string>;
+}
+
+export interface PygmalionRoutePreviewArtifactV2 {
+  version: 2;
+  namespace: string;
+  sourceRevision?: string;
+  assets: {
+    head: Record<string, string>;
+    stylesheets: Record<string, string>;
+  };
+  frames: Record<
+    string,
+    {
+      document: {
+        doctype: string;
+        htmlAttributes: string;
+        headAttributes: string;
+        bodyAttributes: string;
+      };
+      head: {
+        kind: 'head' | 'stylesheet';
+        hash: string;
+      }[];
+      body: string;
+    }
+  >;
+}
+
+export interface PygmalionRoutePreviewArtifactV2Validation {
+  valid: boolean;
+  errors: string[];
+  bytes: number;
+}
+
+export declare const ROUTE_PREVIEW_ARTIFACT_V2_LIMITS: Readonly<
+  Record<string, number>
+>;
+export declare function isSafeFrozenRoutePreviewSnapshot(
+  snapshot: unknown,
+): snapshot is string;
+export declare function createRoutePreviewArtifactV2(input: {
+  namespace: string;
+  sourceRevision?: string;
+  snapshots: Record<string, string>;
+} | PygmalionRoutePreviewArtifactV1): PygmalionRoutePreviewArtifactV2;
+export declare function convertRoutePreviewArtifactV1ToV2(
+  bundle: PygmalionRoutePreviewArtifactV1,
+): PygmalionRoutePreviewArtifactV2;
+export declare function convertRoutePreviewArtifactV2ToV1(
+  bundle: PygmalionRoutePreviewArtifactV2,
+): PygmalionRoutePreviewArtifactV1;
+export declare function validateRoutePreviewArtifactV2(
+  bundle: unknown,
+): PygmalionRoutePreviewArtifactV2Validation;
+export declare function reconstructRoutePreviewArtifactSnapshot(
+  bundle: PygmalionRoutePreviewArtifactV2,
+  frameId: string,
+): string | null;
+export declare function reconstructRoutePreviewArtifactSnapshots(
+  bundle: PygmalionRoutePreviewArtifactV2,
+): Record<string, string>;
+
+export declare function scanStoryboardEnvironment(
+  root: string,
+  options?: PygmalionStoryboardEnvironmentScanOptions,
+): Promise<PygmalionStoryboardEnvironmentManifest>;
+
+export declare function storyboardEnvironmentBootstrapSource(): string;
+export declare function pygmalionStoryboardRuntimePlugin(): PluginOption;
+export declare function pygmalionStoryboardPlugin(options: {
+  root: string;
+  sourceDirectory?: string;
+  endpoint?: string;
+  canonicalEndpoint?: string;
+}): PluginOption;
+
+export declare const PYGMALION_STORYBOARD_CANONICAL_CONTROL: string;
+export declare const PYGMALION_STORYBOARD_ENVIRONMENT_CONTROL: string;
+export declare const PYGMALION_STORYBOARD_ENVIRONMENT_QUERY: string;
+
 export interface PygmalionSourceGraph {
   sourceDirectory: string;
   files: string[];