@almadar/runtime 1.0.0

package/dist/index.js

@@ -0,0 +1,1556 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { isEntityReference, parseEntityRef, parseImportedTraitRef, isPageReference, isPageReferenceString, isPageReferenceObject, parsePageRef, OrbitalSchemaSchema } from '@almadar/core';
+import { resolveBinding, evaluate, createMinimalContext, evaluateGuard } from '@almadar/evaluator';
+export { createMinimalContext } from '@almadar/evaluator';
+
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var ImportChain, LoaderCache, ExternalOrbitalLoader;
+var init_external_loader = __esm({
+  "src/loader/external-loader.ts"() {
+    ImportChain = class _ImportChain {
+      chain = [];
+      /**
+       * Try to add a path to the chain.
+       * @returns Error message if circular, null if OK
+       */
+      push(absolutePath) {
+        if (this.chain.includes(absolutePath)) {
+          const cycle = [...this.chain.slice(this.chain.indexOf(absolutePath)), absolutePath];
+          return `Circular import detected: ${cycle.join(" -> ")}`;
+        }
+        this.chain.push(absolutePath);
+        return null;
+      }
+      /**
+       * Remove the last path from the chain.
+       */
+      pop() {
+        this.chain.pop();
+      }
+      /**
+       * Clone the chain for nested loading.
+       */
+      clone() {
+        const newChain = new _ImportChain();
+        newChain.chain = [...this.chain];
+        return newChain;
+      }
+    };
+    LoaderCache = class {
+      cache = /* @__PURE__ */ new Map();
+      get(absolutePath) {
+        return this.cache.get(absolutePath);
+      }
+      set(absolutePath, schema) {
+        this.cache.set(absolutePath, schema);
+      }
+      has(absolutePath) {
+        return this.cache.has(absolutePath);
+      }
+      clear() {
+        this.cache.clear();
+      }
+      get size() {
+        return this.cache.size;
+      }
+    };
+    ExternalOrbitalLoader = class {
+      options;
+      cache;
+      constructor(options) {
+        this.options = {
+          stdLibPath: options.stdLibPath ?? "",
+          scopedPaths: options.scopedPaths ?? {},
+          allowOutsideBasePath: options.allowOutsideBasePath ?? false,
+          ...options
+        };
+        this.cache = new LoaderCache();
+      }
+      /**
+       * Load a schema from an import path.
+       *
+       * @param importPath - The import path (e.g., "./health.orb", "std/behaviors/game-core")
+       * @param fromPath - The path of the file doing the import (for relative resolution)
+       * @param chain - Import chain for circular detection
+       */
+      async load(importPath, fromPath, chain) {
+        const importChain = chain ?? new ImportChain();
+        const resolveResult = this.resolvePath(importPath, fromPath);
+        if (!resolveResult.success) {
+          return resolveResult;
+        }
+        const absolutePath = resolveResult.data;
+        const circularError = importChain.push(absolutePath);
+        if (circularError) {
+          return { success: false, error: circularError };
+        }
+        try {
+          const cached = this.cache.get(absolutePath);
+          if (cached) {
+            return { success: true, data: cached };
+          }
+          const loadResult = await this.loadFile(absolutePath);
+          if (!loadResult.success) {
+            return loadResult;
+          }
+          const loaded = {
+            schema: loadResult.data,
+            sourcePath: absolutePath,
+            importPath
+          };
+          this.cache.set(absolutePath, loaded);
+          return { success: true, data: loaded };
+        } finally {
+          importChain.pop();
+        }
+      }
+      /**
+       * Load a specific orbital from a schema by name.
+       *
+       * @param importPath - The import path
+       * @param orbitalName - The orbital name (optional, defaults to first orbital)
+       * @param fromPath - The path of the file doing the import
+       * @param chain - Import chain for circular detection
+       */
+      async loadOrbital(importPath, orbitalName, fromPath, chain) {
+        const schemaResult = await this.load(importPath, fromPath, chain);
+        if (!schemaResult.success) {
+          return schemaResult;
+        }
+        const schema = schemaResult.data.schema;
+        let orbital;
+        if (orbitalName) {
+          const found = schema.orbitals.find((o) => o.name === orbitalName);
+          if (!found) {
+            return {
+              success: false,
+              error: `Orbital "${orbitalName}" not found in ${importPath}. Available: ${schema.orbitals.map((o) => o.name).join(", ")}`
+            };
+          }
+          orbital = found;
+        } else {
+          if (schema.orbitals.length === 0) {
+            return {
+              success: false,
+              error: `No orbitals found in ${importPath}`
+            };
+          }
+          orbital = schema.orbitals[0];
+        }
+        return {
+          success: true,
+          data: {
+            orbital,
+            sourcePath: schemaResult.data.sourcePath,
+            importPath
+          }
+        };
+      }
+      /**
+       * Resolve an import path to an absolute filesystem path.
+       */
+      resolvePath(importPath, fromPath) {
+        if (importPath.startsWith("std/")) {
+          return this.resolveStdPath(importPath);
+        }
+        if (importPath.startsWith("@")) {
+          return this.resolveScopedPath(importPath);
+        }
+        if (importPath.startsWith("./") || importPath.startsWith("../")) {
+          return this.resolveRelativePath(importPath, fromPath);
+        }
+        if (path.isAbsolute(importPath)) {
+          if (!this.options.allowOutsideBasePath) {
+            return {
+              success: false,
+              error: `Absolute paths not allowed: ${importPath}`
+            };
+          }
+          return { success: true, data: importPath };
+        }
+        return this.resolveRelativePath(`./${importPath}`, fromPath);
+      }
+      /**
+       * Resolve a standard library path.
+       */
+      resolveStdPath(importPath) {
+        if (!this.options.stdLibPath) {
+          return {
+            success: false,
+            error: `Standard library path not configured. Cannot load: ${importPath}`
+          };
+        }
+        const relativePath = importPath.slice(4);
+        let absolutePath = path.join(this.options.stdLibPath, relativePath);
+        if (!absolutePath.endsWith(".orb")) {
+          absolutePath += ".orb";
+        }
+        const normalizedPath = path.normalize(absolutePath);
+        const normalizedStdLib = path.normalize(this.options.stdLibPath);
+        if (!normalizedPath.startsWith(normalizedStdLib)) {
+          return {
+            success: false,
+            error: `Path traversal outside std library: ${importPath}`
+          };
+        }
+        return { success: true, data: absolutePath };
+      }
+      /**
+       * Resolve a scoped package path.
+       */
+      resolveScopedPath(importPath) {
+        const match = importPath.match(/^(@[^/]+)/);
+        if (!match) {
+          return {
+            success: false,
+            error: `Invalid scoped package path: ${importPath}`
+          };
+        }
+        const scope = match[1];
+        const scopeRoot = this.options.scopedPaths[scope];
+        if (!scopeRoot) {
+          return {
+            success: false,
+            error: `Scoped package "${scope}" not configured. Available: ${Object.keys(this.options.scopedPaths).join(", ") || "none"}`
+          };
+        }
+        const relativePath = importPath.slice(scope.length + 1);
+        let absolutePath = path.join(scopeRoot, relativePath);
+        if (!absolutePath.endsWith(".orb")) {
+          absolutePath += ".orb";
+        }
+        const normalizedPath = path.normalize(absolutePath);
+        const normalizedRoot = path.normalize(scopeRoot);
+        if (!normalizedPath.startsWith(normalizedRoot)) {
+          return {
+            success: false,
+            error: `Path traversal outside scoped package: ${importPath}`
+          };
+        }
+        return { success: true, data: absolutePath };
+      }
+      /**
+       * Resolve a relative path.
+       */
+      resolveRelativePath(importPath, fromPath) {
+        const baseDir = fromPath ? path.dirname(fromPath) : this.options.basePath;
+        let absolutePath = path.resolve(baseDir, importPath);
+        if (!absolutePath.endsWith(".orb")) {
+          absolutePath += ".orb";
+        }
+        if (!this.options.allowOutsideBasePath) {
+          const normalizedPath = path.normalize(absolutePath);
+          const normalizedBase = path.normalize(this.options.basePath);
+          if (!normalizedPath.startsWith(normalizedBase)) {
+            return {
+              success: false,
+              error: `Path traversal outside base path: ${importPath}. Base: ${this.options.basePath}`
+            };
+          }
+        }
+        return { success: true, data: absolutePath };
+      }
+      /**
+       * Load and parse an .orb file.
+       */
+      async loadFile(absolutePath) {
+        try {
+          if (!fs.existsSync(absolutePath)) {
+            return {
+              success: false,
+              error: `File not found: ${absolutePath}`
+            };
+          }
+          const content = await fs.promises.readFile(absolutePath, "utf-8");
+          let data;
+          try {
+            data = JSON.parse(content);
+          } catch (e) {
+            return {
+              success: false,
+              error: `Invalid JSON in ${absolutePath}: ${e instanceof Error ? e.message : String(e)}`
+            };
+          }
+          const parseResult = OrbitalSchemaSchema.safeParse(data);
+          if (!parseResult.success) {
+            const errors = parseResult.error.errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
+            return {
+              success: false,
+              error: `Invalid schema in ${absolutePath}:
+${errors}`
+            };
+          }
+          return { success: true, data: parseResult.data };
+        } catch (e) {
+          return {
+            success: false,
+            error: `Failed to load ${absolutePath}: ${e instanceof Error ? e.message : String(e)}`
+          };
+        }
+      }
+      /**
+       * Clear the cache.
+       */
+      clearCache() {
+        this.cache.clear();
+      }
+      /**
+       * Get cache statistics.
+       */
+      getCacheStats() {
+        return { size: this.cache.size };
+      }
+    };
+  }
+});
+
+// src/EventBus.ts
+var EventBus = class {
+  listeners = /* @__PURE__ */ new Map();
+  debug;
+  constructor(options = {}) {
+    this.debug = options.debug ?? false;
+  }
+  /**
+   * Emit an event to all registered listeners
+   */
+  emit(type, payload, source) {
+    const event = {
+      type,
+      payload,
+      timestamp: Date.now(),
+      source
+    };
+    const listeners = this.listeners.get(type);
+    const listenerCount = listeners?.size ?? 0;
+    if (this.debug) {
+      if (listenerCount > 0) {
+        console.log(`[EventBus] Emit: ${type} \u2192 ${listenerCount} listener(s)`, payload);
+      } else {
+        console.warn(`[EventBus] Emit: ${type} (NO LISTENERS)`, payload);
+      }
+    }
+    if (listeners) {
+      const listenersCopy = Array.from(listeners);
+      for (const listener of listenersCopy) {
+        try {
+          listener(event);
+        } catch (error) {
+          console.error(`[EventBus] Error in listener for '${type}':`, error);
+        }
+      }
+    }
+    if (type !== "*") {
+      const wildcardListeners = this.listeners.get("*");
+      if (wildcardListeners) {
+        for (const listener of Array.from(wildcardListeners)) {
+          try {
+            listener(event);
+          } catch (error) {
+            console.error(`[EventBus] Error in wildcard listener:`, error);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Subscribe to an event type
+   */
+  on(type, listener) {
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, /* @__PURE__ */ new Set());
+    }
+    const listeners = this.listeners.get(type);
+    listeners.add(listener);
+    if (this.debug) {
+      console.log(`[EventBus] Subscribed to '${type}', total: ${listeners.size}`);
+    }
+    return () => {
+      listeners.delete(listener);
+      if (this.debug) {
+        console.log(`[EventBus] Unsubscribed from '${type}', remaining: ${listeners.size}`);
+      }
+      if (listeners.size === 0) {
+        this.listeners.delete(type);
+      }
+    };
+  }
+  /**
+   * Subscribe to ALL events (wildcard listener)
+   * Useful for event tracking, logging, debugging
+   */
+  onAny(listener) {
+    return this.on("*", listener);
+  }
+  /**
+   * Check if there are listeners for an event type
+   */
+  hasListeners(type) {
+    const listeners = this.listeners.get(type);
+    return listeners !== void 0 && listeners.size > 0;
+  }
+  /**
+   * Get all registered event types
+   */
+  getRegisteredEvents() {
+    return Array.from(this.listeners.keys());
+  }
+  /**
+   * Clear all listeners
+   */
+  clear() {
+    if (this.debug) {
+      console.log(`[EventBus] Clearing all listeners (${this.listeners.size} event types)`);
+    }
+    this.listeners.clear();
+  }
+  /**
+   * Get listener count for an event type (for testing)
+   */
+  getListenerCount(type) {
+    return this.listeners.get(type)?.size ?? 0;
+  }
+};
+var OPERATORS = /* @__PURE__ */ new Set([
+  // Comparison
+  "=",
+  "!=",
+  "<",
+  ">",
+  "<=",
+  ">=",
+  // Logic
+  "and",
+  "or",
+  "not",
+  "if",
+  // Math
+  "+",
+  "-",
+  "*",
+  "/",
+  "%",
+  // Array
+  "count",
+  "first",
+  "last",
+  "map",
+  "filter",
+  "find",
+  "some",
+  "every",
+  "reduce",
+  // String
+  "concat",
+  "upper",
+  "lower",
+  "trim",
+  "substring",
+  "split",
+  "join",
+  "str",
+  // Effects
+  "set",
+  "emit",
+  "navigate",
+  "persist",
+  "notify",
+  "render-ui",
+  "render",
+  "spawn",
+  "despawn",
+  "call-service",
+  "do",
+  "when",
+  "increment",
+  "decrement",
+  "log"
+]);
+function interpolateProps(props, ctx) {
+  const result = {};
+  for (const [key, value] of Object.entries(props)) {
+    result[key] = interpolateValue(value, ctx);
+  }
+  return result;
+}
+function interpolateValue(value, ctx) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return interpolateString(value, ctx);
+  }
+  if (Array.isArray(value)) {
+    return interpolateArray(value, ctx);
+  }
+  if (typeof value === "object") {
+    return interpolateProps(value, ctx);
+  }
+  return value;
+}
+function interpolateString(value, ctx) {
+  if (value.startsWith("@") && isPureBinding(value)) {
+    return resolveBinding(value, ctx);
+  }
+  if (value.includes("@")) {
+    return interpolateEmbeddedBindings(value, ctx);
+  }
+  return value;
+}
+function isPureBinding(value) {
+  return /^@[\w]+(?:\.[\w]+)*$/.test(value);
+}
+function interpolateEmbeddedBindings(value, ctx) {
+  return value.replace(/@[\w]+(?:\.[\w]+)*/g, (match) => {
+    const resolved = resolveBinding(match, ctx);
+    return resolved !== void 0 ? String(resolved) : match;
+  });
+}
+function interpolateArray(value, ctx) {
+  if (value.length === 0) {
+    return [];
+  }
+  if (isSExpression(value)) {
+    return evaluate(value, ctx);
+  }
+  return value.map((item) => interpolateValue(item, ctx));
+}
+function isSExpression(value) {
+  if (value.length === 0) return false;
+  const first = value[0];
+  if (typeof first !== "string") return false;
+  if (OPERATORS.has(first)) return true;
+  if (first.includes("/")) return true;
+  if (first === "lambda" || first === "let") return true;
+  return false;
+}
+function containsBindings(value) {
+  if (typeof value === "string") {
+    return value.includes("@");
+  }
+  if (Array.isArray(value)) {
+    return value.some(containsBindings);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.values(value).some(containsBindings);
+  }
+  return false;
+}
+function extractBindings(value) {
+  const bindings = [];
+  function collect(v) {
+    if (typeof v === "string") {
+      const matches = v.match(/@[\w]+(?:\.[\w]+)*/g);
+      if (matches) {
+        bindings.push(...matches);
+      }
+    } else if (Array.isArray(v)) {
+      v.forEach(collect);
+    } else if (v !== null && typeof v === "object") {
+      Object.values(v).forEach(collect);
+    }
+  }
+  collect(value);
+  return [...new Set(bindings)];
+}
+function createContextFromBindings(bindings) {
+  return createMinimalContext(
+    bindings.entity || {},
+    bindings.payload || {},
+    bindings.state || "idle"
+  );
+}
+function findInitialState(trait) {
+  if (!trait.states || trait.states.length === 0) {
+    console.warn(`[StateMachine] Trait "${trait.name}" has no states defined, using "unknown"`);
+    return "unknown";
+  }
+  const markedInitial = trait.states.find((s) => s.isInitial)?.name;
+  const firstState = trait.states[0]?.name;
+  return markedInitial || firstState || "unknown";
+}
+function createInitialTraitState(trait) {
+  return {
+    traitName: trait.name,
+    currentState: findInitialState(trait),
+    previousState: null,
+    lastEvent: null,
+    context: {}
+  };
+}
+function findTransition(trait, currentState, eventKey) {
+  if (!trait.transitions || trait.transitions.length === 0) {
+    return void 0;
+  }
+  return trait.transitions.find((t) => {
+    if (Array.isArray(t.from)) {
+      return t.from.includes(currentState) && t.event === eventKey;
+    }
+    return t.from === currentState && t.event === eventKey;
+  });
+}
+function normalizeEventKey(eventKey) {
+  return eventKey.startsWith("UI:") ? eventKey.slice(3) : eventKey;
+}
+function processEvent(options) {
+  const { traitState, trait, eventKey, payload, entityData } = options;
+  const normalizedEvent = normalizeEventKey(eventKey);
+  const transition = findTransition(trait, traitState.currentState, normalizedEvent);
+  if (!transition) {
+    return {
+      executed: false,
+      newState: traitState.currentState,
+      previousState: traitState.currentState,
+      effects: []
+    };
+  }
+  if (transition.guard) {
+    const ctx = createContextFromBindings({
+      entity: entityData,
+      payload,
+      state: traitState.currentState
+    });
+    try {
+      const guardPasses = evaluateGuard(
+        transition.guard,
+        ctx
+      );
+      if (!guardPasses) {
+        return {
+          executed: false,
+          newState: traitState.currentState,
+          previousState: traitState.currentState,
+          effects: [],
+          transition: {
+            from: traitState.currentState,
+            to: transition.to,
+            event: normalizedEvent
+          },
+          guardResult: false
+        };
+      }
+    } catch (error) {
+      console.error("[StateMachineCore] Guard evaluation error:", error);
+    }
+  }
+  return {
+    executed: true,
+    newState: transition.to,
+    previousState: traitState.currentState,
+    effects: transition.effects || [],
+    transition: {
+      from: traitState.currentState,
+      to: transition.to,
+      event: normalizedEvent
+    },
+    guardResult: transition.guard ? true : void 0
+  };
+}
+var StateMachineManager = class {
+  traits = /* @__PURE__ */ new Map();
+  states = /* @__PURE__ */ new Map();
+  constructor(traits = []) {
+    for (const trait of traits) {
+      this.addTrait(trait);
+    }
+  }
+  /**
+   * Add a trait to the manager.
+   */
+  addTrait(trait) {
+    this.traits.set(trait.name, trait);
+    this.states.set(trait.name, createInitialTraitState(trait));
+  }
+  /**
+   * Remove a trait from the manager.
+   */
+  removeTrait(traitName) {
+    this.traits.delete(traitName);
+    this.states.delete(traitName);
+  }
+  /**
+   * Get current state for a trait.
+   */
+  getState(traitName) {
+    return this.states.get(traitName);
+  }
+  /**
+   * Get all current states.
+   */
+  getAllStates() {
+    return new Map(this.states);
+  }
+  /**
+   * Check if a trait can handle an event from its current state.
+   */
+  canHandleEvent(traitName, eventKey) {
+    const trait = this.traits.get(traitName);
+    const state = this.states.get(traitName);
+    if (!trait || !state) return false;
+    return !!findTransition(trait, state.currentState, normalizeEventKey(eventKey));
+  }
+  /**
+   * Send an event to all traits.
+   *
+   * @returns Array of transition results (one per trait that had a matching transition)
+   */
+  sendEvent(eventKey, payload, entityData) {
+    const results = [];
+    for (const [traitName, trait] of this.traits) {
+      const traitState = this.states.get(traitName);
+      if (!traitState) continue;
+      const result = processEvent({
+        traitState,
+        trait,
+        eventKey,
+        payload,
+        entityData
+      });
+      if (result.executed) {
+        this.states.set(traitName, {
+          ...traitState,
+          currentState: result.newState,
+          previousState: result.previousState,
+          lastEvent: normalizeEventKey(eventKey),
+          context: { ...traitState.context, ...payload }
+        });
+        results.push({ traitName, result });
+      }
+    }
+    return results;
+  }
+  /**
+   * Reset a trait to its initial state.
+   */
+  resetTrait(traitName) {
+    const trait = this.traits.get(traitName);
+    if (trait) {
+      this.states.set(traitName, createInitialTraitState(trait));
+    }
+  }
+  /**
+   * Reset all traits to initial states.
+   */
+  resetAll() {
+    for (const [traitName, trait] of this.traits) {
+      this.states.set(traitName, createInitialTraitState(trait));
+    }
+  }
+};
+
+// src/EffectExecutor.ts
+function parseEffect(effect) {
+  if (!Array.isArray(effect) || effect.length === 0) {
+    return null;
+  }
+  const [operator, ...args] = effect;
+  if (typeof operator !== "string") {
+    return null;
+  }
+  return { operator, args };
+}
+function resolveArgs(args, bindings) {
+  const ctx = createContextFromBindings(bindings);
+  return args.map((arg) => interpolateValue(arg, ctx));
+}
+var EffectExecutor = class {
+  handlers;
+  bindings;
+  context;
+  debug;
+  constructor(options) {
+    this.handlers = options.handlers;
+    this.bindings = options.bindings;
+    this.context = options.context;
+    this.debug = options.debug ?? false;
+  }
+  /**
+   * Execute a single effect.
+   */
+  async execute(effect) {
+    const parsed = parseEffect(effect);
+    if (!parsed) {
+      if (this.debug) {
+        console.warn("[EffectExecutor] Invalid effect format:", effect);
+      }
+      return;
+    }
+    const { operator, args } = parsed;
+    const resolvedArgs = resolveArgs(args, this.bindings);
+    if (this.debug) {
+      console.log("[EffectExecutor] Executing:", operator, resolvedArgs);
+    }
+    try {
+      await this.dispatch(operator, resolvedArgs);
+    } catch (error) {
+      console.error("[EffectExecutor] Error executing effect:", operator, error);
+      throw error;
+    }
+  }
+  /**
+   * Execute multiple effects in sequence.
+   */
+  async executeAll(effects) {
+    for (const effect of effects) {
+      await this.execute(effect);
+    }
+  }
+  /**
+   * Execute multiple effects in parallel.
+   */
+  async executeParallel(effects) {
+    await Promise.all(effects.map((effect) => this.execute(effect)));
+  }
+  // ==========================================================================
+  // Effect Dispatch
+  // ==========================================================================
+  async dispatch(operator, args) {
+    switch (operator) {
+      // === Universal Effects ===
+      case "emit": {
+        const event = args[0];
+        const payload = args[1];
+        this.handlers.emit(event, payload);
+        break;
+      }
+      case "set": {
+        const [entityId, field, value] = args;
+        this.handlers.set(entityId, field, value);
+        break;
+      }
+      case "persist": {
+        const action = args[0];
+        const entityType = args[1];
+        const data = args[2];
+        await this.handlers.persist(action, entityType, data);
+        break;
+      }
+      case "call-service": {
+        const service = args[0];
+        const action = args[1];
+        const params = args[2];
+        await this.handlers.callService(service, action, params);
+        break;
+      }
+      case "fetch": {
+        if (this.handlers.fetch) {
+          const entityType = args[0];
+          const options = args[1];
+          await this.handlers.fetch(entityType, options);
+        } else {
+          this.logUnsupported("fetch");
+        }
+        break;
+      }
+      case "spawn": {
+        if (this.handlers.spawn) {
+          const entityType = args[0];
+          const props = args[1];
+          this.handlers.spawn(entityType, props);
+        } else {
+          this.logUnsupported("spawn");
+        }
+        break;
+      }
+      case "despawn": {
+        if (this.handlers.despawn) {
+          const entityId = args[0];
+          this.handlers.despawn(entityId);
+        } else {
+          this.logUnsupported("despawn");
+        }
+        break;
+      }
+      case "log": {
+        if (this.handlers.log) {
+          const message = args[0];
+          const level = args[1];
+          const data = args[2];
+          this.handlers.log(message, level, data);
+        } else {
+          console.log(args[0], args.slice(1));
+        }
+        break;
+      }
+      // === Client-Only Effects ===
+      case "render-ui":
+      case "render": {
+        if (this.handlers.renderUI) {
+          const slot = args[0];
+          const pattern = args[1];
+          const props = args[2];
+          const priority = args[3];
+          this.handlers.renderUI(slot, pattern, props, priority);
+        } else {
+          this.logUnsupported("render-ui");
+        }
+        break;
+      }
+      case "navigate": {
+        if (this.handlers.navigate) {
+          const path2 = args[0];
+          const params = args[1];
+          this.handlers.navigate(path2, params);
+        } else {
+          this.logUnsupported("navigate");
+        }
+        break;
+      }
+      case "notify": {
+        if (this.handlers.notify) {
+          const message = args[0];
+          const type = args[1] || "info";
+          this.handlers.notify(message, type);
+        } else {
+          console.log(`[Notify:${args[1] || "info"}] ${args[0]}`);
+        }
+        break;
+      }
+      // === Compound Effects ===
+      case "do": {
+        const nestedEffects = args;
+        for (const nested of nestedEffects) {
+          await this.execute(nested);
+        }
+        break;
+      }
+      case "when": {
+        const condition = args[0];
+        const thenEffect = args[1];
+        const elseEffect = args[2];
+        if (condition) {
+          await this.execute(thenEffect);
+        } else if (elseEffect) {
+          await this.execute(elseEffect);
+        }
+        break;
+      }
+      default: {
+        if (this.debug) {
+          console.warn("[EffectExecutor] Unknown operator:", operator);
+        }
+      }
+    }
+  }
+  logUnsupported(operator) {
+    if (this.debug) {
+      console.warn(
+        `[EffectExecutor] Effect "${operator}" not supported on this platform`
+      );
+    }
+  }
+};
+function createTestExecutor(overrides = {}) {
+  const noopAsync = async () => {
+  };
+  const noop = () => {
+  };
+  return new EffectExecutor({
+    handlers: {
+      emit: overrides.emit ?? noop,
+      persist: overrides.persist ?? noopAsync,
+      set: overrides.set ?? noop,
+      callService: overrides.callService ?? (async () => ({})),
+      ...overrides
+    },
+    bindings: {},
+    context: {
+      traitName: "TestTrait",
+      state: "test",
+      transition: "test->test"
+    },
+    debug: true
+  });
+}
+
+// src/resolver/reference-resolver.ts
+init_external_loader();
+var ReferenceResolver = class {
+  loader;
+  options;
+  localTraits;
+  constructor(options) {
+    this.options = options;
+    this.loader = options.loader ?? new ExternalOrbitalLoader(options);
+    this.localTraits = options.localTraits ?? /* @__PURE__ */ new Map();
+  }
+  /**
+   * Resolve all references in an orbital.
+   */
+  async resolve(orbital, sourcePath, chain) {
+    const errors = [];
+    const warnings = [];
+    const importChain = chain ?? new ImportChain();
+    const importsResult = await this.resolveImports(
+      orbital.uses ?? [],
+      sourcePath,
+      importChain
+    );
+    if (!importsResult.success) {
+      return { success: false, errors: importsResult.errors };
+    }
+    const imports = importsResult.data;
+    const entityResult = this.resolveEntity(orbital.entity, imports);
+    if (!entityResult.success) {
+      errors.push(...entityResult.errors);
+    }
+    const traitsResult = this.resolveTraits(orbital.traits, imports);
+    if (!traitsResult.success) {
+      errors.push(...traitsResult.errors);
+    }
+    const pagesResult = this.resolvePages(orbital.pages, imports);
+    if (!pagesResult.success) {
+      errors.push(...pagesResult.errors);
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    if (!entityResult.success || !traitsResult.success || !pagesResult.success) {
+      return { success: false, errors: ["Internal error: unexpected failure state"] };
+    }
+    return {
+      success: true,
+      data: {
+        name: orbital.name,
+        entity: entityResult.data.entity,
+        entitySource: entityResult.data.source,
+        traits: traitsResult.data,
+        pages: pagesResult.data,
+        imports,
+        original: orbital
+      },
+      warnings
+    };
+  }
+  /**
+   * Resolve `uses` declarations to loaded orbitals.
+   */
+  async resolveImports(uses, sourcePath, chain) {
+    const errors = [];
+    const orbitals = /* @__PURE__ */ new Map();
+    if (this.options.skipExternalLoading) {
+      return {
+        success: true,
+        data: { orbitals },
+        warnings: ["External loading skipped"]
+      };
+    }
+    for (const use of uses) {
+      if (orbitals.has(use.as)) {
+        errors.push(`Duplicate import alias: ${use.as}`);
+        continue;
+      }
+      const loadResult = await this.loader.loadOrbital(
+        use.from,
+        void 0,
+        sourcePath,
+        chain
+      );
+      if (!loadResult.success) {
+        errors.push(`Failed to load "${use.from}" as "${use.as}": ${loadResult.error}`);
+        continue;
+      }
+      orbitals.set(use.as, {
+        alias: use.as,
+        from: use.from,
+        orbital: loadResult.data.orbital,
+        sourcePath: loadResult.data.sourcePath
+      });
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    return { success: true, data: { orbitals }, warnings: [] };
+  }
+  /**
+   * Resolve entity reference.
+   */
+  resolveEntity(entityRef, imports) {
+    if (!isEntityReference(entityRef)) {
+      return {
+        success: true,
+        data: { entity: entityRef },
+        warnings: []
+      };
+    }
+    const parsed = parseEntityRef(entityRef);
+    if (!parsed) {
+      return {
+        success: false,
+        errors: [`Invalid entity reference format: ${entityRef}. Expected "Alias.entity"`]
+      };
+    }
+    const imported = imports.orbitals.get(parsed.alias);
+    if (!imported) {
+      return {
+        success: false,
+        errors: [
+          `Unknown import alias in entity reference: ${parsed.alias}. Available aliases: ${Array.from(imports.orbitals.keys()).join(", ") || "none"}`
+        ]
+      };
+    }
+    const importedEntity = this.getEntityFromOrbital(imported.orbital);
+    if (!importedEntity) {
+      return {
+        success: false,
+        errors: [
+          `Imported orbital "${parsed.alias}" does not have an inline entity. Entity references cannot be chained.`
+        ]
+      };
+    }
+    const persistence = importedEntity.persistence ?? "persistent";
+    return {
+      success: true,
+      data: {
+        entity: importedEntity,
+        source: {
+          alias: parsed.alias,
+          persistence
+        }
+      },
+      warnings: []
+    };
+  }
+  /**
+   * Get the entity from an orbital (handling EntityRef).
+   */
+  getEntityFromOrbital(orbital) {
+    const entityRef = orbital.entity;
+    if (typeof entityRef === "string") {
+      return null;
+    }
+    return entityRef;
+  }
+  /**
+   * Resolve trait references.
+   */
+  resolveTraits(traitRefs, imports) {
+    const errors = [];
+    const resolved = [];
+    for (const traitRef of traitRefs) {
+      const result = this.resolveTraitRef(traitRef, imports);
+      if (!result.success) {
+        errors.push(...result.errors);
+      } else {
+        resolved.push(result.data);
+      }
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    return { success: true, data: resolved, warnings: [] };
+  }
+  /**
+   * Resolve a single trait reference.
+   */
+  resolveTraitRef(traitRef, imports) {
+    if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
+      return {
+        success: true,
+        data: {
+          trait: traitRef,
+          source: { type: "inline" }
+        },
+        warnings: []
+      };
+    }
+    if (typeof traitRef !== "string" && "ref" in traitRef) {
+      const refObj = traitRef;
+      return this.resolveTraitRefString(refObj.ref, imports, refObj.config, refObj.linkedEntity);
+    }
+    if (typeof traitRef === "string") {
+      return this.resolveTraitRefString(traitRef, imports);
+    }
+    return {
+      success: false,
+      errors: [`Unknown trait reference format: ${JSON.stringify(traitRef)}`]
+    };
+  }
+  /**
+   * Resolve a trait reference string.
+   */
+  resolveTraitRefString(ref, imports, config, linkedEntity) {
+    const parsed = parseImportedTraitRef(ref);
+    if (parsed) {
+      const imported = imports.orbitals.get(parsed.alias);
+      if (!imported) {
+        return {
+          success: false,
+          errors: [
+            `Unknown import alias in trait reference: ${parsed.alias}. Available aliases: ${Array.from(imports.orbitals.keys()).join(", ") || "none"}`
+          ]
+        };
+      }
+      const trait = this.findTraitInOrbital(imported.orbital, parsed.traitName);
+      if (!trait) {
+        return {
+          success: false,
+          errors: [
+            `Trait "${parsed.traitName}" not found in imported orbital "${parsed.alias}". Available traits: ${this.listTraitsInOrbital(imported.orbital).join(", ") || "none"}`
+          ]
+        };
+      }
+      return {
+        success: true,
+        data: {
+          trait,
+          source: { type: "imported", alias: parsed.alias, traitName: parsed.traitName },
+          config,
+          linkedEntity
+        },
+        warnings: []
+      };
+    }
+    const localTrait = this.localTraits.get(ref);
+    if (localTrait) {
+      return {
+        success: true,
+        data: {
+          trait: localTrait,
+          source: { type: "local", name: ref },
+          config,
+          linkedEntity
+        },
+        warnings: []
+      };
+    }
+    return {
+      success: false,
+      errors: [
+        `Trait "${ref}" not found. For imported traits, use format "Alias.traits.TraitName". Local traits available: ${Array.from(this.localTraits.keys()).join(", ") || "none"}`
+      ]
+    };
+  }
+  /**
+   * Find a trait in an orbital by name.
+   */
+  findTraitInOrbital(orbital, traitName) {
+    for (const traitRef of orbital.traits) {
+      if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
+        if (traitRef.name === traitName) {
+          return traitRef;
+        }
+      }
+      if (typeof traitRef !== "string" && "ref" in traitRef) {
+        const refObj = traitRef;
+        if (refObj.ref === traitName || refObj.name === traitName) ;
+      }
+    }
+    return null;
+  }
+  /**
+   * List trait names in an orbital.
+   */
+  listTraitsInOrbital(orbital) {
+    const names = [];
+    for (const traitRef of orbital.traits) {
+      if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
+        names.push(traitRef.name);
+      }
+    }
+    return names;
+  }
+  /**
+   * Resolve page references.
+   */
+  resolvePages(pageRefs, imports) {
+    const errors = [];
+    const resolved = [];
+    for (const pageRef of pageRefs) {
+      const result = this.resolvePageRef(pageRef, imports);
+      if (!result.success) {
+        errors.push(...result.errors);
+      } else {
+        resolved.push(result.data);
+      }
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    return { success: true, data: resolved, warnings: [] };
+  }
+  /**
+   * Resolve a single page reference.
+   */
+  resolvePageRef(pageRef, imports) {
+    if (!isPageReference(pageRef)) {
+      return {
+        success: true,
+        data: {
+          page: pageRef,
+          source: { type: "inline" },
+          pathOverridden: false
+        },
+        warnings: []
+      };
+    }
+    if (isPageReferenceString(pageRef)) {
+      return this.resolvePageRefString(pageRef, imports);
+    }
+    if (isPageReferenceObject(pageRef)) {
+      return this.resolvePageRefObject(pageRef, imports);
+    }
+    return {
+      success: false,
+      errors: [`Unknown page reference format: ${JSON.stringify(pageRef)}`]
+    };
+  }
+  /**
+   * Resolve a page reference string.
+   */
+  resolvePageRefString(ref, imports) {
+    const parsed = parsePageRef(ref);
+    if (!parsed) {
+      return {
+        success: false,
+        errors: [`Invalid page reference format: ${ref}. Expected "Alias.pages.PageName"`]
+      };
+    }
+    const imported = imports.orbitals.get(parsed.alias);
+    if (!imported) {
+      return {
+        success: false,
+        errors: [
+          `Unknown import alias in page reference: ${parsed.alias}. Available aliases: ${Array.from(imports.orbitals.keys()).join(", ") || "none"}`
+        ]
+      };
+    }
+    const page = this.findPageInOrbital(imported.orbital, parsed.pageName);
+    if (!page) {
+      return {
+        success: false,
+        errors: [
+          `Page "${parsed.pageName}" not found in imported orbital "${parsed.alias}". Available pages: ${this.listPagesInOrbital(imported.orbital).join(", ") || "none"}`
+        ]
+      };
+    }
+    return {
+      success: true,
+      data: {
+        page,
+        source: { type: "imported", alias: parsed.alias, pageName: parsed.pageName },
+        pathOverridden: false
+      },
+      warnings: []
+    };
+  }
+  /**
+   * Resolve a page reference object with optional path override.
+   */
+  resolvePageRefObject(refObj, imports) {
+    const baseResult = this.resolvePageRefString(refObj.ref, imports);
+    if (!baseResult.success) {
+      return baseResult;
+    }
+    const resolved = baseResult.data;
+    if (refObj.path) {
+      const originalPath = resolved.page.path;
+      resolved.page = {
+        ...resolved.page,
+        path: refObj.path
+      };
+      resolved.pathOverridden = true;
+      resolved.originalPath = originalPath;
+    }
+    return {
+      success: true,
+      data: resolved,
+      warnings: baseResult.warnings
+    };
+  }
+  /**
+   * Find a page in an orbital by name.
+   */
+  findPageInOrbital(orbital, pageName) {
+    const pages = orbital.pages;
+    if (!pages) return null;
+    for (const pageRef of pages) {
+      if (typeof pageRef !== "string" && !("ref" in pageRef)) {
+        const page = pageRef;
+        if (page.name === pageName) {
+          return { ...page };
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * List page names in an orbital.
+   */
+  listPagesInOrbital(orbital) {
+    const pages = orbital.pages;
+    if (!pages) return [];
+    const names = [];
+    for (const pageRef of pages) {
+      if (typeof pageRef !== "string" && !("ref" in pageRef)) {
+        names.push(pageRef.name);
+      }
+    }
+    return names;
+  }
+  /**
+   * Add local traits for resolution.
+   */
+  addLocalTraits(traits) {
+    for (const trait of traits) {
+      this.localTraits.set(trait.name, trait);
+    }
+  }
+  /**
+   * Clear loader cache.
+   */
+  clearCache() {
+    this.loader.clearCache();
+  }
+};
+async function resolveSchema(schema, options) {
+  const resolver = new ReferenceResolver(options);
+  const errors = [];
+  const warnings = [];
+  const resolved = [];
+  for (const orbital of schema.orbitals) {
+    const inlineTraits = orbital.traits.filter(
+      (t) => typeof t !== "string" && "stateMachine" in t
+    );
+    resolver.addLocalTraits(inlineTraits);
+  }
+  for (const orbital of schema.orbitals) {
+    const result = await resolver.resolve(orbital);
+    if (!result.success) {
+      errors.push(`Orbital "${orbital.name}": ${result.errors.join(", ")}`);
+    } else {
+      resolved.push(result.data);
+      warnings.push(...result.warnings.map((w) => `Orbital "${orbital.name}": ${w}`));
+    }
+  }
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+  return { success: true, data: resolved, warnings };
+}
+
+// src/loader/index.ts
+init_external_loader();
+
+// src/UsesIntegration.ts
+async function preprocessSchema(schema, options) {
+  const namespaceEvents = options.namespaceEvents ?? true;
+  const resolveResult = await resolveSchema(schema, options);
+  if (!resolveResult.success) {
+    return { success: false, errors: resolveResult.errors };
+  }
+  const resolved = resolveResult.data;
+  const warnings = resolveResult.warnings;
+  const preprocessedOrbitals = [];
+  const entitySharing = {};
+  const eventNamespaces = {};
+  for (const resolvedOrbital of resolved) {
+    const orbitalName = resolvedOrbital.name;
+    const persistence = resolvedOrbital.entitySource?.persistence ?? resolvedOrbital.entity.persistence ?? "persistent";
+    entitySharing[orbitalName] = {
+      entityName: resolvedOrbital.entity.name,
+      persistence,
+      isShared: persistence !== "runtime",
+      sourceAlias: resolvedOrbital.entitySource?.alias,
+      collectionName: resolvedOrbital.entity.collection
+    };
+    eventNamespaces[orbitalName] = {};
+    for (const resolvedTrait of resolvedOrbital.traits) {
+      const traitName = resolvedTrait.trait.name;
+      const namespace = {
+        emits: {},
+        listens: {}
+      };
+      if (namespaceEvents && resolvedTrait.source.type === "imported") {
+        const emits = resolvedTrait.trait.emits ?? [];
+        for (const emit of emits) {
+          const eventName = typeof emit === "string" ? emit : emit.event;
+          namespace.emits[eventName] = `${orbitalName}.${traitName}.${eventName}`;
+        }
+        const listens = resolvedTrait.trait.listens ?? [];
+        for (const listen of listens) {
+          namespace.listens[listen.event] = listen.event;
+        }
+      }
+      eventNamespaces[orbitalName][traitName] = namespace;
+    }
+    const preprocessedOrbital = {
+      name: orbitalName,
+      description: resolvedOrbital.original.description,
+      visual_prompt: resolvedOrbital.original.visual_prompt,
+      // Resolved entity (always inline now)
+      entity: resolvedOrbital.entity,
+      // Resolved traits (inline definitions)
+      traits: resolvedOrbital.traits.map((rt) => {
+        if (rt.config || rt.linkedEntity) {
+          return {
+            ref: rt.trait.name,
+            config: rt.config,
+            linkedEntity: rt.linkedEntity,
+            // Include the resolved trait definition for runtime
+            _resolved: rt.trait
+          };
+        }
+        return rt.trait;
+      }),
+      // Resolved pages (inline definitions with path overrides applied)
+      pages: resolvedOrbital.pages.map((rp) => rp.page),
+      // Preserve other fields
+      exposes: resolvedOrbital.original.exposes,
+      domainContext: resolvedOrbital.original.domainContext,
+      design: resolvedOrbital.original.design
+    };
+    preprocessedOrbitals.push(preprocessedOrbital);
+  }
+  const preprocessedSchema = {
+    ...schema,
+    orbitals: preprocessedOrbitals
+  };
+  return {
+    success: true,
+    data: {
+      schema: preprocessedSchema,
+      entitySharing,
+      eventNamespaces,
+      warnings
+    }
+  };
+}
+function getIsolatedCollectionName(orbitalName, entitySharing) {
+  const info = entitySharing[orbitalName];
+  if (!info) {
+    throw new Error(`Unknown orbital: ${orbitalName}`);
+  }
+  if (info.persistence === "runtime") {
+    return `${orbitalName}_${info.entityName}`;
+  }
+  return info.collectionName || info.entityName.toLowerCase() + "s";
+}
+function getNamespacedEvent(orbitalName, traitName, eventName, eventNamespaces) {
+  const orbitalNs = eventNamespaces[orbitalName];
+  if (!orbitalNs) return eventName;
+  const traitNs = orbitalNs[traitName];
+  if (!traitNs) return eventName;
+  return traitNs.emits[eventName] || eventName;
+}
+function isNamespacedEvent(eventName) {
+  return eventName.includes(".");
+}
+function parseNamespacedEvent(eventName) {
+  const parts = eventName.split(".");
+  if (parts.length === 3) {
+    return { orbital: parts[0], trait: parts[1], event: parts[2] };
+  }
+  if (parts.length === 2) {
+    return { trait: parts[0], event: parts[1] };
+  }
+  return { event: eventName };
+}
+
+export { EffectExecutor, EventBus, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createTestExecutor, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map