@ps-generator-bridge/generator 0.1.0

package/dist/contract-C4vydf6-.d.ts

@@ -0,0 +1,1270 @@
+import { Stream } from 'node:stream';
+import { EventEmitter } from 'node:events';
+
+type PsBounds$1 = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+type PsRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type PsPixmap = {
+    format: number;
+    width: number;
+    height: number;
+    rowBytes: number;
+    colorMode: number;
+    channelCount: number;
+    bitsPerChannel: number;
+    pixels: Buffer;
+    bytesPerPixel: number;
+    padding: number;
+    bounds: PsBounds$1;
+    resolution: number;
+    getPixel: (n: number) => any;
+    readChannel: (n?: number) => any;
+};
+interface PsDocumentInfo {
+    version: string;
+    timeStamp: number;
+    count: number;
+    id: number;
+    file: string;
+    bounds: PsBounds$1;
+    selection: number[];
+    resolution: number;
+    globalLight: {
+        angle: number;
+        altitude: number;
+    };
+    generatorSettings?: any;
+    profile: string;
+    mode: string;
+    depth: number;
+    layers: any[];
+}
+
+/**
+ * The plugin's contract with generator-core, typed faithfully from
+ * `generator-core/lib/generator.js` (every public method, the low-level
+ * `_sendJSX*` transport, and the underscore-prefixed internals). Public
+ * thenable methods are typed as `Promise<T>` (consumers `await` them); the
+ * `_sendJSX*` methods return a `Deferred<T>` — generator-core's Q deferred,
+ * which streams progress messages for pixmap/shape protocols.
+ *
+ * This is an interface (not a class): the plugin never `instanceof`-checks the
+ * generator and only depends on the surface. A test fake cannot satisfy the
+ * full required surface, so tests build one via the `fakeGenerator()` factory
+ * (a single `as unknown as FakeGenerator & PsGenerator` cast) — see
+ * `test/fakeGenerator.ts`.
+ */
+
+
+/**
+ * generator-core's Q `Deferred` shape — the return of `_sendJSXString` /
+ * `_sendJSXFile`. The promise streams `progress` / `fail` notifications (used
+ * by the pixmap/shape protocols) and settles via `resolve` / `reject`. Only the
+ * members the plugin reaches are modelled.
+ */
+interface Deferred<T> {
+  promise: {
+    then<TResult>(
+      onFulfilled?: (value: T) => TResult | PromiseLike<TResult>,
+      onRejected?: (reason: unknown) => TResult | PromiseLike<TResult>
+    ): Promise<TResult>;
+    progress(fn: (message: { type: string; value: unknown }) => void): void;
+    fail(fn: (reason: unknown) => void): void;
+    finally(fn: () => void): void;
+  };
+  resolve(value?: T): void;
+  reject(reason?: unknown): void;
+  notify(message: unknown): void;
+}
+
+declare namespace PsGenerator {
+  /** Settings for `getPixmap` / `getDocumentPixmap` (generator.js:1201-1208). */
+  export interface GetPixmapSettings {
+    boundsOnly?: boolean;
+    inputRect?: PsBounds$1;
+    outputRect?: PsBounds$1;
+    scaleX?: number;
+    scaleY?: number;
+    clipBounds?: PsBounds$1;
+    useJPGEncoding?: string;
+    useSmartScaling?: boolean;
+    convertToWorkingRGBProfile?: boolean;
+    useICCProfile?: string;
+    getICCProfileData?: boolean;
+    allowDither?: boolean;
+    useColorSettingsDither?: boolean;
+    interpolationType?: string;
+    forceSmartPSDPixelScaling?: boolean;
+    clipToDocumentBounds?: boolean;
+    maxDimension?: number;
+    compId?: number;
+    compIndex?: number;
+    includeAncestorMasks?: boolean;
+    includeAdjustors?: boolean;
+    includeChildren?: boolean;
+    includeClipBase?: boolean;
+    includeClipped?: boolean;
+  }
+
+  /** Settings for `savePixmap` / `streamPixmap` (generator.js:1959-1977). */
+  export interface SavePixmapSettings {
+    format: string;
+    quality?: number;
+    lossless?: boolean;
+    ppi?: number;
+    padding?: PsBounds$1;
+    extract?: { x: number; y: number; width: number; height: number };
+    background?: [number, number, number, number];
+    _scale?: number;
+    usePngquant?: boolean;
+    useFlite?: boolean;
+    useJPGEncoding?: boolean;
+  }
+
+  /** Flags overriding `getDocumentInfo` defaults (generator.js:720-748). */
+  export interface DocumentInfoFlags {
+    compInfo?: boolean;
+    imageInfo?: boolean;
+    layerInfo?: boolean;
+    expandSmartObjects?: boolean;
+    getTextStyles?: boolean;
+    getFullTextStyles?: boolean;
+    selectedLayers?: boolean;
+    getCompLayerSettings?: boolean;
+    getDefaultLayerFX?: boolean;
+    getPathData?: boolean;
+  }
+
+  /** A layer spec: a layer id, or an index range with optional hidden indices. */
+  export type LayerSpec =
+    | number
+    | { firstLayerIndex: number; lastLayerIndex: number; hidden?: number[] };
+
+  /** Result of `getGuides` (generator.js:2047). */
+  export interface Guides {
+    horizontal: number[];
+    vertical: number[];
+  }
+
+  /** Result of `getMenuState` / `checkPluginCompatibility`. */
+  export interface MenuState {
+    enabled: boolean;
+    checked: boolean;
+  }
+
+  export interface PluginCompatibility {
+    compatible: boolean;
+    message: string | null;
+  }
+
+  /** Scaling settings for `getPixmapParams` (generator.js:1566-1574). */
+  export interface PixmapParamsSettings {
+    width?: number;
+    height?: number;
+    scaleX?: number;
+    scaleY?: number;
+    scale?: number;
+  }
+}
+
+interface PsGenerator {
+  // --- lifecycle -----------------------------------------------------------
+
+  /** Launch the generator: connect to Photoshop, resolve with self. */
+  start(options?: Record<string, any>): Promise<PsGenerator>;
+
+  /** Disconnect from Photoshop. */
+  shutdown(): void;
+
+  /** Whether the Photoshop connection is currently live. */
+  isConnected(): boolean;
+
+  /** Send a keep-alive; resolves true when Photoshop acknowledges. */
+  checkConnection(): Promise<boolean>;
+
+  // --- jsx evaluation ------------------------------------------------------
+
+  /** Evaluate a local jsx file with optional params; resolves `message.value`. */
+  evaluateJSXFile(
+    path: string,
+    params?: Record<string, any>,
+    sharedEngineSafe?: boolean
+  ): Promise<any>;
+
+  /** `evaluateJSXFile` forced into the shared script engine. */
+  evaluateJSXFileSharedSafe(path: string, params?: Record<string, any>): Promise<any>;
+
+  /** Evaluate a jsx string; resolves `message.value`. */
+  evaluateJSXString(s: string, sharedEngineSafe?: boolean): Promise<any>;
+
+  /** `evaluateJSXString` forced into the shared script engine. */
+  evaluateJSXStringSharedSafe(s: string): Promise<any>;
+
+  /** Low-level jsx-string transport (private in generator-core). Returns the
+   *  raw deferred so callers can subscribe to the progress stream. */
+  _sendJSXString(s: string, deferred?: Deferred<any>, sharedEngineSafe?: boolean): Deferred<any>;
+
+  /** Low-level jsx-file transport (private in generator-core). Returns the raw
+   *  deferred; the pixmap/shape protocols subscribe to its progress messages. */
+  _sendJSXFile(
+    path: string,
+    params?: Record<string, any>,
+    sharedEngineSafe?: boolean
+  ): Deferred<any>;
+
+  // --- UI / clipboard ------------------------------------------------------
+
+  /** Show a Photoshop alert dialog. */
+  alert(message: string, stringReplacements?: string): void;
+
+  /** Copy a string to the system clipboard. */
+  copyToClipboard(str: string): void;
+
+  // --- Photoshop environment ----------------------------------------------
+
+  /** Resolve to the Photoshop install directory path. */
+  getPhotoshopPath(): Promise<string>;
+
+  /** Resolve to the Photoshop executable directory (inside the .app on Mac). */
+  getPhotoshopExecutableLocation(): Promise<string>;
+
+  /** Resolve to the Photoshop locale string. */
+  getPhotoshopLocale(): Promise<string>;
+
+  /** Resolve to the Photoshop version, e.g. "19.0.0". */
+  getPhotoshopVersion(): Promise<string>;
+
+  // --- menus ---------------------------------------------------------------
+
+  /** Register a menu item; resolves once Photoshop has rebuilt the menu. */
+  addMenuItem(name: string, displayName: string, enabled: boolean, checked: boolean): Promise<void>;
+
+  /** Toggle (and optionally rename) an existing menu item. */
+  toggleMenu(name: string, enabled: boolean, checked: boolean, displayName?: string): Promise<void>;
+
+  /** Read the enabled/checked state of a menu item, or null if absent. */
+  getMenuState(name: string): PsGenerator.MenuState | null;
+
+  // --- documents -----------------------------------------------------------
+
+  /** Resolve to the ids of all open documents. */
+  getOpenDocumentIDs(): Promise<number[]>;
+
+  /** Resolve to a document's info (layers, comps, image, …); rejects with
+   *  "No Open Document" when none is open. */
+  getDocumentInfo(
+    documentId?: number,
+    flags?: PsGenerator.DocumentInfoFlags
+  ): Promise<PsDocumentInfo>;
+
+  // --- generator settings --------------------------------------------------
+
+  /** Get a layer's generator settings for a plugin. */
+  getLayerSettingsForPlugin(documentId: number, layerId: number, pluginId: string): Promise<any>;
+
+  /** Set a layer's generator settings for a plugin. */
+  setLayerSettingsForPlugin(
+    settings: Record<string, any>,
+    layerId: number,
+    pluginId: string
+  ): Promise<any>;
+
+  /** Get document-wide generator settings for a plugin. */
+  getDocumentSettingsForPlugin(documentId: number, pluginId: string): Promise<any>;
+
+  /** Set document-wide generator settings for a plugin. */
+  setDocumentSettingsForPlugin(
+    settings: Record<string, any>,
+    documentId: number,
+    pluginId: string
+  ): Promise<any>;
+
+  /** Extract and parse generator settings from a document object. */
+  extractDocumentSettings(document: Record<string, any>, pluginId?: string): any;
+
+  // --- Photoshop events ----------------------------------------------------
+
+  /** Subscribe to one or more Photoshop events over the connection. */
+  subscribeToPhotoshopEvents(events: string | string[]): Promise<boolean>;
+
+  /** Register a listener for a Photoshop event. */
+  onPhotoshopEvent(event: string, listener: (event: any) => void): void;
+
+  /** Register a one-shot listener for a Photoshop event. */
+  oncePhotoshopEvent(event: string, listener: (event: any) => void): void;
+
+  /** Remove a Photoshop event listener. */
+  removePhotoshopEventListener(event: string, listener: (event: any) => void): void;
+
+  /** List current listeners for a Photoshop event. */
+  photoshopEventListeners(event: string): Array<(event: any) => void>;
+
+  /** Emit a Photoshop event to its listeners. */
+  emitPhotoshopEvent(event: string, data?: any): void;
+
+  // --- pixmaps -------------------------------------------------------------
+
+  /** Get a pixmap (or bounds) for a layer id. */
+  getPixmap(
+    documentId: number,
+    layerSpec: number,
+    settings: PsGenerator.GetPixmapSettings
+  ): Promise<PsPixmap>;
+
+  /** Get a pixmap (or bounds) for an index range of layers. */
+  getPixmap(
+    documentId: number,
+    layerSpec: {
+      firstLayerIndex: number;
+      lastLayerIndex: number;
+      hidden?: number[];
+    },
+    settings: PsGenerator.GetPixmapSettings
+  ): Promise<PsPixmap>;
+
+  /** Get a pixmap of the whole document in its current visibility state. */
+  getDocumentPixmap(documentId: number, settings: PsGenerator.GetPixmapSettings): Promise<PsPixmap>;
+
+  /** Compute the `getPixmap` settings for a target scaling/padding. */
+  getPixmapParams(
+    settings: PsGenerator.PixmapParamsSettings,
+    staticInputBounds: PsBounds$1,
+    visibleInputBounds: PsBounds$1,
+    paddedInputBounds: PsBounds$1,
+    clipToBounds?: PsBounds$1
+  ): PsGenerator.GetPixmapSettings;
+
+  /** Write a pixmap to `path` via ImageMagick; resolves to the written path. */
+  savePixmap(
+    pixmap: PsPixmap,
+    path: string,
+    settings: PsGenerator.SavePixmapSettings
+  ): Promise<string>;
+
+  /** Stream a pixmap's converted bytes to `outputStream`. */
+  streamPixmap(
+    pixmap: PsPixmap,
+    outputStream: Stream,
+    settings: PsGenerator.SavePixmapSettings
+  ): Promise<void>;
+
+  /** Parse and coerce a pixmap's numeric properties in place. */
+  _parsePixmapProperties(pixmap: PsPixmap): void;
+
+  /** Parse and coerce a save-pixmap settings object in place. */
+  _parsePixmapSaveSettings(settings: PsGenerator.SavePixmapSettings): void;
+
+  // --- shapes / svg / guides ----------------------------------------------
+
+  /** Resolve to a layer's path/shape data, or reject "layer does not contain a shape". */
+  getLayerShape(documentId: number, layerId: number): Promise<{ path: any }>;
+
+  /** Resolve to an SVG string for the layer, optionally scaled. */
+  getSVG(documentId: number, layerId: number, settings?: { scale?: number }): Promise<string>;
+
+  /** Resolve to the horizontal/vertical guide positions in a document. */
+  getGuides(documentId: number): Promise<PsGenerator.Guides>;
+
+  /** Recursively compute the containing bounds of a layer tree (or undefined). */
+  getDeepBounds(layer: any): PsBounds$1 | undefined;
+
+  // --- bounds helpers (private) -------------------------------------------
+
+  /** True when a bounds rect has zero or non-finite area. */
+  _isBoundEmpty(bounds: PsBounds$1): boolean;
+
+  /** Smallest rect containing both bounds. */
+  _unionBounds(boundsA: PsBounds$1, boundsB: PsBounds$1): PsBounds$1;
+
+  /** Largest rect inside both bounds (zeroed when empty). */
+  _intersectBounds(boundsA: PsBounds$1, boundsB: PsBounds$1): PsBounds$1;
+
+  /** Union of a layer's raster + vector mask bounds, or undefined. */
+  _getTotalMaskBounds(bounds: any): PsBounds$1 | undefined;
+
+  // --- hidden layers (private) --------------------------------------------
+
+  /** Recursively collect indices of hidden layers (children of hidden groups
+   *  are hidden too). Used by `getDocumentPixmap`. */
+  _computeHiddenLayers(parent: { layers: any[] }, hideAll?: boolean): number[];
+
+  // --- style (private) -----------------------------------------------------
+
+  /** Resolve to extracted style info for a document (private, unstable API). */
+  _getStyleInfo(documentId: number, flags?: { selectedLayers?: boolean }): Promise<any>;
+
+  // --- settings parsing (private) -----------------------------------------
+
+  /** Parse a `{ json }`-wrapped settings blob into an object. */
+  _parseDocumentSettings(settings: { json?: string } | any): any;
+
+  /** Register/subscribe a Photoshop event listener helper (private). */
+  _registerPhotoshopEventHelper(
+    event: string,
+    listener: (event: any) => void,
+    isOnce: boolean
+  ): void;
+
+  // --- headlights (private) -----------------------------------------------
+
+  /** Log a Headlights event (Adobe-internal). */
+  _logHeadlights(event: string): Promise<void>;
+
+  /** Log a plugin-loaded Headlights record (Adobe-internal). */
+  _logHeadlightsPluginLoaded(pluginName: string, pluginVersion: string): Promise<void>;
+
+  // --- plugin management ---------------------------------------------------
+
+  /** Read a plugin's `package.json` metadata; throws on invalid input. */
+  getPluginMetadata(directory: string): any;
+
+  /** Check a plugin's `generator-core-version` compatibility. */
+  checkPluginCompatibility(metadata: any): PsGenerator.PluginCompatibility;
+
+  /** Load a plugin from a directory; throws on incompatibility / failure. */
+  loadPlugin(directory: string): void;
+
+  /** Return an already-loaded plugin by name, or null. */
+  getPlugin(name: string): any | null;
+
+  // --- custom options ------------------------------------------------------
+
+  /** Resolve to the custom-options table for a plugin (persists until PS quit). */
+  getCustomOptions(pluginId: string): Promise<Record<string, any>>;
+
+  /** Replace the custom-options table for a plugin (no merge). */
+  setCustomOptions(pluginId: string, settings: Record<string, any>): Promise<void>;
+
+  /** Update a single custom option key for a plugin. */
+  updateCustomOption(pluginId: string, key: string, value: unknown): Promise<void>;
+
+  /** Delete a single custom option key for a plugin. */
+  deleteCustomOption(pluginId: string, key: string): Promise<void>;
+
+  // --- websocket servers (generator-core built-in) ------------------------
+
+  /** Start a generator-core websocket server for a plugin; resolves to the port. */
+  startWebsocketServer(
+    pluginId: string,
+    desiredPort?: number,
+    domain?: any,
+    origin?: string
+  ): Promise<number>;
+
+  /** Stop a plugin's generator-core websocket server. */
+  stopWebsocketServer(pluginId: string): Promise<void>;
+
+  // --- interpolation constants (generator.js:1102-1135) -------------------
+
+  readonly INTERPOLATION_NEAREST_NEIGHBOR: "nearestNeighbor";
+  readonly INTERPOLATION_BILINEAR: "bilinear";
+  readonly INTERPOLATION_BICUBIC: "bicubic";
+  readonly INTERPOLATION_BICUBIC_SMOOTHER: "bicubicSmoother";
+  readonly INTERPOLATION_BICUBIC_SHARPER: "bicubicSharper";
+  readonly INTERPOLATION_BICUBIC_AUTOMATIC: "bicubicAutomatic";
+  readonly INTERPOLATION_PRESERVE_DETAILS_UPSCALE: "preserveDetailsUpscale";
+  readonly INTERPOLATION_AUTOMATIC: "automaticInterpolation";
+}
+
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * 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[];
+};
+/**
+ * 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;
+    width: number;
+    height: number;
+}
+interface PsBounds {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+
+/**
+ * The plugin contract a Plugin depends on (RFC 0003) — a deliberately narrowed
+ * view of the server's `PsBridgeHost`. Exposes only what a Plugin needs: the JSX
+ * seam and the feature-module accessors (all typed by the generator's own
+ * contract interfaces), plus the listen-only event stream. Excludes
+ * broadcast/emit/server/the raw generator handle — a Plugin manages its own
+ * clients through BasePlugin.broadcast/send.
+ *
+ * This is the one hand-written piece of the plugin surface that stays in the
+ * SDK: it is a *curation* of the host, not a mirror of it. Its member types are
+ * imported (type-only) from the generator contract so they can never drift from
+ * the implementation. The server's `PsBridgeHost implements PluginHost`;
+ * external Plugins only ever see this interface, so they depend on the SDK alone
+ * at runtime, never on the server package.
+ */
+interface PluginHost {
+    readonly jsx: JsxRunnerApi;
+    /** Feature modules, reached by short key (e.g. `plugin.modules.layer`). */
+    readonly modules: {
+        layer: LayerModuleApi;
+        document: DocumentModuleApi;
+        action: ActionModuleApi;
+        image: ImageModuleApi;
+    };
+    /** Typed, listen-only Photoshop event stream (lazy subscribe). */
+    readonly events: PhotoshopEvents;
+    /**
+     * Optional object-storage upload service (RFC 0008). Present only when the host
+     * has COS configured via the environment; undefined otherwise. A plugin guards
+     * on it: `if (this.plugin.cos) await this.plugin.cos.uploadObject(bytes)`.
+     */
+    readonly cos?: CosServiceApi;
+}
+
+/**
+ * A single progress notification emitted by Photoshop while a jsx file
+ * evaluates via `_sendJSXFile`. `type` is `"javascript"` (an evaluation result
+ * — e.g. a bounds object), `"pixmap"` (a raw pixmap buffer), or `"iccProfile"`
+ * (a raw ICC profile buffer).
+ */
+interface JsxProgressMessage {
+    type: "javascript" | "pixmap" | "iccProfile" | string;
+    value: unknown;
+}
+/**
+ * Typed handle to an in-flight `_sendJSXFile` evaluation. `onProgress`/`onFail`
+ * subscribe to the underlying deferred's streams; `resolve`/`reject` let the
+ * caller signal completion (required — the deferred won't settle on its own).
+ * Isolates the `_sendJSXFile` touchpoint inside the JSX seam so callers like
+ * `ImageModule.getPixmap` never reach generator-core's transport directly.
+ */
+interface JsxChannel {
+    onProgress(fn: (message: JsxProgressMessage) => void): void;
+    onFail(fn: (err: unknown) => void): void;
+    resolve(): void;
+    reject(err?: unknown): void;
+}
+/**
+ * The slice of JsxRunner a Plugin reaches through `plugin.jsx` (RFC 0003 /
+ * RFC 0005). The concrete JsxRunner `implements` this (and `forPlugin` returns a
+ * scoped view that also implements it), so the plugin contract can never drift
+ * from the implementation; the SDK re-exports it (via src/contract.ts) as the
+ * type of `PluginHost.jsx`. Excludes lifecycle (`init`) and the low-level pixmap
+ * channel (`openJSXFile`) — plugins only run jsx by name (or raw string).
+ *
+ * `execute` resolves against *this handle's own* jsx scope: the built-in `jsx/`
+ * tree for the host's root runner, or the plugin's own `jsx/` dir for the scoped
+ * view `plugin.jsx` returns. `executeBuiltin` always targets the built-in tree,
+ * so a plugin can reach a host domain (e.g. `Document/getDocumentInfo`) without
+ * knowing its own id or dir. `run` takes a raw script and is scope-independent.
+ */
+interface JsxRunnerApi {
+    execute<T = unknown>(name: string, params?: Record<string, unknown>, sharedEngineSafe?: boolean): Promise<T>;
+    executeBuiltin<T = unknown>(name: string, params?: Record<string, unknown>, sharedEngineSafe?: boolean): Promise<T>;
+    run<T = unknown>(script: string): Promise<T>;
+}
+/**
+ * Runs packaged jsx by name (ADR 0008). Resolves a name like
+ * `Document/getDocumentInfo` to its physical path under the bundle's `jsx/`
+ * directory, hands it to the injected generator's `evaluateJSXFile`, and
+ * normalizes the result.
+ *
+ * Returns `message.value` verbatim — it does NOT `JSON.parse` for the caller;
+ * the `T` type parameter is a labelling convenience only. A string value
+ * starting with `"Error:"` becomes a thrown `Error` carrying the remainder.
+ *
+ * jsx text caching is handled by generator-core's `_sendJSXCache`, so this seam
+ * adds none of its own. `__dirname` is `dist` for all bundled code, so
+ * `polyfillsDir` defaults to `dist/jsx/polyfills`.
+ *
+ * ExtendScript's default engine persists globals across evaluations, so the
+ * polyfills injected once in `init()` remain available to every later
+ * `execute` (and to `run` when it uses the default engine). The default engine
+ * is the only one primed — `sharedEngineSafe` callers use a separate engine
+ * that does NOT receive the polyfills.
+ */
+declare class JsxRunner implements JsxRunnerApi {
+    private readonly generator;
+    private readonly logger;
+    private readonly polyfillsDir;
+    private readonly jsxDir;
+    private polyfillsCache;
+    constructor(generator: PsGenerator, logger: Logger, polyfillsDir?: string);
+    /**
+     * A jsx runner scoped to a plugin's own `jsx/` dir (RFC 0005). The returned
+     * handle's `execute` resolves under `dir`, while `executeBuiltin` still targets
+     * the built-in tree; `run` is unchanged. The scope is the *only* per-plugin
+     * state — there is no shared mutable registry; the host builds one of these per
+     * plugin in `hostFor` and injects it as `plugin.jsx`.
+     */
+    forPlugin(dir: string): JsxRunnerApi;
+    /**
+     * Resolve a jsx name to an absolute `.jsx` path under `baseDir`. The name may
+     * carry domain subdirs (e.g. `Document/getDocumentInfo`). No escape guard: jsx
+     * names come from trusted in-process code (a module or a plugin's own source),
+     * which already runs arbitrary JS, so a guard would add no boundary.
+     */
+    private resolvePath;
+    /**
+     * Prime the default ExtendScript engine with ES polyfills. Reads every
+     * `*.js` file under `polyfillsDir` (recursively, sorted by relative path for
+     * deterministic concatenation order), concatenates them into `polyfillsCache`,
+     * and evaluates the bundle once. Must be awaited before any `execute` call
+     * that depends on the polyfills; `PsBridgeHost.onInit` does this before
+     * `server.listen`.
+     *
+     * Missing dir -> throw (packaging bug). Empty dir -> no-op. Injection
+     * returning `"Error:…"` or rejecting -> throw, so a broken polyfill surfaces
+     * at startup rather than as a runtime `find is not a function`.
+     */
+    init(): Promise<void>;
+    /**
+     * Run the jsx registered under `name` in the built-in `jsx/` tree (domain
+     * subdirs included, e.g. `Document/getDocumentInfo`). `params` are inlined into
+     * the script; `sharedEngineSafe` opts into Photoshop's shared script engine.
+     * The root runner's own scope *is* the built-in tree, so `execute` and
+     * `executeBuiltin` coincide here; a plugin's scoped view (see `forPlugin`)
+     * splits them apart.
+     */
+    execute<T = unknown>(name: string, params?: Record<string, unknown>, sharedEngineSafe?: boolean): Promise<T>;
+    /**
+     * Alias of `execute` on the root runner — always the built-in tree. Present so
+     * the root satisfies `JsxRunnerApi` alongside the scoped view; the scoped view
+     * overrides `execute` (plugin dir) while delegating `executeBuiltin` here.
+     */
+    executeBuiltin<T = unknown>(name: string, params?: Record<string, unknown>, sharedEngineSafe?: boolean): Promise<T>;
+    /**
+     * Run the jsx under `name` resolved against `baseDir`. The seam through which
+     * both the root runner (built-in tree) and the scoped view (a plugin's dir)
+     * reach Photoshop; keeps path resolution + result normalization in one place.
+     *
+     * @internal Server-internal — not on `JsxRunnerApi`, not reachable by plugins.
+     * Public only so the sibling `ScopedJsx` can delegate to it.
+     */
+    executeIn<T = unknown>(baseDir: string, name: string, params?: Record<string, unknown>, sharedEngineSafe?: boolean): Promise<T>;
+    /**
+     * Evaluate an arbitrary jsx string in the default ExtendScript engine (the
+     * same engine `init()` primed with polyfills). No `sharedEngineSafe` opt-out:
+     * polyfills live only in the default engine, so a shared-engine variant would
+     * be silently un-polyfilled. Return value follows the same convention as
+     * `run` — verbatim, with `"Error:"`-prefixed strings turned into thrown
+     * Errors.
+     */
+    run<T = unknown>(script: string): Promise<T>;
+    /**
+     * Open a built-in packaged jsx file via the low-level `_sendJSXFile` channel
+     * and return a typed handle to its in-flight evaluation. A root-runner-only
+     * seam (not on `JsxRunnerApi`): the only caller is `ImageModule.getPixmap`.
+     * Plugins reach pixmaps through `plugin.modules.image`, not this channel.
+     *
+     * Unlike `run` (which
+     * awaits a single resolved value), this exposes the raw progress stream so
+     * the caller can collect the multi-message responses Photoshop emits for
+     * pixmap-producing scripts (bounds + pixmap + optional ICC profile). The
+     * caller owns completion: it must call `channel.resolve()` once it has
+     * received every message it expected, or `channel.reject(err)` on failure.
+     *
+     * `sharedEngineSafe` defaults to `true` to match the pixmap protocol
+     * (generator-core's `getPixmap` / `getDocumentPixmap` both use the shared
+     * engine).
+     */
+    openJSXFile(name: string, params?: Record<string, unknown>, sharedEngineSafe?: boolean): JsxChannel;
+    /**
+     * Shared result normalization for `run` and `execute`: a string starting with
+     * `"Error:"` becomes a thrown `Error` carrying the remainder; everything else
+     * is returned verbatim (no `JSON.parse` — `T` is a labelling convenience).
+     */
+    private normalizeJsxResult;
+    /**
+     * Recursively list `*.js` files under `polyfillsDir`, sorted by relative path
+     * (POSIX-normalized) so concatenation order is stable across platforms and
+     * polyfills that depend on each other load in a fixed sequence. Throws if the
+     * directory itself is missing.
+     */
+    private collectPolyfillFiles;
+}
+
+/**
+ * Layer/document bounds in pixels. The console logged this as `[Object]` (not
+ * expanded); this is the standard generator bounds shape.
+ */
+interface Bounds {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+/** One entry in `imageChanged.layers` — a layer touched by the change. */
+interface ImageChangedLayer {
+    /** Layer id (stable across the session). */
+    id: number;
+    /** Present (true) when the layer's pixels changed. */
+    pixels?: boolean;
+    /** Present (true) when the layer was removed in this change. */
+    removed?: boolean;
+    /** Layer bounds; present on geometry/pixel changes. */
+    bounds?: Bounds;
+}
+/**
+ * Payload of the `imageChanged` event. Fields are a union of everything PS may
+ * send; only `version` / `timeStamp` / `count` / `id` are always present. A
+ * single event carries *either* metadata flags (`metaDataOnly`, `selection`),
+ * *or* `layers`, *or* document-level flags (`active` / `file` / `closed`).
+ */
+interface ImageChangedEvent {
+    /** Generator protocol version, e.g. "1.6.1". */
+    version: string;
+    /** Seconds since epoch (float), e.g. 1782455135.936. */
+    timeStamp: number;
+    /** Per-document monotonically increasing change counter (resets per doc id). */
+    count: number;
+    /** Document id this change belongs to. */
+    id: number;
+    /** True on the first event for a doc / on activation. */
+    active?: boolean;
+    /** Document title or full path, e.g. "Test-恢复的.psd" or "C:\\...\\Test.psd". */
+    file?: string;
+    /** True when the document was closed. */
+    closed?: boolean;
+    /** True when only metadata changed (no pixel/layer body). */
+    metaDataOnly?: boolean;
+    /** Selected layer indices; empty array when the selection is cleared. */
+    selection?: number[];
+    /** Layers touched by this change (pixel edits, bounds, removals). */
+    layers?: ImageChangedLayer[];
+}
+/**
+ * Map of Photoshop event name -> payload type passed to the listener. Shapes
+ * marked "observed" were confirmed from live PS output; the rest are inferred
+ * from the generator protocol docs.
+ */
+interface PhotoshopEventMap {
+    /** [workspace display name] (inferred). */
+    workspaceChanged: string;
+    /** Tool name, e.g. "paintbrushTool" / "moveTool" (observed). */
+    toolChanged: string;
+    /** "enter" | "exit" (inferred). */
+    quickMaskStateChanged: string;
+    /** Document id (observed). */
+    documentChanged: number;
+    /** Document id of the closed document (observed). */
+    closedDocument: number;
+    /** Document id (inferred). */
+    newDocumentViewCreated: number;
+    /** Document id (inferred). */
+    activeViewChanged: number;
+    /** Document id of the now-current document (observed). */
+    currentDocumentChanged: number;
+    /** Color as 6-character hex value (inferred). */
+    backgroundColorChanged: string;
+    /** Color as 6-character hex value (inferred). */
+    foregroundColorChanged: string;
+    /** Image/document change descriptor (observed). */
+    imageChanged: ImageChangedEvent;
+}
+/** Listener for a given Photoshop event key. */
+type PhotoshopEventListener<K extends keyof PhotoshopEventMap> = (payload: PhotoshopEventMap[K]) => void;
+/**
+ * Listen-only typed surface a Plugin reaches through `plugin.events` /
+ * `this.events`. `EventManager` (an `EventEmitter`) `implements` this; `emit` is
+ * deliberately excluded — a Plugin subscribes, it never dispatches Photoshop
+ * events.
+ */
+interface PhotoshopEvents {
+    on<K extends keyof PhotoshopEventMap>(event: K, listener: PhotoshopEventListener<K>): this;
+    once<K extends keyof PhotoshopEventMap>(event: K, listener: PhotoshopEventListener<K>): this;
+    off<K extends keyof PhotoshopEventMap>(event: K, listener: PhotoshopEventListener<K>): this;
+}
+type Listener<K extends keyof PhotoshopEventMap> = PhotoshopEventListener<K>;
+/**
+ * Owns the plugin's Photoshop event subscriptions, exposed as a typed
+ * `EventEmitter`. Held by `PsBridgeHost` (see `plugin.events`).
+ *
+ * Subscriptions are lazy: the manager only calls `generator.onPhotoshopEvent`
+ * the first time a caller listens to an event, and `removePhotoshopEventListener`
+ * once the last listener for that event goes away. Reference counting rides on
+ * the `newListener` / `removeListener` meta-events so every add/remove path
+ * (`on` / `once` / `off` / `removeAllListeners`) is covered.
+ *
+ * The `on` / `once` / `off` / `emit` signatures are narrowed to
+ * `PhotoshopEventMap`, so only confirmed events can be listened to at compile
+ * time; unknown names throw at runtime.
+ */
+declare class EventManager extends EventEmitter implements PhotoshopEvents {
+    private readonly generator;
+    private readonly bridges;
+    constructor(generator: PsGenerator);
+    on<K extends keyof PhotoshopEventMap>(event: K, listener: Listener<K>): this;
+    once<K extends keyof PhotoshopEventMap>(event: K, listener: Listener<K>): this;
+    addListener<K extends keyof PhotoshopEventMap>(event: K, listener: Listener<K>): this;
+    off<K extends keyof PhotoshopEventMap>(event: K, listener: Listener<K>): this;
+    removeListener<K extends keyof PhotoshopEventMap>(event: K, listener: Listener<K>): this;
+    /** Dispatch a payload to listeners. Fired by the PS bridge; not for external use. */
+    emit<K extends keyof PhotoshopEventMap>(event: K, payload: PhotoshopEventMap[K]): boolean;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+    /** First listener for a PS event -> subscribe upstream once. */
+    private onAdd;
+    /** Last listener for a PS event removed -> detach the upstream bridge. */
+    private onRemove;
+}
+
+/**
+ * Action-domain feature module (ADR 0006). Exposes the `Action:*` WS Request
+ * methods, each backed by a packaged `jsx/Action/<name>.jsx` script run through
+ * the plugin's `JsxRunner` (ADR 0008). A jsx failure follows the `"Error:"`
+ * prefix convention: `JsxRunner` throws, and `Registry.dispatch` turns it into an
+ * INTERNAL response — the methods themselves do not catch.
+ *
+ * Migrated from LightAi's `ActionManager`. The `@McpTool` metadata did not carry
+ * over (no MCP runtime here — only the `@ws` WS path), but the human-facing
+ * descriptions are preserved as method JSDoc.
+ */
+/**
+ * The Action module surface a Plugin reaches through `plugin.modules.action`
+ * (RFC 0003). `ActionModule implements` this; the SDK re-exports it via
+ * src/contract.ts.
+ */
+interface ActionModuleApi {
+    autoCutout(): Promise<boolean>;
+    removeBackground(): Promise<{
+        success: boolean;
+    }>;
+}
+declare class ActionModule extends BaseModule implements ActionModuleApi {
+    constructor(plugin: PsBridgeHost);
+    /**
+     * Automatically create a selection for the main subject of the current layer.
+     * Runs `jsx/Action/autoCutout.jsx`. The jsx return value is not consulted:
+     * success is implicit, and a failure surfaces as a thrown error (hence an
+     * INTERNAL response), so this always resolves to `true` on the happy path.
+     */
+    autoCutout(): Promise<boolean>;
+    /**
+     * Remove the background of the current layer. Runs `jsx/Action/removeBackground.jsx`
+     * and wraps the jsx's boolean result as `{ success }`.
+     */
+    removeBackground(): Promise<{
+        success: boolean;
+    }>;
+}
+
+type PsDocument = {
+    id: number;
+    name: string;
+    width: number;
+    height: number;
+    resolution: number;
+    isDirty: boolean;
+    filePath?: string;
+};
+/**
+ * The Document module surface a Plugin reaches through `plugin.modules.document`
+ * (RFC 0003). `DocumentModule implements` this; the SDK re-exports it via
+ * src/contract.ts.
+ */
+interface DocumentModuleApi {
+    getCurrentDocument(): Promise<PsDocument>;
+    exportDocument(params: Record<string, unknown>): Promise<unknown>;
+    saveDocument(params: {
+        savePath?: string;
+    }): Promise<unknown>;
+}
+declare class DocumentModule extends BaseModule implements DocumentModuleApi {
+    constructor(plugin: PsBridgeHost);
+    currentDocument: PsDocument | null;
+    getCurrentDocument(): Promise<PsDocument>;
+    exportDocument(params: Record<string, any>): Promise<unknown>;
+    saveDocument(params: {
+        savePath?: string;
+    }): Promise<unknown>;
+}
+
+/**
+ * Single-layer pixmap export + preview, isolated from the buggy
+ * `generator.getPixmap` (generator-core's version omits the
+ * `includeAdjustors/Children/ClipBase/Clipped` flags and passes a stray
+ * `settings.thread` field). `getPixmap` here is a faithful port of
+ * LightAi's `LayerManager.getPixmap` (index.ts:364-482): it calls the plugin's
+ * own `Layer/getLayerPixmap.jsx` over the progress channel and collects the
+ * bounds + pixmap + ICC profile messages Photoshop streams back.
+ *
+ * Whole-document export is handled separately by generator-core's
+ * `getDocumentPixmap` (to be wired up later); this module only deals with
+ * explicit layer specs, which is what `Layer/getLayerPixmap.jsx` requires.
+ *
+ * Encoding (raw RGBA -> PNG) goes through `sharp`, externalized from the bundle
+ * and resolved from node_modules at runtime inside Photoshop's Node.
+ */
+/**
+ * The Image module surface a Plugin reaches through `plugin.modules.image`
+ * (RFC 0003). `ImageModule implements` this; the SDK re-exports it via
+ * src/contract.ts. `settings` is widened to `Record<string, unknown>` so the
+ * plugin contract does not drag the generator-core `GetPixmapSettings` namespace
+ * into the SDK; `buffer` is `Uint8Array` (not `Buffer`) so the SDK stays
+ * Node-free.
+ */
+interface ImageModuleApi {
+    exportImage(options: {
+        documentId?: number;
+        layerSpec: LayerSpec;
+        settings?: Record<string, unknown>;
+    }): Promise<ImageResult>;
+    getPreview(options: {
+        documentId?: number;
+        layerSpec: number;
+    }): Promise<ImageResult>;
+    exportDocument(options: {
+        documentId?: number;
+        settings?: Record<string, unknown>;
+    }): Promise<ImageResult>;
+}
+declare class ImageModule extends BaseModule implements ImageModuleApi {
+    constructor(plugin: PsBridgeHost);
+    /**
+     * Export a single layer as a PNG buffer plus its bounds and pixel
+     * dimensions. `settings` carries the `GetPixmapSettings` Photoshop accepts;
+     * the four `include*` flags default to `true` when unspecified (the fix over
+     * generator-core). `layerSpec` is required — the underlying jsx needs an
+     * explicit layer id or index range.
+     */
+    exportImage(options: {
+        documentId?: number;
+        layerSpec: LayerSpec;
+        settings?: PsGenerator.GetPixmapSettings;
+    }): Promise<ImageResult>;
+    /**
+     * Export a downscaled preview of a single layer. The scale is computed so
+     * the longer edge lands near 300px; scaling is done by Photoshop via
+     * `scaleX/scaleY`, not by `sharp`. `includeClipped/ClipBase/Adjustors` are
+     * forced to `false` to fetch only the body layer's pixels. `layerSpec` is
+     * required (a layer id; the layer's `rect` drives the scale).
+     */
+    getPreview(options: {
+        documentId?: number;
+        layerSpec: number;
+    }): Promise<ImageResult>;
+    /**
+     * Export the whole document (its current visibility state, flattened) as a PNG
+     * buffer plus bounds and pixel dimensions. Unlike `exportImage` (a single layer
+     * via the `Layer/getLayerPixmap` jsx protocol), this uses generator-core's
+     * built-in `getDocumentPixmap`, which returns an already-parsed `PsPixmap`.
+     * `documentId` defaults to the current document; `settings` carries the
+     * `GetPixmapSettings` Photoshop accepts (e.g. `scaleX`/`scaleY`).
+     */
+    exportDocument(options: {
+        documentId?: number;
+        settings?: PsGenerator.GetPixmapSettings;
+    }): Promise<ImageResult>;
+    /**
+     * `@ws` wrapper over {@link exportImage} (RFC 0008). Returns a wire-friendly
+     * {@link WsImageResult}: when `plugin.cos` is enabled the PNG is uploaded and
+     * `data` is an https URL, otherwise `data` is a base64 data URI. A COS upload
+     * failure throws (no base64 fallback) — a configured channel must be used.
+     */
+    exportLayerWs(options: {
+        documentId?: number;
+        layerSpec: LayerSpec;
+        settings?: PsGenerator.GetPixmapSettings;
+    }): Promise<WsImageResult>;
+    /**
+     * `@ws` wrapper over {@link getPreview} (RFC 0008). Always returns base64 —
+     * previews are high-frequency, downscaled thumbnails not worth a COS round-trip,
+     * so this never uploads even when `plugin.cos` is enabled.
+     */
+    getPreviewWs(options: {
+        documentId?: number;
+        layerSpec: number;
+    }): Promise<WsImageResult>;
+    /**
+     * `@ws` wrapper over {@link exportDocument} (RFC 0008). Uploads to COS when
+     * enabled (https URL), else base64; a COS failure throws.
+     */
+    exportDocumentWs(options: {
+        documentId?: number;
+        settings?: PsGenerator.GetPixmapSettings;
+    }): Promise<WsImageResult>;
+    /**
+     * Turn a module-internal {@link ImageResult} (raw PNG `buffer`) into the
+     * wire-friendly {@link WsImageResult} (`data` string). With `upload` set and
+     * `plugin.cos` enabled, the buffer is uploaded and `data` is the signed URL;
+     * otherwise `data` is a `data:image/png;base64,...` URI. Both forms drop
+     * straight into an `<img src>`.
+     */
+    private toWsResult;
+    /**
+     * Resolve a layer's name for the COS object key. A numeric `layerSpec` is
+     * looked up via the layer module; an index-range spec has no single name, so it
+     * falls back to "layers". Lookup failures degrade to `layer-{id}` rather than
+     * failing the export.
+     */
+    private resolveLayerName;
+    /**
+     * Resolve a document's name for the COS object key. Uses the current document's
+     * name when the target is the current document; otherwise falls back to
+     * `doc-{id}` rather than spending a jsx round-trip to name an off-screen doc.
+     */
+    private resolveDocumentName;
+    /**
+     * Faithful port of LightAi `LayerManager.getPixmap` (index.ts:364-482).
+     * Builds the params (dropping generator-core's stray `settings.thread` and
+     * defaulting the four `include*` flags to `true`), opens the pixmap jsx over
+     * the progress channel, and resolves three native promises as the
+     * bounds/pixmap/iccProfile messages arrive. Once all expected messages are
+     * in, signals the channel to settle and constructs a `Pixmap`.
+     */
+    private getPixmap;
+    /**
+     * Resolve the document id: explicit override, else the document module's
+     * current document, else fail loud (matches LightAi's "No document opened").
+     */
+    private resolveDocumentId;
+    /**
+     * Convert a pixmap's raw pixels into a tightly-packed RGBA buffer. Handles both
+     * the single-layer protocol (`getLayerPixmap`: 4-channel, no row padding) and
+     * generator-core's `getDocumentPixmap` (which may return 3-channel pixmaps and
+     * rows padded to `rowBytes`). 4-channel is Photoshop's `[A,R,G,B]` layout;
+     * 3-channel is `[R,G,B]` and gets an opaque alpha. Rows are walked by
+     * `rowBytes` so any per-row padding is skipped rather than misaligning the image.
+     */
+    private parseRawPixels;
+    private encodePng;
+}
+/**
+ * Result of an image export / preview: PNG bytes plus geometry metadata. The
+ * bytes are typed as `Uint8Array` (the implementation returns a `Buffer`, which
+ * is a `Uint8Array` subtype) so this type can cross into the Node-free SDK
+ * contract unchanged.
+ */
+interface ImageResult {
+    buffer: Uint8Array;
+    bounds: PsBounds$1;
+    width: number;
+    height: number;
+}
+
+/**
+ * Plugin-facing COS contract (RFC 0008). The minimal slice modules and plugins
+ * reach through `plugin.cos`: upload in-memory bytes or a local file and get back
+ * a ready-to-use signed URL. Params use `Uint8Array`/path strings (never `Buffer`
+ * or the COS SDK's own types) so the SDK's re-export of this interface stays
+ * Node-free, mirroring how `ImageModuleApi` is exposed.
+ */
+interface CosServiceApi {
+    /** Upload raw bytes, returning a signed URL. `name` labels the object key. */
+    uploadObject(data: Uint8Array, name?: string): Promise<string>;
+    /** Upload a local file by path, returning a signed URL. */
+    uploadFile(dir: string, name?: string): Promise<string>;
+}
+/** Permanent-key COS config, read from the environment by {@link CosService.fromEnv}. */
+interface CosConfig {
+    secretId: string;
+    secretKey: string;
+    bucket: string;
+    region: string;
+    keyPrefix: string;
+    urlExpires: number;
+}
+/**
+ * Optional object-storage upload unit (RFC 0008). Enabled only when the four
+ * `PS_BRIDGE_COS_*` env fields are present; otherwise the host leaves `plugin.cos`
+ * undefined and image exports fall back to base64. Uses a permanent key pair and
+ * returns signed URLs without an attachment disposition, so the image they point
+ * at stays inline-displayable.
+ */
+declare class CosService implements CosServiceApi {
+    private readonly config;
+    private readonly logger;
+    private readonly cos;
+    constructor(config: CosConfig, logger: Logger);
+    /**
+     * Build a CosService from the environment, or return undefined when COS is not
+     * configured. All four `PS_BRIDGE_COS_SECRET_ID/SECRET_KEY/BUCKET/REGION` must be
+     * present and non-empty — a missing field means "not enabled", decided once at
+     * startup rather than failing loudly on the first upload.
+     */
+    static fromEnv(logger: Logger): CosService | undefined;
+    uploadObject(data: Uint8Array, name?: string): Promise<string>;
+    uploadFile(dir: string, name?: string): Promise<string>;
+    /**
+     * Compose the object key `{keyPrefix}/{name}-{ts}{ext}` (keyPrefix is env-
+     * configurable, default `ps-bridge/exports`). `name` (a layer/document name) is
+     * kept verbatim including non-ASCII (e.g. Chinese); only path separators and
+     * whitespace are replaced — they would nest the key or break the URL — and the
+     * label is length-capped. Uniqueness rides on the timestamp, not the label.
+     */
+    private buildKey;
+    private sanitizeName;
+    private putObject;
+    private putFile;
+    private signedUrl;
+}
+
+/** Host config handed in by generator-core (self._config[name]). */
+interface PluginConfig {
+    port?: number;
+    /**
+     * Directory whose direct child folders are loaded as plugin packages
+     * (each a `package.json` with a `main` entry; see the plugin loader).
+     * Defaults to `<generator-package>/plugins` — i.e. `packages/generator/plugins`,
+     * a symlink to the repo-root `/plugins` in development.
+     */
+    pluginsDir?: string;
+    [key: string]: unknown;
+}
+/**
+ * Test-only overrides for `JsxRunner` construction. Production callers pass
+ * nothing; tests point `polyfillsDir` at the source `jsx/polyfills` tree so
+ * `init()` reads real files instead of the bundler's `dist/jsx/polyfills`
+ * (which `__dirname`-based resolution can't reach under vitest's source
+ * runtime).
+ */
+interface JsxRunnerOverrides {
+    polyfillsDir?: string;
+}
+/**
+ * The host generator-core loads. Registers a menu item and starts the server's
+ * own WebSocket service (ADR 0003). Every call into Photoshop goes through the
+ * injected `generator`, which makes the whole init path observable from a test
+ * mock (see test/fakeGenerator.ts).
+ */
+declare class PsBridgeHost implements PluginHost {
+    readonly generator: PsGenerator;
+    readonly config: PluginConfig;
+    readonly logger: Logger;
+    private server;
+    /** Feature modules, reached by short key (`host.modules.layer`, ADR 0009). */
+    readonly modules: {
+        layer: LayerModule;
+        document: DocumentModule;
+        action: ActionModule;
+        image: ImageModule;
+    };
+    private plugins;
+    private readonly _jsx;
+    private readonly _events;
+    /**
+     * Optional object-storage upload service (RFC 0008). Set from the environment
+     * at construction — present only when the `PS_BRIDGE_COS_*` fields are configured;
+     * otherwise undefined. Reached by modules and plugins through `plugin.cos`.
+     */
+    readonly cos?: CosService;
+    private constructor();
+    /** Run packaged jsx by name (ADR 0008). Used by modules and other server callers. */
+    get jsx(): JsxRunner;
+    /** Photoshop event subscriptions owned by the host. */
+    get events(): EventManager;
+    /**
+     * Build the host contract for one plugin (RFC 0005). A shallow view that shares
+     * the host's `modules` and `events` (both global-singleton semantics — they do
+     * not split per plugin) but swaps in a `jsx` scoped to `<pluginDir>/jsx`, so the
+     * plugin's `jsx.execute("x")` resolves to its own files while `executeBuiltin`
+     * still reaches the built-in tree. Passed to `loadPlugins` as the `hostFor`
+     * factory; the plugin never sees the concrete `PsBridgeHost`.
+     */
+    private hostFor;
+    /** Entry point: construct the host and run its async initialization. */
+    static init(generator: PsGenerator, config: PluginConfig, logger: Logger, overrides?: JsxRunnerOverrides): Promise<PsBridgeHost>;
+    private onInit;
+    private createMenuItem;
+    private handleMenuClicked;
+    /** Stop the WebSocket service (used by tests; PS teardown is process exit). */
+    close(): Promise<void>;
+}
+
+/**
+ * Base class for feature modules (ADR 0006). A module reaches every dependency
+ * through `this.plugin` — `this.plugin.generator` for Photoshop, `this.plugin.logger`,
+ * and `this.plugin.emit` / `this.plugin.broadcast` to push Events. Methods are
+ * exposed via the `@ws` / `@api` decorators and wired up by `bootstrap`.
+ */
+declare abstract class BaseModule {
+    readonly name: string;
+    readonly plugin: PsBridgeHost;
+    constructor(name: string, plugin: PsBridgeHost);
+}
+
+declare class PsLayer {
+    id: number;
+    index: number;
+    name: string;
+    type: number;
+    visible: boolean;
+    bounds: PsBounds$1;
+    rect: PsRect;
+    clip: boolean;
+    children?: PsLayer[];
+    constructor(init: Partial<PsLayer>);
+}
+/**
+ * The Layer module surface a Plugin reaches through `plugin.modules.layer`
+ * (RFC 0003). `LayerModule implements` this, so the plugin contract tracks the
+ * implementation by compiler force; the SDK re-exports it via src/contract.ts.
+ */
+interface LayerModuleApi {
+    getLayerInfo(options?: {
+        id?: number;
+        index?: number;
+        getChildren?: boolean;
+        getGeneratorSettings?: boolean;
+    }): Promise<PsLayer>;
+    getLayerInfoByID(layerID: number, options?: {
+        getChildren: boolean;
+    }): Promise<PsLayer>;
+    getLayerInfoByIndex(layerIndex: number, options?: {
+        getChildren: boolean;
+    }): Promise<PsLayer>;
+}
+declare class LayerModule extends BaseModule implements LayerModuleApi {
+    constructor(plugin: PsBridgeHost);
+    getLayerInfo(options?: {
+        id?: number;
+        index?: number;
+        getChildren?: boolean;
+        getGeneratorSettings?: boolean;
+    }): Promise<PsLayer>;
+    getLayerInfoByID(layerIDOrParams: number | {
+        layerID: number;
+        options?: {
+            getChildren: boolean;
+        };
+    }, options?: {
+        getChildren: boolean;
+    }): Promise<PsLayer>;
+    getLayerInfoByIndex(layerIndexOrParams: number | {
+        layerIndex: number;
+        options?: {
+            getChildren: boolean;
+        };
+    }, options?: {
+        getChildren: boolean;
+    }): Promise<PsLayer>;
+}
+
+export { type ActionModuleApi as A, type Bounds as B, type CosServiceApi as C, type DocumentModuleApi as D, type ImageChangedEvent as I, JsxRunner as J, type LayerModuleApi as L, PsGenerator as P, type PluginConfig as a, PsBridgeHost as b, type ImageChangedLayer as c, type ImageModuleApi as d, type ImageResult as e, type JsxRunnerApi as f, type LayerSpec as g, type PhotoshopEventListener as h, type PhotoshopEventMap as i, type PhotoshopEvents as j, type PsBounds$1 as k, type PsDocument as l, PsLayer as m, type PsRect as n };