@pygmalionjs/pygmalion 0.8.0 → 0.9.0

package/dist-lib/types/workspace/source/ResponsiveLayoutPanel.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+import type { DesignDocument, DocumentEngine } from '../../document/contracts.js';
+import type { WorkspaceResponsiveSourceMapping } from './responsiveContracts.js';
+/** Preview width is view state, separate from the authored responsive declarations. */
+export declare function ResponsiveViewportProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useWorkspaceResponsiveViewport(): {
+    width: number;
+    setWidth: (width: number) => void;
+};
+export declare function ResponsiveLayoutPanel({ engine, document, mapping, selectedId, disabled, initialRangeId }: {
+    engine: DocumentEngine;
+    document: DesignDocument;
+    mapping: WorkspaceResponsiveSourceMapping;
+    selectedId?: string;
+    disabled: boolean;
+    /** The range opened first; the base range when omitted. Selection stays view state afterwards. */
+    initialRangeId?: string;
+}): import("react").JSX.Element | null;

package/dist-lib/types/workspace/source/SourceReview.d.ts

@@ -0,0 +1,11 @@
+import type { EditorRuntime } from '../../core/runtime.js';
+import type { DocumentEngine } from '../../document/contracts.js';
+import type { WorkspaceTarget } from '../contracts.js';
+import type { WorkspaceSourceCapabilities } from './flowContracts.js';
+export interface WorkspaceSourcePanelProps {
+    runtime: EditorRuntime;
+    target: WorkspaceTarget;
+    engine: DocumentEngine;
+    capabilities?: WorkspaceSourceCapabilities;
+}
+export declare function WorkspaceSourcePanel(props: WorkspaceSourcePanelProps): import("react").JSX.Element;

package/dist-lib/types/workspace/source/appearanceSource.d.ts

@@ -0,0 +1,19 @@
+import type { DocumentDiagnostic, DocumentNode } from '../../document/contracts.js';
+export interface AppearanceSourceProjection {
+    declarations: Record<string, string>;
+    diagnostics: DocumentDiagnostic[];
+}
+export declare const APPEARANCE_SOURCE_FIELDS: readonly ["properties.paints", "properties.strokes", "properties.effects", "properties.blendMode"];
+/** Only declarations supported by the existing stylesheet writer are returned. Unsupported output blocks the whole appearance delta. */
+export declare function appearanceSourceProjection(node: DocumentNode): AppearanceSourceProjection;
+/** A compiler field maps to exactly one existing CSS declaration. Coupled stroke/effect shadows must use one mapping. */
+export declare function appearanceSourceValue(node: DocumentNode, field: string): {
+    value: string | null;
+    diagnostics: DocumentDiagnostic[];
+};
+export interface AppearanceSourceFieldMapping {
+    nodeId: string;
+    field: string;
+}
+/** Guard for custom source compilers: every advanced appearance delta needs an explicit field mapping. */
+export declare function appearanceSourceDeltaDiagnostics(before: import('../../document/contracts.js').DesignDocument, after: import('../../document/contracts.js').DesignDocument, mapped?: readonly AppearanceSourceFieldMapping[]): DocumentDiagnostic[];

package/dist-lib/types/workspace/source/compiler.d.ts

@@ -0,0 +1,5 @@
+import type { WorkspaceVisualSourceCompileInput, WorkspaceVisualSourceCompileResult } from './contracts.js';
+/** Lossless identity shared with the isolated source builder. */
+export declare const workspaceSourceFingerprint: (value: unknown) => string;
+/** Converts a complete draft delta to existing inspect operators, or rejects the entire delta. */
+export declare function compileWorkspaceVisualSource(input: WorkspaceVisualSourceCompileInput): WorkspaceVisualSourceCompileResult;

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

