@pygmalionjs/pygmalion 0.6.18 → 0.6.20

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-CZSFEQgN.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-B6UY1aLt.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

package/dist-lib/types/canvas/useFlowSession.d.ts

@@ -1,3 +1,4 @@
+import { type InteractiveSessionSurface } from '../editor/interactiveSessionSurface';
 /**
  * True while a flow session still owes this screen its snapshot. Frames use
  * it exactly like the artifact-hydration gate: activation waits for the
@@ -24,11 +25,18 @@ export declare function useViewportSessionPending(page: {
  * itself — the session does that work in one instance the warm pool keeps.
  */
 export declare function useInteractiveSessionPending(page: {
-    importPageId?: string;
     id: string;
     interactiveStateId?: string;
     interactiveOptionId?: string;
-}): boolean;
+    interactiveOptionIds?: readonly string[];
+}, targetCacheKey?: string): boolean;
+/** The runner-owned live document currently reproducing this state. */
+export declare function useInteractiveSessionSurface(page: {
+    id: string;
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+    interactiveOptionIds?: readonly string[];
+}): InteractiveSessionSurface | null;
 /**
  * True while this frame holds one of the host's live screen slots, meaning it
  * renders the running app rather than its frozen capture.

package/dist-lib/types/editor/designImport.d.ts

@@ -67,6 +67,8 @@ export interface DesignScreenInteractionRunOptions {
      * The capture default is 600ms. A step's explicit `settleMs` always wins.
      */
     defaultActionSettleMs?: number;
+    /** Called after boot presets succeed and immediately before actions begin. */
+    onBeforeInteractions?: () => void;
 }
 /** A JSON-compatible value that conveys host-specific meaning without Pygmalion interpreting it. */
 export type DesignSerializable = string | number | boolean | null | readonly DesignSerializable[] | {

package/dist-lib/types/editor/flowSessionScheduler.d.ts

@@ -1,5 +1,9 @@
 import { type DesignImportController, type DesignScreenCaptureSpec } from './designImport';
+import type { ResolvedFlowPath } from './flowSessions';
+import type { ScreenFlowPath } from './screenFlows';
 import { type PageModel } from './store';
+/** Applies the active frame's own boot condition to a path-specific session. */
+export declare function resolveActivePagePath(resolved: ResolvedFlowPath, path: ScreenFlowPath, page: PageModel): ResolvedFlowPath;
 /** Diagnostic counters for the headless debug surface. */
 export declare const __flowSchedulerDebug: {
     calls: number;
@@ -69,7 +73,13 @@ type InteractivePreparationController = Pick<DesignImportController, 'prepareScr
  * The runner already waits for a trailing paint and stable geometry before it
  * serializes, so repeating the capture stability pass only delays the panel.
  */
-export declare function prepareInteractiveSessionState(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec, controller?: InteractivePreparationController | null): Promise<import("./designImport").DesignScreenCaptureReport>;
+export declare function prepareInteractiveSessionState(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec, controller?: InteractivePreparationController | null, onBeforeInteractions?: () => void): Promise<import("./designImport").DesignScreenCaptureReport>;
+export declare function interactiveSessionScreenId(page: {
+    id: string;
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+    interactiveOptionIds?: readonly string[];
+}): string;
 /**
  * Materializes one screen in its declared interactive state through the
  * screen's flow path. The prefix walks as pass-through; the target publishes
@@ -78,14 +88,14 @@ export declare function prepareInteractiveSessionState(iframe: HTMLIFrameElement
  * Returns false when no flow claims the screen — those frames keep the live
  * boot fallback.
  */
-export declare function materializePageInteractiveState(page: PageModel, previewRevision: string): boolean;
+export declare function materializePageInteractiveState(page: PageModel, previewRevision: string, targetCacheKey?: string): boolean;
 /** True while an interactive-state session still owes this page its snapshot. */
 export declare function interactiveSessionWillDeliver(page: {
-    importPageId?: string;
     id: string;
     interactiveStateId?: string;
     interactiveOptionId?: string;
-}): boolean;
+    interactiveOptionIds?: readonly string[];
+}, targetCacheKey?: string): boolean;
 /** Subscribe to interactive-state delivery changes. */
 export declare function subscribeInteractiveSessions(listener: () => void): () => void;
 /** Diagnostic counters for the interactive-state path. */

