@xpell/core 2.0.0-alpha.10

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to **xpell-core** are documented in this file.
+
+This project follows **Semantic Versioning** with pre-release tags (`alpha`, `beta`).
+Until `2.0.0` stable, breaking changes may occur between alpha versions.
+
+---
+
+## [2.0.0-alpha.1] — 2025-XX-XX
+
+### Summary
+First public alpha of the **Xpell Core 2.x runtime**.
+
+This release establishes the new internal architecture that powers XVM, XUI 2.x,
+and future Xpell II modules. It introduces an event-driven runtime state model
+(**XData2**) that replaces per-frame polling with explicit, observable state updates.
+
+This version is intended for **early adopters, internal framework packages,
+and contributors**.
+
+---
+
+### 🚀 Added
+- **XData2**: observable runtime shared-state system.
+  - Explicit APIs: `set`, `get`, `delete`, `touch`, `patch`
+  - Key-based subscriptions (`on`, `onAny`)
+  - Backward-compatible legacy access via `XData._o` (deprecated)
+- **Binding foundation** in `XObject` enabling event-driven data flow (no polling).
+- `XParams`: unified parameter handling for CLI commands, JSON payloads, and runtime calls.
+- `docs/XData2.md`: specification for the new runtime shared-state model.
+- `ARCHITECTURE.md` documenting the core Xpell 2.x runtime design.
+- `CHANGELOG.md` to formalize version history and release notes.
+
+---
+
+### 🔄 Changed
+- Refactored **XData** into an observable, event-driven runtime state system.
+- Deprecated frame-based polling patterns in favor of explicit subscriptions.
+- Clearer separation of responsibilities:
+  - **XData** → runtime shared state
+  - **XObject** → behavior and binding
+  - **XUIObject** → visual/runtime UI representation
+- Refactored `XModule` and `XObjectManager` for improved clarity and stronger TypeScript safety.
+- Internal cleanup and alignment to support the Xpell 2.x runtime model.
+
+---
+
+### 🛠 Tooling
+- Updated build scripts for the 2.x architecture.
+- Added `publish-alpha` workflow for prerelease publishing.
+
+---
+
+### ⚠️ Notes
+- This is an **alpha release**.
+- APIs may change before `2.0.0` stable.
+- Direct writes to `XData._o[...]` are deprecated but supported during migration.
+- Deep mutations require explicit `touch(key)` to emit updates.
+- Polling-based data access will be removed in a future major release.
+
+---
+
+## [1.0.0]
+
+### ⚠️ Breaking
+- Removed legacy internal core folder usage.
+- Unified runtime exports for use across Xpell modules.
+
+### 🛠 Improvements
+- Internal cleanup and improved type safety.
+- Event system stabilization.
+
+---
+
+## Pre-2.0 Releases
+
+Earlier versions focused on:
+- Initial runtime loop
+- Core object model
+- Experimental command execution
+
+These versions are considered **legacy** relative to Xpell 2.x.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aime Technologies Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# 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 Core is designed for **high-performance, real-time JavaScript/TypeScript applications**, including:
+
+- real-time UI  
+- AI-driven interfaces  
+- dashboards  
+- data-driven visualizations  
+- WebGL/3D experiences  
+- vibe-coded apps (LLM-assisted development)
+
+If you are building with Xpell, this package provides the low-level primitives the rest of the framework depends on.
+
+## Features
+
+- 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  
+
+## Installation
+
+    npm install xpell-core
+    pnpm add xpell-core
+    yarn add xpell-core
+
+## Usage
+
+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.
+
+## When to use Xpell Core
+
+Use xpell-core directly if you are:
+
+- 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  
+
+Most end-users should install:
+
+    npm install xpell
+
+which includes xpell-core automatically.
+
+## Who Should Use xpell-core Directly?
+
+Most developers should **not** depend on xpell-core directly.
+
+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
+
+For application development, use:
+- xpell-ui
+- xpell
+
+
+## Relationship to the Xpell Framework
+
+Xpell Core powers all other Xpell packages:
+
+- xpell-ui  
+- xpell-3d  
+- xpell  
+- future Xpell II modules  
+
+## Documentation
+
+For a detailed overview of the Xpell architecture, see  
+[`docs/architecture/overview.md`](docs/architecture/overview.md).
+
+## Links
+
+https://xpell.ai
+
+GitHub:  
+https://github.com/xpell-ai/xpell-core
+
+## Versioning
+
+xpell-core follows **semantic versioning**, aligned with the main Xpell release stream.
+
+## License
+
+MIT License — © Aime Technologies, 2022–Present