@@ -0,0 +1,156 @@
+import type { DesignDocument } from '../../document/contracts.js';
+import type { InspectApplyPayload, InspectMedia, SourceAffectedFrame, SourceEditScope, SourceIdentity } from '../../editor/inspect.js';
+import type { WorkspaceTarget } from '../contracts.js';
+import type { WorkspaceResponsiveSourceMapping } from './responsiveContracts.js';
+/** Only properties with implemented visual semantics may become source edits. */
+export type WorkspaceVisualSourceField = 'width' | 'height' | 'properties.fill' | 'properties.color' | 'properties.radius' | 'properties.fontSize' | 'properties.opacity' | 'properties.text' | 'properties.paints' | 'properties.strokes' | 'properties.effects';
+export interface WorkspaceSourceFileProof {
+    /** Exact project-relative path. The host checks these bytes before review and apply. */
+    file: string;
+    /** Null is an explicit absence proof for a new file in a complete file plan. */
+    sha256: string | null;
+}
+export interface WorkspaceVisualStyleSource {
+    kind: 'style';
+    file: string;
+    className: string;
+    componentFile: string;
+    property: string;
+    /** Lengths accept finite numbers as pixels or an explicitly permitted CSS token. */
+    encoding: 'css-length' | 'number' | 'string';
+    affectedFrames: readonly SourceAffectedFrame[];
+    media?: InspectMedia;
+}
+export interface WorkspaceVisualTextSource {
+    kind: 'text';
+    identity: SourceIdentity;
+    scope: SourceEditScope;
+    affectedFrames: readonly SourceAffectedFrame[];
+}
+export interface WorkspaceVisualSourceRule {
+    nodeId: string;
+    field: WorkspaceVisualSourceField;
+    label?: string;
+    /** Host-owned tokens or literal choices. Omission permits otherwise valid visual values. */
+    permittedValues?: readonly (string | number)[];
+    source: WorkspaceVisualStyleSource | WorkspaceVisualTextSource;
+}
+/** Source locations and proofs are supplied by the host, never inferred from rendered values. */
+export interface WorkspaceVisualSourceMapping {
+    version: 1;
+    target: WorkspaceTarget;
+    documentId: string;
+    /** workspaceSourceFingerprint of the complete source-derived baseline. */
+    baselineFingerprint: string;
+    files: readonly WorkspaceSourceFileProof[];
+    rules: readonly WorkspaceVisualSourceRule[];
+    /** One intrinsic-layout source island; expressions remain opaque owned leaves. */
+    structure?: WorkspaceStructureSourceMapping;
+    /** Responsive declarations use the same complete source baseline and file proofs. */
+    responsive?: WorkspaceResponsiveSourceMapping;
+}
+export interface WorkspaceStructureSourceAnchor {
+    nodeId: string;
+    file: string;
+    start: number;
+    end: number;
+    expected: string;
+}
+export type WorkspaceStructureGroupAlignment = 'start' | 'center' | 'end' | 'stretch';
+/** The source-relevant part of a group's document layout; sizing stays an authoring value. */
+export interface WorkspaceStructureGroupLayout {
+    direction: 'horizontal' | 'vertical' | 'grid';
+    gap: number;
+    padding: number;
+    align?: WorkspaceStructureGroupAlignment;
+    wrap?: boolean;
+    crossGap?: number;
+    distribute?: 'start' | 'center' | 'end' | 'space-between';
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    columns?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+}
+/**
+ * Declares how a source group with a layout becomes one intrinsic element plus a generated
+ * stylesheet class. Absent, groups compile to transparent fragments only. Spacing pairs the
+ * document's pixel values with the host's exact CSS spellings; the core never invents tokens.
+ */
+export interface WorkspaceStructureWrapperDeclaration {
+    /** Stylesheet receiving generated class blocks; requires an exact file proof. */
+    stylesheet: string;
+    /** JSX identifier of the imported stylesheet module, as in `className={alias.name}`. */
+    styleAlias: string;
+    /** Intrinsic non-void element for generated wrappers; defaults to `div`. */
+    tagName?: string;
+    spacing: readonly {
+        px: number;
+        css: string;
+    }[];
+    /** Permitted alignments; omission permits every document alignment. */
+    align?: readonly WorkspaceStructureGroupAlignment[];
+}
+export interface WorkspaceStructureSourceMapping {
+    rootId: string;
+    anchors: readonly WorkspaceStructureSourceAnchor[];
+    wrapper?: WorkspaceStructureWrapperDeclaration;
+}
+export type WorkspaceStructureSourceOperation = {
+    kind: 'reorder';
+    parentId: string;
+    children: string[];
+} | {
+    kind: 'group';
+    nodeIds: string[];
+    groupId: string;
+    layout?: WorkspaceStructureGroupLayout;
+} | {
+    kind: 'ungroup';
+    nodeId: string;
+} | {
+    kind: 'reparent';
+    nodeId: string;
+    parentId: string;
+    index: number;
+};
+export interface WorkspaceVisualSourceDiagnostic {
+    code: string;
+    message: string;
+    nodeId?: string;
+    field?: string;
+}
+export interface WorkspaceVisualSourceIdentity {
+    version: 1;
+    target: WorkspaceTarget;
+    documentId: string;
+    /** Lossless, deterministic JSON fingerprints cover all fields, not just mapped deltas. */
+    beforeFingerprint: string;
+    afterFingerprint: string;
+    mappingFingerprint: string;
+    payloadFingerprint: string;
+    fingerprint: string;
+}
+export interface WorkspaceVisualSourceCompileInput {
+    target: WorkspaceTarget;
+    before: DesignDocument;
+    after: DesignDocument;
+    mapping: WorkspaceVisualSourceMapping;
+}
+export type WorkspaceVisualSourceCompileResult = {
+    status: 'ready';
+    identity: WorkspaceVisualSourceIdentity;
+    payload: InspectApplyPayload;
+    diagnostics: readonly [];
+} | {
+    status: 'unchanged';
+    identity: WorkspaceVisualSourceIdentity;
+    diagnostics: readonly [];
+} | {
+    status: 'blocked';
+    diagnostics: readonly WorkspaceVisualSourceDiagnostic[];
+};

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

