@pixerate/editor 0.107.0 → 0.108.0

package/dist/paint-editor/index.d.cts

@@ -4,6 +4,7 @@ export { b as MAX_BRUSH_SIZE } from '../mixer-5ziHU8OS.cjs';
 import { R as RasterRect, a as TiledSurface, B as BlendMode, b as BlendModeInfo } from '../surface-CkKOHGPm.cjs';
 export { c as BLEND_MODES, d as PAINTERLY_BLEND_MODES, e as Tile, i as isBlendMode, f as isPainterlyBlendMode, s as standardBlendMode } from '../surface-CkKOHGPm.cjs';
 import { I as ImageEditorAssetStore, S as SerializedLayer, P as PsdExportResult } from '../export-JGWQEPJn.cjs';
+import { g as PresenceStore, e as PresenceClock, d as PresenceActorInfo, c as PresenceActor, f as PresenceState } from '../presence-Cb6WhcrQ.cjs';
 import { a as AgentToolProvider } from '../registry-BqA1AZt0.cjs';
 import '../types-CwMPoRMU.cjs';
 import '../warp-D5jz_tN7.cjs';
@@ -1385,7 +1386,8 @@ declare class PaintEditorController {
     paintStroke(init: PaintStrokeInit & {
         points: readonly PenPoint[];
     }): PaintStrokeResult;
-    private checkPoints;
+    /** Checks stroke samples (finite x and y, pressure 0..1) and returns them; throws a sentence naming the bad point. */
+    checkPoints(points: readonly PenPoint[]): PenPoint[];
     /** Every recorded stroke, oldest first. */
     getStrokes(): readonly RecordedStroke[];
     /**
@@ -1533,6 +1535,91 @@ declare class PaintEditorController {
 /** Largest tracing or reference image side, in pixels. */
 declare const MAX_IMAGE_SIDE = 8192;
 
+type PaintPresenceActor = PresenceActor;
+type PaintPresenceState = PresenceState;
+/** Cursor positions (document pixels) and notes of agents painting, for an overlay. */
+declare class PaintPresence extends PresenceStore {
+}
+/** What an agent asks for. Each command that paints commits as one undo step. */
+type PaintAgentCommand = {
+    kind: 'stroke';
+    stroke: PaintStrokeInit & {
+        points: readonly PenPoint[];
+    };
+    note?: string;
+} | {
+    kind: 'fill';
+    fill: FillLayerOptions;
+    note?: string;
+} | {
+    kind: 'replay';
+    replay: ReplayOptions;
+    note?: string;
+} | {
+    kind: 'point';
+    at: {
+        x: number;
+        y: number;
+    };
+    note?: string;
+} | {
+    kind: 'say';
+    text: string;
+};
+type PaintPerformanceResult = {
+    ok: true;
+    command: PaintAgentCommand;
+    result?: unknown;
+} | {
+    ok: false;
+    command: PaintAgentCommand;
+    message: string;
+};
+interface PaintDirectorOptions {
+    clock?: PresenceClock;
+    /** 1 = natural speed; 2 = twice as fast. */
+    speed?: number;
+    /** Hide each actor's cursor this long after its last command (ms, default 1500; 0 keeps it). */
+    linger?: number;
+    /** Longest a stroke takes to paint at speed 1 (ms, default 1800); longer strokes are sped up. */
+    maxStrokeMs?: number;
+}
+/** Where along a stroke each point is reached, 0..1: by its time `t` when the points have times, else by distance. */
+declare function strokeSchedule(points: readonly PenPoint[]): number[];
+/** How long a stroke takes to paint at speed 1 (ms): its recorded duration, else ~1.5 px/ms, between 250 ms and `max`. */
+declare function strokeDuration(points: readonly PenPoint[], max?: number): number;
+/** A zig-zag across `rect` (for a fill rubbed over the sheet), `rows` passes from the top. */
+declare function sweepPath(rect: RasterRect, rows?: number): Array<{
+    x: number;
+    y: number;
+}>;
+/**
+ * Acts out agent commands on a paint canvas: the actor's cursor glides to the stroke's start and
+ * paints it live along its points (paced by their times, or evenly), the stroke committing as
+ * one undo step; fills are rubbed across the sheet first; replays start from the strokes they
+ * copy and end on what they painted. Commands queue per actor. A command that cannot apply (an
+ * unknown or locked layer, a stroke the user is still painting) fails with the controller's
+ * sentence before anything is painted.
+ */
+declare class PaintDirector {
+    private readonly controller;
+    readonly presence: PaintPresence;
+    private readonly options;
+    private readonly clock;
+    private readonly queue;
+    constructor(controller: PaintEditorController, presence: PaintPresence, options?: PaintDirectorOptions);
+    /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
+    perform(actor: PresenceActorInfo, commands: readonly PaintAgentCommand[]): Promise<PaintPerformanceResult[]>;
+    private ms;
+    private where;
+    /** Glides to `to`; an actor that just appeared starts there instead of the corner. */
+    private glide;
+    private say;
+    private performOne;
+    /** Paints a stroke live: begins it, pushes its points frame by frame as the cursor reaches them, then ends it (one undo step). */
+    private stroke;
+}
+
 /**
  * Agent tools for the paint editor (`createPaintEditorToolProvider`). Strict schemas, every
  * argument described, all four annotations. Each write is one undo step (or editor state, said so)
@@ -1545,6 +1632,13 @@ interface PaintEditorToolProviderOptions {
     id?: string;
     /** Always prefix tool names with `<namespace>__`. */
     namespace?: string;
+    /**
+     * Acts out strokes, fills and replays with an agent cursor on the canvas (see `PaintDirector`):
+     * strokes paint live along their points. Each call is still one undo step. Without it, they apply at once.
+     */
+    director?: PaintDirector;
+    /** The agent's cursor (default `{ id: 'agent', name: 'Agent' }`). */
+    actor?: PresenceActorInfo;
 }
 /** Agent tools for one paint editor. */
 declare function createPaintEditorToolProvider(controller: PaintEditorController, options?: PaintEditorToolProviderOptions): AgentToolProvider;
