@medeo-plugin/sdk 0.8.0 → 0.9.0

package/dist/generated.d.ts

@@ -7,7 +7,7 @@ export type Permission = "storage" | "creation_open" | {
     "file_full_access": Array<string>;
 } | {
     "network": Array<string>;
-} | "agent_api" | "clipboard_read" | "clipboard_write" | "screen_capture" | "camera" | "microphone" | "system_audio" | "applications" | "global_shortcuts" | "notifications" | "tray" | "app_windows" | "accessibility" | "input_method" | {
+} | "agent_api" | "clipboard_read" | "clipboard_write" | "screen_capture" | "camera" | "microphone" | "system_audio" | "applications" | "global_shortcuts" | "notifications" | "tray" | "app_windows" | "accessibility" | "window_management" | "input_method" | {
     "external_open": Array<string>;
 } | {
     "browser_view": Array<string>;
@@ -157,6 +157,28 @@ export type PackageSignature = {
     signature: string;
     index: string;
 };
+export type About = {
+    /**
+     * Display name of the author, at most 80 characters. Official packages show Medeo.
+     */
+    author?: string;
+    /**
+     * SPDX license expression, at most 64 characters.
+     */
+    license?: string;
+    /**
+     * Project website.
+     */
+    homepage?: string;
+    /**
+     * Source repository.
+     */
+    repository?: string;
+    /**
+     * Where users report problems.
+     */
+    bugs?: string;
+};
 export type PackageInfo = {
     manifest: Manifest;
     digest: string;
@@ -171,6 +193,11 @@ export type PackageInfo = {
      * shown at install and in the developer log, never a reason to refuse.
      */
     warnings?: Array<string>;
+    /**
+     * The package's signed `about.json` (author, license, links), when valid.
+     * Older Medeo ignore the file, so declaring it never blocks installation.
+     */
+    about?: About;
 };
 export type CapabilityDescriptor = {
     permission: string;

package/dist/index.d.ts

@@ -193,7 +193,13 @@ export declare const shortcuts: {
 /** `panel: true` (macOS): a frameless window floating over every app and Space that does not
  * activate Medeo — the app the user was in keeps focus — opened at the pointer and hidden (not
  * closed) when it loses focus; opening it again moves it to the pointer. `hide` keeps a window
- * and its page alive for the next `open`/`focus`. */
+ * and its page alive for the next `open`/`focus`.
+ * `overlay: true` (macOS, needs `window_management` too): a transparent, shadowless panel covering
+ * the whole display under the pointer (menu bar included), above full-screen apps — for previews
+ * and radial menus. It takes keyboard focus without activating Medeo, hides when it loses focus,
+ * and each `open` moves it to the pointer's display; `width`/`height` are ignored. The page's
+ * `window.screenX/screenY` is the display's top-left in the same global points as
+ * `windowManagement`. `panel` and `overlay` are exclusive. */
 export declare const appWindows: {
     open: (options: {
         id: string;
@@ -202,6 +208,7 @@ export declare const appWindows: {
         width: number;
         height: number;
         panel?: boolean;
+        overlay?: boolean;
     }) => Promise<unknown>;
     close: (id: string) => Promise<unknown>;
     focus: (id: string) => Promise<unknown>;
@@ -801,6 +808,61 @@ export declare const accessibility: {
     }>>;
     insertText: (focus: string, text: string) => Promise<NativeOperation<unknown>>;
 };
+/** A rectangle in global points: origin at the top-left of the main display, y grows downwards
+ * (displays left of or above the main one have negative coordinates). */
+export interface WindowFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The frontmost window of another app. `id` stays the same for the same window while it lives. */
+export interface ManagedWindow {
+    id: string;
+    title: string;
+    application: string;
+    bundle_id: string;
+    frame: WindowFrame;
+    resizable: boolean;
+    fullscreen: boolean;
+    minimized: boolean;
+    standard: boolean;
+}
+/** `visible_frame` excludes the menu bar and the Dock. `id` is the display number for this session,
+ * `uuid` survives restarts and reconnecting. The first entry is the main display. */
+export interface ManagedScreen {
+    id: string;
+    uuid: string;
+    name: string;
+    primary: boolean;
+    scale: number;
+    frame: WindowFrame;
+    visible_frame: WindowFrame;
+}
+/** Window management (macOS, permission `window_management`, OS Accessibility). All calls are
+ * operations: `operations.wait(await windowManagement.focused())`. `request` opens the system
+ * prompt and is window-only; the others work in the worker too. `focused` never returns a Medeo window:
+ * when Medeo is in front (a plugin's own page) it is the window of the app right behind it, and `null`
+ * when there is none or the frontmost app has no window; `set_frame` reports the frame the app
+ * actually accepted (apps may clamp sizes) and fails with `resource_missing` once the window is gone. */
+export declare const windowManagement: {
+    status: () => Promise<NativeOperation<{
+        authorization: "granted" | "denied";
+    }>>;
+    request: () => Promise<NativeOperation<{
+        authorization: "granted" | "denied";
+    }>>;
+    focused: () => Promise<NativeOperation<ManagedWindow | null>>;
+    setFrame: (id: string, frame: WindowFrame) => Promise<NativeOperation<{
+        frame: WindowFrame;
+        resized: boolean;
+    }>>;
+    screens: () => Promise<NativeOperation<ManagedScreen[]>>;
+    pointer: () => Promise<NativeOperation<{
+        x: number;
+        y: number;
+    }>>;
+};
 export declare const browserView: {
     open: (id: string, url: string, width?: number, height?: number) => Promise<unknown>;
     state: (id: string) => Promise<unknown>;

package/dist/index.js

@@ -88,7 +88,13 @@ export const shortcuts = { list: () => globalThis.medeoPlugin.invoke('shortcuts.
 /** `panel: true` (macOS): a frameless window floating over every app and Space that does not
  * activate Medeo — the app the user was in keeps focus — opened at the pointer and hidden (not
  * closed) when it loses focus; opening it again moves it to the pointer. `hide` keeps a window
- * and its page alive for the next `open`/`focus`. */
+ * and its page alive for the next `open`/`focus`.
+ * `overlay: true` (macOS, needs `window_management` too): a transparent, shadowless panel covering
+ * the whole display under the pointer (menu bar included), above full-screen apps — for previews
+ * and radial menus. It takes keyboard focus without activating Medeo, hides when it loses focus,
+ * and each `open` moves it to the pointer's display; `width`/`height` are ignored. The page's
+ * `window.screenX/screenY` is the display's top-left in the same global points as
+ * `windowManagement`. `panel` and `overlay` are exclusive. */
 export const appWindows = { open: (options) => globalThis.medeoPlugin.invoke('windows.open', options), close: (id) => globalThis.medeoPlugin.invoke('windows.close', { id }), focus: (id) => globalThis.medeoPlugin.invoke('windows.focus', { id }), hide: (id) => globalThis.medeoPlugin.invoke('windows.hide', { id }), list: () => globalThis.medeoPlugin.invoke('windows.list') };
 export const tray = { set: (title, items, options = {}) => globalThis.medeoPlugin.invoke('tray.set', { title, items, ...options }), remove: () => globalThis.medeoPlugin.invoke('tray.remove'), events: () => globalThis.medeoPlugin.invoke('tray.events') };
 export const external = { open: (url) => globalThis.medeoPlugin.invoke('external.open', { url }) };
@@ -414,6 +420,20 @@ function mediaProvider(kind) {
 }
 export const camera = mediaProvider('camera'), microphone = mediaProvider('microphone'), systemAudio = mediaProvider('system_audio');
 export const accessibility = { status: () => nativeCall('accessibility.status'), request: () => nativeCall('accessibility.request'), windows: () => nativeCall('accessibility.windows'), focus: (id) => nativeCall('accessibility.focus', { id }), selectedText: (id) => nativeCall('accessibility.selected_text', { id }), insertText: (focus, text) => nativeCall('accessibility.insert_text', { id: focus, text }) };
+/** Window management (macOS, permission `window_management`, OS Accessibility). All calls are
+ * operations: `operations.wait(await windowManagement.focused())`. `request` opens the system
+ * prompt and is window-only; the others work in the worker too. `focused` never returns a Medeo window:
+ * when Medeo is in front (a plugin's own page) it is the window of the app right behind it, and `null`
+ * when there is none or the frontmost app has no window; `set_frame` reports the frame the app
+ * actually accepted (apps may clamp sizes) and fails with `resource_missing` once the window is gone. */
+export const windowManagement = {
+    status: () => nativeCall('window_management.status'),
+    request: () => nativeCall('window_management.request'),
+    focused: () => nativeCall('window_management.focused'),
+    setFrame: (id, frame) => nativeCall('window_management.set_frame', { id, x: frame.x, y: frame.y, width: frame.width, height: frame.height }),
+    screens: () => nativeCall('window_management.screens'),
+    pointer: () => nativeCall('window_management.pointer'),
+};
 export const browserView = { open: (id, url, width = 1000, height = 720) => capabilities.invoke('browser.open', { id, url, width, height }), state: (id) => capabilities.invoke('browser.state', { id }), close: (id) => capabilities.invoke('browser.close', { id }) };
 export const printing = { print: (text) => capabilities.invoke('printing.print', { text }) };
 export const processes = { start: (executable, args = [], timeoutMs = 60000) => nativeCall('process.start', { executable, arguments: args, timeout_ms: timeoutMs }), state: (id) => nativeCall('process.state', { id }), write: (id, text) => nativeCall('process.write', { id, text }), stop: (id) => nativeCall('process.stop', { id }) };

package/dist/registry.d.ts

@@ -713,6 +713,48 @@ export declare const METHODS: {
         readonly confirm: false;
         readonly adapter: "host";
     };
+    readonly "window_management.status": {
+        readonly permission: "window_management";
+        readonly provider: "medeo.system-services";
+        readonly ui: false;
+        readonly confirm: false;
+        readonly adapter: "host";
+    };
+    readonly "window_management.request": {
+        readonly permission: "window_management";
+        readonly provider: "medeo.system-services";
+        readonly ui: true;
+        readonly confirm: false;
+        readonly adapter: "host";
+    };
+    readonly "window_management.focused": {
+        readonly permission: "window_management";
+        readonly provider: "medeo.system-services";
+        readonly ui: false;
+        readonly confirm: false;
+        readonly adapter: "host";
+    };
+    readonly "window_management.set_frame": {
+        readonly permission: "window_management";
+        readonly provider: "medeo.system-services";
+        readonly ui: false;
+        readonly confirm: false;
+        readonly adapter: "host";
+    };
+    readonly "window_management.screens": {
+        readonly permission: "window_management";
+        readonly provider: "medeo.system-services";
+        readonly ui: false;
+        readonly confirm: false;
+        readonly adapter: "host";
+    };
+    readonly "window_management.pointer": {
+        readonly permission: "window_management";
+        readonly provider: "medeo.system-services";
+        readonly ui: false;
+        readonly confirm: false;
+        readonly adapter: "host";
+    };
     readonly "input_method.status": {
         readonly permission: "input_method";
         readonly provider: "medeo.input-method";

package/dist/registry.js

@@ -102,6 +102,12 @@ export const METHODS = {
     "accessibility.focus": { permission: "accessibility", provider: "medeo.system-services", ui: true, confirm: false, adapter: "host" },
     "accessibility.selected_text": { permission: "accessibility", provider: "medeo.system-services", ui: true, confirm: false, adapter: "host" },
     "accessibility.insert_text": { permission: "accessibility", provider: "medeo.system-services", ui: true, confirm: false, adapter: "host" },
+    "window_management.status": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
+    "window_management.request": { permission: "window_management", provider: "medeo.system-services", ui: true, confirm: false, adapter: "host" },
+    "window_management.focused": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
+    "window_management.set_frame": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
+    "window_management.screens": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
+    "window_management.pointer": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
     "input_method.status": { permission: "input_method", provider: "medeo.input-method", ui: false, confirm: false, adapter: "host" },
     "input_method.configure": { permission: "input_method", provider: "medeo.input-method", ui: false, confirm: false, adapter: "host" },
     "input_method.enable": { permission: "input_method", provider: "medeo.input-method", ui: true, confirm: false, adapter: "host" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medeo-plugin/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "TypeScript SDK for Medeo desktop plugins: one import for the sandboxed worker, its windows and Node plugins.",
   "license": "MIT",
   "repository": {

package/src/generated.ts

@@ -1,6 +1,6 @@
 // Generated by platform-contract; do not edit.
 export type JsonValue = number | string | boolean | Array<JsonValue> | { [key in string]?: JsonValue } | null;
-export type Permission = "storage" | "creation_open" | { "file_access": Array<string> } | { "file_full_access": Array<string> } | { "network": Array<string> } | "agent_api" | "clipboard_read" | "clipboard_write" | "screen_capture" | "camera" | "microphone" | "system_audio" | "applications" | "global_shortcuts" | "notifications" | "tray" | "app_windows" | "accessibility" | "input_method" | { "external_open": Array<string> } | { "browser_view": Array<string> } | "system_info" | "secrets" | "background_tasks" | "power" | { "process_spawn": Array<string> } | "local_server" | "printing" | "contacts" | "calendar" | "location" | "device_access" | { "approvals": Array<string> } | "node";
+export type Permission = "storage" | "creation_open" | { "file_access": Array<string> } | { "file_full_access": Array<string> } | { "network": Array<string> } | "agent_api" | "clipboard_read" | "clipboard_write" | "screen_capture" | "camera" | "microphone" | "system_audio" | "applications" | "global_shortcuts" | "notifications" | "tray" | "app_windows" | "accessibility" | "window_management" | "input_method" | { "external_open": Array<string> } | { "browser_view": Array<string> } | "system_info" | "secrets" | "background_tasks" | "power" | { "process_spawn": Array<string> } | "local_server" | "printing" | "contacts" | "calendar" | "location" | "device_access" | { "approvals": Array<string> } | "node";
 export type PluginCommand = { id: string, title: string, };
 export type PluginLocalization = { default_locale: string, catalogs: { [key in string]?: string }, };
 export type Runtime = "sandbox" | "node";
@@ -76,6 +76,27 @@ export type PackageFile = { size: number, sha256: string, };
 export type PackageIndex = { manifest: Manifest, files: { [key in string]?: PackageFile }, };
 export type Asset = { mime: string, path: string, size: number, sha256: string, };
 export type PackageSignature = { format: number, public_key: string, signature: string, index: string, };
+export type About = { 
+/**
+ * Display name of the author, at most 80 characters. Official packages show Medeo.
+ */
+author?: string, 
+/**
+ * SPDX license expression, at most 64 characters.
+ */
+license?: string, 
+/**
+ * Project website.
+ */
+homepage?: string, 
+/**
+ * Source repository.
+ */
+repository?: string, 
+/**
+ * Where users report problems.
+ */
+bugs?: string, };
 export type PackageInfo = { manifest: Manifest, digest: string, publisher: string, 
 /**
  * Bytes of all signed files, i.e. the installed size. Records written
@@ -86,7 +107,12 @@ size: number,
  * What this build accepted but does not understand (`unknown_contribution:<key>`);
  * shown at install and in the developer log, never a reason to refuse.
  */
-warnings?: Array<string>, };
+warnings?: Array<string>, 
+/**
+ * The package's signed `about.json` (author, license, links), when valid.
+ * Older Medeo ignore the file, so declaring it never blocks installation.
+ */
+about?: About, };
 export type CapabilityDescriptor = { permission: string, group: string, version: number, scoped: boolean, methods: Array<string>, available_methods: Array<string>, granted: boolean, declared: boolean, os_authorization: string, };
 export type DirectoryGrant = { id: string, name: string, available: boolean, 
 /**

package/src/index.ts

@@ -133,8 +133,14 @@ export const shortcuts = {list:()=>globalThis.medeoPlugin.invoke('shortcuts.list
 /** `panel: true` (macOS): a frameless window floating over every app and Space that does not
  * activate Medeo — the app the user was in keeps focus — opened at the pointer and hidden (not
  * closed) when it loses focus; opening it again moves it to the pointer. `hide` keeps a window
- * and its page alive for the next `open`/`focus`. */
-export const appWindows = {open:(options:{id:string;entry:string;title:string;width:number;height:number;panel?:boolean})=>globalThis.medeoPlugin.invoke('windows.open',options),close:(id:string)=>globalThis.medeoPlugin.invoke('windows.close',{id}),focus:(id:string)=>globalThis.medeoPlugin.invoke('windows.focus',{id}),hide:(id:string)=>globalThis.medeoPlugin.invoke('windows.hide',{id}),list:()=>globalThis.medeoPlugin.invoke('windows.list') as Promise<{id:string;title:string;visible:boolean}[]>};
+ * and its page alive for the next `open`/`focus`.
+ * `overlay: true` (macOS, needs `window_management` too): a transparent, shadowless panel covering
+ * the whole display under the pointer (menu bar included), above full-screen apps — for previews
+ * and radial menus. It takes keyboard focus without activating Medeo, hides when it loses focus,
+ * and each `open` moves it to the pointer's display; `width`/`height` are ignored. The page's
+ * `window.screenX/screenY` is the display's top-left in the same global points as
+ * `windowManagement`. `panel` and `overlay` are exclusive. */
+export const appWindows = {open:(options:{id:string;entry:string;title:string;width:number;height:number;panel?:boolean;overlay?:boolean})=>globalThis.medeoPlugin.invoke('windows.open',options),close:(id:string)=>globalThis.medeoPlugin.invoke('windows.close',{id}),focus:(id:string)=>globalThis.medeoPlugin.invoke('windows.focus',{id}),hide:(id:string)=>globalThis.medeoPlugin.invoke('windows.hide',{id}),list:()=>globalThis.medeoPlugin.invoke('windows.list') as Promise<{id:string;title:string;visible:boolean}[]>};
 /** A menu entry, a checkmarked toggle, or a divider. */
 export type TrayItem = {id:string;title:string;checked?:boolean}|{separator:true};
 /** `icon`: a PNG in the package drawn as a menu-bar template (black + alpha, about 36 px tall);
@@ -457,6 +463,28 @@ function mediaProvider(kind:'camera'|'microphone'|'system_audio'){return{
 }}
 export const camera=mediaProvider('camera'),microphone=mediaProvider('microphone'),systemAudio=mediaProvider('system_audio');
 export const accessibility={status:()=>nativeCall('accessibility.status'),request:()=>nativeCall('accessibility.request'),windows:()=>nativeCall<{id:string;title:string;application:string}[]>('accessibility.windows'),focus:(id:string)=>nativeCall('accessibility.focus',{id}),selectedText:(id:string)=>nativeCall<{id:string;text:string}>('accessibility.selected_text',{id}),insertText:(focus:string,text:string)=>nativeCall('accessibility.insert_text',{id:focus,text})};
+/** A rectangle in global points: origin at the top-left of the main display, y grows downwards
+ * (displays left of or above the main one have negative coordinates). */
+export interface WindowFrame {x:number;y:number;width:number;height:number}
+/** The frontmost window of another app. `id` stays the same for the same window while it lives. */
+export interface ManagedWindow {id:string;title:string;application:string;bundle_id:string;frame:WindowFrame;resizable:boolean;fullscreen:boolean;minimized:boolean;standard:boolean}
+/** `visible_frame` excludes the menu bar and the Dock. `id` is the display number for this session,
+ * `uuid` survives restarts and reconnecting. The first entry is the main display. */
+export interface ManagedScreen {id:string;uuid:string;name:string;primary:boolean;scale:number;frame:WindowFrame;visible_frame:WindowFrame}
+/** Window management (macOS, permission `window_management`, OS Accessibility). All calls are
+ * operations: `operations.wait(await windowManagement.focused())`. `request` opens the system
+ * prompt and is window-only; the others work in the worker too. `focused` never returns a Medeo window:
+ * when Medeo is in front (a plugin's own page) it is the window of the app right behind it, and `null`
+ * when there is none or the frontmost app has no window; `set_frame` reports the frame the app
+ * actually accepted (apps may clamp sizes) and fails with `resource_missing` once the window is gone. */
+export const windowManagement={
+ status:()=>nativeCall<{authorization:'granted'|'denied'}>('window_management.status'),
+ request:()=>nativeCall<{authorization:'granted'|'denied'}>('window_management.request'),
+ focused:()=>nativeCall<ManagedWindow|null>('window_management.focused'),
+ setFrame:(id:string,frame:WindowFrame)=>nativeCall<{frame:WindowFrame;resized:boolean}>('window_management.set_frame',{id,x:frame.x,y:frame.y,width:frame.width,height:frame.height}),
+ screens:()=>nativeCall<ManagedScreen[]>('window_management.screens'),
+ pointer:()=>nativeCall<{x:number;y:number}>('window_management.pointer'),
+};
 export const browserView={open:(id:string,url:string,width=1000,height=720)=>capabilities.invoke('browser.open',{id,url,width,height}),state:(id:string)=>capabilities.invoke('browser.state',{id}),close:(id:string)=>capabilities.invoke('browser.close',{id})};
 export const printing={print:(text:string)=>capabilities.invoke('printing.print',{text})};
 export const processes={start:(executable:string,args:string[]=[],timeoutMs=60000)=>nativeCall<{id:string;status:string}>('process.start',{executable,arguments:args,timeout_ms:timeoutMs}),state:(id:string)=>nativeCall<{status:string;exit_code:number|null;stdout:string;stderr:string;truncated:boolean}>('process.state',{id}),write:(id:string,text:string)=>nativeCall<{written:number}>('process.write',{id,text}),stop:(id:string)=>nativeCall('process.stop',{id})};

package/src/registry.ts

@@ -102,6 +102,12 @@ export const METHODS = {
   "accessibility.focus": { permission: "accessibility", provider: "medeo.system-services", ui: true, confirm: false, adapter: "host" },
   "accessibility.selected_text": { permission: "accessibility", provider: "medeo.system-services", ui: true, confirm: false, adapter: "host" },
   "accessibility.insert_text": { permission: "accessibility", provider: "medeo.system-services", ui: true, confirm: false, adapter: "host" },
+  "window_management.status": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
+  "window_management.request": { permission: "window_management", provider: "medeo.system-services", ui: true, confirm: false, adapter: "host" },
+  "window_management.focused": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
+  "window_management.set_frame": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
+  "window_management.screens": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
+  "window_management.pointer": { permission: "window_management", provider: "medeo.system-services", ui: false, confirm: false, adapter: "host" },
   "input_method.status": { permission: "input_method", provider: "medeo.input-method", ui: false, confirm: false, adapter: "host" },
   "input_method.configure": { permission: "input_method", provider: "medeo.input-method", ui: false, confirm: false, adapter: "host" },
   "input_method.enable": { permission: "input_method", provider: "medeo.input-method", ui: true, confirm: false, adapter: "host" },