@almadar/runtime 3.2.3 → 3.2.5

package/dist/index.d.ts

@@ -1,12 +1,138 @@
 import { B as BindingContext, E as EvaluationContextExtensions, P as PatternProps, a as EffectHandlers, b as EffectContext, c as ExecutionEnvironment, d as EffectResult, T as TraitDefinition } from './types-B8OfRFfV.js';
 export { e as Effect, f as EventListener, H as HANDLER_MANIFEST, I as IEventBus, R as RuntimeConfig, g as RuntimeEvent, h as TraitState, i as TransitionObserver, j as TransitionResult, U as Unsubscribe } from './types-B8OfRFfV.js';
-export { E as EntitySharingMap, a as EventBus, b as EventNamespaceMap, O as OrbitalEventRequest, c as OrbitalEventResponse, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, e as PreprocessOptions, f as PreprocessResult, g as PreprocessedSchema, h as ProcessEventOptions, R as RegisteredOrbital, i as RuntimeOrbital, j as RuntimeOrbitalSchema, k as RuntimeTrait, S as StateMachineManager, l as createInitialTraitState, m as findInitialState, n as findTransition, o as getIsolatedCollectionName, p as getNamespacedEvent, q as isNamespacedEvent, r as normalizeEventKey, s as parseNamespacedEvent, t as preprocessSchema, u as processEvent } from './OrbitalServerRuntime-RHykAuqO.js';
+import { U as UnifiedLoaderOptions, S as SchemaLoader, I as ImportChainLike, L as LoadResult, a as LoadedSchema, b as LoadedOrbital } from './OrbitalServerRuntime-DMRvEfcT.js';
+export { E as EntitySharingMap, c as EventBus, d as EventNamespaceMap, O as OrbitalEventRequest, e as OrbitalEventResponse, f as OrbitalServerRuntimeConfig, P as PersistenceAdapter, g as PreprocessOptions, h as PreprocessResult, i as PreprocessedSchema, j as ProcessEventOptions, R as RegisteredOrbital, k as RuntimeOrbital, l as RuntimeOrbitalSchema, m as RuntimeTrait, n as StateMachineManager, o as createInitialTraitState, p as findInitialState, q as findTransition, r as getIsolatedCollectionName, s as getNamespacedEvent, t as isBrowser, u as isElectron, v as isNamespacedEvent, w as isNode, x as normalizeEventKey, y as parseNamespacedEvent, z as preprocessSchema, A as processEvent } from './OrbitalServerRuntime-DMRvEfcT.js';
 import { EvaluationContext } from '@almadar/evaluator';
 export { EvaluationContext, createMinimalContext } from '@almadar/evaluator';
 import { EventPayload, EntityRow, OrbitalDefinition, OrbitalSchema } from '@almadar/core';
 export { ServerBridgeConfig, ServerBridgeState } from './ServerBridge.js';
 import 'express';
 