package/dist/XCommand.d.ts

@@ -0,0 +1,84 @@
+/**
+ * XCommand — Runtime Command Representation
+ *
+ * Canonical command structure used by the Xpell runtime.
+ *
+ * `XCommand` represents a parsed, normalized command produced by the
+ * Xpell parser and consumed by modules (`XModule`) and runtime objects
+ * (`XObject`) for execution.
+ *
+ * ---
+ *
+ * ## Responsibilities
+ *
+ * - Represent an executable command (`_op`, `_params`, metadata)
+ * - Serve as the output of the Xpell parser
+ * - Provide a uniform execution contract across runtime layers
+ *
+ * ---
+ *
+ * ## Execution Flow
+ *
+ * - Text / JSON / CLI-style input → Xpell Parser
+ * - Parser output → `XCommand`
+ * - Execution target → `XModule` or `XObject`
+ *
+ * ---
+ *
+ * XCommand is a transportable, serializable instruction
+ * independent of execution context.
+ *
+ * One-liner: XCommand is intent made executable.
+ *
+ * @packageDocumentation
+ * @since 2022-07-22
+ * @author Tamir Fridman
+ * @license MIT
+ * @copyright
+ * © 2022–present Aime Technologies. All rights reserved.
+ */
+export type XCommandData = {
+    _module: string;
+    _object?: string;
+    _op: string;
+    _params?: {
+        [k: string]: string | number | Function;
+    };
+};
+export declare class XCommand {
+    /**
+     * The XModule to handle to command
+     */
+    _module: string;
+    /**
+     * The XObject that should handle the command (optional - uses only to send XCommand to specific object)
+     */
+    _object?: string;
+    /**
+     * The command operation (op/method) to execute
+     */
+    _op: string;
+    /**
+     * command parameters array
+     */
+    _params?: {
+        [k: string]: string | number | Function;
+    };
+    /**
+     * XCommand create date timestamp
+     */
+    d: number;
+    constructor(data?: XCommandData);
+    /**
+     * Gets th parameter value from the XCommand whether it has a name or just a position
+     * There are 2 ways to send XCommand with parameters:
+     *  1. <module> <op> <param-0> <param-1> <param-2>     // position is for this case
+     *  2. <module> <op> param-name:param-value            // name is for this case
+     * @param position the position of the parameter if no name is send
+     * @param name the name of the parameter
+     * @param defaultValue the default value if none above exists
+     * @returns {any} the actual parameter value
+     */
+    getParam(position: number, name: string, defaultValue: any): any;
+}
+export default XCommand;

package/dist/XConst.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Xpell Constants
+ *
+ * Canonical constants used across the Xpell runtime.
+ *
+ * This module defines well-known JSON node keys used by Xpell
+ * object schemas, parsers, and serializers. Centralizing these
+ * constants ensures consistency and prevents string duplication
+ * across modules.
+ *
+ * One-liner: Constants define the Xpell object language.
+ *
+ * @packageDocumentation
+ * @since 2022-07-22
+ * @author Tamir Fridman
+ * @license MIT
+ * @copyright
+ * © 2022–present Aime Technologies. All rights reserved.
+ */
+/**
+ * XObject json nodes
+ */
+export declare const NODES: {
+    readonly type: "_type";
+    readonly children: "_children";
+    readonly parent_element: "_parent_element";
+};
+export type XNodeKey = typeof NODES[keyof typeof NODES];

