refactor: replace @thread decorator with ensemble.json configuration

Replace the @thread decorator with a declarative ensemble.json configuration
file for defining threading topology. This provides better visibility,
tooling support, and clearer project structure.

Changes:
- Remove @thread decorator and related metadata functions
- Add ensemble.json configuration with actor-to-thread mappings
- Create config loader with validation for ensemble.json
- Add JSON schema for IDE autocomplete and validation
- Update ActorSystem to use config-based thread assignment
- Update Vite plugin to generate worker bundles from config
- Separate dev/build bundling strategies in Vite plugin
- Add on-demand worker bundling for dev mode via middleware

Breaking changes:
- @thread decorator no longer supported
- Projects must create ensemble.json to define worker threads
- ActorSystem constructor now accepts optional EnsembleConfig

Author: d-buckner

README.md

@@ -68,8 +68,19 @@ npm install @d-buckner/ensemble-collaboration
 ```typescript
 import { createActorToken, ActorSystem, Actor, action } from '@d-buckner/ensemble-core';
 
-// 1. Define an actor
-class CounterActor extends Actor {
+// 1. Define actor interfaces
+interface CounterState {
+  count: number;
+}
+
+interface CounterActions {
+  increment(): void;
+}
+
+interface CounterEvents {}
+
+// 2. Define an actor
+class CounterActor extends Actor<CounterState, CounterActions, CounterEvents> {
   state = { count: 0 };
 
   @action
@@ -78,14 +89,14 @@ class CounterActor extends Actor {
   }
 }
 
-// 2. Create a token and system
+// 3. Create a token and system
 const CounterToken = createActorToken<CounterActor>('counter');
 const system = new ActorSystem();
 
 system.register({ token: CounterToken, actor: CounterActor });
 await system.start();
 
-// 3. Use the actor
+// 4. Use the actor
 const counter = system.get(CounterToken);
 counter.on('stateChanged', (state) => console.log(state));
 counter.actions.increment(); // { count: 1 }

demos/react/collaboration/src/actors/TodosActor.ts

@@ -6,8 +6,15 @@ export interface TodoDoc {
   todos: Array<{ id: string; text: string; done: boolean }>;
 }
 
+// Define actions
+export interface TodosActions {
+  addTodo(text: string): void;
+  toggleTodo(id: string): void;
+  removeTodo(id: string): void;
+}
+
 // Extend CollaborationActor with domain actions
-export class TodosActor extends CollaborationActor<TodoDoc> {
+export class TodosActor extends CollaborationActor<TodoDoc, TodosActions> {
   protected declare deps: CollaborationDeps;
   static readonly initialState: TodoDoc = {
     todos: []

demos/react/counter/ensemble.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../../ensemble.schema.json",
+  "threads": {
+    "counter": {
+      "actors": [
+        {
+          "path": "./src/actors/CounterActor.ts",
+          "name": "CounterActor"
+        }
+      ]
+    }
+  }
+}

demos/react/counter/src/actors/CounterActor.ts

@@ -1,12 +1,17 @@
-import { Actor, action, thread } from '@d-buckner/ensemble-core';
+import { Actor, action } from '@d-buckner/ensemble-core';
 
 
 export interface CounterState {
   count: number;
 }
 
-@thread('counter')
-export class CounterActor extends Actor<CounterState> {
+export interface CounterActions {
+  increment(): void;
+  decrement(): void;
+  reset(): void;
+}
+
+export class CounterActor extends Actor<CounterState, CounterActions> {
   static readonly initialState: CounterState = { count: 0 };
 
   constructor() {

demos/react/counter/src/index.tsx

@@ -5,10 +5,12 @@ import { createRoot } from 'react-dom/client';
 import { CounterActor } from './actors/CounterActor';
 import { App } from './App';
 import { CounterToken } from './tokens';
+import ensembleConfig from '../ensemble.json';
 
 
 async function main() {
-  const system = new ActorSystem();
+  // Load thread configuration from ensemble.json
+  const system = new ActorSystem(ensembleConfig);
 
   system.register({
     token: CounterToken,

demos/solidjs/counter/src/actors/CounterActor.ts

@@ -5,7 +5,13 @@ export interface CounterState extends Record<string, unknown> {
   count: number;
 }
 
-export class CounterActor extends Actor<CounterState> {
+export interface CounterActions {
+  increment(): void;
+  decrement(): void;
+  reset(): void;
+}
+
+export class CounterActor extends Actor<CounterState, CounterActions> {
   static readonly initialState: CounterState = { count: 0 };
 
   constructor() {

demos/solidjs/metrics-dashboard/ensemble.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "../../../ensemble.schema.json",
+  "threads": {
+    "worker-1": {
+      "actors": [
+        {
+          "path": "./src/actors/MetricGeneratorActor.ts",
+          "name": "MetricGeneratorActor"
+        },
+        {
+          "path": "./src/actors/StatisticsActor.ts",
+          "name": "StatisticsActor"
+        }
+      ]
+    },
+    "worker-2": {
+      "actors": [
+        {
+          "path": "./src/actors/AnomalyDetectionActor.ts",
+          "name": "AnomalyDetectionActor"
+        }
+      ]
+    }
+  }
+}

demos/solidjs/metrics-dashboard/src/actors/AnomalyDetectionActor.ts

@@ -1,4 +1,4 @@
-import { Actor, effect, thread } from '@d-buckner/ensemble-core';
+import { Actor, effect } from '@d-buckner/ensemble-core';
 import type { StatisticsActor, ProcessedBatch, ProcessedMetrics } from './StatisticsActor';
 import type { IActorClient } from '@d-buckner/ensemble-core';
 
@@ -18,6 +18,8 @@ export interface AnomalyDetectionState {
   recentAnomalies: Anomaly[];
 }
 
+export interface AnomalyDetectionActions {}
+
 export interface AnomalyDetectionEvents {
   latestAnomaly: Anomaly;
 }
@@ -35,8 +37,7 @@ interface AnomalyDetectionDeps {
  * - Historical state tracking for trend detection
  * - Reactive event communication
  */
-@thread('worker-2')
-export class AnomalyDetectionActor extends Actor<AnomalyDetectionState, AnomalyDetectionEvents> {
+export class AnomalyDetectionActor extends Actor<AnomalyDetectionState, AnomalyDetectionActions, AnomalyDetectionEvents> {
   static readonly initialState: AnomalyDetectionState = {
     isMonitoring: false,
     anomaliesDetected: 0,

demos/solidjs/metrics-dashboard/src/actors/DashboardActor.ts

@@ -24,6 +24,8 @@ export interface DashboardState {
   windowSize: number; // Number of data points to keep
 }
 
+export interface DashboardActions {}
+
 interface DashboardDeps {
   StatisticsActor: ActorClient<StatisticsActor>;
   AnomalyDetectionActor: ActorClient<AnomalyDetectionActor>;
@@ -40,7 +42,7 @@ interface DashboardDeps {
  *
  * Runs on MAIN THREAD for direct UI access
  */
-export class DashboardActor extends Actor<DashboardState> {
+export class DashboardActor extends Actor<DashboardState, DashboardActions> {
   static readonly initialState: DashboardState = {
     chartData: {
       cpuSeries: [],

demos/solidjs/metrics-dashboard/src/actors/MetricGeneratorActor.ts

@@ -1,4 +1,4 @@
-import { Actor, action, thread } from '@d-buckner/ensemble-core';
+import { Actor, action } from '@d-buckner/ensemble-core';
 import { createNoise2D } from 'simplex-noise';
 
 
@@ -46,6 +46,14 @@ export interface MetricGeneratorState {
   throughput: number; // target metrics per second
 }
 
+export interface MetricGeneratorActions {
+  start(): void;
+  stop(): void;
+  setBatchSize(size: number): void;
+  setThroughput(throughput: number): void;
+  setPaused(paused: boolean): void;
+}
+
 export interface MetricGeneratorEvents {
   metricBatch: MetricBatch;
 }
@@ -58,8 +66,7 @@ export interface MetricGeneratorEvents {
  * - Complex data structure generation
  * - Continuous streaming
  */
-@thread('worker-1')
-export class MetricGeneratorActor extends Actor<MetricGeneratorState, MetricGeneratorEvents> {
+export class MetricGeneratorActor extends Actor<MetricGeneratorState, MetricGeneratorActions, MetricGeneratorEvents> {
   static readonly initialState: MetricGeneratorState = {
     isGenerating: false,
     batchesGenerated: 0,