odac 1.4.3 → 1.4.5

package/.agent/rules/coding.md

@@ -21,7 +21,7 @@ trigger: always_on
 
 ## 4. Modern JavaScript
 - **Standard:** Use ES6+ features (Async/Await, Arrow functions, Destructuring).
-- **Modules:** Strict adherence to ES Modules (import/export).
+- **Modules:** The current codebase uses CommonJS (`require` / `module.exports`). Follow CommonJS for existing modules to keep the codebase consistent. A gradual migration to ES Modules is planned; prefer ESM only for new, isolated packages or tools with clear interop boundaries.
 
 ## 5. Route & Session Logic
-- **Session Initialization:** `Odac.Request.setSession()` MUST be called before any logic that attempts to access `Odac.Request.session()`. This includes global middleware or form processing logic in `Route.js` that runs before the specific controller is resolved.
+- **Session Initialization:** `Odac.Request.setSession()` MUST be called before any logic that attempts to access `Odac.Request.session()`. This includes global middleware or form processing logic in `Route.js` that runs before the specific controller is resolved.

package/.agent/rules/memory.md

@@ -38,6 +38,7 @@ trigger: always_on
 
 ## Documentation Standards
 - **AI Skill Front Matter:** Every file under `docs/ai/skills/**/*.md` must start with YAML front matter containing `name`, `description`, and `metadata.tags`; values must be specific to that document's topic (never copied from generic examples).
+- **Template Syntax Documentation:** `{{ }}` and `<odac var>` are equal-status syntaxes, NOT legacy vs modern. `{{ }}` is preferred inside HTML attributes and inline text; `<odac var>` is preferred for standalone block output. Never label `{{ }}` as "legacy" or "backward compatibility" in docs.
 
 ## Testing & Validation
 - **Mandatory Test Coverage:** Every new feature, method, or significant logic change MUST be accompanied by a corresponding unit or integration test.
@@ -53,4 +54,7 @@ trigger: always_on
 - **Automatic JSON Parsing:** The `#ajax` method (and by extension `odac.get`) must automatically parse the response if the `Content-Type` header contains `application/json`, even if `dataType` is not explicitly set to `json`.
 
 ## Security Logic & Authentication
-- **Enterprise Token Rotation:** The `Auth.js` system utilizes a non-blocking refresh token rotation mechanism for cookies (`odac_x`/`odac_y`). To prevent race conditions during concurrent requests in high-throughput SPAs, rotated tokens are **not** immediately deleted. Instead, their `active` timestamp is set to naturally expire in 60 seconds (Grace Period), and their `date` timestamp is set to the Unix Epoch (`new Date(0)`) as an identifier mark. Never delete rotated tokens immediately.
+- **Enterprise Token Rotation:** The `Auth.js` system utilizes a non-blocking refresh token rotation mechanism for cookies (`odac_x`/`odac_y`). To prevent race conditions during concurrent requests in high-throughput SPAs, rotated tokens are **not** immediately deleted. Instead, their `active` timestamp is set to naturally expire in 60 seconds (Grace Period), and their `date` timestamp is set to the Unix Epoch (`new Date(0)`) as an identifier mark. Never delete rotated tokens immediately.
+
+## View Engine & SSR
+- **Auto-Navigation Injection:** The ODAC View engine (`src/View.js`) automatically parses skeleton HTML files and dynamically injects `data-odac-navigate="content"` into the element immediately wrapping `{{ CONTENT }}`. Do NOT manually add this attribute to HTML templates or assume it is missing based on static analysis, as it is handled seamlessly at runtime via SSR.

package/.github/workflows/release.yml

@@ -30,6 +30,7 @@ jobs:
         with:
           node-version: '24'
           registry-url: 'https://registry.npmjs.org'
+          always-auth: false
 
       - name: Update npm
         run: npm install -g npm@latest