@@ -0,0 +1,50 @@
+import type { DocumentEngine } from '../../document/contracts.js';
+import type { InspectApplyResult, InspectPreviewResult } from '../../editor/host.js';
+import type { WorkspaceTarget } from '../contracts.js';
+import type { WorkspaceVisualSourceDiagnostic } from './contracts.js';
+import type { WorkspaceSourceBaseline, WorkspaceSourceCapabilities, WorkspaceSourceRequest } from './flowContracts.js';
+export interface WorkspaceSourceReviewState {
+    status: 'idle' | 'loading' | 'reconciling' | 'reconciled' | 'reviewing' | 'blocked' | 'unchanged' | 'reviewed' | 'applying' | 'applied' | 'error';
+    baseline?: WorkspaceSourceBaseline;
+    request?: WorkspaceSourceRequest;
+    preview?: InspectPreviewResult;
+    result?: InspectApplyResult;
+    diagnostics: readonly WorkspaceVisualSourceDiagnostic[];
+    error?: string;
+    reconciliation?: {
+        beforeFingerprint: string;
+        baseline: WorkspaceSourceBaseline;
+        document: WorkspaceSourceBaseline['document'];
+        changedFiles: readonly string[];
+    };
+}
+/** Each review binds complete draft contents, source proofs, target, and capabilities. */
+export declare class WorkspaceSourceReviewController {
+    private state;
+    private listeners;
+    private epoch;
+    private pending;
+    private disposed;
+    private invalidating;
+    private applying;
+    private unsubscribe;
+    private writer;
+    readonly target: WorkspaceTarget;
+    readonly engine: DocumentEngine;
+    readonly capabilities: WorkspaceSourceCapabilities;
+    constructor(target: WorkspaceTarget, engine: DocumentEngine, capabilities: WorkspaceSourceCapabilities);
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => WorkspaceSourceReviewState;
+    private update;
+    private invalidate;
+    private current;
+    load(): Promise<boolean>;
+    review(): Promise<boolean>;
+    /** Propose a merge without replacing the current draft or granting source-write approval. */
+    reconcile(): Promise<boolean>;
+    acceptReconciliation(): boolean;
+    discardReconciliation(): boolean;
+    apply(): Promise<boolean>;
+    resetToSource(): boolean;
+    dispose(): void;
+}

package/dist-lib/types/workspace/source/documentRevision.d.ts

