@pygmalionjs/pygmalion 0.8.1 → 0.9.0

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

@@ -0,0 +1,37 @@
+import type { BindingDiagnostic, BindingNodeContext, BindingRuntimeScope, BindingValueResult, DataBindingDocument, DataCatalog, DataField, DataFixtureContext, DataPreviewResolver } from './contracts.js';
+export interface ProjectedDataBinding {
+    bindingId: string;
+    nodeId: string;
+    slotId: string;
+    rowPath: BindingRuntimeScope['rowPath'];
+    /** The source result remains distinct from any missing-value presentation. */
+    result: BindingValueResult;
+    presentation: {
+        kind: 'value';
+        value: unknown;
+    } | {
+        kind: 'hidden';
+    } | {
+        kind: 'empty';
+    } | {
+        kind: 'error';
+        message: string;
+    };
+}
+export interface ProjectedDataRow {
+    repeatId: string;
+    templateNodeId: string;
+    rowPath: BindingRuntimeScope['rowPath'];
+}
+export interface DataProjection {
+    values: readonly ProjectedDataBinding[];
+    rows: readonly ProjectedDataRow[];
+    diagnostics: readonly BindingDiagnostic[];
+}
+/** Executable values remain opaque; only the declared field boundary is validated. */
+export declare function readDataField(field: DataField, scope: BindingRuntimeScope, resolver: DataPreviewResolver): BindingValueResult;
+/** Preview is a projection: it never changes a document, its history, or source expressions. */
+export declare function projectDataBindings(catalog: DataCatalog, document: DataBindingDocument, nodes: readonly BindingNodeContext[], fixture: DataFixtureContext, resolver: DataPreviewResolver, options?: {
+    maxRows?: number;
+    maxDepth?: number;
+}): DataProjection;

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

@@ -0,0 +1,109 @@
+import type { BindingDiagnostic, BindingNodeContext, BindingValidationResult, DataBinding, DataBindingDocument, DataCatalog, DataCatalogIdentity, DataField, RepeatBinding } from './contracts.js';
+/** A small expression language issued by a host source adapter, never by sampled data. */
+export type BindingSourceExpression = {
+    kind: 'identifier';
+    name: string;
+} | {
+    kind: 'member';
+    object: BindingSourceExpression;
+    property: string;
+    optional?: boolean;
+} | {
+    kind: 'call';
+    helper: string;
+    arguments: readonly BindingSourceExpression[];
+} | {
+    kind: 'literal';
+    value: string | number | boolean | null;
+} | {
+    kind: 'coalesce';
+    value: BindingSourceExpression;
+    fallback: BindingSourceExpression;
+};
+export interface BindingSourceProof {
+    file: string;
+    sourceRevision: string;
+    /** SHA-256 of the complete original UTF-8 source file. */
+    fileHash: string;
+    start: number;
+    end: number;
+    /** Original expression at this exact range. Not a fixture value. */
+    expected: string;
+}
+export interface BindingSourceResolution {
+    sourceRef: string;
+    expression: BindingSourceExpression;
+    proof: BindingSourceProof;
+    /** Identifiers proven to be in lexical scope by the host source adapter. */
+    identifiers: readonly string[];
+    /** Existing callable symbols explicitly approved by the host. No new hooks or imports are guessed. */
+    helpers: readonly string[];
+    /** A source adapter must explicitly acknowledge the presentation contract it emits. */
+    presentation: {
+        missing: DataBinding['missing'];
+        formatter?: DataBinding['formatter'];
+    };
+}
+export interface RepeatSourceResolution {
+    sourceRef: string;
+    expression: BindingSourceExpression;
+    proof: BindingSourceProof;
+    identifiers: readonly string[];
+    helpers: readonly string[];
+    itemIdentifier: string;
+    keyExpression: BindingSourceExpression;
+}
+export interface BindingSourceAdapter {
+    id: string;
+    version: string;
+    resolveBinding(context: {
+        catalog: DataCatalog;
+        document: DataBindingDocument;
+        binding: DataBinding;
+        field: DataField;
+    }): BindingSourceResolution | {
+        unavailable: string;
+    };
+    resolveRepeat?(context: {
+        catalog: DataCatalog;
+        document: DataBindingDocument;
+        repeat: RepeatBinding;
+        field: DataField;
+    }): RepeatSourceResolution | {
+        unavailable: string;
+    };
+}
+export interface BindingSourcePlan {
+    schema: 'pygmalion.binding-source-plan';
+    version: 1;
+    catalog: DataCatalogIdentity;
+    adapter: {
+        id: string;
+        version: string;
+    };
+    documentFingerprint: string;
+    bindings: readonly {
+        bindingId: string;
+        nodeId: string;
+        slotId: string;
+        resolution: BindingSourceResolution;
+    }[];
+    repeats: readonly {
+        repeatId: string;
+        templateNodeId: string;
+        resolution: RepeatSourceResolution;
+    }[];
+}
+export declare function bindingDocumentFingerprint(document: DataBindingDocument): string;
+export declare function validateBindingSourceExpression(input: unknown, identifiers: readonly string[], helpers: readonly string[], options?: {
+    allowLiteralRoot?: boolean;
+}): boolean;
+export declare function printBindingSourceExpression(expression: BindingSourceExpression): string;
+export declare function validBindingSourceProof(input: unknown, sourceRevision: string): input is BindingSourceProof;
+export declare function validateBindingSourcePlan(input: unknown): BindingValidationResult;
+/** Compile a reviewed-source proposal. This never mutates source and never emits literal-prop operations. */
+export declare function compileBindingSourcePlan(catalog: DataCatalog, document: DataBindingDocument, nodes: readonly BindingNodeContext[], adapter?: BindingSourceAdapter): {
+    status: 'ready' | 'blocked';
+    diagnostics: readonly BindingDiagnostic[];
+    plan?: BindingSourcePlan;
+};

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

