@pygmalionjs/pygmalion 0.8.1 → 0.9.0

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

@@ -0,0 +1,224 @@
+import type { DataProjection } from '../../binding/preview.js';
+import type { DesignDocument, DocumentDiagnostic, DocumentMatrix, DocumentNodeConstraints, DocumentTransaction } from '../../document/contracts.js';
+import { documentTransformedBounds } from '../../document/geometry.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
+ * gesture becomes a transform, where a moving box snaps, and how several free
+ * layers resize and rotate together as one selection box.
+ *
+ * Every function here is deterministic and free of DOM access so the overlay
+ * stays a thin event adapter and the math can be exercised in plain node tests.
+ * Angles follow the design tool convention: degrees are positive
+ * counter-clockwise on screen. The document y-axis points down, so a CSS
+ * `rotate(θ)` equals `-θ` in that convention.
+ */
+export type GeometryHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+export declare const GEOMETRY_HANDLES: readonly GeometryHandle[];
+export type DocumentBounds = ReturnType<typeof documentTransformedBounds>;
+export interface LayerPlacement {
+    readonly transform: DocumentMatrix;
+    readonly width: number;
+    readonly height: number;
+}
+export interface LayerGeometry extends LayerPlacement {
+    readonly nodeId: string;
+    readonly name: string;
+    /** The projected parent; the document root for top-level layers. */
+    readonly parentId: string;
+    readonly parentWorld: DocumentMatrix;
+    readonly world: DocumentMatrix;
+    /** World-axis bounding box of the rendered layer. */
+    readonly bounds: DocumentBounds;
+    /** False when the size is derived (hug contents, repeated examples); rotation and movement stay available. */
+    readonly resizable: boolean;
+    readonly resizeAxes?: {
+        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. */
+    readonly constraintsEditable: boolean;
+}
+export interface SelectionHandlesPlan {
+    readonly layers: readonly LayerGeometry[];
+    readonly blocked: readonly DocumentDiagnostic[];
+}
+export interface ResizeGesture {
+    readonly handle: GeometryHandle;
+    /** Pointer travel in canvas units (screen pixels divided by zoom). */
+    readonly delta: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly aspectLock?: boolean;
+    readonly fromCenter?: boolean;
+}
+/** A placement of a layer inside a shared box (parent-relative, like the layer's own transform). */
+export interface SelectionPlacement extends LayerPlacement {
+    readonly nodeId: string;
+}
+export type SnapReference = 'start' | 'center' | 'end';
+export interface SnapEdges {
+    readonly x?: readonly SnapReference[];
+    readonly y?: readonly SnapReference[];
+}
+/** One distance between two boxes along an axis, drawn at the cross-axis coordinate `at`. */
+export interface SnapGap {
+    readonly from: number;
+    readonly to: number;
+    readonly at: number;
+}
+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. */
+    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". */
+    readonly start: number;
+    readonly end: number;
+    /** When set, only this reference of the moving box may land on the line. */
+    readonly reference?: SnapReference;
+    /** The equal distances a `spacing` candidate reproduces, for drawing. */
+    readonly gaps?: readonly SnapGap[];
+}
+export interface SnapResult {
+    readonly dx: number;
+    readonly dy: number;
+    readonly guides: readonly SnapGuide[];
+}
+export interface SnapCandidateOptions {
+    /** Include the moving layers' own children: right for a resize, wrong for a move (the children travel along). */
+    readonly children?: boolean;
+}
+export interface MoveSnapSession {
+    readonly nodeIds: readonly string[];
+    readonly bounds: DocumentBounds;
+    readonly candidates: readonly SnapGuide[];
+    readonly tolerance: number;
+}
+/**
+ * Decide, per selected layer, whether canvas handles may edit it. The policy matches
+ * layer arrangement: repeated rows, auto layout children, and source-layout fragments are
+ * 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 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
+ * corner stays fixed in the layer's own frame, so the anchor is exact for rotated and
+ * skewed layers. Aspect lock keeps the starting ratio; center mode grows both sides.
+ */
+export declare function resizeLayer(layer: LayerPlacement & {
+    readonly parentWorld: DocumentMatrix;
+}, gesture: ResizeGesture): LayerPlacement;
+/** Rotation of a local transform relative to its parent, in degrees, positive counter-clockwise on screen. */
+export declare function layerRotationDegrees(transform: DocumentMatrix): number;
+/** Rotate a layer about any world point; the result is the new parent-relative transform. */
+export declare function rotateLayerAbout(layer: LayerPlacement & {
+    readonly parentWorld: DocumentMatrix;
+}, degrees: number, center: {
+    readonly x: number;
+    readonly y: number;
+}): DocumentMatrix;
+/**
+ * Rotate a layer about its own center. `world` space rotates what the user sees regardless of
+ * parent transforms; `parent` space changes the inspector's parent-relative angle exactly.
+ */
+export declare function rotateLayer(layer: LayerPlacement & {
+    readonly parentWorld: DocumentMatrix;
+}, degrees: number, space?: 'world' | 'parent'): DocumentMatrix;
+/** Set the parent-relative rotation shown in the inspector, keeping the center in place. */
+export declare function setLayerRotation(layer: LayerPlacement & {
+    readonly parentWorld: DocumentMatrix;
+}, degrees: number): DocumentMatrix;
+/** Angle swept by a pointer around a center, in degrees positive counter-clockwise on screen. */
+export declare function rotationGestureDegrees(center: {
+    x: number;
+    y: number;
+}, from: {
+    x: number;
+    y: number;
+}, to: {
+    x: number;
+    y: number;
+}): number;
+export declare function snapRotation(degrees: number, step?: number): number;
+/** Snap distance in canvas units for a constant on-screen tolerance. */
+export declare function snapTolerance(zoom: number, screenPixels?: number): number;
+/** World-axis box around several layers; null without layers. */
+export declare function selectionBounds(layers: readonly Pick<LayerGeometry, 'bounds'>[]): DocumentBounds | null;
+/**
+ * Layers of a selection that transform independently: a layer whose ancestor is also selected
+ * travels with that ancestor, so applying the box transform to both would move it twice.
+ */
+export declare function independentLayers(document: DesignDocument, layers: readonly LayerGeometry[]): LayerGeometry[];
+/** Exact affine scaling of the shared world box, retaining finite local sizes.
+ * Nonuniform scaling of rotated layers changes their angle/skew rather than approximating bounds.
+ */
+export declare function scaleLayersToBox(layers: readonly LayerGeometry[], from: DocumentBounds, to: DocumentBounds): SelectionPlacement[];
+/** A resize handle dragged on the selection box: the box resizes like a layer, its members follow. */
+export declare function resizeSelection(layers: readonly LayerGeometry[], box: DocumentBounds, gesture: ResizeGesture): {
+    readonly box: DocumentBounds;
+    readonly placements: readonly SelectionPlacement[];
+};
+/** Rotate every member about the center of the selection box in world space. */
+export declare function rotateSelection(layers: readonly LayerGeometry[], box: DocumentBounds, degrees: number): SelectionPlacement[];
+/**
+ * Edges and centers of visible siblings, the parent's own bounds, the parent's persisted guides
+ * and layout grid tracks, and (for a resize) the moving layers' own children, excluding the
+ * moving layers themselves.
+ */
+export declare function snapCandidates(document: DesignDocument, nodeIds: readonly string[], projection: DataProjection | null, options?: SnapCandidateOptions): readonly SnapGuide[];
+/**
+ * Positions where a moving box would sit at the same distance from a sibling as two siblings
+ * sit from each other: beyond either end of an aligned pair, or centered in the gap between
+ * them when it fits. Each candidate names the reference of the box that lands and the two
+ * equal gaps to draw.
+ */
+export declare function spacingCandidates(box: DocumentBounds, siblings: readonly {
+    readonly nodeId: string;
+    readonly bounds: DocumentBounds;
+}[]): SnapGuide[];
+/** Move a box by the smallest offset that lands one of its references on a candidate line, per axis. */
+export declare function snapBounds(bounds: DocumentBounds, candidates: readonly SnapGuide[], tolerance: number, edges?: SnapEdges): SnapResult;
+/** References that move for a handle: one edge per axis, or both edges when growing from the center. */
+export declare function resizeSnapEdges(handle: GeometryHandle, fromCenter?: boolean): SnapEdges;
+/**
+ * Resize with snapping: the moving edges of the world box are pulled onto candidate lines by
+ * adjusting the pointer travel. The box is affine in that travel for a fixed handle, so a few
+ * passes converge; only references that land exactly are reported as guides.
+ */
+export declare function snapResizeGesture(layer: LayerPlacement & {
+    readonly parentWorld: DocumentMatrix;
+}, gesture: ResizeGesture, candidates: readonly SnapGuide[], tolerance: number): {
+    placement: LayerPlacement;
+    guides: readonly SnapGuide[];
+};
+/**
+ * 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;
+/** 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;
+    y: number;
+}): {
+    delta: {
+        x: number;
+        y: number;
+    };
+    guides: readonly SnapGuide[];
+};
+/**
+ * Commit a gesture as canonical commands inside the caller's single transaction: a size change
+ * 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;
+/** 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

@@ -0,0 +1,39 @@
+import type { DataProjection } from '../../binding/preview.js';
+import type { DesignDocument, DocumentDiagnostic, DocumentEngineOptions, DocumentTransaction } from '../../document/contracts.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[];
+    action: DocumentLayerArrangement;
+}
+export interface DocumentLayerArrangementOptions extends Pick<DocumentEngineOptions, 'preflight'> {
+    projection?: DataProjection | null;
+}
+export interface ReadyDocumentLayerArrangement {
+    readonly status: 'ready';
+    readonly nodeIds: readonly string[];
+    readonly action: DocumentLayerArrangement;
+    readonly beforeFingerprint: string;
+    /** Only geometry is retained; fixture values never enter a command or document history. */
+    readonly geometryFingerprint: string;
+    readonly operations: readonly {
+        readonly nodeId: string;
+        readonly x: number;
+        readonly y: number;
+    }[];
+}
+export type DocumentLayerArrangementPlan = ReadyDocumentLayerArrangement | {
+    readonly status: 'unchanged';
+    readonly nodeIds: readonly string[];
+    readonly operations: readonly [];
+} | {
+    readonly status: 'blocked';
+    readonly diagnostics: readonly DocumentDiagnostic[];
+};
+/**
+ * Align selected topmost subtrees by world-axis bounding boxes, or distribute equal edge gaps.
+ * Distribution keeps the first and last layer positions fixed; ties use canonical tree order.
+ * A disposable transaction validates the entire result, including current host policy and layout.
+ */
+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;

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

