EUIX Core Diet — Simplification & Pruning Architectural Plan

Core Philosophy: Make EUIX minimal by default and powerful by opt-in. Core Identity: A lightweight reactive declarative UI runtime that turns markup + state + events into DOM updates without requiring a build step or a virtual DOM.

1. Executive Summary & Audit Overview #

Over its development history, EUIX evolved from a fast, zero-VDOM XML/HTML declarative runtime into an expansive application framework. While individual capabilities (SWR client, nested router with data loaders, SQL-like XML array mutations, WebMCP LLM tools, SVG charts, Leaflet GIS) are impressive in isolation, their combined presence in the default distribution has caused significant issues:

• Bundle Inflation: The default bundle (dist/EUIXEngine.es.js) stands at 755.4 KB raw and 148.0 KB gzip. Even Lite Core (dist/EUIXEngineCore.es.js) is 355.0 KB raw and 69.5 KB gzip.
• Inverted Dependency Direction: Core runtime files (DOMRenderer.js, Lifecycle.js, constants.js, EUIXEngineCore.js) have hardcoded knowledge of optional plugins (e.g., $route, $api, $stream, errors., navigator_config, date_config, REVALIDATE_API, ANIMATE).
• XML Programming Language Anti-Pattern: XML templates acquired imperative programming constructs: <try><catch><finally>, <throw>, <action_def><param><step><return>, and a 600-line pseudo-SQL array query engine in MUTATE_STATE.
• Platform Duplication: Declarative abstractions like <flex direction="..." gap="..."> duplicate native CSS flexbox/grid that developers already write with utility classes.
• Conceptual Overload: Instead of learning 5–8 intuitive concepts, a newcomer faces SWR, resilience pipelines, state history snapshots, navigation blockers, and chart specifications on day one.

This plan details the Milestone 1 Audit and provides the architectural blueprint to return EUIX to an ultra-fast, lean core runtime (<= ~20 KB gzip target) while preserving advanced capabilities through decoupled, opt-in plugins.

2. Baseline Measurements & Bundle Analysis #

Measured on Node v23.1.0 with Terser minification and zlib compression:

2.1 Core & Primary Bundles #

2.2 Modular Plugins Breakdown #

2.3 Repository Source Code Volume #

• src/core/: 11,367 LOC across 17 files
• src/plugins/: 16,331 LOC across 38 files
• src/compiler/: 1,117 LOC across 3 files
• src/server/: 600 LOC across 1 file
• tests/: 31,009 LOC across 162 files (790 automated test cases)
• docs/: 4,350 LOC across 55 documentation files

3. Dependency Map & Architectural Hotspots #

3.1 Existing Inverted Dependencies (Core Leaks) #

Core should have zero knowledge of plugins. Currently, several core modules reach out or bake in awareness of specific plugins:

[Core: DOMRenderer.js]   ── hardcodes ──> $route, $router, $fetcher (Router)
                         ── hardcodes ──> api, $api (Api Plugin)
                         ── hardcodes ──> stream, $stream (Stream Plugin)
                         ── hardcodes ──> errors, $errors (Validation Plugin)

[Core: constants.js]     ── hardcodes ──> METADATA_AND_EVENT_TAGS:
                                            navigator_config, device_config,
                                            date_config, date_settings,
                                            actions, action_def, workflow_def,
                                            animations, keyframe_def,
                                            api_config, api_endpoint, persistence
                         ── hardcodes ──> ACTION_DISPATCH_TABLE:
                                            REVALIDATE_API, ANIMATE, TRANSITION,
                                            RETRY_ERROR_BOUNDARY, UNDO_STATE,
                                            REDO_STATE, TAKE_SNAPSHOT

[Core: Lifecycle.js]     ── hardcodes ──> initDataModel queries:
                                            <computed>, <watch>, <animation_def>,
                                            <persistence>, <api_config>, <api_endpoint>

[Core: EUIXEngineCore.js]── hardcodes ──> constructor initializes:
                                            _apiConfig, _registeredXhrs, _xhrCache,
                                            _actionRegistry, _depGraph,
                                            _computedRegistry, _watchRegistry,
                                            _setupStorageListener, _initRevalidationListeners

3.2 Target Dependency Direction #

