@virid/core 0.0.1

package/README.md

@@ -0,0 +1,259 @@
+# 🛰️ @virid/core
+
+
+
+> **A Lightweight, Message-Driven Logic Engine inspired by Rust's ECS Architecture and Nestjs.**
+
+[中文说明](README.zh.md)
+
+## ✨ Features
+
+
+
+### 🧩 What is CCS Architecture?
+
+`virid` is built on the **CCS (Component-Controller-System)** architecture. Based on the traditional ECS (Entity-Component-System) pattern, it introduces a "Controller" layer specifically for Web/UI environments to bridge logic and views seamlessly.
+
+#### 1. 💾 Component (Data) — "The Container of Truth"
+
+- **Definition**: Pure data structures containing zero business logic.
+- **Responsibility**: Stores state (e.g., `PlaylistComponent` storing song lists and playback status). In `virid`, Components are managed as **Singletons** within the IoC container.
+
+#### 2. 🎮 Controller (The Bridge) — "The Anchor of Views"
+
+- **Definition**: A proxy layer between the UI framework (Vue) and the core logic (Core).
+- **Responsibility**:
+  - **Projection**: Safely maps data from `Components` to Vue using `@Project`.
+  - **Command**: Captures UI events (like clicks) and transforms them into `Messages` to be dispatched to the engine.
+  - **Context Awareness**: Perceives UI hierarchy and metadata (like list indices) via `@Env`.
+
+#### 3. ⚙️ System (Logic) — "The Arbiter of Causality"
+
+- **Definition**: A collection of stateless static methods and the **only** legitimate place for state transitions.
+- **Responsibility**: Listens for `Messages` and modifies `Component` data accordingly. Systems are **deterministic**, ensuring that the same input always yields the same state transition.
+
+### 🛠️ Decoupling of Logic Sovereignty
+
+### 1. Total UI Demotion: Framework-Agnostic Core
+
+- **Transfer of Sovereignty**: The UI framework is stripped of its authority over state management and business scheduling, relegated to a pure **"State Projection Layer."** All business causality and state machine transitions are executed within the closed loop of `virid Core`.
+- **Physical Isolation**: The Core layer has zero dependencies on `DOM/BOM` APIs. Your core logic runs seamlessly in **Node.js servers, Web Workers, or even Command Line Interface (CLI) tools**.
+- **Seamless Migration**: Logical assets are no longer tethered to a specific UI library. Switch the adapter layer, and you are ready for **Vue, React, or beyond**.
+
+### 2. Production-Grade Testability
+
+- **Farewell to Mocking Hell**: Say goodbye to JSDOM and complex browser simulations. Since the core logic is pure JS/TS, you can boot the Core directly in Node.js and complete unit tests for complex business flows via a **"Send Message -> Assert State"** pattern.
+- **Logic Playback**: As all side effects are triggered by messages, business logic becomes a **pure pipeline**, enabling offline refactoring and automated regression of production logic paths.
+
+### 3. Powerful Inversion of Control (IoC)
+
+- **Deep IoC Architecture**: Built on **InversifyJS** for robust Dependency Injection. `Systems`, `Components`, and `Controllers` are auto-assembled via the container.
+- **Dynamic Lifecycle**: Supports on-demand loading and auto-injection of logic modules. Whether it’s a global singleton `System` or a `Controller` that dies with a component, the container manages the entire lifecycle.
+
+---
+
+## 🏎️ Game-Grade Scheduling Engine
+
+- **Deterministic Tick Mechanism**: Introduces a Bevy-inspired message loop where all logical changes advance within discrete "Ticks."
+- **Double-Buffered Message Pool**: Physically isolates "processing" and "incoming" messages, effectively eliminating infinite loops and logical jitter.
+- **Physically Isolated Message Strategies**:
+  - **SingleMessage (Signal)**: Automatically merges identical signals, triggering a single batch process within the same Tick.
+  - **EventMessage (Event)**: Guarantees strict sequential execution, ensuring the atomicity of logical chains.
+
+---
+
+## 🛡️ State Security & Access Control
+
+- **Read-Only Data Shield**: Controllers receive read-only proxies by default, strictly prohibiting illegal tampering with `Component` states outside of a `System`.
+- **Atomic Modification Protocol**: Data changes are forced through specific `AtomicModifyMessage` protocols, ensuring every state transition is traceable and auditable.
+
+---
+
+## 🧬 Declarative Meta-Programming
+
+- **Decorator-Driven**: Use `@System`, `@Message`, `@Inherit`, and `@Project` to declaratively describe complex dependency networks and reactive logic flows.
+- **Automated Data Routing**: Dispatching a message immediately triggers the response; parameters are injected automatically, eliminating the need to write tedious boilerplate for listeners and dispatchers.
+
+## 📖 Quick Start
+
+⚠️ Important: You MUST import reflect-metadata at the very first line of your entry file (e.g., main.ts), otherwise decorators will not function correctly.
+
+Build a strictly protected state machine in a pure JS environment in just three steps.
+
+### 1. Define Components & Messages
+
+**Components** are pure data structures; **Messages** are the sole driving contracts.
+
+```ts
+import {
+  createvirid,
+  Component,
+  System,
+  Message,
+  SingleMessage,
+  AtomicModifyMessage,
+} from "@virid/core";
+
+// Initialize the core engine
+const app = createVirid();
+
+// Define Data Entity (Component)
+@Component()
+class CounterComponent {
+  public count = 0;
+}
+// Register component
+app.bindComponent(CounterComponent);
+
+// Define operation instructions (Message)
+class IncrementMessage extends SingleMessage {
+  constructor(public amount: number) {
+    super();
+  }
+}
+```
+
+### 2. Implement Systems
+
+**Systems** are stateless static methods. They retrieve components via Dependency Injection (DI) to handle business logic. You don't need to manually instantiate or invoke them—virid will automatically discover and execute them through static analysis.
+
+```ts
+//Define System
+class CounterSystem {
+  @System()
+  static onIncrement(
+    @Message(IncrementMessage) message: IncrementMessage,
+    count: CounterComponent,
+  ) {
+    console.log("---------------------System----------------------");
+    console.log("message :>> ", message);
+    count.count += message.amount;
+  }
+}
+```
+
+### 3. Headless Execution
+
+No browser required. Drive your business logic directly in **Node.js** or any testing framework.
+
+```ts
+// Business logic automatically completes scheduling in the next microtask
+queueMicrotask(() => {
+  IncrementMessage.send(1);
+  IncrementMessage.send(5);
+  queueMicrotask(() => {
+    AtomicModifyMessage.send(
+      CounterComponent,
+      (comp) => {
+        console.log("----------------AtomicModifyMessage------------------");
+        console.log("CounterComponent :>> ", comp);
+      },
+      "Check CounterComponent",
+    );
+  });
+});
+```
+
+## 🛠️ Advanced Engineering Practices
+
+### ⚓ Lifecycle Interception (Middleware & AOP Hooks)
+
+virid provides deep access to the message pipeline, allowing you to easily extend the system with features like **Undo/Redo, State Synchronization, or Automated Logging**.
+
+- **Middleware**: Pre-process messages before they enter the `EventHub`.
+
+  TypeScript
+
+  ```
+  app.useMiddleware((message, next) => {
+    console.log(`[Log]: Intercepted message ${message.constructor.name}`);
+    next(); // Continue the pipeline
+  });
+  ```
+
+- **AOP Hooks**: Perform aspect-oriented processing before or after specific message execution.
+  - `onBeforeExecute`: Triggered before System logic runs (e.g., for permission checks).
+  - `onAfterExecute`: Triggered after logic execution (e.g., for data persistence).
+
+  TypeScript
+
+  ```
+  app.onBeforeExecute(IncrementMessage, (message, context) => {
+    console.log("---------------- onBeforeExecute ------------------");
+    console.log("Message Details:", message);
+    console.log("Target System:", context.targetClass.name);
+    console.log("Method Context:", context.methodName);
+  });
+  ```
+
+---
+
+### ⚡ Atomic Modification: The "Snapshot" Privilege
+
+To balance **strict constraints** with **development efficiency**, virid allows direct state mutations via `AtomicModifyMessage` without the need to write a full `System`.
+
+- **Semantic Mutations**: Every atomic modification requires a mandatory `label`, transforming "arbitrary" assignments into auditable, meaningful actions.
+- **Consistency Guarantee**: Atomic modifications still follow the **Tick Scheduling** mechanism, ensuring that data changes are synchronized with System logic.
+
+---
+
+### 🚨 Everything is a Message: Robust Error Monitoring
+
+virid treats exceptions as first-class citizens of the system:
+
+- **Automatic Encapsulation**: Any synchronous or asynchronous exception within a `System` or `Hook` is automatically captured by the `Dispatcher` and encapsulated into an `ErrorMessage`.
+- **Defensive Programming**: You can define a dedicated `ErrorSystem` to handle these messages globally (e.g., reporting to Sentry or triggering UI alerts). This ensures the core engine remains resilient and never crashes due to a single component failure.
+
+---
+
+---
+
+## 🚀 Conclusion: Why virid?
+
+virid is not just another state management library; it is an endeavor to introduce **Deterministic Industrial Standards** to Web development.
+
+As your project scales from dozens to thousands of components, and your business logic evolves from simple CRUD into intricate cross-component choreographies, the virid architecture ensures that your codebase remains:
+
+- **Traceable**: Every logical transition has a clear trail via messages.
+- **Predictable**: Every state modification follows strict, predefined protocols.
+- **Decoupled**: Every business flow can be tested and validated entirely independent of the UI.
+
+### 🛰️ Data Flow Architecture
+
+```mermaid
+graph TD
+    %% 定义外部触发
+    User([External/Logic Call]) -->|Message.send| Writer[MessageWriter]
+
+    %% 核心引擎内部
+    subgraph Engine [Virid Core Engine]
+        direction TB
+        Writer -->|Middleware Pipeline| Hub[EventHub: Staging]
+
+        subgraph Dispatcher [Deterministic Dispatcher]
+            Hub -->|Tick / Buffer Flip| Active[EventHub: Active Pool]
+            Active -->|Sort by Priority| TaskQueue[Task Queue]
+
+            subgraph Executor [Execution Context]
+                TaskQueue -->|Identify| Sys[System Static Method]
+                Container[(Inversify Container)] -.->|Inject Component| Sys
+                Sys -->|Execute| Logic{Business Logic}
+            end
+        end
+
+        Logic -->|Update| Data[(Raw Component Data)]
+
+        %% 异常与反馈流
+        Logic -- "New Message" --> Writer
+        Logic -- "Error" --> ErrorHandler[Error Message System]
+    end
+
+    %% 状态输出
+    Data -->|Optional Projection| Output([External State Observation])
+
+    %% 样式
+    style Engine fill:#fff,stroke:#333,stroke-width:2px
+    style Dispatcher fill:#f5f5f5,stroke:#666,dashed
+    style Container fill:#e1f5fe,stroke:#01579b
+
+```