@@ -40,6 +41,7 @@ jobs:
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HUSKY: 0
         run: npx semantic-release
       - name: Get version
         id: version

package/.husky/pre-push

@@ -1,5 +1,4 @@
 #!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
 
 # Prevent pushing code with High/Critical vulnerabilities in production dependencies
 echo "🛡️  Running Production Security Gate (npm audit)..."

package/.kiro/steering/coding.md

@@ -0,0 +1,27 @@
+---
+inclusion: always
+---
+
+# Coding Standards & Best Practices
+
+## 1. Testing Strategy
+- **Rule:** No feature is complete without tests.
+- **Goal:** Maintain stability and prevent regressions.
+- **Action:** Write unit tests for logic and integration tests for API endpoints.
+
+## 2. Dependency Management
+- **Philosophy:** "Less is more."
+- **Rule:** Avoid external dependencies unless absolutely necessary.
+- **Preference:** Prioritize native Node.js modules (`fs`, `http`, `crypto`, etc.) to reduce bundle size and security attack surface.
+
+## 3. Error Handling
+- **Rule:** Fail loudly and clearly.
+- **Practice:** Use custom Error classes where possible.
+- **Message:** Error messages should guide the developer on how to fix the issue, not just say "Error".
+
+## 4. Modern JavaScript
+- **Standard:** Use ES6+ features (Async/Await, Arrow functions, Destructuring).
+- **Modules:** The current codebase uses CommonJS (`require` / `module.exports`). Follow CommonJS for existing modules to keep the codebase consistent. A gradual migration to ES Modules is planned; prefer ESM only for new, isolated packages or tools with clear interop boundaries.
+
+## 5. Route & Session Logic
+- **Session Initialization:** `Odac.Request.setSession()` MUST be called before any logic that attempts to access `Odac.Request.session()`. This includes global middleware or form processing logic in `Route.js` that runs before the specific controller is resolved.

package/.kiro/steering/memory.md

