@syntrologie/runtime-sdk 1.0.1-canary.3 → 2.0.0-canary.1

package/dist/apps/AppLoader.js

@@ -0,0 +1,250 @@
+/**
+ * App Loader
+ *
+ * Handles loading apps from CDN based on canvas config requirements.
+ *
+ * Loading Strategy:
+ * 1. Core apps (built-in actions) are bundled with runtime - no loading needed
+ * 2. External apps are loaded from CDN when config references them
+ *
+ * The loader determines which apps are needed by scanning the canvas config for:
+ * - Action kinds with namespaces (e.g., "gamification:awardBadge")
+ * - Widget IDs with namespaces (e.g., "gamification:leaderboard")
+ * - Explicit app references in config
+ */
+// ============================================================================
+// Core Apps (bundled with runtime)
+// ============================================================================
+/**
+ * Core action kinds that are bundled with the runtime.
+ * These don't require loading external apps.
+ */
+const CORE_ACTION_KINDS = new Set([
+    "overlays:highlight",
+    "overlays:pulse",
+    "overlays:badge",
+    "overlays:tooltip",
+    "content:insertHtml",
+    "content:setText",
+    "content:setAttr",
+    "content:addClass",
+    "content:removeClass",
+    "content:setStyle",
+    "core:mountWidget",
+    "core:wait",
+    "core:sequence",
+    "core:parallel",
+    "navigation:scrollTo",
+    "navigation:navigate",
+]);
+/**
+ * Check if an action kind is a core action.
+ */
+export function isCoreActionKind(kind) {
+    return CORE_ACTION_KINDS.has(kind);
+}
+/**
+ * Extract app ID from a namespaced action kind.
+ * e.g., "gamification:awardBadge" → "gamification"
+ */
+export function getAppIdFromActionKind(kind) {
+    if (isCoreActionKind(kind))
+        return null;
+    const colonIndex = kind.indexOf(":");
+    if (colonIndex === -1)
+        return null;
+    return kind.slice(0, colonIndex);
+}
+/**
+ * Extract app ID from a namespaced widget ID.
+ * e.g., "gamification:leaderboard" → "gamification"
+ */
+export function getAppIdFromWidgetId(widgetId) {
+    const colonIndex = widgetId.indexOf(":");
+    if (colonIndex === -1)
+        return null;
+    return widgetId.slice(0, colonIndex);
+}
+// ============================================================================
+// App Loader
+// ============================================================================
+/**
+ * Create an app loader instance.
+ */
+export function createAppLoader(options) {
+    const { cdnBase, registry, timeout = 10000, onLoadStart, onLoadEnd } = options;
+    /** Cache of loading promises to avoid duplicate loads */
+    const loadingPromises = new Map();
+    /** Cache of loaded app URLs */
+    const loadedUrls = new Set();
+    /**
+     * Get the CDN URL for an app.
+     */
+    function getAppUrl(appId) {
+        // Convention: apps are at {cdnBase}/apps/{appId}/index.js
+        return `${cdnBase}/apps/${appId}/index.js`;
+    }
+    /**
+     * Load a single app from CDN.
+     */
+    async function loadApp(appId) {
+        var _a;
+        // Check if already registered
+        if (registry.has(appId)) {
+            return { appId, success: true, manifest: (_a = registry.get(appId)) === null || _a === void 0 ? void 0 : _a.manifest };
+        }
+        // Check if already loading
+        if (loadingPromises.has(appId)) {
+            return loadingPromises.get(appId);
+        }
+        // Start loading
+        const loadPromise = (async () => {
+            onLoadStart === null || onLoadStart === void 0 ? void 0 : onLoadStart(appId);
+            try {
+                const url = getAppUrl(appId);
+                // Skip if already loaded this URL
+                if (loadedUrls.has(url)) {
+                    const registration = registry.get(appId);
+                    if (registration) {
+                        onLoadEnd === null || onLoadEnd === void 0 ? void 0 : onLoadEnd(appId, true);
+                        return { appId, success: true, manifest: registration.manifest };
+                    }
+                }
+                // Create timeout promise
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error(`Timeout loading app: ${appId}`)), timeout);
+                });
+                // Fetch and execute the app bundle
+                const loadPromise = loadAppBundle(url, appId);
+                await Promise.race([loadPromise, timeoutPromise]);
+                loadedUrls.add(url);
+                // Get the registered manifest
+                const registration = registry.get(appId);
+                if (!registration) {
+                    throw new Error(`App ${appId} did not register after loading`);
+                }
+                onLoadEnd === null || onLoadEnd === void 0 ? void 0 : onLoadEnd(appId, true);
+                return { appId, success: true, manifest: registration.manifest };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                onLoadEnd === null || onLoadEnd === void 0 ? void 0 : onLoadEnd(appId, false, errorMessage);
+                return { appId, success: false, error: errorMessage };
+            }
+            finally {
+                loadingPromises.delete(appId);
+            }
+        })();
+        loadingPromises.set(appId, loadPromise);
+        return loadPromise;
+    }
+    /**
+     * Load an app bundle from a URL.
+     */
+    async function loadAppBundle(url, appId) {
+        var _a;
+        // For browser environments, we use dynamic import or script loading
+        if (typeof window !== "undefined") {
+            // Try dynamic import first (for ES modules)
+            try {
+                const module = await import(/* webpackIgnore: true */ url);
+                // The module should export a manifest and optionally auto-register
+                if (module.manifest) {
+                    registry.register(module.manifest);
+                }
+                else if ((_a = module.default) === null || _a === void 0 ? void 0 : _a.manifest) {
+                    registry.register(module.default.manifest);
+                }
+                else if (module.default) {
+                    // If module.default is the manifest itself
+                    registry.register(module.default);
+                }
+                return;
+            }
+            catch {
+                // Fall back to script tag loading for UMD bundles
+            }
+            // Script tag loading for UMD bundles
+            return new Promise((resolve, reject) => {
+                const script = document.createElement("script");
+                script.src = url;
+                script.async = true;
+                script.onload = () => {
+                    // UMD bundles should register themselves via global
+                    const registered = registry.get(appId);
+                    if (registered) {
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`App ${appId} did not self-register`));
+                    }
+                };
+                script.onerror = () => {
+                    reject(new Error(`Failed to load app script: ${url}`));
+                };
+                document.head.appendChild(script);
+            });
+        }
+        // For SSR/Node environments, we can't dynamically load apps
+        throw new Error("Dynamic app loading not supported in SSR");
+    }
+    /**
+     * Analyze config to determine which apps need to be loaded.
+     */
+    function getRequiredApps(config) {
+        var _a;
+        const appIds = new Set();
+        // Check explicit app references
+        if (config.apps) {
+            for (const appId of config.apps) {
+                appIds.add(appId);
+            }
+        }
+        // Check action kinds for namespaced actions
+        if (config.actions) {
+            for (const action of config.actions) {
+                const appId = getAppIdFromActionKind(action.kind);
+                if (appId) {
+                    appIds.add(appId);
+                }
+                // Also check core:mountWidget actions for widget namespaces
+                if (action.kind === "core:mountWidget") {
+                    const widgetId = (_a = action.widget) === null || _a === void 0 ? void 0 : _a.widgetId;
+                    if (widgetId) {
+                        const widgetAppId = getAppIdFromWidgetId(widgetId);
+                        if (widgetAppId) {
+                            appIds.add(widgetAppId);
+                        }
+                    }
+                }
+            }
+        }
+        return Array.from(appIds);
+    }
+    /**
+     * Load all apps required by a config.
+     */
+    async function loadAppsForConfig(config) {
+        const requiredApps = getRequiredApps(config);
+        if (requiredApps.length === 0) {
+            return [];
+        }
+        // Load all apps in parallel
+        const results = await Promise.all(requiredApps.map((appId) => loadApp(appId)));
+        return results;
+    }
+    /**
+     * Preload apps without activating them.
+     */
+    async function preloadApps(appIds) {
+        return Promise.all(appIds.map((appId) => loadApp(appId)));
+    }
+    return {
+        loadApp,
+        loadAppsForConfig,
+        preloadApps,
+        getRequiredApps,
+        getAppUrl,
+    };
+}
+//# sourceMappingURL=AppLoader.js.map

