@fulate/ui 1.0.0

package/dist/text/editing.d.ts

@@ -0,0 +1,16 @@
+import type { PointView } from "@fulate/share";
+import type { Text } from "./index";
+import type { ContentEditingConsumer } from "../editor/capability";
+declare const SELECTION_COLOR = "rgba(66, 133, 244, 0.3)";
+export { SELECTION_COLOR };
+export declare function getCaretLocalXY(self: Text, caretIndex: number): {
+    x: number;
+    y: number;
+    h: number;
+};
+export declare function syncEditingText(self: Text, value: string): void;
+export declare function enterEditing(self: Text, initialClickLocal?: PointView, consumer?: ContentEditingConsumer | null): void;
+export declare function requestEditingFinish(self: Text): void;
+export declare function closeEditing(self: Text): void;
+export declare const exitEditing: typeof requestEditingFinish;
+export declare function setupClickToEdit(self: Text): (() => void) | null;

package/dist/text/index.d.ts

@@ -0,0 +1,149 @@
+import { ChangeImpact, type ElementTransformClass, type GeometrySnapshot, type Layer, type PropertyChanges, type Root, type ShadowOption } from "@fulate/core";
+import { Rectangle, RectangleProperties, RectangleTransform, type RectangleOption } from "../rectangle";
+import { type BackgroundColor, type PointView, type Rect } from "@fulate/share";
+import { type TextLineBoxMetrics } from "./paint";
+import { TEXT_STYLE_DEFAULTS, type TextStyleKey, type TextStyleConfig, type ResolvedTextStyle, buildFontString } from "./style";
+import { type ContentEditingConsumer, type ContentEditingSession, type EditorCapabilityToken } from "../editor/capability";
+export type { TextStyleConfig, TextStyleKey, ResolvedTextStyle };
+export { buildFontString, TEXT_STYLE_DEFAULTS };
+export { measureTextRun } from "./paint";
+export type { TextLineBoxMetrics, TextRunMetrics } from "./paint";
+/**
+ * Text uses its intrinsic text size when width/height are omitted. Supplying a
+ * width constrains wrapping; `wordWrap`, `ellipsis`, and `overflow` are
+ * independent. By default text does not wrap, truncate, or clip.
+ */
+export interface TextOption<T = Text> extends RectangleOption<T> {
+    text?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    fontStyle?: string;
+    color?: BackgroundColor;
+    textAlign?: "left" | "center" | "right";
+    textBaseline?: CanvasTextBaseline;
+    verticalAlign?: "top" | "middle" | "bottom";
+    underline?: boolean;
+    strikethrough?: boolean;
+    lineHeight?: number;
+    wordWrap?: boolean;
+    /** 单行或最后可见行放不下时是否绘制省略号；与 `wordWrap`、`overflow` 独立。 */
+    ellipsis?: boolean;
+    maxLines?: number;
+    editable?: boolean;
+    placeholder?: string;
+    placeholderColor?: string;
+    letterSpacing?: number;
+    textStrokeColor?: BackgroundColor;
+    textStrokeWidth?: number;
+    textShadow?: ShadowOption | null;
+}
+export declare class TextProperties extends RectangleProperties {
+    text: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    fontStyle?: string;
+    color?: BackgroundColor;
+    textAlign?: "left" | "center" | "right";
+    textBaseline?: CanvasTextBaseline;
+    verticalAlign?: "top" | "middle" | "bottom";
+    underline?: boolean;
+    strikethrough?: boolean;
+    lineHeight?: number;
+    wordWrap?: boolean;
+    ellipsis: boolean;
+    maxLines?: number;
+    editable: boolean;
+    placeholder: string;
+    placeholderColor: string;
+    letterSpacing?: number;
+    textStrokeColor?: BackgroundColor;
+    textStrokeWidth?: number;
+    textShadow?: Readonly<ShadowOption> | null;
+    constructor(options?: TextOption);
+    getImpact(changes: PropertyChanges): ChangeImpact;
+}
+export declare class TextTransform<E extends Text = Text> extends RectangleTransform<E> {
+    protected resolveFitSize(): void;
+    protected buildVisualBounds(snapshot: GeometrySnapshot): Readonly<Rect> | null;
+    protected buildVisualOutline(snapshot: GeometrySnapshot): PointView[];
+}
+export declare class Text<P extends TextProperties = TextProperties, O extends TextOption<any> = TextOption<any>> extends Rectangle<P, O> {
+    readonly type = "text";
+    get text(): string;
+    get fontSize(): number;
+    get fontFamily(): string;
+    get fontWeight(): string | number;
+    get fontStyle(): string;
+    get color(): BackgroundColor;
+    get textAlign(): "left" | "center" | "right";
+    get textBaseline(): CanvasTextBaseline;
+    get verticalAlign(): "top" | "bottom" | "middle";
+    get underline(): boolean;
+    get strikethrough(): boolean;
+    get lineHeight(): number;
+    get wordWrap(): boolean;
+    get ellipsis(): boolean;
+    get maxLines(): number;
+    get editable(): boolean;
+    get placeholder(): string;
+    get placeholderColor(): string;
+    get letterSpacing(): number;
+    get textStrokeColor(): BackgroundColor;
+    get textStrokeWidth(): number;
+    get textShadow(): Readonly<ShadowOption>;
+    get isEditing(): boolean;
+    textarea: HTMLTextAreaElement | null;
+    editingConsumer: ContentEditingConsumer | null;
+    editAbort: AbortController | null;
+    editSubscriptionRemove: (() => void) | null;
+    caretVisible: boolean;
+    blinkTimer: ReturnType<typeof setInterval> | null;
+    composing: boolean;
+    scrollX: number;
+    selAnchor: number;
+    private clickToEditRemove;
+    private skinTextCommitRemove;
+    private textMeasurementRemove;
+    /** One resolved style snapshot; authored and Root skin changes invalidate it. */
+    private resolvedTextStyleCache;
+    private textLineBoxMetricsCache;
+    private readonly textBlock;
+    constructor(options?: NoInfer<O>, properties?: P, Transform?: ElementTransformClass);
+    getEditorCapability<T>(token: EditorCapabilityToken<T>): T | undefined;
+    beginContentEditing(consumer: ContentEditingConsumer): ContentEditingSession | undefined;
+    get fontString(): string;
+    getResolvedTextStyle(): ResolvedTextStyle;
+    getFontString(style?: Required<TextStyleConfig>): string;
+    get textLayout(): import("./layout").TextLayoutSnapshot;
+    /** @internal Shared by TextRow layout and the final Text painter. */
+    getTextLineBoxMetrics(text?: string): TextLineBoxMetrics;
+    /** @internal Alphabetic baseline relative to this Text box. */
+    getTextBlockFirstAlphabeticBaseline(): number;
+    /** @internal The editor frame follows the Text box, not visible overflow. */
+    getSelectionFrameBounds(): Readonly<Rect> | null;
+    get lines(): string[];
+    get lineCharOffsets(): readonly number[];
+    get textHeight(): number;
+    protected getLayoutWidth(): number;
+    protected getResolvedHeight(): number;
+    syncTextLayout(): void;
+    /** 布局 owner 提交 Text 自身的 intrinsic size；派生布局可覆写为只采用其 resolved frame。 */
+    protected commitTextLayoutSize(width: number | undefined, height: number | undefined): void;
+    /** @internal Shared by Yoga Span and the canvas Text owner. */
+    measureTextLayout(width: number, height?: number): import("./layout").TextLayoutMetrics;
+    /** @internal TextTransform 消费现有 Text layout owner 的 visual bounds。 */
+    getVisibleTextBounds(): Rect | null;
+    enterEditing(initialClickLocal?: PointView): void;
+    exitEditing(): void;
+    setEditingText(value: string): void;
+    protected onPropertiesChanged(current: P, changes: PropertyChanges): void;
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    private readonly handleTextMeasurementChanged;
+    /** @internal Layout owners such as Span use this to invalidate Yoga. */
+    protected onTextLayoutInvalidated(): void;
+    protected paintTextContent(ctx: CanvasRenderingContext2D, offsetY?: number): void;
+    protected paintContent(ctx: CanvasRenderingContext2D): void;
+}

