@xpell/core 2.0.0-alpha.10 → 2.0.1

package/README.md

@@ -1,96 +1,135 @@
-# Xpell Core
+# @xpell/core
 
-**Xpell Core** is the foundational runtime of the Xpell framework.  
-It provides the core engine, real-time update loop, event system, data layer, and utilities used by XUI (UI engine), X3D (3D engine), and higher-level Xpell modules.
+Xpell 2 Alpha --- AI-Native Runtime Engine
 
-Xpell Core is designed for **high-performance, real-time JavaScript/TypeScript applications**, including:
+`@xpell/core` is the foundational execution layer of the Xpell 2
+platform.
 
-- real-time UI  
-- AI-driven interfaces  
-- dashboards  
-- data-driven visualizations  
-- WebGL/3D experiences  
-- vibe-coded apps (LLM-assisted development)
+It defines the runtime contracts that power the entire ecosystem,
+including:
 
-If you are building with Xpell, this package provides the low-level primitives the rest of the framework depends on.
+-   `@xpell/ui` (real-time UI layer)
+-   `@xpell/3d` (spatial runtime)
+-   `@xpell/node` (server runtime)
 
-## Features
+Xpell Core is designed for real-time, AI-collaborative systems --- where
+applications can evolve at runtime instead of relying solely on rebuild
+cycles.
 
-- Real-time engine update loop  
-- Event and signal system  
-- Core data structures  
-- Object lifecycle management  
-- Shared utilities for UI, 3D, and AI modules  
-- Zero-dependency, lightweight foundation  
-- Written in TypeScript  
+> This package is part of the Xpell 2 Alpha platform.\
+> See the full release overview at https://xpell.ai
 
-## Installation
+------------------------------------------------------------------------
 
-    npm install xpell-core
-    pnpm add xpell-core
-    yarn add xpell-core
+## What @xpell/core Provides
 
-## Usage
+### XData 2
 
-xpell-core provides low-level building blocks for the Xpell framework. Below is a simple example showing how to use Xpell Core's event system and update loop.
+Structured shared runtime state for predictable mutation and
+coordination.
 
-## When to use Xpell Core
+### Nano-Commands 2
 
-Use xpell-core directly if you are:
+Command handlers defined as text or structured JSON, enabling safe
+serialization and AI-driven runtime edits.
 
-- Building low-level extensions for Xpell  
-- Creating custom UI components  
-- Developing new rendering pipelines  
-- Writing real-time, loop-driven modules  
-- Integrating AI-powered reactive systems  
-- Working inside internal Xpell packages  
+### XEM (Xpell Event Manager)
 
-Most end-users should install:
+A lightweight process-wide event bus for decoupled runtime coordination.
 
-    npm install xpell
+### XModule
 
-which includes xpell-core automatically.
+The only valid extension point for behavior in the Xpell runtime.
 
-## Who Should Use xpell-core Directly?
+### XObject
 
-Most developers should **not** depend on xpell-core directly.
+The base runtime object model (UI behavior lives only in `@xpell/ui`).
 
-Use xpell-core only if you are:
-- Developing Xpell framework modules
-- Building custom runtime systems
-- Extending XModule or XObject internals
-- Working on Xpell UI / 3D / server internals
+### Execution Loop
 
-For application development, use:
-- xpell-ui
-- xpell
+Deterministic real-time update cycle for dynamic systems.
 
+------------------------------------------------------------------------
 
-## Relationship to the Xpell Framework
+## Design Principles
 
-Xpell Core powers all other Xpell packages:
+-   Runtime-first architecture
+-   Explicit contracts over hidden state
+-   Modular extension via XModule
+-   No UI assumptions inside core
+-   Zero external dependencies
+-   TypeScript-native
 
-- xpell-ui  
-- xpell-3d  
-- xpell  
-- future Xpell II modules  
+------------------------------------------------------------------------
 
-## Documentation
+## Installation (Alpha)
 
-For a detailed overview of the Xpell architecture, see  
-[`docs/architecture/overview.md`](docs/architecture/overview.md).
+npm install @xpell/core@alpha
 
-## Links
+You will typically combine it with:
 
-https://xpell.ai
+npm install @xpell/ui@alpha\
+npm install @xpell/node@alpha\
+npm install @xpell/3d@alpha
 
