opacacms 0.1.21 → 0.2.0

package/README.md

@@ -13,16 +13,22 @@ OpacaCMS is a runtime-agnostic powerhouse that runs anywhere: **Node.js, Bun, Cl
 - [⚙️ Configuration](#-configuration)
 - [📦 Collections](#-collections)
 - [🧪 Field Types](#-field-types)
+- [✅ Validation](#-validation)
 - [🌍 Globals](#-globals)
 - [🔐 Access Control](#-access-control)
 - [⚓ Hooks](#-hooks)
+- [🔔 Webhooks](#-webhooks)
+- [📌 Versioning](#-versioning)
+- [🧮 Virtual Fields](#-virtual-fields)
 - [👤 Authentication](#-authentication)
+- [📝 Logging](#-logging)
 - [🗄 Database Adapters](#-database-adapters)
 - [🔄 Migrations](#-migrations)
 - [☁️ Storage](#-storage)
-- [🌐 i18n](#-internationalization-i18n)
-- [🎨 Custom Components](#-custom-admin-components)
+- [🌐 Internationalization (i18n)](#-internationalization-i18n)
+- [🎨 Custom Admin Components](#-custom-admin-components)
 - [🔌 API & SDK](#-the-client-sdk)
+- [🏠 Full-Stack Examples](#-full-stack-examples)
 
 ---
 
@@ -50,7 +56,12 @@ my-cms/
 ├── opacacms.config.ts   ← The heart of your CMS (schema + DB + auth)
 ├── migrations/          ← Your DB history
 ├── collections/         ← Where your data models live
+│   ├── posts.ts
+│   ├── products.ts
+│   └── ...
 ├── globals/             ← Singleton documents (settings, etc.)
+│   ├── site-settings.ts
+│   └── ...
 └── src/                 ← Your app logic
 ```
 
@@ -61,18 +72,49 @@ my-cms/
 Your `opacacms.config.ts` is the single source of truth. Export its configuration as the **default export**.
 
 ```typescript
-import { defineConfig } from 'opacacms';
+import { defineConfig } from 'opacacms/config';
 import { createSQLiteAdapter } from 'opacacms/db/sqlite';
 import { posts } from './collections/posts';
+import { siteSettings } from './globals/site-settings';
 
 export default defineConfig({
   appName: 'My Shiny Blog 💫',
   serverURL: 'http://localhost:3000',
+  secret: process.env.OPACA_SECRET,
   db: createSQLiteAdapter('local.db'),
-  collections: [posts], // No need to call .build() anymore! ✌️
+  collections: [posts],
+  globals: [siteSettings],
+  i18n: {
+    locales: ['en', 'pt-BR', 'tr'],
+    defaultLocale: 'en',
+  },
+  auth: {
+    strategies: { emailPassword: true },
+    features: {
+      apiKeys: { enabled: true },
+    },
+  },
+  logger: { level: 'debug' },
 });
 ```
 
+### Configuration Options
+
+| Option           | Type                             | Description                                                       |
+| ---------------- | -------------------------------- | ----------------------------------------------------------------- |
+| `appName`        | `string`                         | Display name shown in the Admin UI sidebar                        |
+| `serverURL`      | `string`                         | The base URL of your server (used for CORS, auth callbacks, etc.) |
+| `secret`         | `string`                         | Secret used for signing tokens and encryption                     |
+| `db`             | `DatabaseAdapter`                | Database adapter (`createSQLiteAdapter`, `createD1Adapter`, etc.) |
+| `collections`    | `Collection[]`                   | Array of collection definitions                                   |
+| `globals`        | `Global[]`                       | Array of global definitions                                       |
+| `i18n`           | `{ locales, defaultLocale }`     | Internationalization config                                       |
+| `auth`           | `AuthConfig`                     | Authentication strategies and features                            |
+| `logger`         | `{ level, disabled? }`           | Logger configuration                                              |
+| `trustedOrigins` | `string[]`                       | Origins allowed for CORS requests                                 |
+| `storages`       | `Record<string, StorageAdapter>` | Named storage adapters for file uploads                           |
+| `api`            | `{ maxLimit? }`                  | API-level settings (e.g., max items per page)                     |
+
 ---
 
 ## 📦 Collections
@@ -87,20 +129,48 @@ export const posts = Collection.create('posts')
   .label('Blog Posts')
   .icon('FileText')
   .fields([
-    Field.text('title').required(),
+    Field.text('title').required().label('Post Title'),
     Field.slug('slug').from('title').unique(),
     Field.richText('content').localized(),
     Field.relationship('author').to('_users').single(),
-  ]);
+    Field.select('status')
+      .options([
+        { label: 'Draft', value: 'draft' },
+        { label: 'Published', value: 'published' },
+      ])
+      .defaultValue('draft'),
+    Field.checkbox('featured').label('Featured Post'),
+  ])
+  .access({
+    read: () => true,
+    create: ({ user }) => !!user,
+    update: ({ user }) => user?.role === 'admin',
+    delete: ({ user }) => user?.role === 'admin',
+  })
+  .hooks({
+    beforeCreate: async (data) => {
+      // Mutate data before insertion
+      return { ...data, publishedAt: new Date().toISOString() };
+    },
+    afterCreate: async (doc) => {
+      console.log('New post created:', doc.id);
+    },
+  });
 ```
 
-### 🛠 Builder Methods
+### Collection Builder Methods
 
-- `.label(name)`: Title in Sidebar.
-- `.icon(name)`: Lucide icon name.
-- `.fields([...])`: Your data structure.
-- `.access(rules)`: Who can do what.
-- `.hooks(fns)`: Lifecycle side-effects.
+| Method               | Description                                                      |
+| -------------------- | ---------------------------------------------------------------- |
+| `.label(name)`       | Sets the display name used in the Admin UI sidebar               |
+| `.icon(name)`        | [Lucide](https://lucide.dev) icon name for the sidebar           |
+| `.fields([...])`     | Defines the data structure for this collection                   |
+| `.access(rules)`     | Collection-level access control                                  |
+| `.hooks(fns)`        | Lifecycle hooks (`beforeCreate`, `afterUpdate`, etc.)            |
+| `.webhooks([...])`   | External webhook notifications                                   |
+| `.admin({...})`      | Advanced Admin UI configuration (`hidden`, `disableAdmin`, etc.) |
+| `.versions(true)`    | Enable document versioning with history                          |
+| `.timestamps({...})` | Customize timestamp field names                                  |
 
 ---
 
@@ -108,23 +178,402 @@ export const posts = Collection.create('posts')
 
 We've got everything you need to build powerful schemas:
 
-- `Field.text()`: Simple strings.
-- `Field.richText()`: Block-based editor (Notion style!). 📝
-- `Field.relationship()`: Connect your data.
-- `Field.file()`: Simple uploads. ☁️
-- `Field.blocks()`: Dynamic page builders. 🧱
-- `Field.group()`: Nested objects.
-- `Field.select()` / `Field.checkbox()`: Pickers.
+| Field                  | Usage                                       | Description                                   |
+| ---------------------- | ------------------------------------------- | --------------------------------------------- |
+| `Field.text()`         | `Field.text('title')`                       | Simple string input                           |
+| `Field.number()`       | `Field.number('price')`                     | Numeric input                                 |
+| `Field.richText()`     | `Field.richText('content')`                 | Block-based Lexical editor (Notion style!) 📝 |
+| `Field.relationship()` | `Field.relationship('author').to('_users')` | Links to another collection                   |
+| `Field.file()`         | `Field.file('image')`                       | File/image upload ☁️                          |
+| `Field.blocks()`       | `Field.blocks('layout').blocks([...])`      | Dynamic page builder 🧱                       |
+| `Field.group()`        | `Field.group('meta').fields([...])`         | Nested object group                           |
+| `Field.array()`        | `Field.array('tags').fields([...])`         | Repeatable field group                        |
+| `Field.select()`       | `Field.select('status').options([...])`     | Dropdown picker                               |
+| `Field.checkbox()`     | `Field.checkbox('active')`                  | Boolean toggle                                |
+| `Field.slug()`         | `Field.slug('slug').from('title')`          | Auto-generated URL slug                       |
+| `Field.date()`         | `Field.date('publishedAt')`                 | Date/time picker                              |
+| `Field.virtual()`      | `Field.virtual('fullName').resolve(...)`    | Computed field (not stored)                   |
+| `Field.tabs()`         | `Field.tabs('layout').tabs([...])`          | UI-only grouping for the admin                |
+
+### Common Field Methods
+
+Every field type inherits these chainable methods from the base builder:
+
+```typescript
+Field.text('email')
+  .label('Email Address') // Admin UI label
+  .placeholder('you@example.com') // Input placeholder
+  .required() // Mark as required
+  .unique() // Unique constraint in the DB
+  .localized() // Enable per-locale values (i18n)
+  .defaultValue('hello@world.com') // Default value
+  .validate(z.string().email()) // Custom validation (function or Zod)
+  .access({ readOnly: true }) // Field-level access control
+  .description('Primary email') // Help text below the field
+  .hidden() // Hide from Admin UI
+  .readOnly() // Read-only in Admin UI
+  .admin({ components: { Field: 'my-custom-field' } }); // Custom component
+```
 
 ---
 
-## 🎨 Custom Admin Components
+## ✅ Validation
+
+OpacaCMS supports **granular field validation** via the `.validate()` method. You can pass either a **custom function** or a **Zod schema** — they're fully interchangeable.
+
+### Custom Function Validation
+
+Return `true` to pass, or a `string` error message to fail:
+
+```typescript
+Field.text('username').validate((value) => {
+  if (value === 'admin') return "Username 'admin' is reserved";
+  return true;
+});
+```
+
+### Zod Schema Validation
+
+Pass any `z.ZodTypeAny` schema directly. Errors are automatically mapped:
+
+```typescript
+import { z } from 'zod';
+
+Field.text('cpf').validate(
+  z.string().regex(/^\d{3}\.\d{3}\.\d{3}-\d{2}$/, 'Invalid CPF format'),
+);
+
+Field.text('password').validate(
+  z
+    .string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Must contain at least one uppercase letter'),
+);
+
+Field.text('email')
+  .required()
+  .validate(z.string().email('Invalid email address'));
+```
+
+> **💡 Tip:** Zod validation integrates seamlessly with `.required()`. The built-in requirement check runs first, then your Zod schema validates the value shape.
+
+---
+
+## 🌍 Globals
+
+Globals are **singleton documents** — perfect for site settings, navigation, footers, and other one-of-a-kind configs.
+
+```typescript
+import { Global, Field } from 'opacacms/schema';
+
+export const siteSettings = Global.create('site-settings')
+  .label('Site Settings')
+  .icon('Settings')
+  .fields([
+    Field.text('siteName').required(),
+    Field.text('tagline').localized(),
+    Field.file('logo'),
+    Field.group('social').fields([Field.text('twitter'), Field.text('github')]),
+  ]);
+```
+
+API: `GET /api/globals/site-settings` and `PUT /api/globals/site-settings`
+
+---
+
+## 🔐 Access Control
+
+Secure your data with simple functions at both **collection** and **field** levels. 🛡️
+
+### Collection-Level Access
+
+```typescript
+.access({
+  read: ({ user }) => !!user,                    // Logged in? You're good.
+  create: ({ user }) => user?.role === 'admin',   // Only admins please!
+  update: ({ data, user }) => data.ownerId === user.id, // Only your own stuff.
+  delete: ({ user }) => user?.role === 'admin',
+  requireApiKey: true,                            // Require API key for programmatic access
+})
+```
+
+### Field-Level Access
+
+Control visibility and editability per-field:
+
+```typescript
+Field.text('internalNotes').access({
+  hidden: ({ user }) => user?.role !== 'admin', // Only admins see this
+  readOnly: ({ operation }) => operation === 'update', // Editable only on create
+  disabled: false,
+});
+```
+
+### Role-Based Access Control (RBAC)
+
+Combine `auth` with the `access` property to define granular permissions:
+
+```typescript
+access: {
+  roles: {
+    admin: {
+      posts: ['read', 'create', 'update', 'delete'],
+      users: ['read', 'update']
+    },
+    editor: {
+      posts: ['read', 'update']
+    }
+  }
+}
+```
+
+---
+
+## ⚓ Hooks
+
+Hooks let you run side-effects at key points in the document lifecycle. They receive the document data and can mutate it before persistence.
+
+```typescript
+.hooks({
+  beforeCreate: async (data) => {
+    // Transform or enrich data before saving
+    data.slug = data.title.toLowerCase().replace(/\s+/g, '-');
+    return data;
+  },
+  afterCreate: async (doc) => {
+    // Side-effects after the document is saved
+    await sendWelcomeEmail(doc.email);
+  },
+  beforeUpdate: async (data) => {
+    data.updatedBy = 'system';
+    return data;
+  },
+  afterUpdate: async (doc) => {
+    await invalidateCache(`/posts/${doc.slug}`);
+  },
+  beforeDelete: async (id) => {
+    await archiveDocument(id);
+  },
+  afterDelete: async (id) => {
+    console.log(`Document ${id} deleted`);
+  },
+})
+```
+
+---
+
+## 🔔 Webhooks
+
+Send HTTP notifications to external services when documents change. Webhooks run in the background using `waitUntil` on supported runtimes (Cloudflare Workers, Vercel Edge).
+
+```typescript
+Collection.create('orders').webhooks([
+  {
+    url: 'https://hooks.slack.com/services/xxx',
+    events: ['afterCreate', 'afterUpdate'],
+    headers: { Authorization: 'Bearer my-token' },
+  },
+  {
+    url: 'https://api.example.com/webhooks/orders',
+    events: ['afterDelete'],
+  },
+]);
+```
+
+Supported events: `afterCreate`, `afterUpdate`, `afterDelete`.
+
+---
+
+## 📌 Versioning
+
+Enable document versioning to keep a full history of changes. Each save creates a snapshot that can be restored later.
+
+```typescript
+Collection.create('posts')
+  .versions(true) // That's it!
+  .fields([...])
+```
+
+### Version API
+
+| Endpoint                                 | Method | Description                      |
+| ---------------------------------------- | ------ | -------------------------------- |
+| `/api/posts/versions?parentId=xxx`       | `GET`  | List all versions for a document |
+| `/api/posts/versions/:versionId/restore` | `POST` | Restore a specific version       |
+
+The admin UI provides a visual "Versions" panel where editors can browse and restore past versions.
+
+---
+
+## 🧮 Virtual Fields
+
+Virtual fields are **computed at read-time** and never stored in the database. Perfect for derived values, aggregated data, or API mashups.
+
+```typescript
+Field.virtual('fullName').resolve(async ({ data, user, req }) => {
+  return `${data.firstName} ${data.lastName}`;
+});
+```
+
+Virtual fields receive the full document `data`, the current `user`, `session`, `apiKey`, and the Hono `req` context.
+
+---
+
+## 👤 Authentication
+
+OpacaCMS features a robust, built-in authentication system powered by [Better Auth](https://better-auth.com). It's secure by default and fully customizable.
+
+### Basic Setup
+
+```typescript
+auth: {
+  strategies: {
+    emailPassword: true, // Enabled by default
+    magicLink: {
+      enabled: true,
+      sendEmail: async ({ email, url }) => {
+        await sendMyMagicLink(email, url);
+      }
+    }
+  },
+  features: {
+    apiKeys: { enabled: true }, // Programmable access
+    mfa: { enabled: true, issuer: 'My App' } // Two-Factor Auth
+  }
+}
+```
+
+### API Key Authentication
+
+When `apiKeys` is enabled, you can create API keys with fine-grained collection permissions:
+
+```typescript
+// API keys can have per-collection permissions
+{
+  permissions: {
+    posts: ['read', 'create'],
+    users: ['read']
+  }
+}
+```
+
+Pass the key in your requests:
+
+```bash
+curl -H "Authorization: Bearer opaca_key_xxx" https://api.mycms.com/api/posts
+```
+
+---
+
+## 📝 Logging
+
+OpacaCMS includes a configurable global logger that standardizes output across the core system and authentication events.
+
+```typescript
+logger: {
+  level: 'debug', // 'debug' | 'info' | 'warn' | 'error'
+  disabled: false,
+  disableColors: false
+}
+```
+
+Access the logger in custom middleware:
+
+```typescript
+const logger = c.get('logger');
+logger.info('Custom route hit');
+```
+
+---
+
+## 🗄 Database Adapters
 
-This is where OpacaCMS shines. You can replace any field UI with your own **React** or **Vue** components. 💅
+OpacaCMS provides first-class adapters for multiple database engines. All adapters implement the same interface, so switching is as simple as changing one line.
 
-### 1️⃣ React components
+| Adapter       | Import               | Usage                             |
+| ------------- | -------------------- | --------------------------------- |
+| SQLite (Bun)  | `opacacms/db/sqlite` | `createSQLiteAdapter('local.db')` |
+| Cloudflare D1 | `opacacms/db/d1`     | `createD1Adapter(env.DB)`         |
 
-Just use our `defineReactField` helper!
+---
+
+## 🔄 Migrations
+
+Migrations keep your database schema in sync with your collections. They're auto-generated from your field definitions.
+
+```bash
+# Create a migration
+bunx opacacms migrate:create initial-schema
+
+# Apply migrations
+bunx opacacms migrate
+```
+
+When using `createBunHandler` or `createCloudflareWorkersHandler`, migrations run automatically on startup via `db.migrate(config.collections)`.
+
+---
+
+## ☁️ Storage
+
+OpacaCMS supports pluggable storage adapters for file uploads. You can define multiple named storages and reference them per-field.
+
+```typescript
+import { createR2Storage } from 'opacacms/storage';
+
+storages: {
+  default: createR2Storage({
+    bucketBinding: env.BUCKET,
+    publicUrl: 'https://cdn.example.com',
+  }),
+  secure: createR2Storage({
+    bucketBinding: env.SECURE_BUCKET,
+    publicUrl: 'https://secure.example.com',
+  }),
+}
+```
+
+---
+
+## 🌐 Internationalization (i18n)
+
+Enable field-level localization with a simple config and the `.localized()` method on any field.
+
+```typescript
+// Config
+i18n: {
+  locales: ['en', 'pt-BR', 'tr'],
+  defaultLocale: 'en',
+}
+
+// Field
+Field.text('title').localized()
+Field.richText('content').localized()
+```
+
+### Locale Selection
+
+Pass the desired locale in your API requests:
+
+```bash
+# Via header
+curl -H "x-opaca-locale: pt-BR" https://api.mycms.com/api/posts
+
+# Via query parameter
+curl https://api.mycms.com/api/posts?locale=pt-BR
+
+# Get all locales
+curl https://api.mycms.com/api/posts?locale=all
+```
+
+When writing data, send the locale header and the value will be stored under that locale key automatically. The system handles merging — existing locale values are preserved.
+
+---
+
+## 🎨 Custom Admin Components
+
+This is where OpacaCMS shines. You can replace any field UI with your own **React** or **Vue** components via Web Components. 💅
+
+### 1️⃣ React Components
 
 ```tsx
 // MyColorPicker.tsx
@@ -141,9 +590,7 @@ const ColorPicker = ({ value, onChange }) => (
 defineReactField('my-color-picker', ColorPicker);
 ```
 
-### 2️⃣ Vue components
-
-Same thing, just pass your `createApp` function!
+### 2️⃣ Vue Components
 
 ```tsx
 // MyVuePicker.vue
@@ -166,62 +613,357 @@ Field.text('color').admin({
 
 ---
 
-## 🔐 Access Control
+## 🛠 Advanced Admin Configuration
+
+Collections and Fields can be further customized for the Admin UI using the `.admin()` method.
 
-Secure your data with simple functions. 🛡️
+### Collection Admin Options
+
+| Option           | Type       | Description                                                                     |
+| ---------------- | ---------- | ------------------------------------------------------------------------------- |
+| `hidden`         | `boolean`  | If true, hides the collection from the sidebar but keeps it accessible via URL. |
+| `disableAdmin`   | `boolean`  | If true, completely removes the collection from the Admin UI.                   |
+| `useAsTitle`     | `string`   | The field name to use as the title in breadcrumbs and lists.                    |
+| `defaultColumns` | `string[]` | The default fields to show in the collection list table.                        |
+
+Example:
 
 ```typescript
-.access({
-  read: ({ user }) => !!user, // Logged in? You're good.
-  create: ({ user }) => user?.role === 'admin', // Only admins please!
-  update: ({ data, user }) => data.ownerId === user.id, // Only your own stuff.
-})
+export const InternalData = Collection.create('internal_data')
+  .admin({
+    hidden: true, // Only accessible via direct link
+  })
+  .fields([...]);
 ```
 
 ---
 
-## 👤 Authentication
+## 🔌 The Client SDK
+
+Query your CMS like a pro with full type-safety. ⚡️
 
-OpacaCMS uses [better-auth](https://better-auth.com) under the hood. It handles the heavy lifting so you don't have to. 🔒
+```typescript
+import { createClient } from 'opacacms/client';
 
----
+const cms = createClient({ baseURL: 'https://api.mycms.com' });
 
-## 🔄 Migrations
+const posts = await cms.collections.posts.find({
+  limit: 10,
+  sort: 'createdAt:desc',
+  // Deep Populate! 🚀
+  populate: {
+    author: true,
+    comments: {
+      populate: {
+        user: true,
+      },
+    },
+  },
+});
+```
 
-Go from development to production safely.
+### Filtering & Querying
 
 ```bash
-# Create a migration
-bunx opacacms migrate:create initial-schema
+# Basic filter
+GET /api/posts?status=published
 
-# Apply it
-bunx opacacms migrate
+# Operator-based filtering
+GET /api/posts?price[gt]=10&price[lt]=100
+
+# Pagination
+GET /api/posts?page=2&limit=20
+
+# Sorting
+GET /api/posts?sort=createdAt:desc
+
+# Deep populate via REST
+GET /api/posts?populate=author,comments.user
 ```
 
 ---
 
-## 🔌 The Client SDK
+## 🏠 Full-Stack Examples
 
-Query your CMS like a pro with full type-safety. ⚡️
+### Next.js (App Router)
+
+OpacaCMS integrates with Next.js via the `createNextHandler` which wraps the internal Hono router using `hono/vercel`.
+
+#### 1. API Route Handler
 
 ```typescript
-import { createClient } from 'opacacms/client';
+// app/api/[[...route]]/route.ts
+import { createNextHandler } from 'opacacms/runtimes/next';
+import config from '@/opacacms.config';
 
-const cms = createClient({ baseURL: 'https://api.mycms.com' });
+export const { GET, POST, PUT, DELETE, PATCH, OPTIONS } =
+  createNextHandler(config);
+```
 
-const posts = await cms.collections.posts.find({
-  limit: 10,
-  sort: 'createdAt:desc',
+#### 2. Admin UI Page
+
+The admin interface is delivered as a **Web Component** — just import it in a client page and point it at your server:
+
+```tsx
+// app/admin/[[...segments]]/page.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import 'opacacms/admin/ui/styles/index.scss'; // Admin styles
+
+// Declare the web component for TypeScript
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'opaca-admin': {
+        'server-url'?: string;
+        config?: string;
+      };
+    }
+  }
+}
+
+export default function AdminPage() {
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    import('opacacms/admin/webcomponent')
+      .then(() => setLoaded(true))
+      .catch((err) => console.error('Failed to load Opaca Admin', err));
+  }, []);
+
+  if (!loaded) return <div>Loading Admin Interface...</div>;
+
+  return <opaca-admin server-url="http://localhost:3000" />;
+}
+```
+
+That's it! Your full-stack Next.js app now has a complete CMS admin panel at `/admin` and a REST API at `/api`.
+
+---
+
+### Vue
+
+For Vue, import the pre-built admin bundle and use the web component directly:
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import 'opacacms/admin.css'; // Or the bundled CSS path
+
+const loaded = ref(false);
+
+onMounted(async () => {
+  try {
+    await import('opacacms/admin/webcomponent');
+    loaded.value = true;
+  } catch (err) {
+    console.error('Failed to load Opaca Admin', err);
+  }
 });
+</script>
+
+<template>
+  <div v-if="!loaded">Loading Admin Interface...</div>
+  <opaca-admin v-else server-url="http://localhost:3000" />
+</template>
+```
+
+Your API server can run as a separate Bun or Node.js process using the standalone handler.
+
+---
+
+### Cloudflare Workers
+
+OpacaCMS runs natively on Cloudflare Workers with D1 (database) and R2 (storage):
+
+```typescript
+// src/index.ts
+import { createCloudflareWorkersHandler } from 'opacacms/runtimes/cloudflare-workers';
+import config from './opacacms.config';
+
+const app = createCloudflareWorkersHandler(config);
+
+// Serve the admin SPA
+app.get('/admin*', (c) => {
+  return c.html(`
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <link rel="stylesheet" href="/admin.css">
+    </head>
+    <body>
+      <opaca-admin server-url="${new URL(c.req.url).origin}"></opaca-admin>
+      <script type="module" src="/webcomponent.js"></script>
+    </body>
+    </html>
+  `);
+});
+
+export default app;
+```
+
+```typescript
+// opacacms.config.ts
+import { defineConfig } from 'opacacms/config';
+import { createD1Adapter } from 'opacacms/db/d1';
+import { createR2Storage } from 'opacacms/storage';
+
+const getConfig = (env: Env, request: Request) =>
+  defineConfig({
+    appName: 'My Edge CMS',
+    serverURL: new URL(request.url).origin,
+    secret: env.OPACA_SECRET,
+    db: createD1Adapter(env.DB),
+    storages: {
+      default: createR2Storage({
+        bucketBinding: env.BUCKET,
+        publicUrl: new URL(request.url).origin,
+      }),
+    },
+    collections: [posts, products],
+    i18n: {
+      locales: ['en', 'pt-BR'],
+      defaultLocale: 'en',
+    },
+  });
+
+export default getConfig;
 ```
 
 ---
 
+### Bun (Standalone Server)
+
+```typescript
+import { createBunHandler } from 'opacacms/runtimes/bun';
+import config from './opacacms.config';
+
+const { app, init } = createBunHandler(config, { port: 3000 });
+
+await init(); // Connects DB, runs migrations, starts server
+// 🚀 Listening on http://localhost:3000
+```
+
+---
+
+## Runtime Handlers
+
+| Runtime                  | Import                                 | Handler                                  |
+| ------------------------ | -------------------------------------- | ---------------------------------------- |
+| **Next.js** (App Router) | `opacacms/runtimes/next`               | `createNextHandler(config)`              |
+| **Bun** (Standalone)     | `opacacms/runtimes/bun`                | `createBunHandler(config, opts)`         |
+| **Cloudflare Workers**   | `opacacms/runtimes/cloudflare-workers` | `createCloudflareWorkersHandler(config)` |
+| **Node.js**              | `opacacms/runtimes/node`               | `createNodeHandler(config)`              |
+
+---
+
 ## 🌟 Why OpacaCMS?
 
 - **Blazing Fast**: Built on Hono & Bun. 🚀
 - **Truly Decoupled**: Your data is yours. No hidden SaaS lock-in.
 - **Developer First**: Everything is a typed API. 👩‍💻
 - **Deploy Anywhere**: Vercel, Cloudflare, Fly.io, or your own VPS.
+- **Zod Validation**: First-class support for Zod schemas on any field.
+- **Version History**: Full document versioning with one-click restore.
+- **Edge-Ready**: Native Cloudflare D1 + R2 support for global deployments.
+
+## Ready to build something awesome? [Let's go!](https://opacacms.com) 🎈
+
+## 🔌 Next-Gen Plugins
 
-Ready to build something awesome? [Let's go!](https://opacacms.com) 🎈
+OpacaCMS features a powerful, hook-based plugin system that allows you to extend the backend (schema, API middleware, routes) and the Admin UI (custom views, isolated dashboards) with full type-safety.
+
+### The `definePlugin` Helper
+
+Use `definePlugin` for a type-safe experience and rich metadata support.
+
+```typescript
+// plugins/my-plugin.ts
+import { definePlugin, html } from 'opacacms';
+
+export const myPlugin = () =>
+  definePlugin({
+    name: 'my-plugin',
+    label: 'Custom Dashboard',
+    description: 'A powerful extension for your CMS.',
+    version: '1.0.0',
+    icon: 'Activity',
+
+    // 1. Hook into Global API Requests
+    onRequest: async (c) => {
+      if (c.req.path.startsWith('/api/secret')) {
+        console.log('Intercepted secret request!');
+      }
+    },
+
+    // 2. Add API Routes & UI Assets
+    onRouterInit: (app) => {
+      // Serve the UI Registration Script
+      app.get('/api/plugins/my-plugin/setup.js', (c) => {
+        const js = `
+          // Use the simplified window.opaca helper
+          window.opaca.ui.registerAdminRoute({
+            label: "Plugin Dashboard",
+            icon: "Activity",
+            path: "/admin/my-plugin",
+            render: (serverUrl) => \`
+              <iframe 
+                src="\${serverUrl}/api/plugins/my-plugin/view" 
+                style="width:100%; height:calc(100vh - 100px); border:none;"
+              ></iframe>
+            \`
+          });
+        `;
+        return (c.header('Content-Type', 'application/javascript'), c.body(js));
+      });
+
+      // Serve the Isolated HTML View with Hono/HTML
+      app.get('/api/plugins/my-plugin/view', (c) => {
+        return c.html(html`
+          <body
+            style="background: #f6f9fc; padding: 40px; font-family: sans-serif;"
+          >
+            <h1>Modern Plugin UI</h1>
+            <p>Isolated from CMS styles with zero boilerplate.</p>
+          </body>
+        `);
+      });
+    },
+
+    // 3. Register Assets
+    adminAssets: () => ({
+      scripts: ['/api/plugins/my-plugin/setup.js'],
+    }),
+  });
+```
+
+### Plugin Lifecycle Hooks
+
+| Hook             | Description                                                                  |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `onInit`         | Runs during CMS startup. Used to inject collections or modify global config. |
+| `onRequest`      | Global middleware called for EVERY API request. Return `false` to block.     |
+| `onRouterInit`   | Called when the API router is being built. Mount custom Hono routes here.    |
+| `onInitComplete` | Fired once all plugins and core modules are fully initialized.               |
+| `onDestroy`      | Cleanup hook for graceful shutdown.                                          |
+| `onExport`       | Hook for SSG (Static Site Generation) plugins to export custom files.        |
+
+### Global Admin Registry (`window.opaca`)
+
+Plugins can interact with the Admin UI via the `window.opaca` object:
+
+- `window.opaca.ui.registerAdminRoute(item)`: Simplest way to add a new page to the sidebar.
+- `window.opaca.ui.notify(message, type)`: Show a toast notification.
+- `window.opaca.ui.toggleSidebar()`: Programmatically collapse/expand the menu.
+
+### Registering the Plugin
+
+Add your plugin to the `plugins` array in `opacacms.config.ts`:
+
+```typescript
+export default defineConfig({
+  // ...
+  plugins: [myPlugin()],
+});
+```