@pygmalionjs/pygmalion 0.18.0 → 0.20.0

package/dist-lib/types/editor/conditionAxes.d.ts

@@ -0,0 +1,60 @@
+import type { StoryboardEnvironment } from './designImport.js';
+/**
+ * One value of a catalog condition axis.
+ *
+ * The environment is what the value means to the browser: boot storage,
+ * permissions, devices, an opaque screen preset. It is merged into the
+ * storyboard baseline, so every capture fingerprint, flow session and
+ * Application run re-resolves under it. An option without an environment is a
+ * pure catalog choice and leaves existing capture identities untouched.
+ */
+export interface CatalogConditionAxisOptionDef {
+    value: string;
+    label: string;
+    description?: string;
+    environment?: StoryboardEnvironment;
+}
+/**
+ * One independent condition the whole catalog can be seen under.
+ *
+ * A session preset is a single runtime choice; a preview environment control
+ * dresses only the live preview. Products also have flags that cut across both:
+ * a color scheme, an account level, a feature entitlement. Each is its own axis
+ * with stable value ids. Screens say in `conditions` which values they exist
+ * under; a screen that names no axis exists under every value of it.
+ *
+ * Without `defaultValue` an unselected axis constrains nothing, the same way the
+ * legacy "Default" session shows every runtime. With one, the default is the
+ * effective value from the start.
+ */
+export interface CatalogConditionAxisDef {
+    id: string;
+    label: string;
+    description?: string;
+    defaultValue?: string;
+    options: readonly CatalogConditionAxisOptionDef[];
+}
+/** Explicit selections only; defaults stay implicit. */
+export type CatalogConditionSelections = Readonly<Record<string, string>>;
+/** Values, per axis id, a screen exists under. Absent axes mean every value. */
+export type ScreenConditionDeclaration = Readonly<Record<string, readonly string[]>>;
+/**
+ * One editor's declared condition axes, the explicit selections, and the
+ * environment they contribute to the storyboard baseline.
+ */
+export declare function createConditionAxes(deps: {
+    setStoryboardBaselineEnvironment(environment?: StoryboardEnvironment): void;
+}): {
+    setConditionAxes: (next: readonly CatalogConditionAxisDef[]) => void;
+    getConditionAxes: () => readonly CatalogConditionAxisDef[];
+    getConditionAxisValue: (axisId: string) => string | null | undefined;
+    getConditionAxisSelections: () => CatalogConditionSelections;
+    selectConditionAxisValue: (axisId: string, value: string | null) => void;
+    clearConditionAxisSelections: () => void;
+    getConditionAxesEnvironment: () => StoryboardEnvironment | undefined;
+    isInSelectedConditions: (conditions: ScreenConditionDeclaration | undefined) => boolean;
+    conditionDeclarationIssues: (conditions: ScreenConditionDeclaration | undefined) => string[];
+    subscribeConditionAxes: (listener: () => void) => () => void;
+    getConditionAxesRevision: () => number;
+};
+export type ConditionAxes = ReturnType<typeof createConditionAxes>;

package/dist-lib/types/editor/declarations.d.ts

