@medeo-plugin/sdk 0.7.0 → 0.9.0

package/src/index.ts

@@ -13,7 +13,7 @@ export interface PluginAPI {
   post(message:unknown):Promise<void>;
   onMessage(callback:(message:unknown)=>void):()=>void;
   invoke(method: MethodName, args?: Record<string, unknown>): Promise<unknown>;
-  run(command: string): Promise<unknown>;
+  run(command: string, args?: JsonValue): Promise<unknown>;
 }
 declare global { var medeoPlugin: PluginAPI; interface Window { medeoPlugin: PluginAPI } }
 
@@ -55,14 +55,14 @@ export const storage = {
   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: (command: string) => globalThis.medeoPlugin.run(command) };
+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: () => unknown | Promise<unknown>): Disposable };
+  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. */
@@ -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);
@@ -229,10 +235,11 @@ export const inputMethod={
  * 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}
-export interface NetworkJob {id:string;status:'running'|'completed'|'failed'|'cancelled';received?:number;http_status?:number|null;headers?:[string,string][];error?:string|null}
+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}),
@@ -244,6 +251,80 @@ export const network = {
  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;}
@@ -382,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/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));
+}

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" },

package/src/rpc.ts

@@ -0,0 +1,136 @@
+import { channel, type Disposable } from './index.ts';
+
+/** A transport is injectable for offline tests; the default is this plugin's own channel. */
+export interface RpcTransport {
+  post(message: unknown): Promise<void>;
+  onMessage(listener: (message: unknown) => void): () => void;
+}
+export interface RpcOptions { transport?: RpcTransport; timeoutMs?: number; signal?: AbortSignal }
+type Handler = (...args: any[]) => unknown;
+export type WorkerApiClient<T> = { [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never } & { $dispose(): void };
+const PROTOCOL = 'medeo.rpc.v1';
+const MAX_PENDING = 64;
+const MAX_BYTES = 60 * 1024;
+interface Packet { protocol: typeof PROTOCOL; kind: 'request' | 'result' | 'error'; client: string; id: string; method?: string; args?: unknown[]; value?: unknown; error?: string }
+function packet(value: unknown): value is Packet {
+  if (!value || typeof value !== 'object') return false;
+  const p = value as Packet;
+  return p.protocol === PROTOCOL && ['request', 'result', 'error'].includes(p.kind) && typeof p.client === 'string' && p.client.length <= 80 && typeof p.id === 'string' && p.id.length <= 80;
+}
+/** Reject values JSON would silently drop or change, rather than corrupting an RPC argument. */
+function checked<T>(value: T): T {
+  const seen = new Set<object>();
+  function visit(v: unknown): void {
+    if (v === null || typeof v === 'string' || typeof v === 'boolean') return;
+    if (typeof v === 'number' && Number.isFinite(v)) return;
+    if (!v || typeof v !== 'object' || (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) || seen.has(v)) throw new Error('rpc_invalid_json');
+    seen.add(v);
+    const array = Array.isArray(v);
+    if (array && Object.keys(v).length !== v.length) throw new Error('rpc_invalid_json');
+    for (const key of Reflect.ownKeys(v)) {
+      if (array && key === 'length') continue;
+      const descriptor = Object.getOwnPropertyDescriptor(v, key)!;
+      if (typeof key !== 'string' || !descriptor.enumerable || !('value' in descriptor) ||
+          (array && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= v.length))) throw new Error('rpc_invalid_json');
+      visit(descriptor.value);
+    }
+    seen.delete(v);
+  }
+  visit(value);
+  const json = JSON.stringify(value);
+  if (new TextEncoder().encode(json).length > MAX_BYTES) throw new Error('rpc_message_too_large');
+  return JSON.parse(json) as T;
+}
+
+/** Register in activate, then push the returned disposable into context.subscriptions.
+ * Requests only reach this plugin's worker; this is not a cross-plugin service API.
+ */
+export function defineWorkerApi<T extends { [K in keyof T]: Handler }>(handlers: T, options: Pick<RpcOptions, 'transport'> = {}): Disposable {
+  for (const name of ['then', '$dispose']) {
+    if (Object.hasOwn(handlers, name)) throw new Error(`rpc_reserved_method: ${name}`);
+  }
+  const transport = options.transport ?? channel;
+  const active = new Set<string>();
+  let stopped = false;
+  const respond = (p: Packet) => {
+    if (stopped) return;
+    const message = checked(p);
+    void Promise.resolve().then(() => { if (!stopped) return transport.post(message); }).catch(() => {});
+  };
+  const off = transport.onMessage(message => {
+    if (stopped || !packet(message) || message.kind !== 'request') return;
+    const key = JSON.stringify([message.client, message.id]);
+    if (active.has(key)) return;
+    const reply = { protocol: PROTOCOL, client: message.client, id: message.id } as const;
+    if (active.size >= MAX_PENDING) { respond({ ...reply, kind: 'error', error: 'rpc_busy' }); return; }
+    if (typeof message.method !== 'string' || !Object.hasOwn(handlers, message.method) || typeof handlers[message.method as keyof T] !== 'function' || !Array.isArray(message.args)) {
+      respond({ ...reply, kind: 'error', error: 'rpc_method_not_found' }); return;
+    }
+    active.add(key);
+    void Promise.resolve().then(() => {
+      if (stopped) return;
+      const request = checked(message);
+      return handlers[request.method as keyof T](...request.args!);
+    }).then(value => {
+      respond({ ...reply, kind: 'result', value: checked(value === undefined ? null : value) });
+    }).catch(error => {
+      let detail = 'rpc_failed';
+      try { detail = String(error instanceof Error ? error.message : error).slice(0, 1000); } catch {}
+      respond({ ...reply, kind: 'error', error: detail });
+    }).finally(() => active.delete(key));
+  });
+  return { dispose() { stopped = true; off(); active.clear(); } };
+}
+
+/** Create once per window, dispose on unmount. Timeout/disposal cancels waiting,
+ * not a worker side effect that already started. All arguments/results are JSON.
+ */
+export function useWorkerApi<T>(options: RpcOptions = {}): WorkerApiClient<T> {
+  const transport = options.transport ?? channel;
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 300_000) throw new Error('rpc_invalid_timeout');
+  const client = globalThis.crypto.randomUUID();
+  let sequence = 0, stopped = false;
+  const pending = new Map<string, { resolve(value: unknown): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }>();
+  const settle = (id: string, value: unknown, error?: string) => {
+    const request = pending.get(id); if (!request) return;
+    pending.delete(id); clearTimeout(request.timer);
+    if (error !== undefined) request.reject(new Error(error)); else request.resolve(value);
+  };
+  const off = transport.onMessage(message => {
+    if (!packet(message) || message.client !== client || message.kind === 'request') return;
+    try {
+      const response = checked(message);
+      if (response.kind === 'error') settle(response.id, null, typeof response.error === 'string' ? response.error : 'rpc_failed');
+      else settle(response.id, checked(response.value));
+    } catch (error) { settle(message.id, null, error instanceof Error ? error.message : 'rpc_invalid_json'); }
+  });
+  const dispose = () => {
+    if (stopped) return;
+    stopped = true; off(); options.signal?.removeEventListener('abort', dispose);
+    for (const id of pending.keys()) settle(id, null, 'rpc_disposed');
+  };
+  options.signal?.addEventListener('abort', dispose, { once: true });
+  if (options.signal?.aborted) dispose();
+  return new Proxy(Object.create(null), {
+    get(_target, method) {
+      if (method === '$dispose') return dispose;
+      if (method === 'then' || typeof method !== 'string') return undefined;
+      return (...args: unknown[]) => {
+        if (stopped) return Promise.reject(new Error('rpc_disposed'));
+        if (pending.size >= MAX_PENDING) return Promise.reject(new Error('rpc_busy'));
+        const id = String(++sequence);
+        let message: Packet;
+        try { message = checked({ protocol: PROTOCOL, kind: 'request', client, id, method, args }); }
+        catch (error) { return Promise.reject(error); }
+        return new Promise((resolve, reject) => {
+          const timer = setTimeout(() => settle(id, null, 'rpc_timeout'), timeoutMs);
+          pending.set(id, { resolve, reject, timer });
+          void Promise.resolve().then(() => {
+            if (!stopped && pending.has(id)) return transport.post(message);
+          }).catch(error => settle(id, null, error instanceof Error ? error.message : 'rpc_send_failed'));
+        });
+      };
+    },
+  }) as WorkerApiClient<T>;
+}

