@bardioc/app-sdk 0.4.11 → 1.0.0

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-export { createHostBridge } from './host-bridge.js';
+export type { GraphApi } from './api/graph.js';
+export type { OsApi } from './api/os.js';
+export type { RelayApi } from './api/relay.js';
+export { connect } from './client.js';
+export type { Bardioc } from './client.js';
+export { BardiocError } from './errors.js';
+export type { ErrorCode } from './errors.js';
+export type { AppRecord, AppUpload, BffRequest, Command, Context, GraphEvent, IdbEntry, InstalledApp, MenuItem, MenuRoot, NotifyLevel, OsConfig, Shortcut, UploadResult, } from './contract.js';
 export { DEFAULT_WINDOW_SIZE, MANIFEST_FILENAME, WINDOW_SIZES, validateManifest, } from './manifest.js';
-export type { AppManifest, AppManifestPermission, AppManifestWindowConfig, CustomWindowSize, WindowSizePreset, } from './manifest.js';
-export { SDK_CONTRACT_MATRIX, getRequiredPermissionForSdkMessage } from './contract-matrix.js';
-export { ALLOWED_KERNEL_MESSAGES, SDK_MSG } from './protocol.js';
-export type { SdkMessageType } from './protocol.js';
-export { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from './errors.js';
-export type { Application, BackendRequestOptions, BackendTransport, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, EventsApi, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphEvent, GraphEventPushPayload, GraphEventType, GraphNodeRaw, GraphTransport, GremlinOptions, HistoryEntry, HistoryOptions, HostBridge, HostBridgeConfig, InstanceList, MutationOptions, NotifyLevel, OrgMember, OrgStructure, OrgUnit, OsConfig, OsRequestOptions, OsTransport, QueryOptions, SdkCommandDefinition, SdkCommandHandler, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbEntry, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkIdbStore, SdkInitResponse, SdkKernelProxyPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorage, SdkStorageDeletePayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransport, SdkTransportPayload, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';
+export type { AppManifest, AppManifestRole, AppManifestRules, AppManifestWindowConfig, CustomWindowSize, WindowSizePreset, } from './manifest.js';
+export type { Application, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphNodeRaw, GremlinOptions, HistoryEntry, HistoryOptions, InstanceList, MutationOptions, OrgMember, OrgStructure, OrgUnit, QueryOptions, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';

package/dist/index.js

@@ -1,5 +1,3 @@
-export { createHostBridge } from './host-bridge.js';
+export { connect } from './client.js';
+export { BardiocError } from './errors.js';
 export { DEFAULT_WINDOW_SIZE, MANIFEST_FILENAME, WINDOW_SIZES, validateManifest, } from './manifest.js';
-export { SDK_CONTRACT_MATRIX, getRequiredPermissionForSdkMessage } from './contract-matrix.js';
-export { ALLOWED_KERNEL_MESSAGES, SDK_MSG } from './protocol.js';
-export { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from './errors.js';

package/dist/manifest.d.ts

@@ -1,5 +1,4 @@
 /** Schema for `public/app-manifest.json` — required in every iframe app's build output. */
-export type AppManifestPermission = 'notify' | 'storage' | 'indexdb' | 'kernel-proxy' | 'transport' | 'events';
 export interface CustomWindowSize {
     width: number;
     height: number;
@@ -51,6 +50,15 @@ export interface AppManifestWindowConfig {
     centered?: boolean;
     isHeaderless?: boolean;
 }
+/** Graph access of one role the app declares. */
+export interface AppManifestRole {
+    vertexRule?: string;
+    edgeRule?: string;
+}
+export interface AppManifestRules {
+    /** Role name to its graph access; the names are the roles the app requests at review. */
+    roles?: Record<string, AppManifestRole>;
+}
 export interface AppManifest {
     /** Schema version. Use `2` for new apps. */
     manifestVersion: 1 | 2;
@@ -65,11 +73,11 @@ export interface AppManifest {
         name: string;
         url?: string;
     };
-    permissions?: AppManifestPermission[];
     categories?: string[];
     showInDock?: boolean;
     showInDockAppsMenu?: boolean;
     window?: AppManifestWindowConfig;
+    rules?: AppManifestRules;
 }
 export declare const MANIFEST_FILENAME = "app-manifest.json";
 export declare function validateManifest(data: unknown): {

package/dist/manifest.js

@@ -10,15 +10,6 @@ export const WINDOW_SIZES = {
 // size used when an app declares no window.size
 export const DEFAULT_WINDOW_SIZE = 'md';
 export const MANIFEST_FILENAME = 'app-manifest.json';
-const VALID_PERMISSIONS = new Set([
-    'notify',
-    'storage',
-    'indexdb',
-    // Deprecated: legacy/internal only. Do not request for normal hosted apps.
-    'kernel-proxy',
-    'transport',
-    'events',
-]);
 function validateBooleanField(value, fieldPath, errors) {
     if (value !== undefined && typeof value !== 'boolean') {
         errors.push(`${fieldPath} must be a boolean`);
@@ -120,20 +111,6 @@ function validateAuthor(m, errors) {
         }
     }
 }
-function validatePermissions(m, errors) {
-    if (m.permissions !== undefined) {
-        if (!Array.isArray(m.permissions)) {
-            errors.push('permissions must be an array');
-        }
-        else {
-            for (const perm of m.permissions) {
-                if (typeof perm !== 'string' || !VALID_PERMISSIONS.has(perm)) {
-                    errors.push(`Invalid permission: "${String(perm)}". Valid: ${[...VALID_PERMISSIONS].join(', ')}`);
-                }
-            }
-        }
-    }
-}
 function validateCategories(m, errors) {
     if (m.categories !== undefined) {
         if (!Array.isArray(m.categories)) {
@@ -147,6 +124,31 @@ function validateCategories(m, errors) {
         }
     }
 }
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// The rule grammar is checked at review, so only the shape is validated here.
+function validateRules(rules, errors) {
+    if (!isPlainObject(rules)) {
+        errors.push('rules must be an object');
+        return;
+    }
+    if (rules.roles === undefined)
+        return;
+    if (!isPlainObject(rules.roles)) {
+        errors.push('rules.roles must be an object');
+        return;
+    }
+    for (const [name, role] of Object.entries(rules.roles)) {
+        if (!isPlainObject(role)) {
+            errors.push(`rules.roles.${name} must be an object`);
+            continue;
+        }
+        for (const field of ['vertexRule', 'edgeRule']) {
+            if (role[field] !== undefined && typeof role[field] !== 'string') {
+                errors.push(`rules.roles.${name}.${field} must be a string`);
+            }
+        }
+    }
+}
 function validateDockFields(m, errors) {
     validateBooleanField(m.showInDock, 'showInDock', errors);
     validateBooleanField(m.showInDockAppsMenu, 'showInDockAppsMenu', errors);
@@ -160,11 +162,13 @@ export function validateManifest(data) {
     validateCoreFields(m, errors);
     validateOptionalFields(m, errors);
     validateAuthor(m, errors);
-    validatePermissions(m, errors);
     validateCategories(m, errors);
     validateDockFields(m, errors);
     if (m.window !== undefined) {
         validateWindowConfig(m.window, errors);
     }
+    if (m.rules !== undefined) {
+        validateRules(m.rules, errors);
+    }
     return { valid: errors.length === 0, errors };
 }

package/dist/protocol.d.ts

@@ -1,29 +1,6 @@
-export type { EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, GraphEvent, GraphEventPushPayload, GraphEventType, SdkCommandDefinition, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransportPayload, } from './types.js';
-export declare const ALLOWED_KERNEL_MESSAGES: ReadonlySet<string>;
-export declare const SDK_MSG: {
-    readonly INIT: "SDK_INIT";
-    readonly INIT_ACK: "SDK_INIT_ACK";
-    readonly RESPONSE: "SDK_RESPONSE";
-    readonly NOTIFY: "SDK_NOTIFY";
-    readonly KERNEL_PROXY: "SDK_KERNEL_PROXY";
-    readonly TRANSPORT: "SDK_TRANSPORT";
-    readonly SET_COMMANDS: "SDK_SET_COMMANDS";
-    readonly SET_MENU: "SDK_SET_MENU";
-    readonly SET_ACTIVE_TAB: "SDK_SET_ACTIVE_TAB";
-    readonly SHORTCUT_EVENT: "SDK_SHORTCUT_EVENT";
-    readonly COMMAND_INVOKE: "SDK_COMMAND_INVOKE";
-    readonly STORAGE_GET: "SDK_STORAGE_GET";
-    readonly STORAGE_SET: "SDK_STORAGE_SET";
-    readonly STORAGE_DELETE: "SDK_STORAGE_DELETE";
-    readonly STORAGE_KEYS: "SDK_STORAGE_KEYS";
-    readonly IDB_PUT: "SDK_IDB_PUT";
-    readonly IDB_GET: "SDK_IDB_GET";
-    readonly IDB_DELETE: "SDK_IDB_DELETE";
-    readonly IDB_QUERY: "SDK_IDB_QUERY";
-    readonly LAUNCH_APP: "SDK_LAUNCH_APP";
-    readonly OS_CONFIG_UPDATE: "SDK_OS_CONFIG_UPDATE";
-    readonly EVENT_SUBSCRIBE: "SDK_EVENT_SUBSCRIBE";
-    readonly EVENT_UNSUBSCRIBE: "SDK_EVENT_UNSUBSCRIBE";
-    readonly GRAPH_EVENT: "SDK_GRAPH_EVENT";
-};
-export type SdkMessageType = (typeof SDK_MSG)[keyof typeof SDK_MSG];
+export { APP_METHODS, GRAPH_EVENT_TYPES, HOST_METHODS, PROTOCOL_VERSION, graphEventFilter, } from './contract.js';
+export type { AppMethods, AppRecord, AppUpload, BffRequest, CallMethod, Command, Context, GraphEvent, HostEvents, HostMethods, IdbEntry, InstalledApp, MenuItem, MenuRoot, Method, NotifyLevel, OsConfig, Params, Result, Shortcut, StreamMethod, UploadResult, } from './contract.js';
+export { BardiocError } from './errors.js';
+export type { ErrorCode, WireError } from './errors.js';
+export { acceptApp, serve } from './serve.js';
+export type { AcceptOptions, Connection, HostHandlers } from './serve.js';

package/dist/protocol.js

@@ -1,31 +1,3 @@
-// host ↔ iframe postMessage protocol — wire-format types and constants
-// Legacy/internal kernel proxy allow-list. Generic resource CRUD is intentionally
-// not iframe-reachable; apps should use scoped SDK APIs such as idb/transport.
-export const ALLOWED_KERNEL_MESSAGES = new Set(['PING']);
-// All postMessage type strings used in the SDK protocol
-export const SDK_MSG = {
-    INIT: 'SDK_INIT',
-    INIT_ACK: 'SDK_INIT_ACK',
-    RESPONSE: 'SDK_RESPONSE',
-    NOTIFY: 'SDK_NOTIFY',
-    KERNEL_PROXY: 'SDK_KERNEL_PROXY',
-    TRANSPORT: 'SDK_TRANSPORT',
-    SET_COMMANDS: 'SDK_SET_COMMANDS',
-    SET_MENU: 'SDK_SET_MENU',
-    SET_ACTIVE_TAB: 'SDK_SET_ACTIVE_TAB',
-    SHORTCUT_EVENT: 'SDK_SHORTCUT_EVENT',
-    COMMAND_INVOKE: 'SDK_COMMAND_INVOKE',
-    STORAGE_GET: 'SDK_STORAGE_GET',
-    STORAGE_SET: 'SDK_STORAGE_SET',
-    STORAGE_DELETE: 'SDK_STORAGE_DELETE',
-    STORAGE_KEYS: 'SDK_STORAGE_KEYS',
-    IDB_PUT: 'SDK_IDB_PUT',
-    IDB_GET: 'SDK_IDB_GET',
-    IDB_DELETE: 'SDK_IDB_DELETE',
-    IDB_QUERY: 'SDK_IDB_QUERY',
-    LAUNCH_APP: 'SDK_LAUNCH_APP',
-    OS_CONFIG_UPDATE: 'SDK_OS_CONFIG_UPDATE',
-    EVENT_SUBSCRIBE: 'SDK_EVENT_SUBSCRIBE',
-    EVENT_UNSUBSCRIBE: 'SDK_EVENT_UNSUBSCRIBE',
-    GRAPH_EVENT: 'SDK_GRAPH_EVENT',
-};
+export { APP_METHODS, GRAPH_EVENT_TYPES, HOST_METHODS, PROTOCOL_VERSION, graphEventFilter, } from './contract.js';
+export { BardiocError } from './errors.js';
+export { acceptApp, serve } from './serve.js';

package/dist/react.d.ts

@@ -1,31 +1,27 @@
-import { type ReactNode } from 'react';
-import type { GraphEvent, HostBridge, HostBridgeConfig, NotifyLevel, OsConfig, SdkCommandDefinition, SdkCommandHandler, SdkMenuRoot } from './types.js';
-export interface AppSdkProviderProps extends HostBridgeConfig {
+import { type DependencyList, type ReactNode } from 'react';
+import { type Bardioc } from './client.js';
+import type { Command, GraphEvent, MenuRoot, NotifyLevel, OsConfig } from './contract.js';
+export interface AppSdkProviderProps {
     children: ReactNode;
+    /** Apply theme, language and size to this document. Default: `true`. */
+    applyOsConfig?: boolean;
 }
-export interface AppCommand extends SdkCommandDefinition {
-    handler: SdkCommandHandler;
-}
-/** Mounts the SDK bridge and makes it available to descendant hooks. */
-export declare function AppSdkProvider({ children, ...config }: Readonly<AppSdkProviderProps>): import("react/jsx-runtime").JSX.Element | null;
-/** Returns the raw {@link HostBridge}. Must be used inside `<AppSdkProvider>`. */
-export declare function useSdk(): HostBridge;
-/** Returns a stable callback that fires a host notification toast. */
+/** Connects to the host and renders `children` once connected. */
+export declare function AppSdkProvider({ children, applyOsConfig: apply, }: Readonly<AppSdkProviderProps>): import("react/jsx-runtime").JSX.Element | null;
+/** The connection to the host. Must be used inside `<AppSdkProvider>`. */
+export declare function useSdk(): Bardioc;
+/** A stable callback that records a notification in the host. */
 export declare function useNotify(): (message: string, level?: NotifyLevel) => void;
-/** Returns a stable callback that proxies a message to the OS service worker. */
-export declare function useSendToKernel(): <R = unknown>(kernelType: string, kernelPayload?: unknown) => Promise<R>;
-export declare function useCommandMenu(commands: AppCommand[], menu: SdkMenuRoot[] | null): void;
+export interface AppCommand extends Command {
+    handler: () => unknown;
+}
+/** Publishes the app's commands and menu to the host while mounted. */
+export declare function useCommandMenu(commands: AppCommand[], menu: MenuRoot[] | null): void;
+/** Tells the host which tab the app shows. */
 export declare function useActiveTab(activeTab: string | null): void;
-/**
- * Returns the current OS configuration (theme, language, systemSize) from the host.
- * Automatically subscribes to updates and returns the latest values.
- */
-export declare function useOsConfig(): OsConfig | null;
-/**
- * Subscribes to live graph events for the given OGIT types while mounted.
- * The handler is kept in a ref so its identity may change without resubscribing;
- * the subscription is recreated only when `types` (or extra `deps`) change.
- */
-export declare function useGraphEvents(options: {
+/** The host's current theme, language and size. */
+export declare function useOsConfig(): OsConfig;
+/** Streams graph events of `types` while mounted; `handler` may change without resubscribing. */
+export declare function useGraphEvents({ types }: {
     types: string[];
-}, handler: (event: GraphEvent) => void, deps?: React.DependencyList): void;
+}, handler: (event: GraphEvent) => void, deps?: DependencyList): void;

package/dist/react.js

@@ -1,221 +1,128 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useRef, useState, } from 'react';
-import { createHostBridge } from './host-bridge.js';
-const SdkContext = createContext(null);
-const SYSTEM_SIZE_CLASS_NAMES = ['text-sm', 'text-base', 'text-lg', 'text-xl'];
-function applyOsConfigToDocument(osConfig) {
-    if (!osConfig) {
-        return;
-    }
+import { connect } from './client.js';
+const BardiocContext = createContext(null);
+const reportFailure = (what) => (error) => console.error(`[app-sdk] ${what} failed`, error);
+const SYSTEM_SIZES = ['text-sm', 'text-base', 'text-lg', 'text-xl'];
+function applyOsConfig({ theme, language, systemSize }) {
     const root = document.documentElement;
-    const isDark = osConfig.theme === 'dark';
-    root.classList.toggle('dark', isDark);
-    // Advertise the resolved theme to the UA so externally-referenced SVGs (app icon.svg
-    // via <img>, favicons) theme-switch through @media (prefers-color-scheme). Mirrors
-    // webos-host (next-themes enableColorScheme) and Storybook's preview decorator.
-    root.style.colorScheme = isDark ? 'dark' : 'light';
-    if (osConfig.language) {
-        root.lang = osConfig.language;
-    }
-    root.classList.remove(...SYSTEM_SIZE_CLASS_NAMES);
-    if (osConfig.systemSize && SYSTEM_SIZE_CLASS_NAMES.includes(osConfig.systemSize)) {
-        root.classList.add(osConfig.systemSize);
-    }
+    root.classList.toggle('dark', theme === 'dark');
+    // Externally referenced SVGs (icons, favicons) theme through prefers-color-scheme.
+    root.style.colorScheme = theme;
+    root.lang = language;
+    root.classList.remove(...SYSTEM_SIZES);
+    if (systemSize && SYSTEM_SIZES.includes(systemSize))
+        root.classList.add(systemSize);
 }
-function hasShortcutItems(items) {
-    return items.some(item => {
-        switch (item.type) {
-            case 'command':
-                return typeof item.shortcut === 'string' && item.shortcut.trim().length > 0;
-            case 'submenu':
-                return hasShortcutItems(item.items);
-        }
-    });
-}
-function hasShortcutRoots(menu) {
-    if (!menu?.length) {
-        return false;
-    }
-    return menu.some(root => hasShortcutItems(root.items));
-}
-/** Mounts the SDK bridge and makes it available to descendant hooks. */
-export function AppSdkProvider({ children, ...config }) {
-    const bridgeRef = useRef(null);
-    const { appId, connectTimeout, debug, targetOrigin } = config;
-    const configKey = JSON.stringify([
-        appId ?? null,
-        connectTimeout ?? null,
-        debug ?? false,
-        targetOrigin ?? null,
-    ]);
-    const bridgeConfig = { appId, connectTimeout, debug, targetOrigin };
-    const bridgeConfigKeyRef = useRef(null);
-    const [readyConfigKey, setReadyConfigKey] = useState(null);
-    const [errorState, setErrorState] = useState(null);
+/** Connects to the host and renders `children` once connected. */
+export function AppSdkProvider({ children, applyOsConfig: apply = true, }) {
+    const [bardioc, setBardioc] = useState(null);
+    const [error, setError] = useState(null);
     useEffect(() => {
-        let cancelled = false;
-        setReadyConfigKey(null);
-        setErrorState(null);
-        const bridge = createHostBridge(bridgeConfig);
-        bridgeRef.current = bridge;
-        bridgeConfigKeyRef.current = configKey;
-        bridge
-            .connect()
-            .then(() => {
-            if (!cancelled) {
-                setReadyConfigKey(configKey);
-            }
-        })
-            .catch((err) => {
-            if (!cancelled) {
-                bridgeRef.current = null;
-                bridgeConfigKeyRef.current = null;
-                setErrorState({ configKey, message: err.message });
-            }
-        });
+        let active = true;
+        connect().then(connected => active && setBardioc(connected), (failure) => active && setError(failure.message));
         return () => {
-            cancelled = true;
-            bridge.destroy();
-            if (bridgeRef.current === bridge) {
-                bridgeRef.current = null;
-            }
-            if (bridgeConfigKeyRef.current === configKey) {
-                bridgeConfigKeyRef.current = null;
-            }
+            active = false;
         };
-    }, [appId, configKey, connectTimeout, debug, targetOrigin]);
+    }, []);
     useEffect(() => {
-        if (readyConfigKey !== configKey ||
-            bridgeConfigKeyRef.current !== configKey ||
-            !bridgeRef.current) {
+        if (!apply || !bardioc)
             return;
-        }
-        applyOsConfigToDocument(bridgeRef.current.context?.osConfig ?? null);
-        const unsubscribe = bridgeRef.current.onOsConfigUpdate(newConfig => {
-            applyOsConfigToDocument(newConfig);
-        });
-        return unsubscribe;
-    }, [configKey, readyConfigKey]);
-    if (errorState?.configKey === configKey) {
-        return _jsx("div", { "data-sdk-error": true, children: errorState.message });
-    }
-    if (readyConfigKey !== configKey ||
-        bridgeConfigKeyRef.current !== configKey ||
-        !bridgeRef.current) {
+        applyOsConfig(bardioc.context.osConfig);
+        return bardioc.onContextChange(context => applyOsConfig(context.osConfig));
+    }, [apply, bardioc]);
+    if (error)
+        return _jsx("div", { "data-sdk-error": true, children: error });
+    if (!bardioc)
         return null;
-    }
-    return _jsx(SdkContext.Provider, { value: bridgeRef.current, children: children });
+    return _jsx(BardiocContext.Provider, { value: bardioc, children: children });
 }
-/** Returns the raw {@link HostBridge}. Must be used inside `<AppSdkProvider>`. */
+/** The connection to the host. Must be used inside `<AppSdkProvider>`. */
 export function useSdk() {
-    const bridge = useContext(SdkContext);
-    if (!bridge)
+    const bardioc = useContext(BardiocContext);
+    if (!bardioc)
         throw new Error('useSdk() must be used inside <AppSdkProvider>');
-    return bridge;
+    return bardioc;
 }
-/** Returns a stable callback that fires a host notification toast. */
+/** A stable callback that records a notification in the host. */
 export function useNotify() {
-    const bridge = useSdk();
+    const { ui } = useSdk();
     return useCallback((message, level) => {
-        bridge.notify(message, level);
-    }, [bridge]);
-}
-/** Returns a stable callback that proxies a message to the OS service worker. */
-export function useSendToKernel() {
-    const bridge = useSdk();
-    return useCallback((kernelType, kernelPayload) => bridge.sendToKernel(kernelType, kernelPayload), [bridge]);
+        ui.notify(message, level).catch(reportFailure('notify'));
+    }, [ui]);
 }
+const hasShortcut = (items) => items.some(item => item.type === 'command' ? Boolean(item.shortcut?.trim()) : hasShortcut(item.items));
+/** Publishes the app's commands and menu to the host while mounted. */
 export function useCommandMenu(commands, menu) {
-    const bridge = useSdk();
+    const { ui } = useSdk();
     useEffect(() => {
-        const unregister = bridge.registerCommandHandlers(Object.fromEntries(commands.map(command => [command.id, command.handler])));
-        return unregister;
-    }, [bridge, commands]);
+        const unregister = commands.map(({ id, handler }) => ui.onCommand(id, handler));
+        ui.setCommands(commands.map(({ handler: _, ...command }) => command)).catch(reportFailure('setCommands'));
+        return () => unregister.forEach(stop => stop());
+    }, [ui, commands]);
     useEffect(() => {
-        const commandState = commands.map(({ handler: _handler, ...command }) => command);
-        void bridge.setCommands(commandState).catch((error) => {
-            console.error('[app-sdk] failed to sync command state', error);
-        });
-        void bridge.setMenu(menu).catch((error) => {
-            console.error('[app-sdk] failed to sync app menu', error);
-        });
-    }, [bridge, commands, menu]);
+        ui.setMenu(menu).catch(reportFailure('setMenu'));
+    }, [ui, menu]);
     useEffect(() => {
-        if (!hasShortcutRoots(menu)) {
+        if (!menu?.some(root => hasShortcut(root.items)))
             return;
-        }
-        const handleKeyDown = (event) => {
-            if (event.defaultPrevented || event.isComposing || event.repeat) {
+        const onKeyDown = (event) => {
+            if (event.defaultPrevented || event.isComposing || event.repeat)
                 return;
-            }
-            if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+            if (!event.metaKey && !event.ctrlKey && !event.altKey)
                 return;
-            }
-            bridge.sendShortcutEvent({
-                code: event.code,
-                ctrlKey: event.ctrlKey,
-                metaKey: event.metaKey,
-                altKey: event.altKey,
-                shiftKey: event.shiftKey,
-            });
-        };
-        window.addEventListener('keydown', handleKeyDown);
-        return () => {
-            window.removeEventListener('keydown', handleKeyDown);
+            const { code, ctrlKey, metaKey, altKey, shiftKey } = event;
+            ui.shortcut({ code, ctrlKey, metaKey, altKey, shiftKey }).catch(reportFailure('shortcut'));
         };
-    }, [bridge, menu]);
-    useEffect(() => {
-        return () => {
-            void bridge.setMenu(null).catch(() => undefined);
-            void bridge.setCommands([]).catch(() => undefined);
-        };
-    }, [bridge]);
+        window.addEventListener('keydown', onKeyDown);
+        return () => window.removeEventListener('keydown', onKeyDown);
+    }, [ui, menu]);
+    useEffect(() => () => {
+        ui.setMenu(null).catch(reportFailure('setMenu'));
+        ui.setCommands([]).catch(reportFailure('setCommands'));
+    }, [ui]);
 }
