@pygmalionjs/pygmalion 0.6.35 → 0.7.2

package/dist-lib/testing.js

@@ -1,8 +1,48 @@
-import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-BbF5Ov5K.js";
+import { cu as l, bK as u } from "./runtime-DRkTU9eq.js";
+import { cd as w, cD as E, cE as b, cF as P, aH as R, b3 as $, bU as q } from "./runtime-DRkTU9eq.js";
+const v = {
+  mirror: ["status", "refresh", "refs"],
+  session: ["open", "check", "previewVisual", "applyVisual", "revertVisual"],
+  inspect: ["impact"],
+  qa: ["capture"],
+  preview: ["artifact", "progress", "catalog"],
+  storyboard: ["environment", "sourceUsage", "componentBranches"]
+};
+function g(m = {}, t = {}) {
+  const n = [], d = t.origin ?? "", e = (r) => {
+    var a;
+    const i = {};
+    for (const o of v[r]) {
+      const s = `${r}.${String(o)}`, c = (a = m[r]) == null ? void 0 : a[o];
+      i[String(o)] = (...p) => (n.push({ operation: s, request: p[0] }), c ? Promise.resolve(c(...p)) : Promise.reject(
+        new u({
+          operation: s,
+          code: "not_implemented",
+          message: `The memory transport has no handler for ${s}.`
+        })
+      ));
+    }
+    return i;
+  };
+  return {
+    calls: n,
+    endpoints: l(t.endpoints),
+    resolveUrl: (r) => `${d}${r}`,
+    mirror: e("mirror"),
+    session: e("session"),
+    inspect: e("inspect"),
+    qa: e("qa"),
+    preview: e("preview"),
+    storyboard: e("storyboard")
+  };
+}
 export {
-  s as FrozenRoutePreviewView,
-  a as NodeModel,
-  r as editor,
-  i as serializeNode,
-  t as setComponentRegistry
+  w as EditorRuntimeProvider,
+  E as EditorStore,
+  b as FrozenRoutePreviewView,
+  P as NodeModel,
+  R as createEditorRuntime,
+  g as createMemoryTransport,
+  $ as serializeNode,
+  q as setComponentRegistry
 };

package/dist-lib/types/{App.d.ts → EditorShell.d.ts}

@@ -9,4 +9,4 @@ export interface AppProps {
     /** Host source/revision identity included in the validation lifecycle. */
     codegenValidationScope?: string;
 }
-export declare const App: import("react").FunctionComponent<AppProps>;
+export declare const EditorShell: import("react").FunctionComponent<AppProps>;

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

@@ -1,8 +1,9 @@
 import { type ReactNode } from 'react';
 import { type FrameLodFrame } from '../editor/frameLod';
+import type { EditorRuntime } from '../core/runtime';
 export declare function resolveCameraPointerEvents(editMode: boolean, tool: string, interactionActive: boolean): 'none' | undefined;
 /** Diagnostic passthrough for headless debugging of the LOD frame inputs. */
