add documentation (WIP)

Author: spearwolf

packages/shadow-objects/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to [@spearwolf/shadow-objects](https://github.com/spearwolf/
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## unreleased
+
+- sharpen the `EntityApi` type definitions
+
 ## [0.26.4] - 2026-01-15
 
 - fix return type definitions for `provideContext()` and `provideGlobalContext()`

packages/shadow-objects/README.md

@@ -140,7 +140,7 @@ In your HTML or View layer, you use the provided Web Components to create the En
 
 ```html
 <!-- 1. Initialize the Environment -->
-<shae-worker-env src="./my-module.js"></shae-worker-env>
+<shae-worker src="./my-module.js"></shae-worker>
 
 <!-- 2. Create Entities -->
 <shae-ent token="my-entity">

packages/shadow-objects/docs/01-fundamentals/01-mental-model.md

@@ -0,0 +1,62 @@
+# The Mental Model
+
+The **Shadow Objects Framework** is built upon a strict separation of concerns. To help you visualize how this works, let's start with a simple analogy.
+
+## Analogy: The Shadow Theater
+
+Imagine a **Shadow Theater** (Wayang Kulit).
+
+*   **The Screen (The View):** The audience watches the screen. They see moving shapes and stories unfolding. This is your UI (HTML/CSS).
+*   **The Puppets (The Entities):** Behind the screen are the puppets. They are the actual objects with structure and form.
+*   **The Puppeteer (The Logic/Shadow Object):** The puppeteer manipulates the puppets, deciding how they move and react based on the script.
+
+In Shadow Objects:
+*   You don't script the screen directly (no `document.querySelector` to update text).
+*   You script the **Puppeteer** (Shadow Object).
+*   The framework projects the state of the puppets onto the screen automatically.
+
+## The Two Worlds
+
+This analogy maps to two distinct realms in your application:
+
+### 1. The Light World (View)
+This is what the user sees and interacts with. It consists of the DOM, Web Components, and the rendering layer.
+*   **Role:** Pure projection and user input.
+*   **State:** Minimal / Transient. Ideally, the view should not hold business logic state.
+*   **Environment:** The Main Thread (Browser UI).
+
+### 2. The Shadow World (Logic)
+This is where your application actually "lives". It contains the business logic, state management, and side effects.
+*   **Role:** Processing logic, managing state, handling data.
+*   **State:** The source of truth.
+*   **Environment:** Typically a **Web Worker** (the "Dark"), but can also run on the Main Thread for simple setups.
+
+## Core Concepts
+
+To bridge these two worlds, we use four fundamental concepts:
+
+### 1. Entity (The Puppet)
+An **Entity** is the abstract representation of a component. It exists in the Shadow World but mirrors a node in the View hierarchy.
+*   Forms a tree structure (Parent/Child).
+*   Holds **Properties** (data syncing from View).
+*   Participates in the **Context** system.
+
+### 2. Shadow Object (The Brain)
+A **Shadow Object** is a functional unit of logic attached to an Entity.
+*   It is the "code" that runs for a specific component.
+*   It is reactive: it listens to property changes and triggers effects.
+*   It can talk to other Shadow Objects via Context.
+
+### 3. Token (The Name)
+A **Token** is a simple string identifier (e.g., `"my-button"`, `"user-profile"`) that links the View to the Logic.
+*   In the View: `<shae-ent token="my-button">`
+*   In the Registry: `"my-button"` maps to `MyButtonShadowObject`.
+
+> [!NOTE]
+> **Token vs. ID:** A `Token` describes *what* the object is (like a class name). The framework assigns unique IDs internally to distinguish specific instances.
+
+### 4. Events (The Signals)
+While Properties flow down (from View to Logic), **Events** allow for dynamic communication in both directions.
+
+*   **Inbound (View → Logic):** Entities receive events from the View (like `click`, `submit`, or custom DOM events). Your Shadow Object can listen to these events to trigger actions.
+*   **Outbound (Logic → View):** Shadow Objects can emit their own events. These travel back to the View, allowing the UI layer to react to logic decisions (e.g., playing an animation, showing a toast, or navigating).

packages/shadow-objects/docs/01-fundamentals/02-architecture.md

@@ -0,0 +1,110 @@
+# Architecture
+
+This section details how the Shadow Objects framework orchestrates the communication between the View and the Logic, and how its internal systems operate.
+
+## System Overview
+
+The architecture revolves around a central **Kernel** that manages the lifecycle of the Shadow World and mediates communication.
+
+A key architectural decision is that the **View Layer is abstract**. While the framework provides ready-to-use Web Components, they are built on top of a lower-level JavaScript API that you can use directly.
+
+```mermaid
+graph TD
+    subgraph "Light World (Main Thread)"
+        UserCode[Your App / Framework]
+
+        subgraph "View Layer Abstraction"
+            WC[Web Components <shae-ent>]
+            React[React / Vue Adapter]
+            Vanilla[Vanilla JS]
+
+            API[ViewComponent API]
+        end
+
+        UserCode --> WC
+        UserCode --> React
+        UserCode --> Vanilla
+
+        WC -.->|Uses| API
+        React -.->|Uses| API
+        Vanilla -.->|Uses| API
+    end
+
+    subgraph "Communication Bridge"
+        Msg[Message Dispatch]
+    end
+
+    subgraph "Shadow World (Worker Thread)"
+        Kernel[The Kernel]
+        Registry[Registry]
+
+        EntityTree[Entity Tree]
+        Entity[Entity]
+        SO[Shadow Object]
+
+        Kernel -->|Manages| EntityTree
+        Kernel -->|Consults| Registry
+
+        EntityTree --> Entity
+        Entity -->|Has| SO
+    end
+
+    API -->|Messages| Msg
+    Msg -->|Events| Kernel
+    Kernel -->|State Updates| Msg
+    Msg -->|Render Updates| API
+```
+
+## Core Components
+
+### 1. The Kernel
+The **Kernel** is the engine of the Shadow World.
+*   **Entity Management:** It maintains the `EntityTree`, handling the creation, movement, and destruction of Entities mirroring the DOM structure.
+*   **Orchestration:** When an Entity is created, the Kernel asks the **Registry** "What logic belongs to this Token?" and instantiates the corresponding Shadow Objects.
+*   **Scheduling:** It manages the reactive update cycle, ensuring changes propagate efficiently.
+
+### 2. The Registry
+The **Registry** is the configuration lookup table.
+*   **Mapping:** It maps **Tokens** (strings) to **Shadow Object Constructors**.
+*   **Routing:** It defines complex composition rules. A single Token in the view might trigger multiple Shadow Objects in the logic (e.g., a "button" token might load the `ButtonLogic` *and* a `AnalyticsMixin`).
+*   **Conditional Routing:** Routes can be dynamic, loading logic only if certain properties are present on the Entity.
+
+### 3. Message Dispatch
+Because the Light World and Shadow World often run in different threads (Main vs. Worker), they cannot share memory directly. They communicate via **Messages**.
+*   **View -> Shadow:** Property changes, DOM events, and lifecycle hooks are sent as messages to the Kernel.
+*   **Shadow -> View:** State changes in Shadow Objects are batched and sent back to update the View.
+
+## The View Layer & ViewComponent API
+
+The framework interacts with the "Light World" through the **ViewComponent API**. This is a JavaScript interface that handles the message passing and synchronization with the Kernel.
+
+### Web Components (The Default Implementation)
+The standard way to use Shadow Objects is via the provided Web Components (`<shae-worker>`, `<shae-ent>` and `<shae-prop>`).
+*   **Role:** These are simply a convenience wrapper.
+*   **Function:** They automatically handle the lifecycle (mount/unmount) and property syncing by calling the ViewComponent API internally.
+
+### Custom Integrations
+Because the architecture relies on the ViewComponent API, you are not forced to use Web Components. You can integrate Shadow Objects into any environment:
+*   **React/Vue/Svelte:** You could write a wrapper that syncs a React component's lifecycle to Shadow Objects.
+*   **Vanilla JS:** You can instantiate `ViewComponent` classes directly in plain JavaScript code if you don't want to use DOM elements.
+*   **Canvas/WebGL:** You could even bind Shadow Objects to non-DOM objects, like sprites in a game engine.
+
+## Communication Patterns
+
+### Property Synchronization (Downstream)
+Data flows primarily **down** from the View to the Shadow World.
+1.  **View Update:** The View (e.g., via attribute change on `<shae-ent>` or direct API call) updates a property.
+2.  **Message:** The ViewComponent API sends a message to the Kernel.
+3.  **Kernel Update:** Kernel updates `Entity.properties`.
+4.  **Reaction:** Shadow Object's `useProperty` signal updates, triggering Effects.
+
+### Events (Upstream & Lateral)
+Shadow Objects can emit events or react to them.
+*   **DOM Events:** Forwarded from View to Entity.
+*   **Internal Events:** Entities can emit events to communicate with parents or children without direct references.
+
+### Context (Dependency Injection)
+The framework implements a hierarchical **Context** system similar to React Context or Angular Services.
+*   **Provider:** An Entity provides a value (or signal).
+*   **Consumer:** Any descendant Entity can consume that value.
+*   **Reactive:** If the provider updates the value, all consumers update automatically.

packages/shadow-objects/docs/01-fundamentals/03-lifecycle.md

@@ -0,0 +1,125 @@
+# Lifecycle
+
+Understanding the lifecycle of an Entity and its Shadow Objects is crucial for managing resources, side effects, and subscriptions correctly.
+
+## The Entity Lifecycle
+
+An Entity's life is controlled by the **ViewComponent API**.
+
+### View Components & Component Context
+
+The underlying machinery involves two key classes:
+1.  **`ViewComponent`**: Represents a single node in the View Layer.
+2.  **`ComponentContext`**: Orchestrates a group of ViewComponents, manages their hierarchy, and batches changes (Change Trails) to be sent to the Kernel.
+
+While most developers use the provided Web Components, it's helpful to understand how they map to this API:
+
+*   **`<shae-ent>` (The Entity):** When this Web Component is connected to the DOM, it internally creates a new `ViewComponent` instance and mounts it.
+*   **`<shae-worker>` (The Environment):** This Web Component (or similar environment wrappers) manages the `ComponentContext`. It ensures that all `<shae-ent>` children are registered within the same context, allowing them to form a cohesive tree structure that is then synced to the Shadow World.
+
+### Lifecycle Phases
+
+1.  **Mount (View Layer):** The View Component is initialized and registered with its Context.
+    *   *Web Components:* `<shae-ent>` connects, finds its nearest `ComponentContext` (provided by parent `<shae-ent>` or root `<shae-worker>`), and registers itself.
+    *   *Manual:* You create a `ViewComponent` and call `context.addComponent(component)`.
+2.  **Creation (Shadow):** The `ComponentContext` sends a message to the Kernel describing the new component. The Kernel creates an `Entity` node.
+3.  **Instantiation:** The Kernel resolves the Token and creates the associated Shadow Object(s).
+4.  **Active:** The Shadow Object runs its logic, sets up signals, and reacts to changes.
+5.  **Unmount (View Layer):** The View Component is disposed.
+    *   *Web Components:* `<shae-ent>` disconnects and calls `component.destroy()`.
+    *   *Manual:* You call `component.destroy()` or `context.destroyComponent(component)`.
+6.  **Destruction (Shadow):** The Kernel destroys the `Entity` and triggers the cleanup of all associated Shadow Objects.
+
+## The Shadow Object Lifecycle
+
+Shadow Objects are functional units. Their lifecycle is simple: **Setup** and **Teardown**.
+
+### 1. Setup Phase (The Function Body)
+The code inside your function (or constructor) runs **once** when the object is instantiated. This is where you connect your logic to the framework.
+
+*   **Goal:** Define your reactive graph.
+*   **Actions (The ShadowObjectCreationAPI):**
+
+    *   **Inputs (Properties):**
+        *   `useProperty(name)`: Create a reactive signal for a single property.
+        *   `useProperties(map)`: Create signals for multiple properties at once.
+    *   **Context (Dependency Injection):**
+        *   `useContext(name)`: Consume a context value from the nearest ancestor provider.
+        *   `useParentContext(name)`: Consume a context value starting from the parent (skipping self).
+        *   `provideContext(name, value)`: Provide a value to descendants.
+        *   `provideGlobalContext(name, value)`: Provide a value globally to all entities.
+    *   **Reactivity:**
+        *   `createSignal(initial)`: Create a local state signal.
+        *   `createEffect(fn)`: Create a side effect that runs when dependencies change.
+        *   `createMemo(fn)`: Create a derived signal (computed value).
+        *   `createResource(factory, cleanup)`: Manage an external resource (like a 3D object) with lifecycle management.
+    *   **Events:**
+        *   `on(target, event, callback)`: Listen for events (from View or other objects).
+        *   `once(target, event, callback)`: Listen for an event exactly once.
+    *   **Lifecycle:**
+        *   `onDestroy(callback)`: Register a cleanup function to run when the object is destroyed.
+    *   **Access:**
+        *   `entity`: Direct access to the underlying `EntityApi` (advanced usage).
+
+```typescript
+export function MyLogic({ 
+  useProperty, 
+  createEffect, 
+  createSignal,
+  on, 
+  entity, // Access to the entity instance
+  onDestroy 
+}) {
+  // SETUP: Runs once
+  const title = useProperty('title');
+  const [count, setCount] = createSignal(0);
+  
+  createEffect(() => {
+    // RUNTIME: Runs whenever 'title' or 'count' changes
+    console.log(`Title: ${title()}, Count: ${count()}`);
+  });
+
+  // SETUP: Listen for View events
+  // Events dispatched from the View are received on the entity instance as 'onViewEvent'.
+  // The first argument is the type (name) of the event, the second is the data.
+  on(entity, 'onViewEvent', (type, data) => {
+      if (type === 'click') {
+          setCount(c => c + 1);
+          console.log('View was clicked!', data);
+      }
+  });
+
+  onDestroy(() => {
+    // TEARDOWN: Runs once when destroyed
+    console.log('Cleaning up...');
+  });
+}
+```
+
+### 2. Runtime Phase (Reactivity & Events)
+After setup, the Shadow Object is "alive". It doesn't re-run the main function. Instead, it reacts to changes in the environment.
+
+#### A. Reactive Updates
+Effects and Computed values (Memos) re-run whenever their dependencies change.
+*   **Drivers:** Property updates (from View), Context updates (from Parent), or internal Signal changes.
+
+#### B. Event Flow
+The Runtime phase is also driven by **Events**, which can flow in multiple directions:
+
+1.  **View → Entity:** The View Layer triggers standard DOM events (like `click`, `input`) or custom events. These are sent to the Entity as events.
+    *   **Mechanism:** The `ViewComponent` captures the DOM event and sends a message to the Shadow World.
+    *   **Reaction:** The Shadow Object listens to these events on the `entity` instance using `on(entity, 'onViewEvent', (type, data) => ... )`. The specific event name (e.g., 'click') is passed as the first argument.
+2.  **Entity → View:** The Shadow Object can emit events. The View Layer receives these messages and can trigger UI updates (e.g., navigation, playing sound).
+3.  **Entity Tree (Inter-Object):** Shadow Objects can communicate with each other via events. Because Entities form a tree, events can be dispatched through the hierarchy, allowing decoupled communication between logic units (e.g. a child item signaling a selection to a parent list).
+
+### 3. Teardown Phase (Cleanup)
+When the Entity is destroyed (or if the specific route that created this object is disabled), the Teardown phase begins.
+
+*   **Automatic:** All framework-managed signals, effects, and event listeners (`createEffect`, `on`) are automatically disposed of.
+*   **Manual:** Use `onDestroy` to clean up *external* resources, such as:
+    *   `setInterval` / `setTimeout`
+    *   Global event listeners (e.g. on `window`)
+    *   WebSockets or network connections
+
+> [!WARNING]
+> **Memory Leaks:** Always ensure you clean up non-framework resources in `onDestroy`. Failing to clear a `setInterval` will keep the closure alive indefinitely!