package/dist/text/layout.d.ts

@@ -0,0 +1,101 @@
+import { type LayoutLine } from "@chenglou/pretext";
+export declare function subscribeTextMeasurementChanges(listener: () => void): () => boolean;
+export interface TextLayoutLine {
+    readonly text: string;
+    readonly width: number;
+    readonly ellipsized: boolean;
+}
+export interface TextLayoutOptions {
+    width: number;
+    height?: number;
+    lineHeight: number;
+    wordWrap: boolean;
+    maxLines?: number;
+    overflow: "hidden" | "visible";
+    /** 单行宽度溢出时是否使用同一测量引擎省略。 */
+    ellipsis?: boolean;
+}
+export interface TextLayoutMetrics {
+    readonly lineCount: number;
+    readonly textHeight: number;
+    readonly naturalWidth: number;
+    readonly maxLineWidth: number;
+    readonly truncated: boolean;
+}
+/**
+ * Return the painted alphabetic baseline relative to the Canvas draw Y.
+ * The same shared Canvas context and font string also own Text width metrics.
+ */
+export declare function measureTextAlphabeticBaselineOffset(text: string, font: string, textBaseline: CanvasTextBaseline): number;
+/**
+ * Measure one text run through the same engine used by Text and Span.
+ * `white-space: pre-wrap` keeps the caller's spaces and hard breaks intact.
+ */
+export declare function measureTextWidth(text: string, font: string, letterSpacing?: number): number;
+/** Fit a single run and append an ellipsis only when it does not fit. */
+export declare function fitTextWithEllipsis(text: string, maxWidth: number, font: string, letterSpacing?: number): string;
+declare class PreparedTextLayout {
+    readonly text: string;
+    readonly font: string;
+    readonly letterSpacing: number;
+    readonly normalizedText: string;
+    readonly naturalWidth: number;
+    private readonly plainText;
+    private prepared;
+    constructor(text: string, font: string, letterSpacing: number);
+    measure(options: TextLayoutOptions): TextLayoutMetrics;
+    private getFirstLineRange;
+    layout(options: TextLayoutOptions): TextLayoutSnapshot;
+    private getRichPrepared;
+}
+type SnapshotLine = LayoutLine & {
+    ellipsized: boolean;
+};
+interface TextLineSourceRange {
+    readonly sourceStart: number;
+    readonly sourceEnd: number;
+}
+export declare class TextLayoutSnapshot {
+    readonly normalizedText: string;
+    private readonly font;
+    private readonly letterSpacing;
+    readonly lineHeight: number;
+    readonly naturalWidth: number;
+    readonly rawLineCount: number;
+    readonly truncated: boolean;
+    readonly maxLineWidth: number;
+    readonly textHeight: number;
+    private readonly lineCaretMetrics;
+    private readonly lineSourceRanges;
+    private readonly preparedSegments;
+    private readonly layoutLines;
+    private segmentStarts;
+    private segmentBoundaries;
+    private lineCharOffsetsCache;
+    constructor(normalizedText: string, font: string, letterSpacing: number, lineHeight: number, naturalWidth: number, preparedSegments: readonly string[], rawLineCount: number, truncated: boolean, lines: readonly SnapshotLine[], maxLineWidth: number);
+    get lines(): readonly TextLayoutLine[];
+    get lineCharOffsets(): readonly number[];
+    static empty(): TextLayoutSnapshot;
+    getLineSourceRange(index: number): TextLineSourceRange;
+    getLineIndex(offset: number): number;
+    getLineX(index: number, width: number, textAlign: string): number;
+    getBlockVerticalOffset(height: number, verticalAlign: string, contentHeight?: number): number;
+    getCaretLocalXY(caretIndex: number, width: number, height: number, textAlign: string, verticalAlign: string, fontSize: number): {
+        x: number;
+        y: number;
+        h: number;
+    };
+    hitTestCaret(lineIndex: number, localX: number, width: number, textAlign: string): number;
+    measureLineRange(index: number, start: number, end: number): {
+        x: number;
+        width: number;
+    };
+    private getCaretX;
+    private getBoundaryX;
+    private getLineCaretMetrics;
+    private cursorOffset;
+    private ensureSourceIndex;
+}
+export declare function prepareTextLayout(text: string, font: string, letterSpacing?: number): PreparedTextLayout;
+export type PreparedTextLayoutHandle = PreparedTextLayout;
+export {};

