@dlient/api-types 1.0.0

package/README.md

@@ -0,0 +1,39 @@
+# @dlient/api-types — host-api 共享单源类型
+
+目的：把 host-api 的**方法签名 + 参数/返回类型 + 英文说明**收敛为单一来源，worker（`@dlient/plugin-sdk`）与 UI（`@dlient/api-bridge`）两端引用同一套类型，避免双份漂移。
+
+## 真源
+主进程 api 目录 `app/src/main/api/*.ts`（方法 key、handler 实际读取的参数字段、英文 description）。新增/修改 host-api 时先改 api 目录，再同步本包。
+
+## 文件布局
+- `src/index.ts`：汇总导出（主会话维护，勿动）。
+- `src/modules/<module>.ts`：每个 host-api 模块一个文件。
+
+## 每个模块文件导出约定（样板见 `src/modules/notification.ts`）
+1. 该模块的方法**输入 Options 接口**（字段逐一加英文注释；字段语义以主进程 handler 实际读取为准）。
+2. 返回值类型（从 handler 返回结构提取）。
+3. 扁平签名类型：key = 完整点路径（如 `'fs.read'`），值为方法函数类型。
+   命名：模块类型名 `<Cap>ModuleApi`，值形如：
+   ```ts
+   export type FsModuleApi = {
+     'fs.read'(options: FsReadOptions): Promise<FsReadResult>
+   }
+   ```
+4. 每个方法一条英文 JSDoc 注释（一句话，说明用途/注意点），放在签名成员上。
+
+## 通用约束
+- 全部注释用英文。
+- 参数用**具名 options 对象**（与 handler 一致），不出现 `any` 参数。
+- 方法若无参/基本类型，直接签名（如 `'app.getVersion'(): Promise<string>`）。
+- 不导入任何运行时依赖；文件内只含 type/interface 声明（type-only）。
+- 保留 `@dlient/plugin-sdk/src/host-api.ts` 顶部模块列表的既有已文档化字段（如 NotificationSendOptions）作参考。
+
+## 修改 host-api 的同步流程（重要）
+1. 改主进程 `app/src/main/api/*.ts`（真源：方法行为/description）。
+2. 同步本包 `src/modules/<module>.ts`：方法签名/options/返回类型/英文注释（改 method key 时同步改）。
+3. 两端类型**自动跟随**：`@dlient/plugin-sdk` host-api.ts 与 `@dlient/api-bridge` 均以 `HostApiMap['<path>']` 引用本包，无需再手写双份。
+4. 运行时 path 表保持：plugin-sdk `HOST_API_PATHS` / api-bridge `UI_HOST_API_PATHS` 增删 key 时与本包同步（防路径漂移）。
+5. 改完执行：`npm --prefix app/packages/api-types run build`，再 rebuild plugin-sdk / api-bridge / ui，并把 dist 同步到 app 与插件 node_modules（发布时按 registry 依赖传递，无需手工同步）。
+
+## 发布顺序
+`@dlient/api-types` 先发 → `@dlient/plugin-sdk`、`@dlient/api-bridge`、`@dlient/ui` 依序发新版本（它们已声明对 api-types 的依赖）。

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @dlient/api-types — host-api 共享单源类型（docs/README 见本目录）。
+ *
+ * worker（@dlient/plugin-sdk rpc.xx）与 UI（@dlient/api-bridge api.xx）两端引用同一套
+ * 方法签名 / options / 返回类型与英文说明，避免双份漂移。真源：app/src/main/api/*.ts。
+ * 本文件仅做汇总：新增 host-api 方法时在 modules/<module>.ts 增补，并确认模块已在此 re-export。
+ */
+import type { AppModuleApi } from './modules/app';
+import type { I18nModuleApi } from './modules/i18n';
+import type { OsModuleApi } from './modules/os';
+import type { SystemModuleApi } from './modules/system';
+import type { PowerSaveModuleApi } from './modules/powerSave';
+import type { ScreenModuleApi } from './modules/screen';
+import type { FsModuleApi } from './modules/fs';
+import type { DialogModuleApi } from './modules/dialog';
+import type { ClipboardModuleApi } from './modules/clipboard';
+import type { NetModuleApi } from './modules/net';
+import type { NotificationModuleApi } from './modules/notification';
+import type { ChildModuleApi } from './modules/child';
+import type { PermissionModuleApi } from './modules/permission';
+import type { PluginModuleApi } from './modules/plugin';
+import type { WebviewModuleApi } from './modules/webview';
+import type { LogModuleApi } from './modules/log';
+export type * from './modules/app';
+export type * from './modules/i18n';
+export type * from './modules/os';
+export type * from './modules/system';
+export type * from './modules/powerSave';
+export type * from './modules/screen';
+export type * from './modules/fs';
+export type * from './modules/dialog';
+export type * from './modules/clipboard';
+export type * from './modules/net';
+export type * from './modules/notification';
+export type * from './modules/child';
+export type * from './modules/permission';
+export type * from './modules/plugin';
+export type * from './modules/webview';
+/**
+ * 全部 host-api 方法的统一签名表（扁平，key = 点路径）。
+ * worker 端以它为 rpc 模块树的类型基础；UI 端引用其中开放子集。
+ */
+export type HostApiMap = AppModuleApi & I18nModuleApi & OsModuleApi & SystemModuleApi & PowerSaveModuleApi & ScreenModuleApi & FsModuleApi & DialogModuleApi & ClipboardModuleApi & NetModuleApi & NotificationModuleApi & ChildModuleApi & PermissionModuleApi & PluginModuleApi & WebviewModuleApi & LogModuleApi;