package/dist-lib/types/editor/flowSessions.d.ts

@@ -87,7 +87,7 @@ export interface FlowSessionRunnerOptions {
         preset?: DesignScreenPreset;
         interactions?: readonly DesignScreenInteraction[];
         assertions?: readonly DesignScreenAssertion[];
-    }) => Promise<DesignScreenCaptureReport>;
+    }, waypoint: ResolvedFlowWaypoint) => Promise<DesignScreenCaptureReport>;
     /** Extra settle before serializing a waypoint (fonts, trailing paints). */
     settle?: (iframe: HTMLIFrameElement, ms: number) => Promise<void>;
     /** Layout-stability wait before serializing. Defaults to waitForGeometryStability. */
@@ -95,6 +95,8 @@ export interface FlowSessionRunnerOptions {
     serialize?: (iframe: HTMLIFrameElement, fallbackUrl: string) => string | null;
     /** Writes one waypoint snapshot into the route preview store. */
     publish?: (cacheKey: string, snapshot: string) => boolean;
+    /** Releases a live document after its delivery finishes or is abandoned. */
+    onWaypointFinish?: (iframe: HTMLIFrameElement, waypoint: ResolvedFlowWaypoint, outcome: 'completed' | 'failed' | 'cancelled') => void;
     onError?: (pathId: string, error: unknown) => void;
 }
 /**
@@ -144,6 +146,11 @@ export declare function createFlowSessionRunner(options?: FlowSessionRunnerOptio
     setConcurrency(next: number): void;
     /** Session state of one screen, or null when no session claims it. */
     screenState(screenId: string): FlowScreenState | null;
+    /**
+     * Forgets a terminal delivery whose external snapshot was evicted. A
+     * running or queued screen keeps its claim and cannot be invalidated.
+     */
+    forgetScreen(screenId: string): boolean;
     /** True while the session still owes this screen its snapshot. */
     willDeliver(screenId: string): boolean;
     subscribe(listener: () => void): () => void;

package/dist-lib/types/editor/interactiveSessionSurface.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The live document currently reproducing a right-panel screen state.
+ *
+ * State preservation and state presentation are intentionally separate. The
+ * flow runner keeps this iframe alive until its exact frozen snapshot is
+ * published, while the active frame may mirror the running document
+ * immediately so capture stability never becomes interaction latency.
+ */
+export interface InteractiveSessionSurface {
+    iframe: HTMLIFrameElement;
+    screenId: string;
+}
+/** Exposes a runner-owned iframe without transferring its ownership. */
+export declare function exposeInteractiveSessionSurface(screenId: string, iframe: HTMLIFrameElement): void;
+/** Releases a surface only when the caller still owns the registered iframe. */
+export declare function releaseInteractiveSessionSurface(screenId: string, iframe: HTMLIFrameElement): void;
+export declare function getInteractiveSessionSurface(screenId: string): InteractiveSessionSurface | null;
+export declare function subscribeInteractiveSessionSurface(screenId: string, listener: () => void): () => void;

package/inspect.d.ts

@@ -0,0 +1,35 @@
+import type { InspectApplyPayload } from './dist-lib/types/lib';
+
+export interface PygmalionInspectWritebackOptions {
+  sourceDirectory?: string;
+  normalizeValue?: (property: string, value: string) => string;
+}
+
+export interface PygmalionInspectPreviewResult {
+  files: { file: string; diff: string }[];
+  affectedFiles: string[];
+}
+
+export interface PygmalionInspectWriteResult {
+  applied: number;
+  changed: number;
+  files: string[];
+}
+
+export declare function previewInspectChanges(
+  root: string,
+  input: InspectApplyPayload,
+  options?: PygmalionInspectWritebackOptions,
+): Promise<PygmalionInspectPreviewResult>;
+
+export declare function writeInspectChanges(
+  root: string,
+  input: InspectApplyPayload,
+  options?: PygmalionInspectWritebackOptions,
+): Promise<PygmalionInspectWriteResult>;
+
+export declare function findAffectedSourceFiles(
+  root: string,
+  componentFiles: string[],
+  options?: { sourceDirectory?: string },
+): Promise<string[]>;

