odac 1.4.1 → 1.4.2

package/.agent/rules/memory.md

@@ -43,6 +43,11 @@ trigger: always_on
 - **Mandatory Test Coverage:** Every new feature, method, or significant logic change MUST be accompanied by a corresponding unit or integration test.
     - **Verify Correctness:** do not assume code works; prove it with a test that covers both success and failure scenarios (e.g., edge cases, error conditions).
     - **Update Existing Tests:** If a feature modifies existing behavior, update the relevant tests to reflect the new logic and ensure they pass.
+- **Atomic Test Structure:**
+    - **Directory Mapping:** Each source class/module must have its own directory under `test/` (e.g., `src/Auth.js` -> `test/Auth/`).
+    - **Method-Level Files:** Every public method should have its own test file within the class directory (e.g., `test/Auth/check.test.js`).
+    - **Sub-module Context:** Nested modules should follow the same pattern (e.g., `src/View/Form.js` -> `test/View/Form/generateFieldHtml.test.js`).
+    - **Isolation & Parallelism:** This structure is mandatory to leverage Jest's multi-threaded execution and ensure strict isolation between test cases.
 
 ## Client Library (odac.js)
 - **Automatic JSON Parsing:** The `#ajax` method (and by extension `odac.get`) must automatically parse the response if the `Content-Type` header contains `application/json`, even if `dataType` is not explicitly set to `json`.

package/.releaserc.js

@@ -4,7 +4,12 @@ module.exports = {
     [
       '@semantic-release/commit-analyzer',
       {
-        preset: 'conventionalcommits'
+        preset: 'conventionalcommits',
+        releaseRules: [
+          {type: 'major', release: 'major'},
+          {type: 'minor', release: 'minor'},
+          {type: '*', release: 'patch'}
+        ]
       }
     ],
     [
@@ -16,6 +21,8 @@ module.exports = {
             const commit = JSON.parse(JSON.stringify(c))
 
             const map = {
+              major: '🚀 Major Updates',
+              minor: '🌟 Minor Updates',
               feat: "✨ What's New",
               fix: '🛠️ Fixes & Improvements',
               perf: '⚡️ Performance Upgrades',
@@ -134,4 +141,4 @@ Powered by [⚡ ODAC](https://odac.run)
     ],
     '@semantic-release/github'
   ]
-}
+}

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 ### doc
 
+- **forms:** update backend and frontend forms documentation with practical usage patterns and improved descriptions
+- **validation:** enhance backend validation documentation with detailed usage patterns and examples
+
+### ⚙️ Engine Tuning
+
+- **test:** restructure test suite into class-scoped directories and method-level atomic files
+
+### ✨ What's New
+
+- **database:** add debug logging for schema parsing failures in nanoid metadata loader
+- **database:** introduce NanoID support for automatic ID generation in schema
+- **release:** enhance commit analyzer with release rules and custom labels
+- **shutdown:** implement graceful shutdown for IPC, Database, and Cron services
+
+### 📚 Documentation
+
+- **database:** remove underscore from nanoid example to reflect true alphanumeric output
+
+### 🛠️ Fixes & Improvements
+
+- **Auth:** handle token rotation for WebSocket connections and update active timestamp
+- **core:** explicitly stop session GC interval during graceful shutdown
+- **database:** namespace nanoid schema cache by connection to prevent table to prevent collisions
+- **forms:** initialize ODAC form handlers on DOMContentLoaded and after AJAX navigation
+- **manageSkills:** correct targetPath assignment for skill synchronization
+- **Validator:** pass Odac instance to Validator for improved access to global methods
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### doc
+
 - enhance AI skills documentation with structured YAML front matter and detailed descriptions
 
 ### ⚙️ Engine Tuning

package/bin/odac.js

@@ -210,7 +210,7 @@ async function manageSkills(targetDir = process.cwd()) {
   }
 
   const targetBase = path.resolve(targetDir, targetSubDir)
-  const targetPath = targetBase
+  const targetPath = copySkillsOnly ? path.join(targetBase, 'odac.js') : targetBase
 
   try {
     fs.mkdirSync(targetPath, {recursive: true})
@@ -222,7 +222,8 @@ async function manageSkills(targetDir = process.cwd()) {
       fs.cpSync(aiSourceDir, targetPath, {recursive: true})
     }
 
-    console.log(`\n✨ AI skills successfully synced to: \x1b[32m${targetSubDir}\x1b[0m`)
+    const finalSubDir = copySkillsOnly ? path.join(targetSubDir, 'odac.js') : targetSubDir
+    console.log(`\n✨ AI skills successfully synced to: \x1b[32m${finalSubDir}\x1b[0m`)
     console.log('Your AI Agent now has full knowledge of the ODAC Framework. 🚀')
   } catch (err) {
     console.error('❌ Failed to sync AI skills:', err.message)

package/client/odac.js

@@ -111,6 +111,12 @@ if (typeof window !== 'undefined') {
       // In constructor we can't call this.data() easily if it uses 'this' for caching properly before init
       // But based on original code logic:
       this.#data = this.data()
+
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => this.#initForms())
+      } else {
+        this.#initForms()
+      }
     }
 
     #ajax(options) {
@@ -795,6 +801,8 @@ if (typeof window !== 'undefined') {
     }
 
     #handleLoadComplete(data, callback) {
+      this.#initForms()
+
       if (this.actions.load)
         (Array.isArray(this.actions.load) ? this.actions.load : [this.actions.load]).forEach(fn => fn(this.page(), data.variables))
       if (this.actions.page && this.actions.page[this.page()])
@@ -808,6 +816,30 @@ if (typeof window !== 'undefined') {
       this.#isNavigating = false
     }
 
+    /**
+     * Scans the DOM for ODAC form components and registers submit handlers
+     * for any that haven't been initialized yet. Called on DOMContentLoaded
+     * and after every AJAX navigation to bind freshly rendered forms.
+     */
+    #initForms() {
+      const formTypes = [
+        {cls: 'odac-register-form', attr: 'data-odac-register'},
+        {cls: 'odac-login-form', attr: 'data-odac-login'},
+        {cls: 'odac-magic-login-form', attr: 'data-odac-magic-login'},
+        {cls: 'odac-custom-form', attr: 'data-odac-form'}
+      ]
+
+      for (const {cls, attr} of formTypes) {
+        document.querySelectorAll(`form.${cls}[${attr}]`).forEach(form => {
+          const token = form.getAttribute(attr)
+          const selector = `form[${attr}="${token}"]`
+          if (!this.#formSubmitHandlers.has(selector)) {
+            this.form({form: selector})
+          }
+        })
+      }
+    }
+
     loader(selector, elements, callback) {
       this.#loader.elements = elements
       this.#loader.callback = callback
@@ -993,19 +1025,6 @@ if (typeof window !== 'undefined') {
     }
     document.readyState === 'loading' ? document.addEventListener('DOMContentLoaded', init) : init()
   })()