package/dist/index.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/modules/app.d.ts

@@ -0,0 +1,158 @@
+/**
+ * app host-api — typed single source.
+ * Real source of truth: app/src/main/api/app.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Whitelisted names accepted by app.getPath. 'userData' resolves to the plugin-isolated dir, 'plugins' to the host plugins dir. */
+export type AppPathName = 'userData' | 'plugins' | 'home' | 'temp' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos' | 'recent';
+/** Options accepted by app.notify (worker scope; a '__render' receiver is stripped with a security warning). */
+export interface AppNotifyOptions {
+    /** Event name delivered to matching listeners. Required. */
+    event: string;
+    /** Target receiver role/plugin ids; 'all' broadcasts to every listener. Defaults to []. */
+    receiver?: string[];
+    /** Arbitrary serializable payload attached to the event. */
+    data?: unknown;
+    /** Deduplication/sequence id. Defaults to `${event}-${Date.now()}`. */
+    event_id?: string;
+}
+/** Result of app.notify: constant success marker. */
+export interface AppNotifyResult {
+    ok: true;
+}
+/** Options accepted by app.shortcut.register. */
+export interface AppShortcutRegisterOptions {
+    /** Local shortcut id reported back to the plugin when the accelerator fires. Required. */
+    id: string;
+    /** Global accelerator in Electron Accelerator syntax. Required; registration throws when the key is busy. */
+    accelerator: string;
+    /** Reserved action hint carried by the registration. */
+    action?: string;
+}
+/** One native context-menu item template (only safe display fields are honored; click callbacks are injected by the host). */
+export interface AppMenuItemSpec {
+    /** Identifier returned when the item is clicked; optional for separators. */
+    id?: string;
+    /** Display label. */
+    label?: string;
+    /** Item kind. Defaults to 'normal'; 'separator' ignores all other fields. */
+    type?: 'normal' | 'separator' | 'checkbox';
+    /** Whether the item is enabled. Defaults to true. */
+    enabled?: boolean;
+    /** Initial checked state for 'checkbox' items. Defaults to false. */
+    checked?: boolean;
+}
+/** Options accepted by app.menu.popup. */
+export interface AppMenuPopupOptions {
+    /** Menu item templates. Must be a non-empty array. */
+    items: AppMenuItemSpec[];
+    /** Optional popup x position (screen DIP). */
+    x?: number;
+    /** Optional popup y position (screen DIP). */
+    y?: number;
+}
+/** Result of app.menu.popup: the clicked item id, or null when dismissed (blank area / ESC). */
+export type AppMenuPopupResult = string | null;
+/** Options accepted by app.createNativeHost (usually called internally by the SDK's createNativeHost helper). */
+export interface CreateNativeHostOptions {
+    /** Entry file name located inside the plugin dist dir; path traversal is rejected. Required. */
+    fileName: string;
+    /** Absolute path to the Node executable used to run the entry. Required. */
+    node: string;
+}
+/** Options accepted by app.createNativeClient (same shape as hosted child spawn options). */
+export interface CreateNativeClientOptions {
+    /** Command to spawn. Required (missing cmd fails the call). */
+    cmd: string;
+    /** Command-line arguments. Defaults to []. */
+    args?: string[];
+    /** Working directory of the child process. */
+    cwd?: string;
+    /** Extra environment variables (merged over a stripped base env). */
+    env?: Record<string, string>;
+    /** Detach the child process. A platform default is applied when omitted. */
+    detached?: boolean;
+    /** Human-readable purpose shown on the spawn authorization prompt. */
+    description?: string;
+}
+/** Cross-process reference to a host-managed child process (returned by createNativeHost / createNativeClient). */
+export interface NativeSpawnRef {
+    /** Host-side handle id (used by disposeNativeClient and the SDK child handles). */
+    handleId: string;
+    /** Process id (diagnostics/display). */
+    pid: number;
+}
+/** Kill/dispose outcome of app.disposeNativeClient (idempotent; already-exited handles report reason). */
+export interface NativeDisposeResult {
+    ok: boolean;
+    reason?: string;
+}
+/** Flat signature map for the app module. */
+export type AppModuleApi = {
+    /** Host app version. */
+    'app.getVersion'(): Promise<string>;
+    /** Resolves a whitelisted path; 'userData' returns the plugin-isolated data dir, 'plugins' the host plugins dir. */
+    'app.getPath'(name: AppPathName): Promise<string>;
+    /** Whether the host currently has a focused window. */
+    'app.isActive'(): Promise<boolean>;
+    /** Whether all host windows are hidden. */
+    'app.isHidden'(): Promise<boolean>;
+    /** Host app name. */
+    'app.getName'(): Promise<string>;
+    /** Host app locale. */
+    'app.getLocale'(): Promise<string>;
+    /** Host app locale country code. */
+    'app.getLocaleCountryCode'(): Promise<string>;
+    /** Host system locale. */
+    'app.getSystemLocale'(): Promise<string>;
+    /** Host preferred system languages (most to least preferred). */
+    'app.getPreferredSystemLanguages'(): Promise<string[]>;
+    /** Broadcasts an event to renderer receivers; a '__render' receiver is stripped and warned. Worker scope. */
+    'app.notify'(options: AppNotifyOptions): Promise<AppNotifyResult>;
+    /** Registers or removes the OS auto-launch entry for the host. Worker scope; dangerous. */
+    'app.setAutoLaunch'(enabled: boolean): Promise<void>;
+    /** Forwards a global setting change ('theme' | 'language') to all host windows. Worker scope. */
+    'app.event'(channel: 'theme' | 'language', value: string): Promise<void>;
+    /** Starts a host-managed native Node process running an entry inside the plugin dist. Worker scope; dangerous. */
+    'app.createNativeHost'(options: CreateNativeHostOptions): Promise<NativeSpawnRef>;
+    /** Spawns a host-managed child process and returns its cross-process handle. Worker scope; dangerous. */
+    'app.createNativeClient'(options: CreateNativeClientOptions): Promise<NativeSpawnRef>;
+    /** Kills and disposes a hosted child by handle id (idempotent). Worker scope; dangerous. */
+    'app.disposeNativeClient'(handleId: string): Promise<NativeDisposeResult>;
+    /** Closes the main window (frameless title-bar control). Worker scope. */
+    'app.window.close'(): Promise<void>;
+    /** Focuses the main window. Worker scope. */
+    'app.window.focus'(): Promise<void>;
+    /** Blurs the main window. Worker scope. */
+    'app.window.blur'(): Promise<void>;
+    /** Shows the main window. Worker scope. */
+    'app.window.show'(): Promise<void>;
+    /** Hides the main window. Worker scope. */
+    'app.window.hide'(): Promise<void>;
+    /** Maximizes the main window. Worker scope. */
+    'app.window.maximize'(): Promise<void>;
+    /** Restores the main window from maximized. Worker scope. */
+    'app.window.unmaximize'(): Promise<void>;
+    /** Minimizes the main window. Worker scope. */
+    'app.window.minimize'(): Promise<void>;
+    /** Restores the main window from minimized. Worker scope. */
+    'app.window.restore'(): Promise<void>;
+    /** Whether the main window is maximized. Worker scope. */
+    'app.window.isMaximized'(): Promise<boolean>;
+    /** Sets the main window full screen. Worker scope. */
+    'app.window.setFullScreen'(flag: boolean): Promise<void>;
+    /** Reads a JSON data file from the plugin-isolated data dir; resolves null when missing or invalid. */
+    'app.data.read'(file: string): Promise<unknown>;
+    /** Atomically writes a JSON data file under the plugin-isolated data dir (file-locked). */
+    'app.data.write'(file: string, json: unknown): Promise<void>;
+    /** Encrypts a string with a plugin-scoped key (AES-256-GCM). */
+    'app.crypt.encrypt'(plain: string): Promise<string>;
+    /** Decrypts a plugin-scoped ciphertext (base64 input). */
+    'app.crypt.decrypt'(value: string): Promise<string>;
+    /** Registers a global shortcut bound to a plugin action id; a busy accelerator throws INVALID. Worker scope; dangerous. */
+    'app.shortcut.register'(options: AppShortcutRegisterOptions): Promise<void>;
+    /** Unregisters a global shortcut by its accelerator. Worker scope; dangerous. */
+    'app.shortcut.unregister'(accelerator: string): Promise<void>;
+    /** Pops up a native context menu at the cursor (or given x/y); resolves with the clicked item id or null. Worker scope. */
+    'app.menu.popup'(options: AppMenuPopupOptions): Promise<AppMenuPopupResult>;
+};

