@medeo-plugin/sdk 0.0.0-stage → 0.8.0

package/src/index.ts

@@ -0,0 +1,468 @@
+import type {JsonValue} from './generated.ts';
+import type {MethodName} from './registry.ts';
+export {METHODS, LIMITS, type MethodName} from './registry.ts';
+/** One SDK for both runtimes: a sandboxed worker/window, and a `runtime: "node"`
+ * plugin, whose bootstrap installs the same `medeoPlugin` surface. The SDK itself
+ * imports nothing from Node and asserts no identity of its own. */
+export type { Manifest, PluginCommand, Permission, CapabilityDescriptor } from './generated.ts';
+/** The `api_version` this SDK targets; `spec/api-v1.json` carries the same number. */
+export const API_VERSION = 1;
+export interface PluginAPI {
+  onLocaleChanged(callback:(state:PluginLocaleState)=>void):()=>void;
+  onEvent(callback:(event:PlatformEvent)=>void):()=>void;
+  post(message:unknown):Promise<void>;
+  onMessage(callback:(message:unknown)=>void):()=>void;
+  invoke(method: MethodName, args?: Record<string, unknown>): Promise<unknown>;
+  run(command: string, args?: JsonValue): Promise<unknown>;
+}
+declare global { var medeoPlugin: PluginAPI; interface Window { medeoPlugin: PluginAPI } }
+
+/** Pushed by the Host: an operation changed status (or streamed progress), or a
+ * plugin-owned queue has entries to pull. Events carry no payload data. */
+export type PlatformEvent =
+  | {type:'operation';id:string;method:string;status:string;revision?:number}
+  | {type:'signal';channel:'files.watch'|'server'|'input_method'|'background'|'permissions'|'config'|'shortcuts'|'tray'};
+/** Messages between this plugin's background worker and its own windows
+ * (64 KiB each, JSON). A worker message reaches every open window; a window
+ * message reaches the worker. Nothing is persisted or sent elsewhere. */
+export const channel = {
+  post:(message:unknown)=>globalThis.medeoPlugin.post(message),
+  onMessage:<T=unknown>(callback:(message:T)=>void)=>globalThis.medeoPlugin.onMessage(m=>callback(m as T)),
+};
+export const events = {
+  on:(callback:(event:PlatformEvent)=>void)=>globalThis.medeoPlugin.onEvent(callback),
+  /** Call `pull` now and again whenever the channel signals new entries. A
+   * failed pull (e.g. a permission withdrawn meanwhile) waits for the next signal. */
+  onSignal(channel:Extract<PlatformEvent,{type:'signal'}>['channel'],pull:()=>unknown){
+    const run=()=>{void Promise.resolve().then(pull).catch(()=>{})};
+    const off=globalThis.medeoPlugin.onEvent(event=>{if(event.type==='signal'&&event.channel===channel)run()});
+    run();return off;
+  },
+};
+/** Resolves on the next event for `id`, or after `fallbackMs` as a safety net. */
+function nextChange(id:string,fallbackMs:number):{promise:Promise<void>;off:()=>void}{
+  let off=()=>{};
+  const promise=new Promise<void>(resolve=>{
+    const timer=setTimeout(resolve,fallbackMs);
+    const stop=globalThis.medeoPlugin.onEvent(event=>{if(event.type==='operation'&&event.id===id){clearTimeout(timer);resolve()}});
+    off=()=>{clearTimeout(timer);stop()};
+  });
+  return {promise,off};
+}
+export const storage = {
+  get: <T = unknown>(key: string) => globalThis.medeoPlugin.invoke('storage.get', { key }) as Promise<T | null>,
+  remove: (key:string) => globalThis.medeoPlugin.invoke('storage.remove',{key}),
+  set: (key: string, value: unknown) => globalThis.medeoPlugin.invoke('storage.set', { key, value }),
+};
+export const creation = { open: () => globalThis.medeoPlugin.invoke('creation.open') };
+export const commands = { run: <T = unknown>(command: string, args?: JsonValue) => globalThis.medeoPlugin.run(command, args) as Promise<T> };
+export interface Disposable { dispose(): unknown }
+/** Passed to `activate` (VS Code style), in both runtimes. */
+export interface PluginContext {
+  /** Disposed, in reverse order, when the plugin stops. */
+  subscriptions: Disposable[];
+  /** Register a handler for each command the manifest declares; all must be registered when `activate` returns. */
+  commands: { register(id: string, handler: (args?: JsonValue) => unknown | Promise<unknown>): Disposable };
+  /** `runtime: "node"` only: the installed, verified package directory (read-only). */
+  extensionPath?: string;
+  /** `runtime: "node"` only: a private writable directory that survives updates. */
+  storagePath?: string;
+}
+/** A plugin's background entry: export the result, e.g.
+ * `export const { activate, deactivate } = definePlugin({ activate(context) { … } })`. */
+export interface PluginDefinition {
+  activate(context: PluginContext): unknown | Promise<unknown>;
+  deactivate?(): unknown | Promise<unknown>;
+}
+export function definePlugin(definition: PluginDefinition): Required<PluginDefinition> {
+  return { deactivate: () => undefined, ...definition };
+}
+/** Settings declared under `contributes.configuration`; the user edits them in the plugin center. */
+export const config = {
+  get: <T = unknown>(key: string) => globalThis.medeoPlugin.invoke('config.get', { key }) as Promise<T>,
+  all: () => globalThis.medeoPlugin.invoke('config.get') as Promise<Record<string, unknown>>,
+  set: (key: string, value: unknown) => globalThis.medeoPlugin.invoke('config.set', { key, value }),
+  /** Calls `listener` with all values after each change, from the user or the plugin. */
+  onDidChange(listener: (values: Record<string, unknown>) => void): () => void {
+    return globalThis.medeoPlugin.onEvent(event => {
+      if (event.type === 'signal' && event.channel === 'config') void config.all().then(listener).catch(() => {});
+    });
+  },
+};
+
+/** Native providers return quickly; subscribe to progress instead of holding a command open. */
+export interface Provider { id: string; version: number; available: boolean; capabilities: string[] }
+/** `full`: the user approved full access (view and direct Trash) for this directory. */
+export interface Resource { id: string; name: string; available: boolean; full?: boolean }
+/** Ask for full access (requires the `file_full_access` permission). */
+export interface DirectoryAccess { full?: boolean }
+export const providers = {
+  list: () => globalThis.medeoPlugin.invoke('providers.list') as Promise<Provider[]>,
+  require: async (id: string, version = 1) => {
+    const provider = (await providers.list()).find(p => p.id === id && p.version === version && p.available);
+    if (!provider) throw new Error('provider_unavailable');
+    return provider;
+  },
+};
+export const resources = {
+  chooseDirectories: (access: DirectoryAccess = {}) => globalThis.medeoPlugin.invoke('resources.choose_directories', access.full ? { full: true } : {}) as Promise<Resource[]>,
+  list: () => globalThis.medeoPlugin.invoke('resources.list') as Promise<Resource[]>,
+  revoke: (id: string) => globalThis.medeoPlugin.invoke('resources.revoke', { id }) as Promise<Resource[]>,
+  requestDirectory: (path: string, reason: string, access: DirectoryAccess = {}) => globalThis.medeoPlugin.invoke('resources.request_directory', { path, reason, ...(access.full ? { full: true } : {}) }) as Promise<Resource[]>,
+};
+/** Generic registered-provider entry point; the Host remains the authority. */
+export const capabilities = {
+  list: () => globalThis.medeoPlugin.invoke('capabilities.list') as Promise<import('./generated').CapabilityDescriptor[]>,
+  labels: () => globalThis.medeoPlugin.invoke('capabilities.labels') as Promise<Record<string,string>>,
+  invoke: <T=unknown>(method:string,args:Record<string,unknown>={}) => globalThis.medeoPlugin.invoke(method as MethodName,args) as Promise<T>,
+};
+export const clipboard = {read:()=>globalThis.medeoPlugin.invoke('clipboard.read') as Promise<{text:string}>,write:(text:string)=>globalThis.medeoPlugin.invoke('clipboard.write',{text})};
+/** `running` reports, per rule, whether a matching process exists; it never
+ * returns the process list. Rules match an exact executable name or a path fragment. */
+export interface ProcessRule {name?:string;path_contains?:string}
+export interface SystemInfo {platform:string;architecture:string;release:string;locale:string;/** The Medeo running the plugin (0.1.23+; absent on older Medeo). */medeo?:{version:string;channel:'stg'|'prd'};displays:{id:string;bounds:{x:number;y:number;width:number;height:number};scale:number}[]}
+export const system = {info:()=>globalThis.medeoPlugin.invoke('system.info') as Promise<SystemInfo>,running:(rules:ProcessRule[])=>capabilities.invoke<NativeOperation<boolean[]>>('system.running',{rules})};
+/** One outcome per path of `trash`, in the order given. */
+export interface TrashResult {path:string;trashed:boolean;error?:string}
+/** `runtime: "node"` plugins only (the `node` permission): moves up to 256 absolute
+ * paths to the OS Trash, the one thing Node cannot do itself. A failure does not stop the rest. */
+export const trash = (paths:string[]) => globalThis.medeoPlugin.invoke('system.trash',{paths}) as Promise<TrashResult[]>;
+export const notifications = {show:(id:string,title:string,body:string)=>globalThis.medeoPlugin.invoke('notifications.show',{id,title,body}),close:(id:string)=>globalThis.medeoPlugin.invoke('notifications.close',{id})};
+export const power = {start:(type:'prevent-app-suspension'|'prevent-display-sleep')=>globalThis.medeoPlugin.invoke('power.start',{type}) as Promise<{id:string}>,stop:(id:string)=>globalThis.medeoPlugin.invoke('power.stop',{id}),state:()=>globalThis.medeoPlugin.invoke('power.state')};
+export const shortcuts = {list:()=>globalThis.medeoPlugin.invoke('shortcuts.list') as Promise<{id:string;accelerator:string;open_ui:boolean}[]>,register:(id:string,accelerator:string,openUI=false)=>globalThis.medeoPlugin.invoke('shortcuts.register',{id,accelerator,open_ui:openUI}),unregister:(id:string)=>globalThis.medeoPlugin.invoke('shortcuts.unregister',{id}),events:()=>globalThis.medeoPlugin.invoke('shortcuts.events')};
+/** `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}[]>};
+/** 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);
+ *  `click`: an id reported on a left click, which then leaves the menu to a right click. */
+export interface TrayOptions {icon?:string;click?:string}
+export const tray = {set:(title:string,items:TrayItem[],options:TrayOptions={})=>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:string)=>globalThis.medeoPlugin.invoke('external.open',{url})};
+
+/** `scope` says how long an approval lasts: `always` (stored), `run` (until the plugin stops),
+ * `never` (refused with "don't ask again"). `remembered`: refused earlier, no dialog was shown. */
+export interface PermissionAnswer { granted: boolean; scope?: 'always' | 'run' | 'never' | 'none'; remembered?: boolean }
+export const permissions = {request:(permission:string,reason:string)=>globalThis.medeoPlugin.invoke('permissions.request',{permission,reason}) as Promise<PermissionAnswer>};
+
+/** One of the plugin's own actions for the user to approve (`approvals` permission; `action` must be declared).
+ * `rule_key` identifies it (`bash:git status`); `rule_pattern` (a prefix of it ending in `*`) is what
+ * "always" remembers instead. Medeo draws the dialog and keeps the rules. In a Node plugin nothing
+ * forces you to ask: it is up to the plugin to call this before acting. */
+export interface ApprovalRequest {
+  action: string; title: string; detail?: string;
+  preview?: { kind: 'text' | 'command' | 'diff'; text: string };
+  rule_key: string; rule_pattern?: string;
+}
+/** `scope`: `once`, `run`, `always`, or `rule` when a remembered answer decided without a dialog. */
+export interface ApprovalAnswer { decision: 'allow' | 'deny'; scope: 'once' | 'run' | 'always' | 'rule'; rule?: string }
+export interface ApprovalRule { action: string; pattern: string; allow: boolean; scope: 'run' | 'always' }
+export const approvals = {
+  request:(request:ApprovalRequest)=>globalThis.medeoPlugin.invoke('approvals.request',{...request}) as Promise<ApprovalAnswer>,
+  rules:()=>globalThis.medeoPlugin.invoke('approvals.rules') as Promise<ApprovalRule[]>,
+  forget:(action:string,pattern:string)=>globalThis.medeoPlugin.invoke('approvals.forget',{action,pattern}) as Promise<ApprovalRule[]>,
+};
+
+
+// Text content stays in Host memory. Closing a window does not cancel jobs;
+// state() without an id lists jobs owned by this active plugin instance.
+export interface AgentJob {
+  id: string; status: 'running' | 'completed' | 'failed' | 'cancelled';
+  text?: string; models?: string[]; error?: string | null;
+}
+export const agent = {
+  models: () => capabilities.invoke<AgentJob>('agent.models', {}),
+  start: (messages: {role:'system'|'user'|'assistant';content:string}[], model?:string) =>
+    capabilities.invoke<AgentJob>('agent.start', {messages, ...(model ? {model} : {})}),
+  state: (id:string) => operations.state(id) as Promise<AgentJob>,
+  cancel: (id:string) => operations.cancel(id) as Promise<AgentJob>,
+  release: (id:string) => operations.release(id),
+  /** Calls `onText` as the reply streams in; resolves with the final job. */
+  async follow(id:string,onText:(job:AgentJob)=>void):Promise<AgentJob>{
+    for(;;){const change=nextChange(id,2000);const job=await agent.state(id);onText(job);if(job.status!=='running'){change.off();return job}await change.promise;change.off()}
+  },
+};
+
+export interface ApplicationEntry { id:string;title:string;path:string;bundle_id:string }
+export interface ApplicationList { status:string;error:string|null;incomplete:boolean;total:number;entries:ApplicationEntry[] }
+export interface ApplicationState { status:string;error:string|null;launch:{id:string;status:string;error:string|null;pid?:number}|null }
+export const applications = {
+  /** The whole inventory; plugins rank and filter it themselves. */
+ list: (refresh=false) => capabilities.invoke<ApplicationList>('applications.list',{refresh}),
+  launch: (id:string) => capabilities.invoke<{id:string;status:string}>('applications.launch',{id}),
+  state: () => capabilities.invoke<ApplicationState>('applications.state',{}),
+};
+
+export interface CaptureSource {id:string;title:string;width:number;height:number}
+export interface CaptureRecord {id:string;source_title:string;status:string;active:boolean;can_stop:boolean;can_recover:boolean;error?:string|null;playable:boolean;duration_ms:number;bytes:number;microphone:boolean;system_audio:boolean;audio_tracks?:number}
+export const capture = {
+ status:(refresh=true)=>capabilities.invoke<{status:string;os:Record<string,string>}>('capture.status',{refresh}),
+ sources:(refresh=false,requestPermission=false)=>capabilities.invoke<{status:string;error?:string;os:Record<string,string>;sources:CaptureSource[]}>('capture.sources',{refresh,request_permission:requestPermission}),
+ start:(source:string,options:{microphone?:boolean;systemAudio?:boolean}={})=>capabilities.invoke<{id?:string;cancelled?:boolean}>('capture.start',{source,microphone:options.microphone??false,system_audio:options.systemAudio??false}),
+ state:()=>capabilities.invoke<{records:CaptureRecord[];os:Record<string,string>}>('capture.state',{}),
+ stop:(id:string)=>capabilities.invoke('capture.stop',{id}),
+ cancel:(id:string)=>capabilities.invoke('capture.cancel',{id}),
+ recover:(id:string)=>capabilities.invoke('capture.recover',{id}),
+ open:(id:string,mode:'play'|'reveal'='play')=>capabilities.invoke('capture.open',{id,mode}),
+ previewURL:(id:string)=>location.origin+'/_capture/'+encodeURIComponent(id)+'.mp4',
+};
+
+export interface InputMethodState {enabled:boolean;provider_ready:boolean;configured_name:string;occupied:boolean;system_source:string}
+export interface InputSourceState {status:string;state_key:string;can_setup:boolean;can_remove:boolean;installed?:boolean;registered?:boolean;enabled?:boolean;selected?:boolean;update_available?:boolean;error?:string;last_operation?:{id:string;status:string;error?:string};task?:string}
+export const inputMethod={
+ system:(refresh=false)=>capabilities.invoke<InputSourceState>('input_method.system',{refresh}),
+ setup:()=>capabilities.invoke<{task?:string;cancelled?:boolean}>('input_method.setup'),
+ remove:()=>capabilities.invoke<{task?:string;cancelled?:boolean}>('input_method.remove'),
+ settings:()=>capabilities.invoke<{task:string}>('input_method.settings'),
+ status:()=>capabilities.invoke<InputMethodState>('input_method.status'),
+ configure:(name:string)=>capabilities.invoke('input_method.configure',{name}),
+ enable:()=>capabilities.invoke<InputMethodState>('input_method.enable'),
+ disable:()=>capabilities.invoke('input_method.disable'),
+ events:()=>capabilities.invoke<{id:string;text:string}[]>('input_method.events'),
+ respond:(id:string,candidates:string[])=>capabilities.invoke('input_method.respond',{id,candidates}),
+};
+
+/** HTTP uses only approved origins; no redirects, browser cookies, or Medeo credentials.
+ * Closing UI preserves jobs; disable/revoke cancels. Mutations are never replayed.
+ * Release completed results to return the per-instance memory quota.
+ */
+export interface NetworkRequest {url:string;method?:'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'DELETE'|'OPTIONS';headers?:Record<string,string>;body?:string;body_base64?:string;timeout_ms?:number;stream?:boolean}
+export interface NetworkJob {id:string;status:'running'|'completed'|'failed'|'cancelled';received?:number;http_status?:number|null;headers?:[string,string][];error?:string|null;stream?:boolean}
+export interface NetworkChunk {data_base64:string;next_offset:number;eof:boolean}
+export interface NetworkOrigin {origin:string;declared:boolean;allowed:boolean}
+export interface NetworkServerEvent {data:string;event:string;id:string;retry?:number}
+export const network = {
+ origins:()=>capabilities.invoke<NetworkOrigin[]>('network.origins'),
+ requestOrigin:(origin:string,reason:string)=>capabilities.invoke<{origin:string;granted:boolean}>('network.request_origin',{origin,reason}),
+ revokeOrigin:(origin:string)=>capabilities.invoke<NetworkOrigin[]>('network.revoke_origin',{origin}),
+ request:(request:NetworkRequest)=>capabilities.invoke<NetworkJob>('network.request',{...request}),
+ state:(id:string)=>operations.state(id) as Promise<NetworkJob>,
+ read:(id:string,offset=0,length=32768)=>capabilities.invoke<NetworkChunk>('network.read',{id,offset,length}),
+ cancel:(id:string)=>operations.cancel(id) as Promise<NetworkJob>,
+ release:(id:string)=>operations.release(id) as Promise<{released:boolean}>,
+ /** Resolves once the response has fully arrived; the job stays readable until released. */
+ async settled(id:string):Promise<NetworkJob>{for(;;){const change=nextChange(id,2000);const state=await network.state(id);if(state.status!=='running'){change.off();return state}await change.promise;change.off()}},
+ /** Single consumer for a stream:true job. Break/throw/abort cancels and releases it. */
+ async *bytes(id:string,signal?:AbortSignal):AsyncGenerator<Uint8Array>{
+   let offset=0;
+   let abortCleanup:Promise<void>|undefined;
+   const abort=()=>{abortCleanup=network.dispose(id);void abortCleanup.catch(()=>{})};
+   signal?.addEventListener('abort',abort,{once:true});
+   try {
+     for(;;){
+       let wake!:()=>void;
+       const changed=new Promise<void>(resolve=>{wake=resolve});
+       const off=events.on(event=>{if(event.type==='operation'&&event.id===id)wake()});
+       signal?.addEventListener('abort',wake,{once:true});
+       try {
+         if(signal?.aborted)throw new Error('network_cancelled');
+         const state=await network.state(id);
+         if(state.status==='failed'||state.status==='cancelled')throw new Error(state.error??state.status);
+         const part=await network.read(id,offset);
+         offset=part.next_offset;
+         if(signal?.aborted)throw new Error('network_cancelled');
+         if(part.data_base64)yield Uint8Array.from(atob(part.data_base64),c=>c.charCodeAt(0));
+         if(part.eof)return;
+         if(!part.data_base64)await changed;
+       } finally {off();signal?.removeEventListener('abort',wake)}
+     }
+   } finally {
+     signal?.removeEventListener('abort',abort);
+     await (abortCleanup??network.dispose(id));
+   }
+ },
+ /** Incremental UTF-8 decoder, including code points split across HTTP chunks. */
+ async *textStream(id:string,signal?:AbortSignal):AsyncGenerator<string>{
+   const decoder=new TextDecoder();
+   for await(const bytes of network.bytes(id,signal)){
+     const text=decoder.decode(bytes,{stream:true});if(text)yield text;
+   }
+   const tail=decoder.decode();if(tail)yield tail;
+ },
+ /** SSE framing only: no automatic reconnect/retry or Last-Event-ID requests. */
+ async *sse(id:string,signal?:AbortSignal):AsyncGenerator<NetworkServerEvent>{
+   let pending='',data:string[]=[],event='',lastId='',retry:number|undefined,size=0,skipLf=false;
+   for await(const text of network.textStream(id,signal)){
+     pending+=skipLf&&text.startsWith('\n')?text.slice(1):text;
+     skipLf=false;
+     for(;;){
+       const at=pending.search(/[\r\n]/);
+       if(at<0)break;
+       skipLf=pending[at]==='\r'&&at===pending.length-1;
+       const line=pending.slice(0,at);
+       pending=pending.slice(at+(pending[at]==='\r'&&pending[at+1]==='\n'?2:1));
+       size+=line.length;
+       if(size>262144)throw new Error('network_sse_event_too_large');
+       if(!line){
+         if(data.length)yield {data:data.join('\n'),event:event||'message',id:lastId,...(retry===undefined?{}:{retry})};
+         data=[];event='';size=0;continue;
+       }
+       if(line.startsWith(':'))continue;
+       const colon=line.indexOf(':');
+       const field=colon<0?line:line.slice(0,colon);
+       let value=colon<0?'':line.slice(colon+1);if(value.startsWith(' '))value=value.slice(1);
+       if(field==='data')data.push(value);
+       else if(field==='event')event=value;
+       else if(field==='id'&&!value.includes('\0'))lastId=value;
+       else if(field==='retry'&&/^\d+$/.test(value)&&Number.isSafeInteger(Number(value)))retry=Number(value);
+     }
+     if(size+pending.length>262144)throw new Error('network_sse_event_too_large');
+   }
+   // SSE requires a blank line to dispatch; incomplete final events are discarded.
+ },
+ /** Explicitly dispose a stream that was never iterated (or has another owner). */
+ async dispose(id:string):Promise<void>{
+   const ignoreMissing=(error:unknown)=>{if(!/^(operation_missing|network_job_missing|permission_denied)$/.test(error instanceof Error?error.message:String(error)))throw error};
+   try{await network.cancel(id)}catch(error){ignoreMissing(error)}
+   try{await network.release(id)}catch(error){ignoreMissing(error)}
+ },
+ async text(id:string):Promise<string>{
+   const decoder=new TextDecoder();let offset=0,text='';
+   for(;;){const part=await network.read(id,offset);const bytes=Uint8Array.from(atob(part.data_base64),c=>c.charCodeAt(0));text+=decoder.decode(bytes,{stream:!part.eof});if(part.eof)return text;offset=part.next_offset;}
+ },
+};
+
+/** Workspace operations use current directory references and asynchronous jobs. */
+export interface FileRoot {id:string|null;name:string;available:boolean;error?:string}
+export interface FileEntry {path:string;name:string;kind:'file'|'directory'|'blocked';size:number;revision:string;accessible:boolean}
+export interface FileRecord {id:string;operation:string;source:string;destination:string;status:string;has_original:boolean;in_trash?:boolean|null;created_ms:number|null;retention:"workspace"|"trash"|"none"|"unknown"}
+export interface FileJob<T=unknown> {id:string;status:'running'|'completed'|'failed'|'cancelled';result:T|null;error:string|null;method?:string}
+export interface FileWatch {id:string;status:'starting'|'watching'|'stopped'|'failed';cursor?:number;error?:string|null}
+export interface FileWatchEvents extends FileWatch {cursor:number;rescan_required:boolean;events:{cursor:number;kind:'ready'|'created'|'changed'|'removed'|'rescan_required';path:string|null}[]}
+export interface FilePreview {id:string;path:string;bytes:number;count:number;revision:string|null;purpose:string;record:string|null}
+export interface FileHistoryPage {items:FileRecord[];next_cursor:string|null;total:number}
+export const files = {
+ backupPreview:(root:string,record:string)=>capabilities.invoke<FileJob<FilePreview>>('files.backup_preview',{root,record}),
+ archiveBackup:(preview:string)=>capabilities.invoke<FileJob<FileRecord>>('files.archive_backup',{preview}),
+ forgetPreview:(root:string,record:string)=>capabilities.invoke<FileJob<FilePreview>>('files.forget_preview',{root,record}),
+ forgetRecord:(preview:string)=>capabilities.invoke<FileJob<{forgotten:string}>>('files.forget_record',{preview}),
+ historyPage:(root:string,cursor?:string,limit=50)=>capabilities.invoke<FileJob<FileHistoryPage>>('files.history_page',{root,...(cursor?{cursor}:{}),limit}),
+ trashPreview:(root:string,path:string)=>capabilities.invoke<FileJob<FilePreview>>('files.trash_preview',{root,path}),
+ discardPreview:(preview:string)=>capabilities.invoke<{discarded:boolean}>('files.discard_preview',{preview}),
+ trash:(preview:string)=>capabilities.invoke<FileJob<FileRecord>>('files.trash',{preview}),
+ /** Breadth-first listings of a whole tree in one call. Hidden and `skip`
+  * directories are listed by their parent but not entered. */
+ listTree:(root:string,path='',options:{depth?:number;skip?:string[];hidden?:boolean;limit?:number}={})=>capabilities.invoke<FileJob<{directories:{path:string;entries?:FileEntry[];error?:string}[];truncated:boolean}>>('files.list_tree',{root,path,...options}),
+ /** Full-access roots only: move entries to the Trash without a Host confirmation.
+  * `stamp` is what `files.measure` returned; a changed entry is refused, not moved. */
+ trashDirect:(items:{root:string;path:string;stamp:{revision:string;digest:string;bytes:number;count:number}}[])=>capabilities.invoke<FileJob<{path:string;record?:FileRecord;error?:string}[]>>('files.trash_direct',{items}),
+ watch:(root:string,path='',recursive=false)=>capabilities.invoke<FileWatch>('files.watch',{root,path,recursive}),
+ watches:()=>capabilities.invoke<FileWatch[]>('files.watches'),
+ events:(id:string,after=0)=>capabilities.invoke<FileWatchEvents>('files.events',{id,after}),
+ unwatch:(id:string)=>capabilities.invoke<{stopped:boolean}>('files.unwatch',{id}),
+ roots:()=>capabilities.invoke<FileJob<FileRoot[]>>('files.roots'),
+ list:(root:string,path='')=>capabilities.invoke<FileJob<FileEntry[]>>('files.list',{root,path}),
+ stat:(root:string,path='')=>capabilities.invoke<FileJob<FileEntry>>('files.stat',{root,path}),
+ readText:(root:string,path:string,revision?:string)=>capabilities.invoke<FileJob<{text:string;entry:FileEntry}>>('files.read_text',{root,path,...(revision?{revision}:{})}),
+ writeText:(root:string,path:string,text:string,revision:string)=>capabilities.invoke<FileJob<{record:FileRecord;entry:FileEntry|null}>>('files.write_text',{root,path,text,revision}),
+ mkdir:(root:string,path:string)=>capabilities.invoke<FileJob<FileEntry>>('files.mkdir',{root,path}),
+ move:(root:string,path:string,destination:string,revision:string)=>capabilities.invoke<FileJob<FileRecord>>('files.move',{root,path,destination,revision}),
+ history:(root:string)=>capabilities.invoke<FileJob<FileRecord[]>>('files.history',{root}),
+ restore:(root:string,record:string)=>capabilities.invoke<FileJob<FileRecord>>('files.restore',{root,record}),
+ state:<T=unknown>(id:string)=>operations.state<T>(id) as Promise<FileJob<T>>,
+ cancel:(id:string)=>operations.cancel(id),
+ release:(id:string)=>operations.release(id),
+ result:<T>(job:FileJob<T>):Promise<T>=>operations.wait<T>(job),
+};
+
+/** Plugin-owned credentials. Values are returned only to this granted plugin;
+ * Agent/Medeo credentials are never part of this vault. No automatic retry. */
+export interface SecretOperation { id:string; status:'running'|'completed'|'failed'; value?:string|null; error?:string }
+async function secretOperation(method:'get'|'set'|'remove',args:Record<string,unknown>):Promise<string|null>{
+ const job=await capabilities.invoke<SecretOperation>('secrets.'+method,args);
+ const deadline=Date.now()+30000;
+ for(;;){
+  const change=nextChange(job.id,1000);
+  const result=await capabilities.invoke<SecretOperation>('secrets.result',{id:job.id});
+  if(result.status!=='running')change.off();
+  if(result.status==='completed')return result.value??null;
+  if(result.status==='failed')throw Error(result.error??'secrets_storage_failed');
+  if(Date.now()>=deadline){change.off();throw Error('secrets_outcome_unknown')}
+  await change.promise;change.off();
+ }
+}
+export const secrets={
+ get:(key:string)=>secretOperation('get',{key}),
+ set:async(key:string,value:string)=>{await secretOperation('set',{key,value})},
+ remove:async(key:string)=>{await secretOperation('remove',{key})},
+};
+
+export interface LocalServerOptions { port?:number; routes:{method:'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'DELETE';path:string}[]; origins?:string[]; timeout_ms?:number }
+export interface LocalServerState { id:string; status:'starting'|'running'|'stopping'|'stopped'|'failed'; origin:string|null; error:string|null; pending:number; accepted:number }
+export interface LocalRequest { id:string; method:string; path:string; query:string; headers:Record<string,string>; body_base64:string }
+/** A loopback server is instance-owned and never survives Host restart. Keep the
+ * start token in private memory and serve requests in a worker for background use. */
+export const server={
+ start:(options:LocalServerOptions)=>capabilities.invoke<{id:string;status:'starting';access_token:string}>('server.start',{...options}),
+ state:(id:string)=>capabilities.invoke<LocalServerState>('server.state',{id}),
+ list:()=>capabilities.invoke<LocalServerState[]>('server.state'),
+ events:(id:string,limit=8)=>capabilities.invoke<{requests:LocalRequest[]}>('server.events',{id,limit}),
+ respond:(id:string,request:string,response:{status?:number;body_base64?:string;content_type?:string})=>capabilities.invoke<{responded:boolean}>('server.respond',{id,request,...response}),
+ stop:(id:string)=>capabilities.invoke<LocalServerState>('server.stop',{id}),
+};
+
+
+export interface PluginLocaleState {preference:string;locale:string;system_locale:string;direction:'ltr';supported_locales:string[];catalog_locales:string[];catalog_locale:string|null;fallback_locale:string|null;name:string;commands:Record<string,string>}
+/** Text is formatted in Rust from the signed package. Render with textContent,
+ * never innerHTML. Register listeners before initial state fetch to avoid races. */
+export const i18n={
+ state:()=>capabilities.invoke<PluginLocaleState>('i18n.state'),
+ setLocale:(preference:string)=>capabilities.invoke<PluginLocaleState>('i18n.setLocale',{preference}),
+ t:(key:string,params:Record<string,string|number>={})=>capabilities.invoke<string>('i18n.t',{key,params}),
+ /** Every message of the effective locale (default-locale fallback merged in). */
+ catalog:()=>capabilities.invoke<Record<string,string>>('i18n.catalog'),
+ onDidChangeLocale:(callback:(state:PluginLocaleState)=>void)=>globalThis.medeoPlugin.onLocaleChanged(callback),
+};
+
+/** Every asynchronous call returns an owned operation handle. Status changes
+ * are pushed; `wait` resolves on them and releases the result. */
+export interface NativeOperation<T=unknown>{id:string;status:'running'|'completed'|'failed'|'cancelled'|'interrupted';result:T|null;error:string|null}
+export const operations={
+ state:<T=unknown>(id:string)=>capabilities.invoke<NativeOperation<T>>('operations.state',{id}),
+ list:()=>capabilities.invoke<{id:string;method:string;status:string}[]>('operations.list'),
+ cancel:(id:string)=>capabilities.invoke('operations.cancel',{id}),
+ release:(id:string)=>capabilities.invoke('operations.release',{id}),
+ async wait<T>(operation:{id:string;status:string},signal?:AbortSignal):Promise<T>{
+  let value=operation as NativeOperation<T>;
+  while(value.status==='running'){
+   if(signal?.aborted){await operations.cancel(value.id);throw Error('cancelled')}
+   const change=nextChange(value.id,2000);
+   value=await operations.state<T>(value.id);
+   if(value.status==='running')await change.promise;
+   change.off();
+  }
+  // Quick reads may come back settled and already released by the Host.
+  if(!(value as {released?:boolean}).released)await operations.release(value.id);
+  if(value.status!=='completed')throw Error(value.error??value.status);
+  return value.result as T;
+ },
+};
+const nativeCall=<T=unknown>(method:string,args:Record<string,JsonValue>={})=>capabilities.invoke<NativeOperation<T>>(method,args);
+/** A camera / microphone / system audio recording. `waveform` (240 peaks, 0…1) is in `state(id)` once
+ * completed; listings carry a 40-point `waveform_preview` instead. Live fields exist only while recording:
+ * `levels` holds the latest input levels (0…1, about 20 a second) and `levels_seq` counts every level so far;
+ * `frame` is the camera's latest preview as base64 JPEG. "completed" means `previewURL` can play it. */
+export interface MediaRecord {id:string;kind:'camera'|'microphone'|'system_audio';status:'starting'|'recording'|'stopping'|'completed'|'failed'|'interrupted';error?:string|null;created_ms:number;extension:string;duration_ms?:number;bytes?:number;waveform?:number[];waveform_preview?:number[];elapsed_ms?:number;level?:number;peak?:number;levels?:number[];levels_seq?:number;frame?:string}
+function mediaProvider(kind:'camera'|'microphone'|'system_audio'){return{
+ status:()=>nativeCall<{authorization:string}>(kind+'.status'),
+ start:(maxSeconds=300)=>nativeCall<{id:string;status:string}>(kind+'.start',{max_seconds:maxSeconds}),
+ stop:(id:string)=>nativeCall(kind+'.stop',{id}),
+ state:(id?:string)=>nativeCall(kind+'.state',id?{id}:{}),
+ read:(id:string,offset=0,length=32768)=>nativeCall<NetworkChunk>(kind+'.read',{id,offset,length}),
+ /** Same-origin URL for an `<audio>` / `<video>` element; plays once the record is "completed". */
+ previewURL:(record:Pick<MediaRecord,'id'|'extension'>)=>location.origin+'/_media/'+encodeURIComponent(record.id)+(record.extension==='m4a'?'.m4a':'.mp4'),
+}}
+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})};
+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})};
+export interface BackgroundEvent{id:string;schedule:string;due_ms:number;payload:JsonValue}
+export const background={schedule:(id:string,delayMs:number,payload:JsonValue=null,intervalMs=0)=>capabilities.invoke('background.schedule',{id,delay_ms:delayMs,interval_ms:intervalMs,payload}),list:()=>capabilities.invoke('background.list'),cancel:(id:string)=>capabilities.invoke('background.cancel',{id}),events:()=>capabilities.invoke<BackgroundEvent[]>('background.events')};
+export const contacts={status:()=>nativeCall('contacts.status'),request:()=>nativeCall('contacts.request'),list:(query='',limit=50)=>nativeCall('contacts.list',{query,limit}),save:(contact:{given_name:string;family_name:string;email:string;phone:string})=>nativeCall<{id:string;created:boolean}>('contacts.save',contact)};
+export const calendar={status:()=>nativeCall('calendar.status'),request:()=>nativeCall('calendar.request'),list:(startMs:number,endMs:number,limit=50)=>nativeCall('calendar.list',{start_ms:startMs,end_ms:endMs,limit}),save:(event:{title:string;notes:string;start_ms:number;end_ms:number})=>nativeCall<{id:string;created:boolean}>('calendar.save',event)};
+export const deviceLocation={status:()=>nativeCall('location.status'),request:()=>nativeCall('location.request'),current:()=>nativeCall<{latitude:number;longitude:number;accuracy_m:number;timestamp_ms:number}>('location.current')};
+export const devices={choose:(transport:'serial'|'hid'|'ble')=>nativeCall('devices.choose',{transport}),open:(id:string,baudRate=115200)=>nativeCall('devices.open',{id,baud_rate:baudRate}),list:()=>nativeCall('devices.list'),read:(id:string,length=4096)=>nativeCall<{data_base64:string;bytes:number}>('devices.read',{id,length}),write:(id:string,dataBase64:string)=>nativeCall<{written:number}>('devices.write',{id,data_base64:dataBase64}),close:(id:string)=>nativeCall('devices.close',{id})};