package/dist/text/paint.d.ts

@@ -0,0 +1,59 @@
+import { type TextLayoutSnapshot } from "./layout";
+import type { Text } from "./index";
+import { type ResolvedTextStyle } from "./style";
+import type { ShadowOption, TextStyleConfig } from "@fulate/core";
+export declare function resolveColorFill(ctx: CanvasRenderingContext2D, color: ResolvedTextStyle["color"], w: number, h: number): string | CanvasGradient;
+export declare function drawTextLine(ctx: CanvasRenderingContext2D, line: string, x: number, y: number, font: string, letterSpacing: number, doFill: boolean, doStroke: boolean): void;
+export interface TextDecorationOptions {
+    x: number;
+    y: number;
+    width: number;
+    fontSize: number;
+    textBaseline: string;
+    underline?: boolean;
+    strikethrough?: boolean;
+    color: string;
+    thickness?: number;
+}
+export declare function drawTextDecoration(ctx: CanvasRenderingContext2D, opts: TextDecorationOptions): void;
+export interface TextStrokeOptions {
+    line: string;
+    x: number;
+    y: number;
+    font: string;
+    letterSpacing: number;
+    strokeColor: string | CanvasGradient;
+    strokeWidth: number;
+}
+export declare function drawTextWithStroke(ctx: CanvasRenderingContext2D, opts: TextStrokeOptions): void;
+export declare function applyTextShadow(ctx: CanvasRenderingContext2D, shadow: ShadowOption): void;
+export declare function clearTextShadow(ctx: CanvasRenderingContext2D): void;
+export interface TextRunMetrics {
+    /** CSS font shorthand used for measurement and later painting. */
+    readonly font: string;
+    /** Painted width; empty text is always `0`. */
+    readonly width: number;
+    /** Line-box height in logical pixels. */
+    readonly lineHeight: number;
+    /** Canvas draw Y relative to the run's line-box top. */
+    readonly drawY: number;
+    /** Alphabetic baseline relative to the run's line-box top. */
+    readonly alphabeticBaseline: number;
+}
+/**
+ * Measure one native Canvas text run with Fulate's resolved font and line-box
+ * semantics. This performs one `measureText()` call and writes the run's font,
+ * baseline, and letter spacing to the supplied context without saving or
+ * restoring it. Empty text measures a space for baseline data but reports zero
+ * width.
+ */
+export declare function measureTextRun(ctx: CanvasRenderingContext2D, text: string, style: Readonly<Required<TextStyleConfig>>, fontSize?: number, fontWeight?: string | number): TextRunMetrics;
+export interface TextLineBoxMetrics {
+    readonly alphabeticBaseline: number;
+    readonly height: number;
+}
+/** Measure the line box produced by the existing Text painter. */
+export declare function measureTextLineBoxMetrics(text: string, style: ResolvedTextStyle): TextLineBoxMetrics;
+/** 绘制一份已排版文字块；Text 与内部组合共同使用。 */
+export declare function paintTextBlock(ctx: CanvasRenderingContext2D, layout: TextLayoutSnapshot, style: ResolvedTextStyle, width: number, height: number): void;
+export declare function paintTextContent(self: Text, ctx: CanvasRenderingContext2D, offsetY?: number): void;

