@medeo-plugin/sdk 0.0.0-stage → 0.8.0

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,68 @@
 {
   "name": "@medeo-plugin/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/one2x-ai/medeo-desktop-plugin-sdk.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "homepage": "https://github.com/one2x-ai/medeo-desktop-plugin-sdk#readme",
+  "keywords": [
+    "medeo",
+    "plugin",
+    "sdk"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "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",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "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

@@ -0,0 +1,158 @@
+// 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 PluginCommand = { id: string, title: string, };
+export type PluginLocalization = { default_locale: string, catalogs: { [key in string]?: string }, };
+export type Runtime = "sandbox" | "node";
+export type GrantScope = "once" | "run" | "always";
+export type ApprovalRule = { action: string, 
+/**
+ * The rule key, or a prefix ending in `*`.
+ */
+pattern: string, allow: boolean, 
+/**
+ * `run` rules belong to the running instance; `always` rules are stored.
+ */
+scope: GrantScope, };
+export type ApprovalRecord = { action: string, rule_key: string, 
+/**
+ * `allow` or `deny`.
+ */
+decision: string, 
+/**
+ * `once`, `run`, `always`, or `rule` when a remembered rule decided.
+ */
+scope: string, time_ms: number, };
+export type TargetPlatform = "macos" | "windows";
+export type Engines = { medeo?: string, };
+export type InstallSourceKind = "file" | "folder" | "github" | "npm" | "dev";
+export type InstallSource = { kind: InstallSourceKind, 
+/**
+ * A file path, folder path, `owner/repo[#tag-prefix]` or npm package name.
+ */
+locator: string, 
+/**
+ * The release tag or npm version the package was taken from.
+ */
+version?: string, };
+export type ConfigType = "string" | "number" | "boolean";
+export type ConfigProperty = { type: ConfigType, default: JsonValue, title: string, description?: string, 
+/**
+ * Allowed values; the plugin center shows a choice.
+ */
+enum?: Array<JsonValue>, };
+export type Configuration = { properties: { [key in string]?: ConfigProperty }, };
+export type Keybinding = { command: string, key: string, };
+export type Menus = { 
+/**
+ * Command ids shown in the main window's Plugins menu.
+ */
+app?: Array<string>, };
+export type Contributes = { configuration?: Configuration, keybindings?: Array<Keybinding>, menus?: Menus, };
+export type Manifest = { localization?: PluginLocalization, id: string, name: string, 
+/**
+ * One sentence the plugin center shows under the name; translated as
+ * `plugin.description` in the plugin's catalogs.
+ */
+description?: string, 
+/**
+ * The plugin's icon, at the package root: `icon.svg` or `icon.png`.
+ */
+icon?: string, version: string, api_version: number, worker: string, ui: string | null, permissions: Array<Permission>, commands: Array<PluginCommand>, runtime?: Runtime, 
+/**
+ * When Medeo starts the plugin: `onStartup`, `onCommand:<id>`,
+ * `onSchedule`, `onShortcut`. Without any, it starts when used.
+ */
+activation_events?: Array<string>, contributes?: Contributes, 
+/**
+ * Operating systems the plugin runs on; empty means all.
+ */
+platforms?: Array<TargetPlatform>, 
+/**
+ * The Medeo versions the plugin needs; absent means any that loads format 2.
+ */
+engines?: Engines, };
+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 PackageInfo = { manifest: Manifest, digest: string, publisher: string, 
+/**
+ * Bytes of all signed files, i.e. the installed size. Records written
+ * before this field existed are backfilled at start.
+ */
+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>, };
+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, 
+/**
+ * Full access: view and move to the Trash without a Host confirmation.
+ */
+full: boolean, };
+export type NetworkOrigin = { origin: string, declared: boolean, allowed: boolean, };
+export type InstalledPlugin = { localization: JsonValue, id: string, active: string | null, versions: Array<PackageInfo>, grants: Array<Permission>, directories: Array<DirectoryGrant>, network_origins: Array<NetworkOrigin>, 
+/**
+ * For resident (`onStartup`) plugins: whether the user lets it run in
+ * the background. Other plugins run only while in use and ignore it.
+ */
+enabled: boolean, resident: boolean, 
+/**
+ * User-owned macOS Dock launcher preference; plugins cannot modify it.
+ */
+dock: boolean, 
+/**
+ * User-owned: whether the plugin's menu-bar icon (`tray`) is shown; plugins cannot modify it.
+ */
+menu_bar: boolean, instance: string | null, 
+/**
+ * Permission ids granted to the running instance only (`run` scope).
+ */
+session_grants: Array<string>, 
+/**
+ * Permission ids the user refused with "don't ask again".
+ */
+denied: Array<string>, 
+/**
+ * Remembered `approvals.request` answers.
+ */
+approval_rules: Array<ApprovalRule>, 
+/**
+ * The active version's icon as a `data:` URL, when the package has one.
+ */
+icon?: string, 
+/**
+ * Where the plugin was installed from, when Main recorded it.
+ */
+source?: InstallSource, };
+export type Instance = { id: string, plugin_id: string, digest: string, manifest: Manifest, };
+export type Task = { id: string, plugin_id: string, instance: string, command: string, status: string, result: JsonValue | null, 
+/**
+ * Unix milliseconds; absent for rows written before times were recorded.
+ */
+created_ms: number | null, finished_ms: number | null, };
+export type Snapshot = { protocol: number, plugins: Array<InstalledPlugin>, tasks: Array<Task>, };
+export type HostEvent = { "type": "operation", instance: string, id: string, method: string, status: string, revision?: number, } | { "type": "signal", instance: string, channel: string, } | { "type": "wake", plugin_id: string, };
+export type Command = { "op": "ping" } | { "op": "shortcuts_list" } | { "op": "shortcut_validate", target: string, accelerator: string, } | { "op": "shortcut_save", target: string, accelerator: string, } | { "op": "shortcut_remove", target: string, } | { "op": "system_locale", locale: string, } | { "op": "plugin_locale", plugin_id: string, locale: string, } | { "op": "approve", instance: string, ticket: string, approved: boolean, 
+/**
+ * Without it an approval is stored (`always`) and a refusal asks again next time.
+ */
+scope?: GrantScope, } | { "op": "capture_stop", id: string, } | { "op": "capture_asset", instance: string, id: string, } | { "op": "media_asset", instance: string, id: string, } | { "op": "agent_settings" } | { "op": "agent_configure", endpoint: string, model: string, encrypted_key: string | null, key: string, persist: boolean, } | { "op": "agent_remove" } | { "op": "agent_test", action: string, id: string | null, } | { "op": "snapshot" } | { "op": "capability_catalog" } | { "op": "grant_permission", plugin_id: string, digest: string, permission: string, } | { "op": "forget_approval_rule", plugin_id: string, action: string, pattern: string, } | { "op": "approval_log", plugin_id: string, } | { "op": "revoke_permission", plugin_id: string, permission: string, } | { "op": "network_origin_revoke", plugin_id: string, origin: string, } | { "op": "configure_capabilities", methods: Array<string>, } | { "op": "capability_result", instance: string, ticket: string, result: JsonValue | null, error: string | null, } | { "op": "quiesce", plugin_id: string, } | { "op": "resource_grant", instance: string, directories: Array<string>, full: boolean, } | { "op": "resource_revoke", plugin_id: string, grant_id: string, } | { "op": "inspect", package_file: string, } | { "op": "install", package_file: string, digest: string, grants: Array<Permission>, 
+/**
+ * Recorded with the plugin (plugin center "Source"); absent for older callers.
+ */
+source?: InstallSource, } | { "op": "pack_dir", directory: string, key_file: string, output: string, 
+/**
+ * Stamp a content-derived `-dev.h<hash>` version like the toolchain's `dev` does.
+ */
+development: boolean, } | { "op": "prepare", plugin_id: string, digest: string, } | { "op": "commit", instance: string, } | { "op": "abort", instance: string, } | { "op": "stop", plugin_id: string, } | { "op": "busy", plugin_id: string, } | { "op": "deactivate", plugin_id: string, } | { "op": "dock_set", plugin_id: string, enabled: boolean, } | { "op": "menu_bar_set", plugin_id: string, enabled: boolean, } | { "op": "keep_running", plugin_id: string, enabled: boolean, } | { "op": "uninstall", plugin_id: string, } | { "op": "config_state", plugin_id: string, } | { "op": "config_set", plugin_id: string, key: string, value: JsonValue, } | { "op": "package_dir", instance: string, } | { "op": "remove_version", plugin_id: string, digest: string, } | { "op": "grants", plugin_id: string, grants: Array<Permission>, } | { "op": "asset", instance: string, path: string, } | { "op": "invoke", instance: string, method: string, args: JsonValue, 
+/**
+ * Main sets this when the caller is one of the plugin's windows rather
+ * than its background worker; `ui` methods require it.
+ */
+ui?: boolean, } | { "op": "task_start", instance: string, command: string, } | { "op": "task_finish", instance: string, task: string, result: JsonValue | null, failed: boolean, } | { "op": "labels", locale: string, };
+export type Request = { version: number, id: number, command: Command, };
+export type Response = { id: number, result: JsonValue | null, error: string | null, };