odac 1.4.2 → 1.4.4

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/.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,5 +1,104 @@
 ### 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
+- **client:** remove redundant truthy check for websocket token
+- **route:** remove useless variable assignment for decodedUrl
+
+### ⚡️ Performance Upgrades
+
+- **client:** remove redundant token consumption during websocket initialization
+
+### 📚 Documentation
+
+- **README:** enhance security section with detailed CSRF protection features
+
+### 🛠️ Fixes & Improvements
+
+- **client:** enhance websocket reconnection logic with attempt tracking and timer management
+- **client:** preserve existing websocket subprotocols & add try/catch layer to token provider
+- **route:** improve URL decoding and public path handling for file requests
+- **route:** sanitize decoded URL and improve public path validation
+- **route:** use robust path.extname instead of string splitting for mime type resolution
+- **websocket:** implement token provider for dynamic token handling on reconnect
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### doc
+
 - **forms:** update backend and frontend forms documentation with practical usage patterns and improved descriptions
 - **validation:** enhance backend validation documentation with detailed usage patterns and examples
 

package/README.md

@@ -9,7 +9,7 @@
 *   🎨 **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.
-*   🛡️ **Built-in Security:** Automatic CSRF protection and secure default headers keep your application safe.
+*   🛡️ **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.
 *   🌍 **i18n Support:** Native multi-language support to help you reach a global audience.

package/client/odac.js

@@ -7,10 +7,12 @@ class OdacWebSocket {
   #reconnectAttempts = 0
   #handlers = {}
   #isClosed = false
+  #tokenProvider = null
 
   constructor(url, protocols = [], options = {}) {
     this.#url = url
     this.#protocols = protocols
+    this.#tokenProvider = options.tokenProvider || null
     this.#options = {
       autoReconnect: true,
       reconnectDelay: 3000,
@@ -23,6 +25,19 @@ class OdacWebSocket {
   connect() {
     if (this.#isClosed) return
 
+    if (this.#tokenProvider) {
+      try {
+        const freshToken = this.#tokenProvider()
+        if (freshToken) {
+          let current = Array.isArray(this.#protocols) ? this.#protocols : this.#protocols ? [this.#protocols] : []
+          this.#protocols = current.filter(p => !p.startsWith('odac-token-'))
+          this.#protocols.push(`odac-token-${freshToken}`)
+        }
+      } catch (e) {
+        console.error('Odac WebSocket tokenProvider error:', e)
+      }
+    }
+
     this.#socket = this.#protocols.length > 0 ? new WebSocket(this.#url, this.#protocols) : new WebSocket(this.#url)
 
     this.#socket.onopen = () => {
@@ -924,12 +939,9 @@ if (typeof window !== 'undefined') {
       const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
       const wsUrl = `${protocol}//${window.location.host}${path}`
       const protocols = []
-      if (token) {
-        const csrfToken = this.token()
-        if (csrfToken) protocols.push(`odac-token-${csrfToken}`)
-      }
+      const tokenProvider = token ? () => this.token() : null
 
-      return new OdacWebSocket(wsUrl, protocols, options)
+      return new OdacWebSocket(wsUrl, protocols, {...options, tokenProvider})
     }
 
     #createSharedWebSocket(path, options) {
@@ -966,6 +978,9 @@ if (typeof window !== 'undefined') {
           case 'error':
             emit('error', data)
             break
+          case 'requestToken':
+            worker.port.postMessage({type: 'provideToken', token: this.token()})
+            break
         }
       }
 
@@ -1031,6 +1046,67 @@ if (typeof window !== 'undefined') {
 
   const broadcast = (type, data) => ports.forEach(port => port.postMessage({type, data}))
 
+  let wsConfig = null
+  let reconnectAttempts = 0
+  let reconnectTimer = null
+
+  const requestTokenFromPort = () => {
+    return new Promise(resolve => {
+      const firstPort = ports.values().next().value
+      if (!firstPort) return resolve(null)
+
+      let timeoutTimer = null
+
+      const handler = event => {
+        if (event.data.type === 'provideToken') {
+          clearTimeout(timeoutTimer)
+          firstPort.removeEventListener('message', handler)
+          resolve(event.data.token)
+        }
+      }
+
+      timeoutTimer = setTimeout(() => {
+        firstPort.removeEventListener('message', handler)
+        resolve(null)
+      }, 5000)
+
+      firstPort.addEventListener('message', handler)
+      firstPort.postMessage({type: 'requestToken'})
+    })
+  }
+
+  const connectSocket = protocols => {
+    if (!wsConfig || ports.size === 0) return
+    const wsUrl = wsConfig.protocol + '//' + wsConfig.host + wsConfig.path
+    socket = new OdacWebSocket(wsUrl, protocols, {
+      ...wsConfig.options,
+      tokenProvider: null
+    })
+    socket.on('open', () => {
+      reconnectAttempts = 0
+      broadcast('open')
+    })
+    socket.on('message', data => broadcast('message', data))
+    socket.on('close', e => {
+      broadcast('close', {code: e?.code, reason: e?.reason, wasClean: e?.wasClean})
+      const maxAttempts = wsConfig.options.maxReconnectAttempts || 10
+      if (wsConfig && wsConfig.options.autoReconnect !== false && ports.size > 0 && reconnectAttempts < maxAttempts) {
+        if (socket) {
+          socket.close()
+          socket = null
+        }
+        reconnectAttempts++
+        reconnectTimer = setTimeout(() => {
+          requestTokenFromPort().then(freshToken => {
+            if (!freshToken || ports.size === 0) return
+            connectSocket(['odac-token-' + freshToken])
+          })
+        }, wsConfig.options.reconnectDelay || 1000)
+      }
+    })
+    socket.on('error', e => broadcast('error', {message: e?.message || 'WebSocket error'}))
+  }
+
   self.onconnect = e => {
     const port = e.ports[0]
     ports.add(port)
@@ -1041,15 +1117,10 @@ if (typeof window !== 'undefined') {
       switch (type) {
         case 'connect':
           if (!socket) {
-            const wsUrl = protocol + '//' + host + path
+            wsConfig = {host, path, protocol, options}
             const protocols = token ? ['odac-token-' + token] : []
-            socket = new OdacWebSocket(wsUrl, protocols, options)
-            socket.on('open', () => broadcast('open'))
-            socket.on('message', data => broadcast('message', data))
-            socket.on('close', e => broadcast('close', {code: e?.code, reason: e?.reason, wasClean: e?.wasClean}))
-            socket.on('error', e => broadcast('error', {message: e?.message || 'WebSocket error'}))
+            connectSocket(protocols)
           } else if (socket.connected) {
-            // If already connected, notify the new port immediately
             port.postMessage({type: 'open'})
           }
           break
@@ -1058,9 +1129,15 @@ if (typeof window !== 'undefined') {
           break
         case 'close':
           ports.delete(port)
-          if (ports.size === 0 && socket) {
-            socket.close()
-            socket = null
+          if (ports.size === 0) {
+            if (reconnectTimer) {
+              clearTimeout(reconnectTimer)
+              reconnectTimer = null
+            }
+            if (socket) {
+              socket.close()
+              socket = null
+            }
           }
           break
       }

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.

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

@@ -18,7 +18,7 @@ Handling incoming data and sending structured responses.
 3.  **Returning Data**: 
     -   `return { ... }`: Returns JSON.
     -   `return Odac.return({ ... })`: Explicit JSON return.
-    -   `Odac.Response.header('Key', 'Value')`: Set custom headers.
+    -   `Odac.Request.header('Key', 'Value')`: Set custom headers.
 
 ## Reference Patterns
 ### 1. Unified Request Handling
@@ -36,7 +36,7 @@ module.exports = async function(Odac) {
 ### 2. Header and Status Management
 ```javascript
 module.exports = function(Odac) {
-  Odac.Response.header('Content-Type', 'text/plain');
+  Odac.Request.header('Content-Type', 'text/plain');
   return "Raw text response";
 };
 ```