package/dist/text/style.d.ts

@@ -0,0 +1,13 @@
+import type { TextStyleConfig } from "@fulate/core";
+export type { TextStyleConfig };
+export type ResolvedTextStyle = Required<TextStyleConfig>;
+export declare const TEXT_STYLE_DEFAULTS: Required<TextStyleConfig>;
+export declare const TEXT_STYLE_KEYS: readonly TextStyleKey[];
+export type TextStyleKey = keyof TextStyleConfig;
+export declare function buildFontString(style: {
+    fontStyle?: string;
+    fontWeight?: string | number;
+    fontSize?: number;
+    fontFamily?: string;
+}, fontSize?: number, fontWeight?: string | number): string;
+export declare function resolveTextStyle(instance: Record<string, any>, defaults: Record<string, any>): ResolvedTextStyle;

package/dist/triangle.d.ts

@@ -0,0 +1,20 @@
+import { type Edge, type PointView } from "@fulate/share";
+import { type GeometrySnapshot } from "@fulate/core";
+import { EditorShape, EditorShapeTransform } from "./editor/shape";
+export declare class TriangleTransform<E extends Triangle = Triangle> extends EditorShapeTransform<E> {
+    protected buildVisualOutline(snapshot: GeometrySnapshot): PointView[];
+    protected buildGeometrySnapshot(revision: number, layoutReferenceBounds?: Readonly<import("@fulate/share").Rect>): GeometrySnapshot;
+}
+export declare class Triangle extends EditorShape {
+    readonly type = "triangle";
+    constructor(options?: {});
+    protected buildPath(ctx: CanvasRenderingContext2D): void;
+    getEdgeSegment(edge: Edge): {
+        start: PointView;
+        end: PointView;
+    };
+    protected getDefaultConnectionPortSchema(): {
+        id: string;
+        localPosition: (el: any) => any;
+    }[];
+}