package/dist/XData.d.ts

@@ -0,0 +1,51 @@
+export type XDataStore = Record<string, any>;
+export type XDataMeta = {
+    source?: string;
+    trace?: boolean;
+};
+export type XDataChange = {
+    key: string;
+    value: any;
+    prev: any;
+    ts: number;
+    op: "set" | "delete" | "touch" | "patch";
+    meta?: XDataMeta;
+    stack?: string;
+};
+export type XDataListener = (change: XDataChange) => void;
+export declare class _XData {
+    private _objects;
+    private _listeners;
+    private _any_listeners;
+    _compat_writes: boolean;
+    _warn_legacy_writes: boolean;
+    _verbose: boolean;
+    _compat_legacy_keys: boolean;
+    private _o_proxy;
+    constructor();
+    /**
+     * Shared memory view.
+     * Reads are always supported.
+     * Writes are supported in compat mode (optional) and should be migrated to set()/delete()/touch().
+     */
+    get _o(): XDataStore;
+    /** Preferred read API */
+    get<T = any>(key: string): T | undefined;
+    /** Preferred write API */
+    set(key: string, value: any, meta?: XDataMeta): void;
+    /** Shallow merge helper (nice for state objects) */
+    patch(key: string, partial: Record<string, any>, meta?: XDataMeta): void;
+    /** In-place mutation notifier */
+    touch(key: string, meta?: XDataMeta): void;
+    has(key: string): boolean;
+    delete(key: string, meta?: XDataMeta): void;
+    pick<T = any>(key: string, meta?: XDataMeta): T | undefined;
+    clean(): void;
+    on(key: string, fn: XDataListener): () => void;
+    off(key: string, fn: XDataListener): void;
+    onAny(fn: XDataListener): () => void;
+    private _emit;
+}
+/** Singleton */
+export declare const XData: _XData;
+export default XData;

package/dist/XError.d.ts

@@ -0,0 +1,34 @@
+export type XErrorLevel = "info" | "warn" | "error" | "fatal";
+export type XErrorMeta = {
+    [k: string]: any;
+};
+export type XErrorOptions = {
+    _level?: XErrorLevel;
+    _meta?: XErrorMeta;
+    _cause?: unknown;
+};
+export declare class XError extends Error {
+    _code: string;
+    _level: XErrorLevel;
+    _meta?: XErrorMeta;
+    _cause?: unknown;
+    constructor(_code: string, message: string, opts?: XErrorOptions);
+    toXData(): {
+        _code: string;
+        _level: XErrorLevel;
+        _meta: XErrorMeta | undefined;
+        _cause: unknown;
+        name: string;
+        message: string;
+    };
+    toJSON(): {
+        stack: string | undefined;
+        _code: string;
+        _level: XErrorLevel;
+        _meta: XErrorMeta | undefined;
+        _cause: unknown;
+        name: string;
+        message: string;
+    };
+}
+export default XError;

package/dist/XEventManager.d.ts

