snice 2.5.4 → 3.2.0

package/README.md

@@ -1,10 +1,10 @@
 # Snice
 
-An imperative TypeScript framework for building vanilla web components with decorators and routing
+> **AI Assistants:** For token-efficient documentation, read [docs/ai/](./docs/ai/) instead. Same content, 70% fewer tokens.
 
-## Quick Start
+A TypeScript framework for building sustainable web applications through clear separation of governance.
 
-Create a new Snice app with one command:
+## Quick Start
 
 ```bash
 npx snice create-app my-app
@@ -12,1101 +12,769 @@ cd my-app
 npm run dev
 ```
 
-## Core Philosophy: Imperative, Not Reactive
+## Philosophy
 
-Snice takes an **imperative approach** to web components. Unlike reactive frameworks that automatically re-render when data changes, Snice components:
+Without structure, you'll end up with auth checks mixed in rendering logic, business rules duplicated across components, and data fetching scattered in event handlers. **Snice provides constructs that guide you to put code where it belongs, keeping you productive as your app grows.**
 
-- **Render once** when connected to the DOM
-- **Never re-render** automatically
-- Require **explicit method calls** to update visual state
-- Give you **full control** over when and how updates happen
+- **Pages fetch data and assemble UI** - They understand what the user wants to do
+- **Elements handle visuals only** - They don't know or care about business logic
+- **Controllers let you swap behavior** - Same UI, different data sources or logic
+- **Cross-cutting concerns stay separate** - Auth, routing, and global state don't leak into your components
 
-This approach gives you direct control over DOM updates without hidden complexity or automatic re-renders.
+Yes, global state is bad! but you will have a little always, and it should be managed well.
+Usually we see auth/principals, themes, and localization as global state examples.
 
-## The Snice Way: Elements + Controllers
+Each piece hints at where your code should live, preventing the mess that kills velocity on larger teams.
 
-Snice separates UI from data: **elements handle UI, controllers handle behavior and data**.
+## The Tools
 
-```typescript
-import { element, controller, property, query } from 'snice';
+Snice provides decorators and utilities that map directly to these architectural concerns:
 
-export interface IUserCard extends HTMLElement {
-  userId: string;
-  showUser(user: any): void;
-}
 
-// Element: Just UI
-@element('user-card')
-class UserCard extends HTMLElement implements IUserCard {
-  @property({ attribute: 'user-id' })
-  userId = '';
-  
-  @query('h3')
-  nameElement!: HTMLHeadingElement;
-  
-  @query('p')
-  emailElement!: HTMLParagraphElement;
-  
-  html() {
-    return `
-      <div class="card">
-        <h3>Loading...</h3>
-        <p>Please wait...</p>
-      </div>
-    `;
-  }
-  
-  showUser(user: any) {
-    this.nameElement.textContent = user.name;
-    this.emailElement.textContent = user.email;
-  }
-}
+### Basic Building Blocks
+```typescript
 
-// Controller: Data and behavior
-@controller('user-loader')
-class UserLoaderController {
-  element!: IUserCard;
-  
-  async attach(element: IUserCard) {
-    const response = await fetch(`/api/users/${element.userId}`);
-    const user = await response.json();
-    
-    element.showUser(user);
-  }
-  
-  async detach(element: IUserCard) { /* Cleanup */ }
-}
-```
+@page({ tag: 'user-profile-page', routes: ['/users/:userId'], guards: [isAuthenticated] })
+class UserProfilePage extends HTMLElement { ... }
 
-Connect them in HTML:
-```html
-<user-card user-id="123" controller="user-loader"></user-card>
-```
+@element('user-stats')
+class UserStats extends HTMLElement { ... }
 
-That's it. Element renders UI, controller fetches data, they communicate through method calls, events, and request/response channels.
+@controller('real-time-user-loader')
+class RealTimeUserLoader { ... }
 
-## Core Concepts
+// And within these classes, use decorators like:
+@property() name = 'default';
+@render() fn() { return html`...`; }
+@styles() fn() { return css`...`; }
+@ready() async fn() { ... }
+@dispose() fn() { ... }
+@watch('name') fn(oldVal, newVal) { ... }
+@query('input') input!: HTMLInputElement;
+@queryAll('.item') items!: NodeListOf<HTMLElement>;
+@on('click', 'button') fn(e: Event) { ... }
+@dispatch('value-changed') fn(val: string) => Event Detail
+@context() fn(ctx: Context) { ... }
+@request('user') fn(): () => Request;
+@respond('user') fn(req) => Response;
+```
 
-Snice provides a clear separation of concerns through decorators:
 
-### Class Decorators
-- **`@element`** - Creates custom HTML elements with encapsulated visual behavior and styling
-- **`@controller`** - Handles data fetching, server communication, and business logic separate from visual components  
-- **`@page`** - Defines routable page components that render when their route is active, with URL params passed as attributes
+### 1. Cross-Cutting Concerns: Router + Context
 
-### Property & Query Decorators
-- **`@property`** - Declares properties that automatically sync with DOM attributes
-- **`@query`** - Queries a single element from shadow DOM
-- **`@queryAll`** - Queries multiple elements from shadow DOM
-- **`@watch`** - Watches property changes and calls a method when they occur
-- **`@ready`** - Runs a method after the element's shadow DOM is ready
-- **`@dispose`** - Runs a method when the element is removed from the DOM
+```typescript
+// sample-app-context.ts
+class AppContext {
+  user: User | null = null;
+  theme: 'light' | 'dark' = 'light';
 
-### Event Decorators
-- **`@on`** - Listens for events on elements
-- **`@dispatch`** - Dispatches custom events after method execution
-- **`@request`** - Makes requests from elements or controllers
-- **`@respond`** - Responds to requests in elements or controllers
+  setUser(user: User) { this.user = user; }
+  getUser() { return this.user; }
+}
 
-This separation keeps your components focused: elements handle presentation, controllers manage data, and pages define navigation.
+// main.ts
+import { Router } from 'snice';
 
-## Basic Component
+const { page, navigate, initialize } = Router({
+  target: '#app',
+  context: new AppContext(),  // Global state
+  type: 'hash'
+});
 
-```typescript
-import { element } from 'snice';
+// Any page can access context
+@page({ tag: 'dashboard-page', routes: ['/dashboard'] })
+class DashboardPage extends HTMLElement {
+  private appContext?: AppContext;
 
-@element('my-button')
-class MyButton extends HTMLElement {
-  html() {
-    return `<button>Click me</button>`;
+  @context()
+  handleContext(ctx: Context) {
+    this.appContext = ctx.application;
+    const user = this.getUser();
   }
+  // ...
 }
 ```
 
-That's it. Your component renders when added to the DOM:
-
-```html
-<my-button></my-button>
-```
+### 2. Pages: Orchestrating Intent
 
-## The Imperative Way
+```typescript
+// pages/user-profile-page.ts
+@page({ tag: 'user-profile-page', routes: ['/users/:userId'] })
+class UserProfilePage extends HTMLElement {
+  @property()
+  userId = '';  // From URL parameter
 
-In Snice, updates are explicit. Components expose methods that controllers or other components call to update state:
+  @property({ type: Object })
+  user = null;
 
-```typescript
-import { element, property, query } from 'snice';
+  @property({ type: Object })
+  userStats = null;
 
-@element('counter-display')
-class CounterDisplay extends HTMLElement {
-  @property({ type: Number })
-  count = 0;
-  
-  @query('.count')
-  countElement!: HTMLSpanElement;
-  
-  @query('.status')
-  statusElement!: HTMLSpanElement;
-
-  html() {
-    // Renders ONCE - no automatic re-rendering
-    return `
-      <div class="counter">
-        <span class="count">${this.count}</span>
-        <span class="status">Ready</span>
-      </div>
+  @ready()
+  async loadUserData() {
+    // Pages handle data fetching, elements just display
+    const [user, stats] = await Promise.all([
+      fetch(`/api/users/${this.userId}`).then(r => r.json()),
+      fetch(`/api/users/${this.userId}/stats`).then(r => r.json())
+    ]);
+    this.user = user;
+    this.userStats = stats;
+  }
+
+  @render()
+  renderContent() {
+    return html`
+      <page-header .user=${this.user}></page-header>
+      <user-stats .stats=${this.userStats}></user-stats>
+      <user-activity .userId=${this.userId}></user-activity>
     `;
   }
-  
-  // Imperative update methods - YOU control when updates happen
-  setCount(newCount: number) {
-    this.count = newCount;
-    this.countElement.textContent = String(newCount);
-  }
-  
-  setStatus(status: string) {
-    this.statusElement.textContent = status;
-  }
-  
-  increment() {
-    this.setCount(this.count + 1);
-    this.setStatus('Incremented!');
-  }
 }
 ```
 
-**Key Points:**
-- The `html()` method runs **once** when the element connects
-- Updates happen through **explicit method calls** like `setCount()`
-- You have **full control** over what updates and when
-- No surprises, no magic, no hidden re-renders
-
-## Properties
-
-Properties automatically sync with DOM attributes in both directions. The HTML is rendered once when the element connects to the DOM. Use properties for initial configuration and watch for changes to update the UI.
+### 3. Elements: Pure Presentation
 
 ```typescript
-import { element, property } from 'snice';
-
-@element('user-card')
-class UserCard extends HTMLElement {
-  @property()
-  name = 'Anonymous';
-
-  @property({ attribute: 'user-role' })  // Maps to user-role attribute
-  role = 'User';
+// elements/user-stats.ts
+@element('user-stats')
+class UserStats extends HTMLElement {
+  @property({ type: Object })
+  stats = null;
 
-  @property({ type: Boolean })
-  verified = false;
+  @render()
+  renderContent() {
+    if (!this.stats) return html`<div>Loading...</div>`;
 
-  html() {
-    // This renders ONCE with the initial property values
-    return `
-      <div class="card">
-        <h3>${this.name}</h3>
-        <span class="role">${this.role}</span>
-        ${this.verified ? '<span class="badge">✓ Verified</span>' : ''}
+    return html`
+      <div class="stats">
+        <div class="stat">
+          <span class="label">Views</span>
+          <span class="value">${this.stats.views}</span>
+        </div>
+        <div class="stat">
+          <span class="label">Followers</span>
+          <span class="value">${this.stats.followers}</span>
+        </div>
       </div>
     `;
   }
+
+  @styles()
+  statsStyles() {
+    return css`
+      .stats { display: flex; gap: 2rem; }
+      .stat { text-align: center; }
+    `;
+  }
 }
-```
 
-Use it with attributes (both ways work):
-```html
-<!-- Setting attributes automatically updates properties -->
-<user-card name="Jane Doe" user-role="Admin" verified></user-card>
-
-<script>
-  const card = document.querySelector('user-card');
-  card.name = 'John Smith';      // Sets name="John Smith" attribute
-  card.verified = true;          // Sets verified attribute
-</script>
+// Usage in parent page (which handles data fetching):
+// <user-stats .stats=${this.userStats}></user-stats>
 ```
 
-For arrays of basic types, use `SimpleArray` for safe reflection:
+### 4. Controllers: Behavior Management
 
 ```typescript
-import { element, property, SimpleArray } from 'snice';
+// controllers/real-time-user-loader.ts
+@controller('real-time-user-loader')
+class RealTimeUserLoader {
+  async attach(element: IUserList) {
+    this.socket = new WebSocket('/api/users/stream');
+    this.socket.onmessage = (e) => {
+      element.setUsers(JSON.parse(e.data));
+    };
+  }
+  // ...
+}
 
-@element('tag-list')
-class TagList extends HTMLElement {
-  @property({ type: SimpleArray })
-  tags = ['javascript', 'typescript', 'web'];
+// controllers/cached-user-loader.ts
+@controller('cached-user-loader')
+class CachedUserLoader {
+  async attach(element: IUserList) {
+    const cached = localStorage.getItem('users');
+    if (cached) element.setUsers(JSON.parse(cached));
+  }
+  // ...
+}
+
+// elements/user-list.ts - stays the same
+@element('user-list')
+class UserList extends HTMLElement {
+  setUsers(users: User[]) {
+    this.users = users;
+    // ...
+  }
 
-  html() {
-    return `<div>${this.tags.join(', ')}</div>`;
+  @render()
+  renderContent() {
+    return html`
+      <ul>${this.users.map(u => html`<li>${u.name}</li>`)}</ul>
+    `;
   }
 }
 ```
 
+Usage - swap behavior without touching presentation:
+
 ```html
-<tag-list tags="react，vue，angular"></tag-list>
+<user-list controller="real-time-user-loader"></user-list>
+<user-list controller="cached-user-loader"></user-list>
 ```
 
-## Watching Property Changes
+## Key Features
 
-Use `@watch` to imperatively update DOM when properties change:
+**Differential Rendering** - Only updates changed parts of the DOM, not entire components
 
-```typescript
-import { element, property, watch, query } from 'snice';
+**Auto-Rendering** - Components automatically re-render when properties change
 
-@element('theme-toggle')
-class ThemeToggle extends HTMLElement {
-  @property()
-  theme: 'light' | 'dark' = 'light';
+**Template Syntax** - Clean `html\`...\`` and `css\`...\`` tagged templates
 
-  @query('.icon')
-  icon!: HTMLSpanElement;
-  
-  html() {
-    return `
-      <button>
-        <span class="icon">🌞</span>
-      </button>
-    `;
-  }
-  
-  @watch('theme')
-  updateTheme(oldValue: string, newValue: string) {
-    this.icon.textContent = newValue === 'dark' ? '🌙' : '🌞';
-  }
-  
-  @on('click', 'button')
-  toggle() {
-    this.theme = this.theme === 'light' ? 'dark' : 'light';
-  }
-}
-```
+**Type Safety** - Full TypeScript support with decorator-based APIs
 
-**Key Points:**
-- `@watch` methods are called when the property value changes
-- Receives `oldValue`, `newValue`, and `propertyName` as parameters
-- Perfect for imperatively updating DOM elements
-- Can watch multiple properties with multiple decorators
-- Works with both programmatic changes and attribute changes
+**Zero Dependencies** - No external runtime dependencies
 
-You can watch multiple properties with a single decorator:
+**Standards-Based** - Built on web components, works with any framework
 
-```typescript
-@watch('width', 'height', 'scale')
-updateDimensions(_old: number, _new: number, _name: string) {
-  // Called when any of these properties change
-  console.log(`${_name} changed from ${_old} to ${_new}`);
-  this.recalculateLayout();
-}
-```
+## Core APIs
 
-Watch all property changes with the wildcard:
+### Class Decorators
 
+**`@element('tag-name')`** - Define reusable UI components
 ```typescript
-@watch('*')
-handleAnyPropertyChange(_old: any, _new: any, _name: string) {
-  console.log(`Property ${_name} changed from ${_old} to ${_new}`);
-  // Useful for debugging or when all properties affect the same output
-}
+@element('my-button')
+class MyButton extends HTMLElement { }
 ```
 
-## Queries
-
-Query single elements with `@query`:
-
+**`@page({ tag, routes })`** - Define routable pages
 ```typescript
-import { element, query } from 'snice';
-
-@element('my-form')
-class MyForm extends HTMLElement {
-  @query('input')
-  input!: HTMLInputElement;
-
-  html() {
-    return `<input type="text" />`;
-  }
+@page({ tag: 'home-page', routes: ['/'] })
+class HomePage extends HTMLElement { }
+```
 
-  getValue() {
-    return this.input.value;
-  }
+**`@controller('controller-name')`** - Define behavior modules
+```typescript
+@controller('data-loader')
+class DataLoader {
+  async attach(element) { }
+  async detach(element) { }
 }
 ```
 
-Query multiple elements with `@queryAll`:
+### Rendering
 
+**`@render(options?)`** - Define component template (auto re-renders on property changes)
 ```typescript
-import { element, queryAll } from 'snice';
-
-@element('checkbox-group')
-class CheckboxGroup extends HTMLElement {
-  @queryAll('input[type="checkbox"]')
-  checkboxes!: NodeListOf<HTMLInputElement>;
-
-  html() {
-    return `
-      <input type="checkbox" value="option1" />
-      <input type="checkbox" value="option2" />
-      <input type="checkbox" value="option3" />
-    `;
-  }
-
-  getSelectedValues() {
-    return Array.from(this.checkboxes)
-      .filter(cb => cb.checked)
-      .map(cb => cb.value);
-  }
+@render()
+renderContent() {
+  return html`<div>${this.data}</div>`;
 }
 ```
 
-## Events
-
-Listen for events with `@on`:
-
+**`@styles()`** - Define scoped styles
 ```typescript
-import { element, on } from 'snice';
-
-@element('my-clicker')
-class MyClicker extends HTMLElement {
-  html() {
-    return `
-      <button>Click me</button>
-      <input type="text" placeholder="Press Enter" />
-    `;
-  }
-
-  @on('click', 'button')
-  handleClick() {
-    console.log('Button clicked!');
-  }
-
-  @on('keydown:Enter', 'input')  // Only plain Enter (no modifiers)
-  handleEnter() {
-    console.log('Enter pressed!');
-  }
-  
-  @on('keydown:ctrl+Enter', 'input')  // Only Ctrl+Enter
-  handleCtrlEnter() {
-    console.log('Ctrl + Enter pressed!');
-  }
-  
-  @on('focus')  // Listen on the host element itself (no target)
-  handleFocus() {
-    console.log('Element received focus!');
-  }
+@styles()
+componentStyles() {
+  return css`.container { padding: 1rem; }`;
 }
 ```
 
-## Dispatching Events
-
-Automatically dispatch custom events with `@dispatch`:
+### Properties & State
 
+**`@property(options?)`** - Reactive properties that sync with attributes
 ```typescript
-import { element, dispatch, on, query } from 'snice';
+@property()
+name = 'default';
 
-@element('toggle-switch')
-class ToggleSwitch extends HTMLElement {
-  private isOn = false;
-
-  @query('.toggle')
-  toggleButton!: HTMLElement;
+@property({ type: Boolean })
+enabled = false;
+```
 
-  html() {
-    return `<button class="toggle">OFF</button>`;
-  }
-  
-  @on('click', '.toggle')
-  @dispatch('toggled')
-  toggle() {
-    this.isOn = !this.isOn;
-    this.toggleButton.textContent = this.isOn ? 'ON' : 'OFF';
-    return { on: this.isOn };
-  }
+**`@watch(...propertyNames)`** - React to property changes
+```typescript
+@watch('name')
+onNameChange(oldVal, newVal) {
+  console.log(`Name changed from ${oldVal} to ${newVal}`);
 }
 ```
 
-The `@dispatch` decorator:
-- Dispatches after the method completes
-- Uses the return value as the event detail
-- Works with async methods
-- Bubbles by default
+### Lifecycle
 
+**`@ready()`** - Runs after initial render completes
 ```typescript
-// With options from EventInit
-@dispatch('my-event', { bubbles: false, cancelable: true })
-
-// Don't dispatch if method returns undefined
-@dispatch('maybe-data', { dispatchOnUndefined: false })
+@ready()
+async initialize() {
+  // Fetch data, set up listeners, etc.
+}
 ```
 
-## Styling
-
+**`@dispose()`** - Runs when element is removed from DOM
 ```typescript
-@element('styled-card')
-class StyledCard extends HTMLElement {
-  html() {
-    return `<div class="card">Hello</div>`;
-  }
-
-  css() {
-    return `
-      .card {
-        padding: 20px;
-        background: #f0f0f0;
-        border-radius: 8px;
-      }
-    `;
-  }
+@dispose()
+cleanup() {
+  // Clean up listeners, close connections, etc.
 }
 ```
 
-CSS is automatically scoped to your component.
+### DOM Queries
 
-## Routing
+**`@query(selector)`** - Query single element from shadow DOM
+```typescript
+@query('input')
+input!: HTMLInputElement;
+```
 
+**`@queryAll(selector)`** - Query multiple elements from shadow DOM
 ```typescript
-import { Router } from 'snice';
+@queryAll('.item')
+items!: NodeListOf<HTMLElement>;
+```
 
-const router = Router({ target: '#app', type: 'hash' });
+### Events & Communication
 
-const { page, navigate, initialize } = router;
+**Template Events** - Handle events directly in templates (with keyboard modifiers!)
+```typescript
+html`
+  <button @click=${this.handleClick}>Click</button>
+  <input @keydown:Enter=${this.submit} />
+  <input @keydown:ctrl+s=${this.save} />
+`
+```
 
-@page({ tag: 'home-page', routes: ['/'] })
-class HomePage extends HTMLElement {
-  html() {
-    return `<h1>Home</h1>`;
-  }
+**`@on` Decorator** - Event delegation with selectors
+```typescript
+// Works in both elements AND controllers
+@on('click', 'button')  // Event delegation
+handleClick(e: Event) {
+  console.log('Button clicked!');
 }
 
-@page({ tag: 'about-page', routes: ['/about'] })
-class AboutPage extends HTMLElement {
-  html() {
-    return `<h1>About</h1>`;
-  }
+@on('keydown:Enter', 'input')  // Keyboard modifiers
+handleEnter(e: KeyboardEvent) {
+  this.submit();
 }
 
-// Page with URL parameter  
-import { property } from 'snice';
-
-@page({ tag: 'user-page', routes: ['/users/:userId'] })
-class UserPage extends HTMLElement {
-  @property()
-  userId = '';
-  
-  html() {
-    return `<h1>User ${this.userId}</h1>`;
-  }
+@on('input', 'input', { debounce: 300 })  // Debounce support
+handleInput(e: Event) {
+  this.search((e.target as HTMLInputElement).value);
 }
-
-// Start the router
-initialize();
-
-// Navigate programmatically
-navigate('/about');
-navigate('/users/123');  // Sets userId="123" on UserPage
 ```
 
-### Route Guards
-
-Protect routes with guard functions that control access:
-
+**`@dispatch(eventName)`** - Auto-dispatch custom events after method execution
 ```typescript
-import { Router, Guard, RouteParams } from 'snice';
-
-// Create router with context
-const router = Router({
-  target: '#app',
-  type: 'hash',
-  context: new AppContext(),  // Your app's context object
-});
-
-const { page, navigate, initialize } = router;
+@dispatch('value-changed')
+setValue(val: string) {
+  this.value = val;
+  return { value: val };  // Event detail
+}
+```
 
-// Simple guards (params is empty object for non-parameterized routes)
-const isAuthenticated: Guard<AppContext> = (ctx, params) => ctx.getUser() !== null;
-const isAdmin: Guard<AppContext> = (ctx, params) => ctx.getUser()?.role === 'admin';
+### Global State
 
-// Protected page with single guard
-@page({ tag: 'dashboard-page', routes: ['/dashboard'], guards: isAuthenticated })
-class DashboardPage extends HTMLElement {
-  html() {
-    return `<h1>Dashboard</h1>`;
-  }
+**`@context(options?)`** - Receive router context updates (global state)
+```typescript
+// Method decorator that receives context updates
+@context()
+handleContext(ctx: Context) {
+  this.appContext = ctx.application;
+  this.requestRender();
 }
 
-// Admin page with multiple guards (all must pass)
-@page({ tag: 'admin-page', routes: ['/admin'], guards: [isAuthenticated, isAdmin] })
-class AdminPage extends HTMLElement {
-  html() {
-    return `<h1>Admin Panel</h1>`;
-  }
+// With timing options
+@context({ debounce: 300 })
+handleContextDebounced(ctx: Context) {
+  // Called after 300ms of no updates
 }
 
-// Guard that uses route params to check resource-specific permissions
-const canEditUser: Guard<AppContext> = (ctx, params) => {
-  const user = ctx.getUser();
-  if (!user) return false;
-
-  // params.id comes from route '/users/:id/edit'
-  return ctx.hasPermission('users.edit', params.id);
-};
-
-// Guard that checks ownership
-const ownsItem: Guard<AppContext> = (ctx, params) => {
-  const user = ctx.getUser();
-  if (!user) return false;
-  
-  // params.itemId comes from route '/items/:itemId'
-  return user.ownedItems.includes(parseInt(params.itemId));
-};
-
-@page({ tag: 'user-edit', routes: ['/users/:id/edit'], guards: [isAuthenticated, canEditUser] })
-class UserEditPage extends HTMLElement {
-  @property()
-  id = '';  // Automatically set from route param
-  
-  html() {
-    return `<h1>Edit User ${this.id}</h1>`;
-  }
+@context({ throttle: 100 })
+handleContextThrottled(ctx: Context) {
+  // Called at most once per 100ms
 }
 
-@page({ tag: 'item-view', routes: ['/items/:itemId'], guards: [isAuthenticated, ownsItem] })
-class ItemView extends HTMLElement {
-  @property()
-  itemId = '';  // Automatically set from route param
-  
-  html() {
-    return `<h1>Item ${this.itemId}</h1>`;
-  }
+@context({ once: true })
+handleContextOnce(ctx: Context) {
+  // Called only once, then unregisters
 }
+```
 
-// Custom 403 page (optional)
-@page({ tag: 'forbidden-page', routes: ['/403'] })
-class ForbiddenPage extends HTMLElement {
-  html() {
-    return `
-      <h1>Access Denied</h1>
-      <p>You don't have permission to view this page.</p>
-      <a href="#/">Return to home</a>
-    `;
-  }
+**Context Object Structure:**
+```typescript
+interface Context {
+  application: AppContext;  // Your router context
+  navigation: {
+    placards: Placard[];    // Page metadata
+    route: string;          // Current route
+    params: Record<string, string>;  // Route parameters
+  };
+  update(): void;  // Notify all subscribers
 }
-
-initialize();
 ```
 
-When a guard denies access:
-- The 403 page is rendered if defined
-- Otherwise, a default "Unauthorized" message is shown
-- The URL doesn't change (no redirect)
+**Triggering Context Updates:**
 
-## Controllers (Data Fetching)
-
-Controllers handle server communication separately from visual components:
+When you modify the application context, call `update()` to notify all subscribers:
 
 ```typescript
-import { controller, element } from 'snice';
-
-interface IUserElement extends HTMLElement {
-  setUsers(users: any[]): void;
-}
+@page({ tag: 'login-page', routes: ['/login'] })
+class LoginPage extends HTMLElement {
+  private ctx?: Context<AppContext>;
 
-@controller('user-controller')
-class UserController {
-  element!: IUserElement;
-
-  async attach(element: IUserElement) {
-    const response = await fetch('/api/users');
-    const users = await response.json();
-    element.setUsers(users);
+  @context()
+  handleContext(ctx: Context<AppContext>) {
+    this.ctx = ctx;
+    this.requestRender();
   }
 
-  async detach(element: IUserElement) { /* Cleanup */ }
-}
-
-@element('user-list')
-class UserList extends HTMLElement {
-  users: any[] = [];
-
-  html() {
-    return `
-      <ul>
-        ${this.users.map(u => `<li>${u.name}</li>`).join('')}
-      </ul>
-    `;
-  }
+  login(user: User) {
+    // Modify the application context
+    this.ctx!.application.setUser(user);
 
-  setUsers(users: any[]) {
-    this.users = users;
-    if (this.shadowRoot) {
-      this.shadowRoot.innerHTML = this.html();
-    }
+    // Notify all @context subscribers
+    this.ctx!.update();
   }
 }
 ```
 
-Use it:
+**Note:** The router calls `update()` automatically during navigation. Only call it manually when you change application state (like login/logout, theme changes, etc.).
 
-```html
-<user-list controller="user-controller"></user-list>
-```
+### Request/Response
 
-## Request/Response
+For the few cases where elements need to request data from controllers (like fetching user info or current state), Snice provides a request/response pattern:
 
-Bidirectional communication between elements and controllers:
+**`@request(channel)`** - Make requests to controllers from elements
+**`@respond(channel)`** - Respond to requests from elements in controllers
 
-```typescript
-import { element, request, type Response } from 'snice';
+This pattern is useful when:
+- Elements need to fetch data without direct controller access
+- You want to keep elements decoupled from specific controller implementations
+- Multiple elements may request the same data
 
-// Element makes request, controller responds
-@element('user-profile')  
-class UserProfile extends HTMLElement {
+**Example:**
 
-  @request('fetch-user')
-  async *getUser(): Response<{ name: string; email: string }> {
-    const user = await (yield { userId: 123 });
-    return user;
-  }
+```typescript
+// Controller responds to requests
+@element('app-controller')
+class AppController extends HTMLElement {
+  private currentUser = { name: 'Alice', role: 'admin' };
 
-  @ready()
-  async load() {
-    const userData = await this.getUser();
-    this.displayUser(userData);
+  @respond('user')
+  getUserData() {
+    return this.currentUser;
   }
-  
 }
 
-@controller('user-controller')
-class UserController {
+// Element makes requests
+@element('user-badge')
+class UserBadge extends HTMLElement {
+  @request('user')
+  getUser!: () => any;
 
-  @respond('fetch-user')
-  async handleFetchUser(request: { userId: number }) {
-    const response = await fetch(`/api/users/${request.userId}`);
-    return response.json();
+  @ready()
+  init() {
+    const user = this.getUser();
+    console.log('Current user:', user);
   }
 
+  @render()
+  renderContent() {
+    const user = this.getUser();
+    return html`<div>Welcome, ${user.name}!</div>`;
+  }
 }
 ```
 
-## Layouts
+**Usage:**
+```html
+<app-controller>
+  <user-badge></user-badge>
+</app-controller>
+```
+
+See [Request/Response documentation](./docs/request-response.md) for details.
 
-Wrap your pages in shared layout components for consistent navigation, headers, and footers across your application.
+## Template Syntax
 
-### Basic Layout Usage
+### Auto-Rendering with Differential Updates
 
 ```typescript
-import { Router, layout, page } from 'snice';
+@element('counter-display')
+class CounterDisplay extends HTMLElement {
+  @property({ type: Number })
+  count = 0;
 
-// Create a layout component
-@layout('app-shell')
-class AppShell extends HTMLElement {
-  html() {
-    return `
-      <header>
-        <nav>
-          <a href="#/">Home</a>
-          <a href="#/about">About</a>
-        </nav>
-      </header>
-      <main>
-        <slot name="page"></slot>
-      </main>
-      <footer>© 2024 My App</footer>
+  @render()
+  renderContent() {
+    return html`
+      <div class="counter">
+        <span class="count">${this.count}</span>
+        <button @click=${this.increment}>+</button>
+      </div>
     `;
   }
-}
-
-// Configure router with default layout
-const router = Router({
-  target: '#app',
-  type: 'hash',
-  layout: 'app-shell'  // All pages use this layout by default
-});
-
-const { page, initialize } = router;
 
-// Pages automatically render inside the layout
-@page({ tag: 'home-page', routes: ['/'] })
-class HomePage extends HTMLElement {
-  html() {
-    return `<h1>Home Content</h1>`;
+  @styles()
+  counterStyles() {
+    return css`.counter { display: flex; gap: 1rem; }`;
   }
-}
 
-// Override layout per page
-@page({ tag: 'full-page', routes: ['/fullscreen'], layout: false })
-class FullPage extends HTMLElement {
-  html() {
-    return `<div>No layout wrapper</div>`;
+  increment() {
+    this.count++;
+    // Auto re-renders! Only <span class="count"> updates
   }
 }
-
-initialize();
 ```
 
-### Layout Features
+**Key Points:**
+- Properties trigger automatic re-renders
+- Only changed parts update (differential rendering)
+- Event handlers: `@click=${this.method}`
+- Batched updates (multiple changes = single render)
 
-- **Shared wrapper**: Layout components wrap page content using `<slot name="page"></slot>`
-- **Default layouts**: Set `layout: 'component-name'` in router options
-- **Per-page override**: Use `layout: 'other-layout'` or `layout: false` in page options
-- **Smooth transitions**: Layout persists during page transitions for better UX
-- **Nested layouts**: Layouts can contain other layouts for complex structures
+### Property Binding
 
-## Router Context
+Use `.property=${value}` to set element properties directly:
 
-Access router context in page components, nested elements, and controllers using the `@context` decorator.
+```typescript
+html`
+  <input .value=${this.text} />
+  <custom-element .complexData=${this.dataObject}></custom-element>
+`
+```
 
-### ⚠️ Important Warning About Global State
+### Boolean Attributes
 
-**Context is global shared state and should be treated with extreme caution.** Mutating context from multiple components creates hard-to-debug issues, race conditions, and tightly coupled code. This is a serious footgun if used improperly.
+Use `?attribute=${boolean}` for boolean attributes:
 
-**Best practices:**
-- Treat context as **read-only** in components
-- Only mutate context through well-defined methods in the context class
-- Use context for truly global, app-wide state (user auth, theme, locale)
-- For component-specific state, use properties instead
-- Consider the context immutable from the component's perspective
+```typescript
+html`
+  <button ?disabled=${this.isLoading}>Submit</button>
+  <input type="checkbox" ?checked=${this.isChecked} />
+`
+```
 
-### Basic Usage in Pages
+### Conditionals
 
 ```typescript
-// Define your context class with controlled mutations
-class AppContext {
-  private user: User | null = null;
-  
-  // Controlled mutation through methods
-  setUser(user: User) {...}
-  
-  // Read-only access
-  getUser() {...}
-  
-  isAuthenticated() {...}
-}
+// Ternary operator
+html`
+  ${this.isLoggedIn
+    ? html`<span>Welcome!</span>`
+    : html`<a href="/login">Login</a>`
+  }
+`
+
+// <if> conditional element
+html`
+  <if ${this.isLoggedIn}>
+    <span>Welcome, ${this.user.name}!</span>
+    <button @click=${this.logout}>Logout</button>
+  </if>
+  <if ${!this.isLoggedIn}>
+    <a href="/login">Login</a>
+  </if>
+`
+
+// <case>/<when>/<default> for multiple branches
+html`
+  <case ${this.status}>
+    <when value="loading">
+      <span>Loading...</span>
+    </when>
+    <when value="success">
+      <span>Success!</span>
+    </when>
+    <when value="error">
+      <span>Error occurred</span>
+    </when>
+    <default>
+      <span>Unknown status</span>
+    </default>
+  </case>
+`
+```
+
+### Lists
 
-// Create router with context
-const appContext = new AppContext();
-const { page, initialize } = Router({
-  target: '#app',
-  type: 'hash',
-  context: appContext
-});
-
-// Access context in page components
-@page({ tag: 'profile-page', routes: ['/profile'] })
-class ProfilePage extends HTMLElement {
-  @context()
-  ctx?: AppContext;
-  
-  html() {
-    // READ context, don't mutate it directly
-    const user = this.ctx?.getUser();
-    if (!user) {
-      return `<p>Please log in</p>`;
-    }
-    return `
-      <h1>Welcome, ${user.name}!</h1>
-      <p>Email: ${user.email}</p>
-    `;
-  }
-}
+```typescript
+html`
+  <ul>
+    ${this.items.map(item => html`
+      <li @click=${() => this.select(item.id)}>${item.name}</li>
+    `)}
+  </ul>
+`
 ```
 
-### Context in Nested Elements
-
-Nested elements within pages can also access context:
+### Keyboard Shortcuts
 
 ```typescript
-// This element can be used inside any page
-@element('user-avatar')
-class UserAvatar extends HTMLElement {
-  @context()
-  ctx?: AppContext;
-  
-  html() {
-    // Context is available even in nested elements
-    const user = this.ctx?.getUser();
-    return user 
-      ? `<img src="${user.avatar}" alt="${user.name}">`
-      : `<div class="placeholder">?</div>`;
-  }
-}
-
-// Use it in a page
-@page({ tag: 'dashboard', routes: ['/'] })
-class Dashboard extends HTMLElement {
-  html() {
-    return `
-      <h1>Dashboard</h1>
-      <user-avatar></user-avatar>  <!-- Will have access to context -->
-    `;
-  }
-}
+html`
+  <input @keydown.enter=${this.submit} />
+  <input @keydown.ctrl+s=${this.save} />
+  <input @keydown.ctrl+shift+s=${this.saveAs} />
+  <input @keydown.escape=${this.cancel} />
+  <input @keydown.~enter=${this.submitAny} />
+`
 ```
 
-### Context in Controllers
+Keyboard syntax:
+- `@keydown.enter` - Plain Enter (no modifiers)
+- `@keydown.ctrl+s` - Ctrl+S combination
+- `@keydown.~enter` - Enter with any modifiers
+- `@keydown.down` - Arrow keys (up, down, left, right)
+- `@keydown.escape` - Escape key
 
-Controllers attached to page elements automatically acquire context:
+## Router
 
 ```typescript
-@controller('nav-controller')
-class NavController {
-  element!: HTMLElement;
-  
-  @context()
-  ctx?: AppContext;
-  
-  attach(element: HTMLElement) {
-    // Context is available in controllers too
-    if (!this.ctx?.isAuthenticated()) {
-      window.location.hash = '#/login';
-    }
-  }
-  
-  detach(element: HTMLElement) { /* Cleanup */ }
-}
+// main.ts
+const { page, navigate, initialize } = Router({
+  target: '#app',
+  context: new AppContext()
+});
 
-@page({ tag: 'admin-page', routes: ['/admin'] })
-class AdminPage extends HTMLElement {
-  html() {
-    return `<div controller="nav-controller">Admin Panel</div>`;
+// pages/home-page.ts
+@page({ tag: 'home-page', routes: ['/'] })
+class HomePage extends HTMLElement {
+  @render()
+  renderContent() {
+    return html`<h1>Home</h1>`;
   }
 }
-```
 
-The `@context` decorator:
-- Injects the router's context into page components
-- Available to nested elements via event bubbling
-- Available to controllers attached to pages
-- Returns the same context instance everywhere
-- Automatically cleaned up when elements are removed
+// pages/user-page.ts
+@page({ tag: 'user-page', routes: ['/users/:userId'] })
+class UserPage extends HTMLElement {
+  @property()
+  userId = '';  // Auto-populated from URL
+  // ...
+}
 
-**Remember:** With great power comes great responsibility. Global state is dangerous - use it wisely and sparingly.
+// main.ts
+initialize();
+navigate('/users/123');
+```
 
-## Observing External Changes
+### Route Guards
 
-The `@observe` decorator provides lifecycle-managed observation of external changes like viewport intersection, element resize, media queries, and DOM mutations:
+Protect routes with guard functions:
 
 ```typescript
-import { element, observe } from 'snice';
-
-@element('lazy-image')
-class LazyImage extends HTMLElement {
-  html() {
-    return `
-      <img data-src="photo.jpg" class="lazy" />
-      <div class="loading">Loading...</div>
-    `;
-  }
+const isAuthenticated: Guard<AppContext> = (ctx) => ctx.getUser() !== null;
 
-  // Observe when image enters viewport
-  @observe('intersection', '.lazy', { threshold: 0.1 })
-  loadImage(entry: IntersectionObserverEntry) {
-    if (entry.isIntersecting) {
-      const img = entry.target as HTMLImageElement;
-      img.src = img.dataset.src!;
-      img.classList.add('loaded');
-      return false; // Stop observing after loading
-    }
-  }
-
-  // Respond to viewport size changes
-  @observe('media:(min-width: 768px)')
-  handleDesktop(matches: boolean) {
-    this.classList.toggle('desktop-mode', matches);
-  }
-}
+@page({
+  tag: 'dashboard-page',
+  routes: ['/dashboard'],
+  guards: isAuthenticated
+})
+class DashboardPage extends HTMLElement { }
 ```
 
-All observers are automatically cleaned up when elements disconnect from the DOM. See the [Observe API documentation](./docs/observe.md) for more examples.
-
-## Parts - Selective Re-rendering
+## Layouts
 
-For complex components with frequent updates to specific sections, the `@part` decorator enables selective re-rendering of template parts without rebuilding the entire component:
+Layouts wrap pages with shared UI and dynamically build navigation from page metadata:
 
 ```typescript
-import { element, part, property, on } from 'snice';
-
-@element('user-dashboard')
-class UserDashboard extends HTMLElement {
-  @property()
-  user = { name: 'Loading...', stats: { views: 0, likes: 0 } };
-  
-  notifications = [];
-  messages = [];
-
-  html() {
-    return `
-      <header part="user-info"></header>
-      <main>
-        <section part="stats"></section>
-        <aside part="notifications"></aside>
-        <div part="messages"></div>
-      </main>
-    `;
-  }
-
-  @part('user-info')
-  renderUserInfo() {
-    return `
-      <h1>${this.user.name}</h1>
-      <button id="refresh-user">Refresh</button>
-    `;
-  }
-
-  @part('stats')
-  renderStats() {
-    return `
-      <div class="stats">
-        <span>Views: ${this.user.stats.views}</span>
-        <span>Likes: ${this.user.stats.likes}</span>
-      </div>
-    `;
-  }
+// layouts/app-shell.ts
+@layout('app-shell')
+class AppShell extends HTMLElement implements Layout {
+  private placards: Placard[] = [];
+  private currentRoute = '';
 
-  @part('notifications', { throttle: 300 })
-  renderNotifications() {
-    return `
-      <h3>Notifications (${this.notifications.length})</h3>
-      ${this.notifications.map(n => `<div>${n}</div>`).join('')}
+  @render()
+  renderContent() {
+    return html`
+      <header>
+        <nav>
+          ${this.placards
+            .filter(p => p.show !== false)
+            .map(p => html`
+              <a href="#/${p.name}"
+                 class="${this.currentRoute === p.name ? 'active' : ''}">
+                ${p.icon} ${p.title}
+              </a>
+            `)}
+        </nav>
+      </header>
+      <main><slot name="page"></slot></main>
     `;
   }
 
-  @part('messages')
-  async renderMessages() {
-    if (this.messages.length === 0) {
-      return '<p>No messages</p>';
-    }
-    return this.messages.map(m => `<div class="message">${m}</div>`).join('');
-  }
-
-  // Update specific parts without re-rendering everything
-  updateUserName(newName) {
-    this.user.name = newName;
-    this.renderUserInfo(); // Only re-renders the header
-  }
-
-  incrementViews() {
-    this.user.stats.views++;
-    this.renderStats(); // Only re-renders the stats section
-  }
-
-  addNotification(notification) {
-    this.notifications.unshift(notification);
-    this.renderNotifications(); // Only re-renders notifications
-  }
-
-  @on('click', '#refresh-user')
-  async handleRefreshUser() {
-    // Simulate API call
-    const userData = await this.fetchUserData();
-    this.user = userData;
-    this.renderUserInfo(); // Update just the user info part
-    this.renderStats();    // Update just the stats part
+  // Called when route changes
+  update(appContext, placards, currentRoute, routeParams) {
+    this.placards = placards;
+    this.currentRoute = currentRoute;
+    // Property changes trigger re-render
   }
 }
-```
-
-**Benefits of `@part`:**
-- **Performance** - Update only what changed instead of re-rendering entire templates
-- **Granular Control** - Target specific sections for updates
-- **Complex UIs** - Perfect for dashboards, lists, or components with independent sections
-- **Async Support** - Part methods can be async for data fetching
-- **Throttle/Debounce** - Control render frequency to optimize performance
-
-### Performance Options
 
-The `@part` decorator supports throttle and debounce options to optimize render performance:
-
-```typescript
-// Throttle: Limit renders to once per 300ms
-@part('notifications', { throttle: 300 })
-renderNotifications() { /* ... */ }
-
-// Debounce: Delay render until 150ms after last call
-@part('search-results', { debounce: 150 })
-renderSearchResults() { /* ... */ }
+// main.ts - configure router with layout
+const { page, initialize } = Router({
+  target: '#app',
+  layout: 'app-shell'
+});
 ```
 
-- **Throttle** - Limits renders to a maximum frequency (e.g., once every 300ms)
-- **Debounce** - Delays renders until after calls stop for the specified time
-
-The `@part` decorator is ideal when you have components with multiple independent sections that update at different frequencies or from different data sources.
-
-## Lifecycle Callbacks
+Pages render inside `<slot name="page"></slot>`. Layout persists, only page content swaps.
 
-Snice provides decorators for advanced DOM lifecycle events that go beyond basic connected/disconnected callbacks:
+## Placards
 
-### @moved Decorator
-
-The `@moved` decorator runs methods when an element is moved within the DOM using `Element.moveBefore()`. This is useful for handling position changes without full disconnection/reconnection:
+Page metadata that layouts use to build navigation, breadcrumbs, and help systems:
 
 ```typescript
-@element('my-element')
-class MyElement extends HTMLElement {
-  @moved()
-  onElementMoved() {
-    console.log('Element moved to new position');
-    this.updatePosition();
-  }
-
-  // With timing options
-  @moved({ debounce: 100 })
-  onMovedDebounced() {
-    // Only called once after moves stop for 100ms
-    this.recalculateLayout();
-  }
+// pages/dashboard-page.ts
+const placard: Placard<AppContext> = {
+  name: 'dashboard',
+  title: 'Dashboard',
+  icon: '📊',
+  order: 1,
+  searchTerms: ['home', 'overview', 'stats'],
+  hotkeys: ['ctrl+d'],
+  visibleOn: [isAuthenticated]
+};
 
-  @moved({ throttle: 500 })
-  onMovedThrottled() {
-    // Called at most once every 500ms during rapid moves
-    this.optimizePerformance();
-  }
-}
+@page({
+  tag: 'dashboard-page',
+  routes: ['/dashboard'],
+  placard: placard
+})
+class DashboardPage extends HTMLElement { }
 ```
 
-### @adopted Decorator
+**Features:**
+- **Navigation** - `title`, `icon`, `order`, `show`
+- **Hierarchy** - `parent`, `group`, `breadcrumbs`
+- **Discovery** - `searchTerms`, `hotkeys`, `tooltip`
+- **Visibility** - `visibleOn` guards control who sees what
 
-The `@adopted` decorator runs methods when an element is moved to a new document (like iframes or document fragments):
+Layouts receive placard data in `update()` and auto-build navigation. See [docs](./docs/placards.md).
 
-```typescript
-@element('portable-element')
-class PortableElement extends HTMLElement {
-  @adopted()
-  onAdoptedToNewDocument() {
-    console.log('Element moved to new document');
-    this.updateDocumentReferences();
-  }
+## Migrating from v2.x
 
-  // With timing options
-  @adopted({ debounce: 200 })
-  onAdoptedDebounced() {
-    // Debounced for performance during rapid document moves
-    this.reinitializeForNewContext();
-  }
-}
-```
+v3.0.0 introduces template-based rendering with differential updates. Key changes:
 
-### Timing Options
+- **Use `@render()` instead of `html()` method**
+  Return `html\`...\`` tagged template instead of string
 
-Both decorators support the same timing options as `@part`:
+- **Use `@styles()` instead of `css()` method**
+  Return `css\`...\`` tagged template instead of string
 
-- **`debounce`** - Delays execution until after calls stop for the specified milliseconds
-- **`throttle`** - Limits execution to once per specified milliseconds
+- **`@on()` decorator available**
+  Works in both elements AND controllers with full event delegation, keyboard modifiers, and debounce/throttle support.
+  Template event syntax (`@click=${handler}`) is also available as an alternative.
 
-```typescript
-// Examples of timing control
-@moved({ debounce: 150 })    // Wait 150ms after moves stop
-@adopted({ throttle: 300 })  // Maximum once per 300ms
-```
+- **`@part` decorator removed**
+  Differential rendering makes selective re-rendering unnecessary
 
-These lifecycle callbacks are perfect for:
-- **Performance optimization** during rapid DOM changes
-- **Layout recalculation** when elements move
-- **Context updates** when elements move between documents
-- **Resource cleanup/setup** during document adoption
+See [Migration Guide](./docs/migration-v2-to-v3.md) for detailed migration guide.
 
 ## Documentation
 
 - [Elements API](./docs/elements.md) - Complete guide to creating elements with properties, queries, and styling
 - [Controllers API](./docs/controllers.md) - Data fetching, business logic, and controller patterns
+- [Routing API](./docs/routing.md) - Single-page application routing with transitions
+- [Placards API](./docs/placards.md) - Rich page metadata for dynamic navigation and discovery
 - [Events API](./docs/events.md) - Event handling, dispatching, and custom events
 - [Request/Response API](./docs/request-response.md) - Bidirectional communication between elements and controllers
-- [Routing API](./docs/routing.md) - Single-page application routing with transitions
 - [Observe API](./docs/observe.md) - Lifecycle-managed observers for external changes
 
 ## License