@pygmalionjs/pygmalion 0.8.0 → 0.9.0

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

@@ -0,0 +1,50 @@
+import type { InspectApplyPayload } from '../editor/inspect.js';
+import type { InspectApplyResult, InspectPreviewResult } from '../editor/host.js';
+export type SourceWriteErrorCode = 'invalid-path' | 'empty-change' | 'excluded-source' | 'empty-diff' | 'unexpected-file' | 'missing-file' | 'review-required' | 'stale-preview' | 'busy' | 'not-applied';
+export declare class SourceWriteError extends Error {
+    readonly code: SourceWriteErrorCode;
+    readonly path?: string;
+    constructor(code: SourceWriteErrorCode, message: string, path?: string);
+}
+export interface SourceWritePolicy {
+    /** Repository-owned recovery outputs that must never count as source changes. */
+    excludedSourcePrefixes?: readonly string[];
+    requireBranch?: boolean;
+    /** Optional workspace identity; a change invalidates a reviewed payload. */
+    scope?: () => string;
+}
+export interface InspectSourceRuntime {
+    previewVisual(payload: InspectApplyPayload): Promise<InspectPreviewResult>;
+    applyVisual(payload: InspectApplyPayload): Promise<InspectApplyResult>;
+}
+/** Payloads must be JSON-serializable. Each runtime call receives an independent snapshot. */
+export interface ReviewedSourceOperationRuntime<TPayload> {
+    preview(payload: TPayload): Promise<InspectPreviewResult>;
+    apply(payload: TPayload): Promise<InspectApplyResult>;
+}
+export interface ReviewedSourceOperationFiles {
+    /** Existing inputs whose paths must satisfy the source policy, including read-only dependencies. */
+    proofFiles: readonly string[];
+    /** The only files this operation may change, including newly created files. */
+    changedFiles: readonly string[];
+}
+export interface ReviewedSourceOperationPolicy<TPayload> extends SourceWritePolicy {
+    /** A synchronous, side-effect-free declaration for the captured payload. */
+    files(payload: TPayload): ReviewedSourceOperationFiles;
+    /** Additional payload validation, run before preview and apply. */
+    validate?(payload: TPayload): void;
+    /** Require each changed file exactly once in both diffs and affectedFiles. Defaults to false. */
+    requireCompletePreview?: boolean;
+}
+export declare function inspectPayloadSourceFiles(payload: InspectApplyPayload): string[];
+export declare function assertInspectSourcePayload(payload: InspectApplyPayload, policy?: SourceWritePolicy): void;
+/** Review tickets are single-use and survive neither a new preview nor a workspace change. */
+export declare function createReviewedSourceOperation<TPayload>(runtime: ReviewedSourceOperationRuntime<TPayload>, policy: ReviewedSourceOperationPolicy<TPayload>): {
+    preview: (payload: TPayload) => Promise<InspectPreviewResult>;
+    apply: (payload: TPayload) => Promise<InspectApplyResult>;
+};
+/** Compatibility adapter for visual Inspect payloads; unchanged files may be omitted from a preview. */
+export declare function createReviewedSourceWriter(runtime: InspectSourceRuntime, policy?: SourceWritePolicy): {
+    preview: (payload: InspectApplyPayload) => Promise<InspectPreviewResult>;
+    apply: (payload: InspectApplyPayload) => Promise<InspectApplyResult>;
+};

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