@@ -0,0 +1,57 @@
+export type XEventListenerOptions = {
+    _once?: boolean;
+    _owner?: any;
+    _tag?: string;
+};
+export interface XEventListener {
+    _id: string;
+    _callback: Function;
+    _options?: XEventListenerOptions;
+    _owner?: any;
+    _tag?: string;
+}
+export type XEventListenerId = string;
+export declare class _XEventManager {
+    _log_rules: {
+        register: boolean;
+        remove: boolean;
+        fire: boolean;
+    };
+    protected _events: Record<string, XEventListener[]>;
+    protected _listener_index: Record<string, string>;
+    constructor();
+    /**
+     * Register a listener on an event name (runtime bus only).
+     *
+     * Backward compatible:
+     * - Canonical: on(name, cb, { _once, _owner, _tag })
+     * - Legacy:   on(name, cb, { _once }, owner)
+     */
+    on(event_name: string, listener: Function, options?: XEventListenerOptions, owner?: any): XEventListenerId;
+    /**
+     * Register a listener that will be removed after first fire.
+     */
+    once(event_name: string, listener: Function, owner?: any): XEventListenerId;
+    /**
+     * Fire an event with optional payload.
+     */
+    fire(event_name: string, data?: any): Promise<void>;
+    /**
+     * Remove a listener by id.
+     */
+    remove(listener_id: string): void;
+    /**
+     * Remove all listeners for a given owner reference.
+     */
+    removeOwner(owner: any): void;
+    /**
+     * Clear the entire event bus (mostly for tests / hard reset).
+     */
+    clear(): void;
+}
+/**
+ * Global Xpell event manager instance.
+ */
+export declare const XEventManager: _XEventManager;
+export declare const _xem: _XEventManager;
+export default XEventManager;

package/dist/XLogger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * XLogger — Xpell Logging Engine (v2)
+ *
+ * Dev mode:
+ *   - `_xlog` is mapped to `console` for correct callsites in DevTools.
+ * Production mode:
+ *   - `_xlog` is mapped to `XLogger` for consistent formatting & controls.
+ */
+export type XLogLevel = "log" | "debug" | "warn" | "error";
+export type XLoggerOptions = {
+    _enabled?: boolean;
+    _show_date?: boolean;
+    _show_time?: boolean;
+    _debug?: boolean;
+};
+export declare class _XLogger {
+    _enabled: boolean;
+    _show_date: boolean;
+    _show_time: boolean;
+    _debug: boolean;
+    constructor(opts?: XLoggerOptions);
+    configure(opts: XLoggerOptions): void;
+    private _dt;
+    log(message?: any, ...optional_params: any[]): void;
+    warn(message?: any, ...optional_params: any[]): void;
+    error(message?: any, ...optional_params: any[]): void;
+    debug(message?: any, ...optional_params: any[]): void;
+}
+/** Singleton */
+export declare const XLogger: _XLogger;
+export default XLogger;
+export declare const _xlog: Pick<Console, "log" | "warn" | "error" | "debug">;

package/dist/XModule.d.ts

