@pygmalionjs/pygmalion 0.8.1 → 0.10.0

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

@@ -0,0 +1,216 @@
+import type { DesignDocument, DocumentDiagnostic, DocumentDuplicateMetadataRemapper, DocumentNode, DocumentNodePatch, DocumentTransaction, DocumentValue } from './contracts.js';
+import { type Paint, type Effect } from './appearance.js';
+import { type LayoutGrid } from '../workspace/edit/canvasGuideModel.js';
+export type { LayoutGrid } from '../workspace/edit/canvasGuideModel.js';
+import { type RichTextCase } from './richText.js';
+/**
+ * Local and shared styles.
+ *
+ * A style is a named, reusable value of one kind (paint, text, effect, grid) stored once in
+ * `document.metadata.styles`. A node references a style by id in `node.properties.styles[slot]`
+ * and always keeps the *projected* value in its ordinary properties (`fill`, `color`, typography
+ * keys, `effects`, `layoutGrids`), so the canvas, the visual compiler, and every other module render
+ * and compile a styled node without knowing about styles at all. Editing a style re-projects it into
+ * every consumer; detaching removes the reference and keeps the projected value, exactly as Figma does.
+ *
+ * Shared styles come from a `StyleLibraryDocument`. An imported style remembers its origin; applying a
+ * newer library revision re-projects changed styles and reports the affected consumers before anything
+ * is written.
+ */
+export type StyleKind = 'paint' | 'text' | 'effect' | 'grid';
+export declare const STYLE_KINDS: readonly StyleKind[];
+/** Where a style can attach on a node. `fill` and `color` are both paint slots (layer fill, text colour). */
+export type StyleSlot = 'fill' | 'color' | 'text' | 'effect' | 'grid';
+export declare const STYLE_SLOTS: readonly StyleSlot[];
+export declare const STYLE_SLOT_KIND: Readonly<Record<StyleSlot, StyleKind>>;
+export declare const STYLE_KIND_LABEL: Readonly<Record<StyleKind, string>>;
+export declare const STYLE_SLOT_LABEL: Readonly<Record<StyleSlot, string>>;
+/** Paint styles reuse the appearance model, including ordered multi-paint stacks. */
+export type StylePaint = Paint;
+export type PaintStyleValue = StylePaint | {
+    paints: StylePaint[];
+};
+/** Node-level typography keys a text style may set. Colour is a paint style, links and lists are content. */
+export interface TextStyleValue {
+    fontFamily?: string;
+    fontWeight?: number;
+    fontSize?: number;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    textCase?: RichTextCase;
+    lineHeight?: number;
+    letterSpacing?: number;
+    indent?: number;
+}
+export declare const TEXT_STYLE_CHARACTER_KEYS: readonly ["fontFamily", "fontWeight", "fontSize", "italic", "underline", "strikethrough", "textCase"];
+export declare const TEXT_STYLE_PARAGRAPH_KEYS: readonly ["lineHeight", "letterSpacing", "indent"];
+export declare const TEXT_STYLE_KEYS: readonly (keyof TextStyleValue)[];
+export type StyleEffect = Effect;
+export interface EffectStyleValue {
+    effects: StyleEffect[];
+}
+export interface GridStyleValue {
+    grids: LayoutGrid[];
+}
+export type StyleValue = PaintStyleValue | TextStyleValue | EffectStyleValue | GridStyleValue;
+export interface StyleValueByKind {
+    paint: PaintStyleValue;
+    text: TextStyleValue;
+    effect: EffectStyleValue;
+    grid: GridStyleValue;
+}
+export interface StyleOrigin {
+    libraryId: string;
+    styleId: string;
+    revision: string;
+}
+export interface DesignStyle {
+    id: string;
+    kind: StyleKind;
+    name: string;
+    value: StyleValue;
+    description?: string;
+    origin?: StyleOrigin;
+}
+export interface StylesMetadata {
+    version: 1;
+    styles: Record<string, DesignStyle>;
+    libraries?: Record<string, {
+        revision: string;
+    }>;
+}
+/** A published set of styles. Ids are stable across revisions; a document imports the ones it uses. */
+export interface StyleLibraryDocument {
+    schemaVersion: 1;
+    id: string;
+    revision: string;
+    styles: Record<string, Omit<DesignStyle, 'origin'>>;
+}
+export type StyleReferences = Partial<Record<StyleSlot, string>>;
+export type StyleConsumer = {
+    kind: 'node';
+    nodeId: string;
+    slot: StyleSlot;
+} | {
+    kind: 'override';
+    instanceId: string;
+    definitionNodeId: string;
+    slot: StyleSlot;
+};
+export type StylePropagation = {
+    kind: 'node';
+    nodeId: string;
+    properties: Record<string, DocumentValue>;
+} | {
+    kind: 'override';
+    instanceId: string;
+    definitionNodeId: string;
+    properties: Record<string, DocumentValue>;
+};
+export interface StyleLibraryChange {
+    styleId: string;
+    name: string;
+    kind: StyleKind;
+    status: 'updated' | 'renamed' | 'removed' | 'unchanged' | 'unavailable';
+    consumers: StyleConsumer[];
+}
+export interface StyleLibraryUpdatePlan {
+    documentFingerprint: string;
+    libraryId: string;
+    revision: string;
+    metadata: StylesMetadata;
+    propagations: StylePropagation[];
+    changes: StyleLibraryChange[];
+}
+export declare class StyleError extends Error {
+    readonly code: string;
+    readonly styleId?: string;
+    readonly nodeId?: string;
+    constructor(code: string, message: string, location?: {
+        styleId?: string;
+        nodeId?: string;
+    });
+}
+export declare function isStylePaint(value: unknown): value is StylePaint;
+export declare function isTextStyleValue(value: unknown): value is TextStyleValue;
+export declare function isStyleEffect(value: unknown): value is StyleEffect;
+export declare function isLayoutGrid(value: unknown): value is LayoutGrid;
+export declare function isStyleValue<K extends StyleKind>(kind: K, value: unknown): value is StyleValueByKind[K];
+export declare function isDesignStyle(value: unknown): value is DesignStyle;
+export declare function isStylesMetadata(value: unknown): value is StylesMetadata;
+export declare function isStyleReferences(value: unknown): value is StyleReferences;
+export declare function validateStyleLibrary(input: unknown): DocumentDiagnostic[];
+export declare const EMPTY_STYLES: StylesMetadata;
+/** The document's styles, or an empty set; an invalid sidecar is refused rather than guessed. */
+export declare function documentStyles(document: DesignDocument): StylesMetadata;
+export declare function documentStyle(document: DesignDocument, styleId: string): DesignStyle;
+export declare function documentStylesOfKind(document: DesignDocument, kind: StyleKind): DesignStyle[];
+export declare function nodeStyleReferences(node: Pick<DocumentNode, 'properties'>): StyleReferences;
+/** Slots that make sense for a layer kind; the panel offers exactly these. */
+export declare function styleSlotsFor(node: Pick<DocumentNode, 'kind'> & Partial<Pick<DocumentNode, 'properties'>>): StyleSlot[];
+/** Validation of the sidecar and every reference; part of the document-level diagnostics a host may run on load. */
+export declare function documentStyleDiagnostics(document: DesignDocument): DocumentDiagnostic[];
+export declare function createStyle(metadata: StylesMetadata, style: DesignStyle): StylesMetadata;
+export declare function renameStyle(metadata: StylesMetadata, styleId: string, name: string): StylesMetadata;
+export declare function describeStyle(metadata: StylesMetadata, styleId: string, description: string | undefined): StylesMetadata;
+export declare function setStyleValue(metadata: StylesMetadata, styleId: string, value: StyleValue): StylesMetadata;
+export declare function removeStyle(metadata: StylesMetadata, styleId: string): StylesMetadata;
+/** Cuts a shared style loose from its library: it stays in the document as a local style. */
+export declare function detachStyleFromLibrary(metadata: StylesMetadata, styleId: string): StylesMetadata;
+/**
+ * Writes a style's value into a node's properties and records the reference. Text styles pass through the
+ * typography normalizer so a key set on the layer is cleared from every run and the plain projection stays exact.
+ */
+export declare function projectStyle(properties: Readonly<Record<string, DocumentValue>>, style: DesignStyle, slot: StyleSlot, kind?: DocumentNode['kind']): Record<string, DocumentValue>;
+/** Removes the reference and keeps the projected value on the layer. */
+export declare function detachStyleReference(properties: Readonly<Record<string, DocumentValue>>, slot: StyleSlot): Record<string, DocumentValue>;
+/** Reads a style value back out of a layer, so a style can be created from the selection. */
+export declare function styleValueFromNode(node: Pick<DocumentNode, 'kind' | 'properties'>, kind: StyleKind, slot?: StyleSlot): StyleValue;
+export declare function styleConsumers(document: DesignDocument, styleId: string): StyleConsumer[];
+/**
+ * Re-projects a style (its current value, or `value` when the caller is about to change it) into every consumer.
+ * With `value === null` the consumers are detached instead: the reference goes, the projected values stay.
+ */
+export declare function propagateStyle(document: DesignDocument, styleId: string, value?: StyleValue | null | undefined): StylePropagation[];
+export declare function applyStylePropagation(tx: DocumentTransaction, propagations: readonly StylePropagation[]): void;
+/** Writes the sidecar; an empty set removes the key so documents without styles carry no metadata. */
+export declare function writeStyles(tx: DocumentTransaction, metadata: StylesMetadata): void;
+export declare function applyStylePatch(document: DesignDocument, nodeId: string, slot: StyleSlot, styleId: string): DocumentNodePatch;
+export declare function detachStylePatch(document: DesignDocument, nodeId: string, slot: StyleSlot): DocumentNodePatch;
+/** Creates a style and, when a layer is given, applies it to that layer in the same transaction. */
+export declare function commitCreateStyle(tx: DocumentTransaction, document: DesignDocument, style: DesignStyle, applyTo?: {
+    nodeId: string;
+    slot: StyleSlot;
+}): void;
+export declare function commitStyleValue(tx: DocumentTransaction, document: DesignDocument, styleId: string, value: StyleValue): void;
+export declare function commitRenameStyle(tx: DocumentTransaction, document: DesignDocument, styleId: string, name: string): void;
+/** Deleting a style detaches its consumers; their projected values stay, as in Figma. */
+export declare function commitRemoveStyle(tx: DocumentTransaction, document: DesignDocument, styleId: string): void;
+export declare function commitApplyStyle(tx: DocumentTransaction, document: DesignDocument, nodeId: string, slot: StyleSlot, styleId: string): void;
+export declare function commitDetachStyle(tx: DocumentTransaction, document: DesignDocument, nodeId: string, slot: StyleSlot): void;
+/** Figma's "update style from selection": the layer's current value becomes the style's value everywhere. */
+export declare function commitStyleFromNode(tx: DocumentTransaction, document: DesignDocument, styleId: string, nodeId: string, slot: StyleSlot): void;
+/** Imports one library style as a shared style; the local id defaults to the library's stable id. */
+export declare function importLibraryStyle(metadata: StylesMetadata, library: StyleLibraryDocument, styleId: string, localId?: string): StylesMetadata;
+/**
+ * The diff of a newer library revision against the document: which imported styles change, which were removed
+ * from the library (they stay as local styles), and which consumers each change reaches. Nothing is written.
+ */
+export declare function planStyleLibraryUpdate(document: DesignDocument, library: StyleLibraryDocument): StyleLibraryUpdatePlan;
+export declare function commitStyleLibraryUpdate(tx: DocumentTransaction, document: DesignDocument, plan: StyleLibraryUpdatePlan): void;
+/**
+ * Styles never reference layers, so duplicating a subtree keeps the sidecar unchanged. Wrap a host remapper
+ * with this so the style sidecar survives duplication next to host-owned sidecars.
+ */
+export declare function stylesDuplicateRemapper(inner?: DocumentDuplicateMetadataRemapper): DocumentDuplicateMetadataRemapper;
+/** The only metadata this module writes; a duplicate guard can treat this key as remap-free. */
+export declare const STYLES_METADATA_KEY = "styles";
+/** Node property keys owned by this module; they are sidecars with no source representation of their own. */
+export declare const STYLE_SIDECAR_PROPERTY_KEYS: readonly string[];
+/**
+ * Source review: a style reference has no representation in code — the projected value is what compiles. These
+ * diagnostics name a changed reference (or a changed style set) so the review controller can explain a blocked
+ * review instead of reporting an unmapped field, mirroring the typography diagnostics.
+ */
+export declare function stylesSourceDiagnostics(after: DesignDocument, before: DesignDocument): DocumentDiagnostic[];

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