-// interface for active tab for iframe app
+/** Tells the host which tab the app shows. */
 export function useActiveTab(activeTab) {
-    const bridge = useSdk();
+    const { ui } = useSdk();
     useEffect(() => {
-        void bridge.setActiveTab(activeTab).catch((error) => {
-            console.error('[app-sdk] failed to sync active tab', error);
-        });
+        ui.setActiveTab(activeTab).catch(reportFailure('setActiveTab'));
         return () => {
-            void bridge.setActiveTab(null).catch(() => undefined);
+            ui.setActiveTab(null).catch(reportFailure('setActiveTab'));
         };
-    }, [bridge, activeTab]);
+    }, [ui, activeTab]);
 }
-/**
- * Returns the current OS configuration (theme, language, systemSize) from the host.
- * Automatically subscribes to updates and returns the latest values.
- */
+/** The host's current theme, language and size. */
 export function useOsConfig() {
-    const bridge = useSdk();
-    const [osConfig, setOsConfig] = useState(() => bridge.context?.osConfig ?? null);
+    const bardioc = useSdk();
+    const [osConfig, setOsConfig] = useState(bardioc.context.osConfig);
     useEffect(() => {
-        // Sync with current context on mount
-        if (bridge.context?.osConfig) {
-            setOsConfig(bridge.context.osConfig);
-        }
-        // Subscribe to OS config updates from host
-        const unsubscribe = bridge.onOsConfigUpdate(newConfig => {
-            setOsConfig(newConfig);
-        });
-        return unsubscribe;
-    }, [bridge]);
+        setOsConfig(bardioc.context.osConfig);
+        return bardioc.onContextChange(context => setOsConfig(context.osConfig));
+    }, [bardioc]);
     return osConfig;
 }