package/README.zh.md

@@ -0,0 +1,203 @@
+# 🛰️ @virid/core
+
+> **A Lightweight, Message-Driven Logic Engine inspired by Rust's ECS Architecture and Nestjs.** **受 Rust Bevy ECS 架构与Nestjs启发的轻量级消息驱动逻辑引擎。**
+
+## ✨ 特点
+
+### 🧩 什么是 CCS 架构？
+
+`virid` 采用 **CCS (Controller-Component-System)** 架构。它在传统 ECS 的基础上，为 Web/UI 环境引入了“控制器”层，实现了逻辑与视图的完美桥接。
+
+#### 1. 💾 Component (数据) —— “逻辑的容器”
+
+- **定义**：纯粹的数据结构，不包含任何业务逻辑。
+- **职责**：存储状态。在 `virid` 中，它是 IoC 容器管理的单例。
+
+#### 2. 🎮 Controller (控制器) —— “视图的锚点”
+
+- **定义**：UI 框架（Vue）与核心逻辑（Core）之间的代理。
+- **职责**：
+  - **投影 (Projection)**：将 Component 里的数据安全地映射给 Vue。
+  - **指令 (Command)**：接收用户的点击事件，并将其转化为 `Message` 发送给引擎。
+
+#### 3. ⚙️ System (系统) —— “因果的裁判”
+
+- **定义**：无状态的静态方法集合，是逻辑变更的唯一合法场所。
+- **职责**：监听 `Message`，根据指令修改 `Component` 中的数据。它是确定性的，确保同样的输入永远得到同样的输出。
+
+### 🛠️ 逻辑主权
+
+#### 1. 彻底的 UI 降级：框架无关核心
+
+- **主权移交**：UI 框架被剥夺了状态管理与业务调度的权限，退化为纯粹的 **“状态投影层”**。所有的业务因果律、状态机转换均在 `virid Core` 中闭环执行。
+- **物理隔离**：Core 层不依赖任何 `DOM/BOM` API。核心逻辑可以无缝运行在 **Node.js 服务端、Web Worker、甚至是命令行 (CLI) 工具**中。
+- **无缝迁移**：逻辑资产不再与特定 UI 框架绑定。只需更换一个适配层，就能适配 vue 或React 应用。
+
+#### 2. 生产级的可测试性
+
+- **告别模拟 (Mock) 地狱**：无需 JSDOM，无需模拟复杂的浏览器环境。由于核心逻辑是纯 JS/TS 驱动的，可以直接在 Node.js 中启动 Core，通过 **“发送消息 -> 断言状态”** 的方式，完成对复杂业务流的单元测试。
+- **逻辑回放**：所有副作用都通过消息触发，让业务逻辑变成**纯净的流水线**，支持对线上逻辑路径进行离线重构与自动化回归。
+
+#### 3. 强力控制反转
+
+- **深度 IoC 架构**：基于 **InversifyJS** 实现依赖注入。`System`、`Component` 与 `Controller` 之间通过容器自动装配。
+- **动态生命周期**：支持逻辑模块的按需加载与自动注入。无论是全局单例的 `System` 还是随组件销毁的 `Controller`，均由容器统一接管生命周期。
+
+### 🏎️ 游戏级调度引擎
+
+- **确定性 Tick 机制**: 引入类 Bevy 的消息循环，所有逻辑变更在 Tick 中推进。
+- **双缓冲消息池**: 物理隔离“正在处理”与“新产生”的消息，避死循环与逻辑抖动。
+- **物理隔离消息策略**:
+  - **SingleMessage (信号)**: 自动合并同类项，同 Tick 内仅触发一次批量处理。
+  - **EventMessage (事件)**: 严格保序执行，确保逻辑链条的原子性。
+
+### 🛡️ 状态安全与权限控制
+
+- **只读数据护盾**: Controller 层(@virid/vue中)默认获得只读代理，禁止在 System 之外非法篡改 Component 状态。
+- **原子修改协议**: 强制通过特定的 `AtomicModifyMessage` 变更数据，让每一次状态改变都有迹可循、可被审计。
+
+### 🧬 声明式元编程
+
+- **装饰器驱动**: 使用 `@System`, `@Message`, `@Inherit`, `@Project` 等装饰器，以声明式的方式描述复杂的依赖网络和逻辑响应流。
+- **自动数据路由**: 消息发送即触发，参数自动注入，无需手动编写复杂的监听与分发代码。
+
+## 📖 快速上手
+
+只需三步，即可在纯 JS 环境中构建一个受严格保护的状态机。
+
+#### 1. 定义组件与消息 (Component & Message)
+
+组件(Component)是纯粹的数据结构，消息是唯一的驱动契约。
+
+```ts
+import {
+  createvirid,
+  Component,
+  System,
+  Message,
+  SingleMessage,
+  AtomicModifyMessage,
+} from "@virid/core";
+
+// Initialize the core engine
+const app = createvirid();
+
+// Define Data Entity (Component)
+@Component()
+class CounterComponent {
+  public count = 0;
+}
+// Register component
+app.bindComponent(CounterComponent);
+
+// Define operation instructions (Message)
+class IncrementMessage extends SingleMessage {
+  constructor(public amount: number) {
+    super();
+  }
+}
+```
+
+#### 2. 编写系统 (System)
+
+系统是无状态的静态方法，通过依赖注入获取组件并处理业务逻辑。**你无需任何操作，他们是纯static的，virid会自动找到他们并正确地调用他们。**
+
+```ts
+//Define System
+class CounterSystem {
+  @System()
+  static onIncrement(
+    @Message(IncrementMessage) message: IncrementMessage,
+    count: CounterComponent,
+  ) {
+    console.log("---------------------System----------------------");
+    console.log("message :>> ", message);
+    count.count += message.amount;
+  }
+}
+```
+
+#### 3. 纯环境运行 (Headless Execution)
+
+无需浏览器，直接在 Node.js 或测试框架中驱动你的业务。
+
+```ts
+// Business logic automatically completes scheduling in the next microtask
+queueMicrotask(() => {
+  IncrementMessage.send(1);
+  IncrementMessage.send(5);
+  queueMicrotask(() => {
+    AtomicModifyMessage.send(
+      CounterComponent,
+      (comp) => {
+        console.log("----------------AtomicModifyMessage------------------");
+        console.log("CounterComponent :>> ", comp);
+      },
+      "Check CounterComponent",
+    );
+  });
+});
+```
+
+## 🛠️ 高级工程实践 (Advanced Engineering)
+
+### ⚓ 全生命周期拦截 (Lifecycle Hooks & Middleware)
+
+virid 提供了深度介入消息管道的能力，你可以轻易地将其扩展为支持 **Undo/Redo**、**状态同步** 或 **自动日志** 的系统。
+
+- **Middleware**: 在消息进入 EventHub 之前进行预处理。
+
+  TypeScript
+
+  ```ts
+  app.useMiddleware((message, next) => {
+    console.log(`Identified message ${message.constructor.name}`);
+    next(); // 继续流转
+  });
+  ```
+
+- **AOP Hooks**: 针对特定消息的执行前后进行切面处理。
+  - `onBeforeExecute`: 在 System 逻辑运行前触发（如权限检查）。
+  - `onAfterExecute`: 在逻辑运行后触发（如数据持久化）。
+
+  ```ts
+  app.onBeforeExecute(IncrementMessage, (message, context) => {
+    console.log("----------------onBeforeExecute------------------");
+    console.log("message :>> ", message);
+    console.log("targetClass :>> ", context.targetClass);
+    console.log("methodName :>> ", context.methodName);
+    console.log("params :>> ", context.params);
+  });
+  ```
+
+### ⚡ 原子修改：“快照”特权 (Atomic Modification)
+
+为了兼顾“严苛约束”与“开发效率”，virid 允许通过 `AtomicModifyMessage` 直接描述状态变更，而无需编写完整的 System。
+
+- **语义化变更**：每一条原子修改都强制要求一个 `label`，让原本“随意的”赋值操作变得可被审计。
+- **一致性保证**：原子修改依然遵循 Tick 调度，确保数据变更与 System 逻辑同步生效。
+
+### 🚨 万物皆消息：健壮的异常监控 (Error as Message)
+
+virid 将异常视为系统的一等公民：
+
+- **自动封装**：任何 System 或 Hook 中的同步/异步异常，都会被 Dispatcher 自动捕获并封装为 `ErrorMessage`。
+- **防御式编程**：你可以定义一个 `ErrorSystem` 统一处理这些消息（如发送 Sentry 日志或触发 UI 告警），确保核心逻辑引擎永远不会因为单一组件的崩溃而宕机。
+
+---
+
+## 🚀 结语：为什么是 virid？
+
+virid 不是在重复造一个状态库，它是在为 Web 开发引入一套**具备强确定性的工业标准**。
+
+当你的项目从几十个组件增长到几千个，当你的业务逻辑从简单的 CRUD 变成复杂的跨组件联动时，virid 的架构将确保你的代码依然：**逻辑可寻迹、修改可预期、测试可脱离 UI。**
+
+```
+数据流转示意图
+User -->|Dispatch| Writer[MessageWriter]
+Writer -->|Middleware| Hub[EventHub: Staging]
+Hub -->|Tick/Flip| Active[EventHub: Active]
+Active -->|Execute| System[System/Hook]
+System -->|Update| Component[Raw Component Data]
+Component -->|Reactive| UI[Vue/React View]
+```

