penta2himajin · penta2himajin · Mar 26, 2026 · Mar 25, 2026 · Mar 26, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -34,7 +34,7 @@ src/
   contexts.ts     # Solid contexts
   types.ts        # JSX IntrinsicElements
   index.ts        # Public API
-tests/            # Unit (79) + Integration (13) + Component (9) = 101 tests
+tests/            # 443 tests across 15 suites
 docs/             # Design specification
 examples/         # Runnable demos (breakout)
 ```

diff --git a/README.md b/README.md
@@ -57,14 +57,16 @@ solidion/
     core/           # Renderer internals: meta, props, events, texture, scene-stack, frame, sync
     hooks/          # L1a/L1b hooks: useTween, useSpring, useStateMachine, etc.
     behaviors/      # L1c composition components: SpringBehavior, OscillateBehavior, etc.
-    components/     # Game, Scene, Preload, Overlay
+    components/     # Game, Scene, Preload, Overlay, GameLoop, Show, For
+    ecs/            # Data-driven ECS: pure step functions + System component
+    debug/          # Dev-only utilities: inspectBindings, profiling, expose
     renderer.ts     # solid-js/universal createRenderer implementation
     contexts.ts     # Solid contexts (Game, Scene, FrameManager, ParentNode)
     types.ts        # JSX IntrinsicElements type definitions
-    index.ts        # Public API
-  tests/            # Unit tests (79) + integration tests (13) + component tests (9)
+    index.ts        # Public API (L0–L1c)
+  tests/            # 443 tests across 15 suites
   docs/             # Design specification
-  examples/         # Runnable demos
+  examples/         # Runnable demos (breakout, null-pow, floppy-heads, nadion-defense, aquarium)
 ```
 
 ## Testing