-/**
- * Subscribes to live graph events for the given OGIT types while mounted.
- * The handler is kept in a ref so its identity may change without resubscribing;
- * the subscription is recreated only when `types` (or extra `deps`) change.
- */
-export function useGraphEvents(options, handler, deps = []) {
-    const bridge = useSdk();
+/** Streams graph events of `types` while mounted; `handler` may change without resubscribing. */
+export function useGraphEvents({ types }, handler, deps = []) {
+    const { events } = useSdk();
     const handlerRef = useRef(handler);
     handlerRef.current = handler;
-    const typesKey = JSON.stringify(options.types);
+    const typesKey = JSON.stringify(types);
     useEffect(() => {
-        const unsubscribe = bridge.events.subscribe({ types: JSON.parse(typesKey) }, event => handlerRef.current(event));
-        return unsubscribe;
+        let end;
+        let active = true;
+        events
+            .graph({ types: JSON.parse(typesKey) }, event => handlerRef.current(event))
+            .then(stop => {
+            if (active)
+                end = stop;
+            else
+                stop();
+        }, reportFailure('events.graph'));
+        return () => {
+            active = false;
+            end?.();
+        };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [bridge, typesKey, ...deps]);
+    }, [events, typesKey, ...deps]);
 }

package/dist/serve.d.ts