package/dist/vector-path.d.ts

@@ -0,0 +1,58 @@
+import type { PointView } from "@fulate/share";
+import { ChangeImpact, ShapeProperties, type AuthoredSubpath, type GeometrySnapshot, type OwnerPropertyChange, type PropertyChanges, type ReparentTransformIntent, type ShapeOption, type ShapeOptionPatch, type ElementTransformBaseline, type TransformIntent } from "@fulate/core";
+import { EditorShape, EditorShapeTransform } from "./editor/shape";
+import { type EditorCapabilityToken, type PointControlDescriptor, type PointEditRequest, type PointEditingScope, type PointOwnerEdit } from "./editor/capability";
+/** Sketch/SVG-style creation intent; commands never enter live Properties. */
+export type VectorPathCommand = Readonly<{
+    type: "M" | "L";
+    point: PointView;
+}> | Readonly<{
+    type: "C";
+    control1: PointView;
+    control2: PointView;
+    point: PointView;
+}> | Readonly<{
+    type: "Z";
+}>;
+export interface VectorPathGeometry {
+    readonly subpaths: readonly AuthoredSubpath[];
+}
+export interface VectorPathOption extends ShapeOption<VectorPath> {
+    /** 普通创建传 commands；restore 直接传 canonical geometry。 */
+    path?: readonly VectorPathCommand[] | VectorPathGeometry;
+}
+type VectorPathPatch = ShapeOptionPatch<VectorPathOption>;
+interface VectorPathStateOption extends Omit<VectorPathOption, "path"> {
+    path?: VectorPathGeometry;
+}
+export declare class VectorPathProperties extends ShapeProperties {
+    path: VectorPathGeometry;
+    constructor(options?: VectorPathStateOption);
+    getImpact(changes: PropertyChanges): ChangeImpact;
+}
+export declare class VectorPathTransform<E extends VectorPath = VectorPath> extends EditorShapeTransform<E> {
+    protected buildGeometrySnapshot(revision: number): GeometrySnapshot;
+}
+export declare class VectorPath extends EditorShape<VectorPathProperties, VectorPathOption> {
+    readonly type = "vectorPath";
+    get path(): VectorPathGeometry;
+    constructor(options?: VectorPathOption);
+    protected resolveOptions(options: VectorPathPatch): Partial<Omit<VectorPathOption, "key" | "children">>;
+    getEditorCapability<T>(token: EditorCapabilityToken<T>): T | undefined;
+    resolvePointScope(worldPoint: PointView): {
+        readonly kind: "owner";
+    };
+    hasPointScope(scope: PointEditingScope): scope is {
+        readonly kind: "owner";
+    };
+    getPointControls(_scope: PointEditingScope): readonly PointControlDescriptor[];
+    getPointScopeOutline(_scope: PointEditingScope): any;
+    resolvePointEdit(request: PointEditRequest): PointOwnerEdit | null;
+    private findAnchor;
+    private findSegment;
+    private ownerPathChange;
+    captureTransformBaseline(): ElementTransformBaseline<VectorPathGeometry>;
+    resolveTransformChange(baseline: Readonly<ElementTransformBaseline<VectorPathGeometry>>, intent: Readonly<TransformIntent | ReparentTransformIntent>): OwnerPropertyChange;
+    protected buildPath(ctx: CanvasRenderingContext2D): void;
+}
+export {};

package/dist/worker-surface-protocol.d.ts

@@ -0,0 +1,26 @@
+export type WorkerSurfaceRequest<Initialize, Create, Message> = {
+    type: "initialize";
+    input: Initialize;
+} | {
+    type: "create";
+    surfaceId: number;
+    input: Create;
+} | {
+    type: "message";
+    surfaceId: number;
+    input: Message;
+} | {
+    type: "destroy";
+    surfaceId: number;
+};
+export type WorkerSurfaceResponse<Output = never> = {
+    type: "ready";
+} | {
+    type: "frame";
+    surfaceId: number;
+    bitmap: ImageBitmap;
+} | {
+    type: "output";
+    surfaceId: number;
+    output: Output;
+};