@@ -74,20 +76,25 @@ npm install
 npm test
 ```
 
-101 tests across 10 suites:
+443 tests across 15 suites:
 
 | Suite | Tests | Scope |
 |---|---|---|
+| renderer | 110 | Renderer logic (mock Phaser) |
+| hooks | 107 | State machine, spring, tween, sequence, etc. |
+| props | 48 | Property application & composition |
+| ecs | 38 | Pure step functions & System component |
+| texture | 29 | Texture auto-loading |
+| components | 18 | Sync, reapplyProp, preload |
+| visibility | 16 | Recursive visibility toggling |
+| debug | 14 | Debug utilities & profiling |
+| integration | 13 | Real Solid reactivity + renderer |
+| contexts | 12 | Context providers & accessors |
 | meta | 11 | Metadata & delta system |
 | events | 9 | Event name resolution |
-| props | 14 | Property application & composition |
-| texture | 9 | Texture auto-loading |
+| store-compat | 8 | SolidJS store compatibility |
 | scene-stack | 5 | Scene stack management |
 | frame | 5 | Frame callback lifecycle |
-| renderer | 12 | Renderer logic (mock Phaser) |
-| hooks | 14 | State machine & sequence logic |
-| components | 9 | Sync, reapplyProp, preload |
-| **integration** | **13** | **Real Solid reactivity + renderer** |
 
 ## Entry Points
 
@@ -124,6 +131,10 @@ See [docs/solidion-spec.md](docs/solidion-spec.md) for the full design specifica
 See [examples/](examples/) for runnable demos.
 
 - **[Breakout](examples/breakout/)** — Block breaker game demonstrating reactive signals, frame-loop physics, batch updates, and conditional state
+- **[Null Pow!](examples/null-pow/)** — Pac-Man-style maze game with ghost AI, useOverlap collision, and useScene keyboard input
+- **[Floppy Heads](examples/floppy-heads/)** — Flappy Bird-style game with procedural pipe generation and score tracking
+- **[Nadion Defense](examples/nadion-defense/)** — Space Invaders-style tower defense with 40 reactive enemies and projectile pools
+- **[Aquarium](examples/aquarium/)** — Hybrid ECS + hooks demo with fish, food, bubbles, jellyfish, and seaweed
 
 ## Why "Solidion"?
 

diff --git a/...es/aquarium/dist/assets/index-DXpeFDb9.js → ...es/aquarium/dist/assets/index-CBWJ4zHt.js b/...es/aquarium/dist/assets/index-DXpeFDb9.js → ...es/aquarium/dist/assets/index-CBWJ4zHt.js
diff --git a/examples/aquarium/dist/index.html b/examples/aquarium/dist/index.html
@@ -35,7 +35,7 @@
     }
     .footer a { color: #4488cc; text-decoration: none; }
   </style>
-  <script type="module" crossorigin src="./assets/index-DXpeFDb9.js"></script>
+  <script type="module" crossorigin src="./assets/index-CBWJ4zHt.js"></script>
 </head>
 <body>
   <div id="game-container"></div>

diff --git a/examples/aquarium/vite.config.ts b/examples/aquarium/vite.config.ts
@@ -18,6 +18,7 @@ export default defineConfig({
       "solidion/ecs": resolve(__dirname, "../../src/ecs/index.ts"),
       "solidion/core": resolve(__dirname, "../../src/core/index.ts"),
       "solidion/debug": resolve(__dirname, "../../src/debug/index.ts"),
+      "solidion/renderer": resolve(__dirname, "../../src/renderer.ts"),
       "solidion": resolve(__dirname, "../../src/index.ts"),
       "solid-js/store": resolve(rootModules, "solid-js/store/dist/store.js"),
       "solid-js/universal": resolve(rootModules, "solid-js/universal/dist/universal.js"),

diff --git a/...es/breakout/dist/assets/index-C5iHtZ1c.js → ...es/breakout/dist/assets/index-ClY0sCA3.js b/...es/breakout/dist/assets/index-C5iHtZ1c.js → ...es/breakout/dist/assets/index-ClY0sCA3.js
diff --git a/examples/breakout/dist/index.html b/examples/breakout/dist/index.html
@@ -35,7 +35,7 @@
     }
     .footer a { color: #7fdbca; text-decoration: none; }
   </style>
-  <script type="module" crossorigin src="./assets/index-C5iHtZ1c.js"></script>
+  <script type="module" crossorigin src="./assets/index-ClY0sCA3.js"></script>
 </head>
 <body>
   <div id="game-container"></div>

diff --git a/examples/breakout/vite.config.ts b/examples/breakout/vite.config.ts
@@ -18,6 +18,7 @@ export default defineConfig({
       "solidion/ecs": resolve(__dirname, "../../src/ecs/index.ts"),
       "solidion/core": resolve(__dirname, "../../src/core/index.ts"),
       "solidion/debug": resolve(__dirname, "../../src/debug/index.ts"),
+      "solidion/renderer": resolve(__dirname, "../../src/renderer.ts"),
       "solidion": resolve(__dirname, "../../src/index.ts"),
       "solid-js/universal": resolve(rootModules, "solid-js/universal/dist/universal.js"),
       "solid-js": resolve(rootModules, "solid-js/dist/solid.js"),

diff --git a/...loppy-heads/dist/assets/index-BQY7vmBW.js → ...loppy-heads/dist/assets/index-BTNBT8dr.js b/...loppy-heads/dist/assets/index-BQY7vmBW.js → ...loppy-heads/dist/assets/index-BTNBT8dr.js
diff --git a/examples/floppy-heads/dist/index.html b/examples/floppy-heads/dist/index.html
@@ -35,7 +35,7 @@
     }
     .footer a { color: #7fdbca; text-decoration: none; }
   </style>
-  <script type="module" crossorigin src="./assets/index-BQY7vmBW.js"></script>
+  <script type="module" crossorigin src="./assets/index-BTNBT8dr.js"></script>
 </head>
 <body>
   <div id="game-container"></div>

diff --git a/examples/floppy-heads/vite.config.ts b/examples/floppy-heads/vite.config.ts
@@ -18,6 +18,7 @@ export default defineConfig({
       "solidion/ecs": resolve(__dirname, "../../src/ecs/index.ts"),
       "solidion/core": resolve(__dirname, "../../src/core/index.ts"),
       "solidion/debug": resolve(__dirname, "../../src/debug/index.ts"),
+      "solidion/renderer": resolve(__dirname, "../../src/renderer.ts"),
       "solidion": resolve(__dirname, "../../src/index.ts"),
       // Deduplicate solid-js: ensure both example and library code use the
       // same instance, AND use the browser build (not server/SSR).

diff --git a/...ion-defense/dist/assets/index-BtiCr2mZ.js → ...ion-defense/dist/assets/index-DirEFGQ8.js b/...ion-defense/dist/assets/index-BtiCr2mZ.js → ...ion-defense/dist/assets/index-DirEFGQ8.js
diff --git a/examples/nadion-defense/dist/index.html b/examples/nadion-defense/dist/index.html
@@ -35,7 +35,7 @@
     }
     .footer a { color: #ff9944; text-decoration: none; }
   </style>
-  <script type="module" crossorigin src="./assets/index-BtiCr2mZ.js"></script>
+  <script type="module" crossorigin src="./assets/index-DirEFGQ8.js"></script>
 </head>
 <body>
   <div id="game-container"></div>

diff --git a/examples/nadion-defense/vite.config.ts b/examples/nadion-defense/vite.config.ts
@@ -18,6 +18,7 @@ export default defineConfig({
       "solidion/ecs": resolve(__dirname, "../../src/ecs/index.ts"),
       "solidion/core": resolve(__dirname, "../../src/core/index.ts"),
       "solidion/debug": resolve(__dirname, "../../src/debug/index.ts"),
+      "solidion/renderer": resolve(__dirname, "../../src/renderer.ts"),
       "solidion": resolve(__dirname, "../../src/index.ts"),
       // Deduplicate solid-js: ensure both example and library code use the
       // same instance, AND use the browser build (not server/SSR).

diff --git a/...es/null-pow/dist/assets/index-157JVz5-.js → ...es/null-pow/dist/assets/index-yj2HKat-.js b/...es/null-pow/dist/assets/index-157JVz5-.js → ...es/null-pow/dist/assets/index-yj2HKat-.js
diff --git a/examples/null-pow/dist/index.html b/examples/null-pow/dist/index.html
@@ -35,7 +35,7 @@
     }
     .footer a { color: #00cc88; text-decoration: none; }
   </style>
-  <script type="module" crossorigin src="./assets/index-157JVz5-.js"></script>
+  <script type="module" crossorigin src="./assets/index-yj2HKat-.js"></script>
 </head>
 <body>
   <div id="game-container"></div>

diff --git a/examples/null-pow/vite.config.ts b/examples/null-pow/vite.config.ts
@@ -18,6 +18,7 @@ export default defineConfig({
       "solidion/ecs": resolve(__dirname, "../../src/ecs/index.ts"),
       "solidion/core": resolve(__dirname, "../../src/core/index.ts"),
       "solidion/debug": resolve(__dirname, "../../src/debug/index.ts"),
+      "solidion/renderer": resolve(__dirname, "../../src/renderer.ts"),
       "solidion": resolve(__dirname, "../../src/index.ts"),
       // Deduplicate solid-js: ensure both example and library code use the
       // same instance, AND use the browser build (not server/SSR).

diff --git a/package.json b/package.json
@@ -15,6 +15,9 @@
     },
     "./debug": {
       "import": "./src/debug/index.ts"
+    },
+    "./renderer": {
+      "import": "./src/renderer.ts"
     }
   },
   "scripts": {

diff --git a/site/astro.config.mjs b/site/astro.config.mjs
@@ -40,6 +40,7 @@ export default defineConfig({
             { slug: "guides/components" },
             { slug: "guides/hooks" },
             { slug: "guides/behaviors" },
+            { slug: "guides/ecs" },
           ],
         },
         {

diff --git a/site/src/content/docs/guides/behaviors.md b/site/src/content/docs/guides/behaviors.md
@@ -5,6 +5,10 @@ description: Declarative behavior components for composition
 
 Behaviors (L1c layer) provide declarative composition for common game patterns. They can be used as JSX children of game objects.
 
+```tsx
+import { SpringBehavior, OscillateBehavior, FollowBehavior, VelocityBehavior } from "solidion";
+```
+
 ## SpringBehavior
 
 Attach spring physics to a game object property.

diff --git a/site/src/content/docs/guides/components.md b/site/src/content/docs/guides/components.md
@@ -5,6 +5,10 @@ description: Built-in Solidion components
 
 Solidion provides high-level components for managing Phaser's game lifecycle.
 
+```tsx
+import { Game, Scene, Preload, Overlay, GameLoop, Show, For, Index } from "solidion";
+```
+
 ## Game
 
 The root component that creates a Phaser game instance.

diff --git a/site/src/content/docs/guides/ecs.md b/site/src/content/docs/guides/ecs.md
@@ -0,0 +1,84 @@
+---
+title: ECS (Entity Component System)
+description: Data-driven pattern for bulk entity processing
+---
+
+The ECS pattern (`solidion/ecs`) is for games with many entities of the same type — 10+ fish, 30+ bullets, etc. It combines SolidJS `createStore` with pure step functions and declarative `System` components.
+
+```tsx
+import { System, forActive, createSystemFactory } from "solidion/ecs";
+import {
+  springStep, velocityStep, followStep,
+  oscillationStep, fsmStep, fsmSend,
+  tweenStep, tweenLerp,
+} from "solidion/ecs";
+```
+
+## When to use ECS vs Hooks
+
+| Pattern | When |
+|---------|------|
+| **Hooks** (`useSpring`, `useStateMachine`, ...) | Few entities (1–5), unique complex behavior per entity |
+| **ECS** (`System` + step functions) | Many entities (10+), shared behavior definitions, single store |
+
+## Pure Step Functions
+
+Step functions are the same algorithms used inside `useSpring`, `useOscillation`, etc., extracted as pure functions for bulk processing. They take current state + config + delta time, and return the next state.
+
+```tsx
+import { springStep, type SpringState, type SpringConfig } from "solidion/ecs";
+
+// Advance a spring by delta seconds
+const next: SpringState = springStep(
+  { x: 0, y: 0, vx: 0, vy: 0 },
+  { targetX: 100, targetY: 200, stiffness: 120, damping: 14 },
+  1 / 60,
+);
+```
+
+Available step functions:
+
+| Function | Description |
+|----------|-------------|
+| `springStep` | Damped spring simulation |
+| `oscillationStep` | Sine-wave oscillation |
+| `velocityStep` | Velocity + acceleration + bounds/bounce |
+| `followStep` | Exponential decay toward a target |
+| `fsmStep` / `fsmSend` | Finite state machine transitions |
+| `tweenStep` / `tweenLerp` | Tween interpolation |
+
+## System Component
+
+`System` registers a per-frame callback. Place it inside `<Game>` or `<Scene>` — JSX child order determines execution order.
+
+```tsx
+const [store, setStore] = createStore({ fish: [...] });
+
+<Game>
+  <System
+    when={() => phase() === "play"}
+    update={(time, delta) => {
+      forActive(store.fish, (f, i) => {
+        const next = springStep(f, f.config, delta / 1000);
+        setStore("fish", i, next);
+      });
+    }}
+  />
+</Game>
+```
+
+## forActive
+
+Helper to iterate only active entities in a store array:
+
+```tsx
+forActive(store.entities, (entity, index) => {
+  // Only called for entities where entity.active !== false
+  const next = velocityStep(entity, entity.config, delta / 1000);
+  setStore("entities", index, next);
+});
+```
+
+## Full Example
+
+See [examples/aquarium/](https://github.com/penta2himajin/solidion/tree/main/examples/aquarium) for a complete hybrid ECS + hooks demo with fish, food, bubbles, and more.
diff --git a/site/src/content/docs/guides/hooks.md b/site/src/content/docs/guides/hooks.md
@@ -5,6 +5,11 @@ description: Solidion hooks for animations, state machines, and more
 
 Solidion provides hooks (L1a layer) that integrate Phaser features with SolidJS reactivity.
 
+```tsx
+import { useTween, useStateMachine, useSequence, useOverlap } from "solidion";  // L1a
+import { useSpring, useFollow, useOscillation, useVelocity } from "solidion";  // L1b
+```
+
 ## useTween
 
 Animate properties with Phaser tweens, controlled reactively.

diff --git a/site/src/content/docs/ja/guides/behaviors.md b/site/src/content/docs/ja/guides/behaviors.md
@@ -5,6 +5,10 @@ description: コンポジション用の宣言的Behaviorコンポーネント
 
 Behaviors（L1cレイヤー）は一般的なゲームパターンのための宣言的なコンポジションを提供します。ゲームオブジェクトのJSX子要素として使用できます。
 
+```tsx
+import { SpringBehavior, OscillateBehavior, FollowBehavior, VelocityBehavior } from "solidion";
+```
+
 ## SpringBehavior
 
 ゲームオブジェクトのプロパティにスプリング物理を付与します。

diff --git a/site/src/content/docs/ja/guides/components.md b/site/src/content/docs/ja/guides/components.md
@@ -5,6 +5,10 @@ description: Solidionの組み込みコンポーネント
 
 SolidionはPhaserのゲームライフサイクルを管理するための高レベルコンポーネントを提供します。
 
+```tsx
+import { Game, Scene, Preload, Overlay, GameLoop, Show, For, Index } from "solidion";
+```
+
 ## Game
 
 Phaserゲームインスタンスを作成するルートコンポーネントです。
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,6 +5,10 @@ description: Built-in Solidion components @@
     Solidion provides high-level components for managing Phaser's game lifecycle.
+    ```tsx
+    import { Game, Scene, Preload, Overlay, GameLoop, Show, For, Index } from "solidion";
+    ```
     ## Game
     The root component that creates a Phaser game instance.
@@ Expand Down @@