@@ -0,0 +1,17 @@
+import type { DocumentMatrix, DocumentNode, DocumentTransaction } from './contracts.js';
+import { type SvgAsset } from './assets.js';
+import { type VectorPath } from './vector.js';
+export declare function svgTransform(text?: string): DocumentMatrix;
+/** SVG path parser. Quadratic and smooth segments become equivalent cubic control points. */
+export declare function parseSvgPath(data: string): VectorPath[];
+export interface SvgImportResult {
+    asset: SvgAsset;
+    rootId: string;
+    nodes: DocumentNode[];
+}
+/** Imports primitives and cubic paths as real editable vector/group nodes. Unsupported constructs reject atomically. */
+export declare function importEditableSvg(markup: string, options: {
+    name?: string;
+    allocateId: (sourceId: string) => string;
+}): SvgImportResult;
+export declare function addImportedSvg(transaction: Pick<DocumentTransaction, 'add'>, result: SvgImportResult, parentId: string): void;

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

@@ -0,0 +1,222 @@
+import type { DocumentMatrix, DocumentValue } from './contracts.js';
+/**
+ * Pure path model for `vector` nodes. The document stores it under
+ * `node.properties.vector` as plain JSON: absolute coordinates in the node's
+ * own space, one entry per sub-path, cubic curves only (`M`/`L`/`C`/`Z`).
+ *
+ * Everything here is deterministic and free of DOM access. Editing operations
+ * return new values and never mutate their input, so a canvas gesture can
+ * preview a result and commit or drop it. Precision limits are documented on
+ * the boolean operations, which flatten curves before clipping.
+ */
+export type VectorFillRule = 'nonzero' | 'evenodd';
+export type VectorBooleanOperation = 'union' | 'subtract' | 'intersect' | 'exclude';
+export type VectorLineCap = 'butt' | 'round' | 'square';
+export type VectorLineJoin = 'miter' | 'round' | 'bevel';
+export type VectorShape = 'rectangle' | 'ellipse' | 'line' | 'polygon' | 'star' | 'arc';
+export interface VectorPoint {
+    x: number;
+    y: number;
+}
+export type VectorCommand = {
+    type: 'M';
+    x: number;
+    y: number;
+} | {
+    type: 'L';
+    x: number;
+    y: number;
+} | {
+    type: 'C';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    type: 'Z';
+};
+export interface VectorPath {
+    closed: boolean;
+    commands: VectorCommand[];
+}
+export interface VectorStroke {
+    width: number;
+    color: string;
+    cap?: VectorLineCap;
+    join?: VectorLineJoin;
+}
+export interface VectorProperties {
+    version: 1;
+    paths: VectorPath[];
+    fillRule?: VectorFillRule;
+    fill?: string;
+    stroke?: VectorStroke;
+    /** Non-destructive corner radius applied to straight corners at render time. */
+    corners?: number;
+    /** A mask clips the siblings rendered above it; its own paint is not shown. */
+    mask?: boolean;
+    /** Records the operation that produced this geometry; informational. */
+    booleanOp?: VectorBooleanOperation;
+}
+export interface VectorBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Editing view of a path: anchors with optional absolute handles. `in` leads into the anchor, `out` leaves it. */
+export interface VectorAnchor {
+    x: number;
+    y: number;
+    in?: VectorPoint;
+    out?: VectorPoint;
+}
+export interface VectorAnchorAddress {
+    path: number;
+    anchor: number;
+}
+export interface VectorSegmentAddress {
+    path: number;
+    segment: number;
+}
+export type VectorAnchorMode = 'corner' | 'smooth';
+export type VectorHandleSide = 'in' | 'out';
+export type VectorRing = VectorPoint[];
+export interface VectorSegment {
+    from: number;
+    to: number;
+    curve: boolean;
+    /** Cubic control polygon; a line repeats its end points. */
+    points: [VectorPoint, VectorPoint, VectorPoint, VectorPoint];
+}
+export declare const VECTOR_SHAPES: readonly VectorShape[];
+export declare const VECTOR_BOOLEAN_OPERATIONS: readonly VectorBooleanOperation[];
+/** Curve flattening tolerance in canvas units for boolean operations and area. */
+export declare const VECTOR_FLATNESS = 0.1;
+/** Vertices closer than this are merged by the polygon clipper. */
+export declare const VECTOR_MERGE_DISTANCE = 0.000001;
+/** Features thinner than twice this distance are not resolved by the polygon clipper. */
+export declare const VECTOR_SIDE_SAMPLE = 0.0001;
+/** Strict structural check of stored path data; unknown keys and non-finite numbers are rejected. */
+export declare function isVectorProperties(value: unknown): value is VectorProperties;
+/** A detached copy of valid stored path data, or null. */
+export declare function parseVector(value: unknown): VectorProperties | null;
+/** Canonical JSON for `node.properties.vector`: known keys only, in a stable order, nothing undefined. */
+export declare function serializeVector(vector: VectorProperties): {
+    [key: string]: DocumentValue;
+};
+/** Anchors of a path; a closed path never repeats its first anchor, the closing segment is implicit. */
+export declare function vectorPathAnchors(path: VectorPath): VectorAnchor[];
+/** Rebuilds commands from anchors; a curved closing segment is written explicitly before `Z`. */
+export declare function vectorPathFromAnchors(anchors: readonly VectorAnchor[], closed: boolean): VectorPath;
+/** Segments of a path in anchor order; the closing segment of a closed path comes last. */
+export declare function vectorPathSegments(path: VectorPath): VectorSegment[];
+/** Exact bounds of the geometry including curve extrema; null without anchors. Strokes and corners are not included. */
+export declare function vectorBounds(vector: VectorProperties): VectorBounds | null;
+/** Applies an affine matrix to every coordinate, control points included. Style keys are kept. */
+export declare function transformVector(vector: VectorProperties, matrix: DocumentMatrix): VectorProperties;
+export declare function translateVector(vector: VectorProperties, dx: number, dy: number): VectorProperties;
+/** Matrix that maps the geometry's bounds onto a node box; a zero-extent axis keeps its scale. */
+export declare function vectorFitTransform(bounds: VectorBounds, width: number, height: number): DocumentMatrix;
+/** Moves the geometry so its bounds start at the origin and reports the node size it needs. */
+export declare function normalizeVectorOrigin(vector: VectorProperties): {
+    vector: VectorProperties;
+    offset: VectorPoint;
+    width: number;
+    height: number;
+};
+/** Node placement after geometry changed: the local offset travels through the node's linear part. */
+export declare function fitVectorNode(vector: VectorProperties, transform: DocumentMatrix): {
+    vector: VectorProperties;
+    transform: DocumentMatrix;
+    width: number;
+    height: number;
+};
+export declare function rectangleVector(width: number, height: number): VectorProperties;
+export declare function ellipseVector(width: number, height: number): VectorProperties;
+/** A straight segment from the node origin to its far corner; a zero height gives a horizontal line. */
+export declare function lineVector(width: number, height: number): VectorProperties;
+/** A regular polygon inscribed in the node box, first vertex at the top. */
+export declare function polygonVector(width: number, height: number, sides?: number): VectorProperties;
+/** A star with alternating outer and inner vertices; the inner ratio is relative to the outer radius. */
+export declare function starVector(width: number, height: number, points?: number, innerRatio?: number): VectorProperties;
+/** Elliptical sector or ring sector, with cubic segments no larger than a quarter turn.
+ * Angles are clockwise degrees in the local y-down coordinate system. Cubics approximate
+ * circular arcs with the same quarter-circle convention as ellipseVector.
+ */
+export declare function arcVector(width: number, height: number, start?: number, sweep?: number, innerRadius?: number): VectorProperties;
+export declare function createShapeVector(shape: VectorShape, width: number, height: number): VectorProperties;
+/**
+ * Replaces each straight corner with a circular arc approximated by one cubic. The tangent
+ * length is clamped to half of each adjacent segment so neighbouring arcs never overlap; two
+ * arcs that meet at the middle of a segment share one anchor (a square with a large radius
+ * becomes a circle, an oblong a pill). Corners between curved segments, path ends, and
+ * collinear anchors are left alone.
+ */
+export declare function roundVectorCorners(vector: VectorProperties, radius: number): VectorProperties;
+/** SVG `d` attribute; corner rounding is applied unless `corners: false`. */
+export declare function vectorPathData(vector: VectorProperties, options?: {
+    corners?: boolean;
+}): string;
+/** Smooth: both handles present and collinear through the anchor in opposite directions. */
+export declare function vectorAnchorMode(anchor: VectorAnchor): VectorAnchorMode;
+export declare function moveVectorAnchor(vector: VectorProperties, address: VectorAnchorAddress, target: VectorPoint): VectorProperties;
+/** Moves one handle; with `mirror`, an existing opposite handle keeps the same length on the opposite side. */
+export declare function moveVectorHandle(vector: VectorProperties, address: VectorAnchorAddress, side: VectorHandleSide, target: VectorPoint, mirror?: boolean): VectorProperties;
+/** Corner drops both handles; smooth mirrors handles along the neighbour tangent, one third of the shorter side. */
+export declare function setVectorAnchorMode(vector: VectorProperties, address: VectorAnchorAddress, mode: VectorAnchorMode): VectorProperties;
+/** Splits a segment at parameter `t`; a cubic keeps its shape exactly (de Casteljau). */
+export declare function insertVectorAnchor(vector: VectorProperties, address: VectorSegmentAddress, t?: number): VectorProperties;
+/** Removes an anchor; neighbours keep their handles. A sub-path with fewer than two anchors is removed. */
+export declare function deleteVectorAnchor(vector: VectorProperties, address: VectorAnchorAddress): VectorProperties;
+/** A closed path can open at any anchor; an open path can split at an interior anchor. */
+export declare function canSplitVectorPath(vector: VectorProperties, address: VectorAnchorAddress): boolean;
+/** Opens a closed path at the anchor (it becomes both ends) or splits an open path into two at the anchor. */
+export declare function splitVectorPath(vector: VectorProperties, address: VectorAnchorAddress): VectorProperties;
+export declare function canJoinVectorPaths(vector: VectorProperties, from: number, to: number): boolean;
+/**
+ * Joins the end of one open path to the start of another with a straight segment (coincident
+ * ends merge into one anchor). Joining a path to itself closes it.
+ */
+export declare function joinVectorPaths(vector: VectorProperties, from: number, to: number): VectorProperties;
+/**
+ * Closest point on any segment; null without segments. Straight segments project exactly,
+ * curves sample 32 steps and then halve the step 24 times around the best sample.
+ */
+export declare function nearestVectorSegmentPoint(vector: VectorProperties, target: VectorPoint): {
+    path: number;
+    segment: number;
+    t: number;
+    point: VectorPoint;
+    distance: number;
+} | null;
+/** Closed sub-paths as polygons (corner rounding applied); open sub-paths are skipped. */
+export declare function flattenVector(vector: VectorProperties, tolerance?: number): {
+    rings: VectorRing[];
+    fillRule: VectorFillRule;
+};
+/** Point containment using the fill rule, on the flattened geometry. */
+export declare function vectorContainsPoint(vector: VectorProperties, target: VectorPoint, tolerance?: number): boolean;
+/** Absolute sum of signed ring areas: exact for boolean results and simple shapes. */
+export declare function vectorArea(vector: VectorProperties, tolerance?: number): number;
+/**
+ * Polygon clipper on flattened rings. Every edge is split at every intersection (including
+ * collinear overlaps), duplicate edges are merged, and each remaining edge is classified by
+ * sampling a point on each side against both inputs with their fill rules. Edges whose sides
+ * disagree about the result form the boundary, oriented with the result on the left, and
+ * are chained into rings by taking the tightest turn at every vertex. Limits: O(n²) in the
+ * number of flattened edges, vertices within `VECTOR_MERGE_DISTANCE` are merged, and slivers
+ * thinner than twice `VECTOR_SIDE_SAMPLE` can be misclassified.
+ */
+export declare function booleanRings(a: readonly VectorRing[], aRule: VectorFillRule, b: readonly VectorRing[], bRule: VectorFillRule, operation: VectorBooleanOperation): VectorRing[];
+/** Only identical paths or strictly separated exact bounds currently preserve curves. */
+export declare function booleanVectorPrecision(a: VectorProperties, b: VectorProperties): 'curve-preserved' | 'polygon-approximation';
+/** Boolean output keeps original cubic commands when equality or separated bounds proves
+ * the set operation. Intersecting or unproven geometry still uses the polygon approximation.
+ * Open sub-paths do not take part. The first operand supplies paint; an empty result has no paths.
+ */
+export declare function booleanVectors(a: VectorProperties, b: VectorProperties, operation: VectorBooleanOperation, tolerance?: number): VectorProperties;
+/** World-space matrix of a node combined with the fit of its stored geometry onto its box. */
+export declare function vectorRenderTransform(vector: VectorProperties, width: number, height: number, world?: DocumentMatrix): DocumentMatrix;

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