package/dist/modules/child.d.ts

@@ -0,0 +1,89 @@
+/**
+ * child host-api — typed single source.
+ * Real source of truth: app/src/main/api/child.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Options accepted by child.execFile (one-shot capture of a single command; shares the spawn option shape). */
+export interface ChildExecFileOptions extends SpawnHostedOptions {
+    /** Kill the command if it does not finish within this many milliseconds. */
+    timeout?: number;
+}
+/** Streamed child-process event callbacks delivered by the host over the child-event channel. */
+export interface ChildEventHandlers {
+    /** Streamed stdout chunk (one callback at a time). */
+    onStdout?: (data: string) => void;
+    /** Streamed stderr chunk (one callback at a time). */
+    onStderr?: (data: string) => void;
+    /** Exit notification: natural exit or killed. */
+    onExit?: (info: {
+        code: number | null;
+        signal?: string;
+        reason: 'exited' | 'killed';
+    }) => void;
+    /** Spawn failure (e.g. command not found). */
+    onError?: (err: Error) => void;
+}
+/**
+ * Handle returned by child.spawn (SDK shape — identical on the worker `rpc.child.spawn`
+ * surface). The host stores the underlying process as an opaque handle ref; the SDK performs
+ * the child-subscribe handshake so stdout/stderr/exit stream back to these callbacks, and
+ * kill/stdin go through the child-control message channel.
+ */
+export interface ChildHandle {
+    /** Host-side handle id. */
+    handleId: string;
+    /** Read-only process id (diagnostics / display). */
+    pid: number;
+    /** Idempotent: kills the process tree and unregisters; no-op once exited. */
+    kill(): Promise<void>;
+    /** Streamed stdout (child-event push). One callback at a time. */
+    onStdout(cb: (data: string) => void): void;
+    /** Streamed stderr (child-event push). One callback at a time. */
+    onStderr(cb: (data: string) => void): void;
+    /** Exit event (child-event push; natural exit or killed). */
+    onExit(cb: (info: {
+        code: number | null;
+        signal?: string;
+        reason: 'exited' | 'killed';
+    }) => void): void;
+    /** Spawn failure event (child-event push; e.g. command not found). */
+    onError(cb: (err: Error) => void): void;
+    /** Writes stdin (child-control write; used by the native-host RPC bridge). */
+    write(chunk: string): Promise<void>;
+    /** Ends stdin (child-control end; graceful close signal). */
+    end(): Promise<void>;
+}
+/** Options accepted by child.spawn as exposed by the SDK (same shape as ChildSpawnOptions). */
+export interface SpawnHostedOptions {
+    /** Command to run: absolute path, or executable name resolved through a stripped PATH. Required. */
+    cmd: string;
+    /** Command-line arguments. Defaults to []. */
+    args?: string[];
+    /** Working directory of the child process. */
+    cwd?: string;
+    /** Extra environment variables merged over the stripped base env (PATH/HOME). */
+    env?: Record<string, string>;
+    /** Whether to spawn detached. Defaults to true except on Windows. */
+    detached?: boolean;
+    /** Human-readable purpose shown in the spawn-confirmation dialog when the command is not pre-authorized. */
+    description?: string;
+}
+/** Result of child.execFile: captured stdout/stderr and the numeric exit code. */
+export interface ChildExecFileResult {
+    stdout: string;
+    stderr: string;
+    /** 0 on success; the error code on failure; -1 when no numeric code was reported. */
+    code: number;
+}
+/** Flat signature map for the child module. */
+export type ChildModuleApi = {
+    /**
+     * Spawns a subprocess through the host (command whitelist + spawn-confirm authorization)
+     * and returns a ChildHandle — kill/stdin and streamed stdout/stderr/exit/error events are
+     * delivered over message channels via the SDK subscription handshake.
+     * (Internally the host keeps an opaque ref of shape { handleId, pid }.)
+     */
+    'child.spawn'(options: SpawnHostedOptions): Promise<ChildHandle>;
+    /** Runs a command once and captures its output (probe-style usage, e.g. `node --version`). Authorization is the same as child.spawn. */
+    'child.execFile'(options: ChildExecFileOptions): Promise<ChildExecFileResult>;
+};