The target architecture enforces strict unidirectionality:

                  +-----------------------------------+
                  |            EUIX Core              |
                  |  State, Parser, Renderer, Events, |
                  |       Components, Slots, Hooks    |
                  +-----------------------------------+
                                    ▲
                                    │ (public extension APIs:
                                    │  .use(), hooks, registerAction,
                                    │  registerBindingNamespace)
         +--------------------------+--------------------------+
         │                          │                          │
+-----------------+        +-----------------+        +-----------------+
|   Core Plugins  |        | UI Convenience  |        |   Ecosystem     |
|   (Api, Router, |        | (Animation, Dnd,|        | (Leaflet, Chart,|
|   Composer,     |        |  A11y, Storage, |        |  Date, WebMCP,  |
|   Reactive)     |        |  VirtualList)   |        |  DevTools)      |
+-----------------+        +-----------------+        +-----------------+

4. Complete Feature Classification Matrix #

Every capability in EUIX is classified into one of five categories:

4.1 KEEP IN CORE #

Essential to the fundamental EUIX runtime.

4.2 SIMPLIFY #

Belongs in core, but its implementation has become unnecessarily complex.

4.3 MOVE TO PLUGIN #

Useful capability, but not required for basic EUIX applications.

4.4 ECOSYSTEM / INTEGRATION #

Domain-specific capabilities that belong in external/ecosystem packages rather than defining the EUIX runtime.

4.5 DEPRECATE / REMOVE #

Features that duplicate native browser/HTML/CSS functionality or introduce disproportionate complexity.

5. Architectural Deep Dives #

5.1 Removing Duplicate Platform Abstractions #

Currently, DOMRenderer.js executes applyLayoutStyles() and applyItemChildStyles() across every <flex> and <grid> element:

// BEFORE: DOMRenderer.js parses 16 different layout attributes
const direction = xmlNode.getAttribute("direction") || xmlNode.getAttribute("flex_direction") || xmlNode.getAttribute("dir");
const align = xmlNode.getAttribute("align") || xmlNode.getAttribute("align_items");
const justify = xmlNode.getAttribute("justify") || xmlNode.getAttribute("justify_content");
const gap = xmlNode.getAttribute("gap");
// ... 150 more lines of string parsing and regex matching

Diet Decision:

1. Core stops treating <flex> and <grid> as special privileged tags. They render as standard HTML elements or can be written cleanly as:
   XML

   Copy

   <!-- Native HTML & CSS: Zero runtime cost, zero bytes in core -->
   <div class="flex flex-col gap-4 items-center justify-between">
     <h1>Clean Markup</h1>
   </div>

2. For backward compatibility, an optional EUIXLayoutCompatPlugin or legacy shim can translate legacy <flex> and <grid> attributes if explicitly loaded.

5.2 Action System Simplification #

The Problem: XML as a Programming Language

Currently, developers can write entire imperative programs in XML:

<!-- ANTI-PATTERN: Imperative programming inside XML -->
<on_click action="TRY">
  <try>
    <step action="MUTATE_STATE">
      <path>users</path>
      <operation>REMOVE</operation>
      <where field="id" equals="{item.id}" />
    </step>
    <step action="REVALIDATE_API" tag="get_users" />
  </try>
  <catch>
    <step action="RUN_SCRIPT">alert('Failed!');</step>
  </catch>
</on_click>

The Solution: Declarative for Simple, JavaScript for Complex

The core action dispatcher converges to 4 fundamental primitives:

1. SET: Update a state path directly (e.g. on_click:set="count={data.count + 1}" or <on_click set="count" value="10" />).
2. TOGGLE: Invert a boolean state path (e.g. on_click:toggle="isOpen").
3. CALL: Invoke a registered JavaScript function with context (e.g. on_click="deleteUser" or <on_click action="deleteUser" />).
4. EMIT: Dispatch a custom DOM/EUIX event.

<!-- REFACTORED: Clean, declarative, maintainable -->
<button on_click="deleteUser" data-id="{item.id}">Delete</button>

With application logic defined where it belongs — in JavaScript:

engine.action("deleteUser", async ({ $data, $el }) => {
  const id = $el.dataset.id;
  try {
    $data.users = $data.users.filter(u => u.id !== id);
    await api.delete(`/users/${id}`);
  } catch (err) {
    alert("Failed to delete user");
  }
});

• Action Composer (<action_def>): Remains available as an opt-in plugin (euixjs/composer) for users who specifically need XML workflow orchestration.
• RUN_SCRIPT: Preserved as an advanced escape hatch for rapid prototyping and zero-build demos, but de-emphasized in documentation.