package/dist/apps/AppLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppLoader.js","sourceRoot":"","sources":["../../src/apps/AppLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA+CH,+EAA+E;AAC/E,mCAAmC;AACnC,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,oBAAoB;IACpB,gBAAgB;IAChB,gBAAgB;IAChB,kBAAkB;IAClB,oBAAoB;IACpB,iBAAiB;IACjB,iBAAiB;IACjB,kBAAkB;IAClB,qBAAqB;IACrB,kBAAkB;IAClB,kBAAkB;IAClB,WAAW;IACX,eAAe;IACf,eAAe;IACf,qBAAqB;IACrB,qBAAqB;CACtB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,IAAI,gBAAgB,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACvC,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAE/E,yDAAyD;IACzD,MAAM,eAAe,GAAG,IAAI,GAAG,EAAkC,CAAC;IAElE,+BAA+B;IAC/B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC;;OAEG;IACH,SAAS,SAAS,CAAC,KAAa;QAC9B,0DAA0D;QAC1D,OAAO,GAAG,OAAO,SAAS,KAAK,WAAW,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,KAAK,UAAU,OAAO,CAAC,KAAa;;QAClC,8BAA8B;QAC9B,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAA,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,0CAAE,QAAQ,EAAE,CAAC;QAC3E,CAAC;QAED,2BAA2B;QAC3B,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;QACrC,CAAC;QAED,gBAAgB;QAChB,MAAM,WAAW,GAAG,CAAC,KAAK,IAA4B,EAAE;YACtD,WAAW,aAAX,WAAW,uBAAX,WAAW,CAAG,KAAK,CAAC,CAAC;YAErB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;gBAE7B,kCAAkC;gBAClC,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACxB,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;oBACzC,IAAI,YAAY,EAAE,CAAC;wBACjB,SAAS,aAAT,SAAS,uBAAT,SAAS,CAAG,KAAK,EAAE,IAAI,CAAC,CAAC;wBACzB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,CAAC;oBACnE,CAAC;gBACH,CAAC;gBAED,yBAAyB;gBACzB,MAAM,cAAc,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;oBACtD,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,wBAAwB,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;gBAChF,CAAC,CAAC,CAAC;gBAEH,mCAAmC;gBACnC,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBAC9C,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;gBAElD,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAEpB,8BAA8B;gBAC9B,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACzC,IAAI,CAAC,YAAY,EAAE,CAAC;oBAClB,MAAM,IAAI,KAAK,CAAC,OAAO,KAAK,iCAAiC,CAAC,CAAC;gBACjE,CAAC;gBAED,SAAS,aAAT,SAAS,uBAAT,SAAS,CAAG,KAAK,EAAE,IAAI,CAAC,CAAC;gBACzB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,CAAC;YAEnE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC5E,SAAS,aAAT,SAAS,uBAAT,SAAS,CAAG,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;gBACxC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;YACxD,CAAC;oBAAS,CAAC;gBACT,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAChC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QAEL,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACxC,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,KAAa;;QACrD,oEAAoE;QACpE,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,4CAA4C;YAC5C,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,GAAG,CAAC,CAAC;gBAE3D,mEAAmE;gBACnE,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;oBACpB,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACrC,CAAC;qBAAM,IAAI,MAAA,MAAM,CAAC,OAAO,0CAAE,QAAQ,EAAE,CAAC;oBACpC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAC7C,CAAC;qBAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC1B,2CAA2C;oBAC3C,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACpC,CAAC;gBACD,OAAO;YACT,CAAC;YAAC,MAAM,CAAC;gBACP,kDAAkD;YACpD,CAAC;YAED,qCAAqC;YACrC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;gBAChD,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC;gBACjB,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;gBAEpB,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE;oBACnB,oDAAoD;oBACpD,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;oBACvC,IAAI,UAAU,EAAE,CAAC;wBACf,OAAO,EAAE,CAAC;oBACZ,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,wBAAwB,CAAC,CAAC,CAAC;oBAC1D,CAAC;gBACH,CAAC,CAAC;gBAEF,MAAM,CAAC,OAAO,GAAG,GAAG,EAAE;oBACpB,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC,CAAC;gBACzD,CAAC,CAAC;gBAEF,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACpC,CAAC,CAAC,CAAC;QACL,CAAC;QAED,4DAA4D;QAC5D,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACH,SAAS,eAAe,CAAC,MAA6B;;QACpD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;QAEjC,gCAAgC;QAChC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;gBAChC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;QAED,4CAA4C;QAC5C,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpC,MAAM,KAAK,GAAG,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAClD,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACpB,CAAC;gBAED,4DAA4D;gBAC5D,IAAI,MAAM,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;oBACvC,MAAM,QAAQ,GAAG,MAAC,MAAc,CAAC,MAAM,0CAAE,QAAQ,CAAC;oBAClD,IAAI,QAAQ,EAAE,CAAC;wBACb,MAAM,WAAW,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;wBACnD,IAAI,WAAW,EAAE,CAAC;4BAChB,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;wBAC1B,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,KAAK,UAAU,iBAAiB,CAAC,MAA6B;QAC5D,MAAM,YAAY,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAE7C,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,4BAA4B;QAC5B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAC5C,CAAC;QAEF,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,UAAU,WAAW,CAAC,MAAgB;QACzC,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO;QACL,OAAO;QACP,iBAAiB;QACjB,WAAW;QACX,eAAe;QACf,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/apps/AppRegistry.d.ts

