@pygmalionjs/pygmalion 0.18.0 → 0.19.0

package/dist-lib/{runtime-B8Qu1ung.js → runtime-DlZpODq8.js}

@@ -20749,7 +20749,7 @@ function z_(t) {
           stamped: u ? i.isStampedFrozenPreview(u.root) : null
         },
         lodState: a.__debugFrameLodState(),
-        readFramesNow: (await import("./CameraLayer-Clqgdcjb.js")).__debugReadEditorFrames(t).find((h) => h.id === n)
+        readFramesNow: (await import("./CameraLayer-Bv1TqRim.js")).__debugReadEditorFrames(t).find((h) => h.id === n)
       };
     },
     /** Flow-session delivery states for headless diagnosis of the captureless supply. */
@@ -20984,26 +20984,26 @@ export {
   Vu as b7,
   Ha as b8,
   WS as b9,
-  i0 as bA,
-  $0 as bB,
-  R0 as bC,
-  Ld as bD,
-  Fd as bE,
-  Jy as bF,
-  pI as bG,
-  X0 as bH,
-  _w as bI,
-  Aw as bJ,
-  eI as bK,
-  n0 as bL,
-  r0 as bM,
-  b0 as bN,
-  bu as bO,
-  Uu as bP,
-  uo as bQ,
-  co as bR,
-  Pp as bS,
-  Ba as bT,
+  gw as bA,
+  i0 as bB,
+  $0 as bC,
+  R0 as bD,
+  Ld as bE,
+  Fd as bF,
+  Jy as bG,
+  pI as bH,
+  X0 as bI,
+  _w as bJ,
+  Aw as bK,
+  eI as bL,
+  n0 as bM,
+  r0 as bN,
+  b0 as bO,
+  bu as bP,
+  Uu as bQ,
+  uo as bR,
+  co as bS,
+  Pp as bT,
   gI as bU,
   J_ as bV,
   x0 as bW,
@@ -21013,30 +21013,30 @@ export {
   nb as b_,
   HS as ba,
   lo as bb,
-  e_ as bc,
-  ro as bd,
-  xc as be,
-  Ro as bf,
-  h_ as bg,
-  dt as bh,
-  pd as bi,
-  kd as bj,
-  yI as bk,
-  mI as bl,
-  M0 as bm,
-  T0 as bn,
-  p0 as bo,
-  k0 as bp,
-  C0 as bq,
-  cr as br,
-  pu as bs,
-  Rv as bt,
-  $v as bu,
-  qy as bv,
-  l0 as bw,
-  Dv as bx,
-  QS as by,
-  gw as bz,
+  Ba as bc,
+  e_ as bd,
+  ro as be,
+  xc as bf,
+  Ro as bg,
+  h_ as bh,
+  dt as bi,
+  pd as bj,
+  kd as bk,
+  yI as bl,
+  mI as bm,
+  M0 as bn,
+  T0 as bo,
+  p0 as bp,
+  k0 as bq,
+  C0 as br,
+  cr as bs,
+  pu as bt,
+  Rv as bu,
+  $v as bv,
+  qy as bw,
+  l0 as bx,
+  Dv as by,
+  QS as bz,
   Zn as c,
   B0 as c0,
   Q0 as c1,

package/dist-lib/testing.js

@@ -1,5 +1,5 @@
-import { b$ as l, T as u } from "./runtime-B8Qu1ung.js";
-import { bo as y, ch as b, ci as E, cj as P, bk as $, aw as T } from "./runtime-B8Qu1ung.js";
+import { b$ as d, T as u } from "./runtime-DlZpODq8.js";
+import { bp as y, ch as b, ci as E, cj as P, bl as $, aw as T } from "./runtime-DlZpODq8.js";
 const v = {
   mirror: ["status", "refresh", "refs"],
   session: ["open", "check", "previewVisual", "applyVisual", "revertVisual"],
@@ -9,7 +9,7 @@ const v = {
   storyboard: ["environment", "sourceUsage", "componentBranches"]
 };
 function h(m = {}, t = {}) {
-  const n = [], d = t.origin ?? "", r = (e) => {
+  const n = [], l = t.origin ?? "", r = (e) => {
     var a;
     const i = {};
     for (const o of v[e]) {
@@ -26,8 +26,8 @@ function h(m = {}, t = {}) {
   };
   return {
     calls: n,
-    endpoints: l(t.endpoints),
-    resolveUrl: (e) => `${d}${e}`,
+    endpoints: d(t.endpoints),
+    resolveUrl: (e) => `${l}${e}`,
     mirror: r("mirror"),
     session: r("session"),
     inspect: r("inspect"),

package/dist-lib/types/token-library/bindings.d.ts

@@ -8,6 +8,43 @@ export interface VariableBinding {
 }
 export type VariableBindings = Record<string, VariableBinding>;
 export type VariableValueCodec = (library: TokenLibraryDocument, resolved: TokenValueResolution) => VariableScalar;
+export type VariableModeProvider = {
+    kind: 'binding';
+} | {
+    kind: 'node';
+    nodeId: string;
+} | {
+    kind: 'instance';
+    instanceId: string;
+    overrideAddress: string;
+} | {
+    kind: 'default';
+};
+export interface VariableModeResolution {
+    collectionId: string;
+    /** The requested mode, even when an alias is authored in a fallback mode. */
+    modeId: string;
+    provider: VariableModeProvider;
+    visitedNodeIds: readonly string[];
+}
+export interface VariableInstanceAddress {
+    instanceId: string;
+    overrideAddress: string;
+}
+export type VariableOccurrenceAddress = {
+    nodeId: string;
+} | VariableInstanceAddress;
+export interface VariableOccurrencePlan {
+    address: VariableOccurrenceAddress;
+    property: VariableTarget;
+    binding: VariableBinding;
+    mode: VariableModeResolution;
+    resolved: TokenValueResolution;
+    value: VariableScalar;
+    before: DocumentValue | undefined;
+    /** Literal projection only. Binding identity and transaction ownership stay with the caller. */
+    patch: DocumentNodePatch;
+}
 export interface VariableChange {
     nodeId: string;
     overrideAddress?: string;
@@ -50,8 +87,15 @@ export declare function isVariableBinding(value: unknown): value is VariableBind
 export declare function nodeVariableBindings(node: Pick<DocumentNode, 'properties'>): VariableBindings;
 /** Built-in values are JSON scalars. Other syntax remains the host codec's responsibility. */
 export declare function resolveScalarVariable(library: TokenLibraryDocument, resolved: TokenValueResolution, seen?: Set<string>): VariableScalar;
+export declare function resolveVariableModeForNode(document: DesignDocument, nodeId: string, library: TokenLibraryDocument, tokenId: string, explicit?: string): VariableModeResolution;
 export declare function variableModeForNode(document: DesignDocument, nodeId: string, library: TokenLibraryDocument, tokenId: string, explicit?: string): string;
+/** Resolves an opaque override address through the actual component resolver. */
+export declare function resolveVariableModeForInstance(document: DesignDocument, address: VariableInstanceAddress, library: TokenLibraryDocument, binding: VariableBinding): VariableModeResolution;
 export declare function variableTargetsForNode(node: DocumentNode): VariableTarget[];
+/** Override projection stays sparse; unrelated inherited properties never become local overrides. */
+export declare function projectVariableScalar(node: DocumentNode, property: VariableTarget, value: VariableScalar, placement: 'own' | 'override'): DocumentNodePatch;
+/** Reads one occurrence without refreshing unrelated nodes or changing either document. */
+export declare function planVariableOccurrence(document: DesignDocument, address: VariableOccurrenceAddress, property: VariableTarget, library: TokenLibraryDocument, codec?: VariableValueCodec): VariableOccurrencePlan;
 export declare function bindVariablePatch(document: DesignDocument, nodeId: string, property: VariableTarget, library: TokenLibraryDocument, binding: VariableBinding, codec?: VariableValueCodec): DocumentNodePatch;
 export declare function detachVariablePatch(node: DocumentNode, property: VariableTarget): DocumentNodePatch;
 /** A refresh plan records all affected nodes before the caller commits one history entry. */

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

@@ -1,10 +1,14 @@
 import type { DesignDocument, DocumentEngineOptions, DocumentTransaction } from '../../document/contracts.js';
+import type { ProjectedDocumentNode } from './projection.js';
 import type { DataProjection } from '../../binding/preview.js';
 
-export declare function ArrangeLayers({ document, selected, projection, preflight, act, compact }: {
+export declare function ArrangeLayers({ document, selected, projection, scene, visibleRootIds, isGeometryCurrent, preflight, act, compact }: {
     document: DesignDocument;
     selected: readonly string[];
     projection: DataProjection | null;
+    scene?: ProjectedDocumentNode;
+    visibleRootIds?: readonly string[];
+    isGeometryCurrent?: () => boolean;
     compact?: boolean;
     preflight?: DocumentEngineOptions['preflight'];
     act(label: string, apply: (transaction: DocumentTransaction) => void): boolean;

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

@@ -1,13 +1,17 @@
 import type { DataProjection } from '../../binding/preview.js';
 import type { WorkspaceCamera } from '../contracts.js';
+import { type ProjectedDocumentNode } from './projection.js';
 import type { DesignDocument, DocumentNode, DocumentTransaction } from '../../document/contracts.js';
 
 type Act = (label: string, apply: (transaction: DocumentTransaction) => void) => unknown;
 /** A camera mounts rulers in viewport pixels and transforms document annotations exactly once. */
-export declare function CanvasGuides({ document, selected, projection, camera, zoom: suppliedZoom, act, width, height, visibleRootIds }: {
+export declare function CanvasGuides({ document, selected, projection, scene, geometryKey, isGeometryCurrent, camera, zoom: suppliedZoom, act, width, height, visibleRootIds }: {
     document: DesignDocument;
     selected?: readonly string[];
     projection?: DataProjection | null;
+    scene?: ProjectedDocumentNode;
+    geometryKey?: string;
+    isGeometryCurrent?: () => boolean;
     camera?: WorkspaceCamera;
     zoom?: number;
     act: Act;

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

@@ -1,3 +1,4 @@
+import type { ProjectedDocumentNode } from './projection.js';
 import type { DataProjection } from '../../binding/preview.js';
 import type { DesignDocument, DocumentTransaction } from '../../document/contracts.js';
 import { type PrototypeConnectionSelection } from './prototypeWiringModel.js';
@@ -8,6 +9,9 @@ export interface PrototypeWiringProps {
     selected: readonly string[];
     projection: DataProjection | null;
     zoom: number;
+    scene?: ProjectedDocumentNode;
+    geometryKey?: string;
+    isGeometryCurrent?: () => boolean;
     visibleRootIds?: readonly string[];
     selectedConnection: PrototypeConnectionSelection | null;
     onSelectConnection(value: PrototypeConnectionSelection | null): void;

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

@@ -1,5 +1,6 @@
 import type { DataProjection } from '../../binding/preview.js';
 import type { DesignDocument, DocumentTransaction } from '../../document/contracts.js';
+import type { ProjectedDocumentNode } from './projection.js';
 import { type LayerPlacement, type SnapGuide } from './geometryHandles.js';
 
 type Act = (label: string, apply: (transaction: DocumentTransaction) => void) => boolean;
@@ -11,6 +12,11 @@ export interface SelectionHandlesProps {
     selected: readonly string[];
     visibleRootIds?: readonly string[];
     projection: DataProjection | null;
+    scene?: ProjectedDocumentNode;
+    /** Measurement/provider lifetime, including changes that return to the same screen. */
+    geometryKey?: string;
+    /** Synchronous owner check, captured at gesture start and checked before committing. */
+    isGeometryCurrent?: () => boolean;
     /** Canvas scale; handles keep a constant screen size and snapping a constant screen tolerance. */
     zoom: number;
     act: Act;
@@ -41,15 +47,17 @@ export declare const SELECTION_BOX_ID = "selection";
  * mirroring layer arrangement. The dimension badge follows the live world bounds without
  * applying its own document changes.
  */
-export declare function SelectionHandles({ document, selected, visibleRootIds, projection, zoom, act, movePreview, movePreviews, onPreview, onPreviewMany }: SelectionHandlesProps): import("react").JSX.Element;
+export declare function SelectionHandles({ document, selected, visibleRootIds, projection, scene, geometryKey, isGeometryCurrent, zoom, act, movePreview, movePreviews, onPreview, onPreviewMany }: SelectionHandlesProps): import("react").JSX.Element;
 /**
  * Inspector section: the geometry policy for the whole selection, plus parent-relative rotation
  * in degrees and resize constraints when exactly one layer is selected.
  */
-export declare function LayerGeometryInspector({ document, selected, projection, act, compact }: {
+export declare function LayerGeometryInspector({ document, selected, projection, scene, isGeometryCurrent, act, compact }: {
     document: DesignDocument;
     selected: readonly string[];
     projection: DataProjection | null;
+    scene?: ProjectedDocumentNode;
+    isGeometryCurrent?: () => boolean;
     act: Act;
     compact?: boolean;
 }): import("react").JSX.Element | null;

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

@@ -3,6 +3,7 @@ import type { DataProjection } from '../../binding/preview.js';
 import type { DesignDocument, DocumentNode, DocumentTransaction } from '../../document/contracts.js';
 import { type VectorAnchor, type VectorAnchorAddress, type VectorBooleanOperation, type VectorProperties, type VectorShape } from '../../document/vector.js';
 import { type VectorAnchorAction, type VectorAnchorActions, type VectorBooleanPlan, type VectorEditPlan, type VectorStyle, type VectorTool } from './vectorTools.js';
+import type { ProjectedDocumentNode } from './projection.js';
 
 type Act = (label: string, apply: (transaction: DocumentTransaction) => void) => boolean;
 /** Box geometry a canvas gesture is previewing for one layer; the surface draws it instead of the stored path. */
@@ -13,6 +14,12 @@ export interface VectorGeometryPreview {
 export interface VectorEditingSession {
     readonly document: DesignDocument;
     readonly projection: DataProjection | null;
+    /** The same disposable measured scene rendered by the canvas. */
+    readonly scene?: ProjectedDocumentNode;
+    readonly geometryKey?: string;
+    /** Captured at gesture start and checked again before any document command. */
+    readonly isGeometryCurrent?: () => boolean;
+    readonly visibleRootIds?: readonly string[];
     readonly selection: readonly string[];
     readonly tool: VectorTool;
     setTool(tool: VectorTool): void;
@@ -42,6 +49,10 @@ export interface VectorEditingInput {
     document: DesignDocument;
     selection: readonly string[];
     projection: DataProjection | null;
+    scene?: ProjectedDocumentNode;
+    geometryKey?: string;
+    isGeometryCurrent?: () => boolean;
+    visibleRootIds?: readonly string[];
     act: Act;
     select(id: string): void;
 }
@@ -67,7 +78,7 @@ export declare function VectorNodeSurface({ node, width, height, vector }: {
  * The returned `toolbar` and `inspector` are ready to mount; the canvas mounts `VectorEditor`
  * with the same session inside the stage.
  */
-export declare function useVectorEditing({ document, selection, projection, act, select }: VectorEditingInput): VectorEditing;
+export declare function useVectorEditing({ document, selection, projection, scene, geometryKey, isGeometryCurrent, visibleRootIds, act, select }: VectorEditingInput): VectorEditing;
 /**
  * Canvas overlay inside the scaled stage. With the pen tool it covers the stage and turns
  * clicks into anchors (a click on the first anchor closes the path, Enter finishes an open

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

@@ -1,6 +1,7 @@
 import type { DataProjection } from '../../binding/preview.js';
 import type { DesignDocument, DocumentNode } from '../../document/contracts.js';
 import { type VectorShape } from '../../document/vector.js';
+import { type ProjectedDocumentNode } from './projection.js';
 export interface CanvasBox {
     x: number;
     y: number;
@@ -13,7 +14,11 @@ export interface CanvasEntry {
     topLevel: boolean;
 }
 export type DrawingTool = 'frame' | 'text' | VectorShape;
-export declare function canvasEntries(document: DesignDocument, projection: DataProjection | null, selected?: readonly string[], visibleRootIds?: readonly string[]): CanvasEntry[];
+/** A selected definition descendant keeps its shared root visible without exposing inactive pages. */
+export declare function selectedSharedRootIds(document: DesignDocument, selected: readonly string[]): readonly string[];
+export declare function canvasEntries(document: DesignDocument, projection: DataProjection | null, selected?: readonly string[], visibleRootIds?: readonly string[], scene?: ProjectedDocumentNode): CanvasEntry[];
+/** A mixed unavailable/preparing scene must not finalize a fit using partial bounds. */
+export declare function canvasGeometryReady(scene: ProjectedDocumentNode): boolean;
 export declare function canvasBounds(entries: readonly CanvasEntry[]): CanvasBox;
 export declare function marqueeSelection(document: DesignDocument, entries: readonly CanvasEntry[], box: CanvasBox): readonly string[];
 export declare function drawingBox(start: {

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

@@ -1,6 +1,7 @@
 import type { DataProjection } from '../../binding/preview.js';
 import type { DesignDocument, DocumentDiagnostic, DocumentMatrix, DocumentNodeConstraints, DocumentTransaction } from '../../document/contracts.js';
 import { documentTransformedBounds } from '../../document/geometry.js';
+import { type ProjectedDocumentNode } from './projection.js';
 /**
  * Pure geometry for the selection handles: which layers may be edited on the
  * canvas, how a handle drag becomes a new size and placement, how a rotation
@@ -36,6 +37,15 @@ export interface LayerGeometry extends LayerPlacement {
         readonly width: boolean;
         readonly height: boolean;
     };
+    /** Canonical sizes are retained even when the disposable scene derives an axis. */
+    readonly authoredSize?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly derivedAxes?: {
+        readonly width: boolean;
+        readonly height: boolean;
+    };
     readonly notes: readonly DocumentDiagnostic[];
     readonly constraints: DocumentNodeConstraints | undefined;
     /** Constraints only act inside a free-placement container that can itself be resized. */
@@ -95,6 +105,8 @@ export interface SnapResult {
     readonly guides: readonly SnapGuide[];
 }
 export interface SnapCandidateOptions {
+    /** The same disposable final scene used by the canvas, including measured text. */
+    readonly scene?: ProjectedDocumentNode;
     /** 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). */
@@ -226,6 +238,6 @@ export declare function snapMove(session: MoveSnapSession, delta: {
  * uses `resize` so child constraints apply, a placement change uses `move`, and a rotation
  * replaces the transform. Nothing is issued when the placement is unchanged.
  */
-export declare function applyLayerPlacement(transaction: DocumentTransaction, nodeId: string, before: LayerPlacement, after: LayerPlacement): boolean;
+export declare function applyLayerPlacement(transaction: DocumentTransaction, nodeId: string, before: LayerPlacement & Pick<LayerGeometry, 'authoredSize' | 'derivedAxes' | 'resizeAxes'>, after: LayerPlacement): boolean;
 /** Commit every member of a selection gesture in the caller's transaction; true when any layer changed. */
 export declare function applySelectionPlacements(transaction: DocumentTransaction, layers: readonly LayerGeometry[], placements: readonly SelectionPlacement[]): boolean;

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

@@ -1,5 +1,6 @@
 import type { DataProjection } from '../../binding/preview.js';
 import type { DesignDocument, DocumentDiagnostic, DocumentEngineOptions, DocumentTransaction } from '../../document/contracts.js';
+import { type ProjectedDocumentNode } from './projection.js';
 export type DocumentLayerArrangement = 'align-left' | 'align-center-x' | 'align-right' | 'align-top' | 'align-center-y' | 'align-bottom' | 'distribute-horizontal' | 'distribute-vertical';
 export interface DocumentLayerArrangementRequest {
     nodeIds: readonly string[];
@@ -7,6 +8,8 @@ export interface DocumentLayerArrangementRequest {
 }
 export interface DocumentLayerArrangementOptions extends Pick<DocumentEngineOptions, 'preflight'> {
     projection?: DataProjection | null;
+    scene?: ProjectedDocumentNode;
+    visibleRootIds?: readonly string[];
 }
 export interface ReadyDocumentLayerArrangement {
     readonly status: 'ready';
@@ -36,4 +39,4 @@ export type DocumentLayerArrangementPlan = ReadyDocumentLayerArrangement | {
  */
 export declare function planDocumentLayerArrangement(document: DesignDocument, request: DocumentLayerArrangementRequest, options?: DocumentLayerArrangementOptions): DocumentLayerArrangementPlan;
 /** Run as the only move batch in one live transaction; let validation errors roll it back. */
-export declare function applyDocumentLayerArrangement(transaction: DocumentTransaction, plan: ReadyDocumentLayerArrangement, currentDocument: DesignDocument, projection?: DataProjection | null): void;
+export declare function applyDocumentLayerArrangement(transaction: DocumentTransaction, plan: ReadyDocumentLayerArrangement, currentDocument: DesignDocument, projection?: DataProjection | null, scene?: ProjectedDocumentNode): void;

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

@@ -1,6 +1,7 @@
 import type { BindingRuntimeScope } from '../../binding/contracts.js';
 import type { DataProjection } from '../../binding/preview.js';
-import type { DesignDocument, DocumentNode, DocumentResolveOptions } from '../../document/contracts.js';
+import type { DesignDocument, DocumentDiagnostic, DocumentNode, DocumentResolveOptions } from '../../document/contracts.js';
+import type { TextLayoutSnapshot } from '../../document/textLayout.js';
 export interface ProjectedDocumentNode {
     sourceNodeId: string;
     instanceId?: string;
@@ -9,6 +10,27 @@ export interface ProjectedDocumentNode {
     rowPath: BindingRuntimeScope['rowPath'];
     node: DocumentNode;
     children: ProjectedDocumentNode[];
+    /** Disposable measured geometry; never serialized into the authored document. */
+    textLayout?: ProjectedTextLayout;
 }
+export interface ProjectedTextLayout {
+    readonly status: 'preparing' | 'ready' | 'unavailable' | 'failed';
+    readonly authoredSize: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly derivedAxes: {
+        readonly width: boolean;
+        readonly height: boolean;
+    };
+    readonly diagnostics: readonly DocumentDiagnostic[];
+    readonly snapshot?: TextLayoutSnapshot;
+    /** Parent bounds may be fixed while unresolved layout changes its child placements. */
+    readonly childrenPending?: boolean;
+}
+/** Fixed parent bounds remain usable; only derived size or unresolved ancestor placement is refused. */
+export declare function projectedGeometryDiagnostics(item: ProjectedDocumentNode, ancestors?: readonly ProjectedDocumentNode[]): readonly DocumentDiagnostic[];
+/** Reuses the canonical layout solver on a disposable scene, including repeated index addresses. */
+export declare function reflowProjectedDocumentScene(scene: ProjectedDocumentNode): ProjectedDocumentNode;
 /** Fixture rows affect this disposable scene only, never canonical document geometry. */
 export declare function projectDocumentScene(document: DesignDocument, data: DataProjection | null, resolveOptions?: DocumentResolveOptions, resolveRowOptions?: (rowPath: BindingRuntimeScope['rowPath']) => DocumentResolveOptions): ProjectedDocumentNode;

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

@@ -1,6 +1,7 @@
 import type { DataProjection } from '../../binding/preview.js';
 import type { DesignDocument, DocumentTransaction } from '../../document/contracts.js';
 import { type PrototypeAction, type PrototypeInteraction } from '../../document/prototype.js';
+import { type ProjectedDocumentNode } from './projection.js';
 export type PrototypeActionPath = readonly (number | 'branches' | 'actions' | 'otherwise')[];
 export interface PrototypeConnectionSelection {
     nodeId: string;
@@ -35,7 +36,7 @@ export declare const connectionKey: (value: PrototypeConnectionSelection) => str
 /** 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;
+export declare function planPrototypeWiring(document: DesignDocument, projection: DataProjection | null, selected?: readonly string[], visibleRootIds?: readonly string[], scene?: ProjectedDocumentNode): 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;

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

@@ -0,0 +1,28 @@
+import type { DataProjection } from '../../binding/preview.js';
+import type { DesignDocument, DocumentDiagnostic } from '../../document/contracts.js';
+import { type ProjectedDocumentNode, type ProjectedTextLayout } from './projection.js';
+import type { TextLayoutRuntime } from './textLayoutRuntime.js';
+export interface TextLayoutSceneOptions {
+    readonly scene: ProjectedDocumentNode;
+    readonly revisionKey: string;
+    readonly visibleRootIds?: readonly string[];
+    readonly projection?: DataProjection | null;
+    readonly sourceMapped?: boolean;
+}
+export interface TextLayoutScene {
+    readonly scene: ProjectedDocumentNode;
+    readonly status: ProjectedTextLayout['status'];
+    readonly diagnostics: readonly DocumentDiagnostic[];
+}
+/** Carries unresolved derived axes to ancestors before any asynchronous work starts. */
+export declare function prepareTextLayoutScene(document: DesignDocument, options: TextLayoutSceneOptions, available?: boolean): TextLayoutScene;
+/** One bounded disposable layout, shared by rendering and every geometry reader. */
+export declare function measureTextLayoutScene(document: DesignDocument, options: TextLayoutSceneOptions & {
+    runtime: TextLayoutRuntime;
+    signal?: AbortSignal;
+    retry?: boolean;
+}): Promise<TextLayoutScene>;
+/** Position-only candidate validation. The caller must also retain the original scene lifetime guard. */
+export declare function reuseTextLayoutScene(document: DesignDocument, options: TextLayoutSceneOptions & {
+    measuredScene: ProjectedDocumentNode;
+}): TextLayoutScene;

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

@@ -0,0 +1,19 @@
+import type { DocumentEngine } from '../../document/contracts.js';
+import { type TextLayoutScene, type TextLayoutSceneOptions } from './textLayoutProjection.js';
+import type { TextLayoutRuntime } from './textLayoutRuntime.js';
+export interface UseTextLayoutOptions extends TextLayoutSceneOptions {
+    readonly engine: DocumentEngine;
+    readonly runtime?: TextLayoutRuntime | null;
+    readonly lifetimeKey: string;
+    /** Fires synchronously for target, mode, page or provider transitions, including batched round trips. */
+    readonly subscribeLifetime?: (invalidate: () => void) => () => void;
+    readonly ownerDocument?: Document;
+}
+export interface TextLayoutState extends TextLayoutScene {
+    readonly geometryKey: string;
+    /** Capture this function at gesture start; a later render cannot revive that geometry. */
+    readonly isCurrent: () => boolean;
+    readonly retry: () => void;
+}
+/** One subscription owns the disposable scene and its synchronous invalidation epoch. */
+export declare function useTextLayout(options: UseTextLayoutOptions): TextLayoutState;

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

@@ -1,8 +1,8 @@
 import type { DataProjection } from '../../binding/preview.js';
 import type { DesignDocument, DocumentDiagnostic, DocumentMatrix, DocumentNode, DocumentNodePatch, DocumentTransaction } from '../../document/contracts.js';
 import { booleanVectorPrecision, type VectorAnchor, type VectorAnchorAddress, type VectorBooleanOperation, type VectorFillRule, type VectorPoint, type VectorProperties, type VectorShape, type VectorStroke } from '../../document/vector.js';
-import { type LayerGeometry } from './geometryHandles.js';
-import type { ProjectedDocumentNode } from './projection.js';
+import { type LayerGeometry, type SnapCandidateOptions } from './geometryHandles.js';
+import { type ProjectedDocumentNode } from './projection.js';
 /**
  * Pure editing model for `vector` layers. The document stores path data under
  * `node.properties.vector` in the layer's own space; the layer box is the geometry's
@@ -91,7 +91,9 @@ export declare function vectorGeometryPatch(node: DocumentNode, next: VectorProp
 /** Changes paint and corner keys without touching geometry; an `undefined` value removes the key. */
 export declare function vectorStylePatch(node: DocumentNode, style: Partial<VectorStyle>): DocumentNodePatch;
 /** Canvas placement of a layer: the world transform with the root's own transform removed, as the canvas renders it. */
-export declare function renderedWorldTransform(document: DesignDocument, nodeId: string): DocumentMatrix;
+export declare function renderedWorldTransform(document: DesignDocument, nodeId: string, options?: SnapCandidateOptions & {
+    projection?: DataProjection | null;
+}): DocumentMatrix;
 /** New layers join the selected container, or the root; the rule matches text insertion. */
 export declare function vectorInsertParent(document: DesignDocument, selection: readonly string[]): string;
 /** A default-sized shape placed inside the parent, offset by the number of existing children so repeated inserts stay visible. */
@@ -105,13 +107,15 @@ export declare function penPathNode(points: readonly VectorAnchor[], closed: boo
  * selection handles use, so an auto layout child, a source layout fragment, or a repeated
  * row is refused with the same diagnostic instead of a guessed box.
  */
-export declare function planVectorEdit(document: DesignDocument, selection: readonly string[], projection: DataProjection | null): VectorEditPlan;
+export declare function planVectorEdit(document: DesignDocument, selection: readonly string[], projection: DataProjection | null, options?: SnapCandidateOptions): VectorEditPlan;
 /** Anchor operations the current anchor selection allows. */
 export declare function vectorAnchorActions(vector: VectorProperties, anchors: readonly VectorAnchorAddress[]): VectorAnchorActions;
 /** Applies one anchor action to the box geometry; the caller commits the result as one transaction. */
 export declare function applyVectorAnchorAction(vector: VectorProperties, anchors: readonly VectorAnchorAddress[], action: VectorAnchorAction): VectorAnchorActionResult;
 /** Two vector layers sharing a parent; the lower layer (earlier in the parent order) is the base of a subtraction. */
-export declare function planVectorBoolean(document: DesignDocument, selection: readonly string[]): VectorBooleanPlan;
+export declare function planVectorBoolean(document: DesignDocument, selection: readonly string[], options?: SnapCandidateOptions & {
+    projection?: DataProjection | null;
+}): VectorBooleanPlan;
 /** The combined layer, in the parent's space, with the lower layer's paint. Throws when the result has no shape. */
 export declare function vectorBooleanNode(plan: Extract<VectorBooleanPlan, {
     status: 'ready';

package/package.json

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