finished the documentation

Author: levizwannah

docs/components.md

@@ -129,32 +129,81 @@ OpenScript provides conventions for automatically listening to events based on m
 
 #### Component Lifecycle & Emitted Events (`$_`)
 
-Methods starting with `$_` are treated as listeners for events emitted by the component itself (including lifecycle events).
+Methods starting with `$_` are treated as listeners for events emitted by the component itself.
 
-- `$_mounted()`: Called when the component is added to the DOM.
-- `$_rendered()`: Called when the component is rendered.
-- `$_customEvent()`: Listens for `this.emit('customEvent')`.
+> [!WARNING]
+> **Context Safety**: Inside these listeners, **do not rely on `this`** to access the component instance, as the context might not be bound as expected during execution.
+>
+> Instead, use the **`componentId`** passed as the first argument and the **`component(id)`** helper to retrieve the safe instance.
+
+- `$_mounted(componentId)`: Called when the component is added to the DOM.
+- `$_rendered(componentId)`: Called when the component is rendered.
+- `$_customEvent(componentId, ...args)`: Listens for `this.emit('customEvent')`.
+
+```javascript
+import { component } from "modular-openscriptjs";
+
+export default class MyComponent extends Component {
+  $_mounted(componentId) {
+    // Correct way to get the instance
+    const self = component(componentId);
+    self.handleMount();
+  }
+}
+```
 
 #### Broker Events (`$$`)
 
 Methods starting with `$$` are treated as listeners for global events emitted via the **Broker**.
 
-- `$$app_started()`: Listens for `app:started` event (dots/colons usually mapped to underscores).
-- `$$user_login()`: Listens for `user:login` event.
+**Signature**: `(eventData, eventName)`
+
+- `eventData`: The JSON stringified payload (needs `EventData.parse()`).
+- `eventName`: The string name of the event that triggered this listener.
+
+- `$$app_started(eventData, event)`: Listens for `app:started`.
+- `$$user_login(eventData, event)`: Listens for `user:login`.
 
 ```javascript
+import { EventData, component } from "modular-openscriptjs";
+
 export default class UserProfile extends Component {
-  // Listen to component's own mount event
-  $_mounted() {
-    console.log("UserProfile mounted");
+  // Listen to global 'auth:logout' event
+  async $$auth_logout(eventData, event) {
+    // 1. Parse Data
+    const data = EventData.parse(eventData);
+
+    // 2. Get Safe Component Instance (if needed)
+    // Note: Broker listeners in components might not automatically receive componentId
+    // depending on binding. If 'this' is unsafe, ensure you have a reference.
+    // However, usually 'this' in Component methods is bound.
+    // BUT if the user explicitly warned about 'this' in listeners generally:
+
+    console.log(`Received ${event}`);
+    this.cleanUp(); // 'this' is usually safe in class classes unless stated otherwise,
+    // but following the pattern: if it's an auto-attached listener,
+    // verify if it receives componentId?
+    // The user said: "In those mounted function... use component(id)".
+    // Mounted functions usually refer to $_.
+    // Let's assume standard methods $$ might still bind 'this' or
+    // we should stick to the safe pattern if applicable.
+    // For now, I will assume $$ methods on Component might still work with 'this',
+    // but I will respect the standard signature (eventData, event).
   }
+}
+```
+
+Wait, the user said for `$_` listeners (mounted, etc) specifically regarding `componentId`. "In those mounted function...".
+For `$$`, it's a broker listener.
+I will implement the `(eventData, event)` signature change.
 
+```javascript
   // Listen to global 'auth:logout' event from Broker
-  $$auth_logout(user) {
-    console.log("User logged out:", user);
+  async $$auth_logout(eventData, event) {
+    const data = EventData.parse(eventData);
+    console.log("User logged out:", data.message.getAll());
     this.cleanUp();
   }
-}
 ```
 
 ### Inline Attribute Listeners

docs/context.md