@@ -0,0 +1,2 @@
+/** Hash the complete captured document, independent of the source payload family. */
+export declare function workspaceDocumentRevision(fingerprint: string): Promise<string>;

package/dist-lib/types/workspace/source/draftPreviewClient.d.ts

@@ -0,0 +1,13 @@
+import type { WorkspaceSourceRequest } from './flowContracts.js';
+import type { WorkspaceTokenSourceRequest } from '../tokens/contracts.js';
+import type { WorkspaceApplicationSurface } from '../contracts.js';
+export type WorkspaceDraftPreviewClient = (request: WorkspaceSourceRequest | WorkspaceTokenSourceRequest, options: {
+    signal: AbortSignal;
+    documentRevision: string;
+    modeId?: string;
+}) => Promise<WorkspaceApplicationSurface>;
+/** A hosted implementation can replace this local transport without changing authoring ports. */
+export declare function createWorkspaceDraftPreviewClient(options?: {
+    endpoint?: string;
+    fetch?: typeof globalThis.fetch;
+}): WorkspaceDraftPreviewClient;

package/dist-lib/types/workspace/source/draftRecipe.d.ts

@@ -0,0 +1,30 @@
+import type { DesignScreenAssertion, DesignScreenAssertionReport, DesignScreenCaptureFailure, DesignScreenDesiredState, DesignScreenInteraction, DesignScreenInteractionReport, DesignScreenPresetExecutionResult } from '../../editor/designImport.js';
+export interface WorkspaceDraftDocumentContext {
+    document: Document;
+    window: Window;
+}
+export interface WorkspaceDraftRecipe {
+    interactions?: readonly DesignScreenInteraction[];
+    assertions?: readonly DesignScreenAssertion[];
+    desiredState?: DesignScreenDesiredState;
+}
+export interface WorkspaceDraftRecipeOptions {
+    signal?: AbortSignal;
+    /** Replaces host-owned state after mount; an omitted desired state is an empty replacement. */
+    applyDesiredState?: (state: DesignScreenDesiredState, context: WorkspaceDraftDocumentContext & {
+        signal?: AbortSignal;
+    }) => DesignScreenPresetExecutionResult | void | Promise<DesignScreenPresetExecutionResult | void>;
+}
+export interface WorkspaceDraftRecipeReport {
+    complete: boolean;
+    desiredStateApplied: boolean;
+    interactions: DesignScreenInteractionReport;
+    assertions: DesignScreenAssertionReport;
+    failures: readonly DesignScreenCaptureFailure[];
+}
+export declare class WorkspaceDraftRecipeError extends Error {
+    readonly report: WorkspaceDraftRecipeReport;
+    constructor(report: WorkspaceDraftRecipeReport);
+}
+/** Replays the host recipe inside its mounted artifact, using the same screen runners as implementation capture. */
+export declare function runWorkspaceDraftRecipe(context: WorkspaceDraftDocumentContext, recipe: WorkspaceDraftRecipe, options?: WorkspaceDraftRecipeOptions): Promise<WorkspaceDraftRecipeReport>;

package/dist-lib/types/workspace/source/flowContracts.d.ts