@@ -1,5 +1,6 @@
 import { type CodegenFrameOptions, type CodegenNode } from './codegen.js';
 import type { EditorDeclarations } from './declarations.js';
+import type { BindingNodeContext, DataBindingDocument, DataCatalog } from '../binding/contracts.js';
 import { type NodeJSON } from './store.js';
 export declare const DESIGN_IR_SCHEMA: "pygmalion.design-ir";
 export declare const DESIGN_IR_VERSION: 1;
@@ -181,6 +182,12 @@ export interface DesignCodegenAdapter {
     generate(context: DesignCodegenAdapterContext): string | DesignCodegenAdapterOutput;
 }
 export interface DesignCompileOptions {
+    /** Dynamic documents use the structured binding source plan, never literal-prop output. */
+    bindings?: {
+        catalog: DataCatalog;
+        document: DataBindingDocument;
+        nodes: readonly BindingNodeContext[];
+    };
     target?: string;
     purpose?: DesignCompilePurpose;
     force?: boolean;

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

@@ -63,6 +63,8 @@ export interface DesignScreenInteraction {
 }
 /** Timing policy for replaying a screen recipe outside the capture pipeline. */
 export interface DesignScreenInteractionRunOptions {
+    /** Cancels waits and prevents subsequent recipe actions from reaching the document. */
+    signal?: AbortSignal;
     /**
      * Fallback pause after click, focus, hover, fill, check, and press steps.
      * The capture default is 600ms. A step's explicit `settleMs` wins unless
@@ -92,6 +94,8 @@ export interface DesignScreenInteractionRunOptions {
      */
     onAfterInteractions?: () => void | Promise<void>;
 }
+/** The existing recipe runners also operate inside an already mounted artifact. */
+export type DesignScreenDocumentContext = Pick<HTMLIFrameElement, 'contentDocument' | 'contentWindow'>;
 /** A JSON-compatible value that conveys host-specific meaning without Pygmalion interpreting it. */
 export type DesignSerializable = string | number | boolean | null | readonly DesignSerializable[] | {
     readonly [key: string]: DesignSerializable;
@@ -613,6 +617,9 @@ export declare function createDesignScreenCollection({ cases, scenarios, behavio
 }): DesignScreenCollectionResult;
 /** Host basic environment + override for each case. Objects are recursively merged and arrays/primitives are replaced by cases. */
 export declare function mergeScreenPresets(defaults?: DesignScreenPreset, override?: DesignScreenPreset): DesignScreenPreset;
+export declare function runScreenAssertions(iframe: DesignScreenDocumentContext, assertions: readonly DesignScreenAssertion[], options?: {
+    signal?: AbortSignal;
+}): Promise<DesignScreenAssertionReport>;
 export declare function createDesignImportController(manifest: DesignImportManifest, options?: CreateDesignImportOptions): DesignImportController;
 /** The design import controller the host installed for one editor. */
 export declare function createDesignImportRegistry(): {

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

@@ -144,6 +144,14 @@ export interface InspectMedia {
 }
 /** Source edit payload posted through a host-provided write-back endpoint. */
 export interface InspectApplyPayload {
+    /** Optional exact source snapshot required by canonical document output. */
+    sourceProof?: {
+        sourceRevision: string;
+        files: readonly {
+            file: string;
+            sha256: string;
+        }[];
+    };
     /** Final bundle of declarations per (scss file, local class). */
     styles: {
         file: string;

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

@@ -51,7 +51,7 @@ export interface RevisionCatalogPageCommit {
  * previous revision's entry would make adoption and code generation lie about
  * which component the selected checkout contains.
  */
-export declare function bindRevisionComponentRegistry(manifest: Readonly<Record<string, Omit<RegistryEntry, 'component'>>> | undefined, hostRegistry: ComponentRegistry | undefined): ComponentRegistry | undefined;
+export declare function bindRevisionComponentRegistry(manifest: Readonly<Record<string, Omit<RegistryEntry, 'component'>>> | undefined, hostRegistry: ComponentRegistry | undefined, hostLibraryComponents?: readonly string[]): ComponentRegistry | undefined;
 /**
  * Installs a catalog and its page commit as one recoverable boundary.
  *

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

@@ -1,4 +1,4 @@
-import type { DesignScreenInteraction, DesignScreenInteractionRunOptions, DesignScreenInteractionReport } from './designImport.js';
+import type { DesignScreenInteraction, DesignScreenInteractionRunOptions, DesignScreenInteractionReport, DesignScreenDocumentContext } from './designImport.js';
 /**
  * The pause after an action under the `live` settle policy: enough for the
  * application's handlers and one paint, in place of the authored settle a
@@ -7,6 +7,6 @@ import type { DesignScreenInteraction, DesignScreenInteractionRunOptions, Design
 export declare const LIVE_ACTION_SETTLE_MS = 80;
 /** The most a timer-only wait keeps under the `live` settle policy. */
 export declare const LIVE_TIMER_WAIT_CAP_MS = 250;
-export declare function settleScreen(iframe: HTMLIFrameElement, settleMs: number): Promise<void>;
+export declare function settleScreen(iframe: DesignScreenDocumentContext, settleMs: number, signal?: AbortSignal): Promise<void>;
 export declare function elementVisible(element: Element): boolean;
-export declare function runScreenInteractions(iframe: HTMLIFrameElement, interactions: readonly DesignScreenInteraction[], options?: DesignScreenInteractionRunOptions): Promise<DesignScreenInteractionReport>;
+export declare function runScreenInteractions(iframe: DesignScreenDocumentContext, interactions: readonly DesignScreenInteraction[], options?: DesignScreenInteractionRunOptions): Promise<DesignScreenInteractionReport>;

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

@@ -16,7 +16,7 @@ import { type SharedSourceEditScope, type SharedSourceImpact } from './sharedSou
 import { type DesignAssetEditRequest } from './assetEditing.js';
 export type NodeType = 'rows' | 'columns' | 'text' | 'component';
 /** Autolayout container type (with direction, gap, and alignment). */
-export declare const isContainerType: (t: NodeType) => t is "rows" | "columns";
+export declare const isContainerType: (t: NodeType) => t is "columns" | "rows";
 /** Can contain child nodes — container + children:'nodes' components (Card, etc.). */
 export declare const canHaveChildren: (declarations: Pick<EditorDeclarations, "getRegistry">, n: NodeModel) => boolean;
 export type SizeMode = 'fill' | 'fit' | 'fixed';

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

@@ -0,0 +1,44 @@
+import { type CreateDesignImportOptions, type DesignImportController, type DesignImportManifest } from '../editor/designImport.js';
+import { type PygmalionRevisionCatalog } from '../editor/revisionCatalog.js';
+import type { WorkspaceConfiguration } from '../workspace/configuration.js';
+export declare const PYGMALION_HOST_PROJECT_VERSION: 1;
+/** Product declarations only. No editor session or executable mock handlers. */
+export type PygmalionHostStoryboard = Omit<PygmalionRevisionCatalog, 'version' | 'namespace' | 'sourceRevision' | 'screens' | 'tokens' | 'componentRegistry' | 'componentConnections' | 'codegenProject'>;
+export type PygmalionHostDesign = Pick<PygmalionRevisionCatalog, 'componentConnections' | 'codegenProject'>;
+export interface PygmalionHostProjectDefinition {
+    version: typeof PYGMALION_HOST_PROJECT_VERSION;
+    /** Stable project identity, independent of a development server's port. */
+    id: string;
+    inventory: DesignImportManifest;
+    storyboard?: PygmalionHostStoryboard;
+    design?: PygmalionHostDesign;
+    /** Opaque product state is interpreted only by these host executors. */
+    reproduction?: Pick<CreateDesignImportOptions, 'executeScreenPreset' | 'executeDesiredState' | 'stability'>;
+    presentation?: Pick<CreateDesignImportOptions, 'screensCanvasPartition' | 'layerOptions'>;
+    /** Source/document and data adapters used only by the browser workspace. */
+    workspace?: WorkspaceConfiguration;
+}
+export interface PygmalionHostProject {
+    readonly version: typeof PYGMALION_HOST_PROJECT_VERSION;
+    readonly id: string;
+    readonly definition: PygmalionHostProjectDefinition;
+    readonly designImport: DesignImportController;
+    readonly editorProps: PygmalionHostStoryboard & PygmalionHostDesign & {
+        designImport: DesignImportController;
+        workspace?: WorkspaceConfiguration;
+    };
+}
+/** Owns the assembly shared by the browser editor and offline catalog jobs. */
+export declare function createPygmalionHostProject(input: PygmalionHostProjectDefinition): PygmalionHostProject;
+/**
+ * One-way projection from the same host definition, preserving the existing
+ * wire format. Executable adapters and React implementations never cross it.
+ */
+export declare function createPygmalionRevisionCatalog(project: PygmalionHostProject, identity: {
+    sourceRevision: string;
+    namespace?: string;
+}): PygmalionRevisionCatalog;
+/** Project and legacy declarations cannot silently compete for ownership. */
+export declare function resolvePygmalionProjectProps<T extends {
+    project?: PygmalionHostProject;
+}>(props: T): Omit<T, 'project'> & Partial<PygmalionHostProject['editorProps']>;

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

@@ -0,0 +1,11 @@
+import type { DesignComponentConnectionDef } from '../editor/componentConnections.js';
+import type { ComponentRegistry } from '../editor/registry.js';
+export interface DesignRegistryInventoryEntry {
+    name: string;
+    kind: string;
+    source: string;
+}
+/** Portable inference from literal registry props; product vocabularies stay in the host. */
+export declare function createDesignRegistryConnections(inventory: readonly DesignRegistryInventoryEntry[], registry: ComponentRegistry, options?: {
+    missing?: 'error' | 'skip';
+}): DesignComponentConnectionDef[];

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

@@ -0,0 +1,15 @@
+/** Complete text-file changes compiled by a trusted host source adapter. */
+export interface SourceFilePlan {
+    version: 1;
+    sourceRevision: string;
+    /** Null proves that a new source file does not exist yet. */
+    proofs: {
+        file: string;
+        sha256: string | null;
+    }[];
+    changes: {
+        file: string;
+        beforeSha256: string | null;
+        content: string;
+    }[];
+}