snice 2.5.4 → 3.1.0

package/README.md

@@ -1,10 +1,10 @@
-# Snice
+# Snice v3.0.0
 
-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,720 @@ cd my-app
 npm run dev
 ```
 
-## Core Philosophy: Imperative, Not Reactive
+## Philosophy: Sustainable Architecture Through Separation of Concerns
 
-Snice takes an **imperative approach** to web components. Unlike reactive frameworks that automatically re-render when data changes, Snice components:
+Most frameworks separate code by technology: HTML, CSS, JavaScript. Snice separates by **concerns of governance and data flow**. This shepherds you toward sustainable development by providing tools that encourage good practices.
 
-- **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
+### The Snice Architecture
 
-This approach gives you direct control over DOM updates without hidden complexity or automatic re-renders.
+Every application has four distinct concerns:
 
-## The Snice Way: Elements + Controllers
+**1. Cross-Cutting Concerns** - Global state and navigation
+- Authentication/principal
+- Theming and preferences
+- Routing and navigation
+- Application-wide configuration
 
-Snice separates UI from data: **elements handle UI, controllers handle behavior and data**.
+**2. Pages** - Code that handles human intent
+- Understand what the user is trying to accomplish
+- Orchestrate atomic elements to fulfill that intent
+- Handle page-level data fetching and coordination
+- Map URL parameters to user goals
 
-```typescript
-import { element, controller, property, query } from 'snice';
+**3. Elements** - Pure presentation
+- Display data, nothing more
+- No understanding of business logic or user intent
+- Completely reusable across different contexts
+- Concerned only with how things look and visual behaviors
 
-export interface IUserCard extends HTMLElement {
-  userId: string;
-  showUser(user: any): void;
-}
+**4. Controllers** - Behavior and data management
+- Handle server communication and data fetching when applicable
+- Manage complex business logic when pages get too large
+- Enable behavior swapping (A/B testing, feature flags)
+- Clear separation of presentation from behavior
 
-// 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;
-  }
-}
+This architecture ensures **pages orchestrate**, **elements present**, and **controllers behave**. Data flows down, events flow up, and every piece knows only what it needs to know.
 
-// 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 */ }
-}
-```
+## Why This Matters
 
-Connect them in HTML:
-```html
-<user-card user-id="123" controller="user-loader"></user-card>
-```
+Traditional component architectures blur these lines. A "UserProfile" component might handle routing, authentication, API calls, and rendering. When requirements change, you can't swap behavior without touching presentation. When you need to reuse the UI, you can't because it's coupled to specific business logic.
 
-That's it. Element renders UI, controller fetches data, they communicate through method calls, events, and request/response channels.
+Snice encourages boundaries:
+- Want different behavior? Swap the controller, keep the element
+- Need to reuse UI? Elements don't know about your business logic
+- Debugging data flow? Follow the clear page → element → controller boundaries
+- Onboarding new developers? The architecture guides them to the right place
 
-## Core Concepts
+## The Tools
 
-Snice provides a clear separation of concerns through decorators:
+Snice provides decorators and utilities that map directly to these architectural concerns:
 
-### 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
+// 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
+});
 
-```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;
+    cost user = this.getUser();
   }
+  // ...
 }
 ```
 
-That's it. Your component renders when added to the DOM:
+### 2. Pages: Orchestrating Intent
 
-```html
-<my-button></my-button>
-```
-
-## 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));
+    };
+  }
+  // ...
+}
+
+// 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));
+  }
+  // ...
+}
 
-@element('tag-list')
-class TagList extends HTMLElement {
-  @property({ type: SimpleArray })
-  tags = ['javascript', 'typescript', 'web'];
+// 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, small bundle size
 
-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" />`;
-  }
-
-  getValue() {
-    return this.input.value;
-  }
-}
+@page({ tag: 'home-page', routes: ['/'] })
+class HomePage extends HTMLElement { }
 ```
 
-Query multiple elements with `@queryAll`:
-
+**`@controller('controller-name')`** - Define behavior modules
 ```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);
