@dlient/api-types 1.0.0

package/dist/modules/fs.d.ts

@@ -0,0 +1,140 @@
+/**
+ * fs host-api — typed single source.
+ * Real source of truth: app/src/main/api/fs.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ * Path whitelist enforcement (fs-grants) is applied uniformly by executeHostApi,
+ * not by these option fields.
+ */
+/** Options accepted by fs.read (2nd argument; default = read text content). */
+export interface FsReadOptions {
+    /** Read the file as raw bytes and return base64-encoded content. Defaults to false (UTF-8 text). */
+    base64?: boolean;
+}
+/** Binary payload accepted by fs.write / fs.withLock when writing bytes (base64-encoded data). */
+export interface FsWriteData {
+    /** File content as a base64 string (decoded before being written). */
+    base64: string;
+}
+/**
+ * Result of fs.stat: the serializable data fields of the Node fs.Stats object.
+ * IPC strips prototype methods (isFile/isDirectory) and only data fields survive;
+ * time fields are ms-epoch numbers (prefer mtimeMs over Date variants).
+ */
+export interface FsStatResult {
+    dev: number;
+    ino: number;
+    mode: number;
+    nlink: number;
+    uid: number;
+    gid: number;
+    rdev: number;
+    /** File size in bytes. */
+    size: number;
+    blksize: number;
+    blocks: number;
+    /** Access time, ms-epoch. */
+    atimeMs: number;
+    /** Modification time, ms-epoch. */
+    mtimeMs: number;
+    /** Status change time, ms-epoch. */
+    ctimeMs: number;
+    /** Creation time, ms-epoch. */
+    birthtimeMs: number;
+}
+/** Single entry returned by fs.listDir (best-effort size/mtime when stat fails are 0). */
+export interface FsListDirEntry {
+    /** Entry file/dir name (basename within the listed directory). */
+    name: string;
+    /** Whether the entry is a directory. */
+    isDirectory: boolean;
+    /** Whether the entry is a regular file. */
+    isFile: boolean;
+    /** File size in bytes (0 for directories or when stat failed). */
+    size: number;
+    /** Modification time in ms-epoch (0 when stat failed). */
+    mtimeMs: number;
+}
+/** fs.listDir return type: an array of directory entries. */
+export type FsListDirResult = FsListDirEntry[];
+/** Result of fs.lock: the lock id that must be passed back to fs.unlock / fs.withLock. */
+export interface FsLockResult {
+    /** Opaque lock id; pass it to fs.unlock to release this lock. */
+    lockId: string;
+}
+/** Options accepted by fs.lock / fs.withLock (3rd argument; per-path cross-process file lock). */
+export interface FsLockOptions {
+    /** Lock auto-expiry in ms (guards against a dead holder). Defaults to 30000. */
+    ttlMs?: number;
+    /** Whether to queue when the path is already locked; false throws busy immediately. Defaults to true. */
+    wait?: boolean;
+    /** Max queue wait in ms before a TIMEOUT error. Defaults to 15000. */
+    timeoutMs?: number;
+}
+/** Single file operation executed by fs.withLock while holding the path lock. */
+export type FsWithLockOperation = 
+/** Read the file (UTF-8 text). */
+{
+    method: 'read';
+}
+/** Read the file metadata (same shape as fs.stat). */
+ | {
+    method: 'stat';
+}
+/** Write the file (string content or base64 payload). */
+ | {
+    method: 'write';
+    data: string | FsWriteData;
+}
+/** Append text to the file (creates parent directories first). */
+ | {
+    method: 'append';
+    data: string;
+}
+/** Delete the file/dir. */
+ | {
+    method: 'delete';
+}
+/** Rotate log files (SDK logger pre-write check; host-side log rotation). */
+ | {
+    method: 'rotate';
+};
+/** fs.withLock return type: 'read'/'stat' return data, other operations resolve with undefined. */
+export type FsWithLockResult = string | FsStatResult | undefined;
+/** Flat signature map for the fs module. */
+export type FsModuleApi = {
+    /**
+     * Reads a file: UTF-8 text by default, or base64-encoded bytes when options.base64 is true.
+     * Requires an fs-grants read whitelist entry for the path.
+     */
+    'fs.read'(path: string, options?: FsReadOptions): Promise<string>;
+    /** Returns file/dir metadata as a flat data object (throws when the path does not exist). */
+    'fs.stat'(path: string): Promise<FsStatResult>;
+    /** Lists directory entries with a best-effort size/mtime per entry. */
+    'fs.listDir'(path: string): Promise<FsListDirResult>;
+    /**
+     * Watches a directory for changes and returns a watch id. Changes are delivered to the
+     * calling plugin worker as `<pluginId>.fs-watch-event` with args [watchId, filename].
+     */
+    'fs.watch'(path: string): Promise<string>;
+    /** Stops a directory watch started by fs.watch (idempotent; unknown ids are ignored). */
+    'fs.unwatch'(watchId: string): Promise<void>;
+    /** Creates a directory (recursive; no error when it already exists). */
+    'fs.mkdir'(path: string): Promise<void>;
+    /** Writes a file atomically (string content or base64 payload; parent dirs are created). */
+    'fs.write'(path: string, data: string | FsWriteData): Promise<void>;
+    /** Appends text to a file, creating parent directories first (log writes use this). */
+    'fs.append'(path: string, data: string): Promise<void>;
+    /** Deletes a file or directory (recursive, force). Requires a write whitelist entry. */
+    'fs.delete'(path: string): Promise<void>;
+    /**
+     * Copies a directory tree. dest must be inside the host userData directory;
+     * exclude filters out top-level entry names (e.g. node_modules, .git).
+     */
+    'fs.copyDir'(src: string, dest: string, exclude?: string[]): Promise<void>;
+    /** Acquires a per-path cross-process file lock (worker-only scope); returns { lockId }. */
+    'fs.lock'(path: string, options?: FsLockOptions): Promise<FsLockResult>;
+    /** Releases a file lock previously acquired with fs.lock (idempotent on unknown lockId). */
+    'fs.unlock'(path: string, lockId: string): Promise<void>;
+    /** Runs a single file operation while holding the path lock (worker-only scope). */
+    'fs.withLock'(path: string, operation: FsWithLockOperation, options?: FsLockOptions): Promise<FsWithLockResult>;
+};

package/dist/modules/i18n.d.ts

@@ -0,0 +1,12 @@
+/**
+ * i18n host-api — typed single source.
+ * Real source of truth: app/src/main/api/i18n.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Host UI language codes (worker query result of i18n.getLocale). */
+export type I18nLocale = 'zh-CN' | 'en-US';
+/** Flat signature map for the i18n module. */
+export type I18nModuleApi = {
+    /** Host current UI language ('zh-CN' / 'en-US'). */
+    'i18n.getLocale'(): Promise<I18nLocale>;
+};

package/dist/modules/log.d.ts

@@ -0,0 +1,14 @@
+/**
+ * log host-api — typed single source.
+ * Real source of truth: app/src/main/api/log.ts (handler reads these fields).
+ * 声明 manifest.permissions 的 log（前缀组，覆盖 log.*）即可写入自身插件日志，无需 fs 权限。
+ */
+export interface LogModuleApi {
+    /**
+     * 写入插件日志（source 由宿主按调用方身份推导：worker→'worker' / ui→'renderer'）。
+     * 落 plugin-data/<pluginId>/logs/main.log（含轮转与订阅推送）；未声明 log 权限则拒绝。
+     */
+    'log.write'(level?: 'debug' | 'info' | 'warn' | 'error', message?: string, data?: unknown): Promise<{
+        ok: boolean;
+    }>;
+}

package/dist/modules/net.d.ts

@@ -0,0 +1,58 @@
+/**
+ * net host-api — typed single source.
+ * Real source of truth: app/src/main/api/net.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ * net.fetch / net.request go through net-grants authorization (host policy blocks
+ * internal/loopback traffic and hard-denies cloud metadata endpoints).
+ */
+/** Request init accepted by net.fetch (serializable subset of Electron net.fetch init). */
+export interface NetFetchInit {
+    /** HTTP method (e.g. 'GET' / 'POST'). Defaults to 'GET'. */
+    method?: string;
+    /** Request headers as a flat name → value map. */
+    headers?: Record<string, string>;
+    /** Request body (only string bodies are forwarded). */
+    body?: string;
+}
+/** Options accepted by net.request (net.fetch with the url moved into the options object). */
+export interface NetRequestOptions {
+    /** Target URL. Required. */
+    url: string;
+    /** HTTP method (e.g. 'GET' / 'POST'). Defaults to 'GET'. */
+    method?: string;
+    /** Request headers as a flat name → value map. */
+    headers?: Record<string, string>;
+    /** Request body (only string bodies are forwarded). */
+    body?: string;
+}
+/** Result of a successful net.fetch / net.request call. */
+export interface NetFetchResult {
+    /** Whether the response status was 2xx (mirrors fetch Response.ok). */
+    ok: boolean;
+    /** HTTP status code. */
+    status: number;
+    /** HTTP status text. */
+    statusText: string;
+    /** Response headers as a flat name → value map (last value wins per header). */
+    headers: Record<string, string>;
+    /** Response body bytes encoded as base64 (empty string when the body is empty). */
+    body: string;
+}
+/** Flat signature map for the net module. */
+export type NetModuleApi = {
+    /** Whether the machine has an internet connection (read-only). */
+    'net.isOnline'(): Promise<boolean>;
+    /**
+     * Performs an HTTP request (net-grants authorization; see module header). Returns the
+     * full response with the body base64-encoded. User denial throws USER_DENIED.
+     * The `description` argument (optional) is the authorization request copy shown in the
+     * net-access permission dialog when this URL is not yet authorized (tell the user why).
+     */
+    'net.fetch'(url: string, init?: NetFetchInit, description?: string): Promise<NetFetchResult>;
+    /** Performs an HTTP request from an options object (same authorization as net.fetch; its `description` argument is likewise shown in the net-access permission dialog as the authorization reason). */
+    'net.request'(options: NetRequestOptions, description?: string): Promise<NetFetchResult>;
+    /** Allocates a free TCP port on 127.0.0.1 (replaces worker-side node:net binding). */
+    'net.getFreePort'(): Promise<number>;
+    /** Probes whether a local TCP port is reachable on 127.0.0.1 (800ms timeout). */
+    'net.probePort'(port: number): Promise<boolean>;
+};

package/dist/modules/notification.d.ts

@@ -0,0 +1,84 @@
+/**
+ * notification host-api — typed single source.
+ * Real source of truth: app/src/main/api/notification.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/**
+ * Options accepted by notification.send.
+ * Identity fields (group_id/group_title/subtitle/icon) are NOT part of the public surface:
+ * the host derives them from the sending plugin and injects them when the notification is sent,
+ * so a plugin cannot impersonate another plugin or override its branding. Only content fields
+ * below may be provided by the caller.
+ */
+export interface NotificationSendOptions {
+    /** Notification title. Required. */
+    title: string;
+    /** Optional body text. */
+    body?: string;
+    /** Whether the notification is silent (no sound). Defaults to false. */
+    silent?: boolean;
+    /** Whether to show an inline reply box. Defaults to false. */
+    hasReply?: boolean;
+    /** Placeholder text for the reply box (only meaningful when hasReply is true). */
+    replyPlaceholder?: string;
+    /** Action buttons. 'reply' actions are carried by hasReply and mapped to buttons by the host. */
+    actions?: {
+        type: 'button' | 'reply';
+        text: string;
+    }[];
+    /** Custom close-button text (macOS system notification / in-app strip). */
+    closeButtonText?: string;
+    /** 'default' auto-dismisses; 'never' keeps the notification until dismissed (Windows system engine / in-app). */
+    timeoutType?: 'default' | 'never';
+}
+/** Result of a successful notification.send call: the handle id used for events/removal. */
+export interface NotificationSendResult {
+    id: string;
+}
+/** Notification lifecycle event names delivered to the send handle via host push. */
+export type NotificationEventName = 'click' | 'close' | 'reply' | 'action' | 'failed' | 'show';
+/** Payload attached to notification events (action carries index, reply carries text, failed carries error). */
+export interface NotificationEventPayload {
+    index?: number;
+    reply?: string;
+    error?: string;
+}
+/**
+ * Handle returned by notification.send on the SDK/UI surface (identical shape for worker
+ * `rpc.notification.send` and UI `api.notification.send`). The SDK performs the subscribe
+ * handshake; lifecycle events stream back to the local `on(...)` callbacks. close() closes
+ * this notification (owner-checked).
+ */
+export interface NotificationHandle {
+    readonly id: string;
+    /** Subscribes to notification lifecycle events ('click' | 'close' | 'reply' | 'action' | 'failed' | 'show'). */
+    on(event: NotificationEventName, cb: (payload?: NotificationEventPayload) => void): NotificationHandle;
+    /** Closes this notification (equivalent to notification.remove(id)). */
+    close(): Promise<void>;
+}
+/** Flat signature map for the notification module. */
+export type NotificationModuleApi = {
+    /** Whether system notifications are supported on this platform. */
+    'notification.isSupported'(): Promise<boolean>;
+    /**
+     * Sends a notification and returns its handle id.
+     * Worker/UI SDKs wrap this into a handle supporting on('click'|'close'|'reply'|'action'|'failed'|'show').
+     * macOS foreground is routed to the in-app notification strip automatically.
+     */
+    'notification.send'(options: NotificationSendOptions): Promise<NotificationSendResult>;
+    /**
+     * Closes a notification by id. Owner-checked: only notifications sent by this plugin can be closed;
+     * other plugins' ids return PERMISSION_DENIED. Works for both system and in-app engines.
+     */
+    'notification.remove'(id: string): Promise<void>;
+    /** Closes all notifications sent by this plugin (both system and in-app engines). No argument needed. */
+    'notification.removeGroup'(): Promise<void>;
+    /** Subscribes to events of a notification id (owner-checked). Usually called automatically by the SDK handle. */
+    'notification.subscribe'(options: {
+        id: string;
+    }): Promise<void>;
+    /** Unsubscribes from events of a notification id (owner-checked). Usually called automatically by the SDK handle. */
+    'notification.unsubscribe'(options: {
+        id: string;
+    }): Promise<void>;
+};

package/dist/modules/os.d.ts

@@ -0,0 +1,12 @@
+/**
+ * os host-api — typed single source.
+ * Real source of truth: app/src/main/api/os.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Flat signature map for the os module. */
+export type OsModuleApi = {
+    /** Opens an external URL with the system default app (http/https/mailto/...). System scope; dangerous. */
+    'os.openExternal'(url: string): Promise<void>;
+    /** Reveals a file or directory in the system file manager. System scope. */
+    'os.showItemInFolder'(path: string): Promise<void>;
+};

package/dist/modules/permission.d.ts

@@ -0,0 +1,72 @@
+/**
+ * permission host-api — typed single source.
+ * Real source of truth: app/src/main/api/permission.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Resource kind a permission targets. */
+export type PermissionResourceType = 'fs' | 'net' | 'spawn';
+/** fs access mode requested in a permission.request fs item. */
+export type PermissionFsMode = 'read' | 'write';
+/** Lifetime of a granted permission. */
+export type PermissionGrantScope = 'persistent' | 'session';
+/** A single granted-resource record, as returned inside permission.list / permission.plugin.list. */
+export interface PermissionGrant {
+    /** Resource kind of the grant (fs = path, net = URL prefix, spawn = command). */
+    type: PermissionResourceType;
+    /** fs: absolute path; net: URL prefix; spawn: command. */
+    target: string;
+    /** Owner plugin instance key (e.g. 'dev-tools' or 'nodejs@dev'). */
+    pluginId: string;
+    /** fs-only access mode ('read' | 'write'); absent for net/spawn grants. */
+    mode?: PermissionFsMode;
+    /** Whether the grant is persisted across host restarts (persistent) or session-only. */
+    scope: PermissionGrantScope;
+    /** Epoch milliseconds when the grant was recorded. */
+    grantedAt: number;
+}
+/** A plugin's resource grants grouped by kind (market "Permissions" page / own-grants view). */
+export interface PermissionGrantList {
+    fs: PermissionGrant[];
+    net: PermissionGrant[];
+    spawn: PermissionGrant[];
+}
+/** One item of a permission.request batch: fs items carry path (+ optional mode), net items carry url, spawn items carry cmd. */
+export interface PermissionRequestItem {
+    /** Resource kind: 'fs' (also used when omitted and path is set) | 'net' | 'spawn'. net requires url; spawn requires cmd. */
+    type?: PermissionResourceType;
+    /** fs: absolute path or alias to request (see the fs module dir-alias list). */
+    path?: string;
+    /** net: URL to request (only honored when type is 'net'). */
+    url?: string;
+    /** spawn: command to request (only honored when type is 'spawn'). */
+    cmd?: string;
+    /** fs-only access mode(s): 'read' | 'write' | both; defaults to read + write when omitted. */
+    mode?: PermissionFsMode | PermissionFsMode[];
+}
+/** Options accepted by permission.revoke (admin entry to revoke another plugin's resource grant). */
+export interface PermissionRevokeOptions {
+    /** Target plugin instance key. */
+    pluginId?: string;
+    /** fs: path; net: URL prefix; spawn: command. */
+    target?: string;
+}
+/** Result of a successful permission.revoke call. */
+export interface PermissionRevokeResult {
+    ok: boolean;
+}
+/** Result of permission.request: granted/denied are requested targets (denied = rejected by the user in the confirm dialog). */
+export interface PermissionRequestResult {
+    granted: string[];
+    denied: string[];
+}
+/** Flat signature map for the permission module. */
+export type PermissionModuleApi = {
+    /** Lists the resource grants of an arbitrary plugin (admin; market "Permissions" page). */
+    'permission.plugin.list'(pluginId: string): Promise<PermissionGrantList>;
+    /** Revokes one resource grant of a plugin by type + target (type ∈ fs | net | spawn; merged fs.revokeAccess / net.revokeUrl / auth.revokeGrant). */
+    'permission.revoke'(type: PermissionResourceType, options: PermissionRevokeOptions): Promise<PermissionRevokeResult>;
+    /** Batch pre-authorization: lists fs/net/spawn resources once so the user can grant them in a single dialog (avoids per-call prompts at runtime). */
+    'permission.request'(resources: PermissionRequestItem[], description?: string): Promise<PermissionRequestResult>;
+    /** Lists the current plugin's own resource grants (no argument needed; identity comes from the caller). */
+    'permission.list'(): Promise<PermissionGrantList>;
+};

