refactor: update dispatchMessageToView usage across the codebase

Author: spearwolf

packages/shadow-objects-e2e/public/mod-hello.js

@@ -1,14 +1,14 @@
-function foo({entity, useProperty}) {
+function foo({useProperty, dispatchMessageToView}) {
   const xyz = useProperty('xyz');
 
   console.log('ShadowObject "foo" created: xyz=', xyz());
 
   xyz((val) => {
     console.log('foo.xyz changed to', val);
-    entity.dispatchMessageToView('fooEcho', xyz());
+    dispatchMessageToView('fooEcho', xyz());
   });
 
-  entity.dispatchMessageToView('helloFromFoo', {xyz: xyz()});
+  dispatchMessageToView('helloFromFoo', {xyz: xyz()});
 }
 
 export const shadowObjects = {

packages/shadow-objects/CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - sharpen the `EntityApi` type definitions
 
+## [0.27.0] - 2026-01-19
+
+### ⚠️ Breaking Changes
+
+- **API Update:** `dispatchMessageToView` has been moved from the `entity` instance to the `ShadowObjectCreationAPI`.
+    - **Before:** `entity.dispatchMessageToView(...)`
+    - **After:** `dispatchMessageToView(...)` (available as an argument in the constructor/factory function)
+- **Type Definitions:** Removed `dispatchMessageToView` from `EntityApi` interface.
+
 ## [0.26.4] - 2026-01-15
 
 - fix return type definitions for `provideContext()` and `provideGlobalContext()`

packages/shadow-objects/docs/02-guides/01-getting-started.md

@@ -140,7 +140,7 @@ export default {
     *   `CounterLogic` receives `onViewEvent`.
     *   `setCount` updates the signal.
     *   `createEffect` runs.
-    *   **Events:** The Shadow Object uses `entity.dispatchMessageToView` to communicate back (see View Integration).
+    *   **Events:** The Shadow Object uses `dispatchMessageToView` to communicate back (see View Integration).
 
 ## Next Steps
 

packages/shadow-objects/docs/02-guides/02-creating-shadow-objects.md

@@ -108,12 +108,12 @@ createEffect(() => {
 To update the **View Component**, you should use events. This keeps the data flow unidirectional and explicit.
 
 ```typescript
-export function CounterLogic({ entity, createSignal, createEffect }) {
+export function CounterLogic({ createSignal, createEffect, dispatchMessageToView }) {
   const [count, setCount] = createSignal(0);
 
   // Notify View of changes
   createEffect(() => {
-    entity.dispatchMessageToView('count-changed', { value: count() });
+    dispatchMessageToView('count-changed', { value: count() });
   });
 }
 ```
@@ -139,7 +139,7 @@ on(entity, 'onViewEvent', (type, data) => {
 You can also send events *up* to the View.
 
 ```typescript
-entity.dispatchMessageToView('loginSuccess', { user: 'Alice' });
+dispatchMessageToView('loginSuccess', { user: 'Alice' });
 ```
 
 In the View Layer, you would listen for this event on the component.

packages/shadow-objects/docs/02-guides/03-view-integration.md

@@ -76,7 +76,7 @@ The Shadow Object receives this via `on(entity, 'onViewEvent', ...)`.
 
 ### Receiving Events from Shadow World
 
-When a Shadow Object calls `entity.dispatchMessageToView('my-event', data)`, the `<shae-ent>` element dispatches a CustomEvent.
+When a Shadow Object calls `dispatchMessageToView('my-event', data)`, the `<shae-ent>` element dispatches a CustomEvent.
 
 ```javascript
 ent.addEventListener('my-event', (e) => {
@@ -90,7 +90,7 @@ To update the UI based on state changes in the Shadow Object, you should emit ev
 // Shadow Object
 createEffect(() => {
    // Whenever count changes, notify the view
-   entity.dispatchMessageToView('count-changed', { value: count() });
+   dispatchMessageToView('count-changed', { value: count() });
 });
 ```
 
@@ -100,7 +100,7 @@ To update the UI based on state changes in the Shadow Object, you should emit ev
 // Shadow Object
 createEffect(() => {
    // Whenever count changes, notify the view
-   entity.dispatchMessageToView('count-changed', { value: count() });
+   dispatchMessageToView('count-changed', { value: count() });
 });
 
 // View Layer

packages/shadow-objects/docs/03-api/01-shadow-object-api.md

@@ -161,35 +161,50 @@ Same as `on`, but the listener is automatically removed after the first trigger.
 
 ---
 
-## 5. Lifecycle
+## 5. View Integration
 
-### `onDestroy(callback)`
+Shadow Objects can communicate directly with the View Layer (the DOM) by dispatching messages.
 
-Registers a cleanup function. This is critical for preventing memory leaks when using non-framework resources (like `setInterval`).
+### `dispatchMessageToView(type, data?, transferables?, traverseChildren?)`
 
-*   **Signature:** `onDestroy(fn: () => void): void`
+Sends an event **from** the Shadow World **to** the View Layer. The `<shae-ent>` DOM element will dispatch a `CustomEvent`.
+
+*   **Signature:** `dispatchMessageToView(type: string, data?: unknown, transferables?: Transferable[], traverseChildren?: boolean): void`
+
+**Parameters:**
+*   `type`: The name of the custom event to dispatch on the `<shae-ent>` element.
+*   `data`: (Optional) Data to send as `event.detail`.
+*   `transferables`: (Optional) Array of transferable objects (like `ArrayBuffer`, `MessagePort`) to transfer ownership of, instead of cloning.
+*   `traverseChildren`: (Optional) If `true`, the event will be dispatched to the corresponding view component and all its descendants in the view hierarchy. Defaults to `false`.
 
 ```typescript
-const interval = setInterval(tick, 1000);
-onDestroy(() => clearInterval(interval));
+// Shadow World
+dispatchMessageToView('login-success', { user: 'Alice' });
+
+// View Layer (DOM)
+el.addEventListener('login-success', (e) => console.log(e.detail.user));
 ```
 
 ---
 
-## 6. The `entity` Instance
+## 6. Lifecycle
 
-The API provides direct access to the underlying `EntityApi` instance via the `entity` property.
 
-### `entity.dispatchMessageToView(type, detail)`
+### `onDestroy(callback)`
 
-Sends an event **from** the Shadow World **to** the View Layer. The `<shae-ent>` DOM element will dispatch a `CustomEvent`.
+Registers a cleanup function. This is critical for preventing memory leaks when using non-framework resources (like `setInterval`).
 
-*   **Signature:** `entity.dispatchMessageToView(type: string, detail?: any): void`
+*   **Signature:** `onDestroy(fn: () => void): void`
 
 ```typescript
-// Shadow World
-entity.dispatchMessageToView('login-success', { user: 'Alice' });
-
-// View Layer (DOM)
-el.addEventListener('login-success', (e) => console.log(e.detail.user));
+const interval = setInterval(tick, 1000);
+onDestroy(() => clearInterval(interval));
 ```
+
+---
+
+## 7. The `entity` Instance
+
+The API provides direct access to the underlying `EntityApi` instance via the `entity` property. This gives access to entity metadata like `uuid`, `order`, hierarchy info (`parent`, `children`), and property inspection (`propKeys`, `propEntries`).
+
+Note: `dispatchMessageToView` is now a top-level method on the API object and is no longer available on the `entity` instance.

packages/shadow-objects/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spearwolf/shadow-objects",
   "description": "a reactive entity-component framework that feels at home in the shadows",
-  "version": "0.26.4",
+  "version": "0.27.0",
   "author": {
     "name": "Wolfger Schramm",
     "email": "wolfger@spearwolf.de",

packages/shadow-objects/src/in-the-dark/Kernel.spec.ts

@@ -166,17 +166,29 @@ describe('Kernel', () => {
   });
 
   describe('MessageToView with traverseChildren', () => {
+    const registry = new Registry();
+
+    // Helper class to expose dispatchMessageToView for testing
+    @ShadowObject({registry, token: 'test'})
+    class TestDispatcher {
+      dispatchMessageToView: ShadowObjectCreationAPI['dispatchMessageToView'];
+      constructor({dispatchMessageToView}: ShadowObjectCreationAPI) {
+        this.dispatchMessageToView = dispatchMessageToView;
+      }
+    }
+    expect(TestDispatcher).toBeDefined();
+
     it('should emit MessageToView event with traverseChildren=false by default', async () => {
-      const kernel = new Kernel();
+      const kernel = new Kernel(registry);
       const uuid = generateUUID();
 
       kernel.createEntity(uuid, 'test');
-      const entity = kernel.getEntity(uuid);
+      const so = kernel.findShadowObjects(uuid)[0] as any;
 
       const messageToViewSpy = vi.fn();
       on(kernel, MessageToView, messageToViewSpy);
 
-      entity.dispatchMessageToView('testType', {payload: 'data'});
+      so.dispatchMessageToView('testType', {payload: 'data'});
 
       // Wait for queueMicrotask to complete
       await new Promise((resolve) => queueMicrotask(() => resolve(undefined)));
@@ -193,16 +205,16 @@ describe('Kernel', () => {
     });
 
     it('should emit MessageToView event with traverseChildren=true when specified', async () => {
-      const kernel = new Kernel();
+      const kernel = new Kernel(registry);
       const uuid = generateUUID();
 
       kernel.createEntity(uuid, 'test');
-      const entity = kernel.getEntity(uuid);
+      const so = kernel.findShadowObjects(uuid)[0] as any;
 
       const messageToViewSpy = vi.fn();
       on(kernel, MessageToView, messageToViewSpy);
 
-      entity.dispatchMessageToView('broadcastEvent', {message: 'hello'}, undefined, true);
+      so.dispatchMessageToView('broadcastEvent', {message: 'hello'}, undefined, true);
 
       // Wait for queueMicrotask to complete
       await new Promise((resolve) => queueMicrotask(() => resolve(undefined)));
@@ -219,17 +231,17 @@ describe('Kernel', () => {
     });
 
     it('should emit MessageToView with transferables', async () => {
-      const kernel = new Kernel();
+      const kernel = new Kernel(registry);
       const uuid = generateUUID();
 
       kernel.createEntity(uuid, 'test');
-      const entity = kernel.getEntity(uuid);
+      const so = kernel.findShadowObjects(uuid)[0] as any;
 
       const messageToViewSpy = vi.fn();
       on(kernel, MessageToView, messageToViewSpy);
 
       const buffer = new ArrayBuffer(8);
-      entity.dispatchMessageToView('dataEvent', {buffer}, [buffer], false);
+      so.dispatchMessageToView('dataEvent', {buffer}, [buffer], false);
 
       // Wait for queueMicrotask to complete
       await new Promise((resolve) => queueMicrotask(() => resolve(undefined)));

packages/shadow-objects/src/in-the-dark/Kernel.ts

@@ -517,6 +517,10 @@ export class Kernel {
           return ctxReader;
         },
 
+        dispatchMessageToView(type: string, data?: unknown, transferables?: Transferable[], traverseChildren = false) {
+          entry.entity.dispatchMessageToView(type, data, transferables, traverseChildren);
+        },
+
         useProperty: getUseProperty,
 
         useProperties<K extends string>(props: Record<K, string>): Record<K, SignalReader<any>> {

packages/shadow-objects/src/types.ts

@@ -86,7 +86,7 @@ export interface AppliedChangeTrailEvent {
 }
 
 export type EntityApi = Readonly<
-  Pick<Entity, 'uuid' | 'order' | 'hasParent' | 'dispatchMessageToView' | 'propKeys' | 'propEntries'> & {
+  Pick<Entity, 'uuid' | 'order' | 'hasParent' | 'propKeys' | 'propEntries'> & {
     parent?: EntityApi;
     children: readonly EntityApi[];
     traverse(callback: (entity: EntityApi) => unknown): void;
@@ -106,6 +106,8 @@ export type Maybe<T = unknown> = NonNullable<T> | undefined;
 export interface ShadowObjectCreationAPI {
   entity: EntityApi;
 
+  dispatchMessageToView(type: string, data?: unknown, transferables?: TransferablesType, traverseChildren?: boolean): void;
+
   provideContext<T = unknown>(
     name: string | symbol,
     sourceOrInitialValue?: T | SignalReader<T | undefined>,