package/src/testing.ts

@@ -0,0 +1,144 @@
+import type { PluginAPI, PluginContext, PlatformEvent, PluginLocaleState } from './index.ts';
+import { METHODS } from './registry.ts';
+
+export type FakeHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
+type CommandHandler = Parameters<PluginContext['commands']['register']>[1];
+export interface FakeHostOptions {
+  storage?: Record<string, unknown>;
+  /** Declared configuration keys and their initial/default values. */
+  config?: Record<string, unknown>;
+  handlers?: Record<string, FakeHandler>;
+  commands?: Record<string, CommandHandler>;
+}
+
+// Preserve descriptors as well as values, including an originally absent global.
+// Removed nested installations are skipped so out-of-order cleanup cannot revive one.
+type Installation = { api: PluginAPI; previous?: PropertyDescriptor; removed: boolean };
+const installations: Installation[] = [];
+function installAPI(api: PluginAPI): () => void {
+  const entry: Installation = { api, previous: Object.getOwnPropertyDescriptor(globalThis, 'medeoPlugin'), removed: false };
+  Object.defineProperty(globalThis, 'medeoPlugin', { configurable: true, writable: true, value: api });
+  installations.push(entry);
+  return () => {
+    if (entry.removed) return;
+    entry.removed = true;
+    while (installations.at(-1)?.removed) {
+      const top = installations.pop()!;
+      // Never overwrite a bridge installed by unrelated test code.
+      if (Object.getOwnPropertyDescriptor(globalThis, 'medeoPlugin')?.value !== top.api) continue;
+      if (top.previous) Object.defineProperty(globalThis, 'medeoPlugin', top.previous);
+      else Reflect.deleteProperty(globalThis, 'medeoPlugin');
+    }
+  };
+}
+
+/** Offline bridge for real SDK calls. No OS, permissions, persistence or manifest
+ * validation is simulated. Channel messages loop back to this host's listeners.
+ * Install only within a serial test scope (globals cannot isolate concurrent tests).
+ * Every unimplemented capability fails unless supplied in `handlers`.
+ */
+export function createFakeHost(options: FakeHostOptions = {}) {
+  const clone = <T>(value: T): T => structuredClone(value);
+  const storage = new Map(Object.entries(clone(options.storage ?? {})));
+  const config = new Map(Object.entries(clone(options.config ?? {})));
+  const handlers = new Map(Object.entries(options.handlers ?? {}));
+  const commands = new Map<string, CommandHandler>();
+  const messages = new Set<(message: unknown) => void>();
+  const events = new Set<(event: PlatformEvent) => void>();
+  const locales = new Set<(state: PluginLocaleState) => void>();
+  const restores = new Set<() => void>();
+  let disposed = false;
+  const assertActive = () => { if (disposed) throw new Error('fake_host_disposed'); };
+  const subscribe = <T>(listeners: Set<(value: T) => void>, callback: (value: T) => void) => {
+    assertActive(); listeners.add(callback); return () => { listeners.delete(callback); };
+  };
+  const emit = <T>(listeners: Set<(value: T) => void>, value: T) => {
+    assertActive(); for (const listener of [...listeners]) listener(clone(value));
+  };
+  const key = (args: Record<string, unknown>) => {
+    if (typeof args.key !== 'string') throw new Error('invalid_key');
+    return args.key;
+  };
+  const builtins: Record<string, FakeHandler> = {
+    'storage.get': args => clone(storage.get(key(args)) ?? null),
+    'storage.set': args => { storage.set(key(args), clone(args.value)); return null; },
+    'storage.remove': args => { storage.delete(key(args)); return null; },
+    'config.get': args => {
+      if (args.key === undefined) return Object.fromEntries(config);
+      const name = key(args);
+      if (!config.has(name)) throw new Error(`unknown_configuration: ${name}`);
+      return config.get(name);
+    },
+    'config.set': args => {
+      const name = key(args);
+      if (!config.has(name)) throw new Error(`unknown_configuration: ${name}`);
+      config.set(name, clone(args.value));
+      emit(events, { type: 'signal', channel: 'config' });
+      return null;
+    },
+  };
+  const api: PluginAPI = {
+    async invoke(method, args = {}) {
+      assertActive();
+      const handler = handlers.get(method) ?? (Object.hasOwn(builtins, method) ? builtins[method] : undefined);
+      if (!handler) throw new Error(`${Object.hasOwn(METHODS, method) ? 'unimplemented_method' : 'unknown_method'}: ${method}`);
+      return clone(await handler(clone(args)));
+    },
+    async run(command, args) {
+      assertActive();
+      const handler = commands.get(command);
+      if (!handler) throw new Error(`unregistered_command: ${command}`);
+      return clone(await handler(clone(args)));
+    },
+    async post(message) { emit(messages, message); },
+    onMessage: callback => subscribe(messages, callback),
+    onEvent: callback => subscribe(events, callback),
+    onLocaleChanged: callback => subscribe(locales, callback),
+  };
+  const context: PluginContext = {
+    subscriptions: [],
+    commands: {
+      register(id, handler) {
+        assertActive();
+        if (commands.has(id)) throw new Error(`duplicate_command: ${id}`);
+        commands.set(id, handler);
+        const disposable = { dispose() { if (commands.get(id) === handler) commands.delete(id); } };
+        context.subscriptions.push(disposable);
+        return disposable;
+      },
+    },
+  };
+  for (const [id, handler] of Object.entries(options.commands ?? {})) context.commands.register(id, handler);
+  return {
+    api, context,
+    /** Explicit installation: importing this module never changes the global. */
+    install() {
+      assertActive();
+      const restore = installAPI(api);
+      const off = () => { restore(); restores.delete(off); };
+      restores.add(off);
+      return off;
+    },
+    emitEvent: (event: PlatformEvent) => emit(events, event),
+    emitMessage: (message: unknown) => emit(messages, message),
+    emitLocaleChanged: (state: PluginLocaleState) => emit(locales, state),
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const restore of [...restores].reverse()) restore();
+      messages.clear(); events.clear(); locales.clear(); commands.clear();
+      const errors: unknown[] = [];
+      for (const subscription of context.subscriptions.splice(0).reverse()) {
+        try { await subscription.dispose(); } catch (error) { errors.push(error); }
+      }
+      if (errors.length) throw new AggregateError(errors, 'fake_host_cleanup_failed');
+    },
+  };
+}
+
+/** Installs a bridge for a callback and restores it even when the callback throws. */
+export async function withFakeHost<T>(options: FakeHostOptions, run: (host: ReturnType<typeof createFakeHost>) => T | Promise<T>): Promise<T> {
+  const host = createFakeHost(options);
+  host.install();
+  try { return await run(host); } finally { await host.dispose(); }
+}