@@ -0,0 +1,44 @@
+import type { DesignDocument, DocumentDiagnostic, DocumentEngineOptions, DocumentTransaction } from '../../document/contracts.js';
+export interface DocumentLayerMoveRequest {
+    nodeIds: readonly string[];
+    targetId: string;
+    placement: 'before' | 'inside' | 'after';
+}
+export interface DocumentLayerMoveOperation {
+    readonly nodeId: string;
+    readonly parentId: string;
+    /** Index in the destination after removing this operation's node. */
+    readonly index: number;
+}
+export interface ReadyDocumentLayerMove {
+    readonly status: 'ready';
+    readonly nodeIds: readonly string[];
+    readonly operations: readonly DocumentLayerMoveOperation[];
+    /** Complete authoring identity, including geometry, bindings, and source revision. */
+    readonly beforeFingerprint: string;
+    readonly parentId: string;
+    /** Final insertion index after removing every selected subtree from the destination. */
+    readonly index: number;
+}
+export type DocumentLayerMovePlan = ReadyDocumentLayerMove | {
+    readonly status: 'unchanged';
+    readonly nodeIds: readonly string[];
+    readonly operations: readonly [];
+} | {
+    readonly status: 'blocked';
+    readonly diagnostics: readonly DocumentDiagnostic[];
+};
+/** Canonical preorder; selecting an ancestor includes its subtree exactly once. */
+export declare function normalizeDocumentLayerSelection(document: DesignDocument, nodeIds: readonly string[]): readonly string[];
+/**
+ * Plan against the current canonical snapshot, preferably again at drop time.
+ * A disposable real transaction owns tree, layout, slot, and binding policy. Free placement keeps
+ * world transforms; a destination layout owns the resulting positions and dimensions.
+ * Preflight must be pure and should match the live engine's current host/binding preflight.
+ */
+export declare function planDocumentLayerMove(document: DesignDocument, request: DocumentLayerMoveRequest, options?: Pick<DocumentEngineOptions, 'preflight'>): DocumentLayerMovePlan;
+/**
+ * Apply as the first/only move batch in the live engine's transaction, using its current snapshot.
+ * Callers must let errors escape that transaction so the engine can roll back the complete move.
+ */
+export declare function applyDocumentLayerMove(transaction: DocumentTransaction, plan: ReadyDocumentLayerMove, currentDocument: DesignDocument): void;

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