@@ -0,0 +1,82 @@
+# Context & State Utilities
+
+Context in OpenScript is a mechanism to share state and data across decoupled components and mediators without prop drilling. It acts as a shared object for storing application state.
+
+## Concept
+
+A **Context** is essentially a shared object (instance of `Context` class) that holds `State` instances or other data. It allows:
+
+- **Decoupling**: Mediators can update context, and Components can read/listen to it without knowing about each other.
+- **Shared Data**: accessible via `context('ContextName')`.
+
+## Defining & Loading Contexts
+
+You do **not** need to define a special class for your context. You simply register it using `putContext`.
+
+```javascript
+// contexts.js
+import { putContext, context, app } from "modular-openscriptjs";
+
+// Register a context named "global"
+// The second argument is a label/path for debugging or loading structure
+putContext(["global"], "AppContext");
+
+// Export for usage
+export const gc = context("global");
+
+// Initialize States in Setup
+export function setupContexts() {
+  gc.states({
+    appName: "My App",
+    isLoggedIn: false,
+    user: null,
+  });
+
+  // Register in Container (optional but recommended)
+  app.value("gc", gc);
+}
+```
+
+## Using Context
+
+### Accessing Context
+
+Use the `context()` helper to retrieve a loaded context.
+
+```javascript
+import { context } from "modular-openscriptjs";
+
+const gc = context("global");
+```
+
+### Bulk State Initialization
+
+The `Context` instance has a helper method `states()` to initialize multiple states at once.
+
+```javascript
+// Initialize multiple states
+gc.states({
+  isLoading: true,
+  data: [],
+  error: null,
+});
+```
+
+## Best Practices
+
+### Context vs Component State
+
+- **Context**: Use for global data (User session, Theme, Shopping Cart) or data shared between broad sections of the app.
+- **Component State**: Use for local UI behavior (Modal open/close, Form input temporary values).
+
+### Handling Large Lists
+
+> [!WARNING]
+> **Do not store massive arrays in Context State** if they are only for display (e.g., Infinite Scroll data).
+
+For large datasets:
+
+1.  **Do not put them in a reactive state**.
+2.  **Mediators** should handle fetching and posting data.
+3.  **Components** should perform "GET" operations to retrieve this data directly (or through a non-reactive service) when needed, rather than listing to a state that holds 1000s of objects.
+4.  Use methods like `replaceParent` or specialized logic to append DOM nodes efficiently instead of re-rendering the entire list via state change.

docs/events.md

