odac 1.4.13 → 1.4.15

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 ### 🛠️ Fixes & Improvements
 
+- **docs:** update references from 'odac' to 'Odac' for consistency
+- **form:** improve form submission handler ownership to prevent duplicate submissions
+- **form:** prevent multiple submit handlers on re-bound forms
+- **startup:** surface init/migration errors instead of swallowing them
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### 🛠️ Fixes & Improvements
+
+- **docs:** update frontend scripts documentation to include code obfuscation details and enhance clarity
+- **form:** add escapeHtmlPreservingTemplates method to handle template tokens
+- **route:** enhance error handling to support object responses in error method
+- **view:** use escapeHtmlPreservingTemplates consistently for form attributes
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### 🛠️ Fixes & Improvements
+
 - **form:** enhance form handling with metadata and improved parsing logic
 - **form:** implement token rotation on successful form submissions
 - **view:** prevent script injection and handle escaped quotes in form configs

package/bin/odac.js

@@ -532,6 +532,7 @@ async function runMigration(cmd, cliArgs) {
     }
   } catch (err) {
     console.error('❌ Migration error:', err.message)
+    if (err.cause) console.error('   Cause:', err.cause.message || err.cause)
     process.exit(1)
   } finally {
     for (const conn of Object.values(connections)) {

package/client/odac.js

@@ -119,6 +119,7 @@ if (typeof window !== 'undefined') {
     #page = null
     #token = {hash: [], data: false}
     #formSubmitHandlers = new Map()
+    #formElementSelectors = new WeakMap()
     #loader = {elements: {}, callback: null, parts: {}}
     #isNavigating = false
 
@@ -412,6 +413,20 @@ if (typeof window !== 'undefined') {
         const formElement = e.target.closest(formSelector)
         if (!formElement) return
 
+        // Ownership guard: a single form can be matched by more than one
+        // registered selector — e.g. an <odac:form> auto-bound by #initForms
+        // under its data-odac-form token, then re-bound by the app via
+        // Odac.form('#id', cb) to attach a callback. The form is tagged with the
+        // selector it was last registered under; only that handler may process
+        // the submit, so the form fires exactly once instead of 2x. We don't
+        // tear down the other selector's listener (it may still serve *other*
+        // forms — e.g. a shared '.ajax-form' selector), we just let those
+        // handlers ignore this form. Forms never explicitly (re-)bound aren't
+        // tracked and fall through normally, preserving delegation for forms
+        // added to the DOM after registration.
+        const owner = this.#formElementSelectors.get(formElement)
+        if (owner && owner !== formSelector) return
+
         e.preventDefault()
 
         if (obj.messages !== false) {
@@ -680,6 +695,7 @@ if (typeof window !== 'undefined') {
 
       document.addEventListener('submit', handler)
       this.#formSubmitHandlers.set(formSelector, handler)
+      document.querySelectorAll(formSelector).forEach(formEl => this.#formElementSelectors.set(formEl, formSelector))
     }
 
     get(url, callback) {
@@ -997,6 +1013,9 @@ if (typeof window !== 'undefined') {
 
       for (const {cls, attr} of formTypes) {
         document.querySelectorAll(`form.${cls}[${attr}]`).forEach(form => {
+          // Skip forms the app already bound via Odac.form(...) — re-registering
+          // here would attach a second handler and cause 2x submit.
+          if (this.#formElementSelectors.has(form)) return
           const token = form.getAttribute(attr)
           const selector = `form[${attr}="${token}"]`
           if (!this.#formSubmitHandlers.has(selector)) {

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

@@ -18,7 +18,7 @@ Frontend logic is organized into **Actions** using `Odac.action()`. This method
     -   `start`: Fires once when the script initializes.
     -   `load`: Fires after every page load (including AJAX navigations).
 3.  **Page Scoping**: Use the `page: { name: fn }` object to isolate code to specific routes.
-4.  **Persistent Storage**: Use `odac.storage(key, value)` for a secure LocalStorage wrapper.
+4.  **Persistent Storage**: Use `Odac.storage(key, value)` for a secure LocalStorage wrapper.
 
 ## Reference Patterns
 
@@ -60,11 +60,11 @@ Odac.action({
 ### 3. Data Utilities
 ```javascript
 // Accessing data shared from backend (Odac.share)
-const user = odac.data('user')
+const user = Odac.data('user')
 
 // Using Storage wrapper
-odac.storage('theme', 'dark')
-const theme = odac.storage('theme')
+Odac.storage('theme', 'dark')
+const theme = Odac.storage('theme')
 ```
 
 ### 4. Programmatic Navigation
@@ -84,4 +84,4 @@ Odac.load('/dashboard', function(page, vars) {
 ## Best Practices
 -   **Clean Selectors**: Use ID or specific data-attributes for event listeners to avoid conflicts.
 -   **No Inline JS**: Move all logic from HTML attributes (onclick, etc.) into `Odac.action()`.
--   **Shared State**: Use `odac.data()` to pass complex objects from the backend once per request.
+-   **Shared State**: Use `Odac.data()` to pass complex objects from the backend once per request.

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

@@ -1,36 +1,92 @@
 ---
 name: frontend-scripts-typescript-skill
-description: ODAC frontend JS/TS pipeline guidelines for writing, bundling, and optimizing client-side scripts using esbuild.
+description: ODAC frontend JS/TS pipeline guidelines for writing, bundling, and optimizing client-side scripts using esbuild and code obfuscation.
 metadata:
-  tags: frontend, javascript, typescript, esbuild, bundling, minification, tree-shaking, scripts, assets
+  tags: frontend, javascript, typescript, esbuild, bundling, minification, tree-shaking, scripts, assets, obfuscation
 ---
 
 # Frontend Scripts & TypeScript Skill
 
-Zero-config frontend asset pipeline powered by esbuild for TypeScript transpilation, bundling, minification, and tree-shaking.
+ODAC provides a built-in, Zero-Config frontend asset pipeline powered by **esbuild** for TypeScript transpilation, bundling, minification, tree-shaking, and multi-level code obfuscation.
 
-## Core Rules
-1.  **Entry Points**: Place `.ts`, `.js`, `.mts`, or `.mjs` files in `view/js/`. Each becomes a separate bundle.
-2.  **Partials Convention**: Files starting with `_` (e.g., `_utils.ts`) are ignored as entry points — use them as shared imports only.
-3.  **Output Path**: Compiled files go to `public/assets/js/{name}.js`.
-4.  **No TypeScript Enforcement**: Both TypeScript and plain JavaScript are supported equally.
-5.  **Import Resolution**: Use standard ES module `import`/`export` between files. esbuild bundles everything into a single output per entry point.
-6.  **Configuration**: Optional `js` key in `odac.json` for `target`, `minify`, `sourcemap`, and `bundle` settings.
+## Core Rules & Conventions
 
-## Development vs Production
-- **`odac dev`**: Watch mode with source maps, no minification, instant rebuilds.
-- **`odac build`**: Full minification, tree-shaking, and dead code elimination.
+1.  **Entry Points**: Every `.ts`, `.js`, `.mts`, or `.mjs` file placed directly in `view/js/` represents a unique entry point and will compile into a separate bundle in `public/assets/js/{name}.js`.
+2.  **Partials Convention**: Files starting with an underscore (e.g., `_utils.ts`, `_api.ts`) are treated as private modules/partials. They are **ignored** as entry points and should only be used as shared imports.
+3.  **No TypeScript Enforcement**: TypeScript and plain JavaScript are supported equally out of the box.
+4.  **Import Resolution**: Use standard ES module `import`/`export` syntax. esbuild bundles all imported modules into a single optimized bundle, eliminating extra runtime network requests.
+5.  **Output Path**: Compiled output is saved statically under `public/assets/js/`.
+
+## Pipeline Modes
+
+*   **Development (`npm run dev` / `odac dev`)**: 
+    *   Watches all scripts in `view/js/` for instant sub-millisecond rebuilds.
+    *   Source maps are always enabled to facilitate easy debugging.
+    *   No minification or obfuscation is applied.
+*   **Production (`npm run build` / `odac build`)**:
+    *   Enables full bundling, minification, and tree-shaking.
+    *   Applies configured obfuscation levels.
+    *   Exports clean production-ready assets to `public/assets/js/`.
+
+## Configuration (`odac.json`)
+
+You can customize the pipeline behavior via the optional `js` key in the `odac.json` configuration file:
+
+```json
+{
+  "js": {
+    "target": "es2020",
+    "minify": true,
+    "sourcemap": false,
+    "bundle": true,
+    "obfuscate": false
+  }
+}
+```
+
+### Configuration Options
+
+| Option      | Default    | Description |
+|-------------|------------|-------------|
+| `target`    | `"es2020"` | JavaScript target version (`es2015`, `es2020`, `esnext`, etc.). |
+| `minify`    | `true`     | Enables minification (whitespace removal, variable shortening, dead code elimination) in production. |
+| `sourcemap` | `false`    | Generates source maps in production builds (always enabled in dev mode). |
+| `bundle`    | `true`     | Bundles all imported dependency modules into the output entry-point file. |
+| `obfuscate` | `false`    | Configures the level of production code obfuscation (`false`, `true`/`"low"`, `"medium"`, `"high"`). |
+
+---
+
+## Obfuscation Levels
+
+ODAC supports three distinct levels of code obfuscation in production mode (`odac build`). Obfuscation is disabled by default and is never applied during development.
+
+| Level | Behavior |
+|-------|----------|
+| `false` | **No Obfuscation**: Standard minification and tree-shaking only. |
+| `true` / `"low"` | **Low Mangling**: Mangles properties starting with `_` (private-by-convention). |
+| `"medium"` | **Medium Security**: Low level mangling + drops `debugger` statements + removes `console.debug` and `console.trace` calls. |
+| `"high"` | **Maximum Hardening**: Mangles all `_` and `$` prefixed properties + drops all `console.*` calls and `debugger` statements. |
+
+> [!WARNING]
+> **High Obfuscation Compatibility Warning:** 
+> The `"high"` obfuscation level mangles `$`-prefixed properties. This can break frontend code interacting with external libraries or frameworks that rely heavily on the `$` naming convention (e.g., jQuery). Start with `"low"` or `"medium"` and verify compatibility thoroughly before deploying with `"high"`.
+
+---
+
+## Example Directory Structure
 
-## Example Structure
 ```
 view/js/
-├── app.ts          → public/assets/js/app.js
-├── admin.ts        → public/assets/js/admin.js
-├── _api.ts         (shared module, not compiled)
-└── _utils.ts       (shared module, not compiled)
+├── app.ts          → compiled to public/assets/js/app.js (Entry Point)
+├── admin.ts        → compiled to public/assets/js/admin.js (Entry Point)
+├── _api.ts         (Shared API Module — Import only, not compiled on its own)
+└── _utils.ts       (Shared Utility Module — Import only, not compiled on its own)
 ```
 
 ## HTML Integration
+
+Inject compiled scripts into your skeleton or layout templates using regular script tags:
+
 ```html
 <script src="/assets/js/app.js"></script>
 ```

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

@@ -15,7 +15,7 @@ Remember the `Odac` object? It's your best friend inside a controller. It's pass
 *   `Odac.return(data)`: Send back a response.
 *   `Odac.direct(url)`: Redirect the user to a new page.
 *   `Odac.set(key, value)`: Pass variables to your View template.
-*   `Odac.share(key, value)`: Share data directly with frontend JavaScript (`odac.data()`).
+*   `Odac.share(key, value)`: Share data directly with frontend JavaScript (`Odac.data()`).
 *   `Odac.cookie(key, value)`: Set a browser cookie.
 *   `Odac.validator()`: Check user input easily.
 *   `Odac.setInterval(callback, delay)`: Schedule repeating tasks (auto-cleanup).

package/docs/backend/05-forms/01-custom-forms.md

@@ -204,6 +204,50 @@ Automatically set field values without user input:
 <odac:submit text="Save" loading="Saving..." class="btn btn-primary" id="save-btn"/>
 ```
 
+## Client-Side Callbacks (Optional)
+
+`<odac:form>` works fully on its own — submission, CSRF, validation, loading
+states, success/error messages and redirects are all wired up automatically,
+**no JavaScript required.**
+
+If you also need to run your own code after a submit (analytics, closing a
+modal, updating the UI, etc.), give the form an `id` and attach a callback with
+`Odac.form()`:
+
+```html
+<odac:form action="Account.unlink" id="server-unlink">
+  <!-- fields -->
+  <odac:submit text="Unlink"/>
+</odac:form>
+```
+
+```javascript
+Odac.form('#server-unlink', function(data) {
+  if (data.result.success) {
+    closeModal()
+  }
+})
+```
+
+This is **safe to combine** with the automatic registration — calling
+`Odac.form()` on an `<odac:form>` re-binds the same form rather than adding a
+second handler, so the form still submits only once. (Internally the dedup is
+keyed by the form element, not the selector string.)
+
+> **Note:** Call `Odac.form()` after the form exists in the DOM (e.g. on
+> `DOMContentLoaded` or after AJAX navigation). Binding before the element is
+> rendered can leave the automatic registration in place as a second handler.
+
+You can trigger submission programmatically with the native API:
+
+```javascript
+document.getElementById('server-unlink').requestSubmit()
+```
+
+For the full callback/options API (`messages`, `loading`, redirect strings,
+file-upload progress) see
+[Form Handling with odac.js](../../frontend/03-forms/01-form-handling.md).
+
 ## Controller Handler (Server Actions)
  
 Handle form submission directly in your controller. The action is defined as `ControllerName.methodName`.

package/docs/frontend/01-overview/01-introduction.md

@@ -88,13 +88,13 @@ Odac.action({
 
 ```javascript
 // Basic usage
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
     // This callback is executed on success
     console.log('Form submitted successfully!', data);
 });
 
 // With options
-odac.form({
+Odac.form({
     form: '#my-form',
     messages: ['success', 'error'], // Show both success and error messages
     loading: function(percent) {
@@ -119,7 +119,7 @@ To display validation errors, you can add elements with the `odac-form-error` at
 For simple GET requests, you can use the `Odac.get()` method.
 
 ```javascript
-odac.get('/api/users', function(data) {
+Odac.get('/api/users', function(data) {
     console.log('Users:', data);
 });
 ```
@@ -133,18 +133,18 @@ odac.get('/api/users', function(data) {
 -   **`Odac.client()`**: Returns a unique client identifier from a cookie.
 -   **`Odac.data(key)`**: Returns shared data passed from the backend via `Odac.share`. You can get the full data object or a specific key:
     ```javascript
-    let allData = odac.data();
-    let user = odac.data('user'); // Returns null if not exists
+    let allData = Odac.data();
+    let user = Odac.data('user'); // Returns null if not exists
     ```
 -   **`Odac.page()`**: Returns the identifier of the current page. This is the controller name (e.g., `'user'`) or view name (e.g., `'dashboard'`) set by the backend. Use this to conditionally run code for specific pages.
 -   **`Odac.storage()`**: A wrapper for `localStorage`.
     ```javascript
     // Set a value
-    odac.storage('my-key', 'my-value');
+    Odac.storage('my-key', 'my-value');
 
     // Get a value
-    let value = odac.storage('my-key');
+    let value = Odac.storage('my-key');
 
     // Remove a value
-    odac.storage('my-key', null);
+    Odac.storage('my-key', null);
     ```

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

@@ -126,17 +126,17 @@ Controllers automatically support AJAX loading. Use `Odac.View.skeleton()` to sp
 ```javascript
 module.exports = function (Odac) {
   // Define the skeleton template
-  odac.View.skeleton('main')
+  Odac.View.skeleton('main')
   
   // Set view parts - lowercase keys map to UPPERCASE placeholders
-  odac.View.set({
+  Odac.View.set({
     header: 'main',      // Loads view/header/main.html into {{ HEADER }}
     content: 'about',    // Loads view/content/about.html into {{ CONTENT }}
     footer: 'main'       // Loads view/footer/main.html into {{ FOOTER }}
   })
   
   // Optional: Send variables to frontend (AJAX only)
-  odac.set({
+  Odac.set({
     pageTitle: 'About',
     data: {foo: 'bar'}
   }, true) // true = include in AJAX responses
@@ -318,13 +318,13 @@ Both methods work automatically - no additional configuration needed!
   }
   ```
 
-### odac.loader(selector, elements, callback)
+### Odac.loader(selector, elements, callback)
 
 Low-level method for direct initialization (not recommended for new code).
 
 **Parameters:** Same as navigate configuration, but as separate arguments.
 
-### odac.load(url, callback, push)
+### Odac.load(url, callback, push)
 
 Programmatically load a page via AJAX.
 
@@ -335,7 +335,7 @@ Programmatically load a page via AJAX.
 
 **Example:**
 ```javascript
-odac.load('/about', function(page, variables) {
+Odac.load('/about', function(page, variables) {
   console.log('Loaded:', page)
 })
 ```
@@ -377,7 +377,7 @@ Send data from server to client in AJAX responses:
 
 ```javascript
 // In controller
-odac.set({
+Odac.set({
   user: {name: 'John', role: 'admin'},
   stats: {views: 1234}
 }, true) // true = include in AJAX
@@ -423,12 +423,12 @@ Odac.action({
   navigate: {
     update: 'main',
     on: function(page, variables) {
-      odac.fn.updateActiveNav(window.location.pathname)
+      Odac.fn.updateActiveNav(window.location.pathname)
       console.log('Navigated to:', page)
     }
   },
   
-  // Custom functions (accessible as odac.fn.functionName)
+  // Custom functions (accessible as Odac.fn.functionName)
   function: {
     updateActiveNav: function(url) {
       document.querySelectorAll('nav a').forEach(link => {
@@ -440,14 +440,14 @@ Odac.action({
   // App initialization
   load: function() {
     console.log('App initialized')
-    odac.fn.updateActiveNav(window.location.pathname)
+    Odac.fn.updateActiveNav(window.location.pathname)
   },
   
   // Page-specific code
   page: {
     index: function(variables) {
       // Home page specific code
-      odac.form('#contact-form', function(data) {
+      Odac.form('#contact-form', function(data) {
         if (data.result.success) {
           alert('Message sent!')
         }
@@ -463,7 +463,7 @@ Odac.action({
   // Event handlers
   click: {
     '#refresh-btn': function() {
-      odac.load(window.location.pathname)
+      Odac.load(window.location.pathname)
     }
   }
 })
@@ -595,8 +595,8 @@ This is usually caused by mismatched keys between your skeleton, controller, and
 
 2. **Controller** (`controller/page/about.js`):
    ```javascript
-   odac.View.skeleton('main')
-   odac.View.set({
+   Odac.View.skeleton('main')
+   Odac.View.set({
      header: 'main',    // Lowercase → {{ HEADER }}
      content: 'about'   // Lowercase → {{ CONTENT }}
    })

package/docs/frontend/02-ajax-navigation/02-configuration.md

@@ -129,7 +129,7 @@ The keys (content, header, etc.) must match the view parts defined in your contr
 
 ```javascript
 // In controller
-odac.View.set({
+Odac.View.set({
   header: 'main',
   content: 'about',
   sidebar: 'main'
@@ -219,14 +219,14 @@ In your controller, send data to the client:
 ```javascript
 module.exports = function(Odac) {
   // Set variables for AJAX responses
-  odac.set({
+  Odac.set({
     title: 'About Page',
     user: {name: 'John', role: 'admin'},
     stats: {views: 1234}
   }, true)  // true = include in AJAX
   
-  odac.View.skeleton('main')
-  odac.View.set({
+  Odac.View.skeleton('main')
+  Odac.View.set({
     header: 'main',
     content: 'about',
     footer: 'main'

package/docs/frontend/02-ajax-navigation/03-advanced-usage.md

@@ -6,31 +6,31 @@ Advanced techniques and patterns for AJAX navigation in Odac.
 
 ## Programmatic Navigation
 
-### Using odac.load()
+### Using Odac.load()
 
 Navigate programmatically from your code:
 
 ```javascript
 // Basic usage
-odac.load('/about')
+Odac.load('/about')
 
 // With callback
-odac.load('/about', function(page, variables) {
+Odac.load('/about', function(page, variables) {
   console.log('Loaded:', page)
   console.log('Data:', variables)
 })
 
 // Without updating history
-odac.load('/about', callback, false)
+Odac.load('/about', callback, false)
 ```
 
 ### Use Cases
 
 **Redirect after form submission:**
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (data.result.success) {
-    odac.load('/success')
+    Odac.load('/success')
   }
 })
 ```
@@ -38,16 +38,16 @@ odac.form('#my-form', function(data) {
 **Conditional navigation:**
 ```javascript
 if (user.isLoggedIn) {
-  odac.load('/dashboard')
+  Odac.load('/dashboard')
 } else {
-  odac.load('/login')
+  Odac.load('/login')
 }
 ```
 
 **Timed navigation:**
 ```javascript
 setTimeout(() => {
-  odac.load('/next-page')
+  Odac.load('/next-page')
 }, 3000)
 ```
 
@@ -76,8 +76,8 @@ Define all parts in your controller:
 
 ```javascript
 module.exports = function(Odac) {
-  odac.View.skeleton('main')
-  odac.View.set({
+  Odac.View.skeleton('main')
+  Odac.View.set({
     header: 'main',
     content: 'dashboard',
     sidebar: 'dashboard',
@@ -333,10 +333,10 @@ Odac.action({
 Gracefully handle navigation errors:
 
 ```javascript
-// Override odac.load to add error handling
-const originalLoad = odac.load.bind(Odac)
+// Override Odac.load to add error handling
+const originalLoad = Odac.load.bind(Odac)
 
-odac.load = function(url, callback, push) {
+Odac.load = function(url, callback, push) {
   try {
     originalLoad(url, function(page, variables) {
       if (callback) callback(page, variables)
@@ -359,7 +359,7 @@ function loadWithRetry(url, maxRetries = 3) {
   
   function attempt() {
     attempts++
-    odac.load(url, 
+    Odac.load(url, 
       (page, vars) => {
         console.log('Success after', attempts, 'attempts')
       },
@@ -491,7 +491,7 @@ describe('Navigation', () => {
     })
     
     // Simulate navigation
-    odac.load('/about')
+    Odac.load('/about')
     
     // Assert
     expect(document.querySelector('.nav-link.active').href)

package/docs/frontend/03-forms/01-form-handling.md

@@ -14,7 +14,7 @@ Learn how to handle forms with automatic AJAX submission, CSRF protection, and v
 ```
 
 ```javascript
-odac.form('#contact-form', function(data) {
+Odac.form('#contact-form', function(data) {
   if (data.result.success) {
     alert('Form submitted successfully!')
   }
@@ -35,7 +35,7 @@ That's it! odac.js handles:
 ### Basic Usage
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   console.log('Response:', data)
 })
 ```
@@ -43,7 +43,7 @@ odac.form('#my-form', function(data) {
 ### With Options
 
 ```javascript
-odac.form({
+Odac.form({
   form: '#my-form',
   messages: true,  // Show error/success messages
   loading: function(percent) {
@@ -59,10 +59,37 @@ odac.form({
 ### Redirect After Submit
 
 ```javascript
-odac.form('#my-form', '/success-page')
+Odac.form('#my-form', '/success-page')
 // Redirects to /success-page on success
 ```
 
+## Using with `<odac:form>` Components
+
+`Odac.form()` works with both plain `<form>` elements and server-rendered
+[`<odac:form>` components](../../backend/05-forms/01-custom-forms.md).
+
+An `<odac:form>` already registers itself automatically, so you only call
+`Odac.form()` when you want to add your own callback. Give the component an `id`
+and bind to it:
+
+```html
+<odac:form action="Contact.submit" id="contact-form">
+  <!-- fields -->
+  <odac:submit text="Send"/>
+</odac:form>
+```
+
+```javascript
+Odac.form('#contact-form', function(data) {
+  if (data.result.success) {
+    closeModal()
+  }
+})
+```
+
+Calling `Odac.form()` on an already-registered `<odac:form>` **re-binds** the
+same form instead of adding a second handler, so it still submits only once.
+
 ## Error Handling
 
 ### Automatic Error Display
@@ -85,7 +112,7 @@ If you want to control where errors appear, add error elements manually:
 ### Custom Error Display
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (!data.result.success) {
     // Custom error handling
     Object.entries(data.errors).forEach(([field, message]) => {
@@ -137,7 +164,7 @@ If you want to control where success messages appear, add a success element manu
 ### Custom Success Message
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (data.result.success) {
     document.querySelector('#custom-message').innerHTML = 
       'Thank you! Your form has been submitted.'
@@ -157,7 +184,7 @@ odac.form('#my-form', function(data) {
 ```
 
 ```javascript
-odac.form('#upload-form', function(data) {
+Odac.form('#upload-form', function(data) {
   if (data.result.success) {
     console.log('File uploaded:', data.result.filename)
   }
@@ -167,7 +194,7 @@ odac.form('#upload-form', function(data) {
 ### Upload Progress
 
 ```javascript
-odac.form({
+Odac.form({
   form: '#upload-form',
   loading: function(percent) {
     document.querySelector('#progress').style.width = percent + '%'
@@ -189,7 +216,7 @@ odac.form({
 ### Disable Messages
 
 ```javascript
-odac.form({
+Odac.form({
   form: '#my-form',
   messages: false  // Don't show automatic messages
 }, function(data) {
@@ -201,7 +228,7 @@ odac.form({
 
 ```javascript
 // Only show error messages, suppress success messages
-odac.form({
+Odac.form({
   form: '#my-form',
   messages: ['error']
 }, function(data) {
@@ -211,7 +238,7 @@ odac.form({
 })
 
 // Only show success messages, suppress error messages
-odac.form({
+Odac.form({
   form: '#my-form',
   messages: ['success']
 }, function(data) {
@@ -224,7 +251,7 @@ odac.form({
 ### Form Reset
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (data.result.success) {
     // Reset the form
     document.querySelector('#my-form').reset()
@@ -242,7 +269,7 @@ document.querySelector('#my-form').addEventListener('submit', function(e) {
   }
 })
 
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   console.log('Submitted!')
 })
 ```
@@ -254,8 +281,8 @@ odac.form('#my-form', function(data) {
 ```javascript
 // controller/post/contact.js
 module.exports = async function(Odac) {
-  const email = await odac.Request.request('email')
-  const message = await odac.Request.request('message')
+  const email = await Odac.Request.request('email')
+  const message = await Odac.Request.request('message')
   
   // Validation
   const errors = {}
@@ -285,7 +312,7 @@ module.exports = async function(Odac) {
 
 ```javascript
 // route/www.js
-odac.Route.post('/api/contact', 'contact')
+Odac.Route.post('/api/contact', 'contact')
 ```
 
 ## Validation
@@ -306,7 +333,7 @@ Always validate on the server:
 
 ```javascript
 module.exports = async function(Odac) {
-  const email = await odac.Request.request('email')
+  const email = await Odac.Request.request('email')
   
   const errors = {}
   
@@ -349,7 +376,7 @@ module.exports = async function(Odac) {
 **Note:** Error and success elements are auto-generated. Add them manually only if you need custom positioning or styling.
 
 ```javascript
-odac.form('#contact-form', function(data) {
+Odac.form('#contact-form', function(data) {
   if (data.result.success) {
     document.querySelector('#contact-form').reset()
   }
@@ -367,7 +394,7 @@ odac.form('#contact-form', function(data) {
 ```
 
 ```javascript
-odac.form('#login-form', function(data) {
+Odac.form('#login-form', function(data) {
   if (data.result.success) {
     // Redirect to dashboard
     window.location.href = '/dashboard'
@@ -420,6 +447,15 @@ odac.form('#login-form', function(data) {
 - Verify `messages` option is not set to `false`
 - If using custom error elements, ensure `odac-form-error` attributes match field names exactly
 
+### Form Submits Twice
+
+- Make sure you don't register the **same form under two different selectors**
+  (e.g. `Odac.form('#my-form')` and `Odac.form('form#my-form')`) — use one
+  consistent selector.
+- Binding `Odac.form()` to an `<odac:form>` is safe and will **not** double up;
+  it re-binds the existing handler. If you still see two submits, check that you
+  bind **after** the form is in the DOM, not before it renders.
+
 ### CSRF Token Errors
 
 - CSRF tokens are handled automatically

package/docs/frontend/04-api-requests/01-get-post.md

@@ -7,7 +7,7 @@ Learn how to make GET and POST requests to your API endpoints using odac.js.
 ### Basic GET Request
 
 ```javascript
-odac.get('/api/data', function(response) {
+Odac.get('/api/data', function(response) {
   console.log('Data:', response)
 })
 ```
@@ -16,7 +16,7 @@ odac.get('/api/data', function(response) {
 
 ```javascript
 const userId = 123
-odac.get(`/api/users/${userId}`, function(user) {
+Odac.get(`/api/users/${userId}`, function(user) {
   console.log('User:', user.name)
   console.log('Email:', user.email)
 })
@@ -25,7 +25,7 @@ odac.get(`/api/users/${userId}`, function(user) {
 ### Error Handling
 
 ```javascript
-odac.get('/api/data', function(response) {
+Odac.get('/api/data', function(response) {
   if (response.error) {
     console.error('Error:', response.error)
     return
@@ -43,7 +43,7 @@ odac.get('/api/data', function(response) {
 The recommended way to make POST requests is using `Odac.form()`:
 
 ```javascript
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   if (data.result.success) {
     console.log('Success!')
   }
@@ -58,12 +58,12 @@ For custom POST requests without forms, use the internal AJAX method:
 
 ```javascript
 // Note: This is an advanced pattern
-// For most cases, use odac.form() instead
+// For most cases, use Odac.form() instead
 
 const formData = new FormData()
 formData.append('name', 'John')
 formData.append('email', 'john@example.com')
-formData.append('_token', odac.token())
+formData.append('_token', Odac.token())
 
 fetch('/api/submit', {
   method: 'POST',
@@ -83,12 +83,12 @@ odac.js automatically handles CSRF tokens:
 
 ```javascript
 // Token is automatically included
-odac.get('/api/data', function(response) {
+Odac.get('/api/data', function(response) {
   // ...
 })
 
 // Token is automatically included in forms
-odac.form('#my-form', function(data) {
+Odac.form('#my-form', function(data) {
   // ...
 })
 ```
@@ -98,7 +98,7 @@ odac.form('#my-form', function(data) {
 If you need the token manually:
 
 ```javascript
-const token = odac.token()
+const token = Odac.token()
 console.log('Current token:', token)
 ```
 
@@ -108,7 +108,7 @@ console.log('Current token:', token)
 
 ```javascript
 // Get user profile
-odac.get('/api/profile', function(profile) {
+Odac.get('/api/profile', function(profile) {
   document.querySelector('#username').textContent = profile.name
   document.querySelector('#email').textContent = profile.email
 })
@@ -118,7 +118,7 @@ odac.get('/api/profile', function(profile) {
 
 ```javascript
 // Get products
-odac.get('/api/products', function(products) {
+Odac.get('/api/products', function(products) {
   const container = document.querySelector('#products')
   
   products.forEach(product => {
@@ -143,7 +143,7 @@ searchInput.addEventListener('input', function() {
   
   if (query.length < 3) return
   
-  odac.get(`/api/search?q=${encodeURIComponent(query)}`, function(results) {
+  Odac.get(`/api/search?q=${encodeURIComponent(query)}`, function(results) {
     displayResults(results)
   })
 })
@@ -172,7 +172,7 @@ document.querySelector('#autocomplete').addEventListener('input', function() {
   debounceTimer = setTimeout(() => {
     if (value.length < 2) return
     
-    odac.get(`/api/autocomplete?q=${value}`, function(suggestions) {
+    Odac.get(`/api/autocomplete?q=${value}`, function(suggestions) {
       showSuggestions(suggestions)
     })
   }, 300)
@@ -200,7 +200,7 @@ function loadMore() {
   loading = true
   page++
   
-  odac.get(`/api/posts?page=${page}`, function(posts) {
+  Odac.get(`/api/posts?page=${page}`, function(posts) {
     posts.forEach(post => {
       appendPost(post)
     })
@@ -214,7 +214,7 @@ function loadMore() {
 ```javascript
 // Poll for updates every 30 seconds
 setInterval(function() {
-  odac.get('/api/notifications', function(notifications) {
+  Odac.get('/api/notifications', function(notifications) {
     updateNotificationBadge(notifications.count)
   })
 }, 30000)
@@ -239,7 +239,7 @@ module.exports = function(Odac) {
 
 ```javascript
 // route/www.js
-odac.Route.get('/api/users', 'users')
+Odac.Route.get('/api/users', 'users')
 ```
 
 ### GET with Parameters
@@ -247,13 +247,13 @@ odac.Route.get('/api/users', 'users')
 ```javascript
 // controller/get/user.js
 module.exports = async function(Odac) {
-  const userId = odac.Request.data.url.id
+  const userId = Odac.Request.data.url.id
   
   // Fetch user from database
   const user = await getUserById(userId)
   
   if (!user) {
-    odac.Request.status(404)
+    Odac.Request.status(404)
     return {error: 'User not found'}
   }
   
@@ -263,7 +263,7 @@ module.exports = async function(Odac) {
 
 ```javascript
 // route/www.js
-odac.Route.get('/api/users/{id}', 'user')
+Odac.Route.get('/api/users/{id}', 'user')
 ```
 
 ### POST Endpoint
@@ -271,8 +271,8 @@ odac.Route.get('/api/users/{id}', 'user')
 ```javascript
 // controller/post/create.js
 module.exports = async function(Odac) {
-  const name = await odac.Request.request('name')
-  const email = await odac.Request.request('email')
+  const name = await Odac.Request.request('name')
+  const email = await Odac.Request.request('email')
   
   // Validation
   if (!name || !email) {
@@ -300,7 +300,7 @@ module.exports = async function(Odac) {
 
 ```javascript
 // route/www.js
-odac.Route.post('/api/users/create', 'create')
+Odac.Route.post('/api/users/create', 'create')
 ```
 
 ## Response Format
@@ -357,7 +357,7 @@ function getCached(url, callback) {
     return
   }
   
-  odac.get(url, function(data) {
+  Odac.get(url, function(data) {
     cache[url] = data
     callback(data)
   })
@@ -386,7 +386,7 @@ function processQueue() {
   processing = true
   const {url, callback} = requestQueue.shift()
   
-  odac.get(url, function(data) {
+  Odac.get(url, function(data) {
     callback(data)
     processing = false
     processQueue()
@@ -403,7 +403,7 @@ function getWithRetry(url, callback, maxRetries = 3) {
   function attempt() {
     attempts++
     
-    odac.get(url, function(data) {
+    Odac.get(url, function(data) {
       if (data.error && attempts < maxRetries) {
         setTimeout(attempt, 1000 * attempts)
       } else {

package/docs/frontend/05-streaming/01-client-streaming.md

@@ -6,7 +6,7 @@ Odac provides a simple client-side API for consuming Server-Sent Events (SSE) st
 
 ```javascript
 // Simple callback
-odac.listen('/events', (data) => {
+Odac.listen('/events', (data) => {
   console.log('Received:', data)
 })
 ```
@@ -14,7 +14,7 @@ odac.listen('/events', (data) => {
 ### With Options
 
 ```javascript
-const stream = odac.listen('/events', 
+const stream = Odac.listen('/events', 
   (data) => {
     console.log('Message:', data)
   },
@@ -34,7 +34,7 @@ stream.close()
 
 ```javascript
 // Server sends: data: {"message": "Hello"}\n\n
-odac.listen('/events', (data) => {
+Odac.listen('/events', (data) => {
   console.log(data.message) // "Hello"
 })
 ```
@@ -47,8 +47,8 @@ odac.listen('/events', (data) => {
 
 ```javascript
 // Server
-odac.Route.get('/dashboard/stats', async (Odac) => {
-  odac.stream((send) => {
+Odac.Route.get('/dashboard/stats', async (Odac) => {
+  Odac.stream((send) => {
     const interval = setInterval(async () => {
       const stats = await getServerStats()
       send(stats)
@@ -62,7 +62,7 @@ odac.Route.get('/dashboard/stats', async (Odac) => {
 })
 
 // Client
-odac.listen('/dashboard/stats', (stats) => {
+Odac.listen('/dashboard/stats', (stats) => {
   document.getElementById('cpu').textContent = stats.cpu + '%'
   document.getElementById('memory').textContent = stats.memory + 'MB'
 })
@@ -72,16 +72,16 @@ odac.listen('/dashboard/stats', (stats) => {
 
 ```javascript
 // Server
-odac.Route.get('/notifications', async (Odac) => {
-  const userId = await odac.request('userId')
+Odac.Route.get('/notifications', async (Odac) => {
+  const userId = await Odac.request('userId')
   
-  odac.stream((send) => {
+  Odac.stream((send) => {
     global.notificationStreams[userId] = { send }
   })
 })
 
 // Client
-odac.listen('/notifications', (notification) => {
+Odac.listen('/notifications', (notification) => {
   showToast(notification.message)
 })
 ```
@@ -90,8 +90,8 @@ odac.listen('/notifications', (notification) => {
 
 ```javascript
 // Server
-odac.Route.get('/build/logs', async (Odac) => {
-  odac.stream(async function* () {
+Odac.Route.get('/build/logs', async (Odac) => {
+  Odac.stream(async function* () {
     for await (const log of getBuildLogs()) {
       yield { timestamp: Date.now(), message: log }
     }
@@ -100,7 +100,7 @@ odac.Route.get('/build/logs', async (Odac) => {
 
 // Client
 const logs = []
-odac.listen('/build/logs', (log) => {
+Odac.listen('/build/logs', (log) => {
   logs.push(log)
   updateLogsUI(logs)
 })
@@ -108,7 +108,7 @@ odac.listen('/build/logs', (log) => {
 
 ## API Reference
 
-### odac.listen(url, onMessage, options)
+### Odac.listen(url, onMessage, options)
 
 **Parameters:**
 - `url` (string): Stream endpoint URL

package/docs/frontend/06-websocket/00-overview.md

@@ -6,7 +6,7 @@ Odac provides built-in WebSocket support with automatic reconnection and cross-t
 
 **Backend (route/main.js):**
 ```javascript
-odac.Route.ws('/chat', (ws, Odac) => {
+Odac.Route.ws('/chat', (ws, Odac) => {
   ws.on('message', data => {
     ws.broadcast(data)
   })

package/index.js

@@ -1,4 +1,14 @@
 'use strict'
 
 global.__dir = process.cwd()
-require('./src/Odac.js').init()
+
+// Surface startup failures loudly. init() is async; without a .catch() any
+// rejection (migration, DB connection, config parse) becomes an UnhandledPromiseRejection
+// that the structured logger never sees — making a broken boot look like a clean start.
+require('./src/Odac.js')
+  .init()
+  .catch(err => {
+    console.error('\x1b[31m[ODAC Fatal]\x1b[0m Startup failed:', err.message)
+    if (err.cause) console.error('\x1b[31m[ODAC Fatal]\x1b[0m Cause:', err.cause.message || err.cause)
+    process.exit(1)
+  })

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.4.13",
+  "version": "1.4.15",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/Request.js

@@ -50,12 +50,18 @@ class OdacRequest {
   async abort(code) {
     this.status(code)
     let result = {401: 'Unauthorized', 404: 'Not Found', 408: 'Request Timeout'}[code] ?? null
-    if (
-      this.#odac.Route?.routes?.[this.route]?.error &&
-      this.#odac.Route.routes[this.route].error[code] &&
-      typeof this.#odac.Route.routes[this.route].error[code].cache === 'function'
-    )
-      result = await this.#odac.Route.routes[this.route].error[code].cache(this.#odac)
+    const errorRoute = this.#odac.Route?.routes?.[this.route]?.error?.[code]
+    if (errorRoute && typeof errorRoute.cache === 'function') {
+      try {
+        const handlerResult = await errorRoute.cache(this.#odac)
+        // If the handler returned nothing, assume it configured the view via Odac.View.set()
+        // and let Route.request() continue to View.print() like normal pages.
+        if (handlerResult === undefined) return
+        result = handlerResult
+      } catch (e) {
+        console.error(JSON.stringify({level: 'ERROR', message: `Error in custom error handler for ${code}`, error: e.message}))
+      }
+    }
     this.end(result)
   }
 

package/src/Route.js

@@ -858,6 +858,13 @@ class Route {
   }
 
   error(code, file) {
+    if (typeof file === 'object' && file !== null && !Array.isArray(file)) {
+      this.set('error', code, _odac => {
+        _odac.set(file)
+        _odac.View.set(file)
+      })
+      return
+    }
     this.set('error', code, file)
   }
 

package/src/View/Form.js

@@ -58,6 +58,30 @@ class Form {
     return String(value).replace(/[&<>"']/g, ch => map[ch])
   }
 
+  // Like escapeHtml but leaves {{ ... }} / {!! ... !!} template tokens intact
+  // so they survive into the view engine's {{ }} pass. Escaping inside the
+  // tokens would corrupt the JS expression (e.g. ' -> &#39;) and produce
+  // "Unexpected token '&'" at render time.
+  static escapeHtmlPreservingTemplates(value) {
+    if (value === null || value === undefined) return ''
+    const str = String(value)
+    const regex = /\{\{[\s\S]*?\}\}|\{!![\s\S]*?!!\}/g
+    let result = ''
+    let lastIndex = 0
+    let match
+    while ((match = regex.exec(str)) !== null) {
+      if (match.index > lastIndex) {
+        result += this.escapeHtml(str.substring(lastIndex, match.index))
+      }
+      result += match[0]
+      lastIndex = regex.lastIndex
+    }
+    if (lastIndex < str.length) {
+      result += this.escapeHtml(str.substring(lastIndex))
+    }
+    return result
+  }
+
   static parse(content, Odac) {
     for (const type of this.FORM_TYPES) {
       content = this.parseFormType(content, Odac, type)
@@ -484,16 +508,18 @@ class Form {
     let html = ''
     const escapedName = this.escapeHtml(field.name)
     const escapedType = this.escapeHtml(field.type)
-    const escapedPlaceholder = this.escapeHtml(field.placeholder)
+    const escapedPlaceholder = this.escapeHtmlPreservingTemplates(field.placeholder)
 
     if (field.label && field.type !== 'checkbox') {
-      const fieldId = this.escapeHtml(field.id || `odac-${field.name}`)
-      html += `<label for="${fieldId}">${this.escapeHtml(field.label)}</label>\n`
+      const fieldId = this.escapeHtmlPreservingTemplates(field.id || `odac-${field.name}`)
+      html += `<label for="${fieldId}">${this.escapeHtmlPreservingTemplates(field.label)}</label>\n`
     }
 
-    const classAttr = field.class ? ` class="${this.escapeHtml(field.class)}"` : ''
-    const idAttr = field.id ? ` id="${this.escapeHtml(field.id)}"` : ` id="${this.escapeHtml(`odac-${field.name}`)}"`
-    const valueAttr = field.value !== null ? ` value="${this.escapeHtml(field.value)}"` : ''
+    const classAttr = field.class ? ` class="${this.escapeHtmlPreservingTemplates(field.class)}"` : ''
+    const idAttr = field.id
+      ? ` id="${this.escapeHtmlPreservingTemplates(field.id)}"`
+      : ` id="${this.escapeHtmlPreservingTemplates(`odac-${field.name}`)}"`
+    const valueAttr = field.value !== null ? ` value="${this.escapeHtmlPreservingTemplates(field.value)}"` : ''
 
     if (field.type === 'checkbox') {
       const attrs = this.buildHtml5Attributes(field)
@@ -501,14 +527,14 @@ class Form {
       if (field.label) {
         html += `<label>\n`
         html += `  <input type="checkbox"${idAttr} name="${escapedName}" value="1"${classAttr}${checkedAttr}${attrs}>\n`
-        html += `  ${this.escapeHtml(field.label)}\n`
+        html += `  ${this.escapeHtmlPreservingTemplates(field.label)}\n`
         html += `</label>\n`
       } else {
         html += `<input type="checkbox"${idAttr} name="${escapedName}" value="1"${classAttr}${checkedAttr}${attrs}>\n`
       }
     } else if (field.type === 'textarea') {
       const attrs = this.buildHtml5Attributes(field)
-      html += `<textarea${idAttr} name="${escapedName}" placeholder="${escapedPlaceholder}"${classAttr}${attrs}>${this.escapeHtml(
+      html += `<textarea${idAttr} name="${escapedName}" placeholder="${escapedPlaceholder}"${classAttr}${attrs}>${this.escapeHtmlPreservingTemplates(
         field.value || ''
       )}</textarea>\n`
     } else {
@@ -524,7 +550,7 @@ class Form {
     for (const key in field.extraAttributes) {
       const val = field.extraAttributes[key]
       if (val === '') attrs += ` ${key}`
-      else attrs += ` ${key}="${this.escapeHtml(val)}"`
+      else attrs += ` ${key}="${this.escapeHtmlPreservingTemplates(val)}"`
     }
     return attrs
   }