-
-  document.addEventListener('DOMContentLoaded', () => {
-    ;['register', 'login'].forEach(type => {
-      document.querySelectorAll(`form.odac-${type}-form[data-odac-${type}]`).forEach(form => {
-        const token = form.getAttribute(`data-odac-${type}`)
-        window.Odac.form({form: `form[data-odac-${type}="${token}"]`})
-      })
-    })
-    document.querySelectorAll('form.odac-custom-form[data-odac-form]').forEach(form => {
-      const token = form.getAttribute('data-odac-form')
-      window.Odac.form({form: `form[data-odac-form="${token}"]`})
-    })
-  })
 } else {
   let socket = null
   const ports = new Set()

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

@@ -27,6 +27,25 @@ await Odac.DB.table('posts').insert({
 });
 ```
 
+## ID Strategy (NanoID)
+1.  **Schema-Driven**: Define string IDs with `type: 'nanoid'` in `schema/*.js`.
+2.  **Auto Generation**: On `insert()`, ODAC auto-generates missing nanoid fields.
+3.  **No Override**: If ID is explicitly provided, ODAC preserves it.
+4.  **Bulk Safe**: Auto-generation works for both single and bulk inserts.
+
+```javascript
+// schema/posts.js
+module.exports = {
+  columns: {
+    id: {type: 'nanoid', primary: true},
+    title: {type: 'string', length: 255}
+  }
+}
+
+// ID is generated automatically
+await Odac.DB.table('posts').insert({title: 'Hello'});
+```
+
 ## Migration Awareness
 1.  **Schema-First**: Structural DB changes must be defined in `schema/*.js`.
 2.  **Auto-Migrate**: Migrations run automatically at startup from `Database.init()`.

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

@@ -1,26 +1,120 @@
 ---
 name: backend-forms-validation-skill
-description: Secure ODAC form processing workflow with validation, CSRF protection, and safe request-to-database handling.
+description: Practical ODAC form usage patterns for register/login, magic-login, custom actions, and automatic database insert.
 metadata:
-  tags: backend, forms, validation, csrf, input-security, request-processing
+  tags: backend, forms, validation, register, login, magic-login, request-processing
 ---
 
 # Backend Forms & Validation Skill
 
-Processing form data securely and validating inputs.
+ODAC forms for validation, authentication flows, and safe request handling.
 
 ## Rules
-1.  **Validator**: Always use `Odac.Validator` for input.
-2.  **Auto-save**: Use `Odac.DB.table().save(Odac.Request.post())` for quick inserts.
-3.  **CSRF**: Ensure `{{ TOKEN }}` is in your HTML forms.
+1.  **Use ODAC form tags**: Prefer `<odac:register>`, `<odac:login>`, `<odac:magic-login>`, `<odac:form>` instead of manual raw form handlers.
+2.  **Do not add manual hidden security fields**: Keep forms clean and use ODAC defaults.
+3.  **Validation in template**: Define rules with `<odac:validate rule="..." message="..."/>`; they become both frontend HTML constraints and backend validator checks.
+4.  **Server-side enrichment**: Use `<odac:set>` for trusted fields (`compute`, `value`, `callback`, `if-empty`) instead of taking these values from user input.
+5.  **Action vs table**: In `<odac:form>`, use `table="..."` for automatic insert or `action="Class.method"` for custom business logic.
+
+## Form Type Variants
+
+### 1) Register Form
+```html
+<odac:register redirect="/dashboard" autologin="true">
+  <odac:input name="email" type="email" label="Email">
+    <odac:validate rule="required|email" message="Valid email required"/>
+  </odac:input>
+
+  <odac:input name="password" type="password" label="Password">
+    <odac:validate rule="required|minlen:8" message="Min 8 chars"/>
+  </odac:input>
+
+  <odac:set name="created_at" compute="now"/>
+  <odac:submit text="Register" loading="Processing..."/>
+</odac:register>
+```
+
+### 2) Login Form
+```html
+<odac:login redirect="/panel">
+  <odac:input name="email" type="email" label="Email">
+    <odac:validate rule="required|email" message="Email required"/>
+  </odac:input>
+
+  <odac:input name="password" type="password" label="Password">
+    <odac:validate rule="required" message="Password required"/>
+  </odac:input>
+
+  <odac:submit text="Login" loading="Logging in..."/>
+</odac:login>
+```
+
+### 3) Magic Login Form
+```html
+<odac:magic-login redirect="/dashboard" email-label="Work Email" submit-text="Send Link" />
+```
+
+```html
+<odac:magic-login redirect="/dashboard">
+  <odac:input name="email" type="email" label="Email">
+    <odac:validate rule="required|email" message="Valid email required"/>
+  </odac:input>
+  <odac:submit text="Send Magic Link" loading="Sending..."/>
+</odac:magic-login>
+```
+
+### 4) Custom Form with Automatic DB Insert
+```html
+<odac:form table="waitlist" redirect="/" success="Thank you!" clear="true">
+  <odac:input name="email" type="email" label="Email">
+    <odac:validate rule="required|email|unique" message="Email already exists"/>
+  </odac:input>
+
+  <odac:set name="created_at" compute="now"/>
+  <odac:set name="ip" compute="ip"/>
+  <odac:submit text="Join" loading="Joining..."/>
+</odac:form>
+```
+
+### 5) Custom Form with Controller Action
+```html
+<odac:form action="Contact.submit" clear="false">
+  <odac:input name="subject" type="text" label="Subject">
+    <odac:validate rule="required|minlen:3" message="Subject is too short"/>
+  </odac:input>
+  <odac:submit text="Send" loading="Sending..."/>
+</odac:form>
+```
 
-## Patterns
 ```javascript
-// Validation
-const check = Odac.Validator.run(Odac.Request.post(), {
-  email: 'required|email',
-  password: 'required|min:8'
-});
+module.exports = class Contact {
+  constructor(Odac) {
+    this.Odac = Odac
+  }
+
+  async submit(form) {
+    const data = form.data
+    if (!data.subject) return form.error('subject', 'Subject required')
+    return form.success('Message sent', '/thank-you')
+  }
+}
+```
 
-if (check.failed()) return Odac.Request.error(check.errors());
+## Field-Level Variants
+- **Input types**: `text`, `email`, `password`, `number`, `url`, `textarea`, `checkbox`.
+- **Validation mapping**: `required|minlen|maxlen|min|max|alpha|alphanumeric|numeric|email|url|accepted`.
+- **Pass-through attrs**: Unrecognized `<odac:input ...>` attributes are preserved into generated HTML input/textarea.
+- **Skip persistence**: Use `skip` on `<odac:input>` to validate a field but exclude it from final payload.
+- **Unique shorthand**: `unique` attribute on `<odac:input>` enables auth-register uniqueness list.
+
+## Patterns
+```javascript
+// Access validated data in action-driven custom form
+Odac.Route.class.post('/contact', class Contact {
+  async submit(form) {
+    const {email, message} = form.data
+    if (!email || !message) return form.error('_odac_form', 'Missing input')
+    return form.success('Saved successfully')
+  }
+})
 ```

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

@@ -19,7 +19,8 @@ ODAC migrations are **declarative**. The `schema/` directory is the single sourc
 4. **Index Sync**: Define indexes in schema; engine adds/removes them automatically.
 5. **Drop Behavior**: If a column/index is removed from schema, it is removed from DB on next startup.
 6. **Seeds**: Use `seed` + `seedKey` for idempotent reference data.
-7. **Data Transformations**: Use imperative files under `migration/` only for one-time data migration logic.
+7. **NanoID Columns**: `type: 'nanoid'` maps to string columns and missing values are auto-generated on insert/seed.
+8. **Data Transformations**: Use imperative files under `migration/` only for one-time data migration logic.
 
 ## Reference Patterns
 ### 1. Schema File (Final State)
@@ -29,7 +30,7 @@ ODAC migrations are **declarative**. The `schema/` directory is the single sourc
 
 module.exports = {
   columns: {
-    id: {type: 'increments'},
+    id: {type: 'nanoid', primary: true},
     email: {type: 'string', length: 255, nullable: false},
     role: {type: 'enum', values: ['admin', 'user'], default: 'user'},
     timestamps: {type: 'timestamps'}
@@ -44,6 +45,11 @@ module.exports = {
 }
 ```
 
+### NanoID Notes
+- `length` can be customized: `{type: 'nanoid', length: 12, primary: true}`.
+- If seed rows omit the nanoid field, ODAC fills it automatically.
+- If seed rows provide an explicit nanoid value, ODAC keeps it unchanged.
+
 ### 2. Multi-Database Layout
 ```
 schema/

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

@@ -1,60 +1,160 @@
 ---
 name: backend-validation-skill
-description: Fluent ODAC validation strategies for input hardening, brute-force protection, and standardized error responses.
+description: Detailed ODAC Validator usage for request validation, security checks, brute-force protection, and consistent API responses.
 metadata:
   tags: backend, validation, fluent-api, input-security, brute-force, error-handling
 ---
 
 # Backend Validation Skill
 
-The `Validator` service provides a fluent, chainable API for securing user input and enforcing business rules.
-
-## Architectural Approach
-Validation should happen as early as possible in the request lifecycle. The `Validator` service handles automatic error formatting and frontend integration.
+ODAC validation should be centralized with the fluent `Validator` API and returned in framework-standard result format.
 
 ## Core Rules
-1.  **Chaining**: Use the fluent API: `.post(key).check(rules).message(msg)`.
-2.  **Brute Force**: Protect sensitive endpoints with `.brute(attempts)`.
-3.  **Automatic Errors**: Use `await validator.error()` to check status and `await validator.result()` to return standardized JSON.
-4.  **Inverse Rules**: Use `!` to invert any rule (e.g., `!required`).
+1.  **Create validator per request**: Use `const validator = Odac.validator()`.
+2.  **Fail fast**: Run all checks, then immediately return on `await validator.error()`.
+3.  **Field-first messages**: Assign a specific `.message(...)` per check chain.
+4.  **Use standard result shape**: Return `await validator.result('Validation failed')` for errors.
+5.  **Protect sensitive flows**: Add `await validator.brute(n)` on login/reset/auth endpoints.
+
+## Minimal Flow
+```javascript
+module.exports = async Odac => {
+  const validator = Odac.validator()
+
+  validator.post('email').check('required|email').message('Valid email required')
+  validator.post('password').check('required|minlen:8').message('Password must be at least 8 characters')
+
+  if (await validator.error()) {
+    await validator.brute(5)
+    return await validator.result('Validation failed')
+  }
+
+  return await validator.success({ok: true})
+}
+```
+
+## API Surface
+- `post(key)`: Validate POST payload field.
+- `get(key)`: Validate querystring field.
+- `var(name, value)`: Validate computed/custom value.
+- `file(name)`: Validate uploaded file object.
+- `check(rules | boolean)`: Apply pipe rules or direct boolean validation.
+- `message(text)`: Set message for the latest check on current field.
+- `error()`: Runs validation and returns `true` if any error exists.
+- `result(message?, data?)`: Returns ODAC-standard response object.
+- `success(dataOrMessage?)`: Convenience wrapper for success payload.
+- `brute(maxAttempts = 5)`: Tracks failed attempts per hour/page/ip.
+
+## Rule Catalog
+
+### Type & format rules
+- `required`, `accepted`
+- `numeric`, `float`
+- `alpha`, `alphaspace`, `alphanumeric`, `alphanumericspace`, `username`
+- `email`, `ip`, `mac`, `domain`, `url`
+- `array`, `date`, `xss`
+
+### Length & value rules
+- `len:X`, `minlen:X`, `maxlen:X`
+- `min:X`, `max:X`
+- `equal:value`, `not:value`
+- `same:field`, `different:field`
+
+### String/date matching rules
+- `in:substring`, `notin:substring`
+- `regex:pattern`
+- `mindate:YYYY-MM-DD`, `maxdate:YYYY-MM-DD`
+
+### Auth/security rules
+- `usercheck`: Must be authenticated.
+- `user:field`: Input must match authenticated user field.
+- `disposable`: Email must be disposable.
+- `!disposable`: Email must not be disposable.
+
+### Inverse rules
+- Prefix any rule with `!` to invert: `!required`, `!email`, `!equal:admin`.
 
 ## Reference Patterns
 
-### 1. Standard Validation Chaining
+### 1) Multi-check per field with specific errors
 ```javascript
-module.exports = async function (Odac) {
-  const validator = Odac.Validator;
+module.exports = async Odac => {
+  const validator = Odac.validator()
 
   validator
-    .post('email').check('required|email').message('Valid email required')
-    .post('password').check('required|minlen:8').message('Password too short');
+    .post('password')
+    .check('required').message('Password is required')
+    .check('minlen:8').message('Minimum 8 characters')
+    .check('regex:[A-Z]').message('At least one uppercase letter')
+    .check('regex:[0-9]').message('At least one number')
 
   if (await validator.error()) {
-    return validator.result('Please fix input errors');
+    return await validator.result('Please fix input errors')
   }
 
-  // Proceed with validated data
-  return validator.success('Success');
-};
+  return await validator.success('Success')
+}
+```
+
+### 2) GET + POST + VAR together
+```javascript
+module.exports = async Odac => {
+  const validator = Odac.validator()
+  const plan = await Odac.request('plan')
+
+  validator.get('page').check('numeric|min:1').message('Invalid page')
+  validator.post('email').check('required|email|!disposable').message('Corporate email required')
+  validator.var('plan', plan).check('in:pro').message('Only pro plan is allowed')
+
+  if (await validator.error()) return await validator.result('Validation failed')
+  return await validator.success({ok: true})
+}
 ```
 
-### 2. Custom Variable and Security Validation
+### 3) Boolean check for business rules
 ```javascript
-validator.var('age', userAge).check('numeric|min:18').message('Must be 18+');
+module.exports = async Odac => {
+  const validator = Odac.validator()
+  const canPublish = await somePermissionCheck(Odac)
+
+  validator.post('title').check('required').message('Title required')
+  validator.var('permission', null).check(canPublish).message('No publish permission')
+
+  if (await validator.error()) return await validator.result('Validation failed')
+  return await validator.success('Published')
+}
+```
+
+### 4) Brute-force on auth endpoint
+```javascript
+module.exports = async Odac => {
+  const validator = Odac.validator()
+
+  validator.post('email').check('required|email').message('Email required')
+  validator.post('password').check('required').message('Password required')
+
+  if (await validator.error()) {
+    await validator.brute(5)
+    return await validator.result('Login failed')
+  }
 
-// Security checks
-validator.post('bio').check('xss').message('Malicious HTML detected');
-validator.var('auth', null).check('usercheck').message('Authentication required');
+  return await validator.success('OK')
+}
 ```
 
-### 3. Common Rules Reference
--   `required`, `email`, `numeric`, `username`, `url`, `ip`, `json`.
--   `len:X`, `minlen:X`, `maxlen:X`.
--   `mindate:YYYY-MM-DD`, `maxdate:YYYY-MM-DD`.
--   `regex:pattern`, `same:field`, `different:field`.
--   `!disposable`: Blocks temporary email providers.
+## Response Contract
+- **Success**:
+  - `result.success: true`
+  - optional `result.message`
+  - optional `data`
+- **Failure**:
+  - `result.success: false`
+  - `errors.{field}` map
+  - global errors may use `errors._odac_form`
 
 ## Best Practices
--   **Specific Messages**: Provide helpful error messages that guide the user.
--   **Security First**: Use the `xss` rule for any user-generated content that will be rendered later.
--   **Fail Fast**: Return the validation result immediately if `validator.error()` is true.
+- Keep validation at route/controller entry; do not defer to deep service layers.
+- Use separate `check()` calls when you need rule-specific messages.
+- Prefer `var()` for derived values instead of re-reading mutable request state.
+- Use `xss` for text fields that can later be rendered in HTML.
+- Always combine auth endpoints with `brute()` to reduce credential-stuffing risk.

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

@@ -1,28 +1,56 @@
 ---
 name: frontend-forms-api-skill
-description: AJAX form and API request patterns in odac.js for interactive UX and predictable frontend data flows.
+description: odac.js form submission patterns for parser-generated ODAC forms and predictable AJAX request handling.
 metadata:
-  tags: frontend, forms, ajax, api-requests, odac-get, odac-post
+  tags: frontend, forms, ajax, odac-form, register, login, magic-login
 ---
 
 # Frontend Forms & API Skill
 
-Handling AJAX form submissions and API requests.
+Handling ODAC AJAX form submissions generated from server-side form parsing.
 
 ## Rules
-1.  **Forms**: Use `odac.form('#id', callback)` for AJAX submission.
-2.  **Requests**: Use `odac.get()` and `odac.post()` for manual requests.
-3.  **Realtime**: Handle WebSocket events using Hub structures in `Odac.action()`.
+1.  **Bind by form selector**: Use `Odac.form({ form: 'selector' }, callback)` or short form `Odac.form('selector', callback)`.
+2.  **Leverage parser-generated forms**: `odac-register`, `odac-login`, `odac-magic-login`, and `odac-custom-form` are all auto-bound on page load and after every AJAX navigation.
+3.  **Expect JSON result shape**: Handle `result.success`, `result.message`, `result.redirect`, and `errors` in callback.
+4.  **Message/clear control**: Use `messages` and `clear` options for UX behavior.
 
 ## Patterns
 ```javascript
-// Form with automatic validation feedback
-odac.form('#my-form', (res) => {
-  if(res.success) odac.visit('/done');
-});
-
-// Simple API Check
-odac.get('/api/status', (data) => {
-  console.log('Status:', data);
-});
+// 1) Bind a parsed custom form
+Odac.form('form[data-odac-form]')
+
+// 2) Bind parsed register/login forms explicitly (optional)
+Odac.form('form[data-odac-register]')
+Odac.form('form[data-odac-login]')
+
+// 3) Bind parsed magic-login form manually
+Odac.form('form[data-odac-magic-login]', response => {
+  if (response?.result?.success && !response.result.redirect) {
+    const info = document.querySelector('[data-status]')
+    if (info) info.textContent = response.result.message
+  }
+})
+
+// 4) Advanced options: disable auto clear and hide success messages
+Odac.form(
+  {form: 'form[data-odac-form]', clear: false, messages: ['error']},
+  response => {
+    if (response?.result?.success && response.result.redirect) {
+      window.location.href = response.result.redirect
+    }
+  }
+)
+
+// 5) Manual GET request helper
+Odac.get('/api/status', data => {
+  const status = document.querySelector('[data-api-status]')
+  if (status) status.textContent = String(data?.status ?? '')
+})
 ```
+
+## Response Handling Contract
+- **Success**: `response.result.success === true`
+- **Redirect**: `response.result.redirect` exists when server wants navigation
+- **Form errors**: `response.errors.{fieldName}` maps to `odac-form-error="fieldName"`
+- **Global form error**: `response.errors._odac_form`