5.3 Decoupling the API Layer #

The Boundary:

Core should have zero references to:

• _apiConfig
• _registeredXhrs
• _xhrCache
• REVALIDATE_API
• {api.<id>.<prop>}

Extension Mechanism:

EUIXApiPlugin uses documented extension points:

1. Hook: engine.on('lifecycle:init', () => { /* setup endpoints */ })
2. Custom Action: engine.registerAction('REVALIDATE_API', (actionNode, ctx) => { ... })
3. Namespace Resolver: engine.registerBindingNamespace('api', (key, ctx) => apiStatusTracker.get(key))

A developer who does not use euixjs/api pays 0 KB and learns 0 API concepts.

5.4 Decoupling the Router #

The router currently weighs 89.6 KB raw / 18.5 KB gzip and imports features matching React Router / TanStack:

• data/loader.js, data/action.js, data/fetcher.js, data/cache.js, data/revalidation.js
• navigation/blocker.js, navigation/prefetch.js, navigation/scroll.js, navigation/transitions.js
• server/static-router.js, server/hydration.js

Router Diet:

1. Minimal Router (euixjs/router):
   • Route matching (path parsing, wildcard, params :id)
   • Navigation (navigate(to), pushState/replaceState, popstate)
   • <route path="..." component="..."> and <outlet /> rendering
   • <route_link to="...">
   • Target weight: < 15 KB raw / ~4 KB gzip.
2. Advanced Router Capabilities (euixjs/router/advanced or modular opt-ins):
   • Loaders, actions, fetchers, navigation blockers, scroll restoration, and View Transitions become opt-in extensions or secondary modules.

5.5 Reactive Utilities Boundary #

6. Default Import Philosophy & Package Strategy #

6.1 Desired Default Import #

import { EUIX } from 'euixjs' must import the lightweight Core runtime.

// NEW DEFAULT: Clean, lean, modular (< 20 KB gzip target)
import { EUIXEngine } from 'euixjs';

// Mount core application (zero unused plugin bloat)
const engine = EUIXEngine.mount(xmlString, '#app');

When optional capabilities are needed, they are imported explicitly:

import { EUIXEngine } from 'euixjs';
import { EUIXApiPlugin } from 'euixjs/api';
import { EUIXRouterPlugin } from 'euixjs/router';

EUIXEngine.use(EUIXApiPlugin).use(EUIXRouterPlugin);

const engine = EUIXEngine.mount(xmlString, '#app');

6.2 Backward Compatibility Shim (euixjs/full) #

To avoid breaking existing codebases that expect all 20+ plugins to be pre-registered:

// BACKWARD COMPATIBLE: Full bundle for existing legacy apps
import { EUIXEngine } from 'euixjs/full';

In package.json:

{
  "exports": {
    ".": {
      "types": "./types/core.d.ts",
      "import": "./dist/EUIXEngineCore.es.js",
      "require": "./dist/EUIXEngineCore.umd.js"
    },
    "./core": {
      "types": "./types/core.d.ts",
      "import": "./dist/EUIXEngineCore.es.js",
      "require": "./dist/EUIXEngineCore.umd.js"
    },
    "./full": {
      "types": "./types/index.d.ts",
      "import": "./dist/EUIXEngineFull.es.js",
      "require": "./dist/EUIXEngineFull.umd.js"
    },
    "./api": "./dist/plugins/EUIXApiPlugin.es.js",
    "./router": "./dist/plugins/EUIXRouterPlugin.es.js",
    "./composer": "./dist/plugins/EUIXComposerPlugin.es.js",
    "./reactive": "./dist/plugins/EUIXReactivePlugin.es.js",
    "./storage": "./dist/plugins/EUIXStoragePlugin.es.js",
    "./animation": "./dist/plugins/EUIXAnimationPlugin.es.js",
    "./devtools": "./dist/EUIXDevTools.es.js"
  }
}

7. Documentation & Playground Diet #

7.1 Documentation Reorganization (Progressive Disclosure) #

A new developer should learn only 6 concepts to be fully productive:

1. Getting Started: Installation & Mounting (EUIXEngine.mount())
2. Templates & Expressions: XML markup, {data.variable}, interpolation
3. State: <data_model>, getState(), setState()
4. Logic: Conditional rendering (<if>), loops (<for_each>)
5. Events & Actions: on_click, bind, named JavaScript actions (engine.action())
6. Components: <component_def>, <slot>, props

