@medeo-plugin/sdk 0.7.0 → 0.8.0

package/dist/index.d.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;
@@ -57,7 +57,7 @@ export declare const creation: {
     open: () => Promise<unknown>;
 };
 export declare const commands: {
-    run: (command: string) => Promise<unknown>;
+    run: <T = unknown>(command: string, args?: JsonValue) => Promise<T>;
 };
 export interface Disposable {
     dispose(): unknown;
@@ -68,7 +68,7 @@ export interface PluginContext {
     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;
+        register(id: string, handler: (args?: JsonValue) => unknown | Promise<unknown>): Disposable;
     };
     /** `runtime: "node"` only: the installed, verified package directory (read-only). */
     extensionPath?: string;
@@ -435,6 +435,7 @@ export interface NetworkRequest {
     body?: string;
     body_base64?: string;
     timeout_ms?: number;
+    stream?: boolean;
 }
 export interface NetworkJob {
     id: string;
@@ -443,6 +444,7 @@ export interface NetworkJob {
     http_status?: number | null;
     headers?: [string, string][];
     error?: string | null;
+    stream?: boolean;
 }
 export interface NetworkChunk {
     data_base64: string;
@@ -454,6 +456,12 @@ export interface NetworkOrigin {
     declared: boolean;
     allowed: boolean;
 }
+export interface NetworkServerEvent {
+    data: string;
+    event: string;
+    id: string;
+    retry?: number;
+}
 export declare const network: {
     origins: () => Promise<NetworkOrigin[]>;
     requestOrigin: (origin: string, reason: string) => Promise<{
@@ -470,6 +478,14 @@ export declare const network: {
     }>;
     /** Resolves once the response has fully arrived; the job stays readable until released. */
     settled(id: string): Promise<NetworkJob>;
+    /** Single consumer for a stream:true job. Break/throw/abort cancels and releases it. */
+    bytes(id: string, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
+    /** Incremental UTF-8 decoder, including code points split across HTTP chunks. */
+    textStream(id: string, signal?: AbortSignal): AsyncGenerator<string>;
+    /** SSE framing only: no automatic reconnect/retry or Last-Event-ID requests. */
+    sse(id: string, signal?: AbortSignal): AsyncGenerator<NetworkServerEvent>;
+    /** Explicitly dispose a stream that was never iterated (or has another owner). */
+    dispose(id: string): Promise<void>;
     text(id: string): Promise<string>;
 };
 /** Workspace operations use current directory references and asynchronous jobs. */

package/dist/index.js

@@ -39,7 +39,7 @@ export const storage = {
     set: (key, value) => globalThis.medeoPlugin.invoke('storage.set', { key, value }),
 };
 export const creation = { open: () => globalThis.medeoPlugin.invoke('creation.open') };
-export const commands = { run: (command) => globalThis.medeoPlugin.run(command) };
+export const commands = { run: (command, args) => globalThis.medeoPlugin.run(command, args) };
 export function definePlugin(definition) {
     return { deactivate: () => undefined, ...definition };
 }
@@ -168,6 +168,121 @@ export const network = {
         await change.promise;
         change.off();
     } },
+    /** Single consumer for a stream:true job. Break/throw/abort cancels and releases it. */
+    async *bytes(id, signal) {
+        let offset = 0;
+        let abortCleanup;
+        const abort = () => { abortCleanup = network.dispose(id); void abortCleanup.catch(() => { }); };
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+            for (;;) {
+                let wake;
+                const changed = new Promise(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, signal) {
+        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, signal) {
+        let pending = '', data = [], event = '', lastId = '', retry, 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) {
+        const ignoreMissing = (error) => { 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) {
         const decoder = new TextDecoder();
         let offset = 0, text = '';

package/dist/react.d.ts

@@ -0,0 +1,46 @@
+/** React is only imported by the optional @medeo-plugin/sdk/ui/react entry. */
+import { type ReactNode } from 'react';
+import { type CardOptions, type PillOptions, type ToggleOptions, type SegmentedOptions, type ListOptions } from './ui.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 declare function useUIStyles(): void;
+export declare function Card({ title, description, testid, children }: CardOptions & {
+    children?: ReactNode;
+}): import("react").DetailedReactHTMLElement<{
+    className: string;
+    'data-testid': string;
+    'aria-label': string;
+}, HTMLElement>;
+export declare function Pill({ label, tone, testid }: PillOptions): import("react").DetailedReactHTMLElement<{
+    className: string;
+    'data-testid': string;
+    'data-tone': "error" | "neutral" | "info";
+}, HTMLElement>;
+/** Controlled: update checked in onChange. Native input supplies name and Space handling. */
+export declare function Toggle({ label, checked, disabled, onChange, testid }: ToggleOptions): import("react").DetailedReactHTMLElement<{
+    className: string;
+    'data-testid': string;
+}, HTMLElement>;
+/** Controlled radio group with a single tab stop and arrow/Home/End navigation. */
+export declare function Segmented<T extends string>({ label, value, options, disabled, onChange, testid }: SegmentedOptions<T>): import("react").DetailedReactHTMLElement<{
+    className: string;
+    role: "radiogroup";
+    'aria-label': string;
+    'data-testid': string;
+}, HTMLElement>;
+export declare function List({ label, testid, items }: ListOptions & {
+    items: readonly {
+        key: string;
+        content: ReactNode;
+    }[];
+}): import("react").DetailedReactHTMLElement<{
+    className: string;
+    'data-testid': string;
+    'aria-label': string;
+}, HTMLElement>;
+export declare function EmptyState({ title, description, testid }: CardOptions): import("react").DetailedReactHTMLElement<{
+    className: string;
+    'data-testid': string;
+    'aria-label': string;
+}, HTMLElement>;

package/dist/react.js

@@ -0,0 +1,44 @@
+/** React is only imported by the optional @medeo-plugin/sdk/ui/react entry. */
+import { createElement as h, useEffect } from 'react';
+import { segmentTarget, segmentTabIndex } from './ui.js';
+import { installStyles } from './ui/styles.js';
+export { uiStyles, installStyles } from './ui/styles.js';
+/** Call once near your root. SSR-safe; style installation is idempotent. */
+export function useUIStyles() { useEffect(() => { installStyles(); }, []); }
+export function Card({ title, description, testid, children }) {
+    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 }) {
+    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 }) {
+    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) => onChange(event.currentTarget.checked) }), h('span', null, label));
+}
+/** Controlled radio group with a single tab stop and arrow/Home/End navigation. */
+export function Segmented({ label, value, options, disabled, onChange, testid }) {
+    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) => {
+            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].focus();
+            onChange(options[target].value);
+        },
+    }, option.label)));
+}
+export function List({ label, testid, items }) {
+    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 }) {
+    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/dist/rpc.d.ts

@@ -0,0 +1,28 @@
+import { 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;
+};
+/** 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 declare function defineWorkerApi<T extends {
+    [K in keyof T]: Handler;
+}>(handlers: T, options?: Pick<RpcOptions, 'transport'>): Disposable;
+/** 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 declare function useWorkerApi<T>(options?: RpcOptions): WorkerApiClient<T>;
+export {};

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 {};