docs: update README with enhanced mental model and add shadow theater diagram

Author: spearwolf

README.md

@@ -1,51 +1,89 @@
 # shadow-objects
 
-A reactive entity←component framework that feels home in the shadows 🧛
+A reactive Entity←Component Framework that feels at home in the shadows 🧛
 
 > [!WARNING]
 > 🚀 This is a highly experimental framework that is slowly maturing. Use at your own risk. 🔥
 
-## Documentation 📚
+---
+
+## 🎭 The Mental Model: The Shadow Theater
+
+Imagine a **web application** like a classic **Shadow Theater**:
+
+*   **The Screen (View):** What the user sees – the DOM elements and UI components.
+*   **The Puppets (Entities):** The abstract objects in the background representing the actual scene.
+*   **The Puppeteer (Shadow Object):** The logic pulling the strings. The puppeteer decides how the puppets move but remains invisible to the audience.
+
+**The Problem with Traditional Frameworks:**
+Logic (puppeteer) and presentation (screen) are often mixed in the same thread (Main Thread). In complex applications, this leads to performance bottlenecks because UI rendering blocks business logic – and vice versa.
+
+**The Solution by `shadow-objects`:**
+We separate the worlds strictly.
+
+![The Shadow Theater Model](packages/shadow-objects/docs/shadow-theater.svg)
+
+1.  **In the Light (Main Thread):** The dumb View. It only displays and forwards events.
+2.  **In the Shadow (Web Worker):** The smart Logic. This is where **Entities** and **Shadow Objects** live. They process data, calculate states, and "project" the result back onto the screen.
+
+Through this architecture, your application logic runs parallel to the UI, decoupled and reactive.
+
+---
+
+## 📚 Documentation
 
 **The complete and authoritative documentation is located in the [`packages/shadow-objects/docs/`](packages/shadow-objects/docs/) directory.**
 
-*   [**Fundamentals**](packages/shadow-objects/docs/01-fundamentals/): Understand the mental model, architecture, and lifecycle.
-*   [**Guides**](packages/shadow-objects/docs/02-guides/): Step-by-step instructions.
-*   [**API Reference**](packages/shadow-objects/docs/03-api/): Detailed API docs.
+*   [**Fundamentals**](packages/shadow-objects/docs/01-concepts/): Understand the mental model, architecture, and lifecycle in detail.
+*   [**Guides**](packages/shadow-objects/docs/02-guides/): Step-by-step instructions for getting started.
+*   [**API Reference**](packages/shadow-objects/docs/03-api/): Detailed description of the interfaces.
+
+---
 
-## 🏗️ Project Structure
+## 🏗️ Project Structure (Monorepo)
 
 This repository is a monorepo managed with [nx](https://nx.dev/) and [pnpm](https://pnpm.io/).
 
+### Core Packages
+
+| Package | Description |
+| :--- | :--- |
+| **[`shadow-objects`](packages/shadow-objects/)** | The heart. The core library of the framework. |
+| **[`shae-offscreen-canvas`](packages/shae-offscreen-canvas/)** | A Custom Element implementing an **Offscreen Canvas** – demonstrates the power of `shadow-objects` for graphics applications. |
+
+### Testing & Quality Assurance
+
 | Package | Description |
 | :--- | :--- |
-| **[`shadow-objects`](packages/shadow-objects/)** | The core framework library. |
-| **[`shae-offscreen-canvas`](packages/shae-offscreen-canvas/)** | A custom HTML element implementing an **offscreen canvas**. |
 | **[`shadow-objects-testing`](packages/shadow-objects-testing/)** | Functional and integration tests. |
-| **[`shadow-objects-e2e`](packages/shadow-objects-e2e/)** | End-to-end tests using [Playwright](https://playwright.dev/). |
+| **[`shadow-objects-e2e`](packages/shadow-objects-e2e/)** | End-to-End tests using [Playwright](https://playwright.dev/). |
+
+---
 
 ## ⚡ Available Scripts
 
 Run these commands from the root directory:
 
 | Command | Description |
 | :--- | :--- |
-| `pnpm cbt` | **Clean, Build, Test.** Runs a full clean build and test cycle for the entire workspace. |
+| `pnpm cbt` | **Clean, Build, Test.** Runs a full cycle: clean, build, and test the entire workspace. |
 | `pnpm start` | Starts the **shae-offscreen-canvas** demo server. |
 | `pnpm test` | Runs all tests (Unit, Integration, E2E) across all packages. |
 | `pnpm test:ci` | Runs tests excluding E2E (faster, for CI pipelines). |
 | `pnpm build` | Builds all packages. |
-| `pnpm lint` | Runs linting across the workspace. |
-| `pnpm clean` | Cleans all build artifacts (`dist`, `build` folders). |
+| `pnpm lint` | Runs linter across the entire workspace. |
+| `pnpm clean` | Deletes all build artifacts (`dist`, `build` folders). |
+
+---
 
 ## ⚙️ Development Setup
 
 1.  **Prerequisites:** Node.js >=20.12.2, pnpm >=9.1.2
-2.  **Install dependencies:**
+2.  **Install Dependencies:**
     ```sh
     pnpm install
     ```
-3.  **Install Playwright browsers (for E2E):**
+3.  **Install Playwright Browsers (for E2E Tests):**
     ```sh
     cd packages/shadow-objects-e2e
     pnpm exec playwright install chromium firefox