package/node/inspect-plugin.mjs

@@ -385,7 +385,7 @@ export function pygmalionInspectPlugin({
         magic.append(`
 
 ;(() => {
-  if (!import.meta.env.DEV) return;
+  if (typeof window === 'undefined') return;
   (globalThis.__PYG_CSS_MODULES__ ||= []).push(${items});
 })();`);
       }

package/node/inspect-writeback.mjs

@@ -0,0 +1,163 @@
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { writeStyleEdit, writeTextEdit } from './inspect-plugin.mjs';
+import { createUnifiedDiff } from './source-diff.mjs';
+import { writeSourceOperations } from './source-operations.mjs';
+
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '.cjs', '.cts']);
+
+function normalizeSourceDirectory(value = 'src') {
+  return value.replace(/^\.?\//, '').replace(/\/$/, '') || '.';
+}
+
+function validateRelativeSourcePath(root, value, sourceDirectory, extensions) {
+  if (
+    typeof value !== 'string' ||
+    path.isAbsolute(value) ||
+    value.includes('\0') ||
+    value.split(/[\\/]/).includes('..') ||
+    !extensions.has(path.extname(value).toLowerCase())
+  ) {
+    throw new Error(`Source path cannot be modified: ${String(value)}`);
+  }
+  const normalized = value.split(path.sep).join('/');
+  if (
+    sourceDirectory !== '.' &&
+    normalized !== sourceDirectory &&
+    !normalized.startsWith(`${sourceDirectory}/`)
+  ) {
+    throw new Error(`Only ${sourceDirectory} source files can be modified`);
+  }
+  const absolutePath = path.resolve(root, normalized);
+  const relativePath = path.relative(root, absolutePath);
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    throw new Error('Source path escapes app root');
+  }
+  return {
+    absolutePath,
+    relativePath: relativePath.split(path.sep).join('/'),
+  };
+}
+
+function normalizeInspectChanges(input) {
+  const styles = Array.isArray(input?.styles) ? input.styles : [];
+  const texts = Array.isArray(input?.texts) ? input.texts : [];
+  const operations = Array.isArray(input?.operations) ? input.operations : [];
+  const operationCount = styles.length + texts.length + operations.length;
+  if (operationCount === 0 || operationCount > 100) {
+    throw new Error('Inspect changes must contain between 1 and 100 operations');
+  }
+  return { styles, texts, operations, operationCount };
+}
+
+function collectInspectFiles(root, changes, sourceDirectory) {
+  const files = new Map();
+  for (const style of changes.styles) {
+    const file = validateRelativeSourcePath(
+      root,
+      style?.file,
+      sourceDirectory,
+      new Set(['.scss']),
+    );
+    files.set(file.relativePath, file.absolutePath);
+  }
+  for (const text of changes.texts) {
+    const file = validateRelativeSourcePath(
+      root,
+      text?.componentFile,
+      sourceDirectory,
+      SOURCE_EXTENSIONS,
+    );
+    files.set(file.relativePath, file.absolutePath);
+  }
+  for (const operation of changes.operations) {
+    const file = validateRelativeSourcePath(
+      root,
+      operation?.identity?.componentFile,
+      sourceDirectory,
+      SOURCE_EXTENSIONS,
+    );
+    files.set(file.relativePath, file.absolutePath);
+  }
+  return files;
+}
+
+async function applyInspectChanges(root, changes, options) {
+  const results = [];
+  for (const style of changes.styles) {
+    results.push(await writeStyleEdit(root, style, options));
+  }
+  const sourceResult = changes.operations.length
+    ? await writeSourceOperations(root, changes.operations, options)
+    : null;
+  for (const text of changes.texts) {
+    results.push(await writeTextEdit(root, text, options));
+  }
+  return {
+    applied: results.length + (sourceResult?.operations ?? 0),
+    changed: results.filter((result) => result.changed).length + (sourceResult?.changed ?? 0),
+  };
+}
+
+export async function previewInspectChanges(root, input, options = {}) {
+  const appRoot = path.resolve(root);
+  const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
+  const changes = normalizeInspectChanges(input);
+  const files = collectInspectFiles(appRoot, changes, sourceDirectory);
+  const before = new Map();
+  for (const [relativePath, absolutePath] of files) {
+    before.set(relativePath, await fsp.readFile(absolutePath, 'utf8'));
+  }
+
+  const temporaryRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'pygmalion-inspect-'));
+  try {
+    for (const [relativePath, source] of before) {
+      const target = path.join(temporaryRoot, relativePath);
+      await fsp.mkdir(path.dirname(target), { recursive: true });
+      await fsp.writeFile(target, source);
+    }
+    await applyInspectChanges(temporaryRoot, changes, {
+      ...options,
+      sourceDirectory,
+    });
+    const diffs = [];
+    for (const [relativePath, source] of before) {
+      const next = await fsp.readFile(path.join(temporaryRoot, relativePath), 'utf8');
+      const diff = createUnifiedDiff(source, next, relativePath);
+      if (diff) diffs.push({ file: relativePath, diff });
+    }
+    return {
+      files: diffs,
+      affectedFiles: [...files.keys()].sort(),
+    };
+  } finally {
+    await fsp.rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+export async function writeInspectChanges(root, input, options = {}) {
+  const appRoot = path.resolve(root);
+  const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
+  const changes = normalizeInspectChanges(input);
+  const files = collectInspectFiles(appRoot, changes, sourceDirectory);
+  const backups = new Map();
+  for (const [relativePath, absolutePath] of files) {
+    backups.set(relativePath, await fsp.readFile(absolutePath, 'utf8'));
+  }
+
+  try {
+    const result = await applyInspectChanges(appRoot, changes, {
+      ...options,
+      sourceDirectory,
+    });
+    return { ...result, files: [...files.keys()].sort() };
+  } catch (error) {
+    await Promise.all(
+      [...backups].map(([relativePath, source]) =>
+        fsp.writeFile(files.get(relativePath), source),
+      ),
+    );
+    throw error;
+  }
+}

package/node/inspect.mjs

@@ -0,0 +1,5 @@
+export {
+  previewInspectChanges,
+  writeInspectChanges,
+} from './inspect-writeback.mjs';
+export { findAffectedSourceFiles } from './source-graph.mjs';

package/node/vite.mjs

@@ -84,6 +84,10 @@ import {
   validateQaCaptureRequest,
 } from './qa-capture-plugin.mjs';
 import { resolveGitSourceState } from './source-revision.mjs';
+import {
+  previewInspectChanges,
+  writeInspectChanges,
+} from './inspect-writeback.mjs';
 
 function requiredPath(value, name, base) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -414,6 +418,8 @@ export {
   writeSourceOperations,
   writeStyleEdit,
   writeTextEdit,
+  previewInspectChanges,
+  writeInspectChanges,
   convertRoutePreviewArtifactV1ToV2,
   convertRoutePreviewArtifactV2ToV1,
   createRoutePreviewArtifactV2,

package/node/webpack-loader.cjs

@@ -0,0 +1,59 @@
+const path = require('node:path');
+
+const inspectPlugins = new Map();
+
+function normalizeSourceDirectory(value) {
+  if (typeof value !== 'string') return 'src';
+  return value.replace(/^\.?\//, '').replace(/\/$/, '') || '.';
+}
+
+function isWithinSourceDirectory(relativePath, sourceDirectory) {
+  return (
+    sourceDirectory === '.' ||
+    relativePath === sourceDirectory ||
+    relativePath.startsWith(`${sourceDirectory}/`)
+  );
+}
+
+function inspectPlugin(root, sourceDirectory) {
+  const key = `${root}\0${sourceDirectory}`;
+  let promise = inspectPlugins.get(key);
+  if (!promise) {
+    promise = import('./inspect-plugin.mjs').then(({ pygmalionInspectPlugin }) =>
+      pygmalionInspectPlugin({ root, sourceDirectory }),
+    );
+    inspectPlugins.set(key, promise);
+  }
+  return promise;
+}
+
+module.exports = function pygmalionWebpackLoader(source, inputMap) {
+  const callback = this.async();
+  const options = typeof this.getOptions === 'function' ? this.getOptions() : {};
+  const root = path.resolve(options.root || this.rootContext || process.cwd());
+  const sourceDirectory = normalizeSourceDirectory(options.sourceDirectory);
+  const componentFile = path
+    .relative(root, this.resourcePath)
+    .split(path.sep)
+    .join('/');
+
+  if (
+    componentFile.startsWith('../') ||
+    path.isAbsolute(componentFile) ||
+    !isWithinSourceDirectory(componentFile, sourceDirectory)
+  ) {
+    callback(null, source, inputMap);
+    return;
+  }
+
+  inspectPlugin(root, sourceDirectory)
+    .then((plugin) => {
+      const transformed = plugin.transform(String(source), this.resourcePath);
+      if (!transformed) {
+        callback(null, source, inputMap);
+        return;
+      }
+      callback(null, transformed.code, transformed.map);
+    })
+    .catch((error) => callback(error));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.6.18",
+  "version": "0.6.20",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -23,7 +23,12 @@
       "types": "./storyboard.d.ts",
       "default": "./node/storyboard.mjs"
     },
+    "./inspect": {
+      "types": "./inspect.d.ts",
+      "default": "./node/inspect.mjs"
+    },
     "./dev-view": "./node/dev-view.vite.mjs",
+    "./webpack-loader": "./node/webpack-loader.cjs",
     "./testing": {
       "types": "./dist-lib/types/testing.d.ts",
       "default": "./dist-lib/testing.js"
@@ -40,6 +45,8 @@
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",
     "node/inspect-plugin.mjs",
+    "node/inspect.mjs",
+    "node/inspect-writeback.mjs",
     "node/preview-artifact-plugin.mjs",
     "node/preview-artifact-store.mjs",
     "node/preview-capture-worker.mjs",
@@ -59,6 +66,8 @@
     "node/storyboard-environment.mjs",
     "node/storyboard.mjs",
     "node/vite.mjs",
+    "node/webpack-loader.cjs",
+    "inspect.d.ts",
     "qa.d.ts",
     "storyboard.d.ts",
     "vite.d.ts"

package/vite.d.ts

@@ -264,6 +264,34 @@ export declare function writeTextEdit(
   options?: { sourceDirectory?: string },
 ): Promise<unknown>;
 
+export interface PygmalionInspectWritebackOptions {
+  sourceDirectory?: string;
+  normalizeValue?: (property: string, value: string) => string;
+}
+
+export interface PygmalionInspectPreviewResult {
+  files: { file: string; diff: string }[];
+  affectedFiles: string[];
+}
+
+export interface PygmalionInspectWriteResult {
+  applied: number;
+  changed: number;
+  files: string[];
+}
+
+export declare function previewInspectChanges(
+  root: string,
+  input: import('./types').InspectApplyPayload,
+  options?: PygmalionInspectWritebackOptions,
+): Promise<PygmalionInspectPreviewResult>;
+
+export declare function writeInspectChanges(
+  root: string,
+  input: import('./types').InspectApplyPayload,
+  options?: PygmalionInspectWritebackOptions,
+): Promise<PygmalionInspectWriteResult>;
+
 export interface PygmalionSourceOperationApplyResult {
   code: string;
   changed: boolean;