-export declare function __debugReadEditorFrames(): (FrameLodFrame & {
+export declare function __debugReadEditorFrames(runtime: EditorRuntime): (FrameLodFrame & {
     memoKey?: string;
 })[];
 export declare function CameraLayer({ children, interactionFrameId, }: {

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

@@ -1,4 +1,4 @@
-import { type PageModel } from '../editor/store';
+import type { PageModel } from '../editor/store';
 export declare const FrameLabelBanner: import("react").FunctionComponent<{
     page: PageModel;
     active: boolean;

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

@@ -1,5 +1,5 @@
 import { type FrameInteractionPhase } from '../editor/frameInteraction';
-import { type PageModel } from '../editor/store';
+import type { PageModel } from '../editor/store';
 export declare const FrameView: import("react").FunctionComponent<{
     page: PageModel;
     active: boolean;

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

@@ -1,4 +1,4 @@
-import { type PageModel } from '../editor/store';
+import type { PageModel } from '../editor/store';
 export declare function FrozenRoutePreviewView({ page, snapshot, height, onDocumentReady, onDocumentHeightChange, onReplayIssuesChange, }: {
     page: PageModel;
     snapshot: string;

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

@@ -1,3 +1,4 @@
+import type { EditorStore } from '../editor/store';
 export declare const SECTION_PAD = 28;
 /**
  * Section bounds on the active canvas — the union of explicit section
@@ -13,7 +14,7 @@ export declare const SECTION_PAD = 28;
  * section. Understating is the safe direction, and nothing is drawn from
  * these bounds any more that a designer could see the shortfall in.
  */
-export declare function sectionBounds(): Map<string, {
+export declare function sectionBounds(editor: EditorStore): Map<string, {
     x0: number;
     y0: number;
     x1: number;

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

@@ -1,5 +1,5 @@
 import { type RoutePreviewShadowArtifact } from '../editor/routePreview';
-import { type PageModel } from '../editor/store';
+import type { PageModel } from '../editor/store';
 export declare const ShadowRoutePreview: import("react").FunctionComponent<{
     page: PageModel;
     snapshot?: string;

package/dist-lib/types/contract/errors.d.ts

@@ -0,0 +1,30 @@
+export interface TransportErrorInit {
+    /** The operation that failed, e.g. `preview.artifact`. */
+    operation: string;
+    /**
+     * A machine code: the server's own when its `error` field is one,
+     * otherwise `request_failed`, `invalid_json`, `invalid_response`,
+     * `network`, `service_not_configured`, or `not_implemented`.
+     */
+    code: string;
+    message: string;
+    status?: number;
+    retryable?: boolean;
+    preparing?: boolean;
+    details?: readonly string[];
+    /** The parsed body, for a caller that needs more than the code. */
+    payload?: unknown;
+    cause?: unknown;
+}
+export declare class TransportError extends Error {
+    readonly operation: string;
+    readonly code: string;
+    readonly status: number | undefined;
+    readonly retryable: boolean;
+    readonly preparing: boolean;
+    readonly details: readonly string[];
+    readonly payload: unknown;
+    constructor(init: TransportErrorInit);
+    /** Structural, so an error from another module instance of this class still counts. */
+    static is(value: unknown): value is TransportError;
+}

package/dist-lib/types/contract/index.d.ts

@@ -0,0 +1,5 @@
+export { PREVIEW_CAPTURE_PRIORITY, PYGMALION_ENDPOINTS, PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX, PYGMALION_REVISION_CATALOG_SUFFIX, PYGMALION_SOURCE_USAGE_MAX_FILES, PYGMALION_STORYBOARD_ENVIRONMENT_QUERY, normalizePygmalionEndpoint, resolvePygmalionEndpoints, type PreviewCapturePriority, type PygmalionEndpointOverrides, type PygmalionEndpoints, } from './paths.js';
+export { TransportError, type TransportErrorInit } from './errors.js';
+export type { EditorTransport, TransportCallOptions, TransportFetch, TransportRequestInit, TransportResponse, } from './transport.js';
+export { createViteTransport, type ViteTransportOptions } from './viteTransport.js';
+export type { ComponentBranchesRequest, InspectImpactRequest, MirrorRefreshRequest, PreviewCatalogRequest, PygmalionDesignSessionStatus, PygmalionDevMirrorStatus, PygmalionIntegrationState, PygmalionRevertResult, PygmalionSessionOperation, PygmalionSourceRef, PygmalionSourceRefs, PygmalionVisualOperation, PygmalionVisualRevertOperation, QaCaptureEnvelope, SessionApplyVisualRequest, SessionApplyVisualResponse, SessionCheckRequest, SessionMutationRequest, SessionOpenRequest, SessionPreviewVisualRequest, SessionPreviewVisualResponse, SessionRevertVisualRequest, SessionRevertVisualResponse, SourceUsageRequest, } from './types.js';

package/dist-lib/types/contract/memoryTransport.d.ts

@@ -0,0 +1,19 @@
+import { type PygmalionEndpointOverrides } from './paths.js';
+import type { EditorTransport } from './transport.js';
+type Group = keyof Omit<EditorTransport, 'endpoints' | 'resolveUrl'>;
+/** Handlers per group, each optional; the request is the first argument as on the transport. */
+export type MemoryTransportHandlers = {
+    [G in Group]?: Partial<EditorTransport[G]>;
+};
+export interface MemoryTransportCall {
+    operation: string;
+    request: unknown;
+}
+export interface MemoryTransport extends EditorTransport {
+    readonly calls: readonly MemoryTransportCall[];
+}
+export declare function createMemoryTransport(handlers?: MemoryTransportHandlers, options?: {
+    endpoints?: PygmalionEndpointOverrides;
+    origin?: string;
+}): MemoryTransport;
+export {};

package/dist-lib/types/contract/paths.d.ts

@@ -0,0 +1,57 @@
+/** Every path one side talks on, after overrides. Opt-in services are `null` until configured. */
+export interface PygmalionEndpoints {
+    readonly devControl: string;
+    readonly sessionControl: string;
+    readonly inspectControl: string;
+    readonly qaCapture: string;
+    /** Ends with a slash; QA results link PNGs under it. */
+    readonly qaArtifactPrefix: string;
+    readonly previewArtifact: string | null;
+    readonly previewCatalog: string | null;
+    readonly previewCaptureProgress: string | null;
+    readonly storyboardEnvironment: string;
+    readonly sourceUsage: string;
+    readonly componentBranches: string;
+}
+/** Overrides a host passes to both the Vite plugins and the browser transport. */
+export interface PygmalionEndpointOverrides {
+    devControl?: string;
+    sessionControl?: string;
+    inspectControl?: string;
+    qaCapture?: string;
+    qaArtifactPrefix?: string;
+    /** A path, `true` for the default, or omitted to leave the service unconfigured. */
+    previewArtifact?: string | true | null;
+    /** A path, `true` for the default derived from the artifact path, or omitted to derive it. */
+    previewCatalog?: string | true | null;
+    storyboardEnvironment?: string;
+    sourceUsage?: string;
+    componentBranches?: string;
+}
+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 type PreviewCapturePriority = (typeof PREVIEW_CAPTURE_PRIORITY)[keyof typeof PREVIEW_CAPTURE_PRIORITY];
+export declare function normalizePygmalionEndpoint(value: string | undefined, fallback: string, name: string): string;
+export declare function resolvePygmalionEndpoints(overrides?: PygmalionEndpointOverrides): PygmalionEndpoints;

package/dist-lib/types/contract/transport.d.ts

@@ -0,0 +1,69 @@
+import type { PygmalionEndpoints } from './paths.js';
+import type { ComponentBranchesRequest, InspectImpactRequest, MirrorRefreshRequest, PreviewCatalogRequest, PygmalionDesignSessionStatus, PygmalionDevMirrorStatus, PygmalionSourceRefs, QaCaptureEnvelope, SessionApplyVisualRequest, SessionApplyVisualResponse, SessionCheckRequest, SessionOpenRequest, SessionPreviewVisualRequest, SessionPreviewVisualResponse, SessionRevertVisualRequest, SessionRevertVisualResponse, SourceUsageRequest } from './types.js';
+import type { InspectImpactResult } from '../editor/host';
+import type { InspectQaCaptureRequest } from '../editor/visualQa';
+import type { PreviewArtifactTransportRequest } from '../editor/previewBootstrap';
+import type { ComponentBranch } from '../editor/screenDimensions';
+import type { CompositionSourceUsage } from '../editor/storyboardComposition';
+export interface TransportCallOptions {
+    signal?: AbortSignal;
+}
+/** The subset of RequestInit a transport sends; a real `fetch` accepts it as is. */
+export interface TransportRequestInit {
+    method: 'GET' | 'POST';
+    headers: Record<string, string>;
+    body?: string;
+    cache?: 'no-store';
+    credentials?: 'same-origin';
+    signal?: AbortSignal;
+}
+/** The subset of Response a transport reads; a real Response satisfies it, and so does a test fake. */
+export interface TransportResponse {
+    readonly ok: boolean;
+    readonly status?: number;
+    readonly statusText?: string;
+    json(): Promise<unknown>;
+}
+export type TransportFetch = (input: string, init: TransportRequestInit) => Promise<TransportResponse>;
+export interface EditorTransport {
+    /** The paths this transport talks on, after overrides. */
+    readonly endpoints: PygmalionEndpoints;
+    /** Turns a server-relative path (a QA PNG, an artifact asset) into a URL the document can load. */
+    resolveUrl(path: string): string;
+    readonly mirror: {
+        status(options?: TransportCallOptions): Promise<PygmalionDevMirrorStatus>;
+        refresh(request?: MirrorRefreshRequest, options?: TransportCallOptions): Promise<PygmalionDevMirrorStatus>;
+        refs(options?: TransportCallOptions): Promise<PygmalionSourceRefs>;
+    };
+    readonly session: {
+        open(request: SessionOpenRequest, options?: TransportCallOptions): Promise<PygmalionDesignSessionStatus>;
+        check(request: SessionCheckRequest, options?: TransportCallOptions): Promise<PygmalionDesignSessionStatus>;
+        previewVisual(request: SessionPreviewVisualRequest, options?: TransportCallOptions): Promise<SessionPreviewVisualResponse>;
+        applyVisual(request: SessionApplyVisualRequest, options?: TransportCallOptions): Promise<SessionApplyVisualResponse>;
+        revertVisual(request: SessionRevertVisualRequest, options?: TransportCallOptions): Promise<SessionRevertVisualResponse>;
+    };
+    readonly inspect: {
+        impact(request: InspectImpactRequest, options?: TransportCallOptions): Promise<InspectImpactResult>;
+    };
+    readonly qa: {
+        capture(request: InspectQaCaptureRequest, options?: TransportCallOptions): Promise<QaCaptureEnvelope>;
+    };
+    readonly preview: {
+        /**
+         * Probes or captures preview artifacts. Answers with the bundle, the
+         * unwrapped `{ok, artifact}` bundle, or a frame resolution envelope, as
+         * the server does; previewBootstrap.ts validates whichever arrives.
+         */
+        artifact(request: PreviewArtifactTransportRequest): Promise<unknown>;
+        /** The raw `progress` value; previewCaptureProgress.ts normalizes it. */
+        progress(options?: TransportCallOptions): Promise<unknown>;
+        /** The unvalidated catalog (unwrapped from `{catalog}`); revisionCatalog.ts validates it. */
+        catalog(request: PreviewCatalogRequest, options?: TransportCallOptions): Promise<unknown>;
+    };
+    readonly storyboard: {
+        /** The raw manifest; storyboardDiscovery.ts validates it. */
+        environment(options?: TransportCallOptions): Promise<unknown>;
+        sourceUsage(request: SourceUsageRequest, options?: TransportCallOptions): Promise<Record<string, CompositionSourceUsage>>;
+        componentBranches(request: ComponentBranchesRequest, options?: TransportCallOptions): Promise<readonly ComponentBranch[]>;
+    };
+}

package/dist-lib/types/contract/types.d.ts

@@ -0,0 +1,150 @@
+import type { InspectApplyPayload } from '../editor/inspect';
+export type PygmalionIntegrationState = 'up_to_date' | 'auto_merged' | 'review_required' | 'conflict' | 'offline';
+export interface PygmalionDevMirrorStatus {
+    /** 'drifted' means another server moved the shared mirror checkout; a refresh resyncs it. */
+    state: 'idle' | 'syncing' | 'ready' | 'error' | 'drifted';
+    commit: string | null;
+    shortCommit: string | null;
+    /** Git ref the mirror is tracking, or null when it follows the source branch. */
+    sourceRef: string | null;
+    syncedAt: string | null;
+    updated: boolean;
+    warning: string | null;
+    error: string | null;
+    appOrigin: string | null;
+    /** Present when the proxy child is absent or serves another ref's checkout. */
+    runtimeDrift?: {
+        expectedAppRoot: string;
+        actualAppRoot: string | null;
+    };
+}
+/** One revision the mirror can be repointed at. */
+export interface PygmalionSourceRef {
+    name: string;
+    /** Abbreviated commit used for compact branch-tip labels. */
+    commit: string;
+    /** Full immutable object id used for preview and artifact identity. */
+    sourceRevision?: string;
+    fullName: string;
+    kind: 'local' | 'remote';
+}
+/** Revisions available to `switchSource`, listed from the mirror repository. */
+export interface PygmalionSourceRefs {
+    refs: readonly PygmalionSourceRef[];
+    /** Revision followed when none is pinned. */
+    defaultRef: string | null;
+    /** Ref that renders uncommitted work. */
+    worktreeRef: string | null;
+}
+export interface PygmalionVisualOperation {
+    id: string;
+    revision: number;
+    kind: 'visual';
+    createdAt: string;
+    commitSha: string;
+    files: string[];
+    integrationState: PygmalionIntegrationState;
+}
+export interface PygmalionVisualRevertOperation {
+    id: string;
+    revision: number;
+    kind: 'visual-revert';
+    createdAt: string;
+    commitSha: string;
+    revertsOperationId: string;
+    revertsRevision: number;
+    revertsCommitSha: string;
+    recordedCommitSha: string;
+    files: string[];
+    integrationState: PygmalionIntegrationState;
+}
+export type PygmalionSessionOperation = PygmalionVisualOperation | PygmalionVisualRevertOperation;
+export interface PygmalionDesignSessionStatus {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    createdFromSha: string;
+    baseDevSha: string;
+    branchName: string | null;
+    headSha: string | null;
+    revision: number;
+    integration: {
+        state: PygmalionIntegrationState;
+        latestDevSha: string;
+        checkedAt: string;
+        affectedFiles: string[];
+        conflictFiles: string[];
+        error?: string;
+    };
+    lastOperation: PygmalionSessionOperation | null;
+    canRevert: boolean;
+    lastRevertableOperation: PygmalionVisualOperation | null;
+    lastRevert: PygmalionVisualRevertOperation | null;
+    appOrigin: string | null;
+    previewError: string | null;
+}
+export interface PygmalionRevertResult {
+    reverted: true;
+    operation: PygmalionVisualRevertOperation;
+    session: PygmalionDesignSessionStatus;
+}
+export interface MirrorRefreshRequest {
+    /** The ref to repoint the mirror at; omitted resyncs the current one. */
+    ref?: string;
+}
+export interface SessionOpenRequest {
+    sessionId: string;
+    baseDevSha: string;
+}
+export interface SessionCheckRequest {
+    sessionId: string;
+}
+export interface SessionMutationRequest {
+    sessionId: string;
+    baseDevSha: string;
+    expectedRevision: number;
+}
+export interface SessionPreviewVisualRequest extends SessionMutationRequest {
+    changes: InspectApplyPayload;
+}
+export interface SessionPreviewVisualResponse {
+    revision: number;
+    files: {
+        file: string;
+        diff: string;
+    }[];
+    affectedFiles: string[];
+}
+export interface SessionApplyVisualRequest extends SessionMutationRequest {
+    /** The revision the reviewed diff was produced against, when one was. */
+    previewRevision?: number;
+    changes: InspectApplyPayload;
+}
+export interface SessionApplyVisualResponse {
+    applied?: number;
+    session: PygmalionDesignSessionStatus;
+}
+export interface SessionRevertVisualRequest extends SessionMutationRequest {
+    expectedHeadSha: string;
+}
+export type SessionRevertVisualResponse = PygmalionRevertResult;
+export interface InspectImpactRequest {
+    componentFiles: string[];
+}
+/** The raw QA capture envelope; visualQa.ts turns it into an InspectQaResult. */
+export interface QaCaptureEnvelope {
+    baselineId: string;
+    frames?: unknown;
+    failures?: unknown;
+    complete?: unknown;
+}
+export interface PreviewCatalogRequest {
+    namespace: string;
+    sourceRevision: string;
+}
+export interface SourceUsageRequest {
+    files: readonly string[];
+}
+export interface ComponentBranchesRequest {
+    source: string;
+}

package/dist-lib/types/contract/validate.d.ts

@@ -0,0 +1,15 @@
+import type { PygmalionDesignSessionStatus, PygmalionDevMirrorStatus, PygmalionSourceRefs, QaCaptureEnvelope, SessionApplyVisualResponse, SessionPreviewVisualResponse, SessionRevertVisualResponse } from './types.js';
+import type { InspectImpactResult } from '../editor/host';
+import type { ComponentBranch } from '../editor/screenDimensions';
+import type { CompositionSourceUsage } from '../editor/storyboardComposition';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function readMirrorStatus(operation: string, body: unknown): PygmalionDevMirrorStatus;
+export declare function readSourceRefs(operation: string, body: unknown): PygmalionSourceRefs;
+export declare function readSessionStatus(operation: string, body: unknown, fallback: string): PygmalionDesignSessionStatus;
+export declare function readPreviewVisual(operation: string, body: unknown): SessionPreviewVisualResponse;
+export declare function readApplyVisual(operation: string, body: unknown): SessionApplyVisualResponse;
+export declare function readRevertVisual(operation: string, body: unknown): SessionRevertVisualResponse;
+export declare function readImpact(operation: string, body: unknown): InspectImpactResult;
+export declare function readQaEnvelope(operation: string, body: unknown): QaCaptureEnvelope;
+export declare function readSourceUsage(operation: string, body: unknown): Record<string, CompositionSourceUsage>;
+export declare function readComponentBranches(body: unknown): readonly ComponentBranch[];

package/dist-lib/types/contract/viteTransport.d.ts

@@ -0,0 +1,10 @@
+import { type PygmalionEndpointOverrides } from './paths.js';
+import type { EditorTransport, TransportFetch } from './transport.js';
+export interface ViteTransportOptions {
+    /** Defaults to the global `fetch`, looked up per call. */
+    fetch?: TransportFetch;
+    endpoints?: PygmalionEndpointOverrides;
+    /** Prefix for every request and for `resolveUrl`; empty (same origin) by default. */
+    origin?: string;
+}
+export declare function createViteTransport(options?: ViteTransportOptions): EditorTransport;

package/dist-lib/types/core/context.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from 'react';
+import type { EditorRuntime } from './runtime';
+export { useEditorRuntime, useEditorStore, useHostBindings, useHostCallbacks, } from './runtimeContext';
+/**
+ * Makes one runtime available to the editor tree below it. `<PygmalionEditor>`
+ * renders this itself; a host renders it only around package components it
+ * mounts on its own, such as the testing surface.
+ */
+export declare function EditorRuntimeProvider({ runtime, children, }: {
+    runtime: EditorRuntime;
+    children: ReactNode;
+}): import("react").JSX.Element;