-GitHub:  
-https://github.com/xpell-ai/xpell-core
+Alpha builds are intentionally not published under the `latest` tag.
+
+------------------------------------------------------------------------
+
+## When to Use @xpell/core Directly
+
+Most application developers should work with higher-level packages.
+
+Use `@xpell/core` directly if you are:
+
+-   Building runtime extensions
+-   Creating custom XModule implementations
+-   Extending engine-level primitives
+-   Working on Xpell internals
+-   Developing advanced AI-driven runtime systems
+
+------------------------------------------------------------------------
+
+## Architecture Role in Xpell 2
+
+Xpell 2 is modular:
+
+-   `@xpell/core` → Runtime contracts + execution engine\
+-   `@xpell/ui` → Real-time UI framework\
+-   `@xpell/3d` → Three.js-based spatial runtime\
+-   `@xpell/node` → Server runtime (xnode, Wormholes, XDB)
+
+Core defines the execution model.\
+Other packages implement specialized layers on top of it.
+
+------------------------------------------------------------------------
+
+## Alpha Status
+
+This package is currently in Alpha.
+
+-   APIs may evolve
+-   Contracts may be refined
+-   Performance optimizations are ongoing
+
+This release is intended for architectural experimentation and early
+adopters.
+
+------------------------------------------------------------------------
+
+## Documentation & Links
+
+Website: https://xpell.ai\
+GitHub: https://github.com/xpell-ai/xpell-core
+
+------------------------------------------------------------------------
 
 ## Versioning
 
-xpell-core follows **semantic versioning**, aligned with the main Xpell release stream.
+Follows semantic versioning under the Xpell 2 release stream.
+
+------------------------------------------------------------------------
 
 ## License
 
-MIT License — © Aime Technologies, 2022–Present
+MIT License --- © Aime Technologies

package/dist/XCommand.d.ts

