@pygmalionjs/pygmalion 0.6.34 → 0.7.1

package/node/component-branches.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import { PYGMALION_ENDPOINTS } from './contract.mjs';
 import path from 'node:path';
 
 // Component branch scanner — reads a component source file and extracts the
@@ -8,8 +9,7 @@ import path from 'node:path';
 // gate) and feeds the editor's "discovered branches" list, so awareness is
 // automatic while application stays declared.
 
-export const PYGMALION_COMPONENT_BRANCHES_CONTROL =
-  '/__pygmalion-storyboard/component-branches';
+export const PYGMALION_COMPONENT_BRANCHES_CONTROL = PYGMALION_ENDPOINTS.componentBranches;
 
 const MAX_BRANCHES = 80;
 
@@ -77,7 +77,7 @@ export async function scanComponentBranchesFile(root, sourcePath) {
 export function componentBranchesMiddleware(root) {
   return async (req, res, next) => {
     if (req.method !== 'GET') return next();
-    let sourcePath = '';
+    let sourcePath;
     try {
       const url = new URL(req.url ?? '', 'http://localhost');
       sourcePath = url.searchParams.get('source') ?? '';

package/node/contract.d.mts

@@ -0,0 +1,63 @@
+// Declarations for node/contract.mjs. Types here are anonymous literal shapes on
+// purpose: the browser re-exports these values, and an emitted declaration that
+// referenced a named type from this file would carry a relative path into the
+// published bundle's types. node/public-declarations.test.mjs checks that every
+// value declared here is exported by the module.
+
+export declare const PYGMALION_ENDPOINTS: {
+  readonly devPrefix: '/__pygmalion-dev';
+  readonly devControl: '/__pygmalion-dev-control';
+  readonly sessionPrefix: '/__pygmalion-session';
+  readonly sessionControl: '/__pygmalion-design-session';
+  readonly inspectControl: '/__pygmalion-inspect';
+  readonly qaControl: '/__pygmalion-qa';
+  readonly qaCapture: '/__pygmalion-qa/capture';
+  readonly qaArtifactPrefix: '/__pygmalion-qa/artifacts/';
+  readonly previewArtifact: '/__pygmalion-route-preview/artifact';
+  readonly storyboardEnvironment: '/__pygmalion-storyboard/environment';
+  readonly storyboardCanonical: '/__pygmalion-storyboard/canonicalize';
+  readonly sourceUsage: '/__pygmalion-storyboard/source-usage';
+  readonly componentBranches: '/__pygmalion-storyboard/component-branches';
+};
+
+export declare const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX: '/progress';
+export declare const PYGMALION_REVISION_CATALOG_SUFFIX: '/catalog';
+export declare const PYGMALION_STORYBOARD_ENVIRONMENT_QUERY: '__pygmalion_environment';
+export declare const PYGMALION_SOURCE_USAGE_MAX_FILES: 100;
+
+export declare const PREVIEW_CAPTURE_PRIORITY: {
+  readonly selected: 0;
+  readonly canvas: 10;
+  readonly background: 20;
+};
+
+export declare function normalizePygmalionEndpoint(
+  value: string | undefined,
+  fallback: string,
+  name: string,
+): string;
+
+export declare function resolvePygmalionEndpoints(overrides?: {
+  devControl?: string;
+  sessionControl?: string;
+  inspectControl?: string;
+  qaCapture?: string;
+  qaArtifactPrefix?: string;
+  previewArtifact?: string | true | null;
+  previewCatalog?: string | true | null;
+  storyboardEnvironment?: string;
+  sourceUsage?: string;
+  componentBranches?: string;
+}): {
+  readonly devControl: string;
+  readonly sessionControl: string;
+  readonly inspectControl: string;
+  readonly qaCapture: string;
+  readonly qaArtifactPrefix: string;
+  readonly previewArtifact: string | null;
+  readonly previewCatalog: string | null;
+  readonly previewCaptureProgress: string | null;
+  readonly storyboardEnvironment: string;
+  readonly sourceUsage: string;
+  readonly componentBranches: string;
+};

package/node/contract.mjs

@@ -0,0 +1,175 @@
+// The wire contract the browser editor and the Node plugins share.
+//
+// Every endpoint path used to be a string literal written twice: once in the
+// plugin that serves it and once in the browser module that calls it, with a
+// comment saying "a test pins the pair". This module is the one place the
+// paths live. The plugins re-export their old names from it, and the browser
+// imports it directly (Vite bundles it; the declarations beside it type it).
+//
+// Plain JavaScript on purpose: `node/` is published as-is, and `src/` is not
+// in the package, so a TypeScript source of truth here would need a build
+// step before every test run. Keep this file free of imports and of anything
+// that needs Node or a DOM.
+
+const QA_CONTROL = '/__pygmalion-qa';
+const STORYBOARD_CONTROL = '/__pygmalion-storyboard';
+
+/** Default paths, served by the Vite plugins and called by the editor. */
+export const PYGMALION_ENDPOINTS = Object.freeze({
+  /** Proxied checkout of the mirror; frames load under `${devPrefix}/<sha>-<rev>/…`. */
+  devPrefix: '/__pygmalion-dev',
+  /** Mirror status, refresh, and the list of refs. */
+  devControl: '/__pygmalion-dev-control',
+  /** Proxied checkout of a design session. */
+  sessionPrefix: '/__pygmalion-session',
+  /** Open, check, preview, apply, and revert a design session. */
+  sessionControl: '/__pygmalion-design-session',
+  /** Source impact and write-back. */
+  inspectControl: '/__pygmalion-inspect',
+  /** Base of the visual QA service. */
+  qaControl: QA_CONTROL,
+  /** Baseline and changed captures for visual QA. */
+  qaCapture: `${QA_CONTROL}/capture`,
+  /** Prefix of the PNG artifacts a QA result links to; ends with a slash. */
+  qaArtifactPrefix: `${QA_CONTROL}/artifacts/`,
+  /** Preview artifacts: probe with GET, capture with POST. */
+  previewArtifact: '/__pygmalion-route-preview/artifact',
+  /** The generated storyboard environment manifest. */
+  storyboardEnvironment: `${STORYBOARD_CONTROL}/environment`,
+  /** Canonicalized storyboard executions (tooling only). */
+  storyboardCanonical: `${STORYBOARD_CONTROL}/canonicalize`,
+  /** Which frames use which source files. */
+  sourceUsage: `${STORYBOARD_CONTROL}/source-usage`,
+  /** Component branches scanned from one source file. */
+  componentBranches: `${STORYBOARD_CONTROL}/component-branches`,
+});
+
+/** Appended to the preview artifact endpoint for capture progress. */
+export const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX = '/progress';
+/** Appended to the preview artifact endpoint for the exact revision catalog. */
+export const PYGMALION_REVISION_CATALOG_SUFFIX = '/catalog';
+/** Query parameter that carries a storyboard environment into a previewed route. */
+export const PYGMALION_STORYBOARD_ENVIRONMENT_QUERY = '__pygmalion_environment';
+/** Most files one source-usage request may name. */
+export const PYGMALION_SOURCE_USAGE_MAX_FILES = 100;
+
+/**
+ * Where a capture request sits among captures waiting on the same identity.
+ * Smaller runs first. The editor sends a frame the designer selected ahead of
+ * a canvas being filled, and a canvas being filled ahead of one nobody is
+ * looking at; a request that says nothing sits with the canvas.
+ */
+export const PREVIEW_CAPTURE_PRIORITY = Object.freeze({
+  /** A frame the designer selected: whatever else is queued waits. */
+  selected: 0,
+  /** The canvas in front of the designer being filled. */
+  canvas: 10,
+  /** A canvas nobody is looking at yet. */
+  background: 20,
+});
+
+/**
+ * An endpoint override or its default: a path that starts with "/" and does
+ * not end with one. `name` names the option in the error.
+ */
+export function normalizePygmalionEndpoint(value, fallback, name) {
+  const endpoint = value ?? fallback;
+  if (
+    typeof endpoint !== 'string' ||
+    !endpoint.startsWith('/') ||
+    endpoint.endsWith('/')
+  ) {
+    throw new Error(`Pygmalion ${name} must start with "/" and must not end with "/"`);
+  }
+  return endpoint;
+}
+
+function normalizePrefix(value, fallback, name) {
+  const prefix = value ?? fallback;
+  if (typeof prefix !== 'string' || !prefix.startsWith('/') || !prefix.endsWith('/')) {
+    throw new Error(`Pygmalion ${name} must start and end with "/"`);
+  }
+  return prefix;
+}
+
+function normalizeOptional(value, fallback, name) {
+  if (value === undefined || value === null) return null;
+  if (value === true) return fallback;
+  return normalizePygmalionEndpoint(value, fallback, name);
+}
+
+/**
+ * The full set of paths one side talks on, from one set of overrides.
+ *
+ * Both sides call this, so a host that moves a path configures it once. The
+ * preview artifact and catalog services are opt-in: they stay `null` unless
+ * the host names a path or passes `true` for the default, which keeps "no
+ * artifact endpoint configured" meaning what it did: nothing calls it. The
+ * catalog and progress paths derive from the artifact path unless named.
+ */
+export function resolvePygmalionEndpoints(overrides = {}) {
+  const previewArtifact = normalizeOptional(
+    overrides.previewArtifact,
+    PYGMALION_ENDPOINTS.previewArtifact,
+    'endpoints.previewArtifact',
+  );
+  const derivedCatalog =
+    previewArtifact == null ? null : `${previewArtifact}${PYGMALION_REVISION_CATALOG_SUFFIX}`;
+  const previewCatalog =
+    overrides.previewCatalog === undefined
+      ? derivedCatalog
+      : normalizeOptional(
+          overrides.previewCatalog,
+          derivedCatalog ??
+            `${PYGMALION_ENDPOINTS.previewArtifact}${PYGMALION_REVISION_CATALOG_SUFFIX}`,
+          'endpoints.previewCatalog',
+        );
+  return Object.freeze({
+    devControl: normalizePygmalionEndpoint(
+      overrides.devControl,
+      PYGMALION_ENDPOINTS.devControl,
+      'endpoints.devControl',
+    ),
+    sessionControl: normalizePygmalionEndpoint(
+      overrides.sessionControl,
+      PYGMALION_ENDPOINTS.sessionControl,
+      'endpoints.sessionControl',
+    ),
+    inspectControl: normalizePygmalionEndpoint(
+      overrides.inspectControl,
+      PYGMALION_ENDPOINTS.inspectControl,
+      'endpoints.inspectControl',
+    ),
+    qaCapture: normalizePygmalionEndpoint(
+      overrides.qaCapture,
+      PYGMALION_ENDPOINTS.qaCapture,
+      'endpoints.qaCapture',
+    ),
+    qaArtifactPrefix: normalizePrefix(
+      overrides.qaArtifactPrefix,
+      PYGMALION_ENDPOINTS.qaArtifactPrefix,
+      'endpoints.qaArtifactPrefix',
+    ),
+    previewArtifact,
+    previewCatalog,
+    previewCaptureProgress:
+      previewArtifact == null
+        ? null
+        : `${previewArtifact}${PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX}`,
+    storyboardEnvironment: normalizePygmalionEndpoint(
+      overrides.storyboardEnvironment,
+      PYGMALION_ENDPOINTS.storyboardEnvironment,
+      'endpoints.storyboardEnvironment',
+    ),
+    sourceUsage: normalizePygmalionEndpoint(
+      overrides.sourceUsage,
+      PYGMALION_ENDPOINTS.sourceUsage,
+      'endpoints.sourceUsage',
+    ),
+    componentBranches: normalizePygmalionEndpoint(
+      overrides.componentBranches,
+      PYGMALION_ENDPOINTS.componentBranches,
+      'endpoints.componentBranches',
+    ),
+  });
+}

package/node/design-session.mjs

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { PYGMALION_ENDPOINTS } from './contract.mjs';
 import { execFile } from 'node:child_process';
 import fsp from 'node:fs/promises';
 import http from 'node:http';
@@ -15,8 +16,8 @@ import { resolvePygmalionPreviewViteCacheDir } from './preview-vite-cache.mjs';
 
 const execFileAsync = promisify(execFile);
 
-export const PYGMALION_SESSION_PREFIX = '/__pygmalion-session';
-export const PYGMALION_SESSION_CONTROL = '/__pygmalion-design-session';
+export const PYGMALION_SESSION_PREFIX = PYGMALION_ENDPOINTS.sessionPrefix;
+export const PYGMALION_SESSION_CONTROL = PYGMALION_ENDPOINTS.sessionControl;
 
 const DEFAULT_PREVIEW_PORT = 5220;
 const READY_TIMEOUT_MS = 60_000;
@@ -1009,6 +1010,7 @@ export function pygmalionDesignSessionPlugin(options) {
               `${error instanceof Error ? error.message : String(error)}; ${
                 restoreError instanceof Error ? restoreError.message : String(restoreError)
               }`,
+              { cause: restoreError },
             );
           }
         }

package/node/dev-mirror.mjs

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { PYGMALION_ENDPOINTS } from './contract.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import fsp from 'node:fs/promises';
 import http from 'node:http';
@@ -11,8 +12,8 @@ import { resolvePygmalionPreviewViteCacheDir } from './preview-vite-cache.mjs';
 
 const execFileAsync = promisify(execFile);
 
-export const PYGMALION_DEV_PREFIX = '/__pygmalion-dev';
-export const PYGMALION_DEV_CONTROL = '/__pygmalion-dev-control';
+export const PYGMALION_DEV_PREFIX = PYGMALION_ENDPOINTS.devPrefix;
+export const PYGMALION_DEV_CONTROL = PYGMALION_ENDPOINTS.devControl;
 
 const DEFAULT_PREVIEW_PORT = 5197;
 const READY_TIMEOUT_MS = 60_000;
@@ -195,7 +196,7 @@ function isPlainMirrorStamp(value) {
  * regenerated their own inventory into the same directory.
  */
 export async function devMirrorClaim(repoRoot, mirrorRoot, owner) {
-  let stamp = null;
+  let stamp;
   try {
     const raw = await fsp.readFile(await mirrorClaimFile(repoRoot, mirrorRoot), 'utf8');
     const parsed = JSON.parse(raw);
@@ -350,15 +351,21 @@ function escapeRegExp(value) {
  * of asking for a ref string.
  */
 export async function listSourceRefs(repoRoot, remote = 'origin') {
-  const format = '%(refname:short)%09%(objectname:short=8)%09%(refname)';
+  const format =
+    '%(refname:short)%09%(objectname:short=8)%09%(objectname)%09%(refname)';
   const read = async (...patterns) => {
     const raw = await git(repoRoot, 'for-each-ref', `--format=${format}`, ...patterns);
     if (!raw) return [];
     return raw
       .split('\n')
       .map((line) => line.split('\t'))
-      .filter((parts) => parts.length === 3 && parts[0])
-      .map(([name, commit, fullName]) => ({ name, commit, fullName }));
+      .filter((parts) => parts.length === 4 && parts[0])
+      .map(([name, commit, sourceRevision, fullName]) => ({
+        name,
+        commit,
+        sourceRevision,
+        fullName,
+      }));
   };
   const remotes = (await read(`refs/remotes/${remote}`))
     // `%(refname:short)` may abbreviate refs/remotes/origin/HEAD to just
@@ -375,15 +382,19 @@ export async function listSourceRefs(repoRoot, remote = 'origin') {
   // `dev@a0d5fdbf → 3e8cca5b`, an invitation to go backwards.
   const remoteTipPrefix = `refs/remotes/${remote}/`;
   const remoteTips = new Map(
-    remotes.map((item) => [item.fullName.slice(remoteTipPrefix.length), item.commit]),
+    remotes.map((item) => [item.fullName.slice(remoteTipPrefix.length), item]),
   );
-  const locals = (await read('refs/heads')).map((item) => ({
-    ...item,
-    // A branch the remote does not have resolves locally (the fetch fails and
-    // becomes a warning), so its own tip is the honest answer there.
-    commit: remoteTips.get(item.name) ?? item.commit,
-    kind: 'local',
-  }));
+  const locals = (await read('refs/heads')).map((item) => {
+    const remoteTip = remoteTips.get(item.name);
+    return {
+      ...item,
+      // A branch the remote does not have resolves locally (the fetch fails and
+      // becomes a warning), so its own tip is the honest answer there.
+      commit: remoteTip?.commit ?? item.commit,
+      sourceRevision: remoteTip?.sourceRevision ?? item.sourceRevision,
+      kind: 'local',
+    };
+  });
   const seen = new Set();
   return [...locals, ...remotes].filter((item) => {
     if (seen.has(item.name)) return false;
@@ -536,6 +547,7 @@ async function acquireDevMirrorReclaimMutex(lockPath, deadline) {
       if (Date.now() >= deadline) {
         throw new Error(
           'dev screen refresh on another editor server is not finished',
+          { cause: error },
         );
       }
       await new Promise((resolve) => setTimeout(resolve, 250));
@@ -634,6 +646,7 @@ export async function withDevMirrorSyncLock(
       if (Date.now() >= deadline) {
         throw new Error(
           'dev screen refresh on another editor server is not finished',
+          { cause: error },
         );
       }
       await new Promise((resolve) => setTimeout(resolve, 250));

package/node/inspect-plugin.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import { PYGMALION_ENDPOINTS } from './contract.mjs';
 import path from 'node:path';
 import MagicString from 'magic-string';
 import ts from 'typescript';
@@ -24,7 +25,7 @@ export { writeSourceOperations } from './source-operations.mjs';
 const CSS_MODULE_IMPORT_RE =
   /import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+\.module\.scss)['"]\s*;?/g;
 
-export const PYGMALION_INSPECT_CONTROL = '/__pygmalion-inspect';
+export const PYGMALION_INSPECT_CONTROL = PYGMALION_ENDPOINTS.inspectControl;
 
 function jsxScriptKind(componentFile) {
   if (/\.tsx$/.test(componentFile)) return ts.ScriptKind.TSX;
@@ -59,7 +60,7 @@ const HOVER_EVENT_ATTRIBUTES = new Set([
 
 const FOCUS_EVENT_ATTRIBUTES = new Set(['onFocus']);
 
-function primitiveJsxAttributeValue(attribute, sourceFile) {
+function primitiveJsxAttributeValue(attribute, _sourceFile) {
   if (!attribute.initializer) return true;
   if (ts.isStringLiteral(attribute.initializer)) return attribute.initializer.text;
   if (!ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression) {

package/node/preview-artifact-plugin.mjs

@@ -1,4 +1,10 @@
 import path from 'node:path';
+import {
+  PREVIEW_CAPTURE_PRIORITY,
+  PYGMALION_ENDPOINTS,
+  PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX,
+  PYGMALION_REVISION_CATALOG_SUFFIX,
+} from './contract.mjs';
 import fs from 'node:fs/promises';
 import {
   mergeRoutePreviewArtifactV3,
@@ -7,10 +13,12 @@ import {
 } from './route-preview-artifact-v3.mjs';
 import { createPreviewArtifactStore } from './preview-artifact-store.mjs';
 
-export const PYGMALION_PREVIEW_ARTIFACT_ENDPOINT =
-  '/__pygmalion-route-preview/artifact';
-export const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX = '/progress';
-export const PYGMALION_REVISION_CATALOG_SUFFIX = '/catalog';
+export const PYGMALION_PREVIEW_ARTIFACT_ENDPOINT = PYGMALION_ENDPOINTS.previewArtifact;
+export {
+  PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX,
+  PYGMALION_REVISION_CATALOG_SUFFIX,
+  PREVIEW_CAPTURE_PRIORITY,
+} from './contract.mjs';
 export const DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE =
   'artifacts/pygmalion-route-previews.json';
 
@@ -24,17 +32,6 @@ const MAX_FRAME_REQUEST_COUNT = 2_048;
 // client from parking megabytes in memory.
 const MAX_FRAME_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
 const MAX_REVISION_CATALOG_BYTES = 16 * 1024 * 1024;
-/**
- * Where a request sits among captures waiting on the same identity. Smaller
- * runs first. The editor sends a frame the designer selected ahead of a
- * canvas being filled, and a canvas being filled ahead of one nobody is
- * looking at; a request that says nothing sits with the canvas.
- */
-export const PREVIEW_CAPTURE_PRIORITY = Object.freeze({
-  selected: 0,
-  canvas: 10,
-  background: 20,
-});
 const DEFAULT_CAPTURE_PRIORITY = PREVIEW_CAPTURE_PRIORITY.canvas;
 const MAX_CAPTURE_PRIORITY = 1_000;
 const CAPTURE_PROGRESS_PHASES = new Set([
@@ -762,7 +759,7 @@ export function pygmalionPreviewArtifactPlugin({
 
   async function validateSourceLease(lease, sourceRevision) {
     if (typeof lease?.validate !== 'function') return;
-    let current = false;
+    let current;
     try {
       current = (await lease.validate()) === true;
     } catch {

package/node/preview-artifact-store.mjs

@@ -167,7 +167,9 @@ async function acquireFilesystemReclaimMutex(lockPath, deadline) {
       // Recovery of this guard would recreate the same ABA race one level down.
       // A dead guard therefore fails closed until it is removed manually.
       if (Date.now() >= deadline) {
-        throw new Error('Timed out waiting for the preview artifact store lock.');
+        throw new Error('Timed out waiting for the preview artifact store lock.', {
+          cause: error,
+        });
       }
       await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
     } finally {
@@ -1371,7 +1373,7 @@ export function createPreviewArtifactStore({
     // seen a request yet and so cannot name one.
     if (namespace === undefined) {
       const dropped = [];
-      let names = [];
+      let names;
       try {
         names = await fs.readdir(path.join(root, 'namespaces'));
       } catch {

package/node/qa-capture-plugin.mjs

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { PYGMALION_ENDPOINTS } from './contract.mjs';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import os from 'node:os';
@@ -6,8 +7,8 @@ import path from 'node:path';
 import pixelmatch from 'pixelmatch';
 import pngjs from 'pngjs';
 
-export const PYGMALION_QA_CAPTURE_ENDPOINT = '/__pygmalion-qa/capture';
-export const PYGMALION_QA_ARTIFACT_PREFIX = '/__pygmalion-qa/artifacts/';
+export const PYGMALION_QA_CAPTURE_ENDPOINT = PYGMALION_ENDPOINTS.qaCapture;
+export const PYGMALION_QA_ARTIFACT_PREFIX = PYGMALION_ENDPOINTS.qaArtifactPrefix;
 export const DEFAULT_QA_CAPTURE_MAX_FRAMES = 128;
 
 const DEFAULT_TIMEOUT_MS = 180_000;

package/node/storyboard-canonical.mjs

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
+import { PYGMALION_ENDPOINTS } from './contract.mjs';
 import { availableParallelism, totalmem } from 'node:os';
 
-export const PYGMALION_STORYBOARD_CANONICAL_CONTROL =
-  '/__pygmalion-storyboard/canonicalize';
+export const PYGMALION_STORYBOARD_CANONICAL_CONTROL = PYGMALION_ENDPOINTS.storyboardCanonical;
 
 const MAX_SNAPSHOT_BYTES = 12 * 1024 * 1024;
 const AUTO_ID_PATTERN =

package/node/storyboard-capture-runtime.mjs

@@ -487,6 +487,7 @@ export async function runStoryboardInteraction(page, interaction) {
   } catch (error) {
     throw new Error(
       `"${interaction.label}" interaction failed: ${messageOf(error)}`,
+      { cause: error },
     );
   }
   await page.waitForTimeout(settleMs);
@@ -557,7 +558,7 @@ async function assertionFailure(page, assertion) {
 export async function runStoryboardAssertion(page, assertion) {
   const timeoutMs = assertion.timeoutMs ?? 2_000;
   const startedAt = Date.now();
-  let failure = null;
+  let failure;
   do {
     failure = await assertionFailure(page, assertion);
     if (!failure || Date.now() - startedAt >= timeoutMs) break;
@@ -1583,7 +1584,6 @@ export async function captureStoryboardCase({
     if (!warm) {
       context = await atCaptureStage('setup', () =>
         browser.newContext({
-          viewport,
           deviceScaleFactor: resolveScreenshotScale(contextOptions),
           colorScheme: 'light',
           reducedMotion: 'reduce',

package/node/storyboard-environment.mjs

@@ -1,4 +1,9 @@
 import { createHash } from 'node:crypto';
+import {
+  PYGMALION_ENDPOINTS,
+  PYGMALION_SOURCE_USAGE_MAX_FILES,
+  PYGMALION_STORYBOARD_ENVIRONMENT_QUERY,
+} from './contract.mjs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import ts from 'typescript';
@@ -13,12 +18,10 @@ import {
 } from './storyboard-canonical.mjs';
 
 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';
+  PYGMALION_ENDPOINTS.storyboardEnvironment;
+export const PYGMALION_SOURCE_USAGE_CONTROL = PYGMALION_ENDPOINTS.sourceUsage;
+const MAX_SOURCE_USAGE_REQUEST = PYGMALION_SOURCE_USAGE_MAX_FILES;
+export { PYGMALION_STORYBOARD_ENVIRONMENT_QUERY };
 
 const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
 const IGNORED_DIRECTORIES = new Set([

package/node/vite.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { normalizePygmalionEndpoint } from './contract.mjs';
 import {
   PYGMALION_DEV_CONTROL,
   PYGMALION_DEV_PREFIX,
@@ -110,19 +111,7 @@ function optionalNonEmptyString(value, name) {
   return value.trim();
 }
 
-function normalizeEndpoint(value, fallback, name) {
-  const endpoint = value ?? fallback;
-  if (
-    typeof endpoint !== 'string' ||
-    !endpoint.startsWith('/') ||
-    endpoint.endsWith('/')
-  ) {
-    throw new Error(
-      `Pygmalion ${name} must start with "/" and must not end with "/"`,
-    );
-  }
-  return endpoint;
-}
+const normalizeEndpoint = normalizePygmalionEndpoint;
 
 export function definePygmalionProject(config) {
   if (!config || typeof config !== 'object') {

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.6.34",
+  "version": "0.7.1",
   "description": "Code-backed DOM design sandbox and visual QA editor",
-  "license": "UNLICENSED",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jud1thDev/pygmalion.git"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -33,6 +40,10 @@
       "types": "./runtime.d.ts",
       "default": "./node/runtime.mjs"
     },
+    "./contract": {
+      "types": "./node/contract.d.mts",
+      "default": "./node/contract.mjs"
+    },
     "./testing": {
       "types": "./dist-lib/types/testing.d.ts",
       "default": "./dist-lib/testing.js"
@@ -42,6 +53,8 @@
   "files": [
     "dist-lib",
     "docs/screen-state-contract.md",
+    "node/contract.mjs",
+    "node/contract.d.mts",
     "node/component-branches.mjs",
     "node/automatic-motion-runtime.mjs",
     "node/automatic-pseudo-runtime.mjs",
@@ -83,11 +96,13 @@
     "build": "tsc && vite build",
     "build:lib": "vite build --config vite.lib.config.ts && npm run build:types",
     "test": "node --test node/*.test.mjs src/*.test.mjs src/**/*.test.mjs",
+    "lint": "eslint .",
     "lint:language": "node scripts/lint-language.mjs",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run lint:language && npm test && npm run typecheck && npm run build:lib",
+    "prepublishOnly": "npm run lint && npm run lint:language && npm test && npm run typecheck && npm run build:lib",
     "preview": "vite preview",
-    "build:types": "node scripts/emit-types.mjs"
+    "build:types": "node scripts/emit-types.mjs",
+    "release": "node scripts/release.mjs"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -108,14 +123,19 @@
     "typescript": "^5.8.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@tailwindcss/vite": "^4.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.0",
+    "eslint": "^10.10.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.12.0",
     "happy-dom": "^20.11.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwindcss": "^4.0.0",
+    "typescript-eslint": "^8.70.0",
     "vite": "^6.0.0"
   }
 }