package/dist/modules/clipboard.d.ts

@@ -0,0 +1,95 @@
+/**
+ * clipboard host-api — typed single source.
+ * Real source of truth: app/src/main/api/clipboard.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ * Reading methods need the 'clipboard.read' permission, writing/clearing 'clipboard.write'.
+ */
+/** Clipboard type: 'clipboard' (default) or Linux-only 'selection'. */
+export type ClipboardType = 'selection' | 'clipboard';
+/** Bookmark data read from / written to the clipboard (macOS / Windows). */
+export interface ClipboardBookmark {
+    /** Bookmark title. */
+    title: string;
+    /** Bookmark URL. */
+    url: string;
+}
+/** Image source accepted by clipboard.writeImage (one of dataUrl/path/buffer). */
+export interface ClipboardImageInput {
+    /** Image content as a data URL. */
+    dataUrl?: string;
+    /** Path to an image file on disk. */
+    path?: string;
+    /** Raw encoded image bytes (PNG/JPEG; size hint used when the format needs it). */
+    buffer?: ArrayBuffer;
+    /** Width hint for the raw buffer (used only with buffer). */
+    width?: number;
+    /** Height hint for the raw buffer (used only with buffer). */
+    height?: number;
+}
+/** Result of clipboard.readImage: an empty image yields an empty dataUrl. */
+export interface ClipboardReadImageResult {
+    /** dataUrl of the image ('' when the clipboard holds no image). */
+    dataUrl: string;
+    /** Image size in DIP. */
+    size: {
+        width: number;
+        height: number;
+    };
+}
+/** Composite payload accepted by clipboard.write. */
+export interface ClipboardWriteData {
+    /** Plain text content. */
+    text?: string;
+    /** HTML content. */
+    html?: string;
+    /** Image content (dataUrl or file path). */
+    image?: {
+        dataUrl?: string;
+        path?: string;
+    };
+    /** RTF content. */
+    rtf?: string;
+    /** Bookmark content (macOS / Windows). */
+    bookmark?: ClipboardBookmark;
+}
+/** Flat signature map for the clipboard module. */
+export type ClipboardModuleApi = {
+    /** Reads plain text from the clipboard. */
+    'clipboard.readText'(): Promise<string>;
+    /** Reads HTML content from the clipboard. */
+    'clipboard.readHTML'(type?: ClipboardType): Promise<string>;
+    /** Reads RTF content from the clipboard. */
+    'clipboard.readRTF'(type?: ClipboardType): Promise<string>;
+    /** Reads a bookmark ({ title, url }) from the clipboard (macOS / Windows). */
+    'clipboard.readBookmark'(): Promise<ClipboardBookmark>;
+    /** Reads the find text (macOS find pasteboard). */
+    'clipboard.readFindText'(): Promise<string>;
+    /** Reads the clipboard image as { dataUrl, size } (dataUrl is '' when empty). */
+    'clipboard.readImage'(type?: ClipboardType): Promise<ClipboardReadImageResult>;
+    /** Reads raw bytes stored under a format (experimental; delivered as a typed array). */
+    'clipboard.readBuffer'(format: string): Promise<Uint8Array>;
+    /** Reads clipboard content by format (experimental). */
+    'clipboard.read'(format: string): Promise<string>;
+    /** Lists the formats currently available on the clipboard. */
+    'clipboard.availableFormats'(type?: ClipboardType): Promise<string[]>;
+    /** Checks whether the clipboard holds the given format (experimental). */
+    'clipboard.has'(format: string, type?: ClipboardType): Promise<boolean>;
+    /** Writes plain text to the clipboard. */
+    'clipboard.writeText'(text: string): Promise<void>;
+    /** Writes HTML content to the clipboard. */
+    'clipboard.writeHTML'(markup: string, type?: ClipboardType): Promise<void>;
+    /** Writes RTF content to the clipboard. */
+    'clipboard.writeRTF'(text: string, type?: ClipboardType): Promise<void>;
+    /** Writes a bookmark to the clipboard (macOS / Windows). */
+    'clipboard.writeBookmark'(title: string, url: string, type?: ClipboardType): Promise<void>;
+    /** Writes the find text (macOS find pasteboard). */
+    'clipboard.writeFindText'(text: string): Promise<void>;
+    /** Writes an image (dataUrl/path/buffer) to the clipboard. */
+    'clipboard.writeImage'(image: ClipboardImageInput, type?: ClipboardType): Promise<void>;
+    /** Writes raw bytes under a format (experimental). */
+    'clipboard.writeBuffer'(format: string, buffer: ArrayBuffer, type?: ClipboardType): Promise<void>;
+    /** Writes several representations at once ({ text, html, image, rtf, bookmark }). */
+    'clipboard.write'(data: ClipboardWriteData, type?: ClipboardType): Promise<void>;
+    /** Clears the clipboard content. */
+    'clipboard.clear'(type?: ClipboardType): Promise<void>;
+};

