@ps-generator-bridge/sdk 0.1.0

package/dist/PsPhotoshopProxy-BjnvziWn.d.cts

@@ -0,0 +1,879 @@
+/**
+ * The wire contract shared by the SDK client and the server.
+ *
+ * This package is the single source of truth for the protocol (ADR 0001): the
+ * server depends on this module type-only and implements the same shapes. To add
+ * a server capability, model it here first (a new entry in `ProtocolMethods`),
+ * then implement it on the server and expose a method on the client.
+ */
+/** Bumped on any breaking change to the envelope or method shapes. */
+declare const PROTOCOL_VERSION = 1;
+/**
+ * Request method names shared by the sdk type surface and generator registration.
+ * Keep new built-in/module Request names here first, then reference these
+ * constants from server decorators so the Protocol remains the source of truth.
+ */
+declare const ProtocolMethod: {
+    readonly GetServerInfo: "getServerInfo";
+    readonly JsxRun: "jsx:run";
+    readonly JsxExecute: "jsx:execute";
+    readonly EventSubscribe: "event:subscribe";
+    readonly EventUnsubscribe: "event:unsubscribe";
+    readonly ActionAutoCutout: "action:autoCutout";
+    readonly ActionRemoveBackground: "action:removeBackground";
+    readonly LayerGetInfo: "layer:getInfo";
+    readonly LayerGetInfoById: "layer:getInfoById";
+    readonly LayerGetInfoByIndex: "layer:getInfoByIndex";
+    readonly DocumentCurrent: "document:current";
+    readonly DocumentExport: "document:export";
+    readonly DocumentSave: "document:save";
+    readonly ImageExportLayer: "image:exportLayer";
+    readonly ImageGetPreview: "image:getPreview";
+    readonly ImageExportDocument: "image:exportDocument";
+};
+type ProtocolMethod = (typeof ProtocolMethod)[keyof typeof ProtocolMethod];
+/** Every method the server exposes, keyed by name -> { params, result }. */
+interface ProtocolMethods {
+    [ProtocolMethod.GetServerInfo]: {
+        params: Record<string, never>;
+        result: ServerInfo;
+    };
+    [ProtocolMethod.JsxRun]: {
+        params: {
+            script: string;
+        };
+        result: unknown;
+    };
+    [ProtocolMethod.JsxExecute]: {
+        params: {
+            name: string;
+            params?: Record<string, unknown>;
+        };
+        result: unknown;
+    };
+    [ProtocolMethod.EventSubscribe]: {
+        params: {
+            type: PhotoshopEventName;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    [ProtocolMethod.EventUnsubscribe]: {
+        params: {
+            type: PhotoshopEventName;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    [ProtocolMethod.ActionAutoCutout]: {
+        params: Record<string, never>;
+        result: boolean;
+    };
+    [ProtocolMethod.ActionRemoveBackground]: {
+        params: Record<string, never>;
+        result: {
+            success: boolean;
+        };
+    };
+    [ProtocolMethod.LayerGetInfo]: {
+        params?: {
+            id?: number;
+            index?: number;
+            getChildren?: boolean;
+            getGeneratorSettings?: boolean;
+        };
+        result: PsLayer;
+    };
+    [ProtocolMethod.LayerGetInfoById]: {
+        params: {
+            layerID: number;
+            options?: {
+                getChildren: boolean;
+            };
+        };
+        result: PsLayer;
+    };
+    [ProtocolMethod.LayerGetInfoByIndex]: {
+        params: {
+            layerIndex: number;
+            options?: {
+                getChildren: boolean;
+            };
+        };
+        result: PsLayer;
+    };
+    [ProtocolMethod.DocumentCurrent]: {
+        params: Record<string, never>;
+        result: PsDocument;
+    };
+    [ProtocolMethod.DocumentExport]: {
+        params: {
+            filePath: string;
+        } & Record<string, unknown>;
+        result: unknown;
+    };
+    [ProtocolMethod.DocumentSave]: {
+        params: {
+            savePath?: string;
+        };
+        result: unknown;
+    };
+    [ProtocolMethod.ImageExportLayer]: {
+        params: {
+            documentId?: number;
+            layerSpec: LayerSpec;
+            settings?: Record<string, unknown>;
+        };
+        result: WsImageResult;
+    };
+    [ProtocolMethod.ImageGetPreview]: {
+        params: {
+            documentId?: number;
+            layerSpec: number;
+        };
+        result: WsImageResult;
+    };
+    [ProtocolMethod.ImageExportDocument]: {
+        params: {
+            documentId?: number;
+            settings?: Record<string, unknown>;
+        };
+        result: WsImageResult;
+    };
+}
+type MethodName = keyof ProtocolMethods;
+/**
+ * A layer spec: either a layer id, or an index range plus the indices of layers
+ * to hide (the form Photoshop's `getLayerPixmap.jsx` accepts). Modeled here as a
+ * wire type (RFC 0008) so the protocol is self-contained; the generator's image
+ * module re-exports it for its plugin-facing API.
+ */
+type LayerSpec = number | {
+    firstLayerIndex: number;
+    lastLayerIndex: number;
+    hidden: number[];
+};
+interface PsRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface PsLayer {
+    id: number;
+    index: number;
+    name: string;
+    type: number;
+    visible: boolean;
+    bounds: PsBounds$1;
+    rect: PsRect;
+    clip: boolean;
+    children?: PsLayer[];
+}
+interface PsDocument {
+    id: number;
+    name: string;
+    width: number;
+    height: number;
+    resolution: number;
+    isDirty: boolean;
+    filePath?: string;
+}
+/**
+ * The result of an image `@ws` method (RFC 0008). `data` is an out-of-the-box
+ * image string the client can drop straight into an `<img src>`:
+ * `data:image/png;base64,...` when inlined, or `https://...` when a `CosService`
+ * uploaded it. The client tells them apart by the `data`/`http` prefix — there
+ * is deliberately no separate discriminator field. `bounds`/`width`/`height`
+ * carry the same geometry as the module-internal `ImageResult`.
+ */
+interface WsImageResult {
+    data: string;
+    bounds: PsBounds$1;
+    width: number;
+    height: number;
+}
+interface PsBounds$1 {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+interface ServerInfo {
+    name: string;
+    version: string;
+    /** Photoshop version, when the server is connected to PS; omitted otherwise. */
+    psVersion?: string;
+    plugins?: PluginInfo[];
+}
+interface PluginInfo {
+    id: string;
+}
+interface Bounds {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+interface ImageChangedLayer {
+    id: number;
+    pixels?: boolean;
+    removed?: boolean;
+    bounds?: Bounds;
+}
+interface ImageChangedEvent {
+    version: string;
+    timeStamp: number;
+    count: number;
+    id: number;
+    active?: boolean;
+    file?: string;
+    closed?: boolean;
+    metaDataOnly?: boolean;
+    selection?: number[];
+    layers?: ImageChangedLayer[];
+}
+interface PhotoshopEventMap {
+    workspaceChanged: string;
+    toolChanged: string;
+    quickMaskStateChanged: string;
+    documentChanged: number;
+    closedDocument: number;
+    newDocumentViewCreated: number;
+    activeViewChanged: number;
+    currentDocumentChanged: number;
+    backgroundColorChanged: string;
+    foregroundColorChanged: string;
+    imageChanged: ImageChangedEvent;
+}
+type PhotoshopEventName = keyof PhotoshopEventMap;
+/** A request envelope sent client -> server. */
+interface RequestEnvelope<M extends MethodName = MethodName> {
+    id: string;
+    method: M;
+    params: ProtocolMethods[M]["params"];
+}
+/** A response envelope sent server -> client. */
+type ResponseEnvelope<M extends MethodName = MethodName> = {
+    id: string;
+    ok: true;
+    result: ProtocolMethods[M]["result"];
+} | {
+    id: string;
+    ok: false;
+    error: ProtocolError;
+};
+/**
+ * Every server -> client push event, keyed by type -> data payload. Open-ended
+ * (ADR 0006): declared keys are strongly typed; an undeclared `type` still flows
+ * through the looser `on(type: string, ...)` / `EventEnvelope` overloads.
+ */
+interface ProtocolEvents {
+    /** Handshake: the first event after a socket opens, carrying the clientId. */
+    connected: {
+        clientId: string;
+    };
+    workspaceChanged: PhotoshopEventMap["workspaceChanged"];
+    toolChanged: PhotoshopEventMap["toolChanged"];
+    quickMaskStateChanged: PhotoshopEventMap["quickMaskStateChanged"];
+    documentChanged: PhotoshopEventMap["documentChanged"];
+    closedDocument: PhotoshopEventMap["closedDocument"];
+    newDocumentViewCreated: PhotoshopEventMap["newDocumentViewCreated"];
+    activeViewChanged: PhotoshopEventMap["activeViewChanged"];
+    currentDocumentChanged: PhotoshopEventMap["currentDocumentChanged"];
+    backgroundColorChanged: PhotoshopEventMap["backgroundColorChanged"];
+    foregroundColorChanged: PhotoshopEventMap["foregroundColorChanged"];
+    imageChanged: PhotoshopEventMap["imageChanged"];
+}
+type EventName = keyof ProtocolEvents;
+/** A one-way event envelope sent server -> client (no id, no response). */
+interface EventEnvelope<E extends EventName = EventName> {
+    type: E;
+    data: ProtocolEvents[E];
+}
+interface ProtocolError {
+    /**
+     * Error code. Server-level codes are values of `ErrorCode`; a plugin may throw
+     * its own code (defined in its package), which the server surfaces verbatim
+     * (open-ended contract, RFC 0006). Typed here as `string` to admit both.
+     */
+    code: string;
+    message: string;
+}
+/**
+ * Server-level error codes. Plugin-specific codes (e.g. SidePaint's
+ * `PAINT_GONE`/`IMPORT_FAILED`/`VALUE_RESOLVE`/`UNSUPPORTED_SCHEME`) live in
+ * their plugin package since RFC 0006 and are surfaced verbatim by the server.
+ */
+declare const ErrorCode: {
+    readonly UnknownMethod: "UNKNOWN_METHOD";
+    readonly BadRequest: "BAD_REQUEST";
+    readonly Internal: "INTERNAL";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Frame discriminators shared by both ends (ADR 0005). The three envelope kinds
+ * are told apart by characteristic fields: Request has `method`, Response has a
+ * boolean `ok`, Event has `type` and no `id`.
+ */
+declare function isRequest(value: unknown): value is RequestEnvelope;
+declare function isResponse(value: unknown): value is ResponseEnvelope;
+declare function isEvent(value: unknown): value is EventEnvelope;
+/** Decode a raw text frame. Throws on invalid JSON. Shared by both ends. */
+declare function parseFrame(data: string): unknown;
+/** Encode a value into a text frame. Shared by both ends. */
+declare function serializeFrame(value: unknown): string;
+
+/**
+ * The minimal slice of a JSX runner the Photoshop DOM proxy depends on: run a
+ * raw ExtendScript string and resolve its evaluation result. Defined locally
+ * (not imported from the generator contract) so the proxy stays transport- and
+ * host-agnostic and can be wired to any backend that can evaluate a script.
+ *
+ * The server's `JsxRunnerApi` satisfies this structurally (`plugin.jsx`), so a
+ * plugin passes `this.jsx` straight in. A future client-side backend would
+ * supply its own adapter.
+ */
+interface PsJsxRunner {
+    run<T = unknown>(script: string): Promise<T>;
+}
+
+/**
+ * Photoshop DOM enum constants. Each value is the ExtendScript global enum name
+ * string, embeddable directly into a JSX fragment.
+ *
+ * @example
+ * await this.photoshop.activeDocument.close(SaveOptions.DONOTSAVECHANGES);
+ * // emits JSX: app.activeDocument.close(SaveOptions.DONOTSAVECHANGES)
+ */
+declare const SaveOptions: {
+    /** Do not save changes. */
+    readonly DONOTSAVECHANGES: "SaveOptions.DONOTSAVECHANGES";
+    /** Prompt the user. */
+    readonly PROMPTTOSAVECHANGES: "SaveOptions.PROMPTTOSAVECHANGES";
+    /** Save changes. */
+    readonly SAVECHANGES: "SaveOptions.SAVECHANGES";
+};
+type SaveOptionsValue = (typeof SaveOptions)[keyof typeof SaveOptions];
+declare const LayerKind: {
+    readonly NORMAL: "LayerKind.NORMAL";
+    readonly TEXT: "LayerKind.TEXT";
+    readonly SMARTOBJECT: "LayerKind.SMARTOBJECT";
+    readonly SOLIDFILL: "LayerKind.SOLIDFILL";
+    /**
+     * @remarks In `enums.d.ts`, GRADIENTFILL=4 and PATTERNFILL=4 share a value
+     * (an Adobe enum conflict); a kind of 4 always maps back to GRADIENTFILL and
+     * the two cannot be told apart at runtime (disambiguate by layer name etc.).
+     */
+    readonly GRADIENTFILL: "LayerKind.GRADIENTFILL";
+    readonly PATTERNFILL: "LayerKind.PATTERNFILL";
+    readonly LEVELS: "LayerKind.LEVELS";
+    readonly CURVES: "LayerKind.CURVES";
+    readonly BRIGHTNESSCONTRAST: "LayerKind.BRIGHTNESSCONTRAST";
+    readonly HUESATURATION: "LayerKind.HUESATURATION";
+    readonly COLORBALANCE: "LayerKind.COLORBALANCE";
+    readonly INVERSION: "LayerKind.INVERSION";
+    readonly POSTERIZE: "LayerKind.POSTERIZE";
+    readonly THRESHOLD: "LayerKind.THRESHOLD";
+    readonly EXPOSURE: "LayerKind.EXPOSURE";
+    readonly VIBRANCE: "LayerKind.VIBRANCE";
+    readonly VIDEO: "LayerKind.VIDEO";
+    readonly LAYER3D: "LayerKind.LAYER3D";
+    readonly BLACKANDWHITE: "LayerKind.BLACKANDWHITE";
+    readonly CHANNELMIXER: "LayerKind.CHANNELMIXER";
+    readonly GRADIENTMAP: "LayerKind.GRADIENTMAP";
+    readonly SELECTIVECOLOR: "LayerKind.SELECTIVECOLOR";
+    readonly PHOTOFILTER: "LayerKind.PHOTOFILTER";
+    readonly COLORLOOKUP: "LayerKind.COLORLOOKUP";
+};
+type LayerKindValue = (typeof LayerKind)[keyof typeof LayerKind];
+declare const BlendMode: {
+    readonly NORMAL: "BlendMode.NORMAL";
+    readonly DISSOLVE: "BlendMode.DISSOLVE";
+    readonly DARKEN: "BlendMode.DARKEN";
+    readonly MULTIPLY: "BlendMode.MULTIPLY";
+    readonly COLORBURN: "BlendMode.COLORBURN";
+    readonly LINEARBURN: "BlendMode.LINEARBURN";
+    readonly DARKERCOLOR: "BlendMode.DARKERCOLOR";
+    readonly LIGHTEN: "BlendMode.LIGHTEN";
+    readonly SCREEN: "BlendMode.SCREEN";
+    readonly COLORDODGE: "BlendMode.COLORDODGE";
+    readonly LINEARDODGE: "BlendMode.LINEARDODGE";
+    readonly LIGHTERCOLOR: "BlendMode.LIGHTERCOLOR";
+    readonly OVERLAY: "BlendMode.OVERLAY";
+    readonly SOFTLIGHT: "BlendMode.SOFTLIGHT";
+    readonly HARDLIGHT: "BlendMode.HARDLIGHT";
+    readonly VIVIDLIGHT: "BlendMode.VIVIDLIGHT";
+    readonly LINEARLIGHT: "BlendMode.LINEARLIGHT";
+    readonly PINLIGHT: "BlendMode.PINLIGHT";
+    readonly HARDMIX: "BlendMode.HARDMIX";
+    readonly DIFFERENCE: "BlendMode.DIFFERENCE";
+    readonly EXCLUSION: "BlendMode.EXCLUSION";
+    readonly SUBTRACT: "BlendMode.SUBTRACT";
+    readonly DIVIDE: "BlendMode.DIVIDE";
+    readonly HUE: "BlendMode.HUE";
+    readonly SATURATION: "BlendMode.SATURATION";
+    readonly COLORBLEND: "BlendMode.COLORBLEND";
+    readonly LUMINOSITY: "BlendMode.LUMINOSITY";
+    readonly PASSTHROUGH: "BlendMode.PASSTHROUGH";
+};
+type BlendModeValue = (typeof BlendMode)[keyof typeof BlendMode];
+declare const ElementPlacement: {
+    readonly PLACEATBEGINNING: "ElementPlacement.PLACEATBEGINNING";
+    readonly PLACEINSIDE: "ElementPlacement.PLACEINSIDE";
+    readonly PLACEBEFORE: "ElementPlacement.PLACEBEFORE";
+    readonly PLACEAFTER: "ElementPlacement.PLACEAFTER";
+    readonly PLACEATEND: "ElementPlacement.PLACEATEND";
+};
+type ElementPlacementValue = (typeof ElementPlacement)[keyof typeof ElementPlacement];
+declare const AnchorPosition: {
+    readonly TOPLEFT: "AnchorPosition.TOPLEFT";
+    readonly TOPCENTER: "AnchorPosition.TOPCENTER";
+    readonly TOPRIGHT: "AnchorPosition.TOPRIGHT";
+    readonly MIDDLELEFT: "AnchorPosition.MIDDLELEFT";
+    readonly MIDDLECENTER: "AnchorPosition.MIDDLECENTER";
+    readonly MIDDLERIGHT: "AnchorPosition.MIDDLERIGHT";
+    readonly BOTTOMLEFT: "AnchorPosition.BOTTOMLEFT";
+    readonly BOTTOMCENTER: "AnchorPosition.BOTTOMCENTER";
+    readonly BOTTOMRIGHT: "AnchorPosition.BOTTOMRIGHT";
+};
+type AnchorPositionValue = (typeof AnchorPosition)[keyof typeof AnchorPosition];
+declare const DocumentMode: {
+    readonly BITMAP: "DocumentMode.BITMAP";
+    readonly GRAYSCALE: "DocumentMode.GRAYSCALE";
+    readonly RGB: "DocumentMode.RGB";
+    readonly CMYK: "DocumentMode.CMYK";
+    readonly LAB: "DocumentMode.LAB";
+    readonly INDEXEDCOLOR: "DocumentMode.INDEXEDCOLOR";
+    readonly MULTICHANNEL: "DocumentMode.MULTICHANNEL";
+    readonly DUOTONE: "DocumentMode.DUOTONE";
+};
+type DocumentModeValue = (typeof DocumentMode)[keyof typeof DocumentMode];
+declare const SelectionType: {
+    readonly REPLACE: "SelectionType.REPLACE";
+    readonly EXTEND: "SelectionType.EXTEND";
+    readonly DIMINISH: "SelectionType.DIMINISH";
+    readonly INTERSECT: "SelectionType.INTERSECT";
+};
+type SelectionTypeValue = (typeof SelectionType)[keyof typeof SelectionType];
+
+/**
+ * A bounding rectangle `[left, top, right, bottom]`.
+ *
+ * @remarks Units follow Photoshop's current `rulerUnits` setting; values are not
+ * guaranteed to be pixels unless `rulerUnits` is `Units.PIXELS`.
+ */
+type PsBounds = [number, number, number, number];
+/**
+ * A simplified SolidColor representation. The first version only fills `rgb`;
+ * in CMYK/Lab documents that RGB is Photoshop's automatic approximation. The
+ * `cmyk` field is reserved for a later version and is currently always omitted.
+ */
+interface PsColor {
+    model: "rgb" | "cmyk" | "hsb" | "lab" | "gray";
+    rgb?: {
+        red: number;
+        green: number;
+        blue: number;
+        hexValue?: string;
+    };
+    cmyk?: {
+        cyan: number;
+        magenta: number;
+        yellow: number;
+        black: number;
+    };
+}
+
+/**
+ * Wraps an ExtendScript Layer / ArtLayer / LayerSet: the shared Layer
+ * properties and methods plus ArtLayer-only members such as `kind`.
+ *
+ * @remarks
+ * `activeLayer` may be an ArtLayer or a LayerSet. Read `typename` before
+ * touching ArtLayer-only members:
+ * - "ArtLayer" -> a normal layer, `kind` is valid
+ * - "LayerSet" -> a group, `kind` is unavailable
+ *
+ * @example
+ * const layer = this.photoshop.activeDocument.activeLayer;
+ * const name = await layer.name;
+ * await layer.setName("Background");
+ * await layer.setVisible(false);
+ */
+declare class PhotoshopLayer {
+    private readonly _jsx;
+    private readonly _path;
+    constructor(_jsx: PsJsxRunner, _path: string);
+    /** Unique layer id. */
+    get id(): Promise<number>;
+    /** Layer name. */
+    get name(): Promise<string>;
+    /** Layer visibility. */
+    get visible(): Promise<boolean>;
+    /** Layer opacity (0-100). */
+    get opacity(): Promise<number>;
+    /** BlendMode code -> enum-name map (all 27 members, plus newer ones). */
+    private static readonly _BLEND_MODE_MAP;
+    /**
+     * Blend mode as an enum-name string (e.g. "BlendMode.NORMAL"). ExtendScript
+     * yields the numeric code; the static map turns it into a readable name.
+     */
+    get blendMode(): Promise<string>;
+    /** Whether the layer is fully locked. */
+    get allLocked(): Promise<boolean>;
+    /**
+     * Layer bounds `[left, top, right, bottom]`.
+     *
+     * @remarks Units follow `rulerUnits`; values are not pixels unless it is
+     * `Units.PIXELS`.
+     */
+    get bounds(): Promise<PsBounds>;
+    /** LayerKind code -> enum-name map. */
+    private static readonly _LAYER_KIND_MAP;
+    /**
+     * Layer kind as an enum-name string (e.g. "LayerKind.NORMAL"). ArtLayer only;
+     * reading it on a LayerSet throws. Check `typename` first.
+     *
+     * @remarks GRADIENTFILL=4 and PATTERNFILL=4 collide in Adobe's enums, so a
+     * kind of 4 always maps to GRADIENTFILL.
+     */
+    get kind(): Promise<string>;
+    /** Object type name ("ArtLayer" or "LayerSet"). */
+    get typename(): Promise<string>;
+    /** Set the layer name. */
+    setName(value: string): Promise<void>;
+    /** Set layer visibility. */
+    setVisible(value: boolean): Promise<void>;
+    /** Set layer opacity (0-100). */
+    setOpacity(value: number): Promise<void>;
+    /**
+     * Set the blend mode.
+     *
+     * @example
+     * import { BlendMode } from "@ps-generator-bridge/sdk/plugin";
+     * await layer.setBlendMode(BlendMode.MULTIPLY);
+     */
+    setBlendMode(value: BlendModeValue): Promise<void>;
+    /** Set whether the layer is fully locked. */
+    setAllLocked(value: boolean): Promise<void>;
+    /** Delete this layer. */
+    remove(): Promise<void>;
+    /** Duplicate this layer (the copy becomes `activeLayer`). */
+    duplicate(): Promise<PhotoshopLayer>;
+    /**
+     * Move this layer relative to another.
+     *
+     * @param relativeObjectJsxPath JSX path of the reference layer (e.g.
+     *   "app.activeDocument.layers[0]").
+     * @param insertionLocation placement enum.
+     *
+     * @remarks Pass a bare JSX path expression. A `PhotoshopLayers.getByName()`
+     * path contains quotes and cannot be used as a reference expression here.
+     *
+     * @example
+     * import { ElementPlacement } from "@ps-generator-bridge/sdk/plugin";
+     * await layer.move("app.activeDocument.layers[0]", ElementPlacement.PLACEBEFORE);
+     */
+    move(relativeObjectJsxPath: string, insertionLocation: ElementPlacementValue): Promise<void>;
+    /** Translate the layer by a pixel delta. */
+    translate(deltaX: number, deltaY: number): Promise<void>;
+    /**
+     * Scale the layer.
+     *
+     * @param horizontal horizontal scale percent (150 = 150%).
+     * @param vertical vertical scale percent.
+     * @param anchor scaling anchor (optional).
+     */
+    resize(horizontal: number, vertical: number, anchor?: AnchorPositionValue): Promise<void>;
+    /**
+     * Rotate the layer.
+     *
+     * @param angle degrees, clockwise positive.
+     * @param anchor rotation anchor (optional).
+     */
+    rotate(angle: number, anchor?: AnchorPositionValue): Promise<void>;
+    /** Move the layer to the end of its stack. */
+    moveToEnd(): Promise<void>;
+}
+
+/**
+ * Wraps an ExtendScript Layers collection (`Document.layers` or
+ * `LayerSet.layers`).
+ *
+ * @example
+ * const layers = this.photoshop.activeDocument.layers;
+ * const count = await layers.length;
+ * const first = layers.at(0);
+ * const named = layers.getByName("Background");
+ */
+declare class PhotoshopLayers {
+    private readonly _jsx;
+    private readonly _path;
+    constructor(_jsx: PsJsxRunner, _path: string);
+    /** Number of layers in the collection. */
+    get length(): Promise<number>;
+    /**
+     * Access a layer by index. The collection is 0-based, matching JavaScript;
+     * `layers[0]` is the top-most layer.
+     */
+    at(index: number): PhotoshopLayer;
+    /**
+     * Look up a layer by name (case-sensitive). The returned wrapper works for
+     * property reads/writes but its path contains a `getByName(...)` call, so it
+     * must not be passed as `PhotoshopLayer.move()`'s reference path.
+     */
+    getByName(name: string): PhotoshopLayer;
+}
+
+/**
+ * Wraps `Document.selection`.
+ *
+ * @example
+ * const sel = this.photoshop.activeDocument.selection;
+ * await sel.selectAll();
+ * const bounds = await sel.bounds;
+ * await sel.deselect();
+ */
+declare class PhotoshopSelection {
+    private readonly _jsx;
+    private readonly _path;
+    constructor(_jsx: PsJsxRunner, _path: string);
+    /**
+     * Selection bounds `[left, top, right, bottom]`. Throws when there is no
+     * selection.
+     *
+     * @remarks Units follow `rulerUnits`.
+     */
+    get bounds(): Promise<PsBounds>;
+    /** Whether the selection is a solid (un-feathered) rectangle. */
+    get solid(): Promise<boolean>;
+    /** Select the whole canvas. */
+    selectAll(): Promise<void>;
+    /** Deselect. */
+    deselect(): Promise<void>;
+    /** Invert the selection. */
+    invert(): Promise<void>;
+    /**
+     * Create a selection from a region of points.
+     *
+     * @param region polygon points, e.g. `[[0,0],[100,0],[100,100],[0,100]]`.
+     * @param type selection operation (optional, defaults to replace).
+     * @param feather feather radius in pixels (optional).
+     * @param antiAlias anti-alias the edges (optional).
+     *
+     * @example
+     * import { SelectionType } from "@ps-generator-bridge/sdk/plugin";
+     * await sel.select([[0,0],[100,0],[100,100],[0,100]], SelectionType.REPLACE, 0, true);
+     */
+    select(region: number[][], type?: SelectionTypeValue, feather?: number, antiAlias?: boolean): Promise<void>;
+    /** Grow the selection by `by` pixels. */
+    expand(by: number): Promise<void>;
+    /** Shrink the selection by `by` pixels. */
+    contract(by: number): Promise<void>;
+    /** Feather the selection edge by `by` pixels. */
+    feather(by: number): Promise<void>;
+    /** Translate the selection boundary (content stays put). */
+    translateBoundary(deltaX: number, deltaY: number): Promise<void>;
+}
+
+/**
+ * Wraps an ExtendScript Document.
+ *
+ * @example
+ * const doc = this.photoshop.activeDocument;
+ * const name = await doc.name;
+ * const [width, height] = await Promise.all([doc.width, doc.height]);
+ * await doc.save();
+ */
+declare class PhotoshopDocument {
+    private readonly _jsx;
+    private readonly _path;
+    constructor(_jsx: PsJsxRunner, _path: string);
+    /** Document name (file name, without directory). */
+    get name(): Promise<string>;
+    /** Unique document id. */
+    get id(): Promise<number>;
+    /**
+     * Document width.
+     *
+     * @remarks The unit follows Photoshop's current `app.preferences.rulerUnits`.
+     * For guaranteed pixels, set `rulerUnits` to `Units.PIXELS` first (e.g. via
+     * `this.jsx.run(...)`).
+     */
+    get width(): Promise<number>;
+    /**
+     * Document height.
+     *
+     * @remarks The unit follows `rulerUnits` (see {@link width}).
+     */
+    get height(): Promise<number>;
+    /** Document resolution (PPI). */
+    get resolution(): Promise<number>;
+    /** Document color mode as an enum-name string (e.g. "DocumentMode.RGB"). */
+    get mode(): Promise<string>;
+    /** Whether the document is saved since its last change. */
+    get saved(): Promise<boolean>;
+    /**
+     * Full document path (native `fsName`). For an unsaved document this may
+     * return a temporary path or throw.
+     */
+    get fullName(): Promise<string>;
+    /** Directory containing the document (native `fsName`). */
+    get path(): Promise<string>;
+    /** The active layer. */
+    get activeLayer(): PhotoshopLayer;
+    /** The Layers collection (ArtLayers + LayerSets). */
+    get layers(): PhotoshopLayers;
+    /** The selection. */
+    get selection(): PhotoshopSelection;
+    /** Save the document in its current format. */
+    save(): Promise<void>;
+    /**
+     * Close the document.
+     *
+     * @param saving save behavior before closing (defaults to not saving).
+     *
+     * @example
+     * import { SaveOptions } from "@ps-generator-bridge/sdk/plugin";
+     * await doc.close(SaveOptions.DONOTSAVECHANGES);
+     */
+    close(saving?: SaveOptionsValue): Promise<void>;
+    /**
+     * Save to a path. Mirrors ExtendScript
+     * `saveAs(saveIn, options?, asCopy?, extensionType?)`; only `saveIn` and
+     * `asCopy` are exposed, `options` is undefined and `extensionType` is left to
+     * the Photoshop default.
+     *
+     * @param saveIn destination path.
+     * @param asCopy save as a copy (does not change the document's saved state).
+     */
+    saveAs(saveIn: string, asCopy?: boolean): Promise<void>;
+    /** Flatten all layers into a single background layer. */
+    flatten(): Promise<void>;
+    /** Merge all visible layers. */
+    mergeVisibleLayers(): Promise<void>;
+    /** Rasterize all layers. */
+    rasterizeAllLayers(): Promise<void>;
+    /**
+     * Duplicate the document.
+     *
+     * @param name optional name for the copy.
+     * @returns the duplicated document.
+     *
+     * @remarks Assumes `duplicate()` makes the copy the active document, so the
+     * result points at `app.activeDocument`.
+     */
+    duplicate(name?: string): Promise<PhotoshopDocument>;
+    /**
+     * Resize the canvas.
+     *
+     * @param width new width in pixels.
+     * @param height new height in pixels.
+     * @param anchor anchor position (optional, defaults to center).
+     *
+     * @example
+     * import { AnchorPosition } from "@ps-generator-bridge/sdk/plugin";
+     * await doc.resizeCanvas(1920, 1080, AnchorPosition.MIDDLECENTER);
+     */
+    resizeCanvas(width: number, height: number, anchor?: string): Promise<void>;
+    /**
+     * Resize the image.
+     *
+     * @param width new width in pixels (optional).
+     * @param height new height in pixels (optional).
+     * @param resolution new resolution in PPI (optional).
+     */
+    resizeImage(width?: number, height?: number, resolution?: number): Promise<void>;
+    /** Rotate the canvas by `angle` degrees. */
+    rotateCanvas(angle: number): Promise<void>;
+    /**
+     * Crop the document to `bounds` `[left, top, right, bottom]` (pixels).
+     *
+     * @remarks Only `bounds` is exposed; ExtendScript `crop()` also takes angle,
+     * width and height — reach those via `this.jsx.run(...)` if needed.
+     */
+    crop(bounds: PsBounds): Promise<void>;
+}
+
+/**
+ * Wraps the ExtendScript global `app` object.
+ *
+ * @example
+ * const version = await this.photoshop.app.version; // "25.0"
+ * await this.photoshop.app.open("/path/to/design.psd");
+ */
+declare class PhotoshopApp {
+    private readonly _jsx;
+    private readonly _path;
+    constructor(_jsx: PsJsxRunner);
+    /** Photoshop version (e.g. "25.0"). */
+    get version(): Promise<string>;
+    /** Application locale (e.g. "zh_CN"). */
+    get locale(): Promise<string>;
+    /** Application name (e.g. "Adobe Photoshop"). */
+    get name(): Promise<string>;
+    /** Internal build number. */
+    get build(): Promise<string>;
+    /**
+     * Install path (native `fsName`). `app.path` is a File in ExtendScript, so the
+     * string comes from `.fsName`.
+     */
+    get path(): Promise<string>;
+    /**
+     * Current foreground color (RGB).
+     *
+     * @remarks The first version returns only the RGB approximation; in CMYK/Lab
+     * documents this is Photoshop's converted RGB and may lose precision. The
+     * `cmyk` field is reserved and currently always undefined.
+     */
+    get foregroundColor(): Promise<PsColor>;
+    /** Shortcut for `activeDocument` reached through the `app` path. */
+    get activeDocument(): PhotoshopDocument;
+    /**
+     * Open a file and return its Document wrapper. The opened document becomes the
+     * active document.
+     *
+     * @param filePath native or POSIX path.
+     *
+     * @example
+     * const doc = await this.photoshop.app.open("/Users/me/design.psd");
+     */
+    open(filePath: string): Promise<PhotoshopDocument>;
+    /** Emit a beep. */
+    beep(): Promise<void>;
+}
+
+/**
+ * Entry point of the Photoshop DOM proxy. A plugin reaches it through
+ * `this.photoshop`:
+ *
+ * ```ts
+ * const version = await this.photoshop.app.version;
+ * const name = await this.photoshop.activeDocument.name;
+ * ```
+ *
+ * Transport-agnostic: every property read and method call lowers to an
+ * ExtendScript string run through the injected {@link PsJsxRunner}. The proxy
+ * holds no PS state of its own.
+ *
+ * @remarks
+ * - `app` maps to the ExtendScript global `app` (Application).
+ * - `activeDocument` is a shortcut for `app.activeDocument`.
+ * - With no active document, reading any property of `activeDocument` throws.
+ */
+declare class PsPhotoshopProxy {
+    /** Application wrapper; its path is fixed to "app". */
+    readonly app: PhotoshopApp;
+    private readonly _jsx;
+    constructor(jsx: PsJsxRunner);
+    /**
+     * The active document (shortcut for `app.activeDocument`). A fresh wrapper is
+     * created on each access; wrappers are lightweight and stateless.
+     */
+    get activeDocument(): PhotoshopDocument;
+}
+
+export { AnchorPosition as A, type Bounds as B, ElementPlacement as C, DocumentMode as D, type EventName as E, type ElementPlacementValue as F, LayerKind as G, type LayerKindValue as H, type ImageChangedEvent as I, PhotoshopApp as J, PhotoshopDocument as K, type LayerSpec as L, type MethodName as M, PhotoshopLayer as N, PhotoshopLayers as O, type ProtocolMethods as P, PhotoshopSelection as Q, type RequestEnvelope as R, type ServerInfo as S, type PsBounds as T, type PsColor as U, SaveOptions as V, type WsImageResult as W, type SaveOptionsValue as X, SelectionType as Y, type SelectionTypeValue as Z, type ProtocolEvents as a, type PhotoshopEventName as b, type PhotoshopEventMap as c, type PsJsxRunner as d, PsPhotoshopProxy as e, type PluginInfo as f, ProtocolMethod as g, type PsLayer as h, type PsDocument as i, ErrorCode as j, type EventEnvelope as k, type ImageChangedLayer as l, PROTOCOL_VERSION as m, type ProtocolError as n, type PsBounds$1 as o, type PsRect as p, type ResponseEnvelope as q, isEvent as r, isRequest as s, isResponse as t, parseFrame as u, serializeFrame as v, type AnchorPositionValue as w, BlendMode as x, type BlendModeValue as y, type DocumentModeValue as z };