@dlient/api-types 1.0.0

package/dist/modules/screen.d.ts

@@ -0,0 +1,84 @@
+/**
+ * screen host-api — typed single source.
+ * Real source of truth: app/src/main/api/screen.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** A 2D point in DIP or screen coordinates (Electron Point serialized). */
+export interface ScreenPoint {
+    x: number;
+    y: number;
+}
+/** A 2D size in DIP (Electron Size serialized). */
+export interface ScreenSize {
+    width: number;
+    height: number;
+}
+/** An axis-aligned rectangle in DIP or screen coordinates (Electron Rectangle serialized). */
+export interface ScreenRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A display snapshot as returned by the screen module (Electron Display serialized as pure data). */
+export interface ScreenDisplay {
+    /** Unique display identifier. */
+    id: number;
+    /** User-friendly display label. */
+    label: string;
+    /** Display bounds in DIP. */
+    bounds: ScreenRect;
+    /** Work-area bounds (taskbar excluded) in DIP. */
+    workArea: ScreenRect;
+    /** Display size in DIP. */
+    size: ScreenSize;
+    /** Work-area size in DIP. */
+    workAreaSize: ScreenSize;
+    /** DIP scale factor (e.g. 1 for 100%, 2 for 200%). */
+    scaleFactor: number;
+    /** Display rotation in degrees (0 / 90 / 180 / 270). */
+    rotation: number;
+    /** Whether this is an internal (built-in) display. */
+    internal: boolean;
+    /** Touch support capability reported by the OS. */
+    touchSupport: 'available' | 'unavailable' | 'unknown';
+    /** Whether the display is monochrome. */
+    monochrome: boolean;
+    /** Accelerometer support capability reported by the OS. */
+    accelerometerSupport: 'available' | 'unavailable' | 'unknown';
+    /** Display color space (e.g. 'srgb'; Windows only). */
+    colorSpace: string;
+    /** Number of bits per pixel. */
+    colorDepth: number;
+    /** Number of bits per color component. */
+    depthPerComponent: number;
+    /** Display refresh rate in Hz. */
+    displayFrequency: number;
+}
+/** Flat signature map for the screen module. */
+export type ScreenModuleApi = {
+    /** Current absolute cursor position in DIP. */
+    'screen.getCursorScreenPoint'(): Promise<ScreenPoint>;
+    /** Info of the primary display. */
+    'screen.getPrimaryDisplay'(): Promise<ScreenDisplay>;
+    /** Info of all currently available displays. */
+    'screen.getAllDisplays'(): Promise<ScreenDisplay[]>;
+    /** The display nearest the given point. */
+    'screen.getDisplayNearestPoint'(point: ScreenPoint): Promise<ScreenDisplay>;
+    /** The display that most intersects the given rectangle. */
+    'screen.getDisplayMatching'(rect: ScreenRect): Promise<ScreenDisplay>;
+    /** Converts a physical screen point to a DIP point (Windows / Linux). */
+    'screen.screenToDipPoint'(point: ScreenPoint): Promise<ScreenPoint>;
+    /** Converts a DIP point to a physical screen point (Windows / Linux). */
+    'screen.dipToScreenPoint'(point: ScreenPoint): Promise<ScreenPoint>;
+    /**
+     * Converts a physical screen rect to a DIP rect (Windows).
+     * The window argument is not serializable over the host api — always pass null.
+     */
+    'screen.screenToDipRect'(window: null, rect: ScreenRect): Promise<ScreenRect>;
+    /**
+     * Converts a DIP rect to a physical screen rect (Windows).
+     * The window argument is not serializable over the host api — always pass null.
+     */
+    'screen.dipToScreenRect'(window: null, rect: ScreenRect): Promise<ScreenRect>;
+};

package/dist/modules/system.d.ts

@@ -0,0 +1,14 @@
+/**
+ * system host-api — typed single source.
+ * Real source of truth: app/src/main/api/system.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Idle states reported by system.getIdleState (Electron powerMonitor). */
+export type SystemIdleState = 'active' | 'idle' | 'locked' | 'unknown';
+/** Flat signature map for the system module. */
+export type SystemModuleApi = {
+    /** System idle state; the system is 'idle' after thresholdSeconds of inactivity. Defaults to 5 seconds. */
+    'system.getIdleState'(thresholdSeconds?: number): Promise<SystemIdleState>;
+    /** Enables/disables OS theme following; while enabled, OS theme changes are forwarded to the renderer. */
+    'system.listenNativeTheme'(enabled: boolean): Promise<void>;
+};