@@ -0,0 +1,56 @@
+---
+inclusion: always
+---
+
+# Project Memory & Rules
+
+## Configuration & Environment
+- **Debug Mode Logic:** The `debug` configuration in `src/Config.js` defaults to `process.env.NODE_ENV !== 'production'`. This ensures that `odac dev` (undefined NODE_ENV) enables debug/hot-reload, while `odac start` (NODE_ENV=production) disables it to use caching.
+- **Logging Strategy:** 
+    - **Development (`debug: true`):** Enable verbose logging, hot-reloading notifications, and detailed stack traces for easier debugging.
+    - **Production (`debug: false`):** Minimize logging to essential operational events (Start/Stop) and Fatal Errors only. Avoid `console.log` for per-request information to preserve performance and disk space. Sensitive error details must not be exposed to the user.
+
+## Development Standards & Integrity
+- **NO QUICK/LAZY FIXES:** Explicitly prohibited. 
+    - Never implement truncated solutions (e.g., `substring(0, 32)` on a hash) or temporary workarounds just to make code run.
+    - Always implement the mathematically and architecturally correct "Enterprise-Grade" solution (e.g., using raw `Buffer` for crypto keys instead of hex strings).
+    - If a proper solution requires refactoring, do the refactoring. Do not patch holes.
+    - **Prioritize Correctness over Speed:** It is better to verify documentation or think for a minute than to output a sub-par patch.
+
+## Code Quality & Modern Standards
+- **No Legacy Syntax:** 
+    - **Strictly Prohibited:** The use of `var` is forbidden. Use `const` (preferred) or `let` (only if mutation is needed).
+    - **Variable Scope:** Ensure variables are block-scoped to prevent leakage.
+- **Anti-Spaghetti Code:**
+    - **Fail-Fast Pattern:** Avoid deeply nested `if/else` logic. Use early returns (`return`, `break`, `continue`) to handle negative cases immediately.
+    - **Promise Handling:** Resolve Promises upfront (e.g., `Promise.all` or strict `await` before loops) rather than mixing `await` inside deep logic or mutating input objects.
+    - **Strict Equality:** Always use strict equality checks (`===`) instead of loose ones.
+    - **Loop Optimization:** Use labeled loops (`label: for`) for efficient control flow in nested structures. Eliminate intermediate "flag" variables (`isMatch`, `found`) by using direct `return` or `continue label`.
+    - **Direct Returns:** Return a value as soon as it is determined. Avoid assigning to a temporary variable (e.g. `matchedUser`) and breaking the loop, unless post-loop processing is strictly necessary.
+    - **Async State Safety:** When an async function depends on mutable class state (like `pendingMiddlewares`), capture that state into a local `const` *synchronously* before triggering any async operations. This prevents race conditions where the state changes before the async task consumes it.
+    - **Async I/O Preference:** Prefer asynchronous file system operations (`fs.promises` or `await fs.promises.*`) over synchronous methods (`fs.readFileSync`, `fs.writeFileSync`) to prevent blocking the event loop and ensure high concurrency, especially in request handling paths.
+
+## Dependency Management
+- **Prefer Native Fetch:** Use the native `fetch` API for network requests in both Node.js (18+) and browser environments to reduce dependencies and bundle size.
+
+## Naming & Text Conventions
+- **ODAC Casing:** Always write "ODAC" in uppercase letters when referring to the framework name in strings, comments, log messages, or user-facing text. **EXCEPTION:** The class name itself (`class Odac`) and variable references to it should remain `Odac` (PascalCase) as per code conventions.
+
+## Documentation Standards
+- **AI Skill Front Matter:** Every file under `docs/ai/skills/**/*.md` must start with YAML front matter containing `name`, `description`, and `metadata.tags`; values must be specific to that document's topic (never copied from generic examples).
+
+## Testing & Validation
+- **Mandatory Test Coverage:** Every new feature, method, or significant logic change MUST be accompanied by a corresponding unit or integration test.
+    - **Verify Correctness:** do not assume code works; prove it with a test that covers both success and failure scenarios (e.g., edge cases, error conditions).
+    - **Update Existing Tests:** If a feature modifies existing behavior, update the relevant tests to reflect the new logic and ensure they pass.
+- **Atomic Test Structure:**
+    - **Directory Mapping:** Each source class/module must have its own directory under `test/` (e.g., `src/Auth.js` -> `test/Auth/`).
+    - **Method-Level Files:** Every public method should have its own test file within the class directory (e.g., `test/Auth/check.test.js`).
+    - **Sub-module Context:** Nested modules should follow the same pattern (e.g., `src/View/Form.js` -> `test/View/Form/generateFieldHtml.test.js`).
+    - **Isolation & Parallelism:** This structure is mandatory to leverage Jest's multi-threaded execution and ensure strict isolation between test cases.
+
+## Client Library (odac.js)
+- **Automatic JSON Parsing:** The `#ajax` method (and by extension `odac.get`) must automatically parse the response if the `Content-Type` header contains `application/json`, even if `dataType` is not explicitly set to `json`.
+
+## Security Logic & Authentication
+- **Enterprise Token Rotation:** The `Auth.js` system utilizes a non-blocking refresh token rotation mechanism for cookies (`odac_x`/`odac_y`). To prevent race conditions during concurrent requests in high-throughput SPAs, rotated tokens are **not** immediately deleted. Instead, their `active` timestamp is set to naturally expire in 60 seconds (Grace Period), and their `date` timestamp is set to the Unix Epoch (`new Date(0)`) as an identifier mark. Never delete rotated tokens immediately.

package/.kiro/steering/project.md

@@ -0,0 +1,30 @@
+---
+inclusion: always
+---
+
+# Project Context & Design Philosophy
+
+## Project Identity
+- **Type:** Node.js Framework
+- **Goal:** To provide a robust, enterprise-ready backbone for web applications.
+
+## Core Priorities (The "Big 3")
+1.  **Enterprise-Level Security:** 
+    - Security is not an afterthought; it is foundational. 
+    - Default to secure settings. 
+    - Validate all inputs. 
+    - Sanitize outputs. 
+    - Use established cryptographic standards.
+2.  **Zero-Config:** 
+    - The framework should work "out of the box" with sensible defaults. 
+    - Configuration should be optional, not mandatory for getting started. 
+    - "Convention over Configuration" is key.
+3.  **High Performance:** 
+    - Code must be optimized for throughput and low latency. 
+    - Avoid unnecessary overhead. 
+    - Profile and benchmark critical paths. 
+    - Memory management is crucial.
+
+## Interaction Guidelines for AI
+- Always assume the user wants the most efficient and secure solution unless specified otherwise.
+- When suggesting architecture, prioritize scalability and maintainability.

package/.kiro/steering/workflow.md

@@ -0,0 +1,16 @@
+---
+inclusion: always
+---
+
+# Development Workflow Rules
+
+## 1. Quality Assurance (Linting)
+- **Rule:** **ALWAYS** runs lint checks after writing or modifying code.
+- **Action:** Execute the project's linting command (e.g., `npm run lint` or `eslint .`) to verify code compliance.
+- **Strictness:** Do not mark a task as complete if lint errors persist. Fix them immediately.
+
+## 2. Documentation Hygiene
+- **Rule:** Documentation must be kept in sync with code changes.
+- **Trigger:** Adding a new feature, modifying an API, or changing configuration behavior.
+- **Action:** Update the relevant `.md` files (README, API docs, etc.) or JSDoc comments.
+- **Goal:** Ensure that the documentation is never stale and accurately reflects the current state of the codebase.

package/CHANGELOG.md

@@ -1,3 +1,101 @@
+### security
+
+- **template:** add noopener to external footer links to mitigate reverse tabnabbing
+- **template:** add rel="noopener" to all external links to prevent tabnabbing without losing referer analytics
+
+### ✨ What's New
+
+- **client:** add native View Transition API support via odac-transition attribute
+- Implement a complete UI redesign using Tailwind CSS, introduce new components, and update branding to ODAC.
+
+### 📚 Documentation
+
+- Add documentation for auto-navigation injection in the View Engine and SSR.
+- **template:** correct casing for Odac object api references in comments
+- **views:** clarify template syntax as equal-status with usage guidelines
+
+### 🛠️ Fixes & Improvements
+
+- **client:** clear stale view transition names on aborted navigation promises
+- **client:** decode HTML entities in document title to prevent XSS vulnerabilities
+- **template:** sync active nav state properly across desktop and mobile menus
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### doc
+
+- Introduce WebSocket routing and controllers, update request handling, and refactor language and validator modules to use async operations.
+
+### ⚙️ Engine Tuning
+
+- **view:** extract <odac:img> parsing to Image.parse() method
+
+### ✨ What's New
+
+- **image:** add Odac.image() API for programmatic image URL generation
+- **view:** add <odac:img> tag with on-demand image processing
+- **view:** add warning message when sharp dependency is unavailable
+- **view:** implement human-readable cache filenames and mtime-based cache busting
+
+### 📚 Documentation
+
+- **steering:** correct module system standard to explicitly dictate CommonJS preserving architectural consistency
+- **View/Image:** correct cache eviction jsdoc from LRU to FIFO reflecting O(1) performance trait
+
+### 🛠️ Fixes & Improvements
+
+- **auth:** prevent duplicate login tokens during magic link verification
+- Refactor `fs` module usage to `node:fs` and `fs.promises`, and update string manipulation from `substr` to `slice`.
+- **request:** use global.Odac namespace for consistent access
+- **route:** improve controller loading error handling with specific error messages
+- **route:** update inline function reference on hot reload
+- **View/Image:** clamp unrequested output formats to supported whitelist to prevent processing crashes
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### doc
+
+- Introduce WebSocket routing and controllers, update request handling, and refactor language and validator modules to use async operations.
+
+### ⚙️ Engine Tuning
+
+- **view:** extract <odac:img> parsing to Image.parse() method
+
+### ✨ What's New
+
+- **image:** add Odac.image() API for programmatic image URL generation
+- **view:** add <odac:img> tag with on-demand image processing
+- **view:** add warning message when sharp dependency is unavailable
+- **view:** implement human-readable cache filenames and mtime-based cache busting
+
+### 📚 Documentation
+
+- **steering:** correct module system standard to explicitly dictate CommonJS preserving architectural consistency
+- **View/Image:** correct cache eviction jsdoc from LRU to FIFO reflecting O(1) performance trait
+
+### 🛠️ Fixes & Improvements
+
+- **auth:** prevent duplicate login tokens during magic link verification
+- Refactor `fs` module usage to `node:fs` and `fs.promises`, and update string manipulation from `substr` to `slice`.
+- **request:** use global.Odac namespace for consistent access
+- **route:** improve controller loading error handling with specific error messages
+- **route:** update inline function reference on hot reload
+- **View/Image:** clamp unrequested output formats to supported whitelist to prevent processing crashes
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### ⚙️ Engine Tuning
 
 - **client:** extract ws connection logic and fix recursive sharedworker reconnects reconnect bug

package/README.md

@@ -8,7 +8,7 @@
 *   🚀 **Developer Friendly:** Simple setup and intuitive API design let you start building immediately.
 *   🎨 **Built-in Tailwind CSS:** Zero-config integration with Tailwind CSS v4. Automatic compilation and optimization out of the box.
 *   🔗 **Powerful Routing:** Create clean, custom URLs and manage infinite pages with a flexible routing system.
-*   ✨ **Seamless SPA Experience:** Automatic AJAX handling for forms and page transitions eliminates the need for complex client-side code.
+*   ✨ **Seamless SPA Experience:** Automatic AJAX handling for forms and page transitions with native **View Transition API** support. Add a single HTML attribute for smooth, browser-native animations — no client-side code required.
 *   🛡️ **Built-in Security:** Enterprise-grade security out of the box. Includes secure default headers and a **Multi-tab Safe, Single-Use CSRF Protection (Nonce)**. Tokens self-replenish in the background, ensuring maximum defense without ever interrupting the user experience.
 *   🔐 **Authentication:** Ready-to-use session management with enterprise-grade **Refresh Token Rotation**, secure password hashing, and authentication helpers.
 *   🗄️ **Database Agnostic:** Integrated support for major databases (PostgreSQL, MySQL, SQLite) and Redis via Knex.js.
@@ -72,6 +72,7 @@ project/
 ├── middleware/     # Route middlewares
 ├── public/         # Static assets
 ├── route/          # Route definitions
+├── schema/         # Database schemas (auto-migrate)
 ├── view/           # HTML templates
 ├── .env            # Environment variables
 └── odac.json       # App configuration

package/client/odac.js

@@ -195,6 +195,33 @@ if (typeof window !== 'undefined') {
       xhr.send(data)
     }
 
+    /**
+     * Assigns `view-transition-name` CSS properties to all elements carrying
+     * the `odac-transition` attribute, enabling the browser's native View
+     * Transition API to animate them individually during navigation.
+     *
+     * @returns {Element[]} The list of elements that received transition names.
+     */
+    #applyTransitionNames() {
+      const elements = document.querySelectorAll('[odac-transition]')
+      elements.forEach(el => {
+        el.style.viewTransitionName = el.getAttribute('odac-transition')
+      })
+      return Array.from(elements)
+    }
+
+    /**
+     * Removes `view-transition-name` from previously tagged elements to
+     * prevent stale names from conflicting with future transitions.
+     *
+     * @param {Element[]} elements - Elements to clean up.
+     */
+    #clearTransitionNames(elements) {
+      elements.forEach(el => {
+        el.style.viewTransitionName = ''
+      })
+    }
+
     #fade(element, type, duration = 400, callback) {
       const isIn = type === 'in'
       const startOpacity = isIn ? 0 : 1
@@ -720,6 +747,20 @@ if (typeof window !== 'undefined') {
         .replace(/\n/g, '<br>')
     }
 
+    /**
+     * Decodes HTML entities back to their plain-text representation.
+     * Uses a textarea element as a safe decoder — no script execution risk.
+     *
+     * @param {string} str - HTML-encoded string (e.g. "&amp;" → "&").
+     * @returns {string} Decoded plain-text string.
+     */
+    #decodeHtmlEntities(str) {
+      if (typeof str !== 'string') return str
+      const textarea = document.createElement('textarea')
+      textarea.innerHTML = str
+      return textarea.value
+    }
+
     load(url, callback, push = true) {
       if (this.#isNavigating) return false
 
@@ -739,6 +780,84 @@ if (typeof window !== 'undefined') {
         if (element) elementsToUpdate.push({key, element})
       })
 
+      const useViewTransition = document.startViewTransition && document.querySelectorAll('[odac-transition]').length > 0
+
+      if (useViewTransition) {
+        this.#loadWithViewTransition(url, callback, push, currentUrl, currentSkeleton, elementsToUpdate)
+      } else {
+        this.#loadWithFade(url, callback, push, currentUrl, currentSkeleton, elementsToUpdate)
+      }
+    }
+
+    /**
+     * Performs page navigation using the browser's native View Transition API.
+     * Elements with `odac-transition` attributes receive individual transition
+     * names, enabling per-element morphing animations orchestrated by the browser.
+     * Non-transition elements still update their content within the transition frame.
+     */
+    #loadWithViewTransition(url, callback, push, currentUrl, currentSkeleton, elementsToUpdate) {
+      const oldTransitionElements = this.#applyTransitionNames()
+
+      this.#ajax({
+        url,
+        type: 'GET',
+        headers: {
+          'X-Odac': 'ajaxload',
+          'X-Odac-Load': Object.keys(this.#loader.elements).join(','),
+          'X-Odac-Skeleton': currentSkeleton || ''
+        },
+        dataType: 'json',
+        success: (data, status, xhr) => {
+          const finalUrl = xhr.responseURL || url
+          if (data.skeletonChanged) {
+            this.#clearTransitionNames(oldTransitionElements)
+            window.location.href = finalUrl
+            return
+          }
+
+          const transition = document.startViewTransition(() => {
+            if (finalUrl !== currentUrl && push) window.history.pushState(null, document.title, finalUrl)
+
+            const newPage = xhr.getResponseHeader('X-Odac-Page')
+            if (newPage !== null) {
+              this.#page = newPage
+              document.documentElement.dataset.odacPage = newPage
+            }
+
+            if (data.data) this.#data = data.data
+            if (data.title) document.title = this.#decodeHtmlEntities(data.title)
+
+            elementsToUpdate.forEach(({key, element}) => {
+              if (data.output && data.output[key] !== undefined) element.innerHTML = data.output[key]
+            })
+
+            this.#applyTransitionNames()
+          })
+
+          transition.finished
+            .then(() => {
+              this.#clearTransitionNames(document.querySelectorAll('[odac-transition]'))
+              this.#handleLoadComplete(data, callback)
+            })
+            .catch(() => {
+              this.#clearTransitionNames(document.querySelectorAll('[odac-transition]'))
+              this.#isNavigating = false
+            })
+        },
+        error: () => {
+          this.#clearTransitionNames(oldTransitionElements)
+          this.#isNavigating = false
+          window.location.replace(url)
+        }
+      })
+    }
+
+    /**
+     * Performs page navigation using the legacy fade-in/fade-out animation.
+     * This is the fallback path when the View Transition API is unavailable
+     * or no `odac-transition` elements exist in the DOM.
+     */
+    #loadWithFade(url, callback, push, currentUrl, currentSkeleton, elementsToUpdate) {
       let ajaxData = null,
         ajaxXhr = null,
         fadeOutComplete = false,