@@ -1,3 +1,72 @@
+export * from './document/components.js';
+export * from './token-library/bindings.js';
+export { STYLE_KINDS, STYLE_SLOTS, STYLE_SLOT_KIND, STYLE_KIND_LABEL, STYLE_SLOT_LABEL, TEXT_STYLE_CHARACTER_KEYS, TEXT_STYLE_PARAGRAPH_KEYS, TEXT_STYLE_KEYS, StyleError, isStylePaint, isTextStyleValue, isStyleEffect, isStyleValue, isDesignStyle, isStylesMetadata, isStyleReferences, validateStyleLibrary, EMPTY_STYLES, documentStyles, documentStyle, documentStylesOfKind, nodeStyleReferences, styleSlotsFor, documentStyleDiagnostics, createStyle, renameStyle, describeStyle, setStyleValue, removeStyle, detachStyleFromLibrary, projectStyle, detachStyleReference, styleValueFromNode, styleConsumers, propagateStyle, applyStylePropagation, writeStyles, applyStylePatch, detachStylePatch, commitCreateStyle, commitStyleValue, commitRenameStyle, commitRemoveStyle, commitApplyStyle, commitDetachStyle, commitStyleFromNode, importLibraryStyle, planStyleLibraryUpdate, commitStyleLibraryUpdate, stylesDuplicateRemapper, STYLES_METADATA_KEY, STYLE_SIDECAR_PROPERTY_KEYS, stylesSourceDiagnostics } from './document/styles.js';
+export type { StyleKind, StyleSlot, StylePaint, PaintStyleValue, TextStyleValue, StyleEffect, EffectStyleValue, GridStyleValue, StyleValue, StyleValueByKind, StyleOrigin, DesignStyle, StylesMetadata, StyleLibraryDocument, StyleReferences, StyleConsumer, StylePropagation, StyleLibraryChange, StyleLibraryUpdatePlan } from './document/styles.js';
+export { componentOverrideTarget, remapComponentOverrideAddress } from './document/engine.js';
+export { ComponentPanel } from './workspace/edit/ComponentPanel.js';
+export type { ComponentPanelProps } from './workspace/edit/ComponentPanel.js';
+export { StylesPanel } from './workspace/edit/StylesPanel.js';
+export type { StylesPanelProps } from './workspace/edit/StylesPanel.js';
+export { TokenLibraryProvider, useTokenLibraryController, useHasTokenLibraryProvider } from './workspace/tokens/TokenLibraryContext.js';
+export { createTokenLibraryEngine, reopenTokenLibrary, validateTokenLibraryDocument, resolveTokenLibraryValue, tokenValueEditability, TokenLibraryValidationError } from './token-library/engine.js';
+export type * from './token-library/contracts.js';
+export type * from './workspace/tokens/contracts.js';
+export { WorkspaceTokenLibraryController } from './workspace/tokens/controller.js';
+export type { WorkspaceTokenLibraryState } from './workspace/tokens/controller.js';
+export { createReviewedSourceOperation } from './host/sourceWriteback.js';
+export type { ReviewedSourceOperationRuntime, ReviewedSourceOperationPolicy, ReviewedSourceOperationFiles } from './host/sourceWriteback.js';
+export type { SourceFilePlan } from './host/sourceFilePlan.js';
+export type { WorkspaceDraftPreviewClient } from './workspace/source/draftPreviewClient.js';
+import { type PygmalionHostProject } from './host/project.js';
+export { createPygmalionHostProject, createPygmalionRevisionCatalog, PYGMALION_HOST_PROJECT_VERSION, } from './host/project.js';
+export type { PygmalionHostProject, PygmalionHostProjectDefinition, PygmalionHostStoryboard, PygmalionHostDesign, } from './host/project.js';
+export { createDesignRegistryConnections } from './host/registryConnections.js';
+export type { DesignRegistryInventoryEntry } from './host/registryConnections.js';
+export { createReviewedSourceWriter, assertInspectSourcePayload, inspectPayloadSourceFiles, SourceWriteError, } from './host/sourceWriteback.js';
+export type { InspectSourceRuntime, SourceWritePolicy, SourceWriteErrorCode } from './host/sourceWriteback.js';
+export { WorkspaceController } from './workspace/controller.js';
+export { createLegacyModeAdapter } from './workspace/legacyModeAdapter.js';
+export type * from './workspace/contracts.js';
+export { resolveWorkspaceTarget } from './workspace/configuration.js';
+export type { WorkspaceConfiguration, WorkspaceTargetConfiguration } from './workspace/configuration.js';
+export { compileWorkspaceVisualSource, workspaceSourceFingerprint } from './workspace/source/compiler.js';
+export { compileWorkspaceDocumentSource, jsxStructureWrapperClassName } from './workspace/source/structure.js';
+export { compileWorkspaceResponsiveSource, resolveResponsiveLayout, setResponsiveLayoutOverride } from './workspace/source/responsive.js';
+export { describeResponsiveValueContract, responsiveRangePreviewWidth, sortResponsiveRanges } from './workspace/source/responsive.js';
+export { useWorkspaceResponsiveViewport } from './workspace/source/ResponsiveLayoutPanel.js';
+export type * from './workspace/source/responsiveContracts.js';
+export type { WorkspaceDocumentSourceChanges } from './workspace/source/structure.js';
+export { WorkspaceSourceReviewController } from './workspace/source/controller.js';
+export { createWorkspaceDraftPreviewClient } from './workspace/source/draftPreviewClient.js';
+export { runWorkspaceDraftRecipe, WorkspaceDraftRecipeError } from './workspace/source/draftRecipe.js';
+export type { WorkspaceDraftDocumentContext, WorkspaceDraftRecipe, WorkspaceDraftRecipeOptions, WorkspaceDraftRecipeReport } from './workspace/source/draftRecipe.js';
+export type * from './workspace/source/contracts.js';
+export type * from './workspace/source/flowContracts.js';
+export type { WorkspaceSourceReviewState } from './workspace/source/controller.js';
+export * from './binding/index.js';
+export { planScopeTransfer, resolveScopeTransfer, applyScopeTransfer } from './workspace/edit/scopeTransfer.js';
+export type { ScopeTransferPlan, ScopeTransferDecisionPlan, ScopeTransferItem, ScopeTransferChoice, ScopeTransferDecision, ScopeTransferOptions, ResolvedScopeTransfer } from './workspace/edit/scopeTransfer.js';
+export { planDocumentLayerMove, applyDocumentLayerMove, normalizeDocumentLayerSelection } from './workspace/edit/layerMoves.js';
+export type { DocumentLayerMoveRequest, DocumentLayerMovePlan, DocumentLayerMoveOperation, ReadyDocumentLayerMove } from './workspace/edit/layerMoves.js';
+export { TEXT_CHARACTER_KEYS, TEXT_PARAGRAPH_KEYS, TEXT_RESIZE_MODES, RICH_TEXT_CASES, RICH_TEXT_LISTS, RICH_TEXT_ALIGNMENTS, TEXT_PARAGRAPH_PROPERTY, TEXT_NODE_PROPERTY_KEYS, isTextLink, isTextResizeMode, isRichTextCharacterValue, isRichTextParagraphValue, isRichTextCharacterStyle, isRichTextParagraphStyle, isRichTextRun, isRichTextParagraph, isRichText, richTextPlain, richTextLength, richTextFromPlain, normalizeRichText, applyRichTextCharacterStyle, clearRichTextCharacterStyle, setRichTextParagraphStyle, clearRichTextParagraphStyle, richTextInheritedStyle, insertRichText, deleteRichText, replaceRichText, splitRichTextParagraph, mergeRichTextParagraphs, applyPlainTextEdit, richTextCharacterStyleAt, richTextParagraphStyleAt, richTextVaryingKeys, textNodeStyle, textResizeMode, textNodePlain, textNodeModel, isRichTextTrivial, hoistRichTextStyle, richTextValue, normalizeTextProperties, plainTextProperties, textFontRequirements, documentFontRequirements, textNodeFontRequirements, loadTextFonts, loadDocumentFonts, fontFaceSetLoader, } from './document/richText.js';
+export type * from './document/richText.js';
+export { VECTOR_SHAPES, VECTOR_BOOLEAN_OPERATIONS, VECTOR_FLATNESS, VECTOR_MERGE_DISTANCE, VECTOR_SIDE_SAMPLE, isVectorProperties, parseVector, serializeVector, vectorPathAnchors, vectorPathFromAnchors, vectorPathSegments, vectorBounds, transformVector, translateVector, vectorFitTransform, normalizeVectorOrigin, fitVectorNode, rectangleVector, ellipseVector, arcVector, lineVector, polygonVector, starVector, createShapeVector, roundVectorCorners, vectorPathData, vectorAnchorMode, moveVectorAnchor, moveVectorHandle, setVectorAnchorMode, insertVectorAnchor, deleteVectorAnchor, canSplitVectorPath, splitVectorPath, canJoinVectorPaths, joinVectorPaths, nearestVectorSegmentPoint, flattenVector, vectorContainsPoint, vectorArea, booleanRings, booleanVectors, booleanVectorPrecision, vectorRenderTransform, } from './document/vector.js';
+export type * from './document/vector.js';
+export { VectorEditor, VectorInspector, VectorNodeSurface, useVectorEditing } from './workspace/edit/VectorEditor.js';
+export type { VectorEditing, VectorEditingInput, VectorEditingSession, VectorEditorProps, VectorGeometryPreview } from './workspace/edit/VectorEditor.js';
+export { VectorToolbar } from './workspace/edit/VectorToolbar.js';
+export { VECTOR_TOOLS, VECTOR_SHAPE_LABELS, VECTOR_BOOLEAN_LABELS, VECTOR_DEFAULT_FILL, VECTOR_DEFAULT_STROKE, VECTOR_NO_ANCHOR_ACTIONS, vectorNodeGeometry, vectorBoxGeometry, vectorRenderModel, vectorGeometryPatch, vectorStylePatch, renderedWorldTransform, vectorInsertParent, shapeInsertion, penClosesOnFirst, penPathNode, penDragAnchor, vectorAnchorsInBox, planVectorEdit, vectorAnchorActions, applyVectorAnchorAction, planVectorBoolean, vectorBooleanNode, vectorBooleanPrecision, applyVectorBoolean, vectorMaskClips, } from './workspace/edit/vectorTools.js';
+export type { VectorTool, VectorAnchorAction, VectorStyle, VectorRenderModel, VectorEditTarget, VectorEditPlan, VectorAnchorActions, VectorAnchorActionResult, VectorBooleanPlan, VectorInsertion } from './workspace/edit/vectorTools.js';
+export { richTextSourceDiagnostics, richTextSourceProjection, TEXT_SOURCE_MAPPED_PROPERTIES } from './workspace/source/textSource.js';
+export type { RichTextSourceProjection } from './workspace/source/textSource.js';
+export { TextEditor, TextInlineEditor, TextNodeSurface, useTextFontStatus } from './workspace/edit/TextEditor.js';
+export type { TextEditorProps, TextInlineEditorProps } from './workspace/edit/TextEditor.js';
+export { applyTextCharacterStyle, applyTextParagraphStyle, characterStyleCss, commitTextEdit, decorationCss, isBoundTextNode, paragraphStyleCss, richTextBlocks, setTextResize, textEditorModel, textResizeCss, textStyleTarget, textStyleValues, TEXT_ALIGN_OPTIONS, TEXT_CASE_OPTIONS, TEXT_FONT_WEIGHT_OPTIONS, TEXT_INDENT_STEP, TEXT_LIST_OPTIONS, TEXT_RESIZE_OPTIONS, } from './workspace/edit/textStyles.js';
+export type { TextBlock, TextStyleTarget, TextStyleValues } from './workspace/edit/textStyles.js';
+export * from './document/contracts.js';
+export * from './document/geometry.js';
+export { createDesignDocument, createDocumentNode, createDocumentEngine, reopenDesignDocument, resolveDocumentNode, projectDesignDocument, validateDesignDocument, DocumentValidationError, } from './document/engine.js';
+import type { WorkspaceConfiguration } from './workspace/configuration.js';
 import type { DesignImportController, DesignImportInitialPage, DesignScenarioSource } from './editor/designImport.js';
 import type { ComponentRegistry } from './editor/registry.js';
 import type { DesignComponentConnectionDef } from './editor/componentConnections.js';