package/dist/index.d.mts

@@ -0,0 +1,218 @@
+import { Newable, Container, BindInWhenOnFluentSyntax, BindWhenOnFluentSyntax } from 'inversify';
+
+type AnyConstructor = abstract new (...args: any[]) => any;
+declare abstract class BaseMessage {
+    static send<T extends AnyConstructor>(this: T, ...args: ConstructorParameters<T>): void;
+    senderInfo?: {
+        fileName: string;
+        line: number;
+        timestamp: number;
+    };
+    constructor();
+}
+/**
+ * 可合并的信号基类
+ */
+declare abstract class SingleMessage extends BaseMessage {
+    private readonly __kind;
+    constructor();
+}
+/**
+ * 不可合并的消息基类
+ */
+declare abstract class EventMessage extends BaseMessage {
+    private readonly __kind;
+    constructor();
+}
+/**
+ * 基础错误消息：不可合并，必须被精准捕获
+ */
+declare class ErrorMessage extends EventMessage {
+    readonly error: Error;
+    readonly context?: string;
+    constructor(error: Error, context?: string);
+}
+/**
+ * 基础警告消息：不可合并，必须被精准捕获
+ */
+declare class WarnMessage extends EventMessage {
+    readonly context: string;
+    constructor(context: string);
+}
+/**
+ * 原子修改消息：不可合并，带上组件类型、修改逻辑和语义标签
+ */
+declare class AtomicModifyMessage<T> extends EventMessage {
+    readonly ComponentClass: Newable<T>;
+    readonly recipe: (comp: T) => void;
+    readonly label: string;
+    constructor(ComponentClass: Newable<T>, // 你要改哪个组件？
+    recipe: (comp: T) => void, // 你打算怎么改？
+    label: string);
+}
+type Middleware = (message: BaseMessage, next: () => void) => void;
+type Hook<T extends BaseMessage> = (message: [BaseMessage] extends [T] ? SingleMessage[] | EventMessage : T extends SingleMessage ? T[] : T, context: CCSSystemContext) => void | Promise<void>;
+type MessageIdentifier<T> = (abstract new (...args: any[]) => T) | (new (...args: any[]) => T);
+interface CCSSystemContext {
+    params: any[];
+    targetClass: any;
+    methodName: string;
+    originalMethod: (...args: any[]) => any;
+}
+interface SystemTask {
+    fn: (...args: any[]) => any;
+    priority: number;
+}
+/**
+ * 核心逻辑：根据 T 的类型决定 Hook 接收的是数组还是单体
+ */
+type MessagePayload<T> = T extends SingleMessage ? T[] : T extends EventMessage ? T : T | T[];
+
+/**
+ * @description:  事件中心，存储和分发消息 - 物理隔离 SIGNAL 与 EVENT
+ */
+declare class EventHub {
+    private signalActive;
+    private signalStaging;
+    private eventActive;
+    private eventStaging;
+    /**
+     * 写入逻辑：根据消息策略分流
+     */
+    push(event: any): void;
+    /**
+     * 翻转缓冲区：在 Dispatcher 的 Tick 开始时调用
+     */
+    flip(): void;
+    /**
+     * [SIGNAL专用] 批量读取某种类型的信号
+     */
+    peekSignal<T>(type: new (...args: any[]) => T): T[];
+    /**
+     * [EVENT专用] 获取当前所有待处理的事件流
+     */
+    getEventStream(): any[];
+    /**
+     * [新增] 根据索引精准读取 EVENT 里的某个数据
+     * 配合 Dispatcher 逐条分发时使用
+     */
+    peekEventAt(index: number): any;
+    /**
+     * 清理已处理的内容
+     */
+    clearSignals(types: Set<any>): void;
+    clearEvents(): void;
+    /**
+     * 重置所有池子
+     */
+    reset(): void;
+}
+
+declare class Dispatcher {
+    private dirtySignalTypes;
+    private eventQueue;
+    private isRunning;
+    private tickCount;
+    private eventHub;
+    private beforeHooks;
+    private afterHooks;
+    constructor(eventHub: EventHub);
+    addBefore<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
+    addAfter<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
+    private cleanupHook;
+    setCleanupHook(hook: (types: Set<any>) => void): void;
+    /**
+     * 标记脏数据：根据基类判断进入哪个池子
+     */
+    markDirty(message: any): void;
+    tick(interestMap: Map<any, SystemTask[]>): void;
+}
+
+/**
+ * @description: 消息注册器 - 负责将系统函数或监听器与消息类型关联
+ */
+declare class MessageRegistry {
+    interestMap: Map<any, SystemTask[]>;
+    /**
+     * 注册消息并返回一个卸载函数
+     * 这种模式能完美适配 Controller 的生命周期销毁
+     */
+    register(eventClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
+}
+
+declare class MessageInternal {
+    readonly eventHub: EventHub;
+    readonly dispatcher: Dispatcher;
+    readonly registry: MessageRegistry;
+    readonly middlewares: Middleware[];
+    constructor();
+    useMiddleware(mw: Middleware): void;
+    onBeforeExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
+    onAfterExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
+    /**
+     * 消息进入系统的唯一入口
+     */
+    dispatch(message: BaseMessage): void;
+    private pipeline;
+}
+
+interface IMessagePublisher {
+    dispatch(message: BaseMessage): void;
+}
+declare function activatInstance(instance: MessageInternal): void;
+declare const publisher: IMessagePublisher;
+declare class MessageWriter {
+    /**
+     * 核心入口：无论是类还是实例，统一交给 Internal 处理
+     */
+    static write<T extends BaseMessage, K extends new (...args: any[]) => T>(target: K | T, ...args: ConstructorParameters<K>): void;
+    /**
+     * 快捷方式：系统内部常用
+     */
+    static error(e: Error, context?: string): void;
+    static warn(context: string): void;
+}
+
+/**
+ * @description: 系统装饰器
+ * @param priority 优先级，数值越大越早执行
+ */
+declare function System(priority?: number): (target: any, key: string, descriptor: PropertyDescriptor) => void;
+/**
+ * @description: 标记参数为 MessageReader 并锁定其消息类型
+ */
+declare function Message<T extends BaseMessage>(eventClass: new (...args: any[]) => T, single?: boolean): (target: any, key: string, index: number) => void;
+/**
+ * @description: 标记Controller身份
+ */
+declare function Controller(): (target: any) => void;
+/**
+ * @description: 标记Component身份
+ */
+declare function Component(): (target: any) => void;
+
+interface ViridPlugin {
+    name: string;
+    install: (app: ViridApp, options?: any) => void;
+}
+
+/**
+ * 创建 virid 核心实例
+ */
+declare class ViridApp {
+    container: Container;
+    private messageInternal;
+    private bindBase;
+    get(identifier: any): unknown;
+    bindController<T>(identifier: new (...args: any[]) => T): BindInWhenOnFluentSyntax<T>;
+    bindComponent<T>(identifier: new (...args: any[]) => T): BindWhenOnFluentSyntax<T>;
+    useMiddleware(mw: Middleware): void;
+    onBeforeExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
+    onAfterExecute<T extends BaseMessage>(type: MessageIdentifier<T>, hook: Hook<T>): void;
+    register(eventClass: any, systemFn: (...args: any[]) => any, priority?: number): () => void;
+    use(plugin: ViridPlugin, options: any): this;
+}
+
+declare function createVirid(): ViridApp;
+
+export { AtomicModifyMessage, BaseMessage, type CCSSystemContext, Component, Controller, ErrorMessage, EventMessage, type Hook, type IMessagePublisher, Message, type MessageIdentifier, MessageInternal, type MessagePayload, MessageWriter, type Middleware, SingleMessage, System, type SystemTask, ViridApp, type ViridPlugin, WarnMessage, activatInstance, createVirid, publisher };