odac 0.9.0

package/docs/backend/03-config/04-environment-variables.md

@@ -0,0 +1,227 @@
+## 🌍 Environment Variables
+
+CandyPack supports environment variables through `.env` files, making it easy to manage sensitive data and environment-specific settings.
+
+### Creating a .env File
+
+Create a `.env` file in your website's root directory (same location as `config.json`):
+
+```bash
+# .env
+
+# Application
+NODE_ENV=production
+DEBUG=false
+APP_URL=https://myapp.com
+
+# Database
+MYSQL_HOST=localhost
+MYSQL_USER=root
+MYSQL_PASSWORD=super_secret_123
+MYSQL_DATABASE=myapp
+
+# API Keys
+STRIPE_SECRET_KEY=sk_live_xxxxx
+STRIPE_WEBHOOK_SECRET=whsec_xxxxx
+API_KEY=your_api_key_here
+
+# Mail
+MAIL_FROM=noreply@myapp.com
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=user@gmail.com
+SMTP_PASSWORD=app_password
+
+# Features
+FEATURE_BETA=true
+MAINTENANCE_MODE=false
+```
+
+### Using in config.json
+
+Reference environment variables using `${VARIABLE_NAME}` syntax:
+
+```json
+{
+  "mysql": {
+    "host": "${MYSQL_HOST}",
+    "user": "${MYSQL_USER}",
+    "password": "${MYSQL_PASSWORD}",
+    "database": "${MYSQL_DATABASE}"
+  },
+  "api": {
+    "stripe": {
+      "key": "${STRIPE_SECRET_KEY}",
+      "webhook": "${STRIPE_WEBHOOK_SECRET}"
+    }
+  },
+  "mail": {
+    "from": "${MAIL_FROM}"
+  }
+}
+```
+
+### Accessing in Controllers
+
+You can access environment variables in your controllers in three ways:
+
+#### 1. Using Candy.env() (Recommended)
+
+```javascript
+module.exports = function() {
+  const apiKey = Candy.env('API_KEY')
+  const debug = Candy.env('DEBUG', 'false')
+  const port = Candy.env('PORT', '3000')
+  
+  if (debug === 'true') {
+    console.log('Debug mode enabled')
+  }
+}
+```
+
+The second parameter is the default value if the variable is not set.
+
+#### 2. Using process.env
+
+```javascript
+module.exports = function() {
+  const nodeEnv = process.env.NODE_ENV
+  const debug = process.env.DEBUG === 'true'
+  const apiKey = process.env.API_KEY
+}
+```
+
+#### 3. From Candy.Config (if defined in config.json)
+
+```javascript
+module.exports = function() {
+  const dbHost = Candy.Config.mysql.host
+  const apiKey = Candy.Config.api.stripe.key
+}
+```
+
+### Practical Examples
+
+#### Feature Flags
+
+```javascript
+// controller/home.js
+module.exports = function() {
+  const betaEnabled = Candy.env('FEATURE_BETA', 'false') === 'true'
+  const maintenance = Candy.env('MAINTENANCE_MODE', 'false') === 'true'
+  
+  if (maintenance) {
+    return Candy.abort(503)
+  }
+  
+  Candy.set('betaEnabled', betaEnabled)
+  return Candy.View.render('home')
+}
+```
+
+#### API Integration
+
+```javascript
+// controller/payment.js
+module.exports = async function() {
+  const stripeKey = Candy.env('STRIPE_SECRET_KEY')
+  const webhookSecret = Candy.env('STRIPE_WEBHOOK_SECRET')
+  
+  const stripe = require('stripe')(stripeKey)
+  
+  // Process payment...
+}
+```
+
+#### Mail Configuration
+
+```javascript
+// controller/contact.js
+module.exports = async function() {
+  const mail = Candy.Mail()
+  
+  mail.from(Candy.env('MAIL_FROM', 'noreply@example.com'))
+  mail.to(Candy.request('email'))
+  mail.subject('Thank you for contacting us')
+  mail.html('<h1>We received your message!</h1>')
+  
+  await mail.send()
+  
+  return Candy.return({ success: true })
+}
+```
+
+### Security Best Practices
+
+#### 1. Add .env to .gitignore
+
+The `.env` file should never be committed to version control:
+
+```gitignore
+# .gitignore
+.env
+.env.local
+.env.*.local
+```
+
+#### 2. Create .env.example
+
+Provide a template for other developers:
+
+```bash
+# .env.example
+
+# Database
+MYSQL_HOST=localhost
+MYSQL_USER=root
+MYSQL_PASSWORD=your_password_here
+MYSQL_DATABASE=myapp
+
+# API Keys
+API_KEY=your_api_key_here
+```
+
+Commit `.env.example` to git, but not `.env`.
+
+#### 3. Different Environments
+
+Use different `.env` files for different environments:
+
+**Development (.env):**
+```bash
+NODE_ENV=development
+DEBUG=true
+MYSQL_HOST=localhost
+MYSQL_PASSWORD=dev123
+```
+
+**Production (.env):**
+```bash
+NODE_ENV=production
+DEBUG=false
+MYSQL_HOST=production.db.com
+MYSQL_PASSWORD=super_secure_production_password
+```
+
+### Comments and Formatting
+
+The `.env` file supports:
+
+- **Comments:** Lines starting with `#`
+- **Quotes:** Values can be wrapped in single or double quotes
+- **Spaces:** Spaces around `=` are trimmed
+
+```bash
+# This is a comment
+API_KEY=simple_value
+DB_PASSWORD="password with spaces"
+MAIL_FROM='noreply@example.com'
+```
+
+### Important Notes
+
+- Environment variables are loaded when the application starts
+- Changes to `.env` require restarting the application
+- The `.env` file is **optional** - you can use direct values in `config.json` if preferred
+- Variables defined in `.env` are available throughout your entire application
+- If a variable is not found, `Candy.env()` returns the default value or `undefined`