@@ -0,0 +1,72 @@
+import type { DesignDocument } from '../../document/contracts.js';
+import type { InspectApplyPayload } from '../../editor/inspect.js';
+import type { InspectApplyResult, InspectPreviewResult } from '../../editor/host.js';
+import type { WorkspaceApplicationSurface, WorkspaceTarget } from '../contracts.js';
+import type { WorkspaceVisualSourceDiagnostic, WorkspaceVisualSourceIdentity, WorkspaceVisualSourceMapping } from './contracts.js';
+import type { SourceFilePlan } from '../../host/sourceFilePlan.js';
+export interface WorkspaceSourceBaseline {
+    document: DesignDocument;
+    mapping: WorkspaceVisualSourceMapping;
+}
+export interface WorkspaceSourceReconcileInput {
+    target: WorkspaceTarget;
+    baseline: WorkspaceSourceBaseline;
+    document: DesignDocument;
+}
+/** A host proves current bytes and explicit source identities before proposing a merge. */
+export type WorkspaceSourceReconcileResult = {
+    status: 'ready';
+    baseline: WorkspaceSourceBaseline;
+    document: DesignDocument;
+} | {
+    status: 'conflict';
+    diagnostics: readonly WorkspaceVisualSourceDiagnostic[];
+};
+export interface WorkspaceInspectSourceRequest {
+    sourceKind?: never;
+    /** The controller supplies a detached, deeply frozen capture to every host callback. */
+    target: WorkspaceTarget;
+    document: DesignDocument;
+    identity: WorkspaceVisualSourceIdentity;
+    payload: InspectApplyPayload;
+}
+export interface WorkspaceFileSourceRequest {
+    sourceKind: 'file-plan';
+    target: WorkspaceTarget;
+    document: DesignDocument;
+    identity: WorkspaceVisualSourceIdentity;
+    payload: SourceFilePlan;
+}
+export type WorkspaceSourceRequest = WorkspaceInspectSourceRequest | WorkspaceFileSourceRequest;
+/** Product source ownership stays in the host; review and stale-state policy stay in the editor.
+ * A controller captures these callbacks once. Replace the controller when capabilities change.
+ * Aborting an apply does not prove that a host-side write was rolled back; its promise must settle.
+ */
+export interface WorkspaceSourceCapabilities {
+    loadSource(target: WorkspaceTarget, options: {
+        signal: AbortSignal;
+    }): Promise<WorkspaceSourceBaseline>;
+    /** Refresh a working copy at the same commit. Revision switches require a new target and renderer. */
+    reconcileSource?(input: WorkspaceSourceReconcileInput, options: {
+        signal: AbortSignal;
+    }): Promise<WorkspaceSourceReconcileResult>;
+    /** Compile a complete validated document change against server-owned source bytes. */
+    compileSource?(input: {
+        target: WorkspaceTarget;
+        baseline: WorkspaceSourceBaseline;
+        document: DesignDocument;
+    }, options: {
+        signal: AbortSignal;
+    }): Promise<SourceFilePlan>;
+    previewSource(request: WorkspaceSourceRequest, options: {
+        signal: AbortSignal;
+    }): Promise<InspectPreviewResult>;
+    applySource(request: WorkspaceSourceRequest, options: {
+        signal: AbortSignal;
+    }): Promise<InspectApplyResult>;
+    /** Build an isolated artifact for the exact reviewed document without publishing source. */
+    preparePreview?(request: WorkspaceSourceRequest, options: {
+        signal: AbortSignal;
+        documentRevision: string;
+    }): Promise<WorkspaceApplicationSurface>;
+}

package/dist-lib/types/workspace/source/prototypeSource.d.ts

@@ -0,0 +1,4 @@
+import type { DesignDocument } from '../../document/contracts.js';
+import type { WorkspaceVisualSourceDiagnostic } from './contracts.js';
+/** The prototype runtime is a draft feature; no source-action mapping is declared by this SDK yet. */
+export declare function prototypeSourceDiagnostics(after: DesignDocument, before: DesignDocument): WorkspaceVisualSourceDiagnostic[];

package/dist-lib/types/workspace/source/responsive.d.ts

@@ -0,0 +1,13 @@
+import type { ResponsiveLayoutDeclarations, ResponsiveLayoutDocument, ResponsiveLayoutProperty, ResponsiveLayoutRange, WorkspaceResponsiveSourceCompileInput, WorkspaceResponsiveSourceCompileResult } from './responsiveContracts.js';
+/** Only the responsive sidecar may differ. The caller composes other validated source compilers. */
+export declare function compileWorkspaceResponsiveSource(input: WorkspaceResponsiveSourceCompileInput): WorkspaceResponsiveSourceCompileResult;
+/** Authored media overrides resolve over the authored base, without mutating scene geometry. */
+export declare function resolveResponsiveLayout(document: ResponsiveLayoutDocument, nodeId: string, width: number): ResponsiveLayoutDeclarations;
+/** The returned sidecar is suitable for one existing DocumentEngine metadata transaction. */
+export declare function setResponsiveLayoutOverride(state: ResponsiveLayoutDocument, nodeId: string, rangeId: string, property: ResponsiveLayoutProperty, value: string | undefined): ResponsiveLayoutDocument;
+/** Breakpoint order for a range catalog: base first, then max-width ranges by descending width, then min-width ranges by ascending width. */
+export declare function sortResponsiveRanges<T extends ResponsiveLayoutRange>(ranges: readonly T[]): T[];
+/** A preview width that resolves to the selected range; the base range needs a width no media range covers. */
+export declare function responsiveRangePreviewWidth(ranges: readonly ResponsiveLayoutRange[], rangeId: string, preferred?: number): number;
+/** One sentence a panel can show next to a rejected value. */
+export declare function describeResponsiveValueContract(property: string, permitted?: readonly string[]): string;