All advanced, plugin, and ecosystem documentation will be cleanly separated:

docs/
├── 01-getting-started/   # 15-minute quickstart (6 core concepts only)
├── 02-core/              # Templates, State, Reactivity, Components, Actions
├── 03-plugins/           # Opt-in: Api, Router, Composer, Storage, Reactive
├── 04-integrations/      # Ecosystem: Leaflet, Charts, Date, WebMCP
├── 05-advanced/          # SSR, Compiler, DevTools, Performance
└── 06-reference/         # Complete API reference

7.2 Playground Simplification #

Currently, index.html loads 15+ sections including GIS maps, live cryptocurrency portfolio, SVG charts, and a 106 KB documentation portal.

Target Playground: Reduce the primary playground to 4 crystal-clear demonstrations:

1. Counter: Basic state, expressions, and event handling.
2. Todo List: Arrays, keyed <for_each>, conditional rendering, and form input bindings.
3. User Directory (API): Demonstrates euixjs/api with fetch, loading, and error states.
4. Mini-App (Interactive Component): Demonstrates components, slots, and named JS actions.

Move complex examples (Crypto Portfolio, GIS Maps, WebMCP, Gantt Chart) to examples/ and demos/.

8. Target Architecture & Project Structure #

xui/
├── src/
│   ├── core/                        # Lightweight Core Runtime (<= ~20 KB gzip target)
│   │   ├── EUIXEngineCore.js        # Engine class, mount/unmount, plugin system
│   │   ├── state/                   # Reactive state store, microtask batching, dirty bitmask
│   │   ├── parser/                  # Fast AST parser & JIT expression evaluator
│   │   ├── renderer/                # DOM renderer, keyed reconciliation, slots
│   │   ├── components/              # Component definition, props, template unwrapping
│   │   ├── actions/                 # Core action dispatcher (SET, CALL, TOGGLE, RUN_SCRIPT)
│   │   ├── binding/                 # Input bindings (bind, bind.number, bind.boolean)
│   │   └── utils/                   # Shared DOM helpers and constants (zero external deps)
│   │
│   ├── plugins/                     # Official Opt-in Plugins
│   │   ├── api/                     # SWR API client & offline mutation queue
│   │   ├── router/                  # Lightweight client-side router
│   │   ├── composer/                # Multi-step action workflows (<action_def>)
│   │   ├── resilience/              # Circuit breakers, retries, timeouts
│   │   ├── reactive/                # Dependency graph & <computed> tags
│   │   ├── storage/                 # Persistence (localStorage/sessionStorage)
│   │   ├── animation/               # Web Animations & transition orchestration
│   │   ├── virtual/                 # Virtual list scrolling
│   │   ├── validation/              # Form schema validation
│   │   ├── stream/                  # WebSocket / SSE client
│   │   ├── dnd/                     # Drag and drop pointer events
│   │   └── head/                    # Document head/meta manager
│   │
│   ├── integrations/                # Ecosystem Integrations
│   │   ├── leaflet/                 # Interactive GIS mapping
│   │   ├── chart/                   # SVG data visualization
│   │   ├── date/                    # Intl date/time formatting & presets
│   │   └── webmcp/                  # AI WebMCP agent tooling
│   │
│   ├── devtools/                    # Developer Tools & Inspector HUD
│   │   ├── EUIXDevTools.js
│   │   └── inspector/
│   │
│   ├── compiler/                    # Ahead-of-Time AST Compiler & Typegen
│   └── server/                      # Zero-JSDOM Server-Side Renderer (SSR)

9. Execution Plan & Milestones #

10. Success Criteria Checklist #

• One-Sentence Identity: "EUIX is a lightweight declarative reactive UI runtime."
• Core Mental Model: New developers need to understand only 6 concepts to build applications.
• Pay-For-What-You-Use: Basic apps import only the core runtime (euixjs). Unused features cost 0 KB.
• Clean Dependency Direction: Core has zero imports or hardcoded knowledge of plugins or integrations.
• JavaScript Escape Hatch: Developers can drop down to native JavaScript (engine.action()) rather than programming in XML.
• Bundle Size Target: Core bundle target <= ~20 KB gzip (down from 69.5 KB / 148 KB).
• No Unnecessary Breakage: Compatibility shims provided for legacy apps via euixjs/full.
• 100% Test Passing: All 790 existing automated tests remain green throughout each milestone.