@@ -0,0 +1,9 @@
+import type { DocumentEngine } from '../document/contracts.js';
+import type { DataFixtureContext, HostDataCapabilities } from './contracts.js';
+/** Async fixture state stays outside the authoring document and command history. */
+export declare function useDataProjection(engine: DocumentEngine, capabilities: HostDataCapabilities, screenId: string, fixtureId: string | undefined): {
+    projection: import("./preview.js").DataProjection | null;
+    fixture: DataFixtureContext | undefined;
+    error: string | undefined;
+    status: "unavailable" | "ready" | "loading" | "error";
+};

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

@@ -0,0 +1,8 @@
+import type { BindingDiagnostic, BindingNodeContext, BindingScopeUse, BindingValidationResult, DataBindingDocument, DataCatalog } from './contracts.js';
+export declare function isBindingScopeUse(value: unknown): value is BindingScopeUse;
+export declare function isDataBindingDocument(input: unknown): input is DataBindingDocument;
+/** Resolve lexical scope from declarations, never from displayed values or object paths. */
+export declare function bindingScopeId(catalog: DataCatalog, document: DataBindingDocument, use: BindingScopeUse): string | undefined;
+export declare function validateDataBindings(catalog: DataCatalog, input: unknown, nodeList: readonly BindingNodeContext[]): BindingValidationResult;
+/** Contribute only newly introduced errors; the document engine owns rollback and undo. */
+export declare function preflightBindingReparent(catalog: DataCatalog, document: DataBindingDocument, beforeNodes: readonly BindingNodeContext[], afterNodes: readonly BindingNodeContext[]): readonly BindingDiagnostic[];

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

@@ -7,6 +7,8 @@ import { InspectSession } from '../editor/inspect.js';
 import { HostBindings, type HostBindingsInit } from './hostBindings.js';
 import { type EditorRuntimeDebug } from './debug.js';
 import type { EditorTransport } from '../contract/transport.js';