package/docs/backend/03-config/05-early-hints.md

@@ -0,0 +1,352 @@
+# Early Hints (HTTP 103)
+
+Early Hints is a performance optimization feature that allows the server to send preliminary HTTP headers to the browser before the final response is ready. This enables browsers to start preloading critical resources (CSS, JavaScript, fonts) while the server is still processing the request.
+
+## Zero-Config Operation
+
+Early Hints works automatically without any configuration. The framework:
+
+1. **Detects** critical resources from your HTML files at startup
+2. **Caches** resource information for fast access
+3. **Sends** Early Hints on subsequent requests automatically
+4. **Optimizes** page load performance transparently
+
+You don't need to do anything - it just works!
+
+## How It Works
+
+### Automatic Resource Detection
+
+When your application starts, CandyPack scans your `view/` and `skeleton/` directories and builds a manifest of critical resources:
+
+```html
+<!-- skeleton/main.html -->
+<html>
+  <head>
+    <link rel="stylesheet" href="/css/main.css">
+    <script src="/js/app.js"></script>
+  </head>
+  <body>...</body>
+</html>
+```
+
+The framework automatically detects:
+- ✅ CSS files (`<link rel="stylesheet">`)
+- ✅ Blocking JavaScript (`<script src="...">` without `defer` or `async`)
+- ✅ Web fonts (`<link href="...woff2">`)
+
+### Request Flow
+
+**First Request:**
+```
+1. Browser requests /
+2. Controller sets view: skeleton('main')
+3. Framework checks manifest for 'skeleton/main'
+4. Sends 103 Early Hints with CSS/JS links
+5. Browser starts downloading resources
+6. Server processes request (database queries, etc.)
+7. Sends 200 OK with HTML
+8. Resources already loaded!
+```
+
+**Subsequent Requests:**
+Same flow - hints are sent from the manifest immediately.
+
+## Configuration (Optional)
+
+While Early Hints works automatically, you can customize it in `config.json`:
+
+```json
+{
+  "earlyHints": {
+    "enabled": true,
+    "auto": true,
+    "maxResources": 5
+  }
+}
+```
+
+### Options
+
+#### `enabled` (boolean, default: `true`)
+Enable or disable Early Hints globally.
+
+```json
+{
+  "earlyHints": {
+    "enabled": false
+  }
+}
+```
+
+#### `auto` (boolean, default: `true`)
+Enable automatic resource detection and hint generation.
+
+```json
+{
+  "earlyHints": {
+    "auto": false
+  }
+}
+```
+
+#### `maxResources` (number, default: `5`)
+Maximum number of resources to include in Early Hints. Limiting this prevents overwhelming the browser with too many preload hints.
+
+```json
+{
+  "earlyHints": {
+    "maxResources": 3
+  }
+}
+```
+
+## What Gets Preloaded?
+
+The framework intelligently selects only **critical resources** from the `<head>` section:
+
+### ✅ Included
+- CSS files: `<link rel="stylesheet" href="/css/main.css">`
+- Blocking JavaScript: `<script src="/js/app.js"></script>`
+- Web fonts: `<link href="/fonts/main.woff2" as="font">` (supports `.woff`, `.woff2`, `.ttf`, `.otf`, `.eot`)
+
+### ❌ Excluded
+- Deferred scripts: `<script src="/js/app.js" defer></script>`
+- Async scripts: `<script src="/js/app.js" async></script>`
+- Deferred CSS: `<link rel="stylesheet" href="/css/non-critical.css" defer>`
+- Resources in `<body>` (not critical for initial render)
+- Images (handled by browser's own optimization)
+
+## Excluding Resources from Early Hints
+
+If you want to prevent specific resources from being preloaded, use the `defer` attribute:
+
+```html
+<head>
+  <!-- Critical CSS - will be preloaded -->
+  <link rel="stylesheet" href="/css/critical.css">
+  
+  <!-- Non-critical CSS - will NOT be preloaded -->
+  <link rel="stylesheet" href="/css/non-critical.css" defer>
+  
+  <!-- Critical JS - will be preloaded -->
+  <script src="/js/app.js"></script>
+  
+  <!-- Analytics JS - will NOT be preloaded -->
+  <script src="/js/analytics.js" defer></script>
+</head>
+```
+
+The `defer` attribute works consistently for both CSS and JavaScript:
+- **For JS**: Browser's native defer behavior (execute after DOM is ready)
+- **For CSS**: CandyPack-specific (exclude from Early Hints, but still loads normally)
+
+This is useful for:
+- Non-critical styles (animations, print styles)
+- Analytics and tracking scripts
+- Third-party widgets
+- Below-the-fold content styles
+
+## Performance Impact
+
+Early Hints is most effective when:
+- Server-side processing takes time (database queries, API calls)
+- You have critical CSS/JS files in `<head>`
+- Users are on slower connections
+
+### Example Improvement
+
+**Without Early Hints:**
+```
+Server processing: 500ms
+Resource download: 200ms
+Total: 700ms
+```
+
+**With Early Hints:**
+```
+Server processing: 500ms (resources downloading in parallel)
+Total: 500ms (200ms saved!)
+```
+
+## Browser Support
+
+- Chrome 103+
+- Edge 103+
+- Firefox 103+
+- Safari (partial support)
+
+Older browsers simply ignore the `103` response and wait for the `200 OK` - no breaking changes!
+
+## Technical Details
+
+### Manifest System
+
+At startup, the framework builds an in-memory manifest:
+
+```javascript
+{
+  'view/header/home': [
+    {href: '/css/header.css', as: 'style'},
+    {href: '/js/header.js', as: 'script'}
+  ],
+  'skeleton/main': [
+    {href: '/css/main.css', as: 'style'},
+    {href: '/js/app.js', as: 'script'}
+  ]
+}
+```
+
+### Proxy Integration
+
+CandyPack's architecture uses a proxy layer. Early Hints are:
+1. Generated in the framework
+2. Sent via `X-Candy-Early-Hints` header to proxy
+3. Forwarded to client as `103 Early Hints` by proxy
+
+This ensures Early Hints work correctly in the multi-domain hosting environment.
+
+### Node.js Requirements
+
+- Requires Node.js 18+ for `response.writeEarlyHints()` API
+- Automatically disabled on older Node.js versions
+- No errors or warnings - graceful degradation
+
+## Best Practices
+
+### 1. Keep Critical Resources in `<head>`
+
+```html
+<!-- Good: Critical CSS in head -->
+<head>
+  <link rel="stylesheet" href="/css/critical.css">
+</head>
+
+<!-- Bad: CSS in body -->
+<body>
+  <link rel="stylesheet" href="/css/styles.css">
+</body>
+```
+
+### 2. Use `defer` for Non-Critical Scripts
+
+```html
+<!-- Good: Non-critical scripts deferred -->
+<script src="/js/analytics.js" defer></script>
+
+<!-- Bad: Blocking script for non-critical feature -->
+<script src="/js/analytics.js"></script>
+```
+
+### 3. Minimize Critical Resources
+
+Aim for 3-5 critical resources maximum. Combine CSS/JS files if needed:
+
+```html
+<!-- Good: Combined critical CSS -->
+<link rel="stylesheet" href="/css/critical.css">
+
+<!-- Bad: Too many separate files -->
+<link rel="stylesheet" href="/css/reset.css">
+<link rel="stylesheet" href="/css/typography.css">
+<link rel="stylesheet" href="/css/layout.css">
+<link rel="stylesheet" href="/css/components.css">
+```
+
+Or use `defer` for non-critical resources:
+
+```html
+<!-- Good: Critical resources only -->
+<link rel="stylesheet" href="/css/critical.css">
+<link rel="stylesheet" href="/css/animations.css" defer>
+<link rel="stylesheet" href="/css/print.css" defer>
+```
+
+### 4. Preload Fonts
+
+If using custom fonts, include them in `<head>`. All common font formats are supported:
+
+```html
+<!-- WOFF2 (recommended, best compression) -->
+<link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin>
+
+<!-- WOFF (fallback for older browsers) -->
+<link rel="preload" href="/fonts/main.woff" as="font" type="font/woff" crossorigin>
+
+<!-- TrueType/OpenType -->
+<link rel="preload" href="/fonts/main.ttf" as="font" type="font/ttf" crossorigin>
+<link rel="preload" href="/fonts/main.otf" as="font" type="font/otf" crossorigin>
+```
+
+## Troubleshooting
+
+### Early Hints Not Working?
+
+**Check Node.js version:**
+```bash
+node --version  # Should be 18.0.0 or higher
+```
+
+**Verify configuration:**
+```json
+{
+  "earlyHints": {
+    "enabled": true  // Make sure it's not disabled
+  }
+}
+```
+
+**Check browser DevTools:**
+1. Open Network tab
+2. Look for `103 Early Hints` status
+3. Check response headers for `Link:` headers
+
+### No Resources Detected?
+
+Make sure resources are in `<head>`:
+```html
+<!-- This will be detected -->
+<head>
+  <link rel="stylesheet" href="/css/main.css">
+</head>
+
+<!-- This will NOT be detected -->
+<body>
+  <link rel="stylesheet" href="/css/main.css">
+</body>
+```
+
+### Too Many Resources?
+
+Reduce `maxResources` in config:
+```json
+{
+  "earlyHints": {
+    "maxResources": 3
+  }
+}
+```
+
+## Disabling Early Hints
+
+Removing the `earlyHints` configuration section from your `config.json` is equivalent to using the default settings, which has the feature enabled. To truly disable Early Hints, you must explicitly set `enabled: false` in your configuration:
+
+```json
+{
+  "earlyHints": {
+    "enabled": false
+  }
+}
+```
+
+## Summary
+
+Early Hints is a powerful performance optimization that:
+- ✅ Works automatically (zero-config)
+- ✅ Detects critical resources intelligently
+- ✅ Improves page load times
+- ✅ Requires no code changes
+- ✅ Degrades gracefully on older browsers
+- ✅ Can be customized if needed
+
+Just build your app normally, and Early Hints will optimize it for you!

package/docs/backend/04-routing/01-basic-page-routes.md

@@ -0,0 +1,28 @@
+## 📄 Basic Page Routes
+
+#### `page(path, controller)`
+This is the most common method. It maps a URL path to a controller that is expected to render a standard HTML page. It handles `GET` requests.
+
+-   `path`: The URL path to match (e.g., `/about`).
+-   `controller`: The name of the controller file.
+
+```javascript
+// When a user visits yoursite.com/
+Candy.Route.page('/', 'index');
+
+// When a user visits yoursite.com/contact
+Candy.Route.page('/contact', 'contact-form');
+```
+
+**Page Identifier:** The controller filename becomes the page identifier in the frontend. For example, `'contact-form'` becomes accessible as `Candy.page()` returning `"contact-form"`. This allows you to run page-specific JavaScript:
+
+```javascript
+// Frontend
+Candy.action({
+  page: {
+    'contact-form': function() {
+      console.log('Contact form page loaded')
+    }
+  }
+})
+```

package/docs/backend/04-routing/02-controller-less-view-routes.md

@@ -0,0 +1,43 @@
+## ⚡ Controller-less View Routes
+
+For simple pages that don't require complex logic in a controller, you can render a view directly from your route file by passing a view configuration object as the second parameter.
+
+#### `page(path, { ... })`
+This defines a page and immediately tells it which view components to render.
+
+```javascript
+Candy.Route.page("/users", {
+    skeleton: "dashboard",
+    header: "dashboard.main",
+    sidebar: "dashboard.main",
+    footer: "dashboard.main",
+    content: "users"
+});
+```
+This example tells CandyPack to render the `/users` page by assembling a view from multiple parts, likely using a main `dashboard` skeleton and filling it with different content blocks.
+
+**Page Identifier:** When using view objects, the page identifier (accessible via `Candy.page()` in frontend) is automatically set to the `content` or `all` value. In this example, the page identifier would be `"users"`, allowing you to run page-specific JavaScript:
+
+```javascript
+// Frontend
+Candy.action({
+  page: {
+    users: function() {
+      console.log('Users page loaded')
+    }
+  }
+})
+```
+
+#### `auth.page(path, { ... })`
+Similar to `page()`, but requires authentication. Only authenticated users can access this route.
+
+```javascript
+// Only authenticated users can see the dashboard
+Candy.Route.auth.page('/', {
+    skeleton: 'main', 
+    content: 'dashboard'
+});
+```
+
+See [Authentication-Aware Routes](04-authentication-aware-routes.md) for more details.

package/docs/backend/04-routing/03-api-and-data-routes.md

@@ -0,0 +1,20 @@
+## 📦 API and Data Routes
+
+#### `get(path, controller, options)`
+Defines a route that responds to `GET` requests. This is ideal for API endpoints that return data (like JSON).
+
+-   `options`: By default, CandyPack protects routes from CSRF attacks by checking for a token. For a public API or stateless endpoint, you must disable this by passing `{ token: false }`. If you don't, the server will expect a token and will not return a response if one isn't provided.
+
+```javascript
+// An API endpoint at GET /api/users/123
+// We disable the token check as this is a public API.
+Candy.Route.get('/api/users/{id}', 'api/users.get', { token: false });
+```
+
+#### `post(path, controller, options)`
+Defines a route that responds to `POST` requests, typically used for form submissions. The `{ token: false }` option works here as well, but should be used with caution as POST routes are primary targets for CSRF attacks.
+
+```javascript
+// A form that posts data to /login
+Candy.Route.post('/login', 'auth.login');
+```