@@ -0,0 +1,161 @@
+/**
+ * XModule — Base Runtime Module
+ *
+ * Abstract base class for all Xpell runtime modules.
+ *
+ * XModule defines the contract for extending the Xpell interpreter
+ * with modular functionality, object ownership, and executable commands.
+ *
+ * ---
+ *
+ * ## Module Rules
+ *
+ * - Every module MUST have a unique name
+ * - Each module owns an Object Manager responsible for module-specific XObjects
+ * - Child XObjects are managed via their parent and not independently
+ * - Modules may execute commands via `XCommand`, JSON, or CLI-style text
+ *
+ * ---
+ *
+ * ## Command Exposure Rules
+ *
+ * - Methods prefixed with `_` are exposed to the Xpell interpreter
+ * - Public command names:
+ *   - Strip the leading `_`
+ *   - Convert spaces and dashes to underscores
+ *
+ * ---
+ *
+ * ## Example
+ *
+ * ```ts
+ * class MyModule extends XModule {
+ *   _my_Command(xCommand) {
+ *     // command implementation
+ *   }
+ * }
+ *
+ * // Invocation:
+ * XModule.execute("my-Command")
+ * ```
+ *
+ * ---
+ *
+ * XModule is the extension point that turns the Xpell core
+ * into a programmable runtime.
+ *
+ * One-liner: XModule is how behavior enters the Xpell runtime.
+ *
+ * @packageDocumentation
+ * @since 2022-07-22
+ * @author Tamir Fridman
+ * @license MIT
+ * @copyright
+ * © 2022–present Aime Technologies. All rights reserved.
+ */
+import XObjectManager from "./XObjectManager";
+import { XObjectData, XObject, XObjectPack } from "./XObject";
+import XCommand, { XCommandData } from "./XCommand";
+export type XModuleData = {
+    _name: string;
+};
+export declare const XD_MODULE_NUM_OF_OBJECTS = "engine:module:num-of-objects:";
+/**
+ * Xpell Base Module
+ * This class represents xpell base module to be extends
+ * @class XModule
+ *
+ */
+export declare class XModule {
+    #private;
+    [k: string]: any;
+    _id: string;
+    _name: string;
+    _log_rules: {
+        createObject: boolean;
+        removeObject: boolean;
+    };
+    constructor(data: XModuleData);
+    load(): void;
+    /**
+     * Creates new XObject from data object
+     * @param data - The data of the new object (JSON)
+     * @return {XObject|*}
+     */
+    create(data: XObjectData): any;
+    /**
+     * removes and XObject from the object manager
+     * @param objectId op
+     */
+    remove(objectId: string): void;
+    _info(xCommand: XCommand): void;
+    /**
+     * Run xpell command -
+     * CLI mode, parse the command to XCommand JSON format and call execute method
+     * @param {string} XCommand input - text
+     * @returns command execution result
+     */
+    run(stringXCommand: string): Promise<any>;
+    /**
+     * execute xpell command - CLI mode
+     * @param {XCommand} XCommand input (JSON)
+     * @returns command execution result
+     */
+    execute(xCommand: XCommand | XCommandData): Promise<any>;
+    /**
+     * This method triggers every frame from the Xpell engine.
+     * The method can be override by the extending module to support extended onFrame functionality
+     * @param frameNumber Current frame number
+     */
+    onFrame(frameNumber: number): Promise<void>;
+    /**
+     * X Object Manager
+     */
+    /**
+     * getter for om (object manager) instance
+     * @returns {XObjectManager}
+     * @deprecated - use _object_manager instead
+     * If you wish to get an object from the object manager use
+     * getObject directly on the module instead of om.getObject
+     */
+    get om(): XObjectManager;
+    get _object_manager(): XObjectManager;
+    /**
+     * Returns the XObject instance from the module Object Manager
+     * @param objectId
+     * @returns XObject
+     */
+    getObject(objectId: string): XObject;
+    /**
+     * Returns the XObject instance from the module Object Manager
+     * Usage:
+     * xmodule._o["object-id"] is equivalent to xmodule.getObject("object-id")
+     */
+    get _o(): import("./XObjectManager").XObjectManagerIndex;
+    /**
+     * Imports external object pack to the engine
+     * The object class should be like XObjects with static implementation of getObjects() method
+     * @param {XObjects} xObjectPack
+     */
+    importObjectPack(xObjectPack: XObjectPack | any): void;
+    /**
+     * Imports external object pack to the engine
+     * @deprecated - use importObjectPack instead
+     * @param xObjectPack
+     */
+    importObjects(xObjectPack: XObjectPack | any): void;
+    /**
+     * Imports external objects to the engine
+     * The object class should be like XObjects with static implementation of getObjects() method
+     * @param xObjectName
+     * @param xObject
+     */
+    importObject(xObjectName: string, xObject: XObject): void;
+    _help(cmd: any): Promise<any>;
+    /**
+     * Override in modules to provide help text.
+     * @param op optional: specific command name (e.g. "navigate")
+     */
+    help(op?: string): any;
+}
+export default XModule;

package/dist/XNanoCommands.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+export interface XNanoCommand {
+    (xCommand: XCommand | XCommandData, xObject: XObject): any;
+}
+/**
+ * x-nano-command pack
+ */
+export type XNanoCommandPack = {
+    [k: string]: XNanoCommand;
+};
+/**
+ * XNanoCommand Pack
+ */
+export declare const _xobject_basic_nano_commands: XNanoCommandPack;
+declare const _default: XNanoCommandPack;
+export default _default;