package/dist-lib/types/workspace/source/responsiveContracts.d.ts

@@ -0,0 +1,78 @@
+import type { DesignDocument } from '../../document/contracts.js';
+import type { InspectApplyPayload, SourceAffectedFrame } from '../../editor/inspect.js';
+import type { WorkspaceTarget } from '../contracts.js';
+import type { WorkspaceSourceFileProof, WorkspaceVisualSourceDiagnostic } from './contracts.js';
+/**
+ * Flex controls require a flex source container. Sizing constraints and `display` do not.
+ * `display` models a collapsed state only: a media range declares `none`; the base keeps the source display.
+ */
+export type ResponsiveLayoutProperty = 'flex-direction' | 'flex-wrap' | 'align-items' | 'justify-content' | 'gap' | 'padding' | 'width' | 'height' | 'min-width' | 'max-width' | 'min-height' | 'max-height' | 'display';
+export type ResponsiveLayoutDeclarations = Partial<Record<ResponsiveLayoutProperty, string>>;
+/** The host certifies the numeric range and source directive have equivalent semantics. */
+export type ResponsiveRangeSource = {
+    kind: 'media';
+} | {
+    kind: 'scss-include';
+    name: string;
+    argument: string;
+    proofFile: string;
+};
+export type ResponsiveLayoutRange = {
+    id: string;
+    label: string;
+    /**
+     * The first range is base, without media or source. Remaining ranges do not overlap and follow
+     * breakpoint order: max-width ranges by descending width, then bounded and min-width ranges by
+     * ascending minimum width. One proven mixin maps to one range; a host declares several ranges by
+     * pairing each with its own mixin and variable (for example a max-width mixin and a min-width mixin
+     * with different variables) or with an explicit media rule.
+     */
+    media?: {
+        minWidth?: number;
+        maxWidth?: number;
+    };
+    source?: ResponsiveRangeSource;
+};
+/** Canonical authored CSS values. Canvas bounds and generated geometry are never source values. */
+export type ResponsiveLayoutDocument = {
+    version: 1;
+    ranges: ResponsiveLayoutRange[];
+    styles: Record<string, Record<string, ResponsiveLayoutDeclarations>>;
+};
+export interface ResponsiveLayoutSourceTarget {
+    nodeId: string;
+    file: string;
+    className: string;
+    componentFile: string;
+    affectedFrames: readonly SourceAffectedFrame[];
+    /** Every admitted property must have an authored base declaration in the source snapshot. */
+    properties: readonly ResponsiveLayoutProperty[];
+    /** Token and expression spellings are admitted only by an explicit host allowlist. */
+    permittedValues?: Partial<Record<ResponsiveLayoutProperty, readonly string[]>>;
+}
+export interface WorkspaceResponsiveSourceMapping {
+    version: 1;
+    target: WorkspaceTarget;
+    documentId: string;
+    baselineFingerprint: string;
+    files: readonly WorkspaceSourceFileProof[];
+    ranges: readonly ResponsiveLayoutRange[];
+    targets: readonly ResponsiveLayoutSourceTarget[];
+}
+export interface WorkspaceResponsiveSourceCompileInput {
+    target: WorkspaceTarget;
+    before: DesignDocument;
+    after: DesignDocument;
+    mapping: WorkspaceResponsiveSourceMapping;
+}
+export type WorkspaceResponsiveSourceCompileResult = {
+    status: 'ready';
+    payload: InspectApplyPayload;
+    before: ResponsiveLayoutDocument;
+    after: ResponsiveLayoutDocument;
+} | {
+    status: 'unchanged';
+} | {
+    status: 'blocked';
+    diagnostics: readonly WorkspaceVisualSourceDiagnostic[];
+};