package/dist/modules/dialog.d.ts

@@ -0,0 +1,114 @@
+/**
+ * dialog host-api — typed single source.
+ * Real source of truth: app/src/main/api/dialog.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ * All methods are async (the *Sync Electron variants are intentionally not exposed);
+ * the window argument is not serializable and is omitted — only options are passed.
+ */
+/** Permission tokens accepted by fs.showOpenDialog to auto-grant file access for selected paths. */
+export type DialogFsPermission = 'fs.read' | 'fs.write';
+/** Options accepted by dialog.showMessageBox (serializable subset of Electron MessageBoxOptions). */
+export interface DialogShowMessageBoxOptions {
+    /** Dialog title. */
+    title?: string;
+    /** Message box type controlling the icon and default sound. */
+    type?: 'none' | 'info' | 'error' | 'question' | 'warning';
+    /** Main message text. Required. */
+    message: string;
+    /** Extra detail text shown under the message. */
+    detail?: string;
+    /** Labels of the buttons, in order. Defaults to a single "OK" button. */
+    buttons?: string[];
+    /** Index of the button activated when Enter is pressed. Defaults to 0. */
+    defaultId?: number;
+    /** Index of the button activated when Esc is pressed. */
+    cancelId?: number;
+    /** Label of the confirmation checkbox. */
+    checkboxLabel?: string;
+    /** Initial checked state of the confirmation checkbox. Defaults to false. */
+    checkboxChecked?: boolean;
+    /** Whether to apply the Windows button ordering heuristic. Defaults to false. */
+    noLink?: boolean;
+}
+/** Result of a successful dialog.showMessageBox call. */
+export interface DialogShowMessageBoxResult {
+    /** Index of the clicked button (matches options.buttons order). */
+    response: number;
+    /** Whether the confirmation checkbox was checked (false when no checkboxLabel is set). */
+    checkboxChecked: boolean;
+}
+/** Options accepted by dialog.showOpenDialog (serializable subset of Electron OpenDialogOptions). */
+export interface DialogShowOpenOptions {
+    /** Dialog title. */
+    title?: string;
+    /** Initial path shown by the dialog. */
+    defaultPath?: string;
+    /** Custom label for the confirm button. */
+    buttonLabel?: string;
+    /** File-type filters shown in the dialog. */
+    filters?: {
+        name: string;
+        extensions: string[];
+    }[];
+    /** Dialog behaviour flags. */
+    properties?: ('openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles' | 'createDirectory' | 'promptToCreate' | 'noResolveAliases' | 'treatPackageAsDirectory' | 'dontAddToRecent')[];
+    /** Informational text shown above the file list. */
+    message?: string;
+}
+/** File access granted for the paths picked in dialog.showOpenDialog. */
+export interface DialogFsGrant {
+    /** Paths granted for fs.read (mirrors permissions containing 'fs.read'). */
+    read: string[];
+    /** Paths granted for fs.write (mirrors permissions containing 'fs.write'). */
+    write: string[];
+}
+/** Result of a successful dialog.showOpenDialog call (cancel/denial throw instead). */
+export interface DialogShowOpenResult {
+    /** Selected paths, realpath-resolved so they match later fs.* whitelist checks. */
+    filePaths: string[];
+    /** Granted file access per permission requested (empty arrays for pure-select calls). */
+    granted: DialogFsGrant;
+}
+/** Options accepted by dialog.showSaveDialog (serializable subset of Electron SaveDialogOptions). */
+export interface DialogShowSaveOptions {
+    /** Dialog title. */
+    title?: string;
+    /** Initial path shown by the dialog. */
+    defaultPath?: string;
+    /** Custom label for the confirm button. */
+    buttonLabel?: string;
+    /** File-type filters shown in the dialog. */
+    filters?: {
+        name: string;
+        extensions: string[];
+    }[];
+    /** Custom label for the filename text field. */
+    nameFieldLabel?: string;
+    /** Dialog behaviour flags. */
+    properties?: ('showHiddenFiles' | 'createDirectory' | 'treatPackageAsDirectory' | 'dontAddToRecent' | 'showOverwriteConfirmation')[];
+    /** Informational text shown above the file list. */
+    message?: string;
+}
+/** Result of a successful dialog.showSaveDialog call (cancel throws DIALOG_CANCELED instead). */
+export interface DialogShowSaveResult {
+    /** The chosen path, realpath-resolved; a temp write grant is registered for it. */
+    filePath: string;
+}
+/** Flat signature map for the dialog module. */
+export type DialogModuleApi = {
+    /** Shows a native message box and resolves with the clicked button index. */
+    'dialog.showMessageBox'(options: DialogShowMessageBoxOptions): Promise<DialogShowMessageBoxResult>;
+    /**
+     * Shows an open/file-picker dialog. permissions requests fs access for the selected paths
+     * (authorization prompt + grant); when omitted (legacy options-only call) it is a pure
+     * selection without granting. Cancel or user denial throws DIALOG_CANCELED / USER_DENIED.
+     * The `description` argument (optional) is the authorization request copy shown in the
+     * fs-access permission dialog when the picked paths are not yet authorized.
+     */
+    'dialog.showOpenDialog'(permissions: DialogFsPermission[], options: DialogShowOpenOptions, description?: string): Promise<DialogShowOpenResult>;
+    /**
+     * Shows a save dialog. The chosen path is written a temp write grant (intent is explicit,
+     * so no confirmation prompt is shown). Cancel throws DIALOG_CANCELED.
+     */
+    'dialog.showSaveDialog'(options: DialogShowSaveOptions): Promise<DialogShowSaveResult>;
+};