-  }
+@controller('data-loader')
+class DataLoader {
+  async attach(element) { }
+  async detach(element) { }
 }
 ```
 
-## Events
-
-Listen for events with `@on`:
+### Rendering
 
+**`@render(options?)`** - Define component template (auto re-renders on property changes)
 ```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!');
-  }
+@render()
+renderContent() {
+  return html`<div>${this.data}</div>`;
 }
 ```
 
-## Dispatching Events
-
-Automatically dispatch custom events with `@dispatch`:
-
+**`@styles()`** - Define scoped styles
 ```typescript
-import { element, dispatch, on, query } from 'snice';
-
-@element('toggle-switch')
-class ToggleSwitch extends HTMLElement {
-  private isOn = false;
-
-  @query('.toggle')
-  toggleButton!: HTMLElement;
-
-  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 };
-  }
+@styles()
+componentStyles() {
+  return css`.container { padding: 1rem; }`;
 }
 ```
 
-The `@dispatch` decorator:
-- Dispatches after the method completes
-- Uses the return value as the event detail
-- Works with async methods
-- Bubbles by default
+### Properties & State
 
+**`@property(options?)`** - Reactive properties that sync with attributes
 ```typescript
-// With options from EventInit
-@dispatch('my-event', { bubbles: false, cancelable: true })
+@property()
+name = 'default';
 
-// Don't dispatch if method returns undefined
-@dispatch('maybe-data', { dispatchOnUndefined: false })
+@property({ type: Boolean })
+enabled = false;
 ```
 
-## Styling
-
+**`@watch(...propertyNames)`** - React to property changes
 ```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;
-      }
-    `;
-  }
+@watch('name')
+onNameChange(oldVal, newVal) {
+  console.log(`Name changed from ${oldVal} to ${newVal}`);
 }
 ```
 
-CSS is automatically scoped to your component.
-
-## Routing
+### Lifecycle
 
+**`@ready()`** - Runs after initial render completes
 ```typescript
-import { Router } from 'snice';
-
-const router = Router({ target: '#app', type: 'hash' });
-
-const { page, navigate, initialize } = router;
-
-@page({ tag: 'home-page', routes: ['/'] })
-class HomePage extends HTMLElement {
-  html() {
-    return `<h1>Home</h1>`;
-  }
+@ready()
+async initialize() {
+  // Fetch data, set up listeners, etc.
 }
+```
 
-@page({ tag: 'about-page', routes: ['/about'] })
-class AboutPage extends HTMLElement {
-  html() {
-    return `<h1>About</h1>`;
-  }
-}
-
-// 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>`;
-  }
+**`@dispose()`** - Runs when element is removed from DOM
+```typescript
+@dispose()
+cleanup() {
+  // Clean up listeners, close connections, etc.
 }
-
-// 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:
+### DOM Queries
 
+**`@query(selector)`** - Query single element from shadow DOM
 ```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
-});
+@query('input')
+input!: HTMLInputElement;
+```
 
-const { page, navigate, initialize } = router;
+**`@queryAll(selector)`** - Query multiple elements from shadow DOM
+```typescript
+@queryAll('.item')
+items!: NodeListOf<HTMLElement>;
+```
 
-// 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';
+### Events & Communication
 
-// Protected page with single guard
-@page({ tag: 'dashboard-page', routes: ['/dashboard'], guards: isAuthenticated })
-class DashboardPage extends HTMLElement {
-  html() {
-    return `<h1>Dashboard</h1>`;
-  }
-}
+**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} />
+`
+```
 
-// 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>`;
-  }
+**`@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!');
 }
 
-// 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>`;
-  }
+@on('keydown:Enter', 'input')  // Keyboard modifiers
+handleEnter(e: KeyboardEvent) {
+  this.submit();
 }
 