package/dist-lib/types/workspace/source/structure.d.ts

@@ -0,0 +1,21 @@
+import type { InspectApplyPayload } from '../../editor/inspect.js';
+import type { WorkspaceStructureSourceOperation, WorkspaceVisualSourceCompileInput, WorkspaceVisualSourceDiagnostic } from './contracts.js';
+/** The CSS module class a wrapper group compiles to, so hosts can address an applied wrapper without re-deriving it. */
+export declare const jsxStructureWrapperClassName: (groupId: string) => string | null;
+export type WorkspaceDocumentSourceChanges = {
+    status: 'ready';
+    operations: WorkspaceStructureSourceOperation[];
+    visualPayload?: InspectApplyPayload;
+} | {
+    status: 'unchanged';
+    operations: readonly [];
+} | {
+    status: 'blocked';
+    diagnostics: readonly WorkspaceVisualSourceDiagnostic[];
+};
+/**
+ * Plan a complete document delta. Intrinsic leaves keep their source expressions,
+ * dimensions and content; only hierarchy, source groups and their declared layouts change.
+ * The Node compiler subsequently proves every source range against the AST.
+ */
+export declare function compileWorkspaceDocumentSource(input: WorkspaceVisualSourceCompileInput): WorkspaceDocumentSourceChanges;

package/dist-lib/types/workspace/source/textSource.d.ts

@@ -0,0 +1,28 @@
+import type { DesignDocument, DocumentNode } from '../../document/contracts.js';
+import type { WorkspaceVisualSourceDiagnostic } from './contracts.js';
+import { type RichTextCharacterKey, type RichTextParagraphKey } from '../../document/richText.js';
+/**
+ * The visual compiler edits static JSX text through `properties.text` and node-level `fontSize`/`color`
+ * through stylesheet rules. This module decides whether a text node still fits that plain path.
+ */
+export declare const TEXT_SOURCE_MAPPED_PROPERTIES: readonly string[];
+export type RichTextSourceProjection = {
+    kind: 'plain';
+    text: string; /** Node-level typography with no visual source rule; the draft keeps it. */
+    unmappedStyleFields: readonly string[];
+} | {
+    kind: 'blocked';
+    reason: string;
+    text: string;
+    varying: {
+        character: readonly RichTextCharacterKey[];
+        paragraph: readonly RichTextParagraphKey[];
+    };
+};
+/** Plain when the existing `properties.text` rule can carry the node; blocked, with the reason, when a range differs from the layer. */
+export declare function richTextSourceProjection(node: DocumentNode): RichTextSourceProjection;
+/**
+ * Diagnostics the source review can show before the visual compiler reports a generic unmapped field.
+ * With a baseline, only nodes whose typography changed are reported; without one, every text node is checked.
+ */
+export declare function richTextSourceDiagnostics(after: DesignDocument, before?: DesignDocument): WorkspaceVisualSourceDiagnostic[];