@@ -0,0 +1,12 @@
+import type { BindingRuntimeScope } from '../../binding/contracts.js';
+import type { DataProjection } from '../../binding/preview.js';
+import type { DesignDocument, DocumentNode, DocumentResolveOptions } from '../../document/contracts.js';
+export interface ProjectedDocumentNode {
+    sourceNodeId: string;
+    instanceId?: string;
+    rowPath: BindingRuntimeScope['rowPath'];
+    node: DocumentNode;
+    children: ProjectedDocumentNode[];
+}
+/** Fixture rows affect this disposable scene only, never canonical document geometry. */
+export declare function projectDocumentScene(document: DesignDocument, data: DataProjection | null, resolveOptions?: DocumentResolveOptions): ProjectedDocumentNode;

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

@@ -0,0 +1,96 @@
+import type { BindingScopeUse, DataValueType, HostDataCapabilities } from '../../binding/contracts.js';
+import { type DataScopeDescription } from '../../binding/documentCommands.js';
+import type { DesignDocument, DocumentDiagnostic, DocumentEngineOptions, DocumentTransaction } from '../../document/contracts.js';
+import { type DocumentLayerMovePlan, type DocumentLayerMoveRequest, type ReadyDocumentLayerMove } from './layerMoves.js';
+export interface ScopeTransferOptions extends Pick<DocumentEngineOptions, 'preflight'> {
+    /** Host declarations supply scope evidence and compatible fields. Without them a scope escape stays a plain rejection. */
+    capabilities?: HostDataCapabilities;
+}
+/** One declared field the designer may connect instead, resolved from the catalog and the destination position. */
+export interface ScopeTransferChoice {
+    /** `dataFieldChoiceKey(fieldId, scope)`; a decision names exactly this key. */
+    readonly key: string;
+    readonly fieldId: string;
+    readonly fieldLabel: string;
+    readonly valueKind: DataValueType['kind'];
+    readonly scope: BindingScopeUse;
+    readonly scopeLabel: string;
+    readonly templateName?: string;
+}
+export interface ScopeTransferItem {
+    /** A binding leaves its repeated item, or a nested repeat leaves the item that supplies its collection. */
+    readonly kind: 'binding' | 'repeat';
+    readonly id: string;
+    readonly nodeId: string;
+    readonly nodeName: string;
+    readonly slot?: {
+        readonly id: string;
+        readonly label: string;
+    };
+    readonly field: {
+        readonly id: string;
+        readonly label: string;
+        readonly valueKind: DataValueType['kind'];
+        readonly sourceRef: string;
+    };
+    readonly current: DataScopeDescription;
+    readonly destination: DataScopeDescription;
+    readonly choices: readonly ScopeTransferChoice[];
+    /** Written content is the existing text conversion: a text-content slot on an actual text layer. */
+    readonly written: boolean;
+    /** Plain disconnection removes the binding without inventing properties; repeats offer no disconnection. */
+    readonly disconnect: boolean;
+}
+export interface ScopeTransferDecisionPlan {
+    readonly status: 'decision';
+    /** The document this plan was made against; the identity used for staleness and dialog expiry. */
+    readonly document: DesignDocument;
+    /** The structural move, planned without binding policy, that the decisions complete. */
+    readonly move: ReadyDocumentLayerMove;
+    readonly nodeIds: readonly string[];
+    readonly parentId: string;
+    readonly index: number;
+    /** The innermost scope at the destination parent. */
+    readonly destination: DataScopeDescription;
+    readonly items: readonly ScopeTransferItem[];
+}
+export type ScopeTransferPlan = DocumentLayerMovePlan | ScopeTransferDecisionPlan;
+export type ScopeTransferDecision = {
+    readonly id: string;
+    readonly kind: 'retarget';
+    readonly choice: string;
+} | {
+    readonly id: string;
+    readonly kind: 'written';
+    readonly text: string;
+} | {
+    readonly id: string;
+    readonly kind: 'disconnect';
+};
+export type ResolvedScopeTransfer = {
+    readonly status: 'ready';
+    readonly move: ReadyDocumentLayerMove;
+    apply(transaction: DocumentTransaction, currentDocument: DesignDocument): void;
+} | {
+    readonly status: 'blocked';
+    readonly diagnostics: readonly DocumentDiagnostic[];
+};
+/**
+ * Plan a layer move that may carry bound layers out of, into, or between repeated item templates.
+ * A move the live policy accepts, or rejects for any reason other than scope escape, is returned as
+ * the ordinary move plan. A move blocked solely by scope escapes becomes a decision plan: every
+ * escaping binding or nested repeat is listed with its field, current scope, destination scope, and
+ * the compatible fields declared at the destination. Nothing here reads displayed values.
+ */
+export declare function planScopeTransfer(document: DesignDocument, request: DocumentLayerMoveRequest, options?: ScopeTransferOptions): ScopeTransferPlan;
+/**
+ * Apply the move and every binding decision as one batch of the caller's live transaction.
+ * Validation errors escape so the engine rolls back the complete move; there is no partial state.
+ */
+export declare function applyScopeTransfer(transaction: DocumentTransaction, plan: ScopeTransferDecisionPlan, decisions: readonly ScopeTransferDecision[], currentDocument: DesignDocument, options?: ScopeTransferOptions): void;
+/**
+ * Check a complete decision set in a disposable engine under the live policy before anything is committed.
+ * The binding validator runs independently as well, so an invalid decision is rejected even when the
+ * caller's preflight is not the binding preflight.
+ */
+export declare function resolveScopeTransfer(plan: ScopeTransferDecisionPlan, decisions: readonly ScopeTransferDecision[], options?: ScopeTransferOptions): ResolvedScopeTransfer;

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

