@ps-generator-bridge/sdk 0.1.0

package/dist/plugin.d.ts

@@ -0,0 +1,457 @@
+import { L as LayerSpec, e as PsPhotoshopProxy } from './PsPhotoshopProxy-BjnvziWn.js';
+export { A as AnchorPosition, w as AnchorPositionValue, x as BlendMode, y as BlendModeValue, D as DocumentMode, z as DocumentModeValue, C as ElementPlacement, F as ElementPlacementValue, G as LayerKind, H as LayerKindValue, J as PhotoshopApp, K as PhotoshopDocument, N as PhotoshopLayer, O as PhotoshopLayers, Q as PhotoshopSelection, T as PsBoundsTuple, U as PsColor, V as SaveOptions, X as SaveOptionsValue, Y as SelectionType, Z as SelectionTypeValue } from './PsPhotoshopProxy-BjnvziWn.js';
+
+type PsBounds = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+type PsRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+/**
+ * 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>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+    }>;
+}
+
+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>;
+}
+
+/**
+ * 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>;
+}
+/**
+ * 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;
+    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>;
+}
+
+declare class PsLayer {
+    id: number;
+    index: number;
+    name: string;
+    type: number;
+    visible: boolean;
+    bounds: PsBounds;
+    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>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Per-plugin client push bus (RFC 0004). BasePlugin.broadcast/send delegate to
+ * this; the server's per-plugin assembler attaches a concrete adapter backed by
+ * the plugin's own ClientStore after construction. Defined in the SDK so
+ * BasePlugin can be implemented without depending on the server.
+ */
+interface PluginClientBus {
+    /** Push an Event to every online client of this plugin. */
+    broadcast(type: string, data: unknown): void;
+    /** Push an Event to one client of this plugin (no-op if not connected). */
+    send(clientId: string, type: string, data: unknown): void;
+}
+
+/**
+ * Base class for plugins (ADR 0009 / RFC 0003). A plugin is the orchestration
+ * layer above feature modules: it composes one or more module calls (reached
+ * through `this.modules`, e.g. `this.modules.layer`) and exposes
+ * its own `@ws`/`@api` handlers, bootstrapped the same way as modules.
+ *
+ * Dependency direction is strictly downward: a plugin may depend on modules,
+ * never on sibling plugins and never in reverse (modules must not reach
+ * plugins). `plugin` is the abstract PluginHost interface — never the
+ * concrete server plugin — so a plugin depends only on this SDK subpath.
+ *
+ * `@ws`/`@api` names are written in full by the developer (e.g.
+ * `@ws("LayerOps:merge")`) — `bootstrap` does not inject or derive a namespace.
+ * Use a `Domain:action` prefix to keep names from colliding across modules and
+ * plugins (ADR 0006 convention); the assembler's `registerMethod` is a silent
+ * `Map.set`, so prefix uniqueness is the developer's responsibility.
+ *
+ * Client push: `broadcast`/`send` reach only this plugin's own online clients,
+ * via the PluginClientBus the server attaches after construction. A subclass
+ * may override `onConnect`/`onDisconnect` to react to its clients coming and
+ * going; the defaults are no-ops.
+ */
+declare abstract class BasePlugin {
+    /** Stable URL identity of this plugin (read from the class's `static id`). */
+    readonly id: string;
+    /** The abstract plugin contract (never the concrete server plugin). */
+    protected readonly plugin: PluginHost;
+    private bus;
+    private _photoshop;
+    constructor(id: string, plugin: PluginHost);
+    /** Feature modules, reached by short key (shortcut for `this.plugin.modules`). */
+    protected get modules(): PluginHost["modules"];
+    /**
+     * The jsx runner scoped to this plugin's own `jsx/` dir (shortcut for
+     * `this.plugin.jsx`, RFC 0005). `jsx.execute("x")` runs `<pluginRoot>/jsx/x.jsx`;
+     * `jsx.executeBuiltin("Document/getDocumentInfo")` reaches the host's built-in
+     * tree.
+     */
+    protected get jsx(): JsxRunnerApi;
+    /**
+     * Typed, listen-only Photoshop event stream (shortcut for `this.plugin.events`).
+     * Subscriptions are lazy on the server side: the first `on`/`once` for an event
+     * subscribes upstream, and the last `off` unsubscribes.
+     */
+    protected get events(): PhotoshopEvents;
+    /**
+     * Photoshop DOM proxy, a typed object wrapper over `this.jsx`. Read and write
+     * the live document through `this.photoshop.app` / `this.photoshop.activeDocument`
+     * (e.g. `await this.photoshop.activeDocument.name`) instead of hand-writing
+     * ExtendScript. Lazily built once and backed by this plugin's own jsx runner;
+     * drop to `this.jsx.run(...)` for anything the proxy does not cover.
+     */
+    protected get photoshop(): PsPhotoshopProxy;
+    /**
+     * Attach the per-plugin client bus. Called by the server's assembler after
+     * construction and before `listen`, so `broadcast`/`send` are live by the time
+     * any handler can fire. Not part of the public Plugin authoring API.
+     */
+    _attachBus(bus: PluginClientBus): void;
+    /** Push an Event to every online client of this plugin. */
+    broadcast(type: string, data: unknown): void;
+    /** Push an Event to one client of this plugin (no-op if not connected). */
+    send(clientId: string, type: string, data: unknown): void;
+    /** Called after a client handshake registers with this plugin. Default no-op. */
+    onConnect(_clientId: string): void;
+    /** Called after a client socket is removed from this plugin. Default no-op. */
+    onDisconnect(_clientId: string): void;
+}
+/**
+ * Whether `S` is a class that extends BasePlugin. Uses the global brand rather
+ * than `instanceof` so it works when `S` came from a separately-bundled copy of
+ * this SDK (external plugins). The brand is inherited via the prototype chain,
+ * so direct and indirect subclasses both qualify.
+ */
+declare function isBasePluginClass(S: unknown): boolean;
+
+/**
+ * Minimal HTTP vocabulary for the @api decorator (ADR 0006 / RFC 0003). The SDK
+ * plugin subpath is platform-neutral and must not depend on fastify, so it
+ * declares its own string union; the server adapts it to fastify's HTTPMethods
+ * at the assembly boundary.
+ */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+/**
+ * A WS Request handler as seen by the plugin devkit (ADR 0006 open-ended
+ * contract). params/result are `unknown` at this layer; the SDK re-applies
+ * strong types for declared methods. `ctx` is opaque here — the server supplies
+ * a typed HandlerContext, and a handler accepting `unknown` accepts it.
+ */
+type MethodHandler = (params: unknown, ctx: unknown) => Promise<unknown> | unknown;
+/**
+ * An HTTP route handler as seen by the plugin devkit. request/reply are opaque
+ * (platform-neutral SDK); the server casts to fastify's request/reply at the
+ * assembly boundary.
+ */
+type ApiHandler = (request: unknown, reply: unknown) => Promise<unknown> | unknown;
+/** An HTTP route a module or plugin exposes via @api (ADR 0006). */
+interface ApiRouteSpec {
+    method: HttpMethod | HttpMethod[];
+    url: string;
+    handler: ApiHandler;
+}
+/**
+ * Abstract assembly target (ADR 0006 / RFC 0003): the second-stage bootstrap
+ * registers scanned @ws/@api metadata against this. The server provides two
+ * concrete implementations — the global Registry (modules + builtins) and a
+ * per-plugin scoped assembler (RFC 0004). The SDK only depends on this shape,
+ * keeping the dependency arrow server -> sdk / plugin -> sdk acyclic.
+ */
+interface AssemblyTarget {
+    registerMethod(name: string, handler: MethodHandler): void;
+    registerApi(route: ApiRouteSpec): void;
+}
+
+/** Mark a method as a WS Request handler registered under `name` (ADR 0006). */
+declare function ws(name: string): (_value: unknown, context: ClassMethodDecoratorContext) => void;
+/**
+ * Mark a method as an HTTP route handler. `@api("/path")` defaults to GET;
+ * `@api({ method, url })` selects the verb(s) (ADR 0006). The route URL is
+ * registered verbatim for modules (under `/{path}`) and prefixed with the
+ * plugin id for plugins (under `/{pluginId}/{path}`, RFC 0004) — the
+ * decorator only collects metadata; the assembly target decides the final URL.
+ */
+declare function api(pathOrRoute: string | {
+    method?: HttpMethod | HttpMethod[];
+    url: string;
+}): (_value: unknown, context: ClassMethodDecoratorContext) => void;
+/**
+ * Second stage of decorator registration (ADR 0006 / 0009): scan a module or
+ * plugin instance's collected metadata and register each decorated method
+ * against the assembly target, bound to the instance so handlers can reach
+ * `this`. Walks the metadata prototype chain so inherited handlers are included.
+ * The `@ws`/`@api` name is registered verbatim — developers write the full
+ * `Domain:action` name; no namespace is injected. For a plugin, the target is
+ * the per-plugin scoped assembler (RFC 0004); for a module, the global Registry.
+ */
+declare function bootstrap(instance: object, target: AssemblyTarget): void;
+
+export { type ActionModuleApi, type ApiHandler, type ApiRouteSpec, type AssemblyTarget, BasePlugin, type Bounds, type CosServiceApi, type DocumentModuleApi, type HttpMethod, type ImageChangedEvent, type ImageChangedLayer, type ImageModuleApi, type ImageResult, type JsxRunnerApi, type LayerModuleApi, LayerSpec, type MethodHandler, type PhotoshopEventListener, type PhotoshopEventMap, type PhotoshopEvents, type PluginClientBus, type PluginHost, type PsBounds, type PsDocument, PsLayer, PsPhotoshopProxy, type PsRect, api, bootstrap, isBasePluginClass, ws };