electron-snapora 1.0.1

package/dist/main/index.d.ts

@@ -0,0 +1,283 @@
+import { BrowserWindowConstructorOptions, BrowserWindow, WebContents, IpcMain, IpcMainInvokeEvent } from 'electron';
+import { ScreenshotErrorCode, ScreenshotOptions, ScreenshotResult } from '../types/index.js';
+export { ScreenshotBounds, ScreenshotImageResult, ScreenshotLocale, ScreenshotMessageOverrides, ScreenshotMessages, ScreenshotOutputMetadata, ScreenshotTheme, ScreenshotTool } from '../types/index.js';
+import { d as ScreenshotOutputPayload, e as ScreenshotOutputResponse, S as ScreenshotInitializePayload, C as CaptureDisplay, f as ScreenCaptureAdapter, g as CapturedFrame } from '../messages-DYY0MpGh.js';
+export { h as SCREENSHOT_PROTOCOL_VERSION, i as ScreenshotCancelPayload, b as ScreenshotCompletePayload, c as ScreenshotErrorPayload, j as ScreenshotOutputAction, k as ScreenshotReadyPayload } from '../messages-DYY0MpGh.js';
+
+type ScreenshotDiagnosticStage = 'queue' | 'session' | 'capture' | 'overlay-create' | 'overlay-load' | 'overlay-ready' | 'overlay-prepare' | 'output';
+type ScreenshotDiagnosticPhase = 'start' | 'complete' | 'cancel' | 'error';
+type ScreenshotDiagnosticContextValue = string | number | boolean | ReadonlyArray<string | number | boolean>;
+interface ScreenshotDiagnosticEvent {
+    jobId: string;
+    stage: ScreenshotDiagnosticStage;
+    phase: ScreenshotDiagnosticPhase;
+    timestamp: number;
+    durationMs?: number;
+    senderWebContentsId?: number;
+    code?: ScreenshotErrorCode;
+    message?: string;
+    context?: Readonly<Record<string, ScreenshotDiagnosticContextValue>>;
+}
+type ScreenshotDiagnosticListener = (event: Readonly<ScreenshotDiagnosticEvent>) => void;
+
+interface ScreenshotOutputContext {
+    senderWebContentsId: number;
+}
+
+interface ElectronOutputAdapterOptions {
+    saveFile?: (data: Uint8Array, suggestedName: string, senderWebContentsId: number) => Promise<string | undefined>;
+    copyImage?: (data: Uint8Array) => void;
+    createSuggestedName?: () => string;
+}
+interface ScreenshotOutputExecutor {
+    execute(payload: ScreenshotOutputPayload, context: ScreenshotOutputContext): Promise<ScreenshotOutputResponse>;
+}
+declare class ElectronOutputAdapter implements ScreenshotOutputExecutor {
+    #private;
+    constructor(options?: ElectronOutputAdapterOptions);
+    execute(payload: ScreenshotOutputPayload, context: ScreenshotOutputContext): Promise<ScreenshotOutputResponse>;
+}
+
+interface OverlayResources {
+    htmlPath: string;
+    preloadPath: string;
+}
+type PackagedResourceExists = (path: string) => boolean;
+interface MissingPackagedResource {
+    label: string;
+    path: string;
+}
+declare class PackagedResourceError extends Error {
+    readonly missingResources: ReadonlyArray<MissingPackagedResource>;
+    constructor(missingResources: ReadonlyArray<MissingPackagedResource>);
+}
+/**
+ * main 入口发布在 dist/main，Overlay 页面与内部 Preload 发布在 dist/overlay。
+ * 资源定位集中在这里，避免宿主构建工具或 Electron 版本参与路径拼接。
+ */
+declare function resolveOverlayResources(mainModuleDirectory?: string, resourceExists?: PackagedResourceExists): OverlayResources;
+/** 返回包内已打包的默认宿主 Preload，适用于不需要合并其他 Preload 的窗口。 */
+declare function resolveHostPreloadPath(mainModuleDirectory?: string, resourceExists?: PackagedResourceExists): string;
+declare function assertOverlayResources(resources: OverlayResources, resourceExists?: PackagedResourceExists): void;
+
+type OverlayBrowserWindow = Pick<BrowserWindow, 'destroy' | 'focus' | 'isDestroyed' | 'loadFile' | 'moveTop' | 'on' | 'removeListener' | 'setAlwaysOnTop' | 'setBounds' | 'setIgnoreMouseEvents' | 'setOpacity' | 'setVisibleOnAllWorkspaces' | 'show' | 'showInactive'> & {
+    webContents: Pick<WebContents, 'id' | 'on' | 'removeListener' | 'send'>;
+};
+type OverlayBrowserWindowFactory = (options: BrowserWindowConstructorOptions) => OverlayBrowserWindow;
+interface OverlayWindowOptions {
+    display: CaptureDisplay;
+    resources?: OverlayResources;
+    createWindow?: OverlayBrowserWindowFactory;
+    platform?: NodeJS.Platform;
+    resourceExists?: PackagedResourceExists;
+}
+interface ScreenshotOverlayWindow {
+    readonly webContentsId: number;
+    load(): Promise<void>;
+    sendInitialize(payload: ScreenshotInitializePayload): void;
+    prime(): void;
+    reveal(): void;
+    showCopyFeedback?(durationMs: number, options: ScreenshotOptions): void;
+    destroy(): void;
+    onClosed(listener: () => void): () => void;
+    onRendererGone(listener: () => void): () => void;
+}
+/** 管理包内截图窗口，窗口始终使用隔离上下文且不向页面开放 Node.js。 */
+declare class OverlayWindow implements ScreenshotOverlayWindow {
+    #private;
+    constructor(options: OverlayWindowOptions);
+    get webContentsId(): number;
+    load(): Promise<void>;
+    sendInitialize(payload: ScreenshotInitializePayload): void;
+    /** 先以全透明状态进入桌面合成器，隐藏 Windows/macOS 的窗口出场和大图首帧栅格化。 */
+    prime(): void;
+    reveal(): void;
+    /** 复制完成后销毁全屏截图层，改用独立的小窗口显示鼠标穿透提示。 */
+    showCopyFeedback(durationMs: number, options: ScreenshotOptions): void;
+    destroy(): void;
+    onClosed(listener: () => void): () => void;
+    onRendererGone(listener: () => void): () => void;
+}
+
+interface ScreenshotResourceLimits {
+    maxCapturePixels: number;
+    maxCaptureDataUrlBytes: number;
+    maxOutputBytes: number;
+}
+type ScreenshotResourceLimitOptions = Partial<ScreenshotResourceLimits>;
+declare const DEFAULT_SCREENSHOT_RESOURCE_LIMITS: Readonly<ScreenshotResourceLimits>;
+declare const HARD_SCREENSHOT_RESOURCE_LIMITS: Readonly<ScreenshotResourceLimits>;
+declare function resolveScreenshotResourceLimits(options?: ScreenshotResourceLimitOptions): ScreenshotResourceLimits;
+
+type ScreenshotSessionState = 'idle' | 'capturing' | 'opening-overlay' | 'preparing-overlay' | 'editing' | 'exporting' | 'completed' | 'cancelled' | 'failed';
+type ScreenshotOverlayFactory = (display: CaptureDisplay) => ScreenshotOverlayWindow;
+interface ScreenshotSessionOptions {
+    jobId: string;
+    captureOptions: ScreenshotOptions;
+    captureAdapter: ScreenCaptureAdapter;
+    ipcMain: Pick<IpcMain, 'on' | 'removeListener'>;
+    createOverlay: ScreenshotOverlayFactory;
+    overlayReadyTimeoutMs?: number;
+    onSettled?: () => void;
+    registerOutputHandler?: (senderWebContentsId: number, jobId: string) => () => void;
+    resourceLimits?: ScreenshotResourceLimitOptions;
+    onDiagnostic?: ScreenshotDiagnosticListener;
+}
+/**
+ * 管理一次截图任务从屏幕采集到 Overlay 结算的完整生命周期。
+ * 所有 IPC 都同时校验发送窗口、协议版本和 jobId，并且只允许结算一次。
+ */
+declare class ScreenshotSession {
+    #private;
+    constructor(options: ScreenshotSessionOptions);
+    get state(): ScreenshotSessionState;
+    /** 允许主进程在宿主窗口销毁或业务主动终止时结束任意活动阶段。 */
+    cancel(): boolean;
+    run(): Promise<ScreenshotResult>;
+}
+
+interface ScreenshotJobContext {
+    senderWebContentsId?: number;
+}
+interface ScreenshotExecution {
+    result: Promise<ScreenshotResult>;
+    cancel(): boolean;
+}
+type ScreenshotBusyPolicy = 'reject' | 'queue';
+type ScreenshotRunner = (jobId: string, options: ScreenshotOptions, context: ScreenshotJobContext) => Promise<ScreenshotResult> | ScreenshotExecution;
+type ScreenshotManagerIpcMain = Pick<IpcMain, 'handle' | 'on' | 'removeListener'>;
+interface ScreenshotManagerOptions {
+    /** 完全接管会话执行；设置后其余高层注入项不会参与默认 runner。 */
+    runner?: ScreenshotRunner;
+    ipcMain?: ScreenshotManagerIpcMain;
+    captureAdapter?: ScreenCaptureAdapter;
+    outputAdapter?: ScreenshotOutputExecutor;
+    createOverlay?: ScreenshotOverlayFactory;
+    overlayOptions?: Omit<OverlayWindowOptions, 'display'>;
+    overlayReadyTimeoutMs?: number;
+    resourceLimits?: ScreenshotResourceLimitOptions;
+    /** reject 保持即时失败；queue 仅为其他宿主窗口按 FIFO 排队。 */
+    busyPolicy?: ScreenshotBusyPolicy;
+    maxQueuedCaptures?: number;
+    onDiagnostic?: ScreenshotDiagnosticListener;
+}
+/**
+ * 统一管理截图会话，确保同一时刻只存在一个覆盖层任务。
+ * 窗口创建、屏幕采集与导出由 runner 注入，避免核心调度逻辑绑定 Electron 版本细节。
+ */
+declare class ScreenshotManager {
+    #private;
+    constructor(options?: ScreenshotManagerOptions);
+    get activeJobId(): string | undefined;
+    get queuedCaptureCount(): number;
+    /** 不传 sender ID 时供主进程直接取消；传入时只允许取消该页面创建的任务。 */
+    cancel(senderWebContentsId?: number): boolean;
+    capture(options?: ScreenshotOptions, context?: ScreenshotJobContext): Promise<ScreenshotResult>;
+}
+
+interface ElectronDisplayLike {
+    id: number;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    scaleFactor: number;
+}
+interface ScreenApi {
+    getAllDisplays(): ElectronDisplayLike[];
+    getCursorScreenPoint(): {
+        x: number;
+        y: number;
+    };
+    getDisplayNearestPoint(point: {
+        x: number;
+        y: number;
+    }): ElectronDisplayLike;
+    getPrimaryDisplay(): ElectronDisplayLike;
+}
+interface DesktopCaptureSource {
+    display_id: string;
+    thumbnail: {
+        getSize(): {
+            width: number;
+            height: number;
+        };
+        isEmpty(): boolean;
+        toDataURL(): string;
+    };
+}
+interface DesktopCapturerApi {
+    getSources(options: {
+        types: Array<'screen'>;
+        thumbnailSize: {
+            width: number;
+            height: number;
+        };
+        fetchWindowIcons: boolean;
+    }): Promise<DesktopCaptureSource[]>;
+}
+type ScreenPermissionStatus = 'not-determined' | 'granted' | 'denied' | 'restricted' | 'unknown';
+interface ElectronCaptureAdapterOptions {
+    desktopCapturer?: DesktopCapturerApi;
+    screen?: ScreenApi;
+    platform?: NodeJS.Platform;
+    getScreenPermissionStatus?: () => ScreenPermissionStatus;
+    resourceLimits?: ScreenshotResourceLimitOptions;
+}
+/**
+ * Electron 默认屏幕采集实现。适配器只依赖长期稳定的 Electron API，
+ * 采集结果转换为普通数据结构后再交给 Overlay，避免 UI 直接持有 NativeImage。
+ */
+declare class ElectronCaptureAdapter implements ScreenCaptureAdapter {
+    #private;
+    constructor(options?: ElectronCaptureAdapterOptions);
+    resolveTargetDisplay(options?: ScreenshotOptions): CaptureDisplay;
+    capture(options?: ScreenshotOptions, targetDisplay?: CaptureDisplay): Promise<CapturedFrame[]>;
+}
+
+declare class ScreenshotError extends Error {
+    readonly code: ScreenshotErrorCode;
+    constructor(code: ScreenshotErrorCode, message: string, options?: ErrorOptions);
+}
+
+type ValidateScreenshotIpcSender = (event: IpcMainInvokeEvent) => boolean;
+interface RegisterScreenshotIpcOptions {
+    ipcMain: IpcMain;
+    manager: ScreenshotManager;
+    channel?: string;
+    cancelChannel?: string;
+    validateSender?: ValidateScreenshotIpcSender;
+}
+interface SetupElectronSnaporaOptions extends Omit<RegisterScreenshotIpcOptions, 'manager'> {
+    managerOptions?: ScreenshotManagerOptions;
+}
+interface SetupElectronSnaporaResult {
+    manager: ScreenshotManager;
+    preloadPath: string;
+    unregister: () => void;
+}
+/**
+ * 创建默认截图管理器、注册宿主 IPC，并返回可直接交给 BrowserWindow 的 Preload 路径。
+ * 高级宿主仍可分别使用 ScreenshotManager 和 registerScreenshotIpc。
+ */
+declare function setupElectronSnapora(options: SetupElectronSnaporaOptions): SetupElectronSnaporaResult;
+/** 注册宿主渲染进程调用入口，并返回可用于应用退出或热重载的清理函数。 */
+declare function registerScreenshotIpc(options: RegisterScreenshotIpcOptions): () => void;
+
+declare const DEFAULT_HOST_CAPTURE_CHANNEL = "electron-snapora:host:capture";
+declare const DEFAULT_HOST_CANCEL_CHANNEL = "electron-snapora:host:cancel";
+declare const OVERLAY_CHANNELS: {
+    readonly ready: "electron-snapora:overlay:ready";
+    readonly prepared: "electron-snapora:overlay:prepared";
+    readonly initialize: "electron-snapora:overlay:initialize";
+    readonly feedback: "electron-snapora:overlay:feedback";
+    readonly feedbackReady: "electron-snapora:overlay:feedback-ready";
+    readonly confirm: "electron-snapora:overlay:confirm";
+    readonly cancel: "electron-snapora:overlay:cancel";
+    readonly error: "electron-snapora:overlay:error";
+    readonly output: "electron-snapora:overlay:output";
+};
+
+export { CaptureDisplay, CapturedFrame, DEFAULT_HOST_CANCEL_CHANNEL, DEFAULT_HOST_CAPTURE_CHANNEL, DEFAULT_SCREENSHOT_RESOURCE_LIMITS, ElectronCaptureAdapter, type ElectronCaptureAdapterOptions, ElectronOutputAdapter, type ElectronOutputAdapterOptions, HARD_SCREENSHOT_RESOURCE_LIMITS, type MissingPackagedResource, OVERLAY_CHANNELS, type OverlayResources, OverlayWindow, type OverlayWindowOptions, PackagedResourceError, type PackagedResourceExists, type RegisterScreenshotIpcOptions, ScreenCaptureAdapter, type ScreenshotBusyPolicy, type ScreenshotDiagnosticContextValue, type ScreenshotDiagnosticEvent, type ScreenshotDiagnosticListener, type ScreenshotDiagnosticPhase, type ScreenshotDiagnosticStage, ScreenshotError, ScreenshotErrorCode, type ScreenshotExecution, ScreenshotInitializePayload, type ScreenshotJobContext, ScreenshotManager, type ScreenshotManagerIpcMain, type ScreenshotManagerOptions, ScreenshotOptions, type ScreenshotOutputExecutor, ScreenshotOutputPayload, ScreenshotOutputResponse, type ScreenshotOverlayFactory, type ScreenshotOverlayWindow, type ScreenshotResourceLimitOptions, type ScreenshotResourceLimits, ScreenshotResult, type ScreenshotRunner, ScreenshotSession, type ScreenshotSessionOptions, type ScreenshotSessionState, type SetupElectronSnaporaOptions, type SetupElectronSnaporaResult, type ValidateScreenshotIpcSender, assertOverlayResources, registerScreenshotIpc, resolveHostPreloadPath, resolveOverlayResources, resolveScreenshotResourceLimits, setupElectronSnapora };