@@ -0,0 +1,75 @@
+import type { CSSProperties } from 'react';
+import type { DesignDocument, DocumentValue } from '../../document/contracts.js';
+import { type RichText, type RichTextAlign, type RichTextCase, type RichTextCharacterKey, type RichTextCharacterStyle, type RichTextList, type RichTextParagraph, type RichTextParagraphKey, type RichTextParagraphStyle, type RichTextRange, type TextNodeCharacterStyle, type TextResizeMode } from '../../document/richText.js';
+/** Inspector vocabularies. Values are the document values; labels are what the editor shows. */
+export declare const TEXT_FONT_WEIGHT_OPTIONS: readonly {
+    value: number;
+    label: string;
+}[];
+export declare const TEXT_CASE_OPTIONS: readonly {
+    value: RichTextCase;
+    label: string;
+}[];
+export declare const TEXT_LIST_OPTIONS: readonly {
+    value: RichTextList;
+    label: string;
+}[];
+export declare const TEXT_ALIGN_OPTIONS: readonly {
+    value: RichTextAlign;
+    label: string;
+}[];
+export declare const TEXT_RESIZE_OPTIONS: readonly {
+    value: TextResizeMode;
+    label: string;
+}[];
+export declare const TEXT_INDENT_STEP = 24;
+/** True when any binding targets the node; bound text renders projected data and keeps no rich runs. */
+export declare function isBoundTextNode(document: DesignDocument, nodeId: string): boolean;
+/** Inherited character properties only; decorations paint through descendants, so they are emitted per run. */
+export declare function characterStyleCss(style: TextNodeCharacterStyle): CSSProperties;
+/** The effective decoration of a run, or undefined when nothing is decorated. */
+export declare function decorationCss(effective: TextNodeCharacterStyle): string | undefined;
+export declare function paragraphStyleCss(style: RichTextParagraphStyle): CSSProperties;
+/** The component measures; these rules let the surface grow while the document keeps the recorded mode. */
+export declare function textResizeCss(mode: TextResizeMode): CSSProperties;
+export type TextBlock = {
+    kind: 'paragraph';
+    index: number;
+    paragraph: RichTextParagraph;
+} | {
+    kind: 'list';
+    list: 'bullet' | 'numbered';
+    items: readonly {
+        index: number;
+        paragraph: RichTextParagraph;
+    }[];
+};
+/** Consecutive paragraphs sharing an effective list kind render as one real `<ul>`/`<ol>`. */
+export declare function richTextBlocks(model: RichText, base: RichTextParagraphStyle): TextBlock[];
+export interface TextStyleTarget {
+    scope: 'layer' | 'range';
+    range: RichTextRange;
+    /** Connected content: the node never stores runs, so every change is node-level. */
+    plain: boolean;
+}
+/** A non-collapsed selection on written text styles a range; anything else styles the whole layer. */
+export declare function textStyleTarget(plain: boolean, selection: RichTextRange | null, length: number): TextStyleTarget;
+export declare function textEditorModel(properties: Readonly<Record<string, DocumentValue>>, target: TextStyleTarget): RichText;
+export interface TextStyleValues {
+    character: TextNodeCharacterStyle;
+    paragraph: RichTextParagraphStyle;
+    /** Keys whose value differs inside the target, so a control shows "Mixed" instead of one value. */
+    mixed: readonly string[];
+}
+/** What the inspector shows for the target: effective values, with keys that vary reported as mixed. */
+export declare function textStyleValues(properties: Readonly<Record<string, DocumentValue>>, model: RichText, target: TextStyleTarget): TextStyleValues;
+/**
+ * Applies one character key. A range edit writes runs; a layer edit writes the node property and clears the
+ * key from every run so the whole text follows it, matching a whole-layer selection. `undefined` clears.
+ */
+export declare function applyTextCharacterStyle(properties: Readonly<Record<string, DocumentValue>>, model: RichText, target: TextStyleTarget, key: RichTextCharacterKey, value: RichTextCharacterStyle[RichTextCharacterKey] | string | undefined): Record<string, DocumentValue>;
+export declare function applyTextParagraphStyle(properties: Readonly<Record<string, DocumentValue>>, model: RichText, target: TextStyleTarget, key: RichTextParagraphKey, value: RichTextParagraphStyle[RichTextParagraphKey] | undefined): Record<string, DocumentValue>;
+/** The resize mode is a layer property in every scope. */
+export declare function setTextResize(properties: Readonly<Record<string, DocumentValue>>, mode: TextResizeMode): Record<string, DocumentValue>;
+/** Folds the textarea result into the model as one span replacement so untouched runs keep their styles. */
+export declare function commitTextEdit(properties: Readonly<Record<string, DocumentValue>>, model: RichText, target: TextStyleTarget, draft: string): Record<string, DocumentValue>;

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

