@path-ioc/unplugin 0.1.3 → 0.1.4

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1>@path-ioc/unplugin</h1>
-  <p><b>Universal Dev Plugin for Path-IoC (Virtual Container & Type Generator)</b></p>
-  <p>Cross-bundler virtual module injector & automated TypeScript type generator for Vite, Rolldown, Webpack 5, Rspack, Rollup, and Esbuild</p>
+  <p><b>Compiler-Runtime Co-design Plugin for Path-IoC (Virtual Container & Type Synthesis)</b></p>
+  <p>Cross-bundler virtual module injector & microsecond TypeScript type generator for Vite, Rolldown, Webpack 5, Rspack, Rollup, and Esbuild</p>
 
   <p>
     <a href="https://www.npmjs.com/package/@path-ioc/unplugin"><img src="https://img.shields.io/npm/v/@path-ioc/unplugin.svg" alt="NPM version"></a>
@@ -18,57 +18,82 @@
   </p>
 </div>
 
-> 💡 **Architectural Positioning**: `@path-ioc/unplugin` is the companion build-time engine for [`@path-ioc/core`](../core). In production projects, both work as one: `unplugin` scans physical module directories at build time and synthesizes real-time `.d.ts` definitions, while `core` executes lock-free DAG topological scheduling at runtime.  
-> **For the full architecture manifesto, design principles, and end-to-end guide:**  
-> 📖 **[Read the @path-ioc/core Guide](../core/README.md)** or visit **[https://path-ioc.dev](https://path-ioc.dev)**.
+> 💡 **Architectural Positioning: Compiler-Runtime Co-design**  
+> `@path-ioc/unplugin` is not a mere convenience helper; it is the compiler-side twin intimately coupled with [`@path-ioc/core`](../core/README.md), forming the bedrock of Path-IoC's **Compiler-Runtime Co-design** philosophy.  
+> In modern TypeScript development, relying on runtime reflection (`reflect-metadata`) causes bundling failures, cold-start latency, and lack of true static type awareness. `@path-ioc/unplugin` shifts module scanning, DAG topological caching, and type synthesis to the build phase, enabling sub-millisecond hot-reloading and **21.2 µs** per-request container ignition for the [`@path-ioc/core`](../core/README.md) runtime.  
+> 📖 **For module authoring specifications, pure function factories, and end-to-end guides, see: [`@path-ioc/core` Official Guide](../core/README.md)** or visit the official documentation at **[https://path-ioc.dev/](https://path-ioc.dev/)**.
 
 ---
 
-## Key Responsibilities
+## Live Demo & Instant Ignition (Live Demo Video)
 
-- **Universal Bundler Support**:
-  Built on the `unplugin` standard to natively support **Vite**, **Rolldown (Rust)**, **Webpack 5**, **Rspack**, **Rollup**, and **Esbuild** with a unified configuration API.
-- **`virtual:modular-container` Streaming Module Injection**:
-  Automatically scans `src/modules/**/index.{ts,tsx}` during development/build to generate the complete module registry. Injected purely in-memory for Vite/Rolldown/Rollup, and dynamically bridged for Webpack/Rspack.
-- **Zero-Config TypeScript Type Synthesis**:
-  Generates `ignore.modular.d.ts` in milliseconds during dev mode and HMR, augmenting the global `ModularContainer` interface with 100% accurate IDE auto-completion.
-- **Automatic `.gitignore` Self-Healing**:
-  Appends `ignore.*` rules to your project's `.gitignore` automatically to prevent ephemeral declaration files from polluting version control.
+<div align="center">
+  <video src="https://cdn.path-ioc.dev/path-ioc/demo-en.mp4" controls width="100%" playsinline>
+    Your browser does not support the video tag. <a href="https://cdn.path-ioc.dev/path-ioc/demo-en.mp4">Watch Live Demo Video</a>
+  </video>
+  <p>⚡ <b><a href="https://cdn.path-ioc.dev/path-ioc/demo-en.mp4">Watch Live Architecture Tour: Real-time Coding, Topological Orchestration & Instant Ignition</a></b></p>
+</div>
+
+---
+
+## Key Pillars of Compiler-Runtime Co-design
+
+### 1. Single-Graph Compile Cache Closure (`compiledGraph`)
+Inside the generated `virtual:modular-container`, `@path-ioc/unplugin` maintains a module-level closure that holds the pre-compiled `compiledGraph`:
+- **One-Time Cold Boot**: The entire application's dependency DAG is parsed, validated, and sorted once at process startup (500 nodes compile in just **1.72 ms**);
+- **Ultra-Fast Request Ignition**: Every invocation of `createModularContainer()` reuses the cached immutable graph, hydrating an isolated container in just **21.2 microseconds (µs)**;
+- **Zero Runtime DAG Recomputation**: In high-concurrency environments (Cloudflare Workers, Hono, Node.js), incoming HTTP requests suffer zero latency penalty from graph reconstruction.
+
+### 2. Microsecond AST Real-Time Type Synthesis (`0.04 ms`)
+During development and Hot Module Replacement (HMR), the plugin's background AST scanner detects file changes and generates `types/ignore.modular.d.ts` in **0.04 milliseconds**:
+- Augments the global `ModularContainer` interface with zero manual boilerplate;
+- Developers write `const { db, logger } = container;` and instantly enjoy 100% accurate IDE auto-completion and type checking;
+- Safely manages ephemeral declaration files with automatic `.gitignore` self-healing.
+
+### 3. Clear Host Ignition Boundary
+Traditional frameworks force business code to adapt to proprietary application classes and controller decorators. With `@path-ioc/unplugin`, the host only ignites the container:
+```typescript
+import { createModularContainer } from "virtual:modular-container";
+
+// One-line host ignition (Hono, Express, Koa, Workers, Next.js API, CLI)
+const container = await createModularContainer();
+```
+Business modules circulate 100% autonomously within the mesh, completely decoupled from the host environment.
 
 ---
 
-## Installation
+## Universal Bundler Integration
+
+### 1. Installation
 
 ```bash
 pnpm add -D @path-ioc/unplugin
 pnpm add @path-ioc/core
 ```
 
----
-
-## Bundler Quick Reference
+### 2. Bundler Configuration Quick Reference
 
-### 1. Vite (`vite.config.ts`)
+#### Vite (`vite.config.ts`)
 ```typescript
 import { defineConfig } from "vite";
 import { vitePlugin as pathIoc } from "@path-ioc/unplugin";
 
 export default defineConfig({
-  plugins: [pathIoc({ modulesPath: "src/modules", typeFileOutput: "types" })],
+  plugins: [pathIoc()],
 });
 ```
 
-### 2. Rolldown (`rolldown.config.ts`)
+#### Rolldown (`rolldown.config.ts`)
 ```typescript
 import { defineConfig } from "rolldown";
 import { rolldownPlugin as pathIoc } from "@path-ioc/unplugin";
 
 export default defineConfig({
-  plugins: [pathIoc({ modulesPath: "src/modules", typeFileOutput: "types" })],
+  plugins: [pathIoc()],
 });
 ```
 
-### 3. Rspack (`rspack.config.js`)
+#### Rspack (`rspack.config.js`)
 ```javascript
 const { rspackPlugin: pathIoc } = require("@path-ioc/unplugin");
 
@@ -77,26 +102,35 @@ module.exports = {
 };
 ```
 
-### 4. Webpack 5 (`webpack.config.js`)
+#### Webpack 5 (`webpack.config.js`)
 ```javascript
 const { webpackPlugin: pathIoc } = require("@path-ioc/unplugin");
 
 module.exports = {
-  plugins: [pathIoc({ modulesPath: "src/modules" })],
+  plugins: [pathIoc()],
 };
 ```
 
-### 5. Rollup (`rollup.config.js`) / Esbuild
+#### Rollup (`rollup.config.js`) & Esbuild
 ```javascript
 // Rollup
 import { rollupPlugin as pathIoc } from "@path-ioc/unplugin";
+
 // Esbuild
 import { esbuildPlugin as pathIoc } from "@path-ioc/unplugin";
 ```
 
+> **Zero-Configuration by Default**: All bundler plugins fully support zero-argument `pathIoc()` invocation. If your project uses custom directories, override them as needed:
+> ```typescript
+> pathIoc({
+>   modulesPath: "src/modules",   // Custom module root directory (default: "src/modules")
+>   typeFileOutput: "types",     // Custom type declaration output directory (default: "types")
+> })
+> ```
+
 ---
 
-## Plugin Options
+## Plugin Options (`PathIocPluginOptions`)
 
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
@@ -105,10 +139,49 @@ import { esbuildPlugin as pathIoc } from "@path-ioc/unplugin";
 
 ---
 
-## Production Usage & Module Writing
+## Virtual Module (`virtual:modular-container`)
+
+The plugin injects `virtual:modular-container` into your application at build time:
+
+```typescript
+import {
+  modules,                 // Complete module descriptor array: { key: string, module: IOCModule }[]
+  createModularContainer,  // High-performance container bootstrapper: (targetContainer?: Record<string, any>) => Promise<ModularContainer>
+} from "virtual:modular-container";
+```
+
+### Serverless / Hono Production Example (Request Isolation)
+
+```typescript
+import { Hono } from "hono";
+import { createModularContainer } from "virtual:modular-container";
+import { memoizeModule } from "@path-ioc/core";
+
+const app = new Hono<{ Bindings: { DB_URL: string } }>();
+
+app.use("*", async (c, next) => {
+  // 1. Instant container ignition: single-graph cache (only 21.2µs)
+  const container = await createModularContainer();
+
+  // 2. Safe infrastructure singleton memoization
+  memoizeModule(container, "dbPool", () => createPostgresPool(c.env.DB_URL));
+
+  // 3. Dynamic injection of per-request multi-tenant context
+  container.$inject("requestContext", {
+    requestId: c.req.header("x-request-id") || crypto.randomUUID(),
+  });
+
+  c.set("ioc", container);
+  await next();
+});
+```
+
+---
+
+## Module Authoring & Core Runtime Guide
 
-For practical guidance on creating modules with `main`, declaring dependencies, and igniting the container, please see:  
-👉 **[Read @path-ioc/core Documentation](../core/README.md)**
+`@path-ioc/unplugin` focuses on compile-time automated scanning, type synthesis, and single-graph cache injection. For authoring `main` pure-function closures, declaring Mesh dependencies, and leveraging IoC-DL and AOP aspects, please refer directly to:  
+👉 **[Read the `@path-ioc/core` Architectural & Practical Guide](../core/README.md)** or visit the official documentation at **[https://path-ioc.dev/](https://path-ioc.dev/)**.
 
 ---
 

package/README.zh-CN.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1>@path-ioc/unplugin</h1>
-  <p><b>Universal Dev Plugin for Path-IoC (Virtual Container & Type Generator)</b></p>
-  <p>跨构建工具（Vite / Rolldown / Webpack / Rspack / Rollup / Esbuild）的通用虚拟模块注入与 TypeScript 类型自动推导插件</p>
+  <p><b>Compiler-Runtime Co-design Plugin for Path-IoC (Virtual Container & Type Synthesis)</b></p>
+  <p>跨构建工具（Vite / Rolldown / Webpack / Rspack / Rollup / Esbuild）的通用虚拟模块注入与微秒级 TypeScript 类型自动推导插件</p>
 
   <p>
     <a href="https://www.npmjs.com/package/@path-ioc/unplugin"><img src="https://img.shields.io/npm/v/@path-ioc/unplugin.svg" alt="NPM version"></a>
@@ -18,57 +18,82 @@
   </p>
 </div>
 
-> 💡 **核心定位**：`@path-ioc/unplugin` 是 [`@path-ioc/core`](../core) 的编译期伴生驱动引擎。在真实生产工程中，两者密不可分：`unplugin` 负责在构建期自动扫描物理目录并实时生成 `.d.ts` 类型推导，`core` 负责在运行时进行极速无锁 DAG 拓扑装配。  
-> **完整的架构设计哲学、模块编写规范、依赖查找与端到端完整指南，请直接查阅：**  
-> 📖 **[`@path-ioc/core` 官方指南](../core/README.zh-CN.md)** 或访问官方主站 **[https://path-ioc.dev/zh/](https://path-ioc.dev/zh/)**。
+> 💡 **核心定位：编译器-运行时协同设计 (Compiler-Runtime Co-design)**  
+> `@path-ioc/unplugin` 绝非单纯的“自动化辅助小工具”，它是与 [`@path-ioc/core`](../core/README.zh-CN.md) 密不可分的编译期双子星，共同构成 Path-IoC **编译器-运行时协同设计 (Compiler-Runtime Co-design)** 的核心基石。  
+> 传统 TS IoC 方案将模块发现与元数据反射全部推迟到运行时执行，导致现代转译器类型擦除崩溃与边缘冷启动超时。`@path-ioc/unplugin` 将目录扫描、拓扑编译缓存与类型合成前置至编译期，为 [`@path-ioc/core`](../core/README.zh-CN.md) 运行时提供亚毫秒级热更新与每请求仅需 **21.2 µs** 的极致点火性能。  
+> 📖 **模块编写规范、纯函数工厂与端到端进阶指南，请直接参阅：[`@path-ioc/core` 官方指南](../core/README.zh-CN.md)** 或访问官方主站 **[https://path-ioc.dev/zh/](https://path-ioc.dev/zh/)**。
 
 ---
 
-## 核心职能 (Key Responsibilities)
+## 实机编码与极速点火演示录屏 (Live Demo Video)
 
-- **全构建器原生支持 (Universal Bundler Support)**：
-  基于 `unplugin` 规范，一套逻辑原生适配 **Vite**、**Rolldown (Rust)**、**Webpack 5**、**Rspack**、**Rollup** 与 **Esbuild**。
-- **`virtual:modular-container` 虚拟模块流式注入**：
-  构建期自动扫描 `src/modules/**/index.{ts,tsx}`，动态生成全量模块注册表。在 Vite/Rolldown/Rollup 环境下纯内存流式注入，在 Webpack/Rspack 下自动创建临时代理桥接。
-- **TypeScript 零配置类型合成**：
-  开发时与 HMR 热更新时毫秒级生成 `ignore.modular.d.ts`，自动扩充全局 `ModularContainer` 接口，解构享 100% 准确 IDE 提示。
-- **Git 规避自愈 (`.gitignore` 自动维护)**：
-  自动向项目 `.gitignore` 补充 `ignore.*` 规则，防止生成的临时声明污染版本控制。
+<div align="center">
+  <video src="https://cdn.path-ioc.dev/path-ioc/demo-zh.mp4" controls width="100%" playsinline>
+    您的浏览器不支持 HTML5 视频播放。<a href="https://cdn.path-ioc.dev/path-ioc/demo-zh.mp4">点击查看实机演示视频</a>
+  </video>
+  <p>⚡ <b><a href="https://cdn.path-ioc.dev/path-ioc/demo-zh.mp4">点击查看实机架构漫游：实时编码、拓扑依赖编排与极速容器点火</a></b></p>
+</div>
+
+---
+
+## 编译器-运行时协同三大支柱
+
+### 1. 单图编译缓存闭包 (`compiledGraph`)
+在插件自动生成的 `virtual:modular-container` 内部，维护了模块级闭包变量 `compiledGraph`：
+- **进程冷启动仅编译一次**：应用的依赖 DAG 图在进程冷启动时仅进行一次静态拓扑分析与环路深搜（500 节点仅需 **1.72 ms**）；
+- **请求级极致微秒点火**：后续所有 `createModularContainer()` 调用均直接复用该闭包静态图，实例化隔离容器仅耗时 **21.2 微秒 (µs)**；
+- **消除运行时重复构建开销**：在高并发场景（如 Cloudflare Workers、Node.js 服务端），彻底杜绝重复解析依赖树的 CPU 浪费。
+
+### 2. 零负担微秒级 AST 实时类型推导 (`0.04 ms`)
+开发态与 HMR 热更新期间，插件的 AST 监听器在开发者每次保存代码瞬间触发，耗时仅 **0.04 毫秒** 即可生成 `types/ignore.modular.d.ts`：
+- 无缝扩充全局 `ModularContainer` 接口，解构享受 100% 准确的 IDE 提示；
+- 开发者直接书写 `const { db, logger } = container;`，无需手动声明任何类型胶水代码；
+- 自动写入 `.gitignore` 自愈规则，避免临时声明污染版本控制。
+
+### 3. 清晰的宿主点火边界 (Host Ignition Boundary)
+传统框架用专有语法侵入应用入口，造成强框架绑定。而在 Path-IoC 中，宿主仅负责一行点火：
+```typescript
+import { createModularContainer } from "virtual:modular-container";
+
+// 宿主一行点火 (无论 Hono、Express、Koa、Workers、Next.js API 还是 CLI)
+const container = await createModularContainer();
+```
+业务模块在网格（Mesh）内部自闭环运转，不挑宿主，实现真正的架构解耦。
 
 ---
 
-## 安装 (Installation)
+## 全构建器原生支持
+
+### 1. 安装
 
 ```bash
 pnpm add -D @path-ioc/unplugin
 pnpm add @path-ioc/core
 ```
 
----
-
-## 构建工具集成速查 (Bundler Quick Reference)
+### 2. 构建工具配置速查
 
-### 1. Vite (`vite.config.ts`)
+#### Vite (`vite.config.ts`)
 ```typescript
 import { defineConfig } from "vite";
 import { vitePlugin as pathIoc } from "@path-ioc/unplugin";
 
 export default defineConfig({
-  plugins: [pathIoc({ modulesPath: "src/modules", typeFileOutput: "types" })],
+  plugins: [pathIoc()],
 });
 ```
 
-### 2. Rolldown (`rolldown.config.ts`)
+#### Rolldown (`rolldown.config.ts`)
 ```typescript
 import { defineConfig } from "rolldown";
 import { rolldownPlugin as pathIoc } from "@path-ioc/unplugin";
 
 export default defineConfig({
-  plugins: [pathIoc({ modulesPath: "src/modules", typeFileOutput: "types" })],
+  plugins: [pathIoc()],
 });
 ```
 
-### 3. Rspack (`rspack.config.js`)
+#### Rspack (`rspack.config.js`)
 ```javascript
 const { rspackPlugin: pathIoc } = require("@path-ioc/unplugin");
 
@@ -77,26 +102,35 @@ module.exports = {
 };
 ```
 
-### 4. Webpack 5 (`webpack.config.js`)
+#### Webpack 5 (`webpack.config.js`)
 ```javascript
 const { webpackPlugin: pathIoc } = require("@path-ioc/unplugin");
 
 module.exports = {
-  plugins: [pathIoc({ modulesPath: "src/modules" })],
+  plugins: [pathIoc()],
 };
 ```
 
-### 5. Rollup (`rollup.config.js`) / Esbuild
+#### Rollup (`rollup.config.js`) / Esbuild
 ```javascript
 // Rollup
 import { rollupPlugin as pathIoc } from "@path-ioc/unplugin";
+
 // Esbuild
 import { esbuildPlugin as pathIoc } from "@path-ioc/unplugin";
 ```
 
+> **零配置开箱即用**：各构建器插件均完全支持零参调用 `pathIoc()`。若项目目录结构特殊，可按需传入自定义配置：
+> ```typescript
+> pathIoc({
+>   modulesPath: "src/modules",   // 自定义模块根目录（默认: "src/modules"）
+>   typeFileOutput: "types",     // 自定义类型输出目录（默认: "types"）
+> })
+> ```
+
 ---
 
-## 插件配置项 (Plugin Options)
+## 插件配置项 (`PathIocPluginOptions`)
 
 | 配置项 | 类型 | 默认值 | 描述 |
 | :--- | :--- | :--- | :--- |
@@ -105,10 +139,50 @@ import { esbuildPlugin as pathIoc } from "@path-ioc/unplugin";
 
 ---
 
-## 真实应用与模块编写
+## 虚拟模块 (`virtual:modular-container`)
+
+构建插件在运行时动态提供以下命名导出：
+
+```typescript
+import {
+  modules,                 // 全量模块描述数组: { key: string, module: IOCModule }[]
+  createModularContainer,  // 高性能实例化入口: (targetContainer?: Record<string, any>) => Promise<ModularContainer>
+} from "virtual:modular-container";
+```
+
+### Serverless / Hono 生产级请求隔离示例
+
+```typescript
+import { Hono } from "hono";
+import { createModularContainer } from "virtual:modular-container";
+import { memoizeModule } from "@path-ioc/core";
+
+const app = new Hono<{ Bindings: { DB_URL: string } }>();
+
+app.use("*", async (c, next) => {
+  // 1. 微秒级容器点火：单图编译缓存（仅 21.2µs），高并发每请求安全隔离
+  const container = await createModularContainer();
+
+  // 2. 静态基础设施安全单例化 (利用单 Worker 实例内静态 env 缓存连接池)
+  // ⚠️ 铁律：严禁在 memoize 闭包内引用特定请求上下文 (如 c.req.header)
+  memoizeModule(container, "dbPool", () => createPostgresPool(c.env.DB_URL));
+
+  // 3. 动态注入当前请求的多租户专属上下文
+  container.$inject("requestContext", {
+    requestId: c.req.header("x-request-id") || crypto.randomUUID(),
+  });
+
+  c.set("ioc", container);
+  await next();
+});
+```
+
+---
+
+## 模块编写规范与进阶指南
 
-关于如何编写 `main` 纯函数模块、声明依赖、在应用入口一行唤醒容器，请参阅：  
-👉 **[查看 @path-ioc/core 完整实战指南](../core/README.zh-CN.md)**
+`@path-ioc/unplugin` 专注解决编译构建态的自动化扫描、类型合成与单图缓存注入。关于如何在业务中编写 `main` 纯函数闭包、声明 Mesh 依赖、利用 IoC-DL 进行依赖查找与 AOP 切面开发，请直接参阅：  
+👉 **[查看 `@path-ioc/core` 核心架构与实战指南](../core/README.zh-CN.md)** 或访问官方主站 **[https://path-ioc.dev/zh/](https://path-ioc.dev/zh/)**
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@path-ioc/unplugin",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Universal dev plugin for Path-IoC generating virtual modular container and TypeScript typings",
   "keywords": [
     "unplugin",