@medeo-plugin/sdk 0.7.0 → 0.9.0

package/dist/rpc.js

@@ -0,0 +1,172 @@
+import { channel } from "./index.js";
+const PROTOCOL = 'medeo.rpc.v1';
+const MAX_PENDING = 64;
+const MAX_BYTES = 60 * 1024;
+function packet(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const p = value;
+    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(value) {
+    const seen = new Set();
+    function visit(v) {
+        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);
+}
+/** 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(handlers, options = {}) {
+    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();
+    let stopped = false;
+    const respond = (p) => {
+        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 };
+        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] !== '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](...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(options = {}) {
+    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();
+    const settle = (id, value, error) => {
+        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) => {
+                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;
+                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'));
+                });
+            };
+        },
+    });
+}

package/dist/testing.d.ts

@@ -0,0 +1,28 @@
+import type { PluginAPI, PluginContext, PlatformEvent, PluginLocaleState } from './index.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>;
+}
+/** 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 declare function createFakeHost(options?: FakeHostOptions): {
+    api: PluginAPI;
+    context: PluginContext;
+    /** Explicit installation: importing this module never changes the global. */
+    install(): () => void;
+    emitEvent: (event: PlatformEvent) => void;
+    emitMessage: (message: unknown) => void;
+    emitLocaleChanged: (state: PluginLocaleState) => void;
+    dispose(): Promise<void>;
+};
+/** Installs a bridge for a callback and restores it even when the callback throws. */
+export declare function withFakeHost<T>(options: FakeHostOptions, run: (host: ReturnType<typeof createFakeHost>) => T | Promise<T>): Promise<T>;
+export {};

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.9.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/generated.ts

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