@@ -0,0 +1,26 @@
+import { type AppMethods, type CallMethod, type Context, type HostEvents, type HostMethods, type Method, type Params, type Result, type StreamMethod } from './contract.js';
+type HostHandler<M extends Method> = M extends CallMethod ? (params: Params<M>, signal: AbortSignal) => Result<M> | Promise<Result<M>> : M extends StreamMethod ? (params: Params<M>, emit: (value: Result<M>) => void) => () => void : never;
+/** What a host implements: one handler per app method. */
+export type HostHandlers = {
+    [K in keyof AppMethods]: HostHandler<AppMethods[K]>;
+};
+/** A host's end of one app connection. */
+export interface Connection {
+    call<K extends keyof HostMethods>(method: K, params: Params<HostMethods[K]>): Promise<Result<HostMethods[K]>>;
+    emit<K extends keyof HostEvents>(event: K, payload: HostEvents[K]): void;
+    close(): void;
+}
+/** Answers an app's calls on `port` with `handlers`, validating every call against the contract. */
+export declare function serve(port: MessagePort, handlers: HostHandlers): Connection;
+export interface AcceptOptions {
+    /** The app's window, read per message: a reload keeps the frame but not its document. */
+    source: () => Window | null | undefined;
+    origin: string;
+    context: () => Context;
+    onConnect: (port: MessagePort) => void;
+    /** An app speaking another protocol version; it has already been told. */
+    onReject?: (protocol: number) => void;
+}
+/** Waits for an app's `ready` and answers each one with a fresh port. */
+export declare function acceptApp({ source, origin, context, onConnect, onReject }: AcceptOptions): () => void;
+export {};