@@ -761,7 +880,7 @@ if (typeof window !== 'undefined') {
         }
 
         if (ajaxData.data) this.#data = ajaxData.data
-        if (ajaxData.title) document.title = ajaxData.title
+        if (ajaxData.title) document.title = this.#decodeHtmlEntities(ajaxData.title)
 
         if (elementsToUpdate.length === 0) {
           this.#handleLoadComplete(ajaxData, callback)
@@ -794,7 +913,7 @@ if (typeof window !== 'undefined') {
       }
 
       this.#ajax({
-        url: url,
+        url,
         type: 'GET',
         headers: {
           'X-Odac': 'ajaxload',

package/docs/ai/skills/backend/authentication.md

@@ -59,13 +59,15 @@ const val = Odac.session('key');
 Odac.session('key', null);
 ```
 
-### 4. Realtime Hubs (WebSockets)
+### 4. Realtime Broadcasting (Ipc)
 ```javascript
-// Broadcast to everyone in a room
-Odac.Hub.to('lobby').send('chat_message', { text: 'Hello!' });
+// Broadcast to everyone subscibed in this worker cluster
+await Odac.Ipc.publish('lobby', { type: 'chat', text: 'Hello!' });
 
-// Targeted user broadcast
-Odac.Hub.user(userId).send('notification', { text: 'New follower' });
+// In your WS handler, listen for Ipc messages
+Odac.Ipc.subscribe('lobby', (msg) => {
+  Odac.ws.send(msg);
+});
 ```
 
 ## Security Best Practices

package/docs/ai/skills/backend/controllers.md

@@ -32,7 +32,7 @@ class User {
 
   // GET /users/{id}
   async show(Odac) {
-    const id = Odac.Request.input('id');
+    const id = await Odac.request('id');
     const user = await Odac.Service.get('User').find(id);
     return Odac.return(user);
   }
@@ -48,7 +48,28 @@ class User {
 module.exports = User;
 ```
 
-### 2. Simple Function-Based Controller
+### 2. WebSocket Controller
+```javascript
+// controller/ws/Chat.js
+module.exports = function(Odac) {
+  const ws = Odac.ws; // The WebSocket client instance
+
+  ws.on('message', (data) => {
+    console.log('Received:', data);
+    // Broadcast to everyone else
+    ws.broadcast({ sender: ws.id, text: data.text });
+  });
+
+  ws.on('close', () => {
+    console.log('Client disconnected:', ws.id);
+  });
+
+  // Optional: send welcome message
+  ws.send({ type: 'info', message: 'Connected to Chat!' });
+};
+```
+
+### 3. Simple Function-Based Controller
 ```javascript
 // controller/Home.js
 module.exports = function(Odac) {
@@ -56,7 +77,7 @@ module.exports = function(Odac) {
 };
 ```
 
-### 3. Usage in Routes
+### 4. Usage in Routes
 ```javascript
 // route/web.js
 Odac.Route.get('/users', 'User@index');

package/docs/ai/skills/backend/forms.md

@@ -109,12 +109,14 @@ module.exports = class Contact {
 
 ## Patterns
 ```javascript
-// Access validated data in action-driven custom form
-Odac.Route.class.post('/contact', class Contact {
+// Custom form action in class/Contact.js
+module.exports = class Contact {
   async submit(form) {
-    const {email, message} = form.data
-    if (!email || !message) return form.error('_odac_form', 'Missing input')
-    return form.success('Saved successfully')
+    const { email, message } = form.data;
+    if (!email || !message) return form.error('email', 'Required fields missing');
+    
+    // Process data...
+    return form.success('Message received!');
   }
-})
+}
 ```

package/docs/ai/skills/backend/image-processing.md

@@ -0,0 +1,93 @@
+---
+name: backend-image-processing-skill
+description: ODAC on-demand image optimization via the odac:img template tag with automatic resize, format conversion, and aggressive caching.
+metadata:
+  tags: backend, image, optimization, sharp, webp, resize, template, view
+---
+
+# Backend Image Processing Skill
+
+ODAC provides on-demand image processing through the `<odac:img>` template tag. Images are automatically resized, converted to modern formats (WebP, AVIF), and cached to disk for sub-millisecond subsequent responses.
+
+## Architectural Approach
+
+Processing happens at render time via `src/View/Image.js`. The first request triggers sharp-based transformation; all subsequent requests serve from `storage/.cache/img/`. Sharp is an optional dependency — when absent, `<odac:img>` gracefully degrades to a standard `<img>` tag.
+
+## Core Rules
+
+1. **Optional Dependency**: Sharp must be installed separately (`npm install sharp`). The framework functions without it.
+2. **Security**: Path traversal is blocked. Only files under `public/` are processable.
+3. **Cache**: Processed images are stored in `storage/.cache/img/` with human-readable filenames (`{name}-{dimension}-{hash}.{ext}`) for easy debugging and CDN log analysis.
+4. **Max Dimension**: 4096px cap prevents resource exhaustion from oversized requests.
+
+## Reference Patterns
+
+### 1. Basic Resize + Format Conversion
+```html
+<odac:img src="/images/hero.jpg" width="800" height="600" format="webp"/>
+```
+
+### 2. Format Conversion Only (No Resize)
+```html
+<odac:img src="/images/logo.png" format="webp"/>
+```
+
+### 3. Custom Quality
+```html
+<odac:img src="/images/banner.jpg" width="1200" format="webp" quality="90"/>
+```
+
+### 4. Dynamic Source from Controller
+```html
+<odac:img src="{{ product.image }}" width="200" height="200" format="webp" alt="Product"/>
+```
+
+### 5. With Standard HTML Attributes
+```html
+<odac:img src="/images/avatar.jpg" width="64" height="64" format="webp"
+          alt="User avatar" class="rounded-full" loading="lazy" decoding="async"/>
+```
+
+## Supported Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `src` | string | Source path relative to `public/` (required) |
+| `width` | number | Target width in pixels |
+| `height` | number | Target height in pixels |
+| `format` | string | Output format: `webp`, `avif`, `png`, `jpeg`, `tiff` |
+| `quality` | number | Compression quality 1-100 (default: 80) |
+| All others | — | Passed through to the `<img>` tag as-is |
+
+## Configuration
+
+Default settings in `odac.json`:
+```json
+{
+  "image": {
+    "quality": 80,
+    "maxDimension": 4096,
+    "format": "webp"
+  }
+}
+```
+
+## Best Practices
+
+- Prefer `webp` format for the best size/quality ratio across modern browsers.
+- Set explicit `width` and `height` to prevent layout shift (CLS).
+- Use `loading="lazy"` for below-the-fold images.
+- Keep source images at high resolution in `public/`; let ODAC handle the downsizing.
+
+## Programmatic API (`Odac.image()`)
+
+For cases where a raw URL is needed instead of an `<img>` tag (div backgrounds, JSON APIs, mail templates, cron jobs):
+
+```js
+const url = await Odac.image('/images/hero.jpg', { width: 800, format: 'webp' })
+// → "/_odac/img/hero-800-a1b2c3d4.webp"
+```
+
+- Available on every `Odac` instance (controller, cron, middleware).
+- Same processing pipeline and cache as `<odac:img>`.
+- Returns original `src` as fallback when sharp is unavailable.