odac 1.4.3 → 1.4.5

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/backend/views.md

@@ -14,12 +14,18 @@ Views in ODAC are logic-light but powerful. They support automatic XSS protectio
 
 ## Core Rules
 1.  **Skeleton Architecture**: Use `Odac.View.skeleton('name')` to wrap content in a layout.
-2.  **Data Binding**:
-    -   `{{ key }}`: Escaped output (Standard).
-    -   `{!! key !!}`: Raw output (Use with extreme caution).
-3.  **Conditionals**: Use `<odac:if condition="VAR"> ... </odac:if>`.
-4.  **Looping**: Use `<odac:for in="ARRAY" value="ITEM"> ... </odac:for>` or the performance-optimized `[[odac_for ...]]`.
-5.  **Server-Side JS**: Use `<script:odac>` for complex calculations during rendering.
+2.  **Data Binding — Two Equivalent Syntaxes**:
+    -   `<odac var="key" />`: Tag-based output (HTML-escaped, XSS-safe).
+    -   `{{ key }}`: Inline/interpolation output (HTML-escaped, XSS-safe). Identical behavior to `<odac var>`.
+    -   `<odac var="key" raw />` or `{!! key !!}`: Raw output (Use with extreme caution).
+3.  **Choosing the Right Syntax**:
+    -   **Inside HTML attributes** (`src`, `alt`, `href`, `class`, `value`, etc.) → Always prefer `{{ }}`. It reads naturally and keeps markup clean.
+    -   **Inline within text or mixed HTML** → Prefer `{{ }}` for short interpolations.
+    -   **Standalone block output** (the variable is the only content of an element) → Prefer `<odac var="" />` for structural clarity and IDE support.
+    -   Both syntaxes compile to the same engine output. The choice is about readability, not functionality.
+4.  **Conditionals**: Use `<odac:if condition="VAR"> ... </odac:if>`.
+5.  **Looping**: Use `<odac:for in="ARRAY" value="ITEM"> ... </odac:for>` or the performance-optimized `[[odac_for ...]]`.
+6.  **Server-Side JS**: Use `<script:odac>` for complex calculations during rendering.
 
 ## Reference Patterns
 
