You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+43-25Lines changed: 43 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,39 +2,56 @@
2
2
3
3
This document provides context and guidelines for AI agents working on the **Shadow Objects Framework**.
4
4
5
-
## 1. Project Overview
5
+
## 1. How It Works (3 lines)
6
6
7
-
The **Shadow Objects Framework** is a reactive library designed to decouple business logic and state management from the UI rendering layer. It runs application logic "in the dark" (e.g., in a web worker), mirroring the view hierarchy of the application.
8
-
9
-
**Goal:** Separate concerns by running logic in a separate thread/context from the UI, using a reactive architecture.
7
+
Shadow Objects is an ECS framework where **Entities** (game objects) live in a **Shadow Environment** (main thread or web worker), and **Shadow Objects** (ECS components) attach behavior to them. The **View Layer** (DOM, Canvas) renders entity state and dispatches events back into the shadow environment. The **Kernel** orchestrates the entity lifecycle and schedules updates.
10
8
11
9
## 2. Architecture & Core Concepts
12
10
13
-
### Mental Model (The Shadow Theater)
14
-
-**View (Screen):** The visible UI (DOM, Canvas). Minimal state, pure projection.
15
-
-**Entities (Puppets):** Abstract representation of components in the Shadow World.
16
-
-**Shadow Objects (Puppeteer):** Functional units of logic attached to Entities.
17
-
-**Token:** String identifier linking View components to Logic.
11
+
### Mental Model (ECS Game Engine)
12
+
13
+
Shadow Objects is an Entity-Component System (ECS) applied to web app state management:
14
+
15
+
-**View / Renderer:** The visible UI (DOM, Canvas). Minimal state, pure rendering.
16
+
-**Entities (Game Objects):** Lightweight containers in the shadow environment — no logic of their own.
17
+
-**Shadow Objects (ECS Components):** Functional units of logic attached to Entities. This is where behavior lives.
18
+
-**Token (Component Tag):** String identifier linking View nodes to their shadow logic.
18
19
19
20
### Key Components
20
-
-**Kernel:** The engine. Manages Entity lifecycle, orchestrates Shadow Objects, and schedules updates.
21
-
-**Registry:** Maps **Tokens** to **Shadow Object Constructors**. Defines routing and composition rules.
22
-
-**Message Dispatch:** Bridges the gap between Light World (UI) and Shadow World (Worker) via asynchronous messages.
Copy file name to clipboardExpand all lines: README.md
+38-39Lines changed: 38 additions & 39 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,66 +1,65 @@
1
1
# shadow-objects
2
2
3
-
A reactive Entity←Component Framework that feels at home in the shadows 🧛
3
+
A reactive Entity-Component Framework for running app logic in a shadow environment.
4
4
5
5
> [!WARNING]
6
-
> 🚀 This is a highly experimental framework that is slowly maturing. Use at your own risk. 🔥
6
+
> This is a highly experimental framework that is slowly maturing. Use at your own risk.
7
7
8
8
---
9
9
10
-
## 🎭 The Mental Model: The Shadow Theater
10
+
## The Mental Model: ECS for Web Apps
11
+
12
+
Think of shadow-objects like a **game engine for your application state**:
11
13
12
-
Imagine a **web application** like a classic **Shadow Theater**:
14
+
-**Your UI (React, Vue, Svelte, Canvas)** is the renderer — it just draws what it's told.
15
+
-**Entities** are lightweight game objects in the shadow environment. No logic, just identity.
16
+
-**Shadow Objects** are ECS components that attach behavior to entities — signals, effects, event handlers.
17
+
-**The Kernel** runs the show: it manages entity lifecycle and schedules updates.
13
18
14
-
***The Screen (View):** What the user sees – the DOM elements and UI components.
15
-
***The Puppets (Entities):** The abstract objects in the background representing the actual scene.
16
-
***The Puppeteer (Shadow Object):** The logic pulling the strings. The puppeteer decides how the puppets move but remains invisible to the audience.
19
+
Your UI is the renderer. Shadow Objects is the game world.
17
20
18
-
**The Problem with Traditional Frameworks:**
19
-
Logic (puppeteer) and presentation (screen) are often mixed in the same thread (Main Thread). This works well for document-centric applications, but friction arises in complex, rich interactions like 3D configurators, game engines, or data-intensive tools and leads to complexity bottlenecks because UI rendering blocks business logic – and vice versa.
21
+
The shadow environment can run on the **main thread** (local mode, zero overhead) or in a **web worker** (remote mode, parallel execution). Both are first-class citizens.
20
22
21
-
**The Solution by `shadow-objects`:**
22
-
We separate the worlds strictly.
23
+
**Shadow Objects doesn't replace React, Vue, or Svelte.** It's the logic layer those frameworks render. When your app state gets complex enough that you're fighting your UI framework's reactivity, shadow-objects gives you a clean separation: business logic over here, rendering over there.
If Redux and Zustand are global state on one thread, shadow-objects is reactive ECS state across any number of threads.
25
26
26
-
1.**In the Light (Main Thread):** The dumb View. It only displays and forwards events.
27
-
2.**In the Shadow (Web Worker _or_ Main Thread):** The smart Logic. This is where **Entities** and **Shadow Objects** live. They process data, calculate states, and "project" the result back onto the screen.
27
+
---
28
28
29
-
Through this architecture, your application logic runs parallel to the UI, decoupled and reactive.
29
+
> [!WARNING]
30
+
> 🚀 This is a highly experimental framework that is slowly maturing. Use at your own risk. 🔥
30
31
31
32
---
32
33
33
-
## 📚 Documentation
34
+
## Documentation
34
35
35
-
**The complete and authoritative documentation is located in the [`packages/shadow-objects/docs/`](packages/shadow-objects/docs/) directory.**
36
+
**The complete and authoritative documentation is in [`packages/shadow-objects/docs/`](packages/shadow-objects/docs/).**
36
37
37
-
*[**Fundamentals**](packages/shadow-objects/docs/01-concepts/): Understand the mental model, architecture, and lifecycle in detail.
38
-
*[**Guides**](packages/shadow-objects/docs/02-guides/): Step-by-step instructions for getting started.
39
-
*[**API Reference**](packages/shadow-objects/docs/03-api/): Detailed description of the interfaces.
38
+
| File | What's inside |
39
+
| :--- | :--- |
40
+
|[**getting-started.md**](packages/shadow-objects/docs/getting-started.md)| Hello World, your first shadow object |
41
+
|[**concepts.md**](packages/shadow-objects/docs/concepts.md)| ECS mental model, architecture, lifecycle, entity tree |
This repository is a monorepo managed with [nx](https://nx.dev/) and [pnpm](https://pnpm.io/).
46
52
47
-
### Core Packages
48
-
49
-
| Package | Description |
50
-
| :--- | :--- |
51
-
|**[`shadow-objects`](packages/shadow-objects/)**| The heart. The core library of the framework. |
52
-
|**[`shae-offscreen-canvas`](packages/shae-offscreen-canvas/)**| A Custom Element implementing an **Offscreen Canvas** – demonstrates the power of `shadow-objects` for graphics applications. |
53
-
54
-
### Testing & Quality Assurance
55
-
56
-
| Package | Description |
57
-
| :--- | :--- |
58
-
|**[`shadow-objects-testing`](packages/shadow-objects-testing/)**| Functional and integration tests. |
59
-
|**[`shadow-objects-e2e`](packages/shadow-objects-e2e/)**| End-to-End tests using [Playwright](https://playwright.dev/). |
53
+
| Package | npm name | Description |
54
+
| :--- | :--- | :--- |
55
+
|[**`shadow-objects`**](packages/shadow-objects/)|`@spearwolf/shadow-objects`| The core framework library |
56
+
|[**`shae-offscreen-canvas`**](packages/shae-offscreen-canvas/)|`@spearwolf/shae-offscreen-canvas`| Custom element for offscreen canvas rendering — demonstrates shadow-objects for graphics |
57
+
|[**`shadow-objects-testing`**](packages/shadow-objects-testing/)| — (not published) | Functional and integration tests |
58
+
|[**`shadow-objects-e2e`**](packages/shadow-objects-e2e/)| — (not published) | End-to-end tests using [Playwright](https://playwright.dev/)|
60
59
61
60
---
62
61
63
-
## ⚡ Available Scripts
62
+
## Available Scripts
64
63
65
64
Run these commands from the root directory:
66
65
@@ -76,14 +75,14 @@ Run these commands from the root directory:
Playwright end-to-end test suite for the shadow-objects ecosystem.
4
+
5
+
This package is not published to npm. It runs full browser tests against a Vite-served app, covering scenarios that require a real page load -- remote worker environments, bundle integrity, and multi-entity interactions.
6
+
7
+
## What lives here
8
+
9
+
-**Remote worker environment tests** -- spinning up a shadow environment in a web worker and verifying it communicates correctly with the view layer
10
+
-**Bundle smoke tests** -- loading the published build artifacts in a real browser to catch packaging mistakes early
11
+
-**Worker and canvas integration tests** -- exercising the full path from view-layer entities through the worker to rendered output
12
+
13
+
## Prerequisites
14
+
15
+
Playwright browsers must be installed before running the tests:
Functional and integration test suite for the `@spearwolf/shadow-objects` core library.
4
+
5
+
This package is not published to npm. It exists solely to exercise the shadow-objects internals in a real browser environment using `@web/test-runner`.
6
+
7
+
## What lives here
8
+
9
+
-**Entity and component lifecycle tests** -- verifying that entities are created, destroyed, and re-parented correctly
10
+
-**Token and registry tests** -- confirming that tokens connect view nodes to the right shadow objects
11
+
-**Change propagation tests** -- covering how property and token changes flow through the shadow environment
12
+
-**Event routing tests** -- ensuring that events sent from the view layer reach the correct shadow objects
This package contains the core library for the **Shadow Objects Framework** — a reactive library that decouples business logic from UI rendering using a full Entity Component System (ECS) architecture.
*[**API Reference**](./docs/03-api/): Detailed API docs.
12
-
*[**Best Practices & Patterns**](./docs/04-patterns/): Idiomatic usage and design patterns.
5
+
Shadow Objects is a reactive ECS (Entity Component System) library that decouples business logic from UI rendering. Entities are lightweight game objects; Shadow Objects are ECS components that attach behavior to them. Shadow environments can run on the main thread (local) or in a web worker (remote) -- both are first-class.
0 commit comments