開發規範與核心守則

Islumina 不以龐大單體框架（Monolithic Framework）自居，而是以「模組化組合」為核心哲學。

所有的生態系模組皆遵循嚴格的架構標準，確保開發者可以零負擔、無縫地將特定模組引進現有的架構中，不被框架給綁架。

家族硬規 (Core Principles)

在 Islumina 家族中的所有核心套件，都必須且已經遵守以下最高標準的架構紀律：

1. 零跨套件依賴 (Zero Cross-Package Dependencies) 這是最重要的 P0 級規範。每個套件（例如 aifsmjs 或 aiecsjs）都是完全獨立的模組，絕不互相依賴。它們會自帶必要的底層實作（例如各自獨立的 Event Emitter），保證您的專案即使只安裝單一套件，也不會引入任何不必要的耦合。

2. 無框架綁定 (Framework-Agnostic) 所有的套件皆為純邏輯層的實作，程式碼內 絕對不 包含對特定渲染引擎（如 PixiJS、Three.js）或 UI 框架（如 React、Vue）的引用。它們可以無痛掛載至任何網頁、Node.js，甚至是 Web Worker 之中。

3. 純淨輸出 (ESM + CJS Dual Export) 所有模組皆透過 tsup 進行打包，支援完整的 ESM 與 CJS 雙輸出，無論您的建置工具為何都能輕鬆整合。

4. 最高級別的型別安全 (TypeScript Strict) 套件使用最嚴格的 TypeScript 規範開發（開啟 strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes 等設定），且全面禁止使用 any。

---

模組核心定位與使用指南

雖然各套件彼此獨立，但它們在系統設計上各有專注的單一職責（Single Responsibility）：

1. aifsmjs - 有限狀態機

專為高自由度設計的 FSM 模組，支援精簡的字串狀態轉移（string-shorthand transition）、可選用的上下文（Context）共享，以及階層式的子狀態機（Hierarchical Sub-machine）。

2. aiecsjs - 實體元件系統 (Entity Component System)

高效能架構的原型 ECS。提供極速的 forEachEntityIndexed 遍歷機制，並內建記憶體回收安全（recycle-safe）的陣列下標操作。支援實體關係（Relations）、指令緩衝（Commands）並可將邏輯委派給 SharedArrayBuffer (SAB) Worker 運行。

3. aispritejs - 狀態驅動的精靈圖動畫引擎

透過純數值、布林值或觸發事件來驅動狀態轉移，進而映射到對應的動畫幀。它是完全渲染無關（renderer-agnostic）的核心，可輕鬆與 PixiJS 等渲染器銜接（提供對應的 adapter 參考）。

4. aieventjs - 具備型別安全的事件發布訂閱系統

不只是簡單的 Emitter，更支援時間節流（throttleMs）、通配符（wildcard）監聽，甚至具備進階的採樣率（sampleRate）功能。

5. aipooljs - 物件池管理

標準化高效的物件生命週期管理。專注於 borrow（借出）機制以及當池滿時的安全處理機制（onOverflow）。

6. aiquadtreejs - 四元樹空間分割

專為碰撞偵測與 Broadphase 檢索設計。提供零記憶體分配（zero-alloc）的 retrieveInto API，杜絕每一幀的垃圾回收（GC）壓力。

7. aiaudiojs - 遊戲音效系統

基於 Howler.js 的高階封裝，專注於解決遊戲中的音效生命週期與等功率淡入淡出（equal-power crossfade）。（註：刻意排除內建的合成器 synth 實作，以保持輕量化。）

8. aibridgejs - 通訊橋接系統

專注於嚴格的網頁安全（pure-web safety labels）的溝通橋接層，用於不同系統或跨環境（如 Main thread 與 Worker 之間）的資料拋接。