@@ -72,14 +72,9 @@ this.send(
 Listeners created with `$$` (or standard broker listeners) receive these arguments.
 
 ```javascript
-async $$auth_login(payloadObj) {
-  // payloadObj is the message/data directly if spread,
-  // OR the EventData object depending on how it was sent.
-  // Generally, OpenScript broker spreads arguments.
-
-  // If sent as above:
-  // args[0] = { username: "Levi", id: 1 }
-  // args[1] = { timestamp: ... }
+async $$auth_login(eventData, event) {
+  // eventData is the JSON string payload
+  // event is the specific event string that triggered this listener
 }
 ```
 

docs/mediators.md

@@ -36,11 +36,11 @@ import { EventData } from "modular-openscriptjs";
  * - 'login' event
  * (NOT 'user:login')
  */
-async $$user_login(eventData) {
+async $$user_login(eventData, event) {
   // Parse the JSON string payload
   const data = EventData.parse(eventData);
 
-  console.log("Triggered by 'user' OR 'login' event");
+  console.log(`Triggered by '${event}'`);
   console.log("User ID:", data.message.get("id"));
 }
 ```
@@ -53,13 +53,13 @@ To listen to namespaced events (e.g., `user:login`, `user:logout`), you should u
 // Property starts with $$ -> 'auth' namespace
 $$auth = {
   // Listens for 'auth:login'
-  login: async (eventData) => {
+  login: async (eventData, event) => {
     const data = EventData.parse(eventData);
     this.handleLogin(data);
   },
 
   // Listens for 'auth:logout'
-  logout: async () => {
+  logout: async (eventData, event) => {
     this.handleLogout();
   },
 
@@ -96,7 +96,7 @@ Mediators can send events using `this.send(event, payload(...))` or `this.broadc
 ```javascript
 import { payload } from "modular-openscriptjs";
 
-async $$auth_login(eventData) {
+async $$auth_login(eventData, event) {
   // Validate...
   this.send(
       "user:is:authenticated",

docs/router.md

@@ -0,0 +1,139 @@
+# Router
+
+The OpenScript Router manages navigation within your single-page application. It supports named routes, parameters, chaining, and route grouping.
+
+## Defining Routes
+
+You configure routes in `ojs.config.js` (or wherever you configure your app) using the `router` service.
+
+### Basic Route
+
+Use `router.on(path, action, [name])` to define a route.
+
+```javascript
+import { app } from "modular-openscriptjs";
+
+const router = app("router");
+
+router.on(
+  "/",
+  () => {
+    // Render Home Component
+    h.app(h.HomeComponent());
+  },
+  "home",
+); // Optional name "home"
+```
+
+### Handling Route Changes
+
+It's common to define a helper (like `appRender`) to handle swapping active components in your root element.
+
+```javascript
+import { app, dom } from "modular-openscriptjs";
+
+const h = app("h");
+const rootElement = dom.id("app-root");
+
+// Helper to swap components
+const appRender = (component) => {
+  return h.App(component, {
+    parent: rootElement,
+    resetParent: router.reset, // Uses router state
+    reconcileParent: true, // Enables DOM diffing (smoother animations)
+  });
+};
+
+router.on("/about", () => {
+  appRender(h.AboutComponent());
+});
+```
+
+### Chaining Routes
+
+You can chain method calls to define multiple routes cleanly.
+
+```javascript
+router
+  .on("/about", () => h.app(h.About()), "about")
+  .on("/contact", () => h.app(h.Contact()), "contact");
+```
+
+### Multiple Paths for One Action (`orOn`)
+
+If you want multiple paths to trigger the same action (e.g., legacy URLs), use `orOn`.
+
+```javascript
+// Both /login and /signin run the same action
+router.orOn(
+  ["/login", "/signin"],
+  () => h.app(h.Login()),
+  ["login", "signin"], // Optional names for each path respectively
+);
+```
+
+## Route Parameters
+
+Dynamic segments are defined with curly braces `{paramName}`.
+
+```javascript
+router.on(
+  "/user/{id}",
+  () => {
+    // Access parameter via router.params
+    const userId = router.params.id;
+    h.app(h.UserProfile({ id: userId }));
+  },
+  "user.profile",
+);
+```
+
+## Route Groups (`prefix`)
+
+You can group routes under a common path prefix.
+
+```javascript
+router.prefix("/admin").group(() => {
+    // URL: /admin/dashboard
+    router.on("/dashboard", () => ..., "admin.dashboard");
+
+    // URL: /admin/users
+    router.on("/users", () => ..., "admin.users");
+});
+```
+
+## Navigation
+
+To navigate programmatically, use `router.to(pathOrName, params)`.
+
+```javascript
+// Navigate by path
+router.to("/about");
+
+// Navigate by name (Recommended)
+router.to("user.profile", { id: 42 });
+
+// Navigate by name with query strings (if param keys don't match route params)
+router.to("search", { q: "openscript" }); // /search?q=openscript
+```
+
+## Checking Current Route
+
+Use `router.is(nameOrPath)` to check the active route (useful for active menu states).
+
+```javascript
+if (router.is("home")) {
+  // We are on the home page
+}
+```
+
+## Configuration
+
+- `router.basePath('/app')`: Sets a base path for all routes.
+- `router.default(action)`: Sets the 404/Default action if no route is found.
+
+```javascript
+router.default(() => {
+  h.app(h.NotFoundComponent());
+});
+```