@@ -35,8 +41,17 @@ Odac.View.set({
 
 ### 2. Template Syntax Reference
 ```html
-<!-- Display Variable -->
-<h1>{{ title }}</h1>
+<!-- Standalone block output — prefer <odac var> -->
+<h1><odac var="title" /></h1>
+
+<!-- Inside attributes — prefer {{ }} -->
+<img src="{{ product.image }}" alt="{{ product.name }}">
+<a href="/user/{{ user.id }}" class="btn {{ isActive ? 'active' : '' }}">Profile</a>
+<input type="text" value="{{ query }}">
+
+<!-- Inline text interpolation — prefer {{ }} -->
+<p>Welcome, {{ user.name }}. You have {{ notifications }} new messages.</p>
+<span>${{ product.price }}</span>
 
 <!-- Conditional -->
 <odac:if condition="stats.users > 100">
@@ -62,7 +77,17 @@ Perfect for calculations that shouldn't clutter the controller but are too compl
 <p>Tax: ${{ tax }}</p>
 ```
 
+## Syntax Selection Guide
+
+| Context | Preferred Syntax | Example |
+|---------|-----------------|---------|
+| HTML attributes (`src`, `href`, `alt`, `class`, `value`) | `{{ }}` | `<img src="{{ photo.url }}" alt="{{ photo.caption }}">` |
+| Inline text within elements | `{{ }}` | `<p>Hello, {{ user.name }}</p>` |
+| Standalone element content | `<odac var />` | `<h1><odac var="title" /></h1>` |
+| Raw HTML output (trusted only) | `<odac var raw />` or `{!! !!}` | `<div><odac var="content" raw /></div>` |
+
 ## Security Best Practices
--   **Always use `{{ }}`**: Standard tags prevent XSS.
+-   **Both `{{ }}` and `<odac var>` are XSS-safe**: Both apply HTML escaping by default. Use either with confidence.
+-   **Raw output requires trust**: Only use `raw` / `{!! !!}` with content you fully control. Never with user input.
 -   **Limit `<script:odac>`**: Do not perform database queries or API calls inside views; keep them in the controller.
 -   **Partial Awareness**: Use `<odac:include view="path.to.view" />` for reusable components.

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

@@ -2,7 +2,7 @@
 name: frontend-navigation-spa-skill
 description: Single-page navigation patterns in odac.js for smooth transitions, route control, and lifecycle-safe execution.
 metadata:
-  tags: frontend, navigation, spa, ajax-navigation, page-lifecycle, transitions
+  tags: frontend, navigation, spa, ajax-navigation, page-lifecycle, transitions, view-transitions
 ---
 
 # Frontend Navigation & SPA Skill
@@ -13,6 +13,7 @@ Smooth transitions and single-page application behavior using `odac.js`.
 1.  **Selection**: Enable via `Odac.action({ navigate: 'main' })`.
 2.  **Exclusion**: Use `data-navigate="false"` or `.no-navigate` class for full reloads.
 3.  **Lifecycle**: Use `load` and `page` events to run code after navigation.
+4.  **View Transitions**: Add `odac-transition` attribute to elements for native browser View Transition API animations. Zero-config — no JS setup required.
 
 ## Patterns
 ```javascript
@@ -25,3 +26,46 @@ Odac.action({
   }
 });
 ```
+
+## View Transitions (Native Browser API)
+
+Elements with the `odac-transition` attribute automatically use the browser's View Transition API instead of the legacy fade animation. The attribute value becomes the `view-transition-name`, enabling per-element morphing between pages.
+
+### HTML Usage
+```html
+<header odac-transition="header">Site Header</header>
+<nav odac-transition="sidebar">Navigation</nav>
+<main>Content updated by AJAX loader</main>
+<img odac-transition="hero" src="/hero.jpg" />
+```
+
+### Behavior
+- When `odac-transition` elements exist and the browser supports View Transition API → native transition is used.
+- When no `odac-transition` elements exist or the API is unsupported → legacy fade fallback runs automatically.
+- Transition names are applied before the snapshot and cleaned up after the transition completes.
+- The attribute value must be unique per page (browser requirement for `view-transition-name`).
+
+### CSS Customization
+```css
+/* Target a specific element's transition */
+::view-transition-old(hero) {
+  animation: fade-out 0.3s ease;
+}
+::view-transition-new(hero) {
+  animation: fade-in 0.3s ease;
+}
+
+/* Slide sidebar from left */
+::view-transition-old(sidebar) {
+  animation: slide-out-left 0.25s ease;
+}
+::view-transition-new(sidebar) {
+  animation: slide-in-left 0.25s ease;
+}
+```
+
+### Rules
+1. Each `odac-transition` value must be unique within the page.
+2. Elements persist across navigations (e.g., shared header) for smooth morphing.
+3. No JavaScript configuration needed — attribute-only setup.
+4. Falls back to fade animation gracefully on unsupported browsers.

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

@@ -1,8 +1,17 @@
 ## 🔧 Template Syntax Overview
 
-Odac uses a powerful template engine to create dynamic content in view files. The engine provides a clean, HTML-like syntax for displaying variables, conditionals, loops, translations, and more.
+Odac uses a powerful template engine to create dynamic content in view files. The engine provides two equivalent syntaxes for displaying variables, plus dedicated tags for conditionals, loops, translations, and more.
 
-> **Note:** Odac also supports legacy syntax (`{{ }}`, `{!! !!}`, `{{-- --}}`) for backward compatibility, but the new `<odac>` tag syntax is recommended for all new projects.
+### Two Syntaxes, One Engine
+
+ODAC offers two ways to output variables. Both are HTML-escaped (XSS-safe) and compile to the same engine code. The choice is about readability, not functionality.
+
+| Syntax | Best For | Example |
+|--------|----------|---------|
+| `<odac var="x" />` | Standalone block output where the variable is the main content | `<h1><odac var="title" /></h1>` |
+| `{{ x }}` | Attributes, inline text, and mixed HTML where tag syntax would be verbose | `<img src="{{ photo.url }}" alt="{{ photo.caption }}">` |
+
+> **Guideline:** Use `{{ }}` inside HTML attributes (`src`, `href`, `alt`, `class`, `value`, etc.) and for inline text interpolation. Use `<odac var>` for standalone element content. Both are equally supported and recommended.
 
 ### Quick Reference
 
@@ -13,10 +22,17 @@ This page provides a quick overview of all available template features. For deta
 Display data passed from controllers using `Odac.set()`:
 
 ```html
-<!-- HTML-safe output -->
-<odac var="username" />
+<!-- Standalone block output — prefer <odac var> -->
+<h1><odac var="username" /></h1>
+
+<!-- Inside attributes — prefer {{ }} -->
+<img src="{{ product.image }}" alt="{{ product.name }}">
+<a href="/user/{{ user.id }}">Profile</a>
 
-<!-- Raw HTML output -->
+<!-- Inline text — prefer {{ }} -->
+<p>Welcome, {{ user.name }}. You have {{ count }} items.</p>
+
+<!-- Raw HTML output (trusted content only) -->
 <odac var="htmlContent" raw />
 
 <!-- String literals -->
@@ -130,6 +146,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:
@@ -146,8 +179,10 @@ Full access to the Odac object in templates:
 
 | Feature | Syntax | Documentation |
 |---------|--------|---------------|
-| Variable (Controller) | `<odac var="x" />` | [Variables](./03-variables.md) |
-| Raw HTML | `<odac var="x" raw />` | [Variables](./03-variables.md) |
+| Variable (standalone) | `<odac var="x" />` | [Variables](./03-variables.md) |
+| Variable (inline/attribute) | `{{ x }}` | [Variables](./03-variables.md) |
+| Raw HTML (tag) | `<odac var="x" raw />` | [Variables](./03-variables.md) |
+| Raw HTML (inline) | `{!! x !!}` | [Variables](./03-variables.md) |
 | String | `<odac>text</odac>` | [Variables](./03-variables.md) |
 | Query Parameter | `<odac get="key" />` | [Request Data](./04-request-data.md) |
 | Translation | `<odac translate>key</odac>` | [Translations](./07-translations.md) |
@@ -161,21 +196,36 @@ 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
+### Syntax Selection Guide
 
-Odac also supports legacy syntax for backward compatibility:
+Choose the right syntax based on context for clean, readable templates:
 
 ```html
-<!-- Variable output -->
-{{ username }}
+<!-- ✅ Attributes — use {{ }} -->
+<img src="{{ product.image }}" alt="{{ product.name }}">
+<a href="/products/{{ product.id }}" class="card {{ isActive ? 'active' : '' }}">
+<input type="text" name="search" value="{{ query }}">
+
+<!-- ✅ Inline text — use {{ }} -->
+<p>Hello, {{ user.name }}. You have {{ count }} notifications.</p>
+<span>${{ product.price }}</span>
+
+<!-- ✅ Standalone block content — use <odac var> -->
+<h1><odac var="pageTitle" /></h1>
+<td><odac var="user.email" /></td>
+
+<!-- ✅ Raw output — either form works -->
+<div><odac var="richContent" raw /></div>
+<div>{!! richContent !!}</div>
+```
 
-<!-- Raw HTML -->
-{!! htmlContent !!}
+### Legacy Comment Syntax
 
-<!-- Comments -->
+```html
 {{-- This is a comment --}}
 ```
 
-**Note:** The new `<odac>` tag syntax is recommended for all new projects.
+**Note:** For new projects, prefer the `<!--odac ... odac-->` comment syntax for consistency.
 

package/docs/backend/07-views/03-variables.md

@@ -311,18 +311,33 @@ module.exports = async function(Odac) {
 </odac:if>
 ```
 
-### Legacy Syntax (Backward Compatibility)
+### Inline Syntax (`{{ }}` and `{!! !!}`)
 
-Odac also supports legacy syntax:
+ODAC provides an inline interpolation syntax that is equivalent to the `<odac var>` tag. Both compile to the same engine output and are equally supported.
+
+**Use `{{ }}` when the variable appears inside HTML attributes or inline within text:**
 
 ```html
-<!-- HTML-safe output -->
-{{ username }}
-{{ user.email }}
+<!-- Inside attributes — {{ }} keeps markup clean -->
+<img src="{{ product.image }}" alt="{{ product.name }}">
+<a href="/user/{{ user.id }}" class="btn {{ isActive ? 'active' : '' }}">Profile</a>
+<input type="text" name="q" value="{{ searchQuery }}">
+
+<!-- Inline text interpolation -->
+<p>Welcome, {{ user.name }}. You have {{ notifications }} new messages.</p>
+<span>${{ product.price }}</span>
 
-<!-- Raw HTML output -->
+<!-- Raw inline output (trusted content only) -->
 {!! htmlContent !!}
 {!! user.bio !!}
 ```
 
-**Note:** The new `<odac>` tag syntax is recommended for all new projects as it provides better IDE support and readability.
+**Use `<odac var>` when the variable is the standalone content of an element:**
+
+```html
+<h1><odac var="pageTitle" /></h1>
+<td><odac var="user.email" /></td>
+<p><odac var="product.description" /></p>
+```
+
+Both syntaxes are XSS-safe by default (HTML-escaped). The choice is purely about readability. See [Template Syntax Overview](./03-template-syntax.md) for the full selection guide.

package/docs/backend/07-views/11-image-optimization.md

@@ -0,0 +1,197 @@
+## 🖼️ Image Optimization
+
+ODAC provides automatic image optimization through the `<odac:img>` tag. Images are resized, converted to modern formats (WebP, AVIF), and cached — all on-demand, with zero configuration required.
+
+> **Note:** Image optimization requires the `sharp` package. Install it with `npm install sharp`. Without it, `<odac:img>` gracefully falls back to a standard `<img>` tag with no processing.
+
+### Basic Usage
+
+The simplest usage — just provide a `src`. ODAC automatically converts the image to WebP:
+
+```html
+<odac:img src="/images/hero.jpg" />
+```
+
+This is equivalent to writing:
+
+```html
+<img src="/_odac/img/hero-o-a1b2c3d4.webp">
+```
+
+The processed image is cached after the first request. All subsequent requests are served instantly.
+
+### Resize
+
+Specify `width` and/or `height` to resize the image. Aspect ratio is always preserved — the image will never be stretched or enlarged beyond its original size:
+
+```html
+<!-- Resize by width only -->
+<odac:img src="/images/hero.jpg" width="800" />
+
+<!-- Resize by both dimensions (fits inside the box) -->
+<odac:img src="/images/hero.jpg" width="800" height="600" />
+
+<!-- Thumbnail -->
+<odac:img src="/images/product.jpg" width="200" height="200" />
+```
+
+### Format Conversion
+
+Convert to any modern format using the `format` attribute:
+
+```html
+<!-- WebP (default) -->
+<odac:img src="/images/photo.png" format="webp" />
+
+<!-- AVIF (best compression, newer browsers) -->
+<odac:img src="/images/photo.png" format="avif" />
+
+<!-- Keep as PNG -->
+<odac:img src="/images/logo.png" format="png" />
+```
+
+**Supported formats:** `webp`, `avif`, `png`, `jpeg`, `tiff`
+
+### Quality
+
+Control the compression quality with the `quality` attribute (1–100, default: 80):
+
+```html
+<!-- High quality for hero images -->
+<odac:img src="/images/banner.jpg" width="1200" quality="90" />
+
+<!-- Lower quality for thumbnails (smaller file size) -->
+<odac:img src="/images/thumb.jpg" width="100" quality="60" />
+```
+
+### Standard HTML Attributes
+
+All standard `<img>` attributes are passed through as-is:
+
+```html
+<odac:img
+  src="/images/avatar.jpg"
+  width="64"
+  height="64"
+  alt="User avatar"
+  class="rounded-full"
+  loading="lazy"
+  decoding="async"
+/>
+```
+
+### Dynamic Source
+
+Use template variables for dynamic image sources:
+
+```html
+<!-- From controller data -->
+<odac:img src="{{ product.image }}" width="300" height="300" alt="{{ product.name }}" />
+
+<!-- In a loop -->
+<odac:for in="products" value="product">
+  <odac:img src="{{ product.thumbnail }}" width="200" alt="{{ product.name }}" />
+</odac:for>
+```
+
+### Practical Examples
+
+#### Product Card
+
+```html
+<div class="product-card">
+  <odac:img
+    src="{{ product.image }}"
+    width="400"
+    height="300"
+    alt="{{ product.name }}"
+    class="product-image"
+    loading="lazy"
+  />
+  <h3><odac var="product.name" /></h3>
+  <p>$<odac var="product.price" /></p>
+</div>
+```
+
+#### Hero Banner
+
+```html
+<section class="hero">
+  <odac:img
+    src="/images/hero.jpg"
+    width="1920"
+    height="600"
+    alt="Hero banner"
+    class="hero-image"
+    quality="90"
+  />
+</section>
+```
+
+#### Avatar with Fallback
+
+```html
+<odac:if condition="user.avatar">
+  <odac:img src="{{ user.avatar }}" width="64" height="64" alt="Avatar" class="avatar" />
+<odac:else>
+  <img src="/images/default-avatar.png" width="64" height="64" alt="Default avatar" class="avatar">
+</odac:if>
+```
+
+#### Image Gallery
+
+```html
+<div class="gallery">
+  <odac:for in="photos" value="photo">
+    <a href="{{ photo.url }}">
+      <odac:img
+        src="{{ photo.url }}"
+        width="400"
+        height="300"
+        alt="{{ photo.caption }}"
+        class="gallery-thumb"
+        loading="lazy"
+      />
+    </a>
+  </odac:for>
+</div>
+```
+
+### Configuration
+
+You can override the defaults in `odac.json`:
+
+```json
+{
+  "image": {
+    "format": "webp",
+    "quality": 80,
+    "maxDimension": 4096
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `format` | `webp` | Default output format when `format` is not specified in the tag |
+| `quality` | `80` | Default compression quality (1–100) |
+| `maxDimension` | `4096` | Maximum allowed width or height in pixels |
+
+### How It Works
+
+1. The `<odac:img>` tag is compiled at template render time.
+2. ODAC checks the source file's modification time (`mtime`) and includes it in the hash. This means when you update a source image, the URL automatically changes — no manual cache busting needed.
+3. On the first request, ODAC processes the source image using `sharp` and saves the result to `storage/.cache/img/`.
+4. The `<img>` tag in the HTML points to `/_odac/img/{name}-{dimension}-{hash}.{ext}` — an internal route that serves the cached file. The filename includes the original image name and dimension for easy debugging.
+5. All subsequent requests hit the cache directly, with `Cache-Control: immutable` headers for maximum browser caching.
+
+> **Cache Busting:** You don't need to rename files or add query strings. Simply replace the source image in `public/` and the next page render will produce a new URL with a different hash, forcing browsers and CDNs to fetch the updated version.
+
+### Best Practices
+
+- Always set `alt` for accessibility.
+- Use `loading="lazy"` for below-the-fold images to improve page load performance.
+- Set explicit `width` and `height` to prevent layout shift (CLS).
+- Keep original high-resolution images in `public/` — let ODAC handle the downsizing.
+- Use `avif` for the best compression ratio on modern browsers; use `webp` for broader compatibility.
+- For programmatic URL access in controllers (JSON APIs, CSS backgrounds, emails), see [`Odac.image()`](../05-controllers/02-your-trusty-odac-assistant.md#image-processing).

package/docs/frontend/02-ajax-navigation/01-quick-start.md

@@ -6,6 +6,7 @@ Odac framework includes a built-in AJAX navigation system that enables smooth, s
 
 - **Zero Configuration**: Works automatically with all internal links (`/`)
 - **Smooth Transitions**: Load only specific page sections without full page reload
+- **Native View Transitions**: Automatic browser View Transition API support via `odac-transition` attribute
 - **History API Integration**: Browser back/forward buttons work seamlessly
 - **Automatic Token Management**: CSRF tokens are handled automatically
 - **Progressive Enhancement**: Falls back to normal navigation if JavaScript fails
@@ -178,6 +179,27 @@ module.exports = function (Odac) {
 5. Browser URL updates via History API
 6. Page-specific callbacks execute
 
+### View Transition Load (with `odac-transition` elements)
+
+When elements with `odac-transition` attribute exist on the page and the browser supports the View Transition API, ODAC uses native transitions instead of fade:
+
+1. User clicks `<a href="/about">`
+2. ODAC assigns `view-transition-name` to all `odac-transition` elements (old state snapshot)
+3. AJAX request is sent (same as above)
+4. `document.startViewTransition()` is called — browser captures old state
+5. DOM is updated with new content inside the transition callback
+6. New `odac-transition` elements receive their names
+7. Browser animates between old and new snapshots
+8. Transition names are cleaned up after completion
+
+No configuration needed — just add the attribute to your HTML:
+
+```html
+<header odac-transition="header">{{ HEADER }}</header>
+<main>{{ CONTENT }}</main>
+<img odac-transition="hero" src="/hero.jpg" alt="Hero" />
+```
+
 **Key Points:**
 - The `output` keys in the JSON response match the lowercase keys from `Odac.View.set()` in your controller
 - These keys correspond to UPPERCASE placeholders in your skeleton (e.g., `content` → `{{ CONTENT }}`)