package/dist/worker-surface-worker.d.ts

@@ -0,0 +1,25 @@
+export interface WorkerSurface<Message> {
+    receive(message: Message): void;
+    dispose(): void;
+}
+export interface WorkerSurfaceFactory<Initialize, Create, Message, Runtime, Output = never> {
+    initialize(input: Initialize): Runtime | Promise<Runtime>;
+    create(runtime: Runtime, input: Create, emitFrame: (bitmap: ImageBitmap) => void, emitOutput: (output: Output) => void): WorkerSurface<Message>;
+}
+/** Installs the shared typed lifecycle in one Worker realm. */
+export declare function runWorkerSurfaceHost<Initialize, Create, Message, Runtime, Output = never>(factory: WorkerSurfaceFactory<Initialize, Create, Message, Runtime, Output>): void;
+/** Coalesces renderer callbacks to one current transferable bitmap frame. */
+export declare class BitmapFrameEmitter {
+    private readonly getCanvas;
+    private readonly emit;
+    private pending;
+    private queued;
+    private paused;
+    private active;
+    constructor(getCanvas: () => OffscreenCanvas, emit: (bitmap: ImageBitmap) => void);
+    request(): void;
+    pause(): void;
+    resume(): void;
+    dispose(): void;
+    private flush;
+}

package/dist/worker-surface-worker.js

@@ -0,0 +1,109 @@
+//#region packages/ui/src/worker-surface-worker.ts
+/** Installs the shared typed lifecycle in one Worker realm. */
+function runWorkerSurfaceHost(factory) {
+	const scope = self;
+	const surfaces = /* @__PURE__ */ new Map();
+	let runtime;
+	scope.onmessage = async (event) => {
+		const message = event.data;
+		switch (message.type) {
+			case "initialize":
+				runtime = await factory.initialize(message.input);
+				scope.postMessage({ type: "ready" });
+				break;
+			case "create": {
+				const { surfaceId } = message;
+				const entry = { surface: null };
+				surfaces.set(surfaceId, entry);
+				try {
+					entry.surface = factory.create(runtime, message.input, (bitmap) => {
+						if (surfaces.get(surfaceId) !== entry) {
+							bitmap.close();
+							return;
+						}
+						const response = {
+							type: "frame",
+							surfaceId,
+							bitmap
+						};
+						scope.postMessage(response, [bitmap]);
+					}, (output) => {
+						if (surfaces.get(surfaceId) !== entry) return;
+						const response = {
+							type: "output",
+							surfaceId,
+							output
+						};
+						scope.postMessage(response);
+					});
+				} catch (error) {
+					surfaces.delete(surfaceId);
+					throw error;
+				}
+				break;
+			}
+			case "message":
+				surfaces.get(message.surfaceId).surface.receive(message.input);
+				break;
+			case "destroy": {
+				const entry = surfaces.get(message.surfaceId);
+				surfaces.delete(message.surfaceId);
+				entry.surface.dispose();
+				break;
+			}
+		}
+	};
+}
+/** Coalesces renderer callbacks to one current transferable bitmap frame. */
+var BitmapFrameEmitter = class {
+	pending = null;
+	queued = false;
+	paused = false;
+	active = true;
+	constructor(getCanvas, emit) {
+		this.getCanvas = getCanvas;
+		this.emit = emit;
+	}
+	request() {
+		if (!this.active || this.paused) return;
+		this.queued = true;
+		this.flush();
+	}
+	pause() {
+		if (!this.active || this.paused) return;
+		this.paused = true;
+		this.queued = false;
+	}
+	resume() {
+		if (!this.active || !this.paused) return;
+		this.paused = false;
+		this.request();
+	}
+	dispose() {
+		this.active = false;
+		this.queued = false;
+	}
+	flush() {
+		if (!this.active || this.paused || this.pending || !this.queued) return;
+		this.queued = false;
+		const pending = createImageBitmap(this.getCanvas());
+		this.pending = pending;
+		pending.then((bitmap) => {
+			if (!this.active || this.paused || this.pending !== pending || this.queued) {
+				bitmap.close();
+				return;
+			}
+			try {
+				this.emit(bitmap);
+			} catch (error) {
+				bitmap.close();
+				throw error;
+			}
+		}).finally(() => {
+			if (this.pending === pending) this.pending = null;
+			if (this.active && !this.paused && this.queued) this.flush();
+		});
+	}
+};
+//#endregion
+export { BitmapFrameEmitter, runWorkerSurfaceHost };

