miolo 3.0.0-beta.227 → 3.0.0-beta.229

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miolo",
-  "version": "3.0.0-beta.227",
+  "version": "3.0.0-beta.229",
   "description": "all-in-one koa-based server",
   "author": "Donato Lorenzo <donato@afialapis.com>",
   "contributors": [

package/template/.agent/skills/miolo-caching/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: miolo-caching
+description: Advanced data caching and synchronization patterns for miolo applications. Use when handling useSsrData(), real-time data invalidation via WebSockets, or preventing abrupt UI re-renders using lazy refresh patterns.
+---
+
+# Miolo Caching & Sockets
+
+This skill covers how to efficiently cache data on the client using `useSsrData()`, keep it in sync across multiple clients via WebSockets, and ensure smooth UI experiences.
+
+## The `useSsrData()` Cache
+
+`useSsrData` handles both Server-Side Rendering (SSR) preloading and client-side data fetching. However, its true power comes from its caching capabilities and how it integrates with global application events.
+
+### Basic Invalidation
+
+When data changes on the server (e.g., a user adds a new Todo), you typically need to refresh the client's cache. 
+
+```javascript
+const [todos, setTodos, refreshTodos] = useSsrData('todos', [], loadTodos)
+
+// After a mutation:
+const handleAdd = async (newTodo) => {
+  await fetcher.post('/api/todos', newTodo)
+  // Manually refresh local data
+  refreshTodos() 
+}
+```
+
+## WebSocket Synchronization
+
+In multi-user apps, when User A updates a Todo, User B needs to see the change. Miolo uses WebSockets to broadcast invalidation messages.
+
+### The `exclude_socket_id` Pattern
+
+When User A makes a mutation, they generally update their UI optimistically or refresh their own data immediately. If the server broadcasts a blanket `refresh` to *everyone*, User A will suffer a redundant data fetch.
+
+**Server-side:**
+```javascript
+// Example: src/server/io/cache/todos/invalidate.mjs
+
+export async function ch_todos_invalidate(ctx) {
+  // A mutation happened. Inform the socket layer.
+  // The cache key "todos" matches the key used in the client's useSsrData("todos", ...)
+  await ctx.miolo.io.emitSsrRefresh(ctx, "todos", { 
+    excludeCurrent: true // Ignore the user who caused the change!
+  })
+}
+```
+
+**Client-side:**
+When the socket receives the invalidation, Miolo's core triggers a re-fetch for any `useSsrData` listening to the updated keys, keeping User B in sync seamlessly.
+
+### The `only_socket_id` Pattern
+
+Sometimes, an operation is localized or private. The server can push data updates specifically to a single connected client.
+
+**Server-side:**
+```javascript
+// Example: src/server/io/cache/stats/invalidate.mjs
+
+export async function ch_personal_stats_invalidate(ctx) {
+  await ctx.miolo.io.emitSsrRefresh(ctx, "personal_stats", {
+    onlyCurrent: true // Push update specifically to the originating client
+  })
+}
+```
+
+## Lazy SSR Data Refresh (`ssr-lazy-refresh`)
+
+A common UX problem with real-time sockets is "Abrupt UI Re-renders". If User B is actively reading a list and User A edits an item, a forced websocket refresh might cause User B's screen to jump or lose scroll state unexpectedly.
+
+To solve this, use the **lazy refresh** pattern:
+
+1. **Trigger `ssr-lazy-refresh`:** Instead of an immediate forced refresh, the server passes `lazy: true`.
+   ```javascript
+   await ctx.miolo.io.emitSsrRefresh(ctx, "todos", { 
+     excludeCurrent: true,
+     lazy: true 
+   })
+   ```
+2. **Wait for Interaction:** The data refresh is delayed until the user navigates, focuses the window, or explicitly triggers an action (handled by `miolo-navigation` and window focus listeners).
+3. **Implementation:** Miolo marks the internal `pendingLazyRefreshRef` flag. When the UX is safe (e.g., natural navigation boundary), it refreshes without causing jarring layout shifts.
+
+### Best Practices
+
+- **Avoid Blanket Broadcasts:** Always provide `excludeCurrent: true` in your server mutations when the originating client already handled its local state optimistically.
+- **Respect User Focus:** Use lazy refreshing for heavy or layout-shifting data updates. 
+- **Graceful Degradation:** The cache should always fall back to `remoteLoader` if the socket disconnects.

package/template/.agent/skills/miolo-model/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: miolo-model
+description: Patterns and conventions for data models in miolo apps. Use when creating or modifying data models, establishing JSDoc strict typing, extending MioloModel or MioloArray, or working in the src/ns/model directory.
+---
+
+# Miolo Data Models
+
+This skill details how to properly use and type data models in miolo applications using `miolo-model`. Models should encapsulate business logic and data structure securely, working across both client and server boundaries.
+
+## Architecture & Location
+
+Models reside in `src/ns/model/` (or `src/ns/models/`) because they are part of the shared **namespace (ns)** layer, meaning they execute seamlessly on both the server (Node.js) and the client (React).
+
+```
+src/ns/model/
+├── base/                   # Base models mirroring DB structures or API responses
+│   ├── Category.mjs
+│   ├── Todo.mjs
+│   └── TodoList.mjs
+└── aggregate_models...     # Domain-specific aggregated models
+```
+
+## Extending `MioloModel`
+
+All single-entity models should extend `MioloModel`.
+
+**File:** `src/ns/model/base/Todo.mjs`
+
+```javascript
+import { MioloModel } from "miolo-model"
+import Category from "./Category.mjs"
+
+/**
+ * @typedef {import("#ns/names/status.mjs").TodoStatus} TodoStatus
+ */
+
+export default class Todo extends MioloModel {
+  constructor(data) {
+    super(data)
+    
+    /**
+     * Initializing nested models
+     * @type {Category}
+     */
+    this.category = new Category()
+  }
+
+  /**
+   * Safely setting a nested model using Miolo patterns
+   * @param {Category | object} [category]
+   */
+  set_category(category) {
+    this.category = category instanceof Category ? category : new Category(category || {})
+  }
+
+  // --- Getters to access internal data map safely ---
+
+  /** @returns {number | undefined} */
+  get id_todo() {
+    return this.get_value("id_todo")
+  }
+
+  /** @returns {TodoStatus} */
+  get status() {
+    // Provide a sensible default if property is not found
+    return this.get_value("status", "PENDING")
+  }
+
+  /** @returns {boolean} */
+  get is_urgent() {
+    return this.get_value("is_urgent", false)
+  }
+
+  // --- Encapsulated Business Logic ---
+
+  /**
+   * @returns {boolean}
+   */
+  is_completed() {
+    return this.status === "COMPLETED"
+  }
+}
+```
+
+### Key Principles for Models:
+1. **Never read internal keys directly:** Always use `this.get_value("key", defaultValue)`.
+2. **Encapsulate Nested Objects:** Provide initialization logic in `constructor` and use setters like `set_category` to ensure the nested data is instantiated as a proper model object.
+3. **Keep Logic Here:** Don't put business logic like "is this todo completed?" in a React component. Put it in `is_completed()` inside the model.
+
+## Extending `MioloArray`
+
+For lists of models, extend `MioloArray`. This allows mapping a raw array of data directly into an array of proper model instances.
+
+**File:** `src/ns/model/base/TodoList.mjs`
+
+```javascript
+import { MioloArray } from "miolo-model"
+import Todo from "./Todo.mjs"
+
+/**
+ * @extends {MioloArray<Todo>}
+ */
+export default class TodoList extends MioloArray {
+  /**
+   * Return the Model class to map the raw items into
+   */
+  get model() {
+    return Todo
+  }
+
+  // --- List-specific Business Logic ---
+
+  /**
+   * @returns {Array<Todo>}
+   */
+  get_urgent_todos() {
+    return this.filter(t => t.is_urgent && !t.is_completed())
+  }
+}
+```
+
+> [!WARNING]
+> **TypeScript limitations with MioloArray:** Because `MioloArray` alters how native array methods (`filter`, `slice`, etc.) return data (returning a `MioloArray` instead of a standard `Array`), strict TypeScript checking might complain about `push()` signature incompatibilities. This is a known TS limitation with extending `Array`.
+> *Solution:* Use `"skipLibCheck": true` in `jsconfig.json` or explicitly ignore the TS errors in `node_modules` via `exclude`.
+
+## Strict JSDoc Typing (`checkJs: true`)
+
+Miolo enforces robust type safety without needing `.ts` files by utilizing standard JSDoc.
+
+1. **Enable Type Checking:** Add `"checkJs": true` in your `jsconfig.json`.
+2. **Type Every Getter:** `/** @returns {number | undefined} */ get id()`
+3. **Type Every Param:** `/** @param {boolean} also_doubt @returns {boolean} */ is_callable(also_doubt = false)`
+4. **Use `@typedef`:** Import and declare shared enums/types from namespace files. 
+
+```javascript
+/**
+ * @typedef {import("#ns/names/role.mjs").Role} Role
+ */
+```
+
+### Why Typed Models?
+
+By strictly typing the `src/ns/model` layer, you guarantee that API responses mapped into `MioloModel` objects will provide intelligent autocompletion across your entire client (React components) and server (routing layers), drastically reducing runtime errors.

package/template/.agent/skills/miolo-react-patterns/SKILL.md

@@ -32,13 +32,13 @@ src/cli/
 
 ## Context Pattern
 
-Every context follows a three-file pattern:
+Every context follows a strictly-typed three-file pattern to ensure type safety across the application:
 
 ```
 context/feature/
-├── FeatureContext.jsx     # Context definition
-├── FeatureProvider.jsx    # Provider component
-└── useFeatureContext.mjs  # Hook for consuming
+├── FeatureContext.mjs     # Context definition
+├── FeatureProvider.jsx    # Provider component (exports JSDoc types)
+└── useFeatureContext.mjs  # Hook for consuming (returns JSDoc types)
 ```
 
 ### Context Definition
@@ -53,46 +53,33 @@ const SessionContext = createContext()
 export default SessionContext
 ```
 
-### Provider Component
+### Provider Component with JSDoc Types
 
 **File:** `context/session/SessionProvider.jsx`
 
 ```javascript
 import { useState, useEffect } from 'react'
 import SessionContext from './SessionContext.mjs'
+import User from '#ns/model/User.mjs'
+
+/**
+ * Define the structure of your context data so consumers get autocomplete.
+ * 
+ * @typedef {Object} SessionContextData
+ * @property {User} user
+ * @property {boolean} loading
+ * @property {boolean} isAuthenticated
+ * @property {Function} login
+ * @property {Function} logout
+ */
 
 export default function SessionProvider({ children }) {
   const [user, setUser] = useState(null)
   const [loading, setLoading] = useState(true)
 
-  useEffect(() => {
-    // Fetch current user
-    fetch('/api/user/current')
-      .then(res => res.json())
-      .then(data => {
-        setUser(data.user)
-        setLoading(false)
-      })
-  }, [])
-
-  const login = async (credentials) => {
-    const res = await fetch('/api/user/login', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(credentials)
-    })
-    const data = await res.json()
-    if (data.ok) {
-      setUser(data.user)
-    }
-    return data
-  }
-
-  const logout = async () => {
-    await fetch('/api/user/logout', { method: 'POST' })
-    setUser(null)
-  }
+  // ... implementation ...
 
+  /** @type {SessionContextData} */
   const value = {
     user,
     loading,
@@ -109,7 +96,7 @@ export default function SessionProvider({ children }) {
 }
 ```
 
-### Consumer Hook
+### Strictly Typed Consumer Hook
 
 **File:** `context/session/useSessionContext.mjs`
 
@@ -117,6 +104,15 @@ export default function SessionProvider({ children }) {
 import { useContext } from 'react'
 import SessionContext from './SessionContext.mjs'
 
+/**
+ * Import the typedef from the Provider
+ * @typedef {import("./SessionProvider.jsx").SessionContextData} SessionContextData
+ */
+
+/**
+ * The hook returns the typed context data
+ * @returns {SessionContextData}
+ */
 export default function useSessionContext() {
   const context = useContext(SessionContext)
   
@@ -134,6 +130,7 @@ export default function useSessionContext() {
 import useSessionContext from '#cli/context/session/useSessionContext.mjs'
 
 export default function Profile() {
+  // Full IDE autocomplete for `user`, `loading`, `logout`!
   const { user, loading, logout } = useSessionContext()
 
   if (loading) return <div>Loading...</div>

package/template/.agent/skills/miolo-ssr/SKILL.md

@@ -423,6 +423,7 @@ const loader = async (ctx) => {
 ## Related Skills
 
 - **miolo-session-context** - Access `useSsrData` from session context
+- **miolo-caching** - Advanced caching, socket invalidation (`exclude_socket_id`), and lazy refreshing.
 - **miolo-fetcher** - Fetcher usage in remote loaders (future skill)
 - **miolo-react-patterns** - Context provider patterns
 

package/template/jsconfig.json

@@ -2,6 +2,7 @@
   "compilerOptions": {
     "jsx": "react-jsx",
     "checkJs": false,
+    "lib": ["ES2022", "DOM"],
     "target": "ES6",
     "module": "ES6",
     "moduleResolution": "bundler",

package/template/package.json

@@ -46,9 +46,9 @@
     "intre": "^3.0.0-beta.4",
     "joi": "^18.2.3",
     "lucide-react": "^1.24.0",
-    "miolo-cli": "^3.0.0-beta.227",
+    "miolo-cli": "^3.0.0-beta.229",
     "miolo-model": "file:../miolo-model",
-    "miolo-react": "^3.0.0-beta.227",
+    "miolo-react": "^3.0.0-beta.229",
     "next-themes": "^0.4.6",
     "radix-ui": "^1.6.2",
     "react": "^19.2.7",
@@ -63,7 +63,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.3",
-    "miolo": "^3.0.0-beta.227",
+    "miolo": "^3.0.0-beta.229",
     "sass-embedded": "^1.100.0"
   },
   "overrides": {