@@ -0,0 +1,102 @@
+/**
+ * App Registry
+ *
+ * Central registry for managing SynOS apps.
+ * Handles app registration, activation, deactivation, and lifecycle management.
+ */
+import type { SmartCanvasRuntime } from "../runtime";
+import type { AppManifest, AppRegistration, AppRegistryEvent } from "./types";
+/**
+ * Callback for app registry events.
+ */
+export type AppRegistryEventCallback = (event: AppRegistryEvent) => void;
+/**
+ * App registry for managing SynOS apps.
+ */
+export declare class AppRegistry {
+    private apps;
+    private eventListeners;
+    private runtime;
+    /**
+     * Bind the registry to a runtime instance.
+     * Must be called before apps can be activated.
+     */
+    bind(runtime: SmartCanvasRuntime): void;
+    /**
+     * Unbind from the current runtime.
+     * Deactivates all active apps first.
+     */
+    unbind(): Promise<void>;
+    /**
+     * Register an app.
+     *
+     * Registration makes the app available but does not activate it.
+     * Call activate() to start the app's runtime extensions.
+     */
+    register(manifest: AppManifest): AppRegistration;
+    /**
+     * Activate an app.
+     *
+     * Activating an app:
+     * 1. Creates an AppContext for sandboxed runtime access
+     * 2. Registers the app's actions with ExecutorRegistry
+     * 3. Registers the app's widgets with WidgetRegistry
+     * 4. Sets up the app's event handlers
+     */
+    activate(appId: string): Promise<void>;
+    /**
+     * Deactivate an app.
+     *
+     * Deactivating an app:
+     * 1. Runs the cleanup function
+     * 2. Unregisters all actions and widgets
+     * 3. Removes event handlers
+     */
+    deactivate(appId: string): Promise<void>;
+    /**
+     * Unregister an app.
+     *
+     * The app must be inactive before it can be unregistered.
+     */
+    unregister(appId: string): Promise<void>;
+    /**
+     * Get an app registration.
+     */
+    get(appId: string): AppRegistration | undefined;
+    /**
+     * Check if an app is registered.
+     */
+    has(appId: string): boolean;
+    /**
+     * Check if an app is active.
+     */
+    isActive(appId: string): boolean;
+    /**
+     * List all registered apps.
+     */
+    list(): AppRegistration[];
+    /**
+     * List all active apps.
+     */
+    listActive(): AppRegistration[];
+    /**
+     * List all apps with editor modules.
+     */
+    listEditable(): AppRegistration[];
+    /**
+     * Subscribe to registry events.
+     */
+    subscribe(callback: AppRegistryEventCallback): () => void;
+    /**
+     * Emit an event to all listeners.
+     */
+    private emit;
+    /**
+     * Clean up all apps.
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * Default singleton instance of AppRegistry.
+ */
+export declare const appRegistry: AppRegistry;

package/dist/apps/AppRegistry.js

@@ -0,0 +1,317 @@
+/**
+ * App Registry
+ *
+ * Central registry for managing SynOS apps.
+ * Handles app registration, activation, deactivation, and lifecycle management.
+ */
+import { createAppContext, cleanupAppContext } from "./AppContext";
+/**
+ * App registry for managing SynOS apps.
+ */
+export class AppRegistry {
+    constructor() {
+        this.apps = new Map();
+        this.eventListeners = new Set();
+        this.runtime = null;
+    }
+    /**
+     * Bind the registry to a runtime instance.
+     * Must be called before apps can be activated.
+     */
+    bind(runtime) {
+        this.runtime = runtime;
+    }
+    /**
+     * Unbind from the current runtime.
+     * Deactivates all active apps first.
+     */
+    async unbind() {
+        // Deactivate all active apps
+        for (const [appId, registration] of this.apps) {
+            if (registration.state === "active") {
+                await this.deactivate(appId);
+            }
+        }
+        this.runtime = null;
+    }
+    /**
+     * Register an app.
+     *
+     * Registration makes the app available but does not activate it.
+     * Call activate() to start the app's runtime extensions.
+     */
+    register(manifest) {
+        // Validate manifest
+        if (!manifest.id || typeof manifest.id !== "string") {
+            throw new Error("App manifest must have an 'id' property");
+        }
+        if (!manifest.version || typeof manifest.version !== "string") {
+            throw new Error("App manifest must have a 'version' property");
+        }
+        if (!manifest.name || typeof manifest.name !== "string") {
+            throw new Error("App manifest must have a 'name' property");
+        }
+        // Check for existing registration
+        if (this.apps.has(manifest.id)) {
+            const existing = this.apps.get(manifest.id);
+            if (existing.state === "active") {
+                throw new Error(`Cannot re-register active app: ${manifest.id}`);
+            }
+            console.warn(`[AppRegistry] Overriding existing app registration: ${manifest.id}`);
+        }
+        // Create registration
+        const registration = {
+            manifest,
+            state: "registered",
+            registeredAt: Date.now(),
+        };
+        this.apps.set(manifest.id, registration);
+        // Emit event
+        this.emit({
+            type: "app:registered",
+            appId: manifest.id,
+            manifest,
+        });
+        return registration;
+    }
+    /**
+     * Activate an app.
+     *
+     * Activating an app:
+     * 1. Creates an AppContext for sandboxed runtime access
+     * 2. Registers the app's actions with ExecutorRegistry
+     * 3. Registers the app's widgets with WidgetRegistry
+     * 4. Sets up the app's event handlers
+     */
+    async activate(appId) {
+        var _a;
+        const registration = this.apps.get(appId);
+        if (!registration) {
+            throw new Error(`App not registered: ${appId}`);
+        }
+        if (registration.state === "active") {
+            console.warn(`[AppRegistry] App already active: ${appId}`);
+            return;
+        }
+        if (!this.runtime) {
+            throw new Error("AppRegistry not bound to a runtime. Call bind() first.");
+        }
+        // Check dependencies
+        if (registration.manifest.dependencies) {
+            for (const depId of registration.manifest.dependencies) {
+                const dep = this.apps.get(depId);
+                if (!dep || dep.state !== "active") {
+                    throw new Error(`App ${appId} depends on ${depId}, which is not active`);
+                }
+            }
+        }
+        // Update state
+        registration.state = "activating";
+        try {
+            // Create app context
+            const isBuiltIn = ((_a = registration.manifest.metadata) === null || _a === void 0 ? void 0 : _a.isBuiltIn) === true;
+            const context = createAppContext({
+                appId,
+                runtime: this.runtime,
+                isBuiltIn,
+            });
+            // Register runtime extensions
+            const { runtime: runtimeExtensions } = registration.manifest;
+            const cleanupFns = [];
+            if (runtimeExtensions) {
+                // Register actions
+                if (runtimeExtensions.actions) {
+                    for (const actionDef of runtimeExtensions.actions) {
+                        context.registerAction(actionDef);
+                    }
+                }
+                // Register widgets
+                if (runtimeExtensions.widgets) {
+                    for (const widgetDef of runtimeExtensions.widgets) {
+                        context.registerWidget(widgetDef);
+                    }
+                }
+                // Set up event handlers
+                if (runtimeExtensions.events) {
+                    for (const handler of runtimeExtensions.events) {
+                        const unsubscribe = this.runtime.events.subscribe((event) => {
+                            if (handler.names.includes(event.name)) {
+                                const eventContext = {
+                                    appId,
+                                    state: context.state,
+                                    telemetry: context.telemetry,
+                                    surfaces: context.surfaces,
+                                };
+                                try {
+                                    handler.handler(event, eventContext);
+                                }
+                                catch (error) {
+                                    console.error(`[AppRegistry] Event handler error in ${appId}:`, error);
+                                }
+                            }
+                        });
+                        cleanupFns.push(unsubscribe);
+                    }
+                }
+            }
+            // Store cleanup function
+            registration.cleanup = async () => {
+                // Run cleanup functions
+                for (const fn of cleanupFns) {
+                    try {
+                        await fn();
+                    }
+                    catch (error) {
+                        console.error(`[AppRegistry] Cleanup error in ${appId}:`, error);
+                    }
+                }
+                // Clean up app context resources
+                cleanupAppContext(appId, this.runtime);
+            };
+            // Update state
+            registration.state = "active";
+            registration.activatedAt = Date.now();
+            // Emit event
+            this.emit({ type: "app:activated", appId });
+        }
+        catch (error) {
+            registration.state = "error";
+            registration.error = String(error);
+            this.emit({ type: "app:error", appId, error: String(error) });
+            throw error;
+        }
+    }
+    /**
+     * Deactivate an app.
+     *
+     * Deactivating an app:
+     * 1. Runs the cleanup function
+     * 2. Unregisters all actions and widgets
+     * 3. Removes event handlers
+     */
+    async deactivate(appId) {
+        var _a;
+        const registration = this.apps.get(appId);
+        if (!registration) {
+            throw new Error(`App not registered: ${appId}`);
+        }
+        if (registration.state !== "active") {
+            console.warn(`[AppRegistry] App not active: ${appId}`);
+            return;
+        }
+        // Check if any active apps depend on this one
+        for (const [otherId, other] of this.apps) {
+            if (other.state === "active" && ((_a = other.manifest.dependencies) === null || _a === void 0 ? void 0 : _a.includes(appId))) {
+                throw new Error(`Cannot deactivate ${appId}: app ${otherId} depends on it`);
+            }
+        }
+        // Update state
+        registration.state = "deactivating";
+        try {
+            // Run cleanup
+            if (registration.cleanup) {
+                await registration.cleanup();
+                registration.cleanup = undefined;
+            }
+            // Update state
+            registration.state = "inactive";
+            // Emit event
+            this.emit({ type: "app:deactivated", appId });
+        }
+        catch (error) {
+            registration.state = "error";
+            registration.error = String(error);
+            this.emit({ type: "app:error", appId, error: String(error) });
+            throw error;
+        }
+    }
+    /**
+     * Unregister an app.
+     *
+     * The app must be inactive before it can be unregistered.
+     */
+    async unregister(appId) {
+        const registration = this.apps.get(appId);
+        if (!registration) {
+            return;
+        }
+        if (registration.state === "active") {
+            await this.deactivate(appId);
+        }
+        this.apps.delete(appId);
+        // Emit event
+        this.emit({ type: "app:unregistered", appId });
+    }
+    /**
+     * Get an app registration.
+     */
+    get(appId) {
+        return this.apps.get(appId);
+    }
+    /**
+     * Check if an app is registered.
+     */
+    has(appId) {
+        return this.apps.has(appId);
+    }
+    /**
+     * Check if an app is active.
+     */
+    isActive(appId) {
+        const registration = this.apps.get(appId);
+        return (registration === null || registration === void 0 ? void 0 : registration.state) === "active";
+    }
+    /**
+     * List all registered apps.
+     */
+    list() {
+        return Array.from(this.apps.values());
+    }
+    /**
+     * List all active apps.
+     */
+    listActive() {
+        return Array.from(this.apps.values()).filter((r) => r.state === "active");
+    }
+    /**
+     * List all apps with editor modules.
+     */
+    listEditable() {
+        return Array.from(this.apps.values()).filter((r) => r.manifest.editor !== undefined);
+    }
+    /**
+     * Subscribe to registry events.
+     */
+    subscribe(callback) {
+        this.eventListeners.add(callback);
+        return () => {
+            this.eventListeners.delete(callback);
+        };
+    }
+    /**
+     * Emit an event to all listeners.
+     */
+    emit(event) {
+        for (const listener of this.eventListeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.error("[AppRegistry] Event listener error:", error);
+            }
+        }
+    }
+    /**
+     * Clean up all apps.
+     */
+    async destroy() {
+        await this.unbind();
+        this.apps.clear();
+        this.eventListeners.clear();
+    }
+}
+/**
+ * Default singleton instance of AppRegistry.
+ */
+export const appRegistry = new AppRegistry();
+//# sourceMappingURL=AppRegistry.js.map