package/dist/worker-surface.d.ts

@@ -0,0 +1,23 @@
+export interface WorkerSurfacePoolOptions<Initialize> {
+    readonly size: number;
+    readonly initialize: Initialize;
+    readonly createWorker: () => Worker;
+}
+export interface WorkerSurfaceHandle<Message> {
+    post(message: Message): void;
+    dispose(): void;
+}
+type FrameReceiver = (bitmap: ImageBitmap) => void;
+type OutputReceiver<Output> = (output: Output) => void;
+/** Pins long-lived bitmap surfaces to a fixed set of homogeneous Workers. */
+export declare class WorkerSurfacePool<Initialize, Create, Message, Output = never> {
+    private slots;
+    private entries;
+    private nextSurfaceId;
+    constructor(options: WorkerSurfacePoolOptions<Initialize>);
+    create(input: Create, onFrame: FrameReceiver, onOutput?: OutputReceiver<Output>): WorkerSurfaceHandle<Message>;
+    dispose(): void;
+    private pickWorker;
+    private receive;
+}
+export {};

package/dist/workspace.d.ts

@@ -0,0 +1,44 @@
+import { type ElementJSON, type Layer, type Root, type Viewport, type ViewportInsets } from "@fulate/core";
+import { Image, ImageProperties, type ImageOption } from "./image";
+/** @internal 当前 Root 中为 Workspace 自动聚焦提供屏幕边距的唯一 owner。 */
+export type WorkspaceFocusInsetsSource = () => number | ViewportInsets;
+/** @internal Workspace 与高层 screen-space overlay 共享的 Root context key。 */
+export declare const workspaceFocusInsetsKey: unique symbol;
+/** Workspace 只接受自身配置，不接受任何 children。 */
+export interface WorkspaceOption extends Omit<ImageOption<Workspace>, "children" | "image" | "resize"> {
+    /** 首次进入 Root 时是否在首个 Canvas paint 前无动画聚焦，默认 `true`。 */
+    fit?: boolean;
+    /** Root 尺寸变化后是否无动画重新聚焦工作区，默认 `true`。 */
+    fitOnResize?: boolean;
+}
+export type WorkspaceJSON = Omit<ElementJSON<WorkspaceOption>, "children">;
+/** Workspace 的自有 authored 属性。 */
+export declare class WorkspaceProperties extends ImageProperties {
+    /** 首次进入 Root 时是否在首个 Canvas paint 前执行一次无动画聚焦。 */
+    fit: boolean;
+    /** Root 尺寸变化后是否执行无动画聚焦。 */
+    fitOnResize: boolean;
+    constructor(options?: WorkspaceOption);
+}
+/** Options forwarded unchanged to the owning Root viewport. */
+export type WorkspaceFitOptions = NonNullable<Parameters<Viewport["focus"]>[1]>;
+/** Fits one active Workspace into its owning Root viewport. */
+export declare function fitWorkspace(workspace: Workspace, options?: WorkspaceFitOptions): Promise<void>;
+/** Workspace 是不可选择的背景板，支持颜色、图片及无动画的首次与 resize fit。 */
+export declare class Workspace extends Image<WorkspaceProperties, WorkspaceOption> {
+    readonly type = "workspace";
+    private didFocus;
+    private resizeRequested;
+    private pendingResizeFit;
+    private removeInitialFitObserver;
+    private removeResizeListener;
+    constructor(options?: WorkspaceOption);
+    get fit(): boolean;
+    get fitOnResize(): boolean;
+    /** Workspace 只导出自己的配置，不导出任何子节点。 */
+    toJSON(): WorkspaceJSON;
+    protected onDeactivate(root: Root | null, layer: Layer | null): void;
+    protected onActivate(root: Root | null, layer: Layer | null): void;
+    private focusInsets;
+    private scheduleResizeFit;
+}