@@ -1688,4 +1782,4 @@ interface BlendMenuGroup {
  */
 declare const BLEND_MENU_GROUPS: readonly BlendMenuGroup[];
 
-export { type Affine, BLEND_MENU_GROUPS, BRUSH_ID, BRUSH_ROTATIONS, BRUSH_SLIDERS, BUILTIN_BRUSHES, type BlendMenuGroup, BlendMode, BlendModeInfo, type BrushDynamics, type BrushLibraryFile, type BrushRotation, type BrushThumbnail, type ColorWheel, DEFAULT_BRUSH_ID, DEFAULT_DPI, DEFAULT_DYNAMICS, DEFAULT_PAPER, DEFAULT_SWATCHES, DEFAULT_VIEW, DryStroke, type DryStrokeOptions, type FillLayerOptions, GRAIN_PATTERNS, GRAIN_TILE, type GrainPattern, type GrainTuning, HARMONY_KINDS, type Hand, type HarmonyColor, type HarmonyKind, IDENTITY_AFFINE, IDENTITY_COPY, type ImageEncoder, type ImageFormat, type ImageNode, type LayerUpdate, type Linear2, type LoadedPaintDocument, MAX_CANVAS_SIDE, MAX_COORDINATE, MAX_IMAGE_SIDE, MAX_ZOOM, MIN_CANVAS_SIDE, MIN_ZOOM, MIXING_PAD_HEIGHT, MIXING_PAD_WIDTH, MixingPad, type MixingPadTool, PAINT_BRUSH_CATEGORIES, PAINT_BRUSH_ENGINES, PAINT_FORMAT, PAINT_SCHEMA_VERSION, PAINT_TOOLS, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, PAPER_SLIDERS, type Paint2DContext, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintBrushInput, type PaintCanvas, PaintCanvasPresenter, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, PaintGesture, type PaintGroupLayer, type PaintGuides, type PaintLayer, type PaintLayerInfo, type PaintPixelLayer, type PaintPointerEvent, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintTool, type PaintView, type PaperFamily, PaperGrain, type PaperNode, type PaperSettings, type PaperTiling, type PenDab, PenDabWalker, type PenPoint, PenSmoother, type PerspectiveGuide, PerspectiveSnapper, type PixelImage, type Point2, type PointerSample, type RecordedStroke, type ReferenceImage, type RenderOptions, type ReplayOptions, type Rgb255, SNAP_DECIDE_DISTANCE, SYMMETRY_MODES, type SerializeOptions, type SerializedPaintDocument, type SliderControl, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, type Swatch, type SymmetryGuide, type SymmetryMode, TRACING_NODE_ID, TileableNoise, type TracingImage, type ViewLayer, type ViewportBox, affineCopy, applyAffine, brushToJSON, clonePaper, colorHarmony, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, decodeImageBlob, defaultGuides, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downloadBytes, downsampleRgba, fitZoom, grainCatch, grainHeights, guideOverlay, handlePaintShortcut, hash2, hexToRgb8, hslToRgb, hsvToRgb, hueToWheel, invertAffine, isPalmTouch, mapPenPoint, mix32, mixerLoadForStroke, mixerTip, newPaintLayerId, normalizeBrushStroke, normalizeCanvas, normalizeDynamics, normalizePaintBrush, normalizePaper, normalizePerspective, normalizeRotation, normalizeSymmetry, normalizeView, paperGrain, paperKey, paperNode, paperPreset, parseBrushLibrary, parseHexColor, patchPath, penOrientation, perspectiveDirections, perspectiveGuideLines, pointerToPenPoint, rand01, randSigned, readPath, renderBrushThumbnail, renderColorWheel, renderPaper, rgbToHexColor, rgbToHsl, rgbToHsv, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, symmetryAxisAngles, symmetryAxisSegments, symmetryCopies, thumbnailStroke, tiltToOrientation, toStrokePoint, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument, wheelAngle, wheelPick, wheelPoint, wheelToHue };
+export { type Affine, BLEND_MENU_GROUPS, BRUSH_ID, BRUSH_ROTATIONS, BRUSH_SLIDERS, BUILTIN_BRUSHES, type BlendMenuGroup, BlendMode, BlendModeInfo, type BrushDynamics, type BrushLibraryFile, type BrushRotation, type BrushThumbnail, type ColorWheel, DEFAULT_BRUSH_ID, DEFAULT_DPI, DEFAULT_DYNAMICS, DEFAULT_PAPER, DEFAULT_SWATCHES, DEFAULT_VIEW, DryStroke, type DryStrokeOptions, type FillLayerOptions, GRAIN_PATTERNS, GRAIN_TILE, type GrainPattern, type GrainTuning, HARMONY_KINDS, type Hand, type HarmonyColor, type HarmonyKind, IDENTITY_AFFINE, IDENTITY_COPY, type ImageEncoder, type ImageFormat, type ImageNode, type LayerUpdate, type Linear2, type LoadedPaintDocument, MAX_CANVAS_SIDE, MAX_COORDINATE, MAX_IMAGE_SIDE, MAX_ZOOM, MIN_CANVAS_SIDE, MIN_ZOOM, MIXING_PAD_HEIGHT, MIXING_PAD_WIDTH, MixingPad, type MixingPadTool, PAINT_BRUSH_CATEGORIES, PAINT_BRUSH_ENGINES, PAINT_FORMAT, PAINT_SCHEMA_VERSION, PAINT_TOOLS, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, PAPER_SLIDERS, type Paint2DContext, type PaintAgentCommand, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintBrushInput, type PaintCanvas, PaintCanvasPresenter, PaintDirector, type PaintDirectorOptions, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, PaintGesture, type PaintGroupLayer, type PaintGuides, type PaintLayer, type PaintLayerInfo, type PaintPerformanceResult, type PaintPixelLayer, type PaintPointerEvent, PaintPresence, type PaintPresenceActor, type PaintPresenceState, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintTool, type PaintView, type PaperFamily, PaperGrain, type PaperNode, type PaperSettings, type PaperTiling, type PenDab, PenDabWalker, type PenPoint, PenSmoother, type PerspectiveGuide, PerspectiveSnapper, type PixelImage, type Point2, type PointerSample, type RecordedStroke, type ReferenceImage, type RenderOptions, type ReplayOptions, type Rgb255, SNAP_DECIDE_DISTANCE, SYMMETRY_MODES, type SerializeOptions, type SerializedPaintDocument, type SliderControl, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, type Swatch, type SymmetryGuide, type SymmetryMode, TRACING_NODE_ID, TileableNoise, type TracingImage, type ViewLayer, type ViewportBox, affineCopy, applyAffine, brushToJSON, clonePaper, colorHarmony, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, decodeImageBlob, defaultGuides, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downloadBytes, downsampleRgba, fitZoom, grainCatch, grainHeights, guideOverlay, handlePaintShortcut, hash2, hexToRgb8, hslToRgb, hsvToRgb, hueToWheel, invertAffine, isPalmTouch, mapPenPoint, mix32, mixerLoadForStroke, mixerTip, newPaintLayerId, normalizeBrushStroke, normalizeCanvas, normalizeDynamics, normalizePaintBrush, normalizePaper, normalizePerspective, normalizeRotation, normalizeSymmetry, normalizeView, paperGrain, paperKey, paperNode, paperPreset, parseBrushLibrary, parseHexColor, patchPath, penOrientation, perspectiveDirections, perspectiveGuideLines, pointerToPenPoint, rand01, randSigned, readPath, renderBrushThumbnail, renderColorWheel, renderPaper, rgbToHexColor, rgbToHsl, rgbToHsv, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, strokeDuration, strokeSchedule, sweepPath, symmetryAxisAngles, symmetryAxisSegments, symmetryCopies, thumbnailStroke, tiltToOrientation, toStrokePoint, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument, wheelAngle, wheelPick, wheelPoint, wheelToHue };

package/dist/paint-editor/index.d.ts

@@ -4,6 +4,7 @@ export { b as MAX_BRUSH_SIZE } from '../mixer-DNqiYXYQ.js';
 import { R as RasterRect, a as TiledSurface, B as BlendMode, b as BlendModeInfo } from '../surface-CkKOHGPm.js';
 export { c as BLEND_MODES, d as PAINTERLY_BLEND_MODES, e as Tile, i as isBlendMode, f as isPainterlyBlendMode, s as standardBlendMode } from '../surface-CkKOHGPm.js';
 import { I as ImageEditorAssetStore, S as SerializedLayer, P as PsdExportResult } from '../export-a9bnF7Cl.js';
+import { g as PresenceStore, e as PresenceClock, d as PresenceActorInfo, c as PresenceActor, f as PresenceState } from '../presence-Cb6WhcrQ.js';
 import { a as AgentToolProvider } from '../registry-D-4fit9C.js';
 import '../types-CwMPoRMU.js';
 import '../warp-CWHZzE3x.js';
@@ -1385,7 +1386,8 @@ declare class PaintEditorController {
     paintStroke(init: PaintStrokeInit & {
         points: readonly PenPoint[];
     }): PaintStrokeResult;
-    private checkPoints;
+    /** Checks stroke samples (finite x and y, pressure 0..1) and returns them; throws a sentence naming the bad point. */
+    checkPoints(points: readonly PenPoint[]): PenPoint[];
     /** Every recorded stroke, oldest first. */
     getStrokes(): readonly RecordedStroke[];
     /**
@@ -1533,6 +1535,91 @@ declare class PaintEditorController {
 /** Largest tracing or reference image side, in pixels. */
 declare const MAX_IMAGE_SIDE = 8192;
 
+type PaintPresenceActor = PresenceActor;
+type PaintPresenceState = PresenceState;
+/** Cursor positions (document pixels) and notes of agents painting, for an overlay. */
+declare class PaintPresence extends PresenceStore {
+}
+/** What an agent asks for. Each command that paints commits as one undo step. */
+type PaintAgentCommand = {
+    kind: 'stroke';
+    stroke: PaintStrokeInit & {
+        points: readonly PenPoint[];
+    };
+    note?: string;
+} | {
+    kind: 'fill';
+    fill: FillLayerOptions;
+    note?: string;
+} | {
+    kind: 'replay';
+    replay: ReplayOptions;
+    note?: string;
+} | {
+    kind: 'point';
+    at: {
+        x: number;
+        y: number;
+    };
+    note?: string;
+} | {
+    kind: 'say';
+    text: string;
+};
+type PaintPerformanceResult = {
+    ok: true;
+    command: PaintAgentCommand;
+    result?: unknown;
+} | {
+    ok: false;
+    command: PaintAgentCommand;
+    message: string;
+};
+interface PaintDirectorOptions {
+    clock?: PresenceClock;
+    /** 1 = natural speed; 2 = twice as fast. */
+    speed?: number;
+    /** Hide each actor's cursor this long after its last command (ms, default 1500; 0 keeps it). */
+    linger?: number;
+    /** Longest a stroke takes to paint at speed 1 (ms, default 1800); longer strokes are sped up. */
+    maxStrokeMs?: number;
+}
+/** Where along a stroke each point is reached, 0..1: by its time `t` when the points have times, else by distance. */
+declare function strokeSchedule(points: readonly PenPoint[]): number[];
+/** How long a stroke takes to paint at speed 1 (ms): its recorded duration, else ~1.5 px/ms, between 250 ms and `max`. */
+declare function strokeDuration(points: readonly PenPoint[], max?: number): number;
+/** A zig-zag across `rect` (for a fill rubbed over the sheet), `rows` passes from the top. */
+declare function sweepPath(rect: RasterRect, rows?: number): Array<{
+    x: number;
+    y: number;
+}>;
+/**
+ * Acts out agent commands on a paint canvas: the actor's cursor glides to the stroke's start and
+ * paints it live along its points (paced by their times, or evenly), the stroke committing as
+ * one undo step; fills are rubbed across the sheet first; replays start from the strokes they
+ * copy and end on what they painted. Commands queue per actor. A command that cannot apply (an
+ * unknown or locked layer, a stroke the user is still painting) fails with the controller's
+ * sentence before anything is painted.
+ */
+declare class PaintDirector {
+    private readonly controller;
+    readonly presence: PaintPresence;
+    private readonly options;
+    private readonly clock;
+    private readonly queue;
+    constructor(controller: PaintEditorController, presence: PaintPresence, options?: PaintDirectorOptions);
+    /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
+    perform(actor: PresenceActorInfo, commands: readonly PaintAgentCommand[]): Promise<PaintPerformanceResult[]>;
+    private ms;
+    private where;
+    /** Glides to `to`; an actor that just appeared starts there instead of the corner. */
+    private glide;
+    private say;
+    private performOne;
+    /** Paints a stroke live: begins it, pushes its points frame by frame as the cursor reaches them, then ends it (one undo step). */
+    private stroke;
+}
+
 /**
  * Agent tools for the paint editor (`createPaintEditorToolProvider`). Strict schemas, every
  * argument described, all four annotations. Each write is one undo step (or editor state, said so)
@@ -1545,6 +1632,13 @@ interface PaintEditorToolProviderOptions {
     id?: string;
     /** Always prefix tool names with `<namespace>__`. */
     namespace?: string;
+    /**
+     * Acts out strokes, fills and replays with an agent cursor on the canvas (see `PaintDirector`):
+     * strokes paint live along their points. Each call is still one undo step. Without it, they apply at once.
+     */
+    director?: PaintDirector;
+    /** The agent's cursor (default `{ id: 'agent', name: 'Agent' }`). */
+    actor?: PresenceActorInfo;
 }
 /** Agent tools for one paint editor. */
 declare function createPaintEditorToolProvider(controller: PaintEditorController, options?: PaintEditorToolProviderOptions): AgentToolProvider;
@@ -1688,4 +1782,4 @@ interface BlendMenuGroup {
  */
 declare const BLEND_MENU_GROUPS: readonly BlendMenuGroup[];
 
-export { type Affine, BLEND_MENU_GROUPS, BRUSH_ID, BRUSH_ROTATIONS, BRUSH_SLIDERS, BUILTIN_BRUSHES, type BlendMenuGroup, BlendMode, BlendModeInfo, type BrushDynamics, type BrushLibraryFile, type BrushRotation, type BrushThumbnail, type ColorWheel, DEFAULT_BRUSH_ID, DEFAULT_DPI, DEFAULT_DYNAMICS, DEFAULT_PAPER, DEFAULT_SWATCHES, DEFAULT_VIEW, DryStroke, type DryStrokeOptions, type FillLayerOptions, GRAIN_PATTERNS, GRAIN_TILE, type GrainPattern, type GrainTuning, HARMONY_KINDS, type Hand, type HarmonyColor, type HarmonyKind, IDENTITY_AFFINE, IDENTITY_COPY, type ImageEncoder, type ImageFormat, type ImageNode, type LayerUpdate, type Linear2, type LoadedPaintDocument, MAX_CANVAS_SIDE, MAX_COORDINATE, MAX_IMAGE_SIDE, MAX_ZOOM, MIN_CANVAS_SIDE, MIN_ZOOM, MIXING_PAD_HEIGHT, MIXING_PAD_WIDTH, MixingPad, type MixingPadTool, PAINT_BRUSH_CATEGORIES, PAINT_BRUSH_ENGINES, PAINT_FORMAT, PAINT_SCHEMA_VERSION, PAINT_TOOLS, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, PAPER_SLIDERS, type Paint2DContext, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintBrushInput, type PaintCanvas, PaintCanvasPresenter, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, PaintGesture, type PaintGroupLayer, type PaintGuides, type PaintLayer, type PaintLayerInfo, type PaintPixelLayer, type PaintPointerEvent, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintTool, type PaintView, type PaperFamily, PaperGrain, type PaperNode, type PaperSettings, type PaperTiling, type PenDab, PenDabWalker, type PenPoint, PenSmoother, type PerspectiveGuide, PerspectiveSnapper, type PixelImage, type Point2, type PointerSample, type RecordedStroke, type ReferenceImage, type RenderOptions, type ReplayOptions, type Rgb255, SNAP_DECIDE_DISTANCE, SYMMETRY_MODES, type SerializeOptions, type SerializedPaintDocument, type SliderControl, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, type Swatch, type SymmetryGuide, type SymmetryMode, TRACING_NODE_ID, TileableNoise, type TracingImage, type ViewLayer, type ViewportBox, affineCopy, applyAffine, brushToJSON, clonePaper, colorHarmony, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, decodeImageBlob, defaultGuides, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downloadBytes, downsampleRgba, fitZoom, grainCatch, grainHeights, guideOverlay, handlePaintShortcut, hash2, hexToRgb8, hslToRgb, hsvToRgb, hueToWheel, invertAffine, isPalmTouch, mapPenPoint, mix32, mixerLoadForStroke, mixerTip, newPaintLayerId, normalizeBrushStroke, normalizeCanvas, normalizeDynamics, normalizePaintBrush, normalizePaper, normalizePerspective, normalizeRotation, normalizeSymmetry, normalizeView, paperGrain, paperKey, paperNode, paperPreset, parseBrushLibrary, parseHexColor, patchPath, penOrientation, perspectiveDirections, perspectiveGuideLines, pointerToPenPoint, rand01, randSigned, readPath, renderBrushThumbnail, renderColorWheel, renderPaper, rgbToHexColor, rgbToHsl, rgbToHsv, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, symmetryAxisAngles, symmetryAxisSegments, symmetryCopies, thumbnailStroke, tiltToOrientation, toStrokePoint, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument, wheelAngle, wheelPick, wheelPoint, wheelToHue };
+export { type Affine, BLEND_MENU_GROUPS, BRUSH_ID, BRUSH_ROTATIONS, BRUSH_SLIDERS, BUILTIN_BRUSHES, type BlendMenuGroup, BlendMode, BlendModeInfo, type BrushDynamics, type BrushLibraryFile, type BrushRotation, type BrushThumbnail, type ColorWheel, DEFAULT_BRUSH_ID, DEFAULT_DPI, DEFAULT_DYNAMICS, DEFAULT_PAPER, DEFAULT_SWATCHES, DEFAULT_VIEW, DryStroke, type DryStrokeOptions, type FillLayerOptions, GRAIN_PATTERNS, GRAIN_TILE, type GrainPattern, type GrainTuning, HARMONY_KINDS, type Hand, type HarmonyColor, type HarmonyKind, IDENTITY_AFFINE, IDENTITY_COPY, type ImageEncoder, type ImageFormat, type ImageNode, type LayerUpdate, type Linear2, type LoadedPaintDocument, MAX_CANVAS_SIDE, MAX_COORDINATE, MAX_IMAGE_SIDE, MAX_ZOOM, MIN_CANVAS_SIDE, MIN_ZOOM, MIXING_PAD_HEIGHT, MIXING_PAD_WIDTH, MixingPad, type MixingPadTool, PAINT_BRUSH_CATEGORIES, PAINT_BRUSH_ENGINES, PAINT_FORMAT, PAINT_SCHEMA_VERSION, PAINT_TOOLS, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, PAPER_SLIDERS, type Paint2DContext, type PaintAgentCommand, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintBrushInput, type PaintCanvas, PaintCanvasPresenter, PaintDirector, type PaintDirectorOptions, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, PaintGesture, type PaintGroupLayer, type PaintGuides, type PaintLayer, type PaintLayerInfo, type PaintPerformanceResult, type PaintPixelLayer, type PaintPointerEvent, PaintPresence, type PaintPresenceActor, type PaintPresenceState, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintTool, type PaintView, type PaperFamily, PaperGrain, type PaperNode, type PaperSettings, type PaperTiling, type PenDab, PenDabWalker, type PenPoint, PenSmoother, type PerspectiveGuide, PerspectiveSnapper, type PixelImage, type Point2, type PointerSample, type RecordedStroke, type ReferenceImage, type RenderOptions, type ReplayOptions, type Rgb255, SNAP_DECIDE_DISTANCE, SYMMETRY_MODES, type SerializeOptions, type SerializedPaintDocument, type SliderControl, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, type Swatch, type SymmetryGuide, type SymmetryMode, TRACING_NODE_ID, TileableNoise, type TracingImage, type ViewLayer, type ViewportBox, affineCopy, applyAffine, brushToJSON, clonePaper, colorHarmony, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, decodeImageBlob, defaultGuides, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downloadBytes, downsampleRgba, fitZoom, grainCatch, grainHeights, guideOverlay, handlePaintShortcut, hash2, hexToRgb8, hslToRgb, hsvToRgb, hueToWheel, invertAffine, isPalmTouch, mapPenPoint, mix32, mixerLoadForStroke, mixerTip, newPaintLayerId, normalizeBrushStroke, normalizeCanvas, normalizeDynamics, normalizePaintBrush, normalizePaper, normalizePerspective, normalizeRotation, normalizeSymmetry, normalizeView, paperGrain, paperKey, paperNode, paperPreset, parseBrushLibrary, parseHexColor, patchPath, penOrientation, perspectiveDirections, perspectiveGuideLines, pointerToPenPoint, rand01, randSigned, readPath, renderBrushThumbnail, renderColorWheel, renderPaper, rgbToHexColor, rgbToHsl, rgbToHsv, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, strokeDuration, strokeSchedule, sweepPath, symmetryAxisAngles, symmetryAxisSegments, symmetryCopies, thumbnailStroke, tiltToOrientation, toStrokePoint, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument, wheelAngle, wheelPick, wheelPoint, wheelToHue };

package/dist/paint-editor/index.js

@@ -54,6 +54,12 @@ import {
   tileKey,
   tilesInRect
 } from "../chunk-WMBIJCHA.js";
+import {
+  PerformanceQueue,
+  PresenceStore,
+  realPresenceClock,
+  tweenPresenceCursor
+} from "../chunk-B6DSIEXA.js";
 import "../chunk-KKREERP2.js";
 
 // src/paint-editor/noise.ts
@@ -2716,6 +2722,7 @@ var PaintEditorController = class {
     else this.emit([]);
     return result;
   }
+  /** Checks stroke samples (finite x and y, pressure 0..1) and returns them; throws a sentence naming the bad point. */
   checkPoints(points) {
     if (!Array.isArray(points) || !points.length) throw new PaintEditorError("points is empty; give at least one {x, y} in document pixels.");
     const out = [];
@@ -3250,6 +3257,169 @@ function resampleInto(src, rect, width, height) {
   return { width, height, data: out };
 }
 
+// src/paint-editor/presence.ts
+var PaintPresence = class extends PresenceStore {
+};
+var FRAME = 16;
+function strokeSchedule(points) {
+  if (points.length < 2) return points.map(() => 1);
+  const t0 = points[0].t;
+  const t1 = points[points.length - 1].t;
+  if (points.every((p) => Number.isFinite(p.t)) && t1 > t0) {
+    return points.map((p) => Math.min(1, Math.max(0, (p.t - t0) / (t1 - t0))));
+  }
+  const acc = [0];
+  for (let i = 1; i < points.length; i++) acc.push(acc[i - 1] + Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y));
+  const total = acc[acc.length - 1];
+  return total > 0 ? acc.map((d) => d / total) : points.map(() => 1);
+}
+function strokeDuration(points, max = 1800) {
+  const t0 = points[0]?.t;
+  const t1 = points[points.length - 1]?.t;
+  let ms;
+  if (points.every((p) => Number.isFinite(p.t)) && t1 > t0) ms = t1 - t0;
+  else {
+    let length = 0;
+    for (let i = 1; i < points.length; i++) length += Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
+    ms = length / 1.5;
+  }
+  return Math.min(max, Math.max(250, ms));
+}
+function sweepPath(rect, rows = 4) {
+  const inset = Math.min(rect.width, rect.height) * 0.08;
+  const left = rect.x + inset;
+  const right = rect.x + rect.width - inset;
+  const out = [];
+  for (let r = 0; r < rows; r++) {
+    const y = rect.y + inset + (rect.height - 2 * inset) * (r + 0.5) / rows;
+    out.push(r % 2 ? { x: right, y } : { x: left, y }, r % 2 ? { x: left, y } : { x: right, y });
+  }
+  return out;
+}
+var centre = (r) => ({ x: r.x + r.width / 2, y: r.y + r.height / 2 });
+var PaintDirector = class {
+  constructor(controller, presence, options = {}) {
+    this.controller = controller;
+    this.presence = presence;
+    this.options = options;
+    this.clock = options.clock ?? realPresenceClock;
+    this.queue = new PerformanceQueue(presence, { clock: this.clock, linger: options.linger });
+  }
+  controller;
+  presence;
+  options;
+  clock;
+  queue;
+  /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
+  perform(actor, commands) {
+    return this.queue.run(actor, async () => {
+      const results = [];
+      for (const command of commands) {
+        try {
+          results.push({ ok: true, command, result: await this.performOne(actor.id, command) });
+        } catch (error) {
+          results.push({ ok: false, command, message: error instanceof Error ? error.message : String(error) });
+        }
+      }
+      return results;
+    });
+  }
+  ms(n) {
+    return Math.round(n / Math.max(0.1, this.options.speed ?? 1));
+  }
+  where(id) {
+    const a = this.presence.get(id);
+    return { x: a?.x ?? 0, y: a?.y ?? 0 };
+  }
+  /** Glides to `to`; an actor that just appeared starts there instead of the corner. */
+  async glide(id, to, ms = 380) {
+    const a = this.presence.get(id);
+    if (!a || a.x === 0 && a.y === 0) {
+      this.presence.set({ id, x: to.x, y: to.y });
+      return;
+    }
+    await tweenPresenceCursor(this.presence, this.clock, id, this.where(id), to, this.ms(ms));
+  }
+  async say(id, text, ms) {
+    if (!text) return;
+    this.presence.set({ id, message: text });
+    await this.clock.wait(this.ms(ms));
+  }
+  async performOne(id, command) {
+    const c = this.controller;
+    switch (command.kind) {
+      case "say":
+        await this.say(id, command.text, 900);
+        return void 0;
+      case "point":
+        await this.say(id, command.note, 500);
+        await this.glide(id, command.at);
+        this.presence.set({ id, pressed: true });
+        await this.clock.wait(this.ms(110));
+        this.presence.set({ id, pressed: false });
+        return void 0;
+      case "stroke":
+        await this.say(id, command.note, 500);
+        return this.stroke(id, command.stroke);
+      case "fill": {
+        await this.say(id, command.note, 500);
+        const { width, height } = c.getState().document.canvas;
+        const path = sweepPath({ x: 0, y: 0, width, height });
+        await this.glide(id, path[0]);
+        this.presence.set({ id, pressed: true });
+        try {
+          for (let i = 1; i < path.length; i++) await tweenPresenceCursor(this.presence, this.clock, id, path[i - 1], path[i], this.ms(i % 2 ? 260 : 90));
+        } finally {
+          this.presence.set({ id, pressed: false });
+        }
+        return c.fillLayer(command.fill);
+      }
+      case "replay": {
+        await this.say(id, command.note, 500);
+        const source = c.getStrokes().filter((s) => command.replay.strokeIds?.includes(s.id));
+        const first = source[0]?.points[0];
+        if (first) await this.glide(id, first);
+        const result = c.replayStrokes(command.replay);
+        if (result.bounds) await this.glide(id, centre(result.bounds), 520);
+        return result;
+      }
+    }
+  }
+  /** Paints a stroke live: begins it, pushes its points frame by frame as the cursor reaches them, then ends it (one undo step). */
+  async stroke(id, init) {
+    const c = this.controller;
+    const points = c.checkPoints(init.points);
+    const { points: _points, ...rest } = init;
+    const session = c.beginStroke({ snapToPerspective: false, start: points[0], ...rest });
+    try {
+      await this.glide(id, points[0]);
+      this.presence.set({ id, pressed: true });
+      const at = strokeSchedule(points);
+      const duration = this.ms(strokeDuration(points, this.options.maxStrokeMs));
+      let next = 0;
+      const frames = Math.max(1, Math.round(duration / FRAME));
+      for (let f = 1; f <= frames; f++) {
+        const t = f / frames;
+        const from = next;
+        while (next < points.length && at[next] <= t + 1e-9) next++;
+        if (next > from) {
+          session.push(points.slice(from, next));
+          const p = points[next - 1];
+          this.presence.set({ id, x: p.x, y: p.y });
+        }
+        if (f < frames) await this.clock.wait(duration / frames);
+      }
+      if (next < points.length) session.push(points.slice(next));
+      this.presence.set({ id, pressed: false });
+      return session.end();
+    } catch (error) {
+      if (c.activeStroke === session) session.cancel();
+      this.presence.set({ id, pressed: false });
+      throw error;
+    }
+  }
+};
+
 // src/paint-editor/guide-tools.ts
 var READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
@@ -3685,6 +3855,12 @@ function createPaintEditorToolProvider(controller, options = {}) {
   const c = controller;
   const tools = [];
   const add = (t) => tools.push(t);
+  const act = async (command, direct) => {
+    if (!options.director) return direct();
+    const [r] = await options.director.perform(options.actor ?? { id: "agent", name: "Agent" }, [command]);
+    if (!r || !r.ok) throw new Error(r && !r.ok ? r.message : "The director did not run the command.");
+    return r.result;
+  };
   add({
     name: "get_canvas_info",
     title: "Get the canvas",
@@ -3949,7 +4125,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Fill a layer", ...WRITE2 },
-    handler: (a) => c.fillLayer(a)
+    handler: (a) => act({ kind: "fill", fill: a }, () => c.fillLayer(a))
   });
   add({
     name: "clear_layer",
@@ -4132,7 +4308,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "paint_stroke",
     title: "Paint a brush stroke",
-    description: "Paints one stroke through points (document pixels, with optional pressure, time, tilt and barrel rotation) on a pixel layer with a library brush or the active one, optionally changed for this stroke. Grain-responsive brushes follow the paper; the mixer engine (mixer-brush, blender, smudge) picks up and moves paint already on the layer. The symmetry guide adds its mirror copies; with a tracing image that samples colours, a stroke without color takes the image colour at its first point. One undo step. Returns the layer id, changed bounds, dab count, the recorded strokeId (for replay_strokes) and, for the mixer, its load after the stroke.",
+    description: "Paints one stroke through points (document pixels, with optional pressure, time, tilt and barrel rotation) on a pixel layer with a library brush or the active one, optionally changed for this stroke. Grain-responsive brushes follow the paper; the mixer engine (mixer-brush, blender, smudge) picks up and moves paint already on the layer. The symmetry guide adds its mirror copies; with a tracing image that samples colours, a stroke without color takes the image colour at its first point. With an agent cursor (a director), the stroke is painted live along the points at the pace of their times. One undo step. Returns the layer id, changed bounds, dab count, the recorded strokeId (for replay_strokes) and, for the mixer, its load after the stroke.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4148,8 +4324,9 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Paint a brush stroke", ...WRITE2 },
-    handler: (a) => {
-      const r = c.paintStroke({ points: a.points, layerId: a.layerId, brushId: a.brushId, brush: a.brush, color: a.color, seed: a.seed, snapToPerspective: a.snapToPerspective });
+    handler: async (a) => {
+      const stroke = { points: a.points, layerId: a.layerId, brushId: a.brushId, brush: a.brush, color: a.color, seed: a.seed, snapToPerspective: a.snapToPerspective };
+      const r = await act({ kind: "stroke", stroke }, () => c.paintStroke(stroke));
       return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
     }
   });
@@ -4223,7 +4400,10 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Replay strokes, varied", ...WRITE2 },
-    handler: (a) => c.replayStrokes(a)
+    handler: (a) => {
+      const replay = a;
+      return act({ kind: "replay", replay }, () => c.replayStrokes(replay));
+    }
   });
   add({
     name: "set_view",
@@ -4675,10 +4855,12 @@ export {
   PAPER_NODE_ID,
   PAPER_SLIDERS,
   PaintCanvasPresenter,
+  PaintDirector,
   PaintDocumentError,
   PaintEditorController,
   PaintEditorError,
   PaintGesture,
+  PaintPresence,
   PaintStrokeSession,
   PaperGrain,
   PenDabWalker,
@@ -4762,6 +4944,9 @@ export {
   serializePaintDocumentExternal,
   standardBlendMode,
   strokeBounds,
+  strokeDuration,
+  strokeSchedule,
+  sweepPath,
   symmetryAxisAngles,
   symmetryAxisSegments,
   symmetryCopies,