+/**
+ * Unified Schema Loader
+ *
+ * Auto-detects the environment and routes to the appropriate loader:
+ * - FileSystemLoader for Node.js/Electron
+ * - HttpLoader for browser
+ *
+ * Also handles mixed loading scenarios where some imports use filesystem
+ * and others use HTTP.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * UnifiedLoader - Auto-detects environment and routes to appropriate loader.
+ *
+ * Loading Strategy:
+ * - Electron: Uses FileSystemLoader with HTTP fallback for remote URLs
+ * - Browser: Uses HttpLoader only (no filesystem access)
+ * - Node.js: Uses FileSystemLoader with HTTP for remote URLs
+ *
+ * Import Type Resolution:
+ * - `./local.orb`: FileSystem (Node/Electron) or Error (Browser)
+ * - `std/behaviors/x`: FileSystem OR HTTP (configurable)
+ * - `@scope/pkg.orb`: FileSystem OR HTTP (configurable)
+ * - `https://...`: Always HTTP
+ *
+ * @example
+ * ```typescript
+ * const loader = createUnifiedLoader({
+ *   basePath: "/project/schemas",
+ *   stdLibPath: "/project/std",  // or "https://cdn.example.com/std"
+ * });
+ *
+ * // Load relative file (uses FileSystem in Node, error in Browser)
+ * const local = await loader.load("./my-schema.orb");
+ *
+ * // Load from URL (always uses HTTP)
+ * const remote = await loader.load("https://example.com/schema.orb");
+ *
+ * // Load from std library (uses configured path type)
+ * const std = await loader.load("std/behaviors/game-core");
+ * ```
+ */
+declare class UnifiedLoader implements SchemaLoader {
+    private options;
+    private httpLoader;
+    private fsLoader;
+    private fsLoaderInitialized;
+    private cache;
+    constructor(options: UnifiedLoaderOptions);
+    /**
+     * Initialize the filesystem loader if available.
+     */
+    private initFsLoader;
+    /**
+     * Determine which loader to use for an import path.
+     */
+    private getLoaderForPath;
+    /**
+     * Load a schema from an import path.
+     *
+     * Note: We delegate chain management to the inner loader (HttpLoader or FsLoader).
+     * The inner loader handles circular import detection, so we don't push/pop here.
+     * We only use the unified cache to avoid duplicate loads across loaders.
+     */
+    load(importPath: string, fromPath?: string, chain?: ImportChainLike): Promise<LoadResult<LoadedSchema>>;
+    /**
+     * Load a specific orbital from a schema by name.
+     */
+    loadOrbital(importPath: string, orbitalName?: string, fromPath?: string, chain?: ImportChainLike): Promise<LoadResult<LoadedOrbital>>;
+    /**
+     * Resolve an import path to an absolute path/URL.
+     */
+    resolvePath(importPath: string, fromPath?: string): LoadResult<string>;
+    /**
+     * Clear all caches.
+     */
+    clearCache(): void;
+    /**
+     * Get combined cache statistics.
+     */
+    getCacheStats(): {
+        size: number;
+    };
+    /**
+     * Check if filesystem loading is available.
+     */
+    hasFilesystemAccess(): Promise<boolean>;
+    /**
+     * Get current environment info.
+     */
+    getEnvironmentInfo(): {
+        isElectron: boolean;
+        isBrowser: boolean;
+        isNode: boolean;
+        hasFilesystem: boolean;
+    };
+}
+/**
+ * Create a unified loader with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const loader = createUnifiedLoader({
+ *   basePath: "/schemas",
+ *   stdLibPath: "/std",
+ * });
+ *
+ * // With HTTP std library
+ * const loader = createUnifiedLoader({
+ *   basePath: "/schemas",
+ *   stdLibPath: "https://cdn.example.com/orbital-std",
+ * });
+ *
+ * // Force HTTP only (browser-like behavior)
+ * const loader = createUnifiedLoader({
+ *   basePath: "/api/schemas",
+ *   forceLoader: "http",
+ * });
+ * ```
+ */
+declare function createUnifiedLoader(options: UnifiedLoaderOptions): UnifiedLoader;
+
 /**
  * BindingResolver - Platform-Agnostic Binding Resolution
  *
@@ -529,4 +655,4 @@ declare namespace index {
   export { type index_ComposeBehaviorsInput as ComposeBehaviorsInput, type index_ComposeBehaviorsResult as ComposeBehaviorsResult, type index_EventWiringEntry as EventWiringEntry, type index_LayoutStrategy as LayoutStrategy, type index_PipeStep as PipeStep, index_applyEventWiring as applyEventWiring, index_composeBehaviors as composeBehaviors, index_detectLayoutStrategy as detectLayoutStrategy, index_pipeBehaviors as pipeBehaviors };
 }
 
-export { BindingContext, type ClientEventBus, type ComposeBehaviorsInput, type ComposeBehaviorsResult, type CreateClientEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntityField, type EntitySchema, type EventWiringEntry, ExecutionEnvironment, type LayoutStrategy, type MockPersistenceConfig, type OsHandlerContext, type OsHandlerResult, type PayloadMismatch, type PipeStep, type SlotSetter, TraitDefinition, applyEventWiring, buildEmitsFromTraits, composeBehaviors, index as composition, containsBindings, createClientEffectHandlers, createContextFromBindings, createTestExecutor, detectLayoutStrategy, extractBindings, interpolateProps, interpolateValue, pipeBehaviors, validatePayloadShapes };
+export { BindingContext, type ClientEventBus, type ComposeBehaviorsInput, type ComposeBehaviorsResult, type CreateClientEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntityField, type EntitySchema, type EventWiringEntry, ExecutionEnvironment, ImportChainLike, type LayoutStrategy, LoadResult, LoadedOrbital, LoadedSchema, type MockPersistenceConfig, type OsHandlerContext, type OsHandlerResult, type PayloadMismatch, type PipeStep, SchemaLoader, type SlotSetter, TraitDefinition, UnifiedLoaderOptions, applyEventWiring, buildEmitsFromTraits, composeBehaviors, index as composition, containsBindings, createClientEffectHandlers, createContextFromBindings, createTestExecutor, createUnifiedLoader, detectLayoutStrategy, extractBindings, interpolateProps, interpolateValue, pipeBehaviors, validatePayloadShapes };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { EffectExecutor, EventBus, HANDLER_MANIFEST, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createTestExecutor, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-PXASRZKG.js';
+export { EffectExecutor, EventBus, HANDLER_MANIFEST, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createTestExecutor, createUnifiedLoader, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-JMMXSTWF.js';
 import { __export } from './chunk-PZ5AY32C.js';
 import { isInlineTrait } from '@almadar/core';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/runtime",
-  "version": "3.2.3",
+  "version": "3.2.5",
   "description": "Interpreted runtime for Almadar orbital applications (OrbitalServerRuntime)",
   "type": "module",
   "main": "./dist/index.js",