@xpell/core 2.0.1 → 2.0.3

package/docs/AGENTS.md

@@ -0,0 +1,10 @@
+# XPELL-CORE codex.md rules for ai agent for vibe coding with xpell-core
+## `packages/xpell-core/AGENTS.md`
+
+# AGENTS.md — @xpell/core
+
+Before making changes, apply:
+
+- docs/skills/xpell-contract
+- docs/skills/xpell-core
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpell/core",
-  "version": "2.0.01",
+  "version": "2.0.3",
   "publishConfig": {
     "access": "public"
   },
@@ -52,7 +52,7 @@
   "devDependencies": {
     "typedoc": "^0.27.9",
     "typescript": "^5.9.3",
-    "vite": "^7.3.2"
+    "vite": "^7.3.3"
   },
   "scripts": {
     "dev": "vite",

package/docs/Codex.md

@@ -1,138 +0,0 @@
-# XPELL-CORE codex.md rules for ai agent for vibe coding with xpell-core
-
-## Purpose
-This document defines the strict contract for **xpell-core** — the runtime engine and interpreter that powers all Xpell systems.
-
----
-
-## Core Responsibilities
-xpell-core provides:
-- Engine loop
-- Event system
-- Command system
-- Data layer (XData)
-- Object lifecycle (XObject)
-- Module loading (XModule)
-
-xpell-core does **NOT** provide UI rendering.
-
----
-
-## Runtime Object Model
-
-- `XObject` is the foundational runtime object.
-- XObject is **UI-agnostic** and MUST NOT include or assume:
-  - DOM access
-  - visibility logic
-  - UI methods (`show`, `hide`, etc.)
-
-UI behavior is added only by higher-level layers (e.g. `XUIObject`).
-
----
-## XData Contract (XData2)
-
-- XData is shared runtime memory (process-wide), used for explicit state sharing and signaling.
-- XData is NOT persistence.
-- Keys must be explicit, stable, and documented at their point of use.
-- No module may mirror XData into hidden local mutable state as a “shadow source of truth”.
-
-### Canonical API (required)
-All new code MUST use the XData2 API:
-
-- Read: `XData.get(key)` / `_xd.get(key)`
-- Write: `XData.set(key, value, { source })` / `_xd.set(...)`
-- Delete: `XData.delete(key, { source })` / `_xd.delete(...)`
-- Subscribe: `XData.on(key, cb)` / `_xd.on(...)`
-- Notify without changing value (optional): `XData.touch(key, { source })`
-- Mailbox semantics (optional): `XData.pick(key, { source })`
-
-### Compatibility API (legacy)
-- Direct object access via `_o` is LEGACY compatibility only:
-  - `XData._o[key] = value`
-  - `_xd._o[key] = value`
-- `_o` access MAY exist only to support old code and migration.
-- New code MUST NOT write via `_o`.
-- Core may optionally:
-  - warn in dev on legacy writes (`_warn_legacy_writes`)
-  - route legacy writes through `.set()` (`_compat_writes`)
-- Whether `_o` triggers notifications is a configuration detail of XData2, not a contract.
-
-### Required metadata
-- Every `.set()` and `.delete()` in core/runtime code MUST include a `source` string.
-  - Example: `{ source: "xvm:navigate" }`
-- `source` must be stable and human-readable for debugging.
-
-### Rules
-- Do not assume ordering of listeners.
-- Avoid high-frequency writes unless necessary (frame loop keys should be intentional).
-- Do not use XData as an event bus; use XEventManager (`_xem`) for events.
-
----
-
-## Naming Convention — Runtime State
-
-- All runtime-managed object members MUST:
-  - start with `_`
-  - use `snake_case`
-
-- Method names MAY use `camelCase`.
-
-This defines the boundary between runtime state and implementation logic.
-
----
-
-## Method Exposure & Command Mapping
-
-### Method Visibility
-- Methods starting with `_` are **public to the Xpell engine**.
-- Such methods may be invoked via `run / execute`.
-- Methods without `_` are internal-only.
-
-This replaces legacy descriptor-based exposure.
-
-### Command Name Mapping
-- Leading `_` is removed when invoked.
-- `_` and `-` are interchangeable.
-- No other transformations are allowed.
-
-Example:
-```ts
-public _my_x_method(cmd) { ... }
-```
-
-Callable as:
-```txt
-my_x_method
-my-x-method
-```
-
----
-
-## Parser Responsibilities
-
-- `XParser.parse()` → module-level commands only.
-- Object / nano-command parsing is internal and separate.
-- Parsers must not infer or substitute for one another.
-- Parsing never executes commands or mutates state.
-
----
-
-## Platform Rules
-
-- xpell-core is platform-agnostic by design.
-- Platform-specific logic must be isolated.
-- Core must not assume DOM, UI, or filesystem access.
-
----
-
-## Forbidden Patterns ❌
-- UI logic in core
-- Implicit globals
-- Hidden mutable state
-- Framework-style lifecycles
-- API inference or auto-magic
-
----
-
-## One-Line Anchor
-**xpell-core is a real-time interpreter engine that provides execution, data, and events for Xpell systems.**

package/docs/Codex_Skills/SKILL.md

@@ -1,184 +0,0 @@
----
-name: Xpell Core Contract
-id: xpell-core
-version: 1.0.0
-updated: 2026-02-26
-description: Foundational runtime contract for @xpell/core: deterministic interpreter, XData2 shared state, Nano-Commands v2, XEM event bus, and module/object base classes. Enforces data-first AI-native execution.
-requires: 
-  - xpell-contract
----
-
-## 1) Applies to / Scope
-- Package: `@xpell/core` in this repository.
-- Source of truth scanned: `package.json`, all `src/*.ts`, `README.md`, `docs/Codex.md`, `docs/XData 2.md`, `docs/nano-commands2.md`, `docs/architecture/overview.md`, and built type entry (`dist/index.d.ts`).
-- This contract governs code that depends on core directly, and integration layers built on top (`@xpell/ui`, `@xpell/node`, `@xpell/3d`, app repos).
-
-## 2) Core identity (what it is / isn’t)
-What it is:
-- A runtime/interpreter core with:
-- engine loop + scheduler (`XpellEngine.onFrame`, `start`)
-- command dispatch (`run`, `execute`)
-- shared runtime state (`XData` / `_xd`)
-- event bus (`XEventManager` / `_xem`)
-- base extension/object model (`XModule`, `XObject`, `XObjectManager`)
-
-What it is not:
-- Not a UI renderer or DOM layer.
-- Not a persistence/database layer.
-- Not an app/business framework.
-- Not a hidden-state runtime; contracts are explicit.
-
-Code reality caveat:
-- `XParser.xmlString2Xpell()` uses `DOMParser`; this helper requires an environment that provides it.
-
-## 3) Public API map (high level; details in SKILL_API_MAP.md)
-- Package export surface is a single public subpath: `"."` (plus `"./package.json"`).
-- Public entrypoint re-exports from `src/Xpell.ts` via `src/index.ts`.
-- High-level API groups:
-- Engine/runtime singleton: `Xpell`, `_x`, `XpellEngine`
-- State: `XData`, `_xd`, `_XData`
-- Events: `XEventManager`, `_xem`, `_XEventManager`
-- Modules/objects: `XModule`, `XObject`, `XObjectManager`, `XObjectPack`
-- Commands/parsing: `XCommand`, `XParser`, nano-command types
-- Utility/protocol/error: `XUtils`, `XParams`, `XResponse*`, `XError`, `XLogger`
-- Integration expectations by layer:
-- `@xpell/ui`: implements UI-specific objects/ops on top of core (`XObject` stays UI-agnostic in core).
-- `@xpell/3d`: implements 3D/spatial behavior on top of core lifecycle, events, and commands.
-- `@xpell/node`: uses core runtime contracts (commands/events/XData/protocol) without DOM assumptions.
-- App repos: should depend on higher layers (`@xpell/ui`, `@xpell/node`, `@xpell/3d`) unless extending engine internals directly.
-- Detailed package-specific operation allowlists for `@xpell/ui`, `@xpell/3d`, and `@xpell/node` are `unknown` in this repo (not defined under `@xpell/core` source).
-
-## 4) Runtime invariants (single source of truth, execute path, state, events)
-- Single source of truth:
-- Engine module registry inside `_x` (`_modules`) is authoritative for module command routing.
-- Runtime shared data keys live in `XData`; object-level behavior lives on `XObject` instances.
-- Execute path:
-- `_x.run("...")` -> `XParser.parse(...)` -> `_x.execute(xcmd)`.
-- `_x.execute(xcmd)` requires `xcmd._module` and a loaded module; otherwise throws.
-- `XModule.execute(xcmd)`:
-- if `xcmd._object` exists: dispatches to that object’s `XObject.execute(...)`.
-- else maps op to module method: `"_"+_op.replaceAll("-", "_")`; missing op throws.
-- `XObject.execute(xcmd)` resolves `_op` in object’s `_nano_commands`; missing op logs error.
-- Loop/state:
-- Engine increments frame, calls each module `onFrame`, then writes:
-- `engine:frame-number`
-- `engine:fps`
-- legacy keys `frame-number` / `fps` only when `_compat_legacy_keys` is true.
-- Events:
-- Event coordination uses `_xem` (`on`, `once`, `fire`, `remove`, `removeOwner`).
-- `XObject` event handlers are parsed once on mount and cleaned on dispose.
-- Serialization:
-- `XObject.toXData()` drops function fields.
-- `XResponse.toXData()` returns transport-safe response envelope.
-
-## 5) XData2 contract (keys, mutation rules, no hidden mirrors)
-- Canonical API: `get`, `set`, `patch`, `touch`, `has`, `delete`, `pick`, `on`, `off`, `onAny`, `clean`.
-- Mutations emit `XDataChange` with `{ key, value, prev, ts, op, meta }`.
-- `_o` exists for compatibility and can proxy writes/deletes to canonical methods when `_compat_writes=true`.
-- Listener order should not be relied on by consumers.
-- Keys should be explicit and stable (contract/documentation requirement).
-- Hidden mirrored mutable state is forbidden by contract (`docs/Codex.md`), not automatically enforced by runtime code.
-- `source` metadata on writes/deletes is required by contract docs, but enforcement is partial: code accepts missing `meta` (`unknown` enforcement completeness).
-
-## 6) Nano-Commands v2 contract (data-only, JSON form, sequences if present)
-- Handler forms supported by `XObject` runtime:
-- function (dev/runtime-authored)
-- string nano-command
-- JSON command object with `_op` (and optional `_params`)
-- arrays/sequences of handlers (executed in order, awaited)
-- JSON handler target rules in `XObject.checkAndRunInternalFunction`:
-- `_object` may be omitted, `"this"`, or the current object id.
-- non-self targets are rejected (logged, not executed).
-- Built-in nano commands in core pack include:
-- `info`, `log`, `fire`, `noop`, `set-field`, `delete-field`, `toggle-field`, `merge`, `run-seq`
-- `run-seq` exists in code and enforces self-targeted steps only.
-- Contract mismatch to note:
-- `docs/nano-commands2.md` says “no run-seq nano command”; source code currently implements `"run-seq"`.
-- Data-only requirement for DB-stored views is documented, but runtime does not globally block function handlers (`unknown` global validation boundary).
-
-## 7) XEM contract (events are not a state store; payload explicit; ordering not assumed)
-- API: `on`, `once`, `fire`, `remove`, `removeOwner`, `clear`.
-- Events are coordination only; state belongs in `XData`.
-- Payload is explicit (`fire(event_name, data)`).
-- Listener order should not be assumed by consumers. Current implementation iterates a snapshot in registration order.
-- Listener exceptions are caught and logged; dispatch continues.
-
-## 8) XModule contract (only extension point; naming; ops; cross-module boundaries)
-- `XModule` is the base extension point for behavior.
-- Module identity uses `_name` and `_id`.
-- Command exposure is underscore-prefixed methods:
-- command `"my-op"` maps to method `"_my_op"`.
-- Objects are created/owned through module’s `XObjectManager`.
-- Object-targeted commands require explicit `_object` id.
-- No fallback object-name command resolution in `execute` (explicitness over ambiguity).
-- Cross-module behavior should go through engine dispatch/events/XData contracts; direct hidden mutation across modules is an anti-pattern.
-
-## 9) XObject contract (no UI assumptions; lifecycle; no platform coupling)
-- `XObject` is the base runtime node, not a UI object.
-- Lifecycle hooks:
-- `onCreate`
-- `onMount` (parses events, binds `_data_source`)
-- `onData`
-- `onFrame`
-- `dispose` (unbind data, remove listeners, clear refs, dispose children)
-- Data-source binding is subscription-based (`_xd.on`), not frame polling.
-- Exports are JSON-first via `toXData`; functions are omitted.
-- `XObject` itself is UI-agnostic; UI methods belong to higher layers (`@xpell/ui`).
-
-## 10) Hard forbiddens (explicit bullets)
-- Do not add UI behavior (DOM/show/hide/layout/CSS assumptions) to `@xpell/core` base classes.
-- Do not use `XData` as an event bus; use `_xem`.
-- Do not rely on hidden mirrors of `XData` as shadow state.
-- Do not write new code via `XData._o[...]` when canonical methods are available.
-- Do not assume listener ordering semantics.
-- Do not use `eval`, `new Function`, or executable code inside persisted command payloads.
-- Do not perform implicit cross-object targeting in JSON handlers; keep handlers local unless explicitly supported by runtime boundary.
-- Do not couple core to Node FS/DOM-only APIs in base runtime contracts.
-
-## 11) Error + logging contract (structured errors, no secret logs)
-- Structured error type: `XError` with `_code`, `_level`, `_meta`, `_cause`, `message`.
-- Protocol envelope: `XResponse` / `XResponseOK` / `XResponseError` with `_ok`, `_ts`, `_pt`, `_result`.
-- Unknown errors are normalized to `XError("E_INTERNAL", ...)` in `XResponse.error`.
-- Logging:
-- `XLogger` singleton is configurable.
-- `_xlog` is `console` in dev and `XLogger` in production.
-- Secret redaction is not built into logger (`unknown` automated redaction policy). Treat sensitive data logging as forbidden at usage level.
-
-## 12) Minimal examples (2–3 short snippets, proven by repo patterns)
-```ts
-import { _x, XModule } from "@xpell/core";
-
-class DemoModule extends XModule {
-  constructor() { super({ _name: "demo" }); }
-  _ping(cmd: any) { return cmd?._params?.msg ?? "pong"; }
-}
-
-_x.loadModule(new DemoModule());
-const out = await _x.execute({ _module: "demo", _op: "ping", _params: { msg: "hi" } });
-```
-
-```ts
-import { _xd } from "@xpell/core";
-
-const off = _xd.on("engine:fps", (ch) => {
-  console.log("fps:", ch.value);
-});
-
-_xd.set("engine:fps", 60, { source: "example:fps" });
-off();
-```
-
-```ts
-import { XObject } from "@xpell/core";
-
-const obj = new XObject({
-  _id: "obj-1",
-  _on_data: [
-    { _op: "log" },
-    { _op: "set-field", _params: { name: "_name", value: "updated" } }
-  ]
-});
-
-await obj.onMount();
-await obj.onData({ value: 1 });
-```

package/docs/Codex_Skills/SKILL_API_MAP.md

@@ -1,122 +0,0 @@
-# @xpell/core Skill API Map
-
-## 1) package.json exports map
-
-Verbatim export keys:
-- `"."`
-- `"./package.json"`
-
-Resolved values summary:
-- `"."`:
-- `types`: `./dist/index.d.ts`
-- `import`: `./dist/xpell-core.es.js`
-- `require`: `./dist/xpell-core.cjs.js`
-- `"./package.json"` -> `./package.json`
-
-Related package entry fields:
-- `main`: `./dist/xpell-core.cjs.js`
-- `module`: `./dist/xpell-core.es.js`
-- `types`: `./dist/index.d.ts`
-
-## 2) Entrypoints and what they export
-
-### `src/index.ts`
-- `export * from "./Xpell"`
-- `export { default } from "./Xpell"`
-
-### `src/Xpell.ts` (public surface re-exported by package root)
-Engine:
-- `XpellEngine`
-- `Xpell` (singleton), `_x` alias
-- `XD_FRAME_NUMBER`, `XD_FPS`
-
-State:
-- `XData`, `_xd`, `_XData`
-- `type XDataStore`
-
-Events:
-- `XEventManager`, `_xem`, `_XEventManager`
-- `type XEventListener`
-- `type XEventListenerOptions`
-
-Modules/objects:
-- `XModule` + `type XModuleData`
-- `XObject`, `XObjectPack`
-- `XObjectManager`
-- `type XObjectData`
-- `type XObjectOnEventIndex`
-- `type XObjectOnEventHandler`
-- `type XDataXporter`
-- `type XDataXporterHandler`
-- `type IXData`
-- `type XValue`
-
-Commands/parsing:
-- `XParser`
-- `XCommand` + `type XCommandData`
-- `type XNanoCommandPack`
-- `type XNanoCommand`
-- `XParams`
-
-Utilities/runtime helpers:
-- `XUtils`, `_xu`, `_XUtils`
-- `type XFrameScheduler`
-- `XLogger`, `_xlog`, `_XLogger`
-
-Protocol/errors:
-- `XError` + `type XErrorOptions` + `type XErrorLevel` + `type XErrorMeta`
-- `XResponse`, `XResponseOK`, `XResponseError`
-- `type XResponseData`
-
-## 3) Main folders/subsystems
-
-`src/Xpell.ts`
-- Engine singleton and frame loop, module loading, top-level command dispatch.
-
-`src/XData.ts`
-- XData2 shared runtime memory, change events, legacy `_o` compatibility proxy.
-
-`src/XNanoCommands.ts`
-- Built-in object nano-commands (`info`, `log`, `fire`, `noop`, field mutators, `run-seq`).
-
-`src/XEventManager.ts`
-- Process-wide event bus with listener ids, owner cleanup, one-time listeners.
-
-`src/XModule.ts`
-- Base module extension point, object registry ownership, op dispatch mapping.
-
-`src/XObject.ts`
-- Base runtime object with lifecycle hooks, event wiring, data-source binding, nano-command execution, JSON export.
-
-`src/XObjectManager.ts`
-- Registry for object classes and live module-owned objects.
-
-`src/XParser.ts` + `src/XCommand.ts`
-- Text/object command parsing and canonical command shape.
-
-`src/XProtocol.ts` + `src/XError.ts`
-- Response envelope and structured error model.
-
-`src/XUtils.ts`, `src/XLogger.ts`, `src/XParams.ts`, `src/XConst.ts`
-- Runtime utilities, logging, parameter helpers, shared node constants.
-
-## 4) Hot classes/singletons for maintainers
-
-Hot singletons:
-- `_x` / `Xpell` -> global engine instance
-- `_xd` / `XData` -> global runtime state store
-- `_xem` / `XEventManager` -> global event bus
-- `_xlog` / `XLogger` -> logging facade
-- `_xu` / `XUtils` -> utility singleton
-
-Hot base classes:
-- `XModule` -> extension boundary for module behavior
-- `XObject` -> base runtime object (no UI assumptions)
-- `XObjectManager` -> module object/class registry
-- `XCommand` -> normalized command envelope
-- `_XData`, `_XEventManager`, `_XLogger`, `_XUtils` -> class-level implementations behind singletons
-
-## 5) Maintainer notes (code-vs-doc reality)
-
-- `docs/nano-commands2.md` states “no run-seq nano command”, but `src/XNanoCommands.ts` currently implements `"run-seq"`.
-- Data-only handlers are documented as required for persisted views, but `XObject` still accepts function handlers (runtime/dev use).

package/docs/Codex_Skills/SKILL_CHECKLIST.md

@@ -1,18 +0,0 @@
-# @xpell/core Codex Checklist
-
-Use this checklist before generating or editing code that depends on `@xpell/core`.
-
-- [ ] Do not infer missing runtime state. Use explicit keys/params only.
-- [ ] Treat `XData` as shared runtime memory, not persistence or an event bus.
-- [ ] Use canonical `XData` APIs (`get/set/delete/touch/patch/on`), not new writes via `_o`.
-- [ ] Include stable `source` metadata on `XData.set/delete/touch/pick` calls.
-- [ ] Route cross-module behavior through `_x.execute(...)`, `_xem`, or documented `XData` keys.
-- [ ] Ensure `_x.execute` payload includes `_module` and `_op`; include `_object` only for explicit object targeting.
-- [ ] In `XModule`, expose executable ops as underscore methods (`_op_name`) and keep op names explicit.
-- [ ] In `XObject`, keep handlers local/data-first: string, JSON command, or array sequence; avoid function handlers for persisted/agent-editable payloads.
-- [ ] Do not assume event listener ordering; treat `_xem` events as coordination signals only.
-- [ ] Keep core usage platform-neutral: no UI/DOM/Node-FS assumptions unless the code path explicitly supports that environment.
-- [ ] Do not add UI behavior to core base classes (`XObject`, `XModule`, engine).
-- [ ] Use structured errors (`XError`) and protocol responses (`XResponse*`) for transport-facing failures.
-- [ ] Avoid logging secrets/sensitive payloads; `_xlog` has no built-in redaction guarantee.
-- [ ] If docs and source disagree, follow source code and record the mismatch.