@@ -80,7 +149,7 @@ export { createStoryboardRouteScenarioId, createStoryboardGraphFromDiscovery, ge
 export type { LoadStoryboardDiscoveryOptions, StoryboardDiscoveryCandidate, StoryboardDiscoveryEdge, StoryboardDiscoveryGraphOptions, StoryboardDiscoveryManifest, StoryboardDiscoveryResult, StoryboardDiscoveryRoute, StoryboardDiscoveryScenario, StoryboardResolvedPage, } from './editor/storyboardDiscovery.js';
 export { createStoryboardGraphViewModel } from './editor/storyboardGraphView.js';
 export type { StoryboardFrameReference, StoryboardGraphCanonicalView, StoryboardGraphFrameView, StoryboardGraphSourceView, StoryboardGraphTransitionView, StoryboardGraphViewModel, } from './editor/storyboardGraphView.js';
-export { createStoryboardRouteUrl, mergeStoryboardEnvironment, STORYBOARD_ENVIRONMENT_CONTROL, STORYBOARD_ENVIRONMENT_QUERY, } from './editor/storyboardEnvironment.js';
+export { createStoryboardRouteUrl, mergeStoryboardEnvironment, resolveStoryboardBootEnvironment, STORYBOARD_ENVIRONMENT_CONTROL, STORYBOARD_ENVIRONMENT_QUERY, } from './editor/storyboardEnvironment.js';
 export type { ApplyPayload, DesignChangePayload, DesignChangeResult, DesignCodeDocument, DesignElementChange, DesignElementDocument, DesignTokenDocument, InspectApplyResult, InspectImpactFrame, InspectImpactResult, InspectPreviewResult, } from './editor/host.js';
 export type { InspectApplyPayload, PrimitiveSourceValue, PrimitiveSourceValueType, SourceAffectedFrame, SourceEditOperation, SourceEditScope, SourceIdentity, SourceInsertComponent, } from './editor/inspect.js';
 export type { InspectQaArtifactHash, InspectQaCaptureRequest, InspectQaFailure, InspectQaFrameResult, InspectQaPixelDiff, InspectQaPixelDimensions, InspectQaResult, } from './editor/visualQa.js';
@@ -103,7 +172,9 @@ export type { SharedSourceEditScope, SharedSourceFrameSummary, SharedSourceImpac
 export type { NodeJSON } from './editor/store.js';
 export interface InitialPageDef extends DesignImportInitialPage {
 }
-export declare function PygmalionEditor({ runtime, registry, tokens, initialPages, initialCanvas, activeFramePersistenceKey, initialEditMode, componentConnections, codegenProject, codegenValidator, codegenValidationScope, viewportPresets, sessionPresets, previewEnvironmentControls, designImport, onTokensChange, appOrigin, previewRevision, previewCacheNamespace, previewArtifacts, previewConcurrency, previewOpen, onPreviewOpenChange, flowCanvas, frameSurface, captureSupply, screenFlows, screenFlowConcurrency, scenarioCoverage, screenDimensions, screenLists, sectionHeaders, sectionHeaderLabels, screenLanes, frameBranchKinds, frameLabelLabels, screenCards, liveScreenBudget, screenStateAxes, interactiveStates, surfaceClassifications, onApply, onDesignChange, onInspectApply, onInspectPreview, onInspectImpact, storyboard, storyboardScenarios, sessionStoryboards, storyboardDiscovery, }: {
+export interface PygmalionEditorProps {
+    /** Host-owned inventory, storyboard, reproduction and design bindings. */
+    project?: PygmalionHostProject;
     /**
      * The runtime this editor renders. Create one with `createEditorRuntime()`
      * and keep it for the editor's lifetime; two editors on one page each take
@@ -129,6 +200,8 @@ export declare function PygmalionEditor({ runtime, registry, tokens, initialPage
      * once rather than re-asserting over whatever the designer picked.
      */
     initialEditMode?: 'edit' | 'view-only';
+    /** The redesigned workspaces use a canonical document and separate run state. */
+    workspace?: WorkspaceConfiguration;
     /** Explicit external-design to registered-code component mappings. */
     componentConnections?: readonly DesignComponentConnectionDef[];
     /**
@@ -323,4 +396,29 @@ export declare function PygmalionEditor({ runtime, registry, tokens, initialPage
      * environment service.
      */
     storyboardDiscovery?: boolean;
-}): import("react").JSX.Element;
+}
+export declare function PygmalionEditor(props: PygmalionEditorProps): import("react").JSX.Element;
+export { applyLayout, layoutHugAxes, layoutProblem, layoutChildProblem, layoutChild, isAbsoluteLayoutChild, participatesInLayout } from './document/layout.js';
+export type { LayoutSpec, LayoutChild, LayoutPlacement, LayoutResult } from './document/layout.js';
+export { LayoutPanel } from './workspace/edit/LayoutPanel.js';
+export type { LayoutPanelProps } from './workspace/edit/LayoutPanel.js';
+export { CanvasGuides, CanvasGuidesPanel } from './workspace/edit/CanvasGuides.js';
+export { nodeGuides, guidesPatch, nodeLayoutGrids, layoutGridsPatch, isCanvasGuide, isLayoutGrid, defaultLayoutGrid, rulerTicks, rulerScale } from './workspace/edit/canvasGuideModel.js';
+export type { CanvasGuide, LayoutGrid, LayoutGridTracks, LayoutGridPixels } from './workspace/edit/canvasGuideModel.js';
+export * from './document/appearance.js';
+export { AppearancePanel, AppearanceSurface, AppearanceVectorSurface } from './workspace/edit/AppearancePanel.js';
+export type { AppearancePanelProps } from './workspace/edit/AppearancePanel.js';
+export * from './workspace/source/appearanceSource.js';
+export { assetInteropSourceDeltaDiagnostics, ASSETS_METADATA_KEY, ASSET_STORE_VERSION, IMAGE_MEDIA_TYPES, IMAGE_SCALE_MODES, IMAGE_SCALE_MODE_LABELS, createImageAsset, createSvgAsset, documentAssets, resolveAsset, addAsset, removeAsset, renameAsset, mergeAssetStores, assetStoreDiagnostics, serializeAssetStore, writeDocumentAssets, addDocumentAsset, nodeImagePaints, nodeAssetIds, assetReferences, unusedAssetIds, pruneUnusedAssets, missingAssetIds, assetsDuplicateMetadata, assetSourceUrl, imagePaint, imagePaintCss, nodeImageCss, imageNode, isImageNode, importAssetFiles, assetsFromInventory } from './document/assets.js';
+export type { DocumentAsset, ImageAsset, SvgAsset, AssetStore, ImageAssetInput, SvgAssetInput, AssetFileLike, InventoryAssetMedia, InventoryAssetEntry } from './document/assets.js';
+export * from './document/svgImport.js';
+export * from './document/exportSettings.js';
+export * from './workspace/edit/clipboard.js';
+export { AssetsPanel } from './workspace/edit/AssetsPanel.js';
+export type { AssetsPanelProps } from './workspace/edit/AssetsPanel.js';
+export * from './document/prototype.js';
+export { remapPrototypeProperties } from './document/prototypeReferences.js';
+export { PrototypePanel } from './workspace/edit/PrototypePanel.js';
+export { PrototypePlayer } from './workspace/view/PrototypePlayer.js';
+export type { PrototypePlayerProps } from './workspace/view/PrototypePlayer.js';
+export * from './workspace/view/prototypePlayback.js';

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

@@ -0,0 +1,62 @@
+import type { DesignDocument, DocumentDiagnostic, DocumentNode, DocumentNodePatch, DocumentTransaction, DocumentValue } from '../document/contracts.js';
+import type { TokenLibraryDocument, TokenValueResolution } from './contracts.js';
+export type VariableScalar = string | number | boolean;
+export interface VariableBinding {
+    libraryId: string;
+    tokenId: string;
+    modeId?: string;
+}
+export type VariableBindings = Record<string, VariableBinding>;
+export type VariableValueCodec = (library: TokenLibraryDocument, resolved: TokenValueResolution) => VariableScalar;
+export interface VariableChange {
+    nodeId: string;
+    overrideAddress?: string;
+    property: string;
+    tokenId: string;
+    before: DocumentValue | undefined;
+    after: VariableScalar;
+}
+export interface VariableUpdatePlan {
+    documentFingerprint: string;
+    libraryId: string;
+    sourceRevision: string;
+    libraryFingerprint: string;
+    patches: {
+        nodeId: string;
+        overrideAddress?: string;
+        patch: DocumentNodePatch;
+    }[];
+    changes: VariableChange[];
+    diagnostics: DocumentDiagnostic[];
+}
+export declare const VARIABLE_TARGETS: {
+    readonly width: "number";
+    readonly height: "number";
+    readonly radius: "number";
+    readonly opacity: "number";
+    readonly fontSize: "number";
+    readonly fontWeight: "number";
+    readonly lineHeight: "number";
+    readonly letterSpacing: "number";
+    readonly text: "string";
+    readonly fontFamily: "string";
+    readonly fill: "string";
+    readonly color: "string";
+    readonly hidden: "boolean";
+    readonly clip: "boolean";
+};
+export type VariableTarget = keyof typeof VARIABLE_TARGETS;
+export declare function isVariableBinding(value: unknown): value is VariableBinding;
+export declare function nodeVariableBindings(node: Pick<DocumentNode, 'properties'>): VariableBindings;
+/** Built-in values are JSON scalars. Other syntax remains the host codec's responsibility. */
+export declare function resolveScalarVariable(library: TokenLibraryDocument, resolved: TokenValueResolution, seen?: Set<string>): VariableScalar;
+export declare function variableModeForNode(document: DesignDocument, nodeId: string, library: TokenLibraryDocument, tokenId: string, explicit?: string): string;
+export declare function variableTargetsForNode(node: DocumentNode): VariableTarget[];
+export declare function bindVariablePatch(document: DesignDocument, nodeId: string, property: VariableTarget, library: TokenLibraryDocument, binding: VariableBinding, codec?: VariableValueCodec): DocumentNodePatch;
+export declare function detachVariablePatch(node: DocumentNode, property: VariableTarget): DocumentNodePatch;
+/** A refresh plan records all affected nodes before the caller commits one history entry. */
+export declare function planVariableLibraryUpdate(document: DesignDocument, library: TokenLibraryDocument, codec?: VariableValueCodec): VariableUpdatePlan;
+export declare function commitVariableLibraryUpdate(tx: DocumentTransaction, document: DesignDocument, plan: VariableUpdatePlan): void;
+export declare function commitVariableMode(tx: DocumentTransaction, document: DesignDocument, nodeId: string, library: TokenLibraryDocument, collectionId: string, modeId: string | null, codec?: VariableValueCodec): void;
+/** Literal projection does not claim that source code preserves the binding or mode relationship. */
+export declare function variablesSourceDiagnostics(after: DesignDocument, before: DesignDocument): DocumentDiagnostic[];

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

@@ -0,0 +1,117 @@
+/** Authored token state. Source paths, CSS names, and codecs belong to the host baseline. */
+export interface TokenLibraryDocument {
+    schemaVersion: 1;
+    id: string;
+    sourceRevision: string;
+    collections: Record<string, TokenCollection>;
+    tokens: Record<string, LibraryToken>;
+}
+export interface TokenCollection {
+    id: string;
+    name: string;
+    defaultModeId: string;
+    modes: TokenMode[];
+}
+export interface TokenMode {
+    id: string;
+    name: string;
+    /** An absent authored value may inherit from this mode. Empty text is still authored. */
+    fallbackModeId?: string;
+}
+export interface LibraryToken {
+    /** Stable across rename, draft persistence, and source regeneration. */
+    id: string;
+    collectionId: string;
+    name: string;
+    /** The host's declared value type, preserved without inferring it from text. */
+    type: string;
+    valuesByMode: Record<string, TokenValue>;
+}
+export interface TokenReferenceSpan {
+    /** Non-overlapping UTF-16 offsets in the exact authored text. Syntax belongs to the codec. */
+    start: number;
+    end: number;
+    tokenId: string;
+    /** Omission keeps the requested evaluation mode, including through inherited values. */
+    modeId?: string;
+}
+export interface TokenValue {
+    kind: 'literal' | 'alias' | 'expression' | 'opaque';
+    /** Exact authored value text; codecs preserve delimiters, units, and embedded expressions. */
+    text: string;
+    /** An opaque host codec identity. The core never parses or formats this syntax. */
+    format: string;
+    references: TokenReferenceSpan[];
+}
+export interface ResolvedTokenReference extends TokenReferenceSpan {
+    modeId: string;
+}
+/** Resolves authorship and graph edges, not host value syntax or computed CSS. */
+export interface TokenValueResolution {
+    tokenId: string;
+    collectionId: string;
+    modeId: string;
+    authoredModeId: string;
+    inherited: boolean;
+    value: TokenValue;
+    references: ResolvedTokenReference[];
+}
+export interface TokenLibraryDiagnostic {
+    code: string;
+    message: string;
+    tokenId?: string;
+    collectionId?: string;
+    modeId?: string;
+}
+export interface TokenLibraryValidationResult {
+    valid: boolean;
+    diagnostics: readonly TokenLibraryDiagnostic[];
+}
+export interface TokenValueEditability {
+    editable: boolean;
+    reason?: 'opaque-value';
+}
+export interface TokenLibraryTransaction {
+    createCollection(collection: TokenCollection): void;
+    renameCollection(collectionId: string, name: string): void;
+    /** Only an empty collection may be removed. */
+    removeCollection(collectionId: string): void;
+    addMode(collectionId: string, mode: TokenMode): void;
+    renameMode(collectionId: string, modeId: string, name: string): void;
+    /** Referenced/default modes must be retargeted explicitly before removal. */
+    removeMode(collectionId: string, modeId: string): void;
+    setDefaultMode(collectionId: string, modeId: string): void;
+    setModeFallback(collectionId: string, modeId: string, fallbackModeId: string | null): void;
+    create(token: LibraryToken): void;
+    /** Creates an authored override when this mode previously inherited a value. */
+    setValue(tokenId: string, modeId: string, value: TokenValue): void;
+    /** Removes an authored override; validation requires every mode to remain resolvable. */
+    clearValue(tokenId: string, modeId: string): void;
+    /** Stable references remain attached to the same token; the host formats source names. */
+    rename(tokenId: string, name: string): void;
+    /** Referenced tokens, including references in inactive modes, cannot be removed. */
+    remove(tokenId: string): void;
+    /** Restores a same-library, same-source snapshot as one undoable transaction. */
+    replaceDocument(document: TokenLibraryDocument): void;
+}
+export interface TokenLibraryEngineOptions {
+    historyLimit?: number;
+    /** Pure host policy checks run before the entire transaction commits. */
+    preflight?(input: {
+        before: TokenLibraryDocument;
+        after: TokenLibraryDocument;
+        operations: readonly string[];
+    }): readonly TokenLibraryDiagnostic[];
+}
+export interface TokenLibraryEngine {
+    readonly snapshot: TokenLibraryDocument;
+    readonly revision: number;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    transact(label: string, apply: (transaction: TokenLibraryTransaction) => void): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    /** Serializes the library only; the internal history envelope is not a public format. */
+    serialize(): string;
+    subscribe(listener: () => void): () => void;
+}

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

@@ -0,0 +1,13 @@
+import type { TokenLibraryDiagnostic, TokenLibraryDocument, TokenLibraryEngine, TokenLibraryEngineOptions, TokenLibraryValidationResult, TokenValueEditability, TokenValueResolution } from './contracts.js';
+export declare class TokenLibraryValidationError extends Error {
+    readonly diagnostics: readonly TokenLibraryDiagnostic[];
+    constructor(diagnostics: readonly TokenLibraryDiagnostic[]);
+}
+/** Validate authored syntax boundaries and the complete token/mode reference graph. */
+export declare function validateTokenLibraryDocument(input: unknown): TokenLibraryValidationResult;
+/** A lightweight lookup for an already validated library; returned data is detached and frozen. */
+export declare function resolveTokenLibraryValue(document: TokenLibraryDocument, tokenId: string, modeId: string): TokenValueResolution;
+export declare function tokenValueEditability(document: TokenLibraryDocument, tokenId: string, modeId: string): TokenValueEditability;
+/** Separate library sessions share the existing document transaction and history implementation. */
+export declare function createTokenLibraryEngine(document: TokenLibraryDocument, options?: TokenLibraryEngineOptions): TokenLibraryEngine;
+export declare function reopenTokenLibrary(serialized: string, options?: TokenLibraryEngineOptions): TokenLibraryEngine;

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

@@ -0,0 +1,9 @@
+import type { WorkspaceConfiguration } from './configuration.js';
+
+export interface WorkspaceShellProps {
+    configuration: WorkspaceConfiguration;
+    sourceRevision: string;
+    previewIdentityReady: boolean;
+    previewOpen?: boolean;
+}
+export declare const WorkspaceShell: import("react").FunctionComponent<WorkspaceShellProps>;

package/dist-lib/types/workspace/application/ApplicationWorkspace.d.ts

@@ -0,0 +1,3 @@
+export declare function ApplicationWorkspace({ ready }: {
+    ready: boolean;
+}): import("react").JSX.Element | null;

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

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+import type { HostDataCapabilities } from '../binding/contracts.js';
+import type { DesignDocument, DocumentNode, DocumentDuplicateMetadataRemapper } from '../document/contracts.js';
+import type { WorkspaceSourceCapabilities } from './source/flowContracts.js';
+import type { WorkspaceTarget } from './contracts.js';
+import type { WorkspaceTokenLibraryCapabilities } from './tokens/contracts.js';
+/** One target's source, data, rendering, and persistence capabilities travel together. */
+export interface WorkspaceTargetConfiguration {
+    data?: HostDataCapabilities;
+    source?: WorkspaceSourceCapabilities;
+    duplicateMetadata?: DocumentDuplicateMetadataRemapper;
+    loadDocument?(target: WorkspaceTarget, options: {
+        signal: AbortSignal;
+    }): Promise<DesignDocument>;
+    /** Persist the versioned design draft; this is not permission to write source. */
+    saveDocument?(target: WorkspaceTarget, serializedDocument: string): Promise<void>;
+    /** Render the actual registered implementation with resolved input props. */
+    renderComponent?(node: DocumentNode, props: Readonly<Record<string, unknown>>, context: {
+        document: DesignDocument;
+    }): ReactNode;
+    onRequestData?(request: {
+        screenId: string;
+        description: string;
+    }): void;
+}
+/** Source loading and product interpretation stay with the host adapter. */
+export interface WorkspaceConfiguration extends WorkspaceTargetConfiguration {
+    /** One shared token library, independent of per-screen visual document drafts. */
+    tokenLibrary?: WorkspaceTokenLibraryCapabilities;
+    initialMode?: 'view' | 'edit';
+    /** Host source/session controls occupy the shared header, outside mode panels. */
+    chrome?: ReactNode;
+    /** Undefined explicitly marks an unsupported screen or source revision. */
+    resolveTarget?(target: WorkspaceTarget): WorkspaceTargetConfiguration | undefined;
+}
+/** An explicit target resolver never inherits capabilities from the root configuration. */
+export declare function resolveWorkspaceTarget(configuration: WorkspaceConfiguration, target: WorkspaceTarget): WorkspaceTargetConfiguration | undefined;
+/** Compares captured capability identities without invoking any host callbacks. */
+export declare function sameWorkspaceTargetConfiguration(left: WorkspaceTargetConfiguration | undefined, right: WorkspaceTargetConfiguration | undefined): boolean;

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

@@ -0,0 +1,64 @@
+/** Navigation state belongs to the workspace, never to document history. */
+export type WorkspaceMode = 'view' | 'edit' | 'application';
+export interface WorkspaceTarget {
+    screenId: string;
+    sourceRevision: string;
+}
+export interface WorkspaceCamera {
+    x: number;
+    y: number;
+    zoom: number;
+}
+export interface WorkspaceDesignContext {
+    target: WorkspaceTarget;
+    selection: readonly string[];
+    camera: WorkspaceCamera;
+}
+export interface WorkspaceApplicationSurface {
+    /** An implementation URL or a built draft URL supplied by the host. */
+    url: string;
+    /** A built draft must identify the exact document revision it executes. */
+    documentRevision?: string;
+    /** The artifact must confirm that its declared screen recipe has completed. */
+    waitForReady?: boolean;
+}
+/** A fixed CSS viewport width for an executed surface; the host application still owns its own layout. */
+export interface WorkspaceRunViewport {
+    width: number;
+    label?: string;
+}
+export interface WorkspaceApplicationRun {
+    id: number;
+    target: WorkspaceTarget;
+    kind: 'implementation' | 'built-draft';
+    documentRevision?: string;
+    viewport?: WorkspaceRunViewport;
+    status: 'preparing' | 'ready' | 'failed';
+    surface?: WorkspaceApplicationSurface;
+    error?: string;
+    /** Run navigation cannot change the selected storyboard or design target. */
+    locations: readonly string[];
+    locationIndex: number;
+}
+export interface WorkspaceSnapshot {
+    mode: WorkspaceMode;
+    view: {
+        target: WorkspaceTarget | null;
+        camera: WorkspaceCamera;
+    };
+    design: WorkspaceDesignContext | null;
+    application: WorkspaceApplicationRun | null;
+    returnMode: 'view' | 'edit';
+}
+export interface WorkspaceRunRequest {
+    target: WorkspaceTarget;
+    kind?: WorkspaceApplicationRun['kind'];
+    documentRevision?: string;
+    /** Requested execution width; omitted means the surface fills the workspace. */
+    viewport?: WorkspaceRunViewport;
+}
+export type WorkspaceApplicationPreparer = (
+/** Captured run identity; caller mutations cannot retarget preparation. */
+request: WorkspaceRunRequest, 
+/** Return, replacement, and disposal abort pending work. */
+signal: AbortSignal) => Promise<WorkspaceApplicationSurface>;

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

@@ -0,0 +1,35 @@
+import type { WorkspaceApplicationPreparer, WorkspaceRunViewport, WorkspaceApplicationSurface, WorkspaceCamera, WorkspaceMode, WorkspaceRunRequest, WorkspaceSnapshot, WorkspaceTarget } from './contracts.js';
+/** Runtime-scoped navigation with independent design and application contexts. */
+export declare class WorkspaceController {
+    private value;
+    private listeners;
+    private designContexts;
+    private runSequence;
+    /** Owns both pending preparation and the lifetime of its ready surface. */
+    private activeRunController;
+    private cancellingPreparation;
+    private disposed;
+    constructor(initialMode?: 'view' | 'edit');
+    getSnapshot: () => WorkspaceSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    private update;
+    selectView(target: WorkspaceTarget): void;
+    edit(target?: WorkspaceTarget | null): void;
+    setMode(mode: Exclude<WorkspaceMode, 'application'>): void;
+    setSelection(selection: readonly string[]): void;
+    setCamera(mode: 'view' | 'edit', next: WorkspaceCamera): void;
+    beginApplication(request: WorkspaceRunRequest): number;
+    private startApplication;
+    completeApplication(id: number, surface: WorkspaceApplicationSurface): boolean;
+    failApplication(id: number, error: string): boolean;
+    invalidateApplication(id: number, error: string): boolean;
+    prepareApplication(request: WorkspaceRunRequest, prepare: WorkspaceApplicationPreparer): Promise<boolean>;
+    /** Resizing the executed surface is view state; it never restarts or re-prepares the run. */
+    setApplicationViewport(id: number, viewport: WorkspaceRunViewport | undefined): boolean;
+    navigateApplication(id: number, location: string): boolean;
+    backApplication(): boolean;
+    returnFromApplication(): void;
+    private cancelPreparation;
+    private abortRunController;
+    dispose(): void;
+}

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

@@ -0,0 +1,42 @@
+import type { BindingNodeContext, HostDataCapabilities } from '../binding/contracts.js';
+import type { DesignDocument, DocumentDiagnostic, DocumentEngine } from '../document/contracts.js';
+import { type WorkspaceConfiguration, type WorkspaceTargetConfiguration } from './configuration.js';
+import type { WorkspaceTarget } from './contracts.js';
+export interface WorkspaceDocumentSession {
+    target: WorkspaceTarget;
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    engine?: DocumentEngine;
+    error?: string;
+    saving: boolean;
+    savedRevision: number;
+    dirty: boolean;
+    configuration?: WorkspaceTargetConfiguration;
+    configurationRevision: number;
+}
+export declare function documentBindingNodes(document: DesignDocument): BindingNodeContext[];
+/** Bindings participate in the document commit, never in a parallel history. */
+export declare function documentBindingPreflight(capabilities: HostDataCapabilities | undefined | (() => HostDataCapabilities | undefined)): ({ before, after }: {
+    before: DesignDocument;
+    after: DesignDocument;
+}) => readonly DocumentDiagnostic[];
+/** A runtime owns this collection; mode switches do not destroy its draft engines. */
+export declare class WorkspaceDocumentSessions {
+    private sessions;
+    private pending;
+    private subscriptions;
+    private configurations;
+    private baselines;
+    private savedSnapshots;
+    private pendingSaves;
+    private listeners;
+    private disposed;
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: (target: WorkspaceTarget) => WorkspaceDocumentSession;
+    private update;
+    load(target: WorkspaceTarget, configuration: WorkspaceConfiguration): Promise<DocumentEngine | null>;
+    save(target: WorkspaceTarget, explicitSave?: NonNullable<WorkspaceTargetConfiguration['saveDocument']>): Promise<boolean>;
+    /** Reset means the snapshot first loaded for this target, including a persisted draft. */
+    reset(target: WorkspaceTarget): boolean;
+    hasUnsavedChanges(): boolean;
+    dispose(): void;
+}

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

@@ -0,0 +1,23 @@
+import type { DesignDocument, DocumentEngine, DocumentNode } from '../../document/contracts.js';
+import { appearanceToCss } from '../../document/appearance.js';
+
+export interface AppearancePanelProps {
+    engine: DocumentEngine;
+    nodeId: string;
+    disabled?: boolean;
+}
+export declare function AppearancePanel({ engine, nodeId, disabled }: AppearancePanelProps): import("react").JSX.Element | null;
+/** Separate decorative layers preserve each paint's opacity independently of the content. */
+export declare function AppearanceSurface({ node, document }: {
+    node: DocumentNode;
+    document: DesignDocument;
+}): import("react").JSX.Element | null;
+export { appearanceToCss };
+/** Canvas paths remain real SVG elements, including editable geometry previews. */
+export declare function AppearanceVectorSurface({ node, document, width, height, vector }: {
+    node: DocumentNode;
+    document: DesignDocument;
+    width?: number;
+    height?: number;
+    vector?: import('../../document/vector.js').VectorProperties;
+}): import("react").JSX.Element;

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

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