-@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>`;
-  }
+@on('input', 'input', { debounce: 300 })  // Debounce support
+handleInput(e: Event) {
+  this.search((e.target as HTMLInputElement).value);
 }
+```
 
-// 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>
-    `;
-  }
+**`@dispatch(eventName)`** - Auto-dispatch custom events after method execution
+```typescript
+@dispatch('value-changed')
+setValue(val: string) {
+  this.value = val;
+  return { value: val };  // Event detail
 }
-
-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)
-
-## Controllers (Data Fetching)
-
-Controllers handle server communication separately from visual components:
+### Global State
 
+**`@context(options?)`** - Receive router context updates (global state)
 ```typescript
-import { controller, element } from 'snice';
-
-interface IUserElement extends HTMLElement {
-  setUsers(users: any[]): void;
+// Method decorator that receives context updates
+@context()
+handleContext(ctx: Context) {
+  this.appContext = ctx.application;
+  this.requestRender();
 }
 
-@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);
-  }
-
-  async detach(element: IUserElement) { /* Cleanup */ }
+// With timing options
+@context({ debounce: 300 })
+handleContextDebounced(ctx: Context) {
+  // Called after 300ms of no updates
 }
 
-@element('user-list')
-class UserList extends HTMLElement {
-  users: any[] = [];
-
-  html() {
-    return `
-      <ul>
-        ${this.users.map(u => `<li>${u.name}</li>`).join('')}
-      </ul>
-    `;
-  }
+@context({ throttle: 100 })
+handleContextThrottled(ctx: Context) {
+  // Called at most once per 100ms
+}
 
-  setUsers(users: any[]) {
-    this.users = users;
-    if (this.shadowRoot) {
-      this.shadowRoot.innerHTML = this.html();
-    }
-  }
+@context({ once: true })
+handleContextOnce(ctx: Context) {
+  // Called only once, then unregisters
 }
 ```
 
-Use it:
-
-```html
-<user-list controller="user-controller"></user-list>
+**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
+}
 ```
 
-## Request/Response
+**Triggering Context Updates:**
 
-Bidirectional communication between elements and controllers:
+When you modify the application context, call `update()` to notify all subscribers:
 
 ```typescript
-import { element, request, type Response } from 'snice';
+@page({ tag: 'login-page', routes: ['/login'] })
+class LoginPage extends HTMLElement {
+  private ctx?: Context<AppContext>;
 
-// Element makes request, controller responds
-@element('user-profile')  
-class UserProfile extends HTMLElement {
-
-  @request('fetch-user')
-  async *getUser(): Response<{ name: string; email: string }> {
-    const user = await (yield { userId: 123 });
-    return user;
+  @context()
+  handleContext(ctx: Context<AppContext>) {
+    this.ctx = ctx;
+    this.requestRender();
   }
 
-  @ready()
-  async load() {
-    const userData = await this.getUser();
-    this.displayUser(userData);
+  login(user: User) {
+    // Modify the application context
+    this.ctx!.application.setUser(user);
+
+    // Notify all @context subscribers
+    this.ctx!.update();
   }
-  
 }
+```
 
-@controller('user-controller')
-class UserController {
+**Note:** The router calls `update()` automatically during navigation. Only call it manually when you change application state (like login/logout, theme changes, etc.).
 
-  @respond('fetch-user')
-  async handleFetchUser(request: { userId: number }) {
-    const response = await fetch(`/api/users/${request.userId}`);
-    return response.json();
-  }
+### Request/Response
 
-}
-```
+**`@request(channel)`** - Make requests to controllers
+**`@respond(channel)`** - Respond to requests from elements
 
-## Layouts
+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() {...}
-}
-
-// Create router with context
-const appContext = new AppContext();
-const { page, initialize } = Router({
-  target: '#app',
-  type: 'hash',
-  context: appContext
-});
+// 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
 
-// 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>
-    `;
-  }
-
-  // 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
-    }
-  }
+const isAuthenticated: Guard<AppContext> = (ctx) => ctx.getUser() !== null;
 
-  // 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