odac 1.4.4 → 1.4.6

package/.agent/rules/memory.md

@@ -32,12 +32,14 @@ trigger: always_on
 
 ## 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.
+- **Hybrid Overrides:** When using `overrides` in `package.json` for security hardening, always verify tool compatibility (especially Jest/Coverage). If a global override (e.g., `minimatch: 10.x`) breaks a critical utility (e.g., `test-exclude`), use a nested override to provide a compatible version (e.g., `3.x`) for that specific tool while keeping the rest of the project secure.
 
 ## 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).
+- **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 +55,11 @@ 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.
+- **Template String Escaping:** When escaping template strings for inline JavaScript execution or translation payloads, always escape backslashes first before escaping single quotes (e.g., `.replace(/\\/g, '\\\\').replace(/'/g, "\\'")`) to prevent an injected backslash from disabling the quote escape and causing a Template Injection / XSS vulnerability.
+
+## View Engine & SSR
+- **Auto-Navigation Injection:** The ODAC View engine (`src/View.js`) automatically parses skeleton HTML files and dynamically injects `data-odac-navigate` attributes into ALL elements wrapping `{{ PART_NAME }}` placeholders (e.g. `{{ CONTENT }}`, `{{ SIDEBAR }}`, `{{ FOOTER }}`). Do NOT manually add these attributes to HTML templates.
+- **Smart Part Diffing (AJAX Navigation):** The AJAX navigation system uses a server-driven part diffing mechanism. The client sends its current part values via `X-Odac-Parts` header (e.g. `content=docs/intro,sidebar=docs/nav`). The server compares these with the new page's parts and only renders/returns parts whose view path has changed. Parts that are identical between pages are skipped (no re-render, no DOM update). Parts that exist on the old page but not the new page are cleared. The `parts` manifest is included in every AJAX response for the client to track state. **Exception:** The `content` part is always re-rendered regardless of view path match, since its output is URL-dependent.
+- **Part Refresh Override:** `View.set('partName', 'viewPath', { refresh: true })` forces a part to re-render on every AJAX navigation even if its view path hasn't changed. Useful for parts with request-dependent dynamic content (e.g. active menu state). The `#refresh` Set tracks which parts bypass the diffing comparison.
+- **Initial Parts State:** On first page load, the `<html>` tag receives a `data-odac-parts` JSON attribute containing the current part-to-view mapping. The client reads this to initialize its parts tracking state for subsequent AJAX navigations.

package/.releaserc.js

