intentx-solid 0.1.0 → 0.2.1-z1

package/README.md

@@ -6,7 +6,8 @@
 
 ---
 
-`intentx-solid` is an architectural layer for Solid.
+`intentx-solid` enforces a strict architectural boundary between deterministic business logic and reactive UI in Solid.
+
 It enforces a strict separation between:
 - Business Logic (deterministic runtime)
 - UI Rendering (fine-grained reactivity)
@@ -27,29 +28,26 @@ Use it when your UI starts to feel like business logic.
 
 Avoid it when:
 
-❌ You only need simple `createSignal`  
-❌ You want reducer-style state  
-❌ Your state is purely local UI  
+❌ This library introduces an architectural boundary.  
+❌ If you don’t need architectural boundaries, don’t use it.  
 
 ---
 
-## 🧠 Mental Model
+## 🧠  Mental Model
+
 ```txt
-    UI Event
-       ↓
-    emit(intent)
-       ↓
-    intent handler
-       ↓
-    setState
-       ↓
-    computed re-evaluates
-       ↓
-    Solid store updates
-       ↓
-    Fine-grained reactivity updates UI
+UI / HTTP / Queue / Cron
+        ↓
+  intentx-runtime
+        ↓
+Fine-grained reactivity updates UI
 ```
 
+Core principle:
+
+> Intent is the only mutation entry point.
+> The [runtime](https://www.npmjs.com/package/intentx-runtime) owns behavior. UI only triggers intent.
+
 ---
 
 ## 📦 Installation
@@ -62,8 +60,10 @@ npm install intentx-solid
 
 ## 🧩 Core Logic (Framework-Agnostic)
 
+Even though this is the React package, the runtime is fully usable without React.
+
 ``` ts
-import { createLogic } from "intentx-runtime"
+import { createLogic } from "intentx-solid"
 
 export const counterLogic = createLogic({
   name: "counter",
@@ -76,22 +76,20 @@ export const counterLogic = createLogic({
     double: ({ state }) => state.count * 2
   },
 
-  actions: ({ setState }) => ({
-    inc() {
-      setState(d => {
-        d.count++
-      })
-    }
-  })
-})
-```
-
----
-
-## 🔌 Solid Adapter
+  intents: (bus) => {
+    bus.on("inc", ({ setState }) => {
+      setState((s) => {
+        s.count++;
+      });
+    });
+  },
 
-``` ts
-export { useLogic }
+  actions: {
+    inc({ emit }) {
+      return () => emit("inc");
+    },
+  },
+})
 ```
 
 ---
@@ -104,11 +102,16 @@ import { counterLogic } from "./counter.logic"
 
 export default function Counter() {
   const counter = useLogic(counterLogic)
+  // const { actions, emit, store } = useLogic(counterLogic)
 
   return (
     <>
       <button onClick={counter.actions.inc}>
-        {counter.store.count}
+        {counter.state.count}
+      </button>
+
+      <button onClick={() => emit("inc")}>
+        {counter.state.count}
       </button>
 
       <p>Double: {counter.store.double}</p>
@@ -148,35 +151,91 @@ const counter = useLogic(counterLogic)
 
 ---
 
-## 📡 Scoped Bus
+## 📡  Multiple Logic Communication (Bus)
 
-``` ts
+Each `logic` instance is isolated by default.
+
+To enable communication between runtimes, you can share an Intent Bus.
+
+---
+
+### 1️⃣ Scoped Shared Bus (Recommended)
+
+```ts
+import { useLogic } from "intentx-solid"
+
+// ✅ Same scope → shared bus
+useLogic(logic, {
+  scope: "dashboard",
+  sharedBus: true
+})
+
+// ❌ Different scope → different bus
 useLogic(logic, {
+  scope: "settings",
   sharedBus: true
 })
 ```
 
-Scoped:
+<b>How it works</b>
 
-``` ts
+When sharedBus: true is enabled:
+
+- A singleton bus is created per scope
+
+- Same scope → same bus instance
+
+- Different scope → different bus
+
+- No global leakage
+
+If no `scope` is provided:
+
+```ts
 useLogic(logic, {
-  scope: "dashboard",
   sharedBus: true
 })
 ```
 
-Custom bus:
+→ uses a default global scope bus.
 
-``` ts
-import { createIntentBus } from "intentx-runtime"
+---
+
+### 2️⃣ Custom Bus (Advanced / Cross-Scope)
+
+```ts
+import { createIntentBus } from "intentx-react"
 
 const bus = createIntentBus()
 
-useLogic(logic, {
-  bus
-})
+useLogic(logicA, { bus })
+useLogic(logicB, { bus })
+
 ```
 
+<b>Behavior</b>
+
+- Full cross-scope communication
+- Manual orchestration control
+- Suitable for:
+  - Microfrontend
+  - App-wide coordination
+  - Complex workflow systems
+
+### 🔍 Behavior Comparison
+
+| Mode                 | Isolation    | Scope-aware | Cross-scope  | Recommended           |
+| -------------------- | -----------  | ----------- | ------------ | --------------------- |
+| Default (no options) | ✅ Full      | ❌           | ❌           | Small/local logic     |
+| `sharedBus: true`    | ❌ Per scope | ✅           | ❌           | Modular apps          |
+| Custom `bus`         | ❌ Manual    | ❌           | ✅           | Advanced architecture |
+
+### 🎯 Recommendation
+
+✅ Use sharedBus for modular communication.  
+✅ Use custom bus for orchestration layer.  
+🚫 Avoid global single bus without scope in large apps.  
+
 ---
 
 ## 🧩 Context API
@@ -248,13 +307,13 @@ That is the real split.
 
 ## 🔍 Comparison
 
-| Criteria               | Solid only  | intentx-solid |
-| ---------------------- | ----------- | ------------- |
-| Local UI state         | ✅          | ❌ Overkill    |
-| Async orchestration    | ⚠️ Manual   | ✅ Built-in    |
-| Cross-runtime reuse    | ❌          | ✅             |
-| Deterministic snapshot | ❌          | ✅             |
 
+| Criteria                | Solid primitives | intentx-solid |
+| ----------------------- | ---------------- | ------------- |
+| Local UI                | Excellent        | Overkill      |
+| Async orchestration     | Manual           | Structured    |
+| Cross-environment reuse | No               | Yes           |
+| Deterministic runtime   | No               | Yes           |
 
 
 - UI consumes state.
@@ -312,19 +371,18 @@ createEffect(async () => {
   }
 })
 ```
-
 And moving it here:
 
 ```ts
 // ✅ Logic outside UI
-actions: ({ setState }) => ({
-  async loadUser(id: string) {
+intents: (bus) => {
+  bus.on("loadUser", async ({ setState }) => {
     const data = await fetchUser(id)
     setState(d => {
       d.user = data
     })
-  }
-})
+  });
+}
 ```
 
 Now UI only emits intent.
@@ -341,6 +399,15 @@ intentx-solid ensures they never mix.
 
 ---
 
+## ❌ What This Is Not
+
+- Not a signal replacement
+- Not a store wrapper
+- Not a UI state helper
+- Not a reducer abstraction
+
+---
+
 ## 📜 License
 
 MIT

package/build/index.d.ts

@@ -1,4 +1,4 @@
-import { createIntentBus, LogicActions, LogicFactory, Scope } from 'intentx-runtime';
+import { createIntentBus, LogicActions, InferComputed, Scope, ComputedDef, LogicFactory } from 'intentx-runtime';
 export { EffectMode, ExtractLogicTypes, IntentContext, LogicActions, LogicFactory, LogicRuntime, createIntentBus, createLogic, effect } from 'intentx-runtime';
 import * as solid_js from 'solid-js';
 
@@ -6,13 +6,7 @@ type IntentBus = ReturnType<typeof createIntentBus>;
 declare function getGlobalBus(): IntentBus;
 declare function getScopedBus(scope?: string): IntentBus;
 
-type ComputedDef<S> = Record<string, (context: {
-    state: Readonly<S>;
-}) => any>;
-type InferComputed<C> = {
-    [K in keyof C]: C[K] extends (...args: any) => infer R ? R : never;
-};
-type LogicInstance<S, C, A extends LogicActions> = {
+type LogicApi<S, C, A extends LogicActions> = {
     runtime: any;
     store: Readonly<S & InferComputed<C>>;
     state: Readonly<S & InferComputed<C>>;
@@ -20,19 +14,20 @@ type LogicInstance<S, C, A extends LogicActions> = {
     emit: (...args: any[]) => Promise<void>;
 };
 
-declare function useLogic<S extends object, C extends ComputedDef<S>, A extends LogicActions>(logic: LogicFactory<S, C, A>, options?: {
+type LogicOptions = {
     scope?: Scope | string;
     sharedBus?: boolean;
-    bus?: ReturnType<typeof getScopedBus>;
-}): LogicInstance<S, C, A>;
+    bus?: IntentBus;
+};
+declare function useLogic<S extends object, C extends ComputedDef<S>, A extends LogicActions>(logic: LogicFactory<S, C, A>, options?: LogicOptions): LogicApi<S, C, A>;
 
-declare function setLogicContext<S extends object, C extends ComputedDef<S>, A extends LogicActions>(key: string, logic: LogicFactory<S, C, A>, options?: Parameters<typeof useLogic<S, C, A>>[1]): {
+declare function setLogicContext<S extends object, C extends ComputedDef<S>, A extends LogicActions>(key: string, logic: LogicFactory<S, C, A>, options?: LogicOptions): {
     Provider: (props: {
         children: any;
     }) => solid_js.JSX.Element;
-    store: LogicInstance<S, C, A>;
+    store: LogicApi<S, C, A>;
 };
 declare function useLogicContext<T>(key: string): T;
 
 export { getGlobalBus, getScopedBus, setLogicContext, useLogic, useLogicContext };
-export type { ComputedDef, InferComputed, IntentBus, LogicInstance };
+export type { IntentBus, LogicApi, LogicOptions };

package/build/logic/context.d.ts

@@ -1,10 +1,9 @@
-import type { LogicFactory, LogicActions } from "intentx-runtime";
-import { useLogic } from "./useLogic";
-import type { ComputedDef } from "./types";
-export declare function setLogicContext<S extends object, C extends ComputedDef<S>, A extends LogicActions>(key: string, logic: LogicFactory<S, C, A>, options?: Parameters<typeof useLogic<S, C, A>>[1]): {
+import type { LogicFactory, LogicActions, ComputedDef } from "intentx-runtime";
+import type { LogicOptions } from "./useLogic";
+export declare function setLogicContext<S extends object, C extends ComputedDef<S>, A extends LogicActions>(key: string, logic: LogicFactory<S, C, A>, options?: LogicOptions): {
     Provider: (props: {
         children: any;
     }) => import("solid-js").JSX.Element;
-    store: import("./types").LogicInstance<S, C, A>;
+    store: import("./types").LogicApi<S, C, A>;
 };
 export declare function useLogicContext<T>(key: string): T;

package/build/logic/types.d.ts

@@ -1,11 +1,5 @@
-import type { LogicActions } from "intentx-runtime";
-export type ComputedDef<S> = Record<string, (context: {
-    state: Readonly<S>;
-}) => any>;
-export type InferComputed<C> = {
-    [K in keyof C]: C[K] extends (...args: any) => infer R ? R : never;
-};
-export type LogicInstance<S, C, A extends LogicActions> = {
+import type { InferComputed, LogicActions } from "intentx-runtime";
+export type LogicApi<S, C, A extends LogicActions> = {
     runtime: any;
     store: Readonly<S & InferComputed<C>>;
     state: Readonly<S & InferComputed<C>>;

package/build/logic/useLogic.d.ts

@@ -1,8 +1,9 @@
-import type { Scope, LogicFactory, LogicActions } from "intentx-runtime";
-import { getScopedBus } from "./bus";
-import type { ComputedDef, LogicInstance } from "./types";
-export declare function useLogic<S extends object, C extends ComputedDef<S>, A extends LogicActions>(logic: LogicFactory<S, C, A>, options?: {
+import type { Scope, LogicFactory, LogicActions, ComputedDef } from "intentx-runtime";
+import type { IntentBus } from "./bus";
+import type { LogicApi } from "./types";
+export type LogicOptions = {
     scope?: Scope | string;
     sharedBus?: boolean;
-    bus?: ReturnType<typeof getScopedBus>;
-}): LogicInstance<S, C, A>;
+    bus?: IntentBus;
+};
+export declare function useLogic<S extends object, C extends ComputedDef<S>, A extends LogicActions>(logic: LogicFactory<S, C, A>, options?: LogicOptions): LogicApi<S, C, A>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intentx-solid",
-  "version": "0.1.0",
+  "version": "0.2.1-z1",
   "description": "Intent-driven logic adapter for SolidJS. Connects intentx-runtime with Solid's fine-grained reactivity.",
   "license": "MIT",
   "author": "Delpi.Kye",
@@ -46,29 +46,29 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "rollup -c",
+    "cb": "npm run clean && npm run build"
+  },
   "peerDependencies": {
     "solid-js": "^1.8.0"
   },
   "dependencies": {
-    "intentx-runtime": ">=0.2.2"
+    "intentx-runtime": "^0.2.4"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.0",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.3.0",
+    "rimraf": "^5.0.5",
     "rollup": "^4.9.6",
     "rollup-plugin-dts": "^6.3.0",
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "rollup-plugin-typescript2": "^0.36.0",
-    "rimraf": "^5.0.5",
     "tslib": "^2.6.2",
     "typescript": "^5.3.3",
     "unplugin-solid": "^1.0.0"
-  },
-  "scripts": {
-    "clean": "rimraf build",
-    "build": "rollup -c",
-    "cb": "npm run clean && npm run build"
   }
-}
+}