@ps-generator-bridge/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1131 @@
+'use strict';
+
+// src/protocol.ts
+var PROTOCOL_VERSION = 1;
+var ProtocolMethod = {
+  GetServerInfo: "getServerInfo",
+  JsxRun: "jsx:run",
+  JsxExecute: "jsx:execute",
+  EventSubscribe: "event:subscribe",
+  EventUnsubscribe: "event:unsubscribe",
+  ActionAutoCutout: "action:autoCutout",
+  ActionRemoveBackground: "action:removeBackground",
+  LayerGetInfo: "layer:getInfo",
+  LayerGetInfoById: "layer:getInfoById",
+  LayerGetInfoByIndex: "layer:getInfoByIndex",
+  DocumentCurrent: "document:current",
+  DocumentExport: "document:export",
+  DocumentSave: "document:save",
+  ImageExportLayer: "image:exportLayer",
+  ImageGetPreview: "image:getPreview",
+  ImageExportDocument: "image:exportDocument"
+};
+var ErrorCode = {
+  UnknownMethod: "UNKNOWN_METHOD",
+  BadRequest: "BAD_REQUEST",
+  Internal: "INTERNAL"
+};
+function isRequest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.id === "string" && typeof v.method === "string";
+}
+function isResponse(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.id === "string" && typeof v.ok === "boolean";
+}
+function isEvent(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.type === "string" && v.id === void 0;
+}
+function parseFrame(data) {
+  return JSON.parse(data);
+}
+function serializeFrame(value) {
+  return JSON.stringify(value);
+}
+
+// src/requestTracker.ts
+var requestCounter = 0;
+function nextId() {
+  requestCounter += 1;
+  return `req-${requestCounter}`;
+}
+var RequestTracker = class {
+  constructor(timeoutMs) {
+    this.timeoutMs = timeoutMs;
+    this.pending = /* @__PURE__ */ new Map();
+  }
+  send(transport, method, params) {
+    const id = nextId();
+    const envelope = { id, method, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Request "${method}" timed out after ${this.timeoutMs}ms`));
+      }, this.timeoutMs);
+      this.pending.set(id, {
+        resolve,
+        reject,
+        timer
+      });
+      transport?.send(serializeFrame(envelope));
+    });
+  }
+  settleFrame(data) {
+    let message;
+    try {
+      message = parseFrame(data);
+    } catch {
+      return false;
+    }
+    return this.settle(message);
+  }
+  settle(message) {
+    if (!isResponse(message)) return false;
+    this.settleResponse(message);
+    return true;
+  }
+  failAll(error) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+  settleResponse(message) {
+    const pending = this.pending.get(message.id);
+    if (!pending) return;
+    this.pending.delete(message.id);
+    clearTimeout(pending.timer);
+    if (message.ok) {
+      pending.resolve(message.result);
+    } else {
+      pending.reject(new Error(`${message.error.code}: ${message.error.message}`));
+    }
+  }
+};
+
+// src/transport.ts
+function createWebSocketTransport(url, WebSocketImpl) {
+  const Ctor = WebSocketImpl ?? resolveGlobalWebSocket();
+  const ws = new Ctor(url);
+  let opened = false;
+  let resolveReady;
+  let rejectReady;
+  const readyPromise = new Promise((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+  let closeListener;
+  ws.addEventListener("open", () => {
+    opened = true;
+    resolveReady();
+  });
+  ws.addEventListener("error", () => {
+    if (!opened) rejectReady(new Error(`WebSocket connection to ${url} failed`));
+  });
+  ws.addEventListener("close", () => closeListener?.());
+  return {
+    ready: () => readyPromise,
+    send: (data) => ws.send(data),
+    onMessage: (listener) => ws.addEventListener("message", (event) => listener(String(event.data))),
+    onClose: (listener) => {
+      closeListener = listener;
+    },
+    close: () => ws.close()
+  };
+}
+function resolveGlobalWebSocket() {
+  const candidate = globalThis.WebSocket;
+  if (!candidate) {
+    throw new Error(
+      "No global WebSocket is available (Node 18-21 lack it). Upgrade to Node 22+, or inject a transport, e.g. `new PsBridgeClient({ url, WebSocket: (await import('ws')).WebSocket })`."
+    );
+  }
+  return candidate;
+}
+
+// src/connection.ts
+var RawConnection = class {
+  constructor(options) {
+    this.options = options;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.attempts = 0;
+    this.state = "connecting";
+    this.readyWaiters = [];
+    this.maxRetries = options.maxRetries ?? 5;
+    this.retryDelayMs = options.retryDelayMs ?? 5e3;
+    this.requests = new RequestTracker(options.timeoutMs ?? 1e4);
+    this.clientId = options.clientId;
+    this.connect();
+  }
+  /** The clientId assigned by the server (undefined until the first handshake). */
+  get id() {
+    return this.clientId;
+  }
+  /** Resolves once connected (handshake received); rejects if retries are exhausted. */
+  ready() {
+    if (this.state === "ready") return Promise.resolve();
+    if (this.state === "failed") return Promise.reject(this.failError);
+    return new Promise((resolve, reject) => {
+      this.readyWaiters.push({ resolve, reject });
+    });
+  }
+  /** Fetch the server's identity + (when connected to PS) its Photoshop version. */
+  getServerInfo() {
+    return this.invoke("getServerInfo", {});
+  }
+  async invoke(method, params) {
+    await this.ready();
+    return this.requests.send(this.transport, method, params);
+  }
+  on(type, listener) {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(listener);
+  }
+  /** Unsubscribe a previously registered Event listener. */
+  off(type, listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+  /** Close the connection: stop reconnecting and reject all in-flight work. */
+  close() {
+    if (this.state === "failed") return;
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.fail(new Error("Connection closed"));
+    this.transport?.close();
+  }
+  connect() {
+    if (this.state === "failed") return;
+    const url = this.buildUrl();
+    const transport = this.options.transportFactory ? this.options.transportFactory(url) : createWebSocketTransport(url, this.options.WebSocket);
+    this.transport = transport;
+    let settled = false;
+    const onDead = () => {
+      if (settled) return;
+      settled = true;
+      if (this.transport === transport) this.handleDrop();
+    };
+    transport.onMessage((data) => this.handleMessage(data));
+    transport.onClose(onDead);
+    transport.ready().then(() => void 0, onDead);
+  }
+  buildUrl() {
+    if (!this.clientId) return this.options.url;
+    const sep = this.options.url.includes("?") ? "&" : "?";
+    return `${this.options.url}${sep}id=${encodeURIComponent(this.clientId)}`;
+  }
+  handleMessage(data) {
+    let message;
+    try {
+      message = parseFrame(data);
+    } catch {
+      return;
+    }
+    if (isEvent(message)) {
+      if (message.type === "connected") {
+        this.clientId = message.data.clientId;
+        this.attempts = 0;
+        this.markReady();
+      }
+      this.dispatchEvent(message.type, message.data);
+      return;
+    }
+    this.requests.settle(message);
+  }
+  handleDrop() {
+    if (this.state === "failed") return;
+    this.transport = void 0;
+    this.state = "connecting";
+    if (this.attempts >= this.maxRetries) {
+      this.fail(
+        new Error(`Connection to ${this.options.url} failed after ${this.maxRetries} retries`)
+      );
+      return;
+    }
+    this.attempts += 1;
+    this.retryTimer = setTimeout(() => this.connect(), this.retryDelayMs);
+  }
+  markReady() {
+    this.state = "ready";
+    const waiters = this.readyWaiters.splice(0);
+    for (const waiter of waiters) waiter.resolve();
+  }
+  fail(error) {
+    this.state = "failed";
+    this.failError = error;
+    const waiters = this.readyWaiters.splice(0);
+    for (const waiter of waiters) waiter.reject(error);
+    this.requests.failAll(error);
+  }
+  dispatchEvent(type, data) {
+    const set = this.listeners.get(type);
+    if (!set) return;
+    for (const listener of set) listener(data);
+  }
+};
+
+// src/photoshop/jsx-runner.ts
+function evalJson(jsx, expr) {
+  return jsx.run(`JSON.stringify(${expr})`).then((s) => JSON.parse(s));
+}
+function evalNumber(jsx, expr) {
+  return evalJson(jsx, `Number(${expr})`);
+}
+function evalString(jsx, expr) {
+  return evalJson(jsx, `String(${expr})`);
+}
+function evalBool(jsx, expr) {
+  return evalJson(jsx, `Boolean(${expr})`);
+}
+
+// src/photoshop/JsxBuilder.ts
+var JsxBuilder = class {
+  /**
+   * Escape a string into a JSX string literal. `JSON.stringify` handles quotes,
+   * newlines and Unicode.
+   *
+   * @example JsxBuilder.string("O'Brien") // -> "\"O'Brien\""
+   */
+  static string(value) {
+    return JSON.stringify(value);
+  }
+  /**
+   * Serialize a path to an ExtendScript `File` constructor.
+   *
+   * @example JsxBuilder.file("/path/to/file.psd") // -> 'new File("/path/to/file.psd")'
+   */
+  static file(path) {
+    return `new File(${JSON.stringify(path)})`;
+  }
+  /** Serialize a number, rejecting NaN/Infinity. */
+  static number(value) {
+    if (!isFinite(value)) {
+      throw new Error(`JsxBuilder.number: invalid value ${value}`);
+    }
+    return String(value);
+  }
+  /** Serialize a boolean. */
+  static boolean(value) {
+    return value ? "true" : "false";
+  }
+  /** Pass an enum string through (already in `EnumName.MEMBER` form). */
+  static enum_(value) {
+    return value;
+  }
+  /**
+   * Serialize a numeric array to a JSX array literal (bounds, crop, etc.).
+   *
+   * @example JsxBuilder.numberArray([0, 0, 100, 100]) // -> '[0,0,100,100]'
+   */
+  static numberArray(arr) {
+    return JSON.stringify(arr);
+  }
+  /** Serialize a 2-D numeric array (selection boundary points). */
+  static regionArray(region) {
+    return JSON.stringify(region);
+  }
+  /**
+   * Build a method-call expression from pre-serialized args.
+   *
+   * @example JsxBuilder.call("app.open", [JsxBuilder.file(path)])
+   *          // -> 'app.open(new File("/path/to/file.psd"))'
+   */
+  static call(path, args) {
+    return `${path}(${args.join(", ")})`;
+  }
+  /**
+   * Build a property assignment statement.
+   *
+   * @example JsxBuilder.assign("app.activeDocument.activeLayer.name", JsxBuilder.string("New Name"))
+   *          // -> 'app.activeDocument.activeLayer.name = "New Name"'
+   */
+  static assign(path, value) {
+    return `${path} = ${value}`;
+  }
+};
+
+// src/photoshop/PhotoshopLayer.ts
+var _PhotoshopLayer = class _PhotoshopLayer {
+  constructor(_jsx, _path) {
+    this._jsx = _jsx;
+    this._path = _path;
+  }
+  // --- Layer read-only properties -----------------------------------------
+  /** Unique layer id. */
+  get id() {
+    return evalNumber(this._jsx, `${this._path}.id`);
+  }
+  /** Layer name. */
+  get name() {
+    return evalString(this._jsx, `${this._path}.name`);
+  }
+  /** Layer visibility. */
+  get visible() {
+    return evalBool(this._jsx, `${this._path}.visible`);
+  }
+  /** Layer opacity (0-100). */
+  get opacity() {
+    return evalNumber(this._jsx, `${this._path}.opacity`);
+  }
+  /**
+   * 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() {
+    return evalNumber(this._jsx, `${this._path}.blendMode`).then(
+      (code) => _PhotoshopLayer._BLEND_MODE_MAP[code] ?? `BlendMode.UNKNOWN_${code}`
+    );
+  }
+  /** Whether the layer is fully locked. */
+  get allLocked() {
+    return evalBool(this._jsx, `${this._path}.allLocked`);
+  }
+  /**
+   * Layer bounds `[left, top, right, bottom]`.
+   *
+   * @remarks Units follow `rulerUnits`; values are not pixels unless it is
+   * `Units.PIXELS`.
+   */
+  get bounds() {
+    const expr = `(function(){ var b = ${this._path}.bounds; return [b[0], b[1], b[2], b[3]]; })()`;
+    return evalJson(this._jsx, expr);
+  }
+  /**
+   * 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() {
+    return evalNumber(this._jsx, `${this._path}.kind`).then(
+      (code) => _PhotoshopLayer._LAYER_KIND_MAP[code] ?? `LayerKind.UNKNOWN_${code}`
+    );
+  }
+  /** Object type name ("ArtLayer" or "LayerSet"). */
+  get typename() {
+    return evalString(this._jsx, `${this._path}.typename`);
+  }
+  // --- Property writes -----------------------------------------------------
+  /** Set the layer name. */
+  async setName(value) {
+    await this._jsx.run(JsxBuilder.assign(`${this._path}.name`, JsxBuilder.string(value)));
+  }
+  /** Set layer visibility. */
+  async setVisible(value) {
+    await this._jsx.run(JsxBuilder.assign(`${this._path}.visible`, JsxBuilder.boolean(value)));
+  }
+  /** Set layer opacity (0-100). */
+  async setOpacity(value) {
+    await this._jsx.run(JsxBuilder.assign(`${this._path}.opacity`, JsxBuilder.number(value)));
+  }
+  /**
+   * Set the blend mode.
+   *
+   * @example
+   * import { BlendMode } from "@ps-generator-bridge/sdk/plugin";
+   * await layer.setBlendMode(BlendMode.MULTIPLY);
+   */
+  async setBlendMode(value) {
+    await this._jsx.run(JsxBuilder.assign(`${this._path}.blendMode`, JsxBuilder.enum_(value)));
+  }
+  /** Set whether the layer is fully locked. */
+  async setAllLocked(value) {
+    await this._jsx.run(JsxBuilder.assign(`${this._path}.allLocked`, JsxBuilder.boolean(value)));
+  }
+  // --- Methods -------------------------------------------------------------
+  /** Delete this layer. */
+  async remove() {
+    await this._jsx.run(`${this._path}.remove()`);
+  }
+  /** Duplicate this layer (the copy becomes `activeLayer`). */
+  async duplicate() {
+    await this._jsx.run(`${this._path}.duplicate()`);
+    return new _PhotoshopLayer(this._jsx, "app.activeDocument.activeLayer");
+  }
+  /**
+   * 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);
+   */
+  async move(relativeObjectJsxPath, insertionLocation) {
+    await this._jsx.run(
+      `${this._path}.move(${relativeObjectJsxPath}, ${JsxBuilder.enum_(insertionLocation)})`
+    );
+  }
+  /** Translate the layer by a pixel delta. */
+  async translate(deltaX, deltaY) {
+    await this._jsx.run(
+      JsxBuilder.call(`${this._path}.translate`, [
+        JsxBuilder.number(deltaX),
+        JsxBuilder.number(deltaY)
+      ])
+    );
+  }
+  /**
+   * Scale the layer.
+   *
+   * @param horizontal horizontal scale percent (150 = 150%).
+   * @param vertical vertical scale percent.
+   * @param anchor scaling anchor (optional).
+   */
+  async resize(horizontal, vertical, anchor) {
+    const args = [JsxBuilder.number(horizontal), JsxBuilder.number(vertical)];
+    if (anchor !== void 0) args.push(JsxBuilder.enum_(anchor));
+    await this._jsx.run(JsxBuilder.call(`${this._path}.resize`, args));
+  }
+  /**
+   * Rotate the layer.
+   *
+   * @param angle degrees, clockwise positive.
+   * @param anchor rotation anchor (optional).
+   */
+  async rotate(angle, anchor) {
+    const args = [JsxBuilder.number(angle)];
+    if (anchor !== void 0) args.push(JsxBuilder.enum_(anchor));
+    await this._jsx.run(JsxBuilder.call(`${this._path}.rotate`, args));
+  }
+  /** Move the layer to the end of its stack. */
+  async moveToEnd() {
+    await this._jsx.run(`${this._path}.moveToEnd()`);
+  }
+};
+/** BlendMode code -> enum-name map (all 27 members, plus newer ones). */
+_PhotoshopLayer._BLEND_MODE_MAP = {
+  1: "PASSTHROUGH",
+  2: "NORMAL",
+  3: "DISSOLVE",
+  4: "DARKEN",
+  5: "MULTIPLY",
+  6: "COLORBURN",
+  7: "LINEARBURN",
+  8: "LIGHTEN",
+  9: "SCREEN",
+  10: "COLORDODGE",
+  11: "LINEARDODGE",
+  12: "OVERLAY",
+  13: "SOFTLIGHT",
+  14: "HARDLIGHT",
+  15: "VIVIDLIGHT",
+  16: "LINEARLIGHT",
+  17: "PINLIGHT",
+  18: "DIFFERENCE",
+  19: "EXCLUSION",
+  20: "HUE",
+  21: "SATURATION",
+  22: "COLORBLEND",
+  23: "LUMINOSITY",
+  26: "HARDMIX",
+  27: "SUBTRACT",
+  28: "DARKERCOLOR",
+  29: "LIGHTERCOLOR",
+  30: "DIVIDE"
+};
+// --- ArtLayer-only properties -------------------------------------------
+/** LayerKind code -> enum-name map. */
+_PhotoshopLayer._LAYER_KIND_MAP = {
+  1: "NORMAL",
+  2: "TEXT",
+  3: "SOLIDFILL",
+  4: "GRADIENTFILL",
+  5: "LEVELS",
+  6: "CURVES",
+  7: "COLORBALANCE",
+  8: "HUESATURATION",
+  9: "BRIGHTNESSCONTRAST",
+  10: "THRESHOLD",
+  11: "POSTERIZE",
+  12: "CHANNELMIXER",
+  13: "GRADIENTMAP",
+  14: "INVERSION",
+  15: "EXPOSURE",
+  16: "PHOTOFILTER",
+  17: "SELECTIVECOLOR",
+  18: "SMARTOBJECT",
+  20: "VIBRANCE",
+  21: "VIDEO",
+  22: "BLACKANDWHITE",
+  23: "LAYER3D",
+  26: "COLORLOOKUP"
+};
+var PhotoshopLayer = _PhotoshopLayer;
+
+// src/photoshop/PhotoshopLayers.ts
+var PhotoshopLayers = class {
+  constructor(_jsx, _path) {
+    this._jsx = _jsx;
+    this._path = _path;
+  }
+  /** Number of layers in the collection. */
+  get length() {
+    return evalNumber(this._jsx, `${this._path}.length`);
+  }
+  /**
+   * Access a layer by index. The collection is 0-based, matching JavaScript;
+   * `layers[0]` is the top-most layer.
+   */
+  at(index) {
+    return new PhotoshopLayer(this._jsx, `${this._path}[${index}]`);
+  }
+  /**
+   * 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) {
+    const escapedName = JsxBuilder.string(name);
+    return new PhotoshopLayer(this._jsx, `${this._path}.getByName(${escapedName})`);
+  }
+};
+
+// src/photoshop/PhotoshopSelection.ts
+var PhotoshopSelection = class {
+  constructor(_jsx, _path) {
+    this._jsx = _jsx;
+    this._path = _path;
+  }
+  /**
+   * Selection bounds `[left, top, right, bottom]`. Throws when there is no
+   * selection.
+   *
+   * @remarks Units follow `rulerUnits`.
+   */
+  get bounds() {
+    const expr = `(function(){ var b = ${this._path}.bounds; return [b[0], b[1], b[2], b[3]]; })()`;
+    return evalJson(this._jsx, expr);
+  }
+  /** Whether the selection is a solid (un-feathered) rectangle. */
+  get solid() {
+    return evalBool(this._jsx, `${this._path}.solid`);
+  }
+  // --- Methods -------------------------------------------------------------
+  /** Select the whole canvas. */
+  async selectAll() {
+    await this._jsx.run(`${this._path}.selectAll()`);
+  }
+  /** Deselect. */
+  async deselect() {
+    await this._jsx.run(`${this._path}.deselect()`);
+  }
+  /** Invert the selection. */
+  async invert() {
+    await this._jsx.run(`${this._path}.invert()`);
+  }
+  /**
+   * 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);
+   */
+  async select(region, type, feather, antiAlias) {
+    const args = [JsxBuilder.regionArray(region)];
+    if (type !== void 0) args.push(JsxBuilder.enum_(type));
+    if (feather !== void 0) args.push(JsxBuilder.number(feather));
+    if (antiAlias !== void 0) args.push(JsxBuilder.boolean(antiAlias));
+    await this._jsx.run(JsxBuilder.call(`${this._path}.select`, args));
+  }
+  /** Grow the selection by `by` pixels. */
+  async expand(by) {
+    await this._jsx.run(JsxBuilder.call(`${this._path}.expand`, [JsxBuilder.number(by)]));
+  }
+  /** Shrink the selection by `by` pixels. */
+  async contract(by) {
+    await this._jsx.run(JsxBuilder.call(`${this._path}.contract`, [JsxBuilder.number(by)]));
+  }
+  /** Feather the selection edge by `by` pixels. */
+  async feather(by) {
+    await this._jsx.run(JsxBuilder.call(`${this._path}.feather`, [JsxBuilder.number(by)]));
+  }
+  /** Translate the selection boundary (content stays put). */
+  async translateBoundary(deltaX, deltaY) {
+    await this._jsx.run(
+      JsxBuilder.call(`${this._path}.translateBoundary`, [
+        JsxBuilder.number(deltaX),
+        JsxBuilder.number(deltaY)
+      ])
+    );
+  }
+};
+
+// src/photoshop/PhotoshopDocument.ts
+var PhotoshopDocument = class _PhotoshopDocument {
+  constructor(_jsx, _path) {
+    this._jsx = _jsx;
+    this._path = _path;
+  }
+  // --- Read-only properties -----------------------------------------------
+  /** Document name (file name, without directory). */
+  get name() {
+    return evalString(this._jsx, `${this._path}.name`);
+  }
+  /** Unique document id. */
+  get id() {
+    return evalNumber(this._jsx, `${this._path}.id`);
+  }
+  /**
+   * 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() {
+    return evalNumber(this._jsx, `${this._path}.width`);
+  }
+  /**
+   * Document height.
+   *
+   * @remarks The unit follows `rulerUnits` (see {@link width}).
+   */
+  get height() {
+    return evalNumber(this._jsx, `${this._path}.height`);
+  }
+  /** Document resolution (PPI). */
+  get resolution() {
+    return evalNumber(this._jsx, `${this._path}.resolution`);
+  }
+  /** Document color mode as an enum-name string (e.g. "DocumentMode.RGB"). */
+  get mode() {
+    const expr = `(function(){
+            var m = ${this._path}.mode;
+            if (m === DocumentMode.RGB) return "DocumentMode.RGB";
+            if (m === DocumentMode.CMYK) return "DocumentMode.CMYK";
+            if (m === DocumentMode.GRAYSCALE) return "DocumentMode.GRAYSCALE";
+            if (m === DocumentMode.LAB) return "DocumentMode.LAB";
+            if (m === DocumentMode.BITMAP) return "DocumentMode.BITMAP";
+            if (m === DocumentMode.INDEXEDCOLOR) return "DocumentMode.INDEXEDCOLOR";
+            if (m === DocumentMode.MULTICHANNEL) return "DocumentMode.MULTICHANNEL";
+            if (m === DocumentMode.DUOTONE) return "DocumentMode.DUOTONE";
+            return String(m);
+        })()`;
+    return evalJson(this._jsx, expr);
+  }
+  /** Whether the document is saved since its last change. */
+  get saved() {
+    return evalBool(this._jsx, `${this._path}.saved`);
+  }
+  /**
+   * Full document path (native `fsName`). For an unsaved document this may
+   * return a temporary path or throw.
+   */
+  get fullName() {
+    return evalString(this._jsx, `${this._path}.fullName.fsName`);
+  }
+  /** Directory containing the document (native `fsName`). */
+  get path() {
+    return evalString(this._jsx, `${this._path}.path.fsName`);
+  }
+  // --- Child navigation (synchronous; no request) -------------------------
+  /** The active layer. */
+  get activeLayer() {
+    return new PhotoshopLayer(this._jsx, `${this._path}.activeLayer`);
+  }
+  /** The Layers collection (ArtLayers + LayerSets). */
+  get layers() {
+    return new PhotoshopLayers(this._jsx, `${this._path}.layers`);
+  }
+  /** The selection. */
+  get selection() {
+    return new PhotoshopSelection(this._jsx, `${this._path}.selection`);
+  }
+  // --- Methods -------------------------------------------------------------
+  /** Save the document in its current format. */
+  async save() {
+    await this._jsx.run(`${this._path}.save()`);
+  }
+  /**
+   * 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);
+   */
+  async close(saving = "SaveOptions.DONOTSAVECHANGES") {
+    await this._jsx.run(JsxBuilder.call(`${this._path}.close`, [JsxBuilder.enum_(saving)]));
+  }
+  /**
+   * 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).
+   */
+  async saveAs(saveIn, asCopy) {
+    const script = `${this._path}.saveAs(${JsxBuilder.file(saveIn)}${asCopy !== void 0 ? `, undefined, ${JsxBuilder.boolean(asCopy)}` : ""})`;
+    await this._jsx.run(script);
+  }
+  /** Flatten all layers into a single background layer. */
+  async flatten() {
+    await this._jsx.run(`${this._path}.flatten()`);
+  }
+  /** Merge all visible layers. */
+  async mergeVisibleLayers() {
+    await this._jsx.run(`${this._path}.mergeVisibleLayers()`);
+  }
+  /** Rasterize all layers. */
+  async rasterizeAllLayers() {
+    await this._jsx.run(`${this._path}.rasterizeAllLayers()`);
+  }
+  /**
+   * 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`.
+   */
+  async duplicate(name) {
+    const args = name !== void 0 ? [JsxBuilder.string(name)] : [];
+    await this._jsx.run(JsxBuilder.call(`${this._path}.duplicate`, args));
+    return new _PhotoshopDocument(this._jsx, "app.activeDocument");
+  }
+  /**
+   * 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);
+   */
+  async resizeCanvas(width, height, anchor) {
+    const args = [JsxBuilder.number(width), JsxBuilder.number(height)];
+    if (anchor !== void 0) args.push(JsxBuilder.enum_(anchor));
+    await this._jsx.run(JsxBuilder.call(`${this._path}.resizeCanvas`, args));
+  }
+  /**
+   * Resize the image.
+   *
+   * @param width new width in pixels (optional).
+   * @param height new height in pixels (optional).
+   * @param resolution new resolution in PPI (optional).
+   */
+  async resizeImage(width, height, resolution) {
+    const args = [
+      width !== void 0 ? JsxBuilder.number(width) : "undefined",
+      height !== void 0 ? JsxBuilder.number(height) : "undefined",
+      resolution !== void 0 ? JsxBuilder.number(resolution) : "undefined"
+    ];
+    await this._jsx.run(JsxBuilder.call(`${this._path}.resizeImage`, args));
+  }
+  /** Rotate the canvas by `angle` degrees. */
+  async rotateCanvas(angle) {
+    await this._jsx.run(JsxBuilder.call(`${this._path}.rotateCanvas`, [JsxBuilder.number(angle)]));
+  }
+  /**
+   * 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.
+   */
+  async crop(bounds) {
+    const script = `${this._path}.crop(${JsxBuilder.numberArray(Array.from(bounds))})`;
+    await this._jsx.run(script);
+  }
+};
+
+// src/photoshop/PhotoshopApp.ts
+var PhotoshopApp = class {
+  constructor(_jsx) {
+    this._jsx = _jsx;
+    this._path = "app";
+  }
+  // --- Read-only properties -----------------------------------------------
+  /** Photoshop version (e.g. "25.0"). */
+  get version() {
+    return evalString(this._jsx, `${this._path}.version`);
+  }
+  /** Application locale (e.g. "zh_CN"). */
+  get locale() {
+    return evalString(this._jsx, `${this._path}.locale`);
+  }
+  /** Application name (e.g. "Adobe Photoshop"). */
+  get name() {
+    return evalString(this._jsx, `${this._path}.name`);
+  }
+  /** Internal build number. */
+  get build() {
+    return evalString(this._jsx, `${this._path}.build`);
+  }
+  /**
+   * Install path (native `fsName`). `app.path` is a File in ExtendScript, so the
+   * string comes from `.fsName`.
+   */
+  get path() {
+    return evalString(this._jsx, `${this._path}.path.fsName`);
+  }
+  /**
+   * 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() {
+    const expr = `(function(){
+            var c = ${this._path}.foregroundColor;
+            return {
+                model: "rgb",
+                rgb: { red: c.rgb.red, green: c.rgb.green, blue: c.rgb.blue, hexValue: c.rgb.hexValue }
+            };
+        })()`;
+    return evalJson(this._jsx, expr);
+  }
+  /** Shortcut for `activeDocument` reached through the `app` path. */
+  get activeDocument() {
+    return new PhotoshopDocument(this._jsx, `${this._path}.activeDocument`);
+  }
+  // --- Methods -------------------------------------------------------------
+  /**
+   * 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");
+   */
+  async open(filePath) {
+    const script = JsxBuilder.call(`${this._path}.open`, [JsxBuilder.file(filePath)]);
+    await this._jsx.run(script);
+    return new PhotoshopDocument(this._jsx, `${this._path}.activeDocument`);
+  }
+  /** Emit a beep. */
+  async beep() {
+    await this._jsx.run(`${this._path}.beep()`);
+  }
+};
+
+// src/photoshop/PsPhotoshopProxy.ts
+var PsPhotoshopProxy = class {
+  constructor(jsx) {
+    this._jsx = jsx;
+    this.app = new PhotoshopApp(this._jsx);
+  }
+  /**
+   * The active document (shortcut for `app.activeDocument`). A fresh wrapper is
+   * created on each access; wrappers are lightweight and stateless.
+   */
+  get activeDocument() {
+    return new PhotoshopDocument(this._jsx, "app.activeDocument");
+  }
+};
+
+// src/publicConnection.ts
+var DEFAULT_CONNECTION_URL = "ws://127.0.0.1:7700/ws";
+var PublicEventClient = class {
+  constructor(invoke) {
+    this.invoke = invoke;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.wrappers = /* @__PURE__ */ new WeakMap();
+    this.activeSubscriptions = /* @__PURE__ */ new Set();
+    this.pendingSubscriptions = /* @__PURE__ */ new Set();
+  }
+  on(type, listener) {
+    const hadListeners = this.listenerCount(type) > 0;
+    this.add(type, listener);
+    if (!hadListeners) this.subscribe(type);
+  }
+  once(type, listener) {
+    const wrapped = ((data) => {
+      this.off(type, wrapped);
+      listener(data);
+    });
+    this.wrappers.set(listener, wrapped);
+    this.on(type, wrapped);
+  }
+  off(type, listener) {
+    const key = listener;
+    const wrapped = this.wrappers.get(key);
+    this.wrappers.delete(key);
+    const removed = this.remove(type, wrapped ?? key);
+    if (removed && this.listenerCount(type) === 0) this.unsubscribe(type);
+  }
+  dispatch(type, data) {
+    const set = this.listeners.get(type);
+    if (!set) return;
+    for (const listener of set) listener(data);
+  }
+  replay() {
+    this.activeSubscriptions.clear();
+    for (const type of this.listeners.keys()) this.subscribe(type);
+  }
+  add(type, listener) {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(listener);
+  }
+  remove(type, listener) {
+    const set = this.listeners.get(type);
+    if (!set) return false;
+    const removed = set.delete(listener);
+    if (set.size === 0) this.listeners.delete(type);
+    return removed;
+  }
+  listenerCount(type) {
+    return this.listeners.get(type)?.size ?? 0;
+  }
+  subscribe(type) {
+    if (this.activeSubscriptions.has(type) || this.pendingSubscriptions.has(type)) return;
+    this.pendingSubscriptions.add(type);
+    void this.invoke(ProtocolMethod.EventSubscribe, { type }).then(() => {
+      if (this.listenerCount(type) > 0) this.activeSubscriptions.add(type);
+    }).catch(
+      (error) => console.warn(`event subscribe failed for ${type}: ${error.message}`)
+    ).finally(() => this.pendingSubscriptions.delete(type));
+  }
+  unsubscribe(type) {
+    this.activeSubscriptions.delete(type);
+    this.pendingSubscriptions.delete(type);
+    void this.invoke(ProtocolMethod.EventUnsubscribe, { type }).catch(
+      (error) => console.warn(`event unsubscribe failed for ${type}: ${error.message}`)
+    );
+  }
+};
+var PublicJsxRunner = class {
+  constructor(invoke) {
+    this.invoke = invoke;
+  }
+  run(script) {
+    return this.invoke(ProtocolMethod.JsxRun, { script });
+  }
+  execute(name, params) {
+    return this.invoke(ProtocolMethod.JsxExecute, { name, params });
+  }
+};
+var PublicPluginClient = class {
+  constructor(getServerInfo) {
+    this.getServerInfo = getServerInfo;
+  }
+  async list() {
+    return (await this.getServerInfo()).plugins ?? [];
+  }
+  async has(id) {
+    return (await this.list()).some((plugin) => plugin.id === id);
+  }
+};
+var PublicModules = class {
+  constructor(invoke) {
+    this.invoke = invoke;
+    this.layer = {
+      getLayerInfo: (params) => this.invoke(ProtocolMethod.LayerGetInfo, params),
+      getLayerInfoByID: (layerID, options) => this.invoke(ProtocolMethod.LayerGetInfoById, { layerID, options }),
+      getLayerInfoByIndex: (layerIndex, options) => this.invoke(ProtocolMethod.LayerGetInfoByIndex, { layerIndex, options })
+    };
+    this.document = {
+      getCurrentDocument: () => this.invoke(ProtocolMethod.DocumentCurrent, {}),
+      exportDocument: (params) => this.invoke(ProtocolMethod.DocumentExport, params),
+      saveDocument: (params) => this.invoke(ProtocolMethod.DocumentSave, params)
+    };
+    this.action = {
+      autoCutout: () => this.invoke(ProtocolMethod.ActionAutoCutout, {}),
+      removeBackground: () => this.invoke(ProtocolMethod.ActionRemoveBackground, {})
+    };
+  }
+};
+var Connection = class {
+  constructor(options = {}) {
+    this.raw = new RawConnection({ ...options, url: options.url ?? DEFAULT_CONNECTION_URL });
+    this.call = (method, params) => this.raw.invoke(method, params);
+    this.eventClient = new PublicEventClient(this.call);
+    this.jsxClient = new PublicJsxRunner(this.call);
+    this.event = this.eventClient;
+    this.jsx = this.jsxClient;
+    this.photoshop = new PsPhotoshopProxy(this.jsxClient);
+    this.plugin = new PublicPluginClient(() => this.getServerInfo());
+    this.modules = new PublicModules(this.call);
+    this.raw.on("connected", () => this.eventClient.replay());
+  }
+  get id() {
+    return this.raw.id;
+  }
+  ready() {
+    return this.raw.ready();
+  }
+  close() {
+    this.raw.close();
+  }
+  getServerInfo() {
+    return this.call(ProtocolMethod.GetServerInfo, {});
+  }
+};
+
+// src/client.ts
+var PsBridgeClient = class {
+  constructor(options) {
+    this.requests = new RequestTracker(options.timeoutMs ?? 1e4);
+    if (options.transport) {
+      this.transport = options.transport;
+    } else if (options.url) {
+      this.transport = createWebSocketTransport(options.url, options.WebSocket);
+    } else {
+      throw new Error("PsBridgeClient requires either `url` or `transport`.");
+    }
+    this.transport.onMessage((data) => this.handleMessage(data));
+  }
+  /** Fetch the server's identity + (when connected to PS) its Photoshop version. */
+  getServerInfo() {
+    return this.request("getServerInfo", {});
+  }
+  /** Send a typed request and await its correlated response. */
+  async request(method, params) {
+    await this.transport.ready();
+    return this.requests.send(this.transport, method, params);
+  }
+  /** Reject all in-flight requests and close the transport. */
+  close() {
+    this.requests.failAll(new Error("Client closed"));
+    this.transport.close();
+  }
+  handleMessage(data) {
+    this.requests.settleFrame(data);
+  }
+};
+
+exports.Connection = Connection;
+exports.DEFAULT_CONNECTION_URL = DEFAULT_CONNECTION_URL;
+exports.ErrorCode = ErrorCode;
+exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
+exports.ProtocolMethod = ProtocolMethod;
+exports.PsBridgeClient = PsBridgeClient;
+exports.RawConnection = RawConnection;
+exports.createWebSocketTransport = createWebSocketTransport;
+exports.isEvent = isEvent;
+exports.isRequest = isRequest;
+exports.isResponse = isResponse;
+exports.parseFrame = parseFrame;
+exports.serializeFrame = serializeFrame;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map