@@ -135,7 +135,7 @@ Powered by [⚡ ODAC](https://odac.run)
     [
       '@semantic-release/git',
       {
-        assets: ['package.json', 'CHANGELOG.md'],
+        assets: ['package.json', 'package-lock.json', 'CHANGELOG.md'],
         message: '⚡ ODAC.JS v${nextRelease.version} Released'
       }
     ],

package/CHANGELOG.md

@@ -1,3 +1,53 @@
+### ⚙️ Engine Tuning
+
+- replace global Odac reference with private instance and update dependency overrides for security hardening
+- **test/view:** remove unused CACHE_DIR variable in parseOdacTag tests
+
+### ✨ What's New
+
+- **client:** log malformed data-odac-parts JSON to ease debugging
+- **view:** smart AJAX part diffing with selective re-render
+
+### 🛠️ Fixes & Improvements
+
+- **route:** encode X-Odac-Parts header values to prevent splitting errors
+- **View:** escape single quotes in template expressions to prevent syntax errors
+- **view:** prevent template injection by escaping backslashes in dynamic parser
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### 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.

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

@@ -119,7 +119,7 @@ if (typeof window !== 'undefined') {
     #page = null
     #token = {hash: [], data: false}
     #formSubmitHandlers = new Map()
-    #loader = {elements: {}, callback: null}
+    #loader = {elements: {}, callback: null, parts: {}}
     #isNavigating = false
 
     constructor() {
@@ -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
 
@@ -731,82 +772,188 @@ if (typeof window !== 'undefined') {
       this.#isNavigating = true
 
       const currentSkeleton = document.documentElement.dataset.odacSkeleton
-      const elements = Object.entries(this.#loader.elements)
 
-      const elementsToUpdate = []
-      elements.forEach(([key, selector]) => {
-        const element = document.querySelector(selector)
-        if (element) elementsToUpdate.push({key, element})
+      // Merge loader-registered elements with auto-discovered navigate elements
+      const elements = {...this.#loader.elements}
+      document.querySelectorAll('[data-odac-navigate]').forEach(el => {
+        const partName = el.getAttribute('data-odac-navigate')
+        if (!elements[partName]) elements[partName] = `[data-odac-navigate="${partName}"]`
       })
 
-      let ajaxData = null,
-        ajaxXhr = null,
-        fadeOutComplete = false,
-        ajaxComplete = false
+      const elementsToUpdate = []
+      for (const [key, selector] of Object.entries(elements)) {
+        const element = document.querySelector(selector)
+        if (element) elementsToUpdate.push({key, element, selector})
+      }
 
-      const applyUpdate = () => {
-        if (!fadeOutComplete || !ajaxComplete || !ajaxData) return
+      // Build X-Odac-Parts header from current known parts
+      const partsHeader = Object.entries(this.#loader.parts)
+        .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+        .join(',')
 
-        const finalUrl = ajaxXhr.responseURL || url
-        if (ajaxData.skeletonChanged) {
-          window.location.href = finalUrl
-          return
-        }
-        if (finalUrl !== currentUrl && push) window.history.pushState(null, document.title, finalUrl)
+      // Collect part keys to request from server
+      const loadKeys = Object.keys(elements)
 
-        const newPage = ajaxXhr.getResponseHeader('X-Odac-Page')
-        if (newPage !== null) {
-          this.#page = newPage
-          document.documentElement.dataset.odacPage = newPage
-        }
+      const useViewTransition = document.startViewTransition && document.querySelectorAll('[odac-transition]').length > 0
 
-        if (ajaxData.data) this.#data = ajaxData.data
-        if (ajaxData.title) document.title = ajaxData.title
+      if (useViewTransition) {
+        this.#loadWithViewTransition(url, callback, push, currentUrl, currentSkeleton, elementsToUpdate, partsHeader, loadKeys)
+      } else {
+        this.#loadWithFade(url, callback, push, currentUrl, currentSkeleton, elementsToUpdate, partsHeader, loadKeys)
+      }
+    }
 
-        if (elementsToUpdate.length === 0) {
-          this.#handleLoadComplete(ajaxData, callback)
-          return
-        }
+    /**
+     * 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, partsHeader, loadKeys) {
+      const oldTransitionElements = this.#applyTransitionNames()
 
-        let completed = 0
-        elementsToUpdate.forEach(({key, element}) => {
-          if (ajaxData.output && ajaxData.output[key] !== undefined) element.innerHTML = ajaxData.output[key]
-          this.#fadeIn(element, 200, () => {
-            completed++
-            if (completed === elementsToUpdate.length) this.#handleLoadComplete(ajaxData, callback)
-          })
-        })
+      const headers = {
+        'X-Odac': 'ajaxload',
+        'X-Odac-Load': loadKeys.join(','),
+        'X-Odac-Skeleton': currentSkeleton || ''
       }
+      if (partsHeader) headers['X-Odac-Parts'] = partsHeader
+
+      this.#ajax({
+        url,
+        type: 'GET',
+        headers,
+        dataType: 'json',
+        success: (data, status, xhr) => {
+          const finalUrl = xhr.responseURL || url
+          if (data.skeletonChanged) {
+            this.#clearTransitionNames(oldTransitionElements)
+            window.location.href = finalUrl
+            return
+          }
 
-      if (elementsToUpdate.length > 0) {
-        let fadeOutCount = 0
-        elementsToUpdate.forEach(({element}) => {
-          this.#fadeOut(element, 200, () => {
-            fadeOutCount++
-            if (fadeOutCount === elementsToUpdate.length) {
-              fadeOutComplete = true
-              applyUpdate()
+          // Update tracked parts from server manifest
+          if (data.parts) this.#loader.parts = data.parts
+
+          // Determine which parts were removed by the new page
+          const removedParts = []
+          for (const {key, element} of elementsToUpdate) {
+            if (data.parts && !(key in data.parts)) removedParts.push({key, element})
+          }
+
+          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)
+
+            // Update only parts that have new content from server
+            elementsToUpdate.forEach(({key, element}) => {
+              if (data.output && data.output[key] !== undefined) element.innerHTML = data.output[key]
+            })
+
+            // Clear removed parts
+            for (const {element} of removedParts) {
+              element.innerHTML = ''
+            }
+
+            this.#applyTransitionNames()
           })
-        })
-      } else {
-        fadeOutComplete = true
+
+          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.
+     * Only fades elements whose content actually changed, leaving unchanged
+     * parts (like a shared sidebar) completely untouched and visible.
+     */
+    #loadWithFade(url, callback, push, currentUrl, currentSkeleton, elementsToUpdate, partsHeader, loadKeys) {
+      const headers = {
+        'X-Odac': 'ajaxload',
+        'X-Odac-Load': loadKeys.join(','),
+        'X-Odac-Skeleton': currentSkeleton || ''
       }
+      if (partsHeader) headers['X-Odac-Parts'] = partsHeader
 
       this.#ajax({
-        url: url,
+        url,
         type: 'GET',
-        headers: {
-          'X-Odac': 'ajaxload',
-          'X-Odac-Load': Object.keys(this.#loader.elements).join(','),
-          'X-Odac-Skeleton': currentSkeleton || ''
-        },
+        headers,
         dataType: 'json',
         success: (data, status, xhr) => {
-          ajaxData = data
-          ajaxXhr = xhr
-          ajaxComplete = true
-          applyUpdate()
+          const finalUrl = xhr.responseURL || url
+          if (data.skeletonChanged) {
+            window.location.href = finalUrl
+            return
+          }
+          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)
+          if (data.parts) this.#loader.parts = data.parts
+
+          // Classify elements: changed, removed, or unchanged
+          const changedParts = []
+          const removedParts = []
+
+          for (const {key, element} of elementsToUpdate) {
+            if (data.output && data.output[key] !== undefined) {
+              changedParts.push({key, element})
+            } else if (data.parts && !(key in data.parts)) {
+              removedParts.push({key, element})
+            }
+          }
+
+          // Clear removed parts immediately
+          for (const {element} of removedParts) {
+            element.innerHTML = ''
+          }
+
+          // No changed parts — complete immediately
+          if (changedParts.length === 0) {
+            this.#handleLoadComplete(data, callback)
+            return
+          }
+
+          // Fade out only changed parts, then swap content and fade in
+          let fadeOutCount = 0
+          changedParts.forEach(({key, element}) => {
+            this.#fadeOut(element, 200, () => {
+              element.innerHTML = data.output[key]
+              this.#fadeIn(element, 200, () => {
+                fadeOutCount++
+                if (fadeOutCount === changedParts.length) this.#handleLoadComplete(data, callback)
+              })
+            })
+          })
         },
         error: () => {
           this.#isNavigating = false
@@ -855,9 +1002,10 @@ if (typeof window !== 'undefined') {
       }
     }
 
-    loader(selector, elements, callback) {
+    loader(selector, elements, callback, initialParts) {
       this.#loader.elements = elements
       this.#loader.callback = callback
+      if (initialParts) this.#loader.parts = initialParts
       const odacInstance = this
 
       this.#on(document, 'click', selector, function (e) {
@@ -1033,10 +1181,28 @@ if (typeof window !== 'undefined') {
   window.Odac = new _odac()
   ;(function initAutoNavigate() {
     const init = () => {
-      const contentEl = document.querySelector('[data-odac-navigate="content"]')
-      if (contentEl) {
-        window.Odac.loader('a[href^="/"]:not([data-navigate="false"]):not(.no-navigate)', {content: '[data-odac-navigate="content"]'}, null)
+      const navigateElements = document.querySelectorAll('[data-odac-navigate]')
+      if (navigateElements.length === 0) return
+
+      const elements = {}
+      navigateElements.forEach(el => {
+        const partName = el.getAttribute('data-odac-navigate')
+        elements[partName] = `[data-odac-navigate="${partName}"]`
+      })
+
+      // Initialize parts state from server-rendered data attribute
+      const partsAttr = document.documentElement.dataset.odacParts
+      let initialParts = {}
+      if (partsAttr) {
+        try {
+          initialParts = JSON.parse(partsAttr)
+        } catch (e) {
+          console.error('Odac: Failed to parse data-odac-parts attribute.', e)
+          // Graceful fallback if attribute is malformed
+        }
       }
+
+      window.Odac.loader('a[href^="/"]:not([data-navigate="false"]):not(.no-navigate)', elements, null, initialParts)
     }
     document.readyState === 'loading' ? document.addEventListener('DOMContentLoaded', init) : init()
   })()

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

@@ -1,61 +1,133 @@
 ---
 name: backend-views-templates-skill
-description: ODAC server-side rendering guidelines for template performance, skeleton layouts, and safe output rendering.
+description: ODAC server-side rendering guidelines for skeleton layouts, smart part diffing, template syntax, and safe output rendering.
 metadata:
-  tags: backend, views, templates, ssr, xss-protection, skeleton, rendering
+  tags: backend, views, templates, ssr, xss-protection, skeleton, rendering, part-diffing, ajax-navigation
 ---
 
 # Backend Views & Templates Skill
 
-High-performance server-side rendering using ODAC's optimized template engine.
+High-performance server-side rendering using ODAC's optimized template engine with smart AJAX part diffing.
 
 ## Architectural Approach
-Views in ODAC are logic-light but powerful. They support automatic XSS protection, high-performance looping, and server-side JavaScript execution via `<script:odac>`.
+Views in ODAC are logic-light but powerful. They support automatic XSS protection, high-performance looping, server-side JavaScript execution via `<script:odac>`, and a smart AJAX navigation system that only updates parts of the page that actually changed.
 
 ## 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.  **Part Setting**: Use `Odac.View.set(partName, viewPath)` to fill skeleton placeholders.
+3.  **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).
+4.  **Choosing the Right Syntax**:
+    -   **Inside HTML attributes** (`src`, `alt`, `href`, `class`, `value`, etc.) → Always prefer `{{ }}`.
+    -   **Inline within text or mixed HTML** → Prefer `{{ }}` for short interpolations.
+    -   **Standalone block output** → Prefer `<odac var="" />` for structural clarity.
+5.  **Conditionals**: Use `<odac:if condition="VAR"> ... </odac:if>`.
+6.  **Looping**: Use `<odac:for in="ARRAY" value="ITEM"> ... </odac:for>`.
+7.  **Server-Side JS**: Use `<script:odac>` for complex calculations during rendering.
+
+## Smart Part Diffing (AJAX Navigation)
+
+ODAC uses a **server-driven part diffing** system during AJAX navigation. Understanding this is critical for building multi-section layouts correctly.
+
+### How it works
+- The client tracks which view file each part is currently showing.
+- On every AJAX navigation, it sends this state to the server via `X-Odac-Parts`.
+- The server compares the new page's parts against the client's current state and **only renders parts that changed**.
+- The client only updates DOM elements that received new content.
+
+### Rules
+| Scenario | Behavior |
+|----------|----------|
+| Part view path unchanged | Skipped — not re-rendered, DOM untouched |
+| Part view path changed | Re-rendered and DOM updated |
+| Part removed on new page | DOM element content cleared |
+| Skeleton changed | Full page reload |
+| `content` part | **Always** re-rendered (URL-dependent by nature) |
+
+### Force-refresh a part
+If a part's view path stays the same but its rendered output changes per request (e.g. a sidebar with an active menu state):
+
+```javascript
+// Always re-renders on AJAX navigation even if view path is unchanged
+Odac.View.set('sidebar', 'docs.nav', { refresh: true })
+```
+
+### Skeleton placeholder rules
+- Each `{{ PLACEHOLDER }}` must be wrapped in its own HTML element.
+- The engine auto-injects `data-odac-navigate` on wrapper elements — do not add manually.
+- Unset placeholders are silently removed from the final HTML output.
+
+```html
+<!-- skeleton/main.html -->
+<aside>{{ SIDEBAR }}</aside>   <!-- auto-gets data-odac-navigate="sidebar" -->
+<main>{{ CONTENT }}</main>     <!-- auto-gets data-odac-navigate="content" -->
+```
 
 ## Reference Patterns
 
-### 1. The Controller to View Flow
+### 1. Standard Page with Shared Layout
+```javascript
+// controller/docs/page.js
+module.exports = function (Odac) {
+  Odac.View
+    .skeleton('main')
+    .set('sidebar', 'docs.nav')   // shared — skipped if unchanged on next navigate
+    .set('content', 'docs.intro') // always re-rendered
+}
+```
+
+### 2. Sidebar with Active State (force refresh)
 ```javascript
-// Controller
-Odac.View.skeleton('main');
-Odac.View.set({
-  title: 'Dashboard',
-  stats: { users: 150, orders: 45 }
-});
+// controller/docs/page.js
+module.exports = function (Odac) {
+  Odac.View
+    .skeleton('main')
+    .set('sidebar', 'docs.nav', { refresh: true }) // re-renders every navigate
+    .set('content', 'docs.intro')
+}
 ```
 
-### 2. Template Syntax Reference
+### 3. Page Without Sidebar
+```javascript
+// controller/home.js — navigating here clears the sidebar DOM element
+module.exports = function (Odac) {
+  Odac.View
+    .skeleton('main')
+    .set('content', 'home')
+  // sidebar not set → its DOM element is emptied on AJAX navigation
+}
+```
+
+### 4. 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>
+
+<!-- Inline text interpolation -->
+<p>Welcome, {{ user.name }}. You have {{ notifications }} new messages.</p>
 
 <!-- Conditional -->
 <odac:if condition="stats.users > 100">
   <span class="badge">Popular!</span>
 </odac:if>
 
-<!-- Performance Loop -->
-[[odac_for user in users]]
+<!-- Loop -->
+<odac:for in="users" value="user">
   <li>{{ user.name }}</li>
-[[odac_endfor]]
+</odac:for>
 ```
 
-### 3. Backend JavaScript (`<script:odac>`)
-Perfect for calculations that shouldn't clutter the controller but are too complex for simple tags.
+### 5. Backend JavaScript (`<script:odac>`)
 ```html
 <script:odac>
-  // Runs on the SERVER during rendering
-  const total = items.reduce((sum, i) => sum + i.price, 0);
-  const tax = total * 0.18;
+  const total = items.reduce((sum, i) => sum + i.price, 0)
+  const tax = total * 0.18
 </script:odac>
 
 <p>Subtotal: ${{ total }}</p>
@@ -63,6 +135,6 @@ Perfect for calculations that shouldn't clutter the controller but are too compl
 ```
 
 ## Security Best Practices
--   **Always use `{{ }}`**: Standard tags prevent XSS.
+-   **Both `{{ }}` and `<odac var>` are XSS-safe**: Both apply HTML escaping by default.
+-   **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.