@@ -1,11 +1,13 @@
+import { type ScreenConditionDeclaration } from './conditionAxes.js';
+import type { StoryboardEnvironment } from './designImport.js';
 export declare function createEditorDeclarations(): {
     setPreviewDependencyDigests: (routes: readonly {
         path?: string;
         dependencyDigest?: string;
     }[] | null) => void;
     previewDependencyDigest: (route: string) => string | undefined;
-    routePreviewFrameRecipe: (page: import("./previewBootstrap.js").PreviewFramePage, baselineEnvironment?: import("./designImport.js").StoryboardEnvironment) => import("./previewBootstrap.js").RoutePreviewFrameRecipe;
-    createRoutePreviewFrameFingerprint: (page: import("./previewBootstrap.js").PreviewFramePage, previewRevision: string, baselineEnvironment?: import("./designImport.js").StoryboardEnvironment) => string;
+    routePreviewFrameRecipe: (page: import("./previewBootstrap.js").PreviewFramePage, baselineEnvironment?: StoryboardEnvironment) => import("./previewBootstrap.js").RoutePreviewFrameRecipe;
+    createRoutePreviewFrameFingerprint: (page: import("./previewBootstrap.js").PreviewFramePage, previewRevision: string, baselineEnvironment?: StoryboardEnvironment) => string;
     setDesignImportController: (controller: import("./designImport.js").DesignImportController | null) => void;
     getDesignImportController: () => import("./designImport.js").DesignImportController | null;
     setSurfaceClassifications: (classifications: readonly import("./surfaceDemands.js").SurfaceClassification[] | undefined) => void;
@@ -20,17 +22,32 @@ export declare function createEditorDeclarations(): {
     subscribeStoryboardGraph: (listener: () => void) => () => void;
     bumpPreviewIdentityEpoch: () => void;
     getPreviewIdentityEpoch: () => number;
-    setStoryboardBaselineEnvironment: (environment?: import("./designImport.js").StoryboardEnvironment) => void;
-    getStoryboardBaselineEnvironment: () => import("./designImport.js").StoryboardEnvironment | undefined;
+    setStoryboardBaselineEnvironment: (environment?: StoryboardEnvironment) => void;
+    getStoryboardBaselineEnvironment: () => StoryboardEnvironment | undefined;
     setPreviewEnvironmentControls: (next: readonly import("./previewEnvironmentControls.js").PreviewEnvironmentControlDef[]) => void;
     getPreviewEnvironmentControls: () => readonly import("./previewEnvironmentControls.js").PreviewEnvironmentControlDef[];
     getPreviewEnvironmentControlSelections: () => Readonly<Record<string, string>>;
     getPreviewEnvironmentControlValue: (controlId: string) => string | undefined;
     setPreviewEnvironmentControlValue: (controlId: string, value: string) => void;
     clearPreviewEnvironmentControlValues: () => void;
-    getPreviewEnvironmentOverride: () => import("./designImport.js").StoryboardEnvironment | undefined;
+    getPreviewEnvironmentOverride: () => StoryboardEnvironment | undefined;
     subscribePreviewEnvironmentControls: (listener: () => void) => () => void;
     getPreviewEnvironmentControlRevision: () => number;
+    isPageInSelectedConditions: (page: {
+        runtimes?: readonly string[];
+        conditions?: ScreenConditionDeclaration;
+    }) => boolean;
+    setConditionAxes: (next: readonly import("./conditionAxes.js").CatalogConditionAxisDef[]) => void;
+    getConditionAxes: () => readonly import("./conditionAxes.js").CatalogConditionAxisDef[];
+    getConditionAxisValue: (axisId: string) => string | null | undefined;
+    getConditionAxisSelections: () => import("./conditionAxes.js").CatalogConditionSelections;
+    selectConditionAxisValue: (axisId: string, value: string | null) => void;
+    clearConditionAxisSelections: () => void;
+    getConditionAxesEnvironment: () => StoryboardEnvironment | undefined;
+    isInSelectedConditions: (conditions: ScreenConditionDeclaration | undefined) => boolean;
+    conditionDeclarationIssues: (conditions: ScreenConditionDeclaration | undefined) => string[];
+    subscribeConditionAxes: (listener: () => void) => () => void;
+    getConditionAxesRevision: () => number;
     setSessionPresets: (next: readonly import("./sessionPresets.js").SessionPresetDef[]) => void;
     getSessionPresets: () => import("./sessionPresets.js").SessionPresetDef[];
     getSelectedSessionPreset: () => number | null;

package/dist-lib/types/editor/designImport.d.ts

@@ -258,6 +258,12 @@ export interface DesignImportPage {
      * runtime — only the screens a runtime cannot reach at all need to say so.
      */
     runtimes?: readonly string[];
+    /**
+     * Values, per condition axis id, this screen exists under. An absent axis
+     * means every value of it; unknown ids or values hide the screen and are
+     * reported as declaration issues rather than passing silently.
+     */
+    conditions?: Readonly<Record<string, readonly string[]>>;
     scenarioId?: string;
     /**
      * Every scenario this screen demonstrates. Coverage is the whole set; the
@@ -400,6 +406,12 @@ export interface DesignImportInitialPage {
      * runtime — only the screens a runtime cannot reach at all need to say so.
      */
     runtimes?: readonly string[];
+    /**
+     * Values, per condition axis id, this screen exists under. An absent axis
+     * means every value of it; unknown ids or values hide the screen and are
+     * reported as declaration issues rather than passing silently.
+     */
+    conditions?: Readonly<Record<string, readonly string[]>>;
     scenarioId?: string;
     /** Every authored scenario this initial screen demonstrates. */
     scenarioIds?: readonly string[];

package/dist-lib/types/editor/revisionCatalog.d.ts

@@ -7,6 +7,7 @@ import type { FrameBranchKindDef, FrameLabelLabels } from './frameLabels.js';
 import type { ScreenLaneDef } from './frameLanes.js';
 import { type ScreenStateAxisDef } from './interactiveStates.js';
 import type { PreviewEnvironmentControlDef } from './previewEnvironmentControls.js';
+import type { CatalogConditionAxisDef } from './conditionAxes.js';
 import type { RegistryEntry } from './registry.js';
 import type { ScenarioCoverageClaim } from './scenarioCoverage.js';
 import type { ScreenCardDef } from './screenCards.js';
@@ -55,6 +56,8 @@ export interface PygmalionRevisionCatalogV1 {
     viewportPresets?: readonly ViewportPresetDef[];
     sessionPresets?: readonly SessionPresetDef[];
     previewEnvironmentControls?: readonly PreviewEnvironmentControlDef[];
+    /** Independent catalog conditions every screen, capture and run resolves under. */
+    conditionAxes?: readonly CatalogConditionAxisDef[];
     screenFlows?: readonly ScreenFlowPath[];
     scenarioCoverage?: readonly ScenarioCoverageClaim[];
     screenDimensions?: readonly ScreenDimensionDef[];

package/dist-lib/types/editor/revisionCatalogInstall.d.ts

@@ -4,6 +4,7 @@ import type { FrameBranchKindDef, FrameLabelLabels } from './frameLabels.js';
 import type { ScreenLaneDef } from './frameLanes.js';
 import type { ScreenStateAxisDef } from './interactiveStates.js';
 import type { PreviewEnvironmentControlDef } from './previewEnvironmentControls.js';
+import type { CatalogConditionAxisDef } from './conditionAxes.js';
 import type { ComponentRegistry, RegistryEntry } from './registry.js';
 import type { ScenarioCoverageClaim } from './scenarioCoverage.js';
 import type { ScreenCardDef } from './screenCards.js';
@@ -27,6 +28,7 @@ export interface RevisionCatalogDeclarations {
     viewportPresets?: readonly ViewportPresetDef[];
     sessionPresets?: readonly SessionPresetDef[];
     previewEnvironmentControls?: readonly PreviewEnvironmentControlDef[];
+    conditionAxes?: readonly CatalogConditionAxisDef[];
     screenFlows?: readonly ScreenFlowPath[];
     scenarioCoverage?: readonly ScenarioCoverageClaim[];
     screenDimensions?: readonly ScreenDimensionDef[];

package/dist-lib/types/editor/store.d.ts

@@ -205,6 +205,12 @@ export interface PageModel {
      * a runtime cannot reach at all need to say so.
      */
     runtimes?: readonly string[];
+    /**
+     * Values, per condition axis id, this screen exists under. An absent axis
+     * means every value of it; unknown ids or values hide the screen and are
+     * reported as declaration issues rather than passing silently.
+     */
+    conditions?: Readonly<Record<string, readonly string[]>>;
     scenarioId?: string;
     /** Every scenario the screen demonstrates; coverage counts this set. */
     scenarioIds?: readonly string[];

package/dist-lib/types/editor/storyboardEnvironment.d.ts

@@ -2,6 +2,11 @@ import type { StoryboardEnvironment } from './designImport.js';
 export declare const STORYBOARD_ENVIRONMENT_QUERY: "__pygmalion_environment";
 export declare const STORYBOARD_ENVIRONMENT_CONTROL: "/__pygmalion-storyboard/environment";
 export declare function mergeStoryboardEnvironment(base?: StoryboardEnvironment, override?: StoryboardEnvironment): StoryboardEnvironment | undefined;
+/**
+ * Drops record keys the merge left empty so a composed environment reads, and
+ * hashes, the same as one declared directly. `undefined` when nothing remains.
+ */
+export declare function compactStoryboardEnvironment(environment?: StoryboardEnvironment): StoryboardEnvironment | undefined;
 /**
  * Boot-time environment derived from a screen preset — parity with the Node
  * capture runtime's init script, which installs the preset global and seeds

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

@@ -174,6 +174,8 @@ export { SourceRefControl } from './ui/SourceRefControl.js';
 export type { SourceRefControlProps } from './ui/SourceRefControl.js';
 export type { TokenDef } from './editor/tokens.js';
 import type { SessionPresetDef } from './editor/sessionPresets.js';
+import type { CatalogConditionAxisDef } from './editor/conditionAxes.js';
+export type { CatalogConditionAxisDef, CatalogConditionAxisOptionDef, CatalogConditionSelections, ScreenConditionDeclaration, } from './editor/conditionAxes.js';
 export type { ViewportPresetDef } from './editor/viewportPresets.js';
 export type { SessionPresetDef } from './editor/sessionPresets.js';
 export { GENERIC_ASSERTION_SHARE, MIN_UNVERIFIED_REASON_LENGTH, detectStateGroupCandidates, hooksInSelector, summarizeConditionCoverage, validateHookTargeting, validateScreenConformance, } from './editor/screenConformance.js';
@@ -237,6 +239,13 @@ export interface PygmalionEditorProps {
     sessionPresets?: readonly SessionPresetDef[];
     /** Host-declared browser conditions shown in the active frame's Preview inspector. */
     previewEnvironmentControls?: readonly PreviewEnvironmentControlDef[];
+    /**
+     * Independent catalog conditions — a color scheme, an account level — that
+     * every screen, capture and run resolves under. Screens name the values they
+     * exist in through `conditions`; an option's environment joins the storyboard
+     * baseline so captures re-resolve when the value changes.
+     */
+    conditionAxes?: readonly CatalogConditionAxisDef[];
     /** A public importer that provides unified control over code inventory and importing of entire DOM layers. */
     designImport?: DesignImportController;
     /** Called with cumulative changes when editing a token in the Assets panel — the host is responsible for writing back (file saving). */

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/WorkspaceConditions.d.ts

@@ -1,7 +1,7 @@
 import type { EditorDeclarations } from '../editor/declarations.js';
 
 export interface WorkspaceConditionsProps {
-    declarations: Pick<EditorDeclarations, 'getSessionPresets' | 'getSelectedSessionPreset' | 'selectSessionPreset' | 'subscribeSessionPresets' | 'getPreviewEnvironmentControls' | 'getPreviewEnvironmentControlValue' | 'getPreviewEnvironmentControlSelections' | 'setPreviewEnvironmentControlValue' | 'clearPreviewEnvironmentControlValues' | 'subscribePreviewEnvironmentControls' | 'getPreviewEnvironmentControlRevision'>;
+    declarations: Pick<EditorDeclarations, 'getSessionPresets' | 'getSelectedSessionPreset' | 'selectSessionPreset' | 'subscribeSessionPresets' | 'getConditionAxes' | 'getConditionAxisValue' | 'getConditionAxisSelections' | 'selectConditionAxisValue' | 'clearConditionAxisSelections' | 'subscribeConditionAxes' | 'getConditionAxesRevision' | 'getPreviewEnvironmentControls' | 'getPreviewEnvironmentControlValue' | 'getPreviewEnvironmentControlSelections' | 'setPreviewEnvironmentControlValue' | 'clearPreviewEnvironmentControlValues' | 'subscribePreviewEnvironmentControls' | 'getPreviewEnvironmentControlRevision'>;
 }
 /** Present declared catalog sessions and preview values without interpreting product policy. */
 export declare function WorkspaceConditions({ declarations }: WorkspaceConditionsProps): import("react").JSX.Element | null;

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;