skeleton-crew-runtime 0.1.1

package/dist/runtime.js

@@ -0,0 +1,257 @@
+import { ConsoleLogger, RuntimeState } from './types.js';
+import { PluginRegistry } from './plugin-registry.js';
+import { ScreenRegistry } from './screen-registry.js';
+import { ActionEngine } from './action-engine.js';
+import { EventBus } from './event-bus.js';
+import { UIBridge } from './ui-bridge.js';
+import { RuntimeContextImpl } from './runtime-context.js';
+/**
+ * Runtime is the main orchestrator that coordinates all subsystems.
+ * Handles initialization, shutdown, and lifecycle state tracking.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 3.1, 3.5, 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 9.7, 9.9, 15.1, 15.3, 15.5, 16.1, 16.2, 16.3, 16.4, 16.5
+ */
+export class Runtime {
+    plugins;
+    screens;
+    actions;
+    events;
+    ui;
+    context;
+    initialized = false;
+    pendingPlugins = [];
+    logger;
+    state = RuntimeState.Uninitialized;
+    hostContext;
+    /**
+     * Creates a new Runtime instance with optional configuration.
+     *
+     * @param options - Optional configuration object
+     * @param options.logger - Custom logger implementation (defaults to ConsoleLogger)
+     * @param options.hostContext - Host application services to inject (defaults to empty object)
+     *
+     * Requirements: 1.1, 1.5, 7.1, 7.2, 7.3, 7.4, 7.5, 7.6
+     */
+    constructor(options) {
+        this.logger = options?.logger ?? new ConsoleLogger();
+        this.hostContext = options?.hostContext ?? {};
+        this.validateHostContext(this.hostContext);
+    }
+    /**
+     * Validates host context and logs warnings for common mistakes.
+     * Does not throw errors or modify the context.
+     *
+     * @param context - The host context to validate
+     *
+     * Requirements: 2.1, 2.2, 2.3, 2.4
+     */
+    validateHostContext(context) {
+        // Fast path for empty context
+        if (Object.keys(context).length === 0) {
+            return;
+        }
+        // Check each key in the context
+        Object.entries(context).forEach(([key, value]) => {
+            // Check for large objects (> 1MB)
+            try {
+                const size = JSON.stringify(value).length;
+                if (size > 1024 * 1024) {
+                    this.logger.warn(`Host context key "${key}" is large (${size} bytes)`);
+                }
+            }
+            catch (error) {
+                // JSON.stringify can fail for circular references or other issues
+                // Log but don't fail validation
+                this.logger.warn(`Host context key "${key}" could not be serialized for size check`);
+            }
+            // Check for function values
+            if (typeof value === 'function') {
+                this.logger.warn(`Host context key "${key}" is a function. Consider wrapping it in an object.`);
+            }
+        });
+    }
+    /**
+     * Registers a plugin before initialization.
+     * Plugins registered this way will have their setup callbacks executed during initialize().
+     *
+     * @param plugin - The plugin definition to register
+     * @throws Error if runtime is already initialized
+     */
+    registerPlugin(plugin) {
+        if (this.initialized) {
+            throw new Error('Cannot register plugins after initialization. Use context.plugins.registerPlugin() instead.');
+        }
+        this.pendingPlugins.push(plugin);
+    }
+    /**
+     * Initializes the runtime following the strict initialization sequence.
+     * Creates all subsystems in order, then executes plugin setup callbacks.
+     * Emits runtime:initialized event after successful initialization.
+     *
+     * @throws Error if initialize is called twice
+     * @throws Error if any plugin setup fails
+     *
+     * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 3.1, 3.5, 15.1, 15.3, 15.5, 16.1, 16.2, 16.3, 16.4, 16.5, 17.1, 17.2, 17.3
+     */
+    async initialize() {
+        // Throw error if initialize called twice (Requirement 15.1)
+        if (this.initialized) {
+            throw new Error('Runtime already initialized');
+        }
+        // Set state to Initializing (Requirement 16.2)
+        this.state = RuntimeState.Initializing;
+        try {
+            // Strict initialization sequence (Requirements 2.1, 2.2, 2.3, 2.4)
+            // 1. Create PluginRegistry (Requirement 2.1)
+            this.plugins = new PluginRegistry(this.logger);
+            // Register pending plugins
+            for (const plugin of this.pendingPlugins) {
+                this.plugins.registerPlugin(plugin);
+            }
+            this.pendingPlugins = [];
+            // 2. Create ScreenRegistry (Requirement 2.2)
+            this.screens = new ScreenRegistry(this.logger);
+            // 3. Create ActionEngine (Requirement 2.3)
+            this.actions = new ActionEngine(this.logger);
+            // 4. Create EventBus (Requirement 2.4)
+            this.events = new EventBus(this.logger);
+            // 5. Create UIBridge
+            this.ui = new UIBridge(this.logger);
+            // 6. Create RuntimeContext after all subsystems (Requirements 1.2, 2.4, 9.7)
+            this.context = new RuntimeContextImpl(this.screens, this.actions, this.plugins, this.events, this, this.hostContext);
+            // 7. Pass RuntimeContext to ActionEngine (Requirement 9.9)
+            this.actions.setContext(this.context);
+            // 8. Execute plugin setup callbacks in registration order (Requirements 2.5, 2.6, 3.1)
+            // This will abort on first plugin setup failure (Requirement 3.1)
+            await this.plugins.executeSetup(this.context);
+            // Mark as initialized
+            this.initialized = true;
+            // Set state to Initialized (Requirement 16.2)
+            this.state = RuntimeState.Initialized;
+            // Emit runtime:initialized event (Requirements 17.1, 17.2, 17.3)
+            this.events.emit('runtime:initialized', { context: this.context });
+        }
+        catch (error) {
+            // Reset state to Uninitialized on failure (Requirement 16.5)
+            this.state = RuntimeState.Uninitialized;
+            throw error;
+        }
+    }
+    /**
+     * Shuts down the runtime following the strict shutdown sequence.
+     * Emits runtime:shutdown event at start of shutdown.
+     * Disposes initialized plugins, shuts down UI provider, clears all registries, and releases resources.
+     * Safe to call multiple times (idempotent).
+     *
+     * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 9.5, 15.2, 15.4, 15.6, 16.1, 16.2, 16.3, 16.4, 16.5, 17.4, 17.5
+     */
+    async shutdown() {
+        // Make shutdown idempotent - safe to call multiple times (Requirement 4.5)
+        if (!this.initialized) {
+            return;
+        }
+        // Set state to ShuttingDown (Requirement 16.4)
+        this.state = RuntimeState.ShuttingDown;
+        // Emit runtime:shutdown event (Requirements 17.4, 17.5)
+        this.events.emit('runtime:shutdown', { context: this.context });
+        // 1. Execute dispose callbacks only for initialized plugins (Requirements 4.2, 4.3)
+        // Dispose errors are logged but do not prevent cleanup (Requirement 4.4)
+        await this.plugins.executeDispose(this.context);
+        // 2. Shutdown UI provider before clearing registries (Requirement 9.5)
+        // Handle shutdown errors gracefully - errors are logged but do not prevent cleanup
+        try {
+            await this.ui.shutdown();
+        }
+        catch (error) {
+            this.logger.error('UIBridge shutdown failed', error);
+        }
+        // 3. Clear all registries (Requirement 4.5)
+        this.screens.clear();
+        this.actions.clear();
+        this.events.clear();
+        this.plugins.clear();
+        // 4. Set initialized flag to false (Requirement 4.5)
+        this.initialized = false;
+        // Set state to Shutdown (Requirement 16.4)
+        this.state = RuntimeState.Shutdown;
+    }
+    /**
+     * Returns the RuntimeContext for this runtime instance.
+     *
+     * @returns The RuntimeContext
+     * @throws Error if runtime is not initialized
+     *
+     * Requirement: 9.1
+     */
+    getContext() {
+        if (!this.initialized) {
+            throw new Error('Runtime not initialized');
+        }
+        return this.context;
+    }
+    /**
+     * Returns whether the runtime has been initialized.
+     *
+     * @returns true if runtime is initialized, false otherwise
+     *
+     * Requirements: 16.1, 16.2, 16.3
+     */
+    isInitialized() {
+        return this.state === RuntimeState.Initialized;
+    }
+    /**
+     * Returns the current lifecycle state of the runtime.
+     *
+     * @returns The current RuntimeState
+     *
+     * Requirements: 16.1, 16.2, 16.3, 16.4, 16.5
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Registers a UI provider with the runtime.
+     * Delegates to UIBridge subsystem.
+     * Can be called after initialization completes.
+     *
+     * @param provider - The UI provider implementation
+     * @throws Error if provider is invalid or already registered
+     *
+     * Requirements: 10.3, 10.9
+     */
+    setUIProvider(provider) {
+        this.ui.setProvider(provider);
+    }
+    /**
+     * Returns the registered UI provider.
+     * Delegates to UIBridge subsystem.
+     *
+     * @returns The registered UIProvider or null if none registered
+     *
+     * Requirement: 10.4
+     */
+    getUIProvider() {
+        return this.ui.getProvider();
+    }
+    /**
+     * Renders a screen by looking it up in the ScreenRegistry and delegating to UIBridge.
+     *
+     * @param screenId - The screen identifier to render
+     * @returns The result from the UI provider's render method
+     * @throws Error if screen is not found
+     * @throws Error if no UI provider is registered
+     *
+     * Requirement: 10.5
+     */
+    renderScreen(screenId) {
+        // Look up the screen in the registry
+        const screen = this.screens.getScreen(screenId);
+        // Throw if screen not found
+        if (screen === null) {
+            throw new Error(`Screen with id "${screenId}" not found`);
+        }
+        // Delegate to UIBridge to render the screen
+        return this.ui.renderScreen(screen);
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/screen-registry.d.ts

@@ -0,0 +1,51 @@
+import type { ScreenDefinition, Logger } from './types.js';
+/**
+ * ScreenRegistry subsystem for managing screen definitions.
+ * Provides O(1) lookup performance using Map-based storage.
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 13.1, 13.5, 16.1
+ */
+export declare class ScreenRegistry {
+    private screens;
+    private logger;
+    constructor(logger: Logger);
+    /**
+     * Registers a screen definition.
+     * Validates required fields and rejects duplicate IDs.
+     * Returns an unregister function that removes the screen when called.
+     *
+     * @param screen - The screen definition to register
+     * @returns A function that unregisters the screen when called
+     * @throws ValidationError if screen is missing required fields (id, title, component)
+     * @throws DuplicateRegistrationError if a screen with the same ID is already registered
+     *
+     * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 5.2, 5.5, 5.7, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6, 15.1, 15.2, 15.3, 15.4, 15.5, 16.1, 18.1, 18.2, 18.3, 18.4, 18.5
+     */
+    registerScreen(screen: ScreenDefinition): () => void;
+    /**
+     * Retrieves a screen definition by ID.
+     *
+     * @param id - The screen identifier
+     * @returns The screen definition or null if not found
+     *
+     * Requirements: 5.3, 5.6, 13.1
+     */
+    getScreen(id: string): ScreenDefinition | null;
+    /**
+     * Retrieves all registered screen definitions.
+     * Returns a copy to ensure data isolation.
+     *
+     * @returns Array copy of all registered screen definitions
+     *
+     * Requirements: 5.4, 10.1, 10.2, 10.3, 10.4, 10.5
+     */
+    getAllScreens(): ScreenDefinition[];
+    /**
+     * Clears all registered screens.
+     * Used during shutdown to release resources.
+     *
+     * Requirement: 13.5
+     */
+    clear(): void;
+}
+//# sourceMappingURL=screen-registry.d.ts.map

package/dist/screen-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-registry.d.ts","sourceRoot":"","sources":["../src/screen-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAG3D;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM;IAK1B;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,IAAI;IA2BpD;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAI9C;;;;;;;OAOG;IACH,aAAa,IAAI,gBAAgB,EAAE;IAInC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/screen-registry.js

@@ -0,0 +1,82 @@
+import { ValidationError, DuplicateRegistrationError } from './types.js';
+/**
+ * ScreenRegistry subsystem for managing screen definitions.
+ * Provides O(1) lookup performance using Map-based storage.
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 13.1, 13.5, 16.1
+ */
+export class ScreenRegistry {
+    screens;
+    logger;
+    constructor(logger) {
+        this.screens = new Map();
+        this.logger = logger;
+    }
+    /**
+     * Registers a screen definition.
+     * Validates required fields and rejects duplicate IDs.
+     * Returns an unregister function that removes the screen when called.
+     *
+     * @param screen - The screen definition to register
+     * @returns A function that unregisters the screen when called
+     * @throws ValidationError if screen is missing required fields (id, title, component)
+     * @throws DuplicateRegistrationError if a screen with the same ID is already registered
+     *
+     * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 5.2, 5.5, 5.7, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6, 15.1, 15.2, 15.3, 15.4, 15.5, 16.1, 18.1, 18.2, 18.3, 18.4, 18.5
+     */
+    registerScreen(screen) {
+        // Validate required fields before any state modification (Requirements 18.1, 18.2, 18.3, 18.5)
+        if (!screen.id || typeof screen.id !== 'string') {
+            throw new ValidationError('Screen', 'id');
+        }
+        if (!screen.title || typeof screen.title !== 'string') {
+            throw new ValidationError('Screen', 'title', screen.id);
+        }
+        if (!screen.component || typeof screen.component !== 'string') {
+            throw new ValidationError('Screen', 'component', screen.id);
+        }
+        // Check for duplicate ID (Requirements 15.1, 15.2, 15.3, 15.4, 15.5)
+        if (this.screens.has(screen.id)) {
+            throw new DuplicateRegistrationError('Screen', screen.id);
+        }
+        // Register the screen
+        this.screens.set(screen.id, screen);
+        this.logger.debug(`Screen "${screen.id}" registered successfully`);
+        // Return idempotent unregister function (Requirements 4.1, 4.2, 4.3, 4.4, 4.5)
+        return () => {
+            this.screens.delete(screen.id);
+        };
+    }
+    /**
+     * Retrieves a screen definition by ID.
+     *
+     * @param id - The screen identifier
+     * @returns The screen definition or null if not found
+     *
+     * Requirements: 5.3, 5.6, 13.1
+     */
+    getScreen(id) {
+        return this.screens.get(id) ?? null;
+    }
+    /**
+     * Retrieves all registered screen definitions.
+     * Returns a copy to ensure data isolation.
+     *
+     * @returns Array copy of all registered screen definitions
+     *
+     * Requirements: 5.4, 10.1, 10.2, 10.3, 10.4, 10.5
+     */
+    getAllScreens() {
+        return Array.from(this.screens.values());
+    }
+    /**
+     * Clears all registered screens.
+     * Used during shutdown to release resources.
+     *
+     * Requirement: 13.5
+     */
+    clear() {
+        this.screens.clear();
+    }
+}
+//# sourceMappingURL=screen-registry.js.map

package/dist/screen-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-registry.js","sourceRoot":"","sources":["../src/screen-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACjB,OAAO,CAAgC;IACvC,MAAM,CAAS;IAEvB,YAAY,MAAc;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,MAAwB;QACrC,+FAA+F;QAC/F,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACtD,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YAC9D,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC9D,CAAC;QAED,qEAAqE;QACrE,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,0BAA0B,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,sBAAsB;QACtB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,MAAM,CAAC,EAAE,2BAA2B,CAAC,CAAC;QAEnE,+EAA+E;QAC/E,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACjC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;IACtC,CAAC;IAED;;;;;;;OAOG;IACH,aAAa;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Error thrown when validation fails for a resource
+ * @see Requirements 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
+ */
+export declare class ValidationError extends Error {
+    resourceType: string;
+    field: string;
+    resourceId?: string | undefined;
+    constructor(resourceType: string, field: string, resourceId?: string | undefined);
+}
+/**
+ * Error thrown when attempting to register a duplicate resource
+ * @see Requirements 15.1, 15.2, 15.3, 15.4, 15.5
+ */
+export declare class DuplicateRegistrationError extends Error {
+    resourceType: string;
+    identifier: string;
+    constructor(resourceType: string, identifier: string);
+}
+/**
+ * Error thrown when an action execution exceeds its timeout
+ * @see Requirements 11.1, 11.2, 11.3, 11.4, 11.5
+ */
+export declare class ActionTimeoutError extends Error {
+    actionId: string;
+    timeoutMs: number;
+    constructor(actionId: string, timeoutMs: number);
+}
+/**
+ * Error thrown when an action handler throws an error
+ * @see Requirements 3.1, 3.2, 3.3, 3.4, 3.5
+ */
+export declare class ActionExecutionError extends Error {
+    actionId: string;
+    cause: Error;
+    constructor(actionId: string, cause: Error);
+}
+/**
+ * Logger interface for pluggable logging implementations
+ * @see Requirements 7.1, 7.2, 7.3, 7.4, 7.5, 7.6
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Default console-based logger implementation
+ * @see Requirements 7.1, 7.2, 7.3, 7.4, 7.5, 7.6
+ */
+export declare class ConsoleLogger implements Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Runtime lifecycle states
+ * @see Requirements 16.1, 16.2, 16.3, 16.4, 16.5
+ */
+export declare enum RuntimeState {
+    Uninitialized = "uninitialized",
+    Initializing = "initializing",
+    Initialized = "initialized",
+    ShuttingDown = "shutting_down",
+    Shutdown = "shutdown"
+}
+export interface PluginDefinition {
+    name: string;
+    version: string;
+    setup: (context: RuntimeContext) => void | Promise<void>;
+    dispose?: (context: RuntimeContext) => void | Promise<void>;
+}
+export interface ScreenDefinition {
+    id: string;
+    title: string;
+    component: string;
+}
+/**
+ * Action definition with generic type parameters for type-safe action handling
+ * @template P - Payload type (defaults to unknown for backward compatibility)
+ * @template R - Return type (defaults to unknown for backward compatibility)
+ * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 11.1, 11.2, 11.3, 11.4, 11.5
+ */
+export interface ActionDefinition<P = unknown, R = unknown> {
+    id: string;
+    handler: (params: P, context: RuntimeContext) => Promise<R> | R;
+    timeout?: number;
+}
+/**
+ * UIProvider interface with enhanced lifecycle methods
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5
+ */
+export interface UIProvider {
+    mount(target: unknown, context: RuntimeContext): void | Promise<void>;
+    renderScreen(screen: ScreenDefinition): unknown | Promise<unknown>;
+    unmount?(): void | Promise<void>;
+}
+/**
+ * RuntimeContext provides a safe API facade for subsystems.
+ * @see Requirements 4.1, 4.2, 4.3, 4.4, 4.5, 10.1, 10.2, 10.3, 10.4, 10.5, 12.1, 12.2, 12.3, 12.4, 12.5, 13.1, 13.2, 13.3, 13.4, 13.5
+ */
+export interface RuntimeContext {
+    screens: {
+        registerScreen(screen: ScreenDefinition): () => void;
+        getScreen(id: string): ScreenDefinition | null;
+        getAllScreens(): ScreenDefinition[];
+    };
+    actions: {
+        registerAction<P = unknown, R = unknown>(action: ActionDefinition<P, R>): () => void;
+        runAction<P = unknown, R = unknown>(id: string, params?: P): Promise<R>;
+    };
+    plugins: {
+        registerPlugin(plugin: PluginDefinition): void;
+        getPlugin(name: string): PluginDefinition | null;
+        getAllPlugins(): PluginDefinition[];
+        getInitializedPlugins(): string[];
+    };
+    events: {
+        emit(event: string, data?: unknown): void;
+        emitAsync(event: string, data?: unknown): Promise<void>;
+        on(event: string, handler: (data: unknown) => void): () => void;
+    };
+    getRuntime(): Runtime;
+    /**
+     * Readonly access to host context injected at runtime initialization
+     * @see Requirements 1.3, 1.4, 9.2
+     */
+    readonly host: Readonly<Record<string, unknown>>;
+    /**
+     * Introspection API for querying runtime metadata
+     * @see Requirements 3.1, 4.1, 5.1, 6.1, 9.2
+     */
+    readonly introspect: IntrospectionAPI;
+}
+export interface Runtime {
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    getContext(): RuntimeContext;
+}
+/**
+ * Runtime initialization options
+ * @see Requirements 1.1, 9.1
+ */
+export interface RuntimeOptions {
+    logger?: Logger;
+    hostContext?: Record<string, unknown>;
+}
+/**
+ * Action metadata returned by introspection (excludes handler function)
+ * @see Requirements 3.2, 3.4, 3.5, 9.3
+ */
+export interface ActionMetadata {
+    id: string;
+    timeout?: number;
+}
+/**
+ * Plugin metadata returned by introspection (excludes setup/dispose functions)
+ * @see Requirements 4.2, 4.4, 4.5, 9.4
+ */
+export interface PluginMetadata {
+    name: string;
+    version: string;
+}
+/**
+ * Runtime metadata with overall statistics
+ * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 9.5
+ */
+export interface IntrospectionMetadata {
+    runtimeVersion: string;
+    totalActions: number;
+    totalPlugins: number;
+    totalScreens: number;
+}
+/**
+ * Introspection API for querying runtime metadata
+ * @see Requirements 3.1, 4.1, 5.1, 6.1, 9.2
+ */
+export interface IntrospectionAPI {
+    listActions(): string[];
+    getActionDefinition(id: string): ActionMetadata | null;
+    listPlugins(): string[];
+    getPluginDefinition(name: string): PluginMetadata | null;
+    listScreens(): string[];
+    getScreenDefinition(id: string): ScreenDefinition | null;
+    getMetadata(): IntrospectionMetadata;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}