@pygmalionjs/pygmalion 0.14.0 → 0.16.0

package/dist-lib/types/workspace/edit/geometryHandles.d.ts

@@ -73,7 +73,7 @@ export interface SnapGap {
 export interface SnapGuide {
     readonly axis: 'x' | 'y';
     readonly position: number;
-    /** `edge` and `center` come from boxes, `guide` from persisted guides, `grid` from layout grid tracks, `spacing` from equal sibling distances. */
+    /** `edge` and `center` come from boxes, `guide` from persisted guides, `grid` from layout grids, `spacing` from equal sibling distances. */
     readonly kind: 'edge' | 'center' | 'guide' | 'grid' | 'spacing';
     readonly nodeId: string;
     /** Extent along the other axis, for drawing the guide line; equal values mean "the moving box only". */
@@ -83,6 +83,11 @@ export interface SnapGuide {
     readonly reference?: SnapReference;
     /** The equal distances a `spacing` candidate reproduces, for drawing. */
     readonly gaps?: readonly SnapGap[];
+    /** Candidate-only pixel lattice, starting at `position`; resolved feedback never contains this field. */
+    readonly lattice?: {
+        readonly step: number;
+        readonly extent: number;
+    };
 }
 export interface SnapResult {
     readonly dx: number;
@@ -90,6 +95,8 @@ export interface SnapResult {
     readonly guides: readonly SnapGuide[];
 }
 export interface SnapCandidateOptions {
+    /** Ordinary root layers visible on the current page; undefined retains the complete scene. */
+    readonly visibleRootIds?: readonly string[];
     /** Include the moving layers' own children: right for a resize, wrong for a move (the children travel along). */
     readonly children?: boolean;
 }
@@ -105,7 +112,7 @@ export interface MoveSnapSession {
  * refused with a diagnostic instead of guessed bounds. Derived sizes keep move and
  * rotation but drop the resize handles.
  */
-export declare function planSelectionHandles(document: DesignDocument, nodeIds: readonly string[], projection: DataProjection | null): SelectionHandlesPlan;
+export declare function planSelectionHandles(document: DesignDocument, nodeIds: readonly string[], projection: DataProjection | null, options?: SnapCandidateOptions): SelectionHandlesPlan;
 export declare function layerResizeHandles(layer: Pick<LayerGeometry, 'resizable' | 'resizeAxes'>): readonly GeometryHandle[];
 /**
  * Turn a handle drag into a new local size and placement. The handle's opposite edge or
@@ -202,7 +209,7 @@ export declare function snapResizeGesture(layer: LayerPlacement & {
  * Snapshot for a move gesture: the moving box, its candidates (siblings, parent, guides, grids,
  * and equal sibling distances for this box size), and the zoom-aware tolerance.
  */
-export declare function beginMoveSnap(document: DesignDocument, nodeIds: readonly string[], projection: DataProjection | null, zoom: number): MoveSnapSession | null;
+export declare function beginMoveSnap(document: DesignDocument, nodeIds: readonly string[], projection: DataProjection | null, zoom: number, options?: SnapCandidateOptions): MoveSnapSession | null;
 /** Adjust world pointer travel so the moving box snaps; exact in one pass because only translation changes. */
 export declare function snapMove(session: MoveSnapSession, delta: {
     x: number;

package/dist-lib/types/workspace/edit/prototypeWiringModel.d.ts

@@ -0,0 +1,47 @@
+import type { DataProjection } from '../../binding/preview.js';
+import type { DesignDocument, DocumentTransaction } from '../../document/contracts.js';
+import { type PrototypeAction, type PrototypeInteraction } from '../../document/prototype.js';
+export type PrototypeActionPath = readonly (number | 'branches' | 'actions' | 'otherwise')[];
+export interface PrototypeConnectionSelection {
+    nodeId: string;
+    interactionId: string;
+    actionPath: PrototypeActionPath;
+}
+export interface PrototypeConnection extends PrototypeConnectionSelection {
+    destinationId: string;
+    action: PrototypeAction;
+    label: string;
+}
+export interface WiringPoint {
+    x: number;
+    y: number;
+}
+export interface WiringBounds extends WiringPoint {
+    width: number;
+    height: number;
+}
+export interface PrototypeWiringLayer {
+    nodeId: string;
+    name: string;
+    bounds: WiringBounds;
+    rootId: string;
+    visible: boolean;
+}
+export interface PrototypeWiringPlan {
+    layers: readonly PrototypeWiringLayer[];
+    diagnostics: readonly string[];
+}
+export declare const connectionKey: (value: PrototypeConnectionSelection) => string;
+/** Only explicit destination actions become wires. No flow or action is inferred. */
+export declare function prototypeConnections(document: DesignDocument): PrototypeConnection[];
+/** Canonical, uniquely placed layers only; projected rows and instance leaves cannot acquire shared actions accidentally. */
+export declare function planPrototypeWiring(document: DesignDocument, projection: DataProjection | null, selected?: readonly string[], visibleRootIds?: readonly string[]): PrototypeWiringPlan;
+/** Builds a complete detached edit before the caller opens its single history transaction. */
+export declare function preparePrototypeConnection(document: DesignDocument, sourceId: string, destinationId: string | null, selection?: PrototypeConnectionSelection, interactionId?: string): PrototypeInteraction[];
+export declare function writePrototypeConnection(transaction: DocumentTransaction, document: DesignDocument, sourceId: string, interactions: readonly PrototypeInteraction[]): void;
+export declare function prototypeWireCurve(source: WiringBounds, target: WiringBounds, lane: number, zoom: number, loop?: boolean): {
+    path: string;
+    start: WiringPoint;
+    end: WiringPoint;
+    middle: WiringPoint;
+};

package/dist-lib/types/workspace/edit/rasterExport.d.ts

@@ -0,0 +1,5 @@
+import { type RasterExportRenderer, type RasterExportRequest } from '../../document/exportSettings.js';
+/** The same supported SVG geometry supplies browser raster output; unsupported visuals stay explicit. */
+export declare function rasterExportSvg(request: RasterExportRequest): string;
+/** Explicit browser renderer for supported geometry. It never captures a page or fetches external resources. */
+export declare const renderDesignRaster: RasterExportRenderer;

package/dist-lib/types/workspace/edit/textFontOccurrences.d.ts

@@ -0,0 +1,34 @@
+import type { DesignDocument, DocumentResolveOptions } from '../../document/contracts.js';
+import type { DataProjection } from '../../binding/preview.js';
+import { type TextFontFaceRequest } from '../../document/richText.js';
+import { type ProjectedDocumentNode } from './projection.js';
+export interface TextFontAddress {
+    readonly sourceNodeId: string;
+    readonly instancePath: readonly string[];
+    readonly rowPath: ProjectedDocumentNode['rowPath'];
+}
+export interface TextFontOccurrence extends TextFontAddress {
+    readonly origin: 'authored' | 'source' | 'bound';
+    readonly requests: readonly TextFontFaceRequest[];
+}
+export interface TextFontCollection {
+    readonly occurrences: readonly TextFontOccurrence[];
+    readonly diagnostics: readonly {
+        readonly code: string;
+        readonly message: string;
+        readonly address?: TextFontAddress;
+    }[];
+}
+export interface TextFontCollectionOptions {
+    readonly projection?: DataProjection | null;
+    readonly resolveOptions?: DocumentResolveOptions;
+    /** Supply the same resolved scene the canvas uses, when it has custom resolution. */
+    readonly scene?: ProjectedDocumentNode;
+    readonly visibleRootIds?: readonly string[];
+    readonly subtree?: TextFontAddress;
+    /** Required for connected/source content or case-transformed samples. It must describe rendered text. */
+    readonly resolveText?: (item: ProjectedDocumentNode, address: TextFontAddress) => string | undefined;
+}
+export declare const textFontAddressKey: (address: TextFontAddress) => string;
+/** Read-only effective occurrences; hidden pages/rows and unselected shared definitions do not preload. */
+export declare function collectTextFontOccurrences(document: DesignDocument, options?: TextFontCollectionOptions): TextFontCollection;

package/dist-lib/types/workspace/edit/textFontRuntime.d.ts

@@ -0,0 +1,15 @@
+import { type TextFontFaceResolver, type TextFontPreparationReport } from '../../document/textFontPreparation.js';
+import type { TextFontFaceRequest } from '../../document/richText.js';
+export interface TextFontPreparationRuntime {
+    readonly environmentId: string;
+    prepare(requests: readonly TextFontFaceRequest[], options?: {
+        signal?: AbortSignal;
+        retry?: boolean;
+    }): Promise<TextFontPreparationReport>;
+    clear(): void;
+    dispose(): void;
+}
+/** A bounded successful-result cache with shared in-flight work and independently cancellable readers. */
+export declare function createTextFontPreparationRuntime(resolver: TextFontFaceResolver, options?: {
+    maxEntries?: number;
+}): TextFontPreparationRuntime;

package/dist-lib/types/workspace/edit/useTextFontPreparation.d.ts

@@ -0,0 +1,12 @@
+import type { DesignDocument, DocumentNode } from '../../document/contracts.js';
+import type { TextFontPreparationReport } from '../../document/textFontPreparation.js';
+import { type TextFontCollection } from './textFontOccurrences.js';
+import type { TextFontPreparationRuntime } from './textFontRuntime.js';
+export interface TextFontPreparationState {
+    readonly status: 'idle' | 'loading' | 'ready' | 'unavailable' | 'failed';
+    readonly messages: readonly string[];
+    readonly report?: TextFontPreparationReport;
+    retry(): void;
+}
+/** Exact readiness is opt-in; legacy font-set loading never becomes an identity attestation. */
+export declare function useTextFontPreparation(document: DesignDocument, node: DocumentNode, runtime?: TextFontPreparationRuntime | null, supplied?: TextFontCollection): TextFontPreparationState;

package/dist-lib/types/workspace/view/prototypeMotionInterruption.d.ts

@@ -0,0 +1,47 @@
+import type { PrototypeTransition } from '../../document/prototype.js';
+export declare const prototypeMotionProperties: readonly ["transform", "width", "height", "opacity", "backgroundColor", "borderRadius"];
+export type PrototypeMotionProperty = typeof prototypeMotionProperties[number];
+export type PrototypeMotionStyles = Record<PrototypeMotionProperty, string>;
+export interface PrototypeMotionCapture {
+    styles: PrototypeMotionStyles;
+    velocity: Partial<Record<PrototypeMotionProperty, readonly number[]>>;
+}
+export interface PrototypeMotionRecord {
+    element: HTMLElement;
+    animation: Animation;
+    frames: readonly Keyframe[];
+    durationMs: number;
+    easing(progress: number): number;
+}
+/** Mirrors the bounded CSS linear() samples used by the physical spring renderer. */
+export declare function prototypeMotionTiming(transition: PrototypeTransition, durationMs: number): (progress: number) => number;
+/** Reads presentation once. No time seeks, inline-style writes, frame history or DOM mutations. */
+export declare function capturePrototypeMotionStyles(elements: readonly HTMLElement[], records: readonly PrototypeMotionRecord[], drag?: {
+    progress: number;
+    velocity: number;
+} | null): Map<HTMLElement, PrototypeMotionCapture>;
+export interface PrototypeInterruptedTiming {
+    readonly samples: readonly {
+        offset: number;
+        progress: number;
+        velocityResponse: number;
+    }[];
+    readonly initialSlope: number;
+}
+/** One shared timing table per interrupted transition, never one solver per layer/channel. */
+export declare function createPrototypeInterruptedTiming(transition: PrototypeTransition, durationMs: number): PrototypeInterruptedTiming;
+interface PrototypeInterruptedFrames {
+    frames: Keyframe[];
+    unsupported: PrototypeMotionProperty[];
+}
+interface PrototypeInterruptedFramePlannerOptions {
+    maxTracks?: number;
+    maxBytes?: number;
+}
+/** A single preparation pass owns this cache; it retains no DOM, captures or animation records.
+ * Limits bound cached track count and UTF-16 string payload bytes, not total JavaScript heap size.
+ * Returned frames are detached even when their immutable property strings are reused. */
+export declare function createPrototypeInterruptedFramePlanner(inputTiming: PrototypeInterruptedTiming, options?: PrototypeInterruptedFramePlannerOptions): (captured: PrototypeMotionCapture, target: Partial<PrototypeMotionStyles>) => PrototypeInterruptedFrames;
+/** Existing computed 2D/px/RGB tracks only. Unsupported values retain explicit diagnostics. */
+export declare function createPrototypeInterruptedFrames(captured: PrototypeMotionCapture, target: Partial<PrototypeMotionStyles>, timing: PrototypeInterruptedTiming): PrototypeInterruptedFrames;
+export {};

package/dist-lib/types/workspace/view/prototypePlayback.d.ts

@@ -27,9 +27,17 @@ export interface PrototypePlayerOptions extends PrototypeStartOptions {
     /** Effects describe intended links and scrolling; the adapter decides how to execute them. */
     onEffect?(effect: PrototypeEffect): void;
 }
+export interface PrototypeTransitionChange {
+    previous: PrototypePlayerSnapshot;
+    next: PrototypeState;
+    interrupted: boolean;
+    reset: boolean;
+}
 export interface PrototypePlayerController {
     getSnapshot(): PrototypePlayerSnapshot;
     subscribe(listener: () => void): () => void;
+    /** Capture presentation before the old scene is replaced. Exceptions become diagnostics. */
+    subscribeBeforeTransition(listener: (change: PrototypeTransitionChange) => void): () => void;
     dispatch(event: PrototypeEvent): void;
     beginDrag(input: Omit<PrototypeDragStartInput, 'now'>): boolean;
     updateDrag(input: Pick<PrototypeDragStartInput, 'pointerId' | 'point'>): void;

package/dist-lib/types/workspace/view/storyboardCanvas.d.ts

@@ -16,14 +16,25 @@ export interface StoryboardArtboard extends StoryboardBounds {
     screenId: string;
     group: string;
 }
+export interface StoryboardPoint {
+    x: number;
+    y: number;
+}
 export interface StoryboardConnection {
     edge: StoryboardGraphEdge;
     from: StoryboardArtboard;
     to: StoryboardArtboard;
     path: string;
+    points: readonly StoryboardPoint[];
     labelX: number;
     labelY: number;
 }
+export interface StoryboardExternalConnection {
+    edge: StoryboardGraphEdge;
+    frame: StoryboardArtboard;
+    page: PageModel;
+    direction: 'incoming' | 'outgoing';
+}
 export declare const storyboardFlow: (page: PageModel) => string;
 /** Arrange source-sized screens in flow lanes; never rewrite authored page geometry. */
 export declare function layoutStoryboard(pages: readonly PageModel[]): {
@@ -38,5 +49,9 @@ export declare function zoomStoryboard(camera: WorkspaceCamera, point: {
     y: number;
 }, requested: number): WorkspaceCamera;
 export declare function visibleStoryboardFrames(frames: readonly StoryboardArtboard[], camera: WorkspaceCamera, viewport: StoryboardViewport): StoryboardArtboard[];
-/** A line means an authored transition. Layout proximity never creates an edge. */
+/** A line means an authored transition. Routing and proximity never create or reorder an edge. */
 export declare function storyboardConnections(frames: readonly StoryboardArtboard[], graph: StoryboardGraph | null): StoryboardConnection[];
+/** Portals expose real endpoints filtered from the canvas, only when available in the active catalog. */
+export declare function storyboardExternalConnections(frames: readonly StoryboardArtboard[], graph: StoryboardGraph | null, pages: readonly PageModel[]): StoryboardExternalConnection[];
+/** Include connector lanes in Overview without changing the authored artboard layout. */
+export declare function storyboardConnectionBounds(bounds: StoryboardBounds, connections: readonly StoryboardConnection[]): StoryboardBounds;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {