odac 1.4.3 → 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,3 +1,73 @@
+### 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/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";
 };
 ```

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

@@ -17,6 +17,8 @@ Routes are defined in the `route/` directory. ODAC uses a two-phase routing stra
     -   `Odac.Route.page(url, controller)`: For HTML views (GET).
     -   `Odac.Route.get(url, controller)`: Targeted GET requests.
     -   `Odac.Route.post(url, controller)`: Sensitive POST requests (CSRF enabled by default).
+    -   `Odac.Route.ws(url, controller)`: Bidirectional and persistent WebSocket connections.
+    -   `Odac.Route.authWs(url, controller)`: Authenticated WebSocket connections.
 2.  **Parameters**: Use `{id}` syntax for dynamic segments. Accessed via `Odac.request('id')`.
 3.  **Middlewares**: Chain logic using `.use('name')`. Global middlewares reside in `middleware/`.
 4.  **Error Handling**: Use `Odac.Route.error(code, controller)` for custom 404/500 pages.
@@ -51,6 +53,15 @@ Odac.Route.error(500, 'errors/ServerError');
 Odac.Route.post('/api/webhook', 'Api@webhook', { token: false });
 ```
 
+### 5. Realtime & WebSocket Routes
+```javascript
+// Public WebSocket
+Odac.Route.ws('/chat', 'Chat');
+
+// Authenticated WebSocket with path params
+Odac.Route.authWs('/game/{roomId}', 'Game@join');
+```
+
 ## Best Practices
 -   **Method Specification**: Use `.page()` for views to enable AJAX navigation compatibility.
 -   **Static First**: Prefer exact URL matches over parametric ones where possible (faster).

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

@@ -50,7 +50,7 @@ module.exports = User;
 class User {
   async show(Odac) {
     // Service is automatically available as Odac.User
-    const profile = await Odac.User.getProfile(Odac.Request.input('id'));
+    const profile = await Odac.User.getProfile(await Odac.request('id'));
     
     return Odac.View.make('user.profile', { profile });
   }

package/docs/ai/skills/frontend/realtime.md

@@ -50,5 +50,21 @@ source.onmessage = (event) => {
 
 ## Best Practices
 -   **Resource Management**: Shared WebSocket automatically closes when the last tab using it is closed.
--   **Fallback**: If `SharedWorker` is not supported (e.g., Safari), `Odac.ws` automatically falls back to a standard WebSocket.
--   **Server-Side Hubs**: Ensure the backend uses `Odac.Hub` to send messages to the correct rooms or users.
+-   **Security**: Always use `Odac.ws(url, { token: true })` for authenticated paths; the client will automatically attach the latest CSRF/Session token.
+-   **Distributed State**: Use `Odac.Ipc` in backend WS handlers to broadcast messages across multiple server workers.
+
+### 4. Rooms & Broadcasting (Backend Example)
+```javascript
+// controller/ws/Game.js
+module.exports = async function(Odac) {
+  const ws = Odac.ws;
+  const roomId = await Odac.request('roomId');
+
+  ws.join(roomId);
+
+  ws.on('message', (data) => {
+    // Broadcast only to this room
+    ws.to(roomId).send({ user: ws.id, move: data.move });
+  });
+};
+```

package/docs/backend/05-controllers/02-your-trusty-odac-assistant.md

@@ -21,6 +21,7 @@ Remember the `Odac` object? It's your best friend inside a controller. It's pass
 *   `Odac.setInterval(callback, delay)`: Schedule repeating tasks (auto-cleanup).
 *   `Odac.setTimeout(callback, delay)`: Schedule one-time tasks (auto-cleanup).
 *   `Odac.stream(input)`: Create streaming responses (SSE).
+*   `Odac.image(src, options)`: Get a processed image URL (resize, format conversion, caching).
 
 #### Memory-Safe Timers
 
@@ -41,3 +42,26 @@ module.exports = async (Odac) => {
 ```
 
 With controllers and the `Odac` object, you have everything you need to start building powerful application logic!
+
+#### Image Processing
+
+Use `Odac.image()` when you need a processed image URL outside of templates — for JSON APIs, div backgrounds, email templates, or cron jobs:
+
+```javascript
+module.exports = async (Odac) => {
+  // Get a resized WebP URL for an API response
+  const heroUrl = await Odac.image('/images/hero.jpg', { width: 1200 })
+  // → "/_odac/img/hero-1200-a1b2c3d4.webp"
+
+  // Pass a processed URL to the template for a CSS background
+  const bgUrl = await Odac.image('/images/banner.jpg', { width: 1920, quality: 90 })
+  Odac.set('bgUrl', bgUrl)
+
+  // Convert to a specific format
+  const pngLogo = await Odac.image('/images/logo.png', { width: 200, format: 'png' })
+}
+```
+
+**Options:** `{ width, height, format, quality }` — same as `<odac:img>` tag attributes.
+
+> When `sharp` is not installed, `Odac.image()` returns the original source path as a graceful fallback. For template usage with automatic `<img>` tag generation, see the [`<odac:img>` documentation](../07-views/11-image-optimization.md).

package/docs/backend/07-views/03-template-syntax.md

@@ -130,6 +130,23 @@ Execute JavaScript on the server during template rendering:
 
 **[→ Learn more about Backend JavaScript](./08-backend-javascript.md)**
 
+### Image Optimization
+
+Automatically resize and convert images to modern formats:
+
+```html
+<!-- Auto-convert to WebP (default) -->
+<odac:img src="/images/hero.jpg" />
+
+<!-- Resize + convert -->
+<odac:img src="/images/photo.jpg" width="800" height="600" format="webp" />
+
+<!-- With standard HTML attributes -->
+<odac:img src="/images/avatar.jpg" width="64" height="64" alt="Avatar" loading="lazy" />
+```
+
+**[→ Learn more about Image Optimization](./11-image-optimization.md)**
+
 ### Accessing the Odac Object
 
 Full access to the Odac object in templates:
@@ -161,11 +178,10 @@ Full access to the Odac object in templates:
 | Continue | `<odac:continue />` | [Loops](./06-loops.md) |
 | JavaScript | `<script:odac>...</script:odac>` | [Backend JavaScript](./08-backend-javascript.md) |
 | Comment | `<!--odac ... odac-->` | [Comments](./09-comments.md) |
+| Image | `<odac:img src="..." />` | [Image Optimization](./11-image-optimization.md) |
 
 ### Legacy Syntax
 
-Odac also supports legacy syntax for backward compatibility:
-
 ```html
 <!-- Variable output -->
 {{ username }}