metaowl 0.1.3 → 0.2.0

package/README.md

@@ -1,13 +1,25 @@
 # metaowl
 
-> A lightweight meta-framework for [Odoo OWL](https://github.com/odoo/owl), built on top of [Vite](https://vitejs.dev).
+> A comprehensive meta-framework for [Odoo OWL](https://github.com/odoo/owl), built on top of [Vite](https://vitejs.dev).
 
 [![npm version](https://img.shields.io/npm/v/metaowl.svg)](https://www.npmjs.com/package/metaowl)
 [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](LICENSE)
 [![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 [![GitHub Issues](https://img.shields.io/github/issues/dennisschott/metaowl.svg)](https://github.com/dennisschott/metaowl/issues)
 
-metaowl gives you everything you need to ship production-ready OWL applications — file-based routing, app mounting, a fetch helper, `localStorage` cache, meta tag management, an SSG generator, and a batteries-included Vite plugin — so you can focus on building components instead of wiring infrastructure.
+metaowl is a complete solution for building production-ready OWL applications with everything you need out of the box:
+
+**Core Infrastructure:** File-based routing with dynamic routes, layout system, navigation guards, Pinia-inspired state management, and zero-config app mounting.
+
+**Odoo Integration:** Full JSON-RPC client with authentication, session management, and CRUD operations.
+
+**Developer Experience:** Composables for common patterns (auth, localStorage, fetching), form handling with validation, error boundaries, and internationalization.
+
+**SEO & PWA:** Sitemap/robots.txt generation, structured data support, service worker integration, web app manifest, and push notifications.
+
+**Testing & Quality:** Mock stores, router mocking, component testing utilities, plus bundled ESLint and PostCSS configs.
+
+All powered by a batteries-included Vite plugin that handles the build pipeline, so you can focus on building components instead of wiring infrastructure.
 
 ---
 
@@ -19,6 +31,16 @@ metaowl gives you everything you need to ship production-ready OWL applications
 - [Create a New Project](#create-a-new-project)
 - [Manual Setup](#manual-setup)
 - [File-based Routing](#file-based-routing)
+  - [Dynamic Routes](#dynamic-routes)
+- [Layouts](#layouts)
+- [Navigation Guards](#navigation-guards)
+- [State Management](#state-management-store)
+- [Error Boundaries](#error-boundaries)
+- [i18n / Internationalization](#i18n--internationalization)
+- [Form Handling](#form-handling)
+- [Auto-Import](#auto-import)
+- [Odoo JSON-RPC Service](#odoo-json-rpc-service)
+- [Composables / Hooks](#composables--hooks)
 - [CLI Reference](#cli-reference)
 - [API Reference](#api-reference)
   - [boot](#bootroutes)
@@ -27,6 +49,14 @@ metaowl gives you everything you need to ship production-ready OWL applications
   - [Meta](#meta)
   - [configureOwl](#configureowlconfig)
   - [buildRoutes](#buildroutesmodules)
+  - [Store](#store)
+  - [Layouts API](#layouts-api)
+  - [Router Guards](#router-guards-api)
+  - [Error Boundary](#error-boundary-api)
+  - [i18n](#i18n-api)
+  - [Forms](#forms-api)
+  - [OdooService](#odooservice-api)
+  - [Composables](#composables-api)
 - [Vite Plugin](#vite-plugin)
   - [metaowlPlugin](#metaowlpluginoptions)
   - [metaowlConfig](#metaowlconfigoptions)
@@ -41,10 +71,23 @@ metaowl gives you everything you need to ship production-ready OWL applications
 ## Features
 
 - **File-based routing** — mirrors Nuxt/Next.js conventions out of the box
+- **Dynamic routes** — support for parameters `[id]`, optional params `[id]?`, and catch-all `[...path]`
+- **Layouts** — share page structures across routes with automatic layout resolution
+- **Navigation guards** — route middleware for authentication, authorization, and redirects
+- **State management** — Pinia-like store system with mutations, actions, and getters
 - **App mounting** — zero-config OWL component mounting with template merging
 - **Fetch helper** — thin wrapper around the Fetch API with a configurable base URL and error handler
 - **Cache** — async-style `localStorage` wrapper (`get`, `set`, `remove`, `clear`, `keys`)
 - **Meta tags** — programmatic control over `<title>`, Open Graph, Twitter Card, canonical, and more
+- **Error boundaries** — global error handling with context tracking and error pages
+- **i18n** — internationalization with pluralization and interpolation support
+- **Form handling** — schema validation with async support via `useForm()`
+- **Auto-import** — automatic component registration with TypeScript declarations
+- **Odoo RPC Service** — full JSON-RPC client with authentication and CRUD operations
+- **Composables** — reusable hooks for auth, localStorage, fetching, and more
+- **Testing Utilities** — mock store, router mocking, component mount helpers
+- **SEO Utils** — sitemap, robots.txt, JSON-LD, Open Graph, Twitter Cards
+- **PWA Support** — service worker, manifest generation, push notifications
 - **SSG generator** — statically pre-renders HTML pages with correct meta tags at build time
 - **Vite plugin** — handles `COMPONENTS` injection, XML template copying, CSS auto-import, chunk splitting, and env filtering
 - **ESLint & PostCSS** — shareable configs included; no extra dev-dependencies needed in your project
@@ -76,7 +119,7 @@ Install metaowl globally and run it interactively:
 
 ```bash
 npm install -g metaowl
-metaowl-create app_name
+metaowl-create my-app
 ```
 
 This generates a ready-to-run project:
@@ -213,6 +256,470 @@ SSG path variants (`.html`, trailing slash, `index.html`) are added automaticall
 
 ---
 
+### Dynamic Routes
+
+File-based routing supports dynamic segments using bracket notation. The router supports required parameters, optional parameters, and catch-all routes.
+
+| File | URL Pattern | Example URL | Params |
+|---|---|---|---|
+| `pages/user/[id]/User.js` | `/user/:id` | `/user/123` | `{ id: '123' }` |
+| `pages/product/[category]/[slug]/Product.js` | `/product/:category/:slug` | `/product/tech/hello` | `{ category: 'tech', slug: 'hello' }` |
+| `pages/blog/[id]/[slug?]/Blog.js` | `/blog/:id/:slug?` | `/blog/123` or `/blog/123/my-post` | `{ id: '123' }` or `{ id: '123', slug: 'my-post' }` |
+| `pages/docs/[...path]/Docs.js` | `/docs/:path(.*)` | `/docs/api/routing` | `{ path: 'api/routing' }` |
+| `pages/[...404]/NotFound.js` | `/:path(.*)` | `/any/unknown/path` | `{ path: 'any/unknown/path' }` |
+
+**Param Types:**
+
+- `[param]` — Required parameter, must be present in URL
+- `[param?]` — Optional parameter, may be omitted
+- `[...param]` — Catch-all parameter, matches any number of segments
+
+Access parameters in your component:
+
+```js
+import { Component, xml } from '@odoo/owl'
+
+export class UserPage extends Component {
+  static template = xml`
+    <div>
+      <h1>User Profile</h1>
+      <p>ID: <t t-esc="props.params.id"/></p>
+    </div>
+  `
+  
+  static props = ['params']
+}
+```
+
+---
+
+## Layouts
+
+Layouts provide shared page structures. Create a `layouts/` directory alongside your `pages/`:
+
+```
+src/
+  layouts/
+    default/
+      DefaultLayout.js
+      DefaultLayout.xml
+    admin/
+      AdminLayout.js
+      AdminLayout.xml
+  pages/
+    index/
+      Index.js  → uses 'default' layout
+    admin/
+      dashboard/
+        Dashboard.js  → can use 'admin' layout
+```
+
+Use a layout by setting the static `layout` property:
+
+```js
+export class DashboardPage extends Component {
+  static template = 'DashboardPage'
+  static layout = 'admin'
+}
+```
+
+If no layout is specified, the `default` layout is used automatically.
+
+**Layout Template Convention:**
+
+```xml
+<templates>
+  <t t-name="DefaultLayout">
+    <div class="layout-default">
+      <header>The Header</header>
+      <main>
+        <t t-slot="default"/>
+      </main>
+      <footer>The Footer</footer>
+    </div>
+  </t>
+</templates>
+```
+
+---
+
+## Navigation Guards
+
+Navigation guards intercept route navigation and can:
+- Block access to routes
+- Redirect to other routes
+- Perform async checks (authentication, permissions)
+
+### Global Guards
+
+```js
+import { beforeEach, afterEach } from 'metaowl'
+
+// Run before navigation
+beforeEach((to, from, next) => {
+  const auth = useAuthStore()
+  
+  if (to.meta.requiresAuth && !auth.state.loggedIn) {
+    next('/login')  // redirect
+  } else {
+    next()  // proceed
+  }
+})
+
+// Run after navigation
+afterEach((to, from) => {
+  console.log(`Navigated to ${to.path}`)
+})
+```
+
+### Per-Route Guards
+
+```js
+export class AdminPage extends Component {
+  static route = {
+    path: '/admin',
+    meta: { requiresAuth: true, role: 'admin' },
+    beforeEnter: (to, from, next) => {
+      // Check specific permissions
+      if (!hasAdminRole()) {
+        next('/unauthorized')
+      } else {
+        next()
+      }
+    }
+  }
+}
+```
+
+**Guard Behavior:**
+
+- `next()` — proceed to next guard
+- `next(false)` — abort navigation
+- `next('/path')` — redirect to path
+- `next(error)` — abort with error
+
+---
+
+## State Management (Store)
+
+A Pinia-inspired store system with mutations, actions, and getters.
+
+```js
+import { Store } from 'metaowl'
+
+const useUserStore = Store.define('user', {
+  state: () => ({
+    name: '',
+    loggedIn: false
+  }),
+  
+  getters: {
+    displayName: (state) => state.name || 'Guest'
+  },
+  
+  mutations: {
+    setName: (state, name) => { state.name = name },
+    setLoggedIn: (state, value) => { state.loggedIn = value }
+  },
+  
+  actions: {
+    async login({ commit }, credentials) {
+      const result = await Fetch.url('/api/login', 'POST', credentials)
+      commit('setName', result.name)
+      commit('setLoggedIn', true)
+      return result
+    },
+    
+    logout({ commit }) {
+      commit('setName', '')
+      commit('setLoggedIn', false)
+    }
+  }
+})
+```
+
+**In a component:**
+
+```js
+const store = useUserStore()
+
+store.commit('setName', 'John')  // synchronous mutation
+await store.dispatch('login', { email, password })  // async action
+console.log(store.getters.displayName.value)  // computed getter
+```
+
+**Persistence:**
+
+```js
+import { Store, createPersistencePlugin } from 'metaowl'
+
+// Automatically persist state to localStorage
+Store.use(createPersistencePlugin({
+  storage: localStorage,
+  paths: ['user', 'preferences']  // only persist specific paths
+}))
+```
+
+---
+
+## Error Boundaries
+
+Handle runtime errors gracefully with automatic fallback UI:
+
+```js
+import { ErrorBoundary } from 'metaowl'
+
+// Wrap your app
+const errorBoundary = ErrorBoundary.wrap(AppComponent)
+errorBoundary.mount(document.body)
+
+// Global error handler
+ErrorBoundary.onError((error, context) => {
+  console.error('App error:', error, context)
+  // Send to error tracking service
+  analytics.track('error', { message: error.message, path: context?.route })
+})
+```
+
+**Error Pages:**
+
+```js
+// src/pages/error.js
+export default class ErrorPage extends Component {
+  static template = xml`
+    <div class="error-page">
+      <h1>Error <t t-esc="props.code || 500"/></h1>
+      <p t-esc="props.message"/>
+      <button t-on-click="goHome">Go Home</button>
+    </div>
+  `
+}
+```
+
+---
+
+## i18n / Internationalization
+
+Full-featured translation system with pluralization:
+
+```js
+import { I18n } from 'metaowl'
+
+await I18n.load({
+  locale: 'de',
+  messages: {
+    welcome: 'Willkommen, {name}!',
+    items: '{count, plural, one {# Item} other {# Items}}'
+  }
+})
+```
+
+**In templates:**
+
+```xml
+<div t-esc="I18n.t('welcome', { name: state.username })"/>
+<span t-esc="I18n.t('items', { count: state.cartItems })"/>
+```
+
+**Pluralization:**
+
+```js
+I18n.t('items', { count: 1 })   // "1 Item"
+I18n.t('items', { count: 5 })   // "5 Items"
+```
+
+---
+
+## Form Handling
+
+Declarative forms with validation support:
+
+```js
+import { useForm } from 'metaowl'
+
+class LoginPage extends Component {
+  setup() {
+    this.form = useForm({
+      schema: {
+        email: { required: true, type: 'email' },
+        password: { required: true, minLength: 8 }
+      },
+      onSubmit: async (values) => {
+        await Fetch.post('/api/login', values)
+        this.env.router.navigate('/dashboard')
+      }
+    })
+  }
+}
+```
+
+```xml
+<form t-on-submit.prevent="form.submit">
+  <input t-model="form.values.email" />
+  <span t-if="form.errors.email" t-esc="form.errors.email"/>
+  
+  <input type="password" t-model="form.values.password" />
+  <span t-if="form.errors.password" t-esc="form.errors.password"/>
+  
+  <button type="submit" t-att-disabled="form.isSubmitting">
+    <t t-if="form.isSubmitting">Loading...</t>
+    <t t-else="">Login</t>
+  </button>
+</form>
+```
+
+---
+
+## Auto-Import
+
+Optional automatic component registration for development productivity:
+
+**Enable in vite.config.js:**
+
+```js
+import { metaowlConfig } from 'metaowl/vite'
+
+export default metaowlConfig({
+  autoImport: {
+    enabled: true,
+    pattern: '**/*.js'
+  }
+})
+```
+
+**How it works:**
+
+1. Components in `src/components/` are auto-scanned
+2. Type declarations are generated in `.metaowl/components.d.ts`
+3. Use components without manual imports:
+
+```js
+// No import needed!
+export default class MyPage extends Component {
+  static template = xml`
+    <div>
+      <Button color="primary"/>
+      <Card>
+        <Modal t-if="state.showModal"/>
+      </Card>
+    </div>
+  `
+  // Components are automatically available
+  // from src/components/Button/Button.js, etc.
+}
+```
+
+**Note:** Auto-import is opt-in and primarily useful during development. For production, consider explicit imports for better tree-shaking and clarity.
+
+---
+
+## Odoo JSON-RPC Service
+
+Connect to Odoo backends with a full-featured JSON-RPC client:
+
+```js
+import { OdooService } from 'metaowl'
+
+// Configure connection
+OdooService.configure({
+  baseUrl: 'https://my-odoo-instance.com',
+  database: 'my_database',
+  username: 'admin',
+  password: 'admin'  // or apiKey
+})
+
+// Authenticate
+const session = await OdooService.authenticate()
+console.log(`Logged in as ${session.name}`)
+
+// Search and read records
+const partners = await OdooService.searchRead('res.partner', {
+  domain: [['is_company', '=', true]],
+  fields: ['name', 'email', 'phone'],
+  limit: 10
+})
+
+// Call any model method
+await OdooService.call('res.partner', 'create', [{
+  name: 'New Partner',
+  email: 'partner@example.com'
+}])
+```
+
+**CRUD Operations:**
+
+```js
+// Create
+const id = await OdooService.create('res.partner', { name: 'Test' })
+
+// Read
+const records = await OdooService.read('res.partner', [id], ['name'])
+
+// Update
+await OdooService.write('res.partner', [id], { name: 'Updated' })
+
+// Delete
+await OdooService.unlink('res.partner', [id])
+```
+
+**Session Management:**
+
+```js
+// Check authentication
+if (OdooService.isAuthenticated()) {
+  console.log('User:', OdooService.getSession().name)
+}
+
+// Logout
+OdooService.logout()
+
+// Listen to auth changes
+OdooService.onAuthChange((session) => {
+  console.log(session ? 'Logged in' : 'Logged out')
+})
+```
+
+---
+
+## Composables / Hooks
+
+Reusable OWL hooks for common patterns:
+
+```js
+import { useAuth, useLocalStorage, useFetch } from 'metaowl'
+
+class MyComponent extends Component {
+  setup() {
+    // Authentication state
+    const { user, isLoggedIn, logout } = useAuth()
+
+    // Persisted state
+    const theme = useLocalStorage('theme', 'light')
+
+    // Data fetching
+    const { data, loading, error, refresh } = useFetch('/api/users')
+
+    return { user, theme, data, loading, error, refresh }
+  }
+}
+```
+
+**Available Composables:**
+
+| Composable | Description |
+|---|---|
+| `useAuth()` | Authentication state linked to OdooService |
+| `useLocalStorage(key, default)` | Reactive localStorage access |
+| `useFetch(url, options)` | Data fetching with loading/error states |
+| `useDebounce(value, wait)` | Debounced reactive value |
+| `useThrottle(fn, wait)` | Throttled function |
+| `useWindowSize()` | Reactive window dimensions |
+| `useOnlineStatus()` | Network connectivity state |
+| `useAsyncState(fn)` | Async operation state management |
+| `useCache(key, default)` | Reactive cache access |
+
+---
+
 ## CLI Reference
 
 metaowl ships four CLI commands that use its own bundled Vite, Prettier, and ESLint binaries — no need to install them separately in your project.
@@ -386,6 +893,340 @@ buildRoutes(modules: Record<string, object>): RouteDefinition[]
 
 ---
 
+### `Store`
+
+Pinia-inspired state management system with mutations, actions, and getters.
+
+#### `Store.define(id, config)`
+
+Creates a store factory function.
+
+```ts
+const useStore = Store.define('storeId', {
+  state: () => ({ count: 0 }),
+  getters: { double: (state) => state.count * 2 },
+  mutations: { increment: (state) => state.count++ },
+  actions: { async fetchData({ commit }) { ... } }
+})
+```
+
+#### Store Instance Methods
+
+| Method | Description |
+|---|---|
+| `commit(mutation, payload)` | Execute synchronous mutation |
+| `dispatch(action, payload)` | Execute async action |
+| `subscribe(callback)` | Listen to mutations `(mutation, state, prevState) => void` |
+| `subscribeAction(callback)` | Listen to actions `(action, status, result) => void` |
+| `reset()` | Reset state to initial values |
+
+#### `Store.use(plugin)`
+
+Register a global plugin applied to all stores.
+
+```ts
+import { Store, createPersistencePlugin } from 'metaowl'
+
+Store.use(createPersistencePlugin({ storage: localStorage }))
+```
+
+---
+
+### `Layouts API`
+
+Functions for layout management.
+
+| Function | Description |
+|---|---|
+| `registerLayout(name, Component)` | Register a layout |
+| `getLayout(name)` | Get layout component by name |
+| `setDefaultLayout(name)` | Set default layout |
+| `resolveLayout(Component, path?)` | Resolve layout for component |
+| `subscribeToLayouts(callback)` | Listen to layout events |
+
+**Component Layout Property:**
+
+```js
+export class MyPage extends Component {
+  static layout = 'admin'  // Use 'admin' layout
+}
+```
+
+---
+
+### `Router Guards API`
+
+Functions for navigation control.
+
+| Function | Description |
+|---|---|
+| `beforeEach(guard)` | Register global guard (returns unsubscribe) |
+| `afterEach(hook)` | Register global after hook (returns unsubscribe) |
+| `getCurrentRoute()` | Get current route object |
+| `getPreviousRoute()` | Get previous route object |
+| `push(path)` | Navigate to path |
+| `replace(path)` | Replace current history entry |
+| `back()` / `forward()` / `go(n)` | History navigation |
+
+**Router Singleton:**
+
+```js
+import { router } from 'metaowl'
+
+router.beforeEach((to, from, next) => { ... })
+router.push('/new-path')
+```
+
+---
+
+### `Error Boundary API`
+
+| Function | Description |
+|---|---|
+| `ErrorBoundary.wrap(Component)` | Wrap component with error handling |
+| `ErrorBoundary.onError(callback)` | Register global error handler `(error, context) => void` |
+| `ErrorBoundary.getLastError()` | Get most recent error |
+| `ErrorBoundary.clearError()` | Clear error state |
+
+**Error Context:**
+
+```ts
+{
+  route?: string,
+  component?: string,
+  timestamp: number
+}
+```
+
+---
+
+### `i18n API`
+
+**`I18n.load(config)`**
+
+```ts
+I18n.load({
+  locale: string,
+  messages: Record<string, string | MessageFunction>,
+  numberFormats?: Record<string, object>,
+  dateFormats?: Record<string, object>
+})
+```
+
+**`I18n.t(key, values?)`**
+
+Translate a message with optional interpolation:
+
+```ts
+I18n.t('welcome', { name: 'John' })  // "Welcome, John!"
+```
+
+**`I18n.n(value, format?)`** / **`I18n.d(value, format?)`**
+
+Format numbers and dates:
+
+```ts
+I18n.n(1234.5, 'currency')  // "€1,234.50"
+I18n.d(new Date(), 'short') // "12.03.2026"
+```
+
+**Locale Switching:**
+
+```js
+await I18n.setLocale('en')
+console.log(I18n.locale)  // "en"
+```
+
+---
+
+### `Forms API`
+
+**`useForm(options)`**
+
+```ts
+useForm({
+  schema?: ValidationSchema,
+  initialValues?: Record<string, any>,
+  onSubmit?: (values: Record<string, any>) => Promise<void>,
+  validateOnChange?: boolean,
+  validateOnBlur?: boolean
+}): FormInstance
+```
+
+**Form Instance:**
+
+| Property | Type | Description |
+|---|---|---|
+| `values` | `object` | Current form values |
+| `errors` | `object` | Validation errors by field |
+| `touched` | `object` | Fields that have been touched |
+| `isSubmitting` | `boolean` | Submit in progress |
+| `isValid` | `boolean` | All validation passed |
+| `isDirty` | `boolean` | Values differ from initial |
+
+| Method | Description |
+|---|---|
+| `submit(event?)` | Trigger form submission |
+| `setValue(field, value)` | Set a field value |
+| `setValues(values)` | Set multiple values |
+| `setError(field, message)` | Set a field error |
+| `clearErrors()` | Clear all errors |
+| `reset()` | Reset to initial values |
+| `validate()` | Trigger validation |
+
+**Validation Schema:**
+
+```js
+{
+  email: {
+    required: true,
+    type: 'email'
+  },
+  age: {
+    type: 'number',
+    min: 0,
+    max: 120
+  }
+}
+```
+
+---
+
+### `OdooService API`
+
+| Method | Description |
+|---|---|
+| `configure(config)` | Configure Odoo connection (baseUrl, database, credentials) |
+| `authenticate()` | Login and get session |
+| `logout()` | Clear session |
+| `isAuthenticated()` | Check if currently logged in |
+| `getSession()` | Get current session info |
+| `onAuthChange(callback)` | Subscribe to auth state changes (returns unsubscribe) |
+
+**CRUD Operations:**
+
+| Method | Description |
+|---|---|
+| `searchRead(model, options)` | Search and read records |
+| `call(model, method, args, kwargs)` | Call any model method |
+| `read(model, ids, fields)` | Read specific records |
+| `create(model, values)` | Create new record |
+| `write(model, ids, values)` | Update records |
+| `unlink(model, ids)` | Delete records |
+| `searchCount(model, domain)` | Get count of matching records |
+
+**Utility Methods:**
+
+| Method | Description |
+|---|---|
+| `listDatabases()` | Get available databases |
+| `versionInfo()` | Get Odoo server version info |
+
+**Configuration Options:**
+
+```ts
+{
+  baseUrl: string,        // Odoo instance URL
+  database: string,       // Database name
+  username?: string,      // Username (or use in authenticate())
+  password?: string,      // Password (or apiKey)
+  apiKey?: string,        // API Key alternative to password
+  persistSession?: boolean // Persist to localStorage (default: true)
+}
+```
+
+---
+
+### `Composables API`
+
+**`useAuth()`**
+
+Authentication state for Odoo integration.
+
+```ts
+{
+  user: Ref<Session|null>,      // Current user info
+  isLoggedIn: Ref<boolean>,     // Auth status
+  isLoading: Ref<boolean>,      // Loading state
+  login: (credentials) => Promise<boolean>,
+  logout: () => Promise<void>,
+  checkAuth: () => Promise<boolean>
+}
+```
+
+**`useLocalStorage(key, defaultValue)`**
+
+Reactive localStorage access with cross-tab sync.
+
+```ts
+const theme = useLocalStorage('theme', 'light')
+
+theme.value = 'dark'  // Automatically saves to localStorage
+// Other tabs are notified via storage event
+```
+
+**`useFetch(url, options)`**
+
+Data fetching with reactive states.
+
+```ts
+{
+  data: Ref<any>,       // Fetched data
+  loading: Ref<boolean>,
+  error: Ref<Error|null>,
+  refresh: () => Promise<void>,
+  execute: (url?) => Promise<void>
+}
+```
+
+Options: `initialData`, `immediate`, `transform`, `onError`
+
+**`useDebounce(value, wait)`**
+
+```ts
+const searchQuery = useState('')
+const debounced = useDebounce(searchQuery, 500)
+// debounced updates 500ms after searchQuery stops changing
+```
+
+**`useThrottle(fn, wait)`**
+
+```ts
+const throttledSearch = useThrottle((query) => {
+  performSearch(query)
+}, 500)
+```
+
+**`useWindowSize()`**
+
+```ts
+const { width, height } = useWindowSize()
+const isMobile = computed(() => width.value < 768)
+```
+
+**`useOnlineStatus()`**
+
+```ts
+const isOnline = useOnlineStatus()
+// Reactive to network state changes
+```
+
+**`useAsyncState(asyncFn, options)`**
+
+```ts
+const { state, data, execute, isLoading, isSuccess, isError } =
+  useAsyncState(fetchUserData, { immediate: true })
+// state: null | 'loading' | 'success' | 'error'
+```
+
+**`useCache(key, defaultValue)`**
+
+```ts
+const { value, set, get, remove, clear } = useCache('user-prefs', {})
+```
+
+---
+
 ## Vite Plugin
 
 ### `metaowlPlugin(options)`
@@ -403,6 +1244,14 @@ Returns an array of Vite plugins that configure the full metaowl build pipeline.
 | `frameworkEntry` | `'./node_modules/metaowl/index.js'` | Entry for the `framework` chunk |
 | `restartGlobs` | `[]` | Additional globs that trigger dev-server restart |
 | `envPrefix` | `undefined` | Only expose `process.env` vars with this prefix (plus `NODE_ENV`) |
+| `autoImport` | `{ enabled: false }` | Auto-import configuration: `{ enabled, pattern }` |
+
+**Auto-Import Options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `enabled` | `false` | Enable component auto-import |
+| `pattern` | `'*.js'` | Glob pattern for scanning components |
 
 **What the plugin does:**