@pygmalionjs/pygmalion 0.15.0 → 0.17.0

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

@@ -34,6 +34,7 @@ export interface RasterExportRequest {
     height: number;
     scale: number;
     contentsOnly: boolean;
+    signal?: AbortSignal;
 }
 export type RasterExportRenderer = (request: RasterExportRequest) => Promise<Uint8Array>;
 export interface DesignExportArtifact {
@@ -42,4 +43,6 @@ export interface DesignExportArtifact {
     bytes: Uint8Array;
 }
 /** Raster bytes come only from an explicit host renderer; no hidden capture or network access. */
-export declare function exportDesignNode(document: DesignDocument, nodeId: string, setting: ExportSetting, renderer?: RasterExportRenderer): Promise<DesignExportArtifact>;
+export declare function exportDesignNode(document: DesignDocument, nodeId: string, setting: ExportSetting, renderer?: RasterExportRenderer, options?: {
+    signal?: AbortSignal;
+}): Promise<DesignExportArtifact>;

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

@@ -183,3 +183,13 @@ export declare function fontFaceSetLoader(fonts: {
 } | undefined | null): TextFontLoader | null;
 /** A convenience for text nodes: the node's own font needs. */
 export declare function textNodeFontRequirements(node: DocumentNode): TextFontRequirement[];
+/** An exact preparation request. A missing family remains unresolved; no default is guessed. */
+export interface TextFontFaceRequest {
+    readonly family: string | null;
+    readonly weight: number;
+    readonly style: 'normal' | 'italic';
+    /** Written sample in UTF-16. Rendered case or connected substitutions require explicit resolution. */
+    readonly sample: string;
+}
+/** Preserves family expressions and sample bytes, keeping weight/style/sample combinations distinct. */
+export declare function textFontFaceRequests(model: RichText, base?: TextNodeCharacterStyle): readonly TextFontFaceRequest[];

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

@@ -0,0 +1,36 @@
+import type { TextFontFaceRequest } from './richText.js';
+export type TextFontFaceResult = {
+    readonly status: 'ready';
+    readonly faceId: string;
+    readonly family: string;
+    readonly weight: number;
+    readonly style: 'normal' | 'italic';
+    readonly sample: string;
+} | {
+    readonly status: 'unavailable';
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly status: 'failed';
+    readonly code: string;
+    readonly message: string;
+};
+/** The provider explicitly attests to the exact face and sample coverage in this environment. */
+export interface TextFontFaceResolver {
+    readonly environmentId: string;
+    resolve(request: TextFontFaceRequest, context: {
+        readonly signal: AbortSignal;
+    }): Promise<TextFontFaceResult>;
+}
+export interface PreparedTextFont {
+    readonly request: TextFontFaceRequest;
+    readonly result: TextFontFaceResult;
+}
+export interface TextFontPreparationReport {
+    readonly environmentId: string;
+    readonly status: 'ready' | 'unavailable' | 'failed';
+    readonly fonts: readonly PreparedTextFont[];
+}
+export declare function textFontRequestKey(request: TextFontFaceRequest): string;
+/** Invalid provider attestations fail closed; a fallback or a different sample is not a ready face. */
+export declare function validateTextFontFaceResult(request: TextFontFaceRequest, result: TextFontFaceResult): TextFontFaceResult;

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

@@ -55,8 +55,15 @@ export { planScopeTransfer, resolveScopeTransfer, applyScopeTransfer } from './w
 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 { 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, textFontFaceRequests, } from './document/richText.js';
 export type * from './document/richText.js';
+export * from './document/textFontPreparation.js';
+export { createTextFontPreparationRuntime } from './workspace/edit/textFontRuntime.js';
+export type { TextFontPreparationRuntime } from './workspace/edit/textFontRuntime.js';
+export { collectTextFontOccurrences, textFontAddressKey } from './workspace/edit/textFontOccurrences.js';
+export type { TextFontAddress, TextFontOccurrence, TextFontCollection, TextFontCollectionOptions } from './workspace/edit/textFontOccurrences.js';
+export { useTextFontPreparation } from './workspace/edit/useTextFontPreparation.js';
+export type { TextFontPreparationState } from './workspace/edit/useTextFontPreparation.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';
@@ -438,4 +445,5 @@ export type { PrototypeInputFrame } from './workspace/view/prototypeInputFrame.j
 export { createPrototypeProjectionContext } from './workspace/edit/prototypeProjection.js';
 export type { PrototypeProjectionContext } from './workspace/edit/prototypeProjection.js';
 export * from './workspace/edit/rasterExport.js';
+export type { PreparedTextRasterFaceReference, TextRasterFaceResolver } from './workspace/edit/staticTextRaster.js';
 export * from './document/imagePaintGeometry.js';

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

@@ -4,11 +4,17 @@ import type { DesignDocument, DocumentNode, DocumentDuplicateMetadataRemapper }
 import type { WorkspaceSourceCapabilities } from './source/flowContracts.js';
 import type { WorkspaceTarget } from './contracts.js';
 import type { WorkspaceTokenLibraryCapabilities } from './tokens/contracts.js';
+import type { TextFontPreparationRuntime } from './edit/textFontRuntime.js';
+import type { TextRasterFaceResolver } from './edit/staticTextRaster.js';
 /** One target's source, data, rendering, and persistence capabilities travel together. */
 export interface WorkspaceTargetConfiguration {
     data?: HostDataCapabilities;
     source?: WorkspaceSourceCapabilities;
     duplicateMetadata?: DocumentDuplicateMetadataRemapper;
+    /** Explicit font face and sample preparation; browser fallback rendering is not exact readiness. */
+    textFontPreparation?: TextFontPreparationRuntime;
+    /** Bind a prepared face identity to its exact registered browser FontFace for static text output. */
+    textRasterFaceResolver?: TextRasterFaceResolver;
     loadDocument?(target: WorkspaceTarget, options: {
         signal: AbortSignal;
     }): Promise<DesignDocument>;

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

@@ -10,8 +10,10 @@ export interface AssetsPanelProps {
     onSelect?: (nodeId: string) => void;
     onExport?: (artifact: DesignExportArtifact) => void | Promise<void>;
     rasterRenderer?: RasterExportRenderer;
+    lifetimeKey?: string;
+    subscribeLifetime?: (invalidate: () => void) => () => void;
     disabled?: boolean;
 }
-export declare function AssetsPanel({ engine, pageId, parentId, selectedNodeId, allocateId, onSelect, onExport, rasterRenderer, disabled }: AssetsPanelProps): import("react").JSX.Element;
+export declare function AssetsPanel({ engine, pageId, parentId, selectedNodeId, allocateId, onSelect, onExport, rasterRenderer, lifetimeKey, subscribeLifetime, disabled }: AssetsPanelProps): import("react").JSX.Element;
 /** Explicit local download callback for the panel; raster output still needs a separate host renderer. */
 export declare function downloadDesignArtifact(artifact: DesignExportArtifact): void;

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

@@ -1,10 +1,12 @@
 import type { DocumentEngine } from '../../document/contracts.js';
 import { type DesignExportArtifact, type RasterExportRenderer } from '../../document/exportSettings.js';
 /** The inspector and asset browser share one persisted export-settings editor. */
-export declare function NodeExportPanel({ engine, nodeId, onExport, rasterRenderer, disabled }: {
+export declare function NodeExportPanel({ engine, nodeId, onExport, rasterRenderer, disabled, lifetimeKey, subscribeLifetime }: {
     engine: DocumentEngine;
     nodeId?: string;
     onExport?(artifact: DesignExportArtifact): void | Promise<void>;
     rasterRenderer?: RasterExportRenderer;
     disabled?: boolean;
+    lifetimeKey?: string;
+    subscribeLifetime?: (invalidate: () => void) => () => void;
 }): import("react").JSX.Element;

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

@@ -1,5 +1,7 @@
 import type { DesignDocument, DocumentNode, DocumentTransaction } from '../../document/contracts.js';
 import { type TextFontLoader, type TextFontLoadReport } from '../../document/richText.js';
+import type { TextFontPreparationRuntime } from './textFontRuntime.js';
+import type { TextFontCollection } from './textFontOccurrences.js';
 
 type Act = (label: string, apply: (transaction: DocumentTransaction) => void) => boolean;
 /**
@@ -40,11 +42,15 @@ export interface TextEditorProps {
     connected?: boolean;
     /** Resolves required faces; the browser font set when omitted, no loading when null. */
     fontLoader?: TextFontLoader | null;
+    /** Optional exact face preparation; legacy loading stays separate. */
+    fontPreparation?: TextFontPreparationRuntime | null;
+    /** The selected resolved occurrence, including projected sample and overrides when relevant. */
+    fontCollection?: TextFontCollection;
 }
 /**
  * Inspector section for a text node. The written text is edited in a textarea whose selection decides
  * whether a style applies to a character range or to the whole layer. Every committed edit is one
  * document transaction; Escape discards the uncommitted draft.
  */
-export declare function TextEditor({ document, node, act, connected, fontLoader }: TextEditorProps): import("react").JSX.Element;
+export declare function TextEditor({ document, node, act, connected, fontLoader, fontPreparation, fontCollection }: TextEditorProps): import("react").JSX.Element;
 export {};

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

@@ -0,0 +1,6 @@
+import type { DesignDocument } from '../../document/contracts.js';
+
+/** Browse authored style metadata without selecting a layer or requesting fonts. */
+export declare function TextStyleCatalog({ document }: {
+    document: DesignDocument;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,6 @@
+import type { RasterExportRequest } from '../../document/exportSettings.js';
+export declare function assertRasterActive(signal?: AbortSignal): void;
+export declare function validateRasterSize(request: Pick<RasterExportRequest, 'width' | 'height'>): void;
+/** Cancellation ends this reader even if a browser decode or encode cannot be interrupted internally. */
+export declare function awaitRasterActive<T>(work: Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function encodeRasterCanvas(canvas: HTMLCanvasElement, format: RasterExportRequest['format'], signal?: AbortSignal): Promise<Uint8Array>;

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

@@ -1,5 +1,13 @@
+import { type TextRasterFaceResolver } from './staticTextRaster.js';
+import type { TextFontPreparationRuntime } from './textFontRuntime.js';
 import { type RasterExportRenderer, type RasterExportRequest } from '../../document/exportSettings.js';
 /** The same supported SVG geometry supplies browser raster output; unsupported visuals stay explicit. */
 export declare function rasterExportSvg(request: RasterExportRequest): string;
-/** Explicit browser renderer for supported geometry. It never captures a page or fetches external resources. */
+/** Adds bounded authored text output only when an explicit exact-face provider is available. */
+export declare function createDesignRasterRenderer(options?: {
+    textFontPreparation?: TextFontPreparationRuntime;
+    sourceMapped?: boolean;
+    resolvePreparedFace?: TextRasterFaceResolver;
+}): RasterExportRenderer;
+/** Backward-compatible geometry renderer. Exact text output is explicitly enabled through the factory. */
 export declare const renderDesignRaster: RasterExportRenderer;

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

@@ -0,0 +1,50 @@
+import { type RasterExportRequest } from '../../document/exportSettings.js';
+import { type TextFontFaceRequest } from '../../document/richText.js';
+import type { TextFontPreparationRuntime } from './textFontRuntime.js';
+export interface PreparedTextRasterFaceReference {
+    readonly environmentId: string;
+    readonly faceId: string;
+    readonly family: string;
+    readonly weight: number;
+    readonly style: 'normal' | 'italic';
+    readonly sample: string;
+}
+/** The owner maps its exact prepared identity to the same FontFace object registered for drawing. */
+export type TextRasterFaceResolver = (reference: PreparedTextRasterFaceReference) => FontFace | undefined;
+export interface StaticTextRasterPlan {
+    readonly nodeId: string;
+    readonly width: number;
+    readonly height: number;
+    readonly outputWidth: number;
+    readonly outputHeight: number;
+    readonly font: TextFontFaceRequest;
+    readonly fontSize: number;
+    readonly lineHeight: number;
+    readonly align: 'start' | 'center' | 'end';
+    readonly color: string;
+    readonly opacity: number;
+}
+/** The first text raster slice is a single authored, fixed-size, undecorated line with explicit typography. */
+export declare function createStaticTextRasterPlan(request: RasterExportRequest, options?: {
+    sourceMapped?: boolean;
+}): StaticTextRasterPlan;
+/** Registered face descriptors must support the requested style and weight without synthesis. */
+export declare function supportsStaticTextFace(face: Pick<FontFace, 'family' | 'style' | 'weight' | 'stretch' | 'status'>, family: string, request: TextFontFaceRequest): boolean;
+/** Registered unicode-range restrictions are distinct from the provider's glyph-coverage attestation. */
+export declare function staticTextFaceCoversSample(unicodeRange: string, sample: string): boolean;
+/** Matches the SVG renderer's default xMidYMid meet behavior after output dimension rounding. */
+export declare function staticTextRasterViewport(plan: Pick<StaticTextRasterPlan, 'width' | 'height' | 'outputWidth' | 'outputHeight'>): {
+    scale: number;
+    x: number;
+    y: number;
+};
+/** Measures the same pre-wrap line box as TextNodeSurface, using a zero-height inline baseline marker. */
+export declare function measureStaticTextRaster(plan: StaticTextRasterPlan, family: string, owner: Document): {
+    x: number;
+    baseline: number;
+};
+/** A ready explicit provider plus a registered browser face is required; platform fallback checks are insufficient. */
+export declare function renderStaticTextRaster(request: RasterExportRequest, runtime: TextFontPreparationRuntime, options?: {
+    sourceMapped?: boolean;
+    resolvePreparedFace?: TextRasterFaceResolver;
+}): Promise<Uint8Array>;

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

@@ -0,0 +1,34 @@
+import type { DesignDocument, DocumentResolveOptions } from '../../document/contracts.js';
+import type { DataProjection } from '../../binding/preview.js';
+import { type TextFontFaceRequest } from '../../document/richText.js';
+import { type ProjectedDocumentNode } from './projection.js';
+export interface TextFontAddress {
+    readonly sourceNodeId: string;
+    readonly instancePath: readonly string[];
+    readonly rowPath: ProjectedDocumentNode['rowPath'];
+}
+export interface TextFontOccurrence extends TextFontAddress {
+    readonly origin: 'authored' | 'source' | 'bound';
+    readonly requests: readonly TextFontFaceRequest[];
+}
+export interface TextFontCollection {
+    readonly occurrences: readonly TextFontOccurrence[];
+    readonly diagnostics: readonly {
+        readonly code: string;
+        readonly message: string;
+        readonly address?: TextFontAddress;
+    }[];
+}
+export interface TextFontCollectionOptions {
+    readonly projection?: DataProjection | null;
+    readonly resolveOptions?: DocumentResolveOptions;
+    /** Supply the same resolved scene the canvas uses, when it has custom resolution. */
+    readonly scene?: ProjectedDocumentNode;
+    readonly visibleRootIds?: readonly string[];
+    readonly subtree?: TextFontAddress;
+    /** Required for connected/source content or case-transformed samples. It must describe rendered text. */
+    readonly resolveText?: (item: ProjectedDocumentNode, address: TextFontAddress) => string | undefined;
+}
+export declare const textFontAddressKey: (address: TextFontAddress) => string;
+/** Read-only effective occurrences; hidden pages/rows and unselected shared definitions do not preload. */
+export declare function collectTextFontOccurrences(document: DesignDocument, options?: TextFontCollectionOptions): TextFontCollection;

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

@@ -0,0 +1,15 @@
+import { type TextFontFaceResolver, type TextFontPreparationReport } from '../../document/textFontPreparation.js';
+import type { TextFontFaceRequest } from '../../document/richText.js';
+export interface TextFontPreparationRuntime {
+    readonly environmentId: string;
+    prepare(requests: readonly TextFontFaceRequest[], options?: {
+        signal?: AbortSignal;
+        retry?: boolean;
+    }): Promise<TextFontPreparationReport>;
+    clear(): void;
+    dispose(): void;
+}
+/** A bounded successful-result cache with shared in-flight work and independently cancellable readers. */
+export declare function createTextFontPreparationRuntime(resolver: TextFontFaceResolver, options?: {
+    maxEntries?: number;
+}): TextFontPreparationRuntime;

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

@@ -0,0 +1,12 @@
+import type { DesignDocument, DocumentNode } from '../../document/contracts.js';
+import type { TextFontPreparationReport } from '../../document/textFontPreparation.js';
+import { type TextFontCollection } from './textFontOccurrences.js';
+import type { TextFontPreparationRuntime } from './textFontRuntime.js';
+export interface TextFontPreparationState {
+    readonly status: 'idle' | 'loading' | 'ready' | 'unavailable' | 'failed';
+    readonly messages: readonly string[];
+    readonly report?: TextFontPreparationReport;
+    retry(): void;
+}
+/** Exact readiness is opt-in; legacy font-set loading never becomes an identity attestation. */
+export declare function useTextFontPreparation(document: DesignDocument, node: DocumentNode, runtime?: TextFontPreparationRuntime | null, supplied?: TextFontCollection): TextFontPreparationState;

package/dist-lib/types/workspace/view/prototypeMotionInterruption.d.ts

@@ -30,8 +30,18 @@ export interface PrototypeInterruptedTiming {
 }
 /** One shared timing table per interrupted transition, never one solver per layer/channel. */
 export declare function createPrototypeInterruptedTiming(transition: PrototypeTransition, durationMs: number): PrototypeInterruptedTiming;
-/** Existing computed 2D/px/RGB tracks only. Unsupported values retain explicit diagnostics. */
-export declare function createPrototypeInterruptedFrames(captured: PrototypeMotionCapture, target: Partial<PrototypeMotionStyles>, timing: PrototypeInterruptedTiming): {
+interface PrototypeInterruptedFrames {
     frames: Keyframe[];
     unsupported: PrototypeMotionProperty[];
-};
+}
+interface PrototypeInterruptedFramePlannerOptions {
+    maxTracks?: number;
+    maxBytes?: number;
+}
+/** A single preparation pass owns this cache; it retains no DOM, captures or animation records.
+ * Limits bound cached track count and UTF-16 string payload bytes, not total JavaScript heap size.
+ * Returned frames are detached even when their immutable property strings are reused. */
+export declare function createPrototypeInterruptedFramePlanner(inputTiming: PrototypeInterruptedTiming, options?: PrototypeInterruptedFramePlannerOptions): (captured: PrototypeMotionCapture, target: Partial<PrototypeMotionStyles>) => PrototypeInterruptedFrames;
+/** Existing computed 2D/px/RGB tracks only. Unsupported values retain explicit diagnostics. */
+export declare function createPrototypeInterruptedFrames(captured: PrototypeMotionCapture, target: Partial<PrototypeMotionStyles>, timing: PrototypeInterruptedTiming): PrototypeInterruptedFrames;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {