@bardioc/app-sdk 0.4.0

package/dist/manifest.d.ts

@@ -0,0 +1,78 @@
+/** Schema for `public/app-manifest.json` — required in every iframe app's build output. */
+export type AppManifestPermission = 'notify' | 'storage' | 'indexdb' | 'kernel-proxy' | 'transport';
+export interface CustomWindowSize {
+    width: number;
+    height: number;
+    minWidth?: number;
+    minHeight?: number;
+}
+export declare const WINDOW_SIZES: {
+    readonly xs: {
+        readonly width: 480;
+        readonly height: 320;
+        readonly minWidth: 360;
+        readonly minHeight: 280;
+    };
+    readonly sm: {
+        readonly width: 640;
+        readonly height: 480;
+        readonly minWidth: 480;
+        readonly minHeight: 320;
+    };
+    readonly md: {
+        readonly width: 800;
+        readonly height: 600;
+        readonly minWidth: 480;
+        readonly minHeight: 320;
+    };
+    readonly lg: {
+        readonly width: 1024;
+        readonly height: 800;
+        readonly minWidth: 640;
+        readonly minHeight: 480;
+    };
+    readonly xl: {
+        readonly width: 1280;
+        readonly height: 800;
+        readonly minWidth: 800;
+        readonly minHeight: 600;
+    };
+};
+export type WindowSizePreset = keyof typeof WINDOW_SIZES;
+export declare const DEFAULT_WINDOW_SIZE: WindowSizePreset;
+export interface AppManifestWindowConfig {
+    size?: WindowSizePreset | CustomWindowSize;
+    canHaveMultipleWindows?: boolean;
+    isInstanceAware?: boolean;
+    resizable?: boolean;
+    maximizable?: boolean;
+    minimizable?: boolean;
+    customScroll?: boolean;
+    centered?: boolean;
+    isHeaderless?: boolean;
+}
+export interface AppManifest {
+    /** Schema version. Use `2` for new apps. */
+    manifestVersion: 1 | 2;
+    /** Lowercase app identifier, e.g. `"my-app"` or `"weather"`. */
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    icon?: string;
+    entry?: string;
+    author?: {
+        name: string;
+        url?: string;
+    };
+    permissions?: AppManifestPermission[];
+    categories?: string[];
+    showInDock?: boolean;
+    showInDockAppsMenu?: boolean;
+    window?: AppManifestWindowConfig;
+}
+export declare const MANIFEST_FILENAME = "app-manifest.json";
+export declare function validateManifest(data: unknown): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/manifest.js

@@ -0,0 +1,169 @@
+/** Schema for `public/app-manifest.json` — required in every iframe app's build output. */
+// standard window sizes - pick one via window.size
+export const WINDOW_SIZES = {
+    xs: { width: 480, height: 320, minWidth: 360, minHeight: 280 },
+    sm: { width: 640, height: 480, minWidth: 480, minHeight: 320 },
+    md: { width: 800, height: 600, minWidth: 480, minHeight: 320 },
+    lg: { width: 1024, height: 800, minWidth: 640, minHeight: 480 },
+    xl: { width: 1280, height: 800, minWidth: 800, minHeight: 600 },
+};
+// 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',
+]);
+function validateBooleanField(value, fieldPath, errors) {
+    if (value !== undefined && typeof value !== 'boolean') {
+        errors.push(`${fieldPath} must be a boolean`);
+    }
+}
+function validateWindowConfig(windowConfig, errors) {
+    if (typeof windowConfig !== 'object' || windowConfig === null || Array.isArray(windowConfig)) {
+        errors.push('window must be an object');
+        return;
+    }
+    const w = windowConfig;
+    if (w.size !== undefined) {
+        if (typeof w.size === 'string') {
+            if (!(w.size in WINDOW_SIZES)) {
+                errors.push(`window.size must be one of: ${Object.keys(WINDOW_SIZES).join(', ')}`);
+            }
+        }
+        else if (typeof w.size === 'object' && w.size !== null && !Array.isArray(w.size)) {
+            const size = w.size;
+            const width = size.width;
+            const height = size.height;
+            if (typeof width !== 'number' ||
+                !Number.isFinite(width) ||
+                width <= 0 ||
+                typeof height !== 'number' ||
+                !Number.isFinite(height) ||
+                height <= 0) {
+                errors.push('window.size custom dimensions require positive width and height');
+            }
+            if (size.minWidth !== undefined &&
+                (typeof size.minWidth !== 'number' ||
+                    !Number.isFinite(size.minWidth) ||
+                    size.minWidth <= 0 ||
+                    (typeof width === 'number' && size.minWidth > width))) {
+                errors.push('window.size custom minWidth must be positive and no greater than width');
+            }
+            if (size.minHeight !== undefined &&
+                (typeof size.minHeight !== 'number' ||
+                    !Number.isFinite(size.minHeight) ||
+                    size.minHeight <= 0 ||
+                    (typeof height === 'number' && size.minHeight > height))) {
+                errors.push('window.size custom minHeight must be positive and no greater than height');
+            }
+        }
+        else {
+            errors.push(`window.size must be one of: ${Object.keys(WINDOW_SIZES).join(', ')}, or a custom { width, height } object`);
+        }
+    }
+    validateBooleanField(w.canHaveMultipleWindows, 'window.canHaveMultipleWindows', errors);
+    validateBooleanField(w.isInstanceAware, 'window.isInstanceAware', errors);
+    validateBooleanField(w.resizable, 'window.resizable', errors);
+    validateBooleanField(w.maximizable, 'window.maximizable', errors);
+    validateBooleanField(w.minimizable, 'window.minimizable', errors);
+    validateBooleanField(w.customScroll, 'window.customScroll', errors);
+    validateBooleanField(w.centered, 'window.centered', errors);
+    validateBooleanField(w.isHeaderless, 'window.isHeaderless', errors);
+}
+function validateCoreFields(m, errors) {
+    if (m.manifestVersion !== 1 && m.manifestVersion !== 2) {
+        errors.push('manifestVersion must be 1 or 2');
+    }
+    if (!m.id || typeof m.id !== 'string' || m.id.trim().length === 0) {
+        errors.push('id is required and must be a non-empty string (e.g. "my-app")');
+    }
+    else if (!/^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$/.test(m.id)) {
+        errors.push('id must be lowercase alphanumeric with dots, hyphens, or underscores (e.g. "my-app")');
+    }
+    if (!m.name || typeof m.name !== 'string' || m.name.trim().length === 0) {
+        errors.push('name is required and must be a non-empty string');
+    }
+    if (!m.version || typeof m.version !== 'string') {
+        errors.push('version is required and must be a string');
+    }
+}
+function validateOptionalFields(m, errors) {
+    if (m.description !== undefined && typeof m.description !== 'string') {
+        errors.push('description must be a string');
+    }
+    if (m.icon !== undefined && typeof m.icon !== 'string') {
+        errors.push('icon must be a string');
+    }
+    if (m.entry !== undefined && typeof m.entry !== 'string') {
+        errors.push('entry must be a string');
+    }
+}
+function validateAuthor(m, errors) {
+    if (m.author !== undefined) {
+        if (typeof m.author !== 'object' || m.author === null) {
+            errors.push('author must be an object');
+        }
+        else {
+            const a = m.author;
+            if (!a.name || typeof a.name !== 'string') {
+                errors.push('author.name is required and must be a string');
+            }
+            if (a.url !== undefined && typeof a.url !== 'string') {
+                errors.push('author.url must be a string');
+            }
+        }
+    }
+}
+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)) {
+            errors.push('categories must be an array');
+        }
+        else {
+            for (const cat of m.categories) {
+                if (typeof cat !== 'string')
+                    errors.push('each category must be a string');
+            }
+        }
+    }
+}
+function validateDockFields(m, errors) {
+    validateBooleanField(m.showInDock, 'showInDock', errors);
+    validateBooleanField(m.showInDockAppsMenu, 'showInDockAppsMenu', errors);
+}
+export function validateManifest(data) {
+    const errors = [];
+    if (!data || typeof data !== 'object') {
+        return { valid: false, errors: ['Manifest must be a JSON object'] };
+    }
+    const m = 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);
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,26 @@
+export type { 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";
+};
+export type SdkMessageType = (typeof SDK_MSG)[keyof typeof SDK_MSG];

package/dist/protocol.js

@@ -0,0 +1,28 @@
+// 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',
+};

package/dist/react.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+import { type DevAuthStorageOptions } from './dev.js';
+import type { HostBridge, HostBridgeConfig, NotifyLevel, OsConfig, SdkCommandDefinition, SdkCommandHandler, SdkMenuRoot } from './types.js';
+export interface AppSdkProviderProps extends HostBridgeConfig {
+    children: ReactNode;
+}
+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. */
+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 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;
+/** Returns a stable callback that clears standalone dev auth state and reloads the page. */
+export declare function useStandaloneDevLogout(options: DevAuthStorageOptions): () => void;

package/dist/react.js

@@ -0,0 +1,208 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useRef, useState, } from 'react';
+import { clearDevAuthSession } from './dev.js';
+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;
+    }
+    const root = document.documentElement;
+    root.classList.toggle('dark', osConfig.theme === 'dark');
+    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);
+    }
+}
+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);
+    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 });
+            }
+        });
+        return () => {
+            cancelled = true;
+            bridge.destroy();
+            if (bridgeRef.current === bridge) {
+                bridgeRef.current = null;
+            }
+            if (bridgeConfigKeyRef.current === configKey) {
+                bridgeConfigKeyRef.current = null;
+            }
+        };
+    }, [appId, configKey, connectTimeout, debug, targetOrigin]);
+    useEffect(() => {
+        if (readyConfigKey !== configKey ||
+            bridgeConfigKeyRef.current !== configKey ||
+            !bridgeRef.current) {
+            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) {
+        return null;
+    }
+    return _jsx(SdkContext.Provider, { value: bridgeRef.current, children: children });
+}
+/** Returns the raw {@link HostBridge}. Must be used inside `<AppSdkProvider>`. */
+export function useSdk() {
+    const bridge = useContext(SdkContext);
+    if (!bridge)
+        throw new Error('useSdk() must be used inside <AppSdkProvider>');
+    return bridge;
+}
+/** Returns a stable callback that fires a host notification toast. */
+export function useNotify() {
+    const bridge = 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]);
+}
+export function useCommandMenu(commands, menu) {
+    const bridge = useSdk();
+    useEffect(() => {
+        const unregister = bridge.registerCommandHandlers(Object.fromEntries(commands.map(command => [command.id, command.handler])));
+        return unregister;
+    }, [bridge, 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]);
+    useEffect(() => {
+        if (!hasShortcutRoots(menu)) {
+            return;
+        }
+        const handleKeyDown = (event) => {
+            if (event.defaultPrevented || event.isComposing || event.repeat) {
+                return;
+            }
+            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);
+        };
+    }, [bridge, menu]);
+    useEffect(() => {
+        return () => {
+            void bridge.setMenu(null).catch(() => undefined);
+            void bridge.setCommands([]).catch(() => undefined);
+        };
+    }, [bridge]);
+}
+// interface for active tab for iframe app
+export function useActiveTab(activeTab) {
+    const bridge = useSdk();
+    useEffect(() => {
+        void bridge.setActiveTab(activeTab).catch((error) => {
+            console.error('[app-sdk] failed to sync active tab', error);
+        });
+        return () => {
+            void bridge.setActiveTab(null).catch(() => undefined);
+        };
+    }, [bridge, activeTab]);
+}
+/**
+ * Returns the current OS configuration (theme, language, systemSize) from the host.
+ * Automatically subscribes to updates and returns the latest values.
+ */
+export function useOsConfig() {
+    const bridge = useSdk();
+    const [osConfig, setOsConfig] = useState(() => bridge.context?.osConfig ?? null);
+    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]);
+    return osConfig;
+}
+/** Returns a stable callback that clears standalone dev auth state and reloads the page. */
+export function useStandaloneDevLogout(options) {
+    return useCallback(() => {
+        clearDevAuthSession(options);
+        window.location.reload();
+    }, [options]);
+}