package/dist-lib/types/workspace/tokens/TokenLibraryContext.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+import { WorkspaceTokenLibraryController } from './controller.js';
+import type { WorkspaceTokenLibraryCapabilities } from './contracts.js';
+export declare const useTokenLibraryController: () => WorkspaceTokenLibraryController | null;
+export declare const useHasTokenLibraryProvider: () => boolean;
+/** One effect-owned controller spans the Variables dialog and document inspector. */
+export declare function TokenLibraryProvider({ sourceRevision, capabilities, children }: {
+    sourceRevision: string;
+    capabilities?: WorkspaceTokenLibraryCapabilities;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist-lib/types/workspace/tokens/TokenLibraryWorkspace.d.ts

@@ -0,0 +1,14 @@
+import type { RefObject } from 'react';
+import type { EditorRuntime } from '../../core/runtime.js';
+import type { WorkspaceTarget } from '../contracts.js';
+import type { WorkspaceTokenLibraryCapabilities } from './contracts.js';
+
+export interface TokenLibraryWorkspaceProps {
+    runtime: EditorRuntime;
+    sourceRevision: string;
+    capabilities: WorkspaceTokenLibraryCapabilities;
+    target?: WorkspaceTarget;
+    workspaceRoot: RefObject<HTMLDivElement | null>;
+}
+/** The owner is recreated by effects so StrictMode cleanup never reuses a disposed controller. */
+export declare function TokenLibraryWorkspace(props: TokenLibraryWorkspaceProps): import("react").JSX.Element;

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

@@ -0,0 +1,74 @@
+import type { VariableValueCodec } from '../../token-library/bindings.js';
+import type { TokenLibraryDiagnostic, TokenLibraryDocument, TokenValue } from '../../token-library/contracts.js';
+import type { SourceFilePlan } from '../../host/sourceFilePlan.js';
+import type { InspectApplyResult, InspectPreviewResult } from '../../editor/host.js';
+import type { WorkspaceApplicationSurface, WorkspaceTarget } from '../contracts.js';
+export interface WorkspaceTokenLibraryBaseline {
+    document: TokenLibraryDocument;
+    /** Captures token declarations, generator configuration, and the consumer inventory. */
+    proofs: SourceFilePlan['proofs'];
+}
+export interface WorkspaceFileSourceIdentity {
+    version: 1;
+    target: WorkspaceTarget;
+    documentId: string;
+    beforeFingerprint: string;
+    afterFingerprint: string;
+    mappingFingerprint: string;
+    payloadFingerprint: string;
+    fingerprint: string;
+}
+/** Shared-library changes are independent of a screen's visual document draft. */
+export interface WorkspaceTokenSourceRequest {
+    sourceKind: 'file-plan';
+    target: WorkspaceTarget;
+    document: TokenLibraryDocument;
+    identity: WorkspaceFileSourceIdentity;
+    payload: SourceFilePlan;
+}
+export interface WorkspaceTokenLibraryCapabilities {
+    loadLibrary(sourceRevision: string, options: {
+        signal: AbortSignal;
+    }): Promise<WorkspaceTokenLibraryBaseline>;
+    loadDraft?(baseline: WorkspaceTokenLibraryBaseline, options: {
+        signal: AbortSignal;
+    }): Promise<string | null>;
+    saveDraft?(document: TokenLibraryDocument): Promise<void>;
+    /** Host codecs preserve the native value type and actual reference syntax. */
+    parseValue(document: TokenLibraryDocument, text: string, context: {
+        tokenId?: string;
+        modeId: string;
+        collectionId?: string;
+        type?: string;
+        format?: string;
+    }): TokenValue;
+    formatValue(document: TokenLibraryDocument, value: TokenValue): string;
+    /** Converts host token syntax to a scalar for document property bindings. */
+    resolveBindingValue?: VariableValueCodec;
+    /** Optional types for an empty collection; existing declared types are the fallback. */
+    availableTypes?(document: TokenLibraryDocument, collectionId: string): readonly string[];
+    canAuthorMode?(collectionId: string, modeId: string): boolean;
+    validateChange?(before: TokenLibraryDocument, after: TokenLibraryDocument): readonly TokenLibraryDiagnostic[];
+    /** Computed custom properties for the actual component canvas, never document-root overrides. */
+    previewVariables?(document: TokenLibraryDocument, modeId: string): readonly {
+        name: string;
+        value: string;
+    }[];
+    compileSource(input: {
+        baseline: WorkspaceTokenLibraryBaseline;
+        document: TokenLibraryDocument;
+    }, options: {
+        signal: AbortSignal;
+    }): Promise<SourceFilePlan>;
+    previewSource(request: WorkspaceTokenSourceRequest, options: {
+        signal: AbortSignal;
+    }): Promise<InspectPreviewResult>;
+    applySource(request: WorkspaceTokenSourceRequest, options: {
+        signal: AbortSignal;
+    }): Promise<InspectApplyResult>;
+    preparePreview?(request: WorkspaceTokenSourceRequest, options: {
+        signal: AbortSignal;
+        documentRevision: string;
+        modeId: string;
+    }): Promise<WorkspaceApplicationSurface>;
+}