@medeo-plugin/sdk 0.7.0 → 0.8.0

package/dist/testing.js

@@ -0,0 +1,161 @@
+import { METHODS } from "./registry.js";
+const installations = [];
+function installAPI(api) {
+    const entry = { 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 = {}) {
+    const clone = (value) => 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();
+    const messages = new Set();
+    const events = new Set();
+    const locales = new Set();
+    const restores = new Set();
+    let disposed = false;
+    const assertActive = () => { if (disposed)
+        throw new Error('fake_host_disposed'); };
+    const subscribe = (listeners, callback) => {
+        assertActive();
+        listeners.add(callback);
+        return () => { listeners.delete(callback); };
+    };
+    const emit = (listeners, value) => {
+        assertActive();
+        for (const listener of [...listeners])
+            listener(clone(value));
+    };
+    const key = (args) => {
+        if (typeof args.key !== 'string')
+            throw new Error('invalid_key');
+        return args.key;
+    };
+    const builtins = {
+        '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 = {
+        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 = {
+        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) => emit(events, event),
+        emitMessage: (message) => emit(messages, message),
+        emitLocaleChanged: (state) => 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 = [];
+            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(options, run) {
+    const host = createFakeHost(options);
+    host.install();
+    try {
+        return await run(host);
+    }
+    finally {
+        await host.dispose();
+    }
+}

package/dist/ui/styles.d.ts

@@ -0,0 +1,4 @@
+/** Layout only: colors, type and dimensions remain owned by /_medeo/theme.css. */
+export declare const uiStyles = "\n.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)}\n.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)}\n.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)}\n.medeo-description{margin:0;color:var(--color-surface-on-surface-variant)}\n.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)}\n.medeo-pill[data-tone=error]{color:var(--color-schemes-error);background:var(--medeo-error-wash)}\n.medeo-pill[data-tone=neutral]{background:var(--medeo-hover)}\n.medeo-toggle{display:inline-flex;align-items:center;gap:var(--space-s2);min-height:var(--space-s8);cursor:pointer}\n.medeo-toggle input{width:var(--space-s4);height:var(--space-s4);accent-color:var(--color-schemes-primary)}\n.medeo-toggle:has(input:disabled){opacity:.45;cursor:default}\n.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)}\n.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}\n.medeo-segmented button[aria-checked=true]{background:var(--color-schemes-primary);color:var(--color-schemes-on-primary)}\n.medeo-segmented button:hover:not(:disabled):not([aria-checked=true]){background:var(--medeo-hover)}\n.medeo-segmented button:disabled{opacity:.45;cursor:default}\n.medeo-ui :focus-visible{outline:2px solid var(--color-schemes-primary);outline-offset:2px}\n.medeo-list{list-style:none;margin:0;padding:0;display:grid;gap:var(--space-s2)}\n.medeo-list>li{padding:var(--space-s3);border-bottom:1px solid var(--color-surface-outline-variant)}\n.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)}\n";
+/** Explicit and idempotent; importing this module has no DOM side effects. */
+export declare function installStyles(doc?: Document): void;

package/dist/ui/styles.js

@@ -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) {
+    if (doc.querySelector('style[data-medeo-ui]'))
+        return;
+    const style = doc.createElement('style');
+    style.dataset.medeoUi = '';
+    style.textContent = uiStyles;
+    doc.head.append(style);
+}

package/dist/ui.d.ts

@@ -0,0 +1,50 @@
+export { installStyles, uiStyles } from './ui/styles.js';
+export interface Identified {
+    testid: string;
+}
+export interface CardOptions extends Identified {
+    title: string;
+    description?: string;
+}
+export interface PillOptions extends Identified {
+    label: string;
+    tone?: 'neutral' | 'info' | 'error';
+}
+export interface ToggleOptions extends Identified {
+    label: string;
+    checked: boolean;
+    disabled?: boolean;
+    onChange: (checked: boolean) => void;
+}
+export interface Segment<T extends string = string> {
+    value: T;
+    label: string;
+    disabled?: boolean;
+}
+export interface SegmentedOptions<T extends string = string> extends Identified {
+    label: string;
+    options: readonly Segment<T>[];
+    value: T;
+    disabled?: boolean;
+    onChange: (value: T) => void;
+}
+export interface ListOptions extends Identified {
+    label: string;
+}
+export type Child = Node | string | number | null | undefined | false;
+export declare function card(options: CardOptions, ...children: Child[]): HTMLElement;
+export declare function pill(options: PillOptions): HTMLSpanElement;
+/** Native checkbox keyboard behavior (Space), with switch semantics. */
+export declare function toggle(options: ToggleOptions): HTMLLabelElement & {
+    input: HTMLInputElement;
+};
+/** Shared radio keyboard navigation; disabled choices are skipped, edges wrap. */
+export declare function segmentTarget<T extends string>(options: readonly Segment<T>[], index: number, key: string, rtl?: boolean): number | undefined;
+export declare function segmentTabIndex<T extends string>(options: readonly Segment<T>[], value: T, index: number): number;
+export declare function segmented<T extends string>(options: SegmentedOptions<T>): HTMLDivElement & {
+    setValue(value: T): void;
+    setDisabled(disabled: boolean): void;
+};
+/** Each child becomes one semantic list item; caller owns empty-state wording. */
+export declare function list(options: ListOptions, ...items: Child[]): HTMLUListElement;
+export declare function emptyState(options: CardOptions): HTMLElement;

package/dist/ui.js

@@ -0,0 +1,115 @@
+export { installStyles, uiStyles } from './ui/styles.js';
+function node(tag, className, testid, text) {
+    const el = document.createElement(tag);
+    el.className = className;
+    if (testid !== undefined)
+        el.dataset.testid = testid;
+    if (text !== undefined)
+        el.textContent = text;
+    return el;
+}
+function append(el, children) {
+    for (const child of children)
+        if (child !== null && child !== undefined && child !== false)
+            el.append(typeof child === 'number' ? String(child) : child);
+}
+export function card(options, ...children) {
+    const root = node('section', 'medeo-ui medeo-card', options.testid);
+    root.setAttribute('aria-label', options.title);
+    root.append(node('h2', '', `${options.testid}.title`, options.title));
+    if (options.description !== undefined)
+        root.append(node('p', 'medeo-description', undefined, options.description));
+    append(root, children);
+    return root;
+}
+export function pill(options) {
+    const root = node('span', 'medeo-ui medeo-pill', options.testid, options.label);
+    root.dataset.tone = options.tone ?? 'info';
+    return root;
+}
+/** Native checkbox keyboard behavior (Space), with switch semantics. */
+export function toggle(options) {
+    const root = node('label', 'medeo-ui medeo-toggle', `${options.testid}.root`);
+    const input = node('input', '', options.testid);
+    input.type = 'checkbox';
+    input.setAttribute('role', 'switch');
+    input.checked = options.checked;
+    input.disabled = options.disabled ?? false;
+    input.addEventListener('change', () => options.onChange(input.checked));
+    root.append(input, node('span', '', undefined, options.label));
+    return Object.assign(root, { input });
+}
+/** Shared radio keyboard navigation; disabled choices are skipped, edges wrap. */
+export function segmentTarget(options, index, key, rtl = false) {
+    const enabled = options.map((o, i) => o.disabled ? -1 : i).filter(i => i >= 0);
+    if (!enabled.length)
+        return undefined;
+    if (key === 'Home')
+        return enabled[0];
+    if (key === 'End')
+        return enabled[enabled.length - 1];
+    let direction = key === 'ArrowDown' ? 1 : key === 'ArrowUp' ? -1 : key === 'ArrowRight' ? (rtl ? -1 : 1) : key === 'ArrowLeft' ? (rtl ? 1 : -1) : 0;
+    if (!direction)
+        return undefined;
+    return enabled[(enabled.indexOf(index) + direction + enabled.length) % enabled.length];
+}
+export function segmentTabIndex(options, value, index) {
+    let active = options.findIndex(o => o.value === value && !o.disabled);
+    if (active < 0)
+        active = options.findIndex(o => !o.disabled);
+    return index === active ? 0 : -1;
+}
+export function segmented(options) {
+    const root = node('div', 'medeo-ui medeo-segmented', options.testid);
+    root.setAttribute('role', 'radiogroup');
+    root.setAttribute('aria-label', options.label);
+    let value = options.value, disabled = options.disabled ?? false;
+    const buttons = options.options.map((option, index) => {
+        const button = node('button', '', `${options.testid}.${index}`, option.label);
+        button.type = 'button';
+        button.setAttribute('role', 'radio');
+        button.addEventListener('click', () => {
+            if (disabled || option.disabled)
+                return;
+            value = option.value;
+            render();
+            options.onChange(value);
+        });
+        button.addEventListener('keydown', event => {
+            if (disabled)
+                return;
+            const target = segmentTarget(options.options, index, event.key, getComputedStyle(root).direction === 'rtl');
+            if (target === undefined)
+                return;
+            event.preventDefault();
+            buttons[target].focus();
+            buttons[target].click();
+        });
+        return button;
+    });
+    function render() {
+        buttons.forEach((button, index) => {
+            button.disabled = disabled || !!options.options[index].disabled;
+            button.tabIndex = disabled ? -1 : segmentTabIndex(options.options, value, index);
+            button.setAttribute('aria-checked', String(options.options[index].value === value));
+        });
+    }
+    root.append(...buttons);
+    render();
+    return Object.assign(root, { setValue(next) { value = next; render(); }, setDisabled(next) { disabled = next; render(); } });
+}
+/** Each child becomes one semantic list item; caller owns empty-state wording. */
+export function list(options, ...items) {
+    const root = node('ul', 'medeo-ui medeo-list', options.testid);
+    root.setAttribute('aria-label', options.label);
+    items.forEach((item, index) => { const li = node('li', '', `${options.testid}.${index}`); append(li, [item]); root.append(li); });
+    return root;
+}
+export function emptyState(options) {
+    const root = node('section', 'medeo-ui medeo-empty', options.testid);
+    root.setAttribute('aria-label', options.title);
+    root.append(node('h2', '', undefined, options.title));
+    if (options.description !== undefined)
+        root.append(node('p', 'medeo-description', undefined, options.description));
+    return root;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medeo-plugin/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "TypeScript SDK for Medeo desktop plugins: one import for the sandboxed worker, its windows and Node plugins.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,26 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "import": "./dist/rpc.js",
+      "default": "./dist/rpc.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "import": "./dist/ui.js",
+      "default": "./dist/ui.js"
+    },
+    "./ui/react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
@@ -34,6 +54,14 @@
     "build": "tsc -p tsconfig.build.json",
     "prepack": "npm run build"
   },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22"
   }

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. */
@@ -229,10 +229,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 +245,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;}

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));
+}