package/src/react.ts

@@ -0,0 +1,50 @@
+/** React is only imported by the optional @medeo-plugin/sdk/ui/react entry. */
+import { createElement as h, useEffect, type ReactNode, type KeyboardEvent } from 'react';
+import { segmentTarget, segmentTabIndex, type CardOptions, type PillOptions, type ToggleOptions, type SegmentedOptions, type ListOptions } from './ui.js';
+import { installStyles } from './ui/styles.js';
+export { uiStyles, installStyles } from './ui/styles.js';
+export type { CardOptions, PillOptions, ToggleOptions, SegmentedOptions, ListOptions, Segment } from './ui.js';
+
+/** Call once near your root. SSR-safe; style installation is idempotent. */
+export function useUIStyles(): void { useEffect(() => { installStyles(); }, []); }
+export function Card({ title, description, testid, children }: CardOptions & { children?: ReactNode }) {
+  return h('section', { className: 'medeo-ui medeo-card', 'data-testid': testid, 'aria-label': title },
+    h('h2', { 'data-testid': `${testid}.title` }, title),
+    description !== undefined && h('p', { className: 'medeo-description' }, description), children);
+}
+export function Pill({ label, tone = 'info', testid }: PillOptions) {
+  return h('span', { className: 'medeo-ui medeo-pill', 'data-testid': testid, 'data-tone': tone }, label);
+}
+/** Controlled: update checked in onChange. Native input supplies name and Space handling. */
+export function Toggle({ label, checked, disabled, onChange, testid }: ToggleOptions) {
+  return h('label', { className: 'medeo-ui medeo-toggle', 'data-testid': `${testid}.root` },
+    h('input', { type: 'checkbox', role: 'switch', checked, disabled, 'data-testid': testid, onChange: (event: React.ChangeEvent<HTMLInputElement>) => onChange(event.currentTarget.checked) }),
+    h('span', null, label));
+}
+/** Controlled radio group with a single tab stop and arrow/Home/End navigation. */
+export function Segmented<T extends string>({ label, value, options, disabled, onChange, testid }: SegmentedOptions<T>) {
+  return h('div', { className: 'medeo-ui medeo-segmented', role: 'radiogroup', 'aria-label': label, 'data-testid': testid },
+    options.map((option, index) => h('button', {
+      key: option.value, type: 'button', role: 'radio', 'aria-checked': option.value === value,
+      'data-testid': `${testid}.${index}`, disabled: disabled || option.disabled,
+      tabIndex: disabled ? -1 : segmentTabIndex(options, value, index),
+      onClick: () => { if (!disabled && !option.disabled) onChange(option.value); },
+      onKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => {
+        if (disabled) return;
+        const group = event.currentTarget.parentElement!;
+        const target = segmentTarget(options, index, event.key, getComputedStyle(group).direction === 'rtl');
+        if (target === undefined) return;
+        event.preventDefault();
+        (group.children[target] as HTMLButtonElement).focus();
+        onChange(options[target].value);
+      },
+    }, option.label)));
+}
+export function List({ label, testid, items }: ListOptions & { items: readonly { key: string; content: ReactNode }[] }) {
+  return h('ul', { className: 'medeo-ui medeo-list', 'data-testid': testid, 'aria-label': label },
+    items.map(item => h('li', { key: item.key, 'data-testid': `${testid}.${item.key}` }, item.content)));
+}
+export function EmptyState({ title, description, testid }: CardOptions) {
+  return h('section', { className: 'medeo-ui medeo-empty', 'data-testid': testid, 'aria-label': title },
+    h('h2', null, title), description !== undefined && h('p', { className: 'medeo-description' }, description));
+}