+import { WorkspaceController } from '../workspace/controller.js';
+import { WorkspaceDocumentSessions } from '../workspace/documentSessions.js';
 export interface EditorRuntimeOptions {
     /** Initial host values; every one can also be set later through `runtime.host`. */
     host?: HostBindingsInit;
@@ -18,6 +20,10 @@ export interface EditorRuntimeOptions {
     transport?: EditorTransport;
 }
 export interface EditorRuntime {
+    /** Independent navigation contexts for the three workspace modes. */
+    readonly workspace: WorkspaceController;
+    /** Canonical draft engines survive workspace navigation, scoped by source identity. */
+    readonly documents: WorkspaceDocumentSessions;
     readonly store: EditorStore;
     readonly host: HostBindings;
     readonly transport: EditorTransport;

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

@@ -0,0 +1,112 @@
+import type { CSSProperties } from 'react';
+import type { DesignDocument, DocumentDiagnostic, DocumentNode, DocumentNodeKind, DocumentValue } from './contracts.js';
+export declare const BLEND_MODES: readonly ["normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity"];
+export type BlendMode = typeof BLEND_MODES[number];
+interface PaintCommon {
+    opacity?: number;
+    visible?: boolean;
+    blendMode?: BlendMode;
+}
+export interface SolidPaint extends PaintCommon {
+    type: 'solid';
+    color: string;
+}
+export interface GradientStop {
+    position: number;
+    color: string;
+    opacity?: number;
+}
+export interface GradientPaint extends PaintCommon {
+    type: 'linear' | 'radial' | 'angular';
+    stops: GradientStop[];
+    angle?: number;
+    center?: {
+        x: number;
+        y: number;
+    };
+    radius?: number;
+}
+export interface ImagePaint extends PaintCommon {
+    type: 'image';
+    assetId: string;
+    scaleMode: 'fill' | 'fit' | 'crop' | 'tile';
+    scale?: number;
+}
+export type Paint = SolidPaint | GradientPaint | ImagePaint;
+export interface Stroke {
+    color: string;
+    weight: number;
+    align?: 'inside' | 'center' | 'outside';
+    dashes?: number[];
+    cap?: 'butt' | 'round' | 'square';
+    join?: 'miter' | 'round' | 'bevel';
+    sides?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    opacity?: number;
+    visible?: boolean;
+}
+export interface ShadowEffect {
+    type: 'drop-shadow' | 'inner-shadow';
+    x: number;
+    y: number;
+    blur: number;
+    spread?: number;
+    color: string;
+    visible?: boolean;
+}
+export interface BlurEffect {
+    type: 'layer-blur' | 'background-blur';
+    radius: number;
+    visible?: boolean;
+}
+export type Effect = ShadowEffect | BlurEffect;
+/** Paints and strokes use bottom-to-top order in this document format. */
+export interface Appearance {
+    paints: Paint[];
+    strokes: Stroke[];
+    effects: Effect[];
+    opacity?: number;
+    blendMode?: BlendMode | 'pass-through';
+}
+export declare const APPEARANCE_KEYS: readonly ["paints", "strokes", "effects", "blendMode", "opacity"];
+export declare const isAppearanceColor: (v: unknown) => v is string;
+export declare function isPaint(v: unknown): v is Paint;
+export declare function isStroke(v: unknown): v is Stroke;
+export declare function isEffect(v: unknown): v is Effect;
+export declare function normalizePaint(paint: Paint): Paint;
+export declare function normalizeAppearance(value: Appearance): Appearance;
+export declare function nodeAppearance(node: Pick<DocumentNode, 'kind' | 'properties'>): Appearance;
+/** Replaces only appearance keys; one ordinary solid retains the legacy source mapping. */
+export declare function appearanceProperties(properties: Record<string, DocumentValue>, appearance: Appearance, kind?: DocumentNodeKind): Record<string, DocumentValue>;
+export declare function appearanceDiagnostics(node: DocumentNode): DocumentDiagnostic[];
+export declare const colorWithOpacity: (color: string, opacity?: number) => string;
+export declare function paintToCss(paint: Paint, document?: Pick<DesignDocument, 'metadata'>): CSSProperties;
+export declare function strokeToCss(stroke: Stroke): CSSProperties;
+/** Layer effects. Paints use separate surfaces so image opacity does not fade the node's children. */
+export declare function appearanceToCss(node: DocumentNode, options?: {
+    document?: Pick<DesignDocument, 'metadata'>;
+}): CSSProperties;
+export declare const escapeSvg: (value: string | number) => string;
+/** CSS gradient endpoints in pixel space, including non-square boxes. */
+export declare function linearGradientLine(width: number, height: number, angle?: number): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+export interface SvgAppearance {
+    defs: string;
+    fills: Record<string, string | number>[];
+    strokes: Record<string, string | number>[];
+    diagnostics: DocumentDiagnostic[];
+}
+/** SVG presentation attributes and safe definitions. Angular gradients have no native SVG paint server. */
+export declare function appearanceToSvg(node: DocumentNode, options?: {
+    document?: Pick<DesignDocument, 'metadata'>;
+    idPrefix?: string;
+}): SvgAppearance;
+export {};

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

@@ -0,0 +1,204 @@
+import type { DesignDocument, DocumentDiagnostic, DocumentDuplicateMetadataRemapper, DocumentNode, DocumentTransaction, DocumentValue } from './contracts.js';
+/**
+ * Asset store of a design document. Images and SVG sources live under
+ * `document.metadata.assets` as plain JSON so a saved document is
+ * self-contained; nodes reference them by id through an image paint
+ * (`{ type: 'image', assetId, scaleMode }` inside `properties.paints`) or,
+ * for editable SVG imports, through `properties.sourceAssetId` on the
+ * imported root.
+ *
+ * Ids are content-addressed (`asset:` + the first 24 hex digits of the
+ * SHA-256 of the bytes), so importing the same file twice stores it once and
+ * pasting between documents merges by id without renaming references. All
+ * functions here are pure and free of DOM access; hashing and dimension
+ * probing work on bytes.
+ */
+export declare const ASSETS_METADATA_KEY = "assets";
+export declare const ASSET_STORE_VERSION = 1;
+export declare const IMAGE_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+export declare const IMAGE_SCALE_MODES: readonly ["fill", "fit", "crop", "tile"];
+export declare const IMAGE_SCALE_MODE_LABELS: Readonly<Record<ImageScaleMode, string>>;
+/** Placement default: an image larger than this is scaled down to fit when placed as a layer. */
+export declare const IMAGE_PLACEMENT_MAX = 800;
+export type ImageMediaType = (typeof IMAGE_MEDIA_TYPES)[number];
+export type ImageScaleMode = (typeof IMAGE_SCALE_MODES)[number];
+export type ImageAssetSource = {
+    type: 'data';
+    base64: string;
+} | {
+    type: 'reference';
+    url: string;
+};
+export interface ImageAsset {
+    kind: 'image';
+    id: string;
+    name: string;
+    mediaType: ImageMediaType;
+    width: number;
+    height: number;
+    /** SHA-256 of the encoded bytes, lowercase hex. Reference sources carry the hash the host supplied. */
+    contentHash: string;
+    byteLength?: number;
+    source: ImageAssetSource;
+}
+export interface SvgAsset {
+    kind: 'svg';
+    id: string;
+    name: string;
+    markup: string;
+    width: number;
+    height: number;
+    contentHash: string;
+}
+export type DocumentAsset = ImageAsset | SvgAsset;
+export interface AssetStore {
+    version: 1;
+    items: Record<string, DocumentAsset>;
+}
+export interface ImagePaint {
+    type: 'image';
+    assetId: string;
+    scaleMode: ImageScaleMode;
+    opacity?: number;
+    visible?: boolean;
+    blendMode?: string;
+    scale?: number;
+}
+export interface ImageAssetInput {
+    name: string;
+    /** Encoded bytes, a base64 string, or a `data:` URL. */
+    data?: Uint8Array | string;
+    /** A host-served location; requires `mediaType`, `width`, `height`, and `contentHash`. */
+    url?: string;
+    mediaType?: ImageMediaType;
+    width?: number;
+    height?: number;
+    contentHash?: string;
+}
+export interface SvgAssetInput {
+    name: string;
+    markup: string;
+    width?: number;
+    height?: number;
+}
+export interface AssetFileLike {
+    name: string;
+    type?: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export type InventoryAssetMedia = {
+    kind: 'svg';
+    markup: string;
+} | {
+    kind: 'image';
+    mediaType?: ImageMediaType;
+    width?: number;
+    height?: number;
+    data?: string;
+    url?: string;
+    contentHash?: string;
+};
+export interface InventoryAssetEntry {
+    id: string;
+    name: string;
+    media?: InventoryAssetMedia;
+}
+/** SHA-256 of bytes as lowercase hex; synchronous so the document engine can stay synchronous. */
+export declare function sha256Hex(bytes: Uint8Array): string;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decodes standard or URL-safe base64, with or without padding; null on any other character. */
+export declare function base64ToBytes(text: string): Uint8Array | null;
+/** Media type from the byte signature; null for anything that is not PNG, JPEG, GIF, or WebP. */
+export declare function sniffImageMediaType(bytes: Uint8Array): ImageMediaType | null;
+/** Pixel dimensions from the header of a PNG, JPEG, GIF, or WebP; null when the header is incomplete. */
+export declare function readImageDimensions(bytes: Uint8Array): {
+    width: number;
+    height: number;
+    mediaType: ImageMediaType;
+} | null;
+/** Width and height an SVG declares on its root: `width`/`height` in px, otherwise the `viewBox` size. */
+export declare function svgIntrinsicSize(markup: string): {
+    width: number;
+    height: number;
+} | null;
+export declare const assetIdFor: (contentHash: string) => string;
+export declare const safeAssetUrl: (url: string) => boolean;
+export declare const safeSvgMarkup: (markup: string) => boolean;
+export declare function isDocumentAsset(value: unknown): value is DocumentAsset;
+export declare function isAssetStore(value: unknown): value is AssetStore;
+export declare function isImagePaint(value: unknown): value is ImagePaint;
+export declare const emptyAssetStore: () => AssetStore;
+/** Detached asset store of a document; absent metadata is an empty store. Invalid metadata is reported by `assetStoreDiagnostics`. */
+export declare function documentAssets(document: Pick<DesignDocument, 'metadata'>): AssetStore;
+/** Verifies payload bytes independently of the structural asset schema. */
+export declare function assetIntegrityProblem(asset: DocumentAsset): string | null;
+export declare function assetStoreDiagnostics(document: Pick<DesignDocument, 'metadata'>): DocumentDiagnostic[];
+/** Canonical JSON for `metadata.assets`: known keys in a stable order; undefined when the store is empty. */
+export declare function serializeAssetStore(store: AssetStore): {
+    [key: string]: DocumentValue;
+} | undefined;
+/** The asset a node or paint refers to, or null. Provided for the appearance owner's image paints. */
+export declare function resolveAsset(document: Pick<DesignDocument, 'metadata'>, assetId: string): DocumentAsset | null;
+export declare function createImageAsset(input: ImageAssetInput): ImageAsset;
+export declare function createSvgAsset(input: SvgAssetInput): SvgAsset;
+/** Adds an asset; an identical asset (same id and hash) is a no-op that keeps the existing entry. */
+export declare function addAsset(store: AssetStore, asset: DocumentAsset): AssetStore;
+export declare function removeAsset(store: AssetStore, assetId: string): AssetStore;
+export declare function renameAsset(store: AssetStore, assetId: string, name: string): AssetStore;
+/** Merges every asset of `source` into `target`; a same-id entry with different content is refused. */
+export declare function mergeAssetStores(target: AssetStore, source: AssetStore): AssetStore;
+/** Writes the store to `metadata.assets`; an empty store removes the key so plain documents keep empty metadata. */
+export declare function writeDocumentAssets(transaction: Pick<DocumentTransaction, 'setMetadata'>, store: AssetStore): void;
+export declare function addDocumentAsset(transaction: Pick<DocumentTransaction, 'setMetadata'>, document: Pick<DesignDocument, 'metadata'>, asset: DocumentAsset): void;
+/** Every image paint of a node's own properties, in paint order. */
+export declare function nodeImagePaints(node: Pick<DocumentNode, 'properties'>): ImagePaint[];
+/** Asset ids a node refers to directly: image paints (own and override properties) and an SVG import source. */
+export declare function nodeAssetIds(node: DocumentNode): string[];
+/** Nodes per referenced asset id, including ids that are missing from the store. */
+export declare function assetReferences(document: Pick<DesignDocument, 'nodes'>): Record<string, string[]>;
+export declare function unusedAssetIds(document: Pick<DesignDocument, 'nodes' | 'metadata'>): string[];
+export declare function pruneUnusedAssets(document: Pick<DesignDocument, 'nodes' | 'metadata'>): AssetStore;
+/** Referenced asset ids that the store does not contain. */
+export declare function missingAssetIds(document: Pick<DesignDocument, 'nodes' | 'metadata'>): string[];
+/** Duplicating layers shares assets (ids are content-addressed), so the sidecar passes through unchanged. */
+export declare const assetsDuplicateMetadata: DocumentDuplicateMetadataRemapper;
+/** A URL usable by `<img src>` or `background-image`: a data URL for stored bytes, the location for references. */
+export declare function assetSourceUrl(asset: DocumentAsset): string;
+export declare const imagePaint: (assetId: string, scaleMode?: ImageScaleMode) => ImagePaint;
+/**
+ * CSS for one image paint as a background, keyed like React `CSSProperties`. `fill` covers the box,
+ * `fit` letterboxes, `crop` covers (the crop transform is not modelled), `tile` repeats at natural size.
+ * A missing asset yields an empty object so the layer keeps its other paints.
+ */
+export declare function imagePaintCss(source: Pick<DesignDocument, 'metadata'> | AssetStore, paint: ImagePaint): Record<string, string>;
+/** Background CSS of a node's first image paint; the appearance owner layers this under its own projection. */
+export declare function nodeImageCss(document: Pick<DesignDocument, 'metadata'>, node: Pick<DocumentNode, 'properties'>): Record<string, string>;
+/** Size for a newly placed image: natural size, scaled down uniformly to fit the limit. */
+export declare function imagePlacementSize(asset: Pick<DocumentAsset, 'width' | 'height'>, limit?: number): {
+    width: number;
+    height: number;
+};
+/** A frame whose only paint is the image; this is the "image layer" of the editor. */
+export declare function imageNode(input: {
+    id: string;
+    asset: DocumentAsset;
+    name?: string;
+    scaleMode?: ImageScaleMode;
+    x?: number;
+    y?: number;
+    limit?: number;
+}): DocumentNode;
+export declare function isImageNode(node: DocumentNode): boolean;
+/** Reads dropped or chosen files into assets; failures become diagnostics that name the file. */
+export declare function importAssetFiles(files: Iterable<AssetFileLike>): Promise<{
+    assets: DocumentAsset[];
+    diagnostics: DocumentDiagnostic[];
+}>;
+/** Builds a store from a host inventory whose entries carry media; entries without media are skipped. */
+export declare function assetsFromInventory(entries: Iterable<InventoryAssetEntry>): {
+    store: AssetStore;
+    assetIds: Record<string, string>;
+    diagnostics: DocumentDiagnostic[];
+};
+/** Custom source compilers must acknowledge asset and export sidecars rather than silently dropping them. */
+export declare function assetInteropSourceDeltaDiagnostics(before: DesignDocument, after: DesignDocument): DocumentDiagnostic[];