rhales 0.3.0 → 0.5.3

data/README.md

@@ -1,91 +1,90 @@
 # Rhales - Ruby Single File Components
 
 > [!CAUTION]
-> **Early Development Release** - Rhales is in active development (v0.1.0). The API may change between versions. While functional and tested, it's recommended for experimental use and contributions rather than production applications. Please report issues and provide feedback through GitHub.
+> **Early Development Release** - Rhales is in active development (v0.5). The API underwent breaking changes from v0.4. While functional and tested, it's recommended for experimental use and contributions. Please report issues and provide feedback through GitHub.
 
-Rhales is a framework for building server-rendered components with client-side data hydration using `.rue` files called RSFCs (Ruby Single File Components). Similar to Vue.js single file components but designed for Ruby applications.
+Rhales is a **type-safe contract enforcement framework** for server-rendered pages with client-side data hydration. It uses `.rue` files (Ruby Single File Components) that combine Zod v4 schemas, Handlebars templates, and documentation into a single contract-first format.
 
-About the name:
-It all started with a simple mustache template many years ago. The successor to mustache, "Handlebars" is a visual analog for a mustache and successor to the format. "Two Whales Kissing" is another visual analog for a mustache and since we're working with Ruby we could call that, "Two Whales Kissing for Ruby", which is very long. Rhales combines Ruby and Whales into a one-word name for our library. It's a perfect name with absolutely no ambiguity or risk of confusion with other gems.
+**About the name:** It all started with a simple mustache template many years ago. Mustache's successor, "Handlebars," is a visual analog for a mustache. "Two Whales Kissing" is another visual analog for a mustache, and since we're working with Ruby, we call it "Rhales" (Ruby + Whales). It's a perfect name with absolutely no ambiguity or risk of confusion.
+
+## What's New in v0.5
+
+- ✅ **Schema-First Design**: Replaced `<data>` sections with Zod v4 `<schema>` sections
+- ✅ **Type Safety**: Contract enforcement between backend and frontend
+- ✅ **Simplified API**: Removed deprecated parameters (`sess`, `cust`, `props:`, `app_data:`)
+- ✅ **Clear Context Layers**: Renamed `app` → `request` for clarity
+- ✅ **Schema Tooling**: Rake tasks for schema generation and validation
+- ✅ **100% Migration**: All demo templates use schemas
+
+**Breaking changes from v0.4:** See [Migration Guide](#migration-from-v04-to-v05) below.
 
 ## Features
 
-- **Server-side template rendering** with Handlebars-style syntax
-- **Client-side data hydration** with secure JSON injection
-- **Window collision detection** prevents silent data overwrites
-- **Explicit merge strategies** for controlled data sharing (shallow, deep, strict)
-- **Clear security boundaries** between server context and client data
-- **Partial support** for component composition
-- **Pluggable authentication adapters** for any auth system
-- **Security-first design** with XSS protection and automatic CSP generation
+- **Schema-based hydration** with Zod v4 for type-safe client data
+- **Server-side rendering** with Handlebars-style template syntax
+- **Three-layer context** for request, server, and client data separation
+- **Security-first design** with explicit server-to-client boundaries
+- **Layout & partial composition** for component reuse
+- **CSP support** with automatic nonce generation
+- **Framework agnostic** - works with Rails, Roda, Sinatra, Grape, Padrino
 - **Dependency injection** for testability and flexibility
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem 'rhales'
 ```
 
-And then execute:
+Then execute:
 
 ```bash
 bundle install
 ```
 
-Or install it yourself as:
-
-```bash
-gem install rhales
-```
-
 ## Quick Start
 
 ### 1. Configure Rhales
 
 ```ruby
-# Configure Rhales in your application initialization
+# config/initializers/rhales.rb or similar
 Rhales.configure do |config|
   config.default_locale = 'en'
-  config.template_paths = ['templates']  # or 'app/templates', 'views/templates', etc.
+  config.template_paths = ['templates']
   config.features = { dark_mode: true }
   config.site_host = 'example.com'
 
-  # CSP configuration (enabled by default)
-  config.csp_enabled = true           # Enable automatic CSP header generation
-  config.auto_nonce = true            # Automatically generate nonces
-  config.csp_policy = {               # Customize CSP policy (optional)
-    'default-src' => ["'self'"],
-    'script-src' => ["'self'", "'nonce-{{nonce}}'"],
-    'style-src' => ["'self'", "'nonce-{{nonce}}'", "'unsafe-hashes'"]
-    # ... more directives
-  }
+  # CSP configuration
+  config.csp_enabled = true
+  config.auto_nonce = true
 end
+
+# Optional: Configure logger
+Rhales.logger = Rails.logger
 ```
 
-### 2. Create a Simple Component
+### 2. Create a .rue Component
 
-Create a `.rue` file in your templates directory:
+Create `templates/hello.rue`:
 
-```rue
-<!-- templates/hello.rue -->
-<data>
-{
-  "greeting": "{{greeting}}",
-  "user_name": "{{user.name}}"
-}
-</data>
+```xml
+<schema lang="js-zod" window="appData">
+const schema = z.object({
+  greeting: z.string(),
+  userName: z.string()
+});
+</schema>
 
 <template>
 <div class="hello-component">
-  <h1>{{greeting}}, {{user.name}}!</h1>
-  <p>Welcome to Rhales RSFC!</p>
+  <h1>{{greeting}}, {{userName}}!</h1>
+  <p>Welcome to Rhales v0.5</p>
 </div>
 </template>
 
 <logic>
-# Simple greeting component
+# Simple greeting component demonstrating schema-based hydration
 </logic>
 ```
 
@@ -93,232 +92,469 @@ Create a `.rue` file in your templates directory:
 
 ```ruby
 # In your controller/route handler
-view = Rhales::View.new(request, session, user, 'en',
-  props: {
+view = Rhales::View.new(
+  request,
+  client: {
     greeting: 'Hello',
-    user: { name: 'World' }
+    userName: 'World'
   }
 )
 
 html = view.render('hello')
-# Returns HTML with embedded JSON for client-side hydration
+# Returns HTML with schema-validated data injected as window.appData
+```
+
+## The .rue File Format
+
+A `.rue` file contains three sections:
+
+```xml
+<schema lang="js-zod" window="data" [version="2"] [envelope="Envelope"] [layout="layouts/main"]>
+const schema = z.object({
+  // Zod v4 schema defining client data contract
+});
+</schema>
+
+<template>
+  <!-- Handlebars-style HTML template -->
+  <!-- Has access to ALL context layers -->
+</template>
+
+<logic>
+# Optional Ruby documentation/comments
+</logic>
+```
+
+### Schema Section Attributes
+
+| Attribute | Required | Description | Example |
+|-----------|----------|-------------|---------|
+| `lang` | Yes | Schema language (currently only `js-zod`) | `"js-zod"` |
+| `window` | Yes | Browser global name | `"appData"` → `window.appData` |
+| `version` | No | Schema version | `"2"` |
+| `envelope` | No | Response wrapper type | `"SuccessEnvelope"` |
+| `layout` | No | Layout template reference | `"layouts/main"` |
+
+### Zod Schema Examples
+
+```javascript
+// Simple types
+z.object({
+  user: z.string(),
+  count: z.number(),
+  active: z.boolean()
+})
+
+// Complex nested structures
+z.object({
+  user: z.object({
+    id: z.number(),
+    name: z.string(),
+    email: z.string().email()
+  }),
+  items: z.array(z.object({
+    id: z.number(),
+    title: z.string(),
+    price: z.number().positive()
+  })),
+  metadata: z.record(z.string())
+})
+
+// Optional and nullable
+z.object({
+  theme: z.string().optional(),
+  lastLogin: z.string().nullable()
+})
 ```
 
 ## Context and Data Model
 
-Rhales uses a **two-layer data model** for template rendering:
+Rhales uses a **three-layer context system** that separates concerns and enforces security boundaries:
+
+### 1. Request Layer (Framework Data)
 
-### 1. App Data (Framework Layer)
-All framework-provided data is available under the `app` namespace:
+Framework-provided data available under the `request` namespace:
 
 ```handlebars
-<!-- Framework data through app namespace -->
-{{app.csrf_token}}       <!-- CSRF token for forms -->
-{{app.nonce}}            <!-- CSP nonce for scripts -->
-{{app.authenticated}}    <!-- Authentication state -->
-{{app.environment}}      <!-- Current environment -->
-{{app.features.dark_mode}} <!-- Feature flags -->
-{{app.theme_class}}      <!-- Current theme -->
-```
-
-**Available App Variables:**
-- `app.api_base_url` - Base URL for API calls
-- `app.authenticated` - Whether user is authenticated
-- `app.csrf_token` - CSRF token for forms
-- `app.development` - Whether in development mode
-- `app.environment` - Current environment (production/staging/dev)
-- `app.features` - Feature flags hash
-- `app.nonce` - CSP nonce for inline scripts
-- `app.theme_class` - Current theme CSS class
-
-### 2. Props Data (Application Layer)
-Your application-specific data passed to each view:
+{{request.nonce}}          <!-- CSP nonce for scripts -->
+{{request.csrf_token}}     <!-- CSRF token for forms -->
+{{request.authenticated?}} <!-- Authentication state -->
+{{request.locale}}         <!-- Current locale -->
+```
+
+**Available Request Variables:**
+- `request.nonce` - CSP nonce for inline scripts/styles
+- `request.csrf_token` - CSRF token for form submissions
+- `request.authenticated?` - User authentication status
+- `request.locale` - Current locale (e.g., 'en', 'es')
+- `request.session` - Session object (if available)
+- `request.user` - User object (if available)
+
+### 2. Server Layer (Template-Only Data)
+
+Application data that stays on the server (not sent to browser):
+
+```ruby
+view = Rhales::View.new(
+  request,
+  server: {
+    page_title: 'Dashboard',
+    vite_assets_html: vite_javascript_tag('application'),
+    admin_notes: 'Internal use only'  # Never sent to client
+  }
+)
+```
 
 ```handlebars
-<!-- Application data -->
-{{user.name}}            <!-- Direct access -->
-{{page_title}}           <!-- Props take precedence -->
-{{#if user.admin?}}
-  <a href="/admin">Admin Panel</a>
-{{/if}}
+{{server.page_title}}        <!-- Available in templates -->
+{{server.vite_assets_html}}  <!-- Server-side only -->
 ```
 
+### 3. Client Layer (Serialized to Browser)
+
+Data serialized to browser via schema validation:
+
+```ruby
+view = Rhales::View.new(
+  request,
+  client: {
+    user: current_user.name,
+    items: Item.all.map(&:to_h)
+  }
+)
+```
+
+```handlebars
+{{client.user}}   <!-- Also serialized to window.appData.user -->
+{{client.items}}  <!-- Also serialized to window.appData.items -->
+```
+
+### Context Layer Fallback
+
+Variables can use shorthand notation (checks `client` → `server` → `request`):
+
+```handlebars
+<!-- Explicit layer access -->
+{{client.user}}
+{{server.page_title}}
+{{request.nonce}}
+
+<!-- Shorthand (automatic layer lookup) -->
+{{user}}        <!-- Finds client.user -->
+{{page_title}}  <!-- Finds server.page_title -->
+{{nonce}}       <!-- Finds request.nonce -->
+```
+
+## Security Model: Server-to-Client Boundary
+
+The `.rue` format enforces a **security boundary at the server-to-client handoff**:
+
 ### Server Templates: Full Context Access
-Templates have complete access to all server-side data:
-- User objects and authentication state
-- Database connections and internal APIs
-- Configuration values and secrets
-- Request metadata (CSRF tokens, nonces)
+
+Templates have access to ALL context layers:
 
 ```handlebars
-<!-- Full server access in templates -->
-{{#if user.admin?}}
-  <a href="/admin">Admin Panel</a>
+<!-- Server-side template has full access -->
+{{#if request.authenticated?}}
+  <div class="admin-panel">
+    <h2>Welcome {{client.user}}</h2>
+    <p>Secret: {{server.admin_notes}}</p>  <!-- Not sent to browser -->
+  </div>
 {{/if}}
-<div class="{{app.theme_class}}">{{user.full_name}}</div>
 ```
 
 ### Client Data: Explicit Allowlist
-Only data declared in `<data>` sections reaches the browser:
 
-```rue
-<data>
-{
-  "display_name": "{{user.name}}",
-  "preferences": {
-    "theme": "{{user.theme}}"
-  }
-}
-</data>
+Only schema-declared data reaches the browser:
+
+```xml
+<schema lang="js-zod" window="data">
+const schema = z.object({
+  user: z.string(),
+  userId: z.number()
+  // NOT declared: admin_notes, secret_key, internal_api_url
+});
+</schema>
 ```
 
-Becomes:
+**Result on client:**
+
 ```javascript
 window.data = {
-  "display_name": "John Doe",
-  "preferences": { "theme": "dark" }
+  user: "Alice",
+  userId: 123
+  // admin_notes, secret_key NOT included (never declared in schema)
 }
-// No access to user.admin?, internal APIs, etc.
 ```
 
-This creates a **REST API-like boundary** where you explicitly declare what data crosses the server-to-client security boundary.
+This creates a **REST API-like boundary** where you explicitly declare what data crosses the security boundary.
 
-For complete details, see [Context and Data Boundaries Documentation](docs/CONTEXT_AND_DATA_BOUNDARIES.md).
-  config.site_ssl_enabled = true
-end
+### ⚠️ Critical: Schema Validates, Does NOT Filter
+
+**IMPORTANT**: The schema does NOT filter which data gets serialized. The ENTIRE `client:` hash is serialized to the browser. The schema only validates that the serialized data matches the expected structure.
+
+```ruby
+# ⚠️ DANGER: ALL client data serialized (including password!)
+view = Rhales::View.new(request,
+  client: {
+    user: 'Alice',
+    password: 'secret123',  # ← Serialized to browser!
+    api_key: 'xyz'          # ← Serialized to browser!
+  }
+)
+
+# Schema only validates structure, doesn't prevent serialization
+# If schema doesn't include password/api_key, validation FAILS
+# But data already leaked to browser in HTML response
 ```
 
-### 2. Create a .rue file
+**Your Responsibility**: Ensure the `client:` hash contains ONLY safe, public data. Never pass:
+- Passwords or credentials
+- API keys or secrets
+- Internal URLs or configuration
+- Personally identifiable information (PII) not intended for client
 
-Create `templates/dashboard.rue` - notice how the `<data>` section defines exactly what your frontend app will receive:
+The schema is a **contract validator**, not a **data filter**.
+
+## Complete Example: Dashboard
+
+### Backend (Ruby)
+
+```ruby
+# config/routes.rb (Rails) or route handler
+class DashboardController < ApplicationController
+  def show
+    view = Rhales::View.new(
+      request,
+      client: {
+        user: current_user.name,
+        userId: current_user.id,
+        items: current_user.items.map { |i|
+          { id: i.id, name: i.name, price: i.price }
+        },
+        apiBaseUrl: ENV['API_BASE_URL']
+      },
+      server: {
+        page_title: 'Dashboard',
+        internal_notes: 'User has premium access',  # Server-only
+        vite_assets: vite_javascript_tag('application')
+      }
+    )
+
+    render html: view.render('dashboard').html_safe
+  end
+end
+```
+
+### Frontend (.rue file)
 
 ```xml
-<data window="appState" schema="@/src/types/app-state.d.ts">
-{
-  "user": {
-    "id": "{{user.id}}",
-    "name": "{{user.name}}",
-    "email": "{{user.email}}",
-    "preferences": {{user.preferences}}
-  },
-  "products": {{recent_products}},
-  "cart": {
-    "items": {{cart.items}},
-    "total": "{{cart.total}}"
-  },
-  "api": {
-    "baseUrl": "{{api_base_url}}",
-    "csrfToken": "{{csrf_token}}"
-  },
-  "features": {{enabled_features}}
-}
-</data>
+<!-- templates/dashboard.rue -->
+<schema lang="js-zod" version="2" window="dashboardData" layout="layouts/main">
+const schema = z.object({
+  user: z.string(),
+  userId: z.number(),
+  items: z.array(z.object({
+    id: z.number(),
+    name: z.string(),
+    price: z.number()
+  })),
+  apiBaseUrl: z.string().url()
+});
+</schema>
 
 <template>
-<!doctype html>
-<html lang="{{locale}}" class="{{theme_class}}">
-<head>
-  <title>{{page_title}}</title>
-  <meta name="csrf-token" content="{{csrf_token}}">
-</head>
-<body>
-  <!-- Critical: The mounting point for your frontend framework -->
-  <div id="app">
-    <!-- Server-rendered content for SEO and initial load -->
-    <nav>{{> navigation}}</nav>
-    <main>
-      <h1>{{page_title}}</h1>
-      {{#if user}}
-        <p>Welcome back, {{user.name}}!</p>
-      {{else}}
-        <p>Please sign in to continue.</p>
-      {{/if}}
-    </main>
-  </div>
+<div class="dashboard">
+  <h1>{{server.page_title}}</h1>
+
+  {{#if request.authenticated?}}
+    <p>Welcome, {{client.user}}!</p>
+
+    <div class="items">
+      {{#each client.items}}
+        <div class="item">
+          <h3>{{name}}</h3>
+          <p>${{price}}</p>
+        </div>
+      {{/each}}
+    </div>
+  {{else}}
+    <p>Please log in</p>
+  {{/if}}
+</div>
 
-  <!--
-    RSFC automatically generates hydration scripts:
-    - <script type="application/json" id="app-state-data">{...}</script>
-    - <script>window.appState = JSON.parse(...);</script>
-  -->
+<!-- Client-side JavaScript can access validated data -->
+<script nonce="{{request.nonce}}">
+  // window.dashboardData is populated with schema-validated data
+  console.log('User ID:', window.dashboardData.userId);
+  console.log('Items:', window.dashboardData.items);
 
-  <!-- Your frontend framework takes over from here -->
-  <script nonce="{{nonce}}" type="module" src="/assets/app.js"></script>
-</body>
-</html>
+  // Fetch additional data from API
+  fetch(window.dashboardData.apiBaseUrl + '/user/preferences')
+    .then(r => r.json())
+    .then(prefs => console.log('Preferences:', prefs));
+</script>
 </template>
+
+<logic>
+# Dashboard component demonstrates:
+# - Schema-based type safety
+# - Three-layer context access
+# - Conditional rendering based on auth
+# - Client-side data hydration
+# - CSP nonce support
+</logic>
 ```
 
-### 3. The Manifold: Server-to-SPA Handoff
+### Generated HTML
 
-This example demonstrates Rhales' core value proposition: **eliminating the coordination gap** between server state and frontend frameworks.
+```html
+<div class="dashboard">
+  <h1>Dashboard</h1>
+  <p>Welcome, Alice!</p>
+  <div class="items">
+    <div class="item"><h3>Widget</h3><p>$19.99</p></div>
+    <div class="item"><h3>Gadget</h3><p>$29.99</p></div>
+  </div>
+</div>
+
+<!-- Hydration script injected automatically -->
+<script id="rsfc-data-abc123" type="application/json">
+{"user":"Alice","userId":123,"items":[{"id":1,"name":"Widget","price":19.99},{"id":2,"name":"Gadget","price":29.99}],"apiBaseUrl":"https://api.example.com"}
+</script>
+<script nonce="nonce-xyz789">
+window.dashboardData = JSON.parse(document.getElementById('rsfc-data-abc123').textContent);
+</script>
+
+<!-- Your client-side script -->
+<script nonce="nonce-xyz789">
+  console.log('User ID:', window.dashboardData.userId);
+  console.log('Items:', window.dashboardData.items);
+  fetch(window.dashboardData.apiBaseUrl + '/user/preferences')
+    .then(r => r.json())
+    .then(prefs => console.log('Preferences:', prefs));
+</script>
+```
+
+## Template Syntax
+
+Rhales uses Handlebars-style syntax:
+
+### Variables
+
+```handlebars
+{{variable}}       <!-- HTML-escaped (safe) -->
+{{{variable}}}     <!-- Raw output (use carefully!) -->
+{{object.property}}  <!-- Dot notation -->
+{{array.0}}        <!-- Array index -->
+```
+
+### Conditionals
+
+```handlebars
+{{#if condition}}
+  Content when true
+{{else}}
+  Content when false
+{{/if}}
 
-**What you get:**
-- ✅ **Declarative data contract**: The `<data>` section explicitly defines what your frontend receives
-- ✅ **Type safety ready**: Schema reference points to TypeScript definitions
-- ✅ **Zero coordination overhead**: No separate API design needed for initial state
-- ✅ **SEO + SPA**: Server-rendered HTML with automatic client hydration
-- ✅ **Security boundaries**: Only explicitly declared data reaches the client
+{{#unless condition}}
+  Content when false
+{{/unless}}
+```
+
+**Truthy/Falsy:**
+- Falsy: `nil`, `null`, `false`, `""`, `0`, `"false"`
+- Truthy: All other values
+
+### Loops
+
+```handlebars
+{{#each items}}
+  {{@index}}      <!-- 0-based index -->
+  {{@first}}      <!-- true if first item -->
+  {{@last}}       <!-- true if last item -->
+  {{this}}        <!-- current item (if primitive) -->
+  {{name}}        <!-- item.name (if object) -->
+{{/each}}
+```
+
+### Partials
 
-### 4. RSFC Security Model
+```handlebars
+{{> header}}              <!-- Include templates/header.rue -->
+{{> components/nav}}      <!-- Include templates/components/nav.rue -->
+```
 
-**Key Principle: The security boundary is at the server-to-client handoff, not within server-side rendering.**
+### Layouts
 
 ```xml
-<data>
-{
-  "message": "{{greeting}}",    <!-- ✅ Exposed to client -->
-  "user": {
-    "name": "{{user.name}}"     <!-- ✅ Exposed to client -->
-  }
-  <!-- ❌ user.secret_key not declared, won't reach client -->
-}
-</data>
+<!-- templates/pages/home.rue -->
+<schema lang="js-zod" window="data" layout="layouts/main">
+const schema = z.object({ page: z.string() });
+</schema>
 
 <template>
-  <h1>{{greeting}}</h1>          <!-- ✅ Full server context access -->
-  <p>{{user.name}}</p>           <!-- ✅ Can access user object methods -->
-  <p>{{user.secret_key}}</p>     <!-- ✅ Server-side only, not in <data> -->
+  <h1>Home Page Content</h1>
 </template>
 ```
 
-**Template Section (`<template>`):**
-- ✅ **Full server context access** - like ERB, HAML, or any server-side template
-- ✅ **Can call object methods** - `{{user.full_name}}`, `{{products.count}}`, etc.
-- ✅ **Rich server-side logic** - access to full business objects and their capabilities
-- ✅ **Private by default** - nothing in templates reaches the client unless explicitly declared
+```xml
+<!-- templates/layouts/main.rue -->
+<schema lang="js-zod" window="layoutData">
+const schema = z.object({ siteName: z.string() });
+</schema>
 
-**Data Section (`<data>`):**
-- ✅ **Explicit client allowlist** - only declared variables reach the browser
-- ✅ **JSON serialization boundary** - like designing a REST API endpoint
-- ✅ **Type safety foundation** - can validate against schemas
-- ❌ **Cannot expose secrets** - `user.secret_key` won't reach client unless declared
+<template>
+<!DOCTYPE html>
+<html>
+<head>
+  <title>{{server.siteName}}</title>
+</head>
+<body>
+  <header>{{> components/header}}</header>
+  <main>
+    <!-- Page content injected here -->
+  </main>
+  <footer>{{> components/footer}}</footer>
+</body>
+</html>
+</template>
+```
 
-This design gives you the flexibility of full server-side templating while maintaining explicit control over what data reaches the client.
+## Schema Tooling
 
-**Generated output:**
-```html
-<!-- Server-rendered HTML -->
-<div id="app">
-  <nav>...</nav>
-  <main><h1>User Dashboard</h1><p>Welcome back, Alice!</p></main>
-</div>
+Rhales provides rake tasks for schema management:
 
-<!-- Automatic client hydration -->
-<script id="app-state-data" type="application/json">
-{"user":{"id":123,"name":"Alice","email":"alice@example.com","preferences":{...}},"products":[...],"cart":{...},"api":{...},"features":{...}}
-</script>
-<script nonce="abc123">
-window.appState = JSON.parse(document.getElementById('app-state-data').textContent);
-</script>
+```bash
+# Generate JSON schemas from .rue templates
+rake rhales:schema:generate TEMPLATES_DIR=./templates
 
-<!-- Your Vue/React/Svelte app mounts here with full state -->
-<script nonce="abc123" type="module" src="/assets/app.js"></script>
+# Validate existing JSON schemas
+rake rhales:schema:validate
+
+# Show schema statistics
+rake rhales:schema:stats TEMPLATES_DIR=./templates
 ```
 
-### 5. Framework Integration
+**Example output:**
 
-#### Rails
+```
+Schema Statistics
+============================================================
+Templates directory: templates
+
+Total .rue files: 25
+Files with <schema>: 25
+Files without <schema>: 0
+
+By language:
+  js-zod: 25
+```
+
+## Framework Integration
+
+### Rails
 
 ```ruby
 # config/initializers/rhales.rb
@@ -329,91 +565,79 @@ end
 
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  def render_rhales(template_name, data = {})
-    view = Rhales::View.new(request, session, current_user, I18n.locale)
-    view.render(template_name, data)
+  def render_rhales(template_name, client: {}, server: {})
+    view = Rhales::View.new(request, client: client, server: server)
+    view.render(template_name)
   end
 end
 
 # In your controller
 def dashboard
-  @dashboard_html = render_rhales('dashboard',
-    page_title: 'User Dashboard',
-    user: current_user,
-    recent_products: Product.recent.limit(5),
-    cart: current_user.cart,
-    enabled_features: Feature.enabled_for(current_user)
+  html = render_rhales('dashboard',
+    client: { user: current_user.name, items: @items },
+    server: { page_title: 'Dashboard' }
   )
+  render html: html.html_safe
 end
 ```
 
-#### Sinatra
+### Roda
 
 ```ruby
 # app.rb
-require 'sinatra'
+require 'roda'
 require 'rhales'
 
-Rhales.configure do |config|
-  config.template_paths = ['templates']
-  config.default_locale = 'en'
-end
+class App < Roda
+  plugin :render
 
-helpers do
-  def render_rhales(template_name, data = {})
-    view = Rhales::View.new(request, session, current_user, 'en')
-    view.render(template_name, data)
+  Rhales.configure do |config|
+    config.template_paths = ['templates']
+    config.default_locale = 'en'
   end
-end
 
-get '/dashboard' do
-  @dashboard_html = render_rhales('dashboard',
-    page_title: 'Dashboard',
-    user: current_user,
-    recent_products: Product.recent,
-    cart: session[:cart] || {},
-    enabled_features: FEATURES
-  )
-  erb :dashboard
+  route do |r|
+    r.on 'dashboard' do
+      view = Rhales::View.new(
+        request,
+        client: { user: current_user.name },
+        server: { page_title: 'Dashboard' }
+      )
+      view.render('dashboard')
+    end
+  end
 end
 ```
 
-#### Padrino
+### Sinatra
 
 ```ruby
-# config/apps.rb
-Padrino.configure_apps do
-  Rhales.configure do |config|
-    config.template_paths = ['app/templates']
-    config.default_locale = 'en'
-  end
+require 'sinatra'
+require 'rhales'
+
+Rhales.configure do |config|
+  config.template_paths = ['templates']
+  config.default_locale = 'en'
 end
 
-# app/helpers/application_helper.rb
-module ApplicationHelper
-  def render_rhales(template_name, data = {})
-    view = Rhales::View.new(request, session, current_user, locale)
-    view.render(template_name, data)
+helpers do
+  def render_rhales(template_name, client: {}, server: {})
+    view = Rhales::View.new(request, client: client, server: server)
+    view.render(template_name)
   end
 end
 
-# app/controllers/application_controller.rb
-get :dashboard do
-  @dashboard_html = render_rhales('dashboard',
-    page_title: 'Dashboard',
-    user: current_user,
-    recent_products: Product.recent,
-    cart: current_user&.cart,
-    enabled_features: settings.features
+get '/dashboard' do
+  render_rhales('dashboard',
+    client: { user: 'Alice' },
+    server: { page_title: 'Dashboard' }
   )
-  render :dashboard
 end
 ```
 
-#### Grape
+### Grape
 
 ```ruby
-# config.ru or initializer
 require 'grape'
 require 'rhales'
 
@@ -422,444 +646,337 @@ Rhales.configure do |config|
   config.default_locale = 'en'
 end
 
-# api.rb
 class MyAPI < Grape::API
   helpers do
-    def render_rhales(template_name, data = {})
-      # Create mock request/session for Grape
+    def render_rhales(template_name, client: {}, server: {})
       mock_request = OpenStruct.new(env: env)
-      mock_session = {}
-
-      view = Rhales::View.new(mock_request, mock_session, current_user, 'en')
-      view.render(template_name, data)
+      view = Rhales::View.new(mock_request, client: client, server: server)
+      view.render(template_name)
     end
   end
 
   get '/dashboard' do
     content_type 'text/html'
     render_rhales('dashboard',
-      page_title: 'API Dashboard',
-      user: current_user,
-      recent_products: [],
-      cart: {},
-      enabled_features: { api_v2: true }
+      client: { user: 'Alice' },
+      server: { page_title: 'Dashboard' }
     )
   end
 end
 ```
 
-#### Roda
-
-```ruby
-# app.rb
-require 'roda'
-require 'rhales'
-
-class App < Roda
-  plugin :render
+## Content Security Policy (CSP)
 
-  Rhales.configure do |config|
-    config.template_paths = ['templates']
-    config.default_locale = 'en'
-  end
+Rhales provides **security by default** with automatic CSP support.
 
-  def render_rhales(template_name, data = {})
-    view = Rhales::View.new(request, session, current_user, 'en')
-    view.render(template_name, data)
-  end
+### Default CSP Configuration
 
-  route do |r|
-    r.on 'dashboard' do
-      @dashboard_html = render_rhales('dashboard',
-        page_title: 'Dashboard',
-        user: current_user,
-        recent_products: [],
-        cart: session[:cart],
-        enabled_features: FEATURES
-      )
-      view('dashboard')
-    end
-  end
+```ruby
+Rhales.configure do |config|
+  config.csp_enabled = true     # Default: true
+  config.auto_nonce = true      # Default: true
 end
 ```
 
-### 6. Basic Usage
+### Using Nonces in Templates
 
-```ruby
-# Create a view instance
-view = Rhales::View.new(request, session, current_user, locale)
-
-# Render a template with rich data for frontend hydration
-html = view.render('dashboard',
-  page_title: 'User Dashboard',
-  user: current_user,
-  recent_products: Product.recent.limit(5),
-  cart: current_user.cart,
-  enabled_features: Feature.enabled_for(current_user)
-)
+```handlebars
+<script nonce="{{request.nonce}}">
+  // Inline JavaScript with automatic nonce
+  console.log('Secure execution');
+</script>
 
-# Or use the convenience method
-html = Rhales.render('dashboard',
-  request: request,
-  session: session,
-  user: current_user,
-  page_title: 'User Dashboard',
-  recent_products: products,
-  cart: cart_data,
-  enabled_features: features
-)
+<style nonce="{{request.nonce}}">
+  /* Inline styles with automatic nonce */
+  .component { color: blue; }
+</style>
 ```
 
-## Authentication Adapters
-
-Rhales supports pluggable authentication adapters. Implement the `Rhales::Adapters::BaseAuth` interface:
+### Custom CSP Policies
 
 ```ruby
-class MyAuthAdapter < Rhales::Adapters::BaseAuth
-  def initialize(user)
-    @user = user
-  end
-
-  def anonymous?
-    @user.nil?
-  end
-
-  def theme_preference
-    @user&.theme || 'light'
-  end
-
-  def user_id
-    @user&.id
-  end
-
-  def role?(role)
-    @user&.roles&.include?(role)
-  end
+Rhales.configure do |config|
+  config.csp_policy = {
+    'default-src' => ["'self'"],
+    'script-src' => ["'self'", "'nonce-{{nonce}}'", 'https://cdn.example.com'],
+    'style-src' => ["'self'", "'nonce-{{nonce}}'"],
+    'img-src' => ["'self'", 'data:', 'https://images.example.com'],
+    'connect-src' => ["'self'", 'https://api.example.com']
+  }
 end
-
-# Use with Rhales
-user_adapter = MyAuthAdapter.new(current_user)
-view = Rhales::View.new(request, session, user_adapter)
 ```
 
-## Template Syntax
+### Framework CSP Header Setup
 
-Rhales uses a Handlebars-style template syntax:
+#### Rails
 
-### Variables
-- `{{variable}}` - HTML-escaped output
-- `{{{variable}}}` - Raw output (use carefully!)
+```ruby
+class ApplicationController < ActionController::Base
+  after_action :set_csp_header
 
-### Conditionals
-```erb
-{{#if condition}}
-  Content when true
-{{/if}}
+  private
 
-{{#unless condition}}
-  Content when false
-{{/unless}}
+  def set_csp_header
+    csp_header = request.env['csp_header']
+    response.headers['Content-Security-Policy'] = csp_header if csp_header
+  end
+end
 ```
 
-### Iteration
-```erb
-{{#each items}}
-  <div>{{name}} - {{@index}}</div>
-{{/each}}
-```
+#### Roda
 
-### Partials
-```erb
-{{> header}}
-{{> navigation}}
+```ruby
+class App < Roda
+  def render_with_csp(template_name, **data)
+    result = render_rhales(template_name, **data)
+    csp_header = request.env['csp_header']
+    response.headers['Content-Security-Policy'] = csp_header if csp_header
+    result
+  end
+end
 ```
 
-## Data Hydration
+## Logging
 
-The `<data>` section creates client-side JavaScript:
+Rhales provides production logging for security auditing and debugging:
 
-```erb
-<data window="myData">
-{
-  "apiUrl": "{{api_base_url}}",
-  "user": {{user}},
-  "csrfToken": "{{csrf_token}}"
-}
-</data>
+```ruby
+# Configure logger
+Rhales.logger = Rails.logger  # or Logger.new($stdout)
 ```
 
-Generates:
-```html
-<script id="rsfc-data-abc123" type="application/json">
-{"apiUrl":"https://api.example.com","user":{"id":123},"csrfToken":"token"}
-</script>
-<script nonce="nonce123">
-window.myData = JSON.parse(document.getElementById('rsfc-data-abc123').textContent);
-</script>
+**Logged Events:**
+- View rendering (template, layout, partials, timing, hydration size)
+- Security warnings (unescaped variables, schema mismatches)
+- Errors with context (line numbers, sections, full messages)
+- Performance insights (cache hits, compilation timing)
+
+```ruby
+# Example log output
+INFO  View rendered: template=dashboard layout=main partials=[header,footer] duration_ms=15.2
+WARN  Hydration schema mismatch: template=user_profile missing=[email] extra=[]
+ERROR Template not found: template=missing_partial parent=dashboard
+DEBUG Template cache hit: template=header
 ```
 
-### Window Collision Detection
+## Testing
 
-Rhales automatically detects when multiple templates try to use the same window attribute, preventing silent data overwrites:
+### Test Configuration
 
-```erb
-<!-- layouts/main.rue -->
-<data window="appData">
-{"user": "{{user.name}}", "csrf": "{{csrf_token}}"}
-</data>
+```ruby
+# test/test_helper.rb or spec/spec_helper.rb
+require 'rhales'
 
-<!-- pages/home.rue -->
-<data window="appData">  <!-- ❌ Collision detected! -->
-{"page": "home", "features": ["feature1"]}
-</data>
+Rhales.configure do |config|
+  config.default_locale = 'en'
+  config.app_environment = 'test'
+  config.cache_templates = false
+  config.template_paths = ['test/fixtures/templates']
+end
 ```
 
-This raises a helpful error:
-```
-Window attribute collision detected
+### Testing Context
 
-Attribute: 'appData'
-First defined: layouts/main.rue:1
-Conflict with: pages/home.rue:1
+```ruby
+# Minimal context for testing
+context = Rhales::Context.minimal(
+  client: { user: 'Test' },
+  server: { page_title: 'Test Page' }
+)
 
-Quick fixes:
-  1. Rename one: <data window="homeData">
-  2. Enable merging: <data window="appData" merge="deep">
+expect(context.get('user')).to eq('Test')
+expect(context.get('page_title')).to eq('Test Page')
 ```
 
-### Merge Strategies
-
-When you intentionally want to share data between templates, use explicit merge strategies:
+### Testing Templates
 
-```erb
-<!-- layouts/main.rue -->
-<data window="appData">
-{
-  "user": {"name": "{{user.name}}", "role": "{{user.role}}"},
-  "csrf": "{{csrf_token}}"
-}
-</data>
+```ruby
+# Test inline template
+template = '{{#if active}}Active{{else}}Inactive{{/if}}'
+result = Rhales.render_template(template, active: true)
+expect(result).to eq('Active')
 
-<!-- pages/home.rue with deep merge -->
-<data window="appData" merge="deep">
-{
-  "user": {"email": "{{user.email}}"},  <!-- Merged with layout user -->
-  "page": {"title": "Home", "features": {{features.to_json}}}
-}
-</data>
+# Test .rue file
+mock_request = OpenStruct.new(env: {})
+view = Rhales::View.new(mock_request, client: { message: 'Hello' })
+html = view.render('test_template')
+expect(html).to include('Hello')
 ```
 
-#### Available Merge Strategies
-
-**`merge="shallow"`** - Top-level key merge, throws error on conflicts:
-```javascript
-// Layout: {"user": {...}, "csrf": "abc"}
-// Page:   {"page": {...}, "user": {...}}  // ❌ Error: key conflict
-```
+## Migration from v0.4 to v0.5
 
-**`merge="deep"`** - Recursive merge, last value wins on conflicts:
-```javascript
-// Layout: {"user": {"name": "John", "role": "admin"}}
-// Page:   {"user": {"email": "john@example.com"}}
-// Result: {"user": {"name": "John", "role": "admin", "email": "john@example.com"}}
-```
+### Breaking Changes
 
-**`merge="strict"`** - Recursive merge, throws error on any conflict:
-```javascript
-// Layout: {"user": {"name": "John"}}
-// Page:   {"user": {"name": "Jane"}}  // ❌ Error: value conflict
-```
+1. **`<data>` sections removed** → Use `<schema>` sections
+2. **Parameters removed:**
+   - `sess` → Access via `request.session`
+   - `cust` → Access via `request.user`
+   - `props:` → Use `client:`
+   - `app_data:` → Use `server:`
+   - `locale` → Set via `request.env['rhales.locale']`
+3. **Context layer renamed:** `app` → `request`
 
-## Content Security Policy (CSP)
+### Migration Steps
 
-Rhales provides **security by default** with automatic CSP header generation and nonce management.
+#### 1. Update Ruby Code
 
-### Automatic CSP Protection
+```ruby
+# v0.4 (REMOVED)
+view = Rhales::View.new(req, session, customer, 'en',
+  props: { user: customer.name },
+  app_data: { page_title: 'Dashboard' }
+)
 
-CSP is **enabled by default** when you configure Rhales:
+# v0.5 (Current)
+view = Rhales::View.new(req,
+  client: { user: customer.name },
+  server: { page_title: 'Dashboard' }
+)
 
-```ruby
-Rhales.configure do |config|
-  # CSP is enabled by default with secure settings
-  config.csp_enabled = true     # Default: true
-  config.auto_nonce = true      # Default: true
-end
+# Set locale in request
+req.env['rhales.locale'] = 'en'
 ```
 
-### Default Security Policy
+#### 2. Convert Data to Schema
 
-Rhales ships with a secure default CSP policy:
-
-```ruby
+```xml
+<!-- v0.4 (REMOVED) -->
+<data window="data">
 {
-  'default-src' => ["'self'"],
-  'script-src' => ["'self'", "'nonce-{{nonce}}'"],
-  'style-src' => ["'self'", "'nonce-{{nonce}}'", "'unsafe-hashes'"],
-  'img-src' => ["'self'", 'data:'],
-  'font-src' => ["'self'"],
-  'connect-src' => ["'self'"],
-  'base-uri' => ["'self'"],
-  'form-action' => ["'self'"],
-  'frame-ancestors' => ["'none'"],
-  'object-src' => ["'none'"],
-  'upgrade-insecure-requests' => []
+  "user": "{{user.name}}",
+  "count": {{items.count}}
 }
-```
-
-### Automatic Nonce Generation
-
-Rhales automatically generates and manages CSP nonces:
-
-```erb
-<!-- In your .rue templates -->
-<script nonce="{{app.nonce}}">
-  // Your inline JavaScript with automatic nonce
-  console.log('Secure script execution');
-</script>
+</data>
 
-<style nonce="{{app.nonce}}">
-  /* Your inline styles with automatic nonce */
-  .component { color: blue; }
-</style>
+<!-- v0.5 (Current) -->
+<schema lang="js-zod" window="data">
+const schema = z.object({
+  user: z.string(),
+  count: z.number()
+});
+</schema>
 ```
 
-### Framework Integration
+**Key difference:** In v0.5, pass resolved values in `client:` hash instead of relying on template interpolation in JSON.
 
-CSP headers are automatically set during view rendering:
+#### 3. Update Context References
 
-```ruby
-# Your framework code (Rails, Sinatra, Roda, etc.)
-def dashboard
-  view = Rhales::View.new(request, session, current_user, 'en')
-  html = view.render('dashboard', user: current_user)
+```handlebars
+<!-- v0.4 (REMOVED) -->
+{{app.nonce}}
+{{app.csrf_token}}
 
-  # CSP header automatically added to response:
-  # Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-abc123'; ...
-end
+<!-- v0.5 (Current) -->
+{{request.nonce}}
+{{request.csrf_token}}
 ```
 
-### Custom CSP Policies
-
-Customize the CSP policy for your specific needs:
+#### 4. Update Backend Data Passing
 
 ```ruby
-Rhales.configure do |config|
-  config.csp_policy = {
-    'default-src' => ["'self'"],
-    'script-src' => ["'self'", "'nonce-{{nonce}}'", 'https://cdn.example.com'],
-    'style-src' => ["'self'", "'nonce-{{nonce}}'", 'https://fonts.googleapis.com'],
-    'img-src' => ["'self'", 'data:', 'https://images.example.com'],
-    'connect-src' => ["'self'", 'https://api.example.com'],
-    'font-src' => ["'self'", 'https://fonts.gstatic.com'],
-    # Add your own directives...
+# v0.4: Template interpolation
+view = Rhales::View.new(req, sess, cust, 'en',
+  props: { user: cust }  # Object reference, interpolated in <data>
+)
+
+# v0.5: Resolved values upfront
+view = Rhales::View.new(req,
+  client: {
+    user: cust.name,      # Resolved value
+    userId: cust.id       # Resolved value
   }
-end
+)
 ```
 
-### Per-Framework CSP Setup
+## Performance Optimization
 
-#### Rails
-```ruby
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::Base
-  after_action :set_csp_header
+### Optional: Oj for Faster JSON Processing
 
-  private
+Rhales includes optional support for [Oj](https://github.com/ohler55/oj), a high-performance JSON library that provides:
 
-  def set_csp_header
-    csp_header = request.env['csp_header']
-    response.headers['Content-Security-Policy'] = csp_header if csp_header
-  end
-end
-```
+- **10-20x faster JSON parsing** compared to stdlib
+- **5-10x faster JSON generation** compared to stdlib
+- **Lower memory usage** for large data payloads
+- **Full compatibility** with stdlib JSON API
 
-#### Sinatra
-```ruby
-helpers do
-  def render_with_csp(template_name, data = {})
-    result = render_rhales(template_name, data)
-    csp_header = request.env['csp_header']
-    headers['Content-Security-Policy'] = csp_header if csp_header
-    result
-  end
-end
-```
+#### Installation
+
+Add to your Gemfile:
 
-#### Roda
 ```ruby
-class App < Roda
-  def render_with_csp(template_name, data = {})
-    result = render_rhales(template_name, data)
-    csp_header = request.env['csp_header']
-    response.headers['Content-Security-Policy'] = csp_header if csp_header
-    result
-  end
-end
+gem 'oj', '~> 3.13'
 ```
 
-### CSP Benefits
+Then run:
 
-- **Security by default**: Protection against XSS attacks out of the box
-- **Automatic nonce management**: No manual nonce coordination needed
-- **Template integration**: Nonces automatically available in templates
-- **Framework agnostic**: Works with any Ruby web framework
-- **Customizable policies**: Adapt CSP rules to your application needs
-- **Zero configuration**: Secure defaults work immediately
+```bash
+bundle install
+```
 
-### Disabling CSP
+That's it! Rhales automatically detects Oj at load time and uses it for all JSON operations.
 
-If you need to disable CSP for specific environments:
+**Note:** The backend is selected once when Rhales loads. To ensure Oj is used, require it before Rhales:
 
 ```ruby
-Rhales.configure do |config|
-  config.csp_enabled = false  # Disable CSP header generation
-  config.auto_nonce = false   # Disable automatic nonce generation
-end
+# Gemfile or application initialization
+require 'oj'       # Load Oj first
+require 'rhales'   # Rhales will detect and use Oj
 ```
 
-## Testing
+Most bundler setups handle this automatically, but explicit ordering ensures optimal performance.
 
-Rhales includes comprehensive test helpers and is framework-agnostic:
+#### Verification
+
+Check which backend is active:
 
 ```ruby
-# test/test_helper.rb or spec/spec_helper.rb
-require 'rhales'
+Rhales::JSONSerializer.backend
+# => :oj (if available) or :json (stdlib)
+```
 
-Rhales.configure do |config|
-  config.default_locale = 'en'
-  config.app_environment = 'test'
-  config.cache_templates = false
-  config.template_paths = ['test/templates'] # or wherever your test templates are
-end
+#### Performance Impact
 
-# Test context creation
-context = Rhales::Context.minimal(props: { user: { name: 'Test' } })
-expect(context.get('user.name')).to eq('Test')
+For typical Rhales applications with hydration data:
 
-# Test template rendering
-template = '{{#if authenticated}}Welcome{{/if}}'
-result = Rhales.render_template(template, authenticated: true)
-expect(result).to eq('Welcome')
+| Operation | stdlib JSON | Oj | Improvement |
+|-----------|-------------|-----|-------------|
+| Parse 100KB payload | ~50ms | ~3ms | **16x faster** |
+| Generate 100KB payload | ~30ms | ~5ms | **6x faster** |
+| Memory usage | Baseline | -20% | **Lower** |
 
-# Test full template files
-mock_request = OpenStruct.new(env: {})
-mock_session = {}
-view = Rhales::View.new(mock_request, mock_session, nil, 'en')
-html = view.render('test_template', message: 'Hello World')
-```
+**Recommendation:** Install Oj for production applications with:
+- Large hydration payloads (>10KB)
+- High-traffic endpoints (>100 req/sec)
+- Complex nested data structures
 
-## Development
+Oj provides the most benefit for data-heavy templates and high-concurrency scenarios.
 
-After checking out the repo, run:
+## Development
 
 ```bash
+# Clone repository
+git clone https://github.com/onetimesecret/rhales.git
+cd rhales
+
+# Install dependencies
 bundle install
-bundle exec rspec
+
+# Run tests
+bundle exec rspec spec/rhales/
+
+# Run with documentation format
+bundle exec rspec spec/rhales/ --format documentation
+
+# Build gem
+gem build rhales.gemspec
+
+# Install locally
+gem install ./rhales-0.5.0.gem
 ```
 
 ## Contributing
 
-1. Fork it
+1. Fork it (https://github.com/onetimesecret/rhales/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
@@ -871,11 +988,11 @@ The gem is available as open source under the [MIT License](https://opensource.o
 
 ## AI Development Assistance
 
-Rhales was developed with assistance from AI tools. The following tools provided significant help with architecture design, code generation, and documentation:
+Rhales was developed with assistance from AI tools:
 
-- **Claude Sonnet 4** - Architecture design, code generation, and documentation
-- **Claude Desktop & Claude Code** - Interactive development sessions and debugging
-- **GitHub Copilot** - Code completion and refactoring assistance
+- **Claude Sonnet 4.5** - Architecture design, code generation, documentation
+- **Claude Desktop & Claude Code** - Interactive development and debugging
+- **GitHub Copilot** - Code completion and refactoring
 - **Qodo Merge Pro** - Code review and quality improvements
 
-I remain responsible for all design decisions and the final code. I believe in being transparent about development tools, especially as AI becomes more integrated into our workflows.
+I remain responsible for all design decisions and the final code. Being transparent about development tools as AI becomes more integrated into our workflows.