@@ -42,7 +42,7 @@ export type XCommandData = {
     _object?: string;
     _op: string;
     _params?: {
-        [k: string]: string | number | Function;
+        [k: string]: string | number | boolean | null | undefined | object | any[];
     };
 };
 export declare class XCommand {
@@ -62,7 +62,7 @@ export declare class XCommand {
      * command parameters array
      */
     _params?: {
-        [k: string]: string | number | Function;
+        [k: string]: string | number | boolean | null | object | any[];
     };
     /**
      * XCommand create date timestamp

package/dist/XData.d.ts

@@ -48,4 +48,5 @@ export declare class _XData {
 }
 /** Singleton */
 export declare const XData: _XData;
+export declare const _xd: _XData;
 export default XData;

package/dist/XDataModule.d.ts

@@ -0,0 +1,41 @@
+import { XModule } from "./XModule";
+import { XCommand } from "./XCommand";
+import type { XpellSkill, XpellSkillCommand } from "./XSkills";
+export declare class XDataModule extends XModule {
+    static _name: string;
+    static _skill: XpellSkill;
+    static _ops: Record<string, XpellSkillCommand>;
+    constructor();
+    _get(xcmd: XCommand): Promise<{
+        _ok: boolean;
+        _result: any;
+    }>;
+    _set(xcmd: XCommand): Promise<{
+        _ok: boolean;
+        _result: {
+            key: string;
+        };
+    }>;
+    _patch(xcmd: XCommand): Promise<{
+        _ok: boolean;
+        _result: {
+            key: string;
+        };
+    }>;
+    _delete(xcmd: XCommand): Promise<{
+        _ok: boolean;
+        _result: {
+            key: string;
+        };
+    }>;
+    _touch(xcmd: XCommand): Promise<{
+        _ok: boolean;
+        _result: {
+            key: string;
+        };
+    }>;
+    _has(xcmd: XCommand): Promise<{
+        _ok: boolean;
+        _result: boolean;
+    }>;
+}

package/dist/XEvenetManagerModule.d.ts

@@ -0,0 +1,10 @@
+import XCommand from "./XCommand.js";
+import { XModule } from "./XModule.js";
+import type { XpellSkill, XpellSkillCommand } from "./XSkills";
+export declare class XEventManagerModule extends XModule {
+    static _name: string;
+    static _skill: XpellSkill;
+    static _ops: Record<string, XpellSkillCommand>;
+    constructor();
+    _fire(xcmd: XCommand): Promise<void>;
+}

package/dist/XEventManager.d.ts

@@ -49,9 +49,6 @@ export declare class _XEventManager {
      */
     clear(): void;
 }
-/**
- * Global Xpell event manager instance.
- */
-export declare const XEventManager: _XEventManager;
-export declare const _xem: _XEventManager;
-export default XEventManager;
+export declare function setXEventManager(xem: any): void;
+export declare function getXEventManager(): any;
+export default _XEventManager;

package/dist/XModule.d.ts

@@ -56,10 +56,12 @@
 import XObjectManager from "./XObjectManager";
 import { XObjectData, XObject, XObjectPack } from "./XObject";
 import XCommand, { XCommandData } from "./XCommand";
+import type { XpellSkill, XpellSkillCommand } from "./XSkills";
 export type XModuleData = {
     _name: string;
 };
 export declare const XD_MODULE_NUM_OF_OBJECTS = "engine:module:num-of-objects:";
+export declare const XMODULE_SKILL: XpellSkill;
 /**
  * Xpell Base Module
  * This class represents xpell base module to be extends
@@ -71,12 +73,22 @@ export declare class XModule {
     [k: string]: any;
     _id: string;
     _name: string;
+    _loaded: boolean;
+    _loading: boolean;
     _log_rules: {
         createObject: boolean;
         removeObject: boolean;
     };
+    static _skill: XpellSkill;
+    static _ops: Record<string, XpellSkillCommand>;
+    static getOwnSkillBase(): XpellSkill;
+    getOwnSkill(): XpellSkill;
+    getSkillChain(): XpellSkill[];
+    getObjectSkills(): XpellSkill[];
+    getCommandSkills(): XpellSkillCommand[];
     constructor(data: XModuleData);
-    load(): void;
+    load(): Promise<void>;
+    protected onLoad(): Promise<void>;
     /**
      * Creates new XObject from data object
      * @param data - The data of the new object (JSON)
@@ -126,6 +138,7 @@ export declare class XModule {
      * @returns XObject
      */
     getObject(objectId: string): XObject;
+    hasObject(name: string): boolean;
     /**
      * Returns the XObject instance from the module Object Manager
      * Usage:

package/dist/XNanoCommands.d.ts

@@ -1,42 +1,14 @@
-/**
- * XNanoCommands — Core Nano Command Definitions
- *
- * Built-in nano commands available to all XObject instances.
- *
- * This module defines the foundational nano commands that form the
- * minimal executable vocabulary of the Xpell runtime. These commands
- * are registered on every XObject and can be invoked via command text,
- * events, or programmatic execution.
- *
- * Nano commands act as the bridge between declarative intent
- * (strings, schemas, AI output) and imperative runtime behavior.
- *
- * One-liner: Nano commands are the verbs of the Xpell runtime.
- *
- * @packageDocumentation
- * @since 2022-07-22
- * @author Tamir Fridman
- * @license MIT
- * @copyright
- * © 2022–present Aime Technologies. All rights reserved.
- */
 import XCommand, { XCommandData } from "./XCommand";
 import XObject from "./XObject";
-/**
- * Single x-nano-command interface
- */
+import type { XpellSkillCommand } from "./XSkills";
 export interface XNanoCommand {
-    (xCommand: XCommand | XCommandData, xObject: XObject): any;
+    (xCommand: XCommand | XCommandData, xObject?: XObject): any;
+    _skill?: XpellSkillCommand;
+    getSkill?: () => XpellSkillCommand;
 }
-/**
- * x-nano-command pack
- */
 export type XNanoCommandPack = {
     [k: string]: XNanoCommand;
 };
-/**
- * XNanoCommand Pack
- */
+export declare function createNanoCommandWithSkill(handler: XNanoCommand, skill: XpellSkillCommand): XNanoCommand;
 export declare const _xobject_basic_nano_commands: XNanoCommandPack;
-declare const _default: XNanoCommandPack;
-export default _default;
+export default _xobject_basic_nano_commands;

package/dist/XObject.d.ts

@@ -26,10 +26,12 @@
 import XCommand, { XCommandData } from "./XCommand";
 import { XEventListenerOptions } from "./XEventManager";
 import { XNanoCommandPack, XNanoCommand } from "./XNanoCommands";
+import type { XpellSkill, XpellSkillCommand } from "./XSkills";
+export declare const XOBJECT_SKILL: XpellSkill;
 export type wordsList = {
     [k: string]: string;
 };
-export type XValue = string | number | boolean | null | undefined | Function | XValue[] | {
+export type XValue = string | number | boolean | null | undefined | Function | object | any[] | XValue[] | {
     [k: string]: XValue;
 };
 export interface IXData {
@@ -48,10 +50,11 @@ export type XDataXporter = {
         [id: string]: XDataInstanceXporter;
     };
 };
-export type XObjectOnEventHandler = (xObject: XObject, data?: any) => void;
+export type XObjectOnEventHandler = ((xObject: XObject, data?: any) => void) | string | XCommandData | XObjectOnEventHandler[];
 export interface XObjectOnEventIndex {
     [eventName: string]: XObjectOnEventHandler;
 }
+type XObjectHandler = Function | string | XCommandData | XObjectHandler[];
 export type XObjectData = {
     [k: string]: XValue;
     _id?: string;
@@ -61,10 +64,10 @@ export type XObjectData = {
     _data_source?: string;
     _on?: XObjectOnEventIndex;
     _once?: XObjectOnEventIndex;
-    _on_create?: string | Function;
-    _on_mount?: string | Function;
-    _on_frame?: string | Function;
-    _on_data?: string | Function;
+    _on_create?: XObjectHandler;
+    _on_mount?: XObjectHandler;
+    _on_frame?: XObjectHandler;
+    _on_data?: XObjectHandler;
     _process_frame?: boolean;
     _process_data?: boolean;
     _nano_commands?: XNanoCommandPack;
@@ -76,6 +79,7 @@ export type XObjectData = {
  */
 export declare class XObject {
     [k: string]: string | null | [] | undefined | Function | boolean | number | {} | null;
+    static _xtype: string;
     _id: string;
     _type: string;
     _children: Array<XObject | XObjectData>;
@@ -85,11 +89,11 @@ export declare class XObject {
     _debug?: boolean;
     _on: XObjectOnEventIndex;
     _once: XObjectOnEventIndex;
-    _on_create?: string | Function | undefined;
-    _on_mount?: string | Function | undefined;
-    _on_frame?: string | Function | undefined;
-    _on_data?: string | Function | undefined;
-    _on_event?: string | Function | undefined;
+    _on_create?: XObjectHandler | undefined;
+    _on_mount?: XObjectHandler | undefined;
+    _on_frame?: XObjectHandler | undefined;
+    _on_data?: XObjectHandler | undefined;
+    _on_event?: XObjectHandler | undefined;
     _process_frame: boolean;
     _process_data: boolean;
     protected _xem_options: XEventListenerOptions;
@@ -106,6 +110,15 @@ export declare class XObject {
     protected _xporter: XDataXporter;
     private _xd_unsub?;
     private _xd_bound_key?;
+    /***
+     * Skills
+     */
+    static _skill: XpellSkill;
+    static getOwnSkill(): XpellSkill;
+    static getSkillChain(): XpellSkill[];
+    static getOwnNanoCommands(): XNanoCommandPack;
+    static getNanoCommands(): XNanoCommandPack;
+    static getNanoCommandSkills(): XpellSkillCommand[];
     /**
      * XObject constructor is creating the object and adding all the data keys to the XObject instance
      * @param data constructor input data (object)
@@ -123,7 +136,7 @@ export declare class XObject {
      */
     init(data?: any, skipParse?: boolean): void;
     parseEvents(options?: XEventListenerOptions): void;
-    addEventListener(eventName: string, handler: XObjectOnEventHandler | string, options?: XEventListenerOptions): void;
+    addEventListener(eventName: string, handler: XObjectOnEventHandler | string | any, options?: XEventListenerOptions): string;
     removeEventListener(eventName: string): void;
     removeAllEventListeners(): void;
     /**
@@ -185,7 +198,8 @@ export declare class XObject {
      *
     */
     onCreate(): Promise<void>;
-    protected checkAndRunInternalFunction(func: any, ...params: any): Promise<void>;
+    private runCmd;
+    protected checkAndRunInternalFunction(func: any, ...params: any): Promise<any>;
     /**
      * Triggers when the object is being mounted to other element
      * support external _on_create anonymous function in the , example:
@@ -241,7 +255,7 @@ export declare class XObject {
      * }
      *
      */
-    execute(xCommand: XCommand | XCommandData): Promise<void>;
+    execute(xCommand: XCommand | XCommandData): Promise<any>;
     /**
      * Return an IXObjectData JSON representation of the XObject
      * @returns IXObjectData

package/dist/XObjectManager.d.ts

@@ -61,8 +61,10 @@ export declare class XObjectManager {
     /**
      * Retrieves all the classes dictionary
      * @returns XObjectManagerIndex
+     * @deprecated use getObjectClasses() instead
      */
     getAllClasses(): XObjectManagerIndex;
+    getObjectClasses(): XObjectManagerIndex;
     get _classes(): XObjectManagerIndex;
     /**
      * Add XObject instance to the manager

package/dist/XParams.d.ts

@@ -52,7 +52,7 @@ export type XCmdLike = {
 };
 export declare class XParams {
     static get(cmd: any, key: string | number, def?: any): any;
-    static has(cmd: any, key: string | number): any;
+    static has(cmd: any, key: string | number): boolean;
     static str(cmd: any, ...keys: (string | number)[]): string | undefined;
     static bool(cmd: any, key: string | number, def?: boolean): boolean;
     static int(cmd: any, key: string | number, def?: number): number;

package/dist/XRuntime.d.ts

@@ -0,0 +1,2 @@
+export declare function setXRuntime(x: any): void;
+export declare function getXRuntime(): any;

package/dist/XSkills.d.ts

@@ -0,0 +1,47 @@
+export type XpellSkillType = "view-skill" | "flow-skill" | "entity-skill" | "runtime-api-skill" | "nano-command-pack" | "server-module-api" | "client-module-api" | "wormholes-protocol" | "xdata-skill" | "general";
+export type XpellSkillCommand = {
+    _name: string;
+    _scope?: string;
+    _description?: string;
+    _params?: Record<string, any>;
+    _example?: Record<string, any>;
+};
+export type XpellSkillModule = {
+    _name: string;
+    _scope?: "server" | "client" | "shared";
+    _description?: string;
+    _ops?: XpellSkillCommand[];
+};
+export type XpellSkill = {
+    _id: string;
+    _title: string;
+    _version: string;
+    _active?: boolean;
+    _type?: XpellSkillType;
+    _description?: string;
+    _requires?: string[];
+    _match?: {
+        _keywords?: string[];
+        _requires_any?: string[];
+        _requires_all?: string[];
+        _exclude_keywords?: string[];
+        _priority?: number;
+    };
+    _fields?: Record<string, any>;
+    _exports?: {
+        _xui_objects?: string[];
+        _xui_fields?: string[];
+        _nano_commands?: XpellSkillCommand[];
+        _modules?: XpellSkillModule[];
+        _client_ops?: XpellSkillCommand[];
+        _server_ops?: XpellSkillCommand[];
+    };
+    _core_rules?: string[];
+    _priority_rules?: string[];
+    _canonical_examples?: Record<string, any>[];
+    _anti_patterns?: Array<string | {
+        _bad: any;
+        _reason: string;
+    }>;
+    _notes?: string[];
+};

package/dist/XUtils.d.ts

@@ -75,6 +75,41 @@ export declare class _XUtils {
      * - Node / non-DOM: setImmediate (fast) or setTimeout (paced by target fps)
      */
     createDefaultScheduler(_target_fps?: number): XFrameScheduler;
+    to_iso_now(): string;
+    is_plain_object(value: unknown): value is Record<string, any>;
+    ensure_string(value: unknown, field: string): string;
+    ensure_params(raw: unknown): Record<string, any>;
+    /**
+     * Copy keys from source to target only when value is not null/undefined.
+     * Keeps valid falsy values (0, false, "").
+     */
+    addIfNotNull(source: any, target: any, keys: string[]): void;
+    /**
+    * Add Last Slash
+    * adds a last slash to the url if it doesn't have one
+    */
+    als(url: string): string;
+    /**
+     * Clear Last Slash
+     * removes the last slash if exists
+     */
+    cls(url: string): string;
+    /**
+     * Add First Slash
+     */
+    afs(url: string): string;
+    /**
+     * Clear First Slash
+     */
+    cfs(url: string): string;
+    /**
+     * Calculates expiration time based on short format:
+     *  - 1h (hours)
+     *  - 2d (days)
+     *  - 3y (years, 365d)
+     * Returns epoch ms (now + delta).
+     */
+    calculateExpiration(exp: string): number;
 }
 declare const XUtils: _XUtils;
 declare const _xu: _XUtils;