package/dist/modules/webview.d.ts

@@ -0,0 +1,68 @@
+/**
+ * webview host-api — typed single source.
+ * Real source of truth: app/src/main/api/webview.ts (handler reads these fields).
+ * All docs are English; keep in sync with the main-process api table.
+ */
+/** Rect bounds of a webview, in DIP. */
+export interface WebviewBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Whitelisted webContents events the host forwards to the owning plugin worker (as `onWebContentsEvent`). */
+export type WebviewEventName = 'did-finish-load' | 'did-fail-load' | 'did-start-loading' | 'did-stop-loading' | 'page-title-updated' | 'did-navigate' | 'did-navigate-in-page' | 'will-navigate';
+/** webContents methods the host allows webview.webContentsCall to invoke (method whitelist). */
+export type WebviewWebContentsMethod = 'loadURL' | 'reload' | 'stop' | 'goBack' | 'goForward' | 'getURL' | 'getTitle' | 'executeJavaScript' | 'setZoomLevel' | 'getZoomLevel';
+/** Options accepted by webview.create. */
+export interface WebviewCreateOptions {
+    /** URL to load once the view is created. */
+    src?: string;
+    /** Initial view bounds (0,0,0,0 when omitted — set bounds right after via webview.update). */
+    bounds?: WebviewBounds;
+    /** WebPreferences passthrough; only 'partition' and 'userAgent' are honored, security-sensitive options (sandbox/contextIsolation/nodeIntegration) are always forced by the host. */
+    webPreferences?: {
+        partition?: string;
+        userAgent?: string;
+    };
+    /** Whitelisted webContents events to subscribe; their payloads are forwarded to the owning plugin worker. */
+    events?: WebviewEventName[];
+}
+/** Result of webview.create. */
+export interface WebviewCreateResult {
+    viewId: string;
+}
+/** Options accepted by webview.update (re-bounds an existing view). */
+export interface WebviewUpdateOptions {
+    viewId: string;
+    bounds: WebviewBounds;
+}
+/** Options accepted by webview.setVisible (component-level visibility override; owner visibility alignment still applies). */
+export interface WebviewSetVisibleOptions {
+    viewId: string;
+    visible: boolean;
+}
+/** Options accepted by webview.webContentsCall (invokes a whitelisted webContents method with JSON-serializable args). */
+export interface WebviewWebContentsCallOptions {
+    viewId: string;
+    method: WebviewWebContentsMethod;
+    /** Arguments forwarded to the method; only JSON-serializable values survive the host round-trip. */
+    args?: unknown[];
+}
+/** Flat signature map for the webview module. */
+export type WebviewModuleApi = {
+    /** Creates an embedded webview owned by the currently active plugin (visibility follows the owner-alignment rule). */
+    'webview.create'(options: WebviewCreateOptions): Promise<WebviewCreateResult>;
+    /** Updates the bounds of an existing webview (no-op when the id is unknown). */
+    'webview.update'(options: WebviewUpdateOptions): Promise<void>;
+    /** Destroys a webview by id (no-op when the id is unknown). */
+    'webview.destroy'(viewId: string): Promise<void>;
+    /** Sets the component-level visibility of a webview. */
+    'webview.setVisible'(options: WebviewSetVisibleOptions): Promise<void>;
+    /** Calls a whitelisted webContents method (navigation / title / zoom / executeJavaScript); other methods are rejected. Returns the method's result. */
+    'webview.webContentsCall'(options: WebviewWebContentsCallOptions): Promise<unknown>;
+    /** Shows the caller plugin's webviews again; when views is given only those exact ids are restored (pair with webview.hideWebviewByPlugin's result). */
+    'webview.showWebviewByPlugin'(views?: string[]): Promise<void>;
+    /** Hides all of the caller plugin's webviews and returns the hidden view ids (pass them back to webview.showWebviewByPlugin for exact restore). */
+    'webview.hideWebviewByPlugin'(): Promise<string[]>;
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@dlient/api-types",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vite": "^5.1.6"
+  }
+}