@pygmalionjs/pygmalion 0.2.10 → 0.2.12

package/types.d.ts

@@ -1,6 +1,11 @@
 // Package public type — used by the host repo's tsc to interpret pygmalion import.
 // (lib build doesn't generate d.ts , so keep it by hand — in sync with src/lib.tsx · src/editor/registry.ts )
-import type { ComponentType, ReactElement } from 'react';
+import type {
+  ComponentType,
+  CSSProperties,
+  ReactElement,
+  ReactNode,
+} from 'react';
 
 export interface RegistryEntry {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -26,6 +31,126 @@ export interface RegistryEntry {
 
 export type ComponentRegistry = Record<string, RegistryEntry>;
 
+export type DesignCatalogKind =
+  'icons' | 'design-tokens' | 'atoms' | 'components';
+
+export interface DesignCatalogItem {
+  id: string;
+  name: string;
+  section: string;
+  sourcePath?: string;
+  codeName?: string;
+  description?: string;
+}
+
+export interface DesignCatalogPageDescriptor {
+  id: string;
+  name: string;
+  section: string;
+}
+
+export interface DesignCatalogFrame {
+  width: number;
+  height: number;
+}
+
+export interface DesignCatalogBuild {
+  registry: ComponentRegistry;
+  collection: DesignImportCollection;
+}
+
+export interface DesignGalleryCatalogOptions<T extends DesignCatalogItem> {
+  kind: 'icons' | 'design-tokens';
+  items: readonly T[];
+  expectedCount?: number;
+  pageFor: (item: T) => DesignCatalogPageDescriptor;
+  renderPreview: (item: T) => ReactNode;
+  secondaryLabel?: (item: T) => ReactNode;
+  frame?:
+    | DesignCatalogFrame
+    | ((
+        page: DesignCatalogPageDescriptor,
+        items: readonly T[],
+      ) => DesignCatalogFrame);
+  minimumColumnWidth?: number;
+  registryPrefix?: string;
+}
+
+export interface DesignComponentCatalogOptions {
+  kind: 'atoms' | 'components';
+  items: readonly DesignCatalogItem[];
+  registry: ComponentRegistry;
+  expectedCount?: number;
+  maxVariantCells?: number;
+  registryPrefix?: string;
+}
+
+export interface DesignComponentVariantMatrix {
+  row?: readonly [name: string, values: readonly string[]];
+  column?: readonly [name: string, values: readonly string[]];
+  fixed: readonly (readonly [name: string, value: string])[];
+  additional: readonly (readonly [name: string, values: readonly string[]])[];
+}
+
+export interface PygmalionCatalogDocumentProps {
+  title: ReactNode;
+  eyebrow?: ReactNode;
+  description?: ReactNode;
+  version?: ReactNode;
+  meta?: ReactNode;
+  children: ReactNode;
+  headerBackground?: string;
+  headerColor?: string;
+  bodyBackground?: string;
+  bodyGap?: number;
+}
+
+export interface PygmalionCatalogSectionProps {
+  title: ReactNode;
+  count?: number;
+  description?: ReactNode;
+  children: ReactNode;
+  tone?: 'plain' | 'tinted';
+}
+
+export interface PygmalionCatalogMatrixProps {
+  rows: readonly string[];
+  columns: readonly string[];
+  cornerLabel?: ReactNode;
+  renderCell: (row: string, column: string) => ReactNode;
+  renderRowLabel?: (row: string) => ReactNode;
+  renderColumnLabel?: (column: string) => ReactNode;
+  boundary?: boolean;
+  cellStyle?: CSSProperties;
+}
+
+export declare function PygmalionCatalogDocument(
+  props: PygmalionCatalogDocumentProps,
+): ReactElement;
+export declare function PygmalionCatalogSection(
+  props: PygmalionCatalogSectionProps,
+): ReactElement;
+export declare function PygmalionCatalogMatrix(
+  props: PygmalionCatalogMatrixProps,
+): ReactElement;
+
+export declare function designCatalogKey(value: string): string;
+export declare function designCatalogRegistryName(
+  kind: DesignCatalogKind,
+  id: string,
+  prefix?: string,
+): string;
+export declare function createDesignGalleryCatalog<T extends DesignCatalogItem>(
+  options: DesignGalleryCatalogOptions<T>,
+): DesignCatalogBuild;
+export declare function createDesignComponentVariantMatrix(
+  entry: RegistryEntry | undefined,
+  maxCells?: number,
+): DesignComponentVariantMatrix;
+export declare function createDesignComponentCatalog(
+  options: DesignComponentCatalogOptions,
+): DesignCatalogBuild;
+
 export interface TokenDef {
   /** CSS variable name — e.g. `--app-color-surface-brand`. */
   name: string;
@@ -36,8 +161,16 @@ export interface TokenDef {
   group?: string;
 }
 
-export const DESIGN_IMPORT_KINDS: readonly ['icons', 'design-tokens', 'atoms', 'components', 'screens'];
+export const DESIGN_IMPORT_KINDS: readonly [
+  'icons',
+  'design-tokens',
+  'atoms',
+  'components',
+  'screens',
+];
 export type DesignImportKind = (typeof DESIGN_IMPORT_KINDS)[number];
+export type DesignFrameSizeMode = 'fixed' | 'content';
+export type DesignFrameHeightMode = 'fixed' | 'document';
 
 export interface DesignImportAsset {
   id: string;
@@ -52,13 +185,7 @@ export interface DesignImportAsset {
 }
 
 export type DesignScreenInteractionAction =
-  | 'click'
-  | 'focus'
-  | 'fill'
-  | 'check'
-  | 'press'
-  | 'wait'
-  | 'storage';
+  'click' | 'focus' | 'fill' | 'check' | 'press' | 'wait' | 'storage';
 
 export interface DesignScreenInteraction {
   action: DesignScreenInteractionAction;
@@ -88,10 +215,7 @@ export type DesignSerializable =
 export type DesignScreenPreset = Readonly<Record<string, DesignSerializable>>;
 export type StoryboardPermissionState = 'granted' | 'denied' | 'prompt';
 export type StoryboardMediaFailure =
-  | 'not-allowed'
-  | 'not-found'
-  | 'not-readable'
-  | 'overconstrained';
+  'not-allowed' | 'not-found' | 'not-readable' | 'overconstrained';
 
 export interface StoryboardMediaDevice {
   kind: 'audioinput' | 'audiooutput' | 'videoinput';
@@ -143,6 +267,12 @@ export interface DesignImportPage {
   publish?: boolean;
   width?: number;
   height?: number;
+  /** `content` replaces the 1×1 measurement seed with actual rendered DOM bounds. */
+  frameSizeMode?: DesignFrameSizeMode;
+  /** `document` expands the frame to the rendered document height. The default remains a fixed viewport. */
+  heightMode?: DesignFrameHeightMode;
+  /** Safety limit used only by document-height frames. Defaults to 12,000px and is capped at 32,000px. */
+  maxHeight?: number;
   flow?: string;
   scenario?: string;
   state?: string;
@@ -194,6 +324,39 @@ export interface DesignScreenCollectionResult {
   coverage: DesignScenarioCoverage;
 }
 
+export interface DesignScreenViewport {
+  id: string;
+  label: string;
+  width: number;
+  height: number;
+  heightMode?: DesignFrameHeightMode;
+  maxHeight?: number;
+}
+
+export type DesignScreenViewportPagePatch = Partial<
+  Omit<DesignImportPage, 'id' | 'name' | 'section' | 'width' | 'height'>
+>;
+
+export interface DesignScreenViewportExpansionOptions {
+  include?: (page: DesignImportPage, viewport: DesignScreenViewport) => boolean;
+  transformPage?: (
+    page: DesignImportPage,
+    viewport: DesignScreenViewport,
+  ) => DesignScreenViewportPagePatch | undefined;
+  createPageId?: (
+    page: DesignImportPage,
+    viewport: DesignScreenViewport,
+  ) => string;
+  createPageName?: (
+    page: DesignImportPage,
+    viewport: DesignScreenViewport,
+  ) => string;
+  createSection?: (
+    page: DesignImportPage,
+    viewport: DesignScreenViewport,
+  ) => string;
+}
+
 export interface DesignImportManifest {
   sourceSha?: string;
   registry: ComponentRegistry;
@@ -208,7 +371,10 @@ export interface DesignImportCoverageItem {
   missing: number;
 }
 
-export type DesignImportCoverage = Record<DesignImportKind, DesignImportCoverageItem> & {
+export type DesignImportCoverage = Record<
+  DesignImportKind,
+  DesignImportCoverageItem
+> & {
   sourceSha?: string;
   complete: boolean;
 };
@@ -221,7 +387,8 @@ export interface DesignScreenInteractionReport {
   error?: string;
 }
 
-export type DesignScreenCaptureFailureStage = 'preset' | 'interaction' | 'assertion';
+export type DesignScreenCaptureFailureStage =
+  'preset' | 'interaction' | 'assertion';
 export type DesignScreenCaptureFailureCode =
   | 'preset_executor_missing'
   | 'preset_rejected'
@@ -280,7 +447,10 @@ export interface DesignScreenPresetExecutionResult {
 export type DesignScreenPresetExecutor = (
   request: DesignScreenPresetRequest,
   context: DesignScreenPresetContext,
-) => Promise<DesignScreenPresetExecutionResult | void> | DesignScreenPresetExecutionResult | void;
+) =>
+  | Promise<DesignScreenPresetExecutionResult | void>
+  | DesignScreenPresetExecutionResult
+  | void;
 
 export interface DesignScreenCaptureSpec {
   pageId: string;
@@ -391,11 +561,22 @@ export interface DesignImportController {
   getInitialPages(): DesignImportInitialPage[];
   getCoverage(): DesignImportCoverage;
   assertComplete(): void;
-  captureElement(element: Element, win?: Window, options?: DomImportOptions): DomImportResult | null;
-  captureIframe(iframe: HTMLIFrameElement, options?: DomImportOptions): DomImportResult | null;
+  captureElement(
+    element: Element,
+    win?: Window,
+    options?: DomImportOptions,
+  ): DomImportResult | null;
+  captureIframe(
+    iframe: HTMLIFrameElement,
+    options?: DomImportOptions,
+  ): DomImportResult | null;
   captureIframeWhenStable(
     iframe: HTMLIFrameElement,
-    options?: DomImportOptions & { settleMs?: number; timeoutMs?: number; minElementCount?: number },
+    options?: DomImportOptions & {
+      settleMs?: number;
+      timeoutMs?: number;
+      minElementCount?: number;
+    },
   ): Promise<DomImportResult | null>;
   runScreenInteractions(
     iframe: HTMLIFrameElement,
@@ -423,6 +604,16 @@ export declare function createDesignScreenCollection(options: {
   captureDefaults?: DesignScreenCaptureDefaults;
   captureRequirements?: DesignScreenCaptureRequirements;
 }): DesignScreenCollectionResult;
+export declare function expandDesignScreenCasesViewports(
+  cases: readonly DesignScreenCase[],
+  viewports: readonly DesignScreenViewport[],
+  options?: DesignScreenViewportExpansionOptions,
+): DesignScreenCase[];
+export declare function expandDesignScreenCollectionViewports(
+  collection: DesignImportCollection,
+  viewports: readonly DesignScreenViewport[],
+  options?: DesignScreenViewportExpansionOptions,
+): DesignImportCollection;
 export declare function mergeScreenPresets(
   defaults?: DesignScreenPreset,
   override?: DesignScreenPreset,
@@ -439,12 +630,10 @@ 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;
+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 declare const STORYBOARD_ENVIRONMENT_QUERY: string;
@@ -458,8 +647,7 @@ export declare function setStoryboardBaselineEnvironment(
   environment?: StoryboardEnvironment,
 ): void;
 export declare function getStoryboardBaselineEnvironment():
-  | StoryboardEnvironment
-  | undefined;
+  StoryboardEnvironment | undefined;
 export declare function mergeStoryboardEnvironment(
   base?: StoryboardEnvironment,
   override?: StoryboardEnvironment,
@@ -501,9 +689,494 @@ export interface RoutePreviewArtifactBundleV2 {
   >;
 }
 
+export type RoutePreviewArtifactV3Status =
+  'ready' | 'rendered-with-qa-failure' | 'capture-error';
+export type RoutePreviewArtifactV3ScreenshotMediaType =
+  'image/png' | 'image/webp';
+
+export interface RoutePreviewArtifactV3Viewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface RoutePreviewArtifactV3Diagnostic {
+  readonly stage: string;
+  readonly code: string;
+  readonly selector?: string;
+  readonly label?: string;
+  readonly message?: string;
+  readonly viewport: RoutePreviewArtifactV3Viewport;
+}
+
+export interface RoutePreviewArtifactV3ScreenshotReference {
+  readonly hash: `sha256-${string}`;
+  readonly mediaType: RoutePreviewArtifactV3ScreenshotMediaType;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface RoutePreviewArtifactV3ScreenshotAsset {
+  readonly mediaType: RoutePreviewArtifactV3ScreenshotMediaType;
+  readonly width: number;
+  readonly height: number;
+  readonly data: string;
+  readonly byteLength: number;
+}
+
+export interface RoutePreviewArtifactV3Frame {
+  readonly status: RoutePreviewArtifactV3Status;
+  readonly viewport: RoutePreviewArtifactV3Viewport;
+  readonly snapshot?: RoutePreviewArtifactBundleV2['frames'][string];
+  readonly screenshot?: RoutePreviewArtifactV3ScreenshotReference;
+  readonly diagnostics: readonly RoutePreviewArtifactV3Diagnostic[];
+}
+
+export interface RoutePreviewArtifactBundleV3 {
+  readonly version: 3;
+  readonly namespace: string;
+  readonly sourceRevision?: string;
+  readonly assets: {
+    readonly head: RoutePreviewArtifactBundleV2['assets']['head'];
+    readonly stylesheets: RoutePreviewArtifactBundleV2['assets']['stylesheets'];
+    readonly screenshots: Readonly<
+      Record<string, RoutePreviewArtifactV3ScreenshotAsset>
+    >;
+  };
+  readonly frames: Readonly<Record<string, RoutePreviewArtifactV3Frame>>;
+}
+
+export interface RoutePreviewArtifactV3ValidationResult {
+  readonly valid: boolean;
+  readonly errors: string[];
+  readonly bytes: number;
+}
+
+export interface RoutePreviewArtifactV3ReconstructedScreenshot {
+  readonly mediaType: RoutePreviewArtifactV3ScreenshotMediaType;
+  readonly width: number;
+  readonly height: number;
+  readonly dataUrl: string;
+}
+
 export type RoutePreviewArtifactBundle =
   | RoutePreviewArtifactBundleV1
-  | RoutePreviewArtifactBundleV2;
+  | RoutePreviewArtifactBundleV2
+  | RoutePreviewArtifactBundleV3;
+
+export declare function validateRoutePreviewArtifactV3Browser(
+  value: unknown,
+): RoutePreviewArtifactV3ValidationResult;
+export declare function reconstructRoutePreviewArtifactSnapshotV3(
+  value: unknown,
+  frameId: string,
+): string | null;
+export declare function reconstructRoutePreviewArtifactScreenshotV3(
+  value: unknown,
+  frameId: string,
+): RoutePreviewArtifactV3ReconstructedScreenshot | null;
+
+export interface PreviewRecipeIdentity {
+  id: string;
+  recipe: unknown;
+}
+
+export interface PreviewCacheNamespaceOptions {
+  sourceRevision: string;
+  recipes: readonly PreviewRecipeIdentity[];
+  recipeVersion?: number;
+  scope?: string;
+}
+
+export type StoryboardCaptureRecipeInput = Pick<
+  DesignScreenCase,
+  | 'route'
+  | 'path'
+  | 'componentName'
+  | 'gallery'
+  | 'width'
+  | 'height'
+  | 'environment'
+  | 'preset'
+  | 'interactions'
+  | 'assertions'
+>;
+
+export interface PreviewArtifactExpectation {
+  namespace: string;
+  sourceRevision: string;
+}
+
+export interface PreviewArtifactTransportRequest extends PreviewArtifactExpectation {
+  signal?: AbortSignal;
+  captureBaseUrl?: string;
+}
+
+export type PreviewArtifactTransport = (
+  request: PreviewArtifactTransportRequest,
+) => Promise<unknown | null | undefined>;
+
+export interface PreviewArtifactHttpResponse {
+  readonly ok: boolean;
+  json(): Promise<unknown>;
+}
+
+export type PreviewArtifactFetch = (
+  input: string,
+  init: {
+    method: 'GET';
+    headers: { accept: 'application/json' };
+    cache: 'no-store';
+    signal?: AbortSignal;
+  },
+) => Promise<PreviewArtifactHttpResponse>;
+
+export interface PreviewArtifactHttpTransportOptions {
+  endpoint: string;
+  fetcher?: PreviewArtifactFetch;
+  captureBaseUrl?: string;
+}
+
+export type PreviewArtifactValidationReason =
+  'invalid-bundle' | 'namespace-mismatch' | 'revision-mismatch';
+
+export type PreviewArtifactValidationResult =
+  | {
+      valid: true;
+      artifact: RoutePreviewArtifactBundle;
+      errors: readonly [];
+    }
+  | {
+      valid: false;
+      artifact: null;
+      reason: PreviewArtifactValidationReason;
+      errors: readonly string[];
+    };
+
+export type PreviewArtifactBootstrapResult =
+  | {
+      status: 'accepted';
+      artifact: RoutePreviewArtifactBundle;
+    }
+  | {
+      status: 'unavailable';
+      artifact: null;
+      error?: unknown;
+    }
+  | {
+      status: 'rejected';
+      artifact: null;
+      reason: PreviewArtifactValidationReason;
+      errors: readonly string[];
+    };
+
+export declare function createPreviewRecipeFingerprint(
+  recipes: readonly PreviewRecipeIdentity[],
+): string;
+export declare function createPreviewCacheNamespace(
+  options: PreviewCacheNamespaceOptions,
+): string;
+export declare function createStoryboardCaptureRecipeIdentity(
+  screen: StoryboardCaptureRecipeInput,
+): unknown;
+export declare function createPreviewArtifactHttpTransport(
+  options: PreviewArtifactHttpTransportOptions,
+): PreviewArtifactTransport;
+export declare function validatePreviewArtifactBundle(
+  value: unknown,
+  expectation?: PreviewArtifactExpectation,
+): PreviewArtifactValidationResult;
+export declare function bootstrapPreviewArtifact(
+  options: PreviewArtifactExpectation & {
+    transport: PreviewArtifactTransport;
+    signal?: AbortSignal;
+  },
+): Promise<PreviewArtifactBootstrapResult>;
+
+export type StoryboardGraphEdgeOrigin = 'explicit' | 'inferred';
+
+export interface StoryboardGraphEdgeInput {
+  id?: string;
+  from: string;
+  to: string;
+  kind?: string;
+  label?: string;
+}
+
+export interface StoryboardGraphBuildOptions {
+  screens: readonly DesignScreenCase[];
+  assets?: readonly DesignImportAsset[];
+  scenarios?: readonly DesignScenarioSource[];
+  explicitEdges?: readonly StoryboardGraphEdgeInput[];
+  inferredEdges?: readonly StoryboardGraphEdgeInput[];
+  startScreenIds?: readonly string[];
+  nonVisualScenarioIds?: readonly string[];
+  recipeKey?: (screen: DesignScreenCase) => string;
+}
+
+export interface StoryboardGraphNode {
+  id: string;
+  canonicalScreenId: string;
+  screenIds: readonly string[];
+  names: readonly string[];
+  recipeKey: string;
+  routes: readonly string[];
+  scenarioIds: readonly string[];
+  sourceKeys: readonly string[];
+  flows: readonly string[];
+  states: readonly string[];
+}
+
+export interface StoryboardGraphEdge {
+  id: string;
+  from: string;
+  to: string;
+  kind?: string;
+  label?: string;
+  origin: StoryboardGraphEdgeOrigin;
+  sourceEdgeIds: readonly string[];
+}
+
+export interface StoryboardGraphSourceGroup {
+  sourceKey: string;
+  nodeIds: readonly string[];
+  screenIds: readonly string[];
+  shared: boolean;
+}
+
+export interface StoryboardGraphBranch {
+  nodeId: string;
+  edgeIds: readonly string[];
+  targetNodeIds: readonly string[];
+}
+
+export type StoryboardGraphWarningCode =
+  | 'duplicate-screen-id'
+  | 'invalid-recipe'
+  | 'unknown-edge-source'
+  | 'unknown-edge-target'
+  | 'ambiguous-edge-source'
+  | 'ambiguous-edge-target'
+  | 'unknown-start-screen'
+  | 'disconnected-screen'
+  | 'missing-code-scenario';
+
+export interface StoryboardGraphWarning {
+  code: StoryboardGraphWarningCode;
+  severity: 'warning' | 'error';
+  message: string;
+  screenId?: string;
+  nodeId?: string;
+  edgeId?: string;
+  scenarioId?: string;
+}
+
+export interface StoryboardGraphCoverage {
+  screens: number;
+  canonicalNodes: number;
+  mergedScreens: number;
+  edges: number;
+  connectedNodes: number;
+  disconnectedScreens: readonly string[];
+  codeScenarios: number;
+  representedScenarios: number;
+  missingScenarios: readonly string[];
+  complete: boolean;
+}
+
+export interface StoryboardGraph {
+  version: 1;
+  nodes: readonly StoryboardGraphNode[];
+  edges: readonly StoryboardGraphEdge[];
+  aliases: Readonly<Record<string, string>>;
+  sourceGroups: readonly StoryboardGraphSourceGroup[];
+  startNodeIds: readonly string[];
+  branches: readonly StoryboardGraphBranch[];
+  warnings: readonly StoryboardGraphWarning[];
+  coverage: StoryboardGraphCoverage;
+}
+
+export declare function storyboardScreenRecipeKey(
+  screen: DesignScreenCase,
+): string;
+export declare function createStoryboardGraph(
+  options: StoryboardGraphBuildOptions,
+): StoryboardGraph;
+
+export interface StoryboardFrameReference {
+  frameId: string;
+  screenId: string;
+  name: string;
+}
+
+export interface StoryboardGraphFrameView {
+  frameId: string;
+  screenId: string;
+  name: string;
+  nodeId: string;
+  canonicalScreenId: string;
+  canonicalFrameId?: string;
+  isCanonical: boolean;
+  isStart: boolean;
+  isBranch: boolean;
+  aliasScreenIds: readonly string[];
+  relatedFrameIds: readonly string[];
+  branchTargetFrameIds: readonly string[];
+  warnings: readonly StoryboardGraphWarning[];
+}
+
+export interface StoryboardGraphCanonicalView {
+  nodeId: string;
+  canonicalScreenId: string;
+  canonicalFrameId?: string;
+  aliasScreenIds: readonly string[];
+  aliasFrameIds: readonly string[];
+}
+
+export interface StoryboardGraphSourceView {
+  sourceKey: string;
+  frameIds: readonly string[];
+  nodeIds: readonly string[];
+}
+
+export interface StoryboardGraphViewModel {
+  frames: readonly StoryboardGraphFrameView[];
+  canonicalGroups: readonly StoryboardGraphCanonicalView[];
+  sharedSources: readonly StoryboardGraphSourceView[];
+  startFrameIds: readonly string[];
+  branchFrameIds: readonly string[];
+  warnings: readonly StoryboardGraphWarning[];
+  unresolvedWarnings: readonly StoryboardGraphWarning[];
+  coverage: StoryboardGraphCoverage;
+}
+
+export declare function createStoryboardGraphViewModel(
+  graph: StoryboardGraph,
+  frameReferences: readonly StoryboardFrameReference[],
+): StoryboardGraphViewModel;
+export declare function setStoryboardGraph(graph: StoryboardGraph | null): void;
+export declare function getStoryboardGraph(): StoryboardGraph | null;
+export declare function subscribeStoryboardGraph(
+  listener: () => void,
+): () => void;
+
+export interface StoryboardDiscoveryScenario {
+  id?: string;
+  name?: string;
+  section?: string;
+  flow?: string;
+  sourcePath?: string;
+  description?: string;
+  environment?: StoryboardEnvironment;
+}
+
+export interface StoryboardDiscoveryCandidate {
+  id?: string;
+  route?: string;
+  scenarioId?: string;
+  environment?: StoryboardEnvironment;
+}
+
+export interface StoryboardDiscoveryEdge {
+  id?: string;
+  from?: string;
+  to?: string;
+  kind?: string;
+  label?: string;
+  unresolvedTarget?: boolean;
+}
+
+export interface StoryboardDiscoveryRoute {
+  id?: string;
+  path?: string;
+}
+
+export interface StoryboardDiscoveryManifest {
+  version?: number;
+  routes?: readonly StoryboardDiscoveryRoute[];
+  scenarios?: readonly StoryboardDiscoveryScenario[];
+  candidates?: readonly StoryboardDiscoveryCandidate[];
+  edges?: readonly StoryboardDiscoveryEdge[];
+}
+
+export interface StoryboardResolvedPage {
+  id: string;
+  name: string;
+  canvas?: string;
+  section?: string;
+  importKind?: DesignImportKind;
+  componentName?: string;
+  gallery?: string[];
+  route?: string;
+  path?: string;
+  publish?: boolean;
+  width?: number;
+  height?: number;
+  frameSizeMode?: DesignFrameSizeMode;
+  heightMode?: DesignFrameHeightMode;
+  maxHeight?: number;
+  sourcePaths?: string[];
+  flow?: string;
+  scenario?: string;
+  state?: string;
+  scenarioId?: string;
+  interactions?: readonly DesignScreenInteraction[];
+  environment?: StoryboardEnvironment;
+  preset?: DesignScreenPreset;
+  assertions?: readonly DesignScreenAssertion[];
+}
+
+export interface StoryboardDiscoveryGraphOptions {
+  manifest: StoryboardDiscoveryManifest;
+  pages: readonly StoryboardResolvedPage[];
+  assets?: readonly DesignImportAsset[];
+}
+
+export interface StoryboardDiscoveryResult {
+  manifest: StoryboardDiscoveryManifest;
+  baselineEnvironment?: StoryboardEnvironment;
+  graph: StoryboardGraph;
+}
+
+export interface StoryboardDiscoveryResponse {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}
+
+export type StoryboardDiscoveryFetch = (
+  endpoint: string,
+  init: {
+    headers: { accept: 'application/json' };
+    cache: 'no-store';
+    signal?: AbortSignal;
+  },
+) => Promise<StoryboardDiscoveryResponse>;
+
+export interface LoadStoryboardDiscoveryOptions extends Omit<
+  StoryboardDiscoveryGraphOptions,
+  'manifest'
+> {
+  endpoint: string;
+  signal?: AbortSignal;
+  fetcher?: StoryboardDiscoveryFetch;
+}
+
+export declare function resolveStoryboardScreenCases(
+  pages: readonly StoryboardResolvedPage[],
+  manifest: StoryboardDiscoveryManifest,
+): DesignScreenCase[];
+export declare function getStoryboardDiscoveryBaselineEnvironment(
+  manifest: StoryboardDiscoveryManifest,
+): StoryboardEnvironment | undefined;
+export declare function createStoryboardGraphFromDiscovery(
+  options: StoryboardDiscoveryGraphOptions,
+): StoryboardGraph;
+export declare function loadStoryboardDiscovery(
+  options: LoadStoryboardDiscoveryOptions,
+): Promise<StoryboardDiscoveryResult>;
+export declare function publishStoryboardDiscovery(
+  options: LoadStoryboardDiscoveryOptions,
+): Promise<StoryboardDiscoveryResult>;
 
 export interface InitialPageDef {
   name: string;
@@ -524,6 +1197,9 @@ export interface InitialPageDef {
   /** Frame size (px) — 390×600 (mobile) if not specified. */
   width?: number;
   height?: number;
+  frameSizeMode?: DesignFrameSizeMode;
+  heightMode?: DesignFrameHeightMode;
+  maxHeight?: number;
   /** Immediately after the first render, the entire actual DOM is imported into the layer tree. */
   importLayers?: boolean;
   importPageId?: string;
@@ -701,7 +1377,8 @@ export interface InspectApplyResult {
   /** Modification session branch created by the host. */
   branch?: string;
   /** Result of merging with latest development code. */
-  integration?: 'up_to_date' | 'auto_merged' | 'review_required' | 'conflict' | 'offline';
+  integration?:
+    'up_to_date' | 'auto_merged' | 'review_required' | 'conflict' | 'offline';
   /** Text of application results to show to the designer. */
   message?: string;
   /** Comparison of DOM·PNG recapture of the impact screen immediately after application. */
@@ -772,11 +1449,7 @@ export interface InspectQaCaptureRequest {
 }
 
 export type PygmalionIntegrationState =
-  | 'up_to_date'
-  | 'auto_merged'
-  | 'review_required'
-  | 'conflict'
-  | 'offline';
+  'up_to_date' | 'auto_merged' | 'review_required' | 'conflict' | 'offline';
 
 export interface PygmalionDevMirrorStatus {
   state: 'idle' | 'syncing' | 'ready' | 'error';
@@ -814,8 +1487,7 @@ export interface PygmalionVisualRevertOperation {
 }
 
 export type PygmalionSessionOperation =
-  | PygmalionVisualOperation
-  | PygmalionVisualRevertOperation;
+  PygmalionVisualOperation | PygmalionVisualRevertOperation;
 
 export interface PygmalionDesignSessionStatus {
   id: string;
@@ -904,6 +1576,8 @@ 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;
+  /** Same-origin endpoint that resolves an exact namespace and source revision. */
+  previewArtifactEndpoint?: string;
   /** 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. */
@@ -915,11 +1589,17 @@ export declare function PygmalionEditor(props: {
   /** Reflect button — Returns { branch } after the host saves the file and commits the branch (push is done directly by the user). */
   onApply?: (payload: ApplyPayload) => Promise<{ branch: string } | void>;
   /** Code auto-save path that does not differentiate between icon/token/atom/component/screen. */
-  onDesignChange?: (payload: DesignChangePayload) => Promise<DesignChangeResult | void>;
+  onDesignChange?: (
+    payload: DesignChangePayload,
+  ) => Promise<DesignChangeResult | void>;
   /** Apply inspection edits through the host write-back endpoint. */
-  onInspectApply?: (payload: InspectApplyPayload) => Promise<InspectApplyResult | void>;
+  onInspectApply?: (
+    payload: InspectApplyPayload,
+  ) => Promise<InspectApplyResult | void>;
   /** Preview the code diff before applying. If connected, the Apply button is locked before confirmation. */
-  onInspectPreview?: (payload: InspectApplyPayload) => Promise<InspectPreviewResult>;
+  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. */
@@ -944,4 +1624,8 @@ export declare function pygmalionResetCurrentEdits(): boolean;
 
 /** For host debugging — editor store·mobx inspection utility (instance in bundle). */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export declare const __debug: { editor: any; getObserverTree: any; isObservableProp: any };
+export declare const __debug: {
+  editor: any;
+  getObserverTree: any;
+  isObservableProp: any;
+};