package/dist/modules/plugin.d.ts

@@ -0,0 +1,184 @@
+/**
+ * plugin host-api — typed single source.
+ * Real source of truth: app/src/main/api/plugin.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Install source of a plugin. */
+export type PluginSource = 'market' | 'local' | 'dev';
+/** Plugin kind (what the plugin runs / ships). */
+export type PluginType = 'full' | 'worker' | 'ui' | 'app';
+/** Call-channel gate of a host api (plugin.capabilities entries). */
+export type PluginCapabilityScope = 'all' | 'worker' | 'ui' | 'system';
+/** Install-risk label of a host api (plugin.capabilities entries). */
+export type PluginCapabilityLevel = 'default' | 'warn' | 'dangerous';
+/** One capability entry returned by plugin.capabilities (full api-table metadata). */
+export interface PluginCapability {
+    /** Full dotted api key (also the manifest.permissions declaration value). */
+    key: string;
+    /** Localized human-readable description. */
+    description: {
+        'zh-CN': string;
+        'en-US': string;
+    };
+    /** Who may invoke the api. */
+    scope: PluginCapabilityScope;
+    /** Risk label shown on the market permissions page. */
+    level: PluginCapabilityLevel;
+}
+/** An installed-plugin record, as returned by plugin.scanInstalled / plugin.system. */
+export interface PluginInstalledEntry {
+    id: string;
+    name: string;
+    version: string;
+    /** Whether the plugin worker is enabled. */
+    enabled: boolean;
+    source: PluginSource;
+    type: PluginType;
+    /** True for system plugins (cannot be uninstalled). */
+    system?: boolean;
+    /** Icon (relative path inside the plugin root). */
+    icon?: string;
+    /** Plugin organization ('@xxx'); absent = no organization. */
+    organization?: string;
+    /** Plugin root directory (absolute). */
+    path: string;
+    /** Epoch milliseconds when it was installed. */
+    installedAt: number;
+    /** Epoch milliseconds of the last launch. */
+    lastUsedAt?: number;
+}
+/** A registry entry payload accepted by plugin.registry.report (matches the host installed.json entry shape). */
+export interface PluginRegistryEntry {
+    id: string;
+    name: string;
+    version: string;
+    type: PluginType;
+    source: PluginSource;
+    system?: boolean;
+    icon?: string;
+    /** dist subdirectory relative to the plugin root (defaults to 'dist'). */
+    dist?: string;
+    /** Plugin root directory (absolute). */
+    path: string;
+    /** Epoch milliseconds when the entry was added. */
+    addedAt: number;
+}
+/** A dev-plugin entry reported through plugin.dev.sync (dev runtime → host; source is always 'dev'). */
+export interface PluginDevEntry {
+    id: string;
+    name: string;
+    /** Plugin root directory (absolute; contains package.json — dist is not copied). */
+    path: string;
+    /** dist subdirectory relative to the plugin root (manifest.dist ?? 'dist'). */
+    dist: string;
+    version?: string;
+    type?: PluginType;
+    system?: boolean;
+    icon?: string;
+    /** Epoch milliseconds when the entry was added to the dev list. */
+    addedAt: number;
+}
+/** Result of plugin.dev.getDirInfo: where the dev plugin actually lives. */
+export interface PluginDevDirInfo {
+    /** Plugin root directory (absolute). */
+    dir: string;
+    /** dist subdirectory relative to the plugin root. */
+    dist: string;
+    /** Packaging mode: 'asar' when dist is packed into plugin.asar; 'plain' otherwise. */
+    packaging: 'plain' | 'asar';
+}
+/** Result of plugin.dev.startWatcher / plugin.dev.stopWatcher. */
+export interface PluginDevWatcherResult {
+    ok: boolean;
+    /** startWatcher only: failure reason (localized object for UI display, plain string fallback). */
+    error?: string | {
+        enUS: string;
+        zhCN: string;
+    };
+}
+/** Options accepted by plugin.dev.readLogs (incremental tail read of the target plugin's main.log). */
+export interface PluginLogReadOptions {
+    /** Byte offset to continue reading from (use the previous result's offset). */
+    offset?: number;
+    /** Maximum bytes to read in one call (defaults to 512 KiB). */
+    maxBytes?: number;
+}
+/** Result of plugin.dev.readLogs. */
+export interface PluginLogReadResult {
+    /** Complete log lines read. */
+    lines: string[];
+    /** Next byte offset to continue from. */
+    offset: number;
+    /** True when reading restarted from the log tail (rotation or an oversized gap). */
+    reset: boolean;
+    /** True when output was cut at the read limit. */
+    truncated: boolean;
+}
+/** Result of plugin.logs.subscribe. */
+export interface PluginLogSubscribeResult {
+    /** Subscription id (pass to plugin.logs.unsubscribe). */
+    subId: string;
+}
+/** Result of plugin.installLocal. */
+export interface PluginInstallLocalResult {
+    ok: boolean;
+    /** Installed plugin id (from the manifest dlient.id). */
+    id: string;
+    /** Target install directory (absolute). */
+    path: string;
+}
+/** Flat signature map for the plugin module. */
+export type PluginModuleApi = {
+    /** Lists the full host api-table metadata (keys + scope/level/localized descriptions). System plugins only. */
+    'plugin.capabilities'(): Promise<PluginCapability[]>;
+    /** Reports the complete installed registry from the market worker; the host refreshes its cache from it. System plugins only. */
+    'plugin.registry.report'(entries: PluginRegistryEntry[]): Promise<{
+        ok: boolean;
+    }>;
+    /** Starts a plugin worker (already running → no-op). System plugins only. */
+    'plugin.start'(pluginId: string): Promise<void>;
+    /** Stops a plugin worker (also cleans up its owned WebContentsView). System plugins only. */
+    'plugin.stop'(pluginId: string): Promise<void>;
+    /** Lists the installed system plugins. */
+    'plugin.system'(): Promise<PluginInstalledEntry[]>;
+    /** Scans the installed plugins (registry + directory fallback) into a unified list. Worker-scope primitive for dev-tools/market. */
+    'plugin.scanInstalled'(): Promise<PluginInstalledEntry[]>;
+    /** Lists all running-instance runtime states (formal + dev records). Shape is host-internal; consumed by dev-tools. */
+    'plugin.runtimeList'(): Promise<unknown[]>;
+    /** Imports a local plugin (copy artifacts + patch manifest + register + report + start). Worker-scope primitive for dev-tools. */
+    'plugin.installLocal'(dir: string): Promise<PluginInstallLocalResult>;
+    /** Whether a plugin worker is currently running. */
+    'plugin.isRunning'(pluginId: string): Promise<boolean>;
+    /** Post-uninstall cleanup of a plugin (grants + change broadcast). System plugins only. */
+    'plugin.cleanupUninstall'(pluginId: string): Promise<void>;
+    /** Opens a directory picker for selecting a dev plugin dir; resolves null when cancelled. */
+    'plugin.dev.selectDirectory'(): Promise<string | null>;
+    /** Resolves the dev directory info (dir/dist/packaging) of a dev plugin id; null when unknown. */
+    'plugin.dev.getDirInfo'(pluginId: string): Promise<PluginDevDirInfo | null>;
+    /** Dev runtime reports its full dev-plugin list to the host (cache update; no fs grants implied). */
+    'plugin.dev.sync'(entries: PluginDevEntry[]): Promise<void>;
+    /** Starts the hot-reload watcher for a dev plugin (call after a build completes). */
+    'plugin.dev.startWatcher'(pluginId: string): Promise<PluginDevWatcherResult>;
+    /** Stops the hot-reload watcher of a dev plugin (during build/refresh). */
+    'plugin.dev.stopWatcher'(pluginId: string): Promise<PluginDevWatcherResult>;
+    /** Re-forks the dev-instance worker of a dev plugin (last step of the refresh flow). */
+    'plugin.dev.startDevWorker'(pluginId: string): Promise<void>;
+    /** Stops the dev-instance worker of a dev plugin (first step of the refresh flow). */
+    'plugin.dev.stopDevWorker'(pluginId: string): Promise<void>;
+    /** Whether the dev instance worker's direct port is ready (running may precede port-ready). */
+    'plugin.dev.isPortReady'(pluginId: string): Promise<boolean>;
+    /** Reads the buffered tail of a target plugin's log (incremental byte-offset reads). */
+    'plugin.dev.readLogs'(pluginId: string, options?: PluginLogReadOptions): Promise<PluginLogReadResult>;
+    /** Clears the target plugin's runtime log file (also resets the incremental half-line cache). */
+    'plugin.dev.clearLogs'(pluginId: string): Promise<void>;
+    /** Compatibility with legacy hosts: lists dev plugins (hosts without the dev runtime reject at runtime). */
+    'plugin.dev.list'(): Promise<unknown>;
+    /** Compatibility with legacy hosts: removes a dev plugin by id (hosts without the dev runtime reject at runtime). */
+    'plugin.dev.remove'(pluginId: string): Promise<unknown>;
+    /** Subscribes the caller to a target plugin's log lines (host pushes each line to the caller as `dev-tools.__onPluginLog`). */
+    'plugin.logs.subscribe'(pluginId: string): Promise<PluginLogSubscribeResult>;
+    /** Unsubscribes a log subscription (subId from plugin.logs.subscribe). */
+    'plugin.logs.unsubscribe'(pluginId: string, subId: string): Promise<boolean>;
+    /** Sets the active content-area plugin (was webview.setActivePlugin); null clears it. */
+    'plugin.setActive'(pluginId: string | null): Promise<void>;
+};

package/dist/modules/powerSave.d.ts

@@ -0,0 +1,16 @@
+/**
+ * powerSaveBlocker host-api — typed single source.
+ * Real source of truth: app/src/main/api/power-save.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Blocker types accepted by powerSaveBlocker.start. */
+export type PowerSaveBlockerType = 'prevent-app-suspension' | 'prevent-display-sleep';
+/** Flat signature map for the powerSaveBlocker module. */
+export type PowerSaveModuleApi = {
+    /** Starts blocking the system from entering low-power mode; resolves with the blocker id. Worker scope. */
+    'powerSaveBlocker.start'(type: PowerSaveBlockerType): Promise<number>;
+    /** Stops the blocker with the given id. Worker scope. */
+    'powerSaveBlocker.stop'(id: number): Promise<void>;
+    /** Whether the blocker with the given id is still active. Worker scope. */
+    'powerSaveBlocker.isStarted'(id: number): Promise<boolean>;
+};