package/src/ui/styles.ts

@@ -0,0 +1,31 @@
+/** Layout only: colors, type and dimensions remain owned by /_medeo/theme.css. */
+export const uiStyles = `
+.medeo-ui{font-family:var(--font-family-plain);color:var(--color-surface-on-surface);font-size:var(--type-label-large-size);line-height:var(--type-label-large-leading)}
+.medeo-card{padding:var(--space-s5);border:1px solid var(--color-surface-outline-variant);border-radius:var(--shape-radius-16);background:var(--color-surface-surface-container-lowest);display:grid;gap:var(--space-s3)}
+.medeo-card h2,.medeo-empty h2{margin:0;font-size:var(--type-title-medium-size);line-height:var(--type-title-medium-leading);font-weight:var(--type-title-medium-weight);letter-spacing:var(--type-title-medium-tracking)}
+.medeo-description{margin:0;color:var(--color-surface-on-surface-variant)}
+.medeo-pill{display:inline-flex;align-items:center;justify-self:start;padding:var(--space-s1) var(--space-s3);border-radius:var(--shape-radius-full);background:var(--medeo-selected);font-size:var(--type-label-medium-size);line-height:var(--type-label-medium-leading);font-weight:var(--type-label-medium-prominent-weight)}
+.medeo-pill[data-tone=error]{color:var(--color-schemes-error);background:var(--medeo-error-wash)}
+.medeo-pill[data-tone=neutral]{background:var(--medeo-hover)}
+.medeo-toggle{display:inline-flex;align-items:center;gap:var(--space-s2);min-height:var(--space-s8);cursor:pointer}
+.medeo-toggle input{width:var(--space-s4);height:var(--space-s4);accent-color:var(--color-schemes-primary)}
+.medeo-toggle:has(input:disabled){opacity:.45;cursor:default}
+.medeo-segmented{display:flex;flex-wrap:wrap;gap:var(--space-s1);padding:var(--space-s1);border:1px solid var(--color-surface-outline-variant);border-radius:var(--shape-radius-12)}
+.medeo-segmented button{font:inherit;color:inherit;border:0;border-radius:var(--shape-radius-8);background:transparent;min-height:var(--space-s8);padding:var(--space-s2) var(--space-s3);cursor:pointer}
+.medeo-segmented button[aria-checked=true]{background:var(--color-schemes-primary);color:var(--color-schemes-on-primary)}
+.medeo-segmented button:hover:not(:disabled):not([aria-checked=true]){background:var(--medeo-hover)}
+.medeo-segmented button:disabled{opacity:.45;cursor:default}
+.medeo-ui :focus-visible{outline:2px solid var(--color-schemes-primary);outline-offset:2px}
+.medeo-list{list-style:none;margin:0;padding:0;display:grid;gap:var(--space-s2)}
+.medeo-list>li{padding:var(--space-s3);border-bottom:1px solid var(--color-surface-outline-variant)}
+.medeo-empty{display:grid;gap:var(--space-s2);padding:var(--space-s7);text-align:center;border:1px dashed var(--color-surface-outline);border-radius:var(--shape-radius-12)}
+`;
+
+/** Explicit and idempotent; importing this module has no DOM side effects. */
+export function installStyles(doc: Document = document): void {
+  if (doc.querySelector('style[data-medeo-ui]')) return;
+  const style = doc.createElement('style');
+  style.dataset.medeoUi = '';
+  style.textContent = uiStyles;
+  doc.head.append(style);
+}