@@ -0,0 +1,136 @@
+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';
+/**
+ * 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
+ * bounds. Everything the toolbar, the canvas overlay, and the inspector do goes through
+ * these functions, so a gesture can be planned, previewed, and committed as one document
+ * transaction without touching the DOM.
+ */
+export type VectorTool = 'select' | 'pen' | 'marquee';
+export type VectorAnchorAction = 'smooth' | 'corner' | 'delete' | 'split' | 'close' | 'join';
+export type VectorStyle = Pick<VectorProperties, 'fill' | 'fillRule' | 'stroke' | 'corners' | 'mask'>;
+export interface VectorRenderModel {
+    d: string;
+    fill: string | undefined;
+    fillRule: VectorFillRule;
+    stroke: VectorStroke | undefined;
+    mask: boolean;
+}
+export interface VectorEditTarget {
+    readonly node: DocumentNode;
+    readonly layer: LayerGeometry;
+    /** Geometry in the layer box (the stored geometry with its fit onto `width` × `height` applied). */
+    readonly vector: VectorProperties;
+    /** Canvas placement of the layer box, as rendered. */
+    readonly world: DocumentMatrix;
+}
+export interface VectorEditPlan {
+    /** The single selected vector layer when its anchors may be edited on the canvas. */
+    readonly target: VectorEditTarget | null;
+    /** The single selected vector layer, editable or not; style controls apply to it. */
+    readonly styleNode: DocumentNode | null;
+    readonly blocked: readonly DocumentDiagnostic[];
+}
+export interface VectorAnchorActions {
+    readonly smooth: boolean;
+    readonly corner: boolean;
+    readonly delete: boolean;
+    readonly split: boolean;
+    readonly close: boolean;
+    readonly join: {
+        readonly from: number;
+        readonly to: number;
+    } | null;
+}
+export interface VectorAnchorActionResult {
+    readonly vector: VectorProperties;
+    readonly label: string;
+    readonly anchors: readonly VectorAnchorAddress[];
+}
+export type VectorBooleanPlan = {
+    readonly status: 'ready';
+    readonly lower: DocumentNode;
+    readonly upper: DocumentNode;
+    readonly parentId: string;
+    readonly index: number;
+} | {
+    readonly status: 'blocked';
+    readonly diagnostics: readonly DocumentDiagnostic[];
+};
+export interface VectorInsertion {
+    readonly node: DocumentNode;
+    readonly parentId: string;
+}
+export declare const VECTOR_TOOLS: readonly VectorTool[];
+export declare const VECTOR_SHAPE_LABELS: Readonly<Record<VectorShape, string>>;
+export declare const VECTOR_BOOLEAN_LABELS: Readonly<Record<VectorBooleanOperation, string>>;
+export declare const VECTOR_DEFAULT_FILL = "#d9d9d9";
+export declare const VECTOR_DEFAULT_STROKE: VectorStroke;
+export declare const VECTOR_DEFAULT_SIZE = 100;
+/** Screen pixels within which a pen click lands on the first anchor and closes the path. */
+export declare const VECTOR_CLOSE_TOLERANCE = 8;
+/** Screen pixels a pen pointer may travel and still count as a click. */
+export declare const VECTOR_CLICK_TRAVEL = 4;
+export declare const VECTOR_NO_ANCHOR_ACTIONS: VectorAnchorActions;
+export declare const applyVectorMatrix: (matrix: DocumentMatrix, point: VectorPoint) => VectorPoint;
+export declare const vectorAnchorKey: (address: VectorAnchorAddress) => string;
+export declare const sameVectorAnchor: (a: VectorAnchorAddress, b: VectorAnchorAddress) => boolean;
+export declare function parseVectorAnchorKey(key: string): VectorAnchorAddress | null;
+/** Valid stored path data of a layer, detached; null for other layers or invalid data. */
+export declare function vectorNodeGeometry(node: DocumentNode): VectorProperties | null;
+/** The stored geometry with its fit onto the layer box applied; anchors are then in box units. */
+export declare function vectorBoxGeometry(vector: VectorProperties, width: number, height: number): VectorProperties;
+/** What the surface draws for a layer box; `override` is box geometry a gesture is previewing. */
+export declare function vectorRenderModel(node: DocumentNode, width?: number, height?: number, override?: VectorProperties): VectorRenderModel | null;
+/** Stores box geometry back on the layer: the box is refit to the new bounds and the layer keeps its world position. */
+export declare function vectorGeometryPatch(node: DocumentNode, next: VectorProperties): DocumentNodePatch;
+/** 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;
+/** 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. */
+export declare function shapeInsertion(document: DesignDocument, selection: readonly string[], shape: VectorShape, id: string): VectorInsertion;
+/** True when a pen click near the first anchor should close the path. */
+export declare function penClosesOnFirst(points: readonly VectorPoint[], candidate: VectorPoint, tolerance: number): boolean;
+/** A stroked path through the points, given in the parent's space; null when there is nothing to draw. */
+export declare function penPathNode(points: readonly VectorAnchor[], closed: boolean, id: string): DocumentNode | null;
+/**
+ * Which selected layer the canvas overlay may edit. The geometry policy is the one the
+ * 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;
+/** 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;
+/** 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';
+}>, operation: VectorBooleanOperation, id: string): DocumentNode;
+/** Precision of the operands after the same fit and placement used by the boolean command. */
+export declare function vectorBooleanPrecision(plan: Extract<VectorBooleanPlan, {
+    status: 'ready';
+}>): ReturnType<typeof booleanVectorPrecision>;
+/** Replaces both operands with the combined layer at the lower operand's position, inside one transaction. */
+export declare function applyVectorBoolean(transaction: DocumentTransaction, plan: Extract<VectorBooleanPlan, {
+    status: 'ready';
+}>, node: DocumentNode): void;
+/**
+ * CSS `clip-path` values for layers a mask clips: every later sibling of a mask vector,
+ * until the next mask in the same parent, in that sibling's own coordinates. Computed on
+ * the projected scene so layout positions and repeated rows are the rendered ones.
+ */
+export declare function vectorMaskClips(root: ProjectedDocumentNode): Map<ProjectedDocumentNode, string>;
+/** Dragging a pen anchor produces a mirrored pair in the same coordinate space. */
+export declare function penDragAnchor(start: VectorPoint, end: VectorPoint): VectorAnchor;
+/** Inclusive anchor marquee in canvas coordinates; handles alone do not count as anchors. */
+export declare function vectorAnchorsInBox(vector: VectorProperties, world: DocumentMatrix, start: VectorPoint, end: VectorPoint): VectorAnchorAddress[];

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

@@ -0,0 +1,13 @@
+import type { WorkspaceController } from './controller.js';
+import type { WorkspaceTarget } from './contracts.js';
+export interface LegacyWorkspaceModePort {
+    getTarget(): WorkspaceTarget | null;
+    /** Writes compatibility indicators; it must not navigate or mutate a draft. */
+    projectMode(edit: boolean, preview: boolean): void;
+    onPreviewOpenChange?(open: boolean): void;
+}
+/** A one-way projection; controlled host input re-enters through this adapter. */
+export declare function createLegacyModeAdapter(controller: WorkspaceController, port: LegacyWorkspaceModePort): {
+    setPreviewOpen(open: boolean): void;
+    dispose: () => void;
+};